@promptctl/cc-candybar 1.0.0

package/src/config/loader/diagnostics.ts

@@ -0,0 +1,99 @@
+// [LAW:single-enforcer] One home for config-error reporting: the public issue/
+// error types, the best-effort source-line lookup every validator calls, and the
+// human-readable formatter ConfigError renders. Changes here are display/source-
+// mapping changes; the schema validators never touch this file.
+
+// ─── Public types ────────────────────────────────────────────────────────────
+
+export interface ConfigIssue {
+  /** Dotted logical path inside the config (e.g., "variables.foo.cache"). */
+  readonly path: string;
+  /** Short, actionable description of the problem. */
+  readonly message: string;
+  /** Source line (1-based). For semantic errors, best-effort from the path. */
+  readonly line?: number;
+  /** Source column (1-based). Present only for parse errors. */
+  readonly col?: number;
+}
+
+export class ConfigError extends Error {
+  readonly file: string;
+  readonly issues: readonly ConfigIssue[];
+
+  constructor(file: string, issues: readonly ConfigIssue[]) {
+    super(formatIssues(file, issues));
+    this.name = "ConfigError";
+    this.file = file;
+    this.issues = issues;
+  }
+}
+
+// ─── Best-effort source-line lookup ──────────────────────────────────────────
+
+// Walk source forward, finding each path component as a JSON5 key in turn.
+// JSON5 keys are unquoted identifiers (`foo:`), double-quoted strings, or
+// single-quoted strings. Numeric path parts (e.g., layout indices) are
+// skipped — they point inside arrays where line lookup is less useful.
+//
+// This is "good enough" navigation, not a guarantee. Returns undefined if a
+// path part can't be located — the caller falls back to the logical path.
+export function findKeyLine(
+  source: string,
+  pathParts: readonly string[],
+): number | undefined {
+  let cursor = 0;
+  let foundCursor: number | undefined;
+  for (const part of pathParts) {
+    if (part === "" || /^\d+$/.test(part)) continue;
+    const found = findKeyOccurrence(source, cursor, part);
+    if (found === -1) {
+      return foundCursor !== undefined
+        ? lineFromOffset(source, foundCursor)
+        : undefined;
+    }
+    cursor = found;
+    foundCursor = found;
+  }
+  return foundCursor !== undefined
+    ? lineFromOffset(source, foundCursor)
+    : undefined;
+}
+
+function findKeyOccurrence(source: string, from: number, key: string): number {
+  // Match `<key>:` or `"<key>":` or `'<key>':` — any whitespace before the colon
+  // is allowed by JSON5. Escape regex specials in key.
+  const escaped = key.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+  const re = new RegExp(`(?:["']${escaped}["']|\\b${escaped}\\b)\\s*:`, "g");
+  re.lastIndex = from;
+  const m = re.exec(source);
+  return m ? m.index : -1;
+}
+
+function lineFromOffset(source: string, offset: number): number {
+  let line = 1;
+  for (let i = 0; i < offset && i < source.length; i++) {
+    if (source.charCodeAt(i) === 0x0a) line++;
+  }
+  return line;
+}
+
+// ─── Error formatting ────────────────────────────────────────────────────────
+
+function formatIssues(file: string, issues: readonly ConfigIssue[]): string {
+  if (issues.length === 0) return `${file}: invalid config (no details)`;
+  const lines: string[] = [
+    `Invalid config in ${file} (${issues.length} issue${issues.length === 1 ? "" : "s"}):`,
+  ];
+  for (const issue of issues) {
+    const locParts: string[] = [];
+    if (issue.line !== undefined) {
+      locParts.push(
+        `line ${issue.line}${issue.col !== undefined ? `:${issue.col}` : ""}`,
+      );
+    }
+    if (issue.path) locParts.push(issue.path);
+    const loc = locParts.length > 0 ? `[${locParts.join(" • ")}] ` : "";
+    lines.push(`  ${loc}${issue.message}`);
+  }
+  return lines.join("\n");
+}

package/src/config/loader/discovery.ts

