@lenne.tech/cli 1.26.1 → 1.27.0

package/build/commands/dev/down.js

@@ -15,6 +15,7 @@ const dev_identity_1 = require("../../lib/dev-identity");
 const dev_process_1 = require("../../lib/dev-process");
 const dev_project_1 = require("../../lib/dev-project");
 const dev_state_1 = require("../../lib/dev-state");
+const dev_test_session_1 = require("../../lib/dev-test-session");
 /**
  * Stop the processes started by `lt dev up` and remove the project's
  * Caddy block.
@@ -66,6 +67,17 @@ const DownCommand = {
         // do not pick up stale URLs.
         if ((0, dev_env_bridge_1.clearEnvBridge)(layout.root))
             info(colors.dim('Removed .lt-dev/.env bridge.'));
+        // Also tear down any isolated test stack (`lt dev test`) for this project,
+        // so `lt dev down` always leaves a clean slate.
+        if ((0, dev_test_session_1.hasTestSession)(layout.root)) {
+            const { stopped: testStopped } = yield (0, dev_test_session_1.tearDownTestSession)(layout, identity, {
+                dim: colors.dim,
+                info,
+                warn: warning,
+            });
+            if (testStopped.length > 0)
+                success(`Stopped test stack: ${testStopped.join(', ')}`);
+        }
         if (stopped.length > 0)
             success(`Stopped: ${stopped.join(', ')}`);
         if (!parameters.options.fromGluegunMenu)

package/build/commands/dev/status.js

@@ -26,7 +26,7 @@ const StatusCommand = {
     hidden: false,
     name: 'status',
     run: (toolbox) => __awaiter(void 0, void 0, void 0, function* () {
-        var _a, _b;
+        var _a, _b, _c, _d;
         const { filesystem, parameters, print: { colors, info, warning }, } = toolbox;
         const all = Boolean(parameters.options.all);
         const reg = (0, dev_state_1.loadRegistry)();
@@ -144,6 +144,24 @@ const StatusCommand = {
                 }
             }
         }
+        // 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);
+        if (testSession) {
+            const testEntry = reg.projects[`${identity.slug}-test`];
+            info('');
+            info(colors.bold('  Isolated test stack (lt dev test)'));
+            if (testEntry) {
+                for (const [sub, host] of Object.entries(testEntry.subdomains))
+                    info(`    ${sub.padEnd(6)} https://${host}`);
+                if (testEntry.dbName)
+                    info(`    db     mongodb://127.0.0.1/${testEntry.dbName}`);
+            }
+            const apiAlive = testSession.pids.api ? (0, dev_state_1.isPidAlive)(testSession.pids.api) : false;
+            const appAlive = testSession.pids.app ? (0, dev_state_1.isPidAlive)(testSession.pids.app) : false;
+            info(`    api: ${apiAlive ? colors.green('running') : colors.red('dead')} (pid ${(_c = testSession.pids.api) !== null && _c !== void 0 ? _c : '-'})`);
+            info(`    app: ${appAlive ? colors.green('running') : colors.red('dead')} (pid ${(_d = testSession.pids.app) !== null && _d !== void 0 ? _d : '-'})`);
+            info(colors.dim('    stop: lt dev test down'));
+        }
         info('');
         if (!parameters.options.fromGluegunMenu)
             process.exit();

package/build/commands/dev/test.js

@@ -9,45 +9,44 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const caddy_1 = require("../../lib/caddy");
 const dev_env_bridge_1 = require("../../lib/dev-env-bridge");
 const dev_identity_1 = require("../../lib/dev-identity");
+const dev_process_1 = require("../../lib/dev-process");
 const dev_project_1 = require("../../lib/dev-project");
-const dev_state_1 = require("../../lib/dev-state");
+const dev_test_session_1 = require("../../lib/dev-test-session");
 /**
  * One-shot E2E convenience wrapper.
  *
- * Ensures the project is up under `lt dev`, then runs the test command
- * with the ENV bridge loaded, and optionally tears the session down at
- * the end. Useful for TDD loops, CI reproduction, and "just test it"
- * workflows where the developer doesn't want to remember three commands.
+ * App mode (default) runs the Playwright suite against a fully ISOLATED test
+ * stack (own URLs / ports / Caddy block / dedicated `<…>-test` database) that
+ * runs parallel to — and never touches — the developer's `lt dev up` session.
+ * Playwright's global-setup resets that dedicated DB once before the first test.
+ * The stack is torn down automatically when the run finishes (residue-free).
  *
- * Behaviour:
- *   1. If no `lt dev up` session is alive: run `lt dev up` first.
- *   2. Wait for the App URL to respond (best-effort, ~30s timeout).
- *   3. Inherit the env from `<root>/.lt-dev/.env` (so VS Code IDE-style
- *      runners get the same setup) and spawn the test command in the
- *      App project.
- *   4. With `--teardown` (default false): run `lt dev down` after.
+ * API mode (`--api`) runs the standalone API test suite (`pnpm test:e2e` in the
+ * API), which already isolates itself on its own DB — no stack is brought up.
  *
  * Usage:
- *   lt dev test                       # ensure up + run pnpm test:e2e in app
- *   lt dev test --api                 # run API tests instead (pnpm test in api)
- *   lt dev test --teardown            # plus stop session after
- *   lt dev test --debug               # PWDEBUG=1 + headed mode
- *   lt dev test -- <args>             # forward args to the test runner
- *   lt dev test -- --ui crm-login.spec.ts
+ *   lt dev test                  # isolated Playwright E2E (auto teardown)
+ *   lt dev test --keep           # leave the test stack up afterwards (debug)
+ *   lt dev test down             # tear the test stack down (residue-free)
+ *   lt dev test --api            # run API tests instead (already isolated)
+ *   lt dev test --debug          # PWDEBUG=1 + headed
+ *   lt dev test --shard          # shard across 2 isolated stacks (default — stable)
+ *   lt dev test --shard N        # shard across N isolated stacks (parallel)
+ *   lt dev test --shard auto     # size N from this machine's CPU + RAM
+ *   lt dev test -- <args>        # forward args to Playwright
  */
 const TestCommand = {
     alias: ['t'],
-    description: 'Ensure up + run E2E tests with lt dev env',
+    description: 'Run E2E tests in an isolated, parallel test stack (auto teardown)',
     hidden: false,
     name: 'test',
     run: (toolbox) => __awaiter(void 0, void 0, void 0, function* () {
         var _a;
-        const { filesystem, parameters, print: { colors, error, info, success }, } = toolbox;
+        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) {
             error('No API or App project detected at this path.');
@@ -55,74 +54,193 @@ const TestCommand = {
                 process.exit(1);
             return 'dev test: not a project';
         }
+        const identity = (0, dev_identity_1.buildIdentity)(layout.root);
+        const log = { dim: colors.dim, info, warn: warning };
+        // Sub-command: `lt dev test down` — tear the test stack(s) down + exit.
+        // Reclaims both the unsharded stack and any leftover sharded stacks.
+        if (parameters.first === 'down') {
+            const { stopped } = yield (0, dev_test_session_1.tearDownAllTestSessions)(layout, identity, log);
+            if (stopped.length > 0)
+                success(`Test stack down: ${stopped.join(', ')}`);
+            else
+                info(colors.dim('No test stack was running.'));
+            if (!parameters.options.fromGluegunMenu)
+                process.exit();
+            return 'dev test: down';
+        }
         const apiMode = Boolean(parameters.options.api);
-        const teardown = Boolean(parameters.options.teardown);
+        const keep = Boolean(parameters.options.keep) || parameters.options.teardown === false;
         const debug = Boolean(parameters.options.debug);
-        // Forwarded args after `--` (gluegun puts them in parameters.array).
         const forwarded = parameters.array || [];
-        const targetDir = apiMode ? layout.apiDir : layout.appDir;
-        if (!targetDir) {
-            error(`Cannot run ${apiMode ? 'API' : 'App'} tests — no ${apiMode ? 'apiDir' : 'appDir'} in layout.`);
-            if (!parameters.options.fromGluegunMenu)
-                process.exit(1);
-            return 'dev test: target missing';
+        const pnpmBin = process.env.LT_PNPM_BIN || 'pnpm';
+        // `--shard N` → run the suite split across N fully-isolated stacks in
+        // parallel. A bare `--shard` defaults to 2 — the stable sweet spot for a
+        // heavy built-SSR suite (N>=3 over-subscribes the perf cores → flaky; see
+        // autoShardCount). `--shard auto` instead sizes N from this machine's CPU+RAM.
+        const SHARD_DEFAULT = 2;
+        const shardRaw = (_a = parameters.options.shard) !== null && _a !== void 0 ? _a : parameters.options.shards;
+        let shardTotal;
+        if (shardRaw !== undefined) {
+            if (shardRaw === true)
+                shardTotal = SHARD_DEFAULT;
+            else if (String(shardRaw).toLowerCase() === 'auto')
+                shardTotal = (0, dev_test_session_1.autoShardCount)();
+            else
+                shardTotal = Math.floor(Number(shardRaw));
         }
-        const identity = (0, dev_identity_1.buildIdentity)(layout.root);
-        // Pre-flight: Caddy + ensure up.
-        if (!apiMode) {
-            if (!(yield (0, caddy_1.caddyAvailable)())) {
-                error('caddy is not installed. Run `lt dev install` first.');
+        // -------------------------------------------------------------------------
+        // API mode — standalone, already isolated on its own DB. No stack needed.
+        // -------------------------------------------------------------------------
+        if (apiMode) {
+            if (!layout.apiDir) {
+                error('No API project in this layout.');
                 if (!parameters.options.fromGluegunMenu)
                     process.exit(1);
-                return 'dev test: caddy missing';
+                return 'dev test: no api';
             }
-            if (!(yield (0, caddy_1.caddyDaemonRunning)())) {
-                error('caddy daemon not running. Run `lt dev install` first.');
-                if (!parameters.options.fromGluegunMenu)
-                    process.exit(1);
-                return 'dev test: caddy daemon down';
+            info(colors.bold(`Running API tests for "${identity.slug}" (isolated DB)`));
+            const code = yield (0, dev_process_1.runChildInherit)(pnpmBin, ['run', 'test:e2e', ...forwarded], {
+                cwd: layout.apiDir,
+                env: process.env,
+            });
+            if (code === 0)
+                success('API tests passed.');
+            else
+                error(`API tests failed (exit ${code}).`);
+            if (!parameters.options.fromGluegunMenu)
+                process.exit(code !== null && code !== void 0 ? code : 1);
+            return `dev test: api exit=${code}`;
+        }
+        // -------------------------------------------------------------------------
+        // App mode — isolated Playwright stack.
+        // -------------------------------------------------------------------------
+        if (!layout.appDir) {
+            error('No App project in this layout.');
+            if (!parameters.options.fromGluegunMenu)
+                process.exit(1);
+            return 'dev test: no app';
+        }
+        if (!(yield (0, caddy_1.caddyAvailable)())) {
+            error('caddy is not installed. Run `lt dev install` first.');
+            if (!parameters.options.fromGluegunMenu)
+                process.exit(1);
+            return 'dev test: caddy missing';
+        }
+        if (!(yield (0, caddy_1.caddyDaemonRunning)())) {
+            error('caddy daemon not running. Run `lt dev install` first.');
+            if (!parameters.options.fromGluegunMenu)
+                process.exit(1);
+            return 'dev test: caddy daemon down';
+        }
+        // Pre-flight (#3): if the project's playwright.config is not env-aware
+        // (hardcoded baseURL or an unguarded `webServer`), the suite would IGNORE
+        // the isolated stack we are about to build and hit localhost:3001 instead —
+        // wasting a full build on a stack nothing uses. Abort early with the fix,
+        // unless `--force`.
+        const unpatched = (0, dev_project_1.appNeedsPortPatch)(layout.appDir).some((f) => f.endsWith('playwright.config.ts'));
+        if (unpatched && !parameters.options.force) {
+            error("This project's playwright.config.ts is not env-aware (hardcoded baseURL or unguarded webServer).");
+            error('`lt dev test` would build an isolated stack the suite then IGNORES (tests would hit localhost:3001).');
+            info(colors.dim('Fix: run `lt dev init` to make baseURL env-aware + guard the webServer — or pass --force.'));
+            if (!parameters.options.fromGluegunMenu)
+                process.exit(1);
+            return 'dev test: playwright.config not env-aware (run lt dev init or --force)';
+        }
+        // -------------------------------------------------------------------------
+        // Sharded mode (`--shard N`) — N fully-isolated stacks + parallel
+        // `--shard=i/N`, the local CI-parity matrix. Each shard has its own DB so
+        // there is no cross-shard contention. Auto-teardown of ALL shards (or
+        // `--keep` them for `lt dev test down`).
+        // -------------------------------------------------------------------------
+        if (shardTotal !== undefined && shardTotal > 1) {
+            let allTornDown = false;
+            const teardownAll = () => __awaiter(void 0, void 0, void 0, function* () {
+                if (allTornDown || keep)
+                    return;
+                allTornDown = true;
+                yield (0, dev_test_session_1.tearDownAllTestSessions)(layout, identity, log, { silent: true });
+            });
+            const onShardSignal = () => {
+                teardownAll()
+                    .catch(() => undefined)
+                    .finally(() => process.exit(130));
+            };
+            process.on('SIGINT', onShardSignal);
+            process.on('SIGTERM', onShardSignal);
+            let shardExit = 1;
+            try {
+                info('');
+                info(colors.bold(`Running isolated Playwright E2E for "${identity.slug}" sharded across ${shardTotal} stacks`));
+                shardExit = yield (0, dev_test_session_1.runShardedTestSession)(layout, identity, log, { forwarded, pnpmBin, total: shardTotal });
+            }
+            catch (e) {
+                error(`Failed to run sharded E2E: ${e.message}`);
+                shardExit = 1;
             }
-            const reg = (0, dev_state_1.loadRegistry)();
-            const entry = reg.projects[identity.slug];
-            const session = (0, dev_state_1.loadSession)(layout.root);
-            const sessionAlive = session !== null &&
-                ((session.pids.api && (0, dev_state_1.isPidAlive)(session.pids.api)) || (session.pids.app && (0, dev_state_1.isPidAlive)(session.pids.app)));
-            if (!entry || !sessionAlive) {
-                info(colors.dim('Project not running — invoking `lt dev up` first ...'));
-                const upResult = yield runChild('lt', ['dev', 'up'], { cwd: layout.root, env: process.env, inherit: true });
-                if (upResult !== 0) {
-                    error(`lt dev up failed (exit ${upResult}).`);
-                    if (!parameters.options.fromGluegunMenu)
-                        process.exit(upResult !== null && upResult !== void 0 ? upResult : 1);
-                    return 'dev test: up failed';
+            finally {
+                process.off('SIGINT', onShardSignal);
+                process.off('SIGTERM', onShardSignal);
+                if (keep) {
+                    info('');
+                    info(colors.dim('Test stacks left running (--keep). Stop them with: `lt dev test down`.'));
                 }
-                // Wait for App URL to respond (best-effort).
-                const appHost = (_a = identity.subdomains.app) === null || _a === void 0 ? void 0 : _a.hostname;
-                if (appHost) {
-                    info(colors.dim(`Waiting for https://${appHost} to respond ...`));
-                    yield waitForUrl(`https://${appHost}`, 30000);
+                else {
+                    yield teardownAll();
                 }
             }
+            if (shardExit === 0)
+                success('Tests passed (all shards).');
+            else
+                error(`Tests failed (exit ${shardExit}).`);
+            if (!parameters.options.fromGluegunMenu)
+                process.exit(shardExit !== null && shardExit !== void 0 ? shardExit : 1);
+            return `dev test: sharded exit=${shardExit}`;
         }
-        // Build env: process.env + bridge file (bridge wins for keys it defines).
-        const env = Object.assign(Object.assign({}, process.env), readBridgeEnv(layout.root));
-        if (debug) {
-            env.PWDEBUG = '1';
-            env.HEADED = '1';
-        }
-        // Pick the runner.
-        const pnpmBin = process.env.LT_PNPM_BIN || 'pnpm';
-        const args = apiMode ? ['run', 'test:e2e', ...forwarded] : ['run', 'test:e2e', ...forwarded];
-        info('');
-        info(colors.bold(`Running ${apiMode ? 'API' : 'App'} E2E tests for "${identity.slug}"`));
-        info(colors.dim(`  ${pnpmBin} ${args.join(' ')}`));
-        info(colors.dim(`  cwd: ${targetDir}`));
-        info('');
-        const exitCode = yield runChild(pnpmBin, args, { cwd: targetDir, env, inherit: true });
-        if (teardown) {
+        let tornDown = false;
+        const teardown = () => __awaiter(void 0, void 0, void 0, function* () {
+            if (tornDown || keep)
+                return;
+            tornDown = true;
+            yield (0, dev_test_session_1.tearDownTestSession)(layout, identity, log);
+        });
+        // Residue-free teardown even on Ctrl-C / kill.
+        const onSignal = () => {
+            teardown()
+                .catch(() => undefined)
+                .finally(() => process.exit(130));
+        };
+        process.on('SIGINT', onSignal);
+        process.on('SIGTERM', onSignal);
+        let exitCode = 1;
+        try {
+            const ctx = yield (0, dev_test_session_1.bringUpTestSession)(layout, identity, log);
+            const env = Object.assign(Object.assign(Object.assign({}, process.env), readBridgeEnv(layout.root)), { 
+                // Playwright global-setup resets THIS db (allow-listed) before the suite.
+                MONGO_URI: `mongodb://127.0.0.1/${ctx.dbName}` });
+            if (debug) {
+                env.PWDEBUG = '1';
+                env.HEADED = '1';
+            }
             info('');
-            info(colors.dim('Tearing down lt dev session ...'));
-            yield runChild('lt', ['dev', 'down'], { cwd: layout.root, env: process.env, inherit: true });
+            info(colors.bold(`Running isolated Playwright E2E for "${identity.slug}"`));
+            info(colors.dim(`  app: ${ctx.appUrl}   db: ${ctx.dbName}`));
+            info('');
+            exitCode = yield (0, dev_process_1.runChildInherit)(pnpmBin, ['run', 'test:e2e', ...forwarded], { cwd: layout.appDir, env });
+        }
+        catch (e) {
+            error(`Failed to run isolated E2E: ${e.message}`);
+            exitCode = 1;
+        }
+        finally {
+            process.off('SIGINT', onSignal);
+            process.off('SIGTERM', onSignal);
+            if (keep) {
+                info('');
+                info(colors.dim('Test stack left running (--keep). Stop it with: `lt dev test down`.'));
+            }
+            else {
+                yield teardown();
+            }
         }
         if (exitCode === 0)
             success('Tests passed.');
@@ -134,11 +252,11 @@ const TestCommand = {
     }),
 };
 /**
- * Read the .lt-dev/.env bridge file as a key/value map.
- * Returns an empty object if the file is missing.
+ * Read the test ENV bridge (`.lt-dev/.env.test`) as a key/value map.
+ * Returns an empty object if missing.
  */
 function readBridgeEnv(root) {
-    const file = (0, dev_env_bridge_1.envBridgePath)(root);
+    const file = (0, dev_env_bridge_1.envBridgePath)(root, '.env.test');
     if (!(0, fs_1.existsSync)(file))
         return {};
     const out = {};
@@ -149,43 +267,4 @@ function readBridgeEnv(root) {
     }
     return out;
 }
-/** Spawn a child synchronously (waits for exit), inheriting stdio when requested. */
-function runChild(cmd, args, opts) {
-    return new Promise((resolve) => {
-        const child = (0, child_process_1.spawn)(cmd, args, {
-            cwd: opts.cwd,
-            env: opts.env,
-            stdio: opts.inherit ? 'inherit' : 'pipe',
-        });
-        child.on('error', () => resolve(1));
-        child.on('close', (code) => resolve(code));
-    });
-}
-/** Poll a URL until it responds or timeout elapses. */
-function waitForUrl(url, timeoutMs) {
-    const start = Date.now();
-    return new Promise((resolve) => {
-        const tick = () => {
-            var _a;
-            const child = (0, child_process_1.spawn)('curl', ['-sk', '-o', '/dev/null', '-w', '%{http_code}', '--max-time', '2', url], {
-                stdio: ['ignore', 'pipe', 'ignore'],
-            });
-            let status = '';
-            (_a = child.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (b) => (status += String(b)));
-            child.on('close', () => {
-                if (/^[1-5]\d\d$/.test(status.trim()))
-                    return resolve(true);
-                if (Date.now() - start > timeoutMs)
-                    return resolve(false);
-                setTimeout(tick, 500);
-            });
-            child.on('error', () => {
-                if (Date.now() - start > timeoutMs)
-                    return resolve(false);
-                setTimeout(tick, 500);
-            });
-        };
-        tick();
-    });
-}
 module.exports = TestCommand;

package/build/lib/dev-env-bridge.js

@@ -24,8 +24,8 @@ const os_1 = require("os");
 const path_1 = require("path");
 const HEADER = `# Managed by \`lt dev up\` — do NOT edit, will be overwritten.\n# Removed by \`lt dev down\`. Loaded by Playwright + other tools.\n`;
 /** Remove the ENV bridge file. No-op if missing. */
-function clearEnvBridge(projectRoot) {
-    const file = envBridgePath(projectRoot);
+function clearEnvBridge(projectRoot, fileName = '.env') {
+    const file = envBridgePath(projectRoot, fileName);
     if (!(0, fs_1.existsSync)(file))
         return false;
     try {
@@ -61,16 +61,16 @@ function detectCaddyRootCa() {
     return null;
 }
 /** Resolve the path to the ENV bridge file for a project. */
-function envBridgePath(projectRoot) {
-    return (0, path_1.join)(projectRoot, '.lt-dev', '.env');
+function envBridgePath(projectRoot, fileName = '.env') {
+    return (0, path_1.join)(projectRoot, '.lt-dev', fileName);
 }
 /**
  * Write the ENV bridge file. Idempotent — same content = no rewrite.
  *
  * Returns the absolute path that was written.
  */
-function writeEnvBridge(projectRoot, devEnv, dbName) {
-    const file = envBridgePath(projectRoot);
+function writeEnvBridge(projectRoot, devEnv, dbName, fileName = '.env') {
+    const file = envBridgePath(projectRoot, fileName);
     const lines = [];
     // The App-side env is the more "external" one (Playwright, browser tools).
     // We expose every URL/storage/api key the App env carries.

package/build/lib/dev-identity.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildIdentity = buildIdentity;
+exports.buildTestIdentity = buildTestIdentity;
 exports.projectSlug = projectSlug;
 exports.slugify = slugify;
 /**
@@ -67,6 +68,23 @@ function buildIdentity(root) {
     }
     return { root, slug, subdomains };
 }
+/**
+ * Derive an ephemeral "test" identity from a base identity (used by
+ * `lt dev test`). Suffixes the slug and every subdomain hostname with
+ * `-test`, so the test stack runs on its own URLs / ports / Caddy block,
+ * fully parallel to (and isolated from) the dev session.
+ *
+ *   svl.localhost      → svl-test.localhost
+ *   api.svl.localhost  → api.svl-test.localhost
+ */
+function buildTestIdentity(base, suffix = '-test') {
+    const slug = `${base.slug}${suffix}`;
+    const subdomains = {};
+    for (const [sub, value] of Object.entries(base.subdomains)) {
+        subdomains[sub] = Object.assign(Object.assign({}, value), { hostname: value.isPrimaryApp ? `${slug}.localhost` : `${sub}.${slug}.localhost` });
+    }
+    return { root: base.root, slug, subdomains };
+}
 /**
  * Read the bare project name from package.json (scope stripped).
  * Falls back to directory basename if no package.json or no `name`.

package/build/lib/dev-migrate-helper.js

@@ -78,15 +78,25 @@ function runMigrate(input) {
     });
     const identity = (0, dev_identity_1.buildIdentity)(layout.root);
     const dbName = (0, dev_project_1.deriveDbName)(layout.apiDir, identity.slug);
-    // 1. Code patches (config.env.ts, nuxt.config.ts, playwright.config.ts).
+    // 1. Code patches. Run `autoPatch` over EVERY existing config file (not just
+    //    the ones a port-detector flags): the patches are idempotent, and some —
+    //    e.g. the playwright.config `ignoreHTTPSErrors` + shard-aware
+    //    `LT_DEV_TEST_SHARDS` timeout block — apply to configs that are already
+    //    env-aware. So `lt dev init` makes any project fully `lt dev test --shard`
+    //    ready in one command; an up-to-date config is a no-op (`patched: false`).
     const filesToPatch = [];
     if (layout.apiDir) {
-        const f = (0, dev_project_1.apiNeedsPortPatch)(layout.apiDir);
-        if (f)
-            filesToPatch.push(f);
+        const apiCfg = (0, path_1.join)(layout.apiDir, 'src', 'config.env.ts');
+        if ((0, fs_1.existsSync)(apiCfg))
+            filesToPatch.push(apiCfg);
+    }
+    if (layout.appDir) {
+        for (const rel of ['nuxt.config.ts', 'playwright.config.ts']) {
+            const f = (0, path_1.join)(layout.appDir, rel);
+            if ((0, fs_1.existsSync)(f))
+                filesToPatch.push(f);
+        }
     }
-    if (layout.appDir)
-        filesToPatch.push(...(0, dev_project_1.appNeedsPortPatch)(layout.appDir));
     const codePatches = filesToPatch.map((f) => (0, dev_patches_1.autoPatch)(f));
     // 2. CLAUDE.md URL block (root + each subproject — only patches existing files).
     const claudeCandidates = [

package/build/lib/dev-patches.js

@@ -165,6 +165,16 @@ function patchNuxtConfig(file) {
  *      bracketed by `// >>> lt-dev:bridge >>>` markers.
  *   2. Hardcoded baseURL/host/url for `http://localhost:3001` →
  *      `process.env.NUXT_PUBLIC_SITE_URL || 'http://localhost:3001'`.
+ *   3. `webServer` wrapped in an `LT_DEV_ACTIVE` guard so Playwright reuses
+ *      the App already served by `lt dev` / `lt dev test` instead of spawning
+ *      its own (which would bind the wrong port and miss the isolated stack).
+ *   4. `ignoreHTTPSErrors: true` so Playwright's Chromium accepts the lt dev
+ *      Caddy self-signed cert (required for `lt dev test` over HTTPS).
+ *   5. Shard-aware timeouts gated on `LT_DEV_TEST_SHARDS` — a `SHARDED` const
+ *      plus relaxed `timeout` / `expect` / `navigationTimeout` / `actionTimeout`
+ *      under sharded load only, so serial + CI keep their tight, fast-failing
+ *      defaults. Each sub-patch is a graceful no-op on a non-standard config.
+ *   6. `slowMo: 10` → `0` (pointless per-action delay, multiplied across shards).
  */
 function patchPlaywrightConfig(file) {
     if (!(0, fs_1.existsSync)(file))
@@ -225,6 +235,67 @@ function patchPlaywrightConfig(file) {
             count++;
         }
     }
+    // 3. Wrap `webServer` in an `LT_DEV_ACTIVE` guard so Playwright does NOT
+    //    start/manage its own server when the App is already served by
+    //    `lt dev` / `lt dev test` (both export LT_DEV_ACTIVE + the App URL).
+    //    The original array/object's closing `]`/`}` becomes the ternary's
+    //    false branch, so no bracket-matching is needed. Idempotent.
+    if (!/webServer:\s*process\.env\.LT_DEV_ACTIVE/.test(after)) {
+        after = after.replace(/webServer:\s*([[{])/, (_match, open) => {
+            count++;
+            return `webServer: process.env.LT_DEV_ACTIVE ? undefined : ${open}`;
+        });
+    }
+    // 4. ignoreHTTPSErrors — accept the `lt dev` Caddy self-signed cert on
+    //    `https://*.localhost` (Playwright's bundled Chromium uses its own trust
+    //    store, so NODE_EXTRA_CA_CERTS alone is not enough). No-op in CI (http).
+    //    Without this, `lt dev test` fails with ERR_CERT_AUTHORITY_INVALID.
+    if (!/ignoreHTTPSErrors/.test(after)) {
+        after = after.replace(/(\n(\s*)use:\s*\{)/, (_m, whole, indent) => {
+            count++;
+            return `${whole}\n${indent}  ignoreHTTPSErrors: true,`;
+        });
+    }
+    // 5. Shard-aware timeouts — `lt dev test --shard N` runs N built stacks +
+    //    N Chromium concurrently; the CPU saturates and SSR slows 2-3x. Relax
+    //    timeouts ONLY under that load (the CLI exports LT_DEV_TEST_SHARDS), so
+    //    serial + CI keep their tight values and fast-failure feedback. Each
+    //    sub-patch is idempotent + a graceful no-op on non-standard configs.
+    if (!/const SHARDED\b/.test(after) && /export default defineConfig/.test(after)) {
+        const shardConst = '// `lt dev test --shard N` saturates the CPU (N built SSR servers + N Chromium),\n' +
+            '// slowing every navigation. Relax timeouts ONLY under that load — the CLI sets\n' +
+            "// LT_DEV_TEST_SHARDS — so serial + CI keep their tight, fast-failing defaults.\n" +
+            "const SHARDED = Number(process.env.LT_DEV_TEST_SHARDS || '0') > 1;\n\n";
+        after = after.replace(/(export default defineConfig)/, `${shardConst}$1`);
+        count++;
+    }
+    // 5a. per-test timeout (`isWindows ? A : B` form) → add the sharded branch.
+    if (/timeout:\s*isWindows\s*\?/.test(after) && !/timeout:\s*isWindows\s*\?[^,\n]*SHARDED/.test(after)) {
+        after = after.replace(/timeout:\s*isWindows\s*\?\s*([0-9_]+)\s*:\s*([0-9_]+|undefined)/, (_m, a, b) => {
+            count++;
+            return `timeout: isWindows ? ${a} : SHARDED ? 180_000 : ${b}`;
+        });
+    }
+    // 5b. expect.timeout (only when an `expect: { timeout: N }` already exists).
+    if (/expect:\s*\{\s*timeout:\s*[0-9_]+\s*\}/.test(after) && !/expect:\s*\{\s*timeout:\s*SHARDED/.test(after)) {
+        after = after.replace(/expect:\s*\{\s*timeout:\s*([0-9_]+)\s*\}/, (_m, t) => {
+            count++;
+            return `expect: { timeout: SHARDED ? 30_000 : ${t} }`;
+        });
+    }
+    // 5c. navigation/action ceilings under shard (inject into `use` if absent).
+    if (!/navigationTimeout/.test(after)) {
+        after = after.replace(/(\n(\s*)use:\s*\{)/, (_m, whole, indent) => {
+            count++;
+            return `${whole}\n${indent}  actionTimeout: SHARDED ? 30_000 : undefined,\n${indent}  navigationTimeout: SHARDED ? 60_000 : undefined,`;
+        });
+    }
+    // 6. slowMo: 10 → 0 — an artificial per-action delay, pointless and multiplied
+    //    across N concurrent sharded browsers.
+    after = after.replace(/slowMo:\s*10\b/, () => {
+        count++;
+        return 'slowMo: 0';
+    });
     if (count === 0)
         return { file, patched: false, replacements: 0 };
     (0, fs_1.writeFileSync)(file, after, 'utf8');

package/build/lib/dev-process.js

@@ -13,7 +13,11 @@ exports.checkPortInUse = checkPortInUse;
 exports.killProcessGroup = killProcessGroup;
 exports.listenSnapshot = listenSnapshot;
 exports.rotateLogFile = rotateLogFile;
+exports.runChildInherit = runChildInherit;
+exports.runChildToFile = runChildToFile;
 exports.spawnDetached = spawnDetached;
+exports.terminateProcessGroup = terminateProcessGroup;
+exports.waitForHttp = waitForHttp;
 /**
  * Process + port helpers for `lt dev`.
  *
@@ -145,6 +149,60 @@ function rotateLogFile(logFile) {
     }
     return { archivePath, previousSize, rotated: true };
 }
+/**
+ * Run a child to completion with inherited stdio. Resolves with the exit code.
+ *
+ * Counterpart of `spawnDetached`: foreground, synchronous-feeling, used for
+ * commands the user must see live output from (build, test runners).
+ * Errors during spawn resolve as exit code `1` so callers can branch on a
+ * single integer instead of try/catch.
+ */
+function runChildInherit(cmd, args, opts) {
+    return new Promise((resolve) => {
+        const child = (0, child_process_1.spawn)(cmd, args, { cwd: opts.cwd, env: opts.env, stdio: 'inherit' });
+        child.on('error', () => resolve(1));
+        child.on('close', (code) => resolve(code));
+    });
+}
+/**
+ * Run a child to completion with stdout+stderr redirected to a log file.
+ * Resolves with the exit code (`1` on spawn error). Like `runChildInherit` but
+ * non-interleaving — used to run several children CONCURRENTLY (e.g. parallel
+ * Playwright shards) without their console output clobbering each other.
+ */
+function runChildToFile(cmd, args, opts) {
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(opts.logFile), { recursive: true });
+    // Rotate so each run starts with a fresh log (one prior generation kept as
+    // `<logFile>.1`) instead of appending run-on-run.
+    rotateLogFile(opts.logFile);
+    const out = (0, fs_1.openSync)(opts.logFile, 'a');
+    const close = () => {
+        try {
+            (0, fs_1.closeSync)(out);
+        }
+        catch (_a) {
+            /* already closed */
+        }
+    };
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = (0, child_process_1.spawn)(cmd, args, { cwd: opts.cwd, env: opts.env, stdio: ['ignore', out, out] });
+        }
+        catch (_a) {
+            close();
+            return resolve(1);
+        }
+        child.on('error', () => {
+            close();
+            resolve(1);
+        });
+        child.on('close', (code) => {
+            close();
+            resolve(code);
+        });
+    });
+}
 /**
  * Spawn a detached child whose stdio is redirected to a log file.
  *
@@ -188,3 +246,99 @@ function spawnDetached(cmd, args, opts) {
         }
     }
 }
+/**
+ * Terminate a detached process group RELIABLY: SIGTERM the group, wait up to
+ * `graceMs` for it to exit, then SIGKILL anything still alive.
+ *
+ * Needed because a compiled NestJS API (`node dist`) installs shutdown hooks
+ * that catch SIGTERM and can hang on open Mongo connections — a single
+ * SIGTERM then "succeeds" (the call returns) while the process keeps
+ * listening on its port and holding DB connections. `lt dev test`'s
+ * residue-free teardown promise depends on the process actually being gone,
+ * so we escalate to SIGKILL after a grace period.
+ *
+ * Polls every 150ms so a process that exits cleanly returns near-instantly
+ * (only a hung process waits the full `graceMs`). Returns true if the process
+ * is gone by the end, false if it somehow survived even SIGKILL.
+ */
+function terminateProcessGroup(pid_1) {
+    return __awaiter(this, arguments, void 0, function* (pid, graceMs = 4000) {
+        if (!(0, dev_state_1.isValidPid)(pid))
+            return false;
+        if (!(0, dev_state_1.isPidAlive)(pid))
+            return true;
+        // Phase 1 — graceful: SIGTERM the group (single-PID fallback inside).
+        killProcessGroup(pid);
+        const deadline = Date.now() + Math.max(0, graceMs);
+        while (Date.now() < deadline) {
+            if (!(0, dev_state_1.isPidAlive)(pid))
+                return true;
+            yield delay(150);
+        }
+        // Phase 2 — forced: SIGKILL the group, then the single PID.
+        if (!(0, dev_state_1.isPidAlive)(pid))
+            return true;
+        try {
+            process.kill(-pid, 'SIGKILL');
+        }
+        catch (_a) {
+            /* group already gone or pid is not a group leader */
+        }
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch (_b) {
+            /* already dead */
+        }
+        yield delay(150);
+        return !(0, dev_state_1.isPidAlive)(pid);
+    });
+}
+/**
+ * Poll an HTTPS/HTTP URL until a matching response is observed or `timeoutMs`
+ * elapses.
+ *
+ * Used to wait for dev servers to become reachable before the next step
+ * (typically running a test suite). By default treats ANY HTTP status (1xx-5xx)
+ * as "up" — a 404 means the server is bound and answering, which is usually
+ * what we want to know. Pass `ready` to require a stricter status: an API
+ * readiness probe wants a real 2xx on `/meta`, because Caddy answers 502 while
+ * its upstream is still booting and the default predicate would accept that
+ * prematurely (the cause of the test-suite API-readiness race). Uses `curl`
+ * because it is universally available and handles HTTPS-with-self-signed-cert
+ * (Caddy) via `-k` for free.
+ *
+ * Resolves `true` on the first matching response, `false` on timeout. Never rejects.
+ */
+function waitForHttp(url, timeoutMs, ready = (status) => status >= 100 && status < 600) {
+    const start = Date.now();
+    return new Promise((resolve) => {
+        const tick = () => {
+            var _a;
+            const child = (0, child_process_1.spawn)('curl', ['-sk', '-o', '/dev/null', '-w', '%{http_code}', '--max-time', '2', url], {
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+            let status = '';
+            (_a = child.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (b) => (status += String(b)));
+            child.on('close', () => {
+                const code = Number(status.trim());
+                // `000` (curl could not connect) parses to 0 → never "ready".
+                if (Number.isFinite(code) && code > 0 && ready(code))
+                    return resolve(true);
+                if (Date.now() - start > timeoutMs)
+                    return resolve(false);
+                setTimeout(tick, 500);
+            });
+            child.on('error', () => {
+                if (Date.now() - start > timeoutMs)
+                    return resolve(false);
+                setTimeout(tick, 500);
+            });
+        };
+        tick();
+    });
+}
+/** Promise-based delay used by the graceful→forced termination escalation. */
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/build/lib/dev-project.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.apiNeedsPortPatch = apiNeedsPortPatch;
 exports.appNeedsPortPatch = appNeedsPortPatch;
 exports.deriveDbName = deriveDbName;
+exports.deriveTestDbName = deriveTestDbName;
 exports.resolveLayout = resolveLayout;
 const fs_1 = require("fs");
 const path_1 = require("path");
@@ -33,7 +34,10 @@ function appNeedsPortPatch(appDir) {
             /target:\s*'http:\/\/localhost:3000'/.test(c) ||
             /baseURL:\s*'http:\/\/localhost:3001'/.test(c) ||
             /url:\s*'http:\/\/localhost:3001'/.test(c) ||
-            /host:\s*'http:\/\/localhost:3001'/.test(c));
+            /host:\s*'http:\/\/localhost:3001'/.test(c) ||
+            // Unguarded Playwright `webServer` (no LT_DEV_ACTIVE guard) — patch it so
+            // `lt dev test`'s isolated stack is reused instead of a stray server.
+            (/webServer:\s*[[{]/.test(c) && !/webServer:\s*process\.env\.LT_DEV_ACTIVE/.test(c)));
     });
 }
 /** Read `dbName` from the API config (defaults to `<slug>-local`). */
@@ -49,6 +53,21 @@ function deriveDbName(apiDir, slug) {
     }
     return `${slug}-local`;
 }
+/**
+ * Derive the dedicated database name for the `lt dev test` stack from the
+ * project's dev DB name. Distinct from both `<…>-local` (developer DB) and
+ * the API unit-test DB (`<…>-e2e`), so Playwright E2E never touches developer
+ * or API-test data.
+ *
+ *   svl-sports-system-local → svl-sports-system-test
+ *
+ * Uses the `-test` suffix so it passes test-helper guards that only permit
+ * local/test databases (name ending in `-local` | `-ci` | `-e2e` | `-test`).
+ */
+function deriveTestDbName(devDbName) {
+    const base = devDbName.replace(/-(local|dev)$/i, '');
+    return `${base}-test`;
+}
 /**
  * Resolve layout starting from `cwd`. Walks up to find a workspace if
  * cwd is inside `projects/api/` or `projects/app/`.

package/build/lib/dev-state.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.paths = void 0;
+exports.paths = exports.TEST_SESSION_FILE = void 0;
 exports.allocateInternalPort = allocateInternalPort;
 exports.clearSession = clearSession;
 exports.isPidAlive = isPidAlive;
@@ -28,6 +28,8 @@ 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';
+/** Session file for the ephemeral `lt dev test` stack (runs parallel to the dev session). */
+exports.TEST_SESSION_FILE = 'state.test.json';
 /**
  * Allocate a free internal port for a Caddy upstream.
  *
@@ -44,8 +46,8 @@ function allocateInternalPort(start, taken) {
     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);
+function clearSession(root, sessionFile = SESSION_FILE) {
+    const file = (0, path_1.join)(root, SESSION_DIR, sessionFile);
     if ((0, fs_1.existsSync)(file)) {
         try {
             (0, fs_1.rmSync)(file);
@@ -87,8 +89,8 @@ function loadRegistry() {
     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);
+function loadSession(root, sessionFile = SESSION_FILE) {
+    const file = (0, path_1.join)(root, SESSION_DIR, sessionFile);
     if (!(0, fs_1.existsSync)(file))
         return null;
     try {
@@ -126,10 +128,10 @@ function saveRegistry(reg) {
     }
 }
 /** Persist session state for a project root. */
-function saveSession(root, state) {
+function saveSession(root, state, sessionFile = SESSION_FILE) {
     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');
+    (0, fs_1.writeFileSync)((0, path_1.join)(dir, sessionFile), JSON.stringify(state, null, 2), 'utf8');
 }
 /** Collect all internal ports already claimed across the registry. */
 function takenInternalPorts(reg, excludeSlug) {

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

@@ -0,0 +1,410 @@
+"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.autoShardCount = autoShardCount;
+exports.bringUpTestSession = bringUpTestSession;
+exports.hasTestSession = hasTestSession;
+exports.resolveTestSession = resolveTestSession;
+exports.runShardedTestSession = runShardedTestSession;
+exports.tearDownAllTestSessions = tearDownAllTestSessions;
+exports.tearDownTestSession = tearDownTestSession;
+/**
+ * Ephemeral, isolated test session for `lt dev test`.
+ *
+ * Brings up a SECOND, fully separate stack (own URLs, own internal ports,
+ * own Caddy block, own database) that runs PARALLEL to — and never touches —
+ * the developer's `lt dev up` session. Used to run the Playwright E2E suite
+ * against a clean, dedicated database so a developer can keep working in their
+ * own environment while tests run, and so a test run never pollutes dev data.
+ *
+ * Topology (for slug `svl`):
+ *   - dev session  : svl.localhost / api.svl.localhost   → db `<…>-local`
+ *   - test session : svl-test.localhost / api.svl-test.… → db `<…>-test`
+ *
+ * Both halves run BUILT for speed + prod-fidelity: the API COMPILED (`node dist`,
+ * ts-node intermittently dies mid-run) and the App as the production Nitro output
+ * (`nuxt build` → `node .output/server/index.mjs`, no Vite cold-compile). Each
+ * falls back to its dev runner (`pnpm start` / `pnpm dev`) when no build output is
+ * found. bringUp waits for a real 2xx on the API `/meta` before returning so the
+ * suite never starts against a not-yet-serving API.
+ *
+ * Lifecycle: `bringUpTestSession` → run Playwright → `tearDownTestSession`.
+ * Teardown is idempotent and residue-free (processes, Caddy block, env bridge,
+ * session file, registry entry), so a stale session is always safely reclaimed.
+ */
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const caddy_1 = require("./caddy");
+const dev_env_1 = require("./dev-env");
+const dev_env_bridge_1 = require("./dev-env-bridge");
+const dev_identity_1 = require("./dev-identity");
+const dev_process_1 = require("./dev-process");
+const dev_project_1 = require("./dev-project");
+const dev_state_1 = require("./dev-state");
+const TEST_API_LOG = 'api.test.log';
+const TEST_APP_LOG = 'app.test.log';
+const TEST_BRIDGE_FILE = '.env.test';
+/** Internal port band for the test stack — distinct from the dev band (4000+). */
+const TEST_PORT_BASE = 4500;
+/**
+ * Heuristic for the default local shard count (`--shard auto` / bare `--shard`).
+ *
+ * Unlike CI — where each shard gets its OWN container (CPU + RAM), so N is just
+ * the runner-matrix width — local shards all share ONE machine: every shard runs
+ * a built Nuxt/Nitro server + headless Chromium + a compiled API, which together
+ * peak at ~2 PERFORMANCE cores during SSR render. The catch is headroom: once the
+ * shards' peak demand reaches the perf-core count there is nothing left for the
+ * OS / mongod / orchestrator, SSR slows 2-3x, and timing-sensitive navigations
+ * FAIL no matter how generous their timeout (true over-subscription).
+ *
+ * Measured on an M2 Max (8 perf + 4 eff cores, 12 logical) on a heavy built-SSR
+ * suite: N=2 → 7.4 min, 0 failures (stable); N=3 → 8.7 min, flaky; N=4 → 6-10 min
+ * (high variance), flaky. So the stable optimum is ~perfCores/4 — half the perf
+ * cores busy, half free as headroom. On Apple silicon ~2/3 of logical cores are
+ * perf cores, so `logical/6 ≈ perfCores/4`. This default deliberately FAVOURS a
+ * green, repeatable run over the fastest-on-paper N. Cap by RAM (~4 GB/shard),
+ * clamp to [2, 8].
+ *
+ * A LIGHTER suite (no built SSR, fast tests) or a bigger box can take more —
+ * override with an explicit `--shard N`. Always measure N vs N±1 (wall-clock AND
+ * flakes) to tune. Higher N also needs generous navigation timeouts under load
+ * (see the project's shard-aware `LT_DEV_TEST_SHARDS` timeout handling).
+ */
+function autoShardCount() {
+    const logical = (0, os_1.cpus)().length || 4;
+    const byCpu = Math.floor(logical / 6);
+    const byRam = Math.floor((0, os_1.totalmem)() / Math.pow(1024, 3) / 4);
+    return Math.max(2, Math.min(byCpu, byRam, 8));
+}
+/**
+ * Bring up the isolated test stack. Tears down any stale test session first,
+ * so this is safe to call even if a previous run crashed.
+ */
+function bringUpTestSession(layout_1, baseIdentity_1, log_1) {
+    return __awaiter(this, arguments, void 0, function* (layout, baseIdentity, log, opts = {}) {
+        const { shardIndex, skipBuild } = opts;
+        const names = testStackNames(shardIndex);
+        const { dbName, testIdentity } = resolveTestSession(layout, baseIdentity, shardIndex);
+        // Always start from a clean slate — reclaim a stale/crashed test session.
+        yield tearDownTestSession(layout, baseIdentity, log, { shardIndex, silent: true });
+        // Allocate internal ports (avoid every other registry entry incl. the dev
+        // session AND already-running sibling shards, plus anything currently
+        // listening). Sibling shards are registered before the next one allocates,
+        // so each shard lands on its own port pair.
+        const reg = (0, dev_state_1.loadRegistry)();
+        const taken = (0, dev_state_1.takenInternalPorts)(reg, testIdentity.slug);
+        const apiPort = layout.apiDir ? (0, dev_state_1.allocateInternalPort)(TEST_PORT_BASE, taken) : undefined;
+        if (apiPort)
+            taken.add(apiPort);
+        const appPort = layout.appDir ? (0, dev_state_1.allocateInternalPort)(TEST_PORT_BASE, taken) : undefined;
+        const portsToCheck = [apiPort, 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);
+            if (r)
+                throw new Error(`test internal port ${p} already in use by ${r.command} (pid ${r.pid}).`);
+        }
+        // Caddy block for the test URLs.
+        const routes = [];
+        if (testIdentity.subdomains.api && apiPort)
+            routes.push({ hostname: testIdentity.subdomains.api.hostname, upstreamPort: apiPort });
+        if (testIdentity.subdomains.app && appPort)
+            routes.push({ hostname: testIdentity.subdomains.app.hostname, upstreamPort: appPort });
+        if (routes.length === 0)
+            throw new Error('test session has no subdomains to expose (need an app project).');
+        (0, caddy_1.upsertProjectBlock)(testIdentity.slug, routes);
+        const reload = yield (0, caddy_1.reloadCaddy)();
+        if (!reload.ok)
+            throw new Error(`caddy reload failed:\n${reload.stderr}`);
+        const apiUrl = testIdentity.subdomains.api ? `https://${testIdentity.subdomains.api.hostname}` : '';
+        const appUrl = testIdentity.subdomains.app ? `https://${testIdentity.subdomains.app.hostname}` : '';
+        log.info('');
+        log.info(`Starting isolated test stack "${testIdentity.slug}"`);
+        if (appUrl)
+            log.info(`  app: ${appUrl}  →  127.0.0.1:${appPort}`);
+        if (apiUrl)
+            log.info(`  api: ${apiUrl}  →  127.0.0.1:${apiPort}`);
+        log.info(`  db:  mongodb://127.0.0.1/${dbName}  (reset before the suite by Playwright global-setup)`);
+        log.info('');
+        const devEnv = (0, dev_env_1.buildDevEnv)({
+            apiInternalPort: apiPort !== null && apiPort !== void 0 ? apiPort : 0,
+            appInternalPort: appPort !== null && appPort !== void 0 ? appPort : 0,
+            baseEnv: process.env,
+            dbName,
+            identity: testIdentity,
+        });
+        const pnpmBin = process.env.LT_PNPM_BIN || 'pnpm';
+        const pids = {};
+        // --- API: compiled (`node dist`) for stability; fall back to `pnpm start`.
+        // `skipBuild` (sibling shards) reuses the dist the first shard produced. ---
+        if (layout.apiDir && apiPort) {
+            let build = 0;
+            if (!skipBuild) {
+                log.info(log.dim('Building API (compiled, for stable long runs) …'));
+                build = yield (0, dev_process_1.runChildInherit)(pnpmBin, ['run', '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 apiEnv = Object.assign(Object.assign({}, devEnv.api.env), { NODE_ENV: 'local' });
+            let apiSpawn;
+            if (build === 0 && entry) {
+                apiSpawn = (0, dev_process_1.spawnDetached)('node', [entry], {
+                    cwd: layout.apiDir,
+                    env: apiEnv,
+                    logFile: (0, path_1.join)(layout.root, '.lt-dev', names.apiLog),
+                });
+            }
+            else {
+                log.warn('compiled API not available — falling back to `pnpm start` (ts-node).');
+                apiSpawn = (0, dev_process_1.spawnDetached)(pnpmBin, ['start'], {
+                    cwd: layout.apiDir,
+                    env: apiEnv,
+                    logFile: (0, path_1.join)(layout.root, '.lt-dev', names.apiLog),
+                });
+            }
+            if (apiSpawn)
+                pids.api = apiSpawn.pid;
+        }
+        // --- App: BUILT (`nuxt build` → `node .output/server/index.mjs`) for speed +
+        // prod-fidelity; fall back to the Nuxt dev server when no build output exists.
+        // The built server has no Vite cold-compile (which dominates a dev-mode suite
+        // — ~84% of runtime) and runs the SAME production bundle a deployment ships.
+        // buildDevEnv sets NUXT_PUBLIC_API_PROXY=false, so the built app talks
+        // cross-origin to the test API exactly like prod (the injected session cookie
+        // must be a cross-subdomain DOMAIN cookie — see the project's parseCookieHeader).
+        // Rebuilt every run so the suite never hits stale code (no build-skip / reuse). ---
+        if (layout.appDir && appPort) {
+            let appBuild = 0;
+            if (!skipBuild) {
+                log.info(log.dim('Building App (nuxt build, for speed + prod-fidelity) …'));
+                appBuild = yield (0, dev_process_1.runChildInherit)(pnpmBin, ['run', 'build'], { cwd: layout.appDir, env: devEnv.app.env });
+            }
+            const appEntry = ['.output/server/index.mjs']
+                .map((rel) => (0, path_1.join)(layout.appDir, rel))
+                .find((p) => (0, fs_1.existsSync)(p));
+            let appSpawn;
+            if (appBuild === 0 && appEntry) {
+                appSpawn = (0, dev_process_1.spawnDetached)('node', [appEntry], {
+                    cwd: layout.appDir,
+                    env: devEnv.app.env,
+                    logFile: (0, path_1.join)(layout.root, '.lt-dev', names.appLog),
+                });
+            }
+            else {
+                log.warn('built app not available — falling back to `pnpm dev` (slower: cold-compiles routes).');
+                appSpawn = (0, dev_process_1.spawnDetached)(pnpmBin, ['dev'], {
+                    cwd: layout.appDir,
+                    env: devEnv.app.env,
+                    logFile: (0, path_1.join)(layout.root, '.lt-dev', names.appLog),
+                });
+            }
+            if (appSpawn)
+                pids.app = appSpawn.pid;
+        }
+        // Persist test session + registry entry (so ports are reserved + status sees it).
+        (0, dev_state_1.saveSession)(layout.root, { pids, startedAt: new Date().toISOString() }, names.sessionFile);
+        const subdomainMap = {};
+        for (const [k, v] of Object.entries(testIdentity.subdomains))
+            subdomainMap[k] = v.hostname;
+        reg.projects[testIdentity.slug] = {
+            dbName,
+            internalPorts: { api: apiPort, app: appPort },
+            lastUsedAt: new Date().toISOString(),
+            path: layout.root,
+            subdomains: subdomainMap,
+        };
+        (0, dev_state_1.saveRegistry)(reg);
+        // ENV bridge for external tooling (kept separate from the dev `.env`).
+        (0, dev_env_bridge_1.writeEnvBridge)(layout.root, devEnv, dbName, names.bridgeFile);
+        // Wait for the test App to answer (best-effort).
+        if (appUrl) {
+            log.info(log.dim(`Waiting for ${appUrl} …`));
+            yield (0, dev_process_1.waitForHttp)(appUrl, 90000);
+        }
+        // Wait for the test API to actually SERVE (real 2xx on /meta) before handing
+        // off to Playwright. Previously bringUp only waited for the App, so a compiled
+        // API still connecting to Mongo made the first specs skip via the suite's
+        // `ensureApiReachableOrSkip` guard (the API-readiness race). A strict 2xx is
+        // required: Caddy answers 502 while its upstream is still booting, which the
+        // default (lenient) predicate would accept as "up".
+        if (apiUrl) {
+            log.info(log.dim(`Waiting for ${apiUrl}/meta …`));
+            const apiReady = yield (0, dev_process_1.waitForHttp)(`${apiUrl}/meta`, 120000, (status) => status >= 200 && status < 300);
+            if (!apiReady)
+                log.warn(`Test API did not answer 2xx on ${apiUrl}/meta within 120s — the first specs may skip.`);
+        }
+        return { apiUrl, appEnv: devEnv.app.env, appUrl, dbName, pids, testIdentity };
+    });
+}
+/** True when a test session file exists (used by status/down). */
+function hasTestSession(root) {
+    return (0, dev_state_1.loadSession)(root, dev_state_1.TEST_SESSION_FILE) !== null;
+}
+/** Build the dedicated test identity + test DB name for a project. */
+function resolveTestSession(layout, baseIdentity, shardIndex) {
+    const names = testStackNames(shardIndex);
+    const testIdentity = (0, dev_identity_1.buildTestIdentity)(baseIdentity, names.identitySuffix);
+    const dbName = (0, dev_project_1.deriveTestDbName)((0, dev_project_1.deriveDbName)(layout.apiDir, baseIdentity.slug)) + names.dbSuffix;
+    return { dbName, testIdentity };
+}
+/**
+ * Run the suite SHARDED across `total` fully-isolated stacks in parallel — the
+ * local equivalent of the CI `parallel: N` + `--shard=i/N` matrix, but on one
+ * machine: each shard gets its own URLs/ports/Caddy block AND its own DB
+ * (`<…>-test-<i>`), so there is zero cross-shard data contention (the reason
+ * in-process `workers > 1` against a single stack produces false results —
+ * `cleanupTestEntities` / "pick any active season" collide).
+ *
+ * The first shard builds the API + App; siblings reuse that build (`skipBuild`),
+ * since the bundles are shard-agnostic (URLs come from runtime env). Stacks are
+ * brought up sequentially (builds + Caddy reloads serialise cleanly), then the
+ * N Playwright `--shard=i/N` processes run CONCURRENTLY, each against its own
+ * stack, output captured to `.lt-dev/shard.<i>.test.log`. Returns 0 iff every
+ * shard passed. Teardown is the caller's responsibility (so `--keep` works).
+ */
+function runShardedTestSession(layout, baseIdentity, log, opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const total = Math.max(2, Math.floor(opts.total));
+        const contexts = [];
+        // Bring up the N isolated stacks sequentially (shard 1 builds; 2..N reuse).
+        for (let index = 1; index <= total; index++) {
+            log.info('');
+            log.info(`▶ shard ${index}/${total}: bringing up isolated stack …`);
+            const ctx = yield bringUpTestSession(layout, baseIdentity, log, { shardIndex: index, skipBuild: index > 1 });
+            contexts.push({ ctx, index });
+        }
+        // Run the N Playwright shards CONCURRENTLY, each against its own stack/DB.
+        log.info('');
+        log.info(`Running ${total} Playwright shards in parallel (one isolated stack each) …`);
+        const appDir = layout.appDir;
+        const results = yield Promise.all(contexts.map((_a) => __awaiter(this, [_a], void 0, function* ({ ctx, index }) {
+            // `LT_DEV_TEST_SHARDS` signals to the project's playwright.config that the
+            // suite runs under concurrent sharded load, so it can relax navigation /
+            // test timeouts (N built SSR servers + N Chromium saturate the CPU and slow
+            // every navigation) without loosening them for serial runs.
+            const env = Object.assign(Object.assign({}, ctx.appEnv), { LT_DEV_TEST_SHARDS: String(total), MONGO_URI: `mongodb://127.0.0.1/${ctx.dbName}` });
+            const logFile = (0, path_1.join)(layout.root, '.lt-dev', `shard.${index}.test.log`);
+            // Invoke Playwright DIRECTLY via `pnpm exec` (NOT `pnpm run test:e2e -- …`):
+            // forwarding option flags through `pnpm run`'s `--` is unreliable — pnpm
+            // passed the separator on to Playwright, which then read `--shard`/
+            // `--reporter` as file FILTERS (not options) → every shard ran the whole
+            // suite. `pnpm exec` hands args straight to the binary (mirrors CI).
+            const args = ['exec', 'playwright', 'test', `--shard=${index}/${total}`, '--reporter=line', ...opts.forwarded];
+            const code = yield (0, dev_process_1.runChildToFile)(opts.pnpmBin, args, { cwd: appDir, env, logFile });
+            return { code, index, logFile };
+        })));
+        // Aggregate per-shard exit codes into a single result.
+        let failed = 0;
+        log.info('');
+        for (const r of results.sort((a, b) => a.index - b.index)) {
+            const ok = r.code === 0;
+            if (!ok)
+                failed++;
+            log.info(`  shard ${r.index}/${total}: ${ok ? 'passed' : `FAILED (exit ${r.code})`}  (log: ${r.logFile})`);
+        }
+        return failed === 0 ? 0 : 1;
+    });
+}
+/**
+ * Tear down the unsharded test stack AND every sharded stack discovered on disk
+ * (`state.test.<i>.json` in `.lt-dev/`). Used by `lt dev test down` so a
+ * `--keep`-ed sharded run is fully reclaimed by one command.
+ */
+function tearDownAllTestSessions(layout_1, baseIdentity_1, log_1) {
+    return __awaiter(this, arguments, void 0, function* (layout, baseIdentity, log, opts = {}) {
+        const stopped = [];
+        // Unsharded session first.
+        const base = yield tearDownTestSession(layout, baseIdentity, log, { silent: opts.silent });
+        stopped.push(...base.stopped);
+        // Then any sharded sessions still on disk.
+        let entries = [];
+        try {
+            entries = (0, fs_1.readdirSync)((0, path_1.join)(layout.root, '.lt-dev'));
+        }
+        catch (_a) {
+            /* no .lt-dev dir → nothing sharded to reclaim */
+        }
+        const shardIndices = entries
+            .map((f) => f.match(/^state\.test\.(\d+)\.json$/))
+            .filter((m) => m !== null)
+            .map((m) => Number(m[1]))
+            .sort((a, b) => a - b);
+        for (const shardIndex of shardIndices) {
+            const r = yield tearDownTestSession(layout, baseIdentity, log, { shardIndex, silent: opts.silent });
+            stopped.push(...r.stopped);
+        }
+        return { stopped };
+    });
+}
+/**
+ * Tear down the test stack: stop processes, remove the Caddy block, clear the
+ * env bridge + session file + registry entry. Idempotent + residue-free.
+ */
+function tearDownTestSession(layout_1, baseIdentity_1, log_1) {
+    return __awaiter(this, arguments, void 0, function* (layout, baseIdentity, log, opts = {}) {
+        const names = testStackNames(opts.shardIndex);
+        const testIdentity = (0, dev_identity_1.buildTestIdentity)(baseIdentity, names.identitySuffix);
+        const stopped = [];
+        const session = (0, dev_state_1.loadSession)(layout.root, names.sessionFile);
+        if (session) {
+            for (const [name, pid] of Object.entries(session.pids)) {
+                if (!pid)
+                    continue;
+                if (!(0, dev_state_1.isPidAlive)(pid)) {
+                    stopped.push(`${name} (pid ${pid}, already dead)`);
+                    continue;
+                }
+                // SIGTERM → wait → SIGKILL. A compiled `node dist` API catches SIGTERM
+                // for graceful shutdown and can hang on open Mongo connections, so a
+                // single SIGTERM would leave it listening + holding the test DB. Escalate
+                // to guarantee the residue-free teardown promise.
+                const gone = yield (0, dev_process_1.terminateProcessGroup)(pid);
+                stopped.push(gone ? `${name} (pid ${pid})` : `${name} (pid ${pid}, SURVIVED SIGKILL!)`);
+            }
+            (0, dev_state_1.clearSession)(layout.root, names.sessionFile);
+        }
+        const removed = (0, caddy_1.removeProjectBlock)(testIdentity.slug);
+        if (removed) {
+            const r = yield (0, caddy_1.reloadCaddy)();
+            if (!r.ok && !opts.silent)
+                log.warn(`Removed test Caddy block but reload failed: ${r.stderr.split('\n')[0]}`);
+        }
+        (0, dev_env_bridge_1.clearEnvBridge)(layout.root, names.bridgeFile);
+        // Drop the registry entry so the test slug + ports are reclaimed.
+        const reg = (0, dev_state_1.loadRegistry)();
+        if (reg.projects[testIdentity.slug]) {
+            delete reg.projects[testIdentity.slug];
+            (0, dev_state_1.saveRegistry)(reg);
+        }
+        if (!opts.silent && stopped.length > 0)
+            log.info(`Stopped test stack: ${stopped.join(', ')}`);
+        return { stopped };
+    });
+}
+/**
+ * Resolve the per-stack file/identity names. For a sharded run (`shardIndex`
+ * given) everything gets a `.<i>` / `-<i>` suffix so N stacks coexist without
+ * clobbering each other's session file, env bridge, logs, Caddy block or DB.
+ * Unsharded (shardIndex undefined) keeps the original single-stack names.
+ */
+function testStackNames(shardIndex) {
+    const sharded = shardIndex !== undefined;
+    return {
+        apiLog: sharded ? `api.test.${shardIndex}.log` : TEST_API_LOG,
+        appLog: sharded ? `app.test.${shardIndex}.log` : TEST_APP_LOG,
+        bridgeFile: sharded ? `${TEST_BRIDGE_FILE}.${shardIndex}` : TEST_BRIDGE_FILE,
+        dbSuffix: sharded ? `-${shardIndex}` : '',
+        identitySuffix: sharded ? `-test-${shardIndex}` : '-test',
+        sessionFile: sharded ? `state.test.${shardIndex}.json` : dev_state_1.TEST_SESSION_FILE,
+    };
+}

package/package.json

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