@laitszkin/apollo-toolkit 4.1.4 → 5.0.1

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

@@ -0,0 +1,94 @@
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { UserInputError } from '@laitszkin/tool-utils';
+import type { InstallMode, ParsedArguments } from '../types.js';
+import type { CommandParser, InstallCommand } from './types.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 implements CommandParser<InstallCommand> {
+  parse(argv: string[]): InstallCommand {
+    let showHelp = false;
+    let toolkitHome: string | null = null;
+    let linkMode: 'copy' | 'symlink' | null = null;
+    let explicitInstallCommand = false;
+    const modes: string[] = [];
+
+    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: 'overview' | 'install' = showHelp
+      ? (explicitInstallCommand || modes.length > 0 || linkMode !== null || toolkitHome !== null)
+        ? 'install'
+        : 'overview'
+      : 'overview';
+
+    return {
+      command: 'install',
+      modes: modes as InstallMode[],
+      showHelp,
+      toolkitHome,
+      linkMode,
+      explicitInstallCommand,
+      helpTopic,
+    };
+  }
+
+  toParsedArguments(result: InstallCommand): ParsedArguments {
+    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/parsers/parser-utils.ts

@@ -0,0 +1,17 @@
+import { UserInputError } from '@laitszkin/tool-utils';
+
+/**
+ * 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: unknown): never {
+  const message = (err as Error).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/parsers/tool-parser.ts

@@ -0,0 +1,65 @@
+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 class ToolArgsParser implements CommandParser<ToolCommand | ToolsHelpCommand> {
+  parse(argv: string[]): ToolCommand | ToolsHelpCommand {
+    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: ToolCommand | ToolsHelpCommand): ParsedArguments {
+    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',
+    };
+  }
+}

package/packages/cli/parsers/types.ts

@@ -0,0 +1,56 @@
+import type { InstallMode, ParsedArguments } from '../types.js';
+
+/**
+ * Parsed result for the install (default) command mode.
+ */
+export interface InstallCommand {
+  command: 'install';
+  modes: InstallMode[];
+  showHelp: boolean;
+  toolkitHome: string | null;
+  linkMode: 'copy' | 'symlink' | null;
+  explicitInstallCommand: boolean;
+  helpTopic: 'overview' | 'install';
+}
+
+/**
+ * Parsed result for the uninstall command mode.
+ */
+export interface UninstallCommand {
+  command: 'uninstall';
+  modes: InstallMode[];
+  showHelp: boolean;
+  toolkitHome: string | null;
+  assumeYes: boolean;
+  helpTopic: 'uninstall';
+}
+
+/**
+ * Parsed result for a direct tool invocation.
+ */
+export interface ToolCommand {
+  command: 'tool';
+  toolName: string | null;
+  toolArgs: string[];
+}
+
+/**
+ * Parsed result for the tools listing help screen.
+ */
+export interface ToolsHelpCommand {
+  command: 'tools-help';
+  showToolsHelp: boolean;
+}
+
+/**
+ * Union of all parsed commands returned by the CLI arg parsers.
+ */
+export type ParsedCommand = InstallCommand | UninstallCommand | ToolCommand | ToolsHelpCommand;
+
+/**
+ * Parser interface for turning raw argv arrays into strongly-typed command objects.
+ */
+export interface CommandParser<T> {
+  parse(argv: string[]): T;
+  toParsedArguments(result: T): ParsedArguments;
+}

package/packages/cli/parsers/uninstall-parser.ts

@@ -0,0 +1,75 @@
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { UserInputError } from '@laitszkin/tool-utils';
+import type { InstallMode, ParsedArguments } from '../types.js';
+import type { CommandParser, UninstallCommand } from './types.js';
+import { normalizeParseError } from './parser-utils.js';
+
+/**
+ * Parser for the uninstall command mode.
+ *
+ * Recognises:
+ *   - Positional args: 'uninstall' keyword, mode names (codex, openclaw, ...)
+ *   - --help / -h
+ *   - --home <path>
+ *   - --yes / -y
+ */
+export class UninstallArgsParser implements CommandParser<UninstallCommand> {
+  parse(argv: string[]): UninstallCommand {
+    let showHelp = false;
+    let toolkitHome: string | null = null;
+    let assumeYes = false;
+    const modes: string[] = [];
+
+    try {
+      const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+          help: { type: 'boolean', short: 'h' },
+          home: { type: 'string' },
+          yes: { type: 'boolean', short: 'y' },
+        },
+      });
+
+      showHelp = values.help ?? false;
+      if (values.home) {
+        toolkitHome = path.resolve(values.home);
+      }
+      assumeYes = values.yes ?? false;
+
+      for (const pos of positionals) {
+        if (pos !== 'uninstall') {
+          modes.push(pos);
+        }
+      }
+    } catch (err) {
+      normalizeParseError(err);
+    }
+
+    return {
+      command: 'uninstall',
+      modes: modes as InstallMode[],
+      showHelp,
+      toolkitHome,
+      assumeYes,
+      helpTopic: 'uninstall',
+    };
+  }
+
+  toParsedArguments(result: UninstallCommand): ParsedArguments {
+    return {
+      command: 'uninstall',
+      modes: result.modes,
+      showHelp: result.showHelp,
+      showToolsHelp: false,
+      toolkitHome: result.toolkitHome,
+      toolName: null,
+      toolArgs: [],
+      linkMode: null,
+      assumeYes: result.assumeYes,
+      explicitInstallCommand: false,
+      helpTopic: result.helpTopic,
+    };
+  }
+}

