@notambourine/metafields 0.0.7 → 0.1.0

package/README.md

@@ -1,8 +1,13 @@
 # @notambourine/metafields
 
-Declare merchant-owned Shopify metafield and metaobject definitions in TypeScript, inspect drift,
-and create only what is missing. Schema sync creates and never updates; `--repair` is the one
-opt-in that rewrites a definition, and nothing deletes one.
+Declare Shopify metafield and metaobject definitions in TypeScript, inspect store drift, and apply
+controlled changes. The CLI never deletes or retypes a definition.
+
+Requires Node.js 22.18 or newer.
+
+## Quick start
+
+Create `schema.ts`:
 
 ```ts
 import { defineSchema, field, metaobject } from '@notambourine/metafields';
@@ -29,141 +34,142 @@ export default defineSchema({
 });
 ```
 
+Validate it, inspect a store, then apply the plan:
+
 ```sh
 npx @notambourine/metafields ./schema.ts --validate
 npx @notambourine/metafields ./schema.ts --store example.myshopify.com
 npx @notambourine/metafields ./schema.ts --store example.myshopify.com --apply
-npx @notambourine/metafields ./schema.ts --store example.myshopify.com --check
 ```
 
-The default command is a dry run. Importing a TypeScript schema executes trusted local code, so
-compile declarations to canonical JSON before a secret-bearing workflow consumes pull-request
-output.
-
-Schema modules use Node's built-in type stripping and must use erasable TypeScript syntax.
+Schema modules run as trusted local code through Node's type stripping. Use erasable TypeScript
+syntax. Compile untrusted pull-request declarations before a credentialed workflow consumes them:
 
-See `metafields --help` for `pull`, `compile`, `emit`, and migration commands.
+```sh
+npx @notambourine/metafields compile ./schema.ts --out ./schema.json
+```
 
-## Auth
+Every command accepts `--json` and answers with a single JSON object on stdout, carrying the
+identities it left out under `excluded` or `skipped`. Without `--json`, the document goes to
+stdout and those identities to stderr, so stdout stays pipeable. Writing to `--out` reports
+`{"status":"written","out":"..."}` instead of the document.
 
-Set `SHOPIFY_APP_CLIENT_ID` (or pass `--client-id`) and `SHOPIFY_APP_SECRET`, and the CLI mints a
-short-lived Admin token per store with the `client_credentials` grant. Two grant errors stay
-distinct in the output because a fleet treats them differently: `app_not_installed` means the store
-has not installed the app, `shop_not_permitted` means the app and the store are in different
-organizations.
+## Changes and safety
 
-`SHOPIFY_ADMIN_ACCESS_TOKEN` still works and reaches one store; app auth is an option, not a
-requirement. Complete app credentials win when both are set, and half-set ones fall back to the
-token rather than failing. Only a fleet, which one token cannot reach, requires the app.
+Without `--apply`, the CLI only reports drift. A definition is updated as one unit: if any part is
+blocked or needs `--force`, its other changes wait too. Other definitions continue independently.
 
-Minted tokens are never logged, and Shopify credential prefixes are redacted from errors.
+| Change | Required mode |
+| --- | --- |
+| Create a definition or add a metaobject field | `--apply` |
+| Update labels, `displayNameKey`, or enable a capability | `--apply` |
+| Change access, validations, constraints, or `required` | `--apply --force` |
+| Disable a capability | `--apply --force` |
+| Delete or retype a definition | Never performed |
+| Change invalid values or a definition Shopify is still validating | Never performed |
 
-## Repair
+`--force` opts into changes that can break a storefront or strand stored values. For schema sync it
+requires `--apply`; it cannot override Shopify constraints or repair data.
 
