@lenne.tech/cli 1.9.6 → 1.11.0

package/README.md

@@ -38,9 +38,11 @@ $ lt
 
 ## Documentation
 
-- [Command Reference](docs/commands.md) - Complete list of all commands with options
-- [Configuration Guide](docs/lt.config.md) - Configuration file documentation
-- [Plugin Guide](docs/plugins.md) - How to create plugins
+- **[LT-ECOSYSTEM-GUIDE](docs/LT-ECOSYSTEM-GUIDE.md)** — Complete reference for `lt` CLI **and** the `lt-dev` Claude-Code Plugin (architecture, functions, vendor-mode workflows, agents, skills)
+- **[VENDOR-MODE-WORKFLOW](docs/VENDOR-MODE-WORKFLOW.md)** — Step-by-step guide for npm → vendor conversion, updates, and rollback
+- [Command Reference](docs/commands.md) — Complete list of all commands with options
+- [Configuration Guide](docs/lt.config.md) — Configuration file documentation
+- [Plugin Guide](docs/plugins.md) — How to create plugins
 
 ## Quick Start
 
@@ -55,6 +57,89 @@ $ lt status
 $ lt completion install
 ```
 
+## Framework consumption modes (nest-server)
+
+When you create a new api project (`lt fullstack init` or `lt server create`),
+the CLI supports two framework consumption modes:
+
+**`npm` mode (default)** — `@lenne.tech/nest-server` is installed as an npm
+dependency. Framework source lives in `node_modules/@lenne.tech/nest-server/`.
+Imports use the bare specifier `from '@lenne.tech/nest-server'`. Update path:
+`/lt-dev:backend:update-nest-server` (Claude Code agent).
+
+**`vendor` mode** — The framework's `core/` directory is copied directly into
+`<api>/src/core/` as first-class project code. No `@lenne.tech/nest-server`
+npm dependency. Generated imports use relative paths (`from '../../../core'`).
+Local patches are allowed and tracked in `src/core/VENDOR.md`. Update path:
+`/lt-dev:backend:update-nest-server-core` (Claude Code agent).
+
+### Creating projects
+
+```bash
+# npm mode (classic, default)
+$ lt fullstack init --name myapp --frontend nuxt --api-mode Rest
+
+# vendor mode, HEAD of upstream
+$ lt fullstack init --name myapp --frontend nuxt --api-mode Rest \
+    --framework-mode vendor
+
+# vendor mode, pinned to a specific upstream branch or tag
+$ lt fullstack init --name myapp --framework-mode vendor \
+    --framework-upstream-branch 11.24.1
+
+# dry-run: print the plan without touching the filesystem
+$ lt fullstack init --name myapp --framework-mode vendor --dry-run --noConfirm
+
+# standalone api project (vendor mode works here too)
+$ lt server create --name myapp --framework-mode vendor
+```
+
+### Working on an existing project
+
+All `lt server …` commands (module, object, addProp, test, permissions)
+**auto-detect** the framework mode via `src/core/VENDOR.md` and generate
+the correct import syntax automatically. You never pass `--framework-mode`
+after `init`; it is persisted in the project's `lt.config.json`.
+
+```bash
+# inside projects/api — generates relative or bare imports automatically
+$ lt server module --name Product --controller Rest
+
+# shows the mode + project type
+$ lt status
+
+# prints the mode-specific update instructions
+$ lt fullstack update
+```
+
+### Vendor-mode housekeeping
+
+Vendor-mode projects ship three maintenance scripts under `scripts/vendor/`:
+
+| Script | Purpose | Invocation |
+|---|---|---|
+| `check-vendor-freshness.mjs` | Non-blocking warning when upstream has a newer release than the current baseline | `pnpm run check:vendor-freshness` (auto-invoked by `pnpm run check` / `check:fix` / `check:naf`) |
+| `sync-from-upstream.ts` | Diff generator consumed by the `nest-server-core-updater` Claude Code agent | `pnpm run vendor:sync` |
+| `propose-upstream-pr.ts` | Patch-list generator consumed by the `nest-server-core-contributor` agent | `pnpm run vendor:propose-upstream` |
+
+The vendor-mode baseline (upstream version + commit SHA) is recorded in
+`src/core/VENDOR.md`. Log any substantial local patch there so the updater
+agent can classify it at sync time.
+
+### Integration test
+
+A full end-to-end smoke test for all four supported init combinations
+(`npm/Rest`, `vendor/Rest`, `vendor/GraphQL`, `vendor/Both`) ships with the
+CLI:
+
+```bash
+$ pnpm run test:vendor-init
+```
+
+Each scenario runs init → module → object → addProp → test → tsc → build →
+migrate:list and asserts ~30 structural + functional invariants per scenario.
+Run this before releasing a new CLI version to catch upstream drift early.
+
 ## Configuration
 
 The CLI supports project-specific configuration via `lt.config` files. This allows you to set default values for commands, reducing repetitive input.

package/build/commands/config/validate.js

@@ -56,9 +56,11 @@ const KNOWN_KEYS = {
             apiCopy: 'string',
             apiLink: 'string',
             apiMode: ['Rest', 'GraphQL', 'Both'],
+            frameworkMode: ['npm', 'vendor'],
             frontend: ['angular', 'nuxt'],
             frontendBranch: 'string',
             frontendCopy: 'string',
+            frontendFrameworkMode: ['npm', 'vendor'],
             frontendLink: 'string',
             git: 'boolean',
             gitLink: 'string',

package/build/commands/frontend/convert-mode.js

@@ -0,0 +1,198 @@
+"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 });
+const frontend_framework_detection_1 = require("../../lib/frontend-framework-detection");
+/**
+ * Convert an existing frontend project between npm mode and vendor mode.
+ *
+ * Usage:
+ *   lt frontend convert-mode --to vendor [--upstream-branch 1.5.3]
+ *   lt frontend convert-mode --to npm [--version 1.5.3]
+ */
+const ConvertModeCommand = {
+    description: 'Convert app framework mode',
+    hidden: false,
+    name: 'convert-mode',
+    run: (toolbox) => __awaiter(void 0, void 0, void 0, function* () {
+        const { filesystem, frontendHelper, parameters, print: { error, info, spin, success, warning }, prompt: { confirm }, } = toolbox;
+        // Handle --help-json flag
+        if (toolbox.tools.helpJson({
+            description: 'Convert frontend project between npm and vendor framework modes',
+            name: 'convert-mode',
+            options: [
+                {
+                    description: 'Target mode',
+                    flag: '--to',
+                    required: true,
+                    type: 'string',
+                    values: ['vendor', 'npm'],
+                },
+                {
+                    description: 'Upstream branch/tag to vendor from (only with --to vendor)',
+                    flag: '--upstream-branch',
+                    required: false,
+                    type: 'string',
+                },
+                {
+                    description: 'nuxt-extensions version to install (only with --to npm, default: from VENDOR.md baseline)',
+                    flag: '--version',
+                    required: false,
+                    type: 'string',
+                },
+                {
+                    default: false,
+                    description: 'Skip confirmation prompt',
+                    flag: '--noConfirm',
+                    required: false,
+                    type: 'boolean',
+                },
+                {
+                    default: false,
+                    description: 'Show the resolved plan without making any changes',
+                    flag: '--dry-run',
+                    required: false,
+                    type: 'boolean',
+                },
+            ],
+        })) {
+            return;
+        }
+        const targetMode = parameters.options.to;
+        if (!targetMode || !['npm', 'vendor'].includes(targetMode)) {
+            error('Missing or invalid --to flag. Use: --to vendor  or  --to npm');
+            return;
+        }
+        // Find the frontend project root
+        const cwd = filesystem.cwd();
+        const appDir = (0, frontend_framework_detection_1.findAppDir)(cwd);
+        if (!appDir) {
+            error('Could not find a nuxt.config.ts in the current directory or any parent. Are you inside a Nuxt project?');
+            return;
+        }
+        // Detect current mode
+        const currentMode = (0, frontend_framework_detection_1.detectFrontendFrameworkMode)(appDir);
+        info(`Detected current mode: ${currentMode}`);
+        if (currentMode === targetMode) {
+            warning(`Project is already in ${targetMode} mode. Nothing to do.`);
+            return;
+        }
+        // Dry-run: print the resolved plan and exit without any disk changes.
+        const dryRun = parameters.options['dry-run'] === true || parameters.options['dry-run'] === 'true';
+        if (dryRun) {
+            info('');
+            info('Dry-run plan:');
+            info(`  appDir:       ${appDir}`);
+            info(`  currentMode:  ${currentMode}`);
+            info(`  targetMode:   ${targetMode}`);
+            if (targetMode === 'vendor') {
+                const upstreamBranch = parameters.options['upstream-branch'];
+                info(`  upstreamBranch: ${upstreamBranch || '(auto-detect from package.json)'}`);
+                info('');
+                info('Would execute:');
+                info('  1. Clone @lenne.tech/nuxt-extensions → /tmp/lt-vendor-nuxt-ext-*');
+                info('  2. Copy src/module.ts + src/runtime/ → app/core/');
+                info('  3. Rewrite nuxt.config.ts: @lenne.tech/nuxt-extensions → ./app/core/module');
+                info('  4. Codemod consumer imports (app/**/*.{ts,vue}, tests/**/*.ts)');
+                info('  5. Remove @lenne.tech/nuxt-extensions from package.json');
+                info('  6. Add check:vendor-freshness script');
+                info('  7. Create app/core/VENDOR.md with baseline metadata');
+                info('  8. Prepend vendor-mode notice to CLAUDE.md');
+            }
+            else {
+                const targetVersion = parameters.options.version;
+                info(`  targetVersion: ${targetVersion || '(from VENDOR.md baseline)'}`);
+                info('');
+                info('Would execute:');
+                info('  1. Read baseline version from app/core/VENDOR.md');
+                info('  2. Warn if local patches exist in VENDOR.md');
+                info('  3. Rewrite consumer imports: relative → @lenne.tech/nuxt-extensions');
+                info('  4. Delete app/core/');
+                info('  5. Restore @lenne.tech/nuxt-extensions in package.json');
+                info('  6. Rewrite nuxt.config.ts: ./app/core/module → @lenne.tech/nuxt-extensions');
+                info('  7. Remove vendor scripts and CLAUDE.md marker');
+            }
+            info('');
+            return `frontend convert-mode dry-run (${currentMode} → ${targetMode})`;
+        }
+        // Confirm
+        const noConfirm = parameters.options.noConfirm;
+        if (!noConfirm) {
+            const proceed = yield confirm(`Convert project from ${currentMode} mode to ${targetMode} mode?\n` +
+                `  Project: ${appDir}\n` +
+                `  This will modify nuxt.config.ts, package.json, imports, and CLAUDE.md.`);
+            if (!proceed) {
+                info('Aborted.');
+                return;
+            }
+        }
+        // Execute conversion
+        if (targetMode === 'vendor') {
+            // npm → vendor
+            const upstreamBranch = parameters.options['upstream-branch'];
+            // Auto-detect version from current @lenne.tech/nuxt-extensions dep
+            let branch = upstreamBranch;
+            if (!branch) {
+                try {
+                    const pkg = filesystem.read(`${appDir}/package.json`, 'json');
+                    const deps = Object.assign(Object.assign({}, ((pkg === null || pkg === void 0 ? void 0 : pkg.dependencies) || {})), ((pkg === null || pkg === void 0 ? void 0 : pkg.devDependencies) || {}));
+                    const version = deps['@lenne.tech/nuxt-extensions'];
+                    if (version) {
+                        // Strip semver range chars (^, ~, >=, etc.) to get the bare version
+                        branch = version.replace(/^[^0-9]*/, '');
+                        info(`Auto-detected @lenne.tech/nuxt-extensions version: ${branch}`);
+                    }
+                }
+                catch (_a) {
+                    // Will use HEAD
+                }
+            }
+            const spinner = spin('Converting to vendor mode...');
+            try {
+                yield frontendHelper.convertAppToVendorMode({
+                    dest: appDir,
+                    upstreamBranch: branch,
+                });
+                spinner.succeed('Converted to vendor mode successfully.');
+                success('\nNext steps:');
+                info('  1. Run: pnpm install');
+                info('  2. Run: pnpm run build (or nuxt build)');
+                info('  3. Commit the changes');
+            }
+            catch (err) {
+                spinner.fail(`Conversion failed: ${err.message}`);
+            }
+        }
+        else {
+            // vendor → npm
+            const targetVersion = parameters.options.version;
+            const spinner = spin('Converting to npm mode...');
+            try {
+                yield frontendHelper.convertAppToNpmMode({
+                    dest: appDir,
+                    targetVersion,
+                });
+                spinner.succeed('Converted to npm mode successfully.');
+                success('\nNext steps:');
+                info('  1. Run: pnpm install');
+                info('  2. Run: pnpm run build (or nuxt build)');
+                info('  3. Commit the changes');
+            }
+            catch (err) {
+                spinner.fail(`Conversion failed: ${err.message}`);
+            }
+        }
+        if (!parameters.options.fromGluegunMenu) {
+            process.exit();
+        }
+        return `converted frontend to ${targetMode} mode`;
+    }),
+};
+exports.default = ConvertModeCommand;