flowviant 0.28.9 → 0.29.0

package/bin/cli.mjs

@@ -101,6 +101,16 @@ if (process.argv[2] === 'clean') {
   process.exit(0);
 }
 
+// `flowviant shot <url>` — capture a headless-browser screenshot of a running
+// page. Build agents shell out to this to attach REAL visual evidence to the
+// delivery card. Self-contained + graceful (no browser → exit 1, agent falls
+// back to text evidence); needs no credential, so it runs before the auth gate.
+if (process.argv[2] === 'shot') {
+  const { runShot } = await import('./lib/shot.mjs');
+  await runShot(process.argv.slice(3));
+  process.exit(0);
+}
+
 // `flowviant env <import|set|show>` — the CLI half of team env sync. Values
 // are sealed to the project pubkey ON THIS MACHINE (same write-only crypto as
 // the browser); `show` decrypts locally — it only works on an ENROLLED machine.

package/bin/lib/claude.mjs

@@ -147,32 +147,44 @@ its frontmatter and title are part of the chapter and must comply):
 Open every existing docs/ chapter and FIX any that violate these two rules on
 EVERY run. The sidebar grouping + clean titles depend on it; it is not skippable.
 
-Every chapter declares its sidebar GROUP with a "category:" line in its
-frontmatter — the bold group header it sits under, exactly like the grouped left
-nav in Stripe / HuggingFace docs. Group RELATED chapters under a shared category
-(aim for 2-5 categories total that mirror the codebase's real divisions — e.g.
-"Getting started", "Core runtime", "Workspaces", "Reference"; a category holding a
-single chapter is a smell — merge or regroup). Number the chapters so same-category
-chapters are CONTIGUOUS and the categories flow in reading order. The "# Title" is
-a clean human name — NO number prefix (ordering comes from the filename prefix).
+Every page declares its sidebar GROUP with a "category:" line in its frontmatter
+— the group header it sits under, like the grouped left nav in HuggingFace docs.
+The category may be TWO levels, "Top group / Sub-group", to add HuggingFace's
+second nav tier: use the sub-level to break a LARGE top group into coherent
+sub-groups (e.g. "Workspaces / Fundraising", "Workspaces / Finance & budget"); a
+single level ("Reference") is fine for small groups. Aim for 3-6 top groups that
+mirror the codebase's real divisions; a group OR sub-group holding a single page
+is a smell — merge or regroup. Keep same-group pages CONTIGUOUS by filename number
+so reading order also orders the nav. The "# Title" is a clean human name — NO
+number prefix (ordering comes from the filename prefix).
+
+Prefer MANY FOCUSED pages over a few giant chapters — HuggingFace granularity:
+ONE page per coherent topic, not one page per whole subsystem. If a subsystem is
+large, SPLIT it into several pages (its overview, its data model, its API, its
+key flows), each its own docs/NN-page.md with its own category, so the left nav
+is a fine-grained tree of pages and each page is focused enough to read in one
+sitting. The in-page "## " sections are the right-hand on-this-page rail — the
+left nav is pages, so when a chapter grows more than a handful of "## " sections,
+that is the signal to split it into separate pages.
 
 Fixed spine (flat docs/ files; numeric prefix = reading order):
 - docs/00-start-here.md  (category: "Getting started") — the landing page + MASTER
   TABLE OF CONTENTS: what the product is (2-3 sentences); how to run it locally
   (prerequisites, install, required env, dev server, tests); then a linked table
