ultra-builder-pro-cli 0.23.0 → 0.24.1

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

@@ -1,173 +0,0 @@
-'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');
-const runtimePaths = require('./runtime-paths.cjs');
-
-function blockedBreadcrumb(code, {
-  allowedTransitions = [],
-  requiredTransition = null,
-} = {}) {
-  return {
-    change_id: null,
-    task_id: null,
-    role: 'plan',
-    gate: 'alignment',
-    readiness: 'blocked',
-    blockers: [code],
-    warnings: [],
-    allowed_transitions: allowedTransitions,
-    required_transition: requiredTransition,
-    context_manifest_path: null,
-    context_manifest_hash: null,
-    git_head: null,
-    baseline: null,
-    accepted_intent: [],
-  };
-}
-
-function migrationBreadcrumb(code) {
-  return blockedBreadcrumb(code, {
-    allowedTransitions: ['ultra-init', 'ultra-status'],
-    requiredTransition: 'ultra-init',
-  });
-}
-
-function doctorBreadcrumb(code) {
-  return blockedBreadcrumb(code, {
-    allowedTransitions: ['ultra-doctor', 'ultra-status'],
-    requiredTransition: 'ultra-doctor',
-  });
-}
-
-function compactText(value, maximum = 240) {
-  const normalized = String(value || '').replace(/\s+/g, ' ').trim();
-  if (normalized.length <= maximum) return normalized;
-  return `${normalized.slice(0, maximum - 3).trimEnd()}...`;
-}
-
-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 = runtimePaths.locateStateDb(root);
-  if (!fs.existsSync(dbPath)) {
-    return blockedBreadcrumb('STATE_DB_MISSING', {
-      allowedTransitions: ['ultra-init', 'ultra-status'],
-      requiredTransition: '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(', ')}`);
-  }
-  if (breadcrumb.workflow) {
-    lines.push(
-      `Workflow: ${breadcrumb.workflow.id} (${breadcrumb.workflow.kind}/${breadcrumb.workflow.status})`,
-      `Step: ${breadcrumb.workflow.current_step || 'finalize'}`,
-    );
-  }
-  if (breadcrumb.decision) {
-    const current = breadcrumb.decision.current;
-    lines.push(
-      `Decision thread: ${breadcrumb.decision.thread_id} (${breadcrumb.decision.status}/${breadcrumb.decision.mode})`,
-      current
-        ? `Decision: ${current.id} — ${compactText(current.question)}`
-        : (breadcrumb.decision.status === 'checkpoint_ready'
-          ? 'Decision: checkpoint confirmation required'
-          : 'Decision: normalized intent recorded; application and read-back remain'),
-    );
-  }
-  for (const accepted of (breadcrumb.accepted_intent || []).slice(0, 3)) {
-    const value = accepted.decision
-      || (accepted.consequences ? `Deferred: ${accepted.consequences}` : 'Normalized state recorded');
-    lines.push(
-      `Accepted intent: ${accepted.decision_id} [${accepted.authority || accepted.status}] ${compactText(value)}`,
-    );
-  }
-  lines.push(`Allowed transitions: ${(breadcrumb.allowed_transitions || []).join(', ') || 'none'}`);
-  if (breadcrumb.required_transition) {
-    lines.push(`Required transition: ${breadcrumb.required_transition}`);
-  }
-  if (breadcrumb.context_manifest_path) {
-    lines.push(
-      `Context: ${breadcrumb.context_manifest_path} sha256=${breadcrumb.context_manifest_hash || 'unknown'}`,
-    );
-  }
-  lines.push(
-    'Lifecycle authority: .ultra/.runtime/state.db; digest-bound files carry semantic and evidence content; projections remain non-authoritative.',
-  );
-  return lines.join('\n');
-}
-
-module.exports = {
-  readProjectBreadcrumb,
-  renderProjectBreadcrumb,
-};

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

@@ -1,284 +0,0 @@
-'use strict';
-
-const crypto = require('node:crypto');
-const fs = require('node:fs');
-const path = require('node:path');
-
-const ops = require('./state-ops.cjs');
-const artifacts = require('./artifact-registry.cjs');
-
-const CANDIDATE_ID = /^[a-zA-Z0-9_-]+$/;
-const TRANSITIONS = Object.freeze({
-  proposed: new Set(['approved', 'rejected']),
-  approved: new Set(['applied', 'rejected']),
-  rejected: new Set(),
-  applied: new Set(),
-});
-
-class SpecLearningError extends Error {
-  constructor(code, message) {
-    super(message);
-    this.name = 'SpecLearningError';
-    this.code = code;
-  }
-}
-
-function nowIso() {
-  return new Date().toISOString();
-}
-
-function rowToCandidate(row) {
-  if (!row) return null;
-  let evidence;
-  try { evidence = JSON.parse(row.evidence_json); }
-  catch (error) {
-    throw new SpecLearningError('STATE_CORRUPT', `invalid spec-learning evidence: ${error.message}`);
-  }
-  let applyEvidence;
-  try { applyEvidence = JSON.parse(row.apply_evidence_json || '[]'); }
-  catch (error) {
-    throw new SpecLearningError('STATE_CORRUPT', `invalid spec-learning apply evidence: ${error.message}`);
-  }
-  const candidate = { ...row, evidence, apply_evidence: applyEvidence };
-  delete candidate.evidence_json;
-  delete candidate.apply_evidence_json;
-  return candidate;
-}
-
-function listSpecLearning(db, changeId) {
-  return db.prepare(
-    'SELECT * FROM spec_learning_candidates WHERE change_id = ? ORDER BY proposed_at ASC, id ASC',
-  ).all(changeId).map(rowToCandidate);
-}
-
-function writeAtomic(file, contents) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const temporary = `${file}.tmp-${process.pid}-${Date.now()}`;
-  fs.writeFileSync(temporary, contents);
-  fs.renameSync(temporary, file);
-}
-
-function upsertProjectionArtifact(db, change, rootDir, candidates) {
-  const file = path.resolve(rootDir, change.artifact_root, 'spec-learning.json');
-  const generatedAt = candidates.reduce((latest, candidate) => (
-    [candidate.applied_at, candidate.resolved_at, candidate.proposed_at]
-      .filter(Boolean)
-      .reduce((value, timestamp) => (timestamp > value ? timestamp : value), latest)
-  ), '1970-01-01T00:00:00.000Z');
-  const payload = {
-    schema_version: '1.0',
-    source: '.ultra/.runtime/state.db',
-    change_id: change.id,
-    generated_at: generatedAt,
-    candidates,
-  };
-  const serialized = `${JSON.stringify(payload, null, 2)}\n`;
-  writeAtomic(file, serialized);
-  const relative = path.relative(rootDir, file);
-  const hash = crypto.createHash('sha256').update(serialized).digest('hex');
-  const workflow = db.prepare(
-    `SELECT id FROM workflow_runs WHERE change_id = ?
-     ORDER BY started_at DESC, rowid DESC LIMIT 1`,
-  ).get(change.id);
-  if (!workflow) {
-    throw new SpecLearningError(
-      'ARTIFACT_CONSUMER_MISSING',
-      `change ${change.id} has no workflow consumer for spec learning`,
-    );
-  }
-  const taskConsumers = [...new Set(candidates.map((candidate) => candidate.task_id).filter(Boolean))]
-    .map((taskId) => ({ type: 'task', id: taskId, relation: 'consumed_by' }));
-  artifacts.recordArtifactInTx(db, {
-    owner_type: 'change',
-    owner_id: change.id,
-    kind: 'spec_learning',
-    path: relative,
-    content_digest: hash,
-    source_refs: [{ type: 'change', id: change.id, relation: 'produced_for' }],
-    consumer_refs: [
-      { type: 'workflow', id: workflow.id, relation: 'consumed_by' },
-      ...taskConsumers,
-    ],
-    provenance: { writer: 'spec-learning', workflow_run_id: workflow.id },
-    metadata: { candidates: candidates.length },
-  }, { rootDir });
-  return { path: file, hash };
-}
-
-function mutableChange(db, changeId) {
-  const change = db.prepare('SELECT * FROM changes WHERE id = ?').get(changeId);
-  if (!change) throw new SpecLearningError('CHANGE_NOT_FOUND', `change ${changeId} not found`);
-  if (!['active', 'blocked'].includes(change.status)) {
-    throw new SpecLearningError(
-      'CHANGE_NOT_MUTABLE', `change ${changeId} is ${change.status}; learning must resolve before convergence`,
-    );
-  }
-  return change;
-}
-
-function normalizeEvidence(value) {
-  if (value === undefined) return [];
-  if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || !entry.trim())) {
-    throw new SpecLearningError('VALIDATION_ERROR', 'spec-learning evidence must be non-empty strings');
-  }
-  return [...new Set(value.map((entry) => entry.trim()))];
-}
-
-function targetFile(rootDir, targetRef) {
-  const separator = String(targetRef || '').lastIndexOf('#');
-  if (separator <= 0 || separator === targetRef.length - 1) {
-    throw new SpecLearningError('VALIDATION_ERROR', 'target_ref must use project-relative path#anchor');
-  }
-  const relative = targetRef.slice(0, separator);
-  if (path.isAbsolute(relative)) {
-    throw new SpecLearningError('VALIDATION_ERROR', 'target_ref must be project-relative');
-  }
-  const root = path.resolve(rootDir);
-  const file = path.resolve(root, relative);
-  if (file !== root && !file.startsWith(`${root}${path.sep}`)) {
-    throw new SpecLearningError('VALIDATION_ERROR', 'target_ref escapes the project root');
-  }
-  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
-    throw new SpecLearningError('LEARNING_TARGET_MISSING', `target file does not exist: ${relative}`);
-  }
-  return { file, relative };
-}
-
-function digestFile(file) {
-  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
-}
-
-function verifyApplyEvidence(input, current, rootDir) {
-  const appliedRef = typeof input.applied_ref === 'string' ? input.applied_ref.trim() : '';
-  const beforeDigest = typeof input.before_digest === 'string' ? input.before_digest.trim() : '';
-  const afterDigest = typeof input.after_digest === 'string' ? input.after_digest.trim() : '';
-  const evidence = normalizeEvidence(input.apply_evidence);
-  if (appliedRef !== current.target_ref || !/^[0-9a-f]{64}$/.test(beforeDigest)
-    || !/^[0-9a-f]{64}$/.test(afterDigest) || beforeDigest === afterDigest
-    || evidence.length === 0) {
-    throw new SpecLearningError(
-      'LEARNING_APPLY_EVIDENCE_REQUIRED',
-      'apply requires the exact target ref, distinct before/after digests, and durable evidence refs',
-    );
-  }
-  if (current.before_digest && current.before_digest !== beforeDigest) {
-    throw new SpecLearningError(
-      'LEARNING_APPLY_EVIDENCE_MISMATCH', 'before_digest does not match the proposed target state',
-    );
-  }
-  const target = targetFile(rootDir, appliedRef);
-  if (digestFile(target.file) !== afterDigest) {
-    throw new SpecLearningError(
-      'LEARNING_APPLY_EVIDENCE_MISMATCH', 'after_digest does not match the current target file',
-    );
-  }
-  const workflows = require('./workflow-state.cjs');
-  try {
-    workflows.resolveProjectSourceRef(rootDir, appliedRef, 'applied_ref');
-    for (const ref of evidence) workflows.resolveProjectSourceRef(rootDir, ref, 'apply_evidence');
-  } catch (error) {
-    throw new SpecLearningError(
-      'LEARNING_APPLY_EVIDENCE_MISMATCH', `applied target or evidence anchor is invalid: ${error.message}`,
-    );
-  }
-  return { appliedRef, beforeDigest, afterDigest, evidence };
-}
-
-function proposeSpecLearning(db, input, { rootDir = process.cwd() } = {}) {
-  const change = mutableChange(db, input.change_id);
-  const id = String(input.id || `learning-${crypto.randomUUID().slice(0, 12)}`).trim();
-  if (!CANDIDATE_ID.test(id)) {
-    throw new SpecLearningError('VALIDATION_ERROR', `invalid spec-learning candidate id: ${id}`);
-  }
-  const targetRef = typeof input.target_ref === 'string' ? input.target_ref.trim() : '';
-  const summary = typeof input.summary === 'string' ? input.summary.trim() : '';
-  if (!targetRef || !summary) {
-    throw new SpecLearningError('VALIDATION_ERROR', 'target_ref and summary are required');
-  }
-  if (input.task_id) {
-    const task = db.prepare('SELECT change_id FROM tasks WHERE id = ?').get(input.task_id);
-    if (!task || task.change_id !== change.id) {
-      throw new SpecLearningError('TASK_NOT_FOUND', `task ${input.task_id} is not linked to change ${change.id}`);
-    }
-  }
-  const evidence = normalizeEvidence(input.evidence);
-  const proposedTarget = targetFile(rootDir, targetRef);
-  const proposedDigest = digestFile(proposedTarget.file);
-  const proposedAt = nowIso();
-  return ops.tx(db, () => {
-    try {
-      db.prepare(
-        `INSERT INTO spec_learning_candidates
-         (id, change_id, task_id, target_ref, summary, evidence_json, proposed_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?)`,
-      ).run(id, change.id, input.task_id || null, targetRef, summary, JSON.stringify(evidence), proposedAt);
-      db.prepare(
-        'UPDATE spec_learning_candidates SET before_digest = ? WHERE id = ? AND change_id = ?',
-      ).run(proposedDigest, id, change.id);
-    } catch (error) {
-      if (String(error.message).includes('UNIQUE')) {
-        throw new SpecLearningError('DUPLICATE_LEARNING_ID', `spec-learning candidate ${id} exists`);
-      }
-      throw error;
-    }
-    ops.appendEventInTx(db, {
-      type: 'spec_learning_proposed', change_id: change.id, task_id: input.task_id || null,
-      payload: { candidate_id: id, target_ref: targetRef },
-    });
-    const candidates = listSpecLearning(db, change.id);
-    upsertProjectionArtifact(db, change, rootDir, candidates);
-    return candidates.find((candidate) => candidate.id === id);
-  });
-}
-
-function resolveSpecLearning(db, input, { rootDir = process.cwd() } = {}) {
-  const change = mutableChange(db, input.change_id);
-  const current = rowToCandidate(db.prepare(
-    'SELECT * FROM spec_learning_candidates WHERE id = ? AND change_id = ?',
-  ).get(input.candidate_id, change.id));
-  if (!current) {
-    throw new SpecLearningError('LEARNING_NOT_FOUND', `candidate ${input.candidate_id} not found`);
-  }
-  const status = { approve: 'approved', reject: 'rejected', apply: 'applied' }[input.decision];
-  if (!status) throw new SpecLearningError('VALIDATION_ERROR', `invalid learning decision: ${input.decision}`);
-  if (!TRANSITIONS[current.status].has(status)) {
-    throw new SpecLearningError(
-      'ILLEGAL_LEARNING_TRANSITION', `cannot move candidate ${current.id} from ${current.status} to ${status}`,
-    );
-  }
-  const resolution = typeof input.resolution === 'string' ? input.resolution.trim() : '';
-  if (['rejected', 'applied'].includes(status) && !resolution) {
-    throw new SpecLearningError('VALIDATION_ERROR', `${input.decision} requires a resolution`);
-  }
-  const timestamp = nowIso();
-  const application = status === 'applied'
-    ? verifyApplyEvidence(input, current, rootDir)
-    : null;
-  return ops.tx(db, () => {
-    db.prepare(
-      `UPDATE spec_learning_candidates
-       SET status = ?, resolution = ?, resolved_at = ?, applied_at = ?, applied_ref = ?,
-       before_digest = COALESCE(?, before_digest), after_digest = ?, apply_evidence_json = ?
-       WHERE id = ? AND change_id = ?`,
-    ).run(
-      status, resolution || null, timestamp, status === 'applied' ? timestamp : null,
-      application?.appliedRef || null, application?.beforeDigest || null,
-      application?.afterDigest || null, JSON.stringify(application?.evidence || []),
-      current.id, change.id,
-    );
-    ops.appendEventInTx(db, {
-      type: 'spec_learning_resolved', change_id: change.id, task_id: current.task_id,
-      payload: { candidate_id: current.id, decision: input.decision, status },
-    });
-    const candidates = listSpecLearning(db, change.id);
-    upsertProjectionArtifact(db, change, rootDir, candidates);
-    return candidates.find((candidate) => candidate.id === current.id);
-  });
-}
-
-module.exports = {
-  SpecLearningError,
-  listSpecLearning,
-  proposeSpecLearning,
-  resolveSpecLearning,
-};