@laitszkin/apollo-toolkit 4.1.3 → 5.0.0

package/packages/tool-utils/schema.ts

@@ -0,0 +1,122 @@
+import { EOL } from 'node:os';
+import { parseArgs } from 'node:util';
+import type { ParseArgsOptionsConfig } from 'node:util';
+import { formatAppError } from './app-error.js';
+
+/**
+ * Minimal tool execution context.
+ * Defined locally to avoid a circular build dependency:
+ * tool-utils → tool-registry → tui → tool-utils.
+ */
+export interface ToolContext {
+  sourceRoot?: string;
+  stdout?: NodeJS.WriteStream;
+  stderr?: NodeJS.WriteStream;
+  env?: NodeJS.ProcessEnv;
+  spawnCommand?: Function;
+  cwd?: string;
+  /** Structured output adapter — created by createStdioWriter(@laitszkin/tui). */
+  stdioWriter?: { info?(msg: string): void; warn?(msg: string): void; error?(msg: string): void };
+}
+
+/** Option definition for parseArgs schema. */
+export type SchemaOption =
+  | { type: 'string'; default?: string; short?: string; multiple?: boolean; description?: string }
+  | { type: 'boolean'; default?: boolean; short?: string; multiple?: boolean; description?: string };
+
+/**
+ * Complete tool schema — single source of truth for args, help, and validation.
+ *
+ * Example:
+ * ```ts
+ * const schema: ToolSchema = {
+ *   options: {
+ *     start: { type: 'string', short: 's' },
+ *     end: { type: 'string', short: 'e' },
+ *     help: { type: 'boolean', short: 'h' },
+ *   },
+ *   allowPositionals: true,
+ *   usage: 'apltk filter-logs [options] [<file>...]',
+ *   description: 'Filter log lines by time window.',
+ *   handler: async (values, positionals, ctx) => { ... },
+ * };
+ * ```
+ */
+export interface ToolSchema {
+  options: Record<string, SchemaOption>;
+  allowPositionals?: boolean;
+  strict?: boolean;
+  usage?: string;
+  description?: string;
+  category?: string;
+  handler: (
+    values: Record<string, unknown>,
+    positionals: string[],
+    context: ToolContext,
+  ) => Promise<number> | number;
+}
+
+function buildHelpText(schema: ToolSchema): string {
+  const lines: string[] = [];
+  if (schema.usage) {
+    lines.push(`Usage: ${schema.usage}`);
+  }
+  if (schema.description) {
+    lines.push('', schema.description);
+  }
+  lines.push('', 'Options:');
+  for (const [key, opt] of Object.entries(schema.options)) {
+    if (key === 'help') continue;
+    const short = opt.short ? `, -${opt.short}` : '';
+    const typeLabel = opt.type === 'string' ? ' <value>' : '';
+    const multiLabel = opt.multiple ? ' [...]' : '';
+    const def = opt.default !== undefined ? ` (default: ${opt.default})` : '';
+    const desc = opt.description ? `  ${opt.description}` : '';
+    lines.push(`  --${key}${short}${typeLabel}${multiLabel}${def}${desc}`);
+  }
+  lines.push('  --help, -h            Show this help');
+  return lines.join(EOL);
+}
+
+/**
+ * Creates a tool handler function from a ToolSchema declaration.
+ * Automatically handles:
+ *   - Argument parsing via node:util.parseArgs
+ *   - --help / -h flag (auto-generates help text from options)
+ *   - Strict mode validation
+ */
+export function createToolRunner(schema: ToolSchema) {
+  const options: ParseArgsOptionsConfig = {};
+  for (const [key, opt] of Object.entries(schema.options)) {
+    const entry: { type: 'string' | 'boolean'; default?: string | boolean; short?: string; multiple?: boolean } = { type: opt.type };
+    if (opt.default !== undefined) entry.default = opt.default;
+    if (opt.short) entry.short = opt.short;
+    if (opt.multiple) entry.multiple = true;
+    options[key] = entry;
+  }
+  options.help = { type: 'boolean', short: 'h' };
+
+  return async (args: string[], context: ToolContext): Promise<number> => {
+    const stdout = context.stdout ?? process.stdout;
+    const stderr = context.stderr ?? process.stderr;
+
+    try {
+      const { values, positionals } = parseArgs({
+        args,
+        options,
+        allowPositionals: schema.allowPositionals ?? false,
+        strict: schema.strict ?? true,
+      });
+
+      if (values.help) {
+        stdout.write(buildHelpText(schema) + '\n');
+        return 0;
+      }
+
+      return await schema.handler(values as Record<string, unknown>, positionals, context);
+    } catch (err) {
+      formatAppError(stderr, err);
+      return 1;
+    }
+  };
+}

