@codecademy/gamut 68.6.1-alpha.edab62.0 → 68.6.1-alpha.f6b2ce.0

package/bin/commands/plugin/install.mjs

@@ -1,39 +1,46 @@
 import { cp, mkdir, readdir, rm, symlink } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
+import { resolve } from 'node:path';
 
 import { claudePluginSpec, marketplaceName } from '../../lib/claude.mjs';
 import { cursorDestPath } from '../../lib/cursor.mjs';
-import { resolveFigmaOutput } from '../../lib/figma.mjs';
+import {
+  installDesignMd,
+  listCanonicalThemes,
+  resolveTheme,
+} from '../../lib/design.mjs';
+import { log, warn } from '../../lib/io.mjs';
 import { getFlag, resolvePluginDir } from '../../lib/resolve-plugin-dir.mjs';
 import { runCommand } from '../../lib/run-command.mjs';
 
-export const TARGETS = ['cursor', 'claude', 'figma'];
+export const TARGETS = ['cursor', 'claude'];
 export const SCOPES = ['all', 'skills', 'rules', 'commands', 'agents'];
 
 export function help() {
-  console.log(`
+  log(`
 Usage:
   gamut plugin install [target] [options]
 
-Install the Gamut plugin into an AI or design tool.
+Install the Gamut plugin into an AI tool.
 
 Arguments:
   target               Tool to install into (default: cursor)
-                       cursor | claude | figma
+                       cursor | claude
 
 Options:
   --scope <scope>      Content to install (default: all)
                        all | skills | rules | commands | agents
-  --output <path>      [figma] Explicit destination directory for guidelines/.
-                       If omitted, walks up from cwd to find figma.config.json.
+  --theme <theme>      Copy DESIGN.*.md to ./DESIGN.md in the current directory
+                       core | admin | platform | percipio | lxstudio
+                       (admin/platform use Codecademy DESIGN; aliases: codecademy, cc, lx-studio)
+  --force              Overwrite existing DESIGN.md when using --theme
   --plugin-dir <path>  Override the bundled agent-tools directory
   -h, --help           Show this help message
 
 Examples:
   gamut plugin install
   gamut plugin install claude
-  gamut plugin install figma
-  gamut plugin install figma --output /path/to/project/guidelines
+  gamut plugin install cursor --theme core
+  gamut plugin install cursor --theme percipio --force
   gamut plugin install cursor --scope skills
   gamut plugin install cursor --plugin-dir ./my-agent-tools
 `);
@@ -44,7 +51,6 @@ Examples:
 /** Directories in the plugin source that should not be installed to Cursor. */
 const CURSOR_IGNORE = new Set([
   '.claude-plugin', // Claude Code manifest — not a Cursor concept
-  'guidelines',     // Figma Make only
 ]);
 
 /** @param {string} sourceRoot @param {string} scope */
@@ -55,7 +61,7 @@ async function installCursor(sourceRoot, scope) {
     // Symlink the whole plugin dir (dev convenience)
     await rm(dest, { recursive: true, force: true });
     await symlink(resolve(sourceRoot), dest, 'dir');
-    console.log(`Cursor: symlinked to ${dest}`);
+    log(`Cursor: symlinked to ${dest}`);
     return;
   }
 
@@ -63,31 +69,42 @@ async function installCursor(sourceRoot, scope) {
   await rm(dest, { recursive: true, force: true });
   await mkdir(dest, { recursive: true });
 
-  await cp(`${sourceRoot}/.cursor-plugin`, `${dest}/.cursor-plugin`, { recursive: true });
+  await cp(`${sourceRoot}/.cursor-plugin`, `${dest}/.cursor-plugin`, {
+    recursive: true,
+  });
 
   let dirs;
   if (scope === 'all') {
     const entries = await readdir(sourceRoot, { withFileTypes: true });
     dirs = entries
-      .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !CURSOR_IGNORE.has(e.name))
+      .filter(
+        (e) =>
+          e.isDirectory() &&
+          !e.name.startsWith('.') &&
+          !CURSOR_IGNORE.has(e.name)
+      )
       .map((e) => e.name);
   } else {
     dirs = [scope];
   }
 
-  for (const dir of dirs) {
-    await cp(`${sourceRoot}/${dir}`, `${dest}/${dir}`, { recursive: true }).catch(() => {
-      // directory may be empty/missing — not an error
-    });
-  }
+  await Promise.all(
+    dirs.map((dir) =>
+      cp(`${sourceRoot}/${dir}`, `${dest}/${dir}`, { recursive: true }).catch(
+        () => {
+          // directory may be empty/missing — not an error
+        }
+      )
+    )
+  );
 
   const scopeLabel = scope === 'all' ? 'all content' : scope;
-  console.log(`Cursor: installed (${scopeLabel}) → ${dest}`);
+  log(`Cursor: installed (${scopeLabel}) → ${dest}`);
 }
 
 // Claude Code only loads from recognized plugin directories: skills/, commands/, agents/.
-// rules/ is Cursor-specific (.mdc format); .cursor-plugin/ and guidelines/ are also
-// present in sourceRoot but ignored by Claude Code.
+// rules/ is Cursor-specific (.mdc format). guidelines/ is installed to Cursor and is
+// also source for the Figma Make kit; Claude marketplace registers the full sourceRoot.
 
 /** @param {string} sourceRoot */
 async function installClaude(sourceRoot) {
@@ -95,56 +112,58 @@ async function installClaude(sourceRoot) {
   const mpName = marketplaceName(spec);
   const root = resolve(sourceRoot);
 
-  let code = await runCommand('claude', ['plugin', 'marketplace', 'add', root, '--scope', 'user']);
+  let code = await runCommand('claude', [
+    'plugin',
+    'marketplace',
+    'add',
+    root,
+    '--scope',
+    'user',
+  ]);
   if (code !== 0) {
-    console.warn(
+    warn(
       `warning: "claude plugin marketplace add" exited ${code} — ` +
-        `if it's already registered this is safe to ignore.`,
+        `if it's already registered this is safe to ignore.`
     );
-    code = await runCommand('claude', ['plugin', 'marketplace', 'update', mpName]);
+    code = await runCommand('claude', [
+      'plugin',
+      'marketplace',
+      'update',
+      mpName,
+    ]);
     if (code !== 0) {
       throw new Error(
         `claude plugin marketplace add/update failed (exit ${code}).\n` +
-          `Try manually: claude plugin marketplace add ${root}`,
+          `Try manually: claude plugin marketplace add ${root}`
       );
     }
   }
 
