@hachej/boring-core 0.1.40 → 0.1.42

package/README.md

@@ -7,314 +7,63 @@
 
 </div>
 
-The foundation package for boring-ui apps: Postgres/Drizzle database schema, email/password auth (better-auth), config loader, Fastify HTTP app factory, and React frontend shell. Every child app imports core first.
+The foundation package for boring-ui v2 apps: Postgres/Drizzle database, better-auth
+(email/password, verification, password reset, magic links, optional Google), TOML+env
+config loader, Fastify HTTP app factory, and a React frontend shell with auth/workspace
+gating. Every child app imports core first; domain logic, agent runtime, and workspace UI
+come from the sibling `@hachej/boring-*` packages.
 
 ```bash
 pnpm add @hachej/boring-core
 ```
 
----
-
-## TL;DR
-
-**The Problem**: Building a multi-user agent-powered app means re-implementing auth, sessions, workspaces, invites, email flows, and an app shell every single time. These are the same across every deployment.
-
-**The Solution**: `@hachej/boring-core` provides a complete app skeleton — Postgres DB, better-auth with email verification + password reset + magic links, workspace membership with roles, email transport (Resend/SMTP/console), and a `<BoringApp>` React shell with auth pages. You bring the domain logic.
-
-### Why Use @hachej/boring-core?
-
-| Feature | What It Does |
-|---------|--------------|
-| **Full auth suite** | Email/password + email verification + password reset + magic links (better-auth) |
-| **Workspace management** | Create, update, delete workspaces; member roles (owner/editor/viewer); invites |
-| **Fastify app factory** | Pre-wired with helmet, CORS, rate limiting, secret redaction, graceful shutdown |
-| **Drizzle + Postgres** | Ready-to-run schema for users, workspaces, members, invites, settings |
-| **Email transport** | Resend (default), SMTP, or console — pluggable via URL scheme |
-| **<BoringApp> shell** | Client-rendered React shell with auth gate, theme toggle, workspace switcher |
-| **Config loader** | TOML + env vars merged, Zod-validated, redacted for frontend |
+## Usage essentials
 
