@promptctl/cc-candybar 1.0.0

package/src/index.ts

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+import type { ClaudeHookData } from "./utils/claude";
+
+import process from "node:process";
+import { json } from "node:stream/consumers";
+import { debug } from "./utils/logger";
+import { runInstall, runInstallUrlHandler, runUrlHandle } from "./install";
+import { runDaemon } from "./daemon/server";
+import { tryRenderViaDaemon } from "./daemon/client";
+import { runDaemonStats } from "./daemon/client-stats";
+import { runDebug } from "./daemon/client-debug";
+import { isDebugWhat } from "./daemon/debug-types";
+import { runLint, runSchema } from "./config/cli";
+import { obtainDaemonKick } from "./daemon/acquire";
+import { planOutcome } from "./render/outcome-plan";
+
+// Read terminal width from the live shell context (no subprocess). Returns
+// undefined when nothing reliable is available; the daemon falls back to its
+// own pure lookup chain in that case. Always-COLUMNS-first because Bash
+// exports it on resize and Claude Code propagates it to hook commands.
+// stderr (not stdout) is the TTY-side fallback: when invoked as a Claude
+// statusline hook, stdin is the hook JSON pipe and stdout is the captured
+// statusline pipe, leaving stderr as the only stream still attached to the
+// parent terminal. Mirrors the Rust client's TIOCGWINSZ-on-STDERR_FILENO.
+function detectTermCols(): number | undefined {
+  const env = process.env.COLUMNS;
+  if (env) {
+    const n = parseInt(env, 10);
+    if (!isNaN(n) && n > 0) return n;
+  }
+  const cols = process.stderr.columns;
+  if (cols && cols > 0) return cols;
+  return undefined;
+}
+
+function showHelpText(): void {
+  console.log(`
+cc-candybar - Beautiful powerline statusline for Claude Code
+
+Usage: cc-candybar [options]
+
+Standalone Commands:
+  -h, --help               Show this help
+
+Debugging:
+  CC_CANDYBAR_DEBUG=1      Enable debug logging for troubleshooting
+
+Configuration:
+  Layout and segment options are defined in .cc-candybar.json5 (place in your
+  project dir, cwd, or ~/.config/cc-candybar/config.json5). Use CC_CANDYBAR_CONFIG
+  to point at a specific file. See the default config for all available options:
+    node dist/index.mjs debug --project-dir . --cwd .
+
+Subcommands (macOS):
+  install                  One-shot setup: creates the URL handler app, registers
+                           the cc-candybar:// scheme, and writes the statusLine
+                           command into ~/.claude/settings.json.
+  install-url-handler      Just create + register the URL handler app
+                           (~/Applications/CCCandybarURLHandler.app).
+  url-handle URL           Internal — invoked by the URL handler app on
+                           cmd-click. Parses cc-candybar://<verb>/<value> and
+                           dispatches (currently: copy to clipboard).
+  daemon-stats [--json]    Query the running daemon for runtime stats:
+                           uptime, RSS, cache hit rates, watcher count,
+                           request totals. Does not spawn a daemon.
+
+Config tooling:
+  lint <config-file>       Validate a config file (parse + cross-refs + cycles)
+                           with no daemon. Exit 0 valid, 1 invalid, 2 unreadable.
+  schema                   Print the JSON Schema for the config file shape
+                           (.cc-candybar.json5). Point an editor's $schema at it
+                           for autocomplete + structural validation.
+  vars [--json]            Declared variables: source kind, value, last error.
+  segments [--json]        Segment templates and their last rendered output.
+  config [--json]          The effective merged config. (All three query the
+                           running daemon; none spawn one.)
+
+`);
+}
+
+async function main(): Promise<void> {
+  try {
+    const showHelp =
+      process.argv.includes("--help") || process.argv.includes("-h");
+
+    if (showHelp) {
+      showHelpText();
+      process.exit(0);
+    }
+
+    // [LAW:dataflow-not-control-flow] Subcommand dispatch is data: argv[2]
+    // selects the handler. Each handler short-circuits via process.exit().
+    // Default fallthrough = the existing stdin-driven render flow.
+    const subcommand = process.argv[2];
+    if (subcommand === "install") {
+      runInstall(process.argv.slice(3));
+      process.exit(0);
+    }
+    if (subcommand === "install-url-handler") {
+      runInstallUrlHandler();
+      process.exit(0);
+    }
+    if (subcommand === "url-handle") {
+      await runUrlHandle(process.argv[3]);
+      return;
+    }
+    if (subcommand === "daemon") {
+      runDaemon();
+      return; // daemon owns its own lifecycle
+    }
+    if (subcommand === "daemon-stats") {
+      await runDaemonStats(process.argv.slice(3));
+      process.exit(0);
+    }
+    if (subcommand === "lint") {
+      runLint(process.argv.slice(3)); // owns its own exit code (0/1/2)
+      return;
+    }
+    if (subcommand === "schema") {
+      runSchema(); // owns its own exit code
+      return;
+    }
+    // [LAW:dataflow-not-control-flow] vars/segments/config are ONE handler
+    // parameterized by `what` — the subcommand name IS the DebugWhat. The guard
+    // is the canonical list (debug-types), so a new debug projection is reachable
+    // here with no second-site edit.
+    if (isDebugWhat(subcommand)) {
+      await runDebug(subcommand, process.argv.slice(3));
+      process.exit(0);
+    }
+
+    if (process.stdin.isTTY === true) {
+      console.error(`Error: This tool requires input from Claude Code
+
+cc-candybar is designed to be used as a Claude Code statusLine command.
+It reads hook data from stdin and outputs formatted statusline.
+
+Add to ~/.claude/settings.json:
+{
+  "statusLine": {
+    "type": "command",
+    "command": "cc-candybar --style=powerline"
+  }
+}
+
+Run with --help for more options.
+
+To test output manually:
+echo '{"session_id":"test-session","workspace":{"project_dir":"/path/to/project"},"model":{"id":"claude-sonnet-4-5","display_name":"Claude"}}' | cc-candybar --style=powerline`);
+      process.exit(1);
+    }
+
+    debug(`Working directory: ${process.cwd()}`);
+    debug(`Process args:`, process.argv);
+
+    const hookData = (await json(process.stdin)) as ClaudeHookData;
+    debug(`Received hook data:`, JSON.stringify(hookData, null, 2));
+
+    if (!hookData) {
+      console.error("Error: No input data received from stdin");
+      showHelpText();
+      process.exit(1);
+    }
+
+    // [LAW:one-source-of-truth] The daemon is the *only* renderer. The CLI is
+    // a dumb relay: forward stdin to the daemon, print whatever comes back.
+    // There is no inline render path — two renderers would drift (the CLI has
+    // no shared gitService/usageProvider, no per-session state, no warm
+    // caches). On daemon miss we spawn detached and emit empty output; the
+    // next status-line refresh hits the warm daemon and renders for real.
+    //
+    // [LAW:single-enforcer] Terminal width is captured here, in the user's
+    // shell environment, then trusted by the daemon. The daemon's own env
+    // reflects whichever shell launched it minutes/hours ago, so it can't
+    // measure the active terminal — only the live client can.
+    const outcome = await tryRenderViaDaemon(
+      hookData,
+      process.argv,
+      process.cwd(),
+      detectTermCols(),
+    );
+    // [LAW:types-are-the-program] Three variants, one per outcome kind. The
+    // "kick on every failure" pattern was the load-bearing half of the
+    // 452-corpse spiral (kz8.5) — kicking on `permanent` failures keeps
+    // respawning a daemon that will refuse the next request identically.
+    // [LAW:dataflow-not-control-flow] planOutcome maps each variant to a
+    // plan value (output, kick, debug); the side effects below run against
+    // the plan in fixed order. Variability lives in the data.
+    const plan = planOutcome(outcome);
+    if (plan.debug !== null) {
+      debug(plan.debug);
+    }
+    if (plan.kick) {
+      obtainDaemonKick();
+    }
+    process.stdout.write(plan.output);
+    process.exit(0);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    console.error("Error generating statusline:", errorMessage);
+    process.exit(1);
+  }
+}
+
+main();

