@ianwremmel/dispatch 0.32.1-bootstrap.0

package/src/lib/command/discovery.mts

@@ -0,0 +1,100 @@
+import {readdir} from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+
+import {AbstractCommand} from './abstract-command.mts';
+import {DefinitionError, ensure} from '../errors/index.mts';
+
+export interface CommandNode {
+  readonly name: string;
+  command: AbstractCommand | undefined;
+  readonly children: Map<string, CommandNode>;
+}
+
+function makeNode(name: string): CommandNode {
+  return {name, command: undefined, children: new Map()};
+}
+
+/** Walk `commandsDir`, load each `.mts` command, and assemble the invocation tree. */
+export async function discover(
+  commandsDir: string | URL
+): Promise<CommandNode> {
+  const dir =
+    typeof commandsDir === 'string' ? commandsDir : fileURLToPath(commandsDir);
+  const root = makeNode('');
+
+  const entries = await readdir(dir, {recursive: true, withFileTypes: true});
+  const files = entries
+    .filter(
+      (entry) =>
+        entry.isFile() &&
+        entry.name.endsWith('.mts') &&
+        !entry.name.endsWith('.test.mts')
+    )
+    .map((entry) => path.relative(dir, path.join(entry.parentPath, entry.name)))
+    .sort();
+
+  for (const relative of files) {
+    const segments = relative.slice(0, -'.mts'.length).split(path.sep);
+    const command = await loadCommand(dir, relative, segments);
+    insert(root, segments, command);
+  }
+
+  return root;
+}
+
+async function loadCommand(
+  dir: string,
+  relative: string,
+  segments: string[]
+): Promise<AbstractCommand> {
+  const href = pathToFileURL(path.join(dir, relative)).href;
+  const module = (await import(href)) as Record<string, unknown>;
+  const exported = module.Command;
+
+  ensure(
+    typeof exported === 'function' &&
+      exported.prototype instanceof AbstractCommand,
+    () =>
+      new DefinitionError(
+        `${relative} must export a Command class extending AbstractCommand`,
+        {
+          hint: `add "export class Command extends AbstractCommand { … }" to ${relative}`,
+        }
+      )
+  );
+
+  const Ctor = exported as new () => AbstractCommand;
+  const command = new Ctor();
+  const expected = segments[segments.length - 1] ?? '';
+
+  ensure(
+    command.name === expected,
+    () =>
+      new DefinitionError(
+        `${relative} declares name "${command.name}" but its file requires "${expected}"`,
+        {
+          hint: `rename the command to "${expected}", or move the file to "${command.name}.mts"`,
+        }
+      )
+  );
+
+  return command;
+}
+
+function insert(
+  root: CommandNode,
+  segments: string[],
+  command: AbstractCommand
+): void {
+  let node = root;
+  for (const segment of segments) {
+    let child = node.children.get(segment);
+    if (child === undefined) {
+      child = makeNode(segment);
+      node.children.set(segment, child);
+    }
+    node = child;
+  }
+  node.command = command;
+}

package/src/lib/command/env.mts

@@ -0,0 +1,19 @@
+import {EnvironmentError, ensure} from '../errors/index.mts';
+
+/** Throw if any variable a command declared in `env` is absent from the environment. */
+export function assertEnv(
+  required: readonly string[],
+  env: NodeJS.ProcessEnv
+): void {
+  const missing = required.filter((key) => env[key] === undefined);
+  ensure(
+    missing.length === 0,
+    () =>
+      new EnvironmentError(
+        `missing required environment: ${missing.join(', ')}`,
+        {
+          hint: `set ${missing.join(', ')} before running this command`,
+        }
+      )
+  );
+}

package/src/lib/command/index.mts

@@ -0,0 +1,6 @@
+export * from './abstract-command.mts';
+export * from './parse.mts';
+export * from './env.mts';
+export * from './discovery.mts';
+export * from './transports.mts';
+export type {ChannelSink} from './abstract-command.mts';

package/src/lib/command/parse.mts

