KofTwentyTwo/license-tool
2
0 Fork 0
Code Issues 2 Pull Requests 9 Actions Packages Projects Releases 6 Wiki Activity

init: redesign as full TUI configuration wizard with live source preview #29

New Issue
Closed
opened 2026-06-04 21:22:25 +00:00 by KofTwentyTwo · 4 comments
KofTwentyTwo commented 2026-06-04 21:22:25 +00:00 (Migrated from github.com)
Copy link
Copy source

Problem

The current license-tool init wizard is too terse for the decisions it asks users to make. It asks for SPDX license, copyright holder, year policy, header style, and LICENSE-file management without enough context, preview, or explanation of downstream behavior.

Product Direction

init should be the primary configuration wizard, not a license-selection advisor. It should guide users through configuring .license-tool.yaml, explain implications lightly, avoid legal advice, and show a live preview of what the chosen configuration does to an example source file.

Agreed Design Decisions

  • Replace the current linear huh form with a full TUI.
  • The TUI should default to a live example source-file preview with the selected header applied.
  • Config preview should still be available as a secondary view or tab.
  • The wizard should start with project licensing model, not raw SPDX ID:
    • Open source project
    • Private/internal project
    • Existing project, detect what is already here
    • Advanced/manual configuration
  • For open source projects, show SPDX licenses with common licenses first and a full searchable list available.
  • Support private/internal/proprietary licensing paths.
  • Explain fields in product terms:
    • Copyright holder
    • Year policy
    • Header style
    • LICENSE file management
    • Include/exclude coverage
  • Add include/exclude configuration to the wizard.
  • Add CLI support and persisted config support for includes if needed. --include and --exclude exist today as global runtime flags, but only exclude is currently persisted in .license-tool.yaml.

Example Source Preview

The preview should use an example file by default, not a real repo file.

Include examples for the 15 most popular/common languages supported by the tool. If the repo detects one of those language families, choose that example deterministically. If none are detected, default to a C source file.

Proposed sample priority can be finalized during implementation, but should include representative examples such as:

  • JavaScript / TypeScript
  • Python
  • Java
  • Go
  • C
  • C++
  • C#
  • PHP
  • Ruby
  • Swift
  • Kotlin
  • Rust
  • Shell
  • PowerShell
  • R

Each sample should demonstrate the correct comment style and preserve-first behavior where relevant.

Acceptance Criteria

  • license-tool init presents a full-screen TUI when interactive.
  • The right-side/default preview shows a selected example source file with the generated header applied.
  • The preview updates as license, holder, year, style, and include/exclude choices change.
  • The user can view the generated .license-tool.yaml before writing.
  • The user can configure default include and exclude coverage from the wizard.
  • CLI flags support the same persisted include/exclude settings, not only runtime filtering.
  • The final review screen clearly states which files will be written, including .license-tool.yaml, LICENSE, and LICENSES/<id>.txt when applicable.
  • Non-TTY behavior remains deterministic and script-friendly.
  • Test coverage remains at the configured 100% gate.
## Problem The current `license-tool init` wizard is too terse for the decisions it asks users to make. It asks for SPDX license, copyright holder, year policy, header style, and LICENSE-file management without enough context, preview, or explanation of downstream behavior. ## Product Direction `init` should be the primary configuration wizard, not a license-selection advisor. It should guide users through configuring `.license-tool.yaml`, explain implications lightly, avoid legal advice, and show a live preview of what the chosen configuration does to an example source file. ## Agreed Design Decisions - Replace the current linear `huh` form with a full TUI. - The TUI should default to a live example source-file preview with the selected header applied. - Config preview should still be available as a secondary view or tab. - The wizard should start with project licensing model, not raw SPDX ID: - Open source project - Private/internal project - Existing project, detect what is already here - Advanced/manual configuration - For open source projects, show SPDX licenses with common licenses first and a full searchable list available. - Support private/internal/proprietary licensing paths. - Explain fields in product terms: - Copyright holder - Year policy - Header style - LICENSE file management - Include/exclude coverage - Add include/exclude configuration to the wizard. - Add CLI support and persisted config support for includes if needed. `--include` and `--exclude` exist today as global runtime flags, but only `exclude` is currently persisted in `.license-tool.yaml`. ## Example Source Preview The preview should use an example file by default, not a real repo file. Include examples for the 15 most popular/common languages supported by the tool. If the repo detects one of those language families, choose that example deterministically. If none are detected, default to a C source file. Proposed sample priority can be finalized during implementation, but should include representative examples such as: - JavaScript / TypeScript - Python - Java - Go - C - C++ - C# - PHP - Ruby - Swift - Kotlin - Rust - Shell - PowerShell - R Each sample should demonstrate the correct comment style and preserve-first behavior where relevant. ## Acceptance Criteria - `license-tool init` presents a full-screen TUI when interactive. - The right-side/default preview shows a selected example source file with the generated header applied. - The preview updates as license, holder, year, style, and include/exclude choices change. - The user can view the generated `.license-tool.yaml` before writing. - The user can configure default include and exclude coverage from the wizard. - CLI flags support the same persisted include/exclude settings, not only runtime filtering. - The final review screen clearly states which files will be written, including `.license-tool.yaml`, `LICENSE`, and `LICENSES/<id>.txt` when applicable. - Non-TTY behavior remains deterministic and script-friendly. - Test coverage remains at the configured 100% gate.
KofTwentyTwo commented 2026-06-04 21:28:28 +00:00 (Migrated from github.com)
Copy link
Copy source

