agent-enderun 0.9.4 → 1.0.0

package/framework-mcp/src/tools/messaging/send_message.ts

@@ -0,0 +1,26 @@
+import fs from "fs";
+import path from "path";
+import { resolveFrameworkDir } from "../../utils/security.js";
+import { ToolArgs, ToolResult } from "../types.js";
+
+export function handleSendAgentMessage(projectRoot: string, args: ToolArgs): ToolResult {
+    const { to, category, content, traceId } = args as Required<Pick<ToolArgs, "to" | "category" | "content" | "traceId">>;
+    const frameworkDir = resolveFrameworkDir(projectRoot);
+    const agentName = to.replace("@", "");
+    const messagePath = path.join(projectRoot, frameworkDir, "messages", `${agentName}.json`);
+
+    const message = {
+        timestamp: new Date().toISOString(),
+        from: "@mcp",
+        to,
+        category,
+        traceId,
+        content,
+        status: "PENDING"
+    };
+
+    fs.mkdirSync(path.dirname(messagePath), { recursive: true });
+    fs.appendFileSync(messagePath, JSON.stringify(message) + "\n");
+
+    return { content: [{ type: "text", text: `✅ Message sent to ${to}` }] };
+}

package/framework-mcp/src/tools/types.ts

@@ -0,0 +1,40 @@
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, { type: string; description?: string; enum?: string[] }>;
+        required?: string[];
+    };
+}
+
+export interface CallToolRequest {
+    params: {
+        name: string;
+        arguments?: ToolArgs;
+    };
+}
+
+export interface ToolArgs {
+    path?: string;
+    content?: string;
+    oldText?: string;
+    newText?: string;
+    startLine?: number;
+    endLine?: number;
+    newContent?: string;
+    section?: string;
+    to?: string;
+    category?: "ACTION" | "DELEGATION" | "INFO" | "ALERT";
+    traceId?: string;
+    agent?: string;
+    action?: string;
+    status?: "SUCCESS" | "FAILURE";
+    summary?: string;
+    findings?: string;
+}
+
+export interface ToolResult {
+    isError?: boolean;
+    content: Array<{ type: "text"; text: string }>;
+}

package/framework-mcp/src/utils/cli.ts

@@ -0,0 +1,20 @@
+import { execFileSync } from "child_process";
+
+/**
+ * Executes a CLI command safely using execFileSync (no shell injection risk).
+ * Captures stderr gracefully to prevent stream crashes.
+ */
+export function safeExec(command: string, args: string[], cwd: string): string {
+    try {
+        return execFileSync(command, args, {
+            cwd,
+            encoding: "utf8",
+            timeout: 30000,
+            maxBuffer: 1024 * 1024,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+    } catch (error: unknown) {
+        const err = error as { stderr?: string; message?: string };
+        throw new Error(err.stderr || err.message || "Command execution failed", { cause: error });
+    }
+}

package/framework-mcp/src/utils/security.ts

@@ -0,0 +1,41 @@
+import path from "path";
+import fs from "fs";
+
+/**
+ * Validates and resolves a user-provided path to prevent path traversal attacks.
+ * Ensures the resolved path stays within the project root boundary.
+ */
+export function safePath(projectRoot: string, userPath: string): string {
+    const resolved = path.resolve(projectRoot, userPath);
+    const normalizedRoot = path.resolve(projectRoot);
+
+    if (!resolved.startsWith(normalizedRoot + path.sep) && resolved !== normalizedRoot) {
+        throw new Error(`Access denied: path "${userPath}" escapes project root.`);
+    }
+
+    return resolved;
+}
+
+/**
+ * Resolves the active framework directory by scanning known candidates.
+ */
+export function resolveFrameworkDir(projectRoot: string): string {
+    const candidates = [
+        ".gemini/antigravity",
+        ".gemini/antigravity-cli",
+        ".gemini",
+        ".claude",
+        ".grok",
+        ".agent",
+        ".enderun",
+    ];
+
+    for (const candidate of candidates) {
+        const candidatePath = path.join(projectRoot, candidate);
+        if (fs.existsSync(candidatePath)) {
+            return candidate;
+        }
+    }
+
+    return ".enderun";
+}

package/gemini.md

@@ -2,7 +2,7 @@
 
 This is the primary entry point when using Agent Enderun within the Gemini CLI ecosystem.
 
-The framework operates under a unified governance structure located in the `.enderun/` directory.
+The framework operates under a unified governance structure located in the .enderun/ directory.
 
 ### Primary Constitution
 All governance rules, agent checklists, and project memory live here:
@@ -17,9 +17,15 @@ At the **start of every session**, before any work:
 2. **Load Identity:** Read the relevant agent definition under `.enderun/agents/{agent}.md` (default to `@manager`).
 3. **Internalize Knowledge:** Reference the `.enderun/knowledge/` base for architectural and coding standards.
 
+### 💾 Memory Tiers
+- **Project Memory (Shared):** `.enderun/PROJECT_MEMORY.md` is the source of truth for task history, Trace IDs, and architectural decisions. **Update this at the end of every turn.**
+- **Private Memory (User-Specific):** Use the system's temporary directory memory folder for personal workflows or user-specific notes that should not be committed to Git.
+- **Project Instructions:** This `gemini.md` file contains the "Supreme Law" and coding standards.
+
 ### 🛡️ Core Mandates
 - **Surgical Edits:** Use `replace_text` or `patch_file` via MCP for precise changes.
 - **Traceability:** Every action must inherit the active Trace ID from memory.
 - **Contract First:** No implementation without verified types.
+- **NEVER FORGET:** @manager MUST update `.enderun/PROJECT_MEMORY.md` at the end of EVERY session without exception. This is a non-negotiable process integrity rule.
 
 All paths and references inside the project must comply with the Supreme Constitution located at `.enderun/ENDERUN.md`.

package/grok.md

@@ -2,7 +2,7 @@
 
 This is the primary entry point when using Agent Enderun within the Grok / X.ai ecosystem.
 
-The framework operates under a unified governance structure located in the `.enderun/` directory.
+The framework operates under a unified governance structure located in the .enderun/ directory.
 
 ### Primary Constitution
 All governance rules, agent checklists, and project memory live here:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-enderun",
-  "version": "0.9.4",
+  "version": "1.0.0",
   "description": "The Supreme AI Governance & Orchestration Framework for Enterprise Development",
   "author": "Yusuf BEKAR",
   "license": "MIT",
@@ -82,7 +82,8 @@
     "zod": "^3.24.2"
   },
   "enderun": {
-    "version": "0.9.0",
-    "initializedAt": "2026-05-29T13:21:18.516Z"
-  }
-}
+    "version": "1.0.0",
+    "initializedAt": "2026-05-31T09:58:25.773Z"
+  },
+  "dependencies": {}
+}

