@codecademy/gamut 68.6.1-alpha.c211a2.0 → 68.6.1-alpha.df4bce.0

package/bin/commands/plugin/install.mjs

@@ -0,0 +1,173 @@
+import { cp, mkdir, readdir, rm, symlink } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+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 { runCommand } from '../../lib/run-command.mjs';
+
+export const TARGETS = ['cursor', 'claude', 'figma'];
+export const SCOPES = ['all', 'skills', 'rules', 'commands', 'agents'];
+
+export function help() {
+  console.log(`
+Usage:
+  gamut plugin install [target] [options]
+
+Install the Gamut plugin into an AI or design tool.
+
+Arguments:
+  target               Tool to install into (default: cursor)
+                       cursor | claude | figma
+
+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.
+  --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 --scope skills
+  gamut plugin install cursor --plugin-dir ./my-agent-tools
+`);
+}
+
+// ---------------------------------------------------------------------------
+
+/** 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 */
+async function installCursor(sourceRoot, scope) {
+  const dest = await cursorDestPath(sourceRoot);
+
+  if ((process.env.CURSOR_INSTALL_METHOD ?? 'copy') !== 'copy') {
+    // 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}`);
+    return;
+  }
+
+  // Selective copy: always include the cursor manifest, then scoped content dirs
+  await rm(dest, { recursive: true, force: true });
+  await mkdir(dest, { 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))
+      .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
+    });
+  }
+
+  const scopeLabel = scope === 'all' ? 'all content' : scope;
+  console.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.
+
+/** @param {string} sourceRoot */
+async function installClaude(sourceRoot) {
+  const spec = await claudePluginSpec(sourceRoot);
+  const mpName = marketplaceName(spec);
+  const root = resolve(sourceRoot);
+
+  let code = await runCommand('claude', ['plugin', 'marketplace', 'add', root, '--scope', 'user']);
+  if (code !== 0) {
+    console.warn(
+      `warning: "claude plugin marketplace add" exited ${code} — ` +
+        `if it's already registered this is safe to ignore.`,
+    );
+    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}`,
+      );
+    }
+  }
+
+  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`,
+    );
+  }
+
+  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.`);
+}
+
+// ---------------------------------------------------------------------------
+
+/**
+ * gamut plugin install [cursor|claude|figma] [--scope all|skills|rules|commands|agents]
+ *                                            [--plugin-dir <path>]
+ *
+ * @param {string[]} args
+ */
+export default async function install(args) {
+  const target = args.find((a) => !a.startsWith('-')) ?? 'cursor';
+  const scope = getFlag(args, '--scope', 'all') ?? 'all';
+
+  if (!TARGETS.includes(target)) {
+    throw new Error(`Unknown target: "${target}". Choose from: ${TARGETS.join(', ')}`);
+  }
+  if (!SCOPES.includes(scope)) {
+    throw new Error(`Unknown scope: "${scope}". Choose from: ${SCOPES.join(', ')}`);
+  }
+
+  const pluginDir = await resolvePluginDir(args);
+
+  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);
+  }
+}

package/bin/commands/plugin/list.mjs

@@ -0,0 +1,105 @@
+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';
+
+export function help() {
+  console.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
+`);
+}
+
+// ---------------------------------------------------------------------------
+
+/** @param {string} sourceRoot */
+async function cursorStatus(sourceRoot) {
+  const dest = await cursorDestPath(sourceRoot);
+  const installed = !!(await stat(dest).catch(() => null));
+  return {
+    target: 'cursor',
+    status: installed ? '✓ installed' : '✗ not installed',
+    notes: installed ? dest : 'run: gamut plugin install cursor',
+  };
+}
+
+async function claudeStatus() {
+  // Claude Code doesn't expose a stable filesystem path we can check.
+  return {
+    target: 'claude',
+    status: '? unknown',
+    notes: 'run: claude plugin list',
+  };
+}
+
+/** @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`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+
+/**
+ * gamut plugin list
+ *
+ * Shows installation status for each supported target.
+ *
+ * @param {string[]} args
+ */
+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 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 rule = '─'.repeat(header.length);
+
+  console.log(`\n${header}`);
+  console.log(rule);
+  for (const row of rows) {
+    console.log(`${row.target.padEnd(col0)}  ${row.status.padEnd(col1)}  ${row.notes}`);
+  }
+  console.log();
+}

package/bin/commands/plugin/remove.mjs

