@promptctl/cc-candybar 1.0.0

package/src/demo/dsl.ts

@@ -0,0 +1,117 @@
+// Minimal end-to-end demo of the segment DSL render spine.
+//
+//   pnpm demo:dsl                       # renders src/demo/statusline.json5
+//   pnpm demo:dsl path/to/other.json5   # renders any DSL config
+//
+// [LAW:single-enforcer] This renders through registerDslConfig + renderDsl
+// — the exact spine the daemon calls. There is no demo-only render path; what
+// prints here is what production produces.
+//
+// [LAW:dataflow-not-control-flow] The body is straight-line: read config →
+// register → render frames → dispose. The config file and payload are data;
+// swapping either changes the output without changing this code. Rendering N
+// frames over time is not branching — it lets the asynchronous sources (shell,
+// time) populate the store and shows the line come alive, exactly as the daemon
+// re-renders on each status-line tick.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import process from "node:process";
+import { setTimeout as sleep } from "node:timers/promises";
+
+import {
+  parseDslConfig,
+  mergeWithDefault,
+  validateConfig,
+} from "../config/dsl-loader.js";
+import { VariableStore } from "../var-system/store.js";
+import { SourceRegistry } from "../var-system/sources.js";
+import { listResolvablePaletteNames } from "../themes/policy.js";
+import { effectiveThemeName, resolverForThemeName } from "../themes/index.js";
+import { registerDslConfig, renderDsl } from "../dsl/render.js";
+import { DEFAULT_TERMINAL_WIDTH } from "../render/strip.js";
+import { applyClaudeCodeReserve } from "../utils/terminal-width.js";
+
+const FRAMES = 4;
+const FRAME_INTERVAL_MS = 450;
+
+const here = dirname(fileURLToPath(import.meta.url));
+const configPath = process.argv[2] ?? join(here, "statusline.json5");
+const source = readFileSync(configPath, "utf-8");
+
+// [LAW:one-source-of-truth] The palette names the loader accepts are exactly
+// the names the renderer can resolve — both derive from the same registry, so
+// we hand the loader the live set rather than a hand-maintained copy.
+//
+// Full three-stage pipeline: parse → merge → validate. The renderer accepts
+// only `ValidatedConfig`, so the chain is type-enforced.
+const ALLOWED = new Set(listResolvablePaletteNames());
+const raw = parseDslConfig(configPath, source, ALLOWED);
+const merged = mergeWithDefault(raw);
+const config = validateConfig(merged, configPath, source, ALLOWED);
+
+// One Claude Code status-line hook event, faked. The `input` vars in the
+// config (cwd, model, session) read their values out of this object.
+const payload = {
+  hook_event_name: "Status",
+  session_id: "demo0a1b-2c3d-4e5f-6a7b-8c9d0e1f2a3b",
+  cwd: process.cwd(),
+  model: { id: "claude-opus-4-7", display_name: "Opus 4.7" },
+  workspace: {
+    current_dir: process.cwd(),
+    project_dir: process.cwd(),
+  },
+};
+
+// The demo has no SessionState; the effective theme is just the config default.
+const basePalette = resolverForThemeName(
+  effectiveThemeName(null, config.globals.palette),
+);
+
+// A fresh store + registry for this run. (A hot-reloading daemon would
+// dispose() the old pair and build new ones — see registerDslConfig's docs.)
+// registerDslConfig wires the time/shell sources' timers and watchers onto the
+// registry, so dispose() must run even if registration or rendering throws —
+// otherwise those handles keep the process alive. try/finally guarantees it.
+const store = new VariableStore();
+const registry = new SourceRegistry(store);
+try {
+  const compiled = registerDslConfig(config, registry, {
+    cwd: process.cwd(),
+    store,
+  });
+
+  process.stdout.write(
+    `\n  DSL demo — ${configPath}\n` +
+      `  rendered through registerDslConfig + renderDsl (the daemon's spine)\n` +
+      `  watch the git branch segment appear and the clock tick:\n\n`,
+  );
+
+  for (let frame = 0; frame < FRAMES; frame++) {
+    const line = renderDsl(
+      config,
+      compiled,
+      store,
+      registry,
+      payload,
+      basePalette,
+      {
+        style: "powerline",
+        colorCompatibility: "truecolor",
+        // [LAW:one-source-of-truth] Demo applies the same Claude-Code-UI
+        // reserve the daemon does so demo output matches the bytes a real
+        // statusline would emit at the same terminal width.
+        width: applyClaudeCodeReserve(
+          process.stdout.columns ?? DEFAULT_TERMINAL_WIDTH,
+        ),
+      },
+    );
+    process.stdout.write(`  ${line}\n`);
+    if (frame < FRAMES - 1) await sleep(FRAME_INTERVAL_MS);
+  }
+
+  process.stdout.write("\n");
+} finally {
+  registry.dispose();
+}

