@lenne.tech/cli 1.21.0 → 1.22.0

package/build/lib/dev-patches.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addToGitignore = addToGitignore;
+exports.autoPatch = autoPatch;
+exports.patchApiConfig = patchApiConfig;
+exports.patchClaudeMd = patchClaudeMd;
+exports.patchNuxtConfig = patchNuxtConfig;
+exports.patchPlaywrightConfig = patchPlaywrightConfig;
+/**
+ * Idempotent patches applied by `lt dev migrate`.
+ *
+ * Goal: take a project that still has hardcoded `localhost:3000`
+ * defaults and make it env-aware so it can be served behind Caddy
+ * under `https://<slug>.localhost`.
+ *
+ * Each patch is a regex-based replace that matches only the legacy
+ * form. Already-patched files are no-ops.
+ */
+const fs_1 = require("fs");
+/** Append entry to .gitignore if not already present. */
+function addToGitignore(root, entry) {
+    const path = `${root}/.gitignore`;
+    let content = '';
+    if ((0, fs_1.existsSync)(path))
+        content = (0, fs_1.readFileSync)(path, 'utf8');
+    const lines = content.split(/\r?\n/);
+    if (lines.some((l) => l.trim() === entry || l.trim() === entry.replace(/\/$/, '')))
+        return false;
+    const ensured = `${(content.endsWith('\n') || content.length === 0 ? content : `${content}\n`) + entry}\n`;
+    (0, fs_1.writeFileSync)(path, ensured, 'utf8');
+    return true;
+}
+/** Run the appropriate patch based on filename. */
+function autoPatch(file) {
+    if (file.endsWith('config.env.ts'))
+        return patchApiConfig(file);
+    if (file.endsWith('nuxt.config.ts'))
+        return patchNuxtConfig(file);
+    if (file.endsWith('playwright.config.ts'))
+        return patchPlaywrightConfig(file);
+    return { file, patched: false, replacements: 0 };
+}
+/** API: `port: 3000,` → `port: Number(process.env.PORT) || 3000,`. */
+function patchApiConfig(file) {
+    if (!(0, fs_1.existsSync)(file))
+        return { file, patched: false, replacements: 0 };
+    const before = (0, fs_1.readFileSync)(file, 'utf8');
+    let count = 0;
+    const after = before.replace(/^(\s*)port:\s*3000\s*,$/gm, (_m, indent) => {
+        count++;
+        return `${indent}port: Number(process.env.PORT) || 3000,`;
+    });
+    if (count === 0)
+        return { file, patched: false, replacements: 0 };
+    (0, fs_1.writeFileSync)(file, after, 'utf8');
+    return { file, patched: true, replacements: count };
+}
+/**
+ * Inject a "Local Development (lt dev)" block with the project's
+ * concrete URLs into CLAUDE.md. Idempotent — re-running with the same
+ * URLs is a no-op; re-running with different URLs replaces the block
+ * in place.
+ */
+function patchClaudeMd(file, options) {
+    const { dbName, identity } = options;
+    const startMarker = '<!-- lt-dev:url-block:start -->';
+    const endMarker = '<!-- lt-dev:url-block:end -->';
+    const apiSub = identity.subdomains.api;
+    const appSub = identity.subdomains.app;
+    const lines = [
+        startMarker,
+        '## Local Development (lt dev)',
+        '',
+        `This project is registered with \`lt dev\` (slug: \`${identity.slug}\`). Use these commands to run alongside other lt projects without cross-wiring or port collisions:`,
+        '',
+        '```bash',
+        'lt dev up        # Start API + App behind Caddy with project-specific URLs',
+        'lt dev down      # Stop the detached processes + remove Caddy block',
+        'lt dev status    # Show running PIDs + bound URLs',
+        'lt dev doctor    # Diagnose Caddy/CA/DNS/port issues',
+        '```',
+        '',
+        '**Active URLs for THIS project:**',
+        '',
+    ];
+    if (appSub)
+        lines.push(`- App: \`https://${appSub.hostname}\``);
+    if (apiSub)
+        lines.push(`- API: \`https://${apiSub.hostname}\``);
+    if (dbName)
+        lines.push(`- DB:  \`mongodb://127.0.0.1/${dbName}\``);
+    lines.push('');
+    lines.push('Env vars set automatically by `lt dev up`: `BASE_URL`, `APP_URL`, `NUXT_API_URL`, `NUXT_PUBLIC_API_URL`, `NUXT_PUBLIC_SITE_URL`, `NUXT_PUBLIC_STORAGE_PREFIX`, `NSC__MONGOOSE__URI`, `DATABASE_URL`. **Never assume `localhost:3000` / `localhost:3001` for this project** — those are the framework defaults, not the active URLs.');
+    lines.push('');
+    lines.push(endMarker);
+    const block = lines.join('\n');
+    if (!(0, fs_1.existsSync)(file))
+        return { file, patched: false, replacements: 0 };
+    const content = (0, fs_1.readFileSync)(file, 'utf8');
+    const startIdx = content.indexOf(startMarker);
+    const endIdx = content.indexOf(endMarker);
+    let next;
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        const before = content.slice(0, startIdx);
+        const after = content.slice(endIdx + endMarker.length);
+        next = before + block + after;
+    }
+    else {
+        const sep = content.endsWith('\n\n') ? '' : content.endsWith('\n') ? '\n' : '\n\n';
+        next = `${content}${sep}${block}\n`;
+    }
+    if (next === content)
+        return { file, patched: false, replacements: 0 };
+    (0, fs_1.writeFileSync)(file, next, 'utf8');
+    return { file, patched: true, replacements: 1 };
+}
+/** App: hardcoded port + vite-proxy target → env-aware. */
+function patchNuxtConfig(file) {
+    if (!(0, fs_1.existsSync)(file))
+        return { file, patched: false, replacements: 0 };
+    const before = (0, fs_1.readFileSync)(file, 'utf8');
+    let count = 0;
+    let after = before.replace(/^(\s*)port:\s*3001\s*,$/gm, (_m, indent) => {
+        count++;
+        return `${indent}port: Number(process.env.PORT) || 3001,`;
+    });
+    after = after.replace(/target:\s*'http:\/\/localhost:3000'/g, () => {
+        count++;
+        return `target: process.env.NUXT_API_URL || 'http://localhost:3000'`;
+    });
+    if (count === 0)
+        return { file, patched: false, replacements: 0 };
+    (0, fs_1.writeFileSync)(file, after, 'utf8');
+    return { file, patched: true, replacements: count };
+}
+/**
+ * Playwright: hardcoded baseURL/host/url → env-aware, plus a top-of-file
+ * dotenv-load of `.lt-dev/.env` so external test runners (CLI, IDE, VS
+ * Code Playwright Extension) automatically pick up `lt dev up`'s URLs
+ * and the local Caddy CA — without requiring the parent shell to inherit
+ * any env.
+ *
+ * Patches applied (each idempotent):
+ *   1. Top-of-file: `if (existsSync('.lt-dev/.env')) loadEnv(...)` block,
+ *      bracketed by `// >>> lt-dev:bridge >>>` markers.
+ *   2. Hardcoded baseURL/host/url for `http://localhost:3001` →
+ *      `process.env.NUXT_PUBLIC_SITE_URL || 'http://localhost:3001'`.
+ */
+function patchPlaywrightConfig(file) {
+    if (!(0, fs_1.existsSync)(file))
+        return { file, patched: false, replacements: 0 };
+    const before = (0, fs_1.readFileSync)(file, 'utf8');
+    let count = 0;
+    let after = before;
+    // 1. URL-Patches.
+    for (const key of ['baseURL', 'host', 'url']) {
+        after = after.replace(new RegExp(`${key}:\\s*'http://localhost:3001'`, 'g'), () => {
+            count++;
+            return `${key}: process.env.NUXT_PUBLIC_SITE_URL || 'http://localhost:3001'`;
+        });
+    }
+    // 2. Top-of-file dotenv bridge — only inject if not already present.
+    const bridgeStart = '// >>> lt-dev:bridge >>>';
+    const bridgeEnd = '// <<< lt-dev:bridge <<<';
+    if (!after.includes(bridgeStart)) {
+        const bridgeBlock = [
+            bridgeStart,
+            '// Auto-load <root>/.lt-dev/.env when `lt dev up` is active so',
+            '// external test runners (CLI, IDE, VS Code Playwright Extension)',
+            '// pick up project URLs + Caddy CA without inheriting the parent shell.',
+            "import { existsSync as __ltDevExists, readFileSync as __ltDevRead } from 'node:fs';",
+            "import { resolve as __ltDevResolve } from 'node:path';",
+            "const __ltDevEnvFile = __ltDevResolve(process.cwd(), '.lt-dev/.env');",
+            'if (__ltDevExists(__ltDevEnvFile)) {',
+            '  for (const __ln of __ltDevRead(__ltDevEnvFile, "utf8").split(/\\r?\\n/)) {',
+            '    const __m = __ln.match(/^([A-Z][A-Z0-9_]*)=(.*)$/);',
+            '    if (__m && process.env[__m[1]] === undefined) process.env[__m[1]] = __m[2];',
+            '  }',
+            '}',
+            bridgeEnd,
+            '',
+        ].join('\n');
+        after = bridgeBlock + after;
+        count++;
+    }
+    if (count === 0)
+        return { file, patched: false, replacements: 0 };
+    (0, fs_1.writeFileSync)(file, after, 'utf8');
+    return { file, patched: true, replacements: count };
+}

