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

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`,
+  );
+}

package/bin/lib/resolve-plugin-dir.mjs

@@ -0,0 +1,38 @@
+import { stat } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Returns the absolute path to the bundled agent-tools directory, or the
+ * value of --plugin-dir if provided.
+ *
+ * @param {string[]} args
+ * @returns {Promise<string>}
+ */
+export async function resolvePluginDir(args) {
+  const override = getFlag(args, '--plugin-dir');
+  if (override) {
+    const abs = resolve(override);
+    const st = await stat(abs).catch(() => null);
+    if (!st?.isDirectory()) {
+      throw new Error(`--plugin-dir path not found: ${abs}`);
+    }
+    return abs;
+  }
+
+  // agent-tools/ is bundled at <package-root>/agent-tools/ relative to bin/lib/
+  return resolve(__dirname, '..', '..', 'agent-tools');
+}
+
+/**
+ * @param {string[]} argv
+ * @param {string} flag
+ * @param {string} [fallback]
+ * @returns {string | undefined}
+ */
+export function getFlag(argv, flag, fallback) {
+  const idx = argv.indexOf(flag);
+  return idx !== -1 ? argv[idx + 1] : fallback;
+}

package/bin/lib/run-command.mjs

@@ -0,0 +1,22 @@
+import { spawn } from 'node:child_process';
+
+/**
+ * Spawns an external command and returns its exit code.
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @returns {Promise<number>}
+ */
+export function runCommand(command, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: 'inherit', shell: false });
+    child.on('error', (/** @type {NodeJS.ErrnoException} */ err) => {
+      if (err.code === 'ENOENT') {
+        reject(new Error(`"${command}" not found on PATH. Is it installed?`));
+      } else {
+        reject(err);
+      }
+    });
+    child.on('close', (code) => resolve(code ?? 1));
+  });
+}

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@codecademy/gamut",
   "description": "Styleguide & Component library for Codecademy",
-  "version": "68.6.1-alpha.c211a2.0",
+  "version": "68.6.1-alpha.d52035.0",
   "author": "Codecademy Engineering <dev@codecademy.com>",
+  "bin": "./bin/gamut.mjs",
   "dependencies": {
-    "@codecademy/gamut-icons": "9.57.6-alpha.c211a2.0",
-    "@codecademy/gamut-illustrations": "0.58.12-alpha.c211a2.0",
-    "@codecademy/gamut-patterns": "0.10.31-alpha.c211a2.0",
-    "@codecademy/gamut-styles": "18.0.1-alpha.c211a2.0",
-    "@codecademy/variance": "0.26.2-alpha.c211a2.0",
+    "@codecademy/gamut-icons": "9.57.6-alpha.d52035.0",
+    "@codecademy/gamut-illustrations": "0.58.12-alpha.d52035.0",
+    "@codecademy/gamut-patterns": "0.10.31-alpha.d52035.0",
+    "@codecademy/gamut-styles": "18.0.1-alpha.d52035.0",
+    "@codecademy/variance": "0.26.2-alpha.d52035.0",
     "@formatjs/intl-locale": "5.3.1",
     "@react-aria/interactions": "3.25.0",
     "@types/marked": "^4.0.8",
@@ -30,7 +31,9 @@
     "sanitize-markdown": "^2.6.7"
   },
   "files": [
-    "dist"
+    "dist",
+    "bin",
+    "agent-tools"
   ],
   "license": "MIT",
   "main": "./dist/index.js",
@@ -52,7 +55,7 @@
     "build": "nx build @codecademy/gamut",
     "build:watch": "yarn build && onchange ./src -- yarn build",
     "compile": "babel ./src --out-dir ./dist --extensions \".ts,.tsx\"",
-    "verify": "tsc --noEmit"
+    "verify": "tsc --noEmit && tsc --project tsconfig.bin.json"
   },
   "sideEffects": [
     "**/*.css",