@event4u/agent-config 9.22.0 → 9.24.0

package/src/server/io/yamlIO.ts

@@ -0,0 +1,173 @@
+/**
+ * YAML round-trip helpers for `.agent-settings.yml`.
+ *
+ * Important contract: the template ships with comments that explain
+ * every key — we MUST NOT discard them when the wizard writes back.
+ * `js-yaml.dump` cannot preserve comments, so we use a key-level
+ * replace strategy that mirrors `scripts/install.py::_replace_template_value`:
+ * scan the rendered template line-by-line, replace only the scalar
+ * value at each dotted path, leave comments and indentation alone.
+ *
+ * For arrays and nested objects we fall back to re-serializing the
+ * subtree (`js-yaml.dump`) because line-level replace can't safely
+ * splice multi-line blocks. The form renderer keeps depth ≤ 2, so
+ * the subtree footprint is small.
+ */
+
+import { dump as yamlDump, load as yamlLoad } from 'js-yaml';
+
+export interface ReadResult {
+    values: Record<string, unknown>;
+    raw: string;
+}
+
+export function parseYaml(raw: string): Record<string, unknown> {
+    const parsed = yamlLoad(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('settings file did not parse to an object');
+    }
+    return parsed as Record<string, unknown>;
+}
+
+function formatScalar(value: unknown): string {
+    if (typeof value === 'string') {
+        // js-yaml safely quotes strings that need it; trim the trailing newline.
+        return yamlDump(value, { lineWidth: -1 }).replace(/\n$/, '').trim();
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+    if (value === null || value === undefined) return '""';
+    // Arrays / nested objects: dump inline. Form keeps depth ≤ 2 so this is rare.
+    return yamlDump(value, { lineWidth: -1, flowLevel: 0 }).replace(/\n$/, '').trim();
+}
+
+interface FlatEntry {
+    path: string[];
+    value: unknown;
+}
+
+function flatten(value: unknown, prefix: string[] = []): FlatEntry[] {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return [{ path: prefix, value }];
+    }
+    const entries: FlatEntry[] = [];
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+        entries.push(...flatten(v, [...prefix, k]));
+    }
+    return entries;
+}
+
+/**
+ * Replace the scalar at `dottedPath` in `template` with `value`.
+ * Comments and unrelated keys are preserved verbatim. Returns the
+ * template unchanged when the path cannot be located (matches the
+ * Python installer's tolerant behaviour).
+ */
+export function replaceScalar(template: string, dottedPath: string[], value: unknown): string {
+    if (dottedPath.length === 0) return template;
+    const sections = dottedPath.slice(0, -1);
+    const key = dottedPath[dottedPath.length - 1];
+    const targetIndent = '  '.repeat(sections.length);
+
+    const lines = template.split('\n');
+    const currentPath: (string | null)[] = new Array<string | null>(sections.length).fill(null);
+    const formatted = formatScalar(value);
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined) continue;
+        const stripped = line.trim();
+        if (stripped === '' || stripped.startsWith('#')) continue;
+        const indentLen = line.length - line.trimStart().length;
+        if (indentLen % 2 !== 0) continue;
+        const level = indentLen / 2;
+        if (level > sections.length) continue;
+
+        const m = /^([A-Za-z_][A-Za-z0-9_]*)\s*:/.exec(stripped);
+        if (!m) continue;
+        const lineKey = m[1];
+        if (lineKey === undefined) continue;
+        if (level < sections.length) {
+            if (lineKey === sections[level]) {
+                currentPath[level] = lineKey;
+                for (let j = level + 1; j < currentPath.length; j++) currentPath[j] = null;
+            } else if (currentPath[level] !== null && lineKey !== currentPath[level]) {
+                currentPath[level] = null;
+            }
+            continue;
+        }
+        // level === sections.length → leaf candidate
+        const parentsMatch = sections.every((s, idx) => currentPath[idx] === s);
+        if (!parentsMatch) continue;
+        if (lineKey !== key) continue;
+        lines[i] = `${targetIndent}${key}: ${formatted}`;
+        return lines.join('\n');
+    }
+    return template;
+}
+
+/**
+ * Apply every leaf change from `newValues` to `templateBody`. Paths that
+ * are not present in the template are appended at the end. Comments are
+ * preserved for every key that already exists in the template.
+ */
+export function mergeIntoTemplate(templateBody: string, newValues: Record<string, unknown>): string {
+    let body = templateBody;
+    const appended: string[] = [];
+    for (const entry of flatten(newValues)) {
+        const before = body;
+        body = replaceScalar(body, entry.path, entry.value);
+        if (body === before) {
+            // Path is not in the template — append a flat key=value at EOF.
+            // Form coverage is asserted by parity test, so this branch only
+            // fires on hand-edited templates.
+            appended.push(`${entry.path.join('.')}: ${formatScalar(entry.value)}`);
+        }
+    }
+    if (appended.length > 0) {
+        if (!body.endsWith('\n')) body += '\n';
+        body += `\n# Wizard-added keys (no template entry)\n${appended.join('\n')}\n`;
+    }
+    return body;
+}
+
+export function diffValues(
+    before: Record<string, unknown>,
+    after: Record<string, unknown>,
+): Array<{ path: string; from: unknown; to: unknown }> {
+    const out: Array<{ path: string; from: unknown; to: unknown }> = [];
+    const bMap = new Map(flatten(before).map((e) => [e.path.join('.'), e.value]));
+    const aMap = new Map(flatten(after).map((e) => [e.path.join('.'), e.value]));
+    const paths = new Set<string>([...bMap.keys(), ...aMap.keys()]);
+    for (const path of paths) {
+        const fromV = bMap.get(path);
+        const toV = aMap.get(path);
+        if (JSON.stringify(fromV) !== JSON.stringify(toV)) out.push({ path, from: fromV, to: toV });
+    }
+    return out;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Recursive dict merge — overlay wins, nested dicts are merged, lists
+ * are replaced (not concatenated). Mirrors `scripts/install.py::deep_merge`
+ * so the Python installer and the Fastify server produce the same
+ * three-layer settings tree (`defaults < global < project`).
+ */
+export function deepMerge(
+    base: Record<string, unknown>,
+    overlay: Record<string, unknown>,
+): Record<string, unknown> {
+    const result: Record<string, unknown> = { ...base };
+    for (const [key, value] of Object.entries(overlay)) {
+        const existing = result[key];
+        if (isPlainObject(existing) && isPlainObject(value)) {
+            result[key] = deepMerge(existing, value);
+        } else {
+            result[key] = value;
+        }
+    }
+    return result;
+}

package/src/shared/settingsClasses.ts

@@ -0,0 +1,235 @@
+/**
+ * Settings A/B/C classes — the pure half.
+ *
+ * `docs/contracts/settings-classes.md` is the single source: one markdown table
+ * row per template leaf, each carrying the class that decides **who may write
+ * that key**. This module parses that table and nothing else. There is
+ * deliberately no generated JSON twin — a second machine-readable copy is a
+ * second thing to drift, and the whole point of the contract is that the fence
+ * and the prose explaining it cannot disagree.
+ *
+ * Pure module — no I/O. Consumed by the lint (`src/scripts/lint_settings_classes.ts`),
+ * the `settings set` writer, and the Fastify settings route, so all three
+ * refuse the same keys for the same reason.
+ *
+ * @see docs/contracts/settings-classes.md
+ */
+
+/** The closed class vocabulary. A row outside it is a defect, not a new class. */
+export const SETTINGS_CLASSES = ['A', 'B', 'C'] as const;
+
+export type SettingsClass = (typeof SETTINGS_CLASSES)[number];
+
+export function isSettingsClass(value: string): value is SettingsClass {
+    return (SETTINGS_CLASSES as readonly string[]).includes(value);
+}
+
+/** One parsed row of the contract's key table. */
+export interface SettingsClassRow {
+    /** Dotted leaf path, e.g. `personal.autonomy`. */
+    key: string;
+    /** Raw class cell — NOT yet validated, so the lint can report a bad one. */
+    cls: string;
+    /** 1-indexed line in the contract, so a finding points at something. */
+    line: number;
+}
+
+/** What the contract's own `## Counts` table claims about itself. */
+export interface DeclaredClassCounts {
+    A: number | null;
+    B: number | null;
+    C: number | null;
+    total: number | null;
+}
+
+/**
+ * `| \`some.key\` | C | \`false\` | why |` → one row.
+ *
+ * The class column is what separates the key table from the prose tables above
+ * it, several of which also open with a backticked key. A second cell that is
+ * not a single bare letter is not a key row.
+ */
+const ROW_RE = /^\|\s*`([^`]+)`\s*\|\s*([^|]*?)\s*\|/;
+
+export function parseSettingsClassRows(markdown: string): SettingsClassRow[] {
+    const rows: SettingsClassRow[] = [];
+    const lines = markdown.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const m = ROW_RE.exec(lines[i] ?? '');
+        if (m === null) {
+            continue;
+        }
+        const key = m[1] ?? '';
+        const cls = m[2] ?? '';
+        if (!/^[A-Za-z]$/.test(cls)) {
+            continue;
+        }
+        rows.push({ key, cls, line: i + 1 });
+    }
+    return rows;
+}
+
+/** `| A — preference | 27 |` and `| **Total** | **140** |` → the declared tallies. */
+export function parseDeclaredClassCounts(markdown: string): DeclaredClassCounts {
+    const read = (re: RegExp): number | null => {
+        const m = re.exec(markdown);
+        const raw = m?.[1];
+        return raw === undefined ? null : Number.parseInt(raw, 10);
+    };
+    return {
+        A: read(/^\|\s*A\s+—\s+preference\s*\|\s*(\d+)\s*\|/m),
+        B: read(/^\|\s*B\s+—\s+consent\s*\|\s*(\d+)\s*\|/m),
+        C: read(/^\|\s*C\s+—\s+guarded\s*\|\s*(\d+)\s*\|/m),
+        total: read(/^\|\s*\*\*Total\*\*\s*\|\s*\*\*(\d+)\*\*\s*\|/m),
+    };
+}
+
+/**
+ * Dotted key → class, for the rows whose class is valid.
+ *
+ * A row with an unparseable class is DROPPED rather than defaulted, so a
+ * caller asking "may I write this?" gets `undefined` — which every caller
+ * treats as refuse. A typo in the contract must never widen the fence.
+ */
+export function buildSettingsClassIndex(rows: readonly SettingsClassRow[]): Map<string, SettingsClass> {
+    const index = new Map<string, SettingsClass>();
+    for (const row of rows) {
+        if (!isSettingsClass(row.cls) || index.has(row.key)) {
+            continue;
+        }
+        index.set(row.key, row.cls);
+    }
+    return index;
+}
+
+/**
+ * Conservative-default test for class B (half one of the B invariant).
+ *
+ * A sparse settings file means absent = default. A B key whose default is the
+ * permissive value makes "never asked" indistinguishable from "answered yes",
+ * which turns the ask into decoration on a decision already taken in the
+ * user's name. These are the values that cannot carry a permission.
+ *
+ * Half two of the invariant — that the ask fires on the user's own request and
+ * never at a moment the agent chose — is prose in the contract, not code. No
+ * gate can read the agent's reason for picking a moment.
+ */
+export function isConservativeDefault(value: unknown): boolean {
+    if (value === null || value === false || value === '' || value === 0) {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return value.length === 0;
+    }
+    if (typeof value === 'object' && value !== null) {
+        return Object.keys(value).length === 0;
+    }
+    return false;
+}
+
+/**
+ * Dotted leaf paths of a parsed settings tree.
+ *
+ * A leaf is anything that is not a NON-EMPTY map. An empty map is a real
+ * configurable value with a real default (`subagents.host_capabilities: {}`),
+ * so it is a leaf — one more than the template↔schema parity walk produces.
+ * That divergence is deliberate: a key the parity walk skips is exactly the
+ * key that would otherwise reach the writer with no class.
+ */
+export function settingsLeafPaths(value: unknown, prefix = ''): string[] {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return [prefix];
+    }
+    const entries = Object.entries(value as Record<string, unknown>);
+    if (entries.length === 0) {
+        return [prefix];
+    }
+    return entries.flatMap(([k, v]) => settingsLeafPaths(v, prefix === '' ? k : `${prefix}.${k}`));
+}
+
+/** Read one dotted path out of a parsed settings tree; `undefined` when absent. */
+export function getSettingsLeaf(root: unknown, dotted: string): unknown {
+    let node: unknown = root;
+    for (const part of dotted.split('.')) {
+        if (typeof node !== 'object' || node === null || Array.isArray(node)) {
+            return undefined;
+        }
+        node = (node as Record<string, unknown>)[part];
+    }
+    return node;
+}
+
+/**
+ * The class governing a dotted path, walking to the nearest classified ancestor.
+ *
+ * An exact row wins. Failing that, the longest classified prefix does: a
+ * class-C key whose value is a MAP has children that never appear in a flattened
+ * diff under the key's own name, so `subagents.host_capabilities.subagent_spawn`
+ * must inherit the C on `subagents.host_capabilities` rather than read as
+ * unclassified. Returns `undefined` when nothing on the path is classified —
+ * and every caller treats that as guarded, not as free.
+ */
+export function classOfPath(
+    index: ReadonlyMap<string, SettingsClass>,
+    dotted: string,
+): SettingsClass | undefined {
+    const exact = index.get(dotted);
+    if (exact !== undefined) {
+        return exact;
+    }
+    const parts = dotted.split('.');
+    for (let end = parts.length - 1; end > 0; end--) {
+        const ancestor = index.get(parts.slice(0, end).join('.'));
+        if (ancestor !== undefined) {
+            return ancestor;
+        }
+    }
+    return undefined;
+}
+
+/** Absent / null / empty-scalar — the three spellings of "not set" in a settings file. */
+export function isUnsetSettingValue(value: unknown): boolean {
+    return value === undefined || value === null || value === '';
+}
+
+/** One entry of a settings diff, as `diffValues` produces them. */
+export interface SettingsChange {
+    path: string;
+    from: unknown;
+    to: unknown;
+}
+
+/**
+ * The changed paths a human must confirm before the write lands.
+ *
+ * Extracted from the Fastify write route so the fail-closed branch is testable
+ * without booting a server around it. That branch is the one a single inverted
+ * operator turns into a fail-OPEN, and a gate whose most dangerous line has no
+ * test is a gate that passes review once and rots after.
+ *
+ * `classes === null` means the contract could not be read. Every changed key is
+ * then guarded: unverifiable is not the same as unguarded. With a contract in
+ * hand, a key is guarded when its nearest classified ancestor is C, and ALSO
+ * when nothing on its path is classified at all — the same per-key refusal the
+ * CLI writer applies.
+ *
+ * Pairs where both sides are unset are dropped first: a key written as `null`
+ * reads back as `''` through the comment-preserving merge, and a confirmation
+ * that appears on every save is one nobody reads.
+ */
+export function guardedChangedKeys(
+    classes: ReadonlyMap<string, SettingsClass> | null,
+    changed: readonly SettingsChange[],
+): string[] {
+    return changed
+        .filter((c) => !(isUnsetSettingValue(c.from) && isUnsetSettingValue(c.to)))
+        .map((c) => c.path)
+        .filter((key) => {
+            if (classes === null) {
+                return true;
+            }
+            const cls = classOfPath(classes, key);
+            return cls === 'C' || cls === undefined;
+        })
+        .sort();
+}