flowviant 0.17.0 → 0.19.0

package/bin/lib/authproxy.mjs

@@ -0,0 +1,95 @@
+/**
+ * Opt-in basic-auth reverse proxy for previews (`.flowviant/preview.json`
+ * "auth": true). The public tunnel is otherwise a capability URL — anyone with
+ * it reaches the running app. This gates it: cloudflared → this proxy → dev
+ * server, with a generated password the app surfaces to the reviewer.
+ *
+ * Minimal + dependency-free: forwards HTTP, and pipes WS upgrades (HMR) — the
+ * browser re-sends the cached Basic-auth header on same-origin upgrades, so HMR
+ * still authenticates. If a proxy request fails the page just 502s; it never
+ * touches the default (no-auth) preview path.
+ */
+
+import { createServer, request } from 'node:http';
+import { randomBytes } from 'node:crypto';
+
+/** Start the proxy in front of a dev server on `targetPort`. Resolves
+ *  { port, user, password, stop }. Binds loopback only (cloudflared connects
+ *  locally); the password is what gates the public tunnel. */
+export function startAuthProxy({ targetPort, log }) {
+  const user = 'preview';
+  const password = randomBytes(9).toString('base64url'); // ~12 url-safe chars
+  const expected = 'Basic ' + Buffer.from(`${user}:${password}`).toString('base64');
+  const authed = (req) => req.headers['authorization'] === expected;
+
+  const forwardOpts = (req) => ({
+    host: '127.0.0.1',
+    port: targetPort,
+    method: req.method,
+    path: req.url,
+    headers: req.headers,
+  });
+
+  const server = createServer((req, res) => {
+    if (!authed(req)) {
+      res.writeHead(401, {
+        'WWW-Authenticate': 'Basic realm="Flowviant preview"',
+        'Content-Type': 'text/plain',
+      });
+      res.end('This preview is password-protected. Enter the password shown in Flowviant.');
+      return;
+    }
+    const proxyReq = request(forwardOpts(req), (proxyRes) => {
+      res.writeHead(proxyRes.statusCode || 502, proxyRes.headers);
+      proxyRes.pipe(res);
+    });
+    proxyReq.on('error', () => {
+      if (!res.headersSent) res.writeHead(502, { 'Content-Type': 'text/plain' });
+      res.end('preview origin not reachable');
+    });
+    req.pipe(proxyReq);
+  });
+
+  // WS upgrade (HMR). The browser resends the Basic-auth header on same-origin
+  // upgrades, so we can gate it too, then pipe the two sockets together.
+  server.on('upgrade', (req, socket, head) => {
+    if (!authed(req)) {
+      socket.write('HTTP/1.1 401 Unauthorized\r\nWWW-Authenticate: Basic realm="Flowviant preview"\r\n\r\n');
+      socket.destroy();
+      return;
+    }
+    const proxyReq = request(forwardOpts(req));
+    proxyReq.on('upgrade', (proxyRes, proxySocket, proxyHead) => {
+      const headerLines = Object.entries(proxyRes.headers).map(([k, v]) => `${k}: ${v}`);
+      socket.write(`HTTP/1.1 101 Switching Protocols\r\n${headerLines.join('\r\n')}\r\n\r\n`);
+      if (proxyHead && proxyHead.length) proxySocket.unshift(proxyHead);
+      proxySocket.pipe(socket);
+      socket.pipe(proxySocket);
+      proxySocket.on('error', () => socket.destroy());
+      socket.on('error', () => proxySocket.destroy());
+    });
+    proxyReq.on('error', () => socket.destroy());
+    if (head && head.length) proxyReq.write(head);
+    proxyReq.end();
+  });
+
+  return new Promise((resolve) => {
+    server.on('error', () => resolve(null)); // couldn't bind → caller falls back to no proxy
+    server.listen(0, '127.0.0.1', () => {
+      const port = server.address().port;
+      log?.(`auth proxy on :${port} — preview is password-gated`);
+      resolve({
+        port,
+        user,
+        password,
+        stop: () => {
+          try {
+            server.close();
+          } catch {
+            /* already closed */
+          }
+        },
+      });
+    });
+  });
+}

package/bin/lib/config.mjs

@@ -4,7 +4,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 
-export const VERSION = '0.17.0';
+export const VERSION = '0.19.0';
 
 // Credential stored by `flowviant login` (device auth) — the no-token,
 // no-env-var path. An explicit --fleet flag or FLOWVIANT_FLEET env still wins.

package/bin/lib/live.mjs

@@ -78,6 +78,23 @@ function clearLiveTarget(intentId, kind) {
   }).catch(() => {});
 }
 
