@laitszkin/apollo-toolkit 4.1.3 → 5.0.0

package/packages/cli/dist/index.js

@@ -1,257 +1,50 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { color, supportsColor, buildBanner, buildWelcomeScreen, buildSupportedTargetLines, animateWelcomeScreen, promptYesNo, promptForModes, isInteractive } from '../../tui/dist/index.js';
-import { formatToolList, buildToolDiscoveryHelp, runTool } from '../../tool-registry/dist/index.js';
-import { formatExamples } from '../../tool-registry/dist/index.js';
+import { color, supportsColor, buildBanner, buildWelcomeScreen, animateWelcomeScreen, promptYesNo, promptForModes, isInteractive, createStdioWriter } from '../../tui/dist/index.js';
+import { runTool } from '../../tool-registry/dist/index.js';
 import { TARGET_DEFINITIONS, VALID_MODES, installLinks, listAllKnownSkillNames, listCodexSkillNames, normalizeModes, resolveToolkitHome, syncToolkitHome, uninstallSkills, getTargetRoots, getUninstallTargetRoots, expandUserPath, readManifest, writeManifest, resolveHomeDirectory, listSkillNames, } from './installer.js';
 import { checkForPackageUpdate, compareVersions, execCommand } from './updater.js';
 import { registerAllTools, isKnownToolName } from './tool-registration.js';
 // Re-export installer functions for external consumers (tests, bin)
 export { TARGET_DEFINITIONS, VALID_MODES, installLinks, listAllKnownSkillNames, listCodexSkillNames, normalizeModes, resolveToolkitHome, syncToolkitHome, uninstallSkills, getTargetRoots, getUninstallTargetRoots, expandUserPath, readManifest, writeManifest, resolveHomeDirectory, listSkillNames, checkForPackageUpdate, compareVersions, execCommand, };
