@humaan/payload-plugin-ai-assistant 0.0.0-stage → 0.1.0

package/dist/plan/catalogue.js

@@ -0,0 +1,157 @@
+import { deniedSlugs } from '../constants.js';
+import { pluginRuntime } from '../runtime.js';
+import { assistantNote, blockSlugs, formatFieldGuide } from '../schema/fields.js';
+const denied = new Set(deniedSlugs);
+/** Every collection and global the assistant can read, with the editor's own access. */ export function planTargets(config) {
+    const collections = (config.collections ?? []).flatMap((collection)=>{
+        if (denied.has(collection.slug) || collection.auth) {
+            return [];
+        }
+        return [
+            collectionTarget(collection)
+        ];
+    });
+    const globals = (config.globals ?? []).flatMap((global)=>{
+        if (denied.has(global.slug)) {
+            return [];
+        }
+        return [
+            globalTarget(global)
+        ];
+    });
+    return [
+        ...collections,
+        ...globals
+    ];
+}
+/**
+ * Whether a plan may change a target. Never what the assistant cannot read, nor Payload's own `payload-*`
+ * collections, nor anything the plugin options deny.
+ */ export function canChangeTarget(config, kind, slug) {
+    if (!findTarget(config, kind, slug)) {
+        return false;
+    }
+    const runtime = pluginRuntime(config);
+    if (kind === 'global') {
+        return !runtime.deniedGlobals.includes(slug);
+    }
+    return !slug.startsWith('payload-') && !runtime.deniedCollections.includes(slug);
+}
+/** Upload collections a plan may save attachments into. */ export function uploadTargets(config) {
+    return (config.collections ?? []).flatMap((collection)=>{
+        if (!collection.upload || !canChangeTarget(config, 'collection', collection.slug)) {
+            return [];
+        }
+        return [
+            {
+                slug: collection.slug,
+                mimeTypes: mimeTypesFromUpload(collection.upload)
+            }
+        ];
+    });
+}
+export function findTarget(config, kind, slug) {
+    return planTargets(config).find((target)=>target.kind === kind && target.slug === slug);
+}
+export function collectionFields(config, slug) {
+    return config.collections?.find((collection)=>collection.slug === slug)?.fields;
+}
+export function globalFields(config, slug) {
+    return config.globals?.find((global)=>global.slug === slug)?.fields;
+}
+export function titleFieldOf(config, slug) {
+    const collection = config.collections?.find((item)=>item.slug === slug);
+    return typeof collection?.admin.useAsTitle === 'string' ? collection.admin.useAsTitle : 'title';
+}
+export function describeTarget(config, kind, slug, rules, blocks = []) {
+    const target = findTarget(config, kind, slug);
+    if (!target) {
+        return {
+            error: `Unknown ${kind} "${slug}".`
+        };
+    }
+    const fields = (kind === 'collection' ? collectionFields(config, slug) : globalFields(config, slug)) ?? [];
+    const guide = formatFieldGuide(fields, {
+        blocks
+    });
+    const known = blockSlugs(fields);
+    const unknown = blocks.filter((block)=>!known.includes(block));
+    const listedOnly = known.filter((block)=>!blocks.includes(block));
+    const blockNote = [
+        listedOnly.length > 0 ? 'Blocks without fields underneath are listed by name only. Call describeTarget again with blocks set to the ones you will write.' : '',
+        unknown.length > 0 ? `No block named: ${unknown.join(', ')}.` : ''
+    ].filter(Boolean).join(' ');
+    const rule = rules?.[slug]?.trim();
+    const entity = kind === 'collection' ? config.collections?.find((item)=>item.slug === slug) : config.globals?.find((item)=>item.slug === slug);
+    const note = entity ? assistantNote(entity) : undefined;
+    return {
+        guide: guide || 'This target has no fields the assistant can fill.',
+        ...note ? {
+            note
+        } : {},
+        ...blockNote ? {
+            blocks: blockNote
+        } : {},
+        ...rule ? {
+            rules: rule
+        } : {},
+        drafts: target.drafts,
+        upload: target.upload
+    };
+}
+/** A title search and any field filters, all of which must match. */ export function searchWhere(config, slug, query, filters = []) {
+    const conditions = [];
+    const trimmed = query.trim();
+    if (trimmed) {
+        conditions.push({
+            [titleFieldOf(config, slug)]: {
+                like: trimmed
+            }
+        });
+    }
+    for (const filter of filters){
+        conditions.push({
+            [filter.field]: {
+                [filter.operator]: filter.value
+            }
+        });
+    }
+    if (conditions.length === 0) {
+        return undefined;
+    }
+    return conditions.length === 1 ? conditions[0] : {
+        and: conditions
+    };
+}
+function collectionTarget(collection) {
+    const labels = collection.labels;
+    const label = labels && typeof labels === 'object' && typeof labels.singular === 'string' ? labels.singular : collection.slug;
+    return {
+        slug: collection.slug,
+        kind: 'collection',
+        label,
+        drafts: hasDrafts(collection.versions),
+        upload: Boolean(collection.upload)
+    };
+}
+function globalTarget(global) {
+    return {
+        slug: global.slug,
+        kind: 'global',
+        label: typeof global.label === 'string' ? global.label : global.slug,
+        drafts: hasDrafts(global.versions),
+        upload: false
+    };
+}
+function hasDrafts(versions) {
+    return Boolean(versions && typeof versions === 'object' && versions.drafts);
+}
+function mimeTypesFromUpload(upload) {
+    if (!upload || typeof upload !== 'object' || !('mimeTypes' in upload)) {
+        return [];
+    }
+    const types = upload.mimeTypes;
+    return Array.isArray(types) ? types.filter((item)=>typeof item === 'string') : [];
+}
+
+//# sourceMappingURL=catalogue.js.map

