ultra-builder-pro-cli 0.25.1 → 0.26.0

package/ultra-tools/commands/system.cjs

@@ -1,498 +0,0 @@
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-const Database = require('better-sqlite3');
-
-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 runtimePaths = require('../../mcp-server/lib/runtime-paths.cjs');
-
-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/.runtime/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 = runtimePaths.ensureRuntimeState(rootDir).stateDbPath;
-  const state = inspectSqliteSnapshot(statePath);
-  if (!state.exists) {
-    throw new SystemCommandError(
-      'STATE_DB_MISSING',
-      `.ultra/.runtime/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 resolveThroughExistingAncestor(candidate) {
-  const missing = [];
-  let current = path.resolve(candidate);
-  while (!fs.existsSync(current)) {
-    const parent = path.dirname(current);
-    if (parent === current) return path.resolve(candidate);
-    missing.unshift(path.basename(current));
-    current = parent;
-  }
-  return path.join(fs.realpathSync(current), ...missing);
-}
-
-function managedBackup(rootDir, candidate) {
-  if (!candidate) throw new SystemCommandError('VALIDATION_ERROR', '--backup is required');
-  const runtimeBackupRoot = runtimePaths.pathsFor(rootDir).backupsDir;
-  const legacyBackupRoot = path.join(rootDir, '.ultra', 'backups');
-  const backupRoots = [runtimeBackupRoot, legacyBackupRoot].filter((entry) => fs.existsSync(entry));
-  if (backupRoots.length === 0) {
-    throw new SystemCommandError(
-      'BACKUP_NOT_FOUND',
-      `managed backup directory does not exist: ${runtimeBackupRoot}`,
-    );
-  }
-  let requested = resolveThroughExistingAncestor(
-    path.isAbsolute(candidate) ? candidate : path.resolve(rootDir, candidate),
-  );
-  const legacyPrefix = `${resolveThroughExistingAncestor(legacyBackupRoot)}${path.sep}`;
-  if (!fs.existsSync(requested) && requested.startsWith(legacyPrefix)) {
-    requested = path.join(runtimeBackupRoot, path.relative(legacyBackupRoot, requested));
-  }
-  let resolved;
-  try { resolved = fs.realpathSync(requested); }
-  catch {
-    throw new SystemCommandError('BACKUP_NOT_FOUND', `backup does not exist: ${requested}`);
-  }
-  const managed = backupRoots.some((entry) => {
-    const resolvedRoot = fs.realpathSync(entry);
-    return resolved.startsWith(`${resolvedRoot}${path.sep}`);
-  });
-  if (!managed) {
-    throw new SystemCommandError(
-      'BACKUP_OUTSIDE_MANAGED_ROOT',
-      `backup must be inside ${runtimeBackupRoot}`,
-    );
-  }
-  if (!fs.statSync(resolved).isFile()) {
-    throw new SystemCommandError('BACKUP_NOT_FOUND', `backup is not a file: ${resolved}`);
-  }
-  for (const suffix of ['', '-wal', '-shm']) {
-    const member = `${resolved}${suffix}`;
-    if (!fs.existsSync(member)) continue;
-    const stat = fs.lstatSync(member);
-    if (!stat.isFile() || stat.isSymbolicLink()) {
-      throw new SystemCommandError(
-        'BACKUP_INVALID',
-        `backup snapshot member must be a regular file: ${member}`,
-      );
-    }
-  }
-  const inspection = inspectSqliteSnapshot(resolved);
-  if (!inspection.valid) {
-    throw new SystemCommandError(
-      'BACKUP_INVALID',
-      `backup is not a verified Ultra SQLite snapshot: ${resolved}`,
-    );
-  }
-  return resolved;
-}
-
-function createRecoveryDir(rootDir, prefix) {
-  const dir = path.join(runtimePaths.pathsFor(rootDir).backupsDir, `${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;
-}
-
-function copySnapshot(source, target) {
-  const copied = [];
-  try {
-    for (const suffix of ['', '-wal', '-shm']) {
-      const member = `${source}${suffix}`;
-      if (!fs.existsSync(member)) continue;
-      const staged = `${target}${suffix}`;
-      fs.copyFileSync(member, staged, fs.constants.COPYFILE_EXCL);
-      copied.push(staged);
-    }
-    const inspection = inspectSqlite(target);
-    if (!inspection.valid) {
-      throw new SystemCommandError(
-        'BACKUP_INVALID',
-        `staged backup is not a verified Ultra SQLite snapshot: ${source}`,
-      );
-    }
-    return copied;
-  } catch (error) {
-    for (const file of copied) {
-      try { fs.rmSync(file, { force: true }); } catch { /* best effort */ }
-    }
-    throw error;
-  }
-}
-
-function installSnapshot(staging, activeState) {
-  const installed = [];
-  try {
-    // The main DB is the authority completion marker, so publish it last.
-    for (const suffix of ['-wal', '-shm', '']) {
-      const source = `${staging}${suffix}`;
-      if (!fs.existsSync(source)) continue;
-      const target = `${activeState}${suffix}`;
-      fs.renameSync(source, target);
-      installed.push(target);
-    }
-    return installed;
-  } catch (error) {
-    for (const target of installed.reverse()) {
-      try { fs.rmSync(target, { force: true }); } catch { /* rollback continues */ }
-    }
-    throw error;
-  }
-}
-
-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;
-  let installed = [];
-  try {
-    activeState = ensureCorruptState(rootDir);
-    const sourceBackup = managedBackup(rootDir, options.backup);
-    const recoveryDir = createRecoveryDir(rootDir, 'restore');
-    staging = path.join(runtimePaths.pathsFor(rootDir).runtimeDir, `.state.restore-${stamp()}.db`);
-    copySnapshot(sourceBackup, staging);
-    moveStateFiles(activeState, recoveryDir, moved);
-    installed = installSnapshot(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,
-        recovery_guidance: 'Run ultra-tools system doctor, then ultra-init to inspect baseline readiness.',
-      },
-    });
-    return 0;
-  } catch (error) {
-    if (staging) {
-      for (const suffix of ['', '-wal', '-shm']) {
-        try { fs.rmSync(`${staging}${suffix}`, { force: true }); } catch { /* rollback continues */ }
-      }
-    }
-    for (const target of installed.reverse()) {
-      try { fs.rmSync(target, { 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,
-        recovery_guidance: 'Inspect the preserved evidence, run explicit adoption research, record the brownfield baseline, and obtain owner approval before convergence.',
-      },
-    });
-    return 0;
-  } catch (error) {
-    const rollbackErrors = [];
-    if (moved.length > 0) {
-      const generatedState = activeState || runtimePaths.pathsFor(rootDir).stateDbPath;
-      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')) {
-    process.stdout.write(USAGE);
-    return 0;
-  }
-  if (unknown.length > 0) {
-    emit({ ok: false, error: { code: 'VALIDATION_ERROR', message: `unknown system doctor flag: ${unknown[0]}` } });
-    return 1;
-  }
-  const rootDir = process.cwd();
-  const repair = args.includes('--repair');
-  const dbPath = repair
-    ? runtimePaths.ensureRuntimeState(rootDir).stateDbPath
-    : runtimePaths.locateStateDb(rootDir);
-  if (!fs.existsSync(dbPath)) {
-    emit({
-      ok: false,
-      error: {
-        code: 'STATE_DB_MISSING',
-        message: `.ultra/.runtime/state.db not found under ${rootDir}`,
-      },
-    });
-    return 2;
-  }
-  let db;
-  try {
-    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) {
-    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 {
-    if (db) closeStateDb(db);
-  }
-}
-
-async function dispatch(args) {
-  const [verb, ...rest] = args;
-  if (!verb || verb === '-h' || verb === '--help') {
-    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;
-  }
-  return dispatchDoctor(rest);
-}
-
-module.exports = {
-  USAGE,
-  RESTORE_CONFIRMATION,
-  REBASELINE_CONFIRMATION,
-  dispatch,
-  dispatchDoctor,
-  dispatchRestore,
-  dispatchRebaseline,
-};

package/ultra-tools/commands/task.cjs

@@ -1,105 +0,0 @@
-'use strict';
-
-// CLI dispatcher for the only task-family maintenance command. Runtime task
-// reads and writes intentionally remain MCP-only so a Host cannot silently
-// bypass the state-authority and projection-conflict gates.
-
-const { initProject, InitProjectError } = require('../../mcp-server/lib/init-project.cjs');
-
-const USAGE = `ultra-tools task <verb> [flags]
-
-VERBS:
-  init-project  Initialize or adopt a project with authoritative Ultra state
-
-FLAGS (init-project):
-  --target-dir <path>       target project root (default: cwd)
-  --project-name <name>     project name (required)
-  --project-type <type>     web | api | cli | fullstack | other
-  --stack <stack>           tech stack descriptor (comma-separated ok)
-  --mode <mode>             auto | greenfield | brownfield (default: auto)
-  --git-mode <mode>         auto | initialize | skip (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
-`;
-
-function emit(envelope) {
-  process.stdout.write(`${JSON.stringify(envelope)}\n`);
-}
-
-function parseInitFlags(args) {
-  const flags = { _: [], scope: [] };
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    switch (a) {
-      case '--target-dir':       flags.target_dir       = args[++i]; break;
-      case '--project-name':     flags.project_name     = args[++i]; break;
-      case '--project-type':     flags.project_type     = args[++i]; break;
-      case '--stack':            flags.stack            = args[++i]; break;
-      case '--mode':             flags.mode             = args[++i]; break;
-      case '--git-mode':         flags.git_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;
-      case '-h': case '--help':  flags.help = true; break;
-      default:                   flags._.push(a);
-    }
-  }
-  return flags;
-}
-
-function dispatchInitProject(rawArgs) {
-  const flags = parseInitFlags(rawArgs);
-  if (flags.help) {
-    process.stdout.write(USAGE);
-    return 0;
-  }
-  if (!flags.project_name) {
-    emit({ ok: false, error: { code: 'VALIDATION_ERROR', message: 'missing required flag: --project-name' } });
-    return 1;
-  }
-  const input = {
-    target_dir: flags.target_dir || process.cwd(),
-    project_name: flags.project_name,
-    project_type: flags.project_type,
-    stack: flags.stack,
-    mode: flags.mode || 'auto',
-    git_mode: flags.git_mode || 'auto',
-    scope: flags.scope.length > 0 ? flags.scope : undefined,
-    resume: !!flags.resume,
-    overwrite: !!flags.overwrite,
-    source_template: flags.source_template,
-  };
-  try {
-    const data = initProject(input);
-    emit({ ok: true, data });
-    return 0;
-  } catch (err) {
-    if (err instanceof InitProjectError) {
-      emit({ ok: false, error: { code: err.code, message: err.message, retriable: !!err.retriable } });
-      return err.code === 'VALIDATION_ERROR' ? 1 : 2;
-    }
-    emit({ ok: false, error: { code: 'UNKNOWN', message: err.message, retriable: false } });
-    return 2;
-  }
-}
-
-function dispatch(args) {
-  const [verb, ...rest] = args;
-  if (!verb || verb === '-h' || verb === '--help') {
-    process.stdout.write(USAGE);
-    return 0;
-  }
-  switch (verb) {
-    case 'init-project': return dispatchInitProject(rest);
-    default:
-      emit({ ok: false, error: { code: 'UNKNOWN_VERB', message: `unknown task verb '${verb}'; only init-project is supported by the maintenance CLI` } });
-      return 1;
-  }
-}
-
-module.exports = { dispatch, dispatchInitProject, USAGE };