@promptctl/cc-candybar 1.0.0

package/src/click/wire.ts

@@ -0,0 +1,113 @@
+// [LAW:single-enforcer] THE click-wire codec. A click is an ordered list of
+// effects; this module is the one place that serializes that list to a URL and
+// parses it back. The renderer (every click emitter) calls effectsUrl; the
+// daemon's `dispatch` verb calls parseEffects. Encode and decode live together
+// so the format cannot drift between the two halves [LAW:one-source-of-truth].
+//
+// [LAW:dataflow-not-control-flow] N effects ride one URL the SAME way for N=1 and
+// N=100 — a lone click is the degenerate one-element list. There is no
+// plain-vs-compound mode: every URL effectsUrl emits is `dispatch/e=…`, and the
+// effect COUNT is data the dispatcher folds over, never a branch that selects a
+// wire. (The wire still ACCEPTS direct `cc-candybar://<verb>/…` URLs — old
+// scrollback links, a hand-authored `link` template — so a direct verb is the
+// degenerate one-effect case on the parse side; only emission is unified here.)
+//
+// Why query params (not slashes, not base64): the value handed to the daemon is
+// passed RAW (parseHandlerUrl decodes only the verb), so each `e` param survives
+// exactly one URLSearchParams decode and an effect's own slash-bearing value
+// (a path, a set-state key/value tail) round-trips untouched. base64 was
+// rejected as opaque; a slash-nested payload is unsafe under any single
+// whole-value decode (a `%2F` would un-escape into a structural separator). The
+// `e=…&e=…` payload follows the verb after a `/` (`dispatch/e=…`), NOT a `?`, so
+// `/` stays the one verb delimiter and `?` remains ordinary data in a bare-copy
+// value (`cc-candybar://hello?world`).
+
+import { URLSearchParams } from "node:url";
+
+// [LAW:one-source-of-truth] The scheme string lives here, with the codec that
+// emits it; install/ (Launch Services registration) imports it.
+export const URL_SCHEME = "cc-candybar";
+
+// [LAW:one-source-of-truth] The verb vocabulary. The daemon's VERBS registry
+// keys off these and every emitter builds effects with them, so the emitted
+// verb and the dispatched handler cannot name-drift.
+export const VERB_DISPATCH = "dispatch";
+export const VERB_SET_STATE = "set-state";
+// [LAW:types-are-the-program] A RELATIVE state nudge: its args are
+// `[sessionId, key, by]` where `by` is the signed integer delta. Distinct from
+// set-state because the click intent is "step from whatever the value IS now",
+// not "set to this fixed value" — the absolute target is computed at APPLY time
+// from live state, so the link carries no `current` snapshot and N rapid clicks
+// each re-read-and-write. Additive: old set-state links still resolve.
+export const VERB_STEP_STATE = "step-state";
+export const VERB_COPY = "copy";
+export const VERB_OPEN_VSCODE = "open-vscode";
+export const VERB_TOOLBAR_TOGGLE = "toolbar-toggle";
+export const VERB_SHOW_CONFIG_ERROR = "show-config-error";
+export const VERB_SHOW_CONFIG_WARNING = "show-config-warning";
+// [LAW:effects-at-boundaries] A daemon-global config override: the verb writes
+// the override path (or clears it with an empty value); the render pipeline
+// reads it at the cache-lookup boundary. Clicking a different config is a
+// side-effect isolated to the verb handler; the renderer only sees the result.
+export const VERB_LOAD_CONFIG = "load-config";
+
+// [LAW:types-are-the-program] An effect to EMIT: a verb plus its raw (unencoded)
+// positional args. The wire owns all encoding — callers never percent-encode.
+// set-state's args are `[sessionId, key, value, …]`; copy/open carry one arg.
+export interface Effect {
+  readonly verb: string;
+  readonly args: readonly string[];
+}
+
+// [LAW:types-are-the-program] A parsed effect as the dispatcher sees it: the verb
+// and the still-encoded segment tail. The tail stays encoded because the target
+// verb's handler decodes its own segments at its boundary (single-enforcer per
+// verb) — the same contract a direct (non-dispatch) click URL hands a handler.
+export interface ParsedEffect {
+  readonly verb: string;
+  readonly value: string;
+}
+
+// [LAW:single-enforcer] The segment codec. A verb's args serialize to a
+// slash-joined run of percent-encoded segments; the handler decodes the inverse.
+// Encoding each segment means a segment's own `/` becomes `%2F` and never reads
+// as a separator — the slash-safety the old whole-value decode could not give.
+export function encodeSegments(parts: readonly string[]): string {
+  return parts.map(encodeURIComponent).join("/");
+}
+
+export function decodeSegments(value: string): string[] {
+  return value.length === 0 ? [] : value.split("/").map(decodeURIComponent);
+}
+
+// Serialize an effect list to its dispatch URL. Each effect becomes one ordered
+// `e` query param carrying `verb/<encoded-args>`, percent-encoded whole so its
+// internal `/`, `&`, `=` survive as data. The payload follows `dispatch/` (not
+// `dispatch?`) so `/` is the only verb delimiter parseHandlerUrl needs.
+export function effectsUrl(effects: readonly Effect[]): string {
+  const qs = effects
+    .map(
+      (e) => `e=${encodeURIComponent(`${e.verb}/${encodeSegments(e.args)}`)}`,
+    )
+    .join("&");
+  return `${URL_SCHEME}://${VERB_DISPATCH}/${qs}`;
+}
+
+// [LAW:dataflow-not-control-flow] Parse the dispatch verb's raw value (an
+// `e=…&e=…` query string) into the ordered effect list. URLSearchParams decodes
+// each param exactly once and preserves insertion order; splitting each on the
+// FIRST `/` recovers (verb, still-encoded tail) — the same split parseHandlerUrl
+// applies at the top level, one level down.
+export function parseEffects(rawValue: string): ParsedEffect[] {
+  return new URLSearchParams(rawValue).getAll("e").map(splitVerb);
+}
+
+// [LAW:types-are-the-program] Split a `verb/tail` string at the first `/`. A
+// verb with no args (no slash) yields an empty tail — the degenerate case, not a
+// guard. The tail keeps its slashes (further segments) for the handler to decode.
+export function splitVerb(s: string): ParsedEffect {
+  const i = s.indexOf("/");
+  return i === -1
+    ? { verb: s, value: "" }
+    : { verb: s.slice(0, i), value: s.slice(i + 1) };
+}

