flowviant 0.63.0 → 0.65.0

package/bin/lib/devResolve.mjs

@@ -1,167 +0,0 @@
-/**
- * WHAT STARTS THIS PROJECT — asked of a Claude, on the machine, in the
- * background.
- *
- * WHY THIS EXISTS. Starting a dev server used to require a command a human had
- * typed into a sheet, prefilled `npm run dev`. That prefill is a guess about
- * somebody else's stack, and it was called out as one: "the option to run or
- * start the dev server shouldnt be npm run dev or show it as npm run dev
- * because thats not agnostic to everyones set up. no need to show that."
- *
- * The mechanism is the driver's own: "we are literally asking a claude session
- * to start it for us" — and, decisively, "i still want claude to start the
- * server for me but i dont want it to literally open a chat. have it do it in
- * the background." So this is a headless turn. It reaches no transcript, spends
- * no tab, and leaves no message anybody has to read.
- *
- * IT ANSWERS WITH A STRING AND STARTS NOTHING. The server parses what comes
- * back, through the same `parseDevCommand` a human's answer goes through, and
- * hands the machine an ordinary start job on the next poll. That split is the
- * whole safety story: the policy for what may execute has exactly one
- * implementation, and it lives in the component this repo can actually upgrade.
- * A daemon that decided for itself what counted as a legal command would be a
- * second copy of that policy, free to drift, published, and unrecallable.
- *
- * IT MAY INSTALL. That is not a loophole in the install refusal — it is the
- * refusal's own stated remedy. `parseDevCommand` refuses `npm install` because
- * a SPAWNED command runs lifecycle scripts from the repo and every transitive
- * dependency with no agent in the loop; the file says the remedy is "a turn in
- * the tab: a human asking, an agent doing it". This is exactly that turn, with
- * the human asking by pressing the button. And it is the case that matters: a
- * fresh worktree has no `node_modules` (they are gitignored, so they never come
- * across with the branch), which is precisely the dead end that produced "it
- * was stuck on 'working', does it really take that long to run dev?"
- *
- * IT CLEANS UP AFTER ITSELF. A `-p` turn writes a transcript, and
- * `localSessions.mjs` offers the newest ended session per directory as
- * adoptable — left behind, every resolve would drop a phantom untitled session
- * into the `+` menu.
- */
-
-import { runTurn } from './claude.mjs';
-import { removeProbeTranscript } from './runtimes.mjs';
-
-/** Long, because an install can sit in front of the answer. The SERVER holds
- *  the real ceiling (`RESOLVE_TTL_MS`); this is the machine giving up first so
- *  a wedged child does not hold a slot until then. */
-export const DEV_RESOLVE_TIMEOUT_MS = 10 * 60_000;
-
-/** The sentinel for "I could not tell", so an honest failure is distinguishable
- *  from a model padding an answer it does not have. */
-export const NO_COMMAND = 'NONE';
-
-/**
- * The argv0s the server will accept. Named in the prompt NOT as a security
- * control — the server enforces it either way, and would refuse anything else
- * with the parser's own words — but because a model that knows the shape of an
- * acceptable answer gives one, and a refused proposal costs the asker a whole
- * round trip to learn nothing.
- */
-const ALLOWED = [
-  'npm', 'pnpm', 'yarn', 'bun', 'node', 'deno', 'go', 'python', 'python3',
-  'make', 'cargo', 'rails', 'php', 'dotnet',
-];
-
-export function resolvePrompt() {
-  return [
-    'Work out the ONE command that starts this project’s development server, and reply with only that command.',
-    '',
-    'How to work it out: read the repo. Check package.json scripts, Makefile, Procfile, docker-compose, pyproject.toml, Cargo.toml, README — whatever this project actually uses. Prefer the script the project itself documents for local development.',
-    '',
-    'You MAY install dependencies first if they are missing (for example a worktree with no node_modules). Do that before answering.',
-    '',
-    'Rules for the answer:',
-    `- It must begin with one of: ${ALLOWED.join(', ')} — or a ./path to a script in this repo.`,
-    '- One line. No shell operators (&&, |, ;, >, $, backticks). If the project needs several steps, name a script in the repo that does them.',
-    '- Not an install command. Install as part of your work above if needed; the answer is the command that RUNS the server.',
-    '- It must not daemonize or background itself. It should stay in the foreground; something else supervises it.',
-    `- If you genuinely cannot tell, reply exactly ${NO_COMMAND}.`,
-    '',
-    'Reply with the command alone — no explanation, no backticks, no prose.',
-  ].join('\n');
-}
-
-/**
- * Last plausible command line out of whatever the model said.
- *
- * DELIBERATELY FORGIVING, because the cost of being wrong is low and asymmetric:
- * the server parses this and refuses anything outside the policy, naming what
- * was proposed. Being strict here would turn a model that wrapped its answer in
- * backticks into a failure the asker cannot act on, having already paid for the
- * turn.
- */
-export function pickCommand(text) {
-  const lines = String(text ?? '')
-    .split('\n')
-    .map((l) => l.trim())
-    // Fence markers and bullet/quote decoration, which are formatting rather
-    // than part of anybody's command.
-    .filter((l) => l && !/^```/.test(l))
-    .map((l) => l.replace(/^[-*>\s]+/, '').replace(/^`+|`+$/g, '').trim())
-    .filter(Boolean);
-  if (lines.length === 0) return null;
-  // The LAST such line: a model that explains before complying puts the answer
-  // at the end, and one that complies exactly has only one line anyway.
-  const last = lines[lines.length - 1];
-  if (!last || last === NO_COMMAND) return null;
-  // A sentence is not a command. Cheap shape check so obvious prose becomes
-  // "could not work it out" rather than a refusal quoting a paragraph back.
-  if (last.split(/\s+/).length > 8 || /[.!?]$/.test(last)) return null;
-  return last;
-}
-
-/**
- * Run the turn. Resolves `{ command }` or `{ error }` — never throws, because
- * the caller's only job with a failure is to relay it, and an exception at this
- * boundary would strand the row.
- */
-export async function resolveDevCommandOnMachine({ cwd, model, log, onActivity }) {
-  let sessionId = null;
-  let timer;
-  try {
-    const out = await Promise.race([
-      runTurn({
-        prompt: resolvePrompt(),
-        cwd,
-        streamJson: true,
-        answerFromResult: true,
-        model,
-        label: 'dev',
-        /**
-         * THE TURN'S OWN HUMANIZED TAIL, forwarded so a browser can watch it.
-         *
-         * This is the only feature in the product where a Claude does work
-         * nobody can see — no transcript, by design — and the driver's answer
-         * to that is the right one: "we could have it stream the output for
-         * transparency on the menu." So the same `read …` / `+ npm install …`
-         * lines a tab relays are forwarded here. It is the CLI's own stdout
-         * humanized, never an inference about it, which is the standing rule
-         * for every activity readout in this product.
-         */
-        onActivity,
-        onInit: (i) => {
-          if (i?.sessionId) sessionId = i.sessionId;
-        },
-      }),
-      new Promise((r) => {
-        timer = setTimeout(() => r(null), DEV_RESOLVE_TIMEOUT_MS);
-        timer.unref?.();
-      }),
-    ]);
-    if (out === null) {
-      return { error: 'your Claude did not finish working out how to start this project in time.' };
-    }
-    const command = pickCommand(out);
-    if (!command) {
-      return { error: 'your Claude could not work out how to start this project.' };
-    }
-    log?.(`dev: resolved start command — ${command}`);
-    return { command };
-  } catch (e) {
-    return { error: `your Claude could not be run here: ${e?.message ?? 'unknown error'}` };
-  } finally {
-    clearTimeout(timer);
-    // After the turn, so the delete does not race a child still writing.
-    if (sessionId) setTimeout(() => removeProbeTranscript(cwd, sessionId), 750).unref?.();
-  }
-}

package/bin/lib/devServer.mjs

@@ -1,306 +0,0 @@
-/**
- * RUNNING THE PROJECT'S DEV COMMAND IN A TAB'S WORKTREE.
- *
- * THIS FILE MUST NEVER READ A REPO FILE TO DECIDE WHAT TO EXECUTE. That is the
- * one rule, and it is the whole difference between this and the live-preview
- * target deleted in 2026-08-21, whose obituary is in `preview.mjs`: that one
- * read a command out of `.flowviant/preview.json` — a file the BRANCH controls
- * — or inferred one from package.json, then `spawn(cmd, {shell: true})` with
- * `{...process.env}`, running `npm install` and its lifecycle scripts and
- * handing the resulting internet-exposed process the daemon's own credential.
- * One click behind a button and a hostile branch owned the machine.
- *
- * Here the argv arrives ON THE JOB, already parsed from a string a human
- * approved once for this project and stored server-side. The branch cannot
- * change it. This file re-validates the SHAPE at its own boundary — one place
- * doing a check is one deploy away from being zero places — and spawns with
- * `shell: false`.
- *
- * THE HONEST LIMIT, stated here rather than implied: pinning the command does
- * not pin what the command does. `npm run dev` dereferences to `scripts.dev`,
- * which the branch writes. What this buys is that a human chose the ENTRYPOINT
- * in the open, plus a child environment that is a strict subset of what the
- * agent's own `npm run dev` gets today. The child runs as the SAME UID as this
- * daemon and `~/.flowviant/credentials.json` is 0600 and readable by it. The
- * env allowlist is a control against ACCIDENT AND INHERITANCE — a crash
- * reporter, an error page that dumps `process.env`, a build log — and it is NOT
- * confinement. Nothing in the UI may say "sandboxed" or "isolated".
- *
- * NO PORT IS EVER SCRAPED. The deleted feature learned its port from the
- * child's stdout and tunnelled a guess when it found none. A scraped port has
- * no attribution behind it, and "this port was measured, by cwd, inside THIS
- * worktree" is the only real security control this feature family has. The port
- * here comes from `listenersIn` or it does not come at all — and a running
- * server with no measured port is a REAL state that gets a sentence.
- */
-
-import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
-import { childEnv } from './childEnv.mjs';
-import { mutateRegistry, processAlive, readRegistry } from './procRegistry.mjs';
-import { listenersIn } from './listeners.mjs';
-import { scrub } from './env.mjs';
-
-const FLOWVIANT_DIR = join(homedir(), '.flowviant');
-const REGISTRY = join(FLOWVIANT_DIR, 'devruns.json');
-const REGISTRY_LOCK = join(FLOWVIANT_DIR, 'devruns.lock');
-
-/** Output we keep. Only the tail is ever uplinked, and it is scrubbed on the
- *  way out: a dev server routinely prints connection strings. */
-const RING_BYTES = 512 * 1024;
-const TAIL_BYTES = 4096;
-/** How long we wait for the command to bind something inside the worktree
- *  before reporting it as running-but-unmeasured. */
-const BIND_WATCH_MS = 45_000;
-/** At most this many restarts inside the window, and only for a run that bound
- *  at least once — a server that never bound is a broken command, not a crash,
- *  and restarting it burns the box. */
-const MAX_RESTARTS = 3;
-const RESTART_WINDOW_MS = 10 * 60_000;
-const BACKOFF_MS = [2_000, 8_000, 30_000];
-const PACKAGE_MANAGERS = new Set(['npm', 'pnpm', 'yarn', 'bun']);
-
-const remember = (entry) =>
-  mutateRegistry(FLOWVIANT_DIR, REGISTRY, REGISTRY_LOCK, (list) => [
-    ...list.filter((e) => e.pid !== entry.pid),
-    entry,
-  ]);
-const forget = (pid) =>
-  mutateRegistry(FLOWVIANT_DIR, REGISTRY, REGISTRY_LOCK, (list) =>
-    list.filter((e) => e.pid !== pid)
-  );
-
-/** SIGTERM the GROUP, wait, then SIGKILL it. `npm run dev` spawns grandchildren
- *  that outlive a kill of the parent, which is what `detached: true` and the
- *  negative pid are for. */
-function killGroup(pid, graceMs = 8_000) {
-  const signal = (sig) => {
-    try {
-      process.kill(-pid, sig);
-    } catch {
-      try {
-        process.kill(pid, sig);
-      } catch {
-        /* already gone */
-      }
-    }
-  };
-  signal('SIGTERM');
-  setTimeout(() => {
-    if (processAlive(pid)) signal('SIGKILL');
-  }, graceMs).unref?.();
-}
-
-/**
- * THE FRESH-WORKTREE ANSWER, measured rather than discovered as a bug.
- *
- * `ensureWorktree` is a bare `git worktree add`, so a new tab has source and no
- * `node_modules`, and the first run there would fail with something unhelpful.
- * This is a measurement, and it routes dependency installation to the one place
- * that should own it: a turn in the tab, with a human asking and an audit row
- * for it. The button is never silently broken and the remedy is one sentence.
- */
-export function missingDeps(worktree, argv) {
-  if (!PACKAGE_MANAGERS.has(argv[0])) return false;
-  return !existsSync(join(worktree, 'node_modules'));
-}
-
-/**
- * Start the command and supervise it.
- *
- * `onState` is called with `{started, port, pid, error, endedReason, logTail,
- * restarts}` at each transition; the caller reports it upward. Resolves once
- * the first outcome is known — bound, or running-unmeasured, or failed — and
- * keeps supervising after that.
- */
-export function startDevServer({ sessionId, worktree, argv, log, onState, onExit }) {
-  if (missingDeps(worktree, argv)) {
-    return Promise.resolve({
-      ok: false,
-      endedReason: 'no_deps',
-      error:
-        "No dependencies are installed in this tab's worktree. Ask your Claude to install them, then run dev again.",
-    });
-  }
-
-  let ring = '';
-  let child = null;
-  let stopped = false;
-  let everBound = false;
-  let restarts = 0;
-  const restartTimes = [];
-
-  const append = (buf) => {
-    ring = (ring + buf.toString('utf8')).slice(-RING_BYTES);
-  };
-  const tail = () => scrub(ring.slice(-TAIL_BYTES));
-
-  const spawnOnce = () => {
-    child = spawn(argv[0], argv.slice(1), {
-      cwd: worktree,
-      env: childEnv({ cwd: worktree }),
-      // Its own process group, so the whole tree can be reaped. Load-bearing:
-      // a package manager is a wrapper and the server is its grandchild.
-      detached: true,
-      shell: false,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    // PERMANENT DRAIN LISTENERS, and this is not optional. A detached
-    // long-lived child on piped stdio with no reader BLOCKS ON WRITE once the
-    // pipe buffer fills, so a dev server would hang after a few minutes of HMR
-    // logs — the least diagnosable failure this feature could have.
-    child.stdout?.on('data', append);
-    child.stderr?.on('data', append);
-    return child;
-  };
-
-  return new Promise((resolve) => {
-    let settled = false;
-    const finish = (v) => {
-      if (settled) return;
-      settled = true;
-      resolve(v);
-    };
-
-    const attachExit = () => {
-      child.once('error', (e) => {
-        forget(child?.pid);
-        finish({ ok: false, endedReason: 'spawn_failed', error: String(e?.message || e) });
-      });
-      child.once('exit', (code, signal) => {
-        const pid = child?.pid;
-        forget(pid);
-        if (stopped) return;
-        // A command that NEVER bound is a broken command, not a crash. Restarting
-        // it would spin the box on somebody's typo.
-        const now = Date.now();
-        while (restartTimes.length && now - restartTimes[0] > RESTART_WINDOW_MS) restartTimes.shift();
-        if (everBound && restartTimes.length < MAX_RESTARTS) {
-          const delay = BACKOFF_MS[Math.min(restartTimes.length, BACKOFF_MS.length - 1)];
-          restartTimes.push(now);
-          restarts += 1;
-          log?.(`dev server exited (${signal || code}); restarting in ${delay / 1000}s`);
-          setTimeout(() => {
-            if (stopped) return;
-            spawnOnce();
-            attachExit();
-            remember(entryFor());
-            onState?.({ started: true, port: null, pid: child.pid, restarts, logTail: tail() });
-          }, delay).unref?.();
-          return;
-        }
-        onExit?.({
-          exitCode: typeof code === 'number' ? code : null,
-          signal: signal || null,
-          logTail: tail(),
-          endedReason: everBound ? 'crashed' : 'spawn_failed',
-          error: everBound
-            ? `the dev server exited (${signal || `code ${code}`})`
-            : `the command exited immediately (${signal || `code ${code}`}) without listening`,
-        });
-        finish({ ok: false, endedReason: everBound ? 'crashed' : 'spawn_failed' });
-      });
-    };
-
-    const entryFor = () => ({
-      sessionId,
-      pid: child.pid,
-      cwd: worktree,
-      startedAt: Date.now(),
-      owner: process.pid,
-    });
-
-    try {
-      spawnOnce();
-    } catch (e) {
-      finish({ ok: false, endedReason: 'spawn_failed', error: String(e?.message || e) });
-      return;
-    }
-    attachExit();
-    remember(entryFor());
-
-    // WATCH FOR THE BIND through `listenersIn` and nowhere else.
-    const deadline = Date.now() + BIND_WATCH_MS;
-    const poll = setInterval(() => {
-      if (stopped || !child || child.exitCode !== null) {
-        clearInterval(poll);
-        return;
-      }
-      const found = listenersIn(worktree)[0];
-      if (found) {
-        clearInterval(poll);
-        everBound = true;
-        onState?.({ started: true, port: found.port, pid: child.pid, restarts, logTail: tail() });
-        finish({ ok: true, port: found.port, pid: child.pid, stop, restarts });
-        return;
-      }
-      if (Date.now() > deadline) {
-        clearInterval(poll);
-        // RUNNING, NOTHING MEASURED. A real state and not a spinner: a
-        // `docker compose up` binds from inside a container whose cwd is not
-        // this worktree and will never be attributed.
-        onState?.({ started: true, port: null, pid: child.pid, restarts, logTail: tail() });
-        finish({ ok: true, port: null, pid: child.pid, stop, restarts });
-      }
-    }, 1000);
-    poll.unref?.();
-
-    function stop() {
-      stopped = true;
-      clearInterval(poll);
-      const pid = child?.pid;
-      if (pid) {
-        killGroup(pid);
-        forget(pid);
-      }
-    }
-  });
-}
-
-/**
- * What survived a daemon restart.
- *
- * IDENTITY IS NOT THE COMMAND STRING. `stillOurs` in `preview.mjs` matches a
- * substring of `/proc/<pid>/cmdline`, which cannot work here: `npm run dev` is
- * a human-authored string identical across two tabs, two worktrees, and the
- * driver's own hand-started server. Identity is the CWD — the same readlink
- * `listeners.mjs` already does — plus the pid still being alive. Both must
- * hold, and a could-not-measure is NOT a match and kills nothing.
- */
-export function adoptableDevRuns() {
-  const out = [];
-  for (const e of readRegistry(REGISTRY)) {
-    if (!e || typeof e.sessionId !== 'string' || !Number.isInteger(e.pid)) continue;
-    // Another LIVE daemon owns it — leave it alone entirely.
-    if (e.owner && e.owner !== process.pid && processAlive(e.owner)) continue;
-    if (!processAlive(e.pid)) continue;
-    out.push(e);
-  }
-  return out;
-}
-
-/** Kill a registry entry's process group and drop the row. Used when the
- *  session it belonged to is gone. */
-export function killDevRunEntry(entry) {
-  if (!entry || !Number.isInteger(entry.pid)) return;
-  killGroup(entry.pid);
-  forget(entry.pid);
-}
-
-/** Adopt or reap what the previous process left behind. `activeIds` is the set
- *  of sessions still live on the server; a run whose session is gone is killed,
- *  and one whose session survives is handed back to the caller to re-supervise. */
-export function reapOrphanDevRuns(activeIds, log) {
-  const adopt = [];
-  for (const e of adoptableDevRuns()) {
-    if (Array.isArray(activeIds) && !activeIds.includes(e.sessionId)) {
-      log?.(`dev server for a closed tab (pid ${e.pid}) — stopping it`);
-      killDevRunEntry(e);
-      continue;
-    }
-    adopt.push(e);
-  }
-  return adopt;
-}