@mantajs/core 0.1.7 → 0.2.0-beta.0

package/docs/08-links.md

@@ -0,0 +1,182 @@
+# Links — defineLink()
+
+## Why links exist
+
+Entities need relations. In Manta, relations are always defined with `defineLink()` — never in the model itself. There is no `field.relation()`, `belongsTo()`, `hasMany()`, or `hasOne()` API.
+
+`defineLink()` is the ONE interface for all relations:
+
+- **Intra-module** (`src/modules/{mod}/links/`): 1:1 and 1:N create a FK directly on the child table. M:N creates a pivot table.
+- **Cross-module** (`src/links/`): always creates a pivot table (modules are isolated, no shared FK).
+
+Same API in both cases.
+
+## defineLink()
+
+```typescript
+// src/links/product-inventory.ts — cross-module link
+export default defineLink('product', many('inventory_item'))
+```
+
+**Signature:** `defineLink(left: string, right: string | many(string), extraColumns?)`
+
+- `left` — Left entity name (string, autocompletes from codegen)
+- `right` — Right entity name, optionally wrapped in `many()` for cardinality
+- `extraColumns` — (optional) Additional columns on the pivot table using `field.*`
+
+No imports needed — `defineLink`, `many`, and `field` are globals.
+
+## Cardinality with `many()`
+
+The `many()` modifier controls the relationship type and cascade behavior:
+
+| Pattern | Cardinality | Cascade behavior |
+|---------|-------------|-----------------|
+| `defineLink('a', 'b')` | 1:1 | Symmetric — delete either side deletes the other |
+| `defineLink('a', many('b'))` | 1:N | Delete parent (a) cascades to children (b) |
+| `defineLink(many('a'), many('b'))` | M:N | Delete either side only cleans pivot |
+
+Cascade is **automatic** — no configuration needed.
+
+## Two locations, different storage
+
+### Intra-module links (`src/modules/{mod}/links/`)
+
+For entities within the **same module**. The storage strategy depends on cardinality:
+
+**1:1 — FK on child table:**
+```typescript
+// src/modules/blog/links/post-seo.ts
+// Creates seo.post_id FK (no pivot table)
+export default defineLink('post', 'seo')
+```
+
+**1:N — FK on child table:**
+```typescript
+// src/modules/catalog/links/product-variant.ts
+// Creates variant.product_id FK (no pivot table)
+export default defineLink('product', many('variant'))
+```
+
+**M:N — Pivot table:**
+```typescript
+// src/modules/catalog/links/product-tag.ts
+// Creates product_tag pivot table
+export default defineLink(many('product'), many('tag'))
+```
+
+### Cross-module links (`src/links/`)
+
+For entities in **different modules**. Always creates a pivot table (modules cannot share FK columns):
+
+**1:1 — Pivot table:**
+```typescript
+// src/links/customer-profile.ts
+// Creates customer_profile pivot table
+export default defineLink('customer', 'profile')
+```
+
+**1:N — Pivot table:**
+```typescript
+// src/links/product-inventory.ts
+// Creates product_inventory_item pivot table
+export default defineLink('product', many('inventory_item'))
+```
+
+**M:N — Pivot table:**
+```typescript
+// src/links/product-collection.ts
+// Creates product_collection pivot table
+export default defineLink(many('product'), many('collection'))
+```
+
+## Summary: all 6 cases
+
+| Location | Cardinality | Storage |
+|----------|-------------|---------|
+| Intra-module | 1:1 | FK on child |
+| Intra-module | 1:N | FK on child |
+| Intra-module | M:N | Pivot table |
+| Cross-module | 1:1 | Pivot table |
+| Cross-module | 1:N | Pivot table |
+| Cross-module | M:N | Pivot table |
+
+## Extra columns on pivot table
+
+For M:N relations (or any cross-module link), you can add extra columns using `field.*`:
+
+```typescript
+export default defineLink(many('product'), many('collection'), {
+  position: field.number().default(0),
+})
+```
+
+Extra columns are only supported on pivot tables — not on FK-based links.
+
+### Syntax
+
+The third argument to `defineLink()` is an object of `field.*` definitions, exactly like `defineModel` properties:
+
+```typescript
+// src/links/customer-address.ts
+export default defineLink('customer', many('address'), {
+  type: field.text(),
+  is_default: field.boolean().default(false),
+})
+```
+
+This creates a pivot table `customer_address` with columns: `customer_id`, `address_id`, `type`, `is_default`, plus the standard `id`, `created_at`, `updated_at`, `deleted_at`.
+
+### Behavior
+
+- **Schema generation**: Extra columns are added to the pivot table's Drizzle schema automatically.
+- **Auto-generated link commands**: When `defineLink()` has extra columns, the auto-generated Zod schema for link commands includes the extra fields. `step.link(a, b, { type: 'shipping', is_default: true })` passes extra column values to the INSERT.
+- **Query graph integration**: When using relation field syntax in `query.graph()` (e.g., `fields: ['*', 'addresses.*']`), extra columns from the pivot table are merged into each target entity in the result. For example, each address object will include `type` and `is_default` from the pivot row.
+
+## Usage in workflows
+
+After creating both entities in a command, link them:
+
+```typescript
+workflow: async (input, { step }) => {
+  const product = await step.service.catalog.create({ title: 'Widget' })
+  const inventory = await step.service.inventory.create({ quantity: 100 })
+
+  // Link them — IDs are auto-resolved from the creates above
+  await step.service.catalog.link.inventoryItem()
+}
+```
+
+The framework tracks the last created ID per entity type. `link.inventoryItem()` automatically resolves the Product ID and InventoryItem ID.
+
+## Cascade delete
+
+With `many('inventory_item')`, deleting the parent (product) automatically cascades:
+
+```typescript
+// Deleting a product also soft-deletes linked inventory items
+await step.service.catalog.delete(productId)
+// → Product soft-deleted
+// → All linked InventoryItems soft-deleted
+// → Pivot table entries soft-deleted (cross-module) or FK nulled (intra-module)
+```
+
+The cascade is determined by `many()` placement — no manual configuration needed.
+
+## File locations
+
+```
+src/links/{name}.ts                      # Cross-module links (always pivot)
+src/modules/{mod}/links/{name}.ts        # Intra-module links (FK or pivot)
+```
+
+Each file exports a single `defineLink()` as the default export.
+
+## Validation errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Link requires exactly two entities` | Missing second argument | Use `defineLink('a', 'b')` or `defineLink('a', many('b'))` |
+| `Link between "X" and "Y" is already defined` | Duplicate link | Remove the duplicate file |
+| `No link defined between "X" and "Y"` | Missing link definition | Create a file in `src/links/` with `defineLink()` |
+| `Cannot link: no X created yet` | Link before create | Call `step.service.MODULE.create()` before linking |

