ultra-builder-pro-cli 0.25.0 → 0.26.0

package/mcp-server/lib/change-workflow.cjs

@@ -1,65 +0,0 @@
-'use strict';
-
-const baselines = require('./baseline-workflow.cjs');
-const kernel = require('./kernel-change-workflow.cjs');
-
-function createChange(db, input, options = {}) {
-  return kernel.createChange(db, input, options);
-}
-
-function updateChange(db, id, patch = {}, options = {}) {
-  return kernel.updateChange(db, id, patch, options);
-}
-
-function supersedeChange(db, input = {}, options = {}) {
-  return kernel.supersedeChange(db, input, options);
-}
-
-function assertTaskCreationAllowed(db, input = {}, {
-  rootDir = process.cwd(),
-} = {}) {
-  const change = input.change_id ? kernel.readChange(db, input.change_id) : null;
-  if (input.change_id && !change) {
-    throw new kernel.ChangeWorkflowError(
-      'CHANGE_NOT_FOUND',
-      `change ${input.change_id} not found`,
-    );
-  }
-  if (change && !['active', 'blocked'].includes(change.status)) {
-    throw new kernel.ChangeWorkflowError(
-      'CHANGE_NOT_MUTABLE',
-      `change ${change.id} is ${change.status}`,
-    );
-  }
-  const health = baselines.inspectBaseline(db, { rootDir });
-  return {
-    allowed: true,
-    diagnostics: health.status === 'pass'
-      ? []
-      : (health.blockers || []).map((code) => ({
-        code,
-        severity: 'needs_attention',
-      })),
-  };
-}
-
-function archiveChange(db, input, options = {}) {
-  return kernel.archiveChange(db, input, options);
-}
-
-module.exports = {
-  ChangeWorkflowError: kernel.ChangeWorkflowError,
-  createChange,
-  readChange: kernel.readChange,
-  listChanges: kernel.listChanges,
-  updateChange,
-  supersedeChange,
-  recordDelta: kernel.recordDelta,
-  recordDocumentationReconciliation: kernel.recordDocumentationReconciliation,
-  archiveChange,
-  normalizeDocsImpact: kernel.normalizeDocsImpact,
-  normalizeProviderRefs: kernel.normalizeProviderRefs,
-  normalizeBaselineBypass: kernel.normalizeBaselineBypass,
-  assertTaskCreationAllowed,
-  recoverInterruptedArchives: kernel.recoverInterruptedArchives,
-};

package/mcp-server/lib/context-envelope.cjs

