@aayambansal/squint 0.2.8 → 0.3.0

package/README.md

@@ -150,6 +150,9 @@ squint doctor --probe             # run every engine end to end, verify auth act
 - **Problems**: findings from gates, the dev server, the runtime probe, and a11y sweeps
   collect into a list — `/problems` shows it, `/fix` sends everything as one turn,
   `/fix <n>` targets one. The footer counts what's open.
+- **Sandbox**: `/sandbox on` and asks accumulate in a shadow worktree — the dev server,
+  gates, and probes all run there; `/sandbox diff` shows what is staged, `apply` lands it
+  as one diff, `discard` walks away with the real tree untouched.
 - **Variants without leaving**: `/variants 3 <ask>` runs parallel explorations with
   streaming per-family status; `/variants apply <id>` keeps the winner.
 - **Commands**: type `/` and matching commands appear with descriptions; tab completes.
@@ -228,6 +231,7 @@ All product behavior lives in the harness, so a new engine is ~80 lines.
 
 - [Engine setup guide](./docs/engines.md) — install + auth for all eight, and how to choose
 - [Configuration](./docs/configuration.md) — every key, every `.squint/` file
+- [The loops](./docs/loops.md) — everything that runs automatically around each turn
 - [Architecture](./docs/design/2026-07-25-architecture.md)
 - [How Lovable works under the hood](./docs/research/lovable.md)
 - [Making agents produce excellent frontend work](./docs/research/frontend-quality.md)

package/dist/{cdp-SFWNP7OA.js → cdp-4IZHB3W5.js}

@@ -3,7 +3,7 @@ import {
   cdpCapture,
   hasWebSocket,
   pixelDiffPct
-} from "./chunk-OC6RU6XH.js";
+} from "./chunk-QEENJGCL.js";
 export {
   cdpCapture,
   hasWebSocket,

package/dist/{chrome-NVU47PLK.js → chrome-SBV3H77F.js}

@@ -2,8 +2,8 @@
 import {
   findChrome,
   screenshot
-} from "./chunk-B7LOERSP.js";
-import "./chunk-BWZFACBT.js";
+} from "./chunk-IMDRXXFU.js";
+import "./chunk-KVYGPLWW.js";
 export {
   findChrome,
   screenshot

package/dist/{chunk-X6MDBKED.js → chunk-A64VVTPU.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runAgent
-} from "./chunk-C7WKNJG6.js";
+} from "./chunk-VH7OOFQP.js";
 import {
   FAMILIES,
   FIRST_TURN_ADDENDUM,

package/dist/chunk-CFWKEIJJ.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+// src/session/commands.ts
+var COMMANDS = [
+  { name: "dev", args: "[restart|logs]", group: "build", description: "start/stop the dev server; restart or show recent output" },
+  { name: "mode", args: "plan|safe|yolo", group: "build", description: "how much the engine may do (shift+tab cycles)" },
+  { name: "engine", args: "<id>", group: "build", description: "switch backend (new session)" },
+  { name: "engines", group: "build", description: "list installed engines with streaming/resume support" },
+  { name: "model", args: "[name]", group: "build", description: "model override for the engine" },
+  { name: "queue", args: "clear|drop <n>", group: "build", description: "clear the queue or drop one queued ask" },
+  { name: "check", group: "verify", description: "run all quality gates (typecheck, lint, format, test, build)" },
+  { name: "problems", group: "verify", description: "list open findings from gates, dev server, runtime, a11y" },
+  { name: "fix", args: "[n]", group: "verify", description: "send all open problems to the engine, or just problem n" },
+  { name: "shot", args: "[url]", group: "verify", description: "screenshot the app (or any url) at mobile/tablet/desktop" },
+  { name: "review", args: "[focus]", group: "verify", description: "screenshots + the engine critiques its own rendered work" },
+  { name: "variants", args: "<2-4> <ask>", group: "explore", description: "parallel design explorations; apply/list/clean" },
+  { name: "sandbox", args: "[on|diff|apply|discard]", group: "explore", description: "asks accumulate in a shadow worktree until you apply" },
+  { name: "undo", group: "explore", description: "revert the last ask (files only)" },
+  { name: "checkpoints", group: "explore", description: "list per-ask checkpoints" },
+  { name: "restore", args: "<n>", group: "explore", description: "rewind files to before ask n" },
+  { name: "theme", args: "[name]", group: "session", description: "switch the TUI theme", viewLevel: true },
+  { name: "copy", group: "session", description: "copy the last reply to the clipboard" },
+  { name: "save", group: "session", description: "export the transcript to .squint/transcripts/" },
+  { name: "resume", group: "session", description: "pick up the previous session for this repo" },
+  { name: "clear", group: "session", description: "new session (transcript, totals, persisted state)" },
+  { name: "help", group: "session", description: "list commands" },
+  { name: "quit", group: "session", description: "exit with a session summary" }
+];
+function completeCommand(partial) {
+  const query = partial.toLowerCase();
+  return COMMANDS.filter((c) => c.name.startsWith(query));
+}
+var GROUP_TITLES = {
+  build: "build",
+  verify: "verify",
+  explore: "explore & rewind",
+  session: "session"
+};
+function commandHelp() {
+  const sections = [];
+  for (const group of ["build", "verify", "explore", "session"]) {
+    const rows = COMMANDS.filter((c) => c.group === group).map(
+      (c) => `  /${c.name}${c.args ? ` ${c.args}` : ""} \u2014 ${c.description}`
+    );
+    sections.push(`${GROUP_TITLES[group]}
+${rows.join("\n")}`);
+  }
+  return sections.join("\n");
+}
+
+export {
+  COMMANDS,
+  completeCommand,
+  commandHelp
+};

package/dist/{chunk-5VKUJPOL.js → chunk-F6JZSXEO.js}

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import {
   variantsRoot
-} from "./chunk-X6MDBKED.js";
+} from "./chunk-A64VVTPU.js";
 import {
   findChrome,
   screenshot
-} from "./chunk-B7LOERSP.js";
+} from "./chunk-IMDRXXFU.js";
 import {
   lineSplitter
-} from "./chunk-BWZFACBT.js";
+} from "./chunk-KVYGPLWW.js";
 
 // src/variants/shots.ts
 import path2 from "path";

