@lenne.tech/cli 1.11.1 → 1.13.0

package/build/extensions/frontend-helper.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FrontendHelper = void 0;
+const markdown_table_1 = require("../lib/markdown-table");
 /**
  * Frontend helper functions for project scaffolding
  * Provides reusable methods for setting up Nuxt and Angular frontends
@@ -273,9 +274,7 @@ class FrontendHelper {
                     const { print } = this.toolbox;
                     print.warning('');
                     print.warning('VENDOR.md documents local patches in app/core/ that will be LOST:');
-                    const rows = localChangesSection[0]
-                        .split('\n')
-                        .filter((l) => /^\|\s*\d{4}-/.test(l));
+                    const rows = localChangesSection[0].split('\n').filter((l) => /^\|\s*\d{4}-/.test(l));
                     for (const row of rows.slice(0, 5)) {
                         print.info(`  ${row.trim()}`);
                     }
@@ -307,8 +306,7 @@ class FrontendHelper {
                         // Unhook freshness from check/check:fix/check:naf
                         for (const scriptName of ['check', 'check:fix', 'check:naf']) {
                             if ((_a = scripts[scriptName]) === null || _a === void 0 ? void 0 : _a.includes('check:vendor-freshness')) {
-                                scripts[scriptName] = scripts[scriptName]
-                                    .replace(/pnpm run check:vendor-freshness && /g, '');
+                                scripts[scriptName] = scripts[scriptName].replace(/pnpm run check:vendor-freshness && /g, '');
                             }
                         }
                     }
@@ -354,7 +352,7 @@ class FrontendHelper {
      */
     convertAppCloneToVendored(options) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { dest, upstreamBranch, upstreamRepoUrl = 'https://github.com/lenneTech/nuxt-extensions.git', } = options;
+            const { dest, upstreamBranch, upstreamRepoUrl = 'https://github.com/lenneTech/nuxt-extensions.git' } = options;
             const path = require('node:path');
             const { filesystem, system } = this.toolbox;
             const coreDir = path.join(dest, 'app', 'core');
@@ -501,14 +499,14 @@ class FrontendHelper {
                             "var f=require('fs'),h=require('https');",
                             "try{var c=f.readFileSync('app/core/VENDOR.md','utf8')}catch(e){process.exit(0)}",
                             'var m=c.match(/Baseline-Version[^0-9]*(\\d+\\.\\d+\\.\\d+)/);',
-                            'if(!m){process.stderr.write(String.fromCharCode(9888)+\' vendor-freshness: no baseline\\n\');process.exit(0)}',
+                            "if(!m){process.stderr.write(String.fromCharCode(9888)+' vendor-freshness: no baseline\\n');process.exit(0)}",
                             'var v=m[1];',
                             "h.get('https://registry.npmjs.org/@lenne.tech/nuxt-extensions/latest',function(r){",
                             "var d='';r.on('data',function(c){d+=c});r.on('end',function(){",
-                            "try{var l=JSON.parse(d).version;",
+                            'try{var l=JSON.parse(d).version;',
                             "if(v===l)console.log('vendor core up-to-date (v'+v+')');",
                             "else process.stderr.write('vendor core v'+v+', latest v'+l+'\\n')",
-                            '}catch(e){}})}).on(\'error\',function(){});',
+                            "}catch(e){}})}).on('error',function(){});",
                             'setTimeout(function(){process.exit(0)},5000)',
                             '"',
                         ].join('');
@@ -525,7 +523,20 @@ class FrontendHelper {
                         hookFreshness('check:fix');
                         hookFreshness('check:naf');
                     }
