@promptctl/cc-candybar 1.0.0

package/src/daemon/paths.ts

@@ -0,0 +1,127 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// XDG Base Directory split:
+//   - daemon runtime (pid, log, heap snapshots, spawn.lock) → $XDG_STATE_HOME/cc-candybar
+//   - filesystem caches (git, usage, last-render) → $XDG_CACHE_HOME/cc-candybar
+//
+// Both default per the XDG spec ($HOME/.local/state and $HOME/.cache). Empty
+// env vars fall through to the defaults. The two roots are kept separate so
+// users can `rm -rf` either one without taking the other down.
+//
+// The socket path is NOT derived from XDG_STATE_HOME — see socketPath() below.
+// The Rust client mirrors both path families in rust-client/src/main.rs; both
+// must agree or the client can't find the daemon's socket.
+
+function xdgEnv(name: string): string | undefined {
+  const v = process.env[name];
+  return v && v.length > 0 ? v : undefined;
+}
+
+export function stateDir(): string {
+  const base =
+    xdgEnv("XDG_STATE_HOME") ?? path.join(os.homedir(), ".local", "state");
+  return path.join(base, "cc-candybar");
+}
+
+export function cacheDir(): string {
+  const base = xdgEnv("XDG_CACHE_HOME") ?? path.join(os.homedir(), ".cache");
+  return path.join(base, "cc-candybar");
+}
+
+export function configDir(): string {
+  const base = xdgEnv("XDG_CONFIG_HOME") ?? path.join(os.homedir(), ".config");
+  return path.join(base, "cc-candybar");
+}
+
+// `daemonDir` kept as the canonical name for the runtime root so existing
+// callers (limits.ts, server.ts) don't need to learn a new term. It now
+// resolves under $XDG_STATE_HOME/cc-candybar instead of ~/.claude/powerline.
+export function daemonDir(): string {
+  return stateDir();
+}
+
+// [LAW:one-source-of-truth] The socket IS the daemon's identity — same as
+// tmux's /tmp/tmux-<uid>/default model. UID is kernel identity: immutable,
+// not overridable by any env var. /tmp is guaranteed on every Unix host and
+// is cleared on reboot, which is fine — the daemon doesn't survive reboots.
+// CC_CANDYBAR_SOCKET is the only explicit override for intentional isolation
+// (tests, dev, multiple intentional instances).
+export function socketPath(): string {
+  const override = process.env.CC_CANDYBAR_SOCKET;
+  if (override) return override;
+  const uid = os.userInfo().uid;
+  return path.join("/tmp", `cc-candybar-${uid}`, "socket");
+}
+
+// [LAW:single-enforcer] The daemon is the sole creator of the socket parent
+// directory. If we enforce "this dir is uid==me + mode 0700 + not a symlink"
+// at bind time, then by induction every successful bind happened under a
+// trusted parent — and any client reaching the socket via the canonical path
+// reached one our daemon owns. A foreign-uid or world-writable squat triggers
+// a refusal, turning a silent-MITM attempt into a visible daemon failure (the
+// client sees no response, the user sees the last cached render).
+//
+// Throws on any unsafe state; callers are expected to let the daemon exit.
+// [LAW:no-silent-fallbacks] do NOT auto-rmdir + recreate — a wrong-owner dir
+// is hostile state, not a recoverable error.
+export function ensureSocketParentSafe(sockPath: string): void {
+  const parent = path.dirname(sockPath);
+  // mkdir with mode 0o700; harmless if already exists (mode is not applied
+  // post-hoc — we verify it next).
+  fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
+
+  const st = fs.lstatSync(parent);
+  if (st.isSymbolicLink()) {
+    throw new Error(`socket parent is a symlink: ${parent}`);
+  }
+  if (!st.isDirectory()) {
+    throw new Error(`socket parent is not a directory: ${parent}`);
+  }
+  const myUid = os.userInfo().uid;
+  // getuid is undefined on Windows; we don't ship there, but guard cheaply.
+  if (typeof myUid === "number" && st.uid !== myUid) {
+    throw new Error(
+      `socket parent is not owned by uid ${myUid}: ${parent} (owner uid=${st.uid})`,
+    );
+  }
+  // Reject any group/world bits — only the owner may traverse.
+  if ((st.mode & 0o077) !== 0) {
+    throw new Error(
+      `socket parent has unsafe permissions: ${parent} (mode=${(st.mode & 0o777).toString(8)}, expected 0700)`,
+    );
+  }
+  // If a stale socket file is a symlink, refuse — an attacker who briefly
+  // had write access to a previously-permissive dir could have planted a
+  // symlink even after we tighten perms.
+  try {
+    const sst = fs.lstatSync(sockPath);
+    if (sst.isSymbolicLink()) {
+      throw new Error(`socket path is a symlink: ${sockPath}`);
+    }
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") throw e;
+  }
+}
+
+export function pidPath(): string {
+  return path.join(stateDir(), "pid");
+}
+
+export function sessionStatePath(): string {
+  return path.join(stateDir(), "session-state.json");
+}
+
+// [LAW:single-enforcer] Caller-side spawn dedup. Held by a client *only* during
+// the spawn window — never for the daemon's lifetime. The actual one-daemon
+// invariant is enforced by atomic bind() on socketPath() inside the daemon.
+// This file is a thundering-herd optimization, not the load-bearing lock.
+export function spawnLockPath(): string {
+  return path.join(stateDir(), "spawn.lock");
+}
+
+export function logPath(): string {
+  return path.join(stateDir(), "daemon.log");
+}

