@promptctl/cc-candybar 1.42.1 → 1.43.0

package/src/config/help.ts

@@ -1,151 +0,0 @@
-// [LAW:one-type-per-behavior] candybar-settings-ui-aok.6 — the `(?)` affordance.
-// It is NOT a fourth kind of disclosure. A `(?)` is the SAME binary toggle
-// `kind: "group"`, `{{ menu }}`, edit mode's trigger and the global settings menu
-// all are; it differs from a group in exactly two VALUES — the text its trigger
-// binds (`(?)`/`✕` rather than `label ▸`/`label ▾`) and what its body contains
-// (help lines rather than arbitrary layout). So every artifact below comes out
-// of `disclosure.ts`, and this module contributes no state, no gate, and no
-// glyph rule of its own — only the two values and the shape they fill.
-//
-// The ticket that asked for this predicted the alternative: "if it arrives as
-// another hand-rolled set of four artifacts, the finding to report is that the
-// disclosure itself wants to be one thing". It did. `disclosure.ts` had
-// single-sourced only the two artifacts that are DATA (the state var, the cycle
-// action) and left the two that are STRINGS — the trigger template and the body
-// gate — hand-written at five sites, which is where the `+▸` double-glyph bug of
-// .4 lived. `disclosureTrigger`/`disclosureGate` finish that extraction, and
-// this file is the first caller that never had a copy to begin with.
-//
-// [LAW:one-way-deps] Content is a PARAMETER, never an import: this module knows
-// how to mint a help disclosure and nothing about what any particular one says.
-// The bundled sentences live in `src/help-text.ts` — the corpus `--help` prints
-// — and the two synthesis passes that place a `(?)` pass them in. That is what
-// keeps the bar's help and the CLI's help one set of strings rather than two
-// hand-maintained copies [LAW:one-source-of-truth].
-
-import type { ActionDecl } from "./action.js";
-import type { LayoutNode, SegmentDecl, VariableDecl } from "./dsl-types.js";
-import {
-  DISCLOSURE_CLOSED,
-  DISCLOSURE_GLYPH_CLOSE,
-  disclosureCycleAction,
-  disclosureGate,
-  disclosureStateVar,
-  disclosureTrigger,
-  type DisclosureRef,
-} from "./disclosure.js";
-
-// [LAW:one-source-of-truth] The trigger's closed text, one spelling for the
-// whole bar so a reader learns the affordance once. Its OPEN text is the shared
-// `DISCLOSURE_GLYPH_CLOSE` — the same ✕ a picker's close cell and edit mode's
-// opened `+` wear, because it is the same meaning: click to close what this
-// opened.
-//
-// [LAW:no-silent-failure] Deliberately per-state rather than one static `(?)`.
-// Several `(?)` triggers can be visible at once (edit mode's and the config
-// menu's, whenever both surfaces are open), and the tint that distinguishes
-// other open disclosures — node-registry's `drops.length > 0` — recolours a
-// segment's RESOLVED BACKGROUND, so it is a no-op on any segment declaring no
-// bg. .5 gave edit mode a look at the GLOBALS level only, which left its insert
-// chrome without one; the trigger's own text is therefore the only place the
-// open state can be read, exactly as it is for the `+` beside it.
-export const HELP_GLYPH_CLOSED = "(?)";
-
-// The open member of a help disclosure's binary key: it holds this or the shared
-// CLOSED sentinel, like every other binary disclosure in the bar.
-const HELP_OPEN = "open";
-
-// [LAW:one-source-of-truth] The declarations a `(?)` contributes, keyed by final
-// name — the same accumulator shape `ChromeArtifacts`/`MenuArtifacts` already
-// thread through their synthesis passes, so a caller merges one more set of
-// artifacts the way it already merges its own.
-export interface HelpArtifacts {
-  readonly variables: Record<string, VariableDecl>;
-  readonly actions: Record<string, ActionDecl>;
-  readonly segments: Record<string, SegmentDecl>;
-}
-
-// [LAW:types-are-the-program] The two nodes a caller must place, returned
-// separately because they belong in different rows and only the caller knows
-// which: the trigger is a CELL that joins a row the caller already has (so
-// opening help never widens the bar and closed help costs no row), and the body
-// is a ROW of its own that exists only while the disclosure is open.
-export interface HelpDisclosure {
-  readonly trigger: LayoutNode;
-  readonly body: LayoutNode;
-}
-
-// Mint one `(?)` and its body.
-//
-// `name` is the reserved-namespace base every artifact derives from — the
-// trigger segment, the state variable and the cycle action all take it
-// verbatim, the same one-name-four-artifacts convention `groups.<name>` and
-// `settings.menu` already use, so the toggle's click and the body's gate cannot
-// address different keys [LAW:one-source-of-truth].
-//
-// `within` names the disclosures this help sits INSIDE (edit mode, the settings
-// menu). Both nodes inherit those gates, so a `(?)` opened inside a surface that
-// is then closed cannot leave its body stranded on the bar — the body's gate is
-// its own ref AND every enclosing one, which is what "open" actually means for a
-// nested disclosure [LAW:dataflow-not-control-flow].
-export function declareHelp(
-  name: string,
-  lines: readonly string[],
-  within: readonly DisclosureRef[],
-  out: HelpArtifacts,
-  surface?: { readonly bg: string; readonly fg: string },
-): HelpDisclosure {
-  const self: DisclosureRef = { variable: name, member: HELP_OPEN };
-  out.variables[name] = disclosureStateVar(name, DISCLOSURE_CLOSED);
-  out.actions[name] = disclosureCycleAction(name, HELP_OPEN);
-  out.segments[name] = {
-    template: disclosureTrigger(
-      name,
-      HELP_GLYPH_CLOSED,
-      DISCLOSURE_GLYPH_CLOSE,
-    ),
-    ...surface,
-    // The trigger is visible wherever its host surface is. An unnested `(?)`
-    // (`within` empty) is always visible, and declares no `when` at all.
-    ...gateOf(within),
-  };
-
-  // [LAW:one-source-of-truth] One line is one SEGMENT whose template is that
-  // line VERBATIM — no wrapper text, no joining, no reformatting, and no
-  // escaping. A `template` IS template source, so its static runs reach the bar
-  // unchanged; escaping belongs to text spliced INSIDE a quoted `{{ }}` argument
-  // (what `disclosureTrigger` above does, and this is not), and applying it here
-  // would put backslashes on the bar the moment a sentence used a quote. That is
-  // what makes "the bar's help IS the corpus" checkable as identity rather than
-  // as string similarity: the declaration a test reads and the sentence
-  // `src/help-text.ts` exports are one value, byte for byte.
-  const bodyGate = disclosureGate(self, ...within);
-  const children = lines.map((line, i): LayoutNode => {
-    const lineName = `${name}.${i}`;
-    // [LAW:single-enforcer] The gate lives on the body container below and
-    // nowhere else — the render walk ANDs an ancestor's `when` into every
-    // descendant (src/dsl/render.ts:764), so a copy here would be a second
-    // enforcer of one predicate with nothing keeping the two equal.
-    out.segments[lineName] = { template: line, ...surface };
-    return { kind: "segment", name: lineName };
-  });
-
-  return {
-    trigger: { kind: "segment", name },
-    body: {
-      kind: "container",
-      direction: "horizontal",
-      children,
-      when: bodyGate,
-    },
-  };
-}
-
-// The enclosing gate as an optional `when` field — the codebase's standard
-// spelling for "this field exists only when there is something to put in it",
-// keeping `disclosureGate`'s first argument required so a gate over nothing
-// stays unrepresentable.
-function gateOf(within: readonly DisclosureRef[]): { when?: string } {
-  const [first, ...rest] = within;
-  return first === undefined ? {} : { when: disclosureGate(first, ...rest) };
-}

