@guiho/runx 0.2.3 → 0.2.5

package/docs/reviews/implementation/citty-cli-migration-review.md

@@ -0,0 +1,85 @@
+---
+name: RunX Citty CLI Migration Implementation Review
+purpose: Review the completed Citty migration against its accepted decision, executable plan, architecture, and public contract.
+description: Records findings, acceptance checks, verification evidence, documentation alignment, and residual risk before protected delivery.
+created: 2026-07-14
+flags:
+  - accepted
+tags:
+  - reviews
+  - implementation
+  - cli
+keywords:
+  - runx
+  - citty
+  - command routing
+  - native executable
+owner: runx-implementation-reviews
+---
+
+# RunX Citty CLI Migration Implementation Review
+
+## Verdict
+
+Accepted for protected delivery.
+
+## Findings
+
+No open blocker, high-severity, or medium-severity findings remain.
+
+Two review findings were corrected before this verdict:
+
+- The selector-compatible command map now has a null prototype, so valid
+  selector names such as `constructor` cannot collide with inherited object
+  properties.
+- Root, catalog, run, agent-install, and self-management argument definitions
+  are separated, so Citty help shows only applicable flags while the root still
+  accepts options before or after commands.
+
+## Acceptance Criteria Check
+
+- Citty is the only argument parser, alias registry, command router, and
+  ordinary usage renderer.
+- `source/flags.ts` is removed and no RunX-owned token parsing loop remains.
+- `-h`, `--help`, `-v`, and `--version` work outside a configured project.
+- All catalog, nested agent, nested upgrade, uninstall, alias, and selector
+  shorthand paths dispatch through Citty command definitions.
+- Unknown options and missing positionals produce relevant usage without
+  manifest discovery.
+- Manifest, selector, execution, agent, upgrade, uninstall, text, and JSON
+  domain behavior remains in the existing modules.
+- Inspection, help, version, and dry-run paths do not execute a configured
+  command.
+- Citty bundles into the local native executable and all twelve release targets
+  without adding a Node.js runtime requirement.
+- The npm package declares Citty as a runtime dependency and has no
+  `postinstall` script.
+
+## Verification Evidence
+
+- Typecheck, thirteen tests, library build, local native compile, twelve-target
+  native matrix, npm pack dry-run, packed launcher, and strict XDocs checks
+  passed.
+- Tests cover root and nested help, short and long version/help flags, all
+  public command routes, aliases, options before and after commands, JSON,
+  safety gates, usage errors, agent installation, self-management routing, and
+  selector prototype-name compatibility.
+
+## Docs And TODO Check
+
+- README, canonical docs, architecture, AGENTS instructions, bundled skill,
+  decision, plan, and affected XDocs descriptors align with the implementation.
+- No standalone TODO was needed because the accepted plan was executed in this
+  authorized session.
+
+## Residual Risk
+
+The remaining risk is distribution-only: GitHub CI, protected merge, tag
+creation, manual `production` environment approval, and public npm/GitHub
+publication must still complete. Unit 5 owns that evidence.
+
+## References
+
+- [Citty CLI Migration Decision](../../decisions/citty-cli-migration.md)
+- [Citty CLI Migration Plan](../../plans/citty-cli-migration.md)
+- [Citty CLI Migration Validation](../../validation/citty-cli-migration.md)

package/docs/reviews/implementation/implementation.xdocs.md

@@ -0,0 +1,22 @@
+---
+subject: runx-implementation-reviews
+description: Delivery-readiness reviews of implemented RunX plans and behavior changes.
+parent: runx-reviews
+children: []
+files:
+  citty-cli-migration-review.md: Reviews the implemented Citty command tree, compatibility adapter, tests, documentation, packaging, and release readiness.
+documents:
+  citty-cli-migration-review.md: Accepted implementation review for the full Citty CLI migration.
+tags:
+  - reviews
+  - implementation
+keywords:
+  - runx
+  - citty
+  - implementation review
+flags: []
+status: stable
+---
+
+Implementation reviews compare delivered RunX behavior with accepted decisions,
+plans, architecture, tests, and validation evidence.

package/docs/reviews/plans/citty-cli-migration-review.md

