@promptctl/cc-candybar 1.42.1 → 1.43.0

package/src/config/loader/persist-target.ts

@@ -1,67 +0,0 @@
-// [LAW:one-source-of-truth] THE parser for what a `persist`/`reset` action's
-// key STRING may legally name — the single place a key is classified as a
-// Globals field (candybar-config-engine-71o.3's scope) or a per-segment
-// palette override (candybar-config-engine-71o.6's scope), so cross-ref
-// validation (load time), the config-overrides store (write/read), and the
-// daemon's write-gate all classify a key through ONE authority instead of
-// three independently-drifting `isGlobalsField` checks.
-//
-// [LAW:types-are-the-program] A discriminated union, not a bag of optional
-// fields: every legal key shape is representable, every illegal one
-// collapses to `null` at exactly this one boundary — no downstream consumer
-// re-parses the string itself.
-
-import type { Globals } from "../dsl-types.js";
-import { isGlobalsField } from "./globals.js";
-
-export type PersistTarget =
-  | { readonly scope: "globals"; readonly field: keyof Globals }
-  | { readonly scope: "segment-palette"; readonly segment: string }
-  // [LAW:one-source-of-truth] brandon-layout-edit-2gc.1's structural-edit
-  // target — the accumulated op LOG for one preset's root (see
-  // src/config/layout-ops.ts), never the tree itself: a scalar-shaped value
-  // (a JSON-encoded string[] of op tokens) so it rides the SAME flat-dict
-  // overrides file with no shape change to that store's core writer.
-  | { readonly scope: "preset-root-ops"; readonly preset: string };
-
-// [LAW:locality-or-seam] `segments.<name>.palette` reuses the SAME dotted
-// namespacing SegmentDecl.vars already uses for segment-local variables
-// (`<segment>.<var>`, declared in src/dsl/render.ts) — one idiom for "a name
-// scoped under a segment", not a bespoke second syntax invented for persist
-// targets alone. `presets.<name>.rootOps` mirrors it one level up (a name
-// scoped under a preset) — deliberately spelled `rootOps`, not `root`, so it
-// never reads as the same string as presetRoot()'s load-time diagnostic path
-// `presets.<name>.root` (src/config/presets.ts), a different namespace this
-// key must never be confused with.
-const SEGMENT_PALETTE_KEY = /^segments\.([^.]+)\.palette$/;
-// [LAW:one-source-of-truth] GREEDY capture, not `[^.]+` — a preset name is
-// validated only non-empty/slash/newline-free (loader/presets.ts), so a dot
-// is a legal preset name (e.g. "v1.compact"). presetRootOpsKey always
-// appends the literal ".rootOps" suffix, so a greedy `(.+)` backtracks to
-// the RIGHTMOST occurrence of that anchored suffix and correctly recovers
-// the full name for ANY preset name, dotted or not — round-tripping
-// presetRootOpsKey exactly, rather than restricting preset names further
-// to dodge the ambiguity a non-greedy/exclusive-dot capture would have.
-const PRESET_ROOT_OPS_KEY = /^presets\.(.+)\.rootOps$/;
-
-// [LAW:one-source-of-truth] THE builder for a preset's rootOps key — the
-// inverse of PRESET_ROOT_OPS_KEY's parse. Two independent sites used to
-// spell `presets.${name}.rootOps` themselves (edit-chrome.ts's synthesis,
-// config-validators.ts's always-registered contribution), with only the
-// regex above as a read-side authority and no shared write-side one — they
-// happened to agree, but nothing enforced it. One function now; both call
-// sites import it.
-export function presetRootOpsKey(name: string): string {
-  return `presets.${name}.rootOps`;
-}
-
-export function parsePersistTarget(key: string): PersistTarget | null {
-  if (isGlobalsField(key)) return { scope: "globals", field: key };
-  const segmentMatch = SEGMENT_PALETTE_KEY.exec(key);
-  if (segmentMatch)
-    return { scope: "segment-palette", segment: segmentMatch[1]! };
-  const presetMatch = PRESET_ROOT_OPS_KEY.exec(key);
-  return presetMatch
-    ? { scope: "preset-root-ops", preset: presetMatch[1]! }
-    : null;
-}

package/src/config/loader/presets.ts

