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

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.0",
+  "version": "68.6.1-alpha.edab62.0",
   "author": "Codecademy Engineering <dev@codecademy.com>",
+  "bin": "./bin/gamut.mjs",
   "dependencies": {
-    "@codecademy/gamut-icons": "9.57.5",
-    "@codecademy/gamut-illustrations": "0.58.11",
-    "@codecademy/gamut-patterns": "0.10.30",
-    "@codecademy/gamut-styles": "18.0.0",
-    "@codecademy/variance": "0.26.1",
+    "@codecademy/gamut-icons": "9.57.6-alpha.edab62.0",
+    "@codecademy/gamut-illustrations": "0.58.12-alpha.edab62.0",
+    "@codecademy/gamut-patterns": "0.10.31-alpha.edab62.0",
+    "@codecademy/gamut-styles": "18.0.1-alpha.edab62.0",
+    "@codecademy/variance": "0.26.2-alpha.edab62.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",