@guiho/runx 0.2.2 → 0.2.4

package/library/cli.js

@@ -1,60 +1,243 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
 import { resolve } from 'node:path';
+import { defineCommand, renderUsage, runCommand as runCittyCommand } from 'citty';
 import { installAgentInstructions, installAgentSkill } from './agents.js';
 import { RunXError } from './errors.js';
 import { runCommand } from './executor.js';
-import { booleanFlag, parseArgs, stringFlag } from './flags.js';
-import { readVersion, showCommandHelp, showHelpDocs, showHelpTree, showHome } from './help.js';
+import { readVersion, showHelpDocs, showHelpTree, showHome } from './help.js';
 import { readManifest, resolveCommand } from './manifest.js';
 import { renderDescription, renderExecutionPlan, renderJson, renderList } from './render.js';
 import { checkForLatestVersion, listAvailableVersions, uninstallSelf, upgradeSelf } from './self-management.js';
-const builtins = new Set(['list', 'describe', 'run', 'r', 'check', 'agents', 'upgrade', 'uninstall']);
-export const runCli = async (rawArgs = process.argv.slice(2)) => {
-    const parsed = parseArgs(rawArgs);
-    const options = resolveOptions(parsed.flags);
-    if (booleanFlag(parsed.flags, 'version'))
-        return write(`${readVersion()}\n`);
-    if (booleanFlag(parsed.flags, 'helpTree'))
-        return write(`${showHelpTree()}\n`);
-    if (booleanFlag(parsed.flags, 'helpDocs'))
-        return write(showHelpDocs());
-    if (booleanFlag(parsed.flags, 'help'))
-        return write(parsed.command && builtins.has(parsed.command) ? showCommandHelp(parsed.command) : showHome());
-    if (!parsed.command)
-        return write(showHome());
-    if (!builtins.has(parsed.command)) {
-        await runSelectedCommand(parsed.command, parsed.positionals, options, parsed.flags);
-        return;
+export { runCli, runCliWithErrorHandling, runxCommand, };
+class CliHandled extends Error {
+}
+class CliUsageError extends Error {
+    usage;
+    constructor(message, usage) {
+        super(message);
+        this.name = 'CliUsageError';
+        this.usage = usage;
     }
-    switch (parsed.command) {
-        case 'list':
-            await listCommands(options);
-            return;
-        case 'describe':
-            await describeCommand(parsed.positionals[0], options);
-            return;
-        case 'run':
-        case 'r':
-            await runSelectedCommand(parsed.positionals[0], parsed.positionals.slice(1), options, parsed.flags);
-            return;
-        case 'check':
-            await checkManifest(options);
-            return;
-        case 'agents':
-            await runAgents(parsed.positionals, options, parsed.flags);
-            return;
-        case 'upgrade':
-            await runUpgrade(parsed.positionals, options, parsed.flags);
-            return;
-        case 'uninstall':
-            await runUninstall(options, parsed.flags);
+}
+const commonArgs = {
+    cwd: { type: 'string', description: 'Resolve the manifest from this directory.', valueHint: 'path' },
+    file: { type: 'string', description: 'Use this runx.yaml file.', valueHint: 'path' },
+    format: { type: 'string', description: 'Select text or JSON output.', valueHint: 'text|json', default: 'text' },
+    verbose: { type: 'boolean', description: 'Enable additional diagnostics.' },
+    'help-tree': { type: 'boolean', description: 'Show the complete command hierarchy.' },
+    'help-docs': { type: 'boolean', description: 'Show manifest and agent guidance.' },
+    help: { type: 'boolean', alias: 'h', description: 'Show command help.' },
+    version: { type: 'boolean', alias: 'v', description: 'Show the RunX version.' },
+};
+const runArgs = {
+    ...commonArgs,
+    'dry-run': { type: 'boolean', description: 'Show the action without executing it.' },
+    yes: { type: 'boolean', description: 'Approve a confirmation-gated command.' },
+};
+const agentInstallArgs = {
+    ...commonArgs,
+    tool: { type: 'string', description: 'Select agents, claude, or all.', valueHint: 'agents|claude|all' },
+};
+const selfManagementArgs = {
+    ...commonArgs,
+    'dry-run': { type: 'boolean', description: 'Show the action without changing the executable.' },
+};
+const rootArgs = {
+    ...runArgs,
+    tool: agentInstallArgs.tool,
+};
+const knownArgumentKeys = new Set([
+    '_',
+    'cwd',
+    'file',
+    'format',
+    'verbose',
+    'dryRun',
+    'dry-run',
+    'yes',
+    'tool',
+    'helpTree',
+    'help-tree',
+    'helpDocs',
+    'help-docs',
+    'help',
+    'h',
+    'version',
+    'v',
+]);
+const createCommandTree = () => {
+    const state = { globalArgs: { _: [] }, usageCommand: {} };
+    const listCommand = defineCommand({
+        meta: { name: 'runx list', description: 'List commands in a RunX manifest.' },
+        args: commonArgs,
+        setup: withCommandHelp(state),
+        run: async () => listCommands(resolveOptions(state.globalArgs)),
+    });
+    const describeCommandDefinition = defineCommand({
+        meta: { name: 'runx describe', description: 'Describe one manifest command.' },
+        args: {
+            selector: { type: 'positional', description: 'Command UID, group/id, index, or unambiguous ID.' },
+            ...commonArgs,
+        },
+        setup: withCommandHelp(state),
+        run: async ({ args }) => {
+            if (!args.selector)
+                throw await missingSelector(state);
+            await describeCommand(args.selector, resolveOptions(state.globalArgs));
+        },
+    });
+    const runCommandDefinition = createRunCommand(state);
+    const checkCommand = defineCommand({
+        meta: { name: 'runx check', description: 'Validate a RunX manifest without executing it.' },
+        args: commonArgs,
+        setup: withCommandHelp(state),
+        run: async () => checkManifest(resolveOptions(state.globalArgs)),
+    });
+    const agentsInstallCommand = defineCommand({
+        meta: { name: 'runx agents install', description: 'Install the bundled RunX skill.' },
+        args: {
+            scope: { type: 'positional', description: 'Install locally or globally.', default: 'local', valueHint: 'local|global' },
+            ...agentInstallArgs,
+        },
+        setup: withCommandHelp(state),
+        run: async ({ args }) => runAgentsInstall(args.scope, resolveOptions(state.globalArgs), state.globalArgs),
+    });
+    const agentsInstructionsCommand = defineCommand({
+        meta: { name: 'runx agents instructions', description: 'Install or refresh managed RunX agent instructions.' },
+        args: commonArgs,
+        setup: withCommandHelp(state),
+        run: async () => runAgentsInstructions(resolveOptions(state.globalArgs)),
+    });
+    const agentsCommand = defineCommand({
+        meta: { name: 'runx agents', description: 'Manage the bundled RunX agent integration.' },
+        args: agentInstallArgs,
+        subCommands: {
+            install: agentsInstallCommand,
+            instructions: agentsInstructionsCommand,
+        },
+        setup: withCommandHelp(state),
+    });
+    const upgradeApplyCommand = defineCommand({
+        meta: { name: 'runx upgrade', description: 'Upgrade a native RunX executable.', hidden: true },
+        args: selfManagementArgs,
+        setup: withCommandHelp(state),
+        run: async () => runUpgrade(resolveOptions(state.globalArgs), state.globalArgs),
+    });
+    const upgradeCheckCommand = defineCommand({
+        meta: { name: 'runx upgrade check', description: 'Check whether a newer RunX release is available.' },
+        args: commonArgs,
+        setup: withCommandHelp(state),
+        run: async () => runUpgradeCheck(resolveOptions(state.globalArgs)),
+    });
+    const upgradeListCommand = defineCommand({
+        meta: { name: 'runx upgrade list', description: 'List recent RunX release versions.' },
+        args: commonArgs,
+        setup: withCommandHelp(state),
+        run: async () => runUpgradeList(resolveOptions(state.globalArgs)),
+    });
+    const upgradeCommand = defineCommand({
+        meta: { name: 'runx upgrade', description: 'Inspect or upgrade a native RunX executable.' },
+        args: selfManagementArgs,
+        default: '_apply',
+        subCommands: {
+            _apply: upgradeApplyCommand,
+            check: upgradeCheckCommand,
+            list: upgradeListCommand,
+        },
+        setup: withCommandHelp(state),
+    });
+    const uninstallCommand = defineCommand({
+        meta: { name: 'runx uninstall', description: 'Uninstall a native RunX executable.' },
+        args: selfManagementArgs,
+        setup: withCommandHelp(state),
+        run: async () => runUninstall(resolveOptions(state.globalArgs), state.globalArgs),
+    });
+    const homeCommand = defineCommand({
+        meta: { name: 'runx', description: 'Show the RunX home page.', hidden: true },
+        args: rootArgs,
+        setup: withCommandHelp(state),
+        run: () => write(showHome()),
+    });
+    const staticSubCommands = Object.assign(Object.create(null), {
+        _home: homeCommand,
+        list: listCommand,
+        describe: describeCommandDefinition,
+        run: runCommandDefinition,
+        check: checkCommand,
+        agents: agentsCommand,
+        upgrade: upgradeCommand,
+        uninstall: uninstallCommand,
+    });
+    const usageCommands = new Map([
+        ['list', listCommand],
+        ['describe', describeCommandDefinition],
+        ['run', runCommandDefinition],
+        ['r', runCommandDefinition],
+        ['check', checkCommand],
+        ['agents', agentsCommand],
+        ['agents install', agentsInstallCommand],
+        ['agents instructions', agentsInstructionsCommand],
+        ['upgrade', upgradeCommand],
+        ['upgrade check', upgradeCheckCommand],
+        ['upgrade list', upgradeListCommand],
+        ['uninstall', uninstallCommand],
+    ]);
+    const subCommands = createSelectorCompatibleCommands(staticSubCommands, state);
+    const command = defineCommand({
+        meta: {
+            name: 'runx',
+            version: readVersion(),
+            description: 'A documented, local command catalog for runx.yaml manifests.',
+        },
+        args: rootArgs,
+        default: '_home',
+        subCommands,
+        setup: async (context) => {
+            state.globalArgs = context.args;
+            state.usageCommand = resolveUsageCommand(context.args._, usageCommands, state);
+            await validateArguments(context, state);
+            if (state.globalArgs.version || state.globalArgs.v)
+                return handleOutput(`${readVersion()}\n`);
+            if (state.globalArgs.helpTree)
+                return handleOutput(`${showHelpTree()}\n`);
+            if (state.globalArgs.helpDocs)
+                return handleOutput(showHelpDocs());
+            if (state.globalArgs.help || state.globalArgs.h)
+                return handleUsage(state.usageCommand);
+        },
+    });
+    state.usageCommand = command;
+    return { command, state };
+};
+const { command: runxCommand } = createCommandTree();
+async function runCli(rawArgs = process.argv.slice(2)) {
+    const { command, state } = createCommandTree();
+    try {
+        await runCittyCommand(command, { rawArgs });
+    }
+    catch (error) {
+        if (error instanceof CliHandled)
             return;
+        if (error instanceof CliUsageError)
+            throw error;
+        if (isCittyUsageError(error)) {
+            throw new CliUsageError(error.message, await renderUsage(state.usageCommand));
+        }
+        throw error;
     }
-};
-export const runCliWithErrorHandling = async (rawArgs) => {
+}
+async function runCliWithErrorHandling(rawArgs) {
     try {
         await runCli(rawArgs);
     }
     catch (error) {
+        if (error instanceof CliUsageError) {
+            process.stderr.write(`${error.usage}\n\nerror: ${error.message}\n`);
+            process.exitCode = 1;
+            return;
+        }
         if (error instanceof RunXError) {
             process.stderr.write(`error: ${error.message}\n`);
             process.exitCode = error.exitCode;
@@ -63,84 +246,155 @@ export const runCliWithErrorHandling = async (rawArgs) => {
         process.stderr.write(`error: ${error instanceof Error ? error.message : 'Unexpected failure.'}\n`);
         process.exitCode = 1;
     }
-};
-const listCommands = async (options) => {
+}
+function createRunCommand(state, selectorDefault) {
+    return defineCommand({
+        meta: {
+            name: selectorDefault ? 'runx <selector>' : 'runx run',
+            alias: selectorDefault ? undefined : 'r',
+            description: selectorDefault ? 'Run a selector using the root shorthand.' : 'Run one manifest command.',
+        },
+        args: selectorDefault
+            ? runArgs
+            : {
+                selector: { type: 'positional', description: 'Command UID, group/id, index, or unambiguous ID.' },
+                ...runArgs,
+            },
+        setup: withCommandHelp(state),
+        run: async ({ args }) => {
+            const selector = selectorDefault ?? (typeof args.selector === 'string' ? args.selector : undefined);
+            if (!selector)
+                throw await missingSelector(state);
+            await runSelectedCommand(selector, resolveOptions(state.globalArgs), state.globalArgs);
+        },
+    });
+}
+function createSelectorCompatibleCommands(commands, state) {
+    const aliases = new Set(['r']);
+    return new Proxy(commands, {
+        has: (target, property) => {
+            if (typeof property !== 'string')
+                return Reflect.has(target, property);
+            if (aliases.has(property))
+                return false;
+            return true;
+        },
+        get: (target, property, receiver) => {
+            if (typeof property !== 'string' || Reflect.has(target, property))
+                return Reflect.get(target, property, receiver);
+            return createRunCommand(state, property);
+        },
+    });
+}
+function resolveUsageCommand(positionals, commands, state) {
+    const name = positionals[0];
+    if (!name)
+        return state.usageCommand;
+    if (!commands.has(name))
+        return createRunCommand(state, name);
+    for (let length = positionals.length; length > 0; length -= 1) {
+        const command = commands.get(positionals.slice(0, length).join(' '));
+        if (command)
+            return command;
+    }
+    return commands.get(name);
+}
+function withCommandHelp(state) {
+    return (context) => {
+        state.usageCommand = context.cmd;
+    };
+}
+async function missingSelector(state) {
+    return new CliUsageError('Missing required positional argument: SELECTOR', await renderUsage(state.usageCommand));
+}
+async function validateArguments(context, state) {
+    const unknown = Object.keys(context.args).find((key) => !knownArgumentKeys.has(key));
+    if (!unknown)
+        return;
+    throw new CliUsageError(`Unknown option --${unknown}`, await renderUsage(state.usageCommand));
+}
+async function handleUsage(command) {
+    return handleOutput(`${await renderUsage(command)}\n`);
+}
+function handleOutput(value) {
+    write(value);
+    throw new CliHandled();
+}
+async function listCommands(options) {
     const { manifest, path } = await readManifest(options.cwd, options.file);
     write(options.format === 'json' ? renderJson({ manifestPath: path, manifest }) : renderList(manifest, path));
-};
-const describeCommand = async (selector, options) => {
-    if (!selector)
-        throw new RunXError('Missing selector. Usage: runx describe <selector>');
+}
+async function describeCommand(selector, options) {
     const { manifest, path } = await readManifest(options.cwd, options.file);
     const command = resolveCommand(manifest, path, selector);
     write(options.format === 'json' ? renderJson(command) : renderDescription(command));
-};
-const checkManifest = async (options) => {
+}
+async function checkManifest(options) {
     const { manifest, path } = await readManifest(options.cwd, options.file);
     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`);
-};
-const runSelectedCommand = async (selector, _, options, flags) => {
-    if (!selector)
-        throw new RunXError('Missing selector. Usage: runx run <selector>');
+}
+async function runSelectedCommand(selector, options, args) {
     const { manifest, path } = await readManifest(options.cwd, options.file);
     const command = resolveCommand(manifest, path, selector);
-    if (booleanFlag(flags, 'dryRun')) {
+    if (args.dryRun) {
         write(options.format === 'json' ? renderJson({ dryRun: true, command }) : renderExecutionPlan(command));
         return;
     }
-    if (command.confirm === 'always' && !booleanFlag(flags, 'yes')) {
+    if (command.confirm === 'always' && !args.yes) {
         throw new RunXError(`Command ${command.uid} requires confirmation. Review it with \`runx describe ${command.uid}\` and rerun with --yes when authorized.`);
     }
     if (options.format === 'text')
         write(`Running ${command.uid} (${command.selector})\n`);
-    const exitCode = await runCommand(command);
-    process.exitCode = exitCode;
-};
-const runAgents = async (positionals, options, flags) => {
-    const action = positionals[0];
-    if (action === 'install') {
-        const scope = (positionals[1] ?? 'local');
-        if (scope !== 'local' && scope !== 'global')
-            throw new RunXError('Agent scope must be local or global.');
-        const tool = (stringFlag(flags, 'tool') ?? 'agents');
-        if (!['agents', 'claude', 'all'].includes(tool))
-            throw new RunXError('Agent tool must be agents, claude, or all.');
-        const installed = await installAgentSkill(scope, tool, options.cwd);
-        write(options.format === 'json' ? renderJson({ installed }) : `${installed.map((path) => `installed: ${path}`).join('\n')}\n`);
-        return;
-    }
-    if (action === 'instructions') {
-        const path = await installAgentInstructions(options.cwd);
-        write(options.format === 'json' ? renderJson({ instructions: path }) : `updated: ${path}\n`);
-        return;
-    }
-    throw new RunXError('Usage: runx agents install <local|global> [--tool agents|claude|all] | runx agents instructions');
-};
-const runUpgrade = async (positionals, options, flags) => {
-    if (positionals[0] === 'check') {
-        const result = await checkForLatestVersion();
-        write(options.format === 'json' ? renderJson(result) : `current: ${result.currentVersion}\nlatest: ${result.latestVersion}\nupdate_available: ${result.updateAvailable}\n`);
-        return;
-    }
-    if (positionals[0] === 'list') {
-        const versions = await listAvailableVersions();
-        write(options.format === 'json' ? renderJson({ versions }) : `${versions.join('\n')}\n`);
-        return;
-    }
-    const result = await upgradeSelf(booleanFlag(flags, 'dryRun'));
-    write(options.format === 'json' ? renderJson(result) : `current: ${result.currentVersion}\ntarget: ${result.latestVersion}\npath: ${result.executablePath}\n${result.scheduled ? 'scheduled: true\n' : ''}`);
-};
-const runUninstall = async (options, flags) => {
-    const result = await uninstallSelf(booleanFlag(flags, 'dryRun'));
+    process.exitCode = await runCommand(command);
+}
+async function runAgentsInstall(scopeValue, options, args) {
+    const scope = scopeValue;
+    if (scope !== 'local' && scope !== 'global')
+        throw new RunXError('Agent scope must be local or global.');
+    const tool = (args.tool ?? 'agents');
+    if (!['agents', 'claude', 'all'].includes(tool))
+        throw new RunXError('Agent tool must be agents, claude, or all.');
+    const installed = await installAgentSkill(scope, tool, options.cwd);
+    write(options.format === 'json' ? renderJson({ installed }) : `${installed.map((path) => `installed: ${path}`).join('\n')}\n`);
+}
+async function runAgentsInstructions(options) {
+    const path = await installAgentInstructions(options.cwd);
+    write(options.format === 'json' ? renderJson({ instructions: path }) : `updated: ${path}\n`);
+}
+async function runUpgradeCheck(options) {
+    const result = await checkForLatestVersion();
+    write(options.format === 'json' ? renderJson(result) : `current: ${result.currentVersion}\nlatest: ${result.latestVersion}\nupdate_available: ${result.updateAvailable}\n`);
+}
+async function runUpgradeList(options) {
+    const versions = await listAvailableVersions();
+    write(options.format === 'json' ? renderJson({ versions }) : `${versions.join('\n')}\n`);
+}
+async function runUpgrade(options, args) {
+    const result = await upgradeSelf(Boolean(args.dryRun));
+    if (options.format === 'json')
+        return write(renderJson(result));
+    const summary = `current: ${result.currentVersion}\ntarget: ${result.latestVersion}\n`;
+    write(result.upToDate ? `${summary}Already up to date.\n` : `${summary}path: ${result.executablePath}\n${result.scheduled ? 'scheduled: true\n' : ''}`);
+}
+async function runUninstall(options, args) {
+    const result = await uninstallSelf(Boolean(args.dryRun));
     write(options.format === 'json' ? renderJson(result) : `path: ${result.executablePath}\n${result.dryRun ? 'dry_run: true\n' : result.scheduled ? 'scheduled: true\n' : 'uninstalled: true\n'}`);
-};
-const resolveOptions = (flags) => {
-    const format = stringFlag(flags, 'format') ?? 'text';
+}
+function resolveOptions(args) {
+    const format = args.format ?? 'text';
     if (format !== 'text' && format !== 'json')
         throw new RunXError('Invalid --format value. Expected text or json.');
-    return { cwd: resolve(stringFlag(flags, 'cwd') ?? process.cwd()), file: stringFlag(flags, 'file'), format: format, verbose: booleanFlag(flags, 'verbose') };
-};
-const write = (value) => {
+    return {
+        cwd: resolve(args.cwd ?? process.cwd()),
+        file: args.file,
+        format: format,
+        verbose: Boolean(args.verbose),
+    };
+}
+function isCittyUsageError(error) {
+    return error instanceof Error && error.name === 'CLIError';
+}
+function write(value) {
     process.stdout.write(value);
-};
+}

package/library/help.d.ts

@@ -2,5 +2,4 @@ export declare const readVersion: () => string;
 export declare const showHome: () => string;
 export declare const showHelpTree: () => string;
 export declare const showHelpDocs: () => string;
-export declare const showCommandHelp: (command: string) => string;
 //# sourceMappingURL=help.d.ts.map

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;AAED,eAAO,MAAM,eAAe,YAAa,MAAM,KAAG,MAGjD,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,MAe3B,CAAA;AAED,eAAO,MAAM,YAAY,QAAO,MAapB,CAAA;AAEZ,eAAO,MAAM,YAAY,QAAO,MAU/B,CAAA"}

package/library/help.js

@@ -41,7 +41,3 @@ Use UID values for automation. Use runx describe <selector> and runx run <select
 
 Agent skill: runx agents install local installs guiho-s-runx under .agents/skills.
 `;
-export const showCommandHelp = (command) => `RunX ${command}
-
-Run \`runx --help-tree\` for command structure and \`runx --help-docs\` for manifest guidance.
-`;

package/library/self-management.d.ts

@@ -1,10 +1,7 @@
-import type { UpdateResult } from './types.js';
+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<UpdateResult & {
-    executablePath: string;
-    scheduled: boolean;
-}>;
+export declare const upgradeSelf: (dryRun: boolean) => Promise<RunXUpgradeResult>;
 export declare const uninstallSelf: (dryRun: boolean) => Promise<{
     executablePath: string;
     scheduled: 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,YAAY,EAAE,MAAM,YAAY,CAAA;AAM9C,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,YAAY,GAAG;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAkBxH,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":"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"}

package/library/self-management.js

@@ -28,10 +28,11 @@ export const listAvailableVersions = async () => {
 export const upgradeSelf = async (dryRun) => {
     const executablePath = requireNativeExecutable();
     const update = await checkForLatestVersion();
+    const upToDate = !update.updateAvailable && update.latestVersion === update.currentVersion && Boolean(update.url);
     if (!update.updateAvailable || !update.url)
-        return { ...update, executablePath, scheduled: false };
+        return { ...update, executablePath, scheduled: false, upToDate };
     if (dryRun)
-        return { ...update, executablePath, scheduled: false };
+        return { ...update, executablePath, scheduled: false, upToDate: false };
     const response = await fetch(update.url);
     if (!response.ok)
         throw new RunXError(`Could not download RunX update: HTTP ${response.status}`);
@@ -40,10 +41,10 @@ export const upgradeSelf = async (dryRun) => {
     if (process.platform !== 'win32') {
         await chmod(temporaryPath, 0o755);
         await rename(temporaryPath, executablePath);
-        return { ...update, executablePath, scheduled: false };
+        return { ...update, executablePath, scheduled: false, upToDate: false };
     }
     scheduleWindowsReplacement(temporaryPath, executablePath);
-    return { ...update, executablePath, scheduled: true };
+    return { ...update, executablePath, scheduled: true, upToDate: false };
 };
 export const uninstallSelf = async (dryRun) => {
     const executablePath = requireNativeExecutable();
@@ -60,7 +61,7 @@ export const uninstallSelf = async (dryRun) => {
 const findAsset = (release) => release.assets.find((asset) => asset.name === assetName());
 const assetName = () => `runx-${process.platform === 'win32' ? 'windows' : process.platform === 'darwin' ? 'darwin' : 'linux'}-${process.arch}${process.platform === 'win32' ? '.exe' : ''}`;
 const requireNativeExecutable = () => {
-    const executablePath = process.execPath;
+    const executablePath = process.env['RUNX_SELF_PATH'] ?? process.execPath;
     if (basename(executablePath).toLowerCase().startsWith('bun'))
         throw new RunXError('Self-management requires a native RunX executable installed from a GitHub release.');
     return executablePath;

package/library/types.d.ts

@@ -9,11 +9,6 @@ export type ResolvedCommand = RunXCommand & {
     cwd: string;
 };
 export type OutputFormat = 'text' | 'json';
-export type ParsedArgs = {
-    command?: string;
-    positionals: string[];
-    flags: Record<string, boolean | string | string[]>;
-};
 export type CliOptions = {
     cwd: string;
     file?: string;
@@ -28,4 +23,9 @@ export type UpdateResult = {
     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,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,CAAA;CACnD,CAAA;AAED,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"}
+{"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/runx",
   "description": "A language-agnostic, documented command catalog and local CLI executor.",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "main": "./library/guiho-runx.js",
   "types": "./library/guiho-runx.d.ts",
@@ -68,7 +68,8 @@
     "_uid": "bun nanoid --alphabet abcdefghijklmnopqrstuvwxyz0123456789"
   },
   "dependencies": {
-    "@sinclair/typebox": "^0.34.52"
+    "@sinclair/typebox": "^0.34.52",
+    "citty": "^0.2.2"
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",