@promptctl/cc-candybar 1.26.0 → 1.27.0

package/src/daemon/config-overrides-store.ts

@@ -0,0 +1,322 @@
+// [LAW:one-source-of-truth] The daemon is the SOLE writer of
+// configOverridesPath() — the hand-authored user config file is never
+// machine-edited (candybar-config-engine-71o's binding guardrail). A
+// persistent config write (the `persist` action, distinct from `set`'s
+// per-session write) lands here; RenderCache merges it on top of the user
+// file every reload (src/daemon/cache/render.ts), so this module owns only
+// the read/write/shape of the override layer, never the merge.
+//
+// [LAW:single-enforcer] Read-modify-write + atomic rename, synchronous. Writes
+// here are click-rate (rare), not render-rate (SessionState's every-render
+// atom) — there is no debounce to coalesce and no in-memory cache to keep
+// warm; RenderCache re-reads this file fresh on every reload, exactly as it
+// re-reads the user config file. One source, read where it's needed.
+//
+// [LAW:one-source-of-truth] The file is ONE flat dict keyed by whatever
+// string a `persist`/`reset` action names (candybar-config-engine-71o.6
+// generalized this from Globals-only fields to also admit
+// `segments.<name>.palette` keys — see loader/persist-target.ts, the shared
+// parser both this module and cross-ref.ts classify a key through). Keeping
+// ONE flat dict (rather than a nested `{globals, segments}` shape) means the
+// read-modify-write/atomic-rename plumbing below never needed to change
+// shape — only what keys/values count as valid grew.
+
+import fs from "node:fs";
+import path from "node:path";
+import type { Globals } from "../config/dsl-types.js";
+import { isGlobalsField } from "../config/loader/globals.js";
+import { parsePersistTarget } from "../config/loader/persist-target.js";
+import { debug } from "../utils/logger.js";
+import type { DaemonLogger } from "./log.js";
+
+const quietLogger: DaemonLogger = (_level, message) => debug(message);
+
+// [LAW:one-source-of-truth] Re-exported so every existing importer
+// (verbs/index.ts, verbs/config-validators.ts) keeps reading membership
+// through this module — but the membership check itself now has exactly ONE
+// implementation (loader/globals.ts's isGlobalsField, derived from
+// GLOBALS_SCHEMA), not two independently-authored tables that TypeScript's
+// per-table exhaustiveness only coincidentally kept in agreement.
+export { isGlobalsField } from "../config/loader/globals.js";
+
+// [LAW:types-are-the-program] Every Globals field's primitive WIRE TYPE,
+// keyed by `keyof Globals` — TypeScript forces this map to stay total over
+// Globals, so a field added to/removed from that interface is a compile
+// error here until this table is updated. This is the ONE place a `persist`
+// write's canonical string is coerced to the JS type Globals actually
+// declares (padding: number, autoWrap: boolean, everything else: string). A
+// segment-palette target has no matching row: it's always a NAME, so its
+// kind is "string" unconditionally — see coercePersistValue below. Membership
+// (which keys exist) is NOT re-declared here — see the re-exported
+// isGlobalsField above; this table only adds the per-field KIND membership
+// alone doesn't carry.
+const GLOBALS_FIELD_KIND: Readonly<
+  Record<keyof Globals, "string" | "number" | "boolean">
+> = {
+  default_bg: "string",
+  default_fg: "string",
+  default_empty_value: "string",
+  default_separator: "string",
+  default_truncate_marker: "string",
+  palette: "string",
+  look: "string",
+  // The active arrangement — a NAME like palette/look, so `persist: "preset"`
+  // makes a chosen preset the default every future session opens in.
+  preset: "string",
+  style: "string",
+  autoWrap: "boolean",
+  padding: "number",
+  charset: "string",
+  colorCompatibility: "string",
+};
+
+// [LAW:one-source-of-truth] The same four canonical boolean-ish inputs
+// validateBoolean (state-validators.ts) accepts — a `persist` action's gate
+// is an ALLOW-LIST (the declared `to`/`cycle` members pass through
+// membership-checked but otherwise VERBATIM, unlike validateBoolean's own
+// bespoke normalization), so a config author writing `cycle: ["true",
+// "false"]` or `to: "0"` reaches this boundary with the raw member string,
+// not a pre-canonicalized "1"/"". This is the ONE place that must accept the
+// full accepted-input set, not just the canonical pair.
+const BOOLEAN_TRUTHY = new Set(["1", "true"]);
+const BOOLEAN_FALSY = new Set(["0", "false", ""]);
+
+// [LAW:no-silent-fallbacks] The `persist` write's validator canonicalizes to
+// a STRING (the same wire currency `set` uses) — this is the boundary that
+// lifts it into the typed value its scope declares. An out-of-range/non-
+// numeric string for a "number" Globals field is a caller bug (the range
+// validator already canonicalized it), so it throws loudly rather than
+// writing a silently-wrong type into the overrides file. Replaces the old
+// Globals-only `coerceGlobalsValue`: a bare `string` key (not `keyof
+// Globals`) so a caller no longer needs a type-narrowing assertion before
+// calling this — parsePersistTarget does the classification internally.
+export function coercePersistValue(
+  key: string,
+  raw: string,
+): string | number | boolean {
+  const target = parsePersistTarget(key);
+  if (target === null) {
+    throw new Error(
+      `coercePersistValue: "${key}" is not a valid persist target`,
+    );
+  }
+  if (target.scope === "segment-palette") return raw;
+  const kind = GLOBALS_FIELD_KIND[target.field];
+  if (kind === "string") return raw;
+  if (kind === "number") {
+    const n = Number(raw);
+    if (!Number.isFinite(n)) {
+      throw new Error(
+        `coercePersistValue: "${key}" expects a number, got "${raw}"`,
+      );
+    }
+    return n;
+  }
+  if (BOOLEAN_TRUTHY.has(raw)) return true;
+  if (BOOLEAN_FALSY.has(raw)) return false;
+  throw new Error(
+    `coercePersistValue: "${key}" expects boolean-ish (1, 0, true, false), got "${raw}"`,
+  );
+}
+
+// [LAW:no-silent-failure] Missing/corrupt/wrong-shape file → the empty
+// override set is the *defined* recovery (identical to a first-ever boot),
+// not a hidden fallback to different data. Every present key is classified
+// through parsePersistTarget (globals field or segment-palette) and its
+// value checked against that target's kind; a single malformed entry drops
+// the WHOLE file back to empty (mirrors FileSessionStorage's all-or-nothing
+// shape check) rather than guessing which entries to keep.
+function isValidOverrides(
+  value: unknown,
+): value is Readonly<Record<string, string | number | boolean>> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  for (const [key, v] of Object.entries(value)) {
+    const target = parsePersistTarget(key);
+    if (target === null) return false;
+    const kind =
+      target.scope === "segment-palette"
+        ? "string"
+        : GLOBALS_FIELD_KIND[target.field];
+    if (kind === "number" && typeof v !== "number") return false;
+    if (kind === "boolean" && typeof v !== "boolean") return false;
+    if (kind === "string" && typeof v !== "string") return false;
+  }
+  return true;
+}
+
+// [LAW:single-enforcer] The ONE reader of the on-disk shape — every scoped
+// view (loadConfigOverrides, loadSegmentPaletteOverrides) and every writer
+// (writeConfigOverride, clearConfigOverride) reads through this, so the
+// flat-dict shape and its recovery-to-empty behavior are decided exactly once.
+function loadRawOverrides(
+  filePath: string,
+  logger: DaemonLogger,
+): Readonly<Record<string, string | number | boolean>> {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(filePath, "utf8");
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") {
+      logger("warn", `config-overrides read failed (${code}); starting empty`);
+    }
+    return {};
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (isValidOverrides(parsed)) return parsed;
+    logger("warn", `config-overrides load: unexpected shape, starting empty`);
+    return {};
+  } catch {
+    logger("warn", `config-overrides load: corrupt JSON, starting empty`);
+    return {};
+  }
+}
+
+// [LAW:one-source-of-truth] The Globals-scoped VIEW of a raw dict — kept as
+// `Partial<Globals>` so every existing caller (RenderCache's
+// mergeWithDefault({globals: ...}), stepConfig's range-seed lookup) keeps its
+// original, precisely-typed contract unchanged. Segment-palette entries in
+// the same file are invisible here by construction (isGlobalsField filters
+// them out) — see projectSegmentPaletteOverrides for that half. A pure
+// projection over an already-read dict (not a filePath) so a caller wanting
+// BOTH views (loadOverrides below) pays for exactly one read.
+//
+// [LAW:no-defensive-null-guards] exception: `Object.create(null)` — the key
+// being assigned comes from the on-disk overrides file, which a `persist`
+// write only ever populates from a real Globals field name (isGlobalsField
+// already excludes "__proto__"), but the accumulator itself gets the same
+// null-prototype hygiene src/dsl/render.ts's segment-keyed accumulator uses
+// ("segment names come from user config; a null-prototype object prevents
+// __proto__/constructor/prototype from being treated as segment data") —
+// one guard at the object, not a per-caller property-name check.
+function projectGlobalsOverrides(
+  raw: Readonly<Record<string, string | number | boolean>>,
+): Partial<Globals> {
+  const out: Record<string, string | number | boolean> = Object.create(
+    null,
+  ) as Record<string, string | number | boolean>;
+  for (const [key, value] of Object.entries(raw)) {
+    if (isGlobalsField(key)) out[key] = value;
+  }
+  // [LAW:no-silent-fallbacks] exception: isValidOverrides already proved every
+  // entry's runtime kind matches its target's declared kind (GLOBALS_FIELD_KIND)
+  // before it ever reached the file — this cast states that proof, it doesn't
+  // paper over an unchecked one.
+  return out as Partial<Globals>;
+}
+
+// [LAW:one-source-of-truth] The segment-palette-scoped VIEW of the SAME raw
+// dict — segment name -> persisted palette name. RenderCache overlays this
+// onto the already-merged config's `segments[name].palette` field
+// (applySegmentPaletteOverrides in config/loader/merge.ts), never through
+// mergeWithDefault's wholesale per-name segment replacement.
+//
+// [LAW:no-defensive-null-guards] exception: `Object.create(null)` — unlike
+// projectGlobalsOverrides, the assigned key here (`target.segment`) is NOT
+// membership-checked against any closed set before the write (any string a
+// config declares as a segment name is legal), so a segment genuinely named
+// `__proto__` would otherwise hit the prototype setter on `out[key] =` —
+// the exact crash class the render.ts precedent (see above) already guards
+// against for segment-keyed objects.
+function projectSegmentPaletteOverrides(
+  raw: Readonly<Record<string, string | number | boolean>>,
+): Readonly<Record<string, string>> {
+  const out: Record<string, string> = Object.create(null) as Record<
+    string,
+    string
+  >;
+  for (const [key, value] of Object.entries(raw)) {
+    const target = parsePersistTarget(key);
+    if (target?.scope === "segment-palette" && typeof value === "string") {
+      out[target.segment] = value;
+    }
+  }
+  return out;
+}
+
+export function loadConfigOverrides(
+  filePath: string,
+  logger: DaemonLogger = quietLogger,
+): Partial<Globals> {
+  return projectGlobalsOverrides(loadRawOverrides(filePath, logger));
+}
+
+export function loadSegmentPaletteOverrides(
+  filePath: string,
+  logger: DaemonLogger = quietLogger,
+): Readonly<Record<string, string>> {
+  return projectSegmentPaletteOverrides(loadRawOverrides(filePath, logger));
+}
+
+// [LAW:carrying-cost] RenderCache wants BOTH views on every reload
+// (buildState merges globals overrides, then overlays segment-palette
+// overrides) — calling loadConfigOverrides + loadSegmentPaletteOverrides
+// back to back would read, parse, and shape-validate the same tiny file
+// twice per reload for no reason. One read, two projections.
+export interface Overrides {
+  readonly globals: Partial<Globals>;
+  readonly segmentPalette: Readonly<Record<string, string>>;
+}
+
+export function loadOverrides(
+  filePath: string,
+  logger: DaemonLogger = quietLogger,
+): Overrides {
+  const raw = loadRawOverrides(filePath, logger);
+  return {
+    globals: projectGlobalsOverrides(raw),
+    segmentPalette: projectSegmentPaletteOverrides(raw),
+  };
+}
+
+// [LAW:no-silent-failure] Atomic write shared by set/clear: read the current
+// overrides, apply one mutation, write-to-temp + rename. Owner-only mode,
+// matching every other daemon runtime file (session-state.json, pid, lease).
+// Unlike session-state.json's debounced best-effort flush (no synchronous
+// caller waiting on it), a `persist` write is directly caused by a click that
+// expects a truthful ack — a swallowed failure here would let the verb
+// handler log "set-config: ..." as if it landed when nothing was written.
+// Logs at "error" for the daemon-log breadcrumb, then RETHROWS so the caller
+// (the click) fails loudly instead of claiming a success that didn't happen.
+function writeOverrides(
+  filePath: string,
+  overrides: Readonly<Record<string, string | number | boolean>>,
+  logger: DaemonLogger,
+): void {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(overrides), { mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, filePath);
+  } catch (e) {
+    const message = `config-overrides write failed: ${(e as Error).message}`;
+    logger("error", message);
+    throw new Error(message);
+  }
+}
+
+export function writeConfigOverride(
+  filePath: string,
+  key: string,
+  value: string | number | boolean,
+  logger: DaemonLogger = quietLogger,
+): void {
+  const overrides = loadRawOverrides(filePath, logger);
+  writeOverrides(filePath, { ...overrides, [key]: value }, logger);
+}
+
+export function clearConfigOverride(
+  filePath: string,
+  key: string,
+  logger: DaemonLogger = quietLogger,
+): void {
+  const overrides = loadRawOverrides(filePath, logger);
+  if (!(key in overrides)) return;
+  const next = { ...overrides };
+  delete next[key];
+  writeOverrides(filePath, next, logger);
+}

