@payloadcms/figma 0.1.0-alpha.2 → 0.1.0-alpha.4

package/dist/db-content-api/index.js

@@ -1,5 +1,5 @@
 import createClient from 'openapi-fetch';
-import { APIError, createDatabaseAdapter } from 'payload';
+import { APIError, createDatabaseAdapter, ValidationError } from 'payload';
 import { v4 as uuid } from 'uuid';
 import { FigmaApiError } from '../api/figma-api.js';
 import { CONTENT_SYSTEM_NOT_FOUND_MESSAGE } from '../constants.js';
@@ -9,11 +9,12 @@ import { unwrapDocument, unwrapFindResponse } from './temp-utilities/unwrapDocum
 import { createAuthMiddleware, createErrorMiddleware } from './utilities/auth.js';
 import { getClientVersionHeaders } from './utilities/clientVersionHeaders.js';
 import { dataToContentAPI, resolveVersionContent } from './utilities/data/index.js';
+import { injectGlobalType } from './utilities/data/injectGlobalType.js';
 import { validateRelationshipIds } from './utilities/data/validateRelationships.js';
 import { convertPayloadJoinsToContentAPI } from './utilities/joins.js';
 import { addFallbackLocale } from './utilities/locale/index.js';
 import { normalizeLocaleInWhere } from './utilities/meta/normalizeLocaleInWhere.js';
