@v1nvn/agentic-core 0.44.0 → 0.45.1

package/README.md

@@ -13,7 +13,7 @@ User-facing docs: [root README](../../README.md).
 | ------------------- | ----------------------------------------------------------------------- |
 | `src/last-reply.ts` | finds the previous assistant reply across local Claude Code transcripts |
 | `src/input.ts`      | stdin and markdown-file input with the CLI error contracts              |
-| `src/cli.ts`        | quiet commander parsing, usage/exit, and the runMain failure tail       |
+| `src/cli.ts`        | the runCli/parseCli doors over declarative command specs                |
 | `src/logger.ts`     | level-filtered stderr logger for the MCP servers                        |
 | `src/shutdown.ts`   | close-then-exit signal handling for the server entrypoints              |
 | `src/dev.ts`        | the hot-reload watcher wiring the servers' `yarn dev` harnesses share   |

package/package.json

@@ -1,21 +1,15 @@
 {
   "name": "@v1nvn/agentic-core",
-  "version": "0.44.0",
-  "description": "Shared runtime for the @v1nvn agent tools — last-reply transcript reader.",
+  "version": "0.45.1",
+  "description": "Shared source home for the @v1nvn agent tools — runtime helpers and the drawing kit every process-side surface imports.",
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./src/index.js",
   "exports": {
-    ".": {
-      "types": "./src/index.ts",
-      "default": "./dist/index.js"
-    },
-    "./vite": {
-      "types": "./src/vite.ts",
-      "default": "./dist/vite.js"
-    }
+    ".": "./src/index.js",
+    "./draw": "./src/draw.js",
+    "./vite": "./src/vite.js"
   },
   "scripts": {
-    "build": "vite build",
     "test": "vitest run",
     "test:watch": "vitest"
   },
@@ -35,11 +29,12 @@
     "directory": "packages/core"
   },
   "files": [
-    "dist",
     "src"
   ],
+  "dependencies": {
+    "commander": "^15.0.0"
+  },
   "devDependencies": {
-    "commander": "^15.0.0",
     "vite": "^8.1.4",
     "vitest": "^4.1.10"
   },
@@ -47,6 +42,6 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=23.6"
   }
 }

package/src/cli.js

