@promptctl/cc-candybar 1.42.1 → 1.43.0

package/src/daemon/debug-types.ts

@@ -1,91 +0,0 @@
-// [LAW:types-are-the-program] Wire-level snapshot shapes for the `debug`
-// protocol message. The `what` discriminator carries the response shape
-// forward — a client requesting "vars" gets vars data, "segments" gets
-// segments data, "config" gets config data. There is no `data: unknown`
-// field that callers must shape-check.
-//
-// [LAW:one-source-of-truth] These types are the single contract between the
-// daemon's introspection layer (src/daemon/debug.ts) and any external
-// consumer (the future `cc-candybar vars` / `lint` CLIs, debug tooling).
-// The protocol wraps them; the introspector produces them.
-//
-// Lives in its own module to break a potential cycle: protocol.ts re-exports
-// these for the wire type, debug.ts produces them, and both could otherwise
-// pull each other in.
-
-import type { VarType, VarValue } from "../var-system/types";
-import type { DslConfig, SourceKind } from "../config/dsl-types";
-
-// [LAW:one-source-of-truth] DEBUG_WHATS is the canonical list; DebugWhat is
-// *derived* from it via indexed access on the `as const` tuple type. Adding
-// a new entry to the array automatically expands DebugWhat — and the switch
-// in buildDebugSnapshot (src/daemon/debug.ts) becomes non-exhaustive,
-// failing the typecheck until a new arm is added. The dispatcher arm and
-// the canonical list are kept in lockstep by the type system, not by
-// human discipline.
-export const DEBUG_WHATS = ["vars", "segments", "config"] as const;
-export type DebugWhat = (typeof DEBUG_WHATS)[number];
-
-// Wire-side type guard for an untrusted JSON value. Used by the daemon at
-// the request boundary; symmetrically usable by future CLI shims that
-// validate user input before sending the frame.
-// [LAW:one-source-of-truth] Implemented in terms of DEBUG_WHATS so the
-// guard cannot drift from the canonical list — a new `what` added to
-// DEBUG_WHATS becomes accepted by isDebugWhat with no second-site edit.
-export function isDebugWhat(v: unknown): v is DebugWhat {
-  return (
-    typeof v === "string" && (DEBUG_WHATS as readonly string[]).includes(v)
-  );
-}
-
-// One row of the `vars` snapshot. Captures everything an operator needs to
-// answer "is this variable computing? did it fail? when did it last update?"
-// without re-reading config or grepping logs.
-export interface VarSnapshot {
-  readonly name: string;
-  // The DSL source kind that declared this variable (literal/env/input/...).
-  // null when a variable exists in the store but was not declared via DSL —
-  // present for completeness so a programmatic-only var still shows up in
-  // introspection rather than being silently invisible.
-  readonly source: SourceKind | null;
-  readonly type: VarType;
-  // Current store value. For Computed nodes this triggers re-evaluation if
-  // MobX has invalidated the cache; for Box nodes it is the last value set.
-  readonly value: VarValue;
-  readonly lastError: {
-    readonly timestampMs: number;
-    readonly message: string;
-  } | null;
-  // Wall-clock ms since the box was last set (Box) or null for Computed
-  // nodes whose freshness is governed by MobX invalidation, not a single
-  // timestamp. Null is structurally distinct from 0 so consumers can
-  // distinguish "no age tracking applies" from "just updated."
-  readonly ageMs: number | null;
-}
-
-// One row of the `segments` snapshot.
-export interface SegmentSnapshot {
-  readonly name: string;
-  // The template source string (verbatim, as authored in the config).
-  readonly template: string;
-  // Names of variables potentially referenced by the template, found via
-  // static analysis: dotted paths inside `{{ ... }}` actions, matched
-  // against the store's declared names. Exact runtime deps may be a subset
-  // (branches not taken), but every name returned IS in the store.
-  readonly referencedVars: readonly string[];
-  // The last rendered output for this segment, when the daemon has captured
-  // one. null today — the daemon does not yet render through the DSL spine
-  // (see bzh.2). Populated when the daemon flips to renderDsl.
-  readonly lastRender: string | null;
-}
-
-// [LAW:types-are-the-program] The discriminated union ensures every response
-// carries exactly the data shape its `what` promises. There is no path that
-// produces e.g. `{ what: "vars", segments: [...] }` — the type forbids it.
-export type DebugSnapshot =
-  | { readonly what: "vars"; readonly vars: readonly VarSnapshot[] }
-  | {
-      readonly what: "segments";
-      readonly segments: readonly SegmentSnapshot[];
-    }
-  | { readonly what: "config"; readonly config: DslConfig | null };

