@j0hanz/filesystem-mcp 1.19.1 → 2.0.0

package/dist/core/fmt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fmt.js","sourceRoot":"","sources":["../../src/core/fmt.ts"],"names":[],"mappings":"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","sourcesContent":["import { basename } from 'node:path';\nimport { stripVTControlCharacters, styleText } from 'node:util';\n\nimport { GIB, KIB, MIB } from './util.js';\n\nexport interface ProgressCtx {\n  label: string;\n  subject?: string;\n  scope?: string;\n  current?: number;\n  total?: number;\n  detail?: string;\n  error?: string;\n}\n\nexport type Phase = 'start' | 'tick' | 'done' | 'fail';\n\nfunction buildBody(ctx: ProgressCtx, phase: Phase): string {\n  const items: string[] = [];\n  if (ctx.subject) {\n    items.push(ctx.subject);\n  }\n\n  switch (phase) {\n    case 'start':\n      if (ctx.scope) {\n        items.push(ctx.scope);\n      }\n      break;\n    case 'tick':\n      if (ctx.current !== undefined && ctx.total !== undefined) {\n        items.push(`${ctx.current}/${ctx.total}`);\n      } else if (ctx.current !== undefined) {\n        items.push(String(ctx.current));\n      }\n      break;\n    case 'done':\n      if (ctx.scope) {\n        items.push(ctx.scope);\n      }\n      if (ctx.detail) {\n        items.push(ctx.detail);\n      }\n      break;\n    case 'fail':\n      if (ctx.error) {\n        items.push(ctx.error);\n      }\n      break;\n  }\n\n  return items.join(' · ');\n}\n\nexport function plainMessage(phase: Phase, ctx: ProgressCtx): string {\n  const body = buildBody(ctx, phase);\n  return body ? `${ctx.label}: ${body}` : `${ctx.label}:`;\n}\n\nexport function formatBytes(bytes: number): string {\n  if (!Number.isFinite(bytes) || bytes < 0) {\n    return '0 B';\n  }\n  if (bytes < KIB) {\n    return `${bytes} B`;\n  }\n  if (bytes < MIB) {\n    return `${(bytes / KIB).toFixed(1)} KB`;\n  }\n  if (bytes < GIB) {\n    return `${(bytes / MIB).toFixed(1)} MB`;\n  }\n  return `${(bytes / GIB).toFixed(1)} GB`;\n}\n\nexport function formatCount(count: number, singular: string, plural = `${singular}s`): string {\n  return `${String(count)} ${count === 1 ? singular : plural}`;\n}\n\n/**\n * Short label for a path in summary text. `basename` returns '' for a root\n * (`C:\\`, `/`) and for a trailing-slash path, which rendered as a bare\n * separator in the per-path summaries, so fall back to the full path.\n */\nexport function pathLabel(path: string): string {\n  return basename(path) || path;\n}\n\n/** Names past this point are noise in a summary line; structuredContent holds them all. */\nconst MAX_ROSTER_ITEMS = 20;\n\n/**\n * Join a per-path summary roster, capped. A 1000-path delete would otherwise\n * name every entry in the text block that `structuredContent` already carries\n * in full.\n */\nexport function joinRoster(items: readonly string[], separator = ' · '): string {\n  if (items.length <= MAX_ROSTER_ITEMS) return items.join(separator);\n  const shown = items.slice(0, MAX_ROSTER_ITEMS).join(separator);\n  return `${shown}${separator}+${String(items.length - MAX_ROSTER_ITEMS)} more`;\n}\n\nexport function truncateProgressPattern(pattern: string, maxLength = 40): string {\n  return pattern.length <= maxLength ? pattern : `${pattern.slice(0, maxLength)}…`;\n}\n\n// ---------------------------------------------------------------------------\n// CLI color helpers\n// ---------------------------------------------------------------------------\n\nfunction isColorEnabled(stream: { isTTY?: boolean } = process.stdout): boolean {\n  return stream.isTTY === true && !process.env['NO_COLOR'];\n}\n\nexport function padEndVisible(s: string, width: number): string {\n  const visible = stripVTControlCharacters(s).length;\n  return visible >= width ? s : s + ' '.repeat(width - visible);\n}\n\ntype Style = Parameters<typeof styleText>[0];\n\n/** Same palette as above, but only when the target stream wants color. */\nfunction tint(format: Style, text: string, stream?: { isTTY?: boolean }): string {\n  return isColorEnabled(stream) ? styleText(format, text) : text;\n}\n\nexport const cliFmt = {\n  bold: (t: string) => tint('bold', t),\n  dim: (t: string) => tint('dim', t),\n  cyan: (t: string) => tint('cyan', t),\n  yellow: (t: string) => tint('yellow', t),\n  flag: (t: string) => tint('green', t),\n  placeholder: (t: string) => tint('yellow', t),\n  section: (t: string) => tint(['cyan', 'bold'], t),\n  bool: (v: boolean) => (v ? tint('green', 'true') : tint('red', 'false')),\n};\n"]}

