flowviant 0.15.0 → 0.18.0

package/bin/cli.mjs

@@ -80,6 +80,9 @@ if (process.argv[2] === 'clean') {
   const { join } = await import('node:path');
   const { homedir } = await import('node:os');
   const { execFileSync } = await import('node:child_process');
+  // Also reap any preview dev-server/tunnel groups a crashed daemon left running.
+  const { reapOrphanPreviews } = await import('./lib/preview.mjs');
+  reapOrphanPreviews((m) => console.log(m));
   const dir = join(homedir(), '.flowviant', 'worktrees');
   if (!existsSync(dir)) {
     console.log('nothing to clean — no worktrees at ~/.flowviant/worktrees.');

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.15.0';
+export const VERSION = '0.18.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/fleet.mjs

@@ -47,6 +47,7 @@ import {
   SINGLE_RESUME,
 } from './claude.mjs';
 import { runLiveWorker } from './live.mjs';
+import { reapOrphanPreviews } from './preview.mjs';
 import { preflight } from './preflight.mjs';
 
 async function fetchRoster(haveIds) {
@@ -176,6 +177,9 @@ export async function runFleetDaemon() {
   info(`server · ${FLEET_URL}`);
   console.log('');
   await preflight({ needGit: true });
+  // Kill any preview dev-server/tunnel groups a previously-crashed daemon left
+  // running (detached children survive an ungraceful exit) before we start fresh.
+  reapOrphanPreviews((m) => info(m));
 
   // Persistent worktree home (0.9.0) — survives daemon restarts AND reboots,
   // so Ctrl+C mid-task never loses local work. Keyed per repo path; each
@@ -481,6 +485,8 @@ export async function runFleetDaemon() {
           label,
           cwd: wt,
           baseRef,
+          repoRoot, // for copying the repo's local env into the preview worktree
+
           getToken: (id) => tokenByAgent.get(id),
           getHasWork: (id) => hasWorkByAgent.get(id) ?? false,
           getMcpUrl: () => mcpUrl,

package/bin/lib/live.mjs

@@ -16,7 +16,7 @@
  * live fleet + repo to shake out. Old (poll/sentinel) mode is untouched.
  */
 
-import { readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { readFileSync, writeFileSync, rmSync, existsSync, copyFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import {
@@ -37,6 +37,13 @@ import { loadPreviewConfig, startPreview } from './preview.mjs';
 // Register a branch preview's tunnel URL with Flowviant (fleet-authed). The
 // reviewer then drives it via "Open live preview" in the node.
 const LIVE_TARGET_URL = FLEET_URL.replace(/\/agents\/?$/, '/live-target');
+// Short TTL + a heartbeat that re-asserts while the tunnel is alive. So a live
+// preview stays linked indefinitely (survives long reviews), but one whose
+// daemon DIED ungracefully (no more heartbeats) drops off the card within the
+// TTL instead of showing a dead URL for 2 hours. TTL comfortably covers a few
+// missed heartbeats.
+const PREVIEW_TTL_MINUTES = 6;
+const PREVIEW_HEARTBEAT_MS = 90_000;
 async function registerLiveTarget(intentId, kind, url) {
   try {
     await fetch(LIVE_TARGET_URL, {
@@ -47,7 +54,7 @@ async function registerLiveTarget(intentId, kind, url) {
         'Content-Type': 'application/json',
       },
       signal: AbortSignal.timeout(30_000),
-      body: JSON.stringify({ intentId, kind, url }),
+      body: JSON.stringify({ intentId, kind, url, ttlMinutes: PREVIEW_TTL_MINUTES }),
     });
   } catch {
     /* best-effort — the tunnel still works; it just isn't linked in the app */
@@ -71,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.
@@ -586,11 +610,39 @@ export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive, resume
 
 // Per-agent loop — same signature/scaffolding as runFleetWorker, but each task
 // is a persistent SDK session instead of a one-shot claude turn.
+// A preview runs in the agent's WORKTREE — a fresh checkout that lacks the repo's
+// gitignored env files (.env.local etc.), so the app's DB/auth secrets are absent
+// and anything that hits them (sign-in!) 500s. Copy the files the checkout is
+// missing from the real repo into the worktree so the preview runs like local
+// dev. We only copy files ABSENT from the worktree — i.e. the gitignored ones —
+// so nothing tracked is overwritten and (being gitignored) nothing gets committed.
+const PREVIEW_ENV_FILES = ['.env', '.env.local', '.env.development', '.env.development.local'];
+function copyLocalEnvFiles(repoRoot, worktree, log) {
+  if (!repoRoot || repoRoot === worktree) return;
+  let copied = 0;
+  for (const f of PREVIEW_ENV_FILES) {
+    const src = join(repoRoot, f);
+    const dst = join(worktree, f);
+    if (existsSync(src) && !existsSync(dst)) {
+      try {
+        copyFileSync(src, dst);
+        copied++;
+      } catch {
+        /* best-effort */
+      }
+    }
+  }
+  if (copied) {
+    log?.(`preview: brought ${copied} local env file(s) into the worktree so the app has its secrets.`);
+  }
+}
+
 export async function runLiveWorker({
   agentId,
   label,
   cwd,
   baseRef,
+  repoRoot,
   getToken,
   getHasWork,
   getMcpUrl,
@@ -615,8 +667,16 @@ export async function runLiveWorker({
   // kept up while it's in review (a gated agent parks, so it lives until review
   // resolves). Replaced when the next task finishes; torn down on shutdown.
   let preview = null;
-  let previewTarget = null; // { intentId, kind } of the currently-registered link
+  let previewTarget = null; // { intentId, kind, url } of the currently-registered link
+  let previewHeartbeat = null;
+  const stopHeartbeat = () => {
+    if (previewHeartbeat) {
+      clearInterval(previewHeartbeat);
+      previewHeartbeat = null;
+    }
+  };
   const stopPreview = () => {
+    stopHeartbeat();
     if (preview) {
       try {
         preview.stop();
@@ -650,6 +710,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
@@ -657,7 +723,11 @@ export async function runLiveWorker({
     if (cfg.dir && cfg.dir !== '.') {
       info(`${label} ${c.dim(`live preview: detected a frontend at ${cfg.dir}/ (port ${entry.port})`)}`);
     }
+    // Give the dev server the repo's local env (gitignored secrets the fresh
+    // 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,
@@ -665,12 +735,40 @@ 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);
-      previewTarget = { intentId, kind }; // so teardown can drop the link
+      previewTarget = { intentId, kind, url: preview.url }; // teardown drops it; heartbeat re-asserts it
+      // Re-assert the link while the tunnel is alive so it survives long reviews
+      // (and a dead daemon stops re-asserting → the record expires by itself).
+      stopHeartbeat();
+      previewHeartbeat = setInterval(() => {
+        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 ────────────────────
 
@@ -212,6 +216,74 @@ const TUNNEL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i;
 // Where a dev server announces it bound — "Local: http://localhost:3001/".
 const BIND_RE = /https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0):(\d+)/i;
 
+// ── Orphan reaping ─────────────────────────────────────────────────────────
+// Preview children (dev server + tunnel) are detached so we can kill the whole
+// group — but that also means they SURVIVE an ungraceful daemon death (SIGKILL,
+// crash, box sleep), leaking ports/memory. We record each spawned group's pid +
+// a signature; on the next daemon start we reap any that are still ours.
+const PREVIEW_REGISTRY = join(homedir(), '.flowviant', 'previews.json');
+function readRegistry() {
+  try {
+    const v = JSON.parse(readFileSync(PREVIEW_REGISTRY, 'utf8'));
+    return Array.isArray(v) ? v : [];
+  } catch {
+    return [];
+  }
+}
+function writeRegistry(list) {
+  try {
+    mkdirSync(join(homedir(), '.flowviant'), { recursive: true });
+    writeFileSync(PREVIEW_REGISTRY, JSON.stringify(list));
+  } catch {
+    /* best-effort */
+  }
+}
+function recordPreviewPid(pid, sig) {
+  if (!pid) return;
+  writeRegistry([...readRegistry(), { pid, sig }]);
+}
+function forgetPreviewPid(pid) {
+  if (!pid) return;
+  writeRegistry(readRegistry().filter((e) => e.pid !== pid));
+}
+// Only kill a pid we can VERIFY is still one of ours — its /proc cmdline must
+// still contain the signature we stored. A reused pid (belonging to something
+// unrelated) won't match, so we never kill a stranger. Linux-only (that's where
+// /proc + process groups work); elsewhere we just clear the registry.
+function stillOurs(pid, sig) {
+  if (platform() !== 'linux') return false;
+  try {
+    const cmd = readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ');
+    return typeof sig === 'string' && sig.length > 0 && cmd.includes(sig);
+  } catch {
+    return false; // process gone / unreadable
+  }
+}
+
+/** Reap preview process groups left behind by a previously-crashed daemon.
+ *  Call once at daemon startup, before spawning workers. */
+export function reapOrphanPreviews(log) {
+  const list = readRegistry();
+  if (list.length === 0) return;
+  let killed = 0;
+  for (const { pid, sig } of list) {
+    if (!stillOurs(pid, sig)) continue;
+    try {
+      process.kill(-pid, 'SIGKILL'); // whole group
+      killed++;
+    } catch {
+      try {
+        process.kill(pid, 'SIGKILL');
+        killed++;
+      } catch {
+        /* already gone */
+      }
+    }
+  }
+  writeRegistry([]);
+  if (killed) log?.(`reaped ${killed} orphaned preview process${killed === 1 ? '' : 'es'} from a previous run.`);
+}
+
 /**
  * Start the dev server + tunnel for one worktree. Resolves { url, kind, stop }
  * once the tunnel URL is captured, or null if it can't come up. stop() kills
@@ -229,6 +301,7 @@ export async function startPreview({
   port,
   env: extraEnv,
   hostHeader,
+  auth,
   log,
   timeoutMs = 180_000,
 }) {
@@ -264,10 +337,14 @@ export async function startPreview({
       stdio: ['ignore', 'pipe', 'pipe'],
       env,
     });
+    // Track for orphan reaping: the shell's cmdline stays `sh -c <cmd>`, so `cmd`
+    // is a safe signature to re-verify against later.
+    recordPreviewPid(server.pid, cmd);
 
     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) => {
@@ -283,6 +360,13 @@ export async function startPreview({
       }
     };
     const stop = () => {
+      forgetPreviewPid(server.pid);
+      forgetPreviewPid(tunnel?.pid);
+      try {
+        authProxy?.stop();
+      } catch {
+        /* already closed */
+      }
       killGroup(server);
       killGroup(tunnel);
     };
@@ -297,21 +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);
@@ -324,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);
@@ -343,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.15.0",
+  "version": "0.18.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": {