@guiho/runx 0.2.7 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/CHANGELOG.md +39 -0
  2. package/DOCS.md +127 -128
  3. package/README.md +56 -75
  4. package/devops/build-binaries.ts +44 -62
  5. package/devops/devops.xdocs.md +8 -5
  6. package/devops/install.ps1 +182 -152
  7. package/devops/install.sh +197 -262
  8. package/devops/installers.spec.ts +31 -0
  9. package/devops/verify-release-assets.ts +17 -0
  10. package/docs/docs.xdocs.md +3 -1
  11. package/docs/plans/plans.xdocs.md +7 -0
  12. package/docs/plans/rfc-0034-cli-compliance-migration.md +586 -0
  13. package/docs/plans/upgrade-reliability-implementation.md +95 -0
  14. package/docs/reviews/implementation/implementation.xdocs.md +2 -0
  15. package/docs/reviews/implementation/rfc-0034-cli-compliance-migration-review.md +69 -0
  16. package/docs/reviews/plans/plans.xdocs.md +6 -0
  17. package/docs/reviews/plans/rfc-0034-cli-compliance-migration-review.md +80 -0
  18. package/docs/reviews/plans/upgrade-reliability-implementation-review.md +65 -0
  19. package/docs/superpowers/specs/2026-07-15-upgrade-reliability-design.md +662 -0
  20. package/docs/superpowers/specs/specs.xdocs.md +24 -0
  21. package/docs/superpowers/superpowers.xdocs.md +21 -0
  22. package/docs/todo/rfc-0034-cli-compliance-migration-implementation.md +77 -0
  23. package/docs/todo/rfc-0034-cli-compliance-migration.md +152 -0
  24. package/docs/todo/todo.xdocs.md +6 -2
  25. package/docs/validation/rfc-0034-cli-compliance-migration.md +83 -0
  26. package/docs/validation/upgrade-reliability.md +124 -0
  27. package/docs/validation/validation.xdocs.md +5 -0
  28. package/library/agents.d.ts +29 -4
  29. package/library/agents.d.ts.map +1 -1
  30. package/library/agents.js +143 -41
  31. package/library/cli.d.ts.map +1 -1
  32. package/library/cli.js +311 -331
  33. package/library/configuration.d.ts +57 -0
  34. package/library/configuration.d.ts.map +1 -0
  35. package/library/configuration.js +111 -0
  36. package/library/embedded-resources.d.ts +6 -1
  37. package/library/embedded-resources.d.ts.map +1 -1
  38. package/library/embedded-resources.js +10 -4
  39. package/library/executor.d.ts +5 -1
  40. package/library/executor.d.ts.map +1 -1
  41. package/library/executor.js +10 -10
  42. package/library/help.d.ts +8 -4
  43. package/library/help.d.ts.map +1 -1
  44. package/library/help.js +70 -46
  45. package/library/init.d.ts +8 -27
  46. package/library/init.d.ts.map +1 -1
  47. package/library/init.js +37 -159
  48. package/library/manifest.d.ts +4 -43
  49. package/library/manifest.d.ts.map +1 -1
  50. package/library/manifest.js +4 -125
  51. package/library/path-utils.d.ts +13 -0
  52. package/library/path-utils.d.ts.map +1 -0
  53. package/library/path-utils.js +82 -0
  54. package/library/recovery.d.ts +7 -0
  55. package/library/recovery.d.ts.map +1 -0
  56. package/library/recovery.js +23 -0
  57. package/library/release-catalog.d.ts +32 -0
  58. package/library/release-catalog.d.ts.map +1 -0
  59. package/library/release-catalog.js +124 -0
  60. package/library/self-management.d.ts +24 -4
  61. package/library/self-management.d.ts.map +1 -1
  62. package/library/self-management.js +279 -99
  63. package/library/storage.d.ts +13 -0
  64. package/library/storage.d.ts.map +1 -0
  65. package/library/storage.js +38 -0
  66. package/library/types.d.ts +11 -16
  67. package/library/types.d.ts.map +1 -1
  68. package/library/types.js +3 -0
  69. package/library/update-cache.d.ts +21 -0
  70. package/library/update-cache.d.ts.map +1 -0
  71. package/library/update-cache.js +68 -0
  72. package/library/upgrade-reporting.d.ts +11 -0
  73. package/library/upgrade-reporting.d.ts.map +1 -0
  74. package/library/upgrade-reporting.js +67 -0
  75. package/library/upgrade-types.d.ts +72 -0
  76. package/library/upgrade-types.d.ts.map +1 -0
  77. package/library/upgrade-types.js +3 -0
  78. package/package.json +6 -3
  79. package/scripts/runx-bin.mjs +49 -0
  80. package/scripts/runx-bin.spec.ts +62 -0
  81. package/scripts/scripts.xdocs.md +3 -3
  82. package/skills/guiho-s-runx/SKILL.md +64 -59
  83. package/skills/guiho-s-runx/guiho-s-runx.xdocs.md +7 -4
  84. package/skills/skills.xdocs.md +1 -1
  85. package/docs/todo/implement-runx-alpha.md +0 -36
  86. package/scripts/runx-bin.ts +0 -24
