devsurface 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # 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.
+- Added detected preset commands and ports to the dashboard and command API.
+- Added Python project detection for `requirements.txt`, `pyproject.toml`, and `Pipfile`, including FastAPI/Uvicorn, Flask, and Django commands.
+- Added Go project detection from `go.mod`, with run, build, and test commands.
+- Added Java project detection from Maven and Gradle build files, with build and test commands.
+- Updated doctor checks so detected Python, Go, and Java projects are not treated as broken Node.js projects.
+
 ## 0.4.0
 
 - Added multi-workspace Hub mode: one DevSurface instance serves multiple project

package/README.md

@@ -6,7 +6,7 @@
 
 <h1>DevSurface</h1>
 
-<p><strong>Turn any Node.js repository into a local developer control panel.</strong></p>
+<p><strong>Local developer dashboard for Node.js repositories.</strong></p>
 
 <p>
   <a href="#quick-start">Quick Start</a>
@@ -22,19 +22,30 @@
   <a href="https://github.com/mrfandu1/devsurface">
     <img alt="DevSurface ready" src="docs/devsurface-badge.svg">
   </a>
+  <a href="https://www.npmjs.com/package/devsurface">
+    <img alt="npm version" src="https://img.shields.io/npm/v/devsurface.svg">
+  </a>
+  <a href="https://www.npmjs.com/package/devsurface">
+    <img alt="npm downloads" src="https://img.shields.io/npm/dm/devsurface.svg">
+  </a>
+  <a href="https://github.com/mrfandu1/devsurface/stargazers">
+    <img alt="GitHub stars" src="https://img.shields.io/github/stars/mrfandu1/devsurface?style=flat">
+  </a>
   <a href="LICENSE">
-    <img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-informational">
+    <img alt="License: MIT" src="https://img.shields.io/github/license/mrfandu1/devsurface">
   </a>
   <img alt="Built with TypeScript" src="https://img.shields.io/badge/Built%20with-TypeScript-3178c6">
 </p>
 
 </div>
 
-DevSurface scans a project, starts a local dashboard, and shows the things contributors
-usually need before a project will run: package scripts, environment files, ports,
-Docker Compose, live command logs, and repo health warnings.
+DevSurface is a zero-config CLI and local browser dashboard for understanding,
+configuring, and running unfamiliar repositories. It detects Node.js package scripts,
+Python, Go, and Java project commands, environment files, occupied ports, Docker
+Compose services, frameworks, live command logs, repo health checks, and
+multi-workspace projects.
 
-No config file is required.
+No global install, account, cloud service, or config file is required.
 
 ```bash
 npx devsurface
@@ -64,6 +75,36 @@ DevSurface is local-first:
 - `.env` values are never displayed.
 - Commands are shown before they run.
 
+## Use Cases
+
+DevSurface is useful when you need to:
+
+- Onboard contributors to an unfamiliar Node.js repository.
+- Explore available npm, pnpm, Yarn, or Bun scripts.
+- Check missing environment variables before starting a project.
+- Detect local port conflicts.
+- View and control Docker Compose services.
+- Run development commands from a browser dashboard.
+- Check repository onboarding health in GitHub Actions.
+- Manage multiple local project workspaces.
+
+## Supported Frameworks and Tools
+
+DevSurface detects projects using:
+
+- Next.js
+- Vite
+- Express
+- Fastify
+- NestJS
+- Remix
+- Prisma
+- Python: FastAPI/Uvicorn, Flask, Django
+- Go modules
+- Java: Maven and Gradle
+- Docker Compose
+- npm, pnpm, Yarn, and Bun
+
 ## How It Compares
 
 | Tool                   | What it does                                         | Where DevSurface is different                                                                    |
@@ -287,14 +328,43 @@ 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
+
+### What is DevSurface?
+
+DevSurface is a local developer dashboard for understanding, configuring, and running
+Node.js repositories.
+
+### Can DevSurface run npm scripts from a browser?
+
+Yes. DevSurface detects `package.json` scripts and lets you run them while viewing
+live logs and exit status.
+
+### Does DevSurface display .env values?
+
+No. DevSurface checks whether environment keys exist, but never displays their values.
+
+### Does DevSurface require configuration?
+
+No. It works automatically, with an optional `devsurface.config.json` file for richer
+commands, groups, ports, env paths, and docs links.
+
+### Does DevSurface support Docker Compose?
+
+Yes. It detects Compose services and provides service status, controls, and recent logs.
+
 ## Examples
 
 This repository includes two sample projects:

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