a11y-devkit-deploy 0.7.0 → 0.7.2

package/README.md

@@ -1,8 +1,8 @@
 # A11y Devkit Deploy
 
-A **fully config-driven**, cross-platform CLI for deploying accessibility skills and MCP servers across Claude Code, Cursor, Codex, and VSCode.
+A **fully config-driven**, cross-platform CLI for deploying accessibility skills and MCP servers across multiple IDEs: Claude Code, Cursor, Codex, VSCode, Windsurf, and Factory.
 
-**Add new skills or MCP servers without writing code** - just edit the JSON config and re-run.
+**Add new skills, MCP servers, or entire IDEs without writing code** - just edit the JSON config and re-run.
 
 ## Install
 
@@ -27,8 +27,8 @@ a11y-devkit-deploy
 
 Once installation completes, you'll find a comprehensive usage guide in your IDE's skills directory:
 
-- **Local install**: `.claude/skills/README.md` (or `.cursor/skills/`, `.codex/skills/` depending on your IDE)
-- **Global install**: `~/.claude/skills/README.md` (or your IDE's global skills directory)
+- **Local install**: `.claude/skills/a11y/a11y-devkit-README.md` (or `.cursor/skills/a11y/`, `.codex/skills/a11y/` depending on your IDE)
+- **Global install**: `~/.claude/skills/a11y/a11y-devkit-README.md` (or your IDE's global skills directory)
 
 ### What's in the Guide
 
@@ -42,7 +42,7 @@ The bundled README includes:
 
 ### Preview the Guide
 
-You can preview the guide here: [templates/skills-README.md](templates/skills-README.md)
+You can preview the guide here: [templates/deploy-README.md](templates/deploy-README.md)
 
 ### Next Steps
 
@@ -75,7 +75,31 @@ This CLI automates the setup of accessibility tooling by:
      - **a11y-personas** - Accessibility personas for diverse user needs
      - **arc-issues** - Format AxeCore violations into standardized issue templates
 
-**Fully customizable** - add/remove skills or MCP servers by editing the config file.
+**Fully customizable** - add/remove skills, MCP servers, or entire IDEs by editing the config file.
+
+## Why This Tool?
+
+**Zero Hardcoded Values** - Every aspect of the tool is driven by `config/a11y.json`:
+- IDE paths and configuration files
+- Skills to install
+- MCP servers to configure
+- Even the IDE list itself
+
+**Adding Support for a New IDE** takes just 5 lines of JSON:
+```json
+{
+  "id": "new-ide",
+  "displayName": "New IDE",
+  "mcpServerKey": "servers",
+  "skillsFolder": ".new-ide/skills",
+  "mcpConfigFile": ".new-ide/mcp.json"
+}
+```
+
+**Safe by Default** - Won't overwrite your existing:
+- Custom MCP servers in your IDE configs
+- Other skills in your skills directories
+- Creates backups if it encounters JSON parsing errors
 
 ### Skills Installed (Default)
 
@@ -118,9 +142,9 @@ The generated MCP config looks like this:
 
 ## Configuration
 
-The entire tool is **fully config-driven**. Edit `config/a11y.json` to customize everything without touching code:
+The entire tool is **fully config-driven**. Edit `config/a11y.json` to customize everything without touching code.
 
-### Example: Adding a New Skill
+### Adding a New Skill
 
 Simply add an object to the `skills` array with a `name` (npm package) and `description`:
 
@@ -139,7 +163,7 @@ Simply add an object to the `skills` array with a `name` (npm package) and `desc
 }
 ```
 
-### Example: Adding a New MCP Server
+### Adding a New MCP Server
 
 Add an object to the `mcpServers` array with name, description, command, and args:
 
@@ -162,40 +186,96 @@ Add an object to the `mcpServers` array with name, description, command, and arg
 }
 ```
 
+### Adding a New IDE
+
+Add an object to the `ides` array with the IDE's configuration:
+
+```json
+{
+  "ides": [
+    {
+      "id": "windsurf",
+      "displayName": "Windsurf",
+      "mcpServerKey": "servers",
+      "skillsFolder": ".codeium/windsurf/skills",
+      "mcpConfigFile": ".codeium/windsurf/mcp_config.json"
+    }
+  ]
+}
+```
+
+**IDE Configuration Properties:**
+- `id` - Unique identifier for the IDE
+- `displayName` - Human-readable name shown in prompts
+- `mcpServerKey` - MCP config key name (`"servers"` or `"mcpServers"`)
+- `skillsFolder` - Path to skills directory (relative to home/project root)
+- `mcpConfigFile` - Path to MCP config file (relative to home/project root)
+
 ### Config Structure
 
+- `skillsFolder` - Subfolder name to bundle skills under (e.g., "a11y")
+- `readmeTemplate` - README template file to copy into skills directories
 - `skills` - Array of skill objects with `name` (npm package) and `description`
-- `ideSkillsPaths` - IDE-specific skills directories (configurable per IDE)
-- `ideMcpPaths` - IDE-specific MCP config file paths
+- `ides` - Array of IDE configuration objects
 - `mcpServers` - MCP server definitions with name, description, command, and args
 
 All changes take effect immediately - just re-run the CLI to deploy your updated config.
 
+### Safe Merging
+
+The CLI **safely merges** with existing configurations:
+- **MCP configs** - Adds/updates only the specified servers, preserves others
+- **Skills** - Installs only the configured skills, preserves other skills in the directory
+- **Backups** - Creates `.bak` files if JSON parsing fails
+
 ## Directory Structure
 
 ### Local Install (Project-Specific)
 ```
 your-project/
-├── .claude/skills/          # Skills copied to Claude Code (if selected)
-├── .cursor/skills/          # Skills copied to Cursor (if selected)
-├── .codex/skills/           # Skills copied to Codex (if selected)
-└── .github/skills/          # Skills copied here for version control
+├── .claude/
+│   ├── mcp.json            # Claude Code MCP config
+│   └── skills/             # Claude Code skills
+├── .cursor/
+│   ├── mcp.json            # Cursor MCP config
+│   └── skills/             # Cursor skills
+├── .codex/
+│   ├── mcp.json            # Codex MCP config
+│   └── skills/             # Codex skills
+├── .github/
+│   ├── mcp.json            # VSCode MCP config
+│   └── skills/             # VSCode skills
+├── .codeium/windsurf/
+│   ├── mcp_config.json     # Windsurf MCP config
+│   └── skills/             # Windsurf skills
+└── .factory/
+    ├── mcp.json            # Factory MCP config
+    └── skills/             # Factory skills
 ```
 
 ### Global Install (User-Wide)
 ```
-~/.claude/skills/            # Claude Code skills
-~/.cursor/skills/            # Cursor skills
-~/.codex/skills/             # Codex skills
-~/.vscode/skills/            # VSCode skills
+~/.claude/
+  ├── mcp.json              # Claude Code global MCP config
+  └── skills/               # Claude Code global skills
+~/.cursor/
+  ├── mcp.json              # Cursor global MCP config
+  └── skills/               # Cursor global skills
+~/.codex/
+  ├── mcp.json              # Codex global MCP config
+  └── skills/               # Codex global skills
+~/.github/
+  ├── mcp.json              # VSCode global MCP config
+  └── skills/               # VSCode global skills
+~/.codeium/windsurf/
+  ├── mcp_config.json       # Windsurf global MCP config
+  └── skills/               # Windsurf global skills
+~/.factory/
+  ├── mcp.json              # Factory global MCP config
+  └── skills/               # Factory global skills
 ```
 
-### MCP Configuration Locations
-
-MCP configurations are written to each IDE's OS-specific config path:
-- **macOS**: `~/Library/Application Support/{IDE}/mcp.json`
-- **Windows**: `%APPDATA%\{IDE}\mcp.json`
-- **Linux**: `~/.config/{IDE}/mcp.json`
+**Note:** Paths are fully customizable per IDE in `config/a11y.json`
 
 ## MCP Servers Included (Default)
 
@@ -208,3 +288,63 @@ MCP configurations are written to each IDE's OS-specific config path:
 | magentaa11y | `magentaa11y-mcp` | Component accessibility acceptance criteria |
 | a11y-personas | `a11y-personas-mcp` | Accessibility personas for diverse users |
 | arc-issues | `arc-issues-mcp` | AxeCore violation formatting |
+
+## Complete Config Example
+
+Here's what a complete `config/a11y.json` looks like:
+
+```json
+{
+  "skillsFolder": "a11y",
+  "readmeTemplate": "deploy-README.md",
+  "skills": [
+    {
+      "name": "a11y-base-web-skill",
+      "description": "Core accessibility testing utilities"
+    },
+    {
+      "name": "a11y-tester-skill",
+      "description": "Run accessibility tests"
+    }
+  ],
+  "ides": [
+    {
+      "id": "claude",
+      "displayName": "Claude Code",
+      "mcpServerKey": "servers",
+      "skillsFolder": ".claude/skills",
+      "mcpConfigFile": ".claude/mcp.json"
+    },
+    {
+      "id": "cursor",
+      "displayName": "Cursor",
+      "mcpServerKey": "mcpServers",
+      "skillsFolder": ".cursor/skills",
+      "mcpConfigFile": ".cursor/mcp.json"
+    },
+    {
+      "id": "windsurf",
+      "displayName": "Windsurf",
+      "mcpServerKey": "servers",
+      "skillsFolder": ".codeium/windsurf/skills",
+      "mcpConfigFile": ".codeium/windsurf/mcp_config.json"
+    }
+  ],
+  "mcpServers": [
+    {
+      "name": "wcag",
+      "description": "WCAG guidelines reference",
+      "command": "npx",
+      "args": ["-y", "wcag-mcp"]
+    },
+    {
+      "name": "aria",
+      "description": "ARIA specification reference",
+      "command": "npx",
+      "args": ["-y", "aria-mcp"]
+    }
+  ]
+}
+```
+
+Everything is customizable - add, remove, or modify any section to match your needs.

package/config/a11y.json

@@ -31,18 +31,50 @@
       "description": "Orchestrate accessibility audits"
     }
   ],
-  "ideSkillsPaths": {
-    "claude": ".claude/skills",
-    "cursor": ".cursor/skills",
-    "codex": ".codex/skills",
-    "vscode": ".github/skills"
-  },
-  "ideMcpPaths": {
-    "claude": ".claude/mcp.json",
-    "cursor": ".cursor/mcp.json",
-    "codex": ".codex/mcp.json",
-    "vscode": ".github/mcp.json"
-  },
+  "ides": [
+    {
+      "id": "claude",
+      "displayName": "Claude Code",
+      "mcpServerKey": "servers",
+      "skillsFolder": ".claude/skills",
+      "mcpConfigFile": ".claude/mcp.json"
+    },
+    {
+      "id": "cursor",
+      "displayName": "Cursor",
+      "mcpServerKey": "mcpServers",
+      "skillsFolder": ".cursor/skills",
+      "mcpConfigFile": ".cursor/mcp.json"
+    },
+    {
+      "id": "codex",
+      "displayName": "Codex",
+      "mcpServerKey": "servers",
+      "skillsFolder": ".codex/skills",
+      "mcpConfigFile": ".codex/mcp.json"
+    },
+    {
+      "id": "vscode",
+      "displayName": "VSCode",
+      "mcpServerKey": "servers",
+      "skillsFolder": ".github/skills",
+      "mcpConfigFile": ".github/mcp.json"
+    },
+    {
+      "id": "windsurf",
+      "displayName": "Windsurf",
+      "mcpServerKey": "servers",
+      "skillsFolder": ".codeium/windsurf/skills",
+      "mcpConfigFile": ".codeium/windsurf/mcp_config.json"
+    },
+    {
+      "id": "factory",
+      "displayName": "Factory",
+      "mcpServerKey": "mcpServers",
+      "skillsFolder": ".factory/skills",
+      "mcpConfigFile": ".factory/mcp.json"
+    }
+  ],
   "mcpServers": [
     {
       "name": "wcag",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "a11y-devkit-deploy",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "CLI to deploy a11y skills and MCP servers across IDEs",
   "license": "MIT",
   "type": "module",

package/src/cli.js

@@ -27,7 +27,11 @@ function parseArgs(argv) {
   const args = new Set(argv.slice(2));
   return {
     autoYes: args.has("--yes") || args.has("-y"),
-    scope: args.has("--global") ? "global" : args.has("--local") ? "local" : null
+    scope: args.has("--global")
+      ? "global"
+      : args.has("--local")
+        ? "local"
+        : null,
   };
 }
 
@@ -43,17 +47,23 @@ async function run() {
   const platformInfo = getPlatform();
   const config = await loadConfig();
   const pkg = await loadPackageJson();
-  const idePaths = getIdePaths(projectRoot, platformInfo, config.ideSkillsPaths, config.ideMcpPaths);
+  const idePaths = getIdePaths(projectRoot, platformInfo, config.ides);
   const args = parseArgs(process.argv);
 
-  header(`A11y Devkit Deploy v${pkg.version}`, "Install skills + MCP servers across IDEs");
+  header(
+    `A11y Devkit Deploy v${pkg.version}`,
+    "Install skills + MCP servers across IDEs",
+  );
   info(`Detected OS: ${formatOs(platformInfo)}`);
 
   console.log("\nSkills to install:");
   config.skills.forEach((skill) => {
     const name = typeof skill === "string" ? skill : skill.name;
-    const description = typeof skill === "string" ? "No description" : (skill.description || "No description");
-    console.log(`${name} - ${description}`);
+    const description =
+      typeof skill === "string"
+        ? "No description"
+        : skill.description || "No description";
+    console.log(`- ${name}: ${description}`);
   });
 
   console.log("\nMCP Servers to install:");
@@ -63,16 +73,14 @@ async function run() {
   });
   console.log("");
 
-  const ideChoices = [
-    { title: "Claude Code", value: "claude" },
-    { title: "Cursor", value: "cursor" },
-    { title: "Codex", value: "codex" },
-    { title: "VSCode", value: "vscode" }
-  ];
+  const ideChoices = config.ides.map((ide) => ({
+    title: ide.displayName,
+    value: ide.id,
+  }));
 
   let scope = args.scope;
   let mcpScope = null;
-  let ideSelection = ["claude", "cursor", "codex", "vscode"];
+  let ideSelection = config.ides.map((ide) => ide.id);
   let installSkills = true;
 
   if (!args.autoYes) {
@@ -83,10 +91,13 @@ async function run() {
           name: "scope",
           message: "Install skills + repo locally or globally?",
           choices: [
-            { title: `Local to this project (${formatPath(projectRoot)})`, value: "local" },
-            { title: "Global for this user", value: "global" }
+            {
+              title: `Local to this project (${formatPath(projectRoot)})`,
+              value: "local",
+            },
+            { title: "Global for this user", value: "global" },
           ],
-          initial: 0
+          initial: 0,
         },
         {
           type: "select",
@@ -96,22 +107,23 @@ async function run() {
             {
               title: `Local to this project (${formatPath(projectRoot)})`,
               value: "local",
-              description: "Write to project-level IDE config folders (version-controllable)"
+              description:
+                "Write to project-level IDE config folders (version-controllable)",
             },
             {
               title: "Global for this user",
               value: "global",
-              description: "Write to user-level IDE config folders"
-            }
+              description: "Write to user-level IDE config folders",
+            },
           ],
-          initial: 0
+          initial: 0,
         },
         {
           type: "multiselect",
           name: "ides",
           message: "Configure MCP for which IDEs?",
           choices: ideChoices,
-          initial: ideChoices.map((_, index) => index)
+          initial: ideChoices.map((_, index) => index),
         },
         {
           type: "toggle",
@@ -119,15 +131,15 @@ async function run() {
           message: "Install skills into IDE skills folders?",
           active: "yes",
           inactive: "no",
-          initial: true
-        }
+          initial: true,
+        },
       ],
       {
         onCancel: () => {
           warn("Setup cancelled.");
           process.exit(0);
-        }
-      }
+        },
+      },
     );
 
     scope = scope || response.scope;
@@ -158,13 +170,24 @@ async function run() {
     const skillsSpinner = startSpinner("Installing skills from npm...");
 
     try {
-      const skillTargets = scope === "local"
-        ? ideSelection.map((ide) => idePaths[ide].localSkillsDir)
-        : ideSelection.map((ide) => idePaths[ide].skillsDir);
-
-      const skillNames = config.skills.map((skill) => typeof skill === "string" ? skill : skill.name);
-      const result = await installSkillsFromNpm(skillNames, skillTargets, tempDir, config.skillsFolder, config.readmeTemplate);
-      skillsSpinner.succeed(`${result.installed} skills installed to ${skillTargets.length} IDE location(s).`);
+      const skillTargets =
+        scope === "local"
+          ? ideSelection.map((ide) => idePaths[ide].localSkillsDir)
+          : ideSelection.map((ide) => idePaths[ide].skillsDir);
+
+      const skillNames = config.skills.map((skill) =>
+        typeof skill === "string" ? skill : skill.name,
+      );
+      const result = await installSkillsFromNpm(
+        skillNames,
+        skillTargets,
+        tempDir,
+        config.skillsFolder,
+        config.readmeTemplate,
+      );
+      skillsSpinner.succeed(
+        `${result.installed} skills installed to ${skillTargets.length} IDE location(s).`,
+      );
     } catch (error) {
       skillsSpinner.fail(`Failed to install skills: ${error.message}`);
     }
@@ -174,19 +197,22 @@ async function run() {
 
   // Configure MCP servers using npx (no local installation needed!)
   const mcpSpinner = startSpinner("Updating MCP configurations...");
-  const mcpConfigPaths = mcpScope === "local"
-    ? ideSelection.map((ide) => idePaths[ide].localMcpConfig)
-    : ideSelection.map((ide) => idePaths[ide].mcpConfig);
+  const mcpConfigPaths =
+    mcpScope === "local"
+      ? ideSelection.map((ide) => idePaths[ide].localMcpConfig)
+      : ideSelection.map((ide) => idePaths[ide].mcpConfig);
 
   for (let i = 0; i < ideSelection.length; i++) {
     const ide = ideSelection[i];
     await installMcpConfig(
       mcpConfigPaths[i],
       config.mcpServers,
-      idePaths[ide].mcpServerKey
+      idePaths[ide].mcpServerKey,
     );
   }
-  mcpSpinner.succeed(`MCP configs updated for ${ideSelection.length} IDE(s) (${mcpScope} scope).`);
+  mcpSpinner.succeed(
+    `MCP configs updated for ${ideSelection.length} IDE(s) (${mcpScope} scope).`,
+  );
 
   // Clean up temporary directory
   const cleanupSpinner = startSpinner("Cleaning up temporary files...");
@@ -199,17 +225,18 @@ async function run() {
   console.log("");
   success("Next Steps:");
   const skillsFolderPath = config.skillsFolder ? `${config.skillsFolder}/` : "";
-  const skillsPath = scope === "local"
-    ? `.claude/skills/${skillsFolderPath}README.md (or your IDE's equivalent)`
-    : `~/.claude/skills/${skillsFolderPath}README.md (or your IDE's global skills directory)`;
+  const skillsPath =
+    scope === "local"
+      ? `.claude/skills/${skillsFolderPath}README.md (or your IDE's equivalent)`
+      : `~/.claude/skills/${skillsFolderPath}README.md (or your IDE's global skills directory)`;
   info(`📖 Check ${skillsPath} for comprehensive usage guide`);
   info("✨ Includes 70+ example prompts for all skills and MCP servers");
-  info("🚀 Start with the 'Getting Started' section for your first accessibility check");
+  info(
+    "🚀 Start with the 'Getting Started' section for your first accessibility check",
+  );
   console.log("");
   info("You can re-run this CLI any time to update skills and configs.");
   info("Documentation: https://github.com/joe-watkins/a11y-devkit#readme");
 }
 
-export {
-  run
-};
+export { run };

package/src/paths.js

@@ -30,60 +30,26 @@ function getAppSupportDir(platformInfo = getPlatform()) {
   return process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
 }
 
-function getIdePaths(projectRoot, platformInfo = getPlatform(), ideSkillsPaths = null, ideMcpPaths = null) {
-  const appSupport = getAppSupportDir(platformInfo);
+function getIdePaths(projectRoot, platformInfo = getPlatform(), ideConfigs = []) {
   const home = os.homedir();
+  const paths = {};
+
+  for (const ide of ideConfigs) {
+    // Use custom paths from config, or fall back to default pattern: ~/.{id}/
+    const skillsFolder = ide.skillsFolder || `.${ide.id}/skills`;
+    const mcpConfigFile = ide.mcpConfigFile || `.${ide.id}/mcp.json`;
+
+    paths[ide.id] = {
+      name: ide.displayName,
+      mcpConfig: path.join(home, mcpConfigFile),
+      localMcpConfig: path.join(projectRoot, mcpConfigFile),
+      mcpServerKey: ide.mcpServerKey,
+      skillsDir: path.join(home, skillsFolder),
+      localSkillsDir: path.join(projectRoot, skillsFolder)
+    };
+  }
 
-  // Default paths if not provided via config
-  const skillsPaths = ideSkillsPaths || {
-    claude: ".claude/skills",
-    cursor: ".cursor/skills",
-    codex: ".codex/skills",
-    vscode: ".vscode/skills",
-    local: ".github/skills"
-  };
-
-  const mcpPaths = ideMcpPaths || {
-    claude: ".claude/mcp.json",
-    cursor: ".cursor/mcp.json",
-    codex: ".codex/mcp.json",
-    vscode: ".vscode/mcp.json"
-  };
-
-  return {
-    claude: {
-      name: "Claude Code",
-      mcpConfig: path.join(appSupport, "Claude", "mcp.json"),
-      localMcpConfig: path.join(projectRoot, mcpPaths.claude),
-      mcpServerKey: "servers",
-      skillsDir: path.join(home, skillsPaths.claude),
-      localSkillsDir: path.join(projectRoot, skillsPaths.claude)
-    },
-    cursor: {
-      name: "Cursor",
-      mcpConfig: path.join(appSupport, "Cursor", "mcp.json"),
-      localMcpConfig: path.join(projectRoot, mcpPaths.cursor),
-      mcpServerKey: "mcpServers",
-      skillsDir: path.join(home, skillsPaths.cursor),
-      localSkillsDir: path.join(projectRoot, skillsPaths.cursor)
-    },
-    codex: {
-      name: "Codex",
-      mcpConfig: path.join(home, ".codex", "mcp.json"),
-      localMcpConfig: path.join(projectRoot, mcpPaths.codex),
-      mcpServerKey: "servers",
-      skillsDir: path.join(home, skillsPaths.codex),
-      localSkillsDir: path.join(projectRoot, skillsPaths.codex)
-    },
-    vscode: {
-      name: "VSCode",
-      mcpConfig: path.join(appSupport, "Code", "User", "mcp.json"),
-      localMcpConfig: path.join(projectRoot, mcpPaths.vscode),
-      mcpServerKey: "servers",
-      skillsDir: path.join(home, skillsPaths.vscode),
-      localSkillsDir: path.join(projectRoot, skillsPaths.vscode)
-    }
-  };
+  return paths;
 }
 
 export {