devsurface 0.7.1 → 0.8.0

package/dist/cli/index.js

@@ -1087,6 +1087,141 @@ async function detectPorts(ports) {
   );
 }
 
+// src/core/scanner/portOwner.ts
+import spawn2 from "cross-spawn";
+var LOOKUP_TIMEOUT_MS = 3e3;
+function captureCommand(command, args) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (value) => {
+      if (!settled) {
+        settled = true;
+        resolve(value);
+      }
+    };
+    const child = spawn2(command, args, {
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true
+    });
+    const chunks = [];
+    const timer = setTimeout(() => {
+      child.kill();
+      finish(null);
+    }, LOOKUP_TIMEOUT_MS);
+    child.stdout?.on("data", (chunk) => {
+      chunks.push(chunk);
+    });
+    child.on("error", () => {
+      clearTimeout(timer);
+      finish(null);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      finish(code === 0 ? Buffer.concat(chunks).toString("utf8") : null);
+    });
+  });
+}
+function parseNetstatListeners(output) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const line of output.split(/\r?\n/)) {
+    const columns = line.trim().split(/\s+/);
+    if (columns.length < 5 || columns[0].toUpperCase() !== "TCP") {
+      continue;
+    }
+    if (columns[3].toUpperCase() !== "LISTENING") {
+      continue;
+    }
+    const portMatch = /[.:](\d+)$/.exec(columns[1]);
+    const pid = Number(columns[4]);
+    if (portMatch === null || !Number.isInteger(pid) || pid <= 0) {
+      continue;
+    }
+    const port = Number(portMatch[1]);
+    if (!owners.has(port)) {
+      owners.set(port, pid);
+    }
+  }
+  return owners;
+}
+function parseTasklistName(output) {
+  const line = output.split(/\r?\n/).find((candidate) => candidate.trim().startsWith('"'));
+  if (line === void 0) {
+    return null;
+  }
+  const match = /^"([^"]+)"/.exec(line.trim());
+  return match === null ? null : match[1];
+}
+function parseLsofOwner(output) {
+  let pid = null;
+  let name = null;
+  for (const line of output.split(/\r?\n/)) {
+    if (line.startsWith("p") && pid === null) {
+      const value = Number(line.slice(1));
+      if (Number.isInteger(value) && value > 0) {
+        pid = value;
+      }
+    } else if (line.startsWith("c") && name === null) {
+      name = line.slice(1) || null;
+    }
+    if (pid !== null && name !== null) {
+      break;
+    }
+  }
+  return pid === null ? null : { pid, name };
+}
+async function findOwnersWindows(ports) {
+  const owners = /* @__PURE__ */ new Map();
+  const netstat = await captureCommand("netstat", ["-ano", "-p", "tcp"]);
+  if (netstat === null) {
+    return owners;
+  }
+  const listeners = parseNetstatListeners(netstat);
+  const nameCache = /* @__PURE__ */ new Map();
+  for (const port of ports) {
+    const pid = listeners.get(port);
+    if (pid === void 0) {
+      continue;
+    }
+    if (!nameCache.has(pid)) {
+      const tasklist = await captureCommand("tasklist", [
+        "/FI",
+        `PID eq ${pid}`,
+        "/FO",
+        "CSV",
+        "/NH"
+      ]);
+      nameCache.set(pid, tasklist === null ? null : parseTasklistName(tasklist));
+    }
+    owners.set(port, { pid, name: nameCache.get(pid) ?? null });
+  }
+  return owners;
+}
+async function findOwnersUnix(ports) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const port of ports) {
+    const output = await captureCommand("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-FpcL"]);
+    if (output === null) {
+      continue;
+    }
+    const owner = parseLsofOwner(output);
+    if (owner !== null) {
+      owners.set(port, owner);
+    }
+  }
+  return owners;
+}
+async function findPortOwners(ports) {
+  const unique = Array.from(new Set(ports)).slice(0, 16);
+  if (unique.length === 0) {
+    return /* @__PURE__ */ new Map();
+  }
+  try {
+    return process.platform === "win32" ? await findOwnersWindows(unique) : await findOwnersUnix(unique);
+  } catch {
+    return /* @__PURE__ */ new Map();
+  }
+}
+
 // src/core/scanner/presets.ts
 import { promises as fs9 } from "fs";
 import path9 from "path";
@@ -1381,6 +1516,15 @@ async function scanProject(root = process.cwd()) {
     findFirstFile(resolvedRoot, ["README.md", "README"]),
     findFirstFile(resolvedRoot, ["LICENSE", "LICENSE.md", "COPYING"])
   ]);
+  const busyPorts = (ports ?? []).filter((probe) => probe.inUse).map((probe) => probe.port);
+  if (busyPorts.length > 0) {
+    const owners = await findPortOwners(busyPorts);
+    for (const probe of ports ?? []) {
+      if (probe.inUse) {
+        probe.owner = owners.get(probe.port) ?? null;
+      }
+    }
+  }
   return {
     root: resolvedRoot,
     projectName: config?.config.name ?? packageJson?.data.name ?? path10.basename(resolvedRoot),
@@ -1813,11 +1957,127 @@ async function onboardCommand(cwd = process.cwd()) {
   }
 }
 
-// src/cli/commands/run.ts
+// src/cli/commands/passport.ts
+import { promises as fs13 } from "fs";
+import path13 from "path";
 import pc4 from "picocolors";
 
+// src/core/explain/index.ts
+var NAME_INTENTS = [
+  {
+    keys: ["dev", "develop", "serve", "watch", "start:dev"],
+    explanation: "Starts the development server so you can preview the app in your browser while you work."
+  },
+  { keys: ["start"], explanation: "Starts the application." },
+  {
+    keys: ["build", "compile", "bundle", "dist"],
+    explanation: "Builds the app into optimized files ready for production."
+  },
+  {
+    keys: ["preview"],
+    explanation: "Runs the finished production build locally so you can preview it."
+  },
+  {
+    keys: ["test", "tests", "spec", "unit"],
+    explanation: "Runs the automated tests to check the code still works."
+  },
+  {
+    keys: ["e2e", "integration"],
+    explanation: "Runs end-to-end tests that drive the app like a real user."
+  },
+  {
+    keys: ["lint"],
+    explanation: "Checks the code for style problems and common mistakes."
+  },
+  {
+    keys: ["format", "fmt", "prettier"],
+    explanation: "Automatically reformats the code to a consistent style."
+  },
+  {
+    keys: ["typecheck", "tsc", "types"],
+    explanation: "Checks the code for type errors."
+  },
+  {
+    keys: ["migrate", "migration", "migrations"],
+    explanation: "Applies pending database changes (migrations)."
+  },
+  { keys: ["seed"], explanation: "Fills the database with starter sample data." },
+  {
+    keys: ["clean"],
+    explanation: "Deletes generated files and leftover build output."
+  },
+  {
+    keys: ["deploy", "release", "publish"],
+    explanation: "Publishes or deploys the project \u2014 double-check before running this one."
+  },
+  {
+    keys: ["install", "setup", "bootstrap"],
+    explanation: "Installs the tools and packages the project needs."
+  },
+  {
+    keys: ["storybook"],
+    explanation: "Starts Storybook to preview UI components on their own."
+  },
+  { keys: ["docs"], explanation: "Builds or serves the project documentation." }
+];
+var TOOL_INTENTS = [
+  {
+    test: /nodemon|ts-node-dev/,
+    explanation: "Runs the app and restarts it automatically whenever you change a file."
+  },
+  {
+    test: /vite\s+build|webpack|rollup|esbuild|\btsup\b|\bparcel\b/,
+    explanation: "Builds the app into optimized files ready for production."
+  },
+  {
+    test: /next\s+dev|vite|remix\s+dev|astro\s+dev/,
+    explanation: "Starts the development server so you can preview the app in your browser."
+  },
+  {
+    test: /playwright|cypress/,
+    explanation: "Runs end-to-end tests that drive the app like a real user."
+  },
+  {
+    test: /vitest|\bjest\b|mocha|\bava\b|pytest|\bgo\s+test\b/,
+    explanation: "Runs the automated tests to check the code works."
+  },
+  {
+    test: /eslint|biome\s+lint|ruff|flake8/,
+    explanation: "Checks the code for style problems and common mistakes."
+  },
+  {
+    test: /prettier|biome\s+format|black\b/,
+    explanation: "Reformats the code to a consistent style."
+  },
+  { test: /tsc\b/, explanation: "Compiles and type-checks the TypeScript code." },
+  { test: /prisma/, explanation: "Manages the database schema and data with Prisma." },
+  {
+    test: /docker[-\s]compose|\bdocker\b/,
+    explanation: "Starts or manages the project\u2019s Docker containers."
+  },
+  { test: /\bgo\s+run\b/, explanation: "Runs the Go program." },
+  { test: /\bgo\s+build\b/, explanation: "Builds the Go program into an executable." },
+  {
+    test: /uvicorn|flask\s+run|manage\.py\s+runserver/,
+    explanation: "Starts the development server so you can preview the app in your browser."
+  }
+];
+function explainScript(name, command = "") {
+  const baseName = name.toLowerCase().split(/[:/]/)[0];
+  const intent = NAME_INTENTS.find((entry) => entry.keys.includes(baseName));
+  if (intent !== void 0) {
+    return intent.explanation;
+  }
+  const lowerCommand = command.toLowerCase();
+  const tool = TOOL_INTENTS.find((entry) => entry.test.test(lowerCommand));
+  if (tool !== void 0) {
+    return tool.explanation;
+  }
+  return `Runs the project\u2019s \u201C${name}\u201D command.`;
+}
+
 // src/core/process/runner.ts