@@ -1,119 +0,0 @@
-// [LAW:types-are-the-program] The `presets` schema: each preset is a named
-// config FRAGMENT — an alternative arrangement of the bar the user switches to
-// — capped at exactly the two sections a render RESOLVES (`root`, `globals`)
-// and closed to the sections the daemon REGISTERS once per process
-// (`variables`, `segments`, `actions`, `helpers`). The reasoning for that cap
-// lives on PresetDecl in dsl-types.ts; enforcing it is this file's job, and the
-// record engine enforces it for free — `rejectUnknownKeys` reports any other
-// section as a "preset key" error naming the two that are legal.
-//
-// This file is the structural pass only. Whether a preset's root names a
-// segment that exists, and whether globals.preset names a declared preset, are
-// CROSS-REFERENCE concerns (loader/cross-ref.ts), because both run on the
-// MERGED config — a preset may stage segments the bundled default provides.
-
-import {
-  describeType,
-  isPlainObject,
-  record,
-  recordJson,
-  type FieldSpec,
-  type JsonNode,
-  type RecordSchema,
-  type ValidateCtx,
-} from "./validate-core.js";
-import { findKeyLine } from "./diagnostics.js";
-import { presetGlobalsJson, validatePresetGlobals } from "./globals.js";
-import { LAYOUT_NODE_REF, validateRoot } from "./layout.js";
-import type { PresetDecl } from "../dsl-types.js";
-
-// [LAW:one-source-of-truth] A preset's `root` runs through THE layout validator
-// — the same `validateRoot` the top-level `root:` uses, not a reduced copy — so
-// the A-grammar, the group sugar, and every migration error read identically
-// wherever a layout is authored. Group sugar declared inside a preset therefore
-// also lands in `ctx.groups` and synthesizes its state var / cycle action /
-// toggle segment into the shared sections, exactly as a top-level group does:
-// the synthesized artifacts are process-lifetime (see PresetDecl's cap), the
-// preset only chooses whether to stage them.
-const presetRootSpec: FieldSpec<NonNullable<PresetDecl["root"]>> = {
-  required: false,
-  json: { $ref: LAYOUT_NODE_REF },
-  parse: (ctx, path, field, raw) =>
-    raw[field] === undefined
-      ? undefined
-      : validateRoot(ctx, `${path}.${field}`, raw[field]),
-};
-
-// [LAW:one-source-of-truth] A preset's `globals` runs through the globals field
-// table, minus `preset` itself (a preset cannot select a preset — see
-// validatePresetGlobals). A field added to Globals is preset-settable the same
-// day, with no edit here.
-const presetGlobalsSpec: FieldSpec<NonNullable<PresetDecl["globals"]>> = {
-  required: false,
-  json: presetGlobalsJson(),
-  parse: (ctx, path, field, raw) =>
-    raw[field] === undefined
-      ? undefined
-      : validatePresetGlobals(ctx, `${path}.${field}`, raw[field]),
-};
-
-const PRESET_SCHEMA: RecordSchema<PresetDecl> = {
-  noun: "preset key",
-  fields: { root: presetRootSpec, globals: presetGlobalsSpec },
-};
-
-// An absent presets block is handled by the caller (absence survives the parse);
-// a non-object is a reported error recovering to empty — parseDslConfig throws
-// once any issue exists, so the recovery value never renders.
-export function validatePresets(
-  ctx: ValidateCtx,
-  raw: unknown,
-): Readonly<Record<string, PresetDecl>> {
-  if (!isPlainObject(raw)) {
-    ctx.issues.push({
-      path: "presets",
-      message: `presets must be an object mapping preset names to config fragments, got ${describeType(raw)}`,
-      line: findKeyLine(ctx.source, ["presets"]),
-    });
-    return {};
-  }
-  const out: Record<string, PresetDecl> = {};
-  for (const [name, value] of Object.entries(raw)) {
-    // [LAW:no-silent-failure] A preset name is a deliverable set-state value —
-    // a preset picker writes it on the wire, which rejects empty values and
-    // splits on "/". Rejecting the shape HERE surfaces the error on every
-    // config load, not only once an action ranges the "presets" domain (the
-    // identical guard looks.ts applies to look names, for the identical
-    // reason).
-    //
-    // [LAW:one-source-of-truth] Newlines are ALSO rejected — the same reason
-    // loader/layout.ts's groupLabelSpec rejects \n/\r in a group's `label`
-    // before it ever reaches escapeTemplateLiteral: a preset name is spliced
-    // as DISPLAY TEXT into a synthesized Go-template string literal
-    // (edit-chrome.ts's "customized" banner), and that escaper only handles
-    // backslash/quote — an embedded newline produces an unterminated string
-    // literal go-template-js forbids, breaking synthesis for the WHOLE
-    // config, not just this one preset. Unlike a label, a preset name is
-    // also an identifier used across other seams (the `presets` domain, the
-    // `presets.<name>.rootOps` wire key), so this belongs in its general
-    // validity check, not a narrower escape-harder fix at the one splice site.
-    if (name === "" || name.includes("/") || /[\n\r]/.test(name)) {
-      ctx.issues.push({
-        path: `presets.${name}`,
-        message: `preset name ${JSON.stringify(name)} must be non-empty, slash-free, and newline-free — a preset picker writes the name on the set-state wire (which rejects empty values and splits on "/"), and edit mode splices it into a synthesized template string`,
-        line: findKeyLine(ctx.source, ["presets", name]),
-      });
-      continue;
-    }
-    const parsed = record(ctx, PRESET_SCHEMA, `presets.${name}`, value);
-    if (parsed !== null) out[name] = parsed;
-  }
-  return out;
-}
-
-// [LAW:one-source-of-truth] The schema emitter derives from the SAME declaration
-// the validator interprets — a map of preset names to the closed two-section
-// fragment object.
-export function presetsJson(): JsonNode {
-  return { type: "object", additionalProperties: recordJson(PRESET_SCHEMA) };
-}

