@camstack/server 1.2.425 → 1.2.427

package/dist/launcher.js

@@ -55,7 +55,6 @@ const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const yaml = __importStar(require("js-yaml"));
-const tar = __importStar(require("tar"));
 const addon_root_inventory_js_1 = require("./addon-root-inventory.js");
 const bootstrap_packages_js_1 = require("./bootstrap-packages.js");
 const first_boot_addon_plan_js_1 = require("./first-boot-addon-plan.js");
@@ -63,84 +62,9 @@ const addon_realign_plan_js_1 = require("./core/addon/addon-realign-plan.js");
 const closure_node_modules_js_1 = require("./closure-node-modules.js");
 const framework_nodepath_js_1 = require("./framework-nodepath.js");
 const package_inventory_js_1 = require("./package-inventory.js");
-/** Path of the manifest file embedded inside every archive. */
-const ARCHIVE_MANIFEST_NAME = '.camstack-backup-manifest.json';
+const pending_restore_js_1 = require("./pending-restore.js");
 /** Resolve the data directory from env or default */
 const DATA_DIR = process.env['CAMSTACK_DATA'] ?? 'camstack-data';
-const RESTORE_MARKER_FILE = '.pending-restore.json';
-/**
- * Apply a pending system-restore archive over `dataDir` if a marker is
- * present. Runs BEFORE the addon installer so the restored snapshot's
- * `addons/` folder is what `ensureRequiredPackages` picks up.
- *
- * Marker contract is owned by `SystemBackupService.scheduleRestoreMarker`
- * (packages/core/src/builtins/system-backup) — kept inline here so the
- * launcher remains zero-core-deps. Schema:
- *   { archivePath: string, requestedAt: number, source: string }
- *
- * Failure modes:
- *   - marker malformed → log + leave it in place (operator visibility)
- *   - archive missing  → log + clear marker (auto-recover from stale)
- *   - tar fails        → throw → launcher exits non-zero, marker preserved
- */
-async function applyPendingRestore(dataDir) {
-    const markerPath = path.join(dataDir, RESTORE_MARKER_FILE);
-    if (!fs.existsSync(markerPath))
-        return;
-    console.log(`[launcher] Pending restore marker found at ${markerPath}`);
-    let archivePath = null;
-    let locations = null;
-    try {
-        const raw = fs.readFileSync(markerPath, 'utf-8');
-        const parsed = JSON.parse(raw);
-        if (typeof parsed === 'object' &&
-            parsed != null &&
-            typeof parsed.archivePath === 'string') {
-            archivePath = parsed.archivePath;
-        }
-        const locField = parsed.locations;
-        if (Array.isArray(locField) && locField.every((l) => typeof l === 'string')) {
-            locations = locField;
-        }
-    }
-    catch (err) {
-        console.error('[launcher] Restore marker malformed — leaving in place:', err);
-        return;
-    }
-    if (archivePath == null) {
-        console.error('[launcher] Restore marker missing archivePath — clearing');
-        fs.rmSync(markerPath, { force: true });
-        return;
-    }
-    if (!fs.existsSync(archivePath)) {
-        console.error(`[launcher] Restore archive ${archivePath} missing — clearing marker`);
-        fs.rmSync(markerPath, { force: true });
-        return;
-    }
-    const scope = locations ? ` (only: ${locations.join(', ')})` : '';
-    console.log(`[launcher] Restoring snapshot from ${archivePath} into ${dataDir}${scope}`);
-    fs.mkdirSync(dataDir, { recursive: true });
-    // Same filter logic SystemBackupService.extractArchive uses — kept
-    // inline here so the launcher stays zero-core-deps. The shape is
-    // straightforward enough to duplicate.
-    const allowedPrefixes = locations
-        ? locations.map((loc) => loc.replace(/^\.\//, '').replace(/\/+$/, ''))
-        : null;
-    await tar.extract({
-        file: archivePath,
-        cwd: dataDir,
-        filter: (p) => {
-            if (p === ARCHIVE_MANIFEST_NAME || p === `./${ARCHIVE_MANIFEST_NAME}`)
-                return false;
-            if (!allowedPrefixes)
-                return true;
-            const normalized = p.replace(/^\.\//, '');
-            return allowedPrefixes.some((prefix) => normalized === prefix || normalized.startsWith(`${prefix}/`));
-        },
-    });
-    fs.rmSync(markerPath, { force: true });
-    console.log('[launcher] Restore complete; marker cleared');
-}
 /** Narrow `CAMSTACK_INSTALL_SOURCE` env into the typed union. */
 function parseInstallSource(value) {
     if (value === 'npm' || value === 'local' || value === 'symlink')
@@ -321,7 +245,7 @@ async function launch() {
     // Restore must happen first so the snapshot's `addons/` is what the
     // installer + symlink step pick up — otherwise we'd install a stale
     // set and overwrite it a step later.
-    await applyPendingRestore(dataDir);
+    await (0, pending_restore_js_1.applyPendingRestore)(dataDir, (line) => console.log(line));
     // @camstack/system is imported DYNAMICALLY here — AFTER the active framework
     // dir + NODE_PATH are resolved above — so the correct framework copy is what
     // gets loaded. Never import it at module top.

package/dist/pending-restore.js

@@ -0,0 +1,199 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyPendingRestore = applyPendingRestore;
+/**
+ * The boot-time system restore — the ONLY restore there is. The launcher calls
+ * it before the addon installer and before any runner starts, so nothing has a
+ * file of the data dir open.
+ *
+ * Marker contract is owned by `SystemBackupService.scheduleRestoreMarker`
+ * (`packages/system/src/builtins/system-backup`) — read inline here so the
+ * launcher stays free of `@camstack/*` runtime imports. Schema:
+ *   { archivePath: string, requestedAt: number, source: string, locations?: string[] }
+ *
+ * After the extraction, SQLite databases get their own step
+ * (`sqlite-restore.ts`, D693): an owner snapshot is promoted over its database,
+ * and a sidecar the archive did not bring is dropped, because SQLite would
+ * replay a stale `-wal` onto the restored file.
+ *
+ * Failure modes:
+ *   - marker malformed → log + leave it in place (operator visibility)
+ *   - archive missing  → log + clear marker (auto-recover from stale)
+ *   - tar fails        → throw → launcher exits non-zero, marker preserved
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const tar = __importStar(require("tar"));
+const sqlite_restore_js_1 = require("./sqlite-restore.js");
+/** Path of the manifest file embedded inside every archive. */
+const ARCHIVE_MANIFEST_NAME = '.camstack-backup-manifest.json';
+const RESTORE_MARKER_FILE = '.pending-restore.json';
+/**
+ * Apply a pending system-restore archive over `dataDir` if a marker is
+ * present. Runs BEFORE the addon installer so the restored snapshot's
+ * `addons/` folder is what `ensureRequiredPackages` picks up.
+ */
+async function applyPendingRestore(dataDir, log) {
+    const markerPath = path.join(dataDir, RESTORE_MARKER_FILE);
+    if (!fs.existsSync(markerPath))
+        return;
+    log(`[launcher] Pending restore marker found at ${markerPath}`);
+    let archivePath = null;
+    let locations = null;
+    try {
+        const raw = fs.readFileSync(markerPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' && parsed != null) {
+            if ('archivePath' in parsed && typeof parsed.archivePath === 'string') {
+                archivePath = parsed.archivePath;
+            }
+            if ('locations' in parsed &&
+                Array.isArray(parsed.locations) &&
+                parsed.locations.every((l) => typeof l === 'string')) {
+                locations = parsed.locations.filter((l) => typeof l === 'string');
+            }
+        }
+    }
+    catch (err) {
+        log(`[launcher] Restore marker malformed — leaving in place: ${String(err)}`);
+        return;
+    }
+    if (archivePath == null) {
+        log('[launcher] Restore marker missing archivePath — clearing');
+        fs.rmSync(markerPath, { force: true });
+        return;
+    }
+    if (!fs.existsSync(archivePath)) {
+        log(`[launcher] Restore archive ${archivePath} missing — clearing marker`);
+        fs.rmSync(markerPath, { force: true });
+        return;
+    }
+    const scope = locations ? ` (only: ${locations.join(', ')})` : '';
+    log(`[launcher] Restoring snapshot from ${archivePath} into ${dataDir}${scope}`);
+    fs.mkdirSync(dataDir, { recursive: true });
+    const allowedPrefixes = locations
+        ? locations.map((loc) => loc.replace(/^\.\//, '').replace(/\/+$/, ''))
+        : null;
+    const inScope = (normalized) => !allowedPrefixes ||
+        allowedPrefixes.some((prefix) => normalized === prefix || normalized.startsWith(`${prefix}/`));
+    // What the archive says it carries — read before the extraction, from the
+    // manifest `createArchive` writes as the archive's FIRST entry.
+    const promised = await readPromisedSnapshots(archivePath, log);
+    // Every path this extraction writes — the SQLite step decides from it alone.
+    const extracted = [];
+    await tar.extract({
+        file: archivePath,
+        cwd: dataDir,
+        filter: (p) => {
+            if (p === ARCHIVE_MANIFEST_NAME || p === `./${ARCHIVE_MANIFEST_NAME}`)
+                return false;
+            const normalized = p.replace(/^\.\//, '').replace(/\/+$/, '');
+            const keep = inScope(normalized);
+            if (keep)
+                extracted.push(normalized);
+            return keep;
+        },
+    });
+    (0, sqlite_restore_js_1.applySqliteRestore)(dataDir, (0, sqlite_restore_js_1.planSqliteRestore)(extracted), log);
+    // A database the archive promised and the extraction did not write was NOT
+    // restored. Say so before "Restore complete" — silence would read as done.
+    const { missing, outOfScope } = (0, sqlite_restore_js_1.missingPromisedSnapshots)(promised, extracted, inScope);
+    for (const rel of missing) {
+        log(`[launcher] WARNING Restore: the archive promised the database snapshot ${rel} but carried none — that database was NOT restored`);
+    }
+    for (const rel of outOfScope) {
+        log(`[launcher] Restore: the database snapshot ${rel} is outside the chosen locations — that database was left as it was`);
+    }
+    fs.rmSync(markerPath, { force: true });
+    log('[launcher] Restore complete; marker cleared');
+}
+/**
+ * The `sqliteSnapshots[].snapshotPath` the archive's manifest lists. Reads only
+ * up to the manifest (the first entry) and stops. An archive with no manifest,
+ * or one from before D693, promises nothing.
+ */
+function readPromisedSnapshots(archivePath, log) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (paths) => {
+            if (settled)
+                return;
+            settled = true;
+            reader.destroy();
+            resolve(paths);
+        };
+        const chunks = [];
+        const parser = new tar.Parser({
+            onReadEntry: (entry) => {
+                const name = entry.path.replace(/^\.\//, '');
+                if (name !== ARCHIVE_MANIFEST_NAME) {
+                    entry.resume();
+                    return;
+                }
+                entry.on('data', (chunk) => chunks.push(chunk));
+                entry.on('end', () => done(promisedIn(Buffer.concat(chunks).toString('utf-8'), log)));
+            },
+        });
+        parser.on('end', () => done([]));
+        const reader = fs.createReadStream(archivePath);
+        reader.on('error', () => done([]));
+        reader.pipe(parser);
+    });
+}
+function promisedIn(json, log) {
+    try {
+        const parsed = JSON.parse(json);
+        if (typeof parsed !== 'object' || parsed === null || !('sqliteSnapshots' in parsed))
+            return [];
+        const list = parsed.sqliteSnapshots;
+        if (!Array.isArray(list))
+            return [];
+        const out = [];
+        for (const item of list) {
+            if (typeof item === 'object' &&
+                item !== null &&
+                'snapshotPath' in item &&
+                typeof item.snapshotPath === 'string') {
+                out.push(item.snapshotPath);
+            }
+        }
+        return out;
+    }
+    catch (err) {
+        log(`[launcher] Restore: the archive manifest could not be read — ${String(err)}`);
+        return [];
+    }
+}

package/dist/sqlite-restore.js

@@ -0,0 +1,150 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQLITE_SNAPSHOT_SUFFIX = void 0;
+exports.planSqliteRestore = planSqliteRestore;
+exports.applySqliteRestore = applySqliteRestore;
+exports.missingPromisedSnapshots = missingPromisedSnapshots;
+/**
+ * The SQLite half of the boot-time restore (D693). Runs in the launcher,
+ * BEFORE any runner exists — on databases nobody has open, which is the one
+ * place a filesystem call may touch a `.db` / `-wal` / `-shm` (the D679 guard
+ * names this file in its allowlist, with that reason).
+ *
+ * Two jobs, both about the sidecars SQLite pairs a database with on its first
+ * open:
+ *
+ * 1. **Promote an owner snapshot.** An archive made since D693 carries
+ *    `<db>.backup-snapshot` in place of the live database. It is a verified,
+ *    self-contained copy (rollback journal, no sidecars). Restoring it means:
+ *    delete the target's `<db>-wal`, `-shm` and `-journal`, then rename the
+ *    snapshot over `<db>`.
+ * 2. **Guard a legacy archive.** An archive from before D693 carries `<db>`
+ *    as a file, sometimes without its `-wal`. Whatever sidecar the archive did
+ *    NOT bring is deleted from the target.
+ *
+ * Why the sidecars must go: a `-wal` left by the database being replaced (a
+ * crash, a kill, a runner that never checkpointed) has valid frames, and
+ * SQLite replays them onto whatever file sits beside it. The restored copy
+ * would come up as a mix of two databases.
+ *
+ * Zero `@camstack/*` runtime imports, like the launcher that calls it. The
+ * suffix is spelled here and pinned to `DATABASE_SNAPSHOT_SUFFIX` by
+ * `pending-restore-sqlite.spec.ts`.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** Mirrors `DATABASE_SNAPSHOT_SUFFIX` in `@camstack/types` (spec-pinned). */
+exports.SQLITE_SNAPSHOT_SUFFIX = '.backup-snapshot';
+const SIDECARS = ['-wal', '-shm', '-journal'];
+const DATABASE_SUFFIXES = ['.db', '.sqlite', '.sqlite3'];
+/** Decide, from the paths an extraction wrote, what the target needs. */
+function planSqliteRestore(extracted) {
+    const written = new Set(extracted);
+    const promote = [];
+    const dropSidecars = new Map();
+    for (const rel of written) {
+        if (rel.endsWith(exports.SQLITE_SNAPSHOT_SUFFIX)) {
+            const database = rel.slice(0, -exports.SQLITE_SNAPSHOT_SUFFIX.length);
+            promote.push(rel);
+            // Whatever sits beside the target belongs to the database being replaced.
+            dropSidecars.set(database, [...SIDECARS]);
+        }
+        else if (DATABASE_SUFFIXES.some((suffix) => rel.endsWith(suffix))) {
+            const missing = SIDECARS.filter((sidecar) => !written.has(rel + sidecar));
+            if (missing.length > 0 && !dropSidecars.has(rel))
+                dropSidecars.set(rel, missing);
+        }
+    }
+    return { promote: promote.sort(), dropSidecars };
+}
+/** Make the entries just removed or renamed in `dir` durable. */
+function fsyncDirectory(dir) {
+    const fd = fs.openSync(dir, 'r');
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Apply a plan under `dataDir`. Each deletion and promotion is one log line,
+ * and each touched directory is fsynced before the caller clears its marker —
+ * a power cut after "Restore complete" must not bring the stale WAL back.
+ */
+function applySqliteRestore(dataDir, plan, log, syncDirectory = fsyncDirectory) {
+    const touched = new Set();
+    for (const [database, sidecars] of plan.dropSidecars) {
+        for (const sidecar of sidecars) {
+            const stale = path.join(dataDir, database + sidecar);
+            if (!fs.existsSync(stale))
+                continue;
+            fs.rmSync(stale, { force: true });
+            touched.add(path.dirname(stale));
+            log(`[launcher] Restore: dropped stale ${database}${sidecar} — it belonged to the database being replaced`);
+        }
+    }
+    for (const snapshot of plan.promote) {
+        const database = snapshot.slice(0, -exports.SQLITE_SNAPSHOT_SUFFIX.length);
+        fs.renameSync(path.join(dataDir, snapshot), path.join(dataDir, database));
+        touched.add(path.dirname(path.join(dataDir, database)));
+        log(`[launcher] Restore: promoted the owner snapshot ${snapshot} → ${database}`);
+    }
+    for (const dir of touched) {
+        // A durability nicety, never a reason to abort boot — a launcher that
+        // threw here would fail every boot while the marker stays.
+        try {
+            syncDirectory(dir);
+        }
+        catch (err) {
+            log(`[launcher] WARNING Restore: could not fsync ${dir} (${String(err)}) — continuing`);
+        }
+    }
+}
+function missingPromisedSnapshots(promised, extracted, inScope) {
+    const written = new Set(extracted);
+    const missing = [];
+    const outOfScope = [];
+    for (const rel of promised) {
+        if (written.has(rel))
+            continue;
+        if (inScope(rel))
+            missing.push(rel);
+        else
+            outOfScope.push(rel);
+    }
+    return { missing, outOfScope };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/server",
-  "version": "1.2.425",
+  "version": "1.2.427",
   "license": "MIT",
   "private": false,
   "files": [
@@ -37,17 +37,17 @@
     ]
   },
   "dependencies": {
-    "@camstack/addon-admin-ui": "1.2.296",
+    "@camstack/addon-admin-ui": "1.2.297",
     "@camstack/addon-agent-ui": "1.2.159",
     "@camstack/addon-auth": "1.2.123",
     "@camstack/addon-decoder-nodeav": "1.2.115",
     "@camstack/addon-notifiers": "1.2.121",
     "@camstack/addon-pipeline": "1.2.313",
-    "@camstack/addon-pipeline-orchestrator": "1.2.268",
-    "@camstack/addon-post-analysis": "1.2.306",
+    "@camstack/addon-pipeline-orchestrator": "1.2.269",
+    "@camstack/addon-post-analysis": "1.2.307",
     "@camstack/sdk": "1.2.118",
-    "@camstack/system": "1.2.328",
-    "@camstack/types": "1.2.281",
+    "@camstack/system": "1.2.329",
+    "@camstack/types": "1.2.282",
     "@camstack/ui-library": "1.2.217",
     "@fastify/compress": "^9.0.0",
     "@fastify/cookie": "^11.0.2",