ultra-builder-pro-cli 0.5.0

package/mcp-server/lib/topo.test.cjs

@@ -0,0 +1,158 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { computeWaves } = require('./topo.cjs');
+
+function makeTask(id, deps = []) {
+  return { id, deps };
+}
+
+function idsSet(ids) {
+  return new Set(ids);
+}
+
+function asWaveSets(waves) {
+  return waves.map(idsSet);
+}
+
+test('topo: empty array → empty waves and cycles', () => {
+  const r = computeWaves([]);
+  assert.deepEqual(r.waves, []);
+  assert.deepEqual(r.cycles, []);
+});
+
+test('topo: single task with no deps → single wave', () => {
+  const r = computeWaves([makeTask('A')]);
+  assert.deepEqual(r.waves, [['A']]);
+  assert.deepEqual(r.cycles, []);
+});
+
+test('topo fixture 1: linear chain A, B(A), C(B) → three serial waves', () => {
+  const r = computeWaves([
+    makeTask('A'),
+    makeTask('B', ['A']),
+    makeTask('C', ['B']),
+  ]);
+  assert.deepEqual(asWaveSets(r.waves), [idsSet(['A']), idsSet(['B']), idsSet(['C'])]);
+  assert.deepEqual(r.cycles, []);
+});
+
+test('topo fixture 2: fan-out A→{B,C} + independent D→E → 2 waves', () => {
+  const r = computeWaves([
+    makeTask('A'),
+    makeTask('B', ['A']),
+    makeTask('C', ['A']),
+    makeTask('D'),
+    makeTask('E', ['D']),
+  ]);
+  assert.equal(r.waves.length, 2);
+  assert.deepEqual(asWaveSets(r.waves), [
+    idsSet(['A', 'D']),
+    idsSet(['B', 'C', 'E']),
+  ]);
+  assert.deepEqual(r.cycles, []);
+});
+
+test('topo fixture 3: double diamond merges waves correctly', () => {
+  const r = computeWaves([
+    makeTask('A'),
+    makeTask('B', ['A']),
+    makeTask('C', ['A']),
+    makeTask('D', ['B', 'C']),
+    makeTask('E'),
+    makeTask('F', ['E']),
+    makeTask('G', ['E']),
+    makeTask('H', ['F', 'G']),
+  ]);
+  assert.deepEqual(asWaveSets(r.waves), [
+    idsSet(['A', 'E']),
+    idsSet(['B', 'C', 'F', 'G']),
+    idsSet(['D', 'H']),
+  ]);
+  assert.deepEqual(r.cycles, []);
+});
+
+test('topo fixture 4: 2-node cycle A↔B → cycle reported, no waves', () => {
+  const r = computeWaves([
+    makeTask('A', ['B']),
+    makeTask('B', ['A']),
+  ]);
+  assert.deepEqual(r.waves, []);
+  assert.equal(r.cycles.length, 1);
+  assert.deepEqual(idsSet(r.cycles[0]), idsSet(['A', 'B']));
+});
+
+test('topo fixture 5: two independent cycles A↔B and C↔D → both reported', () => {
+  const r = computeWaves([
+    makeTask('A', ['B']),
+    makeTask('B', ['A']),
+    makeTask('C', ['D']),
+    makeTask('D', ['C']),
+  ]);
+  assert.deepEqual(r.waves, []);
+  assert.equal(r.cycles.length, 2);
+  const cycleSets = r.cycles.map((c) => idsSet(c));
+  const expected = [idsSet(['A', 'B']), idsSet(['C', 'D'])];
+  for (const exp of expected) {
+    const found = cycleSets.some(
+      (s) => s.size === exp.size && [...s].every((x) => exp.has(x)),
+    );
+    assert.ok(found, `cycle ${[...exp].join(',')} not reported`);
+  }
+});
+
+test('topo: self-loop counts as cycle', () => {
+  const r = computeWaves([makeTask('A', ['A'])]);
+  assert.deepEqual(r.waves, []);
+  assert.equal(r.cycles.length, 1);
+  assert.deepEqual(r.cycles[0], ['A']);
+});
+
+test('topo: cycle plus acyclic tail — tail is waved, cycle isolated', () => {
+  const r = computeWaves([
+    makeTask('A', ['B']),
+    makeTask('B', ['A']),
+    makeTask('X'),
+    makeTask('Y', ['X']),
+  ]);
+  assert.deepEqual(asWaveSets(r.waves), [idsSet(['X']), idsSet(['Y'])]);
+  assert.equal(r.cycles.length, 1);
+  assert.deepEqual(idsSet(r.cycles[0]), idsSet(['A', 'B']));
+});
+
+test('topo: external deps (ids not in task_ids) are treated as satisfied', () => {
+  const r = computeWaves([makeTask('A', ['X'])]);
+  assert.deepEqual(r.waves, [['A']]);
+  assert.deepEqual(r.cycles, []);
+});
+
+test('topo: input order does not change wave membership', () => {
+  const tasks = [
+    makeTask('A'),
+    makeTask('B', ['A']),
+    makeTask('C', ['A']),
+    makeTask('D', ['B', 'C']),
+  ];
+  const r1 = computeWaves(tasks);
+  const r2 = computeWaves([...tasks].reverse());
+  assert.deepEqual(asWaveSets(r1.waves), asWaveSets(r2.waves));
+  assert.deepEqual(r1.cycles, r2.cycles);
+});
+
+test('topo: rejects non-array input', () => {
+  assert.throws(() => computeWaves(null), TypeError);
+  assert.throws(() => computeWaves({}), TypeError);
+});
+
+test('topo: 3-node cycle A→B→C→A surfaced intact', () => {
+  const r = computeWaves([
+    makeTask('A', ['C']),
+    makeTask('B', ['A']),
+    makeTask('C', ['B']),
+  ]);
+  assert.deepEqual(r.waves, []);
+  assert.equal(r.cycles.length, 1);
+  assert.deepEqual(idsSet(r.cycles[0]), idsSet(['A', 'B', 'C']));
+});

