@tritard/waterbrother 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tritard/waterbrother",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Waterbrother: Grok-powered coding CLI with local tools, sessions, operator modes, and approval controls",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -33,7 +33,9 @@ import { runBuildWorkflow, startFeatureTask, runChallengeWorkflow } from "./work
 import { createPanelRenderer, buildPanelState } from "./panel.js";
 import { deriveTaskNameFromPrompt, nextActionsForState, routeNaturalInput } from "./router.js";
 import { compressEpisode, compressSessionEpisode, saveEpisode, loadRecentEpisodes, findRelevantEpisodes, buildEpisodicMemoryBlock, buildReminderBlock } from "./episodic.js";
-import { createProduct, loadProduct, saveProduct, hasProduct, generateBlueprint, buildProductContext, detectProductRequest, parseProductIntent, addSurface, createCampaign, getActiveCampaign } from "./product.js";
+import { createProduct, loadProduct, saveProduct, hasProduct, generateBlueprint, buildProductContext, detectProductRequest, parseProductIntent, addSurface, createCampaign, getActiveCampaign, matchTemplate, applyTemplate, startPreview, killPreview } from "./product.js";
+import { runQualityChecks, formatQualityFindings, buildQualityFixPrompt } from "./quality.js";
+import { scanForInitiatives, formatInitiatives, buildInitiativeFixPrompt } from "./initiative.js";
 import { formatPlanForDisplay } from "./planner.js";
 import { parseCharterFromGoal, runExperimentLoop, formatExperimentSummary, gitReturnToBranch } from "./experiment.js";
 
@@ -4776,6 +4778,18 @@ async function promptLoop(agent, session, context) {
     const product = await loadProduct(context.cwd);
     if (product) {
       context.runtime.product = product;
+      // Show product context and run initiative scan
+      const hasBuilt = product.surfaces.some((s) => s.status === "built");
+      if (hasBuilt) {
+        console.log(dim(`product: ${product.name}`));
+        try {
+          const initiatives = await scanForInitiatives({ cwd: context.cwd });
+          if (initiatives.length > 0) {
+            context.runtime.pendingInitiatives = initiatives;
+            console.log(formatInitiatives(initiatives));
+          }
+        } catch {}
+      }
     }
   } catch {}
 
