@lenne.tech/cli 1.20.0 → 1.21.0

package/build/lib/port-registry.js

@@ -0,0 +1,304 @@
+"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 });
+exports.SLOT_PORT_RANGE_END = exports.SLOT_MAX = exports.SLOT_STEP = exports.SLOT_BASE_API = void 0;
+exports.allocatedSlots = allocatedSlots;
+exports.allocateSlot = allocateSlot;
+exports.checkPortInUse = checkPortInUse;
+exports.clearLocalState = clearLocalState;
+exports.isPidAlive = isPidAlive;
+exports.isValidPid = isValidPid;
+exports.listenSnapshot = listenSnapshot;
+exports.loadLocalState = loadLocalState;
+exports.loadRegistry = loadRegistry;
+exports.localStatePath = localStatePath;
+exports.portsForSlot = portsForSlot;
+exports.projectSlug = projectSlug;
+exports.registryPath = registryPath;
+exports.saveLocalState = saveLocalState;
+exports.saveRegistry = saveRegistry;
+exports.slotFromSlug = slotFromSlug;
+/**
+ * Port registry helpers for `lt local` and `lt ports`.
+ *
+ * Provides:
+ * - Deterministic slot allocation from a project slug (hash-based, reproducible across machines)
+ * - Persistent registry at ~/.lenneTech/ports.json
+ * - Live port introspection via `lsof` (single-call snapshot for batch checks)
+ * - Process state tracking under <project>/.lt-local/state.json
+ */
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+/** Lowest API port: slot 0 maps to 3000/3001, slot 1 to 3010/3011, … */
+exports.SLOT_BASE_API = 3000;
+/** Distance between two adjacent slots' API ports. */
+exports.SLOT_STEP = 10;
+/** Number of slots [0..SLOT_MAX). API range = [SLOT_BASE_API, SLOT_BASE_API + SLOT_MAX*SLOT_STEP). */
+exports.SLOT_MAX = 90;
+/** Highest port (exclusive) covered by the slot range. Useful for live-port sweeps. */
+exports.SLOT_PORT_RANGE_END = exports.SLOT_BASE_API + exports.SLOT_MAX * exports.SLOT_STEP;
+/** All currently allocated slots in the registry. */
+function allocatedSlots(registry) {
+    return new Set(Object.values(registry.projects).map((p) => p.slot));
+}
+/**
+ * Allocate a slot for a project. Returns deterministic slot from slug if free,
+ * otherwise scans linearly until a free slot is found. Throws if all are taken.
+ *
+ * The linear scan loops `i in [1, SLOT_MAX)` (not `<=`) because `i = 0` is the
+ * preferred slot already checked in the fast path above.
+ */
+function allocateSlot(slug, registry) {
+    const taken = allocatedSlots(registry);
+    const preferred = slotFromSlug(slug);
+    if (!taken.has(preferred)) {
+        return preferred;
+    }
+    for (let i = 1; i < exports.SLOT_MAX; i++) {
+        const candidate = (preferred + i) % exports.SLOT_MAX;
+        if (!taken.has(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error('No free port slot available (all 90 slots are taken).');
+}
+/**
+ * Check via `lsof` whether a single TCP port is currently bound by a LISTEN socket.
+ *
+ * For multi-port checks prefer {@link listenSnapshot} — it issues a single `lsof`
+ * call instead of one per port (~50ms vs ~50ms × N).
+ *
+ * Note: `-iTCP:<port>` selects connections by *service port* — both LISTEN
+ * sockets and remote endpoints. We filter explicitly to LISTEN via
+ * `-sTCP:LISTEN` AND post-filter the NAME column for `*:<port>` /
+ * `<addr>:<port>` (LISTEN) so outgoing connections whose remote port is
+ * `<port>` don't trigger a false positive.
+ *
+ * Returns null if lsof is unavailable.
+ */
+function checkPortInUse(port) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return new Promise((resolve) => {
+            var _a;
+            const child = (0, child_process_1.spawn)('lsof', ['-iTCP', `-sTCP:LISTEN`, '-nP', `-iTCP:${port}`], {
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+            let out = '';
+            (_a = child.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (chunk) => (out += chunk.toString()));
+            child.on('error', () => resolve(null));
+            child.on('close', () => {
+                const lines = out.trim().split('\n').slice(1); // skip header
+                const portRe = new RegExp(`:${port}\\s+\\(LISTEN\\)\\s*$`);
+                const match = lines.find((l) => portRe.test(l));
+                if (!match) {
+                    resolve({ inUse: false });
+                    return;
+                }
+                const cols = match.split(/\s+/);
+                resolve({ command: cols[0], inUse: true, pid: Number(cols[1]) });
+            });
+        });
+    });
+}
+/** Reset state file to an empty record. Called by `lt local down` after stopping processes. */
+function clearLocalState(projectPath) {
+    const path = localStatePath(projectPath);
+    if ((0, fs_1.existsSync)(path)) {
+        (0, fs_1.writeFileSync)(path, `${JSON.stringify({ pids: {}, ports: { api: 0, app: 0 }, startedAt: '' }, null, 2)}\n`, 'utf8');
+    }
+}
+/**
+ * Check whether a PID is still alive without sending any signal.
+ * `process.kill(pid, 0)` performs a permission check; ESRCH means dead.
+ *
+ * Refuses non-positive / non-integer PIDs to prevent accidental probes
+ * of process groups (negative PID) or every user-owned process (PID 0/-1).
+ */
+function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+/**
+ * Validate a value parsed from `state.json` as a plausible PID.
+ *
+ * Accepts: positive integer in [100, 2^31 - 1] or undefined.
+ * The lower bound 100 excludes init / kernel / login PIDs that should
+ * never be the result of a `pnpm start` spawn.
+ */
+function isValidPid(value) {
+    if (value === undefined)
+        return true;
+    if (typeof value !== 'number')
+        return false;
+    return Number.isInteger(value) && value >= 100 && value <= 0x7fffffff;
+}
+/**
+ * One-shot listener snapshot for an arbitrary set of ports.
+ *
+ * Issues a single `lsof -iTCP -sTCP:LISTEN -nP` call and filters in memory.
+ * ~50ms total regardless of port count, vs ~50ms × N for sequential
+ * {@link checkPortInUse} calls.
+ *
+ * Returns an empty Map if `lsof` is unavailable.
+ */
+function listenSnapshot(ports) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return new Promise((resolve) => {
+            var _a;
+            const child = (0, child_process_1.spawn)('lsof', ['-iTCP', '-sTCP:LISTEN', '-nP'], { stdio: ['ignore', 'pipe', 'ignore'] });
+            let out = '';
+            (_a = child.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (chunk) => (out += chunk.toString()));
+            child.on('error', () => resolve(new Map()));
+            child.on('close', () => {
+                const wanted = new Set(ports);
+                const result = new Map();
+                const lines = out.trim().split('\n').slice(1);
+                const re = /:(\d+)\s+\(LISTEN\)\s*$/;
+                for (const line of lines) {
+                    const m = re.exec(line);
+                    if (!m)
+                        continue;
+                    const port = Number(m[1]);
+                    if (!wanted.has(port))
+                        continue;
+                    if (result.has(port))
+                        continue; // first hit wins (IPv4 before IPv6)
+                    const cols = line.split(/\s+/);
+                    result.set(port, { command: cols[0], pid: Number(cols[1]) });
+                }
+                resolve(result);
+            });
+        });
+    });
+}
+/**
+ * Load the local state JSON for a project.
+ *
+ * Returns null when the file is missing, unreadable, malformed, or contains
+ * structurally invalid data (see {@link isValidPid}). The schema validation
+ * here is the authoritative gate: it prevents `process.kill(-pid, …)` in
+ * `lt local down` from receiving anything but a plausible PID we ourselves
+ * could have written.
+ */
+function loadLocalState(projectPath) {
+    const path = localStatePath(projectPath);
+    if (!(0, fs_1.existsSync)(path))
+        return null;
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)(path, 'utf8'));
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        const obj = parsed;
+        const pids = obj.pids;
+        const ports = obj.ports;
+        if (!pids || typeof pids !== 'object' || !ports || typeof ports !== 'object')
+            return null;
+        if (!isValidPid(pids.api) || !isValidPid(pids.app))
+            return null;
+        if (typeof ports.api !== 'number' || typeof ports.app !== 'number')
+            return null;
+        if (typeof obj.startedAt !== 'string')
+            return null;
+        return {
+            pids: { api: pids.api, app: pids.app },
+            ports: { api: ports.api, app: ports.app },
+            startedAt: obj.startedAt,
+        };
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/**
+ * Load registry; returns empty if missing or corrupt.
+ *
+ * Prints a warning when a corrupt or schema-incompatible file is encountered
+ * so the user notices the silent reset rather than discovering stale port
+ * allocations later.
+ */
+function loadRegistry() {
+    const path = registryPath();
+    if (!(0, fs_1.existsSync)(path)) {
+        return { projects: {}, version: 1 };
+    }
+    try {
+        const raw = (0, fs_1.readFileSync)(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if ((parsed === null || parsed === void 0 ? void 0 : parsed.version) !== 1 || typeof (parsed === null || parsed === void 0 ? void 0 : parsed.projects) !== 'object') {
+            console.warn(`[lt] ports.json has wrong schema (got version=${parsed === null || parsed === void 0 ? void 0 : parsed.version}); starting with empty registry.`);
+            return { projects: {}, version: 1 };
+        }
+        return parsed;
+    }
+    catch (e) {
+        console.warn(`[lt] ports.json was unreadable (${e.message}); starting with empty registry.`);
+        return { projects: {}, version: 1 };
+    }
+}
+/** Path to the local state file inside a project. */
+function localStatePath(projectPath) {
+    return (0, path_1.join)(projectPath, '.lt-local', 'state.json');
+}
+/** Convert a slot to its API+App port pair. */
+function portsForSlot(slot) {
+    const api = exports.SLOT_BASE_API + slot * exports.SLOT_STEP;
+    return { api, app: api + 1 };
+}
+/** Convert any project path → a stable slug (basename, lowercase, alpha-num + dashes). */
+function projectSlug(projectPath) {
+    const base = projectPath.replace(/\/+$/, '').split('/').pop() || 'project';
+    return base
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * Path to the central registry.
+ *
+ * Honors `LT_PORTS_REGISTRY_PATH` for tests / non-default workspaces;
+ * falls back to `~/.lenneTech/ports.json`.
+ */
+function registryPath() {
+    return process.env.LT_PORTS_REGISTRY_PATH || (0, path_1.join)((0, os_1.homedir)(), '.lenneTech', 'ports.json');
+}
+/** Persist local state to <project>/.lt-local/state.json (creates the parent directory if needed). */
+function saveLocalState(projectPath, state) {
+    const path = localStatePath(projectPath);
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(path), { recursive: true });
+    (0, fs_1.writeFileSync)(path, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+/** Save registry, creating parent directory if needed. */
+function saveRegistry(registry) {
+    const path = registryPath();
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(path), { recursive: true });
+    (0, fs_1.writeFileSync)(path, `${JSON.stringify(registry, null, 2)}\n`, 'utf8');
+}
+/**
+ * Deterministic slot from project slug — same slug yields the same slot on every machine.
+ * Uses the lower 32 bits of FNV-1a then modulo SLOT_MAX.
+ */
+function slotFromSlug(slug) {
+    let hash = 2166136261; // FNV-1a 32-bit offset basis
+    for (let i = 0; i < slug.length; i++) {
+        hash ^= slug.charCodeAt(i);
+        hash = Math.imul(hash, 16777619);
+    }
+    return Math.abs(hash | 0) % exports.SLOT_MAX;
+}

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,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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/cli",
-  "version": "1.20.0",
+  "version": "1.21.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",