create-restforge-skills 1.0.0 → 1.0.2

package/cli/index.js

@@ -1,250 +1,250 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * create-restforge-skills
- *
- * Installs the bundled RESTForge Agent Skill (skills/restforge/) into the
- * skills directory of each detected client (Claude Code, Cursor, ...) AND
- * registers the RESTForge MCP server, because the skill is inert without it.
- *
- * The skill is the payload; this CLI is the delivery mechanism. It copies the
- * whole skill folder — SKILL.md AND references/ — so reference links keep
- * working, and merges (never overwrites) the MCP server into each client config.
- *
- * It does NOT set a license; that secret stays a manual step.
- *
- * Uses a TOML parser for Codex configuration; works on Windows, macOS and Linux.
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const { buildEntry, registerMcp } = require('./mcp');
-const { registerCodexMcp, formatCodexMcp } = require('./codex');
-const codexHome = () => process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-
-const SKILL_NAME = 'restforge';
-// Bundled skill source: <package>/skills/restforge, resolved relative to this file.
-const SOURCE_DIR = path.join(__dirname, '..', 'skills', SKILL_NAME);
-
-/**
- * Client registry. Each client knows where its skills live (user vs project
- * scope) and where its MCP config file is. Paths are computed lazily so we never
- * touch the filesystem for a client the user did not select.
- */
-const CLIENTS = {
-  codex: {
-    label: 'Codex',
-    homeMarker: codexHome,
-    skillsDir: (scope, cwd) => path.join(scope === 'project' ? cwd : os.homedir(), '.agents', 'skills'),
-    mcpConfig: (scope, cwd) => path.join(scope === 'project' ? path.join(cwd, '.codex') : codexHome(), 'config.toml'),
-  },
-  claude: {
-    label: 'Claude Code',
-    homeMarker: () => path.join(os.homedir(), '.claude'),
-    skillsDir: (scope, cwd) =>
-      scope === 'project'
-        ? path.join(cwd, '.claude', 'skills')
-        : path.join(os.homedir(), '.claude', 'skills'),
-    mcpConfig: (scope, cwd) =>
-      scope === 'project'
-        ? path.join(cwd, '.mcp.json')
-        : path.join(os.homedir(), '.claude.json'),
-  },
-  cursor: {
-    label: 'Cursor',
-    homeMarker: () => path.join(os.homedir(), '.cursor'),
-    skillsDir: (scope, cwd) =>
-      scope === 'project'
-        ? path.join(cwd, '.cursor', 'skills')
-        : path.join(os.homedir(), '.cursor', 'skills'),
-    mcpConfig: (scope, cwd) =>
-      scope === 'project'
-        ? path.join(cwd, '.cursor', 'mcp.json')
-        : path.join(os.homedir(), '.cursor', 'mcp.json'),
-  },
-};
-
-function parseArgs(argv) {
-  const opts = {
-    clients: null, // null = auto-detect
-    scope: 'user', // 'user' | 'project'
-    dryRun: false,
-    force: false,
-    mcp: true, // register MCP by default — the skill is useless without it
-    mcpCommand: 'npx', // 'npx' (no global install) | 'global' (restforge-mcp)
-    yes: false,
-    help: false,
-  };
-  for (const arg of argv) {
-    if (arg === '--help' || arg === '-h') opts.help = true;
-    else if (arg === '--yes' || arg === '-y') opts.yes = true;
-    else if (arg === '--dry-run') opts.dryRun = true;
-    else if (arg === '--force') opts.force = true;
-    else if (arg === '--no-mcp') opts.mcp = false;
-    else if (arg === '--with-mcp') opts.mcp = true; // accepted; now the default
-    else if (arg.startsWith('--mcp-command=')) {
-      opts.mcpCommand = arg.slice('--mcp-command='.length).trim().toLowerCase();
-    } else if (arg.startsWith('--client=')) {
-      opts.clients = arg
-        .slice('--client='.length)
-        .split(',')
-        .map((c) => c.trim().toLowerCase())
-        .filter(Boolean);
-    } else if (arg.startsWith('--scope=')) {
-      opts.scope = arg.slice('--scope='.length).trim().toLowerCase();
-    } else {
-      console.error(`Unknown argument: ${arg}`);
-      opts.help = true;
-    }
-  }
-  return opts;
-}
-
-const HELP = `
-create-restforge-skills — install the RESTForge Agent Skill into your clients.
-
-Usage:
-  npx create-restforge-skills [options]
-
-By default this copies the skill AND registers the RESTForge MCP server (via npx),
-so it works out of the box. The MCP config is merged, not overwritten, and the
-existing file is backed up to <config>.bak first.
-
-Options:
-  --client=<list>      Comma-separated clients: claude,cursor,codex. Default: auto-detect.
-  --scope=<scope>      user (default) installs globally for you; project installs
-                       into ./.claude, ./.cursor or ./.agents (Codex).
-  --no-mcp             Skip MCP registration (only do this if you know why —
-                       the skill cannot call anything without the MCP server).
-  --mcp-command=<c>    npx (default, no global install needed) or
-                       global (uses the installed restforge-mcp binary).
-  --force              Overwrite an existing restforge skill folder.
-  --dry-run            Show what would happen without writing anything.
-  --yes, -y            Run non-interactively, accepting defaults.
-  --help, -h           Show this help.
-`;
-
-/** Decide which clients to target. */
-function resolveClients(opts) {
-  if (opts.clients && opts.clients.length) {
-    const unknown = opts.clients.filter((c) => !CLIENTS[c]);
-    if (unknown.length) {
-      console.error(`Unknown client(s): ${unknown.join(', ')}`);
-      console.error(`Supported: ${Object.keys(CLIENTS).join(', ')}`);
-      process.exit(1);
-    }
-    return opts.clients;
-  }
-  // Auto-detect: a client counts as present if its home marker dir exists.
-  return Object.keys(CLIENTS).filter((key) => {
-    try {
-      return fs.statSync(CLIENTS[key].homeMarker()).isDirectory();
-    } catch {
-      return false;
-    }
-  });
-}
-
-/** Build the concrete install targets for the chosen clients and scope. */
-function buildTargets(clientKeys, opts) {
-  const cwd = process.cwd();
-  return clientKeys.map((key) => {
-    const client = CLIENTS[key];
-    return {
-      key,
-      label: client.label,
-      dest: path.join(client.skillsDir(opts.scope, cwd), SKILL_NAME),
-      mcpConfig: client.mcpConfig(opts.scope, cwd),
-    };
-  });
-}
-
-/** Copy the skill folder (SKILL.md + references/) into one target. */
-function installSkill(target, opts) {
-  const exists = fs.existsSync(target.dest);
-  if (exists && !opts.force) {
-    return { status: 'skipped', reason: 'already exists (use --force to overwrite)' };
-  }
-  if (opts.dryRun) {
-    return { status: exists ? 'would-overwrite' : 'would-install' };
-  }
-  fs.mkdirSync(path.dirname(target.dest), { recursive: true });
-  if (exists) fs.rmSync(target.dest, { recursive: true, force: true });
-  fs.cpSync(SOURCE_DIR, target.dest, { recursive: true });
-  return { status: exists ? 'overwritten' : 'installed' };
-}
-
-const pad = (s) => String(s).padEnd(12);
-
-function main() {
-  const opts = parseArgs(process.argv.slice(2));
-  if (opts.help) {
-    process.stdout.write(HELP);
-    return;
-  }
-
-  if (!['user', 'project'].includes(opts.scope)) {
-    console.error(`Invalid --scope: ${opts.scope} (expected "user" or "project")`);
-    process.exit(1);
-  }
-  if (!['npx', 'global'].includes(opts.mcpCommand)) {
-    console.error(`Invalid --mcp-command: ${opts.mcpCommand} (expected "npx" or "global")`);
-    process.exit(1);
-  }
-  if (!fs.existsSync(path.join(SOURCE_DIR, 'SKILL.md'))) {
-    console.error(`Bundled skill not found at ${SOURCE_DIR}. Broken package?`);
-    process.exit(1);
-  }
-
-  const clientKeys = resolveClients(opts);
-  if (!clientKeys.length) {
-    console.error('No target client detected (looked for ~/.claude, ~/.cursor and CODEX_HOME or ~/.codex).');
-    console.error('Pass one explicitly, e.g. --client=codex');
-    process.exit(1);
-  }
-
-  const targets = buildTargets(clientKeys, opts);
-  const mcpEntry = buildEntry(opts.mcpCommand);
-
-  console.log(
-    `\nRESTForge skill — ${opts.dryRun ? 'dry run' : 'install'} (scope: ${opts.scope}` +
-      `, mcp: ${opts.mcp ? opts.mcpCommand : 'off'})\n`
-  );
-
-  for (const target of targets) {
-    const skill = installSkill(target, opts);
-    console.log(`  ${pad(target.label)} ${target.dest}`);
-    console.log(`  ${pad('')} → skill: ${skill.status}${skill.reason ? ` (${skill.reason})` : ''}`);
-
-    if (opts.mcp) {
-      const register = target.key === 'codex' ? registerCodexMcp : registerMcp;
-      const mcp = register(target.mcpConfig, mcpEntry, opts);
-      console.log(`  ${pad('')} → mcp:   ${mcp.status}${mcp.error ? ` — ${mcp.error}` : ''}`);
-      console.log(`  ${pad('')}          ${target.mcpConfig}`);
-      if (mcp.backup) console.log(`  ${pad('')}          backup: ${mcp.backup}`);
-      if (mcp.status === 'error') {
-        process.exitCode = 1;
-        const manual = target.key === 'codex' ? formatCodexMcp(mcpEntry) : `"mcpServers": { "restforge": ${JSON.stringify(mcpEntry)} }`;
-        console.log(`  ${pad('')}          add manually: ${manual}`);
-      }
-      if (mcp.status === 'preserved') console.log('                Existing Codex RESTForge settings kept; edit config.toml to change them.');
-    }
-  }
-
-  console.log('\nNext step:');
-  console.log('  Set a valid RESTForge LICENSE for codegen_*/runtime_* operations.');
-  console.log('  (Designer/frontend tools work without a license.)');
-  if (clientKeys.includes('claude')) {
-    console.log('  Claude Code: if its skills dir was just created, restart the client so it');
-    console.log('  watches the new directory.');
-  }
-  if (clientKeys.includes('codex')) {
-    console.log('  Codex: restart the session, then invoke $restforge. Use /mcp to check the server.');
-    if (opts.scope === 'project') console.log('  Codex only loads project .codex/config.toml in trusted projects.');
-  }
-  console.log('');
-}
-
-main();
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * create-restforge-skills
+ *
+ * Installs the bundled RESTForge Agent Skill (skills/restforge/) into the
+ * skills directory of each detected client (Claude Code, Cursor, ...) AND
+ * registers the RESTForge MCP server, because the skill is inert without it.
+ *
+ * The skill is the payload; this CLI is the delivery mechanism. It copies the
+ * whole skill folder — SKILL.md AND references/ — so reference links keep
+ * working, and merges (never overwrites) the MCP server into each client config.
+ *
+ * It does NOT set a license; that secret stays a manual step.
+ *
+ * Uses a TOML parser for Codex configuration; works on Windows, macOS and Linux.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { buildEntry, registerMcp } = require('./mcp');
+const { registerCodexMcp, formatCodexMcp } = require('./codex');
+const codexHome = () => process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+
+const SKILL_NAME = 'restforge';
+// Bundled skill source: <package>/skills/restforge, resolved relative to this file.
+const SOURCE_DIR = path.join(__dirname, '..', 'skills', SKILL_NAME);
+
+/**
+ * Client registry. Each client knows where its skills live (user vs project
+ * scope) and where its MCP config file is. Paths are computed lazily so we never
+ * touch the filesystem for a client the user did not select.
+ */
+const CLIENTS = {
+  codex: {
+    label: 'Codex',
+    homeMarker: codexHome,
+    skillsDir: (scope, cwd) => path.join(scope === 'project' ? cwd : os.homedir(), '.agents', 'skills'),
+    mcpConfig: (scope, cwd) => path.join(scope === 'project' ? path.join(cwd, '.codex') : codexHome(), 'config.toml'),
+  },
+  claude: {
+    label: 'Claude Code',
+    homeMarker: () => path.join(os.homedir(), '.claude'),
+    skillsDir: (scope, cwd) =>
+      scope === 'project'
+        ? path.join(cwd, '.claude', 'skills')
+        : path.join(os.homedir(), '.claude', 'skills'),
+    mcpConfig: (scope, cwd) =>
+      scope === 'project'
+        ? path.join(cwd, '.mcp.json')
+        : path.join(os.homedir(), '.claude.json'),
+  },
+  cursor: {
+    label: 'Cursor',
+    homeMarker: () => path.join(os.homedir(), '.cursor'),
+    skillsDir: (scope, cwd) =>
+      scope === 'project'
+        ? path.join(cwd, '.cursor', 'skills')
+        : path.join(os.homedir(), '.cursor', 'skills'),
+    mcpConfig: (scope, cwd) =>
+      scope === 'project'
+        ? path.join(cwd, '.cursor', 'mcp.json')
+        : path.join(os.homedir(), '.cursor', 'mcp.json'),
+  },
+};
+
+function parseArgs(argv) {
+  const opts = {
+    clients: null, // null = auto-detect
+    scope: 'user', // 'user' | 'project'
+    dryRun: false,
+    force: false,
+    mcp: true, // register MCP by default — the skill is useless without it
+    mcpCommand: 'npx', // 'npx' (no global install) | 'global' (restforge-mcp)
+    yes: false,
+    help: false,
+  };
+  for (const arg of argv) {
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--yes' || arg === '-y') opts.yes = true;
+    else if (arg === '--dry-run') opts.dryRun = true;
+    else if (arg === '--force') opts.force = true;
+    else if (arg === '--no-mcp') opts.mcp = false;
+    else if (arg === '--with-mcp') opts.mcp = true; // accepted; now the default
+    else if (arg.startsWith('--mcp-command=')) {
+      opts.mcpCommand = arg.slice('--mcp-command='.length).trim().toLowerCase();
+    } else if (arg.startsWith('--client=')) {
+      opts.clients = arg
+        .slice('--client='.length)
+        .split(',')
+        .map((c) => c.trim().toLowerCase())
+        .filter(Boolean);
+    } else if (arg.startsWith('--scope=')) {
+      opts.scope = arg.slice('--scope='.length).trim().toLowerCase();
+    } else {
+      console.error(`Unknown argument: ${arg}`);
+      opts.help = true;
+    }
+  }
+  return opts;
+}
+
+const HELP = `
+create-restforge-skills — install the RESTForge Agent Skill into your clients.
+
+Usage:
+  npx create-restforge-skills [options]
+
+By default this copies the skill AND registers the RESTForge MCP server (via npx),
+so it works out of the box. The MCP config is merged, not overwritten, and the
+existing file is backed up to <config>.bak first.
+
+Options:
+  --client=<list>      Comma-separated clients: claude,cursor,codex. Default: auto-detect.
+  --scope=<scope>      user (default) installs globally for you; project installs
+                       into ./.claude, ./.cursor or ./.agents (Codex).
+  --no-mcp             Skip MCP registration (only do this if you know why —
+                       the skill cannot call anything without the MCP server).
+  --mcp-command=<c>    npx (default, no global install needed) or
+                       global (uses the installed restforge-mcp binary).
+  --force              Overwrite an existing restforge skill folder.
+  --dry-run            Show what would happen without writing anything.
+  --yes, -y            Run non-interactively, accepting defaults.
+  --help, -h           Show this help.
+`;
+
+/** Decide which clients to target. */
+function resolveClients(opts) {
+  if (opts.clients && opts.clients.length) {
+    const unknown = opts.clients.filter((c) => !CLIENTS[c]);
+    if (unknown.length) {
+      console.error(`Unknown client(s): ${unknown.join(', ')}`);
+      console.error(`Supported: ${Object.keys(CLIENTS).join(', ')}`);
+      process.exit(1);
+    }
+    return opts.clients;
+  }
+  // Auto-detect: a client counts as present if its home marker dir exists.
+  return Object.keys(CLIENTS).filter((key) => {
+    try {
+      return fs.statSync(CLIENTS[key].homeMarker()).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** Build the concrete install targets for the chosen clients and scope. */
+function buildTargets(clientKeys, opts) {
+  const cwd = process.cwd();
+  return clientKeys.map((key) => {
+    const client = CLIENTS[key];
+    return {
+      key,
+      label: client.label,
+      dest: path.join(client.skillsDir(opts.scope, cwd), SKILL_NAME),
+      mcpConfig: client.mcpConfig(opts.scope, cwd),
+    };
+  });
+}
+
+/** Copy the skill folder (SKILL.md + references/) into one target. */
+function installSkill(target, opts) {
+  const exists = fs.existsSync(target.dest);
+  if (exists && !opts.force) {
+    return { status: 'skipped', reason: 'already exists (use --force to overwrite)' };
+  }
+  if (opts.dryRun) {
+    return { status: exists ? 'would-overwrite' : 'would-install' };
+  }
+  fs.mkdirSync(path.dirname(target.dest), { recursive: true });
+  if (exists) fs.rmSync(target.dest, { recursive: true, force: true });
+  fs.cpSync(SOURCE_DIR, target.dest, { recursive: true });
+  return { status: exists ? 'overwritten' : 'installed' };
+}
+
+const pad = (s) => String(s).padEnd(12);
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  if (!['user', 'project'].includes(opts.scope)) {
+    console.error(`Invalid --scope: ${opts.scope} (expected "user" or "project")`);
+    process.exit(1);
+  }
+  if (!['npx', 'global'].includes(opts.mcpCommand)) {
+    console.error(`Invalid --mcp-command: ${opts.mcpCommand} (expected "npx" or "global")`);
+    process.exit(1);
+  }
+  if (!fs.existsSync(path.join(SOURCE_DIR, 'SKILL.md'))) {
+    console.error(`Bundled skill not found at ${SOURCE_DIR}. Broken package?`);
+    process.exit(1);
+  }
+
+  const clientKeys = resolveClients(opts);
+  if (!clientKeys.length) {
+    console.error('No target client detected (looked for ~/.claude, ~/.cursor and CODEX_HOME or ~/.codex).');
+    console.error('Pass one explicitly, e.g. --client=codex');
+    process.exit(1);
+  }
+
+  const targets = buildTargets(clientKeys, opts);
+
+  console.log(
+    `\nRESTForge skill — ${opts.dryRun ? 'dry run' : 'install'} (scope: ${opts.scope}` +
+      `, mcp: ${opts.mcp ? opts.mcpCommand : 'off'})\n`
+  );
+
+  for (const target of targets) {
+    const skill = installSkill(target, opts);
+    console.log(`  ${pad(target.label)} ${target.dest}`);
+    console.log(`  ${pad('')} → skill: ${skill.status}${skill.reason ? ` (${skill.reason})` : ''}`);
+
+    if (opts.mcp) {
+      const mcpEntry = buildEntry(opts.mcpCommand, target.key);
+      const register = target.key === 'codex' ? registerCodexMcp : registerMcp;
+      const mcp = register(target.mcpConfig, mcpEntry, opts);
+      console.log(`  ${pad('')} → mcp:   ${mcp.status}${mcp.error ? ` — ${mcp.error}` : ''}`);
+      console.log(`  ${pad('')}          ${target.mcpConfig}`);
+      if (mcp.backup) console.log(`  ${pad('')}          backup: ${mcp.backup}`);
+      if (mcp.status === 'error') {
+        process.exitCode = 1;
+        const manual = target.key === 'codex' ? formatCodexMcp(mcpEntry) : `"mcpServers": { "restforge": ${JSON.stringify(mcpEntry)} }`;
+        console.log(`  ${pad('')}          add manually: ${manual}`);
+      }
+      if (mcp.status === 'preserved') console.log('                Existing Codex RESTForge settings kept; edit config.toml to change them.');
+    }
+  }
+
+  console.log('\nNext step:');
+  console.log('  Set a valid RESTForge LICENSE for codegen_*/runtime_* operations.');
+  console.log('  (Designer/frontend tools work without a license.)');
+  if (clientKeys.includes('claude')) {
+    console.log('  Claude Code: if its skills dir was just created, restart the client so it');
+    console.log('  watches the new directory.');
+  }
+  if (clientKeys.includes('codex')) {
+    console.log('  Codex: restart the session, then invoke $restforge. Use /mcp to check the server.');
+    if (opts.scope === 'project') console.log('  Codex only loads project .codex/config.toml in trusted projects.');
+  }
+  console.log('');
+}
+
+main();