@ammduncan/easel 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.2.6 — 2026-05-22
+
+### Fixed
+- **Locked-mode containers (terminal mockups, code blocks, brand-color heros) had invisible text in light mode** when pushed from non-Claude-Code clients. The push tool description's "inverse rule" was stated in prose but had no copy-paste code example — and the wrap/card example used `light-dark()` while the agent then applied the same pattern to a locked-dark terminal, leaving its inner text on `color: inherit` (which resolved to the wrap's dark text in light mode → dark text on dark bg).
+- Added a second copy-paste starter block specifically for locked-mode containers, showing the canonical pattern (`background: #0f172a; color: #e6edf3;` + re-scoping `color: inherit` to children). Right next to the adaptive wrap/card pattern so the agent can't miss the difference.
+
+## 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/dist/mcp.js

@@ -91,11 +91,17 @@ export async function main() {
                     "• Use `light-dark()` for ALL text colors, card backgrounds, borders, and decorative shades. Add `:root { color-scheme: light dark; }` so the function resolves. Hardcoded `color: #475569` goes invisible in dark mode; hardcoded `border: 1px solid #e5e5e5` becomes a hard white line.\n" +
                     "• After setting `.wrap { color: light-dark(...); }`, re-scope `color: inherit` to every descendant so child elements don't fall back to the host's default.\n" +
                     "• Inverse rule: if you DO paint a fixed background on a container (a code block locked to dark, a brand-color hero), you MUST also set its text color AND re-scope `color: inherit` to its children. Background and text are a pair.\n\n" +
-                    "═══ COPY-PASTE STARTER ═══\n" +
+                    "═══ COPY-PASTE STARTER (adaptive) ═══\n" +
                     "  :root { color-scheme: light dark; }\n" +
                     "  .wrap { color: light-dark(#111, #e8e8e8); padding: 56px 48px; font-family: -apple-system, 'Inter', system-ui, sans-serif; max-width: 820px; }\n" +
                     "  .wrap *, .wrap h1, .wrap h2, .wrap h3, .wrap p, .wrap li, .wrap span { color: inherit; }\n" +
                     "  .card { background: light-dark(#fff, #161616); border: 1px solid light-dark(#e0d9c3, #2a2a2a); border-radius: 12px; padding: 24px; }\n\n" +
+                    "═══ COPY-PASTE STARTER (LOCKED-MODE container — terminal, code block, brand hero) ═══\n" +
+                    "If a container has a FIXED background (not `light-dark()`), you MUST set its own text color AND re-scope `color: inherit` to its children. Otherwise the children inherit `light-dark(...)` from `.wrap` and the text flips to the wrong shade in one mode (e.g. dark text on a locked-dark terminal in light host mode → invisible). This is the #1 thing that goes wrong on terminals and code blocks.\n" +
+                    "  .terminal { background: #0f172a; color: #e6edf3; border-radius: 12px; padding: 20px 24px; font-family: ui-monospace, 'SF Mono', Menlo, monospace; font-size: 13.5px; line-height: 1.7; }\n" +
+                    "  .terminal *, .terminal span, .terminal pre { color: inherit; }\n" +
+                    "  .terminal .muted { color: #94a3b8; }\n" +
+                    "  .terminal .accent { color: #6ee7b7; }\n\n" +
                     "═══ TYPOGRAPHY (presentation scale, NOT dashboard) ═══\n" +
                     "• Hero title: 44–52px, weight 500, letter-spacing -0.025em\n" +
                     "• Section titles: 28–36px, weight 500\n" +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ammduncan/easel",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "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",