@guiho/runx 0.2.7 → 0.4.1

package/library/types.d.ts

@@ -1,31 +1,26 @@
-import type { Static } from '@sinclair/typebox';
-import type { CommandSchema, ManifestSchema } from './manifest.js';
-export type RunXManifest = Static<typeof ManifestSchema>;
-export type RunXCommand = Static<typeof CommandSchema>;
-export type ResolvedCommand = RunXCommand & {
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { RunXCommand, RunXManifest } from './configuration.js';
+export type { AgentScope, CliOptions, OutputFormat, ResolvedCommand, RunXCommand, RunXManifest, UpdateResult, };
+type ResolvedCommand = RunXCommand & {
     index: number;
     selector: string;
     manifestPath: string;
     cwd: string;
 };
-export type OutputFormat = 'text' | 'json';
-export type CliOptions = {
+type OutputFormat = 'text' | 'json';
+type CliOptions = {
     cwd: string;
-    file?: string;
+    config?: string;
     format: OutputFormat;
     verbose: boolean;
 };
-export type AgentTool = 'agents' | 'claude' | 'all';
-export type AgentScope = 'local' | 'global';
-export type UpdateResult = {
+type AgentScope = 'local' | 'global';
+type UpdateResult = {
     currentVersion: string;
     latestVersion: string;
     updateAvailable: boolean;
     url?: string;
 };
-export type RunXUpgradeResult = UpdateResult & {
-    executablePath: string;
-    scheduled: boolean;
-    upToDate: boolean;
-};
 //# sourceMappingURL=types.d.ts.map

package/library/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../source/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAElE,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAA;AACxD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,aAAa,CAAC,CAAA;AAEtD,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAA;AAE1C,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,YAAY,CAAA;IACpB,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAA;AAEnD,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE3C,MAAM,MAAM,YAAY,GAAG;IACzB,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,OAAO,CAAA;IACxB,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG;IAC7C,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,OAAO,CAAA;IAClB,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../source/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEnE,YAAY,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,eAAe,EACf,WAAW,EACX,YAAY,EACZ,YAAY,GACb,CAAA;AAED,KAAK,eAAe,GAAG,WAAW,GAAG;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,KAAK,YAAY,GAAG,MAAM,GAAG,MAAM,CAAA;AAEnC,KAAK,UAAU,GAAG;IAChB,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,YAAY,CAAA;IACpB,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,KAAK,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEpC,KAAK,YAAY,GAAG;IAClB,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,OAAO,CAAA;IACxB,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA"}

package/library/types.js

@@ -0,0 +1,3 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */

package/library/update-cache.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { Static } from '@sinclair/typebox';
+export { cacheSchema, readCachedUpdateNotice, runUpdateWorker, spawnUpdateWorker, updateCachePath, };
+export type { UpdateCache, };
+declare const cacheSchema: import("@sinclair/typebox").TObject<{
+    newVersionAvailable: import("@sinclair/typebox").TBoolean;
+    latestVersion: import("@sinclair/typebox").TString;
+    upgradeCommand: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    lastCheck: import("@sinclair/typebox").TString;
+}>;
+type UpdateCache = Static<typeof cacheSchema>;
+declare function updateCachePath(): string;
+declare function readCachedUpdateNotice(verbose?: boolean): Promise<string | null>;
+declare function spawnUpdateWorker(): void;
+declare function runUpdateWorker(options?: {
+    fetchImpl?: typeof fetch;
+    now?: () => Date;
+}): Promise<UpdateCache>;
+//# sourceMappingURL=update-cache.d.ts.map

package/library/update-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-cache.d.ts","sourceRoot":"","sources":["../source/update-cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE/C,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,eAAe,GAChB,CAAA;AACD,YAAY,EACV,WAAW,GACZ,CAAA;AAED,QAAA,MAAM,WAAW;;;;;EAKkB,CAAA;AAEnC,KAAK,WAAW,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAA;AAE7C,iBAAS,eAAe,IAAI,MAAM,CAEjC;AAED,iBAAe,sBAAsB,CAAC,OAAO,UAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAY7E;AAED,iBAAS,iBAAiB,IAAI,IAAI,CAYjC;AAED,iBAAe,eAAe,CAAC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAiBjH"}

package/library/update-cache.js

@@ -0,0 +1,68 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+import { gt, valid } from 'semver';
+import { readVersion } from './help.js';
+import { fetchReleaseCatalog, resolveUpgradePlatform } from './release-catalog.js';
+import { globalRunXDirectory, movePath, readTextIfExists, writeTextFile } from './storage.js';
+import { joinPath } from './path-utils.js';
+export { cacheSchema, readCachedUpdateNotice, runUpdateWorker, spawnUpdateWorker, updateCachePath, };
+const cacheSchema = Type.Object({
+    newVersionAvailable: Type.Boolean(),
+    latestVersion: Type.String(),
+    upgradeCommand: Type.Optional(Type.String()),
+    lastCheck: Type.String(),
+}, { additionalProperties: false });
+function updateCachePath() {
+    return joinPath(globalRunXDirectory(), 'cache.json');
+}
+async function readCachedUpdateNotice(verbose = false) {
+    const raw = await readTextIfExists(updateCachePath());
+    if (raw === null)
+        return null;
+    try {
+        const cache = Value.Decode(cacheSchema, JSON.parse(raw));
+        return cache.newVersionAvailable
+            ? 'New version available. Run this command to upgrade: runx upgrade'
+            : null;
+    }
+    catch (error) {
+        if (verbose)
+            process.stderr.write(`warning: ignored invalid RunX update cache: ${error instanceof Error ? error.message : String(error)}\n`);
+        return null;
+    }
+}
+function spawnUpdateWorker() {
+    if (Bun.env.RUNX_DISABLE_UPDATE_WORKER === '1')
+        return;
+    const command = process.execPath.toLowerCase().includes('bun')
+        ? [process.execPath, Bun.main, '--check-updates-worker']
+        : [process.execPath, '--check-updates-worker'];
+    Bun.spawn(command, {
+        detached: true,
+        stdout: 'ignore',
+        stderr: 'ignore',
+        stdin: 'ignore',
+        env: process.env,
+    }).unref();
+}
+async function runUpdateWorker(options = {}) {
+    const currentVersion = readVersion();
+    const platform = resolveUpgradePlatform();
+    const catalog = await fetchReleaseCatalog({ ...platform, currentVersion, fetchImpl: options.fetchImpl });
+    const latestVersion = catalog.latestStableVersion ?? currentVersion;
+    const newVersionAvailable = Boolean(valid(currentVersion) && valid(latestVersion) && gt(latestVersion, currentVersion));
+    const cache = {
+        newVersionAvailable,
+        latestVersion,
+        ...(newVersionAvailable ? { upgradeCommand: 'runx upgrade' } : {}),
+        lastCheck: (options.now?.() ?? new Date()).toISOString(),
+    };
+    const path = updateCachePath();
+    const temporary = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    await writeTextFile(temporary, `${JSON.stringify(cache, null, 2)}\n`);
+    await movePath(temporary, path);
+    return cache;
+}

package/library/upgrade-reporting.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { ReleaseCatalog, UpgradeEnvelope, UpgradeEvent, UpgradePlan } from './upgrade-types.js';
+export { renderReleaseCatalog, renderUpgradeEvent, renderUpgradeHeading, renderUpgradePlan, renderUpgradeResult, };
+declare const renderUpgradeHeading: () => string;
+declare const renderUpgradePlan: (plan: UpgradePlan) => string;
+declare const renderUpgradeEvent: (event: UpgradeEvent) => string;
+declare const renderUpgradeResult: (result: UpgradeEnvelope) => string;
+declare const renderReleaseCatalog: (catalog: ReleaseCatalog) => string;
+//# sourceMappingURL=upgrade-reporting.d.ts.map

package/library/upgrade-reporting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-reporting.d.ts","sourceRoot":"","sources":["../source/upgrade-reporting.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAwB,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAE1H,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,GACpB,CAAA;AAED,QAAA,MAAM,oBAAoB,QAAO,MAId,CAAA;AAEnB,QAAA,MAAM,iBAAiB,SAAU,WAAW,KAAG,MAS5B,CAAA;AAEnB,QAAA,MAAM,kBAAkB,UAAW,YAAY,KAAG,MAWjD,CAAA;AAED,QAAA,MAAM,mBAAmB,WAAY,eAAe,KAAG,MAWtD,CAAA;AAYD,QAAA,MAAM,oBAAoB,YAAa,cAAc,KAAG,MAavD,CAAA"}

package/library/upgrade-reporting.js

@@ -0,0 +1,67 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+export { renderReleaseCatalog, renderUpgradeEvent, renderUpgradeHeading, renderUpgradePlan, renderUpgradeResult, };
+const renderUpgradeHeading = () => [
+    '------------------------------------------------------------',
+    '  Upgrading the CLI',
+    '------------------------------------------------------------',
+].join('\n') + '\n';
+const renderUpgradePlan = (plan) => [
+    `  current : ${plan.currentVersion}`,
+    `  target  : ${plan.targetVersion}`,
+    `  os      : ${plan.os}`,
+    `  arch    : ${plan.arch}`,
+    `  binary  : ${plan.assetName}`,
+    `  path    : ${plan.executablePath.replaceAll('\\', '/')}`,
+    `  url     : ${plan.assetUrl}`,
+    '------------------------------------------------------------',
+].join('\n') + '\n';
+const renderUpgradeEvent = (event) => {
+    if (event.status !== 'started' || event.phase === 'plan')
+        return '';
+    const labels = {
+        download: 'Downloading...',
+        validate: 'Validating...',
+        replace: 'Replacing...',
+        verify: 'Verifying...',
+        cleanup: 'Cleaning up...',
+    };
+    const label = labels[event.phase];
+    return label ? `${label}\n` : '';
+};
+const renderUpgradeResult = (result) => {
+    const summary = result.outcome === 'upgraded'
+        ? `Upgrade complete: ${result.plan?.currentVersion} -> ${result.plan?.targetVersion}`
+        : result.outcome === 'up-to-date'
+            ? `Already up to date: ${result.result?.installedVersion ?? result.recovery.targetVersion}`
+            : result.outcome === 'dry-run'
+                ? `Dry run complete: ${result.plan?.currentVersion} -> ${result.plan?.targetVersion}`
+                : result.outcome === 'rolled-back'
+                    ? `Upgrade failed during ${result.error?.phase ?? 'replace'}; restored RunX ${result.result?.installedVersion ?? result.recovery.targetVersion}.`
+                    : `Upgrade failed during ${result.error?.phase ?? 'plan'}.`;
+    return `${summary}\n\n${renderRecovery(result.recovery, result.outcome === 'failed' || result.outcome === 'rolled-back')}\n`;
+};
+const renderRecovery = (recovery, repair) => [
+    recovery.targetSource === 'fallback-current'
+        ? `Repair reinstall (target lookup failed; pinned to installed RunX ${recovery.targetVersion}):`
+        : `${repair ? 'To repair RunX' : 'If the new version is not active'}, install RunX ${recovery.targetVersion} directly:`,
+    `  ${recovery.installCommand}`,
+    '',
+    'If RunX is still running and blocks installation, stop it first:',
+    `  ${recovery.stopProcessCommand}`,
+].join('\n');
+const renderReleaseCatalog = (catalog) => {
+    const headers = ['VERSION', 'CHANNEL', 'PUBLISHED', 'CURRENT', 'LATEST', 'ASSET'];
+    const rows = catalog.releases.map((release) => [
+        release.version,
+        release.channel,
+        release.publishedAt?.slice(0, 10) ?? '-',
+        release.current ? 'yes' : '',
+        release.latestStable ? 'yes' : '',
+        release.compatibleAsset ? 'yes' : 'no',
+    ]);
+    const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => row[index]?.length ?? 0)));
+    const line = (values) => values.map((value, index) => value.padEnd(widths[index] ?? value.length)).join('  ').trimEnd();
+    return ['AVAILABLE RUNX VERSIONS', '', line(headers), ...rows.map(line)].join('\n') + '\n';
+};

