---
title: "Mandu 1.0.0 — Battery Included (DRAFT / DEFERRED)"
status: draft
created: 2026-04-18
bun_version: "1.3.12"
---

# Mandu 1.0.0 (DRAFT — not yet released)

> **Status**: 1.0.0 is **intentionally deferred**. The framework has
> reached the feature surface described below (Phase 0–6 done), but
> committing to SemVer stability is a decision the core team isn't
> ready to make yet. This document stays as a forward-looking reference
> for whenever 1.0.0 does ship. Until then, releases continue under
> 0.x minor/patch conventions.

When 1.0.0 eventually ships, these will align at `1.0.0`:
`@mandujs/core`, `@mandujs/cli`, `@mandujs/mcp`, `@mandujs/ate`,
`@mandujs/skills`. Public APIs will be frozen under SemVer at that point.

## Scope of this release

What "battery included" means in practice for v1.0:

| Concern | Before 1.0 | v1.0 |
|---|---|---|
| DB access | bring your own (`pg`/`mysql2`/`better-sqlite3`) | `@mandujs/core/db` — Bun.sql wrapper, 3 dialects |
| Session storage | cookie-only, 4 KB ceiling | cookie OR SQLite store (>4 KB, server-side invalidation) |
| Auth helpers | nothing | `hashPassword` / `verifyPassword` / `loginUser` / `currentUserId` |
| OAuth | DIY | `middleware/oauth` + GitHub / Google presets |
| Email | DIY | abstract `EmailSender` + Resend / memory / SMTP-stub |
| Email verify / password reset | DIY | `createEmailVerification` / `createPasswordReset` |
| CSRF | DIY | `middleware/csrf` (Bun.CSRF or HMAC fallback) |
| Rate limiting | DIY | `middleware/rate-limit` + sliding window + 2 stores |
| Secure headers | DIY (Helmet) | `middleware/secure` — CSP/HSTS/frame-options/PP |
| 404 pages | generic text | `app/not-found.tsx` + `notFound()` helper |
| Redirects from loaders | meta-refresh hack | `redirect()` helper |
| Crons | `node-cron` / `agenda` | `@mandujs/core/scheduler` (Bun.cron) |
| Object storage | `@aws-sdk/client-s3` | `@mandujs/core/storage/s3` (Bun.s3) |
| ID generation | `uuid` package | `@mandujs/core/id` — v7 native |

**Every runtime primitive is Bun-native — zero external npm deps added to `@mandujs/core` since v0.21.**

## Highlights by system

### Performance & quality gates
- `MANDU_PERF=1` enables `Bun.nanoseconds` instrumentation at 5 critical paths
- `--linker=isolated` default — per-package node_modules, no phantom deps
- CI runs every suite with `--randomize --retry=2`; bundler tests gated into a dedicated sequential step to sidestep a known Bun.build cross-worker issue
- `workspaces.catalog` centralizes shared dependency versions (`fast-glob` today, expanding over v1.x)

### Database (`@mandujs/core/db`)
- `createDb({ url, provider?, max?, options? })` returns a callable tagged-template: `await db\`SELECT * FROM users WHERE id = ${id}\``
- `.one()` — 0/1 row; throws on 2+
- `.transaction(async tx => {...})` — commit/rollback; `tx` has the same callable shape
- `.close()` — idempotent pool shutdown
- Parameter binding is always through Bun.sql's native mechanism — string interpolation is structurally impossible via the public API

### Auth flow end-to-end
The `auth-starter` template demonstrates the complete signup / login / logout / avatar upload / CSRF / session-gc stack in ~1300 LOC. Clone it:

```bash
mandu init my-app --template auth-starter
```

### Production hardening
```ts
import { secure } from "@mandujs/core/middleware/secure";
import { rateLimit, createSqliteStore } from "@mandujs/core/middleware/rate-limit";

// In your manifest:
export const middleware = [
  secure(),                                  // CSP, HSTS, etc. — Helmet-equivalent
  rateLimit({
    limit: 100,
    windowMs: 60_000,
    store: createSqliteStore({ dbPath: ".mandu/rate-limits.db" })
  }),
];
```

## Known limitations (v1 scope fences)

- **No ORM** — v1 ships raw tagged-template SQL. Resource-layer code generation (Phase 4c RFC / `docs/rfcs/0001-db-resource-layer.md`) lands in 1.x.
- **No multi-instance rate limit / session coordination** — single-process default. Redis-backed stores arrive in 1.x.
- **No HMR `import.meta.hot` Vite compatibility** — Phase 7 follow-up.
- **CLI not shipped as `--compile` binary** — Phase 7 follow-up.
- **SMTP email adapter is a stub** — Resend + memory work today; RFC 5321 client lands in 1.x via `Bun.connect`.
- **OAuth providers limited to GitHub + Google presets** — custom providers work via the plugin interface; more presets via contribution.
- **`Bun.build` cross-worker race** — bundler tests gated in CI. Internal wrapper (`safeBuild`) caps concurrency but cross-process races need upstream Bun fix.

## Migration

See `docs/migration/v0-to-v1.md`. Most v0.21+ code runs unchanged; Bun 1.3.12 engines minimum is the one hard upgrade.

## What's next

Phase 7+ roadmap in `docs/bun/phases-4-plus.md`:
- **Phase 7** — HMR (`import.meta.hot`) + CLI `--compile` single-binary distribution
- **Phase 8** (optional) — request tracing + Prometheus metrics
- **Phase 9** (optional) — `Bun.WebView` desktop bundling + `Bun.markdown` CLI UX polish
- **Phase 4c** — resource-layer DB code generation (RFC 0001 ready for implementation)

## Credits

Mandu 1.0 reached this scope through a methodology of bounded parallel-agent delivery with explicit handoff contracts — Bun expert / Mandu framework expert / architecture lead / security engineer / quality engineer / validation engineer work streams, coordinated via the phase design docs at `docs/bun/`.
