@ianwremmel/dispatch 0.32.1-bootstrap.0

package/src/commands/project/set.mts

@@ -0,0 +1,50 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, withDatabase} from '../../lib/db/index.mts';
+import {RefreshService} from '../../lib/refresh/index.mts';
+import {ProjectStore} from '../../lib/stores/index.mts';
+
+const options = {
+  id: {
+    type: 'string',
+    description: 'Tracker identifier for the project.',
+    positional: false,
+    required: true,
+  },
+  name: {
+    type: 'string',
+    description: 'Human-readable project name.',
+    positional: false,
+    required: true,
+  },
+  tracker: {
+    type: 'string',
+    description:
+      'Tracker the project lives on, e.g. linear. Every ticket in it inherits this.',
+    positional: false,
+    required: true,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'set';
+  readonly summary = 'Create or update one project.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      await new ProjectStore(db).upsertProject({
+        id: parsed.id,
+        name: parsed.name,
+        source: parsed.tracker,
+      });
+      await new RefreshService(db).reconcile();
+      ctx.io.write(`project ${parsed.id}\n`);
+    });
+  }
+}

package/src/commands/queue.mts

@@ -0,0 +1,41 @@
+import {AbstractCommand} from '../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../lib/command/index.mts';
+import {DB_OPTION, withDatabase} from '../lib/db/index.mts';
+import {dispatchQueue} from '../lib/graph/index.mts';
+
+const options = {
+  project: {
+    type: 'string',
+    description: 'Restrict the queue to one project id.',
+    positional: false,
+    required: false,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'queue';
+  readonly summary =
+    'Print what the scheduler would hand out next, in dispatch order.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      const entries = await dispatchQueue(db, {project: parsed.project});
+      for (const {entry, pass} of entries) {
+        ctx.io.write(
+          `${pass ?? 'available'} ${entry.item.id} kind=${entry.item.kind}` +
+            (entry.item.project === null
+              ? ''
+              : ` project=${entry.item.project}`) +
+            `${entry.item.injected ? ' injected' : ''}\n`
+        );
+      }
+      if (entries.length === 0) ctx.io.write('queue empty\n');
+    });
+  }
+}

package/src/commands/refresh/done.mts

@@ -0,0 +1,42 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, withDatabase} from '../../lib/db/index.mts';
+import {RefreshService} from '../../lib/refresh/index.mts';
+
+const options = {
+  tracker: {
+    type: 'string',
+    description: 'Tracker whose scan is complete.',
+    positional: false,
+    required: true,
+  },
+  cursor: {
+    type: 'string',
+    description:
+      'Opaque tracker token marking how far this scan read. Recorded only when the refresh closes.',
+    positional: false,
+    required: false,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'done';
+  readonly summary = 'Report that everything the scan found has been written.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      const {state, pending} = await new RefreshService(db).completeScan({
+        source: parsed.tracker,
+        cursor: parsed.cursor ?? null,
+      });
+      ctx.io.write(`refresh ${parsed.tracker} ${state}\n`);
+      for (const id of pending) ctx.io.write(`pending ${id}\n`);
+    });
+  }
+}

package/src/commands/refresh/status.mts

@@ -0,0 +1,40 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, withDatabase} from '../../lib/db/index.mts';
+import {RefreshService} from '../../lib/refresh/index.mts';
+
+const options = {
+  tracker: {
+    type: 'string',
+    description: 'Tracker to report on.',
+    positional: false,
+    required: true,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'status';
+  readonly summary =
+    'Print the refresh state and every outstanding instruction.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      const {refresh, requests} = await new RefreshService(db).status(
+        parsed.tracker
+      );
+      ctx.io.write(`refresh ${parsed.tracker} ${refresh?.state ?? 'none'}\n`);
+      for (const request of requests) {
+        if (request.resolution !== null) continue;
+        ctx.io.write(
+          `${request.kind} ${JSON.stringify(request.payload)} delivered=${String(request.deliveredAt !== null)}\n`
+        );
+      }
+    });
+  }
+}

package/src/commands/refresh.mts

