@lenne.tech/cli 1.29.0 → 1.31.0

package/build/commands/dev/status.js

@@ -39,13 +39,51 @@ const StatusCommand = {
                 warning('No projects registered. Run `lt dev init` in a project.');
             }
             else {
+                // One lsof over EVERY registered internal port, so liveness reflects
+                // what is actually bound — not just whether a supervisor PID survives a
+                // crashed ts-node. (See classifyComponentHealth.)
+                const allPorts = [];
+                for (const slug of slugs) {
+                    const e = reg.projects[slug];
+                    if (e.internalPorts.api)
+                        allPorts.push(e.internalPorts.api);
+                    if (e.internalPorts.app)
+                        allPorts.push(e.internalPorts.app);
+                }
+                const snap = yield (0, dev_process_1.listenSnapshot)(allPorts);
                 for (const slug of slugs) {
                     const e = reg.projects[slug];
                     const session = (0, dev_state_1.loadSession)(e.path);
-                    const apiAlive = (session === null || session === void 0 ? void 0 : session.pids.api) ? (0, dev_state_1.isPidAlive)(session.pids.api) : false;
-                    const appAlive = (session === null || session === void 0 ? void 0 : session.pids.app) ? (0, dev_state_1.isPidAlive)(session.pids.app) : false;
-                    const status = apiAlive || appAlive ? colors.green('●') : colors.dim('○');
-                    info(`  ${status} ${slug.padEnd(30)} ${colors.dim(e.path)}`);
+                    // Only components the project actually has (a registered internal
+                    // 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) }));
+                    }
+                    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) }));
+                    }
+                    const allRunning = comps.length > 0 && comps.every((h) => h === 'running');
+                    const anyRunning = comps.some((h) => h === 'running');
+                    const anyCrashed = comps.some((h) => h === 'crashed');
+                    let status;
+                    let note = '';
+                    if (allRunning) {
+                        status = colors.green('●');
+                    }
+                    else if (anyRunning) {
+                        // 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) {
+                        status = colors.yellow('◐');
+                        note = colors.yellow('  crashed — `lt dev up` to restart');
+                    }
+                    else {
+                        status = colors.dim('○');
+                    }
+                    info(`  ${status} ${slug.padEnd(30)} ${colors.dim(e.path)}${note}`);
                     for (const [sub, host] of Object.entries(e.subdomains))
                         info(`     ${sub.padEnd(6)} https://${host}`);
                 }