-import { buildDocumentSchema } from './utilities/schema/buildDocumentSchema.js';
+import { getDocumentSchema } from './utilities/schema/getDocumentSchema.js';
 import { convertPayloadWhereToContentAPI } from './utilities/where.js';
 /**
  * Heads-up logged locally whenever a job is queued. Queued jobs are executed by Figma's deployed runner, so
@@ -109,7 +110,7 @@ async function createCollection(collectionId) {
             }
         });
         if (error) {
-            throw createContentAPIError('createCollection', error, httpResponse.status);
+            throw createDocumentContentAPIError(this, 'createCollection', error, httpResponse.status, collectionId);
         }
         this.payload.logger.info(`Created collection: ${collectionId}`);
     } catch (error) {
@@ -131,13 +132,13 @@ async function findMany({ collection, joins, limit, locale: localeArg, page, pag
             limit,
             locale,
             page: page ?? 1,
-            schema: this.documentSchema,
+            schema: this.documentSchema(),
             sort: addFallbackSort(sort, this.payload, collection),
             where: convertPayloadWhereToContentAPI(normalizedWhere ?? {})
         }
     });
     if (error) {
-        throw createContentAPIError('findMany', error, httpResponse.status);
+        throw createDocumentContentAPIError(this, 'findMany', error, httpResponse.status, collection);
     }
     if (!response) {
         throw new Error('No response from findMany');
@@ -176,13 +177,13 @@ async function findVersions(args) {
             limit: args.limit,
             locale,
             page: args.page ?? 1,
-            schema: this.documentSchema,
+            schema: this.documentSchema(),
             sort: sortWithFallback,
             where: whereClause
         }
     });
     if (error) {
-        throw createContentAPIError('findVersions', error, httpResponse.status);
+        throw createDocumentContentAPIError(this, 'findVersions', error, httpResponse.status, args.collection);
     }
     if (!response) {
         throw new Error('No response from findVersions');
@@ -230,7 +231,7 @@ async function createVersion(args) {
         body: {
             collection: args.collectionSlug,
             contentSystemId: this.contentSystemId,
-            schema: this.documentSchema,
+            schema: this.documentSchema(),
             versionDoc: {
                 createdAt: args.createdAt,
                 latest: true,
@@ -241,7 +242,7 @@ async function createVersion(args) {
         }
     });
     if (error) {
-        throw createContentAPIError('createVersion', error, httpResponse.status);
+        throw createDocumentContentAPIError(this, 'createVersion', error, httpResponse.status, args.collectionSlug);
     }
     if (!response) {
         throw new Error('No response from createVersion');
@@ -272,7 +273,7 @@ async function updateVersion(args) {
             contentSystemId: this.contentSystemId,
             createOnMissing: false,
             locale,
-            schema: this.documentSchema,
+            schema: this.documentSchema(),
             versionDoc: {
                 createdAt: versionMeta.createdAt,
                 latest: versionMeta.latest,
@@ -284,7 +285,7 @@ async function updateVersion(args) {
         }
     });
     if (error) {
-        throw createContentAPIError('updateVersion', error, httpResponse.status);
+        throw createDocumentContentAPIError(this, 'updateVersion', error, httpResponse.status, args.collection);
     }
     if (!response?.result || !('data' in response.result)) {
         throw new Error('No document data in updateVersion response');
@@ -301,21 +302,25 @@ async function updateVersion(args) {
     });
 }
 async function deleteVersions(args) {
-    if (!args.collection) {
-        throw new Error('deleteVersions requires a collection');
+    // Globals are addressed by `globalSlug` and map to the `_global-<slug>` collection.
+    // Only one of `collection`/`globalSlug` is set.
+    const globalSlug = args.globalSlug != null ? getGlobalSlug(args.globalSlug) : undefined;
+    const collection = args.collection ?? globalSlug;
+    if (collection == null) {
+        throw new Error('deleteVersions requires a collection or globalSlug');
     }
     const locale = addFallbackLocale(args.locale, this.payload);
     const { error, response: httpResponse } = await this.client.POST('/api/v1/document_versions:delete', {
         body: {
-            collection: args.collection,
+            collection,
             contentSystemId: this.contentSystemId,
             locale,
-            schema: this.documentSchema,
+            schema: this.documentSchema(),
             where: convertPayloadWhereToContentAPI(args.where)
         }
     });
     if (error) {
-        throw createContentAPIError('deleteVersions', error, httpResponse.status);
+        throw createDocumentContentAPIError(this, 'deleteVersions', error, httpResponse.status, collection);
     }
 }
 async function findOne(args) {
@@ -339,13 +344,13 @@ async function findDistinct(args) {
             limit: args.limit,
             locale,
             page: args.page ?? 1,
-            schema: this.documentSchema,
+            schema: this.documentSchema(),
             sort: addFallbackSort(args.sort, this.payload, args.collection),
             where: convertPayloadWhereToContentAPI(args.where ?? {})
         }
     });
     if (error) {
-        throw createContentAPIError('findDistinct', error, httpResponse.status);
+        throw createDocumentContentAPIError(this, 'findDistinct', error, httpResponse.status, args.collection);
     }
     const { data, ...pagination } = response.result;
     return {
@@ -372,13 +377,13 @@ async function updateMany(args) {
             environmentName: this.environmentName,
             limit: args.limit,
             locale,
-            schema: this.documentSchema,
+            schema: this.documentSchema(),
             sort: addFallbackSort(args.sort || '-updatedAt', this.payload, args.collection),
             where: convertPayloadWhereToContentAPI(args.where)
         }
     });
     if (error) {
-        throw createContentAPIError('updateMany', error, httpResponse.status);
+        throw createDocumentContentAPIError(this, 'updateMany', error, httpResponse.status, args.collection);
     }
     if (!contentAPIResponse) {
         throw new Error('No response from updateMany');
@@ -413,12 +418,12 @@ async function updateOne(args) {
             doc: dataToContentAPI(this.payload, args.collection, args.data),
             environmentName: this.environmentName,
             locale,
-            schema: this.documentSchema,
+            schema: this.documentSchema(),
             where: convertPayloadWhereToContentAPI(where)
         }
     });
     if (error) {
-        throw createContentAPIError('updateOne', error, httpResponse.status);
+        throw createDocumentContentAPIError(this, 'updateOne', error, httpResponse.status, args.collection);
     }
     if (!contentAPIResponse) {
         throw new Error('No response from updateOne');
@@ -445,12 +450,12 @@ async function deleteMany(args) {
             contentSystemId: this.contentSystemId,
             environmentName: this.environmentName,
             locale,
-            schema: this.documentSchema,
+            schema: this.documentSchema(),
             where: convertPayloadWhereToContentAPI(args.where)
         }
     });
     if (error) {
-        throw createContentAPIError('deleteMany', error, httpResponse.status);
+        throw createDocumentContentAPIError(this, 'deleteMany', error, httpResponse.status, args.collection);
     }
 }
 async function deleteOne(args) {
@@ -461,12 +466,12 @@ async function deleteOne(args) {
             contentSystemId: this.contentSystemId,
             environmentName: this.environmentName,
             locale,
-            schema: this.documentSchema,
+            schema: this.documentSchema(),
             where: convertPayloadWhereToContentAPI(args.where)
         }
     });
     if (error) {
-        throw createContentAPIError('deleteOne', error, httpResponse.status);
+        throw createDocumentContentAPIError(this, 'deleteOne', error, httpResponse.status, args.collection);
     }
     if (!response?.result || !('data' in response.result)) {
         throw new Error('No document data in deleteOne response');
@@ -516,11 +521,11 @@ async function create(args) {
             },
             environmentName: this.environmentName,
             locale,
-            schema: this.documentSchema
+            schema: this.documentSchema()
         }
     });
     if (error) {
-        throw createContentAPIError('create', error, httpResponse.status);
+        throw createDocumentContentAPIError(this, 'create', error, httpResponse.status, args.collection);
     }
     if (!contentAPIResponse) {
         throw new Error('No response from create');
@@ -568,12 +573,12 @@ async function count(args) {
             collection: args.collection,
             contentSystemId: this.contentSystemId,
             locale,
-            schema: this.documentSchema,
+            schema: this.documentSchema(),
             where: convertPayloadWhereToContentAPI(args.where)
         }
     });
     if (error) {
-        throw createContentAPIError('count', error, httpResponse.status);
+        throw createDocumentContentAPIError(this, 'count', error, httpResponse.status, args.collection);
     }
     if (!response) {
         throw new Error('No response from count');
@@ -589,12 +594,12 @@ async function countVersions(args) {
             collection: args.collection,
             contentSystemId: this.contentSystemId,
             locale,
-            schema: this.documentSchema,
+            schema: this.documentSchema(),
             where: convertPayloadWhereToContentAPI(args.where)
         }
     });
     if (error) {
-        throw createContentAPIError('countVersions', error, httpResponse.status);
+        throw createDocumentContentAPIError(this, 'countVersions', error, httpResponse.status, args.collection);
     }
     if (!response) {
         throw new Error('No response from countVersions');
@@ -620,25 +625,31 @@ async function upsert(args) {
         data: args.data,
         payload: this.payload
     });
+    // `createdAt` is create-time metadata, so seed it on `createOnMissing` (used only when no
+    // document matches) rather than on `doc`. The server preserves an existing document's
+    // `createdAt` on update precisely because `doc` omits it; `updatedAt` is still refreshed on
+    // every write via `dataToContentAPI`. Sending `createdAt` on `doc` would overwrite it on
+    // every update (e.g. repeated `updateGlobal` calls).
+    const createdAt = new Date().toISOString();
     const { data: contentAPIResponse, error, response: httpResponse } = await this.client.POST('/api/v1/documents:update', {
         body: {
             collection: args.collection,
             contentSystemId: this.contentSystemId,
             createOnMissing: {
-                id: documentId
+                id: documentId,
+                createdAt
             },
             doc: dataToContentAPI(this.payload, args.collection, args.data, {
-                applyDefaults: true,
-                createdAt: true
+                applyDefaults: true
             }),
             environmentName: this.environmentName,
             locale,
-            schema: this.documentSchema,
+            schema: this.documentSchema(),
             where: convertPayloadWhereToContentAPI(args.where)
         }
     });
     if (error) {
-        throw createContentAPIError('upsert', error, httpResponse.status);
+        throw createDocumentContentAPIError(this, 'upsert', error, httpResponse.status, args.collection);
     }
     if (!contentAPIResponse) {
         throw new Error('No response from upsert');
@@ -658,6 +669,7 @@ async function upsert(args) {
     });
 }
 async function updateJobs(args) {
+    const collection = 'payload-jobs';
     const { id, limit, returning, sort, where } = args;
     if (id == null && where == null) {
         throw new Error('updateJobs requires either id or a where clause');
@@ -678,12 +690,12 @@ async function updateJobs(args) {
             equals: String(id)
         }
     } : where;
-    const docData = dataToContentAPI(this.payload, 'payload-jobs', data);
-    const sortClause = addFallbackSort(sort || '-updatedAt', this.payload, 'payload-jobs');
+    const docData = dataToContentAPI(this.payload, collection, data);
+    const sortClause = addFallbackSort(sort || '-updatedAt', this.payload, collection);
     const whereQuery = convertPayloadWhereToContentAPI(whereClause);
     const { data: response, error, response: httpResponse } = await this.client.POST('/api/v1/documents:update', {
         body: {
-            collection: 'payload-jobs',
+            collection,
             contentSystemId: this.contentSystemId,
             createOnMissing: false,
             doc: docData,
@@ -691,13 +703,13 @@ async function updateJobs(args) {
             ...limit != null && {
                 limit
             },
-            schema: this.documentSchema,
+            schema: this.documentSchema(),
             sort: sortClause,
             where: whereQuery
         }
     });
     if (error) {
-        throw createContentAPIError('updateJobs', error, httpResponse.status);
+        throw createDocumentContentAPIError(this, 'updateJobs', error, httpResponse.status, collection);
     }
     if (!response) {
         throw new Error('No response from updateJobs');
@@ -709,18 +721,18 @@ async function updateJobs(args) {
         return [];
     }
     return response.result.data.map((doc)=>unwrapDocument({
-            collectionSlug: 'payload-jobs',
+            collectionSlug: collection,
             doc,
             payload: this.payload
         }));
 }
-function createGlobal(args) {
+async function createGlobal(args) {
     // Globals are singletons identified by their slug. Use upsert so concurrent calls
     // (e.g. handleSchedules processing multiple queueables with the same null jobStats)
     // don't fail with "A record with this field already exists". The deep-merge semantics
     // of the update path are safe here: callers that want a fresh create (first run) get
     // an effective create, and callers that race a prior create get a merge instead.
-    return this.upsert({
+    const doc = await this.upsert({
         collection: getGlobalSlug(args.slug),
         data: {
             ...args.data,
@@ -732,6 +744,7 @@ function createGlobal(args) {
             }
         }
     });
+    return injectGlobalType(doc, args.slug);
 }
 async function findGlobal(args) {
     const doc = await this.findOne({
@@ -739,17 +752,10 @@ async function findGlobal(args) {
         locale: args.locale,
         where: args.where ?? {}
     });
-    if (doc != null) {
-        ;
-        doc.globalType = args.slug;
-    }
-    return doc;
+    return injectGlobalType(doc, args.slug);
 }
 async function updateGlobal(args) {
-    // TODO: upsert's `createOnMissing` path generates a new `createdAt` on every call,
-    // which overwrites the original timestamp on updates. The fix belongs in the Content API:
-    // `createOnMissing` should preserve `createdAt` on updates and only set it on creates.
-    return this.upsert({
+    const doc = await this.upsert({
         collection: getGlobalSlug(args.slug),
         data: args.data,
         where: {
@@ -758,6 +764,7 @@ async function updateGlobal(args) {
             }
         }
     });
+    return injectGlobalType(doc, args.slug);
 }
 // TODO: remove Omit when this PR is released: https://github.com/payloadcms/payload/pull/15183
 function findGlobalVersions(args) {
@@ -809,6 +816,13 @@ function countGlobalVersions(args) {
         where: args.where
     });
 }
+function createDocumentContentAPIError(adapter, operation, error, status, collectionSlug) {
+    const validationError = maybeCreateUniqueValidationError(error, collectionSlug, adapter);
+    if (validationError != null) {
+        return validationError;
+    }
+    return createContentAPIError(operation, error, status);
+}
 function createContentAPIError(operation, error, status) {
     return new APIError(`Content API ${operation} error: ${error.message}`, status, {
         code: error.code,
@@ -816,6 +830,27 @@ function createContentAPIError(operation, error, status) {
         field: error.field
     });
 }
+// A unique-constraint violation from the Content API is Payload's `ValidationError` contract:
+// reconstruct it with the offending field path(s) so callers can map the error back to a field
+// (matching what Payload's other database adapters throw). Falls back to a generic APIError when
+// the collection or offending field is unknown.
+function maybeCreateUniqueValidationError(error, collectionSlug, adapter) {
+    if (error.constraint !== 'unique_constraint') {
+        return null;
+    }
+    const paths = (error.field ?? '').split(',').map((path)=>path.trim()).filter((path)=>path.length > 0);
+    if (paths.length === 0) {
+        adapter.payload.logger.error(`Unique constraint violation but no offending field.`);
+        return null;
+    }
+    return new ValidationError({
+        collection: collectionSlug,
+        errors: paths.map((path)=>({
+                message: error.message,
+                path
+            }))
+    });
+}
 export const contentAPIAdapter = (opts)=>({
         name: 'content-api',
         defaultIDType: 'text',
@@ -855,7 +890,7 @@ export const contentAPIAdapter = (opts)=>({
                 deleteMany: deleteMany,
                 deleteOne: deleteOne,
                 deleteVersions: deleteVersions,
-                documentSchema: buildDocumentSchema(payload.config),
+                documentSchema: ()=>getDocumentSchema(payload.config),
                 environmentName: opts.environmentName,
                 find: find,
                 findDistinct: findDistinct,

package/dist/db-content-api/utilities/data/injectGlobalType.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Payload expects globals to carry a `globalType` (their slug) alongside the stored data.
+ * Globals are stored as `_global-<slug>` collections that have no such column, so the adapter
+ * attaches it to every global document it returns.
+ */
+export declare function injectGlobalType<T>(doc: T, slug: string): T;

