@j0hanz/filesystem-mcp 2.8.0 → 2.9.0

package/README.md

@@ -40,15 +40,15 @@ Once it is connected, you can ask things like:
 - Search and editing are made for code. The AI can search inside files like
   `grep`, with a regex engine (RE2) that cannot hang, and by default the
   server skips `.gitignore`d files and folders like `node_modules`. Edits are
-  exact-match replacements that fail loudly instead of guessing, and you can
-  preview them as a diff first.
-- It goes easy on the AI's context. The AI can read many files in one call or
+  exact-match replacements that return an error when the text does not match,
+  and you can preview them as a diff first.
+- It saves the AI's context. The AI can read many files in one call or
   only the lines it needs, and it can check a file's size and token estimate
   before reading it.
 - It works with any MCP client, over stdio or HTTP, on macOS, Linux, and
   Windows. You can install it with npx, Docker, or a one-click Claude Desktop
   extension, or [build your own client](#build-your-own-client) on it.
-- It is private: it runs on your machine, has no telemetry, and makes no
+- It is private. It runs on your machine, has no telemetry, and makes no
   network calls.
 
 ### Compared with the reference server
@@ -136,7 +136,8 @@ projects:
 For a one-click install, download
 [`filesystem-mcp.mcpb`](https://github.com/j0hanz/filesystem-mcp/releases/latest/download/filesystem-mcp.mcpb),
 open it with Claude Desktop, and pick the folders to allow. Claude Desktop's
-built-in Node.js runs it.
+built-in Node.js runs it. The extension's settings also let you turn on
+read-only mode and block more files.
 
 To set it up by hand, add this to `claude_desktop_config.json`
 (Settings → Developer → Edit Config):
@@ -205,8 +206,8 @@ sets the server up for your current project:
 <details>
 <summary><b>Docker</b></summary>
 
-The container can only see the folders you mount. This setup is read-only
-twice over: the `:ro` mount and the `--read-only` flag.
+The container can only see the folders you mount. This setup blocks writes
+twice, with the `:ro` mount and with the `--read-only` flag.
 
 ```json
 {
@@ -260,9 +261,9 @@ npm install -g @j0hanz/filesystem-mcp
 | `find_files`     | Finds files by name or glob, such as `**/*.test.ts`.                                                          |
 | `search_text`    | Searches inside files for text or a regex, like `grep`, with optional context lines.                          |
 | `stat`           | Gets size, dates, type, permissions, and a token estimate without reading the file.                           |
-| `read`           | Reads one or many text files, whole or by line range, head, or tail. Images and audio come back as media.     |
+| `read`           | Reads text files whole or by lines, head, or tail. Images and audio come back as media; others with `binary`. |
 | `diff`           | Compares two files and returns a unified diff.                                                                |
-| `create` ✎       | Writes new files, or appends to them. Asks before replacing an existing file, unless `overwrite: true`.       |
+| `create` ✎       | Writes new files, appends, or makes empty folders. Asks before replacing a file, unless `overwrite: true`.    |
 | `edit` ✎         | Replaces exact text in files. All edits to a file apply, or none do. `dryRun` shows the diff first.           |
 | `patch` ✎        | Applies a unified diff to a file. All hunks apply, or none do.                                                |
 | `replace_text` ✎ | Finds and replaces text or a regex across many files. `dryRun` shows what would change.                       |
@@ -298,16 +299,16 @@ with API keys, Docker, and troubleshooting.
 
 ## Security
 
-| Protection         | How it works                                                                                                                                                                                                                                                                                                                                                               |
-| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Folder sandbox     | The server resolves every path, including symlinks, and the resolved path must stay inside an allowed folder.                                                                                                                                                                                                                                                              |
-| Secret files       | `.env`, `*.pem`, `*.key`, SSH keys, `.npmrc`, cloud credentials, and [more](docs/configuration.md#secret-files) are blocked and hidden from listings.                                                                                                                                                                                                                      |
-| You stay in charge | The server asks you before the AI deletes a non-empty folder, gets access to a new folder, or writes over a file with `create` or `move`. Only `create` and copies skip that question, when the AI passes `overwrite: true`. In-place edits (`edit`, `patch`, `replace_text`) do not ask, but `dryRun` previews them. A client that cannot ask gets a clear error instead. |
-| Off-limits folders | Neither the AI nor the client can ever add your home folder itself, system folders, or `~/.ssh`, `~/.aws`, and similar folders.                                                                                                                                                                                                                                            |
-| Safe writes        | New content goes to a temporary file that is then renamed into place, so a crash never leaves a half-written file. Writes keep the file's permissions.                                                                                                                                                                                                                     |
-| No regex hangs     | RE2 runs in linear time, so no search pattern can freeze the server.                                                                                                                                                                                                                                                                                                       |
-| HTTP               | The server listens only on localhost by default. Any other address requires an API key.                                                                                                                                                                                                                                                                                    |
-| Container          | The Docker image runs as a non-root user.                                                                                                                                                                                                                                                                                                                                  |
+| Protection         | How it works                                                                                                                                                                                                                                                                                                                                                          |
+| :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Folder sandbox     | The server resolves every path, including symlinks, and the resolved path must stay inside an allowed folder.                                                                                                                                                                                                                                                         |
+| Secret files       | `.env`, `*.pem`, `*.key`, SSH keys, `.npmrc`, cloud credentials, and [more](docs/configuration.md#secret-files) are blocked and hidden from listings.                                                                                                                                                                                                                 |
+| You stay in charge | The server asks you before the AI deletes a non-empty folder, gets access to a new folder, or writes over a file with `create` or `move`. Only `create` and copies skip that question, when the AI passes `overwrite: true`. In-place edits (`edit`, `patch`, `replace_text`) do not ask, but `dryRun` previews them. A client that cannot ask gets an error instead. |
+| Off-limits folders | Neither the AI nor the client can ever add your home folder itself, system folders, or `~/.ssh`, `~/.aws`, and similar folders.                                                                                                                                                                                                                                       |
+| Safe writes        | New content goes to a temporary file that is then renamed into place, so a crash never leaves a half-written file. Writes keep the file's permissions.                                                                                                                                                                                                                |
+| No regex hangs     | RE2 runs in linear time, so no search pattern can freeze the server.                                                                                                                                                                                                                                                                                                  |
+| HTTP               | The server listens only on localhost by default. Any other address requires an API key.                                                                                                                                                                                                                                                                               |
+| Container          | The Docker image runs as a non-root user.                                                                                                                                                                                                                                                                                                                             |
 
 If you find a vulnerability, please report it privately.
 [SECURITY.md](SECURITY.md) explains how.
@@ -350,8 +351,13 @@ The basics:
   `search_text`, `edit`, ...) and in `structuredContent` for `stat`,
   `create`, and `list_roots`. `read` is the exception: the file's text is
   only in the text block, and `_meta` holds metadata about it.
-- **Paths.** Relative paths resolve against the server's working directory,
-  not its root: set `cwd` over stdio, and send absolute paths over HTTP.
+- **Paths.** A relative path resolves against the server's working directory
+  when that is inside a root, and against the root otherwise. With several
+  roots, it must exist under exactly one of them. Absolute paths are never
+  ambiguous. Search results are printed relative to the root, so a result
+  can be passed straight back. A name that differs from the one on disk only
+  in Unicode form (NFC or NFD) or in its space characters (U+00A0, U+202F)
+  finds that entry.
 - **Confirmations.** Overwrites, recursive deletes, and paths outside the
   roots are questions for the user. Declare the `elicitation` capability and
   answer them in a handler, or, on the 2026-07-28 protocol, take them as data
@@ -376,20 +382,20 @@ clients:
 | [hooks](examples/clients/hooks/)           | Runs a task through a model whenever the workspace changes          |
 | [python](examples/clients/python/)         | A TODO report for a workspace, with the Python SDK                  |
 
-## Privacy Policy
+## Privacy policy
 
 Filesystem MCP runs entirely on your machine. This policy covers the npm
 package, the Docker image, and the `.mcpb` desktop extension.
 
 - **Data collection:** none. The server has no telemetry, analytics, or crash
   reporting, and makes no outbound network requests.
-- **Use and storage:** files are read and written only inside the folders you
-  allow, and only when your MCP client calls a tool. Tool results go to that
+- **Use and storage:** the server reads and writes files only inside the
+  folders you allow, and only when your MCP client calls a tool. Tool results go to that
   client and nowhere else. Short-lived result caches live in memory and
   disappear when the server exits.
 - **Third-party sharing:** none by this server. Your MCP client may send tool
   results to its model provider under that client's own privacy policy.
-- **Retention:** nothing is kept after the process exits. Diagnostic logs go to
+- **Retention:** the server keeps nothing after the process exits. Diagnostic logs go to
   stderr on your machine; your MCP client may save them in its own log files.
 - **Contact:** open an issue at
   <https://github.com/j0hanz/filesystem-mcp/issues>, or report security
@@ -399,7 +405,7 @@ package, the Docker image, and the `.mcpb` desktop extension.
 ## Contributing
 
 Bug reports, ideas, and pull requests are welcome. Start with
-[CONTRIBUTING.md](CONTRIBUTING.md): it covers setup, running the server from
+[CONTRIBUTING.md](CONTRIBUTING.md). It covers setup, running the server from
 source, and the checks a pull request needs.
 
 If Filesystem MCP is useful to you, a star on GitHub helps other people find it.

package/dist/cli-help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-help.d.ts","sourceRoot":"","sources":["../src/cli-help.ts"],"names":[],"mappings":"AA+IA,wBAAgB,gBAAgB,IAAI,KAAK,CA8BxC;AAED,wBAAgB,mBAAmB,IAAI,KAAK,CAG3C"}
+{"version":3,"file":"cli-help.d.ts","sourceRoot":"","sources":["../src/cli-help.ts"],"names":[],"mappings":"AAwJA,wBAAgB,gBAAgB,IAAI,KAAK,CA8BxC;AAED,wBAAgB,mBAAmB,IAAI,KAAK,CAG3C"}

package/dist/cli-help.js

@@ -15,7 +15,7 @@ const OPTIONS_HELP = [
     },
     {
         flags: '--read-only',
-        desc: `Disable write tools: ${[...MUTATING_TOOL_NAMES].sort().join(', ')}`,
+        desc: `Disable write tools: ${[...MUTATING_TOOL_NAMES].sort().join(', ')} (env: FS_READ_ONLY)`,
     },
     { flags: '--print-config', desc: 'Print the active configuration as JSON and exit' },
     {
@@ -39,6 +39,10 @@ const OPTIONS_HELP = [
         flags: '--max-file-size <bytes>',
         desc: 'Maximum file size for reads and for one create call, in bytes; the per-message wire limit is 3 × this + 1 MiB (env: FS_MAX_FILE_SIZE)',
     },
+    {
+        flags: '--tool-timeout <ms>',
+        desc: 'Time limit for one list, stat, read, search or replace_text call, in ms (default 5000, 1000-600000) (env: FS_TOOL_TIMEOUT_MS)',
+    },
     {
         flags: '--walk-cwd',
         desc: 'Walk up from CWD to find a project root; implies --allow-cwd (env: FS_ALLOW_CWD_WALK)',
@@ -77,6 +81,10 @@ const ENV_HELP = [
         flags: 'FS_MAX_FILE_SIZE',
         desc: 'Maximum file size for reads and for one create call, in bytes; sizes the wire limit (3 × this + 1 MiB)',
     },
+    {
+        flags: 'FS_TOOL_TIMEOUT_MS',
+        desc: 'Time limit for one list, stat, read, search or replace_text call, in ms (default 5000, 1000-600000)',
+    },
     {
         flags: 'FS_ALLOWED_DIRS',
         desc: 'Allowed dirs: colon-separated (Unix), semicolon-separated (Windows)',
@@ -94,6 +102,7 @@ const ENV_HELP = [
         flags: 'FS_ALLOW_MISSING_ROOTS',
         desc: 'Start even if configured allowed directories do not exist ("true" or "1" enables this)',
     },
+    { flags: 'FS_READ_ONLY', desc: 'Disable write tools ("true" or "1" enables this)' },
     {
         flags: 'FS_ALLOWED_HOSTS',
         desc: 'Comma-separated Host header values to accept (HTTP transport)',

package/dist/cli-help.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-help.js","sourceRoot":"","sources":["../src/cli-help.ts"],"names":[],"mappings":"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","sourcesContent":["import { styleText } from 'node:util';\n\nimport packageJson from '../package.json' with { type: 'json' };\nimport { MUTATING_TOOL_NAMES } from './tools/index.ts';\n\n// Help text and its rendering. Split out of cli.ts so that module holds only\n// argument parsing and directory validation: this file is static copy plus a\n// formatter, and shares no state with the parser.\n\nconst { version: SERVER_VERSION } = packageJson;\n\ninterface HelpRow {\n  flags: string;\n  desc: string;\n}\n\nconst OPTIONS_HELP: HelpRow[] = [\n  { flags: '-h, --help', desc: 'Show this help message' },\n  { flags: '-v, --version', desc: 'Show the server version' },\n  { flags: '--allow-cwd', desc: 'Add the current working directory as an allowed root' },\n  {\n    flags: '--port <number>',\n    desc: 'Start HTTP transport on this port (env: FS_PORT)',\n  },\n  {\n    flags: '--read-only',\n    desc: `Disable write tools: ${[...MUTATING_TOOL_NAMES].sort().join(', ')}`,\n  },\n  { flags: '--print-config', desc: 'Print the active configuration as JSON and exit' },\n  {\n    flags: '--log-level <level>',\n    desc: 'Log level, RFC 5424: debug|info|notice|warn|error|critical|alert|emergency (env: FS_LOG_LEVEL)',\n  },\n  { flags: '--http-host <host>', desc: 'HTTP server bind address (env: FS_HTTP_HOST)' },\n  {\n    flags: '--api-key <key>',\n    desc: 'Require this API key on HTTP requests; prefer FS_API_KEY (argv is world-readable)',\n  },\n  {\n    flags: '--allow-sensitive',\n    desc: 'Turn off the built-in secret-file denylist (.env, keys, credentials) (env: FS_ALLOW_SENSITIVE)',\n  },\n  {\n    flags: '--root-boundary <path>',\n    desc: 'Require all allowed roots to fall under this path (env: FS_ROOT_BOUNDARY)',\n  },\n  {\n    flags: '--max-file-size <bytes>',\n    desc: 'Maximum file size for reads and for one create call, in bytes; the per-message wire limit is 3 × this + 1 MiB (env: FS_MAX_FILE_SIZE)',\n  },\n  {\n    flags: '--walk-cwd',\n    desc: 'Walk up from CWD to find a project root; implies --allow-cwd (env: FS_ALLOW_CWD_WALK)',\n  },\n  {\n    flags: '--deny <pattern>',\n    desc: 'Block paths matching this pattern; repeatable (env: FS_DENYLIST)',\n  },\n  {\n    flags: '--allow <pattern>',\n    desc: 'Exempt a pattern from the built-in sensitive denylist; repeatable (env: FS_ALLOWLIST)',\n  },\n  {\n    flags: '--allow-missing-roots',\n    desc: 'Start even if configured allowed directories do not exist (env: FS_ALLOW_MISSING_ROOTS)',\n  },\n];\n\nconst ENV_HELP: HelpRow[] = [\n  {\n    flags: 'FS_LOG_LEVEL',\n    desc: 'Log level, RFC 5424: debug|info|notice|warn|error|critical|alert|emergency',\n  },\n  { flags: 'FS_PORT', desc: 'Start HTTP transport on this port (unset = stdio)' },\n  { flags: 'FS_HTTP_HOST', desc: 'HTTP bind address' },\n  { flags: 'FS_API_KEY', desc: 'HTTP API key' },\n  {\n    flags: 'FS_TRUST_PROXY',\n    desc: 'Express trust-proxy setting: hop count or expression (unset = do not trust X-Forwarded-*)',\n  },\n  {\n    flags: 'FS_ALLOW_SENSITIVE',\n    desc: 'Turn off the built-in secret-file denylist (\"true\" or \"1\" enables this)',\n  },\n  { flags: 'FS_ROOT_BOUNDARY', desc: 'Path prefix all allowed roots must fall under' },\n  {\n    flags: 'FS_MAX_FILE_SIZE',\n    desc: 'Maximum file size for reads and for one create call, in bytes; sizes the wire limit (3 × this + 1 MiB)',\n  },\n  {\n    flags: 'FS_ALLOWED_DIRS',\n    desc: 'Allowed dirs: colon-separated (Unix), semicolon-separated (Windows)',\n  },\n  {\n    flags: 'FS_ALLOW_CWD_WALK',\n    desc: 'Walk up from CWD to find a project root (\"true\" or \"1\" enables this)',\n  },\n  { flags: 'FS_DENYLIST', desc: 'Paths/patterns to block, comma-separated' },\n  {\n    flags: 'FS_ALLOWLIST',\n    desc: 'Patterns exempted from the built-in sensitive denylist, comma-separated; --deny/FS_DENYLIST still win',\n  },\n  {\n    flags: 'FS_ALLOW_MISSING_ROOTS',\n    desc: 'Start even if configured allowed directories do not exist (\"true\" or \"1\" enables this)',\n  },\n  {\n    flags: 'FS_ALLOWED_HOSTS',\n    desc: 'Comma-separated Host header values to accept (HTTP transport)',\n  },\n  {\n    flags: 'FS_ALLOWED_ORIGINS',\n    desc: 'Comma-separated origin hostnames for CORS; an extension ID or a lowercase <scheme>://* entry (e.g. moz-extension://*) admits browser extensions',\n  },\n  {\n    flags: 'FS_ALLOW_UNRESTRICTED_HOSTS',\n    desc: 'Bind a wildcard host with no Host validation, accepts the risk (\"true\" or \"1\" enables this)',\n  },\n  { flags: 'FS_PUBLIC_URL', desc: 'Resource identifier URL for RFC 9728 discovery' },\n  {\n    flags: 'FS_RATE_LIMIT_RPM',\n    desc: 'Per-client-IP requests/min (default 120 authenticated, 6000 keyless loopback; 1–100000)',\n  },\n  {\n    flags: 'FS_MAX_WATCHERS',\n    desc: 'Max concurrent file watchers (default 256, 1–4096)',\n  },\n  { flags: 'NO_COLOR', desc: 'Any value disables ANSI color output' },\n  {\n    flags: 'FS_REQUEST_STATE_KEY',\n    desc: 'HMAC key for input_required state; optional, >=32 bytes when set',\n  },\n];\n\nconst EXAMPLES_HELP = [\n  '$ filesystem-mcp /path/to/allowed/dir',\n  '$ filesystem-mcp --allow-cwd',\n  '$ filesystem-mcp /project/src /project/tests --allow-cwd',\n  '$ filesystem-mcp --port 3000 /path/to/allowed/dir',\n  '$ filesystem-mcp --read-only /data/readonly',\n  '$ filesystem-mcp --print-config /project',\n];\n\nexport function printHelpAndExit(): never {\n  // Sized from the longest name so a long one (FS_ALLOW_UNRESTRICTED_HOSTS)\n  // never runs into its description.\n  const COL = Math.max(...[...OPTIONS_HELP, ...ENV_HELP].map(({ flags }) => flags.length)) + 2;\n  // Pad first, colour after: `styleText` honours NO_COLOR, and padding the\n  // plain text keeps the columns aligned whether or not colour is on.\n  const row = (color: 'green' | 'cyan', name: string, desc: string): string =>\n    `  ${styleText(color, name.padEnd(COL))}${desc}`;\n  const dim = (t: string): string => styleText('dim', t);\n  const section = (t: string): string => styleText(['cyan', 'bold'], t);\n\n  const lines = [\n    '',\n    `${styleText('bold', 'Filesystem MCP')} ${dim(`v${SERVER_VERSION}`)}`,\n    '',\n    dim('Pass one or more directories to set the allowed access roots.'),\n    '',\n    section('Options:'),\n    ...OPTIONS_HELP.map(({ flags, desc }) => row('green', flags, desc)),\n    '',\n    `${section('Environment variables:')} ${dim('(flags win when both are set; --deny/--allow add to FS_DENYLIST/FS_ALLOWLIST)')}`,\n    ...ENV_HELP.map(({ flags, desc }) => row('cyan', flags, desc)),\n    '',\n    section('Examples:'),\n    ...EXAMPLES_HELP.map((ex) => `  ${dim(ex)}`),\n    '',\n  ];\n\n  process.stdout.write(lines.join('\\n'));\n  process.exit(0);\n}\n\nexport function printVersionAndExit(): never {\n  process.stdout.write(`${styleText('cyan', SERVER_VERSION)}\\n`);\n  process.exit(0);\n}\n"]}
+{"version":3,"file":"cli-help.js","sourceRoot":"","sources":["../src/cli-help.ts"],"names":[],"mappings":"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","sourcesContent":["import { styleText } from 'node:util';\n\nimport packageJson from '../package.json' with { type: 'json' };\nimport { MUTATING_TOOL_NAMES } from './tools/index.ts';\n\n// Help text and its rendering. Split out of cli.ts so that module holds only\n// argument parsing and directory validation: this file is static copy plus a\n// formatter, and shares no state with the parser.\n\nconst { version: SERVER_VERSION } = packageJson;\n\ninterface HelpRow {\n  flags: string;\n  desc: string;\n}\n\nconst OPTIONS_HELP: HelpRow[] = [\n  { flags: '-h, --help', desc: 'Show this help message' },\n  { flags: '-v, --version', desc: 'Show the server version' },\n  { flags: '--allow-cwd', desc: 'Add the current working directory as an allowed root' },\n  {\n    flags: '--port <number>',\n    desc: 'Start HTTP transport on this port (env: FS_PORT)',\n  },\n  {\n    flags: '--read-only',\n    desc: `Disable write tools: ${[...MUTATING_TOOL_NAMES].sort().join(', ')} (env: FS_READ_ONLY)`,\n  },\n  { flags: '--print-config', desc: 'Print the active configuration as JSON and exit' },\n  {\n    flags: '--log-level <level>',\n    desc: 'Log level, RFC 5424: debug|info|notice|warn|error|critical|alert|emergency (env: FS_LOG_LEVEL)',\n  },\n  { flags: '--http-host <host>', desc: 'HTTP server bind address (env: FS_HTTP_HOST)' },\n  {\n    flags: '--api-key <key>',\n    desc: 'Require this API key on HTTP requests; prefer FS_API_KEY (argv is world-readable)',\n  },\n  {\n    flags: '--allow-sensitive',\n    desc: 'Turn off the built-in secret-file denylist (.env, keys, credentials) (env: FS_ALLOW_SENSITIVE)',\n  },\n  {\n    flags: '--root-boundary <path>',\n    desc: 'Require all allowed roots to fall under this path (env: FS_ROOT_BOUNDARY)',\n  },\n  {\n    flags: '--max-file-size <bytes>',\n    desc: 'Maximum file size for reads and for one create call, in bytes; the per-message wire limit is 3 × this + 1 MiB (env: FS_MAX_FILE_SIZE)',\n  },\n  {\n    flags: '--tool-timeout <ms>',\n    desc: 'Time limit for one list, stat, read, search or replace_text call, in ms (default 5000, 1000-600000) (env: FS_TOOL_TIMEOUT_MS)',\n  },\n  {\n    flags: '--walk-cwd',\n    desc: 'Walk up from CWD to find a project root; implies --allow-cwd (env: FS_ALLOW_CWD_WALK)',\n  },\n  {\n    flags: '--deny <pattern>',\n    desc: 'Block paths matching this pattern; repeatable (env: FS_DENYLIST)',\n  },\n  {\n    flags: '--allow <pattern>',\n    desc: 'Exempt a pattern from the built-in sensitive denylist; repeatable (env: FS_ALLOWLIST)',\n  },\n  {\n    flags: '--allow-missing-roots',\n    desc: 'Start even if configured allowed directories do not exist (env: FS_ALLOW_MISSING_ROOTS)',\n  },\n];\n\nconst ENV_HELP: HelpRow[] = [\n  {\n    flags: 'FS_LOG_LEVEL',\n    desc: 'Log level, RFC 5424: debug|info|notice|warn|error|critical|alert|emergency',\n  },\n  { flags: 'FS_PORT', desc: 'Start HTTP transport on this port (unset = stdio)' },\n  { flags: 'FS_HTTP_HOST', desc: 'HTTP bind address' },\n  { flags: 'FS_API_KEY', desc: 'HTTP API key' },\n  {\n    flags: 'FS_TRUST_PROXY',\n    desc: 'Express trust-proxy setting: hop count or expression (unset = do not trust X-Forwarded-*)',\n  },\n  {\n    flags: 'FS_ALLOW_SENSITIVE',\n    desc: 'Turn off the built-in secret-file denylist (\"true\" or \"1\" enables this)',\n  },\n  { flags: 'FS_ROOT_BOUNDARY', desc: 'Path prefix all allowed roots must fall under' },\n  {\n    flags: 'FS_MAX_FILE_SIZE',\n    desc: 'Maximum file size for reads and for one create call, in bytes; sizes the wire limit (3 × this + 1 MiB)',\n  },\n  {\n    flags: 'FS_TOOL_TIMEOUT_MS',\n    desc: 'Time limit for one list, stat, read, search or replace_text call, in ms (default 5000, 1000-600000)',\n  },\n  {\n    flags: 'FS_ALLOWED_DIRS',\n    desc: 'Allowed dirs: colon-separated (Unix), semicolon-separated (Windows)',\n  },\n  {\n    flags: 'FS_ALLOW_CWD_WALK',\n    desc: 'Walk up from CWD to find a project root (\"true\" or \"1\" enables this)',\n  },\n  { flags: 'FS_DENYLIST', desc: 'Paths/patterns to block, comma-separated' },\n  {\n    flags: 'FS_ALLOWLIST',\n    desc: 'Patterns exempted from the built-in sensitive denylist, comma-separated; --deny/FS_DENYLIST still win',\n  },\n  {\n    flags: 'FS_ALLOW_MISSING_ROOTS',\n    desc: 'Start even if configured allowed directories do not exist (\"true\" or \"1\" enables this)',\n  },\n  { flags: 'FS_READ_ONLY', desc: 'Disable write tools (\"true\" or \"1\" enables this)' },\n  {\n    flags: 'FS_ALLOWED_HOSTS',\n    desc: 'Comma-separated Host header values to accept (HTTP transport)',\n  },\n  {\n    flags: 'FS_ALLOWED_ORIGINS',\n    desc: 'Comma-separated origin hostnames for CORS; an extension ID or a lowercase <scheme>://* entry (e.g. moz-extension://*) admits browser extensions',\n  },\n  {\n    flags: 'FS_ALLOW_UNRESTRICTED_HOSTS',\n    desc: 'Bind a wildcard host with no Host validation, accepts the risk (\"true\" or \"1\" enables this)',\n  },\n  { flags: 'FS_PUBLIC_URL', desc: 'Resource identifier URL for RFC 9728 discovery' },\n  {\n    flags: 'FS_RATE_LIMIT_RPM',\n    desc: 'Per-client-IP requests/min (default 120 authenticated, 6000 keyless loopback; 1–100000)',\n  },\n  {\n    flags: 'FS_MAX_WATCHERS',\n    desc: 'Max concurrent file watchers (default 256, 1–4096)',\n  },\n  { flags: 'NO_COLOR', desc: 'Any value disables ANSI color output' },\n  {\n    flags: 'FS_REQUEST_STATE_KEY',\n    desc: 'HMAC key for input_required state; optional, >=32 bytes when set',\n  },\n];\n\nconst EXAMPLES_HELP = [\n  '$ filesystem-mcp /path/to/allowed/dir',\n  '$ filesystem-mcp --allow-cwd',\n  '$ filesystem-mcp /project/src /project/tests --allow-cwd',\n  '$ filesystem-mcp --port 3000 /path/to/allowed/dir',\n  '$ filesystem-mcp --read-only /data/readonly',\n  '$ filesystem-mcp --print-config /project',\n];\n\nexport function printHelpAndExit(): never {\n  // Sized from the longest name so a long one (FS_ALLOW_UNRESTRICTED_HOSTS)\n  // never runs into its description.\n  const COL = Math.max(...[...OPTIONS_HELP, ...ENV_HELP].map(({ flags }) => flags.length)) + 2;\n  // Pad first, colour after: `styleText` honours NO_COLOR, and padding the\n  // plain text keeps the columns aligned whether or not colour is on.\n  const row = (color: 'green' | 'cyan', name: string, desc: string): string =>\n    `  ${styleText(color, name.padEnd(COL))}${desc}`;\n  const dim = (t: string): string => styleText('dim', t);\n  const section = (t: string): string => styleText(['cyan', 'bold'], t);\n\n  const lines = [\n    '',\n    `${styleText('bold', 'Filesystem MCP')} ${dim(`v${SERVER_VERSION}`)}`,\n    '',\n    dim('Pass one or more directories to set the allowed access roots.'),\n    '',\n    section('Options:'),\n    ...OPTIONS_HELP.map(({ flags, desc }) => row('green', flags, desc)),\n    '',\n    `${section('Environment variables:')} ${dim('(flags win when both are set; --deny/--allow add to FS_DENYLIST/FS_ALLOWLIST)')}`,\n    ...ENV_HELP.map(({ flags, desc }) => row('cyan', flags, desc)),\n    '',\n    section('Examples:'),\n    ...EXAMPLES_HELP.map((ex) => `  ${dim(ex)}`),\n    '',\n  ];\n\n  process.stdout.write(lines.join('\\n'));\n  process.exit(0);\n}\n\nexport function printVersionAndExit(): never {\n  process.stdout.write(`${styleText('cyan', SERVER_VERSION)}\\n`);\n  process.exit(0);\n}\n"]}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA0BA,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAyGD,wBAAsB,SAAS,IAAI,OAAO,CAAC;IACzC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,CAAC,CAqED;AAMD,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,GAC7C,OAAO,CAAC,IAAI,CAAC,CAmDf"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA+BA,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAgHD,wBAAsB,SAAS,IAAI,OAAO,CAAC;IACzC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,CAAC,CAuED;AAMD,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,GAC7C,OAAO,CAAC,IAAI,CAAC,CAoDf"}

package/dist/cli.js

@@ -5,10 +5,10 @@ import packageJson from '../package.json' with { type: 'json' };
 import { printHelpAndExit, printVersionAndExit } from "./cli-help.js";
 import { cli, MODERN_PROTOCOL_REVISION } from "./core/config.js";
 import { formatUnknownErrorMessage } from "./core/errors.js";
-import { getReservedDeviceNameForPath, IS_WINDOWS, isWindowsDriveRelativePath, normalizePath, parseTrueEnvFlag, } from "./core/path-utils.js";
+import { getReservedDeviceNameForPath, IS_WINDOWS, isWindowsDrivePath, isWindowsDriveRelativePath, normalizePath, } from "./core/path-utils.js";
 import { PathGuard } from "./core/path.js";
 import { describeSensitivePolicy } from "./core/sensitive.js";
-import { getMaxInboundMessageBytes, getMaxTextFileSize } from "./core/util.js";
+import { getMaxInboundMessageBytes, getMaxTextFileSize, getToolTimeoutMs, parseTrueEnvFlag, } from "./core/util.js";
 import { registeredTools } from "./tools/index.js";
 // ════════════════════════════════════════════════════════════
 // Path & Config Utilities — pure functions and error types
@@ -23,6 +23,9 @@ function validateCliPath(inputPath) {
     if (inputPath.includes('\0')) {
         throw new CliExitError('Path contains null bytes.');
     }
+    if (!IS_WINDOWS && isWindowsDrivePath(inputPath)) {
+        throw new CliExitError(`Windows-style path received on a POSIX host (${process.platform}): ${inputPath}. Use a POSIX path.`);
+    }
     if (isWindowsDriveRelativePath(inputPath)) {
         throw new CliExitError('Windows drive-relative paths are not allowed. Use C:\\path or C:/path instead of C:path.');
     }
@@ -102,6 +105,7 @@ const CLI_PARSER_CONFIG = {
         'allow-sensitive': { type: 'boolean', default: false },
         'root-boundary': { type: 'string' },
         'max-file-size': { type: 'string' },
+        'tool-timeout': { type: 'string' },
         'walk-cwd': { type: 'boolean', default: false },
         deny: { type: 'string', multiple: true },
         allow: { type: 'string', multiple: true },
@@ -135,6 +139,8 @@ export async function parseArgs() {
             cli.logLevel = v['log-level'];
         if (v['max-file-size'] !== undefined)
             cli.maxFileSize = v['max-file-size'];
+        if (v['tool-timeout'] !== undefined)
+            cli.toolTimeout = v['tool-timeout'];
         if (v['root-boundary'] !== undefined)
             cli.rootBoundary = v['root-boundary'];
         if (v['allow-sensitive'])
@@ -155,7 +161,7 @@ export async function parseArgs() {
         const allowCwd = v['allow-cwd'] ||
             v['walk-cwd'] ||
             parseTrueEnvFlag(process.env['FS_ALLOW_CWD_WALK'], 'FS_ALLOW_CWD_WALK');
-        const readOnly = v['read-only'];
+        const readOnly = v['read-only'] || parseTrueEnvFlag(process.env['FS_READ_ONLY'], 'FS_READ_ONLY');
         const printConfig = v['print-config'];
         const port = parsePortOption(v.port ?? process.env['FS_PORT']);
         const allowMissingRoots = v['allow-missing-roots'] ||
@@ -202,6 +208,7 @@ export async function runPrintConfig(options) {
         limits: {
             maxFileSizeBytes: getMaxTextFileSize(),
             maxInboundMessageBytes: getMaxInboundMessageBytes(),
+            toolTimeoutMs: getToolTimeoutMs(),
         },
         // What the binary negotiates with, so an era mismatch ("unsupported
         // protocol version") can be diagnosed without attaching a client. The

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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","sourcesContent":["import { LATEST_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS } from '@modelcontextprotocol/server';\n\nimport type { Stats } from 'node:fs';\nimport { stat } from 'node:fs/promises';\nimport { parseArgs as utilParseArgs } from 'node:util';\n\nimport packageJson from '../package.json' with { type: 'json' };\nimport { printHelpAndExit, printVersionAndExit } from './cli-help.ts';\nimport { cli, MODERN_PROTOCOL_REVISION } from './core/config.ts';\nimport { formatUnknownErrorMessage } from './core/errors.ts';\nimport {\n  getReservedDeviceNameForPath,\n  IS_WINDOWS,\n  isWindowsDriveRelativePath,\n  normalizePath,\n  parseTrueEnvFlag,\n} from './core/path-utils.ts';\nimport { PathGuard } from './core/path.ts';\nimport { describeSensitivePolicy } from './core/sensitive.ts';\nimport { getMaxInboundMessageBytes, getMaxTextFileSize } from './core/util.ts';\nimport { registeredTools } from './tools/index.ts';\n\n// ════════════════════════════════════════════════════════════\n// Path & Config Utilities — pure functions and error types\n// ════════════════════════════════════════════════════════════\n\nexport class CliExitError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'CliExitError';\n  }\n}\n\nfunction validateCliPath(inputPath: string): void {\n  if (inputPath.includes('\\0')) {\n    throw new CliExitError('Path contains null bytes.');\n  }\n\n  if (isWindowsDriveRelativePath(inputPath)) {\n    throw new CliExitError(\n      'Windows drive-relative paths are not allowed. Use C:\\\\path or C:/path instead of C:path.',\n    );\n  }\n\n  const reserved = IS_WINDOWS ? getReservedDeviceNameForPath(inputPath) : undefined;\n  if (reserved) {\n    throw new CliExitError(`Windows reserved device name not allowed: ${reserved}.`);\n  }\n}\n\nasync function validateDirectoryPath(inputPath: string, allowMissing = false): Promise<string> {\n  const normalized = normalizePath(inputPath);\n\n  let stats: Stats;\n  try {\n    stats = await stat(normalized);\n  } catch (error) {\n    if (allowMissing) return normalized;\n    // Node's own message already names the syscall and the errno.\n    throw new Error(`Cannot access directory ${inputPath}: ${formatUnknownErrorMessage(error)}`, {\n      cause: error,\n    });\n  }\n\n  if (!stats.isDirectory()) throw new Error(`${inputPath} is not a directory`);\n  return normalized;\n}\n\n// No dedupe here: PathGuard's `normalizeAllowedDirectories` already Set-dedupes\n// the normalized set, and containment checks are case-insensitive where the\n// filesystem is.\nasync function normalizeAndValidateDirs(\n  paths: readonly string[],\n  allowMissing = false,\n): Promise<string[]> {\n  const normalized: string[] = [];\n  for (const p of paths) {\n    normalized.push(await validateDirectoryPath(p, allowMissing));\n  }\n  return normalized;\n}\n\nfunction normalizeCliExitMessage(error: unknown): string {\n  const rawMessage = formatUnknownErrorMessage(error);\n  return rawMessage.startsWith('Error:') ? rawMessage : `Error: ${rawMessage}`;\n}\n\nfunction parsePortOption(raw: unknown): number | undefined {\n  // '' reads as unset: FS_PORT set-but-empty (compose templating) means stdio.\n  if (raw === undefined || raw === '') return undefined;\n  const n = Number(raw);\n  if (!Number.isInteger(n) || n < 1 || n > 65535) {\n    throw new CliExitError(`Error: --port / FS_PORT must be an integer between 1 and 65535`);\n  }\n  return n;\n}\n\nconst ENV_PLACEHOLDER = /^\\$\\{([A-Za-z_]\\w*)\\}$/;\n\n/**\n * Plugin hosts start servers outside the project and substitute only the\n * variables they know: Antigravity CLI passes `${PWD}` through verbatim, and\n * Copilot CLI does when the launching shell exported no PWD (PowerShell, cmd).\n * A whole-argument `${NAME}` resolves from this process's environment; unset\n * or empty drops it, so it never becomes a bogus relative root.\n */\nfunction expandEnvPlaceholder(arg: string): string[] {\n  const name = ENV_PLACEHOLDER.exec(arg)?.[1];\n  if (name === undefined) return [arg];\n  const value = process.env[name];\n  return value ? [value] : [];\n}\n\nconst CLI_PARSER_CONFIG = {\n  options: {\n    'allow-cwd': { type: 'boolean', default: false },\n    'read-only': { type: 'boolean', default: false },\n    'print-config': { type: 'boolean', default: false },\n    port: { type: 'string' },\n    help: { type: 'boolean', short: 'h' },\n    version: { type: 'boolean', short: 'v' },\n    'log-level': { type: 'string' },\n    'http-host': { type: 'string' },\n    'api-key': { type: 'string' },\n    'allow-sensitive': { type: 'boolean', default: false },\n    'root-boundary': { type: 'string' },\n    'max-file-size': { type: 'string' },\n    'walk-cwd': { type: 'boolean', default: false },\n    deny: { type: 'string', multiple: true },\n    allow: { type: 'string', multiple: true },\n    'allow-missing-roots': { type: 'boolean', default: false },\n  },\n  strict: true,\n  allowPositionals: true,\n} as const;\n\nexport async function parseArgs(): Promise<{\n  allowedDirs: string[];\n  allowCwd: boolean;\n  port: number | undefined;\n  readOnly: boolean;\n  printConfig: boolean;\n  httpHost: string | undefined;\n  apiKey: string | undefined;\n}> {\n  try {\n    const parsed = utilParseArgs(CLI_PARSER_CONFIG);\n\n    if (parsed.values.help) {\n      printHelpAndExit();\n    }\n\n    if (parsed.values.version) {\n      printVersionAndExit();\n    }\n\n    const positionals = parsed.positionals.flatMap(expandEnvPlaceholder);\n    for (const positional of positionals) {\n      validateCliPath(positional);\n    }\n\n    const v = parsed.values;\n    // `--http-host` and `--api-key` are returned to the caller and handed to\n    // the server as config. Every other flag lands in the CLI-override store\n    // (core/config.ts) — the one owner of the flag-beats-env rule — which deep\n    // core readers (path, sensitive, observability, util) consult before\n    // falling back to the operator's environment. Nothing writes process.env.\n    const httpHost = v['http-host'] ?? process.env['FS_HTTP_HOST'];\n    const apiKey = v['api-key'] ?? process.env['FS_API_KEY'];\n    if (v['log-level'] !== undefined) cli.logLevel = v['log-level'];\n    if (v['max-file-size'] !== undefined) cli.maxFileSize = v['max-file-size'];\n    if (v['root-boundary'] !== undefined) cli.rootBoundary = v['root-boundary'];\n    if (v['allow-sensitive']) cli.allowSensitive = true;\n    if (v['walk-cwd']) cli.allowCwdWalk = true;\n    if (v['allow-missing-roots']) cli.allowMissingRoots = true;\n    const patternList = (entries: readonly string[] | undefined): readonly string[] => [\n      ...new Set((entries ?? []).map((entry) => entry.trim()).filter(Boolean)),\n    ];\n    const denyPatterns = patternList(v.deny);\n    if (denyPatterns.length > 0) cli.denyPatterns = denyPatterns;\n    const allowPatterns = patternList(v.allow);\n    if (allowPatterns.length > 0) cli.allowPatterns = allowPatterns;\n\n    const allowCwd =\n      v['allow-cwd'] ||\n      v['walk-cwd'] ||\n      parseTrueEnvFlag(process.env['FS_ALLOW_CWD_WALK'], 'FS_ALLOW_CWD_WALK');\n    const readOnly = v['read-only'];\n    const printConfig = v['print-config'];\n    const port = parsePortOption(v.port ?? process.env['FS_PORT']);\n    const allowMissingRoots =\n      v['allow-missing-roots'] ||\n      parseTrueEnvFlag(process.env['FS_ALLOW_MISSING_ROOTS'], 'FS_ALLOW_MISSING_ROOTS');\n\n    const allowedDirs =\n      positionals.length > 0 ? await normalizeAndValidateDirs(positionals, allowMissingRoots) : [];\n\n    return {\n      allowedDirs,\n      allowCwd,\n      port,\n      readOnly,\n      printConfig,\n      httpHost,\n      apiKey,\n    };\n  } catch (error: unknown) {\n    if (error instanceof CliExitError) {\n      throw error;\n    }\n\n    throw new CliExitError(normalizeCliExitMessage(error));\n  }\n}\n\n// ════════════════════════════════════════════════════════════\n// Effective config reporting — prints the resolved server config as JSON\n// ════════════════════════════════════════════════════════════\n\nexport async function runPrintConfig(\n  options: Awaited<ReturnType<typeof parseArgs>>,\n): Promise<void> {\n  const pathGuard = new PathGuard({\n    allowCwd: options.allowCwd,\n    cliAllowedDirs: options.allowedDirs,\n  });\n  await pathGuard.recomputeAllowedDirectories();\n  const allowedRoots = pathGuard.getRoots();\n\n  const tools = registeredTools(options.readOnly).map((t) => t.name);\n\n  // Derived, never assumed: `--print-config --port 3000` reports the HTTP bind\n  // that `--port` would actually have started, not the stdio default.\n  const config = {\n    transport:\n      options.port !== undefined\n        ? `http://${options.httpHost ?? '127.0.0.1'}:${String(options.port)}`\n        : 'stdio',\n    readOnly: options.readOnly,\n    allowedRoots,\n    tools,\n    apiKey: options.apiKey ? '***' : null,\n    limits: {\n      maxFileSizeBytes: getMaxTextFileSize(),\n      maxInboundMessageBytes: getMaxInboundMessageBytes(),\n    },\n    // What the binary negotiates with, so an era mismatch (\"unsupported\n    // protocol version\") can be diagnosed without attaching a client. The\n    // legacy list is the SDK's own; the modern revision has no SDK export.\n    // The pins are exact (package.json), so the manifest value is the\n    // installed one.\n    protocol: {\n      modern: MODERN_PROTOCOL_REVISION,\n      legacy: { latest: LATEST_PROTOCOL_VERSION, supported: SUPPORTED_PROTOCOL_VERSIONS },\n      sdk: {\n        server: packageJson.dependencies['@modelcontextprotocol/server'],\n        node: packageJson.dependencies['@modelcontextprotocol/node'],\n        express: packageJson.dependencies['@modelcontextprotocol/express'],\n      },\n    },\n    // Everything that can produce ACCESS_DENIED, read through the same\n    // sources the guard and the matcher use (flag beats env).\n    policy: {\n      ...describeSensitivePolicy(),\n      rootBoundary: cli.rootBoundary ?? process.env['FS_ROOT_BOUNDARY'] ?? null,\n      allowMissingRoots:\n        cli.allowMissingRoots ??\n        parseTrueEnvFlag(process.env['FS_ALLOW_MISSING_ROOTS'], 'FS_ALLOW_MISSING_ROOTS'),\n    },\n  };\n\n  process.stdout.write(`${JSON.stringify(config, null, 2)}\\n`);\n}\n"]}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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","sourcesContent":["import { LATEST_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS } from '@modelcontextprotocol/server';\n\nimport type { Stats } from 'node:fs';\nimport { stat } from 'node:fs/promises';\nimport { parseArgs as utilParseArgs } from 'node:util';\n\nimport packageJson from '../package.json' with { type: 'json' };\nimport { printHelpAndExit, printVersionAndExit } from './cli-help.ts';\nimport { cli, MODERN_PROTOCOL_REVISION } from './core/config.ts';\nimport { formatUnknownErrorMessage } from './core/errors.ts';\nimport {\n  getReservedDeviceNameForPath,\n  IS_WINDOWS,\n  isWindowsDrivePath,\n  isWindowsDriveRelativePath,\n  normalizePath,\n} from './core/path-utils.ts';\nimport { PathGuard } from './core/path.ts';\nimport { describeSensitivePolicy } from './core/sensitive.ts';\nimport {\n  getMaxInboundMessageBytes,\n  getMaxTextFileSize,\n  getToolTimeoutMs,\n  parseTrueEnvFlag,\n} from './core/util.ts';\nimport { registeredTools } from './tools/index.ts';\n\n// ════════════════════════════════════════════════════════════\n// Path & Config Utilities — pure functions and error types\n// ════════════════════════════════════════════════════════════\n\nexport class CliExitError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'CliExitError';\n  }\n}\n\nfunction validateCliPath(inputPath: string): void {\n  if (inputPath.includes('\\0')) {\n    throw new CliExitError('Path contains null bytes.');\n  }\n\n  if (!IS_WINDOWS && isWindowsDrivePath(inputPath)) {\n    throw new CliExitError(\n      `Windows-style path received on a POSIX host (${process.platform}): ${inputPath}. Use a POSIX path.`,\n    );\n  }\n\n  if (isWindowsDriveRelativePath(inputPath)) {\n    throw new CliExitError(\n      'Windows drive-relative paths are not allowed. Use C:\\\\path or C:/path instead of C:path.',\n    );\n  }\n\n  const reserved = IS_WINDOWS ? getReservedDeviceNameForPath(inputPath) : undefined;\n  if (reserved) {\n    throw new CliExitError(`Windows reserved device name not allowed: ${reserved}.`);\n  }\n}\n\nasync function validateDirectoryPath(inputPath: string, allowMissing = false): Promise<string> {\n  const normalized = normalizePath(inputPath);\n\n  let stats: Stats;\n  try {\n    stats = await stat(normalized);\n  } catch (error) {\n    if (allowMissing) return normalized;\n    // Node's own message already names the syscall and the errno.\n    throw new Error(`Cannot access directory ${inputPath}: ${formatUnknownErrorMessage(error)}`, {\n      cause: error,\n    });\n  }\n\n  if (!stats.isDirectory()) throw new Error(`${inputPath} is not a directory`);\n  return normalized;\n}\n\n// No dedupe here: PathGuard's `normalizeAllowedDirectories` already Set-dedupes\n// the normalized set, and containment checks are case-insensitive where the\n// filesystem is.\nasync function normalizeAndValidateDirs(\n  paths: readonly string[],\n  allowMissing = false,\n): Promise<string[]> {\n  const normalized: string[] = [];\n  for (const p of paths) {\n    normalized.push(await validateDirectoryPath(p, allowMissing));\n  }\n  return normalized;\n}\n\nfunction normalizeCliExitMessage(error: unknown): string {\n  const rawMessage = formatUnknownErrorMessage(error);\n  return rawMessage.startsWith('Error:') ? rawMessage : `Error: ${rawMessage}`;\n}\n\nfunction parsePortOption(raw: unknown): number | undefined {\n  // '' reads as unset: FS_PORT set-but-empty (compose templating) means stdio.\n  if (raw === undefined || raw === '') return undefined;\n  const n = Number(raw);\n  if (!Number.isInteger(n) || n < 1 || n > 65535) {\n    throw new CliExitError(`Error: --port / FS_PORT must be an integer between 1 and 65535`);\n  }\n  return n;\n}\n\nconst ENV_PLACEHOLDER = /^\\$\\{([A-Za-z_]\\w*)\\}$/;\n\n/**\n * Plugin hosts start servers outside the project and substitute only the\n * variables they know: Antigravity CLI passes `${PWD}` through verbatim, and\n * Copilot CLI does when the launching shell exported no PWD (PowerShell, cmd).\n * A whole-argument `${NAME}` resolves from this process's environment; unset\n * or empty drops it, so it never becomes a bogus relative root.\n */\nfunction expandEnvPlaceholder(arg: string): string[] {\n  const name = ENV_PLACEHOLDER.exec(arg)?.[1];\n  if (name === undefined) return [arg];\n  const value = process.env[name];\n  return value ? [value] : [];\n}\n\nconst CLI_PARSER_CONFIG = {\n  options: {\n    'allow-cwd': { type: 'boolean', default: false },\n    'read-only': { type: 'boolean', default: false },\n    'print-config': { type: 'boolean', default: false },\n    port: { type: 'string' },\n    help: { type: 'boolean', short: 'h' },\n    version: { type: 'boolean', short: 'v' },\n    'log-level': { type: 'string' },\n    'http-host': { type: 'string' },\n    'api-key': { type: 'string' },\n    'allow-sensitive': { type: 'boolean', default: false },\n    'root-boundary': { type: 'string' },\n    'max-file-size': { type: 'string' },\n    'tool-timeout': { type: 'string' },\n    'walk-cwd': { type: 'boolean', default: false },\n    deny: { type: 'string', multiple: true },\n    allow: { type: 'string', multiple: true },\n    'allow-missing-roots': { type: 'boolean', default: false },\n  },\n  strict: true,\n  allowPositionals: true,\n} as const;\n\nexport async function parseArgs(): Promise<{\n  allowedDirs: string[];\n  allowCwd: boolean;\n  port: number | undefined;\n  readOnly: boolean;\n  printConfig: boolean;\n  httpHost: string | undefined;\n  apiKey: string | undefined;\n}> {\n  try {\n    const parsed = utilParseArgs(CLI_PARSER_CONFIG);\n\n    if (parsed.values.help) {\n      printHelpAndExit();\n    }\n\n    if (parsed.values.version) {\n      printVersionAndExit();\n    }\n\n    const positionals = parsed.positionals.flatMap(expandEnvPlaceholder);\n    for (const positional of positionals) {\n      validateCliPath(positional);\n    }\n\n    const v = parsed.values;\n    // `--http-host` and `--api-key` are returned to the caller and handed to\n    // the server as config. Every other flag lands in the CLI-override store\n    // (core/config.ts) — the one owner of the flag-beats-env rule — which deep\n    // core readers (path, sensitive, observability, util) consult before\n    // falling back to the operator's environment. Nothing writes process.env.\n    const httpHost = v['http-host'] ?? process.env['FS_HTTP_HOST'];\n    const apiKey = v['api-key'] ?? process.env['FS_API_KEY'];\n    if (v['log-level'] !== undefined) cli.logLevel = v['log-level'];\n    if (v['max-file-size'] !== undefined) cli.maxFileSize = v['max-file-size'];\n    if (v['tool-timeout'] !== undefined) cli.toolTimeout = v['tool-timeout'];\n    if (v['root-boundary'] !== undefined) cli.rootBoundary = v['root-boundary'];\n    if (v['allow-sensitive']) cli.allowSensitive = true;\n    if (v['walk-cwd']) cli.allowCwdWalk = true;\n    if (v['allow-missing-roots']) cli.allowMissingRoots = true;\n    const patternList = (entries: readonly string[] | undefined): readonly string[] => [\n      ...new Set((entries ?? []).map((entry) => entry.trim()).filter(Boolean)),\n    ];\n    const denyPatterns = patternList(v.deny);\n    if (denyPatterns.length > 0) cli.denyPatterns = denyPatterns;\n    const allowPatterns = patternList(v.allow);\n    if (allowPatterns.length > 0) cli.allowPatterns = allowPatterns;\n\n    const allowCwd =\n      v['allow-cwd'] ||\n      v['walk-cwd'] ||\n      parseTrueEnvFlag(process.env['FS_ALLOW_CWD_WALK'], 'FS_ALLOW_CWD_WALK');\n    const readOnly =\n      v['read-only'] || parseTrueEnvFlag(process.env['FS_READ_ONLY'], 'FS_READ_ONLY');\n    const printConfig = v['print-config'];\n    const port = parsePortOption(v.port ?? process.env['FS_PORT']);\n    const allowMissingRoots =\n      v['allow-missing-roots'] ||\n      parseTrueEnvFlag(process.env['FS_ALLOW_MISSING_ROOTS'], 'FS_ALLOW_MISSING_ROOTS');\n\n    const allowedDirs =\n      positionals.length > 0 ? await normalizeAndValidateDirs(positionals, allowMissingRoots) : [];\n\n    return {\n      allowedDirs,\n      allowCwd,\n      port,\n      readOnly,\n      printConfig,\n      httpHost,\n      apiKey,\n    };\n  } catch (error: unknown) {\n    if (error instanceof CliExitError) {\n      throw error;\n    }\n\n    throw new CliExitError(normalizeCliExitMessage(error));\n  }\n}\n\n// ════════════════════════════════════════════════════════════\n// Effective config reporting — prints the resolved server config as JSON\n// ════════════════════════════════════════════════════════════\n\nexport async function runPrintConfig(\n  options: Awaited<ReturnType<typeof parseArgs>>,\n): Promise<void> {\n  const pathGuard = new PathGuard({\n    allowCwd: options.allowCwd,\n    cliAllowedDirs: options.allowedDirs,\n  });\n  await pathGuard.recomputeAllowedDirectories();\n  const allowedRoots = pathGuard.getRoots();\n\n  const tools = registeredTools(options.readOnly).map((t) => t.name);\n\n  // Derived, never assumed: `--print-config --port 3000` reports the HTTP bind\n  // that `--port` would actually have started, not the stdio default.\n  const config = {\n    transport:\n      options.port !== undefined\n        ? `http://${options.httpHost ?? '127.0.0.1'}:${String(options.port)}`\n        : 'stdio',\n    readOnly: options.readOnly,\n    allowedRoots,\n    tools,\n    apiKey: options.apiKey ? '***' : null,\n    limits: {\n      maxFileSizeBytes: getMaxTextFileSize(),\n      maxInboundMessageBytes: getMaxInboundMessageBytes(),\n      toolTimeoutMs: getToolTimeoutMs(),\n    },\n    // What the binary negotiates with, so an era mismatch (\"unsupported\n    // protocol version\") can be diagnosed without attaching a client. The\n    // legacy list is the SDK's own; the modern revision has no SDK export.\n    // The pins are exact (package.json), so the manifest value is the\n    // installed one.\n    protocol: {\n      modern: MODERN_PROTOCOL_REVISION,\n      legacy: { latest: LATEST_PROTOCOL_VERSION, supported: SUPPORTED_PROTOCOL_VERSIONS },\n      sdk: {\n        server: packageJson.dependencies['@modelcontextprotocol/server'],\n        node: packageJson.dependencies['@modelcontextprotocol/node'],\n        express: packageJson.dependencies['@modelcontextprotocol/express'],\n      },\n    },\n    // Everything that can produce ACCESS_DENIED, read through the same\n    // sources the guard and the matcher use (flag beats env).\n    policy: {\n      ...describeSensitivePolicy(),\n      rootBoundary: cli.rootBoundary ?? process.env['FS_ROOT_BOUNDARY'] ?? null,\n      allowMissingRoots:\n        cli.allowMissingRoots ??\n        parseTrueEnvFlag(process.env['FS_ALLOW_MISSING_ROOTS'], 'FS_ALLOW_MISSING_ROOTS'),\n    },\n  };\n\n  process.stdout.write(`${JSON.stringify(config, null, 2)}\\n`);\n}\n"]}

package/dist/core/concurrency.d.ts

@@ -30,18 +30,18 @@ export declare function processInParallel<T, R>(items: readonly T[], processor:
  * loop breaks on the first that fires. `undefined` means every entry was
  * dispatched.
  */
-export declare function processEntriesConcurrently(entries: AsyncIterable<{
+export declare function processEntriesConcurrently<E extends {
     path: string;
-}> | Iterable<{
+} = {
     path: string;
-}>, options: {
+}>(entries: AsyncIterable<E> | Iterable<E>, options: {
     signal: AbortSignal | undefined;
     concurrency: number;
     maxEntries?: number;
     shouldStop?: () => boolean;
     onEntry: () => void;
     onError?: (entryPath: string, err: unknown) => void;
-    runEntry: (entryPath: string) => Promise<void>;
+    runEntry: (entryPath: string, entry: E) => Promise<void>;
 }): Promise<StoppedReason | undefined>;
 export declare function withAbort<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T>;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../../src/core/concurrency.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,UAAU,GAAG,SAAS,CAAC;AAIlE;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAYpF;AAED,4GAA4G;AAC5G,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,OAAO,GACf,YAAY,GAAG,SAAS,GAAG,SAAS,CAEtC;AAED,UAAU,cAAc,CAAC,CAAC;IACxB,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,EAAE,CAAC;IACvC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAC1C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACjD,WAAW,GAAE,MAA6B,EAC1C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAgE5B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACrE,OAAO,EAAE;IACP,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;IAC3B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IACpD,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD,GACA,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAuEpC;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAmBlF"}
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../../src/core/concurrency.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,UAAU,GAAG,SAAS,CAAC;AAIlE;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAYpF;AAED,4GAA4G;AAC5G,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,OAAO,GACf,YAAY,GAAG,SAAS,GAAG,SAAS,CAEtC;AAED,UAAU,cAAc,CAAC,CAAC;IACxB,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,EAAE,CAAC;IACvC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAC1C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACjD,WAAW,GAAE,MAA6B,EAC1C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAgE5B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,0BAA0B,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAC5F,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,EACvC,OAAO,EAAE;IACP,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;IAC3B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IACpD,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D,GACA,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAuEpC;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAmBlF"}

package/dist/core/concurrency.js

@@ -138,7 +138,7 @@ export async function processEntriesConcurrently(entries, options) {
             // drain below (which would silently abandon other in-flight tasks).
             // runEntry is expected to catch its own errors; if it unexpectedly throws,
             // record it as a failure rather than silently dropping it.
-            const tracked = runEntry(entry.path).catch((err) => {
+            const tracked = runEntry(entry.path, entry).catch((err) => {
                 onError?.(entry.path, err);
             });
             pending.add(tracked);

package/dist/core/concurrency.js.map

@@ -1 +1 @@
-{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../../src/core/concurrency.ts"],"names":[],"mappings":"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","sourcesContent":["import { normalizeUnknownError } from './errors.ts';\nimport { PARALLEL_CONCURRENCY } from './util.ts';\n\nexport type StoppedReason = 'maxResults' | 'maxFiles' | 'timeout';\n\nconst exclusiveChains = new Map<unknown, Promise<unknown>>();\n\n/**\n * Run `fn` as the next holder of `key`'s lock: a read-`await`-write under one\n * key never interleaves with another. A rejected `fn` does not poison the next\n * waiter, and the entry is dropped once the chain drains. Keys: a PathGuard\n * instance (allowed-set grants) or a resolved write target (per-file writes).\n */\nexport async function runExclusive<T>(key: unknown, fn: () => Promise<T>): Promise<T> {\n  const run = (exclusiveChains.get(key) ?? Promise.resolve()).then(fn, fn);\n  const tail = run.then(\n    () => undefined,\n    () => undefined,\n  );\n  exclusiveChains.set(key, tail);\n  try {\n    return await run;\n  } finally {\n    if (exclusiveChains.get(key) === tail) exclusiveChains.delete(key);\n  }\n}\n\n/** The one precedence both scans share: the result cap wins over an abort that fired the same iteration. */\nexport function resolveStopReason(\n  hitCap: boolean,\n  aborted: boolean,\n): 'maxResults' | 'timeout' | undefined {\n  return hitCap ? 'maxResults' : aborted ? 'timeout' : undefined;\n}\n\ninterface ParallelResult<R> {\n  results: { index: number; value: R }[];\n  errors: { index: number; error: Error }[];\n}\n\nexport async function processInParallel<T, R>(\n  items: readonly T[],\n  processor: (item: T, index: number) => Promise<R>,\n  concurrency: number = PARALLEL_CONCURRENCY,\n  signal?: AbortSignal,\n): Promise<ParallelResult<R>> {\n  const itemCount = items.length;\n  if (itemCount === 0) return { results: [], errors: [] };\n\n  const results: { index: number; value: R }[] = [];\n  const errors: { index: number; error: Error }[] = [];\n\n  signal?.throwIfAborted();\n\n  let nextIndex = 0;\n  // Set when a worker saw the signal fire before an item ran — the only\n  // shape in which the batch is genuinely incomplete. The annotation\n  // matters: without it control-flow analysis keeps the `false` narrowing\n  // from the initializer and cannot see the closure assignment.\n  let truncated = false as boolean;\n\n  const next = async (): Promise<void> => {\n    while (nextIndex < itemCount) {\n      if (signal?.aborted) {\n        truncated = true;\n        signal.throwIfAborted();\n      }\n\n      const index = nextIndex;\n      nextIndex += 1;\n      const item = items[index];\n      if (item === undefined) {\n        continue;\n      }\n\n      try {\n        // No abort check after the processor: once an item has run, its\n        // result is real work that a write caller may have committed to\n        // disk. Discarding it here would report a finished append as\n        // failed, and a client retry would append twice.\n        const value = await processor(item, index);\n        results.push({ index, value });\n      } catch (error) {\n        errors.push({\n          index,\n          error: normalizeUnknownError(error),\n        });\n      }\n    }\n  };\n\n  const workerCount = Math.min(itemCount, concurrency);\n  const workers: Promise<void>[] = new Array<Promise<void>>(workerCount);\n  for (let index = 0; index < workerCount; index += 1) {\n    workers[index] = next();\n  }\n\n  await Promise.allSettled(workers);\n  // A deadline (AbortSignal.timeout) hit during the run surfaces here as\n  // signal.reason — a TimeoutError — rather than a fresh AbortError, so\n  // callers see TIMEOUT, not CANCELLED. Only a run that actually skipped\n  // items reports the abort: a deadline firing after the last item\n  // finished leaves a complete batch, and returning it beats telling the\n  // caller that committed writes failed. The per-item throws above are\n  // swallowed by allSettled.\n  if (truncated) signal?.throwIfAborted();\n\n  results.sort((left, right) => left.index - right.index);\n  return { results, errors };\n}\n\n/**\n * The streaming sibling of {@link processInParallel}: bounded-concurrency\n * dispatch over an AsyncIterable that may be far larger than the caller wants\n * to walk, so it stops early and reports why.\n *\n * `maxEntries` caps how many entries are dispatched (maxFiles); `shouldStop`\n * lets the caller stop on its own accumulating result count (maxResults). Both\n * are checked before dispatch, so the returned reason is exactly one — the\n * loop breaks on the first that fires. `undefined` means every entry was\n * dispatched.\n */\nexport async function processEntriesConcurrently(\n  entries: AsyncIterable<{ path: string }> | Iterable<{ path: string }>,\n  options: {\n    signal: AbortSignal | undefined;\n    concurrency: number;\n    maxEntries?: number;\n    shouldStop?: () => boolean;\n    onEntry: () => void;\n    onError?: (entryPath: string, err: unknown) => void;\n    runEntry: (entryPath: string) => Promise<void>;\n  },\n): Promise<StoppedReason | undefined> {\n  const pending = new Set<Promise<void>>();\n  const { signal, concurrency, maxEntries, shouldStop, onEntry, onError, runEntry } = options;\n  let stoppedReason: StoppedReason | undefined;\n  let dispatched = 0;\n\n  const waitForSlot = async (): Promise<void> => {\n    if (pending.size < concurrency) return;\n    await Promise.race(pending);\n  };\n\n  let walkFailed = false;\n  let walkError: unknown;\n  try {\n    for await (const entry of entries) {\n      // The signal is cancellation OR the caller's timeout: stop dispatching and\n      // let the caller report the run as incomplete rather than as a full sweep.\n      if (signal?.aborted) {\n        stoppedReason = 'timeout';\n        break;\n      }\n      if (maxEntries !== undefined && dispatched >= maxEntries) {\n        stoppedReason = 'maxFiles';\n        break;\n      }\n      // Check the result cap before waiting for a slot so an in-flight task that\n      // already crossed the cap stops dispatch without an extra wait...\n      if (shouldStop?.()) {\n        stoppedReason = 'maxResults';\n        break;\n      }\n      await waitForSlot();\n      // ...and again after the slot frees, since tasks settle concurrently. The\n      // cap can still be exceeded by at most `concurrency - 1` already-dispatched\n      // tasks that are mid-flight; that overrun is inherent to concurrent dispatch.\n      if (shouldStop?.()) {\n        stoppedReason = 'maxResults';\n        break;\n      }\n      onEntry();\n      dispatched++;\n\n      // Track a non-rejecting wrapper so a rejected task can never propagate out of\n      // Promise.race(pending) in waitForSlot() and abort the loop before the final\n      // drain below (which would silently abandon other in-flight tasks).\n      // runEntry is expected to catch its own errors; if it unexpectedly throws,\n      // record it as a failure rather than silently dropping it.\n      const tracked = runEntry(entry.path).catch((err: unknown) => {\n        onError?.(entry.path, err);\n      });\n      pending.add(tracked);\n      void tracked.finally(() => {\n        pending.delete(tracked);\n      });\n    }\n  } catch (error) {\n    // A walk the signal cut short throws its reason (see globEntries): that is\n    // the same timeout as the check above, not a failed walk.\n    if (signal?.aborted) stoppedReason = 'timeout';\n    else {\n      walkFailed = true;\n      walkError = error;\n    }\n  }\n\n  if (pending.size > 0) {\n    await Promise.allSettled([...pending]);\n  }\n\n  if (walkFailed) throw walkError;\n  return stoppedReason;\n}\n\nexport function withAbort<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {\n  if (!signal) {\n    return promise;\n  }\n  signal.throwIfAborted();\n  let onAbort: (() => void) | undefined;\n  return Promise.race([\n    promise,\n    new Promise<never>((_, reject) => {\n      onAbort = () => {\n        reject(signal.reason instanceof Error ? signal.reason : new Error('Operation aborted'));\n      };\n      signal.addEventListener('abort', onAbort, { once: true });\n    }),\n  ]).finally(() => {\n    if (onAbort) {\n      signal.removeEventListener('abort', onAbort);\n    }\n  });\n}\n"]}
+{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../../src/core/concurrency.ts"],"names":[],"mappings":"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","sourcesContent":["import { normalizeUnknownError } from './errors.ts';\nimport { PARALLEL_CONCURRENCY } from './util.ts';\n\nexport type StoppedReason = 'maxResults' | 'maxFiles' | 'timeout';\n\nconst exclusiveChains = new Map<unknown, Promise<unknown>>();\n\n/**\n * Run `fn` as the next holder of `key`'s lock: a read-`await`-write under one\n * key never interleaves with another. A rejected `fn` does not poison the next\n * waiter, and the entry is dropped once the chain drains. Keys: a PathGuard\n * instance (allowed-set grants) or a resolved write target (per-file writes).\n */\nexport async function runExclusive<T>(key: unknown, fn: () => Promise<T>): Promise<T> {\n  const run = (exclusiveChains.get(key) ?? Promise.resolve()).then(fn, fn);\n  const tail = run.then(\n    () => undefined,\n    () => undefined,\n  );\n  exclusiveChains.set(key, tail);\n  try {\n    return await run;\n  } finally {\n    if (exclusiveChains.get(key) === tail) exclusiveChains.delete(key);\n  }\n}\n\n/** The one precedence both scans share: the result cap wins over an abort that fired the same iteration. */\nexport function resolveStopReason(\n  hitCap: boolean,\n  aborted: boolean,\n): 'maxResults' | 'timeout' | undefined {\n  return hitCap ? 'maxResults' : aborted ? 'timeout' : undefined;\n}\n\ninterface ParallelResult<R> {\n  results: { index: number; value: R }[];\n  errors: { index: number; error: Error }[];\n}\n\nexport async function processInParallel<T, R>(\n  items: readonly T[],\n  processor: (item: T, index: number) => Promise<R>,\n  concurrency: number = PARALLEL_CONCURRENCY,\n  signal?: AbortSignal,\n): Promise<ParallelResult<R>> {\n  const itemCount = items.length;\n  if (itemCount === 0) return { results: [], errors: [] };\n\n  const results: { index: number; value: R }[] = [];\n  const errors: { index: number; error: Error }[] = [];\n\n  signal?.throwIfAborted();\n\n  let nextIndex = 0;\n  // Set when a worker saw the signal fire before an item ran — the only\n  // shape in which the batch is genuinely incomplete. The annotation\n  // matters: without it control-flow analysis keeps the `false` narrowing\n  // from the initializer and cannot see the closure assignment.\n  let truncated = false as boolean;\n\n  const next = async (): Promise<void> => {\n    while (nextIndex < itemCount) {\n      if (signal?.aborted) {\n        truncated = true;\n        signal.throwIfAborted();\n      }\n\n      const index = nextIndex;\n      nextIndex += 1;\n      const item = items[index];\n      if (item === undefined) {\n        continue;\n      }\n\n      try {\n        // No abort check after the processor: once an item has run, its\n        // result is real work that a write caller may have committed to\n        // disk. Discarding it here would report a finished append as\n        // failed, and a client retry would append twice.\n        const value = await processor(item, index);\n        results.push({ index, value });\n      } catch (error) {\n        errors.push({\n          index,\n          error: normalizeUnknownError(error),\n        });\n      }\n    }\n  };\n\n  const workerCount = Math.min(itemCount, concurrency);\n  const workers: Promise<void>[] = new Array<Promise<void>>(workerCount);\n  for (let index = 0; index < workerCount; index += 1) {\n    workers[index] = next();\n  }\n\n  await Promise.allSettled(workers);\n  // A deadline (AbortSignal.timeout) hit during the run surfaces here as\n  // signal.reason — a TimeoutError — rather than a fresh AbortError, so\n  // callers see TIMEOUT, not CANCELLED. Only a run that actually skipped\n  // items reports the abort: a deadline firing after the last item\n  // finished leaves a complete batch, and returning it beats telling the\n  // caller that committed writes failed. The per-item throws above are\n  // swallowed by allSettled.\n  if (truncated) signal?.throwIfAborted();\n\n  results.sort((left, right) => left.index - right.index);\n  return { results, errors };\n}\n\n/**\n * The streaming sibling of {@link processInParallel}: bounded-concurrency\n * dispatch over an AsyncIterable that may be far larger than the caller wants\n * to walk, so it stops early and reports why.\n *\n * `maxEntries` caps how many entries are dispatched (maxFiles); `shouldStop`\n * lets the caller stop on its own accumulating result count (maxResults). Both\n * are checked before dispatch, so the returned reason is exactly one — the\n * loop breaks on the first that fires. `undefined` means every entry was\n * dispatched.\n */\nexport async function processEntriesConcurrently<E extends { path: string } = { path: string }>(\n  entries: AsyncIterable<E> | Iterable<E>,\n  options: {\n    signal: AbortSignal | undefined;\n    concurrency: number;\n    maxEntries?: number;\n    shouldStop?: () => boolean;\n    onEntry: () => void;\n    onError?: (entryPath: string, err: unknown) => void;\n    runEntry: (entryPath: string, entry: E) => Promise<void>;\n  },\n): Promise<StoppedReason | undefined> {\n  const pending = new Set<Promise<void>>();\n  const { signal, concurrency, maxEntries, shouldStop, onEntry, onError, runEntry } = options;\n  let stoppedReason: StoppedReason | undefined;\n  let dispatched = 0;\n\n  const waitForSlot = async (): Promise<void> => {\n    if (pending.size < concurrency) return;\n    await Promise.race(pending);\n  };\n\n  let walkFailed = false;\n  let walkError: unknown;\n  try {\n    for await (const entry of entries) {\n      // The signal is cancellation OR the caller's timeout: stop dispatching and\n      // let the caller report the run as incomplete rather than as a full sweep.\n      if (signal?.aborted) {\n        stoppedReason = 'timeout';\n        break;\n      }\n      if (maxEntries !== undefined && dispatched >= maxEntries) {\n        stoppedReason = 'maxFiles';\n        break;\n      }\n      // Check the result cap before waiting for a slot so an in-flight task that\n      // already crossed the cap stops dispatch without an extra wait...\n      if (shouldStop?.()) {\n        stoppedReason = 'maxResults';\n        break;\n      }\n      await waitForSlot();\n      // ...and again after the slot frees, since tasks settle concurrently. The\n      // cap can still be exceeded by at most `concurrency - 1` already-dispatched\n      // tasks that are mid-flight; that overrun is inherent to concurrent dispatch.\n      if (shouldStop?.()) {\n        stoppedReason = 'maxResults';\n        break;\n      }\n      onEntry();\n      dispatched++;\n\n      // Track a non-rejecting wrapper so a rejected task can never propagate out of\n      // Promise.race(pending) in waitForSlot() and abort the loop before the final\n      // drain below (which would silently abandon other in-flight tasks).\n      // runEntry is expected to catch its own errors; if it unexpectedly throws,\n      // record it as a failure rather than silently dropping it.\n      const tracked = runEntry(entry.path, entry).catch((err: unknown) => {\n        onError?.(entry.path, err);\n      });\n      pending.add(tracked);\n      void tracked.finally(() => {\n        pending.delete(tracked);\n      });\n    }\n  } catch (error) {\n    // A walk the signal cut short throws its reason (see globEntries): that is\n    // the same timeout as the check above, not a failed walk.\n    if (signal?.aborted) stoppedReason = 'timeout';\n    else {\n      walkFailed = true;\n      walkError = error;\n    }\n  }\n\n  if (pending.size > 0) {\n    await Promise.allSettled([...pending]);\n  }\n\n  if (walkFailed) throw walkError;\n  return stoppedReason;\n}\n\nexport function withAbort<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {\n  if (!signal) {\n    return promise;\n  }\n  signal.throwIfAborted();\n  let onAbort: (() => void) | undefined;\n  return Promise.race([\n    promise,\n    new Promise<never>((_, reject) => {\n      onAbort = () => {\n        reject(signal.reason instanceof Error ? signal.reason : new Error('Operation aborted'));\n      };\n      signal.addEventListener('abort', onAbort, { once: true });\n    }),\n  ]).finally(() => {\n    if (onAbort) {\n      signal.removeEventListener('abort', onAbort);\n    }\n  });\n}\n"]}

package/dist/core/config.d.ts

@@ -10,6 +10,8 @@ export interface CliOverrides {
     logLevel?: string;
     /** `--max-file-size` (raw string; validated by the reader like the env var) */
     maxFileSize?: string;
+    /** `--tool-timeout` (raw string; validated by the reader like the env var) */
+    toolTimeout?: string;
     /** `--root-boundary` */
     rootBoundary?: string;
     /** `--allow-sensitive` */

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,+NACqL,CAAC;AAE/N,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wBAAwB;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mBAAmB;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,8BAA8B;IAC9B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,+DAA+D;IAC/D,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,yFAAyF;IACzF,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,iFAAiF;AACjF,eAAO,MAAM,GAAG,EAAE,YAAiB,CAAC;AAEpC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,eAAe,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,+NACqL,CAAC;AAE/N,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wBAAwB;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mBAAmB;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,8BAA8B;IAC9B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,+DAA+D;IAC/D,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,yFAAyF;IACzF,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,iFAAiF;AACjF,eAAO,MAAM,GAAG,EAAE,YAAiB,CAAC;AAEpC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,eAAe,CAAC"}

package/dist/core/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,4EAA4E;AAC5E,+EAA+E;AAC/E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,kDAAkD;AAElD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GACvC,4NAA4N,CAAC;AAqB/N,iFAAiF;AACjF,MAAM,CAAC,MAAM,GAAG,GAAiB,EAAE,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,YAAY,CAAC","sourcesContent":["// Resolved CLI-flag overrides — the one owner of the flag-beats-env rule.\n//\n// `parseArgs` (cli.ts) used to write flag values back into `process.env` so\n// deep core readers (path, sensitive, observability, util) would pick them up.\n// That made the environment a hidden mutable config bus. Instead, cli.ts\n// assigns onto `cli` once at startup and each reader consults it first, falling\n// back to the operator's environment. This module deliberately has zero imports\n// so any core module can read it without a cycle.\n\n/**\n * How an operator gives this server a root. Lives here rather than beside its\n * readers because both ends of the repo need it — `index.ts` prints it at\n * startup, `list_roots` returns it when it has nothing to list — and this\n * module is the one place either can import without a cycle.\n */\nexport const NO_POSITIONAL_ROOTS_GUIDANCE =\n  'No positional directories specified. Configure roots with directory arguments, FS_ALLOWED_DIRS, or --allow-cwd. Modern clients with elicitation can also call a tool with a concrete path and approve the requested grant.';\n\nexport interface CliOverrides {\n  /** `--log-level` */\n  logLevel?: string;\n  /** `--max-file-size` (raw string; validated by the reader like the env var) */\n  maxFileSize?: string;\n  /** `--root-boundary` */\n  rootBoundary?: string;\n  /** `--allow-sensitive` */\n  allowSensitive?: boolean;\n  /** `--walk-cwd` */\n  allowCwdWalk?: boolean;\n  /** `--allow-missing-roots` */\n  allowMissingRoots?: boolean;\n  /** `--deny` entries (merged with FS_DENYLIST by the reader) */\n  denyPatterns?: readonly string[];\n  /** `--allow` entries (merged with FS_ALLOWLIST by the reader; relieve built-ins only) */\n  allowPatterns?: readonly string[];\n}\n\n/** Written once by cli.ts; an absent key means \"not set on the command line\". */\nexport const cli: CliOverrides = {};\n\n/**\n * The per-request-envelope protocol revision this server serves next to the\n * 2025 `initialize` handshake. The SDK keeps its own copy internal\n * (`FIRST_MODERN_PROTOCOL_VERSION`), so this is asserted against SDK\n * behaviour in `cli.test.ts` rather than imported.\n */\nexport const MODERN_PROTOCOL_REVISION = '2026-07-28';\n"]}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,4EAA4E;AAC5E,+EAA+E;AAC/E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,kDAAkD;AAElD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GACvC,4NAA4N,CAAC;AAuB/N,iFAAiF;AACjF,MAAM,CAAC,MAAM,GAAG,GAAiB,EAAE,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,YAAY,CAAC","sourcesContent":["// Resolved CLI-flag overrides — the one owner of the flag-beats-env rule.\n//\n// `parseArgs` (cli.ts) used to write flag values back into `process.env` so\n// deep core readers (path, sensitive, observability, util) would pick them up.\n// That made the environment a hidden mutable config bus. Instead, cli.ts\n// assigns onto `cli` once at startup and each reader consults it first, falling\n// back to the operator's environment. This module deliberately has zero imports\n// so any core module can read it without a cycle.\n\n/**\n * How an operator gives this server a root. Lives here rather than beside its\n * readers because both ends of the repo need it — `index.ts` prints it at\n * startup, `list_roots` returns it when it has nothing to list — and this\n * module is the one place either can import without a cycle.\n */\nexport const NO_POSITIONAL_ROOTS_GUIDANCE =\n  'No positional directories specified. Configure roots with directory arguments, FS_ALLOWED_DIRS, or --allow-cwd. Modern clients with elicitation can also call a tool with a concrete path and approve the requested grant.';\n\nexport interface CliOverrides {\n  /** `--log-level` */\n  logLevel?: string;\n  /** `--max-file-size` (raw string; validated by the reader like the env var) */\n  maxFileSize?: string;\n  /** `--tool-timeout` (raw string; validated by the reader like the env var) */\n  toolTimeout?: string;\n  /** `--root-boundary` */\n  rootBoundary?: string;\n  /** `--allow-sensitive` */\n  allowSensitive?: boolean;\n  /** `--walk-cwd` */\n  allowCwdWalk?: boolean;\n  /** `--allow-missing-roots` */\n  allowMissingRoots?: boolean;\n  /** `--deny` entries (merged with FS_DENYLIST by the reader) */\n  denyPatterns?: readonly string[];\n  /** `--allow` entries (merged with FS_ALLOWLIST by the reader; relieve built-ins only) */\n  allowPatterns?: readonly string[];\n}\n\n/** Written once by cli.ts; an absent key means \"not set on the command line\". */\nexport const cli: CliOverrides = {};\n\n/**\n * The per-request-envelope protocol revision this server serves next to the\n * 2025 `initialize` handshake. The SDK keeps its own copy internal\n * (`FIRST_MODERN_PROTOCOL_VERSION`), so this is asserted against SDK\n * behaviour in `cli.test.ts` rather than imported.\n */\nexport const MODERN_PROTOCOL_REVISION = '2026-07-28';\n"]}

package/dist/core/cursor.d.ts

@@ -24,6 +24,13 @@ export interface PaginatedPage<T, M, R> extends Page<T, M> {
     /** The externalized full set. First page only, and only when incomplete. */
     readonly resource?: R;
 }
+/**
+ * A paged query's snapshot identity: `method` plus every arg except
+ * `pagingFields`. Result-defining args are in the key by default, so one a tool
+ * forgets to exclude fails loud as an invalid cursor instead of replaying a
+ * stale snapshot.
+ */
+export declare function pageQueryKey<A extends object>(method: string, args: A, pagingFields: readonly (keyof A & string)[]): string;
 /**
  * The one replay-or-produce branch every paged tool runs. A cursor replays a
  * stored snapshot; without one, `produce` runs the query and its result is
@@ -38,6 +45,7 @@ export interface PaginatedPage<T, M, R> extends Page<T, M> {
  */
 export declare function paginate<T, M, R>(params: {
     store: PageSnapshotStore;
+    /** Built by `pageQueryKey`; a snapshot replays only for the key that minted it. */
     queryKey: string;
     cursor: string | undefined;
     pageSize: number;

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

@@ -1 +1 @@
-{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/core/cursor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAgB,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAgClE;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,EAAE,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,UAAU,IAAI,CAAC,CAAC,EAAE,CAAC;IACjB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAE,SAAQ,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;IACxD,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE;IAC9C,KAAK,EAAE,iBAAiB,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC3C,WAAW,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,SAAS,CAAC;CACrE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CA+BlC"}
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/core/cursor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAgB,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAgClE;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,EAAE,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,UAAU,IAAI,CAAC,CAAC,EAAE,CAAC;IACjB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAE,SAAQ,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;IACxD,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC3C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,CAAC,EACP,YAAY,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,GAC1C,MAAM,CAOR;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE;IAC9C,KAAK,EAAE,iBAAiB,CAAC;IACzB,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC3C,WAAW,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,SAAS,CAAC;CACrE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CA+BlC"}