@promptctl/cc-candybar 1.0.0

package/src/render/picker.ts

@@ -0,0 +1,231 @@
+// [LAW:locality-or-seam] A `{{ picker "applyAction" "pageAction" closeOnPick
+// paged }}` call renders a width-fit grid of option cells over the action table:
+// each option cell APPLIES the named option action (and, when closeOnPick, also
+// resets the named page action's key in the SAME atomic write); ✕/←/→ navigate
+// the page cursor. The picker is a pure RENDER helper — it owns no state and no
+// new gate. It references two ALREADY-declared, ALREADY-gated actions by name
+// (the apply set-option → its option domain + the theme key's allow-list gate;
+// the page set-int → the page key's int gate), so the rendered clicks and the
+// wire gate share one source: the action table.
+//
+// [LAW:one-type-per-behavior] There is no `menu`/`picker` TYPE — a picker is
+// content a segment template pulls in, exactly like `action`. This is the
+// successor to the deleted menu/buttons widget runtime: the same `paginate` fold
+// and ←/→/✕ projection, re-expressed over named actions instead of a widget union.
+//
+// [LAW:dataflow-not-control-flow] Paged vs wrap is ONE value, not a mode: the
+// `paged` flag selects the available width passed to `paginate` (term.cols vs
+// Infinity). Infinite width ⇒ one page ⇒ the long line wraps via FlexStrip; finite
+// ⇒ a sliced page with ←/→. The same fold, same emit pipeline; the width value
+// (and the matching noWrap) select the shape.
+//
+// [LAW:one-way-deps] Lives in render/ (depends on template-engine/ + ./action.js),
+// injected into the engine by the caller (registerDslConfig hands pickerFuncs in
+// as data). The generic engine never imports this module.
+
+import { RichText } from "@promptctl/rich-js";
+import type { FuncMap } from "@promptctl/go-template-js";
+import { toNumber } from "../var-system/types.js";
+import { TERM_COLS_VAR } from "../config/dsl-types.js";
+import { effectsUrl, VERB_SET_STATE } from "../click/wire.js";
+import {
+  linkFragment,
+  readVar,
+  type ActionRuntime,
+  type CompiledActionDecl,
+} from "./action.js";
+
+const PICKER_CLOSE = "✕";
+const PICKER_PREV = "←";
+const PICKER_NEXT = "→";
+
+// [LAW:single-enforcer] One display-width measure — rich-js's cellLength, the
+// same algebra FlexStrip wraps by — so pagination fits the line the strip
+// produces. No second width function.
+function cellWidth(text: string): number {
+  return new RichText(text).cellLength;
+}
+
+// [LAW:dataflow-not-control-flow] A pure function of (item widths, available
+// width, reserved width): greedy fill into pages, each reserving room for the
+// ←/→/✕ affordances. The `page` value selects the slice; an oversized lone item
+// gets its own page (it can't be split). Infinite width = one page (the wrap
+// case — everything on one line, FlexStrip breaks it). Exported for unit testing.
+export function paginate(
+  widths: readonly number[],
+  available: number,
+  reserve: number,
+): number[][] {
+  if (!Number.isFinite(available)) {
+    return widths.length > 0 ? [widths.map((_, i) => i)] : [];
+  }
+  const usable = Math.max(1, available - reserve);
+  const pages: number[][] = [];
+  let cur: number[] = [];
+  let curW = 0;
+  for (let i = 0; i < widths.length; i++) {
+    const w = widths[i]!;
+    if (cur.length === 0) {
+      cur = [i];
+      curW = w;
+    } else if (curW + 1 + w <= usable) {
+      cur.push(i);
+      curW += 1 + w;
+    } else {
+      pages.push(cur);
+      cur = [i];
+      curW = w;
+    }
+  }
+  if (cur.length > 0) pages.push(cur);
+  return pages;
+}
+
+// [LAW:dataflow-not-control-flow] Join link-bearing spans with single-space
+// separators into ONE RichText (a picker is one `{{ picker }}` expression, so it
+// must emit one value; the option/affordance cells ride as spans on it). `noWrap`
+// is the `paged` value: a paged page is one line that must not wrap; a wrap-mode
+// run is the long line FlexStrip is ALLOWED to break across lines.
+function assemble(frags: readonly RichText[], paged: boolean): RichText {
+  const spaced: RichText[] = [];
+  for (const frag of frags) {
+    if (spaced.length > 0) spaced.push(new RichText(" "));
+    spaced.push(frag);
+  }
+  const assembled = RichText.fromFragments(spaced);
+  assembled.noWrap = paged;
+  assembled.end = "";
+  return assembled;
+}
+
+// [LAW:no-defensive-null-guards] The loader proves both picker arg names resolve
+// to declared actions; this asserts the KIND each must be (apply ⇒ set-option,
+// page ⇒ set-int) — a wrong kind is an author error surfaced loudly at render
+// (composeWithDiagnostics shows it), not a silent empty picker.
+function requireKind<K extends CompiledActionDecl["kind"]>(
+  runtime: ActionRuntime,
+  name: string,
+  kind: K,
+  shape: string,
+): Extract<CompiledActionDecl, { kind: K }> {
+  const action = runtime.compiled.get(name);
+  if (!action || action.kind !== kind) {
+    throw new Error(
+      `picker references action "${name}" which must be ${shape}, got ${action ? `a ${action.kind} action` : "no such action"}`,
+    );
+  }
+  return action as Extract<CompiledActionDecl, { kind: K }>;
+}
+
+// [LAW:dataflow-not-control-flow] The page value (and the live width) select
+// which option cells render and which boundary arrows exist — a boundary arrow is
+// an ABSENT fragment, never a skipped branch. Every affordance click is a `set`
+// on the page key: ←/→ navigate (render-computed p±1), ✕ closes (-1). Each option
+// click APPLIES its option AND (when closeOnPick) resets the page key to -1 in one
+// atomic set-state — the picker owns the page key, so it derives the close-write
+// rather than the author re-stating the key.
+function renderPicker(
+  applyName: string,
+  pageName: string,
+  closeOnPick: boolean,
+  paged: boolean,
+  runtime: ActionRuntime,
+): RichText {
+  const apply = requireKind(
+    runtime,
+    applyName,
+    "set-option",
+    "a set-option action ({ set, from })",
+  );
+  const page = requireKind(
+    runtime,
+    pageName,
+    "set-int",
+    "an int action ({ set, int: true })",
+  );
+  const store = runtime.store;
+  if (!store) {
+    throw new Error(
+      `picker "${applyName}" rendered without a VariableStore — registerDslConfig was not given one`,
+    );
+  }
+  const sessionId = readVar(store, "session.id");
+  const current = readVar(store, apply.stateVar);
+  const widths = apply.options.map(cellWidth);
+
+  // ✕ is always present; ←/→ appear only on a multi-page menu. Reserve arrow
+  // space only after a first pass proves it overflows — reserving it
+  // unconditionally is self-fulfilling (a run that fits with just ✕ could be
+  // forced to split, making arrows appear unnecessarily). In wrap mode
+  // (available = Infinity) paginate yields one page, so neither pass splits.
+  const available = paged ? toNumber(store.read(TERM_COLS_VAR)) : Infinity;
+  const closeReserve = cellWidth(PICKER_CLOSE) + 1;
+  const arrowReserve = cellWidth(PICKER_PREV) + 1 + cellWidth(PICKER_NEXT) + 1;
+  const firstPass = paginate(widths, available, closeReserve);
+  const pages =
+    firstPass.length > 1
+      ? paginate(widths, available, closeReserve + arrowReserve)
+      : firstPass;
+
+  // [LAW:no-defensive-null-guards] The page value genuinely may be absent/empty
+  // (the key was never written) — parse it at this trust boundary; an out-of-range
+  // or unset value clamps into the existing page set, so the picker never indexes
+  // a non-existent page. The segment's `when` gates visibility on page >= 0.
+  const rawPage = parseInt(readVar(store, page.stateVar), 10);
+  const pageIdx = Number.isInteger(rawPage)
+    ? Math.max(0, Math.min(rawPage, pages.length - 1))
+    : 0;
+  const pageCells = pages[pageIdx] ?? [];
+
+  const pageUrl = (value: number): string =>
+    effectsUrl([
+      { verb: VERB_SET_STATE, args: [sessionId, page.key, String(value)] },
+    ]);
+  const optionUrl = (option: string): string =>
+    effectsUrl([
+      {
+        verb: VERB_SET_STATE,
+        args: [
+          sessionId,
+          apply.key,
+          option,
+          ...(closeOnPick ? [page.key, "-1"] : []),
+        ],
+      },
+    ]);
+
+  const frags: RichText[] = [linkFragment(PICKER_CLOSE, pageUrl(-1), false)];
+  if (pageIdx > 0) {
+    frags.push(linkFragment(PICKER_PREV, pageUrl(pageIdx - 1), false));
+  }
+  for (const i of pageCells) {
+    const option = apply.options[i]!;
+    frags.push(linkFragment(option, optionUrl(option), option === current));
+  }
+  if (pageIdx < pages.length - 1) {
+    frags.push(linkFragment(PICKER_NEXT, pageUrl(pageIdx + 1), false));
+  }
+  return assemble(frags, paged);
+}
+
+// [LAW:dataflow-not-control-flow] One func; the two action NAMES select which
+// declared effects fire, the two bools are the bounded author choices
+// (closeOnPick, paged). Returns T (RichText), the single fragment go-template-js
+// emits for `{{ picker … }}`.
+//
+// [LAW:one-way-deps] The caller injects this FuncMap into createCcCandybarEngine
+// (capabilities-over-context) so the generic engine never imports the picker.
+export function pickerFuncs(runtime: ActionRuntime): FuncMap {
+  return {
+    picker: {
+      fn: (
+        applyName: string,
+        pageName: string,
+        closeOnPick: boolean,
+        paged: boolean,
+      ) => renderPicker(applyName, pageName, closeOnPick, paged, runtime),
+      argTypes: ["string", "string", "bool", "bool"],
+      returnType: "T",
+    },
+  };
+}