package/library/upgrade-types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+export type UpgradeOs = 'windows' | 'darwin' | 'linux';
+export type UpgradeArch = 'x64' | 'arm64';
+export type UpgradeVariant = 'baseline' | 'default' | 'modern';
+export type ReleaseAsset = {
+    name: string;
+    url: string;
+};
+export type ReleaseCatalogEntry = {
+    tag: string;
+    version: string;
+    channel: string;
+    prerelease: boolean;
+    publishedAt: string | null;
+    current: boolean;
+    latestStable: boolean;
+    compatibleAsset: ReleaseAsset | null;
+};
+export type ReleaseCatalog = {
+    schemaVersion: 1;
+    command: 'runx upgrade list';
+    currentVersion: string;
+    latestStableVersion: string | null;
+    releases: ReleaseCatalogEntry[];
+};
+export type RecoveryInstructions = {
+    targetVersion: string;
+    targetSource: 'resolved' | 'fallback-current';
+    installCommand: string;
+    stopProcessCommand: string;
+};
+export type UpgradePlan = {
+    currentVersion: string;
+    targetVersion: string;
+    os: UpgradeOs;
+    arch: UpgradeArch;
+    assetName: string;
+    assetUrl: string;
+    executablePath: string;
+};
+export type UpgradePhase = 'plan' | 'download' | 'validate' | 'replace' | 'verify' | 'cache' | 'cleanup';
+export type UpgradePhaseStatus = 'started' | 'succeeded' | 'skipped' | 'failed';
+export type UpgradeEvent = {
+    sequence: number;
+    phase: UpgradePhase;
+    status: UpgradePhaseStatus;
+    message?: string;
+};
+export type UpgradeOutcome = 'upgraded' | 'up-to-date' | 'dry-run' | 'rolled-back' | 'failed';
+export type UpgradeResult = {
+    installedVersion: string;
+    cleanupDeferred: boolean;
+};
+export type UpgradeErrorCode = 'release_lookup_failed' | 'release_payload_invalid' | 'no_compatible_asset' | 'download_failed' | 'download_invalid' | 'backup_failed' | 'replace_failed' | 'verification_failed' | 'rollback_failed' | 'installer_verification_failed';
+export type UpgradeError = {
+    code: UpgradeErrorCode;
+    phase: UpgradePhase;
+    message: string;
+};
+export type UpgradeEnvelope = {
+    schemaVersion: 1;
+    command: 'runx upgrade';
+    outcome: UpgradeOutcome;
+    plan: UpgradePlan | null;
+    events: UpgradeEvent[];
+    result: UpgradeResult | null;
+    recovery: RecoveryInstructions;
+    error: UpgradeError | null;
+};
+//# sourceMappingURL=upgrade-types.d.ts.map

