@lenne.tech/cli 1.28.0 → 1.30.0

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/extensions/tools.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Tools = void 0;
 const fs_1 = require("fs");
+const command_help_1 = require("../lib/command-help");
 const singleComment = Symbol('singleComment');
 const multiComment = Symbol('multiComment');
 const stripWithoutWhitespace = () => '';
@@ -27,6 +28,14 @@ class Tools {
      * Check if --help-json flag is set; if so, print the command definition as JSON and return true.
      * Commands should call this early and return immediately when it returns true.
      *
+     * In normal CLI usage the global `installHelpInterceptor` (see
+     * `src/lib/command-help.ts`) handles `--help-json` for ALL commands before
+     * their `run()` ever fires — this method is therefore mostly a no-op in
+     * production. It is still kept as a public escape hatch for tests that
+     * invoke a command's `run()` directly without the interceptor, and for
+     * legacy callers — output goes through the same `buildHelpJson` /
+     * `emitHelpJson` pair as the global path, so the schema cannot drift.
+     *
      * @param definition - The command's help definition (name, description, options, etc.)
      * @returns true if --help-json was handled (caller should return), false otherwise
      */
@@ -35,7 +44,7 @@ class Tools {
         if (!parameters.options['help-json'] && !parameters.options.helpJson) {
             return false;
         }
-        console.debug(JSON.stringify(definition, null, 2));
+        (0, command_help_1.emitHelpJson)((0, command_help_1.buildHelpJson)({ description: definition.description, name: definition.name }, definition));
         return true;
     }
     /**

package/build/lib/command-help.js

@@ -0,0 +1,209 @@
+"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.isHelpJsonRequested = isHelpJsonRequested;
+exports.isHelpRequested = isHelpRequested;
+exports.loadCommandHelp = loadCommandHelp;
+exports.renderCommandHelp = renderCommandHelp;
+exports.buildHelpJson = buildHelpJson;
+exports.emitHelpJson = emitHelpJson;
+/**
+ * Wrap every command's `run` so that `--help` / `-h` and `--help-json` print
+ * help and return 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 (isHelpJsonRequested(toolbox === null || toolbox === void 0 ? void 0 : toolbox.parameters)) {
+                emitHelpJson(buildHelpJson(command, loadCommandHelp(command.file)));
+                return undefined;
+            }
+            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 machine-readable help (`--help-json`). */
+function isHelpJsonRequested(parameters) {
+    const options = (parameters === null || parameters === void 0 ? void 0 : parameters.options) || {};
+    return options['help-json'] === true || options.helpJson === true;
+}
+/** True when the invocation asks for human-readable help (`--help` or `-h`). */
+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 (does not run the command)`);
+    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();
+}
+const GLOBAL_HELP_FLAGS = [
+    { description: 'Show human-readable help; the command is NOT executed.', flag: '--help', type: 'boolean' },
+    { description: 'Alias for --help.', flag: '-h', type: 'boolean' },
+    {
+        description: 'Print this JSON description on stdout; the command is NOT executed.',
+        flag: '--help-json',
+        type: 'boolean',
+    },
+];
+/**
+ * Build the JSON shape returned by `--help-json` for a command, merging the
+ * gluegun-known metadata (name, commandPath, description, aliases) with the
+ * command's optional rich `CommandHelp` export.
+ */
+function buildHelpJson(command, help) {
+    const aliases = aliasList(command, help);
+    return {
+        aliases,
+        command: usagePath(command),
+        configuration: help === null || help === void 0 ? void 0 : help.configuration,
+        description: (help === null || help === void 0 ? void 0 : help.description) || command.description || '',
+        examples: help === null || help === void 0 ? void 0 : help.examples,
+        features: help === null || help === void 0 ? void 0 : help.features,
+        globalFlags: GLOBAL_HELP_FLAGS,
+        name: (help === null || help === void 0 ? void 0 : help.name) || command.name || '',
+        options: (help === null || help === void 0 ? void 0 : help.options) || [],
+        richHelp: Boolean(help),
+    };
+}
+/**
+ * Emit a help-json payload to stdout as a single pretty-printed JSON document.
+ * Kept tiny + side-effect-only so it can be stubbed in tests via a captured
+ * `console.log`.
+ */
+function emitHelpJson(payload) {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(payload, null, 2));
+}

package/build/lib/vendor-claude-md.js

@@ -0,0 +1,227 @@
+"use strict";
+/**
+ * Single source of truth for the "Vendor-Mode Notice" blocks that the CLI
+ * writes into project CLAUDE.md files.
+ *
+ * Why this exists: when a project runs in vendor mode, Claude Code (and humans)
+ * must know — from the project itself, without the lt-dev plugin installed —
+ * that the framework lives in a vendored `core/` tree and which command syncs
+ * it (`update`) vs. ports local fixes back (`contribute`). The plugin hooks are
+ * a proactive safety net, but they only fire when the plugin is installed; the
+ * CLAUDE.md block is the plugin-independent channel.
+ *
+ * Three blocks are generated:
+ *   - Backend  → `projects/api/CLAUDE.md`   (marker {@link BACKEND_VENDOR_MARKER})
+ *   - Frontend → `projects/app/CLAUDE.md`   (marker {@link FRONTEND_VENDOR_MARKER})
+ *   - Root     → workspace `CLAUDE.md`      (marker {@link ROOT_VENDOR_MARKER})
+ *
+ * The root block is new: Claude often reads the monorepo root CLAUDE.md first,
+ * so it needs a short pointer to the per-subproject vendor docs.
+ *
+ * Each block starts with its HTML marker comment and ends with a `---`
+ * horizontal rule, so {@link upsertVendorBlock} / {@link removeVendorBlock} can
+ * find and replace exactly the generated region without touching hand-written
+ * content below it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROOT_VENDOR_MARKER = exports.FRONTEND_VENDOR_MARKER = exports.BACKEND_VENDOR_MARKER = void 0;
+exports.buildBackendVendorBlock = buildBackendVendorBlock;
+exports.buildFrontendVendorBlock = buildFrontendVendorBlock;
+exports.buildRootVendorBlock = buildRootVendorBlock;
+exports.hasVendorBlock = hasVendorBlock;
+exports.healVendorClaudeMd = healVendorClaudeMd;
+exports.insertVendorBlockIfMissing = insertVendorBlockIfMissing;
+exports.removeVendorBlock = removeVendorBlock;
+exports.upsertVendorBlock = upsertVendorBlock;
+exports.BACKEND_VENDOR_MARKER = '<!-- lt-vendor-marker -->';
+exports.FRONTEND_VENDOR_MARKER = '<!-- lt-vendor-marker-frontend -->';
+exports.ROOT_VENDOR_MARKER = '<!-- lt-vendor-marker-root -->';
+/**
+ * Vendor-mode notice for the backend api project (`projects/api/CLAUDE.md`).
+ */
+function buildBackendVendorBlock() {
+    return block([
+        exports.BACKEND_VENDOR_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). The',
+        '  update also raises npm packages to at least the upstream baseline',
+        '  (via `/lt-dev:maintenance:maintain`).',
+        '- **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.',
+    ]);
+}
+/**
+ * Vendor-mode notice for the frontend app project (`projects/app/CLAUDE.md`).
+ */
+function buildFrontendVendorBlock() {
+    return block([
+        exports.FRONTEND_VENDOR_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`. The',
+        '  update also raises npm packages to at least the upstream baseline',
+        '  (via `/lt-dev:maintenance:maintain`).',
+        '- **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.',
+    ]);
+}
+/**
+ * Vendor-mode notice for the monorepo root (`<workspace>/CLAUDE.md`).
+ *
+ * Tailored to which halves are vendored so Claude sees only the relevant
+ * commands. At least one of `backend` / `frontend` must be true; otherwise the
+ * caller should {@link removeVendorBlock} instead of writing an empty notice.
+ */
+function buildRootVendorBlock(opts) {
+    const { backend, frontend } = opts;
+    const lines = [
+        exports.ROOT_VENDOR_MARKER,
+        '',
+        '# Vendor-Mode Notice (Monorepo)',
+        '',
+        'This workspace runs at least one framework in **vendor mode** — the',
+        'framework source is vendored directly into the project tree instead of',
+        'being an npm dependency. Read framework code from the vendored `core/`',
+        'trees, not from `node_modules/`.',
+        '',
+        '**Vendored frameworks:**',
+    ];
+    if (backend) {
+        lines.push('- **Backend** (`@lenne.tech/nest-server`): `projects/api/src/core/` —', '  details in `projects/api/CLAUDE.md` and `projects/api/src/core/VENDOR.md`.');
+    }
+    if (frontend) {
+        lines.push('- **Frontend** (`@lenne.tech/nuxt-extensions`): `projects/app/app/core/` —', '  details in `projects/app/CLAUDE.md` and `projects/app/app/core/VENDOR.md`.');
+    }
+    lines.push('', '**Update** (sync from upstream; also raises npm packages to at least the', 'upstream baseline via `/lt-dev:maintenance:maintain`):');
+    if (backend) {
+        lines.push('- Backend: `/lt-dev:backend:update-nest-server-core`');
+    }
+    if (frontend) {
+        lines.push('- Frontend: `/lt-dev:frontend:update-nuxt-extensions-core`');
+    }
+    lines.push('', '**Contribute back** generally-useful core fixes as upstream PRs:');
+    if (backend) {
+        lines.push('- Backend: `/lt-dev:backend:contribute-nest-server-core`');
+    }
+    if (frontend) {
+        lines.push('- Frontend: `/lt-dev:frontend:contribute-nuxt-extensions-core`');
+    }
+    lines.push('', 'Project-specific code never goes into a `core/` tree — see each', "subproject's VENDOR.md Modification Policy.");
+    return block(lines);
+}
+/** True when `content` already contains the given vendor marker. */
+function hasVendorBlock(content, marker) {
+    return content.includes(marker);
+}
+/**
+ * Bring every CLAUDE.md in a workspace in line with its current vendor state:
+ * upsert the matching notice block where a framework is vendored, remove it
+ * where it is not. Idempotent — running it on an already-correct workspace
+ * changes nothing.
+ *
+ * This is what makes `lt fullstack update` able to *heal* pre-existing or
+ * drifted vendor projects (e.g. ones scaffolded before the root notice existed,
+ * or whose notice fell out of date).
+ *
+ * @returns the list of CLAUDE.md paths that were actually modified.
+ */
+function healVendorClaudeMd(fs, state) {
+    const changed = [];
+    const apply = (path, marker, desiredBlock) => {
+        if (!fs.exists(path)) {
+            return;
+        }
+        const content = fs.read(path) || '';
+        const next = desiredBlock ? upsertVendorBlock(content, marker, desiredBlock) : removeVendorBlock(content, marker);
+        if (next !== content) {
+            fs.write(path, next);
+            changed.push(path);
+        }
+    };
+    if (state.apiDir) {
+        apply(joinPath(state.apiDir, 'CLAUDE.md'), exports.BACKEND_VENDOR_MARKER, state.backendVendor ? buildBackendVendorBlock() : null);
+    }
+    if (state.appDir) {
+        apply(joinPath(state.appDir, 'CLAUDE.md'), exports.FRONTEND_VENDOR_MARKER, state.frontendVendor ? buildFrontendVendorBlock() : null);
+    }
+    if (state.workspaceRoot) {
+        const anyVendor = state.backendVendor || state.frontendVendor;
+        apply(joinPath(state.workspaceRoot, 'CLAUDE.md'), exports.ROOT_VENDOR_MARKER, anyVendor ? buildRootVendorBlock({ backend: state.backendVendor, frontend: state.frontendVendor }) : null);
+    }
+    return changed;
+}
+/**
+ * Insert the block at the very top of the file **only when it is missing**.
+ * Used during conversion so a hand-customized existing block is never clobbered.
+ */
+function insertVendorBlockIfMissing(content, marker, newBlock) {
+    if (content.includes(marker)) {
+        return content;
+    }
+    return newBlock + content;
+}
+/**
+ * Remove the generated block (marker through the first `---`) and trim leading
+ * blank lines. Used when converting a project back to npm mode.
+ */
+function removeVendorBlock(content, marker) {
+    if (!content.includes(marker)) {
+        return content;
+    }
+    return content.replace(blockRegex(marker), '').replace(/^\n+/, '');
+}
+/**
+ * Insert the block if missing, or replace the existing generated region with the
+ * current canonical block (idempotent self-heal). Used by `lt fullstack update`
+ * to bring pre-existing / drifted projects up to the current notice.
+ */
+function upsertVendorBlock(content, marker, newBlock) {
+    if (!content.includes(marker)) {
+        return newBlock + content;
+    }
+    return content.replace(blockRegex(marker), newBlock);
+}
+/** Join block lines into the canonical `marker … --- ` shape (ends with `---\n`). */
+function block(lines) {
+    return [...lines, '', '---', ''].join('\n');
+}
+/** Build the regex that matches an existing block from its marker to the first `---`. */
+function blockRegex(marker) {
+    return new RegExp(`${escapeRegExp(marker)}[\\s\\S]*?---\\s*\\n?`);
+}
+/** Escape a string for safe use inside a RegExp. */
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function joinPath(dir, file) {
+    return dir.endsWith('/') ? `${dir}${file}` : `${dir}/${file}`;
+}

