agent-enderun 0.6.1 → 0.6.6

package/antigravity.md

@@ -0,0 +1,15 @@
+# Agent Enderun — Antigravity Adapter
+
+This file is the entry point for Antigravity CLI. The project's "Supreme Law" and all instructions are located in the following file:
+
+👉 **[.antigravitycli/ENDERUN.md](.antigravitycli/ENDERUN.md)**
+
+### 🤖 AGENT DIRECTIVE
+You are ALWAYS operating as `@manager` (Team-Lead) by default — on every message, every turn. The user does NOT need to type `@manager`. Typing a specific agent (e.g. `@backend`) explicitly will override this and activate that specialist role directly. You are responsible for analysis and delegation.
+
+⚠️ **CRITICAL STARTUP REQUIREMENT:**
+At the start of every new session/conversation or first turn, before you perform any task or respond to the user:
+1. You **MUST** read `.antigravitycli/PROJECT_MEMORY.md` immediately (using the `read_project_memory` tool or the most specific file viewing tool) to restore the project's state, active phase, Trace ID, and recent history.
+2. You **MUST** read `.antigravitycli/agents/manager.md` (or the specialist's md file in `.antigravitycli/agents/` if explicitly overridden) to load your role-specific rules, workflows, and checklists.
+
+Please read the Supreme Law thoroughly before taking any action.

package/bin/cli.js

@@ -22,7 +22,7 @@ function getPackageVersion() {
 }
 
 function getFrameworkDir() {
-  const adapters = [".gemini", ".claude", ".cursor", ".enderun", ".codex"];
+  const adapters = [".antigravitycli", ".claude", ".cursor", ".enderun", ".codex", ".gemini"];
   for (const adp of adapters) {
     const fullPath = path.join(targetDir, adp);
     if (fs.existsSync(fullPath) && fs.lstatSync(fullPath).isDirectory()) {
@@ -225,6 +225,60 @@ function updateGitIgnore(targetPath, frameworkDir = ".enderun") {
   }
 }
 
+/**
+ * Finds the Claude config file path (if it exists).
+ */
+function findClaudeConfigPath() {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) return null;
+
+  const possiblePaths = [
+    path.join(home, ".config", "claude", "config.json"),
+    path.join(home, ".claude", "config.json"),
+    path.join(home, "Library", "Application Support", "Claude", "config.json"), // macOS Claude Desktop
+    path.join(home, "Library", "Application Support", "Claude Code", "config.json"), // macOS Claude Code
+    path.join(home, ".config", "Claude", "config.json"), // some Linux setups
+  ];
+
+  for (const p of possiblePaths) {
+    if (fs.existsSync(p)) {
+      return p;
+    }
+  }
+  return null;
+}
+
+/**
+ * Adds or updates an MCP server entry in Claude's config file.
+ */
+function addMcpServerToClaude(configPath, serverName, serverConfig) {
+  try {
+    let config = { mcpServers: {} };
+
+    if (fs.existsSync(configPath)) {
+      const content = fs.readFileSync(configPath, "utf8");
+      config = JSON.parse(content);
+    }
+
+    if (!config.mcpServers) {
+      config.mcpServers = {};
+    }
+
+    config.mcpServers[serverName] = serverConfig;
+
+    // Ensure parent directory exists
+    const dir = path.dirname(configPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
 /**
  * Create initial PROJECT_MEMORY.md if missing.
  */
@@ -318,13 +372,21 @@ function getPackageManager() {
  */
 async function initCommand(selectedAdapter) {
   const ADAPTERS = {
-    gemini: ["gemini.md", "gemini-extension.json"],
+    antigravity: ["antigravity.md"],
     claude: ["claude.md"],
     cursor: ["cursor.md"],
     codex: ["codex.md"],
+    gemini: ["gemini.md"],
   };
 
-  const targetBase = selectedAdapter && selectedAdapter !== "codex" ? `.${selectedAdapter}` : ".enderun";
+  let targetBase;
+  if (selectedAdapter === "antigravity") {
+    targetBase = ".antigravitycli";
+  } else if (selectedAdapter && selectedAdapter !== "codex") {
+    targetBase = `.${selectedAdapter}`;
+  } else {
+    targetBase = ".enderun";
+  }
 
   const targetFrameworkDir = path.join(targetDir, targetBase);
 
@@ -374,7 +436,7 @@ async function initCommand(selectedAdapter) {
   let filesToProcess = [...CORE_FILES];
   if (selectedAdapter) {
     if (!ADAPTERS[selectedAdapter]) {
-      console.error(`❌ Invalid adapter: ${selectedAdapter}. Available: gemini, claude, cursor, codex`);
+      console.error(`❌ Invalid adapter: ${selectedAdapter}. Available: antigravity, claude, cursor, codex, gemini`);
       process.exit(1);
     }
     filesToProcess.push(...ADAPTERS[selectedAdapter]);
@@ -507,30 +569,33 @@ async function initCommand(selectedAdapter) {
   console.log("\n🛠️  Running smart configuration for adapters...");
 
 
-  if (selectedAdapter === "gemini") {
-    // Patch gemini-extension.json to wire up the MCP server automatically
-    const geminiExtPath = path.join(targetDir, "gemini-extension.json");
-    try {
-      const ext = JSON.parse(fs.readFileSync(geminiExtPath, "utf8"));
-      ext.mcpServers = {
-        "agent-enderun": {
-          command: "node",
-          args: ["framework-mcp/dist/index.js"]
-        }
-      };
-      fs.writeFileSync(geminiExtPath, JSON.stringify(ext, null, 2) + "\n");
-      console.log("💎 Gemini: MCP server wired up in gemini-extension.json automatically.");
-    } catch (e) {
-      console.warn("⚠️  Gemini: Could not patch gemini-extension.json for MCP. Wire it up manually.");
-    }
-    console.log(`💎 Gemini: Adapter gemini.md and ${targetBase}/ folder are ready.`);
+  if (selectedAdapter === "antigravity") {
+    console.log(`🚀 Antigravity: Adapter antigravity.md and ${targetBase}/ folder are ready.`);
   }
 
   if (selectedAdapter === "claude") {
     const mcpPath = path.join(targetDir, "framework-mcp/src/index.ts");
-    console.log("\n📝 Claude Code Setup:");
-    console.log("To enable Agent Enderun tools in Claude Code, run this command:");
-    console.log(`\x1b[36mclaude config add framework-mcp npx tsx ${mcpPath}\x1b[0m`);
+    const mcpConfig = {
+      command: "npx",
+      args: ["tsx", mcpPath]
+    };
+
+    const claudeConfigPath = findClaudeConfigPath() || path.join(
+      process.env.HOME || process.env.USERPROFILE || "",
+      "Library", "Application Support", "Claude", "config.json"
+    ); // default macOS path if nothing found
+
+    const success = addMcpServerToClaude(claudeConfigPath, "agent-enderun", mcpConfig);
+
+    if (success) {
+      console.log("✅ Claude: MCP server 'agent-enderun' automatically configured.");
+      console.log(`   Config file: ${claudeConfigPath}`);
+      console.log("   (File was created if it did not exist)");
+    } else {
+      console.log("\n📝 Claude Code Setup (Automatic failed):");
+      console.log("Please run this command manually:");
+      console.log(`\x1b[36mclaude config add agent-enderun npx tsx ${mcpPath}\x1b[0m`);
+    }
   }
 
   if (selectedAdapter === "cursor") {
@@ -773,8 +838,8 @@ function copyDir(src, dest, skipSet = new Set(), nonDestructive = false, framewo
 
         const frameworkBase = frameworkDir.startsWith(".") ? frameworkDir.slice(1) : frameworkDir;
         let currentAdapter = frameworkBase;
-        if (entry.name.endsWith(".md") && [ "gemini", "claude", "cursor", "codex" ].some(a => entry.name.startsWith(a))) {
-          currentAdapter = [ "gemini", "claude", "cursor", "codex" ].find(a => entry.name.startsWith(a));
+        if (entry.name.endsWith(".md") && [ "antigravity", "claude", "cursor", "codex", "gemini" ].some(a => entry.name.startsWith(a))) {
+          currentAdapter = [ "antigravity", "claude", "cursor", "codex", "gemini" ].find(a => entry.name.startsWith(a));
         }
 
         content = content.replace(/\{\{FRAMEWORK_DIR\}\}/g, frameworkDir);
@@ -2069,7 +2134,7 @@ async function main() {
 🤖 Agent Enderun CLI (v${FRAMEWORK_VERSION})
 
 Available Commands:
-  init [adapter]      Initialize the framework (gemini, claude, cursor, codex)
+  init [adapter]      Initialize the framework (antigravity, claude, cursor, codex, gemini)
   create-app <idea>   Generate a full-stack starter from natural language
   check               Full health check
   check:security      Run security audit scan

package/bin/hermes-sandbox.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+/**
+ * Agent Enderun — Hermes Protocol Stateful Simulation Sandbox
+ * 
+ * Demonstrates:
+ * - Scenario 1: Autonomous task delegation.
+ * - Scenario 2: High-risk admin action block & managerApproval injection.
+ */
+
+import fs from "fs";
+import path from "path";
+
+const MESSAGES_DIR = path.resolve("./.enderun/messages");
+const TRACE_ID = "01H7K9P2Q3R4S5T6U7V8W9X0Z2";
+
+console.log("🎬 STARTING HERMES PROTOCOL STATEFUL SANDBOX...");
+console.log(`Trace ID: ${TRACE_ID}`);
+console.log("--------------------------------------------------");
+
+// Ensure messages directory exists
+if (!fs.existsSync(MESSAGES_DIR)) {
+    fs.mkdirSync(MESSAGES_DIR, { recursive: true });
+}
+
+// Clean up previous test messages
+const cleanInbox = (agent) => {
+    const p = path.join(MESSAGES_DIR, `${agent}.json`);
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+};
+cleanInbox("backend");
+cleanInbox("manager");
+
+function sendMessage(from, to, content, category = "INFO") {
+    const messagePath = path.join(MESSAGES_DIR, `${to}.json`);
+    const messages = fs.existsSync(messagePath) ? JSON.parse(fs.readFileSync(messagePath, "utf-8")) : [];
+    
+    const msg = {
+        timestamp: new Date().toISOString(),
+        from,
+        to,
+        traceId: TRACE_ID,
+        category,
+        priority: "HIGH",
+        content,
+        status: "PENDING"
+    };
+    
+    messages.push(msg);
+    fs.writeFileSync(messagePath, JSON.stringify(messages, null, 2));
+    console.log(`📡 [Hermes Msg] ${from} ➡️ ${to} [${category}]: "${content}"`);
+}
+
+function readInbox(agent) {
+    const messagePath = path.join(MESSAGES_DIR, `${agent}.json`);
+    if (!fs.existsSync(messagePath)) return [];
+    
+    const messages = JSON.parse(fs.readFileSync(messagePath, "utf-8"));
+    const pending = messages.filter(m => m.status === "PENDING" || m.status === "READ");
+    
+    // Mark as read
+    const updated = messages.map(m => m.status === "PENDING" ? { ...m, status: "READ" } : m);
+    fs.writeFileSync(messagePath, JSON.stringify(updated, null, 2));
+    
+    return pending;
+}
+
+function updateStatus(agent, traceId, status) {
+    const messagePath = path.join(MESSAGES_DIR, `${agent}.json`);
+    if (!fs.existsSync(messagePath)) return;
+    
+    const messages = JSON.parse(fs.readFileSync(messagePath, "utf-8"));
+    const updated = messages.map(m => m.traceId === traceId ? { ...m, status } : m);
+    fs.writeFileSync(messagePath, JSON.stringify(updated, null, 2));
+    console.log(`🔒 [Hermes LifeCycle] Message on @${agent} marked as: ${status}`);
+}
+
+// --- STEP 1: @manager Delegates Task (Scenario 1) ---
+console.log("\n[Step 1: Task Scaffolding & Briefing Delegation]");
+sendMessage("manager", "backend", "Upgrade User 42 role to SuperAdmin inside target database.", "DELEGATION");
+
+// --- STEP 2: @backend Reads & Detects High-Risk Action without approval (Scenario 2) ---
+console.log("\n[Step 2: @backend Inbox Check & High-Risk Guard Trigger]");
+const backendInbox1 = readInbox("backend");
+const taskMsg = backendInbox1.find(m => m.category === "DELEGATION");
+
+if (taskMsg) {
+    console.log(`⚙️  @backend is processing delegation trace: ${taskMsg.traceId}`);
+    console.log("⚠️  @backend security check: 'Upgrade User 42 role' detected as High-Risk Administrative Action!");
+    console.log("❌ @backend security block: Action rejected due to missing 'managerApproval' signature payload!");
+    
+    sendMessage("backend", "manager", "ALERT: Cannot upgrade role for User 42. High-risk administrative action requires dynamic 'managerApproval' token.", "ALERT");
+    updateStatus("backend", TRACE_ID, "REJECTED");
+}
+
+// --- STEP 3: @manager Processes Block, Generates Approval Token, Re-sends msg ---
+console.log("\n[Step 3: @manager Token Generation & Re-Delegation]");
+const managerInbox = readInbox("manager");
+const alertMsg = managerInbox.find(m => m.category === "ALERT");
+
+if (alertMsg) {
+    console.log(`💡 @manager received alert: "${alertMsg.content}"`);
+    console.log("🔐 @manager Dynamic Key Signing active...");
+    
+    const approvalToken = {
+        approved: true,
+        traceId: TRACE_ID,
+        approvedBy: "@manager",
+        approvedAt: new Date().toISOString(),
+        reason: "Authorized Role Upgrade for Enterprise Compliance",
+        riskLevel: "Critical",
+        rollbackPlan: "Demote role back to standard User via database rollback script."
+    };
+    
+    console.log("✅ managerApproval Token generated successfully:", JSON.stringify(approvalToken, null, 2));
+    
+    sendMessage("manager", "backend", `APPROVED: Here is the signed token: ${JSON.stringify(approvalToken)}`, "DELEGATION");
+}
+
+// --- STEP 4: @backend Receives Approval, Executes Simulated DDL/DML, Completes lifecycle ---
+console.log("\n[Step 4: @backend final validation and execution]");
+const backendInbox2 = readInbox("backend");
+const approvedMsg = backendInbox2.find(m => m.category === "DELEGATION" && m.content.startsWith("APPROVED:"));
+
+if (approvedMsg) {
+    console.log("📥 @backend received approval token.");
+    console.log("🛡️  @backend validation: managerApproval signature MATCHED.");
+    console.log("🚀 @backend execution: Running mock SQL transaction... 'UPDATE users SET role = 'SuperAdmin' WHERE id = 42;'");
+    console.log("📝 @backend logging: Audit log record generated with Trace ID.");
+    
+    sendMessage("backend", "manager", "SUCCESS: User 42 successfully upgraded to SuperAdmin. Trace record finalized.", "INFO");
+    updateStatus("backend", TRACE_ID, "COMPLETED");
+}
+
+console.log("\n--------------------------------------------------");
+console.log("🎉 HERMES STATEFUL SIMULATION COMPLETED SUCCESSFULLY!");

package/docs/README.md

@@ -1,7 +1,12 @@
-# Project Documentation
+# Project Documentation / Proje Dokümantasyonu
 
-This folder is managed by **Agent Enderun agents** and contains documentation
-generated for **your project** — not the framework itself.
+English | [Türkçe](#türkçe)
+
+---
+
+# English
+
+This folder is managed by **Agent Enderun agents** and contains documentation generated for **your project** — not the framework itself.
 
 ## What Goes Here
 
@@ -21,3 +26,28 @@ generated for **your project** — not the framework itself.
 | `/.enderun/docs/` | **Framework** configuration — tech-stack, security policy, privacy policy |
 
 > Agents will populate this folder automatically during **PHASE_2 (Core Development)**.
+
+---
+
+# Türkçe
+
+Bu klasör **Agent Enderun ajanları** tarafından yönetilir ve framework'ün kendisi için değil, **sizin projeniz** için oluşturulan dokümanları içerir.
+
+## Burada Neler Var?
+
+| Dosya | Sahip Ajan | Açıklama |
+| :--- | :--- | :--- |
+| `architecture.md` | @backend | Sistem mimarisi ve veri akış diyagramları |
+| `api-reference.md` | @backend | Genel API uç noktaları ve kullanım örnekleri |
+| `components.md` | @frontend | UI bileşen kataloğu ve kullanım kılavuzları |
+| `deployment.md` | @manager | Dağıtım adımları ve ortam kurulumu |
+| `decisions.md` | @manager | Mimari Karar Kayıtları (ADRs) |
+
+## `.enderun/docs/` Klasöründen Farkı
+
+| Yol | Amaç |
+| :--- | :--- |
+| `/docs/` | **Sizin projenizin** dokümantasyonu — özellikler geliştirildikçe ajanlar tarafından yazılır |
+| `/.enderun/docs/` | **Framework** konfigürasyonu — tech-stack, güvenlik politikası, gizlilik politikası |
+
+> Ajanlar bu klasörü **PHASE_2 (Core Development)** sırasında otomatik olarak dolduracaktır.

package/docs/action-plan-2026.md

@@ -0,0 +1,119 @@
+# Agent Enderun — Strategic Action Plan 2026 (v0.6.6+) / Stratejik Eylem Planı
+
+**Owner / Sorumlu:** @manager  
+**Status / Durum:** APPROVED & ACTIVE  
+**Strategic Focus:** Moving from "Governance on Paper" to "Governance in Practice"
+
+[English](#english) | [Türkçe](#türkçe)
+
+---
+
+# English
+
+This strategic document defines the concrete, week-by-week implementation plan to address the critical gaps identified in the v0.6.6 Gap Analysis. It focuses on the three highest-priority phases: building the reference application, executing the Hermes protocol live tests, and professionalizing the frontend/backend engineering standards.
+
+## Phase 1: Production-Grade Reference Application (`apps/`)
+**Timeline:** Weeks 1–3  
+**Goal:** Prove the constitutional governance framework and kurumsal (enterprise) CRUD constraints in a functional full-stack monorepo application.
+
+### 📂 Directory Architecture
+```text
+apps/
+├── backend/                        # Fastify API Server
+│   ├── src/
+│   │   ├── index.ts                # App entry point
+│   │   ├── types/                  # Generated Type Contracts (Branded)
+│   │   ├── db/                     # Kysely Migrations & Schema
+│   │   ├── routes/                 # Normal CRUD & High-Risk Admin Routes
+│   │   └── plugins/                # Auth & managerApproval Verification
+│   └── contract.version.json       # Generated contract hash & version
+│
+└── web/                            # React + Vite Client (Zero UI Library)
+    ├── src/
+    │   ├── main.tsx
+    │   ├── styled-system/          # Panda CSS zero-runtime styles
+    │   ├── types/                  # Local copies of API Type Contracts
+    │   ├── components/ui/          # Resuable Panda CSS components (no external libs)
+    │   ├── hooks/                  #useListPage, useDetailPage, useFormPage
+    │   └── pages/                  # Layouts and logic
+```
+
+### 🛠️ Concrete Feature Scope
+To keep the scope narrow but technically exhaustive, the reference application will implement a **User & Permissions Management Dashboard**:
+
+1. **Normal CRUD (Standard Business Logic):**
+   - User profile update, view active tasks, and change preferences.
+   - Requires regular authentication token and standard agent checklists.
+
+2. **High-Risk Administrative Action (Enforced Governance):**
+   - **Action:** Upgrading a user's system role to `SuperAdmin` or resetting the system configurations.
+   - **Enforcement:** The backend API **must** require:
+     - The `isHighRiskAdminAction: true` flag in the payload.
+     - A valid `managerApproval` object signed dynamically by `@manager` during the briefing.
+   - **UI Warning:** The frontend must render a prominent security modal, coordinate the briefing request via Hermes, and append the approval payload before dispatching the request.
+
+---
+
+## Phase 2: Hermes Messaging Protocol Live Test Program
+**Timeline:** Weeks 4–6  
+**Goal:** Battle-test multi-agent autonomous coordination across 4 mandatory scenarios in the local `messages/` sandbox.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Developer
+    participant Manager as @manager
+    participant Backend as @backend
+    participant Frontend as @frontend
+
+    Developer->>Manager: "Upgrade User 42 to Admin" (High-Risk)
+    activate Manager
+    Manager->>Backend: Hermes msg: Assess database schema & role payload
+    activate Backend
+    Backend-->>Manager: Hermes msg: Type contract generated & verified
+    deactivate Backend
+    Manager->>Frontend: Hermes msg: Dispatch UI component & slot specs
+    activate Frontend
+    Frontend-->>Manager: Hermes msg: Responsive layout & accessibility check complete
+    deactivate Frontend
+    Manager-->>Developer: Final Briefing + managerApproval signed token
+    deactivate Manager
+```
+
+### 🧪 The 4 Mandatory Scenarios
+1. **Scenario 1: Autonomously Delegating Features**
+   - `@manager` receives a trace, generates the architectural plan, and dispatches precise, localized briefings to `@backend` and `@frontend` with zero manual intervention.
+2. **Scenario 2: Coordinating High-Risk Operations**
+   - `@backend` refuses to write a delete endpoint until `@manager` explicitly logs the `managerApproval` briefing token in `PROJECT_MEMORY.md`.
+3. **Scenario 3: Resolving API Contract Drift**
+   - `@backend` modifies a property in the API schema; `@analyst` detects the drift, notifies `@frontend` via Hermes, and `@frontend` surgically updates the local types to match.
+4. **Scenario 4: Live Knowledge Sharing**
+   - `@explorer` discovers a performance bottleneck or accessibility violation in `apps/web/` and directly updates the agent knowledge base, which `@frontend` immediately adopts in the next turn.
+
+---
+
+## Phase 3: `@frontend` & `@backend` Professionalization & Testing
+**Timeline:** Weeks 7–9  
+**Goal:** Elevate engineering maturity levels from 6.5 to $\ge 9.0$ through mandatory quality gates.
+
+### ♿ @frontend Standards Enforcement
+- **Accessibility (WCAG 2.2 AA) Audit Gate:** All components must pass the visual focus rings, logical tab order, 44x44px touch targets, and semantic ARIA landmarks checks.
+- **Performance Budgets Gate:** Verify that Largest Contentful Paint (LCP) is `< 2.5s`, Cumulative Layout Shift (CLS) is `< 0.1`, and initial gzipped bundle size remains `< 250KB`.
+
+### 🧪 Test Coverage & Quality Gates
+- **Shared Components Coverage:** Minimum **70%** code coverage using Vitest + React Testing Library.
+- **Custom Business Hooks Coverage:** Minimum **85%** code coverage.
+- **Contract Integration Tests:** Automated Vitest checks to verify that `apps/backend/contract.version.json` matches the hashes of frontend type copies on every PR.
+
+---
+
+# Türkçe
+
+Bu stratejik belge, v0.6.6 Gap Analizinde tespit edilen kritik eksiklikleri kapatmak üzere hazırlanmış haftalık somut eylem planıdır.
+
+**Özet:**
+- Faz 1: Referans uygulama + Kurumsal CRUD + Hermes kanıtı
+- Faz 2: 4 zorunlu Hermes Live Test senaryosu
+- Faz 3: @frontend ve @backend profesyonelleşme + kalite kapıları
+
+Detaylı plan ve teknik kapsam İngilizce bölümde yer almaktadır.