package/dist/{chunk-B7LOERSP.js → chunk-IMDRXXFU.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   findBinary
-} from "./chunk-BWZFACBT.js";
+} from "./chunk-KVYGPLWW.js";
 
 // src/preview/chrome.ts
 import { spawn } from "child_process";

package/dist/{chunk-BWZFACBT.js → chunk-KVYGPLWW.js}

@@ -98,8 +98,18 @@ function createClaudeStreamParser(readyLabel) {
             durationMs: data.duration_ms
           }
         ];
-      case "user":
-        return [];
+      case "user": {
+        if (data.parent_tool_use_id) return [];
+        const events = [];
+        for (const block of data.message?.content ?? []) {
+          if (block.type === "tool_result" && block.is_error === true) {
+            const raw = Array.isArray(block.content) ? block.content.map((c) => c?.text ?? "").join(" ") : String(block.content ?? "");
+            const text = raw.trim().split("\n").at(-1) ?? "";
+            if (text) events.push({ type: "status", text: `\u26A0 tool error \xB7 ${truncate(text, 100)}` });
+          }
+        }
+        return events;
+      }
       case "rate_limit_event":
         return [];
       default:

package/dist/chunk-O2S6PAJE.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+// src/state/state.ts
+import fs from "fs";
+import path from "path";
+var IGNORED = ["preview/", "state.json", "variants/", "sandbox/", "sandbox.patch", "transcripts/"];
+function ensureSquintIgnore(cwd) {
+  const dir = path.join(cwd, ".squint");
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, ".gitignore");
+  let existing = "";
+  try {
+    existing = fs.readFileSync(file, "utf8");
+  } catch {
+  }
+  const lines = existing.split("\n").filter((l) => l.trim().length > 0);
+  const missing = IGNORED.filter((entry) => !lines.includes(entry));
+  if (missing.length > 0) {
+    fs.writeFileSync(file, [...lines, ...missing].join("\n") + "\n");
+  }
+}
+function stateFile(cwd) {
+  return path.join(cwd, ".squint", "state.json");
+}
+function loadState(cwd) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(stateFile(cwd), "utf8"));
+    if (typeof raw?.engine === "string" && typeof raw?.sessionId === "string" && typeof raw?.at === "number") {
+      return raw;
+    }
+  } catch {
+  }
+  return null;
+}
+function saveState(cwd, state) {
+  ensureSquintIgnore(cwd);
+  fs.writeFileSync(stateFile(cwd), JSON.stringify(state, null, 2) + "\n");
+}
+function clearState(cwd) {
+  try {
+    fs.rmSync(stateFile(cwd));
+  } catch {
+  }
+}
+
+export {
+  ensureSquintIgnore,
+  loadState,
+  saveState,
+  clearState
+};