package/src/demo/mock-data.ts

@@ -0,0 +1,67 @@
+export interface MockSegment {
+  type: string;
+  text: string;
+}
+
+export interface MockSample {
+  name: string;
+  segments: MockSegment[];
+}
+
+export const MOCK_SAMPLES: MockSample[] = [
+  {
+    name: "Default Session",
+    segments: [
+      { type: "directory", text: "~/projects/my-app" },
+      { type: "git", text: "main ✗" },
+      { type: "model", text: "Claude Sonnet 4" },
+      { type: "session", text: "$2.34 · 45k tok" },
+      { type: "context", text: "38%" },
+    ],
+  },
+  {
+    name: "Heavy Usage",
+    segments: [
+      { type: "directory", text: "~/work/api-server" },
+      { type: "git", text: "feat/auth ✗ +3" },
+      { type: "model", text: "Claude Opus 4" },
+      { type: "session", text: "$12.87 · 156k tok" },
+      { type: "context", text: "72%" },
+      { type: "block", text: "blk #3 $4.20" },
+      { type: "today", text: "today $18.50" },
+    ],
+  },
+  {
+    name: "Critical Context",
+    segments: [
+      { type: "directory", text: "~/big-project" },
+      { type: "git", text: "main ✓" },
+      { type: "model", text: "Claude Opus 4" },
+      { type: "session", text: "$45.20 · 198k tok" },
+      { type: "contextCritical", text: "95% ⚠" },
+      { type: "metrics", text: "1.2s 42msg" },
+    ],
+  },
+  {
+    name: "Full Segments",
+    segments: [
+      { type: "directory", text: "~/code/toolkit" },
+      { type: "git", text: "fix/bug-123 ↑2 ↓1" },
+      { type: "model", text: "Claude Sonnet 4" },
+      { type: "session", text: "$5.67 · 78k tok" },
+      { type: "block", text: "blk #7 $1.23" },
+      { type: "today", text: "today $22.10" },
+      { type: "context", text: "45%" },
+      { type: "metrics", text: "0.8s 89msg +420 -180" },
+      { type: "version", text: "v1.2.3" },
+      { type: "weekly", text: "wk $87.30" },
+    ],
+  },
+  {
+    name: "Minimal",
+    segments: [
+      { type: "directory", text: "~" },
+      { type: "model", text: "Claude" },
+    ],
+  },
+];

package/src/demo/statusline.json5

