create-restforge-skills 0.4.0 → 1.0.0

package/README.md

@@ -28,18 +28,20 @@ restforge-skills/
 ├── *.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
+│   ├── 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
 ```
 
 ## 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:
 
@@ -58,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.
 
@@ -68,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
@@ -85,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
@@ -118,7 +124,9 @@ so the update touches only the skill and leaves the MCP config alone.
 | 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
@@ -127,14 +135,53 @@ it — not into `./.claude/`.
 ### 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.
+### 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
 

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,12 +1,13 @@
 {
   "name": "create-restforge-skills",
-  "version": "0.4.0",
-  "description": "Install the RESTForge Agent Skill into Claude Code, Cursor, and other skills-compatible clients.",
+  "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": [
@@ -23,11 +24,15 @@
     "skill",
     "claude-code",
     "cursor",
+    "codex",
     "mcp"
   ],
   "author": {
     "name": "RESTForge",
     "url": "https://restforge.dev"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "@iarna/toml": "2.2.5"
+  }
 }

package/skills/restforge/SKILL.md

@@ -56,8 +56,10 @@ The platform exposes its capabilities as MCP tools grouped by domain: `health_*`
 
 Verify readiness before planning or producing anything:
 
-1. **Are the RESTForge MCP tools present?** If `codegen_*` / `designer_*` are not
-   in your available tools, the MCP server is **not active**. Stop and tell the
+1. **Are the RESTForge MCP tools present?** Look for `codegen_*` / `designer_*`,
+   including client-prefixed names such as `mcp__restforge__codegen_*`. If the
+   client supports deferred tool discovery, search for RESTForge tools first.
+   If they remain unavailable, the MCP server is **not active**. Stop and tell the
    user to register the RESTForge MCP server and restart the client. Do **not**
    finish the task by hand-reading the bundled `references/` — that bypasses the
    generator and yields slower, non-deterministic output.

package/skills/restforge/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "RESTForge"
+  short_description: "Build RESTForge APIs and frontends through MCP"
+  default_prompt: "Use $restforge to build or update my RESTForge application."