@promptctl/cc-candybar 1.0.0

package/src/template-engine/scope.ts

@@ -0,0 +1,62 @@
+// [LAW:dataflow-not-control-flow] The scope Proxy converts a flat variable
+// store (keys like "session.id", "git.branch", "cwd") into the nested object
+// shape the template engine expects for ".session.id" field access.
+// No data is materialised — the proxy navigates namespace prefixes lazily and
+// calls store.read() only when a leaf is reached, so MobX dependency tracking
+// fires at the point of actual reads inside a computed body.
+//
+// The engine's getField() uses `name in obj` before `obj[name]`, so the
+// proxy must define a `has` trap as well as `get`.
+
+import type { VariableStore } from "../var-system/store.js";
+
+// Build the scope object the engine receives as `.` (dot).
+// Call once per render; the returned object is a read-only view of the store
+// at evaluation time — do not cache across renders.
+export function buildScope(store: VariableStore): object {
+  const names = new Set(store.names());
+  return makeProxy(store, names, "");
+}
+
+function makeProxy(
+  store: VariableStore,
+  names: Set<string>,
+  prefix: string,
+): object {
+  return new Proxy(Object.create(null) as object, {
+    has(_, key: string | symbol): boolean {
+      if (typeof key !== "string") return false;
+      const fullKey = prefix ? `${prefix}.${key}` : key;
+      // Leaf: exact variable.
+      if (names.has(fullKey)) return true;
+      // Interior: a namespace prefix for at least one stored variable.
+      const nsPrefix = `${fullKey}.`;
+      for (const n of names) {
+        if (n.startsWith(nsPrefix)) return true;
+      }
+      return false;
+    },
+
+    get(_, key: string | symbol): unknown {
+      if (typeof key !== "string") return undefined;
+      const fullKey = prefix ? `${prefix}.${key}` : key;
+
+      // Leaf: exact variable in the store.
+      if (names.has(fullKey)) {
+        return store.read(fullKey);
+      }
+
+      // Interior: a namespace prefix for at least one stored variable.
+      // Return a nested proxy; MobX tracking fires only at the leaf read.
+      const nsPrefix = `${fullKey}.`;
+      for (const n of names) {
+        if (n.startsWith(nsPrefix)) {
+          return makeProxy(store, names, fullKey);
+        }
+      }
+
+      // Unknown: `has` returned false so the engine will throw MissingFieldError.
+      return undefined;
+    },
+  });
+}

package/src/themes/index.ts

@@ -0,0 +1,19 @@
+// [LAW:single-enforcer] Public barrel for the themes module. Name/string policy
+// lives in policy.ts; memoized resolver construction (name→resolver and
+// transposition) lives in palette-resolvers.ts. rich-js owns palettes,
+// hydration, all color math, and the anchor rule — cc-candybar keeps no color
+// arithmetic of its own.
+export {
+  resolvePaletteName,
+  effectiveThemeName,
+  listResolvablePaletteNames,
+  listAvailableThemes,
+  pickRandomTheme,
+  STYLE_ORDER,
+  DISPLAY_STYLES,
+} from "./policy.js";
+
+export {
+  resolverForThemeName,
+  transposedResolver,
+} from "./palette-resolvers.js";

package/src/themes/palette-resolvers.ts