package/library/upgrade-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-types.d.ts","sourceRoot":"","sources":["../source/upgrade-types.ts"],"names":[],"mappings":"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"}

package/library/upgrade-types.js

@@ -0,0 +1,3 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/runx",
   "description": "A language-agnostic, documented command catalog and local CLI executor.",
-  "version": "0.2.7",
+  "version": "0.4.1",
   "type": "module",
   "main": "./library/guiho-runx.js",
   "types": "./library/guiho-runx.d.ts",
@@ -12,7 +12,7 @@
     }
   },
   "bin": {
-    "runx": "scripts/runx-bin.ts"
+    "runx": "scripts/runx-bin.mjs"
   },
   "files": [
     "library/",
@@ -57,6 +57,7 @@
     "build": "rm -rf library && tsc -p .",
     "binary": "bun build source/guiho-runx-native-bin.ts --compile --outfile bin/runx",
     "binaries": "bun run devops/build-binaries.ts",
+    "verify-assets": "bun run devops/verify-release-assets.ts",
     "test": "bun test",
     "typecheck": "tsc -p . --noEmit",
     "check": "bun run typecheck && bun test",
@@ -69,10 +70,12 @@
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.52",
-    "citty": "^0.2.2"
+    "citty": "^0.2.2",
+    "semver": "^7.8.5"
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",
+    "@types/semver": "^7.7.1",
     "typescript": "^7.0.2"
   }
 }

