@joehom/awm-cli 0.0.1

package/src/seed.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * Seeds the AWM registry with default MCPs and skills.
+ * Safe to re-run — skips files that already exist unless --force is passed.
+ *
+ * Called automatically via npm postinstall.
+ * Also called by `awm setup [--force]`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getRegistryRoot } from './utils/pathResolver.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULTS_DIR = path.join(__dirname, 'defaults');
+
+/**
+ * Recursively copy src directory to dest.
+ * Uses Node.js built-in fs.cpSync (Node 16.7+).
+ */
+function copyDirSync(src, dest, force) {
+  if (!fs.existsSync(src)) return;
+  if (!force && fs.existsSync(dest)) return; // skip existing
+  fs.cpSync(src, dest, { recursive: true, force: true });
+}
+
+/**
+ * Copy a single file to dest path.
+ * Skips if dest exists and force=false.
+ */
+function copyFileIfMissing(src, dest, force) {
+  if (!force && fs.existsSync(dest)) return false;
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  return true;
+}
+
+export function runSeed(force = false) {
+  const registryRoot = getRegistryRoot();
+
+  // Ensure all registry dirs exist
+  for (const sub of ['mcps', 'skills', 'profiles', 'tools']) {
+    fs.mkdirSync(path.join(registryRoot, sub), { recursive: true });
+  }
+
+  const results = { mcps: [], skills: [], tools: [], skipped: [] };
+
+  // --- Seed MCPs ---
+  const defaultMcpsDir = path.join(DEFAULTS_DIR, 'mcps');
+  if (fs.existsSync(defaultMcpsDir)) {
+    for (const file of fs.readdirSync(defaultMcpsDir)) {
+      if (!file.endsWith('.json')) continue;
+      const src = path.join(defaultMcpsDir, file);
+      const dest = path.join(registryRoot, 'mcps', file);
+      const copied = copyFileIfMissing(src, dest, force);
+      const id = file.replace(/\.json$/, '');
+      if (copied) results.mcps.push(id);
+      else results.skipped.push(`mcp:${id}`);
+    }
+  }
+
+  // --- Seed Tools ---
+  const defaultToolsDir = path.join(DEFAULTS_DIR, 'tools');
+  if (fs.existsSync(defaultToolsDir)) {
+    for (const file of fs.readdirSync(defaultToolsDir)) {
+      if (!file.endsWith('.json')) continue;
+      const src = path.join(defaultToolsDir, file);
+      const dest = path.join(registryRoot, 'tools', file);
+      const copied = copyFileIfMissing(src, dest, force);
+      const id = file.replace(/\.json$/, '');
+      if (copied) results.tools.push(id);
+      else results.skipped.push(`tool:${id}`);
+    }
+  }
+
+  // --- Seed Skills ---
+  const defaultSkillsDir = path.join(DEFAULTS_DIR, 'skills');
+  if (fs.existsSync(defaultSkillsDir)) {
+    for (const name of fs.readdirSync(defaultSkillsDir)) {
+      const src = path.join(defaultSkillsDir, name);
+      if (!fs.statSync(src).isDirectory()) continue;
+      const dest = path.join(registryRoot, 'skills', name);
+      const existed = fs.existsSync(dest);
+      if (!force && existed) {
+        results.skipped.push(`skill:${name}`);
+        continue;
+      }
+      fs.cpSync(src, dest, { recursive: true, force: true });
+      results.skills.push(name);
+    }
+  }
+
+  return results;
+}
+
+// Only auto-run when executed directly (postinstall or `node src/seed.js`)
+// NOT when imported as a module by src/commands/setup.js
+const selfPath = fileURLToPath(import.meta.url);
+const isDirectRun = process.argv[1] &&
+  path.resolve(process.argv[1]) === path.resolve(selfPath);
+
+if (isDirectRun) {
+  const force = process.argv.includes('--force');
+  try {
+    const results = runSeed(force);
+
+    const seeded = results.mcps.length + results.skills.length + results.tools.length;
+    if (results.tools.length > 0) {
+      console.log(`[awm] Seeded tools: ${results.tools.join(', ')}`);
+    }
+    if (results.mcps.length > 0) {
+      console.log(`[awm] Seeded MCPs: ${results.mcps.join(', ')}`);
+    }
+    if (results.skills.length > 0) {
+      console.log(`[awm] Seeded skills: ${results.skills.join(', ')}`);
+    }
+    if (results.skipped.length > 0 && seeded > 0) {
+      console.log(`[awm] Skipped (already present): ${results.skipped.join(', ')}`);
+    }
+    if (seeded === 0) {
+      if (results.skipped.length > 0) {
+        console.log(`[awm] Registry already seeded. Use --force to overwrite.`);
+      } else {
+        console.log(`[awm] Registry seeded (nothing to add).`);
+      }
+    }
+  } catch (err) {
+    // Don't fail the npm install if seeding fails
+    console.warn(`[awm] Warning: could not seed registry: ${err.message}`);
+  }
+}

