@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/mcp/test-simple.mjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+
+/**
+ * Simple AIWG MCP Server Test
+ *
+ * Tests the server by spawning it and sending JSON-RPC messages via stdio.
+ */
+
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import readline from 'readline';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+let messageId = 1;
+
+function createMessage(method, params = {}) {
+  return JSON.stringify({
+    jsonrpc: '2.0',
+    id: messageId++,
+    method,
+    params
+  });
+}
+
+async function main() {
+  console.log('='.repeat(60));
+  console.log('AIWG MCP Server Simple Test');
+  console.log('='.repeat(60));
+  console.log('');
+
+  // Spawn the server
+  const server = spawn('node', [path.join(__dirname, 'server.mjs')], {
+    stdio: ['pipe', 'pipe', 'pipe']
+  });
+
+  let responses = [];
+  let rl = readline.createInterface({ input: server.stdout });
+
+  rl.on('line', (line) => {
+    try {
+      const msg = JSON.parse(line);
+      responses.push(msg);
+    } catch (e) {
+      // Not JSON, might be a log message
+    }
+  });
+
+  server.stderr.on('data', (data) => {
+    console.log('[Server]', data.toString().trim());
+  });
+
+  // Wait for server to start
+  await new Promise(resolve => setTimeout(resolve, 1000));
+
+  const tests = [];
+  let passed = 0;
+  let failed = 0;
+
+  async function sendAndWait(method, params = {}, timeout = 5000) {
+    const msg = createMessage(method, params);
+    const id = messageId - 1;
+
+    server.stdin.write(msg + '\n');
+
+    // Wait for response with matching ID
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+      const response = responses.find(r => r.id === id);
+      if (response) {
+        responses = responses.filter(r => r.id !== id);
+        return response;
+      }
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+    throw new Error(`Timeout waiting for response to ${method}`);
+  }
+
+  async function test(name, fn) {
+    try {
+      await fn();
+      console.log(`✓ ${name}`);
+      passed++;
+    } catch (error) {
+      console.log(`✗ ${name}`);
+      console.log(`  Error: ${error.message}`);
+      failed++;
+    }
+  }
+
+  // Initialize the connection
+  await test('Initialize connection', async () => {
+    const response = await sendAndWait('initialize', {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: {
+        name: 'test-client',
+        version: '1.0.0'
+      }
+    });
+
+    if (response.error) {
+      throw new Error(response.error.message);
+    }
+    if (!response.result.serverInfo) {
+      throw new Error('No serverInfo in response');
+    }
+    console.log(`  Server: ${response.result.serverInfo.name} v${response.result.serverInfo.version}`);
+  });
+
+  // Send initialized notification
+  server.stdin.write(JSON.stringify({
+    jsonrpc: '2.0',
+    method: 'notifications/initialized'
+  }) + '\n');
+
+  await new Promise(resolve => setTimeout(resolve, 500));
+
+  // List tools
+  await test('List tools', async () => {
+    const response = await sendAndWait('tools/list', {});
+    if (response.error) {
+      throw new Error(response.error.message);
+    }
+    const tools = response.result.tools;
+    if (!tools || tools.length === 0) {
+      throw new Error('No tools returned');
+    }
+    const names = tools.map(t => t.name);
+    if (!names.includes('command-run')) {
+      throw new Error('Expected command-run in core tools');
+    }
+    if (names.includes('workflow-run')) {
+      throw new Error('workflow-run should not be registered');
+    }
+    console.log(`  Found ${tools.length} tools: ${tools.map(t => t.name).join(', ')}`);
+  });
+
+  // List resources
+  await test('List resources', async () => {
+    const response = await sendAndWait('resources/list', {});
+    if (response.error) {
+      throw new Error(response.error.message);
+    }
+    const resources = response.result.resources;
+    console.log(`  Found ${resources?.length || 0} resources`);
+  });
+
+  // List prompts
+  await test('List prompts', async () => {
+    const response = await sendAndWait('prompts/list', {});
+    if (response.error) {
+      throw new Error(response.error.message);
+    }
+    const prompts = response.result.prompts;
+    if (!prompts || prompts.length === 0) {
+      throw new Error('No prompts returned');
+    }
+    console.log(`  Found ${prompts.length} prompts: ${prompts.map(p => p.name).join(', ')}`);
+  });
+
+  // Call agent-list tool
+  await test('Call agent-list tool', async () => {
+    const response = await sendAndWait('tools/call', {
+      name: 'agent-list',
+      arguments: {
+        framework: 'all'
+      }
+    });
+    if (response.error) {
+      throw new Error(response.error.message);
+    }
+    const content = response.result.content[0].text;
+    const parsed = JSON.parse(content);
+    console.log(`  Found ${parsed.count} agents`);
+  });
+
+  // Test artifact-write and artifact-read
+  await test('Write and read artifact', async () => {
+    const testContent = `# Test Artifact\nCreated: ${new Date().toISOString()}`;
+
+    // Write
+    const writeResponse = await sendAndWait('tools/call', {
+      name: 'artifact-write',
+      arguments: {
+        path: 'working/mcp-test-artifact.md',
+        content: testContent,
+        project_dir: '.'
+      }
+    });
+    if (writeResponse.error) {
+      throw new Error(writeResponse.error.message);
+    }
+    const writeResult = JSON.parse(writeResponse.result.content[0].text);
+    if (writeResult.status !== 'success') {
+      throw new Error('Write failed');
+    }
+
+    // Read back
+    const readResponse = await sendAndWait('tools/call', {
+      name: 'artifact-read',
+      arguments: {
+        path: 'working/mcp-test-artifact.md',
+        project_dir: '.'
+      }
+    });
+    if (readResponse.error) {
+      throw new Error(readResponse.error.message);
+    }
+    const readContent = readResponse.result.content[0].text;
+    if (!readContent.includes('Test Artifact')) {
+      throw new Error('Read content does not match');
+    }
+    console.log('  Write and read successful');
+  });
+
+  // Test reading from test fixture project
+  await test('Read artifact from test project', async () => {
+    const response = await sendAndWait('tools/call', {
+      name: 'artifact-read',
+      arguments: {
+        path: 'requirements/UC-001-create-task.md',
+        project_dir: 'test/fixtures/mcp-test-project'
+      }
+    });
+    if (response.error) {
+      throw new Error(response.error.message);
+    }
+    const content = response.result.content[0].text;
+    if (!content.includes('UC-001: Create Task')) {
+      throw new Error('Expected UC-001 content');
+    }
+    console.log('  Read UC-001 from test project');
+  });
+
+  // Get decompose-task prompt
+  await test('Get decompose-task prompt', async () => {
+    const response = await sendAndWait('prompts/get', {
+      name: 'decompose-task',
+      arguments: {
+        task: 'Build authentication system',
+        max_subtasks: '5'  // MCP passes all args as strings
+      }
+    });
+    if (response.error) {
+      throw new Error(response.error.message);
+    }
+    const messages = response.result.messages;
+    if (!messages || messages.length === 0) {
+      throw new Error('No messages returned');
+    }
+    console.log(`  Prompt has ${messages.length} messages`);
+  });
+
+  // Cleanup
+  server.kill();
+
+  // Summary
+  console.log('');
+  console.log('='.repeat(60));
+  console.log(`Results: ${passed} passed, ${failed} failed`);
+  console.log('='.repeat(60));
+
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+main().catch(error => {
+  console.error('Test failed:', error);
+  process.exit(1);
+});

package/dist/src/mcp/tools/command-run.mjs

@@ -0,0 +1,101 @@
+/**
+ * AIWG MCP Tool: aiwg-command-run
+ *
+ * Single dispatch MCP tool that routes to the ~94 AIWG CLI commands.
+ * Replaces the `workflow-run` stub.
+ *
+ * Security model:
+ *   - Allow-list validated against `src/extensions/commands/definitions.ts`
+ *     (loaded lazily at first call)
+ *   - `args` is a string array — passed as argv, never shell-interpreted
+ *   - `shell: false` enforced in spawn
+ *   - Destructive commands require `confirmed: true`
+ *
+ * @architecture @.aiwg/architecture/sketch-hermes-mcp-parity.md DD-4
+ * @issues #1312 (S1)
+ * @rules @token-security, @anti-laziness
+ */
+
+import { z } from 'zod';
+import {
+  runAiwgCli,
+  loadCommandAllowList,
+  isDestructive,
+  mcpError,
+  mcpJson,
+} from '../helpers.mjs';
+
+export function registerCommandRunTool(server) {
+  server.registerTool('command-run', {
+    title: 'Run AIWG CLI Command',
+    description: 'Dispatch to any allow-listed AIWG CLI command (`aiwg <command> [args...]`). The full surface of ~94 commands is reachable. Destructive commands require `confirmed: true`.',
+    inputSchema: {
+      command: z.string().describe('Command name from `command-list` (e.g. "use", "discover", "doctor")'),
+      args: z.array(z.string()).default([]).describe('Argument array (never shell-interpreted)'),
+      project_dir: z.string().optional().describe('Working directory for the command'),
+      confirmed: z.boolean().default(false).describe('Required for destructive commands (true to proceed)'),
+      timeout_ms: z.number().int().min(1000).max(600_000).default(120_000).describe('Timeout (1s–10min, default 2min)'),
+    },
+    annotations: {
+      destructiveHint: true,  // conservative default; many subcommands are read-only but the surface is broad
+      openWorldHint: true,    // touches filesystem and project state
+    },
+  }, async ({ command, args, project_dir, confirmed, timeout_ms }) => {
+    try {
+      // 1. Allow-list validation
+      const allowList = await loadCommandAllowList();
+      if (allowList.size === 0) {
+        return mcpError(
+          'command-run: cannot load command allow-list from AIWG_ROOT. ' +
+          'AIWG installation may be incomplete.',
+          { remediation: 'Run `aiwg doctor` to verify AIWG_ROOT is set correctly.' }
+        );
+      }
+      if (!allowList.has(command)) {
+        return mcpError(
+          `command-run: command "${command}" not in allow-list.`,
+          { remediation: 'Call `command-list` (or `discover --type command`) to see available commands.' }
+        );
+      }
+
+      // 2. Destructive-op gate
+      if (isDestructive(command) && !confirmed) {
+        return mcpError(
+          `command-run: "${command}" is a destructive command. Re-invoke with confirmed=true to proceed.`,
+          {
+            remediation: 'Set confirmed=true after surfacing the impact to the user.',
+            requiresConfirmation: true,
+          }
+        );
+      }
+
+      // 3. Argument sanity (no shell metacharacters smuggled via array elements
+      // — these are passed as argv so they're safe, but reject NUL bytes which
+      // would truncate argv at the OS level)
+      for (const a of args) {
+        if (typeof a !== 'string' || a.includes('\0')) {
+          return mcpError('command-run: invalid argument (NUL byte or non-string)');
+        }
+      }
+
+      // 4. Log path only — never log the args content (token-security)
+      console.error(`[AIWG MCP] command-run: aiwg ${command} (${args.length} args)`);
+
+      // 5. Spawn with shell: false (runAiwgCli enforces this)
+      const { stdout, stderr, code } = await runAiwgCli(
+        [command, ...args],
+        { cwd: project_dir, timeoutMs: timeout_ms }
+      );
+
+      return mcpJson({
+        command,
+        exit_code: code,
+        stdout,
+        stderr,
+        confirmed,
+      });
+    } catch (err) {
+      return mcpError(`command-run: ${err.message}`);
+    }
+  });
+}

package/dist/src/mcp/tools/discovery.mjs

@@ -0,0 +1,291 @@
+/**
+ * AIWG MCP Discovery Tools
+ *
+ * Bridges the post-#1212 discoverability surface (`aiwg discover`,
+ * `aiwg show`) into MCP. Adds 8 new tools:
+ *
+ *   - discover          (cross-type ranked search)
+ *   - skill-list        (enumerate canonical skill corpus)
+ *   - skill-show        (fetch SKILL.md body)
+ *   - command-list      (enumerate CLI commands)
+ *   - command-show      (fetch command definition)
+ *   - rule-list         (enumerate rules)
+ *   - rule-show         (fetch rule body)
+ *   - agent-show        (fetch agent definition; agent-list pre-exists)
+ *   - template-list     (enumerate templates)
+ *   - template-show     (fetch raw template body)
+ *
+ * All are global-allowed (#1311) — work without a project root.
+ *
+ * @architecture @.aiwg/architecture/sketch-hermes-mcp-parity.md
+ * @issues #1311 (scope split), #1313 (discover + pairs), #1320 (rule-list/show)
+ */
+
+import { z } from 'zod';
+import { runAiwgCli, mcpError, mcpJson, AIWG_ROOT } from '../helpers.mjs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Register discovery tools on the MCP server.
+ *
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ */
+export function registerDiscoveryTools(server) {
+  // ============================================================
+  // discover — cross-type semantic search
+  // ============================================================
+  server.registerTool('discover', {
+    title: 'Discover AIWG Capabilities',
+    description: 'Semantic search across AIWG operational assets: skills, agents, commands, rules, flows, runbooks, templates, and behaviors. Returns ranked candidates with capability summaries. Mirrors `aiwg discover --json`.',
+    inputSchema: {
+      phrase: z.string().describe('Natural-language capability description (e.g. "create intake form")'),
+      type: z.enum(['skill', 'agent', 'command', 'rule', 'flow', 'runbook', 'template', 'behavior']).optional().describe('Restrict to one artifact type'),
+      limit: z.number().int().min(1).max(50).default(5).describe('Maximum results (default 5)'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  }, async ({ phrase, type, limit }) => {
+    try {
+      const args = ['discover', phrase, '--json', '--limit', String(limit ?? 5)];
+      if (type) args.push('--type', type);
+      const { stdout, stderr, code } = await runAiwgCli(args);
+      if (code !== 0) {
+        return mcpError(`aiwg discover failed (exit ${code}): ${stderr}`);
+      }
+      return mcpJson(stdout);
+    } catch (err) {
+      return mcpError(`discover: ${err.message}`);
+    }
+  });
+
+  // ============================================================
+  // skill-list / skill-show
+  // ============================================================
+  server.registerTool('skill-list', {
+    title: 'List AIWG Skills',
+    description: 'Enumerate available AIWG skills from the canonical corpus. Optional filter by name pattern.',
+    inputSchema: {
+      filter: z.string().optional().describe('Substring or glob filter on skill name'),
+      limit: z.number().int().min(1).max(500).default(50).describe('Maximum results'),
+    },
+    annotations: { readOnlyHint: true },
+  }, async ({ filter, limit }) => {
+    try {
+      const args = ['discover', filter || '', '--type', 'skill', '--json', '--limit', String(limit ?? 50)];
+      const { stdout, code, stderr } = await runAiwgCli(args);
+      if (code !== 0) return mcpError(`skill-list failed: ${stderr}`);
+      return mcpJson(stdout);
+    } catch (err) {
+      return mcpError(`skill-list: ${err.message}`);
+    }
+  });
+
+  server.registerTool('skill-show', {
+    title: 'Show AIWG Skill',
+    description: 'Fetch the full body of an AIWG SKILL.md by name. Returns path + content envelope.',
+    inputSchema: {
+      name: z.string().describe('Skill name (slug; e.g. "intake-wizard")'),
+    },
+    annotations: { readOnlyHint: true },
+  }, async ({ name }) => {
+    try {
+      const { stdout, code, stderr } = await runAiwgCli(['show', 'skill', name, '--json']);
+      if (code !== 0) return mcpError(`skill-show failed: ${stderr}`);
+      return mcpJson(stdout);
+    } catch (err) {
+      return mcpError(`skill-show: ${err.message}`);
+    }
+  });
+
+  // ============================================================
+  // command-list / command-show
+  // ============================================================
+  server.registerTool('command-list', {
+    title: 'List AIWG CLI Commands',
+    description: 'Enumerate available `aiwg <command>` CLI commands. The allow-list for `command-run`.',
+    inputSchema: {
+      filter: z.string().optional().describe('Substring filter on command name'),
+    },
+    annotations: { readOnlyHint: true },
+  }, async ({ filter }) => {
+    try {
+      const args = ['discover', filter || '', '--type', 'command', '--json', '--limit', '200'];
+      const { stdout, code, stderr } = await runAiwgCli(args);
+      if (code !== 0) return mcpError(`command-list failed: ${stderr}`);
+      return mcpJson(stdout);
+    } catch (err) {
+      return mcpError(`command-list: ${err.message}`);
+    }
+  });
+
+  server.registerTool('command-show', {
+    title: 'Show AIWG CLI Command Definition',
+    description: 'Fetch the full spec/help text for a specific `aiwg` CLI command.',
+    inputSchema: {
+      name: z.string().describe('Command name (e.g. "use", "discover", "ralph")'),
+    },
+    annotations: { readOnlyHint: true },
+  }, async ({ name }) => {
+    try {
+      const { stdout, code, stderr } = await runAiwgCli(['show', 'command', name, '--json']);
+      if (code !== 0) return mcpError(`command-show failed: ${stderr}`);
+      return mcpJson(stdout);
+    } catch (err) {
+      return mcpError(`command-show: ${err.message}`);
+    }
+  });
+
+  // ============================================================
+  // rule-list / rule-show  (#1320)
+  // ============================================================
+  server.registerTool('rule-list', {
+    title: 'List AIWG Rules',
+    description: 'Enumerate AIWG enforcement rules (e.g. skill-discovery, no-attribution, anti-laziness, citation-policy). Top-7 CRITICAL/HIGH rules are inlined into Hermes AGENTS.md priming (skill-discovery added #1347); this tool reaches the rest.',
+    inputSchema: {
+      filter: z.string().optional().describe('Substring filter on rule name'),
+      limit: z.number().int().min(1).max(200).default(50),
+    },
+    annotations: { readOnlyHint: true },
+  }, async ({ filter, limit }) => {
+    try {
+      const args = ['discover', filter || '', '--type', 'rule', '--json', '--limit', String(limit ?? 50)];
+      const { stdout, code, stderr } = await runAiwgCli(args);
+      if (code !== 0) return mcpError(`rule-list failed: ${stderr}`);
+      return mcpJson(stdout);
+    } catch (err) {
+      return mcpError(`rule-list: ${err.message}`);
+    }
+  });
+
+  server.registerTool('rule-show', {
+    title: 'Show AIWG Rule',
+    description: 'Fetch the full body of a specific AIWG rule by name.',
+    inputSchema: {
+      name: z.string().describe('Rule name (e.g. "no-attribution", "anti-laziness")'),
+    },
+    annotations: { readOnlyHint: true },
+  }, async ({ name }) => {
+    try {
+      const { stdout, code, stderr } = await runAiwgCli(['show', 'rule', name, '--json']);
+      if (code !== 0) return mcpError(`rule-show failed: ${stderr}`);
+      return mcpJson(stdout);
+    } catch (err) {
+      return mcpError(`rule-show: ${err.message}`);
+    }
+  });
+
+  // ============================================================
+  // agent-show  (agent-list pre-exists in server.mjs)
+  // ============================================================
+  server.registerTool('agent-show', {
+    title: 'Show AIWG Agent Definition',
+    description: 'Fetch the full agent definition (system prompt + frontmatter) by name.',
+    inputSchema: {
+      name: z.string().describe('Agent name (e.g. "test-engineer", "security-auditor")'),
+    },
+    annotations: { readOnlyHint: true },
+  }, async ({ name }) => {
+    try {
+      const { stdout, code, stderr } = await runAiwgCli(['show', 'agent', name, '--json']);
+      if (code !== 0) return mcpError(`agent-show failed: ${stderr}`);
+      return mcpJson(stdout);
+    } catch (err) {
+      return mcpError(`agent-show: ${err.message}`);
+    }
+  });
+
+  // ============================================================
+  // template-list / template-show  (template-render pre-exists)
+  // ============================================================
+  server.registerTool('template-list', {
+    title: 'List AIWG Templates',
+    description: 'Enumerate AIWG document templates from the canonical corpus.',
+    inputSchema: {
+      framework: z.string().optional().describe('Restrict to one framework (e.g. "sdlc-complete")'),
+      filter: z.string().optional().describe('Substring filter on template name'),
+    },
+    annotations: { readOnlyHint: true },
+  }, async ({ framework, filter }) => {
+    try {
+      const results = await scanTemplates(AIWG_ROOT, { framework, filter });
+      return mcpJson({ count: results.length, templates: results });
+    } catch (err) {
+      return mcpError(`template-list: ${err.message}`);
+    }
+  });
+
+  server.registerTool('template-show', {
+    title: 'Show AIWG Template Body',
+    description: 'Fetch the raw body of a template (un-rendered). For variable substitution use `template-render`.',
+    inputSchema: {
+      template: z.string().describe('Template path (e.g. "sdlc-complete/analysis-design/adr-template.md")'),
+    },
+    annotations: { readOnlyHint: true },
+  }, async ({ template }) => {
+    try {
+      // Allow caller to pass either a corpus-relative path or just the template filename
+      const candidates = [
+        path.join(AIWG_ROOT, 'agentic/code/frameworks', template),
+        path.join(AIWG_ROOT, 'agentic/code/frameworks/sdlc-complete/templates', template),
+        path.resolve(template),
+      ];
+      for (const c of candidates) {
+        try {
+          // Anti-traversal: ensure resolved path stays inside AIWG_ROOT
+          const resolved = path.resolve(c);
+          if (!resolved.startsWith(path.resolve(AIWG_ROOT))) continue;
+          const content = await fs.readFile(resolved, 'utf-8');
+          return mcpJson({ path: resolved, content });
+        } catch {
+          // try next
+        }
+      }
+      return mcpError(`template not found: ${template}`);
+    } catch (err) {
+      return mcpError(`template-show: ${err.message}`);
+    }
+  });
+}
+
+/**
+ * Enumerate templates by walking the canonical corpus.
+ * Restricted to the AIWG_ROOT subtree (no .aiwg/ project artifacts).
+ */
+async function scanTemplates(aiwgRoot, { framework, filter } = {}) {
+  const results = [];
+  const root = path.join(aiwgRoot, 'agentic/code/frameworks');
+  let frameworks = [];
+  try {
+    frameworks = (await fs.readdir(root, { withFileTypes: true }))
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+  } catch {
+    return results;
+  }
+  for (const fw of frameworks) {
+    if (framework && fw !== framework) continue;
+    const tplRoot = path.join(root, fw, 'templates');
+    await walkTemplates(tplRoot, tplRoot, fw, results, filter);
+  }
+  return results;
+}
+
+async function walkTemplates(base, dir, framework, out, filter) {
+  let entries = [];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await walkTemplates(base, full, framework, out, filter);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      const rel = path.relative(base, full);
+      const name = entry.name.replace(/\.md$/, '');
+      if (filter && !name.includes(filter) && !rel.includes(filter)) continue;
+      out.push({ framework, name, relativePath: rel, path: full });
+    }
+  }
+}