@j0hanz/filesystem-mcp 2.8.1 → 2.9.0

package/dist/core/file-uri.js

@@ -1,7 +1,9 @@
 import { basename } from 'node:path';
 import { detectMimeFromContent } from "./mime.js";
+import { IS_WINDOWS, toPosixPath } from "./path-utils.js";
 import { countLines } from "./read.js";
-import { getMaxTextFileSize } from "./util.js";
+import { getMaxTextFileSize, jsonBytesOver, MAX_OUTBOUND_RESULT_BYTES } from "./util.js";
+const KIB = 1024;
 // Single owner of the `filesystem-mcp://file/` URI scheme — the template string,
 // the path→URI encoder, the URI→path decoder, the link blocks built from them,
 // and the post-write metadata block every write tool reports alongside them.
@@ -11,10 +13,12 @@ export const FILESYSTEM_FILE_URI_TEMPLATE = 'filesystem-mcp://file/{+path}';
  * must return, since a client expands a suggestion into the template verbatim.
  * Unescaped, a '#' or '?' in a filename truncates the URI into a fragment or
  * query (silently naming a different path) and a '%' makes the decode throw.
- * Separators are restored so the value still reads as a path.
+ * Separators are restored so the value still reads as a path. A backslash is
+ * a separator only on Windows; on POSIX it is part of a name and stays `%5C`,
+ * or `a\b.txt` and `a/b.txt` would share one URI.
  */
 export function encodeFileUriPath(validPath) {
-    const posix = validPath.replace(/\\/g, '/');
+    const posix = IS_WINDOWS ? toPosixPath(validPath) : validPath;
     return encodeURIComponent(posix).replace(/%2F/gi, '/');
 }
 /** Inverse of {@link encodeFileUriPath}; `undefined` on invalid percent-encoding. */
@@ -60,6 +64,24 @@ export function extractPath(uri) {
         return undefined;
     return decodeFileUriPath(url.pathname.slice(1));
 }
+/**
+ * Whether stdio's resources/read would refuse this file: it measures the
+ * JSON-encoded result, so escaping counts, and a file it reads as binary
+ * comes back base64. Without the content, assume the worst escape (6 bytes
+ * per byte) so a link is never one the read refuses.
+ */
+function overStdioRead(validPath, mimeType, size, written) {
+    if (written === undefined)
+        return 6 * size > MAX_OUTBOUND_RESULT_BYTES - 64 * KIB;
+    // readRaw returns any non-text kind as base64 (`isBinary: kind !== 'text'`).
+    if (written.kind !== 'text') {
+        return 4 * Math.ceil(size / 3) > MAX_OUTBOUND_RESULT_BYTES - 64 * KIB;
+    }
+    const result = {
+        contents: [{ uri: buildFileResourceUri(validPath), mimeType, text: written.content }],
+    };
+    return jsonBytesOver(result, MAX_OUTBOUND_RESULT_BYTES) !== undefined;
+}
 /**
  * The URI and link a write tool may advertise for the file it wrote. None on a
  * dry run — nothing was written, so the file on disk is still the one the
@@ -67,10 +89,16 @@ export function extractPath(uri) {
  * the store serves the URI via readRaw, which would reject it with TOO_LARGE.
  * File resources are read directly from disk, not from the result store.
  * `lastModified` is the post-write mtime when the caller stat'd the file; a
- * link without it is still valid.
+ * link without it is still valid. None over stdio when the read would refuse
+ * it: the JSON-encoded result past `MAX_OUTBOUND_RESULT_BYTES` (escaping
+ * counts, binary is base64), or, with no content to measure, any file whose
+ * worst-case escape could be.
  */