package/src/daemon/protocol.ts

@@ -0,0 +1,235 @@
+import type { Socket } from "node:net";
+import type { ClaudeHookData } from "../utils/claude";
+import type { StatsSnapshot } from "./stats";
+import type { DebugSnapshot, DebugWhat } from "./debug-types";
+
+// [LAW:types-are-the-program] PROTOCOL_VERSION encodes one thing:
+// "old-client × new-daemon (or vice versa) cannot communicate." It moves on
+// BREAKING changes only — never on additive ones. The two cases are
+// genuinely different theorems and the version field carries the stronger:
+// incompatibility, not growth.
+//
+// **Additive** (no bump):
+//   - Adding a new request `kind`. Old daemons reject the unknown kind via
+//     the existing BAD_REQUEST fallthrough; old clients never send it.
+//   - Adding a new optional field that older parsers ignore safely.
+//   - Adding a new response variant produced only in response to a new kind.
+//
+// **Breaking** (bump):
+//   - Changing the semantics or required shape of an existing kind.
+//   - Removing a kind or field old clients depend on.
+//   - Renaming a wire field.
+//
+// The 452-corpse precedent (kz8.5) makes this discipline load-bearing: every
+// bump forces every running statusbar through VERSION_MISMATCH until its
+// session restarts, because the spiral-breaker contract refuses to kick on a
+// permanent error. A bump for an additive change taxes every user with
+// blank-statusbar minutes for a feature their session doesn't even use.
+// Don't bump for growth.
+export const PROTOCOL_VERSION = 3;
+
+export interface RenderRequest {
+  v: number;
+  kind: "render";
+  hookData: ClaudeHookData;
+  args: string[];
+  cwd: string;
+  // [LAW:single-enforcer] Terminal width is captured at the trust boundary
+  // (the client's env, where COLUMNS/ioctl are meaningful) and trusted by the
+  // daemon. Absence means the client couldn't determine it. The wire field is
+  // typed `number` but the wire is untrusted JSON — callers MUST run it
+  // through sanitizeTermCols at the receive boundary before using it.
+  termCols?: number;
+}
+
+// [LAW:no-defensive-null-guards] exception: trust boundary. The wire is
+// untrusted JSON; downstream code treats termCols as an integer in a sane
+// range. Validate once here so the type's promise is true.
+//
+// Pathologically large values are capped (not rejected) so a future
+// genuinely-huge terminal still renders — 10000 is two orders of magnitude
+// above the largest plausible real terminal.
+const MAX_TERM_COLS = 10000;
+export function sanitizeTermCols(v: unknown): number | undefined {
+  if (typeof v !== "number") return undefined;
+  if (!Number.isFinite(v)) return undefined;
+  const n = Math.floor(v);
+  if (n <= 0) return undefined;
+  return n > MAX_TERM_COLS ? MAX_TERM_COLS : n;
+}
+
+export interface ShutdownRequest {
+  v: number;
+  kind: "shutdown";
+}
+
+export interface ClickRequest {
+  v: number;
+  kind: "click";
+  verb: string;
+  value: string;
+}
+
+export interface StatsRequest {
+  v: number;
+  kind: "stats";
+}
+
+// [LAW:types-are-the-program] The `what` discriminator carries the response
+// shape forward — a client requesting "vars" gets vars data, "segments" gets
+// segments data, "config" gets config data. No string-keyed lookup on the
+// client side; route by structure. See DebugSnapshot in ./debug-types.
+export interface DebugRequest {
+  v: number;
+  kind: "debug";
+  what: DebugWhat;
+}
+
+export type Request =
+  | RenderRequest
+  | ShutdownRequest
+  | StatsRequest
+  | ClickRequest
+  | DebugRequest;
+
+export type Response =
+  | { ok: true; output: string }
+  | { ok: true; stats: StatsSnapshot }
+  // [LAW:types-are-the-program] DebugSnapshot is itself a discriminated union
+  // on `what`, so the response type carries the requested kind through to the
+  // client. A `{ ok: true; debug: { what: "vars"; vars: [...] } }` shape is
+  // self-describing — the client doesn't need to remember which `what` it sent.
+  | { ok: true; debug: DebugSnapshot }
+  // [LAW:types-are-the-program] `daemonV` is the daemon's own
+  // PROTOCOL_VERSION, echoed on every error response so the client can render
+  // a meaningful diagnostic on VERSION_MISMATCH without parsing the human
+  // message. Optional for back-compat: older daemons (or test stubs) that
+  // omit it are still parseable by current clients.
+  | { ok: false; error: string; code: ErrorCode; daemonV?: number };
+
+// [LAW:types-are-the-program] The wire-level discriminator splits failures
+// into two recovery classes: TIMEOUT is transient — the daemon is alive but
+// slow, so a respawn or retry has a real chance of recovering. Every other
+// code is permanent — respawning would hit the same response identically
+// (the daemon refuses the request for VERSION_MISMATCH or BAD_REQUEST, or
+// fails internally for RENDER_FAILED in a way the spawn loop cannot cure),
+// so the spiral-breaker contract requires the client NOT to kick. The
+// kick-vs-no-kick decision is encoded off this code, not off the error
+// string.
+export type ErrorCode =
+  | "VERSION_MISMATCH"
+  | "TIMEOUT"
+  | "RENDER_FAILED"
+  | "BAD_REQUEST";
+
+// [LAW:types-are-the-program] A typed error class for failures that originate
+// inside the wire-protocol layer (oversized frame, JSON decode failure).
+// Callers in src/daemon/client-transport.ts branch on `e instanceof ProtocolError`
+// to classify these as `permanent/malformed_response` — far more robust than
+// substring-matching against the message, which would silently drift if
+// Node's JSON.parse error wording changes. The class is small but
+// load-bearing: it makes the kick-vs-show-error decision a structural
+// property of the thrown value, not a property of its english string.
+export class ProtocolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProtocolError";
+  }
+}
+
+// 4-byte big-endian length prefix + UTF-8 JSON body. Length-prefix beats
+// newline-delimited because error messages may contain embedded newlines and
+// we'd rather not parse them out of-band.
+//
+// [LAW:one-source-of-truth] FRAME_HEADER_BYTES and MAX_FRAME_BYTES are part
+// of the wire contract the Rust client mirrors (rust-client/src/main.rs);
+// scripts/check-protocol.mjs diffs them, so they must stay named consts.
+export const FRAME_HEADER_BYTES = 4;
+export const MAX_FRAME_BYTES = 16 * 1024 * 1024;
+
+export function encodeFrame(value: unknown): Buffer {
+  const body = Buffer.from(JSON.stringify(value), "utf8");
+  const header = Buffer.alloc(FRAME_HEADER_BYTES);
+  header.writeUInt32BE(body.length, 0);
+  return Buffer.concat([header, body]);
+}
+
+// Streaming frame reader. Calls `onFrame` for each complete frame. Caller
+// owns lifecycle — call `feed` with each chunk; reader keeps a buffer.
+export function makeFrameReader(
+  onFrame: (frame: unknown) => void,
+  onError: (err: Error) => void,
+) {
+  let buf = Buffer.alloc(0);
+  return function feed(chunk: Buffer): void {
+    buf = Buffer.concat([buf, chunk]);
+    while (buf.length >= FRAME_HEADER_BYTES) {
+      const len = buf.readUInt32BE(0);
+      // Hard cap to defend against a runaway sender allocating gigabytes.
+      // [LAW:types-are-the-program] ProtocolError carries the discriminator
+      // structurally — interpretException routes on `instanceof`, not on a
+      // brittle string match against the message body.
+      if (len > MAX_FRAME_BYTES) {
+        onError(new ProtocolError(`frame too large: ${len}`));
+        return;
+      }
+      if (buf.length < FRAME_HEADER_BYTES + len) return;
+      const body = buf.subarray(FRAME_HEADER_BYTES, FRAME_HEADER_BYTES + len);
+      buf = buf.subarray(FRAME_HEADER_BYTES + len);
+      try {
+        onFrame(JSON.parse(body.toString("utf8")));
+      } catch (e) {
+        // JSON.parse throws SyntaxError; wrap as ProtocolError so the
+        // recovery class is structurally typed (not message-matched).
+        // Preserve the original cause for diagnostic logging.
+        const wrapped = new ProtocolError(
+          e instanceof Error ? e.message : String(e),
+        );
+        if (e instanceof Error) {
+          wrapped.cause = e;
+        }
+        onError(wrapped);
+        return;
+      }
+    }
+  };
+}
+
+// Send one frame and await one response, with a hard total budget. Resolves
+// to the parsed response or rejects on timeout / parse error / socket error.
+export function sendOne(
+  sock: Socket,
+  req: Request,
+  totalBudgetMs: number,
+): Promise<Response> {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      sock.removeAllListeners();
+      try {
+        fn();
+      } catch {}
+    };
+    const timer = setTimeout(() => {
+      finish(() => {
+        sock.destroy();
+        reject(new Error("TIMEOUT"));
+      });
+    }, totalBudgetMs);
+
+    const reader = makeFrameReader(
+      (frame) => finish(() => resolve(frame as Response)),
+      (err) => finish(() => reject(err)),
+    );
+    sock.on("data", reader);
+    sock.on("error", (err) => finish(() => reject(err)));
+    sock.on("close", () =>
+      finish(() => reject(new Error("socket closed before response"))),
+    );
+
+    sock.write(encodeFrame(req));
+  });
+}