@lenne.tech/cli 1.35.1 → 1.37.0

package/build/lib/dev-ticket.js

@@ -5,12 +5,21 @@ exports.clearTicketMarker = clearTicketMarker;
 exports.defaultTicketBranch = defaultTicketBranch;
 exports.deriveTicketId = deriveTicketId;
 exports.dropDatabase = dropDatabase;
+exports.dropDatabases = dropDatabases;
 exports.gitBranchExists = gitBranchExists;
 exports.gitFetch = gitFetch;
 exports.gitMainRepoRoot = gitMainRepoRoot;
+exports.gitRefExists = gitRefExists;
 exports.installWorktreeDeps = installWorktreeDeps;
+exports.isReservedTicketId = isReservedTicketId;
+exports.isTicketScopedDb = isTicketScopedDb;
+exports.keepDbFlag = keepDbFlag;
+exports.listBaseRefChoices = listBaseRefChoices;
+exports.listDatabaseNames = listDatabaseNames;
 exports.listWorktrees = listWorktrees;
+exports.planTicketDbDrop = planTicketDbDrop;
 exports.readTicketMarker = readTicketMarker;
+exports.resolveBaseRef = resolveBaseRef;
 exports.resolveDevIdentity = resolveDevIdentity;
 exports.worktreeAdd = worktreeAdd;
 exports.worktreeDirtyOnlyAutoDiscardable = worktreeDirtyOnlyAutoDiscardable;
@@ -24,8 +33,9 @@ exports.writeTicketMarker = writeTicketMarker;
  * command group).
  *
  * The model: ONE git repo, N git worktrees — one per ticket/feature — each on
- * its own branch (created fresh from `origin/dev` so tickets are independent),
- * each running its own `lt dev` stack on a SUFFIXED identity:
+ * its own branch (created fresh from the repo's base branch — see
+ * {@link resolveBaseRef} — so tickets are independent), each running its own
+ * `lt dev` stack on a SUFFIXED identity:
  *
  *   ticket "DEV-2200"  →  id "2200"  →  svl-2200.localhost / api.svl-2200.localhost
  *                         worktree  <parent>/svl-2200/   branch feat/DEV-2200
@@ -49,6 +59,23 @@ const dev_project_1 = require("./dev-project");
 const dev_state_1 = require("./dev-state");
 /** Marker file (under `.lt-dev/`) that tags a worktree with its ticket id. */
 const TICKET_MARKER = 'ticket';