@@ -0,0 +1,86 @@
+// Memoized PaletteResolver construction over rich-js. cc-candybar moves theme
+// NAMES and hue shifts (data); rich-js owns every color value operation. Two
+// memos live here: a theme name -> base resolver, and a (base, hueShift) ->
+// transposed resolver. They compose — the per-render base palette feeds the
+// per-segment transposition.
+//
+// [LAW:no-shared-mutable-globals] Single owner: this module. Both Maps are pure
+// memos of pure rich-js functions, keyed by immutable inputs (resolved theme
+// name; palette name + hueShift). rich-js palettes are immutable registry
+// singletons, so a cached resolver never goes stale. Key spaces are bounded by
+// #themes and #themes × #distinct hueShifts (hueShift = segIndex*hueStep,
+// segIndex bounded by layout) — both small. Shared on purpose: a theme's base
+// resolver and its gruvbox+42° transposition are each computed once per process,
+// not once per RenderCache entry or per render. Read/written only through the
+// two functions below.
+
+import {
+  PaletteResolver,
+  transposePalette,
+  getThemePalette,
+} from "@promptctl/rich-js";
+import type { ThemeKey } from "@promptctl/rich-js";
+import { resolvePaletteName } from "./policy.js";
+
+const baseCache = new Map<string, PaletteResolver>();
+const transposeCache = new Map<string, PaletteResolver>();
+
+/**
+ * The PaletteResolver for a theme name (aliases resolved). Memoized.
+ *
+ * [LAW:single-enforcer] The one place a theme name becomes a PaletteResolver —
+ * the per-render base palette and per-segment `palette:` overrides both flow
+ * through here. A name that does not resolve is registry/resolver drift, never
+ * user error: the loader validates `globals.palette` and the set-state verb
+ * validates session theme values against the resolvable set, so by the time a
+ * name reaches here it must resolve. [LAW:no-defensive-null-guards] the throw is
+ * the loud failure for that broken invariant, not a fallback.
+ */
+export function resolverForThemeName(name: string): PaletteResolver {
+  const resolved = resolvePaletteName(name);
+  const hit = baseCache.get(resolved);
+  if (hit !== undefined) return hit;
+
+  const palette = getThemePalette(resolved);
+  if (palette === null) {
+    throw new Error(
+      `Palette "${name}" (resolved "${resolved}") did not resolve in the ` +
+        `theme registry — allowed names and the registry are inconsistent`,
+    );
+  }
+  const resolver = new PaletteResolver(palette);
+  baseCache.set(resolved, resolver);
+  return resolver;
+}
+
+/**
+ * The PaletteResolver for `base`'s palette transposed by `hueShift` degrees.
+ *
+ * [LAW:dataflow-not-control-flow] hueShift is data; 0 flows through
+ * transposePalette's identity fast-path (byte-exact, no round-trip) — no branch
+ * here. Chroma and lightness are held identity: only hue rotates. rich-js
+ * hue-locks ANCHORED_ROOTS (error/success/warning), so semantic meaning is
+ * preserved by construction — no local exemption list to drift.
+ *
+ * [LAW:single-enforcer] The sole place a transposed resolver is built. The memo
+ * miss (undefined) is genuine optionality — not-yet-computed — not a defended
+ * invariant.
+ */
+export function transposedResolver(
+  base: PaletteResolver,
+  hueShift: number,
+): PaletteResolver {
+  const cacheKey = `${base.palette.name} ${hueShift}`;
+  const hit = transposeCache.get(cacheKey);
+  if (hit !== undefined) return hit;
+
+  const key: ThemeKey = {
+    hueShift,
+    chromaScale: 1,
+    lightnessScale: 1,
+    lightnessShift: 0,
+  };
+  const resolver = new PaletteResolver(transposePalette(base.palette, key));
+  transposeCache.set(cacheKey, resolver);
+  return resolver;
+}

package/src/themes/policy.ts

