@lenne.tech/cli 1.20.0 → 1.22.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)
@@ -282,6 +284,206 @@ For mode-aware update workflows after conversion, use:
 
 ---
 
+## Local Development Commands
+
+Run multiple lt projects in parallel without port collisions or cross-wiring.
+**URL-first**: every project gets stable HTTPS URLs (`<slug>.localhost`,
+`api.<slug>.localhost`) served by Caddy. Internal ports are opaque and
+auto-allocated. Cross-project state (database, storage, cookies) is
+namespaced by slug so projects cannot accidentally interfere.
+
+### `lt dev`
+
+Open the local-orchestration submenu.
+
+**Usage:**
+```bash
+lt dev
+```
+
+**Alias:** `lt d`
+
+---
+
+### `lt dev install`
+
+One-time per-machine setup. Idempotent — re-run anytime to diagnose what's missing.
+
+**Usage:**
+```bash
+lt dev install
+```
+
+**Alias:** `lt d i`
+
+**What it does:**
+1. Verifies `caddy` is on PATH (suggests `brew install caddy` if missing).
+2. Creates `~/.lenneTech/Caddyfile` stub if absent.
+3. Verifies the Caddy daemon is running (suggests `brew services start caddy`).
+4. Validates the Caddyfile.
+5. Reminds you to run `sudo caddy trust` once so browsers accept `https://*.localhost`.
+
+---
+
+### `lt dev migrate`
+
+Register an existing project with `lt dev` and apply idempotent env-aware patches. Safe to run multiple times; safe to run after `lt fullstack init`.
+
+**Usage:**
+```bash
+lt dev migrate
+```
+
+**Alias:** `lt d m`
+
+**What it does:**
+1. Detects the workspace layout (monorepo `projects/api`+`projects/app`, or standalone).
+2. Builds the project identity (slug from `package.json` "name", subdomains).
+3. Patches legacy hardcoded ports in `config.env.ts` (`port: 3000`), `nuxt.config.ts` (`port: 3001`, vite proxy target), `playwright.config.ts` (`baseURL`/`host`/`url`) to env-overridable form. Defaults preserved, idempotent.
+4. Persists the entry to `~/.lenneTech/projects.json` (override path via `LT_DEV_REGISTRY_PATH`).
+5. Adds `.lt-dev/` to the project's `.gitignore`.
+6. Injects (or refreshes) a "Local Development (lt dev)" URL block into `CLAUDE.md` files at the workspace root and inside each subproject — bracketed by HTML comment markers.
+
+---
+
+### `lt dev up`
+
+Start API + App behind Caddy. Allocates internal ports (4000+), spawns processes detached, persists PIDs to `<root>/.lt-dev/state.json`.
+
+**Usage:**
+```bash
+lt dev up
+```
+
+**Alias:** `lt d u`
+
+**Environment variables injected:**
+| Variable | Consumer | Example value |
+|----------|----------|---------------|
+| `PORT` | Nest (api) / Nuxt (app) | auto-allocated 4000+ |
+| `BASE_URL` / `NSC__BASE_URL` | nest-server canonical API URL | `https://api.crm.localhost` |
+| `APP_URL` / `NSC__APP_URL` | nest-server frontend origin (CORS, BetterAuth) | `https://crm.localhost` |
+| `NUXT_API_URL` | Nuxt vite-proxy target for `/api`, `/iam`, … | `https://api.crm.localhost` |
+| `NUXT_PUBLIC_API_URL` | Nuxt `useRuntimeConfig().public.apiUrl` | `https://api.crm.localhost` |
+| `NUXT_PUBLIC_SITE_URL` | Nuxt `useRuntimeConfig().public.siteUrl` + Playwright | `https://crm.localhost` |
+| `NUXT_PUBLIC_STORAGE_PREFIX` | namespaces sessionStorage/localStorage | `crm` |
+| `NUXT_PUBLIC_API_PROXY` | always `false` — Caddy + cookie-domain make it obsolete | `false` |
+| `NSC__MONGOOSE__URI` | nest-server Mongoose URI | `mongodb://127.0.0.1/crm-local` |
+| `DATABASE_URL` | Postgres convenience URL (for nest-base-style projects) | `postgresql://crm-local:crm-local@localhost:5432/crm-local` |
+
+**Override the binary** for both spawns via `LT_PNPM_BIN` (e.g. `LT_PNPM_BIN=/usr/local/bin/pnpm lt dev up`).
+
+**Pre-flight guards (exit code 1 each):**
+- Caddy not installed (`lt dev install` first)
+- Caddy daemon not running (`brew services start caddy`)
+- Already running for this project (`lt dev down` first)
+- Internal port already in use
+
+**Logs:** `<root>/.lt-dev/api.log`, `<root>/.lt-dev/app.log` (append-mode).
+
+---
+
+### `lt dev down`
+
+Stop processes started by `lt dev up` and remove the project's Caddy block.
+
+**Usage:**
+```bash
+lt dev down
+```
+
+**Alias:** `lt d d`
+
+Sends `SIGTERM` to the detached process group (negative PID) so descendants — Vite, the Nest watcher, etc. — receive the signal too. PID values from `state.json` are validated before signaling. Best-effort: removes the project's Caddy block and reloads even if no session was active.
+
+---
+
+### `lt dev status`
+
+Show what is registered + running.
+
+**Usage:**
+```bash
+lt dev status         # current project
+lt dev status --all   # every project in the registry
+```
+
+**Alias:** `lt d s`
+
+The current-project view shows subdomains → upstream ports, db URI, session PIDs (alive/dead), and live `lsof` state. The `--all` view lists every project, with a `●`/`○` indicator for running state.
+
+---
+
+### `lt dev doctor`
+
+Diagnose Caddy / CA / DNS / port issues. Exit code 0 = all green, 1 = at least one FAIL.
+
+**Usage:**
+```bash
+lt dev doctor
+```
+
+**Alias:** `lt d doc`
+
+**Checks:**
+1. `caddy` on PATH
+2. Caddy daemon running (admin endpoint `:2019` reachable)
+3. Caddyfile validates
+4. Ports 80 + 443 free or held by Caddy
+5. `*.localhost` resolves to `127.0.0.1` (RFC 6761)
+6. Registry status
+
+---
+
+### `lt dev test`
+
+One-shot E2E wrapper: ensure `up`, wait for the App URL, run `pnpm run test:e2e` with the `.lt-dev/.env` bridge loaded. Optional teardown after.
+
+**Usage:**
+```bash
+lt dev test                      # App E2E (projects/app)
+lt dev test --api                # API E2E (projects/api) — no Caddy required
+lt dev test --teardown           # plus `lt dev down` after
+lt dev test --debug              # PWDEBUG=1 + HEADED=1
+lt dev test -- --ui spec.ts      # everything after `--` is forwarded to playwright
+```
+
+**Alias:** `lt d t`
+
+**Behaviour:**
+1. Pre-flight: Caddy installed + daemon running (App mode only).
+2. If no `lt dev up` session is alive: invokes `lt dev up` first.
+3. Waits up to 30 s for the App URL to respond.
+4. Reads `<root>/.lt-dev/.env` and merges into the spawn env (existing process.env wins for keys it defines).
+5. Spawns `pnpm run test:e2e [forwarded args]` in `projects/api` (with `--api`) or `projects/app` (default).
+6. With `--teardown`, runs `lt dev down` after.
+
+**When to use this vs. `pnpm run test:e2e` directly:**
+- Use **`lt dev test`** for TDD loops, ad-hoc reproduction, or when you want a single-command "ensure-up + run + teardown" flow.
+- Use **direct `pnpm run test:e2e`** (or VS Code Playwright Extension, IDE test runners) for everyday work — the auto-injected `playwright.config.ts` bridge loads the `.lt-dev/.env` automatically, so the env is correct without the wrapper.
+
+---
+
+### ENV bridge for external test runners
+
+`lt dev up` writes a `<root>/.lt-dev/.env` file with the following keys:
+
+| Key | Source |
+|-----|--------|
+| `BASE_URL`, `APP_URL`, `NSC__BASE_URL`, `NSC__APP_URL` | Identity → `https://api.<slug>.localhost` / `https://<slug>.localhost` |
+| `NUXT_API_URL`, `NUXT_PUBLIC_API_URL`, `NUXT_PUBLIC_SITE_URL` | Same URLs for Nuxt |
+| `NUXT_PUBLIC_STORAGE_PREFIX` | Project slug |
+| `NUXT_PUBLIC_API_PROXY` | Always `false` under `lt dev` |
+| `NSC__MONGOOSE__URI`, `DATABASE_URL` | Project-namespaced DB URI (when `dbName` known) |
+| `LT_DEV_ACTIVE`, `LT_DEV_DB_NAME` | Marker keys for consumers |
+| `NODE_EXTRA_CA_CERTS` | Path to Caddy's root CA cert (auto-detected) |
+
+`lt dev migrate` injects a tiny `// >>> lt-dev:bridge >>>` block at the top of `playwright.config.ts` that loads this file at config-load time — making Playwright (CLI, IDE, VS Code extension) automatically use the `lt dev` URLs and trust the local CA, without inheriting the parent shell.
+
+`lt dev down` removes the bridge file so subsequent runs without `lt dev up` fall back cleanly to the classic `localhost:3000`/`localhost:3001` defaults.
+
+---
+
 ## Git Commands
 
 All git commands support the `--noConfirm` flag and can be configured via `defaults.noConfirm` or `commands.git.noConfirm`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/cli",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "lenne.Tech CLI: lt",
   "keywords": [
     "lenne.Tech",
@@ -58,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",
@@ -85,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",