@guiho/runx 0.2.5 → 0.2.7

package/docs/validation/windows-self-upgrade.md

@@ -0,0 +1,85 @@
+---
+name: RunX Windows Self-Upgrade Validation
+purpose: Record verification evidence for the Windows self-upgrade fix and issue closure.
+description: Captures Windows replacement and rollback tests, complete Bun build checks, native CLI checks, CI syntax, XDocs health, and residual release risk.
+created: 2026-07-14
+flags:
+  - validated
+tags:
+  - validation
+  - windows
+  - cli
+keywords:
+  - runx upgrade
+  - windows executable
+  - rollback
+  - issue 9
+  - issue 1
+owner: runx-validation
+---
+
+# RunX Windows Self-Upgrade Validation
+
+## Summary
+
+The implementation is ready for commit, issue closure, and the requested
+Mirror-managed patch. All local checks passed on Windows.
+
+## Scope
+
+- Synchronous Windows replacement of a running native executable.
+- Target-version verification before successful completion.
+- Rollback after invalid replacement verification.
+- Deferred cleanup of the locked old executable only.
+- Existing manifest-free `-h` behavior from issue #1.
+- Windows CI coverage and structured documentation health.
+
+## Commands and Results
+
+| Check | Result | Evidence |
+| --- | --- | --- |
+| `bun run typecheck` | passed | TypeScript completed without diagnostics. |
+| `bun test` | passed | 15 tests, 0 failures, 134 assertions. |
+| `bun run build` | passed | Library output compiled. |
+| `bun run binary` | passed | Local Windows executable compiled. |
+| `bun run binaries` | passed | All twelve release assets built and verified. |
+| Native `runx-windows-x64.exe -h` outside a manifest | passed | Citty usage rendered with exit code 0. |
+| Native `runx-windows-x64.exe --version` | passed | Reported `0.2.5` before the patch bump. |
+| `Bun.YAML.parse(.github/workflows/ci.yml)` | passed | Workflow YAML parsed successfully. |
+| `xdocs meta . --documents --strict --owner runx --format json` | passed | Root metadata and companions valid. |
+| `xdocs doctor . --warnings-as-errors --format json` | passed | 0 errors and 0 warnings. |
+| `git diff --check` | passed | No whitespace errors. |
+
+## Behavioral Evidence
+
+`source/self-management.spec.ts` runs only on Windows for the platform-specific
+cases. Its success case launches a copied PowerShell executable from the
+configured self path, keeps that executable running, upgrades the same path to
+the current Bun executable, and requires the replacement to report the expected
+version before `upgradeSelf()` resolves. It also observes removal of `.new` and
+eventual removal of `.old` after the running process exits.
+
+The rollback case downloads invalid executable bytes, requires verification to
+fail, and confirms that the original bytes are restored with neither `.new` nor
+`.old` left behind.
+
+The existing `source/cli.spec.ts` root-help test proves both `-h` and `--help`
+work without a manifest, satisfying issue #1.
+
+## Skipped or Blocked Checks
+
+- The new GitHub-hosted `windows-latest` job is not locally runnable; it will
+  execute after the commit reaches GitHub.
+- An actual 0.2.0-to-new-patch public upgrade is blocked until the new release
+  assets are published.
+
+## Readiness
+
+Ready for commit, closing GitHub issues #9 and #1, changelog preparation, and
+the requested Mirror patch plan/apply sequence.
+
+## References
+
+- [Implementation Review](../reviews/implementation/windows-self-upgrade-review.md)
+- [Plan](../plans/windows-self-upgrade.md)
+- [Decision](../decisions/windows-self-upgrade.md)

package/library/cli.d.ts.map

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

package/library/cli.js

@@ -7,6 +7,7 @@ import { installAgentInstructions, installAgentSkill } from './agents.js';
 import { RunXError } from './errors.js';
 import { runCommand } from './executor.js';
 import { readVersion, showHelpDocs, showHelpTree, showHome } from './help.js';
+import { initializeRunXManifest } from './init.js';
 import { readManifest, resolveCommand } from './manifest.js';
 import { renderDescription, renderExecutionPlan, renderJson, renderList } from './render.js';
 import { checkForLatestVersion, listAvailableVersions, uninstallSelf, upgradeSelf } from './self-management.js';
@@ -95,6 +96,12 @@ const createCommandTree = () => {
         setup: withCommandHelp(state),
         run: async () => checkManifest(resolveOptions(state.globalArgs)),
     });
