@ianwremmel/dispatch 0.32.1-bootstrap.0

package/src/commands/worker/set.mts

@@ -0,0 +1,63 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, nowIso, withDatabase} from '../../lib/db/index.mts';
+import {DataError, ensure} from '../../lib/errors/index.mts';
+import {correlateSession} from '../../lib/schedule/index.mts';
+import {WorkerStore} from '../../lib/stores/index.mts';
+
+const options = {
+  node: {
+    type: 'string',
+    description: 'The node the launched worker is working.',
+    positional: false,
+    required: true,
+  },
+  agent: {
+    type: 'string',
+    description:
+      'The agent ref the launch returned — the address a relayed event reaches the worker at.',
+    positional: false,
+    required: true,
+  },
+  db: DB_OPTION,
+} as const;
+
+/**
+ * Record where a node's worker can be reached. The orchestrate session runs
+ * this right after a launch, with the ref the launch returned; from then on
+ * events for the node carry that ref, and the session relays instead of
+ * letting the item cold-start a resume pass.
+ *
+ * Identity comes from the environment: the row belongs to the launching
+ * session, because only the launcher holds a ref that can actually reach the
+ * agent.
+ */
+export class Command extends AbstractCommand {
+  readonly name = 'set';
+  readonly summary = "Record a launched worker's address for event routing.";
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      const session = await correlateSession(db, ctx.env, undefined);
+      ensure(
+        session !== null,
+        () =>
+          new DataError('no live server correlates to this session', {
+            hint: 'only the session that launched the worker can record its address.',
+          })
+      );
+      await new WorkerStore(db).set({
+        node: parsed.node,
+        session,
+        agentRef: parsed.agent,
+        at: nowIso(),
+      });
+      ctx.io.write(`worker ${parsed.node} ${parsed.agent}\n`);
+    });
+  }
+}

package/src/lib/cli/CLAUDE.md

@@ -0,0 +1,13 @@
+# CLI
+
+`runCli({argv, tree, log, env, stdout, stderr})` in `cli.mts` drives a discovered
+command tree and returns an exit code. This is the only layer that knows about
+argv, `--help`, exit codes, and usage text — the `lib/command` contract stays
+transport-neutral. `index.mts` is the barrel.
+
+Read `cli.mts` for the walk / help / parse / error-mapping details. Usage text is
+generated from a command's `name` + `options`, so commands never author one.
+
+`runCli` also supplies each command an `io` bound to `stdout` (its response
+channel, separate from `log`) and hides/refuses any command whose `cli`
+transport is off (`resolveTransports`).

package/src/lib/cli/cli.mts

