atabey 0.0.14 → 0.0.16

package/PRIVACY.md

@@ -93,14 +93,14 @@ DataRetention.eraseAllData("KVKK-RIGHT-TO-ERASURE");
 
 ### 4. Data Portability (KVKK Art. 11 / GDPR Art. 20)
 
-All stored data is exportable:
+All stored operational data and metrics are inspectable:
 
 ```bash
-# Export audit logs
-atabey gateway stats
+# View agent statuses, token usage, and cost distributions
+atabey status
 
-# Export all data
-atabey kvkk:export
+# Run full health and compliance checks
+atabey check
 ```
 
 ### 5. Data Processing Records (KVKK Art. 4 / GDPR Art. 30)
@@ -129,16 +129,10 @@ Every data processing operation is logged in the audit trail:
 ## 📝 CLI Commands
 
 ```bash
-# Check current retention status
-atabey kvkk:status
-
-# Export data inventory
-atabey kvkk:export
-
-# Erase all data (with confirmation)
-atabey kvkk:erase-all
+# View agent status, token usage, and cost distribution
+atabey status
 
-# Run compliance audit
+# Run compliance, health, and security checks
 atabey check
 ```
 

package/README.md

@@ -1,19 +1,19 @@
-# [GOV] Agent Atabey — MCP-Powered AI Governance & Autonomous Orchestration
+# [GOV] Agent Atabey — MCP-Powered AI Governance & Multi-Agent Workflow Layer for AI Coding Assistants
 