package/src/cli/adapters.ts

@@ -25,46 +25,47 @@ export const ADAPTERS: Record<AdapterId, AdapterConfig> = {
         frameworkDir: ".gemini",
         shimFile: "gemini.md",
         templateDir: ".enderun",
-        nestedDirs: ["antigravity", "antigravity-cli"],
+        nestedDirs: ["agents", "skills", "knowledge"],
     },
     claude: {
         id: "claude",
         frameworkDir: ".claude",
         shimFile: "claude.md",
         templateDir: ".enderun",
+        nestedDirs: ["agents", "skills", "knowledge"],
     },
     grok: {
         id: "grok",
-        frameworkDir: ".grok", // Standard config directory for Grok/X.ai agent
+        frameworkDir: ".grok",
         shimFile: "grok.md",
         templateDir: ".enderun",
+        nestedDirs: ["plugins", "knowledge"],
     },
     antigravity: {
         id: "antigravity",
-        frameworkDir: ".gemini/antigravity",
+        frameworkDir: ".agent",
         shimFile: "agent.md",
         templateDir: ".enderun",
+        nestedDirs: ["skills", "workflows", "rules", "knowledge"],
     },
     "antigravity-cli": {
         id: "antigravity-cli",
         frameworkDir: ".gemini/antigravity-cli",
         shimFile: "agent.md",
         templateDir: ".enderun",
+        nestedDirs: ["agents", "skills"],
     },
 };
 
 /** 
  * All framework runtime directories (for discovery). 
- * Verified against 2026 industry standards for Claude Code (.claude/)
- * and internal standards for Antigravity (.gemini/antigravity/).
+ * Verified against 2026 industry standards.
  */
 export const FRAMEWORK_DIR_CANDIDATES = [
-    ".gemini/antigravity",
-    ".gemini/antigravity-cli",
+    ".agent",
     ".gemini",
     ".claude",
     ".grok",
-    ".agent",
     ".enderun",
 ] as const;
 