+/** Where ticket databases live. Deliberately loopback-only — never a remote/prod host. */
+const MONGO_BASE_URI = 'mongodb://127.0.0.1:27017';
+/** Upper bound for a single `mongosh` call, so an unreachable Mongo cannot hang a teardown. */
+const MONGOSH_TIMEOUT_MS = 10000;
+/**
+ * Ticket ids that would make the ticket's derived database collide with a
+ * PROJECT-level database.
+ *
+ * {@link deriveTicketDbName} and {@link deriveTestDbName} both strip a trailing
+ * `-(local|dev)` before appending their own suffix, so these ids round-trip onto
+ * the project's own DBs — e.g. project db `imo-local` + ticket id `local` derives
+ * back to `imo-local`, and its test db to `imo-test`. Both are the DEVELOPER's
+ * databases, not the ticket's. Rejecting the ids at creation keeps the collision
+ * from ever existing; {@link isTicketScopedDb} is the second line of defence for
+ * environments created before this guard.
+ */
+const RESERVED_TICKET_IDS = new Set(['ci', 'dev', 'e2e', 'local', 'prod', 'production', 'staging', 'test']);
 /**
  * Check whether a project's Playwright `global-setup` (if it wipes a DB) would
  * ACCEPT the per-ticket / per-shard test databases that `lt ticket` / `--shard`
@@ -77,6 +104,11 @@ function checkGlobalSetupTicketSafe(layout) {
     catch (_c) {
         return { file, hasDbReset: false, ticketSafe: true };
     }
+    // The API-style per-run scheme (db-lifecycle reporter) manages its own
+    // cleanup + naming — nothing for this Playwright-oriented check to judge.
+    if (content.includes('db-lifecycle.reporter')) {
+        return { file, hasDbReset: true, ticketSafe: true };
+    }
     const hasDbReset = /MONGO_URI|dropDatabase|emptyDatabase|deleteMany|dbNameFromUri/.test(content);
     if (!hasDbReset)
         return { file, hasDbReset: false, ticketSafe: true };
@@ -147,17 +179,63 @@ function deriveTicketId(name, asOverride) {
         return ticketMatch[1];
     return (0, dev_identity_1.slugify)(trimmed);
 }
-/** Drop a MongoDB database (best-effort, via `mongosh`). Returns true on success. */
-function dropDatabase(dbName, mongoBaseUri = 'mongodb://127.0.0.1:27017') {
+/**
+ * Drop a MongoDB database via `mongosh`.
+ *
+ * SHAPE IS DELIBERATE — do NOT "optimise" it into a single multi-DB `--eval`:
+ * the database name travels in the URI PATH (percent-encoded, so it cannot
+ * escape into the host/query and hijack the connection), and `--eval` is a
+ * CONSTANT string, so the name is never interpolated into JavaScript. Together
+ * with `execFileSync`'s argv form (no shell), that is what makes an arbitrary
+ * db name un-injectable. Batching the drops would require building the eval
+ * from the names — trading that property away to save one process spawn.
+ *
+ * Returns WHY it failed, not just that it did: a missing `mongosh` binary and an
+ * unreachable Mongo need completely different fixes from the user, and collapsing
+ * both into `false` is how a "cleanup" feature ends up silently cleaning nothing.
+ */
+function dropDatabase(dbName, mongoBaseUri = MONGO_BASE_URI, driverPaths = []) {
     try {
-        (0, child_process_1.execFileSync)('mongosh', [`${mongoBaseUri}/${encodeURIComponent(dbName)}`, '--quiet', '--eval', 'db.dropDatabase()'], {
-            stdio: 'ignore',
+        (0, child_process_1.execFileSync)('mongosh', [`${mongoBaseUri}/${encodeURIComponent(dbName)}`, '--quiet', '--eval', 'db.dropDatabase()'], 
+        // Without a timeout this blocks for as long as mongosh feels like: a Mongo that
+        // accepts TCP but never answers leaves the driver's 30s server-selection default
+        // to expire — silently, since stdio is ignored. On a default teardown path that
+        // is unacceptable, so we impose our own bound.
+        { killSignal: 'SIGKILL', stdio: 'ignore', timeout: MONGOSH_TIMEOUT_MS });
+        return 'dropped';
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            return 'unreachable';
+        // mongosh is not installed — a REAL machine state that silently disabled every DB
+        // drop for months (ticket DBs piled up because `lt ticket stop` only warned).
+        // Fall back to the PROJECT's own `mongodb` driver when the caller provides
+        // resolution paths (the API project always depends on it via nest-server).
+        const res = runWithProjectDriver(driverPaths, 'await c.db(process.env.LT_MONGO_DB).dropDatabase();', {
+            LT_MONGO_DB: dbName,
+            LT_MONGO_URI: mongoBaseUri,
         });
-        return true;
+        if (res.outcome === 'no-driver')
+            return 'no-mongosh';
+        return res.outcome === 'ok' ? 'dropped' : 'unreachable';
     }
-    catch (_a) {
-        return false;
+}
+/**
+ * Drop several databases, stopping at the first failure.
+ *
+ * A failure is never per-database: if `mongosh` is missing it is missing for all of
+ * them, and if Mongo is unreachable it is unreachable for all of them. Retrying each
+ * name would just multiply the timeout (2 names × 10s of hanging, for one diagnosis).
+ */
+function dropDatabases(dbNames, mongoBaseUri = MONGO_BASE_URI, driverPaths = []) {
+    const dropped = [];
+    for (const db of dbNames) {
+        const outcome = dropDatabase(db, mongoBaseUri, driverPaths);
+        if (outcome !== 'dropped')
+            return { dropped, reason: outcome };
+        dropped.push(db);
     }
+    return { dropped, reason: null };
 }
 /** True if a local branch with this name already exists. */
 function gitBranchExists(repoDir, branch) {
@@ -184,6 +262,18 @@ function gitMainRepoRoot(cwd) {
     const commonDir = git(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
     return (0, path_1.dirname)(commonDir);
 }
+/** True if `ref` resolves to a commit in the repo (any ref kind: local, remote, tag, sha). */
+function gitRefExists(repoDir, ref) {
+    try {
+        (0, child_process_1.execFileSync)('git', ['-C', repoDir, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`], {
+            stdio: 'ignore',
+        });
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
 /**
  * Install dependencies in a freshly-created worktree. Auto-detects the
  * project's package manager from its lockfile (pnpm hard-links from the
@@ -194,6 +284,134 @@ function installWorktreeDeps(dir) {
     const pm = (0, dev_package_manager_1.pickPackageManager)(dir);
     (0, child_process_1.execFileSync)(pm.bin, pm.installArgs, { cwd: dir, stdio: 'inherit' });
 }
+/**
+ * True for ticket ids whose derived database would collide with a project-level
+ * database (see {@link RESERVED_TICKET_IDS}). `lt ticket start` refuses them, so
+ * the collision cannot be created in the first place.
+ */
+function isReservedTicketId(id) {
+    return RESERVED_TICKET_IDS.has(id.trim().toLowerCase());
+}
+/**
+ * True only when `dbName` provably belongs to ticket `ticketId` of the project whose
+ * own dev database is `projectDevDb`.
+ *
+ * This is the LAST gate before an irreversible drop, and it exists because the name
+ * being dropped is *derived* (or read from a slug-keyed global registry) rather than
+ * observed. Two things can therefore steer it at the wrong database:
+ *
+ *   • a reserved ticket id (`local`/`dev`/`test`) derives back onto the project's own
+ *     dev/test DB — the suffix check alone would happily accept that, because the name
+ *     really does look ticket-shaped. Hence the explicit project-DB exclusion FIRST.
+ *   • a registry entry under `<slug>-<id>` that in truth belongs to a different
+ *     checkout (the registry is global and keyed by slug alone) carries THAT project's
+ *     dbName — which will not match this ticket's shape and is rejected here.
+ *
+ * A derivation that drifts must fail closed: refuse, never guess.
+ */
+function isTicketScopedDb(dbName, ticketId, projectDevDb) {
+    if (dbName === projectDevDb || dbName === (0, dev_project_1.deriveTestDbName)(projectDevDb))
+        return false;
+    const base = projectDevDb.replace(/-(local|dev)$/i, '');
+    if (dbName === `${base}-${ticketId}` || dbName === `${base}-${ticketId}-test`)
+        return true;
+    // Sharded Playwright stacks (`lt dev test --shard N`) derive one DB per shard:
+    // `<base>-<id>-test-<n>`. Without this arm they were invisible to the drop plan
+    // and orphaned on every sharded ticket test run.
+    return new RegExp(`^${escapeRegExpForDb(`${base}-${ticketId}-test-`)}\\d+$`).test(dbName);
+}
+/**
+ * Read the `--keep-db` opt-out. FAIL-CLOSED BY CONSTRUCTION.
+ *
+ * gluegun parses argv with yargs-parser and declares NO booleans, so the flag does not
+ * arrive as `true` in most of the spellings people actually type:
+ *
+ *   --keep-db          → true      (boolean)
+ *   --keep-db=true     → 'true'    (STRING)
+ *   --keep-db true     → 'true'    (STRING)
+ *   --keep-db 2200     → 2200      (NUMBER — and the ticket id is GONE from positionals)
+ *   --no-keep-db       → false     (boolean)
+ *
+ * A strict `=== true` test reads three of those as "the user did not ask to keep" and
+ * destroys the very data they asked to keep. That shape is right for `--force`, where a
+ * parse quirk means "don't force" (safe); it is exactly backwards for a flag that
+ * PREVENTS destruction.
+ *
+ * So: the flag's PRESENCE means keep. Only an explicit negation still drops.
+ */
+function keepDbFlag(options = {}) {
+    var _a;
+    const raw = (_a = options.keepDb) !== null && _a !== void 0 ? _a : options['keep-db'];
+    if (raw === undefined || raw === null)
+        return { keep: false, strayValue: null };
+    if (raw === false || raw === 'false' || raw === 0 || raw === '0')
+        return { keep: false, strayValue: null };
+    // The flag takes no value, so anything that is not an affirmation is a positional
+    // yargs-parser swallowed. Hand it back rather than silently losing it.
+    const affirmative = raw === true || ['1', 'true', 'yes'].includes(String(raw).toLowerCase());
+    return { keep: true, strayValue: affirmative ? null : String(raw) };
+}
+/**
+ * Branches offered when the user has to pick a base ref interactively (no
+ * candidate matched). Remote + local branches, most recently committed first,
+ * `origin/HEAD` filtered out (it is an alias, not a branch).
+ */
+function listBaseRefChoices(repoDir, limit = 25) {
+    let out = '';
+    try {
+        out = git(repoDir, [
+            'for-each-ref',
+            '--sort=-committerdate',
+            '--format=%(refname:short)',
+            'refs/remotes',
+            'refs/heads',
+        ]);
+    }
+    catch (_a) {
+        return [];
+    }
+    const refs = out
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l && !l.endsWith('/HEAD'));
+    return [...new Set(refs)].slice(0, limit);
+}
+/**
+ * List all database names on the local Mongo, or null when that is impossible
+ * (mongosh missing / Mongo unreachable).
+ *
+ * Used to OBSERVE what actually exists instead of deriving it: sharded test DBs
+ * (`<base>-<id>-test-<n>`) have an unbounded index, so no static candidate list
+ * can cover them. Callers must still gate every observed name through
+ * {@link isTicketScopedDb} before dropping — observation widens the candidate
+ * set, never the safety rules.
+ */
+function listDatabaseNames(mongoBaseUri = MONGO_BASE_URI, driverPaths = []) {
+    try {
+        const out = (0, child_process_1.execFileSync)('mongosh', [
+            `${mongoBaseUri}/admin`,
+            '--quiet',
+            '--eval',
+            'db.adminCommand({ listDatabases: 1, nameOnly: true }).databases.forEach(d => print(d.name))',
+        ], { killSignal: 'SIGKILL', stdio: ['ignore', 'pipe', 'ignore'], timeout: MONGOSH_TIMEOUT_MS })
+            .toString()
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean);
+        return out;
+    }
+    catch (_a) {
+        // Fall back to the project's own `mongodb` driver (see dropDatabase).
+        const res = runWithProjectDriver(driverPaths, "const { databases } = await c.db('admin').admin().listDatabases({ nameOnly: true });" +
+            ' databases.forEach((d) => console.log(d.name));', { LT_MONGO_URI: mongoBaseUri });
+        if (res.outcome !== 'ok')
+            return null;
+        return res.stdout
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean);
+    }
+}
 /** List all worktrees of the repo (parsed from `git worktree list --porcelain`). */
 function listWorktrees(repoDir) {
     let out = '';
@@ -219,6 +437,35 @@ function listWorktrees(repoDir) {
         result.push(finalizeWorktree(current));
     return result;
 }
+/**
+ * Decide which databases `lt ticket stop` may drop — pure, so the decision guarding an
+ * irreversible action is unit-testable instead of buried in a gluegun `run()` closure.
+ *
+ * The name to drop is never observed; it is DERIVED, or read from the global registry.
+ * Both sources can point at a database the ticket never owned, so every candidate is
+ * validated against the ticket's shape and anything that does not match is refused:
+ *
+ *   • App-only project    → no MongoDB exists at all → nothing to drop.
+ *   • Foreign registry    → the registry is keyed by slug alone, so `<slug>-<id>` can be
+ *                           a genuinely different project (`myapp` + ticket `admin` vs. a
+ *                           real `myapp-admin`). Its `dbName` is that project's — ignore it.
+ *   • Reserved ticket id  → `local`/`dev`/`test` derive back onto the PROJECT's own dev or
+ *                           test DB. Refused by {@link isTicketScopedDb}.
+ */
+function planTicketDbDrop(args) {
+    var _a, _b;
+    const { hasApi, observedDbNames, projectDevDb, registryEntry, ticketId, worktreePath } = args;
+    if (!hasApi)
+        return { foreignEntryPath: null, refused: [], targets: [] };
+    const trusted = (registryEntry === null || registryEntry === void 0 ? void 0 : registryEntry.path) && (0, dev_state_1.sameRealPath)(registryEntry.path, worktreePath) ? registryEntry : undefined;
+    const foreignEntryPath = registryEntry && !trusted ? ((_a = registryEntry.path) !== null && _a !== void 0 ? _a : null) : null;
+    const devDb = (_b = trusted === null || trusted === void 0 ? void 0 : trusted.dbName) !== null && _b !== void 0 ? _b : (0, dev_project_1.deriveTicketDbName)(projectDevDb, ticketId);
+    const shardCandidates = (observedDbNames !== null && observedDbNames !== void 0 ? observedDbNames : []).filter((name) => name.startsWith(`${devDb}-test-`));
+    // eslint-disable-next-line perfectionist/sort-sets -- dev DB first is the meaningful (and drop) order
+    const candidates = [...new Set([devDb, (0, dev_project_1.deriveTestDbName)(devDb), ...shardCandidates])];
+    const targets = candidates.filter((db) => isTicketScopedDb(db, ticketId, projectDevDb));
+    return { foreignEntryPath, refused: candidates.filter((db) => !targets.includes(db)), targets };
+}
 /** Read the ticket id this worktree is tagged with, or null. */
 function readTicketMarker(root) {
     const file = (0, path_1.join)(root, dev_state_1.paths.sessionDir, TICKET_MARKER);
@@ -232,6 +479,37 @@ function readTicketMarker(root) {
         return null;
     }
 }
+/**
+ * Resolve the ref a fresh ticket branch is created from.
+ *
+ * An explicit `--base` always wins (and is reported as missing when it does not
+ * resolve). Otherwise the repo's base branch is DISCOVERED, because it is not
+ * called the same everywhere — `nest-server` uses `develop`, the lt starters use
+ * `dev`, GitHub defaults to `main`:
+ *
+ *   origin/dev → origin/develop → the remote's HEAD → origin/main → origin/master
+ *   → the same names as LOCAL branches (repo without a remote)
+ *
+ * `ref: null` means none of them exists — the caller then asks the user
+ * (`lt ticket start`) instead of failing on a hard-coded `origin/dev`.
+ */
+function resolveBaseRef(repoDir, explicit) {
+    var _a;
+    const wanted = explicit === null || explicit === void 0 ? void 0 : explicit.trim();
+    if (wanted) {
+        return {
+            candidates: [wanted],
+            explicit: true,
+            ref: gitRefExists(repoDir, wanted) ? wanted : null,
+        };
+    }
+    const candidates = baseRefCandidates(repoDir);
+    return {
+        candidates,
+        explicit: false,
+        ref: (_a = candidates.find((ref) => gitRefExists(repoDir, ref))) !== null && _a !== void 0 ? _a : null,
+    };
+}
 /**
  * Resolve the dev identity + DB name for a project root, ticket-aware.
  *
@@ -268,6 +546,47 @@ function worktreeAdd(repoDir, worktreePath, branch, baseRef) {
         git(repoDir, ['worktree', 'add', '-b', branch, worktreePath, baseRef]);
     }
 }
+/** Escape a literal database-name fragment for use inside a RegExp. */
+function escapeRegExpForDb(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Run a CONSTANT driver snippet via `node -e` using the project's own `mongodb`
+ * package (nest-server APIs always depend on it). SAME injection-safety doctrine
+ * as the mongosh path: the eval string is constant, every variable travels via
+ * env — never interpolated into code. `action` receives the connected client as
+ * `c` and must be a constant string from THIS module, never caller input.
+ */
+function runWithProjectDriver(driverPaths, action, env) {
+    let driver = null;
+    for (const dir of driverPaths.filter(Boolean)) {
+        try {
+            driver = require.resolve('mongodb', { paths: [dir] });
+            break;
+        }
+        catch (_a) {
+            /* try next path */
+        }
+    }
+    if (!driver)
+        return { outcome: 'no-driver', stdout: '' };
+    const script = 'const { MongoClient } = require(process.env.LT_MONGO_DRIVER);' +
+        'MongoClient.connect(process.env.LT_MONGO_URI, { serverSelectionTimeoutMS: 8000 })' +
+        `.then(async (c) => { ${action} await c.close(); process.exit(0); })` +
+        '.catch(() => process.exit(2));';
+    try {
+        const stdout = (0, child_process_1.execFileSync)(process.execPath, ['-e', script], {
+            env: Object.assign(Object.assign(Object.assign({}, process.env), env), { LT_MONGO_DRIVER: driver }),
+            killSignal: 'SIGKILL',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: MONGOSH_TIMEOUT_MS,
+        }).toString();
+        return { outcome: 'ok', stdout };
+    }
+    catch (_b) {
+        return { outcome: 'failed', stdout: '' };
+    }
+}
 /** Framework-generated / ephemeral paths a dev/build run dirties (never real work). */
 const GENERATED_PATHS = /(^|\/)(\.nuxtrc|\.nuxt|\.nitro|\.output|dist|\.turbo|\.cache|\.eslintcache)(\/|$)|\.tsbuildinfo$/;
 /** The three git-tracked configs `lt dev up` self-heals to be env-aware. */
@@ -323,7 +642,13 @@ function worktreeSafetyReport(worktreePath) {
     const { realDirty } = classifyWorktreeDirt(worktreePath);
     let unpushed = 0;
     try {
-        unpushed = Number(git(worktreePath, ['rev-list', '--count', 'HEAD', '--not', '--remotes'])) || 0;
+        // Only meaningful when a remote EXISTS: in a local-only repo (e.g. a fresh
+        // `lt fullstack init` without --git-link) "push first" is impossible, and the
+        // branch survives worktree removal anyway — counting every commit as
+        // "unpushed" would turn the gate into a permanent dead end.
+        if (git(worktreePath, ['remote'])) {
+            unpushed = Number(git(worktreePath, ['rev-list', '--count', 'HEAD', '--not', '--remotes'])) || 0;
+        }
     }
     catch (_a) {
         /* no remotes / detached HEAD → cannot determine; treat as 0 */
@@ -336,6 +661,26 @@ function writeTicketMarker(root, id) {
     (0, fs_1.mkdirSync)(dir, { recursive: true });
     (0, fs_1.writeFileSync)((0, path_1.join)(dir, TICKET_MARKER), `${id}\n`, 'utf8');
 }
+/** Branch names a project may use as its integration branch, in preference order. */
+const BASE_BRANCH_NAMES = ['dev', 'develop', 'main', 'master'];
+/**
+ * The refs {@link resolveBaseRef} probes, in order. Remote branches first (a
+ * ticket must start from the freshest integration state), the remote's own HEAD
+ * ahead of the guessed `main`/`master`, and the local branches last so a repo
+ * without a remote still works.
+ */
+function baseRefCandidates(repoDir) {
+    const remoteHead = gitRemoteHead(repoDir);
+    const ordered = [
+        'origin/dev',
+        'origin/develop',
+        ...(remoteHead ? [remoteHead] : []),
+        'origin/main',
+        'origin/master',
+        ...BASE_BRANCH_NAMES,
+    ];
+    return ordered.filter((ref, i) => ordered.indexOf(ref) === i); // dedupe, order preserved
+}
 /**
  * Split a worktree's uncommitted changes into "auto-discardable" (framework-
  * generated files + pristine lt-dev self-heal patches) and "real" developer work.
@@ -347,10 +692,14 @@ function classifyWorktreeDirt(worktreePath) {
     const realDirty = [];
     for (const line of gitStatusPorcelain(worktreePath)) {
         const p = porcelainPath(line);
-        if (GENERATED_PATHS.test(p) || isPristineLtDevPatch(worktreePath, p))
+        if (GENERATED_PATHS.test(p) ||
+            isPristineLtDevPatch(worktreePath, p) ||
+            isPristineLtDevGitignoreAppend(worktreePath, p)) {
             autoDiscardable.push(p);
-        else
+        }
+        else {
             realDirty.push(p);
+        }
     }
     return { autoDiscardable, realDirty };
 }
@@ -363,6 +712,23 @@ function finalizeWorktree(partial) {
 function git(cwd, args) {
     return (0, child_process_1.execFileSync)('git', args, { cwd, encoding: 'utf8' }).trim();
 }
+/**
+ * The branch a remote's HEAD points at (`origin/main`, `origin/develop`, …), or
+ * null. stderr is swallowed: a repo whose `refs/remotes/<remote>/HEAD` was never
+ * set is the normal case here, not an error worth printing.
+ */
+function gitRemoteHead(repoDir, remote = 'origin') {
+    try {
+        const out = (0, child_process_1.execFileSync)('git', ['-C', repoDir, 'symbolic-ref', '--short', `refs/remotes/${remote}/HEAD`], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return out.trim() || null;
+    }
+    catch (_a) {
+        return null;
+    }
+}
 /**
  * `git status --porcelain` lines, each kept VERBATIM (not trimmed).
  *
@@ -374,13 +740,53 @@ function git(cwd, args) {
 function gitStatusPorcelain(cwd) {
     let out = '';
     try {
-        out = (0, child_process_1.execFileSync)('git', ['-C', cwd, 'status', '--porcelain', '--untracked-files=all'], { encoding: 'utf8' });
+        out = (0, child_process_1.execFileSync)('git', ['-C', cwd, 'status', '--porcelain', '--untracked-files=all'], {
+            encoding: 'utf8',
+        });
     }
     catch (_a) {
         return [];
     }
     return out.split(/\r?\n/).filter((l) => l.trim() !== '');
 }
+/**
+ * True when the dirty `.gitignore` differs from HEAD by EXACTLY the `.lt-dev/`
+ * line that `lt dev up` appends on every start (see `addToGitignore`). Older
+ * templates ship without that line, so EVERY ticket worktree's first `up` dirties
+ * `.gitignore` — and without this check every `lt ticket stop` then refuses over
+ * a machine-made change. Any other edit (removed lines, additional added lines)
+ * keeps it real work.
+ */
+function isPristineLtDevGitignoreAppend(worktreePath, relPath) {
+    if (relPath !== '.gitignore')
+        return false;
+    let head = '';
+    try {
+        head = (0, child_process_1.execFileSync)('git', ['-C', worktreePath, 'show', 'HEAD:.gitignore'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    }
+    catch (_a) {
+        return false; // not tracked in HEAD → a NEW .gitignore is real work
+    }
+    let work = '';
+    try {
+        work = (0, fs_1.readFileSync)((0, path_1.join)(worktreePath, '.gitignore'), 'utf8');
+    }
+    catch (_b) {
+        return false; // deleted → real change
+    }
+    const norm = (s) => s
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter(Boolean);
+    const headLines = norm(head);
+    const workLines = norm(work);
+    const removed = headLines.filter((l) => !workLines.includes(l));
+    const added = workLines.filter((l) => !headLines.includes(l));
+    return removed.length === 0 && added.length > 0 && added.every((l) => l === '.lt-dev/');
+}
 /**
  * True when the dirty tracked file at `relPath` (relative to the worktree root)
  * differs from its committed (HEAD) version by EXACTLY the lt-dev self-heal
@@ -398,7 +804,9 @@ function isPristineLtDevPatch(worktreePath, relPath) {
     try {
         // NOT the trimming `git()` helper — the trailing newline must survive so the
         // comparison against the (untrimmed) working-tree content is exact.
-        head = (0, child_process_1.execFileSync)('git', ['-C', worktreePath, 'show', `HEAD:${relPath}`], { encoding: 'utf8' });
+        head = (0, child_process_1.execFileSync)('git', ['-C', worktreePath, 'show', `HEAD:${relPath}`], {
+            encoding: 'utf8',
+        });
     }
     catch (_a) {
         return false; // not tracked at HEAD (e.g. a brand-new file) → never auto-discard

package/build/lib/heal-check-wrapper.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.healCheckWrapper = healCheckWrapper;
+const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const path_1 = require("path");
 /** Marker value for the report-driven check wrapper. */
@@ -39,12 +40,22 @@ function healCheckWrapper(projectRoot, assetPath) {
         return changed;
     }
     // 1. Ensure scripts/check.mjs exists and matches the bundled canonical version.
+    // GUARD: never overwrite a check.mjs with UNCOMMITTED local modifications —
+    // that would silently destroy work that exists nowhere else. A committed
+    // divergence is overwritten (recoverable via `git diff`/history, and the
+    // canonical wrapper is the supported version); an uncommitted one is kept and
+    // reported via the 'scripts/check.mjs (skipped: uncommitted changes)' entry.
     const targetScript = (0, path_1.join)(projectRoot, 'scripts', 'check.mjs');
     const bundled = (0, fs_1.readFileSync)(assetPath, 'utf8');
     if (!(0, fs_1.existsSync)(targetScript) || (0, fs_1.readFileSync)(targetScript, 'utf8') !== bundled) {
-        (0, fs_1.mkdirSync)((0, path_1.dirname)(targetScript), { recursive: true });
-        (0, fs_1.copyFileSync)(assetPath, targetScript);
-        changed.push('scripts/check.mjs');
+        if ((0, fs_1.existsSync)(targetScript) && hasUncommittedChanges(projectRoot, 'scripts/check.mjs')) {
+            changed.push('scripts/check.mjs (skipped: uncommitted changes — commit or discard them, then re-run)');
+        }
+        else {
+            (0, fs_1.mkdirSync)((0, path_1.dirname)(targetScript), { recursive: true });
+            (0, fs_1.copyFileSync)(assetPath, targetScript);
+            changed.push('scripts/check.mjs');
+        }
     }
     // 2. Wire package.json: `check` runs the wrapper; the original chain becomes `check:raw`.
     if (scripts.check !== WRAPPER) {
@@ -57,3 +68,22 @@ function healCheckWrapper(projectRoot, assetPath) {
     }
     return changed;
 }
+/**
+ * True when `relPath` has UNCOMMITTED modifications in the project's git tree.
+ * Overwriting such a file would destroy work that exists nowhere else — a
+ * committed file is recoverable via git, an uncommitted edit is not. Non-git
+ * projects (or git errors) return false: there the overwrite is the only way
+ * to distribute fixes, and `git` cannot protect what it does not track.
+ */
+function hasUncommittedChanges(projectRoot, relPath) {
+    try {
+        const out = (0, child_process_1.execFileSync)('git', ['-C', projectRoot, 'status', '--porcelain', '--', relPath], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return out.trim().length > 0;
+    }
+    catch (_a) {
+        return false;
+    }
+}