@@ -0,0 +1,226 @@
+import {parseArgs} from 'node:util';
+import type {Writable} from 'node:stream';
+
+import type {Logger} from '../logger/index.mts';
+import {parseOptions, assertEnv, resolveTransports} from '../command/index.mts';
+import type {AbstractCommand, CommandNode, Option} from '../command/index.mts';
+import {
+  DispatchError,
+  CommandError,
+  UsageError,
+  assertUsage,
+} from '../errors/index.mts';
+
+export interface RunCliOptions {
+  readonly argv: readonly string[];
+  readonly tree: CommandNode;
+  readonly log: Logger;
+  readonly env: NodeJS.ProcessEnv;
+  readonly stdout: Writable;
+  readonly stderr: Writable;
+}
+
+interface Walked {
+  readonly path: string[];
+  readonly node: CommandNode;
+  readonly rest: string[];
+}
+
+/** Parse argv against the command tree, run the matched command, return an exit code. */
+export async function runCli(options: RunCliOptions): Promise<number> {
+  const {argv, tree, log, env, stdout, stderr} = options;
+  try {
+    const walked = walk(tree, argv);
+
+    if (wantsHelp(argv)) {
+      stdout.write(`${usageText(walked)}\n`);
+      return 0;
+    }
+
+    const {node, rest, path} = walked;
+    const command = node.command;
+
+    if (command === undefined || !resolveTransports(command).cli) {
+      const label = path.length > 0 ? path.join(' ') : 'dispatch';
+      const children = visibleChildNames(node).sort().join(', ');
+      throw new UsageError(
+        rest.length > 0
+          ? `unknown subcommand "${rest[0] ?? ''}" for ${label}`
+          : `${label} needs a subcommand`,
+        children === ''
+          ? {
+              hint: 'this command tree has no commands; the installation is broken.',
+            }
+          : {hint: `run one of: ${children}`}
+      );
+    }
+
+    const parsed = parseCommandArgs(command, rest);
+    assertEnv(command.env, env);
+    const io = {
+      write: (chunk: string) => {
+        stdout.write(chunk);
+      },
+    };
+    await command.run(parsed, {log, env, io});
+    return 0;
+  } catch (error) {
+    if (error instanceof DispatchError) {
+      stderr.write(`error: ${error.toString()}\n`);
+      return error instanceof CommandError ? error.exitCode : 1;
+    }
+    stderr.write(`error: ${String(error)}\n`);
+    return 1;
+  }
+}
+
+/** Descend the tree along leading command-name tokens, ignoring help flags. */
+function walk(root: CommandNode, argv: readonly string[]): Walked {
+  let node = root;
+  const path: string[] = [];
+  const tokens = [...argv];
+  let index = 0;
+  for (; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === undefined || token === '--') break;
+    if (token === '--help' || token === '-h') continue;
+    if (token.startsWith('-')) break;
+    const child = node.children.get(token);
+    if (child === undefined) break;
+    node = child;
+    path.push(token);
+  }
+  return {path, node, rest: tokens.slice(index)};
+}
+
+/**
+ * Whether `--help`/`-h` appears anywhere before a `--` terminator. A command
+ * that needs a literal `--help` option value must have its caller pass it
+ * after `--`.
+ */
+function wantsHelp(argv: readonly string[]): boolean {
+  for (const token of argv) {
+    if (token === '--') return false;
+    if (token === '--help' || token === '-h') return true;
+  }
+  return false;
+}
+
+function parseCommandArgs(
+  command: AbstractCommand,
+  rest: readonly string[]
+): Record<string, unknown> {
+  const flagConfig: Record<string, {type: 'string' | 'boolean'}> = {};
+  const positionalNames: string[] = [];
+  for (const [key, option] of Object.entries(command.options)) {
+    if (option.positional) {
+      positionalNames.push(key);
+    } else {
+      flagConfig[key] = {
+        type: option.type === 'boolean' ? 'boolean' : 'string',
+      };
+    }
+  }
+
+  let values: Record<string, string | boolean | undefined>;
+  let positionals: string[];
+  try {
+    const parsed = parseArgs({
+      args: [...rest],
+      options: flagConfig,
+      allowPositionals: true,
+      strict: true,
+    });
+    values = parsed.values;
+    positionals = parsed.positionals;
+  } catch (error) {
+    throw toUsageError(error);
+  }
+
+  assertUsage(
+    positionals.length <= positionalNames.length,
+    `unexpected argument: ${positionals[positionalNames.length] ?? ''}`
+  );
+
+  const raw: Record<string, string | boolean> = {};
+  for (const [key, value] of Object.entries(values)) {
+    if (value !== undefined) raw[key] = value;
+  }
+  positionalNames.forEach((name, position) => {
+    const value = positionals[position];
+    if (value !== undefined) raw[name] = value;
+  });
+
+  return parseOptions(command.options, raw);
+}
+
+/** Re-tag a `node:util` parse failure as a usage error; rethrow anything else. */
+function toUsageError(error: unknown): UsageError {
+  if (
+    error instanceof Error &&
+    'code' in error &&
+    typeof error.code === 'string' &&
+    error.code.startsWith('ERR_PARSE_ARGS_')
+  ) {
+    return new UsageError(error.message, {cause: error});
+  }
+  throw error;
+}
+
+function usageText(walked: Walked): string {
+  const {path, node} = walked;
+  const invocation = ['dispatch', ...path].join(' ');
+  const lines: string[] = [];
+
+  if (node.command === undefined) {
+    lines.push(`usage: ${invocation} <subcommand>`);
+  } else {
+    const parts = Object.entries(node.command.options).map(([key, option]) =>
+      optionUsage(key, option)
+    );
+    lines.push(`usage: ${[invocation, ...parts].join(' ')}`);
+    lines.push('');
+    lines.push(node.command.summary);
+  }
+
+  if (visibleChildNames(node).length > 0) {
+    lines.push('');
+    lines.push('subcommands:');
+    lines.push(...childLines(node));
+  }
+
+  return lines.join('\n');
+}
+
+function optionUsage(key: string, option: Option): string {
+  if (option.positional) {
+    const label = option.choices ? option.choices.join('|') : key;
+    return option.required ? `<${label}>` : `[<${label}>]`;
+  }
+  if (option.type === 'boolean') {
+    return `[--${key}]`;
+  }
+  const value = option.choices ? option.choices.join('|') : option.type;
+  return option.required ? `--${key} <${value}>` : `[--${key} <${value}>]`;
+}
+
+/** Child names reachable over the cli: pure namespaces, plus commands whose `cli` transport is on. */
+function visibleChildNames(node: CommandNode): string[] {
+  return [...node.children.entries()]
+    .filter(([, child]) => {
+      const cmd = child.command;
+      return cmd === undefined || resolveTransports(cmd).cli;
+    })
+    .map(([name]) => name)
+    .sort();
+}
+
+function childLines(node: CommandNode): string[] {
+  const names = visibleChildNames(node);
+  if (names.length === 0) return [];
+  const width = Math.max(...names.map((name) => name.length));
+  return names.map((name) => {
+    const summary = node.children.get(name)?.command?.summary ?? '';
+    return `  ${name.padEnd(width)}  ${summary}`.trimEnd();
+  });
+}

