spur-board 0.1.0

package/dist/mcp.mjs

@@ -0,0 +1,123 @@
+import { O as ERRORS, l as renderMcpError, o as OPERATIONS } from "./src-CqH_W7D8.mjs";
+import { r as CliError, t as requestOperation } from "./client-C1hJzdYE.mjs";
+import { t as loadClientConfig } from "./config-DQmktVi-.mjs";
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { McpServer, fromJsonSchema } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+//#region src/mcp.ts
+const handlerValidator = { getValidator() {
+	return (input) => ({
+		valid: true,
+		data: input,
+		errorMessage: void 0
+	});
+} };
+function toolInputSchema(op, agent) {
+	const source = z.toJSONSchema(op.input, { io: "input" });
+	if (op.kind === "query") return {
+		...source,
+		type: "object"
+	};
+	const key = {
+		type: "string",
+		minLength: 1,
+		description: "Key to reuse when retrying this action."
+	};
+	const withKey = (schema) => ({
+		...schema,
+		properties: {
+			...schema["properties"],
+			idempotencyKey: key
+		},
+		...agent ? { required: [...schema["required"] ?? [], "idempotencyKey"] } : {}
+	});
+	if (Array.isArray(source["oneOf"])) return {
+		...source,
+		type: "object",
+		oneOf: source["oneOf"].map((entry) => withKey(entry))
+	};
+	return {
+		...withKey(source),
+		type: "object"
+	};
+}
+function toolDescription(op) {
+	const example = op.kind === "mutation" ? {
+		...op.examples[0].input,
+		idempotencyKey: `${op.mcp.name}-example-001`
+	} : op.examples[0].input;
+	return [
+		op.description,
+		`Use when: ${op.mcp.whenToUse}`,
+		`When not to use: ${op.mcp.whenNotToUse}`,
+		`Example: ${JSON.stringify(example)}`,
+		...op.kind === "mutation" ? ["Choose a unique idempotencyKey for each action; reuse it on retries."] : []
+	].join("\n");
+}
+function parseArguments(op, argumentsValue, agent) {
+	if (!argumentsValue || typeof argumentsValue !== "object" || Array.isArray(argumentsValue)) throw new CliError("usage");
+	const { idempotencyKey, ...input } = argumentsValue;
+	let key;
+	if (op.kind === "mutation") if (idempotencyKey === void 0 && !agent) key = randomUUID();
+	else if (typeof idempotencyKey === "string" && idempotencyKey.trim()) key = idempotencyKey;
+	else throw new CliError("usage");
+	else if (idempotencyKey !== void 0) throw new CliError("usage");
+	const parsed = op.input.safeParse(input);
+	if (!parsed.success) throw new CliError("usage");
+	return {
+		input: parsed.data,
+		key
+	};
+}
+/** One tool per catalog operation, with no daemon/config access until a tool is called. */
+function createMcpServer(env = process.env, loadConfig = loadClientConfig) {
+	const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+	const server = new McpServer({
+		name: "spur-board",
+		version
+	});
+	const agent = Boolean(env["SPUR_SESSION"]);
+	for (const op of OPERATIONS) server.registerTool(op.mcp.name, {
+		description: toolDescription(op),
+		inputSchema: fromJsonSchema(toolInputSchema(op, agent), handlerValidator),
+		outputSchema: op.output,
+		annotations: {
+			readOnlyHint: op.kind === "query",
+			idempotentHint: op.kind === "mutation"
+		}
+	}, async (argumentsValue) => {
+		let key;
+		try {
+			const parsed = parseArguments(op, argumentsValue, agent);
+			key = parsed.key;
+			const config = loadConfig(env);
+			const value = await requestOperation(op, parsed.input, key, config);
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(value)
+				}],
+				structuredContent: value
+			};
+		} catch (cause) {
+			const error = cause instanceof CliError ? cause : new CliError("unexpected");
+			return renderMcpError({
+				code: error.code,
+				requestId: error.requestId,
+				...error.context || key && ERRORS[error.code].exit === 5 ? { context: {
+					...error.context,
+					...key && ERRORS[error.code].exit === 5 ? { idempotencyKey: key } : {}
+				} } : {}
+			});
+		}
+	});
+	return server;
+}
+/** Stdio is reserved for JSON-RPC; callers may log diagnostics only to stderr. */
+function startMcp() {
+	serveStdio(() => createMcpServer());
+}
+//#endregion
+export { createMcpServer, startMcp };