@@ -0,0 +1,194 @@
+import { Command, InvalidArgumentError, Option } from 'commander';
+import { describeError } from "./mcp.js";
+// A --help ask caught mid-parse: the parse doors return it instead of exiting,
+// and runCli answers it (the help payload) on stdout with 0.
+export class HelpRequested extends Error {
+    command;
+    constructor(command) {
+        super(`${command.name()} --help`);
+        this.command = command;
+    }
+}
+function addOption(cmd, option) {
+    const bare = option.env === undefined &&
+        option.choices === undefined &&
+        option.default === undefined &&
+        option.parse === undefined;
+    if (bare) {
+        cmd.option(option.flags, option.description);
+        return;
+    }
+    const built = new Option(option.flags, option.description);
+    if (option.env !== undefined) {
+        built.env(option.env);
+    }
+    if (option.choices !== undefined) {
+        built.choices(option.choices);
+    }
+    if (option.default !== undefined) {
+        built.default(option.default);
+    }
+    const { parse } = option;
+    if (parse !== undefined) {
+        // A plain Error from a parse fn skips commander's exitOverride, which is
+        // what records the subcommand for the usage print — wrap it so it rides.
+        built.argParser((value) => {
+            try {
+                return parse(value);
+            }
+            catch (err) {
+                if (err.code === 'commander.invalidArgument') {
+                    throw err;
+                }
+                throw new InvalidArgumentError(describeError(err));
+            }
+        });
+    }
+    cmd.addOption(built);
+}
+function wire(cmd, spec, program, isRoot, sink) {
+    if (spec.description !== undefined) {
+        cmd.description(spec.description);
+    }
+    if (spec.argument !== undefined) {
+        cmd.argument(spec.argument.flags, spec.argument.description);
+    }
+    for (const option of spec.options ?? []) {
+        addOption(cmd, option);
+    }
+    if (isRoot && spec.version !== undefined) {
+        cmd.option('-V, --version', 'print the version and exit');
+    }
+    cmd.action((...all) => {
+        const options = all.at(-2);
+        const command = all.at(-1);
+        sink?.({
+            command: isRoot ? undefined : spec.name,
+            options,
+            args: command.args,
+            root: program.opts(),
+        });
+    });
+    for (const sub of spec.commands ?? []) {
+        const child = new Command(sub.name);
+        wire(child, sub, program, false, sink);
+        cmd.addCommand(child);
+    }
+}
+function materialize(spec, sink) {
+    const program = new Command(spec.name);
+    wire(program, spec, program, true, sink);
+    return program;
+}
+export function buildCli(spec) {
+    return materialize(spec);
+}
+function quiet(command, onUsageError) {
+    command.configureOutput({
+        writeOut: () => undefined,
+        writeErr: () => undefined,
+    });
+    command.exitOverride(err => {
+        const code = err.code;
+        if (code === 'commander.help' || code === 'commander.helpDisplayed') {
+            throw new HelpRequested(command);
+        }
+        onUsageError(command);
+        throw err;
+    });
+    command.commands.forEach(c => {
+        quiet(c, onUsageError);
+    });
+}
+export function parseCli(spec, argv, onHelp, onUsageError) {
+    let invocation;
+    const program = materialize(spec, found => {
+        invocation = found;
+    });
+    let errored;
+    quiet(program, command => {
+        errored = command;
+    });
+    try {
+        program.parse([...argv], { from: 'user' });
+    }
+    catch (err) {
+        if (!(err instanceof HelpRequested)) {
+            if (errored !== undefined) {
+                const cause = err instanceof Error ? err : new Error(String(err));
+                onUsageError?.(errored, cause);
+            }
+            return undefined;
+        }
+        return onHelp !== undefined
+            ? onHelp(err.command.name(), err.command.helpInformation())
+            : err;
+    }
+    return invocation;
+}
+export function helpTextFor(spec, topic) {
+    const program = materialize(spec);
+    const command = topic === spec.name
+        ? program
+        : program.commands.find(c => c.name() === topic);
+    if (command === undefined) {
+        throw new Error(`no '${topic}' command to describe`);
+    }
+    return command.helpInformation();
+}
+function usageError(spec, topic, message) {
+    if (message !== undefined) {
+        // Commander 15 builds its messages with the 'error: ' prefix already in.
+        process.stderr.write(`${message}\n`);
+    }
+    process.stderr.write(`${helpTextFor(spec, topic === undefined ? spec.name : topic)}\n`);
+    return spec.usageExit ?? 1;
+}
+async function call(run, options, args) {
+    try {
+        return (await run(options, args)) ?? 0;
+    }
+    catch (err) {
+        console.error(err.message);
+        return 1;
+    }
+}
+export async function runCli(spec, argv, onHelp) {
+    let asked;
+    let usageTopic;
+    let usageMessage;
+    const parsed = parseCli(spec, argv, (topic, text) => {
+        asked = { topic, text };
+        return 0;
+    }, (command, err) => {
+        usageTopic = command.name();
+        usageMessage = err.message;
+    });
+    if (parsed === undefined) {
+        return usageError(spec, usageTopic, usageMessage);
+    }
+    if (asked !== undefined) {
+        if (onHelp !== undefined) {
+            return onHelp(asked.topic, asked.text) ?? 0;
+        }
+        process.stdout.write(`${asked.text}\n`);
+        return 0;
+    }
+    const invocation = parsed;
+    if (spec.version !== undefined && invocation.root.version === true) {
+        process.stdout.write(`${spec.version}\n`);
+        return 0;
+    }
+    if (invocation.command === undefined) {
+        if ((spec.commands?.length ?? 0) > 0) {
+            return usageError(spec);
+        }
+        return spec.run === undefined
+            ? 0
+            : await call(spec.run, invocation.options, invocation.args);
+    }
+    const sub = spec.commands?.find(c => c.name === invocation.command);
+    return sub?.run === undefined
+        ? 0
+        : await call(sub.run, invocation.options, invocation.args);
+}