package/dist/db-content-api/utilities/data/injectGlobalType.js

@@ -0,0 +1,11 @@
+import { isRecord } from '../isRecord.js';
+/**
+ * Payload expects globals to carry a `globalType` (their slug) alongside the stored data.
+ * Globals are stored as `_global-<slug>` collections that have no such column, so the adapter
+ * attaches it to every global document it returns.
+ */ export function injectGlobalType(doc, slug) {
+    return isRecord(doc) ? {
+        ...doc,
+        globalType: slug
+    } : doc;
+}

package/dist/db-content-api/utilities/data/stringifyNumericIds.d.ts

@@ -0,0 +1 @@
+export declare function stringifyNumericIds(value: unknown): unknown;

package/dist/db-content-api/utilities/data/stringifyNumericIds.js

@@ -0,0 +1,19 @@
+// The Content API stores every document id as a string, but Payload keeps a
+// collection's custom numeric id as a `number`. Stringify numbers so an id filter
+// matches the stored value.
+// Has two shapes it accepts:
+// - Scalar values (most operators)
+// - Arrays of values (for `in`/`not_in` operators)
+// Non-numeric entries (already-string ids) pass through untouched.
+export function stringifyNumericIds(value) {
+    if (typeof value === 'number') {
+        return stringifyNumericId(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry)=>stringifyNumericId(entry));
+    }
+    return value;
+}
+function stringifyNumericId(value) {
+    return typeof value === 'number' ? String(value) : value;
+}

