@simmalugnt-se/payload-editor-assistant 0.1.0

package/dist/components/assistant-api.js

@@ -0,0 +1,34 @@
+import { CSRF_HEADER, ENDPOINT_PREFIX } from "../package-name.js";
+export async function assistantRequest(apiBase, path, body, signal) {
+    const csrfResponse = await fetch(`${apiBase}${ENDPOINT_PREFIX}/csrf`, {
+        credentials: "include",
+        signal,
+    });
+    if (!csrfResponse.ok) {
+        return { ok: false, error: "unauthorized", status: csrfResponse.status };
+    }
+    const csrf = (await csrfResponse.json());
+    if (!csrf.token) {
+        return { ok: false, error: "unauthorized", status: 401 };
+    }
+    const response = await fetch(`${apiBase}${ENDPOINT_PREFIX}${path}`, {
+        method: "POST",
+        credentials: "include",
+        signal,
+        headers: {
+            "Content-Type": "application/json",
+            [CSRF_HEADER]: csrf.token,
+        },
+        body: JSON.stringify(body),
+    });
+    const payload = (await response.json().catch(() => ({})));
+    if (!response.ok) {
+        return {
+            ok: false,
+            error: payload.error ?? "provider_error",
+            message: payload.message,
+            status: response.status,
+        };
+    }
+    return { ok: true, data: payload };
+}

package/dist/components/assistant-context.d.ts

@@ -0,0 +1,66 @@
+import { type ReactNode } from "react";
+import type { AssistantShortcut } from "../types.ts";
+export type AssistantChromeStatus = "idle" | "unavailable" | "unauthorized" | "rate_limited" | "timeout" | "provider_error" | "tool_denied" | "stale_context" | "aborted" | "streaming";
+export type DocumentBridgeSnapshot = {
+    collectionSlug?: string;
+    globalSlug?: string;
+    documentId?: string | number;
+    locale: string;
+    title?: string;
+    modified: boolean;
+    locked?: boolean;
+    hasSavePermission?: boolean;
+    uploadStatus?: string;
+    disabled?: boolean;
+};
+export type FormAdapter = {
+    getData: () => Record<string, unknown>;
+    reset: (data: Record<string, unknown>) => Promise<void> | void;
+    setModified: (modified: boolean) => void;
+};
+export type PendingApproval = {
+    title: string;
+    summary: string;
+    approvalId: string;
+    nonce: string;
+    capability: "form.propose" | "draft.create";
+};
+export type AssistantMessage = {
+    id: string;
+    role: "user" | "assistant" | "system";
+    text: string;
+    candidates?: Array<{
+        href: string;
+        label: string;
+    }>;
+};
+type AssistantContextValue = {
+    open: boolean;
+    collapsed: boolean;
+    status: AssistantChromeStatus;
+    messages: AssistantMessage[];
+    shortcuts: AssistantShortcut[];
+    /** Allowlisted collection slugs. */
+    collections: string[];
+    bridge: DocumentBridgeSnapshot | null;
+    formAdapter: FormAdapter | null;
+    pendingApproval: PendingApproval | null;
+    setOpen: (open: boolean) => void;
+    setCollapsed: (collapsed: boolean) => void;
+    setBridge: (bridge: DocumentBridgeSnapshot | null) => void;
+    setFormAdapter: (adapter: FormAdapter | null) => void;
+    setPendingApproval: (pending: PendingApproval | null) => void;
+    setStatus: (status: AssistantChromeStatus) => void;
+    setMessages: (updater: (current: AssistantMessage[]) => AssistantMessage[]) => void;
+    resetConversation: () => void;
+    stop: () => void;
+    abortController: AbortController | null;
+    setAbortController: (controller: AbortController | null) => void;
+};
+export declare function AssistantStateProvider({ children, shortcuts, collections, }: {
+    children: ReactNode;
+    shortcuts: AssistantShortcut[];
+    collections: string[];
+}): import("react").JSX.Element;
+export declare function useAssistantState(): AssistantContextValue;
+export {};

package/dist/components/assistant-context.js