package/src/lib/cli/index.mts

@@ -0,0 +1 @@
+export * from './cli.mts';

package/src/lib/command/CLAUDE.md

@@ -0,0 +1,26 @@
+# Command
+
+The transport-neutral command contract plus the validation and discovery built on
+it. Nothing here depends on the CLI — `lib/cli` consumes it, and a future MCP
+server will too. `index.mts` is the barrel.
+
+- `abstract-command.mts` — `AbstractCommand`, the `Option` shape, and the
+  `ParsedOptions<typeof options>` type a command uses to type its `run`; also
+  defines `Io` (the command's response channel, distinct from `log`) and the
+  concrete `transports` field, both on `CommandContext`. The docblocks cover
+  the bivariance override and how presence/`choices` narrow the parsed type.
+- `transports.mts` — `resolveTransports(command)` fills the `transports` partial
+  with `{cli: true, mcp: true}` defaults so gating reads definite booleans.
+- `parse.mts` — `parseOptions` turns a raw values map into a validated record
+  (coerce numbers, enforce `required`, check `choices`, apply defaults). The cli
+  builds `raw` from argv; an MCP server would from JSON.
+- `env.mts` — `assertEnv` throws for any variable a command declared in `env`
+  that the environment lacks.
+- `discovery.mts` — `discover` walks a commands dir into a `CommandNode` tree
+  (folder path = invocation path).
+- `test-support.mts` — `runCommand` (runs a command as a transport would and
+  returns its `io` output) plus the fixtures every command test needs:
+  `tempEnv()` for a throwaway graph database and `ticket()` for a blank ticket.
+
+Keep CLI-only concerns (argv, streams, usage strings) out so the contract stays
+reusable.

package/src/lib/command/__fixtures__/bad-export/oops.mts

@@ -0,0 +1 @@
+export const notACommand = 42;

package/src/lib/command/__fixtures__/bad-name/mismatch.mts

@@ -0,0 +1,19 @@
+import {AbstractCommand} from '../../index.mts';
+import type {ParsedOptions, CommandContext} from '../../index.mts';
+
+const options = {} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'wrong';
+  readonly summary = 'Name does not match the file.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _parsed: ParsedOptions<typeof options>,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _ctx: CommandContext
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+  ): Promise<void> {}
+}

