@flumecode/runner 0.22.0 → 0.23.0

package/dist/cli.js

@@ -1,4 +1,652 @@
 #!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/version.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { fileURLToPath } from "node:url";
+function readVersion() {
+  try {
+    const path = fileURLToPath(new URL("../package.json", import.meta.url));
+    const pkg = JSON.parse(readFileSync2(path, "utf8"));
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function compareVersions(a, b) {
+  const parse = (v) => (v.split("-")[0] ?? v).split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const pa = parse(a);
+  const pb = parse(b);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+var RUNNER_VERSION, RUNNER_VERSION_HEADER, RUNNER_MIN_VERSION_HEADER, RUNNER_LATEST_VERSION_HEADER;
+var init_version = __esm({
+  "src/version.ts"() {
+    "use strict";
+    RUNNER_VERSION = readVersion();
+    RUNNER_VERSION_HEADER = "x-flumecode-runner-version";
+    RUNNER_MIN_VERSION_HEADER = "x-flumecode-min-runner-version";
+    RUNNER_LATEST_VERSION_HEADER = "x-flumecode-latest-runner-version";
+  }
+});
+
+// src/tui-api.ts
+function authHeaders(cfg) {
+  return {
+    Authorization: `Bearer ${cfg.apiToken ?? ""}`,
+    "x-flumecode-runner-version": RUNNER_VERSION
+  };
+}
+async function safeText2(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "";
+  }
+}
+async function get(cfg, path) {
+  const res = await fetch(cfg.serverUrl + path, { headers: authHeaders(cfg) });
+  if (!res.ok) throw new Error(await safeText2(res));
+  return res.json();
+}
+async function post(cfg, path, body) {
+  const res = await fetch(cfg.serverUrl + path, {
+    method: "POST",
+    headers: { ...authHeaders(cfg), "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) throw new Error(await safeText2(res));
+  return res.json();
+}
+var listRepositories, listAgents, listRequests, getRequest, createRequest, answerWidgets, acceptPlan, startImplementing, listJobs, listRunners;
+var init_tui_api = __esm({
+  "src/tui-api.ts"() {
+    "use strict";
+    init_version();
+    listRepositories = (cfg) => get(cfg, "/api/cli/repositories").then((r) => r.repositories);
+    listAgents = (cfg) => get(cfg, "/api/cli/agents").then((r) => r.agents);
+    listRequests = (cfg, repoId) => get(cfg, `/api/cli/repositories/${repoId}/requests`).then(
+      (r) => r.requests
+    );
+    getRequest = (cfg, id) => get(cfg, `/api/cli/requests/${id}`);
+    createRequest = (cfg, input) => post(cfg, "/api/cli/requests", input);
+    answerWidgets = (cfg, messageId, payload) => post(cfg, `/api/cli/messages/${messageId}/answer`, payload);
+    acceptPlan = (cfg, messageId, target, mergeBranch) => post(cfg, `/api/cli/plans/${messageId}/accept`, { target, mergeBranch });
+    startImplementing = (cfg, sessionId) => post(cfg, `/api/cli/sessions/${sessionId}/implement`, {});
+    listJobs = (cfg) => get(cfg, "/api/cli/jobs").then((r) => r.jobs);
+    listRunners = (cfg) => get(cfg, "/api/cli/runners").then((r) => r.runners);
+  }
+});
+
+// src/tui/usePoll.ts
+import { useState, useEffect, useRef } from "react";
+function usePoll(fetcher, intervalMs) {
+  const [data, setData] = useState(null);
+  const fetcherRef = useRef(fetcher);
+  fetcherRef.current = fetcher;
+  useEffect(() => {
+    let cancelled = false;
+    function poll() {
+      fetcherRef.current().then((result) => {
+        if (!cancelled) setData(result);
+      }).catch(() => {
+      });
+    }
+    poll();
+    const id = setInterval(poll, intervalMs);
+    return () => {
+      cancelled = true;
+      clearInterval(id);
+    };
+  }, [intervalMs]);
+  return data;
+}
+var init_usePoll = __esm({
+  "src/tui/usePoll.ts"() {
+    "use strict";
+  }
+});
+
+// src/tui/StatusBar.tsx
+import { Box, Text } from "ink";
+import { jsx, jsxs } from "react/jsx-runtime";
+function StatusBar({ jobs, runners }) {
+  const runningJobs = jobs?.filter((j) => j.status === "running").length ?? 0;
+  const onlineRunners = runners?.filter((r) => r.status === "online").length ?? 0;
+  return /* @__PURE__ */ jsx(Box, { borderStyle: "single", paddingX: 1, children: /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
+    "Jobs running: ",
+    runningJobs,
+    " | Runners online: ",
+    onlineRunners
+  ] }) });
+}
+var init_StatusBar = __esm({
+  "src/tui/StatusBar.tsx"() {
+    "use strict";
+  }
+});
+
+// src/tui/RepoListScreen.tsx
+import { useState as useState2 } from "react";
+import { Box as Box2, Text as Text2, useInput } from "ink";
+import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+function RepoListScreen({ config, onSelect }) {
+  const repos = usePoll(() => listRepositories(config), 1e4);
+  const [cursor, setCursor] = useState2(0);
+  useInput((input, key) => {
+    if (!repos) return;
+    if (key.upArrow) setCursor((c) => Math.max(0, c - 1));
+    else if (key.downArrow) setCursor((c) => Math.min(repos.length - 1, c + 1));
+    else if (key.return) {
+      const repo = repos[cursor];
+      if (repo) onSelect(repo);
+    }
+  });
+  if (!repos) return /* @__PURE__ */ jsx2(Text2, { children: "Loading repositories\u2026" });
+  if (repos.length === 0) return /* @__PURE__ */ jsx2(Text2, { children: "No repositories found." });
+  return /* @__PURE__ */ jsxs2(Box2, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsx2(Text2, { bold: true, children: "Select a repository (\u2191\u2193 Enter):" }),
+    repos.map((repo, i) => /* @__PURE__ */ jsxs2(Text2, { color: i === cursor ? "cyan" : void 0, children: [
+      i === cursor ? "\u25B6 " : "  ",
+      repo.fullName
+    ] }, repo.id))
+  ] });
+}
+var init_RepoListScreen = __esm({
+  "src/tui/RepoListScreen.tsx"() {
+    "use strict";
+    init_usePoll();
+    init_tui_api();
+  }
+});
+
+// src/tui/RequestListScreen.tsx
+import { useState as useState3 } from "react";
+import { Box as Box3, Text as Text3, useInput as useInput2 } from "ink";
+import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+function RequestListScreen({ config, repo, onOpen, onNew, onBack }) {
+  const requests = usePoll(() => listRequests(config, repo.id), 5e3);
+  const [cursor, setCursor] = useState3(0);
+  useInput2((input, key) => {
+    if (key.escape) {
+      onBack();
+      return;
+    }
+    if (!requests) return;
+    if (key.upArrow) setCursor((c) => Math.max(0, c - 1));
+    else if (key.downArrow) setCursor((c) => Math.min(requests.length - 1, c + 1));
+    else if (key.return) {
+      const req = requests[cursor];
+      if (req) onOpen(req);
+    } else if (input === "n") {
+      onNew();
+    }
+  });
+  if (!requests) return /* @__PURE__ */ jsx3(Text3, { children: "Loading requests\u2026" });
+  return /* @__PURE__ */ jsxs3(Box3, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsxs3(Text3, { bold: true, children: [
+      repo.fullName,
+      " \u2014 Requests (\u2191\u2193 Enter open, n new, Esc back):"
+    ] }),
+    requests.length === 0 && /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: "No requests yet." }),
+    requests.map((req, i) => /* @__PURE__ */ jsxs3(Text3, { color: i === cursor ? "cyan" : void 0, children: [
+      i === cursor ? "\u25B6 " : "  ",
+      "[",
+      req.status,
+      "] ",
+      req.title
+    ] }, req.id))
+  ] });
+}
+var init_RequestListScreen = __esm({
+  "src/tui/RequestListScreen.tsx"() {
+    "use strict";
+    init_usePoll();
+    init_tui_api();
+  }
+});
+
+// src/tui/NewRequestScreen.tsx
+import { useState as useState4 } from "react";
+import { Box as Box4, Text as Text4, useInput as useInput3 } from "ink";
+import TextInput from "ink-text-input";
+import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
+function NewRequestScreen({ config, repo, onCreated, onBack }) {
+  const agents = usePoll(() => listAgents(config), 3e4);
+  const [field, setField] = useState4("title");
+  const [title, setTitle] = useState4("");
+  const [body, setBody] = useState4("");
+  const [agentCursor, setAgentCursor] = useState4(0);
+  const [branch, setBranch] = useState4("");
+  const [error, setError] = useState4(null);
+  const [submitting, setSubmitting] = useState4(false);
+  useInput3((_input, key) => {
+    if (key.escape) {
+      onBack();
+      return;
+    }
+    if (field === "title" && key.tab) {
+      setField("body");
+      return;
+    }
+    if (field === "body" && key.tab) {
+      setField("agent");
+      return;
+    }
+    if (field === "agent") {
+      if (key.upArrow && agents) setAgentCursor((c) => Math.max(0, c - 1));
+      if (key.downArrow && agents) setAgentCursor((c) => Math.min((agents.length || 1) - 1, c + 1));
+      if (key.tab) setField("branch");
+    }
+    if (field === "branch" && key.return && !submitting) {
+      void submit();
+    }
+  });
+  async function submit() {
+    if (!title.trim() || !agents?.[agentCursor]) return;
+    setSubmitting(true);
+    setError(null);
+    try {
+      const result = await createRequest(config, {
+        title: title.trim(),
+        body: body.trim(),
+        agentId: agents[agentCursor].id,
+        repoId: repo.id,
+        checkoutBranch: branch.trim() || void 0
+      });
+      onCreated(result.requestId);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Unknown error");
+      setSubmitting(false);
+    }
+  }
+  return /* @__PURE__ */ jsxs4(Box4, { flexDirection: "column", gap: 1, children: [
+    /* @__PURE__ */ jsxs4(Text4, { bold: true, children: [
+      "New Request in ",
+      repo.fullName,
+      " (Tab to advance, Esc back)"
+    ] }),
+    /* @__PURE__ */ jsxs4(Box4, { children: [
+      /* @__PURE__ */ jsx4(Text4, { children: "Title: " }),
+      /* @__PURE__ */ jsx4(TextInput, { value: title, onChange: setTitle, focus: field === "title" })
+    ] }),
+    /* @__PURE__ */ jsxs4(Box4, { children: [
+      /* @__PURE__ */ jsx4(Text4, { children: "Body: " }),
+      /* @__PURE__ */ jsx4(TextInput, { value: body, onChange: setBody, focus: field === "body" })
+    ] }),
+    /* @__PURE__ */ jsxs4(Box4, { flexDirection: "column", children: [
+      /* @__PURE__ */ jsxs4(Text4, { children: [
+        "Agent",
+        field === "agent" ? " (\u2191\u2193 to pick, Tab next)" : "",
+        ":"
+      ] }),
+      (agents ?? []).map((a, i) => /* @__PURE__ */ jsxs4(Text4, { color: field === "agent" && i === agentCursor ? "cyan" : void 0, children: [
+        field === "agent" && i === agentCursor ? "\u25B6 " : "  ",
+        a.name
+      ] }, a.id))
+    ] }),
+    /* @__PURE__ */ jsxs4(Box4, { children: [
+      /* @__PURE__ */ jsx4(Text4, { children: "Checkout branch (optional): " }),
+      /* @__PURE__ */ jsx4(TextInput, { value: branch, onChange: setBranch, focus: field === "branch" })
+    ] }),
+    submitting && /* @__PURE__ */ jsx4(Text4, { color: "yellow", children: "Creating\u2026" }),
+    error && /* @__PURE__ */ jsxs4(Text4, { color: "red", children: [
+      "Error: ",
+      error
+    ] })
+  ] });
+}
+var init_NewRequestScreen = __esm({
+  "src/tui/NewRequestScreen.tsx"() {
+    "use strict";
+    init_usePoll();
+    init_tui_api();
+  }
+});
+
+// src/tui/WidgetAnswerScreen.tsx
+import { useState as useState5 } from "react";
+import { Box as Box5, Text as Text5, useInput as useInput4 } from "ink";
+import TextInput2 from "ink-text-input";
+import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
+function renderOptionLabel(opt, i, cursor, isSingle, checked) {
+  const pointer = i === cursor ? "\u25B6 " : "  ";
+  if (isSingle) {
+    return `${pointer}${opt.label}`;
+  }
+  return `${pointer}[${checked.has(opt.id) ? "x" : " "}] ${opt.label}`;
+}
+function WidgetAnswerScreen({ config, message, onDone }) {
+  const [widgetIndex, setWidgetIndex] = useState5(0);
+  const [cursor, setCursor] = useState5(0);
+  const [checked, setChecked] = useState5(/* @__PURE__ */ new Set());
+  const [customText, setCustomText] = useState5("");
+  const [showCustom, setShowCustom] = useState5(false);
+  const [error, setError] = useState5(null);
+  const [submitting, setSubmitting] = useState5(false);
+  const widget = message.widgets[widgetIndex];
+  function handleSingleInput(input, key, w) {
+    const opts2 = [...w.options, { id: "__other__", label: "Other" }];
+    if (key.upArrow) {
+      setCursor((c) => Math.max(0, c - 1));
+    } else if (key.downArrow) {
+      setCursor((c) => Math.min(opts2.length - 1, c + 1));
+    } else if (key.return) {
+      const picked = opts2[cursor];
+      if (picked?.id === "__other__") {
+        setShowCustom(true);
+      } else {
+        void advanceOrSubmit(w, picked?.id, void 0, void 0);
+      }
+    }
+  }
+  function handleMultiInput(input, key, w) {
+    const opts2 = [...w.options, { id: "__other__", label: "Other" }];
+    if (key.upArrow) {
+      setCursor((c) => Math.max(0, c - 1));
+    } else if (key.downArrow) {
+      setCursor((c) => Math.min(opts2.length - 1, c + 1));
+    } else if (input === " ") {
+      const picked = opts2[cursor];
+      if (!picked) return;
+      if (picked.id === "__other__") {
+        setShowCustom((s) => !s);
+      } else {
+        const next = new Set(checked);
+        if (next.has(picked.id)) next.delete(picked.id);
+        else next.add(picked.id);
+        setChecked(next);
+      }
+    } else if (key.return) {
+      void advanceOrSubmit(w, void 0, [...checked], customText || void 0);
+    }
+  }
+  useInput4((input, key) => {
+    if (!widget) return;
+    if (widget.type === "single_select") {
+      handleSingleInput(input, key, widget);
+    } else {
+      handleMultiInput(input, key, widget);
+    }
+  });
+  async function advanceOrSubmit(w, optionId, optionIds, custom) {
+    const answers = [
+      {
+        widgetId: w.id,
+        ...optionId !== void 0 ? { optionId } : {},
+        ...optionIds !== void 0 ? { optionIds } : {},
+        ...custom ? { customText: custom } : {}
+      }
+    ];
+    if (widgetIndex < message.widgets.length - 1) {
+      setWidgetIndex((i) => i + 1);
+      setCursor(0);
+      setChecked(/* @__PURE__ */ new Set());
+      setCustomText("");
+      setShowCustom(false);
+      return;
+    }
+    setSubmitting(true);
+    setError(null);
+    try {
+      await answerWidgets(config, message.id, { requestId: message.requestId, answers });
+      onDone();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Unknown error");
+      setSubmitting(false);
+    }
+  }
+  if (!widget) return /* @__PURE__ */ jsx5(Text5, { children: "No widgets to answer." });
+  const isSingle = widget.type === "single_select";
+  const opts = [...widget.options, { id: "__other__", label: "Other" }];
+  return /* @__PURE__ */ jsxs5(Box5, { flexDirection: "column", gap: 1, children: [
+    /* @__PURE__ */ jsxs5(Text5, { bold: true, children: [
+      "Widget ",
+      widgetIndex + 1,
+      "/",
+      message.widgets.length,
+      ": ",
+      widget.question
+    ] }),
+    widget.body && /* @__PURE__ */ jsx5(Text5, { dimColor: true, children: widget.body }),
+    /* @__PURE__ */ jsx5(Text5, { dimColor: true, children: isSingle ? "\u2191\u2193 to navigate, Enter to select" : "\u2191\u2193 to navigate, Space to toggle, Enter to confirm" }),
+    opts.map((opt, i) => /* @__PURE__ */ jsx5(Text5, { color: i === cursor ? "cyan" : void 0, children: renderOptionLabel(opt, i, cursor, isSingle, checked) }, opt.id)),
+    showCustom && /* @__PURE__ */ jsxs5(Box5, { children: [
+      /* @__PURE__ */ jsx5(Text5, { children: "Custom answer: " }),
+      /* @__PURE__ */ jsx5(TextInput2, { value: customText, onChange: setCustomText, focus: showCustom })
+    ] }),
+    submitting && /* @__PURE__ */ jsx5(Text5, { color: "yellow", children: "Submitting\u2026" }),
+    error && /* @__PURE__ */ jsxs5(Text5, { color: "red", children: [
+      "Error: ",
+      error
+    ] })
+  ] });
+}
+var init_WidgetAnswerScreen = __esm({
+  "src/tui/WidgetAnswerScreen.tsx"() {
+    "use strict";
+    init_tui_api();
+  }
+});
+
+// src/tui/ThreadScreen.tsx
+import { useState as useState6 } from "react";
+import { Box as Box6, Text as Text6, useInput as useInput5 } from "ink";
+import TextInput3 from "ink-text-input";
+import { Fragment, jsx as jsx6, jsxs as jsxs6 } from "react/jsx-runtime";
+function ThreadScreen({ config, requestId, onBack }) {
+  const data = usePoll(() => getRequest(config, requestId), 3e3);
+  const [cursor, setCursor] = useState6(0);
+  const [overlay, setOverlay] = useState6({ kind: "none" });
+  const [targetBranch, setTargetBranch] = useState6("main");
+  const [mergeBranch, setMergeBranch] = useState6("");
+  const [acceptStep, setAcceptStep] = useState6("target");
+  const [error, setError] = useState6(null);
+  const messages = data?.messages ?? [];
+  const sessions = data?.sessions ?? [];
+  const selectedMsg = messages[cursor];
+  const implementableSession = sessions.find((s) => s.status === "planned" || s.status === "ready");
+  useInput5((_input, key) => {
+    if (overlay.kind !== "none") return;
+    if (key.escape) {
+      onBack();
+      return;
+    }
+    if (key.upArrow) {
+      setCursor((c) => Math.max(0, c - 1));
+      return;
+    }
+    if (key.downArrow) {
+      setCursor((c) => Math.min(messages.length - 1, c + 1));
+      return;
+    }
+    if (key.return && selectedMsg) {
+      if (selectedMsg.widgets?.length) {
+        const widgets = selectedMsg.widgets;
+        setOverlay({ kind: "widget", message: { ...selectedMsg, widgets, requestId } });
+      } else if (selectedMsg.type === "plan") {
+        setTargetBranch("main");
+        setMergeBranch("");
+        setAcceptStep("target");
+        setOverlay({ kind: "accept", messageId: selectedMsg.id });
+      }
+    }
+    if (_input === "i" && implementableSession) {
+      void doImplement(implementableSession.id);
+    }
+  });
+  async function doAcceptPlan() {
+    if (overlay.kind !== "accept") return;
+    try {
+      await acceptPlan(
+        config,
+        overlay.messageId,
+        targetBranch.trim() || "main",
+        mergeBranch.trim() || "flumecode/session"
+      );
+      setOverlay({ kind: "accepted" });
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Unknown error");
+    }
+  }
+  async function doImplement(sessionId) {
+    try {
+      await startImplementing(config, sessionId);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Unknown error");
+    }
+  }
+  if (overlay.kind === "widget") {
+    return /* @__PURE__ */ jsx6(
+      WidgetAnswerScreen,
+      {
+        config,
+        message: overlay.message,
+        onDone: () => setOverlay({ kind: "none" })
+      }
+    );
+  }
+  if (overlay.kind === "accept") {
+    return /* @__PURE__ */ jsxs6(Box6, { flexDirection: "column", gap: 1, children: [
+      /* @__PURE__ */ jsx6(Text6, { bold: true, children: "Accept Plan" }),
+      /* @__PURE__ */ jsx6(Text6, { children: "Enter target branch (base):" }),
+      /* @__PURE__ */ jsx6(
+        TextInput3,
+        {
+          value: targetBranch,
+          onChange: setTargetBranch,
+          onSubmit: () => setAcceptStep("merge"),
+          focus: acceptStep === "target"
+        }
+      ),
+      acceptStep === "merge" && /* @__PURE__ */ jsxs6(Fragment, { children: [
+        /* @__PURE__ */ jsx6(Text6, { children: "Enter merge branch name:" }),
+        /* @__PURE__ */ jsx6(
+          TextInput3,
+          {
+            value: mergeBranch,
+            onChange: setMergeBranch,
+            onSubmit: () => void doAcceptPlan(),
+            focus: true
+          }
+        )
+      ] }),
+      error && /* @__PURE__ */ jsx6(Text6, { color: "red", children: error })
+    ] });
+  }
+  return /* @__PURE__ */ jsxs6(Box6, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsx6(Text6, { bold: true, children: "Thread (\u2191\u2193 navigate, Enter act on selected, i implement, Esc back)" }),
+    !data && /* @__PURE__ */ jsx6(Text6, { children: "Loading\u2026" }),
+    overlay.kind === "accepted" && /* @__PURE__ */ jsx6(Text6, { color: "green", children: "Plan accepted! Job queued." }),
+    messages.map((msg, i) => /* @__PURE__ */ jsx6(Box6, { flexDirection: "column", marginY: 0, children: /* @__PURE__ */ jsxs6(Text6, { color: i === cursor ? "cyan" : void 0, children: [
+      i === cursor ? "\u25B6 " : "  ",
+      "[",
+      msg.type,
+      "] ",
+      msg.body?.slice(0, 80) ?? "",
+      msg.widgets?.length ? ` (${msg.widgets.length} widget${msg.widgets.length > 1 ? "s" : ""})` : ""
+    ] }) }, msg.id)),
+    implementableSession && /* @__PURE__ */ jsxs6(Text6, { dimColor: true, children: [
+      "Press i to start implementing session ",
+      implementableSession.id.slice(0, 8),
+      "\u2026"
+    ] }),
+    error && /* @__PURE__ */ jsx6(Text6, { color: "red", children: error })
+  ] });
+}
+var init_ThreadScreen = __esm({
+  "src/tui/ThreadScreen.tsx"() {
+    "use strict";
+    init_usePoll();
+    init_tui_api();
+    init_WidgetAnswerScreen();
+  }
+});
+
+// src/tui/App.tsx
+var App_exports = {};
+__export(App_exports, {
+  App: () => App
+});
+import { useState as useState7 } from "react";
+import { Box as Box7 } from "ink";
+import { jsx as jsx7, jsxs as jsxs7 } from "react/jsx-runtime";
+function renderScreen(screen, setScreen, config) {
+  switch (screen.name) {
+    case "repos":
+      return /* @__PURE__ */ jsx7(
+        RepoListScreen,
+        {
+          config,
+          onSelect: (repo) => setScreen({ name: "requests", repo })
+        }
+      );
+    case "requests":
+      return /* @__PURE__ */ jsx7(
+        RequestListScreen,
+        {
+          config,
+          repo: screen.repo,
+          onOpen: (req) => setScreen({ name: "thread", repo: screen.repo, requestId: req.id }),
+          onNew: () => setScreen({ name: "new-request", repo: screen.repo }),
+          onBack: () => setScreen({ name: "repos" })
+        }
+      );
+    case "new-request":
+      return /* @__PURE__ */ jsx7(
+        NewRequestScreen,
+        {
+          config,
+          repo: screen.repo,
+          onCreated: (requestId) => setScreen({ name: "thread", repo: screen.repo, requestId }),
+          onBack: () => setScreen({ name: "requests", repo: screen.repo })
+        }
+      );
+    case "thread":
+      return /* @__PURE__ */ jsx7(
+        ThreadScreen,
+        {
+          config,
+          requestId: screen.requestId,
+          onBack: () => setScreen({ name: "requests", repo: screen.repo })
+        }
+      );
+  }
+}
+function App({ config }) {
+  const [screen, setScreen] = useState7({ name: "repos" });
+  const jobs = usePoll(() => listJobs(config), 3e3);
+  const runners = usePoll(() => listRunners(config), 3e3);
+  return /* @__PURE__ */ jsxs7(Box7, { flexDirection: "column", children: [
+    renderScreen(screen, setScreen, config),
+    /* @__PURE__ */ jsx7(StatusBar, { jobs, runners })
+  ] });
+}
+var init_App = __esm({
+  "src/tui/App.tsx"() {
+    "use strict";
+    init_tui_api();
+    init_usePoll();
+    init_StatusBar();
+    init_RepoListScreen();
+    init_RequestListScreen();
+    init_NewRequestScreen();
+    init_ThreadScreen();
+  }
+});
 
 // src/cli.ts
 import { createInterface } from "node:readline/promises";
