agent-enderun 0.8.8 → 0.9.1

package/agent.md

@@ -0,0 +1,25 @@
+# Agent Enderun — Antigravity Adapter
+
+This is the primary entry point when using Agent Enderun within the Antigravity (IDE & CLI) ecosystem.
+
+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:
+
+👉 **[.enderun/ENDERUN.md](.enderun/ENDERUN.md)**
+
+### 🤖 Agent Directive
+You are operating under the Agent Enderun governance framework.
+
+At the **start of every session**, before any work:
+1. **Restore Memory:** Read `.enderun/PROJECT_MEMORY.md` to restore state, active Trace ID, and history.
+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.
+
+### 🛡️ 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.
+
+All paths and references inside the project must comply with the Supreme Constitution located at `.enderun/ENDERUN.md`.

package/bin/cli.js

@@ -1,19 +1,19 @@
 #!/usr/bin/env node
-import { spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-const cliPath = join(__dirname, '../src/cli/index.ts');
+const cliPath = join(__dirname, "../src/cli/index.ts");
 
-// shell: false kullanarak argümanların (tırnakların) bozulmasını önle
-const child = spawn('npx', ['tsx', cliPath, ...process.argv.slice(2)], {
-  stdio: 'inherit',
-  shell: false 
+// use shell: false to prevent argument (quote) corruption
+const child = spawn("npx", ["tsx", cliPath, ...process.argv.slice(2)], {
+    stdio: "inherit",
+    shell: false 
 });
 
-child.on('exit', (code) => {
-  process.exit(code ?? 0);
+child.on("exit", (code) => {
+    process.exit(code ?? 0);
 });

package/bin/init-check.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+
+const targetDir = process.cwd();
+
+const candidates = [".gemini", ".claude", ".agent", ".enderun"];
+let frameworkDir = ".enderun";
+for (const dir of candidates) {
+    if (fs.existsSync(path.join(targetDir, dir))) {
+        frameworkDir = dir;
+        break;
+    }
+}
+
+let backend = "apps/backend";
+let docs = "docs";
+
+try {
+    const configPath = path.join(targetDir, 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.docs) docs = config.paths.docs;
+        }
+    }
+} catch (e) {
+    // ignore
+}
+
+const CRITICAL_STRUCTURE = [
+    `${frameworkDir}/agents`,
+    `${frameworkDir}/knowledge`,
+    `${frameworkDir}/memory-graph/agent-contexts`,
+    `${frameworkDir}/logs`,
+    `${frameworkDir}/queue`,
+    `${frameworkDir}/PROJECT_MEMORY.md`,
+    `${docs}/architecture/standards`,
+    `${backend}/src/database`,
+    `${backend}/src/seeds`,
+    `${backend}/migrations`
+];
+
+function checkIntegrity() {
+    console.warn("🔍 Running Agent Enderun Framework Integrity Check...");
+    let isHealthy = true;
+
+    for (const item of CRITICAL_STRUCTURE) {
+        const fullPath = path.join(targetDir, item);
+        if (!fs.existsSync(fullPath)) {
+            console.error(`❌ Missing critical component: ${item}`);
+            isHealthy = false;
+        } else {
+            console.warn(`✅ Verified: ${item}`);
+        }
+    }
+
+    if (isHealthy) {
+        console.warn("\n✨ Framework integrity verified. System is healthy.");
+        process.exit(0);
+    } else {
+        console.error("\n❌ Framework integrity check FAILED. Some components are missing.");
+        process.exit(1);
+    }
+}
+
+checkIntegrity();

package/bin/update-contract.js

@@ -1,8 +1,5 @@
 #!/usr/bin/env node
 
-/* global console, process */
-/* eslint-disable no-console */
-
 import fs from "fs";
 import path from "path";
 import crypto from "crypto";
@@ -12,55 +9,77 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const projectRoot = path.join(__dirname, "..");
 
-const contractPath = path.join(projectRoot, "apps/backend/contract.version.json");
-const sharedTypesDir = path.join(projectRoot, "apps/backend/src/types");
+const candidates = [".gemini", ".claude", ".agent", ".enderun"];
+let frameworkDir = ".enderun";
+for (const dir of candidates) {
+    if (fs.existsSync(path.join(projectRoot, dir))) {
+        frameworkDir = dir;
+        break;
+    }
+}
+
+let backend = "apps/backend";
+try {
+    const configPath = path.join(projectRoot, frameworkDir, "config.json");
+    if (fs.existsSync(configPath)) {
+        const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        if (config.paths && config.paths.backend) {
+            backend = config.paths.backend;
+        }
+    }
+} catch (e) {
+    // ignore
+}
+
+const contractPath = path.join(projectRoot, backend, "contract.version.json");
+const sharedTypesDir = path.join(projectRoot, backend, "src/types");
 
 function collectTypeFiles(dir) {
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
-  const files = [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const files = [];
 
-  for (const entry of entries) {
-    const fullPath = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...collectTypeFiles(fullPath));
-    } else if (entry.name.endsWith(".ts")) {
-      files.push(fullPath);
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...collectTypeFiles(fullPath));
+        } else if (entry.name.endsWith(".ts")) {
+            files.push(fullPath);
+        }
     }
-  }
 
-  return files;
+    return files;
 }
 
 function calculateHash(dir) {
-  const hash = crypto.createHash("sha256");
-  const files = collectTypeFiles(dir).sort();
+    const hash = crypto.createHash("sha256");
+    const files = collectTypeFiles(dir).sort();
   
-  files.forEach(file => {
-    const content = fs.readFileSync(file);
-    hash.update(path.relative(projectRoot, file));
-    hash.update("\0");
-    hash.update(content);
-    hash.update("\0");
-  });
+    files.forEach(file => {
+        const content = fs.readFileSync(file);
+        hash.update(path.relative(projectRoot, file));
+        hash.update("\0");
+        hash.update(content);
+        hash.update("\0");
+    });
   
-  return hash.digest("hex");
+    return hash.digest("hex");
 }
 
 try {
-  console.log("🔍 Calculating shared-types contract hash...");
-  const newHash = calculateHash(sharedTypesDir);
+    console.log("🔍 Calculating shared-types contract hash...");
+    const newHash = calculateHash(sharedTypesDir);
   
-  const contract = JSON.parse(fs.readFileSync(contractPath, "utf-8"));
+    const contract = JSON.parse(fs.readFileSync(contractPath, "utf-8"));
   
-  if (contract.contract_hash === newHash) {
-    console.log("✅ Contract hash is already up to date.");
-  } else {
-    contract.contract_hash = newHash;
-    contract.last_updated = new Date().toISOString();
-    fs.writeFileSync(contractPath, JSON.stringify(contract, null, 2));
-    console.log(`🚀 Contract updated with new hash: ${newHash.slice(0, 10)}...`);
-  }
+    if (contract.contract_hash === newHash) {
+        console.log("✅ Contract hash is already up to date.");
+    } else {
+        contract.contract_hash = newHash;
+        contract.last_updated = new Date().toISOString();
+        fs.writeFileSync(contractPath, JSON.stringify(contract, null, 2));
+        console.log(`🚀 Contract updated with new hash: ${newHash.slice(0, 10)}...`);
+    }
 } catch (error) {
-  console.error("❌ Failed to update contract hash:", error.message);
-  process.exit(1);
+    console.error("❌ Failed to update contract hash:", error.message);
+    process.exit(1);
 }

