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

package/bin/utopia-ds.mjs

@@ -7,6 +7,7 @@ import {
   listComponents, listDocs, listMotionProfiles, listTemplates, listThemes, mcpLaunch, repositoryDoctor, search,
 } from '../lib/api.mjs'
 import { createTemplateSubmissionUrl, validateTemplateSubmission } from '../lib/template-submission.mjs'
+import { installCliTelemetry } from '../lib/telemetry.mjs'
 
 const args = process.argv.slice(2)
 const command = args.find((arg) => !arg.startsWith('--')) ?? 'help'
@@ -15,6 +16,14 @@ const optionsWithValues = new Set(['--copy', '--theme'])
 const values = commandIndex >= 0 ? positionalValues(args.slice(commandIndex + 1)) : []
 const json = args.includes('--json')
 const dense = args.includes('--dense')
+const cliVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+let telemetryErrorCode
+
+installCliTelemetry({
+  command,
+  packageVersion: cliVersion,
+  getErrorCode: () => telemetryErrorCode,
+})
 
 function positionalValues(input) {
   const positionals = []
@@ -36,6 +45,7 @@ function output(type, data, format = null) {
 }
 
 function fail(message, code = 'ERR_INPUT', suggestions = []) {
+  telemetryErrorCode = code
   if (json) console.error(JSON.stringify({ apiVersion: 1, error: message, code, suggestions }, null, 2))
   else console.error(message)
   process.exitCode = 1

package/data/docs/foundations.md

@@ -74,6 +74,7 @@ Arabic display sizing should follow the Latin display scale at about 95%, rather
 - Runtime recipes use four engine-neutral intents: `feedback`, `page`, `surface`, and `layout`.
 - Components consume `--motion-duration-*` and `--motion-ease-*` roles rather than hardcoded milliseconds or easing curves.
 - `MotionProvider` sets the theme profile and runtime adapter for a subtree. Motion-aware components expose `motion?: boolean` for a local override.
+- `MotionProvider asChild` applies that policy to exactly one semantic subtree root without adding a wrapper. The consumer root must accept `className`, `style`, `data-*`, and its children.
 - `motion={false}` and `prefers-reduced-motion: reduce` disable decorative movement while preserving state changes and accessibility.
 - Directional motion follows logical inline start/end and mirrors in RTL when direction carries meaning.
 - Icon motion follows the action: a bell swings from its top, download moves downward, and copy snaps once. Do not apply a generic bounce.

package/data/docs/observability.md

@@ -0,0 +1,165 @@
+# Ceramic Observability
+
+Ceramic observability has two explicit modes. It is not a hidden backdoor:
+
+- `operational` starts when a host configures and enables a collector. It
+  records only minimized error diagnostics, uses an in-memory page-session ID,
+  ignores actor/account IDs and custom properties, and does not use telemetry
+  cookies, `sessionStorage`, `localStorage`, usage events, or page-view events.
+  It needs no consent click, but hosts must publish notice, assess their lawful
+  basis, and provide an immediate opt-out.
+- `consented` records the allow-listed usage plan and optional opaque cohorts
+  only after explicit consent.
+
+## Decisions this data supports
+
+- Which Ceramic versions, components, and public composition paths are in use?
+- Which anonymous app/account cohort is encountering a repeated error?
+- Which route, viewport class, locale, direction, and release are affected?
+- Did a CLI command succeed or fail, without collecting its arguments or path?
+- Did a fixed error fingerprint stop recurring after a release?
+
+## Data minimization contract
+
+Consented Ceramic telemetry may collect:
+
+- event name and timestamp;
+- opaque app, account, actor, session, and event IDs;
+- component and operation names;
+- package version and application release;
+- route template supplied by the host;
+- locale, direction, and viewport bucket;
+- stable error code, error class, and non-reversible fingerprint;
+- allow-listed short boolean, numeric, or non-email string properties.
+
+Ceramic does not collect:
+
+- names, email addresses, raw database IDs, or authentication identifiers;
+- DOM, form values, user copy, component props, command arguments, or cwd;
+- error messages or raw stacks;
+- IP addresses in retained records;
+- session replay, screenshots, keystrokes, or network payloads.
+
+Operational mode accepts only `component_error` and `runtime_error`, and removes
+`accountId`, `actorId`, custom properties, and persistent telemetry storage even
+if the host passes them.
+
+In consented mode, pass pre-hashed or otherwise opaque `accountId` and `actorId` values. The SDK
+rejects identifiers with whitespace or email syntax. Route resolvers should
+return route templates such as `/projects/:projectId`, not raw URLs containing
+customer identifiers.
+
+## Start the private collector and dashboard
+
+Create two different random secrets:
+
+```sh
+export CERAMIC_TELEMETRY_INGEST_KEY="$(openssl rand -hex 32)"
+export CERAMIC_TELEMETRY_ADMIN_TOKEN="$(openssl rand -hex 32)"
+export CERAMIC_TELEMETRY_ALLOWED_ORIGINS="http://localhost:5173"
+npm run observability:start
+```
+
+Open `http://127.0.0.1:4318` and enter the admin token. The collector binds to
+loopback by default, retains data for 30 days, and stores newline-delimited JSON
+under `.ceramic/observability/`, which is ignored by Git.
+
+The dashboard shows aggregate event, error, app, opaque actor/account,
+component, release, and fingerprint counts plus the latest sanitized events.
+The admin can export the aggregate response or delete all retained events.
+
+For a shared deployment, place the collector behind TLS, SSO or a private
+network, persistent encrypted storage, rate limiting, and backups appropriate
+to the retention policy. Do not expose the Node reference collector directly
+to the public internet. The admin token must never be put in a `VITE_*`
+variable or browser bundle.
+
+## Configure a React/browser consumer
+
+```tsx
+import {
+  configureCeramicTelemetry,
+  installCeramicGlobalErrorTracking,
+  trackCeramicEvent,
+} from '@utopia-studio-design/design-system/Telemetry'
+
+configureCeramicTelemetry({
+  enabled: diagnosticsPreference !== 'disabled',
+  consent: 'unknown',
+  mode: 'operational',
+  appId: 'renacore-dashboard',
+  endpoint: 'https://observability.example.com',
+  ingestKey: publicWriteOnlyIngestKey,
+  packageVersion: '0.6.0',
+  release: appRelease,
+  routeResolver: () => currentRouteTemplate,
+  sampleRate: 0.1,
+})
+
+const removeGlobalTracking = installCeramicGlobalErrorTracking()
+```
+
+Global error listeners are never installed automatically by the package. The
+host owns notice, lawful-basis assessment, opt-out, route normalization,
+installation, and cleanup. Errors are sampled at 100%. Repeated reports with the same
+fingerprint inside two seconds are deduplicated so a component boundary and a
+global listener do not create duplicate incidents.
+
+Ceramic's validated `asChild` paths report `ERR_COMPOSITION_CHILD` through the
+configured client before throwing their explanatory development error. With no
+configured and enabled client, this call is a no-op.
+
+To enable usage events, obtain separate explicit consent and configure
+`mode: "consented"`, `consent: "granted"`, and any opaque cohort IDs.
+
+## Configure CLI diagnostics
+
+CLI telemetry is also disabled by default and never sends command arguments,
+queries, target directories, generated file names, or cwd.
+
+```sh
+export CERAMIC_TELEMETRY_ENABLED=true
+export CERAMIC_TELEMETRY_MODE=operational
+export CERAMIC_TELEMETRY_ENDPOINT=https://observability.example.com
+export CERAMIC_TELEMETRY_INGEST_KEY=replace-with-write-only-key
+export CERAMIC_TELEMETRY_APP_ID=renacore-dashboard
+npx utopia-ds doctor --json
+```
+
+Operational CLI mode sends failed completion only, without actor/account IDs.
+Consented mode additionally requires `CERAMIC_TELEMETRY_MODE=consented` and
+`CERAMIC_TELEMETRY_CONSENT=granted`, and may send successful completion and
+opaque cohorts. Network failure never changes CLI output or exit status.
+
+## Event plan
+
+| Event | Trigger | Decision fields |
+| --- | --- | --- |
+| `app_started` | Consented SDK initialization | app, release, package version |
+| `component_used` | Explicit host instrumentation | component, operation, route |
+| `component_error` | Ceramic component contract failure | component, operation, error code/fingerprint |
+| `runtime_error` | Explicit boundary/global error capture | route, release, error code/fingerprint |
+| `cli_command_completed` | Operational failure or consented CLI process exit | command, success, version |
+
+## Public notice and controls
+
+The Ceramic documentation site publishes `#/terms` and `#/privacy`. Its privacy
+page includes a browser-level operational-diagnostics opt-out and honors Global
+Privacy Control and Do Not Track. Consumer applications must publish their own
+notice and control because they determine the collector, purpose, retention,
+recipients, and jurisdiction.
+
+## Operations and deletion
+
+- Default retention: 30 days; configure 1–365 days.
+- `GET /health`: unauthenticated liveness only.
+- `POST /v1/events`: write-only ingest-key authentication.
+- `GET /v1/summary`: admin Bearer authentication.
+- `DELETE /v1/events`: admin Bearer authentication and full retained-data deletion.
+- `DELETE /v1/events?actorId=<opaque-id>` or `?accountId=<opaque-id>`:
+  selective deletion for a consent withdrawal or data-subject request.
+- Rotate ingest and admin secrets independently.
+- Treat the ingest key as public/write-only when used in browsers.
+- Treat the admin token as a server-side secret.
+- Publish a privacy notice before enabling identifiable account or actor
+  cohorts in a production consumer.

package/data/docs/quick-start-ai.md

@@ -42,6 +42,30 @@ export function SaveAction() {
 }
 ```
 
+For navigation, keep the anchor or framework link as the single interactive
+element:
+
+```tsx
+import Link from 'next/link'
+import { Button } from '@utopia-studio-design/design-system/Button'
+
+<Button asChild variant="outline" size="sm">
+  <a href="/docs">Docs</a>
+</Button>
+
+<Button asChild startContent={<FolderIcon />}>
+  <Link href="/settings">Settings</Link>
+</Button>
+```
+
+`asChild` accepts exactly one non-Fragment React element. The child must forward
+`ref`, `className`, events, `children`, and accessibility props to one
+interactive element. Anchor and Link props such as `href`, `target`, and
+`aria-*` are preserved. When `disabled` or `loading` is true, Ceramic does not
+pass the invalid `disabled` attribute to a link: it applies
+`aria-disabled="true"`, `tabIndex={-1}`, and blocks click activation while
+keeping the original `href`.
+
 ## Set Motion Policy
 
 Ceramic maps BeUI-inspired interaction patterns to semantic roles: `press`, `page`, `expand`, `reveal`, and `icon`. Set the application default once and override only when a local workflow needs to be static.
@@ -96,6 +120,14 @@ The MCP server exposes the same API as the CLI. A generated `.mcp.json` uses:
 
 Available tools include search, component/template/theme/doc discovery, and doctor. An MCP client must never receive capabilities that the CLI cannot expose.
 
+## Optional diagnostics
+
+Ceramic telemetry is disabled by default. If a product has an approved
+diagnostics consent flow, configure the write-only SDK and private dashboard
+using `npx utopia-ds docs observability --dense`. Never collect names, emails,
+DOM content, component props, command arguments, filesystem paths, error
+messages, or raw stacks.
+
 ## Agent Decision Loop
 
 1. Run `manifest --json` to discover supported operations.

package/data/manifests/components.json

@@ -671,7 +671,7 @@
       "sourcePath": "packages/design-system/src/components/Button.tsx",
       "shadcnFoundation": [
         "button",
-        "Slot",
+        "single-element asChild composition",
         "cva"
       ],
       "fallbackToShadcn": "button",
@@ -709,6 +709,7 @@
         "New button colors",
         "Gradient states",
         "Unlabeled icon-only buttons",
+        "Fragments or multiple root children inside Button asChild",
         "Left/right-only layout rules",
         "Utopia brand primitives inside reusable component logic",
         "Motion that bypasses MotionProvider or prefers-reduced-motion"
@@ -718,7 +719,10 @@
           "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false.",
           "contentAlign": "Use 'start' for leading-aligned labels, 'center' for the default action layout, or 'between' to pin endContent to the logical inline end.",
           "startContent": "Optional leading icon or content slot with package-owned alignment.",
-          "endContent": "Optional trailing content slot. With contentAlign='between', it remains pinned while the label truncates."
+          "endContent": "Optional trailing content slot. With contentAlign='between', it remains pinned while the label truncates.",
+          "asChild": "Use with exactly one non-Fragment anchor or framework Link that forwards ref, className, events, children, and accessibility props to one interactive element. Button preserves the child href, target, aria attributes, className, and ref while composing its internal slots inside that element.",
+          "disabled": "Native buttons receive disabled. With asChild, disabled links keep href, receive aria-disabled=true and tabIndex=-1, and block click activation without receiving a disabled attribute.",
+          "loading": "Shows the spinner/loadingText and sets aria-busy. Native buttons are disabled; asChild links use the same aria-disabled, tabIndex, and activation-blocking contract as disabled."
         }
       }
     },
@@ -776,8 +780,9 @@
           "label",
           "children",
           "ButtonGroupSeparator.orientation",
-          "ButtonGroupText.asChild"
+        "ButtonGroupText.asChild"
         ],
+        "composition": "ButtonGroupText.asChild accepts exactly one text-compatible consumer element and preserves it as the semantic root while applying the group text class and props.",
         "shadcnReferencePatterns": [
           "button group",
           "button group with dropdown menu",
@@ -4671,6 +4676,7 @@
       "shadcnFoundation": [
         "toggle",
         "Radix Toggle",
+        "Slottable single-button asChild composition",
         "cva"
       ],
       "fallbackToShadcn": "shadcn/ui toggle",
@@ -4697,6 +4703,7 @@
       "neverInvent": [
         "New pressed colors",
         "Checkbox behavior",
+        "Fragments, multiple roots, anchors, or navigation links inside ToggleButton asChild",
         "Left/right-only state names",
         "Utopia brand primitives inside reusable component logic"
       ],
@@ -4711,9 +4718,11 @@
           "isIconOnly",
           "isDisabled",
           "isLoading",
+          "asChild",
           "variant",
           "size"
         ],
+        "composition": "ToggleButton.asChild requires exactly one non-Fragment button-compatible component that forwards ref, className, events, children, disabled, and accessibility props to one button. Ceramic keeps spinner, icon, pressed icon, and label slots inside that root.",
         "arabicFriendly": [
           "Use logical start/end language for labels and adjacent content.",
           "In RTL, keep persistent pressed state behavior identical; only directional layout and directional icons may mirror.",

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,6 +1,6 @@
 {
   "name": "@utopia-studio-design/design-system-cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "AI-readable CLI and MCP server for Ceramic Design System",
   "type": "module",
   "license": "MIT",