@promptctl/cc-candybar 1.41.2 → 1.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.41.2",
+  "version": "1.42.0",
   "description": "Statusline renderer for Claude Code — a JSON5-configurable DSL with daemon-cached data sources, byte-clean palette-aware composition, and OSC8 click verbs.",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -91,9 +91,9 @@
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.41.2",
-    "@promptctl/cc-candybar-darwin-x64": "1.41.2",
-    "@promptctl/cc-candybar-linux-x64": "1.41.2",
-    "@promptctl/cc-candybar-linux-arm64": "1.41.2"
+    "@promptctl/cc-candybar-darwin-arm64": "1.42.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.42.0",
+    "@promptctl/cc-candybar-linux-x64": "1.42.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.42.0"
   }
 }

package/src/cli-flags.ts

@@ -0,0 +1,8 @@
+// [LAW:one-source-of-truth] The bare flags Node answers itself. The dispatch in
+// index.ts reads it, `--help` renders its own lines from it, and the Rust client
+// routes exactly these to Node (its NODE_FLAGS; check-protocol diffs the two),
+// so a spelling added here without its mirror fails the build, not the user.
+export const NODE_FLAGS = {
+  help: ["-h", "--help"],
+  version: ["-V", "--version"],
+} as const;

package/src/daemon/cache/render.ts

@@ -61,6 +61,45 @@ export interface RenderDeps {
   watchers: WatcherRegistry;
 }
 
+// [LAW:no-ambient-temporal-coupling] The cache's outward lifecycle signal. A
+// reload is the one event the cache alone knows the completion of — it runs
+// from a debounced fs watcher, on the cache's own schedule — so anything that
+// must run AFTER a reload (an operator log of its outcome, a test asserting
+// on the state it wrote) needs the cache to say so, or it is left betting on
+// a clock. The same named-bag idiom as renderDsl's RenderObservers
+// [LAW:locality-or-seam]: a caller states what it passes by name, and a new
+// observer is one field here, not a constructor signature every caller
+// re-counts.
+export interface RenderCacheObservers {
+  // Fires once per completed reload of an entry — the initial population in
+  // getOrCreate and every watcher-driven reload alike, success (a fresh
+  // `state`) and failure (`lastError` set, prior state preserved) alike —
+  // after the entry's fields and watcher are settled. The entry is handed
+  // over as ReloadedEntry so the observer reads the outcome from the one
+  // place it lives and the type, not this comment, keeps it from writing
+  // there. Trusted non-throwing (the same contract as onSegmentError): an
+  // observer that throws is a caller bug surfaced loudly, never absorbed here.
+  readonly onReload?: (entry: ReloadedEntry) => void;
+}
+
+// [LAW:types-are-the-program] The observer's view of an entry: an ALLOW-LIST
+// of the load's outcome. Nothing that owns a resource — the watcher handle,
+// the SourceRegistry, the validator disposers, the render-cell sink — crosses
+// this seam, so a handle added to either type later is closed by
+// construction, not by remembering to omit it (`Readonly` alone would not:
+// it cannot stop a method call such as `dispose()`).
+export type ReloadedEntry = Readonly<
+  Pick<
+    CacheEntry,
+    | "projectDir"
+    | "cwd"
+    | "configFile"
+    | "configFilePath"
+    | "lastError"
+    | "lastWarning"
+  >
+> & { readonly state: Readonly<Pick<DslRenderState, "config">> | null };
+
 // [LAW:types-are-the-program] The DSL render state for an entry is one
 // optionally-null bundle, not five independently-optional fields. Either
 // every field is populated (a render is possible) or all are null (parse
