@lenne.tech/cli 1.43.0 → 1.45.0

package/build/commands/dev/doctor.js

@@ -154,23 +154,46 @@ const DoctorCommand = {
             else if (gs.file && gs.hasDbReset) {
                 line('OK', colors.green, 'global-setup allow-list is ticket + shard safe');
             }
-            // 7.5 check.mjs drift: the root wrapper is canonical (bundled with the
+            // 7.5 check wrapper drift: the root wrapper is canonical (bundled with the
             //     CLI, synced by `lt fullstack update`). A diverged copy silently
             //     misses fixes (idle-watchdog, install hoisting, summed test
             //     metrics) — surface it instead of letting copies drift apart.
+            //
+            //     Checked over the WHOLE copy set, not just `check.mjs`: the wrapper
+            //     imports siblings, so a missing or stale one makes `check` die with
+            //     ERR_MODULE_NOT_FOUND (or an import mismatch) before running a single
+            //     step. Reporting only on `check.mjs` meant doctor printed a green
+            //     "matches the canonical CLI version" for a project whose `check` was
+            //     completely broken — and doctor is the tool people reach for exactly
+            //     then.
             try {
                 const { readFileSync: read } = yield Promise.resolve().then(() => __importStar(require('fs')));
                 const { join: j } = yield Promise.resolve().then(() => __importStar(require('path')));
-                const projectCheck = j(layout.root, 'scripts', 'check.mjs');
+                const { resolveCopySet } = yield Promise.resolve().then(() => __importStar(require('../../lib/heal-check-wrapper')));
                 const bundledCheck = j(__dirname, '..', '..', 'templates', 'check', 'check.mjs');
-                if (filesystem.exists(projectCheck) && filesystem.exists(bundledCheck)) {
-                    if (read(projectCheck, 'utf8') === read(bundledCheck, 'utf8')) {
-                        line('OK', colors.green, 'scripts/check.mjs matches the canonical CLI version');
+                if (filesystem.exists(bundledCheck)) {
+                    const missing = [];
+                    const drifted = [];
+                    for (const { rel, source } of resolveCopySet(bundledCheck)) {
+                        const target = j(layout.root, rel);
+                        if (!filesystem.exists(target)) {
+                            missing.push(rel);
+                        }
+                        else if (read(target, 'utf8') !== read(source, 'utf8')) {
+                            drifted.push(rel);
+                        }
                     }
-                    else {
-                        line('WARN', colors.yellow, 'scripts/check.mjs differs from the canonical CLI version');
+                    if (missing.length > 0) {
+                        line('ERROR', colors.red, `check wrapper incomplete — missing ${missing.join(', ')}`);
+                        line('ERROR', colors.red, '  `pnpm run check` cannot start; run `lt fullstack update` to install it');
+                    }
+                    else if (drifted.length > 0) {
+                        line('WARN', colors.yellow, `${drifted.join(', ')} differs from the canonical CLI version`);
                         line('WARN', colors.yellow, '  run `lt fullstack update` to sync it (skips uncommitted local edits)');
                     }
+                    else if (filesystem.exists(j(layout.root, 'scripts', 'check.mjs'))) {
+                        line('OK', colors.green, 'check wrapper matches the canonical CLI version');
+                    }
                 }
             }
             catch (_a) {

package/build/commands/fullstack/add-api.js

@@ -330,7 +330,11 @@ const NewCommand = {
         // non-root level pnpm ignores), drop nested lockfiles the root supersedes,
         // and guarantee a root `.dockerignore` (Docker never reads a sub-project's
         // own when building from the root context).
-        (0, workspace_integration_1.finalizeWorkspaceRoot)({ filesystem, projectDir: workspaceDir });
+        // A disagreement between the two repos is not something the merge may decide
+        // silently. Reported here, and repeated in the closing block — this call site
+        // sits directly above the install output that would otherwise bury it.
+        const { conflicts } = (0, workspace_integration_1.finalizeWorkspaceRoot)({ filesystem, projectDir: workspaceDir });
+        (0, workspace_integration_1.reportWorkspaceConflicts)(conflicts, toolbox.print.warning);
         // Run install + format unless explicitly skipped (CI/agents may
         // want to chain multiple add-* calls before installing once).
         if (!skipInstall && !experimental) {
@@ -357,6 +361,7 @@ const NewCommand = {
         info('');
         success(`API integrated into ${workspaceDir} in ${toolbox.helper.msToMinutesAndSeconds(timer())}m.`);
         info('');
+        (0, workspace_integration_1.reportWorkspaceConflicts)(conflicts, toolbox.print.warning);
         info('Next:');
         if (experimental) {
             info(`  $ cd ${workspaceDir}/projects/api && bun install`);

package/build/commands/fullstack/add-app.js

@@ -259,7 +259,11 @@ const NewCommand = {
         // carry pnpm.overrides too), drop the frontend starter's standalone
         // pnpm-lock.yaml the root supersedes, and guarantee a root `.dockerignore`
         // (else the image inherits the host's node_modules, .output and .env).
-        (0, workspace_integration_1.finalizeWorkspaceRoot)({ filesystem, projectDir: workspaceDir });
+        // A disagreement between the two repos is not something the merge may decide
+        // silently. Reported here, and repeated in the closing block — this call site
+        // sits directly above the install output that would otherwise bury it.
+        const { conflicts } = (0, workspace_integration_1.finalizeWorkspaceRoot)({ filesystem, projectDir: workspaceDir });
+        (0, workspace_integration_1.reportWorkspaceConflicts)(conflicts, toolbox.print.warning);
         if (!skipInstall) {
             const installSpinner = spin('Install workspace packages');
             try {
@@ -278,6 +282,7 @@ const NewCommand = {
         info('');
         success(`App integrated into ${workspaceDir} in ${toolbox.helper.msToMinutesAndSeconds(timer())}m.`);
         info('');
+        (0, workspace_integration_1.reportWorkspaceConflicts)(conflicts, toolbox.print.warning);
         info('Next:');
         info(`  $ cd ${workspaceDir}`);
         info(`  $ ${toolbox.pm.run('start')}`);

package/build/commands/fullstack/init.js

@@ -653,7 +653,12 @@ const NewCommand = {
             // guarantees a root `.dockerignore` (else the images carry the host's
             // node_modules, a stale .output, and a local .env that `nuxt build`
             // bakes in).
-            (0, workspace_integration_1.finalizeWorkspaceRoot)({ filesystem, projectDir });
+            // Two sources setting the same pnpm key to different values is not a merge
+            // to resolve — it is a disagreement between two repos, and the merge would
+            // pick one silently. Say so here, where both halves are still visible, and
+            // again at the end (the install output below buries this one).
+            const { conflicts } = (0, workspace_integration_1.finalizeWorkspaceRoot)({ filesystem, projectDir });
+            (0, workspace_integration_1.reportWorkspaceConflicts)(conflicts, toolbox.print.warning);
             // Install all packages
             if (!experimental) {
                 const installSpinner = spin('Install all packages');
@@ -734,6 +739,7 @@ const NewCommand = {
             info('');
             success(`Generated fullstack workspace with ${frontend} in ${projectDir} with ${name} app in ${helper.msToMinutesAndSeconds(timer())}m.`);
             info('');
+            (0, workspace_integration_1.reportWorkspaceConflicts)(conflicts, toolbox.print.warning);
             info('Next:');
             if (experimental) {
                 info(`  $ cd ${projectDir}`);

package/build/commands/fullstack/update.js

@@ -198,7 +198,20 @@ const NewCommand = {
         const changedCheck = (0, heal_check_wrapper_1.healCheckWrapper)(cwd, checkAsset);
         if (changedCheck.length > 0) {
             info('');
-            success(`  Installed/updated the check wrapper: ${changedCheck.join(', ')}`);
+            // A skip entry is NOT a success — it means the wrapper stayed on its old
+            // version. Reporting the whole list through `success()` painted a refusal
+            // green.
+            const skipped = changedCheck.filter((entry) => entry.includes('skipped'));
+            const applied = changedCheck.filter((entry) => !entry.includes('skipped'));
+            if (applied.length > 0) {
+                success(`  Installed/updated the check wrapper: ${applied.join(', ')}`);
+                info('    `check` now serialises build/typecheck against the test suites,');
+                info('    so it takes longer in wall-clock but no longer destabilises API e2e runs.');
+                info('    The wrapper imports its siblings — keep them together, or `check` will not start.');
+            }
+            for (const entry of skipped) {
+                warning(`  Check wrapper NOT updated: ${entry}`);
+            }
         }
         // ── Self-heal: keep `.lt-dev/` out of git ──────────────────────────────
         //
@@ -209,6 +222,16 @@ const NewCommand = {
             info('');
             success('  Added `.lt-dev/` to .gitignore');
         }
+        // ── Self-heal: keep the check's isolated Nuxt build dir out of git ──────
+        //
+        // The check wrapper pins `NUXT_BUILD_DIR=.nuxt-check` so it never writes the
+        // `.nuxt/` a parked `nuxt dev` reads. Current starters already ignore it
+        // (via their `.nuxt-*` glob); projects scaffolded before that glob do not,
+        // and a build dir is a plausible place for a resolved runtimeConfig to be
+        // committed by accident. Idempotent.
+        if ((0, dev_patches_1.addToGitignore)(cwd, '.nuxt-check')) {
+            success('  Added `.nuxt-check` to .gitignore');
+        }
         // ── Self-heal: repair the vendor-mode migration store ──────────────────
         //
         // `migrations-utils/migrate.js` is written ONCE, at conversion time. Projects

package/build/config/vendor-runtime-deps.json

@@ -1,5 +1,4 @@
 {
-  "$schema": "./vendor-runtime-deps.schema.json",
-  "description": "Upstream @lenne.tech/nest-server devDependencies that are actually needed at runtime in a consumer project. When vendoring, these entries are promoted from upstream devDependencies into the project's dependencies so production runtime has them available.",
-  "runtimeHelpers": ["find-file-up"]
+  "$comment": "Upstream @lenne.tech/nest-server DEVDEPENDENCIES that must land in a vendored project's `dependencies`. Vendoring copies upstream `dependencies` verbatim and does not read `peerDependencies` at all, so a package the framework imports at runtime while keeping it in devDependencies would never reach the production runtime. Entries here are matched against upstream `devDependencies` only — see `isVendorRuntimeDep`, consulted in the `upstreamDevDeps` loop in `extensions/server.ts` — and promoted into `dependencies`, preferring the upstream peer RANGE over the exact devDep pin where one exists, so a generated project still receives patch-level security fixes. A package that appears ONLY in upstream `peerDependencies` cannot be promoted by this list: listing it here is a silent no-op. Two live cases: `find-file-up` (imported by the config loader, devDependency only), and the better-auth trio (declared as peerDependencies AND mirrored into devDependencies upstream; the mirror is what makes the promotion fire, so this list is the fallback if the starter ever stops declaring them itself).",
+  "runtimeHelpers": ["@better-auth/core", "@better-auth/passkey", "better-auth", "find-file-up"]
 }

package/build/extensions/server.js

@@ -951,6 +951,7 @@ class Server {
      */
     convertCloneToVendored(options) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
             const { dest, upstreamBranch, upstreamRepoUrl = 'https://github.com/lenneTech/nest-server.git' } = options;
             const filesystem = this.filesystem;
             const { system } = this.toolbox;
@@ -995,16 +996,22 @@ class Server {
             // transitive deps into the project's package.json (step 5 below).
             let upstreamDeps = {};
             let upstreamDevDeps = {};
+            let upstreamPeerDeps = {};
             let upstreamVersion = '';
             try {
                 const upstreamPkg = filesystem.read(`${tmpClone}/package.json`, 'json');
                 if (upstreamPkg && typeof upstreamPkg === 'object') {
                     upstreamDeps = upstreamPkg.dependencies || {};
                     upstreamDevDeps = upstreamPkg.devDependencies || {};
+                    // Read for the version RANGE only, never as a source of packages: the
+                    // promotion below still keys off devDependencies. A peer range is the
+                    // spec upstream actually supports, whereas the devDep entry beside it is
+                    // an exact pin that exists for the framework's own CI.
+                    upstreamPeerDeps = upstreamPkg.peerDependencies || {};
                     upstreamVersion = upstreamPkg.version || '';
                 }
             }
-            catch (_a) {
+            catch (_b) {
                 // Best-effort — if we can't read upstream pkg, the starter's own
                 // deps should still cover most of the framework's needs.
             }
@@ -1018,7 +1025,7 @@ class Server {
             try {
                 upstreamLockRaw = filesystem.read(`${tmpClone}/pnpm-lock.yaml`) || '';
             }
-            catch (_b) {
+            catch (_c) {
                 // Best-effort — without the lockfile, the closure step falls back to
                 // the upstream package.json ranges (still better than nothing).
             }
@@ -1034,7 +1041,7 @@ class Server {
             try {
                 upstreamWorkspaceYaml = filesystem.read(`${tmpClone}/pnpm-workspace.yaml`) || '';
             }
-            catch (_c) {
+            catch (_d) {
                 // Best-effort: an older framework revision may predate the file. The project
                 // then keeps exactly the allowlist its own template shipped.
             }
@@ -1050,7 +1057,7 @@ class Server {
                     upstreamClaudeMd = claudeMdContent;
                 }
             }
-            catch (_d) {
+            catch (_e) {
                 // Non-fatal — if missing, the project CLAUDE.md just won't get upstream sections.
             }
             // Snapshot the upstream commit SHA for traceability in VENDOR.md.
@@ -1059,7 +1066,7 @@ class Server {
                 const sha = yield system.run(`git -C ${tmpClone} rev-parse HEAD`);
                 upstreamCommit = (sha || '').trim();
             }
-            catch (_e) {
+            catch (_f) {
                 // Non-fatal — VENDOR.md will just show an empty SHA.
             }
             try {
@@ -1342,7 +1349,7 @@ class Server {
                             }
                         }
                     }
-                    catch (_f) {
+                    catch (_g) {
                         // skip unreadable file
                     }
                 }
@@ -1484,9 +1491,13 @@ class Server {
                         pkg.devDependencies = {};
                     const devDeps = pkg.devDependencies;
                     for (const [depName, depVersion] of Object.entries(upstreamDevDeps)) {
-                        // Runtime-needed devDeps → promote to dependencies
+                        // Runtime-needed devDeps → promote to dependencies. Prefer the peer
+                        // RANGE when upstream declares one: the devDep entry beside it is an
+                        // exact pin for the framework's own CI, and baking that into a
+                        // generated project means `pnpm update` never delivers a patch-level
+                        // fix — the wrong default for an auth library like better-auth.
                         if (this.isVendorRuntimeDep(depName) && !(depName in deps)) {
-                            deps[depName] = depVersion;
+                            deps[depName] = (_a = upstreamPeerDeps[depName]) !== null && _a !== void 0 ? _a : depVersion;
                             continue;
                         }
                         // @types/<pkg> where <pkg> is a runtime dep → accept as devDep

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

@@ -1,24 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.healCheckWrapper = healCheckWrapper;
+exports.resolveCopySet = resolveCopySet;
 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. */
 const WRAPPER = 'node scripts/check.mjs';
+/** Where the wrapper and its imports live inside a project. */
+const SCRIPTS_DIR = 'scripts';
 /**
- * Idempotently install the report-driven `check.mjs` wrapper into a project.
+ * Idempotently install the report-driven check wrapper — and every module it
+ * imports — into a project.
  *
- * Copies the bundled canonical wrapper to `<root>/scripts/check.mjs` and rewrites
- * the root `package.json` so that `check` runs the wrapper while the original
- * chain is preserved as `check:raw`. A no-op once already wired (so it is safe to
- * run on every `lt fullstack update`).
+ * Copies the bundled wrapper to `<root>/scripts/check.mjs`, copies its whole
+ * relative-import closure alongside it under the names the wrapper imports them
+ * by, and rewrites the root `package.json` so that `check` runs the wrapper
+ * while the original chain is preserved as `check:raw`. A no-op once already
+ * wired (so it is safe to run on every `lt fullstack update`).
  *
  * `lt fullstack init` already ships the wrapper via the template clone; this is
  * the MIGRATION path that brings it into pre-existing projects.
  *
+ * The copy set moves ATOMICALLY: if any member must be skipped, none are
+ * written. A partial update would leave `check.mjs` and a sibling on different
+ * versions, and the project's `check` then dies on an import mismatch before
+ * running a single step.
+ *
  * @param projectRoot Absolute path to the (workspace) project root.
- * @param assetPath   Absolute path to the bundled canonical `check.mjs`.
+ * @param assetPath   Absolute path to the bundled wrapper. Its DIRECTORY is
+ *                    also probed: every module the wrapper imports relatively
+ *                    (transitively) is shipped from there. The asset always
+ *                    lands as `scripts/check.mjs` regardless of its own name.
  * @returns The list of changed file paths (relative to `projectRoot`); empty when nothing changed.
  */
 function healCheckWrapper(projectRoot, assetPath) {
@@ -39,22 +52,35 @@ function healCheckWrapper(projectRoot, assetPath) {
     if (!scripts || typeof scripts.check !== 'string') {
         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) {
-        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');
+    // 1. Ensure the wrapper — and everything it imports — exists in the project
+    // and matches the canonical version.
+    //
+    // The set is derived from the wrapper's own import statements rather than a
+    // hard-coded name: the wrapper grew a sibling (`build-test-gate.mjs`, which
+    // serialises the CPU-heavy build against the API e2e suite), and copying only
+    // `check.mjs` installs a file whose very first import resolves to nothing —
+    // the project's `check` then dies with ERR_MODULE_NOT_FOUND before running a
+    // single step. Deriving it from the imports (not from "every .mjs in the
+    // directory") keeps the next sibling free of changes here while making sure a
+    // stray file in the asset dir never claims a path in the project's scripts/.
+    const copies = resolveCopySet(assetPath);
+    // Decide EVERY member before writing ANY of them — see the atomicity note in
+    // the doc block above.
+    const plans = copies.map((copy) => planCopy(projectRoot, copy));
+    const blocked = plans.filter((p) => p.action === 'skip');
+    if (blocked.length > 0) {
+        // One entry for the whole set: the set is what could not be updated, and
+        // naming only the blocking member would suggest the others did land.
+        const names = blocked.map((p) => p.rel).join(', ');
+        changed.push(`${copies.map((c) => c.rel).join(' + ')} (skipped: uncommitted changes in ${names} — commit or discard them, then re-run)`);
+    }
+    else {
+        for (const plan of plans) {
+            if (plan.action === 'up-to-date') {
+                continue;
+            }
+            writeCopy(projectRoot, plan);
+            changed.push(plan.rel);
         }
     }
     // 2. Wire package.json: `check` runs the wrapper; the original chain becomes `check:raw`.
@@ -69,11 +95,57 @@ 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.
+ * The wrapper plus the transitive closure of its relative imports.
+ *
+ * Matches both quote styles: the bundled `.mjs` files are formatted by the
+ * consuming project's formatter, not by this repo's, so their quote style is
+ * not ours to assume.
+ */
+function resolveCopySet(assetPath) {
+    const assetDir = (0, path_1.dirname)(assetPath);
+    // Regular files only — a directory named `*.mjs` would otherwise reach
+    // copyFileSync and abort the whole migration with EISDIR.
+    const available = new Set((0, fs_1.readdirSync)(assetDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => entry.name));
+    const copies = [{ rel: `${SCRIPTS_DIR}/check.mjs`, source: assetPath }];
+    // Keyed by target rel, NOT by source basename: the asset lands as
+    // `scripts/check.mjs` whatever it is called, so a `check.mjs` sitting beside a
+    // differently-named asset must not claim that same path a second time.
+    const claimed = new Set(copies.map((c) => c.rel));
+    const queue = [assetPath];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const file = queue.shift();
+        if (visited.has(file)) {
+            continue;
+        }
+        visited.add(file);
+        let source;
+        try {
+            source = (0, fs_1.readFileSync)(file, 'utf8');
+        }
+        catch (_a) {
+            continue;
+        }
+        for (const match of source.matchAll(/\bfrom\s+['"]\.\/([^'"/]+)['"]/g)) {
+            const name = match[1];
+            const rel = `${SCRIPTS_DIR}/${name}`;
+            if (claimed.has(rel) || !available.has(name)) {
+                continue;
+            }
+            claimed.add(rel);
+            const resolved = (0, path_1.join)(assetDir, name);
+            copies.push({ rel, source: resolved });
+            queue.push(resolved);
+        }
+    }
+    return copies;
+}
+/**
+ * True when the TRACKED `relPath` has uncommitted modifications. Overwriting
+ * such a file would destroy work that exists nowhere else. Only meaningful for
+ * a tracked path — see `isTracked`.
  */
 function hasUncommittedChanges(projectRoot, relPath) {
     try {
@@ -87,3 +159,93 @@ function hasUncommittedChanges(projectRoot, relPath) {
         return false;
     }
 }
+/** True when `target` is a symlink (checked without following it). */
+function isSymlink(target) {
+    try {
+        return (0, fs_1.lstatSync)(target).isSymbolicLink();
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * True when git tracks `relPath`, i.e. it holds a recoverable copy.
+ *
+ * An empty `git status --porcelain` alone does NOT establish that: it is also
+ * empty for an ignored file, and for a path in a directory git knows nothing
+ * about. Those are precisely the cases where an overwrite is unrecoverable.
+ */
+function isTracked(projectRoot, relPath) {
+    try {
+        (0, child_process_1.execFileSync)('git', ['-C', projectRoot, 'ls-files', '--error-unmatch', '--', relPath], {
+            stdio: 'ignore',
+        });
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/** Decide what should happen to one copy target, without touching the disk. */
+function planCopy(projectRoot, copy) {
+    const target = (0, path_1.join)(projectRoot, copy.rel);
+    const plan = Object.assign(Object.assign({}, copy), { action: 'write', backup: false });
+    if (!(0, fs_1.existsSync)(target)) {
+        return plan;
+    }
+    // A symlink here resolves OUTSIDE the project, and git reports the (unchanged)
+    // link blob as clean, so the guard below cannot see it. Writing would silently
+    // modify a file somewhere else entirely.
+    if (isSymlink(target)) {
+        plan.action = 'skip';
+        return plan;
+    }
+    if ((0, fs_1.readFileSync)(target, 'utf8') === (0, fs_1.readFileSync)(copy.source, 'utf8')) {
+        plan.action = 'up-to-date';
+        return plan;
+    }
+    // A TRACKED file whose working copy diverges carries edits that exist nowhere
+    // else — never overwrite it. A tracked-and-clean file is safe to replace
+    // (git can restore it). Anything git does not track is not recoverable at
+    // all, so it gets a `.bak` instead of a refusal: refusing would be the worse
+    // outcome, because the wrapper's OWN previous output is untracked until the
+    // user commits it, and a refusal there permanently blocks the update.
+    if (isTracked(projectRoot, copy.rel)) {
+        if (hasUncommittedChanges(projectRoot, copy.rel)) {
+            plan.action = 'skip';
+        }
+        return plan;
+    }
+    plan.backup = true;
+    return plan;
+}
+/** Write one planned copy, backing up an unversioned target first. */
+function writeCopy(projectRoot, plan) {
+    const target = (0, path_1.join)(projectRoot, plan.rel);
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(target), { recursive: true });
+    if (plan.backup && (0, fs_1.existsSync)(target)) {
+        const backup = `${target}.bak`;
+        // Keep the FIRST backup — a later run must not overwrite the original with
+        // an already-generated copy.
+        if (!(0, fs_1.existsSync)(backup)) {
+            (0, fs_1.copyFileSync)(target, backup);
+        }
+    }
+    // temp + rename so an interrupted run can never leave a half-written wrapper.
+    const tmp = `${target}.lt-tmp-${process.pid}`;
+    try {
+        (0, fs_1.copyFileSync)(plan.source, tmp);
+        (0, fs_1.renameSync)(tmp, target);
+    }
+    catch (error) {
+        try {
+            if ((0, fs_1.existsSync)(tmp)) {
+                (0, fs_1.unlinkSync)(tmp);
+            }
+        }
+        catch (_a) {
+            /* best effort */
+        }
+        throw error;
+    }
+}