sofia-cli 0.1.1

package/src/develop/githubMcpAdapter.ts

@@ -0,0 +1,199 @@
+/**
+ * GitHub MCP Adapter.
+ *
+ * Wraps GitHub MCP tool calls for PoC repository creation and file pushes.
+ * When GitHub MCP is unavailable, all methods degrade gracefully by returning
+ * `{ available: false }` or undefined.
+ *
+ * Contract: specs/002-poc-generation/contracts/poc-output.md (GitHub MCP integration)
+ */
+import type { McpManager } from '../mcp/mcpManager.js';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface CreateRepositoryOptions {
+  name: string;
+  description?: string;
+  private?: boolean;
+}
+
+export type CreateRepositoryResult =
+  | {
+      available: true;
+      repoUrl: string;
+      repoName: string;
+    }
+  | {
+      available: false;
+      reason?: string;
+    };
+
+export interface PushFilesOptions {
+  repoUrl: string;
+  files: Array<{ path: string; content: string }>;
+  commitMessage: string;
+  branch?: string;
+}
+
+export type PushFilesResult =
+  | {
+      available: true;
+      commitSha?: string;
+    }
+  | {
+      available: false;
+      reason?: string;
+    };
+
+// ── GitHubMcpAdapter ─────────────────────────────────────────────────────────
+
+/**
+ * Adapter for GitHub MCP repository operations.
+ *
+ * All methods check isAvailable() before attempting tool calls.
+ * On failure or unavailability, returns `{ available: false }` without throwing.
+ */
+export class GitHubMcpAdapter {
+  private readonly mcpManager: McpManager;
+  private _repoUrl: string | undefined;
+
+  constructor(mcpManager: McpManager) {
+    this.mcpManager = mcpManager;
+  }
+
+  /**
+   * Check if GitHub MCP is available.
+   */
+  isAvailable(): boolean {
+    return this.mcpManager.isAvailable('github');
+  }
+
+  /**
+   * Create a GitHub repository via MCP.
+   *
+   * Calls `mcpManager.callTool('github', 'create_repository', ...)` and parses
+   * the response for `html_url`. Returns `{ available: false }` if GitHub MCP
+   * is unavailable or if creation fails.
+   */
+  async createRepository(options: CreateRepositoryOptions): Promise<CreateRepositoryResult> {
+    if (!this.isAvailable()) {
+      return { available: false, reason: 'GitHub MCP not available' };
+    }
+
+    try {
+      const response = await this.mcpManager.callTool(
+        'github',
+        'create_repository',
+        {
+          name: options.name,
+          description: options.description ?? '',
+          private: options.private ?? true,
+        },
+        { timeoutMs: 60_000 },
+      );
+
+      const repoUrl =
+        (response.html_url as string) ?? (response.url as string) ?? (response.clone_url as string);
+      const repoName = (response.name as string) ?? (response.full_name as string) ?? options.name;
+
+      if (!repoUrl) {
+        return { available: false, reason: 'MCP response missing repository URL' };
+      }
+
+      this._repoUrl = repoUrl;
+
+      return {
+        available: true,
+        repoUrl,
+        repoName,
+      };
+    } catch (err: unknown) {
+      const reason = err instanceof Error ? err.message : 'Unknown error';
+      return { available: false, reason };
+    }
+  }
+
+  /**
+   * Push files to a GitHub repository via MCP.
+   *
+   * Calls `mcpManager.callTool('github', 'push_files', ...)` with file paths
+   * and contents. Returns `{ available: false }` if GitHub MCP is unavailable
+   * or if push fails.
+   */
+  async pushFiles(options: PushFilesOptions): Promise<PushFilesResult> {
+    if (!this.isAvailable()) {
+      return { available: false, reason: 'GitHub MCP not available' };
+    }
+
+    try {
+      // Extract owner and repo from repoUrl
+      const { owner, repo } = extractOwnerRepo(options.repoUrl);
+
+      const response = await this.mcpManager.callTool(
+        'github',
+        'push_files',
+        {
+          owner,
+          repo,
+          files: options.files,
+          message: options.commitMessage,
+          branch: options.branch ?? 'main',
+        },
+        { timeoutMs: 60_000 },
+      );
+
+      const commitSha =
+        (response.sha as string | undefined) ??
+        ((response.commit as Record<string, unknown> | undefined)?.sha as string | undefined);
+
+      return {
+        available: true,
+        commitSha,
+      };
+    } catch (err: unknown) {
+      const reason = err instanceof Error ? err.message : 'Unknown error';
+      return { available: false, reason };
+    }
+  }
+
+  /**
+   * Get the repository URL from the last successful createRepository call.
+   */
+  getRepoUrl(): string | undefined {
+    return this._repoUrl;
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Extract owner and repo from a GitHub repository URL.
+ * Supports formats like:
+ *   https://github.com/owner/repo
+ *   https://github.com/owner/repo.git
+ *   https://api.github.com/repos/owner/repo
+ */
+function extractOwnerRepo(repoUrl: string): { owner: string; repo: string } {
+  // Try github.com/{owner}/{repo} pattern
+  const ghMatch = repoUrl.match(/github\.com\/([^/]+)\/([^/.]+)/);
+  if (ghMatch) {
+    return { owner: ghMatch[1], repo: ghMatch[2] };
+  }
+
+  // Fallback: try api.github.com/repos/{owner}/{repo}
+  const apiMatch = repoUrl.match(/api\.github\.com\/repos\/([^/]+)\/([^/.]+)/);
+  if (apiMatch) {
+    return { owner: apiMatch[1], repo: apiMatch[2] };
+  }
+
+  // Last resort: try extracting last two path segments
+  const segments = new URL(repoUrl).pathname.split('/').filter(Boolean);
+  if (segments.length >= 2) {
+    return {
+      owner: segments[segments.length - 2],
+      repo: segments[segments.length - 1].replace('.git', ''),
+    };
+  }
+
+  throw new Error(`Cannot extract owner/repo from URL: ${repoUrl}`);
+}

package/src/develop/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Develop phase module.
+ *
+ * Exports all components of the PoC Generation & Ralph Loop feature (Feature 002).
+ * Orchestrates: scaffold → install → iterate (test → fix → repeat) → complete.
+ */
+
+export { PocScaffolder } from './pocScaffolder.js';
+export type { ScaffoldContext, ScaffoldResult } from './pocScaffolder.js';
+
+export { generateDynamicScaffold } from './dynamicScaffolder.js';
+export type { DynamicScaffoldContext, DynamicScaffoldResult } from './dynamicScaffolder.js';
+
+export { TestRunner } from './testRunner.js';
+
+export { CodeGenerator } from './codeGenerator.js';
+
+export { McpContextEnricher } from './mcpContextEnricher.js';
+
+export { GitHubMcpAdapter } from './githubMcpAdapter.js';
+
+export { RalphLoop } from './ralphLoop.js';
+export type { RalphLoopOptions, RalphLoopResult } from './ralphLoop.js';
+
+export { deriveCheckpointState } from './checkpointState.js';
+export type { CheckpointState } from './checkpointState.js';
+
+export {
+  selectTemplate,
+  createDefaultRegistry,
+  NODE_TS_VITEST_TEMPLATE,
+  PYTHON_PYTEST_TEMPLATE,
+} from './templateRegistry.js';
+export type { TemplateEntry, TemplateRegistry } from './templateRegistry.js';

package/src/develop/mcpContextEnricher.ts

@@ -0,0 +1,279 @@
+/**
+ * MCP Context Enricher.
+ *
+ * Conditionally queries MCP services to enrich the LLM iteration prompt
+ * with up-to-date library docs and architecture guidance:
+ *
+ * - Context7: library documentation for PoC dependencies
+ * - Azure MCP / Microsoft Docs: when plan references Azure services
+ * - web.search: when stuck (2+ consecutive iterations with same failures)
+ *
+ * All MCP queries degrade gracefully — returns empty context when unavailable.
+ *
+ * Contract: specs/002-poc-generation/tasks.md (T048/T049)
+ */
+import type { McpManager } from '../mcp/mcpManager.js';
+import { isWebSearchConfigured } from '../mcp/webSearch.js';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface EnricherOptions {
+  /** MCP manager to check service availability (legacy, optional) */
+  mcpManager?: McpManager;
+  /** Dependencies listed in the plan (e.g., ["express", "zod"]) */
+  dependencies?: string[];
+  /** Plan architecture notes (checked for Azure keywords) */
+  architectureNotes?: string;
+  /** Number of consecutive stuck iterations (same failures) */
+  stuckIterations?: number;
+  /** Current failing test names for stuck detection */
+  failingTests?: string[];
+}
+
+export interface EnrichedContext {
+  /** Context7 library docs */
+  libraryDocs?: string;
+  /** Azure/cloud guidance */
+  azureGuidance?: string;
+  /** Web search results */
+  webSearchResults?: string;
+  /** Combined context string for prompt injection */
+  combined: string;
+}
+
+// ── Azure keyword detection ───────────────────────────────────────────────────
+
+const AZURE_KEYWORDS = [
+  'azure',
+  'cosmos db',
+  'cosmosdb',
+  'blob storage',
+  'service bus',
+  'event hub',
+  'app service',
+  'azure sql',
+  'key vault',
+  'azure functions',
+  'azure openai',
+];
+
+function mentionsAzure(text: string): boolean {
+  const lower = text.toLowerCase();
+  return AZURE_KEYWORDS.some((kw) => lower.includes(kw));
+}
+
+// ── McpContextEnricher ────────────────────────────────────────────────────────
+
+/**
+ * Enriches LLM iteration prompts with context from MCP services.
+ *
+ * Each method degrades gracefully — returns undefined when service
+ * is unavailable rather than throwing.
+ */
+export class McpContextEnricher {
+  /** @internal Exposed for RalphLoop integration */
+  readonly mcpManager: McpManager;
+
+  constructor(mcpManager: McpManager) {
+    this.mcpManager = mcpManager;
+  }
+
+  /**
+   * Enrich the iteration context with MCP-sourced information.
+   *
+   * Queries are conditional on:
+   * 1. Context7: available AND dependencies listed in plan
+   * 2. Azure MCP: available AND plan references Azure services
+   * 3. web.search: configured AND stuckIterations >= 2
+   */
+  async enrich(options: EnricherOptions): Promise<EnrichedContext> {
+    const { dependencies = [], architectureNotes = '', stuckIterations = 0 } = options;
+
+    const parts: string[] = [];
+    let libraryDocs: string | undefined;
+    let azureGuidance: string | undefined;
+    let webSearchResults: string | undefined;
+
+    // Context7 + Azure MCP: run concurrently via Promise.allSettled()
+    const concurrent: Promise<void>[] = [];
+
+    if (this.mcpManager.isAvailable('context7') && dependencies.length > 0) {
+      concurrent.push(
+        this.queryContext7(dependencies).then((result) => {
+          libraryDocs = result;
+        }),
+      );
+    }
+
+    if (this.mcpManager.isAvailable('azure') && mentionsAzure(architectureNotes)) {
+      concurrent.push(
+        this.queryAzureMcp(architectureNotes).then((result) => {
+          azureGuidance = result;
+        }),
+      );
+    }
+
+    await Promise.allSettled(concurrent);
+
+    if (libraryDocs) parts.push(`### Library Documentation (Context7)\n\n${libraryDocs}`);
+    if (azureGuidance) parts.push(`### Azure Architecture Guidance\n\n${azureGuidance}`);
+
+    // web.search: when stuck for 2+ iterations
+    if (isWebSearchConfigured() && stuckIterations >= 2 && options.failingTests?.length) {
+      webSearchResults = await this.queryWebSearch(options.failingTests);
+      if (webSearchResults) parts.push(`### Web Search Results\n\n${webSearchResults}`);
+    }
+
+    return {
+      libraryDocs,
+      azureGuidance,
+      webSearchResults,
+      combined: parts.join('\n\n'),
+    };
+  }
+
+  /**
+   * Query Context7 for library documentation.
+   *
+   * Calls `mcpManager.callTool('context7', 'resolve-library-id', ...)` to
+   * resolve each dependency, then `query-docs` for the resolved library.
+   * Degrades gracefully when the service is unavailable or errors.
+   */
+  private async queryContext7(dependencies: string[]): Promise<string | undefined> {
+    if (!this.mcpManager.isAvailable('context7')) return undefined;
+
+    try {
+      const docs: string[] = [];
+
+      for (const dep of dependencies.slice(0, 5)) {
+        // Filter out type-only and well-known packages that don't need lookup
+        if (dep.startsWith('@types/') || dep === 'typescript' || dep === 'vitest') {
+          continue;
+        }
+
+        try {
+          // Step 1: Resolve library ID
+          const resolved = await this.mcpManager.callTool(
+            'context7',
+            'resolve-library-id',
+            {
+              libraryName: dep,
+            },
+            { timeoutMs: 30_000 },
+          );
+          const libraryId = (resolved.libraryId as string) ?? (resolved.id as string);
+          if (!libraryId) {
+            docs.push(
+              `- **${dep}**: See https://www.npmjs.com/package/${dep} for API documentation`,
+            );
+            continue;
+          }
+
+          // Step 2: Query docs with the resolved ID
+          const docResult = await this.mcpManager.callTool(
+            'context7',
+            'query-docs',
+            {
+              libraryId,
+              topic: dep,
+            },
+            { timeoutMs: 30_000 },
+          );
+          const content = (docResult.content as string) ?? (docResult.text as string);
+          if (content) {
+            docs.push(`- **${dep}**:\n${content}`);
+          } else {
+            docs.push(
+              `- **${dep}**: See https://www.npmjs.com/package/${dep} for API documentation`,
+            );
+          }
+        } catch {
+          // Individual dep failure — fallback link
+          docs.push(`- **${dep}**: See https://www.npmjs.com/package/${dep} for API documentation`);
+        }
+      }
+
+      return docs.length > 0 ? docs.join('\n') : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Query Azure MCP for architecture guidance.
+   *
+   * Calls `mcpManager.callTool('azure', 'documentation', ...)` with detected
+   * Azure keywords. Degrades gracefully when Azure MCP is unavailable.
+   */
+  private async queryAzureMcp(architectureNotes: string): Promise<string | undefined> {
+    if (!this.mcpManager.isAvailable('azure')) return undefined;
+
+    try {
+      const detected = AZURE_KEYWORDS.filter((kw) => architectureNotes.toLowerCase().includes(kw));
+      if (detected.length === 0) return undefined;
+
+      try {
+        const response = await this.mcpManager.callTool(
+          'azure',
+          'documentation',
+          {
+            query: `Best practices for ${detected.join(', ')}`,
+          },
+          { timeoutMs: 30_000 },
+        );
+        const content = (response.content as string) ?? (response.text as string);
+        if (content) {
+          return content;
+        }
+      } catch {
+        // MCP call failed — fall back to static guidance
+      }
+
+      return [
+        `Detected Azure services: ${detected.join(', ')}`,
+        'Use the @azure/identity DefaultAzureCredential for authentication.',
+        'Prefer connection strings from environment variables (never hardcode).',
+      ].join('\n');
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Query web search for solutions to failing tests.
+   *
+   * Only called when stuckIterations >= 2 to avoid unnecessary API calls.
+   * Uses `mcpManager.callTool` to search for error messages.
+   */
+  private async queryWebSearch(failingTests: string[]): Promise<string | undefined> {
+    if (!isWebSearchConfigured()) return undefined;
+
+    try {
+      const query = failingTests.slice(0, 3).join('; ');
+
+      // Attempt real web search via MCP if available
+      if (this.mcpManager.isAvailable('websearch')) {
+        try {
+          const response = await this.mcpManager.callTool(
+            'websearch',
+            'search',
+            {
+              query: `how to fix: ${query}`,
+            },
+            { timeoutMs: 30_000 },
+          );
+          const content = (response.content as string) ?? (response.text as string);
+          if (content) {
+            return content;
+          }
+        } catch {
+          // Web search MCP unavailable — fall through to static message
+        }
+      }
+
+      return `Web search for: "${query}" — no results available in this environment.`;
+    } catch {
+      return undefined;
+    }
+  }
+}