@ianwremmel/dispatch 0.32.1-bootstrap.0

package/src/lib/mcp/dispatch.mts

@@ -0,0 +1,60 @@
+import type {AbstractCommand, Io} from '../command/index.mts';
+import {parseOptions, assertEnv} from '../command/index.mts';
+import type {Logger} from '../logger/index.mts';
+import type {ChannelSink} from '../command/index.mts';
+import {DispatchError} from '../errors/index.mts';
+
+export interface ToolResult {
+  readonly content: readonly {readonly type: 'text'; readonly text: string}[];
+  readonly isError?: boolean;
+}
+
+export interface CallToolContext {
+  readonly env: NodeJS.ProcessEnv;
+  readonly log: Logger;
+  readonly channel?: ChannelSink | undefined;
+}
+
+/**
+ * Run one command from JSON tool input. Output written to `io` becomes the
+ * result text; a `DispatchError` (bad input, missing env) becomes an `isError`
+ * result rather than throwing, mirroring how the cli maps it to an exit code.
+ */
+export async function callTool(
+  command: AbstractCommand,
+  args: Readonly<Record<string, unknown>>,
+  ctx: CallToolContext
+): Promise<ToolResult> {
+  let captured = '';
+  const io: Io = {
+    write: (chunk) => {
+      captured += chunk;
+    },
+  };
+
+  try {
+    const raw: Record<string, string | boolean> = {};
+    for (const [key, value] of Object.entries(args)) {
+      if (value === undefined || value === null) continue;
+      raw[key] =
+        typeof value === 'boolean'
+          ? value
+          : typeof value === 'number' || typeof value === 'string'
+            ? String(value)
+            : JSON.stringify(value);
+    }
+    const parsed = parseOptions(command.options, raw);
+    assertEnv(command.env, ctx.env);
+    await command.run(parsed, {
+      log: ctx.log,
+      env: ctx.env,
+      io,
+      channel: ctx.channel,
+    });
+    return {content: [{type: 'text', text: captured}]};
+  } catch (error) {
+    const text =
+      error instanceof DispatchError ? error.toString() : String(error);
+    return {content: [{type: 'text', text}], isError: true};
+  }
+}

package/src/lib/mcp/drain.mts

@@ -0,0 +1,83 @@
+import {nowIso} from '../db/time.mts';
+import {withDatabase} from '../db/index.mts';
+import {FetchRequestStore, RefreshStore} from '../stores/index.mts';
+import type {ScanPayload, TicketPayload} from '../stores/index.mts';
+import type {ChannelWriter} from './channel.mts';
+
+/**
+ * Push every instruction the graph owes the session, then every completion.
+ * Returns how many events went out. Delivery is recorded in the database, so a
+ * restart re-derives what is still owed rather than assuming a push landed.
+ */
+export async function drainInstructions(
+  channel: ChannelWriter,
+  env: NodeJS.ProcessEnv,
+  now: () => string = nowIso
+): Promise<number> {
+  return withDatabase(undefined, env, async (db) => {
+    const requests = new FetchRequestStore(db);
+    const refreshes = new RefreshStore(db);
+    const at = now();
+    let sent = 0;
+
+    for (const request of await requests.undelivered()) {
+      if (request.kind === 'scan_project') {
+        const payload = request.payload as ScanPayload;
+        channel.push(
+          'scan_project',
+          {
+            tracker: request.source,
+            projects: payload.projects.join(','),
+            cursor: payload.cursor,
+          },
+          scanBody(request.source, payload)
+        );
+      } else if (request.kind === 'fetch_ticket') {
+        const {ticket} = request.payload as TicketPayload;
+        channel.push(
+          'fetch_ticket',
+          {tracker: request.source, ticket},
+          ticketBody(request.source, ticket)
+        );
+      } else {
+        const {ticket} = request.payload as TicketPayload;
+        channel.push(
+          'refresh_ticket',
+          {tracker: request.source, ticket},
+          `Re-fetch ticket ${ticket} from ${request.source} and record it with dispatch ticket set — the graph's copy may be stale. If ${request.source} no longer has it, run: dispatch ticket missing --id ${ticket}`
+        );
+      }
+      await requests.markDelivered(request.id, at);
+      sent += 1;
+    }
+
+    for (const source of await refreshes.pendingCompletions()) {
+      channel.push(
+        'refresh_complete',
+        {tracker: source},
+        `The ${source} project graph is complete. Stop fetching and report it built.`
+      );
+      await refreshes.markCompletionEmitted(source, at);
+      sent += 1;
+    }
+
+    return sent;
+  });
+}
+
+function scanBody(source: string, payload: ScanPayload): string {
+  const since =
+    payload.cursor === null ? '' : ` updated since ${payload.cursor}`;
+  return [
+    `Scan every ticket in ${payload.projects.join(', ')} on ${source}${since}.`,
+    'Record each project, milestone, ticket, and dependency with the dispatch',
+    `commands, then run: dispatch refresh done --tracker ${source} --cursor <token>`,
+  ].join(' ');
+}
+
+function ticketBody(source: string, ticket: string): string {
+  return [
+    `Fetch ticket ${ticket} from ${source} and record it with dispatch ticket set.`,
+    `If ${source} has no such ticket, run: dispatch ticket missing --id ${ticket}`,
+  ].join(' ');
+}

