@webpieces/ai-hook-rules 0.4.737 → 0.4.739

package/src/core/target-tree.d.ts

@@ -0,0 +1,82 @@
+import { EffectiveTree, EffectiveTreeResolver } from './effective-tree';
+/**
+ * WHICH TREE owns the FILE a Write/Edit/Read is aimed at? The file-path counterpart to
+ * EffectiveTreeResolver, which answers the same question for a Bash command's effective cwd.
+ *
+ * WHY IT HAS TO EXIST (issue #851). The bash half of this question has been answered by git since
+ * effective-tree.ts was written — `isLinkedWorktree` is `--git-dir !== --git-common-dir`, and its header
+ * states the principle in capitals: *PLACEMENT IS NOT IDENTITY*. The FILE half never consumed that
+ * answer. Every file-scoped guard judged `ctx.workspaceRoot`, which is the walk-up from the SESSION's
+ * cwd to whichever `webpieces.config.json` governs it — the PRIMARY clone, for a main-session edit into
+ * an agent worktree. Because Claude Code checks a worktree out INSIDE the repo at
+ * `<repo>/.claude/worktrees/agent-XXXX`, that walk-up answers "primary" for a path that is manifestly
+ * not the primary's, and nothing downstream re-examined it.
+ *
+ * Measured live on 2026-09-03: an Edit of one import line inside a worktree on a CLEAN branch was
+ * refused, citing `pnpm-lock.yaml` and `pnpm-workspace.yaml` — the PRIMARY clone's branch's conflict
+ * files. The main-sync cache is already keyed by branch and already held the correct, non-conflicting
+ * entry for the worktree's branch, one key over. Only the lookup key was wrong. So this class exists to
+ * make the lookup ask the same authority the bash half asks, rather than to introduce a second one.
+ *
+ * IT ASKS EffectiveTreeResolver, and adds NOTHING of its own beyond finding a directory to ask about.
+ * That is deliberate and it is the whole design: two resolvers WILL disagree about which tree a path is
+ * in, and this module exists precisely because two layers already did. There is no `.claude/worktrees`
+ * string match here and there must never be one — matching on placement is the bug, not the fix.
+ *
+ * The only thing worth naming is the walk-up: a Write legitimately names a file, and directories, that
+ * do not exist yet, and git cannot be asked about a directory that is not there. So we climb to the
+ * nearest EXISTING ancestor and ask about that. A parent directory is in the same worktree as the child
+ * it is about to contain — that is a property of the filesystem, not a guess.
+ */
+export declare class TargetTreeResolver {
+    private readonly trees;
+    constructor(trees?: EffectiveTreeResolver);
+    /**
+     * The tree that owns `targetPath`, classified exactly as a Bash command's cwd would be.
+     *
+     * `governedRoot` is the fallback for every case with no better answer — an empty path, a path with
+     * no existing ancestor at all — and is also what `EffectiveTree.governedRoot` keeps meaning: whose
+     * config and excludePaths apply. It is NOT the tree to judge; `EffectiveTree.root` is.
+     */
+    resolve(targetPath: string, governedRoot: string): EffectiveTree;
+    /**
+     * The two relative spellings of one target path, resolved together so a caller cannot accidentally
+     * use the wrong one. See GovernedPath for why there are two.
+     */
+    governedPath(targetPath: string, governedRoot: string): GovernedPath;
+    private nearestExistingDir;
+    /**
+     * `targetPath` made absolute AND symlink-resolved, including when it does not exist yet.
+     *
+     * `fs.realpathSync` throws on a missing path, and a Write's target is missing by definition, so the
+     * resolvable HEAD of the path (its nearest existing ancestor) is resolved and the not-yet-existing
+     * TAIL is re-appended verbatim. That keeps it comparable with `tree.root`, which is git's answer and
+     * always real.
+     */
+    private realAbsolute;
+    private realDir;
+}
+/**
+ * One target path, in the TWO relative spellings the hook path needs — data-only, per CLAUDE.md.
+ *
+ * They are different questions and conflating them is issue #851's secondary defect:
+ *
+ *   `relativePath`     — relative to the GOVERNED root. What `excludePaths`' globs are written against,
+ *                        and what the violation report prints.
+ *   `treeRelativePath` — relative to the tree that OWNS the file. What `isWebpiecesStateDir` must be
+ *                        asked about, because `.webpieces/` is the tooling's state dir *of a tree*, and
+ *                        a worktree has its own. Governed-root-relative, a reviewer subagent's
+ *                        `<primary>/.claude/worktrees/agent-X/.webpieces/pr-review/<branch>/review.json`
+ *                        reads as `.claude/...` and was NOT exempt — while
+ *                        `<primary>/.webpieces/worktrees/agent-X/pr-review/.../review-1.json`, the same
+ *                        kind of file one directory over, was. `wp-review-upsert-pr` REQUIRES that file
+ *                        before `wp-finish-upsert-pr` will open a PR, so the guard could forbid a file
+ *                        the gate demands.
+ *
+ * In the primary clone the two strings are identical, which is why the gap was invisible for so long.
+ */
+export declare class GovernedPath {
+    readonly relativePath: string;
+    readonly treeRelativePath: string;
+    constructor(relativePath: string, treeRelativePath: string);
+}