-import spawn2 from "cross-spawn";
+import spawn3 from "cross-spawn";
 
 // src/core/security/dangerousCommand.ts
 var DANGEROUS_COMMAND = /\b(rm\s+-rf|docker\s+volume\s+rm|drop\s+database|prisma\s+migrate\s+reset|git\s+clean\s+-fdx?)\b/i;
@@ -1981,7 +2241,7 @@ async function runPackageScriptToTerminal(options) {
     return 1;
   }
   return await new Promise((resolve) => {
-    const child = spawn2(runCommand2.command, runCommand2.args, {
+    const child = spawn3(runCommand2.command, runCommand2.args, {
       cwd: options.cwd,
       stdio: "inherit",
       windowsHide: true
@@ -2000,7 +2260,7 @@ async function runConfiguredCommandToTerminal(options) {
     return 1;
   }
   return await new Promise((resolve) => {
-    const child = spawn2(resolvedCommand.command, resolvedCommand.args, {
+    const child = spawn3(resolvedCommand.command, resolvedCommand.args, {
       cwd: options.cwd,
       stdio: "inherit",
       windowsHide: true
@@ -2014,7 +2274,656 @@ async function runConfiguredCommandToTerminal(options) {
   });
 }
 
+// src/core/passport/index.ts
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+}
+var LANGUAGE_LABELS = {
+  node: "JavaScript / TypeScript",
+  python: "Python",
+  go: "Go",
+  java: "Java"
+};
+var STACK_ROLES = [
+  { names: ["next"], role: "Web framework" },
+  { names: ["react", "react-dom"], role: "User interface library" },
+  { names: ["vue"], role: "User interface library" },
+  { names: ["svelte"], role: "User interface library" },
+  { names: ["express"], role: "Web server framework" },
+  { names: ["fastify"], role: "Web server framework" },
+  { names: ["hono"], role: "Web server framework" },
+  { names: ["@nestjs/core"], role: "Web server framework" },
+  { names: ["@remix-run/react"], role: "Web framework" },
+  { names: ["prisma", "@prisma/client"], role: "Database toolkit" },
+  { names: ["mongoose"], role: "MongoDB database layer" },
+  { names: ["pg"], role: "PostgreSQL database driver" },
+  { names: ["redis", "ioredis"], role: "Redis cache client" },
+  { names: ["typescript"], role: "Typed JavaScript" },
+  { names: ["vite"], role: "Build tool and dev server" },
+  { names: ["webpack"], role: "Build tool" },
+  { names: ["tailwindcss"], role: "CSS styling framework" },
+  { names: ["vitest", "jest", "mocha"], role: "Test runner" },
+  { names: ["playwright", "@playwright/test", "cypress"], role: "Browser testing" },
+  { names: ["eslint"], role: "Code quality checks" },
+  { names: ["prettier"], role: "Code formatting" },
+  { names: ["commander", "yargs"], role: "Command-line framework" },
+  { names: ["ws", "socket.io"], role: "Real-time connections" },
+  { names: ["zod"], role: "Data validation" },
+  { names: ["axios"], role: "HTTP requests" },
+  { names: ["dotenv"], role: "Loads .env settings" }
+];
+function describeProject(scan) {
+  const configured = scan.config?.config.description;
+  if (typeof configured === "string" && configured.trim().length > 0) {
+    return configured.trim();
+  }
+  const packageDescription = scan.packageJson?.data.description;
+  if (typeof packageDescription === "string" && packageDescription.trim().length > 0) {
+    return packageDescription.trim();
+  }
+  const parts = [];
+  if (scan.framework !== null) {
+    parts.push(`built with ${scan.framework.type}`);
+  }
+  const languages = scan.language.detected.map((language) => LANGUAGE_LABELS[language] ?? language).join(", ");
+  if (languages.length > 0) {
+    parts.push(`written in ${languages}`);
+  }
+  if (scan.docker !== null && scan.docker.composeFiles.length > 0) {
+    parts.push("with Docker services");
+  }
+  if (parts.length === 0) {
+    return "A software project.";
+  }
+  return `A software project ${parts.join(", ")}.`;
+}
+function startCommand(scan) {
+  if (scan.scripts.dev !== void 0) {
+    return getPackageRunCommand(scan.packageManager, "dev").displayCommand;
+  }
+  if (scan.scripts.start !== void 0) {
+    return getPackageRunCommand(scan.packageManager, "start").displayCommand;
+  }
+  const configured = { ...scan.presetCommands, ...scan.config?.config.commands ?? {} };
+  for (const name of ["dev", "start", "serve"]) {
+    if (configured[name] !== void 0) {
+      return configured[name];
+    }
+  }
+  return null;
+}
+function commandForStep(step, scan) {
+  const action = step.action;
+  if (action === void 0) {
+    return null;
+  }
+  if (action.kind === "install") {
+    return getPackageInstallCommand(scan.packageManager).displayCommand;
+  }
+  if (action.kind === "env-copy") {
+    return "cp .env.example .env";
+  }
+  if (action.kind === "run-script" && action.target !== void 0) {
+    return getPackageRunCommand(scan.packageManager, action.target).displayCommand;
+  }
+  if (action.kind === "run-command" && action.target !== void 0) {
+    const configured = { ...scan.presetCommands, ...scan.config?.config.commands ?? {} };
+    return configured[action.target] ?? null;
+  }
+  if (action.kind === "docker") {
+    return "docker compose up -d";
+  }
+  return null;
+}
+function statusBadge(status) {
+  if (status === "done") {
+    return '<span class="badge badge-done">Done</span>';
+  }
+  if (status === "todo") {
+    return '<span class="badge badge-todo">To do</span>';
+  }
+  return '<span class="badge badge-manual">Needs you</span>';
+}
+function severityBadge(severity) {
+  if (severity === "error") {
+    return '<span class="badge badge-error">Error</span>';
+  }
+  if (severity === "warning") {
+    return '<span class="badge badge-todo">Warning</span>';
+  }
+  return '<span class="badge badge-manual">Info</span>';
+}
+function heroBadges(scan) {
+  const badges = [];
+  if (scan.framework !== null) {
+    badges.push(scan.framework.type);
+  }
+  for (const language of scan.language.detected) {
+    badges.push(LANGUAGE_LABELS[language] ?? language);
+  }
+  if (scan.packageManager !== null) {
+    badges.push(scan.packageManager);
+  }
+  if (scan.git?.branch != null) {
+    badges.push(`branch: ${scan.git.branch}`);
+  }
+  return badges.map((badge) => `<span class="badge badge-hero">${escapeHtml(badge)}</span>`).join("\n          ");
+}
+function commandRow(command, note) {
+  const escaped = escapeHtml(command);
+  return `      <div class="recipe-row">
+        <div class="recipe-note">${escapeHtml(note)}</div>
+        <div class="recipe-command">
+          <code>${escaped}</code>
+          <button type="button" class="copy" data-copy="${escaped}">Copy</button>
+        </div>
+      </div>`;
+}
+function quickStartSection(scan) {
+  const rows = [];
+  if (scan.language.detected.includes("node") && scan.packageJson !== null) {
+    rows.push(
+      commandRow(
+        getPackageInstallCommand(scan.packageManager).displayCommand,
+        "Install the packages the project needs"
+      )
+    );
+  }
+  if (scan.env?.hasExample) {
+    rows.push(
+      commandRow("cp .env.example .env", "Create your local settings file (Windows: use copy)")
+    );
+  }
+  if (scan.docker !== null && scan.docker.composeFiles.length > 0) {
+    rows.push(commandRow("docker compose up -d", "Start the background services"));
+  }
+  const start = startCommand(scan);
+  if (start !== null) {
+    rows.push(commandRow(start, "Start the app"));
+  }
+  if (rows.length === 0) {
+    return "";
+  }
+  return `  <section id="quick-start">
+    <h2>Quick start</h2>
+    <p class="muted">On a fresh machine, run these in a terminal from the project folder, top to bottom.</p>
+${rows.join("\n")}
+  </section>`;
+}
+function requirementsSection(scan) {
+  const requirements = [];
+  if (scan.language.detected.includes("node")) {
+    const nodeRange = scan.packageJson?.data.engines?.node;
+    requirements.push({
+      name: "Node.js",
+      detail: typeof nodeRange === "string" && nodeRange.trim().length > 0 ? `version ${nodeRange.trim()}` : "any recent LTS version"
+    });
+    if (scan.packageManager !== null && scan.packageManager !== "npm") {
+      requirements.push({
+        name: scan.packageManager,
+        detail: "the package manager this project uses"
+      });
+    }
+  }
+  if (scan.language.detected.includes("python")) {
+    requirements.push({ name: "Python", detail: "a recent Python 3 version" });
+  }
+  if (scan.language.detected.includes("go")) {
+    requirements.push({ name: "Go", detail: "a recent Go toolchain" });
+  }
+  if (scan.language.detected.includes("java")) {
+    requirements.push({ name: "Java", detail: "a JDK matching the build files" });
+  }
+  if (scan.docker !== null && scan.docker.composeFiles.length > 0) {
+    requirements.push({
+      name: "Docker Desktop",
+      detail: "runs the background services \u2014 start it before the quick start"
+    });
+  }
+  if (requirements.length === 0) {
+    return "";
+  }
+  const items = requirements.map(
+    (requirement) => `      <li><strong>${escapeHtml(requirement.name)}</strong> \u2014 ${escapeHtml(requirement.detail)}</li>`
+  ).join("\n");
+  return `  <section id="requirements">
+    <h2>What you need installed</h2>
+    <ul class="plain-list">
+${items}
+    </ul>
+  </section>`;
+}
+function stepsSection(plan, scan) {
+  if (plan.steps.length === 0) {
+    return '<p class="muted">Nothing special to set up. Open the project and start exploring.</p>';
+  }
+  const items = plan.steps.map((step) => {
+    const command = commandForStep(step, scan);
+    const commandHtml = command !== null && step.status !== "done" ? `
+        <div class="recipe-command"><code>${escapeHtml(command)}</code><button type="button" class="copy" data-copy="${escapeHtml(command)}">Copy</button></div>` : "";
+    return `      <li class="step step-${step.status}">
+        <div class="step-heading">${statusBadge(step.status)}<strong>${escapeHtml(step.title)}</strong></div>
+        <p>${escapeHtml(step.description)}</p>${commandHtml}
+      </li>`;
+  }).join("\n");
+  return `<ol class="steps">
+${items}
+    </ol>`;
+}
+function stackSection(scan) {
+  const data = scan.packageJson?.data;
+  if (data === void 0 || data === null) {
+    return "";
+  }
+  const all = { ...data.dependencies, ...data.devDependencies };
+  const names = Object.keys(all);
+  if (names.length === 0) {
+    return "";
+  }
+  const seenRoles = /* @__PURE__ */ new Set();
+  const highlights = [];
+  for (const entry of STACK_ROLES) {
+    const found = entry.names.find((name) => all[name] !== void 0);
+    if (found !== void 0 && !seenRoles.has(entry.role)) {
+      seenRoles.add(entry.role);
+      highlights.push({ name: found, role: entry.role });
+    }
+    if (highlights.length >= 8) {
+      break;
+    }
+  }
+  if (highlights.length === 0) {
+    return "";
+  }
+  const remaining = names.length - highlights.length;
+  const cells = highlights.map(
+    (highlight) => `      <div class="stack-cell">
+        <code>${escapeHtml(highlight.name)}</code>
+        <span>${escapeHtml(highlight.role)}</span>
+      </div>`
+  ).join("\n");
+  const more = remaining > 0 ? `
+    <p class="muted">\u2026plus ${remaining} more package${remaining === 1 ? "" : "s"} doing supporting work.</p>` : "";
+  return `  <section id="stack">
+    <h2>The tech stack, translated</h2>
+    <div class="stack-grid">
+${cells}
+    </div>${more}
+  </section>`;
+}
+function scriptsSection(scan) {
+  const entries = Object.entries(scan.scripts);
+  if (entries.length === 0) {
+    return '<p class="muted">No package scripts detected.</p>';
+  }
+  const rows = entries.map(
+    ([name, command]) => `      <tr>
+        <td><code>${escapeHtml(name)}</code></td>
+        <td>${escapeHtml(explainScript(name, command))}</td>
+        <td class="raw"><code>${escapeHtml(command)}</code></td>
+      </tr>`
+  ).join("\n");
+  return `<table>
+      <thead><tr><th>Command</th><th>What it does</th><th>Exactly what runs</th></tr></thead>
+      <tbody>
+${rows}
+      </tbody>
+    </table>`;
+}
+function envSection(scan) {
+  const env = scan.env;
+  if (env === null || !env.hasExample && !env.hasLocal) {
+    return '<p class="muted">This project does not use a .env settings file.</p>';
+  }
+  if (env.keys.length === 0 && env.exampleKeys.length === 0) {
+    return '<p class="muted">Environment files exist but declare no keys.</p>';
+  }
+  const keys = env.keys.length > 0 ? env.keys.map((key) => ({
+    key: key.key,
+    state: key.present ? key.empty ? "empty" : "set" : "missing"
+  })) : env.exampleKeys.map((key) => ({ key, state: "missing" }));
+  const rows = keys.map((entry) => {
+    const badge = entry.state === "set" ? '<span class="badge badge-done">Set</span>' : entry.state === "empty" ? '<span class="badge badge-todo">Empty</span>' : '<span class="badge badge-error">Missing</span>';
+    return `      <tr><td><code>${escapeHtml(entry.key)}</code></td><td>${badge}</td></tr>`;
+  }).join("\n");
+  return `<p class="muted">Only key names are shown. Values never leave your machine.</p>
+    <table>
+      <thead><tr><th>Setting</th><th>Status</th></tr></thead>
+      <tbody>
+${rows}
+      </tbody>
+    </table>`;
+}
+function portsSection(scan) {
+  if (scan.ports.length === 0) {
+    return '<p class="muted">No specific network ports detected.</p>';
+  }
+  const items = scan.ports.map((probe) => {
+    const badge = probe.inUse ? '<span class="badge badge-todo">Busy right now</span>' : '<span class="badge badge-done">Free</span>';
+    return `      <li><code>${probe.port}</code> ${badge}</li>`;
+  }).join("\n");
+  return `<p class="muted">The app expects these ports. \u201CBusy\u201D means another program is using it.</p>
+    <ul class="plain-list">
+${items}
+    </ul>`;
+}
+function dockerSection(scan) {
+  const docker = scan.docker;
+  if (docker === null || docker.composeFiles.length === 0) {
+    return "";
+  }
+  const services = docker.services.length > 0 ? `<ul class="plain-list">
+${docker.services.map((service) => `      <li><code>${escapeHtml(service.name)}</code></li>`).join("\n")}
+    </ul>` : '<p class="muted">Service list is available when Docker is running.</p>';
+  return `  <section id="services">
+    <h2>Background services (Docker)</h2>
+    <p class="muted">This project uses Docker to run helper services (like databases) in the background.</p>
+    ${services}
+  </section>`;
+}
+function healthSection(warnings) {
+  if (warnings.length === 0) {
+    return '<p class="muted">No setup problems detected. Looking good.</p>';
+  }
+  const items = warnings.map(
+    (warning2) => `      <li>
+        <div class="step-heading">${severityBadge(warning2.severity)}<strong>${escapeHtml(warning2.title)}</strong></div>
+        <p>${escapeHtml(warning2.message)}</p>
+      </li>`
+  ).join("\n");
+  return `<ul class="steps">
+${items}
+    </ul>`;
+}
+function troubleshootingSection(scan) {
+  const tips = [];
+  if (scan.language.detected.includes("node")) {
+    const manager = scan.packageManager ?? "npm";
+    tips.push({
+      symptom: `\u201Ccommand not found\u201D when running ${manager}`,
+      fix: manager === "npm" ? "Node.js is not installed (or not on your PATH). Install the LTS version from the official Node.js site, then reopen your terminal." : `Install Node.js first, then install ${manager} (it is a separate tool). Reopen your terminal afterwards.`
+    });
+  }
+  if (scan.ports.length > 0) {
+    tips.push({
+      symptom: "The app says a port is already in use (EADDRINUSE)",
+      fix: "Another program is using that port \u2014 often an old copy of this same app. Close other dev servers or restart your computer, then try again."
+    });
+  }
+  if (scan.env?.hasExample) {
+    tips.push({
+      symptom: "The app starts, then crashes or complains about missing configuration",
+      fix: "Open the .env file and fill in any empty values. The \u201CSettings this project needs\u201D list above shows which keys must be set."
+    });
+  }
+  if (scan.docker !== null && scan.docker.composeFiles.length > 0) {
+    tips.push({
+      symptom: "Docker commands fail or hang",
+      fix: "Docker Desktop is probably not running. Start it, wait for the whale icon to settle, then run the command again."
+    });
+  }
+  tips.push({
+    symptom: "Something else is wrong",
+    fix: "Run \u201Cnpx devsurface\u201D in the project folder \u2014 it opens a live dashboard that checks your setup and pinpoints what is missing."
+  });
+  const items = tips.map(
+    (tip) => `      <li>
+        <strong>${escapeHtml(tip.symptom)}</strong>
+        <p>${escapeHtml(tip.fix)}</p>
+      </li>`
+  ).join("\n");
+  return `  <section id="troubleshooting">
+    <h2>If something goes wrong</h2>
+    <ul class="steps">
+${items}
+    </ul>
+  </section>`;
+}
+function glossarySection(scan) {
+  const terms = [
+    [
+      "Terminal",
+      "The text window where you type commands. On Windows use PowerShell; on Mac use Terminal."
+    ],
+    ["Command", "A line of text you type into the terminal and run by pressing Enter."],
+    [
+      "Dependency",
+      "A ready-made package of code this project reuses instead of writing from scratch."
+    ],
+    ["Port", "A numbered door on your computer that a running app listens on, like 3000 or 8080."],
+    [
+      "localhost",
+      "Your own computer. http://localhost:3000 means \u201Cthe app running on my machine, door 3000\u201D."
+    ]
+  ];
+  if (scan.env !== null && (scan.env.hasExample || scan.env.hasLocal)) {
+    terms.splice(3, 0, [
+      ".env file",
+      "A private settings file with keys and secret values. It stays on your machine and is never shared."
+    ]);
+  }
+  const cells = terms.map(
+    ([term, definition]) => `      <div class="stack-cell">
+        <strong>${escapeHtml(term)}</strong>
+        <span>${escapeHtml(definition)}</span>
+      </div>`
+  ).join("\n");
+  return `  <section id="glossary">
+    <h2>Words you will meet</h2>
+    <div class="stack-grid glossary-grid">
+${cells}
+    </div>
+  </section>`;
+}
+var PASSPORT_CSS = `
+  :root {
+    color-scheme: light;
+    --bg: #F0EEE6; --card: #FAF9F5; --ink: #141413; --muted: #73706A;
+    --line: #E3DFD3; --accent: #CC785C; --accent-deep: #B15D41;
+    --done: #3D7A4E; --warn: #96690F; --bad: #B4392A;
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; padding: 40px 18px 24px; background: var(--bg); color: var(--ink);
+    font: 16px/1.62 "Styrene A", "Segoe UI", system-ui, -apple-system, sans-serif;
+  }
+  main { max-width: 880px; margin: 0 auto; }
+  h1, h2 {
+    font-family: "Tiempos Headline", Georgia, "Times New Roman", serif;
+    font-weight: 500; letter-spacing: -0.01em;
+  }
+  h1 { margin: 6px 0 10px; font-size: 40px; line-height: 1.15; }
+  h2 { margin: 0 0 14px; font-size: 24px; }
+  p { margin: 6px 0; }
+  .muted { color: var(--muted); }
+  .kicker {
+    margin: 0; color: var(--accent-deep); font-size: 13px; font-weight: 700;
+    letter-spacing: 0.14em; text-transform: uppercase;
+  }
+  .lede { font-size: 18.5px; max-width: 60ch; }
+  nav.toc { display: flex; flex-wrap: wrap; gap: 8px; margin: 0 0 22px; }
+  nav.toc a {
+    color: var(--ink); text-decoration: none; font-size: 13px; font-weight: 600;
+    border: 1px solid var(--line); border-radius: 999px; padding: 6px 14px; background: var(--card);
+  }
+  nav.toc a:hover { border-color: var(--accent); color: var(--accent-deep); }
+  header.hero, section {
+    background: var(--card); border: 1px solid var(--line); border-radius: 14px;
+    padding: 28px 32px; margin-bottom: 20px;
+  }
+  .badges { margin-top: 14px; display: flex; flex-wrap: wrap; gap: 8px; }
+  .badge {
+    display: inline-block; border-radius: 999px; padding: 2px 11px;
+    font-size: 12.5px; font-weight: 600; border: 1px solid var(--line); background: var(--bg);
+  }
+  .badge-hero { color: var(--accent-deep); border-color: #E5C8BA; background: #F7EDE7; }
+  .badge-done { color: var(--done); border-color: #C4D9C9; background: #EDF4EE; }
+  .badge-todo { color: var(--warn); border-color: #E4D2A8; background: #F8F1DE; }
+  .badge-manual { color: var(--accent-deep); border-color: #E5C8BA; background: #F7EDE7; }
+  .badge-error { color: var(--bad); border-color: #E7C2BB; background: #F9ECE9; }
+  .readiness { margin-top: 18px; }
+  .readiness-track { height: 10px; border-radius: 999px; background: #E6E2D6; overflow: hidden; }
+  .readiness-fill { height: 100%; border-radius: 999px; background: var(--accent); }
+  ol.steps, ul.steps { margin: 0; padding: 0 0 0 2px; list-style: none; }
+  .steps li { border-top: 1px solid var(--line); padding: 14px 2px; }
+  .steps li:first-child { border-top: none; padding-top: 4px; }
+  .step-heading { display: flex; align-items: center; gap: 10px; margin-bottom: 2px; }
+  .recipe-row { border-top: 1px solid var(--line); padding: 12px 0; }
+  .recipe-row:first-of-type { border-top: none; }
+  .recipe-note { font-size: 14px; color: var(--muted); margin-bottom: 6px; }
+  .recipe-command {
+    display: flex; align-items: center; gap: 10px; padding: 10px 14px; margin-top: 8px;
+    border-radius: 9px; background: #191817; color: #F5F1E8; overflow-x: auto;
+  }
+  .recipe-command code { flex: 1 1 auto; white-space: pre; }
+  button.copy {
+    flex: 0 0 auto; border: 1px solid #4A4742; border-radius: 6px; cursor: pointer;
+    background: transparent; color: #D8D2C4; font-size: 12px; font-weight: 600; padding: 4px 10px;
+  }
+  button.copy:hover { border-color: var(--accent); color: #F5F1E8; }
+  code { font: 13.5px/1.5 ui-monospace, Consolas, "Cascadia Mono", monospace; }
+  table { width: 100%; border-collapse: collapse; }
+  th, td { text-align: left; padding: 9px 10px; border-top: 1px solid var(--line); vertical-align: top; }
+  thead th { border-top: none; font-size: 13px; color: var(--muted); font-weight: 600; }
+  td.raw { overflow-wrap: anywhere; }
+  ul.plain-list { margin: 8px 0 0; padding-left: 4px; list-style: none; }
+  ul.plain-list li { padding: 5px 0; }
+  .stack-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(230px, 1fr)); gap: 12px; }
+  .stack-cell {
+    border: 1px solid var(--line); border-radius: 10px; background: var(--bg);
+    padding: 12px 14px; display: flex; flex-direction: column; gap: 4px;
+  }
+  .stack-cell span { color: var(--muted); font-size: 13.5px; }
+  .glossary-grid { grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); }
+  footer { text-align: center; color: var(--muted); font-size: 13px; padding: 10px 0 26px; }
+  @media print {
+    body { background: #fff; padding: 0; }
+    header.hero, section { border: none; padding: 12px 0; break-inside: avoid; }
+    nav.toc, button.copy { display: none; }
+  }
+`;
+var COPY_SCRIPT = `
+  document.addEventListener('click', function (event) {
+    var button = event.target.closest('button.copy');
+    if (!button || !navigator.clipboard) return;
+    navigator.clipboard.writeText(button.getAttribute('data-copy') || '').then(function () {
+      var original = button.textContent;
+      button.textContent = 'Copied!';
+      setTimeout(function () { button.textContent = original; }, 1600);
+    });
+  });
+`;
+function renderPassportHtml(options) {
+  const { scan, warnings, plan, version } = options;
+  const generatedAt = options.generatedAt ?? /* @__PURE__ */ new Date();
+  const name = escapeHtml(scan.projectName);
+  const generatedOn = generatedAt.toISOString().slice(0, 10);
+  const quickStart = quickStartSection(scan);
+  const requirements = requirementsSection(scan);
+  const stack = stackSection(scan);
+  const docker = dockerSection(scan);
+  const readinessLabel = plan.ready ? "Ready to run" : `${plan.readiness}% ready \u2014 ${escapeHtml(plan.summary)}`;
+  const tocEntries = [];
+  if (quickStart !== "") tocEntries.push(["#quick-start", "Quick start"]);
+  if (requirements !== "") tocEntries.push(["#requirements", "What you need"]);
+  tocEntries.push(["#setup", "Setup steps"]);
+  if (stack !== "") tocEntries.push(["#stack", "Tech stack"]);
+  tocEntries.push(["#commands", "Commands"]);
+  tocEntries.push(["#settings", "Settings"]);
+  tocEntries.push(["#troubleshooting", "Troubleshooting"]);
+  tocEntries.push(["#glossary", "Glossary"]);
+  const toc = tocEntries.map(([href, label]) => `    <a href="${href}">${label}</a>`).join("\n");
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light">
+<title>${name} \u2014 Project Passport</title>
+<style>${PASSPORT_CSS}</style>
+</head>
+<body>
+<main>
+  <header class="hero">
+    <p class="kicker">Project Passport</p>
+    <h1>${name}</h1>
+    <p class="lede">${escapeHtml(describeProject(scan))}</p>
+    <div class="badges">
+          ${heroBadges(scan)}
+    </div>
+    <div class="readiness">
+      <p class="muted">${readinessLabel}</p>
+      <div class="readiness-track"><div class="readiness-fill" style="width:${plan.readiness}%"></div></div>
+    </div>
+  </header>
+
+  <nav class="toc">
+${toc}
+  </nav>
+
+${quickStart}
+${requirements}
+  <section id="setup">
+    <h2>Setup, step by step</h2>
+    <p class="muted">The detailed version of the quick start. Anything marked \u201CDone\u201D was already true when this passport was generated.</p>
+    ${stepsSection(plan, scan)}
+  </section>
+
+${stack}
+  <section id="commands">
+    <h2>Every command, explained</h2>
+    ${scriptsSection(scan)}
+  </section>
+
+  <section id="settings">
+    <h2>Settings this project needs</h2>
+    ${envSection(scan)}
+  </section>
+
+  <section id="ports">
+    <h2>Network ports</h2>
+    ${portsSection(scan)}
+  </section>
+
+${docker}
+  <section id="health">
+    <h2>Health check</h2>
+    ${healthSection(warnings)}
+  </section>
+
+${troubleshootingSection(scan)}
+${glossarySection(scan)}
+  <footer>
+    Generated by DevSurface v${escapeHtml(version)} on ${generatedOn} \xB7
+    Everything was collected locally. No secrets, tokens, or .env values are included.
+  </footer>
+</main>
+<script>${COPY_SCRIPT}</script>
+</body>
+</html>
+`;
+}
+
+// src/version.ts
+var DEV_SURFACE_VERSION = "0.7.1";
+
+// src/cli/commands/passport.ts
+async function passportCommand(cwd = process.cwd(), outFile) {
+  const scan = await scanProject(cwd);
+  const warnings = await runDoctor(cwd, scan);
+  const plan = buildOnboardingPlan(scan, warnings);
+  const html = renderPassportHtml({ scan, warnings, plan, version: DEV_SURFACE_VERSION });
+  const target = path13.resolve(cwd, outFile ?? "devsurface-passport.html");
+  await fs13.writeFile(target, html, "utf8");
+  console.log(pc4.bold(`Passport created for ${safeDisplayText(scan.projectName)}`));
+  console.log(`Saved to ${safeDisplayText(target)}`);
+  console.log(
+    pc4.dim("Open it in any browser or share it \u2014 it works offline and contains no secrets.")
+  );
+}
+
 // src/cli/commands/run.ts
+import pc5 from "picocolors";
 async function runCommand(script, cwd = process.cwd()) {
   const scan = await scanProject(cwd);
   if (scan.scripts[script] !== void 0) {
@@ -2029,7 +2938,7 @@ async function runCommand(script, cwd = process.cwd()) {
   const configuredCommand = scan.config?.config.commands?.[script] ?? scan.presetCommands[script];
   if (configuredCommand !== void 0) {
     if (isDangerousCommand(configuredCommand)) {
-      console.error(pc4.red(`Refusing to run dangerous command "${safeDisplayText(script)}".`));
+      console.error(pc5.red(`Refusing to run dangerous command "${safeDisplayText(script)}".`));
       process.exitCode = 1;
       return;
     }
@@ -2046,17 +2955,17 @@ async function runCommand(script, cwd = process.cwd()) {
     ...Object.keys(scan.presetCommands)
   ];
   const hint = available.length > 0 ? ` Available commands: ${safeDisplayList(available)}.` : "";
-  console.error(pc4.red(`Command "${safeDisplayText(script)}" was not found.${hint}`));
+  console.error(pc5.red(`Command "${safeDisplayText(script)}" was not found.${hint}`));
   process.exitCode = 1;
 }
 
 // src/cli/commands/scan.ts
-import pc5 from "picocolors";
+import pc6 from "picocolors";
 function formatList(values) {
   return safeDisplayList(values);
 }
 function printScanResult(scan) {
-  console.log(pc5.bold(`Project:   ${safeDisplayText(scan.projectName)}`));
+  console.log(pc6.bold(`Project:   ${safeDisplayText(scan.projectName)}`));
   console.log(`Language:  ${formatList(scan.language.detected) || "unknown"}`);
   console.log(`Type:      ${safeDisplayText(scan.framework?.type ?? "Unknown")}`);
   console.log(`Manager:   ${safeDisplayText(scan.packageManager ?? "unknown")}`);
@@ -2083,35 +2992,35 @@ async function scanCommand(cwd = process.cwd()) {
 }
 
 // src/cli/commands/start.ts
-import pc6 from "picocolors";
+import pc7 from "picocolors";
 
 // node_modules/open/index.js
 import process7 from "process";
 import { Buffer as Buffer2 } from "buffer";
-import path13 from "path";
+import path14 from "path";
 import { fileURLToPath } from "url";
 import { promisify as promisify5 } from "util";
 import childProcess from "child_process";
-import fs17, { constants as fsConstants2 } from "fs/promises";
+import fs18, { constants as fsConstants2 } from "fs/promises";
 
 // node_modules/wsl-utils/index.js
 import process3 from "process";
-import fs16, { constants as fsConstants } from "fs/promises";
+import fs17, { constants as fsConstants } from "fs/promises";
 
 // node_modules/is-wsl/index.js
 import process2 from "process";
 import os2 from "os";
-import fs15 from "fs";
+import fs16 from "fs";
 
 // node_modules/is-inside-container/index.js
-import fs14 from "fs";
+import fs15 from "fs";
 
 // node_modules/is-docker/index.js
-import fs13 from "fs";
+import fs14 from "fs";
 var isDockerCached;
 function hasDockerEnv() {
   try {
-    fs13.statSync("/.dockerenv");
+    fs14.statSync("/.dockerenv");
     return true;
   } catch {
     return false;
@@ -2119,7 +3028,7 @@ function hasDockerEnv() {
 }
 function hasDockerCGroup() {
   try {
-    return fs13.readFileSync("/proc/self/cgroup", "utf8").includes("docker");
+    return fs14.readFileSync("/proc/self/cgroup", "utf8").includes("docker");
   } catch {
     return false;
   }
@@ -2135,7 +3044,7 @@ function isDocker() {
 var cachedResult;
 var hasContainerEnv = () => {
   try {
-    fs14.statSync("/run/.containerenv");
+    fs15.statSync("/run/.containerenv");
     return true;
   } catch {
     return false;
@@ -2160,12 +3069,12 @@ var isWsl = () => {
     return true;
   }
   try {
-    if (fs15.readFileSync("/proc/version", "utf8").toLowerCase().includes("microsoft")) {
+    if (fs16.readFileSync("/proc/version", "utf8").toLowerCase().includes("microsoft")) {
       return !isInsideContainer();
     }
   } catch {
   }
-  if (fs15.existsSync("/proc/sys/fs/binfmt_misc/WSLInterop") || fs15.existsSync("/run/WSL")) {
+  if (fs16.existsSync("/proc/sys/fs/binfmt_misc/WSLInterop") || fs16.existsSync("/run/WSL")) {
     return !isInsideContainer();
   }
   return false;
@@ -2183,14 +3092,14 @@ var wslDrivesMountPoint = /* @__PURE__ */ (() => {
     const configFilePath = "/etc/wsl.conf";
     let isConfigFileExists = false;
     try {
-      await fs16.access(configFilePath, fsConstants.F_OK);
+      await fs17.access(configFilePath, fsConstants.F_OK);
       isConfigFileExists = true;
     } catch {
     }
     if (!isConfigFileExists) {
       return defaultMountPoint;
     }
-    const configContent = await fs16.readFile(configFilePath, { encoding: "utf8" });
+    const configContent = await fs17.readFile(configFilePath, { encoding: "utf8" });
     const configMountPoint = /(?<!#.*)root\s*=\s*(?<mountPoint>.*)/g.exec(configContent);
     if (!configMountPoint) {
       return defaultMountPoint;
@@ -2344,8 +3253,8 @@ async function defaultBrowser2() {
 
 // node_modules/open/index.js
 var execFile5 = promisify5(childProcess.execFile);
-var __dirname = path13.dirname(fileURLToPath(import.meta.url));
-var localXdgOpenPath = path13.join(__dirname, "xdg-open");
+var __dirname = path14.dirname(fileURLToPath(import.meta.url));
+var localXdgOpenPath = path14.join(__dirname, "xdg-open");
 var { platform, arch } = process7;
 async function getWindowsDefaultBrowserFromWsl() {
   const powershellPath = await powerShellPath();
@@ -2495,7 +3404,7 @@ var baseOpen = async (options) => {
       const isBundled = !__dirname || __dirname === "/";
       let exeLocalXdgOpen = false;
       try {
-        await fs17.access(localXdgOpenPath, fsConstants2.X_OK);
+        await fs18.access(localXdgOpenPath, fsConstants2.X_OK);
         exeLocalXdgOpen = true;
       } catch {
       }
@@ -2600,8 +3509,8 @@ defineLazyProperty(apps, "browserPrivate", () => "browserPrivate");
 var open_default = open;
 
 // src/server/index.ts
-import { promises as fs21 } from "fs";
-import path17 from "path";
+import { promises as fs23 } from "fs";
+import path19 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { createAdaptorServer } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
@@ -2609,7 +3518,7 @@ import { Hono } from "hono";
 
 // src/core/process/manager.ts
 import { EventEmitter } from "events";
-import spawn3 from "cross-spawn";
+import spawn4 from "cross-spawn";
 var LOG_MESSAGE_LIMIT = 16384;
 var LOG_ENTRY_LIMIT = 1e3;
 function killChildProcessTree(child) {
@@ -2618,7 +3527,7 @@ function killChildProcessTree(child) {
     return;
   }
   if (process.platform === "win32") {
-    const result = spawn3.sync("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+    const result = spawn4.sync("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
       stdio: "ignore",
       windowsHide: true
     });
@@ -2634,7 +3543,7 @@ var ProcessManager = class extends EventEmitter {
   logs = [];
   cleanupInstalled = false;
   start(options) {
-    const child = spawn3(options.command, options.args, {
+    const child = spawn4(options.command, options.args, {
       cwd: options.cwd,
       shell: false,
       windowsHide: true
@@ -2751,16 +3660,16 @@ var ProcessManager = class extends EventEmitter {
 
 // src/core/hub/registry.ts
 import { createHash } from "crypto";
-import { promises as fs19 } from "fs";
+import { promises as fs20 } from "fs";
 import os3 from "os";
-import path15 from "path";
+import path16 from "path";
 
 // src/core/hub/workspaceRoots.ts
-import { promises as fs18 } from "fs";
-import path14 from "path";
+import { promises as fs19 } from "fs";
+import path15 from "path";
 function isWithinRoot8(root, target) {
-  const relative = path14.relative(root, target);
-  return relative === "" || !relative.startsWith("..") && !path14.isAbsolute(relative);
+  const relative = path15.relative(root, target);
+  return relative === "" || !relative.startsWith("..") && !path15.isAbsolute(relative);
 }
 async function configuredWorkspaceRoots() {
   const raw = process.env.DEVSURFACE_WORKSPACE_ROOTS;
@@ -2774,7 +3683,7 @@ async function configuredWorkspaceRoots() {
       continue;
     }
     try {
-      roots.push(await fs18.realpath(path14.resolve(trimmed)));
+      roots.push(await fs19.realpath(path15.resolve(trimmed)));
     } catch {
     }
   }
@@ -2795,16 +3704,16 @@ async function assertWithinWorkspaceRoots(targetPath) {
 
 // src/core/hub/registry.ts
 function workspaceId(realPath) {
-  const base = path15.basename(realPath).replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 32) || "workspace";
+  const base = path16.basename(realPath).replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 32) || "workspace";
   const hash = createHash("sha256").update(realPath).digest("hex").slice(0, 6);
   return `${base}-${hash}`;
 }
 function defaultDataDir() {
-  return process.env.DEVSURFACE_DATA_DIR ?? path15.join(os3.homedir(), ".devsurface");
+  return process.env.DEVSURFACE_DATA_DIR ?? path16.join(os3.homedir(), ".devsurface");
 }
 async function readPackageName(dirPath) {
   try {
-    const raw = JSON.parse(await fs19.readFile(path15.join(dirPath, "package.json"), "utf8"));
+    const raw = JSON.parse(await fs20.readFile(path16.join(dirPath, "package.json"), "utf8"));
     return typeof raw?.name === "string" && raw.name.length > 0 ? raw.name : null;
   } catch {
     return null;
@@ -2815,7 +3724,7 @@ var WorkspaceRegistry = class {
   seeded = false;
   constructor(dataDir) {
     const dir = dataDir ?? defaultDataDir();
-    this.filePath = path15.join(dir, "workspaces.json");
+    this.filePath = path16.join(dir, "workspaces.json");
   }
   async list() {
     await this.seedFromEnv();
@@ -2829,7 +3738,7 @@ var WorkspaceRegistry = class {
     if (existing) {
       return existing;
     }
-    const name = await readPackageName(realDir) ?? path15.basename(realDir);
+    const name = await readPackageName(realDir) ?? path16.basename(realDir);
     const entry = {
       id: workspaceId(realDir),
       name,
@@ -2851,7 +3760,7 @@ var WorkspaceRegistry = class {
   }
   async findByPath(dirPath) {
     try {
-      const realDir = await fs19.realpath(path15.resolve(dirPath));
+      const realDir = await fs20.realpath(path16.resolve(dirPath));
       const entries = await this.read();
       return entries.find((entry) => entry.path === realDir) ?? null;
     } catch {
@@ -2879,9 +3788,9 @@ var WorkspaceRegistry = class {
     }
   }
   async resolveDir(dirPath) {
-    const resolved = path15.resolve(dirPath);
-    const realDir = await fs19.realpath(resolved);
-    const stat = await fs19.stat(realDir);
+    const resolved = path16.resolve(dirPath);
+    const realDir = await fs20.realpath(resolved);
+    const stat = await fs20.stat(realDir);
     if (!stat.isDirectory()) {
       throw new Error(`${dirPath} is not a directory.`);
     }
@@ -2889,7 +3798,7 @@ var WorkspaceRegistry = class {
   }
   async read() {
     try {
-      const content = await fs19.readFile(this.filePath, "utf8");
+      const content = await fs20.readFile(this.filePath, "utf8");
       const parsed = JSON.parse(content);
       return Array.isArray(parsed) ? parsed : [];
     } catch {
@@ -2897,8 +3806,8 @@ var WorkspaceRegistry = class {
     }
   }
   async write(entries) {
-    await fs19.mkdir(path15.dirname(this.filePath), { recursive: true });
-    await fs19.writeFile(this.filePath, JSON.stringify(entries, null, 2) + "\n", {
+    await fs20.mkdir(path16.dirname(this.filePath), { recursive: true });
+    await fs20.writeFile(this.filePath, JSON.stringify(entries, null, 2) + "\n", {
       encoding: "utf8",
       mode: 384
     });
@@ -2982,13 +3891,92 @@ var Hub = class {
 };
 
 // src/server/routes/api.ts
-import { constants as constants2, existsSync } from "fs";
-import { promises as fs20 } from "fs";
-import path16 from "path";
-import spawn4 from "cross-spawn";
+import { constants as constants3, existsSync } from "fs";
+import { promises as fs22 } from "fs";
+import path18 from "path";
+import spawn5 from "cross-spawn";
 
-// src/version.ts
-var DEV_SURFACE_VERSION = "0.7.1";
+// src/core/env/write.ts
+import { constants as constants2, promises as fs21 } from "fs";
+import path17 from "path";
+function isValidEnvKey(key) {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && key.length <= 128;
+}
+function isValidEnvValue(value) {
+  if (value.length > 4096) {
+    return false;
+  }
+  for (const character of value) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code < 32 || code === 127) {
+      return false;
+    }
+  }
+  return true;
+}
+function formatEnvLine(key, value) {
+  if (value === "" || /[\s#'"\\]/.test(value)) {
+    const escaped = value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+    return `${key}="${escaped}"`;
+  }
+  return `${key}=${value}`;
+}
+function applyEnvValue(content, key, value) {
+  const lines = content.split(/\r?\n/);
+  const prefix = new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=`);
+  const index = lines.findIndex((line) => prefix.test(line));
+  if (index >= 0) {
+    lines[index] = formatEnvLine(key, value);
+    return { content: lines.join("\n"), action: "updated" };
+  }
+  const body = content.length === 0 || content.endsWith("\n") ? content : `${content}
+`;
+  return { content: `${body}${formatEnvLine(key, value)}
+`, action: "added" };
+}
+function isWithinRoot9(root, target) {
+  const relative = path17.relative(path17.resolve(root), path17.resolve(target));
+  return relative === "" || !relative.startsWith("..") && !path17.isAbsolute(relative);
+}
+async function setEnvValue(options) {
+  const { root, key, value } = options;
+  if (!isValidEnvKey(key)) {
+    return { ok: false, error: "Invalid key name." };
+  }
+  if (!isValidEnvValue(value)) {
+    return { ok: false, error: "Value must be a single line under 4096 characters." };
+  }
+  const target = options.localPath ?? path17.join(root, ".env");
+  if (!isWithinRoot9(root, target)) {
+    return { ok: false, error: "The env file must live inside the project." };
+  }
+  try {
+    const realParent = await fs21.realpath(path17.dirname(target));
+    const realRoot = await fs21.realpath(root);
+    if (!isWithinRoot9(realRoot, realParent)) {
+      return { ok: false, error: "The env file must live inside the project." };
+    }
+    let current = "";
+    try {
+      current = await fs21.readFile(target, "utf8");
+    } catch {
+    }
+    const next = applyEnvValue(current, key, value);
+    const handle2 = await fs21.open(
+      target,
+      constants2.O_CREAT | constants2.O_WRONLY | constants2.O_TRUNC,
+      384
+    );
+    try {
+      await handle2.writeFile(next.content, "utf8");
+    } finally {
+      await handle2.close();
+    }
+    return { ok: true, action: next.action };
+  } catch {
+    return { ok: false, error: "Could not write the env file." };
+  }
+}
 
 // src/server/localAccess.ts
 var LOCAL_HOSTNAMES = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "::1"]);
@@ -3174,9 +4162,9 @@ function isAllowedTerminalCommand(command) {
 }
 
 // src/server/routes/api.ts
-function isWithinRoot9(root, target) {
-  const relative = path16.relative(path16.resolve(root), path16.resolve(target));
-  return relative === "" || !relative.startsWith("..") && !path16.isAbsolute(relative);
+function isWithinRoot10(root, target) {
+  const relative = path18.relative(path18.resolve(root), path18.resolve(target));
+  return relative === "" || !relative.startsWith("..") && !path18.isAbsolute(relative);
 }
 function isAllowedMutationOrigin(requestUrl, origin) {
   if (origin === null) {
@@ -3208,37 +4196,37 @@ function hasMutationIntent(intent) {
   return intent === "dashboard";
 }
 async function realPathWithinRoot(root, target) {
-  if (!isWithinRoot9(root, target)) {
+  if (!isWithinRoot10(root, target)) {
     return false;
   }
   try {
-    const [realRoot, realTarget] = await Promise.all([fs20.realpath(root), fs20.realpath(target)]);
-    return isWithinRoot9(realRoot, realTarget);
+    const [realRoot, realTarget] = await Promise.all([fs22.realpath(root), fs22.realpath(target)]);
+    return isWithinRoot10(realRoot, realTarget);
   } catch {
     return false;
   }
 }
 async function writableDestinationWithinRoot(root, destination) {
-  if (!isWithinRoot9(root, destination)) {
+  if (!isWithinRoot10(root, destination)) {
     return false;
   }
   try {
     const [realRoot, realParent] = await Promise.all([
-      fs20.realpath(root),
-      fs20.realpath(path16.dirname(destination))
+      fs22.realpath(root),
+      fs22.realpath(path18.dirname(destination))
     ]);
-    return isWithinRoot9(realRoot, realParent);
+    return isWithinRoot10(realRoot, realParent);
   } catch {
     return false;
   }
 }
 async function copyFileExclusive(source, destination) {
-  const content = await fs20.readFile(source);
+  const content = await fs22.readFile(source);
   let handle2 = null;
   try {
-    handle2 = await fs20.open(
+    handle2 = await fs22.open(
       destination,
-      constants2.O_CREAT | constants2.O_EXCL | constants2.O_WRONLY,
+      constants3.O_CREAT | constants3.O_EXCL | constants3.O_WRONLY,
       384
     );
     await handle2.writeFile(content);
@@ -3263,15 +4251,15 @@ function resolveCommandPromptExecutable() {
   return process.env.ComSpec ?? "cmd.exe";
 }
 function findExecutable(command) {
-  if (path16.isAbsolute(command)) {
+  if (path18.isAbsolute(command)) {
     return existsSync(command) ? command : null;
   }
   const pathValue = process.env.PATH ?? "";
-  for (const directory of pathValue.split(path16.delimiter)) {
+  for (const directory of pathValue.split(path18.delimiter)) {
     if (directory.length === 0) {
       continue;
     }
-    const candidate = path16.join(directory, command);
+    const candidate = path18.join(directory, command);
     if (existsSync(candidate)) {
       return candidate;
     }
@@ -3279,7 +4267,7 @@ function findExecutable(command) {
   return null;
 }
 function launchDetached(command, args, root) {
-  const child = spawn4(command, args, {
+  const child = spawn5(command, args, {
     cwd: root,
     detached: true,
     stdio: "ignore",
@@ -3354,6 +4342,33 @@ async function onboardingForRoot(root) {
   const warnings = await runDoctor(root, scan);
   return buildOnboardingPlan(scan, warnings);
 }
+async function passportResponse(root, context) {
+  const scan = await scanProject(root);
+  const warnings = await runDoctor(root, scan);
+  const plan = buildOnboardingPlan(scan, warnings);
+  const html = renderPassportHtml({ scan, warnings, plan, version: DEV_SURFACE_VERSION });
+  if (context.req.query("download") === "1") {
+    const safeName = scan.projectName.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 60) || "project";
+    context.header("Content-Disposition", `attachment; filename="${safeName}-passport.html"`);
+  }
+  return await context.html(html);
+}
+async function handleEnvSet(root, body) {
+  if (body === null || typeof body.key !== "string" || typeof body.value !== "string") {
+    return { status: 400, payload: { error: "key and value are required." } };
+  }
+  const scan = await scanProject(root);
+  const result = await setEnvValue({
+    root,
+    localPath: scan.env?.localPath ?? null,
+    key: body.key,
+    value: body.value
+  });
+  if (!result.ok) {
+    return { status: 400, payload: { error: result.error } };
+  }
+  return { status: 200, payload: { status: result.action, key: body.key } };
+}
 function registerWorkspaceRoutes(app, resolveWorkspace) {
   app.get("/api/workspaces/:id/project", async (context) => {
     const ws = await resolveWorkspace(context.req.param("id"));
@@ -3370,6 +4385,11 @@ function registerWorkspaceRoutes(app, resolveWorkspace) {
     if (!ws) return context.json({ error: "Workspace not found." }, 404);
     return context.json(await onboardingForRoot(ws.root));
   });
+  app.get("/api/workspaces/:id/passport", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
+    return passportResponse(ws.root, context);
+  });
   app.get("/api/workspaces/:id/processes", async (context) => {
     const ws = await resolveWorkspace(context.req.param("id"));
     if (!ws) return context.json({ error: "Workspace not found." }, 404);
@@ -3498,7 +4518,7 @@ function registerWorkspaceRoutes(app, resolveWorkspace) {
   app.post("/api/workspaces/:id/open/package", async (context) => {
     const ws = await resolveWorkspace(context.req.param("id"));
     if (!ws) return context.json({ error: "Workspace not found." }, 404);
-    const packagePath = path16.join(ws.root, "package.json");
+    const packagePath = path18.join(ws.root, "package.json");
     if (!await realPathWithinRoot(ws.root, packagePath)) {
       return context.json({ error: "package.json was not found inside the project root." }, 404);
     }
@@ -3520,7 +4540,7 @@ function registerWorkspaceRoutes(app, resolveWorkspace) {
     if (examplePath === null) {
       return context.json({ error: ".env.example was not found." }, 404);
     }
-    const destination = localPath ?? path16.join(ws.root, scan.config?.config.env?.local ?? ".env");
+    const destination = localPath ?? path18.join(ws.root, scan.config?.config.env?.local ?? ".env");
     if (!await realPathWithinRoot(ws.root, examplePath) || !await writableDestinationWithinRoot(ws.root, destination)) {
       return context.json({ error: "Refusing to copy env files outside the project root." }, 400);
     }
@@ -3530,6 +4550,13 @@ function registerWorkspaceRoutes(app, resolveWorkspace) {
     }
     return context.json({ copied: true });
   });
+  app.post("/api/workspaces/:id/env/set", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
+    const body = await context.req.json().catch(() => null);
+    const result = await handleEnvSet(ws.root, body);
+    return context.json(result.payload, result.status);
+  });
   app.delete("/api/workspaces/:id/run/:pid", async (context) => {
     const ws = await resolveWorkspace(context.req.param("id"));
     if (!ws) return context.json({ error: "Workspace not found." }, 404);
@@ -3597,6 +4624,11 @@ function registerHubApiRoutes(app, options) {
     if (entries.length === 0) return context.json({ error: "No workspaces registered." }, 404);
     return context.json(await onboardingForRoot(hub.ensure(entries[0]).root));
   });
+  app.get("/api/passport", async (context) => {
+    const entries = await hub.registry.list();
+    if (entries.length === 0) return context.json({ error: "No workspaces registered." }, 404);
+    return passportResponse(hub.ensure(entries[0]).root, context);
+  });
   app.get("/api/processes", async (context) => {
     const entries = await hub.registry.list();
     if (entries.length === 0) return context.json([]);
@@ -3713,21 +4745,21 @@ function warnIfContainerRootsUnset(host) {
 }
 async function fileExists(filePath) {
   try {
-    await fs21.access(filePath);
+    await fs23.access(filePath);
     return true;
   } catch {
     return false;
   }
 }
 async function findWebDistDir() {
-  const moduleDir = path17.dirname(fileURLToPath2(import.meta.url));
+  const moduleDir = path19.dirname(fileURLToPath2(import.meta.url));
   const candidates = [
-    path17.join(moduleDir, "..", "web", "dist"),
-    path17.join(moduleDir, "..", "..", "src", "web", "dist"),
-    path17.join(moduleDir, "web", "dist")
+    path19.join(moduleDir, "..", "web", "dist"),
+    path19.join(moduleDir, "..", "..", "src", "web", "dist"),
+    path19.join(moduleDir, "web", "dist")
   ];
   for (const candidate of candidates) {
-    if (await fileExists(path17.join(candidate, "index.html"))) {
+    if (await fileExists(path19.join(candidate, "index.html"))) {
       return candidate;
     }
   }
@@ -3799,7 +4831,7 @@ async function mountWebUi(app) {
     app.use("/assets/*", serveStatic({ root: webDistDir }));
     app.get("/favicon.svg", serveStatic({ root: webDistDir }));
     app.get("*", async (context) => {
-      const html = await fs21.readFile(path17.join(webDistDir, "index.html"), "utf8");
+      const html = await fs23.readFile(path19.join(webDistDir, "index.html"), "utf8");
       return context.html(html);
     });
   } else {
@@ -3899,10 +4931,10 @@ function dashboardUrl(workspaceId2, port = DEFAULT_PORT, host = DEFAULT_HOST) {
 }
 
 // src/cli/commands/start.ts
-async function startCommand(options) {
+async function startCommand2(options) {
   const cwd = options.cwd ?? process.cwd();
   const port = options.port ?? 4567;
-  console.log(pc6.bold(`DevSurface v${DEV_SURFACE_VERSION}`));
+  console.log(pc7.bold(`DevSurface v${DEV_SURFACE_VERSION}`));
   console.log("Scanning project...\n");
   const scan = await scanProject(cwd);
   printScanResult(scan);
@@ -3910,7 +4942,7 @@ async function startCommand(options) {
   if (warnings.length > 0) {
     console.log("\nWarnings:");
     for (const item of warnings) {
-      const marker = item.severity === "error" ? pc6.red("!") : pc6.yellow("!");
+      const marker = item.severity === "error" ? pc7.red("!") : pc7.yellow("!");
       console.log(`  ${marker} ${item.title}`);
     }
   }
@@ -3919,8 +4951,8 @@ async function startCommand(options) {
     const registered = await registerWorkspaceRemotely(cwd, port);
     if (registered) {
       const url = dashboardUrl(registered.id, port);
-      console.log(`Workspace ${pc6.cyan(registered.name)} attached.`);
-      console.log(`Dashboard -> ${pc6.cyan(url)}`);
+      console.log(`Workspace ${pc7.cyan(registered.name)} attached.`);
+      console.log(`Dashboard -> ${pc7.cyan(url)}`);
       if (options.openBrowser !== false) {
         await open_default(url);
       }
@@ -3934,13 +4966,13 @@ async function startCommand(options) {
     initialWorkspace: cwd
   });
   console.log(`
-Dashboard running at -> ${pc6.cyan(server.url)}`);
+Dashboard running at -> ${pc7.cyan(server.url)}`);
 }
 
 // src/cli/commands/serve.ts
-import pc7 from "picocolors";
+import pc8 from "picocolors";
 async function serveCommand(options) {
-  console.log(pc7.bold(`DevSurface Hub v${DEV_SURFACE_VERSION}`));
+  console.log(pc8.bold(`DevSurface Hub v${DEV_SURFACE_VERSION}`));
   console.log("Starting hub server...\n");
   const server = await startHubServer({
     port: options.port,
@@ -3950,7 +4982,7 @@ async function serveCommand(options) {
   if (summaries.length > 0) {
     console.log(`Registered workspaces: ${summaries.length}`);
     for (const ws of summaries) {
-      console.log(`  ${pc7.cyan(ws.name)} -> ${ws.path}`);
+      console.log(`  ${pc8.cyan(ws.name)} -> ${ws.path}`);
     }
   } else {
     console.log(
@@ -3958,17 +4990,17 @@ async function serveCommand(options) {
     );
   }
   console.log(`
-Hub running at -> ${pc7.cyan(server.url)}`);
+Hub running at -> ${pc8.cyan(server.url)}`);
 }
 
 // src/cli/commands/workspace.ts
-import path18 from "path";
-import pc8 from "picocolors";
+import path20 from "path";
+import pc9 from "picocolors";
 async function workspaceAddCommand(dirPath) {
   const registry = new WorkspaceRegistry();
-  const target = path18.resolve(dirPath ?? process.cwd());
+  const target = path20.resolve(dirPath ?? process.cwd());
   const entry = await registry.add(target);
-  console.log(`Added workspace ${pc8.cyan(entry.name)} (${entry.id}) -> ${entry.path}`);
+  console.log(`Added workspace ${pc9.cyan(entry.name)} (${entry.id}) -> ${entry.path}`);
 }
 async function workspaceListCommand() {
   const registry = new WorkspaceRegistry();
@@ -3982,7 +5014,7 @@ async function workspaceListCommand() {
   console.log(`${entries.length} workspace${entries.length === 1 ? "" : "s"}:
 `);
   for (const entry of entries) {
-    console.log(`  ${pc8.cyan(entry.name)} (${entry.id})`);
+    console.log(`  ${pc9.cyan(entry.name)} (${entry.id})`);
     console.log(`    ${entry.path}`);
   }
 }
@@ -3990,7 +5022,7 @@ async function workspaceRemoveCommand(id) {
   const registry = new WorkspaceRegistry();
   const removed = await registry.remove(id);
   if (removed) {
-    console.log(`Removed workspace ${pc8.cyan(id)}.`);
+    console.log(`Removed workspace ${pc9.cyan(id)}.`);
   } else {
     console.error(`Workspace "${id}" not found.`);
     process.exitCode = 1;
@@ -4087,9 +5119,9 @@ function handle(command) {
     process.exitCode = 1;
   });
 }
-program.name("devsurface").description("Turn any Node.js repository into a local developer control panel.").version(DEV_SURFACE_VERSION).option("-p, --port <port>", "dashboard port", toPort, 4567).option("--no-open", "do not open the browser automatically").action((options) => {
+program.name("devsurface").description("Turn any Node.js repository into a local developer control panel.").version(DEV_SURFACE_VERSION).enablePositionalOptions().option("-p, --port <port>", "dashboard port", toPort, 4567).option("--no-open", "do not open the browser automatically").action((options) => {
   handle(
-    startCommand({
+    startCommand2({
       cwd: process.cwd(),
       port: options.port,
       openBrowser: options.open
@@ -4123,6 +5155,9 @@ program.command("doctor").description("Print setup health warnings.").action(()
 program.command("onboard").description("Print a guided setup checklist with readiness score.").action(() => {
   handle(onboardCommand(process.cwd()));
 });
+program.command("passport").description("Generate a shareable HTML onboarding report (Project Passport).").option("-o, --out <file>", "output file path", "devsurface-passport.html").action((options) => {
+  handle(passportCommand(process.cwd(), options.out));
+});
 program.command("init").description("Create a starter devsurface.config.json.").action(() => {
   handle(initCommand(process.cwd()));
 });