@@ -0,0 +1,64 @@
+import type {OptionsRecord} from './abstract-command.mts';
+import {assertUsage} from '../errors/index.mts';
+
+/**
+ * Turn a raw values map (keyed by option name) into a validated values record.
+ * Transport-neutral: the cli builds `raw` from argv, an MCP server from JSON.
+ */
+export function parseOptions(
+  options: OptionsRecord,
+  raw: Readonly<Record<string, string | boolean>>
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const [key, option] of Object.entries(options)) {
+    let provided: string | number | boolean | undefined = raw[key];
+
+    if (provided === undefined) {
+      if (option.type === 'boolean') {
+        result[key] = false;
+        continue;
+      }
+      if (option.default === undefined) {
+        assertUsage(!option.required, `missing required option: ${key}`);
+        continue;
+      }
+      // Route the default through the same coercion/choices path as a
+      // provided value, so a numeric default given as a string still
+      // resolves to a number and a string default is still validated.
+      provided = option.default;
+    }
+
+    if (option.type === 'boolean') {
+      result[key] = provided === true || provided === 'true';
+      continue;
+    }
+
+    const text = String(provided);
+    if (option.type === 'number') {
+      // Accept a plain decimal literal only. `Number()` alone would also admit
+      // hex/binary/octal (`0x1F`), `Infinity`, and whitespace-padded input,
+      // yielding a value whose meaning does not match a `number` option; the
+      // regex rejects those, and `Number.isFinite` rejects exponent overflow
+      // (`1e999`).
+      const value = Number(text);
+      assertUsage(
+        /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/.test(text) &&
+          Number.isFinite(value),
+        `option ${key} expects a number, got "${text}"`
+      );
+      result[key] = value;
+      continue;
+    }
+
+    if (option.choices !== undefined) {
+      assertUsage(
+        option.choices.includes(text),
+        `option ${key} must be one of: ${option.choices.join(', ')}`
+      );
+    }
+    result[key] = text;
+  }
+
+  return result;
+}

package/src/lib/command/test-support.mts

@@ -0,0 +1,81 @@
+import {mkdtemp} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import path from 'node:path';
+
+import {createLogger} from '../logger/index.mts';
+import type {CoreLogger} from '../logger/index.mts';
+import type {Ticket} from '../model/index.mts';
+import type {AbstractCommand} from './abstract-command.mts';
+import {assertEnv} from './env.mts';
+import {parseOptions} from './parse.mts';
+
+/* eslint-disable @typescript-eslint/no-empty-function --
+ * A logger that discards every call, so a test's output only ever reflects `io`. */
+const SILENT: CoreLogger = {
+  error: () => {},
+  warn: () => {},
+  info: () => {},
+  debug: () => {},
+  trace: () => {},
+  log: () => {},
+};
+/* eslint-enable @typescript-eslint/no-empty-function */
+
+/**
+ * Run a command the way a transport would, and return what it wrote to `io`.
+ * `raw` goes through `parseOptions`, so defaults and `choices` apply exactly as
+ * they would from argv or JSON — pass every value as a string except booleans.
+ * Also runs `assertEnv` before `run`, matching both real transports (the cli
+ * and the MCP server), so a command that declares required `env` fails here
+ * the same way it would in production.
+ */
+export async function runCommand(
+  command: AbstractCommand,
+  raw: Record<string, string | boolean>,
+  env: NodeJS.ProcessEnv
+): Promise<string> {
+  const parsed = parseOptions(command.options, raw);
+  assertEnv(command.env, env);
+  let captured = '';
+  await command.run(parsed, {
+    log: createLogger(SILENT),
+    env,
+    io: {
+      write: (chunk) => {
+        captured += chunk;
+      },
+    },
+  });
+  return captured;
+}
+
+/**
+ * An environment pointing at a graph database of this test's own, in a fresh
+ * temp directory. Commands resolve `--db` through `DISPATCH_DB`, so a test that
+ * forgets this one writes the developer's real graph.
+ */
+export async function tempEnv(): Promise<NodeJS.ProcessEnv> {
+  const dir = await mkdtemp(path.join(tmpdir(), 'dispatch-cmd-'));
+  return {DISPATCH_DB: path.join(dir, 'graph.db')};
+}
+
+/**
+ * A ticket whose every optional field is empty, so a test asserting on one of
+ * them is asserting on something it set itself.
+ */
+export function ticket(id: string, project: string): Ticket {
+  return {
+    id,
+    project,
+    url: `https://example.test/${id}`,
+    title: id,
+    status: 'available',
+    targetKind: 'pr',
+    requiresHuman: false,
+    injected: false,
+    priority: null,
+    branchHint: null,
+    labels: [],
+    updatedAt: null,
+  };
+}

package/src/lib/command/transports.mts

