devsurface 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.7.0
+
+- Added structured `setupGuide` steps in `devsurface.config.json`: each step can be a plain string or an object with `title`, `description`, and a `command` or `script` key that turns it into a one-click action button in the Onboarding tab.
+- Updated `devsurface init` to generate a richer config with grouped commands (First-time setup, Daily development, Before committing) and actionable setup steps.
+- Added plain-English explanations for every package script in the dashboard, so non-technical users can see what a command like `vite` or `tsc --noEmit` actually does before running it.
+
 ## 0.6.0
 
 - Added guided onboarding with a setup readiness score (0–100%) computed from scan and doctor results.

package/action/dist/index.js

@@ -75,20 +75,37 @@ function toSetupGuide(value, warnings) {
     return void 0;
   }
   if (!Array.isArray(value)) {
-    warnings.push("setupGuide must be an array of strings.");
+    warnings.push("setupGuide must be an array of strings or step objects.");
     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;
+    if (typeof entry === "string") {
+      const trimmed = entry.trim();
+      if (trimmed.length > 0) {
+        steps.push(trimmed.slice(0, MAX_SETUP_GUIDE_STEP_LENGTH));
+      }
+    } else if (isRecord(entry)) {
+      if (typeof entry.title !== "string" || entry.title.trim().length === 0) {
+        warnings.push("setupGuide step objects must have a non-empty title string.");
+        continue;
+      }
+      const step = {
+        title: entry.title.trim().slice(0, MAX_SETUP_GUIDE_STEP_LENGTH)
+      };
+      if (typeof entry.description === "string" && entry.description.trim().length > 0) {
+        step.description = entry.description.trim().slice(0, MAX_SETUP_GUIDE_STEP_LENGTH);
+      }
+      if (typeof entry.command === "string" && entry.command.trim().length > 0) {
+        step.command = entry.command.trim();
+      }
+      if (typeof entry.script === "string" && entry.script.trim().length > 0) {
+        step.script = entry.script.trim();
+      }
+      steps.push(step);
+    } else {
+      warnings.push("setupGuide entries must be strings or step objects.");
     }
-    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.`);

package/dist/cli/index.js

@@ -56,15 +56,17 @@ var defaultConfig = {
   description: "Local developer control panel",
   commands: {
     install: "npm install",
+    migrate: "npm run db:migrate",
+    seed: "npm run db:seed",
     dev: "npm run dev",
     build: "npm run build",
     test: "npm test",
     lint: "npm run lint"
   },
   groups: {
-    Setup: ["install"],
-    Development: ["dev"],
-    Quality: ["test", "lint"],
+    "First-time setup": ["install", "migrate", "seed"],
+    "Daily development": ["dev"],
+    "Before committing": ["test", "lint"],
     Build: ["build"]
   },
   ports: [3e3],
@@ -76,10 +78,23 @@ var defaultConfig = {
     docker: true
   },
   setupGuide: [
+    {
+      title: "Install dependencies",
+      description: "Run the package manager install to set up node_modules.",
+      command: "install"
+    },
     "Copy .env.example to .env",
-    "Fill in required environment values",
-    "Install dependencies",
-    "Start the dev server"
+    "Fill in required environment values (DATABASE_URL, etc.)",
+    {
+      title: "Run database migrations",
+      description: "Apply the database schema to your local database.",
+      command: "migrate"
+    },
+    {
+      title: "Start the development server",
+      description: "Run the local dev server and open the app in a browser.",
+      command: "dev"
+    }
   ],
   docs: ""
 };
@@ -136,20 +151,37 @@ function toSetupGuide(value, warnings) {
     return void 0;
   }
   if (!Array.isArray(value)) {
-    warnings.push("setupGuide must be an array of strings.");
+    warnings.push("setupGuide must be an array of strings or step objects.");
     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;
+    if (typeof entry === "string") {
+      const trimmed = entry.trim();
+      if (trimmed.length > 0) {
+        steps.push(trimmed.slice(0, MAX_SETUP_GUIDE_STEP_LENGTH));
+      }
+    } else if (isRecord(entry)) {
+      if (typeof entry.title !== "string" || entry.title.trim().length === 0) {
+        warnings.push("setupGuide step objects must have a non-empty title string.");
+        continue;
+      }
+      const step = {
+        title: entry.title.trim().slice(0, MAX_SETUP_GUIDE_STEP_LENGTH)
+      };
+      if (typeof entry.description === "string" && entry.description.trim().length > 0) {
+        step.description = entry.description.trim().slice(0, MAX_SETUP_GUIDE_STEP_LENGTH);
+      }
+      if (typeof entry.command === "string" && entry.command.trim().length > 0) {
+        step.command = entry.command.trim();
+      }
+      if (typeof entry.script === "string" && entry.script.trim().length > 0) {
+        step.script = entry.script.trim();
+      }
+      steps.push(step);
+    } else {
+      warnings.push("setupGuide entries must be strings or step objects.");
     }
-    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.`);
@@ -1692,14 +1724,33 @@ function buildOnboardingPlan(scan, warnings) {
       blocking: false
     });
   }
+  const allCommands = { ...scan.presetCommands, ...scan.config?.config.commands ?? {} };
   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
-    });
+    if (typeof entry === "string") {
+      steps.push({
+        id: `guide-${index}`,
+        title: entry,
+        description: "From the project setup guide.",
+        status: "manual",
+        blocking: false
+      });
+    } else {
+      const step = entry;
+      let action;
+      if (step.command !== void 0 && step.command in allCommands) {
+        action = { kind: "run-command", label: "Run", target: step.command };
+      } else if (step.script !== void 0) {
+        action = { kind: "run-script", label: "Run", target: step.script };
+      }
+      steps.push({
+        id: `guide-${index}`,
+        title: step.title,
+        description: step.description ?? "From the project setup guide.",
+        status: action !== void 0 ? "todo" : "manual",
+        blocking: false,
+        action
+      });
+    }
   }
   const docs = scan.config?.config.docs;
   if (typeof docs === "string" && docs.length > 0 && isSafeHttpUrl(docs)) {
@@ -2937,7 +2988,7 @@ import path16 from "path";
 import spawn4 from "cross-spawn";
 
 // src/version.ts
-var DEV_SURFACE_VERSION = "0.6.0";
+var DEV_SURFACE_VERSION = "0.7.0";
 
 // src/server/localAccess.ts
 var LOCAL_HOSTNAMES = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "::1"]);