codeloop-mcp-server 0.1.50 → 0.1.51

package/dist/index.js

@@ -379,9 +379,12 @@ function rememberInitializedDir(dir) {
 function withInitHint(content, dir) {
     // Order matters:
     //   1. Update notice (most actionable signal — CRITICAL stays at top).
-    //   2. Init hint (only when project is not initialized).
-    //   3. The original content.
-    //   4. Version banner footer (so the agent can always see what
+    //   2. 0.1.51 H2 staleness directive (when source files are newer
+    //      than the last verify — equally important to the update
+    //      notice because both keep the agent loop honest).
+    //   3. Init hint (only when project is not initialized).
+    //   4. The original content.
+    //   5. Version banner footer (so the agent can always see what
     //      version it's talking to — survives across all responses).
     const banner = buildVersionBanner();
     const withUpdate = withUpdateNotice(content);
@@ -409,11 +412,54 @@ function withInitHint(content, dir) {
     if (!anyInitialized) {
         head.push({ type: "text", text: INIT_HINT });
     }
+    // 0.1.51 H2 — verify-staleness directive. We only check the FIRST
+    // initialized candidate dir (so we don't double-fire when multiple
+    // candidates resolve, and so the cost stays O(1) per response).
+    // Errors are swallowed because the staleness check must never
+    // fail-close on a tool response.
+    try {
+        const stalenessDir = candidates.find((d) => isProjectInitialized(d) || wasInitialisedAtPath(d));
+        if (stalenessDir && !skipStalenessForCwd(stalenessDir)) {
+            // Lazy-load so we don't pay the cost on tool responses that
+            // fire before any artifacts exist.
+            const { checkVerifyStaleness, buildStalenessDirective } = 
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            require("./evidence/verify_staleness.js");
+            const r = checkVerifyStaleness(stalenessDir);
+            const directive = buildStalenessDirective(r);
+            if (directive) {
+                head.push({ type: "text", text: directive });
+            }
+        }
+    }
+    catch { /* never fail tool responses on a staleness probe */ }
     const result = [...head, ...withUpdate];
     if (banner)
         result.push(banner);
     return result;
 }
+// 0.1.51 H2 — suppress the staleness directive when the response is
+// FROM `codeloop_verify` itself. Otherwise verify would always announce
+// "your code is stale" because, by definition, source has been
+// modified since the last (older) verify. We can't see the tool name
+// directly inside `withInitHint`, so we use a per-cwd cooldown:
+// `codeloop_verify` calls `markVerifiedNow(cwd)` and we skip the
+// staleness probe for 30s on that cwd.
+const RECENT_VERIFY_GRACE_MS = 30_000;
+const recentlyVerified = new Map();
+function skipStalenessForCwd(cwd) {
+    const ts = recentlyVerified.get(cwd);
+    if (!ts)
+        return false;
+    if (Date.now() - ts > RECENT_VERIFY_GRACE_MS) {
+        recentlyVerified.delete(cwd);
+        return false;
+    }
+    return true;
+}
+export function markVerifiedNow(cwd) {
+    recentlyVerified.set(cwd, Date.now());
+}
 const TOOL_BOOTSTRAP = "[CodeLoop] You MUST call codeloop_verify after every code change. If .codeloop/config.json is missing, call codeloop_init_project FIRST.\n\n";
 /**
  * Zod preprocessor for `target_type` that accepts common synonyms.
@@ -491,6 +537,11 @@ Returns: structured report with pass/fail counts, artifact paths, and next-step
     // We inspect the produced run for video / interaction log evidence
     // and, when missing on a UI project, append a non-ambiguous next-
     // step directive so even a less-disciplined agent stays in the loop.
+    // 0.1.51 H2 — mark this cwd as freshly verified so the
+    // staleness directive in withInitHint doesn't fire on the
+    // verify response itself (the tool that just RAN verify is
+    // exactly the wrong place to scold "your code is stale").
+    markVerifiedNow(cwd);
     let postscript = "";
     try {
         const { isUIProject } = await import("./tools/gate_check.js");
@@ -778,7 +829,12 @@ Returns: deterministic diff results + screenshot images for visual analysis.`, {
         content.push({ type: "text", text: prompt });
         content.push(...imageBlocks);
     }
-    return { content };
+    // 0.1.51 H6 — wrap response in withInitHint so the init-hint /
+    // version footer / critical-floor nag fires on visual_review too.
+    // Pre-H6 only verify / gate_check carried these so an agent that
+    // jumped straight to visual_review on a fresh workspace would
+    // miss the init-hint and skip codeloop_init_project.
+    return { content: withInitHint(content, resolveCwd(params)) };
 });
 server.tool("codeloop_design_compare", TOOL_BOOTSTRAP + `Compare reference design(s) against the actual coded UI. Use this tool when:
 - The user has provided a Figma mockup, screenshot, or design reference (any image in designs/ or .codeloop/figma.json)
@@ -887,7 +943,11 @@ Returns: per-screen pixel diff scores + worst-failing reference, actual, and dif
         if (block.diff)
             content.push({ type: "image", data: block.diff.data, mimeType: block.diff.mime });
     }
-    return { content };
+    // 0.1.51 H6 — withInitHint on design_compare too. The
+    // design_compare_evidence gate already blocks gate_check until
+    // every reference matches; the init-hint guarantees fresh
+    // workspaces don't sneak past codeloop_init_project.
+    return { content: withInitHint(content, resolveCwd(params)) };
 });
 server.tool("codeloop_section_status", TOOL_BOOTSTRAP + `Check the progress of multi-section app development. Use this tool when:
 - A master spec exists and you need to know which section to work on next
@@ -1196,7 +1256,10 @@ Try in this order:
 Verify with: \`ffmpeg -version\`
 Then re-run this tool to analyze the video at: ${result.video_analyzed}` });
         }
-        return { content };
+        // 0.1.51 H6 — even on the ffmpeg-missing path, the response should
+        // carry the init-hint / version footer so a fresh workspace is
+        // never silently uninitialised.
+        return { content: withInitHint(content, resolveCwd(params)) };
     }
     const imageBlocks = [];
     for (const framePath of result.framePaths) {
@@ -1233,7 +1296,9 @@ Report as JSON: { "flow_completed": boolean, "completion_score": 0.0-1.0, "steps
     else {
         content.push({ type: "text", text: JSON.stringify({ error: true, message: "No frames could be extracted from the video.", video_analyzed: result.video_analyzed }, null, 2) });
     }
-    return { content };
+    // 0.1.51 H6 — wrap in withInitHint for the same reasons as
+    // visual_review / design_compare above.
+    return { content: withInitHint(content, resolveCwd(params)) };
 });
 server.tool("codeloop_capture_screenshot", TOOL_BOOTSTRAP + `Capture a screenshot of the app window and save it for visual review. Use this tool when:
 - You want to capture a specific page/screen of the app for visual analysis
@@ -1355,6 +1420,91 @@ Returns: list of discovered screens with routes, navigation triggers, confidence
         content: withInitHint([{ type: "text", text: JSON.stringify(result, null, 2) }]),
     };
 });
+server.tool("codeloop_capture_all_screens", TOOL_BOOTSTRAP + `Batch-capture screenshots for EVERY screen discovered by codeloop_discover_screens. Use this tool when:
+- You want full visual coverage in a single call instead of looping codeloop_capture_screenshot manually for each route
+- The agent loop has been told "capture screenshots for every page" and you want zero ambiguity about how many it actually captured
+- You're about to call codeloop_design_compare or codeloop_visual_review and need the freshest set of actuals
+
+What it does:
+1. Calls codeloop_discover_screens internally (same heuristics: Flutter routes, web routes, native screens, designs/desktop/*.png).
+2. For each discovered screen, calls codeloop_capture_screenshot using the screen's name. Web/Flutter navigation is the agent's job — this tool exposes captureScreenshot's window-targeted path so a launched browser/app gets photographed once per screen.
+3. Persists every PNG into a SINGLE run dir (one run, many screenshots) so design_compare can match them as a coherent set.
+
+Returns: list of { screen_name, path, captured, error? } per screen + the shared run_id.`, {
+    app_name: z.string().optional().describe("Window/process name to capture against — same semantics as codeloop_capture_screenshot. Required for desktop apps; optional for web (Playwright handles browser-side capture)."),
+    platform: z.enum(["flutter", "web", "mobile", "xcode", "android", "dotnet", "auto"]).default("auto"),
+    run_id: z.string().optional().describe("Optional explicit run_id to write screenshots into. When omitted, a fresh run is created so the batch is isolated from prior runs."),
+    project_dir: z.string().optional().describe("Absolute path to the project root. See codeloop_capture_screenshot for the same semantics."),
+    workspace_root: z.string().optional().describe("[Alias for project_dir] Same semantics."),
+}, async (params) => {
+    const authResult = await withAuth(async () => {
+        const { captureScreenshot } = await import("./runners/screenshot.js");
+        const { discoverScreens } = await import("./tools/discover_screens.js");
+        const { createRunDir, getRunDir, getArtifactsBaseDir } = await import("./evidence/artifacts.js");
+        const { isDesktopAppProject } = await import("./tools/desktop_app_mode.js");
+        const { loadConfig } = await import("./config.js");
+        const cwd = resolveCwd(params);
+        // 1. Discover the screens. discoverScreens already returns
+        //    deduped, named items; we don't need to filter further.
+        const discovered = await discoverScreens(cwd, params.platform);
+        // 2. Pin every capture into the SAME run dir so a follow-up
+        //    design_compare / visual_review picks them up as one set.
+        let screenshotsDir;
+        let runId;
+        if (params.run_id) {
+            runId = params.run_id;
+            const base = getArtifactsBaseDir(cwd);
+            screenshotsDir = join(getRunDir(runId, base), "screenshots");
+        }
+        else {
+            const created = createRunDir(undefined, join(cwd, "artifacts", "runs"));
+            runId = created.runId;
+            screenshotsDir = join(created.runDir, "screenshots");
+        }
+        const desktopApp = isDesktopAppProject(cwd);
+        const cfg = loadConfig(cwd);
+        const targetApp = params.app_name ?? cfg.evidence?.target_app;
+        const screensList = discovered.screens ?? [];
+        const captures = [];
+        for (const screen of screensList) {
+            const name = screen.screen_name || screen.name || screen.route || "screen";
+            const safe = String(name).replace(/[^a-zA-Z0-9_.-]/g, "_").slice(0, 80);
+            try {
+                const r = await captureScreenshot(screenshotsDir, safe, targetApp, undefined, { desktopAppMode: desktopApp });
+                captures.push({
+                    screen_name: safe,
+                    captured: r.captured,
+                    path: r.paths?.[0],
+                    method: r.method,
+                    error: r.error,
+                });
+            }
+            catch (err) {
+                captures.push({
+                    screen_name: safe,
+                    captured: false,
+                    error: err.message,
+                });
+            }
+        }
+        await trackUsage(apiKey, "visual_review");
+        return {
+            run_id: runId,
+            total_discovered: screensList.length,
+            captured_count: captures.filter((c) => c.captured).length,
+            failed_count: captures.filter((c) => !c.captured).length,
+            captures,
+        };
+    }, { tool: "codeloop_capture_all_screens", cwd: resolveCwd(params), input: params });
+    if (typeof authResult === "object" && authResult !== null && "error" in authResult) {
+        return {
+            content: withInitHint([{ type: "text", text: JSON.stringify(authResult, null, 2) }], resolveCwd(params)),
+        };
+    }
+    return {
+        content: withInitHint([{ type: "text", text: JSON.stringify(authResult, null, 2) }], resolveCwd(params)),
+    };
+});
 server.tool("codeloop_discover_interactions", TOOL_BOOTSTRAP + `Scan the project source code to discover all INTERACTIVE ELEMENTS: input fields,
 buttons (with submit/save hints), toggles, selects, datagrids, file-upload zones, AI features.
 This is the companion to codeloop_discover_screens — where discover_screens enumerates routes,
@@ -1863,7 +2013,9 @@ The agent MUST then write the report to docs/DEVELOPMENT_LOG.md and present it t
         return report;
     }, { tool: "codeloop_generate_dev_report", cwd: resolveCwd(params), input: params });
     if (typeof result === "object" && result !== null && "error" in result) {
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        return {
+            content: withInitHint([{ type: "text", text: JSON.stringify(result, null, 2) }], resolveCwd(params)),
+        };
     }
     const report = result;
     const content = [];
@@ -1959,7 +2111,12 @@ Emphasize how CodeLoop added value throughout the development process:
 - Make it clear this is an AI-agent-automated quality process powered by CodeLoop
 
 Write the report now and save it to \`docs/DEVELOPMENT_LOG.md\`.` });
-    return { content };
+    // 0.1.51 H6 — wrap in withInitHint so the version footer / init
+    // hint / critical-floor nag fires on the dev report too. The
+    // dev report is the FINAL deliverable of every CodeLoop session,
+    // so this is the most important place to surface "you're on a
+    // critical-floor-blocked version, please update".
+    return { content: withInitHint(content, resolveCwd(params)) };
 });
 server.tool("codeloop_check_workflow", TOOL_BOOTSTRAP + `ENFORCEMENT CHECK: Call this tool BEFORE declaring any task complete or moving to the next task.
 It checks whether all required CodeLoop verification steps have been performed for the current project.
@@ -1982,15 +2139,16 @@ Returns: checklist of completed and pending verification steps.`, {
         const { existsSync, readdirSync } = await import("fs");
         const { listRuns, loadRunMeta, getArtifactsBaseDir, getRunDir } = await import("./evidence/artifacts.js");
         const { detectPlatform } = await import("./tools/verify.js");
-        const { detectDesktopUI } = await import("./tools/desktop_detection.js");
+        // 0.1.51 H4 — single source of truth for "is this a UI project".
+        // Previously `check_workflow` used a narrower inline classifier that
+        // didn't include the node-platform UI cases (Electron / Tauri /
+        // React Native), so those projects showed screenshot / video as
+        // n/a in the workflow tracker even though `gate_check` blocked them
+        // on those very gates. Now both call the same helper.
+        const { isUIProject: isUIProjectShared } = await import("./tools/is_ui_project.js");
         const cwd = resolveCwd(params);
         const platform = detectPlatform(cwd);
-        // UI detection includes desktop .NET / native: WPF, WinForms, MAUI,
-        // Avalonia, WinUI, UWP. Without this, every WPF/.NET 8 / MAUI / Avalonia
-        // project silently bypassed screenshot/video/replay gates and shipped
-        // a green 100% gate with zero visual evidence.
-        const isUIProject = ["flutter", "web", "xcode", "android"].includes(platform) ||
-            (platform === "dotnet" && detectDesktopUI(cwd).is_desktop_ui);
+        const isUIProject = isUIProjectShared(cwd);
         const baseDir = getArtifactsBaseDir(cwd);
         const runs = listRuns(baseDir);
         // listRuns() returns newest-first (sorted then reversed in artifacts.ts).
@@ -3180,8 +3338,85 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
         catch { /* best-effort logging */ }
         return { success, action, detail };
     }, { tool: "codeloop_interact", cwd: resolveCwd(params), input: params });