@@ -0,0 +1,116 @@
+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 { runCommand } from '../../lib/run-command.mjs';
+import { TARGETS } from './install.mjs';
+
+export function help() {
+  console.log(`
+Usage:
+  gamut plugin remove [target] [options]
+
+Remove the installed Gamut plugin from an AI or design tool.
+
+Arguments:
+  target               Tool to remove from (default: cursor)
+                       cursor | claude | figma
+
+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
+`);
+}
+
+// ---------------------------------------------------------------------------
+
+/** @param {string} sourceRoot */
+async function removeCursor(sourceRoot) {
+  const dest = await cursorDestPath(sourceRoot);
+  const st = await stat(dest).catch(() => null);
+
+  if (!st) {
+    console.log(`Cursor: nothing to remove — ${dest} does not exist.`);
+    return;
+  }
+
+  await rm(dest, { recursive: true, force: true });
+  console.log(`Cursor: removed ${dest}`);
+}
+
+/** @param {string} sourceRoot */
+async function removeClaude(sourceRoot) {
+  const spec = await claudePluginSpec(sourceRoot);
+  const mpName = marketplaceName(spec);
+  const pluginName = spec.split('@')[0];
+
+  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.`,
+    );
+  } else {
+    console.log(`Claude Code: removed plugin "${pluginName}"`);
+  }
+
+  code = await runCommand('claude', ['plugin', 'marketplace', 'remove', mpName]);
+  if (code !== 0) {
+    console.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.`,
+    );
+  } else {
+    console.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>]
+ *
+ * @param {string[]} args
+ */
+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(', ')}`);
+  }
+
+  const pluginDir = await resolvePluginDir(args);
+
+  if (target === 'cursor') {
+    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

@@ -0,0 +1,49 @@
+import { getFlag } from '../../lib/resolve-plugin-dir.mjs';
+import install, { TARGETS } from './install.mjs';
+
+export function help() {
+  console.log(`
+Usage:
+  gamut plugin update [target] [options]
+
+Update the Gamut plugin in an AI or design tool.
+Equivalent to re-running install — replaces the existing installation in place.
+
+Arguments:
+  target               Tool to update (default: cursor)
+                       cursor | claude | figma
+
+Options:
+  --scope <scope>      Content to update (default: all)
+                       all | skills | rules | commands | agents
+  --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 --scope skills
+`);
+}
+
+/**
+ * gamut plugin update [cursor|claude|figma] [--scope all|skills|rules|commands|agents]
+ *                                           [--plugin-dir <path>]
+ *
+ * Re-runs install with the same arguments. For Cursor this does an in-place
+ * copy replacing any existing installation. For Claude Code it updates the
+ * marketplace entry and re-installs.
+ *
+ * @param {string[]} args
+ */
+export default async function update(args) {
+  const target = args.find((a) => !a.startsWith('-')) ?? 'cursor';
+  const scope = getFlag(args, '--scope', 'all') ?? 'all';
+
+  if (!TARGETS.includes(target)) {
+    throw new Error(`Unknown target: "${target}". Choose from: ${TARGETS.join(', ')}`);
+  }
+
+  console.log(`Updating Gamut plugin for ${target}${scope !== 'all' ? ` (scope: ${scope})` : ''}…`);
+  await install(args);
+}

package/bin/gamut.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+/**
+ * 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 list
+ */
+
+const args = process.argv.slice(2);
+const [noun, verb, ...rest] = args;
+
+if (!noun || noun === '--help' || noun === '-h') {
+  printHelp();
+  process.exit(noun ? 0 : 1);
+}
+
+if (noun !== 'plugin') {
+  console.error(`Unknown command: "${noun}"`);
+  printHelp();
+  process.exit(1);
+}
+
+if (!verb || verb === '--help' || verb === '-h') {
+  printPluginHelp();
+  process.exit(verb ? 0 : 1);
+}
+
+let cmd;
+try {
+  cmd = await import(`./commands/plugin/${verb}.mjs`);
+} catch {
+  console.error(`Unknown plugin subcommand: "${verb}"`);
+  printPluginHelp();
+  process.exit(1);
+}
+
+if (rest.includes('--help') || rest.includes('-h')) {
+  cmd.help();
+  process.exit(0);
+}
+
+try {
+  await cmd.default(rest);
+} catch (/** @type {any} */ err) {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Help
+// ---------------------------------------------------------------------------
+
+function printHelp() {
+  console.log(`
+gamut — Gamut design system CLI
+
+Usage:
+  gamut <command> [subcommand] [options]
+
+Commands:
+  plugin    Manage the Gamut plugin in your AI/design tools
+
+Run "gamut plugin --help" for plugin subcommands.
+`);
+}
+
+function printPluginHelp() {
+  console.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
+
+Targets:   cursor (default)  |  claude  |  figma
+Scopes:    all (default)     |  skills  |  rules  |  commands  |  agents
+
+Examples:
+  gamut plugin install
+  gamut plugin install claude
+  gamut plugin install cursor --scope skills
+  gamut plugin remove claude
+  gamut plugin update
+  gamut plugin list
+`);
+}

