heyspex 0.1.0 → 0.2.1

package/scripts/hs-settings.mjs

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+/**
+ * hs settings — CLI face of the HeySpex settings capability.
+ * Dispatched from bin/hs.mjs. Delegates to the ONE settings core
+ * (vendor/heyspex-mcp/config-settings.mjs) per the three-faces principle
+ * ([[capability-three-faces-no-per-capability-slash]]).
+ *
+ * Usage:
+ *   hs settings list [prefix] [--json]
+ *   hs settings get <dotted.key> [--json]
+ *   hs settings set <dotted.key> <value> [--json] [--confirmed-by-user]
+ *
+ * WRITE-PERMISSION GUARDRAIL (agent-settings-protocol, owner directive
+ * 2026-07-11): settings writes require explicit user permission. A human typing
+ * `hs settings set` in their own terminal IS the permission. But when this CLI
+ * runs inside an agent harness (Claude Code sets CLAUDECODE=1 / CLAUDE_AGENT for
+ * its shell tool), the write is agent-initiated: it is refused unless
+ * `--confirmed-by-user` is passed, and that flag may ONLY be passed after the
+ * user explicitly approved the exact change in the conversation. This holds
+ * regardless of agent_behaviors.ask_forgiveness_not_permission — that switch
+ * governs behaviors, never its own controls. All writes are audited to
+ * .heyspex/settings-history.jsonl.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+
+import {
+  listConfigLeaves,
+  getEffectiveSetting,
+  setConfigLeaf,
+  validateSettingKey,
+} from '../vendor/heyspex-mcp/config-settings.mjs';
+import {
+  SETTINGS_REGISTRY,
+  getSettingEntry,
+  isKnownSetting,
+} from '../vendor/heyspex-mcp/settings-registry.mjs';
+import { getActiveConfig } from '../vendor/heyspex-mcp/vault-resolve.mjs';
+
+const HELP = `hs settings — read/change HeySpex workflow settings (.heyspex/config.yaml at the VAULT root)
+
+Usage:
+  hs settings list [prefix] [--json]        List all scalar settings (optionally under a dotted prefix)
+  hs settings get <dotted.key> [--json]     Read one setting (e.g. agent_behaviors.capture_on_idea.enabled)
+  hs settings set <dotted.key> <value>      Change one setting (value: string | number | true | false | null)
+       [--confirmed-by-user] [--json]
+
+The settings file lives at <vault root>/.heyspex/config.yaml (ADR-0009). If it is
+missing, \`hs settings set\` creates it from the shipped seed template first and
+then applies the change (reads never create it) — \`hs init\` seeds the same file.
+
+Write permission (agent-settings-protocol):
+  A human running \`hs settings set\` directly is inherently permissioned. Inside an
+  agent harness (CLAUDECODE / CLAUDE_AGENT env present) the write is refused unless
+  --confirmed-by-user is passed — and an agent may pass it ONLY after the user
+  explicitly approved the exact change. Writes are audited to
+  .heyspex/settings-history.jsonl. Agents should prefer the MCP tool
+  heyspex_settings_set (two-step confirm).
+`;
+
+/**
+ * The vault root this face reads/writes. `bin/hs.mjs` always forwards
+ * `HS_VAULT_ROOT`; the last fallback (this script run directly) asks the shared
+ * vault resolver — NEVER this code checkout. Since the 2026-08-31 repo split the
+ * vault is a sibling repo, so falling back to `scripts/..` silently read/wrote a
+ * `.heyspex/config.yaml` the console and MCP never look at
+ * ([[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]).
+ */
+function vaultRoot() {
+  return process.env.HS_VAULT_ROOT || process.env.HEYSPEX_VAULT_ROOT || getActiveConfig().repoRootAbs;
+}
+
+function isAgentHarness() {
+  return Boolean(
+    process.env.CLAUDECODE ||
+      process.env.CLAUDE_AGENT ||
+      process.env.CLAUDE_CODE_SESSION_ID ||
+      process.env.CURSOR_AGENT,
+  );
+}
+
+/**
+ * True when `root` is the HeySpex platform vault rather than a
+ * customer-provisioned one. `hs init --customer-vault` unconditionally stamps
+ * `template_version: <…>` into the scaffolded vault's `heyspex.yaml`
+ * (`spex-console/src/lib/cli/init-git-finalize.ts` `gitFinalizeHook` /
+ * `ensureTemplateVersionLine`) — the platform vault's own marker never
+ * carries that field. That stamp is the one on-disk, offline-readable signal
+ * that distinguishes the two without a network/account lookup (the MCP/CLI
+ * process is standalone, per `vendor/heyspex-mcp/vault-resolve.mjs`'s module
+ * doc). A vault with no `heyspex.yaml` at all (e.g. this code checkout run
+ * directly, with no vault marker) is treated as platform — it is not a
+ * customer scaffold. Registry-declared admin-only entries (e.g.
+ * `close_out.run_command_drift_doctor`) are hidden from `hs settings list`
+ * everywhere `template_version` is present ([[HS-5MNS-15XI-TASK]] AC4).
+ */
+export function isHeyspexPlatformVault(root) {
+  let raw;
+  try {
+    raw = fs.readFileSync(path.join(root, 'heyspex.yaml'), 'utf8');
+  } catch {
+    return true; // no marker at all — not a customer scaffold
+  }
+  return !/^template_version:\s*\S+/m.test(raw);
+}
+
+/** How a value's `source` reads in a one-line human sentence. */
+function describeSource(source) {
+  if (source === 'file') return 'settings file';
+  if (source === 'registry_default') return 'shipped default';
+  return 'absent';
+}
+
+/**
+ * Build the `hs settings list` result: every registry entry this vault ships
+ * (admin-only entries dropped in a non-platform vault), each carrying its
+ * effective value/source plus its shipped default and description, followed
+ * by any keys the settings file has that the registry does not declare
+ * (marked `unrecognised: true`) — the freeform namespaces the registry has
+ * not been taught yet (`agent_behaviors.*`, `mvp_mode.*`, …) land here too,
+ * unchanged from their pre-registry values.
+ * ([[HS-5MNS-15XI-TASK-show-every-declared-setting-in-the]])
+ *
+ * @param {string} root
+ * @param {string} [prefix] - optional dotted-key prefix filter
+ * @returns {{ declared: object[], unrecognised: object[] }}
+ */
+export function buildListEntries(root, prefix, options = {}) {
+  const trimmedPrefix = (prefix ?? '').trim();
+  const matchesPrefix = (key) =>
+    !trimmedPrefix || key === trimmedPrefix || key.startsWith(trimmedPrefix + '.');
+  const platform = isHeyspexPlatformVault(root);
+
+  const declared = [];
+  for (const entry of SETTINGS_REGISTRY) {
+    if (entry.adminOnly && !platform) continue;
+    if (!matchesPrefix(entry.key)) continue;
+    const effective = getEffectiveSetting(root, entry.key, options);
+    declared.push({
+      key: entry.key,
+      value: effective.value,
+      source: effective.source,
+      default: entry.default,
+      type: entry.type,
+      description: entry.description,
+      cliFlag: entry.cliFlag,
+      adminOnly: entry.adminOnly,
+      enforced: entry.enforced,
+      ...(entry.type === 'enum' ? { values: entry.values } : {}),
+    });
+  }
+
+  const unrecognised = listConfigLeaves(root, options)
+    .filter((leaf) => !isKnownSetting(leaf.key))
+    .filter((leaf) => matchesPrefix(leaf.key))
+    .map((leaf) => ({ key: leaf.key, value: leaf.value, unrecognised: true }));
+
+  return { declared, unrecognised };
+}
+
+/**
+ * Build the `hs settings get <key>` result: the effective value (file value
+ * when present, else the registry's shipped default), which of the two it
+ * came from, and — for a name the registry does not declare AND that has no
+ * value in the file either — an explicit "not declared" report instead of a
+ * silent empty value. ([[HS-7W0S-15XI-TASK-return-the-effective-value-from-the]])
+ *
+ * @param {string} root
+ * @param {string} key
+ * @returns {object}
+ */
+export function resolveGet(root, key, options = {}) {
+  const effective = getEffectiveSetting(root, key, options);
+  if (effective.source === 'absent') {
+    return { ok: true, key, found: false, known: false, value: null, source: 'absent' };
+  }
+  const entry = getSettingEntry(key);
+  return {
+    ok: true,
+    key,
+    found: effective.found,
+    known: Boolean(entry),
+    value: effective.value,
+    source: effective.source,
+    ...(entry ? { default: entry.default, description: entry.description } : {}),
+  };
+}
+
+/** Render `resolveGet`'s result as the plain-text `hs settings get` body. */
+function renderGetText(result) {
+  if (result.source === 'absent') {
+    return `${result.key} is not set and is not declared in the settings registry (no shipped default to fall back to)\n`;
+  }
+  return `${result.key} = ${JSON.stringify(result.value)}  [${describeSource(result.source)}]\n`;
+}
+
+/** Render `buildListEntries`'s result as the plain-text `hs settings list` body. */
+function renderListText({ declared, unrecognised }) {
+  const lines = [];
+  for (const row of declared) {
+    lines.push(`${row.key} = ${JSON.stringify(row.value)}  [${describeSource(row.source)}]`);
+    lines.push(`  ${row.description}`);
+  }
+  if (unrecognised.length) {
+    if (declared.length) lines.push('');
+    lines.push('Unrecognised (not declared in the settings registry):');
+    for (const row of unrecognised) {
+      lines.push(`  ${row.key} = ${JSON.stringify(row.value)}`);
+    }
+  }
+  if (!declared.length && !unrecognised.length) return 'no settings found\n';
+  return lines.join('\n') + '\n';
+}
+
+function parseValueToken(token) {
+  if (token === undefined) return undefined;
+  if (token === 'null') return null;
+  if (token === 'true') return true;
+  if (token === 'false') return false;
+  if (/^-?\d+(\.\d+)?$/.test(token)) return Number(token);
+  return token;
+}
+
+function out(obj, asJson, plain) {
+  if (asJson) process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+  else process.stdout.write(plain);
+}
+
+function main(argv) {
+  // bin/hs.mjs forwards the full argv (leading `settings` token included).
+  const args = argv[0] === 'settings' ? argv.slice(1) : argv.slice();
+  if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+    process.stdout.write(HELP);
+    process.exit(args.length === 0 ? 2 : 0);
+  }
+  const asJson = args.includes('--json');
+  const confirmedByUser = args.includes('--confirmed-by-user');
+  const positional = args.filter((a) => !a.startsWith('--'));
+  const [verb, keyArg, ...valueTokens] = positional;
+  const root = vaultRoot();
+
+  if (verb === 'list') {
+    const prefix = keyArg?.trim() || '';
+    const { declared, unrecognised } = buildListEntries(root, prefix);
+    out(
+      { ok: true, count: declared.length + unrecognised.length, declared, unrecognised },
+      asJson,
+      renderListText({ declared, unrecognised }),
+    );
+    process.exit(0);
+  }
+
+  if (verb === 'get') {
+    const check = validateSettingKey(keyArg ?? '');
+    if (!check.ok) {
+      process.stderr.write(`hs settings get: ${check.reason}\n`);
+      process.exit(2);
+    }
+    const result = resolveGet(root, keyArg);
+    out(result, asJson, renderGetText(result));
+    process.exit(0);
+  }
+
+  if (verb === 'set') {
+    const check = validateSettingKey(keyArg ?? '');
+    if (!check.ok) {
+      process.stderr.write(`hs settings set: ${check.reason}\n`);
+      process.exit(2);
+    }
+    if (valueTokens.length === 0) {
+      process.stderr.write('hs settings set: missing <value> (string | number | true | false | null)\n');
+      process.exit(2);
+    }
+    const value = parseValueToken(valueTokens.join(' '));
+
+    if (isAgentHarness() && !confirmedByUser) {
+      const msg =
+        `hs settings set: REFUSED — this shell is running inside an agent harness, and settings writes ` +
+        `require explicit user permission (agent-settings-protocol; independent of ` +
+        `ask_forgiveness_not_permission). Show the user the exact change and, only after they approve, ` +
+        `re-run with --confirmed-by-user (or use the MCP tool heyspex_settings_set, which has a ` +
+        `built-in confirm step).\n`;
+      process.stderr.write(msg);
+      process.exit(3);
+    }
+
+    const actor = isAgentHarness() ? 'agent (CLI, user-confirmed)' : 'human (CLI)';
+    const result = setConfigLeaf(root, keyArg, value, { actor, face: 'cli' });
+    if (!result.ok) {
+      process.stderr.write(`hs settings set: ${result.error} — ${result.message}\n`);
+      process.exit(1);
+    }
+    // HS-4C76 fix 3: the core seeds a missing config.yaml from the template on
+    // the first write instead of refusing — say so, since the user may not have
+    // known the file was absent (it is git-tracked at the vault root).
+    if (result.seeded === true) {
+      process.stderr.write(
+        `hs settings set: note — ${path.join(root, '.heyspex', 'config.yaml')} did not exist and was created from ` +
+          `the seed template before applying this change. Commit it with the vault (ADR-0009).\n`,
+      );
+    }
+    // The CLI face shares the core with heyspex_settings_set, so it inherits the
+    // measured `audited` flag ([[HS-IOJW-5YDH-DIAG]] sweep). A settings write with
+    // no audit row is a partial, and must not print as a clean success.
+    if (result.audited !== true) {
+      process.stderr.write(
+        `hs settings set: WARNING — the value was applied to .heyspex/config.yaml but the audit append to ` +
+          `.heyspex/settings-history.jsonl FAILED. The change is live and UNAUDITED; check that file is writable.\n`,
+      );
+    }
+    out(
+      { ok: true, ...result },
+      asJson,
+      `${keyArg}: ${JSON.stringify(result.previous)} → ${JSON.stringify(result.value)}${result.created ? ' (created)' : ''}${result.seeded === true ? ' (config.yaml seeded from template)' : ''}${result.audited === true ? '' : ' (UNAUDITED — audit append failed)'}\n`,
+    );
+    process.exit(0);
+  }
+
+  process.stderr.write(`hs settings: unknown subcommand \`${verb ?? ''}\` (expected: list | get | set)\n${HELP}`);
+  process.exit(2);
+}
+
+// Only auto-run when executed directly (`node scripts/hs-settings.mjs …` or via
+// bin/hs.mjs's spawn) — not when a test imports this module for its exported
+// helpers (buildListEntries, isHeyspexPlatformVault, …).
+const isMain = (() => {
+  try {
+    return import.meta.url === pathToFileURL(process.argv[1] ?? '').href;
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  main(process.argv.slice(2));
+}