-`--repair` issues the update mutations that resolve drift a plan reported as `CONFLICT`. It is
-never implied by `--apply`, so the only way a definition is rewritten is a human typing the flag.
-Without `--apply` it is a dry run that reports exactly what it would change.
+Use `--dry-run` to cancel requested writes while preserving the plan and exit code:
 
 ```sh
-metafields ./schema.ts --store example.myshopify.com --repair
-metafields ./schema.ts --store example.myshopify.com --repair --apply
+npx @notambourine/metafields ./schema.ts \
+  --store example.myshopify.com --apply --force --dry-run
 ```
 
-Repairable: `required`, storefront `access`, `capabilities`, `validations`, `constraints`,
-metaobject `displayNameKey`, and a field missing from an existing metaobject.
+Exit codes describe the result:
 
-Reported and skipped, never attempted:
+- `0`: the store matches the schema.
+- `1`: actionable drift remains.
+- `2`: input is invalid, Shopify state is indeterminate, or an operation failed.
 
-- A `type` that differs. Shopify will not retype a definition that has stored values; that is what
-  the migration commands are for.
-- Invalid stored values (`validationStatus: SOME_INVALID`). That is data, not shape.
-- Anything `INDETERMINATE`, meaning validation is still in progress. Wait, do not write.
+Cosmetic label drift does not change the exit code. Mutations retry Shopify's explicit
+`THROTTLED` response, but are not retried after a timeout or `5xx` because the first request may
+have landed.
 
-A definition with any of those is skipped whole, so a partial update never reads like progress. It
-also keeps blocking writes to the fleet, the same as a conflict without `--repair`.
+## Authentication
 
-Shopify refuses `required: true` on a field whose existing entries are blank. That `userErrors`
-message is surfaced intact, because the operator needs to know which entries to fill.
+For one store, set an Admin API token:
 
-## Fleets
+```sh
+export SHOPIFY_ADMIN_ACCESS_TOKEN=...
+```
 
-`--store` repeats, and `--stores-from <file>` sweeps a list of stores, one per line, with `#`
-comments:
+For one store or a fleet, set app credentials. The CLI mints a short-lived token for each store:
 
 ```sh
-metafields ./schema.ts --store flagship.myshopify.com --stores-from ./stores.txt --apply
+export SHOPIFY_APP_CLIENT_ID=...
+export SHOPIFY_APP_SECRET=...
 ```
 
-- Every store is planned before any store is written to. Drift on one store that a repair cannot
-  resolve exits nonzero having written nothing, because writing to the others first half-applies
-  the fleet.
-- A swept store that cannot be reached is reported and does not abort the run, as long as one store
-  could be planned. A swept store that has not installed the app is reported as `NOT-INSTALLED` and
-  keeps the run green.
-- A store named on the command line never fails quietly; only a swept store is downgraded.
-- Writes run per store, so one store refusing does not stop the next, and every refusal is
-  reported together.
-- Exit is `2` if any store was unreachable or refused a write, even when every reached store came
-  back clean.
+The client ID is resolved from `--client-id`, then `--app-config`, then
+`SHOPIFY_APP_CLIENT_ID`. The secret is read only from `SHOPIFY_APP_SECRET`.
 
-## Types
+```sh
+npx @notambourine/metafields ./schema.ts \
+  --app-config ./shopify.app.toml --store example.myshopify.com --apply
+```
 
-The schema is the single declaration. Value types come back out of it with `InferMetafields` and
-`InferMetaobjects`, and fields declared `required: true` are not optional in the inferred type:
+`--app-config` reads only the top-level `client_id`. Complete app credentials take priority over a
+static token; incomplete app credentials fall back to the token. Credentials are redacted from
+errors.
 
-```ts
-type Product = InferMetafields<typeof schema>['product'];
+## Fleets
+
+Repeat `--store` or load one store per line from a file. Lines beginning with `#` are ignored.
 
-const promo: string | undefined = product.custom.promo_text;
-const sku: string = product.custom.sku; // declared required
+```sh
+npx @notambourine/metafields ./schema.ts \
+  --store flagship.myshopify.com --stores-from ./stores.txt --apply
 ```
 
