imhcode 1.0.0

package/src/orchestrator/loader.ts

@@ -0,0 +1,237 @@
+/**
+ * File loading utilities for the orchestrator.
+ * Handles YAML parsing, Markdown reading, path resolution, and memory loading.
+ */
+
+import fs from "fs";
+import path from "path";
+import yaml from "js-yaml";
+import { glob } from "glob";
+import { validateManifest } from "./schema";
+import type { LoadedAgent, LoadedSkill, LoadedMemoryFile, AgentManifest } from "./types";
+
+// ─── YAML Loading ─────────────────────────────────────────────────────────────
+
+/**
+ * Load and parse a YAML file. Throws with the file path in the error message.
+ */
+export function loadYaml<T = unknown>(filePath: string): T {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(
+      `❌ File not found: ${filePath}\n` +
+        `  Make sure agent.yml exists in the agent directory.`
+    );
+  }
+
+  const raw = fs.readFileSync(filePath, "utf-8");
+
+  try {
+    return yaml.load(raw) as T;
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `❌ Failed to parse YAML at "${filePath}":\n  ${msg}\n` +
+        `  Check for indentation errors or invalid characters.`
+    );
+  }
+}
+
+// ─── Markdown Loading ─────────────────────────────────────────────────────────
+
+/**
+ * Read a Markdown file. Throws with a clear message if missing.
+ */
+export function loadMarkdown(filePath: string, label: string): string {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(
+      `❌ Markdown file not found: ${filePath}\n` +
+        `  Expected "${label}" at the path above. Create the file and retry.`
+    );
+  }
+
+  return fs.readFileSync(filePath, "utf-8");
+}
+
+// ─── Path Resolution ──────────────────────────────────────────────────────────
+
+/**
+ * Resolve a path declared in agent.yml (relative to the agent directory)
+ * to an absolute path.
+ */
+export function resolveAgentPath(agentDir: string, relativePath: string): string {
+  return path.resolve(agentDir, relativePath);
+}
+
+/**
+ * Extract a skill ID from a SKILL.md path.
+ * e.g. "../../skills/premium-ui/SKILL.md" → "premium-ui"
+ */
+function extractSkillId(skillPath: string): string {
+  const parts = skillPath.replace(/\\/g, "/").split("/");
+  // The skill ID is the folder name that contains SKILL.md
+  const skillMdIndex = parts.findIndex((p) => p === "SKILL.md");
+  if (skillMdIndex > 0) {
+    return parts[skillMdIndex - 1];
+  }
+  // Fallback: use the parent directory name
+  return path.basename(path.dirname(skillPath));
+}
+
+const BINARY_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.pdf', '.zip', '.tar', '.gz', 
+  '.mp4', '.mov', '.avi', '.mp3', '.wav', '.woff', '.woff2', '.ttf', '.eot', 
+  '.exe', '.dll', '.so', '.dylib', '.map', '.db', '.sqlite', '.sqlite3', '.wasm',
+  '.xlsx', '.xls', '.docx', '.doc', '.pptx', '.ppt', '.ds_store'
+]);
+
+const EXCLUDED_DIR_SEGMENTS = [
+  '/node_modules/',
+  '/.next/',
+  '/.nuxt/',
+  '/dist/',
+  '/build/',
+  '/.git/'
+];
+
+const EXCLUDED_FILENAME_EXACT = new Set([
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'skills-lock.json',
+  '.ds_store'
+]);
+
+const MAX_FILE_SIZE_BYTES = 1024 * 1024; // 1MB
+
+/**
+ * Load all readable memory files declared in the agent manifest.
+ * Glob patterns are expanded relative to `cwd`.
+ * Missing files are silently skipped (non-blocking).
+ */
+export async function loadMemoryFiles(
+  manifest: AgentManifest,
+  cwd: string
+): Promise<LoadedMemoryFile[]> {
+  const results: LoadedMemoryFile[] = [];
+
+  for (const pattern of manifest.memory.readable) {
+    let matchedPaths: string[];
+
+    try {
+      matchedPaths = await glob(pattern, {
+        cwd,
+        absolute: true,
+        nodir: true,
+        dot: true,
+        ignore: [
+          "**/node_modules/**",
+          "**/.next/**",
+          "**/.nuxt/**",
+          "**/dist/**",
+          "**/build/**",
+          "**/.git/**",
+          "**/package-lock.json",
+          "**/yarn.lock",
+          "**/pnpm-lock.yaml",
+          "**/skills-lock.json",
+          "**/.DS_Store"
+        ]
+      });
+    } catch {
+      // Invalid glob pattern — skip with a warning
+      console.warn(
+        `  ⚠️  Skipping unresolvable memory glob: "${pattern}"`
+      );
+      continue;
+    }
+
+    for (const filePath of matchedPaths) {
+      if (!fs.existsSync(filePath)) continue;
+
+      // 1. Check directory exclusions (defense in depth)
+      const normalizedPath = filePath.replace(/\\/g, "/");
+      const isExcludedDir = EXCLUDED_DIR_SEGMENTS.some(segment => normalizedPath.includes(segment));
+      if (isExcludedDir) continue;
+
+      // 2. Check filename exclusions
+      const basename = path.basename(filePath).toLowerCase();
+      if (EXCLUDED_FILENAME_EXACT.has(basename)) continue;
+
+      // 3. Check binary file extensions
+      const ext = path.extname(filePath).toLowerCase();
+      if (BINARY_EXTENSIONS.has(ext)) continue;
+
+      try {
+        // 4. Check file size to avoid heap memory issues
+        const stats = fs.statSync(filePath);
+        if (stats.size > MAX_FILE_SIZE_BYTES) {
+          console.warn(`  ⚠️  Skipping large memory file (${(stats.size / 1024).toFixed(0)} KB): "${filePath}"`);
+          continue;
+        }
+
+        const content = fs.readFileSync(filePath, "utf-8");
+        results.push({ path: filePath, content });
+      } catch {
+        // File exists but can't be read — skip silently
+      }
+    }
+  }
+
+  return results;
+}
+
+// ─── Agent Loader ─────────────────────────────────────────────────────────────
+
+/**
+ * Fully load a single agent from its directory:
+ * 1. Parse and validate agent.yml
+ * 2. Load SYSTEM.md
+ * 3. Load all referenced SKILL.md files
+ * 4. Load project memory files
+ */
+export async function loadAgent(
+  agentDir: string,
+  cwd: string
+): Promise<LoadedAgent> {
+  const agentId = path.basename(agentDir);
+  const manifestPath = path.join(agentDir, "agent.yml");
+
+  // 1. Parse and validate agent.yml
+  const rawYaml = loadYaml<unknown>(manifestPath);
+  const manifest = validateManifest(rawYaml, agentId) as AgentManifest;
+
+  // 2. Load SYSTEM.md
+  const systemPromptPath = resolveAgentPath(agentDir, manifest.system_prompt);
+  const systemPrompt = loadMarkdown(systemPromptPath, "system_prompt (SYSTEM.md)");
+
+  // 3. Load skill files
+  const skills: LoadedSkill[] = [];
+  for (const skillRelPath of manifest.skills) {
+    const skillAbsPath = resolveAgentPath(agentDir, skillRelPath);
+
+    if (!fs.existsSync(skillAbsPath)) {
+      throw new Error(
+        `❌ Skill file not found for agent "${agentId}":\n` +
+          `  Path: ${skillAbsPath}\n` +
+          `  Declared in agent.yml: "${skillRelPath}"\n` +
+          `  Create the SKILL.md file or fix the path in agent.yml.`
+      );
+    }
+
+    const content = fs.readFileSync(skillAbsPath, "utf-8");
+    const skillId = extractSkillId(skillRelPath);
+
+    skills.push({ id: skillId, path: skillAbsPath, content });
+  }
+
+  // 4. Load memory files
+  const memoryFiles = await loadMemoryFiles(manifest, cwd);
+
+  return {
+    dir: agentDir,
+    manifest,
+    systemPrompt,
+    skills,
+    memoryFiles,
+  };
+}