package/src/core/target-tree.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GovernedPath = exports.TargetTreeResolver = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const effective_tree_1 = require("./effective-tree");
+/**
+ * WHICH TREE owns the FILE a Write/Edit/Read is aimed at? The file-path counterpart to
+ * EffectiveTreeResolver, which answers the same question for a Bash command's effective cwd.
+ *
+ * WHY IT HAS TO EXIST (issue #851). The bash half of this question has been answered by git since
+ * effective-tree.ts was written — `isLinkedWorktree` is `--git-dir !== --git-common-dir`, and its header
+ * states the principle in capitals: *PLACEMENT IS NOT IDENTITY*. The FILE half never consumed that
+ * answer. Every file-scoped guard judged `ctx.workspaceRoot`, which is the walk-up from the SESSION's
+ * cwd to whichever `webpieces.config.json` governs it — the PRIMARY clone, for a main-session edit into
+ * an agent worktree. Because Claude Code checks a worktree out INSIDE the repo at
+ * `<repo>/.claude/worktrees/agent-XXXX`, that walk-up answers "primary" for a path that is manifestly
+ * not the primary's, and nothing downstream re-examined it.
+ *
+ * Measured live on 2026-09-03: an Edit of one import line inside a worktree on a CLEAN branch was
+ * refused, citing `pnpm-lock.yaml` and `pnpm-workspace.yaml` — the PRIMARY clone's branch's conflict
+ * files. The main-sync cache is already keyed by branch and already held the correct, non-conflicting
+ * entry for the worktree's branch, one key over. Only the lookup key was wrong. So this class exists to
+ * make the lookup ask the same authority the bash half asks, rather than to introduce a second one.
+ *
+ * IT ASKS EffectiveTreeResolver, and adds NOTHING of its own beyond finding a directory to ask about.
+ * That is deliberate and it is the whole design: two resolvers WILL disagree about which tree a path is
+ * in, and this module exists precisely because two layers already did. There is no `.claude/worktrees`
+ * string match here and there must never be one — matching on placement is the bug, not the fix.
+ *
+ * The only thing worth naming is the walk-up: a Write legitimately names a file, and directories, that
+ * do not exist yet, and git cannot be asked about a directory that is not there. So we climb to the
+ * nearest EXISTING ancestor and ask about that. A parent directory is in the same worktree as the child
+ * it is about to contain — that is a property of the filesystem, not a guess.
+ */
+class TargetTreeResolver {
+    trees;
+    constructor(trees = new effective_tree_1.EffectiveTreeResolver()) {
+        this.trees = trees;
+    }
+    /**
+     * The tree that owns `targetPath`, classified exactly as a Bash command's cwd would be.
+     *
+     * `governedRoot` is the fallback for every case with no better answer — an empty path, a path with
+     * no existing ancestor at all — and is also what `EffectiveTree.governedRoot` keeps meaning: whose
+     * config and excludePaths apply. It is NOT the tree to judge; `EffectiveTree.root` is.
+     */
+    resolve(targetPath, governedRoot) {
+        // REAL paths on BOTH sides, or git's answers cannot be compared with each other. Identity here
+        // is `commonDir(target) === commonDir(governed)`, and git prints an ABSOLUTE, symlink-resolved
+        // path from a linked worktree while printing a bare relative `.git` from the primary clone. So
+        // on any repo reached through a symlink — `/var/folders/...` on macOS, which is `/private/var`,
+        // and every `os.tmpdir()` path under it — the two strings differ for the same `.git` and the
+        // repo's OWN worktree classifies as `foreign`, i.e. every guard silently off. Resolving both
+        // sides first is what makes the comparison an answer about git rather than about spelling.
+        const governed = this.realDir(governedRoot);
+        return this.trees.resolve('', this.nearestExistingDir(targetPath, governed), governed);
+    }
+    /**
+     * The two relative spellings of one target path, resolved together so a caller cannot accidentally
+     * use the wrong one. See GovernedPath for why there are two.
+     */
+    governedPath(targetPath, governedRoot) {
+        const absolute = this.realAbsolute(targetPath);
+        const tree = this.resolve(targetPath, governedRoot);
+        // `tree.root` and `tree.governedRoot` are already resolved by resolve() above, so both
+        // subtractions are real-against-real. Mixing one resolved side with one unresolved one produces
+        // a `../../../..` climb out of the filesystem — which reads as "outside the workspace" and
+        // would quietly hand every path the wrong verdict on a symlinked checkout.
+        return new GovernedPath(path.relative(tree.governedRoot, absolute), path.relative(tree.root, absolute));
+    }
+    // The nearest ancestor directory of `targetPath` that EXISTS — the deepest directory git can be
+    // asked about — with symlinks resolved. Bounded by the filesystem root (path.dirname is its own
+    // fixed point at `/`), so the loop terminates without a counter.
+    nearestExistingDir(targetPath, governedRoot) {
+        if (targetPath === '')
+            return governedRoot;
+        let dir = path.dirname(path.resolve(targetPath));
+        for (;;) {
+            if (fs.existsSync(dir))
+                return fs.realpathSync(dir);
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return governedRoot;
+            dir = parent;
+        }
+    }
+    /**
+     * `targetPath` made absolute AND symlink-resolved, including when it does not exist yet.
+     *
+     * `fs.realpathSync` throws on a missing path, and a Write's target is missing by definition, so the
+     * resolvable HEAD of the path (its nearest existing ancestor) is resolved and the not-yet-existing
+     * TAIL is re-appended verbatim. That keeps it comparable with `tree.root`, which is git's answer and
+     * always real.
+     */
+    realAbsolute(targetPath) {
+        const absolute = path.resolve(targetPath);
+        const tail = [];
+        let dir = absolute;
+        for (;;) {
+            if (fs.existsSync(dir))
+                return path.join(fs.realpathSync(dir), ...tail);
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return absolute;
+            tail.unshift(path.basename(dir));
+            dir = parent;
+        }
+    }
+    // A directory made real when it is there, and merely absolute when it is not.
+    realDir(dir) {
+        return fs.existsSync(dir) ? fs.realpathSync(dir) : path.resolve(dir);
+    }
+}
+exports.TargetTreeResolver = TargetTreeResolver;
+/**
+ * One target path, in the TWO relative spellings the hook path needs — data-only, per CLAUDE.md.
+ *
+ * They are different questions and conflating them is issue #851's secondary defect:
+ *
+ *   `relativePath`     — relative to the GOVERNED root. What `excludePaths`' globs are written against,
+ *                        and what the violation report prints.
+ *   `treeRelativePath` — relative to the tree that OWNS the file. What `isWebpiecesStateDir` must be
+ *                        asked about, because `.webpieces/` is the tooling's state dir *of a tree*, and
+ *                        a worktree has its own. Governed-root-relative, a reviewer subagent's
+ *                        `<primary>/.claude/worktrees/agent-X/.webpieces/pr-review/<branch>/review.json`
+ *                        reads as `.claude/...` and was NOT exempt — while
+ *                        `<primary>/.webpieces/worktrees/agent-X/pr-review/.../review-1.json`, the same
+ *                        kind of file one directory over, was. `wp-review-upsert-pr` REQUIRES that file
+ *                        before `wp-finish-upsert-pr` will open a PR, so the guard could forbid a file
+ *                        the gate demands.
+ *
+ * In the primary clone the two strings are identical, which is why the gap was invisible for so long.
+ */
+class GovernedPath {
+    relativePath;
+    treeRelativePath;
+    constructor(relativePath, treeRelativePath) {
+        this.relativePath = relativePath;
+        this.treeRelativePath = treeRelativePath;
+    }
+}
+exports.GovernedPath = GovernedPath;
+//# sourceMappingURL=target-tree.js.map