-## Liquid
+Each store is planned against the same schema. One store refusing a write does not stop the others.
+A store named directly fails loudly; a swept store without the app is reported as `NOT-INSTALLED`
+without failing the fleet. Other unreachable stores and rejected writes exit `2`.
+
+## Pull and generated output
 
-`emit --liquid` writes `.shopify/metafields.json`, the file Shopify's Liquid language server reads
-to complete and hover `product.metafields.custom.promo_text`:
+Pull existing definitions into a new schema file:
 
 ```sh
-metafields emit ./schema.ts --liquid --out .shopify/metafields.json
+npx @notambourine/metafields pull \
+  --store example.myshopify.com \
+  --owner product \
+  --namespace custom \
+  --metaobjects \
+  --out schema.ts
 ```
 
-Generating it from the schema means completions work without a store login, and cover definitions
-that are declared but not yet created. This drives editor assistance only: no theme-check rule
-validates metafields, so nothing here fails a build.
+Owners and namespaces must be explicit unless their corresponding `--all-owners` or
+`--all-namespaces` flag is passed. The output path must not exist; omit `--out` to write to stdout.
 
-The file's shape carries less than the schema does. It has no field for `required`, validations, or
-access, it cannot represent metaobject definitions, and it has no group for `customer` or
-`draft_order` metafields, which are reported as skipped. Treat it as a generated artifact: `emit`
-replaces an existing one and refuses to overwrite a file it did not generate. Shopify's own
-`shopify theme metafields pull` overwrites the same path, so do not hand-edit it.
+Generate Liquid editor metadata from the schema:
 
-## Behavior
+```sh
+npx @notambourine/metafields emit ./schema.ts \
+  --liquid --out .shopify/metafields.json
+```
 
-- Dry run reports missing definitions without writing them.
-- `--apply` creates missing metaobject definitions in dependency order, then metafield definitions.
-- `--check` exits nonzero for missing or incompatible operational shape.
-- Cosmetic name and description drift is reported but never changed.
-- Existing definitions, values, and entries are never updated or deleted by schema sync. Only
-  `--repair` updates one, and nothing deletes a definition or a field under any flag.
-- A description over 255 characters fails `--validate` and fails sync before the first request,
-  listing every offender at once. The Admin API answers `TOO_LONG`, and one create rejected
-  mid-run leaves a store half-applied behind an error that reads transient.
+The generated file supports Liquid completion and hover without a store login. It cannot represent
+metaobjects, `required`, validations, access, customer metafields, or draft-order metafields.
+`emit` refuses to replace a file it did not generate unless passed `--force`.
 
-Exit `0` means the selected condition is satisfied, exit `1` means schema or migration drift, and
-exit `2` means invalid input, indeterminate Shopify state, or an API failure.
+## Types
 
-`pull` requires explicit owners and namespaces:
+Infer application types from the schema. Required declarations remain required:
 
-```sh
-metafields pull --store example.myshopify.com \
-  --owner product --namespace custom --metaobjects --out schema.ts
-```
+```ts
+import type { InferMetafields, InferMetaobjects } from '@notambourine/metafields';
+import schema from './schema.js';
 
-The output path must not exist. Without `--out`, the generated module is written to stdout.
+type ProductMetafields = InferMetafields<typeof schema>['product'];
+type Faq = InferMetaobjects<typeof schema>['faq'];
+```
 
 ## Migrations
 
-Migrations are declarative, copy-only, and compiled before credentials are introduced:
+Migrations copy values to a new definition. They never retype or delete the source.
 
 ```ts
 import { defineMigration, transforms } from '@notambourine/metafields';
@@ -184,11 +190,30 @@ export default defineMigration({
 });
 ```
 