@@ -0,0 +1,69 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useMemo, useState } from "react";
+const AssistantContext = createContext(null);
+export function AssistantStateProvider({ children, shortcuts, collections, }) {
+    const [open, setOpen] = useState(true);
+    const [collapsed, setCollapsed] = useState(false);
+    const [status, setStatus] = useState("idle");
+    const [messages, setMessages] = useState([]);
+    const [bridge, setBridge] = useState(null);
+    const [formAdapter, setFormAdapter] = useState(null);
+    const [pendingApproval, setPendingApproval] = useState(null);
+    const [abortController, setAbortController] = useState(null);
+    const stop = useCallback(() => {
+        abortController?.abort();
+        setAbortController(null);
+        setStatus("aborted");
+    }, [abortController]);
+    const resetConversation = useCallback(() => {
+        abortController?.abort();
+        setAbortController(null);
+        setStatus("idle");
+        setMessages([]);
+        setPendingApproval(null);
+    }, [abortController]);
+    const value = useMemo(() => ({
+        open,
+        collapsed,
+        status,
+        messages,
+        shortcuts,
+        collections,
+        bridge,
+        formAdapter,
+        pendingApproval,
+        setOpen,
+        setCollapsed,
+        setBridge,
+        setFormAdapter,
+        setPendingApproval,
+        setStatus,
+        setMessages,
+        resetConversation,
+        stop,
+        abortController,
+        setAbortController,
+    }), [
+        open,
+        collapsed,
+        status,
+        messages,
+        shortcuts,
+        collections,
+        bridge,
+        formAdapter,
+        pendingApproval,
+        resetConversation,
+        stop,
+        abortController,
+    ]);
+    return _jsx(AssistantContext.Provider, { value: value, children: children });
+}
+export function useAssistantState() {
+    const value = useContext(AssistantContext);
+    if (!value) {
+        throw new Error("useAssistantState must be used within EditorAssistantProvider");
+    }
+    return value;
+}

package/dist/config/denied-fields.d.ts

@@ -0,0 +1,3 @@
+export declare const DENIED_COLLECTION_SLUGS: Set<string>;
+export declare function isDeniedFieldName(name: string): boolean;
+export declare function isDeniedCollectionSlug(slug: string): boolean;

package/dist/config/denied-fields.js

@@ -0,0 +1,34 @@
+const DENIED_FIELD_NAMES = new Set([
+    "password",
+    "hash",
+    "salt",
+    "token",
+    "secret",
+    "apiKey",
+    "api_key",
+    "resetPasswordToken",
+    "resetPasswordExpiration",
+    "loginAttempts",
+    "lockUntil",
+    "sessions",
+    "collection",
+    "_status",
+    "createdAt",
+    "updatedAt",
+    "deletedAt",
+]);
+const DENIED_NAME_PATTERN = /(password|secret|token|api[-_]?key|hash|salt|credential)/i;
+export const DENIED_COLLECTION_SLUGS = new Set([
+    "users",
+    "payload-preferences",
+    "payload-migrations",
+]);
+export function isDeniedFieldName(name) {
+    if (DENIED_FIELD_NAMES.has(name)) {
+        return true;
+    }
+    return DENIED_NAME_PATTERN.test(name);
+}
+export function isDeniedCollectionSlug(slug) {
+    return DENIED_COLLECTION_SLUGS.has(slug) || slug.startsWith("payload-");
+}

package/dist/config/validate.d.ts

@@ -0,0 +1,15 @@
+import type { EditorAssistantPluginOptions, EntityAllowlist, HostToolDefinition } from "../types.ts";
+export type ValidatedEditorAssistantOptions = EditorAssistantPluginOptions & {
+    disabled: boolean;
+    collections: Record<string, EntityAllowlist>;
+    globals: Record<string, EntityAllowlist>;
+    denyFields: string[];
+    shortcuts: NonNullable<EditorAssistantPluginOptions["shortcuts"]>;
+    tools: HostToolDefinition[];
+    trustedOrigins: string[];
+    audit: {
+        collection: string;
+        retentionDays?: number;
+    };
+};
+export declare function validateEditorAssistantOptions(options: EditorAssistantPluginOptions): ValidatedEditorAssistantOptions;

package/dist/config/validate.js