package/docs/commands.md

@@ -10,6 +10,7 @@ This document provides a comprehensive reference for all `lt` CLI commands. For
 
 ## Table of Contents
 
+- [Global Flags](#global-flags)
 - [CLI Commands](#cli-commands)
 - [Server Commands](#server-commands)
 - [Local Development Commands](#local-development-commands)
@@ -32,6 +33,44 @@ This document provides a comprehensive reference for all `lt` CLI commands. For
 
 ---
 
+## Global Flags
+
+These flags work on **every** `lt` subcommand. They are intercepted before the command's `run()` fires, so the command is never executed when one of them is set.
+
+| Flag | Description |
+|--------|-------------|
+| `--help`, `-h` | Print human-readable help (usage, aliases, options, examples). |
+| `--help-json` | Print the same help as a single JSON document on stdout. Stable contract — see shape below. Intended for AI agents and tooling that want to discover a command's surface programmatically. |
+| `--noConfirm` | Skip interactive confirmations (where supported by the command). |
+
+**`--help-json` payload shape** (`HelpJsonShape` in [src/lib/command-help.ts](../src/lib/command-help.ts)):
+
+```jsonc
+{
+  "aliases": ["c"],
+  "command": "lt server create",
+  "configuration": "commands.server.create.*",
+  "description": "Create new server",
+  "examples": ["server create --name Foo --noConfirm"],
+  "features": ["..."],
+  "globalFlags": [
+    { "flag": "--help",      "type": "boolean", "description": "..." },
+    { "flag": "-h",          "type": "boolean", "description": "..." },
+    { "flag": "--help-json", "type": "boolean", "description": "..." }
+  ],
+  "name": "create",
+  "options": [
+    { "flag": "--name", "type": "string", "required": true, "description": "Server name" }
+  ],
+  "richHelp": true
+}
+```
+
+- `richHelp: true` means the command exported a typed `CommandHelp` — `options`, `features`, `examples` and `configuration` are authoritative.
+- `richHelp: false` means only gluegun metadata was available — `options` is the empty array, but `globalFlags` is still guaranteed.
+
+---
+
 ## CLI Commands
 
 ### `lt cli create`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/cli",
-  "version": "1.28.0",
+  "version": "1.30.0",
   "description": "lenne.Tech CLI: lt",
   "keywords": [
     "lenne.Tech",