@event4u/agent-config 16.5.0 → 17.1.0

package/dist/install/installThinLayer.js

@@ -64,7 +64,7 @@ import { absoluteBodyLinkPrefix, build_thin, split_frontmatter, } from '../scrip
 export function thinInstalledRuleLayer(opts) {
     const packageRoot = path.resolve(opts.packageRoot);
     const bodySourceDir = path.join(packageRoot, 'dist', 'agent-src', 'rules');
-    const bodyLinkPrefix = absoluteBodyLinkPrefix(packageRoot);
+    const bodyLinkPrefix = absoluteBodyLinkPrefix(opts.bodyLinkRoot ?? packageRoot);
     const preserved = opts.preserved ?? new Set();
     // Scope is `null` on purpose. The copy already applied the install's rule
     // scope, so the files that EXIST in `rulesDir` are the scoped set; asking
@@ -157,6 +157,7 @@ export function thinInstalledRuleLayer(opts) {
         try {
             if (next !== installed) {
                 fs.writeFileSync(target, next, 'utf-8');
+                opts.onWrite?.(target);
                 rewritten += 1;
             }
             thinned += 1;

package/dist/install/loggedWrites.js

@@ -0,0 +1,142 @@
+/**
+ * The install transaction log read as an ownership record.
+ *
+ * WHY. The writer preserves any managed file it cannot prove is still the bytes
+ * it wrote. For a file deployed before the ownership ledger recorded digests,
+ * the ledger has nothing to compare against, so EVERY such file was preserved
+ * and a sidecar staged beside it — thousands of them on one upgrade, all
+ * untouched. Worse, the ledger then records the staged digest for each target,
+ * so the next run calls the same untouched file "user-modified".
+ *
+ * The proof was on disk the whole time. `src/scripts/install.ts` appends a
+ * `write` entry carrying the SHA-256 of the target's bytes immediately after
+ * every copy. A file whose bytes equal a digest the log records this installer
+ * writing to that exact path is the installer's own output, unedited. A path
+ * with no matching record keeps the existing answer. WHEN that proof may decide
+ * is narrower than "whenever it matches" — see `decideDeployWrite`.
+ *
+ * WHAT IS READ. The active log and every rotated sibling, plain or gzipped
+ * (`txlog.ts` rotates at 10 MB or 30 days, and the gzip step can leave both
+ * forms behind). An unreadable or truncated file contributes nothing — the
+ * failure direction is "no proof", which preserves.
+ *
+ * COST. Parsed per FILE and cached on that file's size and mtime. A rotated
+ * archive never changes, so only the active log is re-read when it grows — and
+ * an install appends to it after every file it touches, so a cache keyed on the
+ * whole set would re-parse the entire history once per candidate.
+ */
+import { gunzipSync } from 'node:zlib';
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { getLogPath } from './paths.js';
+const WRITE_MARKER = '"kind":"write"';
+const fileCache = new Map();
+const dirRealpaths = new Map();
+/**
+ * One canonical spelling for a path: its directory realpath'd, its basename
+ * kept. Both the log keys and the queries go through it, so `/var/…` and its
+ * macOS realpath twin meet. The directory is realpath'd rather than the file
+ * because the file may not exist, and is memoised because a log names a few
+ * hundred directories across tens of thousands of entries.
+ */
+export function canonicalPath(p) {
+    const abs = resolve(p);
+    const dir = dirname(abs);
+    let real = dirRealpaths.get(dir);
+    if (real === undefined) {
+        try {
+            real = realpathSync(dir);
+        }
+        catch {
+            real = dir;
+        }
+        dirRealpaths.set(dir, real);
+    }
+    return join(real, basename(abs));
+}
+/** The active log plus its rotated siblings, sorted by name. */
+function logFiles(logPath) {
+    const dir = dirname(logPath);
+    if (!existsSync(dir))
+        return [];
+    const stem = basename(logPath).replace(/\.jsonl$/, '');
+    try {
+        return readdirSync(dir)
+            .filter((n) => n.startsWith(stem) && (n.endsWith('.jsonl') || n.endsWith('.jsonl.gz')))
+            .map((n) => join(dir, n))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function writesIn(file) {
+    let stamp;
+    try {
+        const st = statSync(file);
+        stamp = `${st.size}:${Math.trunc(st.mtimeMs)}`;
+    }
+    catch {
+        return [];
+    }
+    const cached = fileCache.get(file);
+    if (cached !== undefined && cached.stamp === stamp)
+        return cached.entries;
+    let text = '';
+    try {
+        const raw = readFileSync(file);
+        text = (file.endsWith('.gz') ? gunzipSync(raw) : raw).toString('utf8');
+    }
+    catch {
+        text = '';
+    }
+    const entries = [];
+    for (const line of text.split('\n')) {
+        if (!line.includes(WRITE_MARKER))
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof entry.path !== 'string' || typeof entry.sha256 !== 'string' || entry.sha256 === '')
+            continue;
+        entries.push([canonicalPath(entry.path), entry.sha256]);
+    }
+    fileCache.set(file, { stamp, entries });
+    return entries;
+}
+/** Every `write` the transaction log records, keyed by canonical path. */
+export function loggedWriteDigests(logPath = getLogPath()) {
+    const writes = new Map();
+    for (const file of logFiles(logPath)) {
+        for (const [target, sha] of writesIn(file)) {
+            let set = writes.get(target);
+            if (set === undefined)
+                writes.set(target, (set = new Set()));
+            set.add(sha);
+        }
+    }
+    return writes;
+}
+/**
+ * Wrap a log writer so it records only paths this run's copy deploys.
+ *
+ * The claude-code rewrite and thinning passes walk the whole rule directory,
+ * including rules the user authored there; logging those rewrites would make
+ * the log vouch for content that was never the package's.
+ */
+export function onlyDeployed(anchor, currentFiles, log) {
+    return (target) => {
+        const rel = relative(resolve(anchor), resolve(target)).split(sep).join('/');
+        if (currentFiles.has(rel))
+            log(target);
+    };
+}
+/** Did this installer write exactly `onDiskSha256` to `target`? */
+export function wroteTheseBytes(target, onDiskSha256, writes) {
+    return writes.get(canonicalPath(target))?.has(onDiskSha256) === true;
+}
+//# sourceMappingURL=loggedWrites.js.map

package/dist/install/manifestFiles.js

@@ -256,4 +256,25 @@ export function preservedIndex(preservedTargets, staged) {
     }
     return out;
 }
+/**
+ * Clear `files[]` on the global-scope entries of `deployed`, in place.
+ *
+ * A consumer commits this lock (`README.md` § Team reproducibility), and a
+ * global entry's files are `$HOME`-rooted absolute paths of whoever installed.
+ * The user-scoped ledger (`ownershipLedger.ts`) holds global ownership, and
+ * `sync` replays a global entry from `name`, `scope` and `bridge_marker` alone,
+ * so the entry stays and its files go. An empty list is written as no `files`
+ * key at all, which is also how a lock committed earlier loses its paths.
+ *
+ * Only for tools whose global deploy ran this install: that run just recorded
+ * their digests in the ledger. A lock-only digest of any other tool is the one
+ * record of a pre-ledger edit, and dropping it first would re-arm the overwrite.
+ */
+export function dropGlobalScopeFiles(entries, deployed) {
+    for (const entry of entries) {
+        if (entry['scope'] === 'global' && deployed.has(String(entry['name'])))
+            entry['files'] = [];
+    }
+    return entries;
+}
 //# sourceMappingURL=manifestFiles.js.map

package/dist/install/noGoDenyRows.js

@@ -0,0 +1,300 @@
+/**
+ * The consent step between a classified no-go and a host deny list.
+ *
+ * `road-to-a-project-contract-written-down` step 2.2. Step 2.1 decides what a
+ * bullet WOULD become; nothing here happens without the consumer saying yes,
+ * and a no writes nothing at all.
+ *
+ * ```
+ * THE ROWS ARE SHOWN BEFORE THEY ARE WRITTEN. A DECLINE WRITES NOTHING.
+ * AN ENTRY THE CONSUMER ALREADY HAD SURVIVES THE APPEND BYTE FOR BYTE.
+ * A HOST WITH NO NATIVE DENY LIST GETS A REPORT, NEVER A FILE.
+ * ```
+ *
+ * WHY THE APPEND IS TEXTUAL. Parsing the settings file and re-serialising it
+ * would reformat a file the consumer owns — re-indenting it, dropping the key
+ * order a reader relies on, and rewriting lines this change has no business
+ * touching. Risk 4 in the roadmap's register is exactly that: "rewriting the
+ * settings file drops a user entry or reorders it". So the body is spliced:
+ * every byte outside the insertion point is the byte that was there before,
+ * which is a property a test can assert rather than a promise.
+ *
+ * The file is still PARSED first, to refuse a malformed one rather than splice
+ * into it.
+ */
+import { classifyNoGos } from './noGoRules.js';
+import { denyRulesFor, syntaxFor } from './hostPermissionsAdapter.js';
+/**
+ * Does this tree know how `host` spells a deny rule?
+ *
+ * A host absent from the adapter is not a host that forbids the idea — it is a
+ * host for which nothing here has established a native deny list. The rows are
+ * then REPORTED and no file is touched, which is the honesty
+ * `host_lowering.yaml` keeps for an unestablished hook slot: absent means
+ * nobody established anything, never "cannot".
+ */
+export function hasNativeDenyList(host) {
+    return syntaxFor(host) !== null;
+}
+export function planDenyRows(noGosSection, host) {
+    // Render against the one host whose spelling is established when the target
+    // host's is not, so an unsupported host still gets a REPORT of what its
+    // no-gos would become rather than an empty screen reading "nothing to do".
+    const renderHost = hasNativeDenyList(host) ? host : 'claude';
+    const classified = classifyNoGos(noGosSection);
+    const rows = classified.map((c) => ({
+        classification: c,
+        rules: denyRulesFor(renderHost, c),
+    }));
+    const seen = new Set();
+    const rules = [];
+    for (const r of rows) {
+        for (const rule of r.rules) {
+            if (seen.has(rule))
+                continue;
+            seen.add(rule);
+            rules.push(rule);
+        }
+    }
+    return {
+        rows,
+        rules,
+        prose: classified.filter((r) => r.kind === 'prose'),
+        enforceable: hasNativeDenyList(host),
+    };
+}
+/**
+ * The text shown before the one consent question.
+ *
+ * Every row names the bullet it came from. Risk 1 in the register is a broad
+ * row stopping an edit the consumer later needs "and the agent cannot say why";
+ * carrying the source bullet beside the rule is what lets it say why.
+ */
+export function renderDenyPlan(plan, host) {
+    const syntax = syntaxFor(plan.enforceable ? host : 'claude');
+    const out = [];
+    if (plan.rules.length === 0) {
+        out.push('No no-go bullet named a path or a command, so there is nothing to enforce.');
+    }
+    else if (plan.enforceable) {
+        out.push(`Deny rows for ${host} (${syntax?.deny_key ?? 'permissions.deny'}), one per enforceable no-go:`, '');
+        for (const r of plan.rows) {
+            for (const rule of r.rules)
+                out.push(`  ${rule}`);
+            if (r.rules.length > 0)
+                out.push(`      from: ${r.classification.bullet}`);
+        }
+    }
+    else {
+        out.push(`${host} has no native deny list established in this tree, so these rows are a`, 'report and nothing is written. They are spelled the way `claude` spells a deny', `rule, NOT the way ${host} does — nothing here has established that ${host} reads`, 'this syntax, or any syntax. They are what the no-gos would become there:', '');
+        for (const r of plan.rows)
+            for (const rule of r.rules)
+                out.push(`  ${rule}`);
+    }
+    if (plan.prose.length > 0) {
+        out.push('', 'Instruction-only — no row was built, and the reason for each:');
+        for (const p of plan.prose)
+            out.push(`  ${p.bullet}`, `      ${p.reason}`);
+    }
+    if (plan.rules.length > 0 && plan.enforceable) {
+        // What the rows do NOT cover, on the consent screen rather than in a
+        // comment. The point of the change is to replace a sentence the agent
+        // can read past with a rule the host refuses on; a consumer consenting
+        // to that should be told where the refusal stops.
+        out.push('', 'What these rows do not reach, per the same documentation:', '  · a Bash rule is prefix-matched, so `./artisan …`, `bash -c "…"` and a', '    wrapper such as `sail` or `devbox run` are not matched by it.', '  · Read and Edit rules reach the file tools and the file commands the host', '    recognises in Bash, but not a script that opens the file itself.', '  A no-go is still worth writing down when no row can be built for it.', '', 'Where they reach FURTHER than the bullet reads:', '  · a path row anchors at the session working directory, not at the repository', '    root, and as a DENY rule a single-segment path matches that directory name', '    at any depth — `Edit(migrations/**)` also covers `vendor/pkg/migrations/`.', '  · the rows go into a file your whole team shares if it is committed. The', '    per-developer alternative is `.claude/settings.local.json`; pass it with', '    `--settings` if these should bind only you.');
+    }
+    if (syntax !== null) {
+        out.push('', `Syntax read from ${syntax.docs_url} on ${syntax.docs_at}.`);
+    }
+    return `${out.join('\n')}\n`;
+}
+/**
+ * Walk `text` as JSON and return the span of the value at `path`.
+ *
+ * A hand-rolled walk rather than a regex because a regex over JSON cannot tell
+ * a brace inside a string from a brace that nests, and a settings file holds
+ * both. Returns `null` when the path is absent or the body is not an object.
+ */
+function locate(text, path) {
+    let i = 0;
+    const stack = [];
+    let pendingKey = null;
+    let target = null;
+    const opens = [];
+    const matches = (depthPath) => depthPath.length === path.length && depthPath.every((s, n) => s === path[n]);
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === '"') {
+            let j = i + 1;
+            while (j < text.length) {
+                if (text[j] === '\\') {
+                    j += 2;
+                    continue;
+                }
+                if (text[j] === '"')
+                    break;
+                j += 1;
+            }
+            const literal = text.slice(i + 1, j);
+            // A key is a string followed by a colon, inside an object.
+            let k = j + 1;
+            while (k < text.length && /\s/.test(text[k]))
+                k += 1;
+            if (text[k] === ':')
+                pendingKey = literal;
+            i = j + 1;
+            continue;
+        }
+        if (ch === '{' || ch === '[') {
+            if (opens.length > 0 && pendingKey !== null)
+                stack.push(pendingKey);
+            else if (opens.length > 0)
+                stack.push('');
+            opens.push(i);
+            pendingKey = null;
+            if (matches(stack))
+                target = { open: i, close: -1 };
+            i += 1;
+            continue;
+        }
+        if (ch === '}' || ch === ']') {
+            const open = opens.pop();
+            if (target !== null && target.close === -1 && open === target.open) {
+                target = { open: target.open, close: i };
+            }
+            if (opens.length > 0)
+                stack.pop();
+            // Clear it here too. A key is only pending for the container that
+            // opens right after it; carrying it across a close made the SECOND
+            // object in an array inherit the first one's last key, so
+            // `{"permissions": [{"deny": 1}, {"a": 2}]}` matched on the wrong
+            // element and spliced a bare string into an object.
+            pendingKey = null;
+            i += 1;
+            continue;
+        }
+        if (ch === ',') {
+            pendingKey = null;
+            i += 1;
+            continue;
+        }
+        i += 1;
+    }
+    return target !== null && target.close >= 0 ? target : null;
+}
+/** The indentation of the line `index` sits on. */
+function indentAt(text, index) {
+    const lineStart = text.lastIndexOf('\n', index - 1) + 1;
+    const m = /^[ \t]*/.exec(text.slice(lineStart, index));
+    return m === null ? '' : m[0];
+}
+/**
+ * Append `rules` to the settings body's deny list.
+ *
+ * Three shapes, in order, and all three splice rather than rewrite:
+ *   1. `permissions.deny` exists — insert before its `]`.
+ *   2. `permissions` exists without `deny` — insert the key after its `{`.
+ *   3. neither — insert a whole `permissions` block after the root `{`.
+ *
+ * Throws on a body that is not a JSON object: refusing a malformed file is the
+ * only safe answer, since a splice into one would produce a second malformed
+ * file and lose the consumer's content.
+ */
+export function appendDenyRules(body, rules) {
+    const parsed = JSON.parse(body);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('settings body is not a JSON object');
+    }
+    const perms = parsed['permissions'];
+    // A `permissions` that is present but NOT an object has no span for
+    // `locate` to find, so without this the root branch below would insert a
+    // SECOND `"permissions"` key. The file stays parseable, the last key wins,
+    // and every row the consumer consented to is silently discarded while the
+    // command reports success — measured, and the defect this refusal exists
+    // for. Refusing is the only honest answer: merging would have to guess what
+    // the existing value meant.
+    if (Object.hasOwn(parsed, 'permissions') &&
+        (perms === null || typeof perms !== 'object' || Array.isArray(perms))) {
+        throw new Error('settings body has a `permissions` key that is not an object — refusing rather ' +
+            'than writing a second one');
+    }
+    // The same refusal one level down, and it is NOT covered by the one above:
+    // `locate` finds no span for a `deny` that is not an array either, so the
+    // `permissions` branch would insert a SECOND `"deny"` key inside the same
+    // object — measured, with the consented row discarded and success
+    // reported. A `deny` that is a string or an object was worse still: the
+    // filter below threw `perms.deny?.filter is not a function`, which reached
+    // the consumer instead of the deliberate refusal written here.
+    const denyRaw = perms !== null && typeof perms === 'object' && !Array.isArray(perms)
+        ? perms['deny']
+        : undefined;
+    if (perms !== null &&
+        typeof perms === 'object' &&
+        !Array.isArray(perms) &&
+        Object.hasOwn(perms, 'deny') &&
+        !Array.isArray(denyRaw)) {
+        throw new Error('settings body has a `permissions.deny` key that is not an array — refusing ' +
+            'rather than writing a second one');
+    }
+    const existing = Array.isArray(denyRaw)
+        ? denyRaw.filter((e) => typeof e === 'string')
+        : [];
+    const have = new Set(existing);
+    const added = rules.filter((r) => !have.has(r));
+    const alreadyPresent = rules.filter((r) => have.has(r));
+    if (added.length === 0)
+        return { text: body, added, alreadyPresent };
+    const denySpan = locate(body, ['permissions', 'deny']);
+    if (denySpan !== null) {
+        const inner = body.slice(denySpan.open + 1, denySpan.close);
+        const closeIndent = indentAt(body, denySpan.open);
+        const indent = `${closeIndent}    `;
+        const entries = added.map((r) => `${indent}${JSON.stringify(r)}`).join(',\n');
+        if (inner.trim().length === 0) {
+            return {
+                text: `${body.slice(0, denySpan.open + 1)}\n${entries}\n${closeIndent}` +
+                    `${body.slice(denySpan.close)}`,
+                added,
+                alreadyPresent,
+            };
+        }
+        // Insert AFTER the last element rather than before the `]`, so the
+        // closing bracket keeps the line and the indentation it already had.
+        // Splicing at the bracket leaves the comma stranded on its own line and
+        // un-indents the `]` — a diff in a file the consumer owns, for nothing.
+        const lastChar = inner.replace(/\s+$/, '').length;
+        const at = denySpan.open + 1 + lastChar;
+        return {
+            text: `${body.slice(0, at)},\n${entries}${body.slice(at)}`,
+            added,
+            alreadyPresent,
+        };
+    }
+    const permSpan = locate(body, ['permissions']);
+    if (permSpan !== null) {
+        const indent = `${indentAt(body, permSpan.open)}    `;
+        const entries = added.map((r) => `${indent}    ${JSON.stringify(r)}`).join(',\n');
+        const inner = body.slice(permSpan.open + 1, permSpan.close);
+        const sep = inner.trim().length === 0 ? '' : ',';
+        const block = `\n${indent}"deny": [\n${entries}\n${indent}]${sep}`;
+        return {
+            text: `${body.slice(0, permSpan.open + 1)}${block}${body.slice(permSpan.open + 1)}`,
+            added,
+            alreadyPresent,
+        };
+    }
+    const rootSpan = locate(body, []);
+    if (rootSpan === null)
+        throw new Error('settings body has no root object');
+    const indent = '    ';
+    const entries = added.map((r) => `${indent}        ${JSON.stringify(r)}`).join(',\n');
+    const inner = body.slice(rootSpan.open + 1, rootSpan.close);
+    const sep = inner.trim().length === 0 ? '' : ',';
+    const block = `\n${indent}"permissions": {\n${indent}    "deny": [\n${entries}\n${indent}    ]\n${indent}}${sep}`;
+    return {
+        text: `${body.slice(0, rootSpan.open + 1)}${block}${body.slice(rootSpan.open + 1)}`,
+        added,
+        alreadyPresent,
+    };
+}
+//# sourceMappingURL=noGoDenyRows.js.map