+// Report WHY a preview didn't come up into the task thread, so the reason is
+// visible in the app (not just the daemon console). The card grace-window shows
+// "starting…"; this is the honest terminal state when it can't.
+const PREVIEW_NOTE_URL = FLEET_URL.replace(/\/agents\/?$/, '/preview-note');
+function postPreviewNote(intentId, text) {
+  return fetch(PREVIEW_NOTE_URL, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${FLEET_TOKEN}`,
+      'User-Agent': USER_AGENT,
+      'Content-Type': 'application/json',
+    },
+    signal: AbortSignal.timeout(10_000),
+    body: JSON.stringify({ intentId, text }),
+  }).catch(() => {});
+}
+
 // Safe mode's curated toolset. Bash is scoped to the specific CLIs the agent
 // needs (git/gh/npm/bun) — NOT bare `Bash`, which would auto-approve arbitrary
 // shell (rm -rf, curl|sh, reading ~/.ssh) and defeat the point of safe mode.
@@ -108,7 +125,16 @@ answered…" or teammate line as a new instruction and adapt. There is NO termin
 and NO interactive prompt — your only channel to a human is the flowviant MCP
 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. When the work is done: open ONE draft PR (git push +
+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 +
 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 +
@@ -133,7 +159,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; 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 (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.`,
   ].join('\n');
 }
 
@@ -693,6 +719,12 @@ export async function runLiveWorker({
           'no live preview: no runnable web frontend found (searched the repo root, web/frontend/client/…, and apps/* + packages/*). If your app is elsewhere or not vite/next/astro/etc., add .flowviant/preview.json: {"ui":{"cmd":"cd <dir> && npm install && npm run dev","port":5173}}.'
         )}`
       );
+      if (intentId) {
+        await postPreviewNote(
+          intentId,
+          'No live preview: no runnable web frontend found (searched the repo root, common frontend dirs, and apps/* + packages/*). If this task has a web app, add a `.flowviant/preview.json` pointing at it.',
+        );
+      }
       return;
     }
     // Zero-config win: when we found the app in a subdir, say where, so it's
@@ -704,6 +736,7 @@ export async function runLiveWorker({
     // worktree is missing) so DB/auth-backed paths like sign-in don't 500.
     copyLocalEnvFiles(repoRoot, cwd, (m) => info(`${label} ${c.dim(m)}`));
     info(`${label} ${c.dim('starting a live preview of the branch for review…')}`);
+    let lastPreviewLog = ''; // captured so a failure's reason reaches the app
     preview = await startPreview({
       worktree: cwd,
       kind,
@@ -711,8 +744,21 @@ export async function runLiveWorker({
       port: entry.port,
       env: entry.env, // optional: extra env from .flowviant/preview.json
       hostHeader: entry.hostHeader, // optional: override/disable the Host rewrite
-      log: (m) => info(`${label} ${c.dim(m)}`),
+      auth: entry.auth === true, // optional: password-gate the public tunnel
+      log: (m) => {
+        lastPreviewLog = m;
+        info(`${label} ${c.dim(m)}`);
+      },
     });
+    if (!preview) {
+      // Dev server crashed on boot / tunnel never came up — surface the reason
+      // (the last log line is the specific failure) in the thread, not just the
+      // console, so the reviewer isn't left guessing.
+      await postPreviewNote(
+        intentId,
+        `Live preview didn't start — ${lastPreviewLog || 'the dev server did not come up'}. (Full output is in the daemon console.)`,
+      );
+    }
     if (preview) {
       onPreview?.(stopPreview); // hand the daemon a stop handle for shutdown
       await registerLiveTarget(intentId, kind, preview.url);
@@ -724,6 +770,14 @@ export async function runLiveWorker({
         if (previewTarget) void registerLiveTarget(previewTarget.intentId, previewTarget.kind, previewTarget.url);
       }, PREVIEW_HEARTBEAT_MS);
       previewHeartbeat.unref?.();
+      // Auth on: post the password into the thread so the reviewer can enter it
+      // at the browser prompt (the tunnel is otherwise a capability URL).
+      if (preview.auth && intentId) {
+        await postPreviewNote(
+          intentId,
+          `🔒 This live preview is password-protected. At the browser prompt, sign in with user \`${preview.auth.user}\` and password \`${preview.auth.password}\`.`,
+        );
+      }
       ok(`${label} ${c.dim('live preview ready — open the node to drive it in your review')}`);
     }
   };

package/bin/lib/preview.mjs

@@ -17,9 +17,12 @@
  *       "cmd": "<start dev server>",   // required
  *       "port": 5173,                  // required
  *       "env": { "FOO": "bar" },       // optional — extra env for the dev server