-                    filesystem.write(pkgPath, pkg, { jsonIndent: 2 });
+                    // Sort dependency maps alphabetically so merged-in entries
+                    // (e.g. upstream `@nuxt/kit`) end up in the expected position
+                    // and the generated package.json passes oxfmt/format:check.
+                    const sortObjectKeys = (obj) => {
+                        if (!obj)
+                            return obj;
+                        return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
+                    };
+                    pkg.dependencies = sortObjectKeys(pkg.dependencies);
+                    pkg.devDependencies = sortObjectKeys(pkg.devDependencies);
+                    pkg.peerDependencies = sortObjectKeys(pkg.peerDependencies);
+                    // Ensure trailing newline — oxfmt with the starter's .editorconfig
+                    // `insert_final_newline = true` requires it.
+                    filesystem.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
                 }
             }
             // ── 6. CLAUDE.md: prepend vendor marker + merge upstream sections ────
@@ -544,8 +555,8 @@ class FrontendHelper {
                         'project code. There is **no** `@lenne.tech/nuxt-extensions` npm dependency.',
                         '',
                         '- **Read framework code from `app/core/**`** — not from `node_modules/`.',
-                        '- **nuxt.config.ts** references `\'./app/core/module\'` instead of',
-                        '  `\'@lenne.tech/nuxt-extensions\'`.',
+                        "- **nuxt.config.ts** references `'./app/core/module'` instead of",
+                        "  `'@lenne.tech/nuxt-extensions'`.",
                         '- **Baseline + patch log** live in `app/core/VENDOR.md`. Log any',
                         '  substantial local change there so the `nuxt-extensions-core-updater`',
                         '  agent can classify it at sync time.',
@@ -595,13 +606,41 @@ class FrontendHelper {
                     '# @lenne.tech/nuxt-extensions (vendored)',
                     '',
                     'This directory is a curated vendor copy of `@lenne.tech/nuxt-extensions`.',
-                    'It is first-class project code, not a node_modules shadow copy.',
-                    'Edit freely; log substantial changes in the "Local changes" table below',
-                    'so the `nuxt-extensions-core-updater` agent can classify them at sync time.',
+                    'It is first-class project code, not a node_modules shadow copy — but it',
+                    'is **not a fork**. The copy exists so Claude Code (and humans) can read',
+                    'framework internals directly. Log substantial local changes in the',
+                    '"Local changes" table below so the `nuxt-extensions-core-updater` agent',
+                    'can classify them at sync time.',
                     '',
                     'Unlike the backend (nest-server) vendoring, no flatten-fix is needed —',
                     'the nuxt-extensions source structure is already flat.',
                     '',
+                    '## Modification Policy',
+                    '',
+                    'Edit `app/core/` **only** when the change is generally useful to every',
+                    '@lenne.tech/nuxt-extensions consumer:',
+                    '',
+                    '- Bugfixes that apply to every consumer',
+                    '- Broad framework enhancements (new composables, better defaults, SSR fixes)',
+                    '- Security vulnerability fixes',
+                    '- Type/config compatibility fixes every consumer would hit',
+                    '',
+                    'Everything else stays **outside** `app/core/`. Project-specific business',
+                    'rules, customer branding, and proprietary integrations belong in project',
+                    'code (`app/composables/`, `app/components/`, `app/middleware/`, plugin',
+                    'overrides).',
+                    '',
+                    'Generally-useful changes **MUST** be submitted as an upstream PR to',
+                    'https://github.com/lenneTech/nuxt-extensions. Run',
+                    '`/lt-dev:frontend:contribute-nuxt-extensions-core` to prepare it — the',
+                    'agent filters cosmetic commits, categorizes local changes as',
+                    'upstream-candidate vs. project-specific, and writes PR drafts for human',
+                    "review. Letting useful fixes rot in one project's vendor tree is an",
+                    'anti-pattern: they belong upstream so every consumer benefits and the',
+                    'local patch disappears on the next sync.',
+                    '',
+                    'When in doubt, ask before editing `app/core/`.',
+                    '',
                     '## Baseline',
                     '',
                     '- **Upstream-Repo:** https://github.com/lenneTech/nuxt-extensions',
@@ -612,22 +651,15 @@ class FrontendHelper {
                     '',
                     '## Sync history',
                     '',
-                    '| Date | From | To | Notes |',
-                    '| ---- | ---- | -- | ----- |',
-                    `| ${today} | — | ${syncHistoryTo} | scaffolded by lt CLI |`,
+                    ...(0, markdown_table_1.formatMarkdownTable)(['Date', 'From', 'To', 'Notes'], [[today, '—', syncHistoryTo, 'scaffolded by lt CLI']]),
                     '',
                     '## Local changes',
                     '',
-                    '| Date | Commit | Scope | Reason | Status |',
-                    '| ---- | ------ | ----- | ------ | ------ |',
-                    '| — | — | (none, pristine) | initial vendor | — |',
+                    ...(0, markdown_table_1.formatMarkdownTable)(['Date', 'Commit', 'Scope', 'Reason', 'Status'], [['—', '—', '(none, pristine)', 'initial vendor', '—']]),
                     '',
                     '## Upstream PRs',
                     '',
-                    '| PR | Title | Commits | Status |',
-                    '| -- | ----- | ------- | ------ |',
-                    '| — | (none yet) | — | — |',
-                    '',
+                    ...(0, markdown_table_1.formatMarkdownTable)(['PR', 'Title', 'Commits', 'Status'], [['—', '(none yet)', '—', '—']]),
                 ].join('\n'));
             }
             // ── Post-conversion verification ─────────────────────────────────────
