ultra-builder-pro-cli 0.5.0

package/mcp-server/lib/task-expander.cjs

@@ -0,0 +1,123 @@
+'use strict';
+
+// Phase 8A.3 — Expand a complex task into subtasks via injected llmClient.
+//
+// expandTask(db, { id, sub_count, strategy, llmClient }) reads the parent,
+// asks the LLM for children, and persists them atomically (children rows
+// with parent_id set, parent status → 'expanded'). The status transition
+// automatically emits task_expanded via state-ops' status→event map.
+// Strategy 'manual' is reserved for future CLI interactive flows.
+
+const Ajv = require('ajv/dist/2020');
+const ops = require('./state-ops.cjs');
+const {
+  buildExpandSystemPrompt,
+  buildExpandUserPrompt,
+} = require('../../orchestrator/planner/expand-prompt.cjs');
+
+const CHILDREN_SHAPE = Object.freeze({
+  type: 'object',
+  required: ['children'],
+  properties: {
+    children: {
+      type: 'array',
+      minItems: 1,
+      items: {
+        type: 'object',
+        required: ['id', 'title', 'type', 'priority'],
+        properties: {
+          id:             { type: 'string', pattern: '^[a-zA-Z0-9_\\-]+$' },
+          title:          { type: 'string', minLength: 3, maxLength: 200 },
+          type:           { type: 'string', enum: ['architecture', 'feature', 'bugfix'] },
+          priority:       { type: 'string', enum: ['P0', 'P1', 'P2', 'P3'] },
+          complexity:     { type: 'integer', minimum: 1, maximum: 10 },
+          deps:           { type: 'array', items: { type: 'string' } },
+          files_modified: { type: 'array', items: { type: 'string' } },
+        },
+      },
+    },
+  },
+});
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+const validateChildren = ajv.compile(CHILDREN_SHAPE);
+
+class TaskExpandError extends Error {
+  constructor(code, message, cause) {
+    super(message);
+    this.name = 'TaskExpandError';
+    this.code = code;
+    if (cause) this.cause = cause;
+  }
+}
+
+async function expandTask(db, { id, sub_count, strategy = 'llm', llmClient } = {}) {
+  if (!id) throw new TaskExpandError('VALIDATION_ERROR', 'id required');
+
+  const parent = ops.readTask(db, id);
+  if (!parent) throw new TaskExpandError('TASK_NOT_FOUND', `no task ${id}`);
+  if (parent.status === 'expanded') {
+    throw new TaskExpandError('ALREADY_EXPANDED', `task ${id} is already expanded`);
+  }
+  if (strategy === 'manual') {
+    throw new TaskExpandError('NOT_IMPLEMENTED', 'strategy "manual" not implemented; use "llm"');
+  }
+  if (strategy !== 'llm') {
+    throw new TaskExpandError('VALIDATION_ERROR', `unknown strategy "${strategy}"`);
+  }
+  if (!llmClient || typeof llmClient.completeJson !== 'function') {
+    throw new TaskExpandError('NO_LLM_CLIENT', 'llmClient.completeJson is required');
+  }
+
+  const system = buildExpandSystemPrompt({ sub_count });
+  const user = buildExpandUserPrompt(parent);
+
+  let reply;
+  try {
+    reply = await llmClient.completeJson({ system, user });
+  } catch (err) {
+    throw new TaskExpandError('LLM_CALL_FAILED', `LLM call failed: ${err.message}`, err);
+  }
+  if (!validateChildren(reply.json)) {
+    throw new TaskExpandError(
+      'INVALID_OUTPUT',
+      `LLM output failed schema: ${ajv.errorsText(validateChildren.errors)}`,
+    );
+  }
+
+  const seen = new Set();
+  const children = reply.json.children.map((c) => {
+    if (seen.has(c.id)) {
+      throw new TaskExpandError('INVALID_OUTPUT', `duplicate child id "${c.id}"`);
+    }
+    seen.add(c.id);
+    return {
+      id: c.id,
+      title: c.title,
+      type: c.type,
+      priority: c.priority,
+      complexity: c.complexity ?? null,
+      deps: Array.isArray(c.deps) ? c.deps : [],
+      files_modified: Array.isArray(c.files_modified) ? c.files_modified : [],
+      parent_id: parent.id,
+      tag: parent.tag,
+    };
+  });
+
+  return ops.tx(db, () => {
+    for (const child of children) {
+      ops.createTask(db, child);
+    }
+    ops.patchTask(db, parent.id, { status: 'expanded' });
+    return {
+      parent_id: parent.id,
+      children,
+    };
+  });
+}
+
+module.exports = {
+  expandTask,
+  TaskExpandError,
+  CHILDREN_SHAPE,
+};