@@ -0,0 +1,79 @@
+// [LAW:single-enforcer] The slim name/string policy layered on top of rich-js's
+// theme registry. cc-candybar selects theme NAMES and style IDENTIFIERS here;
+// every color *value* operation (hydrate hex, resolve specs, darken/contrast,
+// hue/transpose) lives in rich-js. This module only moves strings — no
+// PaletteResolver, no ColorRgba, no hex. The semantic/anchor knowledge
+// (which tokens keep their hue) stays in rich-js (ANCHORED_ROOTS), not here.
+
+import { listThemePalettes } from "@promptctl/rich-js";
+
+// --- Theme name aliasing ---
+
+const THEME_ALIASES: Record<string, string> = {
+  dark: "textual-dark",
+  light: "textual-light",
+};
+
+export function resolvePaletteName(name: string): string {
+  return THEME_ALIASES[name] ?? name;
+}
+
+// The theme name a render should use, as data. [LAW:dataflow-not-control-flow]
+// The `??` chain is the precedence — session choice over config default over the
+// built-in — with no "if the session has a theme" branch. The session value is
+// the user's live per-session pick (null when unset); globals.palette is the
+// config default; "textual-dark" is the always-present floor.
+// [LAW:one-source-of-truth] The single definition of "which theme is effective";
+// every render derives basePalette through this, so the rendered palette can
+// never disagree with the chosen theme.
+export function effectiveThemeName(
+  sessionTheme: string | null,
+  globalsPalette: string | undefined,
+): string {
+  return sessionTheme ?? globalsPalette ?? "textual-dark";
+}
+
+function listThemeAliases(): readonly string[] {
+  return Object.keys(THEME_ALIASES);
+}
+
+// [LAW:one-source-of-truth] The set of names that resolve to a concrete Palette
+// is exactly registry names ∪ aliases — the same inputs resolvePaletteName +
+// getThemePalette accept. "custom" and "random" are deliberately absent: neither
+// names a concrete palette (custom needs inline colors; random is a per-session
+// sentinel). Config validators that gate a palette PULL (DSL `palette:` field)
+// must reuse this, not re-derive it.
+export function listResolvablePaletteNames(): readonly string[] {
+  return [...listThemePalettes(), ...listThemeAliases()];
+}
+
+// Selectable theme names for the random pool + picker: registry names plus the
+// "custom" sentinel. Aliases are excluded — they duplicate registry entries.
+export function listAvailableThemes(): string[] {
+  const allNames = new Set<string>(listThemePalettes() as readonly string[]);
+  allNames.add("custom");
+  return [...allNames].sort();
+}
+
+// --- Style identifiers ---
+
+export const STYLE_ORDER: readonly string[] = [
+  "surface",
+  "muted",
+  "button",
+  "hue",
+];
+
+export const DISPLAY_STYLES: ReadonlyArray<
+  "minimal" | "powerline" | "capsule"
+> = ["minimal", "powerline", "capsule"];
+
+// --- Session-random pick ---
+
+// [LAW:one-source-of-truth] The random pool derives from the same registry the
+// rest of the system uses. "custom" is excluded because it requires inline
+// colors.custom to be defined.
+export function pickRandomTheme(): string {
+  const themes = listAvailableThemes().filter((t) => t !== "custom");
+  return themes[Math.floor(Math.random() * themes.length)]!;
+}

package/src/themes/session-random.ts

@@ -0,0 +1,88 @@
+// [LAW:single-enforcer] One place resolves the "random" sentinel into a
+// concrete value, keyed by sessionId so the random pick is *stable for the
+// life of that session* (pick once; clicks like set-state overwrite it).
+// Each setting (theme / style / endpoints) flows through the same pattern:
+// read sessionState → if cached return it → if config says "random" pick
+// + cache → otherwise return config value as-is.
+//
+// The cache is sessionState itself: that means a) the set-state click
+// verb continues to work (it overwrites the same key), and b) the
+// dataflow is uniform — no parallel "random cache" to keep in sync with
+// sessionState.
+
+import { pickRandomTheme, DISPLAY_STYLES, STYLE_ORDER } from "./policy.js";
+
+interface SessionStateRW {
+  get(sessionId: string, key: string): string | null;
+  set(sessionId: string, key: string, value: string): void;
+}
+
+const SENTINEL = "random";
+
+// [LAW:dataflow-not-control-flow] Same shape every call — the only branch is
+// "is this random?" and that's a value-driven question, not a control-flow
+// special case. No early returns hide the cache write from later readers.
+function resolve(
+  sessionId: string,
+  key: string,
+  configValue: string | undefined,
+  sessionState: SessionStateRW | undefined,
+  pick: () => string,
+  fallback: string,
+): string {
+  if (!sessionState) {
+    return configValue === SENTINEL ? pick() : (configValue ?? fallback);
+  }
+  const cached = sessionState.get(sessionId, key);
+  if (cached) return cached;
+  if (configValue !== SENTINEL) return configValue ?? fallback;
+  const chosen = pick();
+  sessionState.set(sessionId, key, chosen);
+  return chosen;
+}
+
+export function resolveSessionTheme(
+  sessionId: string,
+  configTheme: string | undefined,
+  sessionState: SessionStateRW | undefined,
+): string {
+  return resolve(
+    sessionId,
+    "theme",
+    configTheme,
+    sessionState,
+    pickRandomTheme,
+    "dark",
+  );
+}
+
+export function resolveSessionStyle(
+  sessionId: string,
+  configStyle: string | undefined,
+  sessionState: SessionStateRW | undefined,
+): string {
+  return resolve(
+    sessionId,
+    "style",
+    configStyle,
+    sessionState,
+    () => STYLE_ORDER[Math.floor(Math.random() * STYLE_ORDER.length)]!,
+    "surface",
+  );
+}
+
+export function resolveSessionDisplayStyle(
+  sessionId: string,
+  configDisplayStyle: string | undefined,
+  sessionState: SessionStateRW | undefined,
+): "minimal" | "powerline" | "capsule" {
+  const value = resolve(
+    sessionId,
+    "displayStyle",
+    configDisplayStyle,
+    sessionState,
+    () => DISPLAY_STYLES[Math.floor(Math.random() * DISPLAY_STYLES.length)]!,
+    "minimal",
+  );
+  return value === "powerline" || value === "capsule" ? value : "minimal";
+}

