import type { Pool } from 'pg'; import type { FieldDescriptor, MetafieldDefinition, MetafieldType, Validation } from './types.js'; /** * Theme-declared metafield definition — the `theme.json` * `metafieldDefinitions[]` entry shape. Field names follow the lib's * FieldDescriptor (`key`/`type`), NOT the REST API's `fieldKey`/`fieldType`. * * `required` is deliberately absent from the supported surface: seeding a * required definition would make `validateMetafields` reject EVERY entity * save store-wide until values are backfilled, so the validator refuses it. */ export interface ManifestMetafieldDefinition { ownerType: string; namespace: string; key: string; name: string; description?: string; type: MetafieldType; isList?: boolean; required?: boolean; translatable?: boolean; visibleToCustomer?: boolean; validations?: Validation[]; subFields?: FieldDescriptor[]; appearance?: Record; } export interface ManifestDefinitionIssue { /** Index into the metafieldDefinitions array; -1 for array-level issues. */ index: number; message: string; } export interface ProvisionConflictDetail { field: 'type' | 'isList'; declared: unknown; incumbent: unknown; } export interface ProvisionResult { /** 'owner.namespace.key' refs, per outcome. */ seeded: string[]; adopted: string[]; /** Report-only (no stored state): definitions attributed to this theme * that its current manifest no longer declares — left in place. */ retired: string[]; conflicts: Array<{ ref: string; details: ProvisionConflictDetail[]; }>; warnings: ManifestDefinitionIssue[]; errors: ManifestDefinitionIssue[]; /** True when the attribution column doesn't exist yet (unmigrated DB — * e.g. `theme:active` before the server ever booted this core version). */ skipped: boolean; } /** * Owners with the full metafield wiring (meta_data column, write path, prune * subscriber, storefront GraphQL, admin card). `owner_type` itself is an open * varchar, so other strings are accepted — but a definition for an unwired * owner is silently inert, hence the lint warning. */ export declare const WIRED_METAFIELD_OWNERS: readonly string[]; export declare function refOf(d: { ownerType: string; namespace: string; key: string; }): string; /** * Strict validation of a theme.json `metafieldDefinitions[]` array. * `compileField` is NOT a manifest validator (unknown types compile to `{}`, * an empty group only dies at the DB CHECK), so structure is checked by a * strict schema first; compileField runs after as the depth-cap sanity check. * * Errors block activation; warnings are advisory (printed by the CLI / * carried in the provision result). */ export declare function validateManifestMetafieldDefinitions(entries: unknown): { errors: ManifestDefinitionIssue[]; warnings: ManifestDefinitionIssue[]; }; /** * JSON.stringify with recursively sorted object keys — Postgres JSONB does * NOT preserve key order (keys come back sorted by length then bytewise), so * a naive stringify comparison of declared-vs-stored validations/subFields * reports false drift on every re-provision. */ export declare function stableStringify(value: unknown): string; export type IncumbentClassification = { kind: 'identical'; } | { kind: 'mutable-drift'; fields: string[]; } | { kind: 'immutable-conflict'; details: ProvisionConflictDetail[]; }; /** * Compare a declared entry against the existing definition row under the same * (ownerType, namespace, key). Immutable mismatch (type / isList) can never * converge — `updateMetafieldDefinition` rejects those fields — so it's a * conflict; mutable differences are reported as drift and kept (no * auto-PATCH: silently tightening validations can break unrelated saves). */ export declare function classifyIncumbent(declared: ManifestMetafieldDefinition, incumbent: MetafieldDefinition): IncumbentClassification; /** * Reduce a live definition (as mutated by the admin REST surface, whose * payload schemas accept unconstrained validations/subFields arrays) to the * strict manifest shape — `theme:export` must never write a manifest that its * own validation then rejects, blocking activation of the exported theme. * Returns null when the definition can't be expressed in the manifest schema. */ export declare function sanitizeForManifest(def: MetafieldDefinition): ManifestMetafieldDefinition | null; /** * True when the `provisioned_by_theme` attribution column exists — false on * a DB that hasn't run this core version's migrations yet (theme CLI before * the server ever booted). Callers degrade gracefully instead of erroring. */ export declare function provisioningAvailable(pool: Pool): Promise; /** * Ensure a theme's declared metafield definitions exist — idempotent, always * safe to re-run. Runs at `theme:active` and at every server boot (after * migrations), in its OWN transaction — deliberately not inside the theme * installer's: three installer branches commit-and-return early (no-op, * rejected, fresh install) and the ensure must run regardless of the widget * SemVer outcome. * * Per declared entry: * - missing → `INSERT … ON CONFLICT DO NOTHING RETURNING` (atomic; the * check-then-insert `createMetafieldDefinition` service is racy), stamped * `provisioned_by_theme`, + a `metafield_definition_created` event on the * same connection. * - present, immutables match → adopt; claim attribution only when the row * is unowned (`provisioned_by_theme IS NULL`) — first seeder wins. * Mutable drift is warned and kept. * - present, immutables differ → conflict; reported, never applied, never * claimed. * "Retired" (attributed to this theme but no longer declared) is a READ-TIME * REPORT — no stored state, nothing to flip; the definitions stay in place. */ export declare function provisionThemeMetafields(themeId: string, entries: ManifestMetafieldDefinition[], pool: Pool): Promise;