@guiho/runx 0.2.2 → 0.2.4

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/plans.xdocs.md

@@ -4,8 +4,10 @@ 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.
   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.
   npm-trusted-publishing-release-review.md: Ready-for-execution review of the npm trusted-publishing release plan.
 tags:
   - reviews
@@ -13,6 +15,7 @@ tags:
 keywords:
   - runx
   - plan review
+  - citty
   - 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/npm-trusted-publishing-0.2.2.md

@@ -0,0 +1,54 @@
+---
+name: RunX npm Trusted Publishing 0.2.2 Validation
+purpose: Record the release checks and GitHub result for the 0.2.2 trusted-publishing retry.
+description: Documents successful build validation and the tag-ruleset rejection that prevented the Publish workflow from starting.
+created: 2026-07-14
+flags: []
+tags:
+  - validation
+  - release
+keywords:
+  - runx
+  - npm
+  - trusted publishing
+owner: runx-validation
+---
+
+# npm Trusted Publishing 0.2.2 Validation
+
+## Result
+
+The `0.2.2` package bump was merged to protected `main`, but GitHub rejected
+creation of the `@guiho/runx@0.2.2` tag. Because the tag was not created, the
+Publish workflow did not run and npm remained on `0.2.0`.
+
+## Passed checks
+
+- `bun run typecheck`
+- `bun test`: 4 passed, 0 failed
+- `bun run build`
+- `bun run binary`
+- `bun run binaries`: 12 native assets built and verified
+- `mirror version plan patch`: planned `0.2.1` to `0.2.2`
+- `xdocs meta . --documents --strict --owner runx --format json`
+- Pull request `#4` CI: passed
+
+## Release evidence
+
+- Protected-main merge: `57c7d81`
+- Mirror release commit: `6c67be5`
+- Local annotated tag: `@guiho/runx@0.2.2`
+- Remote tag: not created
+- Publish workflow run: not started
+- npm latest version after the attempt: `0.2.0`
+
+## Blocking rules
+
+GitHub rejected the tag with `GH013` because the active tag ruleset both
+requires linear history and restricts tag creation. The reported merge-commit
+violation was `f445631`. The ruleset had no bypass actors, and the authenticated
+repository owner could not bypass it.
+
+Trusted publishing itself was not exercised by this attempt. The tag ruleset
+must permit the release actor to create the version tag before npm OIDC can be
+validated.

package/docs/validation/validation.xdocs.md

@@ -5,12 +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"}