@africode/core 5.0.4 → 5.0.6

package/AGENTS.md

@@ -0,0 +1,583 @@
+# 🤖 AGENTS.md — AfriCode v5.0.0 Robot-First Specification
+
+**Purpose**: This document defines the canonical technology stack, coding conventions, and framework grammar for all AI agents building on AfriCode. It ensures generated code is "native" and secure.
+
+**Last Updated**: May 2, 2026  
+**Framework Version**: 5.0.0  
+**Target Deployment**: Bun Runtime (v1.3.12+) on AMD AI Cloud & Alibaba Cloud Assets
+
+---
+
+## 🏗️ Canonical Technology Stack
+
+### Runtime & Build
+- **Runtime**: Bun v1.3.12+ (native, all-in-one: runtime + bundler + test runner)
+- **Language**: ES2024 JavaScript (native, no transpilation needed for modern syntax)
+- **Module Format**: ESM (native Bun import/export)
+- **Build System**: Bun.build() with custom plugins for SVG optimization
+- **Development Server**: Bun.serve() with FileSystemRouter for automatic routing
+
+### UI & Components
+- **Component Model**: Web Components (Custom Elements + Shadow DOM + Slots)
+- **State Management**: Proxy-based reactivity (core/state.js) — zero virtual DOM
+- **Styling**: CSS Variables + Logical Properties (CSS Containment Level 3)
+- **Pattern Generation**: Procedural SVG (no asset uploads needed)
+- **Message Protocol**: A2UI v1.0 (core/a2ui.js) for AI-generated interfaces
+
+### Data & Persistence
+- **Primary Store**: Bun.SQLite (synchronous API, ultra-fast)
+- **Migration System**: Bun-native SQL scripts in migrations/ folder
+- **Query Pattern**: Direct SQL with type-safe parameter binding
+- **Cache Layer**: In-memory Proxy objects with automatic expiry
+
+### Security & Compliance
+- **Authentication**: Session-based (HttpOnly cookies + SameSite=Strict)
+- **Hashing**: Argon2id (built into Bun)
+- **Fintech Compliance**: NIDA CIG + TIPS + AML/FIU middleware
+- **Cryptography**: Ed25519 for message signing (Bun.crypto)
+- **CORS**: Frame-based origin isolation via Web Components
+
+---
+
+## 📐 Canonical Directory Structure
+
+```
+AfriCode/
+├── bin/                          # CLI entry points
+│   ├── africode.js              # Main CLI
+│   └── create-africode.js       # Project scaffolder
+├── core/                         # Framework internals (do not modify)
+│   ├── sdk.js                   # Main export
+│   ├── state.js                 # Reactive state engine
+│   ├── store.js                 # Global store singleton
+│   ├── a2ui.js                  # AI message protocol
+│   ├── compliance.js            # Fintech middleware
+│   ├── bun-runtime.js           # Bun server initialization
+│   ├── router.js                # FileSystemRouter
+│   ├── html.js                  # HTML template utilities
+│   ├── patterns.js              # SVG procedural generation
+│   ├── validation.js            # Input validation schemas
+│   ├── server/                  # Server utilities
+│   │   ├── auth.js              # Session management
+│   │   ├── db.js                # Database layer
+│   │   ├── render.js            # SSR template rendering
+│   │   └── router.js            # Route handler utilities
+│   └── cli/                      # CLI implementation
+│       └── commands/            # Command handlers
+├── components/                   # Web Components (pre-approved)
+│   ├── index.js                 # Component registry & exports
+│   ├── base.js                  # BaseElement class
+│   ├── button.js                # Button component
+│   ├── card.js                  # Card component
+│   ├── cultural-card.js         # Cultural card variant
+│   ├── kanga-card.js            # Kanga pattern card
+│   ├── form.js                  # Form wrapper
+│   ├── input.js                 # Input control
+│   ├── select.js                # Select dropdown
+│   ├── modal.js                 # Modal dialog
+│   ├── navbar.js                # Navigation bar
+│   └── [33 total components]
+├── patterns/                     # Procedural SVG generators
+│   ├── kente.js                 # Kente weaving patterns
+│   ├── shuka.js                 # Maasai Shuka tartan
+│   ├── ndebele.js               # Ndebele geometric
+│   ├── kitenge.js               # Kitenge florals
+│   └── [8 regional patterns]
+├── samples/                      # 🆕 Hand-curated LLM examples
+│   ├── README.md                # Usage guide for agents
+│   ├── basic-app/               # Minimal app (5 files)
+│   │   ├── package.json
+│   │   ├── pages/index.html
+│   │   ├── styles/theme.css
+│   │   └── core/app.js
+│   ├── fintech-kiosk/           # Payment flow (Lipa Namba)
+│   │   ├── pages/
+│   │   │   ├── index.html       # Entry
+│   │   │   ├── [payment-id].html # Dynamic route
+│   │   │   └── api/payment.js
+│   │   ├── components/
+│   │   │   ├── payment-form.js
+│   │   │   ├── nida-verify.js
+│   │   │   └── confirmation.js
+│   │   └── core/
+│   │       ├── merchant-service.js
+│   │       └── compliance-check.js
+│   ├── cultural-showcase/       # Pattern display
+│   │   ├── pages/
+│   │   ├── components/
+│   │   └── core/pattern-service.js
+│   ├── admin-dashboard/         # Multi-user app
+│   │   ├── pages/auth/login.html
+│   │   ├── pages/dashboard/
+│   │   ├── components/data-table.js
+│   │   └── middleware/auth-check.js
+│   └── [8+ regional examples]
+├── migrations/                   # SQL schema versioning
+│   └── 001_initial_schema.sql   # Base schema with compliance fields
+├── styles/                       # Design tokens
+│   ├── africanity.css           # Main theme
+│   └── typography.css           # Type scale
+├── tests/                        # Test pyramid (70/20/10)
+│   ├── unit/                    # 70% unit tests
+│   │   ├── state.test.js
+│   │   ├── patterns.test.js
+│   │   ├── validation.test.js
+│   │   └── [compliance tests]
+│   ├── integration/             # 20% integration tests
+│   │   ├── a2ui.test.js
+│   │   ├── router.test.js
+│   │   ├── nida-flow.test.js    # NIDA verification
+│   │   ├── tips-payment.test.js # TIPS payment
+│   │   └── aml-screening.test.js
+│   └── e2e/                     # 10% critical journeys
+│       ├── signup-nida.test.js  # Register + verify
+│       ├── lipa-namba.test.js   # Payment flow
+│       └── merchant-checkout.test.js
+├── package.json                  # Main entry point metadata
+├── bunfig.toml                   # Bun configuration
+├── tsconfig.json                 # TypeScript settings (optional)
+├── AGENTS.md                     # 🆕 This file — AI training spec
+├── COMPONENT_SCHEMA.json         # 🆕 Auto-generated component manifest
+└── README.md                      # User documentation
+```
+
+---
+
+## 🎯 Coding Conventions (AI Must Follow)
+
+### File Naming & Structure
+- **Component files**: `kebab-case.js` (e.g., `payment-form.js`)
+- **Utility/service files**: `kebab-case.js` (e.g., `merchant-service.js`)
+- **Test files**: `*.test.js` (e.g., `nida-flow.test.js`)
+- **One component per file** (no monoliths)
+- **Named exports for utilities**, default export for components
+
+### JavaScript Patterns
+
+#### ✅ CORRECT
+```javascript
+// components/payment-form.js
+export class PaymentForm extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+  
+  connectedCallback() {
+    this.render();
+    this.setupEventListeners();
+  }
+  
+  render() {
+    this.shadowRoot.innerHTML = `...`;
+  }
+  
+  setupEventListeners() {
+    this.addEventListener('submit', (e) => this.handleSubmit(e));
+  }
+  
+  async handleSubmit(e) {
+    e.preventDefault();
+    const result = await this.validate();
+    if (result.ok) this.dispatchEvent(new CustomEvent('success', { detail: result }));
+  }
+}
+
+customElements.define('af-payment-form', PaymentForm);
+```
+
+#### ❌ AVOID
+```javascript
+// DON'T use React JSX
+const PaymentForm = () => <form>...</form>;
+
+// DON'T use Vue/Svelte syntax
+<script setup>
+  const form = ref(null);
+</script>
+
+// DON'T use external state libraries (Redux, Zustand)
+import { store } from '@stores/payment';
+
+// DON'T use DOM selectors without scoping
+document.querySelector('.form'); // ❌ Global scope
+
+// DO scope to Shadow DOM
+this.shadowRoot.querySelector('.form'); // ✅ Encapsulated
+```
+
+### State Management Pattern
+```javascript
+// core/app-state.js (CORRECT)
+import { createReactiveState } from 'africode/core/state.js';
+
+export const appState = createReactiveState({
+  user: null,
+  payment: { amount: 0, status: 'idle' },
+  nida: { verified: false, nin: null }
+});
+
+// Subscribe to changes
+appState.subscribe('payment.status', (newStatus) => {
+  console.log('Payment status changed:', newStatus);
+});
+```
+
+### API Route Pattern
+```javascript
+// pages/api/payment.js (CORRECT)
+export async function POST(request) {
+  const body = await request.json();
+  
+  // Validate input
+  const validation = validatePayload(body, paymentSchema);
+  if (!validation.ok) return new Response(validation.error, { status: 400 });
+  
+  // Check compliance
+  const amlResult = await checkAMLScreening(body.amount);
+  if (!amlResult.ok) return new Response('Transaction blocked', { status: 403 });
+  
+  // Process payment
+  const tx = await processPayment(body);
+  return new Response(JSON.stringify(tx), { status: 200 });
+}
+```
+
+### Component Composition
+```javascript
+// pages/checkout.html (CORRECT)
+<af-payment-form id="form">
+  <af-nida-verify slot="identity"></af-nida-verify>
+  <af-card slot="summary">
+    <h2>Order Summary</h2>
+    <af-price amount="50000"></af-price>
+  </af-card>
+</af-payment-form>
+
+<script type="module">
+  import 'africode/components/index.js';
+  
+  const form = document.querySelector('af-payment-form');
+  form.addEventListener('success', (e) => {
+    console.log('Payment confirmed:', e.detail);
+  });
+</script>
+```
+
+### Error Handling
+```javascript
+// Middleware pattern
+export function complianceCheck(handler) {
+  return async (request) => {
+    try {
+      const compliant = await validateCompliance(request);
+      if (!compliant) throw new Error('Compliance failed');
+      return await handler(request);
+    } catch (error) {
+      console.error('Compliance error:', error);
+      return new Response(
+        JSON.stringify({ error: error.message, code: 'COMPLIANCE_ERROR' }),
+        { status: 403 }
+      );
+    }
+  };
+}
+```
+
+---
+
+## 🔐 Fintech Compliance Grammar
+
+### NIDA Verification Flow
+```javascript
+// core/server/nida-flow.js
+export async function verifyNIDA(nin, pin) {
+  // Step 1: Sign request with Ed25519 private key
+  const signature = await signRequest({ nin, timestamp: Date.now() }, privateKey);
+  
+  // Step 2: Call CIG endpoint over TLS 1.3
+  const response = await fetch('https://api.nida.go.tz/cig/verify', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Signature': signature,
+      'X-Client-Id': 'africode-v5'
+    },
+    body: JSON.stringify({ nin, pin })
+  });
+  
+  // Step 3: Validate response signature
+  const data = await response.json();
+  const isValid = await verifySignature(data, data.signature, nidaPublicKey);
+  
+  if (!isValid) throw new Error('Invalid signature from NIDA');
+  return data;
+}
+```
+
+### TIPS Payment Flow
+```javascript
+// core/server/tips-flow.js
+export async function initiateP2PPayment(sender, receiver, amount) {
+  // Validate both parties exist in NIDA
+  await verifyNIDA(sender.nin);
+  await verifyNIDA(receiver.nin);
+  
+  // Create TIPS transaction
+  const tipsPayload = {
+    transactionType: 'P2P',
+    senderNIN: sender.nin,
+    receiverNIN: receiver.nin,
+    amount: amount,
+    currency: 'TZS',
+    reference: generateReference(),
+    timestamp: new Date().toISOString()
+  };
+  
+  // Sign and send to TIPS
+  const tipsResponse = await callTIPS('/p2p/initiate', tipsPayload);
+  
+  // Log for AML/FIU reporting
+  await logAMLTransaction(tipsResponse.transactionId, tipsPayload);
+  
+  return tipsResponse;
+}
+```
+
+### AML Screening
+```javascript
+// core/server/aml-check.js
+export async function screenTransaction(amount, nin) {
+  // Query FIU's AML database
+  const suspicious = await queryFIUList(nin);
+  if (suspicious) return { ok: false, reason: 'SUSPICIOUS_PARTY' };
+  
+  // Check transaction limits
+  const dailyTotal = await getDailyTransactionTotal(nin);
+  if (dailyTotal + amount > 50_000_000) { // 50M TZS daily limit
+    return { ok: false, reason: 'AMOUNT_EXCEEDS_LIMIT' };
+  }
+  
+  // Queue for AML reporting (24-hour window)
+  await queueAMLReport({
+    transactionId: generateId(),
+    amount,
+    nin,
+    timestamp: new Date()
+  });
+  
+  return { ok: true };
+}
+```
+
+---
+
+## 📦 Component Manifest (COMPONENT_SCHEMA.json)
+
+**Purpose**: Auto-generated JSON schema that whitelists safe components for AI generation. Prevents hallucinated HTML and enforces A2UI compliance.
+
+**Generated by**: `scripts/generate-component-schema.js`
+
+```json
+{
+  "version": "5.0.0",
+  "timestamp": "2026-05-02T00:00:00Z",
+  "components": [
+    {
+      "tagName": "af-button",
+      "filePath": "components/button.js",
+      "slots": ["default"],
+      "attributes": {
+        "variant": { "type": "string", "enum": ["primary", "secondary", "ghost"], "default": "primary" },
+        "size": { "type": "string", "enum": ["sm", "md", "lg"], "default": "md" },
+        "disabled": { "type": "boolean", "default": false }
+      },
+      "events": [
+        { "name": "click", "detail": { "type": "object" } }
+      ],
+      "cssCustomProperties": [
+        "--af-button-bg",
+        "--af-button-text",
+        "--af-button-border"
+      ],
+      "example": "<af-button variant=\"primary\" size=\"lg\">Click Me</af-button>",
+      "securityNotes": "Sanitizes slot content"
+    },
+    {
+      "tagName": "af-nida-verify",
+      "filePath": "components/nida-verify.js",
+      "slots": [],
+      "attributes": {
+        "nin": { "type": "string", "required": true, "pattern": "^[0-9]{20}$" },
+        "pin": { "type": "string", "required": true }
+      },
+      "events": [
+        { "name": "verified", "detail": { "verified": true, "user": {} } }
+      ],
+      "complianceNotes": "NIDA CIG v2.1 compliant, Ed25519 signed requests"
+    },
+    {
+      "tagName": "af-payment-form",
+      "filePath": "components/payment-form.js",
+      "slots": ["identity", "summary"],
+      "attributes": {
+        "merchant-id": { "type": "string", "required": true },
+        "amount": { "type": "number", "required": true }
+      },
+      "events": [
+        { "name": "success", "detail": { "transactionId": "", "status": "" } },
+        { "name": "error", "detail": { "error": "", "code": "" } }
+      ],
+      "complianceNotes": "Auto-screens AML, enforces TIPS standards"
+    }
+  ],
+  "forbiddenPatterns": [
+    "eval()",
+    "innerHTML = userInput",
+    "fetch without CORS headers",
+    "localStorage for sensitive data"
+  ]
+}
+```
+
+---
+
+## ⚡ Bun-Native Optimization Rules
+
+### 🎯 Inversion of Control
+```javascript
+// ❌ OLD: Library pattern (user calls your code)
+import { PaymentForm } from 'africode/components';
+const form = new PaymentForm();
+
+// ✅ NEW: Framework pattern (framework owns lifecycle)
+// Just add file: pages/checkout.html
+// Bun.serve + FileSystemRouter auto-discovers and serves it
+```
+
+### 🎯 Asset Optimization (Bun Plugins)
+```javascript
+// bunfig.toml - Bun configuration
+[build]
+plugins = ["./build-plugins/svg-optimizer.js"]
+
+// build-plugins/svg-optimizer.js
+export default {
+  name: 'svg-optimizer',
+  setup(build) {
+    build.onLoad({ filter: /\.svg$/ }, async (args) => {
+      const svg = await Bun.file(args.path).text();
+      const minified = minifySVG(svg);
+      return { 
+        contents: `export default "${minified}"`,
+        loader: 'js'
+      };
+    });
+  }
+};
+```
+
+### 🎯 5ms Startup Target
+- No lazy imports in critical paths
+- Bun.SQLite ready before route handling
+- All validators pre-compiled at startup
+- Compliance certificates pre-loaded in memory
+
+---
+
+## 🧪 Test Pyramid (70/20/10)
+
+### Unit Tests (70%) — core/*/
+```bash
+bun test tests/unit/*.test.js
+# Focus: individual functions, validators, pattern generators
+# Example: patterns.test.js — verify Kente weave algorithm
+```
+
+### Integration Tests (20%) — pages/api/*/
+```bash
+bun test tests/integration/*.test.js
+# Focus: A2UI rendering, router matching, compliance middleware
+# Example: nida-flow.test.js — full verification ceremony
+```
+
+### E2E Tests (10%) — critical user journeys
+```bash
+bun test tests/e2e/*.test.js
+# Focus: signup-nida, lipa-namba payment, merchant-checkout
+# Example: lipa-namba.test.js — real TIPS transaction simulation
+```
+
+---
+
+## 🔥 Hot-Reload Middleware
+
+```javascript
+// core/hmr.js (CORRECT)
+export function createHMRServer() {
+  return new WebSocket('ws://localhost:3001/hmr');
+}
+
+// In Bun.serve, call with --hot flag:
+// bun run bin/africode.js dev --hot
+// This enables:
+// - File watching via Bun.watch()
+// - Soft reloads (no session loss)
+// - Database connection persistence
+// - In-memory state retained
+```
+
+---
+
+## 📋 AI Agent Constraints
+
+When building apps with this spec, AI agents MUST:
+
+1. **Only use pre-approved components** from COMPONENT_SCHEMA.json
+2. **Never generate raw HTML** — use af-* Web Components
+3. **Prefer AfriCode-native patterns first**; use external libraries only when they provide a clear, justified enhancement and are already supported by the project
+4. **Always validate inputs** with schemas in core/validation.js
+5. **Always call compliance middleware** before processing payments
+6. **Always sign NIDA requests** with Ed25519 keys
+7. **Always log transactions** for AML/FIU reporting
+8. **Always use Bun-native APIs** (no Node.js polyfills)
+
+---
+
+## 🚀 Quick Verification
+
+To verify an AI-generated app is "native" to AfriCode:
+
+```bash
+# Check component usage
+grep -r "<af-" pages/ components/ | wc -l  # Should be > 0
+
+# Check for forbidden patterns
+grep -r "eval(" pages/ components/  # Should be empty
+grep -r "innerHTML =" pages/ components/  # Should only be in Shadow DOM
+
+# Check Bun-native compliance
+grep -r "fetch(" pages/ | grep -v "CORS"  # Should all have headers
+
+# Run test pyramid
+bun test tests/unit/   # 70% should pass instantly
+bun test tests/integration/  # 20% should pass in < 5s
+bun test tests/e2e/    # 10% critical journeys
+```
+
+---
+
+## 📚 Resources
+
+- **Framework API**: https://github.com/africode/framework
+- **Bun Docs**: https://bun.sh/docs
+- **Web Components**: https://developer.mozilla.org/en-US/docs/Web/Web_Components
+- **NIDA CIG v2.1**: https://nida.go.tz/cig/docs
+- **TIPS Standards**: https://tips.go.tz/standards
+- **AML/FIU**: https://fiu.go.tz/reporting
+
+---
+
+**Last Reviewed**: May 2, 2026  
+**Next Review**: August 2, 2026 (quarterly)  
+**Contact**: framework@africode.dev