@lenne.tech/cli 1.27.0 → 1.29.0

package/build/commands/tools/crawl.js

@@ -9,6 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.help = void 0;
 const path_1 = require("path");
 const crawler_1 = require("../../lib/crawler");
 /**
@@ -18,6 +19,96 @@ const crawler_1 = require("../../lib/crawler");
  * shares the defuddle + Turndown extraction pipeline but runs headless
  * from Node and follows links / sitemaps automatically.
  */
+exports.help = {
+    aliases: ['cr'],
+    description: 'Crawl a website into Markdown files (for Claude Code knowledge bases)',
+    name: 'crawl',
+    options: [
+        {
+            description: 'Start URL (absolute http/https URL)',
+            flag: '--url',
+            required: true,
+            type: 'string',
+        },
+        {
+            default: '.',
+            description: 'Output directory (created if missing)',
+            flag: '--out',
+            type: 'string',
+        },
+        {
+            default: 0,
+            description: 'Link depth. 0 = only start page; 1 = + direct links; N = up to N hops; "all" (or -1) = follow every same-origin link until --max-pages is reached',
+            flag: '--depth',
+            type: 'number|all',
+        },
+        {
+            default: true,
+            description: 'Download images and inline them with local paths',
+            flag: '--images',
+            type: 'boolean',
+        },
+        {
+            default: true,
+            description: 'Also seed queue from <origin>/sitemap.xml',
+            flag: '--sitemap',
+            type: 'boolean',
+        },
+        {
+            default: 4,
+            description: 'Parallel HTTP requests',
+            flag: '--concurrency',
+            type: 'number',
+        },
+        {
+            default: 200,
+            description: 'Maximum number of pages to crawl (safety cap)',
+            flag: '--max-pages',
+            type: 'number',
+        },
+        {
+            description: 'CSS selector for the main content container',
+            flag: '--selector',
+            type: 'string',
+        },
+        {
+            default: 20000,
+            description: 'HTTP request timeout in ms',
+            flag: '--timeout',
+            type: 'number',
+        },
+        {
+            default: false,
+            description: 'Shortcut for --depth all (follows every same-origin link until --max-pages)',
+            flag: '--all',
+            type: 'boolean',
+        },
+        {
+            default: true,
+            description: "Render pages through a headless browser before extracting (for SPAs like Vue/Nuxt/React/Angular). Uses playwright-core with system Chrome / Edge, falling back to Playwright's bundled chromium. Disable with --no-render for plain HTTP fetches.",
+            flag: '--render',
+            type: 'boolean',
+        },
+        {
+            default: false,
+            description: 'If --render cannot find any browser, auto-install Playwright chromium (one-time ~170 MB download).',
+            flag: '--install-browser',
+            type: 'boolean',
+        },
+        {
+            default: true,
+            description: 'After a multi-page crawl, remove any .md or image files inside <outDir>/pages and <outDir>/images that were not written by this run. Disable with --no-prune to preserve old files.',
+            flag: '--prune',
+            type: 'boolean',
+        },
+        {
+            default: false,
+            description: 'Skip confirmation prompts',
+            flag: '--noConfirm',
+            type: 'boolean',
+        },
+    ],
+};
 const NewCommand = {
     alias: ['cr'],
     description: 'Crawl site to Markdown',
@@ -26,96 +117,7 @@ const NewCommand = {
     run: (toolbox) => __awaiter(void 0, void 0, void 0, function* () {
         var _a, _b, _c, _d, _e;
         const { config, filesystem, helper, parameters, print: { error, info, spin, success, warning }, prompt: { confirm }, tools, } = toolbox;
-        if (tools.helpJson({
-            aliases: ['cr'],
-            description: 'Crawl a website into Markdown files (for Claude Code knowledge bases)',
-            name: 'crawl',
-            options: [
-                {
-                    description: 'Start URL (absolute http/https URL)',
-                    flag: '--url',
-                    required: true,
-                    type: 'string',
-                },
-                {
-                    default: '.',
-                    description: 'Output directory (created if missing)',
-                    flag: '--out',
-                    type: 'string',
-                },
-                {
-                    default: 0,
-                    description: 'Link depth. 0 = only start page; 1 = + direct links; N = up to N hops; "all" (or -1) = follow every same-origin link until --max-pages is reached',
-                    flag: '--depth',
-                    type: 'number|all',
-                },
-                {
-                    default: true,
-                    description: 'Download images and inline them with local paths',
-                    flag: '--images',
-                    type: 'boolean',
-                },
-                {
-                    default: true,
-                    description: 'Also seed queue from <origin>/sitemap.xml',
-                    flag: '--sitemap',
-                    type: 'boolean',
-                },
-                {
-                    default: 4,
-                    description: 'Parallel HTTP requests',
-                    flag: '--concurrency',
-                    type: 'number',
-                },
-                {
-                    default: 200,
-                    description: 'Maximum number of pages to crawl (safety cap)',
-                    flag: '--max-pages',
-                    type: 'number',
-                },
-                {
-                    description: 'CSS selector for the main content container',
-                    flag: '--selector',
-                    type: 'string',
-                },
-                {
-                    default: 20000,
-                    description: 'HTTP request timeout in ms',
-                    flag: '--timeout',
-                    type: 'number',
-                },
-                {
-                    default: false,
-                    description: 'Shortcut for --depth all (follows every same-origin link until --max-pages)',
-                    flag: '--all',
-                    type: 'boolean',
-                },
-                {
-                    default: true,
-                    description: "Render pages through a headless browser before extracting (for SPAs like Vue/Nuxt/React/Angular). Uses playwright-core with system Chrome / Edge, falling back to Playwright's bundled chromium. Disable with --no-render for plain HTTP fetches.",
-                    flag: '--render',
-                    type: 'boolean',
-                },
-                {
-                    default: false,
-                    description: 'If --render cannot find any browser, auto-install Playwright chromium (one-time ~170 MB download).',
-                    flag: '--install-browser',
-                    type: 'boolean',
-                },
-                {
-                    default: true,
-                    description: 'After a multi-page crawl, remove any .md or image files inside <outDir>/pages and <outDir>/images that were not written by this run. Disable with --no-prune to preserve old files.',
-                    flag: '--prune',
-                    type: 'boolean',
-                },
-                {
-                    default: false,
-                    description: 'Skip confirmation prompts',
-                    flag: '--noConfirm',
-                    type: 'boolean',
-                },
-            ],
-        })) {
+        if (tools.helpJson(exports.help)) {
             return 'crawl';
         }
         tools.nonInteractiveHint('lt tools crawl <url> --out <dir> --depth 1 --noConfirm');

package/build/extensions/frontend-helper.js

@@ -11,6 +11,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");
+const vendor_claude_md_1 = require("../lib/vendor-claude-md");
 /**
  * Frontend helper functions for project scaffolding
  * Provides reusable methods for setting up Nuxt and Angular frontends
@@ -390,17 +391,10 @@ class FrontendHelper {
             // ── 6. Clean CLAUDE.md vendor marker ─────────────────────────────────
             const claudeMdPath = path.join(dest, 'CLAUDE.md');
             if (filesystem.exists(claudeMdPath)) {
-                let content = filesystem.read(claudeMdPath) || '';
-                const markerStart = '<!-- lt-vendor-marker-frontend -->';
-                const markerEnd = '---';
-                if (content.includes(markerStart)) {
-                    const startIdx = content.indexOf(markerStart);
-                    const endIdx = content.indexOf(markerEnd, startIdx);
-                    if (endIdx > startIdx) {
-                        content = content.slice(0, startIdx) + content.slice(endIdx + markerEnd.length);
-                        content = content.replace(/^\n+/, '');
-                        filesystem.write(claudeMdPath, content);
-                    }
+                const content = filesystem.read(claudeMdPath) || '';
+                const cleaned = (0, vendor_claude_md_1.removeVendorBlock)(content, vendor_claude_md_1.FRONTEND_VENDOR_MARKER);
+                if (cleaned !== content) {
+                    filesystem.write(claudeMdPath, cleaned);
                 }
             }
             // ── Post-conversion verification ─────────────────────────────────────
@@ -615,32 +609,9 @@ class FrontendHelper {
             const claudeMdPath = path.join(dest, 'CLAUDE.md');
             if (filesystem.exists(claudeMdPath)) {
                 const existing = filesystem.read(claudeMdPath) || '';
-                const marker = '<!-- lt-vendor-marker-frontend -->';
-                if (!existing.includes(marker)) {
-                    const vendorBlock = [
-                        marker,
-                        '',
-                        '# Vendor-Mode Notice (Frontend)',
-                        '',
-                        'This frontend project runs in **vendor mode**: the `@lenne.tech/nuxt-extensions`',
-                        'module has been copied directly into `app/core/` as first-class',
-                        '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'`.",
-                        '- **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.',
-                        '- **Update flow:** run `/lt-dev:frontend:update-nuxt-extensions-core`.',
-                        '- **Contribute back:** run `/lt-dev:frontend:contribute-nuxt-extensions-core`.',
-                        '- **Freshness check:** `pnpm run check:vendor-freshness` warns when',
-                        '  upstream has a newer release than the baseline.',
-                        '',
-                        '---',
-                        '',
-                    ].join('\n');
-                    filesystem.write(claudeMdPath, vendorBlock + existing);
+                const patched = (0, vendor_claude_md_1.insertVendorBlockIfMissing)(existing, vendor_claude_md_1.FRONTEND_VENDOR_MARKER, (0, vendor_claude_md_1.buildFrontendVendorBlock)());
+                if (patched !== existing) {
+                    filesystem.write(claudeMdPath, patched);
                 }
             }
             // Merge upstream CLAUDE.md sections

package/build/extensions/server.js

@@ -47,6 +47,7 @@ const crypto = __importStar(require("crypto"));
 const path_1 = require("path");
 const ts = __importStar(require("typescript"));
 const markdown_table_1 = require("../lib/markdown-table");
+const vendor_claude_md_1 = require("../lib/vendor-claude-md");
 /**
  * Server helper functions
  */
@@ -1585,36 +1586,9 @@ class Server {
             const apiClaudeMdPath = `${dest}/CLAUDE.md`;
             if (filesystem.exists(apiClaudeMdPath)) {
                 const existing = filesystem.read(apiClaudeMdPath) || '';
-                const marker = '<!-- lt-vendor-marker -->';
-                if (!existing.includes(marker)) {
-                    const vendorBlock = [
-                        marker,
-                        '',
-                        '# Vendor-Mode Notice',
-                        '',
-                        'This api project runs in **vendor mode**: the `@lenne.tech/nest-server`',
-                        'core/ tree has been copied directly into `src/core/` as first-class',
-                        'project code. There is **no** `@lenne.tech/nest-server` npm dependency.',
-                        '',
-                        '- **Read framework code from `src/core/**`** — not from `node_modules/`.',
-                        '- **Generated imports use relative paths** to `src/core`, e.g.',
-                        "  `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',
-                        '  substantial local change there so the `nest-server-core-updater`',
-                        '  agent can classify it at sync time.',
-                        '- **Update flow:** run `/lt-dev:backend:update-nest-server-core` (the',
-                        '  agent clones upstream, computes a delta, and presents a review).',
-                        '- **Contribute back:** run `/lt-dev:backend:contribute-nest-server-core`',
-                        '  to propose local fixes as upstream PRs.',
-                        '- **Freshness check:** `pnpm run check:vendor-freshness` warns (non-',
-                        '  blockingly) when upstream has a newer release than the baseline.',
-                        '',
-                        '---',
-                        '',
-                    ].join('\n');
-                    filesystem.write(apiClaudeMdPath, vendorBlock + existing);
+                const patched = (0, vendor_claude_md_1.insertVendorBlockIfMissing)(existing, vendor_claude_md_1.BACKEND_VENDOR_MARKER, (0, vendor_claude_md_1.buildBackendVendorBlock)());
+                if (patched !== existing) {
+                    filesystem.write(apiClaudeMdPath, patched);
                 }
             }
             // ── 9c. Merge nest-server CLAUDE.md sections into project CLAUDE.md ──
@@ -2307,14 +2281,10 @@ class Server {
             // ── 6. Clean CLAUDE.md vendor marker ────────────────────────────────
             const claudeMdPath = `${dest}/CLAUDE.md`;
             if (filesystem.exists(claudeMdPath)) {
-                let content = filesystem.read(claudeMdPath) || '';
-                const marker = '<!-- lt-vendor-marker -->';
-                if (content.includes(marker)) {
-                    // Remove everything from marker to the first `---` separator (end of vendor block)
-                    content = content.replace(new RegExp(`${marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?---\\s*\\n?`, ''), '');
-                    // Remove leading whitespace/newlines
-                    content = content.replace(/^\n+/, '');
-                    filesystem.write(claudeMdPath, content);
+                const content = filesystem.read(claudeMdPath) || '';
+                const cleaned = (0, vendor_claude_md_1.removeVendorBlock)(content, vendor_claude_md_1.BACKEND_VENDOR_MARKER);
+                if (cleaned !== content) {
+                    filesystem.write(claudeMdPath, cleaned);
                 }
             }
             // ── 7. Restore tsconfig excludes ────────────────────────────────────

package/build/lib/command-help.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * Generic `--help` / `-h` support for **every** lt command.
+ *
+ * Problem this solves: gluegun's built-in `.help()` only handles the top-level
+ * `lt --help` (the command list). For a subcommand, `lt fullstack convert-mode
+ * --help` simply *runs* the command — so a user who only wanted to read about a
+ * command accidentally triggers it. {@link installHelpInterceptor} wraps every
+ * loaded command so that, when help is requested, the command prints rich help
+ * and returns **without executing**.
+ *
+ * Two levels of detail:
+ *   1. Generic (always available) — usage, aliases and description from the
+ *      command metadata gluegun already has.
+ *   2. Rich (opt-in) — a command module may `export const help: CommandHelp`
+ *      describing options, features, examples and configuration. The interceptor
+ *      loads it from `command.file` without running the command.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installHelpInterceptor = installHelpInterceptor;
+exports.isHelpRequested = isHelpRequested;
+exports.loadCommandHelp = loadCommandHelp;
+exports.renderCommandHelp = renderCommandHelp;
+/**
+ * Wrap every command's `run` so that `--help` / `-h` prints help and returns
+ * without executing. Call once after `build().create()`, before `cli.run()`.
+ *
+ * Idempotent per command (guarded by `__helpWrapped`), so a command is never
+ * double-wrapped if this runs more than once in the same process (e.g. tests).
+ */
+function installHelpInterceptor(commands, defaultCommand) {
+    for (const command of commands || []) {
+        if (typeof command.run !== 'function' || command.__helpWrapped) {
+            continue;
+        }
+        // Leave the top-level/default command and gluegun's preloaded builtins
+        // (`help`, `version` — they have `file === null`) to gluegun's own
+        // `.help()`, so that `lt --help` keeps printing the brand banner + full
+        // command list. Real file-backed subcommands (incl. `lt config help`) are
+        // still wrapped.
+        if (command === defaultCommand || !command.file || !(command.commandPath && command.commandPath.length)) {
+            continue;
+        }
+        const originalRun = command.run;
+        command.run = (toolbox) => {
+            if ((toolbox === null || toolbox === void 0 ? void 0 : toolbox.print) && isHelpRequested(toolbox.parameters)) {
+                renderCommandHelp(toolbox.print, command, loadCommandHelp(command.file));
+                return undefined;
+            }
+            return originalRun(toolbox);
+        };
+        command.__helpWrapped = true;
+    }
+}
+/**
+ * True when the invocation asks for help (`--help` or `-h`) — but NOT for
+ * `--help-json` (handled separately by `tools.helpJson`).
+ */
+function isHelpRequested(parameters) {
+    const options = (parameters === null || parameters === void 0 ? void 0 : parameters.options) || {};
+    if (options['help-json'] === true || options.helpJson === true) {
+        return false;
+    }
+    return options.help === true || options.h === true;
+}
+/** Best-effort load of a command's rich `help` export from its file. */
+function loadCommandHelp(file) {
+    if (!file) {
+        return undefined;
+    }
+    try {
+        const mod = require(file);
+        const help = (mod && (mod.help || (mod.default && mod.default.help)));
+        return help && typeof help === 'object' ? help : undefined;
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+/**
+ * Render human-readable help for a command to `print`. Uses the rich `help`
+ * definition when available, otherwise a useful generic fallback. Never runs
+ * the command.
+ */
+function renderCommandHelp(print, command, help) {
+    var _a, _b, _c;
+    const { bold, cyan, dim, yellow } = print.colors;
+    const usage = usagePath(command);
+    const description = (help === null || help === void 0 ? void 0 : help.description) || command.description || '(no description)';
+    print.info('');
+    print.info(`${bold(usage)} — ${description}`);
+    const aliases = aliasList(command, help);
+    if (aliases.length) {
+        print.info(dim(`Aliases: ${aliases.join(', ')}`));
+    }
+    if ((_a = help === null || help === void 0 ? void 0 : help.features) === null || _a === void 0 ? void 0 : _a.length) {
+        print.info('');
+        print.info(bold('What it does:'));
+        for (const feature of help.features) {
+            print.info(`  • ${feature}`);
+        }
+    }
+    print.info('');
+    print.info(bold('Usage:'));
+    print.info(`  ${usage} [options]`);
+    if ((_b = help === null || help === void 0 ? void 0 : help.examples) === null || _b === void 0 ? void 0 : _b.length) {
+        print.info('');
+        print.info(bold('Examples:'));
+        for (const example of help.examples) {
+            print.info(`  ${cyan(example.startsWith('lt ') ? example : `lt ${example}`)}`);
+        }
+    }
+    print.info('');
+    print.info(bold('Options:'));
+    const options = [...((help === null || help === void 0 ? void 0 : help.options) || [])];
+    for (const option of options) {
+        const meta = [];
+        if (option.required) {
+            meta.push('required');
+        }
+        if ((_c = option.values) === null || _c === void 0 ? void 0 : _c.length) {
+            meta.push(option.values.join('|'));
+        }
+        else if (option.type) {
+            meta.push(option.type);
+        }
+        if (option.default !== undefined) {
+            meta.push(`default: ${String(option.default)}`);
+        }
+        const metaText = meta.length ? dim(` (${meta.join(', ')})`) : '';
+        print.info(`  ${option.flag.padEnd(28)} ${option.description}${metaText}`);
+    }
+    // Always-present global flags
+    print.info(`  ${'--help, -h'.padEnd(28)} Show this help and exit (does not run the command)`);
+    print.info(`  ${'--help-json'.padEnd(28)} Machine-readable help as JSON (where provided)`);
+    if (!options.some((o) => o.flag === '--noConfirm')) {
+        print.info(`  ${'--noConfirm'.padEnd(28)} Skip confirmation prompts (where supported)`);
+    }
+    if (help === null || help === void 0 ? void 0 : help.configuration) {
+        print.info('');
+        print.info(bold('Configuration (lt.config.json / lt.config.yaml):'));
+        for (const line of help.configuration.split('\n')) {
+            print.info(`  ${line}`);
+        }
+    }
+    if (!help) {
+        print.info('');
+        print.info(dim('Tip: see docs/commands.md and docs/lt.config.md for full reference.'));
+    }
+    print.info('');
+    print.info(yellow('This is help output — the command was NOT executed.'));
+    print.info('');
+}
+function aliasList(command, help) {
+    return (help === null || help === void 0 ? void 0 : help.aliases) || command.aliases || command.alias || [];
+}
+/** Resolve the user-facing invocation, e.g. `lt fullstack convert-mode`. */
+function usagePath(command) {
+    const path = command.commandPath && command.commandPath.length ? command.commandPath : [command.name || ''];
+    return `lt ${path.filter(Boolean).join(' ')}`.trim();
+}

package/build/lib/dev-identity.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildIdentity = buildIdentity;
 exports.buildTestIdentity = buildTestIdentity;
+exports.buildTicketIdentity = buildTicketIdentity;
 exports.projectSlug = projectSlug;
 exports.slugify = slugify;
 /**
@@ -85,6 +86,23 @@ function buildTestIdentity(base, suffix = '-test') {
     }
     return { root: base.root, slug, subdomains };
 }
+/**
+ * Derive a per-TICKET identity from a base identity (used by `lt ticket` /
+ * `lt dev up --ticket`). Suffixes the slug + every subdomain hostname with the
+ * ticket id, so each ticket worktree runs on its OWN URLs / ports / Caddy block
+ * / DB — fully parallel to and isolated from every other ticket and the base
+ * dev session.
+ *
+ *   svl.localhost      → svl-2200.localhost
+ *   api.svl.localhost  → api.svl-2200.localhost
+ *
+ * Mechanically identical to {@link buildTestIdentity} (a named wrapper for
+ * readability + intent at the call sites). `id` is already a clean slug (see
+ * `deriveTicketId` in dev-ticket.ts).
+ */
+function buildTicketIdentity(base, id) {
+    return buildTestIdentity(base, `-${id}`);
+}
 /**
  * Read the bare project name from package.json (scope stripped).
  * Falls back to directory basename if no package.json or no `name`.

package/build/lib/dev-patches.js

@@ -264,7 +264,7 @@ function patchPlaywrightConfig(file) {
     if (!/const SHARDED\b/.test(after) && /export default defineConfig/.test(after)) {
         const shardConst = '// `lt dev test --shard N` saturates the CPU (N built SSR servers + N Chromium),\n' +
             '// slowing every navigation. Relax timeouts ONLY under that load — the CLI sets\n' +
-            "// LT_DEV_TEST_SHARDS — so serial + CI keep their tight, fast-failing defaults.\n" +
+            '// LT_DEV_TEST_SHARDS — so serial + CI keep their tight, fast-failing defaults.\n' +
             "const SHARDED = Number(process.env.LT_DEV_TEST_SHARDS || '0') > 1;\n\n";
         after = after.replace(/(export default defineConfig)/, `${shardConst}$1`);
         count++;

package/build/lib/dev-project.js

@@ -4,6 +4,7 @@ exports.apiNeedsPortPatch = apiNeedsPortPatch;
 exports.appNeedsPortPatch = appNeedsPortPatch;
 exports.deriveDbName = deriveDbName;
 exports.deriveTestDbName = deriveTestDbName;
+exports.deriveTicketDbName = deriveTicketDbName;
 exports.resolveLayout = resolveLayout;
 const fs_1 = require("fs");
 const path_1 = require("path");
@@ -68,6 +69,19 @@ function deriveTestDbName(devDbName) {
     const base = devDbName.replace(/-(local|dev)$/i, '');
     return `${base}-test`;
 }
+/**
+ * Derive the per-TICKET database name from the project's dev DB name, so each
+ * ticket worktree reads/writes its OWN database and tickets never collide.
+ *
+ *   svl-sports-system-local + "2200" → svl-sports-system-2200
+ *
+ * The ticket's isolated `lt dev test` stack then derives its test DB from this
+ * via {@link deriveTestDbName} → `svl-sports-system-2200-test`.
+ */
+function deriveTicketDbName(devDbName, ticketId) {
+    const base = devDbName.replace(/-(local|dev)$/i, '');
+    return `${base}-${ticketId}`;
+}
 /**
  * Resolve layout starting from `cwd`. Walks up to find a workspace if
  * cwd is inside `projects/api/` or `projects/app/`.