@@ -0,0 +1,21 @@
1
+ ---
2
+ subject: runx-superpowers
3
+ description: Approved design specifications produced before RunX implementation planning and code changes.
4
+ parent: runx-docs
5
+ children:
6
+ - runx-superpowers-specs
7
+ files: {}
8
+ documents: {}
9
+ tags:
10
+ - documentation
11
+ - design
12
+ keywords:
13
+ - runx
14
+ - superpowers
15
+ - specifications
16
+ flags: []
17
+ status: stable
18
+ ---
19
+
20
+ This module groups approved RunX design specifications that define behavior,
21
+ interfaces, ownership, validation, and release gates before implementation.
@@ -0,0 +1,77 @@
1
+ ---
2
+ name: RunX RFC 0034 CLI Compliance Migration Implementation
3
+ purpose: Preserve the executed RX-01 through RX-16 implementation record.
4
+ description: Records the delivered module changes, breaking-contract decisions, test-hang diagnosis, and validation handoff for the RunX RFC migration.
5
+ created: 2026-07-18
6
+ flags:
7
+ - completed
8
+ tags:
9
+ - implementation
10
+ - cli
11
+ keywords:
12
+ - RFC 0034
13
+ - RX-01
14
+ - RX-16
15
+ - RunX
16
+ owner: runx-todo
17
+ ---
18
+
19
+ # RunX RFC 0034 CLI Compliance Migration Implementation
20
+
21
+ ## Summary
22
+
23
+ RX-01 through RX-16 were implemented as one breaking pre-1.0 migration. RunX
24
+ now has one Citty tree, Bun-only core modules, TypeBox-decoded configuration,
25
+ cache and release boundaries, complete Developer Context help, the singular
26
+ agent namespace, transactional upgrades, complete installers, a Node-compatible
27
+ npm bootstrap, and the exact fourteen release assets.
28
+
29
+ ## Implementation Map
30
+
31
+ - RX-02-RX-05: `path-utils.ts`, `storage.ts`, `configuration.ts`,
32
+ `update-cache.ts`, release schemas, and shared types establish Bun-first I/O
33
+ and TypeBox boundaries.
34
+ - RX-06-RX-08: `cli.ts` and `help.ts` own the exact Citty tree, exit mapping,
35
+ startup lifecycle, Unicode tree help, depth validation, and Markdown help.
36
+ - RX-09: `agents.ts`, embedded resources, the bundled skill, and
37
+ `prompts/guiho-i-runx.md` implement dual-tool skills, instruction blocks, and
38
+ prompt discovery.
39
+ - RX-10-RX-11: CLI output, release pagination, upgrade selection, replacement,
40
+ rollback, reconciliation, and cache behavior use stable contracts.
41
+ - RX-12-RX-14: both installers, `scripts/runx-bin.mjs`, the binary builder,
42
+ asset verifier, and GitHub workflows enforce the installation and fourteen
43
+ asset contracts.
44
+ - RX-15-RX-16: canonical docs, TODO, xdocs, review, validation, tests, builds,
45
+ and release preparation were aligned to the executable.
46
+
47
+ ## Test-Hang Diagnosis
48
+
49
+ The original unbounded suite hung in legacy process-oriented tests. The
50
+ individual CLI baseline passed 10/10, proving the CLI was not persistently
51
+ stuck. The obsolete tests were replaced or bounded; the final complete suite
52
+ runs 40 tests and exits normally in about 30 seconds.
53
+
54
+ ## Independent Audit Corrections
55
+
56
+ The final independent RFC audit found three public-surface defects that the
57
+ first validation suite did not exercise:
58
+
59
+ - the `upgrade` group hid its apply flags and allowed root `--version` handling
60
+ to intercept `runx upgrade --version <version>`;
61
+ - no-argument startup skipped the cached update notice;
62
+ - text-mode `agent prompt list --names` rendered a JSON array instead of raw
63
+ names.
64
+
65
+ The correction keeps `upgrade check` and `upgrade list`, makes the public
66
+ `upgrade` command own and execute all RFC flags directly, gates root version
67
+ handling to a one-token root invocation, reads the local cache before the
68
+ no-argument banner, and emits one raw prompt name per line. Focused tests invoke
69
+ the real Citty routing and output paths. The ignored `bin/runx.exe` left by a
70
+ single-binary build was removed before exact-asset verification; the strict
71
+ fourteen-name comparison remains unchanged.
72
+
73
+ ## References
74
+
75
+ - [Plan](../plans/rfc-0034-cli-compliance-migration.md)
76
+ - [Implementation review](../reviews/implementation/rfc-0034-cli-compliance-migration-review.md)
77
+ - [Validation](../validation/rfc-0034-cli-compliance-migration.md)
@@ -0,0 +1,152 @@
1
+ ---
2
+ name: Migrate RunX To Full RFC 0034 Compliance
3
+ purpose: Define the required outcome, scope, constraints, and completion signals for the RunX RFC 0034 migration task.
4
+ description: Captures what must be true after RunX adopts the complete GUIHO CLI contract and links the executable migration plan.
5
+ created: 2026-07-18
6
+ flags:
7
+ - approved
8
+ - breaking-change
9
+ - completed
10
+ tags:
11
+ - todo
12
+ - cli
13
+ - migration
14
+ keywords:
15
+ - runx
16
+ - RFC 0034
17
+ - guiho-s-0034-cli-engineer
18
+ - agent namespace
19
+ - fourteen release assets
20
+ owner: runx-todo
21
+ ---
22
+
23
+ # Migrate RunX To Full RFC 0034 Compliance
24
+
25
+ ## Summary
26
+
27
+ Bring RunX into complete compliance with GUIHO RFC 0034. This is an approved
28
+ breaking migration for a pre-1.0 CLI. Compatibility with `runx r`, root selector
29
+ shorthand, `--file`, upward manifest discovery, `runx agents`, `--tool`, old
30
+ markers, `macos` asset names, and the Bun-dependent npm launcher is not required.
31
+
32
+ ## Todo Index
33
+
34
+ - Task: `1. Migrate RunX To Full RFC 0034 Compliance`
35
+ - Status: completed
36
+ - Index: [TODO.md](../../TODO.md)
37
+
38
+ ## Outcome
39
+
40
+ RunX uses the mandatory Bun/TypeScript/Citty/TypeBox stack, has a Bun-only core,
41
+ implements the exact startup/configuration/help/agent/upgrade/installer/output
42
+ contracts, ships a Node-compatible npm bootstrap, and publishes exactly twelve
43
+ RFC-named binaries plus `guiho-s-runx` and `guiho-i-runx`.
44
+
45
+ ## Scope
46
+
47
+ ### In scope
48
+
49
+ - Core CLI source, entrypoints, command tree, domain adapters, and errors.
50
+ - `runx.yaml` resolution and TypeBox decoding.
51
+ - update cache and background worker under `~/.guiho/runx/`.
52
+ - all Developer Context help modes at every scope.
53
+ - complete singular `agent skill`, `agent instruction`, and `agent prompt`
54
+ namespaces.
55
+ - transactional upgrade, catalog pagination, and post-upgrade reconciliation.
56
+ - PowerShell and POSIX installers.
57
+ - Node-compatible npm bootstrap.
58
+ - exact fourteen-asset build and release enforcement.
59
+ - tests, CI, README, DOCS, bundled skill, TODO, changelog, decisions, and xdocs.
60
+
61
+ ### Out of scope
62
+
63
+ - Workflow dependency graphs or a proprietary task language.
64
+ - Remote command execution.
65
+ - Secret management.
66
+ - Publishing, version bumping, tagging, or live installation without separate
67
+ authorization.
68
+
69
+ ## Acceptance Signals
70
+
71
+ - No prohibited Node built-ins exist in core CLI source.
72
+ - No arguments prints a decoded cached update notice first when one is
73
+ available, followed by exactly `Hello Windows - runx v<version>`.
74
+ - `runx.yaml` resolves only by `--config`, effective cwd, then the standardized
75
+ global path, and prints its absolute loaded path.
76
+ - TypeBox decodes configuration, cache, remote releases, structured flags, and
77
+ stable output objects before use.
78
+ - Only `-h` and root `-v` short aliases exist.
79
+ - Every command scope supports standard help, tree help, positive tree depth,
80
+ and redirect-safe Markdown help.
81
+ - The final command catalog in the plan is the only public catalog.
82
+ - Agent skill actions target both agent-tool directories; instruction actions
83
+ handle zero, one, or both instruction files idempotently; prompt output obeys
84
+ raw/names-only rules.
85
+ - Upgrade, list pagination, pre-release filtering, installers, and the npm
86
+ wrapper pass isolated tests.
87
+ - Release verification finds exactly fourteen correctly named assets and no
88
+ `macos` names.
89
+ - Typecheck, tests, safe builds, xdocs validation, implementation review, and
90
+ validation reporting complete successfully.
91
+
92
+ ## Dependencies And Context
93
+
94
+ - [Executable migration plan](../plans/rfc-0034-cli-compliance-migration.md)
95
+ - `guiho-a-0001-swe` is the coordinating Software Engineer/SWE agent.
96
+ - `guiho-s-0034-cli-engineer` is the mandatory specialist skill.
97
+ - The current Citty migration, upgrade work, and bundled RunX skill are inputs,
98
+ not constraints that override RFC 0034.
99
+
100
+ ## Watch-outs
101
+
102
+ - Inspection and dry-run commands must never spawn a manifest command.
103
+ - JSON stdout must remain one parseable document.
104
+ - The foreground startup path must never await a network request.
105
+ - Tests must isolate home directories, skill installation, instruction files,
106
+ update caches, executable replacement, and release hosting.
107
+ - Generated `library/`, `bin/`, `bundle/`, and `vendor/` outputs remain
108
+ unedited.
109
+ - Breaking changes are approved, but unrelated RunX domain behavior must not be
110
+ removed accidentally.
111
+
112
+ ## Before Starting
113
+
114
+ - Read the repository and parent instructions, this spec, and the full plan.
115
+ - Load the SWE agent and every skill named in the plan.
116
+ - Confirm the live branch, clean/understood worktree, and baseline checks.
117
+ - Inventory current agent behavior and prohibited imports again because source
118
+ may have changed after this plan was written.
119
+
120
+ ## While Working
121
+
122
+ - Execute one numbered plan unit at a time with `guiho-s-0023-plan-executor`.
123
+ - Update implementation notes, TODO state, docs, tests, and xdocs in the same
124
+ unit.
125
+ - Do not preserve an obsolete interface merely to avoid a breaking change.
126
+ - Stop on unapproved publishing, tagging, pushing, or real global installation.
127
+
128
+ ## After Finishing
129
+
130
+ - Run implementation review and validation reporting.
131
+ - Record every passed, failed, and skipped check.
132
+ - Keep the TODO in `testing` until all local acceptance signals are proven.
133
+ - Request separate authorization before Mirror versioning or release actions.
134
+
135
+ ## Related Files
136
+
137
+ - [Implementation plan](../plans/rfc-0034-cli-compliance-migration.md) -
138
+ Ordered file-level execution units and validation gates.
139
+ - [CLI architecture](../architecture/cli-architecture.md) - Current architecture
140
+ that the migration must revise where it conflicts with RFC 0034.
141
+ - [Previous Citty decision](../decisions/citty-cli-migration.md) - Earlier
142
+ compatibility contract that must be superseded where it conflicts.
143
+ - [Plan review](../reviews/plans/rfc-0034-cli-compliance-migration-review.md) -
144
+ Ready-for-execution review of sequencing, coverage, and approval gates.
145
+
146
+ ## References
147
+
148
+ - [TODO.md](../../TODO.md)
149
+ - [AGENTS.md](../../AGENTS.md)
150
+ - [Implementation notes](./rfc-0034-cli-compliance-migration-implementation.md)
151
+ - [Implementation review](../reviews/implementation/rfc-0034-cli-compliance-migration-review.md)
152
+ - [Validation report](../validation/rfc-0034-cli-compliance-migration.md)
@@ -4,15 +4,19 @@ description: Linked task specifications for the RunX TODO index.
4
4
  parent: runx-docs
