@cg3/equip 0.2.19 → 0.2.21

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.

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,324 @@
+#!/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 = "acme-docs";       // 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} -->
+## Acme Docs — Agent Instructions
+
+When working with Acme APIs or libraries:
+1. Use the acme-docs tool to look up current API signatures before guessing
+2. Check for deprecation notices — Acme ships breaking changes quarterly
+3. Prefer the code examples from acme-docs over generic web search results
+
+The tool returns versioned docs matching your project's dependency version.
+<!-- /${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":
+        // "skipped" can mean two things:
+        //   1. Rules already at this version (rulesPath exists, marker version matches)
+        //   2. Platform has no writable rules path (rulesPath is null)
+        // Distinguish them so the output isn't misleading.
+        if (p.rulesPath) {
+          cli.info(`${platformName(p.platform)} → already current`);
+        } else {
+          cli.info(`${platformName(p.platform)} → no rules path (MCP-only platform)`);
+        }
+        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.19",
+  "version": "0.2.21",
   "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",