package/src/tools/claude-code.json

@@ -0,0 +1,27 @@
+{
+  "id": "claude-code",
+  "name": "Claude Code",
+  "supports": {
+    "mcp": true,
+    "skills": true
+  },
+  "mcp": {
+    "format": "json",
+    "project": {
+      "targetFile": ".mcp.json",
+      "rootObject": "mcpServers"
+    },
+    "global": {
+      "targetFile": "~/.claude.json",
+      "rootObject": "mcpServers"
+    }
+  },
+  "skills": {
+    "project": {
+      "targetFolder": ".claude/skills"
+    },
+    "global": {
+      "targetFolder": "~/.claude/skills"
+    }
+  }
+}

package/src/tools/codex.json

@@ -0,0 +1,27 @@
+{
+  "id": "codex",
+  "name": "Codex CLI",
+  "supports": {
+    "mcp": true,
+    "skills": true
+  },
+  "mcp": {
+    "format": "toml",
+    "project": {
+      "targetFile": ".codex/config.toml",
+      "rootObject": "mcp_servers"
+    },
+    "global": {
+      "targetFile": "~/.codex/config.toml",
+      "rootObject": "mcp_servers"
+    }
+  },
+  "skills": {
+    "project": {
+      "targetFolder": ".agents/skills"
+    },
+    "global": {
+      "targetFolder": "~/.agents/skills"
+    }
+  }
+}

package/src/tools/copilot-cli.json

@@ -0,0 +1,15 @@
+{
+  "id": "copilot-cli",
+  "name": "Copilot CLI",
+  "supports": {
+    "mcp": true,
+    "skills": false
+  },
+  "mcp": {
+    "format": "json",
+    "global": {
+      "targetFile": "~/.copilot/mcp-config.json",
+      "rootObject": "servers"
+    }
+  }
+}

package/src/tools/cursor.json

@@ -0,0 +1,27 @@
+{
+  "id": "cursor",
+  "name": "Cursor",
+  "supports": {
+    "mcp": true,
+    "skills": true
+  },
+  "mcp": {
+    "format": "json",
+    "project": {
+      "targetFile": ".cursor/mcp.json",
+      "rootObject": "mcpServers"
+    },
+    "global": {
+      "targetFile": "~/.cursor/mcp.json",
+      "rootObject": "mcpServers"
+    }
+  },
+  "skills": {
+    "project": {
+      "targetFolder": ".cursor/rules"
+    },
+    "global": {
+      "targetFolder": "~/.cursor/rules"
+    }
+  }
+}

package/src/tools/gemini-cli.json

@@ -0,0 +1,27 @@
+{
+  "id": "gemini-cli",
+  "name": "Gemini CLI",
+  "supports": {
+    "mcp": true,
+    "skills": true
+  },
+  "mcp": {
+    "format": "json",
+    "project": {
+      "targetFile": ".gemini/settings.json",
+      "rootObject": "mcpServers"
+    },
+    "global": {
+      "targetFile": "~/.gemini/settings.json",
+      "rootObject": "mcpServers"
+    }
+  },
+  "skills": {
+    "project": {
+      "targetFolder": ".gemini/skills"
+    },
+    "global": {
+      "targetFolder": "~/.gemini/skills"
+    }
+  }
+}