- *       "hostHeader": "localhost"      // optional — Host sent to the origin;
+ *       "hostHeader": "localhost",     // optional — Host sent to the origin;
  *                                      //   false disables the rewrite (for apps
  *                                      //   that need their real public Host)
+ *       "auth": true                   // optional — gate the public tunnel
+ *                                      //   behind a generated password (shown
+ *                                      //   in the app); off by default
  *     },
  *     "api": { "cmd": "<start api>", "port": 8787 } }
  */
@@ -28,6 +31,7 @@ import { spawn, execFileSync } from 'node:child_process';
 import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync, readdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir, platform, arch } from 'node:os';
+import { startAuthProxy } from './authproxy.mjs';
 
 // ── Config: explicit file, else infer from package.json ────────────────────
 
@@ -297,6 +301,7 @@ export async function startPreview({
   port,
   env: extraEnv,
   hostHeader,
+  auth,
   log,
   timeoutMs = 180_000,
 }) {
@@ -339,6 +344,7 @@ export async function startPreview({
     let settled = false;
     let tunnel = null;
     let tunnelStarted = false;
+    let authProxy = null; // opt-in basic-auth proxy in front of the dev server
     let out = '';
     const tail = () => out.trim().split('\n').slice(-15).join('\n');
     const killGroup = (child) => {
@@ -356,6 +362,11 @@ export async function startPreview({
     const stop = () => {
       forgetPreviewPid(server.pid);
       forgetPreviewPid(tunnel?.pid);
+      try {
+        authProxy?.stop();
+      } catch {
+        /* already closed */
+      }
       killGroup(server);
       killGroup(tunnel);
     };
@@ -370,22 +381,40 @@ export async function startPreview({
       resolve(val);
     };
 
-    // Open the tunnel once we know the real port (detected or fallback).
-    const openTunnel = (p) => {
+    // Open the tunnel once we know the real port (detected or fallback). When
+    // auth is opted in, put the password proxy in front and tunnel to THAT.
+    const openTunnel = async (p) => {
       if (tunnelStarted || settled) return;
       tunnelStarted = true;
       clearTimeout(bindTimer);
+      let tunnelPort = p;
+      if (auth) {
+        authProxy = await startAuthProxy({ targetPort: p, log });
+        if (settled) {
+          authProxy?.stop(); // torn down while the proxy was coming up — don't leak it
+          return;
+        }
+        if (authProxy) tunnelPort = authProxy.port;
+        else log?.('auth proxy failed to start — tunneling WITHOUT a password.');
+      }
       log?.(`preview: dev server on :${p} — opening the tunnel…`);
       // --http-host-header: send the origin the Host it expects (default
       // localhost — see hostRewrite above). Passes Vite/webpack/Next host checks
       // with zero repo config; skipped when preview.json sets hostHeader:false.
-      const args = ['tunnel', '--url', `http://localhost:${p}`];
+      const args = ['tunnel', '--url', `http://localhost:${tunnelPort}`];
       if (hostRewrite) args.push('--http-host-header', hostRewrite);
       tunnel = spawn(cf, args, { detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
       recordPreviewPid(tunnel.pid, 'cloudflared'); // signature for orphan reaping
       const onTunnel = (d) => {
         const m = TUNNEL_RE.exec(d.toString());
-        if (m) finish({ url: m[0], kind, stop });
+        if (m) {
+          finish({
+            url: m[0],
+            kind,
+            stop,
+            auth: authProxy ? { user: authProxy.user, password: authProxy.password } : undefined,
+          });
+        }
       };
       tunnel.stdout.on('data', onTunnel);
       tunnel.stderr.on('data', onTunnel);
@@ -398,7 +427,7 @@ export async function startPreview({
       out = (out + s).slice(-4000);
       if (!tunnelStarted) {
         const m = BIND_RE.exec(s);
-        if (m) openTunnel(Number(m[1]));
+        if (m) void openTunnel(Number(m[1]));
       }
     };
     server.stdout.on('data', onServer);
@@ -417,7 +446,7 @@ export async function startPreview({
 
     // If the server never prints a URL we recognize (quiet server), tunnel to the
     // configured port as a last resort.
-    bindTimer = setTimeout(() => openTunnel(port), 30_000);
+    bindTimer = setTimeout(() => void openTunnel(port), 30_000);
     timer = setTimeout(() => {
       log?.(
         `preview tunnel did not come up in ${Math.round(timeoutMs / 1000)}s — skipping.${

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.17.0",
+  "version": "0.19.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": {