@@ -0,0 +1,17 @@
+import type {AbstractCommand} from './abstract-command.mts';
+
+export interface ResolvedTransports {
+  readonly cli: boolean;
+  readonly mcp: boolean;
+}
+
+/**
+ * A command's transport availability with defaults filled in, so gating code
+ * reads definite booleans instead of an optional partial. An unstated
+ * transport is available.
+ */
+export function resolveTransports(
+  command: AbstractCommand
+): ResolvedTransports {
+  return {cli: true, mcp: true, ...command.transports};
+}

package/src/lib/command/types.mts

@@ -0,0 +1,53 @@
+import {AbstractCommand} from './abstract-command.mts';
+import type {ParsedOptions, CommandContext} from './abstract-command.mts';
+
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters, @typescript-eslint/no-unused-vars
+function expectType<T>(_value: T): void {
+  // asserts the argument's static type is assignable to T
+}
+
+const options = {
+  force: {
+    type: 'boolean',
+    description: 'd',
+    positional: false,
+    required: false,
+  },
+  count: {
+    type: 'number',
+    description: 'd',
+    positional: false,
+    required: false,
+    default: 1,
+  },
+  format: {
+    type: 'string',
+    description: 'd',
+    positional: false,
+    required: true,
+    choices: ['json', 'text'],
+  },
+  who: {type: 'string', description: 'd', positional: true, required: false},
+} as const;
+
+class Sample extends AbstractCommand {
+  readonly name = 'sample';
+  readonly summary = 's';
+  readonly env = [];
+  readonly options = options;
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _ctx: CommandContext
+  ): Promise<void> {
+    expectType<boolean>(parsed.force);
+    expectType<number>(parsed.count);
+    expectType<'json' | 'text'>(parsed.format);
+    expectType<string | undefined>(parsed.who);
+  }
+}
+
+// Heterogeneous storage must compile: a subclass widens to AbstractCommand.
+expectType<AbstractCommand[]>([new Sample()]);

package/src/lib/db/CLAUDE.md

@@ -0,0 +1,13 @@
+# db
+
+Low-level SQLite: the connection and the schema. No domain knowledge lives here.
+
+- `database.mts` — `Database`: `open` (pragmas incl. `foreign_keys = ON`, schema
+  bootstrap, version refusal), `transaction` (BEGIN IMMEDIATE), `guard` (maps a
+  locked/unwritable DB to `EnvironmentError`), and `run`/`get`/`all`.
+- `schema.mts` — the `SCHEMA` DDL and `SCHEMA_VERSION`. STRICT tables; the DB is
+  a rebuildable cache, so a version mismatch is refused rather than migrated.
+- `time.mts` — `nowIso` and `assertInstant` (RFC 3339 validation). Timestamps are
+  TEXT ISO-8601 UTC.
+- `with-database.mts` — `withDatabase` (open/close around a command body),
+  `resolveDbPath` (flag → `DISPATCH_DB` → XDG), and the shared `DB_OPTION`.

package/src/lib/db/database.mts