-[![Version](https://img.shields.io/badge/Version-v0.0.15-blue.svg)](https://github.com/ysf-bkr/atabey)
+[![Version](https://img.shields.io/badge/Version-v0.0.16-blue.svg)](https://github.com/ysf-bkr/atabey)
 [![npm](https://img.shields.io/npm/v/atabey)](https://www.npmjs.com/package/atabey)
 [![npm-mcp](https://img.shields.io/npm/v/atabey-mcp)](https://www.npmjs.com/package/atabey-mcp)
 [![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
 [![Type-Safety](https://img.shields.io/badge/Type--Safety-100%25-green.svg)](https://github.com/ysf-bkr/atabey)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 [![Tests](https://img.shields.io/badge/Tests-266%20passed-brightgreen)](https://github.com/ysf-bkr/atabey)
 [![MCP Tools](https://img.shields.io/badge/MCP%20Tools-35-blue)](https://github.com/ysf-bkr/atabey)
 [![Engine Tests](https://img.shields.io/badge/Engine%20Tests-56%20passed-brightgreen)](https://github.com/ysf-bkr/atabey)
 
-**Agent Atabey** is a **MCP (Model Context Protocol) server** that plugs directly into your AI coding interface — Claude Code, Gemini CLI, or Cursor — adding 13 specialized AI agents with enterprise-grade governance.
+**Agent Atabey** is an **MCP (Model Context Protocol) server** designed specifically for agentic developer workflows. It plugs directly into your AI coding interface — such as Claude Code, Gemini CLI, or Cursor — to govern, secure, and coordinate the terminal/CLI commands and file modification loops executed autonomously by these AI assistants.
 
 > **Philosophy:** "Order from Chaos"
-> **How it works:** Install → Connect to your AI → Use `@agent` commands in chat
+> **Governance Context:** In an agentic workflow, the AI assistant runs the development tools, shell commands, and file edits. Atabey acts as the deterministic governance and safety layer over these AI execution loops.
 
 ---
 
@@ -38,6 +38,9 @@ You (@backend): "Create a user login service with JWT authentication"
 
 **No separate terminal needed. No CLI commands for daily use.** Just chat with your AI and use `@agent` syntax.
 
+> [!NOTE]
+> **Execution Context:** The LLM inference/execution is handled entirely inside the developer's active AI interface (such as Claude Code or Cursor). Atabey acts as the context injector and policy engine, silently evaluating prompts, routing instructions, and checking output code against quality guidelines.
+
 ---
 
 ## 📋 Table of Contents
@@ -77,6 +80,7 @@ Atabey generates an `mcp.json` config. Point your AI assistant to it:
       "command": "npx",
       "args": ["-y", "atabey-mcp"],
       "env": {
+        "MCP_TRANSPORT": "stdio",
         "ATABEY_PROJECT_ROOT": "/path/to/your/project"
       }
     }
@@ -86,8 +90,10 @@ Atabey generates an `mcp.json` config. Point your AI assistant to it:
 
 **Gemini CLI:**
 ```bash
+# Stdio mode (local, single user)
 gemini config set mcpServers.atabey.command "npx"
 gemini config set mcpServers.atabey.args "[\"-y\", \"atabey-mcp\"]"
+gemini config set mcpServers.atabey.env "{\"MCP_TRANSPORT\": \"stdio\", \"ATABEY_PROJECT_ROOT\": \"/path/to/your/project\"}"
 ```
 
 **Cursor:**
@@ -97,7 +103,10 @@ gemini config set mcpServers.atabey.args "[\"-y\", \"atabey-mcp\"]"
   "mcpServers": {
     "atabey": {
       "command": "npx",
-      "args": ["-y", "atabey-mcp"]
+      "args": ["-y", "atabey-mcp"],
+      "env": {
+        "MCP_TRANSPORT": "stdio"
+      }
     }
   }
 }
@@ -139,11 +148,11 @@ Open your AI interface and simply type:
 └──────────────────────────────────────────────────────────────────┘
 ```
 
-Atabey is **not a separate platform**. It's a tool server that augments your existing AI assistant with:
-- **13 specialized agents** (backend, frontend, security, etc.)
-- **Deterministic quality gates** (AST analysis + lint + tests)
-- **Risk detection** (blocks destructive operations)
-- **Vector memory** (remembers past decisions)
+Atabey is **not a separate execution engine**. It is a context-aware governance and policy middleware that intercepts, validates, and routes the actions of AI coding assistants using their own CLIs:
+- **13 Specialized Agent Contexts** (injected templates to structure AI reasoning)
+- **Deterministic Quality Gates** (AST analysis + lint + tests validating AI writes before commit)
+- **Risk Gate & Heuristic Scanning** (blocking dangerous shell commands or edits and requiring human passcode confirmation)
+- **Persistent Vector Memory** (allowing AIs to query project context locally)
 - **Audit trails** (every action logged)
 
 ---
@@ -242,6 +251,9 @@ npx atabey init gemini
 
 ## 13 Specialized Agents
 
+> [!NOTE]
+> Each agent listed below represents a specialized prompt and rule-template context injected via the MCP server. The actual reasoning and file modification are performed by the developer's active client AI interface using the instructions supplied by these agents.
+
 | Agent | Tier | Role | Freelancer | Team | Enterprise |
 |-------|------|------|:----------:|:----:|:----------:|
 | **@manager** | Supreme | Orchestration, governance, quality gate | ✅ | ✅ | ✅ |
@@ -265,7 +277,7 @@ npx atabey init gemini
 ### 1. Deterministic Quality Gate
 No agent can push code directly to production. All outputs pass through AST analysis (compliance), linting, and unit tests. Failed code triggers an automatic 3-attempt retry loop.
 
-### 2. Autonomous Vector Memory
+### 2. Persistent Vector Memory
 Project context, contracts, and past tasks are stored locally via `better-sqlite3` using TF-IDF semantic search (cosine similarity). Agents search past architectural decisions.
 
 ### 3. Hermes Message Broker
@@ -274,6 +286,9 @@ Agents communicate asynchronously via a SQLite-backed message queue. A file-base
 ### 4. Risk Engine (Human-in-the-Loop — In-Chat Approval)
 Operations containing `DROP`, `DELETE`, `TRUNCATE`, or secret manipulation are flagged. Execution is blocked until human approval.
 
+> [!NOTE]
+> **Heuristic Detection:** The Risk Engine relies on deterministic keyword and path-pattern heuristics (e.g., matching SQL command strings) rather than complex machine learning models to identify and block high-risk operations.
+
 **In-Chat Approval (no terminal switch needed):**
 When an operation is blocked, the AI is instructed to call the `approve_operation` MCP tool:
 ```
@@ -298,7 +313,7 @@ Claude Code, Gemini CLI, Cursor, Codex CLI, Antigravity CLI — automatic agent
 Node.js, Go, Java, Python, .NET — automatic scaffolding based on backend language selection.
 
 ### 9. Multi-User Distributed Lock Registry
-When multiple developers work on the same repository, their autonomous agents might attempt to modify the same files simultaneously. Atabey implements a Git-aware distributed locking mechanism (`DistributedLock`). It dynamically identifies the lock owner using `git config user.name` and blocks other processes from mutating the locked resources until released or expired, preventing merge conflicts and race conditions.
+When multiple developers work on the same repository, their contextual agents might attempt to modify the same files simultaneously. Atabey implements a Git-aware distributed locking mechanism (`DistributedLock`). It dynamically identifies the lock owner using `git config user.name` and blocks other processes from mutating the locked resources until released or expired, preventing merge conflicts and race conditions.
 
 ### 10. Multi-Client MCP Support (Stdio + HTTP/SSE)
 Atabey supports two transport modes:
@@ -385,11 +400,11 @@ Atabey automatically classifies data into security levels:
 
 Data portability (KVKK Art. 11 / GDPR Art. 20):
 ```bash
-# Export all data
-atabey kvkk:export
+# View agent statuses, token usage, and cost distributions
+atabey status
 
-# Export audit logs
-atabey gateway stats
+# Run full health and compliance checks
+atabey check
 ```
 
 ### 15. Adapter-Skill System
@@ -499,12 +514,24 @@ atabey mcp install           Generate mcp.json config for AI integration
 atabey dashboard [port]      Open web dashboard (default: 5858)
 atabey status                Show agent statuses and costs
 atabey check                 Full health and compliance check
-atabey orchestrate           Start autonomous orchestration loop
+atabey orchestrate           Start orchestration workflow loop
 atabey approve <traceId>     Approve a blocked high-risk task (terminal alternative)
 atabey hitl answer "<text>"  Answer a pending ask_human question
 atabey @agent "task"         Send task directly to an agent
 ```
 
+### `atabey init [adapter]` Options
+
+| Option | Values | Description |
+|---|---|---|
+| `[adapter]` | `gemini`, `claude`, `cursor`, `grok`, `codex`, `local`, `antigravity-cli` | The target AI platform/client for initialization. |
+| `--profile` | `freelancer`, `team`, `enterprise` | Preset agent group layout and governance complexity. |
+| `--focus` | `fullstack`, `backend`, `frontend`, `mobile`, `mobile-fullstack` | Optimize active agents and templates for the project type. |
+| `--lang` | `tr`, `en` | Set the language for constitution (`ATABEY.md`) and standard operating procedures. |
+| `--unified` | *None (Flag)* | Place all agent instruction files under a single `.agents/` directory with native client links. |
+| `--yes` | *None (Flag)* | Run in non-interactive mode using default or provided parameters. |
+| `--dryRun` | *None (Flag)* | Simulate the initialization run without writing any files or folders to the workspace. |
+
 > **In-chat alternative:** Use `approve_operation` MCP tool directly in your AI CLI chat — no terminal switch needed.
 
 Full command list: see `atabey help` or [ARCHITECTURE.md](ARCHITECTURE.md)
@@ -538,7 +565,6 @@ Full command list: see `atabey help` or [ARCHITECTURE.md](ARCHITECTURE.md)
 
 ---
 
-
 ## ✅ Implemented Governance Features
 
 > These features were previously listed as "Blind Spots" but are now fully implemented:
@@ -553,11 +579,131 @@ Full command list: see `atabey help` or [ARCHITECTURE.md](ARCHITECTURE.md)
 
 ---
 
+## 🔍 Detailed Feature Analysis
+
+### Auto-Rollback & Rollback Mechanism
+`framework-mcp/src/utils/auto-rollback.ts`
+
+**How It Works:**
+```
+[AI write_file/replace_text/patch_file call]
+   │
+   ├── 1. Pre-Write Snapshot → Original file content saved (SnapshotManager)
+   ├── 2. Tool executes → File is written
+   ├── 3. Post-Write Validation → rules-engine.ts GOV scan
+   │      ├── ✅ Clean → Allow, clear snapshot
+   │      └── ❌ Violation (any type, console.log, secret, copyleft) →
+   │             ├── Original file restored
+   │             ├── New file deleted
+   │             └── REGENERATE instruction sent to AI:
+   │                 "⛔ AI Output Blocked – Governance Violation
+   │                  🔴 No `any` Type (file.ts:5)
+   │                  Fix: Replace `any` with `unknown`"
+   └── Dashboard WS → rollback_violation event
+```
+
+**Detected Violations:**
+| Violation | Severity | Detection |
+|-----------|----------|-----------|
+| `any` type usage | 🔴 CRITICAL | Regex: `: any\b` |
+| `console.log`/`.error`/`.warn`/`.debug` | 🔴 CRITICAL | Regex (exempts logger.ts) |
+| Hardcoded API Key (sk-, ghp_, AIza) | 🟠 HIGH | Regex pattern |
+| Hardcoded GitHub Token | 🟠 HIGH | `ghp_` pattern |
+| Copyleft license violation | 🔴 CRITICAL | `license-scanner.ts` |
+
+**Test Status:** ✅ `auto-rollback.test.ts` — 14 tests, 228 lines, all scenarios covered.
+
+**Critical Assessment:** Working. The `buildRegenerateInstruction()` method tells the AI exactly what it did wrong and how to fix it. This is far more valuable than simple blocking.
+
+---
+
+### Specialty Memory (Agent Learning Mechanism)
+`src/modules/engines/evaluation-engine.ts`
+
+| Status | Detail |
+|--------|--------|
+| ✅ **Error Learning** | Compliance/lint/test failure → `updateSpecialtyMemory()` writes to `.atabey/memory/specialties/<agent>.md` |
+| ❌ **Success Learning** | No mechanism to extract lessons from successful tasks |
+| ❌ **Auto-Injection** | `readLearnedConventions()` exists but is not automatically injected into AI context |
+| ⚠️ **Learning Opportunity** | Agent never asked "What did I learn from this task?" on completion |
+
+**Current Flow:**
+```
+Task → Evaluation → Any errors?
+   ├── Yes → `updateSpecialtyMemory(agent, "Compliance Violations Detected...")`
+   └── No → Nothing saved (❌)
+```
+
+**Desired Flow:**
+```
+Task → Evaluation →
+   ├── Error → Save error lesson
+   └── Success → Save success lesson: "agent/service pattern was used successfully"
+```
+
+---
+
+### Token/Cost Tracking (FinOps)
+`framework-mcp/src/utils/finops.ts`
+
+| Feature | Status |
+|---------|--------|
+| ✅ Per-agent token tracking | Every MCP tool call logged via `Metrics.logUsage()` |
+| ✅ Monthly budget | `ATABEY_BUDGET_MONTHLY` env for USD-based limit |
+| ✅ Per-agent budget | `ATABEY_BUDGET_AGENT_MAX` for agent-based limit |
+| ✅ Auto-shutdown | MCP middleware returns error when budget exceeded |
+| ✅ Alert thresholds | 50/80/90/100% warning levels |
+| ✅ Dashboard panel | FinOpsPanel.tsx with live visualization |
+| ✅ API endpoint | `GET /api/metrics` — agent/action level detail |
+| ❌ **Weekly Summary** | `atabey status` output does not provide a weekly rollup overview |
+
+**Usage:** `framework-mcp/src/index.ts` (lines 150-153) calls `Metrics.logUsage()` on every tool call.
+
+---
+
+### KVKK/GDPR Data Privacy
+`src/shared/pii.ts`
+
+| Pattern | Mask | Test |
+|---------|------|------|
+| Email | `***@***` | ✅ |
+| Phone (+90 TR, international) | `***-***-****` | ✅ |
+| TC ID (11 digits) | `***********` | ✅ |
+| API Key (OpenAI, GitHub, Google) | `***-REDACTED-***` | ✅ |
+| JWT Token | `***-JWT-REDACTED-***` | ✅ |
+| IP (IPv4, IPv6) | `***.***.***.***` | ✅ |
+| Credit Card (AMEX included) | `****-****-****-****` | ✅ |
+| IBAN | `****-IBAN-REDACTED-****` | ✅ |
+| Date of Birth | `**/**/****` | ✅ |
+| SSN (US) | `***-**-****` | ✅ |
+| Password/Secret fields | `***-REDACTED-***` | ✅ |
+
+**Layered Protection:**
+1. **MCP Middleware** — `maskToolArgs()`: AI arguments masked before reaching handler
+2. **MCP Middleware** — `maskToolResult()`: Handler result masked before returning to AI
+3. **Logger** — All log entries scanned for PII
+4. **Dashboard API** — All API responses masked
+
+**Dashboard:** PrivacyPanel.tsx — PII masked/detected statistics, category distribution, Right to Erasure.
+
+---
+
+### 🐞 Detected Issues
+
+| # | Issue | File | Fix |
+|---|-------|------|-----|
+| 1 | `MCP_TRANSPORT=stdio` env missing | `src/cli/commands/mcp.ts:66` | Added `MCP_TRANSPORT: "stdio"` |
+| 2 | No success task learning | `src/modules/engines/evaluation-engine.ts` | `updateSpecialtyMemory()` should be called on success too |
+| 3 | Specialty memory not auto-injected into AI | `silent-router.ts` / `discipline.ts` | `.atabey/memory/specialties/*.md` content should be injected on agent calls |
+| 4 | No weekly cost summary | `finops.ts` | Add weekly rollup statistics to `atabey status` command |
+
+---
+
 ## Strategic Roadmap
 
 | # | Feature | Priority | Status |
 |---|---------|----------|--------|
-| 1 | Agent specialty memory → auto-sync to agent files | 🟠 High | Planned |
+| 1 | Agent specialty memory → auto-sync to agent files | 🟠 High | 🟡 **Partial** (error learning only) |
 | 2 | MCP `prompts/` endpoint for session-level governance injection | 🟠 High | Planned |
 | 3 | Central Enterprise Server (telemetry ingest + org dashboard) | 🟡 Medium | Planned |
 | 4 | Dynamic rule loading from `.atabey/rules/*.json` | 🟡 Medium | Planned |
@@ -566,14 +712,17 @@ Full command list: see `atabey help` or [ARCHITECTURE.md](ARCHITECTURE.md)
 
 ## Security
 
+### Enterprise-Grade Governance
+Atabey defines "enterprise-grade" through deterministic rules: AST compliance parsing, strict TypeScript type validation (zero `any`), syntax/linter checks, and automated unit tests, rather than unpredictable probabilistic algorithms.
+
 ### Zero Type Hole Policy
 - `any` type usage is **strictly forbidden**
 - All function inputs validated with Zod schemas
 - Type safety enforced in CI pipeline
 
-### Zero Mock Policy
-- Mock data usage is **forbidden** (except 3rd party services)
-- Tests run against real implementations
+### Prudent Mocking Policy
+- Core governance logic, schemas, and rule engines are verified against real implementations without mock data.
+- Unit and integration boundaries (such as remote Hermes polling loops, network calls, and LLM provider interfaces) utilize lightweight, standard mocks to ensure isolation and fast test execution.
 
 ### PII Masking (KVKK Compliant)
 - All logs scanned for Personally Identifiable Information
@@ -613,9 +762,18 @@ npm run build
 
 ---
 
-## License
+## License & Business Model
+
+**Code:** GNU Affero General Public License v3.0 — [Yusuf BEKAR](mailto:ybekar@msn.com)
+
+This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+**Network Use Clause (Section 13):** If you modify the Program and make it accessible over a network (e.g., as a SaaS service), you must provide the complete corresponding source code to all users who interact with it remotely. This prevents others from selling Atabey as a closed-source SaaS.
 
-MIT License — [Yusuf BEKAR](mailto:ybekar@msn.com)
+**Service Model (Support / SLA / Consulting):** The code is **100% free and open source**. Revenue comes from:
+- **Enterprise Support & SLA** — Guaranteed response times, priority bug fixes, custom integrations
+- **Consulting & Training** — Team onboarding, governance policy design, architecture review
+- **Managed Enterprise Server** — Centralized telemetry, multi-team budget management, org-wide dashboard
 
 Enterprise inquiries: **ybekar@msn.com**
 

package/bin/cli.js

@@ -1,26 +1,93 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
 import fs from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+// ─── Friendly Error Messages ──────────────────────────────────────
+const ERRORS = {
+    BUILD_REQUIRED: `
+╔══════════════════════════════════════════════════════════╗
+║  🚧  Atabey is not built yet                           ║
+╠══════════════════════════════════════════════════════════╣
+║  The compiled CLI was not found at:                     ║
+║    dist/src/cli/index.js                                ║
+║                                                         ║
+║  📋  To fix this, run:                                  ║
+║     npm run build                                       ║
+║                                                         ║
+║  💡  This compiles TypeScript source into JavaScript.   ║
+║     After build completes, run atabey again.            ║
+╚══════════════════════════════════════════════════════════╝
+`,
+    NODE_VERSION: `
+╔══════════════════════════════════════════════════════════╗
+║  ⚠️  Unsupported Node.js version                       ║
+╠══════════════════════════════════════════════════════════╣
+║  Atabey requires Node.js >= 18.0.0                      ║
+║                                                         ║
+║  Current version: {version}                             ║
+║                                                         ║
+║  📋  To fix this:                                       ║
+║     • Install Node.js 18+ via:                          ║
+║       nvm install 18  (if using nvm)                    ║
+║       brew install node  (if using Homebrew)            ║
+║       https://nodejs.org  (official installer)          ║
+║                                                         ║
+║     • Then switch to it:                                ║
+║       nvm use 18    (if using nvm)                      ║
+╚══════════════════════════════════════════════════════════╝
+`,
+    SPAWN_FAILED: `
+╔══════════════════════════════════════════════════════════╗
+║  ❌  Failed to start Atabey                             ║
+╠══════════════════════════════════════════════════════════╣
+║  Could not launch the CLI process.                      ║
+║                                                         ║
+║  📋  Common causes:                                     ║
+║     • Out of memory                                     ║
+║     • System resource limits                            ║
+║     • Permission issues                                 ║
+║                                                         ║
+║  Try running again, or check logs for details.          ║
+╚══════════════════════════════════════════════════════════╝
+`,
+};
+
+// ─── Node.js Version Check ────────────────────────────────────────
+const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
+if (nodeMajor < 18) {
+    process.stderr.write(ERRORS.NODE_VERSION.replace("{version}", process.versions.node));
+    process.exit(1);
+}
+
+// ─── Start CLI ────────────────────────────────────────────────────
 const cliPath = join(__dirname, "../dist/src/cli/index.js");
 
 if (!fs.existsSync(cliPath)) {
-    process.stderr.write("\n[ERROR] Error: Compiled CLI not found at 'dist/src/cli/index.js'\n");
-    process.stderr.write("[TIP] Solution Tip: Run 'npm run build' to compile the project first.\n\n");
+    process.stderr.write(ERRORS.BUILD_REQUIRED);
     process.exit(1);
 }
 
 const cmd = "node";
 const child = spawn(cmd, [cliPath, ...process.argv.slice(2)], {
     stdio: "inherit",
-    shell: false 
+    shell: false
+});
+
+child.on("error", (err) => {
+    process.stderr.write(ERRORS.SPAWN_FAILED);
+    process.stderr.write(`\n[DETAIL] ${err.message}\n\n`);
+    process.exit(1);
 });
 
 child.on("exit", (code) => {
+    if (code !== 0 && code !== null) {
+        // Non-zero exit — the CLI already printed the error
+        process.exit(code);
+    }
     process.exit(code ?? 0);
 });