@camstack/server 1.2.88 → 1.2.90

package/dist/launcher-framework-swap.js

@@ -0,0 +1,408 @@
+"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.writePendingFrameworkSwap = writePendingFrameworkSwap;
+exports.applyPendingFrameworkSwap = applyPendingFrameworkSwap;
+exports.rollbackUnconfirmedFrameworkSwap = rollbackUnconfirmedFrameworkSwap;
+exports.confirmFrameworkSwapHealthy = confirmFrameworkSwapHealthy;
+/**
+ * Launcher zero-dep framework swap/rollback helpers.
+ *
+ * These run before @camstack/system is imported — zero @camstack imports.
+ * Only node:fs + node:path. All writes are atomic (tmpfile+rename).
+ * All reads tolerate missing/corrupt files (no-op result).
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const lifecycle_journal_path_js_1 = require("./lifecycle-journal-path.js");
+// ---------------------------------------------------------------------------
+// Marker file names
+// ---------------------------------------------------------------------------
+const PENDING_SWAP_MARKER = '.pending-framework-swap.json';
+const SWAP_CONFIRM_MARKER = '.framework-swap-confirm.json';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Write a JSON file atomically via a tmp sibling + rename. */
+function writeJsonAtomic(filePath, value) {
+    const tmp = `${filePath}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(value), 'utf-8');
+    fs.renameSync(tmp, filePath);
+}
+/** Read + parse JSON, returning null on any error (missing / corrupt). */
+function readJsonSafe(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Validate that a parsed value matches the PendingSwapMarker shape. */
+function isPendingSwapMarker(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    if (typeof v['jobId'] !== 'string')
+        return false;
+    if (typeof v['taskId'] !== 'string')
+        return false;
+    if (!Array.isArray(v['packages']))
+        return false;
+    for (const pkg of v['packages']) {
+        if (typeof pkg !== 'object' || pkg === null)
+            return false;
+        const p = pkg;
+        if (typeof p['name'] !== 'string')
+            return false;
+        if (typeof p['stagedPath'] !== 'string')
+            return false;
+        if (typeof p['backupPath'] !== 'string')
+            return false;
+    }
+    if (typeof v['requestedAtMs'] !== 'number')
+        return false;
+    if (v['schemaVersion'] !== 1)
+        return false;
+    return true;
+}
+/** Validate that a parsed value matches the SwapConfirmMarker shape. */
+function isSwapConfirmMarker(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    if (typeof v['jobId'] !== 'string')
+        return false;
+    if (typeof v['taskId'] !== 'string')
+        return false;
+    if (!Array.isArray(v['backups']))
+        return false;
+    for (const b of v['backups']) {
+        if (typeof b !== 'object' || b === null)
+            return false;
+        const entry = b;
+        if (typeof entry['name'] !== 'string')
+            return false;
+        if (typeof entry['backupPath'] !== 'string')
+            return false;
+        if (typeof entry['livePath'] !== 'string')
+            return false;
+    }
+    if (typeof v['appliedAtMs'] !== 'number')
+        return false;
+    if (typeof v['bootAttempts'] !== 'number')
+        return false;
+    if (v['schemaVersion'] !== 1)
+        return false;
+    return true;
+}
+/**
+ * Patch a specific task inside a journal job file atomically.
+ * Reads `<dataDir>/lifecycle/jobs/<jobId>.json`, updates tasks[taskId],
+ * and writes back atomically. Silently no-ops on any read/write error.
+ */
+function patchJournalTask(dataDir, jobId, taskId, patch) {
+    const jobFile = path.join((0, lifecycle_journal_path_js_1.lifecycleJobsDir)(dataDir), `${jobId}.json`);
+    const raw = readJsonSafe(jobFile);
+    if (typeof raw !== 'object' || raw === null)
+        return;
+    const job = raw;
+    const tasks = job['tasks'];
+    if (!Array.isArray(tasks))
+        return;
+    const updatedTasks = tasks.map((task) => {
+        if (typeof task !== 'object' || task === null)
+            return task;
+        const t = task;
+        if (t['taskId'] !== taskId)
+            return task;
+        const updated = { ...t, phase: patch.phase };
+        if (patch.error !== undefined)
+            updated['error'] = patch.error;
+        if (patch.finishedAtMs !== undefined)
+            updated['finishedAtMs'] = patch.finishedAtMs;
+        return updated;
+    });
+    try {
+        writeJsonAtomic(jobFile, { ...job, tasks: updatedTasks });
+    }
+    catch {
+        // journal patch is best-effort — never crash the launcher
+    }
+}
+/** Copy a directory tree cross-device (fallback for EXDEV rename errors). */
+function moveDirCrossDevice(src, dest) {
+    fs.cpSync(src, dest, { recursive: true });
+    fs.rmSync(src, { recursive: true, force: true });
+}
+/**
+ * Write the `.pending-framework-swap.json` marker atomically.
+ * Co-located with the reader (`applyPendingFrameworkSwap`) for symmetry.
+ * Zero @camstack deps — this file runs before @camstack/system is imported.
+ */
+function writePendingFrameworkSwap(dataDir, marker) {
+    const markerPath = path.join(dataDir, PENDING_SWAP_MARKER);
+    writeJsonAtomic(markerPath, marker);
+}
+/**
+ * Apply a pending framework swap if a `.pending-framework-swap.json` marker
+ * exists in `dataDir`. Swaps each listed package atomically:
+ *   1. Backup: rename live → backupPath
+ *   2. Swap: rename staged → live (EXDEV fallback: cpSync + rmSync)
+ *
+ * On any mid-loop failure: restores already-swapped packages, deletes the
+ * marker, returns `{ applied: false }`.
+ * On success: writes `.framework-swap-confirm.json`, patches the journal
+ * task to `applied`, deletes the swap marker, returns `{ applied: true, jobId }`.
+ */
+function applyPendingFrameworkSwap(dataDir, frameworkDir) {
+    if (!frameworkDir)
+        return { applied: false };
+    const markerPath = path.join(dataDir, PENDING_SWAP_MARKER);
+    if (!fs.existsSync(markerPath))
+        return { applied: false };
+    const raw = readJsonSafe(markerPath);
+    if (!isPendingSwapMarker(raw)) {
+        // malformed — delete to prevent blocking future updates
+        try {
+            fs.rmSync(markerPath, { force: true });
+        }
+        catch {
+            // ignore deletion error
+        }
+        return { applied: false };
+    }
+    const marker = raw;
+    const swapped = [];
+    for (const pkg of marker.packages) {
+        const livePath = path.join(frameworkDir, 'node_modules', pkg.name);
+        try {
+            // Step 1: backup live dir if it exists
+            if (fs.existsSync(livePath)) {
+                fs.mkdirSync(path.dirname(pkg.backupPath), { recursive: true });
+                fs.renameSync(livePath, pkg.backupPath);
+            }
+            // Step 2: move staged dir to live
+            try {
+                fs.mkdirSync(path.dirname(livePath), { recursive: true });
+                fs.renameSync(pkg.stagedPath, livePath);
+            }
+            catch (err) {
+                if (err.code === 'EXDEV') {
+                    fs.mkdirSync(path.dirname(livePath), { recursive: true });
+                    moveDirCrossDevice(pkg.stagedPath, livePath);
+                }
+                else {
+                    throw err;
+                }
+            }
+            swapped.push({ livePath, backupPath: pkg.backupPath });
+        }
+        catch {
+            // Restore all already-swapped packages
+            for (const done of swapped) {
+                try {
+                    if (fs.existsSync(done.livePath)) {
+                        fs.rmSync(done.livePath, { recursive: true, force: true });
+                    }
+                    if (fs.existsSync(done.backupPath)) {
+                        fs.mkdirSync(path.dirname(done.livePath), { recursive: true });
+                        fs.renameSync(done.backupPath, done.livePath);
+                    }
+                }
+                catch {
+                    // best-effort restore
+                }
+            }
+            // Delete the pending marker so the next boot doesn't retry a broken swap
+            try {
+                fs.rmSync(markerPath, { force: true });
+            }
+            catch {
+                // ignore
+            }
+            return { applied: false };
+        }
+    }
+    // All packages swapped successfully — write confirm marker
+    const backups = marker.packages.map((pkg) => ({
+        name: pkg.name,
+        backupPath: pkg.backupPath,
+        livePath: path.join(frameworkDir, 'node_modules', pkg.name),
+    }));
+    const confirmMarker = {
+        jobId: marker.jobId,
+        taskId: marker.taskId,
+        backups,
+        appliedAtMs: Date.now(),
+        bootAttempts: 0,
+        schemaVersion: 1,
+    };
+    // Write confirm marker — if this fails, restore everything and fail the apply
+    try {
+        writeJsonAtomic(path.join(dataDir, SWAP_CONFIRM_MARKER), confirmMarker);
+    }
+    catch {
+        // Confirm marker write failed — restore all swapped packages and fail the apply
+        for (const done of swapped) {
+            try {
+                if (fs.existsSync(done.livePath)) {
+                    fs.rmSync(done.livePath, { recursive: true, force: true });
+                }
+                if (fs.existsSync(done.backupPath)) {
+                    fs.mkdirSync(path.dirname(done.livePath), { recursive: true });
+                    fs.renameSync(done.backupPath, done.livePath);
+                }
+            }
+            catch {
+                // best-effort restore
+            }
+        }
+        // Delete the pending marker so the next boot doesn't retry
+        try {
+            fs.rmSync(markerPath, { force: true });
+        }
+        catch {
+            // ignore
+        }
+        return { applied: false };
+    }
+    // Patch journal task → applied (best-effort, doesn't fail the apply)
+    patchJournalTask(dataDir, marker.jobId, marker.taskId, { phase: 'applied' });
+    // Delete the swap marker
+    try {
+        fs.rmSync(markerPath, { force: true });
+    }
+    catch {
+        // ignore
+    }
+    return { applied: true, jobId: marker.jobId };
+}
+/**
+ * Check for an unconfirmed framework swap on boot.
+ *
+ * - `bootAttempts === 0`: this is the probation boot. Increment to 1,
+ *   rewrite the marker, return `{ rolledBack: false }`.
+ * - `bootAttempts >= 1`: the previous probation boot crashed / didn't call
+ *   `confirmFrameworkSwapHealthy`. Restore all backups, patch the journal
+ *   task to `failed`, delete the confirm marker, return `{ rolledBack: true }`.
+ */
+function rollbackUnconfirmedFrameworkSwap(dataDir, frameworkDir) {
+    if (!frameworkDir)
+        return { rolledBack: false };
+    const confirmPath = path.join(dataDir, SWAP_CONFIRM_MARKER);
+    if (!fs.existsSync(confirmPath))
+        return { rolledBack: false };
+    const raw = readJsonSafe(confirmPath);
+    if (!isSwapConfirmMarker(raw))
+        return { rolledBack: false };
+    const confirm = raw;
+    if (confirm.bootAttempts === 0) {
+        // Probation boot — increment attempts and let this boot proceed
+        const updated = { ...confirm, bootAttempts: 1 };
+        try {
+            writeJsonAtomic(confirmPath, updated);
+        }
+        catch {
+            // ignore write failure
+        }
+        return { rolledBack: false };
+    }
+    // bootAttempts >= 1: probation boot didn't become healthy — rollback
+    for (const backup of confirm.backups) {
+        try {
+            if (fs.existsSync(backup.livePath)) {
+                fs.rmSync(backup.livePath, { recursive: true, force: true });
+            }
+            if (fs.existsSync(backup.backupPath)) {
+                fs.mkdirSync(path.dirname(backup.livePath), { recursive: true });
+                fs.renameSync(backup.backupPath, backup.livePath);
+            }
+        }
+        catch {
+            // best-effort restore
+        }
+    }
+    patchJournalTask(dataDir, confirm.jobId, confirm.taskId, {
+        phase: 'failed',
+        error: 'framework update rolled back — boot did not become healthy',
+        finishedAtMs: Date.now(),
+    });
+    try {
+        fs.rmSync(confirmPath, { force: true });
+    }
+    catch {
+        // ignore
+    }
+    return { rolledBack: true };
+}
+/**
+ * Called by post-boot health check once the hub is confirmed healthy after
+ * a framework swap. Deletes all backups and the confirm marker so the old
+ * framework packages are cleaned up.
+ */
+function confirmFrameworkSwapHealthy(dataDir) {
+    const confirmPath = path.join(dataDir, SWAP_CONFIRM_MARKER);
+    if (!fs.existsSync(confirmPath))
+        return;
+    const raw = readJsonSafe(confirmPath);
+    if (!isSwapConfirmMarker(raw)) {
+        // corrupt marker — still delete it
+        try {
+            fs.rmSync(confirmPath, { force: true });
+        }
+        catch {
+            // ignore
+        }
+        return;
+    }
+    const confirm = raw;
+    // Delete all backup dirs
+    for (const backup of confirm.backups) {
+        try {
+            fs.rmSync(backup.backupPath, { recursive: true, force: true });
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
+    // Delete the confirm marker
+    try {
+        fs.rmSync(confirmPath, { force: true });
+    }
+    catch {
+        // ignore
+    }
+}