-  code = await runCommand('claude', ['plugin', 'install', spec, '--scope', 'user']);
+  code = await runCommand('claude', [
+    'plugin',
+    'install',
+    spec,
+    '--scope',
+    'user',
+  ]);
   if (code !== 0) {
     throw new Error(
       `claude plugin install failed (exit ${code}).\n` +
-        `Try manually: claude plugin install ${spec} --scope user`,
+        `Try manually: claude plugin install ${spec} --scope user`
     );
   }
 
-  console.log(`Claude Code: installed ${spec} (user scope)`);
-  console.log(`  Tip: run /reload-plugins in Claude Code if skills don't appear immediately.`);
-  console.log(`  One-off without install: claude --plugin-dir ${root}`);
-}
-
-/**
- * @param {string} sourceRoot
- * @param {string | undefined} outputArg
- */
-async function installFigma(sourceRoot, outputArg) {
-  const src = join(sourceRoot, 'guidelines');
-  const { path: dest, discovered } = await resolveFigmaOutput(outputArg);
-
-  if (discovered) {
-    console.log(`Figma: found figma.config.json — installing to ${dest}`);
-  }
-
-  await rm(dest, { recursive: true, force: true });
-  await cp(src, dest, { recursive: true });
-  console.log(`Figma: installed guidelines/ → ${dest}`);
-  console.log(`  In Figma Make, point your kit at this guidelines/ directory for design system context.`);
+  log(`Claude Code: installed ${spec} (user scope)`);
+  log(
+    `  Tip: run /reload-plugins in Claude Code if skills don't appear immediately.`
+  );
+  log(`  One-off without install: claude --plugin-dir ${root}`);
 }
 
 // ---------------------------------------------------------------------------
 
 /**
- * gamut plugin install [cursor|claude|figma] [--scope all|skills|rules|commands|agents]
+ * gamut plugin install [cursor|claude] [--scope all|skills|rules|commands|agents]
  *                                            [--plugin-dir <path>]
  *
  * @param {string[]} args
@@ -154,20 +173,41 @@ export default async function install(args) {
   const scope = getFlag(args, '--scope', 'all') ?? 'all';
 
   if (!TARGETS.includes(target)) {
-    throw new Error(`Unknown target: "${target}". Choose from: ${TARGETS.join(', ')}`);
+    throw new Error(
+      `Unknown target: "${target}". Choose from: ${TARGETS.join(', ')}`
+    );
   }
   if (!SCOPES.includes(scope)) {
-    throw new Error(`Unknown scope: "${scope}". Choose from: ${SCOPES.join(', ')}`);
+    throw new Error(
+      `Unknown scope: "${scope}". Choose from: ${SCOPES.join(', ')}`
+    );
   }
 
   const pluginDir = await resolvePluginDir(args);
+  const theme = getFlag(args, '--theme');
+  const force = args.includes('--force');
+
+  if (theme) {
+    resolveTheme(theme);
+  }
 
   if (target === 'cursor') {
     await installCursor(pluginDir, scope);
   } else if (target === 'claude') {
     await installClaude(pluginDir);
-  } else if (target === 'figma') {
-    const output = getFlag(args, '--output', undefined);
-    await installFigma(pluginDir, output);
+  }
+
+  if (theme) {
+    const { dest, label } = await installDesignMd(
+      pluginDir,
+      process.cwd(),
+      theme,
+      {
+        force,
+      }
+    );
+    log(`DESIGN.md: installed (${label}) → ${dest}`);
   }
 }
+
+export { listCanonicalThemes };

package/bin/commands/plugin/list.mjs

@@ -1,25 +1,22 @@
 import { stat } from 'node:fs/promises';
 
 import { cursorDestPath } from '../../lib/cursor.mjs';
-import { findFigmaConfigDir } from '../../lib/figma.mjs';
-import { getFlag, resolvePluginDir } from '../../lib/resolve-plugin-dir.mjs';
+import { log } from '../../lib/io.mjs';
+import { resolvePluginDir } from '../../lib/resolve-plugin-dir.mjs';
 
 export function help() {
-  console.log(`
+  log(`
 Usage:
   gamut plugin list [options]
 
 Show installation status for all supported targets.
 
 Options:
-  --output <path>      [figma] Explicit path to DESIGN.md.
-                       If omitted, walks up from cwd to find figma.config.json.
   --plugin-dir <path>  Override the bundled agent-tools directory
   -h, --help           Show this help message
 
 Examples:
   gamut plugin list
-  gamut plugin list --output ./docs/DESIGN.md
 `);
 }
 
@@ -45,32 +42,6 @@ async function claudeStatus() {
   };
 }
 
-/** @param {string | undefined} outputArg */
-async function figmaStatus(outputArg) {
-  let dest;
-  if (outputArg) {
-    dest = outputArg;
-  } else {
-    const dir = await findFigmaConfigDir(process.cwd());
-    dest = dir ? `${dir}/DESIGN.md` : null;
-  }
-
-  if (!dest) {
-    return {
-      target: 'figma',
-      status: '? unknown',
-      notes: 'figma.config.json not found — run from your project root or use --output',
-    };
-  }
-
-  const installed = !!(await stat(dest).catch(() => null));
-  return {
-    target: 'figma',
-    status: installed ? '✓ installed' : '✗ not installed',
-    notes: installed ? dest : `run: gamut plugin install figma`,
-  };
-}
-
 // ---------------------------------------------------------------------------
 
 /**
@@ -82,24 +53,21 @@ async function figmaStatus(outputArg) {
  */
 export default async function list(args) {
   const pluginDir = await resolvePluginDir(args);
-  const output = getFlag(args, '--output', undefined);
 
-  const rows = await Promise.all([
-    cursorStatus(pluginDir),
-    claudeStatus(),
-    figmaStatus(output),
-  ]);
+  const rows = await Promise.all([cursorStatus(pluginDir), claudeStatus()]);
 
   const col0 = Math.max(...rows.map((r) => r.target.length));
   const col1 = Math.max(...rows.map((r) => r.status.length));
 
-  const header = `${'Target'.padEnd(col0)}  ${'Status'.padEnd(col1)}  Path / Notes`;
+  const header = `${'Target'.padEnd(col0)}  ${'Status'.padEnd(
+    col1
+  )}  Path / Notes`;
   const rule = '─'.repeat(header.length);
 
-  console.log(`\n${header}`);
-  console.log(rule);
+  log(`\n${header}`);
+  log(rule);
   for (const row of rows) {
-    console.log(`${row.target.padEnd(col0)}  ${row.status.padEnd(col1)}  ${row.notes}`);
+    log(`${row.target.padEnd(col0)}  ${row.status.padEnd(col1)}  ${row.notes}`);
   }
-  console.log();
+  log('');
 }