package/mcp-server/server.cjs

@@ -0,0 +1,482 @@
+'use strict';
+
+// MCP server (stdio JSON-RPC) exposing task.* + session.* tools backed by
+// .ultra/state.db. Uses the low-level Server API from
+// @modelcontextprotocol/sdk so we can pass raw JSON Schema (Draft 2020-12)
+// straight from spec/mcp-tools.yaml without translating to zod.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const yaml = require('js-yaml');
+const Ajv = require('ajv/dist/2020');
+const addFormats = require('ajv-formats');
+
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { ListToolsRequestSchema, CallToolRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
+const { version: PACKAGE_VERSION } = require('../package.json');
+
+const { initStateDb, closeStateDb } = require('./lib/state-db.cjs');
+const ops = require('./lib/state-ops.cjs');
+const projector = require('./lib/projector.cjs');
+const telemetry = require('./lib/telemetry.cjs');
+const topo = require('./lib/topo.cjs');
+const llm = require('./lib/llm-client.cjs');
+const parser = require('./lib/prd-parser.cjs');
+const expander = require('./lib/task-expander.cjs');
+const planStore = require('./lib/plan-store.cjs');
+const { initProject } = require('./lib/init-project.cjs');
+
+const REPO_ROOT = process.env.UBP_RUNTIME_ROOT
+  ? path.resolve(process.env.UBP_RUNTIME_ROOT)
+  : path.resolve(__dirname, '..');
+const TOOLS_FILE = path.join(REPO_ROOT, 'spec', 'mcp-tools.yaml');
+
+const TASK_TOOLS = Object.freeze([
+  'task.create',
+  'task.update',
+  'task.list',
+  'task.get',
+  'task.delete',
+  'task.init_project',
+  'task.append_event',
+  'task.subscribe_events',
+  'task.switch_tag',
+  'task.dependency_topo',
+  'task.parse_prd',
+  'task.expand',
+]);
+
+const SESSION_TOOLS = Object.freeze([
+  'session.spawn',
+  'session.close',
+  'session.get',
+  'session.list',
+  'session.admission_check',
+  'session.heartbeat',
+  'session.subscribe_events',
+]);
+
+const PLAN_TOOLS = Object.freeze([
+  'plan.export',
+  'plan.get',
+]);
+
+const REGISTERED_TOOLS = Object.freeze([
+  ...TASK_TOOLS, ...SESSION_TOOLS, ...PLAN_TOOLS,
+]);
+
+const STATELESS_TOOLS = new Set(['task.init_project']);
+
+// init_project mutates the filesystem of an unrelated project, not state.db —
+// do NOT run the projector (it would overwrite the freshly-copied template).
+const MUTATING_TOOLS = new Set([
+  'task.create', 'task.update', 'task.delete', 'task.append_event', 'task.switch_tag',
+  'task.parse_prd', 'task.expand',
+  'session.spawn', 'session.close', 'session.heartbeat',
+]);
+
+function loadRegisteredTools() {
+  const manifest = yaml.load(fs.readFileSync(TOOLS_FILE, 'utf8'));
+  return manifest.tools.filter((t) => REGISTERED_TOOLS.includes(t.name));
+}
+
+function buildAjv() {
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  addFormats(ajv);
+  return ajv;
+}
+
+function mintSessionId() {
+  const { randomUUID } = require('node:crypto');
+  return `sess-${randomUUID().slice(0, 8)}`;
+}
+
+function resolvePrdText(input, ctx) {
+  if (input.prd_text && String(input.prd_text).trim()) return String(input.prd_text);
+  if (input.prd_path) {
+    const abs = path.isAbsolute(input.prd_path)
+      ? input.prd_path
+      : path.join(ctx.rootDir || process.cwd(), input.prd_path);
+    return fs.readFileSync(abs, 'utf8');
+  }
+  return null;
+}
+
+function buildLlmClient(ctx) {
+  if (ctx && ctx.llmClient) return ctx.llmClient;
+  return llm.createLlmClient({});
+}
+
+async function dispatchTool(name, input, db, ctx = {}) {
+  switch (name) {
+    case 'task.create': {
+      const { randomUUID } = require('node:crypto');
+      const id = input.id || `task-${randomUUID()}`;
+      const task = ops.createTask(db, { ...input, id });
+      return { id: task.id, status: task.status, created_at: task.created_at };
+    }
+    case 'task.update': {
+      const task = ops.patchTask(db, input.id, input.patch || {});
+      return { ok: true, task };
+    }
+    case 'task.list': {
+      const tasks = ops.listTasks(db, input || {});
+      return { tasks, count: tasks.length };
+    }
+    case 'task.get': {
+      const task = ops.readTask(db, input.id);
+      if (!task) {
+        const err = new Error(`task ${input.id} not found`);
+        err.code = 'TASK_NOT_FOUND';
+        throw err;
+      }
+      return { task };
+    }
+    case 'task.delete': {
+      return ops.deleteTask(db, input.id, { force: !!input.force });
+    }
+    case 'task.init_project': {
+      return initProject(input);
+    }
+    case 'task.append_event': {
+      const r = ops.appendEvent(db, {
+        type: input.type,
+        task_id: input.task_id,
+        session_id: input.session_id,
+        runtime: input.runtime,
+        payload: input.payload,
+      });
+      return { event_id: r.event_id, ts: r.ts };
+    }
+    case 'task.subscribe_events': {
+      return ops.subscribeEventsSince(db, input || {});
+    }
+    case 'session.spawn': {
+      // admission + takeover logic; actual git worktree + child process is
+      // delegated to orchestrator/session-runner (Phase 4.5.1). This tool
+      // records intent in state.db and returns the paths the runner should use.
+      const rootDir = ctx.rootDir || process.cwd();
+      const verdict = ops.admissionCheck(db, input.task_id);
+      if (!verdict.can_spawn && !input.takeover) {
+        const err = new Error(`active session exists for task ${input.task_id}; pass takeover=true or choose resume/abandon`);
+        err.code = 'ADMISSION_DENIED';
+        throw err;
+      }
+      if (!verdict.can_spawn && input.takeover && verdict.conflict) {
+        ops.updateSession(db, verdict.conflict.sid, { status: 'crashed' });
+      }
+      const sid = mintSessionId();
+      const worktreeBase = input.worktree_base || path.join(rootDir, '.ultra', 'worktrees');
+      const worktree_path = path.join(worktreeBase, sid);
+      const artifact_dir = path.join(rootDir, '.ultra', 'sessions', sid);
+      const session = ops.createSession(db, {
+        sid,
+        task_id: input.task_id,
+        runtime: input.runtime,
+        worktree_path,
+        artifact_dir,
+      });
+      return {
+        sid,
+        worktree_path,
+        artifact_dir,
+        lease_expires_at: session.lease_expires_at,
+      };
+    }
+    case 'session.close': {
+      ops.updateSession(db, input.sid, { status: input.status });
+      return { ok: true };
+    }
+    case 'session.get': {
+      const session = ops.readSession(db, input.sid);
+      if (!session) {
+        const err = new Error(`session ${input.sid} not found`);
+        err.code = 'SESSION_NOT_FOUND';
+        throw err;
+      }
+      return { session };
+    }
+    case 'session.admission_check': {
+      return ops.admissionCheck(db, input.task_id);
+    }
+    case 'session.list': {
+      const sessions = ops.listActiveSessions(db, { task_id: input.task_id });
+      const status = input.status || 'running';
+      const filtered = status === 'running'
+        ? sessions
+        : db.prepare(
+            "SELECT * FROM sessions WHERE status = ? AND (? IS NULL OR task_id = ?) ORDER BY started_at ASC LIMIT ?",
+          ).all(status, input.task_id || null, input.task_id || null, Math.min(input.limit || 100, 500));
+      const limit = Math.min(input.limit || 100, 500);
+      const trimmed = filtered.slice(0, limit);
+      return { sessions: trimmed, count: trimmed.length };
+    }
+    case 'session.heartbeat': {
+      return ops.heartbeatSession(db, input.sid);
+    }
+    case 'session.subscribe_events': {
+      return ops.subscribeEventsSince(db, {
+        since_id: input.since_id,
+        session_id: input.sid,
+        limit: input.limit,
+      });
+    }
+    case 'task.switch_tag': {
+      return ops.switchTaskTag(db, input.id, input.tag);
+    }
+    case 'task.dependency_topo': {
+      const requested = Array.isArray(input && input.task_ids) ? input.task_ids : null;
+      const rows = requested
+        ? requested.map((id) => ops.readTask(db, id)).filter(Boolean)
+        : ops.listTasks(db, {});
+      const graph = rows.map((t) => ({
+        id: t.id,
+        deps: Array.isArray(t.deps) ? t.deps : [],
+      }));
+      const result = topo.computeWaves(graph);
+      if (result.cycles.length > 0) {
+        const err = new Error(`dependency graph has ${result.cycles.length} cycle(s)`);
+        err.code = 'CYCLE_DETECTED';
+        err.details = { cycles: result.cycles };
+        throw err;
+      }
+      return { waves: result.waves };
+    }
+    case 'task.parse_prd': {
+      const prdText = resolvePrdText(input, ctx);
+      if (!prdText || !prdText.trim()) {
+        const err = new Error('one of prd_path or prd_text required');
+        err.code = 'NO_INPUT';
+        throw err;
+      }
+      const client = buildLlmClient(ctx);
+      const parsed = await parser.parsePrd(prdText, { llmClient: client, tag: input.tag });
+      const shaped = parsed.tasks.map((t) => ({
+        id: t.id, title: t.title, type: t.type, priority: t.priority,
+        complexity: t.complexity, deps: t.deps, files_modified: t.files_modified,
+        tag: t.tag,
+      }));
+      const dryRun = input.dry_run === true;
+      if (!dryRun) {
+        try {
+          ops.tx(db, () => {
+            for (const t of shaped) ops.createTask(db, t);
+          });
+        } catch (err) {
+          const wrap = new Error(`failed to persist parsed tasks: ${err.message}`);
+          wrap.code = 'PARSE_FAILED';
+          wrap.cause = err;
+          throw wrap;
+        }
+      }
+      const graph = shaped.map((t) => ({ id: t.id, deps: t.deps || [] }));
+      const topoResult = topo.computeWaves(graph);
+      return { tasks: shaped, topo: topoResult.waves };
+    }
+    case 'task.expand': {
+      // Cheap guards before paying for LLM client construction (which would
+      // throw NO_LLM_CREDENTIALS when env keys are missing).
+      const parent = ops.readTask(db, input.id);
+      if (!parent) {
+        const err = new Error(`no task ${input.id}`);
+        err.code = 'TASK_NOT_FOUND';
+        throw err;
+      }
+      if (parent.status === 'expanded') {
+        const err = new Error(`task ${input.id} is already expanded`);
+        err.code = 'ALREADY_EXPANDED';
+        throw err;
+      }
+      const client = buildLlmClient(ctx);
+      const result = await expander.expandTask(db, {
+        id: input.id,
+        sub_count: input.sub_count,
+        strategy: input.strategy,
+        llmClient: client,
+      });
+      return { parent_id: result.parent_id, children: result.children };
+    }
+    case 'plan.export': {
+      const rootDir = ctx.rootDir || process.cwd();
+      const abs = path.isAbsolute(input.out_path)
+        ? input.out_path
+        : path.join(rootDir, input.out_path);
+      const tasks = ops.listTasks(db, { tag: input.tag });
+      if (tasks.length === 0) {
+        const err = new Error('no tasks to plan');
+        err.code = 'NO_TASKS';
+        throw err;
+      }
+      const plan = planStore.buildPlan(tasks, {});
+      const { plan_path } = planStore.savePlanArtifact(plan, abs, input.format || 'json');
+      ops.appendEvent(db, {
+        type: 'plan_approved',
+        payload: { plan_path, wave_count: plan.waves.length, tag: input.tag || null },
+      });
+      return { plan_path, wave_count: plan.waves.length };
+    }
+    case 'plan.get': {
+      const rootDir = ctx.rootDir || process.cwd();
+      const loaded = planStore.loadPlanArtifact(rootDir);
+      if (!loaded) {
+        const err = new Error('no plan has been computed yet');
+        err.code = 'NO_PLAN';
+        throw err;
+      }
+      return { plan: planStore.selectSection(loaded, input.section) };
+    }
+    default:
+      throw new Error(`unhandled tool ${name}`);
+  }
+}
+
+function errorResponse(code, message, retriable = false, details = undefined) {
+  const error = { code, message, retriable };
+  if (details !== undefined) error.details = details;
+  return {
+    isError: true,
+    content: [{
+      type: 'text',
+      text: JSON.stringify({ ok: false, error }),
+    }],
+  };
+}
+
+function startServer({ dbPath, rootDir, projectOnWrite = true }) {
+  let db = null;
+  const getDb = () => {
+    if (!db) db = initStateDb(dbPath).db;
+    return db;
+  };
+
+  const tools = loadRegisteredTools();
+  const ajv = buildAjv();
+  const inputValidators = new Map();
+  const outputValidators = new Map();
+  for (const t of tools) {
+    inputValidators.set(t.name, ajv.compile(t.input_schema));
+    outputValidators.set(t.name, ajv.compile(t.output_schema));
+  }
+
+  const server = new Server(
+    { name: 'ultra-builder-pro-mcp', version: PACKAGE_VERSION },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.input_schema,
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    const toolStart = Date.now();
+    let toolError = null;
+
+    const emitTelemetry = () => {
+      if (!db) return;
+      try {
+        telemetry.appendTelemetry(db, {
+          event_type: 'tool_call',
+          tool_name: name,
+          session_id: (args && args.sid) || null,
+          rootDir,
+          payload: {
+            duration_ms: Date.now() - toolStart,
+            task_id: (args && (args.task_id || args.id)) || null,
+            error: toolError,
+          },
+        });
+      } catch (err) {
+        process.stderr.write(`telemetry warning: ${err.message}\n`);
+      }
+    };
+
+    if (!REGISTERED_TOOLS.includes(name)) {
+      toolError = 'UNKNOWN_TOOL';
+      emitTelemetry();
+      return errorResponse('UNKNOWN_TOOL', `tool ${name} is not registered on this server`);
+    }
+    const validateInput = inputValidators.get(name);
+    if (!validateInput(args)) {
+      toolError = 'VALIDATION_ERROR';
+      emitTelemetry();
+      return errorResponse('VALIDATION_ERROR', ajv.errorsText(validateInput.errors));
+    }
+
+    let result;
+    let toolDb = null;
+    try {
+      toolDb = STATELESS_TOOLS.has(name) ? null : getDb();
+      result = await dispatchTool(name, args, toolDb, { rootDir });
+    } catch (err) {
+      const code = err.code || (err instanceof ops.StateOpsError ? err.code : 'STATE_DB_ERROR');
+      toolError = code;
+      emitTelemetry();
+      return errorResponse(code, err.message, !!err.retriable, err.details);
+    }
+
+    const validateOutput = outputValidators.get(name);
+    if (!validateOutput(result)) {
+      toolError = 'OUTPUT_SCHEMA_DRIFT';
+      emitTelemetry();
+      return errorResponse('OUTPUT_SCHEMA_DRIFT', ajv.errorsText(validateOutput.errors));
+    }
+
+    if (toolDb && projectOnWrite && MUTATING_TOOLS.has(name)) {
+      try { projector.projectAll(toolDb, { rootDir }); }
+      catch (err) { process.stderr.write(`projector warning: ${err.message}\n`); }
+    }
+
+    emitTelemetry();
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result) }],
+      structuredContent: result,
+    };
+  });
+
+  return {
+    server,
+    get db() { return db; },
+    tools,
+    async close() { closeStateDb(db); },
+  };
+}
+
+async function main() {
+  const dbPath = process.env.UBP_DB_PATH
+    ? path.resolve(process.env.UBP_DB_PATH)
+    : path.resolve('.ultra', 'state.db');
+  const rootDir = process.env.UBP_ROOT_DIR
+    ? path.resolve(process.env.UBP_ROOT_DIR)
+    : path.resolve('.');
+  const handle = startServer({ dbPath, rootDir });
+  const transport = new StdioServerTransport();
+  await handle.server.connect(transport);
+  const cleanup = () => handle.close().finally(() => process.exit(0));
+  process.on('SIGTERM', cleanup);
+  process.on('SIGINT', cleanup);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    process.stderr.write(`mcp-server fatal: ${err.message}\n`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  main,
+  startServer,
+  dispatchTool,
+  TASK_TOOLS,
+  SESSION_TOOLS,
+  REGISTERED_TOOLS,
+  STATELESS_TOOLS,
+  MUTATING_TOOLS,
+};