@ai-setting/roy-task-plugin 0.4.2 → 0.5.0

package/dist/claude-plugin/mcp/bridge.mjs

@@ -0,0 +1,482 @@
+/**
+ * Bridge: MCP tool call -> direct SQLite access on roy-agent's task store.
+ *
+ * ## Why direct SQLite and not the `roy-agent tasks` CLI
+ *
+ * The CLI was the first idea and it works for most tools — but it **cannot
+ * create operation records**: `roy-agent tasks operations <id>` only *reads*
+ * them (measured: the subcommand's flags are `--type / --limit / --offset /
+ * --json`, there is no `--create`). Since `task_operation_create` is a
+ * first-class part of the task lifecycle (milestones are the state
+ * dimension of a task), the MCP server cannot go through the CLI alone.
+ *
+ * So the server talks to the store directly, and this is safe because:
+ *
+ * 1. **Same database.** `~/.local/share/roy-agent/tasks.db` is the file the
+ *    roy agent writes and the progress card renders. Writing anywhere else
+ *    would make Claude's tasks invisible to the card.
+ * 2. **`node:sqlite`, not a native addon.** Node 22+ ships SQLite in core.
+ *    No `better-sqlite3` compile step, no `bun:sqlite` — the same file works
+ *    under plain node, which is the whole point of the published package.
+ *    (Measured: `better-sqlite3@11.10.0`'s native module aborts the process
+ *    under node 24 with `Assertion failed: (env) != nullptr`.)
+ * 3. **Schema is stable and read-only by default.** We open the database in
+ *    read-write mode, but every statement is explicit and parameterised.
+ *
+ * ## Migration safety
+ *
+ * We do **not** run migrations. The `task` / `task_operation` tables are
+ * created and migrated by roy-agent itself. If a column this server needs is
+ * missing, we surface that as a tool error rather than guessing a default.
+ */
+
+import { DatabaseSync } from "node:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+/** Raised when a tool call cannot be served. */
+export class BridgeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BridgeError";
+  }
+}
+
+/** Where roy-agent keeps its task store (mirrors `getDefaultTaskDbPath`). */
+export function defaultTaskDbPath() {
+  const xdg = process.env.XDG_DATA_HOME;
+  const base = xdg && xdg.length > 0 ? xdg : join(homedir(), ".local", "share");
+  return join(base, "roy-agent", "tasks.db");
+}
+
+/** The columns `task` exposes, in the order the CLI's JSON output uses. */
+function rowToTask(row) {
+  return {
+    id: row.id,
+    title: row.title,
+    description: row.description ?? "",
+    status: row.status,
+    priority: row.priority,
+    progress: row.progress ?? 0,
+    current_status: row.current_status ?? "",
+    goals_and_expected_deliverables: row.goals_and_expected_deliverables ?? "",
+    parent_task_id: row.parent_task_id ?? null,
+    createdAt: toIso(row.created_at),
+    updatedAt: toIso(row.updated_at),
+    due_date: row.due_date ?? null,
+    tags: parseTags(row.tags),
+    project_path: row.project_path ?? "",
+    context: row.context ?? "",
+    type: row.type ?? "normal",
+  };
+}
+
+function rowToOperation(row) {
+  return {
+    id: row.id,
+    task_id: row.task_id,
+    session_id: row.session_id ?? null,
+    milestone_type: row.milestone_type,
+    milestone_title: row.milestone_title,
+    milestone_description: row.milestone_description ?? "",
+    timestamp: toIso(row.timestamp),
+    md_path: row.md_path ?? null,
+    process_description: row.process_description ?? "",
+  };
+}
+
+function toIso(value) {
+  if (value === null || value === undefined) return new Date().toISOString();
+  if (typeof value === "number") return new Date(value).toISOString();
+  const asNumber = Number(value);
+  if (Number.isFinite(asNumber) && String(value).trim() !== "") {
+    return new Date(asNumber).toISOString();
+  }
+  return String(value);
+}
+
+function parseTags(value) {
+  if (!value) return [];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed.map(String) : [];
+  } catch {
+    return String(value)
+      .split(",")
+      .map((t) => t.trim())
+      .filter(Boolean);
+  }
+}
+
+function requireString(args, key) {
+  const value = args[key];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new BridgeError(`missing required string argument "${key}"`);
+  }
+  return value;
+}
+
+function optionalString(args, key) {
+  const value = args[key];
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string") {
+    throw new BridgeError(`argument "${key}" must be a string`);
+  }
+  return value;
+}
+
+function optionalNumber(args, key) {
+  const value = args[key];
+  if (value === undefined || value === null) return undefined;
+  const num = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(num)) {
+    throw new BridgeError(`argument "${key}" must be a number`);
+  }
+  return num;
+}
+
+function optionalStringArray(args, key) {
+  const value = args[key];
+  if (value === undefined || value === null) return undefined;
+  if (!Array.isArray(value)) {
+    throw new BridgeError(`argument "${key}" must be an array of strings`);
+  }
+  return value.map((v) => String(v));
+}
+
+/**
+ * The subset of roy-agent's schema this server needs.
+ *
+ * We do not run roy-agent's migrations — that would duplicate a versioned
+ * migration chain we do not own. Instead we create the tables only when they
+ * are **entirely absent**, using the same column set the current roy-agent
+ * schema has. If the tables exist we touch nothing, so an existing store is
+ * never rewritten by this server.
+ *
+ * The `id INTEGER PRIMARY KEY AUTOINCREMENT` form matters: `task.id` is the
+ * handle every other API (the CLI, the progress card, the roy agent's own
+ * tools) uses, and it must keep incrementing across server restarts.
+ */
+const FALLBACK_SCHEMA = `
+CREATE TABLE IF NOT EXISTS task (
+  id                           INTEGER PRIMARY KEY AUTOINCREMENT,
+  title                        TEXT NOT NULL,
+  description                  TEXT,
+  status                       TEXT NOT NULL DEFAULT 'todo',
+  priority                     TEXT NOT NULL DEFAULT 'medium',
+  progress                     INTEGER NOT NULL DEFAULT 0,
+  current_status               TEXT,
+  goals_and_expected_deliverables TEXT,
+  parent_task_id               INTEGER,
+  created_at                   INTEGER,
+  updated_at                   INTEGER,
+  due_date                     TEXT,
+  tags                         TEXT,
+  project_path                 TEXT,
+  context                      TEXT,
+  type                         TEXT NOT NULL DEFAULT 'normal'
+);
+CREATE TABLE IF NOT EXISTS task_operation (
+  id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+  task_id             INTEGER,
+  session_id          TEXT,
+  milestone_type      TEXT,
+  milestone_title     TEXT,
+  milestone_description TEXT,
+  timestamp           INTEGER,
+  md_path             TEXT,
+  process_description TEXT
+);
+CREATE INDEX IF NOT EXISTS task_operation_task_idx ON task_operation(task_id);
+`;
+
+/** Open (and create if needed) the task store. */
+export function openStore(dbPath = defaultTaskDbPath()) {
+  if (dbPath !== ":memory:") {
+    try {
+      mkdirSync(dirname(dbPath), { recursive: true });
+    } catch {
+      // best effort — the open below will produce the real error
+    }
+  }
+  const db = new DatabaseSync(dbPath);
+  try {
+    db.exec(FALLBACK_SCHEMA);
+  } catch (err) {
+    // An existing store whose schema differs is roy-agent's business, not
+    // ours. Surface the problem instead of silently corrupting it.
+    process.stderr.write(
+      `roy-task mcp server: schema check failed on ${dbPath}: ${err && err.message}\n`,
+    );
+  }
+  return db;
+}
+
+/**
+ * Serve one tool call.
+ *
+ * Returns a JSON-serialisable value. Throws `BridgeError` for bad input and
+ * plain `Error` for store problems; the caller turns both into MCP errors.
+ */
+export function callTool(db, name, args = {}) {
+  switch (name) {
+    case "task_tree":
+      return taskTree(db, args);
+    case "task_create":
+      return taskCreate(db, args);
+    case "task_get":
+      return taskGet(db, args);
+    case "task_list":
+      return taskList(db, args);
+    case "task_update":
+      return taskUpdate(db, args);
+    case "task_operation_create":
+      return taskOperationCreate(db, args);
+    case "task_complete":
+      return taskComplete(db, args);
+    case "task_search":
+      return taskSearch(db, args);
+    default:
+      throw new BridgeError(`unknown tool "${name}"`);
+  }
+}
+
+function taskTree(db, args) {
+  const depth = optionalNumber(args, "depth");
+  const rootId = optionalNumber(args, "parent_task_id");
+  const rows = db.prepare("SELECT * FROM task ORDER BY id ASC").all();
+  const tasks = rows.map(rowToTask);
+  const byId = new Map(tasks.map((t) => [t.id, { ...t, children: [] }]));
+  const roots = [];
+  for (const node of byId.values()) {
+    const parent = node.parent_task_id ? byId.get(node.parent_task_id) : undefined;
+    if (parent) parent.children.push(node);
+    else roots.push(node);
+  }
+  const scope = rootId !== undefined ? byId.get(rootId) : undefined;
+  const selected = scope ? [scope] : roots;
+  const limited =
+    depth === undefined || depth < 0 ? selected : pruneDepth(selected, depth);
+  return { total: tasks.length, roots: limited.length, tasks: limited };
+}
+
+function pruneDepth(nodes, depth) {
+  if (depth <= 0) return nodes.map((n) => ({ ...n, children: [] }));
+  return nodes.map((n) => ({ ...n, children: pruneDepth(n.children, depth - 1) }));
+}
+
+function taskCreate(db, args) {
+  const title = requireString(args, "title");
+  const now = Date.now();
+  const description = optionalString(args, "description") ?? "";
+  const goals = optionalString(args, "goals_and_expected_deliverables") ?? "";
+  const priority = optionalString(args, "priority") ?? "medium";
+  const type = optionalString(args, "type") ?? "normal";
+  const parentId = optionalNumber(args, "parent_task_id") ?? null;
+  const projectPath = optionalString(args, "project_path") ?? "";
+  const context = optionalString(args, "context") ?? "";
+  const tags = optionalStringArray(args, "tags") ?? [];
+
+  const info = db
+    .prepare(
+      `INSERT INTO task
+        (title, description, status, priority, progress, current_status,
+         goals_and_expected_deliverables, parent_task_id, created_at, updated_at,
+         tags, project_path, context, type)
+       VALUES (?, ?, 'todo', ?, 0, '', ?, ?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      title,
+      description,
+      priority,
+      goals,
+      parentId,
+      now,
+      now,
+      JSON.stringify(tags),
+      projectPath,
+      context,
+      type,
+    );
+  const id = Number(info.lastInsertRowid);
+  const created = db.prepare("SELECT * FROM task WHERE id = ?").get(id);
+  return rowToTask(created);
+}
+
+function taskGet(db, args) {
+  const id = optionalNumber(args, "id");
+  if (id === undefined) throw new BridgeError('missing required number argument "id"');
+  const row = db.prepare("SELECT * FROM task WHERE id = ?").get(id);
+  if (!row) throw new BridgeError(`task ${id} not found`);
+  const task = rowToTask(row);
+  const ops = db
+    .prepare("SELECT * FROM task_operation WHERE task_id = ? ORDER BY id ASC")
+    .all(id)
+    .map(rowToOperation);
+  return { ...task, operations: ops };
+}
+
+function taskList(db, args) {
+  const clauses = [];
+  const params = [];
+  const status = optionalString(args, "status");
+  if (status) {
+    clauses.push("status = ?");
+    params.push(status);
+  }
+  const priority = optionalString(args, "priority");
+  if (priority) {
+    clauses.push("priority = ?");
+    params.push(priority);
+  }
+  const type = optionalString(args, "type");
+  if (type) {
+    clauses.push("type = ?");
+    params.push(type);
+  }
+  const where = clauses.length > 0 ? ` WHERE ${clauses.join(" AND ")}` : "";
+  const total = db.prepare(`SELECT COUNT(*) AS c FROM task${where}`).get(...params).c;
+  const limit = optionalNumber(args, "limit") ?? 20;
+  const offset = optionalNumber(args, "offset") ?? 0;
+  const rows = db
+    .prepare(`SELECT * FROM task${where} ORDER BY id DESC LIMIT ? OFFSET ?`)
+    .all(...params, limit, offset);
+  return {
+    total,
+    count: rows.length,
+    truncated: total > rows.length,
+    limit,
+    offset,
+    tasks: rows.map(rowToTask),
+  };
+}
+
+function taskUpdate(db, args) {
+  const id = optionalNumber(args, "id");
+  if (id === undefined) throw new BridgeError('missing required number argument "id"');
+  const existing = db.prepare("SELECT * FROM task WHERE id = ?").get(id);
+  if (!existing) throw new BridgeError(`task ${id} not found`);
+
+  const sets = [];
+  const params = [];
+  const push = (col, value) => {
+    sets.push(`${col} = ?`);
+    params.push(value);
+  };
+
+  const status = optionalString(args, "status");
+  if (status !== undefined) push("status", status);
+  const progress = optionalNumber(args, "progress");
+  if (progress !== undefined) push("progress", progress);
+  const currentStatus = optionalString(args, "current_status");
+  if (currentStatus !== undefined) push("current_status", currentStatus);
+  const description = optionalString(args, "description");
+  if (description !== undefined) push("description", description);
+  const goals = optionalString(args, "goals_and_expected_deliverables");
+  if (goals !== undefined) push("goals_and_expected_deliverables", goals);
+  const priority = optionalString(args, "priority");
+  if (priority !== undefined) push("priority", priority);
+  const type = optionalString(args, "type");
+  if (type !== undefined) push("type", type);
+  push("updated_at", Date.now());
+
+  params.push(id);
+  db.prepare(`UPDATE task SET ${sets.join(", ")} WHERE id = ?`).run(...params);
+  return rowToTask(db.prepare("SELECT * FROM task WHERE id = ?").get(id));
+}
+
+function taskOperationCreate(db, args) {
+  const taskId = optionalNumber(args, "task_id");
+  if (taskId === undefined) {
+    throw new BridgeError('missing required number argument "task_id"');
+  }
+  const exists = db.prepare("SELECT id FROM task WHERE id = ?").get(taskId);
+  if (!exists) throw new BridgeError(`task ${taskId} not found`);
+
+  const milestoneType = requireString(args, "milestone_type");
+  const milestoneTitle = requireString(args, "milestone_title");
+  const milestoneDescription = optionalString(args, "milestone_description") ?? "";
+  const processDescription = optionalString(args, "process_description") ?? null;
+  const sessionId = optionalString(args, "session_id") ?? null;
+
+  // The 100-150 char rule is roy-agent's, not ours — but the CLI validates it
+  // on the way in, so the MCP tool has to as well or the two paths diverge.
+  if (processDescription !== null) {
+    const len = processDescription.length;
+    if (len > 0 && (len < 100 || len > 150)) {
+      throw new BridgeError(
+        `process_description must be 100-150 characters (got ${len})`,
+      );
+    }
+  }
+
+  const info = db
+    .prepare(
+      `INSERT INTO task_operation
+        (task_id, session_id, milestone_type, milestone_title,
+         milestone_description, timestamp, md_path, process_description)
+       VALUES (?, ?, ?, ?, ?, ?, NULL, ?)`,
+    )
+    .run(
+      taskId,
+      sessionId,
+      milestoneType,
+      milestoneTitle,
+      milestoneDescription,
+      Date.now(),
+      processDescription,
+    );
+  const row = db
+    .prepare("SELECT * FROM task_operation WHERE id = ?")
+    .get(Number(info.lastInsertRowid));
+  return rowToOperation(row);
+}
+
+function taskComplete(db, args) {
+  const id = optionalNumber(args, "id");
+  if (id === undefined) throw new BridgeError('missing required number argument "id"');
+  const existing = db.prepare("SELECT * FROM task WHERE id = ?").get(id);
+  if (!existing) throw new BridgeError(`task ${id} not found`);
+
+  const deliverable = optionalString(args, "deliverable_storage_path");
+  const now = Date.now();
+  const sets = ["status = ?", "progress = 100", "updated_at = ?"];
+  const params = ["completed", now];
+  if (deliverable) {
+    // Same convention roy-agent uses: the deliverable lives in the task's
+    // context JSON under `deliverable_storage_path`.
+    let context = {};
+    try {
+      context = existing.context ? JSON.parse(existing.context) : {};
+    } catch {
+      context = {};
+    }
+    context.deliverable_storage_path = deliverable;
+    sets.push("context = ?");
+    params.push(JSON.stringify(context));
+  }
+  params.push(id);
+  db.prepare(`UPDATE task SET ${sets.join(", ")} WHERE id = ?`).run(...params);
+  return rowToTask(db.prepare("SELECT * FROM task WHERE id = ?").get(id));
+}
+
+function taskSearch(db, args) {
+  const keywords = optionalStringArray(args, "keywords");
+  if (!keywords || keywords.length === 0) {
+    throw new BridgeError('missing required array argument "keywords"');
+  }
+  const limit = optionalNumber(args, "limit") ?? 20;
+  const where = keywords
+    .map(() => "(title LIKE ? OR description LIKE ? OR goals_and_expected_deliverables LIKE ? OR tags LIKE ?)")
+    .join(" AND ");
+  const params = [];
+  for (const kw of keywords) {
+    const like = `%${kw}%`;
+    params.push(like, like, like, like);
+  }
+  const rows = db
+    .prepare(`SELECT * FROM task WHERE ${where} ORDER BY id DESC LIMIT ?`)
+    .all(...params, limit);
+  return { total: rows.length, count: rows.length, tasks: rows.map(rowToTask) };
+}