+Compile before introducing credentials, inspect the plan, then apply it:
+
 ```sh
-metafields compile ./migration.ts --out ./migration.json
-metafields migrate ./migration.json --store example.myshopify.com
-metafields migrate ./migration.json --store example.myshopify.com --apply
+npx @notambourine/metafields compile ./migration.ts --out ./migration.json
+npx @notambourine/metafields migrate ./migration.json --store example.myshopify.com
+npx @notambourine/metafields migrate ./migration.json --store example.myshopify.com --apply
 ```
 
-`0.0.x` is prerelease quality. Confirm owner scopes and behavior against a development store before
-production use.
+Migration exit code `1` means rows remain pending.
+
+## API compatibility
+
+`doctor` checks that Shopify still serves the selected API version and that the package's generated
+metafield type table matches it. It needs no store or credentials.
+
+```sh
+npx @notambourine/metafields doctor
+npx @notambourine/metafields doctor --api-version 2026-07 --json
+```
+
+An unsupported version or changed type table is a failed check. An unreachable Shopify registry is
+indeterminate and exits `2`.
+
+Run `npx @notambourine/metafields --help` for the complete CLI reference.
+
+This `0.x` release is prerelease quality. Confirm scopes and behavior against a development store
+before production use.

package/dist/admin-shapes.d.ts

@@ -0,0 +1,57 @@
+import type { ExistingField, ExistingMetafield, ExistingMetaobject } from './planner.js';
+export interface RawField {
+    key: string;
+    name: string;
+    description?: string | null;
+    type: {
+        name: string;
+    };
+    required?: boolean;
+    validations: {
+        name: string;
+        value: string;
+    }[];
+}
+export interface RawMetafield extends RawField {
+    id: string;
+    namespace: string;
+    ownerType: string;
+    access: Record<string, string | null>;
+    capabilities: Record<string, {
+        enabled: boolean;
+    }>;
+    constraints?: {
+        key: string | null;
+        values: {
+            nodes: {
+                value: string;
+            }[];
+        };
+    } | null;
+    validationStatus: ExistingMetafield['validationStatus'];
+    invalidCount: number;
+}
+export interface RawMetaobject {
+    id: string;
+    type: string;
+    name: string;
+    description?: string | null;
+    displayNameKey?: string | null;
+    access: Record<string, string | null>;
+    capabilities: {
+        publishable: {
+            enabled: boolean;
+        };
+        translatable: {
+            enabled: boolean;
+        };
+    };
+    fieldDefinitions: RawField[];
+}
+export declare function mapField(value: RawField): ExistingField;
+export declare function mapMetafield(value: RawMetafield): ExistingMetafield;
+export declare function mapMetaobject(value: RawMetaobject): ExistingMetaobject;
+export declare const FIELD_SELECTION = "\n  key name description type { name } required validations { name value }\n";
+export declare const METAFIELD_SELECTION = "\n  id namespace key ownerType name description type { name }\n  validations { name value }\n  access { admin storefront customerAccount }\n  capabilities {\n    adminFilterable { enabled }\n    analyticsQueryable { enabled }\n    cartToOrderCopyable { enabled }\n    smartCollectionCondition { enabled }\n    uniqueValues { enabled }\n  }\n  constraints { key values(first: 250) { nodes { value } } }\n  validationStatus\n  invalidCount: metafieldsCount(validationStatus: INVALID)\n";
+export declare const METAOBJECT_SELECTION = "\n  id type name description displayNameKey\n  access { admin storefront }\n  capabilities { publishable { enabled } translatable { enabled } }\n  fieldDefinitions { \n  key name description type { name } required validations { name value }\n }\n";
+//# sourceMappingURL=admin-shapes.d.ts.map

