claude-garage 0.1.0

package/daemon/src/hooks.js

@@ -0,0 +1,241 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { timingSafeEqual } from "node:crypto";
+import { copyFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { listSessions } from "./tmux.js";
+import { setStatus } from "./status.js";
+import { getHookToken } from "./registry.js";
+
+const run = promisify(execFile);
+const PORT = Number(process.env.GARAGE_PORT ?? 4747);
+const HOOK_URL = `http://127.0.0.1:${PORT}/api/hooks/claude`;
+
+function tokenMatches(given, expected) {
+  if (typeof given !== "string") return false;
+  const a = Buffer.from(given);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+const EVENT_TO_STATE = {
+  Notification: "needs-input",
+  Stop: "done",
+};
+
+// Claude Code's Notification hook fires for real blockers (permission
+// prompts, questions, plan approvals) AND for a ~60s idle reminder
+// ("Claude is waiting for your input") after a turn ends. The reminder is
+// idle semantics — waiting for you to ASK, not to ANSWER — and mapping it
+// to needs-input raises a sticky false alarm (needs-input never decays by
+// design). Filter it by message; unknown messages stay needs-input
+// (fail toward attention, never away from it).
+const IDLE_REMINDER_RE = /waiting for your input/i;
+
+// Exported for the test suite.
+export function isIdleReminder(message) {
+  return IDLE_REMINDER_RE.test(message ?? "");
+}
+
+async function getAgents() {
+  try {
+    const { stdout } = await run("claude", ["agents", "--json"]);
+    return JSON.parse(stdout);
+  } catch {
+    return [];
+  }
+}
+
+async function getPanePids() {
+  try {
+    const { stdout } = await run("tmux", [
+      "list-panes",
+      "-a",
+      "-F",
+      "#{session_name}\t#{pane_pid}",
+    ]);
+    const map = new Map(); // pid -> session name
+    for (const line of stdout.split("\n")) {
+      if (!line.trim()) continue;
+      const [name, pid] = line.split("\t");
+      map.set(Number(pid), name);
+    }
+    return map;
+  } catch {
+    return new Map();
+  }
+}
+
+// Resolve a hook payload to the garage session id(s) it applies to.
+// Precise path: payload session_id -> agents-json sessionId -> its pid ->
+// pane_pid join. Fallback: cwd fail-open, applied to every garage session
+// sharing that dir (over-notify rather than silently drop).
+async function resolveSessionIds({ session_id, cwd }) {
+  const [agents, pidToSession] = await Promise.all([getAgents(), getPanePids()]);
+
+  if (session_id) {
+    const agent = agents.find((a) => a.sessionId === session_id);
+    const sessionName = agent && pidToSession.get(agent.pid);
+    if (sessionName) return [sessionName];
+  }
+
+  if (cwd) {
+    const sessions = await listSessions();
+    const matches = sessions.filter((s) => s.dir === cwd).map((s) => s.id);
+    if (matches.length > 0) return matches;
+  }
+
+  return [];
+}
+
+export async function hookSnippet() {
+  const token = await getHookToken();
+  const url = `${HOOK_URL}?token=${token}`;
+  return {
+    hooks: {
+      Notification: [{ hooks: [{ type: "http", url }] }],
+      Stop: [{ hooks: [{ type: "http", url }] }],
+    },
+    allowedHttpHookUrls: [`http://127.0.0.1:${PORT}/*`],
+  };
+}
+
+// p7 hooks-install (design D-hooks-install): merge the snippet into
+// ~/.claude/settings.json server-side so the UI can offer one-click
+// installation instead of asking users to hand-merge JSON.
+//
+// Safety order: parse-or-refuse (a corrupt file is returned as an error,
+// byte-for-byte untouched) -> timestamped backup of the pre-install file
+// -> atomic write (tmp + rename, same directory, so a crash mid-write can
+// never leave a half-written settings.json). Idempotency comes from
+// entry-level dedupe: a hook group is only appended when no existing
+// group for that event already carries one of its hook URLs (the URL
+// embeds the per-install token, which is stable — see getHookToken).
+const SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+
+function groupHasAnyUrl(group, urls) {
+  return (group?.hooks ?? []).some((h) => urls.has(h.url));
+}
+
+export function mergeHookSnippet(settings, snippet) {
+  const merged = { ...settings };
+  let changed = false;
+
+  merged.hooks = { ...(merged.hooks ?? {}) };
+  for (const [event, snippetGroups] of Object.entries(snippet.hooks)) {
+    const existing = [...(merged.hooks[event] ?? [])];
+    for (const group of snippetGroups) {
+      const urls = new Set((group.hooks ?? []).map((h) => h.url));
+      if (!existing.some((g) => groupHasAnyUrl(g, urls))) {
+        existing.push(group);
+        changed = true;
+      }
+    }
+    merged.hooks[event] = existing;
+  }
+
+  const allowed = new Set(merged.allowedHttpHookUrls ?? []);
+  for (const url of snippet.allowedHttpHookUrls ?? []) {
+    if (!allowed.has(url)) {
+      allowed.add(url);
+      changed = true;
+    }
+  }
+  merged.allowedHttpHookUrls = [...allowed];
+
+  return { merged, changed };
+}
+
+async function installHooks() {
+  let raw = null;
+  try {
+    raw = await readFile(SETTINGS_PATH, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+
+  let settings = {};
+  if (raw !== null && raw.trim() !== "") {
+    try {
+      settings = JSON.parse(raw);
+    } catch {
+      const error = new Error(
+        `~/.claude/settings.json is not valid JSON — fix it (or remove it) and retry; the file was left untouched`
+      );
+      error.statusCode = 422;
+      throw error;
+    }
+    if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
+      const error = new Error(
+        `~/.claude/settings.json is not a JSON object — the file was left untouched`
+      );
+      error.statusCode = 422;
+      throw error;
+    }
+  }
+
+  const snippet = await hookSnippet();
+  const { merged, changed } = mergeHookSnippet(settings, snippet);
+  if (!changed) {
+    return { ok: true, installed: true, alreadyInstalled: true, backup: null };
+  }
+
+  await mkdir(dirname(SETTINGS_PATH), { recursive: true });
+
+  let backup = null;
+  if (raw !== null) {
+    backup = `${SETTINGS_PATH}.garage-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+    await copyFile(SETTINGS_PATH, backup);
+  }
+
+  const tmp = `${SETTINGS_PATH}.garage-tmp-${process.pid}`;
+  await writeFile(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+  await rename(tmp, SETTINGS_PATH);
+
+  return { ok: true, installed: true, alreadyInstalled: false, backup };
+}
+
+export default async function hookRoutes(app) {
+  // Auth: per-install token in the URL (claude's HTTP hooks are URL-only
+  // config, so the token rides as a query param). Combined with the normal
+  // Origin allowlist — no exemption — a foreign browser page is stopped by
+  // Origin, and anything else without the token is stopped here.
+  app.post("/api/hooks/claude", async (req, reply) => {
+    const expected = await getHookToken();
+    if (!tokenMatches(req.query?.token, expected)) {
+      return reply.code(401).send({ error: "missing or invalid hook token" });
+    }
+
+    const payload = req.body ?? {};
+    const state = EVENT_TO_STATE[payload.hook_event_name];
+    if (!state) {
+      return reply.code(200).send({ ok: true, ignored: true });
+    }
+
+    if (payload.hook_event_name === "Notification" && isIdleReminder(payload.message)) {
+      // Idle reminder — leave the state alone (Stop already set done,
+      // which decays to idle on its own).
+      return reply.code(200).send({ ok: true, ignored: "idle-reminder" });
+    }
+
+    const ids = await resolveSessionIds(payload);
+    for (const id of ids) setStatus(id, state);
+
+    return reply.code(200).send({ ok: true, applied: ids });
+  });
+
+  app.get("/api/hooks/snippet", async () => hookSnippet());
+
+  // p7 hooks-install: browser-called (rides the normal Origin allowlist,
+  // like every /api route except /api/hooks/claude's token scheme).
+  app.post("/api/hooks/install", async (req, reply) => {
+    try {
+      return await installHooks();
+    } catch (err) {
+      return reply
+        .code(err.statusCode ?? 500)
+        .send({ error: err.message ?? "hook install failed" });
+    }
+  });
+}

package/daemon/src/index.js

@@ -0,0 +1,76 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import Fastify from "fastify";
+import fastifyStatic from "@fastify/static";
+import sessionRoutes from "./sessions.js";
+import workspaceRoutes from "./workspaces.js";
+import pickerRoutes from "./picker.js";
+import hookRoutes from "./hooks.js";
+import eventRoutes from "./events.js";
+import notifyRoutes from "./notify.js";
+import diffRoutes from "./diff.js";
+import editorRoutes from "./editor.js";
+import worktreeRoutes from "./worktrees.js";
+import { attachTermServer } from "./term.js";
+import { rejectForeignOrigins } from "./security.js";
+import { startPoller } from "./poller.js";
+
+const HOST = "127.0.0.1";
+const PORT = Number(process.env.GARAGE_PORT ?? 4747);
+
+// daemon/src/index.js -> repo root is two levels up.
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, "..", "..");
+
+// forceCloseConnections: close() actively terminates keep-alive and
+// hijacked connections (SSE, upgraded sockets) instead of waiting for
+// them to drain — they never would; see bin/garage.js shutdown.
+const app = Fastify({ logger: { level: "info" }, forceCloseConnections: true });
+
+app.addHook("onRequest", rejectForeignOrigins);
+app.get("/api/health", async () => ({ status: "ok" }));
+app.register(sessionRoutes);
+app.register(workspaceRoutes);
+app.register(pickerRoutes);
+app.register(hookRoutes);
+app.register(eventRoutes);
+app.register(notifyRoutes);
+app.register(diffRoutes);
+app.register(editorRoutes);
+app.register(worktreeRoutes);
+attachTermServer(app);
+
+// D-packaging: flag-gated so dev mode (Vite on :5173 proxying to this
+// daemon) never double-registers a static root — registered last, after
+// every /api/* route above, so those routes win over static's own wildcard.
+if (process.env.GARAGE_SERVE_UI === "1") {
+  const uiDist = path.join(REPO_ROOT, "ui", "dist");
+  if (existsSync(uiDist)) {
+    app.register(fastifyStatic, { root: uiDist, prefix: "/" });
+  } else {
+    app.log.error(
+      `GARAGE_SERVE_UI is set but ${uiDist} does not exist — run "npm run build --workspace ui" first`
+    );
+  }
+}
+
+// Poller feeds StatusStore (busy/idle baseline); hooks.js and notify.js
+// subscribe to the same store — see status.js for the single write path.
+const stopPoller = startPoller(app);
+app.addHook("onClose", async () => {
+  stopPoller();
+});
+
+app.listen({ host: HOST, port: PORT }).catch((err) => {
+  if (err.code === "EADDRINUSE") {
+    app.log.error(
+      `port ${PORT} is already in use — set GARAGE_PORT to choose a different port`
+    );
+  } else {
+    app.log.error(err);
+  }
+  process.exit(1);
+});
+
+export { app };

package/daemon/src/notify.js

@@ -0,0 +1,80 @@
+import { execFile } from "node:child_process";
+import { statusEvents } from "./status.js";
+
+const PORT = Number(process.env.GARAGE_PORT ?? 4747);
+const UI_URL = `http://127.0.0.1:${PORT}`;
+
+// D-notify: notification on transition INTO needs-input, edge-triggered
+// (the store only emits "transition" on an actual state change, so this
+// handler naturally fires once per transition, not once per poll tick).
+// Darwin only; a no-op elsewhere. Never throws — a notification failure
+// must not affect the daemon.
+//
+// Clickability: osascript's `display notification` cannot carry a click
+// action — it is a dead-end toast. When terminal-notifier is installed
+// (brew install terminal-notifier), use it instead: its -open flag makes
+// clicking the notification open the pit wall. Checked once, lazily.
+let hasTerminalNotifier = null; // null = not yet probed
+function probeTerminalNotifier(cb) {
+  if (hasTerminalNotifier !== null) return cb(hasTerminalNotifier);
+  execFile("which", ["terminal-notifier"], (err) => {
+    hasTerminalNotifier = !err;
+    cb(hasTerminalNotifier);
+  });
+}
+
+function notifyDarwin(id) {
+  if (process.platform !== "darwin") return;
+  const message = `${id} needs input`;
+  try {
+    probeTerminalNotifier((available) => {
+      if (available) {
+        execFile(
+          "terminal-notifier",
+          ["-title", "claude-garage", "-message", message, "-open", UI_URL],
+          () => {}
+        );
+      } else {
+        const script = `display notification ${JSON.stringify(message)} with title "claude-garage"`;
+        execFile("osascript", ["-e", script], () => {});
+      }
+    });
+  } catch {
+    // never throw
+  }
+}
+
+// Visibility contract: the UI posts here periodically while a pit-wall
+// page is in the foreground. "a visible page exists" = any client entry
+// visible && seen within TTL_MS. Called from the browser, so it stays
+// behind the normal Origin allowlist (unlike /api/hooks/claude).
+const TTL_MS = 45_000;
+const clients = new Map(); // clientId -> { visible, lastSeen }
+
+function anyVisiblePage() {
+  const now = Date.now();
+  for (const { visible, lastSeen } of clients.values()) {
+    if (visible && now - lastSeen <= TTL_MS) return true;
+  }
+  return false;
+}
+
+export default async function notifyRoutes(app) {
+  app.post("/api/ui/visibility", async (req, reply) => {
+    const { clientId, visible } = req.body ?? {};
+    if (typeof clientId !== "string" || !clientId || typeof visible !== "boolean") {
+      return reply
+        .code(400)
+        .send({ error: "clientId (string) and visible (boolean) are required" });
+    }
+    clients.set(clientId, { visible, lastSeen: Date.now() });
+    return reply.code(200).send({ ok: true });
+  });
+
+  statusEvents.on("transition", ({ id, to }) => {
+    if (to === "needs-input" && !anyVisiblePage()) {
+      app.log.info({ id }, "needs-input notification fired");
+      notifyDarwin(id);
+    }
+  });
+}

package/daemon/src/picker.js

@@ -0,0 +1,48 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+// D-picker: browsers deliberately never expose absolute filesystem paths,
+// so the "add workspace" folder picker has to run daemon-side. macOS-only —
+// non-darwin hosts keep the manual path-entry fallback in the UI.
+const PICKER_SCRIPT =
+  'POSIX path of (choose folder with prompt "Add claude-garage workspace")';
+
+// osascript blocks for as long as the dialog is open (the user may leave it
+// sitting there) — give it a generous timeout rather than the execFile
+// default, which would otherwise fail an interaction that's still in progress.
+const PICKER_TIMEOUT_MS = 120_000;
+
+export default async function pickerRoutes(app) {
+  app.post("/api/pick-directory", async (req, reply) => {
+    if (process.platform !== "darwin") {
+      return reply
+        .code(501)
+        .send({ error: "directory picker is only available on macOS" });
+    }
+
+    let stdout;
+    try {
+      ({ stdout } = await run("osascript", ["-e", PICKER_SCRIPT], {
+        timeout: PICKER_TIMEOUT_MS,
+      }));
+    } catch (err) {
+      // osascript exits 1 with "User canceled" in stderr when the user
+      // dismisses the dialog — that's a normal outcome, not an error.
+      const stderr = err?.stderr ?? "";
+      if (stderr.includes("User canceled")) {
+        return reply.code(200).send({ cancelled: true });
+      }
+      return reply.code(500).send({ error: err?.message ?? "osascript failed" });
+    }
+
+    // osascript's `POSIX path of` always trails with a newline, and folder
+    // paths additionally trail with "/" (except the root "/" itself).
+    let dir = stdout.trimEnd();
+    if (dir.length > 1 && dir.endsWith("/")) {
+      dir = dir.slice(0, -1);
+    }
+    return reply.code(200).send({ dir });
+  });
+}

package/daemon/src/poller.js

@@ -0,0 +1,134 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { EventEmitter } from "node:events";
+import { listSessions } from "./tmux.js";
+import { setStatus, getStatus, dropSession } from "./status.js";
+import { upsertSessionMeta } from "./registry.js";
+
+const run = promisify(execFile);
+const POLL_MS = 2000;
+
+// Emits "sessions-changed" whenever the poller notices the garage session
+// list itself changed (spawn/death), so events.js can tell the UI to refetch.
+export const pollerEvents = new EventEmitter();
+pollerEvents.setMaxListeners(0);
+
+let lastSessionIds = new Set();
+
+// `claude agents --json` — missing CLI or any failure is a silent no-op,
+// per D-status's graceful degradation to poller-absent behavior.
+async function getAgents() {
+  try {
+    const { stdout } = await run("claude", ["agents", "--json"]);
+    return JSON.parse(stdout);
+  } catch {
+    return [];
+  }
+}
+
+// tmux pane pid per session name — pane_pid joins exactly to the `pid`
+// reported by `claude agents --json` since garage spawns claude as the
+// pane's root process (design D-status).
+async function getPanePids() {
+  try {
+    const { stdout } = await run("tmux", [
+      "list-panes",
+      "-a",
+      "-F",
+      "#{session_name}\t#{pane_pid}",
+    ]);
+    const map = new Map();
+    for (const line of stdout.split("\n")) {
+      if (!line.trim()) continue;
+      const [name, pid] = line.split("\t");
+      map.set(name, Number(pid));
+    }
+    return map;
+  } catch {
+    return new Map();
+  }
+}
+
+// `claude agents --json` self-reports busy | waiting | idle. `waiting`
+// means blocked on the user (permission prompt, question) — that IS
+// needs-input, just 2s-coarse. Mapping it to idle (the pre-publish bug)
+// meant hookless installs never saw the product's core signal at all.
+// Exported for the test suite.
+export function applyAgentStatus(id, agentStatus) {
+  const mapped =
+    agentStatus === "busy" ? "working" : agentStatus === "waiting" ? "needs-input" : "idle";
+  // The poller's coarse 'idle' must not stomp the hook-sourced precision
+  // states: needs-input clears only on real activity, and done holds until
+  // its decay timer (status.js) or a 'busy' observation (-> working).
+  const current = getStatus(id);
+  if (mapped === "idle" && (current === "needs-input" || current === "done")) return;
+  setStatus(id, mapped);
+}
+
+async function tick() {
+  const sessions = await listSessions().catch(() => []);
+
+  const currentIds = new Set(sessions.map((s) => s.id));
+  let changed = currentIds.size !== lastSessionIds.size;
+  for (const id of lastSessionIds) {
+    if (!currentIds.has(id)) {
+      dropSession(id);
+      changed = true;
+    }
+  }
+  if (!changed) {
+    for (const id of currentIds) {
+      if (!lastSessionIds.has(id)) {
+        changed = true;
+        break;
+      }
+    }
+  }
+  lastSessionIds = currentIds;
+  if (changed) pollerEvents.emit("sessions-changed");
+
+  if (sessions.length === 0) return;
+
+  const [agents, panePids] = await Promise.all([getAgents(), getPanePids()]);
+  if (agents.length === 0) return; // claude CLI missing/no live agents
+
+  const agentByPid = new Map(agents.map((a) => [a.pid, a]));
+  const unmatched = [];
+
+  for (const session of sessions) {
+    const panePid = panePids.get(session.id);
+    const agent = panePid !== undefined ? agentByPid.get(panePid) : undefined;
+    if (agent) {
+      applyAgentStatus(session.id, agent.status);
+      // D-resume-meta: only on the pid-join succeeding do we have a trusted
+      // sessionId for this garage session; upsertSessionMeta itself is a
+      // no-op write when nothing changed. Never let a meta-write failure
+      // interrupt status polling for the rest of the tick.
+      if (agent.sessionId) {
+        await upsertSessionMeta(session.id, {
+          claudeSessionId: agent.sessionId,
+          workspace: session.workspace,
+          label: session.label,
+        }).catch(() => {});
+      }
+    } else {
+      unmatched.push(session);
+    }
+  }
+
+  // Fail-open fallback: pid join missed (e.g. claude exec'd through a
+  // wrapper) — apply the cwd-matching agent's status to ALL sessions in
+  // that dir. Over-notify rather than silently drop.
+  for (const session of unmatched) {
+    const cwdAgent = agents.find((a) => a.cwd === session.dir);
+    if (cwdAgent) applyAgentStatus(session.id, cwdAgent.status);
+  }
+}
+
+export function startPoller(app) {
+  const timer = setInterval(() => {
+    tick().catch((err) => app?.log?.warn?.({ err }, "poller tick failed"));
+  }, POLL_MS);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}