----
-
-## Quick Example
+Most apps use the composed `app/*` surfaces, which fuse core + workspace + agent:
 
 ```ts
-// Server — 4 lines to a full app
-import { createCoreApp, loadConfig } from "@hachej/boring-core/server"
-
-const config = await loadConfig()
-const app = await createCoreApp(config)  // Fastify + DB + auth + routes
+// server entry
+import { createCoreWorkspaceAgentServer } from "@hachej/boring-core/app/server"
 
+const app = await createCoreWorkspaceAgentServer({ plugins })
 await app.listen({ port: 3000 })
 ```
 
 ```tsx
-// Frontend — mount auth gate + workspace routing
-<BoringApp>
-  <Route path="/workspace/:id" element={<WorkspaceRoute />} />
-  <Route path="/settings" element={<Settings />} />
-</BoringApp>
-```
-
-```tsx
-// In your components — typed auth + workspace access
-const user = useUser()
-const workspace = useCurrentWorkspace()
-const role = useWorkspaceRole()  // 'owner' | 'editor' | 'viewer'
-```
-
----
-
-## Design Philosophy
-
-1. **Core owns persistence and identity** — DB tables, auth, sessions, workspaces, invites. Everything else injects stores via interfaces.
-2. **One config source** — `boring.app.toml` + environment variables merged, Zod-validated at boot. No scattered config.
-3. **Email flows are real, not stubs** — password reset, email verification, magic links, workspace invites — all shipped with React Email templates.
-4. **Swap seams, not rewrites** — `AuthProvider`, `UserStore`, `WorkspaceStore` are interfaces. The default impl is Postgres; swap via `createCoreApp({ authProvider })`.
-5. **Fail closed on auth** — config fetch failure throws a `ConfigFetchError` with retries. Users see "Cannot reach server" not a blank page.
-
----
-
-## Installation
-
-```bash
-# pnpm
-pnpm add @hachej/boring-core @hachej/boring-workspace
-
-# npm
-npm install @hachej/boring-core @hachej/boring-workspace
-
-# from source
-git clone https://github.com/hachej/boring-ui.git
-cd boring-ui && pnpm install
-pnpm --filter @hachej/boring-core build
-```
-
-### Dependencies
-
-Postgres is required for production. For dev, set `CORE_STORES=local` and core runs in-memory (state resets on restart).
-
----
-
-## Quick Start
-
-### 1. Set Environment
-
-```bash
-# .env
-DATABASE_URL=postgres://user:pass@localhost:5432/myapp
-BETTER_AUTH_SECRET=<32-byte random hex>
-BETTER_AUTH_URL=http://localhost:3000
-WORKSPACE_SETTINGS_ENCRYPTION_KEY=<32-byte hex>
-MAIL_FROM=noreply@myapp.dev
-MAIL_TRANSPORT_URL=resend://re_xxxxxxxxxxxxxxxx
-```
-
-### 2. Create Config File
-
-```toml
-# boring.app.toml
-[app]
-id = "my-app"
-
-[frontend.branding]
-name = "My App"
-logo = "/logo.svg"
-
-[features]
-invites_enabled = true
-invite_ttl_days = 7
-```
-
-### 3. Run Migrations
-
-```bash
-pnpm drizzle-kit generate --config node_modules/@hachej/boring-core/drizzle.config.ts
-pnpm drizzle-kit migrate --config node_modules/@hachej/boring-core/drizzle.config.ts
-```
-
-### 4. Server Entry
-
-```ts
-import { createCoreApp, loadConfig } from "@hachej/boring-core/server"
-
-const config = await loadConfig()
-const app = await createCoreApp(config)
-
-// add child-app routes
-app.get("/api/v1/my-thing", async () => ({ ok: true }))
-
-await app.listen({ port: config.port })
-```
-
-### 5. Frontend Entry
-
-```tsx
+// frontend entry
 import { createRoot } from "react-dom/client"
-import { BoringApp } from "@hachej/boring-core/front"
-import { Route } from "react-router-dom"
-import "@hachej/boring-core/theme.css"
+import { CoreWorkspaceAgentFront } from "@hachej/boring-core/app/front"
+import "@hachej/boring-core/app/front/styles.css"
 
 createRoot(document.getElementById("root")!).render(
-  <BoringApp>
-    <Route path="/" element={<Dashboard />} />
-  </BoringApp>,
+  <CoreWorkspaceAgentFront apiBaseUrl="" chatEntryMode="chat-first" plugins={plugins} />,
 )
 ```
 
----
-
-## Package Surfaces
+For a core-only app (no agent/workspace), use `createCoreApp(config)` from
+`@hachej/boring-core/server` and `CoreFront` from `@hachej/boring-core/front`.
 
-| Import | Environment | What You Get |
-|--------|-------------|--------------|
-| `@hachej/boring-core/server` | Node | `createCoreApp`, `loadConfig`, auth, stores, routes |
-| `@hachej/boring-core/server/db` | Node | Drizzle schema, migrations, store interfaces |
-| `@hachej/boring-core/front` | Browser | `<BoringApp>`, hooks, auth pages, components |
-| `@hachej/boring-core/shared` | Any | `User`, `Workspace`, `HttpError`, `ErrorCode` types |
-| `@hachej/boring-core/theme.css` | Browser | CSS theme tokens for the frontend shell |
-| `@hachej/boring-core/app/front` | Browser | App composition helpers (`WorkspaceAgentFront`, etc.) |
-| `@hachej/boring-core/app/server` | Node | App composition helpers (`createWorkspaceAgentApp`) |
+### Required environment (production)
 
----
+`DATABASE_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`,
+`WORKSPACE_SETTINGS_ENCRYPTION_KEY`, `MAIL_FROM`, `MAIL_TRANSPORT_URL`
+(`resend://…`, `smtp://…`, or `console://`), `CORS_ORIGINS`. Config is also read from
+`boring.app.toml`. For dev without Postgres, set `CORE_STORES=local` (in-memory, resets
+on restart; not supported by `createCoreWorkspaceAgentServer`).
 
