ultra-builder-pro-cli 0.12.1 → 0.14.0

package/ultra-tools/commands/status.cjs

@@ -71,17 +71,26 @@ function buildCostPanel(db, { since = null, limit = 3, rootDir = process.cwd() }
   const total_cost_usd = by_runtime.reduce((acc, r) => acc + (r.cost_usd || 0), 0);
   const baselineHealth = baselines.inspectBaseline(db, { rootDir });
   const current = baselineHealth.baseline;
+  const baselineStatus = current?.status
+    || (baselineHealth.blockers.includes('BASELINE_SCHEMA_MIGRATION_REQUIRED')
+      ? 'migration_required' : 'missing');
+  const baseline = {
+    id: current?.id || null,
+    mode: current?.mode || null,
+    status: baselineStatus,
+    health: baselineHealth.status,
+    repository_revision: current?.repository_revision || null,
+    blockers: baselineHealth.blockers,
+    warnings: baselineHealth.warnings,
+  };
+  if (current) {
+    baseline.repository_branch = current.repository_branch || null;
+    baseline.worktree_state = current.worktree_state || 'unavailable';
+    baseline.gaps = baselines.summarizeGaps(current.gaps);
+  }
   return {
     period: { since: since || 'all-time' },
-    baseline: {
-      id: current?.id || null,
-      mode: current?.mode || null,
-      status: current?.status || 'missing',
-      health: baselineHealth.status,
-      repository_revision: current?.repository_revision || null,
-      blockers: baselineHealth.blockers,
-      warnings: baselineHealth.warnings,
-    },
+    baseline,
     by_runtime,
     top_tasks,
     total_cost_usd,

package/ultra-tools/commands/system.cjs

@@ -2,16 +2,323 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const Database = require('better-sqlite3');
 
-const { openStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
+const { initStateDb, openStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
+const { initProject } = require('../../mcp-server/lib/init-project.cjs');
 const doctor = require('../../mcp-server/lib/doctor.cjs');
 
-const USAGE = `ultra-tools system doctor [--repair]\n`;
+const RESTORE_CONFIRMATION = 'REPLACE_CORRUPT_ULTRA_STATE';
+const REBASELINE_CONFIRMATION = 'REBASELINE_CORRUPT_ULTRA_STATE';
+const USAGE = `ultra-tools system <verb> [options]
+
+VERBS:
+  doctor [--repair]
+  restore --backup <.ultra/backups/...db> --confirm ${RESTORE_CONFIRMATION}
+  rebaseline --project-name <name> [--scope <path>] --confirm ${REBASELINE_CONFIRMATION}
+`;
+
+class SystemCommandError extends Error {
+  constructor(code, message, exitCode = 1) {
+    super(message);
+    this.name = 'SystemCommandError';
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}
 
 function emit(envelope) {
   process.stdout.write(`${JSON.stringify(envelope)}\n`);
 }
 
+function stamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function parseOptions(args, allowed) {
+  const options = { scope: [] };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
+    const [flag, inline] = arg.startsWith('--') && arg.includes('=')
+      ? arg.split(/=(.*)/s, 2)
+      : [arg, null];
+    const name = flag.startsWith('--') ? flag.slice(2) : null;
+    if (!name || !allowed.has(name)) {
+      throw new SystemCommandError('VALIDATION_ERROR', `unknown system option: ${arg}`);
+    }
+    const value = inline === null ? args[index += 1] : inline;
+    if (value === undefined || String(value).length === 0 || String(value).startsWith('--')) {
+      throw new SystemCommandError('VALIDATION_ERROR', `${flag} requires a value`);
+    }
+    if (name === 'scope') options.scope.push(value);
+    else options[name.replaceAll('-', '_')] = value;
+  }
+  return options;
+}
+
+function inspectSqlite(file) {
+  if (!fs.existsSync(file)) return { exists: false, valid: false, corrupt: false };
+  let db;
+  try {
+    db = new Database(file, { readonly: true, fileMustExist: true });
+    const integrity = db.pragma('integrity_check', { simple: true });
+    const hasSchema = Boolean(db.prepare(
+      "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'schema_version'",
+    ).get());
+    return { exists: true, valid: integrity === 'ok' && hasSchema, corrupt: false, integrity, hasSchema };
+  } catch (error) {
+    const corrupt = /not a database|database disk image is malformed|file is encrypted|malformed/i
+      .test(String(error.message || ''));
+    if (!corrupt) throw error;
+    return { exists: true, valid: false, corrupt: true, error: error.message };
+  } finally {
+    closeStateDb(db);
+  }
+}
+
+function inspectSqliteSnapshot(file) {
+  if (!fs.existsSync(file)) return { exists: false, valid: false, corrupt: false };
+  const snapshotDir = fs.mkdtempSync(path.join(path.dirname(file), '.state-inspect-'));
+  const snapshotPath = path.join(snapshotDir, 'state.db');
+  try {
+    for (const suffix of ['', '-wal', '-shm']) {
+      const source = `${file}${suffix}`;
+      if (fs.existsSync(source)) fs.copyFileSync(source, `${snapshotPath}${suffix}`);
+    }
+    return inspectSqlite(snapshotPath);
+  } finally {
+    fs.rmSync(snapshotDir, { recursive: true, force: true });
+  }
+}
+
+function ensureCorruptState(rootDir) {
+  const statePath = path.join(rootDir, '.ultra', 'state.db');
+  const state = inspectSqliteSnapshot(statePath);
+  if (!state.exists) throw new SystemCommandError('STATE_DB_MISSING', `.ultra/state.db not found under ${rootDir}`, 2);
+  if (!state.corrupt) {
+    throw new SystemCommandError(
+      'STATE_DB_NOT_CORRUPT',
+      'state.db is readable; use system doctor --repair for supported recovery instead of replacing authority',
+      2,
+    );
+  }
+  return statePath;
+}
+
+function managedBackup(rootDir, candidate) {
+  if (!candidate) throw new SystemCommandError('VALIDATION_ERROR', '--backup is required');
+  const backupRoot = path.join(rootDir, '.ultra', 'backups');
+  if (!fs.existsSync(backupRoot)) {
+    throw new SystemCommandError('BACKUP_NOT_FOUND', `managed backup directory does not exist: ${backupRoot}`);
+  }
+  const resolvedRoot = fs.realpathSync(backupRoot);
+  const requested = path.isAbsolute(candidate) ? candidate : path.resolve(rootDir, candidate);
+  let resolved;
+  try { resolved = fs.realpathSync(requested); }
+  catch {
+    throw new SystemCommandError('BACKUP_NOT_FOUND', `backup does not exist: ${requested}`);
+  }
+  if (!resolved.startsWith(`${resolvedRoot}${path.sep}`)) {
+    throw new SystemCommandError(
+      'BACKUP_OUTSIDE_MANAGED_ROOT',
+      `backup must be inside ${backupRoot}`,
+    );
+  }
+  if (!fs.statSync(resolved).isFile()) {
+    throw new SystemCommandError('BACKUP_NOT_FOUND', `backup is not a file: ${resolved}`);
+  }
+  const inspection = inspectSqlite(resolved);
+  if (!inspection.valid) {
+    throw new SystemCommandError('BACKUP_INVALID', `backup is not a verified Ultra SQLite database: ${resolved}`);
+  }
+  return resolved;
+}
+
+function createRecoveryDir(rootDir, prefix) {
+  const dir = path.join(rootDir, '.ultra', 'backups', `${prefix}-${stamp()}`);
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  fs.mkdirSync(dir, { recursive: false });
+  return dir;
+}
+
+function moveStateFiles(statePath, recoveryDir, moved = []) {
+  for (const suffix of ['', '-wal', '-shm']) {
+    const source = `${statePath}${suffix}`;
+    if (!fs.existsSync(source)) continue;
+    const target = path.join(recoveryDir, `state.db${suffix}`);
+    fs.renameSync(source, target);
+    moved.push({ source, target });
+  }
+  return moved;
+}
+
+function restoreMovedFiles(moved) {
+  const errors = [];
+  for (const item of moved) {
+    try {
+      if (fs.existsSync(item.source)) fs.rmSync(item.source, { force: true });
+    } catch (error) {
+      errors.push(`replacement cleanup failed for ${item.source}: ${error.message}`);
+    }
+  }
+  for (const item of moved) {
+    try {
+      if (fs.existsSync(item.target)) fs.renameSync(item.target, item.source);
+    } catch (error) {
+      errors.push(`evidence restore failed for ${item.source}: ${error.message}`);
+    }
+  }
+  return errors;
+}
+
+async function dispatchRestore(args) {
+  let options;
+  try { options = parseOptions(args, new Set(['backup', 'confirm'])); }
+  catch (error) { emit({ ok: false, error: { code: error.code, message: error.message } }); return error.exitCode || 1; }
+  if (options.help) { process.stdout.write(USAGE); return 0; }
+  if (options.confirm !== RESTORE_CONFIRMATION) {
+    emit({
+      ok: false,
+      error: {
+        code: 'CONFIRMATION_REQUIRED',
+        message: `restore requires --confirm ${RESTORE_CONFIRMATION}`,
+      },
+    });
+    return 1;
+  }
+  const rootDir = process.cwd();
+  let moved = [];
+  let activeState;
+  let staging;
+  try {
+    activeState = ensureCorruptState(rootDir);
+    const sourceBackup = managedBackup(rootDir, options.backup);
+    const recoveryDir = createRecoveryDir(rootDir, 'restore');
+    staging = path.join(rootDir, '.ultra', `.state.restore-${stamp()}.db`);
+    fs.copyFileSync(sourceBackup, staging, fs.constants.COPYFILE_EXCL);
+    moveStateFiles(activeState, recoveryDir, moved);
+    fs.renameSync(staging, activeState);
+    const initialized = initStateDb(activeState);
+    closeStateDb(initialized.db);
+    emit({
+      ok: true,
+      data: {
+        status: 'restored',
+        source_backup: sourceBackup,
+        recovery_backup_dir: recoveryDir,
+        quarantined_state_path: path.join(recoveryDir, 'state.db'),
+        schema_version: initialized.schema_version,
+        schema_migration_backup_path: initialized.backup_path || null,
+        next_action: 'Run ultra-tools system doctor, then ultra-init to inspect baseline readiness.',
+      },
+    });
+    return 0;
+  } catch (error) {
+    if (staging) {
+      try { fs.rmSync(staging, { force: true }); } catch { /* rollback continues */ }
+    }
+    const rollbackErrors = activeState ? restoreMovedFiles(moved) : [];
+    emit({
+      ok: false,
+      error: {
+        code: error instanceof SystemCommandError ? error.code : 'STATE_RESTORE_FAILED',
+        message: `${error.message}${rollbackErrors.length ? `; rollback errors: ${rollbackErrors.join('; ')}` : ''}`,
+      },
+    });
+    return error.exitCode || 2;
+  }
+}
+
+async function dispatchRebaseline(args) {
+  let options;
+  try { options = parseOptions(args, new Set(['project-name', 'scope', 'confirm'])); }
+  catch (error) { emit({ ok: false, error: { code: error.code, message: error.message } }); return error.exitCode || 1; }
+  if (options.help) { process.stdout.write(USAGE); return 0; }
+  if (options.confirm !== REBASELINE_CONFIRMATION) {
+    emit({
+      ok: false,
+      error: {
+        code: 'CONFIRMATION_REQUIRED',
+        message: `rebaseline requires --confirm ${REBASELINE_CONFIRMATION}`,
+      },
+    });
+    return 1;
+  }
+  if (!options.project_name) {
+    emit({ ok: false, error: { code: 'VALIDATION_ERROR', message: '--project-name is required' } });
+    return 1;
+  }
+  const rootDir = process.cwd();
+  let moved = [];
+  let projectionMove = null;
+  let activeState;
+  try {
+    activeState = ensureCorruptState(rootDir);
+    const recoveryDir = createRecoveryDir(rootDir, 'rebaseline');
+    moveStateFiles(activeState, recoveryDir, moved);
+    const tasksDir = path.join(rootDir, '.ultra', 'tasks');
+    if (fs.existsSync(tasksDir)) {
+      const legacyTasksDir = path.join(recoveryDir, 'tasks');
+      projectionMove = { source: tasksDir, target: legacyTasksDir };
+      fs.renameSync(tasksDir, legacyTasksDir);
+    }
+    const initialized = initProject({
+      target_dir: rootDir,
+      project_name: options.project_name,
+      mode: 'brownfield',
+      scope: options.scope.length > 0 ? options.scope : undefined,
+      resume: true,
+    });
+    emit({
+      ok: true,
+      data: {
+        status: 'rebaseline_started',
+        recovery_backup_dir: recoveryDir,
+        quarantined_state_path: path.join(recoveryDir, 'state.db'),
+        legacy_projection_path: projectionMove
+          ? path.join(projectionMove.target, 'tasks.json')
+          : null,
+        baseline: initialized.baseline,
+        copied_files: initialized.copied_files,
+        next_action: 'Inspect the preserved evidence, record the brownfield baseline, and obtain owner approval before convergence.',
+      },
+    });
+    return 0;
+  } catch (error) {
+    const rollbackErrors = [];
+    if (moved.length > 0) {
+      const generatedState = activeState || path.join(rootDir, '.ultra', 'state.db');
+      for (const suffix of ['', '-wal', '-shm']) {
+        try { fs.rmSync(`${generatedState}${suffix}`, { force: true }); }
+        catch (rollbackError) { rollbackErrors.push(`generated state cleanup failed: ${rollbackError.message}`); }
+      }
+    }
+    if (projectionMove) {
+      try {
+        if (fs.existsSync(projectionMove.source)) {
+          fs.rmSync(projectionMove.source, { recursive: true, force: true });
+        }
+        if (fs.existsSync(projectionMove.target)) fs.renameSync(projectionMove.target, projectionMove.source);
+      } catch (rollbackError) {
+        rollbackErrors.push(`task projection restore failed: ${rollbackError.message}`);
+      }
+    }
+    rollbackErrors.push(...restoreMovedFiles(moved));
+    emit({
+      ok: false,
+      error: {
+        code: error.code || 'STATE_REBASELINE_FAILED',
+        message: `${error.message}${rollbackErrors.length ? `; rollback errors: ${rollbackErrors.join('; ')}` : ''}`,
+      },
+    });
+    return error.exitCode || 2;
+  }
+}
+
 async function dispatchDoctor(args) {
   const unknown = args.filter((arg) => !['--repair', '-h', '--help'].includes(arg));
   if (args.includes('-h') || args.includes('--help')) {
@@ -28,16 +335,33 @@ async function dispatchDoctor(args) {
     emit({ ok: false, error: { code: 'STATE_DB_MISSING', message: `.ultra/state.db not found under ${rootDir}` } });
     return 2;
   }
-  const db = openStateDb(dbPath);
+  let db;
   try {
+    const repair = args.includes('--repair');
+    const initialized = repair ? initStateDb(dbPath) : null;
+    db = initialized ? initialized.db : openStateDb(dbPath);
     const data = await doctor.runDoctor(db, { rootDir, repair: args.includes('--repair') });
+    if (initialized) {
+      data.schema_version = initialized.schema_version;
+      data.schema_migration_backup_path = initialized.backup_path || null;
+    }
     emit({ ok: true, data });
     return data.status === 'healthy' ? 0 : 2;
   } catch (error) {
-    emit({ ok: false, error: { code: error.code || 'STATE_DB_ERROR', message: error.message } });
+    const corrupt = /not a database|database disk image is malformed|file is encrypted or is not a database|malformed/i
+      .test(String(error.message || ''));
+    emit({
+      ok: false,
+      error: {
+        code: corrupt ? 'STATE_DB_CORRUPT' : (error.code || 'STATE_DB_ERROR'),
+        message: corrupt
+          ? `state.db is corrupt; after owner approval use system restore with a verified managed backup or system rebaseline to quarantine and rebuild authority: ${error.message}`
+          : error.message,
+      },
+    });
     return 2;
   } finally {
-    closeStateDb(db);
+    if (db) closeStateDb(db);
   }
 }
 
@@ -47,6 +371,8 @@ async function dispatch(args) {
     process.stdout.write(USAGE);
     return 0;
   }
+  if (verb === 'restore') return dispatchRestore(rest);
+  if (verb === 'rebaseline') return dispatchRebaseline(rest);
   if (verb !== 'doctor') {
     emit({ ok: false, error: { code: 'UNKNOWN_VERB', message: `unknown system verb: ${verb}` } });
     return 1;
@@ -54,4 +380,12 @@ async function dispatch(args) {
   return dispatchDoctor(rest);
 }
 
-module.exports = { USAGE, dispatch, dispatchDoctor };
+module.exports = {
+  USAGE,
+  RESTORE_CONFIRMATION,
+  REBASELINE_CONFIRMATION,
+  dispatch,
+  dispatchDoctor,
+  dispatchRestore,
+  dispatchRebaseline,
+};

package/ultra-tools/commands/task.cjs

@@ -17,6 +17,8 @@ FLAGS (init-project):
   --project-type <type>     web | api | cli | fullstack | other
   --stack <stack>           tech stack descriptor (comma-separated ok)
   --mode <mode>             auto | greenfield | brownfield (default: auto)
+  --scope <path>            baseline scope; repeat for multiple paths (default: .)
+  --resume                  preserve existing .ultra/ and install only missing assets
   --overwrite               replace existing .ultra/ (backup created)
   --source-template <path>  override bundled template source
   -h, --help                show this message
@@ -27,7 +29,7 @@ function emit(envelope) {
 }
 
 function parseInitFlags(args) {
-  const flags = { _: [] };
+  const flags = { _: [], scope: [] };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     switch (a) {
@@ -36,6 +38,8 @@ function parseInitFlags(args) {
       case '--project-type':     flags.project_type     = args[++i]; break;
       case '--stack':            flags.stack            = args[++i]; break;
       case '--mode':             flags.mode             = args[++i]; break;
+      case '--scope':            flags.scope.push(args[++i]); break;
+      case '--resume':           flags.resume            = true; break;
       case '--source-template':  flags.source_template  = args[++i]; break;
       case '--overwrite':        flags.overwrite        = true; break;
       case '--no-overwrite':     flags.overwrite        = false; break;
@@ -62,6 +66,8 @@ function dispatchInitProject(rawArgs) {
     project_type: flags.project_type,
     stack: flags.stack,
     mode: flags.mode || 'auto',
+    scope: flags.scope.length > 0 ? flags.scope : undefined,
+    resume: !!flags.resume,
     overwrite: !!flags.overwrite,
     source_template: flags.source_template,
   };

package/ultra-tools/status-command.test.cjs

@@ -86,6 +86,35 @@ test('status exposes an in-progress brownfield baseline from authoritative state
   } finally { teardown(dir, db); }
 });
 
+test('status reports a legacy schema as migration-required instead of throwing SQLite errors', () => {
+  const { dir, db } = freshFixture();
+  try {
+    db.exec('DROP TABLE baselines');
+    const out = statusCmd.buildCostPanel(db, { rootDir: dir });
+    assert.equal(out.baseline.status, 'migration_required');
+    assert.deepEqual(out.baseline.blockers, ['BASELINE_SCHEMA_MIGRATION_REQUIRED']);
+    assert.match(statusCmd.renderHuman(out), /migration_required/i);
+  } finally { teardown(dir, db); }
+});
+
+test('status summarizes the authoritative baseline gap ledger', () => {
+  const { dir, db } = freshFixture();
+  try {
+    db.prepare(
+      `INSERT INTO baselines (id, project_name, mode, status, gaps_json)
+       VALUES ('adoption', 'legacy', 'brownfield', 'adopting', ?)`,
+    ).run(JSON.stringify([
+      { id: 'blocker', category: 'baseline_blocker', status: 'open', blocking: true, summary: 'Missing proof', evidence_refs: [] },
+      { id: 'debt', category: 'technical_debt', status: 'accepted', blocking: false, summary: 'Slow test', evidence_refs: [] },
+    ]));
+    const out = statusCmd.buildCostPanel(db, { rootDir: dir });
+    assert.deepEqual(out.baseline.gaps, {
+      total: 2, open: 1, blocking: 1,
+      by_category: { baseline_blocker: 1, technical_debt: 1 },
+    });
+  } finally { teardown(dir, db); }
+});
+
 test('buildCostPanel: since cutoff in future → all filtered out', () => {
   const { dir, db } = freshFixture();
   try {