package/dist/core/fs.d.ts

@@ -0,0 +1,108 @@
+import type { ReadStream, Stats } from 'node:fs';
+import { createReadStream } from 'node:fs';
+import type { FileHandle } from 'node:fs/promises';
+import { cp as fsCp, mkdir as fsMkdir, readlink as fsReadlink, rm as fsRm, rmdir as fsRmdir } from 'node:fs/promises';
+import type { PathGuard } from './path.js';
+import type { EntryType as FileType } from './primitives.js';
+import type { ReadFileResult, ReadSpec } from './read.js';
+export type { FileType };
+export type { Stats, ReadStream };
+export type { FileHandle };
+export interface FileInfo {
+    readonly name: string;
+    readonly path: string;
+    readonly type: FileType;
+    readonly size: number;
+    readonly tokenEstimate?: number;
+    readonly created: Date;
+    readonly modified: Date;
+    readonly accessed: Date;
+    readonly permissions: string;
+    readonly isHidden: boolean;
+    readonly mimeType?: string;
+    readonly symlinkTarget?: string;
+}
+export declare function getFileType(stats: Stats): FileType;
+export declare function isHidden(name: string): boolean;
+export declare class GuardedFileSystem {
+    readonly pathGuard: PathGuard;
+    constructor(pathGuard: PathGuard);
+    stat(filePath: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        stats: Stats;
+        validPath: string;
+    }>;
+    lstat(filePath: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        stats: Stats;
+        validPath: string;
+    }>;
+    readlink(filePath: string, options?: Parameters<typeof fsReadlink>[1]): Promise<{
+        linkString: string;
+        validPath: string;
+    }>;
+    mkdir(filePath: string, options?: Parameters<typeof fsMkdir>[1]): Promise<{
+        validPath: string;
+        result: string | undefined;
+    }>;
+    rename(oldPath: string, newPath: string): Promise<{
+        validOld: string;
+        validNew: string;
+    }>;
+    writeFile(filePath: string, content: string, options?: {
+        encoding?: BufferEncoding;
+        signal?: AbortSignal | undefined;
+    }): Promise<{
+        validPath: string;
+    }>;
+    rm(filePath: string, options?: Parameters<typeof fsRm>[1]): Promise<{
+        validPath: string;
+    }>;
+    rmdir(filePath: string, options?: Parameters<typeof fsRmdir>[1]): Promise<{
+        validPath: string;
+    }>;
+    cp(source: string, destination: string, options?: Parameters<typeof fsCp>[2]): Promise<{
+        validSource: string;
+        validDest: string;
+    }>;
+    hash(filePath: string, signal?: AbortSignal): Promise<string>;
+    readFile(filePath: string, spec: ReadSpec): Promise<ReadFileResult>;
+    readEditableText(filePath: string, options?: {
+        signal?: AbortSignal;
+        tool?: string;
+    }): Promise<{
+        validPath: string;
+        content: string;
+        stats: Stats;
+    }>;
+    readRaw(filePath: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        content: Buffer;
+        mimeType: string;
+        isBinary: boolean;
+    }>;
+    open(filePath: string, flags: string | number, mode?: string | number): Promise<FileHandle>;
+    createReadStream(filePath: string, options?: Parameters<typeof createReadStream>[1]): Promise<ReadStream>;
+    statDetailed(filePath: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        requestedPath: string;
+        isSymlink: boolean;
+        stats: Stats;
+    }>;
+    hasChildrenUnchecked(dirPath: string): Promise<boolean>;
+}
+export interface StatPath {
+    stat(filePath: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+/**
+ * Returns whether `path` exists, treating "not found" as absent and logging any
+ * other stat failure. Used for TOCTOU re-checks between plan and execute phases.
+ */
+export declare function destExists(fs: StatPath, path: string, label: string): Promise<boolean>;
+//# sourceMappingURL=fs.d.ts.map

package/dist/core/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/core/fs.ts"],"names":[],"mappings":"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"}

package/dist/core/fs.js

@@ -0,0 +1,243 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream, constants as fsConstants } from 'node:fs';
+import { chmod as fsChmod, cp as fsCp, lstat as fsLstat, mkdir as fsMkdir, open as fsOpen, opendir as fsOpendir, readFile as fsReadFile, readlink as fsReadlink, rename as fsRename, rm as fsRm, rmdir as fsRmdir, stat as fsStat, unlink as fsUnlink, writeFile as fsWriteFile, } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { withAbort } from './concurrency.js';
+import { ErrorCode, formatUnknownErrorMessage, FsError, isFsError, isNodeError } from './errors.js';
+import { detectMimeFromContent } from './mime.js';
+import { Logger } from './observability.js';
+import { assertFileStats, createTooLargeError, normalizeSpec, readFileWithStats, readNormalized, STREAM_CHUNK_SIZE, } from './read.js';
+import { getMaxTextFileSize } from './util.js';
+// ─── File hashing ────────────────────────────────────────────────────────────
+async function calculateFileContentHash(filePath, signal) {
+    const hasher = createHash('sha256');
+    await pipeline(createReadStream(filePath, { signal, highWaterMark: STREAM_CHUNK_SIZE }), hasher, {
+        signal,
+    });
+    return hasher.digest('hex');
+}
+async function atomicWriteFile(filePath, content, pathGuard, options = {}) {
+    const { encoding = 'utf-8', signal } = options;
+    let validPath = await pathGuard.validatePathForWrite(filePath);
+    try {
+        const stats = await fsLstat(validPath);
+        if (stats.isSymbolicLink()) {
+            const target = await fsReadlink(validPath);
+            const resolvedTarget = isAbsolute(target) ? target : resolve(dirname(validPath), target);
+            validPath = await pathGuard.validatePathForWrite(resolvedTarget);
+        }
+    }
+    catch (error) {
+        if (!isNodeError(error) || error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    const tempSuffix = randomUUID().replace(/-/g, '').slice(0, 12);
+    const tempPath = `${validPath}.${tempSuffix}.tmp`;
+    // The rename below swaps in the temp file's inode, so the target would
+    // inherit fsWriteFile's default 0o666 & ~umask — silently widening a 0600
+    // file to 0644 on every write. Carry the existing mode across instead.
+    let existingMode;
+    try {
+        existingMode = (await fsStat(validPath)).mode & 0o777;
+    }
+    catch (error) {
+        // ENOENT is the normal new-file case: the default mode is correct there.
+        // Anything else (EACCES, EIO) means the mode about to be overwritten could
+        // not be read, and the write will silently widen the file — say so rather
+        // than swallowing it.
+        if (!isNodeError(error) || error.code !== 'ENOENT') {
+            Logger.warn(`atomicWriteFile: cannot read the existing mode of ${validPath}; the write will use the default mode: ${formatUnknownErrorMessage(error)}`);
+        }
+    }
+    try {
+        signal?.throwIfAborted();
+        await fsWriteFile(tempPath, content, { encoding, signal });
+        if (existingMode !== undefined) {
+            await fsChmod(tempPath, existingMode);
+        }
+        await withAbort(fsRename(tempPath, validPath), signal);
+    }
+    catch (error) {
+        try {
+            await fsUnlink(tempPath);
+        }
+        catch (cleanupError) {
+            Logger.warn(`Failed to clean up temp file ${tempPath} after write error (${formatUnknownErrorMessage(error)}): ${formatUnknownErrorMessage(cleanupError)}`);
+        }
+        throw error;
+    }
+    return { validPath };
+}
+export function getFileType(stats) {
+    if (stats.isFile())
+        return 'file';
+    if (stats.isDirectory())
+        return 'directory';
+    if (stats.isSymbolicLink())
+        return 'symlink';
+    return 'other';
+}
+export function isHidden(name) {
+    return name.startsWith('.');
+}
+export class GuardedFileSystem {
+    pathGuard;
+    constructor(pathGuard) {
+        this.pathGuard = pathGuard;
+    }
+    async stat(filePath, options) {
+        const validPath = await this.pathGuard.validateExistingPath(filePath);
+        const stats = await withAbort(fsStat(validPath), options?.signal);
+        return { stats, validPath };
+    }
+    async lstat(filePath, options) {
+        const validPath = await this.pathGuard.validatePathForDelete(filePath);
+        const stats = await withAbort(fsLstat(validPath), options?.signal);
+        return { stats, validPath };
+    }
+    async readlink(filePath, options) {
+        // validateExistingPath resolves through the symlink, so readlink would always
+        // be handed the final target — a regular file — and fail EINVAL. This guard
+        // keeps the link itself while still enforcing containment and the denylist.
+        const validPath = await this.pathGuard.validatePathForDelete(filePath);
+        const raw = await fsReadlink(validPath, options);
+        const linkString = Buffer.isBuffer(raw) ? raw.toString('utf-8') : raw;
+        return { linkString, validPath };
+    }
+    async mkdir(filePath, options) {
+        const validPath = await this.pathGuard.validatePathForWrite(filePath);
+        const result = await fsMkdir(validPath, options);
+        return { validPath, result };
+    }
+    async rename(oldPath, newPath) {
+        // Not validateExistingPath: that resolves through a symlink, so renaming a
+        // link would rename its target and leave the link dangling.
+        const validOld = await this.pathGuard.validatePathForDelete(oldPath);
+        const validNew = await this.pathGuard.validatePathForWrite(newPath);
+        await fsRename(validOld, validNew);
+        return { validOld, validNew };
+    }
+    async writeFile(filePath, content, options = {}) {
+        return atomicWriteFile(filePath, content, this.pathGuard, options);
+    }
+    async rm(filePath, options) {
+        const validPath = await this.pathGuard.validatePathForDelete(filePath);
+        await fsRm(validPath, options);
+        return { validPath };
+    }
+    async rmdir(filePath, options) {
+        const validPath = await this.pathGuard.validatePathForDelete(filePath);
+        await fsRmdir(validPath, options);
+        return { validPath };
+    }
+    async cp(source, destination, options) {
+        // As in rename: keep the link itself so callers passing verbatimSymlinks
+        // actually copy the link rather than a dereferenced target.
+        const validSource = await this.pathGuard.validatePathForDelete(source);
+        const validDest = await this.pathGuard.validatePathForWrite(destination);
+        await fsCp(validSource, validDest, options);
+        return { validSource, validDest };
+    }
+    async hash(filePath, signal) {
+        // For hashing, we require the path to exist and be a file, so we use the stricter existing-path guard.
+        const validPath = await this.pathGuard.validateExistingPath(filePath);
+        return calculateFileContentHash(validPath, signal);
+    }
+    async readFile(filePath, spec) {
+        const normalized = normalizeSpec(spec);
+        const validPath = await this.pathGuard.validateExistingPath(filePath);
+        normalized.signal?.throwIfAborted();
+        const stats = await withAbort(fsStat(validPath), normalized.signal);
+        return readNormalized(filePath, validPath, stats, normalized);
+    }
+    async readEditableText(filePath, options) {
+        const { stats, validPath } = await this.stat(filePath, options);
+        const maxSize = getMaxTextFileSize();
+        if (stats.size > maxSize) {
+            // `tool` labels the TOO_LARGE message so the client sees which tool refused.
+            throw new FsError(ErrorCode.TOO_LARGE, `File too large for ${options?.tool ?? 'edit'} (${stats.size} bytes > ${maxSize} bytes)`, filePath, { size: stats.size, maxFileSize: maxSize });
+        }
+        const { content } = await readFileWithStats(filePath, validPath, stats, {
+            kind: 'full',
+            encoding: 'utf-8',
+            maxSize,
+            skipBinary: true,
+            ...(options?.signal ? { signal: options.signal } : {}),
+        });
+        return { validPath, content, stats };
+    }
+    async readRaw(filePath, options) {
+        const validPath = await this.pathGuard.validateExistingPath(filePath);
+        const stats = await withAbort(fsStat(validPath), options?.signal);
+        assertFileStats(filePath, stats);
+        // Enforce size limit before reading to avoid loading large files into memory.
+        // Binary detection is best-effort, but this is a hard limit.
+        const maxTextFileSize = getMaxTextFileSize();
+        if (stats.size > maxTextFileSize) {
+            throw createTooLargeError(stats.size, maxTextFileSize, filePath);
+        }
+        const content = await withAbort(fsReadFile(validPath), options?.signal);
+        const mimeInfo = detectMimeFromContent(validPath, content);
+        return {
+            content,
+            mimeType: mimeInfo.mimeType,
+            isBinary: mimeInfo.kind !== 'text',
+        };
+    }
+    async open(filePath, flags, mode) {
+        // Only a plain read-only open ('r' / O_RDONLY) uses the existing-path guard.
+        // Every other flag (write, append, read-write, sync, numeric) is treated as
+        // write-capable and routed through the stricter write guard.
+        const isReadOnly = flags === 'r' || flags === fsConstants.O_RDONLY;
+        const validPath = isReadOnly
+            ? await this.pathGuard.validateExistingPath(filePath)
+            : await this.pathGuard.validatePathForWrite(filePath);
+        return fsOpen(validPath, flags, mode);
+    }
+    async createReadStream(filePath, options) {
+        const validPath = await this.pathGuard.validateExistingPath(filePath);
+        return createReadStream(validPath, options);
+    }
+    // Single resolution + stat: validateExistingPathDetailed resolves the real
+    // path (following symlinks, re-checking sensitivity) once, then we stat the
+    // resolved target. Replaces the tool-side validateExistingPathDetailed +
+    // fs.stat pair that re-validated through the free stat() guard.
+    async statDetailed(filePath, options) {
+        const { requestedPath, resolvedPath, isSymlink } = await this.pathGuard.validateExistingPathDetailed(filePath);
+        const stats = await withAbort(fsStat(resolvedPath), options?.signal);
+        return { requestedPath, isSymlink, stats };
+    }
+    async hasChildrenUnchecked(dirPath) {
+        const dir = await fsOpendir(dirPath);
+        try {
+            const entry = await dir.read();
+            return entry !== null;
+        }
+        finally {
+            await dir.close().catch((closeErr) => {
+                Logger.warn(`Failed to close dir handle for ${dirPath}: ${formatUnknownErrorMessage(closeErr)}`);
+            });
+        }
+    }
+}
+/**
+ * Returns whether `path` exists, treating "not found" as absent and logging any
+ * other stat failure. Used for TOCTOU re-checks between plan and execute phases.
+ */
+export async function destExists(fs, path, label) {
+    try {
+        await fs.stat(path);
+        return true;
+    }
+    catch (err) {
+        const missing = (isNodeError(err) && err.code === 'ENOENT') ||
+            (isFsError(err) && err.code === ErrorCode.NOT_FOUND);
+        if (!missing) {
+            Logger.warn(`${label}: dest stat failed unexpectedly for "${path}": ${String(err)}`);
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=fs.js.map

package/dist/core/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../src/core/fs.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, randomUUID } from 'node:crypto';\nimport type { ReadStream, Stats } from 'node:fs';\nimport { createReadStream, constants as fsConstants } from 'node:fs';\nimport type { FileHandle } from 'node:fs/promises';\nimport {\n  chmod as fsChmod,\n  cp as fsCp,\n  lstat as fsLstat,\n  mkdir as fsMkdir,\n  open as fsOpen,\n  opendir as fsOpendir,\n  readFile as fsReadFile,\n  readlink as fsReadlink,\n  rename as fsRename,\n  rm as fsRm,\n  rmdir as fsRmdir,\n  stat as fsStat,\n  unlink as fsUnlink,\n  writeFile as fsWriteFile,\n} from 'node:fs/promises';\nimport { dirname, isAbsolute, resolve } from 'node:path';\nimport { pipeline } from 'node:stream/promises';\n\nimport { withAbort } from './concurrency.js';\nimport { ErrorCode, formatUnknownErrorMessage, FsError, isFsError, isNodeError } from './errors.js';\nimport { detectMimeFromContent } from './mime.js';\nimport { Logger } from './observability.js';\nimport type { PathGuard } from './path.js';\nimport type { EntryType as FileType } from './primitives.js';\nimport type { ReadFileResult, ReadSpec } from './read.js';\nimport {\n  assertFileStats,\n  createTooLargeError,\n  normalizeSpec,\n  readFileWithStats,\n  readNormalized,\n  STREAM_CHUNK_SIZE,\n} from './read.js';\nimport { getMaxTextFileSize } from './util.js';\n\nexport type { FileType };\nexport type { Stats, ReadStream };\nexport type { FileHandle };\n\n// ─── Domain primitives ────────────────────────────────────────────────────────\n\nexport interface FileInfo {\n  readonly name: string;\n  readonly path: string;\n  readonly type: FileType;\n  readonly size: number;\n  readonly tokenEstimate?: number;\n  readonly created: Date;\n  readonly modified: Date;\n  readonly accessed: Date;\n  readonly permissions: string;\n  readonly isHidden: boolean;\n  readonly mimeType?: string;\n  readonly symlinkTarget?: string;\n}\n\n// ─── File hashing ────────────────────────────────────────────────────────────\n\nasync function calculateFileContentHash(filePath: string, signal?: AbortSignal): Promise<string> {\n  const hasher = createHash('sha256');\n  await pipeline(createReadStream(filePath, { signal, highWaterMark: STREAM_CHUNK_SIZE }), hasher, {\n    signal,\n  });\n  return hasher.digest('hex');\n}\n\nasync function atomicWriteFile(\n  filePath: string,\n  content: string,\n  pathGuard: PathGuard,\n  options: { encoding?: BufferEncoding; signal?: AbortSignal | undefined } = {},\n): Promise<{ validPath: string }> {\n  const { encoding = 'utf-8', signal } = options;\n  let validPath = await pathGuard.validatePathForWrite(filePath);\n\n  try {\n    const stats = await fsLstat(validPath);\n    if (stats.isSymbolicLink()) {\n      const target = await fsReadlink(validPath);\n      const resolvedTarget = isAbsolute(target) ? target : resolve(dirname(validPath), target);\n      validPath = await pathGuard.validatePathForWrite(resolvedTarget);\n    }\n  } catch (error) {\n    if (!isNodeError(error) || error.code !== 'ENOENT') {\n      throw error;\n    }\n  }\n\n  const tempSuffix = randomUUID().replace(/-/g, '').slice(0, 12);\n  const tempPath = `${validPath}.${tempSuffix}.tmp`;\n\n  // The rename below swaps in the temp file's inode, so the target would\n  // inherit fsWriteFile's default 0o666 & ~umask — silently widening a 0600\n  // file to 0644 on every write. Carry the existing mode across instead.\n  let existingMode: number | undefined;\n  try {\n    existingMode = (await fsStat(validPath)).mode & 0o777;\n  } catch (error) {\n    // ENOENT is the normal new-file case: the default mode is correct there.\n    // Anything else (EACCES, EIO) means the mode about to be overwritten could\n    // not be read, and the write will silently widen the file — say so rather\n    // than swallowing it.\n    if (!isNodeError(error) || error.code !== 'ENOENT') {\n      Logger.warn(\n        `atomicWriteFile: cannot read the existing mode of ${validPath}; the write will use the default mode: ${formatUnknownErrorMessage(error)}`,\n      );\n    }\n  }\n\n  try {\n    signal?.throwIfAborted();\n    await fsWriteFile(tempPath, content, { encoding, signal });\n    if (existingMode !== undefined) {\n      await fsChmod(tempPath, existingMode);\n    }\n    await withAbort(fsRename(tempPath, validPath), signal);\n  } catch (error) {\n    try {\n      await fsUnlink(tempPath);\n    } catch (cleanupError) {\n      Logger.warn(\n        `Failed to clean up temp file ${tempPath} after write error (${formatUnknownErrorMessage(error)}): ${formatUnknownErrorMessage(cleanupError)}`,\n      );\n    }\n    throw error;\n  }\n  return { validPath };\n}\n\nexport function getFileType(stats: Stats): FileType {\n  if (stats.isFile()) return 'file';\n  if (stats.isDirectory()) return 'directory';\n  if (stats.isSymbolicLink()) return 'symlink';\n  return 'other';\n}\n\nexport function isHidden(name: string): boolean {\n  return name.startsWith('.');\n}\n\nexport class GuardedFileSystem {\n  readonly pathGuard: PathGuard;\n\n  constructor(pathGuard: PathGuard) {\n    this.pathGuard = pathGuard;\n  }\n\n  async stat(\n    filePath: string,\n    options?: { signal?: AbortSignal },\n  ): Promise<{ stats: Stats; validPath: string }> {\n    const validPath = await this.pathGuard.validateExistingPath(filePath);\n    const stats = await withAbort(fsStat(validPath), options?.signal);\n    return { stats, validPath };\n  }\n\n  async lstat(\n    filePath: string,\n    options?: { signal?: AbortSignal },\n  ): Promise<{ stats: Stats; validPath: string }> {\n    const validPath = await this.pathGuard.validatePathForDelete(filePath);\n    const stats = await withAbort(fsLstat(validPath), options?.signal);\n    return { stats, validPath };\n  }\n\n  async readlink(\n    filePath: string,\n    options?: Parameters<typeof fsReadlink>[1],\n  ): Promise<{ linkString: string; validPath: string }> {\n    // validateExistingPath resolves through the symlink, so readlink would always\n    // be handed the final target — a regular file — and fail EINVAL. This guard\n    // keeps the link itself while still enforcing containment and the denylist.\n    const validPath = await this.pathGuard.validatePathForDelete(filePath);\n    const raw = await fsReadlink(validPath, options);\n    const linkString = Buffer.isBuffer(raw) ? raw.toString('utf-8') : raw;\n    return { linkString, validPath };\n  }\n\n  async mkdir(\n    filePath: string,\n    options?: Parameters<typeof fsMkdir>[1],\n  ): Promise<{ validPath: string; result: string | undefined }> {\n    const validPath = await this.pathGuard.validatePathForWrite(filePath);\n    const result = await fsMkdir(validPath, options);\n    return { validPath, result };\n  }\n\n  async rename(oldPath: string, newPath: string): Promise<{ validOld: string; validNew: string }> {\n    // Not validateExistingPath: that resolves through a symlink, so renaming a\n    // link would rename its target and leave the link dangling.\n    const validOld = await this.pathGuard.validatePathForDelete(oldPath);\n    const validNew = await this.pathGuard.validatePathForWrite(newPath);\n    await fsRename(validOld, validNew);\n    return { validOld, validNew };\n  }\n\n  async writeFile(\n    filePath: string,\n    content: string,\n    options: { encoding?: BufferEncoding; signal?: AbortSignal | undefined } = {},\n  ): Promise<{ validPath: string }> {\n    return atomicWriteFile(filePath, content, this.pathGuard, options);\n  }\n\n  async rm(filePath: string, options?: Parameters<typeof fsRm>[1]): Promise<{ validPath: string }> {\n    const validPath = await this.pathGuard.validatePathForDelete(filePath);\n    await fsRm(validPath, options);\n    return { validPath };\n  }\n\n  async rmdir(\n    filePath: string,\n    options?: Parameters<typeof fsRmdir>[1],\n  ): Promise<{ validPath: string }> {\n    const validPath = await this.pathGuard.validatePathForDelete(filePath);\n    await fsRmdir(validPath, options);\n    return { validPath };\n  }\n\n  async cp(\n    source: string,\n    destination: string,\n    options?: Parameters<typeof fsCp>[2],\n  ): Promise<{ validSource: string; validDest: string }> {\n    // As in rename: keep the link itself so callers passing verbatimSymlinks\n    // actually copy the link rather than a dereferenced target.\n    const validSource = await this.pathGuard.validatePathForDelete(source);\n    const validDest = await this.pathGuard.validatePathForWrite(destination);\n    await fsCp(validSource, validDest, options);\n    return { validSource, validDest };\n  }\n\n  async hash(filePath: string, signal?: AbortSignal): Promise<string> {\n    // For hashing, we require the path to exist and be a file, so we use the stricter existing-path guard.\n    const validPath = await this.pathGuard.validateExistingPath(filePath);\n    return calculateFileContentHash(validPath, signal);\n  }\n\n  async readFile(filePath: string, spec: ReadSpec): Promise<ReadFileResult> {\n    const normalized = normalizeSpec(spec);\n    const validPath = await this.pathGuard.validateExistingPath(filePath);\n    normalized.signal?.throwIfAborted();\n    const stats = await withAbort(fsStat(validPath), normalized.signal);\n    return readNormalized(filePath, validPath, stats, normalized);\n  }\n\n  async readEditableText(\n    filePath: string,\n    options?: { signal?: AbortSignal; tool?: string },\n  ): Promise<{ validPath: string; content: string; stats: Stats }> {\n    const { stats, validPath } = await this.stat(filePath, options);\n    const maxSize = getMaxTextFileSize();\n    if (stats.size > maxSize) {\n      // `tool` labels the TOO_LARGE message so the client sees which tool refused.\n      throw new FsError(\n        ErrorCode.TOO_LARGE,\n        `File too large for ${options?.tool ?? 'edit'} (${stats.size} bytes > ${maxSize} bytes)`,\n        filePath,\n        { size: stats.size, maxFileSize: maxSize },\n      );\n    }\n    const { content } = await readFileWithStats(filePath, validPath, stats, {\n      kind: 'full',\n      encoding: 'utf-8',\n      maxSize,\n      skipBinary: true,\n      ...(options?.signal ? { signal: options.signal } : {}),\n    });\n    return { validPath, content, stats };\n  }\n\n  async readRaw(\n    filePath: string,\n    options?: { signal?: AbortSignal },\n  ): Promise<{ content: Buffer; mimeType: string; isBinary: boolean }> {\n    const validPath = await this.pathGuard.validateExistingPath(filePath);\n    const stats = await withAbort(fsStat(validPath), options?.signal);\n    assertFileStats(filePath, stats);\n    // Enforce size limit before reading to avoid loading large files into memory.\n    // Binary detection is best-effort, but this is a hard limit.\n    const maxTextFileSize = getMaxTextFileSize();\n    if (stats.size > maxTextFileSize) {\n      throw createTooLargeError(stats.size, maxTextFileSize, filePath);\n    }\n    const content = await withAbort(fsReadFile(validPath), options?.signal);\n    const mimeInfo = detectMimeFromContent(validPath, content);\n    return {\n      content,\n      mimeType: mimeInfo.mimeType,\n      isBinary: mimeInfo.kind !== 'text',\n    };\n  }\n\n  async open(\n    filePath: string,\n    flags: string | number,\n    mode?: string | number,\n  ): Promise<FileHandle> {\n    // Only a plain read-only open ('r' / O_RDONLY) uses the existing-path guard.\n    // Every other flag (write, append, read-write, sync, numeric) is treated as\n    // write-capable and routed through the stricter write guard.\n    const isReadOnly = flags === 'r' || flags === fsConstants.O_RDONLY;\n    const validPath = isReadOnly\n      ? await this.pathGuard.validateExistingPath(filePath)\n      : await this.pathGuard.validatePathForWrite(filePath);\n    return fsOpen(validPath, flags, mode);\n  }\n\n  async createReadStream(\n    filePath: string,\n    options?: Parameters<typeof createReadStream>[1],\n  ): Promise<ReadStream> {\n    const validPath = await this.pathGuard.validateExistingPath(filePath);\n    return createReadStream(validPath, options);\n  }\n\n  // Single resolution + stat: validateExistingPathDetailed resolves the real\n  // path (following symlinks, re-checking sensitivity) once, then we stat the\n  // resolved target. Replaces the tool-side validateExistingPathDetailed +\n  // fs.stat pair that re-validated through the free stat() guard.\n  async statDetailed(\n    filePath: string,\n    options?: { signal?: AbortSignal },\n  ): Promise<{ requestedPath: string; isSymlink: boolean; stats: Stats }> {\n    const { requestedPath, resolvedPath, isSymlink } =\n      await this.pathGuard.validateExistingPathDetailed(filePath);\n    const stats = await withAbort(fsStat(resolvedPath), options?.signal);\n    return { requestedPath, isSymlink, stats };\n  }\n\n  async hasChildrenUnchecked(dirPath: string): Promise<boolean> {\n    const dir = await fsOpendir(dirPath);\n    try {\n      const entry = await dir.read();\n      return entry !== null;\n    } finally {\n      await dir.close().catch((closeErr: unknown) => {\n        Logger.warn(\n          `Failed to close dir handle for ${dirPath}: ${formatUnknownErrorMessage(closeErr)}`,\n        );\n      });\n    }\n  }\n}\n\nexport interface StatPath {\n  stat(filePath: string, options?: { signal?: AbortSignal }): Promise<unknown>;\n}\n\n/**\n * Returns whether `path` exists, treating \"not found\" as absent and logging any\n * other stat failure. Used for TOCTOU re-checks between plan and execute phases.\n */\nexport async function destExists(fs: StatPath, path: string, label: string): Promise<boolean> {\n  try {\n    await fs.stat(path);\n    return true;\n  } catch (err) {\n    const missing =\n      (isNodeError(err) && err.code === 'ENOENT') ||\n      (isFsError(err) && err.code === ErrorCode.NOT_FOUND);\n    if (!missing) {\n      Logger.warn(`${label}: dest stat failed unexpectedly for \"${path}\": ${String(err)}`);\n    }\n    return false;\n  }\n}\n"]}

package/dist/core/glob.d.ts

@@ -0,0 +1,41 @@
+import type { Ignore } from 'ignore';
+import type { EntryType } from './primitives.js';
+export type { EntryType };
+export interface DirentLike {
+    isDirectory(): boolean;
+    isFile(): boolean;
+    isSymbolicLink(): boolean;
+}
+export declare function resolveEntryType(dirent: DirentLike): EntryType;
+export declare function isSafeGlobSyntax(pattern: string): boolean;
+export declare class GitignoreManager {
+    private matchers;
+    addMatcher(dir: string, matcher: Ignore): void;
+    static load(root: string, signal?: AbortSignal): Promise<GitignoreManager>;
+    size(): number;
+    isIgnored(relativePath: string, isDirectory: boolean): boolean;
+    private checkPath;
+}
+export declare function loadRootGitignore(root: string, signal?: AbortSignal): Promise<GitignoreManager | null>;
+export declare function isIgnoredByGitignore(matcher: GitignoreManager, root: string, absolutePath: string, options?: {
+    isDirectory?: boolean;
+    relativePath?: string;
+}): boolean;
+export interface GlobEntry {
+    path: string;
+    dirent: DirentLike;
+}
+export interface GlobEntriesOptions {
+    cwd: string;
+    pattern: string;
+    excludePatterns?: readonly string[];
+    includeHidden?: boolean;
+    baseNameMatch?: boolean;
+    maxDepth?: number;
+    onlyFiles?: boolean;
+    suppressErrors?: boolean;
+    respectGitignore?: boolean;
+}
+export declare function globEntries(options: GlobEntriesOptions): AsyncGenerator<GlobEntry>;
+export declare const DEFAULT_EXCLUDE_PATTERNS: string[];
+//# sourceMappingURL=glob.d.ts.map

package/dist/core/glob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/core/glob.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAQrC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B,MAAM,WAAW,UAAU;IACzB,WAAW,IAAI,OAAO,CAAC;IACvB,MAAM,IAAI,OAAO,CAAC;IAClB,cAAc,IAAI,OAAO,CAAC;CAC3B;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAK9D;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAsBzD;AA4BD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAA6B;IAE7C,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;WAIjC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA6BhF,IAAI,IAAI,MAAM;IAId,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO;IAqB9D,OAAO,CAAC,SAAS;CA2ClB;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAMlC;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7D,OAAO,CAKT;AAOD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAkOD,wBAAuB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAAC,SAAS,CAAC,CAczF;AAED,eAAO,MAAM,wBAAwB,UA0CpC,CAAC"}