package/src/render/split-lines.ts

@@ -0,0 +1,51 @@
+import type { RichText } from "@promptctl/rich-js";
+
+// [LAW:single-enforcer] THE one place a horizontal cell stream is partitioned
+// into vertical lines. Vertical composition lives on the CELL stream — resolved
+// here, before any strip measures a cell — never inside a strip. A "\n" that
+// reaches a horizontal strip is a zero-width lie: the strip measures a cell by
+// its rendered cell-width, for which an embedded "\n" corrupts wrap math,
+// powerline caps, and background fill. Splitting first means each emitted line
+// is a clean newline-free cell run the strip can measure honestly.
+//
+// [LAW:one-source-of-truth] The line boundary is the literal "\n" carried in a
+// cell's text — the SOLE vertical sentinel. Horizontal cell identity is already
+// carried by segment boundaries and link spans, so only the vertical axis lacks
+// a carrier and only it needs a sentinel.
+
+/**
+ * Partition a cell stream into per-line cell groups on the "\n" sentinel.
+ *
+ * A newline-free cell passes through BY REFERENCE — the common case is
+ * byte-identical to handing the original stream straight to a strip. A cell
+ * carrying "\n" is split via `RichText.split` (span- and OSC-8-preserving, and
+ * it consumes the separator): the piece before the first "\n" closes the
+ * current line, each interior piece is a whole line of its own, and the final
+ * piece begins the next line. The "\n" is consumed as the partition point,
+ * never emitted into a line and never measured.
+ *
+ * An empty input yields `[[]]` — one empty line group, not zero — so a visible
+ * row whose segments all rendered nothing still produces exactly one (empty)
+ * line, matching the pre-substrate behavior.
+ */
+export function splitCellsIntoLines(cells: readonly RichText[]): RichText[][] {
+  const lines: RichText[][] = [];
+  let current: RichText[] = [];
+  for (const cell of cells) {
+    // [LAW:dataflow-not-control-flow] The discriminator is whether the cell
+    // carries the sentinel — a value, read once. The newline-free path keeps
+    // the original reference so the dominant case allocates nothing new.
+    if (!cell.contains("\n")) {
+      current.push(cell);
+      continue;
+    }
+    const pieces = cell.split("\n");
+    current.push(pieces[0]!);
+    for (let i = 1; i < pieces.length; i++) {
+      lines.push(current);
+      current = [pieces[i]!];
+    }
+  }
+  lines.push(current);
+  return lines;
+}