package/build/lib/dev-process.js

@@ -0,0 +1,152 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkPortInUse = checkPortInUse;
+exports.killProcessGroup = killProcessGroup;
+exports.listenSnapshot = listenSnapshot;
+exports.spawnDetached = spawnDetached;
+/**
+ * Process + port helpers for `lt dev`.
+ *
+ * - `spawnDetached`: detached child whose stdout/stderr go to a log file.
+ *   The Claude Code session does NOT block waiting for it, and `lt dev down`
+ *   can SIGTERM the entire process group via `process.kill(-pid, …)`.
+ * - `listenSnapshot` / `checkPortInUse`: thin lsof wrappers used by
+ *   `lt dev doctor` to detect port collisions.
+ */
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const dev_state_1 = require("./dev-state");
+/**
+ * Check via `lsof` whether a single TCP port is bound by a LISTEN socket.
+ * Returns null if lsof is unavailable.
+ */
+function checkPortInUse(port) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return new Promise((resolve) => {
+            var _a;
+            const child = (0, child_process_1.spawn)('lsof', ['-iTCP', `-sTCP:LISTEN`, '-nP', `-iTCP:${port}`], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let errored = false;
+            (_a = child.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (b) => (stdout += String(b)));
+            child.on('error', () => (errored = true));
+            child.on('close', () => {
+                if (errored)
+                    return resolve(null);
+                const lines = stdout.split('\n').filter((l) => l && !l.startsWith('COMMAND'));
+                const matching = lines.find((l) => new RegExp(`[: ]${port}\\s.*\\(LISTEN\\)`).test(l) || l.includes(`:${port} (LISTEN)`));
+                if (!matching)
+                    return resolve({ inUse: false });
+                const parts = matching.trim().split(/\s+/);
+                resolve({ command: parts[0], inUse: true, pid: Number(parts[1]) });
+            });
+        });
+    });
+}
+/** Send SIGTERM to a detached process group; falls back to single-PID kill. */
+function killProcessGroup(pid) {
+    if (!(0, dev_state_1.isValidPid)(pid))
+        return false;
+    try {
+        process.kill(-pid, 'SIGTERM');
+        return true;
+    }
+    catch (_a) {
+        try {
+            process.kill(pid, 'SIGTERM');
+            return true;
+        }
+        catch (_b) {
+            return false;
+        }
+    }
+}
+/**
+ * Multi-port lsof snapshot — single subprocess for N ports.
+ * Returns map<port, {command, pid}> for ports that are in use.
+ */
+function listenSnapshot(ports) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const result = new Map();
+        if (ports.length === 0)
+            return result;
+        return new Promise((resolve) => {
+            var _a;
+            const portArgs = ports.flatMap((p) => ['-iTCP', `-iTCP:${p}`]);
+            const child = (0, child_process_1.spawn)('lsof', ['-sTCP:LISTEN', '-nP', ...portArgs], { stdio: ['ignore', 'pipe', 'pipe'] });
+            let stdout = '';
+            let errored = false;
+            (_a = child.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (b) => (stdout += String(b)));
+            child.on('error', () => (errored = true));
+            child.on('close', () => {
+                if (errored)
+                    return resolve(result);
+                for (const line of stdout.split('\n')) {
+                    if (!line || line.startsWith('COMMAND'))
+                        continue;
+                    const parts = line.trim().split(/\s+/);
+                    if (parts.length < 9)
+                        continue;
+                    const command = parts[0];
+                    const pid = Number(parts[1]);
+                    const name = parts[8];
+                    const portMatch = name.match(/:(\d+)$/);
+                    if (!portMatch)
+                        continue;
+                    const port = Number(portMatch[1]);
+                    if (ports.includes(port) && /\(LISTEN\)/.test(line)) {
+                        result.set(port, { command, pid });
+                    }
+                }
+                resolve(result);
+            });
+        });
+    });
+}
+/**
+ * Spawn a detached child whose stdio is redirected to a log file.
+ *
+ * The parent's copy of the log file descriptor is closed in `finally`
+ * — the child has already inherited its own fd before `spawn` returns,
+ * so closing prevents fd leaks and avoids racing-write artifacts on
+ * filesystems where O_APPEND is not atomic.
+ *
+ * Returns the child PID, or undefined if spawn failed.
+ */
+function spawnDetached(cmd, args, opts) {
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(opts.logFile), { recursive: true });
+    const out = (0, fs_1.openSync)(opts.logFile, 'a');
+    let child;
+    try {
+        child = (0, child_process_1.spawn)(cmd, args, {
+            cwd: opts.cwd,
+            detached: true,
+            env: opts.env,
+            stdio: ['ignore', out, out],
+        });
+        child.unref();
+        return child.pid;
+    }
+    catch (_a) {
+        return undefined;
+    }
+    finally {
+        try {
+            (0, fs_1.closeSync)(out);
+        }
+        catch (_b) {
+            /* fd already inherited by child; ignore */
+        }
+    }
+}