package/src/tools/github-copilot.json

@@ -0,0 +1,23 @@
+{
+  "id": "github-copilot",
+  "name": "GitHub Copilot (VS Code)",
+  "supports": {
+    "mcp": true,
+    "skills": true
+  },
+  "mcp": {
+    "format": "json",
+    "project": {
+      "targetFile": ".vscode/mcp.json",
+      "rootObject": "servers"
+    }
+  },
+  "skills": {
+    "project": {
+      "targetFolder": ".github/skills"
+    },
+    "global": {
+      "targetFolder": "~/.copilot/skills"
+    }
+  }
+}

package/src/tools/windsurf.json

@@ -0,0 +1,23 @@
+{
+  "id": "windsurf",
+  "name": "Windsurf",
+  "supports": {
+    "mcp": true,
+    "skills": true
+  },
+  "mcp": {
+    "format": "json",
+    "global": {
+      "targetFile": "~/.codeium/windsurf/mcp_config.json",
+      "rootObject": "mcpServers"
+    }
+  },
+  "skills": {
+    "project": {
+      "targetFolder": ".windsurf/skills"
+    },
+    "global": {
+      "targetFolder": "~/.codeium/windsurf/skills"
+    }
+  }
+}

package/src/utils/fileUtils.js

@@ -0,0 +1,76 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+// Use dynamic import for fs-extra (ESM)
+let fse;
+async function getFse() {
+  if (!fse) fse = (await import('fs-extra')).default;
+  return fse;
+}
+
+/**
+ * Read and parse a JSON file. Returns null if file doesn't exist.
+ * @param {string} filePath
+ * @returns {any}
+ */
+export function readJson(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const raw = fs.readFileSync(filePath, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Write an object as JSON to a file, creating parent directories as needed.
+ * @param {string} filePath
+ * @param {any} data
+ */
+export function writeJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Copy a directory recursively using fs-extra.
+ * @param {string} src
+ * @param {string} dest
+ */
+export async function copyDir(src, dest) {
+  const fsExtra = await getFse();
+  await fsExtra.copy(src, dest, { overwrite: true });
+}
+
+/**
+ * List immediate subdirectory names within a directory.
+ * Returns [] if the directory doesn't exist.
+ * @param {string} dirPath
+ * @returns {string[]}
+ */
+export function listDirs(dirPath) {
+  if (!fs.existsSync(dirPath)) return [];
+  return fs.readdirSync(dirPath, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name);
+}
+
+/**
+ * List immediate file names within a directory.
+ * Returns [] if the directory doesn't exist.
+ * @param {string} dirPath
+ * @returns {string[]}
+ */
+export function listFiles(dirPath) {
+  if (!fs.existsSync(dirPath)) return [];
+  return fs.readdirSync(dirPath, { withFileTypes: true })
+    .filter(d => d.isFile())
+    .map(d => d.name);
+}
+
+/**
+ * Check if a file or directory exists.
+ * @param {string} p
+ * @returns {boolean}
+ */
+export function fileExists(p) {
+  return fs.existsSync(p);
+}

package/src/utils/logger.js

@@ -0,0 +1,17 @@
+export const log = {
+  info(msg) {
+    console.log(msg);
+  },
+  success(msg) {
+    console.log(`[ok] ${msg}`);
+  },
+  warn(msg) {
+    console.warn(`[warn] ${msg}`);
+  },
+  error(msg) {
+    console.error(`[error] ${msg}`);
+  },
+  dryRun(msg) {
+    console.log(`[dry-run] ${msg}`);
+  },
+};

package/src/utils/pathResolver.js

@@ -0,0 +1,40 @@
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Expands ~, %VAR% (Windows), ${VAR}, and ${env:VAR} in a path string,
+ * then normalizes the result.
+ * @param {string} p
+ * @returns {string}
+ */
+export function resolvePath(p) {
+  if (typeof p !== 'string') return p;
+
+  let result = p;
+
+  // Expand ~ to home directory
+  if (result.startsWith('~/') || result === '~') {
+    result = path.join(os.homedir(), result.slice(1));
+  }
+
+  // Expand ${env:VAR} — must come before ${VAR} to avoid partial matches
+  result = result.replace(/\$\{env:([^}]+)\}/g, (_, name) => process.env[name] ?? '');
+
+  // Expand ${VAR}
+  result = result.replace(/\$\{([^}]+)\}/g, (_, name) => process.env[name] ?? '');
+
+  // Expand %VAR% (Windows style)
+  result = result.replace(/%([^%]+)%/g, (_, name) => process.env[name] ?? '');
+
+  return path.normalize(result);
+}
+
+/**
+ * Returns the registry root directory.
+ * Respects AWM_REGISTRY env var override.
+ * @returns {string}
+ */
+export function getRegistryRoot() {
+  return process.env.AWM_REGISTRY
+    ?? path.join(os.homedir(), '.agent-workspace', 'registry');
+}