package/dist/migrations/0001_init.sql

@@ -0,0 +1,197 @@
+-- Schema v1 of the board store. Forward only: never edit this file once committed;
+-- add the next numbered file instead. Timestamps are ISO-8601 UTC text, JSON columns
+-- hold text checked by zod on read and write, flags are 0 or 1.
+
+CREATE TABLE task (
+  id INTEGER PRIMARY KEY,
+  project TEXT NOT NULL,
+  tracker_kind TEXT NOT NULL,
+  tracker_id TEXT NOT NULL,
+  key TEXT NOT NULL,
+  membership TEXT NOT NULL,
+  archive_reason TEXT,
+  "column" TEXT NOT NULL,
+  shadow_column TEXT,
+  column_epoch INTEGER NOT NULL DEFAULT 0,
+  left_moves INTEGER NOT NULL DEFAULT 0,
+  merged_past_gate INTEGER NOT NULL DEFAULT 0 CHECK (merged_past_gate IN (0, 1)),
+  created_at TEXT NOT NULL,
+  UNIQUE (project, tracker_kind, tracker_id)
+) STRICT;
+
+CREATE TABLE pr_snapshot (
+  repo TEXT NOT NULL,
+  number INTEGER NOT NULL,
+  head_sha TEXT NOT NULL,
+  head_branch TEXT NOT NULL,
+  state TEXT NOT NULL,
+  draft INTEGER NOT NULL CHECK (draft IN (0, 1)),
+  mergeable TEXT,
+  merge_state TEXT,
+  detail TEXT NOT NULL,
+  source TEXT NOT NULL,
+  observed_at TEXT NOT NULL,
+  PRIMARY KEY (repo, number)
+) STRICT;
+
+CREATE TABLE ticket_snapshot (
+  task_id INTEGER PRIMARY KEY REFERENCES task (id),
+  status TEXT NOT NULL,
+  assignee TEXT,
+  detail TEXT NOT NULL,
+  source TEXT NOT NULL,
+  observed_at TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE session_snapshot (
+  id TEXT PRIMARY KEY,
+  spur_project TEXT NOT NULL,
+  branch TEXT,
+  pr TEXT,
+  raw_state TEXT NOT NULL,
+  state TEXT NOT NULL,
+  first_seen TEXT NOT NULL,
+  last_seen TEXT NOT NULL,
+  ended_at TEXT,
+  end_reason TEXT,
+  detail TEXT NOT NULL,
+  source TEXT NOT NULL,
+  observed_at TEXT NOT NULL
+) STRICT;
+
+-- A task's link to a PR (entity 'pr') or to a spur session (entity 'session').
+CREATE TABLE link (
+  id INTEGER PRIMARY KEY,
+  task_id INTEGER NOT NULL REFERENCES task (id),
+  entity TEXT NOT NULL,
+  repo TEXT,
+  number INTEGER,
+  pr_state TEXT,
+  session_id TEXT,
+  role TEXT,
+  source TEXT NOT NULL,
+  banned INTEGER NOT NULL DEFAULT 0 CHECK (banned IN (0, 1)),
+  created_at TEXT NOT NULL,
+  -- Unique indexes treat NULLs as distinct, so each entity must carry its identity.
+  CHECK (entity <> 'pr' OR (repo IS NOT NULL AND number IS NOT NULL AND pr_state IS NOT NULL)),
+  CHECK (entity <> 'session' OR session_id IS NOT NULL)
+) STRICT;
+
+CREATE UNIQUE INDEX link_pr_pair ON link (task_id, repo, number) WHERE entity = 'pr';
+CREATE UNIQUE INDEX link_session_pair ON link (task_id, session_id) WHERE entity = 'session';
+-- At most one active, unbanned PR link per task; conflict and banned links are not limited.
+CREATE UNIQUE INDEX link_one_active_pr ON link (task_id)
+  WHERE entity = 'pr' AND pr_state = 'active' AND banned = 0;
+
+-- A column executor marks its turn finished at a head commit. One visit (epoch) may hold
+-- several rows; the row at the current head commit is the one that counts.
+CREATE TABLE submission (
+  id INTEGER PRIMARY KEY,
+  task_id INTEGER NOT NULL REFERENCES task (id),
+  "column" TEXT NOT NULL,
+  epoch INTEGER NOT NULL,
+  commit_sha TEXT NOT NULL,
+  author TEXT NOT NULL,
+  submitted_at TEXT NOT NULL,
+  note TEXT
+) STRICT;
+
+CREATE INDEX submission_task_column_submitted ON submission (task_id, "column", submitted_at);
+
+CREATE TABLE block (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  task_id INTEGER NOT NULL REFERENCES task (id),
+  type TEXT NOT NULL,
+  reason TEXT NOT NULL,
+  author TEXT NOT NULL,
+  addressee_role TEXT NOT NULL,
+  target_column TEXT,
+  state TEXT NOT NULL,
+  outcome TEXT,
+  outcome_reason TEXT,
+  repeat_of INTEGER REFERENCES block (id),
+  unblocked_by TEXT,
+  unblocked_at TEXT,
+  created_at TEXT NOT NULL
+) STRICT;
+
+CREATE INDEX block_task_state ON block (task_id, state);
+
+CREATE TABLE comment (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  task_id INTEGER NOT NULL REFERENCES task (id),
+  block_id INTEGER REFERENCES block (id),
+  author TEXT NOT NULL,
+  text TEXT NOT NULL,
+  revision INTEGER NOT NULL DEFAULT 1,
+  conversation_ref TEXT,
+  message_ref TEXT,
+  acked_revision INTEGER,
+  created_at TEXT NOT NULL
+) STRICT;
+
+CREATE INDEX comment_task_id ON comment (task_id, id);
+
+-- Idempotent operator and agent commands, keyed by the caller's idempotency key.
+CREATE TABLE command (
+  actor TEXT NOT NULL,
+  key TEXT NOT NULL,
+  operation TEXT NOT NULL,
+  fingerprint TEXT,
+  result TEXT NOT NULL,
+  at TEXT NOT NULL,
+  PRIMARY KEY (actor, key)
+) STRICT;
+
+-- The journal. actor_ref is JSON {project, session}, set exactly when actor is 'agent'.
+CREATE TABLE event (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  at TEXT NOT NULL,
+  project TEXT NOT NULL,
+  task_id INTEGER REFERENCES task (id),
+  kind TEXT NOT NULL,
+  actor TEXT NOT NULL,
+  actor_ref TEXT,
+  payload TEXT NOT NULL,
+  v INTEGER NOT NULL,
+  request_id TEXT
+) STRICT;
+
+CREATE INDEX event_task_id ON event (task_id, id);
+CREATE INDEX event_at ON event (at);
+
+CREATE TABLE outbox (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  kind TEXT NOT NULL,
+  dedupe_key TEXT NOT NULL UNIQUE,
+  payload TEXT NOT NULL,
+  state TEXT NOT NULL,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  next_at TEXT NOT NULL,
+  last_error TEXT,
+  external_ref TEXT,
+  uncertain INTEGER NOT NULL DEFAULT 0 CHECK (uncertain IN (0, 1))
+) STRICT;
+
+CREATE INDEX outbox_state_next_at ON outbox (state, next_at);
+
+CREATE TABLE dismissal (
+  item_key TEXT PRIMARY KEY,
+  fingerprint TEXT NOT NULL,
+  dismissed_by TEXT NOT NULL,
+  dismissed_at TEXT NOT NULL
+) STRICT;
+
+-- Digest and archive slots. The schema version lives in PRAGMA user_version, not here.
+CREATE TABLE meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE source_state (
+  source TEXT PRIMARY KEY,
+  initialized INTEGER NOT NULL DEFAULT 0 CHECK (initialized IN (0, 1)),
+  last_complete_at TEXT,
+  blind_reason TEXT,
+  cursor TEXT
+) STRICT;

package/dist/migrations/0002_delivery.sql

@@ -0,0 +1,49 @@
+-- Schema v2: outbox delivery. Forward only: never edit this file once committed; add the
+-- next numbered file instead. Timestamps are ISO-8601 UTC text, JSON columns hold text
+-- checked by zod on read and write, flags are 0 or 1.
+
+-- A conversation on a gateway: the thread of a block (purpose 'block') or of a feed line
+-- (purpose 'feed_line'). A block may have several.
+CREATE TABLE conversation (
+  ref TEXT NOT NULL,
+  gateway TEXT NOT NULL,
+  space TEXT NOT NULL,
+  task_id INTEGER REFERENCES task (id),
+  block_id INTEGER REFERENCES block (id),
+  purpose TEXT NOT NULL,
+  state TEXT NOT NULL,
+  root_message_ref TEXT NOT NULL,
+  after_message_ref TEXT,
+  created_at TEXT NOT NULL,
+  closed_at TEXT,
+  PRIMARY KEY (gateway, ref)
+) STRICT;
+
+-- One row per (gateway, space) whose transport is failing; its rows wait while it stands.
+-- probe_at is when the last probe's send started: one probe per minute, kept across restarts.
+CREATE TABLE transport_health (
+  gateway TEXT NOT NULL,
+  space TEXT NOT NULL,
+  reason TEXT NOT NULL,
+  since TEXT NOT NULL,
+  probe_at TEXT NOT NULL,
+  PRIMARY KEY (gateway, space)
+) STRICT;
+
+-- When the last send into a (gateway, space) started: the next one waits the space interval,
+-- kept across restarts.
+CREATE TABLE space_slot (
+  gateway TEXT NOT NULL,
+  space TEXT NOT NULL,
+  sent_at TEXT NOT NULL,
+  PRIMARY KEY (gateway, space)
+) STRICT;
+
+-- A dependent row (reply, close, edit) is sent only after its parent is done.
+ALTER TABLE outbox ADD COLUMN parent_outbox_id INTEGER REFERENCES outbox (id);
+-- The first attempt of the current retry window; NULL while the window is suspended.
+ALTER TABLE outbox ADD COLUMN first_attempt_at TEXT;
+-- NULL for a comment that is not delivered to a gateway.
+ALTER TABLE comment ADD COLUMN delivery_state TEXT;
+
+CREATE INDEX outbox_parent_outbox_id ON outbox (parent_outbox_id);

package/dist/migrations/0003_delivery_search.sql

@@ -0,0 +1,3 @@
+-- Keep the earliest possible send time across retry-window and transport-health resets.
+-- Existing uncertain rows remain NULL and must search without a lower bound.
+ALTER TABLE outbox ADD COLUMN first_delivery_at TEXT;

package/dist/migrations/0004_attempt_started.sql

@@ -0,0 +1,3 @@
+-- Claim and send start are separate transactions. Legacy in-flight rows may have been sent.
+ALTER TABLE outbox ADD COLUMN attempt_started INTEGER NOT NULL DEFAULT 0 CHECK (attempt_started IN (0, 1));
+UPDATE outbox SET attempt_started = 1 WHERE state = 'in_flight';

package/dist/migrations/0005_doorbells_items.sql

@@ -0,0 +1,39 @@
+-- Notification state tracks distinct delivered rings separately from outbox transport attempts.
+CREATE TABLE notification (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  source_key TEXT NOT NULL UNIQUE,
+  kind TEXT NOT NULL,
+  task_id INTEGER NOT NULL REFERENCES task (id),
+  block_id INTEGER NOT NULL REFERENCES block (id),
+  comment_id INTEGER REFERENCES comment (id),
+  revision INTEGER,
+  role TEXT NOT NULL,
+  author_session TEXT,
+  recipient_session TEXT,
+  rings INTEGER NOT NULL DEFAULT 0,
+  next_at TEXT NOT NULL,
+  last_outbox_id INTEGER REFERENCES outbox (id),
+  acked_at TEXT,
+  created_at TEXT NOT NULL
+) STRICT;
+
+CREATE INDEX notification_due ON notification (acked_at, next_at);
+CREATE INDEX notification_block ON notification (block_id, id);
+
+-- A new raise of the same item key gets a new raise number and a new feed dedupe key.
+CREATE TABLE operator_item (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  item_key TEXT NOT NULL,
+  raise_no INTEGER NOT NULL,
+  kind TEXT NOT NULL,
+  text TEXT NOT NULL,
+  url TEXT NOT NULL,
+  task_id INTEGER REFERENCES task (id),
+  block_id INTEGER REFERENCES block (id),
+  raised_at TEXT NOT NULL,
+  cleared_at TEXT,
+  line_outbox_id INTEGER REFERENCES outbox (id),
+  UNIQUE (item_key, raise_no)
+) STRICT;
+
+CREATE INDEX operator_item_active ON operator_item (item_key, cleared_at);

package/dist/migrations/0006_notification_exhausted.sql

@@ -0,0 +1 @@
+ALTER TABLE notification ADD COLUMN exhausted_at TEXT;

package/dist/migrations/0007_inbound_item_event.sql

@@ -0,0 +1 @@
+ALTER TABLE operator_item ADD COLUMN inbound_event_json TEXT;

package/dist/migrations/0008_observation.sql

@@ -0,0 +1,49 @@
+-- Observation and operator membership state. Existing task ids and child rows survive.
+CREATE TABLE task_new (
+  id INTEGER PRIMARY KEY,
+  project TEXT NOT NULL,
+  tracker_kind TEXT NOT NULL,
+  tracker_id TEXT,
+  key TEXT NOT NULL,
+  membership TEXT NOT NULL,
+  archive_reason TEXT,
+  "column" TEXT NOT NULL,
+  shadow_column TEXT,
+  column_epoch INTEGER NOT NULL DEFAULT 0,
+  left_moves INTEGER NOT NULL DEFAULT 0,
+  merged_past_gate INTEGER NOT NULL DEFAULT 0 CHECK (merged_past_gate IN (0, 1)),
+  created_at TEXT NOT NULL,
+  manual_include INTEGER NOT NULL DEFAULT 0 CHECK (manual_include IN (0, 1)),
+  manual_exclude INTEGER NOT NULL DEFAULT 0 CHECK (manual_exclude IN (0, 1)),
+  last_change_at TEXT,
+  terminal_at TEXT,
+  archive_slot_at TEXT,
+  UNIQUE (project, tracker_kind, key)
+) STRICT;
+INSERT INTO task_new (id, project, tracker_kind, tracker_id, key, membership, archive_reason,
+  "column", shadow_column, column_epoch, left_moves, merged_past_gate, created_at)
+SELECT id, project, tracker_kind, tracker_id, key, membership, archive_reason,
+  "column", shadow_column, column_epoch, left_moves, merged_past_gate, created_at FROM task;
+DROP TABLE task;
+ALTER TABLE task_new RENAME TO task;
+CREATE UNIQUE INDEX task_stable_tracker_id ON task (project, tracker_kind, tracker_id)
+  WHERE tracker_id IS NOT NULL;
+
+ALTER TABLE source_state ADD COLUMN observed_at TEXT;
+ALTER TABLE source_state ADD COLUMN blind_message TEXT;
+ALTER TABLE source_state ADD COLUMN gone TEXT NOT NULL DEFAULT '[]';
+
+CREATE TABLE source_miss (
+  source TEXT NOT NULL REFERENCES source_state (source),
+  ref_key TEXT NOT NULL,
+  ref TEXT NOT NULL,
+  misses INTEGER NOT NULL CHECK (misses >= 0),
+  gone INTEGER NOT NULL CHECK (gone IN (0, 1)),
+  outcome TEXT,
+  PRIMARY KEY (source, ref_key)
+) STRICT;
+
+ALTER TABLE operator_item ADD COLUMN fingerprint TEXT;
+ALTER TABLE operator_item ADD COLUMN fact_at TEXT;
+ALTER TABLE operator_item ADD COLUMN source TEXT;
+ALTER TABLE operator_item ADD COLUMN priority INTEGER;

package/dist/migrations/0009_operator_tokens.sql

@@ -0,0 +1,15 @@
+-- Named operator credentials store hashes only. Expiry is enforced at read and decision time.
+CREATE TABLE operator_token (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL UNIQUE,
+  hash TEXT NOT NULL UNIQUE,
+  folder TEXT NOT NULL,
+  host TEXT NOT NULL,
+  status TEXT NOT NULL,
+  requested_at TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  decided_at TEXT,
+  item_id INTEGER NOT NULL REFERENCES operator_item (id)
+) STRICT;
+
+CREATE INDEX operator_token_status_expiry ON operator_token (status, expires_at);