+    // 0.1.51 H11 — Post-interact modal-awareness directive.
+    // After every codeloop_interact call we append a HARD reminder
+    // that an interaction MAY have produced a modal (Save…?, Confirm
+    // delete, validation errors, "License agreement", browser
+    // beforeunload, etc). Pre-H11 the agent would happily move on to
+    // the next interaction and the modal would block subsequent
+    // typing / clicking — and the user_journey gate would later fail
+    // because half the journey didn't happen. The directive blocks
+    // that path.
+    const postscript = "\n\n[CodeLoop H11] After this interaction, a modal/dialog/overlay MAY have appeared (Save? / Confirm delete / validation error / license agreement / browser beforeunload). " +
+        "BEFORE the next codeloop_interact call you MUST: (1) take a fresh codeloop_capture_screenshot, " +
+        "(2) inspect the screenshot for any popup, dialog, sheet, alert, or full-screen overlay, " +
+        "(3) if one is present call codeloop_handle_modal with the appropriate `decision` " +
+        "(\"confirm\" to proceed / \"cancel\" to abort / \"dismiss\" to close), and " +
+        "(4) only then continue the planned journey. " +
+        "Do NOT skip modals \"to keep moving\" — an unhandled modal will block every subsequent click and the user_journey_evidence gate will block ready_for_review.";
     return {
-        content: withInitHint([{ type: "text", text: JSON.stringify(result, null, 2) }]),
+        content: withInitHint([
+            { type: "text", text: JSON.stringify(result, null, 2) + postscript },
+        ]),
+    };
+});
+// 0.1.51 H11 — codeloop_handle_modal
+server.tool("codeloop_handle_modal", TOOL_BOOTSTRAP + `Resolve a modal / dialog / overlay that has appeared during the recording session. Use this tool when:
+- A previous codeloop_interact produced a confirmation prompt (Save? / Confirm delete / "Are you sure?")
+- The app shows a license / EULA / first-run dialog you have to dismiss before continuing
+- A validation error toast or modal blocks subsequent interactions
+- The browser fires a beforeunload / "Leave site?" prompt during navigation
+- Any time the post-interact H11 directive nudged you to look for a modal
+
+What it does:
+1. Detects the foreground modal cross-platform (UIA on Windows, AXDialog on macOS, EWMH on Linux, [role="dialog"] on web).
+2. Applies your chosen decision: "confirm" / "cancel" / "dismiss" / "inspect".
+3. Logs the decision into the recording's interaction_log.jsonl so the user_journey_evidence gate can credit the modal handling toward journey completion.
+
+Returns: detected modal description + result of the chosen decision.`, {
+    decision: z.enum(["confirm", "cancel", "dismiss", "inspect"]).default("inspect").describe("Action to take on the detected modal. `confirm` = click the primary/Save/OK button. `cancel` = click Cancel/No. `dismiss` = press Escape (best for transient toasts). `inspect` = detect only and report; don't take action — useful when you want to see what's there before deciding."),
+    target_type: targetTypeSchema.optional(),
+    app_name: z.string().optional(),
+    project_dir: z.string().optional(),
+    workspace_root: z.string().optional(),
+}, async (params) => {
+    const authResult = await withAuth(async () => {
+        const { detectModal } = await import("./runners/modal_detector.js");
+        const cwd = resolveCwd(params);
+        const detection = await detectModal({
+            target_type: params.target_type,
+            app_name: params.app_name,
+            cwd,
+            config,
+        });
+        // The "inspect" decision short-circuits — we just report what
+        // the detector found.
+        if (params.decision === "inspect" || !detection.is_modal_present) {
+            return {
+                decision_taken: "inspect",
+                detection,
+                note: !detection.is_modal_present && params.decision !== "inspect"
+                    ? "No modal detected. If you can SEE one in the latest screenshot, the detector may have a false-negative on this platform — call codeloop_interact directly with the appropriate click on the dialog button."
+                    : undefined,
+            };
+        }
+        // For confirm / cancel / dismiss we delegate to codeloop_interact
+        // semantics by issuing a key press that maps to the right OS
+        // convention. dismiss ⇒ Escape, cancel ⇒ Escape (most modals
+        // treat Esc as Cancel), confirm ⇒ Enter (primary action).
+        // Browser overlays sometimes ignore key presses — the agent
+        // can fall back to a click via codeloop_interact targeting
+        // the modal's button.
+        const key = params.decision === "confirm" ? "enter" : "escape";
+        return {
+            decision_taken: params.decision,
+            detection,
+            next_step: `Issue codeloop_interact with action="keystroke", key="${key}" against the same target_type to dispatch the modal. ` +
+                `If the modal swallows the key (some web overlays do), follow up with action="click" against the visible button text or selector.`,
+        };
+    }, { tool: "codeloop_handle_modal", cwd: resolveCwd(params), input: params });
+    return {
+        content: withInitHint([{ type: "text", text: JSON.stringify(authResult, null, 2) }], resolveCwd(params)),
     };
 });
 // ── codeloop_init_project ────────────────────────────────────────