@laitszkin/apollo-toolkit 4.1.3 → 5.0.0

package/packages/cli/help-text-builder.ts

@@ -0,0 +1,180 @@
+import { buildBanner, buildSupportedTargetLines } from '@laitszkin/tui';
+import { formatToolList, buildToolDiscoveryHelp, formatExamples } from '@laitszkin/tool-registry';
+import { TARGET_DEFINITIONS, VALID_MODES } from './installer.js';
+
+/**
+ * Produces the four help text sections previously generated by standalone
+ * functions.  Each method returns text identical to the original builder so
+ * that observable CLI output is unchanged.
+ */
+export class HelpTextBuilder {
+  private version: string;
+  private colorEnabled: boolean;
+
+  constructor({ version, colorEnabled }: { version: string; colorEnabled: boolean }) {
+    this.version = version;
+    this.colorEnabled = colorEnabled;
+  }
+
+  // ---- shared helpers -------------------------------------------------------
+
+  private modeUsagePattern(): string {
+    return `${VALID_MODES.join('|')}|all`;
+  }
+
+  private joinLines(lines: (string | undefined | null | false)[]): string {
+    return lines.filter(Boolean).join('\n');
+  }
+
+  // ---- public methods -------------------------------------------------------
+
+  /** Replaces  buildHelpText  –  top-level overview help. */
+  overview(): string {
+    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 this.joinLines([
+      buildBanner({ version: this.version, colorEnabled: this.colorEnabled }),
+      '',
+      'Usage:',
+      `  apltk [install] [${this.modeUsagePattern()}]...`,
+      `  apollo-toolkit [install] [${this.modeUsagePattern()}]...`,
+      `  apltk uninstall [${this.modeUsagePattern()}]... [--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),
+    ]);
+  }
+
+  /** Replaces  buildInstallHelpText  –  install-specific help. */
+  install(): string {
+    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 this.joinLines([
+      buildBanner({ version: this.version, colorEnabled: this.colorEnabled }),
+      '',
+      'Usage:',
+      `  apltk [install] [${this.modeUsagePattern()}]...`,
+      `  apollo-toolkit [install] [${this.modeUsagePattern()}]...`,
+      '',
+      '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: this.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),
+    ]);
+  }
+
+  /** Replaces  buildUninstallHelpText  –  uninstall-specific help. */
+  uninstall(): string {
+    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 this.joinLines([
+      buildBanner({ version: this.version, colorEnabled: this.colorEnabled }),
+      '',
+      'Usage:',
+      `  apltk uninstall [${this.modeUsagePattern()}]... [--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: this.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),
+    ]);
+  }
+
+  /** Replaces  buildToolsHelp  –  tools listing help screen. */
+  toolsHelp(): string {
+    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 this.joinLines([
+      buildBanner({ version: this.version, colorEnabled: this.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),
+    ]);
+  }
+}

package/packages/cli/index.ts

@@ -1,10 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { color, supportsColor, supportsAnimation, buildBanner, buildWordmark, buildWelcomeScreen, buildSupportedTargetLines, renderSelectionScreen, animateWelcomeScreen, promptYesNo, promptForModes, isInteractive } from '@laitszkin/tui';
-import type { TargetDefinition } from '@laitszkin/tui';
-import { formatToolList, buildToolDiscoveryHelp, runTool, getTool as getToolCommand } from '@laitszkin/tool-registry';
-import { formatExamples } from '@laitszkin/tool-registry';
+import { color, supportsColor, supportsAnimation, buildBanner, buildWordmark, buildWelcomeScreen, buildSupportedTargetLines, renderSelectionScreen, animateWelcomeScreen, promptYesNo, promptForModes, isInteractive, createStdioWriter } from '@laitszkin/tui';
+import type { TargetDefinition, StdioWriter } from '@laitszkin/tui';
+import { runTool } from '@laitszkin/tool-registry';
 import {
   TARGET_DEFINITIONS,
   VALID_MODES,
@@ -49,257 +48,52 @@ export {
   execCommand,
 };
 import type { CliContext, InstallMode, ParsedArguments } from './types.js';
-
-function buildModeUsagePattern(): string {
-  return `${VALID_MODES.join('|')}|all`;
-}
-
-function buildInteractiveModeHint(): string {
-  const quotedModes = [...VALID_MODES, 'all'].map((mode) => `\`${mode}\``);
-  return `${quotedModes.slice(0, -1).join(', ')}, or ${quotedModes.at(-1)}`;
-}
-
-function buildHelpText({ version, colorEnabled }: { version: string; colorEnabled: boolean }): string {
-  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 }: { version: string; colorEnabled: boolean }): string {
-  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 }: { version: string; colorEnabled: boolean }): string {
-  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 }: { version: string; colorEnabled: boolean }): string {
-  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 type { CommandParser } from './parsers/types.js';
+import { formatAppError } from '@laitszkin/tool-utils';
+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: string): { version: string; name: string } {
   return JSON.parse(fs.readFileSync(path.join(sourceRoot, 'package.json'), 'utf8'));
 }
 
 function parseArguments(argv: string[]): ParsedArguments {
-  const args = [...argv];
-  const result: ParsedArguments = {
-    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 as InstallMode);
-      }
-    }
-    if (result.showHelp) result.helpTopic = 'uninstall';
-    return result;
-  }
-
-  if (args[0] === 'tools' || args[0] === 'tool') {
-    args.shift();
-    const nextArg: string | undefined = args[0];
-    if (args.length === 0 || nextArg === '--help' || nextArg === '-h') {
-      result.command = 'tools-help';
-      result.showToolsHelp = true;
-      return result;
+  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<string, CommandParser<any>>([
+    ['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);
     }
-    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 as InstallMode);
+    return toolParser.toParsedArguments(toolParser.parse(argv));
   }
 
-  if (result.showHelp) {
-    const installContextRequested = result.explicitInstallCommand
-      || result.modes.length > 0
-      || result.linkMode !== null
-      || result.toolkitHome !== null;
-    result.helpTopic = installContextRequested ? 'install' : 'overview';
-  }
-
-  return result;
+  // Default: install (handles bare arguments like "codex", "--help", or empty argv)
+  return installParser.toParsedArguments(installParser.parse(argv));
 }
 
 function buildSymlinkInfo({ colorEnabled }: { colorEnabled: boolean }): string {
@@ -418,7 +212,13 @@ function printUninstallSummary({ stdout, uninstallResult, env }: {
   }
 }
 
-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: string[], context: CliContext = {}): Promise<number> {
   const __filename = fileURLToPath(import.meta.url);
@@ -428,6 +228,7 @@ export async function run(argv: string[], context: CliContext = {}): Promise<num
   const stderr = context.stderr || process.stderr;
   const stdin = context.stdin || process.stdin;
   const env = context.env || process.env;
+  const stdioWriter: StdioWriter = createStdioWriter({ stdout, stderr, env });
   let packageJson = readPackageJson(sourceRoot);
 
   try {
@@ -436,25 +237,32 @@ export async function run(argv: string[], context: CliContext = {}): Promise<num
     if (parsed.showHelp) {
       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,
       });
     }
 
@@ -580,7 +388,7 @@ export async function run(argv: string[], context: CliContext = {}): Promise<num
     printSummary({ stdout, version: packageJson.version, toolkitHome, modes, installResult, env });
     return 0;
   } catch (error) {
-    stderr.write(`Error: ${(error as Error).message}\n`);
+    formatAppError(stderr, error);
     return 1;
   }
 }

