@cg3/equip 0.2.18 → 0.2.20

package/README.md

@@ -4,6 +4,19 @@ Universal MCP server + behavioral rules installer for AI coding agents.
 
 Equip handles the hard part of distributing your MCP tool: detecting which AI coding platforms are installed, writing the correct config format for each one, and managing versioned behavioral rules — all with zero dependencies.
 
+## Run the Demo
+
+```bash
+npx @cg3/equip demo
+```
+
+A self-contained, inline-documented setup script that walks through every equip feature — platform detection, MCP config, behavioral rules, and uninstallation. Runs in dry-run mode by default (no files touched). See [`demo/setup.js`](./demo/setup.js) for the full source.
+
+```bash
+npx @cg3/equip demo --live        # actually write config files
+npx @cg3/equip demo --uninstall   # clean up demo files
+```
+
 ## Supported Platforms
 
 Equip supports **11 platforms** across two tiers, depending on whether the platform has a writable location for behavioral rules.
@@ -158,17 +171,21 @@ const { detectPlatforms, installMcpJson, installRules, createManualPlatform, pla
 - **Dry-run support** — Preview changes without writing files
 - **CLI helpers** — Colored output, prompts, clipboard utilities included
 
-## Limitations — Why Rules Matter (and Why They're Not Enough)
+## How the Layers Work Together
+
+Equip distributes your MCP tool through three complementary layers, each stronger than the last:
 
-MCP tool descriptions alone don't reliably trigger agent behavior. [Research on 856 MCP tools](https://arxiv.org/abs/2602.14878) found that 97.1% of tool descriptions contain quality issues, and even fully optimized descriptions only improve task success by ~6 percentage points.
+1. **MCP config** — Makes the tool available. The agent *can* call it.
+2. **Behavioral rules** — Teaches the agent *when* to call it. Rules live in the agent's system prompt or project context, close to where decisions happen.
+3. **Lifecycle hooks** — Structurally enforces behavior at key moments (e.g., after an error, on task completion). Hooks inject context into the agent's reasoning at exactly the right time, without relying on the agent remembering its rules.
 
-Behavioral rules (the `.md` files equip installs) are stronger — they live in the agent's system prompt or project context, closer to how agents make decisions. But they have limits too:
+Each layer compensates for the limitations of the one before it:
 
-- **Context window compaction** can drop rules from the agent's working memory during long sessions
-- **No platform hooks exist** to enforce tool calls — the agent always decides whether to act
-- **No open standard** for server-initiated actions (MCP sampling exists in spec but isn't widely implemented)
+- **Tool descriptions alone** don't reliably trigger behavior. [Research on 856 MCP tools](https://arxiv.org/abs/2602.14878) found that even fully optimized descriptions only improve task success by ~6 percentage points.
+- **Behavioral rules** are stronger, but can be dropped during context window compaction in long sessions, and the agent can still rationalize skipping them.
+- **Lifecycle hooks** are the strongest available enforcement — they fire automatically at the platform level, independent of the agent's memory or reasoning. Not all platforms support hooks yet, but equip installs them where available and silently skips where not.
 
-Equip gives you the best available distribution: MCP config for tool availability + behavioral rules for usage guidance + lifecycle hooks for structural enforcement on platforms that support them. Hooks bridge the gap between "the agent knows the rules" and "the agent actually follows them" by injecting reminders at the exact moment an error occurs.
+No layer is a silver bullet. Together, they give you the best coverage available today across the broadest set of platforms.
 
 ## License
 

package/bin/equip.js

@@ -16,6 +16,7 @@ const EQUIP_VERSION = JSON.parse(
 
 const TOOLS = {
   prior: { package: "@cg3/prior-node", command: "setup" },
+  demo: { builtin: true },
 };
 
 // ─── CLI ─────────────────────────────────────────────────────
@@ -28,7 +29,11 @@ if (!alias || alias === "--help" || alias === "-h") {
   console.log("");
   console.log("Available tools:");
   for (const [name, info] of Object.entries(TOOLS)) {
-    console.log(`  ${name}  →  ${info.package} ${info.command}`);
+    if (info.builtin) {
+      console.log(`  ${name}  →  built-in (reference example)`);
+    } else {
+      console.log(`  ${name}  →  ${info.package} ${info.command}`);
+    }
   }
   console.log("");
   console.log("Options are forwarded to the tool (e.g. --dry-run, --platform codex)");
@@ -37,6 +42,23 @@ if (!alias || alias === "--help" || alias === "-h") {
 
 const entry = TOOLS[alias];
 
+// Built-in tools run from this package directly
+if (entry && entry.builtin) {
+  if (alias === "demo") {
+    const demoPath = path.join(__dirname, "..", "demo", "setup.js");
+    const child = spawn(process.execPath, [demoPath, ...extraArgs], {
+      stdio: "inherit",
+      env: { ...process.env, EQUIP_VERSION },
+    });
+    child.on("close", (code) => process.exit(code || 0));
+    child.on("error", (err) => {
+      console.error(`Failed to run demo: ${err.message}`);
+      process.exit(1);
+    });
+    return;
+  }
+}
+
 // No registry match — treat as a package name (e.g. "@scope/pkg setup")
 if (!entry) {
   const pkg = alias;

package/demo/README.md

@@ -0,0 +1,64 @@
+# @cg3/equip Demo
+
+A minimal, working setup script that shows how to build your own MCP tool installer on top of `@cg3/equip`.
+
+## Run it
+
+```bash
+npx @cg3/equip demo                        # dry-run (default — safe to explore)
+npx @cg3/equip demo --live                  # actually write config files
+npx @cg3/equip demo --uninstall             # clean up demo files
+npx @cg3/equip demo --platform claude-code  # target a specific platform
+```
+
+The demo runs in **dry-run mode by default** — it shows exactly what would happen without touching any files. Use `--live` to write real config, and `--uninstall` to clean up afterward.
+
+## What it does
+
+The demo installs a fictional MCP tool called `my-tool` across all detected AI coding platforms. It walks through the core equip operations:
+
+1. **Detect** — scan for installed AI tools (Claude Code, Cursor, VS Code, etc.)
+2. **API key** — prompt for or configure authentication
+3. **MCP config** — write server config to each platform's config file
+4. **Behavioral rules** — inject versioned instructions into agent rule files
+5. **Uninstall** — cleanly remove everything the install wrote
+
+Every step is documented inline in [`setup.js`](./setup.js).
+
+## Use as a template
+
+Copy `setup.js` into your own project and replace:
+
+- `TOOL_NAME` — your MCP server name
+- `SERVER_URL` — your MCP endpoint
+- `RULES_CONTENT` — behavioral instructions for agents
+- API key prompt — real authentication flow
+- Remove the dry-run default (real tools should install by default)
+
+Then wire it up in your `package.json`:
+
+```json
+{
+  "bin": { "setup": "./setup.js" }
+}
+```
+
+And register it in equip's tool registry (or run directly with `npx your-package setup`).
+
+## API surface
+
+The demo uses these equip APIs:
+
+| API | Purpose |
+|-----|---------|
+| `new Equip(config)` | Create installer instance |
+| `equip.detect()` | Find installed platforms |
+| `equip.installMcp(platform, apiKey)` | Write MCP config |
+| `equip.installRules(platform)` | Install behavioral rules |
+| `equip.uninstallMcp(platform)` | Remove MCP config |
+| `equip.uninstallRules(platform)` | Remove behavioral rules |
+| `createManualPlatform(id)` | Force a specific platform |
+| `platformName(id)` | Human-readable platform name |
+| `cli.*` | Output helpers (colors, prompts, clipboard) |
+
+See the [main README](../README.md) for the full API reference.

package/demo/setup.js

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+// ─────────────────────────────────────────────────────────────
+// @cg3/equip Demo — Minimal setup script for a fictional MCP tool.
+//
+// This file is a working reference for building your own setup
+// script on top of @cg3/equip. Run it with:
+//
+//   npx @cg3/equip demo                    # dry-run by default (safe)
+//   npx @cg3/equip demo --live             # actually write files
+//   npx @cg3/equip demo --uninstall        # remove demo config
+//   npx @cg3/equip demo --platform codex   # target a specific platform
+//
+// It demonstrates:
+//   1. Platform detection (which AI tools are installed?)
+//   2. MCP server configuration (HTTP or stdio transport)
+//   3. Behavioral rules installation (versioned, marker-based)
+//   4. Lifecycle hooks (optional, platform-dependent)
+//   5. Uninstallation (clean removal of everything it installed)
+//   6. CLI output helpers (colors, prompts, clipboard)
+//
+// Everything is inline-documented. Copy this file as a starting
+// point for your own tool's setup script.
+// ─────────────────────────────────────────────────────────────
+
+"use strict";
+
+// ─── 1. Import equip ────────────────────────────────────────
+//
+// The Equip class is the high-level API. It wraps detection,
+// config building, installation, and uninstallation into a
+// single object. You can also import individual primitives
+// (detectPlatforms, installMcp, etc.) for lower-level control.
+
+const { Equip, createManualPlatform, platformName, cli } = require("@cg3/equip");
+
+// ─── 2. Parse CLI flags ─────────────────────────────────────
+//
+// Keep it simple — equip doesn't ship an arg parser on purpose.
+// Your setup script owns its own CLI interface.
+
+const args = process.argv.slice(2);
+const uninstall = args.includes("--uninstall");
+const liveMode = args.includes("--live");
+const dryRun = !liveMode && !uninstall;  // Demo defaults to dry-run for safety
+const platformOverride = args.includes("--platform")
+  ? args[args.indexOf("--platform") + 1]
+  : null;
+
+// ─── 3. Define your tool ────────────────────────────────────
+//
+// This is the core configuration. Replace these values with
+// your actual MCP server details.
+
+const TOOL_NAME = "my-tool";        // Name in MCP config files
+const SERVER_URL = "https://api.example.com/mcp";  // Your MCP endpoint
+const RULES_VERSION = "0.1.0";      // Bump when rules content changes
+
+// Behavioral rules use HTML comment markers for versioned,
+// non-destructive updates. The marker lets equip find and
+// replace your block without touching the rest of the file.
+//
+// Format:
+//   <!-- marker:vX.Y.Z -->
+//   ... your rules content ...
+//   <!-- /marker -->
+
+const RULES_CONTENT = `<!-- ${TOOL_NAME}:v${RULES_VERSION} -->
+## My Tool — Agent Instructions
+
+When you encounter an error you haven't seen before:
+1. Search my-tool for existing solutions before debugging from scratch
+2. If you find a match, try it and give feedback (useful/not_useful/irrelevant)
+3. If you solve something novel, contribute the solution
+
+Keep searches focused on the error message, not the goal.
+<!-- /${TOOL_NAME} -->`;
+
+// ─── 4. Create the Equip instance ───────────────────────────
+//
+// The constructor validates config and stores it. No side
+// effects — detection and installation happen in separate calls.
+
+const equip = new Equip({
+  name: TOOL_NAME,
+  serverUrl: SERVER_URL,
+
+  // Rules are optional. Omit this block if your tool doesn't
+  // need behavioral instructions injected into agent configs.
+  rules: {
+    content: RULES_CONTENT,
+    version: RULES_VERSION,
+    marker: TOOL_NAME,
+    // fileName: "my-tool.md",       // Use for platforms with rules directories
+    // clipboardPlatforms: ["cursor", "vscode"],  // These get clipboard instead
+  },
+
+  // Stdio transport (alternative to HTTP). Uncomment to use:
+  // stdio: {
+  //   command: "npx",
+  //   args: ["-y", "@example/my-tool-mcp@latest"],
+  //   envKey: "MY_TOOL_API_KEY",    // Env var name for the API key
+  // },
+
+  // Hooks are optional. They run code at specific lifecycle
+  // events in supported platforms (currently Claude Code only).
+  // hooks: [
+  //   {
+  //     event: "PostToolUseFailure",
+  //     matcher: "Bash",
+  //     name: "search-on-error",
+  //     script: `
+  //       // This runs after a Bash tool call fails.
+  //       // Hook scripts receive context via stdin (JSON).
+  //       const input = require("fs").readFileSync("/dev/stdin", "utf-8");
+  //       const { tool_input, tool_output } = JSON.parse(input);
+  //       console.log("Consider searching my-tool for:", tool_output?.stderr);
+  //     `,
+  //   },
+  // ],
+});
+
+// ─── 5. Detect platforms (shared by install and uninstall) ───
+
+function detectTargetPlatforms() {
+  if (platformOverride) {
+    const p = createManualPlatform(platformOverride);
+    cli.info(`Forced platform: ${platformName(platformOverride)}`);
+    return [p];
+  }
+
+  const platforms = equip.detect();
+  if (platforms.length === 0) {
+    cli.fail("No AI coding tools detected. Install one of:");
+    cli.log("  Claude Code, Cursor, VS Code, Windsurf, Codex, Gemini CLI");
+    cli.log("  Or use --platform <id> to specify manually.\n");
+    process.exit(1);
+  }
+  return platforms;
+}
+
+// ─── 6. Uninstall flow ──────────────────────────────────────
+//
+// equip provides uninstallMcp() and uninstallRules() that
+// cleanly remove everything the install wrote:
+//   - MCP config: removes the server entry (restores .bak if available)
+//   - Rules: removes the marker block, preserving other content
+//   - Hooks: removes scripts and settings entries
+//
+// This is important for demos — and equally important for real
+// tools that want a clean "uninstall" command.
+
+async function runUninstall() {
+  cli.log(`\n${cli.BOLD}@cg3/equip demo — uninstall${cli.RESET}\n`);
+
+  cli.step(1, 3, "Detecting platforms");
+  const platforms = detectTargetPlatforms();
+
+  for (const p of platforms) {
+    cli.ok(platformName(p.platform));
+  }
+
+  // ── Remove MCP config ────────────────────────────────────
+  cli.step(2, 3, "Removing MCP config");
+
+  for (const p of platforms) {
+    const removed = equip.uninstallMcp(p);
+    if (removed) {
+      cli.ok(`${platformName(p.platform)} → removed`);
+    } else {
+      cli.info(`${platformName(p.platform)} → not configured (nothing to remove)`);
+    }
+  }
+
+  // ── Remove behavioral rules ──────────────────────────────
+  cli.step(3, 3, "Removing behavioral rules");
+
+  for (const p of platforms) {
+    const removed = equip.uninstallRules(p);
+    if (removed) {
+      cli.ok(`${platformName(p.platform)} → rules removed`);
+    } else {
+      cli.info(`${platformName(p.platform)} → no rules found`);
+    }
+  }
+
+  cli.log(`\n${cli.GREEN}${cli.BOLD}✓ Uninstall complete${cli.RESET}`);
+  cli.log(`  Demo config for "${TOOL_NAME}" has been cleaned up.\n`);
+}
+
+// ─── 7. Install flow ────────────────────────────────────────
+
+async function runInstall() {
+  cli.log(`\n${cli.BOLD}@cg3/equip demo — setup walkthrough${cli.RESET}\n`);
+
+  if (dryRun) {
+    cli.warn("Dry run mode (default for demo) — no files will be modified");
+    cli.info(`Use ${cli.BOLD}--live${cli.RESET} to actually write files\n`);
+  }
+
+  // ── Step 1: Detect platforms ──────────────────────────────
+  //
+  // detectPlatforms() scans the system for installed AI coding
+  // tools: Claude Code, Cursor, VS Code, Windsurf, Codex, etc.
+  //
+  // Each result includes:
+  //   - platform: id string ("claude-code", "cursor", etc.)
+  //   - configPath: where MCP config lives
+  //   - rulesPath: where behavioral rules go (or null)
+  //   - existingMcp: current config for this server name (or null)
+  //   - rootKey: JSON key for MCP servers ("mcpServers", "servers", etc.)
+  //   - configFormat: "json" or "toml"
+  //
+  // You can also force a specific platform with createManualPlatform().
+
+  cli.step(1, 4, "Detecting platforms");
+
+  const platforms = detectTargetPlatforms();
+
+  for (const p of platforms) {
+    const status = p.existingMcp ? `${cli.YELLOW}configured${cli.RESET}` : `${cli.DIM}not configured${cli.RESET}`;
+    cli.ok(`${platformName(p.platform)} [${status}]`);
+  }
+
+  // ── Step 2: Get API key ───────────────────────────────────
+  //
+  // In a real setup script, you'd prompt for or generate an
+  // API key here. For the demo, we use a placeholder.
+
+  cli.step(2, 4, "API key");
+
+  // Real example:
+  // const apiKey = await cli.prompt("  Enter your API key: ");
+  // if (!apiKey) { cli.fail("API key required"); process.exit(1); }
+
+  const apiKey = "demo_key_xxx";  // Placeholder for demo
+  cli.info(`Using demo API key (${apiKey.slice(0, 8)}...)`);
+
+  // ── Step 3: Install MCP config ────────────────────────────
+  //
+  // installMcp() handles all platform differences:
+  //   - JSON vs TOML config formats
+  //   - Different root keys (mcpServers vs servers vs mcp_servers)
+  //   - CLI-first installation (claude mcp add, cursor --add-mcp)
+  //   - Fallback to direct file write with backup
+  //   - Windows path handling (cmd /c wrapper for stdio)
+
+  cli.step(3, 4, "Installing MCP config");
+
+  for (const p of platforms) {
+    const result = equip.installMcp(p, apiKey, { dryRun });
+    if (result.success) {
+      cli.ok(`${platformName(p.platform)} → ${result.method}`);
+    } else {
+      cli.fail(`${platformName(p.platform)}`);
+    }
+  }
+
+  // ── Step 4: Install behavioral rules ──────────────────────
+  //
+  // Rules are versioned markdown blocks injected into each
+  // platform's rules file (CLAUDE.md, GEMINI.md, etc.).
+  //
+  // The marker system means:
+  //   - First install: appends the block
+  //   - Version bump: replaces the old block in-place
+  //   - Same version: skips (idempotent)
+  //   - Uninstall: removes the block cleanly
+  //
+  // Platforms without a rules file (Cursor, VS Code) get the
+  // content copied to clipboard instead.
+
+  cli.step(4, 4, "Installing behavioral rules");
+
+  for (const p of platforms) {
+    const result = equip.installRules(p, { dryRun });
+    switch (result.action) {
+      case "created":
+        cli.ok(`${platformName(p.platform)} → rules installed`);
+        break;
+      case "updated":
+        cli.ok(`${platformName(p.platform)} → rules updated`);
+        break;
+      case "skipped":
+        cli.info(`${platformName(p.platform)} → already current`);
+        break;
+      case "clipboard":
+        cli.info(`${platformName(p.platform)} → copied to clipboard (paste into settings)`);
+        break;
+    }
+  }
+
+  // ── Done ──────────────────────────────────────────────────
+
+  cli.log(`\n${cli.GREEN}${cli.BOLD}✓ Setup complete${cli.RESET}`);
+  if (dryRun) {
+    cli.warn("(dry run — nothing was actually written)\n");
+  } else {
+    // When files were actually written, remind user how to clean up
+    cli.log(`  MCP server "${TOOL_NAME}" is now configured on ${platforms.length} platform(s).`);
+    cli.log("");
+    cli.warn(`This was a demo — run ${cli.BOLD}npx @cg3/equip demo --uninstall${cli.RESET} to remove demo files\n`);
+  }
+}
+
+// ─── 8. Entry point ─────────────────────────────────────────
+//
+// Route to install or uninstall based on flags.
+// Wrap in error handler for clean output.
+
+const run = uninstall ? runUninstall : runInstall;
+
+run().catch((err) => {
+  cli.fail(cli.sanitizeError(err.message));
+  if (process.env.DEBUG) console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cg3/equip",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "Universal MCP + behavioral rules installer for AI coding agents",
   "main": "index.js",
   "bin": {
@@ -18,7 +18,8 @@
   "files": [
     "index.js",
     "bin/",
-    "lib/"
+    "lib/",
+    "demo/"
   ],
   "keywords": [
     "mcp",