a11y-devkit-deploy 0.6.5 → 0.7.0

package/README.md

@@ -1,6 +1,8 @@
 # A11y Devkit Deploy
 
-A 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 Claude Code, Cursor, Codex, and VSCode.
+
+**Add new skills or MCP servers without writing code** - just edit the JSON config and re-run.
 
 ## Install
 
@@ -61,17 +63,23 @@ All MCP servers are configured to run via `npx`, which means:
 
 This CLI automates the setup of accessibility tooling by:
 
-1. **Installing skills from npm** - Downloads and installs 7 accessibility skill packages
-2. **Configuring MCP servers** - Updates each IDE's MCP config to enable 5 accessibility-focused MCP servers:
-   - **wcag** - WCAG 2.2 guidelines, success criteria, and techniques
-   - **aria** - WAI-ARIA roles, states, properties, and patterns
-   - **magentaa11y** - Component accessibility acceptance criteria
-   - **a11y-personas** - Accessibility personas for diverse user needs
-   - **arc-issues** - Format AxeCore violations into standardized issue templates
+1. **Installing skills from npm** - Downloads and installs accessibility skill packages (configurable in `config/a11y.json`)
+2. **Configuring MCP servers** - Updates each IDE's MCP config to enable accessibility-focused MCP servers (also configurable)
+
+**Default configuration includes:**
+   - **7 accessibility skills** - Testing, remediation, validation, documentation, and orchestration
+   - **5 MCP servers**:
+     - **wcag** - WCAG 2.2 guidelines, success criteria, and techniques
+     - **aria** - WAI-ARIA roles, states, properties, and patterns
+     - **magentaa11y** - Component accessibility acceptance criteria
+     - **a11y-personas** - Accessibility personas for diverse user needs
+     - **arc-issues** - Format AxeCore violations into standardized issue templates
 
-### Skills Installed
+**Fully customizable** - add/remove skills or MCP servers by editing the config file.
 
-The following skill packages are installed from npm:
+### Skills Installed (Default)
+
+The following skill packages are installed from npm by default. **Add your own by editing `config/a11y.json`**:
 
 | Skill | Package | Description |
 |-------|---------|-------------|
@@ -110,11 +118,58 @@ The generated MCP config looks like this:
 
 ## Configuration
 
-Edit `config/a11y.json` to customize the deployment:
+The entire tool is **fully config-driven**. Edit `config/a11y.json` to customize everything without touching code:
+
+### Example: Adding a New Skill
+
+Simply add an object to the `skills` array with a `name` (npm package) and `description`:
+
+```json
+{
+  "skills": [
+    {
+      "name": "a11y-tester-skill",
+      "description": "Run accessibility tests"
+    },
+    {
+      "name": "your-custom-skill",
+      "description": "Your custom skill description"
+    }
+  ]
+}
+```
+
+### Example: Adding a New MCP Server
+
+Add an object to the `mcpServers` array with name, description, command, and args:
 
-- `skills` - Array of npm package names to install as skills
+```json
+{
+  "mcpServers": [
+    {
+      "name": "wcag",
+      "description": "WCAG guidelines reference",
+      "command": "npx",
+      "args": ["-y", "wcag-mcp"]
+    },
+    {
+      "name": "your-custom-mcp",
+      "description": "Your custom MCP server",
+      "command": "npx",
+      "args": ["-y", "your-mcp-package"]
+    }
+  ]
+}
+```
+
+### Config Structure
+
+- `skills` - Array of skill objects with `name` (npm package) and `description`
 - `ideSkillsPaths` - IDE-specific skills directories (configurable per IDE)