@@ -5038,7 +5052,13 @@ Infer reasonable defaults. Keep it practical.` },
           type: brief.type || intent.type
         });
 
-        // Fill in details from the brief
+        // Apply template if detected
+        const templateType = matchTemplate(line);
+        if (templateType) {
+          applyTemplate(product, templateType);
+        }
+
+        // Fill in details from the brief (overrides template defaults)
         if (brief.stack) {
           product.stack = { ...product.stack, ...brief.stack };
         }
@@ -5083,41 +5103,76 @@ Infer reasonable defaults. Keep it practical.` },
       if (/^(build|build it|build the product|scaffold|go)$/.test(lower)) {
         const productCtx = buildProductContext(product);
         const planned = product.surfaces.filter((s) => s.status === "planned").map((s) => s.name);
-        const buildPrompt = `Build the entire product from the blueprint. Create all files needed.\n\n${productCtx}\n\nSurfaces to build: ${planned.join(", ") || "all planned pages"}\n\nScaffold the full project: package.json, all pages/components, styling, schema, auth config, and a working dev server. Do everything in one pass.`;
 
         const spinner = createProgressSpinner("building product...");
         try {
-          // Set autonomy to auto for the build — no file-by-file approvals
           const prevAutonomy = agent.toolRuntime.getAutonomyMode();
           agent.toolRuntime.setAutonomyMode("auto");
 
-          await agent.runTurn(buildPrompt, {
+          // Phase 1: Scaffold foundation (package.json, config, shared components)
+          const scaffoldPrompt = `${productCtx}\n\nFirst, set up the project foundation:\n1. Create package.json with all dependencies\n2. Create config files (tailwind, next.config, etc.)\n3. Create shared layout/components (nav, footer)\n4. Set up auth if needed\n5. Run npm install\n\nDo NOT build individual pages yet — just the skeleton.`;
+
+          spinner.setLabel("scaffolding...");
+          await agent.runTurn(scaffoldPrompt, {
             onAssistantDelta() {},
-            onToolStart(tc) {
-              const name = tc?.function?.name || "tool";
-              spinner.setLabel(`${name}...`);
-            },
-            onToolEnd() { spinner.setLabel("building..."); }
+            onToolStart(tc) { spinner.setLabel(`${tc?.function?.name || "tool"}...`); },
+            onToolEnd() { spinner.setLabel("scaffolding..."); }
           });
           await agent.toolRuntime.completeTurn({});
 
+          // Phase 2: Build each surface individually
+          for (let i = 0; i < planned.length; i++) {
+            const surface = planned[i];
+            spinner.setLabel(`building ${surface} (${i + 1}/${planned.length})...`);
+            const surfacePrompt = `${productCtx}\n\nBuild the "${surface}" page/flow. Create all components needed for this surface. Make it complete and polished — real content, proper styling, working interactions. Follow the product's style: ${product.qualityBar.taste || "clean and modern"}.`;
+            await agent.runTurn(surfacePrompt, {
+              onAssistantDelta() {},
+              onToolStart(tc) { spinner.setLabel(`${surface}: ${tc?.function?.name || "tool"}...`); },
+              onToolEnd() { spinner.setLabel(`building ${surface}...`); }
+            });
+            await agent.toolRuntime.completeTurn({});
+            console.log(dim(`  ✓ ${surface}`));
+          }
+
           agent.toolRuntime.setAutonomyMode(prevAutonomy);
           spinner.stop();
 
+          // Quality checks
+          try {
+            const findings = await runQualityChecks({ cwd: context.cwd });
+            const qualityOutput = formatQualityFindings(findings);
+            if (qualityOutput) {
+              console.log("");
+              console.log(qualityOutput);
+            }
+          } catch {}
+
           // Mark surfaces as built
           for (const s of product.surfaces) {
             s.status = "built";
           }
           await saveProduct(context.cwd, product);
 
-          // Try to start dev server and open browser
+          // Start preview server and open browser
           console.log("");
           console.log("PREVIEW ▸ ready");
-          const built = product.surfaces.filter((s) => s.status === "built").map((s) => s.name);
-          if (built.length > 0) console.log(`  ${built.join(", ")}`);
-          console.log("  http://localhost:3000");
+          const builtSurfaces = product.surfaces.filter((s) => s.status === "built").map((s) => s.name);
+          if (builtSurfaces.length > 0) console.log(`  ${builtSurfaces.join(", ")}`);
+
+          try {
+            const preview = await startPreview(context.cwd);
+            if (preview.ok) {
+              console.log(`  ${preview.url}`);
+              context.runtime.previewPid = preview.pid;
+            } else {
+              console.log("  http://localhost:3000 (start dev server manually)");
+            }
+          } catch {
+            console.log("  http://localhost:3000 (start dev server manually)");
+          }
+
           console.log("");
-          console.log(dim("  open · refine · add feature · deploy"));
+          console.log(dim("  refine · add feature · deploy"));
 
         } catch (error) {
           spinner.stop();
@@ -5137,21 +5192,141 @@ Infer reasonable defaults. Keep it practical.` },
         return true;
       }
 
+      // Deploy with milestone gate
       if (/^(deploy|ship|publish|launch)$/.test(lower)) {
         const deployTarget = product.stack.deploy || "Vercel";
-        console.log(`deploying to ${deployTarget}...`);
         try {
+          const confirm = await promptYesNo(`Deploy to ${deployTarget}?`, { input: process.stdin, output: process.stdout });
+          if (!confirm) {
+            console.log("deploy canceled");
+            return true;
+          }
+        } catch {
+          console.log("deploy canceled");
+          return true;
+        }
+
+        const spinner = createProgressSpinner(`deploying to ${deployTarget}...`);
+        try {
+          const prevAutonomy = agent.toolRuntime.getAutonomyMode();
+          agent.toolRuntime.setAutonomyMode("auto");
           await agent.runTurn(
             `Deploy this project to ${deployTarget}. Run the necessary CLI commands (e.g. vercel, netlify deploy, gh-pages). If not set up, initialize it first.`,
-            { onAssistantDelta() {}, onToolStart() {}, onToolEnd() {} }
+            { onAssistantDelta() {}, onToolStart() { spinner.setLabel("deploying..."); }, onToolEnd() {} }
           );
           await agent.toolRuntime.completeTurn({});
+          agent.toolRuntime.setAutonomyMode(prevAutonomy);
+          spinner.stop();
           console.log(`\nSHIP ▸ deployed`);
+          console.log(dim("  share link · add feature · view code"));
         } catch (error) {
+          spinner.stop();
           console.log(`deploy failed: ${error instanceof Error ? error.message : String(error)}`);
         }
         return true;
       }
+
+      // Refine: natural language changes to a built product
+      if (/^(fix these|fix quality|fix initiatives|fix product)$/.test(lower) && !context.runtime.activeTask) {
+        // Only handle product fixes when no task is active — otherwise let router handle "fix these" for task reviews
+        if (context.runtime.pendingInitiatives?.length > 0) {
+          const spinner = createProgressSpinner("fixing product gaps...");
+          try {
+            const fixPrompt = buildInitiativeFixPrompt(context.runtime.pendingInitiatives);
+            const prevAutonomy = agent.toolRuntime.getAutonomyMode();
+            agent.toolRuntime.setAutonomyMode("auto");
+            const productCtx = buildProductContext(product);
+            await agent.runTurn(`${productCtx}\n\n${fixPrompt}`, {
+              onAssistantDelta() {}, onToolStart() { spinner.setLabel("fixing..."); }, onToolEnd() {}
+            });
+            await agent.toolRuntime.completeTurn({});
+            agent.toolRuntime.setAutonomyMode(prevAutonomy);
+            spinner.stop();
+            context.runtime.pendingInitiatives = [];
+            console.log("product gaps addressed");
+            console.log(dim("  refine · add feature · deploy"));
+          } catch (error) {
+            spinner.stop();
+            console.log(`fix failed: ${error instanceof Error ? error.message : String(error)}`);
+          }
+          return true;
+        }
+      }
+
+      if (/^(fix these|fix quality)$/.test(lower) && !context.runtime.activeTask) {
+        const spinner = createProgressSpinner("fixing quality issues...");
+        try {
+          const findings = await runQualityChecks({ cwd: context.cwd });
+          const fixPrompt = buildQualityFixPrompt(findings);
+          if (!fixPrompt) { spinner.stop(); console.log("no quality issues to fix"); return true; }
+          const prevAutonomy = agent.toolRuntime.getAutonomyMode();
+          agent.toolRuntime.setAutonomyMode("auto");
+          const productCtx = buildProductContext(product);
+          await agent.runTurn(`${productCtx}\n\n${fixPrompt}`, {
+            onAssistantDelta() {}, onToolStart() { spinner.setLabel("fixing..."); }, onToolEnd() {}
+          });
+          await agent.toolRuntime.completeTurn({});
+          agent.toolRuntime.setAutonomyMode(prevAutonomy);
+          spinner.stop();
+          console.log("quality issues addressed");
+          console.log(dim("  refine · add feature · deploy"));
+        } catch (error) {
+          spinner.stop();
+          console.log(`fix failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return true;
+      }
+
+      // Refine: any other refinement when product has built surfaces
+      const hasBuilt = product.surfaces.some((s) => s.status === "built");
+      if (hasBuilt && !lower.startsWith("/") && !context.runtime.activeTask) {
+        // Negative gate: exclude things that look like new product requests or work requests
+        const isNewProduct = detectProductRequest(line);
+        const isWorkRequest = /^(add|build|create|implement|fix|refactor|wire|debug)\b/.test(lower) && /\b(to the|for the|in the|api|endpoint|middleware|service|module|auth|database)\b/.test(lower);
+        // Positive gate: must reference visual/UI elements or the existing product
+        const isRefinement = !isNewProduct && !isWorkRequest && /\b(make|change|update|prettier|simpler|bigger|smaller|darker|lighter|color|font|style|dark\s*mode|light\s*mode|resize|move|header|footer|nav|button|logo|image|background|padding|margin|spacing|border|rounded|shadow|gradient|animation|hover|responsive|mobile|desktop|center|align|layout)\b/i.test(lower);
+        if (isRefinement) {
+          const spinner = createProgressSpinner("refining...");
+          try {
+            const productCtx = buildProductContext(product);
+
+            // Check if adding a new surface
+            const addMatch = lower.match(/add\s+(?:a\s+)?(.+?)(?:\s+page|\s+screen|\s+section)?$/);
+            if (addMatch) {
+              const surfaceName = addMatch[1].trim().replace(/^(a|an|the)\s+/i, "");
+              addSurface(product, { name: surfaceName, type: "page", status: "planned" });
+              await saveProduct(context.cwd, product);
+            }
+
+            const prevAutonomy = agent.toolRuntime.getAutonomyMode();
+            agent.toolRuntime.setAutonomyMode("auto");
+            await agent.runTurn(
+              `${productCtx}\n\nRefine the product: ${line}\n\nMake the change while keeping the existing product quality and style consistent.`,
+              {
+                onAssistantDelta() {},
+                onToolStart(tc) { spinner.setLabel(`${tc?.function?.name || "editing"}...`); },
+                onToolEnd() { spinner.setLabel("refining..."); }
+              }
+            );
+            await agent.toolRuntime.completeTurn({});
+            agent.toolRuntime.setAutonomyMode(prevAutonomy);
+            spinner.stop();
+
+            // Mark any new surfaces as built
+            for (const s of product.surfaces) {
+              if (s.status === "planned") s.status = "built";
+            }
+            await saveProduct(context.cwd, product);
+
+            console.log("refined");
+            console.log(dim("  refine · add feature · deploy"));
+          } catch (error) {
+            spinner.stop();
+            console.log(`refine failed: ${error instanceof Error ? error.message : String(error)}`);
+          }
+          return true;
+        }
+      }
     }
 
     const routed = routeNaturalInput(line, { task: context.runtime.activeTask });
@@ -7148,6 +7323,9 @@ Infer reasonable defaults. Keep it practical.` },
     }
   }
 
+  // Kill any running preview server
+  killPreview();
+
   // Save CC-mode session episode on exit (if any files were touched)
   if (!context.runtime.activeTask) {
     try {

package/src/initiative.js

@@ -0,0 +1,141 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const IGNORE_DIRS = new Set(["node_modules", ".git", ".waterbrother", "dist", "build", ".next", ".nuxt"]);
+
+async function fileExists(filePath) {
+  try { await fs.access(filePath); return true; } catch { return false; }
+}
+
+async function findFiles(dir, pattern, maxDepth = 4, depth = 0) {
+  if (depth > maxDepth) return [];
+  const matches = [];
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (IGNORE_DIRS.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        matches.push(...await findFiles(full, pattern, maxDepth, depth + 1));
+      } else if (pattern.test(entry.name)) {
+        matches.push(full);
+      }
+    }
+  } catch {}
+  return matches;
+}
+
+async function grepFiles(dir, textPattern, extensions, maxDepth = 4) {
+  const files = await findFiles(dir, new RegExp(`\\.(${extensions.join("|")})$`), maxDepth);
+  const matches = [];
+  for (const f of files) {
+    try {
+      const content = await fs.readFile(f, "utf8");
+      if (textPattern.test(content)) matches.push(path.relative(dir, f).replace(/\\/g, "/"));
+    } catch {}
+  }
+  return matches;
+}
+
+const INITIATIVES = [
+  {
+    id: "no-404",
+    label: "No 404 page",
+    check: async (cwd) => {
+      const has404 = await findFiles(cwd, /404\.(jsx?|tsx?|html|vue|svelte)$/);
+      return has404.length === 0;
+    },
+    suggestion: "Add a 404 page so users see a friendly message on broken links"
+  },
+  {
+    id: "no-favicon",
+    label: "No favicon",
+    check: async (cwd) => {
+      const hasFavicon = await fileExists(path.join(cwd, "public", "favicon.ico"))
+        || await fileExists(path.join(cwd, "public", "favicon.svg"))
+        || await fileExists(path.join(cwd, "app", "favicon.ico"));
+      return !hasFavicon;
+    },
+    suggestion: "Add a favicon — it's the first thing users notice in their browser tab"
+  },
+  {
+    id: "no-meta-tags",
+    label: "Missing SEO meta tags",
+    check: async (cwd) => {
+      const htmlFiles = await findFiles(cwd, /\.(html|jsx|tsx)$/);
+      for (const f of htmlFiles) {
+        try {
+          const content = await fs.readFile(f, "utf8");
+          if (/meta.*description/i.test(content) || /metadata/i.test(content)) return false;
+        } catch {}
+      }
+      return htmlFiles.length > 0;
+    },
+    suggestion: "Add meta description tags for SEO — helps your site show up in search"
+  },
+  {
+    id: "no-loading-states",
+    label: "No loading indicators",
+    check: async (cwd) => {
+      const hasLoading = await grepFiles(cwd, /loading|spinner|skeleton|isLoading|isPending/i, ["jsx", "tsx", "vue", "svelte"]);
+      return hasLoading.length === 0;
+    },
+    suggestion: "Add loading states to async content — prevents blank screens while data loads"
+  },
+  {
+    id: "no-error-handling",
+    label: "Forms without error handling",
+    check: async (cwd) => {
+      const forms = await grepFiles(cwd, /<form|onSubmit|handleSubmit/i, ["jsx", "tsx", "vue", "svelte"]);
+      if (forms.length === 0) return false;
+      const errorHandling = await grepFiles(cwd, /error|catch|validation|invalid/i, ["jsx", "tsx", "vue", "svelte"]);
+      return errorHandling.length === 0;
+    },
+    suggestion: "Add error handling to forms — show validation messages and handle failures"
+  },
+  {
+    id: "no-responsive",
+    label: "No responsive design hints",
+    check: async (cwd) => {
+      const hasResponsive = await grepFiles(cwd, /@media|sm:|md:|lg:|xl:|responsive|mobile/i, ["css", "scss", "jsx", "tsx", "html"]);
+      return hasResponsive.length === 0;
+    },
+    suggestion: "Add responsive breakpoints — your app should look good on phones"
+  }
+];
+
+export async function scanForInitiatives({ cwd }) {
+  const found = [];
+  for (const initiative of INITIATIVES) {
+    try {
+      const applies = await initiative.check(cwd);
+      if (applies) {
+        found.push({
+          id: initiative.id,
+          label: initiative.label,
+          suggestion: initiative.suggestion
+        });
+      }
+    } catch {}
+  }
+  return found;
+}
+
+export function formatInitiatives(initiatives) {
+  if (!initiatives || initiatives.length === 0) return "";
+  const lines = ["Product improvements available:"];
+  for (const init of initiatives.slice(0, 5)) {
+    lines.push(`  → ${init.suggestion}`);
+  }
+  lines.push("\n  fix these · ignore");
+  return lines.join("\n");
+}
+
+export function buildInitiativeFixPrompt(initiatives) {
+  const lines = ["Fix these product quality gaps:"];
+  for (const init of initiatives) {
+    lines.push(`- ${init.label}: ${init.suggestion}`);
+  }
+  lines.push("\nImplement each fix. Keep changes minimal and focused.");
+  return lines.join("\n");
+}

package/src/product.js

@@ -262,3 +262,191 @@ export function parseProductIntent(text) {
 
   return { type, name, raw: text };
 }
+
+// --- Templates ---
+
+const TEMPLATES = {
+  "landing-page": {
+    surfaces: [
+      { name: "Landing", type: "page" }
+    ],
+    stack: { framework: "Next.js", styling: "Tailwind", backend: null, auth: null, deploy: "Vercel" },
+    taste: "bold, modern, conversion-focused",
+    qualityBar: { ux: ["single page", "clear CTA above fold", "< 3s load time"], trust: ["real testimonials", "no stock photos"] }
+  },
+  "saas": {
+    surfaces: [
+      { name: "Landing", type: "page" },
+      { name: "Pricing", type: "page" },
+      { name: "Login", type: "flow" },
+      { name: "Signup", type: "flow" },
+      { name: "Dashboard", type: "page" },
+      { name: "Settings", type: "page" }
+    ],
+    stack: { framework: "Next.js", styling: "Tailwind", backend: "Supabase", auth: "email + OAuth", deploy: "Vercel" },
+    taste: "clean, professional, trustworthy",
+    qualityBar: { ux: ["mobile-first", "onboarding under 60s", "clear pricing"], trust: ["SSL", "privacy policy link", "real company info"] }
+  },
+  "blog": {
+    surfaces: [
+      { name: "Home / Post List", type: "page" },
+      { name: "Post Page", type: "page" },
+      { name: "About", type: "page" }
+    ],
+    stack: { framework: "Next.js", styling: "Tailwind", backend: null, auth: null, deploy: "Vercel" },
+    taste: "readable, minimal, typographic",
+    qualityBar: { ux: ["< 2s load", "good reading experience", "responsive"], trust: ["author info", "real dates"] }
+  },
+  "store": {
+    surfaces: [
+      { name: "Home / Product List", type: "page" },
+      { name: "Product Detail", type: "page" },
+      { name: "Cart", type: "page" },
+      { name: "Checkout", type: "flow" }
+    ],
+    stack: { framework: "Next.js", styling: "Tailwind", backend: "Supabase", auth: "email", deploy: "Vercel" },
+    taste: "clean, trustworthy, product-focused",
+    qualityBar: { ux: ["fast product browsing", "< 3 clicks to checkout"], trust: ["secure checkout badge", "return policy visible"] }
+  },
+  "portfolio": {
+    surfaces: [
+      { name: "Home / Projects Grid", type: "page" },
+      { name: "Project Detail", type: "page" },
+      { name: "About", type: "page" },
+      { name: "Contact", type: "page" }
+    ],
+    stack: { framework: "Next.js", styling: "Tailwind", backend: null, auth: null, deploy: "Vercel" },
+    taste: "creative, visual, spacious",
+    qualityBar: { ux: ["fast image loading", "smooth transitions", "mobile-friendly"], trust: ["real work samples", "contact info visible"] }
+  }
+};
+
+export function matchTemplate(text) {
+  const lower = text.toLowerCase();
+  if (/\b(landing\s*page|one.?page|single.?page|marketing)\b/.test(lower)) return "landing-page";
+  if (/\b(saas|sass|software.?as|subscription|b2b)\b/.test(lower)) return "saas";
+  if (/\b(blog|journal|writing|articles|posts)\b/.test(lower)) return "blog";
+  if (/\b(store|shop|ecommerce|e.?commerce|marketplace|products?\s+for\s+sale)\b/.test(lower)) return "store";
+  if (/\b(portfolio|showcase|gallery|my\s+work|personal\s+site)\b/.test(lower)) return "portfolio";
+  return null;
+}
+
+export function getTemplate(type) {
+  return TEMPLATES[type] || null;
+}
+
+export function applyTemplate(product, templateName) {
+  const template = TEMPLATES[templateName];
+  if (!template) return;
+  for (const s of template.surfaces) {
+    addSurface(product, { name: s.name, type: s.type, status: "planned" });
+  }
+  product.stack = { ...product.stack, ...template.stack };
+  if (template.taste) product.qualityBar.taste = template.taste;
+  if (template.qualityBar?.ux) product.qualityBar.ux = template.qualityBar.ux;
+  if (template.qualityBar?.trust) product.qualityBar.trust = template.qualityBar.trust;
+}
+
+// --- Preview ---
+
+// Track active preview server for cleanup
+let activePreviewServer = null;
+
+export function killPreview() {
+  if (!activePreviewServer) return;
+  try {
+    if (process.platform === "win32") {
+      const { execSync } = require("node:child_process");
+      execSync(`taskkill /PID ${activePreviewServer.pid} /T /F`, { stdio: "ignore" });
+    } else {
+      process.kill(-activePreviewServer.pid);
+    }
+  } catch {}
+  activePreviewServer = null;
+}
+
+function detectPort(cwd) {
+  try {
+    const pkg = JSON.parse(require("node:fs").readFileSync(path.join(cwd, "package.json"), "utf8"));
+    const devScript = pkg.scripts?.dev || "";
+    // Check for --port or -p flags
+    const portMatch = devScript.match(/(?:--port|-p)\s+(\d+)/);
+    if (portMatch) return parseInt(portMatch[1], 10);
+    // Check for PORT env in dev script
+    const envMatch = devScript.match(/PORT=(\d+)/);
+    if (envMatch) return parseInt(envMatch[1], 10);
+  } catch {}
+  return 3000;
+}
+
+async function pollServer(url, maxWaitMs = 30000) {
+  const start = Date.now();
+  while (Date.now() - start < maxWaitMs) {
+    try {
+      const { request } = await import("node:http");
+      const ok = await new Promise((resolve) => {
+        const req = request(url, { timeout: 1000 }, (res) => { resolve(res.statusCode < 500); });
+        req.on("error", () => resolve(false));
+        req.on("timeout", () => { req.destroy(); resolve(false); });
+        req.end();
+      });
+      if (ok) return true;
+    } catch {}
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  return false;
+}
+
+export async function startPreview(cwd) {
+  const { spawn } = await import("node:child_process");
+  const pkgPath = path.join(cwd, "package.json");
+  let hasDevScript = false;
+  try {
+    const pkg = JSON.parse(await fs.readFile(pkgPath, "utf8"));
+    hasDevScript = Boolean(pkg.scripts?.dev);
+  } catch {}
+  if (!hasDevScript) return { ok: false, reason: "no dev script in package.json" };
+
+  // Kill any existing preview server
+  killPreview();
+
+  // Install deps first
+  try {
+    const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+    const install = spawn(npmCmd, ["install"], { cwd, stdio: "ignore" });
+    await new Promise((resolve) => install.on("close", resolve));
+  } catch {}
+
+  // Detect port
+  const port = detectPort(cwd);
+  const url = `http://localhost:${port}`;
+
+  // Start dev server
+  const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+  const server = spawn(npmCmd, ["run", "dev"], {
+    cwd,
+    stdio: "ignore",
+    detached: process.platform !== "win32"
+  });
+  server.unref();
+  activePreviewServer = server;
+
+  // Poll until server responds (up to 30s)
+  const ready = await pollServer(url);
+
+  if (!ready) {
+    return { ok: true, pid: server.pid, url, warning: "server started but not responding yet — may still be compiling" };
+  }
+
+  // Open browser
+  try {
+    if (process.platform === "win32") {
+      spawn("cmd", ["/c", "start", url], { stdio: "ignore" });
+    } else {
+      const openCmd = process.platform === "darwin" ? "open" : "xdg-open";
+      spawn(openCmd, [url], { stdio: "ignore" });
+    }
+  } catch {}
+
+  return { ok: true, pid: server.pid, url: "http://localhost:3000" };
+}

package/src/quality.js

@@ -0,0 +1,140 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const CHECKS = [
+  {
+    name: "placeholder-content",
+    severity: "warning",
+    pattern: /lorem ipsum|placeholder|sample text|example\.com|test@test/i,
+    extensions: [".html", ".jsx", ".tsx", ".vue", ".svelte", ".md"],
+    message: "Placeholder content found"
+  },
+  {
+    name: "broken-links",
+    severity: "warning",
+    pattern: /href=["']#["']|href=["']["']/,
+    extensions: [".html", ".jsx", ".tsx", ".vue", ".svelte"],
+    message: "Broken or empty link"
+  },
+  {
+    name: "missing-alt",
+    severity: "warning",
+    pattern: /<img(?![^>]*alt=)[^>]*>/i,
+    extensions: [".html", ".jsx", ".tsx", ".vue", ".svelte"],
+    message: "Image missing alt text"
+  },
+  {
+    name: "console-log",
+    severity: "info",
+    pattern: /console\.(log|debug|info)\(/,
+    extensions: [".js", ".jsx", ".ts", ".tsx", ".vue", ".svelte"],
+    message: "console.log left in code"
+  },
+  {
+    name: "todo-fixme",
+    severity: "info",
+    pattern: /\/\/\s*(TODO|FIXME|HACK|XXX)\b/i,
+    extensions: [".js", ".jsx", ".ts", ".tsx", ".vue", ".svelte", ".css"],
+    message: "TODO/FIXME comment"
+  }
+];
+
+const IGNORE_DIRS = new Set(["node_modules", ".git", ".waterbrother", "dist", "build", ".next", ".nuxt"]);
+
+async function walkFiles(dir, extensions, maxDepth = 5, depth = 0) {
+  if (depth > maxDepth) return [];
+  const files = [];
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (IGNORE_DIRS.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...await walkFiles(full, extensions, maxDepth, depth + 1));
+      } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+        files.push(full);
+      }
+    }
+  } catch {}
+  return files;
+}
+
+export async function runQualityChecks({ cwd }) {
+  const findings = [];
+  const allExtensions = [...new Set(CHECKS.flatMap((c) => c.extensions))];
+  const files = await walkFiles(cwd, allExtensions);
+
+  for (const filePath of files) {
+    let content;
+    try {
+      content = await fs.readFile(filePath, "utf8");
+    } catch {
+      continue;
+    }
+
+    const lines = content.split("\n");
+    const rel = path.relative(cwd, filePath).replace(/\\/g, "/");
+
+    for (const check of CHECKS) {
+      if (!check.extensions.some((ext) => filePath.endsWith(ext))) continue;
+      for (let i = 0; i < lines.length; i++) {
+        if (check.pattern.test(lines[i])) {
+          findings.push({
+            check: check.name,
+            severity: check.severity,
+            file: rel,
+            line: i + 1,
+            message: check.message,
+            snippet: lines[i].trim().slice(0, 80)
+          });
+        }
+      }
+    }
+
+    // Check for empty files (< 5 lines of real content)
+    const realLines = lines.filter((l) => l.trim().length > 0 && !l.trim().startsWith("//") && !l.trim().startsWith("/*"));
+    if (realLines.length < 5 && allExtensions.some((ext) => filePath.endsWith(ext))) {
+      findings.push({
+        check: "empty-file",
+        severity: "warning",
+        file: rel,
+        line: 1,
+        message: "File has very little content",
+        snippet: `${realLines.length} non-empty lines`
+      });
+    }
+  }
+
+  return findings;
+}
+
+export function formatQualityFindings(findings) {
+  if (!findings || findings.length === 0) return "";
+  const warnings = findings.filter((f) => f.severity === "warning");
+  const infos = findings.filter((f) => f.severity === "info");
+  const lines = [];
+
+  if (warnings.length > 0) {
+    lines.push(`⚠ ${warnings.length} quality issue${warnings.length > 1 ? "s" : ""}:`);
+    for (const f of warnings.slice(0, 5)) {
+      lines.push(`  ${f.file}:${f.line} — ${f.message}`);
+    }
+    if (warnings.length > 5) lines.push(`  ... and ${warnings.length - 5} more`);
+  }
+  if (infos.length > 0) {
+    lines.push(`ℹ ${infos.length} note${infos.length > 1 ? "s" : ""}: ${[...new Set(infos.map((f) => f.message))].join(", ")}`);
+  }
+
+  return lines.join("\n");
+}
+
+export function buildQualityFixPrompt(findings) {
+  const fixable = findings.filter((f) => f.severity === "warning").slice(0, 10);
+  if (fixable.length === 0) return "";
+  const lines = ["Fix these product quality issues:"];
+  for (const f of fixable) {
+    lines.push(`- ${f.file}:${f.line} — ${f.message} (${f.snippet})`);
+  }
+  lines.push("\nReplace placeholder content with real content. Fix broken links. Add alt text to images.");
+  return lines.join("\n");
+}