@@ -0,0 +1,56 @@
+import {AbstractCommand} from '../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../lib/command/index.mts';
+import {DB_OPTION, withDatabase} from '../lib/db/index.mts';
+import {RefreshService} from '../lib/refresh/index.mts';
+
+const options = {
+  tracker: {
+    type: 'string',
+    description: 'Tracker to refresh, e.g. linear.',
+    positional: false,
+    required: true,
+  },
+  project: {
+    type: 'string',
+    description: 'Comma-separated project ids to scan.',
+    positional: false,
+    required: true,
+  },
+  rebuild: {
+    type: 'boolean',
+    description: 'Drop the graph and scan from scratch, ignoring the cursor.',
+    positional: false,
+    required: false,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'refresh';
+  readonly summary =
+    'Start or resume building the project graph for a tracker.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    const projects = parsed.project
+      .split(',')
+      .map((id) => id.trim())
+      .filter((id) => id !== '');
+
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      const {resumed} = await new RefreshService(db).startScan({
+        source: parsed.tracker,
+        projects,
+        sessionId: ctx.env.CLAUDE_CODE_SESSION_ID ?? null,
+        rebuild: parsed.rebuild,
+      });
+      ctx.io.write(
+        `refresh ${parsed.tracker} ${resumed ? 'resumed' : 'opened'}\n`
+      );
+    });
+  }
+}

package/src/commands/review/record.mts

@@ -0,0 +1,46 @@
+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 {RefreshService} from '../../lib/refresh/index.mts';
+import {correlateSession} from '../../lib/schedule/index.mts';
+import {ReviewStore} from '../../lib/stores/index.mts';
+
+const options = {
+  milestone: {
+    type: 'string',
+    description: 'The milestone whose review just ran.',
+    positional: false,
+    required: true,
+  },
+  session: {
+    type: 'string',
+    description:
+      'Registry id whose claim this releases; defaults to the session correlated from the environment.',
+    positional: false,
+    required: false,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'record';
+  readonly summary =
+    'Record a milestone review with a member snapshot, opening its gate.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      // No server means no claim of this caller's to release; ambiguous
+      // correlation refuses rather than leave a real claim held.
+      const session =
+        (await correlateSession(db, ctx.env, parsed.session)) ?? '';
+      await new ReviewStore(db).record(parsed.milestone, nowIso(), session);
+      await new RefreshService(db).reconcile();
+      ctx.io.write(`review ${parsed.milestone}\n`);
+    });
+  }
+}

package/src/commands/review/release.mts

@@ -0,0 +1,49 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, withDatabase} from '../../lib/db/index.mts';
+import {correlateSession} from '../../lib/schedule/index.mts';
+import {ReviewStore} from '../../lib/stores/index.mts';
+
+const options = {
+  milestone: {
+    type: 'string',
+    description: 'The milestone whose review ended without recording.',
+    positional: false,
+    required: true,
+  },
+  session: {
+    type: 'string',
+    description:
+      'Registry id whose claim this releases; defaults to the session correlated from the environment.',
+    positional: false,
+    required: false,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'release';
+  readonly summary =
+    'Release a milestone-review claim without opening the gate.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      // No server means no claim of this caller's to release; ambiguous
+      // correlation refuses rather than leave a real claim held.
+      const session =
+        (await correlateSession(db, ctx.env, parsed.session)) ?? '';
+      const released = await new ReviewStore(db).release(
+        parsed.milestone,
+        session
+      );
+      ctx.io.write(
+        `released review ${parsed.milestone} existed=${String(released)}\n`
+      );
+    });
+  }
+}

package/src/commands/status.mts