@@ -15,7 +663,9 @@ function readConfig() {
   try {
     const parsed = JSON.parse(readFileSync(configPath, "utf8"));
     if (!parsed.serverUrl || !parsed.token) return null;
-    return { serverUrl: parsed.serverUrl, token: parsed.token };
+    const config = { serverUrl: parsed.serverUrl, token: parsed.token };
+    if (parsed.apiToken) config.apiToken = parsed.apiToken;
+    return config;
   } catch {
     return null;
   }
@@ -26,38 +676,11 @@ function writeConfig(config) {
 }
 
 // src/run.ts
-import { existsSync as existsSync4 } from "node:fs";
-import { join as join5 } from "node:path";
-
-// src/version.ts
-import { readFileSync as readFileSync2 } from "node:fs";
-import { fileURLToPath } from "node:url";
-function readVersion() {
-  try {
-    const path = fileURLToPath(new URL("../package.json", import.meta.url));
-    const pkg = JSON.parse(readFileSync2(path, "utf8"));
-    return pkg.version ?? "unknown";
-  } catch {
-    return "unknown";
-  }
-}
-var RUNNER_VERSION = readVersion();
-var RUNNER_VERSION_HEADER = "x-flumecode-runner-version";
-var RUNNER_MIN_VERSION_HEADER = "x-flumecode-min-runner-version";
-var RUNNER_LATEST_VERSION_HEADER = "x-flumecode-latest-runner-version";
-function compareVersions(a, b) {
-  const parse = (v) => (v.split("-")[0] ?? v).split(".").map((n) => Number.parseInt(n, 10) || 0);
-  const pa = parse(a);
-  const pb = parse(b);
-  const len = Math.max(pa.length, pb.length);
-  for (let i = 0; i < len; i++) {
-    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
-    if (diff !== 0) return diff;
-  }
-  return 0;
-}
+import { existsSync as existsSync5 } from "node:fs";
+import { join as join6 } from "node:path";
 
 // src/api.ts
+init_version();
 var OUTDATED_WARN_INTERVAL_MS = 60 * 6e4;
 var lastOutdatedWarnAt = 0;
 var UPDATE_NUDGE_INTERVAL_MS = 60 * 6e4;
@@ -172,6 +795,20 @@ async function fetchRelatedSessions(config, params) {
     return [];
   }
 }