package/src/daemon/debug.ts

@@ -1,264 +0,0 @@
-// [LAW:single-enforcer] One module owns the projection from daemon DSL
-// state (VariableStore + SourceRegistry + DslConfig + CompiledConfig) to
-// the wire-level DebugSnapshot. buildDebugSnapshot dispatches via an
-// exhaustive switch on `what` — TypeScript enforces every DebugWhat arm
-// at compile time (the function's return-type narrowing fails if a case
-// is missing), so adding a new `what` requires one new arm here, one new
-// DEBUG_WHATS entry, and one new DebugSnapshot variant — the type system
-// keeps the three sites in lockstep.
-//
-// [LAW:one-source-of-truth] The introspector reads through the live
-// VariableStore (current values), SourceRegistry (lastErrors), VarNode
-// (lastUpdatedMs), and DslConfig (declared source kinds, segment templates).
-// There is no parallel cache, no shadow snapshot kept in sync — the daemon
-// has one DSL state and this module projects it.
-//
-// [LAW:dataflow-not-control-flow] The state slot (DaemonDslState | null) is
-// the only branch: null state → empty snapshots; populated state → real
-// snapshots. No special-case introspection paths for the "DSL not active
-// yet" case — the same code produces both outcomes from the same data.
-//
-// Today the daemon does not yet hold a DSL state (bzh.2 has not fired); all
-// snapshots are empty in production. When bzh.2 wires the store, the
-// snapshots populate without any change to this module or the protocol.
-
-import type { VariableStore } from "../var-system/store";
-import type { SourceRegistry } from "../var-system/sources";
-import type { DslConfig, SourceKind, VariableDecl } from "../config/dsl-types";
-import { walkNodes } from "../config/dsl-types";
-import { extractTemplateRefs } from "../config/dsl-loader";
-import type { CompiledConfig } from "../dsl/render";
-import type {
-  DebugSnapshot,
-  DebugWhat,
-  SegmentSnapshot,
-  VarSnapshot,
-} from "./debug-types";
-
-// The daemon's DSL state. Bundled because the four fields are co-installed
-// by registerDslConfig — exposing them as independently-optional would let
-// callers represent illegal combinations (e.g. store with no config).
-export interface DaemonDslState {
-  readonly store: VariableStore;
-  readonly registry: SourceRegistry;
-  readonly config: DslConfig;
-  readonly compiled: CompiledConfig;
-  // [LAW:dataflow-not-control-flow] Per-segment last-render strings live in
-  // the same state bundle the renderer mutates. Today (legacy renderer) it
-  // is empty; bzh.2 populates it from inside renderDsl.
-  readonly lastRenderBySegment: ReadonlyMap<string, string>;
-}
-
-// ─── Dispatcher ──────────────────────────────────────────────────────────────
-
-// [LAW:dataflow-not-control-flow] One arm per `what` — the discriminator is
-// data; the branch chooses the projection function, not whether projection
-// runs. Adding a new `what` is one new arm + one new projection + one new
-// DebugSnapshot variant — the type system enforces all three.
-export function buildDebugSnapshot(
-  what: DebugWhat,
-  state: DaemonDslState | null,
-): DebugSnapshot {
-  switch (what) {
-    case "vars":
-      return { what, vars: introspectVars(state) };
-    case "segments":
-      return { what, segments: introspectSegments(state) };
-    case "config":
-      return { what, config: introspectConfig(state) };
-  }
-}
-
-// ─── vars ────────────────────────────────────────────────────────────────────
-
-// Project every variable currently registered in the store into one
-// VarSnapshot. Names sorted for deterministic snapshot tests. Source kind
-// is looked up from the DslConfig (top-level variables + per-segment
-// `vars` blocks); a variable not found in either is reported with
-// source=null so it still appears in introspection.
-export function introspectVars(
-  state: DaemonDslState | null,
-): readonly VarSnapshot[] {
-  if (state === null) return [];
-
-  const { store, registry, config } = state;
-  const sourceByName = buildSourceKindIndex(config);
-  const names = store.names().sort();
-
-  const out: VarSnapshot[] = [];
-  for (const name of names) {
-    // [LAW:single-enforcer] One requireNode lookup per row. Reading the
-    // value through node.read() instead of store.read(name) avoids a
-    // second Map.get + requireNode round-trip in the inner loop and
-    // makes the per-row data dependency obvious: every field below
-    // comes from this one node.
-    const node = store.getNode(name);
-    const err = registry.getLastError(name);
-    // [LAW:no-defensive-null-guards] No try/catch around node.read():
-    // every SourceRegistry-declared variable either holds a typed
-    // fallback (declareShell/declareFile/declareGit/declareInput catch
-    // internally and write a fallback) or is a computed whose deriver
-    // also catches (declareTemplate). Cycles are detected eagerly at
-    // register time (declareTemplate's force-read). So a read-throw
-    // here would be a *programming* error, not a runtime condition
-    // the snapshot should mask. Letting it propagate keeps the failure
-    // loud at the source instead of laundering it as a synthesized
-    // lastError with an unstable Date.now() timestamp.
-    //
-    // [LAW:single-enforcer] lastError is sourced from SourceRegistry
-    // only. There is no second timestamp-producer that could drift
-    // from the registry's record.
-    out.push({
-      name,
-      source: sourceByName.get(name) ?? null,
-      type: node.type,
-      value: node.read(),
-      lastError:
-        err !== undefined
-          ? { timestampMs: err.timestamp, message: err.message }
-          : null,
-      ageMs: ageFromNode(node.lastUpdatedMs()),
-    });
-  }
-  return out;
-}
-
-function ageFromNode(lastUpdatedMs: number | null): number | null {
-  if (lastUpdatedMs === null) return null;
-  return Math.max(0, Date.now() - lastUpdatedMs);
-}
-
-// Build a name → SourceKind index from the DslConfig. Walks top-level
-// variables and each segment's per-segment vars block; segment-local vars
-// live under the namespaced key `<segName>.<varName>` in the store (same
-// shape registerDslConfig uses to declare them).
-function buildSourceKindIndex(
-  config: DslConfig,
-): ReadonlyMap<string, SourceKind> {
-  const index = new Map<string, SourceKind>();
-  for (const [name, decl] of Object.entries(config.variables)) {
-    index.set(name, sourceKindOf(decl));
-  }
-  for (const [segName, seg] of Object.entries(config.segments)) {
-    if (!seg.vars) continue;
-    for (const [varName, decl] of Object.entries(seg.vars)) {
-      index.set(`${segName}.${varName}`, sourceKindOf(decl));
-    }
-  }
-  return index;
-}
-
-function sourceKindOf(decl: VariableDecl): SourceKind {
-  return decl.kind;
-}
-
-// ─── segments ────────────────────────────────────────────────────────────────
-
-export function introspectSegments(
-  state: DaemonDslState | null,
-): readonly SegmentSnapshot[] {
-  if (state === null) return [];
-
-  const { store, config, lastRenderBySegment } = state;
-  const declaredNames = new Set(store.names());
-  // [LAW:dataflow-not-control-flow] Walk in layout order so the introspection
-  // snapshot mirrors render order — operators reading the snapshot see the
-  // same sequence the bar produces, not an alphabetical reshuffling.
-  const segNames = orderedSegmentNames(config);
-
-  const out: SegmentSnapshot[] = [];
-  for (const name of segNames) {
-    const seg = config.segments[name];
-    if (!seg) continue;
-    out.push({
-      name,
-      template: seg.template,
-      referencedVars: extractReferencedVars(seg.template, declaredNames),
-      lastRender: lastRenderBySegment.get(name) ?? null,
-    });
-  }
-  return out;
-}
-
-// Layout order, with any declared-but-not-laid-out segments appended in
-// declaration order so they still appear in the snapshot (an operator
-// debugging "why isn't this rendering" wants to see the segment, not have
-// it filtered out for being absent from layout).
-function orderedSegmentNames(config: DslConfig): readonly string[] {
-  const out: string[] = [];
-  const seen = new Set<string>();
-  for (const node of walkNodes(config.root)) {
-    if (node.kind !== "segment") continue;
-    if (config.segments[node.name] && !seen.has(node.name)) {
-      out.push(node.name);
-      seen.add(node.name);
-    }
-  }
-  for (const name of Object.keys(config.segments)) {
-    if (!seen.has(name)) {
-      out.push(name);
-      seen.add(name);
-    }
-  }
-  return out;
-}
-
-// [LAW:single-enforcer] Static analysis of which variables a segment
-// template references. Raw candidate extraction (find dotted paths inside
-// `{{ ... }}` actions, strip string literals so `{{ printf ".foo" }}`
-// does not falsely match a declared `foo`) is delegated to
-// extractTemplateRefs in src/config/dsl-loader.ts — that helper already
-// owns the template-ref parsing rules and is exercised by the loader's
-// cycle detector. Reusing it means a future improvement to the parser
-// (e.g. supporting `$x.field` variable references) lands here for free.
-//
-// Static analysis (not runtime evaluation) is the right tool here:
-// evaluation would couple introspection to a working store and would
-// vary by current values (if/with branches taken). Static finds every
-// potentially-referenced name regardless of current state — which is
-// what an operator debugging "what does this segment depend on" needs.
-//
-// This function adds the introspection-specific layers on top of the raw
-// extraction:
-//   1. Intersect with the declared-name set (only report names that exist).
-//   2. Ancestor credit: a candidate `.session.id.extra` resolves to the
-//      declared `session.id` if `extra` is not declared.
-//   3. Sort the result for deterministic snapshots.
-export function extractReferencedVars(
-  template: string,
-  declared: ReadonlySet<string>,
-): readonly string[] {
-  const found = new Set<string>();
-  for (const candidate of extractTemplateRefs(template)) {
-    if (declared.has(candidate)) {
-      found.add(candidate);
-      continue;
-    }
-    // Drop trailing segments until we hit a declared name. Handles
-    // `.session.id.something_extra` where only `session.id` is declared —
-    // still credit it as a reference to `session.id`.
-    const parts = candidate.split(".");
-    while (parts.length > 1) {
-      parts.pop();
-      const prefix = parts.join(".");
-      if (declared.has(prefix)) {
-        found.add(prefix);
-        break;
-      }
-    }
-  }
-  return Array.from(found).sort();
-}
-
-// ─── config ──────────────────────────────────────────────────────────────────
-
-// [LAW:no-defensive-null-guards] No defensive copy. DslConfig is `readonly`
-// throughout and the wire-encoder JSON-serializes it; downstream callers
-// see a fresh value. Returning the live reference is the cheapest correct
-// answer.
-export function introspectConfig(
-  state: DaemonDslState | null,
-): DslConfig | null {
-  if (state === null) return null;
-  return state.config;
-}