payload-mcp-toolkit 0.3.4 → 0.7.4

package/dist/scope/audit-log.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/scope/audit-log.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\r\n\r\n// ─── Audit logging helpers ───────────────────────────────────────────\r\n\r\nconst MAX_LOGGED_STRING = 200\r\n\r\n/**\r\n * Returns the top-level keys of a JSON-string `data` arg, sanitized.\r\n * Per the Codex post-planning finding: logging key names (not values) lets us\r\n * later analyze whether the prose-only input shape is causing AI mistakes.\r\n */\r\nexport function extractDataKeys(args: Record<string, unknown>): string[] | undefined {\r\n  const data = args.data\r\n  if (typeof data !== 'string') return undefined\r\n  try {\r\n    const parsed = JSON.parse(data) as unknown\r\n    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {\r\n      return Object.keys(parsed as Record<string, unknown>)\r\n    }\r\n  } catch {\r\n    return undefined\r\n  }\r\n  return undefined\r\n}\r\n\r\nexport function summariseArgs(args: Record<string, unknown>): Record<string, unknown> {\r\n  const out: Record<string, unknown> = {}\r\n  for (const [k, v] of Object.entries(args)) {\r\n    if (typeof v === 'string' && v.length > MAX_LOGGED_STRING) {\r\n      out[k] = `<truncated:${v.length}>`\r\n    } else {\r\n      out[k] = v\r\n    }\r\n  }\r\n  return out\r\n}\r\n\r\nexport function getRequestId(req: PayloadRequest): string | undefined {\r\n  const headers = req.headers as Headers | undefined\r\n  return headers?.get?.('x-request-id') ?? undefined\r\n}\r\n\r\ntype LoggerLike = Partial<Record<'info' | 'warn' | 'error', (...args: unknown[]) => unknown>>\r\n\r\n/**\r\n * Returns a logger-invoker that swallows transport failures. Audit-log\r\n * writes must never break the tool dispatch path — a throwing logger\r\n * transport (closed stream during HMR, a custom pino dest) would otherwise\r\n * flip a success to isError or mask the real tool error.\r\n */\r\nexport function makeSafeLog(logger: LoggerLike | undefined) {\r\n  return (\r\n    level: 'info' | 'warn' | 'error',\r\n    payload: Record<string, unknown>,\r\n    message: string,\r\n  ) => {\r\n    try {\r\n      logger?.[level]?.(payload, message)\r\n    } catch {\r\n      // Logger transport failure must not break dispatch.\r\n    }\r\n  }\r\n}\r\n"],"names":["MAX_LOGGED_STRING","extractDataKeys","args","data","undefined","parsed","JSON","parse","Array","isArray","Object","keys","summariseArgs","out","k","v","entries","length","getRequestId","req","headers","get","makeSafeLog","logger","level","payload","message"],"mappings":"AAEA,wEAAwE;AAExE,MAAMA,oBAAoB;AAE1B;;;;CAIC,GACD,OAAO,SAASC,gBAAgBC,IAA6B;IAC3D,MAAMC,OAAOD,KAAKC,IAAI;IACtB,IAAI,OAAOA,SAAS,UAAU,OAAOC;IACrC,IAAI;QACF,MAAMC,SAASC,KAAKC,KAAK,CAACJ;QAC1B,IAAIE,UAAU,OAAOA,WAAW,YAAY,CAACG,MAAMC,OAAO,CAACJ,SAAS;YAClE,OAAOK,OAAOC,IAAI,CAACN;QACrB;IACF,EAAE,OAAM;QACN,OAAOD;IACT;IACA,OAAOA;AACT;AAEA,OAAO,SAASQ,cAAcV,IAA6B;IACzD,MAAMW,MAA+B,CAAC;IACtC,KAAK,MAAM,CAACC,GAAGC,EAAE,IAAIL,OAAOM,OAAO,CAACd,MAAO;QACzC,IAAI,OAAOa,MAAM,YAAYA,EAAEE,MAAM,GAAGjB,mBAAmB;YACzDa,GAAG,CAACC,EAAE,GAAG,CAAC,WAAW,EAAEC,EAAEE,MAAM,CAAC,CAAC,CAAC;QACpC,OAAO;YACLJ,GAAG,CAACC,EAAE,GAAGC;QACX;IACF;IACA,OAAOF;AACT;AAEA,OAAO,SAASK,aAAaC,GAAmB;IAC9C,MAAMC,UAAUD,IAAIC,OAAO;IAC3B,OAAOA,SAASC,MAAM,mBAAmBjB;AAC3C;AAIA;;;;;CAKC,GACD,OAAO,SAASkB,YAAYC,MAA8B;IACxD,OAAO,CACLC,OACAC,SACAC;QAEA,IAAI;YACFH,QAAQ,CAACC,MAAM,GAAGC,SAASC;QAC7B,EAAE,OAAM;QACN,oDAAoD;QACtD;IACF;AACF"}

package/dist/scope/policy.d.ts

@@ -0,0 +1,73 @@
+import type { CollectionAction, GlobalAction, KeyScopes, ScopePreset } from '../types';
+export type ResourceKind = 'collection' | 'global' | 'account';
+/**
+ * Discriminated routing tag attached to every tool factory output.
+ *
+ * Collocates the scope-routing decision with the tool definition itself —
+ * the registry derives the collection/global/account lookups from `tools`
+ * at boot. Adding a new tool can no longer drift the routing maps out of
+ * sync because TS requires `routing` on every factory return.
+ */
+export type ToolRouting = {
+    kind: 'collection';
+    action: CollectionAction;
+} | {
+    kind: 'global';
+    action: GlobalAction;
+} | {
+    kind: 'account';
+    action: CollectionAction;
+};
+/**
+ * Minimal "routable tool" interface used by the policy module. The full
+ * `ToolFactoryOutput` shape (handler, parameters, description) is irrelevant
+ * here; we only need `name` + `routing` to build the lookup tables.
+ */
+export interface RoutableTool {
+    name: string;
+    routing: ToolRouting;
+}
+export declare const PRESET_ACTIONS: Record<ScopePreset, CollectionAction[]>;
+/**
+ * Asymmetric per-preset action map for globals. `editor` is intentionally
+ * read-only on globals — a single bad write on a singleton broadcasts
+ * site-wide with no per-document containment. Operators who want global
+ * writes promote the key to `admin` or use a Custom key with explicit
+ * `globalScopes`. README and CHANGELOG call out the asymmetry.
+ */
+export declare const PRESET_GLOBAL_ACTIONS: Record<ScopePreset, GlobalAction[]>;
+export declare const PRESET_TOOL_DENY: Record<ScopePreset, string[]>;
+export interface ScopeDecision {
+    allowed: boolean;
+    reason?: string;
+}
+export interface RoutingTables {
+    collectionToolAction: ReadonlyMap<string, CollectionAction>;
+    globalToolAction: ReadonlyMap<string, GlobalAction>;
+    accountToolAction: ReadonlyMap<string, CollectionAction>;
+    toolKind: ReadonlyMap<string, ResourceKind>;
+}
+export declare function buildRoutingTables(tools: RoutableTool[]): RoutingTables;
+export type ScopeChecker = (scopes: KeyScopes | null | undefined, toolName: string, resource: string | undefined) => ScopeDecision;
+/**
+ * Build a scope checker bound to a concrete tool list. The checker is a pure
+ * function over (scopes, toolName, resource) — the routing tables are closed
+ * over once at construction time.
+ *
+ * Fail-closed semantics:
+ *   - Null/undefined scopes grant full access (back-compat).
+ *   - When `scopes.collections` / `scopes.globals` is set, it is a *whitelist*
+ *     for that resource kind — unlisted resources are denied.
+ *   - When a tool resolves to a collection or global kind but the corresponding
+ *     scope map is undefined and `scopes.preset` is undefined, the call is
+ *     denied (closes the `tools.allow`-only latent fail-open).
+ *   - Account-level tools are gated by the preset's action list, if a preset
+ *     is set. Without a preset, a key scoped to specific collections/globals
+ *     cannot use account-level tools — they'd broaden the surface.
+ */
+export declare function buildScopeChecker(tools: RoutableTool[]): ScopeChecker;
+/**
+ * Internal pure checker. Exposed for the per-request wrapper in the registry
+ * so it can re-use the same `RoutingTables` it built once at startup.
+ */
+export declare function assertScopeAllows(scopes: KeyScopes | null | undefined, toolName: string, resource: string | undefined, tables: RoutingTables): ScopeDecision;