-- `mcpServers` - MCP server definitions using npx
+- `ideMcpPaths` - IDE-specific MCP config file paths
+- `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.
 
 ## Directory Structure
 
@@ -142,7 +197,9 @@ MCP configurations are written to each IDE's OS-specific config path:
 - **Windows**: `%APPDATA%\{IDE}\mcp.json`
 - **Linux**: `~/.config/{IDE}/mcp.json`
 
-## MCP Servers Included
+## MCP Servers Included (Default)
+
+**Add your own by editing `config/a11y.json`**:
 
 | Server | Package | Description |
 |--------|---------|-------------|

package/config/a11y.json

@@ -1,19 +1,41 @@
 {
+  "skillsFolder": "a11y",
+  "readmeTemplate": "deploy-README.md",
   "skills": [
-    "a11y-base-web-skill",
-    "a11y-issue-writer-skill",
-    "a11y-tester-skill",
-    "a11y-remediator-skill",
-    "a11y-validator-skill",
-    "web-standards-skill",
-    "a11y-audit-fix-agent-orchestrator-skill"
+    {
+      "name": "a11y-base-web-skill",
+      "description": "Core accessibility testing utilities"
+    },
+    {
+      "name": "a11y-issue-writer-skill",
+      "description": "Document accessibility issues"
+    },
+    {
+      "name": "a11y-tester-skill",
+      "description": "Run accessibility tests"
+    },
+    {
+      "name": "a11y-remediator-skill",
+      "description": "Fix accessibility issues"
+    },
+    {
+      "name": "a11y-validator-skill",
+      "description": "Validate accessibility compliance"
+    },
+    {
+      "name": "web-standards-skill",
+      "description": "Web standards reference"
+    },
+    {
+      "name": "a11y-audit-fix-agent-orchestrator-skill",
+      "description": "Orchestrate accessibility audits"
+    }
   ],
   "ideSkillsPaths": {
     "claude": ".claude/skills",
     "cursor": ".cursor/skills",
     "codex": ".codex/skills",
-    "vscode": ".github/skills",
-    "local": ".github/skills"
+    "vscode": ".github/skills"
   },
   "ideMcpPaths": {
     "claude": ".claude/mcp.json",
@@ -24,43 +46,33 @@
   "mcpServers": [
     {
       "name": "wcag",
+      "description": "WCAG guidelines reference",
       "command": "npx",
-      "args": [
-        "-y",
-        "wcag-mcp"
-      ]
+      "args": ["-y", "wcag-mcp"]
     },
     {
       "name": "aria",
+      "description": "ARIA specification reference",
       "command": "npx",
-      "args": [
-        "-y",
-        "aria-mcp"
-      ]
+      "args": ["-y", "aria-mcp"]
     },
     {
       "name": "magentaa11y",
+      "description": "MagentaA11y accessibility acceptance criteria tool",
       "command": "npx",
-      "args": [
-        "-y",
-        "magentaa11y-mcp"
-      ]
+      "args": ["-y", "magentaa11y-mcp"]
     },
     {
       "name": "a11y-personas",
+      "description": "Accessibility personas and user scenarios",
       "command": "npx",
-      "args": [
-        "-y",
-        "a11y-personas-mcp"
-      ]
+      "args": ["-y", "a11y-personas-mcp"]
     },
     {
       "name": "arc-issues",
+      "description": "Pre-formatted a11y issue templates",
       "command": "npx",
-      "args": [
-        "-y",
-        "arc-issues-mcp"
-      ]
+      "args": ["-y", "arc-issues-mcp"]
     }
   ]
-}
+}

package/package.json

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

package/src/cli.js

@@ -23,24 +23,6 @@ async function loadPackageJson() {
   return JSON.parse(raw);
 }
 
-const skillDescriptions = {
-  "a11y-base-web-skill": "Core accessibility testing utilities",
-  "a11y-issue-writer-skill": "Document accessibility issues",
-  "a11y-tester-skill": "Run accessibility tests",
-  "a11y-remediator-skill": "Fix accessibility issues",
-  "a11y-validator-skill": "Validate accessibility compliance",
-  "web-standards-skill": "Web standards reference",
-  "a11y-audit-fix-agent-orchestrator-skill": "Orchestrate accessibility audits"
-};
-
-const mcpDescriptions = {
-  "wcag": "WCAG guidelines reference",
-  "aria": "ARIA specification reference",
-  "magentaa11y": "MagentaA11y accessibility acceptance criteria tool",
-  "a11y-personas": "Accessibility personas and user scenarios",
-  "arc-issues": "Pre-formatted a11y issue templates"
-};
-
 function parseArgs(argv) {
   const args = new Set(argv.slice(2));
   return {
@@ -69,13 +51,14 @@ async function run() {
 
   console.log("\nSkills to install:");
   config.skills.forEach((skill) => {
-    const description = skillDescriptions[skill] || "No description";
-    console.log(`${skill} - ${description}`);
+    const name = typeof skill === "string" ? skill : skill.name;
+    const description = typeof skill === "string" ? "No description" : (skill.description || "No description");
+    console.log(`${name} - ${description}`);
   });
 
   console.log("\nMCP Servers to install:");
   config.mcpServers.forEach((server) => {
-    const description = mcpDescriptions[server.name] || "No description";
+    const description = server.description || "No description";
     console.log(`${server.name} - ${description}`);
   });
   console.log("");
@@ -179,7 +162,8 @@ async function run() {
         ? ideSelection.map((ide) => idePaths[ide].localSkillsDir)
         : ideSelection.map((ide) => idePaths[ide].skillsDir);
 
-      const result = await installSkillsFromNpm(config.skills, skillTargets, tempDir);
+      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}`);
@@ -214,9 +198,10 @@ async function run() {
   info("MCP servers use npx - no local installation needed!");
   console.log("");
   success("Next Steps:");
+  const skillsFolderPath = config.skillsFolder ? `${config.skillsFolder}/` : "";
   const skillsPath = scope === "local"
-    ? `.claude/skills/README.md (or your IDE's equivalent)`
-    : `~/.claude/skills/README.md (or your IDE's global skills directory)`;
+    ? `.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");

package/src/installers/skills.js

@@ -17,20 +17,32 @@ async function pathExists(target) {
 
 function run(command, args, options = {}) {
   return new Promise((resolve, reject) => {
-    const child = spawn(command, args, { stdio: "pipe", shell: true, ...options });
+    const child = spawn(command, args, {
+      stdio: "pipe",
+      shell: true,
+      ...options,
+    });
     let stdout = "";
     let stderr = "";
-    
-    child.stdout?.on("data", (data) => { stdout += data; });
-    child.stderr?.on("data", (data) => { stderr += data; });
-    
+
+    child.stdout?.on("data", (data) => {
+      stdout += data;
+    });
+    child.stderr?.on("data", (data) => {
+      stderr += data;
+    });
+
     child.on("error", reject);
     child.on("close", (code) => {
       if (code === 0) {
         resolve({ stdout, stderr });
         return;
       }
-      reject(new Error(`${command} ${args.join(" ")} failed with code ${code}: ${stderr}`));
+      reject(
+        new Error(
+          `${command} ${args.join(" ")} failed with code ${code}: ${stderr}`,
+        ),
+      );
     });
   });
 }
@@ -43,18 +55,26 @@ async function cleanupTemp(tempDir) {
 
 /**
  * Install skills from npm packages into IDE skills directories.
- * 
+ *
  * 1. Creates temp directory with package.json listing skills as dependencies
  * 2. Runs npm install in temp directory
  * 3. Copies installed skill packages (SKILL.md files) to target directories
  * 4. Returns temp directory path for cleanup
- * 
+ *
  * @param {string[]} skills - Array of npm package names
  * @param {string[]} targetDirs - Array of target directories to install skills to
  * @param {string} tempDir - Temporary directory for npm install
+ * @param {string} skillsFolder - Optional subfolder name to bundle skills (e.g., "a11y")
+ * @param {string} readmeTemplate - README template filename from templates folder
  * @returns {Promise<{installed: number, tempDir: string}>}
  */
-async function installSkillsFromNpm(skills, targetDirs, tempDir) {
+async function installSkillsFromNpm(
+  skills,
+  targetDirs,
+  tempDir,
+  skillsFolder = null,
+  readmeTemplate = "deploy-README.md",
+) {
   // Create temp directory
   await fs.mkdir(tempDir, { recursive: true });
 
@@ -63,7 +83,7 @@ async function installSkillsFromNpm(skills, targetDirs, tempDir) {
     name: "a11y-skills-temp",
     version: "1.0.0",
     private: true,
-    dependencies: {}
+    dependencies: {},
   };
 
   for (const skill of skills) {
@@ -72,7 +92,7 @@ async function installSkillsFromNpm(skills, targetDirs, tempDir) {
 
   await fs.writeFile(
     path.join(tempDir, "package.json"),
-    JSON.stringify(packageJson, null, 2)
+    JSON.stringify(packageJson, null, 2),
   );
 
   // Run npm install
@@ -83,7 +103,12 @@ async function installSkillsFromNpm(skills, targetDirs, tempDir) {
   let installedCount = 0;
 
   for (const targetDir of targetDirs) {
-    await fs.mkdir(targetDir, { recursive: true });
+    // Determine the actual skills directory (with or without bundle folder)
+    const skillsDir = skillsFolder
+      ? path.join(targetDir, skillsFolder)
+      : targetDir;
+
+    await fs.mkdir(skillsDir, { recursive: true });
 
     for (const skill of skills) {
       const skillPackageDir = path.join(nodeModulesDir, skill);
@@ -92,7 +117,7 @@ async function installSkillsFromNpm(skills, targetDirs, tempDir) {
       if (await pathExists(skillMdPath)) {
         // Create skill directory in target (use package name without -skill suffix)
         const skillDirName = skill.replace(/-skill$/, "");
-        const targetSkillDir = path.join(targetDir, skillDirName);
+        const targetSkillDir = path.join(skillsDir, skillDirName);
         await fs.mkdir(targetSkillDir, { recursive: true });
 
         // Copy SKILL.md
@@ -102,20 +127,23 @@ async function installSkillsFromNpm(skills, targetDirs, tempDir) {
     }
 
     // Copy the comprehensive README template to the skills directory
-    const readmeTemplatePath = path.join(__dirname, "..", "templates", "skills-README.md");
-    const targetReadmePath = path.join(targetDir, "README.md");
+    const readmeTemplatePath = path.join(
+      __dirname,
+      "..",
+      "..",
+      "templates",
+      readmeTemplate,
+    );
+    const targetReadmePath = path.join(skillsDir, "a11y-devkit-README.md");
     if (await pathExists(readmeTemplatePath)) {
       await fs.copyFile(readmeTemplatePath, targetReadmePath);
     }
   }
 
-  return { 
-    installed: installedCount / targetDirs.length, 
-    tempDir 
+  return {
+    installed: installedCount / targetDirs.length,
+    tempDir,
   };
 }
 
-export {
-  installSkillsFromNpm,
-  cleanupTemp
-};
+export { installSkillsFromNpm, cleanupTemp };