package/bin/lib/claude.mjs

@@ -0,0 +1,52 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Reads .claude-plugin/marketplace.json and returns a "name@marketplace" plugin spec.
+ *
+ * @param {string} sourceRoot
+ * @returns {Promise<string>}
+ */
+export async function claudePluginSpec(sourceRoot) {
+  const mp = join(sourceRoot, '.claude-plugin', 'marketplace.json');
+  let text;
+  try {
+    text = await readFile(mp, 'utf8');
+  } catch {
+    throw new Error(
+      `Missing ${mp}.\n` +
+        `A .claude-plugin/marketplace.json is required for Claude Code installation.`,
+    );
+  }
+
+  const json =
+    /** @type {{ name?: string; plugins?: Array<{ name?: string; source?: string }> }} */ (
+      JSON.parse(text)
+    );
+  const { name: marketplaceName, plugins } = json;
+
+  if (!marketplaceName || !Array.isArray(plugins) || plugins.length === 0) {
+    throw new Error(`Invalid marketplace.json — needs "name" and "plugins[]": ${mp}`);
+  }
+
+  const entry =
+    plugins.find((p) => p.source === './' || p.source === '.' || p.source == null) ?? plugins[0];
+
+  if (!entry?.name) {
+    throw new Error(`No plugin name found in marketplace.json plugins[]: ${mp}`);
+  }
+
+  return `${entry.name}@${marketplaceName}`;
+}
+
+/**
+ * Returns just the marketplace name portion of a plugin spec ("name@marketplace").
+ *
+ * @param {string} spec
+ * @returns {string}
+ */
+export function marketplaceName(spec) {
+  const name = spec.split('@')[1];
+  if (!name) throw new Error(`Could not parse marketplace name from plugin spec: ${spec}`);
+  return name;
+}

package/bin/lib/cursor.mjs

@@ -0,0 +1,40 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** @returns {string} */
+export function cursorPluginsRoot() {
+  return process.env.CURSOR_PLUGINS_LOCAL ?? join(homedir(), '.cursor', 'plugins', 'local');
+}
+
+/**
+ * Reads the .cursor-plugin/plugin.json manifest and derives a folder name.
+ * Falls back to "gamut-agent-tools" if no manifest is found.
+ *
+ * @param {string} sourceRoot
+ * @returns {Promise<string>}
+ */
+export async function cursorFolderName(sourceRoot) {
+  const manifest = join(sourceRoot, '.cursor-plugin', 'plugin.json');
+  try {
+    const text = await readFile(manifest, 'utf8');
+    const json = /** @type {{ name?: string }} */ (JSON.parse(text));
+    if (json.name && typeof json.name === 'string') {
+      return json.name.replace(/^@/, '').replace(/\//g, '-');
+    }
+  } catch {
+    // no manifest — use default
+  }
+  return 'gamut-agent-tools';
+}
+
+/**
+ * Returns the absolute path where the plugin is/should be installed for Cursor.
+ *
+ * @param {string} sourceRoot
+ * @returns {Promise<string>}
+ */
+export async function cursorDestPath(sourceRoot) {
+  const folderName = await cursorFolderName(sourceRoot);
+  return join(cursorPluginsRoot(), folderName);
+}

package/bin/lib/figma.mjs

@@ -0,0 +1,49 @@
+import { stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+/**
+ * Walk up from `startDir` looking for a `figma.config.json` file.
+ * Returns the directory containing it, or null if not found before the filesystem root.
+ *
+ * @param {string} startDir
+ * @returns {Promise<string | null>}
+ */
+export async function findFigmaConfigDir(startDir) {
+  let dir = startDir;
+  while (true) {
+    const st = await stat(join(dir, 'figma.config.json')).catch(() => null);
+    if (st?.isFile()) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Resolves the destination directory for the guidelines/ folder.
+ *
+ * Priority:
+ *   1. --output <path> if provided (treated as the parent directory)
+ *   2. Directory containing the nearest figma.config.json (walking up from cwd)
+ *
+ * Throws with actionable guidance if neither resolves.
+ *
+ * @param {string | undefined} outputArg
+ * @returns {Promise<{ path: string; discovered: boolean }>}
+ */
+export async function resolveFigmaOutput(outputArg) {
+  if (outputArg) {
+    return { path: resolve(outputArg), discovered: false };
+  }
+
+  const dir = await findFigmaConfigDir(process.cwd());
+  if (dir) {
+    return { path: join(dir, 'guidelines'), discovered: true };
+  }
+
+  throw new Error(
+    `Could not find figma.config.json in ${process.cwd()} or any parent directory.\n` +
+      `Provide the destination explicitly with --output:\n` +
+      `  gamut plugin install figma --output /path/to/your/project/guidelines`,
+  );
+}