@@ -128,22 +166,56 @@ const StatusCommand = {
             info(colors.dim('  no `lt dev up` session active'));
         }
         else {
-            const apiAlive = session.pids.api ? (0, dev_state_1.isPidAlive)(session.pids.api) : false;
-            const appAlive = session.pids.app ? (0, dev_state_1.isPidAlive)(session.pids.app) : false;
-            info(`  api: ${apiAlive ? colors.green('running') : colors.red('dead')} (pid ${(_a = session.pids.api) !== null && _a !== void 0 ? _a : '-'})`);
-            info(`  app: ${appAlive ? colors.green('running') : colors.red('dead')} (pid ${(_b = session.pids.app) !== null && _b !== void 0 ? _b : '-'})`);
-            info(colors.dim(`  started: ${session.startedAt}`));
-            // Live port snapshot
+            // Probe the actual ports FIRST: a component is only truly "running" when
+            // its supervisor PID is alive AND its internal port is bound. A crashed
+            // ts-node leaves nodemon alive ("waiting for file changes"), so the
+            // wrapper PID alone reads as "running" while nothing serves the port.
             const ports = [entry.internalPorts.api, entry.internalPorts.app].filter((p) => typeof p === 'number');
+            const snap = yield (0, dev_process_1.listenSnapshot)(ports);
+            const apiHealth = (0, dev_state_1.classifyComponentHealth)({
+                pid: session.pids.api,
+                portBound: entry.internalPorts.api ? snap.has(entry.internalPorts.api) : false,
+            });
+            const appHealth = (0, dev_state_1.classifyComponentHealth)({
+                pid: session.pids.app,
+                portBound: entry.internalPorts.app ? snap.has(entry.internalPorts.app) : false,
+            });
+            const label = (health) => health === 'running'
+                ? colors.green('running')
+                : 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 : '-'})`);
+            }
+            if (session.pids.app !== undefined || entry.internalPorts.app) {
+                info(`  app: ${label(appHealth)} (pid ${(_b = session.pids.app) !== null && _b !== void 0 ? _b : '-'})`);
+            }
+            info(colors.dim(`  started: ${session.startedAt}`));
+            // Live port snapshot — the authoritative "what is actually bound" view.
             if (ports.length > 0) {
                 info('');
                 info(colors.bold('  Live upstream state'));
-                const snap = yield (0, dev_process_1.listenSnapshot)(ports);
                 for (const p of ports) {
                     const r = snap.get(p);
                     info(`    ${p}: ${r ? colors.green(`bound to ${r.command} (pid ${r.pid})`) : colors.dim('free')}`);
                 }
             }
+            // Surface any present-but-not-serving component (crashed OR dead) and
+            // point at the now-selective `lt dev up`, which restarts just the down
+            // 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);
+            if (down.length > 0) {
+                const crashed = (apiPresent && apiHealth === 'crashed') || (appPresent && appHealth === 'crashed');
+                info('');
+                warning(`  ${down.join(' + ')} not serving${crashed ? ' (supervisor still up — crashed)' : ''}. ` +
+                    `Run \`lt dev up\` to restart ${down.length === 1 ? 'it' : 'them'}.`);
+            }
         }
         // Isolated test stack (`lt dev test`), if one is up / left with --keep.
         const testSession = (0, dev_state_1.loadSession)(layout.root, dev_state_1.TEST_SESSION_FILE);

package/build/commands/dev/up.js

@@ -165,30 +165,11 @@ const UpCommand = {
                 info(colors.dim('  (Continuing — env-aware files will work; legacy files may bind on 3000/3001 and miss Caddy.)'));
             }
         }
-        // Already running?
+        // Load any existing session up-front. The "is it already running?" decision
+        // is deliberately deferred until AFTER port allocation: a recorded wrapper
+        // PID being alive is NOT proof a component serves (a crashed ts-node leaves
+        // nodemon alive), so we probe the actual internal ports once we know them.
         const existingSession = (0, dev_state_1.loadSession)(layout.root);
-        if (existingSession) {
-            const apiUp = existingSession.pids.api ? (0, dev_state_1.isPidAlive)(existingSession.pids.api) : false;
-            const appUp = existingSession.pids.app ? (0, dev_state_1.isPidAlive)(existingSession.pids.app) : false;
-            if (apiUp || appUp) {
-                warning(`Already running (api pid ${(_a = existingSession.pids.api) !== null && _a !== void 0 ? _a : '-'}, app pid ${(_b = existingSession.pids.app) !== null && _b !== void 0 ? _b : '-'}).`);
-                // Surface the bound URLs so the user can copy them out without having
-                // to look up `lt dev status` separately. Falls back to the in-process
-                // identity/registry data — both sources stay in sync via saveRegistry.
-                const existingEntry = (0, dev_state_1.loadRegistry)().projects[identity.slug];
-                printProjectUrls(info, {
-                    apiHostname: (_c = identity.subdomains.api) === null || _c === void 0 ? void 0 : _c.hostname,
-                    apiUpstreamPort: existingEntry === null || existingEntry === void 0 ? void 0 : existingEntry.internalPorts.api,
-                    appHostname: (_d = identity.subdomains.app) === null || _d === void 0 ? void 0 : _d.hostname,
-                    appUpstreamPort: existingEntry === null || existingEntry === void 0 ? void 0 : existingEntry.internalPorts.app,
-                    dbName: (_e = existingEntry === null || existingEntry === void 0 ? void 0 : existingEntry.dbName) !== null && _e !== void 0 ? _e : dbName,
-                });
-                info('Run `lt dev down` first.');
-                if (!parameters.options.fromGluegunMenu)
-                    process.exit(1);
-                return 'dev up: already running';
-            }
-        }
         // Allocate internal ports (reuse existing if registered), verify they are
         // free, AND reserve them in the registry — all ATOMICALLY under a cross-
         // process lock, so two simultaneous `lt ticket start` (each → `lt dev up`)