@@ -154,10 +193,15 @@ export class RenderCache {
   private readonly entries = new Map<string, CacheEntry>();
   private readonly deps: RenderDeps;
   private readonly maxEntries: number;
+  private readonly observers: RenderCacheObservers;
 
-  constructor(deps: RenderDeps, opts: { maxEntries?: number } = {}) {
+  constructor(
+    deps: RenderDeps,
+    opts: { maxEntries?: number; observers?: RenderCacheObservers } = {},
+  ) {
     this.deps = deps;
     this.maxEntries = opts.maxEntries ?? MAX_ENTRIES;
+    this.observers = opts.observers ?? {};
   }
 
   // [LAW:dataflow-not-control-flow] One uniform shape: every entry has the
@@ -188,9 +232,15 @@ export class RenderCache {
       state: null,
       watcher: null,
     };
-    this.reloadInto(entry);
+    // [LAW:single-enforcer] Insert, bound, then load — in that order. From the
+    // moment the entry owns live handles it is reachable for eviction and
+    // dispose, so a throwing observer cannot strand a registry outside the
+    // map, and a reentrant getOrCreate for this key finds the entry under
+    // construction rather than building a duplicate. The bound runs before
+    // the load because it is a fact about the MAP, complete at insertion:
+    // nothing the load does (including an observer throwing) can skip it.
+    // [LAW:dataflow-not-control-flow]
     this.entries.set(key, entry);
-
     if (this.entries.size > this.maxEntries) {
       const oldest = this.entries.keys().next().value;
       if (oldest !== undefined) {
@@ -205,6 +255,7 @@ export class RenderCache {
         this.entries.delete(oldest);
       }
     }
+    this.reloadInto(entry);
 
     return entry;
   }
@@ -220,7 +271,17 @@ export class RenderCache {
   // new DslConfig disposes the old SourceRegistry before constructing a new
   // one. The registry owns timers, watchers, MobX reactions, and git
   // subscriptions — dropping it without dispose leaks every handle.
+  //
+  // [LAW:single-enforcer] One publish point for "this reload completed":
+  // loadFromDisk owns the outcome (it returns through more than one arm),
+  // and this wrapper is the only caller, so the signal structurally cannot
+  // be skipped by whichever arm a reload takes — or by an arm added later.
   private reloadInto(entry: CacheEntry): void {
+    this.loadFromDisk(entry);
+    this.observers.onReload?.(entry);
+  }
+
+  private loadFromDisk(entry: CacheEntry): void {
     const resolvedPath = resolveDslConfigPath(
       entry.projectDir,
       entry.cwd,
@@ -286,7 +347,7 @@ export class RenderCache {
   // store, registry, compiled segments, palette — as one transaction. Any
   // failure inside disposes the partially-built registry so we don't leak
   // timers/watchers from a half-constructed reload, then rethrows so the
-  // caller (reloadInto) preserves the prior `entry.state` unchanged.
+  // caller (loadFromDisk) preserves the prior `entry.state` unchanged.
   private buildState(
     entry: CacheEntry,
     resolvedPath: string | null,
@@ -396,7 +457,7 @@ export class RenderCache {
     // key) are part of the same construction transaction as the registry: any
     // failure (registration, a duplicate-key throw) disposes every handle built
     // so far — registry AND already-installed validators — before rethrowing, so
-    // reloadInto preserves the prior last-known-good with nothing half-installed.
+    // loadFromDisk preserves the prior last-known-good with nothing half-installed.
     const validatorDisposers: Array<() => void> = [];
     try {
       // [LAW:one-source-of-truth] The action runtime reads session.id + current

package/src/daemon/client-stats.ts

@@ -64,6 +64,7 @@ export function formatStats(s: StatsSnapshot): string {
   lines.push(`process`);
   lines.push(`  pid           ${s.pid}`);
   lines.push(`  version       ${s.version}`);
+  lines.push(`  protocol      ${s.protocolVersion}`);
   lines.push(`  startedAt     ${s.startedAt}`);
   lines.push(`  uptime        ${fmtUptime(s.uptimeSec)}`);
   lines.push(`  rss           ${fmtBytes(s.rssBytes)}`);

package/src/daemon/server.ts

@@ -131,11 +131,27 @@ const sessionState = new SessionState();
 const contextProvider = new ContextProvider();
 const metricsProvider = new MetricsProvider();
 const tmuxService = new TmuxService();
-const renderCache = new RenderCache({
-  gitService,
-  sessionState,
-  watchers: watcherRegistry,
-});
+const renderCache = new RenderCache(
+  {
+    gitService,
+    sessionState,
+    watchers: watcherRegistry,
+  },
+  {
+    observers: {
+      // [LAW:no-silent-failure] Every config (re)load's outcome lands in
+      // daemon.log beside the "config change detected" line that preceded it
+      // — the operator's only record of whether a save was picked up cleanly,
+      // kept rendering last-known-good behind an error, or resolved to a
+      // different file. Same info level as the detection line.
+      onReload: (entry) =>
+        dlog(
+          "info",
+          `config loaded projectDir=${entry.projectDir} cwd=${entry.cwd} file=${entry.configFilePath ?? "<bundled default>"} error=${entry.lastError === null ? "none" : JSON.stringify(entry.lastError)} warning=${entry.lastWarning === null ? "none" : JSON.stringify(entry.lastWarning)}`,
+        ),
+    },
+  },
+);
 
 const REQUEST_TIMEOUT_MS = 200;
 const BIN_CHECK_INTERVAL_MS = 60 * 1000;

package/src/daemon/stats.ts

@@ -5,6 +5,7 @@
 import type { LaunchCategory } from "../proc/launch";
 import type { LaunchStatsHandle } from "../proc/stats-handle";
 import { PROTOCOL_VERSION } from "./protocol";
+import { PACKAGE_VERSION } from "../version";
 
 // Rolling window for "last minute" counts. Keep timestamps for each launch in
 // a ring buffer; eviction happens lazily on read.
@@ -28,7 +29,11 @@ const HISTOGRAM_CAP = 16;
 
 export interface StatsSnapshot {
   pid: number;
-  version: number;
+  // [LAW:one-source-of-truth] The daemon's own baked package stamp — set
+  // against `cc-candybar --version` to diagnose client-vs-daemon skew in one
+  // step. The wire contract number is a different fact under its own name.
+  version: string;
+  protocolVersion: number;
   startedAt: string;
   uptimeSec: number;
   rssBytes: number;
@@ -199,7 +204,8 @@ export class RuntimeStats {
     const mem = process.memoryUsage();
     return {
       pid: process.pid,
-      version: PROTOCOL_VERSION,
+      version: PACKAGE_VERSION,
+      protocolVersion: PROTOCOL_VERSION,
       startedAt: this.startedAt.toISOString(),
       uptimeSec: Math.floor((Date.now() - this.startedAt.getTime()) / 1000),
       rssBytes: mem.rss,

package/src/help-text.ts

@@ -1,5 +1,6 @@
 import { DISCLOSURE_GLYPH_CLOSED } from "./config/disclosure";
 import { HELP_GLYPH_CLOSED } from "./config/help";
+import { NODE_FLAGS } from "./cli-flags";
 
 // [LAW:effects-at-boundaries] Pure data, no I/O — index.ts owns the console.log
 // effect. Kept as its own module so the text is importable (and testable) without
@@ -36,7 +37,8 @@ cc-candybar - Beautiful powerline statusline for Claude Code
 Usage: cc-candybar [options]
 
 Standalone Commands:
-  -h, --help               Show this help
+  ${NODE_FLAGS.help.join(", ").padEnd(25)}Show this help
+  ${NODE_FLAGS.version.join(", ").padEnd(25)}Print the version of this runtime (cc-candybar <version>)
 
 Debugging:
   CC_CANDYBAR_DEBUG=1      Enable debug logging for troubleshooting

package/src/index.ts

@@ -16,6 +16,8 @@ import { runCheck } from "./check";
 import { obtainDaemonKick } from "./daemon/acquire";
 import { planOutcome } from "./render/outcome-plan";
 import { HELP_TEXT } from "./help-text";
+import { NODE_FLAGS } from "./cli-flags";
+import { PACKAGE_VERSION } from "./version";
 
 // Read terminal width from the live shell context (no subprocess). Returns
 // undefined when nothing reliable is available; the daemon falls back to its
@@ -52,6 +54,9 @@ function detectTermCols(): number | undefined {
 // widen recall of a fact that is otherwise reported as a plain `false`.
 const SSH_ENV_VARS = ["SSH_CONNECTION", "SSH_CLIENT", "SSH_TTY"] as const;
 
+const hasFlag = (flags: readonly string[]): boolean =>
+  flags.some((f) => process.argv.includes(f));
+
 // [LAW:dataflow-not-control-flow] A fold over the vocabulary, not a chain of
 // ifs — adding a name is a data edit.
 //
@@ -69,13 +74,18 @@ function showHelpText(): void {
 
 async function main(): Promise<void> {
   try {
-    const showHelp =
-      process.argv.includes("--help") || process.argv.includes("-h");
-
-    if (showHelp) {
+    if (hasFlag(NODE_FLAGS.help)) {
       showHelpText();
       process.exit(0);
     }
+    // [LAW:one-type-per-behavior] Answers "what is THIS binary" from the baked
+    // stamp alone — never a daemon probe, which would fail exactly when the
+    // flag is most needed (no working daemon). Daemon skew is the stats
+    // snapshot's `version` field.
+    if (hasFlag(NODE_FLAGS.version)) {
+      console.log(`cc-candybar ${PACKAGE_VERSION}`);
+      process.exit(0);
+    }
 
     // [LAW:dataflow-not-control-flow] Subcommand dispatch is data: argv[2]
     // selects the handler. Each handler short-circuits via process.exit().

package/src/install/index.ts

@@ -8,12 +8,7 @@ import type { PermanentOutcome } from "../daemon/client-transport";
 import { obtainDaemonKick } from "../daemon/acquire";
 import { URL_SCHEME, VERB_COPY } from "../click/wire";
 import { DISCLOSURE_GLYPH_CLOSED } from "../config/disclosure";
-
-// [LAW:one-source-of-truth] Replaced at build time by tsdown's `define` option
-// from package.json — the single version stamp install output reports.
-declare const __PACKAGE_VERSION__: string;
-const PACKAGE_VERSION =
-  typeof __PACKAGE_VERSION__ !== "undefined" ? __PACKAGE_VERSION__ : "dev";
+import { PACKAGE_VERSION } from "../version";
 
 const PACKAGE_NAME = "@promptctl/cc-candybar";
 const BUNDLE_ID = "com.cccandybar.url-handler";

package/src/version.ts

@@ -0,0 +1,17 @@
+// [LAW:one-source-of-truth] THE version stamp of this runtime. package.json is
+// the sole authority: tsdown's `define` bakes it into the bundle, and
+// scripts/version-stamp.cjs preloads it for untranspiled source. Every consumer
+// — `--version`, the install banner, the daemon's stats snapshot — reads this
+// one export.
+declare const __PACKAGE_VERSION__: string;
+
+// [LAW:no-silent-failure] A runtime that cannot say what it is must say THAT.
+// The old `"dev"` fallback was an answer-shaped void in a flag whose whole job
+// is answering this question; an unsubstituted build now fails at module load.
+if (typeof __PACKAGE_VERSION__ === "undefined") {
+  throw new Error(
+    "__PACKAGE_VERSION__ was not substituted: build via tsdown (define), or preload scripts/version-stamp.cjs when running source",
+  );
+}
+
+export const PACKAGE_VERSION: string = __PACKAGE_VERSION__;