package/docs/09-agents.md

@@ -0,0 +1,142 @@
+# Agents — defineAgent()
+
+## What is an agent
+
+An agent is a **typed AI call** that you can use as a step in your workflows. It has a contract: typed input (Zod), typed output (Zod), and instructions. The LLM is forced to return the output schema via `generateObject()`.
+
+In a workflow, the agent result is **checkpointed** — if the workflow crashes after the agent step, the result is recovered from checkpoint (no re-call to the LLM).
+
+## defineAgent()
+
+```typescript
+// src/agents/categorize-product.ts
+export default defineAgent({
+  name: 'categorize-product',
+  description: 'Categorize a product into a department',
+  input: z.object({
+    title: z.string(),
+    description: z.string().optional(),
+  }),
+  output: z.object({
+    category: z.enum(['electronics', 'clothing', 'food', 'home', 'other']),
+    confidence: z.number().min(0).max(1),
+    reasoning: z.string(),
+  }),
+  instructions: (input) =>
+    `Categorize this product: "${input.title}". Description: "${input.description ?? 'none'}".`,
+  system: 'You are a product categorization expert.',
+  temperature: 0,
+})
+```
+
+**Required fields:**
+- `name` — Unique agent identifier (kebab-case)
+- `description` — What this agent does
+- `input` — Zod schema for the input (validated before the LLM call)
+- `output` — Zod schema for the output (the LLM is forced to return this shape)
+- `instructions` — Function that receives `input` directly and returns the prompt string
+
+**Optional:**
+- `system` — System prompt
+- `temperature` — 0 = deterministic (default), 1 = creative
+- `maxTokens` — Max response tokens
+- `model` — Override model (e.g., `'gpt-4o'`, `'claude-sonnet-4-20250514'`)
+
+## Usage in commands
+
+```typescript
+// src/commands/import-product.ts
+export default defineCommand({
+  name: 'import-product',
+  description: 'Import and auto-categorize a product',
+  input: z.object({
+    title: z.string(),
+    description: z.string().optional(),
+    price: z.number(),
+  }),
+  workflow: async (input, { step }) => {
+    // Create the product
+    const product = await step.service.catalog.create({
+      title: input.title,
+      description: input.description,
+      price: input.price,
+      status: 'draft',
+    })
+
+    // AI categorization — typed input/output, checkpointed
+    const { category, confidence } = await step.agent.categorizeProduct({
+      title: input.title,
+      description: input.description,
+    })
+
+    // Use the AI result
+    if (confidence > 0.8) {
+      await step.service.catalog.update(product.id, { category })
+    }
+
+    return { product, category, confidence }
+  },
+})
+```
+
+`step.agent.categorizeProduct()` is:
+- **Typed** — input and output are known by autocomplete (from the Zod schemas)
+- **Checkpointed** — if the workflow crashes after this step, the LLM result is recovered
+- **Validated** — input is Zod-checked before calling the LLM, output is forced by `generateObject()`
+- **No compensation** — LLM calls are read-only, nothing to undo
+
+## AI provider configuration
+
+Set the provider via environment variable:
+
+| Variable | Provider | Default model |
+|----------|----------|--------------|
+| `ANTHROPIC_API_KEY` | Anthropic | claude-sonnet-4-20250514 |
+| `OPENAI_API_KEY` | OpenAI | gpt-4o |
+| `GOOGLE_AI_API_KEY` | Google | gemini-2.0-flash |
+| `MISTRAL_API_KEY` | Mistral | mistral-large-latest |
+
+Set `MANTA_AI_PROVIDER` to choose which provider (default: `anthropic`).
+
+## File location
+
+```
+src/agents/{name}.ts
+```
+
+Each file exports a single `defineAgent()` as the default export. Auto-discovered at boot.
+
+## How it works under the hood
+
+1. `step.agent.categorizeProduct(input)` resolves the agent definition from the registry
+2. Input is validated against the agent's Zod `input` schema
+3. `instructions(input)` generates the prompt string
+4. `generateObject()` from Vercel AI SDK calls the LLM with the `output` Zod schema
+5. The LLM is forced to return valid JSON matching the schema
+6. Result is checkpointed via `runStep()` (same as all other steps)
+7. On workflow retry, the checkpoint is returned directly (no LLM re-call)
+
+## Validation errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Agent name is required` | Missing name | Add `name: 'my-agent'` |
+| `Agent "X" requires an output Zod schema` | Missing output | Add `output: z.object({...})` |
+| `Agent "X" instructions must be a function` | String instead of function | Change to `instructions: (input) => '...'` |
+| `Agent "X" not found` | Typo or missing file | Create `src/agents/X.ts` with `defineAgent()` |
+| `step.agent requires ANTHROPIC_API_KEY` | No API key set | Set the environment variable |
+
+## The primitives (updated)
+
+```
+defineModel        → Entity
+defineService      → Mutations (auto-compensated)
+defineCommand      → Workflow
+defineQuery        → Read endpoint (CQRS read side)
+defineQueryGraph   → Graph endpoint (flexible reads)
+defineSubscriber   → Event reaction
+defineJob          → Cron
+defineLink         → Relation
+defineUser         → Auth + CRUD + middleware (auto-generated)
+defineAgent        → AI
+```