package/src/orchestrator/registry.ts

@@ -0,0 +1,211 @@
+/**
+ * Agent registry: discovers and loads all agents from the agents/ directory.
+ * IMH-Code — Imam Hussain Coding Harness Platform
+ * Agents are discovered by scanning for agents/{id}/agent.yml files.
+ */
+
+import fs from "fs";
+import path from "path";
+import { glob } from "glob";
+import { loadAgent } from "./loader";
+import type { LoadedAgent } from "./types";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface RegistryLoadResult {
+  agents: Map<string, LoadedAgent>;
+  errors: Array<{ agentId: string; error: string }>;
+}
+
+// ─── Discovery ────────────────────────────────────────────────────────────────
+
+/**
+ * Scan the agents directory and return absolute paths to all agent.yml files.
+ * Pattern: <agentsDir>/{agent-id}/agent.yml
+ */
+export async function discoverAgents(agentsDir: string): Promise<string[]> {
+  if (!fs.existsSync(agentsDir)) {
+    throw new Error(
+      `❌ Agents directory not found: ${agentsDir}\n` +
+        `  Create the directory and add at least one agent folder with agent.yml.`
+    );
+  }
+
+  const manifestPaths = await glob("*/agent.yml", {
+    cwd: agentsDir,
+    absolute: true,
+  });
+
+  if (manifestPaths.length === 0) {
+    console.warn(
+      `  ⚠️  No agents found in "${agentsDir}".\n` +
+        `  Add a folder with agent.yml and SYSTEM.md to register an agent.`
+    );
+  }
+
+  return manifestPaths.sort(); // deterministic order
+}
+
+// ─── Registry Loader ─────────────────────────────────────────────────────────
+
+/**
+ * Load and validate all agents from the agents directory.
+ * Individual load failures are collected as errors (not thrown) so that
+ * a single bad agent doesn't break listing/inspecting the rest.
+ */
+export async function loadRegistry(
+  agentsDir: string,
+  cwd: string
+): Promise<RegistryLoadResult> {
+  const manifestPaths = await discoverAgents(agentsDir);
+  const agents = new Map<string, LoadedAgent>();
+  const errors: Array<{ agentId: string; error: string }> = [];
+
+  for (const manifestPath of manifestPaths) {
+    const agentDir = path.dirname(manifestPath);
+    const agentId = path.basename(agentDir);
+
+    try {
+      const loaded = await loadAgent(agentDir, cwd);
+      agents.set(agentId, loaded);
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      errors.push({ agentId, error: message });
+    }
+  }
+
+  return { agents, errors };
+}
+
+// ─── Lookup ───────────────────────────────────────────────────────────────────
+
+/**
+ * Resolves a given agent ID or short alias to the canonical agent ID.
+ *
+ * IMH-Code Generic Agent Aliases:
+ *
+ * Core Agents:
+ *   planner, plan, pm        → planner
+ *   designer, design, ui, ux → designer
+ *
+ * Frontend Executors:
+ *   nextjs, next             → nextjs-executor
+ *   react, vite              → react-executor
+ *   vue, nuxt, vue3          → vue-executor
+ *
+ * Backend Executors:
+ *   laravel, php             → laravel-executor
+ *   python, django, fastapi  → python-executor
+ *   java, spring             → java-executor
+ *   flutter, dart            → flutter-executor
+ *   rn, expo, react-native   → react-native-executor
+ *   ios, swift, swiftui      → ios-executor
+ *   android, kotlin          → android-executor
+ *   go, rust, cpp            → systems-executor
+ *   web3, solidity           → web3-executor
+ *   devops, docker           → devops-executor
+ *
+ * Quality Agents:
+ *   tester, qa, test         → tester
+ *   security, audit          → security-auditor
+ *   seo, content             → seo-optimizer
+ *   debugger, debug, fix     → debugger
+ */
+export function resolveAgentIdAlias(agentId: string): string {
+  const clean = agentId.toLowerCase().trim();
+
+  const aliases: Record<string, string> = {
+    // ── Core ─────────────────────────────────────────────────────────────────
+    "plan":               "planner",
+    "orchestrator":       "planner",
+    "pm":                 "planner",
+    "design":             "designer",
+    "ui":                 "designer",
+    "ux":                 "designer",
+
+    // ── Frontend Executors ────────────────────────────────────────────────────
+    "nextjs":             "nextjs-executor",
+    "next":               "nextjs-executor",
+    "next-js":            "nextjs-executor",
+    "react":              "react-executor",
+    "vite":               "react-executor",
+    "react-vite":         "react-executor",
+    "vue":                "vue-executor",
+    "nuxt":               "vue-executor",
+    "vue3":               "vue-executor",
+
+    // ── Backend Executors ─────────────────────────────────────────────────────
+    "laravel":            "laravel-executor",
+    "php":                "laravel-executor",
+    "python":             "python-executor",
+    "django":             "python-executor",
+    "fastapi":            "python-executor",
+    "flask":              "python-executor",
+    "java":               "java-executor",
+    "spring":             "java-executor",
+    "springboot":         "java-executor",
+    "quarkus":            "java-executor",
+    "flutter":            "flutter-executor",
+    "dart":               "flutter-executor",
+    "rn":                 "react-native-executor",
+    "react-native":       "react-native-executor",
+    "expo":               "react-native-executor",
+    "ios":                "ios-executor",
+    "swift":              "ios-executor",
+    "swiftui":            "ios-executor",
+    "android":            "android-executor",
+    "kotlin":             "android-executor",
+    "go":                 "systems-executor",
+    "golang":             "systems-executor",
+    "rust":               "systems-executor",
+    "cpp":                "systems-executor",
+    "c++":                "systems-executor",
+    "systems":            "systems-executor",
+    "web3":               "web3-executor",
+    "solidity":           "web3-executor",
+    "blockchain":         "web3-executor",
+    "devops":             "devops-executor",
+    "docker":             "devops-executor",
+    "cicd":               "devops-executor",
+    "deploy":             "devops-executor",
+
+    // ── Quality Agents ────────────────────────────────────────────────────────
+    "qa":                 "tester",
+    "test":               "tester",
+    "testing":            "tester",
+    "security":           "security-auditor",
+    "audit":              "security-auditor",
+    "pentest":            "security-auditor",
+    "seo":                "seo-optimizer",
+    "content":            "seo-optimizer",
+    "marketing":          "seo-optimizer",
+    "debug":              "debugger",
+    "debugging":          "debugger",
+    "fix":                "debugger",
+  };
+
+  return aliases[clean] || clean;
+}
+
+/**
+ * Get a single agent by ID from a pre-loaded registry.
+ * Throws with a helpful message if not found.
+ */
+export function getAgent(
+  registry: Map<string, LoadedAgent>,
+  agentId: string
+): LoadedAgent {
+  const resolvedId = resolveAgentIdAlias(agentId);
+  const agent = registry.get(resolvedId);
+
+  if (!agent) {
+    const available = [...registry.keys()].join(", ") || "(none)";
+    throw new Error(
+      `❌ Agent "${agentId}" not found (resolved: "${resolvedId}").\n` +
+        `  Available agents: ${available}\n\n` +
+        `  Run "imhcode agent list" to see all agents.`
+    );
+  }
+
+  return agent;
+}