@@ -0,0 +1,92 @@
+// Demo DSL statusline — a runnable example of the segment DSL.
+//
+//   Run it:   pnpm demo:dsl
+//   Hack it:  edit a template / palette / layout entry below and re-run.
+//             No rebuild — the config IS the program.
+//
+// This file is rendered by the SAME two functions the daemon calls
+// (registerDslConfig + renderDsl in src/dsl/render.ts). There is no
+// demo-only render path — what you see here is what production produces.
+{
+  globals: {
+    // Base palette for every segment that doesn't pull its own (see `branch`).
+    palette: 'textual-dark',
+  },
+
+  // ── Variables: where each segment's data comes from ──────────────────────
+  // Every `kind` maps to one runtime source. Templates reference these by name
+  // with a leading dot (`.user`, `.cwd`, …). A referenced-but-undeclared name
+  // is a load-time error, not a silent blank.
+  variables: {
+    // env  — read straight from the process environment.
+    user: { kind: 'env', name: 'USER', default: 'anon' },
+
+    // input — pulled from the JSON payload Claude Code sends each render tick.
+    cwd:     { kind: 'input', path: 'workspace.current_dir', default: '?' },
+    model:   { kind: 'input', path: 'model.display_name',    default: '' },
+    session: { kind: 'input', path: 'session_id',            default: '' },
+
+    // template — derived from other vars; recomputed reactively when they move.
+    sid:  { kind: 'template', template: '{{ trunc 8 .session }}' },
+    here: { kind: 'template', template: '{{ basename .cwd }}' },
+
+    // shell — run a command, cache the result for a TTL window. Populates
+    // asynchronously: until the command returns, `.branch` is the default ''.
+    branch: { kind: 'shell', command: 'git branch --show-current', cache: { ttl: '5s' }, default: '' },
+
+    // time — the system clock, formatted with a Go reference-time layout.
+    clock: { kind: 'time', layout: '15:04:05', cache: { ttl: '1s' } },
+
+    // literal — a fixed value read like any other var. Here it drives the
+    // per-segment hue rotation (HUE_STEP_VAR): adjacent segments rotate 14° so
+    // they stay distinct. Make it a `state` var + a stepper widget to adjust it
+    // live; a literal is the fixed-value form.
+    'hue.step': { kind: 'literal', value: 14 },
+
+    // (file and git kinds exist too — omitted here to stay minimal.)
+  },
+
+  // ── Segments: how each piece of data is drawn ────────────────────────────
+  // `bg`/`fg` are palette spec strings. `fg: 'auto'` picks a readable foreground
+  // for the segment's background. `when` hides a segment when it evaluates false.
+  segments: {
+    user: {
+      template: ' {{ .user }} ',
+      bg: 'primary',
+      fg: 'auto',
+    },
+    directory: {
+      template: ' {{ .here }} ',
+      bg: 'surface',
+      fg: 'foreground',
+    },
+    branch: {
+      template: ' {{ .branch }} ',
+      bg: 'accent',
+      fg: 'auto',
+      when: '{{ ne .branch "" }}',   // hidden entirely outside a git repo
+      palette: 'gruvbox',      // this segment pulls its OWN palette (per-segment switch)
+    },
+    model: {
+      template: ' {{ .model }} ',
+      bg: 'secondary',
+      fg: 'auto',
+      when: '{{ ne .model "" }}',
+    },
+    session: {
+      template: ' ⌗{{ .sid }} ',
+      bg: 'surface',
+      fg: 'foreground',
+    },
+    clock: {
+      template: ' {{ .clock }} ',
+      bg: 'primary',
+      fg: 'auto',
+    },
+  },
+
+  // ── Layout: Option A shape grammar — one horizontal row of segment refs.
+  // { v: [...] } for multiple rows; { h: ['a', 'b'], when: '...' } for a gated row;
+  // bare string 'segname' for a single segment ref.
+  root: { h: ['user', 'directory', 'branch', 'model', 'session', 'clock'] },
+}

package/src/dsl/node-registry.ts

