agent-enderun 0.9.0 → 0.9.1

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.");
+    }
+}

package/src/cli/commands/init.ts

@@ -0,0 +1,272 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { execSync } from "child_process";
+
+import {
+    resolveAdapter,
+    isAdapterShimFile,
+    remapFrameworkContent,
+    runAdapterPostInit,
+    type AdapterConfig,
+} from "../adapters.js";
+import { getPackageManager, mergePackageJson, deepCleanProtocols, sanitizeJson, getPackageVersion } from "../utils/pkg.js";
+import { updateGitIgnore, ensureDir, writeJsonFile, copyDir } from "../utils/fs.js";
+import { initializeMemory } from "../utils/memory.js";
+import { checkCommand } from "./check.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const sourceDir = path.join(__dirname, "../../..");
+const targetDir = process.cwd();
+
+const FRAMEWORK_VERSION = getPackageVersion();
+
+const CORE_FILES = [
+    ".enderun",
+    "mcp.json",
+    ".env.example",
+    "ENDERUN.md",
+    "package.json",
+    "tsconfig.json",
+    "panda.config.ts",
+    "vitest.config.ts",
+    "framework-mcp",
+    "docs",
+    "eslint.config.js",
+];
+
+const FRAMEWORK_SUBDIRS = [
+    "agents",
+    "agents/schema",
+    "skills",
+    "knowledge",
+    "benchmarks",
+    "monitoring",
+    "logs",
+    "messages",
+    "memory-graph",
+    "memory-graph/agent-contexts",
+    "queue",
+    "queue/pending",
+    "queue/processing",
+    "queue/completed",
+    "queue/failed",
+    "queue/pipelines",
+];
+
+function buildDirsToCreate(adapter: AdapterConfig): string[] {
+    const dirs = [
+        adapter.frameworkDir,
+        ...FRAMEWORK_SUBDIRS.map((d) => `${adapter.frameworkDir}/${d}`),
+        "apps/web",
+        "apps/backend",
+        "docs",
+        "framework-mcp",
+        "tests",
+    ];
+    if (adapter.nestedDirs) {
+        for (const nested of adapter.nestedDirs) {
+            dirs.push(`${adapter.frameworkDir}/${nested}`);
+        }
+    }
+    return [...new Set(dirs)];
+}
+
+/**
+ * Scaffold the framework for a specific IDE adapter (separate runtime folder per IDE).
+ */
+export async function initCommand(adapterInput?: string) {
+    const adapter = resolveAdapter(adapterInput);
+    const { frameworkDir, shimFile, templateDir } = adapter;
+    const targetFrameworkDir = path.join(targetDir, frameworkDir);
+
+    console.warn(`🚀 Installing Agent Enderun (Adapter: ${adapter.id} → ${frameworkDir}/)...`);
+
+    if (!fs.existsSync(targetFrameworkDir)) {
+        fs.mkdirSync(targetFrameworkDir, { recursive: true });
+    }
+
+    for (const dir of buildDirsToCreate(adapter)) {
+        const fullPath = path.join(targetDir, dir);
+        if (!fs.existsSync(fullPath)) {
+            fs.mkdirSync(fullPath, { recursive: true });
+            console.warn(`📂 Created directory: ${dir}`);
+        }
+    }
+
+    const filesToProcess = [
+        ...CORE_FILES,
+        shimFile,
+    ].filter(
+        (f) =>
+            CORE_FILES.includes(f) ||
+      f === shimFile ||
+      fs.existsSync(path.join(sourceDir, f)),
+    );
+
+    ensureDir(path.join(targetDir, "apps/backend"));
+    const initContractPath = path.join(targetDir, "apps/backend/contract.version.json");
+    if (!fs.existsSync(initContractPath)) {
+        writeJsonFile(initContractPath, {
+            contract_hash: "initial_hash_placeholder",
+            last_updated: new Date().toISOString(),
+        });
+    }
+
+    let targetPkg: Record<string, unknown> = {};
+    try {
+        const targetPkgPath = path.join(targetDir, "package.json");
+        if (fs.existsSync(targetPkgPath)) {
+            targetPkg = JSON.parse(fs.readFileSync(targetPkgPath, "utf8"));
+        }
+    } catch {
+    // ignore
+    }
+
+    const pkgName = typeof targetPkg.name === "string" ? targetPkg.name : "";
+    const targetScope = pkgName
+        ? pkgName.startsWith("@")
+            ? pkgName.split("/")[0]
+            : `@${pkgName}`
+        : `@${path.basename(targetDir)}`;
+
+    for (const item of filesToProcess) {
+        const src = path.join(sourceDir, item);
+        let dest = path.join(targetDir, item);
+
+        if (item === "framework-mcp" && fs.existsSync(dest)) {
+            try {
+                fs.rmSync(dest, { recursive: true, force: true });
+            } catch {
+                // ignore
+            }
+        }
+
+        if (item === templateDir || item.startsWith(`${templateDir}/`)) {
+            dest = path.join(targetDir, item.replace(templateDir, frameworkDir));
+        }
+        if (item === "ENDERUN.md") {
+            dest = path.join(targetFrameworkDir, "ENDERUN.md");
+        }
+        if (isAdapterShimFile(item)) {
+            dest = path.join(targetDir, item);
+        }
+
+        if (!fs.existsSync(src)) {
+            continue;
+        }
+
+        if (fs.lstatSync(src).isDirectory()) {
+            const skipFiles =
+        item === templateDir ? ["logs", "PROJECT_MEMORY.md", "PROJECT_MEMORY.lock"] : [];
+            const nonDestructive = ["docs", templateDir].includes(item);
+            copyDir(
+                src,
+                dest,
+                new Set(skipFiles),
+                nonDestructive,
+                frameworkDir,
+                targetScope,
+                sanitizeJson,
+                adapter.id,
+            );
+        } else {
+            if (item === "package.json") continue;
+
+            if (fs.existsSync(dest) && !isAdapterShimFile(item)) {
+                console.warn(`ℹ️  Skipping existing file: ${item}`);
+                continue;
+            }
+
+            const ext = path.extname(item);
+            const textExtensions = [".md", ".json", ".js", ".ts", ".txt", ""];
+            if (textExtensions.includes(ext)) {
+                let content = fs.readFileSync(src, "utf8");
+                content = remapFrameworkContent(content, frameworkDir, adapter.id);
+
+                if (ext === ".json") {
+                    try {
+                        const json = JSON.parse(content);
+                        content = JSON.stringify(sanitizeJson(json, targetScope), null, 2);
+                        content = remapFrameworkContent(content, frameworkDir, adapter.id);
+                    } catch {
+                        content = content.replace(/workspace:[^"'\s]*/g, "*");
+                    }
+                }
+
+                fs.writeFileSync(dest, content);
+            } else {
+                fs.copyFileSync(src, dest);
+            }
+        }
+        console.warn(`✅ ${item} processed -> ${path.relative(targetDir, dest)}`);
+    }
+
+    mergePackageJson(path.join(targetDir, "package.json"), path.join(sourceDir, "package.json"));
+    updateGitIgnore(path.join(targetDir, ".gitignore"), frameworkDir);
+
+    const finalMemoryPath = path.join(targetFrameworkDir, "PROJECT_MEMORY.md");
+    initializeMemory(finalMemoryPath, frameworkDir);
+
+    deepCleanProtocols(targetDir, targetScope);
+
+    const sampleTestPath = path.join(targetDir, "tests/initial.test.ts");
+    if (!fs.existsSync(sampleTestPath)) {
+        fs.writeFileSync(
+            sampleTestPath,
+            `import { describe, it, expect } from "vitest";
+
+describe("Initial Setup", () => {
+  it("should verify the testing environment is active", () => {
+    expect(true).toBe(true);
+  });
+});
+`,
+        );
+    }
+
+    if (!fs.existsSync(path.join(targetDir, ".git"))) {
+        try {
+            execSync("git init", { cwd: targetDir, stdio: "ignore" });
+            console.warn("✅ Git repository initialized.");
+        } catch {
+            // ignore
+        }
+    }
+
+    console.warn(`\n🛠️  Running ${adapter.id} adapter configuration...`);
+    runAdapterPostInit(adapter, targetDir);
+
+    console.warn(`\n♊ ${adapter.id.toUpperCase()}: Setup complete.`);
+    console.warn(`   • Framework runtime: ${frameworkDir}/`);
+    console.warn(`   • Entrypoint shim: ${shimFile}`);
+    if (adapter.nestedDirs?.length) {
+        console.warn(`   • Nested: ${adapter.nestedDirs.map((d) => `${frameworkDir}/${d}/`).join(", ")}`);
+    }
+
+    const pkgMgr = getPackageManager();
+    const installCmd = pkgMgr === "npm" ? "npm install" : `${pkgMgr} install`;
+    const buildCmd = pkgMgr === "npm" ? "npm run enderun:build" : `${pkgMgr} run enderun:build`;
+
+    console.warn(`\n✨ Framework scaffolded! (v${FRAMEWORK_VERSION})`);
+
+    if (process.env.ENDERUN_SKIP_INSTALL === "1") {
+        console.warn("\n⏭️  Skipping install steps (ENDERUN_SKIP_INSTALL=1).");
+        return;
+    }
+
+    try {
+        execSync(installCmd, { stdio: "inherit" });
+        console.warn(`\n🏗️  Step 2/3: Running '${buildCmd}'...`);
+        execSync(buildCmd, { stdio: "inherit" });
+        console.warn("\n🔍 Step 3/3: Running 'agent-enderun check'...");
+        checkCommand();
+        console.warn("\n🚀 Agent Enderun is fully installed and verified!");
+    } catch (e: unknown) {
+        const message = e instanceof Error ? e.message : String(e);
+        console.error("\n❌ Automatic installation failed. Run manually:");
+        console.warn(`👉 ${installCmd} && ${buildCmd}`);
+        console.error(message);
+    }
+}

package/src/cli/commands/knowledge.ts

@@ -0,0 +1,44 @@
+import fs from "fs";
+import path from "path";
+
+import { getFrameworkDir } from "../utils/memory.js";
+
+const targetDir = process.cwd(); // Assuming targetDir is process.cwd() in the CLI context
+
+export function updateKnowledgeBaseCommand(topic: string, content: string) {
+    if (!topic || !content) {
+        console.error("❌ Usage: agent-enderun update_knowledge_base <topic> <content>");
+        return;
+    }
+    const frameworkDir = getFrameworkDir();
+    const kbDir = path.join(targetDir, frameworkDir, "knowledge");
+    if (!fs.existsSync(kbDir)) fs.mkdirSync(kbDir, { recursive: true });
+    const fileName = topic.replace(/[^a-z0-9]/gi, "_").toLowerCase() + ".md";
+    fs.writeFileSync(path.join(kbDir, fileName), content);
+    console.warn(`✅ Knowledge base updated: ${topic}`);
+}
+
+export function searchKnowledgeBaseCommand(query: string) {
+    if (!query) {
+        console.error("❌ Usage: agent-enderun search_knowledge_base <query>");
+        return;
+    }
+    const frameworkDir = getFrameworkDir();
+    const kbDir = path.join(targetDir, frameworkDir, "knowledge");
+    if (!fs.existsSync(kbDir)) {
+        console.warn("ℹ️ Knowledge base is empty.");
+        return;
+    }
+    const files = fs.readdirSync(kbDir).filter(f => f.endsWith(".md"));
+    let found = false;
+    for (const file of files) {
+        const content = fs.readFileSync(path.join(kbDir, file), "utf-8");
+        if (content.toLowerCase().includes(query.toLowerCase()) || file.toLowerCase().includes(query.toLowerCase())) {
+            console.warn(`
+### ${file.replace(".md", "")}
+${content.slice(0, 300)}...`);
+            found = true;
+        }
+    }
+    if (!found) console.warn("ℹ️ No matching entries found.");
+}

package/src/cli/commands/lint.ts

@@ -0,0 +1,25 @@
+import { execSync } from "child_process";
+
+import { getPackageVersion } from "../utils/pkg.js";
+
+const FRAMEWORK_VERSION = getPackageVersion();
+
+/**
+ * Run ESLint for the project (same as npm run lint).
+ */
+export function lintCommand(): void {
+    console.warn(`🔍 Running ESLint (v${FRAMEWORK_VERSION})...`);
+    const projectRoot = process.cwd();
+    try {
+        execSync("npm run lint", {
+            cwd: projectRoot,
+            stdio: "inherit",
+            env: process.env,
+        });
+        console.warn("\n✅ ESLint passed with no errors.");
+    } catch {
+        console.warn("\n❌ ESLint reported errors. Fix violations before committing.");
+        console.warn("   Tip: npm run lint -- --fix");
+        process.exit(1);
+    }
+}

package/src/cli/commands/log.ts

@@ -0,0 +1,37 @@
+import fs from "fs";
+import path from "path";
+
+import { getFrameworkDir } from "../utils/memory.js";
+import { normalizeAgentName } from "../utils/string.js";
+
+const targetDir = process.cwd(); // Assuming targetDir is process.cwd() in the CLI context
+
+export function logAgentActionCommand(data: { agent?: unknown; action?: string; requestId?: string; status?: string; summary?: string; files?: string[]; details?: Record<string, unknown> }) {
+    const frameworkDir = getFrameworkDir();
+    const logsDir = path.join(targetDir, frameworkDir, "logs");
+    if (!fs.existsSync(logsDir)) {
+        fs.mkdirSync(logsDir, { recursive: true });
+    }
+
+    const agent = normalizeAgentName(data.agent);
+    const logPath = path.join(logsDir, `${agent}.json`);
+    let logs: Record<string, unknown>[] = [];
+
+    if (fs.existsSync(logPath)) {
+        try {
+            logs = JSON.parse(fs.readFileSync(logPath, "utf8"));
+            if (!Array.isArray(logs)) logs = [];
+        } catch {
+            logs = [];
+        }
+    }
+
+    const newEntry = {
+        timestamp: new Date().toISOString(),
+        ...data,
+    };
+
+    logs.push(newEntry);
+    fs.writeFileSync(logPath, JSON.stringify(logs, null, 2));
+    console.warn(`✅ Logged action to ${frameworkDir}/logs/${agent}.json`);
+}