-## Configuration
+Migrations live in `drizzle/`; run them with `drizzle-kit migrate` against
+`drizzle.config.ts`.
 
-### Environment Variables
+## Documentation
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `DATABASE_URL` | Yes (prod) | Postgres connection string |
-| `BETTER_AUTH_SECRET` | Yes | 32-byte hex — signs session cookies |
-| `BETTER_AUTH_URL` | Yes | Public URL for OAuth callbacks |
-| `WORKSPACE_SETTINGS_ENCRYPTION_KEY` | Yes (prod) | 32-byte hex — encrypts workspace settings |
-| `MAIL_FROM` | Yes (prod) | Sender address for auth emails |
-| `MAIL_TRANSPORT_URL` | Yes (prod) | `resend://key`, `smtp://host`, or `console://` |
-| `CORE_STORES` | No | `postgres` (default) or `local` (in-memory dev) |
-| `CORS_ORIGINS` | Yes (prod) | Comma-separated allowlist |
-| `SEND_WELCOME_EMAIL` | No | Default `true` — suppress with `false` |
-| `SESSION_TTL_SECONDS` | No | Default 2,592,000 (30 days) |
-
----
-
-## Architecture
-
-```
-┌──────────────────────┐
-│   Browser Client     │
-│  /auth/* + /me +     │
-│  /workspaces/*       │
-└──────────┬───────────┘
-           │ HTTP (typed, cookie auth)
-┌──────────▼───────────┐
-│   Fastify App        │
-│  ├── authHook (req.user)
-│  ├── helmet + CORS   │
-│  ├── rate limits     │
-│  ├── secret redaction│
-│  └── graceful shutdown
-└──────────┬───────────┘
-           │
-┌──────────▼───────────┐
-│  better-auth          │
-│  (sessions, email,    │
-│   password reset)     │
-└──────────┬───────────┘
-           │
-┌──────────▼───────────┐
-│   Drizzle + Postgres │
-│  users, sessions,     │
-│  workspaces, members, │
-│  invites, settings    │
-└──────────────────────┘
-```
-
-### Error Handling Contract
-
-All errors flow through a single `setErrorHandler`:
-
-| Condition | Status | Code |
-|-----------|--------|------|
-| No/expired session | 401 | `unauthorized` |
-| Insufficient role | 403 | `forbidden` / `not_member` |
-| Zod validation fail | 400 | `validation_failed` |
-| Rate limited | 429 | `rate_limited` + `Retry-After` |
-| DB ping fails | 503 | `db_unavailable` |
-| Everything else | 500 | `internal_error` |
-
-Every response includes `{ error, code, message, requestId }`. Client-side `apiFetch` parses this into `HttpError` instances.
-
----
-
-## How @hachej/boring-core Compares
-
-| Feature | @hachej/boring-core | Supabase + custom | Firebase | Roll your own |
-|---------|---------------------|-------------------|----------|---------------|
-| Auth flows | ✅ email + reset + magic link | ✅ OAuth only | ✅ OAuth/phone | Weeks to build |
-| Workspaces + invites | ✅ owner/editor/viewer roles | ❌ Custom tables | ❌ Custom rules | ~1 week |
-| Email templates | ✅ 5 React Email templates | ❌ You write them | ❌ SendGrid setup | ~3 days |
-| App shell | ✅ `<BoringApp>` + hooks | ❌ DIY | ❌ DIY | ~1 week |
-| Rate limiting | ✅ pre-wired routes | ❌ Edge functions | ⚠️ Cloud rules | ~2 days |
-| Config validation | ✅ TOML + env + Zod | ❌ dotenv only | ⚠️ Remote config | Custom |
-
-**When to use @hachej/boring-core:**
-- Building a multi-user app around an AI agent
-- You need auth + workspaces + invites in days, not weeks
-- You're deploying to Fly.io, Render, Railway, or any Postgres-capable host
-
-**When it might not fit:**
-- You need server-side rendering (client-rendered only)
-- You want SQLite (Postgres-only with Drizzle)
-- You need Google/Apple/Discord OAuth (planned for v1.x)
-- You need billing/Stripe integration (future `@boring/cloud` package)
-
----
-
-## Troubleshooting
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `ConfigValidationError` at boot | Missing required env var | Check `.env` has all required vars |
-| `config_fetch_failed` in browser | API server not reachable | Verify `BETTER_AUTH_URL` matches |
-| `mail_disabled` warning at boot | `MAIL_FROM` not set | Set `MAIL_TRANSPORT_URL=console://` for dev |
-| `unauthorized` on `/api/v1/me` | No session cookie | Check `BETTER_AUTH_URL` and `CORS_ORIGINS` |
-| `db_unavailable` on `/health` | Postgres can't connect | Verify `DATABASE_URL` and network access |
-
----
-
-## Limitations
-
-- **Postgres only** — No SQLite/libsql support in v1.
-- **Client-rendered only** — `<BoringApp>` mounts client-side. No SSR.
-- **GitHub OAuth deferred** — Planned for v1.x, bundled with agent's GitHub App install.
-- **No billing** — Stripe integration planned for `@boring/cloud` package.
-- **In-memory stores are dev-only** — `CORE_STORES=local` resets on restart. Not for production.
-- **Partial swap seams** — `AuthProvider` is swappable, but the React auth surfaces (`useSession`, sign-in pages) are better-auth-shaped.
-
----
-
-## FAQ
-
-**Q: Can I use this without Postgres?**  
-A: In dev, yes — set `CORE_STORES=local`. State is in-memory and resets on restart. For production, Postgres is required.
-
-**Q: How do I add Google/Discord OAuth?**  
-A: better-auth supports these out of the box. Add the provider config to `createAuth()` in the core source. Official v1.x support planned.
-
-**Q: Can I swap better-auth for Clerk/Neon?**  
-A: The `AuthProvider` interface is designed as a swap seam. You'll need to re-implement the React auth surfaces (`SignInPage`, `useSession`, etc.) and preserve the `users.id` continuity invariant.
-
-**Q: How do email templates work?**  
-A: Five React Email components (`VerifyEmail`, `ResetPassword`, `MagicLink`, `WorkspaceInvite`, `Welcome`) rendered via `@react-email/render`. CSS is inlined. Swap them by providing your own mail transport.
-
-**Q: What's the difference between `@hachej/boring-core/server` and `@hachej/boring-core/server/db`?**  
-A: `server` includes the full Fastify app, routes, auth, and stores. `server/db` is the Drizzle schema + connection + store interfaces only — useful for migration tooling and type-only imports.
+See [`docs/README.md`](./docs/README.md) for the architecture overview, public API
+surface, key abstractions, and links to the gating, plugin, and deployment docs. The
+reference app is [`apps/full-app`](../../apps/full-app/).
 
 ---
 
 *About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.
 
