@lenne.tech/cli 1.39.0 → 1.41.0

package/build/commands/dev/status.js

@@ -58,25 +58,38 @@ const StatusCommand = {
                     // port) count toward the health summary.
                     const comps = [];
                     if (e.internalPorts.api) {
-                        comps.push((0, dev_state_1.classifyComponentHealth)({ pid: session === null || session === void 0 ? void 0 : session.pids.api, portBound: snap.has(e.internalPorts.api) }));
+                        comps.push((0, dev_state_1.classifyComponentHealth)({
+                            pid: session === null || session === void 0 ? void 0 : session.pids.api,
+                            portBound: snap.has(e.internalPorts.api),
+                            startedAt: session === null || session === void 0 ? void 0 : session.startedAt,
+                        }));
                     }
                     if (e.internalPorts.app) {
-                        comps.push((0, dev_state_1.classifyComponentHealth)({ pid: session === null || session === void 0 ? void 0 : session.pids.app, portBound: snap.has(e.internalPorts.app) }));
+                        comps.push((0, dev_state_1.classifyComponentHealth)({
+                            pid: session === null || session === void 0 ? void 0 : session.pids.app,
+                            portBound: snap.has(e.internalPorts.app),
+                            startedAt: session === null || session === void 0 ? void 0 : session.startedAt,
+                        }));
                     }
-                    const allRunning = comps.length > 0 && comps.every((h) => h === 'running');
-                    const anyRunning = comps.some((h) => h === 'running');
-                    const anyCrashed = comps.some((h) => h === 'crashed');
+                    // Aggregate the per-component health into one honest stack glyph
+                    // (pure, unit-tested in dev-state). Presentation (glyph + note) stays here.
+                    const stack = (0, dev_state_1.summarizeStackHealth)(comps);
                     let status;
                     let note = '';
-                    if (allRunning) {
+                    if (stack === 'running') {
                         status = colors.green('●');
                     }
-                    else if (anyRunning) {
+                    else if (stack === 'degraded') {
                         // Some up, some down — honest "partially up" rather than green.
                         status = colors.yellow('◐');
                         note = colors.yellow('  degraded — `lt dev up` to restart the down half');
                     }
-                    else if (anyCrashed) {
+                    else if (stack === 'starting') {
+                        // Still booting after a recent `lt dev up` — not crashed, give it a moment.
+                        status = colors.cyan('◐');
+                        note = colors.dim('  starting — booting, give it a moment');
+                    }
+                    else if (stack === 'crashed') {
                         status = colors.yellow('◐');
                         note = colors.yellow('  crashed — `lt dev up` to restart');
                     }
@@ -177,16 +190,20 @@ const StatusCommand = {
             const apiHealth = (0, dev_state_1.classifyComponentHealth)({
                 pid: session.pids.api,
                 portBound: entry.internalPorts.api ? snap.has(entry.internalPorts.api) : false,
+                startedAt: session.startedAt,
             });
             const appHealth = (0, dev_state_1.classifyComponentHealth)({
                 pid: session.pids.app,
                 portBound: entry.internalPorts.app ? snap.has(entry.internalPorts.app) : false,
+                startedAt: session.startedAt,
             });
             const label = (health) => health === 'running'
                 ? colors.green('running')
-                : health === 'crashed'
-                    ? colors.yellow('crashed (supervisor up, port not listening)')
-                    : colors.red('dead');
+                : health === 'starting'
+                    ? colors.cyan('starting (booting — port not bound yet)')
+                    : health === 'crashed'
+                        ? colors.yellow('crashed (supervisor up, port not listening)')
+                        : colors.red('dead');
             if (session.pids.api !== undefined || entry.internalPorts.api) {
                 info(`  api: ${label(apiHealth)} (pid ${(_a = session.pids.api) !== null && _a !== void 0 ? _a : '-'})`);
             }
@@ -208,10 +225,17 @@ const StatusCommand = {
             // half and leaves the healthy one running.
             const apiPresent = session.pids.api !== undefined || !!entry.internalPorts.api;
             const appPresent = session.pids.app !== undefined || !!entry.internalPorts.app;
-            const down = [
-                apiPresent && apiHealth !== 'running' ? 'api' : null,
-                appPresent && appHealth !== 'running' ? 'app' : null,
-            ].filter((c) => c !== null);
+            // A `starting` component is booting, not down — don't tell the user to
+            // restart a healthy stack that just needs a few more seconds. Partition is
+            // pure + unit-tested in dev-state.
+            const { down, starting } = (0, dev_state_1.partitionComponentStates)([
+                { health: apiHealth, name: 'api', present: apiPresent },
+                { health: appHealth, name: 'app', present: appPresent },
+            ]);
+            if (starting.length > 0) {
+                info('');
+                info(colors.cyan(`  ${starting.join(' + ')} still booting — give it a few seconds, then re-run \`lt dev status\`.`));
+            }
             if (down.length > 0) {
                 const crashed = (apiPresent && apiHealth === 'crashed') || (appPresent && appHealth === 'crashed');
                 info('');

package/build/commands/dev/up.js

@@ -9,9 +9,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.help = void 0;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const caddy_1 = require("../../lib/caddy");
+const dev_api_launch_1 = require("../../lib/dev-api-launch");
 const dev_env_1 = require("../../lib/dev-env");
 const dev_env_bridge_1 = require("../../lib/dev-env-bridge");
 const dev_identity_1 = require("../../lib/dev-identity");
@@ -84,7 +86,7 @@ const UpCommand = {
     hidden: false,
     name: 'up',
     run: (toolbox) => __awaiter(void 0, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
         const { filesystem, parameters, print: { colors, error, info, success, warning }, } = toolbox;
         const layout = (0, dev_project_1.resolveLayout)(filesystem.cwd(), filesystem);
         if (!layout.apiDir && !layout.appDir) {
@@ -112,6 +114,10 @@ const UpCommand = {
         // suffixed so the stack is fully isolated from the base dev session and every
         // other ticket. Without a ticket this is the plain project identity.
         const { dbName, identity, ticket } = (0, dev_ticket_1.resolveDevIdentity)(layout, { ticket: parameters.options.ticket });
+        // `--api-compiled`: run the API compiled (`node dist`) instead of ts-node.
+        // Trades hot reload for stability — ts-node intermittently dies under browser
+        // load without a stacktrace (DEV-2525); `lt dev test` already runs compiled.
+        const apiCompiled = (0, dev_api_launch_1.isApiCompiledRequested)(parameters.options);
         // Guard against two checkouts of the SAME project (same package.json "name"
         // → same slug → shared URLs / ports / DB / Caddy block). If another checkout
         // is already RUNNING under this slug, abort with a clear message — otherwise
@@ -254,16 +260,33 @@ const UpCommand = {
         // ── Health-aware (re)start decision ──────────────────────────────────────
         // Probe the just-resolved ports so we can tell a still-serving component
         // from a crashed one (supervisor PID alive, port free). Only dead/crashed
-        // components get (re)started; a healthy one keeps running untouched.
+        // components get (re)started; a running one keeps serving untouched — and a
+        // still-BOOTING one (`starting`: PID alive, port not bound yet, within the
+        // startup grace window after a recent `up`) is ALSO kept, not force-restarted.
+        // Passing `startedAt` is what lets the classifier distinguish that boot window
+        // from a real crash — otherwise a re-run of `lt dev up` during the API's slow
+        // boot would kill the still-booting component and reset its progress (the very
+        // false-positive the `starting` state exists to prevent).
         const hasApi = Boolean(layout.apiDir && (0, fs_1.existsSync)((0, path_1.join)(layout.apiDir, 'package.json')) && apiPort);
         const hasApp = Boolean(layout.appDir && (0, fs_1.existsSync)((0, path_1.join)(layout.appDir, 'package.json')) && appPort);
         const healthSnap = yield (0, dev_process_1.listenSnapshot)([apiPort, appPort].filter((p) => typeof p === 'number'));
         const apiHealth = hasApi
-            ? (0, dev_state_1.classifyComponentHealth)({ pid: existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.api, portBound: !!apiPort && healthSnap.has(apiPort) })
+            ? (0, dev_state_1.classifyComponentHealth)({
+                pid: existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.api,
+                portBound: !!apiPort && healthSnap.has(apiPort),
+                startedAt: existingSession === null || existingSession === void 0 ? void 0 : existingSession.startedAt,
+            })
             : undefined;
         const appHealth = hasApp
-            ? (0, dev_state_1.classifyComponentHealth)({ pid: existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.app, portBound: !!appPort && healthSnap.has(appPort) })
+            ? (0, dev_state_1.classifyComponentHealth)({
+                pid: existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.app,
+                portBound: !!appPort && healthSnap.has(appPort),
+                startedAt: existingSession === null || existingSession === void 0 ? void 0 : existingSession.startedAt,
+            })
             : undefined;
+        // A component we leave running untouched is either serving (`running`) or
+        // still within its boot grace window (`starting`).
+        const isKeepable = (h) => h === 'running' || h === 'starting';
         // All present components already serving → nothing to do.
         const presentHealth = [apiHealth, appHealth].filter((h) => h !== undefined);
         if (presentHealth.length > 0 && presentHealth.every((h) => h === 'running')) {
@@ -283,18 +306,21 @@ const UpCommand = {
                 process.exit();
             return 'dev up: already running';
         }
-        // Partial restart — at least one component is healthy and at least one is
-        // down. Announce what we keep vs. restart so the user sees the honest state.
-        const partialRestart = presentHealth.some((h) => h === 'running');
+        // Partial restart — at least one component is kept (running or still booting)
+        // and at least one is down. Announce what we keep vs. restart so the user sees
+        // the honest state. A `starting` component is kept (booting), NOT restarted.
+        const partialRestart = presentHealth.some(isKeepable);
         if (partialRestart) {
-            if (apiHealth === 'running')
-                info(colors.dim(`api healthy (pid ${existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.api}) → keeping`));
-            else if (apiHealth)
-                warning(`api ${apiHealth} (port ${apiPort} not serving) → restarting`);
-            if (appHealth === 'running')
-                info(colors.dim(`app healthy (pid ${existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.app}) → keeping`));
-            else if (appHealth)
-                warning(`app ${appHealth} (port ${appPort} not serving) → restarting`);
+            const announceDecision = (name, h, pid, port) => {
+                if (h === 'running')
+                    info(colors.dim(`${name} healthy (pid ${pid}) → keeping`));
+                else if (h === 'starting')
+                    info(colors.cyan(`${name} still booting (pid ${pid}) → keeping (grace window)`));
+                else if (h)
+                    warning(`${name} ${h} (port ${port} not serving) → restarting`);
+            };
+            announceDecision('api', apiHealth, existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.api, apiPort);
+            announceDecision('app', appHealth, existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.app, appPort);
         }
         // Caddy block + reload.
         const routes = [];
@@ -321,7 +347,7 @@ const UpCommand = {
         if (identity.subdomains.app)
             info(`  app: https://${identity.subdomains.app.hostname}  →  127.0.0.1:${appPort}`);
         if (identity.subdomains.api)
-            info(`  api: https://${identity.subdomains.api.hostname}  →  127.0.0.1:${apiPort}`);
+            info(`  api: https://${identity.subdomains.api.hostname}  →  127.0.0.1:${apiPort}${apiCompiled ? colors.dim('  (compiled, no hot reload)') : ''}`);
         if (identity.subdomains.api)
             info(`  db:  mongodb://127.0.0.1/${dbName}`);
         info('');
@@ -350,9 +376,15 @@ const UpCommand = {
                 yield (0, dev_process_1.terminateProcessGroup)(bound.pid);
         });
         if (hasApi && layout.apiDir && apiPort) {
-            if (apiHealth === 'running') {
+            if (isKeepable(apiHealth)) {
                 pids.api = existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.api;
                 kept.push('api');
+                // `--api-compiled` only takes effect when the API (re)starts; a running or
+                // still-booting API is kept as-is (force-restarting it would contradict the
+                // keep logic), so tell the user how to switch a currently-live ts-node API
+                // to compiled.
+                if (apiCompiled)
+                    info(colors.dim('  --api-compiled: API already running/booting — `lt dev down` first to switch it.'));
             }
             else {
                 yield reclaimPort(existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.api, apiPort, apiHealth !== null && apiHealth !== void 0 ? apiHealth : 'dead');
@@ -361,11 +393,20 @@ const UpCommand = {
                 // regenerate a foreign lockfile + crash on un-approved build
                 // scripts when run against an npm-only project.
                 const apiPm = (0, dev_package_manager_1.pickPackageManager)(layout.apiDir);
-                const apiResult = (0, dev_process_1.spawnDetached)(apiPm.bin, apiPm.runScript('start'), {
-                    cwd: layout.apiDir,
-                    env: devEnv.api.env,
-                    logFile: (0, path_1.join)(layout.root, '.lt-dev', 'api.log'),
-                });
+                const apiLogFile = (0, path_1.join)(layout.root, '.lt-dev', 'api.log');
+                const apiResult = apiCompiled
+                    ? yield (0, dev_api_launch_1.startCompiledApi)({
+                        apiDir: layout.apiDir,
+                        env: devEnv.api.env,
+                        log: { info, warn: warning },
+                        logFile: apiLogFile,
+                        pm: apiPm,
+                    })
+                    : (0, dev_process_1.spawnDetached)(apiPm.bin, apiPm.runScript('start'), {
+                        cwd: layout.apiDir,
+                        env: devEnv.api.env,
+                        logFile: apiLogFile,
+                    });
                 if (apiResult) {
                     pids.api = apiResult.pid;
                     started.push('api');
@@ -376,7 +417,7 @@ const UpCommand = {
             }
         }
         if (hasApp && layout.appDir && appPort) {
-            if (appHealth === 'running') {
+            if (isKeepable(appHealth)) {
                 pids.app = existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.app;
                 kept.push('app');
             }
@@ -397,28 +438,38 @@ const UpCommand = {
                 }
             }
         }
-        // Persist the session (PIDs) — merging kept (healthy) + freshly started PIDs.
-        // The registry entry (ports) was already reserved atomically above. On a
-        // partial restart we preserve the original session start time.
-        const startedAt = existingSession && kept.length > 0 ? existingSession.startedAt : new Date().toISOString();
+        // Persist the session (PIDs) — merging kept (running/booting) + freshly
+        // started PIDs. The registry entry (ports) was already reserved atomically
+        // above. Reset the session clock ONLY when something was actually (re)started:
+        //   - A freshly restarted component MUST get "now" so its startup grace window
+        //     is measured from its real start — inheriting a stale `startedAt` would
+        //     make a just-restarted, still-booting component read as `crashed` during
+        //     its own boot (a kept `running` component is classified by port-bound, not
+        //     `startedAt`, so a fresh timestamp never mis-ages it).
+        //   - When nothing was started (all kept — e.g. both still booting), preserve
+        //     the original so repeated `up` during a boot can't keep extending the
+        //     grace window indefinitely.
+        const startedAt = started.length > 0 ? new Date().toISOString() : ((_h = existingSession === null || existingSession === void 0 ? void 0 : existingSession.startedAt) !== null && _h !== void 0 ? _h : new Date().toISOString());
         (0, dev_state_1.saveSession)(layout.root, { pids, startedAt });
         // Write the ENV bridge so external tools (Playwright, IDE test runners,
         // custom shell scripts) can pick up the URLs without inheriting our shell.
         const bridgePath = (0, dev_env_bridge_1.writeEnvBridge)(layout.root, devEnv, dbName);
         info(colors.dim(`ENV bridge: ${bridgePath}`));
         const summary = started.length === 0
-            ? 'Nothing restarted'
+            ? kept.length > 0
+                ? `Kept ${kept.join('+')} (already running or booting)`
+                : 'Nothing restarted'
             : kept.length > 0
                 ? `Restarted ${started.join('+')} (kept ${kept.join('+')})`
                 : `Started ${started.join('+')}`;
-        success(`${summary}: api pid=${(_h = pids.api) !== null && _h !== void 0 ? _h : '-'}, app pid=${(_j = pids.app) !== null && _j !== void 0 ? _j : '-'}`);
+        success(`${summary}: api pid=${(_j = pids.api) !== null && _j !== void 0 ? _j : '-'}, app pid=${(_k = pids.app) !== null && _k !== void 0 ? _k : '-'}`);
         // Echo the bound URLs next to the PIDs as well — the "Starting" block
         // prints them before the spawn, but on a long boot log they scroll out
         // of view, so repeating them here keeps PID + URL visually grouped.
         printProjectUrls(info, {
-            apiHostname: (_k = identity.subdomains.api) === null || _k === void 0 ? void 0 : _k.hostname,
+            apiHostname: (_l = identity.subdomains.api) === null || _l === void 0 ? void 0 : _l.hostname,
             apiUpstreamPort: apiPort,
-            appHostname: (_l = identity.subdomains.app) === null || _l === void 0 ? void 0 : _l.hostname,
+            appHostname: (_m = identity.subdomains.app) === null || _m === void 0 ? void 0 : _m.hostname,
             appUpstreamPort: appPort,
             dbName: identity.subdomains.api ? dbName : undefined,
         });
@@ -446,7 +497,7 @@ const UpCommand = {
                 try {
                     mainRepoRoot = (0, dev_ticket_1.gitMainRepoRoot)(layout.root);
                 }
-                catch (_m) {
+                catch (_o) {
                     /* not a git repo — registry prune still applies */
                 }
                 const mainLayout = (0, dev_project_1.resolveLayout)(mainRepoRoot, filesystem);
@@ -493,7 +544,7 @@ const UpCommand = {
                     }
                 }
             }
-            catch (_o) {
+            catch (_p) {
                 /* never block `up` on cleanup */
             }
         }
@@ -502,4 +553,28 @@ const UpCommand = {
         return `dev up: api=${pids.api}, app=${pids.app}`;
     }),
 };
-module.exports = UpCommand;
+exports.help = {
+    aliases: ['u'],
+    configuration: 'Ephemeral dev-orchestration flags — no lt.config counterpart. Override the spawn binary for both processes via the LT_PNPM_BIN env var.',
+    description: 'Start the API + App behind Caddy under stable https://<slug>.localhost URLs. Health-aware and idempotent: re-running (re)starts only the component(s) that are not truly serving.',
+    examples: ['dev up', 'dev up --api-compiled', 'dev up --ticket DEV-1234'],
+    features: [
+        'Registers a Caddy block and allocates opaque internal ports (4000+).',
+        'Spawns API + App detached; persists PIDs to <root>/.lt-dev/state.json.',
+        'Self-heals legacy hardcoded ports and restarts only the down component(s).',
+    ],
+    name: 'up',
+    options: [
+        {
+            description: 'Run the API compiled (node dist/src/main.js) instead of ts-node — trades hot reload for stability under browser load (DEV-2525). Builds + migrates first; falls back to the ts-node start if the build fails. Only applies when the API (re)starts.',
+            flag: '--api-compiled',
+            type: 'boolean',
+        },
+        {
+            description: 'Suffix the slug / URLs / DB for an isolated ticket stack (also auto-detected from a .lt-dev/ticket marker).',
+            flag: '--ticket',
+            type: 'string',
+        },
+    ],
+};
+module.exports = Object.assign(UpCommand, { help: exports.help });

package/build/lib/dev-api-launch.js

@@ -0,0 +1,89 @@
+"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.findCompiledEntry = findCompiledEntry;
+exports.isApiCompiledRequested = isApiCompiledRequested;
+exports.startCompiledApi = startCompiledApi;
+/**
+ * Launch strategy for the API process under `lt dev up`.
+ *
+ * By default `lt dev up` runs the API via ts-node (`<pm> run start` → nodemon →
+ * ts-node src/main.ts) for hot reload. Under a browser driving the app, that
+ * ts-node process intermittently dies WITHOUT a stacktrace (dev-SSR load plus
+ * ts-node's heavier footprint) — see DEV-2525. `lt dev test` already sidesteps
+ * this by running the API COMPILED (`node dist/src/main.js`); this module brings
+ * the same option to `lt dev up`, opt-in via `--api-compiled`. The trade-off is
+ * NO hot reload, so it stays opt-in — the caller decides stability vs. reload.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const dev_process_1 = require("./dev-process");
+/** Candidate compiled entry points, in preference order. Single-sourced so `lt dev test` agrees. */
+const COMPILED_ENTRIES = ['dist/src/main.js', 'dist/main.js'];
+/** Resolve the compiled API entry point in `apiDir`, or `undefined` if none was built. */
+function findCompiledEntry(apiDir) {
+    return COMPILED_ENTRIES.map((rel) => (0, node_path_1.join)(apiDir, rel)).find((candidate) => (0, node_fs_1.existsSync)(candidate));
+}
+/**
+ * True when the caller opted into the compiled API via `--api-compiled`.
+ *
+ * gluegun parses argv with yargs-parser and declares no booleans, so the flag
+ * arrives in several shapes: a value-less `--api-compiled` → boolean `true`, but
+ * `--api-compiled=true` → the STRING `'true'` and `--api-compiled=1` → the NUMBER
+ * `1`. A bare `=== true` check silently ignores the latter two and drops the very
+ * stability fix the user asked for. This is an ENABLE flag, so a mis-parse fails
+ * SAFE (default ts-node) — but the repo convention is to honour `true`/`'true'`
+ * too (see `dev-ticket.ts#keepDbFlag` for the destructive-flag counterpart).
+ */
+function isApiCompiledRequested(options = {}) {
+    const affirmative = (value) => value === true || ['1', 'true', 'yes'].includes(String(value).toLowerCase());
+    return affirmative(options.apiCompiled) || affirmative(options['api-compiled']);
+}
+/**
+ * Build the API and start it compiled (`node dist/src/main.js`). Applies pending
+ * migrations first for parity with the ts-node path it replaces (`<pm> run start`
+ * = `migrate:up && start:local`). Falls back to the ts-node start when the build
+ * fails or produces no dist entry, so this never leaves the developer with a dead
+ * API. Returns the detached spawn result (`undefined` when nothing was started).
+ */
+function startCompiledApi(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { apiDir, env, log, logFile, pm } = options;
+        log.info('Building API (compiled, for stability — no hot reload) …');
+        const build = yield (0, dev_process_1.runChildInherit)(pm.bin, pm.runScript('build'), { cwd: apiDir, env });
+        const entry = findCompiledEntry(apiDir);
+        if (build === 0 && entry) {
+            if (hasScript(apiDir, 'migrate:up')) {
+                const migrate = yield (0, dev_process_1.runChildInherit)(pm.bin, pm.runScript('migrate:up'), { cwd: apiDir, env });
+                if (migrate !== 0) {
+                    // Parity with `migrate:up && start:local`: a failed migration must PREVENT the server
+                    // from starting rather than boot it against a half-migrated DB behind a "Started" banner.
+                    log.warn(`migrate:up failed (exit ${String(migrate)}) — API NOT started (would run on an un-migrated DB).`);
+                    return undefined;
+                }
+            }
+            return (0, dev_process_1.spawnDetached)('node', [entry], { cwd: apiDir, env: Object.assign(Object.assign({}, env), { NODE_ENV: 'local' }), logFile });
+        }
+        log.warn(`compiled API unavailable (build exit ${String(build)}) — falling back to \`${pm.bin} start\` (ts-node).`);
+        return (0, dev_process_1.spawnDetached)(pm.bin, pm.runScript('start'), { cwd: apiDir, env, logFile });
+    });
+}
+/** True when `package.json` in `apiDir` defines a script named `name`. */
+function hasScript(apiDir, name) {
+    var _a;
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(apiDir, 'package.json'), 'utf8'));
+        return typeof ((_a = pkg.scripts) === null || _a === void 0 ? void 0 : _a[name]) === 'string';
+    }
+    catch (_b) {
+        return false;
+    }
+}

package/build/lib/dev-process.js

@@ -223,7 +223,27 @@ function spawnDetached(cmd, args, opts) {
     const out = (0, fs_1.openSync)(opts.logFile, 'a');
     let child;
     try {
-        child = (0, child_process_1.spawn)(cmd, args, {
+        // Raise the soft file-descriptor limit before exec-ing the real command.
+        // macOS's default soft RLIMIT_NOFILE is 256 (launchd/system default), inherited
+        // by the terminal that runs `lt dev up` and therefore by these detached children
+        // — it is NOT a consequence of the lt-dev LaunchAgent (which runs only Caddy).
+        // The dev file-watcher (nest/nuxt → chokidar) exhausts a soft-256 limit on a
+        // monorepo → intermittent "EMFILE: too many open files, watch" crashes on boot
+        // that force a manual `lt dev up`. We wrap the command in `sh -c "ulimit …; exec …"`:
+        //   - `exec` replaces the shell IN PLACE → the recorded PID and the detached
+        //     process group are still the real process (PID tracking + group-kill in
+        //     `terminateProcessGroup` keep working).
+        //   - `"$0" "$@"` pass cmd + args verbatim — no shell-quoting / injection.
+        //   - the cascade tries a high limit first, falling back on machines with a
+        //     lower `kern.maxfilesperproc`; `2>/dev/null` keeps it best-effort.
+        // Note: because the outer `spawn('/bin/sh', …)` almost always succeeds, a bogus
+        // `cmd` no longer surfaces as `pid === undefined` here — the inner `exec` fails
+        // (exit 127) a few ms later. Callers briefly record a live-then-dead PID, which
+        // `classifyComponentHealth` reaps as `dead`/`crashed` on the next status/up. We
+        // deliberately don't watch for that here: a detached, unref'd child's 127 exit is
+        // racy to observe, and callers must be self-correcting against real crashes anyway.
+        const raiseFdLimit = 'ulimit -n 65536 2>/dev/null || ulimit -n 10240 2>/dev/null || true';
+        child = (0, child_process_1.spawn)('/bin/sh', ['-c', `${raiseFdLimit}; exec "$0" "$@"`, cmd, ...args], {
             cwd: opts.cwd,
             detached: true,
             env: opts.env,

package/build/lib/dev-state.js

@@ -9,8 +9,10 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.paths = exports.TEST_SESSION_FILE = void 0;
+exports.paths = exports.TEST_SESSION_FILE = exports.STARTUP_GRACE_MS = void 0;
 exports.classifyComponentHealth = classifyComponentHealth;
+exports.partitionComponentStates = partitionComponentStates;
+exports.summarizeStackHealth = summarizeStackHealth;
 exports.allocateInternalPort = allocateInternalPort;
 exports.clearSession = clearSession;
 exports.detectSlugConflict = detectSlugConflict;
@@ -38,16 +40,66 @@ exports.withRegistryLock = withRegistryLock;
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
+/**
+ * How long after `lt dev up` a not-yet-bound-but-PID-alive component is treated
+ * as `starting` (booting) rather than `crashed`. Covers the slow API boot
+ * (compile + Mongo + Better Auth + AI tools + migrations) with headroom.
+ */
+exports.STARTUP_GRACE_MS = 60000;
 /**
  * Classify a component's true health from its recorded wrapper PID plus whether
  * its internal port is actually bound (caller provides the port probe result,
  * typically from a single {@link import('./dev-process').listenSnapshot} call).
+ *
+ * When `startedAt` is supplied, a PID-alive-but-port-unbound component is reported
+ * as `starting` (booting) rather than `crashed` for the first {@link STARTUP_GRACE_MS}
+ * after `lt dev up` — see the {@link ComponentHealth} doc block for the full state
+ * model and the false-positive it prevents.
  */
 function classifyComponentHealth(opts) {
+    var _a;
     const wrapperAlive = typeof opts.pid === 'number' && isPidAlive(opts.pid);
     if (!wrapperAlive)
         return 'dead';
-    return opts.portBound ? 'running' : 'crashed';
+    if (opts.portBound)
+        return 'running';
+    // Wrapper alive but the port is not bound. Within the startup grace window after
+    // `lt dev up` this is a still-BOOTING component, not a crash (avoids the
+    // false-positive that told users to restart a healthy, still-booting stack).
+    const graceMs = (_a = opts.startupGraceMs) !== null && _a !== void 0 ? _a : exports.STARTUP_GRACE_MS;
+    if (opts.startedAt) {
+        const ageMs = Date.now() - new Date(opts.startedAt).getTime();
+        if (Number.isFinite(ageMs) && ageMs >= 0 && ageMs < graceMs)
+            return 'starting';
+    }
+    return 'crashed';
+}
+/**
+ * Split present components into those still booting (`starting`) vs. genuinely
+ * down (present, not running, not starting). A `starting` component is booting,
+ * not down — it must NEVER appear in the "restart the down half" hint, otherwise
+ * the user is told to restart a healthy, still-booting stack.
+ */
+function partitionComponentStates(components) {
+    const starting = components.filter((c) => c.present && c.health === 'starting').map((c) => c.name);
+    const down = components
+        .filter((c) => c.present && c.health !== 'running' && c.health !== 'starting')
+        .map((c) => c.name);
+    return { down, starting };
+}
+/** See {@link StackHealth} for the precedence rules this implements. */
+function summarizeStackHealth(components) {
+    if (components.length === 0)
+        return 'stopped';
+    if (components.every((h) => h === 'running'))
+        return 'running';
+    if (components.some((h) => h === 'running'))
+        return 'degraded';
+    if (components.some((h) => h === 'starting'))
+        return 'starting';
+    if (components.some((h) => h === 'crashed'))
+        return 'crashed';
+    return 'stopped';
 }
 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';

package/build/lib/dev-test-session.js

@@ -47,6 +47,7 @@ const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
 const caddy_1 = require("./caddy");
+const dev_api_launch_1 = require("./dev-api-launch");
 const dev_env_1 = require("./dev-env");
 const dev_env_bridge_1 = require("./dev-env-bridge");
 const dev_identity_1 = require("./dev-identity");
@@ -245,9 +246,7 @@ function bringUpTestSession(layout_1, baseIdentity_1, log_1) {
                 log.info(log.dim('Building API (compiled, for stable long runs) …'));
                 build = yield (0, dev_process_1.runChildInherit)(apiPm.bin, apiPm.runScript('build'), { cwd: layout.apiDir, env: process.env });
             }
-            const entry = ['dist/src/main.js', 'dist/main.js']
-                .map((rel) => (0, path_1.join)(layout.apiDir, rel))
-                .find((p) => (0, fs_1.existsSync)(p));
+            const entry = (0, dev_api_launch_1.findCompiledEntry)(layout.apiDir);
             // Seed a throwaway initial admin into the fresh, isolated test DB so the
             // standard auth E2E specs run against a set-up system — locally exactly like
             // the lt-monorepo template CI. Defaults first so an explicitly inherited

package/docs/commands.md

@@ -433,6 +433,13 @@ lt dev up
 
 **Alias:** `lt d u`
 
+**Flags:**
+- `--api-compiled` — run the API **compiled** (`node dist/src/main.js`) instead of ts-node. Trades hot reload for stability: under sustained browser / dev-SSR load the ts-node API process intermittently dies without a stacktrace (DEV-2525); the compiled `node` process does not. Opt-in — omit it for the default ts-node hot-reload start. Details:
+  - Builds the API first, then applies pending migrations (`migrate:up`) for parity with the default `migrate:up && start:local`; a failed migration aborts the start rather than booting against a half-migrated DB.
+  - Auto-falls-back to the ts-node `start` if the build fails or produces no `dist` entry, so you never end up with a dead API.
+  - Only takes effect when the API actually (re)starts. A healthy running API is kept as-is — run `lt dev down` first to switch a live ts-node API to compiled.
+  - Accepted spellings: `--api-compiled` or `--api-compiled=true`.
+
 **Environment variables injected:**
 | Variable | Consumer | Example value |
 |----------|----------|---------------|
@@ -460,15 +467,20 @@ a still-serving component from a *crashed* one (the supervisor / nodemon survive
 ts-node crash and the recorded PID stays alive while nothing listens on the port).
 Behaviour:
 - **All present components truly serving** → no-op, exits 0 with "already running".
-- **Some serving, some down** → restarts ONLY the down component(s); a healthy one
-  keeps running untouched and its PID is preserved in the session.
+- **Still booting** (PID alive, port not bound yet, within the 60 s startup grace
+  window) → KEPT, not restarted. Re-running `lt dev up` while the API is still
+  booting must not kill and restart the still-booting component.
+- **Some serving, some down** → restarts ONLY the down (`crashed`/`dead`)
+  component(s); a running or still-booting one keeps its PID untouched.
 - Before respawning a crashed component it terminates that supervisor's whole
   process group (so its idle `nodemon` doesn't leak / stack a second one) and
   reclaims any orphaned listener still squatting the reused port.
 
 This is the fix for the "`status` says api running but no data loads" case: a
-crashed ts-node dev API is healed by simply re-running `lt dev up` (it does not
-fall back to compiled `node dist` — ts-node is kept so code edits hot-reload).
+crashed ts-node dev API is healed by simply re-running `lt dev up`. The **automatic**
+heal keeps ts-node (it does not silently switch to compiled `node dist`, so code
+edits still hot-reload); pass the explicit `--api-compiled` flag (see **Flags** above)
+when you deliberately want to trade hot reload for compiled stability.
 
 **Logs:** `<root>/.lt-dev/api.log`, `<root>/.lt-dev/app.log` (append-mode).
 
@@ -525,12 +537,17 @@ lt dev status --all   # every project in the registry
 The current-project view shows subdomains → upstream ports, db URI, per-component
 health, and live `lsof` state. **Health is honest:** a component is reported
 `running` only when its supervisor PID is alive AND its internal port is actually
-bound. A supervisor that survived a ts-node crash (PID alive, port free) is shown
-as `crashed (supervisor up, port not listening)` instead of the old misleading
-`running`, with a hint to run `lt dev up` to restart just that one.
+bound. A component that is PID-alive but not yet bound is `starting (booting — port
+not bound yet)` during the first 60 s after `lt dev up` (the slow API boot: swc
+compile + Mongo + Better Auth + migrations) — booting, not down, so no restart is
+suggested. Once that grace window elapses with the port still free, a supervisor
+that survived a ts-node crash (PID alive, port free) is shown as `crashed
+(supervisor up, port not listening)` instead of the old misleading `running`, with
+a hint to run `lt dev up` to restart just that one.
 
 The `--all` view lists every project with a single indicator:
 - `●` (green) — all present components serving
+- `◐` (cyan) — `starting` (booting within the startup grace window — give it a moment)
 - `◐` (yellow) — `degraded` (some up, some down) or `crashed` (supervisor up, port free)
 - `○` (dim) — stopped
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/cli",
-  "version": "1.39.0",
+  "version": "1.41.0",
   "description": "lenne.Tech CLI: lt",
   "keywords": [
     "lenne.Tech",