package/src/daemon/paths.ts

@@ -149,6 +149,16 @@ export function sessionStatePath(): string {
   return path.join(stateDir(), "session-state.json");
 }
 
+// [LAW:one-source-of-truth] The daemon-owned overrides layer for persistent
+// config writes (candybar-config-engine-71o.2): a click that mutates the
+// bundled/user-file DEFAULT (as opposed to `set`, which mutates per-session
+// state) lands here — never in the hand-authored config file itself. Sibling
+// of sessionStatePath(): same root, same single-writer daemon, same test
+// isolation via XDG_STATE_HOME/CC_CANDYBAR_SOCKET-derived overrides.
+export function configOverridesPath(): string {
+  return path.join(stateDir(), "config-overrides.json");
+}
+
 // [LAW:one-source-of-truth] The fork-bomb breaker's daemon-population registry
 // (fork-bomb-breaker.ts) shares socketPath()'s UID-anchored /tmp root and, like
 // it, deliberately ignores XDG_STATE_HOME — the very isolation

package/src/daemon/render-payload.ts

@@ -33,6 +33,40 @@ import type { ContextProvider } from "../segments/context.js";
 import type { MetricsProvider } from "../segments/metrics.js";
 import type { TmuxService } from "../segments/tmux.js";
 import type { GitDataProvider } from "./cache/git.js";
