ebade 0.4.0 → 0.4.3

package/ARCHITECTURE.md

@@ -0,0 +1,109 @@
+# ebade Architecture 🏗️
+
+> **The System of Intent.**
+
+ebade is not just a framework; it's a **compilation pipeline** designed for an era where AI agents are the primary authors of software. This document explains the technical underpinnings of how ebade transforms abstract niyet (intent) into production-ready code.
+
+---
+
+## 🏁 The Core Pipeline
+
+The ebade transformation follows a strictly deterministic flow:
+
+```mermaid
+graph LR
+    A[Intent File .ebade.yaml] --> B[ebade CLI/MCP]
+    B --> C[Intent AST Parser]
+    C --> D[Target Adapter Next.js/etc]
+    D --> E[AI-Enhanced Scaffolder]
+    E --> F[Production Codebase]
+```
+
+### 1. Intent Definition (`.ebade.yaml`)
+
+The source of truth. It defines **WHAT** the application should be, sans implementation details. It uses a high-density decorator syntax that is optimized for LLM token efficiency.
+
+### 2. AST Parsing
+
+The ebade CLI parses the YAML/TypeScript intent into a **Standardized Intent Tree (SIT)**. This tree represents the semantic meaning of the application (pages, components, data flows, auth rules).
+
+### 3. Target Adapters
+
+ebade is target-agnostic. While it currently ships with a high-end **Next.js + Tailwind + Shadcn** adapter, the architecture allows for:
+
+- **Web:** Next.js, Nuxt, SvelteKit.
+- **Mobile:** Flutter, SwiftUI, React Native.
+- **Backend:** Fastify, Go/Gin, NestJS.
+
+### 4. Auto-Verification Protocol (The Guardrail)
+
+Immediately after scaffolding, ebade runs a series of integrity checks:
+
+- **Structural Integrity:** Ensures all core Next.js and Tailwind files are present.
+- **Intent-Code Mapping:** Verifies that exported component names and routes match the original intent.
+- **Test Coverage:** Confirms that matching unit tests (Vitest) have been generated for every new component.
+
+### 5. AI-Enhanced Scaffolding (The "Online Compiler")
+
+This is where the magic happens. ebade uses AI not as a "free-text generator," but as a **Deterministic Compiler Component**.
+
+- **Templates:** ebade provides a library of high-quality, pre-tested component templates.
+- **Mapping:** The AI maps the specific fields and logic from the `@intent` into these templates.
+- **Validation:** Every generated file is validated against the intent AST to ensure zero hallucinations.
+
+---
+
+## 🟢 Green AI: Token Density Architecture
+
+Traditional AI coding (e.g., "Write me a dashboard") is **High Entropy**:
+
+- User sends 50 tokens.
+- AI returns 2,000 tokens of boilerplate.
+- High cost, high noise, high probability of error.
+
+ebade is **Low Entropy**:
+
+- Intent is defined in ~50-100 tokens.
+- ebade handles the structure, imports, and layout (0 tokens).
+- AI only fills in the specific business logic snippets.
+- **Result:** ~70% fewer tokens, 100% more reliable.
+
+---
+
+## 🛠️ Internal Structure
+
+### Intent Model
+
+The `Intent` model is the central class that holds the parsed state.
+
+```typescript
+class IntentProject {
+  name: string;
+  type: ProjectType;
+  pages: PageIntent[];
+  components: ComponentIntent[];
+  data: DataIntent[];
+  auth: AuthConfig;
+}
+```
+
+### The Scaffold Engine
+
+The engine responsible for directory creation and file writing. It uses a "Clean Architecture" approach, ensuring that:
+
+1. Components stay in `@/components`.
+2. Logic stays in `@/lib`.
+3. UI stays in `@/app`.
+
+---
+
+## 🧬 Principles of ebade Engineering
+
+1. **Delete the How:** If a machine can infer the implementation, it shouldn't be in the source file.
+2. **Deterministic Outputs:** Same input must yield the same structure.
+3. **Agent-First DX:** The developer experience (DX) is optimized for the agent's context window.
+4. **Production-Ready by Default:** No "TODOs" in the output. Real types, real error handling, real responsive design.
+
+---
+
+_ebade: Compiling Intent into Reality._ 🌱🚀

package/CHANGELOG.md

