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

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)), '..')
@@ -59,6 +60,186 @@ export function listTemplates() {
   return readJson(join(paths().manifests, 'templates.json')).templates
 }
 
+export function getUxPatternRegistry() {
+  return readJson(join(paths().manifests, 'ux-patterns.json'))
+}
+
+export function listUxPatterns() {
+  return getUxPatternRegistry().patterns
+}
+
+export function listUiParts() {
+  return readJson(join(paths().manifests, 'ui-patterns.json')).parts
+}
+
+export function listUxExamples() {
+  return readJson(join(paths().manifests, 'ux-examples.json')).examples
+}
+
+/** Complete source evidence, distinct from runnable Ceramic examples. */
+export function listUxSourcePatterns() {
+  const inventory = readJson(join(paths().manifests, 'ux-source-inventory.json'))
+  const examples = listUxExamples()
+  return inventory.entries.map(({ evidence, ...entry }) => ({ ...entry,
+    examples: examples.filter(example => (example.sourcePatterns ?? [example.sourcePattern]).includes(entry.id)).map(example => example.id),
+  }))
+}
+
+export function findUxSourcePatterns(goal) {
+  if (typeof goal !== 'string' || !goal.trim() || goal.length > 2000) return { ok: false, code: 'INVALID_GOAL' }
+  const words = goal.toLowerCase().split(/\s+/).filter(word => word.length > 1)
+  const candidates = listUxSourcePatterns().map(entry => {
+    const text = [entry.id, entry.category, ...Object.values(entry.title), ...(entry.keywords ?? []), ...entry.fragments.map(f => f.id)].join(' ').toLowerCase()
+    const aliases = (entry.keywords ?? []).filter(keyword => goal.toLowerCase().includes(keyword.toLowerCase()))
+    return { ...entry, score: words.filter(word => text.includes(word)).length + aliases.length }
+  }).filter(entry => entry.score > 0).sort((a,b) => b.score - a.score)
+  return { ok: true, candidates, guidance: 'AI selects only relevant fragments, without a user selection wizard. Prefer runnable examples when available. source-indexed means original evidence only, NOT an implemented Ceramic component. Use get_ux_source_part for one named fragment. No match means use normal Ceramic components.' }
+}
+
+export function getUxSourcePart(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some(key => !['id', 'part', 'theme'].includes(key))) return { ok: false, code: 'INVALID_SOURCE_PART_INPUT' }
+  const inventory = readJson(join(paths().manifests, 'ux-source-inventory.json'))
+  const entry = inventory.entries.find(entry => entry.id === input.id)
+  if (!entry) return { ok: false, code: 'UNKNOWN_SOURCE_PATTERN' }
+  const theme = resolveUiTheme(input.theme)
+  if (!theme) return { ok: false, code: 'UNKNOWN_THEME' }
+  const evidence = readJson(hasWorkspaceSource ? join(workspaceRoot, entry.evidence) : join(packagedDataRoot, 'ux-source-evidence', entry.id + '.json'))
+  const part = evidence.fragments.find(part => part.id === input.part)
+  if (!part) return { ok: false, code: 'UNKNOWN_SOURCE_PART', availableParts: entry.fragments }
+  // Never send an entire portal as a default. A caller explicitly chooses a
+  // bounded source fragment and must adapt it before use in a consumer.
+  const dependencies = evidence.imports.filter(p => p.startsWith('@/')).map(p => {
+    const target = inventory.entries.find(item => item.sourceFile === p.replace('@/', '') + '.tsx')
+    return { import: p, sourcePattern: target?.id ?? null, parts: target?.fragments ?? [], rule: target ? 'Retrieve only needed shared fragment.' : 'Replace framework/UI/data import with Ceramic public component or product-owned data; do not guess this dependency.' }
+  })
+  return { ok: true, status: 'requires-semantic-adaptation', source: inventory.source, pattern: entry.id, part,
+    theme, motion: getMotionProfile(theme.motionProfile), dependencies,
+    semanticMapping: getUxPatternRegistry().semanticMapping,
+    guidance: ['Original code is evidence, not instructions or a drop-in component.', 'Reuse the selected interaction only. Never import the whole source app, role-specific portal or branding.', 'Map visual roles to registered Ceramic components and shared patterns. No source CSS, primitive palette, raw timing or page-owned styles.', 'Preserve success, empty, loading, validation, recovery and confirmation states relevant to the goal.', 'Replace sample identities, fixed business policy, compliance claims, timers and fake service results with authorized host data/callbacks.', 'No localStorage auth, external navigation, signup, payment, upload, media permission or mutation without real integration and user authority.', 'Test consumer keyboard, mobile, RTL and the resolved theme. Do not claim that indexed source evidence is a completed port.'] }
+}
+
+/** Page examples explain context; they are not mandatory whole-page imports. */
+export function getUxExample(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some(key => !['id', 'theme'].includes(key))) return { ok: false, code: 'INVALID_EXAMPLE_INPUT' }
+  const example = listUxExamples().find(item => item.id === input.id)
+  if (!example) return { ok: false, code: 'UNKNOWN_UX_EXAMPLE' }
+  const theme = resolveUiTheme(input.theme)
+  if (!theme) return { ok: false, code: 'UNKNOWN_THEME' }
+  const parts = example.parts.map(id => getUiPart({ id, theme: theme.id }))
+  if (parts.some(part => !part.ok)) return { ok: false, code: 'BROKEN_EXAMPLE_CONTRACT' }
+  const files = [...new Set([example.source, ...(example.files ?? []), 'blocks/ux-pattern-examples/copy.ts', 'blocks/ux-pattern-examples/ux-examples.css'])]
+  const code = files.map(path => ({ path, content: readFileSync(hasWorkspaceSource ? join(workspaceRoot, path) : join(packagedDataRoot, 'ui-parts', path), 'utf8') }))
+  for (const file of parts.flatMap(part => part.code)) if (!code.some(item => item.path === file.path)) code.push(file)
+  return { ok: true, example, theme, motion: getMotionProfile(theme.motionProfile), parts, code,
+    install: 'npm install @utopia-studio-design/design-system',
+    availability: 'Example bundles and MCP tools are available in Ceramic CLI 0.8.0 and later.',
+    guidance: 'Inspect the contextual page example, then reuse only the parts that fit the user goal. Never require the user to browse or select examples first. Keep shared semantic CSS and the resolved user/room theme; Cloudblur is the fallback. Replace fixture data with authorized product data and callbacks. Demo signup, consent, completion and review do not create accounts, save, approve or deploy anything.' }
+}
+
+/** Candidate discovery, not a command to add every matching part. The coding
+ * agent decides fit in context; the user never has to choose these parts. */
+export function findUiParts(goal) {
+  if (typeof goal !== 'string' || !goal.trim() || goal.length > 2000) return { ok: false, code: 'INVALID_GOAL' }
+  const text = goal.toLowerCase()
+  const candidates = listUiParts().map(part => {
+    const matches = part.keywords.filter(keyword => text.includes(keyword.toLowerCase()))
+    return { ...part, score: matches.length, matchedIntents: matches }
+  }).filter(part => part.score > 0).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+  const sourceCandidates = findUxSourcePatterns(goal).candidates.slice(0, 8)
+  return { ok: true, candidates, sourceCandidates, guidance: 'The AI must check useWhen/avoidWhen against the goal and use only needed parts. Never ask the user to pick parts. Prefer ready Ceramic parts. sourceCandidates expose additional original interactions requiring semantic adaptation via get_ux_source_part, not whole-page import. If nothing fits, use ordinary components; never force a pattern.' }
+}
+
+function resolveUiTheme(theme) {
+  const room = getRoomContext()
+  const id = theme ?? room?.themeId ?? room?.theme?.id ?? 'utopia-cloudblur'
+  // An invalid explicit/custom theme is not permission to silently rebrand.
+  return typeof id === 'string' && id.trim() ? getTheme(id) : null
+}
+
+export function getUiPart(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some(key => !['id', 'theme'].includes(key))) return { ok: false, code: 'INVALID_PART_INPUT' }
+  const part = listUiParts().find(part => part.id === input.id)
+  if (!part) return { ok: false, code: 'UNKNOWN_UI_PART' }
+  const theme = resolveUiTheme(input.theme)
+  if (!theme) return { ok: false, code: 'UNKNOWN_THEME' }
+  const files = [...new Set([part.source, part.styles, ...(part.files ?? []), ...(part.id === 'choice-cards' || part.id === 'list-filters' || part.id === 'review-list' ? ['blocks/semantic-pattern-parts/types.ts'] : [])])]
+  const code = files.map(path => ({ path, content: readFileSync(hasWorkspaceSource ? join(workspaceRoot, path) : join(packagedDataRoot, 'ui-parts', path), 'utf8') }))
+  return { ok: true, part, theme, motion: getMotionProfile(theme.motionProfile), components: part.components.map(getComponent), code, guidance: 'Copy only this reusable export and its dependencies. All labels, data and callbacks are product-owned. Do not copy a screen shell or sample identities. CSS belongs to the shared composition, not the page. Apply the resolved theme to the common host. Never turn fixture results into real authorization.' }
+}
+
+export function prepareUiComposition(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some(key => !['goal', 'theme'].includes(key))) return { ok: false, code: 'INVALID_COMPOSITION_INPUT' }
+  const found = findUiParts(input.goal)
+  if (!found.ok) return found
+  const theme = resolveUiTheme(input.theme)
+  if (!theme) return { ok: false, code: 'UNKNOWN_THEME' }
+  const selected = found.candidates.slice(0, 4)
+  const parts = selected.map(part => getUiPart({ id: part.id, theme: theme.id }))
+  const ids = selected.map(part => part.id)
+  const bindings = []
+  if (ids.includes('list-filters') && ids.includes('review-list')) bindings.push({ from: 'ListFilters.query/status', via: 'Host-owned state and authorized filtered query', to: 'ReviewList.rows', rule: 'Reset both filter values; render empty/loading/error states from the query result.' })
+  if (ids.includes('metric-summary') && ids.includes('review-list')) bindings.push({ from: 'Host-authorized rows and scope', to: 'KPIGrid.metrics', rule: 'Calculate counts for the same filter scope. Never invent totals from unloaded/paginated rows.' })
+  if (ids.includes('outcome-notice')) bindings.push({ from: 'Confirmed service result', to: 'OutcomeNotice', rule: 'Show success only after confirmation; retry must call a real recovery callback.' })
+  return { ok: true, status: selected.length ? 'composition-proposal' : found.sourceCandidates.length ? 'source-adaptation-candidates' : 'no-pattern-needed', goal: input.goal.trim(), theme: theme.id, parts, sourceCandidates: found.sourceCandidates, bindings, guidance: found.guidance, nextSteps: ['AI checks whether each candidate fits; discard unrelated parts without making the user choose.', 'When a relevant interaction exists only in sourceCandidates, use get_ux_source_part to inspect just that fragment and adapt its semantics; do not call it a ready Ceramic port.', 'Compose the selected exports around host-owned product data and callbacks. No complete portal or page import.', 'Use existing Ceramic components for anything not covered; patterns are optional.', 'Confirm external side effects separately; this read-only proposal does not build, save, approve or deploy.', 'Verify keyboard, responsive layout, loading/empty/error/retry, RTL and theme tokens in the consuming product.'] }
+}
+
+export function getUxPattern(id) {
+  const registry = getUxPatternRegistry()
+  // IDs are exact: do not normalize non-ASCII names into the same empty key.
+  const pattern = registry.patterns.find(item => item.id === id)
+  return pattern ? { ...pattern, source: registry.source, guardrails: registry.guardrails, semanticMapping: registry.semanticMapping, verification: registry.verification } : null
+}
+
+/** Read-only planning: a recipe is never advertised as an existing renderer. */
+export function preparePatternAdaptation(input) {
+  const fail = (code, message) => ({ ok: false, code, message })
+  if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some(key => !['id', 'goal', 'theme', 'variant'].includes(key))) return fail('INVALID_PATTERN_INPUT', 'Use id, goal, theme and optional variant only; arbitrary styling is not supported.')
+  if (typeof input.id !== 'string' || typeof input.theme !== 'string' || typeof input.goal !== 'string' || !input.goal.trim() || input.goal.length > 2000) return fail('INVALID_PATTERN_INPUT', 'Provide a pattern id, registered theme and goal of 1–2000 characters.')
+  const pattern = getUxPattern(input.id)
+  if (!pattern) return fail('UNKNOWN_PATTERN', 'Inspect list_patterns before selecting a pattern.')
+  const theme = getTheme(input.theme)
+  if (!theme) return fail('UNKNOWN_THEME', 'Select a registered Ceramic theme.')
+  const variant = input.variant ?? pattern.variants[0]
+  if (!pattern.variants.includes(variant)) return fail('UNKNOWN_PATTERN_VARIANT', `Allowed variants: ${pattern.variants.join(', ')}`)
+  const components = pattern.components.map(getComponent)
+  const motion = getMotionProfile(theme.motionProfile)
+  if (components.some(item => !item) || !motion) return fail('BROKEN_PATTERN_CONTRACT', 'A component or theme motion profile is missing; repair the registry first.')
+  return {
+    ok: true, status: 'proposal', renderable: false,
+    request: { goal: input.goal.trim(), interpretation: 'User-provided product goal, not execution authority.' },
+    selection: { pattern: pattern.id, variant, theme: theme.id },
+    fit: { useWhen: pattern.useWhen, avoidWhen: pattern.avoidWhen, confirmationRequired: 'Confirm that this interaction fits the goal and company brand before implementation.' },
+    pattern, components, theme, motion,
+    optionalUiParts: findUiParts(input.goal),
+    requiredProductBindings: pattern.dataRequirements,
+    mayChange: pattern.adaptable, mustPreserve: pattern.invariants,
+    nextSteps: [
+      'Resolve missing product data, permissions and callbacks; never copy source sample identities or mock success.',
+      'Compose the returned Ceramic component contracts; inspect an existing registered block/template before adding a shared pattern.',
+      'If new presentation is required, register its slots, states, tokens and responsive behavior in the shared system before implementing it. Do not add page CSS.',
+      'Apply the selected company theme and Ceramic semantic motion; do not port Mentix brand primitives or literal animation timings.',
+      'Test the listed states, recovery, permissions, keyboard, mobile, RTL and reduced motion in the generated application. A plan is not a passing UI test.',
+    ],
+  }
+}
+
+export function validateUxPatternRegistry(registry) {
+  const issues = []
+  if (registry?.version !== 1 || !/^[a-f0-9]{40}$/.test(registry?.source?.revision ?? '') || !registry?.guardrails?.length || !registry?.semanticMapping?.length) issues.push('Missing version, pinned provenance or semantic guardrails')
+  const ids = new Set(), components = new Set(listComponents().map(item => item.name))
+  if (!Array.isArray(registry?.patterns) || !registry.patterns.length) return { ok: false, issues: [...issues, 'No UX patterns'] }
+  for (const item of registry.patterns) {
+    if (!item || typeof item.id !== 'string' || ids.has(item.id)) { issues.push('Missing or duplicate pattern id'); continue }
+    ids.add(item.id)
+    if (item.availability !== 'recipe' || item.renderable !== false || !item.useWhen || !item.avoidWhen) issues.push(`${item.id}: recipe status or selection guidance missing`)
+    for (const field of ['variants', 'components', 'slots', 'states', 'dataRequirements', 'invariants', 'adaptable', 'sourceFiles', 'keywords']) {
+      if (!Array.isArray(item[field]) || !item[field].length || item[field].some(value => typeof value !== 'string' || !value)) issues.push(`${item.id}: ${field} incomplete`)
+    }
+    if (Array.isArray(item.components) && item.components.some(name => !components.has(name))) issues.push(`${item.id}: unknown Ceramic component`)
+  }
+  return { ok: issues.length === 0, issues }
+}
+
 export function listBlocks() {
   return readJson(join(paths().manifests, 'blocks.json')).blocks
 }
