@lenne.tech/cli 1.36.0 → 1.37.1

package/build/commands/ticket/stop.js

@@ -9,52 +9,128 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const fs_1 = require("fs");
+exports.help = void 0;
 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_ticket_1 = require("../../lib/dev-ticket");
+const workspace_integration_1 = require("../../lib/workspace-integration");
 /**
  * `lt ticket stop [<id>]` — tear a ticket env down + remove its worktree.
  *
  *   1. `lt dev down` inside the worktree (stops the ticket stack + any test
  *      stacks, removes the Caddy block — residue-free),
  *   2. `git worktree remove` (the BRANCH is kept, so nothing is lost),
- *   3. `--drop-db` also drops the ticket's empty dev + test databases.
+ *   3. drops the ticket's dev + test databases (`--keep-db` opts out).
+ *
+ * The env is gone entirely afterwards — worktree AND registry entry — so the
+ * databases would be orphans: nothing references them, nothing lists them, and
+ * nothing reuses them. They are therefore dropped by default; keeping them was
+ * how machines ended up with hundreds of dead databases from deleted tickets.
+ *
+ * ORDER MATTERS: the drop is irreversible and `git worktree remove` can fail
+ * (locked worktree, modified submodule, permissions). Dropping first would leave
+ * the user with a surviving env whose data is gone — while the error message
+ * tells them to commit and retry. So the fallible step runs first and the
+ * irreversible one only after it succeeded.
  *
  * Run with NO id from INSIDE a ticket worktree to clean up THIS environment
  * (the current folder is removed; the process steps out to the main repo first).
  */