package/dist/admin-shapes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-shapes.d.ts","sourceRoot":"","sources":["../src/admin-shapes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEzF,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACtC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACnD,WAAW,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE;YAAE,KAAK,EAAE;gBAAE,KAAK,EAAE,MAAM,CAAA;aAAE,EAAE,CAAA;SAAE,CAAA;KAAE,GAAG,IAAI,CAAC;IACpF,gBAAgB,EAAE,iBAAiB,CAAC,kBAAkB,CAAC,CAAC;IACxD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACtC,YAAY,EAAE;QAAE,WAAW,EAAE;YAAE,OAAO,EAAE,OAAO,CAAA;SAAE,CAAC;QAAC,YAAY,EAAE;YAAE,OAAO,EAAE,OAAO,CAAA;SAAE,CAAA;KAAE,CAAC;IACxF,gBAAgB,EAAE,QAAQ,EAAE,CAAC;CAC9B;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,aAAa,CASvD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,iBAAiB,CAcnE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,kBAAkB,CActE;AAID,eAAO,MAAM,eAAe,iFAE3B,CAAC;AAEF,eAAO,MAAM,mBAAmB,weAc/B,CAAC;AAEF,eAAO,MAAM,oBAAoB,2PAKhC,CAAC"}

package/dist/admin-shapes.js

@@ -0,0 +1,67 @@
+export function mapField(value) {
+    return {
+        key: value.key,
+        name: value.name,
+        description: value.description,
+        type: value.type,
+        required: value.required,
+        validations: value.validations,
+    };
+}
+export function mapMetafield(value) {
+    return {
+        ...mapField(value),
+        id: value.id,
+        namespace: value.namespace,
+        ownerType: value.ownerType,
+        access: value.access,
+        capabilities: Object.fromEntries(Object.entries(value.capabilities).map(([key, item]) => [key, item.enabled])),
+        constraints: value.constraints
+            ? { key: value.constraints.key, values: value.constraints.values.nodes.map((item) => item.value) }
+            : null,
+        validationStatus: value.validationStatus,
+        invalidCount: value.invalidCount,
+    };
+}
+export function mapMetaobject(value) {
+    return {
+        id: value.id,
+        type: value.type,
+        name: value.name,
+        description: value.description,
+        displayNameKey: value.displayNameKey,
+        access: value.access,
+        capabilities: {
+            publishable: value.capabilities.publishable.enabled,
+            translatable: value.capabilities.translatable.enabled,
+        },
+        fields: value.fieldDefinitions.map(mapField),
+    };
+}
+// Read and pull select the same definitions, so the selections live with the shapes they decode:
+// a capability Shopify adds is then one edit, not two that can silently disagree.
+export const FIELD_SELECTION = `
+  key name description type { name } required validations { name value }
+`;
+export const METAFIELD_SELECTION = `
+  id namespace key ownerType name description type { name }
+  validations { name value }
+  access { admin storefront customerAccount }
+  capabilities {
+    adminFilterable { enabled }
+    analyticsQueryable { enabled }
+    cartToOrderCopyable { enabled }
+    smartCollectionCondition { enabled }
+    uniqueValues { enabled }
+  }
+  constraints { key values(first: 250) { nodes { value } } }
+  validationStatus
+  invalidCount: metafieldsCount(validationStatus: INVALID)
+`;
+export const METAOBJECT_SELECTION = `
+  id type name description displayNameKey
+  access { admin storefront }
+  capabilities { publishable { enabled } translatable { enabled } }
+  fieldDefinitions { ${FIELD_SELECTION} }
+`;
+//# sourceMappingURL=admin-shapes.js.map