package/dist/plan/catalogue.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/plan/catalogue.ts"],"sourcesContent":["import type {\n  CollectionSlug,\n  Field,\n  SanitizedCollectionConfig,\n  SanitizedConfig,\n  SanitizedGlobalConfig,\n  Where,\n} from 'payload'\n\nimport type { AiAssistantPluginOptions } from '../types.js'\nimport type { PlanTarget } from './stored.js'\n\nimport { deniedSlugs } from '../constants.js'\nimport { pluginRuntime } from '../runtime.js'\nimport { assistantNote, blockSlugs, formatFieldGuide } from '../schema/fields.js'\n\nconst denied = new Set<string>(deniedSlugs)\n\n/** Every collection and global the assistant can read, with the editor's own access. */\nexport function planTargets(config: SanitizedConfig): PlanTarget[] {\n  const collections = (config.collections ?? []).flatMap((collection) => {\n    if (denied.has(collection.slug) || collection.auth) {\n      return []\n    }\n    return [collectionTarget(collection)]\n  })\n  const globals = (config.globals ?? []).flatMap((global) => {\n    if (denied.has(global.slug)) {\n      return []\n    }\n    return [globalTarget(global)]\n  })\n  return [...collections, ...globals]\n}\n\n/**\n * Whether a plan may change a target. Never what the assistant cannot read, nor Payload's own `payload-*`\n * collections, nor anything the plugin options deny.\n */\nexport function canChangeTarget(\n  config: SanitizedConfig,\n  kind: 'collection' | 'global',\n  slug: string,\n): boolean {\n  if (!findTarget(config, kind, slug)) {\n    return false\n  }\n  const runtime = pluginRuntime(config)\n  if (kind === 'global') {\n    return !runtime.deniedGlobals.includes(slug)\n  }\n  return !slug.startsWith('payload-') && !runtime.deniedCollections.includes(slug)\n}\n\n/** Upload collections a plan may save attachments into. */\nexport function uploadTargets(config: SanitizedConfig): { mimeTypes: string[]; slug: string }[] {\n  return (config.collections ?? []).flatMap((collection) => {\n    if (!collection.upload || !canChangeTarget(config, 'collection', collection.slug)) {\n      return []\n    }\n    return [{ slug: collection.slug, mimeTypes: mimeTypesFromUpload(collection.upload) }]\n  })\n}\n\nexport function findTarget(\n  config: SanitizedConfig,\n  kind: 'collection' | 'global',\n  slug: string,\n): PlanTarget | undefined {\n  return planTargets(config).find((target) => target.kind === kind && target.slug === slug)\n}\n\nexport function collectionFields(config: SanitizedConfig, slug: string): Field[] | undefined {\n  return config.collections?.find((collection) => collection.slug === slug)?.fields\n}\n\nexport function globalFields(config: SanitizedConfig, slug: string): Field[] | undefined {\n  return config.globals?.find((global) => global.slug === slug)?.fields\n}\n\nexport function titleFieldOf(config: SanitizedConfig, slug: string): string {\n  const collection = config.collections?.find((item) => item.slug === slug)\n  return typeof collection?.admin.useAsTitle === 'string' ? collection.admin.useAsTitle : 'title'\n}\n\nexport function describeTarget(\n  config: SanitizedConfig,\n  kind: 'collection' | 'global',\n  slug: string,\n  rules: AiAssistantPluginOptions['collectionRules'],\n  blocks: readonly string[] = [],\n):\n  | {\n      blocks?: string\n      drafts: boolean\n      guide: string\n      note?: string\n      rules?: string\n      upload: boolean\n    }\n  | { error: string } {\n  const target = findTarget(config, kind, slug)\n  if (!target) {\n    return { error: `Unknown ${kind} \"${slug}\".` }\n  }\n  const fields =\n    (kind === 'collection' ? collectionFields(config, slug) : globalFields(config, slug)) ?? []\n  const guide = formatFieldGuide(fields, { blocks })\n  const known = blockSlugs(fields)\n  const unknown = blocks.filter((block) => !known.includes(block))\n  const listedOnly = known.filter((block) => !blocks.includes(block))\n  const blockNote = [\n    listedOnly.length > 0\n      ? 'Blocks without fields underneath are listed by name only. Call describeTarget again with blocks set to the ones you will write.'\n      : '',\n    unknown.length > 0 ? `No block named: ${unknown.join(', ')}.` : '',\n  ]\n    .filter(Boolean)\n    .join(' ')\n  const rule = rules?.[slug as CollectionSlug]?.trim()\n  const entity =\n    kind === 'collection'\n      ? config.collections?.find((item) => item.slug === slug)\n      : config.globals?.find((item) => item.slug === slug)\n  const note = entity ? assistantNote(entity) : undefined\n  return {\n    guide: guide || 'This target has no fields the assistant can fill.',\n    ...(note ? { note } : {}),\n    ...(blockNote ? { blocks: blockNote } : {}),\n    ...(rule ? { rules: rule } : {}),\n    drafts: target.drafts,\n    upload: target.upload,\n  }\n}\n\nexport interface SearchFilter {\n  /** Dotted field path, such as `category` or `seo.noIndex`. Payload checks it against the schema and the editor's field access. */\n  field: string\n  operator: 'equals' | 'exists' | 'in' | 'like' | 'not_equals'\n  value: (number | string)[] | boolean | number | string\n}\n\n/** A title search and any field filters, all of which must match. */\nexport function searchWhere(\n  config: SanitizedConfig,\n  slug: string,\n  query: string,\n  filters: readonly SearchFilter[] = [],\n): undefined | Where {\n  const conditions: Where[] = []\n  const trimmed = query.trim()\n  if (trimmed) {\n    conditions.push({ [titleFieldOf(config, slug)]: { like: trimmed } })\n  }\n  for (const filter of filters) {\n    conditions.push({ [filter.field]: { [filter.operator]: filter.value } })\n  }\n  if (conditions.length === 0) {\n    return undefined\n  }\n  return conditions.length === 1 ? conditions[0] : { and: conditions }\n}\n\nfunction collectionTarget(collection: SanitizedCollectionConfig): PlanTarget {\n  const labels = collection.labels\n  const label =\n    labels && typeof labels === 'object' && typeof labels.singular === 'string'\n      ? labels.singular\n      : collection.slug\n  return {\n    slug: collection.slug,\n    kind: 'collection',\n    label,\n    drafts: hasDrafts(collection.versions),\n    upload: Boolean(collection.upload),\n  }\n}\n\nfunction globalTarget(global: SanitizedGlobalConfig): PlanTarget {\n  return {\n    slug: global.slug,\n    kind: 'global',\n    label: typeof global.label === 'string' ? global.label : global.slug,\n    drafts: hasDrafts(global.versions),\n    upload: false,\n  }\n}\n\nfunction hasDrafts(versions: { drafts?: unknown } | undefined): boolean {\n  return Boolean(versions && typeof versions === 'object' && versions.drafts)\n}\n\nfunction mimeTypesFromUpload(upload: SanitizedCollectionConfig['upload']): string[] {\n  if (!upload || typeof upload !== 'object' || !('mimeTypes' in upload)) {\n    return []\n  }\n  const types = upload.mimeTypes\n  return Array.isArray(types)\n    ? types.filter((item): item is string => typeof item === 'string')\n    : []\n}\n"],"names":["deniedSlugs","pluginRuntime","assistantNote","blockSlugs","formatFieldGuide","denied","Set","planTargets","config","collections","flatMap","collection","has","slug","auth","collectionTarget","globals","global","globalTarget","canChangeTarget","kind","findTarget","runtime","deniedGlobals","includes","startsWith","deniedCollections","uploadTargets","upload","mimeTypes","mimeTypesFromUpload","find","target","collectionFields","fields","globalFields","titleFieldOf","item","admin","useAsTitle","describeTarget","rules","blocks","error","guide","known","unknown","filter","block","listedOnly","blockNote","length","join","Boolean","rule","trim","entity","note","undefined","drafts","searchWhere","query","filters","conditions","trimmed","push","like","field","operator","value","and","labels","label","singular","hasDrafts","versions","types","Array","isArray"],"mappings":"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"}