package/src/config/action.ts

@@ -0,0 +1,91 @@
+// [LAW:types-are-the-program] The author-facing SHAPE of a decoupled, named
+// ACTION — the config-file schema for `DslConfig.actions`. Pure data (no engine,
+// no rich-js): the strongest theorem about what a user can declare. The loader
+// narrows `unknown` to these; the runtime (render/action.ts) and the validator
+// derivation (daemon/verbs/state-validators.ts) consume them.
+//
+// [LAW:locality-or-seam] An action is the SEAM between the clickable
+// REPRESENTATION (a template region, `{{ action "name" … }}`) and the BEHAVIOR
+// (what the click does). They are joined by NAME: re-glyph a button without
+// touching behavior; re-target an action without touching the template. This is
+// the successor to the widget surface — a widget couples representation and
+// behavior in one declaration; an action splits them so one template expresses
+// anything (text, state-driven display, clickable regions) and the action table
+// is the single, statically-enumerable set of effects those regions can fire.
+//
+// [LAW:one-source-of-truth] Because a `set` action carries its key and value
+// SOURCE as literal data (a literal `to`, an option domain, or numeric bounds),
+// the writable-key gate DERIVES from the action table (deriveActionValidators).
+// A template references a NAME; it cannot smuggle an un-gated write. The rendered
+// click and the gate share ONE source — the action declaration.
+//
+// [LAW:one-source-of-truth] The option-domain + effect-verb vocabulary lives
+// HERE — action.ts is the surviving home now that the widget surface is gone.
+// These are the shapes a picker draws options from and the set/copy/open/int
+// discriminator the loader and the validator-derivation match on.
+
+// [LAW:one-source-of-truth] The domain lists a picker draws options from. Same
+// canonical sources the `themes()`/`styles()` bindings and the set-state
+// validators consult — the rendered options and the derived gate cannot diverge
+// because there is no second enumeration.
+export type OptionSource = "themes" | "styles";
+export const OPTION_SOURCES: readonly OptionSource[] = ["themes", "styles"];
+
+// [LAW:types-are-the-program] The top-level discriminator of an ActionDecl — the
+// click effect is keyed by which of these is present. The loader proves
+// exactly-one-of; the renderer and validator-derivation match with no fallthrough.
+export const ACTION_KEYS = ["set", "copy", "open"] as const;
+export type ActionKey = (typeof ACTION_KEYS)[number];
+
+// [LAW:types-are-the-program] An ActionDecl is the click effect a named action
+// binds to. The top-level discriminator is which of `set`/`copy`/`open` is
+// present (the CacheDecl/widget-Action pattern); a `set` is sub-discriminated by
+// its value SOURCE — `to` (literal), `from` (option-bound), or `min/max/by`
+// (bounded step). The loader proves exactly-one-of at each level; the renderer
+// and the validator-derivation match on the present key with no fallthrough.
+//
+//   set + to            — write a literal value -> allow-list {to}
+//   set + from          — write the option the template binds at render
+//                         (a picker ranges the domain) -> allow-list {options}
+//   set + min/max/by    — write wrap(current ± by) clamped to [min,max]
+//                         (a stepper affordance) -> range [min,max]
+//   set + int           — write any integer the render binds (a paged cursor:
+//                         -1 closed / 0..N pages, clamp owned by the renderer)
+//                         -> int gate (unbounded). The missing primitive a
+//                         width-paginated picker needs — its page key accepts any
+//                         integer, which no bounded/literal arm can express.
+//   set + cycle         — write the SUCCESSOR of the current value in the
+//                         member list, wrapping; a current value outside the
+//                         domain counts as the first member (so the second
+//                         member is the "first click" target — order members
+//                         default-state-first). The bounded stepper's sibling:
+//                         a stepper steps a range, a cycle steps an enumerated
+//                         domain (toggles, N-state cyclers, accordion paths)
+//                         -> allow-list {members}
+//   copy                — copy templated text to the clipboard -> no gate
+//   open                — open a templated target in the editor -> no gate
+//
+// [LAW:one-source-of-truth] Only `set` writes SessionState, so only `set`
+// derives a validator. copy/open write nothing — they derive nothing. The
+// vocabulary grows by arms (a future `run`/`open-url`), not by validator plumbing.
+export type ActionDecl =
+  | { readonly set: string; readonly to: string }
+  | { readonly set: string; readonly from: OptionSource }
+  | {
+      readonly set: string;
+      readonly min: number;
+      readonly max: number;
+      readonly by: number;
+    }
+  | { readonly set: string; readonly int: true }
+  | { readonly set: string; readonly cycle: readonly string[] }
+  | { readonly copy: string }
+  | { readonly open: string };
+
+// [LAW:dataflow-not-control-flow] Does this action write a SessionState key? A
+// `set` action composes a set-state click URL whose first segment is session.id;
+// copy/open embed none. One predicate the loader's session.id requirement folds
+// over — no per-arm branching at the callsite.
+export function actionBindsSet(a: ActionDecl): boolean {
+  return "set" in a;
+}