package/src/render/strip.ts

@@ -0,0 +1,103 @@
+import {
+  Strip,
+  RichText,
+  Style,
+  PowerlineJoiner,
+  CapsuleJoiner,
+  PlainJoiner,
+  FlexStrip,
+  renderToString,
+  type Joiner,
+  type ColorSystemSpec,
+} from "@promptctl/rich-js";
+
+export interface RenderedSegmentLike {
+  type: string;
+  text: string;
+  bgHex?: string;
+  fgHex?: string;
+}
+
+export type StripStyle = "powerline" | "capsule" | "plain";
+
+// [LAW:one-source-of-truth] Raw terminal cols we assume when the wire
+// didn't give us one (older client, env-stripped spawn). RAW — not
+// post-reserve — so the Claude-Code-UI reserve applies uniformly across
+// wire and fallback paths (callers thread this through
+// applyClaudeCodeReserve from src/utils/terminal-width).
+export const DEFAULT_TERMINAL_WIDTH = 120;
+
+export interface BuildLineOptions {
+  style: StripStyle;
+  colorCompatibility: ColorSystemSpec;
+  separator?: string;
+  // [LAW:types-are-the-program] Every render carries a width. Finite values
+  // wrap via FlexStrip; Number.POSITIVE_INFINITY renders one unbounded line.
+  // Required (not optional) so callers cannot silently drop the wire's value.
+  width: number;
+}
+
+function pickJoiner(style: StripStyle, separator?: string): Joiner {
+  // [LAW:dataflow-not-control-flow] joiner choice is data-driven; one branch
+  // per shape, no nested conditionals.
+  if (style === "capsule") return new CapsuleJoiner();
+  if (style === "plain") {
+    return new PlainJoiner(separator !== undefined ? { separator } : {});
+  }
+  return new PowerlineJoiner();
+}
+
+function toCell(seg: RenderedSegmentLike): RichText {
+  // Padding mirrors the legacy buildLineFromSegments: one space on each side
+  // of the segment text. The joiners sit between cells; padding sits inside.
+  const padded = ` ${seg.text} `;
+  const style = new Style({
+    bgcolor: seg.bgHex || undefined,
+    color: seg.fgHex || undefined,
+  });
+  return new RichText(padded, { style, end: "", noWrap: true });
+}
+
+/**
+ * [LAW:single-enforcer] The one place RichText cells become an ANSI byte
+ * string. Every render path (DSL RichText[] via the template-engine
+ * pipeline, buildLineStrip's input-shape adapter, debug per-segment
+ * serialization) flows through here. The wrap dispatch lives here too:
+ * finite width → FlexStrip (rich-js owns the wrap algebra); infinite
+ * width → Strip.
+ *
+ * [LAW:dataflow-not-control-flow] The dispatch is on the value, not on a
+ * flag. There is no `wrap: boolean` knob; presence of a finite width IS
+ * the decision.
+ */
+export function renderStripCells(
+  cells: readonly RichText[],
+  options: BuildLineOptions,
+): string {
+  if (cells.length === 0) return "";
+  const joiner = pickJoiner(options.style, options.separator);
+  if (Number.isFinite(options.width)) {
+    const flex = new FlexStrip([...cells], { joiner });
+    const out = renderToString(flex, {
+      width: options.width,
+      colorSystem: options.colorCompatibility,
+    });
+    return out.endsWith("\n") ? out.slice(0, -1) : out;
+  }
+  const strip = new Strip([...cells], joiner);
+  return renderToString(strip, {
+    colorSystem: options.colorCompatibility,
+  });
+}
+
+/**
+ * Input-shape adapter for callers that hold RenderedSegmentLike[] rather
+ * than pre-constructed RichText cells. Wrap behavior is identical to
+ * renderStripCells — the cell construction is the only difference.
+ */
+export function buildLineStrip(
+  segments: readonly RenderedSegmentLike[],
+  options: BuildLineOptions,
+): string {
+  return renderStripCells(segments.map(toCell), options);
+}

