@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.
- package/CHANGELOG.md +39 -0
- package/DOCS.md +127 -128
- package/README.md +56 -75
- package/devops/build-binaries.ts +44 -62
- package/devops/devops.xdocs.md +8 -5
- package/devops/install.ps1 +182 -152
- package/devops/install.sh +197 -262
- package/devops/installers.spec.ts +31 -0
- package/devops/verify-release-assets.ts +17 -0
- package/docs/docs.xdocs.md +3 -1
- package/docs/plans/plans.xdocs.md +7 -0
- package/docs/plans/rfc-0034-cli-compliance-migration.md +586 -0
- package/docs/plans/upgrade-reliability-implementation.md +95 -0
- package/docs/reviews/implementation/implementation.xdocs.md +2 -0
- package/docs/reviews/implementation/rfc-0034-cli-compliance-migration-review.md +69 -0
- package/docs/reviews/plans/plans.xdocs.md +6 -0
- package/docs/reviews/plans/rfc-0034-cli-compliance-migration-review.md +80 -0
- package/docs/reviews/plans/upgrade-reliability-implementation-review.md +65 -0
- package/docs/superpowers/specs/2026-07-15-upgrade-reliability-design.md +662 -0
- package/docs/superpowers/specs/specs.xdocs.md +24 -0
- package/docs/superpowers/superpowers.xdocs.md +21 -0
- package/docs/todo/rfc-0034-cli-compliance-migration-implementation.md +77 -0
- package/docs/todo/rfc-0034-cli-compliance-migration.md +152 -0
- package/docs/todo/todo.xdocs.md +6 -2
- package/docs/validation/rfc-0034-cli-compliance-migration.md +83 -0
- package/docs/validation/upgrade-reliability.md +124 -0
- package/docs/validation/validation.xdocs.md +5 -0
- package/library/agents.d.ts +29 -4
- package/library/agents.d.ts.map +1 -1
- package/library/agents.js +143 -41
- package/library/cli.d.ts.map +1 -1
- package/library/cli.js +311 -331
- package/library/configuration.d.ts +57 -0
- package/library/configuration.d.ts.map +1 -0
- package/library/configuration.js +111 -0
- package/library/embedded-resources.d.ts +6 -1
- package/library/embedded-resources.d.ts.map +1 -1
- package/library/embedded-resources.js +10 -4
- package/library/executor.d.ts +5 -1
- package/library/executor.d.ts.map +1 -1
- package/library/executor.js +10 -10
- package/library/help.d.ts +8 -4
- package/library/help.d.ts.map +1 -1
- package/library/help.js +70 -46
- package/library/init.d.ts +8 -27
- package/library/init.d.ts.map +1 -1
- package/library/init.js +37 -159
- package/library/manifest.d.ts +4 -43
- package/library/manifest.d.ts.map +1 -1
- package/library/manifest.js +4 -125
- package/library/path-utils.d.ts +13 -0
- package/library/path-utils.d.ts.map +1 -0
- package/library/path-utils.js +82 -0
- package/library/recovery.d.ts +7 -0
- package/library/recovery.d.ts.map +1 -0
- package/library/recovery.js +23 -0
- package/library/release-catalog.d.ts +32 -0
- package/library/release-catalog.d.ts.map +1 -0
- package/library/release-catalog.js +124 -0
- package/library/self-management.d.ts +24 -4
- package/library/self-management.d.ts.map +1 -1
- package/library/self-management.js +279 -99
- package/library/storage.d.ts +13 -0
- package/library/storage.d.ts.map +1 -0
- package/library/storage.js +38 -0
- package/library/types.d.ts +11 -16
- package/library/types.d.ts.map +1 -1
- package/library/types.js +3 -0
- package/library/update-cache.d.ts +21 -0
- package/library/update-cache.d.ts.map +1 -0
- package/library/update-cache.js +68 -0
- package/library/upgrade-reporting.d.ts +11 -0
- package/library/upgrade-reporting.d.ts.map +1 -0
- package/library/upgrade-reporting.js +67 -0
- package/library/upgrade-types.d.ts +72 -0
- package/library/upgrade-types.d.ts.map +1 -0
- package/library/upgrade-types.js +3 -0
- package/package.json +6 -3
- package/scripts/runx-bin.mjs +49 -0
- package/scripts/runx-bin.spec.ts +62 -0
- package/scripts/scripts.xdocs.md +3 -3
- package/skills/guiho-s-runx/SKILL.md +64 -59
- package/skills/guiho-s-runx/guiho-s-runx.xdocs.md +7 -4
- package/skills/skills.xdocs.md +1 -1
- package/docs/todo/implement-runx-alpha.md +0 -36
- 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)
|
package/docs/todo/todo.xdocs.md
CHANGED
|
@@ -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
|
---
|
package/library/agents.d.ts
CHANGED
|
@@ -1,11 +1,36 @@
|
|
|
1
|
-
|
|
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
|
-
|
|
9
|
-
|
|
10
|
-
|
|
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
|
package/library/agents.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"
|
|
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"}
|