@j0hanz/filesystem-mcp 1.19.0 → 2.0.0

package/dist/core/store.js

@@ -0,0 +1,162 @@
+import { randomUUID } from 'node:crypto';
+import { ErrorCode, FsError } from './errors.js';
+import { Logger } from './observability.js';
+import { MIB } from './util.js';
+const MAX_ENTRIES = 64;
+const MAX_TOTAL_BYTES = 25 * MIB;
+const MAX_ENTRY_BYTES = 10 * MIB;
+const ENTRY_TTL_MS = 60 * 1000;
+function isExpired(entry, now = Date.now()) {
+    const expiresAt = Date.parse(entry.expiresAt);
+    if (!Number.isFinite(expiresAt)) {
+        return true;
+    }
+    return expiresAt <= now;
+}
+export class ResourceStore {
+    byUri = new Map();
+    _totalBytes = 0;
+    onListChanged;
+    constructor(onListChanged) {
+        this.onListChanged = onListChanged;
+    }
+    emitListChanged(changed) {
+        if (changed)
+            this.onListChanged?.();
+    }
+    bumpLru(uri, entry) {
+        if (!this.byUri.has(uri)) {
+            return;
+        }
+        this.byUri.delete(uri);
+        this.byUri.set(uri, entry);
+    }
+    removeEntry(uri) {
+        const existing = this.byUri.get(uri);
+        if (!existing) {
+            return undefined;
+        }
+        this._totalBytes -= existing.size;
+        this.byUri.delete(uri);
+        return existing;
+    }
+    evictOldest() {
+        const first = this.byUri.values().next();
+        if (first.done) {
+            return;
+        }
+        this.removeEntry(first.value.uri);
+    }
+    pruneExpiredEntries(now = Date.now()) {
+        const toRemove = [];
+        for (const entry of this.byUri.values()) {
+            if (isExpired(entry, now)) {
+                toRemove.push(entry.uri);
+            }
+        }
+        for (const uri of toRemove) {
+            this.removeEntry(uri);
+        }
+        return toRemove.length > 0;
+    }
+    enforceLimits() {
+        while (this.byUri.size > MAX_ENTRIES) {
+            this.evictOldest();
+        }
+        while (this._totalBytes > MAX_TOTAL_BYTES) {
+            if (this.byUri.size === 0) {
+                Logger.error(`[resource-store] enforceLimits invariant violation: totalBytes=${this._totalBytes} but entryCount=0`);
+                break;
+            }
+            this.evictOldest();
+        }
+    }
+    getExisting(uri) {
+        const existing = this.byUri.get(uri);
+        if (!existing) {
+            throw new FsError(ErrorCode.NOT_FOUND, `Resource not found: ${uri}. Re-run the tool to regenerate.`);
+        }
+        if (isExpired(existing)) {
+            this.removeEntry(uri);
+            this.emitListChanged(true);
+            throw new FsError(ErrorCode.NOT_FOUND, `Resource expired: ${uri}. Re-run the tool to regenerate.`);
+        }
+        this.bumpLru(uri, existing);
+        return existing;
+    }
+    checkBeforePut(entryBytes) {
+        const changed = this.pruneExpiredEntries();
+        if (entryBytes > MAX_ENTRY_BYTES) {
+            this.emitListChanged(changed);
+            throw new FsError(ErrorCode.TOO_LARGE, `Resource too large to cache (${entryBytes} bytes).`);
+        }
+    }
+    putText(params) {
+        const entryBytes = Buffer.byteLength(params.text, 'utf8');
+        this.checkBeforePut(entryBytes);
+        const storedAt = new Date();
+        const entry = {
+            uri: `filesystem-mcp://result/${randomUUID()}`,
+            name: params.name,
+            mimeType: params.mimeType ?? 'text/plain',
+            size: entryBytes,
+            storedAt: storedAt.toISOString(),
+            expiresAt: new Date(storedAt.getTime() + ENTRY_TTL_MS).toISOString(),
+            text: params.text,
+        };
+        this.byUri.set(entry.uri, entry);
+        this._totalBytes += entryBytes;
+        this.enforceLimits();
+        this.emitListChanged(true);
+        return entry;
+    }
+    getEntry(uri) {
+        return this.getExisting(uri);
+    }
+    /**
+     * Returns live URIs currently in the store.
+     * Side effect: prunes expired entries before returning.
+     *
+     * Deliberately silent: this is the read path `resources/list` runs through,
+     * and the caller is already receiving the post-prune list. Emitting here
+     * would tell the client its list changed while handing it that same list.
+     */
+    keys() {
+        this.pruneExpiredEntries();
+        return Array.from(this.byUri.keys());
+    }
+}
+/**
+ * Owner of the externalize-a-payload rule: a tool whose inline response is
+ * truncated publishes the full value to the resource store as pretty-printed
+ * JSON and hands back the URI to reach it by, plus the link block that offers
+ * it to the user.
+ */
+export function putJsonResource(store, name, 
+// `Record<string, unknown> | readonly unknown[]`, not `unknown` or `object`:
+// JSON.stringify returns undefined for undefined and for functions, and `null`
+// is excluded so non-string payloads cannot enter the store's text entry.
+value) {
+    const entry = store.putText({
+        name,
+        mimeType: 'application/json',
+        text: JSON.stringify(value, null, 2),
+    });
+    return {
+        entry: {
+            uri: entry.uri,
+            size: entry.size,
+            mimeType: entry.mimeType,
+            expiresAt: entry.expiresAt,
+        },
+        link: {
+            type: 'resource_link',
+            uri: entry.uri,
+            name: entry.name,
+            mimeType: entry.mimeType,
+            size: entry.size,
+            annotations: { audience: ['user'] },
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/core/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/core/store.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAYhC,MAAM,WAAW,GAAG,EAAE,CAAC;AACvB,MAAM,eAAe,GAAG,EAAE,GAAG,GAAG,CAAC;AACjC,MAAM,eAAe,GAAG,EAAE,GAAG,GAAG,CAAC;AACjC,MAAM,YAAY,GAAG,EAAE,GAAG,IAAI,CAAC;AAE/B,SAAS,SAAS,CAAC,KAAoB,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IACvD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,SAAS,IAAI,GAAG,CAAC;AAC1B,CAAC;AAED,MAAM,OAAO,aAAa;IACP,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IAClD,WAAW,GAAG,CAAC,CAAC;IAEP,aAAa,CAA2B;IAEzD,YAAY,aAA0B;QACpC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;IAEO,eAAe,CAAC,OAAgB;QACtC,IAAI,OAAO;YAAE,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC;IACtC,CAAC;IAEO,OAAO,CAAC,GAAW,EAAE,KAAoB;QAC/C,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC7B,CAAC;IAEO,WAAW,CAAC,GAAW;QAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,CAAC,WAAW,IAAI,QAAQ,CAAC,IAAI,CAAC;QAClC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACvB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAEO,WAAW;QACjB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC;QACzC,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACf,OAAO;QACT,CAAC;QACD,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IAEO,mBAAmB,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;QAC1C,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YACxC,IAAI,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC;gBAC1B,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;QACD,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IAC7B,CAAC;IAEO,aAAa;QACnB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,WAAW,EAAE,CAAC;YACrC,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,CAAC;QACD,OAAO,IAAI,CAAC,WAAW,GAAG,eAAe,EAAE,CAAC;YAC1C,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;gBAC1B,MAAM,CAAC,KAAK,CACV,kEAAkE,IAAI,CAAC,WAAW,mBAAmB,CACtG,CAAC;gBACF,MAAM;YACR,CAAC;YACD,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,CAAC;IACH,CAAC;IAEO,WAAW,CAAC,GAAW;QAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAErC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,OAAO,CACf,SAAS,CAAC,SAAS,EACnB,uBAAuB,GAAG,kCAAkC,CAC7D,CAAC;QACJ,CAAC;QAED,IAAI,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;YACtB,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;YAC3B,MAAM,IAAI,OAAO,CACf,SAAS,CAAC,SAAS,EACnB,qBAAqB,GAAG,kCAAkC,CAC3D,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC5B,OAAO,QAAQ,CAAC;IAClB,CAAC;IAEO,cAAc,CAAC,UAAkB;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC3C,IAAI,UAAU,GAAG,eAAe,EAAE,CAAC;YACjC,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;YAC9B,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC,SAAS,EAAE,gCAAgC,UAAU,UAAU,CAAC,CAAC;QAC/F,CAAC;IACH,CAAC;IAED,OAAO,CAAC,MAAyD;QAC/D,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC1D,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;QAEhC,MAAM,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAkB;YAC3B,GAAG,EAAE,2BAA2B,UAAU,EAAE,EAAE;YAC9C,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,YAAY;YACzC,IAAI,EAAE,UAAU;YAChB,QAAQ,EAAE,QAAQ,CAAC,WAAW,EAAE;YAChC,SAAS,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,YAAY,CAAC,CAAC,WAAW,EAAE;YACpE,IAAI,EAAE,MAAM,CAAC,IAAI;SAClB,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACjC,IAAI,CAAC,WAAW,IAAI,UAAU,CAAC;QAC/B,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,QAAQ,CAAC,GAAW;QAClB,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;;;OAOG;IACH,IAAI;QACF,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;CACF;AAYD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,KAAoB,EACpB,IAAY;AACZ,6EAA6E;AAC7E,+EAA+E;AAC/E,0EAA0E;AAC1E,KAAmD;IAEnD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC;QAC1B,IAAI;QACJ,QAAQ,EAAE,kBAAkB;QAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;KACrC,CAAC,CAAC;IAEH,OAAO;QACL,KAAK,EAAE;YACL,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,SAAS,EAAE,KAAK,CAAC,SAAS;SAC3B;QACD,IAAI,EAAE;YACJ,IAAI,EAAE,eAAe;YACrB,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,WAAW,EAAE,EAAE,QAAQ,EAAE,CAAC,MAAM,CAAC,EAAE;SACpC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type { ContentBlock } from '@modelcontextprotocol/server';\n\nimport { randomUUID } from 'node:crypto';\n\nimport { ErrorCode, FsError } from './errors.js';\nimport { Logger } from './observability.js';\nimport { MIB } from './util.js';\n\ninterface ResourceEntry {\n  uri: string;\n  name: string;\n  mimeType: string;\n  size: number;\n  storedAt: string;\n  expiresAt: string;\n  text: string;\n}\n\nconst MAX_ENTRIES = 64;\nconst MAX_TOTAL_BYTES = 25 * MIB;\nconst MAX_ENTRY_BYTES = 10 * MIB;\nconst ENTRY_TTL_MS = 60 * 1000;\n\nfunction isExpired(entry: ResourceEntry, now = Date.now()): boolean {\n  const expiresAt = Date.parse(entry.expiresAt);\n  if (!Number.isFinite(expiresAt)) {\n    return true;\n  }\n  return expiresAt <= now;\n}\n\nexport class ResourceStore {\n  private readonly byUri = new Map<string, ResourceEntry>();\n  private _totalBytes = 0;\n\n  private readonly onListChanged: (() => void) | undefined;\n\n  constructor(onListChanged?: () => void) {\n    this.onListChanged = onListChanged;\n  }\n\n  private emitListChanged(changed: boolean): void {\n    if (changed) this.onListChanged?.();\n  }\n\n  private bumpLru(uri: string, entry: ResourceEntry): void {\n    if (!this.byUri.has(uri)) {\n      return;\n    }\n    this.byUri.delete(uri);\n    this.byUri.set(uri, entry);\n  }\n\n  private removeEntry(uri: string): ResourceEntry | undefined {\n    const existing = this.byUri.get(uri);\n    if (!existing) {\n      return undefined;\n    }\n    this._totalBytes -= existing.size;\n    this.byUri.delete(uri);\n    return existing;\n  }\n\n  private evictOldest(): void {\n    const first = this.byUri.values().next();\n    if (first.done) {\n      return;\n    }\n    this.removeEntry(first.value.uri);\n  }\n\n  private pruneExpiredEntries(now = Date.now()): boolean {\n    const toRemove: string[] = [];\n    for (const entry of this.byUri.values()) {\n      if (isExpired(entry, now)) {\n        toRemove.push(entry.uri);\n      }\n    }\n    for (const uri of toRemove) {\n      this.removeEntry(uri);\n    }\n    return toRemove.length > 0;\n  }\n\n  private enforceLimits(): void {\n    while (this.byUri.size > MAX_ENTRIES) {\n      this.evictOldest();\n    }\n    while (this._totalBytes > MAX_TOTAL_BYTES) {\n      if (this.byUri.size === 0) {\n        Logger.error(\n          `[resource-store] enforceLimits invariant violation: totalBytes=${this._totalBytes} but entryCount=0`,\n        );\n        break;\n      }\n      this.evictOldest();\n    }\n  }\n\n  private getExisting(uri: string): ResourceEntry {\n    const existing = this.byUri.get(uri);\n\n    if (!existing) {\n      throw new FsError(\n        ErrorCode.NOT_FOUND,\n        `Resource not found: ${uri}. Re-run the tool to regenerate.`,\n      );\n    }\n\n    if (isExpired(existing)) {\n      this.removeEntry(uri);\n      this.emitListChanged(true);\n      throw new FsError(\n        ErrorCode.NOT_FOUND,\n        `Resource expired: ${uri}. Re-run the tool to regenerate.`,\n      );\n    }\n\n    this.bumpLru(uri, existing);\n    return existing;\n  }\n\n  private checkBeforePut(entryBytes: number): void {\n    const changed = this.pruneExpiredEntries();\n    if (entryBytes > MAX_ENTRY_BYTES) {\n      this.emitListChanged(changed);\n      throw new FsError(ErrorCode.TOO_LARGE, `Resource too large to cache (${entryBytes} bytes).`);\n    }\n  }\n\n  putText(params: { name: string; mimeType?: string; text: string }): ResourceEntry {\n    const entryBytes = Buffer.byteLength(params.text, 'utf8');\n    this.checkBeforePut(entryBytes);\n\n    const storedAt = new Date();\n    const entry: ResourceEntry = {\n      uri: `filesystem-mcp://result/${randomUUID()}`,\n      name: params.name,\n      mimeType: params.mimeType ?? 'text/plain',\n      size: entryBytes,\n      storedAt: storedAt.toISOString(),\n      expiresAt: new Date(storedAt.getTime() + ENTRY_TTL_MS).toISOString(),\n      text: params.text,\n    };\n    this.byUri.set(entry.uri, entry);\n    this._totalBytes += entryBytes;\n    this.enforceLimits();\n    this.emitListChanged(true);\n    return entry;\n  }\n\n  getEntry(uri: string): ResourceEntry {\n    return this.getExisting(uri);\n  }\n\n  /**\n   * Returns live URIs currently in the store.\n   * Side effect: prunes expired entries before returning.\n   *\n   * Deliberately silent: this is the read path `resources/list` runs through,\n   * and the caller is already receiving the post-prune list. Emitting here\n   * would tell the client its list changed while handing it that same list.\n   */\n  keys(): string[] {\n    this.pruneExpiredEntries();\n    return Array.from(this.byUri.keys());\n  }\n}\n\nexport interface JsonResourceResult {\n  entry: {\n    uri: string;\n    size: number;\n    mimeType: string;\n    expiresAt: string;\n  };\n  link: ContentBlock;\n}\n\n/**\n * Owner of the externalize-a-payload rule: a tool whose inline response is\n * truncated publishes the full value to the resource store as pretty-printed\n * JSON and hands back the URI to reach it by, plus the link block that offers\n * it to the user.\n */\nexport function putJsonResource(\n  store: ResourceStore,\n  name: string,\n  // `Record<string, unknown> | readonly unknown[]`, not `unknown` or `object`:\n  // JSON.stringify returns undefined for undefined and for functions, and `null`\n  // is excluded so non-string payloads cannot enter the store's text entry.\n  value: Record<string, unknown> | readonly unknown[],\n): JsonResourceResult {\n  const entry = store.putText({\n    name,\n    mimeType: 'application/json',\n    text: JSON.stringify(value, null, 2),\n  });\n\n  return {\n    entry: {\n      uri: entry.uri,\n      size: entry.size,\n      mimeType: entry.mimeType,\n      expiresAt: entry.expiresAt,\n    },\n    link: {\n      type: 'resource_link',\n      uri: entry.uri,\n      name: entry.name,\n      mimeType: entry.mimeType,\n      size: entry.size,\n      annotations: { audience: ['user'] },\n    },\n  };\n}\n"]}

package/dist/core/util.d.ts

@@ -0,0 +1,26 @@
+export declare const KIB = 1024;
+export declare const MIB: number;
+export declare const GIB: number;
+export declare function parseEnvInt(envVar: string, defaultValue: number, min: number, max: number): number;
+/**
+ * Split a comma-separated config value into trimmed, non-empty entries. Empty
+ * entries are dropped so "," or " " reads as unset rather than as a list of
+ * blanks. Every comma-separated env var this server accepts parses through
+ * here, so they all agree on what "configured" means.
+ */
+export declare function splitCsvList(value: string | undefined): string[];
+export declare const PARALLEL_CONCURRENCY: number;
+export declare const ROOTS_TIMEOUT_MS = 5000;
+export declare function getMaxTextFileSize(): number;
+export declare function getDefaultReadManyMaxTotalSize(): number;
+/** Default line chunk size for read continuation when no explicit range was given. */
+export declare const DEFAULT_CONTINUATION_CHUNK_SIZE = 200;
+export declare const DEFAULT_SEARCH_TIMEOUT_MS: number;
+export declare const MAX_TREE_DEPTH = 50;
+export declare const DEFAULT_TREE_ENTRIES = 1000;
+export declare const MAX_LIST_ENTRIES = 20000;
+export declare const MAX_SEARCH_RESULTS = 10000;
+export declare const DEFAULT_SEARCH_RESULTS = 100;
+export declare const MAX_SEARCH_DEPTH = 100;
+export declare const DEFAULT_SEARCH_CONTENT_RESULTS = 500;
+//# sourceMappingURL=util.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../src/core/util.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,GAAG,OAAO,CAAC;AACxB,eAAO,MAAM,GAAG,QAAa,CAAC;AAC9B,eAAO,MAAM,GAAG,QAAa,CAAC;AAoB9B,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,MAAM,CAER;AA6BD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAKhE;AAED,eAAO,MAAM,oBAAoB,QAAoD,CAAC;AAEtF,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,wBAAgB,kBAAkB,IAAI,MAAM,CAQ3C;AAED,wBAAgB,8BAA8B,IAAI,MAAM,CAEvD;AAED,sFAAsF;AACtF,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD,eAAO,MAAM,yBAAyB,QAAwD,CAAC;AAE/F,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AAEtC,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AACxC,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,eAAO,MAAM,8BAA8B,MAAM,CAAC"}

package/dist/core/util.js

@@ -0,0 +1,66 @@
+import { availableParallelism } from 'node:os';
+import { cli } from './config.js';
+import { Logger } from './observability.js';
+export const KIB = 1024;
+export const MIB = 1024 * KIB;
+export const GIB = 1024 * MIB;
+const loggedWarns = new Set();
+function logInvalidEnvValue(envVar, value, expected, defaultValue) {
+    const key = `${envVar}:${value}:${expected}`;
+    if (loggedWarns.has(key)) {
+        return;
+    }
+    loggedWarns.add(key);
+    Logger.warn(`Invalid ${envVar} value: ${value} (must be ${expected}). Using default: ${String(defaultValue)}`);
+}
+export function parseEnvInt(envVar, defaultValue, min, max) {
+    return parseIntSetting(envVar, process.env[envVar], defaultValue, min, max);
+}
+/** Validate a raw integer setting (env var or CLI override) with a logged fallback. */
+function parseIntSetting(name, value, defaultValue, min, max) {
+    if (!value) {
+        return defaultValue;
+    }
+    const trimmed = value.trim();
+    const parsed = Number(trimmed);
+    if (trimmed === '' ||
+        Number.isNaN(parsed) ||
+        !Number.isInteger(parsed) ||
+        parsed < min ||
+        parsed > max) {
+        logInvalidEnvValue(name, value, `${String(min)}-${String(max)}`, defaultValue);
+        return defaultValue;
+    }
+    return parsed;
+}
+/**
+ * Split a comma-separated config value into trimmed, non-empty entries. Empty
+ * entries are dropped so "," or " " reads as unset rather than as a list of
+ * blanks. Every comma-separated env var this server accepts parses through
+ * here, so they all agree on what "configured" means.
+ */
+export function splitCsvList(value) {
+    return (value ?? '')
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+export const PARALLEL_CONCURRENCY = Math.min(Math.max(availableParallelism(), 4), 32);
+export const ROOTS_TIMEOUT_MS = 5000;
+export function getMaxTextFileSize() {
+    return parseIntSetting('FS_MAX_FILE_SIZE', cli.maxFileSize ?? process.env['FS_MAX_FILE_SIZE'], 10 * MIB, MIB, 100 * MIB);
+}
+export function getDefaultReadManyMaxTotalSize() {
+    return parseEnvInt('FS_MAX_READ_MANY_BYTES', 512 * KIB, 10 * KIB, 100 * MIB);
+}
+/** Default line chunk size for read continuation when no explicit range was given. */
+export const DEFAULT_CONTINUATION_CHUNK_SIZE = 200;
+export const DEFAULT_SEARCH_TIMEOUT_MS = parseEnvInt('FS_SEARCH_TIMEOUT_MS', 5000, 100, 60000);
+export const MAX_TREE_DEPTH = 50;
+export const DEFAULT_TREE_ENTRIES = 1000;
+export const MAX_LIST_ENTRIES = 20000;
+export const MAX_SEARCH_RESULTS = 10000;
+export const DEFAULT_SEARCH_RESULTS = 100;
+export const MAX_SEARCH_DEPTH = 100;
+export const DEFAULT_SEARCH_CONTENT_RESULTS = 500;
+//# sourceMappingURL=util.js.map

package/dist/core/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../../src/core/util.ts"],"names":[],"mappings":"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","sourcesContent":["import { availableParallelism } from 'node:os';\n\nimport { cli } from './config.js';\nimport { Logger } from './observability.js';\n\nexport const KIB = 1024;\nexport const MIB = 1024 * KIB;\nexport const GIB = 1024 * MIB;\n\nconst loggedWarns = new Set<string>();\n\nfunction logInvalidEnvValue(\n  envVar: string,\n  value: string,\n  expected: string,\n  defaultValue: number | boolean,\n): void {\n  const key = `${envVar}:${value}:${expected}`;\n  if (loggedWarns.has(key)) {\n    return;\n  }\n  loggedWarns.add(key);\n  Logger.warn(\n    `Invalid ${envVar} value: ${value} (must be ${expected}). Using default: ${String(defaultValue)}`,\n  );\n}\n\nexport function parseEnvInt(\n  envVar: string,\n  defaultValue: number,\n  min: number,\n  max: number,\n): number {\n  return parseIntSetting(envVar, process.env[envVar], defaultValue, min, max);\n}\n\n/** Validate a raw integer setting (env var or CLI override) with a logged fallback. */\nfunction parseIntSetting(\n  name: string,\n  value: string | undefined,\n  defaultValue: number,\n  min: number,\n  max: number,\n): number {\n  if (!value) {\n    return defaultValue;\n  }\n\n  const trimmed = value.trim();\n  const parsed = Number(trimmed);\n  if (\n    trimmed === '' ||\n    Number.isNaN(parsed) ||\n    !Number.isInteger(parsed) ||\n    parsed < min ||\n    parsed > max\n  ) {\n    logInvalidEnvValue(name, value, `${String(min)}-${String(max)}`, defaultValue);\n    return defaultValue;\n  }\n  return parsed;\n}\n\n/**\n * Split a comma-separated config value into trimmed, non-empty entries. Empty\n * entries are dropped so \",\" or \" \" reads as unset rather than as a list of\n * blanks. Every comma-separated env var this server accepts parses through\n * here, so they all agree on what \"configured\" means.\n */\nexport function splitCsvList(value: string | undefined): string[] {\n  return (value ?? '')\n    .split(',')\n    .map((entry) => entry.trim())\n    .filter(Boolean);\n}\n\nexport const PARALLEL_CONCURRENCY = Math.min(Math.max(availableParallelism(), 4), 32);\n\nexport const ROOTS_TIMEOUT_MS = 5000;\n\nexport function getMaxTextFileSize(): number {\n  return parseIntSetting(\n    'FS_MAX_FILE_SIZE',\n    cli.maxFileSize ?? process.env['FS_MAX_FILE_SIZE'],\n    10 * MIB,\n    MIB,\n    100 * MIB,\n  );\n}\n\nexport function getDefaultReadManyMaxTotalSize(): number {\n  return parseEnvInt('FS_MAX_READ_MANY_BYTES', 512 * KIB, 10 * KIB, 100 * MIB);\n}\n\n/** Default line chunk size for read continuation when no explicit range was given. */\nexport const DEFAULT_CONTINUATION_CHUNK_SIZE = 200;\n\nexport const DEFAULT_SEARCH_TIMEOUT_MS = parseEnvInt('FS_SEARCH_TIMEOUT_MS', 5000, 100, 60000);\n\nexport const MAX_TREE_DEPTH = 50;\nexport const DEFAULT_TREE_ENTRIES = 1000;\n\nexport const MAX_LIST_ENTRIES = 20000;\n\nexport const MAX_SEARCH_RESULTS = 10000;\nexport const DEFAULT_SEARCH_RESULTS = 100;\nexport const MAX_SEARCH_DEPTH = 100;\n\nexport const DEFAULT_SEARCH_CONTENT_RESULTS = 500;\n"]}

package/dist/core/watcher-registry.d.ts

@@ -0,0 +1,68 @@
+import type { PathGuard } from './path.js';
+export declare const MAX_WATCHERS: number;
+/**
+ * `ok` means a watcher is live for this uri and `notify` is registered. Every
+ * other outcome names why, and only `invalid-path` carries what
+ * `validateExistingPath` threw — so `error` is unreachable on a branch that has
+ * none.
+ */
+export type WatcherAttachResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'stale' | 'capped' | 'bad-uri' | 'attach-failed';
+} | {
+    ok: false;
+    reason: 'invalid-path';
+    error: unknown;
+};
+/**
+ * Owns the uri → FSWatcher map and the subscription bookkeeping around it:
+ * notify callbacks, desired subscribe/unsubscribe state, and the watcher cap —
+ * plus `acquire`, the one ladder that sequences them correctly. `acquire` awaits
+ * path validation midway and re-checks `isStale` and `hasWatcher` itself
+ * afterwards, so callers do not: they take a lease and release it. The
+ * individual primitives stay public for the state-machine tests.
+ */
+export declare function createWatcherRegistry(): {
+    hasWatcher: (uri: string) => boolean;
+    isAtCap: () => boolean;
+    /** Live watcher count, for pre-checking a batched listen against remaining capacity. */
+    size: () => number;
+    isStale: (uri: string) => boolean;
+    startSubscribe: (uri: string) => void;
+    cancelSubscribe: (uri: string) => void;
+    addCallback: (uri: string, notify: (uri: string) => void) => void;
+    retain: (uri: string) => void;
+    release: (uri: string) => void;
+    /**
+     * The one attach ladder both watcher entry points run: `resources/subscribe`
+     * (2025 era) and the `subscriptions/listen` filter (modern era, HTTP and
+     * stdio). Never throws — it reports the outcome and lets each caller decide
+     * what that is worth: subscribe owes its caller a precise error, and listen
+     * (`prepareListenWatchers`) treats the batch as all-or-nothing, releasing
+     * every lease it already took and rejecting the request. Idempotent per URI
+     * — a second call for an already-watched URI re-registers the notify
+     * callback (one watcher per URI).
+     *
+     * `markSubscribe` is the one branch that differs: only `resources/subscribe`
+     * declares desired state (what `isStale` aborts against). The listen path
+     * must not, or a rejected attach past that point strands a `'subscribing'`
+     * entry nothing settles. Whoever declares it, this function settles it:
+     * every failing exit past that point cancels the declaration, so no uri is
+     * poisoned for a later attach.
+     *
+     * Every `ok` return takes one lease; lifetime is the caller's to manage.
+     * HTTP releases when the listen response closes. Stdio tracks the listen
+     * request ID and releases on cancellation, SDK rejection, or graceful
+     * completion. In both legs the ref-count is by URI, so a watcher another
+     * stream still holds survives.
+     */
+    acquire(pathGuard: PathGuard, uri: string, notify: (uri: string) => void, { markSubscribe }?: {
+        markSubscribe?: boolean;
+    }): Promise<WatcherAttachResult>;
+    attach: (uri: string, resolvedPath: string) => boolean;
+    destroy(): void;
+};
+export type WatcherRegistry = ReturnType<typeof createWatcherRegistry>;
+//# sourceMappingURL=watcher-registry.d.ts.map

package/dist/core/watcher-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher-registry.d.ts","sourceRoot":"","sources":["../../src/core/watcher-registry.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAK3C,eAAO,MAAM,YAAY,QAA+C,CAAC;AAMzE;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,eAAe,CAAA;CAAE,GACvE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1D;;;;;;;GAOG;AACH,wBAAgB,qBAAqB;sBAmGV,MAAM,KAAG,OAAO;mBAErB,OAAO;IAwFzB,wFAAwF;gBAC9E,MAAM;mBAtFI,MAAM,KAAG,OAAO;0BAET,MAAM,KAAG,IAAI;2BAcZ,MAAM,KAAG,IAAI;uBAIjB,MAAM,UAAU,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,KAAG,IAAI;kBAUjD,MAAM,KAAG,IAAI;mBASZ,MAAM,KAAG,IAAI;IA6DjC;;;;;;;;;;;;;;;;;;;;;;OAsBG;uBAEU,SAAS,OACf,MAAM,UACH,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,sBACF;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,GACrD,OAAO,CAAC,mBAAmB,CAAC;kBAhFZ,MAAM,gBAAgB,MAAM,KAAG,OAAO;eA+I9C,IAAI;EAmBlB;AAED,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC"}