@motion-proto/live-tokens 0.74.0 → 0.76.0

package/bin/cli.mjs

@@ -4,26 +4,27 @@
 //   create <dir>             Scaffold a new app that depends on this package.
 //   setup-claude [--force]   Copy bundled Claude Code skills into ./.claude/skills/.
 //   components [id]          List every component the project has, shipped and its own, with props and tokens.
-//   tokens [--family <name>] List every theme token by family, with its value.
+//   tokens [--scale <name>]  List every design token by scale, with its value.
 //   report                   The project as facts: tokens read, components used, findings by rule. Always exits 0.
 //   check-component [id]     Validate a component (or every authored one) against the create-component skill contract.
-//   check-page [paths...]    Validate pages against the build-page skill contract.
+//   check-page [paths...]    Validate pages against the create-page skill contract.
 //   set-colors <colors>      Build the color identity from 10 OKLCH base colors, into the open buffer.
 //   set-geometry <ops>       Apply radius/padding/gap/border-width ops to the open buffer.
 //   set-type <pairing>       Bind Google Fonts families to the theme's font stacks.
 //   save-theme <name>        Compose the live state into themes/<slug>.json and open it.
 //   migrate [...]            Reconcile tokens.css, the data tree, and route references.
 
-import { cpSync, existsSync, mkdirSync, readdirSync, statSync, writeSync } from 'node:fs';
+import { writeSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import process from 'node:process';
-import { COMPONENT_RULES, checkComponent, discoverComponents, formatReport } from './check-component.mjs';
+import { COMPONENT_RULES, COMPONENT_RULE_FIX, checkComponent, discoverComponents, formatReport } from './check-component.mjs';
 import { PAGE_RULES, checkPages, discoverPages } from './check-page.mjs';
 import { describeComponents, describeTokens, formatComponents, formatTokens } from './lib/catalogue.mjs';
 import { buildReport, formatReport as formatProjectReport } from './lib/report.mjs';
 import { loadVocabulary } from './lib/tokenVocabulary.mjs';
 import {
+  applyCoverageSeverity,
   applySeverity,
   countBySeverity,
   formatFindings,
@@ -39,6 +40,7 @@ import {
 } from './migrate.mjs';
 import { runMigrateRoutes, formatRouteResult } from './migrate-routes.mjs';
 import { runCreate, formatCreateResult } from './create.mjs';
+import { runSetupClaude, formatSetupResult } from './setup-claude.mjs';
 import { runSetColors, formatSetColorsResult } from './set-colors.mjs';
 import { runSetGeometry, formatSetGeometryResult } from './set-geometry.mjs';
 import { runSetType, formatSetTypeResult } from './set-type.mjs';
@@ -48,27 +50,33 @@ const USAGE = `Usage: npx @motion-proto/live-tokens <command> [options]
 
 Commands:
   create <dir> [--force]      Scaffold a new Svelte + Vite app wired up with
-                              live-tokens (editor, components, theme tokens)
+                              live-tokens (editor, components, design tokens)
   setup-claude [--force]      Install bundled Claude Code skills into ./.claude/skills/
   components [id] [--json]    List every component the project has, shipped and
                               its own (src/system/components plus any
-                              "componentDirs" in live-tokens.config.json), with
-                              the props each takes; with an id, that component's
-                              props, variants, tokens, and defaults
-  tokens [--family <name>] [--json]
-                              List every theme token the project's tokens.css
-                              declares, by family, with its value
+                              "componentDirs" in live-tokens.config.json). With
+                              an id, that component's props, variants, tokens,
+                              and defaults
+  tokens [--scale <name>] [--json]
+                              List every design token the project's tokens.css
+                              declares, by scale, with its value
   report [--json]             The project as facts: pending migrations, tokens
                               each component declares and reads, which page
                               renders which component, and both checkers'
                               findings by rule under the project's severities
-                              and under --strict. A reading, not a gate: always
-                              exits 0
-  check-component [id]        Validate <id>'s runtime, editor, and registration
-                              against the live-tokens-create-component contract
-  check-page [paths...]       Validate pages against the live-tokens-build-page
+                              and under --strict. Always exits 0
+  check-component [id] [--tests]
+                              Validate <id>'s runtime, editor, and registration
+                              against the live-tokens-create-component contract.
+                              --tests also runs the registry contract under
+                              vitest and the component contract suites under
+                              Playwright, reporting coverage by rule. Needs
+                              @playwright/test, vitest, and happy-dom; a
+                              missing one is a tests-not-installed finding
+                              naming the install command
+  check-page [paths...]       Validate pages against the live-tokens-create-page
                               contract: catalogue components only, and every CSS
-                              value a theme token. Checks every page under src/
+                              value a design token. Checks every page under src/
                               when given no paths.
 
 check-component and check-page also accept:
@@ -84,44 +92,42 @@ check-component and check-page also accept:
                               OKLCH base colors (see the live-tokens-set-colors
                               skill) and enforce AA contrast on the derived text
                               tokens. Reads the live colors and type and writes
-                              the result to the unsaved colors-and-type buffer,
-                              so save the open theme in the editor or run
-                              save-theme to keep it. Fonts and every override no
-                              palette owns carry forward. --dry-run prints the
-                              contrast report without writing.
+                              the result to the colors-and-type buffer. Run
+                              save-theme to keep it as a theme. Fonts and every
+                              override no palette owns carry forward. --dry-run
+                              prints the contrast report without writing.
   set-geometry <ops.json> [--dry-run]
                               Move radius, padding, gap, and border-width
                               aliases along their token scales (see the
                               live-tokens-set-geometry skill). Reads each
                               component's live config and writes the result to
-                              that component's unsaved buffer, so save the open
-                              theme in the editor to keep it. --dry-run prints
-                              the report without writing.
+                              that component's buffer. Run save-theme to keep it
+                              as a theme. --dry-run prints the report without
+                              writing.
   set-type <pairing.json> [--dry-run] [--no-verify]
                               Bind Google Fonts families to --font-display,
                               --font-sans, --font-serif, --font-mono and
                               --font-editorial (see
                               the live-tokens-set-type skill). Each family is
                               verified against the Google Fonts API and the URL
-                              is negotiated from the weights it actually has.
-                              Writes the result to the unsaved colors-and-type
-                              buffer, so save the open theme in the editor to
-                              keep it. --dry-run prints the report without
-                              writing; --no-verify skips the network and
-                              requires an explicit URL per family.
+                              is negotiated from the weights it has. Writes the
+                              result to the colors-and-type buffer. Run
+                              save-theme to keep it as a theme. --dry-run prints
+                              the report without writing. --no-verify skips the
+                              network and requires an explicit URL per family.
   save-theme <name> [--no-activate] [--dry-run]
-                              Compose the live state (the unsaved buffers, the
-                              open theme under them, the shipped defaults under
-                              that) into themes/<slug>.json and open it, which
-                              clears the buffers. With no unsaved edits it saves
-                              a copy of the open theme under the new name.
-                              Opening never changes what your site ships; Adopt
-                              in the editor does that. --no-activate writes the
-                              theme and leaves the live state alone, so a set of
-                              themes comes off one starting look; --dry-run
-                              prints the report without writing.
+                              Compose the live state (the buffers, the open
+                              theme under them, the shipped defaults under that)
+                              into themes/<slug>.json and load it, which clears
+                              the buffers. With no buffer it saves a copy of the
+                              open theme under the new name. Loading never
+                              changes what the site ships. Adopt in the editor
+                              does that. --no-activate writes the theme and does
+                              not load it, so a set of themes comes off one
+                              starting theme. --dry-run prints the report
+                              without writing.
   migrate [--check] [--write] [--tokens <path>]
-                              Reconcile your project with the installed package:
+                              Reconcile the project with the installed package:
                               applies additive tokens.css migrations, moves a
                               pre-0.48 data tree onto the current directory
                               names, heals what the retired pointer files named,
@@ -177,14 +183,19 @@ if (command === 'create') {
   }
 }
 
-function reportChecks(label, findings, checked, rules, opts) {
-  const resolved = applySeverity(findings, rules, opts, readChecksConfig(process.cwd()));
+function reportChecks(label, findings, checked, rules, opts, { coverage, hardFailure, fixes } = {}) {
+  const checksConfig = readChecksConfig(process.cwd());
+  const resolved = applySeverity(findings, rules, opts, checksConfig, fixes ?? {});
+  const resolvedCoverage = coverage ? applyCoverageSeverity(coverage, rules, opts, checksConfig) : coverage;
   console.log(
     opts.json
-      ? toJson(resolved, { label, checked })
+      ? toJson(resolved, { label, checked, coverage: resolvedCoverage })
       : formatFindings(resolved, { label, checked }),
   );
-  process.exit(countBySeverity(resolved).errors === 0 ? 0 : 1);
+  // Decision 2: a missing tool or a setup failure under --tests is an error
+  // even if a project silenced its rule id, since silencing it would read as
+  // "the tests passed" rather than "the tests did not run".
+  process.exit(countBySeverity(resolved).errors === 0 && !hardFailure ? 0 : 1);
 }
 
 if (command === 'components') {
@@ -198,14 +209,14 @@ if (command === 'components') {
 
 if (command === 'tokens') {
   const opts = parseCheckFlags(rest);
-  const at = opts.rest.indexOf('--family');
-  const family = at >= 0 ? opts.rest[at + 1] : undefined;
+  const at = opts.rest.indexOf('--scale');
+  const scale = at >= 0 ? opts.rest[at + 1] : undefined;
   const desc = describeTokens(loadVocabulary());
-  if (family && !desc.families.some((f) => f.family === family)) fail(formatTokens(desc, { family }));
+  if (scale && !desc.scales.some((s) => s.scale === scale)) fail(formatTokens(desc, { scale }));
   writeOut(
     opts.json
-      ? JSON.stringify(family ? desc.families.find((f) => f.family === family) : desc, null, 2)
-      : formatTokens(desc, { family }),
+      ? JSON.stringify(scale ? desc.scales.find((s) => s.scale === scale) : desc, null, 2)
+      : formatTokens(desc, { scale }),
   );
   process.exit(0);
 }
@@ -231,18 +242,28 @@ if (command === 'report') {
 if (command === 'check-component') {
   const opts = parseCheckFlags(rest);
   const ids = opts.rest.length > 0 ? [opts.rest[0]] : discoverComponents();
-  if (ids.length === 0) {
+  if (ids.length === 0 && !opts.tests) {
     console.log('✓ check-component: no component authored under src/system/components yet.');
     process.exit(0);
   }
   const results = ids.map((id) => [id, checkComponent(id)]);
-  if (ids.length === 1 && !opts.json && !opts.strict && opts.off.length + opts.warn.length + opts.error.length === 0) {
+  if (!opts.tests && ids.length === 1 && !opts.json && !opts.strict && opts.off.length + opts.warn.length + opts.error.length === 0) {
     const [id, result] = results[0];
     console.log(formatReport(id, result));
     process.exit(result.errors.length === 0 ? 0 : 1);
   }
-  const label = ids.length === 1 ? `check-component ${ids[0]}` : 'check-component';
-  reportChecks(label, results.flatMap(([, r]) => r.findings), ids.length, COMPONENT_RULES, opts);
+  const label = ids.length === 1 ? `check-component ${ids[0]}${opts.tests ? ' --tests' : ''}` : `check-component${opts.tests ? ' --tests' : ''}`;
+  if (!opts.tests) {
+    reportChecks(label, results.flatMap(([, r]) => r.findings), ids.length, COMPONENT_RULES, opts, { fixes: COMPONENT_RULE_FIX });
+  }
+  const { hasHardFailure, runContractTests } = await import('./contractRunner.mjs');
+  const testOutcome = await runContractTests(opts.rest[0], { root: process.cwd() });
+  const findings = [...results.flatMap(([, r]) => r.findings), ...testOutcome.findings];
+  reportChecks(label, findings, Math.max(ids.length, 1), COMPONENT_RULES, opts, {
+    fixes: COMPONENT_RULE_FIX,
+    coverage: testOutcome.coverage,
+    hardFailure: hasHardFailure(testOutcome.findings),
+  });
 }
 
 if (command === 'check-page') {
@@ -265,7 +286,7 @@ if (command === 'set-colors') {
   }
   if (rest.includes('--carry-from')) {
     fail(
-      `set-colors has no --carry-from: it reads the live look and edits it in place, so a second theme ` +
+      `set-colors has no --carry-from: it reads the live theme and edits it in place, so a second theme ` +
         `already starts from the first. Run save-theme --no-activate between themes.`,
     );
   }
@@ -387,61 +408,14 @@ if (process.platform === 'win32') {
   fail('setup-claude is macOS/Linux only.');
 }
 
-const force = rest.includes('--force');
-
-const srcSkills = join(pkgRoot, '.claude', 'skills');
-
-if (!existsSync(srcSkills)) {
-  fail(`No bundled skills found at ${srcSkills}. Is the package installed correctly?`);
-}
-
-const skills = readdirSync(srcSkills).filter((name) =>
-  statSync(join(srcSkills, name)).isDirectory(),
-);
-
-if (skills.length === 0) {
-  fail('No bundled skills to install.');
-}
-
-const destSkills = join(process.cwd(), '.claude', 'skills');
-mkdirSync(destSkills, { recursive: true });
-
-let installed = 0;
-let skipped = 0;
-for (const skill of skills) {
-  const src = join(srcSkills, skill);
-  const dest = join(destSkills, skill);
-  if (existsSync(dest) && !force) {
-    console.log(`  skip  ${skill}  (already exists; pass --force to overwrite)`);
-    skipped++;
-    continue;
-  }
-  cpSync(src, dest, { recursive: true });
-  console.log(`  ok    ${skill}`);
-  installed++;
-}
-
-console.log(`\n${installed} installed, ${skipped} skipped → ${destSkills}`);
-
-const SAMPLE_PROMPTS = {
-  'live-tokens-build-page': 'build a pricing page using live-tokens components',
-  'live-tokens-pick-component': "what's the difference between TabBar and SegmentedControl?",
-  'live-tokens-create-component': 'author a new Toggle component for my live-tokens project',
-  'live-tokens-create-theme': 'make me a bright and cheerful theme',
-  'live-tokens-set-colors': 'give me a cooler palette, same fonts',
-  'live-tokens-set-type': 'pair some fonts for this theme',
-  'live-tokens-set-geometry': 'make the buttons pill shaped',
-  'live-tokens-fix-findings': 'make check:design pass',
-  'live-tokens-check-compliance': 'check this project against the design system',
-};
-
-const installedSamples = skills
-  .map((s) => SAMPLE_PROMPTS[s] && [s, SAMPLE_PROMPTS[s]])
-  .filter(Boolean);
-
-if (installedSamples.length > 0) {
-  console.log(`\nIn Claude Code, prompts like these auto-trigger the matching skill:`);
-  for (const [skill, prompt] of installedSamples) {
-    console.log(`  • "${prompt}"\n    → ${skill}`);
-  }
+try {
+  const result = runSetupClaude({
+    pkgRoot,
+    cwd: process.cwd(),
+    force: rest.includes('--force'),
+  });
+  console.log(formatSetupResult(result));
+  process.exit(0);
+} catch (err) {
+  fail(err instanceof Error ? err.message : String(err));
 }