package/dist/admin-shapes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-shapes.js","sourceRoot":"","sources":["../src/admin-shapes.ts"],"names":[],"mappings":"AAiCA,MAAM,UAAU,QAAQ,CAAC,KAAe;IACtC,OAAO;QACL,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,WAAW,EAAE,KAAK,CAAC,WAAW;KAC/B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAmB;IAC9C,OAAO;QACL,GAAG,QAAQ,CAAC,KAAK,CAAC;QAClB,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,YAAY,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAC9G,WAAW,EAAE,KAAK,CAAC,WAAW;YAC5B,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;YAClG,CAAC,CAAC,IAAI;QACR,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;QACxC,YAAY,EAAE,KAAK,CAAC,YAAY;KACjC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAoB;IAChD,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,YAAY,EAAE;YACZ,WAAW,EAAE,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,OAAO;YACnD,YAAY,EAAE,KAAK,CAAC,YAAY,CAAC,YAAY,CAAC,OAAO;SACtD;QACD,MAAM,EAAE,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC;KAC7C,CAAC;AACJ,CAAC;AAED,iGAAiG;AACjG,kFAAkF;AAClF,MAAM,CAAC,MAAM,eAAe,GAAG;;CAE9B,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;CAclC,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;uBAIb,eAAe;CACrC,CAAC"}

package/dist/admin.d.ts

@@ -1,6 +1,6 @@
 import type { CanonicalMetafield, CanonicalMetaobject, CompiledSchema } from './schema.js';
 import type { ExistingMetafield, ExistingMetaobject, ExistingSchema, Plan, SyncMode } from './planner.js';
-import { type RepairItem, type RepairPlan } from './repair.js';
+import { type DriftItem, type DriftPlan } from './changes.js';
 export declare const DEFAULT_API_VERSION = "2026-07";
 export declare class AdminError extends Error {
     readonly requestId?: string;
@@ -28,15 +28,16 @@ export declare class AdminClient {
     readMetafield(definition: Pick<CanonicalMetafield, 'ownerType' | 'namespace' | 'key'>): Promise<ExistingMetafield | null>;
     createMetaobject(definition: CanonicalMetaobject): Promise<void>;
     createMetafield(definition: CanonicalMetafield): Promise<void>;
-    repairMetaobject(entry: RepairItem): Promise<void>;
-    repairMetafield(entry: RepairItem): Promise<void>;
+    updateMetaobject(entry: DriftItem, force?: boolean): Promise<void>;
+    updateMetafield(entry: DriftItem, force?: boolean): Promise<void>;
 }
 export interface ApplyResult {
     plan: Plan;
-    applied: string[];
-    repaired: string[];
+    created: string[];
+    updated: string[];
+    skipped: string[];
 }
 export declare function planStore(client: AdminClient, schema: CompiledSchema): Promise<Plan>;
-export declare function applyPlan(client: AdminClient, schema: CompiledSchema, plan: Plan, repair?: RepairPlan): Promise<ApplyResult>;
-export declare function synchronize(client: AdminClient, schema: CompiledSchema, mode: SyncMode): Promise<ApplyResult>;
+export declare function applyPlan(client: AdminClient, schema: CompiledSchema, plan: Plan, drift: DriftPlan, force?: boolean): Promise<ApplyResult>;
+export declare function synchronize(client: AdminClient, schema: CompiledSchema, mode: SyncMode, force?: boolean): Promise<ApplyResult>;
 //# sourceMappingURL=admin.d.ts.map

package/dist/admin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAkB,kBAAkB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC3G,OAAO,KAAK,EACK,iBAAiB,EAAE,kBAAkB,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,EACrF,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAiC,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9F,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAE7C,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,YAAY,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAI9C;CACF;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMpD;AAID,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAQD,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,qBAAa,WAAW;;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAM1B,YAAY,OAAO,EAAE,kBAAkB,EActC;IAEK,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAAE,QAAQ,UAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,CAyCrG;IAEK,UAAU,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAYhE;IAEK,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAMrE;IAEK,aAAa,CAAC,UAAU,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,GAAG,WAAW,GAAG,KAAK,CAAC,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAS9H;IAEK,gBAAgB,CAAC,UAAU,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKrE;IAEK,eAAe,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQnE;IAEK,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvD;IAEK,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAQtD;CACF;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1F;AAED,wBAAsB,SAAS,CAC7B,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,IAAI,EACV,MAAM,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,WAAW,CAAC,CA+BtB;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,WAAW,CAAC,CAOtB"}
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"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"}