package/packages/cli/installer.ts

@@ -1,9 +1,11 @@
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
-import os from 'node:os';
 import path from 'node:path';
+import { createPlatformAdapter } from '@laitszkin/tool-utils';
 import type { InstallMode, InstallTarget, ManifestData, SyncResult } from './types.js';
 
+const platformAdapter = createPlatformAdapter();
+
 export interface TargetDefinition {
   id: InstallMode;
   label: string;
@@ -24,7 +26,7 @@ const SKILLS_DIRNAME = 'skills';
 export const MANIFEST_FILENAME = '.apollo-toolkit-manifest.json';
 
 export function resolveHomeDirectory(env: NodeJS.ProcessEnv = process.env): string {
-  return env.HOME || env.USERPROFILE || os.homedir();
+  return createPlatformAdapter().homeDir(env);
 }
 
 export function expandUserPath(inputPath: string, env: NodeJS.ProcessEnv = process.env): string {
@@ -115,12 +117,12 @@ export async function readManifest(targetRoot: string): Promise<ManifestData | n
   }
 }
 
-function isSafeSkillName(skillName: string): boolean {
+export function isSafeSkillName(skillName: string): boolean {
   return typeof skillName === 'string'
     && skillName.length > 0
     && !skillName.includes('\0')
     && !skillName.includes('/')
-    && !skillName.includes('\\')
+    && !(skillName.includes('\\') && createPlatformAdapter().isWindows())
     && !path.isAbsolute(skillName)
     && skillName !== '.'
     && skillName !== '..';
@@ -148,7 +150,7 @@ export async function writeManifest(
   await fsp.mkdir(targetRoot, { recursive: true });
   await fsp.writeFile(
     path.join(targetRoot, MANIFEST_FILENAME),
-    `${JSON.stringify(manifest, null, 2)}\n`,
+    `${JSON.stringify(manifest, null, 2)}${platformAdapter.EOL}`,
     'utf8',
   );
 }
@@ -229,7 +231,7 @@ async function stageToolkitContents({ sourceRoot, destinationRoot, version, mode
   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`,
+    `${JSON.stringify(metadata, null, 2)}${platformAdapter.EOL}`,
     'utf8',
   );
   return copiedEntries.sort();
@@ -357,9 +359,19 @@ async function replaceWithCopy(sourcePath: string, targetPath: string): Promise<
 }
 
 async function replaceWithSymlink(sourcePath: string, targetPath: string): Promise<void> {
+  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: unknown) {
+    if ((err as NodeJS.ErrnoException).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 }: {

package/packages/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@laitszkin/cli",
-  "version": "4.0.8",
-  "description": "Apollo Toolkit — CLI command management (install, uninstall, tool routing)",
+  "version": "5.0.0",
+  "description": "Apollo Toolkit \u2014 CLI command management (install, uninstall, tool routing)",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,6 +19,7 @@
   "dependencies": {
     "@laitszkin/tui": "*",
     "@laitszkin/tool-registry": "*",
+    "@laitszkin/tool-utils": "*",
     "@laitszkin/tool-filter-logs": "*",
     "@laitszkin/tool-search-logs": "*",
     "@laitszkin/tool-validate-skill-frontmatter": "*",
@@ -35,8 +36,10 @@
     "@laitszkin/tool-generate-storyboard-images": "*",
     "@laitszkin/tool-enforce-video-aspect-ratio": "*",
     "@laitszkin/tool-architecture": "*",
+    "@laitszkin/tool-codegraph": "*",
     "@laitszkin/tool-create-specs": "*",
     "@laitszkin/tool-create-review-report": "*",
+    "@laitszkin/tool-eval": "*",
     "@laitszkin/tool-extract-pdf-text": "*"
   }
-}
+}