agent-enderun 1.1.4 → 1.1.5

package/templates/backend/error-handling.md

@@ -0,0 +1,74 @@
+# Professional Domain Error Handling Pattern (v0.8.5)
+
+All backend components developed under the Agent Enderun framework must comply with the **Domain Error Handling Protocol**. Direct usage of generic Javascript `Error` objects or HTTP status codes inside domain services is strictly forbidden.
+
+---
+
+## 🏛️ 1. DomainError Base Hierarchy
+
+We implement a strongly-typed, business-aware exception hierarchy. Every error thrown by the domain logic must inherit from the `DomainError` class.
+
+```typescript
+export abstract class DomainError extends Error {
+  public abstract readonly statusCode: number;
+  public abstract readonly errorCode: string;
+  public readonly timestamp: string;
+
+  constructor(message: string, public readonly metadata: Record<string, unknown> = {}) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = this.constructor.name;
+    this.timestamp = new Date().toISOString();
+  }
+}
+```
+
+### Core Exception Catalog
+
+*   **`NotFoundError` (HTTP 404):** Thrown when a resource (e.g., `User`, `Project`) identified by a **Branded Type ID** does not exist.
+*   **`ValidationError` (HTTP 400):** Thrown when data validation (usually Zod schemas) fails before processing business logic.
+*   **`ConflictError` (HTTP 409):** Thrown when database unique constraints or concurrent updates conflict.
+*   **`UnauthorizedError` (HTTP 401 / 403):** Thrown when RLS (Row Level Security) or RBAC policies are violated.
+
+---
+
+## ⚡ 2. Fastify Global Exception Handler
+
+Fastify must be configured with a single central error handler to map `DomainError` to client responses safely, preventing internal stack traces from leaking to the outside world.
+
+```typescript
+import { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+
+export function registerGlobalErrorHandler(server: FastifyInstance) {
+  server.setErrorHandler((error: Error, request: FastifyRequest, reply: FastifyReply) => {
+    if (error instanceof DomainError) {
+      server.log.warn({ err: error }, `Domain error: ${error.message}`);
+      return reply.status(error.statusCode).send({
+        success: false,
+        error: error.errorCode,
+        message: error.message,
+        timestamp: error.timestamp,
+        metadata: error.metadata
+      });
+    }
+
+    // Capture unhandled internal technical crashes
+    server.log.error({ err: error }, `Unhandled server crash: ${error.message}`);
+    return reply.status(500).send({
+      success: false,
+      error: "INTERNAL_SERVER_ERROR",
+      message: "An unexpected error occurred inside the system."
+    });
+  });
+}
+```
+
+---
+
+## 🔒 3. Branded Types & Query Constraints
+
+1.  **Branded Type Enforcement:** You must never accept raw string IDs inside repository query parameters. Always enforce compile-time type safety:
+    ```typescript
+    export type UserId = string & { readonly __brand: unique symbol };
+    ```
+2.  **Kysely Query Failures:** All Kysely queries running inside database transactions must be wrapped inside a `try/catch` block that translates SQL constraints into precise `ConflictError` or `UnauthorizedError` entities instead of throwing raw database query failures.

package/templates/frontend/component-patterns.md