package/scripts/runx-bin.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+
+import { spawn } from 'node:child_process'
+import { chmod, mkdir, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { arch, homedir, platform } from 'node:os'
+import { join } from 'node:path'
+
+import packageJson from '../package.json' with { type: 'json' }
+
+const os = platform() === 'win32' ? 'windows' : platform() === 'darwin' ? 'darwin' : platform() === 'linux' ? 'linux' : null
+const cpu = arch() === 'x64' ? 'x64' : arch() === 'arm64' ? 'arm64' : null
+if (!os || !cpu) fail(`Unsupported platform: ${platform()} ${arch()}`)
+
+const suffix = os === 'windows' ? '.exe' : ''
+const asset = cpu === 'arm64' ? `runx-${os}-arm64${suffix}` : `runx-${os}-x64-baseline${suffix}`
+const cache = process.env.RUNX_NATIVE_CACHE || join(homedir(), '.guiho', 'runx', 'npm', packageJson.version)
+const executable = join(cache, `runx${suffix}`)
+const tag = encodeURIComponent(`@guiho/runx@${packageJson.version}`)
+const downloadBase = (process.env.RUNX_DOWNLOAD_BASE_URL || 'https://github.com/CGuiho/runx/releases/download').replace(/\/$/, '')
+const url = `${downloadBase}/${tag}/${asset}`
+
+try {
+  await stat(executable)
+} catch {
+  await mkdir(cache, { recursive: true })
+  const response = await fetch(url, { redirect: 'follow' })
+  if (!response.ok) fail(`Could not download ${asset}: HTTP ${response.status}`)
+  const temporary = `${executable}.${process.pid}.tmp`
+  await writeFile(temporary, new Uint8Array(await response.arrayBuffer()), { flag: 'wx' })
+  if (os !== 'windows') await chmod(temporary, 0o755)
+  await rename(temporary, executable)
+}
+
+const child = spawn(executable, process.argv.slice(2), { env: process.env, stdio: 'inherit' })
+child.once('error', (error) => fail(error.message))
+child.once('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal)
+  else process.exit(code ?? 1)
+})
+
+function fail(message) {
+  process.stderr.write(`error: ${message}\n`)
+  void rm(executable, { force: true }).catch(() => undefined)
+  process.exit(1)
+}

