ultra-builder-pro-cli 0.25.0 → 0.26.0

package/ultra-tools/cli.cjs

@@ -1,129 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * ultra-tools — runtime-agnostic state engine for Ultra Builder Pro.
- *
- * Maintenance CLI for Ultra initialization, status, database operations,
- * migration, and explicit legacy-memory cleanup. Authoritative task mutations
- * stay on the live MCP server; this CLI is not a task-state fallback.
- *
- * Usage:
- *   ultra-tools <subcommand> [...]
- *   ultra-tools --help
- *   ultra-tools --version
- */
-
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-const runtimePaths = require('../mcp-server/lib/runtime-paths.cjs');
-
-const VERSION = (() => {
-  try {
-    const pkg = require('../package.json');
-    return pkg.version;
-  } catch (_err) {
-    return '0.1.0';
-  }
-})();
-
-const USAGE = `ultra-tools v${VERSION}
-
-USAGE:
-  ultra-tools <subcommand> [args]
-
-SUBCOMMANDS:
-  task      init-project
-  session   close | get | list | admission | heartbeat | subscribe | reap
-  system    doctor [--repair] | restore | rebaseline
-  status    [--cost] [--since <duration>] [--json]
-  db        init | checkpoint | vacuum | integrity | backup (Phase 2)
-  migrate   --from=<4.4|4.5> --to=<4.5|20.0> [--dry|--rollback]
-  legacy-memory inspect | archive | prune --confirm DELETE_ULTRA_LEGACY_MEMORY
-
-  --help / -h      show this message
-  --version / -v   show version
-
-All state lives under .ultra/ in the project root.
-`;
-
-function readJsonIfExists(p) {
-  if (!fs.existsSync(p)) return null;
-  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
-  catch (err) {
-    fail(`malformed JSON at ${p}: ${err.message}`);
-  }
-}
-
-function fail(msg, code) {
-  process.stderr.write(`ultra-tools: ${msg}\n`);
-  process.exit(code || 1);
-}
-
-const dbCommand = require('./commands/db.cjs');
-const migrateCommand = require('./commands/migrate.cjs');
-const taskCommand = require('./commands/task.cjs');
-const sessionCommand = require('./commands/session.cjs');
-const statusCommand = require('./commands/status.cjs');
-const legacyMemoryCommand = require('./commands/legacy-memory.cjs');
-const systemCommand = require('./commands/system.cjs');
-
-// Session commands run only against healthy authority and may emit best-effort
-// telemetry. Initialization, diagnosis, migration, and recovery commands must
-// never open state.db before their own evidence-preserving checks.
-const TELEMETRY_SUBCOMMANDS = new Set(['session']);
-
-function emitCliTelemetry(sub, rest) {
-  try {
-    const dbPath = runtimePaths.locateStateDb(process.cwd());
-    if (!fs.existsSync(dbPath)) return;
-    const Database = require('better-sqlite3');
-    const db = new Database(dbPath);
-    try {
-      const telemetry = require('../mcp-server/lib/telemetry.cjs');
-      telemetry.appendTelemetry(db, {
-        event_type: 'tool_call',
-        tool_name: `cli.${sub}`,
-        session_id: process.env.UBP_SESSION_ID || null,
-        rootDir: process.cwd(),
-        payload: { args: Array.isArray(rest) ? rest.slice(0, 4) : [] },
-      });
-    } finally { db.close(); }
-  } catch (_) { /* telemetry is opt-in side channel; never crash the CLI */ }
-}
-
-const SUBCOMMANDS = {
-  task: (args) => process.exit(taskCommand.dispatch(args)),
-  session: (args) => process.exit(sessionCommand.dispatch(args)),
-  status: (args) => process.exit(statusCommand.dispatch(args)),
-  db: (args) => process.exit(dbCommand.dispatch(args)),
-  migrate: (args) => process.exit(migrateCommand.dispatch(args)),
-  'legacy-memory': (args) => process.exit(legacyMemoryCommand.dispatch(args)),
-  system: (args) => systemCommand.dispatch(args).then((code) => process.exit(code)),
-};
-
-function main(argv) {
-  const args = argv.slice(2);
-  if (args.length === 0 || args[0] === '-h' || args[0] === '--help') {
-    process.stdout.write(USAGE);
-    return;
-  }
-  if (args[0] === '-v' || args[0] === '--version') {
-    process.stdout.write(`${VERSION}\n`);
-    return;
-  }
-
-  const [sub, ...rest] = args;
-  const handler = SUBCOMMANDS[sub];
-  if (!handler) fail(`unknown subcommand: ${sub}\n\n${USAGE}`);
-  if (TELEMETRY_SUBCOMMANDS.has(sub)) emitCliTelemetry(sub, rest);
-  handler(rest);
-}
-
-// exports kept for unit tests (Phase 1+)
-module.exports = { USAGE, SUBCOMMANDS, readJsonIfExists, VERSION, main };
-
-if (require.main === module) {
-  main(process.argv);
-}