@@ -0,0 +1,160 @@
+import {mkdir} from 'node:fs/promises';
+import {dirname} from 'node:path';
+import {DatabaseSync} from 'node:sqlite';
+
+import {
+  DefinitionError,
+  DispatchError,
+  EnvironmentError,
+} from '../errors/index.mts';
+import {SCHEMA, SCHEMA_VERSION} from './schema.mts';
+
+export type SqlValue = string | number | null;
+export type Row = Record<string, unknown>;
+
+/* eslint-disable @typescript-eslint/require-await --
+ * The async signatures are the point of this class. `node:sqlite` is synchronous
+ * today; these methods are async so an async driver later is a change behind this
+ * facade, not a rewrite of every call site. */
+
+/**
+ * The dispatch database: one SQLite file holding everything the CLI persists.
+ * Owns the connection — pragmas, schema bootstrap, version enforcement,
+ * transactions — and nothing about what the tables mean; the stores sit on top.
+ */
+export class Database {
+  readonly #db: DatabaseSync;
+
+  private constructor(db: DatabaseSync) {
+    this.#db = db;
+  }
+
+  static async open(path: string): Promise<Database> {
+    if (path !== ':memory:') {
+      try {
+        await mkdir(dirname(path), {recursive: true});
+      } catch (cause) {
+        throw new EnvironmentError(
+          'cannot create the directory for the dispatch database',
+          {cause, hint: 'check the path is writable, or point --db elsewhere.'}
+        );
+      }
+    }
+    try {
+      const raw = new DatabaseSync(path);
+      raw.exec('PRAGMA journal_mode = WAL');
+      raw.exec('PRAGMA busy_timeout = 5000');
+      raw.exec('PRAGMA foreign_keys = ON');
+      const db = new Database(raw);
+      db.#bootstrap(path);
+      return db;
+    } catch (cause) {
+      if (cause instanceof DispatchError) throw cause;
+      throw new EnvironmentError('cannot open the dispatch database', {
+        cause,
+        hint: 'check the file is a readable, writable SQLite database and the disk is not full. If it is locked, another dispatch command is mid-write — retry shortly. Deleting the file forces a rebuild.',
+      });
+    }
+  }
+
+  #bootstrap(path: string): void {
+    this.#db.exec(
+      'CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL) STRICT'
+    );
+    const row = this.#db
+      .prepare("SELECT value FROM meta WHERE key = 'schema_version'")
+      .get() as Row | undefined;
+    Database.assertVersion(this, path, row?.value as string | undefined);
+    this.#db.exec(SCHEMA);
+    if (row === undefined) {
+      this.#db
+        .prepare('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)')
+        .run('schema_version', String(SCHEMA_VERSION));
+    }
+  }
+
+  /**
+   * Refuse a file another schema version wrote. Exposed static so a test can
+   * exercise the guard without a second connection. `found` defaults to the
+   * value recorded in `meta`.
+   */
+  static assertVersion(db: Database, path: string, found?: string): void {
+    const recorded =
+      found ??
+      (db.get("SELECT value FROM meta WHERE key = 'schema_version'")?.value as
+        string | undefined);
+    if (recorded !== undefined && recorded !== String(SCHEMA_VERSION)) {
+      throw new EnvironmentError(
+        `the dispatch database at ${path} was written by schema version ${recorded}, not ${String(SCHEMA_VERSION)}`,
+        {
+          hint: `delete ${path} and re-run a full sync. Claims and recorded reviews go with it — release or re-record what still matters first.`,
+        }
+      );
+    }
+  }
+
+  async close(): Promise<void> {
+    this.#db.close();
+  }
+
+  /**
+   * The body must be synchronous: COMMIT runs as soon as it returns, so an
+   * async body would run its post-await statements outside the transaction.
+   * A returned promise is therefore refused outright.
+   */
+  async transaction<T>(body: () => T): Promise<T> {
+    return this.guard(() => {
+      this.#db.exec('BEGIN IMMEDIATE');
+      try {
+        const result = body();
+        if (result instanceof Promise) {
+          throw new DefinitionError('transaction bodies must be synchronous', {
+            hint: 'an async body would commit before its awaits ran; move the awaits outside the transaction.',
+          });
+        }
+        this.#db.exec('COMMIT');
+        return result;
+      } catch (error) {
+        try {
+          this.#db.exec('ROLLBACK');
+        } catch {
+          // A failing ROLLBACK must not replace the error that caused it.
+        }
+        throw error;
+      }
+    });
+  }
+
+  guard<T>(body: () => T): T {
+    try {
+      return body();
+    } catch (cause) {
+      if (cause instanceof DispatchError) throw cause;
+      throw new EnvironmentError(
+        'the dispatch database rejected an operation',
+        {
+          cause,
+          hint: 'if the database is locked, another dispatch command is mid-write — retry shortly. Otherwise check the file is a writable SQLite database and the disk is not full.',
+        }
+      );
+    }
+  }
+
+  run(sql: string, params: SqlValue[] = []): number {
+    return this.guard(() =>
+      Number(this.#db.prepare(sql).run(...params).changes)
+    );
+  }
+
+  get(sql: string, params: SqlValue[] = []): Row | undefined {
+    return this.guard(
+      () => this.#db.prepare(sql).get(...params) as Row | undefined
+    );
+  }
+
+  all(sql: string, params: SqlValue[] = []): Row[] {
+    return this.guard(() => this.#db.prepare(sql).all(...params) as Row[]);
+  }
+}
+
+/* eslint-enable @typescript-eslint/require-await */

package/src/lib/db/index.mts

@@ -0,0 +1,4 @@
+export * from './database.mts';
+export * from './schema.mts';
+export * from './time.mts';
+export * from './with-database.mts';