----
-
 ## License
 
 MIT

package/dist/app/front/index.js

@@ -8,7 +8,7 @@ import {
   useSignIn,
   useSignUp,
   useWorkspaceRouteStatus
-} from "../../chunk-5R3U6QKD.js";
+} from "../../chunk-MLTJKZL4.js";
 import "../../chunk-HYNKZSTF.js";
 import "../../chunk-H5KU6R6Y.js";
 import "../../chunk-MLKGABMK.js";

package/dist/app/server/index.js

@@ -9,7 +9,7 @@ import {
   registerRoutes,
   registerSettingsRoutes,
   registerWorkspaceRoutes
-} from "../../chunk-2JDK4XUZ.js";
+} from "../../chunk-GZVKZD4P.js";
 import {
   PostgresUserStore,
   PostgresWorkspaceStore,

package/dist/{chunk-2JDK4XUZ.js → chunk-GZVKZD4P.js}

@@ -1625,7 +1625,7 @@ function createPostSignupHook(deps) {
       }
     }
     if (!inviteAccepted) {
-      await workspaceStore.create(user.id, "My Workspace", config.appId, { isDefault: true });
+      await workspaceStore.create(user.id, "Default workspace", config.appId, { isDefault: true });
     }
     if (!inviteAccepted && config.features.sendWelcomeEmail !== false && transport) {
       const getStartedUrl = `${config.auth.url}/`;
@@ -1951,7 +1951,7 @@ var updateWorkspaceBody = z3.object({
 }).strict();
 
 // src/server/routes/workspaces.ts
-var DEFAULT_WORKSPACE_NAME = "My Workspace";
+var DEFAULT_WORKSPACE_NAME = "Default workspace";
 var workspaceRoutesPlugin = async (app) => {
   const store = app.workspaceStore;
   const provisioner = app.provisioner;

package/dist/{chunk-5R3U6QKD.js → chunk-MLTJKZL4.js}

@@ -2180,7 +2180,7 @@ import {
   Label as Label7,
   useToast
 } from "@hachej/boring-ui-kit";
-import { Check as Check2, ChevronsUpDown, LayoutGrid, Plus, Settings as Settings2 } from "lucide-react";
+import { ChevronsUpDown, LayoutGrid, Plus, Settings as Settings2 } from "lucide-react";
 import { useNavigate as useNavigate3 } from "react-router-dom";
 import { z as z6 } from "zod";
 import { Fragment as Fragment4, jsx as jsx17, jsxs as jsxs9 } from "react/jsx-runtime";
@@ -2219,6 +2219,13 @@ function hrefForWorkspace(prefix, workspaceId, suffix = "") {
 function workspaceInitial(name) {
   return (name.trim()[0] ?? "W").toUpperCase();
 }
+function OpenInNewTabIcon({ className }) {
+  return /* @__PURE__ */ jsxs9("svg", { className, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [
+    /* @__PURE__ */ jsx17("path", { d: "M15 3h6v6" }),
+    /* @__PURE__ */ jsx17("path", { d: "M10 14 21 3" }),
+    /* @__PURE__ */ jsx17("path", { d: "M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" })
+  ] });
+}
 function WorkspaceSwitcher({
   appTitle = "Boring",
   workspacePathPrefix = "/workspace"
@@ -2293,6 +2300,9 @@ function WorkspaceSwitcher({
     }
   }
   const switcherLabel = currentWorkspace?.name ?? "Select workspace";
+  function openWorkspaceInNewTab(workspaceId) {
+    window.open(hrefForWorkspace(workspacePathPrefix, workspaceId), "_blank", "noopener,noreferrer");
+  }
   return /* @__PURE__ */ jsxs9(Fragment4, { children: [
     workspaces.length === 0 ? /* @__PURE__ */ jsxs9(
       Button11,
@@ -2352,21 +2362,43 @@ function WorkspaceSwitcher({
             ] }) }),
             /* @__PURE__ */ jsx17("div", { className: "max-h-72 overflow-y-auto pr-1", children: workspaces.map((workspace) => {
               const isCurrent = currentWorkspace?.id === workspace.id;
-              return /* @__PURE__ */ jsxs9(
-                DropdownMenuItem2,
-                {
-                  "aria-label": workspace.name,
-                  "data-current": isCurrent ? "true" : "false",
-                  onSelect: () => navigate(hrefForWorkspace(workspacePathPrefix, workspace.id)),
-                  className: "gap-3 rounded-md py-2 text-[13px] focus:bg-foreground/[0.06] focus:text-foreground",
-                  children: [
-                    /* @__PURE__ */ jsx17("span", { className: "flex h-7 w-7 shrink-0 items-center justify-center rounded-md border border-border/60 bg-background text-xs font-semibold text-muted-foreground", children: workspaceInitial(workspace.name) }),
-                    /* @__PURE__ */ jsx17("span", { className: "min-w-0 flex-1 truncate text-sm", children: workspace.name }),
-                    isCurrent ? /* @__PURE__ */ jsx17(Check2, { className: "h-4 w-4 text-foreground", "aria-hidden": "true" }) : null
-                  ]
-                },
-                workspace.id
-              );
+              return /* @__PURE__ */ jsxs9("div", { className: "group relative w-full", children: [
+                /* @__PURE__ */ jsxs9(
+                  DropdownMenuItem2,
+                  {
+                    "aria-label": workspace.name,
+                    "data-current": isCurrent ? "true" : "false",
+                    onSelect: () => navigate(hrefForWorkspace(workspacePathPrefix, workspace.id)),
+                    style: { paddingRight: 72 },
+                    className: "gap-3 rounded-md py-2 text-[13px] focus:bg-foreground/[0.06] focus:text-foreground",
+                    children: [
+                      /* @__PURE__ */ jsx17("span", { className: "flex h-7 w-7 shrink-0 items-center justify-center rounded-md border border-border/60 bg-background text-xs font-semibold text-muted-foreground", children: workspaceInitial(workspace.name) }),
+                      /* @__PURE__ */ jsx17("span", { className: "min-w-0 flex-1 truncate text-sm", children: workspace.name })
+                    ]
+                  }
+                ),
+                /* @__PURE__ */ jsx17(
+                  "button",
+                  {
+                    type: "button",
+                    tabIndex: -1,
+                    "aria-label": `Open ${workspace.name} in new tab`,
+                    title: "Open in new tab",
+                    onPointerDown: (event) => {
+                      event.preventDefault();
+                      event.stopPropagation();
+                    },
+                    onClick: (event) => {
+                      event.preventDefault();
+                      event.stopPropagation();
+                      openWorkspaceInNewTab(workspace.id);
+                    },
+                    style: { right: 4, top: "50%", transform: "translateY(-50%)" },
+                    className: "absolute z-10 flex h-7 w-7 items-center justify-center rounded-md text-muted-foreground opacity-0 transition hover:bg-foreground/10 hover:text-foreground focus:opacity-100 focus:outline-none focus-visible:ring-1 focus-visible:ring-ring group-hover:opacity-100 group-focus-within:opacity-100",
+                    children: /* @__PURE__ */ jsx17(OpenInNewTabIcon, { className: "h-3.5 w-3.5" })
+                  }
+                )
+              ] }, workspace.id);
             }) }),
             /* @__PURE__ */ jsx17(DropdownMenuSeparator2, { className: "-mx-2" }),
             /* @__PURE__ */ jsxs9(
@@ -2431,7 +2463,7 @@ function WorkspaceSwitcher({
                 setName(event.target.value);
                 if (serverError) setServerError(null);
               },
-              placeholder: "My Workspace",
+              placeholder: "Default workspace",
               "aria-invalid": nameError ? "true" : "false",
               autoFocus: true
             }

package/dist/front/index.js

@@ -58,7 +58,7 @@ import {
   useWorkspaceMembers,
   useWorkspaceRole,
   useWorkspaceRouteStatus
-} from "../chunk-5R3U6QKD.js";
+} from "../chunk-MLTJKZL4.js";
 import {
   TopBarSlotProvider,
   useTopBarSlot

package/dist/server/index.js

@@ -24,7 +24,7 @@ import {
   requireWorkspaceMember,
   validateConfig,
   validatePasswordStrength
-} from "../chunk-2JDK4XUZ.js";
+} from "../chunk-GZVKZD4P.js";
 import {
   createDatabase,
   runMigrations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-core",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "type": "module",
   "license": "MIT",
   "description": "Foundation package for boring-ui-v2 apps: DB, auth, config, HTTP app factory, and frontend app shell.",
@@ -79,9 +79,9 @@
     "react-router-dom": "^7.14.2",
     "smol-toml": "^1.6.1",
     "zod": "^3.25.76",
-    "@hachej/boring-agent": "0.1.40",
-    "@hachej/boring-workspace": "0.1.40",
-    "@hachej/boring-ui-kit": "0.1.40"
+    "@hachej/boring-agent": "0.1.42",
+    "@hachej/boring-ui-kit": "0.1.42",
+    "@hachej/boring-workspace": "0.1.42"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",