package/bin/validate-agent-army.js

@@ -3,16 +3,39 @@
 import fs from "fs";
 import path from "path";
 
-const frameworkDir = fs.existsSync("./.enderun") ? "./.enderun" : "./.gemini";
-const AGENTS_DIR = path.resolve(frameworkDir, "agents");
-const SCHEMA_PATH = path.resolve(frameworkDir, "agents/agent_army_schema.json");
+const FRAMEWORK_CANDIDATES = [".gemini", ".claude", ".agent", ".enderun"];
+
+function detectFrameworkDir() {
+    for (const dir of FRAMEWORK_CANDIDATES) {
+        const agentsPath = path.resolve(dir, "agents");
+        const schemaPath = path.resolve(dir, "agents/agent_army_schema.json");
+        if (fs.existsSync(agentsPath)) {
+            return { frameworkDir: dir, agentsDir: agentsPath, schemaPath };
+        }
+    }
+    return null;
+}
+
+const detected = detectFrameworkDir();
+if (!detected) {
+    console.error("❌ No framework agents/ directory found. Run: agent-enderun init <adapter>");
+    console.error(`   Looked for: ${FRAMEWORK_CANDIDATES.map((d) => `${d}/agents`).join(", ")}`);
+    process.exit(1);
+}
+
+const { frameworkDir, agentsDir, schemaPath } = detected;
 
 console.log(`🛡️  STARTING AUTOMATED AGENT ARMY VALIDATION (${frameworkDir})...`);
 
 try {
-    const schema = JSON.parse(fs.readFileSync(SCHEMA_PATH, "utf8"));
+    if (!fs.existsSync(schemaPath)) {
+        console.error(`❌ Schema missing: ${schemaPath}`);
+        process.exit(1);
+    }
+
+    const schema = JSON.parse(fs.readFileSync(schemaPath, "utf8"));
     const requiredKeys = schema.required;
-    const files = fs.readdirSync(AGENTS_DIR);
+    const files = fs.readdirSync(agentsDir);
     let totalFailed = 0;
 
     console.log("--------------------------------------------------");
@@ -21,10 +44,9 @@ try {
 
     for (const fileName of files) {
         if (!fileName.endsWith(".md")) continue;
-        const filePath = path.join(AGENTS_DIR, fileName);
+        const filePath = path.join(agentsDir, fileName);
         const content = fs.readFileSync(filePath, "utf8");
 
-        // Simple YAML frontmatter parser
         const match = content.match(/^---\n([\s\S]*?)\n---/);
         if (!match) {
             console.log(`| ${fileName.padEnd(9)} | ❌ NO YAML | ----- | ---------------- |`);
@@ -34,11 +56,10 @@ try {
 
         const yamlContent = match[1];
         const agent = {};
-        yamlContent.split("\n").forEach(line => {
+        yamlContent.split("\n").forEach((line) => {
             const [key, ...valParts] = line.split(":");
             if (key && valParts.length > 0) {
                 let val = valParts.join(":").trim();
-                // Clean quotes and handle numbers
                 val = val.replace(/^['"]|['"]$/g, "");
                 if (!isNaN(val) && val !== "") {
                     agent[key.trim()] = Number(val);
@@ -48,13 +69,17 @@ try {
             }
         });
 
-        const missing = requiredKeys.filter(k => agent[k] === undefined);
+        const missing = requiredKeys.filter((k) => agent[k] === undefined);
 
         if (missing.length > 0) {
-            console.log(`| ${fileName.replace(".md", "").padEnd(9)} | ❌ FAILED  | ----- | ${`Missing: ${missing.join(",")}`.slice(0, 16)} |`);
+            console.log(
+                `| ${fileName.replace(".md", "").padEnd(9)} | ❌ FAILED  | ----- | ${`Missing: ${missing.join(",")}`.slice(0, 16)} |`,
+            );
             totalFailed++;
         } else {
-            console.log(`| ${agent.name.padEnd(9)} | ✅ PASSED  | ${String(agent.capability).padEnd(5)} | ${agent.role.substring(0,14).padEnd(14)} |`);
+            console.log(
+                `| ${agent.name.padEnd(9)} | ✅ PASSED  | ${String(agent.capability).padEnd(5)} | ${agent.role.substring(0, 14).padEnd(14)} |`,
+            );
         }
     }
 
@@ -63,7 +88,7 @@ try {
         console.error(`❌ Validation failed! Detected ${totalFailed} invalid agent configurations.`);
         process.exit(1);
     } else {
-        console.log("🎉 SUCCESS: All 8 core agents comply 100% with the Master Agent Army Schema!");
+        console.log("🎉 SUCCESS: All core agents comply with the Master Agent Army Schema!");
     }
 } catch (e) {
     console.error("❌ Critical error during schema validation:", e);

package/claude.md

@@ -1,19 +1,25 @@
-# Agent Enderun — Claude Code CLI Adapter
+# Agent Enderun — Claude Code Adapter
 
-This file is the entry point when using Agent Enderun with Claude Code CLI.
+This is the primary entry point when using Agent Enderun within the Claude Code (CLI & Desktop) ecosystem.
 
-The framework installs into the `.claude/` folder for Claude users.
+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:
 
-👉 **[.claude/ENDERUN.md](.claude/ENDERUN.md)**
+👉 **[.enderun/ENDERUN.md](.enderun/ENDERUN.md)**
 
-### 🤖 Agent Directive (Claude Code CLI users)
+### 🤖 Agent Directive
 You are operating under the Agent Enderun governance framework.
 
 At the **start of every session**, before any work:
-1. Read `.claude/PROJECT_MEMORY.md` to restore state, active Trace ID, and history.
-2. Read the relevant agent definition under `.claude/agents/{agent}.md` (especially `@manager`).
+1. **Restore Memory:** Read `.enderun/PROJECT_MEMORY.md` to restore state, active Trace ID, and history.
+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.
 
-All paths and references inside `.claude/` use the Claude adapter structure. No migration to other CLIs is required.
+### 🛡️ 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.
+
+All paths and references inside the project must comply with the Supreme Constitution located at `.enderun/ENDERUN.md`.

package/docs/README.md

@@ -1,26 +1,34 @@
-# Agent Enderun — Corporate Project Portal
+# Agent Enderun — Governance and Architecture Portal
 
-Welcome to the central documentation portal for your corporate project. This portal is designed to provide your **Agent Army** and human developers with a structured, clean, and unambiguous framework for software design, architecture, and governance.
+This portal is the **Central Knowledge Source** for enterprise projects developed under the Agent Enderun framework. The project's architectural decisions, standards, and governance protocols are sealed here.
+
+Unlike ordinary projects, Agent Enderun projects are built on a structure where AI agents operate autonomously but are bound by a rigid, human-authored constitution. This documentation is the **Immutable Guide** for both AI agents (Army) and human developers.
 
 ---
 
-## 📂 Documentation Directory
+### 📋 Documentation Guide
 
-### [1. Architecture & Governance](architecture/)
-- **[Architecture Decisions (ADRs)](architecture/decisions/)**: Log of key architectural choices and design patterns.
-- **[Approval & High-Risk Workflows](architecture/approval-flows.md)**: Detailed contracts and state machines for `managerApproval` tokens.
-- **[Notification Strategy](architecture/notification-strategy.md)**: Dynamic notification patterns and toaster integrations.
+#### [1. Architecture & Governance](architecture/)
+*   **[Approval & High-Risk Workflows](architecture/approval-flows.md)**: Explains how tokens are generated, audited, and how high-risk actions (e.g., database deletion, privilege escalation) are sealed.
 
-### [2. Frontend Standards](frontend/)
-- **[Component Patterns](frontend/component-patterns.md)**: Guidelines for custom, Zero-UI-Library React components styled with Panda CSS.
-- **[Form Validations](frontend/forms.md)**: Type-safe form states using Zod and React hooks.
-- **[Toaster Notifications](frontend/notifications.md)**: Integration guides for Sonner toast configurations.
+#### [2. Frontend Standards](frontend/)
+*   **[Component Patterns](frontend/component-patterns.md)**: Zero-UI-Library policy, guide on how all components are hand-crafted and type-safe using Panda CSS.
 
-### [3. Backend Standards](backend/)
-- **[Error Handling](backend/error-handling.md)**: Standardized `DomainError` class hierarchies and Fastify error maps.
-- **[Audit Logging](backend/audit-logging.md)**: Database auditing schemes and transaction log contracts.
+#### [3. Backend Standards](backend/)
+*   **[Error Handling](backend/error-handling.md)**: Professional error management hierarchy that does not leak to the front-end and is traceable in logs.
 
 ---
 
-> [!TIP]
-> **Enforcement Rule:** All agents in the army are mandated to read these guidelines before writing any code, ensuring 100% architectural alignment and clean, modular codebase organization.
+## 🛰️ Phase-Based Development Life Cycle
+All projects must pass the following 5 phases sequentially and completely:
+
+1.  **PHASE_0 (Discovery):** Tech-stack (`tech-stack.md`) sealed, risk analysis performed.
+2.  **PHASE_1 (Architecture & Contract):** First, types and API contracts are written. Contracts must be approved before a single line of application code is written.
+3.  **PHASE_2 (Core Development):** Backend and Frontend are built in parallel. Branded Types usage is mandatory.
+4.  **PHASE_3 (Integration & Test):** @quality agent takes over. 80% Test Coverage threshold must be met before proceeding to the next phase.
+5.  **PHASE_4 (Optimization & Deployment):** Security scans and performance tests are completed.
+
+> **Agent Directive:** The documents under this folder define the operational boundaries of the agents. An agent cannot deviate from a rule defined here. If a rule needs to be updated, this can only be done with @manager approval and ADR registration.
+
+**Version:** v0.9.1  
+**Status:** Active Governance

package/docs/architecture/README.md

@@ -0,0 +1,9 @@
+# Architecture Patterns — Agent Enderun
+
+This directory contains the non-negotiable technical standards and architectural patterns for the Agent Enderun framework.
+
+## Directory Structure
+- `standards/`: Technical SOPs, design systems, and compliance mandates.
+
+## Core Mandate
+All agents MUST read and adhere to these documents before initiating any implementation task.

package/docs/architecture/standards/data-fetching-patterns.md

@@ -0,0 +1,13 @@
+# Architecture Patterns & Data Fetching
+
+## 1. UI Layout & Component Structure
+- **Shared UI:** All atomic components (Button, Input, etc.) must be created in `apps/web/src/components/ui/` using **Panda CSS**.
+- **Layouts:** Use wrapper layouts (`Shell`, `Workspace`) in `apps/web/src/components/layout/`. Every page must utilize these layouts to maintain consistency.
+- **Procedural Continuity:** Never re-create an existing component. Search the `components/ui/` directory first.
+
+## 2. Data Fetching & API (CRUD) Patterns
+- **Repository Pattern:** Backend logic must be separated into service/repository layers. No direct DB calls in controllers.
+- **Contract-First:** All API endpoints must use types imported from `apps/backend/src/types/`.
+- **API Layer:** Frontend must use typed fetcher functions located in `apps/web/src/api/`.
+- **Validation:** Use `zod` for request validation on the backend and response validation on the frontend.
+- **Audit Logging:** Every mutation (POST/PUT/PATCH/DELETE) MUST trigger an audit log service call with the current Trace ID.

package/docs/architecture/standards/design-system.md

@@ -0,0 +1,31 @@
+# Design System — Agent Enderun (Enterprise)
+
+## 1. Design Philosophy
+The Agent Enderun Design System focuses on **"Enterprise Clarity"**. Our interfaces are professional, minimalist tools designed to maximize data comprehension and operational speed. 
+
+- **Clarity:** Every pixel must serve a purpose. If it doesn't aid understanding or action, remove it.
+- **Consistency:** Uniform visual language across all applications.
+- **Responsiveness:** Fluid adaptation to any screen size, from mobile to ultra-wide monitors.
+
+## 2. Technical Requirements
+- **Styling:** Panda CSS is MANDATORY. Tailwind, CSS-in-JS, and raw CSS modules are FORBIDDEN.
+- **Zero UI Library:** No external components (MUI, AntD, Shadcn). All UI components must be built from scratch in `apps/web/src/components/ui/`.
+- **Tokenization:** All values (colors, spacing, typography) MUST use `panda.config.ts` tokens. NO hardcoded pixels.
+- **Responsiveness:** Mobile-First design is MANDATORY.
+
+## 3. Responsive Mandate (Mobile-First)
+- **Design Strategy:** Design for 320px width first.
+- **Breakpoints:**
+  - `sm`: 640px
+  - `md`: 768px
+  - `lg`: 1024px
+  - `xl`: 1280px
+  - `2xl`: 1536px
+- **Layouts:** Use Flexbox and Grid. Fixed widths are FORBIDDEN. Use `clamp()` for fluid typography and spacing where applicable.
+- **Reflow:** Content MUST gracefully wrap, stack, or collapse based on screen width without horizontal scrollbars.
+
+## 4. UI/UX Interaction Standards
+- **Interactions:** Hover, Active, and Disabled states are MANDATORY for all interactive elements.
+- **Feedback:** Async operations MUST show Loading states and Toast notifications on completion/error.
+- **Blocking Dialogues:** Native `alert()` and `confirm()` functions are **FORBIDDEN**. Use project-integrated `Modal` components for blocking user interactions and `Toaster` for non-blocking feedback.
+- **Focus:** All interactive elements must have a visible `focus` state for accessibility.

package/docs/architecture/standards/logging.md

@@ -0,0 +1,7 @@
+# Logging & Audit Standard
+
+- **No Console.log:** Production code MUST NOT use `console.log`, `console.warn`, or `console.error`. These are FORBIDDEN in the codebase.
+- **Structured Logging:** All logging MUST go through the centralized `Logger` service (`apps/backend/src/services/logger.ts`). Logs must be produced in JSON format.
+- **Traceability:** Every log entry MUST include the active `traceId` context to ensure cross-agent and cross-service traceability.
+- **Audit Logging:** Every state-mutating operation (POST, PUT, PATCH, DELETE) MUST trigger an `AuditService.log()` call, linking the action to the responsible agent, Trace ID, and entity ID.
+- **Log Persistence:** Logs must be persisted in an structured manner suitable for downstream ingestion by log management systems.

package/docs/architecture/standards/tech-stack.md

@@ -0,0 +1,9 @@
+# Tech Stack — Agent Enderun (Enterprise)
+
+- **Execution Profile:** Full (Enterprise)
+- **Frontend:** React (Vite), Panda CSS (Zero UI Library)
+- **Backend:** Fastify API, Kysely (Query Builder)
+- **Database:** PostgreSQL
+- **Testing:** Vitest (Integration + Unit)
+- **Auth:** Contract-first (Type definitions)
+- **Versioning:** API-path versioning (/api/v1/...)