@mantajs/core 0.2.0-beta.1 → 0.2.0-beta.11

package/docs/16-reference.md

@@ -58,7 +58,7 @@ function defineLink(
 ): ResolvedLink
 ```
 
-### defineContext(config)
+### defineContext(config) — legacy
 
 ```typescript
 function defineContext(config: {
@@ -71,12 +71,32 @@ function defineContext(config: {
 }): ContextDefinition
 ```
 
+`defineContext()` is kept for legacy compatibility. New Manta apps should use filesystem contexts: `src/commands/{context}/` and `src/queries/{context}/` map to `/api/{context}/...`.
+
 ### defineConfig(config?)
 
 ```typescript
 function defineConfig(config?: Partial<MantaConfig>): MantaConfig
 ```
 
+Common SPA config shape:
+
+```typescript
+type SpaConfig = {
+  dashboard?: string | null // default: '@mantajs/dashboard'; null disables the shell
+  preset?: string | null    // default: '@mantajs/ui'; null disables the preset
+  mountPath?: string | null // default: /{spaName}; use '/' for root-mounted SPA
+}
+```
+
+```typescript
+export default defineConfig({
+  spa: {
+    admin: { mountPath: '/' },
+  },
+})
+```
+
 ## Helpers
 
 ### field property types
@@ -102,7 +122,7 @@ Modifiers: `.nullable()`, `.unique()`, `.indexed()`, `.searchable()`, `.default(
 function many(entity: DmlEntity): Many<DmlEntity>
 ```
 
-Cardinality modifier for `defineLink()`. See [Links](./07-links.md).
+Cardinality modifier for `defineLink()`. See [Links](./08-links.md).
 
 ### Globals
 
@@ -111,7 +131,8 @@ All `define*` functions and helpers are globals — zero imports needed:
 | Global | Purpose |
 |--------|---------|
 | `defineModel`, `defineService`, `defineLink`, `defineCommand` | Core primitives |
-| `defineAgent`, `defineSubscriber`, `defineJob`, `defineContext` | Extended primitives |
+| `defineAgent`, `defineSubscriber`, `defineJob` | Extended primitives |
+| `defineContext` | Legacy context primitive; prefer filesystem contexts |
 | `defineConfig` | Configuration |
 | `field` | Property type factory |
 | `many` | Cardinality modifier |
@@ -137,6 +158,14 @@ function makeIdempotent<T>(
 ): (event: Message<T>) => Promise<void>
 ```
 
+### ICachePort production adapters
+
+| Adapter | Package path | Notes |
+| --- | --- | --- |
+| Upstash Redis | `@mantajs/adapter-cache-upstash` | Default production cache for Vercel/Cloudflare presets |
+| Postgres | `@mantajs/adapter-database-pg/cache` | Durable DB-backed fallback for auth revocation/session state |
+| In-memory | `InMemoryCacheAdapter` | Dev/test only; not durable across instances |
+
 ## step API
 
 Used inside `defineCommand({ workflow: (input, { step }) => {...} })`:

package/docs/17-dashboard.md

@@ -51,6 +51,8 @@ src/spa/admin/
 
 **`.ts` not `.tsx`** — pages export `definePage()` or `defineForm()` specs (pure data), not JSX. Only files in `blocks/` and `components/` are `.tsx`.
 
+**Mount path is project config, not page config.** A SPA named `admin` defaults to `/admin`. For a dedicated admin subdomain, set `spa.admin.mountPath = "/"` in `manta.config.ts`; page routes and navigation items remain SPA-local (`/products`, `/dashboard`, etc.).
+
 ---
 
 ## defineSpa()
@@ -141,7 +143,7 @@ export default definePage({
         { key: 'created_at', label: 'Created', format: 'date' },
       ],
       searchable: ['title'],
-      navigateTo: '/admin/products/:id',
+      navigateTo: '/products/:id',
     },
   ],
 })