+async function mintUploadUrls(config, jobId, keys) {
+  const res = await fetch(`${config.serverUrl}/api/runner/previews/mint-upload-urls`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${config.token}`,
+      "content-type": "application/json",
+      [RUNNER_VERSION_HEADER]: RUNNER_VERSION
+    },
+    body: JSON.stringify({ jobId, keys })
+  });
+  noteServerVersion(res);
+  if (!res.ok) throw new Error(`mint-upload-urls failed: ${res.status} ${await safeText(res)}`);
+  return res.json();
+}
 async function safeText(res) {
   try {
     return await res.text();
@@ -1103,6 +1740,36 @@ function buildCodexPrompt(ctx) {
     "\n"
   );
 }
+function buildPreviewPrompt(ctx, committedFileNames, tmpRoute) {
+  const lines2 = [
+    `You are "${ctx.agentName}" authoring an ephemeral UI showcase for ${ctx.repo.fullName}.`,
+    `An implementation just ran and committed UI changes to branch "${ctx.repo.checkoutBranch}". Use the \`flumecode:preview-ui\` skill to create a temporary showcase page that imports the changed components and fills them with realistic fake data.`,
+    `Write your showcase files under \`${tmpRoute}\` and write the URL path to \`${tmpRoute}/.showcase-path\`.`,
+    `These files are ephemeral and git-excluded \u2014 do NOT commit or push them.`,
+    "",
+    "These coding guidelines apply to all code produced in this run:",
+    "",
+    loadRule("coding-guideline"),
+    "",
+    `# Request: ${ctx.request?.title ?? ""}`
+  ];
+  if (ctx.request?.body) {
+    lines2.push("", ctx.request.body);
+  }
+  if (committedFileNames.trim()) {
+    lines2.push(
+      "",
+      "UI files changed by this implementation (showcase these components):",
+      "",
+      committedFileNames.trim()
+    );
+  }
+  lines2.push(
+    "",
+    "When done, reply with one short sentence confirming what showcase file you created."
+  );
+  return lines2.join("\n");
+}
 function buildInitPrompt(ctx) {
   return [
     `You are "${ctx.agentName}" initializing FlumeCode for the repository ${ctx.repo.fullName}, checked out in your current working directory.`,
@@ -1397,6 +2064,18 @@ async function openPullRequest(ctx) {
   }
   throw new Error(`PR creation failed: ${res.status} ${await res.text()}`);
 }
+async function gitCommittedFiles(dir) {
+  const { stdout: stdout2 } = await git([
+    "-C",
+    dir,
+    "--no-pager",
+    "show",
+    "--name-only",
+    "--format=",
+    "HEAD"
+  ]);
+  return stdout2;
+}
 async function cleanup(dir) {
   await rm(dir, { recursive: true, force: true });
 }
@@ -1456,6 +2135,250 @@ async function prNumbersForCommit(ctx, sha) {
   }
 }
 