Implementation Plan

Design-mode output has been turned into the implementation plan for this feature.

MVP Scope

  • Full-screen interactive init TUI.
  • init remains the primary configuration wizard, not legal advice.
  • Live source-file preview is the default preview.
  • Config/YAML preview is available before writing.
  • Include/exclude coverage can be configured from the wizard.
  • Persisted include config support is added alongside existing exclude support.
  • Example source catalog covers 15 language families and falls back to C when none are detected.
  • Non-TTY init remains deterministic and script-friendly.
  • 100% configured coverage gate remains required.

Implementation Slices

  1. Config/include persistence and command integration.
  2. Sample catalog, language detection, and preview rendering engine.
  3. Full-screen Bubble Tea TUI shell and init command wiring.

Deferred Beyond MVP

  • Legal-advice-style license recommendation.
  • Deep existing-project inference beyond safe detected defaults.
  • Custom proprietary license text generation.
  • Network SPDX refresh.
  • Custom filetype editing inside the first TUI pass.
## Implementation Plan Design-mode output has been turned into the implementation plan for this feature. ### MVP Scope - Full-screen interactive `init` TUI. - `init` remains the primary configuration wizard, not legal advice. - Live source-file preview is the default preview. - Config/YAML preview is available before writing. - Include/exclude coverage can be configured from the wizard. - Persisted `include` config support is added alongside existing `exclude` support. - Example source catalog covers 15 language families and falls back to C when none are detected. - Non-TTY `init` remains deterministic and script-friendly. - 100% configured coverage gate remains required. ### Implementation Slices 1. Config/include persistence and command integration. 2. Sample catalog, language detection, and preview rendering engine. 3. Full-screen Bubble Tea TUI shell and `init` command wiring. ### Deferred Beyond MVP - Legal-advice-style license recommendation. - Deep existing-project inference beyond safe detected defaults. - Custom proprietary license text generation. - Network SPDX refresh. - Custom filetype editing inside the first TUI pass.
KofTwentyTwo commented 2026-06-04 21:46:13 +00:00 (Migrated from github.com)
Copy link
Copy source

Implementation status for feature/GH-29-init-tui-wizard:

Completed:

  • Replaced the interactive init collector with a Bubble Tea TUI shell using a progress rail, active control panel, and live preview panel.
  • Added source preview catalog coverage for 15 language families with C fallback.
  • Wired live preview rendering through the pure internal/initwizard preview helpers.
  • Added persisted include config support and preserved include values from CLI flags, collector answers, config loading, init output, audit, apply, and license paths.
  • Preserved deterministic non-interactive init behavior.
  • Updated README, DEVELOPERS, changelog, plan, todo, session state, and coverage rationale docs.

Local verification is green:

  • gofmt -l .: clean
  • go vet ./...: pass
  • golangci-lint run: 0 issues
  • race-enabled full test suite with coverage profile: pass
  • configured coverage gate: PASS, 100% (2136/2136)
  • go build ./...: pass

A smoke test wrote .license-tool.yaml with expected include and exclude values. A temporary test binary is available at /private/tmp/license-tool-gh29 for manual TUI review.