package/src/config/loader/refs.ts

@@ -1,100 +0,0 @@
-// [LAW:dataflow-not-control-flow] Best-effort extraction of the references a
-// template string makes — dotted variable refs, `action "name"` refs, and
-// `picker "apply" "page"` refs. Pure text walks over `{{ … }}` blocks: no
-// full template parse (that is the engine's compile-time job). This file changes
-// when the surface grammar of those refs changes; the cross-ref/cycle passes
-// consume the sets it returns without re-deriving them.
-
-const TEMPLATE_BLOCK_RE = /{{([\s\S]*?)}}/g;
-const STRING_LITERAL_RE = /"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`[^`]*`/g;
-const DOTTED_REF_RE =
-  /(?<![A-Za-z0-9_)])\.([A-Za-z_][\w]*(?:\.[A-Za-z_][\w]*)*)/g;
-
-// [LAW:dataflow-not-control-flow] Extract every `.<id>(.<id>)*` token inside
-// `{{ ... }}` blocks after stripping string literals. The result is a set of
-// dotted reference candidates; the caller decides which are valid.
-export function extractTemplateRefs(template: string): Set<string> {
-  const refs = new Set<string>();
-  let m: RegExpExecArray | null;
-  TEMPLATE_BLOCK_RE.lastIndex = 0;
-  while ((m = TEMPLATE_BLOCK_RE.exec(template)) !== null) {
-    const block = m[1]!.replace(STRING_LITERAL_RE, "");
-    let r: RegExpExecArray | null;
-    DOTTED_REF_RE.lastIndex = 0;
-    while ((r = DOTTED_REF_RE.exec(block)) !== null) {
-      refs.add(r[1]!);
-    }
-  }
-  return refs;
-}
-
-// [LAW:dataflow-not-control-flow] Extract every `action "name"` call from a
-// template, for the load-time existence check. Same best-effort code-span /
-// string-literal walk as extractTemplateRefs: the `action` keyword lives in a
-// CODE span and its NAME is the very next string literal (the display/boundValue
-// literals that follow are preceded by a non-`action` span, so they are never
-// misread as the name).
-const ACTION_ARG_RE = /\baction\s+$/;
-export function extractActionRefs(template: string): Set<string> {
-  const refs = new Set<string>();
-  TEMPLATE_BLOCK_RE.lastIndex = 0;
-  let m: RegExpExecArray | null;
-  while ((m = TEMPLATE_BLOCK_RE.exec(template)) !== null) {
-    const block = m[1]!;
-    let cursor = 0;
-    let s: RegExpExecArray | null;
-    STRING_LITERAL_RE.lastIndex = 0;
-    while ((s = STRING_LITERAL_RE.exec(block)) !== null) {
-      if (ACTION_ARG_RE.test(block.slice(cursor, s.index))) {
-        refs.add(s[0].slice(1, -1));
-      }
-      cursor = s.index + s[0].length;
-    }
-  }
-  return refs;
-}
-
-// [LAW:dataflow-not-control-flow] Extract the action names a `picker` OR `menu`
-// call references, for the load-time existence check. A `picker` binds an
-// (apply, page) action pair as its first two string-literal args
-// (`{{ picker "applyTheme" "themePage" true true }}`); a `menu` binds ONLY its
-// apply action (`{{ menu "applyTheme" (dict …) }}`) — its page cursor is
-// synthesized from identity, and the dict's option-name literals must never be
-// misread as action refs. A menu's body IS a picker, so the existence check is
-// identical; one extractor arms on either keyword with the keyword's own arg
-// count [LAW:single-enforcer]. Same code/string-span walk as extractActionRefs.
-const PICKER_OR_MENU_ARG_RE = /\b(picker|menu)\s+$/;
-export function extractPickerMenuRefs(template: string): Set<string> {
-  const refs = new Set<string>();
-  TEMPLATE_BLOCK_RE.lastIndex = 0;
-  let m: RegExpExecArray | null;
-  while ((m = TEMPLATE_BLOCK_RE.exec(template)) !== null) {
-    const block = m[1]!;
-    let cursor = 0;
-    let pending = 0; // remaining name args to capture for the current call
-    let s: RegExpExecArray | null;
-    STRING_LITERAL_RE.lastIndex = 0;
-    while ((s = STRING_LITERAL_RE.exec(block)) !== null) {
-      const kw = PICKER_OR_MENU_ARG_RE.exec(block.slice(cursor, s.index));
-      if (kw !== null) pending = kw[1] === "picker" ? 2 : 1;
-      if (pending > 0) {
-        refs.add(s[0].slice(1, -1));
-        pending--;
-      }
-      cursor = s.index + s[0].length;
-    }
-  }
-  return refs;
-}
-
-// A ref resolves if (a) the full dotted name is a declared variable, OR
-// (b) it's a strict prefix of some declared variable (namespace navigation
-// like .session in `.session.id` when only `session.id` is declared).
-export function refResolves(ref: string, allVars: Set<string>): boolean {
-  if (allVars.has(ref)) return true;
-  const prefix = `${ref}.`;
-  for (const name of allVars) {
-    if (name.startsWith(prefix)) return true;
-  }
-  return false;
-}

