agent-enderun 0.9.0 → 0.9.2

package/src/cli/adapters.ts

@@ -0,0 +1,208 @@
+import path from "path";
+import fs from "fs";
+
+import { findClaudeConfigPath, addMcpServerToClaude } from "./utils/claude.js";
+import { writeJsonFile, writeTextFile } from "./utils/fs.js";
+
+export const ADAPTER_IDS = ["gemini", "claude", "grok", "antigravity", "antigravity-cli"] as const;
+export type AdapterId = (typeof ADAPTER_IDS)[number];
+
+export interface AdapterConfig {
+  id: AdapterId;
+  /** Runtime framework directory created by init */
+  frameworkDir: string;
+  /** Root shim file (e.g. gemini.md) */
+  shimFile: string;
+  /** Package template copied into frameworkDir */
+  templateDir: ".enderun";
+  /** Extra directories under frameworkDir (gemini only for nested auto-scaffold) */
+  nestedDirs?: string[];
+}
+
+export const ADAPTERS: Record<AdapterId, AdapterConfig> = {
+    gemini: {
+        id: "gemini",
+        frameworkDir: ".gemini",
+        shimFile: "gemini.md",
+        templateDir: ".enderun",
+        nestedDirs: ["antigravity", "antigravity-cli"],
+    },
+    claude: {
+        id: "claude",
+        frameworkDir: ".claude",
+        shimFile: "claude.md",
+        templateDir: ".enderun",
+    },
+    grok: {
+        id: "grok",
+        frameworkDir: ".agent", // Future-proof agent-centric directory for Grok/X.ai
+        shimFile: "grok.md",
+        templateDir: ".enderun",
+    },
+    antigravity: {
+        id: "antigravity",
+        frameworkDir: ".gemini/antigravity",
+        shimFile: "agent.md",
+        templateDir: ".enderun",
+    },
+    "antigravity-cli": {
+        id: "antigravity-cli",
+        frameworkDir: ".gemini/antigravity-cli",
+        shimFile: "agent.md",
+        templateDir: ".enderun",
+    },
+};
+
+/** 
+ * All framework runtime directories (for discovery). 
+ * Verified against 2026 industry standards for Claude Code (.claude/)
+ * and internal standards for Antigravity (.gemini/antigravity/).
+ */
+export const FRAMEWORK_DIR_CANDIDATES = [
+    ".gemini",
+    ".claude",
+    ".agent",
+    ".enderun",
+] as const;
+
+const SHIM_FILES = ADAPTER_IDS.map((id) => ADAPTERS[id].shimFile);
+
+export function resolveAdapter(input?: string): AdapterConfig {
+    const normalized = (input || "gemini").toLowerCase() as AdapterId;
+    if (ADAPTER_IDS.includes(normalized)) {
+        return ADAPTERS[normalized];
+    }
+    console.warn(`⚠️  Unknown adapter "${input}". Falling back to gemini (.gemini/).`);
+    return ADAPTERS.gemini;
+}
+
+export function isAdapterShimFile(fileName: string): boolean {
+    return SHIM_FILES.includes(fileName);
+}
+
+export function remapFrameworkContent(
+    content: string,
+    frameworkDir: string,
+    adapterId: AdapterId,
+): string {
+    let result = content;
+    result = result.replace(/\{\{FRAMEWORK_DIR\}\}/g, frameworkDir);
+    result = result.replace(/\{\{ADAPTER\}\}/g, adapterId);
+    result = result.replace(/\.enderun\//g, `${frameworkDir}/`);
+    result = result.replace(/`\.enderun`/g, `\`${frameworkDir}\``);
+    result = result.replace(/\.enderun(?![\w/-])/g, frameworkDir);
+
+    // Read config paths dynamically to map directory tokens
+    let backend = "apps/backend";
+    let frontend = "apps/web";
+    let docs = "docs";
+    let tests = "tests";
+    try {
+        const configPath = path.join(process.cwd(), frameworkDir, "config.json");
+        if (fs.existsSync(configPath)) {
+            const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+            if (config.paths) {
+                if (config.paths.backend) backend = config.paths.backend;
+                if (config.paths.frontend) frontend = config.paths.frontend;
+                if (config.paths.docs) docs = config.paths.docs;
+                if (config.paths.tests) tests = config.paths.tests;
+            }
+        }
+    } catch {
+        // ignore
+    }
+
+    result = result.replace(/\{\{BACKEND_DIR\}\}/g, backend);
+    result = result.replace(/\{\{FRONTEND_DIR\}\}/g, frontend);
+    result = result.replace(/\{\{DOCS_DIR\}\}/g, docs);
+    result = result.replace(/\{\{TESTS_DIR\}\}/g, tests);
+
+    return result;
+}
+
+export function buildMcpServerEntry(projectRoot: string) {
+    return {
+        command: "node",
+        args: [path.join(projectRoot, "framework-mcp/dist/index.js")],
+        env: {},
+    };
+}
+
+function writeAntigravityScaffold(frameworkDirPath: string): void {
+    const antigravityReadme = `# Antigravity IDE — Agent Enderun
+
+Antigravity IDE integration for the Gemini adapter.
+
+- Framework root: \`${path.basename(frameworkDirPath)}/\`
+- Nested path: \`antigravity/\`
+- Use the parent \`mcp_config.json\` and \`gemini.md\` entrypoint at the project root.
+`;
+
+    const antigravityCliReadme = `# Antigravity CLI — Agent Enderun
+
+Antigravity CLI integration for the Gemini adapter.
+
+- Framework root: \`${path.basename(frameworkDirPath)}/\`
+- Nested path: \`antigravity-cli/\`
+- Register MCP from the project root \`mcp.json\` or \`.gemini/mcp_config.json\`.
+`;
+
+    writeTextFile(path.join(frameworkDirPath, "antigravity/README.md"), antigravityReadme);
+    writeTextFile(path.join(frameworkDirPath, "antigravity-cli/README.md"), antigravityCliReadme);
+}
+
+/**
+ * Adapter-specific MCP and IDE hooks after scaffold.
+ */
+export function runAdapterPostInit(adapter: AdapterConfig, projectRoot: string): void {
+    const mcpEntry = buildMcpServerEntry(projectRoot);
+    const mcpBlock = { mcpServers: { "agent-enderun": mcpEntry } };
+
+    switch (adapter.id) {
+    case "gemini": {
+        writeJsonFile(path.join(projectRoot, adapter.frameworkDir, "mcp_config.json"), mcpBlock);
+        writeAntigravityScaffold(path.join(projectRoot, adapter.frameworkDir));
+        console.warn(`✅ Gemini MCP → ${adapter.frameworkDir}/mcp_config.json`);
+        console.warn(`✅ Antigravity → ${adapter.frameworkDir}/antigravity/ & antigravity-cli/`);
+        break;
+    }
+    case "antigravity": {
+        writeJsonFile(path.join(projectRoot, adapter.frameworkDir, "mcp_config.json"), mcpBlock);
+        console.warn(`✅ Antigravity IDE MCP → ${adapter.frameworkDir}/mcp_config.json`);
+        break;
+    }
+    case "antigravity-cli": {
+        writeJsonFile(path.join(projectRoot, adapter.frameworkDir, "mcp_config.json"), mcpBlock);
+        console.warn(`✅ Antigravity CLI MCP → ${adapter.frameworkDir}/mcp_config.json`);
+        break;
+    }
+    case "grok": {
+        writeJsonFile(path.join(projectRoot, adapter.frameworkDir, "mcp_config.json"), mcpBlock);
+        console.warn(`✅ Grok MCP → ${adapter.frameworkDir}/mcp_config.json`);
+        break;
+    }
+    case "claude": {
+        const configPath = findClaudeConfigPath();
+        if (configPath) {
+            const ok = addMcpServerToClaude(configPath, "agent-enderun", mcpEntry);
+            if (ok) {
+                console.warn(`✅ Claude MCP registered → ${configPath}`);
+            } else {
+                console.warn("⚠️  Could not patch Claude config automatically.");
+            }
+        } else {
+            console.warn("⚠️  Claude config not found. Add MCP manually (see README).");
+        }
+        writeJsonFile(path.join(projectRoot, adapter.frameworkDir, "mcp_config.json"), mcpBlock);
+        break;
+    }
+    default:
+        break;
+    }
+
+    // Keep root mcp.json in sync when missing or empty
+    const rootMcpPath = path.join(projectRoot, "mcp.json");
+    if (!fs.existsSync(rootMcpPath)) {
+        writeJsonFile(rootMcpPath, mcpBlock);
+    }
+}

package/src/cli/commands/app.ts

@@ -0,0 +1,38 @@
+import fs from "fs";
+
+import { updateMemoryForGeneratedApp, collectCreateAppDescription, inferAppSpec, createBackendFiles, createWebFiles, updateProjectDocs } from "../utils/app.js";
+import { traceNewCommand } from "./trace.js";
+import { getMemoryPath } from "../utils/memory.js";
+
+/**
+ * Generate a new application based on natural language input.
+ */
+export async function createAppCommand(args: string[]) {
+    const description = await collectCreateAppDescription(args);
+    const spec = inferAppSpec(description);
+
+    console.warn(`🚀 Generating Enterprise App: ${spec.title}...`);
+
+    createBackendFiles(spec);
+    createWebFiles(spec);
+    updateProjectDocs(spec);
+
+    const memoryPath = getMemoryPath();
+    let traceId = "01HGT8J5E2N0W0W0W0W0W0W0W0"; // default fallback
+
+    if (fs.existsSync(memoryPath)) {
+        const memory = fs.readFileSync(memoryPath, "utf8");
+        const match = memory.match(/- Trace ID: (.*)/);
+        if (match) traceId = match[1].trim();
+    }
+
+    const activeTraceId = traceNewCommand(`Generate ${spec.title} from natural language request`, "manager", "P1") || traceId;
+    updateMemoryForGeneratedApp(spec, activeTraceId);
+
+    console.warn("\n✨ Application scaffolded successfully!");
+    console.warn("📜 Updated project docs and app-local types contract");
+    console.warn("\nNext commands:");
+    console.warn("  npm install");
+    console.warn("  npm run enderun:build");
+    console.warn("  agent-enderun frontend:dev\n");
+}

package/src/cli/commands/check.ts

@@ -0,0 +1,87 @@
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+
+import { getFrameworkDir, getConfiguredPaths } from "../utils/memory.js";
+import { getPackageVersion } from "../utils/pkg.js"; // To get FRAMEWORK_VERSION
+
+const FRAMEWORK_VERSION = getPackageVersion();
+
+/**
+ * Check framework health and MCP status.
+ */
+export function checkCommand() {
+    console.warn(`🔍 Checking Agent Enderun Health (v${FRAMEWORK_VERSION})...`);
+    let issues = 0;
+
+    const frameworkDir = getFrameworkDir();
+    const pathsMap = getConfiguredPaths();
+  
+    const constitutionPath = fs.existsSync(path.join(process.cwd(), "ENDERUN.md"))
+        ? "ENDERUN.md"
+        : path.join(frameworkDir, "ENDERUN.md");
+
+    const checks = [
+        { name: "Constitution (ENDERUN.md)", path: constitutionPath },
+        { name: "Memory (PROJECT_MEMORY.md)", path: path.join(frameworkDir, "PROJECT_MEMORY.md") },
+        { name: "Command Map (cli-commands.json)", path: path.join(frameworkDir, "cli-commands.json") },
+        { name: "Framework Config (config.json)", path: path.join(frameworkDir, "config.json") },
+        { name: "Agent Status (STATUS.md)", path: path.join(frameworkDir, "STATUS.md") },
+        { name: "MCP Config (mcp.json)", path: "mcp.json" },
+        { name: "ESLint Config (eslint.config.js)", path: "eslint.config.js" },
+        { name: "ESLint Standards", path: path.join(frameworkDir, "knowledge/eslint-standards.md") },
+        { name: "Backend Contract", path: path.join(pathsMap.backend, "contract.version.json") },
+        { name: "MCP Server", path: "framework-mcp/package.json" },
+        { name: "Panda CSS Config", path: "panda.config.ts" },
+        { name: "Brain Dashboard", path: path.join(frameworkDir, "BRAIN_DASHBOARD.md") },
+        { name: "Project Architectural Portal (docs/README.md)", path: path.join(pathsMap.docs, "README.md") },
+        { name: "System Getting Started Guide (docs/getting-started.md)", path: path.join(pathsMap.docs, "getting-started.md") },
+        { name: "Enterprise Approval Flows Protocol", path: path.join(pathsMap.docs, "architecture/approval-flows.md") },
+        { name: "Professional Error Handling Pattern", path: path.join(pathsMap.docs, "backend/error-handling.md") },
+        { name: "Atomic Component Standards", path: path.join(pathsMap.docs, "frontend/component-patterns.md") },
+    ];
+
+    for (const check of checks) {
+        if (fs.existsSync(path.join(process.cwd(), check.path))) {
+            console.warn(`✅ ${check.name} found.`);
+        } else {
+            console.warn(`❌ ${check.name} MISSING! (${check.path})`);
+            issues++;
+        }
+    }
+
+    // Dependency Check
+    const mcpNodeModules = path.join(process.cwd(), "framework-mcp/node_modules");
+    const rootNodeModules = path.join(process.cwd(), "node_modules");
+    if (!fs.existsSync(mcpNodeModules) && !fs.existsSync(rootNodeModules)) {
+        console.warn("❌ Dependencies MISSING! (Run 'npm install')");
+        issues++;
+    } else {
+        console.warn("✅ Dependencies found.");
+    }
+
+    // MCP Build Check
+    const mcpPath = path.join(process.cwd(), "framework-mcp/dist/index.js");
+    if (!fs.existsSync(mcpPath)) {
+        console.warn("❌ MCP Build MISSING! (Run 'npm run enderun:build')");
+        issues++;
+    } else {
+        console.warn("✅ MCP Build found.");
+        console.warn("⏳ Testing MCP Server syntax...");
+        try {
+            execSync(`node --check ${mcpPath}`, { stdio: "pipe" });
+            console.warn("✅ MCP Server syntax valid.");
+        } catch {
+            // If --check fails on ESM, we might skip it or use a better check
+            console.warn("⚠️  MCP Syntax check skipped (ESM/Environment).");
+        }
+    }
+
+    if (issues === 0) {
+        console.warn("\n🚀 All systems green! Agent Enderun is ready for orchestration.");
+    } else {
+        console.warn(`
+⚠️  Found ${issues} issues. Please fix them before starting.`);
+        process.exit(1);
+    }
+}

package/src/cli/commands/compliance.ts

@@ -0,0 +1,55 @@
+import fs from "fs";
+import path from "path";
+
+import { collectFiles } from "../utils/fs.js";
+
+const targetDir = process.cwd(); // Assuming targetDir is process.cwd() in the CLI context
+
+export function complianceCheckCommand(targetPath: string) {
+    console.warn(`📜 Checking Constitution Compliance: ${targetPath}...`);
+    const violations: string[] = [];
+    const forbidden = ["@shadcn", "mui", "@chakra-ui", "tailwindcss"];
+
+    // 1. package.json scan (Blind Spot 5)
+    const pkgJsonPath = path.join(targetDir, "package.json");
+    if (fs.existsSync(pkgJsonPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8"));
+            const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+            forbidden.forEach(lib => {
+                if (allDeps[lib] || Object.keys(allDeps).some(d => d.toLowerCase().includes(lib.toLowerCase()))) {
+                    violations.push(`package.json: Forbidden library dependency '${lib}' found in package.json.`);
+                }
+            });
+        } catch {
+            // ignore
+        }
+    }
+
+    // 2. Source files scan
+    const files = collectFiles(path.join(targetDir, targetPath), [".ts", ".tsx", ".js", ".jsx", ".md"]);
+    files.forEach(f => {
+        const isTypesFile = f.includes("brands.ts") || f.includes("brands.js") || f.includes("brands.tsx") || f.includes("src/types/brands");
+
+        const content = fs.readFileSync(f, "utf8");
+        forbidden.forEach(lib => {
+            if (content.includes(lib)) violations.push(`${path.relative(targetDir, f)}: Forbidden library '${lib}' found.`);
+        });
+
+        // Robust Branded Types validation (Blind Spot 4)
+        if ((f.endsWith(".ts") || f.endsWith(".tsx")) && !isTypesFile && content.includes("interface")) {
+            const plainIdMatches = content.match(/\b\w*(?:id|Id|ID)\??\s*:\s*(?:string|number)\b/g);
+            if (plainIdMatches) {
+                plainIdMatches.forEach(match => {
+                    violations.push(`${path.relative(targetDir, f)}: Potential Branded Types violation (plain identifier '${match.trim()}' found inside interface).`);
+                });
+            }
+        }
+    });
+
+    if (violations.length === 0) {
+        console.warn("✅ All systems compliant with ENDERUN.md.");
+    } else {
+        violations.forEach(v => console.warn(`❌ ${v}`));
+    }
+}

package/src/cli/commands/contract.ts

@@ -0,0 +1,45 @@
+import path from "path";
+import fs from "fs";
+import crypto from "crypto";
+import { getConfiguredPaths } from "../utils/memory.js";
+
+/**
+ * Verify type safety between backend and frontend contracts.
+ */
+export function verifyApiContractCommand() {
+    const projectRoot = process.cwd();
+    const pathsMap = getConfiguredPaths();
+    const sharedDir = path.join(projectRoot, pathsMap.backend, "src/types");
+    const contractPath = path.join(projectRoot, pathsMap.backend, "contract.version.json");
+
+    if (!fs.existsSync(sharedDir) || !fs.existsSync(contractPath)) {
+        console.error("❌ Error: API types or contract version file missing.");
+        return;
+    }
+
+    const walk = (d: string): string[] => fs.readdirSync(d, { withFileTypes: true }).flatMap((e) => {
+        const fullPath = path.join(d, e.name);
+        return e.isDirectory() ? walk(fullPath) : (e.name.endsWith(".ts") ? [fullPath] : []);
+    });
+
+    const hash = crypto.createHash("sha256");
+    for (const filePath of walk(sharedDir).sort()) {
+        hash.update(path.relative(projectRoot, filePath));
+        hash.update("\0");
+        hash.update(fs.readFileSync(filePath));
+        hash.update("\0");
+    }
+
+    const currentHash = hash.digest("hex");
+    const contract = JSON.parse(fs.readFileSync(contractPath, "utf8"));
+
+    if (contract.contract_hash === currentHash) {
+        console.warn("✅ Contract is valid and synchronized.");
+    } else {
+        console.error("❌ Error: Contract drift detected!");
+        console.error(`   Stored: ${contract.contract_hash}`);
+        console.error(`   Actual: ${currentHash}`);
+        console.warn("\n👉 Run 'npm run update-contract' to re-sync.");
+        process.exit(1);
+    }
+}

package/src/cli/commands/explorer.ts

@@ -0,0 +1,45 @@
+import fs from "fs";
+import path from "path";
+
+import { collectFiles } from "../utils/fs.js";
+
+const targetDir = process.cwd();
+
+export function explorerGraphCommand(targetPath: string) {
+    console.warn(`🗺️  Generating Dependency Graph for: ${targetPath}...`);
+    const files = collectFiles(path.join(targetDir, targetPath), [".ts", ".tsx"]);
+    const edges: string[] = [];
+    files.forEach((f) => {
+        const content = fs.readFileSync(f, "utf8");
+        const name = path.basename(f, path.extname(f));
+        const imports = content.match(/from\s+['"]\.\.?\/[^'"]+['"]/g) || [];
+        imports.forEach((imp) => {
+            const target = path.basename(imp.split(/['"]/)[1]);
+            edges.push(`${name} --> ${target}`);
+        });
+    });
+    if (edges.length === 0) {
+        console.warn("ℹ️ No internal dependencies found.");
+    } else {
+        console.warn(
+            "```mermaid\ngraph TD\n" + Array.from(new Set(edges)).join("\n") + "\n```",
+        );
+    }
+}
+
+export function explorerAuditCommand(targetPath: string) {
+    console.warn(`🧠 Codebase Intelligence Scan: ${targetPath}...`);
+    const files = collectFiles(path.join(targetDir, targetPath), [".ts", ".tsx"]);
+    const complexity: string[] = [];
+    files.forEach((f) => {
+        const content = fs.readFileSync(f, "utf8");
+        const lines = content.split("\n").length;
+        if (lines > 300) complexity.push(`${path.relative(targetDir, f)} (${lines} lines)`);
+    });
+    if (complexity.length > 0) {
+        console.warn("\n⚠️ Complexity Spikes:");
+        complexity.forEach((c) => console.warn(`- ${c}`));
+    } else {
+        console.warn("✅ Codebase structure looks clean.");
+    }
+}

package/src/cli/commands/git.ts

@@ -0,0 +1,39 @@
+import cp from "child_process";
+import path from "path";
+import { getConfiguredPaths } from "../utils/memory.js";
+
+export function gitCommitCommand(traceId: string) {
+    try {
+        const diff = cp.execSync("git diff --staged", { encoding: "utf8" });
+        if (!diff) {
+            console.warn("ℹ️ No staged changes found. Use 'git add' first.");
+            return;
+        }
+        const files = cp.execSync("git diff --staged --name-only", { encoding: "utf8" })
+            .split("\n")
+            .filter(Boolean);
+        const pathsMap = getConfiguredPaths();
+        const backendTypesPath = path.join(pathsMap.backend, "src/types");
+        let type = "feat";
+        const scope = "code";
+        if (files.some((f) => f.includes(".md"))) type = "docs";
+        else if (files.some((f) => f.includes(backendTypesPath))) type = "arch";
+        else if (files.some((f) => f.includes("bin/cli.js"))) type = "fix";
+
+        const summary =
+      files.length === 1 ? `update ${path.basename(files[0])}` : `update ${files.length} files`;
+        console.warn(`\n### SUGGESTED COMMIT MESSAGE ###\n\n[${traceId}] ${type}(${scope}): ${summary}\n`);
+    } catch {
+        console.warn("❌ Git command failed.");
+    }
+}
+
+export function gitSyncCommand() {
+    console.warn("🔄 Syncing with remote repository...");
+    try {
+        cp.execSync("git pull origin main --rebase", { stdio: "inherit" });
+        console.warn("✅ Successfully synced and rebased.");
+    } catch {
+        console.warn("❌ Sync failed. Please resolve conflicts manually.");
+    }
+}