@promptctl/cc-candybar 1.25.0 → 1.27.0

package/src/config/option-domain.ts

@@ -0,0 +1,164 @@
+// [LAW:one-type-per-behavior] An option domain is a NAME → members lookup,
+// regardless of where the members come from. Before this module, "themes" /
+// "styles" / "looks" were three special-cased branches wearing a closed
+// TypeScript union (OptionSource) — a hardcoded list of legal domain NAMES
+// with extra steps. There is exactly one domain concept: a `from` value is
+// either an INLINE literal domain (an authored array — zero registration,
+// zero engine edit) or the NAME of a domain resolved through this registry.
+// Adding a new registry-backed domain is one `registerOptionDomain` call
+// (data), never a new union member every consumer must re-match on.
+//
+// [LAW:no-shared-mutable-globals] `_GLOBAL_OPTION_DOMAINS` is shared mutable
+// state with exactly one owner (this module) and one explicit API
+// (registerOptionDomain / resolveOptionDomain / knownOptionDomainNames). It
+// holds only domains whose members are legitimately PROCESS-lifetime static
+// (themes, styles — module-init snapshots, same reasoning as
+// template-engine/funcs.ts's THEMES_LIST/STYLES_LIST caches). A domain whose
+// members vary PER CONFIG (the merged `looks:` block — two daemon render-cache
+// entries can hold different looks blocks for different configs
+// simultaneously) can never live here; it is threaded explicitly as
+// `perConfigDomains`, the same way `lookNames` already is.
+//
+// [LAW:one-source-of-truth] This is the ONE place a domain name resolves to
+// its members. render/action.ts (rendering options) and
+// daemon/verbs/state-validators.ts (deriving the click gate) both call
+// through here instead of each hand-rolling the themes/styles/looks branch —
+// the rendered options and the derived gate cannot diverge because there is
+// no second resolver.
+
+import {
+  CHARSETS,
+  COLOR_COMPATIBILITIES,
+  listResolvablePaletteNames,
+  STRIP_STYLES,
+} from "../themes/policy.js";
+import { presetNames } from "./presets.js";
+
+// [LAW:types-are-the-program] The authoring shape of a `set … from` value: a
+// bare string names a domain (resolved through the registry or a per-config
+// override); a non-empty array of strings IS the domain, inline, needing no
+// name and no registration. Mirrors the `cycle` field's array shape — an
+// author already knows this pattern.
+export type OptionDomain = string | readonly string[];
+
+export type OptionDomainResolver = () => readonly string[];
+
+interface DomainEntry {
+  readonly permanent: boolean;
+  readonly resolve: OptionDomainResolver;
+}
+
+const _GLOBAL_OPTION_DOMAINS = new Map<string, DomainEntry>();
+
+function registerBuiltinDomain(
+  name: string,
+  resolve: OptionDomainResolver,
+): void {
+  _GLOBAL_OPTION_DOMAINS.set(name, { permanent: true, resolve });
+}
+
+// [LAW:one-source-of-truth] "themes"/"styles" become ORDINARY registrations —
+// the same registerOptionDomain any future caller uses — reading the same
+// canonical lists the set-state validator and the `themes()`/`styles()`
+// template bindings already consult (listResolvablePaletteNames/
+// STRIP_STYLES). No special-cased branch remains anywhere downstream.
+registerBuiltinDomain("themes", () => listResolvablePaletteNames());
+registerBuiltinDomain("styles", () => STRIP_STYLES);
+// [LAW:one-source-of-truth] Same shape as themes/styles: the exact consts
+// the loader's own field validation and the render layer's glyph/color-depth
+// dispatch already derive from (themes/policy.ts CHARSETS/COLOR_COMPATIBILITIES)
+// — a menu drawing from these can never enumerate a value the render layer
+// would reject.
+registerBuiltinDomain("charsets", () => CHARSETS);
+registerBuiltinDomain("colorCompatibilities", () => COLOR_COMPATIBILITIES);
+
+// [LAW:no-silent-fallbacks] A built-in domain can never be re-claimed — a
+// config or feature registering a custom domain named "themes" gets a loud
+// load-time error, never a silent shadow of the real theme list. Registering
+// returns a disposer (same shape as registerStateValidator) so a caller with
+// a bounded lifetime (a test, a future per-feature domain) can clean up.
+export function registerOptionDomain(
+  name: string,
+  resolve: OptionDomainResolver,
+): () => void {
+  const existing = _GLOBAL_OPTION_DOMAINS.get(name);
+  if (existing) {
+    throw new Error(
+      `registerOptionDomain: option domain "${name}" is already registered` +
+        (existing.permanent
+          ? " (a built-in domain — built-ins cannot be reclaimed)"
+          : ""),
+    );
+  }
+  _GLOBAL_OPTION_DOMAINS.set(name, { permanent: false, resolve });
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    const entry = _GLOBAL_OPTION_DOMAINS.get(name);
+    if (entry && !entry.permanent) _GLOBAL_OPTION_DOMAINS.delete(name);
+  };
+}
+
+// [LAW:one-source-of-truth] THE single construction of a config's per-config
+// domain overrides — the domains whose members are declared IN the config
+// rather than in the registry above: "looks" (the merged `looks:` block) and
+// "presets" (the merged `presets:` block). cross-ref.ts (checking a `from` name
+// resolves), state-validators.ts (deriving the click gate), and dsl/render.ts
+// (compiling render-time options) each need this map; before this function they
+// each rebuilt it independently, three sites that could silently drift if a
+// future per-config domain were added to only some of them.
+//
+// [LAW:locality-or-seam] The parameter is the CONFIG, structurally typed to the
+// blocks read here — not one positional record per domain. Presets were the
+// second per-config domain, and adding them under the old `(looks)` signature
+// would have rippled a new argument through all three call sites; under this
+// one, a third domain is a single line HERE and nothing else moves. Structural
+// (rather than importing DslConfig) so this leaf module still never imports
+// dsl-types.ts — that would cycle through dsl-types.ts -> action.ts ->
+// option-domain.ts (type-only, but still a cycle this module stays clear of,
+// per [LAW:one-way-deps]).
+export function perConfigDomainsFor(config: {
+  readonly looks: Readonly<Record<string, unknown>>;
+  readonly presets: Readonly<Record<string, unknown>>;
+}): ReadonlyMap<string, readonly string[]> {
+  return new Map([
+    ["looks", Object.keys(config.looks)],
+    // [LAW:one-source-of-truth] Not `Object.keys` — the floor is selectable
+    // whether or not a config declares it, and presetNames is where that is
+    // stated (once, for the gate and the render alike).
+    ["presets", presetNames(config.presets)],
+  ]);
+}
+
+// [LAW:one-source-of-truth] The full set of names `from` may legally name for
+// THIS config: every globally-registered domain plus this config's per-config
+// overrides (currently just "looks"). Used both to resolve a name and to spell
+// out the legal set in an unknown-domain error.
+export function knownOptionDomainNames(
+  perConfigDomains: ReadonlyMap<string, readonly string[]>,
+): readonly string[] {
+  return [
+    ...new Set([..._GLOBAL_OPTION_DOMAINS.keys(), ...perConfigDomains.keys()]),
+  ];
+}
+
+// [LAW:dataflow-not-control-flow] One total resolution: an inline array IS
+// its own domain (no lookup); a string is a NAME resolved first against this
+// config's per-config overrides, then the global registry. A name matching
+// neither is a genuine error — the loader's cross-ref pass already proved
+// every `from` name resolves before this runs, so a miss here is a
+// caller/wiring bug, not a config-authoring mistake.
+export function resolveOptionDomain(
+  from: OptionDomain,
+  perConfigDomains: ReadonlyMap<string, readonly string[]>,
+): readonly string[] {
+  if (typeof from !== "string") return from;
+  const local = perConfigDomains.get(from);
+  if (local) return local;
+  const entry = _GLOBAL_OPTION_DOMAINS.get(from);
+  if (entry) return entry.resolve();
+  throw new Error(
+    `unknown option domain "${from}" (have: ${knownOptionDomainNames(perConfigDomains).join(", ")})`,
+  );
+}