+import type {
+  Charset,
+  ColorCompatibility,
+  StripStyle,
+} from "../themes/policy.js";
+
+// ─── Effective globals ─────────────────────────────────────────────────────
+
+// [LAW:one-source-of-truth] The daemon resolves each of these exactly ONCE
+// per render (server.ts, before both the payload build and renderDsl's
+// BuildLineOptions), so the value a trigger label displays and the value
+// that actually shaped the render can never disagree — the same reasoning
+// theme/look already followed, generalized to every globals field a menu or
+// stepper can persist. `theme`/`look`/`style` compose SessionState over the
+// config default (a session pick can diverge from the persisted default for
+// its own session); `charset`/`colorCompatibility`/`autoWrap`/`padding` have
+// no SessionState half today, so their "effective" value is just the
+// resolved config global over its floor constant.
+export interface EffectiveGlobals {
+  readonly theme: string;
+  readonly look: string;
+  // The active PRESET name — effectivePresetName(sessionState.preset,
+  // globals.preset, presets), collapsed to the floor if stale. Unlike every
+  // other field here it is not itself a display value: it is the name of the
+  // fragment whose `globals` were merged to PRODUCE the rest of this struct,
+  // carried alongside so a menu label states the arrangement that actually
+  // rendered [LAW:one-source-of-truth].
+  readonly preset: string;
+  readonly style: StripStyle;
+  readonly charset: Charset;
+  readonly colorCompatibility: ColorCompatibility;
+  readonly autoWrap: boolean;
+  readonly padding: number;
+}
 
 // ─── Augmented payload shape ─────────────────────────────────────────────────
 