package/docs/10-spa.md

@@ -0,0 +1,327 @@
+# SPA, Dashboard & SDK
+
+## SPA — Auto-detected from filesystem
+
+SPAs are auto-detected from `src/spa/{name}/`. No boilerplate — just pages.
+
+```
+src/spa/admin/
+├── config.ts                   # defineSpa() — navigation, title, branding
+├── pages/
+│   ├── page.tsx                # → /admin/ (React page)
+│   ├── products/
+│   │   └── page.ts             # → /admin/products (definePage spec)
+│   ├── products/[id]/
+│   │   └── page.ts             # → /admin/products/:id (definePage spec)
+│   │   └── edit/
+│   │       └── page.ts         # → /admin/products/:id/edit (defineForm spec)
+│   ├── products/create/
+│   │   └── page.ts             # → /admin/products/create (defineForm spec)
+│   └── settings/
+│       └── page.tsx            # → /admin/settings (React page)
+├── blocks/                     # Custom blocks (auto-discovered)
+│   └── inventory-matrix.tsx
+└── components/                 # Local components (imported by blocks/pages)
+    └── product-card.tsx
+```
+
+**Auto-discovered:**
+- `config.ts` → SPA configuration (navigation, branding, settings)
+- `pages/` → file-based routing
+- `blocks/` → custom blocks
+
+**Two page formats:**
+- **`.ts`** — exports `definePage()` or `defineForm()` spec (declarative, no React)
+- **`.tsx`** — exports a React component (full control, for complex cases)
+
+**Defaults**: `@mantajs/dashboard` shell + `@mantajs/ui` preset. Override in config if needed:
+
+```typescript
+// manta.config.ts — optional, only for overrides
+export default defineConfig({
+  spa: {
+    admin: { preset: '@mantajs/ui-preset-dark' },
+    vendor: { dashboard: null },  // no shell, custom SPA
+  },
+})
+```
+
+---
+
+## SPA Configuration — defineSpa()
+
+Define navigation, branding, and settings in `src/spa/{name}/config.ts`. See [Dashboard](./17-dashboard.md) for the full reference.
+
+```typescript
+// src/spa/admin/config.ts
+import { defineSpa } from '@mantajs/dashboard'
+
+export default defineSpa({
+  title: 'Commerce Admin',
+  logo: '/logo.svg',
+  favicon: '/favicon.ico',
+
+  navigation: [
+    { icon: 'Tag', label: 'Products', to: '/products' },
+    { icon: 'Users', label: 'Customers', to: '/customers', items: [
+      { label: 'Groups', to: '/customer-groups' },
+    ]},
+  ],
+
+  settings: [
+    { icon: 'Store', label: 'Store Details', to: '/settings/store' },
+    { icon: 'Key', label: 'API Keys', to: '/settings/api-keys' },
+  ],
+})
+```
+
+---
+
+## Declarative Pages — definePage() & defineForm()
+
+The preferred approach. Pages are pure data specs — no React, no JSX. See [Dashboard](./17-dashboard.md) for the full reference.
+
+### Listing page
+
+```typescript
+// src/spa/admin/pages/customers/page.ts
+import { definePage } from '@mantajs/dashboard'
+
+export default definePage({
+  header: { title: 'Customers', actions: ['create'] },
+  main: [
+    {
+      type: 'DataTable',
+      query: {
+        graph: {
+          entity: 'customer',
+          fields: ['email', 'first_name', 'last_name', 'created_at'],
+          pagination: { limit: 20 },
+        },
+      },
+      columns: [
+        { key: 'email', label: 'Email' },
+        { key: 'first_name', label: 'First Name' },
+        { key: 'last_name', label: 'Last Name' },
+        { key: 'created_at', label: 'Joined', format: 'date' },
+      ],
+      searchable: true,
+      navigateTo: '/customers/:id',
+    },
+  ],
+})
+```
+
+### Detail page
+
+```typescript
+// src/spa/admin/pages/customers/[id]/page.ts
+import { definePage } from '@mantajs/dashboard'
+
+export default definePage({
+  header: { titleField: 'email', actions: ['edit', 'delete'] },
+  main: [
+    {
+      type: 'InfoCard',
+      title: 'General',
+      query: {
+        graph: {
+          entity: 'customer',
+          fields: ['first_name', 'last_name', 'email', 'phone'],
+        },
+      },
+    },
+  ],
+  sidebar: [
+    {
+      type: 'InfoCard',
+      title: 'Dates',
+      query: {
+        graph: {
+          entity: 'customer',
+          fields: ['created_at', 'updated_at'],
+        },
+      },
+      fields: [
+        { key: 'created_at', label: 'Created', display: 'date' },
+        { key: 'updated_at', label: 'Updated', display: 'date' },
+      ],
+    },
+  ],
+})
+```
+
+### Create form
+
+```typescript
+// src/spa/admin/pages/customers/create/page.ts
+import { defineForm } from '@mantajs/dashboard'
+
+export default defineForm({
+  title: 'Create Customer',
+  command: 'create-customer',
+  fields: [
+    { key: 'email', label: 'Email', type: 'text', required: true },
+    { key: 'first_name', label: 'First Name', type: 'text' },
+    { key: 'last_name', label: 'Last Name', type: 'text' },
+    { key: 'phone', label: 'Phone', type: 'text' },
+  ],
+})
+```
+
+### Edit form
+
+```typescript
+// src/spa/admin/pages/customers/[id]/edit/page.ts
+import { defineForm } from '@mantajs/dashboard'
+
+export default defineForm({
+  title: 'Edit Customer',
+  command: 'update-customer',
+  query: {
+    graph: {
+      entity: 'customer',
+      fields: ['first_name', 'last_name', 'email', 'phone'],
+    },
+  },
+  fields: [
+    { key: 'first_name', label: 'First Name', type: 'text' },
+    { key: 'last_name', label: 'Last Name', type: 'text' },
+    { key: 'email', label: 'Email', type: 'text', required: true },
+    { key: 'phone', label: 'Phone', type: 'text' },
+  ],
+})
+```
+
+---
+
+## React Pages — Full Control
+
+For complex pages that need full React control (custom interactions, animations, etc.), use `.tsx` files:
+
+```tsx
+// src/spa/admin/pages/dashboard/page.tsx
+import { useGraphQuery, useCommand } from '@mantajs/sdk'
+import { Button, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, Badge } from '@mantajs/ui'
+import { useNavigate } from 'react-router-dom'
+
+export default function DashboardPage() {
+  const { data: orders } = useGraphQuery({ entity: 'order', pagination: { limit: 5 } })
+  // ... full React control
+}
+```
+
+---
+
+## Custom Blocks
+
+Blocks are standard React components in `src/spa/{name}/blocks/`. Auto-discovered, available in `definePage()` specs.
+
+```tsx
+// src/spa/admin/blocks/inventory-matrix.tsx
+import { useGraphQuery } from '@mantajs/sdk'
+
+interface InventoryMatrixProps {
+  query: Parameters<typeof useGraphQuery>[0]
+  warehouses?: string[]
+}
+
+export default function InventoryMatrix({ query, warehouses = ['default'] }: InventoryMatrixProps) {
+  const { data } = useGraphQuery(query)
+  // ... render matrix
+}
+```
+
+Usage in a page spec:
+
+```typescript
+main: [
+  { type: 'InventoryMatrix', query: { graph: { entity: 'product', relations: ['variant'] } }, warehouses: ['paris'] },
+]
+```
+
+**Override framework blocks**: Create a block with the same kebab-case filename as a framework block (e.g., `blocks/info-card.tsx` overrides the built-in `InfoCard`).
+
+---
+
+## Component Reference
+
+### @mantajs/dashboard — blocks (used in definePage specs)
+
+| Block | Purpose |
+|-------|---------|
+| `DataTable` | List with columns, search, sort, filter, pagination |
+| `InfoCard` | Key-value card with fields |
+| `RelationTable` | Related entities table |
+| `MediaCard` | Image/file gallery |
+| `StatsCard` | Metric cards |
+| `PageHeader` | Title, status badge, actions (used via `header` shortcut) |
+
+### @mantajs/dashboard — patterns (used in React pages)
+
+| Component | Purpose |
+|-----------|---------|
+| `FocusModal` | Full-width modal with header/footer for forms |
+| `EntitySelect` | Searchable selection table in a modal |
+| `MultiStepForm` | Multi-step wizard with stepper |
+| `EditableTable` | Inline editable table (Excel-like) |
+| `BulkActionBar` | Floating action bar for multi-select |
+| `ConfirmDialog` | Confirmation dialog for destructive actions |
+
+### @mantajs/ui (shadcn/ui — 26 components)
+
+| Category | Components |
+|----------|-----------|
+| **Form** | Input, Label, Select, Textarea, Checkbox, Switch, RadioGroup |
+| **Layout** | Card, Separator, Tabs, ScrollArea |
+| **Feedback** | Alert, Badge, Skeleton, Progress, Toaster/toast |
+| **Overlay** | Dialog, Sheet, AlertDialog, Popover, Tooltip, DropdownMenu |
+| **Data** | Table, Pagination |
+| **Navigation** | Button, Command (Cmd+K) |
+| **Display** | Avatar |
+
+### @mantajs/sdk (hooks — 4 hooks + client)
+
+| Hook | Purpose |
+|------|---------|
+| `useCommand('name')` | Execute a command (mutation) — autocomplete |
+| `useQuery('name', params)` | Execute a named query — autocomplete |
+| `useGraphQuery({ entity })` | Graph query (flexible reads) — autocomplete |
+| `useAuth()` | Login, logout, me, isAuthenticated |
+
+---
+
+## AI Agent — Setup & Configuration
+
+The dashboard includes a built-in AI conversational agent that can create pages, modify components, and query data through the query graph.
+
+### Setup
+
+1. Set environment variables:
+
+```bash
+# .env
+MANTA_AI_PROVIDER=anthropic          # or 'openai'
+ANTHROPIC_API_KEY=sk-ant-...         # your API key
+# MANTA_AI_MODEL=claude-sonnet-4-20250514   # optional model override
+```
+
+2. The AI panel appears automatically in the dashboard shell (bottom-right sparkle icon). It's enabled when `ANTHROPIC_API_KEY` (or `OPENAI_API_KEY` for OpenAI) is set.
+
+### What the AI can do
+
+| Capability | How |
+|-----------|-----|
+| **Create pages** | AI generates `definePage()` / `defineForm()` specs |
+| **Modify blocks** | AI updates block props (columns, filters, etc.) |
+| **Query data** | AI uses the query graph to browse entities |
+| **Navigate** | AI adds/removes navigation items in the sidebar |
+
+### Providers
+
+| Provider | Env var | Default model |
+|----------|---------|--------------|
+| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
+| OpenAI | `OPENAI_API_KEY` | `gpt-4o` |
+
+Set `MANTA_AI_PROVIDER` to switch providers. Default: `anthropic`.