@@ -0,0 +1,281 @@
+// [LAW:single-enforcer] THE node-type registry: the one place each layout node
+// kind's render-time behavior (compile + render) is defined, dispatched through a
+// single typed lookup. The walk is ONE uniform dispatch:
+// nodeType(node.kind).render(node, ctx).
+//
+// [LAW:one-type-per-behavior] The layout is exactly two kinds — `container`
+// (arranges children) and `segment` (THE unit of rendering: one ref into the
+// named segments map, rendered to ONE strip item). Interaction, state-driven
+// display, and multi-region clickability all live in a segment's TEMPLATE, not
+// in extra node kinds — so there is no inline/stepper/picker node arm to add.
+// A horizontal run of segments is spelled `{ h: ["seg1", "seg2"] }` in the
+// A-grammar (the `cells` form and `layout` rows were deleted in 2de.19).
+//
+// [LAW:one-way-deps] This module sits BELOW render.ts (the driver): it imports
+// the leaf render/template helpers directly and receives the two recursive
+// capabilities (compileChild, renderChild) + the hue counter as DATA from the
+// driver. It must NOT import render.ts — that would invert the layering. render.ts
+// imports the compiled types + nodeType() from here, one-way.
+//
+// Hue is per-segment DECORATIVE only: each `segment` advances the cursor by one
+// unit (a container advances none), so colors stay positionally stable. It
+// carries NO structural meaning — unit cohesion is structural (one segment = one
+// strip item), not a function of matching backgrounds.
+
+import { RichText } from "@promptctl/rich-js";
+import type { PaletteResolver } from "@promptctl/rich-js";
+import type { Template } from "@promptctl/go-template-js";
+import type {
+  LayoutNode,
+  Direction,
+  SegmentDecl,
+} from "../config/dsl-types.js";
+import { splitCellsIntoLines } from "../render/split-lines.js";
+import { transposedResolver } from "../themes/index.js";
+import {
+  fragmentsToCells,
+  evaluateWhen,
+  applySegmentLayout,
+  resolveSegmentColors,
+} from "../template-engine/index.js";
+
+// ─── Compiled node shapes ──────────────────────────────────────────────────────
+
+// [LAW:dataflow-not-control-flow] The compiled mirror of a LayoutNode: the same
+// recursive shape with every `when` parsed ONCE at registration. renderDsl walks
+// this compiled tree — never the raw config — so the parse-once guarantee covers
+// every node.
+export interface CompiledSegmentNode {
+  readonly kind: "segment";
+  readonly when?: Template<RichText>;
+  readonly name: string;
+}
+export interface CompiledContainerNode {
+  readonly kind: "container";
+  readonly direction: Direction;
+  readonly when?: Template<RichText>;
+  readonly children: readonly CompiledNode[];
+}
+export type CompiledNode = CompiledSegmentNode | CompiledContainerNode;
+
+// Pre-parsed templates and pre-resolved palette for one segment, built once at
+// registration. A `segment` node names one; render looks it up via
+// ctx.lookupSegment.
+export interface CompiledSegment {
+  readonly when?: Template<RichText>;
+  readonly template: Template<RichText>;
+  readonly bg?: Template<RichText>;
+  readonly fg?: Template<RichText>;
+  readonly paletteResolver?: PaletteResolver;
+}
+export type CompiledSegments = Readonly<Record<string, CompiledSegment>>;
+
+// A rendered node is a LIST OF LINES, each line a list of cells — NOT yet
+// serialized. [LAW:types-are-the-program] Cells (not ANSI bytes) are the
+// composition substrate: the powerline joiner caps between adjacent cells, so
+// serializing a node before composition would freeze its last cell's edge and
+// make a cap across a sibling seam unrecoverable. Serialization (the single
+// joiner pass) runs exactly once, at the root, after the whole tree composes.
+export type RenderedLines = ReadonlyArray<readonly RichText[]>;
+
+// ─── Compile / render contexts (the injected capabilities) ──────────────────────
+
+// [LAW:locality-or-seam] The compile-time context the driver hands each node
+// type. `when` is PRE-COMPILED by the driver (walk-owned, uniform across kinds);
+// the type only assembles it in. compileChild is the recursion, injected so this
+// module needn't import the driver.
+export interface NodeCompileCtx {
+  readonly path: string;
+  // The node's own `when`, already parsed by the driver (one parse-when site).
+  readonly when?: Template<RichText>;
+  // Compile a child node (the recursion, injected so this module needn't import
+  // the driver).
+  compileChild(node: LayoutNode, path: string): CompiledNode;
+}
+
+// [LAW:single-enforcer] The render-time context. The hue COUNTER lives in the
+// driver; ctx exposes only nextHueShift() (advance + return this unit's shift) so
+// there is exactly one mutator. `visible` is THIS node's computed visibility
+// (the driver ANDs node.when with the parent's). renderChild continues the walk.
+export interface NodeRenderCtx {
+  readonly scope: object;
+  readonly basePalette: PaletteResolver;
+  readonly visible: boolean;
+  // Advance the walk-owned hue cursor by one unit and return that unit's shift.
+  nextHueShift(): number;
+  readonly perSegmentSink?: Map<string, readonly RichText[]>;
+  // Resolve a segment name to its decl + compiled form (the driver closes over
+  // config.segments + the compiled segments).
+  lookupSegment(
+    name: string,
+  ):
+    | { readonly seg: SegmentDecl; readonly compiled: CompiledSegment }
+    | undefined;
+  // Continue the walk into a child node (parentVisible = this node's visibility).
+  renderChild(node: CompiledNode, parentVisible: boolean): RenderedLines;
+}
+
+// ─── Composition ───────────────────────────────────────────────────────────────
+
+// [LAW:dataflow-not-control-flow] A container's `direction` is the projection it
+// applies to its already-rendered child blocks — DATA selecting a fold, not a
+// branch that skips work. `vertical` STACKS (concatenate the children's line-
+// lists); `horizontal` ZIPS (row i is every child's row-i cells concatenated, so
+// the joiner caps ACROSS the seam — there is no abut). The switch is exhaustive
+// over `Direction`; adding `outline` to DIRECTIONS forces a new arm here.
+function composeBlocks(
+  direction: Direction,
+  blocks: readonly RenderedLines[],
+): RenderedLines {
+  switch (direction) {
+    case "vertical":
+      return blocks.flatMap((b) => b);
+    case "horizontal": {
+      const height = blocks.reduce((m, b) => Math.max(m, b.length), 0);
+      const rows: RichText[][] = [];
+      for (let i = 0; i < height; i++) {
+        rows.push(blocks.flatMap((b) => b[i] ?? []));
+      }
+      return rows;
+    }
+  }
+}
+
+// ─── The node-type contract + registry ──────────────────────────────────────────
+
+type NodeKind = LayoutNode["kind"];
+
+// [LAW:types-are-the-program] One contract per node kind, generic over the kind so
+// each entry's compile/render see their OWN narrowed node arm — never the union,
+// so no internal re-narrow guard. compile (registration: LayoutNode → compiled,
+// parse-once) and render (per-render: compiled → lines) are co-located per kind.
+export interface NodeType<K extends NodeKind> {
+  compile(
+    node: Extract<LayoutNode, { kind: K }>,
+    cctx: NodeCompileCtx,
+  ): Extract<CompiledNode, { kind: K }>;
+  render(
+    node: Extract<CompiledNode, { kind: K }>,
+    ctx: NodeRenderCtx,
+  ): RenderedLines;
+}
+
+const containerType: NodeType<"container"> = {
+  compile(node, cctx) {
+    return {
+      kind: "container",
+      direction: node.direction,
+      when: cctx.when,
+      children: node.children.map((child, i) =>
+        cctx.compileChild(child, `${cctx.path}.children[${i}]`),
+      ),
+    };
+  },
+  render(node, ctx) {
+    // [LAW:dataflow-not-control-flow] A container advances NO hue unit itself; its
+    // children do, walked in order so positional hue stays stable. Hidden or not,
+    // every child is rendered (parentVisible threads the gate) so hidden subtrees
+    // still advance the cursor.
+    return composeBlocks(
+      node.direction,
+      node.children.map((child) => ctx.renderChild(child, ctx.visible)),
+    );
+  },
+};
+
+const segmentType: NodeType<"segment"> = {
+  compile(node, cctx) {
+    return { kind: "segment", when: cctx.when, name: node.name };
+  },
+  render(node, ctx) {
+    const found = ctx.lookupSegment(node.name);
+    // [LAW:no-defensive-null-guards] The loader validates every segment ref
+    // against the segments map and registerDslConfig compiles every declared
+    // segment; a miss is a caller bug (renderDsl given a mismatched compiled
+    // object).
+    if (!found) {
+      throw new Error(`Layout segment "${node.name}" has no matching segment`);
+    }
+    const { seg, compiled: segCompiled } = found;
+
+    // [LAW:single-enforcer] Advance the hue cursor BEFORE the visibility gate so a
+    // hidden segment still consumes its unit — siblings after it keep their
+    // positionally-stable colors regardless of which segments are hidden.
+    const hueShift = ctx.nextHueShift();
+    if (!ctx.visible) return [];
+
+    // [LAW:no-silent-failure] Wrap the whole render body in a try/catch so a
+    // partial-load consequence (e.g. a variable that failed to declare, leaving a
+    // MissingFieldError when the template or when-predicate accesses it) surfaces
+    // as a visible error cell rather than crashing the whole bar. The remaining
+    // segments render normally. This is the render-time complement to the per-
+    // variable catch in registerDslConfig — together they implement option-2
+    // partial rendering: the new config stays active, working segments render, and
+    // broken segments show an error cell.
+    try {
+      if (!evaluateWhen(segCompiled.when, ctx.scope)) return [];
+
+      // [LAW:dataflow-not-control-flow] The per-segment variability is WHICH
+      // palette — the base resolver (per-segment override or basePalette)
+      // transposed by hueShift. bg and fg then resolve from this one palette.
+      const resolver = transposedResolver(
+        segCompiled.paletteResolver ?? ctx.basePalette,
+        hueShift,
+      );
+      const baseStyle = resolveSegmentColors(
+        resolver,
+        segCompiled.bg,
+        segCompiled.fg,
+        ctx.scope,
+      );
+
+      const fragments = segCompiled.template.evaluate(ctx.scope);
+      const segCells = fragmentsToCells(fragments, baseStyle);
+
+      // [LAW:single-enforcer] Partition the segment's authored "\n" into visual
+      // lines BEFORE per-segment layout — width/justify/truncate then measure each
+      // line cleanly. A newline-free segment is the degenerate one-line case. Each
+      // laid line is ONE strip item: applySegmentLayout collapses a line's cells to
+      // 0-or-1 item (OSC-8 links survive as interior spans), so the joiner caps only
+      // at the segment's edges, never inside it.
+      const laidLines = splitCellsIntoLines(segCells).map((line) =>
+        applySegmentLayout(line, {
+          width: seg.width ?? "auto",
+          justify: seg.justify ?? "left",
+          truncate: seg.truncate ?? "right",
+          baseStyle,
+        }),
+      );
+
+      if (ctx.perSegmentSink !== undefined) {
+        ctx.perSegmentSink.set(node.name, laidLines.flat());
+      }
+      return laidLines;
+    } catch (err) {
+      return [
+        [
+          new RichText(
+            `⚠ ${node.name}: ${(err as Error).message ?? String(err)}`,
+          ),
+        ],
+      ];
+    }
+  },
+};
+
+// [LAW:single-enforcer] THE registry. `satisfies` forces an entry for every
+// LayoutNode kind — adding a kind to the union breaks compilation here until its
+// behavior is registered, so "register a type" is one mechanically-enforced act.
+const REGISTRY = {
+  container: containerType,
+  segment: segmentType,
+} satisfies { [K in NodeKind]: NodeType<K> };
+
+// [LAW:types-are-the-program] The one dispatch primitive. Indexing by a node's OWN
+// kind returns the entry built FOR that kind, so the pairing is sound by
+// construction; the cast only widens the static K to the union (TS cannot prove
+// the index/arm link across a heterogeneous registry). Every consumer calls
+// nodeType(node.kind).method(node) — no consumer re-switches on kind.
+export function nodeType(kind: NodeKind): NodeType<NodeKind> {
+  return REGISTRY[kind] as unknown as NodeType<NodeKind>;
+}