package/src/config/ident.ts

@@ -1,22 +0,0 @@
-// [LAW:one-source-of-truth] THE identifier-collapse rule — collapse an
-// arbitrary name (a segment, action, preset, or menu-host name) to an
-// identifier-shaped fragment so synthesized var/action/segment names carry
-// no dots, brackets, or other characters that would break a template field
-// path or a synthesis-time accumulator key. Every non-alphanumeric RUN
-// collapses to a single `_`.
-//
-// [LAW:no-silent-failure] Multiple sites depend on this SAME collapse
-// producing the SAME result for the SAME input: menu-keys.ts derives a
-// menu's synthesized SessionState/action identity from it; edit-chrome.ts
-// keys synthesized per-preset reset/±-chrome artifacts by it;
-// loader/cross-ref.ts's presetIdentCollisions checks that no two preset
-// names collide under it BEFORE edit-chrome.ts ever runs. Before this
-// module existed, three call sites reimplemented the same regex
-// independently (module-privacy taken too far) — a genuine drift risk: if
-// one copy changed without the others, the collision GUARD would stop
-// matching the collision RULE it exists to enforce, silently reopening the
-// exact "second preset steals the first's synthesized action" bug the
-// guard was written to prevent. One function now; every site imports it.
-export function ident(name: string): string {
-  return name.replace(/[^A-Za-z0-9]+/g, "_");
-}