+exports.help = {
+    description: 'Stop a ticket env: remove its worktree (branch kept) and drop its databases',
+    examples: [
+        'ticket stop 2200',
+        'ticket stop 2200 --keep-db',
+        'ticket stop            # from inside a ticket worktree',
+    ],
+    features: [
+        'Runs `lt dev down` inside the worktree (stack + Caddy block, residue-free)',
+        'Removes the git worktree — the BRANCH is kept, so committed work survives',
+        'Drops the ticket dev + test databases (they are orphans once the env is gone)',
+        'Refuses to remove a worktree with uncommitted changes or unpushed commits',
+    ],
+    name: 'stop',
+    options: [
+        {
+            default: false,
+            description: 'Keep the ticket databases instead of dropping them (they are orphans — drop them manually later)',
+            flag: '--keep-db',
+            required: false,
+            type: 'boolean',
+        },
+        {
+            default: false,
+            description: 'Remove the worktree even with uncommitted changes / unpushed commits (the branch is kept)',
+            flag: '--force',
+            required: false,
+            type: 'boolean',
+        },
+        {
+            default: false,
+            description: 'Skip the confirmation prompt for dropping the databases',
+            flag: '--noConfirm',
+            required: false,
+            type: 'boolean',
+        },
+        {
+            default: false,
+            description: 'Deprecated no-op — dropping is the default now. Use --keep-db to opt out.',
+            flag: '--drop-db',
+            required: false,
+            type: 'boolean',
+        },
+    ],
+};
 const StopCommand = {
     alias: ['rm'],
-    description: 'Stop a ticket env + remove its worktree (branch kept); no id = the current worktree',
+    // Discloses what is DESTROYED, not just what is preserved — this line is the most-read
+    // documentation the command has, and dropping databases is its irreversible part.
+    description: 'Stop ticket env + drop its DBs',
     name: 'stop',
     run: (toolbox) => __awaiter(void 0, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e;
-        const { filesystem, parameters, print: { colors, error, info, success, warning }, } = toolbox;
+        var _a, _b, _c, _d, _e, _f;
+        const { filesystem, parameters, print: { colors, error, info, success, warning }, prompt: { confirm }, } = toolbox;
         const layout = (0, dev_project_1.resolveLayout)(filesystem.cwd(), filesystem);
         let mainRepoRoot;
         try {
             mainRepoRoot = (0, dev_ticket_1.gitMainRepoRoot)(layout.root);
         }
-        catch (_f) {
+        catch (_g) {
             error('Not inside a git repository.');
             if (!parameters.options.fromGluegunMenu)
                 process.exit(1);
             return 'ticket stop: not a git repo';
         }
+        // `--keep-db` PREVENTS an irreversible drop, so it is read fail-closed: presence
+        // means keep, only an explicit negation still drops. (A strict `=== true` would
+        // destroy the data on `--keep-db=true`, which yargs-parser hands over as a STRING.)
+        const { keep: keepDb, strayValue } = (0, dev_ticket_1.keepDbFlag)(parameters.options);
+        // `--keep-db` takes no value, so yargs-parser swallows the next positional as one:
+        // `lt ticket stop --keep-db 2200` loses the id. Recover it rather than silently
+        // falling back to the marker and stopping a DIFFERENT ticket than the user named.
+        if (strayValue !== null && parameters.first != null) {
+            error(`Ambiguous: ticket "${parameters.first}" given, but --keep-db also carries "${strayValue}".`);
+            info(colors.dim('  --keep-db takes no value. Use: lt ticket stop <id> --keep-db'));
+            if (!parameters.options.fromGluegunMenu)
+                process.exit(1);
+            return 'ticket stop: ambiguous --keep-db';
+        }
         // Id from the argument — or, when invoked with NO id from INSIDE a ticket
         // worktree, the current worktree's own ticket (so a bare `lt ticket stop`
         // cleans up "this" environment and removes this very folder).
-        const fromMarker = parameters.first == null ? (0, dev_ticket_1.readTicketMarker)(layout.root) : null;
-        const id = String((_b = (_a = parameters.first) !== null && _a !== void 0 ? _a : fromMarker) !== null && _b !== void 0 ? _b : '').trim();
+        const fromMarker = parameters.first == null && strayValue === null ? (0, dev_ticket_1.readTicketMarker)(layout.root) : null;
+        const id = String((_c = (_b = (_a = parameters.first) !== null && _a !== void 0 ? _a : strayValue) !== null && _b !== void 0 ? _b : fromMarker) !== null && _c !== void 0 ? _c : '').trim();
         if (!id) {
-            error('Usage: lt ticket stop <id> [--drop-db] [--force]  — or run with no id from INSIDE a ticket worktree.');
+            error('Usage: lt ticket stop <id> [--keep-db] [--force]  — or run with no id from INSIDE a ticket worktree.');
             if (!parameters.options.fromGluegunMenu)
                 process.exit(1);
             return 'ticket stop: missing id';
         }
+        if (strayValue !== null) {
+            info(colors.dim(`  (read ticket "${id}" from --keep-db — the flag takes no value)`));
+        }
         const wt = (0, dev_ticket_1.listWorktrees)(mainRepoRoot).find((w) => w.ticket === id);
         if (!wt) {
             error(`No ticket worktree "${id}" found. See \`lt ticket list\`.`);
@@ -62,6 +138,16 @@ const StopCommand = {
                 process.exit(1);
             return 'ticket stop: not found';
         }
+        // `git worktree list` reports the MAIN checkout as its first entry, so a stray
+        // `.lt-dev/ticket` marker there would make us "stop" the main repo: drop its
+        // databases, then fail to remove it. Never treat the main checkout as a ticket.
+        if ((0, dev_state_1.sameRealPath)(wt.path, mainRepoRoot)) {
+            error(`"${id}" resolves to the MAIN checkout, not a ticket worktree — refusing.`);
+            info(colors.dim('  A stale .lt-dev/ticket marker in the main repo? Delete it and retry.'));
+            if (!parameters.options.fromGluegunMenu)
+                process.exit(1);
+            return 'ticket stop: refused (main worktree)';
+        }
         // SAFETY: never silently delete unsaved work. Warn + REFUSE (unless --force)
         // when the worktree has uncommitted changes OR unpushed commits, so the user
         // commits + pushes first. (`--force` removes anyway; the branch is kept, so
@@ -77,7 +163,7 @@ const StopCommand = {
                     info(colors.dim(`      … and ${safety.dirtySource.length - 12} more`));
             }
             if (safety.unpushed > 0) {
-                warning(`  • ${safety.unpushed} commit(s) on "${(_c = wt.branch) !== null && _c !== void 0 ? _c : '-'}" not pushed to any remote`);
+                warning(`  • ${safety.unpushed} commit(s) on "${(_d = wt.branch) !== null && _d !== void 0 ? _d : '-'}" not pushed to any remote`);
             }
             info('');
             info(colors.dim('  Commit + push first (the branch is kept), or re-run with --force to remove anyway.'));
@@ -85,37 +171,70 @@ const StopCommand = {
                 process.exit(1);
             return 'ticket stop: unsaved work (use --force)';
         }
+        // Resolve the drop targets BEFORE anything is torn down (the registry entry is
+        // deleted at the end, and the layout is read from the main repo) — but execute
+        // the drop LAST, after the worktree is provably gone.
+        const base = (0, dev_identity_1.buildIdentity)(mainRepoRoot);
+        const ticketSlug = `${base.slug}-${id}`;
+        const mainLayout = (0, dev_project_1.resolveLayout)(mainRepoRoot, filesystem);
+        // The plan is built even with --keep-db: its targets are then RECORDED as kept
+        // (registry `keptDbs`) so the orphan sweep (`lt dev prune` / `lt dev up`) never
+        // collects what the user explicitly asked to keep.
+        const plan = (0, dev_ticket_1.planTicketDbDrop)({
+            hasApi: Boolean(mainLayout.apiDir),
+            // Observe what exists so sharded test DBs (`…-test-<n>`) are included —
+            // their shard index cannot be derived. Listing failure (no mongosh /
+            // Mongo down) degrades to the derived candidates.
+            observedDbNames: (0, dev_ticket_1.listDatabaseNames)(undefined, [mainLayout.apiDir, mainRepoRoot]),
+            projectDevDb: (0, dev_project_1.deriveDbName)(mainLayout.apiDir, base.slug),
+            registryEntry: (0, dev_state_1.loadRegistry)().projects[ticketSlug],
+            ticketId: id,
+            worktreePath: wt.path,
+        });
+        let dropTargets = keepDb ? [] : plan.targets;
+        if (!keepDb) {
+            if (plan.foreignEntryPath) {
+                warning(`  registry slug "${ticketSlug}" belongs to another checkout (${plan.foreignEntryPath}) —`);
+                warning("    ignoring its database name (it is not this ticket's).");
+            }
+            for (const db of plan.refused) {
+                warning(`  refusing to drop "${db}" — it is not a database of ticket "${id}".`);
+                info(colors.dim('    (drop it manually if you are sure it is safe.)'));
+            }
+        }
         // If we are removing the worktree we are standing in, step the process out
         // to the main repo first so git can remove the folder cleanly.
-        const removingCwd = fromMarker !== null || samePath(wt.path, layout.root);
+        const removingCwd = fromMarker !== null || (0, dev_state_1.sameRealPath)(wt.path, layout.root);
         if (removingCwd) {
             try {
                 process.chdir(mainRepoRoot);
             }
-            catch (_g) {
+            catch (_h) {
                 /* best-effort */
             }
         }
+        // Dropping a database is irreversible and — unlike the source work the safety gate
+        // above protects — it can never be recovered from a branch. So it is the one step we
+        // confirm. Non-interactive callers (CI, AI agents, `--noConfirm`) get the documented
+        // default without a prompt; the guards above are what make that safe, not the prompt.
+        if (dropTargets.length > 0 && !(0, workspace_integration_1.isNonInteractive)(parameters.options.noConfirm === true)) {
+            info('');
+            warning('  These databases will be DROPPED (irreversible):');
+            dropTargets.forEach((db) => info(colors.dim(`    • ${db}`)));
+            if (!(yield confirm('Drop them?', true))) {
+                info(colors.dim('  keeping the databases (same as --keep-db).'));
+                dropTargets = [];
+            }
+        }
         info('');
         info(colors.bold(`Stopping ticket "${id}"`));
         // 1. Tear the isolated stack down from inside the worktree (marker-aware).
         info(colors.dim('  lt dev down …'));
-        yield (0, dev_process_1.runChildInherit)(process.execPath, [process.argv[1], 'dev', 'down'], { cwd: wt.path, env: process.env });
-        // 2. Optionally drop the ticket databases (they are otherwise just left empty).
-        if (parameters.options.dropDb === true || parameters.options['drop-db'] === true) {
-            const base = (0, dev_identity_1.buildIdentity)(mainRepoRoot);
-            const entry = (0, dev_state_1.loadRegistry)().projects[`${base.slug}-${id}`];
-            const mainLayout = (0, dev_project_1.resolveLayout)(mainRepoRoot, filesystem);
-            const devDb = (_d = entry === null || entry === void 0 ? void 0 : entry.dbName) !== null && _d !== void 0 ? _d : (0, dev_project_1.deriveTicketDbName)((0, dev_project_1.deriveDbName)(mainLayout.apiDir, base.slug), id);
-            const testDb = (0, dev_project_1.deriveTestDbName)(devDb);
-            for (const db of [devDb, testDb]) {
-                if ((0, dev_ticket_1.dropDatabase)(db))
-                    info(colors.dim(`  dropped db ${db}`));
-                else
-                    warning(`  could not drop db ${db} (mongosh missing or DB not reachable) — drop it manually if needed.`);
-            }
-        }
-        // 3. Remove the worktree (branch is kept). Auto-force when the ONLY dirty
+        yield (0, dev_process_1.runChildInherit)(process.execPath, [process.argv[1], 'dev', 'down'], {
+            cwd: wt.path,
+            env: process.env,
+        });
+        // 2. Remove the worktree (branch is kept). Auto-force when the ONLY dirty
         //    files are auto-discardable — framework-generated (e.g. `nuxt dev`
         //    rewrites the tracked `.nuxtrc` on boot) OR pristine lt-dev self-heal
         //    patches (config.env.ts/nuxt.config.ts/playwright.config.ts that
@@ -132,23 +251,51 @@ const StopCommand = {
         catch (e) {
             error(`git worktree remove failed: ${e.message}`);
             info(colors.dim('  The worktree has uncommitted SOURCE changes — commit/stash them, or pass --force to discard.'));
+            info(colors.dim('  Nothing was dropped — the databases are untouched.'));
             if (!parameters.options.fromGluegunMenu)
                 process.exit(1);
             return 'ticket stop: worktree remove failed';
         }
+        // 3. The env is provably gone now — so its databases are orphans and it is safe to
+        //    do the one thing we cannot undo.
+        if (keepDb) {
+            info(colors.dim('  --keep-db → databases kept (nothing references them anymore; drop them manually when done).'));
+            // Record the kept names on the MAIN project's entry — the ticket's own entry is
+            // deleted below, and without this record the orphan sweep would collect them.
+            if (plan.targets.length > 0) {
+                const reg = (0, dev_state_1.loadRegistry)();
+                const main = reg.projects[base.slug];
+                if (main) {
+                    main.keptDbs = [...new Set([...((_e = main.keptDbs) !== null && _e !== void 0 ? _e : []), ...plan.targets])];
+                    (0, dev_state_1.saveRegistry)(reg);
+                    info(colors.dim(`    recorded as kept in the registry: ${plan.targets.join(', ')}`));
+                }
+            }
+        }
+        else if (dropTargets.length > 0) {
+            const { dropped, reason } = (0, dev_ticket_1.dropDatabases)(dropTargets, undefined, [mainLayout.apiDir, mainRepoRoot]);
+            dropped.forEach((db) => info(colors.dim(`  dropped db ${db}`)));
+            if (reason === 'no-mongosh') {
+                warning('  mongosh is not installed — the ticket databases were NOT dropped.');
+                info(colors.dim(`    install it (brew install mongosh) and drop them manually: ${dropTargets.join(', ')}`));
+            }
+            else if (reason === 'unreachable') {
+                warning('  MongoDB is not reachable — the ticket databases were NOT dropped.');
+                info(colors.dim(`    start it and drop them manually: ${dropTargets.join(', ')}`));
+            }
+        }
         // The whole env is gone now — drop the ticket's registry entry so its slug +
         // reserved ports are reclaimed (`lt dev down` only ends the session, keeping
         // the entry for a restart; `lt ticket stop` removes the env entirely).
         {
             const reg = (0, dev_state_1.loadRegistry)();
-            const ticketSlug = `${(0, dev_identity_1.buildIdentity)(mainRepoRoot).slug}-${id}`;
             if (reg.projects[ticketSlug]) {
                 delete reg.projects[ticketSlug];
                 (0, dev_state_1.saveRegistry)(reg);
             }
         }
         info('');
-        success(`Ticket "${id}" stopped — worktree removed, branch "${(_e = wt.branch) !== null && _e !== void 0 ? _e : '-'}" kept.`);
+        success(`Ticket "${id}" stopped — worktree removed, branch "${(_f = wt.branch) !== null && _f !== void 0 ? _f : '-'}" kept.`);
         if (removingCwd)
             info(colors.dim(`  This folder is gone — your shell is still in it. Run: cd ${mainRepoRoot}`));
         if (!parameters.options.fromGluegunMenu)
@@ -156,13 +303,4 @@ const StopCommand = {
         return `ticket stop: ${id}`;
     }),
 };
-/** True if two paths point at the same location (resolving symlinks, e.g. /tmp → /private/tmp). */
-function samePath(a, b) {
-    try {
-        return (0, fs_1.realpathSync)(a) === (0, fs_1.realpathSync)(b);
-    }
-    catch (_a) {
-        return a === b;
-    }
-}
 module.exports = StopCommand;

package/build/lib/dev-prune.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectDevPrunePlan = collectDevPrunePlan;
+exports.listLiveTicketIds = listLiveTicketIds;
+exports.listPastTicketIds = listPastTicketIds;
+exports.planOrphanTicketDbSweep = planOrphanTicketDbSweep;
+exports.planRegistryPrune = planRegistryPrune;
+exports.planStaleShardDbSweep = planStaleShardDbSweep;
+/**
+ * Garbage collection for `lt dev` / `lt ticket` leftovers.
+ *
+ * Two classes of orphans accumulate on a busy machine and nothing collected them:
+ *
+ *   1. TICKET DATABASES whose environment is gone. `lt ticket stop` is the only
+ *      path that drops `<base>-<id>`(+`-test`/`-test-<n>`) — when a worktree is
+ *      deleted manually, the ticket predates the drop feature, `--keep-db` was
+ *      not intended, or mongosh/Mongo was unavailable at stop time, the DBs stay
+ *      forever (observed: 19 orphaned per-ticket DBs for a single project).
+ *
+ *   2. REGISTRY ENTRIES whose `path` no longer exists. They hold reserved
+ *      internal ports and slugs indefinitely; `lastUsedAt` is recorded but was
+ *      never used for cleanup.
+ *
+ * Safety model (fail closed, like `lt ticket stop`):
+ *   - Ticket ids are taken from THIS project's own `feat/*` branches — the one
+ *     durable record of every ticket ever started here (branches are kept on
+ *     stop). A name that merely LOOKS ticket-shaped is never enough: prefix
+ *     collisions between sibling projects (`nest-server` vs `nest-server-starter`)
+ *     make shape-based sweeps destructive.
+ *   - An id is only orphaned when it has NO live worktree and NO live registry
+ *     entry.
+ *   - Every candidate must pass {@link isTicketScopedDb} — the same last gate
+ *     `lt ticket stop` uses.
+ *   - Databases recorded in any registry entry (dbName or keptDbs — the
+ *     `lt ticket stop --keep-db` record) are NEVER touched.
+ *   - Registry pruning removes ENTRIES only, never a `-local` dev database:
+ *     a deleted folder is not consent to destroy data (the project may be
+ *     re-cloned).
+ */
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const dev_project_1 = require("./dev-project");
+const dev_ticket_1 = require("./dev-ticket");
+/** Branch prefix `lt ticket start` creates worktrees on. */
+const TICKET_BRANCH_PREFIX = 'feat/';
+/**
+ * Collect the full prune plan for one project. Reads the registry and the Mongo
+ * database listing; performs NO destructive action.
+ */
+function collectDevPrunePlan(args) {
+    const { loadRegistry, mainRepoRoot, observedDbNames, projectDevDb, slug } = args;
+    const registry = loadRegistry();
+    return {
+        observed: observedDbNames,
+        orphan: planOrphanTicketDbSweep({
+            mainRepoRoot,
+            observedDbNames,
+            projectDevDb,
+            registry,
+            slug,
+        }),
+        registryPrune: planRegistryPrune(registry),
+        shardTargets: planStaleShardDbSweep({
+            observedDbNames,
+            projectDevDb,
+            projectRoot: mainRepoRoot,
+        }),
+    };
+}
+/** Ticket ids that still have a live environment (worktree and/or live registry entry). */
+function listLiveTicketIds(mainRepoRoot, registry, slug) {
+    var _a;
+    const live = new Set();
+    try {
+        for (const wt of (0, dev_ticket_1.listWorktrees)(mainRepoRoot)) {
+            if (wt.ticket)
+                live.add(wt.ticket);
+            if ((_a = wt.branch) === null || _a === void 0 ? void 0 : _a.startsWith(TICKET_BRANCH_PREFIX)) {
+                live.add((0, dev_ticket_1.deriveTicketId)(wt.branch.slice(TICKET_BRANCH_PREFIX.length)));
+            }
+        }
+    }
+    catch (_b) {
+        /* fail closed below: without worktree info we do not sweep at all */
+        return [];
+    }
+    for (const [key, entry] of Object.entries(registry.projects)) {
+        if (key.startsWith(`${slug}-`) && entry.path && (0, fs_1.existsSync)(entry.path)) {
+            live.add(key.slice(slug.length + 1));
+        }
+    }
+    return [...live];
+}
+/**
+ * Ticket ids of every ticket EVER started in this repo, derived from its local
+ * `feat/*` branches (kept by `lt ticket stop` on purpose). Best-effort: an
+ * unreadable repo yields an empty list, which makes the sweep a no-op.
+ */
+function listPastTicketIds(mainRepoRoot) {
+    let branches;
+    try {
+        branches = (0, child_process_1.execFileSync)('git', ['-C', mainRepoRoot, 'branch', '--list', `${TICKET_BRANCH_PREFIX}*`, '--format=%(refname:short)'], { stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000 })
+            .toString()
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean);
+    }
+    catch (_a) {
+        return [];
+    }
+    const ids = branches.map((branch) => (0, dev_ticket_1.deriveTicketId)(branch.slice(TICKET_BRANCH_PREFIX.length)));
+    return [...new Set(ids)].filter((id) => id && !(0, dev_ticket_1.isReservedTicketId)(id));
+}
+/**
+ * Plan the orphan-ticket-database sweep for ONE project. Pure — no side effects.
+ *
+ * `observedDbNames` must come from an actual server listing; null (listing
+ * failed) yields an empty plan. Observation selects candidates, the safety
+ * gates decide.
+ */
+function planOrphanTicketDbSweep(args) {
+    var _a;
+    const { mainRepoRoot, observedDbNames, projectDevDb, registry, slug } = args;
+    if (!observedDbNames || observedDbNames.length === 0) {
+        return { orphanIds: [], protected: [], targets: [] };
+    }
+    const pastIds = listPastTicketIds(mainRepoRoot);
+    if (pastIds.length === 0) {
+        return { orphanIds: [], protected: [], targets: [] };
+    }
+    const liveIds = new Set(listLiveTicketIds(mainRepoRoot, registry, slug));
+    const orphanIds = pastIds.filter((id) => !liveIds.has(id));
+    // Never touch anything a registry entry still references or explicitly kept.
+    const protectedNames = new Set();
+    for (const entry of Object.values(registry.projects)) {
+        if (entry.dbName) {
+            protectedNames.add(entry.dbName);
+            protectedNames.add((0, dev_project_1.deriveTestDbName)(entry.dbName));
+        }
+        for (const kept of (_a = entry.keptDbs) !== null && _a !== void 0 ? _a : []) {
+            protectedNames.add(kept);
+        }
+    }
+    // Sibling shield: when another REGISTERED project's DB base extends ours
+    // (`nest-server` vs `nest-server-starter`), every name under the longer base
+    // belongs to the sibling — even if one of OUR branch-derived ids happens to
+    // make it parse as ticket-scoped for us (branch `feat/starter-2205` +
+    // sibling DB `nest-server-starter-2205`). The longer base wins, always.
+    const base = projectDevDb.replace(/-(local|dev)$/i, '');
+    const siblingBases = Object.values(registry.projects)
+        .map((entry) => { var _a; return (_a = entry.dbName) === null || _a === void 0 ? void 0 : _a.replace(/-(local|dev)$/i, ''); })
+        .filter((b) => Boolean(b) && b !== base && b.startsWith(`${base}-`));
+    const targets = [];
+    const shielded = [];
+    for (const id of orphanIds) {
+        for (const name of observedDbNames) {
+            if (!(0, dev_ticket_1.isTicketScopedDb)(name, id, projectDevDb))
+                continue;
+            if (protectedNames.has(name) || siblingBases.some((sb) => name === sb || name.startsWith(`${sb}-`))) {
+                shielded.push(name);
+            }
+            else {
+                targets.push(name);
+            }
+        }
+    }
+    return {
+        orphanIds: orphanIds.filter((id) => targets.some((t) => (0, dev_ticket_1.isTicketScopedDb)(t, id, projectDevDb))),
+        protected: shielded,
+        targets: [...new Set(targets)],
+    };
+}
+/**
+ * Registry entries whose recorded path no longer exists. Their slug + reserved
+ * internal ports are reclaimed by deleting the ENTRY; their databases are left
+ * alone here (ticket DBs are handled by the orphan sweep; `-local` dev DBs are
+ * never auto-dropped).
+ */
+function planRegistryPrune(registry) {
+    return Object.entries(registry.projects)
+        .filter(([, entry]) => entry.path && !(0, fs_1.existsSync)(entry.path))
+        .map(([key]) => key);
+}
+/**
+ * Stale sharded-test databases of the project itself (`<base>-test-<n>` from
+ * `lt dev test --shard`). They are ephemeral by definition — every shard run
+ * resets its DB on boot — so with no test session alive they are pure leftovers.
+ * The UNSHARDED `<base>-test` DB is kept: it is the project's steady-state test
+ * database (dev DB + test DB is the intended per-project footprint).
+ */
+function planStaleShardDbSweep(args) {
+    const { observedDbNames, projectDevDb, projectRoot } = args;
+    if (!observedDbNames)
+        return [];
+    try {
+        const sessionDir = (0, path_1.join)(projectRoot, '.lt-dev');
+        if ((0, fs_1.existsSync)(sessionDir) && (0, fs_1.readdirSync)(sessionDir).some((f) => /^state\.test.*\.json$/.test(f))) {
+            // A test session (or shard) is live — its DBs are in use.
+            return [];
+        }
+    }
+    catch (_a) {
+        return [];
+    }
+    const shardPattern = new RegExp(`^${escapeRegExp(`${(0, dev_project_1.deriveTestDbName)(projectDevDb)}-`)}\\d+$`);
+    return observedDbNames.filter((name) => shardPattern.test(name));
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/build/lib/dev-state.js

@@ -18,6 +18,7 @@ exports.isPidAlive = isPidAlive;
 exports.isValidPid = isValidPid;
 exports.loadRegistry = loadRegistry;
 exports.loadSession = loadSession;
+exports.sameRealPath = sameRealPath;
 exports.saveRegistry = saveRegistry;
 exports.saveSession = saveSession;
 exports.takenInternalPorts = takenInternalPorts;
@@ -151,6 +152,15 @@ function loadSession(root, sessionFile = SESSION_FILE) {
     }
     return null;
 }
+/** True if two paths resolve to the same location (normalising symlinks, e.g. /var → /private/var). */
+function sameRealPath(a, b) {
+    try {
+        return (0, fs_1.realpathSync)(a) === (0, fs_1.realpathSync)(b);
+    }
+    catch (_a) {
+        return a === b;
+    }
+}
 /** Atomically persist the registry. */
 function saveRegistry(reg) {
     (0, fs_1.mkdirSync)((0, path_1.dirname)(REGISTRY_PATH), { recursive: true });
@@ -200,15 +210,6 @@ function normalizeRegistry(reg) {
     }
     return reg;
 }
-/** True if two paths resolve to the same location (normalising symlinks, e.g. /var → /private/var). */
-function sameRealPath(a, b) {
-    try {
-        return (0, fs_1.realpathSync)(a) === (0, fs_1.realpathSync)(b);
-    }
-    catch (_a) {
-        return a === b;
-    }
-}
 const LOCK_PATH = `${REGISTRY_PATH}.lock`;
 /**
  * Run `fn` while holding an EXCLUSIVE lock on the registry, so concurrent

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

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TEST_INITIAL_ADMIN_ENV = void 0;
+exports.ensurePlaywrightBrowsers = ensurePlaywrightBrowsers;
 exports.autoShardCount = autoShardCount;
 exports.bringUpTestSession = bringUpTestSession;
 exports.hasTestSession = hasTestSession;
@@ -41,6 +42,7 @@ exports.tearDownTestSession = 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 child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
@@ -53,6 +55,27 @@ const dev_patches_1 = require("./dev-patches");
 const dev_process_1 = require("./dev-process");
 const dev_project_1 = require("./dev-project");
 const dev_state_1 = require("./dev-state");
+/**
+ * Make sure the Playwright browser build the app's OWN playwright version needs
+ * is installed. A freshly created (or freshly updated) project ships a
+ * playwright.config, but the per-version browser build
+ * (`chromium_headless_shell-<rev>`) may be missing from the machine cache —
+ * every spec then fails with "Executable doesn't exist" (observed: 16/16
+ * failures on a brand-new project, easily misread as a broken stack).
+ * `playwright install chromium` is idempotent and returns in about a second
+ * when the build is already cached, so running it up front costs nothing and
+ * removes a whole class of first-run failures. Best-effort: if the install
+ * fails (offline), the suite still runs and Playwright's own error explains it.
+ */
+function ensurePlaywrightBrowsers(appDir, pm, logInfo) {
+    try {
+        const args = pm.exec('playwright', ['install', 'chromium']);
+        (0, child_process_1.execFileSync)(pm.bin, args, { cwd: appDir, stdio: 'ignore', timeout: 300000 });
+    }
+    catch (_a) {
+        logInfo === null || logInfo === void 0 ? void 0 : logInfo('playwright install chromium failed — continuing (the suite reports missing browsers itself).');
+    }
+}
 const TEST_API_LOG = 'api.test.log';
 const TEST_APP_LOG = 'app.test.log';
 const TEST_BRIDGE_FILE = '.env.test';
@@ -351,6 +374,7 @@ function resolveTestSession(layout, baseIdentity, shardIndex, devDbName) {
  */
 function runShardedTestSession(layout, baseIdentity, log, opts) {
     return __awaiter(this, void 0, void 0, function* () {
+        ensurePlaywrightBrowsers(layout.appDir, opts.pm, log.info);
         const total = Math.max(2, Math.floor(opts.total));
         const contexts = [];
         // Bring up the N isolated stacks sequentially (shard 1 builds; 2..N reuse).