package/dist/scope/policy.js

@@ -0,0 +1,218 @@
+// ─── Per-preset action tables ────────────────────────────────────────
+const ALL_ACTIONS = [
+    'read',
+    'create',
+    'update',
+    'delete'
+];
+export const PRESET_ACTIONS = {
+    'read-only': [
+        'read'
+    ],
+    editor: [
+        'read',
+        'create',
+        'update'
+    ],
+    admin: ALL_ACTIONS
+};
+/**
+ * Asymmetric per-preset action map for globals. `editor` is intentionally
+ * read-only on globals — a single bad write on a singleton broadcasts
+ * site-wide with no per-document containment. Operators who want global
+ * writes promote the key to `admin` or use a Custom key with explicit
+ * `globalScopes`. README and CHANGELOG call out the asymmetry.
+ */ export const PRESET_GLOBAL_ACTIONS = {
+    'read-only': [
+        'read'
+    ],
+    editor: [
+        'read'
+    ],
+    admin: [
+        'read',
+        'update'
+    ]
+};
+export const PRESET_TOOL_DENY = {
+    'read-only': [],
+    editor: [
+        'safeDelete',
+        'deleteDocument'
+    ],
+    admin: []
+};
+export function buildRoutingTables(tools) {
+    const collectionToolAction = new Map();
+    const globalToolAction = new Map();
+    const accountToolAction = new Map();
+    const toolKind = new Map();
+    for (const t of tools){
+        toolKind.set(t.name, t.routing.kind);
+        if (t.routing.kind === 'collection') collectionToolAction.set(t.name, t.routing.action);
+        else if (t.routing.kind === 'global') globalToolAction.set(t.name, t.routing.action);
+        else accountToolAction.set(t.name, t.routing.action);
+    }
+    return {
+        collectionToolAction,
+        globalToolAction,
+        accountToolAction,
+        toolKind
+    };
+}
+/**
+ * Build a scope checker bound to a concrete tool list. The checker is a pure
+ * function over (scopes, toolName, resource) — the routing tables are closed
+ * over once at construction time.
+ *
+ * Fail-closed semantics:
+ *   - Null/undefined scopes grant full access (back-compat).
+ *   - When `scopes.collections` / `scopes.globals` is set, it is a *whitelist*
+ *     for that resource kind — unlisted resources are denied.
+ *   - When a tool resolves to a collection or global kind but the corresponding
+ *     scope map is undefined and `scopes.preset` is undefined, the call is
+ *     denied (closes the `tools.allow`-only latent fail-open).
+ *   - Account-level tools are gated by the preset's action list, if a preset
+ *     is set. Without a preset, a key scoped to specific collections/globals
+ *     cannot use account-level tools — they'd broaden the surface.
+ */ export function buildScopeChecker(tools) {
+    const tables = buildRoutingTables(tools);
+    return (scopes, toolName, resource)=>assertScopeAllows(scopes, toolName, resource, tables);
+}
+/**
+ * Internal pure checker. Exposed for the per-request wrapper in the registry
+ * so it can re-use the same `RoutingTables` it built once at startup.
+ */ export function assertScopeAllows(scopes, toolName, resource, tables) {
+    const resourceKind = tables.toolKind.get(toolName) ?? null;
+    // Unregistered tool — fail-closed at request time. Adding a tool without a
+    // routing field is a TS error at the factory return site, so this branch
+    // only fires for typo'd tool names sent by the client.
+    if (resourceKind === null) {
+        return {
+            allowed: false,
+            reason: `Tool "${toolName}" has no registered scope mapping.`
+        };
+    }
+    if (!scopes || scopes.preset === undefined && !scopes.collections && !scopes.globals && !scopes.tools) {
+        return {
+            allowed: true
+        };
+    }
+    if (scopes.tools?.deny?.includes(toolName)) {
+        return {
+            allowed: false,
+            reason: `Tool "${toolName}" is denied for this API key.`
+        };
+    }
+    if (scopes.tools?.allow && !scopes.tools.allow.includes(toolName)) {
+        return {
+            allowed: false,
+            reason: `Tool "${toolName}" is not in the allow-list for this API key.`
+        };
+    }
+    if (scopes.preset && PRESET_TOOL_DENY[scopes.preset]?.includes(toolName)) {
+        return {
+            allowed: false,
+            reason: `Tool "${toolName}" is not allowed by the "${scopes.preset}" preset.`
+        };
+    }
+    if (resourceKind === 'account') {
+        return checkAccount(scopes, toolName, tables.accountToolAction);
+    }
+    const policy = resourceKind === 'collection' ? COLLECTION_POLICY : GLOBAL_POLICY;
+    const toolAction = resourceKind === 'collection' ? tables.collectionToolAction : tables.globalToolAction;
+    return checkResource(scopes, toolName, resource, toolAction, policy);
+}
+const COLLECTION_POLICY = {
+    presetActions: PRESET_ACTIONS,
+    scopeAxis: 'collections',
+    label: 'collection',
+    Label: 'Collection'
+};
+const GLOBAL_POLICY = {
+    presetActions: PRESET_GLOBAL_ACTIONS,
+    scopeAxis: 'globals',
+    label: 'global',
+    Label: 'Global'
+};
+function checkResource(scopes, toolName, resource, toolAction, policy) {
+    const action = toolAction.get(toolName);
+    const presetActions = scopes.preset ? policy.presetActions[scopes.preset] : undefined;
+    const resourceScope = scopes[policy.scopeAxis];
+    if (!resource) {
+        // Resource-keyed tool called without a slug; defer to schema validation.
+        return {
+            allowed: true
+        };
+    }
+    if (!action) return {
+        allowed: true
+    };
+    if (resourceScope) {
+        const override = resourceScope[resource];
+        if (!override) {
+            return {
+                allowed: false,
+                reason: `${policy.Label} "${resource}" is not in this API key's allowed ${policy.scopeAxis}.`
+            };
+        }
+        if (!override.includes(action)) {
+            return {
+                allowed: false,
+                reason: `Action "${action}" on ${policy.label} "${resource}" is not permitted by this API key's scope.`
+            };
+        }
+        return {
+            allowed: true
+        };
+    }
+    if (!presetActions) {
+        // Fail-closed: `tools.allow` without a resource map or preset would
+        // otherwise broadcast the tool across every resource. Require explicit
+        // intent.
+        return {
+            allowed: false,
+            reason: `Tool "${toolName}" requires an explicit ${policy.label} scope or preset on this API key.`
+        };
+    }
+    if (!presetActions.includes(action)) {
+        return {
+            allowed: false,
+            reason: `Action "${action}" on ${policy.label} "${resource}" is not permitted by this API key's preset.`
+        };
+    }
+    return {
+        allowed: true
+    };
+}
+function checkAccount(scopes, toolName, toolAction) {
+    const action = toolAction.get(toolName);
+    const presetActions = scopes.preset ? PRESET_ACTIONS[scopes.preset] : undefined;
+    // Explicit resource override is the tightest signal: an account-level tool
+    // operates across the whole site (searchContent across every collection,
+    // uploadMedia into any media coll, etc.) and would broaden the key beyond
+    // the resource whitelist regardless of which preset is set. Deny account
+    // tools whenever the key carries explicit collection/global scopes.
+    if (scopes.collections || scopes.globals) {
+        return {
+            allowed: false,
+            reason: `Tool "${toolName}" is denied for keys with explicit collection or global scopes — account-level tools would broaden access beyond the whitelist.`
+        };
+    }
+    if (presetActions) {
+        if (action && !presetActions.includes(action)) {
+            return {
+                allowed: false,
+                reason: `Action "${action}" is not permitted by this API key's preset.`
+            };
+        }
+        return {
+            allowed: true
+        };
+    }
+    return {
+        allowed: true
+    };
+}
+
+//# sourceMappingURL=policy.js.map