package/src/config/presets.ts

@@ -0,0 +1,156 @@
+// [LAW:one-source-of-truth] The preset RESOLUTION seam: the three questions a
+// render asks about presets — which one is active, what layout does it stage,
+// what display globals does it carry — answered in one place, from one map.
+//
+// A preset is to configuration what a look is to a theme, and that is the
+// implementation instruction, not an analogy: the selection rides the SAME
+// per-config-member seam looks rides (effectiveMemberName in themes/policy.ts),
+// the domain is threaded as DATA through the same perConfigDomainsFor the click
+// gate and the rendered options both read, and an unknown name collapses to the
+// same kind of always-present floor. Nothing here is parallel machinery
+// [LAW:one-type-per-behavior].
+//
+// WHERE THE PRESET LAYER SITS — the five-layer precedence chain, documented in
+// full in docs/interaction-authoring.md ("persist / reset"), which is the ONE
+// place it is written down:
+//
+//   bundled default  <  user config file  <  persisted overrides
+//                    <  ACTIVE PRESET  <  session pick
+//
+// The preset's position is forced by its lifetime, not chosen. Everything to
+// its left is resolved once per RenderCache entry (an entry serves many
+// sessions: the user file and the overrides file are both read in buildState);
+// everything from the preset rightward is resolved per render, because the pick
+// is per session. The chain is therefore monotonic in "how late is this
+// decided", which is why a preset overrides a persisted default (switching to a
+// "compact" arrangement must actually change padding, even for a user who once
+// persisted a padding they liked) while a session's own click still wins over
+// the preset (a click is later still).
+
+// [LAW:one-way-deps] Type-only, so nothing is emitted and option-domain.ts (a
+// leaf that deliberately never imports dsl-types.ts) can import PRESET_NAMES
+// from here without a runtime cycle.
+import type {
+  DslConfig,
+  Globals,
+  LayoutNode,
+  PresetDecl,
+} from "./dsl-types.js";
+import { effectiveMemberName } from "../themes/policy.js";
+
+// [LAW:one-source-of-truth] The floor preset's name, spelled once. `looks` has
+// `"none"` (the identity adaptation); presets have `"default"` (the identity
+// fragment — the empty PresetDecl, i.e. the config's own root and globals
+// unchanged). The bundled default declares it and merge-by-name cannot remove
+// it, so every merged DslConfig carries it by construction.
+export const PRESET_FLOOR = "default";
+
+// [LAW:dataflow-not-control-flow] The floor's fragment is the EMPTY one — no
+// alternative root, no globals delta — which is exactly what "no preset chosen"
+// already means. It is a value the lookup below starts from rather than a case
+// the lookup handles, so the floor resolves whether or not any config declares
+// it. The bundled default declares `default: {}` for a different job: to put the
+// floor in the DOMAIN, so a `{{ menu }}` lists it and the derived click gate
+// admits a click that returns to it. Domain membership and resolvability are two
+// guarantees, and this one does not lean on the other.
+const FLOOR_FRAGMENT: PresetDecl = {};
+
+// [LAW:one-source-of-truth] THE preset domain: every arrangement selectable in
+// this config — the declared alternatives with the floor always among them. The
+// three readers that each need "the preset names" (perConfigDomainsFor, which
+// feeds the rendered options AND the derived click gate; registerDslConfig's
+// per-preset compile; the `presets` template binding) call this rather than
+// spelling `Object.keys(config.presets)` themselves, so the menu you can see,
+// the click the wire admits, and the layouts that were compiled are the same
+// set by construction — a click returning to the floor cannot be rejected by a
+// gate that forgot the floor was selectable.
+//
+// This is deliberately STRONGER than the looks seam it otherwise mirrors, where
+// "none" is in the domain only because the bundled stdlib ships it. The floor's
+// membership is a fact about the resolution, not about any config, so it is
+// stated here once rather than depending on a merge going right.
+export function presetNames(
+  presets: Readonly<Record<string, unknown>>,
+): readonly string[] {
+  return [...new Set([PRESET_FLOOR, ...Object.keys(presets)])];
+}
+
+// [LAW:one-type-per-behavior] The preset domain's instance of the shared
+// per-config-member resolver — the same call shape effectiveLookName makes, one
+// dimension over. A stale or deleted name collapses to PRESET_FLOOR rather than
+// throwing, and the caller publishes this RESOLVED name as `preset.effective`
+// so the bar's label and the bar's layout can never disagree
+// [LAW:no-silent-failure].
+export function effectivePresetName(
+  sessionPreset: string | null,
+  globalsPreset: string | undefined,
+  declaredPresets: Readonly<Record<string, PresetDecl>>,
+): string {
+  return effectiveMemberName(
+    sessionPreset,
+    globalsPreset,
+    PRESET_FLOOR,
+    declaredPresets,
+  );
+}
+
+// [LAW:single-enforcer] The one place an effective preset NAME becomes the
+// fragment a render reads — a declared preset, or the floor's identity fragment
+// layered under them so the floor never depends on being declared. By the time
+// a name reaches here it must be one of those: effectivePresetName collapses
+// unknown names to the floor.
+// [LAW:no-defensive-null-guards] the throw is the loud failure for that broken
+// invariant (a caller that skipped the resolution and passed a raw session
+// string), never a silent empty-fragment fallback that would render one
+// arrangement while the bar's label named another — the exact contract
+// lookKeyByName holds for looks.
+export function presetByName(
+  presets: Readonly<Record<string, PresetDecl>>,
+  name: string,
+): PresetDecl {
+  const preset = { [PRESET_FLOOR]: FLOOR_FRAGMENT, ...presets }[name];
+  if (preset === undefined) {
+    throw new Error(
+      `Preset "${name}" is not declared in this config — effectivePresetName ` +
+        `collapses unknown names to "${PRESET_FLOOR}", which always resolves; ` +
+        `a miss here means a raw name reached this function without going ` +
+        `through that resolution`,
+    );
+  }
+  return preset;
+}
+
+// A preset's layout AND the config path that layout was authored at, as a total
+// function of the name: a preset that declares no `root` stages the config's own
+// root, which lives at `root` and not under this preset's name.
+//
+// [LAW:one-source-of-truth] Both halves come from ONE decision on purpose. The
+// fallback used to be resolved here while the diagnostic path was spelled
+// separately at the compile site as `presets.<name>.root`, so the two disagreed
+// for exactly the configs that never opted into presets at all: a plain config
+// with no `presets:` block reported its own root's template errors under
+// `presets.default.root`, naming a node the author never wrote. Returning the
+// tree together with where it came from makes that drift unrepresentable rather
+// than merely fixed [FRAMING:representation].
+export function presetRoot(
+  config: DslConfig,
+  name: string,
+): { readonly node: LayoutNode; readonly path: string } {
+  // [LAW:dataflow-not-control-flow] A projection returning DATA, not a branch
+  // around an operation: both arms yield the same shape, and the discriminator
+  // (did this preset declare a root?) is a fact the fragment already carries.
+  const own = presetByName(config.presets, name).root;
+  return own === undefined
+    ? { node: config.root, path: "root" }
+    : { node: own, path: `presets.${name}.root` };
+}
+
+// [LAW:dataflow-not-control-flow] A preset's display globals, as a total
+// function of the name: the config's globals with the preset's shallow-merged
+// over them, per field — the SAME per-field cascade mergeWithDefault applies to
+// `globals` everywhere else in the loader, so a preset naming `padding` says
+// nothing about `charset`. The empty fragment yields the config's globals
+// unchanged, so again no floor-shaped branch.
+export function presetGlobals(config: DslConfig, name: string): Globals {
+  return { ...config.globals, ...presetByName(config.presets, name).globals };
+}