package/dist/db-content-api/utilities/isRecord.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A plain, string-keyed object — the shape that can safely be spread and have
+ * properties read off it without tripping over arrays, `null`, or exotic objects.
+ *
+ * Objects carrying symbol-keyed own properties are rejected: symbol keys are how
+ * libraries tag a value as something more than data, and a spread copies only the
+ * string keys, so treating such a value as a record silently strips the tag.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/db-content-api/utilities/isRecord.js

@@ -0,0 +1,19 @@
+/**
+ * A plain, string-keyed object — the shape that can safely be spread and have
+ * properties read off it without tripping over arrays, `null`, or exotic objects.
+ *
+ * Objects carrying symbol-keyed own properties are rejected: symbol keys are how
+ * libraries tag a value as something more than data, and a spread copies only the
+ * string keys, so treating such a value as a record silently strips the tag.
+ */ export function isRecord(value) {
+    if (value == null) {
+        return false;
+    }
+    if (typeof value !== 'object') {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return false;
+    }
+    return Object.getOwnPropertySymbols(value).length === 0;
+}

package/dist/db-content-api/utilities/schema/getDocumentSchema.d.ts

@@ -0,0 +1,3 @@
+import type { Config, SanitizedConfig } from 'payload';
+import type { DocumentSchemaWire } from './buildDocumentSchema.js';
+export declare function getDocumentSchema(config: Config | SanitizedConfig): DocumentSchemaWire;

