@codecademy/gamut 68.6.2-alpha.f8b396.0 → 68.6.2

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 | 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|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|agents]
- *   gamut plugin remove  [cursor|claude]
- *   gamut plugin update  [cursor|claude] [--scope all|skills|rules|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  |  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);
-}

package/bin/lib/design.mjs

@@ -1,71 +0,0 @@
-import { copyFile, stat } from 'node:fs/promises';
-import { join } from 'node:path';
-
-/** @type {Record<string, { sourceFile: string, label: string }>} */
-const THEME_ALIASES = {
-  core: { sourceFile: 'DESIGN.Codecademy.md', label: 'Codecademy (Core)' },
-  codecademy: {
-    sourceFile: 'DESIGN.Codecademy.md',
-    label: 'Codecademy (Core)',
-  },
-  cc: { sourceFile: 'DESIGN.Codecademy.md', label: 'Codecademy (Core)' },
-  admin: { sourceFile: 'DESIGN.Codecademy.md', label: 'Codecademy (Admin)' },
-  platform: {
-    sourceFile: 'DESIGN.Codecademy.md',
-    label: 'Codecademy (Platform)',
-  },
-  percipio: { sourceFile: 'DESIGN.Percipio.md', label: 'Percipio' },
-  lxstudio: { sourceFile: 'DESIGN.LXStudio.md', label: 'LX Studio' },
-  'lx-studio': { sourceFile: 'DESIGN.LXStudio.md', label: 'LX Studio' },
-};
-
-const CANONICAL_THEMES = ['core', 'admin', 'platform', 'percipio', 'lxstudio'];
-
-/**
- * @param {string} name
- * @returns {{ sourceFile: string, label: string, alias: string }}
- */
-export function resolveTheme(name) {
-  const alias = name.trim().toLowerCase();
-  const entry = THEME_ALIASES[alias];
-  if (!entry) {
-    throw new Error(
-      `Unknown theme: "${name}". Choose from: ${CANONICAL_THEMES.join(', ')} ` +
-        `(aliases: codecademy, cc, lx-studio, …).`
-    );
-  }
-  return { ...entry, alias };
-}
-
-/** @returns {string[]} */
-export function listCanonicalThemes() {
-  return [...CANONICAL_THEMES];
-}
-
-/**
- * @param {string} sourceRoot agent-tools directory
- * @param {string} cwd destination directory (app repo root)
- * @param {string} theme
- * @param {{ force?: boolean }} [options]
- * @returns {Promise<{ dest: string, label: string }>}
- */
-export async function installDesignMd(sourceRoot, cwd, theme, options = {}) {
-  const { sourceFile, label } = resolveTheme(theme);
-  const src = join(sourceRoot, sourceFile);
-  const dest = join(cwd, 'DESIGN.md');
-
-  const srcStat = await stat(src).catch(() => null);
-  if (!srcStat?.isFile()) {
-    throw new Error(`DESIGN source not found: ${src}`);
-  }
-
-  const destStat = await stat(dest).catch(() => null);
-  if (destStat?.isFile() && !options.force) {
-    throw new Error(
-      `DESIGN.md already exists at ${dest}. Use --force to overwrite, or remove it first.`
-    );
-  }
-
-  await copyFile(src, dest);
-  return { dest, label };
-}

package/bin/lib/io.mjs

@@ -1,14 +0,0 @@
-/** @param {string} message */
-export function log(message) {
-  process.stdout.write(message.endsWith('\n') ? message : `${message}\n`);
-}
-
-/** @param {string} message */
-export function warn(message) {
-  process.stderr.write(message.endsWith('\n') ? message : `${message}\n`);
-}
-
-/** @param {string} message */
-export function error(message) {
-  process.stderr.write(message.endsWith('\n') ? message : `${message}\n`);
-}

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

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

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