imhcode 1.1.0 → 2.0.0

package/src/orchestrator/context-scanner.ts

@@ -0,0 +1,221 @@
+import * as fs from "fs";
+import * as path from "path";
+
+export interface ProjectScanResult {
+  hasFrontend: boolean;
+  hasBackend: boolean;
+  frontendFramework?: string;
+  backendFramework?: string;
+  dependencies: Record<string, string>;
+  directories: string[];
+  fileCount: number;
+  recentModifications: string[];
+}
+
+/**
+ * Scan project structure to build context for modifications.
+ */
+export function scanProjectContext(cwd: string): ProjectScanResult {
+  const result: ProjectScanResult = {
+    hasFrontend: false,
+    hasBackend: false,
+    dependencies: {},
+    directories: [],
+    fileCount: 0,
+    recentModifications: []
+  };
+
+  // 1. Detect directories
+  try {
+    const items = fs.readdirSync(cwd);
+    for (const item of items) {
+      if (item.startsWith(".") || item === "node_modules" || item === "dist") continue;
+      const itemPath = path.join(cwd, item);
+      try {
+        const stat = fs.statSync(itemPath);
+        if (stat.isDirectory()) {
+          result.directories.push(item);
+        }
+      } catch {
+        // Ignore
+      }
+    }
+  } catch {
+    // Ignore
+  }
+
+  // 2. Scan frontend
+  const frontendPath = path.join(cwd, "frontend");
+  if (fs.existsSync(frontendPath) && fs.statSync(frontendPath).isDirectory()) {
+    result.hasFrontend = true;
+    const pkgJsonPath = path.join(frontendPath, "package.json");
+    if (fs.existsSync(pkgJsonPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+        result.frontendFramework = pkg.dependencies?.next ? "Next.js" : pkg.dependencies?.vue ? "Vue" : "React";
+        Object.assign(result.dependencies, pkg.dependencies || {});
+        Object.assign(result.dependencies, pkg.devDependencies || {});
+      } catch {
+        // Ignore
+      }
+    }
+  }
+
+  // 3. Scan backend
+  const backendPath = path.join(cwd, "backend");
+  if (fs.existsSync(backendPath) && fs.statSync(backendPath).isDirectory()) {
+    result.hasBackend = true;
+    const composerJsonPath = path.join(backendPath, "composer.json");
+    if (fs.existsSync(composerJsonPath)) {
+      try {
+        const comp = JSON.parse(fs.readFileSync(composerJsonPath, "utf-8"));
+        result.backendFramework = "Laravel";
+        if (comp.require) {
+          Object.assign(result.dependencies, comp.require);
+        }
+      } catch {
+        // Ignore
+      }
+    }
+    // Also check for Python
+    const reqTxtPath = path.join(backendPath, "requirements.txt");
+    if (fs.existsSync(reqTxtPath)) {
+      result.backendFramework = "Python/FastAPI/Django";
+    }
+  }
+
+  // 4. Count files (shallow-ish recursive count for safety/perf)
+  let count = 0;
+  function countFiles(dir: string, depth = 0) {
+    if (depth > 4 || count > 500) return; // Cap at 500 files for scanning performance
+    try {
+      const files = fs.readdirSync(dir);
+      for (const file of files) {
+        if (file.startsWith(".") || file === "node_modules" || file === "dist" || file === "vendor") continue;
+        const fp = path.join(dir, file);
+        const stat = fs.statSync(fp);
+        if (stat.isDirectory()) {
+          countFiles(fp, depth + 1);
+        } else {
+          count++;
+        }
+      }
+    } catch {
+      // Ignore
+    }
+  }
+  countFiles(cwd);
+  result.fileCount = count;
+
+  // 5. Read recent modifications from log if exists
+  const modLogPath = path.join(cwd, "docs", "modifications.md");
+  if (fs.existsSync(modLogPath)) {
+    try {
+      const content = fs.readFileSync(modLogPath, "utf-8");
+      const lines = content.split("\n").filter(l => l.trim().startsWith("|")).slice(2);
+      result.recentModifications = lines.map(l => l.trim());
+    } catch {
+      // Ignore
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Builds context prompt specifically for a modification task.
+ */
+export function buildModificationPrompt(context: ProjectScanResult, description: string): string {
+  const lines = [
+    `# IMH-Code Project Modification Request`,
+    `You are tasked with modifying or extending an existing project.`,
+    ``,
+    `## Project Inventory`,
+    `- Frontend Active: ${context.hasFrontend ? `Yes (${context.frontendFramework})` : "No"}`,
+    `- Backend Active: ${context.hasBackend ? `Yes (${context.backendFramework})` : "No"}`,
+    `- Total Directories: ${context.directories.join(", ")}`,
+    `- File Count: ${context.fileCount}`,
+    ``,
+    `## Detected Stacks & Dependencies`,
+    Object.entries(context.dependencies)
+      .slice(0, 15) // Top 15 dependencies
+      .map(([k, v]) => `- \`${k}\`: \`${v}\``)
+      .join("\n"),
+    context.recentModifications.length > 0 
+      ? `\n## Recent Project Modifications\n` + context.recentModifications.join("\n")
+      : "",
+    ``,
+    `## Modification Instructions`,
+    `Task: ${description}`,
+    ``,
+    `CRITICAL DIRECTIONS:`,
+    `1. Review the existing directories (e.g. frontend/ and backend/) to locate the relevant files.`,
+    `2. Perform the edit IN-PLACE. Do NOT delete or rewrite entire directories unless necessary.`,
+    `3. Adhere strictly to the existing coding style, frameworks, and packages.`,
+    `4. If new dependencies are needed, install them using the appropriate package manager in the correct directory.`,
+    `5. After completing, explain clearly what files were changed.`
+  ];
+
+  return lines.join("\n");
+}
+
+/**
+ * Helper to auto-select best agent ID based on task description keywords.
+ */
+export function detectBestAgent(description: string, context: ProjectScanResult): string {
+  const d = description.toLowerCase();
+
+  // 1. Planning/Architecture
+  if (d.includes("plan") || d.includes("architect") || d.includes("road map") || d.includes("sprint")) {
+    return "planner";
+  }
+
+  // 2. DevOps/Infrastructure
+  if (d.includes("docker") || d.includes("kubernetes") || d.includes("deploy") || d.includes("ci/cd") || d.includes("github action") || d.includes("nginx")) {
+    return "devops-executor";
+  }
+
+  // 3. Testing
+  if (d.includes("test") || d.includes("spec") || d.includes("audit") || d.includes("security")) {
+    if (d.includes("security") || d.includes("vulnerability") || d.includes("owasp")) {
+      return "security-auditor";
+    }
+    return "tester";
+  }
+
+  // 4. SEO
+  if (d.includes("seo") || d.includes("meta tag") || d.includes("sitemap") || d.includes("robots.txt")) {
+    return "seo-optimizer";
+  }
+
+  // 5. Frontend Keywords Check
+  const hasFrontendKeywords = d.includes("ui") || d.includes("page") || d.includes("component") || d.includes("navbar") || d.includes("style") || d.includes("css") || d.includes("tailwind") || d.includes("button") || d.includes("layout");
+  if (hasFrontendKeywords) {
+    if (context.frontendFramework === "Next.js") return "nextjs-executor";
+    if (context.frontendFramework === "Vue") return "vue-executor";
+    return "react-executor";
+  }
+
+  // 6. Backend Keywords Check
+  const hasBackendKeywords = d.includes("api") || d.includes("route") || d.includes("database") || d.includes("controller") || d.includes("migration") || d.includes("model") || d.includes("query") || d.includes("auth");
+  if (hasBackendKeywords) {
+    if (context.backendFramework === "Laravel") return "laravel-executor";
+    if (context.backendFramework === "Python/FastAPI/Django") return "python-executor";
+    return "laravel-executor";
+  }
+
+  // 7. Directory fallbacks if no keywords matched
+  if (context.hasFrontend) {
+    if (context.frontendFramework === "Next.js") return "nextjs-executor";
+    if (context.frontendFramework === "Vue") return "vue-executor";
+    return "react-executor";
+  }
+
+  if (context.hasBackend) {
+    if (context.backendFramework === "Laravel") return "laravel-executor";
+    if (context.backendFramework === "Python/FastAPI/Django") return "python-executor";
+    return "laravel-executor";
+  }
+
+  return "laravel-executor"; // Ultimate default
+}

package/src/orchestrator/import-engine.ts

@@ -0,0 +1,106 @@
+import * as fs from "fs";
+import * as path from "path";
+import { scanProject } from "./project-scanner";
+
+export interface ImportResult {
+  success: boolean;
+  scanResult: any;
+  importMap: {
+    frontend: string;
+    backend: string;
+    database: string;
+    detectedStack: {
+      frontend: string | null;
+      backend: string | null;
+    };
+  };
+}
+
+/**
+ * Import an existing codebase into the IMH-Code orchestration framework.
+ */
+export function importProject(cwd: string): ImportResult {
+  const scanResult = scanProject(cwd);
+
+  const imhDir = path.join(cwd, ".imhcode");
+  if (!fs.existsSync(imhDir)) {
+    fs.mkdirSync(imhDir, { recursive: true });
+  }
+
+  const cmdDir = path.join(imhDir, "commands");
+  if (!fs.existsSync(cmdDir)) {
+    fs.mkdirSync(cmdDir, { recursive: true });
+  }
+
+  const sessionsDir = path.join(imhDir, "sessions");
+  if (!fs.existsSync(sessionsDir)) {
+    fs.mkdirSync(sessionsDir, { recursive: true });
+  }
+
+  // Map paths. If it scanned to ".", default to empty or standard string
+  const importMap = {
+    frontend: scanResult.frontendPath || "frontend",
+    backend: scanResult.backendPath || "backend",
+    database: scanResult.database || "PostgreSQL",
+    detectedStack: {
+      frontend: scanResult.detectedFrontend,
+      backend: scanResult.detectedBackend
+    }
+  };
+
+  fs.writeFileSync(
+    path.join(imhDir, "import-map.json"),
+    JSON.stringify(importMap, null, 2),
+    "utf-8"
+  );
+
+  // PROJECT_BRIEF.md
+  const briefPath = path.join(cwd, "PROJECT_BRIEF.md");
+  const briefContent = `# PROJECT_BRIEF.md (Imported Project)
+
+> **IMH-Code — Imam Hussain Coding Harness Platform**
+> Centralized memory for this imported project.
+
+## Project Summary
+
+*(Imported project. Add a description of your project here to guide the agents.)*
+
+## Status
+
+- **Imported**: ${new Date().toLocaleDateString()}
+- **Current Sprint**: Sprint 1 (Modifications Mode)
+
+## Design Specification
+
+- **Design Style**: Modern SaaS
+- **Color Palette**: Dark Premium
+
+## Scope
+
+- **Frontend Path**: \`${importMap.frontend}\` (${scanResult.detectedFrontend || "None"})
+- **Backend Path**: \`${importMap.backend}\` (${scanResult.detectedBackend || "None"})
+- **Database**: ${importMap.database}
+`;
+  fs.writeFileSync(briefPath, briefContent, "utf-8");
+
+  // context.md
+  const contextPath = path.join(imhDir, "context.md");
+  const contextContent = `# IMH-Code Project Context (Imported)
+
+Generated: ${new Date().toLocaleDateString()}
+Project Path: ${cwd}
+Frontend Framework: ${scanResult.detectedFrontend || "None"} (Path: ${importMap.frontend})
+Backend Framework: ${scanResult.detectedBackend || "None"} (Path: ${importMap.backend})
+
+## Directory Structure Mappings
+- Frontend: \`${importMap.frontend}\`
+- Backend: \`${importMap.backend}\`
+`;
+  fs.writeFileSync(contextPath, contextContent, "utf-8");
+
+  return {
+    success: true,
+    scanResult,
+    importMap
+  };
+}

package/src/orchestrator/index.ts

@@ -48,6 +48,14 @@ export {
 // Session
 export { saveSession, resolveSessionDir } from "./session";
 
+// Modification & Scanning
+export { scanProjectContext, buildModificationPrompt, detectBestAgent } from "./context-scanner";
+export { runModification } from "./modification-engine";
+
+// Project Import & Extension
+export { scanProject } from "./project-scanner";
+export { importProject } from "./import-engine";
+
 // ─── High-level run function ──────────────────────────────────────────────────
 
 import * as fs from "fs";

package/src/orchestrator/modification-engine.ts

@@ -0,0 +1,108 @@
+import * as fs from "fs";
+import * as path from "path";
+import { scanProjectContext, buildModificationPrompt, detectBestAgent } from "./context-scanner";
+import { loadRegistry, getAgent } from "./registry";
+import { runAgent } from "./index";
+
+export interface ModificationOptions {
+  agent?: string;
+  engine?: string;
+  model?: string;
+  dryRun?: boolean;
+  scope?: string;
+}
+
+/**
+ * Execute a targeted project modification.
+ */
+export async function runModification(
+  cwd: string,
+  description: string,
+  options: ModificationOptions = {}
+): Promise<any> {
+  // 1. Scan context
+  const context = scanProjectContext(cwd);
+
+  // 2. Select agent
+  const selectedAgentId = options.agent || detectBestAgent(description, context);
+  
+  console.log(`\n🛠️  [IMH-Code] Initializing Modification Engine`);
+  console.log(`   Task:  "${description}"`);
+  console.log(`   Agent:  ${selectedAgentId}`);
+
+  // Resolve agent manifests directory
+  const globalAgents = path.join(process.env.HOME || "", ".imhcode", "agents");
+  const localAgents = path.join(cwd, "agents");
+  const pkgAgents = path.join(__dirname, "..", "..", "agents");
+  const agentsDir = fs.existsSync(globalAgents) ? globalAgents : 
+                    fs.existsSync(localAgents) ? localAgents : 
+                    pkgAgents;
+
+  // 3. Load Registry
+  const { agents, errors } = await loadRegistry(agentsDir, cwd);
+  if (errors.some(e => e.agentId === selectedAgentId)) {
+    throw new Error(`Failed to load agent "${selectedAgentId}": ${errors.find(e => e.agentId === selectedAgentId)?.error}`);
+  }
+
+  const agent = getAgent(agents, selectedAgentId);
+
+  // 4. Build custom modification task
+  const modificationTask = buildModificationPrompt(context, description);
+
+  // 5. Run the agent
+  const result = await runAgent(
+    agent,
+    modificationTask,
+    {
+      dryRun: options.dryRun !== false,
+      engine: options.engine,
+      model: options.model,
+      outputDir: path.join(cwd, ".imhcode", "sessions"),
+      cwd
+    }
+  );
+
+  // 6. Log changes if live and successful
+  if (!result.dryRun && result.errors.length === 0) {
+    logModification(cwd, {
+      task: description,
+      agentId: selectedAgentId,
+      model: result.model,
+      durationMs: result.durationMs
+    });
+  }
+
+  return result;
+}
+
+interface LogEntry {
+  task: string;
+  agentId: string;
+  model: string;
+  durationMs: number;
+}
+
+function logModification(cwd: string, entry: LogEntry): void {
+  const docsDir = path.join(cwd, "docs");
+  if (!fs.existsSync(docsDir)) {
+    fs.mkdirSync(docsDir, { recursive: true });
+  }
+
+  const logPath = path.join(docsDir, "modifications.md");
+  const timestamp = new Date().toISOString().replace("T", " ").substring(0, 19);
+  
+  let header = `# 🛠️ IMH-Code Project Modifications\n\n| Date | Task | Agent | Model | Duration |\n|------|------|-------|-------|----------|\n`;
+  if (fs.existsSync(logPath)) {
+    try {
+      const existing = fs.readFileSync(logPath, "utf-8");
+      if (existing.trim().length > 10) {
+        header = existing;
+      }
+    } catch {
+      // Ignore
+    }
+  }
+
+  const row = `| ${timestamp} | ${entry.task} | \`${entry.agentId}\` | ${entry.model} | ${(entry.durationMs / 1000).toFixed(1)}s |\n`;
+  fs.writeFileSync(logPath, header.endsWith("\n") ? header + row : header + "\n" + row, "utf-8");
+}

package/src/orchestrator/project-scanner.ts

@@ -0,0 +1,134 @@
+import * as fs from "fs";
+import * as path from "path";
+
+export interface ScanResult {
+  detectedFrontend: string | null;
+  detectedBackend: string | null;
+  frontendPath: string | null;
+  backendPath: string | null;
+  database: string | null;
+  dockerized: boolean;
+  hasCICD: boolean;
+  packageJson?: any;
+  composerJson?: any;
+}
+
+/**
+ * Deep scan an existing codebase to detect stack and structure.
+ */
+export function scanProject(cwd: string): ScanResult {
+  const result: ScanResult = {
+    detectedFrontend: null,
+    detectedBackend: null,
+    frontendPath: null,
+    backendPath: null,
+    database: null,
+    dockerized: false,
+    hasCICD: false,
+  };
+
+  // 1. Helper to search for files recursively with limits
+  function findFile(dir: string, name: string, depth = 0): string | null {
+    if (depth > 3) return null;
+    try {
+      const files = fs.readdirSync(dir);
+      if (files.includes(name)) {
+        return path.join(dir, name);
+      }
+      for (const file of files) {
+        if (file.startsWith(".") || file === "node_modules" || file === "dist" || file === "vendor") continue;
+        const fp = path.join(dir, file);
+        if (fs.statSync(fp).isDirectory()) {
+          const found = findFile(fp, name, depth + 1);
+          if (found) return found;
+        }
+      }
+    } catch {
+      // Ignore
+    }
+    return null;
+  }
+
+  // 2. Scan for package.json (Frontend detection)
+  const pkgJsonPath = findFile(cwd, "package.json");
+  if (pkgJsonPath) {
+    try {
+      const content = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+      result.packageJson = content;
+      const deps = { ...(content.dependencies || {}), ...(content.devDependencies || {}) };
+      
+      if (deps.next) result.detectedFrontend = "Next.js";
+      else if (deps.nuxt || deps.nuxt3 || deps.nuxt4) result.detectedFrontend = "Nuxt/Vue";
+      else if (deps.react) result.detectedFrontend = "React SPA";
+      else if (deps.vue) result.detectedFrontend = "Vue SPA";
+      else if (deps.svelte) result.detectedFrontend = "Svelte";
+      else result.detectedFrontend = "Node/JS";
+
+      // If package.json is in a subdirectory, use that subdirectory
+      const relative = path.relative(cwd, path.dirname(pkgJsonPath));
+      result.frontendPath = relative === "" ? "." : relative;
+    } catch {
+      // Ignore
+    }
+  }
+
+  // 3. Scan for composer.json, requirements.txt, or pom.xml (Backend detection)
+  const composerPath = findFile(cwd, "composer.json");
+  if (composerPath) {
+    try {
+      const content = JSON.parse(fs.readFileSync(composerPath, "utf-8"));
+      result.composerJson = content;
+      if (content.require && (content.require["laravel/framework"] || content.require["laravel/lumen-framework"])) {
+        result.detectedBackend = "Laravel";
+      } else {
+        result.detectedBackend = "PHP";
+      }
+      const relative = path.relative(cwd, path.dirname(composerPath));
+      result.backendPath = relative === "" ? "." : relative;
+    } catch {
+      // Ignore
+    }
+  }
+
+  if (!result.detectedBackend) {
+    const reqsTxtPath = findFile(cwd, "requirements.txt");
+    const pyprojectPath = findFile(cwd, "pyproject.toml");
+    if (reqsTxtPath || pyprojectPath) {
+      result.detectedBackend = "Python (Django/FastAPI)";
+      const matchedPath = reqsTxtPath || pyprojectPath || "";
+      const relative = path.relative(cwd, path.dirname(matchedPath));
+      result.backendPath = relative === "" ? "." : relative;
+    }
+  }
+
+  // 4. Database Detection from env or configs
+  const envPath = findFile(cwd, ".env") || findFile(cwd, ".env.example");
+  if (envPath) {
+    try {
+      const content = fs.readFileSync(envPath, "utf-8");
+      if (content.includes("DB_CONNECTION=pgsql") || content.includes("postgresql://")) {
+        result.database = "PostgreSQL";
+      } else if (content.includes("DB_CONNECTION=mysql") || content.includes("mysql://")) {
+        result.database = "MySQL";
+      } else if (content.includes("DB_CONNECTION=sqlite") || content.includes("sqlite3")) {
+        result.database = "SQLite";
+      }
+    } catch {
+      // Ignore
+    }
+  }
+
+  // 5. Infrastructure detection
+  const dockerCompose = findFile(cwd, "docker-compose.yml");
+  const dockerfile = findFile(cwd, "Dockerfile");
+  if (dockerCompose || dockerfile) {
+    result.dockerized = true;
+  }
+
+  const githubWorkflows = findFile(cwd, ".github/workflows");
+  if (githubWorkflows) {
+    result.hasCICD = true;
+  }
+
+  return result;
+}