package/src/lib/command/__fixtures__/commands/cli-only.mts

@@ -0,0 +1,20 @@
+import {AbstractCommand} from '../../index.mts';
+import type {ParsedOptions, CommandContext} from '../../index.mts';
+
+const options = {} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'cli-only';
+  readonly summary = 'Reachable over cli only.';
+  readonly env = [];
+  readonly options = options;
+  override readonly transports = {mcp: false};
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async run(
+    _parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    ctx.io.write('cli-only ran\n');
+  }
+}

package/src/lib/command/__fixtures__/commands/greet.mts

@@ -0,0 +1,39 @@
+import {AbstractCommand} from '../../index.mts';
+import type {ParsedOptions, CommandContext} from '../../index.mts';
+
+const options = {
+  who: {
+    type: 'string',
+    description: 'Who to greet.',
+    positional: true,
+    required: false,
+    default: 'world',
+  },
+  format: {
+    type: 'string',
+    description: 'Output shape.',
+    positional: false,
+    required: false,
+    default: 'text',
+    choices: ['text', 'json'],
+  },
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'greet';
+  readonly summary = 'Print a greeting.';
+  readonly env = [];
+  readonly options = options;
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    if (parsed.format === 'json') {
+      ctx.io.write(`${JSON.stringify({hello: parsed.who})}\n`);
+    } else {
+      ctx.io.write(`hello ${parsed.who}\n`);
+    }
+  }
+}

package/src/lib/command/__fixtures__/commands/math/add.mts

@@ -0,0 +1,32 @@
+import {AbstractCommand} from '../../../index.mts';
+import type {ParsedOptions, CommandContext} from '../../../index.mts';
+
+const options = {
+  a: {
+    type: 'number',
+    description: 'First addend.',
+    positional: false,
+    required: true,
+  },
+  b: {
+    type: 'number',
+    description: 'Second addend.',
+    positional: false,
+    required: true,
+  },
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'add';
+  readonly summary = 'Add two numbers.';
+  readonly env = [];
+  readonly options = options;
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    ctx.io.write(`${String(parsed.a + parsed.b)}\n`);
+  }
+}

package/src/lib/command/__fixtures__/commands/mcp-only.mts

@@ -0,0 +1,20 @@
+import {AbstractCommand} from '../../index.mts';
+import type {ParsedOptions, CommandContext} from '../../index.mts';
+
+const options = {} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'mcp-only';
+  readonly summary = 'Reachable over MCP only.';
+  readonly env = [];
+  readonly options = options;
+  override readonly transports = {cli: false};
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async run(
+    _parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    ctx.io.write('mcp-only ran\n');
+  }
+}

package/src/lib/command/__fixtures__/commands/needs-token.mts

@@ -0,0 +1,19 @@
+import {AbstractCommand} from '../../index.mts';
+import type {ParsedOptions, CommandContext} from '../../index.mts';
+
+const options = {} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'needs-token';
+  readonly summary = 'Requires MY_TOKEN.';
+  readonly env = ['MY_TOKEN'];
+  readonly options = options;
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async run(
+    _parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    ctx.io.write('ok\n');
+  }
+}

package/src/lib/command/__fixtures__/commands/store/get.mts

@@ -0,0 +1,26 @@
+import {AbstractCommand} from '../../../index.mts';
+import type {ParsedOptions, CommandContext} from '../../../index.mts';
+
+const options = {
+  key: {
+    type: 'string',
+    description: 'Key to read.',
+    positional: true,
+    required: true,
+  },
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'get';
+  readonly summary = 'Read one key.';
+  readonly env = [];
+  readonly options = options;
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    ctx.io.write(`get ${parsed.key}\n`);
+  }
+}

package/src/lib/command/__fixtures__/commands/store.mts