package/src/core/target-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-tree.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/target-tree.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\n\nimport { EffectiveTree, EffectiveTreeResolver } from './effective-tree';\n\n/**\n * WHICH TREE owns the FILE a Write/Edit/Read is aimed at? The file-path counterpart to\n * EffectiveTreeResolver, which answers the same question for a Bash command's effective cwd.\n *\n * WHY IT HAS TO EXIST (issue #851). The bash half of this question has been answered by git since\n * effective-tree.ts was written — `isLinkedWorktree` is `--git-dir !== --git-common-dir`, and its header\n * states the principle in capitals: *PLACEMENT IS NOT IDENTITY*. The FILE half never consumed that\n * answer. Every file-scoped guard judged `ctx.workspaceRoot`, which is the walk-up from the SESSION's\n * cwd to whichever `webpieces.config.json` governs it — the PRIMARY clone, for a main-session edit into\n * an agent worktree. Because Claude Code checks a worktree out INSIDE the repo at\n * `<repo>/.claude/worktrees/agent-XXXX`, that walk-up answers \"primary\" for a path that is manifestly\n * not the primary's, and nothing downstream re-examined it.\n *\n * Measured live on 2026-09-03: an Edit of one import line inside a worktree on a CLEAN branch was\n * refused, citing `pnpm-lock.yaml` and `pnpm-workspace.yaml` — the PRIMARY clone's branch's conflict\n * files. The main-sync cache is already keyed by branch and already held the correct, non-conflicting\n * entry for the worktree's branch, one key over. Only the lookup key was wrong. So this class exists to\n * make the lookup ask the same authority the bash half asks, rather than to introduce a second one.\n *\n * IT ASKS EffectiveTreeResolver, and adds NOTHING of its own beyond finding a directory to ask about.\n * That is deliberate and it is the whole design: two resolvers WILL disagree about which tree a path is\n * in, and this module exists precisely because two layers already did. There is no `.claude/worktrees`\n * string match here and there must never be one — matching on placement is the bug, not the fix.\n *\n * The only thing worth naming is the walk-up: a Write legitimately names a file, and directories, that\n * do not exist yet, and git cannot be asked about a directory that is not there. So we climb to the\n * nearest EXISTING ancestor and ask about that. A parent directory is in the same worktree as the child\n * it is about to contain — that is a property of the filesystem, not a guess.\n */\nexport class TargetTreeResolver {\n    constructor(private readonly trees: EffectiveTreeResolver = new EffectiveTreeResolver()) {}\n\n    /**\n     * The tree that owns `targetPath`, classified exactly as a Bash command's cwd would be.\n     *\n     * `governedRoot` is the fallback for every case with no better answer — an empty path, a path with\n     * no existing ancestor at all — and is also what `EffectiveTree.governedRoot` keeps meaning: whose\n     * config and excludePaths apply. It is NOT the tree to judge; `EffectiveTree.root` is.\n     */\n    resolve(targetPath: string, governedRoot: string): EffectiveTree {\n        // REAL paths on BOTH sides, or git's answers cannot be compared with each other. Identity here\n        // is `commonDir(target) === commonDir(governed)`, and git prints an ABSOLUTE, symlink-resolved\n        // path from a linked worktree while printing a bare relative `.git` from the primary clone. So\n        // on any repo reached through a symlink — `/var/folders/...` on macOS, which is `/private/var`,\n        // and every `os.tmpdir()` path under it — the two strings differ for the same `.git` and the\n        // repo's OWN worktree classifies as `foreign`, i.e. every guard silently off. Resolving both\n        // sides first is what makes the comparison an answer about git rather than about spelling.\n        const governed = this.realDir(governedRoot);\n        return this.trees.resolve('', this.nearestExistingDir(targetPath, governed), governed);\n    }\n\n    /**\n     * The two relative spellings of one target path, resolved together so a caller cannot accidentally\n     * use the wrong one. See GovernedPath for why there are two.\n     */\n    governedPath(targetPath: string, governedRoot: string): GovernedPath {\n        const absolute = this.realAbsolute(targetPath);\n        const tree = this.resolve(targetPath, governedRoot);\n        // `tree.root` and `tree.governedRoot` are already resolved by resolve() above, so both\n        // subtractions are real-against-real. Mixing one resolved side with one unresolved one produces\n        // a `../../../..` climb out of the filesystem — which reads as \"outside the workspace\" and\n        // would quietly hand every path the wrong verdict on a symlinked checkout.\n        return new GovernedPath(\n            path.relative(tree.governedRoot, absolute),\n            path.relative(tree.root, absolute),\n        );\n    }\n\n    // The nearest ancestor directory of `targetPath` that EXISTS — the deepest directory git can be\n    // asked about — with symlinks resolved. Bounded by the filesystem root (path.dirname is its own\n    // fixed point at `/`), so the loop terminates without a counter.\n    private nearestExistingDir(targetPath: string, governedRoot: string): string {\n        if (targetPath === '') return governedRoot;\n        let dir = path.dirname(path.resolve(targetPath));\n        for (;;) {\n            if (fs.existsSync(dir)) return fs.realpathSync(dir);\n            const parent = path.dirname(dir);\n            if (parent === dir) return governedRoot;\n            dir = parent;\n        }\n    }\n\n    /**\n     * `targetPath` made absolute AND symlink-resolved, including when it does not exist yet.\n     *\n     * `fs.realpathSync` throws on a missing path, and a Write's target is missing by definition, so the\n     * resolvable HEAD of the path (its nearest existing ancestor) is resolved and the not-yet-existing\n     * TAIL is re-appended verbatim. That keeps it comparable with `tree.root`, which is git's answer and\n     * always real.\n     */\n    private realAbsolute(targetPath: string): string {\n        const absolute = path.resolve(targetPath);\n        const tail: string[] = [];\n        let dir = absolute;\n        for (;;) {\n            if (fs.existsSync(dir)) return path.join(fs.realpathSync(dir), ...tail);\n            const parent = path.dirname(dir);\n            if (parent === dir) return absolute;\n            tail.unshift(path.basename(dir));\n            dir = parent;\n        }\n    }\n\n    // A directory made real when it is there, and merely absolute when it is not.\n    private realDir(dir: string): string {\n        return fs.existsSync(dir) ? fs.realpathSync(dir) : path.resolve(dir);\n    }\n}\n\n/**\n * One target path, in the TWO relative spellings the hook path needs — data-only, per CLAUDE.md.\n *\n * They are different questions and conflating them is issue #851's secondary defect:\n *\n *   `relativePath`     — relative to the GOVERNED root. What `excludePaths`' globs are written against,\n *                        and what the violation report prints.\n *   `treeRelativePath` — relative to the tree that OWNS the file. What `isWebpiecesStateDir` must be\n *                        asked about, because `.webpieces/` is the tooling's state dir *of a tree*, and\n *                        a worktree has its own. Governed-root-relative, a reviewer subagent's\n *                        `<primary>/.claude/worktrees/agent-X/.webpieces/pr-review/<branch>/review.json`\n *                        reads as `.claude/...` and was NOT exempt — while\n *                        `<primary>/.webpieces/worktrees/agent-X/pr-review/.../review-1.json`, the same\n *                        kind of file one directory over, was. `wp-review-upsert-pr` REQUIRES that file\n *                        before `wp-finish-upsert-pr` will open a PR, so the guard could forbid a file\n *                        the gate demands.\n *\n * In the primary clone the two strings are identical, which is why the gap was invisible for so long.\n */\nexport class GovernedPath {\n    readonly relativePath: string;\n    readonly treeRelativePath: string;\n\n    constructor(relativePath: string, treeRelativePath: string) {\n        this.relativePath = relativePath;\n        this.treeRelativePath = treeRelativePath;\n    }\n}\n"]}