@utopia-studio-design/design-system-cli 0.7.2 → 0.8.1

package/bin/utopia-ds-mcp.mjs

@@ -2,7 +2,7 @@
 import {
   capabilityManifest, getBlock, getBlockDefinition, getBrandbookSkill, getComponent, getDoc, getLogoSkill, getMotionProfile, getRoomContext, getTemplate, getTheme,
   listBlockDefinitions, listBlocks, listComponents, listDocs, listLogoSkills, listMotionProfiles, listTemplates, listThemes, prepareLogoMakerRun,
-  prepareBrandbookRun, repositoryDoctor, search, validateAgentMutation, validateLayout,
+  prepareBrandbookRun, repositoryDoctor, search, validateAgentMutation, validateBrandbook, validateLayout,
 } from '../lib/api.mjs'
 
 const tools = [
@@ -27,6 +27,7 @@ const tools = [
   ['prepare_logo_maker_run', 'Prepare a Brand Room-aware Logo Maker chat run using the same skill contract as Ceramic UI. This does not approve or publish the result.', { skillId: { type: 'string' }, brandName: { type: 'string' }, brief: { type: 'string' }, referenceIds: { type: 'array', items: { type: 'string' }, maxItems: 3 } }, (input) => prepareLogoMakerRun(input)],
   ['get_brandbook_skill', 'Read the Ceramic Brandbook workflow, GitHub source contract, provider rule, and Solution application rules.', {}, () => getBrandbookSkill()],
   ['prepare_brandbook_run', 'Prepare a Brand Room-aware Ceramic Brandbook run. Returns the required A/B/C direction phase and one-BRAND.md handoff prompt; it does not generate, save, or publish a release.', { brandName: { type: 'string' }, brief: { type: 'string', minLength: 12, maxLength: 4000 } }, (input) => prepareBrandbookRun(input)],
+  ['validate_brandbook', 'Mechanically validate the Ceramic BRAND.md contract, A/B/C refinement record, bilingual handoff, assets, and Solution showcase structure.', { path: { type: 'string' } }, (input) => validateBrandbook(input)],
   ['list_docs', 'List AI-readable design-system documents.', {}, () => listDocs()],
   ['get_docs', 'Read one design-system document.', { topic: { type: 'string' } }, ({ topic }) => getDoc(topic)],
   ['doctor', 'Validate the Ceramic source of truth.', {}, () => repositoryDoctor()],

package/data/docs/create-a-brandbook.md

@@ -30,6 +30,17 @@ Call `prepare_brandbook_run` with a brand name and useful brief. A logo is optio
 }
 ```
 
+After the user selects and refines A, B, or C, write the single `BRAND.md` source and validate it before building or saving a release:
+
+```json
+{
+  "name": "validate_brandbook",
+  "arguments": { "path": "/absolute/path/to/brand-directory" }
+}
+```
+
+Treat every validation error as blocking. A successful schema check does not replace visual, Arabic, licensing, or stakeholder review.
+
 This call prepares work; it does not generate, save, or publish a release.
 
 ## Present A, B, and C
@@ -76,4 +87,3 @@ Release checks:
 - Image provenance and rights metadata are present.
 - Marketing and Solution applications reflect the selected direction.
 - Brandbook validation passes before theme authoring begins.
-

package/lib/api.mjs

@@ -6,6 +6,7 @@ import {
   validateAgentLayoutMutation,
   validateLayoutDocument,
 } from './composition-runtime.mjs'
+export { validateBrandbook } from './brandbook-validation.mjs'
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
 const workspaceRoot = resolve(packageRoot, '../..')
@@ -17,7 +18,7 @@ export const apiVersion = 1
 export const cliVersion = packageMetadata.version
 export const mcpLaunch = {
   command: 'npx',
-  args: ['-y', '--package', '@utopia-studio-design/design-system-cli', 'utopia-ds', 'mcp'],
+  args: ['-y', '--package', `${packageMetadata.name}@${cliVersion}`, 'utopia-ds', 'mcp'],
 }
 
 export function paths(root = hasWorkspaceSource ? workspaceRoot : packagedDataRoot) {
@@ -274,7 +275,7 @@ export function capabilityManifest() {
     ],
     mcp: {
       ...mcpLaunch,
-      tools: ['get_room_context', 'search', 'list_components', 'get_component', 'list_block_definitions', 'get_block_definition', 'validate_layout', 'validate_agent_layout_mutation', 'list_blocks', 'get_block', 'list_templates', 'get_template', 'list_themes', 'get_theme', 'list_motion_profiles', 'get_motion_profile', 'list_logo_skills', 'get_logo_skill', 'prepare_logo_maker_run', 'get_brandbook_skill', 'prepare_brandbook_run', 'list_docs', 'get_docs', 'doctor'],
+      tools: ['get_room_context', 'search', 'list_components', 'get_component', 'list_block_definitions', 'get_block_definition', 'validate_layout', 'validate_agent_layout_mutation', 'list_blocks', 'get_block', 'list_templates', 'get_template', 'list_themes', 'get_theme', 'list_motion_profiles', 'get_motion_profile', 'list_logo_skills', 'get_logo_skill', 'prepare_logo_maker_run', 'get_brandbook_skill', 'prepare_brandbook_run', 'validate_brandbook', 'list_docs', 'get_docs', 'doctor'],
     },
   }
 }

package/lib/brandbook-validation.mjs

@@ -0,0 +1,112 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, extname, isAbsolute, join, resolve } from 'node:path'
+
+const chapters = ['brand', 'core', 'photography', 'motion', 'marketing', 'solution']
+const directionFields = ['name', 'thesis', 'typography', 'color', 'imagery', 'motion', 'marketing', 'solution', 'fit', 'tradeoff']
+const text = (value) => typeof value === 'string' && value.trim().length > 0
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+const issue = (code, message, field) => ({ code, message, ...(field ? { field } : {}) })
+
+function resolveBrandPath(inputPath, root) {
+  const candidate = isAbsolute(inputPath) ? inputPath : resolve(root, inputPath)
+  return extname(candidate).toLowerCase() === '.md' ? candidate : join(candidate, 'BRAND.md')
+}
+
+function parseJson(raw, label, errors) {
+  try {
+    return JSON.parse(raw)
+  } catch {
+    errors.push(issue('INVALID_JSON', `${label} must use valid JSON syntax.`))
+    return null
+  }
+}
+
+export function validateBrandbook({ path: inputPath }, root = process.cwd()) {
+  const errors = []
+  const warnings = []
+  const suppliedPath = String(inputPath || '').trim()
+  if (!suppliedPath) {
+    return { ok: false, path: null, errors: [issue('PATH_REQUIRED', 'Provide a BRAND.md file or its containing directory.')], warnings }
+  }
+
+  const brandPath = resolveBrandPath(suppliedPath, root)
+  if (!existsSync(brandPath)) {
+    return { ok: false, path: brandPath, errors: [issue('BRAND_MD_NOT_FOUND', `BRAND.md was not found at ${brandPath}.`)], warnings }
+  }
+
+  const raw = readFileSync(brandPath, 'utf8')
+  const frontmatter = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/)
+  if (!frontmatter) errors.push(issue('FRONTMATTER_REQUIRED', 'BRAND.md must start with JSON frontmatter between --- delimiters.'))
+  const meta = frontmatter ? parseJson(frontmatter[1], 'BRAND.md frontmatter', errors) : null
+  if (meta) {
+    if (meta.schema !== 'ceramic.document/v1' || meta.id !== 'brand') errors.push(issue('INVALID_DOCUMENT_IDENTITY', 'Frontmatter must use schema ceramic.document/v1 and id brand.'))
+    if (!/^[a-z][a-z0-9-]{0,79}$/.test(meta.brandId || '')) errors.push(issue('INVALID_BRAND_ID', 'brandId must be a lowercase slug.', 'brandId'))
+    if (!/^\d+\.\d+\.\d+$/.test(meta.version || '')) errors.push(issue('INVALID_VERSION', 'version must be semantic versioning.', 'version'))
+    if (!['draft', 'review', 'approved'].includes(meta.status)) errors.push(issue('INVALID_STATUS', 'status must be draft, review, or approved.', 'status'))
+    if (!Array.isArray(meta.requiredLocales) || !meta.requiredLocales.includes('en') || !meta.requiredLocales.includes('ar')) {
+      errors.push(issue('REQUIRED_LOCALES', 'requiredLocales must include en and ar unless the user explicitly approved another scope.', 'requiredLocales'))
+    }
+  }
+
+  const blocks = [...raw.matchAll(/^```ceramic\s*\r?\n([\s\S]*?)^```\s*$/gm)]
+  if (blocks.length !== 1) errors.push(issue('CERAMIC_CONTRACT_COUNT', 'BRAND.md must contain exactly one fenced ceramic JSON contract.'))
+  const contract = blocks.length === 1 ? parseJson(blocks[0][1], 'Ceramic contract', errors) : null
+  if (contract) {
+    for (const chapter of chapters) {
+      if (!object(contract[chapter])) {
+        errors.push(issue('CHAPTER_CONTRACT_REQUIRED', `Missing ${chapter} contract.`, chapter))
+        continue
+      }
+      const decisions = contract[chapter].decisions
+      if (!Array.isArray(decisions) || decisions.length === 0) errors.push(issue('DECISIONS_REQUIRED', `${chapter} needs at least one decision.`, `${chapter}.decisions`))
+      if (chapter !== 'brand') {
+        const expected = ['marketing', 'solution'].includes(chapter) ? 'core' : 'brand'
+        if (contract[chapter].extends !== expected) errors.push(issue('INVALID_INHERITANCE', `${chapter}.extends must be ${expected}.`, `${chapter}.extends`))
+      }
+    }
+
+    const session = contract.brand?.directionSession
+    if (!object(session) || !Array.isArray(session.options) || session.options.length !== 3) {
+      errors.push(issue('DIRECTION_SESSION_REQUIRED', 'brand.directionSession must contain exactly three options.', 'brand.directionSession'))
+    } else {
+      if (session.options.map((option) => option?.id).join('') !== 'ABC') errors.push(issue('DIRECTION_ORDER', 'Direction options must be ordered A, B, C.', 'brand.directionSession.options'))
+      for (const option of session.options) {
+        if (!object(option) || !directionFields.every((field) => text(option[field]))) errors.push(issue('DIRECTION_INCOMPLETE', `Direction ${option?.id || '?'} is incomplete.`, 'brand.directionSession.options'))
+      }
+      if (!['A', 'B', 'C'].includes(session.selected)) errors.push(issue('DIRECTION_SELECTION_REQUIRED', 'A selected direction is required.', 'brand.directionSession.selected'))
+      if (!['refined', 'approved'].includes(session.status) || !text(session.refinement)) errors.push(issue('DIRECTION_REFINEMENT_REQUIRED', 'The selected direction must include a refinement note and refined or approved status.', 'brand.directionSession'))
+    }
+
+    const arabic = contract.brand?.localization?.ar
+    if (!object(arabic) || !text(arabic.displayFont) || !text(arabic.bodyFont) || !object(arabic.text) || Object.keys(arabic.text).length === 0) {
+      errors.push(issue('ARABIC_PARITY_REQUIRED', 'brand.localization.ar must provide displayFont, bodyFont, and a nonempty 1:1 text map.', 'brand.localization.ar'))
+    }
+
+    const showcases = contract.solution?.showcases
+    if (!Array.isArray(showcases) || showcases.length < 1 || showcases.length > 3) errors.push(issue('SOLUTION_SHOWCASES', 'solution.showcases must contain one to three brand-fit applications.', 'solution.showcases'))
+    else if (new Set(showcases.map((showcase) => showcase?.type)).size !== showcases.length || showcases.some((showcase) => !['phone', 'desktop', 'environment'].includes(showcase?.type))) {
+      errors.push(issue('SOLUTION_SHOWCASE_TYPES', 'Solution showcase types must be unique phone, desktop, or environment entries.', 'solution.showcases'))
+    }
+  }
+
+  const anchors = [...raw.matchAll(/^## .+ \{#([a-z]+)\}\s*$/gm)].map((match) => match[1])
+  for (const chapter of chapters) if (!anchors.includes(chapter)) errors.push(issue('CHAPTER_ANCHOR_REQUIRED', `Missing {#${chapter}} chapter anchor.`, chapter))
+
+  const manifestPath = join(dirname(brandPath), 'assets', 'manifest.json')
+  if (!existsSync(manifestPath)) errors.push(issue('ASSET_MANIFEST_REQUIRED', 'assets/manifest.json is required.'))
+  else {
+    const manifest = parseJson(readFileSync(manifestPath, 'utf8'), 'Asset manifest', errors)
+    if (manifest && (manifest.schema !== 'ceramic.assets/v1' || !Array.isArray(manifest.assets))) errors.push(issue('INVALID_ASSET_MANIFEST', 'Asset manifest must use ceramic.assets/v1 and contain an assets array.'))
+    if (manifest?.assets) {
+      const families = new Set(manifest.assets.filter((asset) => asset.kind === 'font').map((asset) => asset.family))
+      const arabic = contract?.brand?.localization?.ar
+      for (const role of ['displayFont', 'bodyFont']) if (text(arabic?.[role]) && !families.has(arabic[role])) errors.push(issue('ARABIC_FONT_NOT_BUNDLED', `Arabic ${role} ${arabic[role]} is not registered as a local font asset.`, `brand.localization.ar.${role}`))
+      for (const asset of manifest.assets) {
+        if (!text(asset.path) || !asset.path.startsWith('assets/') || asset.path.includes('..') || !existsSync(join(dirname(brandPath), asset.path))) errors.push(issue('ASSET_FILE_MISSING', `Manifest asset is missing or unsafe: ${asset.path || '(no path)'}.`, 'assets'))
+      }
+    }
+  }
+
+  if (meta?.status === 'approved') warnings.push(issue('APPROVAL_SCOPE', 'Schema validation does not replace visual, linguistic, licensing, or stakeholder approval.'))
+  return { ok: errors.length === 0, path: brandPath, errors, warnings, summary: { errorCount: errors.length, warningCount: warnings.length, chapters: anchors.filter((anchor) => chapters.includes(anchor)).length } }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utopia-studio-design/design-system-cli",
-  "version": "0.7.2",
+  "version": "0.8.1",
   "description": "AI-readable CLI and MCP server for Ceramic Design System",
   "ceramic": {
     "designSystem": "^0.10.0"