@@ -0,0 +1,91 @@
+# Atomic Component Standards & Panda CSS Guidelines (v0.8.5)
+
+All user interface developments inside the Agent Enderun framework must follow the **Fluid Component Protocol**. We strictly build component hierarchies following **Mobile-First Responsive Design** and type-safe styling using **Panda CSS**.
+
+---
+
+## 🚫 1. Absolute UI Policies
+
+### A. Zero UI Library Policy
+*   **The Law:** The use of external component libraries (e.g. TailwindCSS, Radix UI, Shadcn/ui, Material UI, Chakra UI, Ant Design) is strictly forbidden. 
+*   **The Reason:** This ensures absolute design authenticity, maximum bundle optimization, zero dependency bloat, and fully controlled accessibility (WCAG 2.2 AA).
+*   **Exception:** Low-level headless primitives (like `@radix-ui/react-dialog` for focus trapping or `sonner` for toast dispatchers) may be allowed, subject to direct approval by `@manager`.
+
+### B. Shared Component First Policy
+*   **The Law:** Defining reusable atomic components (Buttons, Inputs, Cards, Badges, Modals) inside page-level files is strictly forbidden.
+*   **The Structure:** All atomic items must be created inside `apps/web/src/components/ui/` as focused, single-purpose, highly modular components.
+
+---
+
+## 🐼 2. Panda CSS Styling Standards
+
+We utilize **Panda CSS** as our build-time type-safe CSS-in-JS engine. Raw inline styles or unmapped class names are completely banned.
+
+### A. Styling Token Best Practices
+Always leverage designated design tokens (colors, spacings, shadows) from the Panda config (`panda.config.ts`):
+
+```tsx
+import { css } from "../../styled-system/css";
+
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: "primary" | "secondary";
+}
+
+export function Button({ variant = "primary", className, children, ...props }: ButtonProps) {
+  return (
+    <button
+      className={css(
+        {
+          display: "inline-flex",
+          alignItems: "center",
+          justifyContent: "center",
+          px: "4",
+          py: "2.5",
+          borderRadius: "md",
+          fontSize: "sm",
+          fontWeight: "medium",
+          transition: "all 0.2s ease-in-out",
+          cursor: "pointer",
+          _disabled: { opacity: 0.5, cursor: "not-allowed" },
+        },
+        variant === "primary"
+          ? {
+              bg: "brand.primary",
+              color: "white",
+              _hover: { bg: "brand.primary.hover" },
+            }
+          : {
+              bg: "transparent",
+              color: "slate.700",
+              border: "1px solid",
+              borderColor: "slate.200",
+              _hover: { bg: "slate.50" },
+            }
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}
+```
+
+### B. Mobile-First Fluid Responsiveness
+Use array-based or object-based responsive syntax inside the `css` block. Never hardcode pixel values:
+
+```typescript
+// Enforce fluid flex layout across screen sizes
+const containerStyle = css({
+  display: "flex",
+  flexDirection: { base: "column", md: "row" }, // Mobile-first (column -> row on desktop)
+  gap: { base: "4", lg: "8" },
+  p: { base: "4", md: "6", xl: "8" }
+});
+```
+
+---
+
+## ♿ 3. Accessibility & QA Gates (WCAG 2.2)
+
+1.  **Aria Standards:** All custom interactive elements (dropdowns, mobile navigation draw-ins, accordion blocks) must support full keyboard navigation (Tab, Enter, Space) and have valid `aria-*` tags.
+2.  **Vitest Verification:** A component must never be merged into master without an accompanying test file (`[component].test.tsx`) that verifies the component renders correctly and responds to user click actions.

package/tsconfig.json

@@ -16,6 +16,7 @@
     "src/**/*.ts",
     "tests/**/*.ts",
     "framework-mcp/src/**/*.ts",
+    "framework-mcp/tests/**/*.ts",
     "vitest.config.ts",
     "eslint.config.js"
   ],

package/docs/getting-started.md

@@ -1,22 +0,0 @@
-# Quickstart Guide for New Agent Enderun Projects
-
-This guide is prepared for developers who want to set up Agent Enderun in a new project from scratch.
-
-> **As of v1.0.0, the primary initialization command is:** `npx agent-enderun init`
-
-### Installation Steps
-- Initialize the framework with `npx agent-enderun init`.
-- Fill in the `docs/tech-stack.md` and `docs/project-docs.md` files.
-- Create the first task with `npx agent-enderun trace:new`.
-- `@manager` manages the project automatically in every session.
-
-**Congratulations!** You can now start developing professional software with Agent Enderun.
-
-### 🛡️ Agent Lifecycle (AL) & Init Compatibility
-After running `init`, your agent army definitions are automatically set up with full **Agent Lifecycle (AL)** support (stateMachine + tags).
-
-- The `agent-enderun check` command now **automatically runs AL validation** using the packaged validator script (resolves correctly whether you installed via npm or run from source).
-- This ensures that no matter which adapter you used (`antigravity`, `grok`, `gemini`, etc. — even remapped folders like `.agent/skills`), the agents are compliant with the lifecycle states (IDLE → BRIEFED → EXECUTING → DONE/BLOCKED etc.).
-- Dedicated command: `agent-enderun validate` (or `agent-enderun validate-army`, `agent-enderun check:al`)
-
-> **Tip:** Always run `agent-enderun check` after init or major changes to verify AL compliance. The `validate` command is the direct way to run just the army checker.