@laitszkin/apollo-toolkit 4.1.4 → 5.0.0

package/packages/tools/architecture/index.ts

@@ -4,6 +4,7 @@ import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import type { ToolDefinition, ToolContext } from '@laitszkin/tool-registry';
 import yaml from 'js-yaml';
+import { UserInputError, SystemError, createPlatformAdapter } from '@laitszkin/tool-utils';
 
 // ── Apply & Template helpers (mirrors cli.js internals for the new verbs) ─────
 
@@ -77,7 +78,7 @@ function removeSubmodule(feature: any, slug: string, merged?: any): boolean {
 
 function parseEndpoint(value: string): { feature: string; submodule?: string } {
   const parts = value.split('/').filter(Boolean);
-  if (parts.length === 0) throw new Error(`Invalid endpoint: "${value}"`);
+  if (parts.length === 0) throw new UserInputError(`Invalid endpoint: "${value}"`);
   return parts.length > 1
     ? { feature: parts[0], submodule: parts[1] }
     : { feature: parts[0] };
@@ -145,17 +146,13 @@ function yamlStr(value: string): string {
 
 async function handleApply(applyArgs: string[], context: ToolContext): Promise<number> {
   const stdout = context.stdout || process.stdout;
-  const stderr = context.stderr || process.stderr;
   const sourceRoot =
     context.sourceRoot ||
     path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
 
   const yamlArg = applyArgs[0];
   if (!yamlArg || yamlArg.startsWith('--')) {
-    stderr.write(
-      'Usage: apltk architecture apply <yaml-file> [--spec <dir>] [--project <root>] [--no-render]\n',
-    );
-    return 1;
+    throw new UserInputError('Missing architecture specification YAML file path. Usage: apltk architecture apply <yaml-file>');
   }
 
   // Simple flag parser for trailing flags (--spec, --project, --no-render)
@@ -176,13 +173,11 @@ async function handleApply(applyArgs: string[], context: ToolContext): Promise<n
     batch = yaml.load(raw);
   } catch (e: any) {
     const location = e.mark ? ` at line ${e.mark.line + 1}` : '';
-    stderr.write(`Error parsing apply YAML (${yamlArg})${location}: ${e.message}\n`);
-    return 1;
+    throw new UserInputError(`Error parsing apply YAML (${yamlArg})${location}: ${e.message}`);
   }
 
   if (!batch || typeof batch !== 'object') {
-    stderr.write('Invalid apply YAML: expected an object with "features" / "edges" keys.\n');
-    return 1;
+    throw new UserInputError('Invalid apply YAML: expected an object with "features" / "edges" keys.');
   }
 
   // Import atlas modules (shared with the existing JS CLI)
@@ -215,8 +210,7 @@ async function handleApply(applyArgs: string[], context: ToolContext): Promise<n
   try {
     projectRoot = cli.resolveProjectRoot(flags);
   } catch (e: any) {
-    stderr.write(`${e.message}\n`);
-    return 1;
+    throw new UserInputError(e.message);
   }
 
   const isSpec = Boolean(flags.spec);
@@ -244,7 +238,7 @@ async function handleApply(applyArgs: string[], context: ToolContext): Promise<n
     // 1) Features (add / modify / remove)
     for (const feat of batch.features || []) {
       const slug: string = feat.slug;
-      if (!slug) throw new Error('"features" entry missing required "slug" field');
+      if (!slug) throw new UserInputError('"features" entry missing required "slug" field');
 
       switch (feat.action) {
         case 'add': {
@@ -259,7 +253,7 @@ async function handleApply(applyArgs: string[], context: ToolContext): Promise<n
         }
         case 'modify': {
           const existing = findFeature(merged, slug);
-          if (!existing) throw new Error(`feature "${slug}" not found for action "modify"`);
+          if (!existing) throw new UserInputError(`feature "${slug}" not found for action "modify"`);
           if (feat.title !== undefined) existing.title = String(feat.title);
           if (feat.story !== undefined) existing.story = String(feat.story);
           if (feat.dependsOn !== undefined)
@@ -271,7 +265,7 @@ async function handleApply(applyArgs: string[], context: ToolContext): Promise<n
           removeFeature(merged, slug);
           break;
         default:
-          throw new Error(`feature "${slug}": unknown action "${feat.action}"`);
+          throw new UserInputError(`feature "${slug}": unknown action "${feat.action}"`);
       }
     }
 
@@ -279,7 +273,7 @@ async function handleApply(applyArgs: string[], context: ToolContext): Promise<n
     for (const feat of batch.features || []) {
       if (feat.action === 'remove') continue;
       const parent = findFeature(merged, feat.slug);
-      if (!parent) throw new Error(`feature "${feat.slug}" not found for submodule operations`);
+      if (!parent) throw new UserInputError(`feature "${feat.slug}" not found for submodule operations`);
       for (const sub of feat.submodules || []) {
         switch (sub.action) {
           case 'add': {
@@ -294,7 +288,7 @@ async function handleApply(applyArgs: string[], context: ToolContext): Promise<n
             removeSubmodule(parent, sub.slug, merged);
             break;
           default:
-            throw new Error(
+            throw new UserInputError(
               `submodule "${feat.slug}/${sub.slug}": unknown action "${sub.action}"`,
             );
         }
@@ -310,7 +304,7 @@ async function handleApply(applyArgs: string[], context: ToolContext): Promise<n
         if (sub.action === 'remove') continue;
         const subMod = findSubmodule(parent, sub.slug);
         if (!subMod)
-          throw new Error(`submodule "${feat.slug}/${sub.slug}" not found for function operations`);
+          throw new UserInputError(`submodule "${feat.slug}/${sub.slug}" not found for function operations`);
         for (const fn of sub.functions || []) {
           switch (fn.action) {
             case 'add': {
@@ -332,7 +326,7 @@ async function handleApply(applyArgs: string[], context: ToolContext): Promise<n
               );
               break;
             default:
-              throw new Error(
+              throw new UserInputError(
                 `function "${feat.slug}/${sub.slug}/${fn.name}": unknown action "${fn.action}"`,
               );
           }
@@ -348,7 +342,7 @@ async function handleApply(applyArgs: string[], context: ToolContext): Promise<n
         from = parseEndpoint(edge.from);
         to = parseEndpoint(edge.to);
       } catch (er: any) {
-        throw new Error(`edge: ${er.message}`);
+        throw new UserInputError(`edge: ${er.message}`, undefined, { cause: er });
       }
 
       switch (edge.action) {
@@ -356,28 +350,28 @@ async function handleApply(applyArgs: string[], context: ToolContext): Promise<n
           // Referential integrity validation
           const fromFeature = findFeature(merged, from.feature);
           if (!fromFeature) {
-            throw new Error(
+            throw new UserInputError(
               `edge "${edge.from} → ${edge.to}": source feature "${from.feature}" not found`,
             );
           }
           if (from.submodule) {
             const fromSub = findSubmodule(fromFeature, from.submodule);
             if (!fromSub) {
-              throw new Error(
+              throw new UserInputError(
                 `edge "${edge.from} → ${edge.to}": source submodule "${from.submodule}" not found in feature "${from.feature}"`,
               );
             }
           }
           const toFeature = findFeature(merged, to.feature);
           if (!toFeature) {
-            throw new Error(
+            throw new UserInputError(
               `edge "${edge.from} → ${edge.to}": target feature "${to.feature}" not found`,
             );
           }
           if (to.submodule) {
             const toSub = findSubmodule(toFeature, to.submodule);
             if (!toSub) {
-              throw new Error(
+              throw new UserInputError(
                 `edge "${edge.from} → ${edge.to}": target submodule "${to.submodule}" not found in feature "${to.feature}"`,
               );
             }
@@ -426,12 +420,14 @@ async function handleApply(applyArgs: string[], context: ToolContext): Promise<n
           break;
         }
         default:
-          throw new Error(`edge "${edge.from} → ${edge.to}": unknown action "${edge.action}"`);
+          throw new UserInputError(`edge "${edge.from} → ${edge.to}": unknown action "${edge.action}"`);
       }
     }
   } catch (e: any) {
-    stderr.write(`Batch aborted: ${e.message}\n`);
-    return 1;
+    if (e instanceof UserInputError || e instanceof SystemError) {
+      throw e;
+    }
+    throw new UserInputError(e.message);
   }
 
   // ── All mutations succeeded — persist ──
@@ -481,54 +477,50 @@ async function handleApply(applyArgs: string[], context: ToolContext): Promise<n
 // ── template ─────────────────────────────────────────────────────────────────
 
 async function handleTemplate(templateArgs: string[], context: ToolContext): Promise<number> {
-  const stdout = context.stdout || process.stdout;
-  const stderr = context.stderr || process.stderr;
-
-  // Parse --spec <dir> --output <dir>
-  let specDir: string | undefined;
-  let outputDir: string | undefined;
-  for (let i = 0; i < templateArgs.length; i++) {
-    const a = templateArgs[i];
-    if (a === '--spec' && i + 1 < templateArgs.length) specDir = templateArgs[++i];
-    else if (a === '--output' && i + 1 < templateArgs.length) outputDir = templateArgs[++i];
-  }
+    const stdout = context.stdout || process.stdout;
+    const adapter = createPlatformAdapter();
+
+    // Parse --spec <dir> --output <dir>
+    let specDir: string | undefined;
+    let outputDir: string | undefined;
+    for (let i = 0; i < templateArgs.length; i++) {
+      const a = templateArgs[i];
+      if (a === '--spec' && i + 1 < templateArgs.length) specDir = templateArgs[++i];
+      else if (a === '--output' && i + 1 < templateArgs.length) outputDir = templateArgs[++i];
+    }
 
-  if (!specDir || !outputDir) {
-    stderr.write('Usage: apltk architecture template --spec <spec-dir> --output <output-dir>\n');
-    return 1;
-  }
+    if (!specDir || !outputDir) {
+      throw new UserInputError('Missing --spec and/or --output arguments. Usage: apltk architecture template --spec <spec-dir> --output <output-dir>');
+    }
 
-  const specPath = path.resolve(specDir, 'SPEC.md');
-  const outputDirPath = path.resolve(outputDir);
-  const outputPath = path.join(outputDirPath, 'proposal.yaml');
+    const specPath = path.resolve(specDir, 'SPEC.md');
+    const outputDirPath = path.resolve(outputDir);
+    const outputPath = path.join(outputDirPath, 'proposal.yaml');
 
-  // Extract spec metadata (title, goal) from SPEC.md
-  let featureSlug = 'feature';
-  let featureTitle = 'Feature';
-  let goal = '';
+    // Extract spec metadata (title, goal) from SPEC.md
+    let featureSlug = 'feature';
+    let featureTitle = 'Feature';
+    let goal = '';
 
-  if (fs.existsSync(specPath)) {
-    const meta = parseSpecMetadata(specPath);
-    if (meta.title) {
-      featureTitle = meta.title;
-      featureSlug = toSlug(featureTitle);
-    }
-    if (meta.goal) {
-      goal = meta.goal;
-    }
-  } else {
+    if (fs.existsSync(specPath)) {
+      const meta = parseSpecMetadata(specPath);
+      if (meta.title) {
+        featureTitle = meta.title;
+        featureSlug = toSlug(featureTitle);
+      }
+      if (meta.goal) {
+        goal = meta.goal;
+      }
+    } else {
     const resolvedSpecDir = path.resolve(specDir);
     if (!fs.existsSync(resolvedSpecDir)) {
-      stderr.write(`Spec directory not found: ${resolvedSpecDir}\n`);
-    } else {
-      const mdFiles = fs.readdirSync(resolvedSpecDir).filter((f: string) => f.endsWith('.md'));
-      if (mdFiles.length > 0) {
-        stderr.write(`Spec directory found but no SPEC.md. Found: ${mdFiles.join(', ')}\n`);
-      } else {
-        stderr.write(`Spec directory found but no SPEC.md. No .md files found.\n`);
-      }
+      throw new UserInputError(`Spec directory not found: ${resolvedSpecDir}`);
+    }
+    const mdFiles = fs.readdirSync(resolvedSpecDir).filter((f: string) => f.endsWith('.md'));
+    if (mdFiles.length > 0) {
+      throw new UserInputError(`Spec directory found but no SPEC.md. Found: ${mdFiles.join(', ')}`);
     }
-    return 1;
+    throw new UserInputError('Spec directory found but no SPEC.md. No .md files found.');
   }
 
   // Build proposal.yaml content
@@ -554,11 +546,10 @@ async function handleTemplate(templateArgs: string[], context: ToolContext): Pro
 
   try {
     fs.mkdirSync(outputDirPath, { recursive: true });
-    fs.writeFileSync(outputPath, lines.join('\n'), 'utf8');
+    fs.writeFileSync(outputPath, lines.join(adapter.EOL), 'utf8');
     stdout.write(`${outputPath}\n`);
   } catch (e: any) {
-    stderr.write(`Error writing proposal.yaml: ${e.message}\n`);
-    return 1;
+    throw new SystemError(`Error writing proposal.yaml: ${e.message}`);
   }
 
   // Try to enrich with CodeGraph API listing
@@ -581,7 +572,7 @@ async function handleTemplate(templateArgs: string[], context: ToolContext): Pro
       }
       apiLines.push('#');
       const existing = fs.readFileSync(outputPath, 'utf8');
-      fs.writeFileSync(outputPath, apiLines.join('\n') + '\n' + existing);
+      fs.writeFileSync(outputPath, apiLines.join(adapter.EOL) + adapter.EOL + existing);
       cg.close();
     }
   } catch {
@@ -593,14 +584,27 @@ async function handleTemplate(templateArgs: string[], context: ToolContext): Pro
 
 // ── Handler entrypoint ───────────────────────────────────────────────────────
 
+/**
+ * architectureHandler — Known carryover from the createToolRunner migration.
+ *
+ * Reason for not using createToolRunner:
+ * - Mixed TS/JS dispatch: "apply" and "template" subcommands use TypeScript
+ *   with AppError throws. Other subcommands delegate to the JS atlas CLI
+ *   (cli.js) which has its own error handling.
+ * - Subcommand-level flag parsing: Each subcommand has unique flags; a single
+ *   ToolSchema can't express this. See DESIGN.md §2.3 for the full picture.
+ *
+ * Error handling: All TS paths throw UserInputError/SystemError. JS paths are
+ * handled by cli.dispatch()'s internal catch.
+ */
 export async function architectureHandler(
   args: string[],
   context: ToolContext,
 ): Promise<number> {
   // Intercept apply / template before passing through to the JS CLI
   const first = args[0] || '';
-  if (first === 'apply') return handleApply(args.slice(1), context);
-  if (first === 'template') return handleTemplate(args.slice(1), context);
+  if (first === 'apply') return await handleApply(args.slice(1), context);
+  if (first === 'template') return await handleTemplate(args.slice(1), context);
 
   // Delegate to the existing atlas CLI (still in JS)
   const sourceRoot =
@@ -615,20 +619,13 @@ export async function architectureHandler(
     'cli.js',
   );
 
-  try {
-    // Use file URL for ESM import compatibility on Windows — import() requires forward slashes.
-    const cliModule = await import(pathToFileURL(cliPath).href);
-    const cli = cliModule.default;
-    return cli.dispatch(args, {
-      stdout: context.stdout || process.stdout,
-      stderr: context.stderr || process.stderr,
-    });
-  } catch (error: any) {
-    (context.stderr || process.stderr).write(
-      `Error loading atlas CLI: ${error.message}\n`,
-    );
-    return 1;
-  }
+  // Use file URL for ESM import compatibility on Windows — import() requires forward slashes.
+  const cliModule = await import(pathToFileURL(cliPath).href);
+  const cli = cliModule.default;
+  return cli.dispatch(args, {
+    stdout: context.stdout || process.stdout,
+    stderr: context.stderr || process.stderr,
+  });
 }
 
 export const tool: ToolDefinition = {

package/packages/tools/architecture/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@laitszkin/tool-architecture",
-  "version": "4.0.8",
-  "description": "Apollo Toolkit — CLI tool",
+  "version": "5.0.0",
+  "description": "Apollo Toolkit \u2014 CLI tool",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,4 +19,4 @@
   "dependencies": {
     "@laitszkin/tool-registry": "*"
   }
-}
+}

package/packages/tools/codegraph/dist/index.js

@@ -1,3 +1,4 @@
+import { SystemError, UserInputError } from '../../../tool-utils/dist/index.js';
 import { findProjectRoot } from './lib/cg-instance.js';
 import { handleInit } from './lib/cmd-init.js';
 import { handleSync } from './lib/cmd-sync.js';
@@ -35,13 +36,11 @@ export async function codegraphHandler(args, context) {
         projectRoot = findProjectRoot(context.cwd || process.cwd());
     }
     catch (error) {
-        if (error.code === 'MODULE_NOT_FOUND' || (error.message && error.message.includes('Cannot find module'))) {
-            stderr.write('`@colbymchenry/codegraph` is not installed. Run `npm install @colbymchenry/codegraph` in your project directory.\n');
+        const message = error instanceof Error ? error.message : 'Unknown error finding project root';
+        if (error?.code === 'MODULE_NOT_FOUND' || message.includes('Cannot find module')) {
+            throw new UserInputError('`@colbymchenry/codegraph` is not installed. Run `npm install @colbymchenry/codegraph` in your project directory.');
         }
-        else {
-            stderr.write(`Error finding project root: ${error.message}\n`);
-        }
-        return 1;
+        throw new SystemError(`Error finding project root: ${message}`);
     }
     // Parse --spec <dir> for verify
     const specIndex = rest.indexOf('--spec');
@@ -85,16 +84,14 @@ export async function codegraphHandler(args, context) {
             case 'search': {
                 const query = rest.join(' ');
                 if (!query) {
-                    stderr.write('Usage: apltk codegraph search <query> [--limit N] [--json]\n');
-                    return 1;
+                    throw new UserInputError('Usage: apltk codegraph search <query> [--limit N] [--json]');
                 }
                 return await handleSearch(projectRoot, query, { limit, json: isJson });
             }
             case 'explore': {
                 const query = rest.join(' ');
                 if (!query) {
-                    stderr.write('Usage: apltk codegraph explore <query> [--json]\n');
-                    return 1;
+                    throw new UserInputError('Usage: apltk codegraph explore <query> [--json]');
                 }
                 return await handleExplore(projectRoot, query, { json: isJson, feature: featureName });
             }
@@ -111,25 +108,18 @@ export async function codegraphHandler(args, context) {
             }
             case 'verify': {
                 if (!specDir) {
-                    stderr.write('Usage: apltk codegraph verify --spec <spec-dir> [--json]\n');
-                    return 1;
+                    throw new UserInputError('Usage: apltk codegraph verify --spec <spec-dir> [--json]');
                 }
                 return await handleVerify(projectRoot, specDir, { json: isJson });
             }
             default:
-                stderr.write(`Unknown subcommand: ${subcommand}\n\n`);
-                printHelp(stderr);
-                return 1;
+                throw new SystemError(`Unknown codegraph subcommand: ${subcommand}`);
         }
     }
     catch (error) {
-        if (error.code === 'MODULE_NOT_FOUND' || (error.message && error.message.includes('Cannot find module'))) {
-            stderr.write('`@colbymchenry/codegraph` is not installed. Run `npm install @colbymchenry/codegraph` in your project directory.\n');
-        }
-        else {
-            stderr.write(`Error running codegraph ${subcommand}: ${error.message}\n`);
-        }
-        return 1;
+        if (error instanceof SystemError || error instanceof UserInputError)
+            throw error;
+        throw new SystemError(error instanceof Error ? error.message : 'Unknown error in codegraph', { cause: error instanceof Error ? error : undefined });
     }
 }
 function printHelp(stream) {