ultra-builder-pro-cli 0.5.0

package/ultra-tools/commands/db.cjs

@@ -0,0 +1,175 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { initStateDb, openStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
+
+const DEFAULT_DB_PATH = path.join('.ultra', 'state.db');
+const DEFAULT_BACKUP_DIR = path.join('.ultra', 'backups');
+
+function parseFlags(args) {
+  const flags = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--path') {
+      flags.path = args[++i];
+    } else if (a === '--to') {
+      flags.to = args[++i];
+    } else if (a === '--help' || a === '-h') {
+      flags.help = true;
+    } else {
+      flags._.push(a);
+    }
+  }
+  return flags;
+}
+
+function emit(envelope) {
+  process.stdout.write(`${JSON.stringify(envelope)}\n`);
+}
+
+function dispatch(args) {
+  const [verb, ...rest] = args;
+  const flags = parseFlags(rest);
+
+  if (!verb || flags.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  switch (verb) {
+    case 'init':       return cmdInit(flags);
+    case 'checkpoint': return cmdCheckpoint(flags);
+    case 'vacuum':     return cmdVacuum(flags);
+    case 'integrity':  return cmdIntegrity(flags);
+    case 'backup':     return cmdBackup(flags);
+    default:
+      emit({ ok: false, error: { code: 'UNKNOWN_VERB', message: `unknown db verb '${verb}'; supported: init, checkpoint, vacuum, integrity, backup` } });
+      return 1;
+  }
+}
+
+function cmdInit(flags) {
+  const dbPath = path.resolve(flags.path || DEFAULT_DB_PATH);
+  try {
+    const { db, schema_version, created, tables, path: actualPath } = initStateDb(dbPath);
+    closeStateDb(db);
+    emit({
+      ok: true,
+      data: {
+        path: actualPath,
+        schema_version,
+        created,
+        tables,
+        size_bytes: fs.statSync(actualPath).size,
+      },
+    });
+    return 0;
+  } catch (err) {
+    emit({
+      ok: false,
+      error: {
+        code: 'INIT_FAILED',
+        message: err.message,
+        retriable: false,
+      },
+    });
+    return 2;
+  }
+}
+
+function withOpenDb(flags, fn, errorCode) {
+  const dbPath = path.resolve(flags.path || DEFAULT_DB_PATH);
+  if (!fs.existsSync(dbPath)) {
+    emit({ ok: false, error: { code: 'DB_NOT_FOUND', message: `state.db missing at ${dbPath}; run 'db init' first` } });
+    return 2;
+  }
+  let db;
+  try {
+    db = openStateDb(dbPath);
+    const data = fn(db, dbPath);
+    emit({ ok: true, data: { path: dbPath, ...data } });
+    return 0;
+  } catch (err) {
+    emit({ ok: false, error: { code: errorCode, message: err.message, retriable: false } });
+    return 2;
+  } finally {
+    if (db) closeStateDb(db);
+  }
+}
+
+function cmdCheckpoint(flags) {
+  return withOpenDb(flags, (db) => {
+    const result = db.pragma('wal_checkpoint(TRUNCATE)');
+    // better-sqlite3 returns [{ busy, log, checkpointed }]
+    const row = Array.isArray(result) && result[0] ? result[0] : { busy: 0, log: 0, checkpointed: 0 };
+    return { busy: row.busy, log: row.log, checkpointed: row.checkpointed };
+  }, 'CHECKPOINT_FAILED');
+}
+
+function cmdVacuum(flags) {
+  return withOpenDb(flags, (db) => {
+    const before = db.prepare('SELECT page_count * page_size AS bytes FROM pragma_page_count(), pragma_page_size()').get();
+    db.prepare('VACUUM').run();
+    const after = db.prepare('SELECT page_count * page_size AS bytes FROM pragma_page_count(), pragma_page_size()').get();
+    return { bytes_before: before.bytes, bytes_after: after.bytes, reclaimed_bytes: before.bytes - after.bytes };
+  }, 'VACUUM_FAILED');
+}
+
+function cmdIntegrity(flags) {
+  return withOpenDb(flags, (db) => {
+    const result = db.pragma('integrity_check');
+    const messages = result.map((r) => r.integrity_check);
+    const ok = messages.length === 1 && messages[0] === 'ok';
+    return { integrity_ok: ok, messages };
+  }, 'INTEGRITY_FAILED');
+}
+
+function defaultBackupPath() {
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(DEFAULT_BACKUP_DIR, `state-db-${ts}.db`);
+}
+
+function cmdBackup(flags) {
+  const dbPath = path.resolve(flags.path || DEFAULT_DB_PATH);
+  const targetPath = path.resolve(flags.to || defaultBackupPath());
+  if (!fs.existsSync(dbPath)) {
+    emit({ ok: false, error: { code: 'DB_NOT_FOUND', message: `state.db missing at ${dbPath}` } });
+    return 2;
+  }
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  let db;
+  try {
+    // Flush WAL into the main file so a plain copy captures all committed
+    // writes; fall back to copy-only on a fresh file with no WAL.
+    db = openStateDb(dbPath);
+    db.pragma('wal_checkpoint(TRUNCATE)');
+    closeStateDb(db);
+    db = null;
+    fs.copyFileSync(dbPath, targetPath);
+    const size = fs.statSync(targetPath).size;
+    emit({ ok: true, data: { source: dbPath, target: targetPath, size_bytes: size } });
+    return 0;
+  } catch (err) {
+    emit({ ok: false, error: { code: 'BACKUP_FAILED', message: err.message, retriable: true } });
+    return 2;
+  } finally {
+    if (db) closeStateDb(db);
+  }
+}
+
+const USAGE = `ultra-tools db <verb> [flags]
+
+Verbs (Phase 2):
+  init       [--path <db>]              create or open state.db, apply schema
+  checkpoint [--path <db>]              run PRAGMA wal_checkpoint(TRUNCATE)
+  vacuum     [--path <db>]              run VACUUM and report reclaimed bytes
+  integrity  [--path <db>]              run PRAGMA integrity_check
+  backup     [--path <db>] [--to <out>] online .backup() to a file
+
+Default db: .ultra/state.db
+Default backup: .ultra/backups/state-db-{iso}.db
+`;
+
+module.exports = { dispatch, USAGE, DEFAULT_DB_PATH, DEFAULT_BACKUP_DIR };

package/ultra-tools/commands/legacy-memory.cjs

@@ -0,0 +1,159 @@
+'use strict';
+
+/** Explicit migration boundary for retired Ultra memory stores. */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const Database = require('better-sqlite3');
+
+const CONFIRMATION = 'DELETE_ULTRA_LEGACY_MEMORY';
+
+function tableExists(db, name) {
+  return !!db.prepare("SELECT 1 FROM sqlite_master WHERE type IN ('table', 'view') AND name = ?").get(name);
+}
+
+function inspectLegacy(sourceDir = '.') {
+  const root = path.resolve(sourceDir);
+  const ultra = path.join(root, '.ultra');
+  const hookMemory = path.join(ultra, 'memory');
+  const dbPath = path.join(ultra, 'state.db');
+  let stateMemoryTable = false;
+  let stateMemoryEntries = 0;
+  if (fs.existsSync(dbPath)) {
+    const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    try {
+      stateMemoryTable = tableExists(db, 'memory_entries');
+      if (stateMemoryTable) {
+        stateMemoryEntries = db.prepare('SELECT COUNT(*) AS count FROM memory_entries').get().count;
+      }
+    } finally {
+      db.close();
+    }
+  }
+  return {
+    source_dir: root,
+    hook_memory_dir: fs.existsSync(hookMemory),
+    hook_memory_path: hookMemory,
+    state_db_path: dbPath,
+    state_memory_table: stateMemoryTable,
+    state_memory_entries: stateMemoryEntries,
+  };
+}
+
+function archiveLegacy(sourceDir = '.', { timestamp } = {}) {
+  const status = inspectLegacy(sourceDir);
+  if (!status.hook_memory_dir && !status.state_memory_table) {
+    return { ...status, archived: false, archive_dir: null };
+  }
+  const stamp = timestamp || new Date().toISOString().replace(/[:.]/g, '-');
+  const archiveDir = path.join(status.source_dir, '.ultra', `legacy-memory-archive-${stamp}`);
+  if (fs.existsSync(archiveDir)) throw new Error(`legacy memory archive already exists: ${archiveDir}`);
+  fs.mkdirSync(archiveDir, { recursive: true });
+
+  if (status.hook_memory_dir) {
+    fs.cpSync(status.hook_memory_path, path.join(archiveDir, 'hook-memory'), {
+      recursive: true,
+      dereference: false,
+      errorOnExist: true,
+    });
+  }
+
+  if (status.state_memory_table) {
+    const db = new Database(status.state_db_path, { readonly: true, fileMustExist: true });
+    let entries;
+    try {
+      entries = db.prepare('SELECT * FROM memory_entries ORDER BY id ASC').all();
+    } finally {
+      db.close();
+    }
+    fs.writeFileSync(
+      path.join(archiveDir, 'state-memory-entries.json'),
+      JSON.stringify({ schema: 1, source: status.state_db_path, entries }, null, 2) + '\n',
+      { encoding: 'utf8', flag: 'wx' },
+    );
+  }
+
+  fs.writeFileSync(
+    path.join(archiveDir, 'manifest.json'),
+    JSON.stringify({ schema: 1, archived_at: new Date().toISOString(), ...status }, null, 2) + '\n',
+    { encoding: 'utf8', flag: 'wx' },
+  );
+  return { ...status, archived: true, archive_dir: archiveDir };
+}
+
+function pruneLegacy(sourceDir = '.', { confirm, timestamp } = {}) {
+  if (confirm !== CONFIRMATION) {
+    throw new Error(`prune requires --confirm ${CONFIRMATION}`);
+  }
+  const archived = archiveLegacy(sourceDir, { timestamp });
+  if (!archived.archived) return { ...archived, pruned: false };
+
+  if (archived.hook_memory_dir) {
+    fs.rmSync(archived.hook_memory_path, { recursive: true, force: false });
+  }
+  if (archived.state_memory_table) {
+    const db = new Database(archived.state_db_path, { fileMustExist: true });
+    try {
+      db.transaction(() => {
+        db.exec('DROP TRIGGER IF EXISTS memory_ai');
+        db.exec('DROP TRIGGER IF EXISTS memory_ad');
+        db.exec('DROP TRIGGER IF EXISTS memory_au');
+        db.exec('DROP TABLE IF EXISTS memory_fts');
+        db.exec('DROP TABLE IF EXISTS memory_entries');
+      })();
+    } finally {
+      db.close();
+    }
+  }
+  return { ...archived, pruned: true };
+}
+
+function parseFlags(args) {
+  const flags = { _: [] };
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+    if (token === '--source-dir') {
+      flags.sourceDir = args[i + 1];
+      i += 1;
+    } else if (token.startsWith('--source-dir=')) {
+      flags.sourceDir = token.slice('--source-dir='.length);
+    } else if (token === '--confirm') {
+      flags.confirm = args[i + 1];
+      i += 1;
+    } else if (token.startsWith('--confirm=')) {
+      flags.confirm = token.slice('--confirm='.length);
+    } else {
+      flags._.push(token);
+    }
+  }
+  return flags;
+}
+
+function dispatch(args) {
+  const flags = parseFlags(args);
+  const action = flags._[0] || 'inspect';
+  try {
+    let data;
+    if (action === 'inspect') data = inspectLegacy(flags.sourceDir);
+    else if (action === 'archive') data = archiveLegacy(flags.sourceDir);
+    else if (action === 'prune') data = pruneLegacy(flags.sourceDir, { confirm: flags.confirm });
+    else throw new Error(`unknown legacy-memory action: ${action}`);
+    process.stdout.write(`${JSON.stringify({ ok: true, data })}\n`);
+    return 0;
+  } catch (error) {
+    process.stdout.write(`${JSON.stringify({
+      ok: false,
+      error: { code: 'LEGACY_MEMORY_MIGRATION_FAILED', message: error.message, retriable: false },
+    })}\n`);
+    return 2;
+  }
+}
+
+module.exports = {
+  CONFIRMATION,
+  inspectLegacy,
+  archiveLegacy,
+  pruneLegacy,
+  parseFlags,
+  dispatch,
+};