Implementation status for `feature/GH-29-init-tui-wizard`: Completed: - Replaced the interactive init collector with a Bubble Tea TUI shell using a progress rail, active control panel, and live preview panel. - Added source preview catalog coverage for 15 language families with C fallback. - Wired live preview rendering through the pure `internal/initwizard` preview helpers. - Added persisted `include` config support and preserved include values from CLI flags, collector answers, config loading, init output, audit, apply, and license paths. - Preserved deterministic non-interactive init behavior. - Updated README, DEVELOPERS, changelog, plan, todo, session state, and coverage rationale docs. Local verification is green: - `gofmt -l .`: clean - `go vet ./...`: pass - `golangci-lint run`: 0 issues - race-enabled full test suite with coverage profile: pass - configured coverage gate: PASS, 100% (2136/2136) - `go build ./...`: pass A smoke test wrote `.license-tool.yaml` with expected include and exclude values. A temporary test binary is available at `/private/tmp/license-tool-gh29` for manual TUI review.
KofTwentyTwo commented 2026-06-04 22:02:53 +00:00 (Migrated from github.com)
Copy link
Copy source

Follow-up after manual TUI feedback:

Refined the interactive shell from a plain string renderer into a pane-based Bubble Tea/Lip Gloss TUI:

  • Bordered windows for steps, active controls, and live preview.
  • Narrow-terminal layout now fits in an 80x24 PTY without losing the header or navigation.
  • License selection is a bounded table instead of an unbounded dump.
  • License picker supports type-to-filter, backspace filter editing, ctrl+u clear, home/end, and page up/down.
  • Review renders as an aligned table.
  • Preview content is clipped to the pane height so it cannot flood the screen.

Rebuilt /private/tmp/license-tool-gh29 and verified the first screen plus license filter behavior in a PTY. Final local gate remains green:

  • gofmt -l .: clean
  • go vet ./...: pass
  • golangci-lint run: 0 issues
  • go test ./...: pass
  • race-enabled coverage profile: pass
  • configured coverage gate: PASS, 100% (2136/2136)
  • go build ./...: pass
Follow-up after manual TUI feedback: Refined the interactive shell from a plain string renderer into a pane-based Bubble Tea/Lip Gloss TUI: - Bordered windows for steps, active controls, and live preview. - Narrow-terminal layout now fits in an 80x24 PTY without losing the header or navigation. - License selection is a bounded table instead of an unbounded dump. - License picker supports type-to-filter, backspace filter editing, ctrl+u clear, home/end, and page up/down. - Review renders as an aligned table. - Preview content is clipped to the pane height so it cannot flood the screen. Rebuilt `/private/tmp/license-tool-gh29` and verified the first screen plus license filter behavior in a PTY. Final local gate remains green: - `gofmt -l .`: clean - `go vet ./...`: pass - `golangci-lint run`: 0 issues - `go test ./...`: pass - race-enabled coverage profile: pass - configured coverage gate: PASS, 100% (2136/2136) - `go build ./...`: pass
KofTwentyTwo commented 2026-06-08 14:28:38 +00:00 (Migrated from github.com)
Copy link
Copy source

Pushed handoff branch feature/GH-29-init-tui-wizard at commit 44d4986 (feat(init): add pane-based TUI wizard). Local gate passed before push: gofmt clean, go vet, golangci-lint via v2 go run fallback, normal tests, race coverage, 100% coverage gate, and go build. Note: the generated root .license-tool.yaml from manual TUI testing was intentionally left untracked because it contained a typo in the holder value and was not part of the implementation.

Pushed handoff branch `feature/GH-29-init-tui-wizard` at commit `44d4986` (`feat(init): add pane-based TUI wizard`). Local gate passed before push: gofmt clean, go vet, golangci-lint via v2 go run fallback, normal tests, race coverage, 100% coverage gate, and go build. Note: the generated root `.license-tool.yaml` from manual TUI testing was intentionally left untracked because it contained a typo in the holder value and was not part of the implementation.
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
bug
Something isn't working
 dependencies
Pull requests that update a dependency file
 documentation
Improvements or additions to documentation
 duplicate
This issue or pull request already exists
 enhancement
New feature or request
 github_actions
Pull requests that update GitHub Actions code
 go
Pull requests that update go code
 good first issue
Good for newcomers
 help wanted
Extra attention is needed
 invalid
This doesn't seem right
 question
Further information is requested
 wontfix
This will not be worked on
No labels documentation enhancement
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
forge-recovery (Forge Recovery) james.maes (James Maes)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: KofTwentyTwo/license-tool#29