@@ -0,0 +1,86 @@
+import { BUILTIN_RISK, EMBEDDED_ONLY_CAPABILITIES, isBuiltinCapability, isEntityCapability, } from "../capabilities.js";
+import { isDeniedCollectionSlug } from "./denied-fields.js";
+const RISK_ORDER = { auto: 0, approval: 1, forbidden: 2 };
+export function validateEditorAssistantOptions(options) {
+    const disabled = options.disabled === true;
+    const collections = options.collections ?? {};
+    const globals = options.globals ?? {};
+    if (!disabled) {
+        if (!options.model) {
+            throw new Error("payload-editor-assistant: `model` is required when the plugin is enabled.");
+        }
+        validateEntityMap("collections", collections, { allowDraftCreate: true });
+        validateEntityMap("globals", globals, { allowDraftCreate: false });
+        validateHostTools(options.tools ?? []);
+    }
+    return {
+        ...options,
+        disabled,
+        collections,
+        globals,
+        denyFields: options.denyFields ?? [],
+        shortcuts: options.shortcuts ?? [],
+        tools: options.tools ?? [],
+        trustedOrigins: options.trustedOrigins ?? [],
+        audit: {
+            collection: options.audit?.collection ?? "editor-assistant-audit",
+            retentionDays: options.audit?.retentionDays,
+        },
+    };
+}
+function validateEntityMap(kind, map, rules) {
+    for (const [slug, entry] of Object.entries(map)) {
+        if (kind === "collections" && isDeniedCollectionSlug(slug)) {
+            throw new Error(`payload-editor-assistant: collection "${slug}" cannot be allowlisted.`);
+        }
+        if (!entry?.capabilities?.length) {
+            throw new Error(`payload-editor-assistant: ${kind} "${slug}" must declare at least one capability.`);
+        }
+        for (const capability of entry.capabilities) {
+            if (!isEntityCapability(capability)) {
+                throw new Error(`payload-editor-assistant: unknown capability "${capability}" on ${kind} "${slug}".`);
+            }
+            if (capability === "draft.create" && !rules.allowDraftCreate) {
+                throw new Error(`payload-editor-assistant: globals cannot enable draft.create ("${slug}").`);
+            }
+        }
+        validateFields(entry, `${kind} "${slug}"`);
+    }
+}
+function validateFields(entry, label) {
+    const fields = entry.fields;
+    if (fields === undefined || fields === true) {
+        return;
+    }
+    if ("include" in fields && "exclude" in fields) {
+        throw new Error(`payload-editor-assistant: ${label} fields cannot set both include and exclude.`);
+    }
+    if ("include" in fields && !Array.isArray(fields.include)) {
+        throw new Error(`payload-editor-assistant: ${label} fields.include must be an array.`);
+    }
+    if ("exclude" in fields && !Array.isArray(fields.exclude)) {
+        throw new Error(`payload-editor-assistant: ${label} fields.exclude must be an array.`);
+    }
+}
+function validateHostTools(tools) {
+    for (const tool of tools) {
+        if (!tool.id || !tool.capabilityId) {
+            throw new Error("payload-editor-assistant: host tools require id and capabilityId.");
+        }
+        const risk = tool.risk ?? "approval";
+        if (risk !== "auto" && risk !== "approval" && risk !== "forbidden") {
+            throw new Error(`payload-editor-assistant: host tool "${tool.id}" has invalid risk.`);
+        }
+        if (isBuiltinCapability(tool.capabilityId)) {
+            if (RISK_ORDER[risk] < RISK_ORDER[BUILTIN_RISK[tool.capabilityId]]) {
+                throw new Error(`payload-editor-assistant: host tool "${tool.id}" cannot loosen risk below ${tool.capabilityId}.`);
+            }
+            if (tool.mcp && EMBEDDED_ONLY_CAPABILITIES.has(tool.capabilityId)) {
+                throw new Error(`payload-editor-assistant: host tool "${tool.id}" cannot mark ${tool.capabilityId} as MCP-eligible.`);
+            }
+        }
+        if (risk === "auto" && tool.mcp === true && tool.capabilityId === "form.propose") {
+            throw new Error(`payload-editor-assistant: host tool "${tool.id}" cannot expose form writes to MCP.`);
+        }
+    }
+}

package/dist/domain/allowlist.d.ts