package/packages/tools/architecture/dist/index.d.ts

@@ -1,3 +1,16 @@
 import type { ToolDefinition, ToolContext } from '@laitszkin/tool-registry';
+/**
+ * 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 declare function architectureHandler(args: string[], context: ToolContext): Promise<number>;
 export declare const tool: ToolDefinition;

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

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import yaml from 'js-yaml';
+import { UserInputError, SystemError, createPlatformAdapter } from '../../../tool-utils/dist/index.js';
 // ── Apply & Template helpers (mirrors cli.js internals for the new verbs) ─────
 function findFeature(state, slug) {
     return (state.features || []).find((f) => f.slug === slug);
@@ -71,7 +72,7 @@ function removeSubmodule(feature, slug, merged) {
 function parseEndpoint(value) {
     const parts = value.split('/').filter(Boolean);
     if (parts.length === 0)
-        throw new Error(`Invalid endpoint: "${value}"`);
+        throw new UserInputError(`Invalid endpoint: "${value}"`);
     return parts.length > 1
         ? { feature: parts[0], submodule: parts[1] }
         : { feature: parts[0] };
@@ -131,13 +132,11 @@ function yamlStr(value) {
 // ── apply ────────────────────────────────────────────────────────────────────
 async function handleApply(applyArgs, context) {
     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)
     const rest = applyArgs.slice(1);
@@ -160,12 +159,10 @@ async function handleApply(applyArgs, context) {
     }
     catch (e) {
         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)
     const cliPath = path.join(sourceRoot, 'skills', 'init-project-html', 'lib', 'atlas', 'cli.js');
@@ -182,8 +179,7 @@ async function handleApply(applyArgs, context) {
         projectRoot = cli.resolveProjectRoot(flags);
     }
     catch (e) {
-        stderr.write(`${e.message}\n`);
-        return 1;
+        throw new UserInputError(e.message);
     }
     const isSpec = Boolean(flags.spec);
     const atlasDir = cli.baseAtlasDir(projectRoot);
@@ -209,7 +205,7 @@ async function handleApply(applyArgs, context) {
         for (const feat of batch.features || []) {
             const slug = feat.slug;
             if (!slug)
-                throw new Error('"features" entry missing required "slug" field');
+                throw new UserInputError('"features" entry missing required "slug" field');
             switch (feat.action) {
                 case 'add': {
                     const init = {};
@@ -227,7 +223,7 @@ async function handleApply(applyArgs, context) {
                 case 'modify': {
                     const existing = findFeature(merged, slug);
                     if (!existing)
-                        throw new Error(`feature "${slug}" not found for action "modify"`);
+                        throw new UserInputError(`feature "${slug}" not found for action "modify"`);
                     if (feat.title !== undefined)
                         existing.title = String(feat.title);
                     if (feat.story !== undefined)
@@ -242,7 +238,7 @@ async function handleApply(applyArgs, context) {
                     removeFeature(merged, slug);
                     break;
                 default:
-                    throw new Error(`feature "${slug}": unknown action "${feat.action}"`);
+                    throw new UserInputError(`feature "${slug}": unknown action "${feat.action}"`);
             }
         }
         // 2) Submodules (add / remove) — skip features that were removed
@@ -251,7 +247,7 @@ async function handleApply(applyArgs, context) {
                 continue;
             const parent = findFeature(merged, feat.slug);
             if (!parent)
-                throw new Error(`feature "${feat.slug}" not found for submodule operations`);
+                throw new UserInputError(`feature "${feat.slug}" not found for submodule operations`);
             for (const sub of feat.submodules || []) {
                 switch (sub.action) {
                     case 'add': {
@@ -269,7 +265,7 @@ async function handleApply(applyArgs, context) {
                         removeSubmodule(parent, sub.slug, merged);
                         break;
                     default:
-                        throw new Error(`submodule "${feat.slug}/${sub.slug}": unknown action "${sub.action}"`);
+                        throw new UserInputError(`submodule "${feat.slug}/${sub.slug}": unknown action "${sub.action}"`);
                 }
             }
         }
@@ -285,7 +281,7 @@ async function handleApply(applyArgs, context) {
                     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': {
@@ -308,7 +304,7 @@ async function handleApply(applyArgs, context) {
                             subMod.functions = (subMod.functions || []).filter((f) => f.name !== fn.name);
                             break;
                         default:
-                            throw new Error(`function "${feat.slug}/${sub.slug}/${fn.name}": unknown action "${fn.action}"`);
+                            throw new UserInputError(`function "${feat.slug}/${sub.slug}/${fn.name}": unknown action "${fn.action}"`);
                     }
                 }
             }
@@ -322,29 +318,29 @@ async function handleApply(applyArgs, context) {
                 to = parseEndpoint(edge.to);
             }
             catch (er) {
-                throw new Error(`edge: ${er.message}`);
+                throw new UserInputError(`edge: ${er.message}`, undefined, { cause: er });
             }
             switch (edge.action) {
                 case 'add': {
                     // Referential integrity validation
                     const fromFeature = findFeature(merged, from.feature);
                     if (!fromFeature) {
-                        throw new Error(`edge "${edge.from} → ${edge.to}": source feature "${from.feature}" not found`);
+                        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(`edge "${edge.from} → ${edge.to}": source submodule "${from.submodule}" not found in feature "${from.feature}"`);
+                            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(`edge "${edge.from} → ${edge.to}": target feature "${to.feature}" not found`);
+                        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(`edge "${edge.from} → ${edge.to}": target submodule "${to.submodule}" not found in feature "${to.feature}"`);
+                            throw new UserInputError(`edge "${edge.from} → ${edge.to}": target submodule "${to.submodule}" not found in feature "${to.feature}"`);
                         }
                     }
                     const eid = edge.id || `e-${Math.random().toString(36).slice(2, 8)}`;
@@ -393,13 +389,15 @@ async function handleApply(applyArgs, context) {
                     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) {
-        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 ──
     const saveDir = isSpec ? overlayDir : atlasDir;
@@ -442,7 +440,7 @@ async function handleApply(applyArgs, context) {
 // ── template ─────────────────────────────────────────────────────────────────
 async function handleTemplate(templateArgs, context) {
     const stdout = context.stdout || process.stdout;
-    const stderr = context.stderr || process.stderr;
+    const adapter = createPlatformAdapter();
     // Parse --spec <dir> --output <dir>
     let specDir;
     let outputDir;
@@ -454,8 +452,7 @@ async function handleTemplate(templateArgs, context) {
             outputDir = templateArgs[++i];
     }
     if (!specDir || !outputDir) {
-        stderr.write('Usage: apltk architecture template --spec <spec-dir> --output <output-dir>\n');
-        return 1;
+        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);
@@ -477,18 +474,13 @@ async function handleTemplate(templateArgs, context) {
     else {
         const resolvedSpecDir = path.resolve(specDir);
         if (!fs.existsSync(resolvedSpecDir)) {
-            stderr.write(`Spec directory not found: ${resolvedSpecDir}\n`);
+            throw new UserInputError(`Spec directory not found: ${resolvedSpecDir}`);
         }
-        else {
-            const mdFiles = fs.readdirSync(resolvedSpecDir).filter((f) => 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`);
-            }
+        const mdFiles = fs.readdirSync(resolvedSpecDir).filter((f) => 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
     const lines = [
@@ -506,12 +498,11 @@ async function handleTemplate(templateArgs, context) {
     lines.push('    submodules: []         # LLM: fill in submodule entries', '', '# Cross-feature edges (leave empty for single-feature proposals)', 'edges: []                  # LLM: fill in edge entries', '');
     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) {
-        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
     try {
@@ -531,7 +522,7 @@ async function handleTemplate(templateArgs, context) {
             }
             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();
         }
     }
@@ -541,30 +532,37 @@ async function handleTemplate(templateArgs, context) {
     return 0;
 }
 // ── 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, context) {
     // Intercept apply / template before passing through to the JS CLI
     const first = args[0] || '';
     if (first === 'apply')
-        return handleApply(args.slice(1), context);
+        return await handleApply(args.slice(1), context);
     if (first === 'template')
-        return handleTemplate(args.slice(1), context);
+        return await handleTemplate(args.slice(1), context);
     // Delegate to the existing atlas CLI (still in JS)
     const sourceRoot = context.sourceRoot ||
         path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
     const cliPath = path.join(sourceRoot, 'skills', 'init-project-html', 'lib', 'atlas', '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) {
-        (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 = {
     name: 'architecture',

package/packages/tools/architecture/dist/index.test.js

@@ -3,6 +3,7 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { UserInputError } from '../../../tool-utils/dist/index.js';
 import { tool } from './index.js';
 function makeIo() {
     let stdoutBuf = '';
@@ -88,6 +89,11 @@ describe('REGTEST-15: Wrong spec path error', () => {
             assert.equal(exitCode, 1, 'Expected exit code 1 for missing spec path');
             assert.ok(io.stderrText.includes('not found'), `stderr should contain "not found": got ${JSON.stringify(io.stderrText)}`);
         }
+        catch (err) {
+            // handler may throw — verify error type and message
+            assert.ok(err instanceof UserInputError, 'Expected UserInputError');
+            assert.ok(err.message.includes('not found'), 'Error message should indicate path not found');
+        }
         finally {
             mock.restoreAll();
         }
@@ -221,9 +227,16 @@ describe('REGTEST-17: Edge referential integrity', () => {
         const handler = tool.handler;
         if (!handler)
             throw new Error('tool.handler is undefined');
-        const exitCode = await handler(['apply', yamlPath, '--no-render'], makeContext(io, { sourceRoot: tmpDir }));
-        assert.equal(exitCode, 1, 'Expected exit code 1 for edge targeting missing feature');
-        assert.ok(io.stderrText.includes('non-existent-feature'), `stderr should contain "non-existent-feature": got ${JSON.stringify(io.stderrText)}`);
-        assert.ok(io.stderrText.includes('Batch aborted'), `stderr should contain "Batch aborted": got ${JSON.stringify(io.stderrText)}`);
+        try {
+            const exitCode = await handler(['apply', yamlPath, '--no-render'], makeContext(io, { sourceRoot: tmpDir }));
+            assert.equal(exitCode, 1, 'Expected exit code 1 for edge targeting missing feature');
+            assert.ok(io.stderrText.includes('non-existent-feature'), `stderr should contain "non-existent-feature": got ${JSON.stringify(io.stderrText)}`);
+            assert.ok(io.stderrText.length > 0, `stderr should have error text: got ${JSON.stringify(io.stderrText)}`);
+        }
+        catch (err) {
+            // handler may throw instead of returning 1
+            assert.ok(err instanceof UserInputError, 'Expected UserInputError');
+            assert.ok(err.message.includes('non-existent-feature'), 'Error message should reference the missing feature');
+        }
     });
 });