package/dist/db-content-api/utilities/schema/getDocumentSchema.js

@@ -0,0 +1,24 @@
+import { buildDocumentSchema } from './buildDocumentSchema.js';
+// The schema built by `getDocumentSchema`, keyed by the config it was built from.
+// Weakly held so a config discarded by HMR takes its schema with it.
+let schemaByConfig = new WeakMap();
+// Retrieves a document schema for the given config, building it if necessary.
+// The last output is memoized, so if this config matches the last config we just return
+// the previous output instead of rebuilding it.
+export function getDocumentSchema(config) {
+    const existing = schemaByConfig.get(config);
+    if (existing != null) {
+        return existing;
+    }
+    const schema = buildDocumentSchema(config);
+    // Clear the cache of any previous config, so only the most recent one is held.
+    // This ensures that we never accidentally leak memory by holding on to more
+    // and more schemas if the configs are never garbage collected.
+    schemaByConfig = new WeakMap([
+        [
+            config,
+            schema
+        ]
+    ]);
+    return schema;
+}

package/dist/db-content-api/utilities/where.js

@@ -1,3 +1,4 @@
+import { stringifyNumericIds } from './data/stringifyNumericIds.js';
 export function convertPayloadWhereToContentAPI(where, options = {}) {
     // Empty where {} should be { and: [] } not undefined
     // Content API requires a where clause structure even for "no filter"
@@ -42,7 +43,7 @@ export function convertPayloadWhereToContentAPI(where, options = {}) {
                 conditions.push({
                     operator: 'equals',
                     path: fieldPath,
-                    value: fieldPath === 'id' && typeof value === 'number' ? String(value) : value
+                    value: fieldPath === 'id' ? stringifyNumericIds(value) : value
                 });
                 continue;
             }
@@ -69,9 +70,10 @@ export function convertPayloadWhereToContentAPI(where, options = {}) {
                 }
                 // Content API stores all document IDs as strings.
                 // Payload sends numeric values for collections with custom numeric ID fields,
-                // so we must stringify to match.
-                if (fieldPath === 'id' && typeof finalValue === 'number') {
-                    finalValue = String(finalValue);
+                // so we must stringify to match. This includes the `in`/`not_in` arrays that
+                // Payload's relationship-population dataloader always uses ({ id: { in: [...] } }).
+                if (fieldPath === 'id') {
+                    finalValue = stringifyNumericIds(finalValue);
                 }
                 conditions.push({
                     operator: op,

package/dist/exports/client.d.ts

@@ -2,3 +2,5 @@ export { FigmaAvatar } from '../oauth/components/FigmaAvatar/index.js';
 export { FigmaAvatarCell } from '../oauth/components/FigmaAvatarCell/index.js';
 export { DefaultLoginButton } from '../oauth/components/LoginButton/index.js';
 export { LogoutButton } from '../oauth/components/LogoutButton/index.js';
+export { FigmaCloudLimitProvider } from '../plugin/cloud-limits/CloudLimitProvider/index.js';
+export { FigmaCloudLimitSlugTracker } from '../plugin/cloud-limits/SlugTracker/index.js';

package/dist/exports/client.js

@@ -2,3 +2,5 @@ export { FigmaAvatar } from '../oauth/components/FigmaAvatar/index.js';
 export { FigmaAvatarCell } from '../oauth/components/FigmaAvatarCell/index.js';
 export { DefaultLoginButton } from '../oauth/components/LoginButton/index.js';
 export { LogoutButton } from '../oauth/components/LogoutButton/index.js';
+export { FigmaCloudLimitProvider } from '../plugin/cloud-limits/CloudLimitProvider/index.js';
+export { FigmaCloudLimitSlugTracker } from '../plugin/cloud-limits/SlugTracker/index.js';

package/dist/lib/write-agent-config.d.ts

@@ -0,0 +1,12 @@
+export type WriteAgentConfigResult = {
+    agentsMd: 'appended' | 'created' | 'unchanged';
+    claudeMd: 'appended' | 'created' | 'unchanged';
+};
+/**
+ * Write the root AI-agent pointer files so assistants can find the Payload
+ * skill bundled in node_modules. Idempotent: creates when absent, appends the
+ * pointer when a file exists without it, and no-ops when already present.
+ */
+export declare function writeAgentConfigFiles(args: {
+    projectDir: string;
+}): Promise<WriteAgentConfigResult>;

package/dist/lib/write-agent-config.js

@@ -0,0 +1,52 @@
+import fs from 'fs/promises';
+import path from 'path';
+const SKILL_POINTER_PATH = 'node_modules/payload/skills/payload/SKILL.md';
+const AGENTS_BLOCK = `# AI Agent
+
+For any Payload-related work, reference the skill at
+\`${SKILL_POINTER_PATH}\`.
+`;
+const CLAUDE_IMPORT = '@AGENTS.md';
+/**
+ * Write the root AI-agent pointer files so assistants can find the Payload
+ * skill bundled in node_modules. Idempotent: creates when absent, appends the
+ * pointer when a file exists without it, and no-ops when already present.
+ */ export async function writeAgentConfigFiles(args) {
+    const agentsMd = await ensureFileContains({
+        content: AGENTS_BLOCK,
+        filePath: path.join(args.projectDir, 'AGENTS.md'),
+        marker: SKILL_POINTER_PATH
+    });
+    const claudeMd = await ensureFileContains({
+        content: `${CLAUDE_IMPORT}\n`,
+        filePath: path.join(args.projectDir, 'CLAUDE.md'),
+        marker: CLAUDE_IMPORT
+    });
+    return {
+        agentsMd,
+        claudeMd
+    };
+}
+async function ensureFileContains(args) {
+    const existing = await readFileOrNull(args.filePath);
+    if (existing === null) {
+        await fs.writeFile(args.filePath, args.content, 'utf8');
+        return 'created';
+    }
+    if (existing.includes(args.marker)) {
+        return 'unchanged';
+    }
+    const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+    await fs.writeFile(args.filePath, `${existing}${separator}${args.content}`, 'utf8');
+    return 'appended';
+}
+async function readFileOrNull(filePath) {
+    try {
+        return await fs.readFile(filePath, 'utf8');
+    } catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            return null;
+        }
+        throw err;
+    }
+}