package/src/config/layout-ops.ts

@@ -1,177 +0,0 @@
-// [LAW:one-type-per-behavior] The seam brandon-layout-edit-2gc.1 opens: a
-// bounded, statically-enumerable vocabulary for mutating a LayoutNode tree —
-// remove the segment named X, insert a named segment before/after an
-// existing one. No third LayoutNode kind, no free-form tree editing: a
-// segment's own NAME is the stable position (dsl-types.ts already makes it
-// one — SegmentNode.name is a ref into `segments`, unaffected by a sibling
-// being added or removed elsewhere in the tree), so there is no sibling-index
-// to invalidate when a prior op lands.
-//
-// [LAW:no-ambient-temporal-coupling] A position is never a fact frozen at
-// declaration or click time — `removeSegment`/`insertSegment` always walk
-// the CURRENT tree handed to them. The daemon (src/daemon/cache/render.ts)
-// replays the accumulated op log against the live merged config on every
-// reload, so a later, unrelated config edit is what the next replay sees,
-// never a stale snapshot.
-//
-// [LAW:no-silent-failure] exception: a target/anchor absent from the tree is
-// a documented NO-OP, not a thrown error — mirroring
-// src/config/loader/merge.ts's applySegmentPaletteOverrides, the identical
-// failure shape one layer up. A validated action can only ever name a
-// segment the config declares (loader/cross-ref.ts checks this at config
-// load), so a miss here only happens after a LATER edit (to the bundled
-// default, the user's config, or an earlier op in the same accumulated list)
-// removed the segment — there is nothing left to apply the op to, and
-// bricking the whole render over a stale op would be worse than dropping it.
-
-import type { LayoutNode, SegmentNode } from "./dsl-types.js";
-
-// [LAW:types-are-the-program] The two operations brandon-layout-edit-2gc.1
-// ships. Both address position by NAME, never by index. A future op (e.g.
-// "move") is a new arm here, not a new node kind or a new codec.
-export type LayoutOp =
-  | { readonly op: "remove"; readonly target: string }
-  | {
-      readonly op: "insert";
-      readonly segment: string;
-      readonly anchor: string;
-      readonly relation: "before" | "after";
-    };
-
-// [LAW:single-enforcer] THE codec for a LayoutOp crossing the click wire and
-// the config-overrides file as one opaque string. `:` is the delimiter
-// (loader/actions.ts's segmentNameSpec rejects `:` and `/` in every name an
-// op can carry, so decode is unambiguous — a plain split, no escaping).
-// Encode and decode live together so the format cannot drift between the
-// validator gate (config-validators.ts, which encodes the ONE token a
-// declared action allows), the render side (which emits that same token),
-// and the daemon (which decodes it back).
-export function encodeLayoutOp(op: LayoutOp): string {
-  return op.op === "remove"
-    ? `remove:${op.target}`
-    : `insert:${op.segment}:${op.anchor}:${op.relation}`;
-}
-
-// [LAW:parse-dont-validate] Returns the typed op, or null for anything that
-// doesn't decode — the boundary a caller stamps before trusting the shape.
-// Reached only from data this process did not itself just encode (a
-// hand-edited or previous-version config-overrides.json), never from a
-// value produced by encodeLayoutOp in the same click.
-export function decodeLayoutOp(token: string): LayoutOp | null {
-  const parts = token.split(":");
-  if (parts[0] === "remove" && parts.length === 2 && parts[1]) {
-    return { op: "remove", target: parts[1] };
-  }
-  if (
-    parts[0] === "insert" &&
-    parts.length === 4 &&
-    parts[1] &&
-    parts[2] &&
-    (parts[3] === "before" || parts[3] === "after")
-  ) {
-    return {
-      op: "insert",
-      segment: parts[1],
-      anchor: parts[2],
-      relation: parts[3],
-    };
-  }
-  return null;
-}
-
-// [LAW:single-enforcer] THE one collector of "which segment names does this
-// tree contain" — brandon-layout-edit-2gc.3's edit-chrome synthesis
-// (src/config/edit-chrome.ts) uses it to compute both halves of the +/-
-// affordances: which segments are PRESENT (get a `-`) and, by set difference
-// against every declared segment, which are ADDABLE (populate the `+`
-// picker's domain). A name appearing more than once collapses to one entry —
-// callers that care about occurrence COUNT (none currently do) need a
-// different walk.
-export function collectSegmentNames(root: LayoutNode): ReadonlySet<string> {
-  const out = new Set<string>();
-  const walk = (node: LayoutNode): void => {
-    if (node.kind === "segment") {
-      out.add(node.name);
-      return;
-    }
-    for (const child of node.children) walk(child);
-  };
-  walk(root);
-  return out;
-}
-
-// [LAW:dataflow-not-control-flow] Ops are DATA folded over the tree in
-// order — replaying zero ops is the identity fold, replaying N is the same
-// reduce for every N. No branch on "are there ops to apply."
-export function applyLayoutOps(
-  root: LayoutNode,
-  ops: readonly LayoutOp[],
-): LayoutNode {
-  return ops.reduce(applyOne, root);
-}
-
-function applyOne(root: LayoutNode, op: LayoutOp): LayoutNode {
-  return op.op === "remove"
-    ? removeSegment(root, op.target)
-    : insertSegment(root, op.segment, op.anchor, op.relation);
-}
-
-// [LAW:types-are-the-program] Total and non-throwing: every LayoutNode maps
-// to a LayoutNode, whether or not `target` is present. Acts on the FIRST
-// segment found named `target`, in walkNodes' canonical pre-order — a
-// deterministic, documented tie-break for the edge case of a duplicate name,
-// never an ambiguous or thrown outcome. `done` is a closure-local flag (fresh
-// per call, never shared across calls) that stops the search the instant a
-// match is spliced out, so an EARLIER sibling's match always wins over a
-// LATER one — exactly walkNodes' visit order, not merely "this container's
-// own children before its descendants" (a subtly different, wrong order a
-// single-pass children-array scan would produce). An absent target returns
-// the identical root reference.
-function removeSegment(root: LayoutNode, target: string): LayoutNode {
-  let done = false;
-  function walk(node: LayoutNode): LayoutNode {
-    if (done || node.kind === "segment") return node;
-    const children: LayoutNode[] = [];
-    for (const child of node.children) {
-      if (!done && child.kind === "segment" && child.name === target) {
-        done = true;
-        continue;
-      }
-      children.push(walk(child));
-    }
-    return { ...node, children };
-  }
-  const result = walk(root);
-  return done ? result : root;
-}
-
-// [LAW:types-are-the-program] Splices a new `{ kind: "segment", name:
-// segment }` node immediately before/after the FIRST node found named
-// `anchor`, in walkNodes' canonical pre-order (see removeSegment's `done`
-// note — the same closure-local stop-at-first-match shape). Total and
-// non-throwing: an absent anchor returns the identical root reference.
-function insertSegment(
-  root: LayoutNode,
-  segment: string,
-  anchor: string,
-  relation: "before" | "after",
-): LayoutNode {
-  let done = false;
-  function walk(node: LayoutNode): LayoutNode {
-    if (done || node.kind === "segment") return node;
-    const children: LayoutNode[] = [];
-    for (const child of node.children) {
-      if (!done && child.kind === "segment" && child.name === anchor) {
-        done = true;
-        const inserted: SegmentNode = { kind: "segment", name: segment };
-        if (relation === "before") children.push(inserted, child);
-        else children.push(child, inserted);
-        continue;
-      }
-      children.push(walk(child));
-    }
-    return { ...node, children };
-  }
-  const result = walk(root);
-  return done ? result : root;
-}