@abelxiaoxing/cadence 2.0.22 → 2.0.23

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.
@@ -0,0 +1,302 @@
1
+ /** Workspace identity and bounded filesystem operations, independent of task records. */
2
+ import { spawnSync } from "node:child_process";
3
+ import { createHash } from "node:crypto";
4
+ import {
5
+ closeSync,
6
+ constants,
7
+ fstatSync,
8
+ lstatSync,
9
+ mkdirSync,
10
+ openSync,
11
+ readSync,
12
+ realpathSync,
13
+ type Stats,
14
+ } from "node:fs";
15
+ import { homedir } from "node:os";
16
+ import {
17
+ dirname,
18
+ isAbsolute,
19
+ join,
20
+ parse,
21
+ relative,
22
+ resolve,
23
+ sep,
24
+ } from "node:path";
25
+ import { object } from "./data-shapes.ts";
26
+ export function parseRecord(data: Buffer): unknown {
27
+ try {
28
+ return JSON.parse(data.toString("utf8"));
29
+ } catch {
30
+ throw new Error("Corrupt JSON state; preserved without reset");
31
+ }
32
+ }
33
+ export function absent(error: unknown): boolean {
34
+ return object(error) && error.code === "ENOENT";
35
+ }
36
+ /** Reject links in every existing ancestor. Missing observation never creates paths.
37
+ * The readonly hook inspects each existing directory synchronously, including
38
+ * the root, before visiting its child. It must not await, mutate or retain state
39
+ * as authority for a later call/effect. Legacy/default traversal is unchanged.
40
+ */
41
+ export function safeDirectory(path: string, create?: boolean): boolean;
42
+ export function safeDirectory(
43
+ path: string,
44
+ create: false,
45
+ inspectExisting: (path: string, stat: Stats) => void,
46
+ ): boolean;
47
+ export function safeDirectory(
48
+ path: string,
49
+ create = false,
50
+ inspectExisting?: (path: string, stat: Stats) => void,
51
+ ): boolean {
52
+ const full = resolve(path);
53
+ const root = parse(full).root;
54
+ if (inspectExisting) {
55
+ const st = lstatSync(root);
56
+ if (!st.isDirectory() || st.isSymbolicLink())
57
+ throw new Error("Unsafe directory");
58
+ inspectExisting(root, st);
59
+ }
60
+ let at = root;
61
+ for (const part of full.slice(root.length).split(sep).filter(Boolean)) {
62
+ at = join(at, part);
63
+ let existing: Stats | undefined;
64
+ try {
65
+ // One no-follow observation per component: a link is never reported as
66
+ // a directory, and the inspection sees this same, latest observation.
67
+ const checked = lstatSync(at);
68
+ if (!checked.isDirectory() || checked.isSymbolicLink())
69
+ throw new Error("Unsafe directory");
70
+ existing = checked;
71
+ } catch (error) {
72
+ if (!absent(error)) throw error;
73
+ if (!create) return false;
74
+ try {
75
+ mkdirSync(at, { mode: 0o700 });
76
+ } catch (mkdirError) {
77
+ if (!object(mkdirError) || mkdirError.code !== "EEXIST")
78
+ throw mkdirError;
79
+ }
80
+ const created = lstatSync(at);
81
+ if (!created.isDirectory() || created.isSymbolicLink())
82
+ throw new Error("Unsafe directory");
83
+ }
84
+ // Outside the ENOENT handler: an inspection refusal is never absence and
85
+ // must not authorize creation, even if its error happens to carry ENOENT.
86
+ if (existing) inspectExisting?.(at, existing);
87
+ }
88
+ return true;
89
+ }
90
+ const transientWindows = new Set(["EPERM", "EACCES", "EBUSY"]);
91
+ /** Windows refuses to replace, remove or recreate a path while another process
92
+ * holds it (a polling reader, antivirus, a delete still pending), which POSIX
93
+ * never does. Retry the same operation briefly; `recheck` reasserts the
94
+ * caller's expected bytes before every retry, so a retry never overwrites a
95
+ * change. Other errors, including EEXIST and ENOENT, keep their meaning. */
96
+ export function retryWindowsFileOperation<T>(
97
+ operation: () => T,
98
+ recheck?: () => void,
99
+ ): T {
100
+ if (process.platform !== "win32") return operation();
101
+ const deadline = performance.now() + 2000;
102
+ for (let delay = 2; ; delay = Math.min(delay * 2, 50)) {
103
+ try {
104
+ return operation();
105
+ } catch (error) {
106
+ if (
107
+ !object(error) ||
108
+ !transientWindows.has(String(error.code)) ||
109
+ performance.now() >= deadline
110
+ )
111
+ throw error;
112
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delay);
113
+ recheck?.();
114
+ }
115
+ }
116
+ }
117
+ /** `packaged` reads the installed package's own files (web assets, Agent
118
+ * profiles). A package manager may hard-link them into its store (Bun's default
119
+ * backend), so a second link is not an alias of workspace or task state; their
120
+ * callers bind content instead. Every other read stays single-link. */
121
+ export function readBounded(
122
+ path: string,
123
+ max: number,
124
+ packaged = false,
125
+ ): Buffer | undefined {
126
+ if (!safeDirectory(dirname(path))) return undefined;
127
+ let fd: number;
128
+ try {
129
+ const st = lstatSync(path);
130
+ if (
131
+ !st.isFile() ||
132
+ st.isSymbolicLink() ||
133
+ (!packaged && st.nlink !== 1) ||
134
+ st.size > max
135
+ )
136
+ throw new Error("Unsafe or oversized file");
137
+ fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
138
+ } catch (error) {
139
+ if (absent(error)) return undefined;
140
+ throw error;
141
+ }
142
+ try {
143
+ const st = fstatSync(fd);
144
+ if (!st.isFile() || (!packaged && st.nlink !== 1) || st.size > max)
145
+ throw new Error("Unsafe or oversized file");
146
+ // Read at most max+1 even if another editor grows the file after stat.
147
+ const buffer = Buffer.alloc(max + 1);
148
+ let size = 0;
149
+ while (size < buffer.length) {
150
+ const n = readSync(fd, buffer, size, buffer.length - size, null);
151
+ if (!n) break;
152
+ size += n;
153
+ }
154
+ if (size > max) throw new Error("Oversized file");
155
+ return buffer.subarray(0, size);
156
+ } finally {
157
+ closeSync(fd);
158
+ }
159
+ }
160
+
161
+ /** Git observations describe the physical cwd, not inherited alternate
162
+ * index/worktree overrides. Root never borrows sudo's original user's trust. */
163
+ export function gitEnvironment(): NodeJS.ProcessEnv {
164
+ const root = process.getuid?.() === 0;
165
+ return {
166
+ ...Object.fromEntries(
167
+ Object.entries(process.env).filter(
168
+ ([name]) => !name.startsWith("GIT_") && !(root && name === "SUDO_UID"),
169
+ ),
170
+ ),
171
+ GIT_OPTIONAL_LOCKS: "0",
172
+ LC_ALL: "C",
173
+ };
174
+ }
175
+ /** Observation is not permission to trust another account's repository.
176
+ * Even with fsmonitor/textconv/ext-diff disabled, status/diff can invoke clean
177
+ * or process filters. Root therefore requires Git's own ownership check, with
178
+ * no safe.directory exceptions (including inherited wildcards). No config is
179
+ * written and ordinary-user trust behavior stays unchanged. */
180
+ export function gitArguments(args: string[]): string[] {
181
+ return process.platform !== "win32" && process.getuid?.() === 0
182
+ ? ["-c", "safe.directory=", "-c", "core.fsmonitor=false", ...args]
183
+ : args;
184
+ }
185
+ export function resolveWorkspace(cwd: string): { root: string; cwd: string } {
186
+ const actual = realpathSync(cwd);
187
+ const result = spawnSync(
188
+ "git",
189
+ gitArguments(["rev-parse", "--show-toplevel"]),
190
+ {
191
+ cwd: actual,
192
+ env: gitEnvironment(),
193
+ encoding: "utf8",
194
+ timeout: 3000,
195
+ maxBuffer: 8192,
196
+ windowsHide: true,
197
+ },
198
+ );
199
+ // Remove only Git's record terminator, not valid whitespace in a path.
200
+ const topLevel = result.stdout?.replace(
201
+ process.platform === "win32" ? /\r?\n$/ : /\n$/,
202
+ "",
203
+ );
204
+ if (result.status === 0 && topLevel)
205
+ return { root: realpathSync(topLevel), cwd: actual };
206
+ if (result.error && !object(result.error))
207
+ throw new Error("Cannot resolve workspace");
208
+ if (result.error && object(result.error) && result.error.code !== "ENOENT")
209
+ throw new Error("Workspace lookup failed");
210
+ // A missing Git executable or a confirmed non-repository is an honest non-Git workspace.
211
+ if (!result.error && !result.stderr.includes("not a git repository"))
212
+ throw new Error("Git workspace lookup refused");
213
+ return { root: actual, cwd: actual };
214
+ }
215
+ export function defaultStateHome(): string {
216
+ const candidate =
217
+ process.platform === "win32"
218
+ ? process.env.LOCALAPPDATA
219
+ : process.env.XDG_STATE_HOME;
220
+ if (candidate && !isAbsolute(candidate))
221
+ throw new Error("State home must be absolute");
222
+ return (
223
+ candidate ??
224
+ join(
225
+ homedir(),
226
+ process.platform === "win32" ? "AppData/Local" : ".local/state",
227
+ )
228
+ );
229
+ }
230
+ /** Resolve ambient aliases, including a missing tail, without creating anything. */
231
+ export function canonicalAmbientRoot(path: string): string {
232
+ const full = resolve(path);
233
+ try {
234
+ return realpathSync(full);
235
+ } catch (error) {
236
+ if (!absent(error)) throw error;
237
+ // A dangling alias is not a missing ambient directory.
238
+ try {
239
+ lstatSync(full);
240
+ throw new Error("Dangling ambient root");
241
+ } catch (statError) {
242
+ if (!absent(statError)) throw statError;
243
+ }
244
+ const parent = dirname(full);
245
+ if (parent === full) throw error;
246
+ return join(canonicalAmbientRoot(parent), full.slice(parent.length));
247
+ }
248
+ }
249
+ export function privateRootFor(
250
+ canonicalRoot: string,
251
+ stateHome: string,
252
+ ): string {
253
+ return join(
254
+ canonicalAmbientRoot(stateHome),
255
+ "cadence-assistant-v1",
256
+ createHash("sha256").update(canonicalRoot).digest("hex"),
257
+ );
258
+ }
259
+ export function contains(root: string, path: string): boolean {
260
+ const within = relative(root, resolve(path));
261
+ return (
262
+ !within ||
263
+ (!within.startsWith(`..${sep}`) && within !== ".." && !isAbsolute(within))
264
+ );
265
+ }
266
+ /** Private history, locks and access material must stay outside the working
267
+ * copy, or change observation, check freshness and review would see them. */
268
+ export function stateHomeInside(
269
+ root: string,
270
+ stateHome = defaultStateHome(),
271
+ ): boolean {
272
+ const canonical = realpathSync(root);
273
+ return contains(canonical, privateRootFor(canonical, stateHome));
274
+ }
275
+ /** Also exclude projects *inside* our reserved private namespace. Root access
276
+ * does not turn private history/coordination into an ordinary engineering tree.
277
+ * Resolves missing tails without creating anything (for explicit project mkdir). */
278
+ export function privateWorkspace(
279
+ requested: string,
280
+ stateHome = defaultStateHome(),
281
+ ): boolean {
282
+ return contains(
283
+ join(canonicalAmbientRoot(stateHome), "cadence-assistant-v1"),
284
+ canonicalAmbientRoot(requested),
285
+ );
286
+ }
287
+ /** A project must be explicit and outside private state. Never choose, create or
288
+ * reconstruct a default workspace. The workbench itself has no project cwd. */
289
+ export function effectiveWorkspace(
290
+ requested: string,
291
+ stateHome?: string,
292
+ _home?: string,
293
+ ): { workspace: string; redirected: boolean } {
294
+ if (
295
+ privateWorkspace(requested, stateHome) ||
296
+ stateHomeInside(resolveWorkspace(requested).root, stateHome)
297
+ )
298
+ throw new Error(
299
+ "Choose a project outside Cadence private state; no default workspace was created",
300
+ );
301
+ return { workspace: requested, redirected: false };
302
+ }