create-restforge-skills 0.4.0 → 1.0.1

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 };