@@ -0,0 +1,80 @@
+---
+name: RunX Citty CLI Migration Plan Review
+purpose: Verify that the full Citty migration plan is safe, complete, testable, and ready for execution.
+description: Reviews command compatibility, safety invariants, native packaging, protected delivery, documentation, and Mirror release sequencing.
+created: 2026-07-14
+flags:
+  - approved
+tags:
+  - reviews
+  - plans
+  - cli
+keywords:
+  - runx
+  - citty
+  - plan review
+  - native executable
+owner: runx-plan-reviews
+---
+
+# RunX Citty CLI Migration Plan Review
+
+## Verdict
+
+Ready for execution.
+
+## Findings
+
+- No blocker or high-severity findings remain.
+- The plan explicitly removes both handwritten parsing and manual top-level
+  routing, so the result cannot quietly retain a second parser behind Citty.
+- The root-selector shorthand is treated as a compatibility path with known
+  Citty commands taking precedence, preventing command names from being
+  reinterpreted as manifest selectors.
+- `-h` and `-v` are tested outside a configured project, directly covering the
+  failure that motivated the migration.
+- Manifest parsing, selectors, subprocess execution, upgrades, installers, and
+  JSON payloads stay within their current domain modules; the migration is
+  bounded to CLI ownership.
+- No data, authentication, authorization, or cache migrations are involved.
+
+## Safety and Compatibility Review
+
+- The no-spawn invariant covers listing, describing, checking, help, version,
+  and dry runs.
+- Missing arguments and unknown options are usage failures, while RunX domain
+  failures preserve their existing error contract.
+- Every public command, nested route, alias, positional selector, and applicable
+  option has an explicit test requirement.
+- Citty must bundle into both npm output and Bun native executables without a
+  Node.js runtime dependency.
+
+## Delivery and Release Review
+
+- Complete Bun and native validation precedes protected-branch delivery.
+- The implementation reaches `main` before Mirror plans and applies patch
+  `0.2.4`.
+- The Mirror-managed release commit reaches protected `main` before its tag is
+  pushed.
+- The plan preserves the `production` environment's manual approval gate and
+  observes npm and GitHub distribution after approval.
+
+## Documentation and TODO Review
+
+- README, detailed docs, the bundled RunX skill, and affected XDocs descriptors
+  are named explicitly.
+- The work is authorized for continuous execution in this session, so a second
+  TODO artifact would duplicate the decision, plan, and review without adding a
+  durable scheduling boundary.
+
+## First Executable Unit
+
+Execute Unit 1 in
+[RunX Citty CLI Migration Plan](../../plans/citty-cli-migration.md): add Citty
+with Bun and verify its installed command API before replacing production
+routing.
+
+## References
+
+- [RunX Citty CLI Migration Plan](../../plans/citty-cli-migration.md)
+- [Full Citty CLI Migration](../../decisions/citty-cli-migration.md)

package/docs/reviews/plans/mirror-automatic-push-review.md

@@ -0,0 +1,57 @@
+---
+name: RunX Mirror Automatic Push Plan Review
+purpose: Verify that the automatic-push configuration plan is safe, bounded, and ready for execution.
+description: Reviews synchronized-main safeguards, read-only validation, protected delivery, and release side effects.
+created: 2026-07-14
+flags:
+  - approved
+tags:
+  - reviews
+  - plans
+  - release
+keywords:
+  - runx
+  - mirror push
+  - plan review
+  - protected main
+owner: runx-plan-reviews
+---
+
+# RunX Mirror Automatic Push Plan Review
+
+## Verdict
+
+Ready for execution.
+
+## Findings
+
+- No blocker or high-severity findings remain.
+- The clean, synchronized `main` precondition is explicit and prevents a
+  release tag from pointing at an unmerged feature or stale commit.
+- Unit 1 uses only read-only Mirror validation and explicitly prohibits another
+  version apply, so the current `0.2.4` release remains unchanged.
+- The plan documents that `push = true` makes every future Mirror apply an
+  externally visible release mutation.
+- No application data, authentication, authorization, or cache behavior is
+  affected. GitHub credentials, rulesets, environment approval, and npm OIDC
+  remain external enforcement layers.
+
+## Delivery Review
+
+- The configuration change must pass the protected pull-request workflow
+  before reaching `main`.
+- Post-merge verification checks the resolved configuration on synchronized
+  `main` and confirms that no `0.2.5` tag was created.
+- A CI failure, protection failure, or unexpected version mutation is an
+  explicit stop condition.
+
+## First Executable Unit
+
+Execute Unit 1 in
+[RunX Mirror Automatic Push Plan](../../plans/mirror-automatic-push.md): set and
+document the resolved automatic-push policy without applying a release.
+
+## References
+
+- [RunX Mirror Automatic Push Plan](../../plans/mirror-automatic-push.md)
+- [RunX Mirror Automatic Release Push](../../decisions/mirror-automatic-push.md)

