peaks-loop 4.1.15 → 4.1.17
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +109 -0
- package/dist/cli/commands/code-gate-command.js +16 -1
- package/dist/services/hooks/gate-path-normalize.d.ts +91 -0
- package/dist/services/hooks/gate-path-normalize.js +191 -0
- package/dist/services/hooks/hook-payload-cwd.d.ts +44 -0
- package/dist/services/hooks/hook-payload-cwd.js +113 -0
- package/dist/services/hooks/pre-tool-code-gate.d.ts +39 -39
- package/dist/services/hooks/pre-tool-code-gate.js +77 -111
- package/package.json +5 -5
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"metadata": {
|
|
3
3
|
"pluginRoot": ".",
|
|
4
|
-
"version": "4.1.
|
|
4
|
+
"version": "4.1.17"
|
|
5
5
|
},
|
|
6
6
|
"plugins": [
|
|
7
7
|
{
|
|
8
8
|
"name": "peaks-loop",
|
|
9
9
|
"description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
|
|
10
|
-
"version": "4.1.
|
|
10
|
+
"version": "4.1.17",
|
|
11
11
|
"author": {
|
|
12
12
|
"name": "SquabbyZ"
|
|
13
13
|
},
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,114 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 4.1.17 — 2026-10-22(相对路径按它**在哪个目录**判,不按它**怎么拼写**判)
|
|
4
|
+
|
|
5
|
+
**版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次是**纯修复**:
|
|
6
|
+
既有 CLI 参数、门禁的六个硬阻断族成员、fail-open 策略、auto-compact 三档阈值、
|
|
7
|
+
peaks-code 的 11 步工序与 Gate A–G **一字不改**。
|
|
8
|
+
上一版(4.1.16)把相对路径的**基准**改成了"工具调用实际所在的目录",但**基准与项目根是按字面比较的** ——
|
|
9
|
+
本次把这个洞收口。
|
|
10
|
+
|
|
11
|
+
### 1. 一个目录可以有两种拼法,判决不能因此不同
|
|
12
|
+
|
|
13
|
+
- 此前:相对路径的**基准**(工具调用的目录)与**项目根**按**字面**比较。路径里有符号链接时,
|
|
14
|
+
两者对不上 ⇒ 门禁判定"文件在项目外" ⇒ 退回**按拼写读** ⇒ 拼得像 `src/` 的写法**被放行**。
|
|
15
|
+
- **macOS 上这不是假设**:测试 harness 的项目根来自 `mkdtempSync(tmpdir())`,是**非规范**的
|
|
16
|
+
`/var/folders/...`;而门禁进程自己的工作目录是**规范**的 `/private/var/...`(`/var` 是
|
|
17
|
+
`private/var` 的符号链接)。两者一错配就中招 ⇒ **4.1.16 推上去时 `macos-latest` 那条 job 是红的**,
|
|
18
|
+
8 个用例失败。**Windows 一个月没暴露,只因为本机 temp 路径里没有符号链接。**
|
|
19
|
+
- 现在:路径读**两遍** —— **词面**(怎么写的)与**规范**(文件真实在哪)—— 判决取**最严**的那个。
|
|
20
|
+
**白名单是每一遍各自先判的**:一遍命中白名单不会因为另一遍命中族而变成拒绝。
|
|
21
|
+
- **裁决原则用的是本仓库自己的那条**(见 4.1.15):**误放是漏洞,误拒只是碍事**。
|
|
22
|
+
所以**不是**"规范读法当权威"——那会在 `src` → `shared/src` 这种常见布局里**放宽**门禁
|
|
23
|
+
(词面 `src/x.ts` 拒、规范 `shared/src/x.ts` 放行);而是**任一遍命中族就拒**。
|
|
24
|
+
|
|
25
|
+
### 2. `.sh` 兄弟实现也走同一条规则
|
|
26
|
+
|
|
27
|
+
它原本只按**拼写**判,于是和 Node 版**越漂越远**:Node 拒的写法它放行。
|
|
28
|
+
现在它取同样两遍读法、取同样的最严判决,而且**规范读法相对的是它自己解析出来的那个基准** ——
|
|
29
|
+
两套实现因此不可能对"文件在哪"给出不同答案。
|
|
30
|
+
**两个实现同一条规则,就必须互相测,而不是各自对着自己的预期测。**
|
|
31
|
+
|
|
32
|
+
### 3. 被有意接受的取舍(写在这里以免看起来像疏漏)
|
|
33
|
+
|
|
34
|
+
- **落在项目之外的相对路径**仍按"拼写相对项目根"读 ⇒ **不会放宽**门禁。
|
|
35
|
+
- **一个被纠正的误拒**:当**基准在非族目录**(例如 `<root>/docs`)时,旧的拼写锚定规则会把
|
|
36
|
+
`src/x.ts` 这类写法**拒**掉,而那些文件其实落在 `<root>/docs/…`、**在所有硬阻断族之外**。
|
|
37
|
+
现在按文件真实所在判 ⇒ **放行**。这是**放宽**,方向是裁定自己的不变量(判决跟文件走,不跟拼写走),
|
|
38
|
+
**已接受并记录**(不 claim 掉)。
|
|
39
|
+
- **兄弟实现还有三处已知短板**(它**读不到** payload 顶层 `cwd`、**推导**项目根、**无法相对化绝对路径**),
|
|
40
|
+
归在 backlog §19.1/§19.2 的 owner 决策里,不在本次收口。
|
|
41
|
+
|
|
42
|
+
### 4. 验证
|
|
43
|
+
|
|
44
|
+
- 与**改动前**的代码逐行对照:**896 行里 0 行**让任一实现放行了落在拒绝族里的文件。
|
|
45
|
+
- **不得放宽**:Node 命令**收紧 92 / 放宽 0**;兄弟实现**收紧 76 / 放宽 0**。
|
|
46
|
+
相对**切片前**的代码,Node 112/40、兄弟 108/36 —— 那 76 个放宽**全部**在非族目录的基准上,
|
|
47
|
+
每个文件都落在所有族之外(§3 那个被纠正的误拒),**不是洞**。
|
|
48
|
+
- 家族成员零行改动,fail-open 不变,fast lane 仍然打开这些族。
|
|
49
|
+
- **顺手订正一句注释**:它描述了一种代码并不做的比较(审计里的第六条 LOW)——现在它说的是代码做的事。
|
|
50
|
+
- 另附一条**实测**:门禁读的 payload 顶层 `cwd` **确实是 PreToolUse payload 的顶层字段**
|
|
51
|
+
(对着本机装的 Claude Code 二进制读到构造点,不是推断);**任何 IDE 都会这么发**这一条**仍未实测**。
|
|
52
|
+
|
|
53
|
+
## 4.1.16 — 2026-10-22(相对路径按工具调用实际所在的目录解析)
|
|
54
|
+
|
|
55
|
+
**版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次是**纯修复**:
|
|
56
|
+
既有 CLI 参数、门禁的六个硬阻断族成员、fail-open 策略、auto-compact 三档阈值、
|
|
57
|
+
peaks-code 的 11 步工序与 Gate A–G **一字不改**。
|
|
58
|
+
上一版(4.1.15)在 QA 复核里**诚实记下了一个洞**:工具调用的工作目录不是项目根时,
|
|
59
|
+
相对路径落在 `src/` 里却被放行 —— "判定只由文件落在哪个目录决定"这条不变量**还没有完全成立**。
|
|
60
|
+
**本次把它收口。**
|
|
61
|
+
|
|
62
|
+
### 1. 相对路径的基准:工具调用实际所在的目录
|
|
63
|
+
|
|
64
|
+
- 此前:相对路径按**调用方指定的项目根**解析。于是 cwd 是 `<root>/src`、payload 是
|
|
65
|
+
`deep/x.ts` 时,这个路径其实指向 `<root>/src/deep/x.ts` —— **落在 `src/` 里、应当被拒**,
|
|
66
|
+
而门禁**放行**了。逃逸是**静默**的。
|
|
67
|
+
- 现在:相对路径按**工具调用实际所在的目录**解析。来源有两条,先用前者:
|
|
68
|
+
payload **顶层**的 `cwd`(IDE 给了就用),否则**门禁进程自己的工作目录**。
|
|
69
|
+
**族仍然相对调用方指定的项目根**比;**绝对路径规则不变**;**嵌在 git 仓库里的项目仍然判自己**。
|
|
70
|
+
- **代价(有意接受,写在这里以免看起来像疏漏)**:基准选错会误拒邻近目录的文件。而回退基准是
|
|
71
|
+
门禁进程的 cwd —— 正常调用里 hook 就跑在工具调用的目录上,所以那条回退**就是**工具调用的目录。
|
|
72
|
+
|
|
73
|
+
### 2. 两个逃逸
|
|
74
|
+
|
|
75
|
+
- ⚠️ **`.sh` 兄弟实现的 `./` 剥离**:它把 `.//deep/x.ts` 剥成前导 `/`,于是被当成**绝对路径**、
|
|
76
|
+
**永不相对化** ⇒ 落在所有族之外 ⇒ **放行**。而那个文件在 `<root>/src/deep/x.ts`,**在 `src/` 里**。
|
|
77
|
+
**同一个文件的 10 种拼法里 6 种,两套实现的判决相反** —— 而**两套实现各自的单测都是绿的**。
|
|
78
|
+
现在:"是不是绝对路径"按**未经剥离的原样拼写**判定。
|
|
79
|
+
- ⚠️ **Node 命令信任了一个不是目录的 payload `cwd`**:payload 说了一个不存在、或者不是目录、
|
|
80
|
+
或者相对的地方,路径因此解析到项目之外,"按拼写回退"那条老路又被走到 ⇒ **逃逸重新打开**。
|
|
81
|
+
现在 payload `cwd` **只有**在"**绝对路径 + 存在的目录 + 在指名的项目之内**"三件事同时成立时才被采信;
|
|
82
|
+
否则用**门禁进程自己的工作目录**。⇒ **修复不依赖 payload 的 `cwd` 存在或正确**。
|
|
83
|
+
|
|
84
|
+
### 3. 必须保持的性质(逐条复验)
|
|
85
|
+
|
|
86
|
+
- **fail-open 策略不变**:payload 判不了时**仍然放行**,stderr 上仍留 `PEAKS_CODE_GATE_UNDECIDABLE`。
|
|
87
|
+
- **六个族的成员不变**:`HARD_BLOCKED_PATH_FAMILIES` 与 `ALLOW_LISTED_PATH_PATTERNS` **零行改动**。
|
|
88
|
+
- **fast lane 仍然打开这些族**:租约是 `peaks-race-code` 时,`src/` 的编辑仍然**放行**。
|
|
89
|
+
- **门禁没有被削弱**:本次**多拒**了原先放行的(那正是逃逸),方向是**收紧**而不是放宽。
|
|
90
|
+
|
|
91
|
+
### 4. 留下的东西(写清楚,免得看起来像漏了)
|
|
92
|
+
|
|
93
|
+
- **落在项目之外的相对路径**仍按"拼写相对项目根"读 ⇒ **不会放宽**门禁:它会拒一个拼得像族、
|
|
94
|
+
而文件其实没落在那里的路径 —— **误拒只是碍事,误放才是漏洞**。
|
|
95
|
+
- **一个残留**:payload `cwd` 不可用**且**门禁进程不在工具调用的目录里时,路径会按错误的树解析,
|
|
96
|
+
项目内的文件**可能**被放行。**改动前同样放行**(它按项目根解析)⇒ **残留,不是回归**;
|
|
97
|
+
而门禁本来就不装在那个位置。**这个形状与 §2.13 的根 `dist/` 轴同源**:拿一个不属于自己的基准去解析。
|
|
98
|
+
- **任何 IDE 报的顶层 `cwd` 至今未实测**(PATH 上的 `claude.exe` 是个 546 KB 启动器,没有 payload
|
|
99
|
+
字符串;本机装的 `@anthropic-ai/claude-code` 二进制里读到的 hook-input 形状是**一次 grep 的转述**,
|
|
100
|
+
QA **没能复现**它)⇒ 所以修复**不依赖**它,回退路径自己扛得住。
|
|
101
|
+
|
|
102
|
+
### 5. QA 独立复核
|
|
103
|
+
|
|
104
|
+
**PASS**(8 条验收标准)。两轮 RD、两轮 QA:QA 第一轮 `return-to-rd`,给的两条缺陷都被独立复现过。
|
|
105
|
+
证据:
|
|
106
|
+
|
|
107
|
+
- 与**改动前**的代码逐行对照 **72 组(action + reason):0 处差异**;
|
|
108
|
+
- 两套实现在 **29 种拼法上 29/29 一致**,**65 行族矩阵 65/65 都拒**;
|
|
109
|
+
- **10 种拼法 0 分歧**(改动前 6 种分歧);
|
|
110
|
+
- **六种不可用的 `cwd` + 完全没有 `cwd`:全部拒**。
|
|
111
|
+
|
|
3
112
|
## 4.1.15 — 2026-10-22(门禁剩下的三种写法也不再决定判定)
|
|
4
113
|
|
|
5
114
|
**版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次是**纯修复**:
|
|
@@ -22,6 +22,7 @@
|
|
|
22
22
|
import { resolve } from 'node:path';
|
|
23
23
|
import { addJsonOption, printResult } from '../cli-helpers.js';
|
|
24
24
|
import { decideGateAction, extractFilePath, isGatedTool } from '../../services/hooks/pre-tool-code-gate.js';
|
|
25
|
+
import { resolveToolCallBaseDir } from '../../services/hooks/hook-payload-cwd.js';
|
|
25
26
|
import { hasLeaseForCaller, resolveActiveSkillForCaller } from '../../services/audit/enforcers/active-skill-resolver.js';
|
|
26
27
|
import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
|
|
27
28
|
import { pluckObject, pluckString } from '../../services/ide/hook-translator.js';
|
|
@@ -60,6 +61,16 @@ function resolveDriver(projectRoot, payload) {
|
|
|
60
61
|
return null;
|
|
61
62
|
return resolveActiveSkillForCaller(projectRoot, { callerId }).skill;
|
|
62
63
|
}
|
|
64
|
+
/**
|
|
65
|
+
* The directory the tool call runs in: the payload's own `cwd` when it names
|
|
66
|
+
* a usable one, and the gate process's own working directory otherwise — the
|
|
67
|
+
* directory the harness ran the hook in. Neither source is guessed: the
|
|
68
|
+
* payload is read at its top level, and the process's own directory is a fact
|
|
69
|
+
* about this process.
|
|
70
|
+
*/
|
|
71
|
+
function resolveToolCallDir(payload, projectRoot) {
|
|
72
|
+
return resolveToolCallBaseDir(payload, projectRoot, process.cwd());
|
|
73
|
+
}
|
|
63
74
|
/**
|
|
64
75
|
* The marker the gate leaves on stderr when it could not decide.
|
|
65
76
|
*
|
|
@@ -172,9 +183,13 @@ export function registerCodeGateCommand(program, io) {
|
|
|
172
183
|
// is judged against ITSELF, not against the git root above it. One file
|
|
173
184
|
// must not get two verdicts from two spellings, and a project that is not
|
|
174
185
|
// the git root is exactly where the two would differ.
|
|
186
|
+
// The tool call's OWN directory is a third fact: it is the base a
|
|
187
|
+
// relative path is read against.
|
|
175
188
|
const namedRoot = resolve(opts.project ?? process.cwd());
|
|
176
189
|
const canonicalRoot = resolveCanonicalProjectRoot(namedRoot);
|
|
177
|
-
const
|
|
190
|
+
const driver = resolveDriver(canonicalRoot, parsed);
|
|
191
|
+
const toolCwd = resolveToolCallDir(parsed, namedRoot);
|
|
192
|
+
const verdict = decideGateAction(tool, input, driver, { projectRoot: namedRoot, toolCwd });
|
|
178
193
|
if (opts.dryRun === true) {
|
|
179
194
|
printDryRunVerdict(io, opts.json === true, { tool, input, verdict, undecidable });
|
|
180
195
|
return;
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The ONE spelling-independent form of a target path, and the roots a
|
|
3
|
+
* verdict is taken against.
|
|
4
|
+
*
|
|
5
|
+
* The deny families are project-relative prefixes (`src/`, `tests/unit/`, …),
|
|
6
|
+
* so how the incoming path happens to be SPELLED must not decide the verdict:
|
|
7
|
+
* `src/x.ts`, `./src/x.ts` and the absolute spelling of that same file are one
|
|
8
|
+
* file and must get one verdict. Without this, the same edit is denied in one
|
|
9
|
+
* spelling and allowed in another — and the allow is the one that happens.
|
|
10
|
+
*
|
|
11
|
+
* A RELATIVE path is read against the directory the tool call RUNS IN, not
|
|
12
|
+
* against the project root: the file the call writes is the one that
|
|
13
|
+
* directory names, and the two differ whenever the call runs in a
|
|
14
|
+
* subdirectory. The file it lands in is then judged by where it sits inside
|
|
15
|
+
* the project, so the families still name this project's directories.
|
|
16
|
+
*
|
|
17
|
+
* Two readings of one file are offered: the LEXICAL one (`normalizeGatePath`)
|
|
18
|
+
* and the CANONICAL one (`canonicalGatePath`). One directory can be named
|
|
19
|
+
* two ways, and the caller takes the STRICTEST of the two — a wrongly
|
|
20
|
+
* allowed edit is a hole in the gate, a wrongly refused one is only an
|
|
21
|
+
* inconvenience.
|
|
22
|
+
*
|
|
23
|
+
* The arithmetic lives apart from the decision on purpose: the decision is
|
|
24
|
+
* the gate's rule, and this is the path arithmetic it rests on. The file the
|
|
25
|
+
* decision sits in was at its size cap, and the arithmetic needs room.
|
|
26
|
+
*/
|
|
27
|
+
/**
|
|
28
|
+
* The roots a verdict is taken against: the project the caller named, and
|
|
29
|
+
* the directory the tool call runs in. A bare string is the project root
|
|
30
|
+
* alone — the shape every earlier call used.
|
|
31
|
+
*/
|
|
32
|
+
export interface GateRootPair {
|
|
33
|
+
readonly projectRoot?: string | null;
|
|
34
|
+
readonly toolCwd?: string | null;
|
|
35
|
+
}
|
|
36
|
+
/** The roots, in either of the two spellings. */
|
|
37
|
+
export type GateRoots = string | null | GateRootPair;
|
|
38
|
+
/**
|
|
39
|
+
* The one form of a target path the families are written in.
|
|
40
|
+
*
|
|
41
|
+
* - separators fold to `/` (a Windows payload spells `src\x.ts`)
|
|
42
|
+
* - a leading `./` is dropped
|
|
43
|
+
* - a `..` segment is resolved
|
|
44
|
+
* - an ABSOLUTE path inside `projectRoot` becomes project-relative
|
|
45
|
+
* - an absolute path OUTSIDE `projectRoot` stays absolute: the families name
|
|
46
|
+
* THIS project's directories, and a path in another repository is another
|
|
47
|
+
* project's business. That is also what the gate already did with every
|
|
48
|
+
* absolute path, so it is not a widening.
|
|
49
|
+
* - with no `projectRoot` an absolute path cannot be made relative and is
|
|
50
|
+
* left as it is
|
|
51
|
+
*
|
|
52
|
+
* A RELATIVE path is read against `toolCwd` — the directory the tool call
|
|
53
|
+
* runs in — and the file it lands in is judged by where it sits inside the
|
|
54
|
+
* project. A path that lands OUTSIDE the project keeps the older reading,
|
|
55
|
+
* the spelling read against the project root, which never widens the gate:
|
|
56
|
+
* it refuses a spelled family the file itself never reached.
|
|
57
|
+
*
|
|
58
|
+
* "Inside" and "outside" are asked LEXICALLY first and CANONICALLY second
|
|
59
|
+
* (see `relativizeInsideRoot`), so two spellings of one directory reach one
|
|
60
|
+
* verdict.
|
|
61
|
+
*
|
|
62
|
+
* This is the LEXICAL reading. The CANONICAL reading — the file named by the
|
|
63
|
+
* directory it really sits in — is a separate question, asked by
|
|
64
|
+
* `canonicalGatePath`.
|
|
65
|
+
*/
|
|
66
|
+
export declare function normalizeGatePath(filePath: string, projectRoot?: string | null, toolCwd?: string | null): string;
|
|
67
|
+
/** The roots, whichever of the two spellings the caller used. */
|
|
68
|
+
export declare function rootPair(roots: GateRoots | undefined): GateRootPair;
|
|
69
|
+
/**
|
|
70
|
+
* The CANONICAL project-relative form of a target path: the file the call
|
|
71
|
+
* really touches, named by the directory it REALLY sits in.
|
|
72
|
+
*
|
|
73
|
+
* The lexical form says how the path is WRITTEN; this one says where the
|
|
74
|
+
* file IS. The two differ whenever a directory is named two ways — a
|
|
75
|
+
* symlink, a junction, macOS's `/var` → `/private/var` — and the difference
|
|
76
|
+
* is what a symlinked BASE inside the project looks like: the call runs in
|
|
77
|
+
* `link/`, the file is in `src/`, and the lexical form says `link/x.ts`
|
|
78
|
+
* (no family) while this one says `src/x.ts` (a family).
|
|
79
|
+
*
|
|
80
|
+
* The two sides are compared as they are CANONICALLY spelled, so the answer
|
|
81
|
+
* is the directory the file is in and not the spelling the caller used to
|
|
82
|
+
* reach it. The LEXICAL-first-then-canonical retry belongs to the other
|
|
83
|
+
* reading (`relativizeInsideRoot`), which needs it because a lexical answer
|
|
84
|
+
* can be a statement about the SPELLING rather than about the directory.
|
|
85
|
+
*
|
|
86
|
+
* `null` when the file is outside the project: the project has no name for
|
|
87
|
+
* it, and the spelling-anchored reading the caller already holds is the one
|
|
88
|
+
* that applies. `null` also when there is no project root at all, for the
|
|
89
|
+
* same reason — a path cannot be made relative to nothing.
|
|
90
|
+
*/
|
|
91
|
+
export declare function canonicalGatePath(filePath: string, projectRoot?: string | null, toolCwd?: string | null): string | null;
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The ONE spelling-independent form of a target path, and the roots a
|
|
3
|
+
* verdict is taken against.
|
|
4
|
+
*
|
|
5
|
+
* The deny families are project-relative prefixes (`src/`, `tests/unit/`, …),
|
|
6
|
+
* so how the incoming path happens to be SPELLED must not decide the verdict:
|
|
7
|
+
* `src/x.ts`, `./src/x.ts` and the absolute spelling of that same file are one
|
|
8
|
+
* file and must get one verdict. Without this, the same edit is denied in one
|
|
9
|
+
* spelling and allowed in another — and the allow is the one that happens.
|
|
10
|
+
*
|
|
11
|
+
* A RELATIVE path is read against the directory the tool call RUNS IN, not
|
|
12
|
+
* against the project root: the file the call writes is the one that
|
|
13
|
+
* directory names, and the two differ whenever the call runs in a
|
|
14
|
+
* subdirectory. The file it lands in is then judged by where it sits inside
|
|
15
|
+
* the project, so the families still name this project's directories.
|
|
16
|
+
*
|
|
17
|
+
* Two readings of one file are offered: the LEXICAL one (`normalizeGatePath`)
|
|
18
|
+
* and the CANONICAL one (`canonicalGatePath`). One directory can be named
|
|
19
|
+
* two ways, and the caller takes the STRICTEST of the two — a wrongly
|
|
20
|
+
* allowed edit is a hole in the gate, a wrongly refused one is only an
|
|
21
|
+
* inconvenience.
|
|
22
|
+
*
|
|
23
|
+
* The arithmetic lives apart from the decision on purpose: the decision is
|
|
24
|
+
* the gate's rule, and this is the path arithmetic it rests on. The file the
|
|
25
|
+
* decision sits in was at its size cap, and the arithmetic needs room.
|
|
26
|
+
*/
|
|
27
|
+
import { isAbsolute, relative, resolve } from 'node:path';
|
|
28
|
+
import { normalizePath, stablePath } from '../../shared/path-utils.js';
|
|
29
|
+
/** The directory a path is resolved against, or `null` when there is none. */
|
|
30
|
+
function resolvedDirectory(value) {
|
|
31
|
+
return typeof value === 'string' && value.length > 0 ? resolve(value) : null;
|
|
32
|
+
}
|
|
33
|
+
/** Drop every leading `./` segment: `./src/x.ts` and `src/x.ts` are one path. */
|
|
34
|
+
function stripLeadingDotSegments(path) {
|
|
35
|
+
let out = path;
|
|
36
|
+
while (out.startsWith('./'))
|
|
37
|
+
out = out.slice(2);
|
|
38
|
+
return out;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Collapse the `.` and `..` segments of a RELATIVE path, lexically.
|
|
42
|
+
*
|
|
43
|
+
* The base directory does not enter the answer for a path that stays inside
|
|
44
|
+
* it: a `..` cancels the segment before it, for every base. A `..` that would
|
|
45
|
+
* leave the base is KEPT, so the result still reads as "outside", and a path
|
|
46
|
+
* outside the project belongs to no family.
|
|
47
|
+
*/
|
|
48
|
+
function collapseRelativeDotSegments(path) {
|
|
49
|
+
const out = [];
|
|
50
|
+
for (const segment of path.split('/')) {
|
|
51
|
+
if (segment === '' || segment === '.')
|
|
52
|
+
continue;
|
|
53
|
+
if (segment === '..') {
|
|
54
|
+
const last = out.length > 0 ? out[out.length - 1] : null;
|
|
55
|
+
if (last !== null && last !== '..')
|
|
56
|
+
out.pop();
|
|
57
|
+
else
|
|
58
|
+
out.push('..');
|
|
59
|
+
continue;
|
|
60
|
+
}
|
|
61
|
+
out.push(segment);
|
|
62
|
+
}
|
|
63
|
+
return out.join('/');
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* The path of `target` relative to `root`, compared LEXICALLY: `null` when
|
|
67
|
+
* `target` is not inside `root` — it is outside the root, or it is the root.
|
|
68
|
+
*/
|
|
69
|
+
function relativizeLexically(target, root) {
|
|
70
|
+
const relativePath = normalizePath(relative(root, target));
|
|
71
|
+
if (relativePath.length === 0)
|
|
72
|
+
return null;
|
|
73
|
+
if (relativePath.startsWith('..') || isAbsolute(relativePath))
|
|
74
|
+
return null;
|
|
75
|
+
return stripLeadingDotSegments(relativePath);
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* The path of `target` relative to `root`, when `target` is INSIDE `root`;
|
|
79
|
+
* `null` when it is not — the target is outside the root, or it is the root.
|
|
80
|
+
*
|
|
81
|
+
* The answer is LEXICAL first: the two sides are compared as they are
|
|
82
|
+
* written, so the common case costs no syscall. When the lexical answer is
|
|
83
|
+
* "outside", the question is asked again with the CANONICAL spelling of both
|
|
84
|
+
* sides, because one directory can be named two ways — a symlink, a junction,
|
|
85
|
+
* macOS's `/var` → `/private/var` — and then the lexical answer is a
|
|
86
|
+
* statement about the SPELLING, not about the directory the file is in. The
|
|
87
|
+
* retry can only turn "outside" into "inside", so it can only tighten the
|
|
88
|
+
* gate; whenever the lexical answer says "inside", that answer stands.
|
|
89
|
+
*
|
|
90
|
+
* The canonical answer is relativized against the CANONICAL root, because
|
|
91
|
+
* the project-relative spelling it produces is what the deny families are
|
|
92
|
+
* matched against.
|
|
93
|
+
*/
|
|
94
|
+
function relativizeInsideRoot(target, root) {
|
|
95
|
+
const lexical = relativizeLexically(target, root);
|
|
96
|
+
if (lexical !== null)
|
|
97
|
+
return lexical;
|
|
98
|
+
return relativizeLexically(stablePath(target), stablePath(root));
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* The one form of a target path the families are written in.
|
|
102
|
+
*
|
|
103
|
+
* - separators fold to `/` (a Windows payload spells `src\x.ts`)
|
|
104
|
+
* - a leading `./` is dropped
|
|
105
|
+
* - a `..` segment is resolved
|
|
106
|
+
* - an ABSOLUTE path inside `projectRoot` becomes project-relative
|
|
107
|
+
* - an absolute path OUTSIDE `projectRoot` stays absolute: the families name
|
|
108
|
+
* THIS project's directories, and a path in another repository is another
|
|
109
|
+
* project's business. That is also what the gate already did with every
|
|
110
|
+
* absolute path, so it is not a widening.
|
|
111
|
+
* - with no `projectRoot` an absolute path cannot be made relative and is
|
|
112
|
+
* left as it is
|
|
113
|
+
*
|
|
114
|
+
* A RELATIVE path is read against `toolCwd` — the directory the tool call
|
|
115
|
+
* runs in — and the file it lands in is judged by where it sits inside the
|
|
116
|
+
* project. A path that lands OUTSIDE the project keeps the older reading,
|
|
117
|
+
* the spelling read against the project root, which never widens the gate:
|
|
118
|
+
* it refuses a spelled family the file itself never reached.
|
|
119
|
+
*
|
|
120
|
+
* "Inside" and "outside" are asked LEXICALLY first and CANONICALLY second
|
|
121
|
+
* (see `relativizeInsideRoot`), so two spellings of one directory reach one
|
|
122
|
+
* verdict.
|
|
123
|
+
*
|
|
124
|
+
* This is the LEXICAL reading. The CANONICAL reading — the file named by the
|
|
125
|
+
* directory it really sits in — is a separate question, asked by
|
|
126
|
+
* `canonicalGatePath`.
|
|
127
|
+
*/
|
|
128
|
+
export function normalizeGatePath(filePath, projectRoot, toolCwd) {
|
|
129
|
+
if (filePath.length === 0)
|
|
130
|
+
return '';
|
|
131
|
+
const slashed = normalizePath(filePath);
|
|
132
|
+
const root = resolvedDirectory(projectRoot);
|
|
133
|
+
if (root === null) {
|
|
134
|
+
return isAbsolute(slashed)
|
|
135
|
+
? slashed
|
|
136
|
+
: collapseRelativeDotSegments(stripLeadingDotSegments(slashed));
|
|
137
|
+
}
|
|
138
|
+
if (isAbsolute(slashed)) {
|
|
139
|
+
return relativizeInsideRoot(resolve(slashed), root) ?? slashed;
|
|
140
|
+
}
|
|
141
|
+
// The file the call will really touch: the relative path read against the
|
|
142
|
+
// tool call's own directory, then judged by where it lands in the project.
|
|
143
|
+
const base = resolvedDirectory(toolCwd) ?? root;
|
|
144
|
+
const inside = relativizeInsideRoot(resolve(base, slashed), root);
|
|
145
|
+
if (inside !== null)
|
|
146
|
+
return inside;
|
|
147
|
+
// The file is outside the project: the project reads the spelling instead.
|
|
148
|
+
const spelled = resolve(root, slashed);
|
|
149
|
+
return relativizeInsideRoot(spelled, root) ?? normalizePath(spelled);
|
|
150
|
+
}
|
|
151
|
+
/** The roots, whichever of the two spellings the caller used. */
|
|
152
|
+
export function rootPair(roots) {
|
|
153
|
+
if (roots === null || roots === undefined)
|
|
154
|
+
return { projectRoot: null };
|
|
155
|
+
if (typeof roots === 'string')
|
|
156
|
+
return { projectRoot: roots };
|
|
157
|
+
return roots;
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* The CANONICAL project-relative form of a target path: the file the call
|
|
161
|
+
* really touches, named by the directory it REALLY sits in.
|
|
162
|
+
*
|
|
163
|
+
* The lexical form says how the path is WRITTEN; this one says where the
|
|
164
|
+
* file IS. The two differ whenever a directory is named two ways — a
|
|
165
|
+
* symlink, a junction, macOS's `/var` → `/private/var` — and the difference
|
|
166
|
+
* is what a symlinked BASE inside the project looks like: the call runs in
|
|
167
|
+
* `link/`, the file is in `src/`, and the lexical form says `link/x.ts`
|
|
168
|
+
* (no family) while this one says `src/x.ts` (a family).
|
|
169
|
+
*
|
|
170
|
+
* The two sides are compared as they are CANONICALLY spelled, so the answer
|
|
171
|
+
* is the directory the file is in and not the spelling the caller used to
|
|
172
|
+
* reach it. The LEXICAL-first-then-canonical retry belongs to the other
|
|
173
|
+
* reading (`relativizeInsideRoot`), which needs it because a lexical answer
|
|
174
|
+
* can be a statement about the SPELLING rather than about the directory.
|
|
175
|
+
*
|
|
176
|
+
* `null` when the file is outside the project: the project has no name for
|
|
177
|
+
* it, and the spelling-anchored reading the caller already holds is the one
|
|
178
|
+
* that applies. `null` also when there is no project root at all, for the
|
|
179
|
+
* same reason — a path cannot be made relative to nothing.
|
|
180
|
+
*/
|
|
181
|
+
export function canonicalGatePath(filePath, projectRoot, toolCwd) {
|
|
182
|
+
if (filePath.length === 0)
|
|
183
|
+
return null;
|
|
184
|
+
const slashed = normalizePath(filePath);
|
|
185
|
+
const root = resolvedDirectory(projectRoot);
|
|
186
|
+
if (root === null)
|
|
187
|
+
return null;
|
|
188
|
+
const base = resolvedDirectory(toolCwd) ?? root;
|
|
189
|
+
const target = isAbsolute(slashed) ? resolve(slashed) : resolve(base, slashed);
|
|
190
|
+
return relativizeLexically(stablePath(target), stablePath(root));
|
|
191
|
+
}
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The tool call's own directory, read from a hook payload.
|
|
3
|
+
*
|
|
4
|
+
* A relative target path belongs to the directory the tool call RUNS in: the
|
|
5
|
+
* file a call writes is the one that directory names, not the one the project
|
|
6
|
+
* root would name. The gate needs that directory to say which file a payload
|
|
7
|
+
* really points at, and the payload is where a harness states it.
|
|
8
|
+
*
|
|
9
|
+
* The read is deliberately narrow — one key, at the top level, holding a
|
|
10
|
+
* string. A `cwd` nested inside the tool's own arguments is an ARGUMENT the
|
|
11
|
+
* tool was handed, not the directory the call runs in, so only the top-level
|
|
12
|
+
* key counts.
|
|
13
|
+
*
|
|
14
|
+
* The absence of the key is not an error: the caller then uses the process's
|
|
15
|
+
* own working directory, which is the same directory whenever the harness runs
|
|
16
|
+
* the hook where the tool call runs.
|
|
17
|
+
*/
|
|
18
|
+
export declare function readToolCallCwd(payload: Readonly<Record<string, unknown>>): string | null;
|
|
19
|
+
/**
|
|
20
|
+
* The directory a relative target path is read against.
|
|
21
|
+
*
|
|
22
|
+
* The payload's own `cwd` is the base only when it is a USABLE one: an
|
|
23
|
+
* absolute path naming an existing directory inside the project the caller
|
|
24
|
+
* named. A `cwd` that is missing, relative, names a file, names a directory
|
|
25
|
+
* that is not there, or names a directory outside the project is not a
|
|
26
|
+
* directory this project can judge the file against — and a base that is not
|
|
27
|
+
* the call's own directory resolves the path against the wrong tree, which is
|
|
28
|
+
* how an edit into a hard-blocked family slipped through.
|
|
29
|
+
*
|
|
30
|
+
* The rule ASSUMES the tool call runs inside the named project, which is
|
|
31
|
+
* where the gate is installed. When it does not, the payload `cwd` is
|
|
32
|
+
* rejected and the path is read against the gate's own working directory
|
|
33
|
+
* instead — a different tree — and the error is one-directional: a file that
|
|
34
|
+
* lies outside every family can be denied. It is never the other way round,
|
|
35
|
+
* and that is the trade the gate makes everywhere else: a wrongly allowed
|
|
36
|
+
* edit is a hole, a wrongly refused one is an inconvenience.
|
|
37
|
+
*
|
|
38
|
+
* The fallback is the gate process's own working directory: that is where the
|
|
39
|
+
* hook runs, and in the normal invocation it IS the tool call's directory.
|
|
40
|
+
* The gate does not fail closed here — it uses the best base it has, and a
|
|
41
|
+
* file that lands outside the project is judged by its spelling, which never
|
|
42
|
+
* widens the gate.
|
|
43
|
+
*/
|
|
44
|
+
export declare function resolveToolCallBaseDir(payload: Readonly<Record<string, unknown>>, projectRoot: string, fallback: string): string;
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The tool call's own directory, read from a hook payload.
|
|
3
|
+
*
|
|
4
|
+
* A relative target path belongs to the directory the tool call RUNS in: the
|
|
5
|
+
* file a call writes is the one that directory names, not the one the project
|
|
6
|
+
* root would name. The gate needs that directory to say which file a payload
|
|
7
|
+
* really points at, and the payload is where a harness states it.
|
|
8
|
+
*
|
|
9
|
+
* The read is deliberately narrow — one key, at the top level, holding a
|
|
10
|
+
* string. A `cwd` nested inside the tool's own arguments is an ARGUMENT the
|
|
11
|
+
* tool was handed, not the directory the call runs in, so only the top-level
|
|
12
|
+
* key counts.
|
|
13
|
+
*
|
|
14
|
+
* The absence of the key is not an error: the caller then uses the process's
|
|
15
|
+
* own working directory, which is the same directory whenever the harness runs
|
|
16
|
+
* the hook where the tool call runs.
|
|
17
|
+
*/
|
|
18
|
+
import { statSync } from 'node:fs';
|
|
19
|
+
import { isAbsolute, relative, resolve } from 'node:path';
|
|
20
|
+
import { normalizePath, stablePath } from '../../shared/path-utils.js';
|
|
21
|
+
export function readToolCallCwd(payload) {
|
|
22
|
+
const cwd = payload['cwd'];
|
|
23
|
+
if (typeof cwd !== 'string')
|
|
24
|
+
return null;
|
|
25
|
+
const trimmed = cwd.trim();
|
|
26
|
+
return trimmed.length > 0 ? trimmed : null;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Does `dir` name a directory that exists?
|
|
30
|
+
*
|
|
31
|
+
* A path that is not there, or that names a file, is not a directory a tool
|
|
32
|
+
* call can run in, and the gate cannot resolve a relative path against it.
|
|
33
|
+
* The read fails CLOSED on a path it cannot stat: an unreadable directory is
|
|
34
|
+
* not a usable base.
|
|
35
|
+
*/
|
|
36
|
+
function isExistingDirectory(dir) {
|
|
37
|
+
try {
|
|
38
|
+
return statSync(dir, { throwIfNoEntry: false })?.isDirectory() === true;
|
|
39
|
+
}
|
|
40
|
+
catch {
|
|
41
|
+
return false;
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Is `dir` the project root itself, or a directory inside it? Compared
|
|
46
|
+
* LEXICALLY: the two are compared as they are written.
|
|
47
|
+
*/
|
|
48
|
+
function isInsideLexically(root, dir) {
|
|
49
|
+
const rel = normalizePath(relative(resolve(root), resolve(dir)));
|
|
50
|
+
if (rel.length === 0)
|
|
51
|
+
return true;
|
|
52
|
+
if (rel === '..' || rel.startsWith('../'))
|
|
53
|
+
return false;
|
|
54
|
+
return !isAbsolute(rel);
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Is `dir` the project root itself, or a directory inside it?
|
|
58
|
+
*
|
|
59
|
+
* The check is LEXICAL first, like the path arithmetic it feeds: a symlink
|
|
60
|
+
* inside the project that points outside it passes here. A base outside the
|
|
61
|
+
* project resolves the path against a tree the families do not name, so the
|
|
62
|
+
* file it lands in cannot be judged by where it sits in the project — which
|
|
63
|
+
* is the invariant the gate is built on.
|
|
64
|
+
*
|
|
65
|
+
* When the lexical answer says "outside", the question is asked again with the
|
|
66
|
+
* CANONICAL spelling of both sides, because one directory can be named two
|
|
67
|
+
* ways — a symlink, a junction, macOS's `/var` → `/private/var` — and then
|
|
68
|
+
* the lexical answer is a statement about the SPELLING, not about the
|
|
69
|
+
* directory. The retry can only turn "outside" into "inside", so the base it
|
|
70
|
+
* accepts is one that really is inside the project.
|
|
71
|
+
*/
|
|
72
|
+
function isInsideProject(root, dir) {
|
|
73
|
+
if (isInsideLexically(root, dir))
|
|
74
|
+
return true;
|
|
75
|
+
return isInsideLexically(stablePath(root), stablePath(dir));
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* The directory a relative target path is read against.
|
|
79
|
+
*
|
|
80
|
+
* The payload's own `cwd` is the base only when it is a USABLE one: an
|
|
81
|
+
* absolute path naming an existing directory inside the project the caller
|
|
82
|
+
* named. A `cwd` that is missing, relative, names a file, names a directory
|
|
83
|
+
* that is not there, or names a directory outside the project is not a
|
|
84
|
+
* directory this project can judge the file against — and a base that is not
|
|
85
|
+
* the call's own directory resolves the path against the wrong tree, which is
|
|
86
|
+
* how an edit into a hard-blocked family slipped through.
|
|
87
|
+
*
|
|
88
|
+
* The rule ASSUMES the tool call runs inside the named project, which is
|
|
89
|
+
* where the gate is installed. When it does not, the payload `cwd` is
|
|
90
|
+
* rejected and the path is read against the gate's own working directory
|
|
91
|
+
* instead — a different tree — and the error is one-directional: a file that
|
|
92
|
+
* lies outside every family can be denied. It is never the other way round,
|
|
93
|
+
* and that is the trade the gate makes everywhere else: a wrongly allowed
|
|
94
|
+
* edit is a hole, a wrongly refused one is an inconvenience.
|
|
95
|
+
*
|
|
96
|
+
* The fallback is the gate process's own working directory: that is where the
|
|
97
|
+
* hook runs, and in the normal invocation it IS the tool call's directory.
|
|
98
|
+
* The gate does not fail closed here — it uses the best base it has, and a
|
|
99
|
+
* file that lands outside the project is judged by its spelling, which never
|
|
100
|
+
* widens the gate.
|
|
101
|
+
*/
|
|
102
|
+
export function resolveToolCallBaseDir(payload, projectRoot, fallback) {
|
|
103
|
+
const cwd = readToolCallCwd(payload);
|
|
104
|
+
if (cwd === null)
|
|
105
|
+
return fallback;
|
|
106
|
+
if (!isAbsolute(cwd))
|
|
107
|
+
return fallback;
|
|
108
|
+
if (!isExistingDirectory(cwd))
|
|
109
|
+
return fallback;
|
|
110
|
+
if (!isInsideProject(projectRoot, cwd))
|
|
111
|
+
return fallback;
|
|
112
|
+
return cwd;
|
|
113
|
+
}
|
|
@@ -18,6 +18,9 @@
|
|
|
18
18
|
* logic, usable from any non-Node harness. Both share the same
|
|
19
19
|
* hard-blocked + allow-listed path families.
|
|
20
20
|
*/
|
|
21
|
+
import { normalizeGatePath, type GateRoots } from './gate-path-normalize.js';
|
|
22
|
+
export { normalizeGatePath };
|
|
23
|
+
export type { GateRoots };
|
|
21
24
|
export type GateToolName = 'Edit' | 'Write' | 'MultiEdit' | string;
|
|
22
25
|
export type GatePathKey = 'file_path' | 'path' | 'notebook_path';
|
|
23
26
|
export interface GateInput {
|
|
@@ -42,37 +45,6 @@ export type GateVerdict = {
|
|
|
42
45
|
};
|
|
43
46
|
/** Pull the target file path from `input.file_path | input.path | input.notebook_path`. */
|
|
44
47
|
export declare function extractFilePath(input: Readonly<Record<string, unknown>>): string;
|
|
45
|
-
/**
|
|
46
|
-
* The ONE spelling-independent form of a target path.
|
|
47
|
-
*
|
|
48
|
-
* The deny families are project-relative prefixes (`src/`, `tests/unit/`, …),
|
|
49
|
-
* so how the incoming path happens to be SPELLED must not decide the verdict:
|
|
50
|
-
* `src/x.ts`, `./src/x.ts` and the absolute spelling of that same file are one
|
|
51
|
-
* file and must get one verdict. Without this, the same edit is denied in one
|
|
52
|
-
* spelling and allowed in another — and the allow is the one that happens.
|
|
53
|
-
*
|
|
54
|
-
* - separators fold to `/` (a Windows payload spells `src\x.ts`)
|
|
55
|
-
* - a leading `./` is dropped
|
|
56
|
-
* - a `..` segment is resolved
|
|
57
|
-
* - an ABSOLUTE path inside `projectRoot` becomes project-relative
|
|
58
|
-
* - an absolute path OUTSIDE `projectRoot` stays absolute: the families name
|
|
59
|
-
* THIS project's directories, and a path in another repository is another
|
|
60
|
-
* project's business. That is also what the gate already did with every
|
|
61
|
-
* absolute path, so it is not a widening.
|
|
62
|
-
* - with no `projectRoot` an absolute path cannot be made relative and is
|
|
63
|
-
* left as it is
|
|
64
|
-
*
|
|
65
|
-
* The base a `..` is resolved against is the PROJECT ROOT the caller named,
|
|
66
|
-
* and that is a fact about the caller rather than a guess: the IDE invokes
|
|
67
|
-
* `peaks code-gate --project "<the project directory>"`, and the tool call's
|
|
68
|
-
* own working directory is that same project directory. A `..` that resolves
|
|
69
|
-
* OUTSIDE the root names a file outside the project, so it belongs to no
|
|
70
|
-
* family and is allowed - the same rule an absolute path outside the root
|
|
71
|
-
* follows. The trade-off is written down rather than left implicit: a base
|
|
72
|
-
* chosen wrongly would refuse files of a neighbouring directory, and the
|
|
73
|
-
* project root is the one base both the caller and the tool call agree on.
|
|
74
|
-
*/
|
|
75
|
-
export declare function normalizeGatePath(filePath: string, projectRoot?: string | null): string;
|
|
76
48
|
/**
|
|
77
49
|
* Pure decision function. Given the tool name + input object, return
|
|
78
50
|
* the gate verdict. Tolerates malformed payloads (allow).
|
|
@@ -83,12 +55,40 @@ export declare function normalizeGatePath(filePath: string, projectRoot?: string
|
|
|
83
55
|
* hard-blocked families deny. Resolution is the caller's job, so this
|
|
84
56
|
* module keeps no session, lease or filesystem state.
|
|
85
57
|
*
|
|
86
|
-
* `
|
|
87
|
-
*
|
|
88
|
-
*
|
|
89
|
-
*
|
|
90
|
-
*
|
|
91
|
-
*
|
|
92
|
-
*
|
|
58
|
+
* `roots` is where the verdict is taken: the root the deny families are
|
|
59
|
+
* relative to, and the directory the tool call runs in. A bare string is the
|
|
60
|
+
* project root alone, which is how every earlier call spelled it.
|
|
61
|
+
*
|
|
62
|
+
* The project root is what lets an ABSOLUTE path be judged like its relative
|
|
63
|
+
* spelling; without it an absolute path cannot be related to the project and
|
|
64
|
+
* is left alone. It is the project root the CALLER named, not the canonical
|
|
65
|
+
* root above it: a project nested inside a git repository is judged against
|
|
66
|
+
* itself, and the canonical root - where the session and the leases live - is
|
|
67
|
+
* a different question that this parameter does not answer.
|
|
68
|
+
*
|
|
69
|
+
* The tool call's directory is the base a RELATIVE path is read against: the
|
|
70
|
+
* file a call writes is the one that directory names. It does not move the
|
|
71
|
+
* families - those stay relative to the project root - it only says which
|
|
72
|
+
* file the payload points at.
|
|
73
|
+
*
|
|
74
|
+
* THE VERDICT IS THE STRICTEST OF THE TWO READINGS. The path is read
|
|
75
|
+
* LEXICALLY - how it is written - and, when that reading has not already
|
|
76
|
+
* denied the file, CANONICALLY - where the file really is. A directory can
|
|
77
|
+
* be named two ways, and the difference is what a symlinked base looks like:
|
|
78
|
+
* a call that runs in `link/` and writes `deep/x.ts` lands in `src/deep/x.ts`
|
|
79
|
+
* when `link` points at `src`, and the lexical reading says `link/deep/x.ts`
|
|
80
|
+
* - no family at all. §18.1 rules that the verdict depends on WHICH
|
|
81
|
+
* DIRECTORY the file is in, not on how the path is written.
|
|
82
|
+
*
|
|
83
|
+
* Strictest, and not "canonical wins": making the canonical reading
|
|
84
|
+
* authoritative would WIDEN the gate in a layout this repository supports.
|
|
85
|
+
* When `src` is a symlink to `shared/src`, the lexical reading is
|
|
86
|
+
* `src/x.ts` (a family) and the canonical one is `shared/src/x.ts` (not
|
|
87
|
+
* one), and the file the gate denies today must stay denied. The tie-breaker
|
|
88
|
+
* is the repository's own: a wrongly ALLOWED edit is a hole, a wrongly
|
|
89
|
+
* REFUSED one is only an inconvenience. So a file reached through a
|
|
90
|
+
* directory NAMED `src` stays refused even when it really sits in `docs/` -
|
|
91
|
+
* the spelling is what the path says in this project's terms, and the gate
|
|
92
|
+
* refuses it rather than resolve it.
|
|
93
93
|
*/
|
|
94
|
-
export declare function decideGateAction(tool: GateToolName, input: Readonly<Record<string, unknown>>, driver?: string | null,
|
|
94
|
+
export declare function decideGateAction(tool: GateToolName, input: Readonly<Record<string, unknown>>, driver?: string | null, roots?: GateRoots): GateVerdict;
|
|
@@ -18,8 +18,8 @@
|
|
|
18
18
|
* logic, usable from any non-Node harness. Both share the same
|
|
19
19
|
* hard-blocked + allow-listed path families.
|
|
20
20
|
*/
|
|
21
|
-
import {
|
|
22
|
-
|
|
21
|
+
import { canonicalGatePath, normalizeGatePath, rootPair } from './gate-path-normalize.js';
|
|
22
|
+
export { normalizeGatePath };
|
|
23
23
|
/** Hard-blocked path families — orchestrator MUST NOT Edit/Write these. */
|
|
24
24
|
export const HARD_BLOCKED_PATH_FAMILIES = [
|
|
25
25
|
'src/',
|
|
@@ -91,98 +91,39 @@ function matchesAny(path, families) {
|
|
|
91
91
|
}
|
|
92
92
|
return null;
|
|
93
93
|
}
|
|
94
|
-
/** Drop every leading `./` segment: `./src/x.ts` and `src/x.ts` are one path. */
|
|
95
|
-
function stripLeadingDotSegments(path) {
|
|
96
|
-
let out = path;
|
|
97
|
-
while (out.startsWith('./'))
|
|
98
|
-
out = out.slice(2);
|
|
99
|
-
return out;
|
|
100
|
-
}
|
|
101
94
|
/**
|
|
102
|
-
*
|
|
95
|
+
* The hard-blocked family a reading of the path names, or `null` when it
|
|
96
|
+
* names none.
|
|
103
97
|
*
|
|
104
|
-
* The
|
|
105
|
-
*
|
|
106
|
-
*
|
|
107
|
-
*
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
for (const segment of path.split('/')) {
|
|
112
|
-
if (segment === '' || segment === '.')
|
|
113
|
-
continue;
|
|
114
|
-
if (segment === '..') {
|
|
115
|
-
const last = out.length > 0 ? out[out.length - 1] : null;
|
|
116
|
-
if (last !== null && last !== '..')
|
|
117
|
-
out.pop();
|
|
118
|
-
else
|
|
119
|
-
out.push('..');
|
|
120
|
-
continue;
|
|
121
|
-
}
|
|
122
|
-
out.push(segment);
|
|
123
|
-
}
|
|
124
|
-
return out.join('/');
|
|
125
|
-
}
|
|
126
|
-
/**
|
|
127
|
-
* The path of `target` relative to `root`, when `target` is INSIDE `root`;
|
|
128
|
-
* `null` when it is not — the target is outside the root, or it is the root.
|
|
98
|
+
* The ALLOW-LIST is read FIRST, for each reading on its own: a path the
|
|
99
|
+
* project allows is allowed, and a reading that names an allow-listed
|
|
100
|
+
* directory does not become a deny because ANOTHER reading names a family.
|
|
101
|
+
* That is what keeps `src/x.md` allowed, exactly as it was before.
|
|
102
|
+
*
|
|
103
|
+
* The family comparison folds CASE, because every family name is written in
|
|
104
|
+
* lower case and the filesystem holding the file may not be.
|
|
129
105
|
*/
|
|
130
|
-
function
|
|
131
|
-
|
|
132
|
-
if (relativePath.length === 0)
|
|
106
|
+
function hardBlockedFamilyOf(reading) {
|
|
107
|
+
if (matchesAny(reading, ALLOW_LISTED_PATH_PATTERNS) !== null)
|
|
133
108
|
return null;
|
|
134
|
-
|
|
135
|
-
return null;
|
|
136
|
-
return stripLeadingDotSegments(relativePath);
|
|
109
|
+
return matchesAny(reading, HARD_BLOCKED_PATH_FAMILIES);
|
|
137
110
|
}
|
|
138
111
|
/**
|
|
139
|
-
* The
|
|
140
|
-
*
|
|
141
|
-
* The deny families are project-relative prefixes (`src/`, `tests/unit/`, …),
|
|
142
|
-
* so how the incoming path happens to be SPELLED must not decide the verdict:
|
|
143
|
-
* `src/x.ts`, `./src/x.ts` and the absolute spelling of that same file are one
|
|
144
|
-
* file and must get one verdict. Without this, the same edit is denied in one
|
|
145
|
-
* spelling and allowed in another — and the allow is the one that happens.
|
|
112
|
+
* The verdict for a file that one reading of the path placed in a
|
|
113
|
+
* hard-blocked family.
|
|
146
114
|
*
|
|
147
|
-
*
|
|
148
|
-
*
|
|
149
|
-
*
|
|
150
|
-
* - an ABSOLUTE path inside `projectRoot` becomes project-relative
|
|
151
|
-
* - an absolute path OUTSIDE `projectRoot` stays absolute: the families name
|
|
152
|
-
* THIS project's directories, and a path in another repository is another
|
|
153
|
-
* project's business. That is also what the gate already did with every
|
|
154
|
-
* absolute path, so it is not a widening.
|
|
155
|
-
* - with no `projectRoot` an absolute path cannot be made relative and is
|
|
156
|
-
* left as it is
|
|
157
|
-
*
|
|
158
|
-
* The base a `..` is resolved against is the PROJECT ROOT the caller named,
|
|
159
|
-
* and that is a fact about the caller rather than a guess: the IDE invokes
|
|
160
|
-
* `peaks code-gate --project "<the project directory>"`, and the tool call's
|
|
161
|
-
* own working directory is that same project directory. A `..` that resolves
|
|
162
|
-
* OUTSIDE the root names a file outside the project, so it belongs to no
|
|
163
|
-
* family and is allowed - the same rule an absolute path outside the root
|
|
164
|
-
* follows. The trade-off is written down rather than left implicit: a base
|
|
165
|
-
* chosen wrongly would refuse files of a neighbouring directory, and the
|
|
166
|
-
* project root is the one base both the caller and the tool call agree on.
|
|
115
|
+
* A driver that is not the fast lane falls through to the same deny a
|
|
116
|
+
* two-argument call produces, so an unresolvable identity can never become a
|
|
117
|
+
* silent pass.
|
|
167
118
|
*/
|
|
168
|
-
|
|
169
|
-
if (
|
|
170
|
-
return '';
|
|
171
|
-
const slashed = normalizePath(filePath);
|
|
172
|
-
const root = typeof projectRoot === 'string' && projectRoot.length > 0 ? resolve(projectRoot) : null;
|
|
173
|
-
if (isAbsolute(slashed)) {
|
|
174
|
-
if (root === null)
|
|
175
|
-
return slashed;
|
|
176
|
-
return relativizeInsideRoot(resolve(slashed), root) ?? slashed;
|
|
119
|
+
function denyVerdict(family, requestedPath, driver) {
|
|
120
|
+
if (driver === FAST_LANE_DRIVER) {
|
|
121
|
+
return { action: 'allow' };
|
|
177
122
|
}
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
if (inside !== null)
|
|
183
|
-
return inside;
|
|
184
|
-
// The `..` left the project root: the target is another project's file.
|
|
185
|
-
return normalizePath(resolved);
|
|
123
|
+
const reason = `${family} (orchestrator's hard-blocked path family)`;
|
|
124
|
+
const message = `PEAKS_CODE_PROHIBITED_DIRECT_EDIT: ${requestedPath} matches hard-blocked path family ${reason}; ` +
|
|
125
|
+
`orchestrator MUST NOT Edit/Write these directly. Use: peaks sub-agent dispatch rd --prompt '<your task>' --request-id <rid> --project . --batch-id <uuid>`;
|
|
126
|
+
return { action: 'deny', filePath: requestedPath, reason, message };
|
|
186
127
|
}
|
|
187
128
|
/**
|
|
188
129
|
* Pure decision function. Given the tool name + input object, return
|
|
@@ -194,15 +135,43 @@ export function normalizeGatePath(filePath, projectRoot) {
|
|
|
194
135
|
* hard-blocked families deny. Resolution is the caller's job, so this
|
|
195
136
|
* module keeps no session, lease or filesystem state.
|
|
196
137
|
*
|
|
197
|
-
* `
|
|
198
|
-
*
|
|
199
|
-
*
|
|
200
|
-
*
|
|
201
|
-
*
|
|
202
|
-
*
|
|
203
|
-
*
|
|
138
|
+
* `roots` is where the verdict is taken: the root the deny families are
|
|
139
|
+
* relative to, and the directory the tool call runs in. A bare string is the
|
|
140
|
+
* project root alone, which is how every earlier call spelled it.
|
|
141
|
+
*
|
|
142
|
+
* The project root is what lets an ABSOLUTE path be judged like its relative
|
|
143
|
+
* spelling; without it an absolute path cannot be related to the project and
|
|
144
|
+
* is left alone. It is the project root the CALLER named, not the canonical
|
|
145
|
+
* root above it: a project nested inside a git repository is judged against
|
|
146
|
+
* itself, and the canonical root - where the session and the leases live - is
|
|
147
|
+
* a different question that this parameter does not answer.
|
|
148
|
+
*
|
|
149
|
+
* The tool call's directory is the base a RELATIVE path is read against: the
|
|
150
|
+
* file a call writes is the one that directory names. It does not move the
|
|
151
|
+
* families - those stay relative to the project root - it only says which
|
|
152
|
+
* file the payload points at.
|
|
153
|
+
*
|
|
154
|
+
* THE VERDICT IS THE STRICTEST OF THE TWO READINGS. The path is read
|
|
155
|
+
* LEXICALLY - how it is written - and, when that reading has not already
|
|
156
|
+
* denied the file, CANONICALLY - where the file really is. A directory can
|
|
157
|
+
* be named two ways, and the difference is what a symlinked base looks like:
|
|
158
|
+
* a call that runs in `link/` and writes `deep/x.ts` lands in `src/deep/x.ts`
|
|
159
|
+
* when `link` points at `src`, and the lexical reading says `link/deep/x.ts`
|
|
160
|
+
* - no family at all. §18.1 rules that the verdict depends on WHICH
|
|
161
|
+
* DIRECTORY the file is in, not on how the path is written.
|
|
162
|
+
*
|
|
163
|
+
* Strictest, and not "canonical wins": making the canonical reading
|
|
164
|
+
* authoritative would WIDEN the gate in a layout this repository supports.
|
|
165
|
+
* When `src` is a symlink to `shared/src`, the lexical reading is
|
|
166
|
+
* `src/x.ts` (a family) and the canonical one is `shared/src/x.ts` (not
|
|
167
|
+
* one), and the file the gate denies today must stay denied. The tie-breaker
|
|
168
|
+
* is the repository's own: a wrongly ALLOWED edit is a hole, a wrongly
|
|
169
|
+
* REFUSED one is only an inconvenience. So a file reached through a
|
|
170
|
+
* directory NAMED `src` stays refused even when it really sits in `docs/` -
|
|
171
|
+
* the spelling is what the path says in this project's terms, and the gate
|
|
172
|
+
* refuses it rather than resolve it.
|
|
204
173
|
*/
|
|
205
|
-
export function decideGateAction(tool, input, driver,
|
|
174
|
+
export function decideGateAction(tool, input, driver, roots) {
|
|
206
175
|
// Only gate Edit / Write / MultiEdit.
|
|
207
176
|
if (!isGatedTool(tool)) {
|
|
208
177
|
return { action: 'allow' };
|
|
@@ -218,26 +187,23 @@ export function decideGateAction(tool, input, driver, projectRoot) {
|
|
|
218
187
|
// names it, so the path is reduced to the project-relative form the
|
|
219
188
|
// families are written in before anything is matched. The verdict still
|
|
220
189
|
// echoes the path the tool actually asked for.
|
|
221
|
-
const
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
}
|
|
227
|
-
// Hard-blocked family check — case-insensitively, because every family name
|
|
228
|
-
// is lower-case and the filesystem holding the file may not be.
|
|
229
|
-
const denyMatch = matchesAny(filePath, HARD_BLOCKED_PATH_FAMILIES);
|
|
190
|
+
const pair = rootPair(roots);
|
|
191
|
+
const filePath = normalizeGatePath(requestedPath, pair.projectRoot, pair.toolCwd);
|
|
192
|
+
// The LEXICAL reading: the allow-list first — it short-circuits any deny,
|
|
193
|
+
// for every driver — and then the hard-blocked families.
|
|
194
|
+
const denyMatch = hardBlockedFamilyOf(filePath);
|
|
230
195
|
if (denyMatch !== null) {
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
196
|
+
return denyVerdict(denyMatch, requestedPath, driver ?? null);
|
|
197
|
+
}
|
|
198
|
+
// The CANONICAL reading, asked only when the lexical one has not already
|
|
199
|
+
// denied the file: it costs two filesystem lookups, and the file it names
|
|
200
|
+
// is the one the lexical reading could not place.
|
|
201
|
+
const canonical = canonicalGatePath(requestedPath, pair.projectRoot, pair.toolCwd);
|
|
202
|
+
if (canonical !== null) {
|
|
203
|
+
const canonicalMatch = hardBlockedFamilyOf(canonical);
|
|
204
|
+
if (canonicalMatch !== null) {
|
|
205
|
+
return denyVerdict(canonicalMatch, requestedPath, driver ?? null);
|
|
236
206
|
}
|
|
237
|
-
const reason = `${denyMatch} (orchestrator's hard-blocked path family)`;
|
|
238
|
-
const message = `PEAKS_CODE_PROHIBITED_DIRECT_EDIT: ${requestedPath} matches hard-blocked path family ${reason}; ` +
|
|
239
|
-
`orchestrator MUST NOT Edit/Write these directly. Use: peaks sub-agent dispatch rd --prompt '<your task>' --request-id <rid> --project . --batch-id <uuid>`;
|
|
240
|
-
return { action: 'deny', filePath: requestedPath, reason, message };
|
|
241
207
|
}
|
|
242
208
|
// Anything not in the deny list → allow (e.g. CHANGELOG, README, top-level files).
|
|
243
209
|
return { action: 'allow' };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "peaks-loop",
|
|
3
|
-
"version": "4.1.
|
|
3
|
+
"version": "4.1.17",
|
|
4
4
|
"description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
|
|
5
5
|
"author": "SquabbyZ",
|
|
6
6
|
"keywords": [
|
|
@@ -129,10 +129,10 @@
|
|
|
129
129
|
"picomatch": "4.0.7",
|
|
130
130
|
"yaml": "^2.9.1",
|
|
131
131
|
"zod": "^4.6.7",
|
|
132
|
-
"peaks-loop-
|
|
133
|
-
"peaks-loop-shared": "0.0.
|
|
134
|
-
"peaks-loop-
|
|
135
|
-
"peaks-loop-
|
|
132
|
+
"peaks-loop-internal-runtime": "0.0.57",
|
|
133
|
+
"peaks-loop-shared": "0.0.106",
|
|
134
|
+
"peaks-loop-shared-channel": "0.0.74",
|
|
135
|
+
"peaks-loop-mut": "0.1.71"
|
|
136
136
|
},
|
|
137
137
|
"devDependencies": {
|
|
138
138
|
"@changesets/cli": "2.31.1",
|