@@ -1,581 +0,0 @@
-'use strict';
-
-const path = require('node:path');
-
-const { version: PACKAGE_VERSION } = require('../../package.json');
-const artifactRegistry = require('./artifact-registry.cjs');
-const baselines = require('./baseline-workflow.cjs');
-const canonical = require('./canonical-json.cjs');
-const changes = require('./change-workflow.cjs');
-const decisions = require('./decision-records.cjs');
-const {
-  restoreManagedFile,
-  snapshotManagedFile,
-  writeManagedJson,
-} = require('./managed-file-write.cjs');
-const ops = require('./state-ops.cjs');
-const { readStableProjectFile } = require('./safe-project-file.cjs');
-const checkpoints = require('./stage-checkpoints.cjs');
-const taskLedger = require('./task-ledger.cjs');
-
-const SUMMARY_LIMIT = 16 * 1024;
-const FULL_LIMIT = 64 * 1024;
-
-class ContextEnvelopeError extends Error {
-  constructor(code, message, details) {
-    super(message);
-    this.name = 'ContextEnvelopeError';
-    this.code = code;
-    if (details !== undefined) this.details = details;
-  }
-}
-
-function parseJson(value, fallback) {
-  try { return value == null ? fallback : JSON.parse(value); }
-  catch { return fallback; }
-}
-
-function text(value, max) {
-  if (typeof value !== 'string') return value;
-  if (value.length <= max) return value;
-  return `${value.slice(0, Math.max(0, max - 32))}…[truncated ${value.length - max + 32} chars]`;
-}
-
-function compactValue(value, {
-  depth = 0,
-  maxDepth = 5,
-  textLimit = 2000,
-  arrayLimit = 50,
-} = {}) {
-  if (typeof value === 'string') return text(value, textLimit);
-  if (value === null || value === undefined || typeof value !== 'object') return value;
-  if (depth >= maxDepth) return Array.isArray(value) ? `[${value.length} items]` : '[object]';
-  if (Array.isArray(value)) {
-    return value.slice(0, arrayLimit).map((item) => compactValue(item, {
-      depth: depth + 1, maxDepth, textLimit, arrayLimit,
-    }));
-  }
-  return Object.fromEntries(Object.entries(value).map(([key, child]) => [
-    key,
-    compactValue(child, { depth: depth + 1, maxDepth, textLimit, arrayLimit }),
-  ]));
-}
-
-function selectedChange(db, changeId) {
-  if (!changeId) return null;
-  return changes.readChange(db, changeId);
-}
-
-function selectedTask(db, taskId) {
-  if (!taskId) return null;
-  return ops.readTask(db, taskId);
-}
-
-function resolvedScope(db, input = {}) {
-  const requested = input.scope || {};
-  const task = selectedTask(db, requested.task_id);
-  if (requested.task_id && !task) {
-    throw new ContextEnvelopeError(
-      'CONTEXT_SCOPE_NOT_FOUND',
-      `Context task scope does not exist: ${requested.task_id}`,
-      { scope_type: 'task', scope_id: requested.task_id },
-    );
-  }
-  const changeId = requested.change_id || task?.change_id || null;
-  const change = selectedChange(db, changeId);
-  if (requested.change_id && !change) {
-    throw new ContextEnvelopeError(
-      'CONTEXT_SCOPE_NOT_FOUND',
-      `Context Change scope does not exist: ${requested.change_id}`,
-      { scope_type: 'change', scope_id: requested.change_id },
-    );
-  }
-  if (task && requested.change_id && task.change_id !== requested.change_id) {
-    throw new ContextEnvelopeError(
-      'CONTEXT_SCOPE_MISMATCH',
-      `Context task ${task.id} belongs to Change ${task.change_id || '(none)'}, not ${requested.change_id}`,
-      {
-        task_id: task.id,
-        task_change_id: task.change_id || null,
-        requested_change_id: requested.change_id,
-      },
-    );
-  }
-  const baseline = baselines.readBaseline(db);
-  if (task) return { type: 'task', id: task.id, baseline, change, task };
-  if (change) return { type: 'change', id: change.id, baseline, change, task: null };
-  if (!requested.task_id && !requested.change_id) {
-    const activeChangeRow = db.prepare(
-      `SELECT id FROM changes
-       WHERE status IN ('active', 'blocked', 'ready')
-       ORDER BY
-         CASE status WHEN 'active' THEN 0 WHEN 'blocked' THEN 1 ELSE 2 END,
-         updated_at DESC,
-         rowid DESC
-       LIMIT 1`,
-    ).get();
-    if (activeChangeRow) {
-      const activeChange = selectedChange(db, activeChangeRow.id);
-      const activeTaskRow = db.prepare(
-        `SELECT id FROM tasks
-         WHERE change_id = ? AND status IN ('in_progress', 'blocked', 'pending')
-         ORDER BY
-           CASE status WHEN 'in_progress' THEN 0 WHEN 'blocked' THEN 1 ELSE 2 END,
-           updated_at DESC,
-           rowid DESC
-         LIMIT 1`,
-      ).get(activeChangeRow.id);
-      const activeTask = activeTaskRow ? selectedTask(db, activeTaskRow.id) : null;
-      if (activeTask) {
-        return {
-          type: 'task',
-          id: activeTask.id,
-          baseline,
-          change: activeChange,
-          task: activeTask,
-        };
-      }
-      return {
-        type: 'change',
-        id: activeChange.id,
-        baseline,
-        change: activeChange,
-        task: null,
-      };
-    }
-  }
-  if (baseline) return { type: 'baseline', id: baseline.id, baseline, change: null, task: null };
-  return { type: 'project', id: 'project', baseline: null, change: null, task: null };
-}
-
-function acceptedDecisionRows(db, scope, rootDir) {
-  const rows = [];
-  if (scope.baseline) {
-    rows.push(...decisions.listAcceptedDecisions(
-      db,
-      { baseline_id: scope.baseline.id },
-      { limit: 200, rootDir, validateFiles: true },
-    ));
-  }
-  if (scope.change) {
-    rows.push(...decisions.listAcceptedDecisions(
-      db,
-      { change_id: scope.change.id },
-      { limit: 200, rootDir, validateFiles: true },
-    ));
-  }
-  return rows;
-}
-
-function checkpointRows(db, scope) {
-  const rows = [];
-  if (scope.change) {
-    rows.push(...checkpoints.listCheckpoints(
-      db,
-      { scope: { change_id: scope.change.id }, limit: 100 },
-    ).filter((item) => item.status !== 'superseded'));
-  }
-  if (scope.task) {
-    rows.push(...checkpoints.listCheckpoints(
-      db,
-      { scope: { task_id: scope.task.id }, limit: 100 },
-    ).filter((item) => item.status !== 'superseded'));
-  }
-  if (!scope.change && scope.baseline) {
-    rows.push(...checkpoints.listCheckpoints(
-      db,
-      { scope: { baseline_id: scope.baseline.id }, limit: 100 },
-    ).filter((item) => item.status !== 'superseded'));
-  }
-  return rows;
-}
-
-function artifactRows(db, scope) {
-  const clauses = [
-    "status <> 'archived'",
-    "kind NOT IN ('context_envelope', 'worker_packet')",
-  ];
-  const params = [];
-  if (scope.task) {
-    clauses.push('(task_id = ? OR change_id = ?)');
-    params.push(scope.task.id, scope.change?.id || '');
-  } else if (scope.change) {
-    clauses.push('change_id = ?');
-    params.push(scope.change.id);
-  } else if (scope.baseline) {
-    clauses.push("(owner_type = 'baseline' AND owner_id = ?)");
-    params.push(scope.baseline.id);
-  } else {
-    clauses.push("owner_type = 'project'");
-  }
-  return db.prepare(
-    `SELECT id, owner_type, owner_id, kind, path, digest, status, provenance_json
-     FROM artifacts WHERE ${clauses.join(' AND ')}
-     ORDER BY updated_at DESC, id ASC LIMIT 500`,
-  ).all(...params).map((row) => ({
-    id: row.id,
-    owner_type: row.owner_type,
-    owner_id: row.owner_id,
-    kind: row.kind,
-    ref: row.path,
-    digest: row.digest,
-    status: row.status,
-    provenance: parseJson(row.provenance_json, {}),
-  }));
-}
-
-function executionState(db, scope) {
-  if (!scope.task) return { session: null };
-  const session = db.prepare(
-    `SELECT sid, task_id, runtime, worktree_path, artifact_dir, status,
-            lease_expires_at, heartbeat_at, started_at
-     FROM sessions WHERE task_id = ?
-     ORDER BY started_at DESC, rowid DESC LIMIT 1`,
-  ).get(scope.task.id) || null;
-  const packet = db.prepare(
-    `SELECT id, role, context_envelope_id, context_digest, task_digest,
-            decision_digest, packet_digest, packet_path, output_path, created_at
-     FROM worker_packets WHERE scope_type = 'task' AND scope_id = ?
-       AND status = 'assigned'
-     ORDER BY created_at DESC, rowid DESC LIMIT 1`,
-  ).get(scope.task.id) || null;
-  return { session, worker_packet: packet };
-}
-
-function ledgerHealth(db, rootDir) {
-  try {
-    const result = taskLedger.inspectTaskLedger(db, { rootDir });
-    return {
-      status: result.status || 'available',
-      generation: result.generation ?? null,
-      state_digest: result.state_digest || null,
-      path: taskLedger.LEDGER_RELATIVE_PATH,
-    };
-  } catch (error) {
-    return {
-      status: 'migration_required',
-      generation: null,
-      state_digest: null,
-      path: taskLedger.LEDGER_RELATIVE_PATH,
-      migration: {
-        required: true,
-        code: error.code || 'TASK_LEDGER_INVALID',
-        action: 'ultra.sync migrate',
-      },
-    };
-  }
-}
-
-function authorityPayload(db, input, options) {
-  const rootDir = path.resolve(options.rootDir || process.cwd());
-  const stage = input.stage || 'project';
-  const scope = resolvedScope(db, input);
-  const baselineHealth = scope.baseline
-    ? baselines.inspectBaseline(db, { rootDir })
-    : { blockers: [], warnings: [] };
-  const checkpointList = checkpointRows(db, scope);
-  const diagnostics = {
-    warnings: (baselineHealth.warnings || []).map((code) => ({ code, severity: 'warning' })),
-    needs_attention: checkpointList.flatMap((item) => (
-      item.diagnostics.filter((diagnostic) => diagnostic.severity === 'needs_attention')
-    )),
-    hard_conflicts: checkpointList.flatMap((item) => (
-      item.diagnostics.filter((diagnostic) => diagnostic.severity === 'hard_conflict')
-    )),
-  };
-  if (scope.task) {
-    diagnostics.warnings.push(...ops.taskContractBlockers(scope.task).map((code) => ({
-      code,
-      severity: 'warning',
-      message: 'Task semantics are incomplete; the active Skill and model own the decision to proceed.',
-    })));
-  }
-  if (scope.change) {
-    const advisory = [
-      [!String(scope.change.contract?.outcome || '').trim(), 'CHANGE_OUTCOME_UNRESOLVED'],
-      [!Array.isArray(scope.change.contract?.acceptance)
-        || scope.change.contract.acceptance.length === 0, 'CHANGE_ACCEPTANCE_UNRESOLVED'],
-      [!scope.change.contract?.recovery, 'CHANGE_RECOVERY_UNRESOLVED'],
-      [!String(scope.change.classification?.rationale || '').trim(), 'CHANGE_CLASSIFICATION_UNRESOLVED'],
-      [scope.change.research_disposition?.status === 'unresolved',
-        'CHANGE_RESEARCH_DISPOSITION_UNRESOLVED'],
-    ];
-    diagnostics.warnings.push(...advisory
-      .filter(([missing]) => missing)
-      .map(([, code]) => ({
-        code,
-        severity: 'warning',
-        message: 'Change semantics remain mutable; the active Skill and model own completion.',
-      })));
-  }
-  for (const code of baselineHealth.blockers || []) {
-    diagnostics.needs_attention.push({ code, severity: 'needs_attention' });
-  }
-  const ledger = ledgerHealth(db, rootDir);
-  if (ledger.migration?.required) {
-    diagnostics.needs_attention.push({
-      code: ledger.migration.code,
-      severity: 'needs_attention',
-      action: ledger.migration.action,
-    });
-  }
-  return {
-    schema_version: '1.0',
-    project: {
-      root: '.',
-      runtime: options.runtime || 'unknown',
-      plugin_version: PACKAGE_VERSION,
-      health: diagnostics.hard_conflicts.length > 0 ? 'conflict' : 'available',
-    },
-    git: scope.baseline ? {
-      head: baselineHealth.current_repository_revision || scope.baseline.repository_revision || null,
-      branch: scope.baseline.repository_branch || null,
-      scoped_worktree_digest: scope.baseline.worktree_digest || null,
-      drift: {
-        metadata_only: (baselineHealth.warnings || []).includes('BASELINE_METADATA_ONLY_DRIFT'),
-        source_or_spec: (baselineHealth.blockers || []).some((code) => (
-          String(code).includes('SOURCE') || String(code).includes('SPEC')
-        )),
-      },
-    } : null,
-    baseline: scope.baseline,
-    change: scope.change,
-    task: scope.task,
-    decisions: acceptedDecisionRows(db, scope, rootDir),
-    checkpoints: checkpointList,
-    evidence: [
-      ...(scope.baseline?.evidence || []),
-      ...artifactRows(db, scope),
-    ],
-    execution: {
-      stage,
-      ...executionState(db, scope),
-    },
-    team_checkpoint: ledger,
-    diagnostics,
-  };
-}
-
-function presentation(authority, detail) {
-  const summary = detail !== 'full';
-  return compactValue(authority, {
-    maxDepth: summary ? 4 : 7,
-    textLimit: summary ? 500 : 4000,
-    arrayLimit: summary ? 12 : 100,
-  });
-}
-
-function fitEnvelope(authority, detail, digest) {
-  const limit = detail === 'full' ? FULL_LIMIT : SUMMARY_LIMIT;
-  let envelope = presentation(authority, detail);
-  let output = { schema_version: '1.0', digest, detail, envelope };
-  if (Buffer.byteLength(JSON.stringify(output)) <= limit) return output;
-  envelope = {
-    ...envelope,
-    evidence: (envelope.evidence || []).slice(0, detail === 'full' ? 30 : 6),
-    decisions: (envelope.decisions || []).slice(0, detail === 'full' ? 30 : 8),
-    checkpoints: (envelope.checkpoints || []).slice(0, detail === 'full' ? 20 : 8),
-    cursors: {
-      evidence: authority.evidence.length > (detail === 'full' ? 30 : 6)
-        ? { available: authority.evidence.length, action: 'ultra.context full with narrower scope' }
-        : null,
-      decisions: authority.decisions.length > (detail === 'full' ? 30 : 8)
-        ? { available: authority.decisions.length, action: 'ultra.context full with narrower scope' }
-        : null,
-    },
-  };
-  output = { schema_version: '1.0', digest, detail, envelope };
-  if (Buffer.byteLength(JSON.stringify(output)) <= limit) return output;
-  envelope = compactValue(envelope, {
-    maxDepth: 4,
-    textLimit: detail === 'full' ? 1000 : 240,
-    arrayLimit: detail === 'full' ? 20 : 6,
-  });
-  output = { schema_version: '1.0', digest, detail, envelope };
-  if (Buffer.byteLength(JSON.stringify(output)) > limit) {
-    const error = new Error(`context envelope exceeds ${limit} byte limit after compaction`);
-    error.code = 'CONTEXT_ENVELOPE_LIMIT_EXCEEDED';
-    throw error;
-  }
-  return output;
-}
-
-function buildEnvelope(db, input = {}, options = {}) {
-  const authority = authorityPayload(db, input, options);
-  const digest = canonical.digest(authority);
-  const output = fitEnvelope(authority, input.detail || 'summary', digest);
-  output.bytes = Buffer.byteLength(JSON.stringify(output));
-  return output;
-}
-
-function contextArtifactPath(scope, id) {
-  if (scope.task) return `.ultra/.runtime/projections/contexts/${id}.json`;
-  if (scope.change) return `${scope.change.artifact_root}/contexts/${id}.json`;
-  return `.ultra/.runtime/projections/contexts/${id}.json`;
-}
-
-function readEnvelope(db, id, { rootDir = process.cwd() } = {}) {
-  const row = db.prepare('SELECT * FROM context_envelopes WHERE id = ?').get(id);
-  if (!row) {
-    throw new ContextEnvelopeError(
-      'CONTEXT_ENVELOPE_NOT_FOUND',
-      `Context Envelope not found: ${id}`,
-    );
-  }
-  const read = readStableProjectFile(rootDir, row.artifact_path, { encoding: 'utf8' });
-  if (!row.file_digest || read.digest !== row.file_digest) {
-    throw new ContextEnvelopeError(
-      'CONTEXT_ENVELOPE_FILE_DRIFT',
-      `Context Envelope bytes no longer match ${id}`,
-      {
-        path: row.artifact_path,
-        expected: row.file_digest || null,
-        actual: read.digest,
-      },
-    );
-  }
-  let document;
-  try {
-    document = JSON.parse(read.text);
-  } catch (cause) {
-    throw new ContextEnvelopeError(
-      'CONTEXT_ENVELOPE_INVALID',
-      `Context Envelope is not valid JSON: ${row.artifact_path}`,
-      { cause: cause.message },
-    );
-  }
-  const storedPayload = parseJson(row.payload_json, null);
-  if (!storedPayload
-      || document.schema_version !== '1.0'
-      || document.detail !== 'full'
-      || document.digest !== row.digest
-      || canonical.canonicalJson(document.envelope)
-        !== canonical.canonicalJson(storedPayload)) {
-    throw new ContextEnvelopeError(
-      'CONTEXT_ENVELOPE_DIGEST_MISMATCH',
-      `Context Envelope authority does not match its database record: ${id}`,
-      { path: row.artifact_path },
-    );
-  }
-  return {
-    id: row.id,
-    stage: row.stage,
-    scope_type: row.scope_type,
-    scope_id: row.scope_id,
-    digest: row.digest,
-    file_digest: row.file_digest,
-    artifact_path: row.artifact_path,
-    document,
-  };
-}
-
-function persistEnvelope(db, input = {}, options = {}) {
-  const full = buildEnvelope(db, { ...input, detail: 'full' }, options);
-  const existing = db.prepare(
-    'SELECT * FROM context_envelopes WHERE digest = ?',
-  ).get(full.digest);
-  if (existing) {
-    readEnvelope(db, existing.id, options);
-    return {
-      id: existing.id,
-      digest: existing.digest,
-      artifact_path: existing.artifact_path,
-      stage: existing.stage,
-      scope_type: existing.scope_type,
-      scope_id: existing.scope_id,
-      file_digest: existing.file_digest,
-    };
-  }
-  const scope = resolvedScope(db, input);
-  const id = `context-${full.digest.slice(0, 24)}`;
-  const artifactPath = contextArtifactPath(scope, id);
-  const rootDir = options.rootDir || process.cwd();
-  const snapshot = snapshotManagedFile(rootDir, artifactPath);
-  const published = writeManagedJson(rootDir, artifactPath, full);
-  try {
-    ops.tx(db, () => {
-      db.prepare(
-        `INSERT INTO context_envelopes
-         (id, stage, scope_type, scope_id, digest, file_digest, payload_json, artifact_path)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
-      ).run(
-        id,
-        input.stage || 'project',
-        scope.type,
-        scope.id,
-        full.digest,
-        published.digest,
-        JSON.stringify(full.envelope),
-        artifactPath,
-      );
-      if (!artifactPath.startsWith('.ultra/.runtime/')) {
-        artifactRegistry.recordArtifactInTx(db, {
-          id: `artifact-${id}`,
-          owner_type: scope.change ? 'change' : (scope.baseline ? 'baseline' : 'project'),
-          owner_id: scope.change?.id || scope.baseline?.id || 'project',
-          kind: 'context_envelope',
-          path: artifactPath,
-          content_digest: published.digest,
-          source_refs: [
-            ...(scope.change
-              ? [{ type: 'change', id: scope.change.id, relation: 'compiled_from' }]
-              : []),
-            ...(scope.task
-              ? [{ type: 'task', id: scope.task.id, relation: 'compiled_from_task_contract' }]
-              : []),
-            ...(scope.baseline && !scope.change
-              ? [{ type: 'baseline', id: scope.baseline.id, relation: 'compiled_from' }]
-              : []),
-          ],
-          consumer_refs: [{
-            type: 'external',
-            id: 'ultra-context-consumer',
-            relation: 'consumed_by',
-          }],
-          provenance: {
-            writer: 'context-envelope',
-            envelope_digest: full.digest,
-            stage: input.stage || 'project',
-          },
-          metadata: {
-            envelope_id: id,
-            semantic_digest: full.digest,
-          },
-        }, { rootDir });
-      }
-    });
-  } catch (error) {
-    try {
-      restoreManagedFile(rootDir, snapshot);
-    } catch (rollbackError) {
-      throw new ContextEnvelopeError(
-        'STATE_CORRUPT',
-        'Context Envelope publication failed and its managed file could not be restored',
-        {
-          cause: error.code || error.message,
-          rollback: rollbackError.code || rollbackError.message,
-          path: artifactPath,
-        },
-      );
-    }
-    throw error;
-  }
-  return {
-    id,
-    digest: full.digest,
-    artifact_path: artifactPath,
-    stage: input.stage || 'project',
-    scope_type: scope.type,
-    scope_id: scope.id,
-    file_digest: published.digest,
-  };
-}
-
-module.exports = {
-  ContextEnvelopeError,
-  SUMMARY_LIMIT,
-  FULL_LIMIT,
-  buildEnvelope,
-  persistEnvelope,
-  readEnvelope,
-};