@ammduncan/easel 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.2.5 — 2026-05-22
+
+### Added
+- **Codex client support: `easel setup --client codex`.** Writes the MCP entry into `~/.codex/config.toml` under `[mcp_servers.easel]` and copies the `using-easel` skill into `~/.codex/skills/using-easel/SKILL.md` so Codex agents have the full style guide in addition to the tool description. Line-based TOML upsert preserves other sections and comments.
+
+### Fixed
+- **`easel setup --help` no longer silently runs the destructive Claude Code setup.** Previously, the `--help` flag fell through the `--client` check and reached `cmdSetup()`, which writes to `~/.claude/settings.json`. Now a dedicated help branch fires before any side effects. Includes a manual-install JSON snippet for clients beyond the four officially supported ones.
+
 ## 0.2.4 — 2026-05-22
 
 ### Fixed

package/dist/cli.js

@@ -23,10 +23,11 @@ Usage:
   easel config preset paper       set preset to paper | aurora | slate
   easel config theme dark         set theme to light | dark
   easel config preset aurora theme light   set both at once
-  easel setup                    install Claude Code hook + register MCP in ~/.claude/settings.json
-  easel setup --client cursor    register the MCP in Cursor's config
-  easel setup --client claude-desktop    register the MCP in Claude Desktop's config
-  easel setup --client windsurf  register the MCP in Windsurf's config
+  easel setup                              install Claude Code hook + register MCP in ~/.claude/settings.json
+  easel setup --client cursor              register MCP in ~/.cursor/mcp.json
+  easel setup --client claude-desktop      register MCP in ~/Library/Application Support/Claude/claude_desktop_config.json
+  easel setup --client windsurf            register MCP in ~/.codeium/windsurf/mcp_config.json
+  easel setup --client codex               register MCP in ~/.codex/config.toml + copy skill to ~/.codex/skills/
   easel update          git pull + npm install + build + setup (re-runs setup to apply new conventions)
   easel mcp             run the stdio MCP server in the foreground (used by clients)
   easel restart         kill the running HTTP server and respawn it (picks up new builds/paths)
