@event4u/agent-config 16.4.0 → 17.0.0

package/dist/hooks/svg_rules.chunk.cjs.sha256

@@ -0,0 +1 @@
+4f7974e0505d035deb48babbf569362d8d3b09abede59f4e18f16ac8ced6ab40  svg_rules.chunk.cjs

package/dist/install/conflict.js

@@ -2,7 +2,7 @@
  * Conflict resolution — Phase A5 (simplified, three modes).
  *
  * Three decisions only, replacing the legacy `prompt → write / skip /
- * abort` triple from `scripts/install.py:_resolve_file_conflict`:
+ * abort` triple from `_resolve_file_conflict` in the retired Python installer:
  *
  * - `write`   — target either does not exist OR policy authorises overwrite.
  * - `skip`    — target exists, known path, not forced: leave it alone.
@@ -16,7 +16,8 @@
  */
 import { existsSync } from 'node:fs';
 import { sha256File } from './plan.js';
-import { classifyOwnership, recordedHashesForRoot, } from './recordedOwnership.js';
+import { isLedgerMigration } from './preserve.js';
+import { classifyOwnership, ledgerListedPaths, recordedHashesWithLedger, } from './recordedOwnership.js';
 /**
  * Decide what to do with a single planned target.
  *
@@ -67,7 +68,7 @@ export function resolveFileConflict(inputs) {
 /**
  * Recursive object merge — overlay wins, nested dicts merged, arrays replaced.
  *
- * Mirrors `scripts/install.py:deep_merge`. Arrays do **not** concatenate;
+ * Mirrors `deep_merge` in the retired Python installer. Arrays do **not** concatenate;
  * Claude / Cursor / Cline hook configs rely on whole-array replacement to
  * stay idempotent across re-runs.
  *
@@ -159,7 +160,7 @@ export const CONFLICT_BATCH_THRESHOLD = 5;
  *   modified rows above and loses the unchanged ones below.
  *
  * `recorded` is injectable for tests; by default it is read from the
- * manifest at `plan.root`.
+ * manifest at `plan.root`, with the user-scoped ownership ledger laid over it.
  */
 export function computeConflicts(plan, recordedOverride) {
     // Force returns before the manifest is read. As a default parameter the
@@ -167,7 +168,15 @@ export function computeConflicts(plan, recordedOverride) {
     // force-mode plan paid a read and a YAML parse for nothing.
     if (plan.policy.force)
         return [];
-    const recorded = recordedOverride ?? recordedHashesForRoot(plan.root);
+    const recorded = recordedOverride ?? recordedHashesWithLedger(plan.root);
+    // Read lazily and once: a pass over a tree whose ledger paths all carry
+    // digests never reaches the branch that needs this, and an unconditional
+    // read would charge every plan for an answer most of them discard.
+    let ledgerFiles = null;
+    const ledgerLists = (p) => {
+        ledgerFiles ??= ledgerListedPaths();
+        return ledgerFiles.has(p);
+    };
     const out = [];
     for (const entries of Object.values(plan.filesByTool)) {
         for (const entry of entries) {
@@ -190,7 +199,27 @@ export function computeConflicts(plan, recordedOverride) {
                 continue;
             if (ownership === 'unknown' && plan.policy.knownPaths.has(entry.path))
                 continue;
-            if (onDisk === entry.sha256)
+            // CANDIDACY, not the verdict, and it is computed BEFORE the
+            // equality short-circuit below rather than after. The migration
+            // branch preserves when the bytes differ from what the run WOULD
+            // write — source plus the install-time tag — while `entry.sha256`
+            // is the digest of the UNTAGGED source. The two comparisons are
+            // not the same for any tagged `.md`, which is most of the deployed
+            // tree, so a file that matches the untagged source can still be
+            // preserved by the writer. Short-circuiting first would make the
+            // preview silent about exactly those, and silence is the one
+            // answer a preview must not give about a file the install is
+            // going to keep. Only the writer can tag before hashing, so only
+            // the writer decides; this reports which entries take that path.
+            const migration = ownership === 'unknown' &&
+                isLedgerMigration({
+                    exists: true,
+                    recordedSha256: recorded.get(entry.path),
+                    onDiskSha256: onDisk,
+                    force: false,
+                    ledgerListed: ledgerLists(entry.path),
+                });
+            if (onDisk === entry.sha256 && !migration)
                 continue;
             out.push({
                 path: entry.path,
@@ -199,6 +228,7 @@ export function computeConflicts(plan, recordedOverride) {
                 existingSha256: onDisk,
                 mergeable: isJsonTarget(entry),
                 ownership,
+                migration,
             });
         }
     }

package/dist/install/conflictTracker.js

@@ -18,10 +18,11 @@
  */
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { mkdirp, pathExists, resolvePath, sha256OfFile } from './fsPrimitives.js';
-import { EXIT_COMPLETED_WITH_CONFLICTS, conflictSummaryMessage, decideDeployWrite, foreignSidecarMessage, preservedFileMessage, sidecarPathFor, } from './preserve.js';
-import { recordedHashesForRoot } from './recordedOwnership.js';
+import { EXIT_COMPLETED_WITH_CONFLICTS, conflictSummaryMessage, decideDeployWrite, foreignSidecarMessage, isLedgerMigration, migrationPreservedMessage, preservedFileMessage, sidecarPathFor, } from './preserve.js';
+import { ledgerListedPaths, recordedHashesWithLedger } from './recordedOwnership.js';
 /**
  * Build a tracker bound to one installer's reporting surface.
  *
@@ -35,7 +36,9 @@ export function createConflictTracker(host) {
     const conflictState = {
         root: null,
         recorded: null,
+        ledgerFiles: null,
         preserved: [],
+        migrated: new Set(),
         staged: new Map(),
     };
     /**
@@ -56,13 +59,67 @@ export function createConflictTracker(host) {
     function recordedHashFor(target) {
         if (conflictState.root === null)
             return undefined;
-        conflictState.recorded ??= recordedHashesForRoot(conflictState.root);
+        conflictState.recorded ??= recordedHashesWithLedger(conflictState.root);
         const plain = path.resolve(target);
         if (conflictState.recorded.has(plain))
             return conflictState.recorded.get(plain);
         const real = resolvePath(target);
         return real === plain ? undefined : conflictState.recorded.get(real);
     }
+    /**
+     * Does the ownership ledger list this path, under either spelling?
+     *
+     * Both keys are tried for the reason `recordedHashFor` documents: on macOS
+     * the temp and home trees sit behind a realpath symlink that rewrites a
+     * `/var` prefix onto its private twin, so a single spelling misses every
+     * entry on the platform this is developed on.
+     */
+    function ledgerLists(target) {
+        conflictState.ledgerFiles ??= ledgerListedPaths();
+        const files = conflictState.ledgerFiles;
+        return files.has(path.resolve(target)) || files.has(resolvePath(target));
+    }
+    /**
+     * The digest of the bytes this run would write to `target`.
+     *
+     * Built into a temp file rather than hashed off the package source,
+     * because a deployed file is the package bytes PLUS the install-time tag
+     * and the two differ — comparing against the untagged source would call
+     * every up-to-date file divergent. The temp name carries the TARGET's
+     * extension because `tagDeployed` keys on it, the same constraint
+     * `stageInto` works around.
+     *
+     * `null` on any failure, which preserves: this is consulted only where
+     * nothing can be proven, and failing toward the recoverable direction is
+     * the whole point of the branch that calls it.
+     */
+    function wouldWriteDigest(target, would) {
+        // Under the OS temp dir, never beside the target: a host rule directory
+        // loads every `.md` in it, and a process killed before the unlink below
+        // would leave this file there to be loaded as a rule.
+        const tmp = path.join(os.tmpdir(), `agent-config-would.${process.pid}.${crypto.randomBytes(6).toString('hex')}${path.extname(target)}`);
+        try {
+            if ('content' in would) {
+                fs.writeFileSync(tmp, would.content, 'utf-8');
+            }
+            else {
+                fs.copyFileSync(would.from, tmp);
+                host.tagDeployed(tmp, would.from, would.packageRoot);
+            }
+            return sha256OfFile(tmp);
+        }
+        catch {
+            return null;
+        }
+        finally {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch {
+                /* swallow — best-effort cleanup of our own temp file */
+            }
+        }
+    }
     /**
      * Produce the bytes this run would have written, then reconcile them with
      * whatever already sits at the sidecar path.
@@ -142,14 +199,19 @@ export function createConflictTracker(host) {
         if (conflictState.preserved.includes(target))
             return;
         conflictState.preserved.push(target);
-        host.warn(preservedFileMessage(target, sidecar));
+        host.warn(conflictState.migrated.has(path.resolve(target))
+            ? migrationPreservedMessage(target, sidecar)
+            : preservedFileMessage(target, sidecar));
     }
     return {
         conflictState,
+        recordedDigest: recordedHashFor,
         begin(root) {
             conflictState.root = root;
             conflictState.recorded = null;
+            conflictState.ledgerFiles = null;
             conflictState.preserved = [];
+            conflictState.migrated = new Set();
             conflictState.staged = new Map();
         },
         /**
@@ -158,14 +220,26 @@ export function createConflictTracker(host) {
          * so a file edited between planning and writing is still classified
          * from the bytes that are actually about to be destroyed.
          */
-        resolve(target, force) {
+        resolve(target, force, would) {
             const exists = pathExists(target);
-            return decideDeployWrite({
+            const base = {
                 exists,
                 recordedSha256: exists ? recordedHashFor(target) : undefined,
                 onDiskSha256: exists ? sha256OfFile(target) : null,
                 force,
-            });
+                ledgerListed: exists && ledgerLists(target),
+            };
+            // The packaged digest costs a temp write and a tag, so it is
+            // computed only for the targets that can consume it. On a tree
+            // where every ledger-listed path carries a digest — which is every
+            // tree the ledger itself has written — this is false throughout
+            // and the run pays nothing.
+            const migrating = isLedgerMigration(base);
+            const decision = decideDeployWrite(migrating ? { ...base, packagedSha256: wouldWriteDigest(target, would) } : base);
+            if (decision === 'preserve' && migrating) {
+                conflictState.migrated.add(path.resolve(target));
+            }
+            return decision;
         },
         /**
          * Stage the package content beside a preserved target.

package/dist/install/detect.js

@@ -1,5 +1,5 @@
 /**
- * Detection layer — Phase A2 port of `scripts/install.py:detect_*`.
+ * Detection layer — Phase A2 port of ``detect_` in the retired Python installer*`.
  *
  * Pure functions only: read once, return a plan. No side effects in
  * the detection itself — atomic writes and conflict resolution happen
@@ -75,7 +75,7 @@ export const SCOPE_DETECT_AI_FILES = [
 /**
  * Multi-signal scope detection (ADR-007 D2 / Phase 1.3).
  *
- * 1:1 port of `scripts/install.py:detect_scope`. Pure — no side effects.
+ * 1:1 port of `detect_scope` in the retired Python installer. Pure — no side effects.
  */
 export function detectScope(cwd) {
     if (existsSync(join(cwd, SETTINGS_FILE))) {
@@ -165,7 +165,7 @@ export function discoverPacks(workspaceRoot) {
 /**
  * Locate the agent-config package root from a project root.
  *
- * 1:1 port of `scripts/install.py:detect_package_root` — prefers an
+ * 1:1 port of `detect_package_root` in the retired Python installer — prefers an
  * npm-installed copy under `node_modules/@event4u/agent-config/`,
  * falls back to the project root itself for in-package development
  * (presence of `src/config/profiles/minimal.ini` is the development-mode

package/dist/install/hostPermissionsAdapter.js

@@ -0,0 +1,106 @@
+/**
+ * How each host spells a permission deny rule, and where that spelling was
+ * read from.
+ *
+ * `road-to-a-project-contract-written-down` step 2.1 named
+ * `src/scripts/hooks/host_lowering.yaml` as the home for this pin. It is not
+ * the home, and the departure is recorded in the roadmap's Decisions table
+ * rather than taken quietly. The measurement that forced it:
+ *
+ *   - That table is keyed `(host, surface, slot)` and its own header states
+ *     its subject — "how each host lowers a dispatcher verdict into its own
+ *     hook contract". A permission deny rule has no slot and no verdict; it is
+ *     consulted BEFORE a tool runs, not after a hook dispatches.
+ *   - `_structure()` there reads only named hook keys, so a `permissions:`
+ *     block added to the YAML would be dropped from the typed table and read
+ *     by nobody, while still moving the compiled body's fingerprint.
+ *
+ * Put to the AI council on 2026-10-13 (anthropic + openai, 2/2 present, both
+ * seats converging): place the fact here, keep the classifier host-neutral,
+ * and let a provenance gate stand in for the plumbing ratification the hook
+ * table would have carried.
+ *
+ * ```
+ * THE CLASSIFIER DECIDES WHAT A BULLET MEANS. THIS DECIDES HOW A HOST SPELLS IT.
+ * A HOST ABSENT FROM THE TABLE IS A HOST NOBODY ESTABLISHED — NEVER A REFUSAL.
+ * ```
+ */
+export const HOST_PERMISSION_SYNTAX = {
+    claude: {
+        host: 'claude',
+        docs_url: 'https://code.claude.com/docs/en/permissions.md',
+        docs_at: '2026-10-13',
+        expires: '2027-10-13',
+        deny_key: 'permissions.deny',
+        examples: [
+            // "Claude Code checks file permissions against `Edit(path)` and
+            // `Read(path)` rules only. … Use `Edit(docs/**)` in place of
+            // `Write(docs/**)`, `NotebookEdit(docs/**)`, or `MultiEdit(docs/**)`."
+            'Edit(docs/**)',
+            // "To block Claude's file tools from reading a file or directory,
+            // add a `Read` deny rule for its path, such as `Read(./.env)` or
+            // `Read(./secrets/**)`."
+            'Read(./secrets/**)',
+            // "`Bash(npm run build)` | Matches the exact command `npm run build`"
+            'Bash(npm run build)',
+            // "A `*` at the end, with a space before it, also matches the bare
+            // command. `Bash(ls *)` matches `ls`, and `Bash(git log *)` matches
+            // `git log`. That holds only when the trailing `*` is the rule's
+            // only wildcard: `Bash(* --help *)` matches `npm --help x` but not
+            // `npm --help`."
+            'Bash(ls *)',
+        ],
+    },
+};
+/** The row for `host`, or `null` when nothing is established for it. */
+export function syntaxFor(host) {
+    return HOST_PERMISSION_SYNTAX[host] ?? null;
+}
+/**
+ * The path spec a rule carries.
+ *
+ * A trailing `/` means the directory's contents, which the host spells `/**`.
+ * Everything else is passed through as the consumer wrote it: "a deny or ask
+ * rule whose path isn't usable as a gitignore pattern still guards that exact
+ * path", and widening `src/generated` to `src/generated/**` on a guess would be
+ * the same guess the classifier refuses.
+ */
+function pathSpec(token) {
+    return token.endsWith('/') ? `${token}**` : token;
+}
+/**
+ * The deny rows `c` becomes on `host`. Empty for prose, and empty for a host
+ * with no established row.
+ *
+ * A COMMAND BECOMES TWO ROWS, and the reason is NOT the one an earlier version
+ * of this comment gave. It claimed `Bash(x *)` never matches the bare `x`; the
+ * page says the opposite one line above the sentence that was read — "A `*` at
+ * the end, with a space before it, also matches the bare command." A review
+ * caught it, and it had reached the roadmap as that step's "one non-obvious
+ * finding", so the correction is recorded rather than quietly applied.
+ *
+ * The real reason is the page's own qualifier: the bare-command match "holds
+ * only when the trailing `*` is the rule's only wildcard". A consumer token
+ * carrying its own `*` breaks that, and the exact row is what still guards the
+ * plain command then. One row would be right for most tokens and silently
+ * wrong for those — Risk 3 in the register, "a rule in the wrong syntax is
+ * accepted by the file and enforced by nothing".
+ *
+ * A READ no-go renders `Read(...)` AND `Edit(...)`. The `Read` deny covers the
+ * Edit and Write tools on the same path, but the page names the exception:
+ * "NotebookEdit isn't covered, so add an `Edit` deny rule for paths no tool may
+ * change." A read no-go over a directory holding notebooks would otherwise
+ * leave NotebookEdit able to change it.
+ */
+export function denyRulesFor(host, c) {
+    if (syntaxFor(host) === null || c.action === null || c.token === null)
+        return [];
+    if (c.kind === 'command')
+        return [`Bash(${c.token})`, `Bash(${c.token} *)`];
+    if (c.kind === 'path') {
+        const spec = pathSpec(c.token);
+        return c.action === 'read' ? [`Read(${spec})`, `Edit(${spec})`] : [`Edit(${spec})`];
+    }
+    return [];
+}
+//# sourceMappingURL=hostPermissionsAdapter.js.map