ultra-builder-pro-cli 0.12.1 → 0.14.0

package/mcp-server/lib/prd-parser.test.cjs

@@ -1,171 +1,82 @@
 'use strict';
 
-// Test Double rationale: external LLM API — deterministic fixtures prove
-// parsing logic (prompt assembly, schema validation, id normalization)
-// without egress cost or key dependence. Integration coverage against a
-// real LLM lives behind an env gate and is exercised separately.
-
 const test = require('node:test');
 const assert = require('node:assert/strict');
 
 const { parsePrd, PrdParseError, TASK_LIST_SCHEMA } = require('./prd-parser.cjs');
 
-function fakeClient(jsonFn, { usage = { input_tokens: 100, output_tokens: 50 }, model = 'claude-sonnet-4-6', provider = 'anthropic' } = {}) {
-  return {
-    provider,
-    model,
-    async completeJson({ system, user }) {
-      const json = typeof jsonFn === 'function' ? await jsonFn({ system, user }) : jsonFn;
-      return { json, raw: JSON.stringify(json), usage, model, provider };
-    },
-  };
-}
-
-const HAPPY_TASKS = {
-  tasks: [
-    {
-      id: 'task-1',
-      title: 'Design auth schema',
-      type: 'architecture',
-      priority: 'P1',
-      complexity: 5,
-      deps: [],
-      files_modified: ['src/auth/schema.ts'],
-    },
-    {
-      id: 'task-2',
-      title: 'Implement login endpoint',
-      type: 'feature',
-      priority: 'P1',
-      complexity: 6,
-      deps: ['task-1'],
-      files_modified: ['src/auth/login.ts'],
-    },
-  ],
-};
-
-test('parsePrd: happy path normalizes tasks and returns usage metadata', async () => {
-  const client = fakeClient(HAPPY_TASKS);
-  const result = await parsePrd('Build login', { llmClient: client, tag: 'feat-auth' });
+const HAPPY_TASKS = [
+  {
+    id: 'task-1',
+    title: 'Design auth schema',
+    type: 'architecture',
+    priority: 'P1',
+    complexity: 5,
+    deps: [],
+    files_modified: ['src/auth/schema.ts'],
+  },
+  {
+    id: 'task-2',
+    title: 'Implement login endpoint',
+    type: 'feature',
+    priority: 'P1',
+    complexity: 6,
+    deps: ['task-1'],
+    files_modified: ['src/auth/login.ts'],
+  },
+];
+
+test('parsePrd validates and normalizes host-derived tasks without a provider client', () => {
+  const result = parsePrd(HAPPY_TASKS, { tag: 'feat-auth', changeId: 'auth-change' });
   assert.equal(result.tasks.length, 2);
-  assert.equal(result.tasks[0].id, 'task-1');
   assert.equal(result.tasks[0].tag, 'feat-auth');
+  assert.equal(result.tasks[0].change_id, 'auth-change');
   assert.deepEqual(result.tasks[1].deps, ['task-1']);
-  assert.equal(result.model, 'claude-sonnet-4-6');
-  assert.equal(result.provider, 'anthropic');
-  assert.equal(result.usage.input_tokens, 100);
-});
-
-test('parsePrd: empty text → NO_INPUT', async () => {
-  await assert.rejects(
-    parsePrd('', { llmClient: fakeClient(HAPPY_TASKS) }),
-    (err) => err instanceof PrdParseError && err.code === 'NO_INPUT',
-  );
-  await assert.rejects(
-    parsePrd('   ', { llmClient: fakeClient(HAPPY_TASKS) }),
-    (err) => err instanceof PrdParseError && err.code === 'NO_INPUT',
-  );
+  assert.equal(Object.hasOwn(result, 'model'), false);
+  assert.equal(Object.hasOwn(result, 'provider'), false);
+  assert.equal(Object.hasOwn(result, 'usage'), false);
 });
 
-test('parsePrd: missing llmClient → NO_LLM_CLIENT', async () => {
-  await assert.rejects(
-    parsePrd('Build something', {}),
-    (err) => err instanceof PrdParseError && err.code === 'NO_LLM_CLIENT',
-  );
+test('parsePrd requires at least one host-derived task', () => {
+  for (const value of [undefined, null, [], 'not-an-array']) {
+    assert.throws(
+      () => parsePrd(value),
+      (err) => err instanceof PrdParseError && err.code === 'NO_INPUT',
+    );
+  }
 });
 
-test('parsePrd: llmClient error bubbles up as PARSE_FAILED', async () => {
-  const brokenClient = {
-    provider: 'anthropic',
-    model: 'claude-sonnet-4-6',
-    async completeJson() { throw new Error('upstream LLM 500'); },
-  };
-  await assert.rejects(
-    parsePrd('Build something', { llmClient: brokenClient }),
-    (err) => err instanceof PrdParseError && err.code === 'PARSE_FAILED' && /upstream LLM 500/.test(err.message),
-  );
-});
-
-test('parsePrd: invalid JSON shape rejected — missing required "priority"', async () => {
-  const bad = {
-    tasks: [{
-      id: 'task-1', title: 'Foo', type: 'feature', // priority missing
-      complexity: 3, deps: [], files_modified: [],
-    }],
-  };
-  await assert.rejects(
-    parsePrd('Build Foo', { llmClient: fakeClient(bad) }),
+test('parsePrd rejects an invalid task shape', () => {
+  assert.throws(
+    () => parsePrd([{
+      id: 'task-1', title: 'Missing priority', type: 'feature',
+    }]),
     (err) => err instanceof PrdParseError && err.code === 'PARSE_FAILED' && /priority/.test(err.message),
   );
 });
 
-test('parsePrd: invalid enum value rejected — bad type', async () => {
-  const bad = {
-    tasks: [{
-      id: 'task-1', title: 'Foo', type: 'chore', priority: 'P1',
-    }],
-  };
-  await assert.rejects(
-    parsePrd('Build Foo', { llmClient: fakeClient(bad) }),
-    (err) => err instanceof PrdParseError && err.code === 'PARSE_FAILED',
-  );
-});
-
-test('parsePrd: duplicate task id rejected', async () => {
-  const dup = {
-    tasks: [
+test('parsePrd rejects duplicate task ids', () => {
+  assert.throws(
+    () => parsePrd([
       { id: 'task-1', title: 'First copy', type: 'feature', priority: 'P2' },
       { id: 'task-1', title: 'Second copy', type: 'feature', priority: 'P2' },
-    ],
-  };
-  await assert.rejects(
-    parsePrd('Build dupes', { llmClient: fakeClient(dup) }),
+    ]),
     (err) => err instanceof PrdParseError && err.code === 'PARSE_FAILED' && /duplicate/i.test(err.message),
   );
 });
 
-test('parsePrd: missing optional fields are normalized to defaults', async () => {
-  const minimal = {
-    tasks: [{
-      id: 'task-1', title: 'Minimal task', type: 'feature', priority: 'P3',
-    }],
-  };
-  const result = await parsePrd('anything', { llmClient: fakeClient(minimal) });
+test('parsePrd normalizes optional fields', () => {
+  const result = parsePrd([{
+    id: 'task-1', title: 'Minimal task', type: 'feature', priority: 'P3',
+  }]);
   assert.equal(result.tasks[0].complexity, null);
   assert.deepEqual(result.tasks[0].deps, []);
   assert.deepEqual(result.tasks[0].files_modified, []);
   assert.equal(result.tasks[0].tag, null);
+  assert.equal(result.tasks[0].change_id, null);
 });
 
-test('parsePrd: prompt contains PRD text passed to llmClient', async () => {
-  let captured;
-  const client = {
-    provider: 'anthropic',
-    model: 'claude-sonnet-4-6',
-    async completeJson({ system, user }) {
-      captured = { system, user };
-      return {
-        json: HAPPY_TASKS,
-        raw: '',
-        usage: {},
-        model: 'claude-sonnet-4-6',
-        provider: 'anthropic',
-      };
-    },
-  };
-  await parsePrd('Build the thing with acceptance criteria X', { llmClient: client });
-  assert.match(captured.system, /engineering planner/i);
-  assert.match(captured.user, /Build the thing with acceptance criteria X/);
-});
-
-test('parsePrd: empty tasks array rejected (schema requires minItems:1)', async () => {
-  await assert.rejects(
-    parsePrd('Build nothing', { llmClient: fakeClient({ tasks: [] }) }),
-    (err) => err instanceof PrdParseError && err.code === 'PARSE_FAILED',
-  );
-});
-
-test('TASK_LIST_SCHEMA: exported for downstream consumers', () => {
+test('TASK_LIST_SCHEMA remains available to MCP contract consumers', () => {
   assert.equal(TASK_LIST_SCHEMA.required[0], 'tasks');
   assert.equal(TASK_LIST_SCHEMA.properties.tasks.minItems, 1);
 });

package/mcp-server/lib/project-breadcrumb.cjs

@@ -0,0 +1,139 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const Database = require('better-sqlite3');
+
+const { EXPECTED_VERSION, REQUIRED_TABLES } = require('./state-db.cjs');
+const { readBreadcrumb } = require('./context-spine.cjs');
+
+function blockedBreadcrumb(code, {
+  nextAction,
+  workflow,
+} = {}) {
+  return {
+    change_id: null,
+    task_id: null,
+    role: 'plan',
+    gate: 'alignment',
+    readiness: 'blocked',
+    blockers: [code],
+    warnings: [],
+    next_action: nextAction,
+    recommended_workflow: workflow,
+    context_manifest_path: null,
+    context_manifest_hash: null,
+    git_head: null,
+    baseline: null,
+  };
+}
+
+function migrationBreadcrumb(code) {
+  return blockedBreadcrumb(code, {
+    nextAction: 'Resume project initialization to migrate and re-establish the Ultra baseline.',
+    workflow: 'ultra-init',
+  });
+}
+
+function doctorBreadcrumb(code) {
+  return blockedBreadcrumb(code, {
+    nextAction: 'Run ultra-doctor to inspect and recover the authoritative Ultra state database.',
+    workflow: 'ultra-doctor',
+  });
+}
+
+function latestSchemaVersion(db) {
+  return db.prepare(
+    'SELECT version FROM schema_version ORDER BY applied_at DESC, rowid DESC LIMIT 1',
+  ).get()?.version || null;
+}
+
+function tableNames(db) {
+  return new Set(db.prepare(
+    "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'",
+  ).all().map((row) => row.name));
+}
+
+function readProjectBreadcrumb(rootDir) {
+  const root = path.resolve(rootDir || process.cwd());
+  const ultraDir = path.join(root, '.ultra');
+  if (!fs.existsSync(ultraDir)) return null;
+  const dbPath = path.join(ultraDir, 'state.db');
+  if (!fs.existsSync(dbPath)) {
+    return blockedBreadcrumb('STATE_DB_MISSING', {
+      nextAction: 'Initialize or resume this Ultra project through ultra-init.',
+      workflow: 'ultra-init',
+    });
+  }
+
+  let db;
+  try {
+    db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    db.pragma('query_only = ON');
+    db.pragma('busy_timeout = 1000');
+    const tables = tableNames(db);
+    if (!tables.has('schema_version')) {
+      return migrationBreadcrumb('STATE_SCHEMA_MIGRATION_REQUIRED:unknown');
+    }
+    const version = latestSchemaVersion(db);
+    if (version !== EXPECTED_VERSION) {
+      return migrationBreadcrumb(`STATE_SCHEMA_MIGRATION_REQUIRED:${version || 'unknown'}`);
+    }
+    const missing = REQUIRED_TABLES.filter((name) => !tables.has(name));
+    if (missing.length > 0) {
+      return doctorBreadcrumb(`STATE_SCHEMA_INCOMPLETE:${missing.join(',')}`);
+    }
+    return readBreadcrumb(db, {}, { rootDir: root });
+  } catch (error) {
+    const code = error && typeof error.code === 'string' ? error.code : 'unknown';
+    return doctorBreadcrumb(`STATE_DB_UNREADABLE:${code}`);
+  } finally {
+    if (db) db.close();
+  }
+}
+
+function renderProjectBreadcrumb(rootDir, breadcrumb) {
+  if (!breadcrumb) return '';
+  const root = path.resolve(rootDir || process.cwd());
+  const baseline = breadcrumb.baseline || {};
+  const task = breadcrumb.task_id || 'none';
+  const taskStatus = breadcrumb.task_status || 'none';
+  const lines = breadcrumb.change_id ? [
+    '[Ultra context spine]',
+    `Project: ${root}`,
+    `Baseline: ${baseline.id || 'unknown'} (${baseline.mode || 'unknown'}/${baseline.status || 'unknown'})`,
+    `Change: ${breadcrumb.change_id} (${breadcrumb.change_status || 'active'})`,
+    `Task: ${task} (${taskStatus})`,
+    `Role: ${breadcrumb.role || 'plan'}`,
+    `Gate: ${breadcrumb.gate || 'alignment'}`,
+    `Readiness: ${breadcrumb.readiness || 'blocked'}`,
+  ] : [
+    '[Ultra baseline]',
+    `Project: ${root}`,
+    `Baseline: ${baseline.id || 'missing'} (${baseline.mode || 'unknown'}/${baseline.status || 'missing'})`,
+    `Readiness: ${breadcrumb.readiness || 'blocked'}`,
+  ];
+  if (Array.isArray(breadcrumb.blockers) && breadcrumb.blockers.length > 0) {
+    lines.push(`Blockers: ${breadcrumb.blockers.join(', ')}`);
+  }
+  if (Array.isArray(breadcrumb.warnings) && breadcrumb.warnings.length > 0) {
+    lines.push(`Warnings: ${breadcrumb.warnings.join(', ')}`);
+  }
+  lines.push(
+    `Next: ${breadcrumb.next_action || 'Inspect Ultra status.'}`,
+    `Route: ${breadcrumb.recommended_workflow || 'ultra-doctor'}`,
+  );
+  if (breadcrumb.context_manifest_path) {
+    lines.push(
+      `Context: ${breadcrumb.context_manifest_path} sha256=${breadcrumb.context_manifest_hash || 'unknown'}`,
+    );
+  }
+  lines.push('Authority: .ultra/state.db; JSON/Markdown remain projections or evidence artifacts.');
+  return lines.join('\n');
+}
+
+module.exports = {
+  readProjectBreadcrumb,
+  renderProjectBreadcrumb,
+};

package/mcp-server/lib/project-breadcrumb.test.cjs

@@ -0,0 +1,112 @@
+'use strict';
+
+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 Database = require('better-sqlite3');
+
+const { initStateDb, closeStateDb } = require('./state-db.cjs');
+const { createChange } = require('./change-workflow.cjs');
+const { createTask } = require('./state-ops.cjs');
+const { compileRoleContext, readBreadcrumb } = require('./context-spine.cjs');
+const {
+  readProjectBreadcrumb,
+  renderProjectBreadcrumb,
+} = require('./project-breadcrumb.cjs');
+
+function tmpProject(prefix) {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  fs.mkdirSync(path.join(rootDir, '.ultra'), { recursive: true });
+  return rootDir;
+}
+
+test('project reader returns the exact canonical breadcrumb from state.db', () => {
+  const rootDir = tmpProject('ubp-project-breadcrumb-');
+  const state = initStateDb(path.join(rootDir, '.ultra', 'state.db'));
+  try {
+    state.db.prepare(
+      `INSERT INTO baselines
+       (id, project_name, mode, status, approved_by, approval_note, converged_at)
+       VALUES ('baseline-1', 'fixture', 'greenfield', 'ready', 'test', 'fixture', ?)`,
+    ).run(new Date().toISOString());
+    const { change } = createChange(state.db, {
+      id: 'db-change', title: 'Database change', kind: 'quick',
+      intent: 'Prove every host consumes one breadcrumb.',
+      docs_impact: { status: 'none', rationale: 'test fixture' },
+    }, { rootDir });
+    const task = createTask(state.db, {
+      id: 'db-task', title: 'Use one breadcrumb', type: 'bugfix', priority: 'P0',
+      change_id: change.id,
+    });
+    compileRoleContext(state.db, {
+      input: {
+        task_id: task.id,
+        role: 'implement',
+        gate: 'implementation',
+        execution_contract: {
+          slice_kind: 'tracer_bullet',
+          public_seam: 'all host injections',
+          verification_command: 'npm test',
+        },
+        next_action: 'Run the cross-host breadcrumb regression test.',
+      },
+      change,
+      tasks: [task],
+      rootDir,
+    });
+
+    const expected = readBreadcrumb(state.db, {}, { rootDir });
+    const actual = readProjectBreadcrumb(rootDir);
+    assert.deepEqual(actual, expected);
+    const rendered = renderProjectBreadcrumb(rootDir, actual);
+    assert.match(rendered, /Change: db-change/);
+    assert.match(rendered, /Task: db-task/);
+    assert.ok(rendered.includes(actual.next_action));
+    assert.match(rendered, /Authority: \.ultra\/state\.db/);
+  } finally {
+    closeStateDb(state.db);
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});
+
+test('project reader routes a missing authority to ultra-init', () => {
+  const rootDir = tmpProject('ubp-project-missing-db-');
+  try {
+    const breadcrumb = readProjectBreadcrumb(rootDir);
+    assert.equal(breadcrumb.readiness, 'blocked');
+    assert.deepEqual(breadcrumb.blockers, ['STATE_DB_MISSING']);
+    assert.equal(breadcrumb.recommended_workflow, 'ultra-init');
+  } finally {
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});
+
+test('project reader routes an old schema to ultra-init without consulting projections', () => {
+  const rootDir = tmpProject('ubp-project-old-schema-');
+  const db = new Database(path.join(rootDir, '.ultra', 'state.db'));
+  try {
+    db.exec(`
+      CREATE TABLE schema_version (
+        version TEXT PRIMARY KEY,
+        applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+      );
+      INSERT INTO schema_version(version) VALUES ('10.0');
+    `);
+  } finally {
+    db.close();
+  }
+  fs.writeFileSync(path.join(rootDir, '.ultra', 'workflow-state.json'), JSON.stringify({
+    command: 'ultra-dev', task_id: 'projection-task', status: 'active',
+  }));
+  try {
+    const breadcrumb = readProjectBreadcrumb(rootDir);
+    assert.equal(breadcrumb.readiness, 'blocked');
+    assert.ok(breadcrumb.blockers.includes('STATE_SCHEMA_MIGRATION_REQUIRED:10.0'));
+    assert.equal(breadcrumb.recommended_workflow, 'ultra-init');
+    assert.doesNotMatch(JSON.stringify(breadcrumb), /projection-task|ultra-dev/);
+  } finally {
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});

package/mcp-server/lib/spec-learning.test.cjs

@@ -23,7 +23,7 @@ function fixture() {
   db.prepare(
     `INSERT INTO baselines
      (id, project_name, mode, status, approved_by, approval_note, converged_at)
-     VALUES ('test-baseline', 'fixture', 'migrated', 'ready', 'test', 'legacy fixture', ?)`,
+     VALUES ('test-baseline', 'fixture', 'greenfield', 'ready', 'test', 'accepted fixture', ?)`,
   ).run(new Date().toISOString());
   changes.createChange(db, {
     id: 'learning-change', title: 'Learning change', kind: 'quick',

package/mcp-server/lib/state-authority.cjs

@@ -51,11 +51,17 @@ function assertStateAuthority(db, rootDir) {
     projection_path: projection.path,
     projection_version: projection.version,
   };
-  if (projection.version === '4.4') {
+  const migrationTargets = {
+    '4.4': '4.5',
+    '4.5': '12.0',
+  };
+  const migrationTarget = migrationTargets[projection.version];
+  if (migrationTarget) {
     throw new StateAuthorityError(
       'LEGACY_STATE_MIGRATION_REQUIRED',
-      `state.db has no tasks but ${projection.path} contains ${projection.taskCount} v4.4 tasks; `
-        + 'run ultra-tools migrate --from=4.4 --to=4.5 --source-dir <project-root> before using Ultra MCP tools',
+      `state.db has no tasks but ${projection.path} contains ${projection.taskCount} v${projection.version} tasks; `
+        + `run ultra-tools migrate --from=${projection.version} --to=${migrationTarget} `
+        + '--source-dir <project-root> before using Ultra MCP tools',
       details,
     );
   }