@@ -0,0 +1,12 @@
+import type { EntityCapability } from "../capabilities.ts";
+import type { ValidatedEditorAssistantOptions } from "../config/validate.ts";
+import type { EntityAllowlist } from "../types.ts";
+export declare function resolveAllowlist(options: ValidatedEditorAssistantOptions, target: {
+    collection?: string;
+    global?: string;
+}): {
+    kind: "collection" | "global";
+    slug: string;
+    allowlist: EntityAllowlist;
+} | null;
+export declare function hasCapability(allowlist: EntityAllowlist, capability: EntityCapability): boolean;

package/dist/domain/allowlist.js

@@ -0,0 +1,14 @@
+export function resolveAllowlist(options, target) {
+    if (target.collection) {
+        const allowlist = options.collections[target.collection];
+        return allowlist ? { kind: "collection", slug: target.collection, allowlist } : null;
+    }
+    if (target.global) {
+        const allowlist = options.globals[target.global];
+        return allowlist ? { kind: "global", slug: target.global, allowlist } : null;
+    }
+    return null;
+}
+export function hasCapability(allowlist, capability) {
+    return allowlist.capabilities.includes(capability);
+}

package/dist/domain/audit.d.ts

@@ -0,0 +1,17 @@
+import type { PayloadRequest } from "payload";
+import type { ValidatedEditorAssistantOptions } from "../config/validate.ts";
+export declare function writeAudit(req: PayloadRequest, options: ValidatedEditorAssistantOptions, event: {
+    capability: string;
+    risk: string;
+    outcome: string;
+    targetCollection?: string;
+    targetGlobal?: string;
+    documentId?: string;
+    locale?: string;
+    fieldPaths?: string[];
+    approvalId?: string;
+    nonceId?: string;
+    canonicalHash?: string;
+    baseRevision?: string;
+    errorClass?: string;
+}): Promise<void>;

package/dist/domain/audit.js

@@ -0,0 +1,25 @@
+import { localApi } from "./local-api.js";
+export async function writeAudit(req, options, event) {
+    await localApi(req).create({
+        collection: options.audit.collection,
+        data: {
+            actor: String(req.user?.id ?? ""),
+            capability: event.capability,
+            risk: event.risk,
+            outcome: event.outcome,
+            targetCollection: event.targetCollection,
+            targetGlobal: event.targetGlobal,
+            documentId: event.documentId,
+            locale: event.locale,
+            fieldPaths: event.fieldPaths,
+            approvalId: event.approvalId,
+            nonceId: event.nonceId,
+            canonicalHash: event.canonicalHash,
+            baseRevision: event.baseRevision,
+            errorClass: event.errorClass,
+        },
+        req,
+        overrideAccess: false,
+        user: req.user,
+    });
+}

package/dist/domain/content.d.ts

@@ -0,0 +1,30 @@
+import type { PayloadRequest } from "payload";
+import type { ValidatedEditorAssistantOptions } from "../config/validate.ts";
+export type ContentFindInput = {
+    collection?: string;
+    query: string;
+    locale: string;
+};
+export type ContentFindByIdInput = {
+    collection?: string;
+    global?: string;
+    documentId?: string | number;
+    locale: string;
+};
+export declare function findContent(req: PayloadRequest, options: ValidatedEditorAssistantOptions, input: ContentFindInput): Promise<{
+    ok: true;
+    results: Record<string, unknown>[];
+} | {
+    ok: false;
+    error: string;
+    message: string;
+}>;
+export declare function findContentById(req: PayloadRequest, options: ValidatedEditorAssistantOptions, input: ContentFindByIdInput): Promise<{
+    ok: true;
+    data: Record<string, unknown>;
+    truncated: boolean;
+} | {
+    ok: false;
+    error: string;
+    message: string;
+}>;

package/dist/domain/content.js