package/docs/reviews/plans/plans.xdocs.md

@@ -4,8 +4,12 @@ description: Execution-readiness reviews for RunX implementation and release pla
 parent: runx-reviews
 children: []
 files:
+  citty-cli-migration-review.md: Reviews completeness, compatibility, safety invariants, native packaging, and release sequencing for the Citty migration.
+  mirror-automatic-push-review.md: Reviews synchronized-main safeguards, read-only validation, protected delivery, and release side effects.
   npm-trusted-publishing-release-review.md: Reviews sequencing, acceptance criteria, safety gates, and validation for the RunX 0.2.1 trusted-publishing plan.
 documents:
+  citty-cli-migration-review.md: Ready-for-execution review of the full Citty CLI migration plan.
+  mirror-automatic-push-review.md: Ready-for-execution review of the Mirror automatic-push configuration plan.
   npm-trusted-publishing-release-review.md: Ready-for-execution review of the npm trusted-publishing release plan.
 tags:
   - reviews
@@ -13,6 +17,8 @@ tags:
 keywords:
   - runx
   - plan review
+  - citty
+  - mirror push
   - trusted publishing
 flags: []
 status: stable

package/docs/reviews/reviews.xdocs.md

@@ -3,6 +3,7 @@ subject: runx-reviews
 description: Structured reviews of RunX architecture, plans, implementation, and release readiness.
 parent: runx-docs
 children:
+  - runx-implementation-reviews
   - runx-plan-reviews
 files: {}
 documents: {}

package/docs/validation/citty-cli-migration.md