package/dist/{chunk-OC6RU6XH.js → chunk-QEENJGCL.js}

@@ -201,11 +201,56 @@ async function pixelDiffPct(chromePath, pngA, pngB) {
     setTimeout(() => fs.rmSync(profileDir, { recursive: true, force: true }), 500).unref?.();
   }
 }
+var SLOP_AUDIT = `(() => {
+  const out = [];
+  const bodyFont = (getComputedStyle(document.body).fontFamily || '').toLowerCase();
+  const h1 = document.querySelector('h1,h2');
+  const displayFont = h1 ? (getComputedStyle(h1).fontFamily || '').toLowerCase() : bodyFont;
+  for (const tell of ['inter', 'roboto', 'arial', 'space grotesk']) {
+    if (displayFont.includes(tell) || bodyFont.split(',')[0].includes(tell)) {
+      out.push('generic font stack: ' + tell + ' (' + (displayFont.includes(tell) ? 'display' : 'body') + ')');
+      break;
+    }
+  }
+  const vw = innerWidth, vh = innerHeight;
+  for (const el of document.querySelectorAll('*')) {
+    const r = el.getBoundingClientRect();
+    if (r.top > vh || r.width * r.height < vw * vh * 0.2) continue;
+    const bg = getComputedStyle(el).backgroundImage || '';
+    if (bg.includes('gradient')) {
+      const purples = bg.match(/rgb\\((\\d+),\\s*(\\d+),\\s*(\\d+)/g) || [];
+      if (purples.some((c) => { const [r2, g2, b2] = c.slice(4).split(',').map(Number); return b2 > 150 && r2 > 80 && r2 < 200 && g2 < r2; })) {
+        out.push('purple/violet gradient on a hero-scale element');
+        break;
+      }
+    }
+  }
+  for (const container of document.querySelectorAll('section, div')) {
+    const kids = [...container.children];
+    if (kids.length < 3 || kids.length > 4) continue;
+    const rects = kids.map((k) => k.getBoundingClientRect());
+    if (rects[0].width < 150 || rects[0].top > vh * 2) continue;
+    const sameSize = rects.every((r) => Math.abs(r.width - rects[0].width) < 4 && Math.abs(r.height - rects[0].height) < 24);
+    const cardish = kids.every((k) => k.querySelector('svg, img') && k.querySelector('h2,h3,h4') && k.querySelector('p'));
+    if (sameSize && cardish) { out.push('identical icon-card grid (' + kids.length + ' cards)'); break; }
+  }
+  let emojiBullets = 0;
+  for (const li of document.querySelectorAll('li')) {
+    if (/^[\\u{1F300}-\\u{1FAFF}\\u{2600}-\\u{27BF}]/u.test((li.textContent || '').trim())) emojiBullets++;
+  }
+  if (emojiBullets >= 3) out.push(emojiBullets + ' emoji-bulleted list items');
+  const rootStyle = getComputedStyle(document.documentElement);
+  if (rootStyle.getPropertyValue('--radius').trim() === '0.5rem' && rootStyle.getPropertyValue('--primary').trim() === '222.2 47.4% 11.2%') {
+    out.push('untouched shadcn default theme tokens');
+  }
+  return out.slice(0, 8);
+})()`;
 async function cdpCapture(chromePath, url, outDir, viewports, settleMs = 2500, audit = false) {
   const { child, wsUrl, profileDir } = await launchChrome(chromePath);
   const report = { consoleErrors: [], pageErrors: [], failedRequests: [] };
   const shots = [];
   let a11y = [];
+  let slop = [];
   const requests = /* @__PURE__ */ new Map();
   let connection = null;
   try {
@@ -260,6 +305,15 @@ async function cdpCapture(chromePath, url, outDir, viewports, settleMs = 2500, a
         if (Array.isArray(result?.value)) a11y = result.value.map(String);
       } catch {
       }
+      try {
+        const { result } = await connection.send(
+          "Runtime.evaluate",
+          { expression: SLOP_AUDIT, returnByValue: true },
+          sessionId
+        );
+        if (Array.isArray(result?.value)) slop = result.value.map(String);
+      } catch {
+      }
     }
     for (const viewport of viewports) {
       await connection.send(
@@ -283,7 +337,7 @@ async function cdpCapture(chromePath, url, outDir, viewports, settleMs = 2500, a
     child.kill("SIGKILL");
     setTimeout(() => fs.rmSync(profileDir, { recursive: true, force: true }), 500).unref?.();
   }
-  return { report, shots, a11y };
+  return { report, shots, a11y, slop };
 }
 
 export {

package/dist/{chunk-CHZE3UHK.js → chunk-RQFFAJFE.js}

@@ -2,61 +2,19 @@
 import {
   findChrome,
   screenshot
-} from "./chunk-B7LOERSP.js";
+} from "./chunk-IMDRXXFU.js";
 import {
   cdpCapture,
   hasWebSocket
-} from "./chunk-OC6RU6XH.js";
+} from "./chunk-QEENJGCL.js";
+import {
+  ensureSquintIgnore
+} from "./chunk-O2S6PAJE.js";
 
 // src/preview/preview.ts
-import fs2 from "fs";
-import os from "os";
-import path2 from "path";
-
-// src/state/state.ts
 import fs from "fs";
+import os from "os";
 import path from "path";
-var IGNORED = ["preview/", "state.json", "variants/", "transcripts/"];
-function ensureSquintIgnore(cwd) {
-  const dir = path.join(cwd, ".squint");
-  fs.mkdirSync(dir, { recursive: true });
-  const file = path.join(dir, ".gitignore");
-  let existing = "";
-  try {
-    existing = fs.readFileSync(file, "utf8");
-  } catch {
-  }
-  const lines = existing.split("\n").filter((l) => l.trim().length > 0);
-  const missing = IGNORED.filter((entry) => !lines.includes(entry));
-  if (missing.length > 0) {
-    fs.writeFileSync(file, [...lines, ...missing].join("\n") + "\n");
-  }
-}
-function stateFile(cwd) {
-  return path.join(cwd, ".squint", "state.json");
-}
-function loadState(cwd) {
-  try {
-    const raw = JSON.parse(fs.readFileSync(stateFile(cwd), "utf8"));
-    if (typeof raw?.engine === "string" && typeof raw?.sessionId === "string" && typeof raw?.at === "number") {
-      return raw;
-    }
-  } catch {
-  }
-  return null;
-}
-function saveState(cwd, state) {
-  ensureSquintIgnore(cwd);
-  fs.writeFileSync(stateFile(cwd), JSON.stringify(state, null, 2) + "\n");
-}
-function clearState(cwd) {
-  try {
-    fs.rmSync(stateFile(cwd));
-  } catch {
-  }
-}
-
-// src/preview/preview.ts
 var VIEWPORTS = [
   { name: "mobile", width: 390, height: 844 },
   { name: "tablet", width: 768, height: 1024 },
@@ -65,7 +23,7 @@ var VIEWPORTS = [
 function loadRoutes(cwd) {
   let lines = [];
   try {
-    lines = fs2.readFileSync(path2.join(cwd, ".squint", "routes"), "utf8").split("\n").map((l) => l.trim()).filter((l) => l.length > 0 && !l.startsWith("#"));
+    lines = fs.readFileSync(path.join(cwd, ".squint", "routes"), "utf8").split("\n").map((l) => l.trim()).filter((l) => l.length > 0 && !l.startsWith("#"));
   } catch {
   }
   const routes = ["/", ...lines.filter((l) => l !== "/")];
@@ -76,8 +34,8 @@ function routeShotName(route) {
   return clean.length > 0 ? clean : "root";
 }
 function previewDir(cwd) {
-  const dir = path2.join(cwd, ".squint", "preview");
-  fs2.mkdirSync(dir, { recursive: true });
+  const dir = path.join(cwd, ".squint", "preview");
+  fs.mkdirSync(dir, { recursive: true });
   ensureSquintIgnore(cwd);
   return dir;
 }
@@ -89,7 +47,7 @@ async function captureViewports(cwd, url) {
   const base = url.replace(/\/+$/, "");
   if (hasWebSocket()) {
     try {
-      const { report, shots: shots2, a11y } = await cdpCapture(chrome, url, dir, VIEWPORTS, 2500, true);
+      const { report, shots: shots2, a11y, slop } = await cdpCapture(chrome, url, dir, VIEWPORTS, 2500, true);
       const errors2 = [];
       for (const route of routes.slice(1)) {
         try {
@@ -104,14 +62,14 @@ async function captureViewports(cwd, url) {
           errors2.push(`${route}: capture failed`);
         }
       }
-      return { shots: shots2, errors: errors2, runtime: report, a11y };
+      return { shots: shots2, errors: errors2, runtime: report, a11y, slop };
     } catch {
     }
   }
   const shots = [];
   const errors = [];
   for (const viewport of VIEWPORTS) {
-    const outPath = path2.join(dir, `${viewport.name}.png`);
+    const outPath = path.join(dir, `${viewport.name}.png`);
     const result = await screenshot(chrome, url, outPath, {
       width: viewport.width,
       height: viewport.height
@@ -175,7 +133,7 @@ async function probeRuntime(url, cwd) {
 async function comparePulse(previous, current) {
   const chrome = findChrome();
   if (!chrome || !hasWebSocket()) return null;
-  const { pixelDiffPct } = await import("./cdp-SFWNP7OA.js");
+  const { pixelDiffPct } = await import("./cdp-4IZHB3W5.js");
   return pixelDiffPct(chrome, previous, current);
 }
 function buildRuntimeFixPrompt(report) {
@@ -193,19 +151,26 @@ ${findings.join("\n")}
 
 Fix these as part of the pass \u2014 they are objective defects, not style preferences.`;
 }
-function buildReviewPrompt(shots, extra, runtime, a11y) {
+function slopSection(findings) {
+  if (!findings || findings.length === 0) return "";
+  return `
+
+## Distinctiveness debt (detected mechanically)
+
+${findings.join("\n")}
+
+These patterns make the page read as template output. Rework them within the committed design direction \u2014 this is style debt, not a defect list.`;
+}
+function buildReviewPrompt(shots, extra, runtime, a11y, slop) {
   const list = shots.map((s) => `- ${s.name}: ${s.path}`).join("\n");
   return `Screenshots of the running app were just captured:
 
 ${list}
 
-Read each screenshot and review the rendered UI against the design standards you were given. Check: visual hierarchy and spacing rhythm, typography, color and contrast, alignment, empty-looking or broken regions, and whether the mobile capture shows horizontal overflow or cramped layout. List the concrete issues you can SEE (not hypothetical ones), ranked by visual impact${extra ? `, with special attention to: ${extra}` : ""}. Then fix them and verify the app still builds.${runtimeSection(runtime)}${a11ySection(a11y)}`;
+Read each screenshot and review the rendered UI against the design standards you were given. Check: visual hierarchy and spacing rhythm, typography, color and contrast, alignment, empty-looking or broken regions, and whether the mobile capture shows horizontal overflow or cramped layout. List the concrete issues you can SEE (not hypothetical ones), ranked by visual impact${extra ? `, with special attention to: ${extra}` : ""}. Then fix them and verify the app still builds.${runtimeSection(runtime)}${a11ySection(a11y)}${slopSection(slop)}`;
 }
 
 export {
-  loadState,
-  saveState,
-  clearState,
   VIEWPORTS,
   loadRoutes,
   routeShotName,

package/dist/{chunk-C7WKNJG6.js → chunk-VH7OOFQP.js}

@@ -3,7 +3,7 @@ import {
   findEngineBinary,
   lineSplitter,
   truncate
-} from "./chunk-BWZFACBT.js";
+} from "./chunk-KVYGPLWW.js";
 
 // src/runner/run.ts
 import { spawn } from "child_process";

package/dist/chunk-XEQ6JXXL.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+// src/vcs/sandbox.ts
+import { execFileSync } from "child_process";
+import fs from "fs";
+import path from "path";
+function git(cwd, args) {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+function sandboxDir(cwd) {
+  return path.join(cwd, ".squint", "sandbox");
+}
+function sandboxExists(cwd) {
+  return fs.existsSync(path.join(sandboxDir(cwd), ".git"));
+}
+function openSandbox(cwd) {
+  const dir = sandboxDir(cwd);
+  void import("./state-QOS7WCZO.js").then(({ ensureSquintIgnore }) => ensureSquintIgnore(cwd)).catch(() => {
+  });
+  if (sandboxExists(cwd)) return { dir, reused: true };
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  git(cwd, ["worktree", "add", "--force", "--detach", dir, "HEAD"]);
+  const mainModules = path.join(cwd, "node_modules");
+  const sandboxModules = path.join(dir, "node_modules");
+  if (fs.existsSync(mainModules) && !fs.existsSync(sandboxModules)) {
+    fs.symlinkSync(mainModules, sandboxModules, "dir");
+  }
+  return { dir, reused: false };
+}
+function sandboxDiffStat(cwd) {
+  if (!sandboxExists(cwd)) return null;
+  const dir = sandboxDir(cwd);
+  try {
+    git(dir, ["add", "-A"]);
+    const stat = git(dir, ["diff", "--cached", "--shortstat", "HEAD"]);
+    return stat.length > 0 ? stat : null;
+  } catch {
+    return null;
+  }
+}
+function sandboxFiles(cwd) {
+  if (!sandboxExists(cwd)) return [];
+  const dir = sandboxDir(cwd);
+  try {
+    git(dir, ["add", "-A"]);
+    const out = git(dir, ["diff", "--cached", "--name-status", "HEAD"]);
+    return out.length > 0 ? out.split("\n") : [];
+  } catch {
+    return [];
+  }
+}
+function applySandbox(cwd) {
+  if (!sandboxExists(cwd)) return { ok: false, detail: "no sandbox open" };
+  const dir = sandboxDir(cwd);
+  try {
+    git(dir, ["add", "-A"]);
+    const patch = git(dir, ["diff", "--binary", "--cached", "HEAD"]);
+    if (patch.length === 0) return { ok: false, detail: "sandbox has no changes" };
+    const patchFile = path.join(cwd, ".squint", "sandbox.patch");
+    fs.writeFileSync(patchFile, patch + "\n");
+    git(cwd, ["apply", "--whitespace=nowarn", patchFile]);
+    fs.rmSync(patchFile, { force: true });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, detail: err instanceof Error ? err.message.split("\n")[0] : String(err) };
+  }
+}
+function discardSandbox(cwd) {
+  if (!sandboxExists(cwd)) return false;
+  const dir = sandboxDir(cwd);
+  try {
+    const link = path.join(dir, "node_modules");
+    if (fs.existsSync(link) && fs.lstatSync(link).isSymbolicLink()) fs.rmSync(link);
+  } catch {
+  }
+  try {
+    git(cwd, ["worktree", "remove", "--force", dir]);
+  } catch {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+  try {
+    git(cwd, ["worktree", "prune"]);
+  } catch {
+  }
+  return true;
+}
+
+export {
+  sandboxDir,
+  sandboxExists,
+  openSandbox,
+  sandboxDiffStat,
+  sandboxFiles,
+  applySandbox,
+  discardSandbox
+};