localdeck 1.0.0 → 1.0.2

package/dist/index.js

@@ -27,7 +27,7 @@ import {
   stripAnsi,
   waitForReadiness,
   wrapper_default
-} from "./index-3npyta7k.js";
+} from "./index-eyb4mz5b.js";
 
 // src/index.ts
 import { spawn as spawn2 } from "node:child_process";
@@ -175,9 +175,7 @@ async function startService(opts, overrides = {}) {
     console.log(`${tag}${c.bold("LocalDeck")} ${c.dim("›")} ${paint(service.name)} ${c.dim("→")} ${c.green(appUrl)} ${c.dim(`(also ${service.urls[1]} · dashboard http://localhost:${daemon.apiPort})`)}`);
   }
   const posix = process.platform !== "win32";
-  const child = dependencies.spawn(argv[0], argv.slice(1), { cwd, env, stdio: [opts.prefix ? "ignore" : "inherit", "pipe", "pipe"], shell: !posix, detached: posix });
-  if (child.pid)
-    send({ type: "pid", pid: child.pid });
+  let child;
   const pipe = (stream, name, out) => {
     stream.on("data", (chunk) => {
       if (opts.prefix) {
@@ -192,8 +190,6 @@ async function startService(opts, overrides = {}) {
         send({ type: "log", stream: name, line: part });
     });
   };
-  pipe(child.stdout, "stdout", process.stdout);
-  pipe(child.stderr, "stderr", process.stderr);
   let hinted = false;
   let recentOutput = "";
   const hintOnPortClash = (chunk) => {
@@ -206,34 +202,11 @@ async function startService(opts, overrides = {}) {
       console.error(`${tag}${c.yellow(`  Fix: run without --port (LocalDeck finds the tool's own port automatically), or pick a different stable port, e.g. --port ${service.stablePort + 1000}.`)}`);
     }
   };
-  child.stdout.on("data", hintOnPortClash);
-  child.stderr.on("data", hintOnPortClash);
   let detectTimer;
   let reported;
-  if (!opts.upstreamPort && child.pid) {
-    const rootPid = child.pid;
-    let idle = 0;
-    const tick = async () => {
-      if (child.exitCode !== null || child.signalCode)
-        return;
-      try {
-        const listeners = await listeningPorts(await processTree(rootPid));
-        const pick = chooseUpstream(listeners, upstreamPort);
-        if (pick) {
-          const key = `${connectHost(pick)}:${pick.port}`;
-          if (key !== reported) {
-            reported = key;
-            send({ type: "upstream", port: pick.port, host: connectHost(pick) });
-            if (pick.port !== upstreamPort)
-              console.log(`${tag}${c.dim(`LocalDeck: process is listening on ${key} (ignored $PORT) — ${service.urls[0]} now points there`)}`);
-          }
-          idle++;
-        }
-      } catch {}
-      detectTimer = setTimeout(tick, reported ? Math.min(2000 + idle * 500, 1e4) : 400);
-    };
-    detectTimer = setTimeout(tick, 300);
-  }
+  let retryTimer;
+  let retryAttempts = 0;
+  let finalizing = false;
   let stopping = false;
   let cleanupPromise;
   let leaderExit;
@@ -244,20 +217,49 @@ async function startService(opts, overrides = {}) {
   });
   const cleanup = (signal) => cleanupPromise ??= cleanupTerminalTree(child, signal);
   const finishAfterCleanup = async (signal) => {
-    if (finished || !leaderExit)
+    if (finished || finalizing || !leaderExit)
       return;
+    finalizing = true;
     if (!await cleanup(signal)) {
       cleanupPromise = undefined;
+      finalizing = false;
       stopping = false;
       console.error(`${tag}${c.red(`LocalDeck: process descendants survived cleanup; retry Stop`)}`);
       return;
     }
     if (finished)
       return;
-    finished = true;
     if (detectTimer)
       clearTimeout(detectTimer);
     send({ type: "log", stream: "stderr", line: `process exited (${leaderExit.signal ?? `code ${leaderExit.code}`})` });
+    const interrupted = ["SIGINT", "SIGTERM", "SIGHUP"].includes(leaderExit.signal ?? "") || [130, 143, 129].includes(leaderExit.code ?? -1);
+    if (!stopping && !interrupted && retryAttempts < 3 && ws.readyState === wrapper_default.OPEN) {
+      const message = `LocalDeck: restarting in ${(dependencies.retryDelayMs ?? 3000) / 1000} seconds (attempt ${++retryAttempts}/3)`;
+      console.log(`${tag}${c.yellow(message)}`);
+      send({ type: "log", stream: "stderr", line: message });
+      send({ type: "readiness", status: "checking", message });
+      retryTimer = setTimeout(() => {
+        retryTimer = undefined;
+        if (stopping || finished)
+          return;
+        try {
+          launch();
+        } catch (error) {
+          finished = true;
+          console.error(`${tag}${c.red(`LocalDeck: restart failed: ${error instanceof Error ? error.message : error}`)}`);
+          ws.close();
+          resolveDone(1);
+        }
+      }, dependencies.retryDelayMs ?? 3000);
+      finalizing = false;
+      return;
+    }
+    if (!stopping && !interrupted && retryAttempts === 3) {
+      const message = "LocalDeck: automatic restart limit reached (3/3). Start the service manually to try again.";
+      console.error(`${tag}${c.red(message)}`);
+      send({ type: "log", stream: "stderr", line: message });
+    }
+    finished = true;
     setTimeout(() => {
       ws.close();
       resolveDone(leaderExit.code ?? (leaderExit.signal ? 1 : 0));
@@ -267,6 +269,10 @@ async function startService(opts, overrides = {}) {
     if (finished || stopping)
       return;
     stopping = true;
+    if (retryTimer) {
+      clearTimeout(retryTimer);
+      retryTimer = undefined;
+    }
     cleanup(signal).then(() => finishAfterCleanup(signal));
   };
   ws.on("message", (raw) => {
@@ -280,29 +286,77 @@ async function startService(opts, overrides = {}) {
     }
   });
   ws.on("close", () => {
-    if (!stopping)
+    if (retryTimer) {
+      stop();
+      return;
+    }
+    if (!stopping && !finished)
       console.error(`${tag}${c.yellow("LocalDeck: lost connection to daemon; the stable port is no longer proxied. Process keeps running.")}`);
   });
-  child.on("exit", (code, signal) => {
-    if (code !== 0 && !hinted) {
-      const guidance = startupGuidance(recentOutput);
-      if (guidance)
-        console.error(`${tag}${c.yellow(["LocalDeck: " + guidance.title, ...guidance.steps].join(`
-`))}`);
+  function launch() {
+    leaderExit = undefined;
+    cleanupPromise = undefined;
+    finalizing = false;
+    reported = undefined;
+    recentOutput = "";
+    hinted = false;
+    child = dependencies.spawn(argv[0], argv.slice(1), { cwd, env, stdio: [opts.prefix ? "ignore" : "inherit", "pipe", "pipe"], shell: !posix, detached: posix });
+    if (child.pid)
+      send({ type: "pid", pid: child.pid });
+    pipe(child.stdout, "stdout", process.stdout);
+    pipe(child.stderr, "stderr", process.stderr);
+    child.stdout.on("data", hintOnPortClash);
+    child.stderr.on("data", hintOnPortClash);
+    if (!opts.upstreamPort && child.pid) {
+      const detectedChild = child;
+      const rootPid = child.pid;
+      let idle = 0;
+      const tick = async () => {
+        if (child !== detectedChild || child.exitCode !== null || child.signalCode)
+          return;
+        try {
+          const listeners = await listeningPorts(await processTree(rootPid));
+          const pick = chooseUpstream(listeners, upstreamPort);
+          if (pick) {
+            const key = `${connectHost(pick)}:${pick.port}`;
+            if (key !== reported) {
+              reported = key;
+              send({ type: "upstream", port: pick.port, host: connectHost(pick) });
+              if (pick.port !== upstreamPort)
+                console.log(`${tag}${c.dim(`LocalDeck: process is listening on ${key} (ignored $PORT) — ${service.urls[0]} now points there`)}`);
+            }
+            idle++;
+          }
+        } catch {}
+        if (child !== detectedChild || child.exitCode !== null || stopping || leaderExit)
+          return;
+        detectTimer = setTimeout(tick, reported ? Math.min(2000 + idle * 500, 1e4) : 400);
+      };
+      detectTimer = setTimeout(tick, 300);
     }
-    leaderExit = { code, signal };
-    stopping = true;
-    finishAfterCleanup("SIGTERM");
-  });
-  child.on("error", (err) => {
-    stopping = true;
-    finished = true;
-    console.error(`${tag}${c.red(`LocalDeck: failed to start "${argv[0]}": ${err.message}`)}`);
-    ws.close();
-    resolveDone(1);
-  });
+    child.on("exit", (code, signal) => {
+      if (code !== 0 && !hinted) {
+        const guidance = startupGuidance(recentOutput);
+        if (guidance)
+          console.error(`${tag}${c.yellow(["LocalDeck: " + guidance.title, ...guidance.steps].join(`
+`))}`);
+      }
+      leaderExit = { code, signal };
+      finishAfterCleanup("SIGTERM");
+    });
+    child.on("error", (err) => {
+      stopping = true;
+      finished = true;
+      console.error(`${tag}${c.red(`LocalDeck: failed to start "${argv[0]}": ${err.message}`)}`);
+      ws.close();
+      resolveDone(1);
+    });
+    if (retryAttempts > 0)
+      checkReadiness().catch(() => stop());
+  }
+  launch();
   const readiness = opts.ready;
-  const readyOperation = readiness ? (async () => {
+  const checkReadiness = () => readiness ? (async () => {
     send({ type: "readiness", status: "checking", message: readiness.type === "tcp" ? "Waiting for the service to listen" : "Running configured readiness check" });
     try {
       const ready = await waitForReadiness({
@@ -326,8 +380,11 @@ async function startService(opts, overrides = {}) {
       throw error;
     }
   })() : Promise.resolve(service);
+  const readyOperation = checkReadiness();
   readyOperation.catch(() => {});
-  return { name: opts.name, service, child, stop, done, ready: readyOperation };
+  return { name: opts.name, service, get child() {
+    return child;
+  }, stop, done, ready: readyOperation };
 }
 async function cleanupTerminalTree(child, signal) {
   await killProcessTree(child, signal);
@@ -824,7 +881,7 @@ async function main(argv, overrides = {}) {
     case "init":
       return cmdInit(rest, dependencies);
     case "mcp":
-      return (await import("./mcp-s6gapf6v.js")).runMcp(rest);
+      return (await import("./mcp-4dnef2t7.js")).runMcp(rest);
     case "doctor":
       return cmdDoctor(rest);
     case "forward":

package/dist/{mcp-s6gapf6v.js → mcp-4dnef2t7.js}

@@ -7,7 +7,7 @@ import {
   ensureDaemon,
   environmentValues,
   redactDiagnostic
-} from "./index-3npyta7k.js";
+} from "./index-eyb4mz5b.js";
 
 // ../../node_modules/.bun/ajv@8.20.0/node_modules/ajv/dist/compile/codegen/code.js
 var require_code = __commonJS((exports) => {

package/docs/commands.md

@@ -0,0 +1,94 @@
+# Command reference
+
+[Quick start](../README.md) · Development scripts · [Configuration](configuration.md)
+
+Run project commands from your app's folder or any descendant. LocalDeck searches upwards for `.localdeck`, `.localdeck.json`, or `localdeck.json`.
+
+## Set up and inspect a project
+
+| Command | What it does |
+| --- | --- |
+| `localdeck` | Shows help and, when a configuration exists, lists and remembers the project. May start the daemon to remember it. |
+| `localdeck help`, `-h`, `--h`, `--help` | Shows CLI help without starting a service. |
+| `localdeck -v`, `--v`, `--version` | Prints the installed version. |
+| `localdeck commands` | Lists configured service names, ports, dependencies, tags, and commands; remembers the project. Alias: `cmds`. |
+| `localdeck init` | Detects package-manager scripts, writes `.localdeck`, and remembers the project. Prefers `dev*` scripts per package; falls back to `start*`, `serve*`, and `preview*`. |
+| `localdeck init --dry-run` | Prints the proposed file and services without writing or starting the daemon. |
+| `localdeck init --force` | Replaces an existing configuration with the newly detected configuration. |
+| `localdeck init --name web --command 'your command'` | Creates a service using an explicit command, including non-JavaScript projects. Combine with `--dry-run` or `--force`. |
+| `localdeck init .localdeck.json` | Selects the alternate output filename. `localdeck.json` is also accepted; replacing existing configuration requires `--force`. |
+| `localdeck doctor` | Checks Node, package manager, installed dependencies, configured directories, environment variable names, stable ports, and required database tools. Does not start your services. Exits with status 1 if a check fails. |
+| `localdeck doctor --json` | Produces the same diagnostic report as JSON. |
+
+Initialization uses the nearest `package.json` directory, or the current folder when none exists. `doctor` checks whether explicitly configured stable ports are free; a port held by a service you already started is reported as occupied too.
+
+## Run services
+
+| Command | What it does |
+| --- | --- |
+| `localdeck web` | Runs the configured `web` service and its transitive prerequisites in the terminal. |
+| `localdeck up` | Runs all configured services, starting each after its own prerequisites become ready. |
+| `localdeck up frontend api` | Runs services matching any supplied name or tag, plus their prerequisites. |
+| `localdeck up --profile app` | Runs the names in the saved `app` profile and their prerequisites. Additional name/tag selectors must stay within the profile. |
+| `localdeck run web` | Runs the configured `web` service; an alternative to `localdeck web`. |
+| `localdeck run api -- node server.js` | Runs a one-off command without requiring a configuration. |
+| `localdeck run api --port 4000 --upstream 8787 -- node server.js` | Reserves stable port 4000 and explicitly proxies to upstream port 8787. Omit these flags for automatic allocation and detection. |
+
+`run` accepts `-p` for `--port`, `-u` for `--upstream`, and `--port=4000`/`--upstream=8787`. Ports must be integers from 1 to 65535. Put LocalDeck options before the application command; `--` separates the two. `localdeck run web --port 4000` overrides the configured web service's stable port for that terminal run.
+
+`{port}` inside a configured command expands to the assigned **upstream** port in both terminal and dashboard launches. `$PORT` also contains that port. The stable port is held by LocalDeck, so avoid assigning it the same port your tool insists on using.
+
+Once an automatic stable port has been remembered, an occupied port causes startup to fail with the port number. LocalDeck does not silently move it or overwrite the remembered mapping. Stop the conflicting listener or explicitly select a different stable port.
+
+Foreground services stop on Ctrl-C, including their descendant processes. Restart terminal-owned services from that terminal; dashboard Restart is reserved for daemon-owned active services. Dashboard-launched services are owned by the daemon and continue in the background. Starting a service may offer clean-URL setup during interactive use; cancellation keeps normal port-number URLs working.
+
+## Observe, stop, and share
+
+Here `<service>` may be a unique active name (`web`), a qualified reference (`my-project/web`), or an exact runtime key printed by `ps`. Project references accept an ID, name, or slug. Use an exact key to inspect retained history for a stopped service.
+
+| Command | What it does |
+| --- | --- |
+| `localdeck ps` | Lists registered services with status, project, key, stable/upstream ports, PID, request counts, share URL, age, and command. Aliases: `ls`, `ports`. Stopped entries may remain visible. |
+| `localdeck port <service>` | Prints only the stable port, for use in scripts. Database services return their published port. |
+| `localdeck logs <service>` | Shows the latest 100 captured output lines. |
+| `localdeck logs <service> -f -n 200` | Shows 200 lines, then follows live output. Long options: `--follow`, `--lines`. Ctrl-C exits the log viewer. |
+| `localdeck requests <service> -n 50` | Shows recent proxied HTTP requests: time, status, method, path, latency, origin, and errors. Defaults to 50; `--lines` is equivalent to `-n`. |
+| `localdeck stop <service>` | Stops the service process group and tears down its share. Does not automatically stop its dependencies or dependents. |
+| `localdeck open` | Starts the daemon if needed and opens the dashboard. |
+| `localdeck open <service>` | Opens a service's stable URL. Database endpoints require a database client. |
+| `localdeck share <service>` | Starts a public Cloudflare HTTPS tunnel with an automatically generated password and prints both. Requires `cloudflared`. |
+| `localdeck share <service> --password xyz` | Shares using your chosen password. |
+| `localdeck share <service> --public` | Shares without a password. Cannot be combined with `--password`. |
+| `localdeck unshare <service>` | Closes the service's public tunnel without stopping the local service. |
+
+History limits are integers from 1 to 5000. Only requests through LocalDeck's proxy are recorded. An interrupted client response is recorded once with status 499 and a disconnect error; an upstream response failure is recorded as a proxy error. Database services cannot be opened in a browser or shared. Sharing verifies public connectivity for up to two minutes. Quick Tunnel DNS delays can prevent startup; inspect the error before retrying. Sharing remains active until unshared, stopped, restarted, or the daemon shuts down.
+
+## Daemon and optional forwarding
+
+| Command | What it does |
+| --- | --- |
+| `localdeck daemon status` | Prints daemon status, PID, API URL, uptime, and data directory. |
+| `localdeck daemon start` | Starts the daemon in the background, or reuses the existing daemon. |
+| `localdeck daemon run` | Runs the daemon in the foreground; useful for development and debugging. Ctrl-C shuts it down. |
+| `localdeck daemon stop` | Requests daemon shutdown, including cleanup of managed services and shares. |
+| `localdeck forward` | Runs a foreground TCP relay from `127.0.0.1:80` to port 7777. Ctrl-C stops the relay. Does not start the daemon. |
+| `localdeck forward --to-port 8888` | Relays port 80 to a custom daemon port. Requires port 80 to be available and permission to bind it. |
+
+Normal startup handles clean URLs automatically where supported. Manual `forward` is an advanced alternative; see [clean URLs](dashboard.md#clean-urls).
+
+## Environment variables
+
+| Variable | Meaning |
+| --- | --- |
+| `LOCALDECK_HOME` | Overrides the data directory (default `~/.localdeck`), including state, remembered projects, ports, and logs. Useful for isolated tests. |
+| `LOCALDECK_PORT` when starting LocalDeck | Overrides the daemon API port (default 7777). Use the same value for the Vite dashboard development proxy. |
+| `LOCALDECK_DEV_ORIGINS` | Comma-separated exact loopback HTTP origins allowed to call the daemon from a browser. Read when the daemon starts. |
+| `LOCALDECK_CLOUDFLARED` | Overrides the `cloudflared` executable used for sharing. |
+| `NO_COLOR` | Disables CLI colors. |
+| `CI` | Suppresses interactive clean-URL preparation when set. |
+
+Child services receive `PORT` (upstream), `LOCALDECK_PORT` (stable/published port), and `LOCALDECK_SERVICE` (service name). HTTP services also receive `LOCALDECK_URL`, using a stable numeric localhost URL. These names and other `LOCALDECK_*` names are reserved in configuration `env`; see [environment wiring](configuration.md#profiles-and-environment-wiring).
+
+## MCP client connection
+
+`localdeck mcp` runs the stdio MCP server for service inspection, controls, recorded GET/HEAD replay, and quick sharing. `--project <id>` restricts every tool to one remembered project; `--help` prints usage without connecting. A tool call can start the daemon, but connecting never starts application services. Closing the client leaves services running. See [MCP setup and every tool](mcp.md).

package/docs/configuration.md

@@ -0,0 +1,64 @@
+# Project configuration
+
+[Back to quick start](../README.md) · [Commands](commands.md)
+
+JSON at the project root. `localdeck init` generates one from `package.json`; edit freely.
+
+```json
+[
+  { "name": "database", "run": "docker compose up postgres", "serviceType": "postgres", "upstream": 5432, "ready": { "type": "compose", "service": "postgres", "engine": "postgres" } },
+  { "name": "api", "run": "npm run api", "after": "database", "ready": "/health", "tag": "backend" },
+  { "name": "web", "run": "npm run dev:web", "after": "api", "port": 4000, "tag": "frontend" },
+  { "name": "docs", "run": "npm run dev", "cwd": "packages/docs" }
+]
+```
+
+- `name` — what you type: `localdeck api`. Running services receive a project-qualified hostname; the shorter `api.localhost:7777` alias works only while it is unambiguous.
+- `run` — the command, exactly as you'd type it in the terminal.
+- `port` — optional. The stable port other things should use. Without it, LocalDeck picks one (4000+) the first time and remembers it across runs.
+- `tag` — optional, string or array. `localdeck up backend` runs everything tagged `backend`.
+- `cwd` — optional, relative to the file.
+- `upstream` — optional. Only for the rare tool whose port LocalDeck can't detect; pins where to proxy.
+- `after` — optional, one service name or an array. LocalDeck starts those prerequisites first and waits until they are ready. `localdeck web` and `localdeck up frontend` automatically include transitive prerequisites.
+- `ready` — optional advanced readiness check. Without it, LocalDeck waits for its ownership-verified upstream port. Use `"/health"` for an HTTP endpoint, or one of the advanced objects below.
+- `serviceType` — `http` (default), `postgres`, `redis`, or `compose`. Database services require `upstream`, use that published port directly, and cannot set an HTTP proxy `port`. They have no browser/share links: LocalDeck does not proxy PostgreSQL or Redis traffic.
+- `env` — optional environment overrides. `PORT` and `LOCALDECK_*` are reserved. Use `{service:api:url}` or `{service:database:port}` to reference a service explicitly listed in `after`. Database port references use the actual published port; database URL references are rejected. Keep secrets in your environment, not committed config.
+
+The dashboard shows each relationship as **Starts after** and lets you edit it with checkboxes—no graph terminology or manual JSON is required. Missing names, self-dependencies, and cycles are rejected before the file changes.
+
+Advanced readiness examples:
+
+```json
+[
+  { "name": "database", "run": "docker compose up postgres", "serviceType": "postgres", "upstream": 5432, "ready": { "type": "compose", "service": "postgres", "engine": "postgres" } },
+  { "name": "api", "run": "npm run api", "after": "database", "ready": { "type": "http", "path": "/health", "status": 200 } },
+  { "name": "web", "run": "npm run web", "after": "api" }
+]
+```
+
+Readiness defaults to a 60-second timeout and a 400ms retry interval. A command check receives `PORT`, `LOCALDECK_PORT`, `LOCALDECK_SERVICE`, and `LOCALDECK_URL`; `{upstream}` expands to the process port and `{port}` to the stable port. If a prerequisite times out, LocalDeck stops it, skips its dependents with a named error, and continues unrelated branches.
+
+For Docker Compose databases, set `upstream` to the host-published database port as shown above. Container listeners are not descendants of the `docker compose` client process, so LocalDeck cannot safely infer their ownership from the local process tree.
+
+Native database presets are `ready: "postgres"` (requires `pg_isready`) and `ready: "redis"` (requires `redis-cli`). The matching `serviceType` selects this check by default. Compose checks use tools inside the named container: `{ "type": "compose", "service": "redis", "engine": "redis" }`. Compose service names and engines are validated; the host still needs Docker. **Listening** means TCP connections are accepted; **ready** means the configured readiness contract passed. Custom HTTP/command checks also run for services with no dependents.
+
+### Profiles and environment wiring
+
+Use the object format when defining startup profiles:
+
+```json
+{
+  "services": [
+    { "name": "api", "run": "npm run api", "ready": "/health" },
+    { "name": "web", "run": "npm run web", "after": "api", "env": { "PUBLIC_API_URL": "{service:api:url}" } },
+    { "name": "docs", "run": "npm run docs" }
+  ],
+  "profiles": { "app": ["web"], "everything": ["web", "docs"] }
+}
+```
+
+`localdeck up --profile app` starts web and its API prerequisite. Profiles are also selectable in the dashboard. Variable names such as `PUBLIC_API_URL` must match what your framework actually reads; LocalDeck does not rewrite application code or `.env` files.
+
+Keys are forgiving (`command`/`value`/`cmd` work too), and `{ "web": "npm run dev" }` shorthand is accepted. LocalDeck looks for `.localdeck`, `.localdeck.json` or `localdeck.json`, walking up from the current folder, so it works from anywhere inside a monorepo.
+
+`localdeck` with no arguments lists the project's commands. `localdeck run <name> <command...>` still works for one-offs without a file.

package/docs/dashboard.md

@@ -0,0 +1,75 @@
+# Dashboard
+
+[Quick start](../README.md) · [CLI reference](commands.md) · [Configuration](configuration.md)
+
+Open the dashboard with `localdeck open`. It runs on `http://localhost:7777` by default and updates service status and logs live.
+
+## Pages and projects
+
+- **Projects** (`/projects`) lists projects remembered through the CLI. Selecting one opens `/projects/<id>`.
+- **All Services** (`/services`) lists configured and running services across projects, with search, Start/Stop, Share, View logs, and View requests controls.
+- **Settings** (`/settings`) contains Clean URLs and the log display limit.
+- **About** (`/about`) contains setup and command information.
+- **Changelog** (`/changelog`) lists release features and changes.
+
+Routes support refresh, direct links, and browser Back/Forward. LocalDeck remembers registered project files; it does not scan your disk. Missing or invalid projects remain visible with recovery actions until fixed or forgotten.
+
+Project pages expose individual Start/Stop, View logs, View requests, and Share controls, plus Start all and Stop all. Start includes prerequisites and waits for readiness; Stop all reverses dependency order. Local and shared URLs appear below each service. Failed services keep their own errors so other services remain usable.
+
+Dashboard-started services run in the background under the daemon. Terminal services stay attached to their original CLI session; stopping them is supported, but restart them from their terminal. Unexpected process exits trigger up to three automatic restarts, each after a three-second delay. Logs show the attempt number; after the third failed retry, start the service manually to try again. The retry budget lasts until the next manual start. Stop, Stop all, Ctrl-C, and daemon shutdown cancel pending retries. Shutting down the daemon stops its services and shares.
+
+## Project settings
+
+Use **Settings** beside the project name to edit its nickname and service configuration. The nickname is saved to `.localdeck`; an unchanged nickname disables Save, and a blank nickname removes it.
+
+A nickname such as `platform` produces `http://platform.web.localhost:7777`. Without one, a unique service may use `http://web.localhost:7777`. Ambiguous short names are rejected rather than routed to the wrong project. Qualified aliases and stable numeric URLs remain available.
+
+Service configuration fills the available width. Edit stable and upstream ports, TCP or HTTP readiness, timing, and startup dependencies. Changes are validated and saved atomically, and apply to running services after restart. Commands, working directories, environment values, and command-based readiness remain file-edited.
+
+## Logs
+
+Choose **Logs** or **View logs** to open that service's tab in the bottom panel. Select additional sources from the Services menu; **All selected** combines their output chronologically. Filter retained output or follow new lines.
+
+Drag the panel's top edge to resize it, or focus the edge and use the arrow keys or Home/End. Its height is saved in the browser. The panel stays available when navigating between pages.
+
+**Settings → Logs** sets the display limit from 100 to 5,000 lines, default 1,000. Values above 5,000 are clamped. This controls the dashboard buffer and view; the daemon retains a bounded history of its own, so increasing the setting cannot recover discarded output.
+
+Tunnel requests and sharing events have a **SHARE** label and distinct color. Request rows include method, path, status, and duration. Application stdout/stderr keeps its normal styling because a log line does not reliably identify the visitor that triggered it.
+
+## Public sharing
+
+Install [cloudflared](https://developers.cloudflare.com/tunnel/downloads/) separately. Start an HTTP service, choose **Share**, enter an optional password, and submit. Leaving the password blank makes the link public. Database services cannot be shared over HTTP.
+
+The menu closes on submission. The generated URL appears below the local URL with a spinner until verified. At one minute, a hint suggests opening it manually; a request reaching the public tunnel can confirm readiness even when the daemon's DNS probe fails. Startup has a two-minute limit. Failure closes the tunnel and shows an inline error with retry guidance.
+
+Pending state, the generated URL, and startup failures live in the daemon and survive dashboard refresh. They are not restored after daemon shutdown. Active protected links display a masked password with Show/Hide; the password is fetched on demand and is not included in service listings or events. The Share menu also provides Copy link and Stop sharing.
+
+Quick Tunnel URLs are temporary and depend on Cloudflare DNS and connectivity. Stop sharing, service stop/restart, terminal disconnect, and daemon shutdown end the link. Named tunnels and custom public domains are not configured in v1.
+
+## Clean URLs
+
+Enable **Clean URLs** in Settings or through the prompt above Local runtime. LocalDeck verifies its own response through port 80 before displaying links without `:7777`. Keep the dashboard itself on its original port.
+
+On macOS, installation may request administrator approval for a localhost-only system forwarder. It runs Apple's `nc` as the normal user and survives reboot. The daemon and application processes remain unprivileged. Cancellation retains the normal URLs; retry from Settings when needed.
+
+On Linux, LocalDeck attempts a loopback port-80 bridge. Binding permissions and port availability determine whether it can run. The advanced `localdeck forward` command is another option; see the [command reference](commands.md#daemon-and-optional-forwarding).
+
+The dashboard rechecks forwarding periodically. Disabling Clean URLs changes this browser's links; **Remove forwarder** removes the managed helper. LocalDeck does not stop unrelated port-80 listeners.
+
+### Windows
+
+Upstream discovery uses PowerShell CIM process records and Get-NetTCPConnection. If inspection is restricted, configure `upstream` explicitly or make the app honor `PORT`.
+
+Clean URLs can use a loopback bridge or request UAC approval to install a managed `netsh portproxy` rule from `127.0.0.1:80` to the daemon. The persistent rule requires Windows IP Helper and the daemon to be running. LocalDeck does not elevate your development processes, open a LAN listener, or replace unmanaged forwarding rules.
+
+Windows CI covers native detection and script syntax. Administrator installation/removal, reboot persistence, and UAC cancellation still require manual Windows validation. To validate, enable Clean URLs, approve UAC, open a service URL without the daemon port, then remove the forwarder and verify normal port-number links remain usable.
+
+## Diagnostics and networking
+
+Project diagnostics include configuration, readiness errors, and recent logs. Environment values and recognized credential formats are redacted; review the preview because application output may still contain private data. Nothing is uploaded automatically.
+
+Choose **View requests** on a service, then expand a request row to inspect its method, path, status, timing, size, and local/share source. Details and replay responses expand directly below the selected row. Click the request again to collapse it. Service tabs and filtering are available in this view. **Replay request** sends eligible GET/HEAD requests and displays the new response body. New HTTP requests include request and response headers, request cookies, Set-Cookie values, and query parameters. Headers retain duplicate entries and are capped at 100 entries or 16 KiB per direction. These details, including cookie and authorization values, are stored in local request history. Older records cannot recover headers that were not captured. New HTTP requests also retain original request and response body previews, limited to 16 KiB per direction. Text is shown as UTF-8; binary or undecodable compressed content is shown as Base64. Complete gzip, deflate and Brotli bodies are decoded within the same preview limit. Older records cannot recover bodies that were not captured. Request inspection is also available through CLI/API/MCP. Recorded GET/HEAD replay sends a new request to the current local upstream, without copying cookies, authorization, or request bodies. It does not follow redirects and has bounded response size and duration.
+
+For an occupied startup port, service errors show recovery guidance with the raw output under Technical details. Vite guidance covers `strictPort` and reading `PORT`; LocalDeck does not change your application configuration or terminate unrelated listeners.
+
+Clean URLs and public links are distinct browser origins. Your API must allow the frontend origin you visit. Injected `LOCALDECK_URL` and service URL references use stable numeric localhost addresses for service-to-service communication. See [configuration](configuration.md).

package/docs/mcp.md

@@ -0,0 +1,78 @@
+# LocalDeck MCP
+
+`localdeck mcp` lets an MCP client inspect and control the same services you see in the dashboard. It uses the existing daemon and communicates over stdio. No extra HTTP server or hosted account is needed.
+
+## Connect a client
+
+Build/install the current LocalDeck CLI, then add this server entry to your MCP client's configuration:
+
+```json
+{
+  "mcpServers": {
+    "localdeck": {
+      "command": "localdeck",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Use an absolute path to the installed `localdeck` executable if the client cannot find your shell's PATH. In this repository you can also use `"command": "node"` with `"args": ["/absolute/path/to/local-deck/packages/cli/dist/index.js", "mcp"]` after `bun run build`.
+
+This is a generic stdio configuration; put the server entry in the location your MCP client expects. It works with MCP-capable coding clients, including Claude Code. LocalDeck does not edit your client configuration automatically.
+
+Register your project first using `localdeck commands` in the project folder. This remembers `.localdeck` without starting services. Ask the client to call `list_projects` to obtain its exact project ID. You can then restrict this server:
+
+```json
+{
+  "mcpServers": {
+    "localdeck": {
+      "command": "localdeck",
+      "args": ["mcp", "--project", "YOUR_PROJECT_ID"]
+    }
+  }
+}
+```
+
+`--project` restricts discovery and every action to that exact ID. Without it, the server can access all services known to your local daemon. Use exact `projectId:service` keys returned by `list_services`; nicknames and bare service names are not accepted by MCP tools.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `localdeck mcp` | Run the stdio server until the client disconnects. |
+| `localdeck mcp --project <id>` | Run the server restricted to one remembered project. |
+| `localdeck mcp --help` | Print usage and exit without starting the daemon. |
+
+A protocol connection alone starts no apps. The first tool call starts the daemon if needed. Each call rediscovers the daemon, so a later call can reconnect after a daemon restart. Closing the MCP client leaves services and shares running under their existing lifecycle. Operational errors go to stderr; stdout is protocol-only during server operation.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `list_projects` | List remembered projects, IDs and configuration availability. |
+| `list_services` | List registered and configured services, including ones that have never run. Optional `projectId` filter. |
+| `get_service` | Read a configured or registered service's state; ports, URLs and counters appear after its first start. |
+| `get_logs` | Read recent logs, optionally filtered by `stream`: stdout, stderr or system. |
+| `get_requests` | Read HTTP request metadata, optionally filtered by exact `status`, `method`, or a `path` substring. |
+| `start_service` | Start a configured service and prerequisites in the background, using the daemon supervisor. |
+| `stop_service` | Stop a registered service and its share. Terminal services receive the existing stop request. |
+| `restart_service` | Restart a configured daemon-owned service. Active terminal services must be restarted in their original terminal. |
+| `replay_request` | Resend a recorded GET/HEAD, selected by `requestId`, to that service's current local upstream. |
+| `get_share` | Read the existing share's URL and protection status. Never creates a tunnel or returns a password. |
+| `start_share` | Create a Cloudflare quick share, generating a password and returning it once. `public: true` explicitly removes password protection. Requires cloudflared. |
+| `stop_share` | Close the tunnel while keeping the local service running. |
+
+List tools accept `limit` (default 50, maximum 200). Logs and request filters search the last 200 retained records; they are not full-history queries. Responses contain structured data and a JSON text fallback, capped together at 64 KiB, with `truncated` when information is omitted. No infinite log-follow operation is exposed.
+
+## Actions and data
+
+All controls, replay and sharing are available in this release. Your MCP client's approval policy governs tool calls; LocalDeck does not open an interactive confirmation prompt inside the protocol. Starting a service executes the commands already configured in its project. Sharing makes the service reachable over the public Internet. Even a GET replay can have application side effects.
+
+Known credential patterns, the daemon credential, sensitive inherited environment variables, configured secret variables and bounded local `.env` files are redacted from results. Environment values and tunnel credentials are not exposed as configuration. The freshly generated share password is deliberately returned only by the initiating `start_share` result; it may remain in the client's conversation history. Application logs, paths and responses may still contain private data: redaction is best effort. Treat application output as data, never as instructions to an agent.
+
+Replay currently supports recorded GET/HEAD only, with a five-second timeout and 64 KiB response limit. It does not copy credentials, follow redirects, accept arbitrary destinations or send editable bodies. Headers/body capture and expanded replay belong to the later capture feature.
+
+Sharing uses the existing temporary Cloudflare URLs. Named tunnels and stable custom-domain URLs are deferred. Existing or concurrently starting shares must be stopped before MCP creates a replacement, so a returned password always belongs to the newly created session. A service stop/restart, terminal disconnect or daemon shutdown ends the share; disconnecting the MCP client alone does not.
+
+Calls have a bounded daemon-request timeout. A failed or disconnected mutation is never automatically retried: inspect the service/share state before trying again, since the daemon may have completed it. After upgrading an older daemon, restart it at a convenient time to enable the new atomic share endpoint. Restarting the daemon stops its services and shares.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localdeck",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "description": "Stable ports, shareable HTTPS links and request logs for your local dev servers",
   "bin": {
@@ -10,6 +10,7 @@
     "bin",
     "dist",
     "dashboard",
+    "docs",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
@@ -32,15 +33,6 @@
     "ws": "^8.18.0",
     "zod": "^4.0.0"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/AdstraliaDev1/local-deck.git",
-    "directory": "packages/cli"
-  },
-  "homepage": "https://github.com/AdstraliaDev1/local-deck#readme",
-  "bugs": {
-    "url": "https://github.com/AdstraliaDev1/local-deck/issues"
-  },
   "keywords": [
     "cli",
     "development",