@@ -336,6 +337,24 @@ async function main() {
             await cmdUrl();
             return;
         case "setup": {
+            // Catch --help BEFORE doing anything destructive. The default
+            // cmdSetup() writes to ~/.claude/settings.json, so an unguarded
+            // `easel setup --help` would silently reconfigure Claude Code.
+            if (rest.includes("--help") || rest.includes("-h") || rest[0] === "help") {
+                console.log([
+                    "easel setup — install easel into one of the supported MCP clients.",
+                    "",
+                    "Usage:",
+                    "  easel setup                    Claude Code (default): MCP + SessionStart hook + skill",
+                    "  easel setup --client <name>    register MCP in another client",
+                    "",
+                    `Available clients: ${listClients().join(", ")}`,
+                    "",
+                    "Manual install (any other MCP client): drop this into the client's MCP config —",
+                    '  { "mcpServers": { "easel": { "command": "npx", "args": ["-y", "@ammduncan/easel"] } } }',
+                ].join("\n"));
+                return;
+            }
             const clientIdx = rest.indexOf("--client");
             if (clientIdx !== -1) {
                 const name = rest[clientIdx + 1];

package/dist/client-setup.js

@@ -1,36 +1,39 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { homedir, platform } from "node:os";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(__dirname, "..");
 const CLIENTS = {
     "claude-desktop": {
         name: "claude-desktop",
         label: "Claude Desktop",
-        configPath: () => {
-            const home = homedir();
-            if (platform() === "darwin") {
-                return join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
-            }
-            if (platform() === "win32") {
-                const appData = process.env.APPDATA ?? join(home, "AppData", "Roaming");
-                return join(appData, "Claude", "claude_desktop_config.json");
-            }
-            return join(home, ".config", "Claude", "claude_desktop_config.json");
-        },
+        run: () => upsertJsonMcpServer(claudeDesktopConfigPath()),
         postSetup: "Quit and relaunch Claude Desktop to load the MCP server.",
     },
     cursor: {
         name: "cursor",
         label: "Cursor",
-        configPath: () => join(homedir(), ".cursor", "mcp.json"),
+        run: () => upsertJsonMcpServer(join(homedir(), ".cursor", "mcp.json")),
         postSetup: "Open Cursor and toggle MCP servers in Settings → Features → MCP, " +
             "or restart Cursor for the registration to take effect.",
     },
     windsurf: {
         name: "windsurf",
         label: "Windsurf",
-        configPath: () => join(homedir(), ".codeium", "windsurf", "mcp_config.json"),
+        run: () => upsertJsonMcpServer(join(homedir(), ".codeium", "windsurf", "mcp_config.json")),
         postSetup: "Restart Windsurf to load the MCP server.",
     },
+    codex: {
+        name: "codex",
+        label: "Codex",
+        run: () => {
+            upsertTomlMcpServer(join(homedir(), ".codex", "config.toml"));
+            installEaselSkillTo(join(homedir(), ".codex", "skills", "using-easel"));
+        },
+        postSetup: "Restart Codex to load the MCP server. The using-easel skill has " +
+            "been copied to ~/.codex/skills/ so Codex will know when to push.",
+    },
 };
 export function listClients() {
     return Object.keys(CLIENTS);
@@ -40,7 +43,17 @@ export function setupClient(name) {
     if (!spec) {
         throw new Error(`unknown client: ${name}`);
     }
-    const configPath = spec.configPath();
+    spec.run();
+    console.log(`[easel] ${spec.label} configured`);
+    console.log(`  - ${spec.postSetup}`);
+}
+/**
+ * Installs the easel MCP entry into a JSON config file with the standard
+ * `mcpServers: { name: { command, args } }` shape — used by Claude Desktop,
+ * Cursor, Windsurf, and friends. Merges into any existing config; preserves
+ * sibling top-level keys and other registered MCP servers.
+ */
+function upsertJsonMcpServer(configPath) {
     const config = readJson(configPath);
     const mcpServers = config.mcpServers ?? {};
     mcpServers.easel = {
@@ -50,9 +63,74 @@ export function setupClient(name) {
     config.mcpServers = mcpServers;
     mkdirSync(dirname(configPath), { recursive: true });
     writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
-    console.log(`[easel] ${spec.label} configured`);
     console.log(`  - wrote ${configPath}`);
-    console.log(`  - ${spec.postSetup}`);
+}
+/**
+ * Installs the easel MCP entry into a TOML config file under the
+ * `[mcp_servers.easel]` section — used by Codex. Line-based upsert: replaces
+ * the existing `[mcp_servers.easel]` block in place if it's there, otherwise
+ * appends. Other sections and comments preserved.
+ */
+function upsertTomlMcpServer(configPath) {
+    const newSection = "[mcp_servers.easel]\n" +
+        'command = "npx"\n' +
+        'args = ["-y", "@ammduncan/easel"]\n';
+    const existing = existsSync(configPath) ? readFileSync(configPath, "utf-8") : "";
+    const updated = upsertTomlSection(existing, "mcp_servers.easel", newSection);
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, updated);
+    console.log(`  - wrote ${configPath}`);
+}
+/**
+ * Line-based TOML section upsert. Replaces an existing `[<header>]` block
+ * (defined as the lines from the header up to the next top-level `[...]`
+ * header or EOF) with `newBlock`; appends if no such block exists. Other
+ * sections are left untouched. Adequate for our narrow use case — not a
+ * general-purpose TOML editor.
+ */
+function upsertTomlSection(content, header, newBlock) {
+    const targetHeader = `[${header}]`;
+    const lines = content.split("\n");
+    let startIdx = -1;
+    let endIdx = lines.length;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === targetHeader) {
+            startIdx = i;
+            for (let j = i + 1; j < lines.length; j++) {
+                const stripped = lines[j].trim();
+                if (/^\[[^\]]+\]$/.test(stripped)) {
+                    endIdx = j;
+                    break;
+                }
+            }
+            break;
+        }
+    }
+    const newBlockLines = newBlock.replace(/\n+$/, "").split("\n");
+    if (startIdx === -1) {
+        const trailing = content.length === 0 || content.endsWith("\n") ? "" : "\n";
+        const spacer = content.length === 0 ? "" : "\n";
+        return content + trailing + spacer + newBlockLines.join("\n") + "\n";
+    }
+    const before = lines.slice(0, startIdx);
+    const after = lines.slice(endIdx);
+    const trailingBlank = after.length > 0 && after[0] !== "" ? [""] : [];
+    return [...before, ...newBlockLines, ...trailingBlank, ...after].join("\n");
+}
+/**
+ * Copies the bundled `using-easel/SKILL.md` into a target skills directory.
+ * Used by clients that have a skill-discovery mechanism (Claude Code,
+ * Codex).
+ */
+export function installEaselSkillTo(destDir) {
+    const src = resolve(PROJECT_ROOT, "skills", "using-easel", "SKILL.md");
+    if (!existsSync(src)) {
+        console.warn(`  - skipped skill install: source missing at ${src}`);
+        return;
+    }
+    mkdirSync(destDir, { recursive: true });
+    copyFileSync(src, join(destDir, "SKILL.md"));
+    console.log(`  - installed using-easel skill into ${destDir}`);
 }
 function readJson(path) {
     if (!existsSync(path))
@@ -71,3 +149,14 @@ function readJson(path) {
         throw new Error(`couldn't parse existing config at ${path}: ${err.message}`);
     }
 }
+function claudeDesktopConfigPath() {
+    const home = homedir();
+    if (platform() === "darwin") {
+        return join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    if (platform() === "win32") {
+        const appData = process.env.APPDATA ?? join(home, "AppData", "Roaming");
+        return join(appData, "Claude", "claude_desktop_config.json");
+    }
+    return join(home, ".config", "Claude", "claude_desktop_config.json");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ammduncan/easel",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "A live browser tab for every Claude Code (and MCP) session. The push MCP tool appends HTML cards to a scrolling feed you keep open in split-screen.",
   "type": "module",
   "license": "MIT",