+// src/preview.ts
+import { appendFileSync, existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync5, rmSync } from "node:fs";
+import { createServer } from "node:net";
+import { join as join5, relative } from "node:path";
+import { spawn as spawn2 } from "node:child_process";
+var PREVIEW_MAX_TURNS = 60;
+var CAPTURE_TIMEOUT_MS = 3e4;
+var DEV_SERVER_READY_TIMEOUT_MS = 6e4;
+var VIEWPORTS = [
+  { name: "mobile", width: 375, height: 812 },
+  { name: "tablet", width: 768, height: 1024 },
+  { name: "desktop", width: 1280, height: 800 }
+];
+var UI_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".tsx",
+  ".jsx",
+  ".vue",
+  ".svelte",
+  ".astro",
+  ".css",
+  ".scss",
+  ".sass",
+  ".less"
+]);
+function changedFilesTouchUi(stat) {
+  for (const line of stat.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const dot = trimmed.lastIndexOf(".");
+    if (dot === -1) continue;
+    const ext = trimmed.slice(dot);
+    if (UI_EXTENSIONS.has(ext)) return true;
+  }
+  return false;
+}
+function detectFramework(dir) {
+  const pm = detectPackageManager(dir);
+  const pkgPath = join5(dir, "package.json");
+  if (!existsSync4(pkgPath)) return { pm, family: null, devCmd: null };
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync5(pkgPath, "utf8"));
+  } catch {
+    return { pm, family: null, devCmd: null };
+  }
+  const deps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies
+  };
+  const family = pickFamily(deps);
+  const port = 0;
+  const devCmd = family ? pickDevCmd(family, port) : null;
+  return { pm, family, devCmd };
+}
+async function runPreviewPass(ctx, dir, committedFileNames, config, abort) {
+  const tmpRoute = mkTempRouteDir(dir);
+  try {
+    gitExclude(dir, tmpRoute);
+    await runClaudeCode({
+      cwd: dir,
+      prompt: buildPreviewPrompt(ctx, committedFileNames, tmpRoute),
+      permissionMode: ctx.permissionMode,
+      abortController: abort,
+      maxTurns: PREVIEW_MAX_TURNS
+    });
+    const showcasePath = readShowcasePath(tmpRoute);
+    if (!showcasePath) {
+      throw new Error("preview-ui skill did not write .showcase-path \u2014 skipping preview");
+    }
+    const framework = detectFramework(dir);
+    if (!framework.family) {
+      throw new Error("unsupported framework \u2014 skipping preview");
+    }
+    const port = await findFreePort();
+    const devServer = await startDevServer(dir, framework, port);
+    try {
+      const url = `http://localhost:${port}${showcasePath}`;
+      const shots = await captureWithChromium(url, VIEWPORTS);
+      const { previewId, urls } = await mintUploadUrls(config, ctx.jobId, shots.keys);
+      await uploadAll(urls, shots.keys, shots.bytes);
+      return { previewId, entrypoint: shots.entrypointKey };
+    } finally {
+      await devServer.stop();
+    }
+  } finally {
+    rmSync(tmpRoute, { recursive: true, force: true });
+  }
+}
+function pickFamily(deps) {
+  if (deps["next"]) return "next";
+  if (deps["@sveltejs/kit"]) return "svelte-kit";
+  if (deps["nuxt"]) return "nuxt";
+  if (deps["astro"]) return "astro";
+  if (deps["react-scripts"]) return "cra";
+  if (deps["@remix-run/react"] || deps["@remix-run/node"]) return "remix";
+  if (deps["vite"]) {
+    if (deps["vue"]) return "vite-vue";
+    if (deps["svelte"]) return "vite-svelte";
+    if (deps["react"]) return "vite-react";
+    return "vite-react";
+  }
+  return null;
+}
+function pickDevCmd(family, port) {
+  switch (family) {
+    case "next":
+      return ["next", "dev", "-p", String(port)];
+    case "vite-react":
+    case "vite-vue":
+    case "vite-svelte":
+      return ["vite", "--port", String(port)];
+    case "nuxt":
+      return ["nuxt", "dev", "--port", String(port)];
+    case "svelte-kit":
+      return ["vite", "--port", String(port)];
+    case "astro":
+      return ["astro", "dev", "--port", String(port)];
+    case "cra":
+      return ["react-scripts", "start"];
+    case "remix":
+      return ["remix", "dev", "--port", String(port)];
+  }
+}
+function mkTempRouteDir(dir) {
+  const suffix = Math.random().toString(36).slice(2, 10);
+  const tmpRoute = join5(dir, `__flumecode_preview_${suffix}`);
+  mkdirSync2(tmpRoute, { recursive: true });
+  return tmpRoute;
+}
+function gitExclude(dir, tmpRoute) {
+  const excludePath = join5(dir, ".git", "info", "exclude");
+  const rel = relative(dir, tmpRoute);
+  appendFileSync(excludePath, `
+${rel}
+`);
+}
+function readShowcasePath(tmpRoute) {
+  const sentinelPath = join5(tmpRoute, ".showcase-path");
+  if (!existsSync4(sentinelPath)) return null;
+  const content = readFileSync5(sentinelPath, "utf8").trim();
+  return content.length > 0 ? content : null;
+}
+function findFreePort() {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (!addr || typeof addr === "string") {
+        server.close();
+        reject(new Error("Could not determine free port"));
+        return;
+      }
+      const port = addr.port;
+      server.close((err) => {
+        if (err) reject(err);
+        else resolve(port);
+      });
+    });
+    server.on("error", reject);
+  });
+}
+function startDevServer(dir, framework, port) {
+  return new Promise((resolve, reject) => {
+    const pm = framework.pm ?? "npm";
+    const devCmd = pickDevCmd(framework.family, port);
+    const argv = [pm === "npm" ? "npx" : "exec", ...devCmd];
+    const cmd = pm === "npm" ? "npx" : pm;
+    const args = pm === "npm" ? devCmd : ["exec", ...devCmd];
+    const proc = spawn2(cmd, args, {
+      cwd: dir,
+      env: { ...process.env, PORT: String(port) },
+      stdio: "ignore"
+    });
+    proc.on("error", reject);
+    const baseUrl = `http://localhost:${port}`;
+    const deadline = Date.now() + DEV_SERVER_READY_TIMEOUT_MS;
+    const poll = () => {
+      fetch(baseUrl).then((res) => {
+        if (res.ok || res.status < 500) {
+          resolve({
+            stop: () => new Promise((res2) => {
+              proc.kill();
+              proc.on("close", () => res2());
+              setTimeout(res2, 500);
+            })
+          });
+        } else {
+          scheduleNext();
+        }
+      }).catch(() => scheduleNext());
+    };
+    const scheduleNext = () => {
+      if (Date.now() > deadline) {
+        proc.kill();
+        reject(
+          new Error(`Dev server did not become ready within ${DEV_SERVER_READY_TIMEOUT_MS}ms`)
+        );
+        return;
+      }
+      setTimeout(poll, 1e3);
+    };
+    setTimeout(poll, 2e3);
+  });
+}
+async function captureWithChromium(url, viewports) {
+  const { chromium } = await import("playwright");
+  const browser = await chromium.launch({ headless: true });
+  const keys = [];
+  const bytes = [];
+  try {
+    for (const vp of viewports) {
+      const context = await browser.newContext({
+        viewport: { width: vp.width, height: vp.height }
+      });
+      const page = await context.newPage();
+      await page.goto(url, { timeout: CAPTURE_TIMEOUT_MS, waitUntil: "networkidle" });
+      const screenshot = await page.screenshot({ fullPage: true, type: "png" });
+      keys.push(`${vp.name}.png`);
+      bytes.push(Buffer.from(screenshot));
+      await context.close();
+    }
+  } finally {
+    await browser.close();
+  }
+  return {
+    keys,
+    bytes,
+    entrypointKey: keys[keys.length - 1] ?? "desktop.png"
+  };
+}
+async function uploadAll(urls, keys, bytes) {
+  await Promise.all(
+    keys.map((key, i) => {
+      const url = urls[key];
+      if (!url) return Promise.resolve();
+      return fetch(url, {
+        method: "PUT",
+        headers: { "content-type": "image/png" },
+        body: bytes[i]
+      });
+    })
+  );
+}
+
 // src/run.ts
 var IDLE_MS = 5e3;
 var CANCEL_POLL_MS = 2500;
