@kody-ade/kody-engine-lite 0.1.141 → 0.1.143

package/dist/bin/cli.js

@@ -252,7 +252,9 @@ function getProjectConfig() {
           ...raw.mcp,
           // Auto-enable when devServer is configured (user can still set enabled: false to override)
           enabled: raw.mcp.enabled ?? !!raw.mcp.devServer
-        } : void 0
+        } : void 0,
+        // Top-level devServer takes precedence; fall back to mcp.devServer for backward compat
+        devServer: raw.devServer ?? raw.mcp?.devServer ?? void 0
       };
     } catch {
       logger.warn("kody.config.json is invalid JSON \u2014 using defaults");
@@ -4943,7 +4945,7 @@ function taskHasUI(taskDir) {
 }
 function getDevServerInfo(taskDir) {
   const config = getProjectConfig();
-  const ds = config.mcp?.devServer;
+  const ds = config.devServer;
   if (!ds) return void 0;
   return {
     command: ds.command,
@@ -5011,13 +5013,9 @@ done
 \`\`\`
 If the dev server fails to start (e.g. DB connection issues), skip browser verification and proceed with code-only changes. Do NOT hang waiting for it.
 After you are done browsing, kill the dev server: \`kill $DEV_PID 2>/dev/null || true\``;
-  if (stageName === "build" || stageName === "review-fix") {
-    return `## Browser Visual Verification (MANDATORY for UI tasks)
-
-This task involves UI changes. You MUST visually verify your implementation using the browser tools.
-${devServerBlock}
-
-### Available Browser Tools
+  const config = getProjectConfig();
+  const hasMcpPlaywright = isMcpEnabledForStage(stageName, config.mcp);
+  const mcpTools = `### Available Browser Tools
 - \`mcp__playwright__browser_navigate\` \u2014 go to a URL
 - \`mcp__playwright__browser_snapshot\` \u2014 capture accessibility tree (shows all elements, text, roles)
 - \`mcp__playwright__browser_take_screenshot\` \u2014 take a visual screenshot
@@ -5029,14 +5027,50 @@ ${devServerBlock}
 - \`mcp__playwright__browser_press_key\` \u2014 press keyboard keys (Enter, Escape, Tab, etc.)
 - \`mcp__playwright__browser_resize\` \u2014 resize viewport (test responsive layouts)
 - \`mcp__playwright__browser_wait_for\` \u2014 wait for text to appear/disappear
-- \`mcp__playwright__browser_evaluate\` \u2014 run JavaScript on the page
+- \`mcp__playwright__browser_evaluate\` \u2014 run JavaScript on the page`;
+  const cliTools = `### Browser Verification via Playwright CLI
+Use the \`playwright-cli\` commands in your bash tool to interact with the browser:
+\`\`\`bash
+# Take a screenshot of a page
+playwright-cli screenshot ${serverUrl ?? "http://localhost:3000"} --output /tmp/screenshot.png
+
+# Navigate and interact
+playwright-cli open ${serverUrl ?? "http://localhost:3000"}
+
+# Run a quick verification script
+npx playwright test --grep "homepage" --reporter=list
+\`\`\`
+
+Alternatively, write and run a short Playwright script to verify the UI:
+\`\`\`bash
+node -e "
+const { chromium } = require('playwright');
+(async () => {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  await page.goto('${serverUrl ?? "http://localhost:3000"}');
+  await page.screenshot({ path: '/tmp/verify.png', fullPage: true });
+  console.log('Title:', await page.title());
+  await browser.close();
+})();
+"
+\`\`\`
+Use the screenshot output and page title to verify the UI is rendering correctly.`;
+  const toolsBlock = hasMcpPlaywright ? mcpTools : cliTools;
+  if (stageName === "build" || stageName === "review-fix") {
+    return `## Browser Visual Verification (MANDATORY for UI tasks)
+
+This task involves UI changes. You MUST visually verify your implementation using the browser tools.
+${devServerBlock}
+
+${toolsBlock}
 
 ### Verification Steps (DO ALL OF THESE)
 1. Start the dev server (see above)
-2. Use \`browser_navigate\` to go to the affected page(s)
-3. Use \`browser_snapshot\` to capture the page and verify elements are present
-4. **Test interactions**: if the task involves buttons, forms, search, toggles, or any interactive elements \u2014 click them, type into them, and verify the result with another snapshot
-5. If the task mentions responsive behavior, use \`browser_resize\` to test at different widths (e.g., 1200px, 768px, 480px) and take snapshots at each
+2. Navigate to the affected page(s)
+3. Take a screenshot or snapshot to verify elements are present
+4. **Test interactions**: if the task involves buttons, forms, search, toggles, or any interactive elements \u2014 click them, type into them, and verify the result
+5. If the task mentions responsive behavior, test at different viewport widths (e.g., 1200px, 768px, 480px)
 6. Kill the dev server when done
 
 Do NOT skip the browser verification. The visual check AND interaction testing are required parts of implementing UI changes.`;
@@ -5047,22 +5081,14 @@ Do NOT skip the browser verification. The visual check AND interaction testing a
 This task involves UI changes. You MUST visually verify the implementation using the browser tools before giving your verdict.
 ${devServerBlock}
 
-### Available Browser Tools
-- \`mcp__playwright__browser_navigate\` \u2014 go to a URL
-- \`mcp__playwright__browser_snapshot\` \u2014 capture accessibility tree (shows all elements, text, roles)
-- \`mcp__playwright__browser_take_screenshot\` \u2014 take a visual screenshot
-- \`mcp__playwright__browser_click\` \u2014 click an element
-- \`mcp__playwright__browser_type\` \u2014 type text into an input
-- \`mcp__playwright__browser_hover\` \u2014 hover over an element
-- \`mcp__playwright__browser_resize\` \u2014 resize viewport
-- \`mcp__playwright__browser_wait_for\` \u2014 wait for text to appear/disappear
+${toolsBlock}
 
 ### Review Verification Steps (DO ALL OF THESE)
 1. Start the dev server (see above)
-2. Use \`browser_navigate\` to go to the affected page(s)
-3. Use \`browser_snapshot\` to verify elements, layout, and text content
+2. Navigate to the affected page(s)
+3. Take a screenshot or snapshot to verify elements, layout, and text content
 4. **Test interactions**: click buttons, fill forms, test search \u2014 verify the UI responds correctly
-5. If the task mentions responsive behavior, use \`browser_resize\` to test at different widths
+5. If the task mentions responsive behavior, test at different viewport widths
 6. Include your browser verification findings in the review (what you saw, what you interacted with, what worked/failed)
 7. Kill the dev server when done
 
@@ -5070,10 +5096,12 @@ Do NOT skip the browser verification. A review of UI changes without visual AND
   }
   return `## Browser Tools Available
 
-You have access to Playwright MCP browser tools for visual verification.
+You have access to browser tools for visual verification.
 ${devServerBlock}
 
-Use browser tools to navigate to pages and take snapshots to verify UI output.`;
+${toolsBlock}
+
+Use browser tools to navigate to pages and take screenshots to verify UI output.`;
 }
 function buildFullPrompt(stageName, taskId, taskDir, projectDir, feedback) {
   const config = getProjectConfig();
@@ -5089,7 +5117,9 @@ function buildFullPrompt(stageName, taskId, taskDir, projectDir, feedback) {
 
 ${prompt}` : prompt;
   }
-  if (isMcpEnabledForStage(stageName, config.mcp) && taskHasUI(taskDir)) {
+  const browserStages = ["build", "review", "review-fix"];
+  const hasBrowserTools = isMcpEnabledForStage(stageName, config.mcp) || config.devServer && browserStages.includes(stageName);
+  if (hasBrowserTools && taskHasUI(taskDir)) {
     assembled = assembled + "\n\n" + getBrowserToolGuidance(stageName, taskDir);
     const qaGuidePath = path21.join(projectDir, ".kody", "qa-guide.md");
     if (fs23.existsSync(qaGuidePath)) {
@@ -5198,8 +5228,23 @@ async function pollReady(url, timeoutSec) {
   }
   return false;
 }
+async function waitForReady(url, timeoutSec, stdoutMatch) {
+  const deadline = Date.now() + timeoutSec * 1e3;
+  while (Date.now() < deadline) {
+    if (stdoutMatch()) {
+      logger.info("  Dev server stdout matched ready pattern");
+      const httpTimeout = Math.min(15, Math.max(1, Math.floor((deadline - Date.now()) / 1e3)));
+      return pollReady(url, httpTimeout);
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  return false;
+}
 async function startDevServer(opts) {
-  const timeout = opts.readyTimeout ?? 30;
+  const timeout = opts.readyTimeout ?? 60;
+  const patternStr = opts.readyPattern ?? DEFAULT_READY_PATTERN;
+  const pattern = new RegExp(patternStr, "i");
+  const useStdoutDetection = Boolean(opts.readyPattern);
   const [cmd, ...args2] = opts.command.split(/\s+/);
   let child;
   try {
@@ -5216,8 +5261,10 @@ async function startDevServer(opts) {
   }
   let stdout = "";
   let stderr = "";
+  let stdoutMatched = false;
   child.stdout?.on("data", (chunk) => {
     stdout += chunk.toString();
+    if (!stdoutMatched && pattern.test(stdout)) stdoutMatched = true;
   });
   child.stderr?.on("data", (chunk) => {
     stderr += chunk.toString();
@@ -5227,7 +5274,7 @@ async function startDevServer(opts) {
     exited = true;
   });
   child.unref();
-  const ready = await pollReady(opts.url, timeout);
+  const ready = useStdoutDetection ? await waitForReady(opts.url, timeout, () => stdoutMatched) : await pollReady(opts.url, timeout);
   if (!ready) {
     if (exited) {
       logger.warn(`  Dev server exited before becoming ready`);
@@ -5254,10 +5301,12 @@ async function startDevServer(opts) {
   };
   return { ready, url: opts.url, pid, stop };
 }
+var DEFAULT_READY_PATTERN;
 var init_dev_server = __esm({
   "src/dev-server.ts"() {
     "use strict";
     init_logger();
+    DEFAULT_READY_PATTERN = "Ready in|compiled|started server|Local:|localhost:";
   }
 });
 
@@ -5318,9 +5367,10 @@ async function executeAgentStage(ctx, def) {
   if (mcpConfigJson) {
     logger.info(`  MCP servers enabled for ${def.name}`);
   }
+  const devServerStages = ["build", "review", "review-fix"];
   let devServerHandle = null;
-  const ds = config.mcp?.devServer;
-  if (mcpConfigJson && ds && taskHasUI(ctx.taskDir)) {
+  const ds = config.devServer;
+  if (ds && devServerStages.includes(def.name) && taskHasUI(ctx.taskDir)) {
     logger.info(`  Starting dev server: ${ds.command}`);
     const envVars = {};
     for (const varName of ds.env ?? []) {
@@ -5329,7 +5379,8 @@ async function executeAgentStage(ctx, def) {
     devServerHandle = await startDevServer({
       command: ds.command,
       url: ds.url,
-      readyTimeout: ds.readyTimeout ?? 30,
+      readyTimeout: ds.readyTimeout ?? 60,
+      readyPattern: ds.readyPattern ?? "Ready in|compiled|started server|Local:|localhost:",
       envVars
     });
     if (devServerHandle.ready) {
@@ -8242,28 +8293,33 @@ function buildConfig(cwd, basic) {
   };
   const mcp = detectMcpConfig(cwd, basic.pm, pkg);
   if (mcp) config.mcp = mcp;
+  const devServer = detectDevServer(basic.pm, pkg);
+  if (devServer) config.devServer = devServer;
   return config;
 }
-function detectMcpConfig(cwd, pm, pkg) {
+function detectDevServer(pm, pkg) {
   const allDeps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
   const hasFrontend = FRONTEND_DEPS.some((dep) => dep in allDeps);
   if (!hasFrontend) return void 0;
   const scripts = pkg.scripts ?? {};
-  const hasDevScript = !!scripts.dev;
+  if (!scripts.dev) return void 0;
   const isNext = "next" in allDeps || "nuxt" in allDeps;
   const isVite = "vite" in allDeps;
   const defaultPort = isNext ? 3e3 : isVite ? 5173 : 3e3;
+  return {
+    command: `${pm} dev`,
+    url: `http://localhost:${defaultPort}`
+  };
+}
+function detectMcpConfig(cwd, pm, pkg) {
+  const allDeps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
+  const hasFrontend = FRONTEND_DEPS.some((dep) => dep in allDeps);
+  if (!hasFrontend) return void 0;
   const mcp = {
     enabled: true,
     servers: {},
     stages: ["build", "review"]
   };
-  if (hasDevScript) {
-    mcp.devServer = {
-      command: `${pm} dev`,
-      url: `http://localhost:${defaultPort}`
-    };
-  }
   return mcp;
 }
 

package/kody.config.schema.json

@@ -241,7 +241,7 @@
         },
         "devServer": {
           "type": "object",
-          "description": "Dev server configuration for browser tool verification",
+          "description": "DEPRECATED: Use top-level devServer instead. Kept for backward compatibility.",
           "properties": {
             "command": {
               "type": "string",
@@ -270,6 +270,34 @@
       },
       "required": ["enabled", "servers"],
       "additionalProperties": false
+    },
+    "devServer": {
+      "type": "object",
+      "description": "Dev server configuration for browser tool verification. Works with any provider (MCP or CLI-based).",
+      "properties": {
+        "command": {
+          "type": "string",
+          "description": "Command to start the dev server (e.g., 'pnpm dev')"
+        },
+        "url": {
+          "type": "string",
+          "description": "URL where the dev server will be accessible (e.g., 'http://localhost:3000')"
+        },
+        "readyPattern": {
+          "type": "string",
+          "description": "Regex pattern to match in stdout when server is ready. Default: 'Ready in|compiled|started server|Local:'"
+        },
+        "readyTimeout": {
+          "type": "number",
+          "description": "Seconds to wait for the server to be ready. Default: 30"
+        },
+        "env": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "List of GitHub secret names to forward as environment variables for the dev server process (e.g., ['BLOB_READ_WRITE_TOKEN', 'DATABASE_URL']). These are injected into the workflow env block during 'kody init'."
+        }
+      },
+      "required": ["command", "url"]
     }
   },
   "additionalProperties": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine-lite",
-  "version": "0.1.141",
+  "version": "0.1.143",
   "description": "Autonomous SDLC pipeline: Kody orchestration + Claude Code + LiteLLM",
   "license": "MIT",
   "type": "module",