5
5
  children: []
6
6
  files:
7
- implement-runx-alpha.md: Defines the completion signals and constraints for the alpha task.
8
7
  protect-branches-and-tag-creation.md: Records the verified active GitHub branch and release-tag rulesets for RunX.
8
+ rfc-0034-cli-compliance-migration.md: Defines the required breaking migration outcome, scope, constraints, and completion signals for full RFC 0034 compliance.
9
+ rfc-0034-cli-compliance-migration-implementation.md: Records the delivered RX units, implementation map, test-hang diagnosis, and independent audit corrections.
9
10
  documents:
10
- implement-runx-alpha.md: Task specification for implementing RunX alpha.
11
11
  protect-branches-and-tag-creation.md: Completed task specification with active RunX ruleset IDs, protected patterns, and verification evidence.
12
+ rfc-0034-cli-compliance-migration.md: Task specification linked from TODO task 1 for the full RunX CLI contract migration.
13
+ rfc-0034-cli-compliance-migration-implementation.md: Completed implementation, independent correction, and validation handoff for TODO task 1.
12
14
  tags:
13
15
  - todo
14
16
  keywords:
15
17
  - runx
18
+ - RFC 0034
19
+ - CLI migration
16
20
  - tasks
17
21
  flags: []
18
22
  status: stable
