@bompus/house-rules 0.0.0-stage → 0.13.0

package/config-view.mjs

@@ -0,0 +1,209 @@
+// Human output is grouped and aligned; JSON output bypasses this renderer.
+import { styleText } from "node:util";
+
+const clean = (value) => String(value ?? "").replace(/\p{Cc}/gu, " ");
+function display() {
+  const color =
+    process.stdout.isTTY && !Object.hasOwn(process.env, "NO_COLOR") && process.env.TERM !== "dumb";
+  const paint = (style, text) => (color ? styleText(style, text, { validateStream: false }) : text);
+  const width = Math.max(24, Math.min(process.stdout.columns ?? 100, 120));
+  const wrap = (text, size) => {
+    const words = clean(text).split(/\s+/);
+    const lines = [""];
+    for (let word of words) {
+      while (word.length > size) {
+        if (lines.at(-1)) lines.push("");
+        lines[lines.length - 1] = word.slice(0, size);
+        word = word.slice(size);
+        lines.push("");
+      }
+      if (lines.at(-1).length + word.length + 1 > size) lines.push("");
+      lines[lines.length - 1] += (lines.at(-1) ? " " : "") + word;
+    }
+    return lines;
+  };
+  const table = (headers, rows) => {
+    const first = Math.max(headers[0].length, ...rows.map((row) => clean(row[0]).length));
+    const second = Math.max(headers[1].length, ...rows.map((row) => clean(row[1]).length));
+    if (first + second + 14 > width) {
+      return rows
+        .flatMap((row) => [
+          ...wrap(`${row[0]}  [${row[1]}]`, width - 2).map((l) => `  ${paint("bold", l)}`),
+          ...wrap(row[2], width - 4).map((l) => `    ${l}`),
+          "",
+        ])
+        .join("\n");
+    }
+    const third = width - first - second - 8;
+    const line = (a, b, c) => {
+      const state = b.padEnd(second);
+      return `  ${a.padEnd(first)}  ${paint(b === "on" ? "green" : b === "off" ? "dim" : "cyan", state)}  ${c}`;
+    };
+    const heading = paint("dim", line(...headers));
+    return [
+      heading,
+      ...rows.flatMap(([a, b, c]) =>
+        wrap(c, third).map((text, index) =>
+          line(index ? "" : clean(a), index ? "" : clean(b), text),
+        ),
+      ),
+    ].join("\n");
+  };
+  return { paint, table, wrap, width };
+}
+
+export function renderHelp() {
+  const { paint, table } = display();
+  return [
+    "",
+    `  ${paint("dim", "╭─")} ${paint("cyan", paint("bold", "HOUSE RULES"))}  ${paint("dim", "configuration")}`,
+    "",
+    "  node compose.mjs config <command> [options]",
+    "",
+    table(
+      ["Command", "Writes", "Purpose"],
+      [
+        ["catalog", "no", "Browse modifiers, skills and rule sections."],
+        ["status", "no", "See selections, personal origins and current revision."],
+        ["validate", "no", "Check configuration and compose every selected layer."],
+        ["preview", "no", "Review proposed selections; --rules prints composed rules."],
+        ["set", "opt-in", "Preview changes, then save with --apply --expect <revision>."],
+      ],
+    ),
+    "",
+    "  Selection",
+    "    --enable-modifier <name>    --disable-modifier <name>",
+    "    --enable-skill <name>       --disable-skill <name>",
+    "    --questions default|plain|coded|cards",
+    "    --panel-file <json>        Replace portable panel preferences (preview/set)",
+    "    --expect-panel <revision>  Require reviewed panel input when applying",
+    "",
+    "  Output",
+    "    --config <path>   --json   --rules (preview only)",
+    "",
+    "  Repeat toggle flags to change several selections together.",
+    "  Saving config does not regenerate output or connect agent hosts.",
+    "  Panel preferences do not discover providers, enable a skill or run models.",
+    "",
+  ].join("\n");
+}
+
+export function renderConfig(report) {
+  const { paint, table, wrap, width } = display();
+  const lines = [
+    "",
+    `  ${paint("dim", "╭─")} ${paint("cyan", paint("bold", "HOUSE RULES"))}  ${paint("dim", report.command)}`,
+    "",
+  ];
+  const section = (label) => lines.push(`  ${paint("bold", label)}`, "");
+  const detail = (text) => lines.push(...wrap(text, width - 2).map((l) => `  ${l}`));
+  detail(`Config  ${report.configPath}${report.exists ? "" : " (not created)"}`);
+  detail(`Revision  ${report.applied?.revision ?? report.revision}`);
+  lines.push("");
+  const enabled = report.modifiers.filter((m) => m.enabled).length;
+  detail(
+    `${enabled}/${report.modifiers.length} modifiers enabled   ${report.skills.filter((s) => s.enabled).length}/${report.skills.length} skills selected   ${report.rules.length} rule sections`,
+  );
+  detail(`Configured questions  ${report.questions}   Host loading  ${report.hostLoading}`);
+  lines.push("");
+  if (["set", "preview"].includes(report.command)) {
+    section(
+      report.applied
+        ? report.applied.changed
+          ? "Configuration saved"
+          : "Already configured"
+        : "Change preview",
+    );
+    if (!report.changes.length) detail("No selection changes.");
+    for (const change of report.changes) {
+      detail(change.key);
+      const removed = change.before.filter((name) => !change.after.includes(name));
+      const added = change.after.filter((name) => !change.before.includes(name));
+      for (const [sign, names, style] of [
+        ["-", removed, "red"],
+        ["+", added, "green"],
+      ]) {
+        for (const name of names) lines.push(`    ${paint(style, `${sign} ${clean(name)}`)}`);
+      }
+      if (!removed.length && !added.length) detail("Selection order changed.");
+    }
+    if (report.panel) {
+      section(report.panel.changed ? "Panel section replacement" : "Panel section unchanged");
+      detail(`Panel input revision  ${report.panel.revision}`);
+      detail("Before");
+      for (const line of JSON.stringify(report.panel.before, null, 2).split("\n")) detail(line);
+      detail("After");
+      for (const line of JSON.stringify(report.panel.after, null, 2).split("\n")) detail(line);
+      detail(
+        `Preferences ${report.applied ? "configured" : "proposed"} only. Route access, effort and permissions are unverified.`,
+      );
+    }
+    lines.push("");
+    if (!report.applied) {
+      const panelGuard = report.panel ? ` --expect-panel ${report.panel.revision}` : "";
+      detail(
+        report.command === "set"
+          ? `To save, repeat with --apply --expect ${report.revision}${panelGuard}`
+          : `To save, run config set with the same selection flags plus --apply --expect ${report.revision}${panelGuard}`,
+      );
+      detail("Review personal rule overrides below before choosing a question format.");
+    } else
+      detail(
+        "Next, recompose output with compose.mjs or rerun the installer. Existing skills directories are retained; host connection is separate.",
+      );
+    lines.push("");
+  }
+  if (report.command === "validate") detail("Configuration and composition are valid.");
+  else if (["status", "catalog"].includes(report.command)) {
+    section("Modifiers");
+    lines.push(
+      table(
+        ["Name", "State", "Purpose"],
+        report.modifiers.map((m) => [m.name, m.enabled ? "on" : "off", m.description]),
+      ),
+      "",
+    );
+    section("Skills");
+    lines.push(
+      table(
+        ["Name", "State", report.command === "catalog" ? "Purpose" : "Origin"],
+        report.skills.map((s) => [
+          s.name,
+          s.enabled ? "on" : "off",
+          report.command === "catalog" ? s.description : s.origin,
+        ]),
+      ),
+      "",
+    );
+    section("Effective rules");
+    lines.push(
+      table(
+        ["Section", "State", "Source"],
+        report.rules.map((r) => [r.heading, "active", r.origin]),
+      ),
+      "",
+    );
+    section("Personal layers");
+    for (const layer of report.layers) detail(layer);
+  }
+  const personal = report.rules.filter(
+    (rule) => rule.source !== "core" && !rule.source.startsWith("modifier "),
+  );
+  if (["preview", "set"].includes(report.command) && personal.length) {
+    section("Personal rule overrides and additions");
+    lines.push(
+      table(
+        ["Section", "State", "Source"],
+        personal.map((r) => [r.heading, "active", r.origin]),
+      ),
+      "",
+    );
+  }
+  for (const name of report.unavailable)
+    detail(`Retained exclusion with no current source: ${name}`);
+  for (const warning of report.warnings) detail(`Warning: ${warning}`);
+  lines.push("");
+  detail("Status describes composed selections. It does not verify an agent's loaded context.");
+  lines.push(`  ${paint("dim", "╰─")}`);
+  return lines.join("\n");
+}