@@ -89,8 +90,28 @@ export function remapFrameworkContent(
     adapterId: AdapterId,
 ): string {
     let result = content;
+
+    // 1. Dynamic Agent Folder Mapping based on adapter
+    let agentFolder = "agents";
+    let knowledgeFolder = "knowledge";
+    
+    if (adapterId === "antigravity") {
+        agentFolder = "skills";
+        knowledgeFolder = "rules";
+    } else if (adapterId === "grok") {
+        agentFolder = "plugins";
+    }
+
+    // 2. Replacements
     result = result.replace(/\{\{FRAMEWORK_DIR\}\}/g, frameworkDir);
     result = result.replace(/\{\{ADAPTER\}\}/g, adapterId);
+    
+    // Replace standard patterns with adapter-specific ones
+    const frameworkPattern = ".enderun/";
+    result = result.replace(new RegExp(frameworkPattern + "agents/", "g"), `${frameworkDir}/${agentFolder}/`);
+    result = result.replace(new RegExp(frameworkPattern + "knowledge/", "g"), `${frameworkDir}/${knowledgeFolder}/`);
+    
+    // Generic fallback for other .enderun/ paths
     result = result.replace(/\.enderun\//g, `${frameworkDir}/`);
     result = result.replace(/`\.enderun`/g, `\`${frameworkDir}\``);
     result = result.replace(/\.enderun(?![\w/-])/g, frameworkDir);

package/src/cli/commands/check.ts

@@ -16,6 +16,12 @@ export function checkCommand() {
 
     const frameworkDir = getFrameworkDir();
     const pathsMap = getConfiguredPaths();
+
+    // Determine folder names based on adapter detection
+    let knowledgeDir = "knowledge";
+    if (frameworkDir === ".agent") {
+        knowledgeDir = "rules";
+    }
   
     const constitutionPath = fs.existsSync(path.join(process.cwd(), "ENDERUN.md"))
         ? "ENDERUN.md"
@@ -29,7 +35,7 @@ export function checkCommand() {
         { 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: "ESLint Standards", path: path.join(frameworkDir, `${knowledgeDir}/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" },

package/src/cli/commands/init.ts

@@ -11,7 +11,7 @@ import {
     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 { updateGitIgnore, ensureDir, writeJsonFile, copyDir, writeTextFile } from "../utils/fs.js";
 import { initializeMemory } from "../utils/memory.js";
 import { checkCommand } from "./check.js";
 
@@ -76,23 +76,21 @@ function buildDirsToCreate(adapter: AdapterConfig): string[] {
 /**
  * Scaffold the framework for a specific IDE adapter (separate runtime folder per IDE).
  */
-export async function initCommand(adapterInput?: string) {
+export async function initCommand(adapterInput?: string, dryRun = false) {
     const adapter = resolveAdapter(adapterInput);
     const { frameworkDir, shimFile, templateDir } = adapter;
     const targetFrameworkDir = path.join(targetDir, frameworkDir);
 
+    if (dryRun) {
+        console.warn("\n🔍 DRY RUN MODE ACTIVE - No changes will be made to the filesystem.\n");
+    }
+
     console.warn(`🚀 Installing Agent Enderun (Adapter: ${adapter.id} → ${frameworkDir}/)...`);
 
-    if (!fs.existsSync(targetFrameworkDir)) {
-        fs.mkdirSync(targetFrameworkDir, { recursive: true });
-    }
+    ensureDir(targetFrameworkDir, dryRun);
 
     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}`);
-        }
+        ensureDir(path.join(targetDir, dir), dryRun);
     }
 
     const filesToProcess = [
@@ -105,13 +103,13 @@ export async function initCommand(adapterInput?: string) {
       fs.existsSync(path.join(sourceDir, f)),
     );
 
-    ensureDir(path.join(targetDir, "apps/backend"));
+    ensureDir(path.join(targetDir, "apps/backend"), dryRun);
     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(),
-        });
+        }, dryRun);
     }
 
     let targetPkg: Record<string, unknown> = {};
