@tanqory/dev-mcp 0.0.0-stage → 0.1.0-alpha.1

package/bundled/theme-abi/schemas/theme-artifact.v1.schema.json

@@ -0,0 +1,230 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.tanqory.com/theme-artifact/v1/artifact.schema.json",
+  "title": "ThemeArtifact descriptor (artifact.json) v1",
+  "description": "Root descriptor of an immutable, content-addressed theme artifact. Deterministic: two builders with the same `inputs` produce byte-identical artifact.json (no measurements, no timestamps). artifact.json itself is NOT in `files` and is NOT covered by artifactDigest; its digest is bound inside the signed in-toto statement (theme-artifact-v1.md §6). Measured numbers live in b/<buildId>/conformance-report.json (B5, Build-1).",
+  "type": "object",
+  "required": [
+    "format",
+    "abiVersion",
+    "artifactDigest",
+    "files",
+    "inputDigest",
+    "inputs",
+    "manifestDigest",
+    "limits",
+    "capabilities",
+    "inlineScriptHashes"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "format": {
+      "const": "tanqory-theme-artifact/1"
+    },
+    "abiVersion": {
+      "type": "string",
+      "pattern": "^2\\.[0-9]+$",
+      "description": "Equals manifest.json `abi`."
+    },
+    "artifactDigest": {
+      "$ref": "#/$defs/sha256",
+      "description": "Merkle-list root over `files` (theme-artifact-v1.md §4.2). Also the storage key prefix `a/<hex>/`."
+    },
+    "files": {
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 4096,
+      "items": {
+        "type": "object",
+        "required": [
+          "path",
+          "sha256",
+          "size"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "path": {
+            "type": "string",
+            "pattern": "^(manifest\\.json|server/entry\\.mjs|preview/entry\\.mjs|client/client-manifest\\.json|client/assets/[A-Za-z0-9._-]+|defaults/(settings\\.json|templates/[a-z0-9][a-z0-9.-]*\\.json|regions/[a-z][a-z0-9-]*\\.json)|locales/[a-zA-Z]{2,3}(-[A-Za-z0-9]{2,8})*\\.json|sbom\\.cdx\\.json|README\\.md|LICENSE)$",
+            "maxLength": 200
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "size": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 67108864
+          },
+          "contentType": {
+            "type": "string",
+            "maxLength": 100
+          }
+        }
+      },
+      "description": "Sorted by `path` as UTF-8 byte order, ascending, no duplicates. Must contain manifest.json, server/entry.mjs, client/client-manifest.json and sbom.cdx.json. The signed statement repeats these as `predicate.files` — the loader verifies leaves from the STATEMENT, this list is for builders/tools."
+    },
+    "manifestDigest": {
+      "$ref": "#/$defs/sha256",
+      "description": "sha256 of manifest.json bytes."
+    },
+    "inputDigest": {
+      "$ref": "#/$defs/sha256",
+      "description": "sha256 over RFC 8785 (JCS) canonical JSON of `inputs`, which holds exactly the six identity fields."
+    },
+    "inputs": {
+      "type": "object",
+      "required": [
+        "sourceDigest",
+        "lockfileDigest",
+        "builderImageDigest",
+        "abiVersion",
+        "buildFlags",
+        "mirrorSnapshotId"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "sourceDigest": {
+          "$ref": "#/$defs/sha256",
+          "description": "Merkle-list root (§4.2 algorithm, header tanqory-theme-source/1) over the ingested ThemeSource tree after the ingest gate filter."
+        },
+        "lockfileDigest": {
+          "$ref": "#/$defs/sha256",
+          "description": "sha256 of pnpm-lock.yaml bytes."
+        },
+        "builderImageDigest": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$",
+          "description": "OCI digest of the theme-builder image."
+        },
+        "abiVersion": {
+          "type": "string",
+          "pattern": "^2\\.[0-9]+$"
+        },
+        "mirrorSnapshotId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9._-]{1,128}$",
+          "description": "Immutable snapshot id of the registry mirror the lockfile was resolved against (security §5.5)."
+        },
+        "buildFlags": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "profile",
+            "minify",
+            "sourcemaps",
+            "target",
+            "preview"
+          ],
+          "properties": {
+            "profile": {
+              "enum": [
+                "production"
+              ]
+            },
+            "minify": {
+              "type": "boolean"
+            },
+            "sourcemaps": {
+              "enum": [
+                "none",
+                "external-private"
+              ]
+            },
+            "target": {
+              "type": "string",
+              "pattern": "^es20[0-9]{2}$"
+            },
+            "preview": {
+              "type": "boolean",
+              "description": "Whether preview/entry.mjs was built."
+            },
+            "defines": {
+              "type": "object",
+              "additionalProperties": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  }
+                ]
+              },
+              "description": "Build-time constants inlined into the bundle; part of identity."
+            }
+          }
+        }
+      },
+      "description": "Exactly the six identity fields of §4.3, and nothing else. `sourceRef` was removed on 2026-10-09 (Vec-3): the descriptor must be byte-identical for a given artifactDigest, and where the source was fetched from varies per build. A descriptor that carries `sourceRef`, or any other member here, is invalid. The source reference is recorded in the signed provenance of each build."
+    },
+    "limits": {
+      "type": "object",
+      "required": [
+        "limitsVersion",
+        "passed"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "limitsVersion": {
+          "type": "string",
+          "pattern": "^2\\.[0-9]+$",
+          "description": "Limits table (ABI minor) the builder checked against."
+        },
+        "passed": {
+          "const": true,
+          "description": "Only a passing artifact is ever written to storage; a failed build produces no artifact. Measurements are in conformance-report.json."
+        }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "required": [
+        "server"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "server": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string"
+          }
+        },
+        "browser": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "description": "Byte-equal copy of manifest.capabilities (browser defaulted explicitly). The signed statement carries the same object; the loader trusts the STATEMENT."
+    },
+    "inlineScriptHashes": {
+      "type": "array",
+      "maxItems": 32,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^'sha256-[A-Za-z0-9+/]{43}='$"
+      },
+      "description": "Sorted CSP source expressions ('sha256-<base64>', single quotes included) of every executable inline script the theme may emit, computed at build time from src/inline/*.js (theme-artifact-v1 §1.2). Copied verbatim into the signed statement; a per-render x-tq-csp-script-hash is accepted only if listed there (ABI §5). [] when the theme has none."
+    },
+    "sbomRef": {
+      "type": "string",
+      "pattern": "^a/[0-9a-f]{64}/sbom\\.cdx\\.json$",
+      "description": "CycloneDX 1.6 SBOM (also listed in `files`). Build-scoped objects (statement, provenance, conformance report under b/<buildId>/) are never referenced from this deterministic descriptor."
+    }
+  },
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    }
+  }
+}

