@lenne.tech/cli 1.48.0 → 1.49.0

package/build/lib/cross-env.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENV_PREFIX = exports.CROSS_ENV_PACKAGE = exports.CROSS_ENV_VERSION = void 0;
+exports.bareEnvPrefixes = bareEnvPrefixes;
+exports.ensureCrossEnvDependency = ensureCrossEnvDependency;
+exports.usesPosixEnvPrefix = usesPosixEnvPrefix;
+exports.withCrossEnv = withCrossEnv;
+/**
+ * Environment prefixes in GENERATED package.json scripts.
+ *
+ * npm and pnpm run scripts through cmd.exe on Windows, which knows no
+ * `VAR=value command` form: it reads `NODE_ENV` as the program name and aborts
+ * with "'NODE_ENV' is not recognized as an internal or external command"
+ * (reported from a Windows laptop, 2026-09-16, on a project generated by lt
+ * 1.47.0: `pnpm run start:local` died there).
+ *
+ * `cross-env` sets the variable in the child process instead, so the same script
+ * works in bash, zsh, PowerShell and cmd.exe.
+ */
+/** Pinned exactly: an override target or dependency of ours is never a range (repo rule). */
+exports.CROSS_ENV_VERSION = '10.1.0';
+exports.CROSS_ENV_PACKAGE = 'cross-env';
+/**
+ * A POSIX env assignment in front of a command — the form cmd.exe cannot run.
+ *
+ * Deliberately NOT anchored to the start of the script: the mistake that actually
+ * happens when converting is an `&&` chain in which only the first link was
+ * wrapped (`cross-env NODE_ENV=x a && NODE_ENV=x b`), and an anchored expression
+ * reports that as clean.
+ */
+exports.ENV_PREFIX = /(^|[\s;&|(])[A-Z_][A-Z0-9_]*=\S/;
+/** `cross-env` plus the assignments it carries — those are the covered ones. */
+const CROSS_ENV_ASSIGNMENTS = /cross-env\s+(?:[A-Z_][A-Z0-9_]*=\S+\s+)+/g;
+/**
+ * Bare `VAR=value` prefixes in `script`, i.e. the ones cmd.exe would choke on.
+ * Assignments that `cross-env` carries are removed first, so a correctly
+ * converted script — including `cross-env A=1 B=2 cmd` — reports nothing.
+ */
+function bareEnvPrefixes(script) {
+    const rest = script.replace(CROSS_ENV_ASSIGNMENTS, '');
+    const found = [];
+    for (const match of rest.matchAll(/(?:^|[\s;&|(])([A-Z_][A-Z0-9_]*=\S+)/g)) {
+        found.push(match[1]);
+    }
+    return found;
+}
+/**
+ * Make sure a generated project can run the scripts we just wrote.
+ *
+ * Lands in `dependencies`, NOT `devDependencies`: production trees are installed
+ * without dev packages — the starter's Dockerfile uses
+ * `pnpm install --frozen-lockfile --prod` and `pnpm deploy --prod` — and the scripts
+ * run there (`start:prod`, `dp:prod` → `migrate:prod:up`) are exactly the env-carrying
+ * ones. Measured by the starter session on two real `--prod` installs from one
+ * lockfile: as a devDependency `node_modules/.bin/cross-env` is missing, as a
+ * dependency it is there. (The framework repos keep it in devDependencies: their
+ * scripts never reach a customer image, and nest-server is published to npm, where a
+ * production dependency would be forced on every consumer.)
+ *
+ * Only added when the project does not declare it anywhere already — the starters ship
+ * it themselves, and a second entry would fight theirs on every update. An existing
+ * entry keeps its group and version, devDependencies included.
+ *
+ * @param pkg Parsed package.json of the generated project; mutated in place.
+ * @returns true when the dependency was added.
+ */
+function ensureCrossEnvDependency(pkg) {
+    const declared = [pkg.dependencies, pkg.devDependencies, pkg.peerDependencies, pkg.optionalDependencies].some((group) => group && typeof group === 'object' && exports.CROSS_ENV_PACKAGE in group);
+    if (declared) {
+        return false;
+    }
+    if (!pkg.dependencies || typeof pkg.dependencies !== 'object') {
+        pkg.dependencies = {};
+    }
+    pkg.dependencies[exports.CROSS_ENV_PACKAGE] = exports.CROSS_ENV_VERSION;
+    pkg.dependencies = Object.fromEntries(Object.entries(pkg.dependencies).sort(([a], [b]) => a.localeCompare(b)));
+    return true;
+}
+/** True when `script` still carries a bare `VAR=value` prefix. */
+function usesPosixEnvPrefix(script) {
+    return bareEnvPrefixes(script).length > 0;
+}
+/**
+ * Prefix a command with `cross-env VAR=value …`.
+ *
+ * @param env     Variables to set, e.g. `{ NODE_ENV: 'production' }`.
+ * @param command The command to run.
+ */
+function withCrossEnv(env, command) {
+    const assignments = Object.entries(env)
+        .map(([name, value]) => `${name}=${value}`)
+        .join(' ');
+    return `cross-env ${assignments} ${command}`;
+}

package/build/lib/dev-api-launch.js

@@ -9,6 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyPendingMigrations = applyPendingMigrations;
 exports.findCompiledEntry = findCompiledEntry;
 exports.isApiCompiledRequested = isApiCompiledRequested;
 exports.resolveApiRuntime = resolveApiRuntime;
@@ -29,6 +30,33 @@ const node_path_1 = require("node:path");
 const dev_process_1 = require("./dev-process");
 /** Candidate compiled entry points, in preference order. Single-sourced so `lt dev test` agrees. */
 const COMPILED_ENTRIES = ['dist/src/main.js', 'dist/main.js'];
+/**
+ * Apply the project's pending migrations (`<pm> run migrate:up`) ahead of an API
+ * that is started WITHOUT its own `start` script.
+ *
+ * lt projects chain the migration into that script (`migrate:up && start:local`),
+ * so every path that starts the compiled bundle directly — `lt dev up
+ * --api-compiled` and `lt dev test` — drops the migration along with it. On a
+ * database that outlives the run, that leaves the API on a state no deployed
+ * environment has: a changed unique index never reached the `lt dev test` DB, and
+ * the suite failed with a 409 that looked like a bug in the feature (DEV-3289).
+ *
+ * `env` must be the environment the API itself gets. The migration store resolves
+ * its database from the same `config.env.ts` + `NSC__MONGOOSE__URI` merge, so
+ * sharing the env is what makes both reach the same database.
+ *
+ * A project without a `migrate:up` script is `skipped`, never an error — nest-base
+ * (Prisma) projects have none. A migration killed by a signal (`null`) is `failed`.
+ */
+function applyPendingMigrations(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { apiDir, env, pm } = options;
+        if (!hasScript(apiDir, 'migrate:up'))
+            return { status: 'skipped' };
+        const exitCode = yield (0, dev_process_1.runChildInherit)(pm.bin, pm.runScript('migrate:up'), { cwd: apiDir, env });
+        return exitCode === 0 ? { status: 'applied' } : { exitCode, status: 'failed' };
+    });
+}
 /** Resolve the compiled API entry point in `apiDir`, or `undefined` if none was built. */
 function findCompiledEntry(apiDir) {
     return COMPILED_ENTRIES.map((rel) => (0, node_path_1.join)(apiDir, rel)).find((candidate) => (0, node_fs_1.existsSync)(candidate));
@@ -106,14 +134,12 @@ function startCompiledApi(options) {
         const build = yield (0, dev_process_1.runChildInherit)(pm.bin, pm.runScript('build'), { cwd: apiDir, env });
         const entry = findCompiledEntry(apiDir);
         if (build === 0 && entry) {
-            if (hasScript(apiDir, 'migrate:up')) {
-                const migrate = yield (0, dev_process_1.runChildInherit)(pm.bin, pm.runScript('migrate:up'), { cwd: apiDir, env });
-                if (migrate !== 0) {
-                    // Parity with `migrate:up && start:local`: a failed migration must PREVENT the server
-                    // from starting rather than boot it against a half-migrated DB behind a "Started" banner.
-                    log.warn(`migrate:up failed (exit ${String(migrate)}) — API NOT started (would run on an un-migrated DB).`);
-                    return undefined;
-                }
+            const migration = yield applyPendingMigrations({ apiDir, env, pm });
+            if (migration.status === 'failed') {
+                // Parity with `migrate:up && start:local`: a failed migration must PREVENT the server
+                // from starting rather than boot it against a half-migrated DB behind a "Started" banner.
+                log.warn(`migrate:up failed (exit ${String(migration.exitCode)}) — API NOT started (would run on an un-migrated DB).`);
+                return undefined;
             }
             return (0, dev_process_1.spawnDetached)(resolveApiRuntime(apiDir), [entry], {
                 cwd: apiDir,

package/build/lib/dev-package-manager.js

@@ -74,16 +74,20 @@ function buildCommand(bin, name) {
         },
     };
 }
+/**
+ * Manager behind an override like `LT_PM_BIN`.
+ *
+ * Reads the file NAME, split on both separators and stripped of a Windows launcher
+ * extension: there the binary is `C:\\…\\pnpm.cmd`, which neither `endsWith('pnpm')`
+ * nor `includes('/pnpm')` matched — the override then resolved to `unknown` and the
+ * caller drove the wrong manager.
+ */
 function inferNameFromBin(bin) {
-    const lower = bin.toLowerCase();
-    if (lower.endsWith('pnpm') || lower.includes('/pnpm')) {
-        return 'pnpm';
-    }
-    if (lower.endsWith('yarn') || lower.includes('/yarn')) {
-        return 'yarn';
-    }
-    if (lower.endsWith('npm') || lower.includes('/npm')) {
-        return 'npm';
+    var _a;
+    const file = (_a = bin.toLowerCase().split(/[\\/]/).pop()) !== null && _a !== void 0 ? _a : '';
+    const name = file.replace(/\.(bat|cmd|exe|ps1)$/, '');
+    if (name === 'pnpm' || name === 'yarn' || name === 'npm') {
+        return name;
     }
     return 'unknown';
 }

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

@@ -17,9 +17,11 @@ exports.buildShardPlaywrightInvocation = buildShardPlaywrightInvocation;
 exports.buildTestAppEnv = buildTestAppEnv;
 exports.hasTestSession = hasTestSession;
 exports.isStackServing = isStackServing;
+exports.migrationFailedError = migrationFailedError;
 exports.resolveTestSession = resolveTestSession;
 exports.runShardedTestSession = runShardedTestSession;
 exports.shardReportDir = shardReportDir;
+exports.startTestApi = startTestApi;
 exports.tearDownAllTestSessions = tearDownAllTestSessions;
 exports.tearDownTestSession = tearDownTestSession;
 exports.testAppEntryCandidates = testAppEntryCandidates;
@@ -30,8 +32,10 @@ exports.unreachableStackError = unreachableStackError;
  * 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.
+ * against a dedicated database so a developer can keep working in their own
+ * environment while tests run, and so a test run never pollutes dev data. That
+ * database outlives the run — the CLI never drops it — so the API is migrated
+ * before it starts, like every other environment (DEV-3289).
  *
  * Topology (for slug `svl`):
  *   - dev session  : svl.localhost / api.svl.localhost   → db `<…>-local`
@@ -99,12 +103,13 @@ const TEST_PORT_BASE = 4500;
  * `systemSetup.initialAdmin.*` and seeds the admin ONCE on an empty DB (it never
  * overwrites an existing admin), so a set-up system exists before the suite runs.
  * A fresh template project's standard auth E2E specs assume such a system — they
- * do no self-setup — so without this they fail LOCALLY on the empty per-run DB.
+ * do no self-setup — so without this they fail LOCALLY on a test DB that has no
+ * users yet (its first run, or after a global-setup reset it).
  * These are the exact values the lt-monorepo template CI uses
  * (`.gitlab-ci.yml` / `.github/workflows/test.yml`), keeping CI ↔ local parity.
  *
- * Injected ONLY into the `lt dev test` API process (its DB is fresh + discarded
- * per run), NEVER into `lt dev up` — no surprise admin in the persistent dev DB.
+ * Injected ONLY into the `lt dev test` API process (its DB is the dedicated
+ * `<…>-test` one), NEVER into `lt dev up` — no surprise admin in the dev DB.
  */
 exports.TEST_INITIAL_ADMIN_ENV = {
     NSC__SYSTEM_SETUP__INITIAL_ADMIN__EMAIL: 'ci-admin@test.com',
@@ -276,7 +281,11 @@ function bringUpTestSession(layout_1, baseIdentity_1, log_1) {
             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)`);
+        // No claim about resetting here: the CLI never drops this DB, and whether a
+        // project's global-setup does is the project's business. The claim used to be
+        // printed unconditionally and sent a diagnosis looking for a reset that never
+        // happened instead of at the un-migrated DB (DEV-3289).
+        log.info(`  db:  mongodb://127.0.0.1/${dbName}`);
         log.info('');
         const devEnv = (0, dev_env_1.buildDevEnv)({
             apiInternalPort: apiPort !== null && apiPort !== void 0 ? apiPort : 0,
@@ -294,43 +303,23 @@ function bringUpTestSession(layout_1, baseIdentity_1, log_1) {
         // hands it to the Playwright child as well.
         const appEnv = buildTestAppEnv(devEnv.app.env);
         const pids = {};
-        // --- API: compiled (`node dist`) for stability; fall back to the project's
-        // own dev start script. `skipBuild` (sibling shards) reuses the dist the
-        // first shard produced. Per-component PM detection mirrors `lt dev up`:
-        // a monorepo with an npm api and a pnpm app must drive each correctly. ---
+        // --- API: compiled (`node dist`) for stability, migrated first; falls back to
+        // the project's own start script (see `startTestApi`). ---
         if (layout.apiDir && apiPort) {
-            const apiPm = (0, dev_package_manager_1.pickPackageManager)(layout.apiDir);
-            let build = 0;
-            if (!skipBuild) {
-                log.info(log.dim('Building API (compiled, for stable long runs) …'));
-                build = yield (0, dev_process_1.runChildInherit)(apiPm.bin, apiPm.runScript('build'), { cwd: layout.apiDir, env: process.env });
-            }
-            const entry = (0, dev_api_launch_1.findCompiledEntry)(layout.apiDir);
-            // Seed a throwaway initial admin into the fresh, isolated test DB so the
-            // standard auth E2E specs run against a set-up system — locally exactly like
-            // the lt-monorepo template CI. Defaults first so an explicitly inherited
+            // Seed a throwaway initial admin into the isolated test DB so the standard
+            // auth E2E specs run against a set-up system — locally exactly like the
+            // lt-monorepo template CI. Defaults first so an explicitly inherited
             // `NSC__…INITIAL_ADMIN__…` still wins (deliberate override respected). Only
             // reached from `lt dev test` — `lt dev up` never calls bringUpTestSession.
             const apiEnv = Object.assign(Object.assign(Object.assign({}, exports.TEST_INITIAL_ADMIN_ENV), devEnv.api.env), { NODE_ENV: 'local' });
-            let apiSpawn;
-            if (build === 0 && entry) {
-                // Runtime follows the PROJECT, never a hardcoded default: a `nest-base` API
-                // bundles with `Bun.build({ target: 'bun' })` and dies under node with
-                // "__require is not a function" (DEV-3208).
-                apiSpawn = (0, dev_process_1.spawnDetached)((0, dev_api_launch_1.resolveApiRuntime)(layout.apiDir), [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 \`${apiPm.bin} start\` (ts-node).`);
-                apiSpawn = (0, dev_process_1.spawnDetached)(apiPm.bin, apiPm.runScript('start'), {
-                    cwd: layout.apiDir,
-                    env: apiEnv,
-                    logFile: (0, path_1.join)(layout.root, '.lt-dev', names.apiLog),
-                });
-            }
+            const apiSpawn = yield startTestApi({
+                apiDir: layout.apiDir,
+                apiEnv,
+                dbName,
+                log,
+                logFile: (0, path_1.join)(layout.root, '.lt-dev', names.apiLog),
+                skipBuild,
+            });
             if (apiSpawn)
                 pids.api = apiSpawn.pid;
         }
@@ -515,6 +504,19 @@ function hasTestSession(root) {
 function isStackServing(status) {
     return status > 0 && ![502, 503, 504].includes(status);
 }
+/**
+ * The abort thrown when the test DB cannot be migrated.
+ *
+ * An abort rather than a warning for the same reason as `unreachableStackError`:
+ * a suite run on an un-migrated DB tests a data state no environment has, and
+ * whatever it reports is about the test setup, not about the feature. Unlike the
+ * API's boot, `migrate:up` runs in the foreground, so its output is already on
+ * screen right above this message.
+ */
+function migrationFailedError(dbName, exitCode) {
+    return new Error(`migrate:up failed (exit ${String(exitCode)}) against the test DB "${dbName}" — test API not started, ` +
+        'because a suite on an un-migrated DB tests a state no environment has. The migration output is above.');
+}
 /** Build the dedicated test identity + test DB name for a project. */
 function resolveTestSession(layout, baseIdentity, shardIndex, devDbName) {
     const names = testStackNames(shardIndex);
@@ -599,6 +601,50 @@ function runShardedTestSession(layout, baseIdentity, log, opts) {
 function shardReportDir(root, shardIndex) {
     return (0, path_1.join)(root, '.lt-dev', `shard.${shardIndex}.playwright-report`);
 }
+/**
+ * Start the test stack's API: build → apply pending migrations → start the
+ * compiled bundle, or fall back to the project's own `start` script when no
+ * bundle is available.
+ *
+ * The compiled start bypasses that `start` script and therefore the
+ * `migrate:up` it chains in front of the server. The test DB outlives every
+ * run — the CLI never drops it — so without the explicit step here it drifted
+ * behind every environment that does migrate (DEV-3289). The migration runs
+ * with `apiEnv`, the API's own env, so both resolve the same database, and
+ * before the spawn, because the API syncs its indexes against whatever it finds
+ * on boot. A failed migration throws `migrationFailedError`.
+ *
+ * `skipBuild` (sibling shards) reuses the dist the first shard produced but
+ * still migrates: every shard has a database of its own. The fallback does not
+ * migrate itself — the `start` script it runs owns that, exactly as under
+ * `lt dev up`. Per-directory package manager, like `lt dev up`: a monorepo with
+ * an npm API and a pnpm App must drive each with its own.
+ */
+function startTestApi(opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { apiDir, apiEnv, dbName, log, logFile, skipBuild } = opts;
+        const apiPm = (0, dev_package_manager_1.pickPackageManager)(apiDir);
+        let build = 0;
+        if (!skipBuild) {
+            log.info(log.dim('Building API (compiled, for stable long runs) …'));
+            build = yield (0, dev_process_1.runChildInherit)(apiPm.bin, apiPm.runScript('build'), { cwd: apiDir, env: process.env });
+        }
+        const entry = (0, dev_api_launch_1.findCompiledEntry)(apiDir);
+        if (build === 0 && entry) {
+            const migration = yield (0, dev_api_launch_1.applyPendingMigrations)({ apiDir, env: apiEnv, pm: apiPm });
+            if (migration.status === 'failed')
+                throw migrationFailedError(dbName, migration.exitCode);
+            if (migration.status === 'skipped')
+                log.info(log.dim(`no migrate:up script — ${dbName} is not migrated`));
+            // Runtime follows the PROJECT, never a hardcoded default: a `nest-base` API
+            // bundles with `Bun.build({ target: 'bun' })` and dies under node with
+            // "__require is not a function" (DEV-3208).
+            return (0, dev_process_1.spawnDetached)((0, dev_api_launch_1.resolveApiRuntime)(apiDir), [entry], { cwd: apiDir, env: apiEnv, logFile });
+        }
+        log.warn(`compiled API not available — falling back to \`${apiPm.bin} start\` (ts-node).`);
+        return (0, dev_process_1.spawnDetached)(apiPm.bin, apiPm.runScript('start'), { cwd: apiDir, env: apiEnv, logFile });
+    });
+}
 /**
  * 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

package/build/lib/fail-run.js

@@ -20,6 +20,17 @@ exports.failRun = failRun;
  * buffered output, including the spinner's own failure message, which is the one
  * line the operator actually needs.
  *
+ * That choice carries a precondition worth stating, because it was violated:
+ * setting `process.exitCode` only ends the process once **the event loop drains**,
+ * and `bin/lt` has no terminal `process.exit()` after `run()`. A running ora
+ * spinner holds the loop open on two counts — its `setInterval` for the animation
+ * and the `stdin.resume()` its stdin discarder performs. So a command that called
+ * `failRun` and returned while a spinner was still spinning did not exit at all:
+ * no message, no prompt back, and the terminal left in raw mode. The remedy is to
+ * stop the spinner, NOT to switch this helper to `process.exit()` — that would
+ * trade a hang for the truncated-output bug this helper exists to avoid.
+ * `__tests__/spinner-lifetime.test.ts` enforces the spinner half.
+ *
  * **Guarded by `fromGluegunMenu`**, like the CLI's other exit-code call sites
  * (`dev test`, `dev tunnel`, `tools ocr`, `workspace-integration`): inside the
  * interactive `lt` menu a command is one step of a longer session, and failing

package/build/lib/heal-vendor-migrate-store.js

@@ -90,9 +90,10 @@ const ts = __importStar(require("typescript"));
  * Detection runs on the TypeScript AST, not on regex-stripped text. A regex
  * "lexer" has no string/template/regex-literal state, so a `/*` or `//` inside a
  * literal earlier in the file silently erased the guard and triggered the very
- * overwrite this function must avoid. `lib/strip-comments.ts` solves the comment
- * half properly (TS scanner) and would have been the right reuse; the AST solves
- * comments AND nesting in one step, and recognises a backtick require for free.
+ * overwrite this function must avoid. Scanning is not enough either: a standalone
+ * `ts.createScanner` loop desynchronises on the first interpolating template
+ * literal (that is what retired `lib/strip-comments.ts`). The AST solves comments
+ * AND nesting in one step, and recognises a backtick require for free.
  *
  * ## Recoverability
  *

package/build/lib/migrate-scripts.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILD_GUARD_FILE = exports.COMPILED_MIGRATE_ARGS = exports.MIGRATE_ENVIRONMENTS = void 0;
+exports.deployedMigrateScripts = deployedMigrateScripts;
+exports.missingBuildGuardWarning = missingBuildGuardWarning;
+const path_1 = require("path");
+const cross_env_1 = require("./cross-env");
+/** Script suffix → `NODE_ENV` value. `prod` maps to `production`, the name Nest config keys off. */
+exports.MIGRATE_ENVIRONMENTS = [
+    ['develop', 'develop'],
+    ['test', 'test'],
+    ['preview', 'preview'],
+    ['prod', 'production'],
+];
+/** Where the build puts the compiled migrations and the store helper. */
+exports.COMPILED_MIGRATE_ARGS = '--store ./dist/migrations-utils/migrate.js --migrations-dir ./dist/migrations';
+/**
+ * Build guard in front of every deployed script — the same wiring nest-server-starter
+ * uses (`node scripts/… && <migrate>`), so the chain fails BEFORE migrate starts and
+ * `dp:prod` never reaches the server start.
+ *
+ * It is needed because the failure is otherwise SILENT: measured with nest-server
+ * 11.41.2, a missing migrations directory prints "treating as empty" and a missing or
+ * empty one both end in "No pending migrations", exit 0. An unbuilt checkout would
+ * report a successful migration run that never happened, and the server would then come
+ * up against an unmigrated database.
+ */
+exports.BUILD_GUARD_FILE = 'require-built-migrations.mjs';
+const BUILD_GUARD = `node scripts/${exports.BUILD_GUARD_FILE} && `;
+/**
+ * Build the four deployed migrate scripts.
+ *
+ * @param invocation How this project starts the migrate CLI: `'migrate'` in npm mode
+ *                   (the binary of `@lenne.tech/nest-server`, a production dependency),
+ *                   `'node ./dist/bin/migrate.js'` in vendor mode (the shim `copy:bin`
+ *                   ships into `dist/`).
+ */
+function deployedMigrateScripts(invocation) {
+    const scripts = {};
+    for (const [scriptEnv, nodeEnv] of exports.MIGRATE_ENVIRONMENTS) {
+        scripts[`migrate:${scriptEnv}:up`] =
+            BUILD_GUARD + (0, cross_env_1.withCrossEnv)({ NODE_ENV: nodeEnv }, `${invocation} up ${exports.COMPILED_MIGRATE_ARGS}`);
+    }
+    return scripts;
+}
+/**
+ * Warn when the build guard the deployed scripts call is not in the project.
+ *
+ * The file ships with nest-server-starter, which BOTH modes clone as their base
+ * (`server.ts`: "Both npm and vendor mode clone nest-server-starter as the base"), and
+ * nothing in the conversion prunes `scripts/` wholesale — only
+ * `strip-api-mode-markers.mjs`, `scripts/vendor/` and, in REST mode,
+ * `run-spectaql.mjs`. So the CLI does NOT ship its own copy: a second, nearly identical
+ * file is exactly the drift we are trying to avoid.
+ *
+ * What it does instead is fail loudly if the assumption stops holding — e.g. a project
+ * built from an older starter. Same treatment as `migrations-utils/mongo-uri.js`:
+ * without the file every deployed migrate script dies at the first `&&`.
+ *
+ * @returns A warning message, or null when the guard is present.
+ */
+function missingBuildGuardWarning(filesystem, projectDir) {
+    if (filesystem.exists((0, path_1.join)(projectDir, 'scripts', exports.BUILD_GUARD_FILE))) {
+        return null;
+    }
+    return (`  ⚠ scripts/${exports.BUILD_GUARD_FILE} is missing — the deployed migrate:<env>:up scripts call it ` +
+        'before migrating and would fail immediately. It ships with nest-server-starter; add it ' +
+        '(or update the starter this project was created from).');
+}

package/build/lib/module-specifiers.js

@@ -0,0 +1,144 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileImportedSpecifiers = fileImportedSpecifiers;
+exports.importedSpecifiers = importedSpecifiers;
+exports.isPackageImport = isPackageImport;
+exports.isRelativeCoreImport = isRelativeCoreImport;
+/**
+ * The module specifiers a file imports — read from the syntax tree, never from text.
+ *
+ * The detectors that ask "does this file still import X?" used to search the raw source
+ * and blank out comments first, because a docblock that DOCUMENTS the conversion quotes
+ * the very syntax they look for (`nest-server-starter`'s
+ * `tests/unit/bootstrap-diagnostics.spec.ts` names `from '@lenne.tech/nest-server'` in
+ * prose, and the detector told the user to rewrite imports that file does not have).
+ *
+ * That workaround does not hold. `stripComments` drives a standalone `ts.createScanner`
+ * in a plain `scan()` loop, and a template literal WITH a substitution cannot be read
+ * that way: the scanner hands back `TemplateHead` and needs `reScanTemplateToken()` to
+ * continue. Without it every token after the first `` `x${…}` `` is misread, so comments
+ * from there on pass through verbatim. Bisected on `src/templates/check/check.mjs`: the
+ * first surviving comment appears right after `` `${s.toFixed(1)}s` `` on line 70, and a
+ * two-line fixture reproduces it. A plain template without substitution is fine; regex
+ * literals and division — the first suspects — are not the cause.
+ * Since template literals are everywhere, degradation was present in 23 of 76 real
+ * frontend files and 21 of 50 backend files; only the absence of a needle-quoting
+ * comment BELOW such a template kept it from producing false alarms.
+ *
+ * Asking the parser removes the whole class: a comment is not part of the AST, so there
+ * is nothing to strip and nothing to get wrong.
+ */
+const ts = __importStar(require("typescript"));
+/** `<script>` / `<script setup>` blocks of a Vue SFC, which is not valid TypeScript as a whole. */
+const VUE_SCRIPT_BLOCK = /<script\b[^>]*>([\s\S]*?)<\/script>/gi;
+/**
+ * Same, for a file on disk. A `.vue` SFC is not valid TypeScript, so its `<script>`
+ * blocks are extracted first and parsed individually — the template and style blocks
+ * cannot contain imports and are skipped. Everything else is parsed as-is.
+ *
+ * @returns The specifiers, or `[]` when the file cannot be read.
+ */
+function fileImportedSpecifiers(filePath, read) {
+    const source = read(filePath);
+    if (!source) {
+        return [];
+    }
+    if (!filePath.endsWith('.vue')) {
+        return importedSpecifiers(source, filePath);
+    }
+    const specifiers = [];
+    for (const [, block] of source.matchAll(VUE_SCRIPT_BLOCK)) {
+        specifiers.push(...importedSpecifiers(block, `${filePath}.ts`));
+    }
+    return specifiers;
+}
+/**
+ * Every module specifier `source` imports, exports from, dynamically imports or
+ * requires. Duplicates are preserved; order follows the file.
+ *
+ * Covers `import x from 'y'`, `import 'y'`, `export … from 'y'`, `export * from 'y'`,
+ * `import y = require('y')`, `await import('y')` and `require('y')`.
+ *
+ * @param source The file's text.
+ * @param fileName Only used to pick the parser dialect (`.tsx` vs `.ts`).
+ */
+function importedSpecifiers(source, fileName = 'file.ts') {
+    const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true);
+    const specifiers = [];
+    const literalText = (node) => node && ts.isStringLiteralLike(node) ? node.text : null;
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+            const text = literalText(node.moduleSpecifier);
+            if (text !== null) {
+                specifiers.push(text);
+            }
+        }
+        else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) {
+            const text = literalText(node.moduleReference.expression);
+            if (text !== null) {
+                specifiers.push(text);
+            }
+        }
+        else if (ts.isCallExpression(node)) {
+            const callee = node.expression;
+            const isRequire = ts.isIdentifier(callee) && callee.text === 'require';
+            const isDynamicImport = callee.kind === ts.SyntaxKind.ImportKeyword;
+            if (isRequire || isDynamicImport) {
+                const text = literalText(node.arguments[0]);
+                if (text !== null) {
+                    specifiers.push(text);
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return specifiers;
+}
+/** True when `specifier` is `pkg` itself or a deep import of it (`pkg/sub/path`). */
+function isPackageImport(specifier, pkg) {
+    return specifier === pkg || specifier.startsWith(`${pkg}/`);
+}
+/**
+ * True when `specifier` is a relative path whose last segment is `core`, or that leads
+ * into a `core` directory — `./core`, `../core`, `../../core/utils`.
+ */
+function isRelativeCoreImport(specifier) {
+    if (!specifier.startsWith('.')) {
+        return false;
+    }
+    return specifier.split('/').includes('core');
+}