package/ultra-tools/commands/db.cjs

@@ -1,226 +0,0 @@
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { randomUUID } = require('node:crypto');
-const Database = require('better-sqlite3');
-
-const { initStateDb, openStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
-const runtimePaths = require('../../mcp-server/lib/runtime-paths.cjs');
-
-const DEFAULT_DB_PATH = runtimePaths.STATE_DB_RELATIVE_PATH;
-const DEFAULT_BACKUP_DIR = path.join(runtimePaths.RUNTIME_RELATIVE_DIR, '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 resolveAuthorityPath(flags, { migrateLegacy = true } = {}) {
-  const env = flags.path
-    ? { UBP_DB_PATH: path.resolve(flags.path) }
-    : process.env;
-  return runtimePaths.resolveConfiguredStateDb(process.cwd(), {
-    env,
-    migrateLegacy,
-  }).stateDbPath;
-}
-
-function cmdInit(flags) {
-  try {
-    const dbPath = resolveAuthorityPath(flags, { migrateLegacy: true });
-    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) {
-  let db;
-  try {
-    const dbPath = resolveAuthorityPath(flags, { migrateLegacy: true });
-    if (!fs.existsSync(dbPath)) {
-      emit({ ok: false, error: { code: 'DB_NOT_FOUND', message: `state.db missing at ${dbPath}; run 'db init' first` } });
-      return 2;
-    }
-    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 quoteSqlString(value) {
-  return `'${String(value).replaceAll("'", "''")}'`;
-}
-
-function createOnlineBackup(db, targetPath, {
-  beforeSnapshot = null,
-} = {}) {
-  const stage = path.join(
-    path.dirname(targetPath),
-    `.${path.basename(targetPath)}.snapshot-${process.pid}-${randomUUID()}`,
-  );
-  try {
-    if (beforeSnapshot) beforeSnapshot();
-    // VACUUM INTO is SQLite's synchronous, transactionally consistent
-    // snapshot primitive. It reads committed pages through SQLite rather than
-    // copying a main file that may lag committed WAL frames.
-    db.exec(`VACUUM INTO ${quoteSqlString(stage)}`);
-    const snapshot = new Database(stage, { readonly: true, fileMustExist: true });
-    try {
-      const integrity = snapshot.pragma('integrity_check');
-      if (integrity.length !== 1 || integrity[0].integrity_check !== 'ok') {
-        throw new Error('SQLite backup snapshot failed integrity_check');
-      }
-    } finally {
-      snapshot.close();
-    }
-    fs.renameSync(stage, targetPath);
-    return fs.statSync(targetPath).size;
-  } finally {
-    fs.rmSync(stage, { force: true });
-  }
-}
-
-function cmdBackup(flags) {
-  let db;
-  try {
-    const dbPath = resolveAuthorityPath(flags, { migrateLegacy: true });
-    const targetPath = runtimePaths.assertManagedBackupDestination(
-      process.cwd(),
-      flags.to || defaultBackupPath(),
-    ).targetPath;
-    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 });
-    db = openStateDb(dbPath);
-    const size = createOnlineBackup(db, targetPath);
-    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/.runtime/state.db
-Default backup: .ultra/.runtime/backups/state-db-{iso}.db
-`;
-
-module.exports = {
-  dispatch,
-  USAGE,
-  DEFAULT_DB_PATH,
-  DEFAULT_BACKUP_DIR,
-  _internal: {
-    createOnlineBackup,
-  },
-};

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

@@ -1,159 +0,0 @@
-'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,
-};