package/src/segments/cache.ts

@@ -0,0 +1,131 @@
+// Prompt-cache warmth provider.
+//
+// Anthropic's prompt cache has a fixed TTL (1h): each turn that reads or
+// creates cache entries refreshes it, and after the TTL the next turn pays
+// full cache-creation cost again. This provider answers one question — when
+// does the current session's cache go cold? — by tail-reading the transcript
+// for the most recent entry that touched the cache and projecting its
+// timestamp forward by the TTL.
+//
+// [LAW:dataflow-not-control-flow] The datum is a single epoch instant, not a
+// rendered string. Whether the timer shows "12m", "cold", or hides entirely,
+// and what color it takes, are all functions of this one number evaluated in
+// the DSL template — the same shape block/weekly use with `resetsAt`. The
+// provider carries no display policy.
+//
+// [LAW:types-are-the-program] The return is `Outcome<number>`: a known expiry
+// instant (`ok`), "no cache activity found" (`absent` — no transcript yet, or
+// no cache-bearing entry), or a real read failure (`failed` — the transcript
+// exists but couldn't be read). Absent becomes a missing payload field, which
+// the segment's `when` predicate reads as hidden; failed reaches the payload
+// boundary, the one place that logs it — there is no "0 means hidden"
+// ambiguity to defend against downstream, and no failure dressed as absence.
+
+import { ABSENT, ok, type Outcome } from "../utils/outcome.js";
+import { readTail } from "../utils/transcript-fs.js";
+
+// Anthropic prompt cache TTL. A const, not a knob: it is a property of the
+// upstream cache, not of this renderer. If a future cache tier ships a
+// different TTL, that is a new arm here, not a user config field.
+const CACHE_TTL_MS = 60 * 60 * 1000;
+const TAIL_CHUNK = 64 * 1024;
+const TAIL_MAX = 1 * 1024 * 1024;
+
+// [LAW:types-are-the-program] A cheap CANDIDATE filter, not the authority. It
+// matches any line mentioning a non-zero cache-token field, which includes a
+// line whose *message content* merely quotes the string (a pasted JSON snippet,
+// a transcript of a review discussing these very fields). The authoritative
+// check is the parsed `message.usage` value — the regex only avoids JSON.parsing
+// every line; a match is verified before its timestamp is trusted. The `[1-9]`
+// rejects the `":0` common case so most non-cache lines never reach the parser.
+const CACHE_HIT_RE =
+  /"(?:cache_read_input_tokens|cache_creation_input_tokens)":[1-9]/;
+
+// The transcript-line shape this provider reads. Untrusted JSON — every field is
+// optional and narrowed at use; only positive `message.usage` cache tokens count.
+interface UsageLine {
+  readonly timestamp?: string;
+  readonly message?: {
+    readonly usage?: {
+      readonly cache_read_input_tokens?: number;
+      readonly cache_creation_input_tokens?: number;
+    };
+  };
+}
+
+// Parse a candidate line and return its millisecond timestamp ONLY if its
+// `message.usage` actually records positive cache activity. A content-only
+// mention (or unparseable line) yields null, so a false-positive regex match
+// can never set the timer warm.
+function cacheActivityTs(line: string): number | null {
+  let parsed: UsageLine;
+  try {
+    parsed = JSON.parse(line) as UsageLine;
+  } catch {
+    return null;
+  }
+  const usage = parsed.message?.usage;
+  const positive =
+    (usage?.cache_read_input_tokens ?? 0) > 0 ||
+    (usage?.cache_creation_input_tokens ?? 0) > 0;
+  if (!positive) return null;
+  const ms = parsed.timestamp != null ? Date.parse(parsed.timestamp) : NaN;
+  return Number.isNaN(ms) ? null : ms;
+}
+
+/**
+ * Epoch *seconds* at which the session's prompt cache expires; `absent` when
+ * no cache-bearing transcript entry can be found; `failed` when the
+ * transcript exists but couldn't be read. Seconds (not millis) to match the
+ * unit of block/weekly `resetsAt`, so the DSL composes
+ * `minutesUntilReset .cache.expiresAt` with no unit translation.
+ */
+export async function cacheExpiresAt(
+  transcriptPath: string,
+): Promise<Outcome<number>> {
+  const lastCacheMs = await findLastCacheActivityTs(transcriptPath);
+  if (lastCacheMs.kind !== "ok") return lastCacheMs;
+  return ok(Math.floor((lastCacheMs.value + CACHE_TTL_MS) / 1000));
+}
+
+// Tail-read the JSONL transcript and return the millisecond timestamp of the
+// last entry with cache activity. The relevant entry is almost always within
+// the final few KB, so the common case reads one TAIL_CHUNK; only a transcript
+// whose last cache hit is deeper grows to TAIL_MAX. [LAW:single-enforcer] both
+// reads go through the gated transcript-fs seam (readTail), so this scanner is
+// bounded with every other transcript read instead of blocking the event loop
+// on synchronous fs.
+async function findLastCacheActivityTs(
+  transcriptPath: string,
+): Promise<Outcome<number>> {
+  for (const maxBytes of [TAIL_CHUNK, TAIL_MAX]) {
+    const tail = await readTail(transcriptPath, maxBytes);
+    // absent (no transcript yet) and failed (unreadable) both end the scan;
+    // the outcome carries which one happened to the payload boundary.
+    if (tail.kind !== "ok") return tail;
+    const ts = scanBufferForLastCacheTs(tail.value.buf, tail.value.fromStart);
+    if (ts != null) return ok(ts);
+    // The window reached the file start: the whole transcript is scanned, no
+    // hit exists — growing further would re-read the same bytes.
+    if (tail.value.fromStart) return ABSENT;
+  }
+  return ABSENT;
+}
+
+function scanBufferForLastCacheTs(
+  buf: Buffer,
+  bufStartsAtFileBeginning: boolean,
+): number | null {
+  const text = buf.toString("utf8");
+  const lines = text.split("\n");
+  // When the window doesn't start at the file beginning, the first line is
+  // likely a partial JSON object — skip it so we never mis-parse a fragment.
+  const start = bufStartsAtFileBeginning ? 0 : 1;
+  for (let i = lines.length - 1; i >= start; i--) {
+    const line = lines[i];
+    if (!line || !CACHE_HIT_RE.test(line)) continue; // cheap candidate filter
+    const ts = cacheActivityTs(line); // authoritative: parsed usage must be > 0
+    if (ts != null) return ts;
+  }
+  return null;
+}