devsurface 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.6.0
+
+- Added guided onboarding with a setup readiness score (0–100%) computed from scan and doctor results.
+- Added `devsurface onboard` CLI command that prints a colored checklist of setup steps with done/todo/manual status.
+- Added `/api/onboarding` endpoint (and `/api/workspaces/:id/onboarding` for hub mode) returning the full onboarding plan.
+- Added Onboarding tab in the dashboard with progress bar, per-step actions (install deps, copy `.env`, run scripts, open docs), and a compact banner on the overview when the project is not yet ready.
+- Added `setupGuide` (or `setup_guide`) field in `devsurface.config.json` for maintainers to embed ordered setup instructions (max 24 steps, 200 chars each).
+- Added Python, Go, and Java language support to the onboarding plan; install step is skipped for non-Node projects.
+- Hardened hub workspace registry file permissions to `0o600`.
+- Added a startup warning when `DEVSURFACE_WORKSPACE_ROOTS` is unset in container mode.
+- Shifted keyboard shortcuts: 2=Onboarding, 3=Scripts, 8=Logs (previously 7).
+
 ## 0.5.0
 
 - Added framework presets for Next.js, Vite, Express, Fastify, NestJS, Remix, and Prisma.

package/README.md

@@ -328,12 +328,16 @@ DevSurface is designed for local development.
 
 - Local dashboard servers bind to loopback hosts.
 - Container deployments use `DEVSURFACE_CONTAINER=true`.
-- Workspace registration can be limited with `DEVSURFACE_WORKSPACE_ROOTS`.
+- Workspace registration can be limited with `DEVSURFACE_WORKSPACE_ROOTS`. In container
+  or shared-host deployments, set this to restrict which directories the hub will accept;
+  on a single-user laptop it is optional and DevSurface starts with no extra config.
 - `.env` values are never returned by scanners, API routes, CLI output, or UI panels.
 - Dashboard command runs show the exact command string first.
 - Docker service start and stop actions show the exact Compose command before running.
 - Destructive-looking configured commands, such as `rm -rf`, `docker volume rm`,
-  database drops, and `git clean -fd`, are visibly marked before execution.
+  database drops, and `git clean -fd`, are visibly marked before execution. This list is a
+  helpful warning, not a sandbox: it flags common footguns for confirmation but does not
+  attempt to detect every dangerous command. Treat package scripts as code that runs as you.
 - Child processes started by DevSurface are cleaned up when the dashboard exits.
 
 ## FAQ

package/action/dist/index.js

@@ -68,6 +68,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;
@@ -122,6 +149,7 @@ function validateConfig(raw) {
       ports: toPorts(raw.ports, warnings),
       env,
       services,
+      setupGuide: toSetupGuide(raw.setupGuide ?? raw.setup_guide, warnings),
       docs
     },
     warnings

package/dist/cli/index.js

@@ -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
@@ -1549,9 +1583,188 @@ async function initCommand(cwd = process.cwd()) {
   }
 }
 
-// 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";
 
@@ -1765,7 +1978,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(pc3.red(`Refusing to run dangerous command "${safeDisplayText(script)}".`));
+      console.error(pc4.red(`Refusing to run dangerous command "${safeDisplayText(script)}".`));
       process.exitCode = 1;
       return;
     }
@@ -1782,17 +1995,17 @@ async function runCommand(script, cwd = process.cwd()) {
     ...Object.keys(scan.presetCommands)
   ];
   const hint = available.length > 0 ? ` Available commands: ${safeDisplayList(available)}.` : "";
-  console.error(pc3.red(`Command "${safeDisplayText(script)}" was not found.${hint}`));
+  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")}`);
@@ -1819,7 +2032,7 @@ 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";
@@ -2634,7 +2847,10 @@ 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", "utf8");
+    await fs19.writeFile(this.filePath, JSON.stringify(entries, null, 2) + "\n", {
+      encoding: "utf8",
+      mode: 384
+    });
   }
   async seedFromEnv() {
     if (this.seeded) {
@@ -2721,7 +2937,7 @@ import path16 from "path";
 import spawn4 from "cross-spawn";
 
 // src/version.ts
-var DEV_SURFACE_VERSION = "0.5.0";
+var DEV_SURFACE_VERSION = "0.6.0";
 
 // src/server/localAccess.ts
 var LOCAL_HOSTNAMES = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "::1"]);
@@ -3082,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"));
@@ -3093,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);
@@ -3315,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([]);
@@ -3418,6 +3649,17 @@ 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 fs21.access(filePath);
@@ -3533,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);
   }
@@ -3608,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);
@@ -3616,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}`);
     }
   }
@@ -3625,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);
       }
@@ -3640,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,
@@ -3656,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(
@@ -3664,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 path18 from "path";
-import pc7 from "picocolors";
+import pc8 from "picocolors";
 async function workspaceAddCommand(dirPath) {
   const registry = new WorkspaceRegistry();
   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();
@@ -3688,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}`);
   }
 }
@@ -3696,7 +3939,7 @@ 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;
@@ -3826,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()));
 });