@@ -135,16 +133,43 @@ export async function initCommand(adapterInput?: string) {
         const src = path.join(sourceDir, item);
         let dest = path.join(targetDir, item);
 
-        if (item === "framework-mcp" && fs.existsSync(dest)) {
+        // Safeguard: Do not delete or overwrite if we are in the framework's own development directory
+        const isDevMode = src === dest;
+
+        if (item === "framework-mcp" && fs.existsSync(dest) && !isDevMode) {
             try {
-                fs.rmSync(dest, { recursive: true, force: true });
+                if (dryRun) {
+                    console.warn(`[DRY RUN] Would remove existing directory: ${dest}`);
+                } else {
+                    fs.rmSync(dest, { recursive: true, force: true });
+                }
             } catch {
                 // ignore
             }
         }
 
         if (item === templateDir || item.startsWith(`${templateDir}/`)) {
-            dest = path.join(targetDir, item.replace(templateDir, frameworkDir));
+            let relativePath = item.replace(templateDir, "").replace(/^\//, "");
+            
+            // Adapter-specific agent/skill folder remapping
+            if (relativePath.startsWith("agents")) {
+                if (adapter.id === "antigravity") {
+                    relativePath = relativePath.replace("agents", "skills");
+                } else if (adapter.id === "grok") {
+                    relativePath = relativePath.replace("agents", "plugins");
+                }
+            } else if (relativePath.startsWith("knowledge")) {
+                if (adapter.id === "antigravity") {
+                    relativePath = relativePath.replace("knowledge", "rules");
+                }
+            }
+
+            dest = path.join(targetDir, frameworkDir, relativePath);
+        }
+        
+        // Skip if src and dest are same and it's not a shim or specific file that needs re-mapping
+        if (isDevMode && !isAdapterShimFile(item) && item !== "package.json") {
+            continue;
         }
         if (item === "ENDERUN.md") {
             dest = path.join(targetFrameworkDir, "ENDERUN.md");
@@ -161,6 +186,11 @@ export async function initCommand(adapterInput?: string) {
             const skipFiles =
         item === templateDir ? ["logs", "PROJECT_MEMORY.md", "PROJECT_MEMORY.lock"] : [];
             const nonDestructive = ["docs", templateDir].includes(item);
+
+            if (item === templateDir) {
+                // the destination path (dest) is already mapped correctly above.
+            }
+
             copyDir(
                 src,
                 dest,
@@ -170,6 +200,7 @@ export async function initCommand(adapterInput?: string) {
                 targetScope,
                 sanitizeJson,
                 adapter.id,
+                dryRun,
             );
         } else {
             if (item === "package.json") continue;
@@ -195,25 +226,38 @@ export async function initCommand(adapterInput?: string) {
                     }
                 }
 
-                fs.writeFileSync(dest, content);
+                writeTextFile(dest, content, dryRun);
             } else {
-                fs.copyFileSync(src, dest);
+                if (dryRun) {
+                    console.warn(`[DRY RUN] Would copy binary file: ${dest}`);
+                } 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);
+    if (!dryRun) {
+        mergePackageJson(path.join(targetDir, "package.json"), path.join(sourceDir, "package.json"));
+    } else {
+        console.warn("[DRY RUN] Would merge package.json content.");
+    }
+    
+    updateGitIgnore(path.join(targetDir, ".gitignore"), frameworkDir, dryRun);
 
     const finalMemoryPath = path.join(targetFrameworkDir, "PROJECT_MEMORY.md");
-    initializeMemory(finalMemoryPath, frameworkDir);
+    initializeMemory(finalMemoryPath, frameworkDir, dryRun);
 
-    deepCleanProtocols(targetDir, targetScope);
+    if (!dryRun) {
+        deepCleanProtocols(targetDir, targetScope);
+    } else {
+        console.warn("[DRY RUN] Would clean specific workspace protocols.");
+    }
 
     const sampleTestPath = path.join(targetDir, "tests/initial.test.ts");
     if (!fs.existsSync(sampleTestPath)) {
-        fs.writeFileSync(
+        writeTextFile(
             sampleTestPath,
             `import { describe, it, expect } from "vitest";
 
@@ -223,20 +267,29 @@ describe("Initial Setup", () => {
   });
 });
 `,
+            dryRun,
         );
     }
 
     if (!fs.existsSync(path.join(targetDir, ".git"))) {
         try {
-            execSync("git init", { cwd: targetDir, stdio: "ignore" });
-            console.warn("✅ Git repository initialized.");
+            if (dryRun) {
+                console.warn("[DRY RUN] Would initialize git repository.");
+            } else {
+                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);
+    if (!dryRun) {
+        runAdapterPostInit(adapter, targetDir);
+    } else {
+        console.warn(`[DRY RUN] Would run post-init steps for ${adapter.id}`);
+    }
 
     console.warn(`\n♊ ${adapter.id.toUpperCase()}: Setup complete.`);
     console.warn(`   • Framework runtime: ${frameworkDir}/`);
@@ -251,8 +304,8 @@ describe("Initial Setup", () => {
 
     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).");
+    if (dryRun || process.env.ENDERUN_SKIP_INSTALL === "1") {
+        console.warn(`\n⏭️  Skipping install steps (${dryRun ? "Dry-Run" : "ENDERUN_SKIP_INSTALL=1"}).`);
         return;
     }