package/dist/scope/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/scope/policy.ts"],"sourcesContent":["import type { CollectionAction, GlobalAction, KeyScopes, ScopePreset } from '../types'\r\n\r\n// ─── Routing primitives ──────────────────────────────────────────────\r\n\r\nexport type ResourceKind = 'collection' | 'global' | 'account'\r\n\r\n/**\r\n * Discriminated routing tag attached to every tool factory output.\r\n *\r\n * Collocates the scope-routing decision with the tool definition itself —\r\n * the registry derives the collection/global/account lookups from `tools`\r\n * at boot. Adding a new tool can no longer drift the routing maps out of\r\n * sync because TS requires `routing` on every factory return.\r\n */\r\nexport type ToolRouting =\r\n  | { kind: 'collection'; action: CollectionAction }\r\n  | { kind: 'global'; action: GlobalAction }\r\n  | { kind: 'account'; action: CollectionAction }\r\n\r\n/**\r\n * Minimal \"routable tool\" interface used by the policy module. The full\r\n * `ToolFactoryOutput` shape (handler, parameters, description) is irrelevant\r\n * here; we only need `name` + `routing` to build the lookup tables.\r\n */\r\nexport interface RoutableTool {\r\n  name: string\r\n  routing: ToolRouting\r\n}\r\n\r\n// ─── Per-preset action tables ────────────────────────────────────────\r\n\r\nconst ALL_ACTIONS: CollectionAction[] = ['read', 'create', 'update', 'delete']\r\n\r\nexport const PRESET_ACTIONS: Record<ScopePreset, CollectionAction[]> = {\r\n  'read-only': ['read'],\r\n  editor: ['read', 'create', 'update'],\r\n  admin: ALL_ACTIONS,\r\n}\r\n\r\n/**\r\n * Asymmetric per-preset action map for globals. `editor` is intentionally\r\n * read-only on globals — a single bad write on a singleton broadcasts\r\n * site-wide with no per-document containment. Operators who want global\r\n * writes promote the key to `admin` or use a Custom key with explicit\r\n * `globalScopes`. README and CHANGELOG call out the asymmetry.\r\n */\r\nexport const PRESET_GLOBAL_ACTIONS: Record<ScopePreset, GlobalAction[]> = {\r\n  'read-only': ['read'],\r\n  editor: ['read'],\r\n  admin: ['read', 'update'],\r\n}\r\n\r\nexport const PRESET_TOOL_DENY: Record<ScopePreset, string[]> = {\r\n  'read-only': [],\r\n  editor: ['safeDelete', 'deleteDocument'],\r\n  admin: [],\r\n}\r\n\r\n// ─── Routing tables built from the tool list ─────────────────────────\r\n\r\nexport interface ScopeDecision {\r\n  allowed: boolean\r\n  reason?: string\r\n}\r\n\r\nexport interface RoutingTables {\r\n  collectionToolAction: ReadonlyMap<string, CollectionAction>\r\n  globalToolAction: ReadonlyMap<string, GlobalAction>\r\n  accountToolAction: ReadonlyMap<string, CollectionAction>\r\n  toolKind: ReadonlyMap<string, ResourceKind>\r\n}\r\n\r\nexport function buildRoutingTables(tools: RoutableTool[]): RoutingTables {\r\n  const collectionToolAction = new Map<string, CollectionAction>()\r\n  const globalToolAction = new Map<string, GlobalAction>()\r\n  const accountToolAction = new Map<string, CollectionAction>()\r\n  const toolKind = new Map<string, ResourceKind>()\r\n  for (const t of tools) {\r\n    toolKind.set(t.name, t.routing.kind)\r\n    if (t.routing.kind === 'collection') collectionToolAction.set(t.name, t.routing.action)\r\n    else if (t.routing.kind === 'global') globalToolAction.set(t.name, t.routing.action)\r\n    else accountToolAction.set(t.name, t.routing.action)\r\n  }\r\n  return { collectionToolAction, globalToolAction, accountToolAction, toolKind }\r\n}\r\n\r\n// ─── Scope evaluation ────────────────────────────────────────────────\r\n\r\nexport type ScopeChecker = (\r\n  scopes: KeyScopes | null | undefined,\r\n  toolName: string,\r\n  resource: string | undefined,\r\n) => ScopeDecision\r\n\r\n/**\r\n * Build a scope checker bound to a concrete tool list. The checker is a pure\r\n * function over (scopes, toolName, resource) — the routing tables are closed\r\n * over once at construction time.\r\n *\r\n * Fail-closed semantics:\r\n *   - Null/undefined scopes grant full access (back-compat).\r\n *   - When `scopes.collections` / `scopes.globals` is set, it is a *whitelist*\r\n *     for that resource kind — unlisted resources are denied.\r\n *   - When a tool resolves to a collection or global kind but the corresponding\r\n *     scope map is undefined and `scopes.preset` is undefined, the call is\r\n *     denied (closes the `tools.allow`-only latent fail-open).\r\n *   - Account-level tools are gated by the preset's action list, if a preset\r\n *     is set. Without a preset, a key scoped to specific collections/globals\r\n *     cannot use account-level tools — they'd broaden the surface.\r\n */\r\nexport function buildScopeChecker(tools: RoutableTool[]): ScopeChecker {\r\n  const tables = buildRoutingTables(tools)\r\n  return (scopes, toolName, resource) => assertScopeAllows(scopes, toolName, resource, tables)\r\n}\r\n\r\n/**\r\n * Internal pure checker. Exposed for the per-request wrapper in the registry\r\n * so it can re-use the same `RoutingTables` it built once at startup.\r\n */\r\nexport function assertScopeAllows(\r\n  scopes: KeyScopes | null | undefined,\r\n  toolName: string,\r\n  resource: string | undefined,\r\n  tables: RoutingTables,\r\n): ScopeDecision {\r\n  const resourceKind = tables.toolKind.get(toolName) ?? null\r\n  // Unregistered tool — fail-closed at request time. Adding a tool without a\r\n  // routing field is a TS error at the factory return site, so this branch\r\n  // only fires for typo'd tool names sent by the client.\r\n  if (resourceKind === null) {\r\n    return {\r\n      allowed: false,\r\n      reason: `Tool \"${toolName}\" has no registered scope mapping.`,\r\n    }\r\n  }\r\n\r\n  if (!scopes || (scopes.preset === undefined && !scopes.collections && !scopes.globals && !scopes.tools)) {\r\n    return { allowed: true }\r\n  }\r\n\r\n  if (scopes.tools?.deny?.includes(toolName)) {\r\n    return { allowed: false, reason: `Tool \"${toolName}\" is denied for this API key.` }\r\n  }\r\n  if (scopes.tools?.allow && !scopes.tools.allow.includes(toolName)) {\r\n    return {\r\n      allowed: false,\r\n      reason: `Tool \"${toolName}\" is not in the allow-list for this API key.`,\r\n    }\r\n  }\r\n\r\n  if (scopes.preset && PRESET_TOOL_DENY[scopes.preset]?.includes(toolName)) {\r\n    return {\r\n      allowed: false,\r\n      reason: `Tool \"${toolName}\" is not allowed by the \"${scopes.preset}\" preset.`,\r\n    }\r\n  }\r\n\r\n  if (resourceKind === 'account') {\r\n    return checkAccount(scopes, toolName, tables.accountToolAction)\r\n  }\r\n  const policy = resourceKind === 'collection' ? COLLECTION_POLICY : GLOBAL_POLICY\r\n  const toolAction =\r\n    resourceKind === 'collection' ? tables.collectionToolAction : tables.globalToolAction\r\n  return checkResource(scopes, toolName, resource, toolAction, policy)\r\n}\r\n\r\n/**\r\n * Per-resource-kind policy. Collapses what used to be two near-identical\r\n * `checkCollection` / `checkGlobal` helpers — the only differences are\r\n * the preset-actions table, the label, and which axis of `KeyScopes` to\r\n * read for explicit overrides.\r\n */\r\ninterface ResourcePolicy {\r\n  presetActions: Record<ScopePreset, readonly string[]>\r\n  scopeAxis: 'collections' | 'globals'\r\n  label: 'collection' | 'global'\r\n  Label: 'Collection' | 'Global'\r\n}\r\n\r\nconst COLLECTION_POLICY: ResourcePolicy = {\r\n  presetActions: PRESET_ACTIONS,\r\n  scopeAxis: 'collections',\r\n  label: 'collection',\r\n  Label: 'Collection',\r\n}\r\n\r\nconst GLOBAL_POLICY: ResourcePolicy = {\r\n  presetActions: PRESET_GLOBAL_ACTIONS,\r\n  scopeAxis: 'globals',\r\n  label: 'global',\r\n  Label: 'Global',\r\n}\r\n\r\nfunction checkResource(\r\n  scopes: KeyScopes,\r\n  toolName: string,\r\n  resource: string | undefined,\r\n  toolAction: ReadonlyMap<string, string>,\r\n  policy: ResourcePolicy,\r\n): ScopeDecision {\r\n  const action = toolAction.get(toolName)\r\n  const presetActions = scopes.preset ? policy.presetActions[scopes.preset] : undefined\r\n  const resourceScope = scopes[policy.scopeAxis]\r\n\r\n  if (!resource) {\r\n    // Resource-keyed tool called without a slug; defer to schema validation.\r\n    return { allowed: true }\r\n  }\r\n  if (!action) return { allowed: true }\r\n\r\n  if (resourceScope) {\r\n    const override = resourceScope[resource]\r\n    if (!override) {\r\n      return {\r\n        allowed: false,\r\n        reason: `${policy.Label} \"${resource}\" is not in this API key's allowed ${policy.scopeAxis}.`,\r\n      }\r\n    }\r\n    if (!override.includes(action as never)) {\r\n      return {\r\n        allowed: false,\r\n        reason: `Action \"${action}\" on ${policy.label} \"${resource}\" is not permitted by this API key's scope.`,\r\n      }\r\n    }\r\n    return { allowed: true }\r\n  }\r\n\r\n  if (!presetActions) {\r\n    // Fail-closed: `tools.allow` without a resource map or preset would\r\n    // otherwise broadcast the tool across every resource. Require explicit\r\n    // intent.\r\n    return {\r\n      allowed: false,\r\n      reason: `Tool \"${toolName}\" requires an explicit ${policy.label} scope or preset on this API key.`,\r\n    }\r\n  }\r\n\r\n  if (!presetActions.includes(action)) {\r\n    return {\r\n      allowed: false,\r\n      reason: `Action \"${action}\" on ${policy.label} \"${resource}\" is not permitted by this API key's preset.`,\r\n    }\r\n  }\r\n  return { allowed: true }\r\n}\r\n\r\nfunction checkAccount(\r\n  scopes: KeyScopes,\r\n  toolName: string,\r\n  toolAction: ReadonlyMap<string, CollectionAction>,\r\n): ScopeDecision {\r\n  const action = toolAction.get(toolName)\r\n  const presetActions = scopes.preset ? PRESET_ACTIONS[scopes.preset] : undefined\r\n\r\n  // Explicit resource override is the tightest signal: an account-level tool\r\n  // operates across the whole site (searchContent across every collection,\r\n  // uploadMedia into any media coll, etc.) and would broaden the key beyond\r\n  // the resource whitelist regardless of which preset is set. Deny account\r\n  // tools whenever the key carries explicit collection/global scopes.\r\n  if (scopes.collections || scopes.globals) {\r\n    return {\r\n      allowed: false,\r\n      reason: `Tool \"${toolName}\" is denied for keys with explicit collection or global scopes — account-level tools would broaden access beyond the whitelist.`,\r\n    }\r\n  }\r\n\r\n  if (presetActions) {\r\n    if (action && !presetActions.includes(action)) {\r\n      return {\r\n        allowed: false,\r\n        reason: `Action \"${action}\" is not permitted by this API key's preset.`,\r\n      }\r\n    }\r\n    return { allowed: true }\r\n  }\r\n\r\n  return { allowed: true }\r\n}\r\n"],"names":["ALL_ACTIONS","PRESET_ACTIONS","editor","admin","PRESET_GLOBAL_ACTIONS","PRESET_TOOL_DENY","buildRoutingTables","tools","collectionToolAction","Map","globalToolAction","accountToolAction","toolKind","t","set","name","routing","kind","action","buildScopeChecker","tables","scopes","toolName","resource","assertScopeAllows","resourceKind","get","allowed","reason","preset","undefined","collections","globals","deny","includes","allow","checkAccount","policy","COLLECTION_POLICY","GLOBAL_POLICY","toolAction","checkResource","presetActions","scopeAxis","label","Label","resourceScope","override"],"mappings":"AA6BA,wEAAwE;AAExE,MAAMA,cAAkC;IAAC;IAAQ;IAAU;IAAU;CAAS;AAE9E,OAAO,MAAMC,iBAA0D;IACrE,aAAa;QAAC;KAAO;IACrBC,QAAQ;QAAC;QAAQ;QAAU;KAAS;IACpCC,OAAOH;AACT,EAAC;AAED;;;;;;CAMC,GACD,OAAO,MAAMI,wBAA6D;IACxE,aAAa;QAAC;KAAO;IACrBF,QAAQ;QAAC;KAAO;IAChBC,OAAO;QAAC;QAAQ;KAAS;AAC3B,EAAC;AAED,OAAO,MAAME,mBAAkD;IAC7D,aAAa,EAAE;IACfH,QAAQ;QAAC;QAAc;KAAiB;IACxCC,OAAO,EAAE;AACX,EAAC;AAgBD,OAAO,SAASG,mBAAmBC,KAAqB;IACtD,MAAMC,uBAAuB,IAAIC;IACjC,MAAMC,mBAAmB,IAAID;IAC7B,MAAME,oBAAoB,IAAIF;IAC9B,MAAMG,WAAW,IAAIH;IACrB,KAAK,MAAMI,KAAKN,MAAO;QACrBK,SAASE,GAAG,CAACD,EAAEE,IAAI,EAAEF,EAAEG,OAAO,CAACC,IAAI;QACnC,IAAIJ,EAAEG,OAAO,CAACC,IAAI,KAAK,cAAcT,qBAAqBM,GAAG,CAACD,EAAEE,IAAI,EAAEF,EAAEG,OAAO,CAACE,MAAM;aACjF,IAAIL,EAAEG,OAAO,CAACC,IAAI,KAAK,UAAUP,iBAAiBI,GAAG,CAACD,EAAEE,IAAI,EAAEF,EAAEG,OAAO,CAACE,MAAM;aAC9EP,kBAAkBG,GAAG,CAACD,EAAEE,IAAI,EAAEF,EAAEG,OAAO,CAACE,MAAM;IACrD;IACA,OAAO;QAAEV;QAAsBE;QAAkBC;QAAmBC;IAAS;AAC/E;AAUA;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASO,kBAAkBZ,KAAqB;IACrD,MAAMa,SAASd,mBAAmBC;IAClC,OAAO,CAACc,QAAQC,UAAUC,WAAaC,kBAAkBH,QAAQC,UAAUC,UAAUH;AACvF;AAEA;;;CAGC,GACD,OAAO,SAASI,kBACdH,MAAoC,EACpCC,QAAgB,EAChBC,QAA4B,EAC5BH,MAAqB;IAErB,MAAMK,eAAeL,OAAOR,QAAQ,CAACc,GAAG,CAACJ,aAAa;IACtD,2EAA2E;IAC3E,yEAAyE;IACzE,uDAAuD;IACvD,IAAIG,iBAAiB,MAAM;QACzB,OAAO;YACLE,SAAS;YACTC,QAAQ,CAAC,MAAM,EAAEN,SAAS,kCAAkC,CAAC;QAC/D;IACF;IAEA,IAAI,CAACD,UAAWA,OAAOQ,MAAM,KAAKC,aAAa,CAACT,OAAOU,WAAW,IAAI,CAACV,OAAOW,OAAO,IAAI,CAACX,OAAOd,KAAK,EAAG;QACvG,OAAO;YAAEoB,SAAS;QAAK;IACzB;IAEA,IAAIN,OAAOd,KAAK,EAAE0B,MAAMC,SAASZ,WAAW;QAC1C,OAAO;YAAEK,SAAS;YAAOC,QAAQ,CAAC,MAAM,EAAEN,SAAS,6BAA6B,CAAC;QAAC;IACpF;IACA,IAAID,OAAOd,KAAK,EAAE4B,SAAS,CAACd,OAAOd,KAAK,CAAC4B,KAAK,CAACD,QAAQ,CAACZ,WAAW;QACjE,OAAO;YACLK,SAAS;YACTC,QAAQ,CAAC,MAAM,EAAEN,SAAS,4CAA4C,CAAC;QACzE;IACF;IAEA,IAAID,OAAOQ,MAAM,IAAIxB,gBAAgB,CAACgB,OAAOQ,MAAM,CAAC,EAAEK,SAASZ,WAAW;QACxE,OAAO;YACLK,SAAS;YACTC,QAAQ,CAAC,MAAM,EAAEN,SAAS,yBAAyB,EAAED,OAAOQ,MAAM,CAAC,SAAS,CAAC;QAC/E;IACF;IAEA,IAAIJ,iBAAiB,WAAW;QAC9B,OAAOW,aAAaf,QAAQC,UAAUF,OAAOT,iBAAiB;IAChE;IACA,MAAM0B,SAASZ,iBAAiB,eAAea,oBAAoBC;IACnE,MAAMC,aACJf,iBAAiB,eAAeL,OAAOZ,oBAAoB,GAAGY,OAAOV,gBAAgB;IACvF,OAAO+B,cAAcpB,QAAQC,UAAUC,UAAUiB,YAAYH;AAC/D;AAeA,MAAMC,oBAAoC;IACxCI,eAAezC;IACf0C,WAAW;IACXC,OAAO;IACPC,OAAO;AACT;AAEA,MAAMN,gBAAgC;IACpCG,eAAetC;IACfuC,WAAW;IACXC,OAAO;IACPC,OAAO;AACT;AAEA,SAASJ,cACPpB,MAAiB,EACjBC,QAAgB,EAChBC,QAA4B,EAC5BiB,UAAuC,EACvCH,MAAsB;IAEtB,MAAMnB,SAASsB,WAAWd,GAAG,CAACJ;IAC9B,MAAMoB,gBAAgBrB,OAAOQ,MAAM,GAAGQ,OAAOK,aAAa,CAACrB,OAAOQ,MAAM,CAAC,GAAGC;IAC5E,MAAMgB,gBAAgBzB,MAAM,CAACgB,OAAOM,SAAS,CAAC;IAE9C,IAAI,CAACpB,UAAU;QACb,yEAAyE;QACzE,OAAO;YAAEI,SAAS;QAAK;IACzB;IACA,IAAI,CAACT,QAAQ,OAAO;QAAES,SAAS;IAAK;IAEpC,IAAImB,eAAe;QACjB,MAAMC,WAAWD,aAAa,CAACvB,SAAS;QACxC,IAAI,CAACwB,UAAU;YACb,OAAO;gBACLpB,SAAS;gBACTC,QAAQ,GAAGS,OAAOQ,KAAK,CAAC,EAAE,EAAEtB,SAAS,mCAAmC,EAAEc,OAAOM,SAAS,CAAC,CAAC,CAAC;YAC/F;QACF;QACA,IAAI,CAACI,SAASb,QAAQ,CAAChB,SAAkB;YACvC,OAAO;gBACLS,SAAS;gBACTC,QAAQ,CAAC,QAAQ,EAAEV,OAAO,KAAK,EAAEmB,OAAOO,KAAK,CAAC,EAAE,EAAErB,SAAS,2CAA2C,CAAC;YACzG;QACF;QACA,OAAO;YAAEI,SAAS;QAAK;IACzB;IAEA,IAAI,CAACe,eAAe;QAClB,oEAAoE;QACpE,uEAAuE;QACvE,UAAU;QACV,OAAO;YACLf,SAAS;YACTC,QAAQ,CAAC,MAAM,EAAEN,SAAS,uBAAuB,EAAEe,OAAOO,KAAK,CAAC,iCAAiC,CAAC;QACpG;IACF;IAEA,IAAI,CAACF,cAAcR,QAAQ,CAAChB,SAAS;QACnC,OAAO;YACLS,SAAS;YACTC,QAAQ,CAAC,QAAQ,EAAEV,OAAO,KAAK,EAAEmB,OAAOO,KAAK,CAAC,EAAE,EAAErB,SAAS,4CAA4C,CAAC;QAC1G;IACF;IACA,OAAO;QAAEI,SAAS;IAAK;AACzB;AAEA,SAASS,aACPf,MAAiB,EACjBC,QAAgB,EAChBkB,UAAiD;IAEjD,MAAMtB,SAASsB,WAAWd,GAAG,CAACJ;IAC9B,MAAMoB,gBAAgBrB,OAAOQ,MAAM,GAAG5B,cAAc,CAACoB,OAAOQ,MAAM,CAAC,GAAGC;IAEtE,2EAA2E;IAC3E,yEAAyE;IACzE,0EAA0E;IAC1E,yEAAyE;IACzE,oEAAoE;IACpE,IAAIT,OAAOU,WAAW,IAAIV,OAAOW,OAAO,EAAE;QACxC,OAAO;YACLL,SAAS;YACTC,QAAQ,CAAC,MAAM,EAAEN,SAAS,+HAA+H,CAAC;QAC5J;IACF;IAEA,IAAIoB,eAAe;QACjB,IAAIxB,UAAU,CAACwB,cAAcR,QAAQ,CAAChB,SAAS;YAC7C,OAAO;gBACLS,SAAS;gBACTC,QAAQ,CAAC,QAAQ,EAAEV,OAAO,4CAA4C,CAAC;YACzE;QACF;QACA,OAAO;YAAES,SAAS;QAAK;IACzB;IAEA,OAAO;QAAEA,SAAS;IAAK;AACzB"}

