harnery 0.26.0 → 0.27.0

package/src/core/workflow/workspaces/reclaim.ts

@@ -0,0 +1,109 @@
+/**
+ * Resolve a workspace stuck at `preserved_dirty` (ADR 0042).
+ *
+ * When a run ends with uncommitted work, the provider preserves the worktree
+ * rather than destroying the only copy of that work. That decision is correct,
+ * and until this existed it was also permanent: cleanup re-attempted, found the
+ * tree still dirty, preserved again, and incremented a counter. The only exit
+ * was to leave Harnery and remove the directory by hand, after which Harnery's
+ * records described a workspace that no longer existed.
+ *
+ * The shape of the fix is deliberate. Neither mode deletes anything directly.
+ * Each one makes the working tree *clean* by an explicit, named act, and then
+ * hands off to the ordinary cleanup path, which releases a clean workspace as it
+ * always has. So reclaim adds no second removal path that could diverge from the
+ * audited one, and a force-delete of live work exists nowhere in the codebase.
+ */
+
+import { existsSync } from "node:fs";
+import { git, gitMaybe } from "./git.ts";
+
+export type ReclaimMode = "salvage" | "discard";
+
+export type ReclaimPreparation =
+  | { action: "salvaged"; branch: string; commit: string; detail: string }
+  | { action: "discarded"; detail: string }
+  | { action: "already_clean"; detail: string }
+  | { action: "already_gone"; detail: string };
+
+export interface PrepareReclaimInput {
+  worktreePath: string;
+  mode: ReclaimMode;
+  runId: string;
+}
+
+/**
+ * Bring the worktree to a clean state so ordinary cleanup can release it.
+ *
+ * Returns `already_gone` rather than throwing when the directory has been
+ * removed out from under us. A workspace whose worktree no longer exists has
+ * effectively been reclaimed; treating that as an error is what produced an
+ * attempt counter that only ever went up.
+ */
+export function prepareReclaim(input: PrepareReclaimInput): ReclaimPreparation {
+  if (!existsSync(input.worktreePath)) {
+    return {
+      action: "already_gone",
+      detail: "the worktree directory is already gone; nothing to reclaim",
+    };
+  }
+
+  const status = gitMaybe(input.worktreePath, ["status", "--porcelain"]);
+  if (!status.ok) {
+    throw new Error(`cannot read worktree status for reclaim: ${status.err || "git failed"}`);
+  }
+  if (status.out.trim().length === 0) {
+    return { action: "already_clean", detail: "the worktree has no uncommitted changes" };
+  }
+
+  if (input.mode === "discard") {
+    // Ordered: reset drops tracked modifications, clean removes what reset
+    // cannot see. Running clean first would leave staged deletions behind.
+    git(input.worktreePath, ["reset", "--hard"]);
+    git(input.worktreePath, ["clean", "-fd"]);
+    return { action: "discarded", detail: "uncommitted changes were discarded on request" };
+  }
+
+  // Salvage onto a ref of its own, then put the checked-out branch back exactly
+  // where it was. Two reasons, both learned by doing it the obvious way first:
+  //
+  //  1. Cleanup DELETES the provider's workspace branch. Committing the salvage
+  //     there would have parked the work on a ref that the very next step
+  //     removes, leaving it unreachable and eventually collectable.
+  //  2. Cleanup pins the workspace ref's OID in a frozen intent and refuses when
+  //     it moves, which is a guard worth keeping. Advancing that branch turned
+  //     every reclaim into `blocked`.
+  //
+  // Committing and rewinding satisfies both: the tree ends clean, the workspace
+  // ref ends untouched, and the work lives on a ref cleanup has no reason to
+  // touch.
+  const before = git(input.worktreePath, ["rev-parse", "HEAD"]).trim();
+  git(input.worktreePath, ["add", "-A"]);
+  git(input.worktreePath, ["commit", "--no-verify", "-m", salvageMessage(input.runId)]);
+  const commit = git(input.worktreePath, ["rev-parse", "HEAD"]).trim();
+  const branch = salvageBranch(input.runId);
+  git(input.worktreePath, ["branch", "--force", branch, commit]);
+  git(input.worktreePath, ["reset", "--hard", before]);
+  return {
+    action: "salvaged",
+    branch,
+    commit,
+    detail: `salvaged to ${branch} at ${commit.slice(0, 12)}`,
+  };
+}
+
+/**
+ * `--no-verify` above is not a shortcut. A salvage commit is an archival act on
+ * an abandoned workspace, so a repository hook that rejects work in progress
+ * would convert "preserve the work" into "cannot preserve the work", which is
+ * the failure this whole path exists to prevent.
+ */
+function salvageMessage(runId: string): string {
+  return `chore(workspace): salvage uncommitted work from run ${runId}`;
+}
+
+/** Named for the run rather than the workspace, because the run id is what an
+ * operator has in hand when they come looking for the work later. */
+export function salvageBranch(runId: string): string {
+  return `harnery/salvage/${runId}`;
+}

package/src/lib/tunnel/error-page.ts