@@ -564,7 +566,7 @@ header: {
   actions: [
     'create',
     { label: 'Export', command: 'export-products' },
-    { label: 'Import', to: '/admin/products/import' },
+    { label: 'Import', to: '/products/import' },
   ],
 }
 ```

package/docs/AGENT.md

@@ -350,7 +350,7 @@ Tables: `admin_user`, `admin_invite`
 
 Auth routes (on `/api/admin/`):
 - `POST /login` (public) — returns JWT with `{ id, type: 'admin' }`
-- `DELETE /logout` (public) — blacklists token
+- `DELETE /logout` (public) — clears auth cookies and attempts server-side token revocation
 - `POST /refresh` (public) — refresh token
 - `POST /forgot-password` (public) — reset flow
 - `POST /reset-password` (public) — confirm reset
@@ -362,7 +362,9 @@ Protected routes (JWT required, `type === 'admin'`):
 - `POST /create-user`, `POST /update-user`, `POST /delete-user`
 - `POST /create-invite`, `POST /refresh-invite`
 
-Middleware: all `/api/admin/*` routes verify JWT + `type === 'admin'`
+Middleware: all `/api/admin/*` routes verify JWT, reject cache-blacklisted identities when cache is reachable, then require `type === 'admin'`
+
+Production auth requires a durable `ICachePort` for logout/reset/session revocation. Default production presets use `@mantajs/adapter-cache-upstash`; use `@mantajs/adapter-database-pg/cache` when Postgres should be the durable cache backend.
 
 Override: create `src/commands/admin/login.ts` to replace auto-generated login.
 Override: create `src/middleware/admin.ts` to replace auto-generated middleware.
@@ -396,7 +398,13 @@ src/spa/admin/
         └── page.tsx          # → /admin/products
 ```
 
-Defaults: `@mantajs/dashboard` (shell) + `@mantajs/ui` (preset). Override in config:
+Defaults: `@mantajs/dashboard` (shell) + `@mantajs/ui` (preset). The generated Vite entry imports the dashboard CSS through the package export:
+
+```typescript
+import '@mantajs/dashboard/index.css'
+```
+
+Override in config:
 
 ```typescript
 // manta.config.ts
@@ -408,6 +416,42 @@ export default defineConfig({
 })
 ```
 
+Mount paths:
+
+```typescript
+export default defineConfig({
+  spa: {
+    admin: {},                  // default: /admin
+    // admin: { mountPath: '/' } // root mount for admin.example.com
+  },
+})
+```
+
+When `mountPath` is `/`, generated Vercel rewrites exclude `/api/*` so API routes remain server-side.
+
+Dev Vite ports:
+
+```typescript
+export default defineConfig({
+  spa: {
+    admin: {
+      vitePort: 5310, // default starts at 5200
+    },
+  },
+})
+```
+
+Temporary local overrides also work:
+
+```bash
+MANTA_VITE_PORT=5310 manta dev
+MANTA_VITE_PORT_ADMIN=5311 manta dev
+```
+
+`manta build` writes a SPA fallback manifest. With the Node preset, `manta start` mirrors Vercel SPA fallback behavior locally: root/login auth shortcuts redirect under the single SPA mount path, SPA subroutes serve `index.html`, and `/api/*` remains server-side.
+
+`manta build --preset vercel` preserves existing custom `vercel.json` project settings such as `buildCommand`, `installCommand`, `outputDirectory`, `functions`, `headers`, plus custom redirects/rewrites/crons that do not collide with framework-generated SPA or cron entries.
+
 ### SDK — Frontend hooks
 
 ```typescript
@@ -497,5 +541,8 @@ Complete framework documentation is in `node_modules/@mantajs/core/docs/`:
 | [14-adapters](node_modules/@mantajs/core/docs/14-adapters.md) | Custom adapters |
 | [15-hosts](node_modules/@mantajs/core/docs/15-hosts.md) | Custom hosts |
 | [16-reference](node_modules/@mantajs/core/docs/16-reference.md) | API reference |
+| [17-dashboard](node_modules/@mantajs/core/docs/17-dashboard.md) | Dashboard specs, pages, forms, blocks |
+
+Projects generated by `manta init` include `.codex/skills/mantajs/SKILL.md` and `.claude/skills/mantajs/SKILL.md`. `manta dev` refreshes both from `@mantajs/core/skills/mantajs/SKILL.md` so Codex and Claude keep pointing at this same docs directory.
 
-**Read the relevant doc BEFORE writing code.** When in doubt, check [04-commands.md](node_modules/@mantajs/core/docs/04-commands.md) for workflow patterns.
+**Read the relevant doc BEFORE writing code.** When in doubt, check [05-commands.md](node_modules/@mantajs/core/docs/05-commands.md) for workflow patterns.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantajs/core",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.11",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -36,7 +36,8 @@
       "default": "./dist/testing/relational-query-suite.js"
     },
     "./package.json": "./package.json",
-    "./docs/*": "./docs/*"
+    "./docs/*": "./docs/*",
+    "./skills/*": "./skills/*"
   },
   "dependencies": {
     "drizzle-orm": "^0.35.0",
@@ -51,6 +52,7 @@
   },
   "files": [
     "dist",
-    "docs"
+    "docs",
+    "skills"
   ]
 }

package/skills/mantajs/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: mantajs
+description: Use when working inside a Manta/Mantajs project: creating models, services, commands, queries, workflows, dashboards/SPAs, adapters, plugins, hosts, tests, or deployment config. Loads the canonical framework documentation shipped by @mantajs/core.
+---
+
+# Mantajs
+
+Before changing Manta code in an application, read the project root `AGENT.md` if it exists. It contains project-specific conventions plus links to the framework docs.
+
+The canonical framework documentation is shipped with `@mantajs/core`:
+
+```
+node_modules/@mantajs/core/docs/
+```
+
+If this skill was installed or refreshed by the Manta CLI, it should live at:
+
+```
+.codex/skills/mantajs/SKILL.md
+.claude/skills/mantajs/SKILL.md
+```
+
+`manta init` writes the skill for new projects. `manta dev` refreshes it for existing projects so it stays aligned with the installed `@mantajs/core` docs.
+
+## Workflow
+
+1. Identify the primitive or area involved.
+2. Read only the matching doc file from `node_modules/@mantajs/core/docs/`.
+3. Follow the existing project structure and generated `AGENT.md`.
+4. Prefer Manta primitives over hand-written routes or custom framework glue.
+
+## Doc Map
+
+| Need | Read |
+| --- | --- |
+| Mental model, project structure | `00-overview.md` |
+| First project or scaffolded layout | `01-getting-started.md` |
+| Entities and fields | `02-models.md` |
+| Services and repositories | `03-services.md` |
+| Users, auth, sessions | `04-users.md` |
+| Commands, workflows, long-running runs | `05-commands.md` |
+| Queries and external query graph | `06-queries.md` |
+| Events, jobs, workflows | `07-events.md` |
+| Links and relations | `08-links.md` |
+| AI agents and typed LLM steps | `09-agents.md` |
+| SPA generation, dashboard mount path, SDK | `10-spa.md` |
+| `defineConfig`, CLI, presets, release config | `11-config.md` |
+| Constraints and validation rules | `12-constraints.md` |
+| Tests and conformance suites | `13-testing.md` |
+| Adapter authoring | `14-adapters.md` |
+| Host authoring and production bootstrap | `15-hosts.md` |
+| API surface reference | `16-reference.md` |
+| Dashboard specs, pages, forms, blocks | `17-dashboard.md` |
+
+## Current SPA Rules
+
+- Standalone/Nitro SPAs live in `src/spa/{name}/`.
+- The default mount path is `/{name}`; set `spa.{name}.mountPath = "/"` in `manta.config.ts` for a root-mounted SPA on a dedicated subdomain.
+- `@mantajs/dashboard/index.css` is the public dashboard stylesheet export.
+- Root-mounted SPAs must not capture `/api/*`; keep API routes under `/api`.
+
+## Hard Rules
+
+- Do not create ad hoc API routes for business behavior; use `defineCommand()` or `defineQuery()`.
+- Do not bypass generated services for simple entity writes.
+- Keep module entities/services together under `src/modules/{module}/entities/{entity}/`.
+- Read the relevant doc before inventing a new pattern.

package/skills/mantajs/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: Mantajs
+short_description: Work with Mantajs projects using the docs shipped by @mantajs/core.
+default_prompt: Read the Mantajs project AGENT.md, then use the relevant @mantajs/core docs before changing code.