create-restforge-skills 0.3.0 → 1.0.0

package/README.md

@@ -7,58 +7,41 @@ 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.
+This package is the **only** 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`.
+  `marketplace.json`, or `.mcp.json`. The installer (`create-restforge-skills`)
+  copies the skill into each client and registers the MCP server there.
 
-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.
+The skill depends on one 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
+├── README.md                 ← this file (end-user guide, published to npm)
 ├── package.json              ← npm package: create-restforge-skills
-├── bump-and-publish.bat      ← version bump + npm publish
-├── sync-to-plugin.bat        ← mirror the skill into the Claude Code plugin
+├── *.bat                     ← maintainer scripts (see docs/DEVELOPMENT.md)
 ├── cli/
 │   ├── index.js              ← installer that copies the skill into each client
-│   └── mcp.js                ← merges the MCP server into each client config
-├── docs/                     ← internal docs, NOT published (excluded from npm files)
+│   ├── mcp.js                ← merges JSON MCP config for Claude Code / Cursor
+│   └── codex.js              ← safely appends Codex TOML MCP configuration
+├── docs/
+│   └── DEVELOPMENT.md        ← maintainer guide, NOT published (excluded from npm files)
 └── skills/
     └── restforge/
-        ├── SKILL.md          ← the portable skill (name + description + workflow)
+        ├── SKILL.md          ← the portable skill (name + description + workflow)
+        ├── agents/openai.yaml ← Codex display metadata and example prompt
         └── references/       ← progressive-disclosure reference material
 ```
 
-## Single source of truth
-
-`skills/restforge/` here is the **one** authoritative copy of the skill. Two
-distribution channels consume it — do not edit the skill anywhere else:
-
-- **This package** (`create-restforge-skills`) — published to npm; cross-client.
-- **The Claude Code plugin** (`../packages/restforge-plugins`) — its
-  `skills/restforge-skills/` folder is a **generated mirror**. After editing the
-  canonical skill, run `sync-to-plugin.bat` to propagate, then commit the plugin
-  repo. Hand-edits to the plugin's skill copy are overwritten on the next sync.
-
 ## Install
 
-One command. It detects your installed clients (Claude Code, Cursor), copies the
+One command. It detects your installed clients (Claude Code, Cursor, Codex), copies the
 skill into each, and registers the RESTForge MCP server — because the skill is
 inert without it:
 
@@ -77,7 +60,8 @@ 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/`)
+  ignored. The skill goes to your home (`~/.claude/skills/`, `~/.cursor/skills/`,
+  or `~/.agents/skills/` for Codex)
   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.
 
@@ -87,7 +71,9 @@ is chosen by `--scope`, not by where you stand or by a path you pass.
   `./.claude/skills/` or `./.cursor/skills/`; the MCP config goes to `./.mcp.json`
   for Claude Code (its project-scope convention, not a file under `.claude/`) and
   to `./.cursor/mcp.json` for Cursor. Use this to commit the skill with a specific
-  repo so the team gets it on clone.
+  repo so the team gets it on clone.
+  For Codex, the corresponding paths are `./.agents/skills/` and
+  `./.codex/config.toml`; project MCP settings load only in trusted projects.
 
 ```bash
 # normal — anywhere, global for every project
@@ -104,8 +90,9 @@ Note: a bare path such as `npx create-restforge-skills .` is **not** recognized
 ### Options
 
 ```bash
-npx create-restforge-skills --client=cursor      # one client only
-npx create-restforge-skills --scope=project      # skill into ./.claude or ./.cursor, MCP into ./.mcp.json (commit for the team)
+npx create-restforge-skills --client=cursor      # one client only
+npx create-restforge-skills --client=codex       # Codex skill + MCP configuration
+npx create-restforge-skills --scope=project      # install into the current project
 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
@@ -117,6 +104,19 @@ 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.
 
+### Update
+
+`npx` caches previously downloaded packages, so when updating always pin
+`@latest` and pass `--force` to overwrite the installed skill folder:
+
+```bash
+npx create-restforge-skills@latest --force
+```
+
+If the machine already has the RESTForge MCP server registered the way you want
+it (for example via a globally installed `restforge-mcp` binary), add `--no-mcp`
+so the update touches only the skill and leaves the MCP config alone.
+
 ### Where it installs
 
 | Client | Scope | Skill | MCP config |
@@ -124,34 +124,71 @@ directory.
 | Claude Code | user (default) | `~/.claude/skills/restforge/` | `~/.claude.json` |
 | Claude Code | project | `./.claude/skills/restforge/` | `./.mcp.json` |
 | Cursor | user (default) | `~/.cursor/skills/restforge/` | `~/.cursor/mcp.json` |
-| Cursor | project | `./.cursor/skills/restforge/` | `./.cursor/mcp.json` |
+| Cursor | project | `./.cursor/skills/restforge/` | `./.cursor/mcp.json` |
+| Codex | user (default) | `~/.agents/skills/restforge/` | `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) |
+| Codex | project | `./.agents/skills/restforge/` | `./.codex/config.toml` |
 
 Note the asymmetry on the project row: Claude Code reads a project-scope MCP
 server from `./.mcp.json` in the repo root, so that is where the installer writes
 it — not into `./.claude/`.
 