@@ -229,6 +410,10 @@ export function search(query) {
   const terms = String(query).toLowerCase().split(/\s+/).filter(Boolean)
   const score = (text) => terms.reduce((total, term) => total + (text.toLowerCase().includes(term) ? 1 : 0), 0)
   const results = [
+    ...listUiParts().map((item) => ({ kind: 'ui-part', id: item.id, title: item.title.en, summary: [Object.values(item.title).join(' '), item.useWhen, ...item.keywords].join(' '), item })),
+    ...listUxExamples().map(item => ({ kind: 'ux-example', id: item.id, title: item.title.en, summary: [...Object.values(item.title), ...Object.values(item.description), ...item.parts].join(' '), item })),
+    ...listUxSourcePatterns().map(item => ({ kind: 'ux-source-pattern', id: item.id, title: item.title.en, summary: [item.category, ...Object.values(item.title), ...item.fragments.map(f => f.id)].join(' '), item })),
+    ...listUxPatterns().map((item) => ({ kind: 'ux-pattern', id: item.id, title: item.title, summary: [item.useWhen, ...item.keywords].join(' '), item })),
     ...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 })),
@@ -240,7 +425,7 @@ export function search(query) {
     ...listDocs().map((topic) => ({ kind: 'docs', id: topic, title: topic, summary: getDoc(topic)?.content.slice(0, 500) ?? '', item: { topic } })),
   ]
   return results
