@tanqory/dev-mcp 0.0.0-stage → 0.1.0

package/src/schemas.mjs

@@ -0,0 +1,127 @@
+/**
+ * get_schema: the shapes a theme author writes, from the installed packages (bundled copy as fallback).
+ */
+import { DOCS } from './docs.mjs'
+
+export const SCHEMA_KINDS = ['manifest', 'section', 'block', 'field-registry', 'theme-settings', 'content-document', 'locale', 'ai-profile', 'storefront-report', 'conformance-report']
+
+const doc = (id) => DOCS.find((d) => d.id === id)
+
+/** `export interface Name …` / `export declare function name …` up to its closing line at column 0. */
+export function tsBlock(text, name) {
+  const lines = text.split('\n')
+  const re = new RegExp(`^export\\s+(?:declare\\s+)?(?:interface|type|function|const)\\s+${name}\\b`)
+  let at = lines.findIndex((l) => re.test(l))
+  if (at < 0) return null
+  let start = at
+  while (start > 0 && /^\s*(\/\*\*|\*)/.test(lines[start - 1])) start--
+  let end = at
+  if (/;\s*$/.test(lines[at]) && !/\{\s*$/.test(lines[at])) return lines.slice(start, at + 1).join('\n')
+  while (end < lines.length - 1 && !/^\}/.test(lines[end])) end++
+  return lines.slice(start, end + 1).join('\n')
+}
+
+const LOCALE_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  title: 'Theme locale file (locales/<lang>.json)',
+  description:
+    "A flat object: dotted key → string. The theme's own keys start with `theme.`; any kit key may be overridden. `{name}` placeholders must be the same set in every language. en.json and th.json must have exactly the same keys.",
+  type: 'object',
+  propertyNames: { pattern: '^[A-Za-z0-9_]+(\\.[A-Za-z0-9_-]+)+$' },
+  additionalProperties: { type: 'string' },
+}
+
+const CONTENT_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  title: 'Starter content document (templates/<name>.json, regions/<region>.json)',
+  description:
+    'templates/<name>.json: { contentVersion, template: "<name>", regions: { main: { sections: [node…] } } }. regions/header.json and regions/footer.json: { sections: [node…] }. A node is { id, type, settings?, blocks? }; `type` must be a declared section (or, inside blocks, a declared block of that section) and every setting key must be declared with a valid value. `npm run build` refuses anything else.',
+  $defs: {
+    node: {
+      type: 'object',
+      required: ['id', 'type'],
+      properties: {
+        id: { type: 'string', pattern: '^[A-Za-z0-9][A-Za-z0-9._-]*$' },
+        type: { type: 'string' },
+        settings: { type: 'object' },
+        blocks: { type: 'array', items: { $ref: '#/$defs/node' } },
+        disabled: { type: 'boolean' },
+      },
+      additionalProperties: false,
+    },
+  },
+  oneOf: [
+    {
+      type: 'object',
+      required: ['contentVersion', 'template', 'regions'],
+      properties: {
+        contentVersion: { type: 'integer', minimum: 1 },
+        template: { type: 'string' },
+        regions: { type: 'object', additionalProperties: { type: 'object', properties: { sections: { type: 'array', items: { $ref: '#/$defs/node' } } } } },
+      },
+    },
+    { type: 'object', required: ['sections'], properties: { sections: { type: 'array', items: { $ref: '#/$defs/node' } } } },
+  ],
+}
+
+/**
+ * @param {import('./docs.mjs').DocCorpus} corpus
+ */
+export async function getSchema(corpus, kind) {
+  const read = async (id) => corpus.read(doc(id))
+  const parse = (r) => (r ? JSON.parse(r.text) : null)
+  const meta = (r) => ({ source: r?.source ?? null, version: r?.version ?? null })
+
+  switch (kind) {
+    case 'manifest': {
+      const r = await read('abi/manifest-schema')
+      return { kind, ...meta(r), schema: parse(r), notes: ['dist/abi/manifest.json is generated by buildManifest (scripts/build.mjs) from your defineSection/defineBlock/defineSettings declarations; do not edit it by hand.', 'The file is the JCS (RFC 8785) bytes plus one trailing newline.'] }
+    }
+    case 'section':
+    case 'block': {
+      const m = parse(await read('abi/manifest-schema'))
+      const t = await read('kit/section-types')
+      const names = kind === 'section' ? ['SectionDefinition', 'SectionPresetDef', 'SectionComponentProps', 'BlockInstance', 'defineSection'] : ['defineBlock', 'BlockSchema', 'BlockInstance']
+      return {
+        kind,
+        ...meta(t),
+        types: names.map((n) => tsBlock(t.text, n)).filter(Boolean).join('\n\n'),
+        schema: m?.$defs?.component ?? null,
+        schemaNote: 'manifest.components.<type> as the build derives it from the declaration (attributes = settings, children = blocks).',
+        notes:
+          kind === 'section'
+            ? ['`type` is persisted: never rename it once stores saved content.', 'presets[0] is the editor\'s "Add section" preview: it must render with height > 0.', 'The kit wraps every section in its data-tq-node element; never render a section outside the kit section tree.', 'Register the section in defineTheme({ sections }) (src/theme.tsx).']
+            : ['List the block in the section\'s `blocks`; the component receives blocks in the merchant\'s order as { type, settings } (settings are not resolved for blocks: coerce with String()/Number()).'],
+      }
+    }
+    case 'field-registry': {
+      const r = await read('abi/field-types')
+      const helpers = await read('kit/field-helpers')
+      return { kind, ...meta(r), types: helpers ? tsBlock(helpers.text, 'field') : null, registry: r?.text ?? null, notes: ['Every field takes { label, info, placeholder, group }; every setting needs a default.', "field.resource(kind, default, opts): the stored value is a handle (or an image URL); pass '' for no default."] }
+    }
+    case 'theme-settings': {
+      const m = parse(await read('abi/manifest-schema'))
+      return { kind, source: 'installed-or-bundled', version: null, schema: m?.properties?.settingsSchema ?? null, notes: ['Declared in src/settings.ts with defineSettings(); values for the starter in config/settings.json (only declared keys, valid values). Read in components with useSettings().'] }
+    }
+    case 'content-document':
+      return { kind, source: 'dev-mcp', version: null, schema: CONTENT_SCHEMA, notes: ['Node ids must be unique within a document.'] }
+    case 'locale': {
+      const r = await read('kit/strings')
+      return { kind, source: 'dev-mcp', version: null, schema: LOCALE_SCHEMA, kitKeys: r ? [...r.text.matchAll(/^\| `([^`]+)` \|/gm)].map((m) => m[1]) : [], notes: ['Every visible string the theme adds goes in locales/en.json and locales/th.json and is rendered with t(); merchant-editable text belongs in settings.', 'The storefront tier renders th and en and fails visible text that does not change between them.'] }
+    }
+    case 'ai-profile': {
+      const r = await read('conformance/x-tanqory-ai-schema')
+      return { kind, ...meta(r), schema: parse(r), notes: ['Declared with ai.* helpers on sections; buildManifest prints manifest["x-tanqory-ai"]. Warn-only today.'] }
+    }
+    case 'storefront-report': {
+      const r = await read('conformance/storefront-report-schema')
+      return { kind, ...meta(r), schema: parse(r) }
+    }
+    case 'conformance-report': {
+      const r = await read('abi/conformance-report-schema')
+      return { kind, ...meta(r), schema: parse(r) }
+    }
+    default:
+      return null
+  }
+}