package/src/orchestrator/schema.ts

@@ -0,0 +1,141 @@
+/**
+ * Zod schema for agent.yml manifest validation.
+ * IMH-Code — Imam Hussain Coding Harness Platform
+ * Every agent must pass this schema or an actionable error is thrown.
+ */
+
+import { z } from "zod";
+
+// ─── Sub-schemas ──────────────────────────────────────────────────────────────
+
+const AgentPermissionsSchema = z.object({
+  read_files: z.boolean().default(true),
+  write_files: z.boolean().default(false),
+  run_commands: z.boolean().default(false),
+  network_access: z.boolean().default(false),
+});
+
+const AgentMemorySchema = z.object({
+  scopes: z
+    .array(z.enum(["imhdb", "project", "global", "session"]))
+    .min(1, "At least one memory scope is required"),
+  readable: z.array(z.string()).default([]),
+  writable: z.array(z.string()).default([]),
+});
+
+const AgentOutputSchema = z.object({
+  format: z.string().default("markdown"),
+  include_tests: z.boolean().default(false),
+  test_framework: z.string().optional(),
+});
+
+// ─── Root Manifest Schema ─────────────────────────────────────────────────────
+
+export const AgentManifestSchema = z.object({
+  /** Kebab-case unique identifier. Must match the folder name. */
+  id: z
+    .string()
+    .min(1)
+    .regex(
+      /^[a-z0-9-]+$/,
+      "Agent ID must be kebab-case (lowercase letters, digits, hyphens only)"
+    ),
+
+  name: z.string().min(1, "Agent name is required"),
+
+  description: z.string().min(1, "Agent description is required"),
+
+  version: z
+    .string()
+    .regex(
+      /^\d+\.\d+\.\d+$/,
+      "Version must follow semver format (e.g. 1.0.0)"
+    )
+    .default("1.0.0"),
+
+  role: z.string().min(1, "Agent role is required"),
+
+  /** Path to the SYSTEM.md file, relative to the agent directory */
+  system_prompt: z
+    .string()
+    .default("./SYSTEM.md")
+    .refine(
+      (v) => v.endsWith(".md"),
+      "system_prompt must point to a Markdown (.md) file"
+    ),
+
+  /** Paths to SKILL.md files, relative to the agent directory */
+  skills: z.array(z.string()).default([]),
+
+  preferred_engines: z
+    .array(z.string())
+    .min(1, "At least one preferred engine is required"),
+
+  fallback_engines: z.array(z.string()).default([]),
+
+  default_model: z.string().min(1, "default_model is required"),
+
+  permissions: AgentPermissionsSchema.default({
+    read_files: true,
+    write_files: false,
+    run_commands: false,
+    network_access: false,
+  }),
+
+  memory: AgentMemorySchema.default({
+    scopes: ["session"],
+    readable: [],
+    writable: [],
+  }),
+
+  supported_task_types: z
+    .array(z.string())
+    .min(1, "At least one supported task type is required"),
+
+  /** Array of single-key objects like [{ lighthouse_score: ">= 90" }] */
+  quality_gates: z.array(z.record(z.string(), z.union([z.string(), z.number()]))).default([]),
+
+  output: AgentOutputSchema.default({
+    format: "markdown",
+    include_tests: false,
+  }),
+});
+
+export type AgentManifestInput = z.input<typeof AgentManifestSchema>;
+export type AgentManifestOutput = z.output<typeof AgentManifestSchema>;
+
+/**
+ * Validates a raw YAML-parsed object against the AgentManifest schema.
+ * Returns a well-typed manifest or throws a detailed ZodError.
+ */
+export function validateManifest(
+  raw: unknown,
+  agentId: string
+): AgentManifestOutput {
+  const result = AgentManifestSchema.safeParse(raw);
+
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+        return `  • [${path}] ${issue.message}`;
+      })
+      .join("\n");
+
+    throw new Error(
+      `❌ Invalid agent.yml for agent "${agentId}":\n${issues}\n\n` +
+        `  Fix the fields above and re-run the command.`
+    );
+  }
+
+  // Validate that the id in the YAML matches the folder name
+  if (result.data.id !== agentId) {
+    throw new Error(
+      `❌ Agent ID mismatch for "${agentId}":\n` +
+        `  The "id" field in agent.yml is "${result.data.id}" but the folder is named "${agentId}".\n` +
+        `  They must match exactly.`
+    );
+  }
+
+  return result.data;
+}