@@ -0,0 +1,114 @@
+export interface TunnelErrorPageOptions {
+  kind: "access-denied" | "upstream-unavailable";
+  incidentId: string;
+  timestamp: string;
+  tunnelName: string;
+  method: string;
+  path: string;
+  clientIp: string;
+  cloudflareRay: string;
+  target?: string;
+  errorCode?: string;
+  errorMessage?: string;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#039;");
+}
+
+function diagnosticText(options: TunnelErrorPageOptions): string {
+  const lines = [
+    `Tunnel incident: ${options.incidentId}`,
+    `Time: ${options.timestamp}`,
+    `Problem: ${options.kind}`,
+    `Tunnel: ${options.tunnelName}`,
+    `Request: ${options.method} ${options.path}`,
+    `Client IP: ${options.clientIp || "(not provided by proxy)"}`,
+    `Cloudflare Ray: ${options.cloudflareRay || "(not provided)"}`,
+  ];
+
+  if (options.target) lines.push(`Upstream: ${options.target}`);
+  if (options.errorCode) lines.push(`Error code: ${options.errorCode}`);
+  if (options.errorMessage) lines.push(`Error: ${options.errorMessage}`);
+
+  return lines.join("\n");
+}
+
+export function renderTunnelErrorPage(options: TunnelErrorPageOptions): string {
+  const denied = options.kind === "access-denied";
+  const title = denied ? "This device is not allowed yet" : "The preview is temporarily offline";
+  const summary = denied
+    ? "The tunnel is running, but this device's public IP is not on its access list."
+    : "The public tunnel and access check are working, but the local preview server is not responding.";
+  const nextStep = denied
+    ? "Copy the diagnostic below and send it to the person running the tunnel. It includes the public IP that needs to be allowed."
+    : "Copy the diagnostic below and send it to the person running the tunnel. The incident ID can be matched to the server log.";
+  const diagnostic = diagnosticText(options);
+  const safeDiagnosticForScript = JSON.stringify(diagnostic).replaceAll("<", "\\u003c");
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="robots" content="noindex,nofollow">
+  <title>${escapeHtml(title)}</title>
+  <style>
+    :root { color-scheme: light; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    * { box-sizing: border-box; }
+    body { margin: 0; min-height: 100vh; background: #f4f2ed; color: #17211c; display: grid; place-items: center; padding: 24px; }
+    main { width: min(100%, 720px); background: #fff; border: 1px solid #d8d4ca; border-radius: 18px; box-shadow: 0 18px 50px rgba(23, 33, 28, .10); overflow: hidden; }
+    .bar { height: 8px; background: ${denied ? "#b54708" : "#b42318"}; }
+    .content { padding: clamp(24px, 5vw, 48px); }
+    .eyebrow { margin: 0 0 10px; color: ${denied ? "#8a3708" : "#912018"}; font-size: 13px; font-weight: 750; letter-spacing: .09em; text-transform: uppercase; }
+    h1 { margin: 0; max-width: 18ch; font-size: clamp(30px, 7vw, 48px); line-height: 1.02; letter-spacing: -.04em; }
+    .summary { margin: 20px 0 10px; max-width: 58ch; font-size: 18px; line-height: 1.55; }
+    .next { margin: 0 0 24px; max-width: 62ch; color: #536058; line-height: 1.55; }
+    .diagnostic-wrap { position: relative; }
+    pre { margin: 0; padding: 18px; border: 1px solid #ccd2cd; border-radius: 12px; background: #111814; color: #edf5ef; font: 13px/1.55 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; white-space: pre-wrap; overflow-wrap: anywhere; }
+    button { width: 100%; margin-top: 12px; border: 0; border-radius: 11px; padding: 14px 18px; background: #17643a; color: #fff; font: inherit; font-weight: 750; cursor: pointer; }
+    button:hover { background: #0e5230; }
+    button:focus-visible { outline: 3px solid #87c89f; outline-offset: 3px; }
+    .incident { margin: 18px 0 0; color: #68736c; font-size: 13px; text-align: center; }
+  </style>
+</head>
+<body>
+  <main>
+    <div class="bar"></div>
+    <div class="content">
+      <p class="eyebrow">Tunnel diagnostic</p>
+      <h1>${escapeHtml(title)}</h1>
+      <p class="summary">${escapeHtml(summary)}</p>
+      <p class="next">${escapeHtml(nextStep)}</p>
+      <div class="diagnostic-wrap">
+        <pre id="diagnostic">${escapeHtml(diagnostic)}</pre>
+        <button id="copy" type="button">Copy diagnostic</button>
+      </div>
+      <p class="incident">Incident ${escapeHtml(options.incidentId)}</p>
+    </div>
+  </main>
+  <script>
+    const diagnostic = ${safeDiagnosticForScript};
+    const button = document.getElementById("copy");
+    button.addEventListener("click", async () => {
+      try {
+        await navigator.clipboard.writeText(diagnostic);
+        button.textContent = "Copied";
+      } catch {
+        const range = document.createRange();
+        range.selectNodeContents(document.getElementById("diagnostic"));
+        const selection = window.getSelection();
+        selection.removeAllRanges();
+        selection.addRange(range);
+        button.textContent = "Selected — copy now";
+      }
+    });
+  </script>
+</body>
+</html>`;
+}

package/src/lib/tunnel/gate.ts

@@ -9,6 +9,8 @@
 // available; stdout/stderr is captured into .cache/tunnel/gate.log by the
 // spawner.
 
+import { renderTunnelErrorPage } from "./error-page";
+
 // `--port`/`--name` are also passed on argv (not just env) so the gate's port
 // and instance name show up in its process command line. That's what lets
 // `tunnel down` scope its stray-process sweep to a single instance via
@@ -30,6 +32,7 @@ const TARGET = process.env.HARNERY_TUNNEL_TARGET ?? "127.0.0.1:8001";
 const VHOST = process.env.HARNERY_TUNNEL_VHOST ?? "localhost";
 const PORT = Number(process.env.HARNERY_TUNNEL_PORT ?? argvFlag("--port") ?? "9001");
 const ACCESS = process.env.HARNERY_TUNNEL_ACCESS ?? "cloudflare-allowlist";
+const NAME = argvFlag("--name") ?? "default";
 
 const UPSTREAM_HTTP = `http://${TARGET}`;
 const UPSTREAM_WS = `ws://${TARGET}`;
@@ -38,6 +41,27 @@ interface WsData {
   path: string;
 }
 
+function requestDetails(req: Request, url: URL) {
+  return {
+    incidentId: crypto.randomUUID().slice(0, 8),
+    timestamp: new Date().toISOString(),
+    tunnelName: NAME,
+    method: req.method,
+    path: url.pathname + url.search,
+    clientIp: req.headers.get("cf-connecting-ip") ?? "",
+    cloudflareRay: req.headers.get("cf-ray") ?? "",
+  };
+}
+
+function errorDetails(error: unknown): { code: string; message: string } {
+  if (!(error instanceof Error)) {
+    return { code: "UnknownError", message: String(error) };
+  }
+  const code =
+    "code" in error && typeof error.code === "string" ? error.code : error.name || "Error";
+  return { code, message: error.message || "The upstream request failed." };
+}
+
 const server = Bun.serve<WsData, never>({
   port: PORT,
   hostname: "127.0.0.1",
@@ -51,13 +75,21 @@ const server = Bun.serve<WsData, never>({
     if (ACCESS === "cloudflare-allowlist") {
       const ip = req.headers.get("cf-connecting-ip") ?? "";
       if (!ALLOW.has(ip)) {
+        const details = requestDetails(req, url);
         // Log denials so operators can whitelist a phone/laptop that just
         // hit 403 without asking the human to dig up their public IP.
         console.log(
           // lint-ok-emission: detached worker, see file note above
-          `deny: ${ip || "(missing-cf-connecting-ip)"} ${req.method} ${url.pathname}`,
+          `deny: incident=${details.incidentId} ip=${ip || "(missing-cf-connecting-ip)"} ray=${details.cloudflareRay || "(missing)"} ${req.method} ${details.path}`,
         );
-        return new Response("403 Forbidden\n", { status: 403 });
+        return new Response(renderTunnelErrorPage({ ...details, kind: "access-denied" }), {
+          status: 403,
+          headers: {
+            "cache-control": "no-store",
+            "content-type": "text/html; charset=utf-8",
+            "x-harnery-tunnel-incident": details.incidentId,
+          },
+        });
       }
     }
 
@@ -81,7 +113,38 @@ const server = Bun.serve<WsData, never>({
     if (!["GET", "HEAD"].includes(req.method)) {
       init.body = await req.arrayBuffer();
     }
-    const resp = await fetch(UPSTREAM_HTTP + url.pathname + url.search, init);
+    let resp: Response;
+    try {
+      resp = await fetch(UPSTREAM_HTTP + url.pathname + url.search, init);
+    } catch (error) {
+      const details = requestDetails(req, url);
+      const failure = errorDetails(error);
+      console.log(
+        // lint-ok-emission: detached worker, see file note above
+        `upstream-error: incident=${details.incidentId} ip=${details.clientIp || "(missing-cf-connecting-ip)"} ray=${details.cloudflareRay || "(missing)"} code=${failure.code} ${req.method} ${details.path}`,
+      );
+      return new Response(
+        renderTunnelErrorPage({
+          ...details,
+          kind: "upstream-unavailable",
+          target: UPSTREAM_HTTP,
+          errorCode: failure.code,
+          errorMessage: failure.message,
+        }),
+        {
+          // Cloudflare replaces 502 response bodies with its own generic error
+          // page. Return the diagnostic as a successful document and preserve
+          // the semantic status in a header so the human can actually see it.
+          status: 200,
+          headers: {
+            "cache-control": "no-store",
+            "content-type": "text/html; charset=utf-8",
+            "x-harnery-tunnel-incident": details.incidentId,
+            "x-harnery-tunnel-status": "502",
+          },
+        },
+      );
+    }
     const respHeaders = new Headers(resp.headers);
     respHeaders.delete("content-encoding");
     respHeaders.delete("content-length");