package/dist/tools/_helpers.d.ts

@@ -1,4 +1,15 @@
-import type { PayloadRequest } from 'payload';
+import { z } from 'zod';
+import type { CollectionConfig, PayloadRequest } from 'payload';
+/**
+ * Build a `z.enum` over a list of valid resource slugs with a friendly
+ * error message that names the valid set and clarifies why an unknown
+ * slug (e.g. one removed via `options.exclude.globals`) is rejected.
+ *
+ * Default Zod enum errors are "Invalid enum value. …" — accurate but
+ * unhelpful when the slug looks plausible to a caller who isn't aware
+ * the host config excluded it.
+ */
+export declare function slugEnum(slugs: string[], kind: 'global' | 'collection'): z.ZodEnum<[string, ...string[]]>;
 export interface McpTextResponse {
     content: Array<{
         type: 'text';
@@ -9,6 +20,56 @@ export declare const DRAFT_NOTE = " Document is in draft status \u2014 use publi
 export declare function textResponse(text: string): McpTextResponse;
 export declare function jsonResponse(payload: unknown): McpTextResponse;
 export declare function errorMessage(error: unknown): string;
+export type PublishVerifyTarget = {
+    kind: 'collection';
+    slug: string;
+    id: string;
+} | {
+    kind: 'global';
+    slug: string;
+    locale?: string;
+};
+/**
+ * Capture the document's current `updatedAt` BEFORE a publish attempt so
+ * the recovery branch can tell "this attempt landed despite a post-write
+ * validator throw" from "an older publish was successful and this attempt
+ * did nothing". A missing snapshot is non-fatal — the recovery branch
+ * conservatively falls through to the original error in that case.
+ */
+export declare function snapshotPublishMarker(req: PayloadRequest, target: PublishVerifyTarget): Promise<string | undefined>;
+/**
+ * After a Payload update throws on a publish call, determine whether the
+ * publish actually landed despite the error. Returns the live document
+ * only when (a) the live `_status` is 'published' AND (b) `updatedAt`
+ * strictly advanced past the pre-update snapshot — i.e. the current
+ * attempt produced the published row. Without the strictly-newer check,
+ * a pre-existing published version from an earlier successful publish
+ * would mask a real failure of the current attempt.
+ *
+ * Returns null on:
+ *   - missing pre-snapshot (cannot disambiguate; conservative)
+ *   - verify read failure (do not mask the original error with a
+ *     secondary read error)
+ *   - live `_status` not 'published'
+ *   - live `updatedAt` not strictly newer than the pre-snapshot
+ */
+export declare function verifyPublishSucceededDespiteError(req: PayloadRequest, target: PublishVerifyTarget, preUpdatedAt: string | undefined): Promise<Record<string, unknown> | null>;
 export declare function stampMcpContext(req: PayloadRequest): void;
 export declare function getDocDisplayName(doc: unknown, fallback: string): string;
 export declare function requireDraftCollection(collection: string, draftCollections: Set<string>, noun?: string): McpTextResponse | null;
+/**
+ * Resolves the preview URL for a draft document by delegating to the
+ * collection's own configured preview function (`admin.livePreview.url`
+ * preferred, then `admin.preview`). Returns null when no function is
+ * configured, when it fails, or when it returns a relative path with no
+ * absolute `siteUrl` to anchor it.
+ */
+export declare function resolvePreviewUrl(collection: CollectionConfig, doc: Record<string, unknown>, req: PayloadRequest, siteUrl: string | undefined): Promise<string | null>;
+/**
+ * If `doc` is a draft, appends a preview-URL hint to the MCP response so the
+ * AI can present it to the user. Falls back to a generic admin-panel hint
+ * when the collection has no preview function configured.
+ *
+ * Pure with respect to the response: a fresh content array is returned.
+ */
+export declare function decorateDraftResponse(response: McpTextResponse, doc: Record<string, unknown> | null | undefined, collection: CollectionConfig | undefined, req: PayloadRequest, siteUrl: string | undefined): Promise<McpTextResponse>;

package/dist/tools/_helpers.js

@@ -1,3 +1,19 @@
+import { z } from 'zod';
+/**
+ * Build a `z.enum` over a list of valid resource slugs with a friendly
+ * error message that names the valid set and clarifies why an unknown
+ * slug (e.g. one removed via `options.exclude.globals`) is rejected.
+ *
+ * Default Zod enum errors are "Invalid enum value. …" — accurate but
+ * unhelpful when the slug looks plausible to a caller who isn't aware
+ * the host config excluded it.
+ */ export function slugEnum(slugs, kind) {
+    return z.enum(slugs, {
+        errorMap: ()=>({
+                message: `${kind === 'global' ? 'Global' : 'Collection'} slug must be one of: ${slugs.join(', ')}. Unknown or excluded slugs are rejected.`
+            })
+    });
+}
 export const DRAFT_NOTE = ' Document is in draft status — use publishDraft to make it live.';
 export function textResponse(text) {
     return {
@@ -15,6 +31,104 @@ export function jsonResponse(payload) {
 export function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function asIsoString(v) {
+    if (typeof v === 'string') return v;
+    if (v instanceof Date) return v.toISOString();
+    return undefined;
+}
+/**
+ * Capture the document's current `updatedAt` BEFORE a publish attempt so
+ * the recovery branch can tell "this attempt landed despite a post-write
+ * validator throw" from "an older publish was successful and this attempt
+ * did nothing". A missing snapshot is non-fatal — the recovery branch
+ * conservatively falls through to the original error in that case.
+ */ export async function snapshotPublishMarker(req, target) {
+    try {
+        const pre = target.kind === 'collection' ? await req.payload.findByID({
+            collection: target.slug,
+            id: target.id,
+            draft: true,
+            depth: 0,
+            req,
+            overrideAccess: false,
+            user: req.user
+        }) : await req.payload.findGlobal({
+            slug: target.slug,
+            draft: true,
+            depth: 0,
+            // `fallbackLocale: false` disables Payload's locale-fallback so
+            // the read returns the literal state of the requested locale.
+            // Without this, a localized global with fallbackLocale='en'
+            // could report the 'en' updatedAt while the caller is
+            // publishing 'de', producing a false-positive in
+            // verifyPublishSucceededDespiteError.
+            ...target.locale ? {
+                locale: target.locale,
+                fallbackLocale: false
+            } : {},
+            req,
+            overrideAccess: false,
+            user: req.user
+        });
+        return asIsoString(pre?.updatedAt);
+    } catch  {
+        return undefined;
+    }
+}
+/**
+ * After a Payload update throws on a publish call, determine whether the
+ * publish actually landed despite the error. Returns the live document
+ * only when (a) the live `_status` is 'published' AND (b) `updatedAt`
+ * strictly advanced past the pre-update snapshot — i.e. the current
+ * attempt produced the published row. Without the strictly-newer check,
+ * a pre-existing published version from an earlier successful publish
+ * would mask a real failure of the current attempt.
+ *
+ * Returns null on:
+ *   - missing pre-snapshot (cannot disambiguate; conservative)
+ *   - verify read failure (do not mask the original error with a
+ *     secondary read error)
+ *   - live `_status` not 'published'
+ *   - live `updatedAt` not strictly newer than the pre-snapshot
+ */ export async function verifyPublishSucceededDespiteError(req, target, preUpdatedAt) {
+    if (!preUpdatedAt) return null;
+    try {
+        const live = target.kind === 'collection' ? await req.payload.findByID({
+            collection: target.slug,
+            id: target.id,
+            draft: false,
+            depth: 0,
+            req,
+            overrideAccess: false,
+            user: req.user
+        }) : await req.payload.findGlobal({
+            slug: target.slug,
+            draft: false,
+            depth: 0,
+            // Disable Payload locale-fallback (see snapshotPublishMarker
+            // note) so verify reads the literal state of the locale that
+            // updateGlobal was called against.
+            ...target.locale ? {
+                locale: target.locale,
+                fallbackLocale: false
+            } : {},
+            req,
+            overrideAccess: false,
+            user: req.user
+        });
+        const d = live;
+        if (!d || d._status !== 'published') return null;
+        const liveUpdatedAt = asIsoString(d.updatedAt);
+        if (!liveUpdatedAt || liveUpdatedAt <= preUpdatedAt) return null;
+        return d;
+    } catch (verifyError) {
+        req.payload.logger?.debug?.({
+            event: 'mcp.publish.verify_read_failed',
+            err: verifyError
+        }, '[payload-mcp-toolkit] publish-recovery verify-read failed; surfacing original error');
+        return null;
+    }
+}
 export function stampMcpContext(req) {
     req.context = {
         ...req.context,
@@ -31,5 +145,72 @@ export function requireDraftCollection(collection, draftCollections, noun = 'dra
         ...draftCollections
     ].join(', ') || 'none'}`);
 }
+/**
+ * Resolves the preview URL for a draft document by delegating to the
+ * collection's own configured preview function (`admin.livePreview.url`
+ * preferred, then `admin.preview`). Returns null when no function is
+ * configured, when it fails, or when it returns a relative path with no
+ * absolute `siteUrl` to anchor it.
+ */ export async function resolvePreviewUrl(collection, doc, req, siteUrl) {
+    const admin = collection.admin ?? {};
+    const locale = req.locale ?? 'en';
+    let raw;
+    const livePreviewUrl = admin.livePreview?.url;
+    if (typeof livePreviewUrl === 'function') {
+        try {
+            raw = await livePreviewUrl({
+                data: doc,
+                locale: {
+                    code: locale,
+                    label: locale
+                },
+                req,
+                payload: req.payload,
+                collectionConfig: collection
+            });
+        } catch  {
+            raw = null;
+        }
+    } else if (typeof livePreviewUrl === 'string') {
+        raw = livePreviewUrl;
+    }
+    if (!raw && typeof admin.preview === 'function') {
+        try {
+            raw = await admin.preview(doc, {
+                locale,
+                req,
+                token: null
+            });
+        } catch  {
+            raw = null;
+        }
+    }
+    if (!raw || typeof raw !== 'string') return null;
+    if (raw.startsWith('http://') || raw.startsWith('https://')) return raw;
+    if (!siteUrl) return null;
+    const base = siteUrl.endsWith('/') ? siteUrl.slice(0, -1) : siteUrl;
+    const path = raw.startsWith('/') ? raw : `/${raw}`;
+    return `${base}${path}`;
+}
+/**
+ * If `doc` is a draft, appends a preview-URL hint to the MCP response so the
+ * AI can present it to the user. Falls back to a generic admin-panel hint
+ * when the collection has no preview function configured.
+ *
+ * Pure with respect to the response: a fresh content array is returned.
+ */ export async function decorateDraftResponse(response, doc, collection, req, siteUrl) {
+    if (!doc || doc._status !== 'draft' || !collection) return response;
+    const previewUrl = await resolvePreviewUrl(collection, doc, req, siteUrl);
+    const hint = previewUrl ? `\n📋 This document is a draft. Preview it here: ${previewUrl}` : '\n📋 This document is a draft. Use the admin panel to preview it.';
+    return {
+        content: [
+            ...response.content,
+            {
+                type: 'text',
+                text: hint
+            }
+        ]
+    };
+}
 
 //# sourceMappingURL=_helpers.js.map

package/dist/tools/_helpers.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/tools/_helpers.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\n\nexport interface McpTextResponse {\n  content: Array<{ type: 'text'; text: string }>\n}\n\nexport const DRAFT_NOTE = ' Document is in draft status — use publishDraft to make it live.'\n\nexport function textResponse(text: string): McpTextResponse {\n  return { content: [{ type: 'text', text }] }\n}\n\nexport function jsonResponse(payload: unknown): McpTextResponse {\n  return textResponse(JSON.stringify(payload))\n}\n\nexport function errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error)\n}\n\nexport function stampMcpContext(req: PayloadRequest): void {\n  req.context = { ...req.context, source: 'mcp' }\n}\n\nexport function getDocDisplayName(doc: unknown, fallback: string): string {\n  const d = doc as Record<string, unknown> | null | undefined\n  return (\n    (typeof d?.name === 'string' && d.name) ||\n    (typeof d?.title === 'string' && d.title) ||\n    (typeof d?.slug === 'string' && d.slug) ||\n    fallback\n  )\n}\n\nexport function requireDraftCollection(\n  collection: string,\n  draftCollections: Set<string>,\n  noun = 'drafts',\n): McpTextResponse | null {\n  if (draftCollections.has(collection)) return null\n  return textResponse(\n    `Error: Collection \"${collection}\" does not support ${noun}. ` +\n      `Draft-enabled collections: ${[...draftCollections].join(', ') || 'none'}`,\n  )\n}\n"],"names":["DRAFT_NOTE","textResponse","text","content","type","jsonResponse","payload","JSON","stringify","errorMessage","error","Error","message","String","stampMcpContext","req","context","source","getDocDisplayName","doc","fallback","d","name","title","slug","requireDraftCollection","collection","draftCollections","noun","has","join"],"mappings":"AAMA,OAAO,MAAMA,aAAa,mEAAkE;AAE5F,OAAO,SAASC,aAAaC,IAAY;IACvC,OAAO;QAAEC,SAAS;YAAC;gBAAEC,MAAM;gBAAQF;YAAK;SAAE;IAAC;AAC7C;AAEA,OAAO,SAASG,aAAaC,OAAgB;IAC3C,OAAOL,aAAaM,KAAKC,SAAS,CAACF;AACrC;AAEA,OAAO,SAASG,aAAaC,KAAc;IACzC,OAAOA,iBAAiBC,QAAQD,MAAME,OAAO,GAAGC,OAAOH;AACzD;AAEA,OAAO,SAASI,gBAAgBC,GAAmB;IACjDA,IAAIC,OAAO,GAAG;QAAE,GAAGD,IAAIC,OAAO;QAAEC,QAAQ;IAAM;AAChD;AAEA,OAAO,SAASC,kBAAkBC,GAAY,EAAEC,QAAgB;IAC9D,MAAMC,IAAIF;IACV,OACE,AAAC,OAAOE,GAAGC,SAAS,YAAYD,EAAEC,IAAI,IACrC,OAAOD,GAAGE,UAAU,YAAYF,EAAEE,KAAK,IACvC,OAAOF,GAAGG,SAAS,YAAYH,EAAEG,IAAI,IACtCJ;AAEJ;AAEA,OAAO,SAASK,uBACdC,UAAkB,EAClBC,gBAA6B,EAC7BC,OAAO,QAAQ;IAEf,IAAID,iBAAiBE,GAAG,CAACH,aAAa,OAAO;IAC7C,OAAOzB,aACL,CAAC,mBAAmB,EAAEyB,WAAW,mBAAmB,EAAEE,KAAK,EAAE,CAAC,GAC5D,CAAC,2BAA2B,EAAE;WAAID;KAAiB,CAACG,IAAI,CAAC,SAAS,QAAQ;AAEhF"}
+{"version":3,"sources":["../../src/tools/_helpers.ts"],"sourcesContent":["import { z } from 'zod'\r\nimport type { CollectionConfig, PayloadRequest } from 'payload'\r\n\r\n/**\r\n * Build a `z.enum` over a list of valid resource slugs with a friendly\r\n * error message that names the valid set and clarifies why an unknown\r\n * slug (e.g. one removed via `options.exclude.globals`) is rejected.\r\n *\r\n * Default Zod enum errors are \"Invalid enum value. …\" — accurate but\r\n * unhelpful when the slug looks plausible to a caller who isn't aware\r\n * the host config excluded it.\r\n */\r\nexport function slugEnum(\r\n  slugs: string[],\r\n  kind: 'global' | 'collection',\r\n): z.ZodEnum<[string, ...string[]]> {\r\n  return z.enum(slugs as [string, ...string[]], {\r\n    errorMap: () => ({\r\n      message: `${kind === 'global' ? 'Global' : 'Collection'} slug must be one of: ${slugs.join(', ')}. Unknown or excluded slugs are rejected.`,\r\n    }),\r\n  })\r\n}\r\n\r\nexport interface McpTextResponse {\r\n  content: Array<{ type: 'text'; text: string }>\r\n}\r\n\r\nexport const DRAFT_NOTE = ' Document is in draft status — use publishDraft to make it live.'\r\n\r\nexport function textResponse(text: string): McpTextResponse {\r\n  return { content: [{ type: 'text', text }] }\r\n}\r\n\r\nexport function jsonResponse(payload: unknown): McpTextResponse {\r\n  return textResponse(JSON.stringify(payload))\r\n}\r\n\r\nexport function errorMessage(error: unknown): string {\r\n  return error instanceof Error ? error.message : String(error)\r\n}\r\n\r\nfunction asIsoString(v: unknown): string | undefined {\r\n  if (typeof v === 'string') return v\r\n  if (v instanceof Date) return v.toISOString()\r\n  return undefined\r\n}\r\n\r\nexport type PublishVerifyTarget =\r\n  | { kind: 'collection'; slug: string; id: string }\r\n  | { kind: 'global'; slug: string; locale?: string }\r\n\r\n/**\r\n * Capture the document's current `updatedAt` BEFORE a publish attempt so\r\n * the recovery branch can tell \"this attempt landed despite a post-write\r\n * validator throw\" from \"an older publish was successful and this attempt\r\n * did nothing\". A missing snapshot is non-fatal — the recovery branch\r\n * conservatively falls through to the original error in that case.\r\n */\r\nexport async function snapshotPublishMarker(\r\n  req: PayloadRequest,\r\n  target: PublishVerifyTarget,\r\n): Promise<string | undefined> {\r\n  try {\r\n    const pre =\r\n      target.kind === 'collection'\r\n        ? await req.payload.findByID({\r\n            collection: target.slug as any,\r\n            id: target.id,\r\n            draft: true,\r\n            depth: 0,\r\n            req,\r\n            overrideAccess: false,\r\n            user: req.user,\r\n          })\r\n        : await req.payload.findGlobal({\r\n            slug: target.slug as never,\r\n            draft: true,\r\n            depth: 0,\r\n            // `fallbackLocale: false` disables Payload's locale-fallback so\r\n            // the read returns the literal state of the requested locale.\r\n            // Without this, a localized global with fallbackLocale='en'\r\n            // could report the 'en' updatedAt while the caller is\r\n            // publishing 'de', producing a false-positive in\r\n            // verifyPublishSucceededDespiteError.\r\n            ...(target.locale\r\n              ? { locale: target.locale as never, fallbackLocale: false as never }\r\n              : {}),\r\n            req,\r\n            overrideAccess: false,\r\n            user: req.user,\r\n          })\r\n    return asIsoString((pre as { updatedAt?: unknown } | null | undefined)?.updatedAt)\r\n  } catch {\r\n    return undefined\r\n  }\r\n}\r\n\r\n/**\r\n * After a Payload update throws on a publish call, determine whether the\r\n * publish actually landed despite the error. Returns the live document\r\n * only when (a) the live `_status` is 'published' AND (b) `updatedAt`\r\n * strictly advanced past the pre-update snapshot — i.e. the current\r\n * attempt produced the published row. Without the strictly-newer check,\r\n * a pre-existing published version from an earlier successful publish\r\n * would mask a real failure of the current attempt.\r\n *\r\n * Returns null on:\r\n *   - missing pre-snapshot (cannot disambiguate; conservative)\r\n *   - verify read failure (do not mask the original error with a\r\n *     secondary read error)\r\n *   - live `_status` not 'published'\r\n *   - live `updatedAt` not strictly newer than the pre-snapshot\r\n */\r\nexport async function verifyPublishSucceededDespiteError(\r\n  req: PayloadRequest,\r\n  target: PublishVerifyTarget,\r\n  preUpdatedAt: string | undefined,\r\n): Promise<Record<string, unknown> | null> {\r\n  if (!preUpdatedAt) return null\r\n  try {\r\n    const live =\r\n      target.kind === 'collection'\r\n        ? await req.payload.findByID({\r\n            collection: target.slug as any,\r\n            id: target.id,\r\n            draft: false,\r\n            depth: 0,\r\n            req,\r\n            overrideAccess: false,\r\n            user: req.user,\r\n          })\r\n        : await req.payload.findGlobal({\r\n            slug: target.slug as never,\r\n            draft: false,\r\n            depth: 0,\r\n            // Disable Payload locale-fallback (see snapshotPublishMarker\r\n            // note) so verify reads the literal state of the locale that\r\n            // updateGlobal was called against.\r\n            ...(target.locale\r\n              ? { locale: target.locale as never, fallbackLocale: false as never }\r\n              : {}),\r\n            req,\r\n            overrideAccess: false,\r\n            user: req.user,\r\n          })\r\n    const d = live as Record<string, unknown> | null | undefined\r\n    if (!d || d._status !== 'published') return null\r\n    const liveUpdatedAt = asIsoString(d.updatedAt)\r\n    if (!liveUpdatedAt || liveUpdatedAt <= preUpdatedAt) return null\r\n    return d\r\n  } catch (verifyError) {\r\n    req.payload.logger?.debug?.(\r\n      { event: 'mcp.publish.verify_read_failed', err: verifyError },\r\n      '[payload-mcp-toolkit] publish-recovery verify-read failed; surfacing original error',\r\n    )\r\n    return null\r\n  }\r\n}\r\n\r\nexport function stampMcpContext(req: PayloadRequest): void {\r\n  req.context = { ...req.context, source: 'mcp' }\r\n}\r\n\r\nexport function getDocDisplayName(doc: unknown, fallback: string): string {\r\n  const d = doc as Record<string, unknown> | null | undefined\r\n  return (\r\n    (typeof d?.name === 'string' && d.name) ||\r\n    (typeof d?.title === 'string' && d.title) ||\r\n    (typeof d?.slug === 'string' && d.slug) ||\r\n    fallback\r\n  )\r\n}\r\n\r\nexport function requireDraftCollection(\r\n  collection: string,\r\n  draftCollections: Set<string>,\r\n  noun = 'drafts',\r\n): McpTextResponse | null {\r\n  if (draftCollections.has(collection)) return null\r\n  return textResponse(\r\n    `Error: Collection \"${collection}\" does not support ${noun}. ` +\r\n      `Draft-enabled collections: ${[...draftCollections].join(', ') || 'none'}`,\r\n  )\r\n}\r\n\r\n/**\r\n * Resolves the preview URL for a draft document by delegating to the\r\n * collection's own configured preview function (`admin.livePreview.url`\r\n * preferred, then `admin.preview`). Returns null when no function is\r\n * configured, when it fails, or when it returns a relative path with no\r\n * absolute `siteUrl` to anchor it.\r\n */\r\nexport async function resolvePreviewUrl(\r\n  collection: CollectionConfig,\r\n  doc: Record<string, unknown>,\r\n  req: PayloadRequest,\r\n  siteUrl: string | undefined,\r\n): Promise<string | null> {\r\n  const admin = (collection.admin ?? {}) as Record<string, any>\r\n  const locale = (req as unknown as { locale?: string }).locale ?? 'en'\r\n\r\n  let raw: string | null | undefined\r\n\r\n  const livePreviewUrl = admin.livePreview?.url\r\n  if (typeof livePreviewUrl === 'function') {\r\n    try {\r\n      raw = await livePreviewUrl({\r\n        data: doc,\r\n        locale: { code: locale, label: locale },\r\n        req,\r\n        payload: req.payload,\r\n        collectionConfig: collection,\r\n      })\r\n    } catch {\r\n      raw = null\r\n    }\r\n  } else if (typeof livePreviewUrl === 'string') {\r\n    raw = livePreviewUrl\r\n  }\r\n\r\n  if (!raw && typeof admin.preview === 'function') {\r\n    try {\r\n      raw = await admin.preview(doc, { locale, req, token: null })\r\n    } catch {\r\n      raw = null\r\n    }\r\n  }\r\n\r\n  if (!raw || typeof raw !== 'string') return null\r\n\r\n  if (raw.startsWith('http://') || raw.startsWith('https://')) return raw\r\n  if (!siteUrl) return null\r\n\r\n  const base = siteUrl.endsWith('/') ? siteUrl.slice(0, -1) : siteUrl\r\n  const path = raw.startsWith('/') ? raw : `/${raw}`\r\n  return `${base}${path}`\r\n}\r\n\r\n/**\r\n * If `doc` is a draft, appends a preview-URL hint to the MCP response so the\r\n * AI can present it to the user. Falls back to a generic admin-panel hint\r\n * when the collection has no preview function configured.\r\n *\r\n * Pure with respect to the response: a fresh content array is returned.\r\n */\r\nexport async function decorateDraftResponse(\r\n  response: McpTextResponse,\r\n  doc: Record<string, unknown> | null | undefined,\r\n  collection: CollectionConfig | undefined,\r\n  req: PayloadRequest,\r\n  siteUrl: string | undefined,\r\n): Promise<McpTextResponse> {\r\n  if (!doc || doc._status !== 'draft' || !collection) return response\r\n\r\n  const previewUrl = await resolvePreviewUrl(collection, doc, req, siteUrl)\r\n  const hint = previewUrl\r\n    ? `\\n📋 This document is a draft. Preview it here: ${previewUrl}`\r\n    : '\\n📋 This document is a draft. Use the admin panel to preview it.'\r\n\r\n  return { content: [...response.content, { type: 'text', text: hint }] }\r\n}\r\n"],"names":["z","slugEnum","slugs","kind","enum","errorMap","message","join","DRAFT_NOTE","textResponse","text","content","type","jsonResponse","payload","JSON","stringify","errorMessage","error","Error","String","asIsoString","v","Date","toISOString","undefined","snapshotPublishMarker","req","target","pre","findByID","collection","slug","id","draft","depth","overrideAccess","user","findGlobal","locale","fallbackLocale","updatedAt","verifyPublishSucceededDespiteError","preUpdatedAt","live","d","_status","liveUpdatedAt","verifyError","logger","debug","event","err","stampMcpContext","context","source","getDocDisplayName","doc","fallback","name","title","requireDraftCollection","draftCollections","noun","has","resolvePreviewUrl","siteUrl","admin","raw","livePreviewUrl","livePreview","url","data","code","label","collectionConfig","preview","token","startsWith","base","endsWith","slice","path","decorateDraftResponse","response","previewUrl","hint"],"mappings":"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"}