devsurface 0.4.0 → 0.6.0

package/dist/cli/index.js

@@ -7,8 +7,8 @@ import { Command } from "commander";
 import pc from "picocolors";
 
 // src/core/doctor/index.ts
-import { promises as fs9 } from "fs";
-import path9 from "path";
+import { promises as fs11 } from "fs";
+import path11 from "path";
 
 // src/core/documentation.ts
 function extractScriptReferences(content) {
@@ -32,8 +32,8 @@ function extractScriptReferences(content) {
 }
 
 // src/core/scanner/index.ts
-import { promises as fs8 } from "fs";
-import path8 from "path";
+import { promises as fs10 } from "fs";
+import path10 from "path";
 
 // src/core/config/load.ts
 import { promises as fs } from "fs";
@@ -75,6 +75,12 @@ var defaultConfig = {
   services: {
     docker: true
   },
+  setupGuide: [
+    "Copy .env.example to .env",
+    "Fill in required environment values",
+    "Install dependencies",
+    "Start the dev server"
+  ],
   docs: ""
 };
 
@@ -123,6 +129,33 @@ function toGroups(value, warnings) {
   }
   return groups;
 }
+var MAX_SETUP_GUIDE_STEPS = 24;
+var MAX_SETUP_GUIDE_STEP_LENGTH = 200;
+function toSetupGuide(value, warnings) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    warnings.push("setupGuide must be an array of strings.");
+    return void 0;
+  }
+  const steps = [];
+  for (const entry of value) {
+    if (typeof entry !== "string") {
+      warnings.push("setupGuide entries must be strings.");
+      continue;
+    }
+    const trimmed = entry.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+    steps.push(trimmed.slice(0, MAX_SETUP_GUIDE_STEP_LENGTH));
+  }
+  if (steps.length > MAX_SETUP_GUIDE_STEPS) {
+    warnings.push(`setupGuide may contain at most ${MAX_SETUP_GUIDE_STEPS} steps.`);
+  }
+  return steps.slice(0, MAX_SETUP_GUIDE_STEPS);
+}
 function toPorts(value, warnings) {
   if (value === void 0) {
     return void 0;
@@ -177,6 +210,7 @@ function validateConfig(raw) {
       ports: toPorts(raw.ports, warnings),
       env,
       services,
+      setupGuide: toSetupGuide(raw.setupGuide ?? raw.setup_guide, warnings),
       docs
     },
     warnings
@@ -836,9 +870,64 @@ async function detectGit(root) {
   }
 }
 
-// src/core/scanner/packageManager.ts
+// src/core/scanner/language.ts
 import { promises as fs6 } from "fs";
 import path6 from "path";
+var languageFiles = [
+  { language: "python", candidates: ["requirements.txt", "pyproject.toml", "Pipfile"] },
+  { language: "go", candidates: ["go.mod"] },
+  { language: "java", candidates: ["pom.xml", "build.gradle", "build.gradle.kts"] }
+];
+function isWithinRoot5(root, target) {
+  const relative = path6.relative(path6.resolve(root), path6.resolve(target));
+  return relative === "" || !relative.startsWith("..") && !path6.isAbsolute(relative);
+}
+async function safeFile(root, candidate) {
+  const filePath = path6.join(root, candidate);
+  try {
+    const [realRoot, stat, realPath] = await Promise.all([
+      fs6.realpath(root),
+      fs6.stat(filePath),
+      fs6.realpath(filePath)
+    ]);
+    if (stat.isFile() && isWithinRoot5(realRoot, realPath)) {
+      return realPath;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+async function detectProjectLanguage(root, packageJson) {
+  const detected = [];
+  const files = [];
+  if (packageJson !== null) {
+    detected.push("node");
+    files.push(packageJson.path);
+  }
+  for (const definition of languageFiles) {
+    let found = false;
+    for (const candidate of definition.candidates) {
+      const file = await safeFile(root, candidate);
+      if (file !== null) {
+        found = true;
+        files.push(file);
+      }
+    }
+    if (found) {
+      detected.push(definition.language);
+    }
+  }
+  return {
+    primary: detected[0] ?? null,
+    detected,
+    files
+  };
+}
+
+// src/core/scanner/packageManager.ts
+import { promises as fs7 } from "fs";
+import path7 from "path";
 var lockFiles = [
   { file: "pnpm-lock.yaml", manager: "pnpm" },
   { file: "yarn.lock", manager: "yarn" },
@@ -848,7 +937,7 @@ var lockFiles = [
 ];
 async function exists(filePath) {
   try {
-    await fs6.access(filePath);
+    await fs7.access(filePath);
     return true;
   } catch {
     return false;
@@ -856,7 +945,7 @@ async function exists(filePath) {
 }
 async function detectPackageManager(root) {
   for (const lockFile of lockFiles) {
-    if (await exists(path6.join(root, lockFile.file))) {
+    if (await exists(path7.join(root, lockFile.file))) {
       return lockFile.manager;
     }
   }
@@ -864,23 +953,23 @@ async function detectPackageManager(root) {
 }
 
 // src/core/scanner/packageJson.ts
-import { promises as fs7 } from "fs";
-import path7 from "path";
-function isWithinRoot5(root, target) {
-  const relative = path7.relative(root, target);
-  return relative === "" || !relative.startsWith("..") && !path7.isAbsolute(relative);
+import { promises as fs8 } from "fs";
+import path8 from "path";
+function isWithinRoot6(root, target) {
+  const relative = path8.relative(root, target);
+  return relative === "" || !relative.startsWith("..") && !path8.isAbsolute(relative);
 }
 async function readPackageJson(root) {
-  const packageJsonPath = path7.join(root, "package.json");
+  const packageJsonPath = path8.join(root, "package.json");
   try {
     const [realRoot, realPackageJsonPath] = await Promise.all([
-      fs7.realpath(root),
-      fs7.realpath(packageJsonPath)
+      fs8.realpath(root),
+      fs8.realpath(packageJsonPath)
     ]);
-    if (!isWithinRoot5(realRoot, realPackageJsonPath)) {
+    if (!isWithinRoot6(realRoot, realPackageJsonPath)) {
       return null;
     }
-    const content = await fs7.readFile(realPackageJsonPath, "utf8");
+    const content = await fs8.readFile(realPackageJsonPath, "utf8");
     const data = JSON.parse(content);
     return { path: realPackageJsonPath, data };
   } catch {
@@ -966,6 +1055,235 @@ async function detectPorts(ports) {
   );
 }
 
+// src/core/scanner/presets.ts
+import { promises as fs9 } from "fs";
+import path9 from "path";
+function dependencyNames(packageJson) {
+  const data = packageJson?.data;
+  return new Set(
+    Object.keys({
+      ...data?.dependencies,
+      ...data?.devDependencies,
+      ...data?.optionalDependencies,
+      ...data?.peerDependencies
+    })
+  );
+}
+function hasAnyDependency(dependencies, names) {
+  return names.some((name) => dependencies.has(name));
+}
+async function readIfPresent2(root, candidate) {
+  const filePath = path9.join(root, candidate);
+  try {
+    const [realRoot, realPath] = await Promise.all([fs9.realpath(root), fs9.realpath(filePath)]);
+    const relative = path9.relative(realRoot, realPath);
+    if (relative.startsWith("..") || path9.isAbsolute(relative)) {
+      return null;
+    }
+    return await fs9.readFile(realPath, "utf8");
+  } catch {
+    return null;
+  }
+}
+function completePreset(draft) {
+  return {
+    name: draft.name,
+    label: draft.label,
+    commands: draft.commands ?? {},
+    groups: draft.groups ?? {},
+    ports: draft.ports ?? []
+  };
+}
+function nodePresets(framework, packageJson) {
+  const detected = new Set(framework?.detected ?? []);
+  const dependencies = dependencyNames(packageJson);
+  const presets = [];
+  if (detected.has("Next.js")) {
+    presets.push({
+      name: "next",
+      label: "Next.js",
+      commands: {
+        "next:dev": "next dev",
+        "next:build": "next build",
+        "next:start": "next start"
+      },
+      groups: {
+        "Next.js": ["next:dev", "next:build", "next:start"]
+      },
+      ports: [3e3]
+    });
+  }
+  if (detected.has("Vite")) {
+    presets.push({
+      name: "vite",
+      label: "Vite",
+      commands: {
+        "vite:dev": "vite --host 127.0.0.1",
+        "vite:build": "vite build",
+        "vite:preview": "vite preview --host 127.0.0.1"
+      },
+      groups: {
+        Vite: ["vite:dev", "vite:build", "vite:preview"]
+      },
+      ports: [5173, 4173]
+    });
+  }
+  if (detected.has("NestJS")) {
+    presets.push({
+      name: "nestjs",
+      label: "NestJS",
+      commands: {
+        "nest:start": "nest start --watch",
+        "nest:build": "nest build"
+      },
+      groups: {
+        NestJS: ["nest:start", "nest:build"]
+      },
+      ports: [3e3]
+    });
+  }
+  if (detected.has("Remix")) {
+    presets.push({
+      name: "remix",
+      label: "Remix",
+      commands: {
+        "remix:dev": "remix vite:dev",
+        "remix:build": "remix vite:build"
+      },
+      groups: {
+        Remix: ["remix:dev", "remix:build"]
+      },
+      ports: [5173]
+    });
+  }
+  if (detected.has("Express") || detected.has("Fastify")) {
+    presets.push({
+      name: detected.has("Fastify") ? "fastify" : "express",
+      label: detected.has("Fastify") ? "Fastify" : "Express",
+      ports: [3e3]
+    });
+  }
+  if (detected.has("Prisma") || hasAnyDependency(dependencies, ["prisma", "@prisma/client"])) {
+    presets.push({
+      name: "prisma",
+      label: "Prisma",
+      commands: {
+        "prisma:migrate": "prisma migrate dev",
+        "prisma:studio": "prisma studio"
+      },
+      groups: {
+        Database: ["prisma:migrate", "prisma:studio"]
+      },
+      ports: [5555]
+    });
+  }
+  return presets.map(completePreset);
+}
+async function pythonPresets(root, language) {
+  if (!language.detected.includes("python")) {
+    return [];
+  }
+  const [requirements, pyproject, pipfile] = await Promise.all([
+    readIfPresent2(root, "requirements.txt"),
+    readIfPresent2(root, "pyproject.toml"),
+    readIfPresent2(root, "Pipfile")
+  ]);
+  const manifest = [requirements, pyproject, pipfile].filter(Boolean).join("\n").toLowerCase();
+  const commands = {};
+  const groups = {};
+  const ports = [];
+  if (requirements !== null) {
+    commands["python:install"] = "python -m pip install -r requirements.txt";
+    groups.Setup = ["python:install"];
+  }
+  if (manifest.includes("uvicorn") || manifest.includes("fastapi")) {
+    commands["python:dev"] = "uvicorn main:app --reload --host 127.0.0.1";
+    groups.Python = [...groups.Python ?? [], "python:dev"];
+    ports.push(8e3);
+  }
+  if (manifest.includes("flask")) {
+    commands["flask:dev"] = "flask --app app run --host 127.0.0.1";
+    groups.Python = [...groups.Python ?? [], "flask:dev"];
+    ports.push(5e3);
+  }
+  if (manifest.includes("django") || await readIfPresent2(root, "manage.py") !== null) {
+    commands["django:dev"] = "python manage.py runserver 127.0.0.1:8000";
+    commands["django:migrate"] = "python manage.py migrate";
+    groups.Python = [...groups.Python ?? [], "django:dev", "django:migrate"];
+    ports.push(8e3);
+  }
+  return [
+    completePreset({
+      name: "python",
+      label: "Python",
+      commands,
+      groups,
+      ports
+    })
+  ];
+}
+function goPresets(language) {
+  if (!language.detected.includes("go")) {
+    return [];
+  }
+  return [
+    completePreset({
+      name: "go",
+      label: "Go",
+      commands: {
+        "go:run": "go run .",
+        "go:build": "go build ./...",
+        "go:test": "go test ./..."
+      },
+      groups: {
+        Go: ["go:run", "go:build", "go:test"]
+      }
+    })
+  ];
+}
+async function javaPresets(language) {
+  if (!language.detected.includes("java")) {
+    return [];
+  }
+  const hasMaven = language.files.some((file) => path9.basename(file) === "pom.xml");
+  const hasGradle = language.files.some((file) => path9.basename(file).startsWith("build.gradle"));
+  const commands = {};
+  const groups = {};
+  if (hasMaven) {
+    commands["maven:test"] = "mvn test";
+    commands["maven:package"] = "mvn package";
+    groups.Maven = ["maven:test", "maven:package"];
+  }
+  if (hasGradle) {
+    commands["gradle:test"] = "gradle test";
+    commands["gradle:build"] = "gradle build";
+    groups.Gradle = ["gradle:test", "gradle:build"];
+  }
+  return [completePreset({ name: "java", label: "Java", commands, groups })];
+}
+async function detectPresets(options) {
+  return [
+    ...nodePresets(options.framework, options.packageJson),
+    ...await pythonPresets(options.root, options.language),
+    ...goPresets(options.language),
+    ...await javaPresets(options.language)
+  ].filter(
+    (preset) => Object.keys(preset.commands).length > 0 || Object.keys(preset.groups).length > 0 || preset.ports.length > 0
+  );
+}
+function mergePresetCommands(presets) {
+  return Object.assign({}, ...presets.map((preset) => preset.commands));
+}
+function mergePresetGroups(presets) {
+  const groups = {};
+  for (const preset of presets) {
+    for (const [group, commands] of Object.entries(preset.groups)) {
+      groups[group] = [...groups[group] ?? [], ...commands];
+    }
+  }
+  return groups;
+}
+
 // src/core/scanner/scripts.ts
 function extractScripts(packageJson) {
   if (!packageJson?.data.scripts || typeof packageJson.data.scripts !== "object" || Array.isArray(packageJson.data.scripts)) {
@@ -980,17 +1298,17 @@ function extractScripts(packageJson) {
 }
 
 // src/core/scanner/index.ts
-function isWithinRoot6(root, target) {
-  const relative = path8.relative(path8.resolve(root), path8.resolve(target));
-  return relative === "" || !relative.startsWith("..") && !path8.isAbsolute(relative);
+function isWithinRoot7(root, target) {
+  const relative = path10.relative(path10.resolve(root), path10.resolve(target));
+  return relative === "" || !relative.startsWith("..") && !path10.isAbsolute(relative);
 }
 async function findFirstFile(root, candidates) {
-  const resolvedRoot = await fs8.realpath(root).catch(() => path8.resolve(root));
+  const resolvedRoot = await fs10.realpath(root).catch(() => path10.resolve(root));
   for (const candidate of candidates) {
-    const filePath = path8.join(root, candidate);
+    const filePath = path10.join(root, candidate);
     try {
-      const [stat, realPath] = await Promise.all([fs8.stat(filePath), fs8.realpath(filePath)]);
-      if (stat.isFile() && isWithinRoot6(resolvedRoot, realPath)) {
+      const [stat, realPath] = await Promise.all([fs10.stat(filePath), fs10.realpath(filePath)]);
+      if (stat.isFile() && isWithinRoot7(resolvedRoot, realPath)) {
         return { path: realPath, exists: true };
       }
     } catch {
@@ -1002,15 +1320,25 @@ function configuredPorts(configPorts) {
   return Array.isArray(configPorts) ? configPorts : [];
 }
 async function scanProject(root = process.cwd()) {
-  const resolvedRoot = await fs8.realpath(root).catch(() => path8.resolve(root));
+  const resolvedRoot = await fs10.realpath(root).catch(() => path10.resolve(root));
   const config = await loadConfig(resolvedRoot);
   const packageJson = await readPackageJson(resolvedRoot);
   const scripts = extractScripts(packageJson) ?? {};
   const framework = detectFramework(packageJson);
+  const language = await detectProjectLanguage(resolvedRoot, packageJson);
+  const presets = await detectPresets({
+    root: resolvedRoot,
+    packageJson,
+    framework,
+    language
+  });
+  const presetCommands = mergePresetCommands(presets);
+  const presetGroups = mergePresetGroups(presets);
   const portsToProbe = [
     ...configuredPorts(config?.config.ports),
     ...inferPortsFromScripts(scripts),
-    ...defaultPortsForFramework(framework)
+    ...defaultPortsForFramework(framework),
+    ...presets.flatMap((preset) => preset.ports)
   ];
   const [packageManager, env, docker, git, ports, readme, license] = await Promise.all([
     detectPackageManager(resolvedRoot),
@@ -1023,14 +1351,18 @@ async function scanProject(root = process.cwd()) {
   ]);
   return {
     root: resolvedRoot,
-    projectName: config?.config.name ?? packageJson?.data.name ?? path8.basename(resolvedRoot),
+    projectName: config?.config.name ?? packageJson?.data.name ?? path10.basename(resolvedRoot),
     packageJson,
     packageManager: packageManager ?? (packageJson ? "npm" : null),
+    language,
     scripts,
     env,
     docker,
     git,
     framework,
+    presets,
+    presetCommands,
+    presetGroups,
     ports: ports ?? [],
     readme,
     license,
@@ -1041,18 +1373,18 @@ async function scanProject(root = process.cwd()) {
 // src/core/doctor/index.ts
 async function pathExists(filePath) {
   try {
-    await fs9.access(filePath);
+    await fs11.access(filePath);
     return true;
   } catch {
     return false;
   }
 }
-async function readIfPresent2(filePath) {
+async function readIfPresent3(filePath) {
   if (filePath === null) {
     return null;
   }
   try {
-    return await fs9.readFile(filePath, "utf8");
+    return await fs11.readFile(filePath, "utf8");
   } catch {
     return null;
   }
@@ -1068,7 +1400,9 @@ async function runDoctor(root = process.cwd(), scan) {
       warning("config-warning", "warning", "Config warning", configWarning, result.config?.path)
     );
   }
-  if (result.packageJson === null) {
+  const isNodeProject = result.language.detected.includes("node");
+  const hasKnownProjectLanguage = result.language.detected.length > 0;
+  if (result.packageJson === null && !hasKnownProjectLanguage) {
     warnings.push(
       warning(
         "missing-package-json",
@@ -1079,7 +1413,7 @@ async function runDoctor(root = process.cwd(), scan) {
     );
     return warnings;
   }
-  if (!await pathExists(path9.join(root, "node_modules", ".bin"))) {
+  if (isNodeProject && !await pathExists(path11.join(root, "node_modules", ".bin"))) {
     warnings.push(
       warning(
         "missing-node-modules",
@@ -1126,7 +1460,7 @@ async function runDoctor(root = process.cwd(), scan) {
       warning("missing-readme", "warning", "No README", "No README.md or README file was found.")
     );
   } else {
-    const readme = await readIfPresent2(result.readme.path);
+    const readme = await readIfPresent3(result.readme.path);
     if (readme !== null) {
       const references = extractScriptReferences(readme);
       const missingScripts = references.filter((script) => result.scripts[script] === void 0);
@@ -1162,7 +1496,7 @@ async function runDoctor(root = process.cwd(), scan) {
       )
     );
   }
-  if (result.scripts.test === void 0) {
+  if (isNodeProject && result.scripts.test === void 0) {
     warnings.push(
       warning(
         "missing-test-script",
@@ -1172,7 +1506,7 @@ async function runDoctor(root = process.cwd(), scan) {
       )
     );
   }
-  if (result.scripts.build === void 0) {
+  if (isNodeProject && result.scripts.build === void 0) {
     warnings.push(
       warning(
         "missing-build-script",
@@ -1233,25 +1567,204 @@ async function doctorCommand(cwd = process.cwd()) {
 }
 
 // src/cli/commands/init.ts
-import { promises as fs10 } from "fs";
-import path10 from "path";
+import { promises as fs12 } from "fs";
+import path12 from "path";
 import pc2 from "picocolors";
 async function initCommand(cwd = process.cwd()) {
-  const configPath = path10.join(cwd, CONFIG_FILE_NAME);
+  const configPath = path12.join(cwd, CONFIG_FILE_NAME);
   try {
-    await fs10.access(configPath);
+    await fs12.access(configPath);
     console.log(pc2.yellow(`${CONFIG_FILE_NAME} already exists.`));
     return;
   } catch {
-    await fs10.writeFile(configPath, `${JSON.stringify(defaultConfig, null, 2)}
+    await fs12.writeFile(configPath, `${JSON.stringify(defaultConfig, null, 2)}
 `, "utf8");
     console.log(pc2.green(`Created ${CONFIG_FILE_NAME}.`));
   }
 }
 
-// src/cli/commands/run.ts
+// src/cli/commands/onboard.ts
 import pc3 from "picocolors";
 
+// src/core/onboarding/index.ts
+function hasWarning(warnings, id) {
+  return warnings.some((warning2) => warning2.id === id);
+}
+function pickStartAction(scan) {
+  if (scan.scripts.dev !== void 0) {
+    return { kind: "run-script", label: "Start dev server", target: "dev" };
+  }
+  if (scan.scripts.start !== void 0) {
+    return { kind: "run-script", label: "Start app", target: "start" };
+  }
+  const configuredCommands = {
+    ...scan.presetCommands,
+    ...scan.config?.config.commands
+  };
+  for (const name of ["dev", "start", "serve"]) {
+    if (configuredCommands[name] !== void 0) {
+      return { kind: "run-command", label: `Run ${name}`, target: name };
+    }
+  }
+  return null;
+}
+function dockerStep(scan) {
+  const docker = scan.docker;
+  if (docker === null) {
+    return null;
+  }
+  const runningServices = docker.services.filter((service) => service.status === "running");
+  const allRunning = docker.services.length > 0 && runningServices.length === docker.services.length;
+  if (docker.daemonStatus !== "running") {
+    return {
+      id: "docker-start",
+      title: "Start Docker services",
+      description: docker.message ?? "A Docker Compose file was found, but the Docker engine is not running.",
+      status: "manual",
+      blocking: false,
+      action: { kind: "docker", label: "Open Services" }
+    };
+  }
+  if (docker.services.length === 0 || allRunning) {
+    return {
+      id: "docker-start",
+      title: "Start Docker services",
+      description: docker.services.length === 0 ? "Docker is running. No Compose services need to be started." : "All Docker Compose services are running.",
+      status: "done",
+      blocking: false
+    };
+  }
+  return {
+    id: "docker-start",
+    title: "Start Docker services",
+    description: `${runningServices.length}/${docker.services.length} Compose services running. Start the rest in Services.`,
+    status: "todo",
+    blocking: false,
+    action: { kind: "docker", label: "Open Services" }
+  };
+}
+function buildOnboardingPlan(scan, warnings) {
+  const steps = [];
+  const isNodeProject = scan.language.detected.includes("node");
+  if (isNodeProject && scan.packageJson !== null) {
+    const needsInstall = hasWarning(warnings, "missing-node-modules");
+    steps.push({
+      id: "install-dependencies",
+      title: "Install dependencies",
+      description: needsInstall ? "node_modules is missing. Install dependencies before running scripts." : "Dependencies are installed.",
+      status: needsInstall ? "todo" : "done",
+      blocking: true,
+      action: needsInstall ? { kind: "install", label: "Install" } : void 0
+    });
+  }
+  if (scan.env?.hasExample) {
+    const missingLocal = !scan.env.hasLocal;
+    steps.push({
+      id: "create-env",
+      title: "Create .env file",
+      description: missingLocal ? ".env.example exists but the local .env file is missing." : ".env is present.",
+      status: missingLocal ? "todo" : "done",
+      blocking: true,
+      action: missingLocal ? { kind: "env-copy", label: "Copy .env" } : void 0
+    });
+    if (scan.env.hasLocal) {
+      const unset = [.../* @__PURE__ */ new Set([...scan.env.missingKeys, ...scan.env.emptyKeys])];
+      steps.push({
+        id: "fill-env",
+        title: "Fill in environment values",
+        description: unset.length > 0 ? `Set values for: ${unset.join(", ")}. Values are intentionally hidden.` : "All environment keys from the example are present.",
+        status: unset.length > 0 ? "manual" : "done",
+        blocking: true
+      });
+    }
+  }
+  const docker = dockerStep(scan);
+  if (docker !== null) {
+    steps.push(docker);
+  }
+  const portsInUse = scan.ports.filter((probe) => probe.inUse);
+  if (portsInUse.length > 0) {
+    steps.push({
+      id: "free-ports",
+      title: "Resolve port conflicts",
+      description: `Already in use: ${portsInUse.map((probe) => probe.port).join(", ")}. Stop the conflicting process or change the port.`,
+      status: "manual",
+      blocking: false
+    });
+  }
+  for (const [index, entry] of (scan.config?.config.setupGuide ?? []).entries()) {
+    steps.push({
+      id: `guide-${index}`,
+      title: entry,
+      description: "From the project setup guide.",
+      status: "manual",
+      blocking: false
+    });
+  }
+  const docs = scan.config?.config.docs;
+  if (typeof docs === "string" && docs.length > 0 && isSafeHttpUrl(docs)) {
+    steps.push({
+      id: "read-docs",
+      title: "Read the project docs",
+      description: docs,
+      status: "manual",
+      blocking: false,
+      action: { kind: "open-docs", label: "Open docs", target: docs }
+    });
+  }
+  const startAction = pickStartAction(scan);
+  if (startAction !== null) {
+    steps.push({
+      id: "start-app",
+      title: "Start the app",
+      description: "Run the development server once setup is complete.",
+      status: "todo",
+      blocking: false,
+      action: startAction
+    });
+  }
+  const blocking = steps.filter((step) => step.blocking);
+  const blockingDone = blocking.filter((step) => step.status === "done");
+  const readiness = blocking.length === 0 ? 100 : Math.round(blockingDone.length / blocking.length * 100);
+  const ready = readiness === 100;
+  const remaining = blocking.length - blockingDone.length;
+  const summary = ready ? "Project is ready to run." : `${remaining} setup step${remaining === 1 ? "" : "s"} remaining before the project is ready.`;
+  return { steps, readiness, ready, summary };
+}
+
+// src/cli/commands/onboard.ts
+function statusGlyph(status) {
+  if (status === "done") {
+    return pc3.green("[x]");
+  }
+  if (status === "todo") {
+    return pc3.yellow("[ ]");
+  }
+  return pc3.cyan("[~]");
+}
+async function onboardCommand(cwd = process.cwd()) {
+  const scan = await scanProject(cwd);
+  const warnings = await runDoctor(cwd, scan);
+  const plan = buildOnboardingPlan(scan, warnings);
+  console.log(pc3.bold(`Onboarding ${safeDisplayText(scan.projectName)}`));
+  console.log(`${plan.readiness}% ready \u2014 ${safeDisplayText(plan.summary)}`);
+  console.log("");
+  if (plan.steps.length === 0) {
+    console.log(pc3.green("No onboarding steps detected."));
+    return;
+  }
+  for (const step of plan.steps) {
+    console.log(`${statusGlyph(step.status)} ${pc3.bold(safeDisplayText(step.title))}`);
+    console.log(`    ${safeDisplayText(step.description)}`);
+    if (step.action && step.status !== "done") {
+      console.log(pc3.dim(`    \u2192 ${safeDisplayText(step.action.label)}`));
+    }
+  }
+}
+
+// src/cli/commands/run.ts
+import pc4 from "picocolors";
+
 // src/core/process/runner.ts
 import spawn2 from "cross-spawn";
 
@@ -1430,38 +1943,74 @@ async function runPackageScriptToTerminal(options) {
     });
   });
 }
+async function runConfiguredCommandToTerminal(options) {
+  const resolvedCommand = await resolveConfiguredCommand(options.cwd, options.command);
+  if (resolvedCommand === null) {
+    return 1;
+  }
+  return await new Promise((resolve) => {
+    const child = spawn2(resolvedCommand.command, resolvedCommand.args, {
+      cwd: options.cwd,
+      stdio: "inherit",
+      windowsHide: true
+    });
+    child.on("error", () => {
+      resolve(1);
+    });
+    child.on("close", (code) => {
+      resolve(code ?? 1);
+    });
+  });
+}
 
 // src/cli/commands/run.ts
 async function runCommand(script, cwd = process.cwd()) {
   const scan = await scanProject(cwd);
-  if (scan.packageJson === null) {
-    console.error(pc3.red("No package.json was found in this directory."));
-    process.exitCode = 1;
+  if (scan.scripts[script] !== void 0) {
+    const exitCode = await runPackageScriptToTerminal({
+      cwd,
+      packageManager: scan.packageManager,
+      script
+    });
+    process.exitCode = exitCode;
     return;
   }
-  if (scan.scripts[script] === void 0) {
-    console.error(pc3.red(`Script "${script}" was not found in package.json.`));
-    process.exitCode = 1;
+  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)}".`));
+      process.exitCode = 1;
+      return;
+    }
+    const exitCode = await runConfiguredCommandToTerminal({
+      cwd,
+      command: configuredCommand
+    });
+    process.exitCode = exitCode;
     return;
   }
-  const exitCode = await runPackageScriptToTerminal({
-    cwd,
-    packageManager: scan.packageManager,
-    script
-  });
-  process.exitCode = exitCode;
+  const available = [
+    ...Object.keys(scan.scripts),
+    ...Object.keys(scan.config?.config.commands ?? {}),
+    ...Object.keys(scan.presetCommands)
+  ];
+  const hint = available.length > 0 ? ` Available commands: ${safeDisplayList(available)}.` : "";
+  console.error(pc4.red(`Command "${safeDisplayText(script)}" was not found.${hint}`));
+  process.exitCode = 1;
 }
 
 // src/cli/commands/scan.ts
-import pc4 from "picocolors";
+import pc5 from "picocolors";
 function formatList(values) {
   return safeDisplayList(values);
 }
 function printScanResult(scan) {
-  console.log(pc4.bold(`Project:   ${safeDisplayText(scan.projectName)}`));
+  console.log(pc5.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")}`);
   console.log(`Scripts:   ${formatList(Object.keys(scan.scripts))}`);
+  console.log(`Presets:   ${formatList(scan.presets.map((preset) => preset.label)) || "none"}`);
   console.log(`Git:       ${safeDisplayText(scan.git?.branch ?? "not detected")}`);
   console.log(`README:    ${scan.readme.exists ? "found" : "missing"}`);
   console.log(`LICENSE:   ${scan.license.exists ? "found" : "missing"}`);
@@ -1483,35 +2032,35 @@ async function scanCommand(cwd = process.cwd()) {
 }
 
 // src/cli/commands/start.ts
-import pc5 from "picocolors";
+import pc6 from "picocolors";
 
 // node_modules/open/index.js
 import process7 from "process";
 import { Buffer as Buffer2 } from "buffer";
-import path11 from "path";
+import path13 from "path";
 import { fileURLToPath } from "url";
 import { promisify as promisify5 } from "util";
 import childProcess from "child_process";
-import fs15, { constants as fsConstants2 } from "fs/promises";
+import fs17, { constants as fsConstants2 } from "fs/promises";
 
 // node_modules/wsl-utils/index.js
 import process3 from "process";
-import fs14, { constants as fsConstants } from "fs/promises";
+import fs16, { constants as fsConstants } from "fs/promises";
 
 // node_modules/is-wsl/index.js
 import process2 from "process";
 import os2 from "os";
-import fs13 from "fs";
+import fs15 from "fs";
 
 // node_modules/is-inside-container/index.js
-import fs12 from "fs";
+import fs14 from "fs";
 
 // node_modules/is-docker/index.js
-import fs11 from "fs";
+import fs13 from "fs";
 var isDockerCached;
 function hasDockerEnv() {
   try {
-    fs11.statSync("/.dockerenv");
+    fs13.statSync("/.dockerenv");
     return true;
   } catch {
     return false;
@@ -1519,7 +2068,7 @@ function hasDockerEnv() {
 }
 function hasDockerCGroup() {
   try {
-    return fs11.readFileSync("/proc/self/cgroup", "utf8").includes("docker");
+    return fs13.readFileSync("/proc/self/cgroup", "utf8").includes("docker");
   } catch {
     return false;
   }
@@ -1535,7 +2084,7 @@ function isDocker() {
 var cachedResult;
 var hasContainerEnv = () => {
   try {
-    fs12.statSync("/run/.containerenv");
+    fs14.statSync("/run/.containerenv");
     return true;
   } catch {
     return false;
@@ -1560,12 +2109,12 @@ var isWsl = () => {
     return true;
   }
   try {
-    if (fs13.readFileSync("/proc/version", "utf8").toLowerCase().includes("microsoft")) {
+    if (fs15.readFileSync("/proc/version", "utf8").toLowerCase().includes("microsoft")) {
       return !isInsideContainer();
     }
   } catch {
   }
-  if (fs13.existsSync("/proc/sys/fs/binfmt_misc/WSLInterop") || fs13.existsSync("/run/WSL")) {
+  if (fs15.existsSync("/proc/sys/fs/binfmt_misc/WSLInterop") || fs15.existsSync("/run/WSL")) {
     return !isInsideContainer();
   }
   return false;
@@ -1583,14 +2132,14 @@ var wslDrivesMountPoint = /* @__PURE__ */ (() => {
     const configFilePath = "/etc/wsl.conf";
     let isConfigFileExists = false;
     try {
-      await fs14.access(configFilePath, fsConstants.F_OK);
+      await fs16.access(configFilePath, fsConstants.F_OK);
       isConfigFileExists = true;
     } catch {
     }
     if (!isConfigFileExists) {
       return defaultMountPoint;
     }
-    const configContent = await fs14.readFile(configFilePath, { encoding: "utf8" });
+    const configContent = await fs16.readFile(configFilePath, { encoding: "utf8" });
     const configMountPoint = /(?<!#.*)root\s*=\s*(?<mountPoint>.*)/g.exec(configContent);
     if (!configMountPoint) {
       return defaultMountPoint;
@@ -1744,8 +2293,8 @@ async function defaultBrowser2() {
 
 // node_modules/open/index.js
 var execFile5 = promisify5(childProcess.execFile);
-var __dirname = path11.dirname(fileURLToPath(import.meta.url));
-var localXdgOpenPath = path11.join(__dirname, "xdg-open");
+var __dirname = path13.dirname(fileURLToPath(import.meta.url));
+var localXdgOpenPath = path13.join(__dirname, "xdg-open");
 var { platform, arch } = process7;
 async function getWindowsDefaultBrowserFromWsl() {
   const powershellPath = await powerShellPath();
@@ -1895,7 +2444,7 @@ var baseOpen = async (options) => {
       const isBundled = !__dirname || __dirname === "/";
       let exeLocalXdgOpen = false;
       try {
-        await fs15.access(localXdgOpenPath, fsConstants2.X_OK);
+        await fs17.access(localXdgOpenPath, fsConstants2.X_OK);
         exeLocalXdgOpen = true;
       } catch {
       }
@@ -2000,8 +2549,8 @@ defineLazyProperty(apps, "browserPrivate", () => "browserPrivate");
 var open_default = open;
 
 // src/server/index.ts
-import { promises as fs19 } from "fs";
-import path15 from "path";
+import { promises as fs21 } from "fs";
+import path17 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { createAdaptorServer } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
@@ -2151,16 +2700,16 @@ var ProcessManager = class extends EventEmitter {
 
 // src/core/hub/registry.ts
 import { createHash } from "crypto";
-import { promises as fs17 } from "fs";
+import { promises as fs19 } from "fs";
 import os3 from "os";
-import path13 from "path";
+import path15 from "path";
 
 // src/core/hub/workspaceRoots.ts
-import { promises as fs16 } from "fs";
-import path12 from "path";
-function isWithinRoot7(root, target) {
-  const relative = path12.relative(root, target);
-  return relative === "" || !relative.startsWith("..") && !path12.isAbsolute(relative);
+import { promises as fs18 } from "fs";
+import path14 from "path";
+function isWithinRoot8(root, target) {
+  const relative = path14.relative(root, target);
+  return relative === "" || !relative.startsWith("..") && !path14.isAbsolute(relative);
 }
 async function configuredWorkspaceRoots() {
   const raw = process.env.DEVSURFACE_WORKSPACE_ROOTS;
@@ -2174,7 +2723,7 @@ async function configuredWorkspaceRoots() {
       continue;
     }
     try {
-      roots.push(await fs16.realpath(path12.resolve(trimmed)));
+      roots.push(await fs18.realpath(path14.resolve(trimmed)));
     } catch {
     }
   }
@@ -2186,7 +2735,7 @@ async function assertWithinWorkspaceRoots(targetPath) {
     return;
   }
   for (const root of roots) {
-    if (isWithinRoot7(root, targetPath)) {
+    if (isWithinRoot8(root, targetPath)) {
       return;
     }
   }
@@ -2195,16 +2744,16 @@ async function assertWithinWorkspaceRoots(targetPath) {
 
 // src/core/hub/registry.ts
 function workspaceId(realPath) {
-  const base = path13.basename(realPath).replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 32) || "workspace";
+  const base = path15.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 ?? path13.join(os3.homedir(), ".devsurface");
+  return process.env.DEVSURFACE_DATA_DIR ?? path15.join(os3.homedir(), ".devsurface");
 }
 async function readPackageName(dirPath) {
   try {
-    const raw = JSON.parse(await fs17.readFile(path13.join(dirPath, "package.json"), "utf8"));
+    const raw = JSON.parse(await fs19.readFile(path15.join(dirPath, "package.json"), "utf8"));
     return typeof raw?.name === "string" && raw.name.length > 0 ? raw.name : null;
   } catch {
     return null;
@@ -2215,7 +2764,7 @@ var WorkspaceRegistry = class {
   seeded = false;
   constructor(dataDir) {
     const dir = dataDir ?? defaultDataDir();
-    this.filePath = path13.join(dir, "workspaces.json");
+    this.filePath = path15.join(dir, "workspaces.json");
   }
   async list() {
     await this.seedFromEnv();
@@ -2229,7 +2778,7 @@ var WorkspaceRegistry = class {
     if (existing) {
       return existing;
     }
-    const name = await readPackageName(realDir) ?? path13.basename(realDir);
+    const name = await readPackageName(realDir) ?? path15.basename(realDir);
     const entry = {
       id: workspaceId(realDir),
       name,
@@ -2251,7 +2800,7 @@ var WorkspaceRegistry = class {
   }
   async findByPath(dirPath) {
     try {
-      const realDir = await fs17.realpath(path13.resolve(dirPath));
+      const realDir = await fs19.realpath(path15.resolve(dirPath));
       const entries = await this.read();
       return entries.find((entry) => entry.path === realDir) ?? null;
     } catch {
@@ -2279,9 +2828,9 @@ var WorkspaceRegistry = class {
     }
   }
   async resolveDir(dirPath) {
-    const resolved = path13.resolve(dirPath);
-    const realDir = await fs17.realpath(resolved);
-    const stat = await fs17.stat(realDir);
+    const resolved = path15.resolve(dirPath);
+    const realDir = await fs19.realpath(resolved);
+    const stat = await fs19.stat(realDir);
     if (!stat.isDirectory()) {
       throw new Error(`${dirPath} is not a directory.`);
     }
@@ -2289,7 +2838,7 @@ var WorkspaceRegistry = class {
   }
   async read() {
     try {
-      const content = await fs17.readFile(this.filePath, "utf8");
+      const content = await fs19.readFile(this.filePath, "utf8");
       const parsed = JSON.parse(content);
       return Array.isArray(parsed) ? parsed : [];
     } catch {
@@ -2297,8 +2846,11 @@ var WorkspaceRegistry = class {
     }
   }
   async write(entries) {
-    await fs17.mkdir(path13.dirname(this.filePath), { recursive: true });
-    await fs17.writeFile(this.filePath, JSON.stringify(entries, null, 2) + "\n", "utf8");
+    await fs19.mkdir(path15.dirname(this.filePath), { recursive: true });
+    await fs19.writeFile(this.filePath, JSON.stringify(entries, null, 2) + "\n", {
+      encoding: "utf8",
+      mode: 384
+    });
   }
   async seedFromEnv() {
     if (this.seeded) {
@@ -2380,12 +2932,12 @@ var Hub = class {
 
 // src/server/routes/api.ts
 import { constants as constants2, existsSync } from "fs";
-import { promises as fs18 } from "fs";
-import path14 from "path";
+import { promises as fs20 } from "fs";
+import path16 from "path";
 import spawn4 from "cross-spawn";
 
 // src/version.ts
-var DEV_SURFACE_VERSION = "0.4.0";
+var DEV_SURFACE_VERSION = "0.6.0";
 
 // src/server/localAccess.ts
 var LOCAL_HOSTNAMES = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "::1"]);
@@ -2571,9 +3123,9 @@ function isAllowedTerminalCommand(command) {
 }
 
 // src/server/routes/api.ts
-function isWithinRoot8(root, target) {
-  const relative = path14.relative(path14.resolve(root), path14.resolve(target));
-  return relative === "" || !relative.startsWith("..") && !path14.isAbsolute(relative);
+function isWithinRoot9(root, target) {
+  const relative = path16.relative(path16.resolve(root), path16.resolve(target));
+  return relative === "" || !relative.startsWith("..") && !path16.isAbsolute(relative);
 }
 function isAllowedMutationOrigin(requestUrl, origin) {
   if (origin === null) {
@@ -2605,35 +3157,35 @@ function hasMutationIntent(intent) {
   return intent === "dashboard";
 }
 async function realPathWithinRoot(root, target) {
-  if (!isWithinRoot8(root, target)) {
+  if (!isWithinRoot9(root, target)) {
     return false;
   }
   try {
-    const [realRoot, realTarget] = await Promise.all([fs18.realpath(root), fs18.realpath(target)]);
-    return isWithinRoot8(realRoot, realTarget);
+    const [realRoot, realTarget] = await Promise.all([fs20.realpath(root), fs20.realpath(target)]);
+    return isWithinRoot9(realRoot, realTarget);
   } catch {
     return false;
   }
 }
 async function writableDestinationWithinRoot(root, destination) {
-  if (!isWithinRoot8(root, destination)) {
+  if (!isWithinRoot9(root, destination)) {
     return false;
   }
   try {
     const [realRoot, realParent] = await Promise.all([
-      fs18.realpath(root),
-      fs18.realpath(path14.dirname(destination))
+      fs20.realpath(root),
+      fs20.realpath(path16.dirname(destination))
     ]);
-    return isWithinRoot8(realRoot, realParent);
+    return isWithinRoot9(realRoot, realParent);
   } catch {
     return false;
   }
 }
 async function copyFileExclusive(source, destination) {
-  const content = await fs18.readFile(source);
+  const content = await fs20.readFile(source);
   let handle2 = null;
   try {
-    handle2 = await fs18.open(
+    handle2 = await fs20.open(
       destination,
       constants2.O_CREAT | constants2.O_EXCL | constants2.O_WRONLY,
       384
@@ -2660,15 +3212,15 @@ function resolveCommandPromptExecutable() {
   return process.env.ComSpec ?? "cmd.exe";
 }
 function findExecutable(command) {
-  if (path14.isAbsolute(command)) {
+  if (path16.isAbsolute(command)) {
     return existsSync(command) ? command : null;
   }
   const pathValue = process.env.PATH ?? "";
-  for (const directory of pathValue.split(path14.delimiter)) {
+  for (const directory of pathValue.split(path16.delimiter)) {
     if (directory.length === 0) {
       continue;
     }
-    const candidate = path14.join(directory, command);
+    const candidate = path16.join(directory, command);
     if (existsSync(candidate)) {
       return candidate;
     }
@@ -2746,6 +3298,11 @@ function handleDockerError(error, context) {
   }
   throw error;
 }
+async function onboardingForRoot(root) {
+  const scan = await scanProject(root);
+  const warnings = await runDoctor(root, scan);
+  return buildOnboardingPlan(scan, warnings);
+}
 function registerWorkspaceRoutes(app, resolveWorkspace) {
   app.get("/api/workspaces/:id/project", async (context) => {
     const ws = await resolveWorkspace(context.req.param("id"));
@@ -2757,6 +3314,11 @@ function registerWorkspaceRoutes(app, resolveWorkspace) {
     if (!ws) return context.json({ error: "Workspace not found." }, 404);
     return context.json(await runDoctor(ws.root));
   });
+  app.get("/api/workspaces/:id/onboarding", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
+    return context.json(await onboardingForRoot(ws.root));
+  });
   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);
@@ -2851,7 +3413,7 @@ function registerWorkspaceRoutes(app, resolveWorkspace) {
     if (!ws) return context.json({ error: "Workspace not found." }, 404);
     const name = decodeURIComponent(context.req.param("name"));
     const scan = await scanProject(ws.root);
-    const configuredCommand = scan.config?.config.commands?.[name] ?? null;
+    const configuredCommand = scan.config?.config.commands?.[name] ?? scan.presetCommands[name] ?? null;
     if (configuredCommand === null) {
       return context.json({ error: `Configured command "${name}" was not found.` }, 404);
     }
@@ -2885,7 +3447,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 = path14.join(ws.root, "package.json");
+    const packagePath = path16.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);
     }
@@ -2907,7 +3469,7 @@ function registerWorkspaceRoutes(app, resolveWorkspace) {
     if (examplePath === null) {
       return context.json({ error: ".env.example was not found." }, 404);
     }
-    const destination = localPath ?? path14.join(ws.root, scan.config?.config.env?.local ?? ".env");
+    const destination = localPath ?? path16.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);
     }
@@ -2979,6 +3541,11 @@ function registerHubApiRoutes(app, options) {
     if (entries.length === 0) return context.json({ error: "No workspaces registered." }, 404);
     return context.json(await runDoctor(hub.ensure(entries[0]).root));
   });
+  app.get("/api/onboarding", async (context) => {
+    const entries = await hub.registry.list();
+    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/processes", async (context) => {
     const entries = await hub.registry.list();
     if (entries.length === 0) return context.json([]);
@@ -3082,23 +3649,34 @@ function setupHubWebSocket(server, hub) {
 }
 
 // src/server/index.ts
+function warnIfContainerRootsUnset(host) {
+  if (host !== "0.0.0.0" && host !== "::") {
+    return;
+  }
+  if (process.env.DEVSURFACE_WORKSPACE_ROOTS?.trim()) {
+    return;
+  }
+  console.warn(
+    "Warning: DEVSURFACE_WORKSPACE_ROOTS is unset in container mode. Any loopback or private-network client can register arbitrary directories as workspaces. Set DEVSURFACE_WORKSPACE_ROOTS to restrict workspace registration."
+  );
+}
 async function fileExists(filePath) {
   try {
-    await fs19.access(filePath);
+    await fs21.access(filePath);
     return true;
   } catch {
     return false;
   }
 }
 async function findWebDistDir() {
-  const moduleDir = path15.dirname(fileURLToPath2(import.meta.url));
+  const moduleDir = path17.dirname(fileURLToPath2(import.meta.url));
   const candidates = [
-    path15.join(moduleDir, "..", "web", "dist"),
-    path15.join(moduleDir, "..", "..", "src", "web", "dist"),
-    path15.join(moduleDir, "web", "dist")
+    path17.join(moduleDir, "..", "web", "dist"),
+    path17.join(moduleDir, "..", "..", "src", "web", "dist"),
+    path17.join(moduleDir, "web", "dist")
   ];
   for (const candidate of candidates) {
-    if (await fileExists(path15.join(candidate, "index.html"))) {
+    if (await fileExists(path17.join(candidate, "index.html"))) {
       return candidate;
     }
   }
@@ -3170,7 +3748,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 fs19.readFile(path15.join(webDistDir, "index.html"), "utf8");
+      const html = await fs21.readFile(path17.join(webDistDir, "index.html"), "utf8");
       return context.html(html);
     });
   } else {
@@ -3197,6 +3775,7 @@ async function startHubServer(options) {
   const port = options.port ?? DEFAULT_PORT;
   const hub = new Hub({ dataDir: options.dataDir });
   hub.attachCleanupHandlers();
+  warnIfContainerRootsUnset(host);
   if (options.initialWorkspace) {
     await hub.registry.add(options.initialWorkspace);
   }
@@ -3272,7 +3851,7 @@ function dashboardUrl(workspaceId2, port = DEFAULT_PORT, host = DEFAULT_HOST) {
 async function startCommand(options) {
   const cwd = options.cwd ?? process.cwd();
   const port = options.port ?? 4567;
-  console.log(pc5.bold(`DevSurface v${DEV_SURFACE_VERSION}`));
+  console.log(pc6.bold(`DevSurface v${DEV_SURFACE_VERSION}`));
   console.log("Scanning project...\n");
   const scan = await scanProject(cwd);
   printScanResult(scan);
@@ -3280,7 +3859,7 @@ async function startCommand(options) {
   if (warnings.length > 0) {
     console.log("\nWarnings:");
     for (const item of warnings) {
-      const marker = item.severity === "error" ? pc5.red("!") : pc5.yellow("!");
+      const marker = item.severity === "error" ? pc6.red("!") : pc6.yellow("!");
       console.log(`  ${marker} ${item.title}`);
     }
   }
@@ -3289,8 +3868,8 @@ async function startCommand(options) {
     const registered = await registerWorkspaceRemotely(cwd, port);
     if (registered) {
       const url = dashboardUrl(registered.id, port);
-      console.log(`Workspace ${pc5.cyan(registered.name)} attached.`);
-      console.log(`Dashboard -> ${pc5.cyan(url)}`);
+      console.log(`Workspace ${pc6.cyan(registered.name)} attached.`);
+      console.log(`Dashboard -> ${pc6.cyan(url)}`);
       if (options.openBrowser !== false) {
         await open_default(url);
       }
@@ -3304,13 +3883,13 @@ async function startCommand(options) {
     initialWorkspace: cwd
   });
   console.log(`
-Dashboard running at -> ${pc5.cyan(server.url)}`);
+Dashboard running at -> ${pc6.cyan(server.url)}`);
 }
 
 // src/cli/commands/serve.ts
-import pc6 from "picocolors";
+import pc7 from "picocolors";
 async function serveCommand(options) {
-  console.log(pc6.bold(`DevSurface Hub v${DEV_SURFACE_VERSION}`));
+  console.log(pc7.bold(`DevSurface Hub v${DEV_SURFACE_VERSION}`));
   console.log("Starting hub server...\n");
   const server = await startHubServer({
     port: options.port,
@@ -3320,7 +3899,7 @@ async function serveCommand(options) {
   if (summaries.length > 0) {
     console.log(`Registered workspaces: ${summaries.length}`);
     for (const ws of summaries) {
-      console.log(`  ${pc6.cyan(ws.name)} -> ${ws.path}`);
+      console.log(`  ${pc7.cyan(ws.name)} -> ${ws.path}`);
     }
   } else {
     console.log(
@@ -3328,17 +3907,17 @@ async function serveCommand(options) {
     );
   }
   console.log(`
-Hub running at -> ${pc6.cyan(server.url)}`);
+Hub running at -> ${pc7.cyan(server.url)}`);
 }
 
 // src/cli/commands/workspace.ts
-import path16 from "path";
-import pc7 from "picocolors";
+import path18 from "path";
+import pc8 from "picocolors";
 async function workspaceAddCommand(dirPath) {
   const registry = new WorkspaceRegistry();
-  const target = path16.resolve(dirPath ?? process.cwd());
+  const target = path18.resolve(dirPath ?? process.cwd());
   const entry = await registry.add(target);
-  console.log(`Added workspace ${pc7.cyan(entry.name)} (${entry.id}) -> ${entry.path}`);
+  console.log(`Added workspace ${pc8.cyan(entry.name)} (${entry.id}) -> ${entry.path}`);
 }
 async function workspaceListCommand() {
   const registry = new WorkspaceRegistry();
@@ -3352,7 +3931,7 @@ async function workspaceListCommand() {
   console.log(`${entries.length} workspace${entries.length === 1 ? "" : "s"}:
 `);
   for (const entry of entries) {
-    console.log(`  ${pc7.cyan(entry.name)} (${entry.id})`);
+    console.log(`  ${pc8.cyan(entry.name)} (${entry.id})`);
     console.log(`    ${entry.path}`);
   }
 }
@@ -3360,13 +3939,85 @@ async function workspaceRemoveCommand(id) {
   const registry = new WorkspaceRegistry();
   const removed = await registry.remove(id);
   if (removed) {
-    console.log(`Removed workspace ${pc7.cyan(id)}.`);
+    console.log(`Removed workspace ${pc8.cyan(id)}.`);
   } else {
     console.error(`Workspace "${id}" not found.`);
     process.exitCode = 1;
   }
 }
 
+// src/cli/updateCheck.ts
+var REGISTRY_LATEST_URL = "https://registry.npmjs.org/devsurface/latest";
+var UPDATE_CHECK_TIMEOUT_MS = 900;
+function parseVersion(version) {
+  const match = version.match(/^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (!match) {
+    return null;
+  }
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function isNewerVersion(latestVersion, currentVersion) {
+  const latest = parseVersion(latestVersion);
+  const current = parseVersion(currentVersion);
+  if (latest === null || current === null) {
+    return false;
+  }
+  for (let index = 0; index < latest.length; index += 1) {
+    if (latest[index] > current[index]) {
+      return true;
+    }
+    if (latest[index] < current[index]) {
+      return false;
+    }
+  }
+  return false;
+}
+function formatUpdateNotice(info) {
+  return `Update available: v${info.latestVersion}
+Run: npx devsurface@latest`;
+}
+function shouldCheckForUpdates() {
+  return process.env.DEVSURFACE_UPDATE_CHECK !== "0" && process.env.CI !== "true";
+}
+async function checkForUpdate(currentVersion, fetchImpl = fetch) {
+  if (!shouldCheckForUpdates()) {
+    return null;
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), UPDATE_CHECK_TIMEOUT_MS);
+  try {
+    const response = await fetchImpl(REGISTRY_LATEST_URL, {
+      headers: {
+        accept: "application/json"
+      },
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      return null;
+    }
+    const body = await response.json();
+    const latestVersion = typeof body.version === "string" ? body.version : null;
+    if (latestVersion === null || !isNewerVersion(latestVersion, currentVersion)) {
+      return null;
+    }
+    return {
+      currentVersion,
+      latestVersion
+    };
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function printUpdateNotice(currentVersion) {
+  const update = await checkForUpdate(currentVersion);
+  if (update !== null) {
+    console.log(`
+${formatUpdateNotice(update)}`);
+  }
+}
+
 // src/cli/index.ts
 var program = new Command();
 function toPort(value) {
@@ -3377,7 +4028,9 @@ function toPort(value) {
   return port;
 }
 function handle(command) {
-  command.catch((error) => {
+  command.then(async () => {
+    await printUpdateNotice(DEV_SURFACE_VERSION);
+  }).catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
     console.error(message);
     process.exitCode = 1;
@@ -3416,6 +4069,9 @@ program.command("scan").description("Print detected project info.").action(() =>
 program.command("doctor").description("Print setup health warnings.").action(() => {
   handle(doctorCommand(process.cwd()));
 });
+program.command("onboard").description("Print a guided setup checklist with readiness score.").action(() => {
+  handle(onboardCommand(process.cwd()));
+});
 program.command("init").description("Create a starter devsurface.config.json.").action(() => {
   handle(initCommand(process.cwd()));
 });