package/src/utils/cache.ts

@@ -0,0 +1,206 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { setTimeout } from "node:timers/promises";
+import { debug } from "./logger";
+import { cacheDir } from "../daemon/paths";
+
+interface ErrnoError extends Error {
+  code?: string;
+}
+
+export interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+}
+
+export class CacheManager {
+  private static readonly CACHE_DIR = cacheDir();
+  private static readonly USAGE_CACHE_DIR = path.join(this.CACHE_DIR, "usage");
+  private static readonly LOCKS_DIR = path.join(this.CACHE_DIR, "locks");
+
+  private static isLocked(name: string): boolean {
+    const lockFile = path.join(this.LOCKS_DIR, name);
+    if (!fs.existsSync(lockFile)) {
+      return false;
+    }
+
+    try {
+      const lockContent = fs.readFileSync(lockFile, "utf-8");
+      const pid = parseInt(lockContent.trim(), 10);
+
+      if (isNaN(pid)) {
+        debug(`Invalid PID in lock file ${name}, removing stale lock`);
+        fs.unlinkSync(lockFile);
+        return false;
+      }
+
+      try {
+        process.kill(pid, 0);
+        return true;
+      } catch (error) {
+        if ((error as ErrnoError).code === "ESRCH") {
+          debug(`Removing stale lock file ${name} for dead process ${pid}`);
+          fs.unlinkSync(lockFile);
+          return false;
+        }
+        debug(`Error checking process ${pid} for lock ${name}:`, error);
+        return true;
+      }
+    } catch (error) {
+      debug(`Error reading lock file ${name}:`, error);
+      return true;
+    }
+  }
+
+  private static async acquireLock(
+    name: string,
+    timeout = 5000,
+  ): Promise<boolean> {
+    const RETRY_DELAY_MS = 50;
+    const FILE_CREATE_FLAG = "wx";
+
+    await this.ensureCacheDirectories();
+    const lockFile = path.join(this.LOCKS_DIR, name);
+    const startTime = Date.now();
+    const lockContent = String(process.pid);
+
+    while (Date.now() - startTime < timeout) {
+      try {
+        await fs.promises.writeFile(lockFile, lockContent, {
+          flag: FILE_CREATE_FLAG,
+        });
+        debug(`Lock acquired for ${name}`);
+        return true;
+      } catch (error) {
+        if ((error as ErrnoError).code === "EEXIST") {
+          await setTimeout(RETRY_DELAY_MS);
+        } else {
+          throw error;
+        }
+      }
+    }
+    debug(`Failed to acquire lock for ${name} within ${timeout}ms`);
+    return false;
+  }
+
+  private static async releaseLock(name: string): Promise<void> {
+    const lockFile = path.join(this.LOCKS_DIR, name);
+    try {
+      await fs.promises.unlink(lockFile);
+      debug(`Lock released for ${name}`);
+    } catch (error) {
+      if ((error as ErrnoError).code !== "ENOENT") {
+        debug(`Error releasing lock for ${name}:`, error);
+      }
+    }
+  }
+
+  static async ensureCacheDirectories(): Promise<void> {
+    try {
+      await Promise.all([
+        fs.promises.mkdir(this.CACHE_DIR, { recursive: true }),
+        fs.promises.mkdir(this.USAGE_CACHE_DIR, { recursive: true }),
+        fs.promises.mkdir(this.LOCKS_DIR, { recursive: true }),
+      ]);
+    } catch (error) {
+      debug("Failed to create cache directories:", error);
+    }
+  }
+
+  static createProjectHash(projectPath: string): string {
+    return createHash("md5").update(projectPath).digest("hex").substring(0, 8);
+  }
+
+  static async getUsageCache(
+    cacheType: "pricing",
+    latestMtime?: number,
+  ): Promise<unknown> {
+    const MAX_RETRIES = 3;
+    const RETRY_DELAY_MS = 75;
+    const FILE_ENCODING = "utf-8";
+
+    await this.ensureCacheDirectories();
+    const cachePath = path.join(this.USAGE_CACHE_DIR, `${cacheType}.json`);
+    const lockName = `${cacheType}.usage.lock`;
+
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+      const isCurrentlyLocked = this.isLocked(lockName);
+      if (isCurrentlyLocked) {
+        debug(`Cache for ${cacheType} is locked, waiting...`);
+        await setTimeout(RETRY_DELAY_MS);
+        continue;
+      }
+
+      try {
+        const content = await fs.promises.readFile(cachePath, FILE_ENCODING);
+        const cached: CacheEntry<unknown> = JSON.parse(content);
+        const cacheIsValid = !latestMtime || cached.timestamp >= latestMtime;
+
+        if (cacheIsValid) {
+          debug(`[CACHE-HIT] ${cacheType} disk cache: found`);
+          return this.deserializeDates(cached.data);
+        } else {
+          debug(
+            `${cacheType} cache outdated: cache=${cached.timestamp}, latest=${latestMtime}`,
+          );
+          return null;
+        }
+      } catch (error) {
+        if ((error as ErrnoError).code === "ENOENT") {
+          debug(`No shared ${cacheType} usage cache found`);
+          return null;
+        }
+        const attemptNumber = attempt + 1;
+        debug(
+          `Attempt ${attemptNumber} failed to read ${cacheType} cache: ${(error as Error).message}. Retrying...`,
+        );
+        await setTimeout(RETRY_DELAY_MS);
+      }
+    }
+
+    debug(`Failed to read ${cacheType} cache after ${MAX_RETRIES} attempts.`);
+    return null;
+  }
+
+  private static deserializeDates(data: unknown): unknown {
+    if (Array.isArray(data)) {
+      return data.map((entry) => ({
+        ...entry,
+        timestamp: new Date(entry.timestamp),
+      }));
+    }
+    return data;
+  }
+
+  static async setUsageCache(
+    cacheType: "pricing",
+    data: unknown,
+    latestMtime?: number,
+  ): Promise<void> {
+    const lockName = `${cacheType}.usage.lock`;
+    const lockAcquired = await this.acquireLock(lockName);
+    if (!lockAcquired) {
+      debug(`Could not acquire lock to set usage cache for ${cacheType}`);
+      return;
+    }
+
+    try {
+      await this.ensureCacheDirectories();
+      const cachePath = path.join(this.USAGE_CACHE_DIR, `${cacheType}.json`);
+      const cacheTimestamp = latestMtime || Date.now();
+      const cacheEntry: CacheEntry<unknown> = {
+        data,
+        timestamp: cacheTimestamp,
+      };
+      const cacheContent = JSON.stringify(cacheEntry);
+
+      await fs.promises.writeFile(cachePath, cacheContent, "utf-8");
+      debug(`[CACHE-SET] ${cacheType} disk cache stored`);
+    } catch (error) {
+      debug(`Failed to save ${cacheType} usage cache:`, error);
+    } finally {
+      await this.releaseLock(lockName);
+    }
+  }
+}