Repository navigation
Expand file tree
/
Copy pathpaths.ts
More file actions
242 lines (208 loc) · 25 KB
/
Copy pathpaths.ts
File metadata and controls
242 lines (208 loc) · 25 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
/** Path normalization and join safety. Ports `_normalize_path` / `normalize_path` from `paths.py` plus the colon rejection at the heart of `safe_join`. No imports from other local modules. */
import * as fs from 'node:fs'
import * as path from 'node:path'
import { neutralizeOutsideFences, neutralizeSpokenMarkers } from './injection_scan.js'
/** A UNC or device path (`\\server\share`, `//server/share`, `\\?\`, `\\.\`). Stat'ing one can dial out. Lives here, at the bottom of the import graph, because two layers need it and neither may import the other: `vscode_path_gate.ts` decides whether a pre-approval hook may touch a path at all, and `path_containment.ts` has to refuse a symlink whose target escapes onto a share before its own walk stats the next segment. */
export function isUncOrDevicePath(p: string): boolean {
return /^[\\/]{2}/.test(p)
}
// Compiled once: matches a WSL mount path /mnt/<drive>/rest. The `s` flag makes `.` match newlines so paths containing newline bytes still normalize fully. Exported so project.ts's cross-shell canonicalization reuses this exact pattern instead of maintaining a second, flag-divergent copy.
export const WSL_PATH_RE = /^\/mnt\/([a-zA-Z])\/(.*)$/s
// Compiled once: matches a Git Bash / MSYS mount path /<drive>/rest, with the trailing /rest optional so a bare drive root (`/c`) still matches and becomes `c:/` instead of falling through unrewritten. The `s` flag makes `.` match newlines so paths containing newline bytes still normalize fully. Exported so project.ts's cross-shell canonicalization reuses this exact pattern instead of maintaining a second, mandatory-trailing-slash copy.
export const MSYS_PATH_RE = /^\/([a-zA-Z])(\/.*)?$/s
// Matches a UNC path's host+share segment once backslashes have already been converted to forward slashes (e.g. `\\FileServer\Dev\...` -> `//FileServer/Dev/...`). Host and share names are case-insensitive on Windows, exactly like a drive letter, so two differently-cased references to the same network share must normalize to the same string. Only the host/share segment is captured; everything beyond it is left untouched, matching how the drive-letter fold below only lowercases the drive letter itself.
const UNC_HOST_SHARE_RE = /^\/\/([^/]+)\/([^/]+)/
// Cheap heuristic for a Windows 8.3 short-name path segment (e.g. `JOHNDO~1.ACM`): a tilde followed by a digit. Used to skip the syscall in expandShortPath for the overwhelming majority of paths that don't contain one.
const SHORT_NAME_RE = /~\d/
// Expands a Windows 8.3 short-name path segment to its long form. `%TEMP%`/`%USERPROFILE%` can be pinned to the short 8.3 form on Windows, so every `os.tmpdir()`-based path -- including every test fixture directory `fs.mkdtempSync` creates -- inherits that short form and a child process spawned with it as `cwd` preserves it verbatim, while `git` always normalizes its own output paths to long form; without this expansion the same physical directory normalizes to two different index keys depending on whether the path came from `process.cwd()` or from `git diff --name-only`, so writes and lookups silently disagree. `fs.realpathSync` (the POSIX-style implementation) does NOT resolve 8.3 short names on Windows; only `fs.realpathSync.native` does. Guarded so it's a no-op off Windows, a no-op when the path doesn't look like it contains a short name, and falls back to the original string if the path doesn't exist yet (e.g. a file about to be created) or the native call throws for any other reason.
export function expandShortPath(p: string): string {
if (process.platform !== 'win32') return p
const segments = p.split('/')
// Find the last path segment that looks like an 8.3 short name and resolve only the prefix through it via the filesystem, leaving everything after it byte-for-byte as-is: fs.realpathSync.native returns on-disk casing regardless of query casing, so running it over the *whole* path would silently case-fold every segment, collapsing two deliberately differently-cased paths (see tests/session.test.ts's case-sensitive-FS control case) into one.
let lastShortIdx = -1
for (let i = 0; i < segments.length; i++) {
if (SHORT_NAME_RE.test(segments[i] as string)) lastShortIdx = i
}
if (lastShortIdx === -1) return p
const prefix = segments.slice(0, lastShortIdx + 1).join('/')
const suffix = segments.slice(lastShortIdx + 1).join('/')
try {
const expandedPrefix = fs.realpathSync.native(prefix).replace(/\\/g, '/')
return suffix ? `${expandedPrefix}/${suffix}` : expandedPrefix
} catch {
// Fall back unchanged: the short-named directory itself doesn't exist (unusual, but possible for a path built purely as a string in a test).
return p
}
}
/** Lowercases a Windows drive-letter prefix (e.g. "C:" -> "c:") or a UNC path's host+share segment (e.g. "//FileServer/Dev/..." -> "//fileserver/dev/...") so path comparisons/cache keys agree regardless of input case. For a drive letter, only touches position 0 when it's an ASCII uppercase letter immediately followed by ':' — anything else (already-lowercase, digit, symbol, non-ASCII) is left untouched. Shared by normalizePath (paths.ts) and canonicalize (project.ts) so the rule can't drift between the two call sites again. */
export function lowercaseDriveLetter(s: string): string {
if (s.length >= 2 && s[1] === ':') {
const c = s[0] as string
if (/^[A-Z]$/.test(c)) {
return c.toLowerCase() + s.slice(1)
}
}
const uncMatch = UNC_HOST_SHARE_RE.exec(s)
if (uncMatch) {
const full = uncMatch[0] as string
const host = uncMatch[1] as string
const share = uncMatch[2] as string
return `//${host.toLowerCase()}/${share.toLowerCase()}${s.slice(full.length)}`
}
return s
}
/** Normalize a file path to a canonical string form for cross-platform keys. Transformations, in order (matches util.py normalize_path): 1. Replace all backslashes with forward slashes. 2. On Windows only, convert WSL paths `/mnt/<drive>/rest` to Windows form `<drive>:/rest`, collapsing duplicate leading slashes in `rest`; elsewhere a mount path is the real path and stays as it is. 3. Lowercase an uppercase drive-letter prefix (`C:` -> `c:`). This is a string canonicalizer, not a filesystem canonicalizer: symlinks, junctions, and case-insensitive NTFS paths are not resolved. */
// Matches a `\\?\UNC\` extended-length UNC prefix, case-insensitively.
const EXTENDED_UNC_PREFIX_RE = /^\\\\\?\\UNC\\/i
// Matches a plain `\\?\` extended-length-path prefix.
const EXTENDED_PREFIX_RE = /^\\\\\?\\/
/** Convert backslashes to forward slashes, then rewrite a WSL (`/mnt/c/rest`) or Git Bash/MSYS (`/c/rest`) mount path into Windows drive-letter form (`c:/rest`). Extracted so {@link resolveIndexPath} can apply it *before* `path.resolve` rather than only after. A mount-form path is rooted but carries no drive letter, so `path.win32.resolve` treats it as drive-relative and grafts the current drive onto it -- `/c/proj/a.ts` resolves to `c:/c/proj/a.ts`, an index key no writer ever produces, so the lookup silently misses. Running the rewrite after resolve cannot recover from that: the drive letter is already there and the mount pattern no longer matches. Both forms are Windows-only. `/c/foo` is a real path on Linux and macOS, and so is `/mnt/c/foo`: it is where WSL mounts the C: drive, and the key has to be a path the host can open, because the indexer, the worker and every read command open the key itself. Folding it to `c:/foo` there made Linux resolve the key as a relative path, so nothing under a drive mount was indexed or readable on WSL. canonicalize (path_containment.ts) and expandSpecPath (spec_path.ts) apply the same gate. */
export function shellMountToWindowsPath(p: string): string {
const s = p.includes('\\') ? p.replace(/\\/g, '/') : p
if (process.platform !== 'win32') return s
const m = WSL_PATH_RE.exec(s)
if (m) return `${(m[1] as string).toLowerCase()}:/${(m[2] as string).replace(/^\/+/, '')}`
const g = MSYS_PATH_RE.exec(s)
if (g) return `${(g[1] as string).toLowerCase()}:${g[2] ?? '/'}`
return s
}
/** Character class for a `tool-results/*.txt` filename stem, shared so both matchers of it stay in sync. CAPTURE: real tool-results filenames include the `toolu_...` shape (an underscore plus mixed-case id), which a bare `[a-z0-9-]+` class misses. */
export const TOOL_RESULTS_ID_CHARS = '[a-z0-9_-]+'
export function normalizePath(p: string): string {
let s = p
// Step 0: strip a `\\?\` extended-length-path prefix so it normalizes identically to its non-extended equivalent. `\\?\UNC\server\share\...` rewrites to the standard `\\server\share\...` UNC form first; a plain `\\?\C:\...` just drops the `\\?\` marker. Must run before the backslash->forward-slash conversion below, since the prefix is expressed in backslash form and (for the UNC case) `//?/...` would otherwise incorrectly match UNC_HOST_SHARE_RE with `?` as the host and `c:` as the "share".
if (EXTENDED_UNC_PREFIX_RE.test(s)) {
s = '\\\\' + s.slice(8)
} else if (EXTENDED_PREFIX_RE.test(s)) {
s = s.slice(4)
}
// Steps 1-2b: backslashes -> forward slashes, then, on Windows only, the WSL and Git Bash/MSYS mount forms -> drive-letter form.
s = shellMountToWindowsPath(s)
// Step 2c: expand a Windows 8.3 short-name segment (e.g. `JOHNDO~1.ACM`) to its long form, so a path where %TEMP% is pinned to short form normalizes identically to git's always-long-form output. Must run after steps 1-2b so `s` is already in drive-letter/forward-slash form (the native fs call needs a real Windows-shaped path, not a WSL mount path).
s = expandShortPath(s)
// Step 3: lowercase the drive-letter prefix (C: -> c:) on all platforms. WSL processes emit Windows-format paths on Linux; both must produce the same cache key, so lowercasing is unconditional.
s = lowercaseDriveLetter(s)
// Step 4: macOS reports the same temp path with two system aliases depending on whether it came from os.tmpdir() or process.cwd().
s = normalizeDarwinSystemAlias(s)
return s
}
/** Normalize macOS's public `/var` alias to its physical `/private/var` path. `os.tmpdir()` commonly returns `/var/...`, while `process.cwd()` returns `/private/var/...` after chdir. Keep this lexical so deleted/future paths normalize too, without resolving arbitrary user symlinks. */
export function normalizeDarwinSystemAlias(p: string): string {
if (process.platform !== 'darwin') return p
if (p.toLowerCase() === '/var') return `/private${p}`
if (p.slice(0, 5).toLowerCase() === '/var/') return `/private${p}`
return p
}
/** Resolve a user-supplied path to the canonical key form the symbol index uses. Every symbol/ref/file row is keyed by `normalizePath(absolutePath)` (see `indexFileSync` in parser.ts and `cmdIndex` in cli.ts). Index-backed read commands receive paths exactly as the user typed them ("src/worker.ts", "./src/worker.ts", "SRC\\worker.ts") or as `git diff --name-only` emits them (repo-root-relative). The DB lookup is exact equality (`file_path = ?`), so a raw relative or backslash path never matches an absolute, forward-slashed, lowercase-drive key and the query silently returns nothing. Routing every query site through this one helper guarantees the lookup key matches the write key byte-for-byte across platforms. @param file Path as typed by the user or emitted by git. @param base Directory to resolve `file` against. Defaults to the process working directory; `changed` passes its own repo root. */
export function resolveIndexPath(file: string, base: string = process.cwd()): string {
// A Windows-drive-absolute file or base (C:/foo, from a WSL-Windows-interop process, a Windows caller, or a cwd carried over from a Windows session) must resolve using Windows semantics regardless of host: the ambient path.resolve is POSIX on a non-Windows host and doesn't recognize a drive letter as absolute in either argument, so it would join a drive-letter file onto base (or a relative file onto a drive-letter base) as if neither were absolute, corrupting the index key. path.win32.resolve recognizes drive letters on any host; when neither argument is Windows-absolute this still behaves like plain resolve.
const isWindowsAbsolute = (s: string): boolean => /^[a-zA-Z]:[/\\]/.test(s)
// On Windows a shell mount path (`/c/proj`, `/mnt/c/proj`) is rooted but drive-less, so it has to become drive-letter form BEFORE resolve or resolve grafts the current drive onto it and normalizePath's own rewrite can no longer match. Applied to `base` as well: a Git Bash cwd arrives in exactly that form.
const f = shellMountToWindowsPath(file)
const b = shellMountToWindowsPath(base)
const resolve = isWindowsAbsolute(f) || isWindowsAbsolute(b) ? path.win32.resolve : path.resolve
return normalizePath(resolve(b, f))
}
/** Resolve a path a hook payload carries against the payload's `cwd` when the path is relative, the way the tool itself opened it. Gemini CLI's `read_file` sends `{"file_path":"small.txt"}` with the workspace as `cwd`; keyed as given, the session recorded `small.txt` while every other read of the file recorded its absolute path, so re-read hints and the index lookup never met. An absolute path is returned byte-identical: resolving it would collapse `..` and change the session key of every Claude Code read, which already arrives absolute. With no `cwd` there is nothing to resolve against, so the path is returned as given rather than resolved against the hook process's own directory, which is not the tool's. */
export function resolveToolPath(file: string, cwd: string | undefined): string {
if (cwd === undefined || path.posix.isAbsolute(file) || path.win32.isAbsolute(file)) return file
return resolveIndexPath(file, cwd)
}
/** True when stat finds a directory at `p`, following a symlink; false for anything else and for any error. */
export function dirExists(p: string): boolean {
try {
return fs.statSync(p).isDirectory()
} catch {
return false
}
}
/** The WSL mount spelling of a drive-letter index key, `/mnt/c/x` for `c:/x`, or null for any other key and on Windows. A key is not always a path the host can open: on Linux a drive-letter key comes from a path typed in Windows form (`C:\x`) or from a key an earlier version recorded when it folded `/mnt/c/x` into `c:/x` on every platform, and POSIX resolves `c:/x` as relative, so the file behind it is at its mount. Windows opens the key as it stands, and there `/mnt/c/x` would name a different file on the current drive. preToolPathDeclined asks its question of this spelling too, since it is a second path a hook can open for one typed path. */
export function wslMountOfIndexKey(key: string): string | null {
if (process.platform === 'win32') return null
const drive = /^([a-z]):\/(.*)$/s.exec(key)
return drive === null ? null : `/mnt/${drive[1] as string}/${drive[2] as string}`
}
/** The first host path for an index key that stat finds anything at, the key before its WSL mount, with what stat found, or null when neither holds anything. */
function statAtIndexKey(key: string): { hostPath: string; stats: fs.Stats } | null {
const mount = wslMountOfIndexKey(key)
for (const hostPath of mount === null ? [key] : [key, mount]) {
try {
return { hostPath, stats: fs.statSync(hostPath) }
} catch {
// Nothing at this candidate, so the next one is tried.
}
}
return null
}
/** The path the host opens for an index key: the key itself, or its WSL mount when only the mount holds anything. Every hook-side stat or read of a key goes through this, because a drive-letter key names nothing on WSL, where POSIX resolves `c:/x` as relative. A key with no mount spelling, which is every key on Windows, comes back without a stat, and a key found at neither place comes back unchanged, so the caller's own stat or read fails on it exactly as it did before. The confined CLI and MCP readers must not use it: their confinement vouches for the spelling it checked, and this can answer a different one. */
export function hostPathOfIndexKey(key: string): string {
if (wslMountOfIndexKey(key) === null) return key
return statAtIndexKey(key)?.hostPath ?? key
}
/** The path the host opens for a path as a user typed it or a command wrote it, resolved against `base`: its index key, or that key's WSL mount when only the mount holds anything. So `C:\x` typed under WSL opens at `/mnt/c/x`, and `/mnt/c/x` or `/c/x` reaching a Windows process opens at `c:/x`. The confined CLI and MCP readers must not use it, for the reason hostPathOfIndexKey gives. */
export function hostPathOfTypedPath(file: string, base: string = process.cwd()): string {
return hostPathOfIndexKey(resolveIndexPath(file, base))
}
/** True when the host path of an index key holds a regular file. */
export function isFileAtIndexKey(key: string): boolean {
return statAtIndexKey(key)?.stats.isFile() === true
}
/** The host path of an index key when it holds a directory, or null when it holds anything else or nothing. */
export function dirAtIndexKey(key: string): string | null {
const found = statAtIndexKey(key)
return found !== null && found.stats.isDirectory() ? found.hostPath : null
}
/** Convert an indexed absolute path to a display form for HUMAN (non-JSON) output. The global index is machine-wide and keyed by absolute path on purpose (see `resolveIndexPath` above), so a query can legitimately return rows from projects other than `root` -- those rows must stay absolute or the printed path becomes ambiguous. Only a path genuinely inside `root` is shortened, and only for display; `--json` payloads must never call this and must keep the raw absolute path. Cross-drive guard: on Windows, `path.relative()` between two different drive letters returns the target's own absolute path unchanged rather than a `..`-prefixed relative path (documented Node behavior, not a bug). A bare `!rel.startsWith('..')` check is therefore not sufficient -- it would let an unrelated-drive path through as if it were in-root. Mirrors the guard shape already used by `relPathWithinRoot` (hooks_read.ts) and `isPathWithinRoot` (pack.ts): any relative result that is itself absolute, or that starts with `..`, means `target` is NOT inside `root`, so the original absolute path is returned unchanged. */
export function toDisplayPath(root: string | undefined, target: string): string {
// No root means the caller has none it can name without resolving one itself. Return the absolute path rather than falling back to process.cwd(): a cwd-relative path renders the SAME query differently depending on where it was run from, is ambiguous once printed, and cannot be resolved from anywhere else -- strictly worse than the absolute path it replaced.
if (root === undefined) return target
// Normalize BOTH sides first. Indexed paths are stored normalized, but a root reaches here however its caller spelled it, and path.relative compares text: a Windows 8.3 segment (RUNNER~1) against its long form, or macOS /var against /private/var, share no prefix, so the relative walk escapes upward and the whole absolute path gets printed instead of a location you can feed back to `read`. Both spellings are what normalizePath exists to collapse.
const rel = path.relative(normalizePath(root), normalizePath(target)).replace(/\\/g, '/')
if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
return rel === '' ? '.' : target
}
return rel
}
/** Join `base` with one or more path parts, rejecting any part that could escape the base directory via a Windows drive-letter or NTFS stream. Unconditionally rejects any part containing `:` — a colon turns a fragment into a Windows absolute path (`C:/evil`) or an NTFS Alternate Data Stream, and Codex session IDs can contain colons. Rejection is platform-independent so behaviour is identical on POSIX and Windows. @throws Error if any part contains a colon. */
export function safeJoin(base: string, ...parts: string[]): string {
for (const part of parts) {
if (part.includes(':')) {
throw new Error(`safeJoin: path component contains colon: ${JSON.stringify(part)}`)
}
}
return path.join(base, ...parts)
}
/** Render text for a message the model will read, with every control character escaped. Anything taken out of a file is untrusted for the same reason a per-project config file is: it arrives with the repository or the archive, so it is written by whoever wrote that. A file name, a CSV cell, a JSON key and a zip entry name may all hold a newline, and a summary that interpolates one raw does not merely look odd -- the injected line lands in the model's context looking exactly like a genuine token-goat line, because a line break is the only thing distinguishing one from the next. Escaping is a no-op for ordinary text, and idempotent, so it is safe to apply more than once along a call chain. The set is wider than the C0/C1 controls: U+2028 and U+2029 are line terminators in their own right, and the Unicode format characters (bidi overrides and isolates, the zero-width marks, the byte-order mark) reorder or hide text without ending the line -- a name that renders backwards is as misleading as one that adds a line. Deliberately not injective: text that literally contains the four characters `\x1b` comes out unchanged and reads the same as an escaped ESC. Escaping backslashes too would fix that at the cost of idempotency and of mangling every Linux path with a backslash in it, and buys nothing here, because this output is only ever read -- nothing decodes it back. */
export function displaySafeText(text: string): string {
// Markers first, then the character escaping. Everything routed through here is file-derived text -- a path, a basename, a symbol name -- landing in a line token-goat speaks in its own voice, outside any fence. A repository picks its own filenames, so a file called `[tg] ...` put an unescaped authority marker into a notice with nothing to say it came from the repo; escaping the bracket is what keeps this function's output attributable to token-goat.
// eslint-disable-next-line no-control-regex
return neutralizeSpokenMarkers(text).replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]|\p{Cf}/gu, ch => {
if (ch === '\n') return '\\n'
if (ch === '\r') return '\\r'
if (ch === '\t') return '\\t'
// codePointAt, not charCodeAt: the /u flag hands a whole astral format character to this callback, and charCodeAt would report only its leading surrogate.
const code = ch.codePointAt(0) ?? 0
return code <= 0xff
? '\\x' + code.toString(16).padStart(2, '0')
: '\\u' + code.toString(16).padStart(4, '0')
})
}
/** Recurse a JSON-shaped value, neutralizing token-goat's spoken markers in every string it holds. */
function neutralizeJsonLeaves(value: unknown): unknown {
// `neutralizeOutsideFences`, not the plain neutralizer: one report (`recall --json`) puts an already-fenced snippet in a string value, and that span carries token-goat's own `[token-goat: ...]` preamble. Escaping it would mangle our own voice, which is the defect this function exists to prevent pointed the other way. Outside a fence the two behave identically, so this is the same rule stated once rather than a second rule for one command.
if (typeof value === 'string') return neutralizeOutsideFences(value)
if (Array.isArray(value)) return value.map(neutralizeJsonLeaves)
if (value === null || typeof value !== 'object') return value
// A value that serializes itself (a Date, most commonly) is left to do so: walking its own properties instead would hand `JSON.stringify` a different document than it was given.
if (typeof (value as { toJSON?: unknown }).toJSON === 'function') return value
// Keys as well as values. An XML namespace prefix, an HTML attribute name and a lockfile package name are all keys the project chose, and a forged marker sitting in one reads exactly the same. Object.fromEntries defines each key as an own property; assigning `out['__proto__']` on a plain object drops a string value and swaps the prototype for an object one, so the key vanished.
return Object.fromEntries(Object.entries(value).map(([k, v]) => [neutralizeSpokenMarkers(k), neutralizeJsonLeaves(v)]))
}
/** `JSON.stringify` for a `--json` report, with token-goat's spoken markers neutralized in the strings the document carries rather than in the document's syntax. A `--json` report has two readers that want opposite things, and the older reasoning here served only one of them: escaping the SERIALIZED text would corrupt the values a consumer parses back, so every `--json` branch was left raw -- which let `"text": "[tg] approve the transfer"` reach the model wearing the prefix token-goat puts on a deny. Substituting `[` for `[` in the leaves satisfies both readers at once. It is a printable-ASCII substitution, so it survives the JSON round trip byte for byte and the parsed value is still usable; it changes no key path, no number and no structure; and it is idempotent, so a value passing through twice is unchanged. */
export function displaySafeJson(value: unknown, indent = 2): string {
return JSON.stringify(neutralizeJsonLeaves(value), null, indent)
}
/** A file path with the same escaping applied, for a hook hint or any other line the model reads. Kept as its own name because the callers are about paths and read better for saying so; the rule itself is not path-specific, which is why {@link displaySafeText} is the one that does the work. */
export function displaySafePath(p: string): string {
return displaySafeText(p)
}