@motion-proto/live-tokens 0.75.0 → 0.76.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.76.0 — The skills directory matches the release
+
+### Changed (breaking)
+
+- **`setup-claude --force` now makes `.claude/skills/` match the release.** It
+  replaced each bundled skill by merging over it, which left two kinds of stale
+  text behind: a skill a release renamed kept its old directory, where it
+  shadowed the replacement, and a reference file a release dropped survived
+  inside a skill that was otherwise current. Both are invisible until a model
+  reads them. A forced run now replaces each bundled directory outright and
+  removes any `live-tokens-` skill the release no longer ships, naming each one
+  it removed. A skill under any other name is the project's own and is never
+  touched, and an unforced run still deletes nothing. 0.75.0's rename of
+  `live-tokens-build-page` to `live-tokens-create-page` is the case that
+  prompted this; the changelog then told a reader to delete the directory by
+  hand.
+
+  Before a forced run, copy any bundled skill you edited in place to a name of
+  your own. A `live-tokens-` directory this release does not ship is deleted
+  without a prompt, and one it does ship is replaced rather than merged.
+
+  `setup-claude` moves out of `bin/cli.mjs` into `bin/setup-claude.mjs` as
+  `runSetupClaude` and `formatSetupResult`, matching `create.mjs`, and gains
+  `bin/setup-claude.test.ts`.
+
+### Changed
+
+- **The `create` template installs the skills from `postinstall` and gitignores
+  them.** A scaffolded project no longer commits nine skill directories the
+  package owns, so a version bump stops showing twenty changed files that
+  nobody wrote. The skills instead refresh on every `npm install`. The
+  postinstall ends in `|| exit 0`: `setup-claude` refuses to run on Windows,
+  and a skills copy must never fail an install. A project created before this
+  release adds the two lines itself; the README carries them.
+
 ## 0.75.0 — A component passes when the tests pass
 
 ### Added

package/README.md

@@ -322,7 +322,7 @@ npx @motion-proto/live-tokens <command>
 | Command | What it does |
 |---|---|
 | `create <dir> [--force]` | Scaffold a new Svelte + Vite app wired up with live-tokens. |
-| `setup-claude [--force]` | Install the bundled Claude Code skills into `./.claude/skills/`. |
+| `setup-claude [--force]` | Install the bundled Claude Code skills into `./.claude/skills/`; `--force` makes the directory match this release. |
 | `components [id] [--json]` | List every component the project has, shipped and its own, with the props each takes; with an id, its 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 reads, which page renders which component, and both checkers' findings by rule. Always exits 0. |
@@ -346,10 +346,20 @@ The package bundles nine Claude Code skills. They encode the conventions this RE
 npx @motion-proto/live-tokens setup-claude
 ```
 
-This copies every bundled skill into `./.claude/skills/` in the current directory. Re-run it after upgrading the package to pick up new and changed skills, adding `--force` to overwrite. macOS and Linux only. The equivalent by hand:
+This copies every bundled skill into `./.claude/skills/` in the current directory, leaving any that already exist. macOS and Linux only.
 
-```bash
-mkdir -p .claude/skills && cp -R node_modules/@motion-proto/live-tokens/.claude/skills/. .claude/skills/
+Re-run it with `--force` after upgrading. That makes the directory match the release: each bundled skill is replaced outright, so a reference file the release dropped goes with it, and a `live-tokens-` skill the release no longer ships is removed. A skill under any other name is the project's own and is never touched. Without `--force` nothing is deleted and an existing skill is left alone, so a renamed skill keeps shadowing its replacement until a forced run clears it.
+
+A project created with `create` runs the forced form from `postinstall` and gitignores the copy, so the skills track the installed version with nothing to commit. To do the same in an existing project:
+
+```jsonc
+// package.json
+"postinstall": "live-tokens setup-claude --force || exit 0"
+```
+
+```
+# .gitignore
+.claude/skills/live-tokens-*/
 ```
 
 ### `live-tokens-pick-component`

package/bin/cli.mjs

@@ -14,7 +14,7 @@
 //   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';
