@bojanrajkovic/mcp-paprika 1.2.0-beta.3 → 1.3.0

package/dist/auth/build.d.ts

@@ -10,7 +10,7 @@
  * after cache.init() completes.
  */
 import type { Logger } from "pino";
-import type { DiskCache } from "../cache/disk-cache.js";
+import type { DiskCacheRoot } from "../cache/disk/index.js";
 import type { PaprikaConfig } from "../utils/config.js";
 import type { AuthContext } from "./types.js";
-export declare function buildAuthContext(config: PaprikaConfig, cache: DiskCache, parentLog: Logger): Promise<AuthContext | null>;
+export declare function buildAuthContext(config: PaprikaConfig, cache: DiskCacheRoot, parentLog: Logger): Promise<AuthContext | null>;

package/dist/auth/cleanup.d.ts

@@ -16,7 +16,7 @@
  * Public `sweepOnce()` is exposed for direct testing and for startup use.
  */
 import type { Logger } from "pino";
-import type { DiskCache } from "../cache/disk-cache.js";
+import type { DiskCacheRoot } from "../cache/disk/index.js";
 import type { AuthRequestStore } from "./auth-request-store.js";
 import type { AuthCodeStore } from "./auth-code-store.js";
 import type { DiskClientRegistrationStore } from "./client-registration.js";