package/dist/plan/diff.d.ts

@@ -0,0 +1,13 @@
+import type { FieldChangeView } from '../types.js';
+import type { StoredFile, StoredOperation } from './stored.js';
+/**
+ * What an operation will write, field by field, with the current value beside it.
+ * Nested groups become dotted paths. Lists and blocks are shown whole.
+ * `current` is the document as the assistant reads it, so rich text is markdown on both sides.
+ */
+export declare function fieldChanges({ operation, current, files, operations, }: {
+    current?: unknown;
+    files: readonly StoredFile[];
+    operation: StoredOperation;
+    operations: readonly StoredOperation[];
+}): FieldChangeView[];

package/dist/plan/diff.js

@@ -0,0 +1,87 @@
+import { valueAtPath } from './tokens.js';
+const maxChanges = 30;
+const maxValueCharacters = 2_000;
+/**
+ * What an operation will write, field by field, with the current value beside it.
+ * Nested groups become dotted paths. Lists and blocks are shown whole.
+ * `current` is the document as the assistant reads it, so rich text is markdown on both sides.
+ */ export function fieldChanges({ operation, current, files, operations }) {
+    const show = (value)=>display(value, files, operations);
+    const changes = leaves(operation.set).map(([path, value])=>{
+        const before = current === undefined ? undefined : valueAtPath(current, path);
+        return {
+            path,
+            ...isEmpty(before) ? {} : {
+                before: show(before)
+            },
+            after: show(value)
+        };
+    });
+    for (const append of operation.append){
+        changes.push({
+            path: append.path,
+            added: true,
+            after: show(append.blocks)
+        });
+    }
+    return changes.slice(0, maxChanges);
+}
+function leaves(value, prefix = '') {
+    return Object.entries(value).flatMap(([key, item])=>{
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (isRecord(item) && !isToken(item) && Object.keys(item).length > 0) {
+            return leaves(item, path);
+        }
+        return [
+            [
+                path,
+                item
+            ]
+        ];
+    });
+}
+function display(value, files, operations) {
+    const named = withTokenNames(value, files, operations);
+    if (typeof named === 'string') {
+        return cut(named);
+    }
+    if (typeof named === 'number' || typeof named === 'boolean') {
+        return String(named);
+    }
+    return cut(JSON.stringify(named, null, 2) ?? '');
+}
+/** Swaps `{ "$file": 0 }` and `{ "$op": 1 }` for words the editor recognises. */ function withTokenNames(value, files, operations) {
+    if (Array.isArray(value)) {
+        return value.map((item)=>withTokenNames(item, files, operations));
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    if (isToken(value)) {
+        if ('$file' in value) {
+            const file = files.find((item)=>item.index === value.$file);
+            return `Attached file: ${file?.title || file?.name || `#${String(value.$file)}`}`;
+        }
+        const index = typeof value.$op === 'number' ? value.$op : -1;
+        return `New document: ${operations[index]?.label ?? `step ${index + 1}`}`;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, item])=>[
+            key,
+            withTokenNames(item, files, operations)
+        ]));
+}
+function isToken(value) {
+    const keys = Object.keys(value);
+    return keys.length === 1 && (keys[0] === '$file' || keys[0] === '$op');
+}
+function isEmpty(value) {
+    return value === undefined || value === null || value === '' || Array.isArray(value) && value.length === 0;
+}
+function cut(value) {
+    return value.length > maxValueCharacters ? `${value.slice(0, maxValueCharacters)}…` : value;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+//# sourceMappingURL=diff.js.map

package/dist/plan/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/plan/diff.ts"],"sourcesContent":["import type { FieldChangeView } from '../types.js'\nimport type { StoredFile, StoredOperation } from './stored.js'\n\nimport { valueAtPath } from './tokens.js'\n\nconst maxChanges = 30\nconst maxValueCharacters = 2_000\n\n/**\n * What an operation will write, field by field, with the current value beside it.\n * Nested groups become dotted paths. Lists and blocks are shown whole.\n * `current` is the document as the assistant reads it, so rich text is markdown on both sides.\n */\nexport function fieldChanges({\n  operation,\n  current,\n  files,\n  operations,\n}: {\n  current?: unknown\n  files: readonly StoredFile[]\n  operation: StoredOperation\n  operations: readonly StoredOperation[]\n}): FieldChangeView[] {\n  const show = (value: unknown) => display(value, files, operations)\n  const changes: FieldChangeView[] = leaves(operation.set).map(([path, value]) => {\n    const before = current === undefined ? undefined : valueAtPath(current, path)\n    return {\n      path,\n      ...(isEmpty(before) ? {} : { before: show(before) }),\n      after: show(value),\n    }\n  })\n  for (const append of operation.append) {\n    changes.push({ path: append.path, added: true, after: show(append.blocks) })\n  }\n  return changes.slice(0, maxChanges)\n}\n\nfunction leaves(value: Record<string, unknown>, prefix = ''): [string, unknown][] {\n  return Object.entries(value).flatMap(([key, item]): [string, unknown][] => {\n    const path = prefix ? `${prefix}.${key}` : key\n    if (isRecord(item) && !isToken(item) && Object.keys(item).length > 0) {\n      return leaves(item, path)\n    }\n    return [[path, item]]\n  })\n}\n\nfunction display(\n  value: unknown,\n  files: readonly StoredFile[],\n  operations: readonly StoredOperation[],\n): string {\n  const named = withTokenNames(value, files, operations)\n  if (typeof named === 'string') {\n    return cut(named)\n  }\n  if (typeof named === 'number' || typeof named === 'boolean') {\n    return String(named)\n  }\n  return cut(JSON.stringify(named, null, 2) ?? '')\n}\n\n/** Swaps `{ \"$file\": 0 }` and `{ \"$op\": 1 }` for words the editor recognises. */\nfunction withTokenNames(\n  value: unknown,\n  files: readonly StoredFile[],\n  operations: readonly StoredOperation[],\n): unknown {\n  if (Array.isArray(value)) {\n    return value.map((item) => withTokenNames(item, files, operations))\n  }\n  if (!isRecord(value)) {\n    return value\n  }\n  if (isToken(value)) {\n    if ('$file' in value) {\n      const file = files.find((item) => item.index === value.$file)\n      return `Attached file: ${file?.title || file?.name || `#${String(value.$file)}`}`\n    }\n    const index = typeof value.$op === 'number' ? value.$op : -1\n    return `New document: ${operations[index]?.label ?? `step ${index + 1}`}`\n  }\n  return Object.fromEntries(\n    Object.entries(value).map(([key, item]) => [key, withTokenNames(item, files, operations)]),\n  )\n}\n\nfunction isToken(value: Record<string, unknown>): boolean {\n  const keys = Object.keys(value)\n  return keys.length === 1 && (keys[0] === '$file' || keys[0] === '$op')\n}\n\nfunction isEmpty(value: unknown): boolean {\n  return (\n    value === undefined ||\n    value === null ||\n    value === '' ||\n    (Array.isArray(value) && value.length === 0)\n  )\n}\n\nfunction cut(value: string): string {\n  return value.length > maxValueCharacters ? `${value.slice(0, maxValueCharacters)}…` : value\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)\n}\n"],"names":["valueAtPath","maxChanges","maxValueCharacters","fieldChanges","operation","current","files","operations","show","value","display","changes","leaves","set","map","path","before","undefined","isEmpty","after","append","push","added","blocks","slice","prefix","Object","entries","flatMap","key","item","isRecord","isToken","keys","length","named","withTokenNames","cut","String","JSON","stringify","Array","isArray","file","find","index","$file","title","name","$op","label","fromEntries","Boolean"],"mappings":"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"}

package/dist/plan/parsePlan.d.ts

@@ -0,0 +1,27 @@
+import type { PlanTarget, StoredFile, StoredPlan } from './stored.js';
+/** A file attached to the conversation, by its position in the conversation's attachments. */
+export interface IncomingFile {
+    /** The stored attachment, read again when a plan that lists it is applied. */
+    attachmentId: string;
+    /** Where a plan would save it. Empty when no allowed upload collection accepts it, so it can be read but not saved. */
+    collection: string;
+    index: number;
+    kind: StoredFile['kind'];
+    name: string;
+    savesImmediately: boolean;
+    size: number;
+    type: string;
+}
+/**
+ * Turns the model's submitPlan arguments into a plan the server can run.
+ * Field values are kept, but only for collections the editor is allowed to change.
+ */
+export declare function parsePlan(input: unknown, targets: readonly PlanTarget[], files: readonly IncomingFile[]): {
+    errors: string[];
+    ok: false;
+} | {
+    ok: true;
+    plan: StoredPlan;
+};
+/** `{ "seo.image": id }` becomes `{ seo: { image: id } }`, the shape the fields expect. */
+export declare function nestDottedKeys(value: Record<string, unknown>): Record<string, unknown>;

package/dist/plan/parsePlan.js

@@ -0,0 +1,322 @@
+import { deniedSlugs } from '../constants.js';
+import { topLevelSetPaths } from '../schema/listingFields.js';
+const denied = new Set(deniedSlugs);
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function text(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+/**
+ * Turns the model's submitPlan arguments into a plan the server can run.
+ * Field values are kept, but only for collections the editor is allowed to change.
+ */ export function parsePlan(input, targets, files) {
+    if (!isRecord(input)) {
+        return {
+            ok: false,
+            errors: [
+                'The plan must be an object.'
+            ]
+        };
+    }
+    const errors = [];
+    const summary = text(input.summary);
+    if (!summary) {
+        errors.push('Add a summary of what will change.');
+    }
+    const blocked = input.blocked === true;
+    const questions = stringList(input.questions);
+    const bySlug = new Map(targets.map((target)=>[
+            `${target.kind}:${target.slug}`,
+            target
+        ]));
+    const operations = Array.isArray(input.operations) ? input.operations : [];
+    if (!Array.isArray(input.operations)) {
+        errors.push('operations must be a list.');
+    }
+    if (blocked && operations.length > 0) {
+        errors.push('A blocked plan must not include operations.');
+    }
+    if (blocked && questions.length === 0) {
+        errors.push('Say what the editor needs to decide.');
+    }
+    const parsedOperations = operations.flatMap((item, index)=>{
+        const operation = parseOperation(item, index, bySlug, errors);
+        return operation ? [
+            operation
+        ] : [];
+    });
+    const referencedFiles = new Set();
+    for (const [index, operation] of parsedOperations.entries()){
+        const tokens = {
+            operationIndex: index,
+            fileCount: files.length,
+            referencedFiles,
+            errors
+        };
+        collectTokenErrors(operation.set, `operations.${index}.set`, tokens);
+        for (const append of operation.append){
+            collectTokenErrors(append.blocks, `operations.${index}.append`, tokens);
+        }
+    }
+    const fileNotes = parseFileNotes(input.files, files, errors);
+    for (const index of referencedFiles){
+        if (!fileNotes.has(index)) {
+            errors.push(`List file ${index} in files before a field points at it.`);
+        }
+    }
+    if (!blocked && parsedOperations.length === 0 && fileNotes.size === 0) {
+        errors.push('The plan needs an operation, or a file to save.');
+    }
+    const candidates = parseCandidates(input.candidates, bySlug, errors);
+    if (errors.length > 0) {
+        return {
+            ok: false,
+            errors
+        };
+    }
+    return {
+        ok: true,
+        plan: {
+            summary,
+            blocked,
+            questions,
+            candidates,
+            operations: parsedOperations,
+            files: files.flatMap((file)=>{
+                const note = fileNotes.get(file.index);
+                if (!note) {
+                    return [];
+                }
+                return [
+                    {
+                        ...file,
+                        alt: note.alt,
+                        title: note.title,
+                        note: note.note || 'Saved with this request.'
+                    }
+                ];
+            })
+        }
+    };
+}
+function parseOperation(item, index, bySlug, errors) {
+    if (!isRecord(item)) {
+        errors.push(`Operation ${index + 1} must be an object.`);
+        return undefined;
+    }
+    const action = item.action === 'create' || item.action === 'update' ? item.action : undefined;
+    const kind = item.kind === 'global' ? 'global' : item.kind === 'collection' ? 'collection' : undefined;
+    const slug = text(item.slug);
+    const label = text(item.label);
+    const summary = text(item.summary);
+    if (!action) {
+        errors.push(`Operation ${index + 1} needs action create or update.`);
+    }
+    if (!kind) {
+        errors.push(`Operation ${index + 1} needs kind collection or global.`);
+    }
+    if (!slug) {
+        errors.push(`Operation ${index + 1} needs a slug.`);
+    }
+    if (!label) {
+        errors.push(`Operation ${index + 1} needs a label.`);
+    }
+    if (!summary) {
+        errors.push(`Operation ${index + 1} needs a summary.`);
+    }
+    if (slug && denied.has(slug)) {
+        errors.push(`The assistant cannot change ${slug}.`);
+    }
+    const target = kind && slug ? bySlug.get(`${kind}:${slug}`) : undefined;
+    if (kind && slug && !denied.has(slug) && !target) {
+        errors.push(`Unknown ${kind} "${slug}".`);
+    }
+    if (action === 'create' && kind === 'global') {
+        errors.push(`Globals cannot be created. Update ${slug || 'the global'}.`);
+    }
+    if (action === 'create' && target?.upload) {
+        errors.push(`Save files from the attachment list. Do not create a ${slug} document.`);
+    }
+    if (action === 'update' && !text(item.id) && kind === 'collection') {
+        errors.push(`Operation ${index + 1} updates ${slug || 'a document'} and needs an id from searchDocuments or readDocument.`);
+    }
+    const set = isRecord(item.set) ? item.set : undefined;
+    if (item.set !== undefined && !set) {
+        errors.push(`Operation ${index + 1} set must be an object.`);
+    }
+    const append = parseAppend(item.append, index, errors);
+    if (!action || !kind || !slug || !label || !summary) {
+        return undefined;
+    }
+    const data = nestDottedKeys(set ?? {});
+    return {
+        action,
+        kind,
+        slug,
+        id: text(item.id) || undefined,
+        label,
+        summary,
+        savesImmediately: target ? !target.drafts : true,
+        fields: topLevelSetPaths(data),
+        set: data,
+        append
+    };
+}
+/** `{ "seo.image": id }` becomes `{ seo: { image: id } }`, the shape the fields expect. */ export function nestDottedKeys(value) {
+    const nested = {};
+    for (const [key, item] of Object.entries(value)){
+        const keys = key.split('.').filter(Boolean);
+        let current = nested;
+        for (const part of keys.slice(0, -1)){
+            if (!isRecord(current[part])) {
+                current[part] = {};
+            }
+            current = current[part];
+        }
+        const leaf = keys.at(-1);
+        if (!leaf) {
+            continue;
+        }
+        const next = isRecord(item) && !isToken(item) ? nestDottedKeys(item) : item;
+        current[leaf] = isRecord(current[leaf]) && isRecord(next) ? {
+            ...current[leaf],
+            ...next
+        } : next;
+    }
+    return nested;
+}
+function isToken(value) {
+    const keys = Object.keys(value);
+    return keys.length === 1 && (keys[0] === '$file' || keys[0] === '$op');
+}
+function parseAppend(value, index, errors) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        errors.push(`Operation ${index + 1} append must be a list.`);
+        return [];
+    }
+    return value.flatMap((item)=>{
+        if (!isRecord(item) || !text(item.path) || !Array.isArray(item.blocks)) {
+            errors.push(`Operation ${index + 1} append entries need a path and a blocks list.`);
+            return [];
+        }
+        const blocks = item.blocks.filter(isRecord);
+        if (blocks.length !== item.blocks.length) {
+            errors.push(`Operation ${index + 1} blocks must be objects with blockType.`);
+        }
+        return [
+            {
+                path: text(item.path),
+                blocks
+            }
+        ];
+    });
+}
+/**
+ * Only the files the plan lists are saved. A conversation keeps its attachments, so a later plan
+ * must not save a file again that an earlier plan already saved.
+ */ function parseFileNotes(value, files, errors) {
+    const notes = new Map();
+    if (value === undefined) {
+        return notes;
+    }
+    if (!Array.isArray(value)) {
+        errors.push('files must be a list.');
+        return notes;
+    }
+    for (const item of value){
+        if (!isRecord(item) || typeof item.index !== 'number') {
+            continue;
+        }
+        const file = files.find((candidate)=>candidate.index === item.index);
+        if (!file) {
+            errors.push(`File ${item.index} is not attached.`);
+            continue;
+        }
+        if (!file.collection) {
+            errors.push(`${file.name} cannot be saved: no upload collection the assistant may change accepts it.`);
+            continue;
+        }
+        const note = {
+            alt: text(item.alt),
+            title: text(item.title),
+            note: text(item.note)
+        };
+        if (file.kind === 'image' && !note.alt) {
+            errors.push(`Add alt text for ${file.name}.`);
+        }
+        notes.set(item.index, note);
+    }
+    return notes;
+}
+function parseCandidates(value, bySlug, errors) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        errors.push('candidates must be a list.');
+        return [];
+    }
+    return value.flatMap((item)=>{
+        if (!isRecord(item)) {
+            return [];
+        }
+        const kind = item.kind === 'global' ? 'global' : 'collection';
+        const slug = text(item.slug);
+        const label = text(item.label);
+        if (!slug || !label) {
+            return [];
+        }
+        if (!bySlug.has(`${kind}:${slug}`) && !denied.has(slug)) {
+            errors.push(`Unknown candidate "${slug}".`);
+        }
+        return [
+            {
+                kind,
+                slug,
+                id: text(item.id) || undefined,
+                label
+            }
+        ];
+    });
+}
+function stringList(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.map(text).filter(Boolean);
+}
+function collectTokenErrors(value, path, check) {
+    if (Array.isArray(value)) {
+        value.forEach((item, index)=>collectTokenErrors(item, `${path}.${index}`, check));
+        return;
+    }
+    if (!isRecord(value)) {
+        return;
+    }
+    const keys = Object.keys(value);
+    if (keys.length === 1 && keys[0] === '$file') {
+        const index = value.$file;
+        if (typeof index !== 'number' || !Number.isInteger(index) || index < 0 || index >= check.fileCount) {
+            check.errors.push(`${path} refers to a file that was not attached.`);
+        } else {
+            check.referencedFiles.add(index);
+        }
+        return;
+    }
+    if (keys.length === 1 && keys[0] === '$op') {
+        const index = value.$op;
+        if (typeof index !== 'number' || !Number.isInteger(index) || index < 0 || index >= check.operationIndex) {
+            check.errors.push(`${path} must refer to an earlier operation.`);
+        }
+        return;
+    }
+    for (const [key, item] of Object.entries(value)){
+        collectTokenErrors(item, `${path}.${key}`, check);
+    }
+}
+
+//# sourceMappingURL=parsePlan.js.map