@@ -1650,7 +2573,7 @@ async function processChatJob(ctx, dir, config, abort) {
     console.log(`  \u2026job ${ctx.jobId} posted ${result.widgets.length} widget(s); awaiting reply`);
     return { text: reply, widgets: result.widgets };
   }
-  const wikiExists = existsSync4(join5(dir, ".flumecode", "wiki"));
+  const wikiExists = existsSync5(join6(dir, ".flumecode", "wiki"));
   let documented = false;
   if (ctx.permissionMode !== "plan" && wikiExists && await hasChanges(dir)) {
     try {
@@ -1739,7 +2662,7 @@ ${reply}`;
 
 > \u26A0\uFE0F Dependencies failed to install (\`${installResult.manager}\`); tests may not have run.`;
   }
-  const wikiExists = existsSync4(join5(dir, ".flumecode", "wiki"));
+  const wikiExists = existsSync5(join6(dir, ".flumecode", "wiki"));
   let documented = false;
   if (wikiExists && await hasChanges(dir)) {
     try {
@@ -1764,11 +2687,24 @@ ${reply}`;
   });
   reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented, autoMerged });
   const finalReport = report && conflictResolution ? { ...report, conflictResolution } : report;
+  let preview;
+  if (outcome.kind !== "none") {
+    const committedFileNames = await gitCommittedFiles(dir);
+    if (changedFilesTouchUi(committedFileNames)) {
+      try {
+        console.log(`  \u2026generating UI preview for implement ${ctx.jobId}`);
+        preview = await runPreviewPass(ctx, dir, committedFileNames, config, abort);
+      } catch (err) {
+        console.warn(`  preview skipped: ${errorMessage2(err)}`);
+      }
+    }
+  }
   return {
     text: reply,
     widgets: [],
     ...finalReport ? { report: finalReport } : {},
-    ...outcome.kind === "pr" ? { pr: outcome.pr } : {}
+    ...outcome.kind === "pr" ? { pr: outcome.pr } : {},
+    ...preview ? { preview } : {}
   };
 }
 async function processReviseJob(ctx, dir, resumed, config, abort) {
@@ -1795,7 +2731,7 @@ async function processReviseJob(ctx, dir, resumed, config, abort) {
     console.log(`  \u2026revise ${ctx.jobId} posted ${result.widgets.length} widget(s); awaiting reply`);
     return { text: reply, widgets: result.widgets };
   }
-  const wikiExists = existsSync4(join5(dir, ".flumecode", "wiki"));
+  const wikiExists = existsSync5(join6(dir, ".flumecode", "wiki"));
   let documented = false;
   if (wikiExists && await hasChanges(dir)) {
     try {
@@ -1822,12 +2758,25 @@ async function processReviseJob(ctx, dir, resumed, config, abort) {
     reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented, autoMerged });
   }
   const finalReport = report && conflictResolution ? { ...report, conflictResolution } : report;
+  let preview;
+  if (outcome.kind !== "none") {
+    const committedFileNames = await gitCommittedFiles(dir);
+    if (changedFilesTouchUi(committedFileNames)) {
+      try {
+        console.log(`  \u2026generating UI preview for revise ${ctx.jobId}`);
+        preview = await runPreviewPass(ctx, dir, committedFileNames, config, abort);
+      } catch (err) {
+        console.warn(`  preview skipped: ${errorMessage2(err)}`);
+      }
+    }
+  }
   return {
     text: reply,
     widgets: [],
     ...finalReport ? { report: finalReport } : {},
     ...outcome.kind === "pr" ? { pr: outcome.pr } : {},
-    ...result.plans?.length ? { plans: result.plans } : {}
+    ...result.plans?.length ? { plans: result.plans } : {},
+    ...preview ? { preview } : {}
   };
 }
 async function processResolveJob(ctx, dir, config, abort) {
@@ -1939,7 +2888,7 @@ async function pollLoop(config) {
       scheduleCancelPoll();
       try {
         resetUsage();
-        const { text, widgets, pr, plans, report } = await processJob(ctx, config, abort);
+        const { text, widgets, pr, plans, report, preview } = await processJob(ctx, config, abort);
         const usage = getUsage();
         await reportJob(config, ctx.jobId, {
           status: "done",
@@ -1948,6 +2897,7 @@ async function pollLoop(config) {
           pr,
           ...plans?.length ? { plans } : {},
           ...report ? { report } : {},
+          ...preview ? { preview } : {},
           ...usage.totalTokens > 0 ? { usage } : {}
         });
         console.log(`\u2713 Job ${ctx.jobId} done`);
@@ -2027,6 +2977,8 @@ function formatJobError(ctx, err) {
 }
 
 // src/cli.ts
+init_version();
+import React7 from "react";
 var DEFAULT_SERVER = process.env.FLUME_SERVER || "http://localhost:3000";
 async function login(args) {
   const flags = parseFlags(args);
@@ -2061,6 +3013,21 @@ async function start() {
   }
   await pollLoop(config);
 }
+async function runTui(args) {
+  const flags = parseFlags(args);
+  let config = readConfig() ?? { serverUrl: flags.server ?? DEFAULT_SERVER, token: "" };
+  if (flags.server) config.serverUrl = flags.server.replace(/\/+$/, "");
+  if (flags.token) config.apiToken = flags.token;
+  if (!config.apiToken) {
+    const rl = createInterface({ input: stdin, output: stdout });
+    config.apiToken = (await rl.question("CLI token (flcli_\u2026): ")).trim();
+    rl.close();
+  }
+  writeConfig(config);
+  const { render } = await import("ink");
+  const { App: App2 } = await Promise.resolve().then(() => (init_App(), App_exports));
+  render(React7.createElement(App2, { config }));
+}
 function parseFlags(args) {
   const out = {};
   for (let i = 0; i < args.length; i++) {
@@ -2078,11 +3045,14 @@ if (command === "--version" || command === "-v" || command === "version") {
   void login(rest);
 } else if (command === "start") {
   void start();
+} else if (command === "tui") {
+  void runTui(rest);
 } else {
   console.log(`FlumeCode runner v${RUNNER_VERSION}`);
   console.log("Usage:");
   console.log("  flumecode login     # save server URL + token");
   console.log("  flumecode start     # poll for and run jobs");
+  console.log("  flumecode tui       # open the interactive TUI");
   console.log("  flumecode --version # print the runner version");
   process.exit(command ? 1 : 0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flumecode/runner",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "type": "module",
   "description": "FlumeCode local runner — claims jobs and drives your local Claude Code against a real checkout.",
   "bin": {
@@ -28,11 +28,17 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.0",
     "@modelcontextprotocol/sdk": "^1",
+    "ink": "^5.2.1",
+    "ink-text-input": "^6.0.0",
+    "playwright": "^1.52.0",
+    "react": "^18.3.1",
     "zod": "4.4.3"
   },
   "devDependencies": {
     "@types/node": "^22.10.5",
+    "@types/react": "^19.0.0",
     "esbuild": "^0.24.2",
+    "ink-testing-library": "^4.0.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.3"
   }

package/skills-plugin/skills/preview-ui/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: preview-ui
+description: >-
+  Author an ephemeral fake-data showcase page for changed UI components so the
+  runner can screenshot them in a headless browser. Use after a UI-touching
+  implementation, when the runner provides a tmpRoute directory. Writes the
+  showcase files there and records the URL path in a sentinel file. Never
+  commits, pushes, or modifies application code outside the tmpRoute directory.
+---
+
+# preview-ui
+
+You author a **temporary showcase page** that imports the recently-changed UI
+components and fills them with realistic fake data, so the runner can start the
+repo's dev server and take headless screenshots.
+
+You write only inside the `<tmpRoute>` directory the runner hands you. You never
+modify production code, commit, or push.
+
+## What you receive
+
+The runner injects these into your prompt:
+
+- **`<tmpRoute>`** — an absolute path to an empty temp directory inside the repo
+  (already git-excluded). Write your showcase files here.
+- **Committed UI files** — the list of files changed by the implementation, so
+  you know which components to showcase.
+
+## Step 1 — Detect the framework
+
+Read the repo's `package.json` (and `package.json` files in workspaces, if any)
+to determine the framework:
+
+| Framework     | Key `dependencies` / `devDependencies`  |
+| ------------- | --------------------------------------- |
+| Next.js       | `next`                                  |
+| Vite + React  | `vite` + `react`                        |
+| Vite + Vue    | `vite` + `vue`                          |
+| Vite + Svelte | `vite` + `svelte` (no SvelteKit)        |
+| SvelteKit     | `@sveltejs/kit`                         |
+| Nuxt          | `nuxt`                                  |
+| Astro         | `astro`                                 |
+| CRA           | `react-scripts`                         |
+| Remix         | `@remix-run/react` or `@remix-run/node` |
+
+If the framework is not recognisable or the file list contains no importable
+components, write a single plain `<tmpRoute>/index.html` file with a message
+like "No supported framework detected" and write `/__flumecode_preview` to
+`<tmpRoute>/.showcase-path`. Then stop — do not create a route file.
+
+## Step 2 — Determine the entry path
+
+Choose a URL path unlikely to collide with real routes: `/__flumecode_preview`.
+Write that string (exactly, no trailing newline) to `<tmpRoute>/.showcase-path`.
+
+## Step 3 — Author the showcase entry file
+
+Create a single route/page file at the correct location under `<tmpRoute>` for
+the detected framework:
+
+| Framework              | File to create                                        |
+| ---------------------- | ----------------------------------------------------- |
+| Next.js (App Router)   | `<tmpRoute>/page.tsx` (if the project uses `app/`)    |
+| Next.js (Pages Router) | `<tmpRoute>/index.tsx` (if the project uses `pages/`) |
+| Vite + React           | `<tmpRoute>/App.tsx` (or `.jsx`)                      |
+| Vite + Vue             | `<tmpRoute>/App.vue`                                  |
+| Vite + Svelte          | `<tmpRoute>/App.svelte`                               |
+| SvelteKit              | `<tmpRoute>/+page.svelte`                             |
+| Nuxt                   | `<tmpRoute>/index.vue`                                |
+| Astro                  | `<tmpRoute>/index.astro`                              |
+| CRA                    | `<tmpRoute>/index.tsx`                                |
+| Remix                  | `<tmpRoute>/route.tsx`                                |
+
+**Next.js App Router note:** The runner mounts the showcase at
+`app/__flumecode_preview/page.tsx` by symlinking or copying `<tmpRoute>` to
+`app/__flumecode_preview/`. You only need to produce `<tmpRoute>/page.tsx` — the
+runner handles the mount.
+
+### Content rules
+
+- Import the changed components using their real relative paths (calculate the
+  path from `<tmpRoute>` to the component's source location).
+- Fill every prop with **realistic fake data** — use hardcoded literals, not
+  calls to external APIs or databases.
+- If a component requires a provider (React context, Vuex store, Pinia, etc.),
+  wrap it with a minimal in-file stub provider — do not import the real app
+  store or data layer.
+- If a component calls a route handler or fetch endpoint, stub the relevant
+  function or hook at the top of the file with a mock that returns realistic
+  hard-coded data. Do NOT import MSW or any test library; keep stubs as plain
+  module-level overrides.
+- Export the showcase page as the default export (except Astro/SvelteKit, which
+  don't require a default export).
+- Keep the file short: one `export default` function that renders all changed
+  components in a flex column, with a small amount of padding.
+
+### What NOT to do
+
+- Do not call `fetch`, `axios`, `prisma`, `supabase`, or any I/O in the
+  showcase.
+- Do not import from test utilities, MSW, Storybook, or Cypress.
+- Do not add new npm dependencies.
+- Do not edit any file outside `<tmpRoute>`.
+- Do not commit or push.
+
+## Step 4 — Verify your output
+
+Before finishing, confirm:
+
+1. `<tmpRoute>/.showcase-path` exists and contains the URL path string.
+2. The showcase entry file exists at the expected path under `<tmpRoute>`.
+3. The file imports only modules that already exist in the repo (no invented
+   paths).
+
+If you cannot produce a valid showcase (e.g. the components have complex
+dependencies you cannot stub), write only `<tmpRoute>/.showcase-path` with the
+URL string and leave the entry file absent — the runner will detect the missing
+file and skip the screenshot step gracefully.
+
+## Always
+
+- Write the URL path to `<tmpRoute>/.showcase-path` first, before any other
+  file — the runner reads it even if something else fails.
+- These files are ephemeral and git-excluded. They will be deleted by the runner
+  after screenshots are taken. Never commit or push them.
+- Your final reply should be one short sentence confirming what you created (e.g.
+  "Wrote `<tmpRoute>/page.tsx` showcasing `Button` and `Card` with fake data.").