@@ -0,0 +1,26 @@
+import {AbstractCommand} from '../../index.mts';
+import type {ParsedOptions, CommandContext} from '../../index.mts';
+
+const options = {
+  key: {
+    type: 'string',
+    description: 'Key to read.',
+    positional: true,
+    required: false,
+  },
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'store';
+  readonly summary = 'Inspect the store.';
+  readonly env = [];
+  readonly options = options;
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    ctx.io.write(`store ${parsed.key ?? '(root)'}\n`);
+  }
+}

package/src/lib/command/abstract-command.mts

@@ -0,0 +1,104 @@
+import type {Logger} from '../logger/index.mts';
+
+export type OptionType = 'string' | 'number' | 'boolean';
+
+export interface Option {
+  readonly type: OptionType;
+  readonly description: string;
+  /** Consumes a positional argument instead of a `--flag`. */
+  readonly positional: boolean;
+  /** Absent at parse time is a usage error. */
+  readonly required: boolean;
+  /** Ignored for `boolean` options: an absent boolean flag is always `false`. */
+  readonly default?: string | number | boolean;
+  /**
+   * String options only; a value outside the set is a usage error. Ignored
+   * (has no effect at the type level or at runtime) for `number`/`boolean`.
+   */
+  readonly choices?: readonly string[];
+}
+
+export type OptionsRecord = Readonly<Record<string, Option>>;
+
+export type OptionValue<O extends Option> = O extends {readonly type: 'boolean'}
+  ? boolean
+  : O extends {readonly type: 'number'}
+    ? number
+    : O extends {readonly choices: readonly (infer C extends string)[]}
+      ? C
+      : O extends {readonly type: 'string'}
+        ? string
+        : never;
+
+export type IsPresent<O extends Option> = O extends {readonly type: 'boolean'}
+  ? true
+  : O extends {readonly required: true}
+    ? true
+    : O extends {readonly default: string | number | boolean}
+      ? true
+      : false;
+
+export type PresentKeys<O extends OptionsRecord> = {
+  [K in keyof O]: IsPresent<O[K]> extends true ? K : never;
+}[keyof O];
+
+/** The value a command's `run` receives: present keys required, the rest optional. */
+export type ParsedOptions<O extends OptionsRecord> = {
+  [K in PresentKeys<O>]: OptionValue<O[K]>;
+} & {
+  [K in Exclude<keyof O, PresentKeys<O>>]?: OptionValue<O[K]>;
+};
+
+/**
+ * The command's response channel, distinct from `log` (diagnostics). The cli
+ * writes it to stdout; the MCP server captures it as the tool result.
+ */
+export interface Io {
+  write(chunk: string): void;
+}
+
+/**
+ * What a command is handed at run time. The logger is injected so commands stay
+ * callable outside a process; `env` is the source for `assertEnv`.
+ */
+export interface CommandContext {
+  readonly log: Logger;
+  readonly env: NodeJS.ProcessEnv;
+  readonly io: Io;
+  /**
+   * The session channel, present only when the command runs as an MCP tool
+   * on a server that has one. A command that pushes must still return a
+   * useful result without it: over the CLI there is no session to push to.
+   */
+  readonly channel?: ChannelSink | undefined;
+}
+
+/** What a command may push into the session; see `lib/mcp/channel.mts`. */
+export interface ChannelSink {
+  push(
+    kind: string,
+    meta: Readonly<Record<string, string | null>>,
+    content: string
+  ): void;
+}
+
+/**
+ * The transport-neutral command contract. The framework-facing `run` takes an
+ * already-validated values record; a subclass overrides it with a signature
+ * typed from its own options const (`ParsedOptions<typeof options>`), which
+ * method-parameter bivariance accepts.
+ */
+export abstract class AbstractCommand {
+  abstract readonly name: string;
+  abstract readonly summary: string;
+  abstract readonly env: readonly string[];
+  abstract readonly options: OptionsRecord;
+  abstract run(
+    parsed: Record<string, unknown>,
+    ctx: CommandContext
+  ): Promise<void>;
+
+  /** Transport availability; absent side defaults to available. Read through
+   *  `resolveTransports`, never directly. */
+  readonly transports: {readonly cli?: boolean; readonly mcp?: boolean} = {};
+}