-    .map((result) => ({ ...result, score: score(`${result.title} ${result.summary}`) }))
+    .map((result) => ({ ...result, score: score(`${result.id} ${result.title} ${result.summary}`) }))
     .filter((result) => result.score > 0)
     .sort((a, b) => b.score - a.score || a.title.localeCompare(b.title))
     .map(({ summary: _summary, ...result }) => result)
@@ -260,6 +445,7 @@ export function capabilityManifest() {
       { name: 'init', args: ['[directory]'], flags: ['--yes', '--theme <id>'], responseType: 'init-result' },
       { name: 'room', args: ['connect'], flags: ['--id <id>', '--slug <slug>', '--name <room>', '--brand <brand>', '--source <mode>', '--client <client>', '--directory <path>'], responseType: 'room-connect-result' },
       { name: 'search', args: ['<query>'], flags: [], responseType: 'search-results' },
+      { name: 'pattern', args: ['<id>|--list'], flags: ['--goal <text>', '--theme <id>', '--variant <id>'], responseType: 'ux-pattern|ux-pattern-list|pattern-adaptation-plan' },
       { 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' },
@@ -275,14 +461,14 @@ 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', 'validate_brandbook', 'list_docs', 'get_docs', 'doctor'],
+      tools: ['get_room_context', 'search', 'list_ux_source_patterns', 'find_ux_source_patterns', 'get_ux_source_part', 'list_ux_examples', 'get_ux_example', 'find_ui_parts', 'get_ui_part', 'prepare_ui_composition', 'list_patterns', 'get_pattern', 'prepare_pattern_adaptation', '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'],
     },
   }
 }
 
 export function repositoryDoctor() {
   const required = [
-    'catalog.json', 'components.json', 'blocks.json', 'composition-registry.json', 'templates.json', 'themes.json', 'motion-profiles.json', 'logo-skills.json', 'brandbook-skill.json',
+    'catalog.json', 'components.json', 'blocks.json', 'composition-registry.json', 'templates.json', 'themes.json', 'motion-profiles.json', 'logo-skills.json', 'ux-patterns.json', 'brandbook-skill.json',
   ].map((name) => join(paths().manifests, name))
   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))