@@ -0,0 +1,83 @@
1
+ ---
2
+ name: RunX RFC 0034 CLI Compliance Migration Validation
3
+ purpose: Record direct verification evidence for every migration completion gate.
4
+ description: Command results for typecheck, tests, builds, CLI contracts, npm bootstrap, installers, release assets, imports, xdocs, and Git integrity.
5
+ created: 2026-07-18
6
+ flags:
7
+ - validated
8
+ tags:
9
+ - validation
10
+ - cli
11
+ keywords:
12
+ - RFC 0034
13
+ - 40 tests
14
+ - 14 assets
15
+ - RunX
16
+ owner: runx-validation
17
+ ---
18
+
19
+ # RunX RFC 0034 CLI Compliance Migration Validation
20
+
21
+ ## Summary
22
+
23
+ All local RFC completion gates passed after independent audit corrections for
24
+ upgrade routing, no-argument cached notices, and names-only prompt output. No
25
+ validation blocker remains.
26
+
27
+ ## Commands Run
28
+
29
+ | Command or check | Result |
30
+ | --- | --- |
31
+ | `bun run typecheck` | Passed |
32
+ | `bun test --timeout 30000` | Passed: 40 tests, 272 assertions |
33
+ | `bun run build` | Passed |
34
+ | `bun run binary` | Passed |
35
+ | `bun run binaries` | Passed: twelve native targets |
36
+ | `bun run verify-assets` | Passed: exactly fourteen unique assets |
37
+ | `node --check scripts/runx-bin.mjs` | Passed |
38
+ | packed npm bootstrap local-server smoke | Passed with Node and Bun removed from PATH |
39
+ | prohibited core Node-import scan | Passed: zero matches |
40
+ | CLI banner/help/config/agent/output/exit smoke tests | Passed in CLI suite |
41
+ | live `upgrade --help`, prompt names, source banner, and compiled version smokes | Passed |
42
+ | PowerShell and POSIX installer contract tests | Passed |
43
+ | `xdocs doctor --warnings-as-errors` | Passed: zero errors and zero warnings |
44
+ | `git diff --check` | Passed |
45
+
46
+ ## Independent Audit Regression Evidence
47
+
48
+ - `runx upgrade` now exposes and executes `--version`, `--arch`, `--variant`,
49
+ `--dry-run`, and `--format` without root-version interception while retaining
50
+ `upgrade check` and `upgrade list`.
51
+ - A valid `newVersionAvailable: true` cache produces the required notice before
52
+ the no-argument banner with the update worker disabled.
53
+ - `agent prompt list --names` prints `guiho-i-runx` as a raw text line; JSON
54
+ mode still returns a parseable names array.
55
+ - The stale ignored `bin/runx.exe` created by the single-target build was
56
+ removed before matrix verification. The verifier itself remains strict and
57
+ observed only the twelve RFC binaries plus the two named agent assets.
58
+
59
+ ## Exact Release Asset Evidence
60
+
61
+ The verifier observed twelve `runx-*` assets using Linux, Darwin, and Windows
62
+ names plus `guiho-s-runx` and `guiho-i-runx`. It found no duplicate, extra,
63
+ missing, or legacy platform name.
64
+
65
+ ## Skipped Checks
66
+
67
+ - No npm publication.
68
+ - No GitHub Release creation.
69
+ - No live global RunX replacement or global agent installation.
70
+ - No production deployment.
71
+
72
+ These are release mutations rather than local validation requirements.
73
+
74
+ ## Readiness
75
+
76
+ Ready for the authorized Mirror patch application to `0.4.1`, one-file commits,
77
+ main push, and Mirror-managed tag/ref push. Package publication and GitHub
78
+ Release creation remain intentionally unperformed as direct local actions.
79
+
80
+ ## References
81
+
82
+ - [Implementation review](../reviews/implementation/rfc-0034-cli-compliance-migration-review.md)
83
+ - [Implementation notes](../todo/rfc-0034-cli-compliance-migration-implementation.md)
@@ -0,0 +1,124 @@
1
+ ---
2
+ name: RunX Upgrade Reliability Validation
3
+ purpose: Record release-ready verification evidence for GitHub issues 12 and 13.
4
+ description: Results for release pagination, progress reporting, transactional replacement, rollback, recovery commands, direct installers, native builds, live release smokes, and XDocs integrity.
5
+ created: 2026-07-15
6
+ flags:
7
+ - superseded
8
+ - needs-revalidation
9
+ tags:
10
+ - validation
11
+ - cli
12
+ - reliability
13
+ keywords:
14
+ - runx upgrade
15
+ - upgrade list
16
+ - windows replacement
17
+ - recovery install
18
+ - issue 12
19
+ - issue 13
20
+ owner: runx-validation
21
+ ---
22
+
23
+ # RunX Upgrade Reliability Validation
24
+
25
+ ## Current Status
26
+
27
+ The first validation pass below is superseded by independent review findings.
28
+ The implementation has since been corrected for exact JSON envelope fidelity,
29
+ post-backup rename/rollback state, downgrade prevention, installer failure
30
+ classification, Ubuntu portability, and executable controlled installer tests.
31
+ Candidate verification now has a bounded ten-second timeout in the CLI and both
32
+ direct installers. Those corrections still require the complete release gate
33
+ to be rerun before this document or the TODO task can return to
34
+ `validated`/`completed`.
35
+
36
+ No package publication, version apply, or tag operation was performed.
37
+
38
+ ## Superseded Automated Gate
39
+
40
+ | Command | Result |
41
+ | --- | --- |
42
+ | `bun run typecheck` | Passed. |
43
+ | `bun test` | Passed: 37 tests, 0 failures, 245 assertions across 8 files. |
44
+ | `bun run build` | Passed; TypeScript library output compiled. |
45
+ | `bun run binary` | Passed; local native executable compiled. |
46
+ | `bun run binaries` | Passed; all 12 Linux, macOS, and Windows release assets compiled and were non-empty. |
47
+ | `bun test devops/installers.spec.ts` | Superseded: the earlier suite relied partly on source-pattern checks. The replacement suite executes controlled native installer and recovery scenarios and awaits revalidation. |
48
+
49
+ Generated `library/` and `bin/` outputs remain ignored and are not part of the
50
+ committed change.
51
+
52
+ ## Superseded Behavior Evidence
53
+
54
+ - Release-catalog tests follow `Link: rel="next"`, reject malformed/non-2xx
55
+ responses, apply SemVer prerelease precedence, retain invalid tags last, and
56
+ enforce baseline/default/modern asset candidates.
57
+ - Reporting tests prove the complete plan precedes `Downloading`, which
58
+ precedes the download body and then `Validating`, `Replacing`, and
59
+ `Verifying`.
60
+ - The Windows test runs a copied executable, keeps it mapped in a live process,
61
+ renames it, installs the new canonical executable immediately, verifies the
62
+ exact version, and allows only old-image cleanup to be deferred.
63
+ - Failure tests reject non-native downloads before mutation and restore the
64
+ original executable after target verification failure.
65
+ - Bun-launcher failure returns a recovery command pinned to the resolved target
66
+ instead of losing recovery at the generic CLI error boundary.
67
+ - Installer tests enforce unique temporary paths, exact target versions,
68
+ canonical verification, rollback language/behavior, and separate stop
69
+ commands.
70
+
71
+ ## Superseded Compiled Binary Smoke
72
+
73
+ The compiled `runx-windows-x64-baseline.exe` reported version `0.2.7`.
74
+ `upgrade --dry-run` queried live GitHub release metadata and printed the full
75
+ plan before any mutation, followed by the pinned `0.2.7` PowerShell recovery
76
+ command and the separate safe stop command. `upgrade list --format json`
77
+ returned one valid schema-versioned document containing all eight currently
78
+ published releases from `0.2.7` through `0.2.0`, newest first, with current,
79
+ latest-stable, publication, channel, and compatible-asset data.
80
+
81
+ The first smoke command targeted `bin/runx.exe` after the complete matrix build
82
+ had replaced the local single-binary output with named assets. It failed only
83
+ because that path no longer existed; the smoke was immediately rerun against
84
+ the actual baseline matrix asset and passed.
85
+
86
+ ## Superseded XDocs Gate
87
+
88
+ Using an equivalent validation-only XDocs configuration with agent file writes
89
+ disabled:
90
+
91
+ - strict metadata passed for `docs/plans`, `docs/reviews/plans`, `docs/todo`,
92
+ `source`, `devops`, and `skills/guiho-s-runx`;
93
+ - `xdocs doctor --warnings-as-errors --format json` returned `valid: true`,
94
+ zero errors, and zero warnings; and
95
+ - `xdocs tree` returned one connected RunX tree without duplicate subjects or
96
+ orphans.
97
+
98
+ ## Release Boundary
99
+
100
+ The branch preserves package version `0.2.7`. A future merge/release owner must
101
+ use Mirror to plan and apply any requested patch release; this implementation
102
+ does not publish or tag automatically.
103
+
104
+ ## Required Revalidation
105
+
106
+ - `bun run typecheck`
107
+ - `bun test`, including the controlled installer/recovery suite on Ubuntu and Windows
108
+ - `bun run build`, `bun run binary`, and `bun run binaries`
109
+ - compiled CLI text/JSON smokes, including failed and rolled-back envelopes
110
+ - strict XDocs metadata, doctor warnings-as-errors, and tree validation
111
+
112
+ The current isolated Windows worktree could not begin that rerun because
113
+ `bun install --frozen-lockfile` was denied while opening `bun.lock` with
114
+ `EPERM`. This is an environment validation blocker, not a passing result.
115
+
116
+ ## Review-Correction Checks
117
+
118
+ | Command | Result |
119
+ | --- | --- |
120
+ | Cached TypeScript 6 compiler, `-p . --noEmit` | Passed after the review corrections. |
121
+ | PowerShell parser for `devops/install.ps1` | Passed. |
122
+ | Git Bash `bash -n devops/install.sh` | Passed. |
123
+ | `git diff --check` | Passed. |
124
+ | Focused Bun tests | Blocked before test execution by `EPERM` reading the isolated worktree and `tsconfig.json`; zero tests passed in that attempt. |
@@ -8,12 +8,16 @@ files:
8
8
  citty-cli-migration.md: Records the complete local validation gate for the Citty command-tree migration.