@@ -0,0 +1,85 @@
+import {AbstractCommand} from '../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../lib/command/index.mts';
+import {DB_OPTION, withDatabase} from '../lib/db/index.mts';
+import {derive, dispatchQueue, repoPrLoad} from '../lib/graph/index.mts';
+import {RepoAdmission} from '../lib/schedule/index.mts';
+import {PolicyStore} from '../lib/stores/index.mts';
+
+const options = {
+  project: {
+    type: 'string',
+    description:
+      'Restrict the report to one project id. Anomalies are graph-wide and stay unfiltered.',
+    positional: false,
+    required: false,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'status';
+  readonly summary =
+    'Print per-project counts, milestone gates, anomalies, and the terminal verdict.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      const graph = await derive(db, {project: parsed.project});
+
+      for (const counts of graph.counts) {
+        ctx.io.write(
+          `project ${counts.project} total=${String(counts.total)} ` +
+            `available=${String(counts.available)} blocked=${String(counts.blocked)} ` +
+            `human-blocked=${String(counts.humanBlocked)} in-flight=${String(counts.inFlight)} ` +
+            `dormant=${String(counts.dormant)} verified=${String(counts.verified)} ` +
+            `canceled=${String(counts.canceled)} terminal=${String(counts.terminal)}\n`
+        );
+      }
+      for (const milestone of graph.milestones) {
+        ctx.io.write(
+          `milestone ${milestone.id} project=${milestone.project} ` +
+            `members=${String(milestone.memberCount)} unresolved=${String(milestone.openCount)} ` +
+            `ready-for-review=${String(milestone.readyForReview)} ` +
+            `review-recorded=${String(milestone.reviewRecorded)} open=${String(milestone.open)}\n`
+        );
+      }
+      for (const entry of graph.prs) {
+        ctx.io.write(
+          `pr ${entry.item.id}` +
+            (entry.item.ticket === null ? '' : ` ticket=${entry.item.ticket}`) +
+            ` ${entry.classification}\n`
+        );
+      }
+      // Why the queue is idle when it is: a repo at one of its caps holds
+      // work back with nothing else to show for it, which otherwise reads as
+      // a wedged system. Deliberately no `reserve` here — this reports the
+      // caps holding work *now*, from load already on the forge. Simulating
+      // the fill pass instead would blame a cap for a queue the compute budget
+      // is what is actually holding, and the scheduler's own claims land in
+      // this reading within a tick anyway.
+      const admission = new RepoAdmission(
+        await new PolicyStore(db).getRepoCaps(),
+        await repoPrLoad(db)
+      );
+      for (const {entry} of await dispatchQueue(db, {
+        project: parsed.project,
+      })) {
+        if (entry.item.kind === 'pr') admission.admit(entry.item);
+      }
+      for (const hold of admission.holds()) {
+        ctx.io.write(
+          `cap-hold ${hold.repo} ${hold.cap}=${String(hold.observed)}/${String(hold.limit)} ` +
+            `waiting=${String(hold.waiting)}\n`
+        );
+      }
+      for (const anomaly of graph.anomalies) {
+        ctx.io.write(`anomaly ${anomaly.kind} ${anomaly.detail}\n`);
+      }
+      ctx.io.write(`terminal=${String(graph.terminal)}\n`);
+    });
+  }
+}

package/src/commands/ticket/missing.mts

@@ -0,0 +1,31 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, withDatabase} from '../../lib/db/index.mts';
+import {RefreshService} from '../../lib/refresh/index.mts';
+
+const options = {
+  id: {
+    type: 'string',
+    description: 'The ticket id the tracker has no record of.',
+    positional: false,
+    required: true,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'missing';
+  readonly summary = 'Report that a requested ticket does not exist.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      await new RefreshService(db).markMissing(parsed.id);
+      ctx.io.write(`missing ticket ${parsed.id}\n`);
+    });
+  }
+}

package/src/commands/ticket/rm.mts

@@ -0,0 +1,33 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, withDatabase} from '../../lib/db/index.mts';
+import {RefreshService} from '../../lib/refresh/index.mts';
+import {TicketStore} from '../../lib/stores/index.mts';
+
+const options = {
+  id: {
+    type: 'string',
+    description: 'Tracker identifier for the ticket.',
+    positional: false,
+    required: true,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'rm';
+  readonly summary = 'Delete one ticket.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      const existed = await new TicketStore(db).removeTicket(parsed.id);
+      await new RefreshService(db).reconcile();
+      ctx.io.write(`removed ticket ${parsed.id} existed=${String(existed)}\n`);
+    });
+  }
+}

package/src/commands/ticket/set.mts