+    const initCommand = defineCommand({
+        meta: { name: 'runx init', description: 'Interactively create an empty RunX manifest.' },
+        args: commonArgs,
+        setup: withCommandHelp(state),
+        run: async () => initializeProject(state.globalArgs),
+    });
     const agentsInstallCommand = defineCommand({
         meta: { name: 'runx agents install', description: 'Install the bundled RunX skill.' },
         args: {
@@ -166,6 +173,7 @@ const createCommandTree = () => {
         describe: describeCommandDefinition,
         run: runCommandDefinition,
         check: checkCommand,
+        init: initCommand,
         agents: agentsCommand,
         upgrade: upgradeCommand,
         uninstall: uninstallCommand,
@@ -176,6 +184,7 @@ const createCommandTree = () => {
         ['run', runCommandDefinition],
         ['r', runCommandDefinition],
         ['check', checkCommand],
+        ['init', initCommand],
         ['agents', agentsCommand],
         ['agents install', agentsInstallCommand],
         ['agents instructions', agentsInstructionsCommand],
@@ -334,6 +343,15 @@ async function checkManifest(options) {
     const result = { valid: true, manifestPath: path, commandCount: manifest.commands.length, groups: Object.keys(manifest.groups) };
     write(options.format === 'json' ? renderJson(result) : `valid: true\nmanifest: ${path}\ncommands: ${result.commandCount}\n`);
 }
+async function initializeProject(args) {
+    if (args.file) {
+        throw new RunXError('runx init does not support --file. It always creates runx.yaml in --cwd or the current directory.');
+    }
+    if (args.format === 'json') {
+        throw new RunXError('runx init does not support --format json because initialization is an interactive terminal workflow.');
+    }
+    await initializeRunXManifest({ cwd: resolve(args.cwd ?? process.cwd()) });
+}
 async function runSelectedCommand(selector, options, args) {
     const { manifest, path } = await readManifest(options.cwd, options.file);
     const command = resolveCommand(manifest, path, selector);

package/library/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../source/help.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,QAAO,MAAiF,CAAA;AAEhH,eAAO,MAAM,QAAQ,QAAO,MAe3B,CAAA;AAED,eAAO,MAAM,YAAY,QAAO,MAapB,CAAA;AAEZ,eAAO,MAAM,YAAY,QAAO,MAU/B,CAAA"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../source/help.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,QAAO,MAAiF,CAAA;AAEhH,eAAO,MAAM,QAAQ,QAAO,MAiB3B,CAAA;AAED,eAAO,MAAM,YAAY,QAAO,MAcpB,CAAA;AAEZ,eAAO,MAAM,YAAY,QAAO,MAW/B,CAAA"}

package/library/help.js

@@ -5,6 +5,7 @@ export const showHome = () => `RunX ${readVersion()}
 A documented, local command catalog for runx.yaml manifests.
 
 Usage:
+  runx init [--cwd <path>]
   runx list [--file <path>] [--format <text|json>]
   runx describe <selector>
   runx run <selector> [--dry-run] [--yes]
@@ -12,6 +13,7 @@ Usage:
   runx <selector>
 
 Start here:
+  runx init                 Interactively create an empty runx.yaml catalog.
   runx list                 List every command in the nearest manifest.
   runx --help-tree          Show the complete command tree.
   runx --help-docs          Show manifest and agent documentation guidance.
@@ -23,6 +25,7 @@ export const showHelpTree = () => [
     '|- run <selector>',
     '|  `- alias: r',
     '|- check',
+    '|- init',
     '|- agents',
     '|  |- install <local|global>',
     '|  `- instructions',
@@ -33,6 +36,7 @@ export const showHelpTree = () => [
 export const showHelpDocs = () => `RunX documentation
 
 Manifest: runx.yaml, discovered from the current directory upward or selected with --file.
+Create an empty catalog with runx init. Its manifest uses SemVer 1.x, configures a scripts directory, and always includes the public group.
 Required command fields: uid, id, group, summary, description, command.
 Optional command fields: cwd, shell, tags, confirm.
 

package/library/init.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { RunXManifest } from './types.js';
+export type RunXInitPrompter = {
+    intro(title: string): void;
+    text(options: {
+        message: string;
+        initialValue: string;
+        validate: (value: string | undefined) => string | undefined;
+    }): Promise<string | undefined>;
+    confirm(options: {
+        message: string;
+        initialValue: boolean;
+    }): Promise<boolean | undefined>;
+    preview(manifest: string): void;
+    cancel(message: string): void;
+    outro(message: string): void;
+    close?(): void;
+};
+export type RunXInitResult = {
+    status: 'cancelled';
+} | {
+    status: 'created';
+    path: string;
+    manifest: RunXManifest;
+};
+type RunXInitOptions = {
+    cwd: string;
+    isInteractive?: boolean;
+    prompter?: RunXInitPrompter;
+};
+export declare const initializeRunXManifest: ({ cwd, isInteractive, prompter }: RunXInitOptions) => Promise<RunXInitResult>;
+export declare const createInitialManifest: (projectName: string, scriptsDirectory: string) => RunXManifest;
+export declare const renderInitialManifest: (manifest: RunXManifest) => string;
+export {};
+//# sourceMappingURL=init.d.ts.map

package/library/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../source/init.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,IAAI,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,MAAM,GAAG,SAAS,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IAClJ,OAAO,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAA;IAC1F,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,KAAK,CAAC,IAAI,IAAI,CAAA;CACf,CAAA;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,CAAA;AAE/D,KAAK,eAAe,GAAG;IACrB,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CAC5B,CAAA;AAID,eAAO,MAAM,sBAAsB,qCAA4G,eAAe,KAAG,OAAO,CAAC,cAAc,CAmDtL,CAAA;AAED,eAAO,MAAM,qBAAqB,gBAAiB,MAAM,oBAAoB,MAAM,KAAG,YAQpF,CAAA;AAEF,eAAO,MAAM,qBAAqB,aAAc,YAAY,KAAG,MAenD,CAAA"}

package/library/init.js

@@ -0,0 +1,165 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { randomUUID } from 'node:crypto';
+import { rename, rm, writeFile } from 'node:fs/promises';
+import { basename, isAbsolute, relative, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { RunXError } from './errors.js';
+import { readManifest } from './manifest.js';
+const manifestVersion = '1.0.0';
+export const initializeRunXManifest = async ({ cwd, isInteractive = process.stdin.isTTY === true && process.stdout.isTTY === true, prompter }) => {
+    if (!isInteractive) {
+        throw new RunXError('runx init requires an interactive terminal. Run it directly in a terminal with stdin and stdout attached.');
+    }
+    const activePrompter = prompter ?? createTerminalPrompter();
+    try {
+        const root = resolve(cwd);
+        const path = resolve(root, 'runx.yaml');
+        const defaultProjectName = basename(root) || 'my-project';
+        activePrompter.intro('RunX project setup');
+        if (await Bun.file(path).exists()) {
+            const overwrite = await activePrompter.confirm({
+                message: 'runx.yaml already exists. Replace it?',
+                initialValue: false,
+            });
+            if (overwrite !== true)
+                return cancelInitialization(activePrompter);
+        }
+        const projectName = await activePrompter.text({
+            message: 'Project name',
+            initialValue: defaultProjectName,
+            validate: (value) => value?.trim() ? undefined : 'Enter a project name.',
+        });
+        if (projectName === undefined)
+            return cancelInitialization(activePrompter);
+        const scriptsDirectory = await activePrompter.text({
+            message: 'Scripts directory',
+            initialValue: 'scripts',
+            validate: (value) => validateScriptsDirectory(value, root),
+        });
+        if (scriptsDirectory === undefined)
+            return cancelInitialization(activePrompter);
+        const manifest = createInitialManifest(projectName.trim(), scriptsDirectory.trim());
+        const yaml = renderInitialManifest(manifest);
+        activePrompter.preview(yaml);
+        const confirmed = await activePrompter.confirm({
+            message: 'Create this runx.yaml?',
+            initialValue: true,
+        });
+        if (confirmed !== true)
+            return cancelInitialization(activePrompter);
+        await writeValidatedManifest(root, path, yaml);
+        activePrompter.outro(`Created ${path}`);
+        return { status: 'created', path, manifest };
+    }
+    finally {
+        activePrompter.close?.();
+    }
+};
+export const createInitialManifest = (projectName, scriptsDirectory) => ({
+    version: manifestVersion,
+    project: { name: projectName },
+    scripts: { directory: scriptsDirectory },
+    groups: {
+        public: { summary: 'Default public project commands.' },
+    },
+    commands: [],
+});
+export const renderInitialManifest = (manifest) => [
+    `version: ${JSON.stringify(manifest.version)}`,
+    '',
+    'project:',
+    `  name: ${JSON.stringify(manifest.project?.name ?? '')}`,
+    '',
+    'scripts:',
+    `  directory: ${JSON.stringify(manifest.scripts.directory)}`,
+    '',
+    'groups:',
+    '  public:',
+    `    summary: ${JSON.stringify(manifest.groups.public.summary)}`,
+    '',
+    'commands: []',
+    '',
+].join('\n');
+const createTerminalPrompter = () => {
+    const terminal = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    const accent = (value) => process.env['NO_COLOR'] ? value : `\u001b[36m${value}\u001b[0m`;
+    const success = (value) => process.env['NO_COLOR'] ? value : `\u001b[32m${value}\u001b[0m`;
+    const muted = (value) => process.env['NO_COLOR'] ? value : `\u001b[2m${value}\u001b[0m`;
+    const error = (value) => process.env['NO_COLOR'] ? value : `\u001b[31m${value}\u001b[0m`;
+    const write = (value) => {
+        process.stdout.write(value);
+    };
+    const ask = async (label) => {
+        try {
+            return await terminal.question(label);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return {
+        intro: (title) => write(`\n${accent('◆')} ${title}\n${muted('  A documented command catalog for this project.')}\n\n`),
+        text: async (options) => {
+            while (true) {
+                const value = await ask(`${accent('◆')} ${options.message} ${muted(`[${options.initialValue}]`)}\n  `);
+                if (value === undefined)
+                    return undefined;
+                const selected = value.trim() || options.initialValue;
+                const validation = options.validate(selected);
+                if (!validation)
+                    return selected;
+                write(`${error('▲')} ${validation}\n`);
+            }
+        },
+        confirm: async (options) => {
+            while (true) {
+                const defaultLabel = options.initialValue ? 'Y/n' : 'y/N';
+                const value = await ask(`${accent('◆')} ${options.message} ${muted(`[${defaultLabel}]`)}\n  `);
+                if (value === undefined)
+                    return undefined;
+                const answer = value.trim().toLowerCase();
+                if (!answer)
+                    return options.initialValue;
+                if (answer === 'y' || answer === 'yes')
+                    return true;
+                if (answer === 'n' || answer === 'no')
+                    return false;
+                write(`${error('▲')} Enter yes or no.\n`);
+            }
+        },
+        preview: (manifest) => write(`\n${accent('┌─ runx.yaml preview ─────────────────────────────────')}\n${manifest.trimEnd().split('\n').map((line) => `${accent('│')} ${line}`).join('\n')}\n${accent('└────────────────────────────────────────────────────')}\n\n`),
+        cancel: (message) => write(`${error('■')} ${message}\n`),
+        outro: (message) => {
+            write(`${success('◆')} ${message}\n`);
+        },
+        close: () => terminal.close(),
+    };
+};
+const cancelInitialization = (prompter) => {
+    prompter.cancel('Initialization cancelled. No files were changed.');
+    return { status: 'cancelled' };
+};
+const validateScriptsDirectory = (value, root) => {
+    const directory = value?.trim();
+    if (!directory)
+        return 'Enter a scripts directory.';
+    const resolvedDirectory = resolve(root, directory);
+    const relativeDirectory = relative(root, resolvedDirectory);
+    if (relativeDirectory === '' || relativeDirectory === '.' || isAbsolute(relativeDirectory) || relativeDirectory.startsWith('..')) {
+        return 'Use a relative subdirectory inside this project.';
+    }
+    return undefined;
+};
+const writeValidatedManifest = async (root, path, yaml) => {
+    const temporaryPath = resolve(root, `.runx-${randomUUID()}.yaml.tmp`);
+    try {
+        await writeFile(temporaryPath, yaml, { encoding: 'utf8', flag: 'wx' });
+        await readManifest(root, temporaryPath);
+        await rename(temporaryPath, path);
+    }
+    finally {
+        await rm(temporaryPath, { force: true });
+    }
+};

package/library/manifest.d.ts

@@ -12,10 +12,13 @@ export declare const CommandSchema: import("@sinclair/typebox").TObject<{
     confirm: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"never">, import("@sinclair/typebox").TLiteral<"always">]>>;
 }>;
 export declare const ManifestSchema: import("@sinclair/typebox").TObject<{
-    version: import("@sinclair/typebox").TLiteral<1>;
+    version: import("@sinclair/typebox").TString;
     project: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         name: import("@sinclair/typebox").TString;
     }>>;
+    scripts: import("@sinclair/typebox").TObject<{
+        directory: import("@sinclair/typebox").TString;
+    }>;
     groups: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
         summary: import("@sinclair/typebox").TString;
     }>>;

package/library/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../source/manifest.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAe,YAAY,EAAE,MAAM,YAAY,CAAA;AAI5E,eAAO,MAAM,aAAa;;;;;;;;;;;EAiBS,CAAA;AAEnC,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;EAKQ,CAAA;AAInC,eAAO,MAAM,YAAY,QAAe,MAAM,iBAAiB,MAAM,KAAG,OAAO,CAAC,MAAM,CAiBrF,CAAA;AAED,eAAO,MAAM,YAAY,QAAe,MAAM,iBAAiB,MAAM,KAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAmBvH,CAAA;AAED,eAAO,MAAM,cAAc,aAAc,YAAY,gBAAgB,MAAM,YAAY,MAAM,KAAG,eAkC/F,CAAA"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../source/manifest.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAe,YAAY,EAAE,MAAM,YAAY,CAAA;AAK5E,eAAO,MAAM,aAAa;;;;;;;;;;;EAiBS,CAAA;AAEnC,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;EAMQ,CAAA;AAInC,eAAO,MAAM,YAAY,QAAe,MAAM,iBAAiB,MAAM,KAAG,OAAO,CAAC,MAAM,CAiBrF,CAAA;AAED,eAAO,MAAM,YAAY,QAAe,MAAM,iBAAiB,MAAM,KAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAmBvH,CAAA;AAED,eAAO,MAAM,cAAc,aAAc,YAAY,gBAAgB,MAAM,YAAY,MAAM,KAAG,eAkC/F,CAAA"}

package/library/manifest.js

@@ -3,6 +3,7 @@ import { Type } from '@sinclair/typebox';
 import { TypeCompiler } from '@sinclair/typebox/compiler';
 import { RunXError, invariant } from './errors.js';
 const identifier = '^[a-z][a-z0-9-]*$';
+const semver = '^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$';
 export const CommandSchema = Type.Object({
     uid: Type.String({ pattern: identifier }),
     id: Type.String({ pattern: identifier }),
@@ -22,10 +23,11 @@ export const CommandSchema = Type.Object({
     confirm: Type.Optional(Type.Union([Type.Literal('never'), Type.Literal('always')])),
 }, { additionalProperties: false });
 export const ManifestSchema = Type.Object({
-    version: Type.Literal(1),
+    version: Type.String({ pattern: semver }),
     project: Type.Optional(Type.Object({ name: Type.String({ minLength: 1 }) }, { additionalProperties: false })),
+    scripts: Type.Object({ directory: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
     groups: Type.Record(Type.String({ pattern: identifier }), Type.Object({ summary: Type.String({ minLength: 1 }) }, { additionalProperties: false })),
-    commands: Type.Array(CommandSchema, { minItems: 1 }),
+    commands: Type.Array(CommandSchema),
 }, { additionalProperties: false });
 const manifestCheck = TypeCompiler.Compile(ManifestSchema);
 export const findManifest = async (cwd, explicitFile) => {
@@ -96,6 +98,17 @@ export const resolveCommand = (manifest, manifestPath, selector) => {
     };
 };
 const validateManifestSemantics = (manifest, path) => {
+    const versionMajor = manifest.version.split('.', 1)[0];
+    if (versionMajor !== '1') {
+        throw new RunXError(`Unsupported RunX manifest version "${manifest.version}" in ${path}. Supported major version: 1.`);
+    }
+    const manifestDirectory = dirname(path);
+    const scriptsDirectory = resolve(manifestDirectory, manifest.scripts.directory);
+    const relativeScriptsDirectory = relative(manifestDirectory, scriptsDirectory);
+    invariant(relativeScriptsDirectory !== '' && relativeScriptsDirectory !== '.' && !isAbsolute(relativeScriptsDirectory) && !relativeScriptsDirectory.startsWith('..'), `Scripts directory "${manifest.scripts.directory}" must be a relative subdirectory inside the manifest directory in ${path}.`);
+    if (!manifest.groups.public) {
+        throw new RunXError(`RunX manifest ${path} must define the default "public" group.`);
+    }
     const uids = new Set();
     const selectors = new Set();
     for (const command of manifest.commands) {

package/library/self-management.d.ts

@@ -1,8 +1,9 @@
 import type { RunXUpgradeResult, UpdateResult } from './types.js';
-export declare const checkForLatestVersion: () => Promise<UpdateResult>;
-export declare const listAvailableVersions: () => Promise<string[]>;
-export declare const upgradeSelf: (dryRun: boolean) => Promise<RunXUpgradeResult>;
-export declare const uninstallSelf: (dryRun: boolean) => Promise<{
+export { checkForLatestVersion, listAvailableVersions, uninstallSelf, upgradeSelf, };
+declare const checkForLatestVersion: () => Promise<UpdateResult>;
+declare const listAvailableVersions: () => Promise<string[]>;
+declare const upgradeSelf: (dryRun: boolean) => Promise<RunXUpgradeResult>;
+declare const uninstallSelf: (dryRun: boolean) => Promise<{
     executablePath: string;
     scheduled: boolean;
     dryRun: boolean;

package/library/self-management.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"self-management.d.ts","sourceRoot":"","sources":["../source/self-management.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAMjE,eAAO,MAAM,qBAAqB,QAAa,OAAO,CAAC,YAAY,CAYlE,CAAA;AAED,eAAO,MAAM,qBAAqB,QAAa,OAAO,CAAC,MAAM,EAAE,CAK9D,CAAA;AAED,eAAO,MAAM,WAAW,WAAkB,OAAO,KAAG,OAAO,CAAC,iBAAiB,CAmB5E,CAAA;AAED,eAAO,MAAM,aAAa,WAAkB,OAAO,KAAG,OAAO,CAAC;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAW5H,CAAA"}
+{"version":3,"file":"self-management.d.ts","sourceRoot":"","sources":["../source/self-management.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEjE,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,aAAa,EACb,WAAW,GACZ,CAAA;AAMD,QAAA,MAAM,qBAAqB,QAAa,OAAO,CAAC,YAAY,CAY3D,CAAA;AAED,QAAA,MAAM,qBAAqB,QAAa,OAAO,CAAC,MAAM,EAAE,CAKvD,CAAA;AAED,QAAA,MAAM,WAAW,WAAkB,OAAO,KAAG,OAAO,CAAC,iBAAiB,CAmBrE,CAAA;AAED,QAAA,MAAM,aAAa,WAAkB,OAAO,KAAG,OAAO,CAAC;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAWrH,CAAA"}

package/library/self-management.js

@@ -1,9 +1,11 @@
+import { Buffer } from 'node:buffer';
 import { chmod, rename, rm } from 'node:fs/promises';
 import { basename } from 'node:path';
 import { RunXError } from './errors.js';
 import { readVersion } from './help.js';
+export { checkForLatestVersion, listAvailableVersions, uninstallSelf, upgradeSelf, };
 const repositoryApi = 'https://api.github.com/repos/CGuiho/runx/releases';
-export const checkForLatestVersion = async () => {
+const checkForLatestVersion = async () => {
     const currentVersion = readVersion();
     try {
         const response = await fetch(`${repositoryApi}/latest`, { headers: { accept: 'application/vnd.github+json' } });
@@ -18,14 +20,14 @@ export const checkForLatestVersion = async () => {
         return { currentVersion, latestVersion: currentVersion, updateAvailable: false };
     }
 };
-export const listAvailableVersions = async () => {
+const listAvailableVersions = async () => {
     const response = await fetch(`${repositoryApi}?per_page=20`, { headers: { accept: 'application/vnd.github+json' } });
     if (!response.ok)
         throw new RunXError(`Could not retrieve RunX releases: HTTP ${response.status}`);
     const releases = await response.json();
     return releases.map((release) => release.tag_name.replace(/^@guiho\/runx@/, '').replace(/^v/, ''));
 };
-export const upgradeSelf = async (dryRun) => {
+const upgradeSelf = async (dryRun) => {
     const executablePath = requireNativeExecutable();
     const update = await checkForLatestVersion();
     const upToDate = !update.updateAvailable && update.latestVersion === update.currentVersion && Boolean(update.url);
@@ -43,10 +45,10 @@ export const upgradeSelf = async (dryRun) => {
         await rename(temporaryPath, executablePath);
         return { ...update, executablePath, scheduled: false, upToDate: false };
     }
-    scheduleWindowsReplacement(temporaryPath, executablePath);
-    return { ...update, executablePath, scheduled: true, upToDate: false };
+    await replaceWindowsExecutable(temporaryPath, executablePath, update.latestVersion);
+    return { ...update, executablePath, scheduled: false, upToDate: false };
 };
-export const uninstallSelf = async (dryRun) => {
+const uninstallSelf = async (dryRun) => {
     const executablePath = requireNativeExecutable();
     if (dryRun)
         return { executablePath, scheduled: false, dryRun: true };
@@ -66,10 +68,65 @@ const requireNativeExecutable = () => {
         throw new RunXError('Self-management requires a native RunX executable installed from a GitHub release.');
     return executablePath;
 };
-const scheduleWindowsReplacement = (temporaryPath, executablePath) => {
-    const command = `ping 127.0.0.1 -n 2 > nul & move /y "${temporaryPath}" "${executablePath}" > nul`;
-    Bun.spawn(['cmd.exe', '/d', '/s', '/c', command], { detached: true, stdout: 'ignore', stderr: 'ignore', stdin: 'ignore' });
+const replaceWindowsExecutable = async (temporaryPath, executablePath, expectedVersion) => {
+    const backupPath = `${executablePath}.old`;
+    let originalMoved = false;
+    try {
+        await rm(backupPath, { force: true });
+        await rename(executablePath, backupPath);
+        originalMoved = true;
+        await rename(temporaryPath, executablePath);
+        await verifyExecutableVersion(executablePath, expectedVersion);
+        await cleanupWindowsBackup(backupPath);
+    }
+    catch (error) {
+        const replacementFailure = errorMessage(error);
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+        if (!originalMoved) {
+            throw new RunXError(`Could not replace the Windows RunX executable at ${executablePath}: ${replacementFailure}`);
+        }
+        try {
+            await rm(executablePath, { force: true });
+            await rename(backupPath, executablePath);
+        }
+        catch (rollbackError) {
+            throw new RunXError(`Windows RunX upgrade failed at ${executablePath}: ${replacementFailure}. Automatic rollback also failed: ${errorMessage(rollbackError)}`);
+        }
+        throw new RunXError(`Windows RunX upgrade failed; the previous executable was restored at ${executablePath}: ${replacementFailure}`);
+    }
+};
+const verifyExecutableVersion = async (executablePath, expectedVersion) => {
+    const verification = Bun.spawn([executablePath, '--version'], { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' });
+    const [stdout, stderr, exitCode] = await Promise.all([
+        new Response(verification.stdout).text(),
+        new Response(verification.stderr).text(),
+        verification.exited,
+    ]);
+    const actualVersion = stdout.trim();
+    if (exitCode !== 0)
+        throw new Error(`replacement exited with code ${exitCode}${stderr.trim() ? `: ${stderr.trim()}` : ''}`);
+    if (actualVersion !== expectedVersion)
+        throw new Error(`replacement reported version ${actualVersion || '<empty>'}; expected ${expectedVersion}`);
+};
+const cleanupWindowsBackup = async (backupPath) => {
+    try {
+        await rm(backupPath, { force: true });
+    }
+    catch { }
+    scheduleWindowsBackupCleanup(backupPath);
+};
+const scheduleWindowsBackupCleanup = (backupPath) => {
+    const command = 'for ($attempt = 0; $attempt -lt 300; $attempt += 1) { if (-not (Test-Path -LiteralPath $env:RUNX_BACKUP_PATH)) { exit 0 }; try { Remove-Item -LiteralPath $env:RUNX_BACKUP_PATH -Force -ErrorAction Stop; exit 0 } catch { Start-Sleep -Milliseconds 100 } }; exit 1';
+    const encodedCommand = Buffer.from(command, 'utf16le').toString('base64');
+    Bun.spawn(['cmd.exe', '/d', '/s', '/c', `powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -EncodedCommand ${encodedCommand}`], {
+        detached: true,
+        env: { ...process.env, RUNX_BACKUP_PATH: backupPath },
+        stdout: 'ignore',
+        stderr: 'ignore',
+        stdin: 'ignore',
+    });
 };
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 const compareVersions = (left, right) => {
     const parse = (value) => value.split(/[.+-]/).map((part) => Number.parseInt(part, 10) || 0);
     const a = parse(left);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/runx",
   "description": "A language-agnostic, documented command catalog and local CLI executor.",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "type": "module",
   "main": "./library/guiho-runx.js",
   "types": "./library/guiho-runx.d.ts",