@utopia-studio-design/design-system-cli 0.4.0 → 0.5.0

package/lib/api.mjs

@@ -1,14 +1,20 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import {
+  serializeLayoutDocument,
+  validateAgentLayoutMutation,
+  validateLayoutDocument,
+} from './composition-runtime.mjs'
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
 const workspaceRoot = resolve(packageRoot, '../..')
 const packagedDataRoot = join(packageRoot, 'data')
 const hasWorkspaceSource = existsSync(join(workspaceRoot, 'packages/design-system/src/manifests/components.json'))
+const packageMetadata = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'))
 
 export const apiVersion = 1
-export const cliVersion = '0.4.0'
+export const cliVersion = packageMetadata.version
 export const mcpLaunch = {
   command: 'npx',
   args: ['-y', '--package', '@utopia-studio-design/design-system-cli', 'utopia-ds', 'mcp'],
@@ -52,6 +58,44 @@ export function listTemplates() {
   return readJson(join(paths().manifests, 'templates.json')).templates
 }
 
+export function listBlocks() {
+  return readJson(join(paths().manifests, 'blocks.json')).blocks
+}
+
+export function getCompositionRegistry() {
+  return readJson(join(paths().manifests, 'composition-registry.json'))
+}
+
+export function listBlockDefinitions({ renderableOnly = false } = {}) {
+  return getCompositionRegistry().definitions.filter(
+    (definition) => !renderableOnly || definition.availability === 'available',
+  )
+}
+
+export function getBlockDefinition(name) {
+  const key = normalize(name)
+  return listBlockDefinitions().find(
+    (item) => normalize(item.id) === key || normalize(item.title) === key,
+  ) ?? null
+}
+
+export function validateLayout(document) {
+  return validateLayoutDocument(getCompositionRegistry(), document)
+}
+
+export function validateAgentMutation(current, next) {
+  return validateAgentLayoutMutation(getCompositionRegistry(), current, next)
+}
+
+export function serializeLayout(document) {
+  return serializeLayoutDocument(getCompositionRegistry(), document)
+}
+
+export function getBlock(name) {
+  const key = normalize(name)
+  return listBlocks().find((item) => normalize(item.id) === key || normalize(item.title) === key) ?? null
+}
+
 export function getTemplate(name) {
   const key = normalize(name)
   return listTemplates().find((item) => normalize(item.id) === key || normalize(item.title) === key) ?? null
@@ -104,6 +148,8 @@ export function search(query) {
   const score = (text) => terms.reduce((total, term) => total + (text.toLowerCase().includes(term) ? 1 : 0), 0)
   const results = [
     ...listComponents().map((item) => ({ kind: 'component', id: item.name, title: item.name, summary: [...item.useWhen, item.category].join(' '), item })),
+    ...listBlockDefinitions().map((item) => ({ kind: 'block-definition', id: item.id, title: item.title, summary: `${item.category} ${item.description} ${item.availability}`, item })),
+    ...listBlocks().map((item) => ({ kind: 'block', id: item.id, title: item.title, summary: `${item.category} ${item.purpose}`, item })),
     ...listTemplates().map((item) => ({ kind: 'template', id: item.id, title: item.title, summary: `${item.category} ${item.purpose}`, item })),
     ...listThemes().map((item) => ({ kind: 'theme', id: item.id, title: item.name, summary: item.role, item })),
     ...listMotionProfiles().map((item) => ({ kind: 'motion-profile', id: item.id, title: item.label, summary: `${item.description} ${item.rules.join(' ')}`, item })),
@@ -130,6 +176,9 @@ export function capabilityManifest() {
       { name: 'init', args: ['[directory]'], flags: ['--yes', '--theme <id>'], responseType: 'init-result' },
       { name: 'search', args: ['<query>'], flags: [], responseType: 'search-results' },
       { name: 'component', args: ['<name>|--list'], flags: [], responseType: 'component|component-list' },
+      { name: 'registry', args: ['<block-id>|--list'], flags: ['--renderable'], responseType: 'block-definition|block-definition-list' },
+      { name: 'layout', args: ['validate <file>', 'serialize <file>'], flags: [], responseType: 'layout-validation-result|layout-serialization-result' },
+      { name: 'block', args: ['<id>|--list'], flags: ['--copy <directory>', '--force'], responseType: 'block|block-list|block-copy-result' },
       { name: 'template', args: ['<id>|--list', 'validate [directory]', 'submit [directory]'], flags: ['--skeleton', '--copy <directory>', '--theme <id>', '--force'], responseType: 'template|template-list|template-copy-result|template-validation-result|template-submit-result' },
       { name: 'theme', args: ['<id>|--list', 'create <id> [directory]'], flags: ['--force'], responseType: 'theme|theme-list|theme-create-result' },
       { name: 'motion', args: ['<id>|--list'], flags: [], responseType: 'motion-profile|motion-profile-list' },
@@ -140,16 +189,16 @@ export function capabilityManifest() {
     ],
     mcp: {
       ...mcpLaunch,
-      tools: ['search', 'list_components', 'get_component', 'list_templates', 'get_template', 'list_themes', 'get_theme', 'list_motion_profiles', 'get_motion_profile', 'list_docs', 'get_docs', 'doctor'],
+      tools: ['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_docs', 'get_docs', 'doctor'],
     },
   }
 }
 
 export function repositoryDoctor() {
   const required = [
-    'catalog.json', 'components.json', 'templates.json', 'themes.json', 'motion-profiles.json',
+    'catalog.json', 'components.json', 'blocks.json', 'composition-registry.json', 'templates.json', 'themes.json', 'motion-profiles.json',
   ].map((name) => join(paths().manifests, name))
-  const docs = ['quick-start-ai', 'arabic-friendly', 'theme-authoring'].map((name) => join(paths().docs, `${name}.md`))
+  const docs = ['quick-start-ai', 'arabic-friendly', 'theme-authoring', 'composition-registry'].map((name) => join(paths().docs, `${name}.md`))
   const missing = [...required, ...docs].filter((path) => !existsSync(path))
   const motionRegistry = missing.includes(join(paths().manifests, 'motion-profiles.json')) ? null : getMotionRegistry()
   const motionContract = motionRegistry?.profiles?.every((profile) =>
@@ -158,12 +207,30 @@ export function repositoryDoctor() {
     )
   ) === true
   const contractIssues = motionContract ? [] : ['motion-profiles.json: incomplete semantic recipe contract']
+  const compositionRegistry = missing.includes(join(paths().manifests, 'composition-registry.json'))
+    ? null
+    : getCompositionRegistry()
+  const compositionContract = compositionRegistry?.version === 1
+    && compositionRegistry.layoutSchemaVersion === 1
+    && compositionRegistry.definitions?.every((definition) =>
+      definition.id
+      && definition.version === 1
+      && Array.isArray(definition.allowedSpans)
+      && definition.propsSchema?.additionalProperties === false
+      && Array.isArray(definition.states)
+      && definition.agentPermissions
+    ) === true
+  if (!compositionContract) contractIssues.push('composition-registry.json: incomplete block or layout contract')
   return {
-    ok: missing.length === 0 && motionContract,
+    ok: missing.length === 0 && motionContract && compositionContract,
     checks: {
       manifests: required.every(existsSync),
       docs: docs.every(existsSync),
       components: listComponents().length,
+      blocks: listBlocks().length,
+      blockDefinitions: compositionRegistry?.definitions?.length ?? 0,
+      compositionContract,
+      layoutSchemaVersion: compositionRegistry?.layoutSchemaVersion ?? null,
       templates: listTemplates().length,
       themes: listThemes().length,
       motionProfiles: listMotionProfiles().length,

package/lib/composition-runtime.mjs

@@ -0,0 +1,382 @@
+const forbiddenStyleKeys = new Set([
+  'background',
+  'border',
+  'borderColor',
+  'borderRadius',
+  'borderWidth',
+  'boxShadow',
+  'className',
+  'color',
+  'css',
+  'fill',
+  'gap',
+  'margin',
+  'padding',
+  'radius',
+  'shadow',
+  'spacing',
+  'style',
+  'stroke',
+  'sx',
+  'tokenOverrides',
+  'tokens',
+])
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function addIssue(issues, code, path, message, severity = 'error') {
+  issues.push({ code, path, message, severity })
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue)
+  if (!isRecord(value)) return value
+  return Object.fromEntries(
+    Object.keys(value).sort().map((key) => [key, stableValue(value[key])]),
+  )
+}
+
+function equalValue(left, right) {
+  return JSON.stringify(stableValue(left)) === JSON.stringify(stableValue(right))
+}
+
+function findDefinition(registry, type) {
+  return registry.definitions.find((definition) => definition.id === type) ?? null
+}
+
+function inspectForbiddenStyles(value, path, issues) {
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => inspectForbiddenStyles(entry, `${path}[${index}]`, issues))
+    return
+  }
+  if (!isRecord(value)) return
+  for (const [key, entry] of Object.entries(value)) {
+    if (forbiddenStyleKeys.has(key)) {
+      addIssue(
+        issues,
+        'ARBITRARY_STYLE',
+        `${path}.${key}`,
+        `Arbitrary style key "${key}" is not part of the Ceramic semantic contract.`,
+      )
+    }
+    inspectForbiddenStyles(entry, `${path}.${key}`, issues)
+  }
+}
+
+function validateProp(rule, value, path, issues) {
+  if (rule.type === 'string') {
+    if (typeof value !== 'string') {
+      addIssue(issues, 'INVALID_PROP_TYPE', path, 'Expected a string.')
+      return
+    }
+    if (rule.enum && !rule.enum.includes(value)) {
+      addIssue(issues, 'INVALID_PROP_VALUE', path, `Expected one of: ${rule.enum.join(', ')}.`)
+    }
+    return
+  }
+  if (rule.type === 'number') {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      addIssue(issues, 'INVALID_PROP_TYPE', path, 'Expected a finite number.')
+      return
+    }
+    if (rule.minimum !== undefined && value < rule.minimum) {
+      addIssue(issues, 'INVALID_PROP_VALUE', path, `Expected a value greater than or equal to ${rule.minimum}.`)
+    }
+    if (rule.maximum !== undefined && value > rule.maximum) {
+      addIssue(issues, 'INVALID_PROP_VALUE', path, `Expected a value less than or equal to ${rule.maximum}.`)
+    }
+    return
+  }
+  if (rule.type === 'boolean') {
+    if (typeof value !== 'boolean') addIssue(issues, 'INVALID_PROP_TYPE', path, 'Expected a boolean.')
+    return
+  }
+  if (rule.type === 'array') {
+    if (!Array.isArray(value)) {
+      addIssue(issues, 'INVALID_PROP_TYPE', path, 'Expected an array.')
+      return
+    }
+    if (rule.minItems !== undefined && value.length < rule.minItems) {
+      addIssue(issues, 'INVALID_PROP_VALUE', path, `Expected at least ${rule.minItems} item(s).`)
+    }
+    value.forEach((entry, index) => validateProp(rule.items, entry, `${path}[${index}]`, issues))
+  }
+}
+
+function validateProps(definition, props, path, issues) {
+  if (!isRecord(props)) {
+    addIssue(issues, 'INVALID_PROPS', path, 'Block props must be an object.')
+    return
+  }
+  inspectForbiddenStyles(props, path, issues)
+  const schema = definition.propsSchema
+  for (const required of schema.required ?? []) {
+    if (!(required in props)) addIssue(issues, 'MISSING_PROP', `${path}.${required}`, 'Required block prop is missing.')
+  }
+  for (const [key, value] of Object.entries(props)) {
+    const rule = schema.properties[key]
+    if (!rule) {
+      addIssue(issues, 'UNKNOWN_PROP', `${path}.${key}`, `Prop "${key}" is not registered for ${definition.id}.`)
+      continue
+    }
+    validateProp(rule, value, `${path}.${key}`, issues)
+  }
+}
+
+function validatePlacement(definition, placement, columns, path, issues) {
+  if (!isRecord(placement)) {
+    addIssue(issues, 'INVALID_PLACEMENT', path, 'Block placement must be an object.')
+    return
+  }
+  const allowed = new Set(['column', 'span', 'order', 'compactSpan'])
+  for (const key of Object.keys(placement)) {
+    if (!allowed.has(key)) addIssue(issues, 'UNKNOWN_PLACEMENT_KEY', `${path}.${key}`, `Unknown placement key "${key}".`)
+  }
+  for (const key of ['column', 'span', 'order']) {
+    if (!Number.isInteger(placement[key])) {
+      addIssue(issues, 'INVALID_PLACEMENT', `${path}.${key}`, 'Expected an integer.')
+    }
+  }
+  if (!Number.isInteger(placement.column) || !Number.isInteger(placement.span)) return
+  if (placement.column < 1 || placement.span < 1 || placement.column + placement.span - 1 > columns) {
+    addIssue(issues, 'PLACEMENT_OUT_OF_BOUNDS', path, `Placement must fit inside the ${columns}-column layout.`)
+  }
+  if (!definition.allowedSpans.includes(placement.span)) {
+    addIssue(
+      issues,
+      'UNSUPPORTED_SPAN',
+      `${path}.span`,
+      `${definition.id} supports spans ${definition.allowedSpans.join(', ')}.`,
+    )
+  }
+  if (placement.compactSpan !== undefined) {
+    if (!Number.isInteger(placement.compactSpan) || placement.compactSpan < 1 || placement.compactSpan > columns) {
+      addIssue(issues, 'INVALID_COMPACT_SPAN', `${path}.compactSpan`, `Compact span must be between 1 and ${columns}.`)
+    }
+  }
+}
+
+function validateRegions(document, blockIds, issues) {
+  if (document.regions === undefined) return
+  if (!Array.isArray(document.regions)) {
+    addIssue(issues, 'INVALID_REGIONS', 'regions', 'Layout regions must be an array.')
+    return
+  }
+  const regionIds = new Set()
+  document.regions.forEach((region, index) => {
+    const path = `regions[${index}]`
+    if (!isRecord(region)) {
+      addIssue(issues, 'INVALID_REGION', path, 'Region must be an object.')
+      return
+    }
+    if (typeof region.id !== 'string' || !region.id) addIssue(issues, 'INVALID_REGION_ID', `${path}.id`, 'Region id is required.')
+    else if (regionIds.has(region.id)) addIssue(issues, 'DUPLICATE_REGION_ID', `${path}.id`, `Duplicate region id "${region.id}".`)
+    else regionIds.add(region.id)
+    if (typeof region.locked !== 'boolean') addIssue(issues, 'INVALID_REGION_LOCK', `${path}.locked`, 'Region locked must be a boolean.')
+    if (!Array.isArray(region.blockIds)) {
+      addIssue(issues, 'INVALID_REGION_BLOCKS', `${path}.blockIds`, 'Region blockIds must be an array.')
+      return
+    }
+    for (const blockId of region.blockIds) {
+      if (!blockIds.has(blockId)) {
+        addIssue(issues, 'UNKNOWN_REGION_BLOCK', `${path}.blockIds`, `Region references unknown block "${blockId}".`)
+      }
+    }
+  })
+}
+
+export function validateLayoutDocument(registry, document) {
+  const issues = []
+  if (!isRecord(document)) {
+    addIssue(issues, 'INVALID_DOCUMENT', '$', 'Ceramic layout must be an object.')
+    return { ok: false, issues, document: null }
+  }
+  const rootKeys = new Set(['schemaVersion', 'id', 'theme', 'columns', 'blocks', 'regions'])
+  for (const key of Object.keys(document)) {
+    if (!rootKeys.has(key)) addIssue(issues, 'UNKNOWN_DOCUMENT_KEY', key, `Unknown layout key "${key}".`)
+  }
+  if (document.schemaVersion !== registry.layoutSchemaVersion) {
+    addIssue(
+      issues,
+      'UNSUPPORTED_SCHEMA_VERSION',
+      'schemaVersion',
+      `Supported layout schema version is ${registry.layoutSchemaVersion}.`,
+    )
+  }
+  if (typeof document.id !== 'string' || !document.id) addIssue(issues, 'INVALID_LAYOUT_ID', 'id', 'Layout id is required.')
+  if (typeof document.theme !== 'string' || !document.theme) addIssue(issues, 'INVALID_THEME', 'theme', 'A Ceramic theme id is required.')
+  if (!Number.isInteger(document.columns) || document.columns < 1 || document.columns > 24) {
+    addIssue(issues, 'INVALID_COLUMNS', 'columns', 'Columns must be an integer between 1 and 24.')
+  }
+  if (!Array.isArray(document.blocks)) {
+    addIssue(issues, 'INVALID_BLOCKS', 'blocks', 'Layout blocks must be an array.')
+    return { ok: false, issues, document: null }
+  }
+
+  const blockIds = new Set()
+  const columns = Number.isInteger(document.columns) ? document.columns : 12
+  document.blocks.forEach((block, index) => {
+    const path = `blocks[${index}]`
+    if (!isRecord(block)) {
+      addIssue(issues, 'INVALID_BLOCK', path, 'Block must be an object.')
+      return
+    }
+    const allowed = new Set(['id', 'type', 'version', 'placement', 'props', 'locked'])
+    for (const key of Object.keys(block)) {
+      if (!allowed.has(key)) addIssue(issues, 'UNKNOWN_BLOCK_KEY', `${path}.${key}`, `Unknown block key "${key}".`)
+    }
+    if (typeof block.id !== 'string' || !block.id) addIssue(issues, 'INVALID_BLOCK_ID', `${path}.id`, 'Block id is required.')
+    else if (blockIds.has(block.id)) addIssue(issues, 'DUPLICATE_BLOCK_ID', `${path}.id`, `Duplicate block id "${block.id}".`)
+    else blockIds.add(block.id)
+    if (typeof block.type !== 'string') {
+      addIssue(issues, 'INVALID_BLOCK_TYPE', `${path}.type`, 'Block type is required.')
+      return
+    }
+    const definition = findDefinition(registry, block.type)
+    if (!definition) {
+      addIssue(issues, 'UNKNOWN_BLOCK_TYPE', `${path}.type`, `Block type "${block.type}" is not registered.`)
+      return
+    }
+    if (block.version !== definition.version) {
+      addIssue(issues, 'UNSUPPORTED_BLOCK_VERSION', `${path}.version`, `${definition.id} requires version ${definition.version}.`)
+    }
+    if (definition.availability !== 'available') {
+      addIssue(
+        issues,
+        'BLOCK_NOT_RENDERABLE',
+        `${path}.type`,
+        `${definition.id} is registered for planning but has no production renderer yet.`,
+        'warning',
+      )
+    }
+    if (block.locked !== undefined && typeof block.locked !== 'boolean') {
+      addIssue(issues, 'INVALID_BLOCK_LOCK', `${path}.locked`, 'Block locked must be a boolean.')
+    }
+    validatePlacement(definition, block.placement, columns, `${path}.placement`, issues)
+    validateProps(definition, block.props, `${path}.props`, issues)
+  })
+  validateRegions(document, blockIds, issues)
+  return {
+    ok: !issues.some((issue) => issue.severity === 'error'),
+    issues,
+    document,
+  }
+}
+
+function lockedBlockIds(document) {
+  const ids = new Set(document.blocks.filter((block) => block.locked).map((block) => block.id))
+  for (const region of document.regions ?? []) {
+    if (region.locked) for (const blockId of region.blockIds) ids.add(blockId)
+  }
+  return ids
+}
+
+export function validateAgentLayoutMutation(registry, current, next) {
+  const currentResult = validateLayoutDocument(registry, current)
+  const nextResult = validateLayoutDocument(registry, next)
+  const issues = [...currentResult.issues, ...nextResult.issues]
+  if (!currentResult.ok || !nextResult.ok) return { ok: false, issues }
+
+  const currentById = new Map(current.blocks.map((block) => [block.id, block]))
+  const nextById = new Map(next.blocks.map((block) => [block.id, block]))
+  const locked = lockedBlockIds(current)
+
+  for (const block of current.blocks) {
+    const nextBlock = nextById.get(block.id)
+    const definition = findDefinition(registry, block.type)
+    if (!nextBlock) {
+      if (locked.has(block.id)) addIssue(issues, 'BLOCK_LOCKED', `blocks.${block.id}`, 'Locked blocks cannot be removed by an agent.')
+      else if (!definition.agentPermissions.remove) addIssue(issues, 'AGENT_REMOVE_DENIED', `blocks.${block.id}`, 'Agent removal is not allowed.')
+      continue
+    }
+    if (locked.has(block.id) && !equalValue(block, nextBlock)) {
+      addIssue(issues, 'BLOCK_LOCKED', `blocks.${block.id}`, 'Locked blocks cannot be changed by an agent.')
+      continue
+    }
+    if (block.type !== nextBlock.type || block.version !== nextBlock.version) {
+      addIssue(
+        issues,
+        'BLOCK_IDENTITY_CHANGED',
+        `blocks.${block.id}`,
+        'An existing block id cannot be reassigned to a different type or version.',
+      )
+      continue
+    }
+    if (Boolean(block.locked) !== Boolean(nextBlock.locked)) {
+      addIssue(
+        issues,
+        'AGENT_LOCK_DENIED',
+        `blocks.${block.id}.locked`,
+        'Block locks are controlled by the user or Studio, not by an agent.',
+      )
+    }
+    if (!equalValue(block.placement, nextBlock.placement) && !definition.agentPermissions.move) {
+      addIssue(issues, 'AGENT_MOVE_DENIED', `blocks.${block.id}.placement`, 'Agent movement is not allowed.')
+    }
+    const propKeys = new Set([...Object.keys(block.props), ...Object.keys(nextBlock.props)])
+    for (const key of propKeys) {
+      if (!equalValue(block.props[key], nextBlock.props[key])
+        && !definition.agentPermissions.editableProps.includes(key)) {
+        addIssue(issues, 'AGENT_PROP_DENIED', `blocks.${block.id}.props.${key}`, `Agent editing is not allowed for prop "${key}".`)
+      }
+    }
+  }
+
+  for (const block of next.blocks) {
+    if (currentById.has(block.id)) continue
+    const definition = findDefinition(registry, block.type)
+    if (!definition?.agentPermissions.create) {
+      addIssue(issues, 'AGENT_CREATE_DENIED', `blocks.${block.id}`, `Agent creation is not allowed for ${block.type}.`)
+    }
+    if (block.locked) {
+      addIssue(
+        issues,
+        'AGENT_LOCK_DENIED',
+        `blocks.${block.id}.locked`,
+        'An agent cannot create a user-locked block.',
+      )
+    }
+  }
+
+  for (const region of current.regions ?? []) {
+    const nextRegion = (next.regions ?? []).find((candidate) => candidate.id === region.id)
+    if (region.locked && !equalValue(region, nextRegion)) {
+      addIssue(issues, 'REGION_LOCKED', `regions.${region.id}`, 'Locked regions cannot be changed by an agent.')
+      continue
+    }
+    if (nextRegion && Boolean(region.locked) !== Boolean(nextRegion.locked)) {
+      addIssue(
+        issues,
+        'AGENT_LOCK_DENIED',
+        `regions.${region.id}.locked`,
+        'Region locks are controlled by the user or Studio, not by an agent.',
+      )
+    }
+  }
+
+  const currentRegionIds = new Set((current.regions ?? []).map((region) => region.id))
+  for (const region of next.regions ?? []) {
+    if (!currentRegionIds.has(region.id) && region.locked) {
+      addIssue(
+        issues,
+        'AGENT_LOCK_DENIED',
+        `regions.${region.id}.locked`,
+        'An agent cannot create a user-locked region.',
+      )
+    }
+  }
+
+  return { ok: !issues.some((issue) => issue.severity === 'error'), issues }
+}
+
+export function serializeLayoutDocument(registry, document) {
+  const result = validateLayoutDocument(registry, document)
+  if (!result.ok) {
+    const error = new Error('Ceramic layout validation failed.')
+    error.issues = result.issues
+    throw error
+  }
+  return `${JSON.stringify(stableValue(document), null, 2)}\n`
+}

package/lib/telemetry.mjs

@@ -0,0 +1,74 @@
+function safeId(value) {
+  return typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value)
+    ? value
+    : undefined
+}
+
+function randomId() {
+  return globalThis.crypto?.randomUUID?.() ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 14)}`
+}
+
+const SAFE_COMMANDS = new Set([
+  'component',
+  'doctor',
+  'docs',
+  'help',
+  'init',
+  'manifest',
+  'motion',
+  'search',
+  'template',
+  'theme',
+])
+
+export function installCliTelemetry({ command, packageVersion, getErrorCode }) {
+  const endpoint = process.env.CERAMIC_TELEMETRY_ENDPOINT?.replace(/\/$/, '')
+  const ingestKey = process.env.CERAMIC_TELEMETRY_INGEST_KEY
+  const appId = safeId(process.env.CERAMIC_TELEMETRY_APP_ID)
+  const consented = process.env.CERAMIC_TELEMETRY_MODE === 'consented'
+    && process.env.CERAMIC_TELEMETRY_CONSENT === 'granted'
+  const enabled = process.env.CERAMIC_TELEMETRY_ENABLED === 'true'
+    && endpoint
+    && ingestKey
+    && appId
+    && command !== 'mcp'
+  if (!enabled) return
+
+  let sent = false
+  process.on('beforeExit', async () => {
+    if (sent) return
+    sent = true
+    const errorCode = getErrorCode()
+    const success = !errorCode && (process.exitCode ?? 0) === 0
+    if (!consented && success) return
+    const event = {
+      schemaVersion: 1,
+      id: randomId(),
+      occurredAt: new Date().toISOString(),
+      name: 'cli_command_completed',
+      appId,
+      source: 'cli',
+      sessionId: randomId(),
+      accountId: consented ? safeId(process.env.CERAMIC_TELEMETRY_ACCOUNT_ID) : undefined,
+      actorId: consented ? safeId(process.env.CERAMIC_TELEMETRY_ACTOR_ID) : undefined,
+      errorCode,
+      operation: SAFE_COMMANDS.has(command) ? command : 'unknown',
+      packageVersion,
+      release: process.env.CERAMIC_RELEASE?.slice(0, 128),
+      properties: consented ? { success } : undefined,
+    }
+    try {
+      await fetch(`${endpoint}/v1/events`, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'x-ceramic-ingest-key': ingestKey,
+        },
+        body: JSON.stringify(event),
+        signal: AbortSignal.timeout(750),
+      })
+    } catch {
+      // Telemetry is best effort and must never change CLI behavior.
+    }
+  })
+}

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@utopia-studio-design/design-system-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "AI-readable CLI and MCP server for Ceramic Design System",
+  "ceramic": {
+    "designSystem": "^0.7.0"
+  },
   "type": "module",
   "license": "MIT",
   "bin": {