package/src/install/index.ts

@@ -0,0 +1,410 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { launchSync } from "../proc/launch";
+import { tryClickViaDaemon } from "../daemon/client";
+import type { PermanentOutcome } from "../daemon/client-transport";
+import { obtainDaemonKick } from "../daemon/acquire";
+import { URL_SCHEME, VERB_COPY } from "../click/wire";
+
+// [LAW:one-source-of-truth] Replaced at build time by tsdown's `define` option
+// from package.json. The pinned version is what we write into settings.json so
+// pnpm's content-addressable cache key changes on every release — no stale
+// versions sticking around because of `@latest` resolution.
+declare const __PACKAGE_VERSION__: string;
+const PACKAGE_VERSION =
+  typeof __PACKAGE_VERSION__ !== "undefined" ? __PACKAGE_VERSION__ : "dev";
+
+const PACKAGE_NAME = "@promptctl/cc-candybar";
+const BUNDLE_ID = "com.cccandybar.url-handler";
+const APP_NAME = "CCCandybarURLHandler";
+
+// [LAW:one-source-of-truth] `install` writes no renderer flags into
+// ~/.claude/settings.json. The previous CLI override apparatus (--layout,
+// --tray, --display, --show, --segment) is gone (bzh.2). All authoring now
+// lives in `.cc-candybar.json5` or `.cc-candybar.json` (see
+// resolveDslConfigPath — both extensions are accepted, .json5 preferred);
+// the install command's job is just to wire the URL handler and the daemon
+// entry. To customize, users edit a config file at one of the resolution
+// paths or copy src/demo/statusline.json5 as a starting point.
+const DEFAULT_INSTALL_ARGS: readonly string[] = [];
+
+function shellEscape(arg: string): string {
+  // Safe characters that don't need quoting in any reasonable shell.
+  if (/^[A-Za-z0-9_./=,:-]+$/.test(arg)) return arg;
+  return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+
+function buildStatusLineCommand(rendererArgs: readonly string[]): string {
+  return [
+    "pnpm",
+    "dlx",
+    `${PACKAGE_NAME}@${PACKAGE_VERSION}`,
+    ...rendererArgs.map(shellEscape),
+  ].join(" ");
+}
+
+function appBundlePath(): string {
+  return path.join(os.homedir(), "Applications", `${APP_NAME}.app`);
+}
+
+function settingsJsonPath(): string {
+  return path.join(os.homedir(), ".claude", "settings.json");
+}
+
+function ensureMacOS(): void {
+  if (process.platform !== "darwin") {
+    throw new Error(
+      `URL handler installation requires macOS (found platform: ${process.platform}).`,
+    );
+  }
+}
+
+function supportDir(): string {
+  return path.join(
+    os.homedir(),
+    "Library",
+    "Application Support",
+    "CCCandybar",
+  );
+}
+
+function stableScriptPath(): string {
+  return path.join(supportDir(), "url-handler.mjs");
+}
+
+function appleScriptSource(
+  nodePath: string,
+  scriptPath: string,
+  nodeModulesPath: string,
+): string {
+  // [LAW:no-shared-mutable-globals] Bake absolute paths into the AppleScript
+  // so click-time invocation doesn't depend on PATH, pnpm dlx cache state, or
+  // a global npm install. The script path is a stable copy under
+  // ~/Library/Application Support/CCCandybar that we own. NODE_PATH
+  // points at the project's node_modules so the handler can resolve deps
+  // (rich-js etc.) without being co-located with a package.json.
+  const escNode = nodePath.replace(/"/g, '\\"');
+  const escScript = scriptPath.replace(/"/g, '\\"');
+  const escModules = nodeModulesPath.replace(/"/g, '\\"');
+  return [
+    "on open location L",
+    `\tdo shell script "NODE_PATH='${escModules}' '${escNode}' '${escScript}' url-handle " & quoted form of L`,
+    "end open location",
+  ].join("\n");
+}
+
+// [LAW:one-source-of-truth] The bundle that contains *this* function is
+// the thing we need to copy to a stable location. Two invocation paths
+// reach us:
+//   - via the bin shim: process.argv[1] = ".../bin/cc-candybar" which
+//     does `import '../dist/index.mjs'`. Copying the shim itself would
+//     break — its relative import wouldn't resolve from the new location.
+//     So resolve to the sibling dist/index.mjs.
+//   - direct node:      process.argv[1] = ".../dist/index.mjs". Use as-is.
+export function locateBundledDist(argv1: string | undefined): string {
+  if (!argv1) {
+    throw new Error("install-url-handler: process.argv[1] not set");
+  }
+  if (argv1.endsWith(".mjs") || argv1.endsWith(".js")) {
+    return argv1;
+  }
+  // Treat argv[1] as a bin shim and assume sibling dist/index.mjs.
+  return path.resolve(path.dirname(argv1), "..", "dist", "index.mjs");
+}
+
+function copyDistToStableLocation(): string {
+  const source = locateBundledDist(process.argv[1]);
+  if (!fs.existsSync(source)) {
+    throw new Error(
+      `install-url-handler: bundled dist not found at ${source}. Reinstall the package.`,
+    );
+  }
+  fs.mkdirSync(supportDir(), { recursive: true });
+  const dest = stableScriptPath();
+  fs.copyFileSync(source, dest);
+  return dest;
+}
+
+function infoPlistPatch(): Array<{ key: string; xml: string }> {
+  return [
+    {
+      key: "CFBundleIdentifier",
+      xml: `<string>${BUNDLE_ID}</string>`,
+    },
+    {
+      key: "CFBundleURLTypes",
+      xml: [
+        "<array>",
+        "  <dict>",
+        "    <key>CFBundleURLName</key>",
+        `    <string>Claude Powerline Click Action</string>`,
+        "    <key>CFBundleURLSchemes</key>",
+        "    <array>",
+        `      <string>${URL_SCHEME}</string>`,
+        "    </array>",
+        "  </dict>",
+        "</array>",
+      ].join("\n"),
+    },
+  ];
+}
+
+export function runInstallUrlHandler(): void {
+  ensureMacOS();
+
+  const stableScript = copyDistToStableLocation();
+  process.stdout.write(`Copied dist to ${stableScript}\n`);
+
+  // [LAW:one-source-of-truth] Derive node_modules from the source dist path
+  // (dist/index.mjs → ../node_modules). The stable copy lives elsewhere but
+  // needs the same node_modules to resolve deps at click time.
+  const sourceDist = locateBundledDist(process.argv[1]);
+  const nodeModules = path.join(path.dirname(sourceDist), "..", "node_modules");
+  if (!fs.existsSync(nodeModules)) {
+    throw new Error(
+      `install-url-handler: node_modules not found at ${nodeModules}. Install deps first.`,
+    );
+  }
+
+  const bundle = appBundlePath();
+  fs.mkdirSync(path.dirname(bundle), { recursive: true });
+
+  // If a previous handler exists, remove it so osacompile can write fresh.
+  if (fs.existsSync(bundle)) {
+    fs.rmSync(bundle, { recursive: true, force: true });
+  }
+
+  process.stdout.write(`Building ${bundle}\n`);
+  const osa = launchSync({
+    bin: "/usr/bin/osacompile",
+    args: [
+      "-o",
+      bundle,
+      "-e",
+      appleScriptSource(process.execPath, stableScript, nodeModules),
+    ],
+    category: "install.osacompile",
+  });
+  if (!osa.ok) {
+    process.stderr.write(osa.stderr);
+    throw new Error(`osacompile failed (${osa.reason})`);
+  }
+
+  const plistPath = path.join(bundle, "Contents", "Info.plist");
+
+  for (const { key } of infoPlistPatch()) {
+    // plutil errors if the key already exists; pre-delete so the operation is
+    // idempotent. Ignore failures (key may not exist on a fresh build).
+    launchSync({
+      bin: "/usr/bin/plutil",
+      args: ["-remove", key, plistPath],
+      category: "install.plutil",
+    });
+  }
+
+  for (const { key, xml } of infoPlistPatch()) {
+    const r = launchSync({
+      bin: "/usr/bin/plutil",
+      args: ["-insert", key, "-xml", xml, plistPath],
+      category: "install.plutil",
+    });
+    if (!r.ok) {
+      process.stderr.write(r.stderr);
+      throw new Error(`plutil -insert ${key} failed (${r.reason})`);
+    }
+  }
+
+  process.stdout.write(`Registering ${URL_SCHEME}:// with Launch Services\n`);
+  const lsr = launchSync({
+    bin: "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister",
+    args: ["-f", bundle],
+    category: "install.lsregister",
+  });
+  if (!lsr.ok) {
+    process.stderr.write(lsr.stderr);
+    throw new Error(`lsregister failed (${lsr.reason})`);
+  }
+
+  process.stdout.write(`✓ ${APP_NAME}.app installed and registered.\n`);
+  process.stdout.write(
+    `  Test: open '${URL_SCHEME}://hello-world' && pbpaste\n`,
+  );
+}
+
+interface ParsedUrl {
+  verb: string;
+  value: string;
+}
+
+// [LAW:dataflow-not-control-flow] Parse the URL into a {verb, value} pair
+// without using `new URL`, which lowercases hosts (would mangle case-sensitive
+// session ids). Format: cc-candybar://<verb>/<tail> | cc-candybar://<value>
+// (bare → copy). The verb ends at the FIRST `/`; everything after is the raw
+// value. The dispatch effect list rides as `dispatch/e=…&e=…`, so its query-
+// style payload is just the tail — `?` is NOT a delimiter, it is ordinary data
+// in a bare-copy value (`cc-candybar://hello?world` copies "hello?world").
+//
+// [LAW:single-enforcer] Only the VERB is decoded here. The value is passed RAW
+// to the daemon; each verb's handler decodes its own value at its boundary (the
+// verb that owns the structure owns its decode). A whole-value decode here would
+// un-escape structural separators inside a nested value — the exact hazard that
+// made compound clicks unrepresentable — so it is deliberately absent.
+export function parseHandlerUrl(
+  rawUrl: string,
+  scheme: string = URL_SCHEME,
+): ParsedUrl {
+  const prefix = `${scheme}://`;
+  if (!rawUrl.startsWith(prefix)) {
+    throw new Error(`expected ${prefix} scheme, got: ${rawUrl}`);
+  }
+  const rest = rawUrl.slice(prefix.length);
+  const slash = rest.indexOf("/");
+  if (slash === -1) {
+    return { verb: VERB_COPY, value: rest };
+  }
+  return {
+    verb: decodeURIComponent(rest.slice(0, slash)),
+    value: rest.slice(slash + 1),
+  };
+}
+
+// [LAW:single-enforcer] url-handle is a thin IPC shim: parse the URL, send
+// the click request to the daemon, exit. There is NO in-process verb
+// dispatch and NO direct disk mutation. The daemon is the only writer of
+// click-side state ([LAW:one-source-of-truth] for SessionState); kicking a
+// daemon on a transient failure is the only recovery, and it's
+// fire-and-forget so the next click hits a warm daemon.
+//
+// A `permanent` daemon outcome (BAD_REQUEST for an unknown verb,
+// VERSION_MISMATCH against a future daemon) exits non-zero with the daemon's
+// error message so the failure is visible — never silently swallowed by a
+// local fallback that would diverge from the daemon's truth.
+export async function runUrlHandle(rawUrl: string | undefined): Promise<void> {
+  if (!rawUrl) {
+    process.stderr.write("url-handle: missing URL argument.\n");
+    process.exit(1);
+  }
+
+  let parsed: ParsedUrl;
+  try {
+    parsed = parseHandlerUrl(rawUrl);
+  } catch (err) {
+    process.stderr.write(
+      `url-handle: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    process.exit(1);
+  }
+
+  const outcome = await tryClickViaDaemon(parsed.verb, parsed.value);
+  if (outcome.kind === "ok") {
+    process.exit(0);
+  }
+
+  if (outcome.kind === "transient") {
+    // [LAW:dataflow-not-control-flow] Fire-and-forget kick; the user's click
+    // is lost (the daemon couldn't service it), but the next click hits a
+    // warm daemon. Mirrors the render-path's transient recovery.
+    obtainDaemonKick();
+    process.stderr.write(
+      `url-handle: daemon unavailable (${outcome.cause}: ${outcome.message})\n`,
+    );
+    process.exit(1);
+  }
+
+  // [LAW:dataflow-not-control-flow] Format each permanent cause from its
+  // own typed payload, not by probing for "message" on a generic outcome.
+  // The PermanentOutcome union already discriminates by `cause`; the switch
+  // mirrors that discriminator one-to-one and pulls the right fields.
+  process.stderr.write(formatPermanent(outcome) + "\n");
+  process.exit(1);
+}
+
+// [LAW:single-enforcer] One place that turns a PermanentOutcome into a
+// human-readable diagnostic. Each cause carries its own payload (version
+// mismatch carries the protocol numbers; everything else carries a
+// message); the formatter consumes exactly the fields the cause defines.
+function formatPermanent(outcome: PermanentOutcome): string {
+  switch (outcome.cause) {
+    case "version_mismatch":
+      return `url-handle: daemon rejected click (version mismatch: client v${outcome.clientV} ≠ daemon v${outcome.daemonV})`;
+    case "bad_request":
+      return `url-handle: daemon rejected click (bad request: ${outcome.message})`;
+    case "render_failed":
+      return `url-handle: daemon rejected click (handler failed: ${outcome.message})`;
+    case "malformed_response":
+      return `url-handle: daemon rejected click (malformed response: ${outcome.message})`;
+  }
+}
+
+export function runInstall(rendererArgs: string[]): void {
+  ensureMacOS();
+
+  const force = rendererArgs.includes("--force");
+  const filteredArgs = rendererArgs.filter((a) => a !== "--force");
+
+  const argsToInstall =
+    filteredArgs.length > 0 ? filteredArgs : [...DEFAULT_INSTALL_ARGS];
+
+  runInstallUrlHandler();
+  updateClaudeSettings(argsToInstall, force);
+
+  process.stdout.write(`✓ install complete.\n`);
+  process.stdout.write(
+    `  Restart Claude Code to pick up the new statusline.\n`,
+  );
+}
+
+function updateClaudeSettings(
+  rendererArgs: readonly string[],
+  force: boolean,
+  overridePath?: string,
+): void {
+  const target = overridePath ?? settingsJsonPath();
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let settings: Record<string, any> = {};
+  if (fs.existsSync(target)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(target, "utf-8"));
+    } catch (err) {
+      throw new Error(
+        `Could not parse ${target}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  const existing = settings.statusLine?.command as string | undefined;
+  // [LAW:one-source-of-truth] Detection: if the existing command starts with
+  // our package prefix, we (or a prior version of us) wrote it. Any other
+  // value is a user customization we must not silently destroy.
+  const managedPrefix = `pnpm dlx ${PACKAGE_NAME}@`;
+  const isOurs =
+    typeof existing === "string" && existing.startsWith(managedPrefix);
+
+  if (existing && !isOurs && !force) {
+    process.stderr.write(
+      `Skipping settings.json update: existing statusLine.command appears customized.\n` +
+        `  Current: ${existing}\n` +
+        `  To overwrite, re-run with --force.\n`,
+    );
+    return;
+  }
+
+  settings.statusLine = {
+    type: "command",
+    command: buildStatusLineCommand(rendererArgs),
+  };
+
+  fs.writeFileSync(target, JSON.stringify(settings, null, 2));
+  process.stdout.write(`Updated ${target}\n`);
+}
+
+// Exports for testing
+export const __test__ = {
+  shellEscape,
+  buildStatusLineCommand,
+  DEFAULT_INSTALL_ARGS,
+  updateClaudeSettings,
+};