@@ -0,0 +1,117 @@
+import { entityFields, findCollectionConfig, findGlobalConfig } from "../schema/discover.js";
+import { projectIdentity, projectRecord } from "../schema/project.js";
+import { hasCapability, resolveAllowlist } from "./allowlist.js";
+import { localApi } from "./local-api.js";
+const FIND_LIMIT = 8;
+export async function findContent(req, options, input) {
+    const query = input.query.trim();
+    const slugs = input.collection
+        ? [input.collection]
+        : Object.entries(options.collections)
+            .filter(([, allowlist]) => hasCapability(allowlist, "content.find"))
+            .map(([slug]) => slug);
+    const results = [];
+    for (const slug of slugs) {
+        const resolved = resolveAllowlist(options, { collection: slug });
+        if (!resolved || !hasCapability(resolved.allowlist, "content.find")) {
+            if (input.collection) {
+                return {
+                    ok: false,
+                    error: "tool_denied",
+                    message: "Collection is not allowlisted for search.",
+                };
+            }
+            continue;
+        }
+        const config = findCollectionConfig(req, slug);
+        if (!config) {
+            continue;
+        }
+        try {
+            const found = await localApi(req).find({
+                collection: slug,
+                ...(query ? { where: searchWhere(query, config.admin?.useAsTitle) } : {}),
+                limit: FIND_LIMIT,
+                depth: 0,
+                locale: input.locale,
+                draft: true,
+                sort: "-updatedAt",
+                req,
+                user: req.user,
+                overrideAccess: false,
+            });
+            for (const doc of found.docs) {
+                results.push({
+                    collection: slug,
+                    ...projectIdentity(doc, input.locale),
+                });
+            }
+        }
+        catch {
+            if (input.collection) {
+                return { ok: false, error: "tool_denied", message: "Search failed." };
+            }
+        }
+        if (results.length >= FIND_LIMIT) {
+            break;
+        }
+    }
+    return { ok: true, results: results.slice(0, FIND_LIMIT) };
+}
+export async function findContentById(req, options, input) {
+    const resolved = resolveAllowlist(options, input);
+    if (!resolved || !hasCapability(resolved.allowlist, "content.findById")) {
+        return { ok: false, error: "tool_denied", message: "Target is not allowlisted for read." };
+    }
+    const fields = entityFields(req, options, input);
+    try {
+        if (input.global) {
+            const global = findGlobalConfig(req, input.global);
+            if (!global) {
+                return { ok: false, error: "tool_denied", message: "Global was not found." };
+            }
+            const doc = await localApi(req).findGlobal({
+                slug: input.global,
+                depth: 0,
+                locale: input.locale,
+                draft: true,
+                req,
+                user: req.user,
+                overrideAccess: false,
+            });
+            const projected = projectRecord(doc, fields, options.redact, input.global);
+            return { ok: true, ...projected };
+        }
+        if (!input.collection || input.documentId === undefined) {
+            return {
+                ok: false,
+                error: "tool_denied",
+                message: "A collection and document id are required.",
+            };
+        }
+        const doc = await localApi(req).findByID({
+            collection: input.collection,
+            id: input.documentId,
+            depth: 0,
+            locale: input.locale,
+            draft: true,
+            req,
+            user: req.user,
+            overrideAccess: false,
+        });
+        const projected = projectRecord(doc, fields, options.redact, input.collection);
+        return { ok: true, ...projected };
+    }
+    catch {
+        return { ok: false, error: "tool_denied", message: "Document is not accessible." };
+    }
+}
+function searchWhere(query, useAsTitle) {
+    const clauses = [{ id: { equals: query } }];
+    const titleField = useAsTitle && useAsTitle !== "id" ? useAsTitle : "title";
+    clauses.push({ [titleField]: { contains: query } });
+    if (titleField !== "slug") {
+        clauses.push({ slug: { contains: query } });
+    }
+    return { or: clauses };
+}

package/dist/domain/decide.d.ts

@@ -0,0 +1,30 @@
+import type { PayloadRequest } from "payload";
+import type { ValidatedEditorAssistantOptions } from "../config/validate.ts";
+export type DecideInput = {
+    action: "approve" | "reject";
+    approvalId: string;
+    nonce: string;
+    collection?: string;
+    global?: string;
+    documentId?: string | number;
+    locale: string;
+    formData?: Record<string, unknown>;
+};
+export type DecideResult = {
+    ok: true;
+    capability: "form.propose";
+    patchedData: Record<string, unknown>;
+} | {
+    ok: true;
+    capability: "draft.create";
+    documentId: string;
+    collection: string;
+} | {
+    ok: true;
+    rejected: true;
+} | {
+    ok: false;
+    error: "tool_denied" | "stale_context";
+    message: string;
+};
+export declare function decideChange(req: PayloadRequest, options: ValidatedEditorAssistantOptions, input: DecideInput): Promise<DecideResult>;