@@ -0,0 +1,182 @@
+// [LAW:single-enforcer] Config-file discovery: where the DSL config can live, in
+// what precedence, and how `~` expands. One candidate-path enumerator feeds the
+// resolver, the watchers, and the collision detector so none can disagree about
+// which files are candidates. This file changes when the resolution rules change.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// [LAW:one-source-of-truth] The set of accepted extensions lives here once.
+// Both .json5 and .json are accepted: JSON ⊂ JSON5, so the same parser
+// (JSON5.parse) handles both — only the filename lookup varies. Ordering is
+// load-bearing: .json5 wins over .json at the same location (documented
+// format > compatibility tail).
+const CONFIG_EXTENSIONS = ["json5", "json"] as const;
+
+// [LAW:single-enforcer] One implementation of `~`-prefix expansion, called at
+// each trust boundary that takes a user-supplied path. The CLI `--config`
+// value is expanded in `parseRenderArgs` (server.ts) before it ever reaches
+// here; `CC_CANDYBAR_CONFIG` is expanded below where the env var is read.
+// One function, one rule, two callers.
+//
+// [LAW:enumeration-gap] Only the shell-standard home-expansion forms trigger
+// replacement: bare `~`, `~/...`, or `~\...` on Windows. A string like
+// `~alice/cfg` (POSIX named-home lookup) is NOT expanded — we have no way
+// to resolve another user's home and a literal substitution would corrupt
+// the path (`<homedir>alice/cfg`).
+export function expandHome(p: string): string {
+  return p === "~" || p.startsWith("~/") || p.startsWith("~\\")
+    ? os.homedir() + p.slice(1)
+    : p;
+}
+
+/**
+ * The full ordered list of candidate paths the DSL config could live at,
+ * for a given (projectDir, cwd). Returned regardless of which exist — the
+ * cache uses this to watch every candidate location so the creation of any
+ * file in the resolution chain triggers hot-reload.
+ *
+ * `configFile` is the highest-precedence entry — the path resolved from the
+ * client's `--config` flag (already `~`-expanded at the trust boundary in
+ * server.ts). When present, it is the sole candidate and the rest of the
+ * precedence chain is bypassed.
+ *
+ * [LAW:single-enforcer] One enumerator; `resolveDslConfigPath` finds the
+ * first that exists, watchers listen on all of them, no second list.
+ *
+ * [LAW:dataflow-not-control-flow] Location is the dominant precedence axis;
+ * extension breaks ties within a location. Encoded as a nested flat-map: each
+ * location yields one path per extension in order. No branches on extension.
+ */
+export function dslConfigCandidatePaths(
+  projectDir?: string,
+  cwd?: string,
+  configFile?: string,
+): readonly string[] {
+  // CLI --config wins over everything — highest precedence. Pre-expanded at
+  // the trust boundary; trust the type here.
+  if (configFile) {
+    return [configFile];
+  }
+
+  const envPath = process.env.CC_CANDYBAR_CONFIG;
+  if (envPath) {
+    // [LAW:single-enforcer] env-var is a separate trust boundary; expand here
+    // where the env is read, with the shared `expandHome` helper. [LAW:
+    // dataflow-not-control-flow] When the env var sets the path, it's the
+    // *only* candidate — the precedence chain collapses to one entry.
+    return [expandHome(envPath)];
+  }
+
+  const effectiveCwd = cwd ?? process.cwd();
+  const xdgConfigHome =
+    process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config");
+
+  return [
+    ...(projectDir
+      ? CONFIG_EXTENSIONS.map((ext) =>
+          path.join(projectDir, `.cc-candybar.${ext}`),
+        )
+      : []),
+    ...CONFIG_EXTENSIONS.map((ext) =>
+      path.join(effectiveCwd, `.cc-candybar.${ext}`),
+    ),
+    ...CONFIG_EXTENSIONS.map((ext) =>
+      path.join(xdgConfigHome, "cc-candybar", `config.${ext}`),
+    ),
+  ];
+}
+
+/**
+ * Resolution order for the user's DSL config file:
+ *   1. `configFile` (the CLI `--config <path>` value, already `~`-expanded)
+ *   2. $CC_CANDYBAR_CONFIG env var (literal path, `~`-expanded here)
+ *   3. `<projectDir>/.cc-candybar.json5`
+ *   4. `<projectDir>/.cc-candybar.json`
+ *   5. `<cwd>/.cc-candybar.json5`
+ *   6. `<cwd>/.cc-candybar.json`
+ *   7. `$XDG_CONFIG_HOME/cc-candybar/config.json5`
+ *      (defaulting to `~/.config/cc-candybar/config.json5`)
+ *   8. `$XDG_CONFIG_HOME/cc-candybar/config.json`
+ *
+ * Returns the first path that exists, or null if none do.
+ *
+ * [LAW:dataflow-not-control-flow] The locations array is data; the search is
+ * `locations.find(fs.existsSync)`. Adding a layer is a new array entry, not a
+ * new branch. Extension support is a property of the candidate list, not the
+ * search.
+ *
+ * [LAW:single-enforcer] Built on top of `dslConfigCandidatePaths` — the
+ * precedence list lives in one place.
+ */
+export function resolveDslConfigPath(
+  projectDir?: string,
+  cwd?: string,
+  configFile?: string,
+): string | null {
+  return (
+    dslConfigCandidatePaths(projectDir, cwd, configFile).find(fs.existsSync) ??
+    null
+  );
+}
+
+/**
+ * Detect same-location extension collisions: any location where BOTH
+ * `<base>.json5` and `<base>.json` exist simultaneously. The resolver picks
+ * .json5 (documented format wins), but the user almost certainly didn't
+ * intend to keep two; the duplicate is dead weight that will drift.
+ *
+ * Returns a human-readable warning naming the conflicting files, or null if
+ * no collisions exist. The render path surfaces this through the daemon's
+ * diagnostics channel so the user sees it on every render until they remove
+ * the duplicate.
+ *
+ * [LAW:single-enforcer] Consumes `dslConfigCandidatePaths` — same enumerator
+ * as the resolver and watcher; collision detection cannot disagree with
+ * resolution about which files are candidates.
+ *
+ * [LAW:dataflow-not-control-flow] Walk candidates, group by parent directory
+ * + base name (without extension), find groups with size > 1 whose members
+ * all exist. No special-case branches per extension.
+ */
+export function detectConfigCollisions(
+  projectDir?: string,
+  cwd?: string,
+): string | null {
+  const candidates = dslConfigCandidatePaths(projectDir, cwd);
+  // [LAW:dataflow-not-control-flow] Dedupe candidates by full path first.
+  // When projectDir === cwd (a very common case — the daemon often resolves
+  // both from the same hook payload), the enumerator yields the same path
+  // at both precedence levels. That is a structural duplicate of *position
+  // in the precedence list*, not a same-location duplicate of *files on
+  // disk*. The latter is what collision detection is for; the former is
+  // noise that would fire a false positive.
+  const seen = new Set<string>();
+  const uniqueExisting: string[] = [];
+  for (const candidate of candidates) {
+    if (seen.has(candidate)) continue;
+    seen.add(candidate);
+    if (!fs.existsSync(candidate)) continue;
+    uniqueExisting.push(candidate);
+  }
+  // Group by (dir + base-without-extension). A group with > 1 existing
+  // member is a collision at that logical location.
+  const groups = new Map<string, string[]>();
+  for (const candidate of uniqueExisting) {
+    const dir = path.dirname(candidate);
+    const base = path.basename(candidate).replace(/\.(json5|json)$/, "");
+    const key = path.join(dir, base);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key)!.push(candidate);
+  }
+  const collisions = [...groups.values()].filter((g) => g.length > 1);
+  if (collisions.length === 0) return null;
+  // Stable, parseable message. The first file in each group is the .json5
+  // (the one that wins); the rest are the shadowed siblings.
+  const lines = collisions.map((g) => {
+    const [winner, ...shadowed] = g;
+    return `${winner} shadows ${shadowed.join(", ")}`;
+  });
+  return `config-extension collision: ${lines.join("; ")} — remove the duplicate`;
+}