@@ -749,9 +781,7 @@ class FrontendHelper {
             if (skipPathContaining && absFile.includes(skipPathContaining))
                 continue;
             const content = filesystem.read(absFile) || '';
-            const matches = typeof needle === 'string'
-                ? content.includes(needle)
-                : needle.test(content);
+            const matches = typeof needle === 'string' ? content.includes(needle) : needle.test(content);
             if (matches) {
                 stale.push(absFile.replace(`${appDir}/`, ''));
             }
@@ -800,10 +830,7 @@ class FrontendHelper {
     walkConsumerFiles(appDir) {
         const fs = require('node:fs');
         const path = require('node:path');
-        const searchDirs = [
-            path.join(appDir, 'app'),
-            path.join(appDir, 'tests'),
-        ];
+        const searchDirs = [path.join(appDir, 'app'), path.join(appDir, 'tests')];
         const allFiles = [];
         const walk = (dir) => {
             try {

package/build/extensions/git.js

@@ -119,8 +119,8 @@ class Git {
             const result = [];
             // Toolbox features
             const { system } = this.toolbox;
-            // Get branches
-            const branches = yield system.run('git fetch && git show-branch --list');
+            // Get branches (use short SSH timeout so fetch doesn't hang in offline environments)
+            const branches = yield system.run('GIT_TERMINAL_PROMPT=0 GIT_SSH_COMMAND="ssh -o ConnectTimeout=5 -o BatchMode=yes" git fetch 2>/dev/null; git show-branch --list');
             branches.split('\n').forEach((item) => {
                 const matches = item.match(/\[(.*?)]/);
                 if (matches) {
@@ -251,11 +251,10 @@ class Git {
             if (opts.spin) {
                 searchSpin = spin(opts.spinText);
             }
-            // Update infos
-            const fetch = yield system.run('git fetch');
+            // Update infos (use short SSH timeout so fetch doesn't hang in offline environments)
+            const fetch = yield system.run('GIT_TERMINAL_PROMPT=0 GIT_SSH_COMMAND="ssh -o ConnectTimeout=5 -o BatchMode=yes" git fetch 2>/dev/null || true');
             if (fetch.length && !fetch.startsWith('remote')) {
                 info(`Could not update infos ${fetch.length}`);
-                process.exit(1);
             }
             // Search branch
             if (opts.exact) {

package/build/extensions/server.js

@@ -46,6 +46,7 @@ exports.Server = void 0;
 const crypto = __importStar(require("crypto"));
 const path_1 = require("path");
 const ts = __importStar(require("typescript"));
+const markdown_table_1 = require("../lib/markdown-table");
 /**
  * Server helper functions
  */
@@ -749,6 +750,13 @@ class Server {
                 catch (err) {
                     return { method: result.method, path: dest, success: false };
                 }
+                // Post-install format pass. processApiMode may have left whitespace
+                // artifacts (multi-line arrays/imports) that the formatter flags in
+                // format:check; oxfmt is only available after install, so we run it
+                // here.
+                if (apiMode) {
+                    yield apiModeHelper.formatProject(dest);
+                }
             }
             return { method: result.method, path: dest, success: true };
         });
@@ -890,9 +898,11 @@ class Server {
      *
      * In vendor mode we additionally clone `@lenne.tech/nest-server` to
      * /tmp, copy its framework kernel (`src/core/`, `src/index.ts`,
-     * `src/core.module.ts`, `src/test/`, `src/templates/`, `src/types/`,
-     * `LICENSE`, `bin/migrate.js`) into the project at `src/core/`
-     * applying the flatten-fix, remove `@lenne.tech/nest-server` from the
+     * `src/core.module.ts`, `src/test/`, `src/types/`, `LICENSE`,
+     * `bin/migrate.js`) into the project at `src/core/` applying the
+     * flatten-fix, place upstream `src/templates/` at `<project>/src/templates/`
+     * (outside core/ so the runtime resolver finds it at the same relative
+     * path as in npm mode), remove `@lenne.tech/nest-server` from the
      * project's `package.json`, merge the framework's transitive deps into
      * the project's own deps, and run an AST-based codemod that rewrites
      * every `from '@lenne.tech/nest-server'` import in consumer code
@@ -994,7 +1004,10 @@ class Server {
                 //
                 // Upstream layout: src/core/ (framework sub-dir) + src/index.ts +
                 // src/core.module.ts + src/test/ + src/templates/ + src/types/.
-                // Target layout: everything flat under <project>/src/core/.
+                // Target layout: most things flat under <project>/src/core/, with
+                // one exception: src/templates/ stays at the same upstream location
+                // (<project>/src/templates/) because the runtime email-template
+                // resolver uses __dirname-relative lookup that must match npm mode.
                 //
                 // We WIPE the starter's (non-existent in npm mode) src/core/ first
                 // just to guarantee idempotency when users run this twice.
@@ -1006,7 +1019,15 @@ class Server {
                     [`${tmpClone}/src/index.ts`, `${coreDir}/index.ts`],
                     [`${tmpClone}/src/core.module.ts`, `${coreDir}/core.module.ts`],
                     [`${tmpClone}/src/test`, `${coreDir}/test`],
-                    [`${tmpClone}/src/templates`, `${coreDir}/templates`],
+                    // src/templates/ stays OUTSIDE src/core/ at its upstream location so
+                    // the runtime template resolver (which computes
+                    // `__dirname + '../../../templates'` from within
+                    // src/core/modules/better-auth/) finds E-Mail templates at the same
+                    // relative path as in npm mode (node_modules/@lenne.tech/nest-server/
+                    // src/templates/). Keeping templates as first-class project files
+                    // outside core/ also lets projects customize them without touching
+                    // the vendored framework tree.
+                    [`${tmpClone}/src/templates`, `${dest}/src/templates`],
                     [`${tmpClone}/src/types`, `${coreDir}/types`],
                     [`${tmpClone}/LICENSE`, `${coreDir}/LICENSE`],
                 ];
@@ -1395,14 +1416,14 @@ class Server {
                             "var f=require('fs'),h=require('https');",
                             "try{var c=f.readFileSync('src/core/VENDOR.md','utf8')}catch(e){process.exit(0)}",
                             'var m=c.match(/Baseline-Version[^0-9]*(\\d+\\.\\d+\\.\\d+)/);',
-                            'if(!m){process.stderr.write(String.fromCharCode(9888)+\' vendor-freshness: no baseline\\n\');process.exit(0)}',
+                            "if(!m){process.stderr.write(String.fromCharCode(9888)+' vendor-freshness: no baseline\\n');process.exit(0)}",
                             'var v=m[1];',
                             "h.get('https://registry.npmjs.org/@lenne.tech/nest-server/latest',function(r){",
                             "var d='';r.on('data',function(c){d+=c});r.on('end',function(){",
-                            "try{var l=JSON.parse(d).version;",
+                            'try{var l=JSON.parse(d).version;',
                             "if(v===l)console.log('vendor core up-to-date (v'+v+')');",
                             "else process.stderr.write('vendor core v'+v+', latest v'+l+'\\n')",
-                            '}catch(e){}})}).on(\'error\',function(){});',
+                            "}catch(e){}})}).on('error',function(){});",
                             'setTimeout(function(){process.exit(0)},5000)',
                             '"',
                         ].join('');
@@ -1417,7 +1438,8 @@ class Server {
                                 return;
                             const installPrefix = 'pnpm install && ';
                             if (existing.startsWith(installPrefix)) {
-                                scripts[scriptName] = `${installPrefix}pnpm run check:vendor-freshness && ${existing.slice(installPrefix.length)}`;
+                                scripts[scriptName] =
+                                    `${installPrefix}pnpm run check:vendor-freshness && ${existing.slice(installPrefix.length)}`;
                             }
                             else {
                                 scripts[scriptName] = `pnpm run check:vendor-freshness && ${existing}`;
@@ -1485,7 +1507,7 @@ class Server {
                     ' * Vendor-mode stub for extras/sync-packages.mjs.',
                     ' *',
                     ' * The original script is designed for npm-mode projects where',
-                    " * `@lenne.tech/nest-server` is an installed dependency and",
+                    ' * `@lenne.tech/nest-server` is an installed dependency and',
                     ' * `pnpm run update` pulls the latest upstream deps into the',
                     ' * project package.json.',
                     ' *',
@@ -1547,7 +1569,7 @@ class Server {
                         '',
                         '- **Read framework code from `src/core/**`** — not from `node_modules/`.',
                         '- **Generated imports use relative paths** to `src/core`, e.g.',
-                        '  `import { CrudService } from \'../../../core\';`',
+                        "  `import { CrudService } from '../../../core';`",
                         '  The exact depth depends on the file location. `lt server module`',
                         '  computes it automatically.',
                         '- **Baseline + patch log** live in `src/core/VENDOR.md`. Log any',
@@ -1615,17 +1637,48 @@ class Server {
                     '',
                     'This directory is a curated vendor copy of the `core/` tree from',
                     '@lenne.tech/nest-server. It is first-class project code, not a',
-                    'node_modules shadow copy. Edit freely; log substantial changes in',
-                    'the "Local changes" table below so the `nest-server-core-updater`',
-                    'agent can classify them at sync time.',
+                    'node_modules shadow copy — but it is **not a fork**. The copy',
+                    'exists so Claude Code (and humans) can read framework internals',
+                    'directly. Log substantial local changes in the "Local changes"',
+                    'table below so the `nest-server-core-updater` agent can classify',
+                    'them at sync time.',
                     '',
                     'The flatten-fix was applied during `lt fullstack init`: the',
                     'upstream `src/index.ts`, `src/core.module.ts`, `src/test/`,',
-                    '`src/templates/`, `src/types/`, and `LICENSE` were moved under',
-                    '`src/core/` and their relative `./core/…` specifiers were',
-                    'stripped. See the init code in',
+                    '`src/types/`, and `LICENSE` were moved under `src/core/` and',
+                    'their relative `./core/…` specifiers were stripped. The upstream',
+                    '`src/templates/` tree (E-Mail templates) was placed at the',
+                    'project root `src/templates/` (outside `src/core/`) so the',
+                    'runtime template resolver finds them at the same relative path',
+                    'as in npm mode. See the init code in',
                     '`lenneTech/cli/src/extensions/server.ts#convertCloneToVendored`.',
                     '',
+                    '## Modification Policy',
+                    '',
+                    'Edit `src/core/` **only** when the change is generally useful to every',
+                    '@lenne.tech/nest-server consumer:',
+                    '',
+                    '- Bugfixes that apply to every consumer',
+                    '- Broad framework enhancements',
+                    '- Security vulnerability fixes',
+                    '- Build/TypeScript compatibility fixes every consumer would hit',
+                    '',
+                    'Everything else stays **outside** `src/core/`. Project-specific',
+                    'business rules, customer enums, and proprietary integrations',
+                    'belong in project code via modification, inheritance, extension,',
+                    'or `ICoreModuleOverrides`.',
+                    '',
+                    'Generally-useful changes **MUST** be submitted as an upstream PR',
+                    'to https://github.com/lenneTech/nest-server. Run',
+                    '`/lt-dev:backend:contribute-nest-server-core` to prepare it — the',
+                    'agent filters cosmetic commits, categorizes local changes as',
+                    'upstream-candidate vs. project-specific, and writes PR drafts for',
+                    "human review. Letting useful fixes rot in one project's vendor",
+                    'tree is an anti-pattern: they belong upstream so every consumer',
+                    'benefits and the local patch disappears on the next sync.',
+                    '',
+                    'When in doubt, ask before editing `src/core/`.',
+                    '',
                     '## Baseline',
                     '',
                     '- **Upstream-Repo:** https://github.com/lenneTech/nest-server',
@@ -1636,22 +1689,15 @@ class Server {
                     '',
                     '## Sync history',
                     '',
-                    '| Date | From | To | Notes |',
-                    '| ---- | ---- | -- | ----- |',
-                    `| ${today} | — | ${syncHistoryTo} | scaffolded by lt CLI |`,
+                    ...(0, markdown_table_1.formatMarkdownTable)(['Date', 'From', 'To', 'Notes'], [[today, '—', syncHistoryTo, 'scaffolded by lt CLI']]),
                     '',
                     '## Local changes',
                     '',
-                    '| Date | Commit | Scope | Reason | Status |',
-                    '| ---- | ------ | ----- | ------ | ------ |',
-                    '| — | — | (none, pristine) | initial vendor | — |',
+                    ...(0, markdown_table_1.formatMarkdownTable)(['Date', 'Commit', 'Scope', 'Reason', 'Status'], [['—', '—', '(none, pristine)', 'initial vendor', '—']]),
                     '',
                     '## Upstream PRs',
                     '',
-                    '| PR | Title | Commits | Status |',
-                    '| -- | ----- | ------- | ------ |',
-                    '| — | (none yet) | — | — |',
-                    '',
+                    ...(0, markdown_table_1.formatMarkdownTable)(['PR', 'Title', 'Commits', 'Status'], [['—', '(none yet)', '—', '—']]),
                 ].join('\n'));
             }
             // ── Post-conversion verification ──────────────────────────────────────
@@ -1842,10 +1888,7 @@ class Server {
         if (!this.filesystem.exists(tsconfigPath)) {
             return;
         }
-        const EXCLUDE_ENTRIES = [
-            'src/core/modules/migrate/templates/**/*.template.ts',
-            'src/core/test/**/*.ts',
-        ];
+        const EXCLUDE_ENTRIES = ['src/core/modules/migrate/templates/**/*.template.ts', 'src/core/test/**/*.ts'];
         try {
             // The upstream tsconfig files may contain comments — standard JSON parse
             // breaks on them. Use a regex-based patch as a fallback.
@@ -2080,9 +2123,7 @@ class Server {
                     print.warning('');
                     print.warning('⚠  VENDOR.md documents local patches in src/core/ that will be LOST:');
                     // Extract non-header table rows
-                    const rows = localChangesSection[0]
-                        .split('\n')
-                        .filter((l) => /^\|\s*\d{4}-/.test(l));
+                    const rows = localChangesSection[0].split('\n').filter((l) => /^\|\s*\d{4}-/.test(l));
                     for (const row of rows.slice(0, 5)) {
                         print.info(`  ${row.trim()}`);
                     }
@@ -2112,10 +2153,7 @@ class Server {
             for (const sourceFile of project.getSourceFiles()) {
                 let modified = false;
                 // Static imports + re-exports
-                for (const decl of [
-                    ...sourceFile.getImportDeclarations(),
-                    ...sourceFile.getExportDeclarations(),
-                ]) {
+                for (const decl of [...sourceFile.getImportDeclarations(), ...sourceFile.getExportDeclarations()]) {
                     const spec = decl.getModuleSpecifierValue();
                     if (!spec)
                         continue;
@@ -2182,7 +2220,8 @@ class Server {
                 const migrateCompiler = 'ts:./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js';
                 const migrateStore = '--store ./migrations-utils/migrate.js --migrations-dir ./migrations';
                 const migrateTemplate = './node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/templates/migration-project.template.ts';
-                scripts['migrate:create'] = `f() { migrate create "$1" --template-file ${migrateTemplate} --migrations-dir ./migrations --compiler ${migrateCompiler}; }; f`;
+                scripts['migrate:create'] =
+                    `f() { migrate create "$1" --template-file ${migrateTemplate} --migrations-dir ./migrations --compiler ${migrateCompiler}; }; f`;
                 scripts['migrate:up'] = `migrate up ${migrateStore} --compiler ${migrateCompiler}`;
                 scripts['migrate:down'] = `migrate down ${migrateStore} --compiler ${migrateCompiler}`;
                 scripts['migrate:list'] = `migrate list ${migrateStore} --compiler ${migrateCompiler}`;
@@ -2262,8 +2301,7 @@ class Server {
                 let content = filesystem.read(gitignorePath) || '';
                 content = content
                     .split('\n')
-                    .filter((line) => !line.includes('scripts/vendor/sync-results') &&
-                    !line.includes('scripts/vendor/upstream-candidates'))
+                    .filter((line) => !line.includes('scripts/vendor/sync-results') && !line.includes('scripts/vendor/upstream-candidates'))
                     .join('\n');
                 filesystem.write(gitignorePath, content);
             }
@@ -2279,7 +2317,7 @@ class Server {
                 for (const f of staleRelativeImports.slice(0, 10)) {
                     print.info(`  ${f}`);
                 }
-                print.info('These imports must be manually rewritten to \'@lenne.tech/nest-server\'.');
+                print.info("These imports must be manually rewritten to '@lenne.tech/nest-server'.");
             }
         });
     }

package/build/lib/browser-fetcher.js

@@ -0,0 +1,139 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBrowserFetcher = createBrowserFetcher;
+/**
+ * Headless-browser HTML fetcher for single-page applications.
+ *
+ * Mirrors the chrome-md content script's PageReadyDetector:
+ * waits for the network to settle, then returns the fully hydrated
+ * HTML so Defuddle can extract the real content instead of the
+ * pre-render shell.
+ *
+ * Uses `playwright-core` with a three-tier strategy:
+ *   1. System Chrome / Edge via `channel: 'chrome' | 'msedge'`.
+ *   2. Playwright's own bundled Chromium (if already installed).
+ *   3. Auto-install Playwright's Chromium (`npx playwright install
+ *      chromium`) and retry — opt-in via `autoInstall`.
+ */
+const child_process_1 = require("child_process");
+const DEFAULT_USER_AGENT = 'Mozilla/5.0 (compatible; lenneTech-CLI-Crawler/1.0; +https://lenne.tech)';
+/**
+ * Try to construct a browser fetcher. Prefers a system Chrome /
+ * Edge via Playwright channels, falls back to Playwright's bundled
+ * Chromium, and (optionally) auto-installs Chromium on demand.
+ */
+function createBrowserFetcher() {
+    return __awaiter(this, arguments, void 0, function* (options = {}) {
+        const log = options.onLog || (() => undefined);
+        const reasons = [];
+        const { chromium } = require('playwright-core');
+        // 1. System Chrome.
+        const chromeFetcher = yield launch(chromium, { channel: 'chrome' }, options, 'system-chrome').catch((error) => {
+            reasons.push(`channel:chrome: ${error.message}`);
+            return null;
+        });
+        if (chromeFetcher) {
+            log(`Browser engine: ${chromeFetcher.engine}`);
+            return chromeFetcher;
+        }
+        // 2. System Edge (Windows fallback, also common on macOS).
+        const edgeFetcher = yield launch(chromium, { channel: 'msedge' }, options, 'system-edge').catch((error) => {
+            reasons.push(`channel:msedge: ${error.message}`);
+            return null;
+        });
+        if (edgeFetcher) {
+            log(`Browser engine: ${edgeFetcher.engine}`);
+            return edgeFetcher;
+        }
+        // 3. Playwright's bundled Chromium.
+        const bundledFetcher = yield launch(chromium, {}, options, 'playwright-chromium').catch((error) => {
+            reasons.push(`playwright-chromium: ${error.message}`);
+            return null;
+        });
+        if (bundledFetcher) {
+            log(`Browser engine: ${bundledFetcher.engine}`);
+            return bundledFetcher;
+        }
+        // 4. Optional auto-install, then retry Playwright's chromium.
+        if (options.autoInstall) {
+            log('No browser available — installing Playwright chromium (one-time download, ~170 MB)…');
+            try {
+                yield runNpx(['playwright', 'install', 'chromium']);
+                const retry = yield launch(chromium, {}, options, 'playwright-chromium');
+                if (retry) {
+                    log(`Browser engine: ${retry.engine}`);
+                    return retry;
+                }
+            }
+            catch (error) {
+                reasons.push(`auto-install: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        throw new Error([
+            'Could not start a headless browser for SPA rendering.',
+            ...reasons.map((r) => `  - ${r}`),
+            '',
+            'Fix one of these:',
+            '  1. Install Google Chrome or Microsoft Edge (Playwright picks them up automatically).',
+            '  2. Install Playwright browsers manually: `npx playwright install chromium`.',
+            '  3. Re-run with --install-browser to let the CLI install them.',
+        ].join('\n'));
+    });
+}
+function launch(chromium, launchOptions, options, engineLabel) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const browser = yield chromium.launch(Object.assign(Object.assign({}, launchOptions), { headless: true }));
+        const context = yield browser.newContext({
+            userAgent: options.userAgent || DEFAULT_USER_AGENT,
+        });
+        return {
+            close: () => __awaiter(this, void 0, void 0, function* () {
+                yield context.close();
+                yield browser.close();
+            }),
+            engine: engineLabel,
+            fetch: (url) => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const page = yield context.newPage();
+                try {
+                    yield page.goto(url, {
+                        timeout: (_a = options.maxWaitMs) !== null && _a !== void 0 ? _a : 20000,
+                        waitUntil: 'networkidle',
+                    });
+                    if (options.extraWaitMs) {
+                        yield page.waitForTimeout(options.extraWaitMs);
+                    }
+                    return yield page.content();
+                }
+                finally {
+                    yield page.close();
+                }
+            }),
+        };
+    });
+}
+/**
+ * Run an `npx` command, streaming its output to the current stdio.
+ * Resolves on exit code 0, rejects otherwise.
+ */
+function runNpx(args) {
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)('npx', args, { shell: false, stdio: 'inherit' });
+        child.on('error', reject);
+        child.on('exit', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`npx ${args.join(' ')} exited with code ${code}`));
+        });
+    });
+}