@fmaplabs/meta-manifest 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fmap labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# meta-manifest
+
+A zero-dependency, zod-style builder for Shopify **metaobject definitions**, plus a CLI
+(`mm` / `meta-manifest`) that keeps a store's definitions in sync with schema declared in code.
+Think [tento](https://github.com/drizzle-team/tento), but scoped to metaobject-definition
+schema/migrations rather than a runtime query client (see [Roadmap](#roadmap-runtime-query-client)
+below).
+
+`meta-manifest` is **not** a runtime client for reading/writing metaobject *entries* — it declares
+definitions, validates values against them, and syncs the definitions themselves (create/update
+fields) to a store via `pull` → `diff` → `push`.
+
+## Install
+
+```bash
+npm i -D @fmaplabs/meta-manifest
+# or
+pnpm add -D @fmaplabs/meta-manifest
+```
+
+## Library usage
+
+Declare a metaobject with `defineMetaobject` and the `m` field builders. Implements
+[Standard Schema](https://github.com/standard-schema/standard-schema).
+
+```ts
+import { defineMetaobject, m, type Infer } from "@fmaplabs/meta-manifest";
+
+export const Author = defineMetaobject("author", {
+  name: "Author",
+  displayName: "name",
+  access: { storefront: "public_read" },
+  fields: {
+    name: m.text({ required: true, max: 120 }),
+    bio: m.multilineText(),
+    rating: m.rating({ min: 1, max: 5 }),
+  },
+});
+
+type AuthorValue = Infer<typeof Author.fields>;
+
+Author.type;                 // "$app:author"
+Author.toDefinitionInput();  // MetaobjectDefinitionCreateInput (for metaobjectDefinitionCreate)
+Author.parse(fields);        // Shopify {key, jsonValue}[] -> typed, validated
+Author.encode({ name: "Ursula" }); // typed -> [{ key, value }] for metaobjectUpsert
+```
+
+References between metaobjects are declared with `m.ref(...)` / `m.list(m.ref(...))`:
+
+```ts
+export const Book = defineMetaobject("book", {
+  name: "Book",
+  fields: {
+    title: m.text({ required: true }),
+    author: m.ref(Author),
+  },
+});
+```
+
+For the full `pull` → `diff` → `push` sync model (how local schema and a live store are
+reconciled, destructive-change gating, dependency ordering, error handling), see
+[`docs/SYNC.md`](./docs/SYNC.md).
+
+## CLI
+
+The CLI drives sync against a real store using an Admin API access token. For a
+step-by-step walk-through (install → token → `init` → `pull`/`diff`/`push`, with
+example output and CI usage), see the [CLI quick start & usage guide](./docs/CLI.md).
+
+### Config
+
+`meta-manifest.config.ts` (safe to commit — the token comes from the environment):
+
+```ts
+import { defineConfig } from "@fmaplabs/meta-manifest";
+
+export default defineConfig({
+  shop: "my-store.myshopify.com",
+  accessToken: process.env.SHOPIFY_ADMIN_TOKEN!,
+  apiVersion: "2026-07",           // optional; defaults to DEFAULT_API_VERSION
+  schema: "./src/schema.ts",       // where `pull` writes, `diff`/`push` read
+});
+```
+
+Set `SHOPIFY_ADMIN_TOKEN` in your environment before running `pull`, `diff`, or `push`. The token
+needs the `read_metaobject_definitions` scope for `pull`/`diff`, and `write_metaobject_definitions`
+(which implies read) for `push`.
+
+### Commands
+
+| Command  | Behavior | Exit |
+|----------|----------|------|
+| `mm init` | Scaffold `meta-manifest.config.ts` + a starter `src/schema.ts`. No network. | 0 / 1 |
+| `mm pull` | Enumerate the store's app-owned metaobject definitions and **codegen** `schema.ts` (tento-style — writes/overwrites the schema source file). | 0 / 1 |
+| `mm diff` | Load `schema.ts`, compare it against the store, and print the plan. Read-only. | 0 / 1 |
+| `mm push` | Diff, then apply: topologically ordered (referenced types created first) and **destructive-gated** — `removeField`/`changeFieldType` are skipped unless you pass `--allow-destructive`. | 0 / 1 / 2 |
+
+```bash
+npx mm init                    # scaffold config + schema
+npx mm pull                    # bootstrap schema.ts from an existing store
+npx mm diff                    # preview what push would do
+npx mm push                    # apply non-destructive changes
+npx mm push --allow-destructive  # also apply field removals/type changes
+npx mm pull --force             # overwrite an existing schema.ts without the warning
+npx mm diff --config ./staging.config.ts  # use a non-default config file
+```
+
+### Flags
+
+- `--config <path>` — use a non-default config file instead of `meta-manifest.config.ts`.
+- `--allow-destructive` — apply destructive changes (`removeField`/`changeFieldType`) on push.
+- `--force` — overwrite the schema file on `pull` without the "overwriting" warning.
+
+`mm push` exits `2` if any operation failed **or was blocked** (e.g. a reference cycle among the
+definitions being created in that push — so CI can detect a partial failure), `1` on a
+config/transport error, and `0` otherwise — including when destructive ops were skipped.
+
+## Roadmap: runtime query client
+
+v1 covers metaobject **definitions** (schema sync) only. A runtime client for reading/writing
+metaobject **entries** — the tento-style query API — is not implemented yet and is tracked as a
+follow-up, along with codegen of `access`/`capabilities` config.

package/dist/chunk-3R6VQ3Z3.js

@@ -0,0 +1,97 @@
+// src/config.ts
+var DEFAULT_API_VERSION = "2026-07";
+function defineConfig(config) {
+  return config;
+}
+function validateConfig(raw) {
+  const c = raw;
+  for (const key of ["shop", "accessToken", "schema"]) {
+    if (!c || typeof c[key] !== "string" || c[key] === "") {
+      throw new Error(`Invalid config: missing or empty "${key}".`);
+    }
+  }
+  return c;
+}
+
+// src/sync/client.ts
+var PULL_DEFINITION_QUERY = `query PullMetaobjectDefinition($type: String!) {
+  metaobjectDefinitionByType(type: $type) {
+    id
+    name
+    type
+    description
+    displayNameKey
+    fieldDefinitions {
+      key
+      name
+      description
+      required
+      type { name }
+      validations { name value }
+    }
+    access { admin storefront }
+    capabilities {
+      publishable { enabled }
+      translatable { enabled }
+      renderable { enabled }
+    }
+  }
+}`;
+var LIST_DEFINITIONS_QUERY = `query ListMetaobjectDefinitions($after: String) {
+  metaobjectDefinitions(first: 50, after: $after) {
+    nodes {
+      id
+      name
+      type
+      fieldDefinitions {
+        key
+        name
+        description
+        required
+        type { name }
+        validations { name value }
+      }
+    }
+    pageInfo { hasNextPage endCursor }
+  }
+}`;
+var CREATE_DEFINITION_MUTATION = `mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
+  metaobjectDefinitionCreate(definition: $definition) {
+    metaobjectDefinition { id type }
+    userErrors { field message code }
+  }
+}`;
+var UPDATE_DEFINITION_MUTATION = `mutation UpdateMetaobjectDefinition($id: ID!, $definition: MetaobjectDefinitionUpdateInput!) {
+  metaobjectDefinitionUpdate(id: $id, definition: $definition) {
+    metaobjectDefinition { id type }
+    userErrors { field message code }
+  }
+}`;
+var SyncTransportError = class extends Error {
+  constructor(message, errors) {
+    super(message);
+    this.errors = errors;
+    this.name = "SyncTransportError";
+  }
+  errors;
+};
+async function execute(client, query, variables) {
+  const result = await client(query, variables ? { variables } : void 0);
+  if (Array.isArray(result.errors) ? result.errors.length > 0 : result.errors != null) {
+    throw new SyncTransportError("GraphQL request failed", result.errors);
+  }
+  return result.data;
+}
+
+export {
+  DEFAULT_API_VERSION,
+  defineConfig,
+  validateConfig,
+  PULL_DEFINITION_QUERY,
+  LIST_DEFINITIONS_QUERY,
+  CREATE_DEFINITION_MUTATION,
+  UPDATE_DEFINITION_MUTATION,
+  SyncTransportError,
+  execute
+};
+//# sourceMappingURL=chunk-3R6VQ3Z3.js.map

package/dist/chunk-3R6VQ3Z3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts","../src/sync/client.ts"],"sourcesContent":["export const DEFAULT_API_VERSION = \"2026-07\";\n\nexport interface Config {\n  /** e.g. \"my-store.myshopify.com\" */\n  shop: string;\n  /** Admin API access token; reference via process.env in your config file. */\n  accessToken: string;\n  /** Admin API version. Defaults to DEFAULT_API_VERSION. */\n  apiVersion?: string;\n  /** Path to the schema module whose `schemas` export drives diff/push, and pull writes. */\n  schema: string;\n}\n\n/** Identity helper for type inference in `meta-manifest.config.ts`. */\nexport function defineConfig(config: Config): Config {\n  return config;\n}\n\n/** Validate a loaded config object, throwing a one-line Error naming the first missing field. */\nexport function validateConfig(raw: unknown): Config {\n  const c = raw as Partial<Config> | null | undefined;\n  for (const key of [\"shop\", \"accessToken\", \"schema\"] as const) {\n    if (!c || typeof c[key] !== \"string\" || c[key] === \"\") {\n      throw new Error(`Invalid config: missing or empty \"${key}\".`);\n    }\n  }\n  return c as Config;\n}\n","/**\n * The minimal Admin GraphQL transport the sync adapter depends on. The app\n * supplies a concrete implementation at its edge (wrapping `admin.graphql`),\n * keeping `@fmaplabs/meta-manifest` free of any runtime dependency on a GraphQL\n * client. [design §5]\n */\nexport interface AdminGraphQLClient {\n  (query: string, options?: { variables?: Record<string, unknown> }): Promise<{ data?: unknown; errors?: unknown }>;\n}\n\n// GraphQL operation strings, copied verbatim from the schema-validated documents\n// in the design spec §3. Re-validated against Admin API 2026-07 during planning.\n// Do not edit by hand — keep equal to the validated documents (drift guard, §12).\n\nexport const PULL_DEFINITION_QUERY = `query PullMetaobjectDefinition($type: String!) {\n  metaobjectDefinitionByType(type: $type) {\n    id\n    name\n    type\n    description\n    displayNameKey\n    fieldDefinitions {\n      key\n      name\n      description\n      required\n      type { name }\n      validations { name value }\n    }\n    access { admin storefront }\n    capabilities {\n      publishable { enabled }\n      translatable { enabled }\n      renderable { enabled }\n    }\n  }\n}`;\n\nexport const LIST_DEFINITIONS_QUERY = `query ListMetaobjectDefinitions($after: String) {\n  metaobjectDefinitions(first: 50, after: $after) {\n    nodes {\n      id\n      name\n      type\n      fieldDefinitions {\n        key\n        name\n        description\n        required\n        type { name }\n        validations { name value }\n      }\n    }\n    pageInfo { hasNextPage endCursor }\n  }\n}`;\n\nexport const CREATE_DEFINITION_MUTATION = `mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n  metaobjectDefinitionCreate(definition: $definition) {\n    metaobjectDefinition { id type }\n    userErrors { field message code }\n  }\n}`;\n\nexport const UPDATE_DEFINITION_MUTATION = `mutation UpdateMetaobjectDefinition($id: ID!, $definition: MetaobjectDefinitionUpdateInput!) {\n  metaobjectDefinitionUpdate(id: $id, definition: $definition) {\n    metaobjectDefinition { id type }\n    userErrors { field message code }\n  }\n}`;\n\n/**\n * Thrown when a request fails at the transport or top-level GraphQL layer —\n * distinct from per-op `userErrors`, which `push` reports as `failed` rather\n * than throwing. Carries the offending top-level `errors` payload. [design §5]\n */\nexport class SyncTransportError extends Error {\n  constructor(message: string, readonly errors: unknown) {\n    super(message);\n    this.name = \"SyncTransportError\";\n  }\n}\n\n/**\n * Runs an operation through the injected client and returns its `data`.\n * A non-empty top-level `errors` payload becomes a `SyncTransportError`;\n * a rejected transport promise propagates unchanged. [design §5]\n */\nexport async function execute<T>(\n  client: AdminGraphQLClient,\n  query: string,\n  variables?: Record<string, unknown>,\n): Promise<T> {\n  const result = await client(query, variables ? { variables } : undefined);\n  if (Array.isArray(result.errors) ? result.errors.length > 0 : result.errors != null) {\n    throw new SyncTransportError(\"GraphQL request failed\", result.errors);\n  }\n  return result.data as T;\n}\n"],"mappings":";AAAO,IAAM,sBAAsB;AAc5B,SAAS,aAAa,QAAwB;AACnD,SAAO;AACT;AAGO,SAAS,eAAe,KAAsB;AACnD,QAAM,IAAI;AACV,aAAW,OAAO,CAAC,QAAQ,eAAe,QAAQ,GAAY;AAC5D,QAAI,CAAC,KAAK,OAAO,EAAE,GAAG,MAAM,YAAY,EAAE,GAAG,MAAM,IAAI;AACrD,YAAM,IAAI,MAAM,qCAAqC,GAAG,IAAI;AAAA,IAC9D;AAAA,EACF;AACA,SAAO;AACT;;;ACbO,IAAM,wBAAwB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAwB9B,IAAM,yBAAyB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAmB/B,IAAM,6BAA6B;AAAA;AAAA;AAAA;AAAA;AAAA;AAOnC,IAAM,6BAA6B;AAAA;AAAA;AAAA;AAAA;AAAA;AAYnC,IAAM,qBAAN,cAAiC,MAAM;AAAA,EAC5C,YAAY,SAA0B,QAAiB;AACrD,UAAM,OAAO;AADuB;AAEpC,SAAK,OAAO;AAAA,EACd;AAAA,EAHsC;AAIxC;AAOA,eAAsB,QACpB,QACA,OACA,WACY;AACZ,QAAM,SAAS,MAAM,OAAO,OAAO,YAAY,EAAE,UAAU,IAAI,MAAS;AACxE,MAAI,MAAM,QAAQ,OAAO,MAAM,IAAI,OAAO,OAAO,SAAS,IAAI,OAAO,UAAU,MAAM;AACnF,UAAM,IAAI,mBAAmB,0BAA0B,OAAO,MAAM;AAAA,EACtE;AACA,SAAO,OAAO;AAChB;","names":[]}