package/src/config/cli.ts

@@ -0,0 +1,170 @@
+// [LAW:single-enforcer] Config-tooling CLI entry points. `lint` and `schema`
+// share one module because they share one change-reason: the config grammar.
+// Neither carries validation or schema LOGIC — `lint` is a second entry point
+// into the loader (the single config-validation enforcer the daemon also uses),
+// and `schema` serves the build-generated artifact (derived from the config
+// types). Both are bindings, not reimplementations [LAW:one-source-of-truth].
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { loadConfig, validateConfig } from "./dsl-loader.js";
+import { ConfigError } from "./loader/diagnostics.js";
+
+// Exit codes are a contract (the CLI guideline: not just 0/1), so scripts and
+// editors can distinguish "your config is wrong" from "I couldn't run":
+//   0 — config is valid
+//   1 — config is invalid (ConfigError: structural, cross-ref, or cycle)
+//   2 — usage error or the file could not be read
+const EXIT_VALID = 0;
+const EXIT_INVALID = 1;
+const EXIT_USAGE = 2;
+
+// [LAW:dataflow-not-control-flow] The lint result is DATA — a pure function of
+// the target file's contents — discriminated into the three outcomes the exit-
+// code contract projects. `lintConfig` carries the decision; `runLint` only maps
+// it to (stream, exit). The decision is unit-testable without spawning a process
+// or stubbing process.exit, which is what makes the exit-code goal verifiable.
+export type LintOutcome =
+  | { readonly kind: "valid"; readonly path: string }
+  | { readonly kind: "invalid"; readonly message: string }
+  | {
+      readonly kind: "unreadable";
+      readonly path: string;
+      readonly message: string;
+    };
+
+// Run the real loader (parse → merge-with-default → cross-ref + cycle validation)
+// against an arbitrary file. No daemon: the loader imports only fs, JSON5, and
+// pure validators, so the same errors the daemon would surface at render time are
+// surfaced here ahead of time.
+//
+// [LAW:single-enforcer] loadConfig + validateConfig is the identical pipeline
+// RenderCache.reloadInto runs in the daemon — the validation authority is one
+// function, so lint cannot drift from production. The source we read is passed to
+// validateConfig only to sharpen line numbers (semantic issues map to lines).
+export function lintConfig(target: string): LintOutcome {
+  const resolved = path.resolve(target);
+
+  let source: string;
+  try {
+    source = fs.readFileSync(resolved, "utf-8");
+  } catch (e) {
+    return {
+      kind: "unreadable",
+      path: target,
+      message: e instanceof Error ? e.message : String(e),
+    };
+  }
+
+  try {
+    const { config } = loadConfig(resolved);
+    validateConfig(config, resolved, source);
+  } catch (e) {
+    if (e instanceof ConfigError)
+      return { kind: "invalid", message: e.message };
+    throw e;
+  }
+
+  return { kind: "valid", path: target };
+}
+
+// `cc-candybar lint <path>` — the argv binding. Missing-arg is a usage concern
+// (not a lint outcome), handled here; everything else is the projection of
+// lintConfig's outcome onto the stream + exit-code contract.
+export function runLint(args: readonly string[]): void {
+  const target = args[0];
+  if (target === undefined || target === "") {
+    process.stderr.write(
+      "lint: missing <path>\nUsage: cc-candybar lint <config-file>\n",
+    );
+    process.exit(EXIT_USAGE);
+  }
+  applyLintOutcome(lintConfig(target));
+}
+
+// [LAW:dataflow-not-control-flow] The outcome → (stream, text, exit-code) mapping
+// is DATA. `lintPlan` is a total fold returning that descriptor (a non-returning
+// arm fails the typecheck, so the projection stays exhaustive over LintOutcome);
+// `applyLintOutcome` runs the single write + exit against it. The side effects
+// are unconditional; the data decides their content.
+interface LintPlan {
+  readonly stream: NodeJS.WriteStream;
+  readonly text: string;
+  readonly code: number;
+}
+
+function lintPlan(o: LintOutcome): LintPlan {
+  switch (o.kind) {
+    case "valid":
+      return {
+        stream: process.stdout,
+        text: `✓ ${o.path}: config valid\n`,
+        code: EXIT_VALID,
+      };
+    case "invalid":
+      return {
+        stream: process.stderr,
+        text: o.message + "\n",
+        code: EXIT_INVALID,
+      };
+    case "unreadable":
+      return {
+        stream: process.stderr,
+        text: `lint: cannot read ${o.path}: ${o.message}\n`,
+        code: EXIT_USAGE,
+      };
+  }
+}
+
+function applyLintOutcome(o: LintOutcome): never {
+  const plan = lintPlan(o);
+  plan.stream.write(plan.text);
+  process.exit(plan.code);
+}
+
+// Read the build-generated JSON Schema for the config file shape (RawDslConfig),
+// or null when the artifact is absent. Pure read — `runSchema` owns the side
+// effects, so the locate-and-read path is testable.
+export function loadSchemaText(): string | null {
+  const schemaPath = locateSchema();
+  return schemaPath === null ? null : fs.readFileSync(schemaPath, "utf-8");
+}
+
+// `cc-candybar schema` — print the schema so an editor can annotate a config with
+// `"$schema": "<this output, saved somewhere>"` (or the stable published URL) for
+// autocomplete + structural validation. Emitted from the loader schemas at build
+// time (scripts/gen-schema.ts → emitConfigSchema); served verbatim here (the
+// emitter runs at build, not ship time).
+export function runSchema(): void {
+  const text = loadSchemaText();
+  if (text === null) {
+    process.stderr.write(
+      "schema: bundled schema not found (expected schema/cc-candybar.schema.json). " +
+        "Run `pnpm gen:schema` from a source checkout.\n",
+    );
+    process.exit(EXIT_USAGE);
+  }
+  process.stdout.write(text);
+  process.exit(EXIT_VALID);
+}
+
+// [LAW:locality-or-seam] The schema sits at `<package-root>/schema/...`. Anchor
+// on the running CLI entry (argv[1] — `dist/index.mjs` in prod, since every
+// subcommand execs the Node fallback) and walk up to the nearest ancestor that
+// holds the artifact, so the prod and dev layouts aren't special-cased. argv[1]
+// (not import.meta) keeps this resolvable identically under the ESM bundle and
+// any module setting.
+function locateSchema(): string | null {
+  const rel = path.join("schema", "cc-candybar.schema.json");
+  const anchor = process.argv[1];
+  if (anchor === undefined) return null;
+  let dir = path.dirname(path.resolve(anchor));
+  for (;;) {
+    const candidate = path.join(dir, rel);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}