@@ -69,6 +103,29 @@ export interface RenderPayload extends ClaudeHookData {
   // rendered palette, surfaced so a trigger label can display the active look.
   // Required for the same reason as theme: resolved unconditionally per render.
   readonly look: { readonly effective: string };
+  // [LAW:one-type-per-behavior] The daemon-resolved effective PRESET name —
+  // effectivePresetName(sessionState.preset, globals.preset, presets) — theme
+  // and look's twin one level up: the SAME name that selected the layout this
+  // render walked and the globals it rendered with, surfaced so a preset
+  // trigger's label can never claim an arrangement the bar is not in.
+  readonly preset: { readonly effective: string };
+  // [LAW:one-type-per-behavior] style/charset/colorCompatibility/autoWrap/
+  // padding are theme/look's twins over the remaining persistable globals
+  // (candybar-config-engine-71o.3) — each REQUIRED and unconditionally
+  // present for the same reason: the daemon already resolves the value for
+  // BuildLineOptions every render, and this is that exact value, so a
+  // trigger's "current selection" highlight and the render it describes
+  // trace to one resolution. See EffectiveGlobals for how each is derived.
+  // [LAW:types-are-the-program] Unlike theme/look (open, registry-extensible
+  // names with no closed union to narrow to), style/charset/colorCompatibility
+  // DO have one (StripStyle/Charset/ColorCompatibility) — narrowed to it
+  // rather than widened to `string`, so a downstream `switch` over these
+  // fields gets real exhaustiveness checking.
+  readonly style: { readonly effective: StripStyle };
+  readonly charset: { readonly effective: Charset };
+  readonly colorCompatibility: { readonly effective: ColorCompatibility };
+  readonly autoWrap: { readonly effective: boolean };
+  readonly padding: { readonly effective: number };
 
   // Usage-family. Each provider returns null when it has no data (no
   // transcript yet, no rate-limit window active, etc.); we drop the field
@@ -99,6 +156,10 @@ export interface RenderPayload extends ClaudeHookData {
 // between "no stashes" and "stash count unknown because git failed".
 export interface GitPayload {
   readonly repoName?: string;
+  // The repo's browsable web page (an https/http URL, credentials stripped),
+  // derived from the same remotes read `repoName` is. Missing = the repo has no
+  // remote a browser can open, so a template gates its link on `ne … ""`.
+  readonly repoUrl?: string;
   readonly branch?: string;
   readonly sha?: string;
   readonly ahead?: number;
@@ -537,6 +598,7 @@ function gitOptionsFromClosure(needed: ReadonlySet<string>): GitInfoOptions {
     ...(has("git.stash") && { showStashCount: true }),
     ...(has("git.upstream") && { showUpstream: true }),
     ...(has("git.repoName") && { showRepoName: true }),
+    ...(has("git.repoUrl") && { showRepoUrl: true }),
     ...(has("git.operation") && { showOperation: true }),
     ...(has("git.timeSinceCommit") && { showTimeSinceCommit: true }),
     // Any PR field laid out turns on the (network) forge lookup. Keep these in
@@ -581,18 +643,14 @@ export async function buildRenderPayload(
   // registration; passing it in (rather than recomputing per render) keeps
   // the hot path free of the BFS + extractTemplateRefs cost.
   neededInputPaths: ReadonlySet<string>,
-  // [LAW:one-source-of-truth] The effective theme name, resolved ONCE by the
-  // daemon (effectiveThemeName(sessionState.theme, globals.palette)) and used
-  // for BOTH the rendered basePalette and this payload field — so a trigger
-  // label reading `.theme.effective` can never disagree with the colors. Passed
-  // in (not re-resolved here) because the daemon already computes it for the
-  // palette; this is that same value, threaded to the sole payload assembler.
-  effectiveTheme: string,
-  // [LAW:one-source-of-truth] The effective look name, resolved ONCE by the
-  // daemon beside the theme (effectiveLookName over SessionState/globals/looks)
-  // and used for BOTH the rendered adaptation and this payload field — so a
-  // trigger label reading `.look.effective` can never disagree with the colors.
-  effectiveLook: string,
+  // [LAW:one-source-of-truth] Every globals field a menu/stepper can persist,
+  // resolved ONCE by the daemon (server.ts, before both this call and the
+  // BuildLineOptions it renders with) and used for BOTH the actual render AND
+  // these payload fields — so a trigger label can never disagree with what
+  // was actually rendered. Passed in (not re-resolved here) because the
+  // daemon already computes every one of these for renderDsl's options; this
+  // is that same struct, threaded to the sole payload assembler.
+  effective: EffectiveGlobals,
 ): Promise<RenderPayload> {
   const wants = (prefix: string): boolean =>
     anyPathStartsWith(neededInputPaths, prefix);
@@ -794,13 +852,18 @@ export async function buildRenderPayload(
     ...(home !== undefined && { home }),
     ...(gitProjection.git !== undefined && { git: gitProjection.git }),
     ...(tmuxValue !== undefined && { tmux: { session: tmuxValue } }),
-    // [LAW:one-source-of-truth] Always present — the daemon resolves the
-    // effective theme every render (for basePalette), and this is that value.
-    // No `wants` gate: it costs nothing (a string already in hand) and a
-    // config that reads `.theme.effective` must always find it.
-    theme: { effective: effectiveTheme },
-    // Same contract as theme: always present, a string already in hand.
-    look: { effective: effectiveLook },
+    // [LAW:one-source-of-truth] Always present — the daemon resolves every
+    // one of these each render (for BuildLineOptions/basePalette), and these
+    // are those exact values. No `wants` gate: each costs nothing (already in
+    // hand) and a config reading e.g. `.padding.effective` must always find it.
+    theme: { effective: effective.theme },
+    look: { effective: effective.look },
+    preset: { effective: effective.preset },
+    style: { effective: effective.style },
+    charset: { effective: effective.charset },
+    colorCompatibility: { effective: effective.colorCompatibility },
+    autoWrap: { effective: effective.autoWrap },
+    padding: { effective: effective.padding },
     ...(sessionPayload !== undefined && { session: sessionPayload }),
     ...(todayPayload !== undefined && { today: todayPayload }),
     ...(costPerHour !== undefined && { burn: { costPerHour } }),
@@ -904,6 +967,7 @@ function projectGitInfo(outcome: Outcome<GitInfo>): {
   const stash = field("stash", info.stashCount);
   const upstream = field("upstream", info.upstream);
   const repoName = field("repoName", info.repoName);
+  const repoUrl = field("repoUrl", info.repoUrl);
 
   // [LAW:no-silent-failure] The PR deliberately breaks the `field` pattern: a
   // `failed` lookup is NOT dropped to a missing key (which the template can't
@@ -947,6 +1011,7 @@ function projectGitInfo(outcome: Outcome<GitInfo>): {
       ...(stash !== undefined && { stash }),
       ...(upstream !== undefined && { upstream }),
       ...(repoName !== undefined && { repoName }),
+      ...(repoUrl !== undefined && { repoUrl }),
       ...prFields,
     },
     failures,