package/mcp-server/lib/task-expander.test.cjs

@@ -0,0 +1,253 @@
+'use strict';
+
+// Integration tests for task-expander — real SQLite (Testcontainers-style
+// in-process) so parent_id column + status transition + task_expanded event
+// are exercised end-to-end. The only Test Double is the LLM client, which
+// we inject with deterministic child fixtures.
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { initStateDb, closeStateDb } = require('./state-db.cjs');
+const ops = require('./state-ops.cjs');
+const { expandTask, TaskExpandError } = require('./task-expander.cjs');
+
+function tmpDb() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-expand-'));
+  const { db } = initStateDb(path.join(dir, 'state.db'));
+  return { dir, db };
+}
+
+function cleanup({ dir, db }) {
+  closeStateDb(db);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+function fakeLlm(childrenJson, { shouldFail = false, usage = {} } = {}) {
+  return {
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-6',
+    async completeJson() {
+      if (shouldFail) throw new Error('upstream LLM 500');
+      return {
+        json: { children: childrenJson },
+        raw: JSON.stringify({ children: childrenJson }),
+        usage,
+        model: 'claude-sonnet-4-6',
+        provider: 'anthropic',
+      };
+    },
+  };
+}
+
+function seedParent(db, overrides = {}) {
+  return ops.createTask(db, {
+    id: 'parent-1',
+    title: 'Build authentication module',
+    type: 'feature',
+    priority: 'P1',
+    complexity: 9,
+    files_modified: ['src/auth/index.ts'],
+    ...overrides,
+  });
+}
+
+const HAPPY_CHILDREN = [
+  { id: 'child-1', title: 'Design auth schema',       type: 'architecture', priority: 'P1', complexity: 4, deps: [],          files_modified: ['src/auth/schema.ts'] },
+  { id: 'child-2', title: 'Implement login endpoint', type: 'feature',      priority: 'P1', complexity: 5, deps: ['child-1'], files_modified: ['src/auth/login.ts']  },
+  { id: 'child-3', title: 'Add signup endpoint',      type: 'feature',      priority: 'P2', complexity: 3, deps: ['child-1'], files_modified: ['src/auth/signup.ts'] },
+];
+
+test('expandTask happy path: creates children, flips parent status, emits task_expanded', async () => {
+  const ctx = tmpDb();
+  try {
+    seedParent(ctx.db);
+    const result = await expandTask(ctx.db, {
+      id: 'parent-1',
+      strategy: 'llm',
+      llmClient: fakeLlm(HAPPY_CHILDREN),
+    });
+    assert.equal(result.parent_id, 'parent-1');
+    assert.equal(result.children.length, 3);
+
+    const parentAfter = ops.readTask(ctx.db, 'parent-1');
+    assert.equal(parentAfter.status, 'expanded');
+
+    for (const child of HAPPY_CHILDREN) {
+      const row = ops.readTask(ctx.db, child.id);
+      assert.ok(row, `child ${child.id} missing`);
+      assert.equal(row.parent_id, 'parent-1');
+      assert.equal(row.status, 'pending');
+    }
+
+    const events = ops.subscribeEventsSince(ctx.db, { since_id: 0, limit: 100 });
+    const expandedEvents = events.events.filter((e) => e.type === 'task_expanded');
+    assert.equal(expandedEvents.length, 1);
+    assert.equal(expandedEvents[0].task_id, 'parent-1');
+    const createdEvents = events.events.filter((e) => e.type === 'task_created');
+    assert.ok(createdEvents.length >= 4, 'parent + 3 children task_created events');
+  } finally {
+    cleanup(ctx);
+  }
+});
+
+test('expandTask: missing parent → TASK_NOT_FOUND', async () => {
+  const ctx = tmpDb();
+  try {
+    await assert.rejects(
+      expandTask(ctx.db, {
+        id: 'does-not-exist',
+        llmClient: fakeLlm(HAPPY_CHILDREN),
+      }),
+      (err) => err instanceof TaskExpandError && err.code === 'TASK_NOT_FOUND',
+    );
+  } finally {
+    cleanup(ctx);
+  }
+});
+
+test('expandTask: already-expanded parent → ALREADY_EXPANDED', async () => {
+  const ctx = tmpDb();
+  try {
+    seedParent(ctx.db);
+    // First expansion succeeds
+    await expandTask(ctx.db, {
+      id: 'parent-1',
+      llmClient: fakeLlm(HAPPY_CHILDREN),
+    });
+    // Second attempt must refuse
+    await assert.rejects(
+      expandTask(ctx.db, {
+        id: 'parent-1',
+        llmClient: fakeLlm(HAPPY_CHILDREN.map((c, i) => ({ ...c, id: `other-${i}` }))),
+      }),
+      (err) => err instanceof TaskExpandError && err.code === 'ALREADY_EXPANDED',
+    );
+  } finally {
+    cleanup(ctx);
+  }
+});
+
+test('expandTask: strategy="manual" → NOT_IMPLEMENTED', async () => {
+  const ctx = tmpDb();
+  try {
+    seedParent(ctx.db);
+    await assert.rejects(
+      expandTask(ctx.db, {
+        id: 'parent-1',
+        strategy: 'manual',
+        llmClient: fakeLlm(HAPPY_CHILDREN),
+      }),
+      (err) => err instanceof TaskExpandError && err.code === 'NOT_IMPLEMENTED',
+    );
+  } finally {
+    cleanup(ctx);
+  }
+});
+
+test('expandTask: missing llmClient → NO_LLM_CLIENT', async () => {
+  const ctx = tmpDb();
+  try {
+    seedParent(ctx.db);
+    await assert.rejects(
+      expandTask(ctx.db, { id: 'parent-1' }),
+      (err) => err instanceof TaskExpandError && err.code === 'NO_LLM_CLIENT',
+    );
+  } finally {
+    cleanup(ctx);
+  }
+});
+
+test('expandTask: LLM throws → LLM_CALL_FAILED', async () => {
+  const ctx = tmpDb();
+  try {
+    seedParent(ctx.db);
+    await assert.rejects(
+      expandTask(ctx.db, {
+        id: 'parent-1',
+        llmClient: fakeLlm([], { shouldFail: true }),
+      }),
+      (err) => err instanceof TaskExpandError && err.code === 'LLM_CALL_FAILED',
+    );
+    // parent status must be unchanged
+    assert.equal(ops.readTask(ctx.db, 'parent-1').status, 'pending');
+  } finally {
+    cleanup(ctx);
+  }
+});
+
+test('expandTask: invalid child shape → INVALID_OUTPUT, parent untouched', async () => {
+  const ctx = tmpDb();
+  try {
+    seedParent(ctx.db);
+    const bad = [{ id: 'child-1', title: 'x', type: 'feature', priority: 'P1' }]; // title too short
+    await assert.rejects(
+      expandTask(ctx.db, { id: 'parent-1', llmClient: fakeLlm(bad) }),
+      (err) => err instanceof TaskExpandError && err.code === 'INVALID_OUTPUT',
+    );
+    assert.equal(ops.readTask(ctx.db, 'parent-1').status, 'pending');
+  } finally {
+    cleanup(ctx);
+  }
+});
+
+test('expandTask: duplicate child id → INVALID_OUTPUT', async () => {
+  const ctx = tmpDb();
+  try {
+    seedParent(ctx.db);
+    const dup = [
+      { id: 'same', title: 'First child',  type: 'feature', priority: 'P2' },
+      { id: 'same', title: 'Second child', type: 'feature', priority: 'P2' },
+    ];
+    await assert.rejects(
+      expandTask(ctx.db, { id: 'parent-1', llmClient: fakeLlm(dup) }),
+      (err) => err instanceof TaskExpandError && err.code === 'INVALID_OUTPUT',
+    );
+  } finally {
+    cleanup(ctx);
+  }
+});
+
+test('expandTask: tx rollback — child id collides with existing task → parent status unchanged, no children inserted', async () => {
+  const ctx = tmpDb();
+  try {
+    seedParent(ctx.db);
+    // Pre-create a task with the same id one of the children will try
+    ops.createTask(ctx.db, {
+      id: 'child-1',
+      title: 'Pre-existing task',
+      type: 'bugfix',
+      priority: 'P3',
+    });
+    await assert.rejects(
+      expandTask(ctx.db, { id: 'parent-1', llmClient: fakeLlm(HAPPY_CHILDREN) }),
+      /* any error is acceptable — the point is no partial state */
+    );
+    assert.equal(ops.readTask(ctx.db, 'parent-1').status, 'pending');
+    // child-2 / child-3 must NOT have been inserted
+    assert.equal(ops.readTask(ctx.db, 'child-2'), null);
+    assert.equal(ops.readTask(ctx.db, 'child-3'), null);
+  } finally {
+    cleanup(ctx);
+  }
+});
+
+test('expandTask: children inherit parent tag', async () => {
+  const ctx = tmpDb();
+  try {
+    seedParent(ctx.db, { tag: 'feat-auth' });
+    await expandTask(ctx.db, {
+      id: 'parent-1',
+      llmClient: fakeLlm(HAPPY_CHILDREN),
+    });
+    for (const child of HAPPY_CHILDREN) {
+      const row = ops.readTask(ctx.db, child.id);
+      assert.equal(row.tag, 'feat-auth');
+    }
+  } finally {
+    cleanup(ctx);
+  }
+});

package/mcp-server/lib/telemetry.cjs

@@ -0,0 +1,72 @@
+'use strict';
+
+// Phase 6.2 — Telemetry collector.
+//
+// Double-write model: state.db.telemetry (table, queryable via state-ops
+// aggregations) + .ultra/telemetry/{YYYY-MM-DD}.jsonl (full payload, easy
+// grep, no schema constraint). The table is the authoritative source for
+// cost panel queries; the jsonl is for human ops + audit trails + future
+// Phase 6.5 SDK-usage correlation.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { computeCost } = require('./pricing.cjs');
+
+function todayStamp() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function telemetryJsonlPath(rootDir) {
+  return path.join(rootDir || '.', '.ultra', 'telemetry', `${todayStamp()}.jsonl`);
+}
+
+function appendTelemetry(db, {
+  event_type,
+  tool_name = null,
+  session_id = null,
+  runtime = null,
+  tokens_input = null,
+  tokens_output = null,
+  cost_usd = null,
+  task_id = null,
+  payload = null,
+  rootDir = '.',
+} = {}) {
+  if (!event_type) throw new Error('appendTelemetry: event_type required');
+
+  // Auto-derive cost when tokens + runtime known and caller didn't supply one.
+  let effectiveCost = cost_usd;
+  if (effectiveCost === null && runtime && tokens_input !== null && tokens_output !== null) {
+    effectiveCost = computeCost(runtime, payload && payload.model, tokens_input, tokens_output);
+  }
+
+  const now = new Date().toISOString();
+  const result = db.prepare(
+    'INSERT INTO telemetry (session_id, event_type, tokens_input, tokens_output, tool_name, cost_usd, ts) VALUES (?, ?, ?, ?, ?, ?, ?)',
+  ).run(session_id, event_type, tokens_input, tokens_output, tool_name, effectiveCost, now);
+
+  const jsonl = telemetryJsonlPath(rootDir);
+  fs.mkdirSync(path.dirname(jsonl), { recursive: true });
+  fs.appendFileSync(jsonl, JSON.stringify({
+    id: Number(result.lastInsertRowid),
+    ts: now,
+    session_id,
+    event_type,
+    tool_name,
+    runtime,
+    tokens_input,
+    tokens_output,
+    cost_usd: effectiveCost,
+    task_id,
+    payload,
+  }) + '\n');
+
+  return { id: Number(result.lastInsertRowid), ts: now, cost_usd: effectiveCost };
+}
+
+module.exports = {
+  appendTelemetry,
+  telemetryJsonlPath,
+  todayStamp,
+};

package/mcp-server/lib/topo.cjs

@@ -0,0 +1,131 @@
+'use strict';
+
+// Phase 8A.2 — Dependency topology (Functional Core, no IO).
+//
+// computeWaves groups tasks into execution waves where every task in wave N
+// has all its deps satisfied by waves < N. Cycles are surfaced as separate
+// SCCs via Tarjan so each independent loop is reported on its own.
+//
+// Input:  tasks = [{ id: string, deps: string[] }, ...]
+// Output: { waves: string[][], cycles: string[][] }
+//   - waves[i] is the set of task ids runnable in wave i. Order within a
+//     wave is not meaningful — callers should treat each wave as a set.
+//   - cycles[j] holds the ids of a strongly-connected component (size >= 2,
+//     or size 1 with a self-dep). Empty when the graph is acyclic.
+//
+// Deps that point to ids not present in the input set are treated as
+// already satisfied (the task was completed in a previous plan, or lives
+// outside the current topo scope).
+
+function computeWaves(tasks) {
+  if (!Array.isArray(tasks)) {
+    throw new TypeError('computeWaves: tasks must be an array');
+  }
+
+  const ids = new Set(tasks.map((t) => t.id));
+
+  // adj: prerequisite id → [dependent ids]
+  // inDeg: id → count of in-scope deps not yet satisfied
+  const adj = new Map();
+  const inDeg = new Map();
+
+  for (const t of tasks) {
+    if (!inDeg.has(t.id)) inDeg.set(t.id, 0);
+  }
+  for (const t of tasks) {
+    const deps = Array.isArray(t.deps) ? t.deps : [];
+    for (const d of deps) {
+      if (!ids.has(d)) continue;
+      if (!adj.has(d)) adj.set(d, []);
+      adj.get(d).push(t.id);
+      inDeg.set(t.id, (inDeg.get(t.id) || 0) + 1);
+    }
+  }
+
+  const waves = [];
+  const processed = new Set();
+  let current = tasks.map((t) => t.id).filter((id) => inDeg.get(id) === 0);
+
+  while (current.length > 0) {
+    waves.push(current);
+    for (const id of current) processed.add(id);
+    const next = [];
+    for (const id of current) {
+      const children = adj.get(id) || [];
+      for (const c of children) {
+        const newDeg = (inDeg.get(c) || 0) - 1;
+        inDeg.set(c, newDeg);
+        if (newDeg === 0 && !processed.has(c)) next.push(c);
+      }
+    }
+    current = next;
+  }
+
+  const residual = tasks.map((t) => t.id).filter((id) => !processed.has(id));
+  const cycles = residual.length === 0 ? [] : findSccs(residual, tasks);
+
+  return { waves, cycles };
+}
+
+function findSccs(residualIds, tasks) {
+  const inScope = new Set(residualIds);
+  const adj = new Map();
+  const selfLoops = new Set();
+
+  for (const t of tasks) {
+    if (!inScope.has(t.id)) continue;
+    const deps = Array.isArray(t.deps) ? t.deps : [];
+    for (const d of deps) {
+      if (!inScope.has(d)) continue;
+      if (d === t.id) { selfLoops.add(t.id); continue; }
+      if (!adj.has(d)) adj.set(d, []);
+      adj.get(d).push(t.id);
+    }
+  }
+
+  let index = 0;
+  const indices = new Map();
+  const lowlinks = new Map();
+  const onStack = new Set();
+  const stack = [];
+  const sccs = [];
+
+  function strongconnect(v) {
+    indices.set(v, index);
+    lowlinks.set(v, index);
+    index++;
+    stack.push(v);
+    onStack.add(v);
+
+    const succ = adj.get(v) || [];
+    for (const w of succ) {
+      if (!indices.has(w)) {
+        strongconnect(w);
+        lowlinks.set(v, Math.min(lowlinks.get(v), lowlinks.get(w)));
+      } else if (onStack.has(w)) {
+        lowlinks.set(v, Math.min(lowlinks.get(v), indices.get(w)));
+      }
+    }
+
+    if (lowlinks.get(v) === indices.get(v)) {
+      const scc = [];
+      let w;
+      do {
+        w = stack.pop();
+        onStack.delete(w);
+        scc.push(w);
+      } while (w !== v);
+      if (scc.length > 1 || selfLoops.has(v)) {
+        sccs.push(scc);
+      }
+    }
+  }
+
+  for (const v of residualIds) {
+    if (!indices.has(v)) strongconnect(v);
+  }
+
+  return sccs;
+}
+
+module.exports = { computeWaves };