package/src/utils/validator.js

@@ -0,0 +1,68 @@
+const VALID_TRANSPORTS = ['stdio', 'sse', 'http'];
+const VALID_SCOPES = ['project', 'global'];
+
+/**
+ * Validate an MCP server definition.
+ * Returns { valid: boolean, errors: string[] }
+ * @param {any} mcp
+ */
+export function validateMcp(mcp) {
+  const errors = [];
+  if (!mcp || typeof mcp !== 'object') {
+    return { valid: false, errors: ['MCP definition must be an object'] };
+  }
+  if (!mcp.id || typeof mcp.id !== 'string') {
+    errors.push('MCP requires a string "id" field');
+  }
+  if (!mcp.transport || !VALID_TRANSPORTS.includes(mcp.transport)) {
+    errors.push(`MCP requires "transport" to be one of: ${VALID_TRANSPORTS.join(', ')}`);
+  }
+  if (!mcp.command || typeof mcp.command !== 'string') {
+    errors.push('MCP requires a string "command" field');
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate a profile definition.
+ * Returns { valid: boolean, errors: string[] }
+ * @param {any} profile
+ */
+export function validateProfile(profile) {
+  const errors = [];
+  if (!profile || typeof profile !== 'object') {
+    return { valid: false, errors: ['Profile definition must be an object'] };
+  }
+  if (!profile.id || typeof profile.id !== 'string') {
+    errors.push('Profile requires a string "id" field');
+  }
+  if (!profile.tool || typeof profile.tool !== 'string') {
+    errors.push('Profile requires a string "tool" field');
+  }
+  if (!profile.scope || !VALID_SCOPES.includes(profile.scope)) {
+    errors.push(`Profile requires "scope" to be one of: ${VALID_SCOPES.join(', ')}`);
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate a tool definition.
+ * Returns { valid: boolean, errors: string[] }
+ * @param {any} tool
+ */
+export function validateToolDef(tool) {
+  const errors = [];
+  if (!tool || typeof tool !== 'object') {
+    return { valid: false, errors: ['Tool definition must be an object'] };
+  }
+  if (!tool.id || typeof tool.id !== 'string') {
+    errors.push('Tool definition requires a string "id" field');
+  }
+  if (!tool.name || typeof tool.name !== 'string') {
+    errors.push('Tool definition requires a string "name" field');
+  }
+  if (!tool.supports || typeof tool.supports !== 'object') {
+    errors.push('Tool definition requires a "supports" object');
+  }
+  return { valid: errors.length === 0, errors };
+}

package/src/workspace/applyWorkspace.js

@@ -0,0 +1,81 @@
+import path from 'node:path';
+import { log } from '../utils/logger.js';
+import { getMcp } from '../registry/mcpRegistry.js';
+import { listSkills } from '../registry/skillRegistry.js';
+import { loadTool } from '../registry/toolRegistry.js';
+import { applyMcpJson } from '../adapters/jsonAdapter.js';
+import { applyMcpToml } from '../adapters/tomlAdapter.js';
+import { applySkills } from '../adapters/skillApplier.js';
+import { resolvePath } from '../utils/pathResolver.js';
+
+/**
+ * Apply all MCPs and skills from a workspace config to every listed tool (project scope).
+ * @param {object} workspace
+ * @param {boolean} dryRun
+ */
+export async function applyAll(workspace, dryRun = false) {
+  const { tools = [], mcps: mcpIds = [], skills: skillNames = [] } = workspace;
+
+  // Validate all MCP refs first — collect all errors, abort before any writes
+  const errors = [];
+  const mcpDefs = [];
+  for (const id of mcpIds) {
+    const def = getMcp(id);
+    if (!def) {
+      errors.push(`MCP "${id}" not found in registry`);
+    } else {
+      mcpDefs.push(def);
+    }
+  }
+
+  const registeredSkills = listSkills();
+  for (const name of skillNames) {
+    if (!registeredSkills.includes(name)) {
+      errors.push(`Skill "${name}" not found in registry`);
+    }
+  }
+
+  if (errors.length > 0) {
+    for (const e of errors) log.error(e);
+    throw new Error('Aborting apply due to missing registry entries');
+  }
+
+  // Apply to each tool (project scope only)
+  for (const toolId of tools) {
+    const tool = loadTool(toolId);
+    if (!tool) {
+      log.warn(`Tool "${toolId}" not found — skipping`);
+      continue;
+    }
+
+    const mcpConfig = tool.mcp?.project;
+    if (!mcpConfig) {
+      log.warn(`Tool "${toolId}" has no project MCP config — skipping MCPs`);
+    } else {
+      const targetFile = path.join(process.cwd(), mcpConfig.targetFile);
+      const format = tool.mcp.format;
+      if (format === 'toml') {
+        await applyMcpToml(targetFile, mcpConfig.rootObject, mcpDefs, dryRun);
+      } else {
+        await applyMcpJson(targetFile, mcpConfig.rootObject, mcpDefs, dryRun);
+      }
+    }
+
+    // Apply skills if tool supports them
+    if (tool.supports?.skills && skillNames.length > 0) {
+      const skillsConfig = tool.skills?.project;
+      if (!skillsConfig) {
+        log.warn(`Tool "${toolId}" has no project skills config — skipping skills`);
+      } else {
+        const targetFolder = path.join(process.cwd(), skillsConfig.targetFolder);
+        await applySkills(skillNames, targetFolder, dryRun);
+      }
+    }
+  }
+
+  if (!dryRun && (mcpDefs.length > 0 || skillNames.length > 0)) {
+    log.success(`Applied to tools: ${tools.join(', ')}`);
+    if (mcpDefs.length > 0) log.info(`  MCPs: ${mcpDefs.map(m => m.id).join(', ')}`);
+    if (skillNames.length > 0) log.info(`  Skills: ${skillNames.join(', ')}`);
+  }
+}

package/src/workspace/workspaceConfig.js

@@ -0,0 +1,34 @@
+import path from 'node:path';
+import { readJson, writeJson } from '../utils/fileUtils.js';
+
+export function getWorkspacePath() {
+  return path.join(process.cwd(), '.awm.json');
+}
+
+/**
+ * Read .awm.json from cwd. Returns null if not found.
+ * @returns {object|null}
+ */
+export function readWorkspace() {
+  return readJson(getWorkspacePath());
+}
+
+/**
+ * Write .awm.json to cwd, updating lastSync timestamp.
+ * @param {object} ws
+ */
+export function writeWorkspace(ws) {
+  writeJson(getWorkspacePath(), { ...ws, lastSync: new Date().toISOString() });
+}
+
+/**
+ * Read .awm.json or throw a helpful error if missing.
+ * @returns {object}
+ */
+export function requireWorkspace() {
+  const ws = readWorkspace();
+  if (!ws) {
+    throw new Error('No .awm.json found in current directory. Run "awm init" first.');
+  }
+  return ws;
+}