@camstack/server 1.0.5 → 1.0.6

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
+    }
+}

package/dist/launcher.js

@@ -42,12 +42,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * 1. Run AddonInstaller.ensureRequiredPackages (zero core dependencies)
  * 2. Create symlinks so @camstack/system resolves from data/addons/
  * 3. Dynamically import main.ts (which has static @camstack/system imports)
+ *
+ * Load-order invariant: @camstack/system is imported DYNAMICALLY inside
+ * launch() AFTER applyPendingFrameworkSwap runs, so the swapped framework
+ * code is what gets loaded. NEVER add a top-level static import of
+ * @camstack/system here — that would load the OLD framework before the swap.
  */
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const tar = __importStar(require("tar"));
 const yaml = __importStar(require("js-yaml"));
-const system_1 = require("@camstack/system");
+const launcher_framework_swap_js_1 = require("./launcher-framework-swap.js");
+const framework_nodepath_js_1 = require("./framework-nodepath.js");
 /** Path of the manifest file embedded inside every archive. */
 const ARCHIVE_MANIFEST_NAME = '.camstack-backup-manifest.json';
 /** Resolve the data directory from env or default */
@@ -169,12 +175,15 @@ function readConfigYaml(dataDir) {
  * `symlink` is a dev-time convenience that points data/addons/<pkg>
  * directly at the workspace source dir — never set in shipped
  * containers or Electron bundles.
+ *
+ * `bootstrapSchema` is passed in (not imported at module top) so this
+ * helper can be called after the dynamic @camstack/system import in launch().
  */
-function readBootstrapInstallSource(dataDir) {
+function readBootstrapInstallSource(dataDir, bootstrapSchema) {
     const raw = readConfigYaml(dataDir);
     if (raw === null)
         return undefined;
-    const validation = system_1.bootstrapSchema.safeParse(raw);
+    const validation = bootstrapSchema.safeParse(raw);
     if (!validation.success)
         return undefined;
     return parseInstallSource(validation.data.bootstrap.installSource);
@@ -189,12 +198,34 @@ function readBootstrapInstallSource(dataDir) {
  * launcher runs before @camstack/system is imported and must stay free of
  * core dependencies. Just yaml.load + bootstrapSchema (kernel) for
  * shape validation.
+ *
+ * `bootstrapSchema` is passed in (not imported at module top) so this
+ * helper can be called after the dynamic @camstack/system import in launch().
+ */
+/**
+ * Derive the bootstrap package list from THIS server's own package.json — the
+ * `@camstack/addon-*` deps plus `@camstack/system` (which ships the required
+ * infrastructure builtins). Read by absolute path (the package.json sits one
+ * level up from this launcher's dist dir), so it works in the slim image where
+ * the `@camstack/*` node_modules symlinks are stripped. Mirrors
+ * `AddonInstaller.deriveBootstrapList`, but without `require.resolve`.
  */
-function readBootstrapRequiredAddons(dataDir) {
+function deriveBootstrapFromSelf() {
+    try {
+        const pkgPath = path.resolve(__dirname, '..', 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return Object.keys(pkg.dependencies ?? {}).filter((name) => name.startsWith('@camstack/addon-') || name === '@camstack/system');
+    }
+    catch (err) {
+        console.warn(`[launcher] could not derive bootstrap list from package.json: ${err instanceof Error ? err.message : String(err)}`);
+        return [];
+    }
+}
+function readBootstrapRequiredAddons(dataDir, bootstrapSchema) {
     const raw = readConfigYaml(dataDir);
     if (raw === null)
         return null;
-    const validation = system_1.bootstrapSchema.safeParse(raw);
+    const validation = bootstrapSchema.safeParse(raw);
     if (!validation.success) {
         console.warn(`[launcher] config.yaml failed bootstrapSchema validation: ${validation.error.message}`);
         return null;
@@ -210,10 +241,26 @@ async function launch() {
     // `CAMSTACK_ADDONS_DIR` lets the Docker/Electron images point at their
     // node_modules path (e.g. /data/node_modules); dev keeps `<dataDir>/addons`.
     const addonsDir = process.env['CAMSTACK_ADDONS_DIR'] ?? path.resolve(dataDir, 'addons');
+    // ── Framework swap ────────────────────────────────────────────────────────
+    // MUST run before @camstack/system is loaded so the NEW framework code is
+    // what gets required. Both helpers are zero-dep (no @camstack imports).
+    // Roll back an unconfirmed prior swap (crash-loop guard), then apply any
+    // freshly-staged swap.
+    const frameworkDir = process.env['CAMSTACK_FRAMEWORK_DIR'];
+    const rb = (0, launcher_framework_swap_js_1.rollbackUnconfirmedFrameworkSwap)(dataDir, frameworkDir);
+    if (rb.rolledBack)
+        console.log('[launcher] Rolled back an unconfirmed framework update');
+    const fsw = (0, launcher_framework_swap_js_1.applyPendingFrameworkSwap)(dataDir, frameworkDir);
+    if (fsw.applied)
+        console.log(`[launcher] Applied staged framework update (job ${fsw.jobId ?? '?'})`);
+    // ── End framework swap ────────────────────────────────────────────────────
     // 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);
+    // @camstack/system is imported DYNAMICALLY here — AFTER applyPendingFrameworkSwap —
+    // so the swapped framework code is what gets loaded. Never import it at module top.
+    const { AddonInstaller, bootstrapSchema, detectWorkspacePackagesDir } = await Promise.resolve().then(() => __importStar(require('@camstack/system')));
     // Install source resolution:
     //   1. CAMSTACK_BUNDLED_ADDONS_DIR — set by Electron-packaged builds
     //      to <resourcesPath>/addons. Pre-built addons ship with the
@@ -230,7 +277,7 @@ async function launch() {
     //   CAMSTACK_BUNDLED_ADDONS_DIR: Electron path, forces 'local'.
     //   bootstrap.installSource (config.yaml): same set as env. Env wins.
     const rawEnvSource = process.env['CAMSTACK_INSTALL_SOURCE'];
-    const yamlSource = readBootstrapInstallSource(dataDir);
+    const yamlSource = readBootstrapInstallSource(dataDir, bootstrapSchema);
     const explicitSource = parseInstallSource(rawEnvSource) ?? yamlSource;
     const bundledDir = process.env['CAMSTACK_BUNDLED_ADDONS_DIR'];
     let workspaceDir = null;
@@ -241,14 +288,14 @@ async function launch() {
         console.log(`[launcher] Using bundled addons from ${bundledDir}`);
     }
     else if (explicitSource === 'local' || explicitSource === 'symlink') {
-        workspaceDir = (0, system_1.detectWorkspacePackagesDir)(__dirname);
+        workspaceDir = detectWorkspacePackagesDir(__dirname);
         if (workspaceDir === null) {
             console.warn(`[launcher] installSource=${explicitSource} requested but no workspace ` +
                 `packages/ dir found from ${__dirname} — falling back to 'npm'`);
             resolvedSource = 'npm';
         }
     }
-    const installer = new system_1.AddonInstaller({
+    const installer = new AddonInstaller({
         addonsDir,
         workspacePackagesDir: workspaceDir ?? undefined,
         installSource: resolvedSource,
@@ -257,15 +304,21 @@ async function launch() {
     // kernel's hard-coded REQUIRED_PACKAGES. The kernel never reaches into
     // SQL before this list is installed; everything here must be a known
     // package name that can be resolved from the workspace, the bundle, or
-    // npm. Default (undefined) → fall back to the in-kernel constant.
-    const bootstrapRequired = readBootstrapRequiredAddons(dataDir);
-    if (bootstrapRequired !== null) {
-        console.log(`[launcher] bootstrap.requiredAddons from config.yaml: ${bootstrapRequired.length} packages`);
-        await installer.ensureRequiredPackages(bootstrapRequired);
-    }
-    else {
-        await installer.ensureRequiredPackages();
-    }
+    // npm. Default (undefined) → derive from THIS server's own package.json.
+    //
+    // We derive the list here rather than relying on
+    // `AddonInstaller.REQUIRED_PACKAGES` (which uses
+    // `require.resolve('@camstack/server/package.json')`): in the slim image the
+    // `@camstack/*` workspace symlinks are stripped and NODE_PATH is only
+    // extended to include `/repo/node_modules` LATER in this launcher, so that
+    // static resolves to an EMPTY list at import time — and `@camstack/system`
+    // (which provides the storage-provider / settings / logging infra builtins)
+    // would never get installed into data/addons, aborting boot with
+    // "No addon provides required infrastructure capability storage-provider".
+    // The server's own package.json is always readable next to this launcher.
+    const bootstrapRequired = readBootstrapRequiredAddons(dataDir, bootstrapSchema) ?? deriveBootstrapFromSelf();
+    console.log(`[launcher] bootstrap: ${bootstrapRequired.length} required package(s)`);
+    await installer.ensureRequiredPackages(bootstrapRequired);
     // Reconcile the install manifest with what is on disk. Addons baked
     // into the image are copied straight into addonsDir by the container
     // entrypoint and never pass through an install codepath, so they are
@@ -309,7 +362,11 @@ async function launch() {
     // etc); the server-local node_modules has direct deps. Listing
     // both covers every realistic resolution.
     const workspaceRootNodeModules = path.resolve(serverDir, '..', '..', 'node_modules');
-    const extraNodePaths = [nodeModulesDir, workspaceRootNodeModules].filter((p) => fs.existsSync(p));
+    const frameworkPaths = (0, framework_nodepath_js_1.frameworkNodePaths)(process.env['CAMSTACK_FRAMEWORK_DIR'], fs.existsSync);
+    const extraNodePaths = [...frameworkPaths, nodeModulesDir, workspaceRootNodeModules].filter((p) => fs.existsSync(p));
+    if (frameworkPaths.length > 0) {
+        console.log(`[launcher] Framework dir on NODE_PATH: ${frameworkPaths[0]}`);
+    }
     if (extraNodePaths.length > 0) {
         const sep = process.platform === 'win32' ? ';' : ':';
         process.env['NODE_PATH'] = process.env['NODE_PATH']

package/dist/lifecycle-journal-path.js

@@ -0,0 +1,41 @@
+"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.lifecycleJobsDir = lifecycleJobsDir;
+const path = __importStar(require("node:path"));
+/** Single source of truth for the lifecycle job journal directory. */
+function lifecycleJobsDir(dataDir) {
+    return path.join(dataDir, 'lifecycle', 'jobs');
+}