package/config.mjs

@@ -0,0 +1,381 @@
+// Selection management for compose.mjs config. JSON is the only settings store.
+import { createHash, randomUUID } from "node:crypto";
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+const SHIPPED_SKILLS = join(dirname(fileURLToPath(import.meta.url)), "skills");
+import {
+  composeConfiguration,
+  configurationPath,
+  modifierList,
+  parseFragment,
+  skillSources,
+  splitSections,
+} from "./composition.mjs";
+import { renderConfig, renderHelp } from "./config-view.mjs";
+import { changePanelPreferences } from "./skills/hr-code-review/scripts/panel-preferences.mjs";
+
+const COMMANDS = ["catalog", "status", "validate", "preview", "set"];
+const TOGGLES = ["enable-modifier", "disable-modifier", "enable-skill", "disable-skill"];
+const revisionOf = (text) =>
+  text === null ? "missing" : createHash("sha256").update(text).digest("hex");
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+function stringList(value, key) {
+  if (value === undefined) return;
+  if (!Array.isArray(value) || value.some((v) => typeof v !== "string" || !v.trim()))
+    throw new Error(`${key} must be an array of non-empty strings`);
+  if (new Set(value).size !== value.length) throw new Error(`${key} contains duplicates`);
+}
+
+export const QUESTION_PRESETS = ["default", "plain", "coded", "cards"];
+export const QUESTION_MODIFIERS = ["model-default-questions", "coded-offers", "question-cards"];
+const BACKLOG_VIEWS = ["backlog-visual", "backlog-outline"];
+
+function validateStructure(config) {
+  if (!object(config)) throw new Error("configuration must be a JSON object");
+  for (const key of ["modifiers", "layers"]) stringList(config[key], key);
+  if (config.skills !== undefined && !object(config.skills))
+    throw new Error("skills must be an object");
+  for (const key of ["include", "exclude", "independent"])
+    stringList(config.skills?.[key], `skills.${key}`);
+}
+
+function validateSelection(config) {
+  validateStructure(config);
+  const known = new Set(modifierList().map((m) => m.name));
+  for (const name of config.modifiers ?? []) {
+    if (!known.has(name))
+      throw new Error(
+        `unknown modifier "${name}" (see config catalog); preview its removal with config set --disable-modifier <name>, then save it with config set --disable-modifier <name> --apply --expect <revision>`,
+      );
+  }
+  if (BACKLOG_VIEWS.every((name) => config.modifiers?.includes(name)))
+    throw new Error(
+      `${BACKLOG_VIEWS.join(" and ")} cannot be combined; enable one, or neither for the table alone`,
+    );
+  if (config.modifiers?.includes("question-cards") && !config.modifiers.includes("coded-offers"))
+    throw new Error(
+      "question-cards requires coded-offers; use --questions cards or disable question-cards",
+    );
+  if (
+    config.modifiers?.includes("model-default-questions") &&
+    config.modifiers.some((name) => ["coded-offers", "question-cards"].includes(name))
+  )
+    throw new Error(
+      "model-default-questions cannot combine with coded-offers or question-cards; use --questions",
+    );
+}
+
+export function readConfiguration(path) {
+  // Preserve the caller's config directory: relative layers use the same base as composition.
+  path = resolve(path);
+  let text = null;
+  try {
+    if (!lstatSync(path).isFile())
+      throw new Error("config must be a regular file, not a symlink or directory");
+    text = readFileSync(path, "utf8");
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  let config = {};
+  try {
+    if (text !== null) config = JSON.parse(text.replace(/^\uFEFF/, ""));
+  } catch {
+    throw new Error(`invalid JSON in ${path}`);
+  }
+  validateStructure(config);
+  return { path, text, revision: revisionOf(text), config };
+}
+
+export function selectionReport(config, path) {
+  validateSelection(config);
+  const result = composeConfiguration(config, dirname(path));
+  const allSkills = skillSources(
+    { ...config, skills: { ...config.skills, include: undefined, exclude: [] } },
+    dirname(path),
+  );
+  const selected = new Set(config.modifiers ?? []);
+  const modifiers = modifierList().map((m) => ({ ...m, enabled: selected.has(m.name) }));
+  const skills = [...allSkills].map(([name, source]) => ({
+    name,
+    source,
+    origin: source === join(SHIPPED_SKILLS, name) ? "shipped" : relative(dirname(path), source),
+    enabled: result.skills.has(name),
+    explicitOnly:
+      parseFragment(readFileSync(join(source, "SKILL.md"), "utf8"), source).meta[
+        "disable-model-invocation"
+      ] === "true",
+    description:
+      parseFragment(readFileSync(join(source, "SKILL.md"), "utf8"), source).meta.description ?? "",
+  }));
+  const unavailable = (config.skills?.exclude ?? []).filter((name) => !allSkills.has(name));
+  const rules = splitSections(result.rules).sections.map((s) => ({
+    heading: s.heading,
+    source: "core",
+  }));
+  const origins = new Map();
+  for (const f of result.fragments) {
+    for (const section of splitSections(f.body).sections) origins.set(section.heading, f.source);
+  }
+  for (const rule of rules) {
+    rule.source = origins.get(rule.heading) ?? "core";
+    rule.origin =
+      rule.source === "core" || rule.source.startsWith("modifier ")
+        ? rule.source
+        : relative(dirname(path), rule.source);
+  }
+  return {
+    modifiers,
+    skills,
+    rules,
+    unavailable,
+    layers: (config.layers ?? ["."]).map((layer) => resolve(dirname(path), layer)),
+    fragments: result.fragments.map((f) => ({ source: f.source, ...f.meta })),
+    questions: selected.has("model-default-questions")
+      ? "default"
+      : selected.has("question-cards")
+        ? "cards"
+        : selected.has("coded-offers")
+          ? "coded"
+          : "plain",
+    warnings: result.warnings,
+    composedRules: result.rules,
+    hostLoading: "unverified",
+  };
+}
+
+export function changeSelection(config, options, path) {
+  const next = structuredClone(config);
+  const modifiers = new Set(next.modifiers ?? []);
+  const excluded = new Set(next.skills?.exclude ?? []);
+  const included = next.skills?.include === undefined ? null : new Set(next.skills.include);
+  const knownModifiers = new Set(modifierList().map((m) => m.name));
+  // Use discovery even for excluded skills; preserve unrelated existing exclusions.
+  const knownSkills = new Set(
+    skillSources(
+      { ...next, skills: { ...next.skills, include: undefined, exclude: [] } },
+      dirname(path),
+    ).keys(),
+  );
+  for (const [kind, known, choices] of [
+    ["modifier", knownModifiers, modifiers],
+    ["skill", knownSkills, excluded],
+  ]) {
+    const enable = options[`enable-${kind}`] ?? [];
+    const disable = options[`disable-${kind}`] ?? [];
+    for (const name of [...enable, ...disable]) {
+      if (!known.has(name) && !(kind === "modifier" && disable.includes(name) && choices.has(name)))
+        throw new Error(`unknown ${kind} "${name}" (see config catalog)`);
+      if (enable.includes(name) && disable.includes(name))
+        throw new Error(`cannot enable and disable "${name}" together`);
+      if (
+        kind === "modifier" &&
+        options.questions !== undefined &&
+        QUESTION_MODIFIERS.includes(name)
+      )
+        throw new Error("use --questions or explicit question modifiers, not both");
+    }
+    for (const name of enable) {
+      if (kind === "modifier") choices.add(name);
+      else {
+        choices.delete(name);
+        if (included && existsSync(join(SHIPPED_SKILLS, name, "SKILL.md"))) included.add(name);
+      }
+    }
+    for (const name of disable) {
+      if (kind === "modifier") choices.delete(name);
+      else choices.add(name);
+    }
+  }
+  if (options.questions !== undefined) {
+    if (!QUESTION_PRESETS.includes(options.questions))
+      throw new Error("--questions must be default, plain, coded or cards");
+    if (options.questions === "plain" || options.questions === "default")
+      modifiers.delete("coded-offers");
+    else modifiers.add("coded-offers");
+    if (options.questions === "cards") modifiers.add("question-cards");
+    else modifiers.delete("question-cards");
+    if (options.questions === "default") modifiers.add("model-default-questions");
+    else modifiers.delete("model-default-questions");
+  }
+  if (JSON.stringify([...modifiers]) !== JSON.stringify(next.modifiers ?? []))
+    next.modifiers = [...modifiers];
+  if (JSON.stringify([...excluded]) !== JSON.stringify(next.skills?.exclude ?? []))
+    next.skills = { ...next.skills, exclude: [...excluded] };
+  if (included) next.skills.include = [...included];
+  selectionReport(next, path); // Composition and legacy-name errors precede every write.
+  return next;
+}
+
+// Cooperating CLI writers share an exclusive lock; expected revision guards stale previews.
+// Manual editors do not share this lock. Recheck before rename, but they can still race that rename.
+export function writeConfiguration(snapshot, next, expected) {
+  if (!expected) throw new Error("--apply requires --expect <revision> from status or a preview");
+  selectionReport(next, snapshot.path);
+  mkdirSync(dirname(snapshot.path), { recursive: true });
+  // Lock aliases of the same parent together without changing relative layer discovery.
+  const lock = `${join(realpathSync(dirname(snapshot.path)), basename(snapshot.path))}.lock`;
+  let lockFd;
+  try {
+    lockFd = openSync(lock, "wx", 0o600);
+  } catch (e) {
+    if (e.code === "EEXIST")
+      throw new Error(
+        `configuration is locked: ${lock}; inspect the owner before removing an abandoned lock`,
+      );
+    throw e;
+  }
+  const temporary = `${snapshot.path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(lockFd, JSON.stringify({ pid: process.pid }));
+    const current = readConfiguration(snapshot.path);
+    if (current.revision !== expected || current.revision !== snapshot.revision)
+      throw new Error("configuration changed since preview; read status and preview again");
+    if (current.text !== null && JSON.stringify(current.config) === JSON.stringify(next))
+      return { changed: false, revision: current.revision };
+    const text = `${JSON.stringify(next, null, 2)}\n`;
+    const fd = openSync(
+      temporary,
+      "wx",
+      current.text === null ? 0o600 : statSync(current.path).mode & 0o777,
+    );
+    try {
+      writeFileSync(fd, text);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    if (readConfiguration(snapshot.path).revision !== current.revision)
+      throw new Error("configuration changed during validation; preview again");
+    renameSync(temporary, snapshot.path);
+    return { changed: true, revision: revisionOf(text) };
+  } finally {
+    try {
+      if (existsSync(temporary)) unlinkSync(temporary);
+    } finally {
+      try {
+        closeSync(lockFd);
+      } finally {
+        unlinkSync(lock);
+      }
+    }
+  }
+}
+
+export function selectionChanges(beforeConfig, afterConfig) {
+  return [
+    { key: "modifiers", before: beforeConfig.modifiers ?? [], after: afterConfig.modifiers ?? [] },
+    {
+      key: "skills.include",
+      before: beforeConfig.skills?.include ?? [],
+      after: afterConfig.skills?.include ?? [],
+    },
+    {
+      key: "skills.exclude",
+      before: beforeConfig.skills?.exclude ?? [],
+      after: afterConfig.skills?.exclude ?? [],
+    },
+  ].filter(({ before, after }) => JSON.stringify(before) !== JSON.stringify(after));
+}
+
+export function configCommand(argv) {
+  const command = argv[0] ?? "help";
+  if (command === "help" || command === "--help") return console.log(renderHelp());
+  if (!COMMANDS.includes(command))
+    throw new Error(`unknown config command "${command}" (see config help)`);
+  const { values } = parseArgs({
+    args: argv.slice(1),
+    options: {
+      config: { type: "string" },
+      help: { type: "boolean" },
+      json: { type: "boolean" },
+      rules: { type: "boolean" },
+      questions: { type: "string" },
+      apply: { type: "boolean" },
+      expect: { type: "string" },
+      "panel-file": { type: "string" },
+      "expect-panel": { type: "string" },
+      ...Object.fromEntries(TOGGLES.map((key) => [key, { type: "string", multiple: true }])),
+    },
+  });
+  if (values.help) return console.log(renderHelp());
+  const changing = Boolean(
+    values.questions !== undefined ||
+    values["panel-file"] !== undefined ||
+    TOGGLES.some((key) => values[key]?.length),
+  );
+  if (
+    (changing || values.apply || values.expect !== undefined) &&
+    !["set", "preview"].includes(command)
+  )
+    throw new Error("selection flags belong to config set or preview");
+  if (values.apply && command !== "set") throw new Error("--apply belongs to config set");
+  if (values.expect !== undefined && !values.apply) throw new Error("--expect requires --apply");
+  if (values["expect-panel"] !== undefined && (!values.apply || values["panel-file"] === undefined))
+    throw new Error("--expect-panel requires --apply and --panel-file");
+  if (values.rules && values.json) throw new Error("choose --rules or --json, not both");
+  if (values.rules && command !== "preview") throw new Error("--rules belongs to config preview");
+  if (values.rules && values["panel-file"] !== undefined)
+    throw new Error("--panel-file requires a change report; omit --rules");
+  const snapshot = readConfiguration(configurationPath(values.config));
+  let next = changing ? changeSelection(snapshot.config, values, snapshot.path) : snapshot.config;
+  let panelRevision;
+  if (values["panel-file"] !== undefined) {
+    const path = resolve(values["panel-file"]);
+    if (!lstatSync(path).isFile())
+      throw new Error("panel input must be a regular file, not a symlink or directory");
+    const text = readFileSync(path, "utf8");
+    panelRevision = revisionOf(text);
+    if (values.apply && values["expect-panel"] !== panelRevision)
+      throw new Error("panel input changed or --expect-panel missing; preview again");
+    let preferences;
+    try {
+      preferences = JSON.parse(text.replace(/^\uFEFF/, ""));
+    } catch {
+      throw new Error("invalid JSON in panel input");
+    }
+    next = changePanelPreferences(next, preferences);
+  }
+  const report = selectionReport(next, snapshot.path);
+  const changes = selectionChanges(snapshot.config, next);
+  const applied = values.apply ? writeConfiguration(snapshot, next, values.expect) : null;
+  const output = {
+    command,
+    configPath: snapshot.path,
+    exists: values.apply || snapshot.text !== null,
+    revision: applied?.revision ?? snapshot.revision,
+    changes,
+    applied,
+    ...(values["panel-file"] === undefined
+      ? {}
+      : {
+          panel: {
+            state: values.apply ? "configured" : "proposed",
+            revision: panelRevision,
+            before: snapshot.config.panel ?? null,
+            after: next.panel,
+            changed: JSON.stringify(snapshot.config.panel) !== JSON.stringify(next.panel),
+            readiness: "unverified",
+          },
+        }),
+    ...report,
+  };
+  if (values.rules) return process.stdout.write(report.composedRules);
+  if (values.json) console.log(JSON.stringify(output, null, 2));
+  else console.log(renderConfig(output));
+}