ultra-builder-pro-cli 0.5.0

package/mcp-server/lib/state-db.cjs

@@ -0,0 +1,113 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const Database = require('better-sqlite3');
+
+const REPO_ROOT = process.env.UBP_RUNTIME_ROOT
+  ? path.resolve(process.env.UBP_RUNTIME_ROOT)
+  : path.resolve(__dirname, '..', '..');
+const SCHEMA_FILE = path.join(REPO_ROOT, 'spec', 'schemas', 'state-db.sql');
+const EXPECTED_VERSION = '8A.1';
+
+const REQUIRED_TABLES = Object.freeze([
+  'tasks',
+  'events',
+  'sessions',
+  'schema_version',
+  'migration_history',
+  'telemetry',
+  'specs_refs',
+  'circuit_breaker',
+]);
+
+function readSchemaSql() {
+  if (!fs.existsSync(SCHEMA_FILE)) {
+    throw new Error(`state-db schema missing at ${SCHEMA_FILE}`);
+  }
+  return fs.readFileSync(SCHEMA_FILE, 'utf8');
+}
+
+function applyPragmas(db) {
+  db.pragma('journal_mode = WAL');
+  db.pragma('synchronous = NORMAL');
+  db.pragma('busy_timeout = 5000');
+  db.pragma('foreign_keys = ON');
+}
+
+function runScript(db, sql) {
+  const runner = db.exec.bind(db);
+  db.transaction(() => runner(sql))();
+}
+
+function openStateDb(dbPath) {
+  if (!dbPath) throw new Error('openStateDb: dbPath required');
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  const db = new Database(dbPath);
+  applyPragmas(db);
+  return db;
+}
+
+function tableNames(db) {
+  return db
+    .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'")
+    .all()
+    .map((r) => r.name);
+}
+
+function applySchema(db) {
+  runScript(db, readSchemaSql());
+}
+
+function ensureSchemaVersion(db) {
+  // schema_version is an audit trail — multiple rows across phase upgrades.
+  // Guard by checking whether the expected version row exists rather than
+  // relying on applied_at ordering (same-tick inserts from the seed block
+  // make `ORDER BY applied_at DESC LIMIT 1` non-deterministic).
+  const row = db.prepare('SELECT version FROM schema_version WHERE version = ?').get(EXPECTED_VERSION);
+  if (!row) {
+    const latest = db.prepare('SELECT version FROM schema_version ORDER BY applied_at DESC LIMIT 1').get();
+    throw new Error(
+      `state.db schema_version mismatch: expected '${EXPECTED_VERSION}', file has '${latest ? latest.version : '(empty)'}'`,
+    );
+  }
+  return row.version;
+}
+
+function initStateDb(dbPath) {
+  const db = openStateDb(dbPath);
+  const existing = new Set(tableNames(db));
+  const missing = REQUIRED_TABLES.filter((t) => !existing.has(t));
+  if (missing.length > 0) {
+    applySchema(db);
+  }
+  const version = ensureSchemaVersion(db);
+  return {
+    db,
+    path: dbPath,
+    schema_version: version,
+    created: missing.length > 0,
+    tables: tableNames(db).sort(),
+  };
+}
+
+function closeStateDb(db) {
+  if (db && typeof db.close === 'function') {
+    db.close();
+  }
+}
+
+module.exports = {
+  EXPECTED_VERSION,
+  REQUIRED_TABLES,
+  SCHEMA_FILE,
+  openStateDb,
+  applySchema,
+  applyPragmas,
+  ensureSchemaVersion,
+  initStateDb,
+  closeStateDb,
+  tableNames,
+  runScript,
+};

package/mcp-server/lib/state-db.test.cjs

@@ -0,0 +1,116 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const {
+  EXPECTED_VERSION,
+  REQUIRED_TABLES,
+  initStateDb,
+  closeStateDb,
+  openStateDb,
+  tableNames,
+} = require('./state-db.cjs');
+
+function tmpDbPath(prefix = 'ubp-state') {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`));
+  return { dir, file: path.join(dir, 'state.db') };
+}
+
+test('initStateDb creates workflow tables without an Ultra memory store', () => {
+  const { dir, file } = tmpDbPath();
+  try {
+    const init = initStateDb(file);
+    assert.equal(init.created, true);
+    assert.equal(init.schema_version, EXPECTED_VERSION);
+    for (const t of REQUIRED_TABLES) {
+      assert.ok(init.tables.includes(t), `missing table ${t}`);
+    }
+    assert.ok(!init.tables.includes('memory_entries'));
+    assert.ok(!init.tables.includes('memory_fts'));
+    closeStateDb(init.db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('initStateDb applies WAL + busy_timeout + foreign_keys pragmas', () => {
+  const { dir, file } = tmpDbPath();
+  try {
+    const { db } = initStateDb(file);
+    assert.equal(db.pragma('journal_mode', { simple: true }), 'wal');
+    assert.equal(db.pragma('busy_timeout', { simple: true }), 5000);
+    assert.equal(db.pragma('foreign_keys', { simple: true }), 1);
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('initStateDb is idempotent — second call does not duplicate seed rows', () => {
+  const { dir, file } = tmpDbPath();
+  try {
+    const first = initStateDb(file);
+    const firstRows = first.db.prepare('SELECT COUNT(*) AS n FROM schema_version').get().n;
+    closeStateDb(first.db);
+
+    const second = initStateDb(file);
+    assert.equal(second.created, false, 'second init should not recreate schema');
+    assert.equal(second.schema_version, EXPECTED_VERSION);
+
+    const secondRows = second.db.prepare('SELECT COUNT(*) AS n FROM schema_version').get().n;
+    assert.equal(secondRows, firstRows, 'schema_version row count must not grow on re-init');
+    closeStateDb(second.db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('openStateDb on an empty file produces no tables until schema is applied', () => {
+  const { dir, file } = tmpDbPath();
+  try {
+    const db = openStateDb(file);
+    assert.deepEqual(tableNames(db), []);
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('Phase 8A.1 schema: tasks.parent_id column + tasks_parent partial index + seed row', () => {
+  const { dir, file } = tmpDbPath();
+  try {
+    const { db } = initStateDb(file);
+
+    const cols = db.prepare("PRAGMA table_info(tasks)").all();
+    const parentCol = cols.find((c) => c.name === 'parent_id');
+    assert.ok(parentCol, 'tasks.parent_id column must exist');
+    assert.equal(parentCol.type, 'TEXT');
+    assert.equal(parentCol.notnull, 0, 'parent_id must be nullable (top-level tasks)');
+
+    const indexRow = db
+      .prepare("SELECT name FROM sqlite_master WHERE type = 'index' AND name = 'tasks_parent'")
+      .get();
+    assert.ok(indexRow, 'tasks_parent index must exist');
+
+    const seedRow = db
+      .prepare("SELECT version, description FROM schema_version WHERE version = '8A.1'")
+      .get();
+    assert.ok(seedRow, 'schema_version row for 8A.1 must be seeded');
+    assert.match(seedRow.description, /parent_id/);
+
+    const fkInfo = db.prepare("PRAGMA foreign_key_list(tasks)").all();
+    const parentFk = fkInfo.find((fk) => fk.from === 'parent_id');
+    assert.ok(parentFk, 'parent_id must declare a foreign key to tasks(id)');
+    assert.equal(parentFk.table, 'tasks');
+    assert.equal(parentFk.to, 'id');
+    assert.equal(parentFk.on_delete, 'SET NULL');
+
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});