-> 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
+`references/` and `agents/`) into the client's skills directory. For Claude Code
+and Cursor, 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.
+### OpenAI Codex
+
+Install for Codex explicitly, or let auto-detection find `CODEX_HOME` (default
+`~/.codex`). No Codex CLI binary is required by the installer:
+
+```bash
+npx create-restforge-skills --client=codex
+# Or install into the current project:
+npx create-restforge-skills --client=codex --scope=project
+```
+
+Restart Codex after installation and invoke `$restforge`, for example:
+`Use $restforge to create a product API.` Check the MCP connection with `/mcp`
+in Codex or `codex mcp list` in a terminal.
+
+For manual setup, copy the entire skill folder to the Codex skill path in the
+table above and add this to the corresponding `config.toml`:
+
+```toml
+[mcp_servers.restforge]
+command = "npx"
+args = ["-y", "@restforgejs/mcp-server"]
+```
+
+The installer preserves existing Codex RESTForge registrations, including custom
+commands, URLs, environment variables and timeouts. `--mcp-command` chooses the
+command for a **new** registration; edit `config.toml` to change an existing one.
+`--force` only replaces the skill. Existing TOML comments and formatting are
+preserved, and a changed config is backed up to `config.toml.bak`. If the TOML
+cannot be parsed or extended safely (for example an inline `mcp_servers` table),
+the installer leaves it untouched, reports an error, and exits with code 1;
+the skill may already have been copied. Finish the MCP setup manually.
+
+`CODEX_HOME` changes the user MCP config location and auto-detection marker;
+user skills still go into `~/.agents/skills/`. See the official
+[skill discovery documentation](https://developers.openai.com/codex/skills) and
+[MCP configuration documentation](https://developers.openai.com/codex/mcp).
+
+### Gemini CLI
+
+Installer support is planned. Use the same `skills/restforge/` folder with the
+client's manual skill installation procedure.
+
+## Developing and releasing
+
+Maintainer topics live in [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md): the
+skill source, testing the skill from the working tree, the reference audit, the
+release flow, and the extra care needed on machines that double as RESTForge
+development machines. That guide is not published to npm.
 
 ## License
 

package/cli/codex.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const toml = require('@iarna/toml');
+
+function formatCodexMcp(entry) {
+  return toml.stringify({ mcp_servers: { restforge: entry } });
+}
+
+// Append only, preserving comments, formatting, and any existing custom server.
+// Parse both documents so inline tables, quoted keys and multiline strings are
+// handled by a TOML parser rather than potentially destructive text matching.
+function registerCodexMcp(file, entry, opts) {
+  try {
+    const existed = fs.existsSync(file);
+    const raw = existed ? fs.readFileSync(file, 'utf8') : '';
+    const config = toml.parse(raw);
+    if (config.mcp_servers && Object.hasOwn(config.mcp_servers, 'restforge')) {
+      const existing = config.mcp_servers.restforge;
+      const same = existing.command === entry.command &&
+        JSON.stringify(existing.args || []) === JSON.stringify(entry.args || []);
+      return { status: same ? 'already-registered' : 'preserved' };
+    }
+    const next = raw + (raw.endsWith('\n') || !raw ? '' : '\n') + '\n' + formatCodexMcp(entry);
+    toml.parse(next);
+    if (opts.dryRun) return { status: 'would-register' };
+    let backup;
+    if (existed) {
+      backup = file + '.bak';
+      fs.copyFileSync(file, backup);
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, next, 'utf8');
+    return { status: 'registered', backup };
+  } catch (err) {
+    // Parser diagnostics can contain config values (including credentials).
+    return { status: 'error', error: `Cannot safely register Codex MCP (${err.code || 'invalid or conflicting TOML'}); check config.toml manually.` };
+  }
+}
+
+module.exports = { formatCodexMcp, registerCodexMcp };

package/cli/index.js

@@ -14,14 +14,15 @@
  *
  * 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).
+ * 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.
@@ -33,6 +34,12 @@ const SOURCE_DIR = path.join(__dirname, '..', 'skills', SKILL_NAME);
  * 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'),
@@ -106,9 +113,9 @@ 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.
+  --client=<list>      Comma-separated clients: claude,cursor,codex. Default: auto-detect.
   --scope=<scope>      user (default) installs globally for you; project installs
-                       into ./.claude or ./.cursor in the current directory.
+                       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
@@ -193,8 +200,8 @@ function main() {
 
   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');
+    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);
   }
 
@@ -212,13 +219,17 @@ function main() {
     console.log(`  ${pad('')} → skill: ${skill.status}${skill.reason ? ` (${skill.reason})` : ''}`);
 
     if (opts.mcp) {
-      const mcp = registerMcp(target.mcpConfig, mcpEntry, opts);
+      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') {
-        console.log(`  ${pad('')}          add manually: "mcpServers": { "restforge": ${JSON.stringify(mcpEntry)} }`);
+        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.');
     }
   }
 
@@ -229,6 +240,10 @@ function main() {
     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('');
 }
 

package/package.json

@@ -1,30 +1,38 @@
-{
-  "name": "create-restforge-skills",
-  "version": "0.3.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"
-}
+{
+  "name": "create-restforge-skills",
+  "version": "1.0.0",
+  "description": "Install the RESTForge Agent Skill and MCP server configuration into Claude Code, Cursor, and OpenAI Codex.",
+  "type": "commonjs",
+  "bin": {
+    "create-restforge-skills": "cli/index.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "audit-references": "node scripts/audit-references.js"
+  },
+  "files": [
+    "cli",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "restforge",
+    "agent-skills",
+    "skill",
+    "claude-code",
+    "cursor",
+    "codex",
+    "mcp"
+  ],
+  "author": {
+    "name": "RESTForge",
+    "url": "https://restforge.dev"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@iarna/toml": "2.2.5"
+  }
+}