@@ -5,15 +5,26 @@ All notable changes to **ebade** will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.4.3] - 2025-01-10
+
+### Fixed
+- Critical bug where templates were not found when running via `npx` (fix using `import.meta.url`).
+- Added missing component templates for SaaS Dashboard and Landing Pages (`testimonials`, `faq-accordion`, `cta-banner`, `activity-chart`, `stats-grid`, `recent-events`).
+- Updated `tsconfig.json` generation to use `jsx: preserve` and added path aliases (`@/*`).
+- Added slugification for `package.json` names to ensure valid naming conventions.
+- Synced framework versions across all packages.
+
+## [0.4.1] - 2025-01-10
 
 ### Added
 
+- **Auto-Verification Layer** - CLI now performs structural, syntax, and semantic integrity checks after scaffolding.
 - **Playground UI** - Interactive "Battle Mode" simulation comparing Legacy AI vs ebade-powered Agent.
 - **Shadcn/UI Integration** - All component templates now use Shadcn design patterns.
 - **20+ Component Templates** - navbar, footer, pricing-table, login-form, signup-form, and more.
 - **File-based Template System** - Dynamic template loading from `cli/templates/`.
 - **Real-time Token Savings** - CLI now displays actual token savings during scaffold.
+- **Agent-Native Stack Vision** - Identity (agents.md) + Capability (MCP) + Intent (ebade).
 - MCP Server branding update to **ebade**.
 - Green AI Metrics and Carbon Impact calculations.
 - Turkish identity integration (Badik mascot 🐣 and "The Essence of Code" vision).
@@ -26,7 +37,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - 🎉 Initial alpha release of **ebade**
-- MCP Server package (`@ebade/mcp-server`) with 4 tools:
+- MCP Server package (`ebade-mcp-server`) with 4 tools:
   - `ebade_scaffold` - Create full projects from ebade definitions
   - `ebade_validate` - Validate ebade files against schema
   - `ebade_compile` - Compile single ebade to code

package/README.md

