@kealthas-dev/opencode-path-guard 0.0.0-stage → 1.1.5
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/README.md +26 -2
- package/package.json +20 -4
- package/path-guard.ts +93 -0
package/README.md
CHANGED
|
@@ -1,3 +1,27 @@
|
|
|
1
|
-
#
|
|
1
|
+
# path-guard
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Two guards on the path arguments of opencode's `read`, `grep` and `glob` tools. Why these are hooks and not prompt lines: [docs/design-philosophy.md](../../docs/design-philosophy.md). Where the ideas come from: [docs/multi-agent-prior-art.md](../../docs/multi-agent-prior-art.md).
|
|
4
|
+
|
|
5
|
+
- Package: `@kealthas-dev/opencode-path-guard`, source `path-guard.ts`. Published; commented out in `deploy/opencode.json.example` as opt-in (see `SETUP.md` step 5).
|
|
6
|
+
|
|
7
|
+
## Guessed absolute paths
|
|
8
|
+
|
|
9
|
+
A small model often writes an absolute path with directory segments dropped, `/home/u/Work/Project` for `/home/u/Work/Parent/Child/Project`. The call then fails, and for a path outside the workspace it first stops on an `external_directory` permission prompt, which a headless `opencode run` auto-rejects.
|
|
10
|
+
|
|
11
|
+
When the argument is an absolute path that does not exist, is not already inside the workspace and has no `.` or `..` segment, the plugin looks for the longest tail of the workspace path (always ending in its last directory) that occurs in the guess. If that tail occurs exactly once and the workspace joined with everything after it exists, the argument is rewritten to that path. Otherwise nothing changes. It never invents a path and never trims the rest of the guess, so a guess whose remainder does not exist is left alone. Only a plain `ENOENT` counts as missing; a permission error says nothing about whether the path exists.
|
|
12
|
+
|
|
13
|
+
The logic is a pure function that takes the `path` module as a parameter, so the Windows flavor (backslashes, forward slashes, case-insensitive names), which is the deployment target, is tested on Linux.
|
|
14
|
+
|
|
15
|
+
## Missing search path
|
|
16
|
+
|
|
17
|
+
Checked against opencode 1.18.33: `grep` with a `path` that does not exist does not fail, it ignores the path and searches the whole workspace, and answers as if it had searched the one asked for. `glob` with such a path fails with the bare `ripgrep execution failed`. Both are replaced by an error naming the resolved path. `read` needs nothing, since it already reports `File not found: <path>`.
|
|
18
|
+
|
|
19
|
+
## Notes
|
|
20
|
+
|
|
21
|
+
- The hooks mutate `output.args` in place; reassigning `output.args` would be discarded by opencode.
|
|
22
|
+
- Other tools, and calls without a path argument, are untouched.
|
|
23
|
+
- Out of scope: Git-Bash style paths (`/c/Users/...`) on Windows, which are handled for `edit` by [`gitbash-edit-path-fix`](../gitbash-edit-path-fix/README.md).
|
|
24
|
+
|
|
25
|
+
## Tests
|
|
26
|
+
|
|
27
|
+
`tests/unit/path-guard.test.mjs`: the pure function for posix and win32 paths (dropped parents, the root, doubts that must return nothing), and the hook against a real temporary directory (rewrite in place, paths and tools left alone, the missing-search-path error). `tests/integration/guard-plugins.test.mjs` runs it in a real opencode against a fake model: a guessed path is repaired before the read runs (which also shows that mutating `output.args` in place takes effect), and a `grep` with a missing path gets the error.
|
package/package.json
CHANGED
|
@@ -1,6 +1,22 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kealthas-dev/opencode-path-guard",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"description": "
|
|
6
|
-
|
|
3
|
+
"version": "1.1.5",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"description": "path-guard.ts opencode plugin: repairs an absolute path a model guessed with directory segments dropped, and gives grep/glob a clear error for a search path that does not exist. Written in TypeScript against @opencode-ai/plugin's Plugin type (type-only). Independently installable - not bundled with the other plugins.",
|
|
6
|
+
"main": "path-guard.ts",
|
|
7
|
+
"files": [
|
|
8
|
+
"path-guard.ts"
|
|
9
|
+
],
|
|
10
|
+
"publishConfig": {
|
|
11
|
+
"access": "public"
|
|
12
|
+
},
|
|
13
|
+
"repository": {
|
|
14
|
+
"type": "git",
|
|
15
|
+
"url": "https://github.com/Keal-thas/opencode-toolkit.git",
|
|
16
|
+
"directory": "plugins/path-guard"
|
|
17
|
+
},
|
|
18
|
+
"devDependencies": {
|
|
19
|
+
"@opencode-ai/plugin": "^1.0.0",
|
|
20
|
+
"@types/node": "^22.0.0"
|
|
21
|
+
}
|
|
22
|
+
}
|
package/path-guard.ts
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import { statSync } from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
import type { Plugin } from "@opencode-ai/plugin";
|
|
4
|
+
|
|
5
|
+
// Two guards on the path arguments of opencode's file-reading tools. Both run
|
|
6
|
+
// in tool.execute.before, mutating output.args in place (reassigning
|
|
7
|
+
// output.args would be silently discarded, see docs/lessons-learned.md).
|
|
8
|
+
//
|
|
9
|
+
// 1. A small model often writes an absolute path with directory segments
|
|
10
|
+
// dropped (/home/u/Work/Project for /home/u/Work/Parent/Child/Project). The
|
|
11
|
+
// call then fails, or for a path outside the workspace stops on a permission
|
|
12
|
+
// prompt. If exactly one existing path inside the workspace explains the
|
|
13
|
+
// guess, use it.
|
|
14
|
+
// 2. grep silently ignores a search path that does not exist and searches the
|
|
15
|
+
// whole workspace instead, and glob fails with a bare "ripgrep execution
|
|
16
|
+
// failed". Both are replaced by an error naming the missing path.
|
|
17
|
+
|
|
18
|
+
// Argument names that carry a path, per tool. `read` is only repaired: it already reports a missing file clearly.
|
|
19
|
+
const PATH_ARGS: Record<string, string[]> = { read: ["filePath"], glob: ["path"], grep: ["path"] };
|
|
20
|
+
const SEARCH_TOOLS = new Set(["glob", "grep"]);
|
|
21
|
+
|
|
22
|
+
type PathOps = Pick<typeof path, "isAbsolute" | "resolve" | "join" | "sep">;
|
|
23
|
+
|
|
24
|
+
const defaultExists = (p: string) => {
|
|
25
|
+
try {
|
|
26
|
+
statSync(p);
|
|
27
|
+
return true;
|
|
28
|
+
} catch {
|
|
29
|
+
return false;
|
|
30
|
+
}
|
|
31
|
+
};
|
|
32
|
+
|
|
33
|
+
// Only a plain ENOENT counts as missing: a permission or I/O error says nothing about whether the path exists.
|
|
34
|
+
const isMissing = (p: string) => {
|
|
35
|
+
try {
|
|
36
|
+
statSync(p);
|
|
37
|
+
return false;
|
|
38
|
+
} catch (e) {
|
|
39
|
+
return (e as NodeJS.ErrnoException).code === "ENOENT";
|
|
40
|
+
}
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
// Map a guessed absolute path onto the workspace, or return null. Not exported: opencode loads every export of a plugin module as a plugin (a function export is called with the plugin input, any other export fails the load), so the unit test appends an export to a copy of this file instead. The anchor is the
|
|
44
|
+
// longest tail of the workspace path (ending in its last segment) that occurs in the
|
|
45
|
+
// guess; it must occur exactly once, and the whole remainder of the guess after it
|
|
46
|
+
// must exist under the workspace. Nothing is ever trimmed or invented: any doubt
|
|
47
|
+
// returns null and the call proceeds as the model wrote it.
|
|
48
|
+
function rescuePath(raw: string, workspace: string, ops: PathOps = path, exists: (p: string) => boolean = defaultExists): string | null {
|
|
49
|
+
const sep = ops.sep;
|
|
50
|
+
const root = ops.resolve(workspace);
|
|
51
|
+
const resolved = ops.resolve(raw);
|
|
52
|
+
if (resolved === root || resolved.startsWith(root + sep)) return null; // already inside the workspace: a real absence, not a guess
|
|
53
|
+
// Windows treats / as a separator too, and compares names case-insensitively.
|
|
54
|
+
const guess = (sep === "/" ? raw : raw.replaceAll("/", sep)).split(sep).filter(Boolean);
|
|
55
|
+
if (guess.some((s) => s === "." || s === "..")) return null;
|
|
56
|
+
const fold = sep === "/" ? (s: string) => s : (s: string) => s.toLowerCase();
|
|
57
|
+
const rootSegs = root.split(sep).filter(Boolean);
|
|
58
|
+
|
|
59
|
+
for (let len = rootSegs.length; len >= 1; len--) {
|
|
60
|
+
const anchor = rootSegs.slice(rootSegs.length - len).map(fold);
|
|
61
|
+
const at: number[] = [];
|
|
62
|
+
for (let i = 0; i + len <= guess.length; i++) {
|
|
63
|
+
if (anchor.every((seg, j) => fold(guess[i + j]) === seg)) at.push(i);
|
|
64
|
+
}
|
|
65
|
+
if (at.length === 0) continue; // a shorter anchor may still match
|
|
66
|
+
if (at.length > 1) return null; // ambiguous
|
|
67
|
+
const candidate = [root, ...guess.slice(at[0] + len)].join(sep);
|
|
68
|
+
return exists(candidate) ? candidate : null;
|
|
69
|
+
}
|
|
70
|
+
return null;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
export const PathGuard: Plugin = async ({ directory }) => ({
|
|
74
|
+
"tool.execute.before": async (input, output) => {
|
|
75
|
+
const keys = PATH_ARGS[input.tool];
|
|
76
|
+
const args = output.args as Record<string, unknown> | undefined;
|
|
77
|
+
if (!keys || !args) return;
|
|
78
|
+
for (const key of keys) {
|
|
79
|
+
const given = args[key];
|
|
80
|
+
if (typeof given !== "string" || given === "") continue;
|
|
81
|
+
let target: string = given;
|
|
82
|
+
if (path.isAbsolute(target) && isMissing(target)) {
|
|
83
|
+
const rescued = rescuePath(target, directory);
|
|
84
|
+
if (rescued) args[key] = target = rescued;
|
|
85
|
+
}
|
|
86
|
+
if (SEARCH_TOOLS.has(input.tool) && isMissing(path.resolve(directory, target))) {
|
|
87
|
+
throw new Error(
|
|
88
|
+
`${input.tool}: the search path does not exist: ${path.resolve(directory, target)}. Check the path, or leave it out to search the workspace (${directory}).`,
|
|
89
|
+
);
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
},
|
|
93
|
+
});
|