package/bundled/theme-abi/schemas/theme-manifest.v2.schema.json

@@ -0,0 +1,254 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.tanqory.com/theme-abi/v2/theme-manifest.schema.json",
+  "title": "ThemeManifest v2",
+  "description": "Static description of a theme for the platform (routing, regions, components, settings, capabilities). Produced by the builder into manifest.json and exported verbatim as `manifest` from server/entry.mjs. Keys starting with `x-` are vendor namespaces the platform ignores and never validates (Nova uses `x-nova`).",
+  "type": "object",
+  "required": ["abi", "name", "version", "engines", "capabilities", "client", "contentVersion", "routes", "templates", "regions", "components", "settingsSchema"],
+  "additionalProperties": false,
+  "patternProperties": {
+    "^x-[a-z0-9][a-z0-9-]*$": { "description": "Vendor namespace. Ignored by the platform. Counted toward manifest size." }
+  },
+  "properties": {
+    "abi": { "type": "string", "pattern": "^2\\.[0-9]+$", "description": "ABI the theme was built against (major.minor)." },
+    "name": { "type": "string", "pattern": "^(@[a-z0-9][a-z0-9-]*/)?[a-z0-9][a-z0-9._-]*$", "maxLength": 128 },
+    "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$", "description": "Theme semver (marketplace version)." },
+    "engines": {
+      "type": "object",
+      "required": ["tanqory-abi", "tanqory-field-types"],
+      "additionalProperties": false,
+      "properties": {
+        "tanqory-abi": { "type": "string", "description": "Semver range of hosts this theme accepts, e.g. \"^2.0\"." },
+        "tanqory-field-types": { "type": "string", "pattern": "^[0-9]+$", "description": "Field-type registry version every `type` below is validated against." }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "required": ["server", "browser"],
+      "additionalProperties": false,
+      "description": "Security B-6: both arrays required and explicit; browser ⊆ server. The builder copies both verbatim into the signed statement; the runtime uses the statement's copy, never this file.",
+      "properties": {
+        "server": {
+          "type": "array",
+          "uniqueItems": true,
+          "maxItems": 32,
+          "items": { "$ref": "#/$defs/capability" },
+          "description": "What render() may use. `ctx.data`/`ctx.actions` outside this set throw CapabilityError. `network:<origin>` is the ONLY egress form (proxied fetch to that origin, counted as a sub-request, store/marketplace-approved)."
+        },
+        "browser": {
+          "type": "array",
+          "uniqueItems": true,
+          "maxItems": 16,
+          "items": {
+            "type": "string",
+            "pattern": "^(data:(shop|localization|catalog|content|search|cart|products\\.recommendations|inventory)|actions:(cart|consent))$"
+          },
+          "description": "What hydrated theme JS may call via /_tq/data/* and /_tq/actions/*. Ceiling per capability-security-v1.md §2.6 / B-6 / A10: data:customer, data:metaobjects, actions:customer, actions:form.submit are NEVER browser-mintable (the pattern excludes them, so validation fails on them); data:products.recommendations and data:inventory ARE allowed. Must be ⊆ server (checked by `theme check`, not expressible here). `tanqory theme init` scaffolds {data:shop, data:localization, data:catalog, data:content, data:search, data:cart, actions:cart, actions:consent}; an empty array is valid for zero-JS themes."
+        }
+      }
+    },
+    "forms": {
+      "type": "object",
+      "maxProperties": 16,
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
+      "additionalProperties": {
+        "type": "object",
+        "required": ["fields"],
+        "additionalProperties": false,
+        "properties": {
+          "title": { "type": "string", "maxLength": 64 },
+          "fields": { "type": "array", "minItems": 1, "maxItems": 32, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" } }
+        }
+      },
+      "description": "Forms submittable through actions:form.submit (server-side POST only). Native HTML: the theme writes only `<form data-tq-form=\"<id>\" method=\"post\">`; the form posts to the same path it was rendered on (no `action`, or `action` = that path); the gateway injects both hidden fields `_tq_form` and `_tq_csrf` after its cache (theme must not render them), strips both on POST, accepts application/x-www-form-urlencoded only, caps the body at 8 KiB (8192 bytes) before the isolate, filters to `fields`, and exposes ctx.request.form (owner approval 2026-10-07). Field names are an allowlist and must not start with `_tq_`; destination is the merchant inbox, never a theme URL."
+    },
+    "client": {
+      "type": "object",
+      "required": ["hydration"],
+      "additionalProperties": false,
+      "properties": {
+        "hydration": { "enum": ["none", "full", "partial"], "description": "none = zero-JS/HTMX theme: client-manifest has no isEntry script and the hydration-parity suite is skipped (per-content-type assertions still run)." }
+      }
+    },
+    "contentVersion": { "type": "integer", "minimum": 1, "description": "Version of the content-document shape this theme reads. Docs at a lower version are migrated by the platform via declared `migrations` before render." },
+    "minContentVersion": { "type": "integer", "minimum": 1, "description": "Oldest version this artifact's migrate() accepts. Absent ⇒ equals contentVersion (no chain required); > contentVersion is `migration_range_invalid` (validateManifest semantic check). Docs older than this are first brought up by the previously installed artifact's chain (platform-chained migration)." },
+    "migrations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from", "to"],
+        "additionalProperties": false,
+        "properties": {
+          "from": { "type": "integer", "minimum": 1 },
+          "to": { "type": "integer", "minimum": 2 },
+          "note": { "type": "string", "maxLength": 512 }
+        }
+      },
+      "description": "Each step must be implemented by the entry's `migrate(doc, from, to)`. Steps must chain gap-free from `minContentVersion` (default: 1) to `contentVersion`. Docs below `minContentVersion` are migrated by the platform through the previously installed artifact's chain first (S5)."
+    },
+    "routes": {
+      "type": "object",
+      "description": "Default template per platform route kind. `home` and `not_found` are required. A missing kind means the platform serves its own minimal page for that kind.",
+      "required": ["home", "not_found"],
+      "properties": {
+        "home": { "type": "string", "description": "Template name (key of `templates`)." },
+        "not_found": { "type": "string", "description": "Template name (key of `templates`)." }
+      },
+      "propertyNames": { "pattern": "^(home|product|collection|collections|page|blog|article|search|cart|customer|policy|not_found|custom:[a-z][a-z0-9-]*)$" },
+      "additionalProperties": { "type": "string", "description": "Template name (key of `templates`)." }
+    },
+    "customRoutes": {
+      "type": "object",
+      "maxProperties": 16,
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
+      "additionalProperties": {
+        "type": "object",
+        "required": ["path"],
+        "additionalProperties": false,
+        "properties": {
+          "path": { "type": "string", "pattern": "^/[A-Za-z0-9._~/-]*(:[a-z][A-Za-z0-9]*(/[A-Za-z0-9._~/-]*)?)*$", "description": "URL pattern with `:param` captures, e.g. \"/lookbook/:season\". Must not start with /collections, /products, /pages, /blogs, /policies, /cart, /search, /account (the built-in `customer` kind), /checkout, /orders, /api, /_tq (the reserved platform prefix is `/_tq/`)." }
+        }
+      },
+      "description": "Theme-defined route kinds. Route kind is `custom:<key>`; captures appear in ctx.route.params."
+    },
+    "templates": {
+      "type": "object",
+      "minProperties": 2,
+      "maxProperties": 128,
+      "propertyNames": { "pattern": "^[a-z0-9][a-z0-9.-]*$" },
+      "additionalProperties": {
+        "type": "object",
+        "required": ["route", "regions"],
+        "additionalProperties": false,
+        "properties": {
+          "route": { "type": "string", "pattern": "^(home|product|collection|collections|page|blog|article|search|cart|customer|policy|not_found|custom:[a-z][a-z0-9-]*)$" },
+          "title": { "type": "string", "maxLength": 128 },
+          "regions": { "type": "array", "minItems": 1, "maxItems": 16, "uniqueItems": true, "items": { "type": "string" }, "description": "Ordered region ids this template renders (keys of `regions`)." }
+        }
+      },
+      "description": "Template name → route kind. A resource's templateSuffix selects `<route>.<suffix>` when it exists, else `routes[kind]`."
+    },
+    "regions": {
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 32,
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
+      "additionalProperties": {
+        "type": "object",
+        "required": ["title", "scope"],
+        "additionalProperties": false,
+        "properties": {
+          "title": { "type": "string", "maxLength": 64 },
+          "scope": { "enum": ["shared", "template"], "description": "`shared`: one doc per region for the whole store (header/footer pattern), editable in place from any template; `template`: one doc per template." },
+          "accepts": { "type": "array", "uniqueItems": true, "items": { "type": "string" }, "description": "Component ids (role section|layout) allowed here. Absent = every section whose `regions` lists this id." },
+          "min": { "type": "integer", "minimum": 0 },
+          "max": { "type": "integer", "minimum": 1, "maximum": 64 }
+        }
+      },
+      "description": "Theme-declared regions. The platform imposes none; today's header/template/footer is just one possible declaration."
+    },
+    "components": {
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 256,
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)?$" },
+      "additionalProperties": { "$ref": "#/$defs/component" }
+    },
+    "settingsSchema": {
+      "type": "array",
+      "maxItems": 32,
+      "items": {
+        "type": "object",
+        "required": ["group", "items"],
+        "additionalProperties": false,
+        "properties": {
+          "group": { "type": "string", "maxLength": 64 },
+          "items": {
+            "type": "array",
+            "maxItems": 64,
+            "items": { "allOf": [ { "$ref": "#/$defs/field" }, { "type": "object", "required": ["key"], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" } } } ] }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "capability": {
+      "type": "string",
+      "pattern": "^(data:(shop|localization|catalog|content|search|cart|customer|metaobjects|products\\.recommendations|inventory)|actions:(cart|consent|customer|form\\.submit)|preview:renderSection|network:https://.+)$",
+      "description": "Normative set = `Capability` in render-context.v2.d.ts (`network:https://${string}` — origin well-formedness is a validateManifest() semantic check). Security (capability-security-v1.md §2) cites this type."
+    },
+    "field": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "key": { "type": "string" },
+        "type": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Id in the field-type registry version named by engines[\"tanqory-field-types\"]. Unknown ids fail `theme check`." },
+        "label": { "type": "string", "maxLength": 128 },
+        "info": { "type": "string", "maxLength": 512 },
+        "default": {},
+        "placeholder": { "type": "string", "maxLength": 128 },
+        "group": { "type": "string", "maxLength": 64 },
+        "min": { "type": "number" },
+        "max": { "type": "number" },
+        "step": { "type": "number", "exclusiveMinimum": 0 },
+        "unit": { "type": "string", "maxLength": 8 },
+        "options": { "type": "array", "maxItems": 64, "items": { "type": "object", "required": ["value", "label"], "additionalProperties": false, "properties": { "value": { "type": "string" }, "label": { "type": "string" } } } },
+        "visible_if": { "oneOf": [ { "type": "string", "maxLength": 256 }, { "type": "object" } ] },
+        "dynamic": { "type": "boolean" },
+        "resolve": { "type": "boolean", "description": "Resource-typed fields only: platform resolves the referenced resource into snapshot.refs." },
+        "items": { "$ref": "#/$defs/field", "description": "`list` type only: the element field spec (depth ≤ 2)." },
+        "schema": { "type": "object", "description": "`json` type only: optional JSON Schema (draft 2020-12, ≤ 8 KB serialised) the editor validates the value against." }
+      }
+    },
+    "contentNode": {
+      "type": "object",
+      "required": ["type", "id"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string" },
+        "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$", "maxLength": 64 },
+        "settings": { "type": "object" },
+        "blocks": { "type": "array", "maxItems": 64, "items": { "$ref": "#/$defs/contentNode" } },
+        "disabled": { "type": "boolean" }
+      }
+    },
+    "component": {
+      "type": "object",
+      "required": ["role", "title", "attributes"],
+      "additionalProperties": false,
+      "properties": {
+        "role": { "enum": ["section", "block", "layout"], "description": "section: merchant-placed in a region · block: nested in a section · layout: a region-level unit (e.g. header bar) the theme pins." },
+        "title": { "type": "string", "maxLength": 128 },
+        "description": { "type": "string", "maxLength": 512 },
+        "category": { "type": "string", "maxLength": 64 },
+        "icon": { "type": "string", "maxLength": 64 },
+        "regions": { "type": "array", "uniqueItems": true, "items": { "type": "string" }, "description": "Sections/layout: regions that accept this component." },
+        "parents": { "type": "array", "uniqueItems": true, "items": { "type": "string" }, "description": "Blocks: component ids that may contain this block." },
+        "children": { "type": "array", "uniqueItems": true, "maxItems": 64, "items": { "type": "string" }, "description": "Sections: block ids accepted." },
+        "requires": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^(home|product|collection|collections|page|blog|article|search|cart|customer|policy|not_found|custom:[a-z][a-z0-9-]*)$" }, "description": "Route kinds (any RouteKind, aligned with the .d.ts) whose resource this component needs. The editor refuses to place it on other templates." },
+        "attributes": {
+          "type": "object",
+          "maxProperties": 64,
+          "propertyNames": { "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" },
+          "additionalProperties": { "$ref": "#/$defs/field" }
+        },
+        "presets": {
+          "type": "array",
+          "maxItems": 16,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "name": { "type": "string", "maxLength": 128 },
+              "settings": { "type": "object" },
+              "blocks": { "type": "array", "maxItems": 64, "items": { "$ref": "#/$defs/contentNode" } }
+            }
+          }
+        },
+        "limits": { "type": "object", "additionalProperties": false, "properties": { "maxBlocks": { "type": "integer", "minimum": 0, "maximum": 64 } } }
+      }
+    }
+  }
+}