package/ultra-tools/commands/migrate.cjs

@@ -0,0 +1,354 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { initStateDb, openStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
+const ops = require('../../mcp-server/lib/state-ops.cjs');
+
+const SUPPORTED_FROM = '4.4';
+const SUPPORTED_TO = '4.5';
+
+// Frozen SQL — values flow through parameter bindings.
+const RECORD_MIGRATION_SQL = "INSERT INTO migration_history (from_version, to_version, direction, status, notes) VALUES (@from, @to, @direction, @status, @notes)";
+
+function emit(envelope) {
+  process.stdout.write(`${JSON.stringify(envelope)}\n`);
+}
+
+function parseFlags(args) {
+  const flags = { _: [] };
+  // Accept both "--from 4.4" and "--from=4.4" styles.
+  const valueOf = (token, i) => {
+    const eq = token.indexOf('=');
+    return eq >= 0 ? { value: token.slice(eq + 1), nextI: i } : { value: args[i + 1], nextI: i + 1 };
+  };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--dry')        { flags.dry = true; continue; }
+    if (a === '--rollback')   { flags.rollback = true; continue; }
+    if (a === '--help' || a === '-h') { flags.help = true; continue; }
+    if (a.startsWith('--from'))       { const r = valueOf(a, i); flags.from = r.value; i = r.nextI; continue; }
+    if (a.startsWith('--to'))         { const r = valueOf(a, i); flags.to = r.value; i = r.nextI; continue; }
+    if (a.startsWith('--source-dir')) { const r = valueOf(a, i); flags.sourceDir = r.value; i = r.nextI; continue; }
+    if (a.startsWith('--db-path'))    { const r = valueOf(a, i); flags.dbPath = r.value; i = r.nextI; continue; }
+    flags._.push(a);
+  }
+  return flags;
+}
+
+function parseFrontmatter(text) {
+  if (!text.startsWith('---')) return null;
+  const end = text.indexOf('\n---', 3);
+  if (end === -1) return null;
+  const block = text.slice(3, end).trim();
+  const out = {};
+  for (const line of block.split('\n')) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+    out[key] = value;
+  }
+  return out;
+}
+
+function readJsonOptional(p) {
+  if (!fs.existsSync(p)) return null;
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function findContexts(rootDir) {
+  const dir = path.join(rootDir, '.ultra', 'tasks', 'contexts');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => path.join(dir, f));
+}
+
+function copyDirSync(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.name === 'state.db' || entry.name === 'state.db-wal' || entry.name === 'state.db-shm') continue;
+    if (entry.name.startsWith('backup-v4.4-')) continue;
+    if (entry.isDirectory()) copyDirSync(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+function planForward(sourceDir) {
+  const tasksPath = path.join(sourceDir, '.ultra', 'tasks', 'tasks.json');
+  const tasksJson = readJsonOptional(tasksPath);
+  if (!tasksJson || !Array.isArray(tasksJson.tasks)) {
+    throw new Error(`migrate: tasks.json missing or malformed at ${tasksPath}`);
+  }
+
+  const contextHeaders = {};
+  for (const file of findContexts(sourceDir)) {
+    const fm = parseFrontmatter(fs.readFileSync(file, 'utf8'));
+    if (fm && fm.task_id) contextHeaders[fm.task_id] = { ...fm, _file: file };
+  }
+
+  const warnings = [];
+  for (const task of tasksJson.tasks) {
+    const ctx = contextHeaders[task.id];
+    if (ctx && ctx.status && ctx.status !== task.status) {
+      warnings.push({
+        task_id: task.id,
+        json_status: task.status,
+        context_status: ctx.status,
+        resolution: 'tasks.json wins (v4.4 → v4.5 D21 rule)',
+      });
+    }
+  }
+
+  const eventsPath = path.join(sourceDir, '.ultra', 'activity-log.json');
+  const events = readJsonOptional(eventsPath);
+  const eventList = Array.isArray(events) ? events : [];
+
+  return {
+    tasks: tasksJson.tasks,
+    events: eventList,
+    contextHeaders,
+    warnings,
+  };
+}
+
+function applyForward(db, plan) {
+  const insertTask = db.prepare(
+    "INSERT INTO tasks (id, title, type, priority, complexity, status, deps, tag, trace_to, context_file, created_at, updated_at) VALUES (@id, @title, @type, @priority, @complexity, @status, @deps, @tag, @trace_to, @context_file, @created_at, @updated_at)",
+  );
+  const insertEvent = db.prepare(
+    "INSERT INTO events (ts, type, task_id, session_id, runtime, payload_json) VALUES (@ts, @type, @task_id, @session_id, @runtime, @payload)",
+  );
+
+  const taskInserted = ops.tx(db, () => {
+    let n = 0;
+    for (const t of plan.tasks) {
+      const ctx = plan.contextHeaders[t.id];
+      insertTask.run({
+        id: t.id,
+        title: t.title,
+        type: t.type,
+        priority: t.priority,
+        complexity: t.complexity ?? null,
+        status: t.status,
+        deps: t.deps ? JSON.stringify(t.deps) : null,
+        tag: t.tag ?? null,
+        trace_to: t.trace_to ?? null,
+        context_file: ctx ? ctx._file : null,
+        created_at: t.created_at,
+        updated_at: t.updated_at,
+      });
+      n++;
+    }
+    return n;
+  });
+
+  const eventsInserted = ops.tx(db, () => {
+    let n = 0;
+    for (const e of plan.events) {
+      insertEvent.run({
+        ts: e.ts || new Date().toISOString(),
+        type: e.type,
+        task_id: e.task_id ?? null,
+        session_id: e.session_id ?? null,
+        runtime: e.runtime ?? null,
+        payload: e.payload === undefined ? null : JSON.stringify(e.payload),
+      });
+      n++;
+    }
+    return n;
+  });
+
+  return { taskInserted, eventsInserted };
+}
+
+function recordMigration(db, { from, to, direction, status, notes }) {
+  db.prepare(RECORD_MIGRATION_SQL).run({ from, to, direction, status, notes });
+}
+
+function ensureBackupName(sourceDir) {
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(sourceDir, '.ultra', `backup-v4.4-${ts}`);
+}
+
+function findLatestBackup(sourceDir) {
+  const ultra = path.join(sourceDir, '.ultra');
+  if (!fs.existsSync(ultra)) return null;
+  const candidates = fs.readdirSync(ultra)
+    .filter((n) => n.startsWith('backup-v4.4-'))
+    .sort();
+  return candidates.length === 0 ? null : path.join(ultra, candidates[candidates.length - 1]);
+}
+
+function cmdForward(flags) {
+  const sourceDir = path.resolve(flags.sourceDir || '.');
+  const dbPath = path.resolve(flags.dbPath || path.join(sourceDir, '.ultra', 'state.db'));
+  let plan;
+  try {
+    plan = planForward(sourceDir);
+  } catch (err) {
+    emit({ ok: false, error: { code: 'MIGRATE_FAILED', message: err.message, retriable: false } });
+    return 2;
+  }
+
+  if (flags.dry) {
+    emit({
+      ok: true,
+      data: {
+        mode: 'dry',
+        from: SUPPORTED_FROM,
+        to: SUPPORTED_TO,
+        source_dir: sourceDir,
+        db_path: dbPath,
+        tasks_to_insert: plan.tasks.length,
+        events_to_insert: plan.events.length,
+        warnings: plan.warnings,
+      },
+    });
+    return 0;
+  }
+
+  // Real run: backup the entire .ultra subtree first.
+  const backupDir = ensureBackupName(sourceDir);
+  const ultraSource = path.join(sourceDir, '.ultra');
+  copyDirSync(ultraSource, backupDir);
+
+  let db;
+  try {
+    db = initStateDb(dbPath).db;
+    const counts = applyForward(db, plan);
+    recordMigration(db, {
+      from: SUPPORTED_FROM,
+      to: SUPPORTED_TO,
+      direction: 'forward',
+      status: 'success',
+      notes: `tasks=${counts.taskInserted} events=${counts.eventsInserted} warnings=${plan.warnings.length}`,
+    });
+    emit({
+      ok: true,
+      data: {
+        mode: 'apply',
+        from: SUPPORTED_FROM,
+        to: SUPPORTED_TO,
+        source_dir: sourceDir,
+        db_path: dbPath,
+        backup_dir: backupDir,
+        tasks_inserted: counts.taskInserted,
+        events_inserted: counts.eventsInserted,
+        warnings: plan.warnings,
+      },
+    });
+    return 0;
+  } catch (err) {
+    if (db) {
+      try {
+        recordMigration(db, {
+          from: SUPPORTED_FROM,
+          to: SUPPORTED_TO,
+          direction: 'forward',
+          status: 'failed',
+          notes: err.message,
+        });
+      } catch (_) { /* swallow secondary failure */ }
+    }
+    emit({ ok: false, error: { code: 'MIGRATE_FAILED', message: err.message, retriable: false } });
+    return 2;
+  } finally {
+    if (db) closeStateDb(db);
+  }
+}
+
+function cmdRollback(flags) {
+  const sourceDir = path.resolve(flags.sourceDir || '.');
+  const dbPath = path.resolve(flags.dbPath || path.join(sourceDir, '.ultra', 'state.db'));
+  const backupDir = findLatestBackup(sourceDir);
+  if (!backupDir) {
+    emit({ ok: false, error: { code: 'NO_BACKUP', message: 'no backup-v4.4-* directory found' } });
+    return 2;
+  }
+
+  // Record rollback BEFORE removing the db; if the file is gone we still want an audit row.
+  let db;
+  try {
+    if (fs.existsSync(dbPath)) {
+      db = openStateDb(dbPath);
+      recordMigration(db, {
+        from: SUPPORTED_TO,
+        to: SUPPORTED_FROM,
+        direction: 'rollback',
+        status: 'success',
+        notes: `restored from ${backupDir}`,
+      });
+      closeStateDb(db);
+      db = null;
+      fs.unlinkSync(dbPath);
+      const wal = `${dbPath}-wal`;
+      const shm = `${dbPath}-shm`;
+      if (fs.existsSync(wal)) fs.unlinkSync(wal);
+      if (fs.existsSync(shm)) fs.unlinkSync(shm);
+    }
+
+    // Restore .ultra contents from backup, leaving the backup itself in place.
+    const ultraDir = path.join(sourceDir, '.ultra');
+    for (const entry of fs.readdirSync(ultraDir, { withFileTypes: true })) {
+      if (entry.name.startsWith('backup-v4.4-')) continue;
+      const target = path.join(ultraDir, entry.name);
+      fs.rmSync(target, { recursive: true, force: true });
+    }
+    copyDirSync(backupDir, ultraDir);
+
+    emit({
+      ok: true,
+      data: {
+        mode: 'rollback',
+        from: SUPPORTED_TO,
+        to: SUPPORTED_FROM,
+        backup_dir: backupDir,
+        source_dir: sourceDir,
+      },
+    });
+    return 0;
+  } catch (err) {
+    if (db) closeStateDb(db);
+    emit({ ok: false, error: { code: 'ROLLBACK_FAILED', message: err.message, retriable: false } });
+    return 2;
+  }
+}
+
+function dispatch(args) {
+  const flags = parseFlags(args);
+  if (flags.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (flags.from && flags.from !== SUPPORTED_FROM) {
+    emit({ ok: false, error: { code: 'UNSUPPORTED_VERSION', message: `--from ${flags.from} unsupported (only ${SUPPORTED_FROM})` } });
+    return 1;
+  }
+  if (flags.to && flags.to !== SUPPORTED_TO) {
+    emit({ ok: false, error: { code: 'UNSUPPORTED_VERSION', message: `--to ${flags.to} unsupported (only ${SUPPORTED_TO})` } });
+    return 1;
+  }
+  return flags.rollback ? cmdRollback(flags) : cmdForward(flags);
+}
+
+const USAGE = `ultra-tools migrate --from=4.4 --to=4.5 [flags]
+
+Flags:
+  --source-dir <dir>   project root containing .ultra/ (default: .)
+  --db-path <path>     state.db destination (default: <source-dir>/.ultra/state.db)
+  --dry                print the migration plan without writing
+  --rollback           restore the most recent backup-v4.4-* and drop state.db
+
+The forward flow: backup .ultra/ → init state.db → insert tasks from
+tasks.json → merge context md status (tasks.json wins on conflict, warnings
+recorded) → insert activity-log events → record migration_history.
+Rollback restores from the latest backup-v4.4-* directory and writes a
+matching migration_history rollback row before dropping state.db.
+`;
+
+module.exports = { dispatch, USAGE, parseFlags, planForward, parseFrontmatter };