@guiho/runx 0.2.5 → 0.2.7
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 +31 -0
- package/DOCS.md +31 -9
- package/README.md +22 -3
- package/docs/decisions/decisions.xdocs.md +7 -0
- package/docs/decisions/interactive-init-manifest.md +187 -0
- package/docs/decisions/windows-self-upgrade.md +98 -0
- package/docs/plans/interactive-init-manifest.md +177 -0
- package/docs/plans/plans.xdocs.md +7 -0
- package/docs/plans/windows-self-upgrade.md +129 -0
- package/docs/reviews/implementation/implementation.xdocs.md +7 -0
- package/docs/reviews/implementation/interactive-init-manifest-review.md +69 -0
- package/docs/reviews/implementation/windows-self-upgrade-review.md +79 -0
- package/docs/reviews/plans/interactive-init-manifest-review.md +82 -0
- package/docs/reviews/plans/plans.xdocs.md +7 -0
- package/docs/reviews/plans/windows-self-upgrade-review.md +71 -0
- package/docs/validation/interactive-init-manifest.md +79 -0
- package/docs/validation/validation.xdocs.md +7 -0
- package/docs/validation/windows-self-upgrade.md +85 -0
- package/library/cli.d.ts.map +1 -1
- package/library/cli.js +18 -0
- package/library/help.d.ts.map +1 -1
- package/library/help.js +4 -0
- package/library/init.d.ts +37 -0
- package/library/init.d.ts.map +1 -0
- package/library/init.js +165 -0
- package/library/manifest.d.ts +4 -1
- package/library/manifest.d.ts.map +1 -1
- package/library/manifest.js +15 -2
- package/library/self-management.d.ts +5 -4
- package/library/self-management.d.ts.map +1 -1
- package/library/self-management.js +66 -9
- package/package.json +1 -1
|
@@ -6,20 +6,27 @@ children: []
|
|
|
6
6
|
files:
|
|
7
7
|
alpha-implementation.md: Breaks the accepted alpha into implementation and validation units.
|
|
8
8
|
citty-cli-migration.md: Executes the full Citty command-tree migration, compatibility validation, protected delivery, and patch release.
|
|
9
|
+
interactive-init-manifest.md: Sequences the SemVer manifest, public group, scripts directory, and interactive initializer delivery.
|
|
9
10
|
mirror-automatic-push.md: Enables automatic Mirror release pushes with a synchronized protected-main safety gate.
|
|
10
11
|
npm-trusted-publishing-release.md: Sequences workflow implementation, protected delivery, Mirror patching, and public trusted-publishing verification.
|
|
12
|
+
windows-self-upgrade.md: Sequences synchronous Windows replacement, rollback coverage, validation, issue closure, and patch delivery.
|
|
11
13
|
documents:
|
|
12
14
|
alpha-implementation.md: Plan used for the initial RunX implementation.
|
|
13
15
|
citty-cli-migration.md: Active plan for replacing handwritten CLI parsing and routing with Citty and delivering its patch release.
|
|
16
|
+
interactive-init-manifest.md: Approved implementation plan for the RunX interactive init manifest feature.
|
|
14
17
|
mirror-automatic-push.md: Approved plan for configuring, validating, and merging Mirror push=true without applying another release.
|
|
15
18
|
npm-trusted-publishing-release.md: Approved executable plan for the RunX 0.2.1 trusted-publishing release trial.
|
|
19
|
+
windows-self-upgrade.md: Approved executable plan for fixing Windows native self-upgrade and delivering its patch.
|
|
16
20
|
tags:
|
|
17
21
|
- plans
|
|
18
22
|
keywords:
|
|
19
23
|
- runx
|
|
20
24
|
- implementation
|
|
21
25
|
- citty
|
|
26
|
+
- runx init
|
|
27
|
+
- scripts directory
|
|
22
28
|
- mirror push
|
|
29
|
+
- windows self-upgrade
|
|
23
30
|
flags: []
|
|
24
31
|
status: stable
|
|
25
32
|
---
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: RunX Windows Self-Upgrade Plan
|
|
3
|
+
purpose: Execute the accepted synchronous and recoverable Windows self-upgrade design.
|
|
4
|
+
description: Sequences executable replacement, regression coverage, documentation, validation, issue closure, and the next Mirror patch.
|
|
5
|
+
created: 2026-07-14
|
|
6
|
+
flags:
|
|
7
|
+
- approved
|
|
8
|
+
- executed
|
|
9
|
+
tags:
|
|
10
|
+
- plans
|
|
11
|
+
- cli
|
|
12
|
+
- windows
|
|
13
|
+
keywords:
|
|
14
|
+
- runx upgrade
|
|
15
|
+
- executable replacement
|
|
16
|
+
- rollback
|
|
17
|
+
- patch release
|
|
18
|
+
owner: runx-plans
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
# RunX Windows Self-Upgrade Plan
|
|
22
|
+
|
|
23
|
+
## Sources
|
|
24
|
+
|
|
25
|
+
- [Windows Self-Upgrade Decision](../decisions/windows-self-upgrade.md)
|
|
26
|
+
- [Alpha Command Catalog Requirements](../requirements/alpha-command-catalog.md)
|
|
27
|
+
- [CLI Architecture](../architecture/cli-architecture.md)
|
|
28
|
+
- GitHub issues `CGuiho/runx#9` and `CGuiho/runx#1`
|
|
29
|
+
|
|
30
|
+
## Unit 1: Replace the Windows Executable Synchronously
|
|
31
|
+
|
|
32
|
+
- Goal: Make `upgradeSelf()` return successfully only after the canonical
|
|
33
|
+
Windows executable path contains and runs the target release.
|
|
34
|
+
- Owner: `C:\GUIHO\runx`.
|
|
35
|
+
- Dependencies: Accepted Windows self-upgrade decision.
|
|
36
|
+
- Files:
|
|
37
|
+
- `source/self-management.ts`
|
|
38
|
+
- `source/types.ts` only if the result contract must change
|
|
39
|
+
- Behavior:
|
|
40
|
+
- Download to `.new`, rename the installed executable to `.old`, install the
|
|
41
|
+
new file at the original path, and verify `<self-path> --version`.
|
|
42
|
+
- Return `scheduled: false` after verified replacement.
|
|
43
|
+
- On failure, remove the failed target, restore `.old`, remove `.new`, and
|
|
44
|
+
return a non-zero `RunXError` with recovery context.
|
|
45
|
+
- Delete `.old` immediately when possible; defer only deletion of the locked
|
|
46
|
+
old image after the current process exits.
|
|
47
|
+
- Data/schema, auth, permissions, and cache: No application data, schema,
|
|
48
|
+
authentication, authorization, or cache impact. Filesystem write permission
|
|
49
|
+
to the installed executable remains required.
|
|
50
|
+
- Acceptance: The installed path is the verified target before
|
|
51
|
+
`upgradeSelf()` resolves and no `.new` file remains.
|
|
52
|
+
- Stop conditions: Stop if Windows cannot rename the running executable, the
|
|
53
|
+
target cannot be verified, rollback cannot restore the installed path, or
|
|
54
|
+
unrelated self-management behavior changes.
|
|
55
|
+
|
|
56
|
+
## Unit 2: Add Regression Coverage
|
|
57
|
+
|
|
58
|
+
- Goal: Prove the fixed upgrade contract and preserve the already-correct help
|
|
59
|
+
behavior from issue #1.
|
|
60
|
+
- Dependencies: Unit 1 complete.
|
|
61
|
+
- Files:
|
|
62
|
+
- `source/guiho-runx.spec.ts` or a focused colocated self-management spec
|
|
63
|
+
- existing `source/cli.spec.ts` only if help coverage needs correction
|
|
64
|
+
- Checks:
|
|
65
|
+
- Mock the GitHub latest-release response and downloaded Windows binary.
|
|
66
|
+
- Configure `RUNX_SELF_PATH` to an isolated executable path.
|
|
67
|
+
- Assert the replacement exists at that path before the promise resolves,
|
|
68
|
+
reports `scheduled: false`, runs as the expected version, and leaves no
|
|
69
|
+
`.new` file.
|
|
70
|
+
- Force verification failure and assert restoration of the original file.
|
|
71
|
+
- Run the existing `-h`/`--help` tests outside a manifest directory.
|
|
72
|
+
- Acceptance: Windows CI exercises success and rollback; issue #1 remains
|
|
73
|
+
covered without changing its implemented behavior.
|
|
74
|
+
- Stop conditions: Stop on nondeterministic process cleanup, leaked test
|
|
75
|
+
processes, platform-dependent assertions on non-Windows runners, or failure
|
|
76
|
+
to restore global fetch/environment state.
|
|
77
|
+
|
|
78
|
+
## Unit 3: Align Documentation and Validate
|
|
79
|
+
|
|
80
|
+
- Goal: Make public and structured documentation describe completed rather than
|
|
81
|
+
scheduled Windows replacement, then pass the full release gate.
|
|
82
|
+
- Dependencies: Units 1 and 2 complete.
|
|
83
|
+
- Files:
|
|
84
|
+
- `DOCS.md`
|
|
85
|
+
- `source/source.xdocs.md`
|
|
86
|
+
- `runx.xdocs.md`
|
|
87
|
+
- accepted decision and plan lifecycle flags when implementation completes
|
|
88
|
+
- Checks:
|
|
89
|
+
- `bun run typecheck`
|
|
90
|
+
- `bun test`
|
|
91
|
+
- `bun run build`
|
|
92
|
+
- `bun run binary`
|
|
93
|
+
- `bun run binaries`
|
|
94
|
+
- `xdocs meta . --documents --strict --owner runx --format json`
|
|
95
|
+
- `xdocs doctor . --warnings-as-errors --format json`
|
|
96
|
+
- `git diff --check`
|
|
97
|
+
- Acceptance: All checks pass, docs agree with behavior, and the worktree
|
|
98
|
+
contains only understood task changes.
|
|
99
|
+
- Stop conditions: Stop on any failed validation or unexpected worktree change.
|
|
100
|
+
|
|
101
|
+
## Unit 4: Close Issues and Apply the Patch
|
|
102
|
+
|
|
103
|
+
- Goal: Close both resolved GitHub issues and publish the next
|
|
104
|
+
Mirror-managed patch state.
|
|
105
|
+
- Dependencies: Unit 3 committed and the worktree clean.
|
|
106
|
+
- Sequence:
|
|
107
|
+
- Confirm issue #9 acceptance evidence and issue #1 Citty regression evidence.
|
|
108
|
+
- Close issues #9 and #1 with concise resolution comments.
|
|
109
|
+
- Run `mirror config show` and `mirror version plan patch`.
|
|
110
|
+
- Update the configured changelog with the planned next version and commit
|
|
111
|
+
release preparation.
|
|
112
|
+
- Run the full typecheck/test gate again if release preparation changes any
|
|
113
|
+
executable inputs.
|
|
114
|
+
- Apply `mirror version apply patch --yes`; allow configured commit/push/tag
|
|
115
|
+
behavior and do not hand-edit Mirror-managed fields.
|
|
116
|
+
- Acceptance: Both issues are closed, the changelog records the fix, and
|
|
117
|
+
package version, release commit, tag, and configured remote push agree.
|
|
118
|
+
- Stop conditions: Stop if an issue acceptance criterion is unproved, Mirror
|
|
119
|
+
plans an unexpected version, validation fails, or protected push is rejected.
|
|
120
|
+
|
|
121
|
+
## TODO Alignment
|
|
122
|
+
|
|
123
|
+
This is one approved, focused execution session. No additional durable TODO
|
|
124
|
+
entry or delegated component task is required.
|
|
125
|
+
|
|
126
|
+
## First Executable Unit
|
|
127
|
+
|
|
128
|
+
Unit 1: implement synchronous Windows replacement and rollback in
|
|
129
|
+
`source/self-management.ts`.
|
|
@@ -5,15 +5,22 @@ parent: runx-reviews
|
|
|
5
5
|
children: []
|
|
6
6
|
files:
|
|
7
7
|
citty-cli-migration-review.md: Reviews the implemented Citty command tree, compatibility adapter, tests, documentation, packaging, and release readiness.
|
|
8
|
+
interactive-init-manifest-review.md: Reviews the implemented RunX initializer, strict manifest contract, tests, documentation, and delivery readiness.
|
|
9
|
+
windows-self-upgrade-review.md: Reviews synchronous Windows replacement, rollback, cleanup, tests, CI coverage, and release readiness.
|
|
8
10
|
documents:
|
|
9
11
|
citty-cli-migration-review.md: Accepted implementation review for the full Citty CLI migration.
|
|
12
|
+
interactive-init-manifest-review.md: Accepted implementation review for the RunX interactive init manifest feature.
|
|
13
|
+
windows-self-upgrade-review.md: Accepted implementation review for the Windows native self-upgrade fix.
|
|
10
14
|
tags:
|
|
11
15
|
- reviews
|
|
12
16
|
- implementation
|
|
13
17
|
keywords:
|
|
14
18
|
- runx
|
|
15
19
|
- citty
|
|
20
|
+
- runx init
|
|
21
|
+
- scripts directory
|
|
16
22
|
- implementation review
|
|
23
|
+
- windows self-upgrade
|
|
17
24
|
flags: []
|
|
18
25
|
status: stable
|
|
19
26
|
---
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: RunX Interactive Init Manifest Implementation Review
|
|
3
|
+
purpose: Assess the delivered RunX initializer and manifest contract against the accepted decision and plan.
|
|
4
|
+
description: Reviews Citty routing, strict SemVer and group validation, terminal safety, tests, documentation, and delivery boundaries.
|
|
5
|
+
created: 2026-07-14
|
|
6
|
+
flags:
|
|
7
|
+
- accepted
|
|
8
|
+
tags:
|
|
9
|
+
- reviews
|
|
10
|
+
- implementation
|
|
11
|
+
- cli
|
|
12
|
+
keywords:
|
|
13
|
+
- runx init
|
|
14
|
+
- runx.yaml
|
|
15
|
+
- semantic versioning
|
|
16
|
+
- public group
|
|
17
|
+
- scripts directory
|
|
18
|
+
owner: runx-implementation-reviews
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
# RunX Interactive Init Manifest Implementation Review
|
|
22
|
+
|
|
23
|
+
## Verdict
|
|
24
|
+
|
|
25
|
+
Accepted. No blocking, high, medium, or low findings remain.
|
|
26
|
+
|
|
27
|
+
## Acceptance Criteria Check
|
|
28
|
+
|
|
29
|
+
- `runx init` is a first-class Citty command, appears in the home/help tree,
|
|
30
|
+
and is reserved from selector shorthand.
|
|
31
|
+
- The manifest accepts Semantic Versioning `1.x` strings, requires an in-root
|
|
32
|
+
`scripts.directory` and `public` group, and permits `commands: []` while
|
|
33
|
+
retaining strict command-group validation.
|
|
34
|
+
- The initializer uses a guided terminal adapter with project and scripts
|
|
35
|
+
prompts, an exact YAML preview, confirmation, overwrite confirmation, and
|
|
36
|
+
cancellation behavior. It writes only `runx.yaml`, not `scripts/`.
|
|
37
|
+
- Writes use a same-directory temporary file, validate the temporary manifest,
|
|
38
|
+
then rename it into place. No configured command is read for execution or
|
|
39
|
+
spawned by this path.
|
|
40
|
+
- `--file` and `--format json` fail explicitly for `init`; `--cwd` selects the
|
|
41
|
+
target directory.
|
|
42
|
+
- The README, canonical documentation, source XDocs metadata, and package
|
|
43
|
+
metadata align with the implementation. The bundled agent skill is unchanged
|
|
44
|
+
by design; the separate agent-integration follow-up remains issue #11.
|
|
45
|
+
|
|
46
|
+
## Verification Evidence
|
|
47
|
+
|
|
48
|
+
- `bun run typecheck` passed.
|
|
49
|
+
- `bun test` passed: 22 tests and 180 assertions, including initialization,
|
|
50
|
+
cancellation, overwrite, empty-catalog list/check, and non-interactive CLI
|
|
51
|
+
coverage.
|
|
52
|
+
- `bun run build` and `bun run binary` passed.
|
|
53
|
+
- The compiled `bin/runx.exe --help-tree` includes `init`.
|
|
54
|
+
- XDocs strict metadata checks for `source`, plans, and plan reviews passed;
|
|
55
|
+
the XDocs tree is intact.
|
|
56
|
+
|
|
57
|
+
## Residual Risk
|
|
58
|
+
|
|
59
|
+
The automated environment has no interactive TTY, so the live terminal frame
|
|
60
|
+
was exercised through the injected prompt contract rather than a human session.
|
|
61
|
+
The native binary build and its command-tree smoke check confirm that the
|
|
62
|
+
initializer is included in the compiled executable.
|
|
63
|
+
|
|
64
|
+
## References
|
|
65
|
+
|
|
66
|
+
- [Decision](../../decisions/interactive-init-manifest.md)
|
|
67
|
+
- [Plan](../../plans/interactive-init-manifest.md)
|
|
68
|
+
- [Plan Review](../plans/interactive-init-manifest-review.md)
|
|
69
|
+
- GitHub issues [#10](https://github.com/CGuiho/runx/issues/10) and [#11](https://github.com/CGuiho/runx/issues/11)
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: RunX Windows Self-Upgrade Implementation Review
|
|
3
|
+
purpose: Review the implemented Windows self-upgrade fix against its accepted decision and plan.
|
|
4
|
+
description: Confirms synchronous replacement, target verification, rollback, cleanup, tests, CI coverage, documentation, and release readiness.
|
|
5
|
+
created: 2026-07-14
|
|
6
|
+
flags:
|
|
7
|
+
- accepted
|
|
8
|
+
tags:
|
|
9
|
+
- reviews
|
|
10
|
+
- implementation
|
|
11
|
+
- windows
|
|
12
|
+
keywords:
|
|
13
|
+
- runx upgrade
|
|
14
|
+
- executable replacement
|
|
15
|
+
- rollback
|
|
16
|
+
- windows ci
|
|
17
|
+
owner: runx-implementation-reviews
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
# RunX Windows Self-Upgrade Implementation Review
|
|
21
|
+
|
|
22
|
+
## Verdict
|
|
23
|
+
|
|
24
|
+
Accepted. No blocker, high, medium, or low findings remain.
|
|
25
|
+
|
|
26
|
+
## Findings
|
|
27
|
+
|
|
28
|
+
No actionable findings. The implementation matches the approved synchronous
|
|
29
|
+
replacement and recovery design without changing manifest execution, Citty
|
|
30
|
+
routing, uninstall behavior, or non-Windows upgrade behavior.
|
|
31
|
+
|
|
32
|
+
## Acceptance Criteria
|
|
33
|
+
|
|
34
|
+
- `upgradeSelf()` renames the running Windows executable, installs the
|
|
35
|
+
downloaded target at the canonical path, and awaits `<path> --version`.
|
|
36
|
+
- Successful Windows upgrade results report `scheduled: false`.
|
|
37
|
+
- Verification failures remove the invalid replacement and restore `.old`.
|
|
38
|
+
- `.new` is absent after success and rollback.
|
|
39
|
+
- Cleanup retries deletion of the locked `.old` image after the old process
|
|
40
|
+
releases it.
|
|
41
|
+
- A Windows-only test holds a real copied executable open during replacement,
|
|
42
|
+
verifies the new binary at the canonical path before completion, and observes
|
|
43
|
+
backup cleanup.
|
|
44
|
+
- A second Windows test proves rollback after invalid-binary verification.
|
|
45
|
+
- Existing Citty tests continue to prove `-h` and `--help` outside a manifest.
|
|
46
|
+
- The GitHub workflow now runs typecheck, tests, build, and native compilation
|
|
47
|
+
on `windows-latest` in addition to the existing Linux release-matrix gate.
|
|
48
|
+
|
|
49
|
+
## Verification Evidence
|
|
50
|
+
|
|
51
|
+
- `bun run typecheck`: passed.
|
|
52
|
+
- `bun test`: 15 passed, 0 failed, 134 assertions.
|
|
53
|
+
- `bun run build`: passed.
|
|
54
|
+
- `bun run binary`: passed.
|
|
55
|
+
- `bun run binaries`: twelve native assets built and verified.
|
|
56
|
+
- Windows x64 native `-h` outside a manifest: passed.
|
|
57
|
+
- Windows x64 native `--version`: reported `0.2.5` before the release bump.
|
|
58
|
+
- CI workflow YAML parse: passed.
|
|
59
|
+
- `xdocs doctor . --warnings-as-errors --format json`: 0 errors, 0 warnings.
|
|
60
|
+
- `git diff --check`: passed.
|
|
61
|
+
|
|
62
|
+
## Documentation and TODO
|
|
63
|
+
|
|
64
|
+
`DOCS.md`, source/root/workflow XDocs descriptors, the accepted decision, plan,
|
|
65
|
+
plan review, this implementation review, and validation evidence are aligned.
|
|
66
|
+
No TODO entry is needed for this completed single-session fix.
|
|
67
|
+
|
|
68
|
+
## Residual Risk
|
|
69
|
+
|
|
70
|
+
The new `windows-latest` job cannot execute until the committed workflow reaches
|
|
71
|
+
GitHub. Local Windows coverage exercises the same live-file replacement and
|
|
72
|
+
cleanup behavior. Public upgrade from 0.2.0 to the new patch can only be verified
|
|
73
|
+
after the patch release assets exist.
|
|
74
|
+
|
|
75
|
+
## References
|
|
76
|
+
|
|
77
|
+
- [Decision](../../decisions/windows-self-upgrade.md)
|
|
78
|
+
- [Plan](../../plans/windows-self-upgrade.md)
|
|
79
|
+
- [Plan Review](../plans/windows-self-upgrade-review.md)
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: RunX Interactive Init Manifest Plan Review
|
|
3
|
+
purpose: Verify that the interactive-init implementation plan is executable, safe, and traceable.
|
|
4
|
+
description: Reviews manifest constraints, terminal workflow boundaries, test coverage, XDocs work, and pull-request delivery for runx init.
|
|
5
|
+
created: 2026-07-14
|
|
6
|
+
flags:
|
|
7
|
+
- approved
|
|
8
|
+
tags:
|
|
9
|
+
- reviews
|
|
10
|
+
- plans
|
|
11
|
+
- cli
|
|
12
|
+
keywords:
|
|
13
|
+
- runx init
|
|
14
|
+
- runx.yaml
|
|
15
|
+
- semantic versioning
|
|
16
|
+
- public group
|
|
17
|
+
- scripts directory
|
|
18
|
+
owner: runx-plan-reviews
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
# RunX Interactive Init Manifest Plan Review
|
|
22
|
+
|
|
23
|
+
## Verdict
|
|
24
|
+
|
|
25
|
+
Ready for execution.
|
|
26
|
+
|
|
27
|
+
## Findings
|
|
28
|
+
|
|
29
|
+
No blocker, high, medium, or low findings remain.
|
|
30
|
+
|
|
31
|
+
The plan is traceable to the accepted interactive-init decision, the existing
|
|
32
|
+
command-catalog requirement, and the Citty CLI architecture. The only review
|
|
33
|
+
finding was resolved in the plan: `runx init` is an interactive terminal
|
|
34
|
+
workflow, so `--format json` and `--file` must fail clearly rather than create
|
|
35
|
+
ambiguous output or target files.
|
|
36
|
+
|
|
37
|
+
## Sequencing and Safety
|
|
38
|
+
|
|
39
|
+
- Manifest schema changes precede the initializer, so generated YAML is
|
|
40
|
+
validated by the same strict contract that later commands use.
|
|
41
|
+
- The initializer is isolated from the executor and is explicitly prohibited
|
|
42
|
+
from spawning configured manifest commands.
|
|
43
|
+
- The prompt boundary is injectable for tests; an interactive terminal is
|
|
44
|
+
required for the real user interface.
|
|
45
|
+
- Existing-file confirmation, cancellation, and atomic writes prevent silent
|
|
46
|
+
replacement and partial manifests.
|
|
47
|
+
- The `scripts` directory is configured but not created until a real script is
|
|
48
|
+
added, matching the accepted file-only initialization boundary.
|
|
49
|
+
- Manifest evolution is constrained to supported SemVer major `1`; no legacy
|
|
50
|
+
numeric compatibility or migration policy is hidden in the implementation.
|
|
51
|
+
|
|
52
|
+
## Coverage Review
|
|
53
|
+
|
|
54
|
+
- Tests cover SemVer, public-group, scripts-directory, empty-catalog, command
|
|
55
|
+
group-reference, creation, cancellation, overwrite, non-interactive, and
|
|
56
|
+
unsupported-option behavior.
|
|
57
|
+
- The full Bun typecheck, test, library build, local native compilation, XDocs
|
|
58
|
+
subtree validation, and diff hygiene are named.
|
|
59
|
+
- Native compilation of the terminal prompt dependency is an explicit stop
|
|
60
|
+
condition.
|
|
61
|
+
- No API, database, authentication, authorization, cache, cloud, secret,
|
|
62
|
+
deployment, release, tag, or package-publication work is in scope.
|
|
63
|
+
|
|
64
|
+
## Documentation and TODO Alignment
|
|
65
|
+
|
|
66
|
+
The plan updates public CLI documentation and the affected XDocs descriptors.
|
|
67
|
+
The bundled RunX agent skill is deliberately deferred to the separate
|
|
68
|
+
agent-integration feature tracked in issue #11, as directed by the project
|
|
69
|
+
owner. The work is one focused package session, so no additional long-running
|
|
70
|
+
TODO entry is required.
|
|
71
|
+
|
|
72
|
+
## First Executable Unit
|
|
73
|
+
|
|
74
|
+
Update `source/manifest.ts` and its tests/fixtures to establish the SemVer,
|
|
75
|
+
scripts-directory, mandatory-public-group, and empty-catalog contract.
|
|
76
|
+
|
|
77
|
+
## References
|
|
78
|
+
|
|
79
|
+
- [Plan](../../plans/interactive-init-manifest.md)
|
|
80
|
+
- [Decision](../../decisions/interactive-init-manifest.md)
|
|
81
|
+
- [Requirements](../../requirements/alpha-command-catalog.md)
|
|
82
|
+
- [CLI Architecture](../../architecture/cli-architecture.md)
|
|
@@ -5,12 +5,16 @@ parent: runx-reviews
|
|
|
5
5
|
children: []
|
|
6
6
|
files:
|
|
7
7
|
citty-cli-migration-review.md: Reviews completeness, compatibility, safety invariants, native packaging, and release sequencing for the Citty migration.
|
|
8
|
+
interactive-init-manifest-review.md: Reviews the RunX init manifest schema, terminal workflow, tests, XDocs, and pull-request delivery.
|
|
8
9
|
mirror-automatic-push-review.md: Reviews synchronized-main safeguards, read-only validation, protected delivery, and release side effects.
|
|
9
10
|
npm-trusted-publishing-release-review.md: Reviews sequencing, acceptance criteria, safety gates, and validation for the RunX 0.2.1 trusted-publishing plan.
|
|
11
|
+
windows-self-upgrade-review.md: Reviews synchronous replacement, rollback, regression coverage, issue closure, and patch delivery.
|
|
10
12
|
documents:
|
|
11
13
|
citty-cli-migration-review.md: Ready-for-execution review of the full Citty CLI migration plan.
|
|
14
|
+
interactive-init-manifest-review.md: Ready-for-execution review of the RunX interactive init manifest plan.
|
|
12
15
|
mirror-automatic-push-review.md: Ready-for-execution review of the Mirror automatic-push configuration plan.
|
|
13
16
|
npm-trusted-publishing-release-review.md: Ready-for-execution review of the npm trusted-publishing release plan.
|
|
17
|
+
windows-self-upgrade-review.md: Ready-for-execution review of the Windows native self-upgrade fix plan.
|
|
14
18
|
tags:
|
|
15
19
|
- reviews
|
|
16
20
|
- plans
|
|
@@ -18,8 +22,11 @@ keywords:
|
|
|
18
22
|
- runx
|
|
19
23
|
- plan review
|
|
20
24
|
- citty
|
|
25
|
+
- runx init
|
|
26
|
+
- scripts directory
|
|
21
27
|
- mirror push
|
|
22
28
|
- trusted publishing
|
|
29
|
+
- windows self-upgrade
|
|
23
30
|
flags: []
|
|
24
31
|
status: stable
|
|
25
32
|
---
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: RunX Windows Self-Upgrade Plan Review
|
|
3
|
+
purpose: Verify that the Windows self-upgrade plan is safe, complete, and executable.
|
|
4
|
+
description: Reviews replacement sequencing, rollback, tests, documentation, issue closure, and Mirror patch delivery.
|
|
5
|
+
created: 2026-07-14
|
|
6
|
+
flags:
|
|
7
|
+
- approved
|
|
8
|
+
tags:
|
|
9
|
+
- reviews
|
|
10
|
+
- plans
|
|
11
|
+
- windows
|
|
12
|
+
keywords:
|
|
13
|
+
- runx upgrade
|
|
14
|
+
- executable replacement
|
|
15
|
+
- rollback
|
|
16
|
+
- mirror patch
|
|
17
|
+
owner: runx-plan-reviews
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
# RunX Windows Self-Upgrade Plan Review
|
|
21
|
+
|
|
22
|
+
## Verdict
|
|
23
|
+
|
|
24
|
+
Ready for execution.
|
|
25
|
+
|
|
26
|
+
## Findings
|
|
27
|
+
|
|
28
|
+
No blocker, high, medium, or low findings remain. The plan traces to the accepted
|
|
29
|
+
Windows self-upgrade decision and existing native-upgrade requirement. Each unit
|
|
30
|
+
has a bounded outcome, named files, dependencies, acceptance criteria, checks,
|
|
31
|
+
and explicit stop conditions.
|
|
32
|
+
|
|
33
|
+
## Sequencing and Failure Safety
|
|
34
|
+
|
|
35
|
+
- Replacement precedes verification, and successful completion requires the
|
|
36
|
+
canonical path to execute the expected target version.
|
|
37
|
+
- Rollback occurs before any failure is surfaced after the old executable was
|
|
38
|
+
renamed.
|
|
39
|
+
- Deferred work is limited to deleting the locked old image; replacement itself
|
|
40
|
+
is complete before success.
|
|
41
|
+
- Issue closure and Mirror application follow implementation validation and a
|
|
42
|
+
clean committed worktree.
|
|
43
|
+
- The plan recognizes configured Mirror commit, push, and tag side effects and
|
|
44
|
+
stops on protected-push rejection.
|
|
45
|
+
|
|
46
|
+
## Coverage Review
|
|
47
|
+
|
|
48
|
+
- Success, failure, rollback, temporary-file cleanup, and platform isolation are
|
|
49
|
+
explicit.
|
|
50
|
+
- Existing `-h` coverage directly supports closing issue #1.
|
|
51
|
+
- Typecheck, unit tests, library build, local binary, the twelve-target matrix,
|
|
52
|
+
strict XDocs checks, and diff hygiene are included.
|
|
53
|
+
- No route, API, UI, data schema, authentication, authorization, cache, cloud,
|
|
54
|
+
secret, or database work is in scope.
|
|
55
|
+
|
|
56
|
+
## TODO and Documentation Alignment
|
|
57
|
+
|
|
58
|
+
The work is a single focused package session and does not need a long-running
|
|
59
|
+
TODO entry. Public `DOCS.md`, source/root XDocs descriptors, lifecycle records,
|
|
60
|
+
and the changelog are included in the correct sequence.
|
|
61
|
+
|
|
62
|
+
## First Executable Unit
|
|
63
|
+
|
|
64
|
+
Implement synchronous replacement, target-version verification, rollback, and
|
|
65
|
+
old-image cleanup in `source/self-management.ts`.
|
|
66
|
+
|
|
67
|
+
## References
|
|
68
|
+
|
|
69
|
+
- [Plan](../../plans/windows-self-upgrade.md)
|
|
70
|
+
- [Decision](../../decisions/windows-self-upgrade.md)
|
|
71
|
+
- [CLI Architecture](../../architecture/cli-architecture.md)
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: RunX Interactive Init Manifest Validation
|
|
3
|
+
purpose: Record executable verification evidence for the RunX initializer and strict manifest contract.
|
|
4
|
+
description: Captures typecheck, tests, library and native builds, compiled CLI smoke checks, and XDocs validation for runx init.
|
|
5
|
+
created: 2026-07-14
|
|
6
|
+
flags:
|
|
7
|
+
- passed
|
|
8
|
+
tags:
|
|
9
|
+
- validation
|
|
10
|
+
- cli
|
|
11
|
+
- manifest
|
|
12
|
+
keywords:
|
|
13
|
+
- runx init
|
|
14
|
+
- runx.yaml
|
|
15
|
+
- bun test
|
|
16
|
+
- native binary
|
|
17
|
+
- xdocs
|
|
18
|
+
owner: runx-validation
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
# RunX Interactive Init Manifest Validation
|
|
22
|
+
|
|
23
|
+
## Summary
|
|
24
|
+
|
|
25
|
+
The interactive initializer and strict manifest contract passed all applicable
|
|
26
|
+
local validation gates. No release, version, tag, package publication, cloud,
|
|
27
|
+
or secret operation was performed.
|
|
28
|
+
|
|
29
|
+
## Scope
|
|
30
|
+
|
|
31
|
+
- Citty registration and help surfaces for `runx init`.
|
|
32
|
+
- SemVer `1.x`, scripts-directory, `public` group, and empty-command manifest
|
|
33
|
+
validation.
|
|
34
|
+
- Prompt cancellation, overwrite confirmation, exact generated YAML, atomic
|
|
35
|
+
write validation, and non-interactive error behavior.
|
|
36
|
+
- User documentation and XDocs metadata.
|
|
37
|
+
|
|
38
|
+
## Commands Run
|
|
39
|
+
|
|
40
|
+
| Command | Result | Evidence |
|
|
41
|
+
| --- | --- | --- |
|
|
42
|
+
| `bun run typecheck` | Passed | Strict TypeScript compilation completed without diagnostics. |
|
|
43
|
+
| `bun test` | Passed | 22 tests and 180 assertions passed across CLI, manifest, initializer, and self-management suites. |
|
|
44
|
+
| `bun run build` | Passed | Library output compiled successfully. |
|
|
45
|
+
| `bun run binary` | Passed | Native Windows executable compiled to `bin/runx.exe`. |
|
|
46
|
+
| `bin/runx.exe --help-tree` | Passed | The compiled command tree includes `init`. |
|
|
47
|
+
| `xdocs meta source --strict --format json` | Passed | The new initializer and test files are fully described. |
|
|
48
|
+
| `xdocs meta docs\\plans --documents --strict --format json` | Passed | The plan and companion metadata validate. |
|
|
49
|
+
| `xdocs meta docs\\reviews\\plans --documents --strict --format json` | Passed | The plan review and companion metadata validate. |
|
|
50
|
+
| `xdocs tree` | Passed | The RunX documentation hierarchy is intact. |
|
|
51
|
+
| `git diff --check` | Passed | No whitespace errors were reported before delivery records were added. |
|
|
52
|
+
|
|
53
|
+
## Manual Checks
|
|
54
|
+
|
|
55
|
+
- The generated empty manifest has the required version, project, scripts,
|
|
56
|
+
`public` group, and `commands: []` shape.
|
|
57
|
+
- No empty `scripts/` directory is created by initialization.
|
|
58
|
+
- `runx init --file ...` and `runx init --format json` return explicit errors
|
|
59
|
+
without creating a manifest.
|
|
60
|
+
|
|
61
|
+
## Skipped Checks
|
|
62
|
+
|
|
63
|
+
A person-driven interactive terminal session could not be run in this automated
|
|
64
|
+
non-TTY environment. The initializer’s prompt sequence is covered through its
|
|
65
|
+
injected prompt adapter; the compiled executable was smoke-tested for command
|
|
66
|
+
registration.
|
|
67
|
+
|
|
68
|
+
## Readiness
|
|
69
|
+
|
|
70
|
+
Ready for code review and a draft pull request. The bundled agent-skill
|
|
71
|
+
automation remains intentionally outside this change and is tracked by issue
|
|
72
|
+
#11.
|
|
73
|
+
|
|
74
|
+
## References
|
|
75
|
+
|
|
76
|
+
- [Decision](../decisions/interactive-init-manifest.md)
|
|
77
|
+
- [Plan](../plans/interactive-init-manifest.md)
|
|
78
|
+
- [Implementation Review](../reviews/implementation/interactive-init-manifest-review.md)
|
|
79
|
+
- GitHub issue [#10](https://github.com/CGuiho/runx/issues/10)
|
|
@@ -6,17 +6,24 @@ children: []
|
|
|
6
6
|
files:
|
|
7
7
|
alpha-implementation-summary.md: Records the completed alpha implementation, checks, and release boundaries.
|
|
8
8
|
citty-cli-migration.md: Records the complete local validation gate for the Citty command-tree migration.
|
|
9
|
+
interactive-init-manifest.md: Records validation evidence for the interactive initializer and strict manifest contract.
|
|
10
|
+
windows-self-upgrade.md: Records Windows replacement, rollback, cleanup, native build, CI, and XDocs validation evidence.
|
|
9
11
|
documents:
|
|
10
12
|
alpha-implementation-summary.md: Validation summary for the first RunX implementation.
|
|
11
13
|
citty-cli-migration.md: Validation evidence for TypeScript, tests, native assets, npm packaging, CLI behavior, and XDocs.
|
|
14
|
+
interactive-init-manifest.md: Validation evidence for the RunX interactive init manifest feature.
|
|
12
15
|
npm-trusted-publishing-0.2.2.md: Validation evidence for the blocked 0.2.2 npm trusted-publishing retry.
|
|
16
|
+
windows-self-upgrade.md: Validation evidence for GitHub issues #9 and #1 and the Windows self-upgrade patch.
|
|
13
17
|
tags:
|
|
14
18
|
- validation
|
|
15
19
|
keywords:
|
|
16
20
|
- runx
|
|
17
21
|
- citty
|
|
22
|
+
- runx init
|
|
23
|
+
- scripts directory
|
|
18
24
|
- tests
|
|
19
25
|
- summary
|
|
26
|
+
- windows self-upgrade
|
|
20
27
|
flags: []
|
|
21
28
|
status: stable
|
|
22
29
|
---
|