@codecademy/gamut 68.6.1-alpha.f6b2ce.0 → 68.6.2-alpha.1fc7ca.0

package/bin/commands/plugin/install.mjs

@@ -1,213 +0,0 @@
-import { cp, mkdir, readdir, rm, symlink } from 'node:fs/promises';
-import { resolve } from 'node:path';
-
-import { claudePluginSpec, marketplaceName } from '../../lib/claude.mjs';
-import { cursorDestPath } from '../../lib/cursor.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'];
-export const SCOPES = ['all', 'skills', 'rules', 'commands', 'agents'];
-
-export function help() {
-  log(`
-Usage:
-  gamut plugin install [target] [options]
-
-Install the Gamut plugin into an AI tool.
-
-Arguments:
-  target               Tool to install into (default: cursor)
-                       cursor | claude
-
-Options:
-  --scope <scope>      Content to install (default: all)
-                       all | skills | rules | commands | agents
-  --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 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
-`);
-}
-
-// ---------------------------------------------------------------------------
-
-/** 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
-]);
-
-/** @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');
-    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];
-  }
-
-  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;
-  log(`Cursor: installed (${scopeLabel}) → ${dest}`);
-}
-
-// Claude Code only loads from recognized plugin directories: skills/, commands/, agents/.
-// 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) {
-  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) {
-    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`
-    );
-  }
-
-  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] [--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);
-  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);
-  }
-
-  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,73 +0,0 @@
-import { stat } from 'node:fs/promises';
-
-import { cursorDestPath } from '../../lib/cursor.mjs';
-import { log } from '../../lib/io.mjs';
-import { resolvePluginDir } from '../../lib/resolve-plugin-dir.mjs';
-
-export function help() {
-  log(`
-Usage:
-  gamut plugin list [options]
-
-Show installation status for all supported targets.
-
-Options:
-  --plugin-dir <path>  Override the bundled agent-tools directory
-  -h, --help           Show this help message
-
-Examples:
-  gamut plugin list
-`);
-}
-
-// ---------------------------------------------------------------------------
-
-/** @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',
-  };
-}
-
-// ---------------------------------------------------------------------------
-
-/**
- * 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 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 rule = '─'.repeat(header.length);
-
-  log(`\n${header}`);
-  log(rule);
-  for (const row of rows) {
-    log(`${row.target.padEnd(col0)}  ${row.status.padEnd(col1)}  ${row.notes}`);
-  }
-  log('');
-}

package/bin/commands/plugin/remove.mjs

@@ -1,108 +0,0 @@
-import { rm, stat } from 'node:fs/promises';
-
-import { claudePluginSpec, marketplaceName } from '../../lib/claude.mjs';
-import { cursorDestPath } from '../../lib/cursor.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() {
-  log(`
-Usage:
-  gamut plugin remove [target] [options]
-
-Remove the installed Gamut plugin from an AI tool.
-
-Arguments:
-  target               Tool to remove from (default: cursor)
-                       cursor | claude
-
-Options:
-  --plugin-dir <path>  Override the bundled agent-tools directory
-  -h, --help           Show this help message
-
-Examples:
-  gamut plugin remove
-  gamut plugin remove claude
-`);
-}
-
-// ---------------------------------------------------------------------------
-
-/** @param {string} sourceRoot */
-async function removeCursor(sourceRoot) {
-  const dest = await cursorDestPath(sourceRoot);
-  const st = await stat(dest).catch(() => null);
-
-  if (!st) {
-    log(`Cursor: nothing to remove — ${dest} does not exist.`);
-    return;
-  }
-
-  await rm(dest, { recursive: true, force: true });
-  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) {
-    warn(
-      `warning: "claude plugin remove" exited ${code} — the plugin may not have been installed.`
-    );
-  } else {
-    log(`Claude Code: removed plugin "${pluginName}"`);
-  }
-
-  code = await runCommand('claude', [
-    'plugin',
-    'marketplace',
-    'remove',
-    mpName,
-  ]);
-  if (code !== 0) {
-    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 {
-    log(`Claude Code: removed marketplace "${mpName}"`);
-  }
-}
-
-// ---------------------------------------------------------------------------
-
-/**
- * gamut plugin remove [cursor|claude] [--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);
-  }
-}

package/bin/commands/plugin/update.mjs

@@ -1,59 +0,0 @@
-import { log } from '../../lib/io.mjs';
-import { getFlag } from '../../lib/resolve-plugin-dir.mjs';
-import install, { TARGETS } from './install.mjs';
-
-export function help() {
-  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
-
-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] [--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(', ')}`
-    );
-  }
-
-  log(
-    `Updating Gamut plugin for ${target}${
-      scope !== 'all' ? ` (scope: ${scope})` : ''
-    }…`
-  );
-  await install(args);
-}

package/bin/gamut.mjs

@@ -1,96 +0,0 @@
-#!/usr/bin/env node
-
-import { error, log } from './lib/io.mjs';
-
-/**
- * Gamut CLI
- *
- * Usage:
- *   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
- */
-
-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') {
-  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 {
-  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) {
-  error(`Error: ${err.message}`);
-  process.exit(1);
-}
-
-// ---------------------------------------------------------------------------
-// Help
-// ---------------------------------------------------------------------------
-
-function printHelp() {
-  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() {
-  log(`
-gamut plugin — Manage the Gamut plugin
-
-Subcommands:
-  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
-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
-  gamut plugin list
-`);
-}

package/bin/lib/claude.mjs

@@ -1,52 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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);
-}