package/src/config/loader/emit-schema.ts

@@ -0,0 +1,63 @@
+// [LAW:one-source-of-truth] The JSON Schema emitter — the SECOND interpreter over
+// the declarative loader schemas. `validateConfig` composes the per-module
+// `validate*` functions to validate at runtime; `emitConfigSchema` composes the
+// per-module `*Json` functions to derive the editor-facing JSON Schema. Both read
+// the SAME module-private schema declarations (GLOBALS_SCHEMA, VARIABLE_SCHEMA,
+// SEGMENT_SCHEMA, CACHE_SCHEMA, SET_ARMS, the A-grammar layout grammar), so the
+// published schema and the runtime validator can never describe a different grammar.
+//
+// What a JSON Schema still cannot express (by construction): cross-field
+// refinements (min<max, by≠0, input default matches type), palette-name
+// membership, duration FORMAT, and cross-references between segments/variables/
+// cycles. Those stay SEMANTIC checks the loader carries — schema = shape, lint =
+// meaning, the same complementary boundary `config-schema.test.ts` pins.
+
+import { globalsJson } from "./globals.js";
+import { variablesMapJson } from "./variables.js";
+import { segmentsJson } from "./segments.js";
+import { actionsJson } from "./actions.js";
+import {
+  layoutNodeJson,
+  LAYOUT_NODE_DEF_NAME,
+  LAYOUT_NODE_REF,
+} from "./layout.js";
+import type { JsonNode } from "./validate-core.js";
+
+// [LAW:one-source-of-truth] The stable published identity. The committed artifact
+// is self-identifying at this URL so an editor loading it via `$schema` resolves.
+export const SCHEMA_ID =
+  "https://raw.githubusercontent.com/promptctl/cc-candybar/main/schema/cc-candybar.schema.json";
+
+// [LAW:dataflow-not-control-flow] The RawDslConfig schema: every top-level key is
+// optional (a user file declares only what differs from the bundled default), so
+// the object carries no `required`. Each property is one module's emitted shape —
+// the same composition `validateConfig` performs over the validators. `root`
+// references the LayoutNode definition that closes the node recursion via `$ref`.
+export function emitConfigSchema(): JsonNode {
+  return {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    $id: SCHEMA_ID,
+    title: "cc-candybar config (.cc-candybar.json5)",
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      globals: globalsJson(),
+      variables: variablesMapJson(),
+      segments: segmentsJson(),
+      root: { $ref: LAYOUT_NODE_REF },
+      actions: actionsJson(),
+      helpers: { type: "object", additionalProperties: { type: "string" } },
+    },
+    definitions: {
+      [LAYOUT_NODE_DEF_NAME]: layoutNodeJson(),
+    },
+  };
+}
+
+// [LAW:single-enforcer] One serialization, shared by `gen:schema` (writes the
+// committed artifact) and `check:schema` (byte-diffs against it) so the two can
+// never disagree on how the schema is produced. Trailing newline + 2-space indent
+// match the committed file's format.
+export function serializeConfigSchema(): string {
+  return JSON.stringify(emitConfigSchema(), null, 2) + "\n";
+}