package/bin/commands/plugin/remove.mjs

@@ -2,33 +2,29 @@ import { rm, stat } from 'node:fs/promises';
 
 import { claudePluginSpec, marketplaceName } from '../../lib/claude.mjs';
 import { cursorDestPath } from '../../lib/cursor.mjs';
-import { resolveFigmaOutput } from '../../lib/figma.mjs';
-import { getFlag, resolvePluginDir } from '../../lib/resolve-plugin-dir.mjs';
+import { log, warn } from '../../lib/io.mjs';
+import { resolvePluginDir } from '../../lib/resolve-plugin-dir.mjs';
 import { runCommand } from '../../lib/run-command.mjs';
 import { TARGETS } from './install.mjs';
 
 export function help() {
-  console.log(`
+  log(`
 Usage:
   gamut plugin remove [target] [options]
 
-Remove the installed Gamut plugin from an AI or design tool.
+Remove the installed Gamut plugin from an AI tool.
 
 Arguments:
   target               Tool to remove from (default: cursor)
-                       cursor | claude | figma
+                       cursor | claude
 
 Options:
-  --output <path>      [figma] Path to the DESIGN.md that was installed.
-                       If omitted, walks up from cwd to find figma.config.json.
   --plugin-dir <path>  Override the bundled agent-tools directory
   -h, --help           Show this help message
 
 Examples:
   gamut plugin remove
   gamut plugin remove claude
-  gamut plugin remove figma
-  gamut plugin remove figma --output ./docs/DESIGN.md
 `);
 }
 
@@ -40,12 +36,12 @@ async function removeCursor(sourceRoot) {
   const st = await stat(dest).catch(() => null);
 
   if (!st) {
-    console.log(`Cursor: nothing to remove — ${dest} does not exist.`);
+    log(`Cursor: nothing to remove — ${dest} does not exist.`);
     return;
   }
 
   await rm(dest, { recursive: true, force: true });
-  console.log(`Cursor: removed ${dest}`);
+  log(`Cursor: removed ${dest}`);
 }
 
 /** @param {string} sourceRoot */
@@ -54,45 +50,42 @@ async function removeClaude(sourceRoot) {
   const mpName = marketplaceName(spec);
   const pluginName = spec.split('@')[0];
 
-  let code = await runCommand('claude', ['plugin', 'remove', pluginName, '--scope', 'user']);
+  let code = await runCommand('claude', [
+    'plugin',
+    'remove',
+    pluginName,
+    '--scope',
+    'user',
+  ]);
   if (code !== 0) {
-    console.warn(
-      `warning: "claude plugin remove" exited ${code} — the plugin may not have been installed.`,
+    warn(
+      `warning: "claude plugin remove" exited ${code} — the plugin may not have been installed.`
     );
   } else {
-    console.log(`Claude Code: removed plugin "${pluginName}"`);
+    log(`Claude Code: removed plugin "${pluginName}"`);
   }
 
-  code = await runCommand('claude', ['plugin', 'marketplace', 'remove', mpName]);
+  code = await runCommand('claude', [
+    'plugin',
+    'marketplace',
+    'remove',
+    mpName,
+  ]);
   if (code !== 0) {
-    console.warn(
+    warn(
       `warning: "claude plugin marketplace remove" exited ${code} — ` +
         `the marketplace entry may not exist or the command syntax may differ. ` +
-        `Run "claude plugin marketplace list" to check.`,
+        `Run "claude plugin marketplace list" to check.`
     );
   } else {
-    console.log(`Claude Code: removed marketplace "${mpName}"`);
+    log(`Claude Code: removed marketplace "${mpName}"`);
   }
 }
 
-/** @param {string | undefined} outputArg */
-async function removeFigma(outputArg) {
-  const { path: dest } = await resolveFigmaOutput(outputArg);
-  const st = await stat(dest).catch(() => null);
-
-  if (!st) {
-    console.log(`Figma: nothing to remove — ${dest} does not exist.`);
-    return;
-  }
-
-  await rm(dest, { force: true });
-  console.log(`Figma: removed ${dest}`);
-}
-
 // ---------------------------------------------------------------------------
 
 /**
- * gamut plugin remove [cursor|claude|figma] [--plugin-dir <path>]
+ * gamut plugin remove [cursor|claude] [--plugin-dir <path>]
  *
  * @param {string[]} args
  */
@@ -100,7 +93,9 @@ export default async function remove(args) {
   const target = args.find((a) => !a.startsWith('-')) ?? 'cursor';
 
   if (!TARGETS.includes(target)) {
-    throw new Error(`Unknown target: "${target}". Choose from: ${TARGETS.join(', ')}`);
+    throw new Error(
+      `Unknown target: "${target}". Choose from: ${TARGETS.join(', ')}`
+    );
   }
 
   const pluginDir = await resolvePluginDir(args);
@@ -109,8 +104,5 @@ export default async function remove(args) {
     await removeCursor(pluginDir);
   } else if (target === 'claude') {
     await removeClaude(pluginDir);
-  } else if (target === 'figma') {
-    const output = getFlag(args, '--output', undefined);
-    await removeFigma(output);
   }
 }

package/bin/commands/plugin/update.mjs

@@ -1,8 +1,9 @@
+import { log } from '../../lib/io.mjs';
 import { getFlag } from '../../lib/resolve-plugin-dir.mjs';
 import install, { TARGETS } from './install.mjs';
 
 export function help() {
-  console.log(`
+  log(`
 Usage:
   gamut plugin update [target] [options]
 
@@ -11,23 +12,26 @@ Equivalent to re-running install — replaces the existing installation in place
 
 Arguments:
   target               Tool to update (default: cursor)
-                       cursor | claude | figma
+                       cursor | claude
 
 Options:
   --scope <scope>      Content to update (default: all)
                        all | skills | rules | commands | agents
+  --theme <theme>      Refresh ./DESIGN.md (same themes as install)
+  --force              Overwrite existing DESIGN.md when using --theme
   --plugin-dir <path>  Override the bundled agent-tools directory
   -h, --help           Show this help message
 
 Examples:
   gamut plugin update
   gamut plugin update claude
+  gamut plugin update cursor --theme core --force
   gamut plugin update cursor --scope skills
 `);
 }
 
 /**
- * gamut plugin update [cursor|claude|figma] [--scope all|skills|rules|commands|agents]
+ * gamut plugin update [cursor|claude] [--scope all|skills|rules|commands|agents]
  *                                           [--plugin-dir <path>]
  *
  * Re-runs install with the same arguments. For Cursor this does an in-place
@@ -41,9 +45,15 @@ export default async function update(args) {
   const scope = getFlag(args, '--scope', 'all') ?? 'all';
 
   if (!TARGETS.includes(target)) {
-    throw new Error(`Unknown target: "${target}". Choose from: ${TARGETS.join(', ')}`);
+    throw new Error(
+      `Unknown target: "${target}". Choose from: ${TARGETS.join(', ')}`
+    );
   }
 
-  console.log(`Updating Gamut plugin for ${target}${scope !== 'all' ? ` (scope: ${scope})` : ''}…`);
+  log(
+    `Updating Gamut plugin for ${target}${
+      scope !== 'all' ? ` (scope: ${scope})` : ''
+    }…`
+  );
   await install(args);
 }

package/bin/gamut.mjs

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 
+import { error, log } from './lib/io.mjs';
+
 /**
  * Gamut CLI
  *
  * Usage:
- *   gamut plugin install [cursor|claude|figma] [--scope all|skills|rules|commands|agents]
- *   gamut plugin remove  [cursor|claude|figma]
- *   gamut plugin update  [cursor|claude|figma] [--scope all|skills|rules|commands|agents]
+ *   gamut plugin install [cursor|claude] [--scope all|skills|rules|commands|agents]
+ *   gamut plugin remove  [cursor|claude]
+ *   gamut plugin update  [cursor|claude] [--scope all|skills|rules|commands|agents]
  *   gamut plugin list
  */
 
@@ -19,7 +21,7 @@ if (!noun || noun === '--help' || noun === '-h') {
 }
 
 if (noun !== 'plugin') {
-  console.error(`Unknown command: "${noun}"`);
+  error(`Unknown command: "${noun}"`);
   printHelp();
   process.exit(1);
 }
@@ -33,7 +35,7 @@ let cmd;
 try {
   cmd = await import(`./commands/plugin/${verb}.mjs`);
 } catch {
-  console.error(`Unknown plugin subcommand: "${verb}"`);
+  error(`Unknown plugin subcommand: "${verb}"`);
   printPluginHelp();
   process.exit(1);
 }
@@ -46,7 +48,7 @@ if (rest.includes('--help') || rest.includes('-h')) {
 try {
   await cmd.default(rest);
 } catch (/** @type {any} */ err) {
-  console.error(`Error: ${err.message}`);
+  error(`Error: ${err.message}`);
   process.exit(1);
 }
 
@@ -55,7 +57,7 @@ try {
 // ---------------------------------------------------------------------------
 
 function printHelp() {
-  console.log(`
+  log(`
 gamut — Gamut design system CLI
 
 Usage:
@@ -69,21 +71,23 @@ Run "gamut plugin --help" for plugin subcommands.
 }
 
 function printPluginHelp() {
-  console.log(`
+  log(`
 gamut plugin — Manage the Gamut plugin
 
 Subcommands:
-  install [target] [--scope <scope>]    Install the plugin into a tool
-  remove  [target]                      Remove an installed plugin
-  update  [target] [--scope <scope>]    Update an already-installed plugin
-  list                                  Show installation status for all targets
+  install [target] [--scope <scope>] [--theme <theme>]  Install the plugin (+ optional DESIGN.md)
+  remove  [target]                                      Remove an installed plugin
+  update  [target] [--scope <scope>] [--theme <theme>]  Update an installed plugin
+  list                                                  Show installation status for all targets
 
-Targets:   cursor (default)  |  claude  |  figma
+Targets:   cursor (default)  |  claude
 Scopes:    all (default)     |  skills  |  rules  |  commands  |  agents
+Themes:    core | admin | platform | percipio | lxstudio  (--theme copies DESIGN.md to repo root)
 
 Examples:
   gamut plugin install
   gamut plugin install claude
+  gamut plugin install cursor --theme percipio
   gamut plugin install cursor --scope skills
   gamut plugin remove claude
   gamut plugin update