@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

package/dist/src/mcp/elicitation.mjs

@@ -0,0 +1,149 @@
+/**
+ * MCP elicitation helpers.
+ *
+ * Emit structured single/multi-select forms when the connected client supports
+ * MCP form elicitation, with a graceful markdown fallback otherwise. This is the
+ * stable path for agent-initiated structured questions on Codex, whose native
+ * `request_user_input` tool is mode-gated and off by default (see #1668, #1676
+ * and the native-ux-tools rule).
+ *
+ * @implements #1676
+ * @see agentic/code/addons/aiwg-utils/rules/native-ux-tools.md
+ */
+
+/**
+ * Normalize loosely-typed options into `{ value, label }` pairs.
+ * Accepts plain strings or `{ label, value? }` objects.
+ * @param {Array<string | { value?: string, label: string }>} options
+ * @returns {Array<{ value: string, label: string }>}
+ */
+export function normalizeOptions(options) {
+  return (options || []).map((o, i) => {
+    if (typeof o === 'string') return { value: o, label: o };
+    const label = o.label ?? o.value ?? String(i);
+    const value = o.value ?? o.label ?? String(i);
+    return { value, label };
+  });
+}
+
+/**
+ * True when the connected client advertises MCP form elicitation support.
+ * @param {{ server?: { getClientCapabilities?: () => any } }} mcpServer
+ * @returns {boolean}
+ */
+export function clientSupportsFormElicitation(mcpServer) {
+  try {
+    const caps = mcpServer?.server?.getClientCapabilities?.();
+    return Boolean(caps?.elicitation?.form);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build a restricted JSON-schema (MCP elicitation `requestedSchema`) for a
+ * single- or multi-select choice over the given options.
+ * @param {object} params
+ * @returns {{ requestedSchema: object, key: string, options: Array<{value:string,label:string}> }}
+ */
+export function buildChoiceSchema({
+  key = 'choice',
+  title,
+  description,
+  options,
+  multiSelect = false,
+  minItems,
+  maxItems,
+}) {
+  const opts = normalizeOptions(options);
+  let prop;
+  if (multiSelect) {
+    prop = {
+      type: 'array',
+      ...(title ? { title } : {}),
+      ...(description ? { description } : {}),
+      items: { anyOf: opts.map((o) => ({ const: o.value, title: o.label })) },
+      ...(minItems != null ? { minItems } : {}),
+      ...(maxItems != null ? { maxItems } : {}),
+    };
+  } else {
+    prop = {
+      type: 'string',
+      ...(title ? { title } : {}),
+      ...(description ? { description } : {}),
+      oneOf: opts.map((o) => ({ const: o.value, title: o.label })),
+    };
+  }
+  return {
+    requestedSchema: {
+      type: 'object',
+      properties: { [key]: prop },
+      required: [key],
+    },
+    key,
+    options: opts,
+  };
+}
+
+/**
+ * Ask the user a single- or multi-select question via MCP elicitation.
+ *
+ * Returns `{ supported: false }` when the client has no form-elicitation support
+ * (caller should fall back to a markdown prompt). When supported, returns the
+ * outcome with `action` of `accept` (plus `value`), `decline`, or `cancel`.
+ * Never throws — any transport/capability error degrades to `{ supported: false }`.
+ *
+ * @param {{ server: { elicitInput: Function, getClientCapabilities?: Function } }} mcpServer
+ * @param {object} params
+ * @returns {Promise<{ supported: boolean, action?: string, value?: any, options: Array<{value:string,label:string}> }>}
+ */
+export async function elicitChoice(
+  mcpServer,
+  { question, options, multiSelect = false, key = 'choice', title, description, minItems, maxItems },
+) {
+  const { requestedSchema, options: opts } = buildChoiceSchema({
+    key,
+    title: title ?? question,
+    description,
+    options,
+    multiSelect,
+    minItems,
+    maxItems,
+  });
+
+  if (!clientSupportsFormElicitation(mcpServer)) {
+    return { supported: false, options: opts };
+  }
+
+  try {
+    const result = await mcpServer.server.elicitInput({
+      message: question,
+      requestedSchema,
+      mode: 'form',
+    });
+    const action = result?.action;
+    if (action === 'accept') {
+      return { supported: true, action, value: result?.content?.[key], options: opts };
+    }
+    return { supported: true, action: action === 'decline' ? 'decline' : 'cancel', options: opts };
+  } catch {
+    // Capability mismatch or transport error — degrade to markdown fallback.
+    return { supported: false, options: opts };
+  }
+}
+
+/**
+ * Render a clear markdown prompt for clients without native elicitation.
+ * @param {object} params
+ * @returns {string}
+ */
+export function renderMarkdownPrompt({ question, options, multiSelect = false }) {
+  const opts = normalizeOptions(options);
+  const lines = [`**${question}**`, ''];
+  for (const o of opts) {
+    lines.push(o.label === o.value ? `- \`${o.value}\`` : `- ${o.label} (\`${o.value}\`)`);
+  }
+  lines.push('');
+  lines.push(multiSelect ? '_Select one or more and reply with your choices._' : '_Reply with your choice._');
+  return lines.join('\n');
+}

package/dist/src/mcp/helpers.mjs

@@ -0,0 +1,287 @@
+/**
+ * AIWG MCP Server — Shared Helpers
+ *
+ * @architecture @.aiwg/architecture/sketch-hermes-mcp-parity.md
+ * @issues #1311 (scope split), #1312 (command-run), #1313 (discover + pairs)
+ */
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Resolve AIWG_ROOT, with safe fallback to known install locations.
+ */
+export const AIWG_ROOT = process.env.AIWG_ROOT ||
+  path.join(process.env.HOME || '', '.local/share/ai-writing-guide');
+
+const PROJECT_AIWG_LOCATION_FILE = '.aiwg-location';
+const ARTIFACT_PATH_ENV_ALIASES = [
+  'AIWG_ARTIFACTS_PATH',
+  'AIWG_PROJECT_ARTIFACTS_PATH',
+  'AIWG_PROJECT_AIWG_DIR',
+];
+
+function expandProjectArtifactPath(pathValue, projectDir) {
+  const trimmed = pathValue.trim();
+  if (trimmed === '~') return process.env.HOME || trimmed;
+  if (trimmed.startsWith('~/')) return path.resolve(process.env.HOME || '', trimmed.slice(2));
+  if (path.isAbsolute(trimmed)) return trimmed;
+  return path.resolve(projectDir, trimmed);
+}
+
+function parseProjectArtifactLocation(contents) {
+  for (const rawLine of contents.split(/\r?\n/)) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    if (line.startsWith('export ')) line = line.slice('export '.length).trim();
+    const assignment = line.match(/^AIWG_ARTIFACTS_PATH\s*=\s*(.+)$/);
+    if (assignment) line = assignment[1].trim();
+    if (
+      (line.startsWith('"') && line.endsWith('"')) ||
+      (line.startsWith("'") && line.endsWith("'"))
+    ) {
+      line = line.slice(1, -1);
+    }
+    return line || null;
+  }
+  return null;
+}
+
+export async function resolveProjectAiwgDir(projectDir) {
+  for (const key of ARTIFACT_PATH_ENV_ALIASES) {
+    const value = process.env[key];
+    if (typeof value === 'string' && value.trim()) return expandProjectArtifactPath(value, projectDir);
+  }
+  try {
+    const pointer = await fs.readFile(path.join(projectDir, PROJECT_AIWG_LOCATION_FILE), 'utf-8');
+    const configured = parseProjectArtifactLocation(pointer);
+    if (configured) return expandProjectArtifactPath(configured, projectDir);
+  } catch {
+    // no pointer
+  }
+  return path.resolve(projectDir, '.aiwg');
+}
+
+/**
+ * Walk up the directory tree looking for `.aiwg/` or `.aiwg-location`.
+ *
+ * @param {string} startDir
+ * @returns {Promise<string>}
+ * @throws {Error} when no .aiwg directory or .aiwg-location pointer is found
+ */
+export async function findProjectRoot(startDir = process.cwd()) {
+  let currentDir = startDir;
+  while (currentDir !== path.dirname(currentDir)) {
+    const aiwgPath = path.join(currentDir, '.aiwg');
+    const pointerPath = path.join(currentDir, PROJECT_AIWG_LOCATION_FILE);
+    try {
+      const stat = await fs.stat(aiwgPath);
+      if (stat.isDirectory()) return currentDir;
+    } catch {
+      // continue to pointer check
+    }
+    try {
+      const stat = await fs.stat(pointerPath);
+      if (stat.isFile()) return currentDir;
+    } catch {
+      // continue up
+    }
+    currentDir = path.dirname(currentDir);
+  }
+  throw new Error('No .aiwg directory or .aiwg-location pointer found. Run from an AIWG project or `aiwg new` first.');
+}
+
+/**
+ * Resolve project root with optional global fallback (#1311).
+ *
+ * Tools that operate on global registries (discover, *-show against the
+ * canonical corpus) accept a missing project root and fall back to AIWG_ROOT.
+ * Tools that operate on `.aiwg/` artifacts (artifact-read, memory-*) reject
+ * with a structured remediation message.
+ *
+ * @param {string|undefined} explicitDir
+ * @param {{ allowGlobal?: boolean, toolName?: string }} [options]
+ * @returns {Promise<{ root: string, isGlobal: boolean }>}
+ */
+export async function resolveProjectRoot(explicitDir, { allowGlobal = false, toolName = 'tool' } = {}) {
+  if (explicitDir && explicitDir !== '.') {
+    return { root: path.resolve(explicitDir), isGlobal: false };
+  }
+  try {
+    const root = await findProjectRoot();
+    return { root, isGlobal: false };
+  } catch (err) {
+    if (allowGlobal) {
+      return { root: AIWG_ROOT, isGlobal: true };
+    }
+    throw new Error(
+      `Tool "${toolName}" requires a project root. ${err.message} ` +
+      `Remediation: Run from an AIWG project directory or pass project_dir explicitly.`
+    );
+  }
+}
+
+/**
+ * The set of MCP tools that are allowed to operate without a project root
+ * (they fall back to AIWG_ROOT). Maintained here so tool registrations
+ * stay in sync (#1311).
+ */
+export const GLOBAL_ALLOWED_TOOLS = new Set([
+  'discover',
+  'skill-list',
+  'skill-show',
+  'command-list',
+  'command-show',
+  'rule-list',
+  'rule-show',
+  'agent-list',  // existing; canonical corpus enumeration
+  'agent-show',
+  'template-list',
+  'template-show',
+  'template-render',  // existing; uses corpus templates
+]);
+
+export function isGlobalAllowed(toolName) {
+  return GLOBAL_ALLOWED_TOOLS.has(toolName);
+}
+
+/**
+ * Spawn the `aiwg` CLI as a subprocess with safe argv handling (#1312).
+ *
+ * NEVER use `shell: true` — args must pass as an array so user-provided
+ * strings are never interpreted as shell metacharacters. Token security
+ * (RULES: token-security) — command path is logged, args content is not.
+ *
+ * @param {string[]} args
+ * @param {{ cwd?: string, env?: object, timeoutMs?: number, input?: string }} [options]
+ * @returns {Promise<{ stdout: string, stderr: string, code: number }>}
+ */
+export function runAiwgCli(args, { cwd, env, timeoutMs = 120_000, input } = {}) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('aiwg', args, {
+      shell: false,
+      cwd: cwd || process.cwd(),
+      env: { ...process.env, ...(env || {}) },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      proc.kill('SIGTERM');
+    }, timeoutMs);
+
+    proc.stdout.on('data', (chunk) => { stdout += chunk; });
+    proc.stderr.on('data', (chunk) => { stderr += chunk; });
+
+    proc.on('close', (code) => {
+      clearTimeout(timer);
+      if (timedOut) {
+        reject(new Error(`aiwg ${args[0] || ''} timed out after ${timeoutMs}ms`));
+        return;
+      }
+      resolve({ stdout, stderr, code: code ?? -1 });
+    });
+    proc.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+
+    if (input !== undefined) {
+      proc.stdin.write(input);
+      proc.stdin.end();
+    } else {
+      proc.stdin.end();
+    }
+  });
+}
+
+/**
+ * Structured MCP error response.
+ */
+export function mcpError(message, { remediation, requiresConfirmation } = {}) {
+  const body = { error: message };
+  if (remediation) body.remediation = remediation;
+  if (requiresConfirmation) body.requires_confirmation = true;
+  return {
+    content: [{ type: 'text', text: JSON.stringify(body, null, 2) }],
+    isError: true,
+  };
+}
+
+/**
+ * Structured MCP success response wrapping a JSON or text payload.
+ */
+export function mcpJson(data) {
+  const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+  return { content: [{ type: 'text', text }] };
+}
+
+/**
+ * Read AIWG CLI command registry to build the command-run allow-list.
+ *
+ * Lazily loaded from `src/extensions/commands/definitions.ts` — extracts
+ * `id:` fields. Cached after first read.
+ */
+let _commandIds = null;
+export async function loadCommandAllowList() {
+  if (_commandIds) return _commandIds;
+  const defPath = path.join(AIWG_ROOT, 'src/extensions/commands/definitions.ts');
+  // Fall back to source-checkout location if AIWG_ROOT points to the project itself
+  const candidates = [
+    defPath,
+    path.resolve(process.cwd(), 'src/extensions/commands/definitions.ts'),
+  ];
+  let text = '';
+  for (const c of candidates) {
+    try {
+      text = await fs.readFile(c, 'utf-8');
+      break;
+    } catch {
+      // try next
+    }
+  }
+  if (!text) {
+    // Last-resort fallback: spawn `aiwg help` and parse — slower but always works
+    try {
+      const { stdout } = await runAiwgCli(['help'], { timeoutMs: 30_000 });
+      _commandIds = new Set(
+        Array.from(stdout.matchAll(/^\s{4}([a-z][a-z0-9-]+)\s/gm))
+          .map(m => m[1])
+      );
+      return _commandIds;
+    } catch (e) {
+      _commandIds = new Set();
+      return _commandIds;
+    }
+  }
+  const ids = new Set();
+  for (const m of text.matchAll(/^  id: '([^']+)'/gm)) {
+    ids.add(m[1]);
+  }
+  _commandIds = ids;
+  return _commandIds;
+}
+
+/**
+ * Commands that mutate fleet/project state and require explicit `confirmed: true`
+ * before `command-run` will execute them. Defensive default.
+ */
+export const DESTRUCTIVE_COMMANDS = new Set([
+  'remove',
+  'rollback-workspace',
+  'promote',
+  'uninstall-plugin',
+  'cleanup-audit',
+  'doc-sync',
+  'sandbox',  // local executor sandbox
+  'ralph',    // long-running loop
+  'agent-loop-ext',
+  'ralph-abort',
+]);
+
+export function isDestructive(command) {
+  return DESTRUCTIVE_COMMANDS.has(command);
+}

package/dist/src/mcp/index.mjs

@@ -0,0 +1,11 @@
+/**
+ * AIWG MCP Module
+ *
+ * Exports for the AIWG MCP server implementation.
+ *
+ * @module src/mcp
+ * @version 1.0.0
+ */
+
+export { createServer, startServer } from './server.mjs';
+export { main as cli } from './cli.mjs';