pi-braid 0.44.4 → 0.45.0
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/AGENTS.md +1 -1
- package/CHANGELOG.md +60 -0
- package/README.md +1 -1
- package/TOOLS.md +3 -2
- package/build-info.json +4 -4
- package/dist/extensions/context-management/index.js +5 -0
- package/dist/extensions/core/prompt-builder/tool-guidelines.js +2 -0
- package/dist/extensions/core/run-tool/index.d.ts +58 -0
- package/dist/extensions/core/run-tool/index.js +215 -0
- package/dist/extensions/core/run-tool/run.d.ts +122 -0
- package/dist/extensions/core/run-tool/run.js +394 -0
- package/dist/extensions/enforcement/handlers/register-adherence-meter.d.ts +24 -1
- package/dist/extensions/enforcement/handlers/register-adherence-meter.js +86 -30
- package/dist/extensions/manifest.js +6 -0
- package/dist/lib/tools/tool-families.js +1 -0
- package/dist/lib/tools/workspace-guard.d.ts +70 -0
- package/dist/lib/tools/workspace-guard.js +111 -0
- package/docs/LOCAL_DEV.md +1 -1
- package/package.json +1 -1
- package/src/extensions/context-management/README.md +8 -8
- package/src/extensions/context-management/index.ts +5 -0
- package/src/extensions/core/prompt-builder/tool-guidelines.ts +3 -0
- package/src/extensions/core/run-tool/index.ts +307 -0
- package/src/extensions/core/run-tool/run.ts +503 -0
- package/src/extensions/enforcement/handlers/register-adherence-meter.ts +92 -32
- package/src/extensions/manifest.ts +6 -0
- package/src/lib/tools/tool-families.ts +1 -0
- package/src/lib/tools/workspace-guard.ts +134 -0
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Workspace escape guard for destructive argv.
|
|
3
|
+
*
|
|
4
|
+
* A tool that takes an argv list lets a caller name a path, and a verb that
|
|
5
|
+
* removes or overwrites what it names turns a path typo into data loss. This
|
|
6
|
+
* module answers one question for such a tool: does this argv carry a path
|
|
7
|
+
* argument that resolves outside the workspace root?
|
|
8
|
+
*
|
|
9
|
+
* It is a mechanism, not a policy:
|
|
10
|
+
* - the destructive verb set is the caller's, passed in;
|
|
11
|
+
* - the workspace root and the invocation cwd are the caller's;
|
|
12
|
+
* - nothing here executes, refuses, rewrites or reports. The caller decides
|
|
13
|
+
* what to do with an escape, and its own message names the outcome.
|
|
14
|
+
*
|
|
15
|
+
* Resolution is canonical on both sides. The root and the target's nearest
|
|
16
|
+
* existing ancestor go through realpath, so a symlink that lives inside the
|
|
17
|
+
* workspace and points outside it is caught, while a target that does not exist
|
|
18
|
+
* yet is compared by the canonical path of its parent. A target equal to the
|
|
19
|
+
* root is an escape: removing or rewriting the workspace itself is outside the
|
|
20
|
+
* set of things a single path argument may name.
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
import { existsSync, realpathSync } from "node:fs";
|
|
24
|
+
import { basename, dirname, isAbsolute, resolve, sep } from "node:path";
|
|
25
|
+
|
|
26
|
+
/** One path argument that resolves outside the workspace. */
|
|
27
|
+
export interface WorkspaceEscape {
|
|
28
|
+
/** The program (argv[0]) whose verb the caller marked destructive. */
|
|
29
|
+
verb: string;
|
|
30
|
+
/** The argument as the caller wrote it. */
|
|
31
|
+
argument: string;
|
|
32
|
+
/** The path value read out of the argument (`of=` is read as its right side). */
|
|
33
|
+
path: string;
|
|
34
|
+
/** That path, canonical and absolute. */
|
|
35
|
+
resolved: string;
|
|
36
|
+
/** The workspace root, canonical and absolute. */
|
|
37
|
+
root: string;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** A candidate path value and the argument it was read from. */
|
|
41
|
+
interface Candidate {
|
|
42
|
+
argument: string;
|
|
43
|
+
path: string;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Path values carried by an argv, read conservatively: every element after the
|
|
48
|
+
* program that is not a flag, plus the right side of any `key=value` element
|
|
49
|
+
* (`dd of=/etc/passwd`). A flag's own value (`-o /etc/x`) is not followed by the
|
|
50
|
+
* scanner, which is why the caller keeps destructive verbs to the set whose
|
|
51
|
+
* operands are positional or `key=value`; the guard never guesses at a program's
|
|
52
|
+
* option grammar.
|
|
53
|
+
*/
|
|
54
|
+
export function pathCandidates(argv: readonly string[]): Candidate[] {
|
|
55
|
+
const candidates: Candidate[] = [];
|
|
56
|
+
for (const argument of argv.slice(1)) {
|
|
57
|
+
if (argument === "" || argument === "--" || argument.startsWith("-")) continue;
|
|
58
|
+
const eq = argument.indexOf("=");
|
|
59
|
+
const path = eq >= 0 ? argument.slice(eq + 1) : argument;
|
|
60
|
+
if (path === "") continue;
|
|
61
|
+
candidates.push({ argument, path });
|
|
62
|
+
}
|
|
63
|
+
return candidates;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** Canonical absolute path for a target, whether or not it exists yet. */
|
|
67
|
+
export function canonicalPath(target: string): string {
|
|
68
|
+
let current = resolve(target);
|
|
69
|
+
const missing: string[] = [];
|
|
70
|
+
// realpath the nearest existing ancestor, then re-attach the names that do
|
|
71
|
+
// not exist yet. The loop is bounded by the filesystem's depth: each step
|
|
72
|
+
// removes one segment.
|
|
73
|
+
for (;;) {
|
|
74
|
+
if (existsSync(current)) {
|
|
75
|
+
let real: string;
|
|
76
|
+
try {
|
|
77
|
+
real = realpathSync(current);
|
|
78
|
+
} catch {
|
|
79
|
+
// A path that exists but cannot be resolved (a race, a permission
|
|
80
|
+
// boundary) is compared as written rather than skipped: a guard that
|
|
81
|
+
// ignores what it cannot resolve is a guard that can be bypassed by
|
|
82
|
+
// making the target unreadable.
|
|
83
|
+
real = current;
|
|
84
|
+
}
|
|
85
|
+
return missing.length ? resolve(real, ...missing.reverse()) : real;
|
|
86
|
+
}
|
|
87
|
+
const parent = dirname(current);
|
|
88
|
+
if (parent === current) return resolve(current, ...missing.reverse());
|
|
89
|
+
missing.push(basename(current));
|
|
90
|
+
current = parent;
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** Whether `target` is strictly below `root` after both are canonicalized. */
|
|
95
|
+
export function isBelow(root: string, target: string): boolean {
|
|
96
|
+
const canonicalRoot = canonicalPath(root);
|
|
97
|
+
const canonicalTarget = canonicalPath(target);
|
|
98
|
+
return canonicalTarget.startsWith(canonicalRoot + sep);
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* The first path argument, in argv order, that resolves outside the workspace.
|
|
103
|
+
* Null when the program's verb is not in `verbs`, when no path argument escapes,
|
|
104
|
+
* or when the argv carries no path argument at all.
|
|
105
|
+
*
|
|
106
|
+
* `cwd` is the directory the argv runs in, so relative operands are read the
|
|
107
|
+
* way the program will read them. `workspaceRoot` is the boundary, which need
|
|
108
|
+
* not be `cwd`: a call may run in a subdirectory and still be bounded by the
|
|
109
|
+
* session's working directory.
|
|
110
|
+
*/
|
|
111
|
+
export function findWorkspaceEscape(options: {
|
|
112
|
+
verbs: ReadonlySet<string>;
|
|
113
|
+
argv: readonly string[];
|
|
114
|
+
cwd: string;
|
|
115
|
+
workspaceRoot: string;
|
|
116
|
+
}): WorkspaceEscape | null {
|
|
117
|
+
const { verbs, argv, cwd, workspaceRoot } = options;
|
|
118
|
+
const program = argv[0] ?? "";
|
|
119
|
+
const verb = basename(program);
|
|
120
|
+
if (!verbs.has(verb)) return null;
|
|
121
|
+
const root = canonicalPath(workspaceRoot);
|
|
122
|
+
for (const candidate of pathCandidates(argv)) {
|
|
123
|
+
const target = isAbsolute(candidate.path) ? candidate.path : resolve(cwd, candidate.path);
|
|
124
|
+
if (isBelow(root, target)) continue;
|
|
125
|
+
return {
|
|
126
|
+
verb,
|
|
127
|
+
argument: candidate.argument,
|
|
128
|
+
path: candidate.path,
|
|
129
|
+
resolved: canonicalPath(target),
|
|
130
|
+
root,
|
|
131
|
+
};
|
|
132
|
+
}
|
|
133
|
+
return null;
|
|
134
|
+
}
|