@@ -0,0 +1,95 @@
+---
+name: RunX Citty CLI Migration Validation
+purpose: Preserve verification evidence for the full Citty CLI migration before protected delivery and release.
+description: Records TypeScript, tests, library, native binaries, npm packaging, CLI behavior, XDocs, failures, and residual distribution risk.
+created: 2026-07-14
+flags:
+  - validated
+tags:
+  - validation
+  - cli
+  - release
+keywords:
+  - runx
+  - citty
+  - native matrix
+  - npm pack
+owner: runx-validation
+---
+
+# RunX Citty CLI Migration Validation
+
+## Summary
+
+The complete Citty migration passes the local merge and release gate. Source,
+package, and native executable behavior agree on version `0.2.3` before the
+planned Mirror patch to `0.2.4`.
+
+## Scope
+
+- Citty dependency and command definitions.
+- Root, catalog, agent, upgrade, and uninstall routing.
+- Help, version, errors, aliases, selector shorthand, options, output formats,
+  confirmation, and dry-run safety.
+- TypeScript library, local native executable, twelve release assets, npm
+  tarball, packed launcher, bundled skill, and XDocs metadata.
+
+## Commands Run
+
+| Check | Result | Evidence |
+| --- | --- | --- |
+| `bun run typecheck` | passed | TypeScript emitted no diagnostics. |
+| `bun test` | passed | 13 tests, 0 failures, 125 assertions. |
+| `bun run build` | passed | TypeScript library output completed. |
+| `bun run binary` | passed | Local Windows executable compiled with Citty bundled. |
+| `bin/runx.exe -v` | passed | Printed `0.2.3` without manifest discovery. |
+| `bin/runx.exe --help` | passed | Printed the Citty root command tree and options. |
+| `bun run binaries` | passed | All 12 configured native assets compiled and were non-empty. |
+| `npm pack --dry-run --json` | passed | Reported 78 package files. |
+| `npm pack --json` | passed | Produced a 39,749-byte validation tarball with 78 files. |
+| packed `scripts/runx-bin.ts -v` | passed | Printed `0.2.3` outside a manifest. |
+| packed `scripts/runx-bin.ts --help` | passed | Printed Citty usage outside a manifest. |
+| `xdocs tree` | passed | Included the complete RunX documentation tree. |
+| `xdocs scan` | passed | Found 16 valid descriptors before adding this validation/review scope. |
+| `xdocs doctor .` | passed | 0 errors and 0 warnings. |
+
+## Package Checks
+
+- Packed `package.json` declares `citty: ^0.2.2` under runtime dependencies.
+- Packed `package.json` has no `postinstall` script.
+- The launcher selected the compiled `library/guiho-runx-bin.js` path and
+  returned successful version/help output.
+
+## Manual Behavior Checks
+
+- Source and native `-v`/help worked outside a configured project.
+- Citty usage displayed command-specific arguments and only applicable flags.
+- Unknown options and missing selectors returned usage errors rather than a
+  missing-manifest error.
+- A valid manifest selector named `constructor` executed through the root
+  shorthand, proving the compatibility map is prototype-safe.
+
+## Failures Or Blockers
+
+No implementation blocker remains. Two environment-only validation attempts
+failed before the successful package check: the sandbox denied `C:\tmp`, and
+npm's default user cache was not writable. Re-running with repository-local
+ignored `.temp` paths and npm cache completed successfully without changing the
+artifact.
+
+## Skipped Checks
+
+No plan-required local check was skipped. Public CI, protected merge, Mirror
+patch application, protected tag push, manual environment approval, GitHub
+Release assets, and npm provenance are pending Unit 5.
+
+## Readiness
+
+Ready for protected implementation delivery and the Mirror-managed `0.2.4`
+patch release.
+
+## References
+
+- [Citty CLI Migration Decision](../decisions/citty-cli-migration.md)
+- [Citty CLI Migration Plan](../plans/citty-cli-migration.md)
+- [Citty CLI Migration Implementation Review](../reviews/implementation/citty-cli-migration-review.md)

package/docs/validation/validation.xdocs.md

@@ -5,13 +5,16 @@ parent: runx-docs
 children: []
 files:
   alpha-implementation-summary.md: Records the completed alpha implementation, checks, and release boundaries.
+  citty-cli-migration.md: Records the complete local validation gate for the Citty command-tree migration.
 documents:
   alpha-implementation-summary.md: Validation summary for the first RunX implementation.
+  citty-cli-migration.md: Validation evidence for TypeScript, tests, native assets, npm packaging, CLI behavior, and XDocs.
   npm-trusted-publishing-0.2.2.md: Validation evidence for the blocked 0.2.2 npm trusted-publishing retry.
 tags:
   - validation
 keywords:
   - runx
+  - citty
   - tests
   - summary
 flags: []

package/library/cli.d.ts

@@ -1,3 +1,9 @@
-export declare const runCli: (rawArgs?: string[]) => Promise<void>;
-export declare const runCliWithErrorHandling: (rawArgs?: string[]) => Promise<void>;
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { CommandDef } from 'citty';
+export { runCli, runCliWithErrorHandling, runxCommand, };
+declare const runxCommand: CommandDef<any>;
+declare function runCli(rawArgs?: string[]): Promise<void>;
+declare function runCliWithErrorHandling(rawArgs?: string[]): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map

package/library/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,MAAM,aAAmB,MAAM,EAAE,KAA2B,OAAO,CAAC,IAAI,CAyBpF,CAAA;AAED,eAAO,MAAM,uBAAuB,aAAoB,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAY9E,CAAA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH,OAAO,KAAK,EAAkB,UAAU,EAAkB,MAAM,OAAO,CAAA;AAGvE,OAAO,EACL,MAAM,EACN,uBAAuB,EACvB,WAAW,GACZ,CAAA;AAqPD,QAAA,MAAiB,WAAW,iBAAwB,CAAA;AAEpD,iBAAe,MAAM,CAAC,OAAO,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAY9E;AAED,iBAAe,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBxE"}