@@ -307,8 +493,10 @@ export function repositoryDoctor() {
       && definition.agentPermissions
     ) === true
   if (!compositionContract) contractIssues.push('composition-registry.json: incomplete block or layout contract')
+  const uxPatterns = missing.includes(join(paths().manifests, 'ux-patterns.json')) ? { ok: false, issues: ['Missing UX pattern registry'] } : validateUxPatternRegistry(getUxPatternRegistry())
+  contractIssues.push(...uxPatterns.issues)
   return {
-    ok: missing.length === 0 && motionContract && compositionContract,
+    ok: missing.length === 0 && motionContract && compositionContract && uxPatterns.ok,
     checks: {
       manifests: required.every(existsSync),
       docs: docs.every(existsSync),
@@ -316,6 +504,7 @@ export function repositoryDoctor() {
       blocks: listBlocks().length,
       blockDefinitions: compositionRegistry?.definitions?.length ?? 0,
       compositionContract,
+      uxPatternContract: uxPatterns.ok,
       layoutSchemaVersion: compositionRegistry?.layoutSchemaVersion ?? null,
       templates: listTemplates().length,
       themes: listThemes().length,

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@utopia-studio-design/design-system-cli",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "AI-readable CLI and MCP server for Ceramic Design System",
   "ceramic": {
-    "designSystem": "^0.10.0"
+    "designSystem": "^0.11.0"
   },
   "type": "module",
   "license": "MIT",