package/build/lib/{local-project.js → dev-project.js}

@@ -2,27 +2,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.apiNeedsPortPatch = apiNeedsPortPatch;
 exports.appNeedsPortPatch = appNeedsPortPatch;
+exports.deriveDbName = deriveDbName;
 exports.resolveLayout = resolveLayout;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const workspace_integration_1 = require("./workspace-integration");
 /**
- * Detect whether the API project still has the legacy hardcoded
- * `port: 3000`. Returns the absolute file path if a patch is needed,
- * null if already env-aware (or no file).
+ * Detect whether the API project still has the legacy hardcoded `port: 3000`.
+ * Returns the file path if a patch is needed, null otherwise.
  */
 function apiNeedsPortPatch(apiDir) {
     const file = (0, path_1.join)(apiDir, 'src', 'config.env.ts');
     if (!(0, fs_1.existsSync)(file))
         return null;
     const content = (0, fs_1.readFileSync)(file, 'utf8');
-    // Match `port: 3000,` exactly (not yet env-wrapped).
     return /port:\s*3000\s*,/.test(content) ? file : null;
 }
 /**
  * Detect whether the App project still has hardcoded `port: 3001` or a
  * hardcoded vite-proxy `target: 'http://localhost:3000'`. Returns an
- * array of absolute file paths that need patching.
+ * array of file paths that need patching.
  */
 function appNeedsPortPatch(appDir) {
     const candidates = [(0, path_1.join)(appDir, 'nuxt.config.ts'), (0, path_1.join)(appDir, 'playwright.config.ts')];
@@ -37,40 +36,43 @@ function appNeedsPortPatch(appDir) {
             /host:\s*'http:\/\/localhost:3001'/.test(c));
     });
 }