@@ -1,4 +1,4 @@
-# ebade
+# ebade: The Agent-First Protocol 🧠🌱
 
 ![ebade - The First Agent-First Framework](https://ebade.dev/og-readme.png)
 
@@ -6,254 +6,116 @@
 [![Website](https://img.shields.io/badge/Website-ebade.dev-4F46E5)](https://ebade.dev)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![MCP Server](https://img.shields.io/badge/MCP-Ready-green.svg)](./packages/mcp-server)
-[![Status](https://img.shields.io/badge/Status-Alpha-orange.svg)](./ROADMAP.md)
 [![Green AI](https://img.shields.io/badge/🌱_Green_AI-70%25_Less_Tokens-brightgreen)](./docs/GREEN-AI.md)
-[![Agent-Native](https://img.shields.io/badge/Agent--Native-Universal_AI_Support-black)](./SYNTAX.md)
-[![Sponsor](https://img.shields.io/badge/Sponsor-ebade-pink.svg?logo=github-sponsors)](https://github.com/sponsors/hasankemaldemirci)
+[![Architecture](https://img.shields.io/badge/Architecture-First_Principles-black)](./ARCHITECTURE.md)
 
-> **The first framework designed for AI agents, readable by humans.**
->
-> `Code = f(ebade)`
->
-> _Capture the essence of code. Less tokens. Less carbon. Same result._ 🌱
+> **"Code is a legacy byproduct. Intent is the source of truth."**
 
-## 🎬 See it in action
+**ebade** is not just another framework. It is a **compilation protocol** designed for an era where AI Agents are the primary developers. It shifts the paradigm from "Human-Centric Coding" to "Agentic Intent Modeling."
+
+---
+
+## 🎬 The Power of Intent
+
+Watch how **ebade** transforms 20 lines of YAML into a production-ready, full-stack Next.js application.
 
 ![ebade demo](./assets/demo.gif)
 
-```typescript
+### ⚔️ The Battle of Entropy
 
-// ❌ Before: 100+ lines of boilerplate
-export default function CheckoutPage() {
-  const [cart, setCart] = useState([]);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState(null);
-  useEffect(() => { /* fetch data */ }, []);
-  // ... 100 more lines of HOW
-}
+| Legacy Coding (High Entropy) | ebade Protocol (Low Entropy) |
+| :--- | :--- |
+| **"Write me a dashboard..."** | **"@intent('saas-dashboard')"** |
+| AI guesses folders, imports, and state. | ebade enforces architecture. |
+| 1,500+ tokens burned (Noise). | **<250 tokens** used (Pure Signal). |
+| Hallucinations likely. | **Deterministic** output. |
 
-// ✅ After: Pure intent - WHAT you want
-@page('/checkout')
-@intent('complete-purchase')
-@requires({ data: ['cart', 'user'], auth: 'required' })
-@outcomes({ success: '/order/[id]', error: 'show-inline' })
-export function Checkout({ cart, user }) {
-  // Just business logic, zero boilerplate
-}
-```
+---
+
+## 🛠️ The Syntax (Cheat Sheet)
+
+ebade uses a high-density decorator syntax designed to fit within an Agent's context window.
+
+| Decorator | Purpose | Example |
+| :--- | :--- | :--- |
+| `@page` | Defines routes & paths | `@page('/dashboard')` |
+| `@intent` | The "What" of the logic | `@intent('user-auth')` |
+| `@requires` | Data & Auth dependencies | `@requires(['user', 'db'])` |
+| `@compose` | Intent orchestration | `@compose(['header', 'list'])` |
+| `@outcomes` | Result handlers & UI | `@outcomes({ success: '/dashboard' })` |
+| `@expects` | **Tests as Specification** | `@expects([{ scenario: 'happy-path' }])` |
+
+📖 [Full Syntax Specification](./SYNTAX.md)
 
 ---
 
 ## 🚀 Quick Start
 
-### For AI Agents (MCP)
+### 1. For Agents (MCP)
 
-**ebade** is designed to be used BY AI agents. Add to your MCP configuration:
+Add `ebade` to your AI agent (Claude, Cursor, Windsurf) via the Model Context Protocol:
 
 ```json
 {
   "mcpServers": {
     "ebade": {
-      "command": "node",
-      "args": ["./packages/mcp-server/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "ebade-mcp-server"]
     }
   }
 }
 ```
 
-Then AI agents can use:
-
-- `ebade_scaffold` - Create full projects from intent
-- `ebade_compile` - Compile single intents to code
-- `ebade_validate` - Validate intent files
-- `ebade_generate` - Generate from natural language
-
-### For Humans (CLI)
+### 2. For Humans (CLI)
 
 ```bash
-# Scaffold a new project from an ebade file
+# Scaffold a full project from an intent file
 npx ebade scaffold examples/saas-dashboard.ebade.yaml ./my-app
-
-# See all commands
-npx ebade --help
 ```
 
 ---
 
-## 🤖 Integrated AI Synergy
+## 🏗️ Architecture: First Principles
 
-**ebade** projects automatically configure themselves for AI collaboration. When you scaffold a project, it generates specialized instruction files for major AI agents:
+ebade operates on the principle of **The Online Compiler**. It treats AI as a deterministic component of the toolchain, not a creative oracle.
 
-- **Cursor**: `.cursorrules`
-- **Claude / Windsurf**: `.clauderules`
-- **GitHub Copilot**: `.github/copilot-instructions.md`
+- **Standardized Intent Tree (SIT):** Parses YAML/TS into a logical graph.
+- **Target Adapters:** Compiles intent into Next.js, Flutter, or Svelte (0-token boilerplate).
+- **AgentRules:** Automatically generates `.cursorrules` and `.clauderules` to keep your agent aligned.
 
-These files teach the AI agents exactly how to work with ebade intents, ensuring they never "hallucinate" boilerplate and always stay token-efficient.
+🏗️ [Explore the Architecture](./ARCHITECTURE.md)
 
 ---
 
-## 📊 Benchmark: ~70% Fewer Tokens (Tested)
+## 📊 Benchmark: ~70% Fewer Tokens
 
-We measured token usage across common development tasks:
+| Task | Legacy (Next.js) | ebade (Protocol) | Savings |
+| :--- | :--- | :--- | :--- |
+| **SaaS Dashboard** ⭐ | 1,850 tokens | **245 tokens** | **86.8%** |
+| Checkout Flow | 258 tokens | **66 tokens** | **74.4%** |
+| Product Grid | 133 tokens | **63 tokens** | **52.6%** |
 
-| Task              | Next.js      | ebade      | Savings   | Efficiency |
-| :---------------- | :----------- | :--------- | :-------- | :--------- |
-| Checkout Page     | 258 tokens   | 66 tokens  | **74.4%** | 3.9x       |
-| Product Listing   | 133 tokens   | 63 tokens  | **52.6%** | 2.1x       |
-| User Auth         | 148 tokens   | 56 tokens  | **62.2%** | 2.6x       |
-| SaaS Dashboard ⭐ | 1,850 tokens | 245 tokens | **86.8%** | 7.6x       |
-| **Average**       |              |            | **68.8%** | **4.1x**   |
-
-> _For full project scaffolding, savings can reach 75-92%._
-
-### 💰 Cost Impact
-
-At scale (1M AI coding sessions):
-
-| Framework | Token Cost | Savings    |
-| :-------- | :--------- | :--------- |
-| Next.js   | $5,390     | -          |
-| **ebade** | **$1,850** | **$3,540** |
-
-> _The greenest code is the code you don't generate._
-
-📄 [Full Benchmark Results](./benchmarks/RESULTS.md) | 🌱 [Green AI Manifesto](./docs/GREEN-AI.md)
+> "The greenest code is the code you don't generate." 🌱
 
 ---
 
-## 💡 The Problem
-
-AI agents (Cursor, Copilot, Claude) write code for **human-designed frameworks**:
+## 📦 Project Structure
 
-```text
-AI: "Is this a server or client component?"
-
-AI: "App router or pages router?"
-AI: "useState or useReducer?"
-AI: "Where does this file go?"
-```
-
-Every decision is **ambiguous**. AI guesses. Sometimes wrong.
-
-## ✨ The Solution
-
-**ebade** - A framework where AI expresses **intent**, not implementation.
-
-```text
-Human describes → AI writes intent → ebade compiles → Working code
-                        ↑
-                 No ambiguity here
-```
+- **`www/`**: The [ebade.dev](https://ebade.dev) landing page & playground.
+- **`packages/mcp-server/`**: The bridge for AI agents.
+- **`cli/`**: The core scaffolding engine.
+- **`examples/`**: Real-world intent templates.
 
 ---
 
-## 📦 Packages
+## 🤝 Join the Revolution
 
-| Package                                    | Description              | Status      |
-| :----------------------------------------- | :----------------------- | :---------- |
-| **`ebade`**                                | Core Framework & CLI     | ✅ Alpha    |
-| [@ebade/mcp-server](./packages/mcp-server) | MCP Server for AI agents | ✅ Alpha    |
-| `@ebade/compiler`                          | Advanced Intent Compiler | 🚧 Planning |
-| `@ebade/vscode`                            | VS Code extension        | 📋 Planned  |
+1. **Star the repo** to show your support ⭐
+2. **Become a Sponsor** to help us build a Green AI future 💖
 
 ---
 
-## 🎯 Core Concepts
-
-### Intent-First
-
-```typescript
-@intent('user-authentication')
-@inputs(['email', 'password'])
-@outcomes({ success: '/dashboard', failure: 'show-error' })
-```
-
-You say **WHAT**, not **HOW**.
-
-### Deterministic
-
-Same intent = Same output. Every time. No guessing.
-
-### Composable
-
-```typescript
-@compose(['header', 'sidebar', 'content', 'footer'])
-```
-
-Small intents build big applications.
-
-### Target-Agnostic
-
-```typescript
-@compile('nextjs')   // → Next.js App Router
-@compile('vue')      // → Vue + Nuxt (coming)
-@compile('svelte')   // → SvelteKit (coming)
-```
-
-One intent, many outputs.
-
----
-
-## 📋 Example
-
-```yaml
-# project.intent.yaml
-
-name: my-store
-type: e-commerce
-features:
-  - product-catalog
-  - shopping-cart
-  - checkout
-  - user-auth
-
-pages:
-  - path: /
-    intent: landing-page
-    components:
-      - hero-section
-      - featured-products
-      - testimonials
-
-  - path: /products
-    intent: product-listing
-    components:
-      - search-bar
-      - product-grid
-      - pagination
-
-  - path: /checkout
-
-    intent: checkout-flow
-    auth: required
-    components:
-      - cart-summary
-      - payment-form
-```
-
-**Output:** Full Next.js project with 20+ files, ready to run.
-
----
-
-## 🎭 The Paradigm Shift
-
-| Era      | Paradigm  | Core Question                    |
-| :------- | :-------- | :------------------------------- |
-| 2000s    | jQuery    | "How do I manipulate DOM?"       |
-| 2013     | React     | "What if UI = f(state)?"         |
-| 2024     | AI Coding | "AI writes code, but for humans" |
-| **2026** | **ebade** | **"What if Code = f(intent)?"**  |
-
----
-
-## 📚 Documentation
-
-- 📜 [Manifesto](./MANIFESTO.md) — Philosophy & Vision
-- 📖 [Syntax Spec](./SYNTAX.md) — Complete Decorator Reference
-- 🗺️ [Roadmap](./ROADMAP.md) — Development Plan
-- 📁 [Examples](./examples/) — Real-world Intent Files
-- 📊 [Benchmarks](./benchmarks/) — Token & Cost Analysis
-- 🌱 [Green AI](./docs/GREEN-AI.md) — Environmental Impact
+MIT © ebade Contributors — Made with ❤️ in Türkiye 🇹🇷
 
 ---