package/src/daemon/cache/git.ts

@@ -363,7 +363,7 @@ export class GitDataProvider extends GitService {
   ): Promise<Outcome<PullRequest>> {
     // [LAW:no-silent-failure] A `failed` remote read (git couldn't run) must
     // surface; only `absent` (no remote configured) means "no forge PR".
-    const remote = await this.inner.getRemoteOriginUrl(repoRoot);
+    const remote = await this.inner.getRepoRemoteUrl(repoRoot);
     if (remote.kind === "failed") return remote;
     if (remote.kind === "absent") return ABSENT;
     const remoteUrl = remote.value;

package/src/daemon/cache/render.ts

@@ -8,6 +8,8 @@ import {
   resolveDslConfigPath,
   dslConfigCandidatePaths,
   detectConfigCollisions,
+  mergeWithDefault,
+  applySegmentPaletteOverrides,
   ConfigError,
 } from "../../config/dsl-loader.js";
 import type { ValidatedConfig } from "../../config/dsl-types.js";
@@ -17,6 +19,12 @@ import {
   deriveActionValidators,
   registerStateValidator,
 } from "../verbs/state-validators.js";
+import {
+  deriveConfigActionValidators,
+  registerConfigValidator,
+} from "../verbs/config-validators.js";
+import { loadOverrides } from "../config-overrides-store.js";
+import { configOverridesPath } from "../paths.js";
 import { VariableStore } from "../../var-system/store.js";
 import { SourceRegistry } from "../../var-system/sources.js";
 import type { GitDataProvider } from "./git.js";
@@ -277,7 +285,39 @@ export class RenderCache {
       resolvedPath,
       DEFAULT_DSL_CONFIG,
     );
-    const config = validateConfig(merged, resolvedPath ?? "<default>", source);
+    // [LAW:one-source-of-truth] The persistent config-overrides layer
+    // (candybar-config-engine-71o.2) is a SECOND application of the SAME
+    // mergeWithDefault cascade the user file already went through — no new
+    // merge semantics, just one more layer at bundled-default < user-file <
+    // overrides precedence (a `persist` write changes the DEFAULT; a session
+    // pick still overrides it per-session via effective* resolution,
+    // unchanged). Always applied, even when the overrides file is empty —
+    // an empty overrides object merges as a no-op, so there is no
+    // "has overrides?" branch [LAW:dataflow-not-control-flow]. One
+    // loadOverrides read serves BOTH halves below (globals + segment-palette)
+    // — the overrides file backs two different merge shapes, not two reads.
+    const overrides = loadOverrides(configOverridesPath(), dlog);
+    const withGlobalsOverrides = mergeWithDefault(
+      { globals: overrides.globals },
+      merged,
+    );
+    // [LAW:one-source-of-truth] The segment-scoped half of the SAME overrides
+    // file (candybar-config-engine-71o.6) — a later, narrower merge step, not
+    // a second override layer: mergeWithDefault's `segments` cascade replaces
+    // a named segment WHOLESALE, so a one-field palette override rides its
+    // own overlay (applySegmentPaletteOverrides) against the already-merged
+    // config instead, patching `palette` without dropping the segment's other
+    // fields. Order versus the globals merge above doesn't matter — the two
+    // touch disjoint parts of the config (`globals` vs `segments[name]`).
+    const withOverrides = applySegmentPaletteOverrides(
+      withGlobalsOverrides,
+      overrides.segmentPalette,
+    );
+    const config = validateConfig(
+      withOverrides,
+      resolvedPath ?? "<default>",
+      source,
+    );
 
     const store = new VariableStore();
     // [LAW:single-enforcer] Inject the daemon's shared GitDataProvider so
@@ -321,6 +361,14 @@ export class RenderCache {
       for (const { key, spec } of deriveActionValidators(config)) {
         validatorDisposers.push(registerStateValidator(key, spec));
       }
+      // [LAW:one-source-of-truth] The `persist` action table's twin
+      // derivation, registered through the SAME dispose-before-swap
+      // transaction — a config's persistent-config-writable-key surface
+      // lives and dies with this cache entry exactly like its SessionState
+      // surface does.
+      for (const { key, spec } of deriveConfigActionValidators(config)) {
+        validatorDisposers.push(registerConfigValidator(key, spec));
+      }
     } catch (err) {
       for (const dispose of validatorDisposers) dispose();
       registry.dispose();
@@ -331,7 +379,7 @@ export class RenderCache {
     // serves many sessions, but the effective theme is per-session SessionState;
     // freezing the palette per entry would let the rendered colors diverge from
     // the session's chosen theme. The server resolves basePalette per render
-    // from the effective theme (resolverForThemeName ∘ effectiveThemeName).
+    // from the effective theme (paletteForThemeName ∘ effectiveThemeName).
     return {
       config,
       store,
@@ -380,11 +428,17 @@ export class RenderCache {
     // covers the exact same set of paths the next reload would consult — a
     // `--config` override collapses to one candidate; absent, the precedence
     // chain unfolds in full.
-    const candidates = dslConfigCandidatePaths(
-      entry.projectDir,
-      entry.cwd,
-      entry.configFile,
-    );
+    //
+    // [LAW:dataflow-not-control-flow] configOverridesPath() rides the SAME
+    // candidate list, not a second watch branch: "reload rides the existing
+    // watcher" (candybar-config-engine-71o.2) means a persistent config write
+    // is just one more file in the resolution chain the loop below already
+    // handles uniformly (existence-gated, watched via its parent dir so the
+    // file's first-ever creation also triggers reload).
+    const candidates = [
+      ...dslConfigCandidatePaths(entry.projectDir, entry.cwd, entry.configFile),
+      configOverridesPath(),
+    ];
     const dirSet = new Map<string, Set<string>>();
     for (const candidate of candidates) {
       const dir = path.dirname(candidate);