@promptctl/cc-candybar 1.42.1 → 1.43.0

package/src/config/disclosure.ts

@@ -1,170 +0,0 @@
-// [LAW:one-source-of-truth] THE disclosure primitive: the one toggle machinery
-// that both group sugar (`kind: "group"`, src/config/loader/layout.ts) and the
-// `{{ menu }}` helper (src/config/loader/menu-synth.ts + src/render/menu.ts) are
-// built on. A disclosure is a binary toggle over a SessionState key: the key
-// holds either the CLOSED sentinel or a single MEMBER name; a `cycle` action
-// flips between the two; a ▸/▾ glyph shows which state it is in; sibling
-// disclosures sharing one key become mutually exclusive (an accordion) because
-// one key holds one open member. Group and menu differ ONLY in their BODY (group
-// reveals an arbitrary layout container gated by a `when`; menu drops a picker
-// grid below the row) and in where the trigger lives (group synthesizes a toggle
-// segment; the menu helper IS the trigger). The toggle itself — sentinel, glyphs,
-// the `state` var, the `cycle` action — is single-sourced HERE so the two
-// body-kinds cannot drift [LAW:one-type-per-behavior][LAW:decomposition].
-//
-// [LAW:one-way-deps] This module is intentionally PURE — it imports only decl
-// TYPES (erased at build) and holds no loader (`ValidateCtx`, diagnostics) nor
-// render (rich-js) dependency, so both the loader synthesis passes and the render
-// helper can share it without dragging one layer into the other. The loader-side
-// reserved-namespace collision check — the other half of the shared machinery,
-// which needs the validation context — lives in
-// `src/config/loader/reserved-namespace.ts`.
-
-import type { ActionDecl } from "./action.js";
-import type { VariableDecl } from "./dsl-types.js";
-
-// The "nothing open" sentinel a disclosure's key starts from and returns to on
-// close. A disclosure's MEMBER (a group name / a menu apply-action name) may
-// never equal this — an equal member would make the cycle `[closed, "closed"]`
-// (two identical members, never openable), which both synthesis passes reject.
-export const DISCLOSURE_CLOSED = "closed";
-
-// [LAW:representation] The disclosure glyph vocabulary — one pair for the whole
-// bar so every disclosure reads the same (trailing the label/content it gates,
-// per pdu.8): collapsed ▸, expanded ▾.
-//
-// [LAW:one-source-of-truth] These are the AUTHORED default, never an emission.
-// Every disclosure splices them into the template it synthesizes — group sugar
-// (loader/layout.ts), the settings menu (settings-menu.ts), the bundled drawer
-// — and a hand-authored config writes whichever glyph it likes, because the
-// trigger's text is a display bound at the call site like any other. Until
-// candybar-settings-ui-aok.4 `{{ menu }}` was the exception, appending ▸/▾ from
-// its own runtime where no author could see or decline it, which is how edit
-// mode's `+` came to render `+▸`.
-export const DISCLOSURE_GLYPH_CLOSED = "▸";
-export const DISCLOSURE_GLYPH_OPEN = "▾";
-
-// [LAW:one-source-of-truth] The glyph that CLOSES an open disclosure. The
-// picker body's ✕ has always been this; it lives here now because a trigger can
-// wear it too — edit mode's `+` does, since a `+` whose only open-state cue was
-// the ▸ this change removed would otherwise be indistinguishable from its
-// siblings (three insertion points render byte-identically when one is open,
-// and their dropped bodies are identical too, so row 0 is the only place the
-// answer can live). Two affordances, one meaning, one glyph.
-export const DISCLOSURE_GLYPH_CLOSE = "✕";
-
-// [LAW:single-enforcer] THE display rule every multi-state trigger obeys: bind
-// one display per member, or ONE static display that shows in every state. It
-// lives here, beside the toggle machinery, because both disclosure kinds need
-// it at different times — the loader can count a call's arguments statically
-// and wants an ISSUE to report, the renderer holds the evaluated displays and
-// wants to THROW — and a rule spelled once in each place is a rule that drifts.
-// A `{{ menu }}` folds through it with two members (its `[closed, member]`
-// cycle) and a cycle `{{ action }}` with as many as it declares; nothing about
-// the rule is disclosure-specific beyond who calls it.
-export function cycleDisplayIssue(
-  subject: string,
-  count: number,
-  members: number,
-): string | undefined {
-  if (count === 0) return `${subject} needs a display (the clickable text)`;
-  if (count !== 1 && count !== members) {
-    return `${subject} cycles ${members} members; bind one display per member (${members}) or one static display, got ${count}`;
-  }
-  return undefined;
-}
-
-// [LAW:dataflow-not-control-flow] Which display shows is a pure function of
-// (bound displays, current member index): a single static display shows in
-// every state, per-member displays index by the state. Throws the one rule's
-// text rather than silently dropping or repeating an argument.
-export function pickCycleDisplay(
-  subject: string,
-  displays: readonly string[],
-  members: number,
-  index: number,
-): string {
-  const issue = cycleDisplayIssue(subject, displays.length, members);
-  if (issue !== undefined) throw new Error(issue);
-  return displays.length === 1 ? displays[0]! : displays[index]!;
-}
-
-// [LAW:one-source-of-truth] Go-template string-literal escaping for any DISPLAY
-// text a synthesis splices INSIDE a quoted `{{ }}` argument of a template it
-// emits — a group's label, a preset name in the reset banner, a `(?)` trigger's
-// closed/open glyphs. NOT for a template's own body text, which is source rather
-// than a splice: a help line is assigned verbatim (help.ts) because escaping one
-// would put a backslash on the bar. It lives here, beside the two splices
-// that need it most, because it was already two verbatim copies (loader/layout.ts
-// and edit-chrome.ts, whose comment deferred the merge until "one small rule"
-// earned its own home). The `(?)` affordance was the third caller, so it did.
-export function escapeTemplateLiteral(s: string): string {
-  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-}
-
-// [LAW:types-are-the-program] One open disclosure, named by the two strings that
-// decide it: the VARIABLE a body reads and the MEMBER value that means "this one
-// is open". They are distinct because a group's variable is per-group
-// (`groups.<name>`) while its state KEY may be shared with accordion siblings —
-// so the pair, never a lone key, is what identifies an open state.
-export interface DisclosureRef {
-  readonly variable: string;
-  readonly member: string;
-}
-
-// [LAW:single-enforcer] THE body predicate a disclosure implies. Variadic
-// because nesting is conjunction and nothing else: a row inside two disclosures
-// is open when both are, which is one list, not a compound spelling. Callers
-// that used to hand-write `{{ eq .x "open" }}` beside `{{ and (eq .x "open")
-// (eq .y "open") }}` now pass one ref or two to one function — the shape stops
-// varying with the depth [LAW:dataflow-not-control-flow].
-//
-// `and` is variadic in Go templates and returns its sole argument when given
-// one, so the single-disclosure case needs no separate spelling.
-//
-// [LAW:types-are-the-program] The first ref is a separate parameter so a gate
-// over ZERO disclosures — which would emit an argument-less `{{ and }}` and gate
-// on nothing — is unrepresentable, with no runtime guard to state it.
-export function disclosureGate(
-  first: DisclosureRef,
-  ...rest: readonly DisclosureRef[]
-): string {
-  const terms = [first, ...rest]
-    .map((o) => `(eq .${o.variable} "${escapeTemplateLiteral(o.member)}")`)
-    .join(" ");
-  return `{{ and ${terms} }}`;
-}
-
-// [LAW:single-enforcer] THE trigger template a disclosure's toggle segment
-// carries: one `{{ action }}` over the cycle action, binding the author's text
-// per state — closed first, matching the cycle's own closed-first member order
-// so the display index and the member index are the same number. Since .4 every
-// trigger authors its own text (the runtime appends no glyph), which makes this
-// the one place the binding is spelled; before it, five sites spelled it and the
-// `+▸` double-glyph bug lived in the gap between two of them.
-export function disclosureTrigger(
-  action: string,
-  closed: string,
-  open: string,
-): string {
-  return `{{ action "${action}" "${escapeTemplateLiteral(closed)}" "${escapeTemplateLiteral(open)}" }}`;
-}
-
-// [LAW:single-enforcer] THE backing `state` variable a disclosure key implies:
-// it holds the open member's name and defaults to `def` (the CLOSED sentinel for
-// an independent disclosure, or an initially-open member for a group's
-// `open: true`). One shape, so a group var and a menu var declared on one key
-// cannot disagree on kind or key.
-export function disclosureStateVar(key: string, def: string): VariableDecl {
-  return { kind: "state", key, default: def };
-}
-
-// [LAW:single-enforcer] THE toggle action a disclosure realizes: a binary `cycle`
-// between the CLOSED sentinel and the member (ordered closed-first, so an unset or
-// sibling-held key counts as the first member — the toggle renders ▸ and a click
-// writes the member, opening it and auto-closing any accordion sibling). The
-// derived click gate (`deriveActionValidators`) reads this like every other
-// `set`, so a disclosure toggle needs no parallel verb [LAW:single-enforcer].
-export function disclosureCycleAction(key: string, member: string): ActionDecl {
-  return { set: key, cycle: [DISCLOSURE_CLOSED, member] };
-}