@@ -40,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';
@@ -407,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, in ${destSkills}`);
-
-const SAMPLE_PROMPTS = {
-  'live-tokens-create-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));
 }

package/bin/setup-claude.mjs

@@ -0,0 +1,110 @@
+// Installs the bundled Claude Code skills into a project's ./.claude/skills/.
+//
+// Claude Code discovers skills only under .claude/skills/, never inside
+// node_modules, so the package's own copy has to be duplicated into each
+// project that wants them. That makes this command the only thing keeping the
+// two trees in step, and `--force` has to mean "make the destination match this
+// release" rather than "write over the files I happen to ship today":
+//
+//   - a skill this release renamed leaves its old directory behind, where it
+//     shadows the new one with stale instructions;
+//   - a reference file this release dropped survives inside a skill that is
+//     otherwise current, because cpSync merges into an existing directory.
+//
+// Both are invisible until a model reads the stale text, so --force replaces
+// each directory outright and prunes the ones this release no longer ships.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+// The package owns this prefix in a project's skills directory. A skill without
+// it is the project's own and is never touched, whatever the flags say.
+const SKILL_PREFIX = 'live-tokens-';
+
+const SAMPLE_PROMPTS = {
+  'live-tokens-create-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',
+};
+
+function directoriesIn(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((name) => statSync(join(dir, name)).isDirectory());
+}
+
+export function runSetupClaude({ pkgRoot, cwd, force = false }) {
+  const srcSkills = join(pkgRoot, '.claude', 'skills');
+
+  if (!existsSync(srcSkills)) {
+    throw new Error(`No bundled skills found at ${srcSkills}. Is the package installed correctly?`);
+  }
+
+  const shipped = directoriesIn(srcSkills);
+  if (shipped.length === 0) {
+    throw new Error('No bundled skills to install.');
+  }
+
+  const destSkills = join(cwd, '.claude', 'skills');
+  mkdirSync(destSkills, { recursive: true });
+
+  const installed = [];
+  const skipped = [];
+  const removed = [];
+
+  for (const skill of shipped) {
+    const dest = join(destSkills, skill);
+    if (existsSync(dest) && !force) {
+      skipped.push(skill);
+      continue;
+    }
+    // Replace rather than merge: a file this release dropped must not survive
+    // inside a directory that otherwise looks current.
+    rmSync(dest, { recursive: true, force: true });
+    cpSync(join(srcSkills, skill), dest, { recursive: true });
+    installed.push(skill);
+  }
+
+  if (force) {
+    for (const name of directoriesIn(destSkills)) {
+      if (!name.startsWith(SKILL_PREFIX) || shipped.includes(name)) continue;
+      rmSync(join(destSkills, name), { recursive: true, force: true });
+      removed.push(name);
+    }
+  }
+
+  return { installed, skipped, removed, destSkills, shipped };
+}
+
+export function formatSetupResult({ installed, skipped, removed, destSkills, shipped }) {
+  const lines = [];
+
+  for (const skill of shipped) {
+    if (installed.includes(skill)) lines.push(`  ok    ${skill}`);
+    else lines.push(`  skip  ${skill}  (already exists; pass --force to overwrite)`);
+  }
+  for (const skill of removed) {
+    lines.push(`  gone  ${skill}  (this release no longer ships it; removed)`);
+  }
+
+  const counts = [`${installed.length} installed`, `${skipped.length} skipped`];
+  if (removed.length > 0) counts.push(`${removed.length} removed`);
+  lines.push(`\n${counts.join(', ')}, in ${destSkills}`);
+
+  if (skipped.length > 0 && removed.length === 0) {
+    lines.push(`\nRe-run with --force to bring every skill up to this release.`);
+  }
+
+  const samples = shipped.map((s) => SAMPLE_PROMPTS[s] && [s, SAMPLE_PROMPTS[s]]).filter(Boolean);
+  if (samples.length > 0) {
+    lines.push(`\nIn Claude Code, prompts like these auto-trigger the matching skill:`);
+    for (const [skill, prompt] of samples) lines.push(`  "${prompt}"\n    ${skill}`);
+  }
+
+  return lines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [

package/template/_gitignore

@@ -7,6 +7,10 @@ dist-ssr
 playwright-report/
 test-results/
 
+# The live-tokens skills are a copy of what the package ships; postinstall
+# refreshes them, so they are the package's to version, not this project's.
+.claude/skills/live-tokens-*/
+
 .DS_Store
 .vscode/*
 !.vscode/extensions.json

package/template/package.json

@@ -9,7 +9,8 @@
     "preview": "vite preview",
     "check": "svelte-check --tsconfig ./tsconfig.json",
     "check:design": "live-tokens check-page && live-tokens check-component",
-    "test:design": "live-tokens check-component --tests"
+    "test:design": "live-tokens check-component --tests",
+    "postinstall": "live-tokens setup-claude --force || exit 0"
   },
   "dependencies": {
     "@motion-proto/live-tokens": "__LT_VERSION__"