@@ -31,7 +31,7 @@ export declare class AuthCleanup {
     private readonly _now;
     private readonly _intervalMs;
     private _ac;
-    constructor(_clientStore: DiskClientRegistrationStore, _tokenStore: TokenStore, _cache: DiskCache, _authRequests: AuthRequestStore, _authCodes: AuthCodeStore, log: Logger, _now?: () => number, _intervalMs?: number);
+    constructor(_clientStore: DiskClientRegistrationStore, _tokenStore: TokenStore, _cache: DiskCacheRoot, _authRequests: AuthRequestStore, _authCodes: AuthCodeStore, log: Logger, _now?: () => number, _intervalMs?: number);
     /** Start the background cleanup loop. Idempotent — second call is a no-op. */
     start(): void;
     /** Stop the background cleanup loop. Idempotent — second call is a no-op. */

package/dist/auth/cleanup.js

@@ -67,12 +67,12 @@ export class AuthCleanup {
         const now = this._now();
         // (1) Stale DCR clients: lastTokenActivityAt older than DCR_CLIENT_STALE_DAYS (90d)
         const cutoff = now - DCR_CLIENT_STALE_DAYS * 86400;
-        const allClients = await this._cache.getAllOAuthClients();
+        const allClients = await this._cache.oauthClients.getAll();
         const stale = allClients.filter((c) => c.lastTokenActivityAt < cutoff);
         // Fetch tokens once. Precompute per-client counts for the cascade loop and
         // collect expired tokens for the orphan sweep in (3). One pass over all
         // tokens, then we partition by stale-client cascade vs. expired-orphan.
-        const allTokens = await this._cache.getAllOAuthTokens();
+        const allTokens = await this._cache.oauthTokens.getAll();
         const tokensByClient = new Map();
         for (const t of allTokens) {
             tokensByClient.set(t.clientId, (tokensByClient.get(t.clientId) ?? 0) + 1);
@@ -95,7 +95,7 @@ export class AuthCleanup {
         let expiredTokensRemoved = 0;
         const expiredOrphans = allTokens.filter((t) => t.expiresAt < now && !staleClientIds.has(t.clientId));
         if (expiredOrphans.length > 0) {
-            await Promise.all(expiredOrphans.map((t) => this._cache.removeOAuthToken(t.tokenHash)));
+            await Promise.all(expiredOrphans.map((t) => this._cache.oauthTokens.remove(t.tokenHash)));
             await this._cache.flush();
             expiredTokensRemoved = expiredOrphans.length;
         }

package/dist/auth/client-registration.d.ts

@@ -10,7 +10,7 @@
  * - verifyRegistrationAccessToken: used by route handlers to gate PUT/DELETE access
  */
 import type { Logger } from "pino";
-import { DiskCache } from "../cache/disk-cache.js";
+import type { DiskCacheRoot } from "../cache/disk/index.js";
 /**
  * Wire format for client information (RFC 7591 response format).
  * Snake_case to match RFC 7591.
@@ -41,7 +41,7 @@ export declare class DiskClientRegistrationStore {
      * middleware's fast-path 429 limit).
      */
     private readonly _maxClients;
-    constructor(_cache: DiskCache, _publicUrl: string, log: Logger, 
+    constructor(_cache: DiskCacheRoot, _publicUrl: string, log: Logger, 
     /**
      * Hard cap on the number of registered clients. Enforced atomically
      * inside `registerClient` (via `DiskCache.tryPutOAuthClient`) so concurrent

package/dist/auth/client-registration.js

@@ -63,7 +63,7 @@ export class DiskClientRegistrationStore {
      * Returns undefined if not found.
      */
     async getClient(clientId) {
-        const client = await this._cache.getOAuthClient(clientId);
+        const client = await this._cache.oauthClients.get(clientId);
         if (client === null)
             return undefined;
         return storedToWire(client);
@@ -101,7 +101,7 @@ export class DiskClientRegistrationStore {
         // the authoritative race-safe enforcement. On overflow we throw an OAuth
         // `InvalidRequestError` so @hono/mcp's DCR handler returns 400 with the
         // standard `invalid_request` error code (rather than a 500).
-        const result = await this._cache.tryPutOAuthClient(stored, this._maxClients);
+        const result = await this._cache.oauthClients.tryPut(stored, this._maxClients);
         if (!result.ok) {
             throw new InvalidRequestError(`client registration cap reached (${result.currentCount.toString()} clients)`);
         }
@@ -120,7 +120,7 @@ export class DiskClientRegistrationStore {
      * Throws OAuthMetadataValidationError on invalid metadata.
      */
     async updateClient(clientId, metaIn) {
-        const existing = await this._cache.getOAuthClient(clientId);
+        const existing = await this._cache.oauthClients.get(clientId);
         if (existing === null)
             throw OAuthClientNotFoundError.forId(clientId);
         // Validate patch via dcr-validator; pass logger for URL-parse debug diagnosability
@@ -139,7 +139,7 @@ export class DiskClientRegistrationStore {
             tokenEndpointAuthMethod: "none",
             updatedAt: now,
         };
-        await this._cache.putOAuthClient(updated);
+        await this._cache.oauthClients.put(updated);
         await this._cache.flush();
         return storedToWire(updated, {
             registrationClientUri: `${this._publicUrl}/register/${clientId}`,
@@ -150,7 +150,7 @@ export class DiskClientRegistrationStore {
      * Removes from cache and disk. No cascade — the DELETE /register/:id route composes with TokenStore.removeAllForClient.
      */
     async deleteClient(clientId) {
-        await this._cache.removeOAuthClient(clientId);
+        await this._cache.oauthClients.remove(clientId);
         await this._cache.flush();
     }
     /**
@@ -158,7 +158,7 @@ export class DiskClientRegistrationStore {
      * Returns true if the hashes match, false otherwise (including client not found).
      */
     async verifyRegistrationAccessToken(clientId, presentedToken) {
-        const client = await this._cache.getOAuthClient(clientId);
+        const client = await this._cache.oauthClients.get(clientId);
         if (client === null)
             return false;
         const presentedHash = hashTokenForStorage(presentedToken);

package/dist/auth/routes.d.ts

@@ -7,7 +7,7 @@ import type { AuthCodeStore } from "./auth-code-store.js";
 import type { ResolvedOAuthConfig } from "./types.js";
 import type { DiscoveryDoc } from "./oidc-client.js";
 import type { JWTVerifyGetKey } from "jose";
-import type { DiskCache } from "../cache/disk-cache.js";
+import type { DiskCacheRoot } from "../cache/disk/index.js";
 export interface AuthRoutesDeps {
     readonly clientStore: DiskClientRegistrationStore;
     readonly tokenStore: TokenStore;
@@ -86,4 +86,4 @@ export declare function buildDcrRateLimit(options: {
  * case where the cap is obviously hit; the atomic store check closes the
  * race window for the rest.
  */
-export declare function buildClientCap(cache: DiskCache, max: number): MiddlewareHandler;
+export declare function buildClientCap(cache: DiskCacheRoot, max: number): MiddlewareHandler;

package/dist/auth/routes.js

@@ -331,7 +331,7 @@ export function buildClientCap(cache, max) {
     return async (c, next) => {
         if (c.req.path !== "/register" || c.req.method !== "POST")
             return next();
-        const clients = await cache.getAllOAuthClients();
+        const clients = await cache.oauthClients.getAll();
         if (clients.length >= max) {
             return c.json({ error: "invalid_request", error_description: "client registration cap reached" }, 429);
         }

package/dist/auth/token-store.d.ts

@@ -11,7 +11,7 @@
 import { type Result } from "neverthrow";
 import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
 import type { OAuthError } from "@modelcontextprotocol/sdk/server/auth/errors.js";
-import type { DiskCache } from "../cache/disk-cache.js";
+import type { DiskCacheRoot } from "../cache/disk/index.js";
 import type { OAuthToken } from "./types.js";
 import type { VerifiedIdentity } from "./allowlist.js";
 export interface IssuedPair {
@@ -36,7 +36,7 @@ export declare class TokenStore {
     private readonly _cache;
     private readonly _now;
     private readonly _rotateLock;
-    constructor(_cache: DiskCache, _now?: () => number);
+    constructor(_cache: DiskCacheRoot, _now?: () => number);
     /**
      * Issues a new access + refresh token pair for a client.
      *

package/dist/auth/token-store.js

@@ -62,8 +62,8 @@ export class TokenStore {
             expiresAt: refreshExpiresAt,
             createdAt: now,
         };
-        await this._cache.putOAuthToken(access);
-        await this._cache.putOAuthToken(refresh);
+        await this._cache.oauthTokens.put(access);
+        await this._cache.oauthTokens.put(refresh);
         await this._bumpLastActivity(input.clientId, now);
         await this._cache.flush();
         return {
@@ -84,7 +84,7 @@ export class TokenStore {
      */
     async lookupAccessToken(plaintext) {
         const hash = hashTokenForStorage(plaintext);
-        const record = await this._cache.getOAuthToken(hash);
+        const record = await this._cache.oauthTokens.get(hash);
         if (record === null || record.kind !== "access")
             return null;
         if (record.expiresAt < this._now())
@@ -115,7 +115,7 @@ export class TokenStore {
      */
     async lookupRefreshToken(plaintext) {
         const hash = hashTokenForStorage(plaintext);
-        const record = await this._cache.getOAuthToken(hash);
+        const record = await this._cache.oauthTokens.get(hash);
         if (record === null || record.kind !== "refresh")
             return null;
         if (record.expiresAt < this._now())
@@ -166,7 +166,7 @@ export class TokenStore {
                 newScope = requestedScopes.join(" ");
             }
             // Invalidate the old refresh token IMMEDIATELY (AC7.7)
-            await this._cache.removeOAuthToken(existing.tokenHash);
+            await this._cache.oauthTokens.remove(existing.tokenHash);
             await this._cache.flush();
             // Mint the new pair with rotation linkage
             const accessPlain = generateOpaqueToken("mcp_at_");
@@ -174,7 +174,7 @@ export class TokenStore {
             const now = this._now();
             const accessExpiresAt = now + ACCESS_TOKEN_TTL_SECONDS;
             const refreshExpiresAt = now + REFRESH_TOKEN_TTL_SECONDS;
-            await this._cache.putOAuthToken({
+            await this._cache.oauthTokens.put({
                 tokenHash: hashTokenForStorage(accessPlain),
                 kind: "access",
                 clientId: existing.clientId,
@@ -184,7 +184,7 @@ export class TokenStore {
                 expiresAt: accessExpiresAt,
                 createdAt: now,
             });
-            await this._cache.putOAuthToken({
+            await this._cache.oauthTokens.put({
                 tokenHash: hashTokenForStorage(refreshPlain),
                 kind: "refresh",
                 clientId: existing.clientId,
@@ -215,7 +215,7 @@ export class TokenStore {
      */
     async getTokenRecord(plaintext) {
         const hash = hashTokenForStorage(plaintext);
-        return this._cache.getOAuthToken(hash);
+        return this._cache.oauthTokens.get(hash);
     }
     /**
      * Revokes a token by removing its hash from the cache.
@@ -235,7 +235,7 @@ export class TokenStore {
     async revoke(plaintext) {
         await this._rotateLock.runExclusive(async () => {
             const hash = hashTokenForStorage(plaintext);
-            await this._cache.removeOAuthToken(hash);
+            await this._cache.oauthTokens.remove(hash);
             await this._cache.flush();
         });
     }
@@ -254,9 +254,9 @@ export class TokenStore {
      */
     async removeAllForClient(clientId) {
         await this._rotateLock.runExclusive(async () => {
-            const all = await this._cache.getAllOAuthTokens();
+            const all = await this._cache.oauthTokens.getAll();
             const matching = all.filter((t) => t.clientId === clientId);
-            await Promise.all(matching.map((t) => this._cache.removeOAuthToken(t.tokenHash)));
+            await Promise.all(matching.map((t) => this._cache.oauthTokens.remove(t.tokenHash)));
             await this._cache.flush();
         });
     }
@@ -267,9 +267,9 @@ export class TokenStore {
      * (race with deletion). Does not flush — caller is responsible.
      */
     async _bumpLastActivity(clientId, now) {
-        const client = await this._cache.getOAuthClient(clientId);
+        const client = await this._cache.oauthClients.get(clientId);
         if (client === null)
             return; // race with deletion
-        await this._cache.putOAuthClient({ ...client, lastTokenActivityAt: now });
+        await this._cache.oauthClients.put({ ...client, lastTokenActivityAt: now });
     }
 }

package/dist/auth/types.d.ts

@@ -240,13 +240,13 @@ export declare const IdentitySchema: z.ZodObject<{
     sub: z.ZodString;
     source: z.ZodEnum<["email", "sub"]>;
 }, "strip", z.ZodTypeAny, {
-    source: "sub" | "email";
-    sub: string;
     email: string | null;
-}, {
-    source: "sub" | "email";
     sub: string;
+    source: "email" | "sub";
+}, {
     email: string | null;
+    sub: string;
+    source: "email" | "sub";
 }>;
 /**
  * RFC 8707 resource indicator — must be a fully-qualified URL or an explicit empty
@@ -264,13 +264,13 @@ export declare const OAuthTokenSchema: z.ZodObject<{
         sub: z.ZodString;
         source: z.ZodEnum<["email", "sub"]>;
     }, "strip", z.ZodTypeAny, {
-        source: "sub" | "email";
-        sub: string;
         email: string | null;
-    }, {
-        source: "sub" | "email";
         sub: string;
+        source: "email" | "sub";
+    }, {
         email: string | null;
+        sub: string;
+        source: "email" | "sub";
     }>;
     resource: z.ZodUnion<[z.ZodString, z.ZodLiteral<"">]>;
     expiresAt: z.ZodNumber;
@@ -282,9 +282,9 @@ export declare const OAuthTokenSchema: z.ZodObject<{
     scope: string;
     createdAt: number;
     identity: {
-        source: "sub" | "email";
-        sub: string;
         email: string | null;
+        sub: string;
+        source: "email" | "sub";
     };
     tokenHash: string;
     kind: "access" | "refresh";
@@ -296,9 +296,9 @@ export declare const OAuthTokenSchema: z.ZodObject<{
     scope: string;
     createdAt: number;
     identity: {
-        source: "sub" | "email";
-        sub: string;
         email: string | null;
+        sub: string;
+        source: "email" | "sub";
     };
     tokenHash: string;
     kind: "access" | "refresh";
@@ -353,13 +353,13 @@ export declare const AuthCodeStateSchema: z.ZodObject<{
         sub: z.ZodString;
         source: z.ZodEnum<["email", "sub"]>;
     }, "strip", z.ZodTypeAny, {
-        source: "sub" | "email";
-        sub: string;
         email: string | null;
-    }, {
-        source: "sub" | "email";
         sub: string;
+        source: "email" | "sub";
+    }, {
         email: string | null;
+        sub: string;
+        source: "email" | "sub";
     }>;
 }, "strip", z.ZodTypeAny, {
     clientId: string;
@@ -370,9 +370,9 @@ export declare const AuthCodeStateSchema: z.ZodObject<{
     scope: string;
     createdAt: number;
     identity: {
-        source: "sub" | "email";
-        sub: string;
         email: string | null;
+        sub: string;
+        source: "email" | "sub";
     };
 }, {
     clientId: string;
@@ -383,9 +383,9 @@ export declare const AuthCodeStateSchema: z.ZodObject<{
     scope: string;
     createdAt: number;
     identity: {
-        source: "sub" | "email";
-        sub: string;
         email: string | null;
+        sub: string;
+        source: "email" | "sub";
     };
 }>;
 export type AuthCodeState = z.infer<typeof AuthCodeStateSchema>;
@@ -423,13 +423,13 @@ export declare const AuthInfoExtraSchema: z.ZodObject<{
     sub: z.ZodString;
     source: z.ZodEnum<["email", "sub"]>;
 }, "strip", z.ZodTypeAny, {
-    source: "sub" | "email";
-    sub: string;
     email: string | null;
-}, {
-    source: "sub" | "email";
     sub: string;
+    source: "email" | "sub";
+}, {
     email: string | null;
+    sub: string;
+    source: "email" | "sub";
 }>;
 export type AuthInfoExtra = z.infer<typeof AuthInfoExtraSchema>;
 export interface AuthContext {

package/dist/cache/disk/base.d.ts

@@ -0,0 +1,56 @@
+import { Mutex } from "async-mutex";
+import type { Logger } from "pino";
+/** Open + write + fsync + close — one atomic durable write per call. */
+export declare function writeFileAtomic(path: string, contents: string): Promise<void>;
+export interface DiskCacheOptions<T> {
+    readonly subdir: string;
+    /**
+     * Validates a raw JSON value read from disk and returns a typed `T`.
+     * Wraps the Zod schema's `parse` to sidestep Zod's branded-type input
+     * variance (the schema input is `string`, the output is `string & BRAND`,
+     * which can't be expressed through a single `ZodType<T>` parameter).
+     */
+    readonly parse: (raw: unknown) => T;
+    readonly getKey: (item: T) => string;
+    readonly log?: Logger;
+}
+export declare class DiskCache<T> {
+    protected readonly _subdir: string;
+    protected readonly _parse: (raw: unknown) => T;
+    protected readonly _getKey: (item: T) => string;
+    protected readonly _pending: Map<string, T>;
+    protected readonly _knownKeys: Set<string>;
+    protected readonly _mutex: Mutex;
+    protected readonly log: Logger;
+    protected _initialized: boolean;
+    constructor(opts: DiskCacheOptions<T>);
+    init(): Promise<void>;
+    flush(): Promise<void>;
+    get(key: string): Promise<T | null>;
+    getAll(): Promise<Array<T>>;
+    put(item: T): Promise<void>;
+    remove(key: string): Promise<void>;
+    /**
+     * Mutex-free buffer write. Subclasses call this from their own `put`
+     * overrides (which already hold the mutex) to extend the put with extra
+     * bookkeeping like a hash map without recursively locking.
+     */
+    protected _putInner(item: T): void;
+    /**
+     * Mutex-free remove. Subclasses call this from their own `remove`
+     * overrides. ENOENT on unlink is idempotent — the file already being
+     * gone is the desired end state.
+     */
+    protected _removeInner(key: string): Promise<void>;
+    has(key: string): boolean;
+    get size(): number;
+    /**
+     * Template-method hook: write pending entries to disk inside the mutex.
+     * Subclasses override to add post-write work (e.g. recipes writes its
+     * hash index after the data files are durable). Must NOT re-acquire the
+     * mutex — the caller (`flush()`) already holds it.
+     */
+    protected _writePending(): Promise<void>;
+    protected _writeFileAtomic(path: string, contents: string): Promise<void>;
+    protected _assertInitialized(method: string): void;
+}

package/dist/cache/disk/base.js

@@ -0,0 +1,191 @@
+import { mkdir, open, readdir, readFile, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { Mutex } from "async-mutex";
+import { isNodeError } from "../../utils/errors.js";
+import { SILENT_LOG } from "../../utils/log.js";
+// I/O error handling convention throughout this module:
+// We use try/catch and check error.code rather than existsSync()-then-read.
+// existsSync() is synchronous (blocks the event loop) and introduces a TOCTOU
+// race; try/catch handles the file's actual state at I/O time with no race
+// window. Non-ENOENT codes (EISDIR, EACCES, …) are rethrown so unexpected
+// errors are never silently swallowed.
+/** Open + write + fsync + close — one atomic durable write per call. */
+export async function writeFileAtomic(path, contents) {
+    const fh = await open(path, "w");
+    try {
+        await fh.writeFile(contents);
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+}
+export class DiskCache {
+    _subdir;
+    _parse;
+    _getKey;
+    _pending = new Map();
+    // In-memory mirror of "what keys have a .json file on disk for this entity."
+    // Populated from readdir at init() and maintained by put()/remove(). For
+    // non-hashed entities this is the complete index — the recipes subclass
+    // additionally tracks a UID → hash map for diffing.
+    _knownKeys = new Set();
+    _mutex = new Mutex();
+    log;
+    _initialized = false;
+    constructor(opts) {
+        this._subdir = opts.subdir;
+        this._parse = opts.parse;
+        this._getKey = opts.getKey;
+        this.log = opts.log ?? SILENT_LOG;
+    }
+    async init() {
+        await mkdir(this._subdir, { recursive: true });
+        let files;
+        try {
+            files = await readdir(this._subdir);
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                this._initialized = true;
+                return;
+            }
+            throw error;
+        }
+        for (const f of files) {
+            // Skip the per-entity index file (only RecipeDiskCache writes one). All
+            // other data files are <key>.json; the recipes index is the lone
+            // exception, kept inside the entity's subdir to keep migration simple.
+            if (f === "index.json")
+                continue;
+            if (f.endsWith(".json")) {
+                this._knownKeys.add(f.slice(0, -5));
+            }
+        }
+        this._initialized = true;
+    }
+    async flush() {
+        return this._mutex.runExclusive(() => {
+            this._assertInitialized("flush");
+            return this._writePending();
+        });
+    }
+    async get(key) {
+        this._assertInitialized("get");
+        const hit = this._pending.get(key);
+        if (hit !== undefined)
+            return hit;
+        const filePath = join(this._subdir, `${key}.json`);
+        let raw;
+        try {
+            raw = await readFile(filePath, "utf-8");
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                // Cold-start cache miss; silent by design.
+                return null;
+            }
+            throw error;
+        }
+        return this._parse(JSON.parse(raw));
+    }
+    async getAll() {
+        this._assertInitialized("getAll");
+        // Pending entries shadow disk; seed result with the buffer.
+        const result = new Map(this._pending);
+        // Read the directory live, not from `_knownKeys`. A second cache
+        // instance pointing at the same dir can have written new files we
+        // haven't observed yet; tests and operator-side seeding both rely on
+        // this. The DCR cap middleware in particular reads `oauthClients.getAll()`
+        // on every POST /register and must see externally-seeded files.
+        let files;
+        try {
+            files = await readdir(this._subdir);
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                return [...result.values()];
+            }
+            throw error;
+        }
+        await Promise.all(files.map(async (filename) => {
+            if (!filename.endsWith(".json") || filename === "index.json")
+                return;
+            const key = filename.slice(0, -5);
+            if (result.has(key))
+                return;
+            const raw = await readFile(join(this._subdir, filename), "utf-8");
+            result.set(key, this._parse(JSON.parse(raw)));
+        }));
+        return [...result.values()];
+    }
+    async put(item) {
+        return this._mutex.runExclusive(() => {
+            this._assertInitialized("put");
+            this._putInner(item);
+        });
+    }
+    async remove(key) {
+        return this._mutex.runExclusive(async () => {
+            this._assertInitialized("remove");
+            await this._removeInner(key);
+        });
+    }
+    /**
+     * Mutex-free buffer write. Subclasses call this from their own `put`
+     * overrides (which already hold the mutex) to extend the put with extra
+     * bookkeeping like a hash map without recursively locking.
+     */
+    _putInner(item) {
+        const key = this._getKey(item);
+        this._pending.set(key, item);
+        this._knownKeys.add(key);
+    }
+    /**
+     * Mutex-free remove. Subclasses call this from their own `remove`
+     * overrides. ENOENT on unlink is idempotent — the file already being
+     * gone is the desired end state.
+     */
+    async _removeInner(key) {
+        const filePath = join(this._subdir, `${key}.json`);
+        try {
+            await unlink(filePath);
+        }
+        catch (error) {
+            if (!isNodeError(error) || error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        this._pending.delete(key);
+        this._knownKeys.delete(key);
+    }
+    has(key) {
+        return this._knownKeys.has(key);
+    }
+    get size() {
+        return this._knownKeys.size;
+    }
+    /**
+     * Template-method hook: write pending entries to disk inside the mutex.
+     * Subclasses override to add post-write work (e.g. recipes writes its
+     * hash index after the data files are durable). Must NOT re-acquire the
+     * mutex — the caller (`flush()`) already holds it.
+     */
+    async _writePending() {
+        if (this._pending.size === 0)
+            return;
+        const entries = [...this._pending.entries()];
+        await Promise.all(entries.map(async ([key, item]) => {
+            await this._writeFileAtomic(join(this._subdir, `${key}.json`), JSON.stringify(item, null, 2));
+        }));
+        this._pending.clear();
+    }
+    async _writeFileAtomic(path, contents) {
+        return writeFileAtomic(path, contents);
+    }
+    _assertInitialized(method) {
+        if (!this._initialized) {
+            throw new Error(`DiskCache: ${method}() called before init()`);
+        }
+    }
+}

package/dist/cache/disk/index.d.ts

@@ -0,0 +1,5 @@
+export { DiskCache } from "./base.js";
+export type { DiskCacheOptions } from "./base.js";
+export { RecipeDiskCache } from "./recipes.js";
+export { OAuthClientDiskCache } from "./oauth-clients.js";
+export { DiskCacheRoot } from "./root.js";

package/dist/cache/disk/index.js

@@ -0,0 +1,4 @@
+export { DiskCache } from "./base.js";
+export { RecipeDiskCache } from "./recipes.js";
+export { OAuthClientDiskCache } from "./oauth-clients.js";
+export { DiskCacheRoot } from "./root.js";