package/src/cli.ts

@@ -1,60 +1,274 @@
-import type { Command } from 'commander';
+import { Command, InvalidArgumentError, Option } from 'commander';
 
-// A --help ask caught mid-parse: parseQuietly returns it instead of exiting,
-// so a spec can drive the parse and the bin decides to print and exit.
+import { describeError } from './mcp.ts';
+
+export interface CliOption {
+  readonly choices?: readonly string[];
+  readonly default?: string;
+  readonly description: string;
+  readonly env?: string;
+  readonly flags: string;
+  readonly parse?: (value: string) => unknown;
+}
+
+export type CliResult = number | undefined;
+
+export type CliRun = (
+  options: Record<string, unknown>,
+  args: readonly string[],
+) => CliResult | Promise<CliResult>;
+
+export interface CliSpec {
+  readonly argument?: { readonly description: string; readonly flags: string };
+  readonly commands?: readonly CliSpec[];
+  readonly description?: string;
+  readonly name: string;
+  readonly options?: readonly CliOption[];
+  readonly run?: CliRun;
+  readonly usageExit?: number;
+  readonly version?: string;
+}
+
+export interface CliInvocation {
+  readonly args: readonly string[];
+  readonly command?: string;
+  readonly options: Record<string, unknown>;
+  readonly root: Record<string, unknown>;
+}
+
+// A --help ask caught mid-parse: the parse doors return it instead of exiting,
+// and runCli answers it (the help payload) on stdout with 0.
 export class HelpRequested extends Error {
-  constructor(readonly command: Command) {
+  readonly command: Command;
+
+  constructor(command: Command) {
     super(`${command.name()} --help`);
+    this.command = command;
   }
 }
 
-export function parseQuietly(
-  program: Command,
-  args: readonly string[],
-): Command | HelpRequested | undefined {
-  function quiet(command: Command): void {
-    command.configureOutput({
-      writeOut: () => undefined,
-      writeErr: () => undefined,
-    });
-    command.exitOverride(err => {
-      const code = (err as { code?: string }).code;
-      if (code === 'commander.help' || code === 'commander.helpDisplayed') {
-        throw new HelpRequested(command);
+export type CliHelpHook<T> = (topic: string, text: string) => T;
+
+function addOption(cmd: Command, option: CliOption): void {
+  const bare =
+    option.env === undefined &&
+    option.choices === undefined &&
+    option.default === undefined &&
+    option.parse === undefined;
+  if (bare) {
+    cmd.option(option.flags, option.description);
+    return;
+  }
+  const built = new Option(option.flags, option.description);
+  if (option.env !== undefined) {
+    built.env(option.env);
+  }
+  if (option.choices !== undefined) {
+    built.choices(option.choices);
+  }
+  if (option.default !== undefined) {
+    built.default(option.default);
+  }
+  const { parse } = option;
+  if (parse !== undefined) {
+    // A plain Error from a parse fn skips commander's exitOverride, which is
+    // what records the subcommand for the usage print — wrap it so it rides.
+    built.argParser((value: string) => {
+      try {
+        return parse(value);
+      } catch (err) {
+        if ((err as { code?: string }).code === 'commander.invalidArgument') {
+          throw err;
+        }
+        throw new InvalidArgumentError(describeError(err));
       }
-      throw err;
     });
-    command.commands.forEach(quiet);
   }
+  cmd.addOption(built);
+}
+
+function wire(
+  cmd: Command,
+  spec: CliSpec,
+  program: Command,
+  isRoot: boolean,
+  sink?: (invocation: CliInvocation) => void,
+): void {
+  if (spec.description !== undefined) {
+    cmd.description(spec.description);
+  }
+  if (spec.argument !== undefined) {
+    cmd.argument(spec.argument.flags, spec.argument.description);
+  }
+  for (const option of spec.options ?? []) {
+    addOption(cmd, option);
+  }
+  if (isRoot && spec.version !== undefined) {
+    cmd.option('-V, --version', 'print the version and exit');
+  }
+  cmd.action((...all: unknown[]) => {
+    const options = all.at(-2) as Record<string, unknown>;
+    const command = all.at(-1) as Command;
+    sink?.({
+      command: isRoot ? undefined : spec.name,
+      options,
+      args: command.args,
+      root: program.opts(),
+    });
+  });
+  for (const sub of spec.commands ?? []) {
+    const child = new Command(sub.name);
+    wire(child, sub, program, false, sink);
+    cmd.addCommand(child);
+  }
+}
+
+function materialize(
+  spec: CliSpec,
+  sink?: (invocation: CliInvocation) => void,
+): Command {
+  const program = new Command(spec.name);
+  wire(program, spec, program, true, sink);
+  return program;
+}
+
+export function buildCli(spec: CliSpec): Command {
+  return materialize(spec);
+}
+
+function quiet(
+  command: Command,
+  onUsageError: (command: Command) => void,
+): void {
+  command.configureOutput({
+    writeOut: () => undefined,
+    writeErr: () => undefined,
+  });
+  command.exitOverride(err => {
+    const code = (err as { code?: string }).code;
+    if (code === 'commander.help' || code === 'commander.helpDisplayed') {
+      throw new HelpRequested(command);
+    }
+    onUsageError(command);
+    throw err;
+  });
+  command.commands.forEach(c => {
+    quiet(c, onUsageError);
+  });
+}
+
+export function parseCli<T = HelpRequested>(
+  spec: CliSpec,
+  argv: readonly string[],
+  onHelp?: CliHelpHook<T>,
+  onUsageError?: (command: Command, err: Error) => void,
+): CliInvocation | HelpRequested | T | undefined {
+  let invocation: CliInvocation | undefined;
+  const program = materialize(spec, found => {
+    invocation = found;
+  });
+  let errored: Command | undefined;
+  quiet(program, command => {
+    errored = command;
+  });
   try {
-    quiet(program);
-    program.parse([...args], { from: 'user' });
-    return program;
+    program.parse([...argv], { from: 'user' });
   } catch (err) {
-    return err instanceof HelpRequested ? err : undefined;
+    if (!(err instanceof HelpRequested)) {
+      if (errored !== undefined) {
+        const cause = err instanceof Error ? err : new Error(String(err));
+        onUsageError?.(errored, cause);
+      }
+      return undefined;
+    }
+    return onHelp !== undefined
+      ? onHelp(err.command.name(), err.command.helpInformation())
+      : err;
   }
+  return invocation;
 }
 
-function exitWithCode(code: number): never {
-  // eslint-disable-next-line n/no-process-exit
-  process.exit(code);
+export function helpTextFor(spec: CliSpec, topic: string): string {
+  const program = materialize(spec);
+  const command =
+    topic === spec.name
+      ? program
+      : program.commands.find(c => c.name() === topic);
+  if (command === undefined) {
+    throw new Error(`no '${topic}' command to describe`);
+  }
+  return command.helpInformation();
 }
 
-export function printHelpAndExit(command: Command): never {
-  console.log(command.helpInformation());
-  exitWithCode(0);
+function usageError(spec: CliSpec, topic?: string, message?: string): number {
+  if (message !== undefined) {
+    // Commander 15 builds its messages with the 'error: ' prefix already in.
+    process.stderr.write(`${message}\n`);
+  }
+  process.stderr.write(
+    `${helpTextFor(spec, topic === undefined ? spec.name : topic)}\n`,
+  );
+  return spec.usageExit ?? 1;
 }
 
-export function printUsageAndExit(program: Command): never {
-  console.error(program.helpInformation());
-  exitWithCode(1);
+async function call(
+  run: CliRun,
+  options: Record<string, unknown>,
+  args: readonly string[],
+): Promise<number> {
+  try {
+    return (await run(options, args)) ?? 0;
+  } catch (err) {
+    console.error((err as Error).message);
+    return 1;
+  }
 }
 
-export async function runMain(main: () => Promise<void> | void): Promise<void> {
-  try {
-    await main();
-  } catch (e) {
-    console.error((e as Error).message);
-    exitWithCode(1);
+export async function runCli(
+  spec: CliSpec,
+  argv: readonly string[],
+  onHelp?: CliHelpHook<CliResult>,
+): Promise<number> {
+  let asked: undefined | { readonly text: string; readonly topic: string };
+  let usageTopic: string | undefined;
+  let usageMessage: string | undefined;
+  const parsed = parseCli(
+    spec,
+    argv,
+    (topic, text) => {
+      asked = { topic, text };
+      return 0;
+    },
+    (command, err) => {
+      usageTopic = command.name();
+      usageMessage = err.message;
+    },
+  );
+  if (parsed === undefined) {
+    return usageError(spec, usageTopic, usageMessage);
+  }
+  if (asked !== undefined) {
+    if (onHelp !== undefined) {
+      return onHelp(asked.topic, asked.text) ?? 0;
+    }
+    process.stdout.write(`${asked.text}\n`);
+    return 0;
+  }
+  const invocation = parsed as CliInvocation;
+  if (spec.version !== undefined && invocation.root.version === true) {
+    process.stdout.write(`${spec.version}\n`);
+    return 0;
+  }
+  if (invocation.command === undefined) {
+    if ((spec.commands?.length ?? 0) > 0) {
+      return usageError(spec);
+    }
+    return spec.run === undefined
+      ? 0
+      : await call(spec.run, invocation.options, invocation.args);
   }
+  const sub = spec.commands?.find(c => c.name === invocation.command);
+  return sub?.run === undefined
+    ? 0
+    : await call(sub.run, invocation.options, invocation.args);
 }

package/src/dev.js

@@ -0,0 +1,25 @@
+const RELOAD_DEBOUNCE_MS = 150;
+const IGNORED_SEGMENTS = ['/node_modules/', '/dist/', '/.git/', '/coverage/'];
+function shouldReload(file) {
+    return IGNORED_SEGMENTS.every(seg => !file.includes(seg));
+}
+/**
+ * Debounced file-change reloads, serialized via a promise chain: concurrent
+ * saves never overlap, and a mid-reload save still produces a follow-up.
+ */
+export function watchWithReload(vite, reload) {
+    let chain = Promise.resolve();
+    let timer;
+    vite.watcher.on('change', file => {
+        if (!shouldReload(file)) {
+            return;
+        }
+        if (timer) {
+            clearTimeout(timer);
+        }
+        timer = setTimeout(() => {
+            timer = undefined;
+            chain = chain.then(reload);
+        }, RELOAD_DEBOUNCE_MS);
+    });
+}

package/src/dev.ts

@@ -1,11 +1,6 @@
-// Structural stand-ins for vite's dev server and module runner — the shared
-// hot-reload wiring below must not pull vite into core's runtime surface; the
-// MCP packages pass their real instances through.
-export interface ReloadableRunner {
-  readonly evaluatedModules: { clear(): void };
-  import<T>(entry: string): Promise<T>;
-}
-
+// A structural stand-in for vite's dev server — the shared hot-reload wiring
+// below must not pull vite into core's runtime surface; vite.ts passes the
+// real instance through.
 export interface WatchableDevServer {
   close(): Promise<unknown>;
   readonly watcher: {