package/src/config/dsl-loader.ts

@@ -1,339 +0,0 @@
-// [LAW:one-type-per-behavior] Three primitives, three concerns:
-//
-//   parseDslConfig (text → RawDslConfig)
-//     JSON5 syntax + per-record structural validation. Rejects the removed
-//     `layout:` key and `kind:"cells"` node with migration-pointing errors.
-//     Throws ConfigError on syntax / structural problems.
-//
-//   mergeWithDefault (RawDslConfig + DslConfig → DslConfig)
-//     Cascade: shallow merge globals fields, by-name merge variables and
-//     segments, wholesale root replacement when present. Pure function.
-//
-//   validateConfig (DslConfig → ValidatedConfig)
-//     Cross-references + cycle detection on the merged shape. Sole producer
-//     of ValidatedConfig. Throws ConfigError on cross-ref / cycle problems.
-//
-// loadConfig (path|null → DslConfig) wires parse+merge for the daemon's
-// production path. validateConfig finishes the chain.
-//
-// [LAW:dataflow-not-control-flow] Validation passes accumulate issues into
-// a list; consumers see every problem at once (compiler-style).
-//
-// This file is the pipeline orchestrator + the public barrel. Each validation
-// concern lives in its own `loader/` module (split by change-reason); the
-// re-exports below keep the import surface stable for every consumer.
-
-import fs from "node:fs";
-import JSON5 from "json5";
-import {
-  type DslConfig,
-  type RawDslConfig,
-  type ValidatedConfig,
-} from "./dsl-types.js";
-import { listResolvablePaletteNames } from "../themes/policy.js";
-import {
-  ConfigError,
-  findKeyLine,
-  type ConfigIssue,
-} from "./loader/diagnostics.js";
-import {
-  describeType,
-  isPlainObject,
-  type Mutable,
-  type ValidateCtx,
-} from "./loader/validate-core.js";
-import { mergeWithDefault } from "./loader/merge.js";
-import { validateEditGlobals, validateGlobals } from "./loader/globals.js";
-import { validateVariables } from "./loader/variables.js";
-import { validateSegments } from "./loader/segments.js";
-import { synthesizeGroupDecls, validateRoot } from "./loader/layout.js";
-import { synthesizeMenuDecls } from "./loader/menu-synth.js";
-import { synthesizeEditModeToggle } from "./loader/edit-mode.js";
-import { synthesizeEditChrome } from "./edit-chrome.js";
-import { SETTINGS_NS, synthesizeSettingsMenu } from "./settings-menu.js";
-import { reservedNamespaceCollisions } from "./loader/reserved-namespace.js";
-import { validateActions } from "./loader/actions.js";
-import { validateLooks } from "./loader/looks.js";
-import { validatePresets } from "./loader/presets.js";
-import { validateHelpers } from "./loader/helpers.js";
-import { validateCrossReferences } from "./loader/cross-ref.js";
-import { validateNoCycles } from "./loader/cycles.js";
-
-// ─── Public barrel ───────────────────────────────────────────────────────────
-// [LAW:locality-or-seam] Consumers import from `dsl-loader`; the internal split
-// is invisible to them. Moving a symbol between loader/ modules never touches a
-// callsite as long as it stays re-exported here.
-
-export { ConfigError, findKeyLine } from "./loader/diagnostics.js";
-export type { ConfigIssue } from "./loader/diagnostics.js";
-export {
-  expandHome,
-  dslConfigCandidatePaths,
-  resolveDslConfigPath,
-  detectConfigCollisions,
-} from "./loader/discovery.js";
-export {
-  mergeWithDefault,
-  applySegmentPaletteOverrides,
-} from "./loader/merge.js";
-export {
-  extractTemplateRefs,
-  extractActionRefs,
-  extractPickerMenuRefs,
-} from "./loader/refs.js";
-
-// ─── Three-stage pipeline ────────────────────────────────────────────────────
-
-/**
- * Load a JSON5 DSL config file from disk and merge it with the given
- * default. Returns the effective DslConfig AND the raw source text.
- *
- * `path = null` means "no user file exists" — returns `dflt` unchanged
- * (uniform merge against an empty raw, which is deep-equal to `dflt`) and
- * an empty source. No consumer branches on file presence; that branch lives
- * inside loadConfig exactly once.
- *
- * [LAW:one-way-deps] `dflt` is a required parameter, not a default pointing at
- * DEFAULT_DSL_CONFIG: this module is generic merge/parse machinery, and
- * DEFAULT_DSL_CONFIG is a specific, higher-level instance built ON TOP of it
- * (default-dsl-config.ts imports parseDslConfig/mergeWithDefault to
- * synthesize itself — see that file). A default param here pointing back at
- * DEFAULT_DSL_CONFIG would make this generic module depend on its own
- * specific consumer — a cycle every caller who wants "the bundled default"
- * resolves explicitly by importing DEFAULT_DSL_CONFIG themselves.
- *
- * [LAW:one-source-of-truth] The source is returned alongside the config so the
- * caller can hand it to validateConfig — cross-ref diagnostics (line numbers,
- * the authored-surface discriminator) are derived from it, and the file is read
- * exactly once here rather than re-read downstream.
- *
- * Throws ConfigError on JSON5 syntax / structural / per-record validation
- * failures. Cross-references and cycles are validateConfig()'s job.
- *
- * [LAW:dataflow-not-control-flow] One function, one branch, same operations
- * each call.
- */
-export function loadConfig(
-  path: string | null,
-  dflt: DslConfig,
-  allowedPalettes?: ReadonlySet<string>,
-): { config: DslConfig; source: string } {
-  const source = path === null ? "" : fs.readFileSync(path, "utf-8");
-  const raw: RawDslConfig =
-    path === null ? {} : parseDslConfig(path, source, allowedPalettes);
-  return { config: mergeWithDefault(raw, dflt), source };
-}
-
-/**
- * Promote a merged DslConfig to a ValidatedConfig by running cross-references
- * and cycle detection. Sole producer of ValidatedConfig in the codebase — the
- * phantom brand makes "the renderer never receives an unvalidated config" a
- * compile-time invariant, not a runtime convention.
- *
- * Throws ConfigError aggregating every issue.
- *
- * [LAW:single-enforcer] One cast site, here, exclusive.
- */
-export function validateConfig(
-  config: DslConfig,
-  filePath = "<config>",
-  source = "",
-  allowedPalettes: ReadonlySet<string> = new Set(listResolvablePaletteNames()),
-): ValidatedConfig {
-  const issues: ConfigIssue[] = [];
-  const ctx: ValidateCtx = { source, issues, allowedPalettes, groups: [] };
-  validateCrossReferences(ctx, config);
-  validateNoCycles(ctx, config);
-  if (issues.length > 0) {
-    throw new ConfigError(filePath, issues);
-  }
-  // [LAW:one-source-of-truth] Edit-mode's CHROME half (brandon-layout-edit-
-  // 2gc.3), synthesized HERE — not in parseDslConfig alongside the toggle —
-  // because it needs the fully merged, preset-resolved, rootOps-replayed
-  // tree cross-ref/cycles just proved sound. Its own output (segment refs
-  // into freshly-synthesized segments, actions into freshly-synthesized
-  // actions) is correct by construction and does not re-enter cross-ref/
-  // cycle checking, exactly as group/menu synthesis's output doesn't either.
-  // [LAW:dataflow-not-control-flow] candybar-settings-ui-aok.1's global settings
-  // menu, spliced BEFORE edit chrome so edit chrome walks the final content tree
-  // and treats the menu's reserved `settings.` names as chrome-exempt — the
-  // full ordering argument lives in settings-menu.ts's header, beside the pass
-  // it governs.
-  const withChrome = synthesizeEditChrome(synthesizeSettingsMenu(config));
-  return withChrome as ValidatedConfig;
-}
-
-/**
- * Parse a JSON5 DSL config source into a RawDslConfig. JSON5 syntax + per-
- * record structural validation. Cross-references and cycles are NOT checked
- * here — they belong to validateConfig, which runs on the merged shape.
- *
- * Returned shape preserves absence: top-level keys are optional in RawDslConfig.
- *
- * `allowedPalettes` is the set of palette names a `palette:` field may name.
- * It defaults to every name that resolves to a concrete Palette, so production
- * always validates loudly against the real registry. Tests inject a custom set
- * to exercise validation without depending on registry contents.
- */
-export function parseDslConfig(
-  filePath: string,
-  source: string,
-  allowedPalettes: ReadonlySet<string> = new Set(listResolvablePaletteNames()),
-): RawDslConfig {
-  // ── Stage 1: JSON5 syntax. A parse error here is single, immediate, and
-  // carries line/col from the json5 package — no point continuing to other
-  // passes that need a parsed structure to inspect.
-  const raw = parseJson5OrThrow(filePath, source);
-
-  const issues: ConfigIssue[] = [];
-  const ctx: ValidateCtx = { source, issues, allowedPalettes, groups: [] };
-
-  // ── Stage 2: top-level shape + per-record shape. Absence survives as
-  // `undefined` in the returned RawDslConfig.
-  if (!isPlainObject(raw)) {
-    throw new ConfigError(filePath, [
-      {
-        path: "",
-        message: `Config root must be an object, got ${describeType(raw)}`,
-      },
-    ]);
-  }
-
-  const topLevel = validateTopLevel(ctx, raw);
-
-  if (issues.length > 0) {
-    throw new ConfigError(filePath, issues);
-  }
-
-  return topLevel;
-}
-
-// ─── Internals ───────────────────────────────────────────────────────────────
-
-interface Json5Error extends Error {
-  lineNumber?: number;
-  columnNumber?: number;
-}
-
-function parseJson5OrThrow(filePath: string, source: string): unknown {
-  try {
-    return JSON5.parse(source);
-  } catch (err) {
-    const e = err as Json5Error;
-    throw new ConfigError(filePath, [
-      {
-        path: "",
-        message: `JSON5 syntax error: ${e.message}`,
-        line: e.lineNumber,
-        col: e.columnNumber,
-      },
-    ]);
-  }
-}
-
-// [LAW:types-are-the-program] Returns RawDslConfig — absence of a top-level
-// key survives the parse as `undefined`, distinct from explicit empty. The
-// merge step downstream decides what "absent" means policy-wise (currently:
-// inherit from default).
-function validateTopLevel(
-  ctx: ValidateCtx,
-  raw: Record<string, unknown>,
-): RawDslConfig {
-  for (const key of Object.keys(raw)) {
-    if (!TOP_LEVEL_KEYS.has(key)) {
-      ctx.issues.push({
-        path: key,
-        message: `Unknown top-level key "${key}". Expected one of: ${[...TOP_LEVEL_KEYS].join(", ")}`,
-        line: findKeyLine(ctx.source, [key]),
-      });
-    }
-  }
-
-  const out: Mutable<RawDslConfig> = {};
-  if (raw.globals !== undefined)
-    out.globals = validateGlobals(ctx, "globals", raw.globals);
-  if (raw.variables !== undefined)
-    out.variables = validateVariables(ctx, "variables", raw.variables);
-  if (raw.segments !== undefined)
-    out.segments = validateSegments(ctx, raw.segments);
-  // [LAW:no-silent-failure] `layout:` was removed in 2de.19. Reject loudly with
-  // a migration hint so the author knows exactly how to rewrite their config.
-  if (raw.layout !== undefined) {
-    ctx.issues.push({
-      path: "layout",
-      message:
-        `"layout" is no longer supported — use "root" with the A-grammar instead.\n` +
-        `  Replace:  layout: [["seg1", "seg2"], ["seg3"]]\n` +
-        `  With:     root: { v: [{ h: ["seg1", "seg2"] }, "seg3"] }\n` +
-        `  Single-row example:  root: { h: ["seg1", "seg2"] }`,
-      line: findKeyLine(ctx.source, ["layout"]),
-    });
-  }
-  if (raw.root !== undefined) out.root = validateRoot(ctx, "root", raw.root);
-  if (raw.actions !== undefined)
-    out.actions = validateActions(ctx, raw.actions);
-  if (raw.looks !== undefined) out.looks = validateLooks(ctx, raw.looks);
-  // [LAW:one-source-of-truth] Parsed BEFORE the synthesis passes below, because
-  // a preset's `root` runs through the same validateRoot and therefore collects
-  // its group sugar into the same `ctx.groups` the top-level root does — the
-  // synthesized artifacts must see every group the config declares, wherever it
-  // was staged from.
-  if (raw.presets !== undefined)
-    out.presets = validatePresets(ctx, raw.presets);
-  // [LAW:one-type-per-behavior] Edit mode's staged display globals — the same
-  // fragment shape a preset carries, one rung later in the precedence chain, so
-  // it runs through the same field table (validateEditGlobals) rather than a
-  // parallel schema listing which globals edit mode may set.
-  if (raw.editGlobals !== undefined)
-    out.editGlobals = validateEditGlobals(ctx, "editGlobals", raw.editGlobals);
-  if (raw.helpers !== undefined)
-    out.helpers = validateHelpers(ctx, raw.helpers);
-  // [LAW:one-source-of-truth] Group sugar synthesis runs AFTER every section
-  // parsed: each group collected during the root walk emits its state var +
-  // cycle action + toggle segment into the raw sections (so they merge over the
-  // default and cross-ref like any user declaration), and user names under the
-  // reserved namespace are rejected against the fully-parsed sections.
-  synthesizeGroupDecls(ctx, out);
-  // [LAW:one-source-of-truth] Menu synthesis runs AFTER group synthesis (a group
-  // body may host menu-bearing segments) and after every section parsed: each
-  // menu placement detected in the root walk emits its state var + cycle action
-  // into the raw sections, so they merge over the default, derive the click gate
-  // through deriveActionValidators, and collide loudly with any user name under
-  // the reserved namespace.
-  synthesizeMenuDecls(ctx, out);
-  // [LAW:one-source-of-truth] Edit-mode's TOGGLE half (brandon-layout-edit-
-  // 2gc.3) — unconditional, like the reservation above, so `edit.mode`/
-  // `edit.toggle` exist in EVERY parsed file and a hand-authored trigger
-  // segment cross-ref-checks normally. The CHROME half (the per-position +/-
-  // affordances) runs later, in validateConfig, once the merged/preset-
-  // resolved/rootOps-replayed tree exists to derive it from.
-  synthesizeEditModeToggle(ctx, out);
-  // [LAW:one-source-of-truth] The global settings menu reserves its namespace
-  // here and synthesizes NOTHING here: the tree it must be present in only
-  // exists after merge (a user `root` replaces the default's), so the artifacts
-  // are minted in validateConfig. The reservation is unconditional all the same,
-  // mirroring every other namespace above — "you never author settings.*" is a
-  // stable contract, not a rule that switches on when the pass happens to fire.
-  reservedNamespaceCollisions(
-    ctx,
-    out,
-    SETTINGS_NS,
-    "the global settings menu",
-  );
-  return out;
-}
-
-// [LAW:no-silent-failure] `layout` is intentionally absent — a config that
-// writes it gets an explicit migration error, not an "unknown key" message.
-const TOP_LEVEL_KEYS = new Set([
-  "globals",
-  "variables",
-  "segments",
-  "layout",
-  "root",
-  "actions",
-  "looks",
-  "presets",
-  "editGlobals",
-  "helpers",
-]);