+/** Read `dbName` from the API config (defaults to `<slug>-local`). */
+function deriveDbName(apiDir, slug) {
+    if (apiDir) {
+        const cfg = (0, path_1.join)(apiDir, 'src', 'config.env.ts');
+        if ((0, fs_1.existsSync)(cfg)) {
+            const content = (0, fs_1.readFileSync)(cfg, 'utf8');
+            const match = content.match(/dbName:\s*['"`]([^'"`]+)['"`]/);
+            if (match)
+                return match[1];
+        }
+    }
+    return `${slug}-local`;
+}
 /**
- * Resolve the project layout starting from `cwd`. Walks up to find a
- * monorepo workspace if cwd is inside `projects/api/` or `projects/app/`.
+ * Resolve layout starting from `cwd`. Walks up to find a workspace if
+ * cwd is inside `projects/api/` or `projects/app/`.
  */
 function resolveLayout(cwd, filesystem) {
-    // Inside a sub-project? → walk to workspace root.
     const subContext = (0, workspace_integration_1.detectSubProjectContext)(cwd, filesystem);
-    if (subContext) {
+    if (subContext)
         return monorepoLayout(subContext.workspaceRoot);
-    }
-    // Workspace root directly?
     const layout = (0, workspace_integration_1.detectWorkspaceLayout)(cwd, filesystem);
-    if (layout.hasWorkspace) {
+    if (layout.hasWorkspace)
         return monorepoLayout(layout.workspaceDir);
-    }
-    // Walk up to find a workspace.
     const workspaceRoot = (0, workspace_integration_1.findWorkspaceRoot)(cwd, filesystem);
-    if (workspaceRoot) {
+    if (workspaceRoot)
         return monorepoLayout(workspaceRoot);
-    }
-    // Fall back to standalone — figure out if it's API or App.
+    // Standalone project — figure out if it's API or App.
     const isApi = (0, fs_1.existsSync)((0, path_1.join)(cwd, 'src', 'config.env.ts')) || (0, fs_1.existsSync)((0, path_1.join)(cwd, 'nest-cli.json'));
     const isApp = (0, fs_1.existsSync)((0, path_1.join)(cwd, 'nuxt.config.ts'));
     return {
         apiDir: isApi ? cwd : null,
         appDir: isApp ? cwd : null,
-        name: readPackageName(cwd) || basename(cwd),
         root: cwd,
         workspace: false,
     };
 }
-function basename(p) {
-    return p.replace(/\/+$/, '').split('/').pop() || 'project';
-}
 /** Build the layout for an lt-monorepo workspace root. */
 function monorepoLayout(workspaceRoot) {
     const apiDir = (0, path_1.join)(workspaceRoot, 'projects', 'api');
@@ -78,24 +80,7 @@ function monorepoLayout(workspaceRoot) {
     return {
         apiDir: (0, fs_1.existsSync)(apiDir) ? apiDir : null,
         appDir: (0, fs_1.existsSync)(appDir) ? appDir : null,
-        name: readPackageName(workspaceRoot) || basename(workspaceRoot),
         root: workspaceRoot,
         workspace: true,
     };
 }
-/** Read the `name` field from `package.json`, scrubbed to just the bare name (no scope). */
-function readPackageName(dir) {
-    const pkgPath = (0, path_1.join)(dir, 'package.json');
-    if (!(0, fs_1.existsSync)(pkgPath))
-        return null;
-    try {
-        const pkg = JSON.parse((0, fs_1.readFileSync)(pkgPath, 'utf8'));
-        if (!pkg.name)
-            return null;
-        // Strip npm scope: @lenne.tech/foo → foo
-        return pkg.name.includes('/') ? pkg.name.split('/').pop() : pkg.name;
-    }
-    catch (_a) {
-        return null;
-    }
-}

package/build/lib/dev-state.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paths = void 0;
+exports.allocateInternalPort = allocateInternalPort;
+exports.clearSession = clearSession;
+exports.isPidAlive = isPidAlive;
+exports.isValidPid = isValidPid;
+exports.loadRegistry = loadRegistry;
+exports.loadSession = loadSession;
+exports.saveRegistry = saveRegistry;
+exports.saveSession = saveSession;
+exports.takenInternalPorts = takenInternalPorts;
+/**
+ * State persistence for `lt dev`.
+ *
+ * Two stores:
+ * - Central registry at `~/.lenneTech/projects.json` — index of all
+ *   known projects, used by `lt dev status --all`, the Claude Code
+ *   plugin hook, and conflict detection.
+ * - Per-project state at `<root>/.lt-dev/state.json` — PIDs of the
+ *   currently running `lt dev up` session.
+ *
+ * Both files are JSON, atomically written, and schema-versioned.
+ */
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const REGISTRY_PATH = process.env.LT_DEV_REGISTRY_PATH || (0, path_1.join)((0, os_1.homedir)(), '.lenneTech', 'projects.json');
+const SESSION_DIR = '.lt-dev';
+const SESSION_FILE = 'state.json';
+/**
+ * Allocate a free internal port for a Caddy upstream.
+ *
+ * Strategy: try sequential ports starting from `start`, skipping any
+ * that are already in use. The range 4000-4999 is conventional for
+ * lt dev internal ports — well above the deprecated 3000/3001 range
+ * and safely below most reserved/system ranges.
+ */
+function allocateInternalPort(start, taken) {
+    for (let p = start; p < start + 1000; p++) {
+        if (!taken.has(p))
+            return p;
+    }
+    throw new Error(`No free internal port in range [${start}, ${start + 1000})`);
+}
+/** Remove session state file (called by `lt dev down`). */
+function clearSession(root) {
+    const file = (0, path_1.join)(root, SESSION_DIR, SESSION_FILE);
+    if ((0, fs_1.existsSync)(file)) {
+        try {
+            (0, fs_1.rmSync)(file);
+        }
+        catch (_a) {
+            /* best-effort */
+        }
+    }
+}
+/** Check whether a process with the given PID is currently alive. */
+function isPidAlive(pid) {
+    if (!isValidPid(pid))
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/** Validate a PID — positive integer, within plausible range. */
+function isValidPid(pid) {
+    return typeof pid === 'number' && Number.isInteger(pid) && pid > 0 && pid < 4194304;
+}
+/** Load the central registry; returns an empty one if missing or unreadable. */
+function loadRegistry() {
+    if (!(0, fs_1.existsSync)(REGISTRY_PATH))
+        return { projects: {}, version: 1 };
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)(REGISTRY_PATH, 'utf8'));
+        if (parsed && typeof parsed === 'object' && parsed.version === 1 && typeof parsed.projects === 'object') {
+            return parsed;
+        }
+    }
+    catch (_a) {
+        /* fall through */
+    }
+    return { projects: {}, version: 1 };
+}
+/** Load session state for a project root. */
+function loadSession(root) {
+    const file = (0, path_1.join)(root, SESSION_DIR, SESSION_FILE);
+    if (!(0, fs_1.existsSync)(file))
+        return null;
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)(file, 'utf8'));
+        if (parsed &&
+            typeof parsed === 'object' &&
+            typeof parsed.pids === 'object' &&
+            typeof parsed.startedAt === 'string') {
+            // Validate PIDs
+            const pids = {};
+            if (isValidPid(parsed.pids.api))
+                pids.api = parsed.pids.api;
+            if (isValidPid(parsed.pids.app))
+                pids.app = parsed.pids.app;
+            return { pids, startedAt: parsed.startedAt };
+        }
+    }
+    catch (_a) {
+        /* fall through */
+    }
+    return null;
+}
+/** Atomically persist the registry. */
+function saveRegistry(reg) {
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(REGISTRY_PATH), { recursive: true });
+    const tmp = `${REGISTRY_PATH}.tmp`;
+    (0, fs_1.writeFileSync)(tmp, JSON.stringify(reg, null, 2), 'utf8');
+    // rename is atomic on POSIX
+    (0, fs_1.writeFileSync)(REGISTRY_PATH, (0, fs_1.readFileSync)(tmp, 'utf8'), 'utf8');
+    try {
+        (0, fs_1.rmSync)(tmp);
+    }
+    catch (_a) {
+        /* best-effort */
+    }
+}
+/** Persist session state for a project root. */
+function saveSession(root, state) {
+    const dir = (0, path_1.join)(root, SESSION_DIR);
+    (0, fs_1.mkdirSync)(dir, { recursive: true });
+    (0, fs_1.writeFileSync)((0, path_1.join)(dir, SESSION_FILE), JSON.stringify(state, null, 2), 'utf8');
+}
+/** Collect all internal ports already claimed across the registry. */
+function takenInternalPorts(reg, excludeSlug) {
+    const ports = new Set();
+    for (const [slug, entry] of Object.entries(reg.projects)) {
+        if (slug === excludeSlug)
+            continue;
+        if (entry.internalPorts.api)
+            ports.add(entry.internalPorts.api);
+        if (entry.internalPorts.app)
+            ports.add(entry.internalPorts.app);
+    }
+    return ports;
+}
+/** Path constants exported for tests + status displays. */
+exports.paths = {
+    registry: REGISTRY_PATH,
+    sessionDir: SESSION_DIR,
+    sessionFile: SESSION_FILE,
+};