package/packages/cli/tool-registration.ts

@@ -52,3 +52,6 @@ export async function registerAllTools(): Promise<void> {
     registerTool(mod.tool);
   }
 }
+
+/** Tools excluded from CLI refactoring scope (SPEC.md L28) */
+export const SCOPE_EXCLUDED_TOOLS = new Set(['eval']);

package/packages/cli/types.ts

@@ -1,3 +1,5 @@
+import type { StdioWriter } from '@laitszkin/tui';
+
 export type InstallMode = 'codex' | 'openclaw' | 'trae' | 'agents' | 'claude-code';
 
 export interface InstallTarget {
@@ -25,6 +27,8 @@ export interface SyncResult {
   previousSkillNames: string[];
 }
 
+// ---- Active return type of parseArguments() / input contract for run() --------
+
 export interface ParsedArguments {
   command: 'install' | 'uninstall' | 'tool' | 'tools-help';
   modes: InstallMode[];
@@ -36,7 +40,7 @@ export interface ParsedArguments {
   linkMode: 'copy' | 'symlink' | null;
   assumeYes: boolean;
   explicitInstallCommand: boolean;
-  helpTopic: string;
+  helpTopic: 'overview' | 'install' | 'uninstall' | 'tools-help';
 }
 
 export interface CliContext {
@@ -49,4 +53,5 @@ export interface CliContext {
   confirmUpdate?: Function;
   runTool?: Function;
   spawnCommand?: Function;
+  stdioWriter?: StdioWriter;
 }

package/packages/cli/updater.ts

@@ -1,6 +1,8 @@
 import { spawn } from 'node:child_process';
+import { EOL } from 'node:os';
 import { createInterface } from 'node:readline/promises';
 import { isInteractive } from '@laitszkin/tui';
+import { createPlatformAdapter } from '@laitszkin/tool-utils';
 
 interface Version {
   parts: number[];
@@ -66,9 +68,13 @@ export function execCommand(command: string, args: string[], { env = process.env
   stderr?: NodeJS.WriteStream;
 } = {}): Promise<ExecResult> {
   return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
+    // PlatformAdapter normalizes command names across OS (e.g., appending
+    // .cmd on Windows) so spawn works reliably on any platform.
+    const adapter = createPlatformAdapter();
+    const child = spawn(adapter.resolveCommand(command), args, {
       env,
       stdio: ['ignore', 'pipe', 'pipe'],
+      shell: true,
     });
 
     let capturedStdout = '';
@@ -150,17 +156,17 @@ export async function checkForPackageUpdate({ packageName, currentVersion, env =
     const approved = await confirmUpdate({ stdin, stdout, currentVersion, latestVersion, packageName });
 
     if (!approved) {
-      stdout.write(`Continuing with ${packageName} ${currentVersion}.\n`);
+      stdout.write(`Continuing with ${packageName} ${currentVersion}.${EOL}`);
       return { checked: true, updated: false, latestVersion };
     }
 
-    stdout.write(`Updating ${packageName} to ${latestVersion}...\n`);
+    stdout.write(`Updating ${packageName} to ${latestVersion}...${EOL}`);
     await exec('npm', ['install', '-g', `${packageName}@latest`], { env, stdout, stderr });
-    stdout.write(`Update complete. Continuing with ${packageName} ${latestVersion}.\n`);
+    stdout.write(`Update complete. Continuing with ${packageName} ${latestVersion}.${EOL}`);
 
     return { checked: true, updated: true, latestVersion };
   } catch (error) {
-    stderr.write(`Warning: unable to check or install package updates: ${(error as Error).message}\n`);
+    stderr.write(`Warning: unable to check or install package updates: ${(error as Error).message}${EOL}`);
     return { checked: false, updated: false, error: error as Error };
   }
 }

package/packages/tool-registry/dist/registry.js

@@ -1,3 +1,4 @@
+import { ToolNotFoundError, SystemError } from '../../tool-utils/dist/index.js';
 const TOOLS_BY_NAME = new Map();
 export function registerTool(tool) {
     TOOLS_BY_NAME.set(tool.name, tool);
@@ -18,14 +19,12 @@ export async function runTool(toolName, toolArgs, context = {}) {
     const stderr = context.stderr || process.stderr;
     const tool = getTool(toolName);
     if (!tool) {
-        stderr.write(`Unknown tool: ${toolName}\n\nAvailable tools:\n${formatToolList()}\n`);
-        return 1;
+        throw new ToolNotFoundError(`Unknown tool: ${toolName}`);
     }
     if (tool.handler) {
         return tool.handler(toolArgs, context);
     }
-    stderr.write(`Tool not fully configured: ${toolName}\n`);
-    return 1;
+    throw new SystemError(`Tool not fully configured: ${toolName}`);
 }
 export function formatExamples(examples = []) {
     return examples.map(({ command, result }) => (`  ${command}\n    Result: ${result}`)).join('\n');