@@ -197,15 +178,34 @@ const UpCommand = {
         let appPort;
         try {
             yield (0, dev_state_1.withRegistryLock)(() => __awaiter(void 0, void 0, void 0, function* () {
-                var _a, _b;
                 const reg = (0, dev_state_1.loadRegistry)();
                 const entry = reg.projects[identity.slug];
                 const taken = (0, dev_state_1.takenInternalPorts)(reg, identity.slug);
-                apiPort = (_a = entry === null || entry === void 0 ? void 0 : entry.internalPorts.api) !== null && _a !== void 0 ? _a : (layout.apiDir ? (0, dev_state_1.allocateInternalPort)(4000, taken) : undefined);
+                let apiPortReused = false;
+                let appPortReused = false;
+                if (entry === null || entry === void 0 ? void 0 : entry.internalPorts.api) {
+                    apiPort = entry.internalPorts.api;
+                    apiPortReused = true;
+                }
+                else if (layout.apiDir) {
+                    apiPort = (0, dev_state_1.allocateInternalPort)(4000, taken);
+                }
                 if (apiPort)
                     taken.add(apiPort);
-                appPort = (_b = entry === null || entry === void 0 ? void 0 : entry.internalPorts.app) !== null && _b !== void 0 ? _b : (layout.appDir ? (0, dev_state_1.allocateInternalPort)(4000, taken) : undefined);
-                const portsToCheck = [apiPort, appPort].filter((p) => typeof p === 'number');
+                if (entry === null || entry === void 0 ? void 0 : entry.internalPorts.app) {
+                    appPort = entry.internalPorts.app;
+                    appPortReused = true;
+                }
+                else if (layout.appDir) {
+                    appPort = (0, dev_state_1.allocateInternalPort)(4000, taken);
+                }
+                // Only FRESHLY allocated ports must be verified free here. A reused
+                // (registered) port may legitimately be bound by our own still-healthy
+                // component; the spawn phase below decides per-component whether to keep
+                // or restart it (and reclaims a reused port held by a crashed/orphaned
+                // process). Free-checking a reused port would falsely abort a partial
+                // restart of just the crashed half.
+                const portsToCheck = [apiPortReused ? undefined : apiPort, appPortReused ? undefined : appPort].filter((p) => typeof p === 'number');
                 const snap = yield (0, dev_process_1.listenSnapshot)(portsToCheck);
                 for (const p of portsToCheck) {
                     const r = snap.get(p);
@@ -232,6 +232,49 @@ const UpCommand = {
                 process.exit(1);
             return 'dev up: port in use';
         }
+        // ── 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.
+        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) })
+            : 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) })
+            : undefined;
+        // 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')) {
+            warning(`Already running (api pid ${(_a = existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.api) !== null && _a !== void 0 ? _a : '-'}, app pid ${(_b = existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.app) !== null && _b !== void 0 ? _b : '-'}) — all components healthy.`);
+            const existingEntry = (0, dev_state_1.loadRegistry)().projects[identity.slug];
+            printProjectUrls(info, {
+                apiHostname: (_c = identity.subdomains.api) === null || _c === void 0 ? void 0 : _c.hostname,
+                apiUpstreamPort: existingEntry === null || existingEntry === void 0 ? void 0 : existingEntry.internalPorts.api,
+                appHostname: (_d = identity.subdomains.app) === null || _d === void 0 ? void 0 : _d.hostname,
+                appUpstreamPort: existingEntry === null || existingEntry === void 0 ? void 0 : existingEntry.internalPorts.app,
+                dbName: (_e = existingEntry === null || existingEntry === void 0 ? void 0 : existingEntry.dbName) !== null && _e !== void 0 ? _e : dbName,
+            });
+            info('Run `lt dev down` first to force a full restart.');
+            if (!parameters.options.fromGluegunMenu)
+                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');
+        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`);
+        }
         // Caddy block + reload.
         const routes = [];
         if (identity.subdomains.api && apiPort)
@@ -271,40 +314,77 @@ const UpCommand = {
         const pnpmBin = process.env.LT_PNPM_BIN || 'pnpm';
         const pids = {};
         const rotationNotes = [];
-        if (layout.apiDir && (0, fs_1.existsSync)((0, path_1.join)(layout.apiDir, 'package.json')) && apiPort) {
-            const apiResult = (0, dev_process_1.spawnDetached)(pnpmBin, ['start'], {
-                cwd: layout.apiDir,
-                env: devEnv.api.env,
-                logFile: (0, path_1.join)(layout.root, '.lt-dev', 'api.log'),
-            });
-            if (apiResult) {
-                pids.api = apiResult.pid;
-                if (apiResult.rotated.rotated && apiResult.rotated.archivePath !== undefined) {
-                    rotationNotes.push(formatRotationNote('api', apiResult.rotated.archivePath, (_f = apiResult.rotated.previousSize) !== null && _f !== void 0 ? _f : 0));
+        const started = [];
+        const kept = [];
+        // Free a reused internal port before respawning: stop a CRASHED component's
+        // still-alive supervisor group (otherwise its idle nodemon leaks and a
+        // second one stacks on top), and kill any orphaned listener squatting the
+        // port (e.g. a ts-node whose supervisor already died). No-op on a clean
+        // first start (no prev PID, port free).
+        const reclaimPort = (prevPid, port, health) => __awaiter(void 0, void 0, void 0, function* () {
+            if (health === 'crashed' && prevPid)
+                yield (0, dev_process_1.terminateProcessGroup)(prevPid);
+            const bound = port ? healthSnap.get(port) : undefined;
+            if (bound === null || bound === void 0 ? void 0 : bound.pid)
+                yield (0, dev_process_1.terminateProcessGroup)(bound.pid);
+        });
+        if (hasApi && layout.apiDir && apiPort) {
+            if (apiHealth === 'running') {
+                pids.api = existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.api;
+                kept.push('api');
+            }
+            else {
+                yield reclaimPort(existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.api, apiPort, apiHealth !== null && apiHealth !== void 0 ? apiHealth : 'dead');
+                const apiResult = (0, dev_process_1.spawnDetached)(pnpmBin, ['start'], {
+                    cwd: layout.apiDir,
+                    env: devEnv.api.env,
+                    logFile: (0, path_1.join)(layout.root, '.lt-dev', 'api.log'),
+                });
+                if (apiResult) {
+                    pids.api = apiResult.pid;
+                    started.push('api');
+                    if (apiResult.rotated.rotated && apiResult.rotated.archivePath !== undefined) {
+                        rotationNotes.push(formatRotationNote('api', apiResult.rotated.archivePath, (_f = apiResult.rotated.previousSize) !== null && _f !== void 0 ? _f : 0));
+                    }
                 }
             }
         }
-        if (layout.appDir && (0, fs_1.existsSync)((0, path_1.join)(layout.appDir, 'package.json')) && appPort) {
-            const appResult = (0, dev_process_1.spawnDetached)(pnpmBin, ['dev'], {
-                cwd: layout.appDir,
-                env: devEnv.app.env,
-                logFile: (0, path_1.join)(layout.root, '.lt-dev', 'app.log'),
-            });
-            if (appResult) {
-                pids.app = appResult.pid;
-                if (appResult.rotated.rotated && appResult.rotated.archivePath !== undefined) {
-                    rotationNotes.push(formatRotationNote('app', appResult.rotated.archivePath, (_g = appResult.rotated.previousSize) !== null && _g !== void 0 ? _g : 0));
+        if (hasApp && layout.appDir && appPort) {
+            if (appHealth === 'running') {
+                pids.app = existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.app;
+                kept.push('app');
+            }
+            else {
+                yield reclaimPort(existingSession === null || existingSession === void 0 ? void 0 : existingSession.pids.app, appPort, appHealth !== null && appHealth !== void 0 ? appHealth : 'dead');
+                const appResult = (0, dev_process_1.spawnDetached)(pnpmBin, ['dev'], {
+                    cwd: layout.appDir,
+                    env: devEnv.app.env,
+                    logFile: (0, path_1.join)(layout.root, '.lt-dev', 'app.log'),
+                });
+                if (appResult) {
+                    pids.app = appResult.pid;
+                    started.push('app');
+                    if (appResult.rotated.rotated && appResult.rotated.archivePath !== undefined) {
+                        rotationNotes.push(formatRotationNote('app', appResult.rotated.archivePath, (_g = appResult.rotated.previousSize) !== null && _g !== void 0 ? _g : 0));
+                    }
                 }
             }
         }
-        // Persist the session (PIDs). The registry entry (ports) was already reserved
-        // atomically before the spawn, above.
-        (0, dev_state_1.saveSession)(layout.root, { pids, startedAt: new Date().toISOString() });
+        // 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();
+        (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}`));
-        success(`Started: api pid=${(_h = pids.api) !== null && _h !== void 0 ? _h : '-'}, app pid=${(_j = pids.app) !== null && _j !== void 0 ? _j : '-'}`);
+        const summary = started.length === 0
+            ? '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 : '-'}`);
         // 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.

