mdkg 0.1.6 → 0.1.7

package/dist/core/project_db_migrations.js

@@ -0,0 +1,600 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runProjectDbMigrations = runProjectDbMigrations;
+exports.verifyProjectDb = verifyProjectDb;
+exports.projectDbStats = projectDbStats;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const project_db_1 = require("./project_db");
+const version_1 = require("./version");
+const atomic_1 = require("../util/atomic");
+const errors_1 = require("../util/errors");
+const FOUNDATION_MIGRATION_SQL = `
+CREATE TABLE IF NOT EXISTS project_meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+) STRICT;
+`;
+const BUILTIN_MIGRATIONS = [
+    {
+        ordinal: 1,
+        key: "mdkg.project_db.foundation.v1",
+        filename: "001_mdkg_project_db_foundation.sql",
+        sql: FOUNDATION_MIGRATION_SQL.trim(),
+    },
+];
+function loadDatabaseCtor() {
+    try {
+        const loaded = require("node:sqlite");
+        if (!loaded.DatabaseSync) {
+            throw new Error("node:sqlite DatabaseSync is unavailable");
+        }
+        return loaded.DatabaseSync;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`node:sqlite is required for mdkg project DB migrations: ${message}`);
+    }
+}
+function toPosix(relativePath) {
+    return relativePath.split(path_1.default.sep).join("/");
+}
+function rel(root, filePath) {
+    return toPosix(path_1.default.relative(root, filePath));
+}
+function checksumMigration(migration) {
+    const payload = [
+        `ordinal:${migration.ordinal}`,
+        `key:${migration.key}`,
+        migration.sql.trim(),
+    ].join("\n");
+    return `sha256:${crypto_1.default.createHash("sha256").update(payload).digest("hex")}`;
+}
+function checksumContent(content) {
+    return `sha256:${crypto_1.default.createHash("sha256").update(content.trim()).digest("hex")}`;
+}
+function assertDirectory(root, dirPath, label) {
+    const relative = rel(root, dirPath);
+    if (!fs_1.default.existsSync(dirPath)) {
+        throw new errors_1.ValidationError(`${label} missing at ${relative}; run mdkg db init`);
+    }
+    if (!fs_1.default.statSync(dirPath).isDirectory()) {
+        throw new errors_1.ValidationError(`${relative} exists and is not a directory`);
+    }
+}
+function directoryCheck(root, dirPath, name) {
+    const relative = rel(root, dirPath);
+    if (!fs_1.default.existsSync(dirPath)) {
+        return {
+            name,
+            ok: false,
+            level: "fail",
+            path: relative,
+            detail: `${name} missing`,
+            errors: [`${relative} missing; run mdkg db init`],
+            warnings: [],
+        };
+    }
+    if (!fs_1.default.statSync(dirPath).isDirectory()) {
+        return {
+            name,
+            ok: false,
+            level: "fail",
+            path: relative,
+            detail: `${name} is not a directory`,
+            errors: [`${relative} exists and is not a directory`],
+            warnings: [],
+        };
+    }
+    return {
+        name,
+        ok: true,
+        level: "ok",
+        path: relative,
+        detail: `${name} exists`,
+        errors: [],
+        warnings: [],
+    };
+}
+function assertProjectDbReady(root, config) {
+    if (!config.db.enabled) {
+        throw new errors_1.ValidationError("project db is disabled; run mdkg db init first");
+    }
+    if (config.db.schema_version !== project_db_1.PROJECT_DB_CONFIG_SCHEMA_VERSION) {
+        throw new errors_1.ValidationError(`unsupported project db schema_version ${config.db.schema_version}; supported ${project_db_1.PROJECT_DB_CONFIG_SCHEMA_VERSION}`);
+    }
+    const layout = (0, project_db_1.resolveConfiguredProjectDbLayout)(root, config.db);
+    assertDirectory(root, layout.db, "project db root");
+    assertDirectory(root, layout.schema, "project db schema directory");
+    assertDirectory(root, layout.migrations, "project db migrations directory");
+    assertDirectory(root, layout.runtimeDir, "project db runtime directory");
+    assertDirectory(root, layout.stateDir, "project db state directory");
+    assertDirectory(root, layout.receipts, "project db receipts directory");
+    if (fs_1.default.existsSync(layout.runtimeFile) && fs_1.default.statSync(layout.runtimeFile).isDirectory()) {
+        throw new errors_1.ValidationError(`${rel(root, layout.runtimeFile)} exists and is not a file`);
+    }
+}
+function ensureMigrationFiles(root, config) {
+    const layout = (0, project_db_1.resolveConfiguredProjectDbLayout)(root, config.db);
+    const created = [];
+    const unchanged = [];
+    for (const migration of BUILTIN_MIGRATIONS) {
+        const filePath = path_1.default.join(layout.migrations, migration.filename);
+        const expectedContent = `${migration.sql.trim()}\n`;
+        const relative = rel(root, filePath);
+        if (fs_1.default.existsSync(filePath)) {
+            if (fs_1.default.statSync(filePath).isDirectory()) {
+                throw new errors_1.ValidationError(`${relative} exists and is not a file`);
+            }
+            const current = fs_1.default.readFileSync(filePath, "utf8");
+            if (checksumContent(current) !== checksumContent(expectedContent)) {
+                throw new errors_1.ValidationError(`migration file checksum drift at ${relative}`);
+            }
+            unchanged.push(relative);
+            continue;
+        }
+        (0, atomic_1.atomicWriteFile)(filePath, expectedContent);
+        created.push(relative);
+    }
+    return { created, unchanged };
+}
+function checkMigrationFiles(root, config) {
+    const layout = (0, project_db_1.resolveConfiguredProjectDbLayout)(root, config.db);
+    const errors = [];
+    for (const migration of BUILTIN_MIGRATIONS) {
+        const filePath = path_1.default.join(layout.migrations, migration.filename);
+        const relative = rel(root, filePath);
+        const expectedContent = `${migration.sql.trim()}\n`;
+        if (!fs_1.default.existsSync(filePath)) {
+            errors.push(`${relative} missing; run mdkg db migrate`);
+            continue;
+        }
+        if (fs_1.default.statSync(filePath).isDirectory()) {
+            errors.push(`${relative} exists and is not a file`);
+            continue;
+        }
+        const current = fs_1.default.readFileSync(filePath, "utf8");
+        if (checksumContent(current) !== checksumContent(expectedContent)) {
+            errors.push(`migration file checksum drift at ${relative}`);
+        }
+    }
+    return {
+        name: "migration-files",
+        ok: errors.length === 0,
+        level: errors.length === 0 ? "ok" : "fail",
+        path: rel(root, layout.migrations),
+        detail: errors.length === 0 ? "migration files match mdkg-owned foundation migrations" : "migration file issues found",
+        errors,
+        warnings: [],
+    };
+}
+function createMigrationTableSql(tableName) {
+    return `
+    CREATE TABLE IF NOT EXISTS ${tableName} (
+      migration_key TEXT PRIMARY KEY,
+      ordinal INTEGER NOT NULL UNIQUE,
+      checksum TEXT NOT NULL,
+      applied_at_ms INTEGER NOT NULL,
+      mdkg_version TEXT NOT NULL
+    ) STRICT;
+  `;
+}
+function readAppliedMigrations(db, tableName) {
+    const rows = db
+        .prepare(`SELECT migration_key, ordinal, checksum, applied_at_ms FROM ${tableName} ORDER BY ordinal ASC`)
+        .all();
+    const applied = new Map();
+    for (const row of rows) {
+        applied.set(String(row.migration_key), {
+            migration_key: String(row.migration_key),
+            ordinal: Number(row.ordinal),
+            checksum: String(row.checksum),
+            applied_at_ms: Number(row.applied_at_ms),
+        });
+    }
+    return applied;
+}
+function assertIntegrity(db) {
+    const row = db.prepare("PRAGMA integrity_check").get();
+    const value = String(Object.values(row ?? {})[0] ?? "");
+    if (value !== "ok") {
+        throw new errors_1.ValidationError(`project DB integrity check failed: ${value}`);
+    }
+}
+function integrityCheck(db) {
+    try {
+        const row = db.prepare("PRAGMA integrity_check").get();
+        const value = String(Object.values(row ?? {})[0] ?? "");
+        if (value !== "ok") {
+            return {
+                name: "sqlite-integrity",
+                ok: false,
+                level: "fail",
+                detail: `integrity check failed: ${value}`,
+                errors: [`project DB integrity check failed: ${value}`],
+                warnings: [],
+            };
+        }
+        return {
+            name: "sqlite-integrity",
+            ok: true,
+            level: "ok",
+            detail: "SQLite integrity check ok",
+            errors: [],
+            warnings: [],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            name: "sqlite-integrity",
+            ok: false,
+            level: "fail",
+            detail: "failed to read SQLite database",
+            errors: [`failed to read project DB: ${message}`],
+            warnings: [],
+        };
+    }
+}
+function quoteIdentifier(value) {
+    return `"${value.replace(/"/g, '""')}"`;
+}
+function tableExists(db, tableName) {
+    const row = db
+        .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?")
+        .get(tableName);
+    return row !== undefined;
+}
+function migrationTableCheck(db, config) {
+    const errors = [];
+    if (!tableExists(db, config.db.migration_table)) {
+        errors.push(`migration table ${config.db.migration_table} missing; run mdkg db migrate`);
+    }
+    else {
+        const applied = readAppliedMigrations(db, config.db.migration_table);
+        const knownKeys = new Set(BUILTIN_MIGRATIONS.map((migration) => migration.key));
+        for (const appliedKey of applied.keys()) {
+            if (!knownKeys.has(appliedKey)) {
+                errors.push(`project DB contains unsupported migration ${appliedKey}`);
+            }
+        }
+        for (const migration of BUILTIN_MIGRATIONS) {
+            const row = applied.get(migration.key);
+            const checksum = checksumMigration(migration);
+            if (!row) {
+                errors.push(`migration ${migration.key} missing; run mdkg db migrate`);
+                continue;
+            }
+            if (row.ordinal !== migration.ordinal) {
+                errors.push(`migration order drift for ${migration.key}`);
+            }
+            if (row.checksum !== checksum) {
+                errors.push(`migration checksum drift for ${migration.key}`);
+            }
+        }
+    }
+    return {
+        name: "migrations",
+        ok: errors.length === 0,
+        level: errors.length === 0 ? "ok" : "fail",
+        detail: errors.length === 0 ? "migration metadata is current" : "migration metadata issues found",
+        errors,
+        warnings: [],
+    };
+}
+function transientFiles(root, runtimeFile) {
+    return ["-wal", "-shm", "-journal"]
+        .map((suffix) => {
+        const filePath = `${runtimeFile}${suffix}`;
+        return {
+            path: rel(root, filePath),
+            exists: fs_1.default.existsSync(filePath),
+            size: fs_1.default.existsSync(filePath) ? fs_1.default.statSync(filePath).size : 0,
+        };
+    })
+        .filter((item) => item.exists);
+}
+function transientStateCheck(root, runtimeFile) {
+    const present = transientFiles(root, runtimeFile);
+    const warnings = present.map((item) => `active transient SQLite file present: ${item.path}`);
+    return {
+        name: "transient-runtime-files",
+        ok: true,
+        level: warnings.length > 0 ? "warn" : "ok",
+        detail: warnings.length > 0 ? "active transient runtime files are present" : "no active transient runtime files found",
+        errors: [],
+        warnings,
+    };
+}
+function walkFiles(root) {
+    if (!fs_1.default.existsSync(root)) {
+        return [];
+    }
+    const entries = fs_1.default.readdirSync(root, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path_1.default.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...walkFiles(fullPath));
+        }
+        else if (entry.isFile()) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function tableCounts(db) {
+    const rows = db
+        .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name ASC")
+        .all();
+    return rows.map((row) => {
+        const name = String(row.name);
+        const countRow = db.prepare(`SELECT COUNT(*) AS count FROM ${quoteIdentifier(name)}`).get();
+        return { name, row_count: Number(countRow?.count ?? 0) };
+    });
+}
+function syncProjectMeta(db, config) {
+    const upsert = db.prepare("INSERT INTO project_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value WHERE value <> excluded.value");
+    upsert.run("tool", "mdkg");
+    upsert.run("schema_version", String(config.db.schema_version));
+    upsert.run("mdkg_version", (0, version_1.readPackageVersion)());
+    upsert.run("migration_table", config.db.migration_table);
+    upsert.run("last_migration_key", BUILTIN_MIGRATIONS[BUILTIN_MIGRATIONS.length - 1].key);
+}
+function runProjectDbMigrations(root, config) {
+    assertProjectDbReady(root, config);
+    const migrationFiles = ensureMigrationFiles(root, config);
+    const layout = (0, project_db_1.resolveConfiguredProjectDbLayout)(root, config.db);
+    fs_1.default.mkdirSync(path_1.default.dirname(layout.runtimeFile), { recursive: true });
+    const DatabaseSync = loadDatabaseCtor();
+    const db = new DatabaseSync(layout.runtimeFile);
+    const statuses = [];
+    let appliedCount = 0;
+    try {
+        db.exec("PRAGMA foreign_keys = ON;");
+        db.exec("PRAGMA synchronous = FULL;");
+        assertIntegrity(db);
+        db.exec(createMigrationTableSql(config.db.migration_table));
+        db.exec("BEGIN IMMEDIATE");
+        try {
+            const applied = readAppliedMigrations(db, config.db.migration_table);
+            const knownKeys = new Set(BUILTIN_MIGRATIONS.map((migration) => migration.key));
+            for (const appliedKey of applied.keys()) {
+                if (!knownKeys.has(appliedKey)) {
+                    throw new errors_1.ValidationError(`project DB contains unsupported migration ${appliedKey}`);
+                }
+            }
+            const now = Date.now();
+            for (const migration of BUILTIN_MIGRATIONS) {
+                const checksum = checksumMigration(migration);
+                const row = applied.get(migration.key);
+                if (row) {
+                    if (row.ordinal !== migration.ordinal) {
+                        throw new errors_1.ValidationError(`migration order drift for ${migration.key}`);
+                    }
+                    if (row.checksum !== checksum) {
+                        throw new errors_1.ValidationError(`migration checksum drift for ${migration.key}`);
+                    }
+                    statuses.push({
+                        key: migration.key,
+                        ordinal: migration.ordinal,
+                        checksum,
+                        status: "already_applied",
+                        applied_at_ms: row.applied_at_ms,
+                    });
+                    continue;
+                }
+                db.exec(migration.sql);
+                const appliedAt = now + appliedCount;
+                db
+                    .prepare(`INSERT INTO ${config.db.migration_table} (migration_key, ordinal, checksum, applied_at_ms, mdkg_version) VALUES (?, ?, ?, ?, ?)`)
+                    .run(migration.key, migration.ordinal, checksum, appliedAt, (0, version_1.readPackageVersion)());
+                statuses.push({
+                    key: migration.key,
+                    ordinal: migration.ordinal,
+                    checksum,
+                    status: "applied",
+                    applied_at_ms: appliedAt,
+                });
+                appliedCount += 1;
+            }
+            syncProjectMeta(db, config);
+            db.exec("COMMIT");
+        }
+        catch (err) {
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch {
+                // ignore rollback failures when no transaction is active
+            }
+            throw err;
+        }
+        assertIntegrity(db);
+    }
+    catch (err) {
+        if (err instanceof errors_1.ValidationError) {
+            throw err;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        throw new errors_1.ValidationError(`project DB migration failed: ${message}`);
+    }
+    finally {
+        db.close();
+    }
+    return {
+        action: "db-migrate",
+        ok: true,
+        database: rel(root, layout.runtimeFile),
+        schema_version: config.db.schema_version,
+        migration_table: config.db.migration_table,
+        applied_count: appliedCount,
+        skipped_count: statuses.length - appliedCount,
+        migrations: statuses,
+        migration_files: {
+            created: migrationFiles.created.sort(),
+            unchanged: migrationFiles.unchanged.sort(),
+        },
+    };
+}
+function verifyProjectDb(root, config) {
+    const layout = (0, project_db_1.resolveConfiguredProjectDbLayout)(root, config.db);
+    const checks = [];
+    checks.push({
+        name: "config",
+        ok: config.db.enabled && config.db.schema_version === project_db_1.PROJECT_DB_CONFIG_SCHEMA_VERSION,
+        level: config.db.enabled && config.db.schema_version === project_db_1.PROJECT_DB_CONFIG_SCHEMA_VERSION ? "ok" : "fail",
+        detail: !config.db.enabled
+            ? "project db is disabled"
+            : config.db.schema_version === project_db_1.PROJECT_DB_CONFIG_SCHEMA_VERSION
+                ? "project db config is enabled and supported"
+                : "project db schema version is unsupported",
+        errors: [
+            ...(!config.db.enabled ? ["project db is disabled; run mdkg db init"] : []),
+            ...(config.db.schema_version !== project_db_1.PROJECT_DB_CONFIG_SCHEMA_VERSION
+                ? [`unsupported project db schema_version ${config.db.schema_version}; supported ${project_db_1.PROJECT_DB_CONFIG_SCHEMA_VERSION}`]
+                : []),
+        ],
+        warnings: [],
+    });
+    checks.push(directoryCheck(root, layout.db, "project db root"));
+    checks.push(directoryCheck(root, layout.schema, "project db schema directory"));
+    checks.push(directoryCheck(root, layout.migrations, "project db migrations directory"));
+    checks.push(directoryCheck(root, layout.runtimeDir, "project db runtime directory"));
+    checks.push(directoryCheck(root, layout.stateDir, "project db state directory"));
+    checks.push(directoryCheck(root, layout.receipts, "project db receipts directory"));
+    const databasePath = rel(root, layout.runtimeFile);
+    if (!fs_1.default.existsSync(layout.runtimeFile)) {
+        checks.push({
+            name: "runtime-database",
+            ok: false,
+            level: "fail",
+            path: databasePath,
+            detail: "runtime database missing",
+            errors: [`${databasePath} missing; run mdkg db migrate`],
+            warnings: [],
+        });
+    }
+    else if (fs_1.default.statSync(layout.runtimeFile).isDirectory()) {
+        checks.push({
+            name: "runtime-database",
+            ok: false,
+            level: "fail",
+            path: databasePath,
+            detail: "runtime database path is not a file",
+            errors: [`${databasePath} exists and is not a file`],
+            warnings: [],
+        });
+    }
+    else {
+        checks.push({
+            name: "runtime-database",
+            ok: true,
+            level: "ok",
+            path: databasePath,
+            detail: "runtime database exists",
+            errors: [],
+            warnings: [],
+        });
+    }
+    checks.push(transientStateCheck(root, layout.runtimeFile));
+    const fatalBeforeOpen = checks.some((check) => !check.ok);
+    if (!fatalBeforeOpen && fs_1.default.existsSync(layout.runtimeFile)) {
+        checks.push(checkMigrationFiles(root, config));
+        const DatabaseSync = loadDatabaseCtor();
+        try {
+            const db = new DatabaseSync(layout.runtimeFile);
+            try {
+                checks.push(integrityCheck(db));
+                checks.push(migrationTableCheck(db, config));
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            checks.push({
+                name: "sqlite-open",
+                ok: false,
+                level: "fail",
+                path: databasePath,
+                detail: "failed to open runtime database",
+                errors: [`failed to open project DB: ${message}`],
+                warnings: [],
+            });
+        }
+    }
+    const errors = checks.flatMap((check) => check.errors.map((error) => `${check.name}: ${error}`));
+    const warnings = checks.flatMap((check) => check.warnings.map((warning) => `${check.name}: ${warning}`));
+    return {
+        action: "db-verify",
+        ok: errors.length === 0,
+        enabled: config.db.enabled,
+        database: databasePath,
+        schema_version: config.db.schema_version,
+        migration_table: config.db.migration_table,
+        checks,
+        warning_count: warnings.length,
+        failure_count: errors.length,
+        warnings,
+        errors,
+    };
+}
+function projectDbStats(root, config) {
+    const verification = verifyProjectDb(root, config);
+    if (!verification.ok) {
+        throw new errors_1.ValidationError(`db stats requires a valid project DB; run mdkg db verify`);
+    }
+    const layout = (0, project_db_1.resolveConfiguredProjectDbLayout)(root, config.db);
+    const DatabaseSync = loadDatabaseCtor();
+    const db = new DatabaseSync(layout.runtimeFile);
+    try {
+        const applied = readAppliedMigrations(db, config.db.migration_table);
+        const migrationStatuses = BUILTIN_MIGRATIONS
+            .map((migration) => {
+            const row = applied.get(migration.key);
+            return row
+                ? {
+                    key: migration.key,
+                    ordinal: migration.ordinal,
+                    checksum: row.checksum,
+                    status: "already_applied",
+                    applied_at_ms: row.applied_at_ms,
+                }
+                : undefined;
+        })
+            .filter((item) => item !== undefined);
+        const latestMigration = migrationStatuses[migrationStatuses.length - 1] ?? null;
+        const receiptFiles = walkFiles(layout.receipts);
+        return {
+            action: "db-stats",
+            ok: true,
+            enabled: config.db.enabled,
+            database: rel(root, layout.runtimeFile),
+            schema_version: config.db.schema_version,
+            migration_table: config.db.migration_table,
+            db_size: fs_1.default.statSync(layout.runtimeFile).size,
+            transient_files: transientFiles(root, layout.runtimeFile),
+            migration_count: migrationStatuses.length,
+            latest_migration: latestMigration,
+            tables: tableCounts(db),
+            state_snapshot: {
+                path: rel(root, layout.stateFile),
+                exists: fs_1.default.existsSync(layout.stateFile),
+                size: fs_1.default.existsSync(layout.stateFile) ? fs_1.default.statSync(layout.stateFile).size : 0,
+            },
+            receipt_files: {
+                path: rel(root, layout.receipts),
+                count: receiptFiles.length,
+            },
+        };
+    }
+    finally {
+        db.close();
+    }
+}