@guiho/runx 0.2.6 → 0.4.0

package/docs/decisions/interactive-init-manifest.md

@@ -0,0 +1,187 @@
+---
+name: RunX Interactive Init Manifest
+purpose: Preserve the accepted manifest structure and initialization behavior for runx init.
+description: Defines the Semantic Versioning manifest field, mandatory public group, configurable scripts directory, and empty interactive initialization contract.
+created: 2026-07-14
+flags:
+  - accepted
+  - decision
+tags:
+  - decisions
+  - cli
+  - manifest
+keywords:
+  - runx init
+  - runx.yaml
+  - semantic versioning
+  - public group
+  - scripts directory
+owner: runx-decisions
+---
+
+# RunX Interactive Init Manifest
+
+## Status
+
+Accepted by the project owner on 2026-07-14.
+
+## Context
+
+RunX needs an interactive `runx init` command so a project can establish its
+single `runx.yaml` command catalog before any commands exist. The repository
+already defines groups and documented commands as the core catalog model. The
+initializer must preserve that model without inventing framework-specific
+commands, creating a second configuration file, or forcing a placeholder
+command into the catalog.
+
+Projects may later store executable Bash, PowerShell, or other script files in
+a manifest-owned scripts directory. The manifest must identify that directory
+so agents and developers use one predictable location when adding scripts.
+
+## Decision
+
+### Initialized manifest
+
+`runx init` creates this shape, using the current directory name as the default
+project name:
+
+```yaml
+version: "1.0.0"
+
+project:
+  name: my-project
+
+scripts:
+  directory: scripts
+
+groups:
+  public:
+    summary: Default public project commands.
+
+commands: []
+```
+
+The initializer creates only `runx.yaml`. It does not create an empty `scripts`
+directory because the directory is created when the first script is written.
+
+### Manifest version
+
+- `version` is a valid Semantic Versioning 2.0.0 string with a
+  `MAJOR.MINOR.PATCH` core and optional prerelease or build metadata.
+- The first supported manifest contract is `"1.0.0"`.
+- RunX accepts manifest versions whose major version is `1` and rejects
+  unsupported major versions.
+- Numeric `version: 1` manifests are invalid. RunX is still under development
+  and has no deployed numeric-version compatibility requirement.
+- Future backward-incompatible manifest changes require a major version change.
+
+### Scripts directory
+
+- Every manifest contains `scripts.directory`; it configures the project script
+  location.
+- The initializer's default value is `scripts` relative to the directory
+  containing `runx.yaml`.
+- The path must remain inside the manifest directory and cannot escape through
+  an absolute path or parent traversal.
+- Existing and future command strings may invoke any suitable script type from
+  this directory; RunX remains language-agnostic.
+- The manifest command entry is the script descriptor. No sidecar RunX config
+  or per-script descriptor file is introduced.
+
+### Groups and commands
+
+- `groups` is a first-class catalog concept.
+- Every manifest contains a `public` group, analogous to PostgreSQL's default
+  `public` schema.
+- Additional groups may organize commands by domain or responsibility.
+- Every command explicitly names an existing group. Missing and unknown group
+  references are invalid.
+- Authoring workflows place a new command in `public` unless the user requests
+  or selects another group, but the stored command still contains
+  `group: public` explicitly.
+- An initialized catalog may contain no commands. Once present, every command
+  retains the required `uid`, `id`, `group`, `summary`, `description`, and
+  executable `command` fields.
+
+### Interactive behavior
+
+- `runx init` is a first-class Citty command that never requires an existing
+  manifest.
+- The interactive flow collects or confirms the project name and scripts
+  directory, renders a YAML preview, and requests confirmation before writing.
+- The interface should use a polished terminal presentation with clear
+  progress, validation, cancellation, and success states.
+- No framework-specific templates or automatic package-script imports are
+  offered.
+- An existing `runx.yaml` is never overwritten without explicit confirmation.
+- Cancellation leaves no partial file, and non-interactive invocation fails
+  clearly instead of hanging.
+
+## Alternatives Considered
+
+### Require a first command during initialization
+
+Rejected. Initialization establishes the catalog so commands can be added later
+from explicit developer requests. A fabricated starter command would make the
+manifest less truthful.
+
+### Offer framework-specific templates or scan package scripts
+
+Rejected. RunX is language-agnostic, and the project owner explicitly excluded
+framework-specific starter templates from the initializer.
+
+### Keep numeric `version: 1` compatibility
+
+Rejected. RunX has not been used outside development, so there is no legacy
+manifest population to migrate. Supporting two version shapes would add
+unnecessary schema and documentation complexity.
+
+### Store the scripts directory in a separate config file
+
+Rejected. `runx.yaml` remains the single source of truth for the command
+catalog and its script location.
+
+### Create the scripts directory eagerly
+
+Rejected for initialization. An empty directory is not useful to the catalog
+and is not preserved by Git. The directory should be created with the first
+real script.
+
+## Consequences
+
+- The manifest TypeBox schema must accept only supported Semantic Versioning
+  strings, require `scripts.directory`, and allow an empty command array.
+- Semantic validation must require the `public` group and continue requiring
+  every command to reference a declared group.
+- Script-directory validation must enforce a relative path within the manifest
+  root.
+- Existing fixtures and documentation using numeric `version: 1` must move to
+  `version: "1.0.0"` and include `public`.
+- Listing and checking an empty initialized manifest must succeed without
+  attempting command execution.
+- The initializer needs an isolated prompt boundary so interactive behavior can
+  be tested without depending on a real terminal.
+- The bundled agent skill update is intentionally deferred to the process that
+  delivers the complete agent-integration request.
+
+## Reversal Or Revisit Conditions
+
+Revisit this decision only if real-world manifest migration requires a
+compatibility policy, the command catalog needs multiple script roots, or a
+future major manifest version replaces the group model. Such a change must be
+recorded as a new decision and reflected in the manifest's major version.
+
+## Follow-up Work
+
+- Implement the manifest schema and semantic validation changes.
+- Implement and test the interactive `runx init` command.
+- Update canonical CLI and manifest documentation.
+- Update XDocs descriptors for every changed module or companion document.
+- Leave agent-skill content changes for the complete agent-integration work.
+
+## References
+
+- [Alpha boundaries](./alpha-boundaries.md)
+- [Alpha command-catalog requirements](../requirements/alpha-command-catalog.md)
+- [CLI architecture](../architecture/cli-architecture.md)
+- [GitHub issue #10](https://github.com/CGuiho/runx/issues/10)

package/docs/docs.xdocs.md

@@ -8,6 +8,7 @@ children:
   - runx-decisions
   - runx-plans
   - runx-reviews
+  - runx-superpowers
   - runx-todo
   - runx-validation
 files: {}
@@ -22,4 +23,5 @@ flags: []
 status: stable
 ---
 
-The documentation tree records the approved alpha direction and its verification evidence.
+The documentation tree records the approved product direction, executable
+design specifications, and verification evidence.

package/docs/plans/interactive-init-manifest.md

@@ -0,0 +1,177 @@
+---
+name: RunX Interactive Init Manifest Plan
+purpose: Sequence implementation of the accepted runx init workflow and manifest contract.
+description: Defines the schema, interactive terminal UI, validation, documentation, and pull-request work for RunX initialization.
+created: 2026-07-14
+flags:
+  - approved
+tags:
+  - plans
+  - cli
+  - manifest
+keywords:
+  - runx init
+  - runx.yaml
+  - semantic versioning
+  - public group
+  - scripts directory
+owner: runx-plans
+---
+
+# RunX Interactive Init Manifest Plan
+
+## Sources
+
+- [Interactive Init Manifest Decision](../decisions/interactive-init-manifest.md)
+- [Alpha Command Catalog Requirements](../requirements/alpha-command-catalog.md)
+- [CLI Architecture](../architecture/cli-architecture.md)
+- GitHub issue [#10](https://github.com/CGuiho/runx/issues/10)
+
+## Unit 1: Establish the Manifest Contract
+
+- Goal: Make the current manifest validator enforce the accepted `1.x.x`
+  Semantic Versioning, scripts directory, public group, and empty catalog
+  contract.
+- Owner: `C:\GUIHO\runx`.
+- Dependencies: Accepted interactive-init decision.
+- Files:
+  - `source/manifest.ts`
+  - `source/types.ts` when TypeScript inference exposes the new manifest shape
+  - `source/guiho-runx.spec.ts`
+  - `source/cli.spec.ts` fixtures that construct manifests
+- Behavior:
+  - Replace numeric `version: 1` with a Semantic Versioning string and accept
+    only supported major version `1`.
+  - Require `scripts.directory` as a non-empty relative path inside the
+    manifest root.
+  - Require the `public` group with a non-empty summary.
+  - Permit an empty `commands` array while keeping every populated command
+    explicit about its existing group.
+  - Preserve strict unknown-property rejection and existing selector and
+    execution safety behavior.
+- Data, auth, permissions, and cache: Local YAML contract only. No remote data,
+  authentication, authorization, cache, or secret changes.
+- Tests:
+  - Accept `"1.0.0"` and prerelease/build SemVer forms with major `1`.
+  - Reject numeric versions, malformed SemVer, unsupported major versions,
+    missing scripts configuration, escaping script paths, missing public, and
+    commands that name unknown groups.
+  - Prove empty initialized catalogs check and list without execution.
+- Acceptance: `readManifest()` returns a strict manifest with `scripts` and
+  `public`, and invalid configurations fail with actionable `RunXError`
+  messages.
+- Stop conditions: Stop if SemVer support would require a migration policy,
+  scripts need more than one root, or the change weakens command safety.
+
+## Unit 2: Implement the Interactive Initializer
+
+- Goal: Add a beautiful, cancellable `runx init` Citty command that creates a
+  valid empty `runx.yaml` without ever executing a configured command.
+- Dependencies: Unit 1.
+- Files:
+  - `package.json`
+  - `bun.lock`
+  - `source/init.ts`
+  - `source/init.spec.ts`
+  - `source/cli.ts`
+  - `source/cli.spec.ts`
+  - `source/help.ts`
+- Behavior:
+  - Use a dependency-free Bun terminal prompt adapter with clear visual states,
+    so the initializer remains portable across native and Windows builds.
+  - Isolate prompt interactions behind an injected interface so prompt flow and
+    filesystem behavior can be tested without a real terminal.
+  - In an interactive terminal, welcome the user, collect a project name
+    defaulting to the selected directory name, collect a scripts directory
+    defaulting to `scripts`, preview the exact YAML, and request confirmation.
+  - Write only `runx.yaml`; create `scripts/` later when the first real script
+    is added.
+  - Detect an existing `runx.yaml` in the selected directory and require a
+    second explicit overwrite confirmation.
+  - Use an atomic temporary-file write and leave no partial manifest on
+    cancellation or failure.
+  - Fail clearly outside an interactive terminal; do not hang and do not emit
+    interactive ANSI frames into JSON output.
+  - Accept `--cwd` as the target directory, reject `--file` because the
+    initializer always creates `runx.yaml`, and reject `--format json` because
+    initialization is an interactive terminal workflow.
+  - Register `init` as a first-class Citty command, include it in help/home and
+    command-tree output, and reserve the word from selector shorthand.
+- Tests:
+  - Successful creation exactly matches the accepted YAML shape.
+  - Cancellation leaves no file.
+  - Existing-file rejection and confirmed overwrite are safe.
+  - Default and custom project/scripts values validate.
+  - CLI help works outside a manifest and non-interactive invocation exits with
+    a clear error.
+  - `--file` and `--format json` report clear unsupported-option errors without
+    creating files.
+  - The generated file passes `runx check` and `runx list`.
+- Acceptance: `runx init` produces a polished, deterministic creation flow and
+  never executes a manifest command.
+- Stop conditions: Stop if the terminal prompt adapter fails Bun tests or native
+  compile, if Citty cannot route `init` without conflicting with selector shorthand, or
+  if atomic replacement is not portable on Windows.
+
+## Unit 3: Align Canonical Documentation and XDocs
+
+- Goal: Make public and structured documentation accurately describe the new
+  manifest and initializer without modifying the bundled agent skill.
+- Dependencies: Units 1 and 2.
+- Files:
+  - `README.md`
+  - `DOCS.md`
+  - `source/source.xdocs.md`
+  - `runx.xdocs.md` when its package description needs updating
+  - `docs/plans/plans.xdocs.md`
+- Behavior:
+  - Document `runx init`, Semantic Versioning, `scripts.directory`, mandatory
+    `public`, empty catalog initialization, and command-to-script examples.
+  - Keep the bundled `skills/guiho-s-runx/SKILL.md` unchanged; its update belongs
+    to the separate agent-integration delivery requested by the project owner.
+  - Update the source descriptor for the initializer module and changed CLI /
+    manifest responsibilities.
+- Checks:
+  - `xdocs meta docs\plans --documents --strict --format json`
+  - `xdocs meta source --strict --format json`
+  - `xdocs tree`
+- Acceptance: User-facing docs, XDocs metadata, and implementation agree.
+- Stop conditions: Stop if XDocs requires unrelated coverage cleanup; validate
+  only the affected subtrees and report wider pre-existing findings.
+
+## Unit 4: Validate, Review, Commit, Push, and Open a Pull Request
+
+- Goal: Produce evidence that the implementation satisfies the accepted
+  decision, then deliver it as a draft pull request from `codex/runx-init`.
+- Dependencies: Units 1 through 3.
+- Checks:
+  - `bun run typecheck`
+  - `bun test`
+  - `bun run build`
+  - `bun run binary`
+  - `xdocs meta docs\plans --documents --strict --format json`
+  - `xdocs meta source --strict --format json`
+  - `xdocs tree`
+  - `git diff --check`
+- Delivery:
+  - Write an implementation review and validation report with XDocs metadata.
+  - Commit coherent code, tests, documentation, and validation artifacts.
+  - Push only the feature branch and create a draft pull request that links
+    issue #10 and states that agent-skill automation is intentionally tracked
+    separately in issue #11.
+- Acceptance: All applicable checks pass, the worktree is clean, the branch is
+  pushed, and the draft pull request is reviewable without a release, tag, or
+  package publication.
+- Stop conditions: Stop before push/PR if validation fails, unrelated changes
+  appear, GitHub rejects authentication, or the branch diverges unexpectedly.
+
+## TODO Alignment
+
+This is one approved, focused package implementation and does not need a new
+long-running TODO entry. The decision, plan, review, and validation records are
+the durable delivery trail.
+
+## First Executable Unit
+
+Unit 1: update `source/manifest.ts` and its fixtures/tests to enforce the
+accepted manifest contract.

package/docs/plans/plans.xdocs.md

@@ -6,22 +6,33 @@ children: []
 files:
   alpha-implementation.md: Breaks the accepted alpha into implementation and validation units.
   citty-cli-migration.md: Executes the full Citty command-tree migration, compatibility validation, protected delivery, and patch release.
+  interactive-init-manifest.md: Sequences the SemVer manifest, public group, scripts directory, and interactive initializer delivery.
   mirror-automatic-push.md: Enables automatic Mirror release pushes with a synchronized protected-main safety gate.
   npm-trusted-publishing-release.md: Sequences workflow implementation, protected delivery, Mirror patching, and public trusted-publishing verification.
+  rfc-0034-cli-compliance-migration.md: Executes the breaking full RFC 0034 migration across runtime, configuration, help, agents, upgrades, distribution, release assets, documentation, and validation.
   windows-self-upgrade.md: Sequences synchronous Windows replacement, rollback coverage, validation, issue closure, and patch delivery.
+  upgrade-reliability-implementation.md: Sequences release discovery, streamed progress, transactional replacement, recovery, installers, and validation.
 documents:
   alpha-implementation.md: Plan used for the initial RunX implementation.
   citty-cli-migration.md: Active plan for replacing handwritten CLI parsing and routing with Citty and delivering its patch release.
+  interactive-init-manifest.md: Approved implementation plan for the RunX interactive init manifest feature.
   mirror-automatic-push.md: Approved plan for configuring, validating, and merging Mirror push=true without applying another release.
   npm-trusted-publishing-release.md: Approved executable plan for the RunX 0.2.1 trusted-publishing release trial.
+  rfc-0034-cli-compliance-migration.md: Approved step-by-step plan for making RunX fully compliant with the GUIHO CLI engineer contract.
   windows-self-upgrade.md: Approved executable plan for fixing Windows native self-upgrade and delivering its patch.
+  upgrade-reliability-implementation.md: Approved executable plan for GitHub issues 12 and 13.
 tags:
   - plans
 keywords:
   - runx
   - implementation
   - citty
+  - runx init
+  - scripts directory
   - mirror push
+  - RFC 0034
+  - agent namespace
+  - fourteen release assets
   - windows self-upgrade
 flags: []
 status: stable