package/src/config/loader/reserved-namespace.ts

@@ -1,38 +0,0 @@
-// [LAW:one-source-of-truth] The loader-side half of the disclosure primitive
-// (src/config/disclosure.ts): the ONE reserved-namespace collision check both
-// synthesis passes run. Group sugar reserves `groups.` and the `{{ menu }}`
-// helper reserves `menus.`; each synthesizes its `state` var, `cycle` action, and
-// (for a group) a toggle segment under its prefix, so a user-authored name under
-// that prefix must be a loud load error — never a silent overwrite of a
-// synthesized artifact. The check was duplicated verbatim in both passes; it lives
-// here now, parameterized by the prefix and a human description of what
-// synthesizes it, so the two body-kinds share one enforcer [LAW:single-enforcer].
-
-import type { Mutable, ValidateCtx } from "./validate-core.js";
-import type { RawDslConfig } from "../dsl-types.js";
-import { findKeyLine } from "./diagnostics.js";
-
-// [LAW:no-silent-failure] Reject every user name under the reserved prefix across
-// all three declaration sections (a synthesized disclosure lands in each), before
-// synthesis writes into them — so a `groups.*`/`menus.*` squatter surfaces as a
-// rename-pointing error rather than being silently shadowed. `synthesizedBy`
-// names the feature in the message (e.g. "group nodes", "{{ menu }} helpers") so
-// the author knows which sugar owns the prefix.
-export function reservedNamespaceCollisions(
-  ctx: ValidateCtx,
-  out: Mutable<RawDslConfig>,
-  ns: string,
-  synthesizedBy: string,
-): void {
-  for (const section of ["variables", "actions", "segments"] as const) {
-    for (const name of Object.keys(out[section] ?? {})) {
-      if (name.startsWith(ns)) {
-        ctx.issues.push({
-          path: `${section}.${name}`,
-          message: `"${name}" is in the reserved "${ns}" namespace (synthesized by ${synthesizedBy}) — rename it`,
-          line: findKeyLine(ctx.source, ["root"]),
-        });
-      }
-    }
-  }
-}

package/src/config/loader/segments.ts