package/build/extensions/tools.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Tools = void 0;
 const fs_1 = require("fs");
+const command_help_1 = require("../lib/command-help");
 const singleComment = Symbol('singleComment');
 const multiComment = Symbol('multiComment');
 const stripWithoutWhitespace = () => '';
@@ -27,6 +28,14 @@ class Tools {
      * Check if --help-json flag is set; if so, print the command definition as JSON and return true.
      * Commands should call this early and return immediately when it returns true.
      *
+     * In normal CLI usage the global `installHelpInterceptor` (see
+     * `src/lib/command-help.ts`) handles `--help-json` for ALL commands before
+     * their `run()` ever fires — this method is therefore mostly a no-op in
+     * production. It is still kept as a public escape hatch for tests that
+     * invoke a command's `run()` directly without the interceptor, and for
+     * legacy callers — output goes through the same `buildHelpJson` /
+     * `emitHelpJson` pair as the global path, so the schema cannot drift.
+     *
      * @param definition - The command's help definition (name, description, options, etc.)
      * @returns true if --help-json was handled (caller should return), false otherwise
      */
@@ -35,7 +44,7 @@ class Tools {
         if (!parameters.options['help-json'] && !parameters.options.helpJson) {
             return false;
         }
-        console.debug(JSON.stringify(definition, null, 2));
+        (0, command_help_1.emitHelpJson)((0, command_help_1.buildHelpJson)({ description: definition.description, name: definition.name }, definition));
         return true;
     }
     /**

package/build/lib/command-help.js

@@ -18,12 +18,16 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.installHelpInterceptor = installHelpInterceptor;
+exports.isHelpJsonRequested = isHelpJsonRequested;
 exports.isHelpRequested = isHelpRequested;
 exports.loadCommandHelp = loadCommandHelp;
 exports.renderCommandHelp = renderCommandHelp;
+exports.buildHelpJson = buildHelpJson;
+exports.emitHelpJson = emitHelpJson;
 /**
- * Wrap every command's `run` so that `--help` / `-h` prints help and returns
- * without executing. Call once after `build().create()`, before `cli.run()`.
+ * Wrap every command's `run` so that `--help` / `-h` and `--help-json` print
+ * help and return without executing. Call once after `build().create()`,
+ * before `cli.run()`.
  *
  * Idempotent per command (guarded by `__helpWrapped`), so a command is never
  * double-wrapped if this runs more than once in the same process (e.g. tests).
@@ -43,6 +47,10 @@ function installHelpInterceptor(commands, defaultCommand) {
         }
         const originalRun = command.run;
         command.run = (toolbox) => {
+            if (isHelpJsonRequested(toolbox === null || toolbox === void 0 ? void 0 : toolbox.parameters)) {
+                emitHelpJson(buildHelpJson(command, loadCommandHelp(command.file)));
+                return undefined;
+            }
             if ((toolbox === null || toolbox === void 0 ? void 0 : toolbox.print) && isHelpRequested(toolbox.parameters)) {
                 renderCommandHelp(toolbox.print, command, loadCommandHelp(command.file));
                 return undefined;
@@ -52,10 +60,12 @@ function installHelpInterceptor(commands, defaultCommand) {
         command.__helpWrapped = true;
     }
 }
-/**
- * True when the invocation asks for help (`--help` or `-h`) — but NOT for
- * `--help-json` (handled separately by `tools.helpJson`).
- */
+/** True when the invocation asks for machine-readable help (`--help-json`). */
+function isHelpJsonRequested(parameters) {
+    const options = (parameters === null || parameters === void 0 ? void 0 : parameters.options) || {};
+    return options['help-json'] === true || options.helpJson === true;
+}
+/** True when the invocation asks for human-readable help (`--help` or `-h`). */
 function isHelpRequested(parameters) {
     const options = (parameters === null || parameters === void 0 ? void 0 : parameters.options) || {};
     if (options['help-json'] === true || options.helpJson === true) {
@@ -132,7 +142,7 @@ function renderCommandHelp(print, command, help) {
     }
     // Always-present global flags
     print.info(`  ${'--help, -h'.padEnd(28)} Show this help and exit (does not run the command)`);
-    print.info(`  ${'--help-json'.padEnd(28)} Machine-readable help as JSON (where provided)`);
+    print.info(`  ${'--help-json'.padEnd(28)} Machine-readable help as JSON (does not run the command)`);
     if (!options.some((o) => o.flag === '--noConfirm')) {
         print.info(`  ${'--noConfirm'.padEnd(28)} Skip confirmation prompts (where supported)`);
     }
@@ -159,3 +169,41 @@ function usagePath(command) {
     const path = command.commandPath && command.commandPath.length ? command.commandPath : [command.name || ''];
     return `lt ${path.filter(Boolean).join(' ')}`.trim();
 }
+const GLOBAL_HELP_FLAGS = [
+    { description: 'Show human-readable help; the command is NOT executed.', flag: '--help', type: 'boolean' },
+    { description: 'Alias for --help.', flag: '-h', type: 'boolean' },
+    {
+        description: 'Print this JSON description on stdout; the command is NOT executed.',
+        flag: '--help-json',
+        type: 'boolean',
+    },
+];
+/**
+ * Build the JSON shape returned by `--help-json` for a command, merging the
+ * gluegun-known metadata (name, commandPath, description, aliases) with the
+ * command's optional rich `CommandHelp` export.
+ */
+function buildHelpJson(command, help) {
+    const aliases = aliasList(command, help);
+    return {
+        aliases,
+        command: usagePath(command),
+        configuration: help === null || help === void 0 ? void 0 : help.configuration,
+        description: (help === null || help === void 0 ? void 0 : help.description) || command.description || '',
+        examples: help === null || help === void 0 ? void 0 : help.examples,
+        features: help === null || help === void 0 ? void 0 : help.features,
+        globalFlags: GLOBAL_HELP_FLAGS,
+        name: (help === null || help === void 0 ? void 0 : help.name) || command.name || '',
+        options: (help === null || help === void 0 ? void 0 : help.options) || [],
+        richHelp: Boolean(help),
+    };
+}
+/**
+ * Emit a help-json payload to stdout as a single pretty-printed JSON document.
+ * Kept tiny + side-effect-only so it can be stubbed in tests via a captured
+ * `console.log`.
+ */
+function emitHelpJson(payload) {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(payload, null, 2));
+}

package/build/lib/dev-state.js

@@ -10,6 +10,7 @@ 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.classifyComponentHealth = classifyComponentHealth;
 exports.allocateInternalPort = allocateInternalPort;
 exports.clearSession = clearSession;
 exports.detectSlugConflict = detectSlugConflict;
@@ -36,6 +37,17 @@ exports.withRegistryLock = withRegistryLock;
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
+/**
+ * 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).
+ */
+function classifyComponentHealth(opts) {
+    const wrapperAlive = typeof opts.pid === 'number' && isPidAlive(opts.pid);
+    if (!wrapperAlive)
+        return 'dead';
+    return opts.portBound ? 'running' : 'crashed';
+}
 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';

package/docs/commands.md

@@ -10,6 +10,7 @@ This document provides a comprehensive reference for all `lt` CLI commands. For
 
 ## Table of Contents
 
+- [Global Flags](#global-flags)
 - [CLI Commands](#cli-commands)
 - [Server Commands](#server-commands)
 - [Local Development Commands](#local-development-commands)
@@ -32,6 +33,44 @@ This document provides a comprehensive reference for all `lt` CLI commands. For
 
 ---
 
+## Global Flags
+
+These flags work on **every** `lt` subcommand. They are intercepted before the command's `run()` fires, so the command is never executed when one of them is set.
+
+| Flag | Description |
+|--------|-------------|
+| `--help`, `-h` | Print human-readable help (usage, aliases, options, examples). |
+| `--help-json` | Print the same help as a single JSON document on stdout. Stable contract — see shape below. Intended for AI agents and tooling that want to discover a command's surface programmatically. |
+| `--noConfirm` | Skip interactive confirmations (where supported by the command). |
+
+**`--help-json` payload shape** (`HelpJsonShape` in [src/lib/command-help.ts](../src/lib/command-help.ts)):
+
+```jsonc
+{
+  "aliases": ["c"],
+  "command": "lt server create",
+  "configuration": "commands.server.create.*",
+  "description": "Create new server",
+  "examples": ["server create --name Foo --noConfirm"],
+  "features": ["..."],
+  "globalFlags": [
+    { "flag": "--help",      "type": "boolean", "description": "..." },
+    { "flag": "-h",          "type": "boolean", "description": "..." },
+    { "flag": "--help-json", "type": "boolean", "description": "..." }
+  ],
+  "name": "create",
+  "options": [
+    { "flag": "--name", "type": "string", "required": true, "description": "Server name" }
+  ],
+  "richHelp": true
+}
+```
+
+- `richHelp: true` means the command exported a typed `CommandHelp` — `options`, `features`, `examples` and `configuration` are authoritative.
+- `richHelp: false` means only gluegun metadata was available — `options` is the empty array, but `globalFlags` is still guaranteed.
+
+---
+
 ## CLI Commands
 
 ### `lt cli create`
@@ -412,8 +451,23 @@ lt dev up
 **Pre-flight guards (exit code 1 each):**
 - Caddy not installed (`lt dev install` first)
 - Caddy daemon not running (run `lt dev install` — it bootstraps the lt-dev service)
-- Already running for this project (`lt dev down` first)
-- Internal port already in use
+- A FRESHLY allocated internal port is already in use by a foreign process
+
+**Health-aware (re)start (idempotent):** `lt dev up` is safe to re-run. It probes
+the actual internal ports — not just the recorded supervisor PID — so it can tell
+a still-serving component from a *crashed* one (the supervisor / nodemon survives a
+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.
+- 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).
 
 **Logs:** `<root>/.lt-dev/api.log`, `<root>/.lt-dev/app.log` (append-mode).
 
@@ -446,7 +500,19 @@ lt dev status --all   # every project in the registry
 
 **Alias:** `lt d s`
 
-The current-project view shows subdomains → upstream ports, db URI, session PIDs (alive/dead), and live `lsof` state. The `--all` view lists every project, with a `●`/`○` indicator for running state.
+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.
+
+The `--all` view lists every project with a single indicator:
+- `●` (green) — all present components serving
+- `◐` (yellow) — `degraded` (some up, some down) or `crashed` (supervisor up, port free)
+- `○` (dim) — stopped
+
+A single `lsof` snapshot covers every registered port, so `--all` stays fast.
 
 ---
 

package/package.json

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