create-restforge-skills 0.1.0

package/README.md

@@ -0,0 +1,137 @@
+# RESTForge — Agent Skills (portable)
+
+Vendor-neutral [Agent Skills](https://agentskills.io) for RESTForge. The same
+end-to-end RESTForge workflow knowledge, packaged in the open `SKILL.md` format
+so it works across any skills-compatible agent — **Claude Code, Cursor, Gemini
+CLI, and OpenAI Codex** — not only Claude Code.
+
+## What this package is (and is not)
+
+This package is the **portable** distribution of RESTForge agent knowledge.
+
+- It contains pure Agent Skills: a `skills/restforge/SKILL.md` plus `references/`.
+- It has **no** client-specific packaging — no Claude Code `plugin.json`,
+  `marketplace.json`, or `.mcp.json`.
+
+It is a **complement to**, not a replacement for, [`restforge-plugins`](../packages/restforge-plugins).
+
+| | `restforge-plugins` | `restforge-skills` (this package) |
+|---|---|---|
+| Target | Claude Code only | Claude Code, Cursor, Gemini CLI, Codex |
+| Distribution | Claude Code plugin + marketplace | Copy/symlink the skill folder into each client's skills directory |
+| MCP registration | Bundled (`.mcp.json`) | Done per client by the user (see below) |
+| Knowledge source | `skills/restforge-skills/` | Same knowledge, portable form |
+
+Both packages wrap the **same** workflow knowledge and depend on the **same**
+execution engine: the `@restforgejs/mcp-server` MCP server. A skill describes
+*how* to drive RESTForge; the MCP server is *what* actually executes the
+operations. The skill is useless without the MCP server registered in the client.
+
+## Directory layout
+
+```
+restforge-skills/
+├── README.md                 ← this file
+├── package.json              ← npm package: create-restforge-skills
+├── bump-and-publish.bat      ← version bump + npm publish
+├── cli/
+│   └── index.js              ← installer that copies the skill into each client
+├── docs/                     ← internal docs, NOT published (excluded from npm files)
+└── skills/
+    └── restforge/
+        ├── SKILL.md          ← the portable skill (name + description + workflow)
+        └── references/       ← progressive-disclosure reference material
+```
+
+## Install
+
+One command. It detects your installed clients (Claude Code, Cursor), copies the
+skill into each, and registers the RESTForge MCP server — because the skill is
+inert without it:
+
+```bash
+npx create-restforge-skills
+```
+
+The MCP server is registered via `npx -y @restforgejs/mcp-server`, so there is no
+separate global install. The MCP config is **merged, not overwritten**, and the
+existing file is backed up to `<config>.bak` first.
+
+### Where to run it (working directory)
+
+This is an **installer**, not a project scaffolder. Unlike `create-restforge-app`,
+it takes **no positional folder argument** (`myapp` / `.`). The install location
+is chosen by `--scope`, not by where you stand or by a path you pass.
+
+- **Default (`--scope=user`) — run it from anywhere.** The current directory is
+  ignored. The skill goes to your home (`~/.claude/skills/`, `~/.cursor/skills/`)
+  and is available across **all** your projects. This is the normal usage: a skill
+  is editor/agent tooling, not part of any one app's source.
+
+- **`--scope=project` — run it inside the project folder.** Here the current
+  directory matters: the skill and MCP config are written relative to it
+  (`./.claude/...`, `./.cursor/...`), so you must `cd` into the target project
+  first. Use this to commit the skill with a specific repo so the team gets it on
+  clone.
+
+```bash
+# normal — anywhere, global for every project
+npx create-restforge-skills
+
+# attach to one project — cd in first
+cd path/to/my-project
+npx create-restforge-skills --scope=project
+```
+
+Note: a bare path such as `npx create-restforge-skills .` is **not** recognized as
+"install here" — it is treated as an unknown argument. Use `--scope=project`.
+
+### Options
+
+```bash
+npx create-restforge-skills --client=cursor      # one client only
+npx create-restforge-skills --scope=project      # into ./.claude or ./.cursor (commit for the team)
+npx create-restforge-skills --mcp-command=global # use the installed restforge-mcp binary instead of npx
+npx create-restforge-skills --no-mcp             # skill only; you manage MCP yourself
+npx create-restforge-skills --dry-run            # preview, write nothing
+npx create-restforge-skills --force              # overwrite an existing skill (update)
+```
+
+After install, set a valid RESTForge `LICENSE` for `codegen_*`/`runtime_*`
+operations (Designer/frontend tools need no license). On Claude Code, if the
+skills directory was just created, restart the client so it watches the new
+directory.
+
+### Where it installs
+
+| Client | Skill (user scope) | MCP config |
+|---|---|---|
+| Claude Code | `~/.claude/skills/restforge/` | `~/.claude.json` |
+| Cursor | `~/.cursor/skills/restforge/` | `~/.cursor/mcp.json` |
+
+> For Claude Code, a turnkey alternative is the `restforge-plugins` package,
+> which bundles the skill **and** MCP registration in one `/plugin install`.
+
+### Manual install (no CLI)
+
+The skill folder is self-contained — copy `skills/restforge/` (including
+`references/`) into the client's skills directory and add
+`{ "mcpServers": { "restforge": { "command": "npx", "args": ["-y", "@restforgejs/mcp-server"] } } }`
+to the client's MCP config.
+
+### Gemini CLI / OpenAI Codex
+
+Planned. Both consume the same `skills/restforge/` folder; only the skills
+directory path and MCP config file differ per client.
+
+## Source of truth
+
+The knowledge in this skill mirrors the RESTForge handbook
+([`restforge-handbook`](../restforge-handbook)) and the MCP tool surface
+([`mcp-server`](../packages/mcp-server)). When RESTForge behavior changes, update the
+handbook first, then this skill — the skill is downstream documentation of real
+tool behavior, never an independent source.
+
+## License
+
+MIT.

package/cli/index.js

@@ -0,0 +1,235 @@
+#!/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.
+ *
+ * Zero runtime dependencies: Node built-ins only, for fast `npx` and broad
+ * platform support (Windows included).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { buildEntry, registerMcp } = require('./mcp');
+
+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 = {
+  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. Default: auto-detect.
+  --scope=<scope>      user (default) installs globally for you; project installs
+                       into ./.claude or ./.cursor in the current directory.
+  --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 and ~/.cursor).');
+    console.error('Pass one explicitly, e.g. --client=claude,cursor');
+    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 mcp = registerMcp(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') {
+        console.log(`  ${pad('')}          add manually: "mcpServers": { "restforge": ${JSON.stringify(mcpEntry)} }`);
+      }
+    }
+  }
+
+  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.');
+  }
+  console.log('');
+}
+
+main();