-function buildModeUsagePattern() {
-    return `${VALID_MODES.join('|')}|all`;
-}
-function buildInteractiveModeHint() {
-    const quotedModes = [...VALID_MODES, 'all'].map((mode) => `\`${mode}\``);
-    return `${quotedModes.slice(0, -1).join(', ')}, or ${quotedModes.at(-1)}`;
-}
-function buildHelpText({ version, colorEnabled }) {
-    const examples = [
-        { command: 'apltk --help', result: 'Shows the top-level Apollo Toolkit guide, including install modes and bundled task-tool discovery.' },
-        { command: 'apltk tools --help', result: 'Lists bundled tools by task so you can decide which CLI helper to inspect next.' },
-        { command: 'apltk architecture --help', result: 'Shows the architecture atlas command tree, task guidance, and action-specific follow-up help paths.' },
-        { command: 'apltk tools architecture --help', result: 'Shows what the architecture atlas tool is for, then prints its native command tree and examples.' },
-        { command: 'apltk filter-logs app.log --start 2026-03-24T10:00:00Z', result: 'Prints only the log lines whose timestamps fall within the requested time window.' },
-    ];
-    return [
-        buildBanner({ version, colorEnabled }),
-        '',
-        'Usage:',
-        `  apltk [install] [${buildModeUsagePattern()}]...`,
-        `  apollo-toolkit [install] [${buildModeUsagePattern()}]...`,
-        `  apltk uninstall [${buildModeUsagePattern()}]... [--yes]`,
-        '  apltk tools',
-        '  apltk <tool> [...args]',
-        '  apltk tools <tool> [...args]',
-        '  apltk --help',
-        '  apollo-toolkit --help',
-        '',
-        'Common goals:',
-        '  - Install or refresh skills in one or more agent targets: `apltk install --help`',
-        '  - Remove manifest-tracked installs from selected targets: `apltk uninstall --help`',
-        '  - Discover which bundled helper tool matches a task: `apltk tools --help`',
-        '  - Inspect one tool deeply before running it: `apltk tools <tool> --help`',
-        '',
-        'Bundled tools:',
-        formatToolList(),
-        '',
-        buildToolDiscoveryHelp(),
-        '',
-        'Options:',
-        '  --home <path>  Override Apollo Toolkit home directory',
-        '  --symlink      Install skills as symlinks instead of copied directories',
-        '  --copy         Install skills as copied directories instead of symlinks',
-        '  --yes, -y      Skip uninstall confirmation',
-        '  --help         Show this help text',
-        '',
-        'Examples:',
-        formatExamples(examples),
-    ].join('\n');
-}
-function buildToolsHelp({ version, colorEnabled }) {
-    const examples = [
-        { command: 'apltk tools', result: 'Lists all bundled tools plus the task-oriented discovery guide.' },
-        { command: 'apltk tools open-github-issue --help', result: 'Shows when to use the GitHub issue publisher, then prints its exact script flags and examples.' },
-        { command: 'apltk tools architecture --help', result: 'Shows when to use the architecture atlas CLI, then prints its native command tree.' },
-    ];
-    return [
-        buildBanner({ version, colorEnabled }),
-        '',
-        'Usage:',
-        '  apltk tools',
-        '  apltk <tool> [...args]',
-        '  apltk tools <tool> [...args]',
-        '',
-        buildToolDiscoveryHelp(),
-        '',
-        'Bundled tools:',
-        formatToolList(),
-        '',
-        'Tip:',
-        '  Pass `--help` after a tool name to view task guidance, native script flags, and concrete examples.',
-        '',
-        'Examples:',
-        formatExamples(examples),
-    ].join('\n');
-}
-function buildInstallHelpText({ version, colorEnabled }) {
-    const examples = [
-        { command: 'apltk', result: 'Launches the interactive installer, opens the target selector, and then walks through link-mode confirmation.' },
-        { command: 'apltk codex openclaw --symlink', result: 'Performs a non-interactive install into `codex` and `openclaw` targets using symlinks.' },
-        { command: 'npx @laitszkin/apollo-toolkit all --copy', result: 'Installs a copied snapshot into every supported target instead of symlinking.' },
-    ];
-    return [
-        buildBanner({ version, colorEnabled }),
-        '',
-        'Usage:',
-        `  apltk [install] [${buildModeUsagePattern()}]...`,
-        `  apollo-toolkit [install] [${buildModeUsagePattern()}]...`,
-        '',
-        'Use this when:',
-        '  - You want to install or refresh Apollo Toolkit skills in one or more agent targets.',
-        '  - You need to choose between symlink mode (auto-updating) and copy mode (stable snapshot).',
-        '',
-        'Supported targets:',
-        buildSupportedTargetLines({ targets: [...TARGET_DEFINITIONS], colorEnabled }),
-        '',
-        'Behavior notes:',
-        '  - Running `apltk` with no targets opens the interactive installer and target selector.',
-        '  - `--symlink` keeps installed skills connected to the managed toolkit checkout in `~/.apollo-toolkit`.',
-        '  - `--copy` installs a snapshot that only changes when you run the installer again.',
-        '  - The installer can optionally include codex-exclusive skills in non-codex targets after prompting.',
-        '',
-        'Options:',
-        '  --home <path>  Override Apollo Toolkit home directory',
-        '  --symlink      Install skills as symlinks (recommended)',
-        '  --copy         Install skills as copied directories',
-        '  --help         Show this install help',
-        '',
-        'Examples:',
-        formatExamples(examples),
-    ].join('\n');
-}
-function buildUninstallHelpText({ version, colorEnabled }) {
-    const examples = [
-        { command: 'apltk uninstall', result: 'Opens the interactive uninstall selector when running in a TTY and then asks for confirmation before removal.' },
-        { command: 'apltk uninstall codex agents --yes', result: 'Removes Apollo Toolkit-managed installs from `codex` and `agents` without another confirmation prompt.' },
-        { command: 'apltk uninstall codex --home /tmp/custom-home', result: 'Uses the custom managed toolkit home while removing manifest-tracked installs from the selected target.' },
-    ];
-    return [
-        buildBanner({ version, colorEnabled }),
-        '',
-        'Usage:',
-        `  apltk uninstall [${buildModeUsagePattern()}]... [--yes]`,
-        '',
-        'Use this when:',
-        '  - You want to remove Apollo Toolkit-managed skills from one or more agent targets.',
-        '  - You need to clean up manifest-tracked historical installs as well as the current installed skills.',
-        '',
-        'Supported targets:',
-        buildSupportedTargetLines({ targets: [...TARGET_DEFINITIONS], colorEnabled }),
-        '',
-        'Behavior notes:',
-        '  - With no explicit targets, uninstall opens the interactive selector in a TTY and otherwise falls back to all targets.',
-        '  - Uninstall removes manifest-tracked current and historical Apollo Toolkit skill directories.',
-        '  - `--yes` skips the confirmation prompt after the target list is resolved.',
-        '',
-        'Options:',
-        '  --home <path>  Override Apollo Toolkit home directory',
-        '  --yes, -y      Skip uninstall confirmation',
-        '  --help         Show this uninstall help',
-        '',
-        'Examples:',
-        formatExamples(examples),
-    ].join('\n');
-}
+import { formatAppError } from '../../tool-utils/dist/index.js';
+import { InstallArgsParser } from './parsers/install-parser.js';
+import { UninstallArgsParser } from './parsers/uninstall-parser.js';
+import { ToolArgsParser } from './parsers/tool-parser.js';
+import { HelpTextBuilder } from './help-text-builder.js';
 function readPackageJson(sourceRoot) {
     return JSON.parse(fs.readFileSync(path.join(sourceRoot, 'package.json'), 'utf8'));
 }
 function parseArguments(argv) {
-    const args = [...argv];
-    const result = {
-        command: 'install',
-        modes: [],
-        showHelp: false,
-        showToolsHelp: false,
-        toolkitHome: null,
-        toolName: null,
-        toolArgs: [],
-        linkMode: null,
-        assumeYes: false,
-        explicitInstallCommand: false,
-        helpTopic: 'overview',
-    };
-    if (args[0] === 'uninstall') {
-        result.command = 'uninstall';
-        args.shift();
-        while (args.length > 0) {
-            const arg = args.shift();
-            if (arg === '--help' || arg === '-h') {
-                result.showHelp = true;
-            }
-            else if (arg === '--yes' || arg === '-y') {
-                result.assumeYes = true;
-            }
-            else if (arg === '--home') {
-                const toolkitHome = args.shift();
-                if (!toolkitHome)
-                    throw new Error('Missing value for --home');
-                result.toolkitHome = path.resolve(toolkitHome);
-            }
-            else {
-                result.modes.push(arg);
-            }
+    const firstArg = argv[0];
+    // Shared parser instances (eliminates double instantiation)
+    const installParser = new InstallArgsParser();
+    const toolParser = new ToolArgsParser();
+    // Dispatch table for all known command types
+    // ==== Collision zone (FIX-09) ====
+    // L55-190 and L349-360 are high-collision regions touched by dispatch,
+    // parser, and error-boundary changes.  Modify with care.
+    // =================================
+    const commandParsers = new Map([
+        ['install', installParser],
+        ['uninstall', new UninstallArgsParser()],
+        ['tools', toolParser],
+        ['tool', toolParser],
+    ]);
+    // Command dispatch: iterate parsers, first match wins
+    for (const [name, parser] of commandParsers) {
+        if (firstArg === name) {
+            const result = parser.parse(argv);
+            return parser.toParsedArguments(result);
         }
-        if (result.showHelp)
-            result.helpTopic = 'uninstall';
-        return result;
     }
-    if (args[0] === 'tools' || args[0] === 'tool') {
-        args.shift();
-        const nextArg = args[0];
-        if (args.length === 0 || nextArg === '--help' || nextArg === '-h') {
-            result.command = 'tools-help';
-            result.showToolsHelp = true;
-            return result;
-        }
-        result.command = 'tool';
-        result.toolName = args.shift() || null;
-        result.toolArgs = args;
-        return result;
-    }
-    const firstArg = args[0];
+    // Direct tool name (no "tools" prefix) — route through the 'tool' dispatch table entry
     if (firstArg && isKnownToolName(firstArg)) {
-        result.command = 'tool';
-        result.toolName = args.shift() || null;
-        result.toolArgs = args;
-        return result;
-    }
-    while (args.length > 0) {
-        const arg = args.shift();
-        if (arg === '--help' || arg === '-h') {
-            result.showHelp = true;
-            continue;
-        }
-        if (arg === '--home') {
-            const toolkitHome = args.shift();
-            if (!toolkitHome)
-                throw new Error('Missing value for --home');
-            result.toolkitHome = path.resolve(toolkitHome);
-            continue;
-        }
-        if (arg === '--symlink') {
-            result.linkMode = 'symlink';
-            continue;
-        }
-        if (arg === '--copy') {
-            result.linkMode = 'copy';
-            continue;
-        }
-        if (arg === 'install') {
-            result.explicitInstallCommand = true;
-            continue;
-        }
-        result.modes.push(arg);
-    }
-    if (result.showHelp) {
-        const installContextRequested = result.explicitInstallCommand
-            || result.modes.length > 0
-            || result.linkMode !== null
-            || result.toolkitHome !== null;
-        result.helpTopic = installContextRequested ? 'install' : 'overview';
+        return toolParser.toParsedArguments(toolParser.parse(argv));
     }
-    return result;
+    // Default: install (handles bare arguments like "codex", "--help", or empty argv)
+    return installParser.toParsedArguments(installParser.parse(argv));
 }
 function buildSymlinkInfo({ colorEnabled }) {
     return [
@@ -326,7 +119,12 @@ function printUninstallSummary({ stdout, uninstallResult, env }) {
         stdout.write(`  Removed: ${result.removedSkills.length > 0 ? result.removedSkills.join(', ') : '(manifest only)'}\n`);
     }
 }
-export { parseArguments, buildHelpText, buildInstallHelpText, buildUninstallHelpText, buildToolsHelp, buildBanner, buildWelcomeScreen, registerAllTools };
+export { InstallArgsParser } from './parsers/install-parser.js';
+export { UninstallArgsParser } from './parsers/uninstall-parser.js';
+export { ToolArgsParser } from './parsers/tool-parser.js';
+export { HelpTextBuilder } from './help-text-builder.js';
+export { normalizeParseError } from './parsers/parser-utils.js';
+export { parseArguments, buildBanner, buildWelcomeScreen, registerAllTools };
 export async function run(argv, context = {}) {
     const __filename = fileURLToPath(import.meta.url);
     const __dir = path.dirname(__filename);
@@ -335,6 +133,7 @@ export async function run(argv, context = {}) {
     const stderr = context.stderr || process.stderr;
     const stdin = context.stdin || process.stdin;
     const env = context.env || process.env;
+    const stdioWriter = createStdioWriter({ stdout, stderr, env });
     let packageJson = readPackageJson(sourceRoot);
     try {
         const parsed = parseArguments(argv);
@@ -342,23 +141,30 @@ export async function run(argv, context = {}) {
             const colorEnabled = supportsColor(stdout, env);
             if (parsed.helpTopic === 'overview')
                 await registerAllTools();
+            const builder = new HelpTextBuilder({ version: packageJson.version, colorEnabled });
             const helpText = parsed.helpTopic === 'install'
-                ? buildInstallHelpText({ version: packageJson.version, colorEnabled })
+                ? builder.install()
                 : parsed.helpTopic === 'uninstall'
-                    ? buildUninstallHelpText({ version: packageJson.version, colorEnabled })
-                    : buildHelpText({ version: packageJson.version, colorEnabled });
+                    ? builder.uninstall()
+                    : builder.overview();
             stdout.write(`${helpText}\n`);
             return 0;
         }
         if (parsed.showToolsHelp) {
             await registerAllTools();
-            stdout.write(`${buildToolsHelp({ version: packageJson.version, colorEnabled: supportsColor(stdout, env) })}\n`);
+            stdout.write(`${new HelpTextBuilder({ version: packageJson.version, colorEnabled: supportsColor(stdout, env) }).toolsHelp()}\n`);
             return 0;
         }
+        // Tool dispatch error patterns (FIX-10):
+        // Pattern A (createToolRunner tools): handler throws -> caught internally ->
+        //   formatAppError + return 1
+        // Pattern B (carryover tools): handler throws -> propagates through runTool ->
+        //   CLI boundary catch -> formatAppError + return 1
+        // Both patterns converge on the same formatting at the boundary.
         if (parsed.command === 'tool') {
             await registerAllTools();
-            return (context.runTool || runTool)(parsed.toolName, parsed.toolArgs, {
-                sourceRoot, stdout, stderr, env, spawnCommand: context.spawnCommand,
+            return await (context.runTool || runTool)(parsed.toolName, parsed.toolArgs, {
+                sourceRoot, stdout, stderr, env, spawnCommand: context.spawnCommand, stdioWriter,
             });
         }
         // Uninstall flow
@@ -465,7 +271,7 @@ export async function run(argv, context = {}) {
         return 0;
     }
     catch (error) {
-        stderr.write(`Error: ${error.message}\n`);
+        formatAppError(stderr, error);
         return 1;
     }
 }

package/packages/cli/dist/installer.d.ts

@@ -14,6 +14,7 @@ export declare function normalizeModes(inputModes: string[]): InstallMode[];
 export declare function listSkillNames(rootDir: string, modes?: InstallMode[]): Promise<string[]>;
 export declare function listCodexSkillNames(rootDir: string): Promise<string[]>;
 export declare function readManifest(targetRoot: string): Promise<ManifestData | null>;
+export declare function isSafeSkillName(skillName: string): boolean;
 export declare function writeManifest(targetRoot: string, { version, linkMode, skills, previousSkills }: {
     version: string;
     linkMode: string;

package/packages/cli/dist/installer.js

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
-import os from 'node:os';
 import path from 'node:path';
+import { createPlatformAdapter } from '../../tool-utils/dist/index.js';
+const platformAdapter = createPlatformAdapter();
 export const TARGET_DEFINITIONS = Object.freeze([
     { id: 'codex', label: 'Codex', description: '~/.codex/skills' },
     { id: 'openclaw', label: 'OpenClaw', description: '~/.openclaw/workspace*/skills' },
@@ -14,7 +15,7 @@ const COPY_FILES = new Set(['AGENTS.md', 'CHANGELOG.md', 'LICENSE', 'README.md',
 const SKILLS_DIRNAME = 'skills';
 export const MANIFEST_FILENAME = '.apollo-toolkit-manifest.json';
 export function resolveHomeDirectory(env = process.env) {
-    return env.HOME || env.USERPROFILE || os.homedir();
+    return createPlatformAdapter().homeDir(env);
 }
 export function expandUserPath(inputPath, env = process.env) {
     if (!inputPath)
@@ -99,12 +100,12 @@ export async function readManifest(targetRoot) {
         return null;
     }
 }
-function isSafeSkillName(skillName) {
+export function isSafeSkillName(skillName) {
     return typeof skillName === 'string'
         && skillName.length > 0
         && !skillName.includes('\0')
         && !skillName.includes('/')
-        && !skillName.includes('\\')
+        && !(skillName.includes('\\') && createPlatformAdapter().isWindows())
         && !path.isAbsolute(skillName)
         && skillName !== '.'
         && skillName !== '..';
@@ -125,7 +126,7 @@ export async function writeManifest(targetRoot, { version, linkMode, skills, pre
         historicalSkills,
     };
     await fsp.mkdir(targetRoot, { recursive: true });
-    await fsp.writeFile(path.join(targetRoot, MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+    await fsp.writeFile(path.join(targetRoot, MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}${platformAdapter.EOL}`, 'utf8');
 }
 export async function listAllKnownSkillNames({ toolkitHome, modes = [], env = process.env }) {
     const allNames = new Set();
@@ -186,7 +187,7 @@ async function stageToolkitContents({ sourceRoot, destinationRoot, version, mode
         copiedEntries.push(entry.name);
     }
     const metadata = { version, installedAt: new Date().toISOString(), source: 'npm-package' };
-    await fsp.writeFile(path.join(destinationRoot, '.apollo-toolkit-install.json'), `${JSON.stringify(metadata, null, 2)}\n`, 'utf8');
+    await fsp.writeFile(path.join(destinationRoot, '.apollo-toolkit-install.json'), `${JSON.stringify(metadata, null, 2)}${platformAdapter.EOL}`, 'utf8');
     return copiedEntries.sort();
 }
 export async function syncToolkitHome({ sourceRoot, toolkitHome, version, modes = [] }) {
@@ -297,9 +298,21 @@ async function replaceWithCopy(sourcePath, targetPath) {
     await fsp.cp(sourcePath, targetPath, { recursive: true, force: true });
 }
 async function replaceWithSymlink(sourcePath, targetPath) {
+    const adapter = createPlatformAdapter();
     await fsp.rm(targetPath, { recursive: true, force: true });
     await ensureDirectory(path.dirname(targetPath));
-    await fsp.symlink(sourcePath, targetPath, process.platform === 'win32' ? 'junction' : 'dir');
+    try {
+        await fsp.symlink(sourcePath, targetPath, adapter.symlinkType());
+    }
+    catch (err) {
+        if (err.code === 'EPERM') {
+            process.stderr.write(`Warning: Symlink not supported (EPERM). Falling back to copy mode.${adapter.EOL}`);
+            await replaceWithCopy(sourcePath, targetPath);
+        }
+        else {
+            throw err;
+        }
+    }
 }
 export async function installLinks({ toolkitHome, modes, env = process.env, previousSkillNames = [], linkMode = 'copy', includeExclusiveSkills = false }) {
     const normalizedModes = normalizeModes(modes);

package/packages/cli/dist/parsers/install-parser.d.ts

@@ -0,0 +1,15 @@
+import type { ParsedArguments } from '../types.js';
+import type { CommandParser, InstallCommand } from './types.js';
+/**
+ * Parser for the install (default) command mode.
+ *
+ * Recognises:
+ *   - Positional args: install keyword, mode names (codex, openclaw, ...)
+ *   - --help / -h
+ *   - --home <path>
+ *   - --symlink, --copy
+ */
+export declare class InstallArgsParser implements CommandParser<InstallCommand> {
+    parse(argv: string[]): InstallCommand;
+    toParsedArguments(result: InstallCommand): ParsedArguments;
+}

package/packages/cli/dist/parsers/install-parser.js

@@ -0,0 +1,87 @@
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { UserInputError } from '../../../tool-utils/dist/index.js';
+import { normalizeParseError } from './parser-utils.js';
+/**
+ * Parser for the install (default) command mode.
+ *
+ * Recognises:
+ *   - Positional args: install keyword, mode names (codex, openclaw, ...)
+ *   - --help / -h
+ *   - --home <path>
+ *   - --symlink, --copy
+ */
+export class InstallArgsParser {
+    parse(argv) {
+        let showHelp = false;
+        let toolkitHome = null;
+        let linkMode = null;
+        let explicitInstallCommand = false;
+        const modes = [];
+        try {
+            const { values, positionals } = parseArgs({
+                args: argv,
+                allowPositionals: true,
+                options: {
+                    help: { type: 'boolean', short: 'h' },
+                    home: { type: 'string' },
+                    symlink: { type: 'boolean' },
+                    copy: { type: 'boolean' },
+                },
+            });
+            showHelp = values.help ?? false;
+            if (values.home) {
+                toolkitHome = path.resolve(values.home);
+            }
+            if (values.symlink) {
+                linkMode = 'symlink';
+            }
+            if (values.copy) {
+                linkMode = 'copy';
+            }
+            if (values.symlink && values.copy) {
+                throw new UserInputError('Cannot use both --symlink and --copy');
+            }
+            for (const pos of positionals) {
+                if (pos === 'install') {
+                    explicitInstallCommand = true;
+                }
+                else {
+                    modes.push(pos);
+                }
+            }
+        }
+        catch (err) {
+            normalizeParseError(err);
+        }
+        const helpTopic = showHelp
+            ? (explicitInstallCommand || modes.length > 0 || linkMode !== null || toolkitHome !== null)
+                ? 'install'
+                : 'overview'
+            : 'overview';
+        return {
+            command: 'install',
+            modes: modes,
+            showHelp,
+            toolkitHome,
+            linkMode,
+            explicitInstallCommand,
+            helpTopic,
+        };
+    }
+    toParsedArguments(result) {
+        return {
+            command: 'install',
+            modes: result.modes,
+            showHelp: result.showHelp,
+            showToolsHelp: false,
+            toolkitHome: result.toolkitHome,
+            toolName: null,
+            toolArgs: [],
+            linkMode: result.linkMode,
+            assumeYes: false,
+            explicitInstallCommand: result.explicitInstallCommand,
+            helpTopic: result.helpTopic,
+        };
+    }
+}

package/packages/cli/dist/parsers/parser-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Normalises common parseArgs errors into user-facing UserInputErrors.
+ *
+ * Currently handles:
+ *   - --home without a value
+ *
+ * Call this inside a catch block to normalise the error before propagating it.
+ */
+export declare function normalizeParseError(err: unknown): never;

package/packages/cli/dist/parsers/parser-utils.js

@@ -0,0 +1,16 @@
+import { UserInputError } from '../../../tool-utils/dist/index.js';
+/**
+ * Normalises common parseArgs errors into user-facing UserInputErrors.
+ *
+ * Currently handles:
+ *   - --home without a value
+ *
+ * Call this inside a catch block to normalise the error before propagating it.
+ */
+export function normalizeParseError(err) {
+    const message = err.message;
+    if (message.includes('--home') && (message.includes('argument missing') || message.includes('value') || message.includes('ambiguous'))) {
+        throw new UserInputError('Missing value for --home');
+    }
+    throw err;
+}

package/packages/cli/dist/parsers/tool-parser.d.ts

@@ -0,0 +1,16 @@
+import type { ParsedArguments } from '../types.js';
+import type { CommandParser, ToolCommand, ToolsHelpCommand } from './types.js';
+/**
+ * Parser for tool-invocation modes.
+ *
+ * Two entry paths:
+ *   1. `tools` / `tool` prefix – argv[0] is 'tools' or 'tool'
+ *   2. Direct tool name – argv[0] is a known tool name (detected by caller)
+ *
+ * Returns a ToolsHelpCommand when no tool is named or --help is passed,
+ * otherwise returns a ToolCommand with the tool name and remaining args.
+ */
+export declare class ToolArgsParser implements CommandParser<ToolCommand | ToolsHelpCommand> {
+    parse(argv: string[]): ToolCommand | ToolsHelpCommand;
+    toParsedArguments(result: ToolCommand | ToolsHelpCommand): ParsedArguments;
+}

package/packages/cli/dist/parsers/tool-parser.js

@@ -0,0 +1,58 @@
+/**
+ * Parser for tool-invocation modes.
+ *
+ * Two entry paths:
+ *   1. `tools` / `tool` prefix – argv[0] is 'tools' or 'tool'
+ *   2. Direct tool name – argv[0] is a known tool name (detected by caller)
+ *
+ * Returns a ToolsHelpCommand when no tool is named or --help is passed,
+ * otherwise returns a ToolCommand with the tool name and remaining args.
+ */
+export class ToolArgsParser {
+    parse(argv) {
+        const args = [...argv];
+        // Strip leading 'tools'/'tool' prefix if present
+        const hasToolsPrefix = args[0] === 'tools' || args[0] === 'tool';
+        if (hasToolsPrefix) {
+            args.shift();
+        }
+        if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+            return { command: 'tools-help', showToolsHelp: true };
+        }
+        return {
+            command: 'tool',
+            toolName: args.shift() ?? null,
+            toolArgs: args,
+        };
+    }
+    toParsedArguments(result) {
+        if (result.command === 'tools-help') {
+            return {
+                command: 'tools-help',
+                modes: [],
+                showHelp: false,
+                showToolsHelp: true,
+                toolkitHome: null,
+                toolName: null,
+                toolArgs: [],
+                linkMode: null,
+                assumeYes: false,
+                explicitInstallCommand: false,
+                helpTopic: 'tools-help',
+            };
+        }
+        return {
+            command: 'tool',
+            modes: [],
+            showHelp: false,
+            showToolsHelp: false,
+            toolkitHome: null,
+            toolName: result.toolName,
+            toolArgs: result.toolArgs,
+            linkMode: null,
+            assumeYes: false,
+            explicitInstallCommand: false,
+            helpTopic: 'overview',
+        };
+    }
+}