@motion-proto/live-tokens 0.72.1 → 0.74.0

package/bin/cli.mjs

@@ -8,9 +8,10 @@
 //   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.
-//   generate-theme <brief>   Build a theme from a 10-seed OKLCH brief and open it.
-//   adjust <ops.json>        Apply radius/padding/gap/border-width ops to the open buffer.
-//   set-fonts <brief.json>   Bind Google Fonts families to the theme's font stacks.
+//   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';
@@ -38,9 +39,10 @@ import {
 } from './migrate.mjs';
 import { runMigrateRoutes, formatRouteResult } from './migrate-routes.mjs';
 import { runCreate, formatCreateResult } from './create.mjs';
-import { runGenerateTheme, formatGenerateThemeResult } from './generate-theme.mjs';
-import { runAdjust, formatAdjustResult } from './adjust.mjs';
-import { runSetFonts, formatSetFontsResult } from './set-fonts.mjs';
+import { runSetColors, formatSetColorsResult } from './set-colors.mjs';
+import { runSetGeometry, formatSetGeometryResult } from './set-geometry.mjs';
+import { runSetType, formatSetTypeResult } from './set-type.mjs';
+import { runSaveTheme, formatSaveThemeResult } from './save-theme.mjs';
 
 const USAGE = `Usage: npx @motion-proto/live-tokens <command> [options]
 
@@ -69,7 +71,7 @@ Commands:
                               value a theme token. Checks every page under src/
                               when given no paths.
 
-Both check commands accept:
+check-component and check-page also accept:
   --json                      Machine-readable findings, for a skill to iterate
                               against until the exit code is 0
   --strict                    Treat warnings as errors
@@ -77,31 +79,29 @@ Both check commands accept:
                               (or set "checks": { "rules": {...} } in
                               live-tokens.config.json; "checks": { "exclude":
                               [...] } drops paths from discovery entirely)
-  generate-theme <brief.json> [--no-activate] [--dry-run] [--carry-from <name>]
-                              Build a full theme from a 10-seed OKLCH brief
-                              (see the live-tokens-generate-theme skill),
-                              enforce AA contrast on derived text tokens, write
-                              themes/<slug>.json, and open it in the editor.
-                              Opening never changes what your site ships; Adopt
-                              in the editor does that.
-                              --no-activate writes the theme without opening it;
-                              --dry-run prints the contrast report without
-                              writing. Non-color content (gradients, fonts,
-                              component aliases) carries forward from the live
-                              look, or from theme <name> with --carry-from.
-  adjust <ops.json> [--dry-run]
+  set-colors <base-colors.json> [--dry-run]
+                              Build the theme's whole color identity from 10
+                              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.
+  set-geometry <ops.json> [--dry-run]
                               Move radius, padding, gap, and border-width
                               aliases along their token scales (see the
-                              live-tokens-adjust-geometry skill). Reads each
+                              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.
-  set-fonts <brief.json> [--dry-run] [--no-verify]
+  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-pair-fonts skill). Each family is
+                              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
@@ -109,6 +109,17 @@ Both check commands accept:
                               keep it. --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.
   migrate [--check] [--write] [--tokens <path>]
                               Reconcile your project with the installed package:
                               applies additive tokens.css migrations, moves a
@@ -150,7 +161,7 @@ if (!command || command === '--help' || command === '-h') {
 
 const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-if (command === 'create' || command === 'init') {
+if (command === 'create') {
   const targetArg = rest.find((a) => !a.startsWith('-'));
   if (!targetArg) {
     fail(`Usage: npx @motion-proto/live-tokens create <project-directory>`);
@@ -241,72 +252,97 @@ if (command === 'check-page') {
   reportChecks('check-page', findings, checked, PAGE_RULES, opts);
 }
 
-if (command === 'generate-theme') {
-  const briefPath = rest.find((a) => !a.startsWith('-'));
-  if (!briefPath) {
-    fail(`Usage: npx @motion-proto/live-tokens generate-theme <brief.json> [--no-activate] [--dry-run]`);
+if (command === 'set-colors') {
+  const baseColorsPath = rest.find((a) => !a.startsWith('-'));
+  if (!baseColorsPath) {
+    fail(`Usage: npx @motion-proto/live-tokens set-colors <base-colors.json> [--dry-run]`);
+  }
+  if (rest.includes('--no-activate')) {
+    fail(
+      `set-colors has no --no-activate: it edits the open buffer, which is what the page already runs. ` +
+        `Nothing is activated until save-theme, which takes the flag.`,
+    );
+  }
+  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 ` +
+        `already starts from the first. Run save-theme --no-activate between themes.`,
+    );
   }
   try {
-    const carryIdx = rest.indexOf('--carry-from');
-    const carryFrom = carryIdx !== -1 ? rest[carryIdx + 1] : undefined;
-    if (carryIdx !== -1 && !carryFrom) fail(`--carry-from requires a theme name`);
-    const result = await runGenerateTheme({
-      briefPath,
-      activate: !rest.includes('--no-activate'),
+    const result = await runSetColors({
+      baseColorsPath,
       dryRun: rest.includes('--dry-run'),
-      carryFrom,
     });
-    console.log(formatGenerateThemeResult(result));
+    console.log(formatSetColorsResult(result));
     process.exit(result.report.failures.length === 0 ? 0 : 1);
   } catch (err) {
-    fail(`generate-theme failed: ${err instanceof Error ? err.message : String(err)}`);
+    fail(`set-colors failed: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
 
-if (command === 'adjust') {
+if (command === 'set-geometry') {
   const opsPath = rest.find((a) => !a.startsWith('-'));
   if (!opsPath) {
-    fail(`Usage: npx @motion-proto/live-tokens adjust <ops.json> [--dry-run]`);
+    fail(`Usage: npx @motion-proto/live-tokens set-geometry <ops.json> [--dry-run]`);
   }
   if (rest.includes('--no-activate')) {
     fail(
-      `adjust has no --no-activate: it edits the open buffer, which is what the page already runs. ` +
+      `set-geometry has no --no-activate: it edits the open buffer, which is what the page already runs. ` +
         `Drop the flag and re-run.`,
     );
   }
   try {
-    const result = await runAdjust({
+    const result = await runSetGeometry({
       opsPath,
       dryRun: rest.includes('--dry-run'),
     });
-    console.log(formatAdjustResult(result));
+    console.log(formatSetGeometryResult(result));
     process.exit(0);
   } catch (err) {
-    fail(`adjust failed: ${err instanceof Error ? err.message : String(err)}`);
+    fail(`set-geometry failed: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
 
-if (command === 'set-fonts') {
-  const briefPath = rest.find((a) => !a.startsWith('-'));
-  if (!briefPath) {
-    fail(`Usage: npx @motion-proto/live-tokens set-fonts <brief.json> [--dry-run] [--no-verify]`);
+if (command === 'set-type') {
+  const pairingPath = rest.find((a) => !a.startsWith('-'));
+  if (!pairingPath) {
+    fail(`Usage: npx @motion-proto/live-tokens set-type <pairing.json> [--dry-run] [--no-verify]`);
   }
   if (rest.includes('--no-activate')) {
     fail(
-      `set-fonts has no --no-activate: it edits the open buffer, which is what the page already runs. ` +
+      `set-type has no --no-activate: it edits the open buffer, which is what the page already runs. ` +
         `Drop the flag and re-run.`,
     );
   }
   try {
-    const result = await runSetFonts({
-      briefPath,
+    const result = await runSetType({
+      pairingPath,
       dryRun: rest.includes('--dry-run'),
       verify: !rest.includes('--no-verify'),
     });
-    console.log(formatSetFontsResult(result));
+    console.log(formatSetTypeResult(result));
+    process.exit(0);
+  } catch (err) {
+    fail(`set-type failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+if (command === 'save-theme') {
+  const name = rest.find((a) => !a.startsWith('-'));
+  if (!name) {
+    fail(`Usage: npx @motion-proto/live-tokens save-theme <name> [--no-activate] [--dry-run]`);
+  }
+  try {
+    const result = await runSaveTheme({
+      name,
+      activate: !rest.includes('--no-activate'),
+      dryRun: rest.includes('--dry-run'),
+    });
+    console.log(formatSaveThemeResult(result));
     process.exit(0);
   } catch (err) {
-    fail(`set-fonts failed: ${err instanceof Error ? err.message : String(err)}`);
+    fail(`save-theme failed: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
 
@@ -391,9 +427,10 @@ 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-generate-theme': 'make me a bright and cheerful theme',
-  'live-tokens-adjust-geometry': 'make the buttons pill shaped',
-  'live-tokens-pair-fonts': 'pair some fonts for this theme',
+  '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',
 };

package/bin/lib/liveState.mjs

@@ -0,0 +1,110 @@
+// The live state the three `set-*` workers read, in one place.
+//
+// Every resolver mirrors the dev server's own resolution order — the unsaved
+// buffer, then the open theme's copy by value, then the shipped default — so a
+// CLI edits what the page runs. Pure file reads: the caller passes the resolved
+// dirs, so nothing here loads `dist-plugin` and `bin/engineLoadsLazily.test.ts`
+// holds by construction.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageDataDir = resolve(dirname(fileURLToPath(import.meta.url)), '../..', 'src/live-tokens/data');
+
+function readJsonIfExists(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    throw new Error(`${path} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+/** Local tree first, then the copy the installed package ships. */
+function readData(localDir, packageSubdir, fileName) {
+  return (
+    readJsonIfExists(join(localDir, `${fileName}.json`)) ??
+    readJsonIfExists(join(packageDataDir, packageSubdir, `${fileName}.json`))
+  );
+}
+
+/** `_fileName` and `_source` are read-door markers, never part of a document. */
+export function stripMarkers(value) {
+  if (!value || typeof value !== 'object') return value;
+  const { _fileName, _source, ...rest } = value;
+  return rest;
+}
+
+export function componentNames(componentConfigsDir) {
+  if (!existsSync(componentConfigsDir)) return [];
+  return readdirSync(componentConfigsDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+}
+
+export function readActiveTheme(themesDir) {
+  if (!themesDir) return null;
+  const slug = readJsonIfExists(join(themesDir, '_active.json'))?.activeFile ?? 'default';
+  const theme = readData(themesDir, 'themes', slug);
+  return theme ? { slug, theme } : null;
+}
+
+export function readLiveColorsAndType(colorsAndTypeDir, active) {
+  const working = readJsonIfExists(join(colorsAndTypeDir, '_working.json'));
+  if (working) return { colorsAndType: stripMarkers(working), source: 'working' };
+  if (active?.theme?.colorsAndType) {
+    return { colorsAndType: stripMarkers(active.theme.colorsAndType), source: 'theme' };
+  }
+  const shipped = readData(colorsAndTypeDir, 'colors-and-type', 'default');
+  if (!shipped) throw new Error(`no colors and type to read at ${colorsAndTypeDir}`);
+  return { colorsAndType: stripMarkers(shipped), source: 'default' };
+}
+
+/** `updatedAt` records when a buffer was written, not what it holds, so the
+ *  comparison that tells a discard from an edit ignores it. Both writers of
+ *  `colors-and-type/_working.json` ask this one question, and a rule that kept
+ *  `updatedAt` missed every buffer the other verb had stamped. */
+export function sameContent(a, b) {
+  const strip = ({ updatedAt: _updatedAt, ...rest }) => rest;
+  return JSON.stringify(strip(a)) === JSON.stringify(strip(b));
+}
+
+/** Which layer sits under the buffer: the open theme when it carries colors and
+ *  type, else the shipped default. A report that names the layer reads it from
+ *  here rather than re-deriving the fall-through, which is how the discard
+ *  message came to name a theme that was not open. */
+export const savedColorsAndTypeSource = (active) => (active?.theme?.colorsAndType ? 'theme' : 'default');
+
+/** The layer under the buffer. Returning the buffer to exactly this is a
+ *  discard, not an edit, so a caller compares against it before writing. */
+export function readSavedColorsAndType(colorsAndTypeDir, active) {
+  const saved =
+    savedColorsAndTypeSource(active) === 'theme'
+      ? active.theme.colorsAndType
+      : readData(colorsAndTypeDir, 'colors-and-type', 'default');
+  return saved ? stripMarkers(saved) : null;
+}
+
+/** Each component's live config, and whether a buffer or the open document
+ *  answered. Every theme carries every component by value, but this is a raw
+ *  file read, ahead of any server-side fill — a theme written before a
+ *  component existed can still omit it, so a missing entry falls back to the
+ *  shipped default the same way the theme's own fill would, and still reports
+ *  as the document. */
+export function readLiveComponentConfigs(componentConfigsDir, active) {
+  const configs = {};
+  const sources = {};
+  for (const comp of componentNames(componentConfigsDir)) {
+    const working = readJsonIfExists(join(componentConfigsDir, comp, '_working.json'));
+    const config =
+      working ??
+      active?.theme?.componentConfigs?.[comp] ??
+      readData(join(componentConfigsDir, comp), `component-configs/${comp}`, 'default');
+    if (!config) continue;
+    configs[comp] = stripMarkers(config);
+    sources[comp] = working ? 'working' : 'theme';
+  }
+  return { configs, sources };
+}

package/bin/save-theme.mjs

@@ -0,0 +1,177 @@
+// `live-tokens save-theme` worker.
+//
+// Composes the live state into a theme document at `themes/<slug>.json` and
+// opens it. Live state, and only live state: each layer resolves the way the
+// dev server resolves it — the unsaved buffer, then the open theme's copy by
+// value, then the shipped default — so the theme this writes is the look the
+// page renders. Opening clears every `_working.json` and points
+// `themes/_active.json` at the new document, exactly as the editor's apply door
+// does; `--no-activate` writes the file and leaves the live state alone, which
+// is how a set of themes comes off one starting look.
+//
+// This is the only verb that writes a theme. The three `set-*` verbs write
+// buffers.
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  componentNames,
+  readActiveTheme,
+  readLiveColorsAndType,
+  readLiveComponentConfigs,
+} from './lib/liveState.mjs';
+
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+// The setColors bundle carries the slug helper, the component schema stamp and
+// the dir resolution; composing a theme needs no color pipeline of its own.
+const ENGINE = resolve(pkgRoot, 'dist-plugin/setColors/index.js');
+// Source of truth: src/editor/core/themes/themeTypes.ts, which
+// normalizeTheme.ts re-exports. This copy cannot import TS, so
+// `bin/schemaVersionCopies.test.ts` is what catches a drift.
+const THEME_SCHEMA_VERSION = 5;
+
+async function loadEngine() {
+  if (!existsSync(ENGINE)) {
+    throw new Error(
+      `setColors engine not found at ${relative(process.cwd(), ENGINE)}. ` +
+        `Build the plugin first (npm run build:plugin).`,
+    );
+  }
+  return import(ENGINE);
+}
+
+/** The destination file, read to keep its `createdAt`. Never the package copy:
+ *  this is the file about to be overwritten, not a layer to fall through to. */
+function readLocalJson(path) {
+  return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null;
+}
+
+/** `engine` is a test seam; the CLI always runs the compiled bundle. */
+export async function runSaveTheme({
+  name,
+  activate = true,
+  dryRun = false,
+  colorsAndTypeDir,
+  componentConfigsDir,
+  themesDir,
+  engine,
+} = {}) {
+  const { sanitizeFileName, resolveDataDirs, CURRENT_COMPONENT_SCHEMA_VERSION } =
+    engine ?? (await loadEngine());
+
+  const themeName = typeof name === 'string' ? name.trim() : '';
+  if (!themeName) throw new Error('save-theme needs a theme name');
+  const slug = sanitizeFileName(themeName);
+  if (slug === 'default') {
+    throw new Error('"default" is the protected package theme; pick another name');
+  }
+
+  const resolved = colorsAndTypeDir && componentConfigsDir && themesDir ? null : resolveDataDirs();
+  const dirs = {
+    colorsAndTypeDir: colorsAndTypeDir ?? resolved.colorsAndTypeDir,
+    componentConfigsDir: componentConfigsDir ?? resolved.componentConfigsDir,
+    themesDir: themesDir ?? resolved.themesDir,
+  };
+
+  const active = readActiveTheme(dirs.themesDir);
+  const { colorsAndType, source } = readLiveColorsAndType(dirs.colorsAndTypeDir, active);
+  const { configs, sources } = readLiveComponentConfigs(dirs.componentConfigsDir, active);
+
+  const themePath = join(dirs.themesDir, `${slug}.json`);
+  const existing = readLocalJson(themePath);
+  const now = new Date().toISOString();
+  const sketchSettings = active?.theme?.sketchSettings;
+
+  const theme = {
+    name: themeName,
+    createdAt: existing?.createdAt ?? now,
+    updatedAt: now,
+    schemaVersion: THEME_SCHEMA_VERSION,
+    colorsAndType: { ...colorsAndType, name: themeName },
+    componentConfigs: configs,
+    componentSchemaVersion: CURRENT_COMPONENT_SCHEMA_VERSION,
+    ...(sketchSettings ? { sketchSettings } : {}),
+  };
+
+  if (!dryRun) {
+    mkdirSync(dirs.themesDir, { recursive: true });
+    writeFileSync(themePath, JSON.stringify(theme, null, 2) + '\n');
+    if (activate) applyTheme(slug, dirs);
+  }
+
+  // `working` is the one source label that proves a buffer answered: a
+  // component the open theme omits reports as `theme` after falling through to
+  // its shipped default, so the report says what came from a buffer and names
+  // the fall-through for the rest rather than claiming a layer per component.
+  const bufferedComponents = componentNames(dirs.componentConfigsDir).filter(
+    (comp) => sources[comp] === 'working',
+  );
+
+  return {
+    name: themeName,
+    slug,
+    themePath,
+    existed: existing !== null,
+    dryRun,
+    activated: activate && !dryRun,
+    previousActive: active?.slug ?? 'default',
+    openTheme: active?.slug ?? null,
+    buffered: { colorsAndType: source === 'working', components: bufferedComponents },
+    components: Object.keys(configs).length,
+    sketchSettings: Boolean(sketchSettings),
+  };
+}
+
+/** The apply door's write set, reproduced: clear every working delta and point
+ *  `themes/_active.json` at the open document. Production is untouched. */
+function applyTheme(slug, dirs) {
+  const colorsWorking = join(dirs.colorsAndTypeDir, '_working.json');
+  if (existsSync(colorsWorking)) rmSync(colorsWorking);
+
+  for (const comp of componentNames(dirs.componentConfigsDir)) {
+    const workingPath = join(dirs.componentConfigsDir, comp, '_working.json');
+    if (existsSync(workingPath)) rmSync(workingPath);
+  }
+
+  writeFileSync(join(dirs.themesDir, '_active.json'), JSON.stringify({ activeFile: slug }));
+}
+
+export function formatSaveThemeResult(result) {
+  const root = process.cwd();
+  const lines = [];
+  const wrote = result.dryRun ? 'Would write' : result.existed ? 'Updated' : 'Created';
+  lines.push(`${wrote} theme "${result.name}" → ${relative(root, result.themePath)}`);
+  lines.push(`It carries the colors and type and ${result.components} component config(s) by value.`);
+
+  const edited = [
+    ...(result.buffered.colorsAndType ? ['colors and type'] : []),
+    ...result.buffered.components,
+  ];
+  const open = result.openTheme ? `the open theme "${result.openTheme}"` : 'the package defaults';
+  const kept = result.dryRun ? 'Would save' : 'Saved';
+  if (edited.length > 0) {
+    lines.push(`${kept} your unsaved edits: ${edited.join(', ')}.`);
+    lines.push(`Everything else came from ${open}, or the shipped defaults where it carries no entry.`);
+  } else {
+    lines.push(`No unsaved edits; ${kept.toLowerCase()} a copy of ${open}.`);
+  }
+  if (result.sketchSettings) lines.push(`Sketch settings rode through from the open theme.`);
+
+  if (result.activated) {
+    lines.push(
+      `\nOpened "${result.slug}" (previously open: "${result.previousActive}"). ` +
+        `Reload the app to see it; switch back any time from Load in the editor's Theme panel. ` +
+        `Adopt it there to publish it to tokens.generated.css.`,
+    );
+  } else if (result.dryRun) {
+    lines.push(`\nDry run: nothing written under ${relative(root, dirname(result.themePath))}.`);
+  } else {
+    lines.push(
+      `\nNot opened (--no-activate). Your unsaved edits are still open, so the next ` +
+        `save-theme starts from the same look. Load "${result.slug}" from the editor's Theme panel to see it.`,
+    );
+  }
+  return lines.join('\n');
+}