-  of contents of EVERY chapter GROUPED BY CATEGORY, each with a one-line
-  description; then 2-3 role-based reading paths (e.g. "New to the backend: read
-  Architecture, then Agent fleet, then Data model").
+  of contents of EVERY page GROUPED BY CATEGORY, each with a one-line description;
+  then 2-3 role-based reading paths (e.g. "New to the backend: read Architecture,
+  then Agent fleet, then Data model").
 - docs/01-architecture.md  (category: "Getting started") — the system at a glance:
   a Mermaid diagram (a fenced code block whose language is mermaid) of the major
   components and how they connect, a component-responsibility table, the primary
-  request/data flows, and a link into the chapter for each component.
-- docs/1N-<chapter>.md — ONE chapter per major subsystem, EACH with its own
-  "category:" grouping it with its siblings. Cover every significant subsystem.
+  request/data flows, and a link into the page for each component.
+- docs/NN-<page>.md — the subsystem PAGES: many focused pages (split large
+  subsystems into several), EACH with its own 1- or 2-level "category:" placing it
+  in the nav. Cover every significant part of the system.
 - docs/90-decisions.md  (category: "Reference") — notable design decisions, each as
   context, decision, why, and consequences.
 - docs/91-glossary.md  (category: "Reference") — the project's terms of art,
-  alphabetized, each linking to the chapter or vault page that defines it.
+  alphabetized, each linking to the page that defines it.
 
 EVERY chapter follows this exact anatomy, in order:
   1. YAML frontmatter: a "category:" group header (see the spine) AND a "files:"

package/bin/lib/live.mjs

@@ -112,6 +112,7 @@ const SAFE_TOOLS = [
   'Bash(gh:*)',
   'Bash(npm:*)',
   'Bash(bun:*)',
+  'Bash(flowviant:*)', // `flowviant shot` — capture screenshot evidence
   'mcp__flowviant',
 ];
 
@@ -131,14 +132,21 @@ tools. When you hit a decision only a human can make, call report_blocker (with
 options when you can) and then STOP your turn — do not spin or guess; you will be
 resumed with the answer. As you satisfy each "done when" criterion, call
 attach_evidence for it — proof the reviewer can SEE without running anything.
-Match the evidence to what you built: backend/API work → a request/response
-capture or a data sample showing the write; a single screen → a screenshot.
-CRITICAL for a multi-step FLOW (login, signup, checkout): a screenshot of one
-page does NOT prove the flow works — you MUST prove the whole path end to end.
-Best: write an e2e/integration test that DRIVES the flow (fill form → submit →
-assert the post-login/success state) and attach its test_output; if you have a
-browser tool (e.g. Playwright), also attach a screen recording of it running.
-Never let a static screenshot stand in for a flow. When the work is done: open ONE draft PR (git push +
+This IS your handover, so make it tangible; match the evidence to what you built:
+• UI / any visible screen → attach a real SCREENSHOT. Start the app's dev server
+  in your worktree, then capture it headlessly with
+  \`flowviant shot http://localhost:<PORT>/<route> --out shot.png\` (it finds a
+  browser for you and never needs a display), and attach_evidence with kind
+  "screenshot" and the file's base64 (\`base64 -w0 shot.png\`). Shoot EVERY key
+  screen you changed. If \`flowviant shot\` reports that no browser is available,
+  do NOT block — fall back to the text evidence below.
+• backend / API work → a request/response capture or a data sample showing the
+  write (kind "request_response" or "sample").
+• a multi-step FLOW (login, signup, checkout): one screenshot does NOT prove it
+  works — write an e2e/integration test that DRIVES the flow (fill form → submit
+  → assert the post-success state), attach its test_output, AND screenshot the
+  end state. Never let a single static screenshot stand in for a flow.
+When the work is done: open ONE draft PR (git push +
 gh pr create --draft), call attach_pr, then call complete with a plain-language
 summary of what you built AND a criteria self-report (index into the brief's
 "done when" list + met true/false + a short note per item). That summary +
@@ -168,7 +176,7 @@ function seedPrompt(runId, brief, transcript, resumedInPlace) {
       ? [``, `Conversation so far (you may be resuming — pick up where this left off):`, transcript]
       : []),
     ``,
-    `${transcript ? 'Continue' : 'Begin'}. Post a short plan first as a Markdown list (one numbered line per step), then: report_progress as you go; attach_evidence for each "done when" criterion as you satisfy it (test output, a request/response, a data sample, or a screenshot — so it's reviewable without running anything); report_blocker + stop if you hit a human decision; open a draft PR, attach_pr, then complete (summary + criteria self-report — your delivery card) when done.`,
+    `${transcript ? 'Continue' : 'Begin'}. Post a short plan first as a Markdown list (one numbered line per step), then: report_progress as you go; attach_evidence for each "done when" criterion as you satisfy it — a real screenshot for UI (run the dev server, then \`flowviant shot <url> --out shot.png\`), or test output / a request-response / a data sample for backend, so it's reviewable without running anything; report_blocker + stop if you hit a human decision; open a draft PR, attach_pr, then complete (summary + criteria self-report — your delivery card) when done.`,
   ].join('\n');
 }
 

package/bin/lib/shot.mjs

@@ -0,0 +1,218 @@
+/**
+ * `flowviant shot <url>` — capture a headless-browser screenshot of a running
+ * page, so a build agent can attach REAL visual evidence to its delivery card
+ * (not just the ephemeral live preview). This is the primitive the daemon agent
+ * shells out to; it wraps the two fiddly parts — finding a browser across the
+ * user's environment, and driving Chrome's headless `--screenshot` — so the
+ * agent doesn't have to guess.
+ *
+ * Design mirrors the preview/cloudflared path: zero-config where possible, and
+ * NEVER a hard failure. No browser found / render crashes → a clear one-line
+ * hint on stderr + a non-zero exit, and the agent falls back to text evidence
+ * (test output, request/response, sample). It must never block a delivery.
+ *
+ * Environment coverage (the "what about WSL / a Linux VM?" cases):
+ *   - Linux: PATH + conventional install paths for chrome/chromium/edge/brave.
+ *   - macOS / Windows: the standard app locations.
+ *   - WSL with no Linux browser: falls back to Windows Chrome/Edge via /mnt/c
+ *     interop, translating paths with `wslpath` (WSL2 forwards localhost, so a
+ *     Windows browser can still reach the dev server running in WSL).
+ *   - A bare VM with no browser AND no system libs: probing/render fails →
+ *     graceful text-evidence fallback with an `apt install chromium` hint.
+ *   - FLOWVIANT_CHROME / CHROME_PATH override wins over all discovery.
+ */
+
+import { spawn, execFileSync } from 'node:child_process';
+import { existsSync, statSync, readFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir, platform } from 'node:os';
+
+// ── Browser discovery ───────────────────────────────────────────────────────
+
+const LINUX_BINS = [
+  'google-chrome-stable', 'google-chrome', 'chromium', 'chromium-browser',
+  'chrome', 'brave-browser', 'microsoft-edge', 'microsoft-edge-stable',
+];
+const LINUX_PATHS = [
+  '/usr/bin/google-chrome-stable', '/usr/bin/google-chrome', '/usr/bin/chromium',
+  '/usr/bin/chromium-browser', '/snap/bin/chromium', '/usr/bin/brave-browser',
+  '/usr/bin/microsoft-edge', '/usr/bin/microsoft-edge-stable',
+];
+const MAC_PATHS = [
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+];
+const WIN_PATHS = [
+  'C:/Program Files/Google/Chrome/Application/chrome.exe',
+  'C:/Program Files (x86)/Google/Chrome/Application/chrome.exe',
+  'C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe',
+  'C:/Program Files/Microsoft/Edge/Application/msedge.exe',
+];
+// WSL interop: the same Windows installs, seen through the /mnt/c mount.
+const WSL_WIN_PATHS = WIN_PATHS.map((p) => `/mnt/c/${p.slice(3)}`);
+
+function which(name) {
+  try {
+    const p = execFileSync('which', [name], { encoding: 'utf8' }).trim();
+    return p || null;
+  } catch {
+    return null;
+  }
+}
+
+function isWSL() {
+  if (process.env.WSL_DISTRO_NAME) return true;
+  try {
+    return /microsoft|wsl/i.test(readFileSync('/proc/version', 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+/** Locate a usable browser, or null. `viaWindows` means a Windows .exe reached
+ *  through WSL interop — its file-path args must be translated with wslpath. */
+export function resolveBrowser() {
+  const override = process.env.FLOWVIANT_CHROME || process.env.CHROME_PATH;
+  if (override && existsSync(override)) return { bin: override, viaWindows: false };
+
+  const os = platform();
+  if (os === 'darwin') {
+    for (const p of MAC_PATHS) if (existsSync(p)) return { bin: p, viaWindows: false };
+    return null;
+  }
+  if (os === 'win32') {
+    for (const p of WIN_PATHS) if (existsSync(p)) return { bin: p, viaWindows: false };
+    return null;
+  }
+  // linux
+  for (const name of LINUX_BINS) {
+    const p = which(name);
+    if (p) return { bin: p, viaWindows: false };
+  }
+  for (const p of LINUX_PATHS) if (existsSync(p)) return { bin: p, viaWindows: false };
+  // WSL with no Linux browser — reach the Windows one.
+  if (isWSL()) {
+    for (const p of WSL_WIN_PATHS) if (existsSync(p)) return { bin: p, viaWindows: true };
+  }
+  return null;
+}
+
+// ── Capture ─────────────────────────────────────────────────────────────────
+
+function toWinPath(p) {
+  return execFileSync('wslpath', ['-w', p], { encoding: 'utf8' }).trim();
+}
+
+function runChrome(browser, { url, out, width, height, headlessFlag, timeoutMs }) {
+  return new Promise((resolve) => {
+    const userDataDir = mkdtempSync(join(tmpdir(), 'flowviant-shot-'));
+    const cleanup = () => { try { rmSync(userDataDir, { recursive: true, force: true }); } catch { /* best effort */ } };
+
+    // A Windows .exe can't read a WSL path — translate the file args it touches.
+    let outArg = out;
+    let udArg = userDataDir;
+    if (browser.viaWindows) {
+      try {
+        outArg = toWinPath(out);
+        udArg = toWinPath(userDataDir);
+      } catch {
+        cleanup();
+        return resolve({ ok: false, reason: 'wslpath', message: 'wslpath unavailable — cannot use Windows Chrome from WSL.' });
+      }
+    }
+
+    const args = [
+      headlessFlag,
+      '--disable-gpu',
+      '--no-sandbox',            // required as root / in many VMs + containers
+      '--disable-dev-shm-usage', // small /dev/shm in containers/VMs crashes Chrome otherwise
+      '--hide-scrollbars',
+      '--force-color-profile=srgb',
+      `--user-data-dir=${udArg}`,
+      `--window-size=${width},${height}`,
+      '--virtual-time-budget=5000', // let fonts/JS settle before capture (SPAs)
+      `--screenshot=${outArg}`,
+      url,
+    ];
+
+    let err = '';
+    let child;
+    try {
+      child = spawn(browser.bin, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+    } catch (e) {
+      cleanup();
+      return resolve({ ok: false, reason: 'spawn', message: e.message });
+    }
+    child.stderr?.on('data', (d) => { err += d.toString(); });
+    const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ } }, timeoutMs);
+    child.on('error', (e) => {
+      clearTimeout(timer);
+      cleanup();
+      resolve({ ok: false, reason: 'spawn', message: e.message });
+    });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      cleanup();
+      if (existsSync(out) && statSync(out).size > 0) return resolve({ ok: true, path: out });
+      const tail = err.trim().split('\n').slice(-2).join(' ');
+      resolve({ ok: false, reason: 'render', message: `Chrome exited (code ${code}) without an image.${tail ? ' ' + tail : ''}` });
+    });
+  });
+}
+
+/** Capture `url` to a PNG at `out`. Tries new headless, then classic headless
+ *  (older Chromium). Resolves { ok, path } or { ok:false, reason, message }. */
+export async function captureScreenshot({ url, out, width = 1440, height = 900, timeoutMs = 60_000 }) {
+  const browser = resolveBrowser();
+  if (!browser) {
+    return {
+      ok: false,
+      reason: 'no-browser',
+      message: 'No Chrome/Chromium/Edge found. Install one (Linux: `sudo apt install chromium`) to capture screenshot evidence.',
+    };
+  }
+  let r = await runChrome(browser, { url, out, width, height, headlessFlag: '--headless=new', timeoutMs });
+  if (!r.ok && r.reason === 'render') {
+    // Older Chromium rejects `--headless=new` — retry with classic headless.
+    r = await runChrome(browser, { url, out, width, height, headlessFlag: '--headless', timeoutMs });
+  }
+  return r;
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────
+
+function getOpt(argv, name) {
+  const i = argv.indexOf(name);
+  return i >= 0 ? argv[i + 1] : undefined;
+}
+
+/** `flowviant shot <url> [--out file.png] [--width N] [--height N] [--base64]`
+ *  On success prints the PNG path (or its base64 with --base64) to stdout and
+ *  exits 0. On any failure: a hint on stderr, exit 1 (graceful — the agent then
+ *  attaches text evidence instead). Usage error exits 2. */
+export async function runShot(argv) {
+  const url = argv.find((a) => !a.startsWith('--') && /^(https?|file|data):/i.test(a));
+  if (!url) {
+    console.error('usage: flowviant shot <url> [--out file.png] [--width 1440] [--height 900] [--base64]');
+    console.error('  url: a running page (http://localhost:5173/…), a built file (file://…), or a data: URL');
+    process.exit(2);
+  }
+  const out = getOpt(argv, '--out') || join(process.cwd(), `flowviant-shot-${Date.now()}.png`);
+  const width = Number(getOpt(argv, '--width')) || 1440;
+  const height = Number(getOpt(argv, '--height')) || 900;
+  const wantBase64 = argv.includes('--base64');
+
+  const r = await captureScreenshot({ url, out, width, height });
+  if (!r.ok) {
+    console.error(`flowviant shot: ${r.message}`);
+    process.exit(1);
+  }
+  if (wantBase64) {
+    process.stdout.write(readFileSync(out).toString('base64'));
+  } else {
+    console.log(r.path);
+  }
+  process.exit(0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.28.9",
+  "version": "0.29.0",
   "description": "Run your own Claude Code as headless build agents for Flowviant — on your own credentials. Claims dispatched work, opens PRs, captures review evidence, and routes questions back to you.",
   "type": "module",
   "bin": {