@@ -0,0 +1,134 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, withDatabase} from '../../lib/db/index.mts';
+import {STATUSES, TARGET_KINDS} from '../../lib/model/status.mts';
+import {RefreshService} from '../../lib/refresh/index.mts';
+import {TicketStore} from '../../lib/stores/index.mts';
+
+const options = {
+  id: {
+    type: 'string',
+    description: 'Tracker identifier, e.g. CLC-945.',
+    positional: false,
+    required: true,
+  },
+  project: {
+    type: 'string',
+    description: 'Project the ticket belongs to.',
+    positional: false,
+    required: true,
+  },
+  status: {
+    type: 'string',
+    description: 'Normalized lifecycle status; map the tracker state yourself.',
+    positional: false,
+    required: true,
+    choices: STATUSES,
+  },
+  title: {
+    type: 'string',
+    description: 'Ticket title.',
+    positional: false,
+    required: false,
+  },
+  url: {
+    type: 'string',
+    description: 'Ticket URL.',
+    positional: false,
+    required: false,
+  },
+  'target-kind': {
+    type: 'string',
+    description: 'What finishing this ticket produces.',
+    positional: false,
+    required: false,
+    choices: TARGET_KINDS,
+  },
+  'requires-human': {
+    type: 'boolean',
+    description: 'Only a human may work this ticket.',
+    positional: false,
+    required: false,
+  },
+  injected: {
+    type: 'boolean',
+    description: 'Rank this ticket to the top of the frontier.',
+    positional: false,
+    required: false,
+  },
+  priority: {
+    type: 'number',
+    description: 'Lower is more urgent; omit if the tracker has none.',
+    positional: false,
+    required: false,
+  },
+  labels: {
+    type: 'string',
+    description: 'Comma-separated tracker labels, passed through as-is.',
+    positional: false,
+    required: false,
+  },
+  'branch-hint': {
+    type: 'string',
+    description: 'Branch-name seed the tracker suggests.',
+    positional: false,
+    required: false,
+  },
+  'updated-at': {
+    type: 'string',
+    description: 'When the tracker last saw the ticket move (RFC 3339).',
+    positional: false,
+    required: false,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'set';
+  readonly summary = 'Create or update one ticket.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    const labels =
+      parsed.labels === undefined
+        ? undefined
+        : parsed.labels
+            .split(',')
+            .map((label) => label.trim())
+            .filter((label) => label !== '');
+
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      // Only what the caller named. A re-read reports the fields it was asked
+      // about and says nothing about the rest, so absent must mean "leave it"
+      // — otherwise answering a refresh blanks the ticket's title and labels.
+      // `injected` and `requires-human` are carried only when set: the parser
+      // cannot tell an absent boolean from a false one.
+      await new TicketStore(db).patchTicket({
+        id: parsed.id,
+        project: parsed.project,
+        status: parsed.status,
+        ...(parsed.url === undefined ? {} : {url: parsed.url}),
+        ...(parsed.title === undefined ? {} : {title: parsed.title}),
+        ...(parsed['target-kind'] === undefined
+          ? {}
+          : {targetKind: parsed['target-kind']}),
+        ...(parsed['requires-human'] ? {requiresHuman: true} : {}),
+        ...(parsed.injected ? {injected: true} : {}),
+        ...(parsed.priority === undefined ? {} : {priority: parsed.priority}),
+        ...(parsed['branch-hint'] === undefined
+          ? {}
+          : {branchHint: parsed['branch-hint']}),
+        ...(labels === undefined ? {} : {labels}),
+        ...(parsed['updated-at'] === undefined
+          ? {}
+          : {updatedAt: parsed['updated-at']}),
+      });
+      await new RefreshService(db).reconcile();
+      ctx.io.write(`ticket ${parsed.id}\n`);
+    });
+  }
+}

package/src/commands/worker/rm.mts

@@ -0,0 +1,46 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, 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 whose worker address to drop.',
+    positional: false,
+    required: true,
+  },
+  db: DB_OPTION,
+} as const;
+
+/**
+ * Hand a node from warm relay to cold recovery, for a relay that provably
+ * went nowhere: drops the caller's own address and releases its claim, so
+ * the scheduler re-serves the item as a `resume` pass.
+ */
+export class Command extends AbstractCommand {
+  readonly name = 'rm';
+  readonly summary = "Drop a node's worker address.";
+  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 recorded the address can revoke it.',
+          })
+      );
+      const removed = await new WorkerStore(db).remove(parsed.node, session);
+      ctx.io.write(`worker ${parsed.node} removed=${String(removed)}\n`);
+    });
+  }
+}