@lenne.tech/cli 1.19.0 → 1.21.0

package/docs/commands.md

@@ -12,6 +12,8 @@ This document provides a comprehensive reference for all `lt` CLI commands. For
 
 - [CLI Commands](#cli-commands)
 - [Server Commands](#server-commands)
+- [Local Development Commands](#local-development-commands)
+- [Ports Commands](#ports-commands)
 - [Git Commands](#git-commands)
 - [Fullstack Commands](#fullstack-commands)
 - [Deployment Commands](#deployment-commands)
@@ -67,7 +69,7 @@ lt cli rename <new-name>
 
 ### `lt server create`
 
-Creates a new NestJS server project.
+Creates a new standalone NestJS server project in a sibling directory. For an in-workspace API, prefer [`lt fullstack add-api`](#lt-fullstack-add-api).
 
 **Usage:**
 ```bash
@@ -77,17 +79,27 @@ lt server create [name] [options]
 **Options:**
 | Option | Description |
 |--------|-------------|
+| `--name <name>` | Server name (preferred over the positional argument) |
 | `--description <text>` | Project description |
 | `--author <name>` | Author name |
 | `--api-mode <Rest\|GraphQL\|Both>` | API mode (ignored with `--next`) |
 | `--framework-mode <npm\|vendor>` | Framework consumption mode (ignored with `--next`) |
+| `--framework-upstream-branch <ref>` | Upstream `nest-server` branch/tag/commit to vendor (only with `--framework-mode vendor`) |
 | `--branch <branch>` / `-b` | Branch of nest-server-starter to use as template |
 | `--copy <path>` / `-c` | Copy from local template directory instead of cloning |
 | `--link <path>` | Symlink to local template directory (fastest, changes affect original) |
 | `--git` | Initialize git repository |
 | `--next` | **Experimental:** clone [`nest-base`](https://github.com/lenneTech/nest-base) (Bun + Prisma 7 + Postgres + Better-Auth) instead of `nest-server-starter`. Skips API-mode / vendor-mode / install / lt.config.json processing. |
+| `--dry-run` | Print the resolved plan and exit without making any changes |
+| `--force` | Override the workspace-detection abort under `--noConfirm` |
 | `--noConfirm` | Skip confirmation prompts |
 
+**Workspace-awareness:** When run inside a directory that already looks like a fullstack workspace (contains `pnpm-workspace.yaml` or `projects/`), the command behaves differently per mode:
+
+- **interactive** → asks for confirmation before creating a stray standalone clone
+- **`--noConfirm` without `--force`** → **refuses** with exit code 1 and points the caller to `lt fullstack add-api`. This is the default behaviour for AI agents and CI scripts: fail loud rather than produce a stray clone that pnpm-workspace.yaml does not pick up.
+- **`--noConfirm --force`** → proceeds and logs a hint so the override is visible in CI logs.
+
 **CLAUDE.md Patching:** If the project contains a `CLAUDE.md`, the generic API mode description is replaced with the selected mode. In single-mode projects (`Rest` or `GraphQL`), the "API Mode System" documentation section is condensed to a brief note. Skipped when `--next` is used.
 
 **Configuration:** `commands.server.create.*`, `defaults.author`, `defaults.noConfirm`
@@ -272,6 +284,193 @@ For mode-aware update workflows after conversion, use:
 
 ---
 
+## Local Development Commands
+
+Orchestrate parallel lt projects on the same machine without port collisions. Each project gets a deterministic port slot derived from its slug; API/App ports are always slot-paired (`3000+slot*10` / `3001+slot*10`). Slot allocation is reproducible across machines (FNV-1a hash) and persisted in `~/.lenneTech/ports.json`.
+
+### `lt local`
+
+Open the local-orchestration submenu.
+
+**Usage:**
+```bash
+lt local
+```
+
+**Alias:** `lt l`
+
+---
+
+### `lt local init`
+
+Register the current project in the central port registry, optionally patching legacy hardcoded ports to be env-aware.
+
+**Usage:**
+```bash
+lt local init [options]
+```
+
+**Alias:** `lt l i`
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--slot <n>` | Force a specific slot index (0..89) instead of the deterministic slug hash |
+| `--patch` | Apply env-aware port patches non-interactively |
+| `--no-patch` | Skip the patch detection / prompt entirely |
+| `--noConfirm` | Skip confirmation prompts (without `--patch`, patches are skipped) |
+
+**What it does:**
+1. Detects the workspace layout (monorepo with `projects/api/` + `projects/app/`, or standalone API/App project).
+2. Looks up or allocates a slot via FNV-1a hash of the project slug. If the slot is taken, falls through linearly to the next free slot.
+3. Detects legacy hardcoded ports in `config.env.ts` (`port: 3000`), `nuxt.config.ts` (`port: 3001`, vite proxy `target: 'http://localhost:3000'`), and `playwright.config.ts` (`baseURL`/`host`/`url: 'http://localhost:3001'`). If `--patch` (or interactive confirm), rewrites them to env-overridable form (`Number(process.env.PORT) || 3000`, `process.env.NUXT_API_URL || …`, etc.) — defaults preserved, idempotent.
+4. Persists the entry to `~/.lenneTech/ports.json`.
+5. Adds `.lt-local/` to the project's `.gitignore`.
+6. Injects (or refreshes) a "Local Development (lt local)" port block into `CLAUDE.md` files at the workspace root and inside each subproject — bracketed by HTML comment markers so it can be replaced cleanly when ports change.
+
+**Examples:**
+```bash
+# Inside a workspace or standalone project
+lt local init
+
+# Force slot 5 for predictable cross-team ports
+lt local init --slot 5 --noConfirm --patch
+
+# Register without touching any source files
+lt local init --no-patch --noConfirm
+```
+
+---
+
+### `lt local up`
+
+Start the API + App with project-specific ports. Spawns `pnpm start` (api) and `pnpm dev` (app) detached; persists PIDs to `<root>/.lt-local/state.json`.
+
+**Usage:**
+```bash
+lt local up
+```
+
+**Alias:** `lt l u`
+
+**Environment variables injected into both children:**
+| Variable | Consumer | Example value |
+|----------|----------|---------------|
+| `PORT` | Nest (api) / Nuxt dev server (app) | slot-derived |
+| `BASE_URL` | nest-server config.env.ts (canonical API base) | `http://localhost:3030` |
+| `APP_URL` | nest-server config.env.ts (frontend origin for redirects/CORS) | `http://localhost:3031` |
+| `NUXT_API_URL` | Nuxt vite-proxy target for `/api`, `/iam`, … | `http://localhost:3030` |
+| `NUXT_PUBLIC_API_URL` | Nuxt `useRuntimeConfig().public.apiUrl` | `http://localhost:3030` |
+| `NUXT_PUBLIC_SITE_URL` | Nuxt `useRuntimeConfig().public.siteUrl` + Playwright | `http://localhost:3031` |
+| `NUXT_PUBLIC_STORAGE_PREFIX` | namespaces sessionStorage/localStorage so parallel projects don't share auth tokens | `crm-local` |
+| `NSC__MONGOOSE__URI` | nest-server-config Mongoose URI (only when `dbName` is known) | `mongodb://127.0.0.1/crm-local` |
+
+**Override the binary** used for both spawns by setting `LT_PNPM_BIN` (e.g. `LT_PNPM_BIN=/usr/local/bin/pnpm lt local up`).
+
+**Pre-flight guards (exit code 1 each):**
+- Project not registered (`lt local init` first)
+- Already running (run `lt local down` first)
+- Port already in use by another process
+
+**Logs:** `<root>/.lt-local/api.log`, `<root>/.lt-local/app.log` (append-mode).
+
+---
+
+### `lt local down`
+
+Stop processes started by `lt local up`. Sends `SIGTERM` to the detached process group (negative PID) so descendants — Vite, the Nest watcher, etc. — receive the signal too. Falls back to single-PID kill if the process group send fails (`EPERM`).
+
+**Usage:**
+```bash
+lt local down
+```
+
+**Alias:** `lt l d`
+
+PID values from `state.json` are validated (positive integer in `[100, 2^31)`) before any signal is sent, so a tampered state file cannot cause `lt local down` to signal arbitrary process groups.
+
+---
+
+### `lt local status`
+
+Show what is registered + running for the current project: slot, ports, db URI, PIDs (alive/dead), and live `lsof` state of the assigned ports.
+
+**Usage:**
+```bash
+lt local status
+```
+
+**Alias:** `lt l s`
+
+---
+
+## Ports Commands
+
+Inspect the port registry and currently-bound dev ports across all your lt projects. Useful for diagnosing collisions and rebuilding the registry from disk.
+
+### `lt ports`
+
+List all reserved registry entries side-by-side with the live `lsof` state. Issues a single `lsof` call internally for the entire slot range (3000–3899) instead of per port — runs in ~150ms regardless of how many projects are registered.
+
+**Usage:**
+```bash
+lt ports
+```
+
+**Alias:** `lt p`
+
+**Output sections:**
+1. **Reserved ports (registry)** — every project entry with a `●` (bound) or `○` (free) indicator per port.
+2. **Currently bound dev ports (3000–3899)** — every port in the slot range that currently has a LISTEN socket, with command + PID + owning registry entry (if any).
+
+---
+
+### `lt ports check <port>`
+
+Exit-coded port probe — useful in shell scripts.
+
+**Usage:**
+```bash
+lt ports check <port>
+```
+
+**Exit codes:**
+| Code | Meaning |
+|------|---------|
+| `0` | Port is free |
+| `1` | Port is in use |
+| `2` | `lsof` not available, or `<port>` argument missing/invalid |
+
+**Example:**
+```bash
+if lt ports check 3000; then
+  echo "API port free"
+else
+  echo "API port already bound"
+fi
+```
+
+---
+
+### `lt ports scan [dir]`
+
+Rebuild the registry from the filesystem. Walks the given directory (default: cwd) up to depth 3, looking for `lt.config.json` + `package.json` pairs or workspace markers (`pnpm-workspace.yaml`, `projects/`). Re-allocates a slot for new projects; preserves slots for existing entries (only refreshing the path if it moved). Writes only when the registry actually changed (no mtime churn for cloud-sync tools).
+
+**Usage:**
+```bash
+lt ports scan [dir]
+```
+
+**Examples:**
+```bash
+lt ports scan                       # scan from cwd
+lt ports scan ~/code/lenneTech      # scan a specific tree
+```
+
+Symlinks are skipped to avoid traversal loops; dotdirs and `node_modules` are not descended into.
+
+---
+
 ## Git Commands
 
 All git commands support the `--noConfirm` flag and can be configured via `defaults.noConfirm` or `commands.git.noConfirm`.
@@ -558,6 +757,82 @@ Additionally, the API's `CLAUDE.md` is patched to reflect the selected API mode
 
 **Configuration:** `commands.fullstack.*`, `defaults.noConfirm`
 
+**Auto-detection in existing workspaces:** When `lt fullstack init` runs without a name argument inside a directory that already looks like a fullstack workspace (contains `pnpm-workspace.yaml` or `projects/`), it inspects the layout and dispatches to the matching incremental command:
+
+- both `projects/api` and `projects/app` exist → refuses with a hint to use `add-api` / `add-app` directly
+- only `projects/app` exists → delegates to `lt fullstack add-api` (with all original flags forwarded)
+- only `projects/api` exists → delegates to `lt fullstack add-app`
+- neither exists → falls through to the regular new-workspace flow
+
+To force a brand-new workspace from inside an existing one, pass `--name <slug>`.
+
+---
+
+### `lt fullstack add-api`
+
+Add a NestJS API (`projects/api/`) to an existing fullstack workspace that currently only contains a frontend (`projects/app/`). Mirrors every API-related flag from `lt fullstack init` so configuration stays consistent across both flows.
+
+**Usage:**
+```bash
+lt fullstack add-api [options]
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--api-mode <mode>` | API mode: `Rest`, `GraphQL`, or `Both` |
+| `--framework-mode <mode>` | Backend framework consumption mode: `npm` (classic) or `vendor` (core copied to `src/core/`) |
+| `--framework-upstream-branch <ref>` | Upstream `nest-server` branch/tag/commit to vendor (only with `--framework-mode vendor`) |
+| `--api-branch <branch>` | Branch of `nest-server-starter` to clone |
+| `--api-copy <path>` | Copy API from a local template directory |
+| `--api-link <path>` | Symlink API to a local template directory (fastest, changes affect original) |
+| `--next` | **Experimental:** clone [`nest-base`](https://github.com/lenneTech/nest-base) (Bun + Prisma 7 + Postgres + Better-Auth) instead of `nest-server-starter`. Forces `--api-mode Rest` and `--framework-mode npm`, runs `bun run rename` post-clone, skips workspace install. |
+| `--workspace-dir <path>` | Workspace root. When omitted, defaults to cwd; if cwd is not a workspace, the command walks up until it finds one (so it works from inside `projects/api/src/`). |
+| `--skip-install` | Skip `pnpm install` and the post-install format pass |
+| `--dry-run` | Print the resolved plan without making any changes |
+| `--noConfirm` | Skip all interactive prompts |
+
+**Refusal cases:**
+- `projects/api/` already exists → suggests `lt fullstack init` in a fresh directory
+- no workspace detected at the target path → asks the user to run `lt fullstack init` first
+
+**Side effects:** writes `projects/api/lt.config.json` with the resolved `apiMode` + `frameworkMode`, hoists workspace-scoped `pnpm.overrides` from sub-projects to the root, runs `pnpm install` + `oxfmt` on the new sub-project (unless `--skip-install` is set).
+
+**Configuration:** Reads `commands.fullstack.*` (same keys as `lt fullstack init`).
+
+---
+
+### `lt fullstack add-app`
+
+Add a frontend app (`projects/app/`) to an existing fullstack workspace that currently only contains an API (`projects/api/`). Mirrors every frontend-related flag from `lt fullstack init`.
+
+**Usage:**
+```bash
+lt fullstack add-app [options]
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--frontend <type>` | Frontend framework: `nuxt` or `angular` |
+| `--frontend-framework-mode <mode>` | Frontend framework consumption mode: `npm` or `vendor` (nuxt-extensions copied to `app/core/`) |
+| `--frontend-branch <branch>` | Branch of the frontend starter to clone (`ng-base-starter` or `nuxt-base-starter`) |
+| `--frontend-copy <path>` | Copy frontend from a local template directory |
+| `--frontend-link <path>` | Symlink frontend to a local template directory (fastest, changes affect original) |
+| `--next` | Default the nuxt-base-starter ref to the `next` branch (auth `basePath` aligned with the experimental `--next` API) |
+| `--workspace-dir <path>` | Workspace root. When omitted, defaults to cwd; if cwd is not a workspace, the command walks up until it finds one (so it works from inside `projects/api/src/`). |
+| `--skip-install` | Skip `pnpm install` and the post-install format pass |
+| `--dry-run` | Print the resolved plan without making any changes |
+| `--noConfirm` | Skip all interactive prompts |
+
+**Refusal cases:**
+- `projects/app/` already exists → suggests `lt fullstack init` in a fresh directory
+- no workspace detected at the target path → asks the user to run `lt fullstack init` first
+
+**Side effects:** patches `projects/app/.env` with a project-specific `NUXT_PUBLIC_STORAGE_PREFIX`, optionally vendorizes `nuxt-extensions` into `app/core/`, hoists workspace-scoped `pnpm.overrides`, runs `pnpm install` + `oxfmt` on the new sub-project (unless `--skip-install` is set).
+
+**Configuration:** Reads `commands.fullstack.*` (same keys as `lt fullstack init`).
+
 ---
 
 ### `lt fullstack convert-mode`
@@ -689,7 +964,7 @@ lt npm update
 
 ### `lt frontend angular`
 
-Creates a new Angular workspace using ng-base-starter.
+Creates a new standalone Angular workspace using ng-base-starter. For an in-workspace app, prefer [`lt fullstack add-app --frontend angular`](#lt-fullstack-add-app).
 
 **Usage:**
 ```bash
@@ -699,21 +974,26 @@ lt frontend angular [name] [options]
 **Options:**
 | Option | Description |
 |--------|-------------|
+| `--name <name>` | Workspace name (preferred over the positional argument) |
 | `--branch <branch>` / `-b` | Branch of ng-base-starter to use as template |
 | `--copy <path>` / `-c` | Copy from local template directory instead of cloning |
 | `--link <path>` | Symlink to local template directory (fastest, changes affect original) |
 | `--localize` | Enable Angular localize |
 | `--noLocalize` | Disable Angular localize |
 | `--gitLink <url>` | Git repository URL to link |
+| `--dry-run` | Print the resolved plan and exit without making any changes |
+| `--force` | Override the workspace-detection abort under `--noConfirm` |
 | `--noConfirm` / `-y` | Skip confirmation prompts |
 
+**Workspace-awareness:** Inside a fullstack workspace the command is interactive (confirm prompt), but under `--noConfirm` it **refuses** with exit code 1 and points the caller to `lt fullstack add-app --frontend angular`. Pass `--noConfirm --force` to override (rare).
+
 **Configuration:** `commands.frontend.angular.*`, `defaults.noConfirm`
 
 ---
 
 ### `lt frontend nuxt`
 
-Creates a new Nuxt workspace using nuxt-base-starter.
+Creates a new standalone Nuxt workspace using nuxt-base-starter. For an in-workspace app, prefer [`lt fullstack add-app --frontend nuxt`](#lt-fullstack-add-app).
 
 **Usage:**
 ```bash
@@ -723,16 +1003,24 @@ lt frontend nuxt [options]
 **Options:**
 | Option | Description |
 |--------|-------------|
+| `--name <name>` | Workspace name |
 | `--branch <branch>` / `-b` | Branch of nuxt-base-starter to use (uses git clone instead of create-nuxt-base) |
 | `--copy <path>` / `-c` | Copy from local template directory instead of cloning |
 | `--link <path>` | Symlink to local template directory (fastest, changes affect original) |
+| `--frontend-framework-mode <npm\|vendor>` | Frontend framework consumption mode (`vendor` copies `nuxt-extensions` into `app/core/`) |
+| `--next` | Default branch to `nuxt-base-starter#next` (auth `basePath` aligned with the experimental `--next` API) |
+| `--dry-run` | Print the resolved plan and exit without making any changes |
+| `--force` | Override the workspace-detection abort under `--noConfirm` |
+| `--noConfirm` | Skip confirmation prompts (requires `--name`) |
 
 **Note:** For `--copy` and `--link`, specify the path to the `nuxt-base-template/` subdirectory, not the repository root:
 ```bash
 lt frontend nuxt --copy /path/to/nuxt-base-starter/nuxt-base-template
 ```
 
-**Configuration:** `commands.frontend.nuxt.*`
+**Workspace-awareness:** Inside a fullstack workspace the command is interactive (confirm prompt), but under `--noConfirm` it **refuses** with exit code 1 and points the caller to `lt fullstack add-app --frontend nuxt`. Pass `--noConfirm --force` to override (rare).
+
+**Configuration:** `commands.frontend.nuxt.*`, `commands.fullstack.frontendFrameworkMode` (shared with `init` / `add-app`)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/cli",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "description": "lenne.Tech CLI: lt",
   "keywords": [
     "lenne.Tech",
@@ -31,6 +31,7 @@
     "coverage": "jest --coverage",
     "test:vendor-init": "bash scripts/test-vendor-init.sh",
     "test:frontend-vendor-init": "bash scripts/test-frontend-vendor-init.sh",
+    "test:incremental-fullstack": "bash scripts/test-incremental-fullstack.sh",
     "format": "prettier --write 'src/**/*.{js,ts,tsx,json}' '!src/templates/**/*'",
     "lint": "eslint './src/**/*.{ts,js,vue}'",
     "lint:fix": "eslint './src/**/*.{ts,js,vue}' --fix",
@@ -57,16 +58,16 @@
     "bin"
   ],
   "dependencies": {
-    "@aws-sdk/client-s3": "3.1032.0",
+    "@aws-sdk/client-s3": "3.1045.0",
     "@lenne.tech/cli-plugin-helper": "0.0.14",
-    "axios": "1.15.0",
+    "axios": "1.16.0",
     "bcrypt": "6.0.0",
-    "defuddle": "0.17.0",
+    "defuddle": "0.18.1",
     "glob": "13.0.6",
     "gluegun": "5.2.2",
     "js-sha256": "0.11.1",
     "js-yaml": "4.1.1",
-    "jsdom": "29.0.2",
+    "jsdom": "29.1.1",
     "lodash": "4.18.1",
     "open": "11.0.0",
     "playwright-core": "1.59.1",
@@ -84,15 +85,12 @@
     "@types/js-yaml": "4.0.9",
     "@types/jsdom": "28.0.1",
     "@types/lodash": "4.17.24",
-    "@types/node": "25.6.0",
+    "@types/node": "25.6.2",
     "@types/turndown": "5.0.6",
-    "@typescript-eslint/eslint-plugin": "8.58.2",
-    "@typescript-eslint/parser": "8.58.2",
     "ejs": "5.0.2",
     "eslint": "9.39.4",
-    "eslint-config-prettier": "10.1.8",
     "husky": "9.1.7",
-    "jest": "30.3.0",
+    "jest": "30.4.2",
     "prettier": "3.8.3",
     "rimraf": "6.1.3",
     "standard-version": "9.5.0",