package/src/lib/mcp/index.mts

@@ -0,0 +1,5 @@
+export * from './tools.mts';
+export * from './dispatch.mts';
+export * from './mcp.mts';
+export * from './channel.mts';
+export * from './drain.mts';

package/src/lib/mcp/mcp.mts

@@ -0,0 +1,267 @@
+import {readFile} from 'node:fs/promises';
+import readline from 'node:readline';
+import type {Readable, Writable} from 'node:stream';
+
+import type {CommandNode} from '../command/index.mts';
+import {createLogger, streamSink} from '../logger/index.mts';
+import type {Logger} from '../logger/index.mts';
+import {buildTools} from './tools.mts';
+import type {BuiltTools} from './tools.mts';
+import {callTool} from './dispatch.mts';
+import {JsonRpcError} from '../errors/index.mts';
+import {ChannelWriter} from './channel.mts';
+import {drainInstructions} from './drain.mts';
+
+const PROTOCOL_VERSION = '2025-06-18';
+
+/**
+ * The handshake reports the shipped plugin version, read from the manifest so
+ * the two can never disagree. A missing or unreadable manifest (a stripped-down
+ * install) degrades to 0.0.0 rather than failing the handshake.
+ */
+async function serverInfo(): Promise<{name: string; version: string}> {
+  try {
+    const manifest = new URL(
+      '../../../.claude-plugin/plugin.json',
+      import.meta.url
+    );
+    const parsed = JSON.parse(await readFile(manifest, 'utf8')) as {
+      version?: unknown;
+    };
+    return {
+      name: 'dispatch',
+      version: typeof parsed.version === 'string' ? parsed.version : '0.0.0',
+    };
+  } catch {
+    return {name: 'dispatch', version: '0.0.0'};
+  }
+}
+
+interface JsonRpcRequest {
+  jsonrpc?: string;
+  id?: string | number | null;
+  method?: string;
+  params?: Record<string, unknown>;
+}
+
+interface RequestContext {
+  readonly tools: BuiltTools;
+  readonly env: NodeJS.ProcessEnv;
+  readonly log: Logger;
+  readonly serverInfo: {name: string; version: string};
+  readonly channel: ChannelWriter;
+}
+
+interface Handled {
+  readonly response: unknown;
+  readonly ranTool: boolean;
+}
+
+/**
+ * Serve MCP over newline-delimited JSON-RPC 2.0 on stdin/stdout until stdin
+ * closes. When `tick` is given, its `run` fires on the interval and after
+ * every tool call — the scheduling heartbeat riding the same channel.
+ */
+export async function runMcpServer(opts: {
+  tree: CommandNode;
+  stdin: Readable;
+  stdout: Writable;
+  stderr: Writable;
+  env: NodeJS.ProcessEnv;
+  tick?: {
+    intervalMs: number;
+    run: (channel: ChannelWriter) => Promise<void>;
+  };
+}): Promise<void> {
+  const channel = new ChannelWriter((payload) => {
+    opts.stdout.write(`${JSON.stringify(payload)}\n`);
+  });
+
+  const ctx: RequestContext = {
+    tools: buildTools(opts.tree),
+    env: opts.env,
+    log: createLogger(streamSink(opts.stderr)),
+    serverInfo: await serverInfo(),
+    channel,
+  };
+
+  // Every tick entrypoint — the timer and the post-tool-call run — shares one
+  // non-reentrancy guard: a tick requested while one runs coalesces into a
+  // single follow-up rather than overlapping DB work.
+  const tickState = {running: false, requested: false};
+  const tickQuietly = async (): Promise<void> => {
+    if (opts.tick === undefined) return;
+    if (tickState.running) {
+      tickState.requested = true;
+      return;
+    }
+    tickState.running = true;
+    try {
+      do {
+        tickState.requested = false;
+        try {
+          await opts.tick.run(channel);
+        } catch (error) {
+          ctx.log.error('scheduler tick failed', {
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- the await above can re-enter tickQuietly, which sets `requested`; the analyzer cannot see that mutation
+      } while (tickState.requested);
+    } finally {
+      tickState.running = false;
+    }
+  };
+
+  // The timer drains as well as ticks: an idle session makes no tool calls
+  // while it waits on channel events, so an instruction the scheduler
+  // enqueues after the last call would otherwise sit undelivered until the
+  // session happens to call a tool — which, waiting on that very
+  // instruction, it never does. Tick first so the asks this beat enqueues
+  // are delivered in the same beat.
+  const timer =
+    opts.tick === undefined
+      ? undefined
+      : setInterval(() => {
+          void tickQuietly().then(() => drainQuietly(channel, ctx));
+        }, opts.tick.intervalMs);
+
+  try {
+    const rl = readline.createInterface({
+      input: opts.stdin,
+      crlfDelay: Infinity,
+    });
+    for await (const line of rl) {
+      if (line.trim() === '') continue;
+      const {response, ranTool} = await handleLine(line, ctx);
+      if (response !== undefined)
+        opts.stdout.write(`${JSON.stringify(response)}\n`);
+      if (ranTool) {
+        await drainQuietly(channel, ctx);
+        await tickQuietly();
+      }
+    }
+  } finally {
+    if (timer !== undefined) clearInterval(timer);
+  }
+}
+
+/**
+ * A drain failure (an unwritable state dir, a locked file, a schema-version
+ * mismatch after an upgrade) must not take the read loop down with it — the
+ * graph is a rebuildable cache, and stdout is the JSON-RPC channel, so the
+ * failure goes to stderr and the undelivered rows stay undelivered for the
+ * next tool call to retry.
+ */
+async function drainQuietly(
+  channel: ChannelWriter,
+  ctx: RequestContext
+): Promise<void> {
+  try {
+    await drainInstructions(channel, ctx.env);
+  } catch (error) {
+    ctx.log.error('channel drain failed', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+async function handleLine(line: string, ctx: RequestContext): Promise<Handled> {
+  let request: JsonRpcRequest;
+  try {
+    request = JSON.parse(line) as JsonRpcRequest;
+  } catch {
+    return {
+      response: errorResponse(null, new JsonRpcError(-32700, 'parse error')),
+      ranTool: false,
+    };
+  }
+
+  const ranTool = request.method === 'tools/call';
+
+  // A notification is defined by the absence of `id`, not by the method it
+  // names — an explicit `null` id is still a request per the current
+  // behavior below.
+  const isNotification = request.id === undefined;
+
+  if (isNotification) {
+    // Never reply to a notification, regardless of how dispatch fares.
+    try {
+      if (request.jsonrpc === '2.0' && typeof request.method === 'string') {
+        await dispatch(request.method, request.params ?? {}, ctx);
+      }
+    } catch {
+      // swallow: notifications get no response, even on failure
+    }
+    return {response: undefined, ranTool};
+  }
+
+  const id = request.id ?? null;
+  try {
+    if (request.jsonrpc !== '2.0' || typeof request.method !== 'string') {
+      throw new JsonRpcError(-32600, 'invalid request');
+    }
+    const result = await dispatch(request.method, request.params ?? {}, ctx);
+    return {response: {jsonrpc: '2.0', id, result}, ranTool};
+  } catch (error) {
+    if (error instanceof JsonRpcError) {
+      return {response: errorResponse(id, error), ranTool};
+    }
+    // A non-JsonRpcError from a handler must not kill the read loop for
+    // later lines, so it becomes an internal-error response instead of a
+    // rethrow.
+    return {
+      response: errorResponse(id, new JsonRpcError(-32603, 'internal error')),
+      ranTool,
+    };
+  }
+}
+
+async function dispatch(
+  method: string,
+  params: Record<string, unknown>,
+  ctx: RequestContext
+): Promise<unknown> {
+  switch (method) {
+    case 'initialize':
+      return {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {tools: {}, experimental: {'claude/channel': {}}},
+        serverInfo: ctx.serverInfo,
+      };
+    case 'notifications/initialized':
+      return undefined;
+    case 'tools/list':
+      return {tools: ctx.tools.defs};
+    case 'tools/call': {
+      const name = params.name;
+      if (typeof name !== 'string') {
+        throw new JsonRpcError(-32602, 'invalid params: name is required');
+      }
+      const command = ctx.tools.byName.get(name);
+      if (command === undefined) {
+        throw new JsonRpcError(-32602, `unknown tool: ${name}`);
+      }
+      const args =
+        (params.arguments as Record<string, unknown> | undefined) ?? {};
+      return callTool(command, args, {
+        env: ctx.env,
+        log: ctx.log,
+        channel: ctx.channel,
+      });
+    }
+    default:
+      throw new JsonRpcError(-32601, `method not found: ${method}`);
+  }
+}
+
+function errorResponse(
+  id: string | number | null,
+  error: JsonRpcError
+): unknown {
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: {code: error.code, message: error.message},
+  };
+}

package/src/lib/mcp/tools.mts

@@ -0,0 +1,77 @@
+import type {CommandNode, AbstractCommand, Option} from '../command/index.mts';
+import {resolveTransports} from '../command/index.mts';
+
+interface PropertySchema {
+  type: 'string' | 'number' | 'boolean';
+  description: string;
+  enum?: readonly string[];
+  default?: string | number | boolean;
+}
+
+export interface JsonSchema {
+  readonly type: 'object';
+  readonly properties: Record<string, PropertySchema>;
+  readonly required?: readonly string[];
+}
+
+export interface ToolDef {
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: JsonSchema;
+}
+
+export interface BuiltTools {
+  readonly defs: readonly ToolDef[];
+  readonly byName: ReadonlyMap<string, AbstractCommand>;
+}
+
+/** Walk the command tree into MCP tool defs plus a name -> command lookup. */
+export function buildTools(tree: CommandNode): BuiltTools {
+  const defs: ToolDef[] = [];
+  const byName = new Map<string, AbstractCommand>();
+  walk(tree, [], defs, byName);
+  return {defs, byName};
+}
+
+function walk(
+  node: CommandNode,
+  path: string[],
+  defs: ToolDef[],
+  byName: Map<string, AbstractCommand>
+): void {
+  const command = node.command;
+  if (command !== undefined && resolveTransports(command).mcp) {
+    const name = path.join('_');
+    defs.push({
+      name,
+      description: command.summary,
+      inputSchema: inputSchema(command),
+    });
+    byName.set(name, command);
+  }
+  for (const [segment, child] of node.children) {
+    walk(child, [...path, segment], defs, byName);
+  }
+}
+
+function inputSchema(command: AbstractCommand): JsonSchema {
+  const properties: Record<string, PropertySchema> = {};
+  const required: string[] = [];
+  for (const [key, option] of Object.entries(command.options)) {
+    properties[key] = propertySchema(option);
+    if (option.required) required.push(key);
+  }
+  return required.length > 0
+    ? {type: 'object', properties, required}
+    : {type: 'object', properties};
+}
+
+function propertySchema(option: Option): PropertySchema {
+  const schema: PropertySchema = {
+    type: option.type,
+    description: option.description,
+  };
+  if (option.choices !== undefined) schema.enum = option.choices;
+  if (option.default !== undefined) schema.default = option.default;
+  return schema;
+}

package/src/lib/model/CLAUDE.md

@@ -0,0 +1,8 @@
+# model
+
+Pure domain types and vocabulary. No SQL.
+
+- `status.mts` — the tracker-neutral enums (`Status`, `TargetKind`, `PrOrigin`,
+  `Kind`, `OutcomeKind`), their guards, `GROUP_OF`, and `RESOLVED_STATUSES`.
+- `types.mts` — the domain model interfaces (`Project`, `Ticket`, `Pr`, …) the
+  stores map rows to and from.

package/src/lib/model/index.mts

@@ -0,0 +1,3 @@
+export * from './repo-caps.mts';
+export * from './status.mts';
+export * from './types.mts';

package/src/lib/model/repo-caps.mts

@@ -0,0 +1,95 @@
+import {assertUsage} from '../errors/index.mts';
+
+/**
+ * How many PRs one repo may have open at once when nothing overrides it. An
+ * open PR holds third-party resources — preview stacks, cloud quota — for as
+ * long as it stays open, which no claim-based budget bounds: a worker releases
+ * its claim the moment it yields to a wait.
+ */
+export const DEFAULT_MAX_OPEN_PRS = 5;
+
+/**
+ * How many of one repo's PRs may have CI running at once when nothing
+ * overrides it. Deliberately coarse: a PR with twenty parallel jobs counts as
+ * one, because the failure being prevented is "too much in flight at once"
+ * rather than exact job accounting.
+ */
+export const DEFAULT_MAX_IN_FLIGHT_BUILDS = 3;
+
+export const REPO_CAPS = ['open-prs', 'in-flight-builds'] as const;
+export type RepoCap = (typeof REPO_CAPS)[number];
+
+/** Both caps, each a global default plus per-repo overrides. */
+export interface RepoCapPolicy {
+  readonly openPrs: number;
+  readonly inFlightBuilds: number;
+  readonly openPrsByRepo: Readonly<Record<string, number>>;
+  readonly inFlightBuildsByRepo: Readonly<Record<string, number>>;
+}
+
+export const DEFAULT_REPO_CAPS: RepoCapPolicy = Object.freeze({
+  openPrs: DEFAULT_MAX_OPEN_PRS,
+  inFlightBuilds: DEFAULT_MAX_IN_FLIGHT_BUILDS,
+  openPrsByRepo: Object.freeze({}),
+  inFlightBuildsByRepo: Object.freeze({}),
+});
+
+/** The limit in force for one repo: its override, else the global default. */
+export function limitFor(
+  policy: RepoCapPolicy,
+  repo: string,
+  cap: RepoCap
+): number {
+  return cap === 'open-prs'
+    ? (policy.openPrsByRepo[repo] ?? policy.openPrs)
+    : (policy.inFlightBuildsByRepo[repo] ?? policy.inFlightBuilds);
+}
+
+/**
+ * A cap must be a whole number of 0 or more. A negative one is never reached
+ * from below, so it would refuse every PR item forever — and the build cap's
+ * only promise is that it drains without an agent.
+ */
+export function assertCapLimit(value: number, option: string): number {
+  assertUsage(
+    Number.isInteger(value) && value >= 0,
+    `option ${option} expects a whole number of 0 or more, got "${String(value)}"`
+  );
+  return value;
+}
+
+/**
+ * Parse an override list — `owner/repo=2,owner/other=0` — into a limit per
+ * repo. The option name rides along so a malformed entry names the flag its
+ * writer has to fix.
+ */
+export function parseRepoLimits(
+  spec: string,
+  option: string
+): Record<string, number> {
+  const limits: Record<string, number> = {};
+  for (const part of spec.split(',')) {
+    const entry = part.trim();
+    if (entry === '') continue;
+    const split = entry.indexOf('=');
+    assertUsage(
+      split > 0,
+      `option ${option} expects "owner/repo=<number>" entries, got "${entry}"`
+    );
+    const repo = entry.slice(0, split).trim();
+    const value = entry.slice(split + 1).trim();
+    assertUsage(
+      /^[^/\s]+\/[^/\s]+$/u.test(repo),
+      `option ${option} expects an owner/repo before "=", got "${repo}"`
+    );
+    // An explicit digits-only match, because `Number('')` is 0: an entry that
+    // forgot its limit would otherwise read as a cap of zero and wedge the
+    // repo it names.
+    assertUsage(
+      /^\d+$/u.test(value),
+      `option ${option} expects a whole number of 0 or more for ${repo}, got "${value}"`
+    );
+    limits[repo] = Number(value);
+  }
+  return limits;
+}

package/src/lib/model/status.mts

@@ -0,0 +1,91 @@
+export const KINDS = [
+  'project',
+  'milestone',
+  'ticket',
+  'pr',
+  'unknown',
+] as const;
+export type Kind = (typeof KINDS)[number];
+export type ConcreteKind = Exclude<Kind, 'unknown'>;
+
+export const STATUSES = [
+  'backlog',
+  'paused',
+  'awaiting-external',
+  'available',
+  'in-progress',
+  'in-review',
+  'finished',
+  'delivered',
+  'verified',
+  'canceled',
+] as const;
+export type Status = (typeof STATUSES)[number];
+
+export const STATUS_GROUPS = [
+  'backlog',
+  'unstarted',
+  'started',
+  'completed',
+  'canceled',
+] as const;
+export type StatusGroup = (typeof STATUS_GROUPS)[number];
+
+export const GROUP_OF: Readonly<Record<Status, StatusGroup>> = Object.freeze({
+  backlog: 'backlog',
+  paused: 'backlog',
+  'awaiting-external': 'backlog',
+  available: 'unstarted',
+  'in-progress': 'started',
+  'in-review': 'started',
+  finished: 'started',
+  delivered: 'started',
+  verified: 'completed',
+  canceled: 'canceled',
+});
+
+/** Statuses that stop a ticket blocking its dependents (effective blocking). */
+export const RESOLVED_STATUSES: ReadonlySet<Status> = new Set<Status>([
+  'verified',
+  'canceled',
+]);
+
+export function isStatus(value: string): value is Status {
+  return (STATUSES as readonly string[]).includes(value);
+}
+
+export function isResolved(status: Status): boolean {
+  return RESOLVED_STATUSES.has(status);
+}
+
+export const TARGET_KINDS = ['pr', 'verification', 'human-only'] as const;
+export type TargetKind = (typeof TARGET_KINDS)[number];
+
+export function isTargetKind(value: string): value is TargetKind {
+  return (TARGET_KINDS as readonly string[]).includes(value);
+}
+
+export const PR_ORIGINS = ['prompt', 'ticket', 'adopted', 'resumed'] as const;
+export type PrOrigin = (typeof PR_ORIGINS)[number];
+
+export function isPrOrigin(value: string): value is PrOrigin {
+  return (PR_ORIGINS as readonly string[]).includes(value);
+}
+
+export const OUTCOMES = [
+  'verified',
+  'canceled',
+  'delivered',
+  'human-blocked',
+  'decomposed',
+  'failed',
+] as const;
+export type OutcomeKind = (typeof OUTCOMES)[number];
+
+export function isOutcome(value: string): value is OutcomeKind {
+  return (OUTCOMES as readonly string[]).includes(value);
+}
+
+export const STATUS_LIST = STATUSES.join(', ');
+export const TARGET_KIND_LIST = TARGET_KINDS.join(', ');
+export const PR_ORIGIN_LIST = PR_ORIGINS.join(', ');