@@ -1,120 +0,0 @@
-// [LAW:types-are-the-program] The segment schema: a required `template` plus
-// optional layout/paint/visibility fields and a nested `vars` block (validated by
-// the variable schema). Declared as DATA (SEGMENT_SCHEMA) and interpreted by the
-// generic `record` engine — a plain record with no cross-field invariant, so two
-// value-shaped fields (`width`, `vars`) carry their bespoke parse as field specs.
-// This file changes when a segment field is added or removed.
-
-import {
-  JUSTIFY_MODES,
-  TRUNCATE_MODES,
-  type SegmentDecl,
-  type VariableDecl,
-} from "../dsl-types.js";
-import { findKeyLine } from "./diagnostics.js";
-import {
-  describeType,
-  describeValue,
-  isPlainObject,
-  optionalEnumSpec,
-  optionalStringSpec,
-  paletteSpec,
-  record,
-  recordJson,
-  requireStringSpec,
-  type FieldSpec,
-  type FieldSpecMap,
-  type JsonNode,
-  type RecordSchema,
-  type ValidateCtx,
-} from "./validate-core.js";
-import { validateVariables, variablesMapJson } from "./variables.js";
-
-export function validateSegments(
-  ctx: ValidateCtx,
-  raw: unknown,
-): Record<string, SegmentDecl> {
-  if (raw === undefined) return {};
-  if (!isPlainObject(raw)) {
-    ctx.issues.push({
-      path: "segments",
-      message: `segments must be an object, got ${describeType(raw)}`,
-      line: findKeyLine(ctx.source, ["segments"]),
-    });
-    return {};
-  }
-
-  const out: Record<string, SegmentDecl> = {};
-  for (const [name, decl] of Object.entries(raw)) {
-    const parsed = record(ctx, SEGMENT_SCHEMA, `segments.${name}`, decl);
-    if (parsed !== null) out[name] = parsed;
-  }
-  return out;
-}
-
-// [LAW:types-are-the-program] `width` is `"auto"` or a positive integer — a union
-// the generic string/enum specs cannot express, so it carries its own parse and
-// bespoke message as DATA. Absent → omitted; present-and-wrong → issue + omitted.
-function widthSpec(): FieldSpec<"auto" | number> {
-  return {
-    required: false,
-    json: { anyOf: [{ const: "auto" }, { type: "integer", minimum: 1 }] },
-    parse: (ctx, path, field, raw) => {
-      const v = raw[field];
-      if (v === undefined) return undefined;
-      if (v === "auto") return "auto";
-      if (typeof v === "number" && Number.isInteger(v) && v > 0) return v;
-      ctx.issues.push({
-        path: `${path}.${field}`,
-        message: `width must be "auto" or a positive integer, got ${describeValue(v)}`,
-        line: findKeyLine(ctx.source, [...path.split("."), field]),
-      });
-      return undefined;
-    },
-  };
-}
-
-// [LAW:decomposition] The nested `vars` block defers to the variable schema —
-// recursion by reuse of the already-migrated per-name taggedUnion, not a new
-// combinator. Absent → omitted; present → the parsed map (possibly empty, with
-// its own issues already reported), mirroring the old `if (raw.vars !== undefined)`.
-function varsSpec(): FieldSpec<Readonly<Record<string, VariableDecl>>> {
-  return {
-    required: false,
-    // [LAW:one-source-of-truth] The nested `vars` schema is the SAME name →
-    // VariableDecl map the top-level `variables` block emits — one source.
-    json: variablesMapJson(),
-    parse: (ctx, path, field, raw) => {
-      const v = raw[field];
-      if (v === undefined) return undefined;
-      return validateVariables(ctx, `${path}.${field}`, v);
-    },
-  };
-}
-
-// [LAW:dataflow-not-control-flow] The segment's shape as DATA over its fields, in
-// declaration order. The engine runs every spec, rejects unknown keys, and fails
-// the segment when `template` is absent or invalid — the isPlainObject guard,
-// unknown-key loop, result-threading, and optional-omission the old body hand-rolled.
-const SEGMENT_FIELDS: FieldSpecMap<SegmentDecl> = {
-  template: requireStringSpec(),
-  width: widthSpec(),
-  justify: optionalEnumSpec(JUSTIFY_MODES),
-  truncate: optionalEnumSpec(TRUNCATE_MODES),
-  bg: optionalStringSpec(),
-  fg: optionalStringSpec(),
-  when: optionalStringSpec(),
-  palette: paletteSpec(),
-  vars: varsSpec(),
-};
-
-const SEGMENT_SCHEMA: RecordSchema<SegmentDecl> = {
-  noun: "segment key",
-  fields: SEGMENT_FIELDS,
-};
-
-// [LAW:one-source-of-truth] The `segments` block is a name → SegmentDecl map,
-// derived from the SAME SEGMENT_SCHEMA the validator interprets.
-export function segmentsJson(): JsonNode {
-  return { type: "object", additionalProperties: recordJson(SEGMENT_SCHEMA) };
-}