package/scripts/runx-bin.spec.ts

@@ -0,0 +1,62 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+
+import { afterEach, expect, test } from 'bun:test'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+let directory = ''
+
+afterEach(async () => {
+  if (directory) await rm(directory, { recursive: true, force: true })
+  directory = ''
+})
+
+test('packed npm bootstrap downloads and delegates with Node while Bun is absent from PATH', async () => {
+  const node = Bun.which('node')
+  if (!node) throw new Error('Node is required for the npm bootstrap test.')
+  directory = await mkdtemp(join(tmpdir(), 'runx-npm-'))
+  const root = Bun.fileURLToPath(new URL('..', import.meta.url))
+  const packed = Bun.spawn([process.execPath, 'pm', 'pack', '--destination', directory, '--ignore-scripts'], {
+    cwd: root,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [packCode, packOutput, packError] = await Promise.all([
+    packed.exited,
+    new Response(packed.stdout).text(),
+    new Response(packed.stderr).text(),
+  ])
+  expect(packCode, packError).toBe(0)
+  const archiveName = [...new Bun.Glob('*.tgz').scanSync({ cwd: directory, onlyFiles: true })][0]
+  expect(archiveName, packOutput).toBeDefined()
+  const extraction = Bun.spawn(['tar', '-xzf', join(directory, archiveName), '-C', directory])
+  expect(await extraction.exited).toBe(0)
+
+  const server = Bun.serve({ port: 0, fetch: () => new Response(Bun.file(process.execPath)) })
+  try {
+    const wrapper = join(directory, 'package', 'scripts', 'runx-bin.mjs')
+    const child = Bun.spawn([node, wrapper, '--version'], {
+      cwd: join(directory, 'package'),
+      env: {
+        ...process.env,
+        PATH: join(node, '..'),
+        RUNX_NATIVE_CACHE: join(directory, 'native-cache'),
+        RUNX_DOWNLOAD_BASE_URL: `http://127.0.0.1:${server.port}`,
+      },
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const [exitCode, stdout, stderr] = await Promise.all([
+      child.exited,
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+    ])
+    expect(exitCode, stderr).toBe(0)
+    expect(stdout.trim()).toBe(process.versions.bun)
+  } finally {
+    server.stop(true)
+  }
+})

package/scripts/scripts.xdocs.md

@@ -4,7 +4,8 @@ description: Package-manager launcher scripts for RunX.
 parent: runx
 children: []
 files:
-  runx-bin.ts: Executes a packaged native binary, the published compiled library launcher, or the source CLI fallback in a checkout.
+  runx-bin.mjs: Node-compatible npm bootstrap that downloads, caches, and delegates to the exact native release binary.
+  runx-bin.spec.ts: Packs the npm package and proves Node-only bootstrap download/delegation with Bun absent from PATH.
 documents: {}
 tags:
   - scripts
@@ -16,5 +17,4 @@ flags: []
 status: stable
 ---
 
-The package launcher preserves the `runx` bin command in installed npm packages
-and development checkouts without requiring unpublished source files.
+The npm launcher contains no RunX domain logic and requires no Bun installation.

package/skills/guiho-s-runx/SKILL.md

@@ -1,73 +1,78 @@
 ---
 name: guiho-s-runx
-purpose: Guide agents through safe inspection and execution of RunX command catalogs.
-description: Use when inspecting, creating, validating, organizing, documenting, or running a RunX `runx.yaml` command catalog. This includes listing available project commands, choosing a command by UID or selector, reviewing command descriptions, dry runs, confirmation-gated execution, and agent-safe project automation.
-created: 2026-07-12
-owner: guiho-s-runx
-flags: []
+description: Use when inspecting, validating, documenting, or safely executing a RunX runx.yaml command catalog.
+purpose: Teach agents the supported RunX catalog inspection and execution workflow.
+created: 2026-07-18
+flags:
+  - bundled
 tags:
-  - agents
   - runx
+  - cli
 keywords:
-  - runx
-  - citty
+  - runx.yaml
   - command catalog
   - dry run
+owner: guiho-s-runx
+metadata:
+  version: "0.2.0"
 ---
 
 # GUIHO RunX
 
-Use RunX as the command catalog for a project. It documents executable local
-commands but does not make them inherently safe: a manifest is trusted code.
-
-## Inspect Before Executing
-
-1. From the intended project directory, run `runx check --format json`.
-2. Run `runx list --format json` to inspect groups, UIDs, summaries, tags, and
-   confirmation requirements.
-3. Choose a stable `uid` for automation. An index is only for the current list
-   and an unqualified ID can be ambiguous.
-4. Run `runx describe <uid>` before an unfamiliar or high-impact command.
-5. Run `runx run <uid> --dry-run` before a real execution when the command has
-   filesystem, database, release, deployment, or production effects.
-
-## Execute Safely
-
-- Use `runx run <uid>` or the short alias `runx r <uid>`.
-- `runx <selector>` is allowed as a human shorthand only when it cannot be
-  confused with a built-in command; agents should prefer explicit `runx run`.
-- If `confirm: always` is set, RunX requires `--yes`.
-- Add `--yes` only after the user explicitly authorizes the specific command.
-- Do not treat a group name such as `development` or `operations` as a safety
-  guarantee. Read the command description and command text.
-- Do not add secrets to `runx.yaml`. Use the project's existing environment or
-  secret-management workflow.
-- Use `runx <command> --help` for command-specific Citty usage. `runx -h` and
-  `runx -v` are global operations and do not require a manifest.
-
-## Maintain Manifests
-
-- Keep `uid`, `id`, `group`, `summary`, `description`, and `command` present.
-- Keep UIDs stable; never reuse a UID for a materially different command.
-- Use a group for organization, a concise summary for listings, and a complete
-  description for prerequisites, effects, and risk.
-- Set `confirm: always` for destructive, release, deployment, migration, and
-  production-impacting commands when confirmation is useful.
-- Run `runx check` after every manifest change. It rejects unknown fields,
-  duplicate UIDs/selectors, missing descriptions, invalid working directories,
-  and unsupported shell choices.
-
-## Useful Commands
+## Inspect Before Execution
+
+1. Run `runx check --format json`.
+2. Run `runx list --format json`.
+3. Prefer a stable UID for automation.
+4. Run `runx describe <uid>` before unfamiliar work.
+5. Run `runx run <uid> --dry-run` before any mutation or high-impact command.
+
+RunX manifests are trusted executable code. A group name is not a safety
+boundary. Never add `--yes` unless the developer explicitly authorizes the
+specific confirmation-gated command.
+
+## Configuration
+
+RunX resolves YAML only:
+
+1. `--config <path>`;
+2. effective-cwd `runx.yaml`;
+3. `~/.guiho/runx/runx.yaml`.
+
+It does not search parent directories.
+
+## Execute
+
+Use only:
 
 ```text
-runx                         Show the RunX home page and usage.
-runx -h                      Show generated command help.
-runx -v                      Show the installed version.
-runx list                    List the nearest manifest.
-runx describe <uid>          Explain one command without execution.
-runx run <uid> --dry-run     Inspect the execution plan.
-runx r <uid>                 Run through the short alias.
-runx agents install local    Install this skill into .agents/skills.
-runx --help-tree             Show the command hierarchy.
-runx --help-docs             Show manifest documentation guidance.
+runx run <uid>
 ```
+
+Listing, describing, checking, help, agent operations, and dry runs must never
+execute a manifest command. Preserve the child command's exact exit code.
+
+## Maintain Catalogs
+
+- Keep `uid`, `id`, `group`, `summary`, `description`, and `command`.
+- Keep UIDs stable and never reuse one for materially different behavior.
+- Use `confirm: always` for destructive, release, deployment, migration, and
+  production-impacting operations.
+- Do not place secrets in `runx.yaml`.
+- Run `runx check` after every change.
+
+## Agent And Upgrade Commands
+
+```text
+runx agent skill list
+runx agent skill show guiho-s-runx
+runx agent instruction show
+runx agent prompt list --names
+runx agent prompt show guiho-i-runx
+runx upgrade check
+runx upgrade list
+runx upgrade --dry-run
+```
+
+Use `--help`, `--help-tree`, or `--help-docs` at any command scope for the
+current executable contract.