-export function writtenFileLinks(validPath, mimeType, size, dryRun = false, lastModified) {
-    if (dryRun || size === undefined || size > getMaxTextFileSize()) {
+export function writtenFileLinks(validPath, mimeType, size, dryRun = false, lastModified, transport, written) {
+    if (dryRun ||
+        size === undefined ||
+        size > getMaxTextFileSize() ||
+        (transport === 'stdio' && overStdioRead(validPath, mimeType, size, written))) {
         return { resourceUri: undefined, resourceLink: undefined };
     }
     return {
@@ -93,7 +121,7 @@ export function buildWrittenFileMeta(options) {
         lineCount: countLines(content),
         mimeType,
         kind,
-        ...writtenFileLinks(validPath, mimeType, size, options.dryRun, options.lastModified),
+        ...writtenFileLinks(validPath, mimeType, size, options.dryRun, options.lastModified, options.transport, { content, kind }),
     };
 }
 //# sourceMappingURL=file-uri.js.map

package/dist/core/file-uri.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-uri.js","sourceRoot":"","sources":["../../src/core/file-uri.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ContentBlock } from '@modelcontextprotocol/server';\n\nimport { basename } from 'node:path';\n\nimport { detectMimeFromContent } from './mime.ts';\nimport type { FileKind } from './mime.ts';\nimport { countLines } from './read.ts';\nimport { getMaxTextFileSize } from './util.ts';\n\n// Single owner of the `filesystem-mcp://file/` URI scheme — the template string,\n// the path→URI encoder, the URI→path decoder, the link blocks built from them,\n// and the post-write metadata block every write tool reports alongside them.\n\nexport const FILESYSTEM_FILE_URI_TEMPLATE = 'filesystem-mcp://file/{+path}';\n\n/**\n * The `{+path}` template-variable form of a path — what `completion/complete`\n * must return, since a client expands a suggestion into the template verbatim.\n * Unescaped, a '#' or '?' in a filename truncates the URI into a fragment or\n * query (silently naming a different path) and a '%' makes the decode throw.\n * Separators are restored so the value still reads as a path.\n */\nexport function encodeFileUriPath(validPath: string): string {\n  const posix = validPath.replace(/\\\\/g, '/');\n  return encodeURIComponent(posix).replace(/%2F/gi, '/');\n}\n\n/** Inverse of {@link encodeFileUriPath}; `undefined` on invalid percent-encoding. */\nexport function decodeFileUriPath(encoded: string): string | undefined {\n  try {\n    return decodeURIComponent(encoded);\n  } catch {\n    return undefined;\n  }\n}\n\nexport function buildFileResourceUri(validPath: string): string {\n  return `filesystem-mcp://file/${encodeFileUriPath(validPath)}`;\n}\n\n/**\n * The link block for a URI already built by `buildFileResourceUri`. Callers that\n * hold the URI must use this rather than rebuilding from a path: a path that\n * differs only in case (the drive letter, on Windows) yields a *different* URI\n * string, and watchers key on that string — a link and a `resourceUri` that\n * disagree hand the client two subscriptions for one file.\n */\nexport function buildFileResourceLinkFor(\n  uri: string,\n  name: string,\n  mimeType: string,\n  size: number,\n  /** ISO-8601 mtime of the file the link names, when the caller has one. */\n  lastModified?: string,\n): ContentBlock {\n  return {\n    type: 'resource_link',\n    uri,\n    name,\n    mimeType,\n    size,\n    annotations: {\n      audience: ['user', 'assistant'],\n      ...(lastModified !== undefined ? { lastModified } : {}),\n    },\n  };\n}\n\nfunction buildFileResourceLink(\n  validPath: string,\n  mimeType: string,\n  size: number,\n  lastModified?: string,\n): ContentBlock {\n  return buildFileResourceLinkFor(\n    buildFileResourceUri(validPath),\n    basename(validPath),\n    mimeType,\n    size,\n    lastModified,\n  );\n}\n\nexport function extractPath(uri: string): string | undefined {\n  const url = URL.parse(uri);\n  if (url?.protocol !== 'filesystem-mcp:' || url.host !== 'file') return undefined;\n  return decodeFileUriPath(url.pathname.slice(1));\n}\n\nexport interface WrittenFileMeta {\n  size: number;\n  lineCount: number;\n  mimeType: string;\n  kind: FileKind;\n  /** Undefined unless {@link writtenFileLinks} allows it: see there for when. */\n  resourceUri: string | undefined;\n  /** Undefined unless {@link writtenFileLinks} allows it: see there for when. */\n  resourceLink: ContentBlock | undefined;\n}\n\n/**\n * The URI and link a write tool may advertise for the file it wrote. None on a\n * dry run — nothing was written, so the file on disk is still the one the\n * caller already has. None when the size is unknown or over the text-size cap —\n * the store serves the URI via readRaw, which would reject it with TOO_LARGE.\n * File resources are read directly from disk, not from the result store.\n * `lastModified` is the post-write mtime when the caller stat'd the file; a\n * link without it is still valid.\n */\nexport function writtenFileLinks(\n  validPath: string,\n  mimeType: string,\n  size: number | undefined,\n  dryRun = false,\n  lastModified?: string,\n): Pick<WrittenFileMeta, 'resourceUri' | 'resourceLink'> {\n  if (dryRun || size === undefined || size > getMaxTextFileSize()) {\n    return { resourceUri: undefined, resourceLink: undefined };\n  }\n  return {\n    resourceUri: buildFileResourceUri(validPath),\n    resourceLink: buildFileResourceLink(validPath, mimeType, size, lastModified),\n  };\n}\n\n/**\n * The block every write tool reports for the content it wrote (or, with\n * `dryRun`, would have written): size, line count, MIME, and whatever\n * {@link writtenFileLinks} allows it to advertise. Named fields, because\n * `validPath` and `content` are both strings and a positional swap type-checks.\n */\nexport function buildWrittenFileMeta(options: {\n  validPath: string;\n  content: string;\n  dryRun?: boolean | undefined;\n  lastModified?: string | undefined;\n}): WrittenFileMeta {\n  const { validPath, content } = options;\n  const size = Buffer.byteLength(content, 'utf-8');\n  const { mimeType, kind } = detectMimeFromContent(validPath, content);\n  return {\n    size,\n    lineCount: countLines(content),\n    mimeType,\n    kind,\n    ...writtenFileLinks(validPath, mimeType, size, options.dryRun, options.lastModified),\n  };\n}\n"]}
+{"version":3,"file":"file-uri.js","sourceRoot":"","sources":["../../src/core/file-uri.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ContentBlock } from '@modelcontextprotocol/server';\n\nimport { basename } from 'node:path';\n\nimport { detectMimeFromContent } from './mime.ts';\nimport type { FileKind } from './mime.ts';\nimport { IS_WINDOWS, toPosixPath } from './path-utils.ts';\nimport { countLines } from './read.ts';\nimport { getMaxTextFileSize, jsonBytesOver, MAX_OUTBOUND_RESULT_BYTES } from './util.ts';\n\nconst KIB = 1024;\n\n// Single owner of the `filesystem-mcp://file/` URI scheme — the template string,\n// the path→URI encoder, the URI→path decoder, the link blocks built from them,\n// and the post-write metadata block every write tool reports alongside them.\n\nexport const FILESYSTEM_FILE_URI_TEMPLATE = 'filesystem-mcp://file/{+path}';\n\n/**\n * The `{+path}` template-variable form of a path — what `completion/complete`\n * must return, since a client expands a suggestion into the template verbatim.\n * Unescaped, a '#' or '?' in a filename truncates the URI into a fragment or\n * query (silently naming a different path) and a '%' makes the decode throw.\n * Separators are restored so the value still reads as a path. A backslash is\n * a separator only on Windows; on POSIX it is part of a name and stays `%5C`,\n * or `a\\b.txt` and `a/b.txt` would share one URI.\n */\nexport function encodeFileUriPath(validPath: string): string {\n  const posix = IS_WINDOWS ? toPosixPath(validPath) : validPath;\n  return encodeURIComponent(posix).replace(/%2F/gi, '/');\n}\n\n/** Inverse of {@link encodeFileUriPath}; `undefined` on invalid percent-encoding. */\nexport function decodeFileUriPath(encoded: string): string | undefined {\n  try {\n    return decodeURIComponent(encoded);\n  } catch {\n    return undefined;\n  }\n}\n\nexport function buildFileResourceUri(validPath: string): string {\n  return `filesystem-mcp://file/${encodeFileUriPath(validPath)}`;\n}\n\n/**\n * The link block for a URI already built by `buildFileResourceUri`. Callers that\n * hold the URI must use this rather than rebuilding from a path: a path that\n * differs only in case (the drive letter, on Windows) yields a *different* URI\n * string, and watchers key on that string — a link and a `resourceUri` that\n * disagree hand the client two subscriptions for one file.\n */\nexport function buildFileResourceLinkFor(\n  uri: string,\n  name: string,\n  mimeType: string,\n  size: number,\n  /** ISO-8601 mtime of the file the link names, when the caller has one. */\n  lastModified?: string,\n): ContentBlock {\n  return {\n    type: 'resource_link',\n    uri,\n    name,\n    mimeType,\n    size,\n    annotations: {\n      audience: ['user', 'assistant'],\n      ...(lastModified !== undefined ? { lastModified } : {}),\n    },\n  };\n}\n\nfunction buildFileResourceLink(\n  validPath: string,\n  mimeType: string,\n  size: number,\n  lastModified?: string,\n): ContentBlock {\n  return buildFileResourceLinkFor(\n    buildFileResourceUri(validPath),\n    basename(validPath),\n    mimeType,\n    size,\n    lastModified,\n  );\n}\n\nexport function extractPath(uri: string): string | undefined {\n  const url = URL.parse(uri);\n  if (url?.protocol !== 'filesystem-mcp:' || url.host !== 'file') return undefined;\n  return decodeFileUriPath(url.pathname.slice(1));\n}\n\nexport interface WrittenFileMeta {\n  size: number;\n  lineCount: number;\n  mimeType: string;\n  kind: FileKind;\n  /** Undefined unless {@link writtenFileLinks} allows it: see there for when. */\n  resourceUri: string | undefined;\n  /** Undefined unless {@link writtenFileLinks} allows it: see there for when. */\n  resourceLink: ContentBlock | undefined;\n}\n\n/**\n * Whether stdio's resources/read would refuse this file: it measures the\n * JSON-encoded result, so escaping counts, and a file it reads as binary\n * comes back base64. Without the content, assume the worst escape (6 bytes\n * per byte) so a link is never one the read refuses.\n */\nfunction overStdioRead(\n  validPath: string,\n  mimeType: string,\n  size: number,\n  written: { content: string; kind: FileKind } | undefined,\n): boolean {\n  if (written === undefined) return 6 * size > MAX_OUTBOUND_RESULT_BYTES - 64 * KIB;\n  // readRaw returns any non-text kind as base64 (`isBinary: kind !== 'text'`).\n  if (written.kind !== 'text') {\n    return 4 * Math.ceil(size / 3) > MAX_OUTBOUND_RESULT_BYTES - 64 * KIB;\n  }\n  const result = {\n    contents: [{ uri: buildFileResourceUri(validPath), mimeType, text: written.content }],\n  };\n  return jsonBytesOver(result, MAX_OUTBOUND_RESULT_BYTES) !== undefined;\n}\n\n/**\n * The URI and link a write tool may advertise for the file it wrote. None on a\n * dry run — nothing was written, so the file on disk is still the one the\n * caller already has. None when the size is unknown or over the text-size cap —\n * the store serves the URI via readRaw, which would reject it with TOO_LARGE.\n * File resources are read directly from disk, not from the result store.\n * `lastModified` is the post-write mtime when the caller stat'd the file; a\n * link without it is still valid. None over stdio when the read would refuse\n * it: the JSON-encoded result past `MAX_OUTBOUND_RESULT_BYTES` (escaping\n * counts, binary is base64), or, with no content to measure, any file whose\n * worst-case escape could be.\n */\nexport function writtenFileLinks(\n  validPath: string,\n  mimeType: string,\n  size: number | undefined,\n  dryRun = false,\n  lastModified?: string,\n  transport?: 'stdio' | 'http',\n  written?: { content: string; kind: FileKind },\n): Pick<WrittenFileMeta, 'resourceUri' | 'resourceLink'> {\n  if (\n    dryRun ||\n    size === undefined ||\n    size > getMaxTextFileSize() ||\n    (transport === 'stdio' && overStdioRead(validPath, mimeType, size, written))\n  ) {\n    return { resourceUri: undefined, resourceLink: undefined };\n  }\n  return {\n    resourceUri: buildFileResourceUri(validPath),\n    resourceLink: buildFileResourceLink(validPath, mimeType, size, lastModified),\n  };\n}\n\n/**\n * The block every write tool reports for the content it wrote (or, with\n * `dryRun`, would have written): size, line count, MIME, and whatever\n * {@link writtenFileLinks} allows it to advertise. Named fields, because\n * `validPath` and `content` are both strings and a positional swap type-checks.\n */\nexport function buildWrittenFileMeta(options: {\n  validPath: string;\n  content: string;\n  dryRun?: boolean | undefined;\n  lastModified?: string | undefined;\n  transport?: 'stdio' | 'http' | undefined;\n}): WrittenFileMeta {\n  const { validPath, content } = options;\n  const size = Buffer.byteLength(content, 'utf-8');\n  const { mimeType, kind } = detectMimeFromContent(validPath, content);\n  return {\n    size,\n    lineCount: countLines(content),\n    mimeType,\n    kind,\n    ...writtenFileLinks(\n      validPath,\n      mimeType,\n      size,\n      options.dryRun,\n      options.lastModified,\n      options.transport,\n      { content, kind },\n    ),\n  };\n}\n"]}

package/dist/core/fmt.d.ts

@@ -10,6 +10,8 @@ export interface ProgressCtx {
 type Phase = 'tick' | 'done' | 'fail';
 export declare function plainMessage(phase: Phase, ctx: ProgressCtx): string;
 export declare function formatCount(count: number, singular: string, plural?: string): string;
+/** Human-readable byte size for tree lines and summary text: `5 B`, `1 KiB`, `1.5 KiB`, `20 KiB`. */
+export declare function formatByteSize(bytes: number): string;
 /**
  * Short label for a path in summary text. `basename` returns '' for a root
  * (`C:\`, `/`) and for a trailing-slash path, which rendered as a bare

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

@@ -1 +1 @@
-{"version":3,"file":"fmt.d.ts","sourceRoot":"","sources":["../../src/core/fmt.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAkCtC,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,CAGnE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAiB,GAAG,MAAM,CAE5F;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAKD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,SAAQ,GAAG,MAAM,CAI9E;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/D;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC/C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C,GAAG,MAAM,CAsBT;AAED,iDAAiD;AACjD,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAG9D;AASD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;CACrB,GAAG,MAAM,GAAG,SAAS,CAWrB"}
+{"version":3,"file":"fmt.d.ts","sourceRoot":"","sources":["../../src/core/fmt.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAkCtC,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,CAGnE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAiB,GAAG,MAAM,CAE5F;AAID,qGAAqG;AACrG,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAapD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAKD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,SAAQ,GAAG,MAAM,CAI9E;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/D;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC/C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C,GAAG,MAAM,CAsBT;AAED,iDAAiD;AACjD,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAG9D;AASD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;CACrB,GAAG,MAAM,GAAG,SAAS,CAWrB"}

package/dist/core/fmt.js

@@ -37,6 +37,22 @@ export function plainMessage(phase, ctx) {
 export function formatCount(count, singular, plural = `${singular}s`) {
     return `${String(count)} ${count === 1 ? singular : plural}`;
 }
+const SIZE_UNITS = ['B', 'KiB', 'MiB', 'GiB', 'TiB'];
+/** Human-readable byte size for tree lines and summary text: `5 B`, `1 KiB`, `1.5 KiB`, `20 KiB`. */
+export function formatByteSize(bytes) {
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < SIZE_UNITS.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    let rounded = unit === 0 || value >= 10 ? Math.round(value) : Math.round(value * 10) / 10;
+    if (rounded >= 1024 && unit < SIZE_UNITS.length - 1) {
+        rounded = 1;
+        unit++;
+    }
+    return `${String(rounded)} ${SIZE_UNITS[unit]}`;
+}
 /**
  * Short label for a path in summary text. `basename` returns '' for a root
  * (`C:\`, `/`) and for a trailing-slash path, which rendered as a bare

package/dist/core/fmt.js.map

@@ -1 +1 @@
-{"version":3,"file":"fmt.js","sourceRoot":"","sources":["../../src/core/fmt.ts"],"names":[],"mappings":"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","sourcesContent":["import { basename } from 'node:path';\n\nimport { MAX_SEARCH_RESULTS } from './util.ts';\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\ntype Phase = '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 '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 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): string {\n  return pattern.length <= 40 ? pattern : `${pattern.slice(0, 40)}…`;\n}\n\n/**\n * `stoppedReason` names the engine's own cap, and `maxResults` is also the name\n * of the caller's page-size argument — spelling the cap out keeps a caller who\n * passed `maxResults: 5` from reading their own argument back.\n */\nconst STOP_REASON_TEXT: Record<string, string> = {\n  maxResults: `hit the server's ${String(MAX_SEARCH_RESULTS)}-result scan cap, not your maxResults`,\n  timeout: 'hit the time limit, or the request was cancelled',\n};\n\n/**\n * The `//` lines a paged search appends to its text block. Paging, the\n * engine's stop state and the files it skipped live in the structured half,\n * which `defineTool` ships under `_meta` for a tool that authors its own text —\n * and no client renders that. These lines are the only place a caller learns\n * that more remains, that the scan was cut, or that files went unexamined (a\n * lone match in an oversized file otherwise reads as \"No matches\"). They are\n * independent: a scan can stop early with too few results to page, so a\n * truncation with no cursor must still say so. Prefixed `//` so none can be\n * mistaken for a result row.\n */\nexport function pageTrailer(p: {\n  offset: number;\n  shown: number;\n  total: number;\n  noun: string;\n  tool: string;\n  nextCursor?: string | undefined;\n  /** The call's own arguments; printed merged with the cursor so the hint is sendable as-is. */\n  nextArgs?: Record<string, unknown> | undefined;\n  stoppedReason?: string | undefined;\n  skippedTooLarge?: number | undefined;\n  skippedInaccessible?: number | undefined;\n}): string {\n  const lines: string[] = [];\n  // Position is owed on every page of a split set, including the last one —\n  // which has no cursor and would otherwise read as the whole answer.\n  if (p.offset > 0 || p.total > p.shown) {\n    const next =\n      p.nextCursor === undefined\n        ? ''\n        : ` Next page: ${p.tool} ${JSON.stringify({ ...p.nextArgs, cursor: p.nextCursor })}`;\n    lines.push(\n      `// showing ${String(p.offset + 1)}-${String(p.offset + p.shown)} of ${String(p.total)} ${p.noun}.${next}`,\n    );\n  }\n  if (p.stoppedReason !== undefined) lines.push(stoppedEarlyLine(p.stoppedReason));\n  const skipped = [\n    p.skippedTooLarge ? `${formatCount(p.skippedTooLarge, 'file')} over the text size limit` : '',\n    p.skippedInaccessible ? formatCount(p.skippedInaccessible, 'inaccessible file') : '',\n  ].filter(Boolean);\n  if (skipped.length > 0) {\n    lines.push(`// skipped ${skipped.join(', ')}; results may be incomplete.`);\n  }\n  return lines.length > 0 ? `\\n\\n${lines.join('\\n')}` : '';\n}\n\n/** The `//` line saying a scan was cut short. */\nexport function stoppedEarlyLine(stoppedReason: string): string {\n  const why = STOP_REASON_TEXT[stoppedReason] ?? `stopped (${stoppedReason})`;\n  return `// scan stopped early: ${why}. That total is a floor, not the count. Narrow path or pattern for the rest.`;\n}\n\n// Regex syntax literal code rarely holds: unspaced alternation (`a|b`, not\n// `||` or a `string | null` union), class escapes, and `.*` / `.+`. Bare `(`,\n// `.`, `[` stay out — `foo(` and `a.b` are ordinary literal needles. A Windows\n// path like `src\\db` can still trip `\\d`; the hint only shows on zero\n// matches, so a stray one costs one line.\nconst REGEX_META = /(?<=[^\\s|])\\|(?=[^\\s|])|\\\\[dDwWsSbB]|\\.[*+]/;\n\n/**\n * The `//` line explaining a zero-match result, or undefined. Without it a\n * regex matched literally, or a glob that selected no files, reads exactly\n * like a genuine miss (issue #55). An `incomplete` scan (files skipped or\n * failed, scan stopped) already has its own line, which explains the zero\n * better, so it gets no hint.\n */\nexport function zeroMatchHint(p: {\n  searchPattern: string;\n  isRegex: boolean;\n  pattern?: string | undefined;\n  filesScanned: number;\n  incomplete: boolean;\n}): string | undefined {\n  if (p.incomplete) return undefined;\n  if (p.filesScanned === 0) {\n    return p.pattern === undefined\n      ? '// no files were searched: nothing under path passed the hidden/ignored/maxDepth filters.'\n      : `// no files were searched: nothing under path matched pattern '${p.pattern}' after the hidden/ignored/maxDepth filters. pattern is a file-name glob; the text to find goes in searchPattern.`;\n  }\n  if (!p.isRegex && REGEX_META.test(p.searchPattern)) {\n    return '// searchPattern was matched as literal text but looks like a regex; pass isRegex=true to match it as one.';\n  }\n  return undefined;\n}\n"]}
+{"version":3,"file":"fmt.js","sourceRoot":"","sources":["../../src/core/fmt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAc/C,SAAS,SAAS,CAAC,GAAgB,EAAE,KAAY;IAC/C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAChB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;IAED,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,MAAM;YACT,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBACzD,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;YAC5C,CAAC;iBAAM,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;gBACrC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YAClC,CAAC;YACD,MAAM;QACR,KAAK,MAAM;YACT,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;gBACd,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACxB,CAAC;YACD,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;gBACf,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACzB,CAAC;YACD,MAAM;QACR,KAAK,MAAM;YACT,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;gBACd,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACxB,CAAC;YACD,MAAM;IACV,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAY,EAAE,GAAgB;IACzD,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,GAAG,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,QAAgB,EAAE,MAAM,GAAG,GAAG,QAAQ,GAAG;IAClF,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAErD,qGAAqG;AACrG,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,OAAO,KAAK,IAAI,IAAI,IAAI,IAAI,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrD,KAAK,IAAI,IAAI,CAAC;QACd,IAAI,EAAE,CAAC;IACT,CAAC;IACD,IAAI,OAAO,GAAG,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC;IAC1F,IAAI,OAAO,IAAI,IAAI,IAAI,IAAI,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpD,OAAO,GAAG,CAAC,CAAC;QACZ,IAAI,EAAE,CAAC;IACT,CAAC;IACD,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AAChC,CAAC;AAED,2FAA2F;AAC3F,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAE5B;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,KAAwB,EAAE,SAAS,GAAG,KAAK;IACpE,IAAI,KAAK,CAAC,MAAM,IAAI,gBAAgB;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC/D,OAAO,GAAG,KAAK,GAAG,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC;AAChF,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,OAAO,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC;AACrE,CAAC;AAED;;;;GAIG;AACH,MAAM,gBAAgB,GAA2B;IAC/C,UAAU,EAAE,oBAAoB,MAAM,CAAC,kBAAkB,CAAC,uCAAuC;IACjG,OAAO,EAAE,kDAAkD;CAC5D,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,CAY3B;IACC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,0EAA0E;IAC1E,oEAAoE;IACpE,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC;QACtC,MAAM,IAAI,GACR,CAAC,CAAC,UAAU,KAAK,SAAS;YACxB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,eAAe,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC;QACzF,KAAK,CAAC,IAAI,CACR,cAAc,MAAM,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,IAAI,EAAE,CAC3G,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,CAAC,aAAa,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;IACjF,MAAM,OAAO,GAAG;QACd,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,eAAe,EAAE,MAAM,CAAC,2BAA2B,CAAC,CAAC,CAAC,EAAE;QAC7F,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,mBAAmB,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC,EAAE;KACrF,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClB,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,cAAc,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC3D,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,gBAAgB,CAAC,aAAqB;IACpD,MAAM,GAAG,GAAG,gBAAgB,CAAC,aAAa,CAAC,IAAI,YAAY,aAAa,GAAG,CAAC;IAC5E,OAAO,0BAA0B,GAAG,8EAA8E,CAAC;AACrH,CAAC;AAED,2EAA2E;AAC3E,8EAA8E;AAC9E,+EAA+E;AAC/E,sEAAsE;AACtE,0CAA0C;AAC1C,MAAM,UAAU,GAAG,6CAA6C,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,CAM7B;IACC,IAAI,CAAC,CAAC,UAAU;QAAE,OAAO,SAAS,CAAC;IACnC,IAAI,CAAC,CAAC,YAAY,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,CAAC,CAAC,OAAO,KAAK,SAAS;YAC5B,CAAC,CAAC,2FAA2F;YAC7F,CAAC,CAAC,kEAAkE,CAAC,CAAC,OAAO,mHAAmH,CAAC;IACrM,CAAC;IACD,IAAI,CAAC,CAAC,CAAC,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC;QACnD,OAAO,4GAA4G,CAAC;IACtH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC","sourcesContent":["import { basename } from 'node:path';\n\nimport { MAX_SEARCH_RESULTS } from './util.ts';\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\ntype Phase = '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 '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 formatCount(count: number, singular: string, plural = `${singular}s`): string {\n  return `${String(count)} ${count === 1 ? singular : plural}`;\n}\n\nconst SIZE_UNITS = ['B', 'KiB', 'MiB', 'GiB', 'TiB'];\n\n/** Human-readable byte size for tree lines and summary text: `5 B`, `1 KiB`, `1.5 KiB`, `20 KiB`. */\nexport function formatByteSize(bytes: number): string {\n  let value = bytes;\n  let unit = 0;\n  while (value >= 1024 && unit < SIZE_UNITS.length - 1) {\n    value /= 1024;\n    unit++;\n  }\n  let rounded = unit === 0 || value >= 10 ? Math.round(value) : Math.round(value * 10) / 10;\n  if (rounded >= 1024 && unit < SIZE_UNITS.length - 1) {\n    rounded = 1;\n    unit++;\n  }\n  return `${String(rounded)} ${SIZE_UNITS[unit]}`;\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): string {\n  return pattern.length <= 40 ? pattern : `${pattern.slice(0, 40)}…`;\n}\n\n/**\n * `stoppedReason` names the engine's own cap, and `maxResults` is also the name\n * of the caller's page-size argument — spelling the cap out keeps a caller who\n * passed `maxResults: 5` from reading their own argument back.\n */\nconst STOP_REASON_TEXT: Record<string, string> = {\n  maxResults: `hit the server's ${String(MAX_SEARCH_RESULTS)}-result scan cap, not your maxResults`,\n  timeout: 'hit the time limit, or the request was cancelled',\n};\n\n/**\n * The `//` lines a paged search appends to its text block. Paging, the\n * engine's stop state and the files it skipped live in the structured half,\n * which `defineTool` ships under `_meta` for a tool that authors its own text —\n * and no client renders that. These lines are the only place a caller learns\n * that more remains, that the scan was cut, or that files went unexamined (a\n * lone match in an oversized file otherwise reads as \"No matches\"). They are\n * independent: a scan can stop early with too few results to page, so a\n * truncation with no cursor must still say so. Prefixed `//` so none can be\n * mistaken for a result row.\n */\nexport function pageTrailer(p: {\n  offset: number;\n  shown: number;\n  total: number;\n  noun: string;\n  tool: string;\n  nextCursor?: string | undefined;\n  /** The call's own arguments; printed merged with the cursor so the hint is sendable as-is. */\n  nextArgs?: Record<string, unknown> | undefined;\n  stoppedReason?: string | undefined;\n  skippedTooLarge?: number | undefined;\n  skippedInaccessible?: number | undefined;\n}): string {\n  const lines: string[] = [];\n  // Position is owed on every page of a split set, including the last one —\n  // which has no cursor and would otherwise read as the whole answer.\n  if (p.offset > 0 || p.total > p.shown) {\n    const next =\n      p.nextCursor === undefined\n        ? ''\n        : ` Next page: ${p.tool} ${JSON.stringify({ ...p.nextArgs, cursor: p.nextCursor })}`;\n    lines.push(\n      `// showing ${String(p.offset + 1)}-${String(p.offset + p.shown)} of ${String(p.total)} ${p.noun}.${next}`,\n    );\n  }\n  if (p.stoppedReason !== undefined) lines.push(stoppedEarlyLine(p.stoppedReason));\n  const skipped = [\n    p.skippedTooLarge ? `${formatCount(p.skippedTooLarge, 'file')} over the text size limit` : '',\n    p.skippedInaccessible ? formatCount(p.skippedInaccessible, 'inaccessible file') : '',\n  ].filter(Boolean);\n  if (skipped.length > 0) {\n    lines.push(`// skipped ${skipped.join(', ')}; results may be incomplete.`);\n  }\n  return lines.length > 0 ? `\\n\\n${lines.join('\\n')}` : '';\n}\n\n/** The `//` line saying a scan was cut short. */\nexport function stoppedEarlyLine(stoppedReason: string): string {\n  const why = STOP_REASON_TEXT[stoppedReason] ?? `stopped (${stoppedReason})`;\n  return `// scan stopped early: ${why}. That total is a floor, not the count. Narrow path or pattern for the rest.`;\n}\n\n// Regex syntax literal code rarely holds: unspaced alternation (`a|b`, not\n// `||` or a `string | null` union), class escapes, and `.*` / `.+`. Bare `(`,\n// `.`, `[` stay out — `foo(` and `a.b` are ordinary literal needles. A Windows\n// path like `src\\db` can still trip `\\d`; the hint only shows on zero\n// matches, so a stray one costs one line.\nconst REGEX_META = /(?<=[^\\s|])\\|(?=[^\\s|])|\\\\[dDwWsSbB]|\\.[*+]/;\n\n/**\n * The `//` line explaining a zero-match result, or undefined. Without it a\n * regex matched literally, or a glob that selected no files, reads exactly\n * like a genuine miss (issue #55). An `incomplete` scan (files skipped or\n * failed, scan stopped) already has its own line, which explains the zero\n * better, so it gets no hint.\n */\nexport function zeroMatchHint(p: {\n  searchPattern: string;\n  isRegex: boolean;\n  pattern?: string | undefined;\n  filesScanned: number;\n  incomplete: boolean;\n}): string | undefined {\n  if (p.incomplete) return undefined;\n  if (p.filesScanned === 0) {\n    return p.pattern === undefined\n      ? '// no files were searched: nothing under path passed the hidden/ignored/maxDepth filters.'\n      : `// no files were searched: nothing under path matched pattern '${p.pattern}' after the hidden/ignored/maxDepth filters. pattern is a file-name glob; the text to find goes in searchPattern.`;\n  }\n  if (!p.isRegex && REGEX_META.test(p.searchPattern)) {\n    return '// searchPattern was matched as literal text but looks like a regex; pass isRegex=true to match it as one.';\n  }\n  return undefined;\n}\n"]}

package/dist/core/fs.d.ts

@@ -1,6 +1,7 @@
 import type { Stats } 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 FileKind } from './mime.ts';
 import type { EntryType as FileType } from './path-utils.ts';
 import type { PathGuard } from './path.ts';
 import type { ReadFileResult, ReadSpec } from './read.ts';
@@ -24,7 +25,7 @@ export declare class GuardedFileSystem {
         validPath: string;
     }>;
     lstat(filePath: string, options?: {
-        signal?: AbortSignal;
+        signal?: AbortSignal | undefined;
     }): Promise<{
         stats: Stats;
         validPath: string;
@@ -84,7 +85,10 @@ export declare class GuardedFileSystem {
     }): Promise<{
         content: Buffer;
         mimeType: string;
+        kind: FileKind;
         isBinary: boolean;
+        validPath: string;
+        modified: string;
     }>;
     open(filePath: string): Promise<FileHandle>;
     statDetailed(filePath: string, options?: {
@@ -95,6 +99,17 @@ export declare class GuardedFileSystem {
         stats: Stats;
     }>;
     hasChildrenUnchecked(dirPath: string): Promise<boolean>;
+    /**
+     * Direct children of a directory, leaving out entries the guard treats as
+     * sensitive so the count never reveals what listings hide. Hidden and
+     * ignored entries count: this answers "is it empty?", not "what would list show?".
+     * A symlinked child counts only when list would show it. The path validation, open, opendir,
+     * each read and each link check race the signal, so a stalled mount ends the call at its
+     * deadline.
+     */
+    countEntries(dirPath: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<number>;
 }
 /**
  * Returns whether `path` exists, treating "not found" as absent and logging any

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

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

package/dist/core/fs.js

@@ -51,38 +51,23 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import { randomUUID } from 'node:crypto';
+import { constants, existsSync } 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 { isAbsolute, join } from 'node:path';
 import { runExclusive, withAbort } from "./concurrency.js";
 import { ErrorCode, formatUnknownErrorMessage, FsError, isFsError, isNodeError, isNotFoundErrno, } from "./errors.js";
 import { detectMimeFromContent, MIME_SAMPLE_SIZE } from "./mime.js";
 import { Logger } from "./observability.js";
-import { normalizePath, respellCaseOnlyTarget } from "./path-utils.js";
-import { APPEND_CREATE_NOFOLLOW, APPEND_NOFOLLOW, assertFileStats, createTooLargeError, READ_NOFOLLOW, readFileWithStats, } from "./read.js";
+import { isSamePath, normalizePath, respellSpellingOnlyTarget } from "./path-utils.js";
+import { APPEND_CREATE_NOFOLLOW, APPEND_NOFOLLOW, assertFileStats, createTooLargeError, O_NOFOLLOW, READ_NOFOLLOW, readFileWithStats, } from "./read.js";
 import { getMaxTextFileSize } from "./util.js";
+// Directory open for countEntries. O_NOFOLLOW refuses a symlink named as the
+// directory; used only under COUNT_THROUGH_FD, like the re-check it feeds.
+const DIR_NOFOLLOW = constants.O_RDONLY | constants.O_DIRECTORY | O_NOFOLLOW;
+// The descriptor re-check and the read through /proc/self/fd need Linux with procfs mounted,
+// as the read path's re-check does; elsewhere the count reads the directory by path.
+const COUNT_THROUGH_FD = process.platform === 'linux' && existsSync('/proc/self/fd');
 // ─── Domain primitives ────────────────────────────────────────────────────────
-/**
- * validatePathForWrite + symlink resolution: a write aimed at a link must land
- * on its revalidated target, not create a new file beside the link. ENOENT is
- * the normal new-file case, so it falls through with the original path.
- */
-async function resolveForWrite(pathGuard, filePath) {
-    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 (!isNotFoundErrno(error)) {
-            throw error;
-        }
-    }
-    return validPath;
-}
 const CHAR_LF = 10;
 const LINE_COUNT_CHUNK_BYTES = 64 * 1024;
 export class GuardedFileSystem {
@@ -95,6 +80,7 @@ export class GuardedFileSystem {
      * for a symlink after validation still passes. Re-read the open descriptor's
      * real path (Linux `/proc/self/fd`; skipped elsewhere) and require it to stay
      * inside the roots. Run before any byte is read or written through `handle`.
+     * Resolves to the normalized real path checked, or undefined when /proc is unreadable.
      */
     async #assertFdWithinRoots(handle, requestedPath) {
         let fdPath;
@@ -102,7 +88,7 @@ export class GuardedFileSystem {
             fdPath = await fsReadlink(`/proc/self/fd/${String(handle.fd)}`);
         }
         catch {
-            return;
+            return undefined;
         }
         // A replaced target reads back as "<path> (deleted)".
         const inRoots = isAbsolute(fdPath) &&
@@ -112,6 +98,7 @@ export class GuardedFileSystem {
         if (!inRoots) {
             throw new FsError(ErrorCode.ACCESS_DENIED, 'Path changed under validation and now resolves outside the allowed roots (TOCTOU).', requestedPath);
         }
+        return normalizePath(fdPath);
     }
     /** The one read open: O_NOFOLLOW, then the descriptor re-check above. */
     async #openVerified(validPath, requestedPath, signal) {
@@ -138,6 +125,23 @@ export class GuardedFileSystem {
             throw error;
         }
     }
+    /**
+     * Waits for `pending` until `signal` fires. A result that lands after the abort goes to
+     * `release` without anyone waiting on it, so a stalled open or read never holds the caller.
+     */
+    async #abandonOnAbort(pending, signal, release, label) {
+        try {
+            return await withAbort(pending, signal);
+        }
+        catch (error) {
+            void pending
+                .then(release, () => undefined)
+                .catch((releaseErr) => {
+                Logger.warn(`Failed to release ${label} after abort: ${formatUnknownErrorMessage(releaseErr)}`);
+            });
+            throw error;
+        }
+    }
     /**
      * Serialize a read-modify-write on the resolved write target, so two writers
      * of one file (any spelling, including via a symlinked parent) cannot both
@@ -145,7 +149,7 @@ export class GuardedFileSystem {
      * do not take the lock, so `fn` may call them.
      */
     async lockForWrite(filePath, fn) {
-        const key = await resolveForWrite(this.pathGuard, filePath);
+        const key = await this.pathGuard.validatePathForWrite(filePath);
         return runExclusive(key, () => fn(key));
     }
     async stat(filePath, options) {
@@ -176,14 +180,19 @@ export class GuardedFileSystem {
         // link would rename its target and leave the link dangling.
         const validOld = await this.pathGuard.validatePathForDelete(oldPath);
         let validNew = await this.pathGuard.validatePathForWrite(newPath);
-        // Renaming a path onto itself is only meaningful as a case-only rename.
-        if (validOld === validNew)
-            validNew = respellCaseOnlyTarget(newPath, validNew);
+        // A new path naming the old entry itself, in another case or Unicode
+        // spelling, renames that entry. Probed without following a final link:
+        // validatePathForWrite resolved a link to its target, and renaming onto
+        // that would replace the target with the link.
+        const sameEntry = await this.pathGuard.validatePathForDelete(newPath).then((entry) => isSamePath(entry, validOld), () => false);
+        if (sameEntry || validOld === validNew) {
+            validNew = respellSpellingOnlyTarget(newPath, sameEntry ? validOld : validNew);
+        }
         await fsRename(validOld, validNew);
     }
     async writeFile(filePath, content, options = {}) {
         const { signal } = options;
-        const validPath = await resolveForWrite(this.pathGuard, filePath);
+        const validPath = await this.pathGuard.validatePathForWrite(filePath);
         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
@@ -242,7 +251,7 @@ export class GuardedFileSystem {
      */
     async appendFile(filePath, content, options = {}) {
         const { signal } = options;
-        const validPath = await resolveForWrite(this.pathGuard, filePath);
+        const validPath = await this.pathGuard.validatePathForWrite(filePath);
         // Non-regular targets must be rejected before the open: 'a' on a FIFO
         // (POSIX) blocks until a reader appears, and fsOpen takes no signal, so
         // the call would hang unabortable and pin its concurrency slot. The
@@ -443,7 +452,10 @@ export class GuardedFileSystem {
             return {
                 content,
                 mimeType: mimeInfo.mimeType,
+                kind: mimeInfo.kind,
                 isBinary: mimeInfo.kind !== 'text',
+                validPath,
+                modified: stats.mtime.toISOString(),
             };
         }
         catch (e_3) {
@@ -480,6 +492,89 @@ export class GuardedFileSystem {
             });
         }
     }
+    /**
+     * Direct children of a directory, leaving out entries the guard treats as
+     * sensitive so the count never reveals what listings hide. Hidden and
+     * ignored entries count: this answers "is it empty?", not "what would list show?".
+     * A symlinked child counts only when list would show it. The path validation, open, opendir,
+     * each read and each link check race the signal, so a stalled mount ends the call at its
+     * deadline.
+     */
+    async countEntries(dirPath, options) {
+        const signal = options?.signal;
+        // Refuse an already-cancelled call before any validation or I/O.
+        signal?.throwIfAborted();
+        // A late validation result is a plain object, so a stalled realpath needs no release.
+        const { resolvedPath } = await withAbort(this.pathGuard.validateExistingPathDetailed(dirPath), signal);
+        // With procfs (COUNT_THROUGH_FD), open the directory itself with O_NOFOLLOW and check where
+        // the open descriptor really is, so a directory or ancestor swapped for a symlink after
+        // validation is refused. Then read entries through the descriptor, which a later swap cannot
+        // redirect.
+        const handle = COUNT_THROUGH_FD
+            ? await this.#abandonOnAbort(fsOpen(resolvedPath, DIR_NOFOLLOW), signal, (late) => late.close(), `directory descriptor for ${resolvedPath}`)
+            : undefined;
+        let dir;
+        let pendingRead;
+        try {
+            const openedPath = handle ? await this.#assertFdWithinRoots(handle, dirPath) : undefined;
+            // An in-root swap passes the roots check, but the children would be filtered under the
+            // validated directory's spelling, not the one actually opened.
+            if (openedPath !== undefined && !isSamePath(openedPath, resolvedPath)) {
+                throw new FsError(ErrorCode.ACCESS_DENIED, 'Path changed under validation and now resolves to another directory (TOCTOU).', dirPath);
+            }
+            const readPath = handle ? `/proc/self/fd/${String(handle.fd)}` : resolvedPath;
+            dir = await this.#abandonOnAbort(fsOpendir(readPath), signal, (late) => late.close(), `directory stream for ${resolvedPath}`);
+            let count = 0;
+            for (;;) {
+                // Each read races the signal, so a read that stalls ends the call at its deadline.
+                const read = dir.read();
+                pendingRead = read;
+                const entry = await withAbort(read, signal);
+                pendingRead = undefined;
+                if (entry === null)
+                    break;
+                if (this.pathGuard.isSensitive(join(dirPath, entry.name)))
+                    continue;
+                // list walks the real directory, so it checks every child, links
+                // included, under its real spelling: a deny rule naming the real
+                // directory hides the child under an alias too.
+                if (this.pathGuard.isSensitive(join(resolvedPath, entry.name)))
+                    continue;
+                // A link counts only when list would show it: same rule, same error policy.
+                if (entry.isSymbolicLink() &&
+                    !(await withAbort(this.pathGuard.isEntryAccessible(join(resolvedPath, entry.name)), signal))) {
+                    continue;
+                }
+                count += 1;
+            }
+            // A deadline that fired during the last read still ends the call, even with no entries left.
+            signal?.throwIfAborted();
+            return count;
+        }
+        finally {
+            if (dir) {
+                const stream = dir;
+                if (pendingRead) {
+                    // close() queues behind a read still in flight, so awaiting it would hold the TIMEOUT
+                    // response on a stalled mount. Close once that read settles, without waiting for it.
+                    void pendingRead
+                        .then(() => stream.close(), () => stream.close())
+                        .catch((closeErr) => {
+                        Logger.warn(`Failed to close dir handle for ${resolvedPath} after abort: ${formatUnknownErrorMessage(closeErr)}`);
+                    });
+                }
+                else {
+                    await stream.close().catch((closeErr) => {
+                        Logger.warn(`Failed to close dir handle for ${resolvedPath}: ${formatUnknownErrorMessage(closeErr)}`);
+                    });
+                }
+            }
+            // A failed close must not replace the error the count threw, so it is logged, not thrown.
+            await handle?.close().catch((closeErr) => {
+                Logger.warn(`Failed to close dir descriptor for ${resolvedPath}: ${formatUnknownErrorMessage(closeErr)}`);
+            });
+        }
+    }
 }
 /**
  * Returns whether `path` exists, treating "not found" as absent and logging any