9
9
  interactive-init-manifest.md: Records validation evidence for the interactive initializer and strict manifest contract.
10
10
  windows-self-upgrade.md: Records Windows replacement, rollback, cleanup, native build, CI, and XDocs validation evidence.
11
+ upgrade-reliability.md: Tracks the superseded first pass and required revalidation after independent upgrade reliability review corrections.
12
+ rfc-0034-cli-compliance-migration.md: Records passing RFC tests, live upgrade/startup/prompt regressions, builds, bootstrap, installers, import scan, and fourteen-asset evidence.
11
13
  documents:
12
14
  alpha-implementation-summary.md: Validation summary for the first RunX implementation.
13
15
  citty-cli-migration.md: Validation evidence for TypeScript, tests, native assets, npm packaging, CLI behavior, and XDocs.
14
16
  interactive-init-manifest.md: Validation evidence for the RunX interactive init manifest feature.
15
17
  npm-trusted-publishing-0.2.2.md: Validation evidence for the blocked 0.2.2 npm trusted-publishing retry.
16
18
  windows-self-upgrade.md: Validation evidence for GitHub issues #9 and #1 and the Windows self-upgrade patch.
19
+ upgrade-reliability.md: Revalidation record for GitHub issues 12 and 13; currently marked needs-revalidation.
20
+ rfc-0034-cli-compliance-migration.md: Complete RFC 0034 correction validation and patch-release readiness report.
17
21
  tags:
18
22
  - validation
19
23
  keywords:
@@ -24,6 +28,7 @@ keywords:
24
28
  - tests
25
29
  - summary
26
30
  - windows self-upgrade
31
+ - upgrade reliability
27
32
  flags: []
28
33
  status: stable
29
34
  ---
@@ -1,11 +1,36 @@
1
- import type { AgentScope, AgentTool } from './types.js';
1
+ /**
2
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
3
+ */
4
+ import type { AgentScope } from './types.js';
5
+ export { applyAgentInstructions, installAgentSkill, listAgentPrompts, listAgentSkills, removeAgentInstructions, showAgentInstructions, showAgentPrompt, showAgentSkill, uninstallAgentSkill, updateAgentInstructions, updateAgentSkill, };
2
6
  type EmbeddedResources = {
3
7
  skill: string;
8
+ prompt: string;
4
9
  } | undefined;
5
10
  declare global {
6
11
  var __RUNX_EMBEDDED_RESOURCES__: EmbeddedResources;
7
12
  }
8
- export declare const installAgentSkill: (scope: AgentScope, tool: AgentTool, cwd: string) => Promise<string[]>;
9
- export declare const installAgentInstructions: (cwd: string) => Promise<string>;
10
- export {};
13
+ declare function installAgentSkill(scope: AgentScope, cwd: string): Promise<string[]>;
14
+ declare function updateAgentSkill(scope: AgentScope, cwd: string): Promise<string[]>;
15
+ declare function uninstallAgentSkill(scope: AgentScope, cwd: string): Promise<string[]>;
16
+ declare function listAgentSkills(filter?: string): Array<{
17
+ id: string;
18
+ description: string;
19
+ }>;
20
+ declare function showAgentSkill(id: string): Promise<{
21
+ id: string;
22
+ path: string;
23
+ description: string;
24
+ metadata: Record<string, string>;
25
+ }>;
26
+ declare function applyAgentInstructions(cwd: string): Promise<string[]>;
27
+ declare function updateAgentInstructions(cwd: string): Promise<string[]>;
28
+ declare function removeAgentInstructions(cwd: string): Promise<string[]>;
29
+ declare function showAgentInstructions(): Promise<string>;
30
+ declare function listAgentPrompts(namesOnly: true): string[];
31
+ declare function listAgentPrompts(namesOnly?: false): Array<{
32
+ id: string;
33
+ description: string;
34
+ }>;
35
+ declare function showAgentPrompt(id: string): Promise<string>;
11
36
  //# sourceMappingURL=agents.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAGvD,KAAK,iBAAiB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAA;AAEtD,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,2BAA2B,EAAE,iBAAiB,CAAA;CACnD;AAKD,eAAO,MAAM,iBAAiB,UAAiB,UAAU,QAAQ,SAAS,OAAO,MAAM,KAAG,OAAO,CAAC,MAAM,EAAE,CAiBzG,CAAA;AAED,eAAO,MAAM,wBAAwB,QAAe,MAAM,KAAG,OAAO,CAAC,MAAM,CAgB1E,CAAA"}
1
+ {"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,uBAAuB,EACvB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,GACjB,CAAA;AAED,KAAK,iBAAiB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAA;AAEtE,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,2BAA2B,EAAE,iBAAiB,CAAA;CACnD;AAOD,iBAAe,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAElF;AAED,iBAAe,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEjF;AAED,iBAAe,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAIpF;AAED,iBAAS,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAIpF;AAED,iBAAe,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC,CAQtI;AAED,iBAAe,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEpE;AAED,iBAAe,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAErE;AAED,iBAAe,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAYrE;AAED,iBAAe,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC,CAEtD;AAED,iBAAS,gBAAgB,CAAC,SAAS,EAAE,IAAI,GAAG,MAAM,EAAE,CAAA;AACpD,iBAAS,gBAAgB,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAOxF,iBAAe,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1D"}