package/cli/mcp.js

@@ -0,0 +1,94 @@
+'use strict';
+
+/**
+ * MCP registration for create-restforge-skills.
+ *
+ * The skill is inert without the RESTForge MCP server, so registration is the
+ * default behavior. This module merges (never overwrites) a `restforge` entry
+ * into a client's MCP config and backs the file up first.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Build the MCP server entry.
+ * - 'npx' (default): no separate global install — npx fetches on first run.
+ * - 'global': uses the globally-installed `restforge-mcp` binary (faster start).
+ */
+function buildEntry(mcpCommand) {
+  if (mcpCommand === 'global') {
+    return { command: 'restforge-mcp' };
+  }
+  return { command: 'npx', args: ['-y', '@restforgejs/mcp-server'] };
+}
+
+function readConfig(file) {
+  if (!fs.existsSync(file)) return { existed: false, data: {} };
+  const raw = fs.readFileSync(file, 'utf8').trim();
+  if (!raw) return { existed: true, data: {} };
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    const e = new Error(`config is not valid JSON: ${err.message}`);
+    e.code = 'EBADJSON';
+    throw e;
+  }
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    const e = new Error('config root is not a JSON object');
+    e.code = 'EBADJSON';
+    throw e;
+  }
+  return { existed: true, data };
+}
+
+/**
+ * Merge the `restforge` MCP server into `file`.
+ * Returns { status, backup?, error? } where status is one of:
+ *   registered | updated | already-registered | would-register | would-update | error
+ * Never overwrites unrelated keys; backs up an existing file before writing.
+ */
+function registerMcp(file, entry, opts) {
+  let cfg;
+  try {
+    cfg = readConfig(file);
+  } catch (err) {
+    if (err.code === 'EBADJSON') {
+      // Refuse to touch a config we cannot safely parse.
+      return { status: 'error', error: err.message };
+    }
+    throw err;
+  }
+
+  const data = cfg.data;
+  const servers =
+    data.mcpServers && typeof data.mcpServers === 'object' && !Array.isArray(data.mcpServers)
+      ? data.mcpServers
+      : {};
+
+  const existing = servers.restforge;
+  if (existing && JSON.stringify(existing) === JSON.stringify(entry)) {
+    return { status: 'already-registered' };
+  }
+
+  const willUpdate = Boolean(existing);
+  if (opts.dryRun) {
+    return { status: willUpdate ? 'would-update' : 'would-register' };
+  }
+
+  let backup;
+  if (cfg.existed) {
+    backup = file + '.bak';
+    fs.copyFileSync(file, backup);
+  }
+
+  servers.restforge = entry;
+  data.mcpServers = servers;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n', 'utf8');
+
+  return { status: willUpdate ? 'updated' : 'registered', backup };
+}
+
+module.exports = { buildEntry, registerMcp };

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "create-restforge-skills",
+  "version": "0.1.0",
+  "description": "Install the RESTForge Agent Skill into Claude Code, Cursor, and other skills-compatible clients.",
+  "type": "commonjs",
+  "bin": {
+    "create-restforge-skills": "cli/index.js"
+  },
+  "files": [
+    "cli",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "restforge",
+    "agent-skills",
+    "skill",
+    "claude-code",
+    "cursor",
+    "mcp"
+  ],
+  "author": {
+    "name": "RESTForge",
+    "url": "https://restforge.dev"
+  },
+  "license": "MIT"
+}