package/src/config/loader/globals.ts

@@ -0,0 +1,42 @@
+// [LAW:types-are-the-program] The globals schema: a fixed set of string fields
+// plus a validated palette name, declared as DATA and interpreted by the record
+// engine. This file changes when a global default field is added or removed —
+// add a key to GLOBALS_SCHEMA and Globals; the engine does the rest.
+
+import { type Globals } from "../dsl-types.js";
+import {
+  optionalStringSpec,
+  paletteSpec,
+  record,
+  recordJson,
+  type JsonNode,
+  type RecordSchema,
+  type ValidateCtx,
+} from "./validate-core.js";
+
+const GLOBALS_SCHEMA: RecordSchema<Globals> = {
+  noun: "globals key",
+  fields: {
+    default_bg: optionalStringSpec(),
+    default_fg: optionalStringSpec(),
+    default_empty_value: optionalStringSpec(),
+    default_separator: optionalStringSpec(),
+    default_truncate_marker: optionalStringSpec(),
+    palette: paletteSpec(),
+  },
+};
+
+// An absent globals block is the empty default (no issue); a non-object is a
+// reported error that recovers to the empty default, since parseDslConfig throws
+// once any issue exists so the recovery value never renders [LAW:no-silent-failure].
+export function validateGlobals(ctx: ValidateCtx, raw: unknown): Globals {
+  if (raw === undefined) return {};
+  return record(ctx, GLOBALS_SCHEMA, "globals", raw) ?? {};
+}
+
+// [LAW:one-source-of-truth] The schema emitter derives from the SAME declaration
+// the validator interprets — `globals` emit is `recordJson(GLOBALS_SCHEMA)`,
+// symmetric to `validateGlobals` calling `record(GLOBALS_SCHEMA)`.
+export function globalsJson(): JsonNode {
+  return recordJson(GLOBALS_SCHEMA);
+}

package/src/config/loader/helpers.ts

@@ -0,0 +1,48 @@
+// [LAW:types-are-the-program] The helpers schema is the simplest possible: a
+// record of name → template-body STRING. Each value is a Go-template source the
+// renderer compiles into a `{{ define }}` block; whether the body PARSES (and
+// whether a `{{ template "name" }}` reference resolves) is a render-time concern
+// (registerDslConfig parses the preamble and throws a per-helper diagnostic).
+// This file changes only if the helper authoring shape changes.
+
+import { findKeyLine } from "./diagnostics.js";
+import {
+  describeType,
+  describeValue,
+  isPlainObject,
+  type ValidateCtx,
+} from "./validate-core.js";
+
+// [LAW:single-enforcer] Structural validation of the `helpers` block: an object
+// whose every value is a string template body. Null-prototype record so a helper
+// named "__proto__"/"constructor" is an ordinary own property, matching actions.
+export function validateHelpers(
+  ctx: ValidateCtx,
+  raw: unknown,
+): Record<string, string> {
+  if (raw === undefined) return {};
+  if (!isPlainObject(raw)) {
+    ctx.issues.push({
+      path: "helpers",
+      message: `helpers must be an object, got ${describeType(raw)}`,
+      line: findKeyLine(ctx.source, ["helpers"]),
+    });
+    return {};
+  }
+  const out: Record<string, string> = Object.create(null) as Record<
+    string,
+    string
+  >;
+  for (const [name, body] of Object.entries(raw)) {
+    if (typeof body !== "string") {
+      ctx.issues.push({
+        path: `helpers.${name}`,
+        message: `helpers.${name} must be a string template body, got ${describeValue(body)}`,
+        line: findKeyLine(ctx.source, ["helpers", name]),
+      });
+      continue;
+    }
+    out[name] = body;
+  }
+  return out;
+}