everything-dev 1.42.1 → 1.42.2

package/skills/api-and-auth/SKILL.md

@@ -0,0 +1,355 @@
+---
+name: api-and-auth
+description: API architecture, oRPC contracts, auth middleware, plugin-client composition, session handling, and client-side auth. Use when adding API routes, creating middleware, calling other plugins in-process, or integrating auth in routes and UI.
+metadata:
+  sources: "api/src/index.ts,api/src/contract.ts,api/src/lib/auth.ts,host/src/services/auth.ts,host/src/services/plugins.ts,host/src/program.ts,ui/src/lib/auth.ts,ui/src/lib/api.ts"
+---
+
+# API Architecture & Auth
+
+## Plugin Anatomy
+
+The API is an every-plugin registered via `createPlugin.withPlugins<PluginsClient>()`:
+
+```ts
+export default createPlugin.withPlugins<PluginsClient>()({
+  variables: z.object({ /* typed config */ }),
+  secrets: z.object({ /* typed env vars, defaults for dev */ }),
+  context: z.object({ /* per-request context injected by host */ }),
+  contract,
+  initialize: (config, plugins) => Effect.promise(async () => {
+    return { db, upvoteService, publisher, auth, plugins };
+  }),
+  shutdown: (services) => Effect.promise(async () => { /* cleanup */ }),
+  createRouter: (services, builder) => ({
+    ping: builder.ping.handler(async () => ({ status: "ok", timestamp })),
+  }),
+});
+```
+
+Fields: `variables` (public config), `secrets` (private env), `context` (per-request host context), `contract` (oRPC router), `initialize` (startup, returns services), `createRouter` (maps procedures to handlers), `shutdown` (cleanup). `plugins` in `initialize` gives typed factories for all other plugins.
+
+## oRPC Contract Design
+
+Defined in `api/src/contract.ts`:
+
+```ts
+import { BAD_REQUEST, NOT_FOUND, UNAUTHORIZED } from "every-plugin/errors";
+import { eventIterator, oc } from "every-plugin/orpc";
+import { z } from "every-plugin/zod";
+
+export const contract = oc.router({
+  ping: oc.route({ method: "GET", path: "/ping" }).output(
+    z.object({ status: z.literal("ok"), timestamp: z.iso.datetime() }),
+  ),
+  upvoteThing: oc
+    .route({ method: "POST", path: "/upvotes" })
+    .input(z.object({ thingId: z.string() }))
+    .output(z.object({ thingId: z.string(), userId: z.string(), totalCount: z.number().int().nonnegative() }))
+    .errors({ UNAUTHORIZED, BAD_REQUEST }),
+  getUserVote: oc
+    .route({ method: "GET", path: "/upvotes/{thingId}/me" })
+    .input(z.object({ thingId: z.string() }))
+    .output(z.object({ thingId: z.string(), hasUpvote: z.boolean() }))
+    .errors({ UNAUTHORIZED }),
+  getUpvoteFeed: oc
+    .route({ method: "GET", path: "/upvotes/feed" })
+    .input(z.object({ limit: z.number().int().min(1).max(100).optional(), cursor: z.string().optional() }))
+    .output(z.object({ data: z.array(/*...*/), meta: z.object({ total, hasMore, nextCursor }) })),
+  subscribeUpvotes: oc
+    .route({ method: "GET", path: "/upvotes/stream" })
+    .output(eventIterator(VoteEventSchema)),
+});
+```
+
+Conventions: `.errors()` declares typed errors, `{paramName}` path params match Zod input keys, `.output(eventIterator(Schema))` enables SSE streaming, export `type ContractType = typeof contract` for type generation.
+
+## Route Implementation
+
+```ts
+createRouter: (services, builder) => {
+  const { requireAuth } = createAuthMiddleware(builder);
+
+  return {
+    ping: builder.ping.handler(async () => ({
+      status: "ok",
+      timestamp: new Date().toISOString(),
+    })),
+    upvoteThing: builder.upvoteThing.use(requireAuth).handler(async ({ input, context }) => {
+      return await services.upvoteService.upvoteThing(input.thingId, context.userId);
+    }),
+    subscribeUpvotes: builder.subscribeUpvotes.handler(async function* ({ signal, lastEventId }) {
+      const iterator = services.publisher.subscribe("vote", { signal, lastEventId });
+      for await (const event of iterator) yield event;
+    }),
+  };
+};
+```
+
+Handler receives `{ input, context, signal?, lastEventId? }`.
+
+## Middleware
+
+Create auth middleware with `createAuthMiddleware(builder)` in `api/src/lib/auth.ts`. Each middleware narrows the context type through `.use()` — no non-null assertions needed.
+
+```ts
+const { requireAuth } = createAuthMiddleware(builder);
+
+builder.myRoute.use(requireAuth).handler(async ({ input, context }) => {
+  context.userId; // string — narrowed by middleware
+});
+```
+
+Available: `requireAuth`, `requireAuthOrApiKey`, `requireRole("admin")`, `requireOrganization`, `requireOrgRole("owner")`, `requireApiKey`. Apply via `.use()`:
+
+```ts
+builder.authHealth.use(requireAuth).handler(...)
+builder.adminAction.use(requireRole("admin")).handler(...)
+```
+
+See `references/middleware.md` for the full middleware table, org metadata validation, and typed context helpers.
+
+## Error Handling
+
+Use `ORPCError` from `every-plugin/errors`:
+
+```ts
+import { ORPCError } from "every-plugin/orpc";
+import { BAD_REQUEST, UNAUTHORIZED } from "every-plugin/errors";
+
+throw new ORPCError("UNAUTHORIZED", {
+  message: "Authentication required",
+  data: { hint: "Sign in or provide an API key" },
+});
+```
+
+Declare throwable errors in the contract via `.errors({ UNAUTHORIZED, BAD_REQUEST })`. Client-side errors are intercepted by `onError` in `createRpcLink` (`ui/src/lib/api.ts`).
+
+## Auth Plugin Architecture
+
+The auth plugin is an **external plugin** loaded in **Phase 0** of the host's initialization:
+
+1. **Phase 0** (`host/src/services/plugins.ts`): Load auth plugin, create `authClient` factory.
+2. **Phase 1**: Load all non-API plugins.
+3. **Phase 2**: Load API plugin with `pluginsClient` (includes auth + all other plugin factories).
+
+The host mounts the auth handler at `/api/auth/*`:
+
+```ts
+// host/src/services/auth.ts
+export function registerAuthHandler(app, plugins) {
+  const services = getAuthServices(plugins);
+  if (!services) return;
+  app.on(["POST", "GET"], "/api/auth/*", (c) => services.handler(c.req.raw));
+}
+```
+
+## Session Middleware
+
+Runs on every non-auth request. Resolves the session from cookies and sets Hono request context:
+
+```ts
+// host/src/services/auth.ts
+export function createSessionMiddleware(plugins) {
+  return async (c, next) => {
+    if (c.req.path.startsWith("/api/auth/")) return next();
+    c.set("reqHeaders", c.req.raw.headers);
+
+    const authClient = authClientFactory({ reqHeaders });
+    const [session, context] = await Promise.all([
+      authClient.getSession(),
+      authClient.getContext(),
+    ]);
+
+    c.set("user", session?.user ?? context.user ?? null);
+    c.set("session", session?.session ?? null);
+    c.set("walletAddress", context.near.primaryAccountId ?? null);
+    c.set("apiKey", context.apiKey ?? null);
+    c.set("organizationId", context.organization?.activeOrganizationId ?? null);
+
+    await next();
+  };
+}
+```
+
+If resolution fails, all values are `null` — `requireAuth` routes reject with `UNAUTHORIZED`.
+
+The context is transformed for the API plugin via `buildPluginContext()`, with the full `organization` envelope from Better Auth:
+
+```ts
+export function buildPluginContext(c) {
+  return {
+    userId: user?.id, user: user ?? undefined,
+    organization: context.organization ?? undefined,
+    apiKey: apiKey ?? undefined,
+    reqHeaders: c.get("reqHeaders"),
+    getRawBody: c.get("getRawBody"),
+  };
+}
+```
+
+## Auth in API Routes
+
+The API plugin receives `auth` in `initialize`:
+
+```ts
+initialize: (config, plugins) => Effect.promise(async () => {
+  const { auth, ...restPlugins } = plugins;
+  return { auth, plugins: restPlugins, ... };
+})
+```
+
+Use `getAuthClient()` for in-process calls:
+
+```ts
+import { getAuthClient, createAuthMiddleware } from "./lib/auth";
+
+const authClient = getAuthClient(services, { reqHeaders: context.reqHeaders });
+const session = await authClient.getSession();
+```
+
+`AuthCapableServices` requires an `auth` factory. If unavailable, `getAuthClient()` throws.
+
+## Auth on the Client
+
+Create the client in `ui/src/lib/auth.ts`:
+
+```ts
+export function createAuthClient(runtimeConfig) {
+  return betterAuth.createClient({
+    baseURL: runtimeConfig.authBaseUrl,
+    plugins: [siwn({ recipients, networkId }), passkey(), organization(), admin(), apiKey(), anonymous(), phone()],
+  });
+}
+```
+
+In route code:
+
+```ts
+import { useAuthClient, sessionQueryOptions } from "@/app";
+
+const authClient = useAuthClient();
+```
+
+The `sessionQueryOptions()` helper provides standard TanStack Query config:
+
+```ts
+const session = await queryClient.ensureQueryData(
+  sessionQueryOptions(authClient, context.session),
+);
+```
+
+### Auth Route Guard
+
+The `_authenticated.tsx` layout redirects unauthenticated users:
+
+```ts
+export const Route = createFileRoute("/_layout/_authenticated")({
+  beforeLoad: async ({ context, location }) => {
+    const { queryClient, authClient } = context;
+    const session = await queryClient.ensureQueryData(
+      sessionQueryOptions(authClient, context.session),
+    );
+    if (!session?.user) {
+      throw redirect({ to: "/login", search: { redirect: location.href } });
+    }
+    return { auth: { isAuthenticated: true, user: session.user, session: session.session } };
+  },
+  component: AuthenticatedLayout,
+});
+```
+
+## Plugin Client Composition
+
+The host uses **two-phase loading** so API plugins can call other plugins in-process:
+
+1. **Phase 0**: Auth plugin → `authClient` factory
+2. **Phase 1**: All non-API plugins → `pluginsClient` map of `createClient` factories
+3. **Phase 2**: API plugin with all plugin factories merged
+
+```ts
+// host/src/services/plugins.ts
+const pluginsClient = { ...pluginClients };
+if (authClient) pluginsClient.auth = authClient;
+const baseApi = await loadPluginEntry(runtime, apiEntry, integrityRegistry, pluginsClient);
+```
+
+### Calling Plugins from API Routes
+
+The API plugin receives `plugins` in `initialize`:
+
+```ts
+initialize: (config, plugins) => Effect.promise(async () => {
+  const authClient = plugins.auth({ reqHeaders: someHeaders });
+  const session = await authClient.getSession();
+  return { auth: plugins.auth, plugins, ... };
+})
+```
+
+### API-Owned Registry Pattern
+
+When the API owns the durable registry and a plugin owns the semantic payload:
+
+```ts
+const provider = thingProviders[input.pluginId];
+if (!provider) {
+  throw new ORPCError("BAD_REQUEST", { message: `Unsupported pluginId: ${input.pluginId}` });
+}
+```
+
+Rules: API owns `thingId`, `pluginId`, timestamps. Plugin owns `type` and `payload`. Keep one SSE stream per concept and filter server-side.
+
+### Effect and DB Lifecycle
+
+Prefer `Layer` for long-lived resources (DB, service singletons) and `Effect` for the work itself. Use `runEffect()` to bridge Effect and async handlers with clean ORPC error boundaries — unwraps `ORPCError` from Effect and converts unknown errors to `INTERNAL_SERVER_ERROR`:
+
+```ts
+import { runEffect } from "@/lib/context";
+
+const result = await runEffect(services.myService.doSomething(input));
+```
+
+Best practices: Keep service interfaces Effect-native, bridge to async only at the handler boundary via `runEffect()`. Use `Context.Tag` for DI between services. Initialize long-lived resources in `initialize` and return them as services.
+
+### SSR Proxy Client
+
+`createPluginsClient()` creates a Proxy that merges the API client with all plugin clients:
+
+```ts
+export function createPluginsClient(result, context) {
+  const apiClient = result.api?.createClient(context);
+  const pluginClients = {};
+  for (const [key, plugin] of Object.entries(result.plugins)) {
+    if (key === "api") continue;
+    pluginClients[key] = plugin.createClient(context);
+  }
+  if (result.authClient) pluginClients.auth = result.authClient(context);
+
+  return new Proxy(apiClient, {
+    get(target, key) {
+      if (typeof key === "string" && key in pluginClients) return pluginClients[key];
+      return Reflect.get(target, key);
+    },
+  });
+}
+```
+
+## Generated Types
+
+See `references/generated-types.md` for the full table — files, contents, and regeneration triggers.
+
+## SSE Notes
+
+Prefer a single publisher channel per concept and filter on the consumer side:
+
+```ts
+const iterator = services.publisher.subscribe("thing", { signal, lastEventId });
+for await (const event of iterator) {
+  if (input.pluginId && event.pluginId !== input.pluginId) continue;
+  yield event;
+}
+```
+
+## How Routes Are Mounted
+
+The host (`host/src/program.ts`) creates RPC and OpenAPI handlers from each plugin's router, mounted at `/api/rpc/<plugin-namespace>`. The session middleware runs on `/api/*` before the RPC handlers, ensuring context is set.

package/skills/api-and-auth/references/generated-types.md

@@ -0,0 +1,14 @@
+# Generated Types
+
+| File | Contents | Regenerated by |
+|------|----------|---------------|
+| `api/src/lib/plugins-types.gen.ts` | `PluginsClient` — factory types for all plugins | `bos types gen` |
+| `api/src/lib/auth-types.gen.ts` | Auth plugin request context types | `bos types gen` |
+| `ui/src/lib/api-types.gen.ts` | `ApiContract` — all procedure types | `bos types gen` |
+| `ui/src/lib/auth-types.gen.ts` | Auth client session/user types | `bos types gen` |
+
+Type resolution:
+- `local:plugins/<name>` → reads `src/contract.ts` directly from disk
+- Remote URL → fetches contract types from the deployed plugin's manifest
+- Missing local path with no URL → skipped with a warning
+- Run `bos types gen` or restart `bos dev` after hand-editing `bos.config.json`

package/skills/api-and-auth/references/middleware.md

@@ -0,0 +1,38 @@
+# Middleware Reference
+
+## Available Middlewares
+
+| Middleware | Narrows |
+|---|---|
+| `requireAuth` | `userId: string`, `user: RequestAuthUser` |
+| `requireAuthOrApiKey` | gate only — allows session or API key auth, no narrowing |
+| `requireRole("admin")` | `userId`, `user` |
+| `requireOrganization` | `userId`, `user`, `organization.activeOrganizationId: string` |
+| `requireOrgRole("owner")` | all of above + `organization.member` non-null with `id`, `role` |
+| `requireApiKey` | `apiKey: ApiKeyContext` |
+
+## Org Metadata Validation
+
+Pass an optional Zod schema to `createAuthMiddleware` for runtime validation:
+
+```ts
+import { z } from "every-plugin/zod";
+
+const orgMetaSchema = z.object({ plan: z.enum(["free", "pro"]), seats: z.number() });
+const { requireOrganization } = createAuthMiddleware(builder, { orgMetaSchema });
+```
+
+When a schema is provided, `requireOrganization` and `requireOrgRole` call `schema.safeParse()` on the org metadata. On parse failure, throws `INTERNAL_SERVER_ERROR` (data integrity issue). When no schema is passed, metadata stays `Record<string, unknown>` with no validation.
+
+## Typed Org Context Helpers
+
+```ts
+import type { OrgAuthenticatedContext } from "./lib/auth";
+
+type MyOrgMeta = { plan: "free" | "pro"; seats: number };
+
+const ctx = context as OrgAuthenticatedContext<MyOrgMeta>;
+ctx.organization.organization?.metadata?.plan;
+```
+
+Also available: `OrgMemberAuthenticatedContext<TMeta>` (guarantees `organization.member` is non-null).

package/skills/cli-reference/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: cli-reference
+description: Quick reference for all bos CLI commands — flags, options, environment settings, and links to detailed guidance in related skills. Use when any bos command comes up or the user needs a CLI overview.
+metadata:
+  sources: "packages/everything-dev/src/contract.ts,packages/everything-dev/src/contract.meta.ts,packages/everything-dev/src/cli.ts,packages/everything-dev/src/cli/catalog.ts"
+---
+
+# CLI Command Reference
+
+17 `bos` commands organised by workflow category.
+
+## Development
+
+### `bos dev`
+
+Start a development session. Runs host, API, auth, and UI processes with hot reload.
+
+**Flags:** `--host <local|remote>` `--ui <local|remote>` `--api <local|remote>` `--auth <local|remote>` `--remote-plugins <ids>` `--proxy` `--ssr` `--port <n>`
+
+```bash
+bos dev                   # full local (all services)
+bos dev --api remote      # UI-only mode, use remote API
+bos dev --ui remote       # API-only mode, use remote UI
+bos dev --proxy           # local host proxies to remote API/UI
+bos dev --remote-plugins auth,registry  # force specific plugins remote
+```
+
+→ [`dev-workflow`](.) skill for port assignments, service-descriptor architecture, hot reload, and debugging.
+
+### `bos start`
+
+Start the production host. Loads config from `bos.config.json`, wires MF remotes, serves SSR.
+
+**Flags:** `--env <production|staging>` `--port <n>` `--account <id>` `--domain <domain>` `--no-interactive`
+
+```bash
+bos start                          # production, auto-detects env
+bos start --env staging            # staging mode
+bos start --account myapp.near     # tenant override
+```
+
+→ [`dev-workflow`](.) skill for production topology and [`super-app`](.) for tenant overrides.
+
+### `bos build`
+
+Build all workspace packages (or a subset) for production.
+
+**Flags:** `--packages <list>` `--force` `--deploy`
+
+```bash
+bos build                    # build all workspaces
+bos build --packages ui,api  # build specific packages
+bos build --force            # rebuild even if up-to-date
+bos build --deploy           # build + deploy to Zephyr
+```
+
+→ [`publish-sync`](.) skill for full deploy+publish workflow.
+
+### `bos config`
+
+Print the loaded configuration (plain or fully resolved).
+
+**Flags:** `--full`
+
+```bash
+bos config        # print bos.config.json with env overrides applied
+bos config --full # print fully resolved config (extends + deep merge)
+```
+
+→ [`extends-config`](.) skill for deep merge semantics and resolved config lifecycle.
+
+## Lifecycle
+
+### `bos init`
+
+Scaffold a new project from a deployed app or template. Interactive by default.
+
+**Flags:** `--extends <ref>` `--directory <dir>` `--account <id>` `--domain <d>` `--source <dir>` `--plugins <list>` `--overrides <sections>` `--no-interactive` `--no-install`
+
+```bash
+bos init                                       # interactive wizard
+bos init mysite.everything.dev                 # quick scaffold from current config
+bos init --extends bos://account/gateway       # from a specific parent
+bos init --overrides ui,api,host,plugins       # customise local sections
+bos init --source ./my-app --no-interactive    # from local source, skip prompts
+```
+
+→ [`init-upgrade`](.) skill for template download, file selection, snapshots, and conflict wiring.
+
+### `bos sync`
+
+Sync template files from the parent project. Compares snapshot-versioned files to detect conflicts.
+
+**Flags:** `--dry-run` `--no-install`
+
+```bash
+bos sync
+bos sync --dry-run    # preview without writing
+```
+
+→ [`init-upgrade`](.) skill for snapshot-based conflict detection and framework-owned sections.
+
+### `bos upgrade`
+
+Upgrade framework packages then sync template files. Interactive; prompts for package selection.
+
+**Flags:** `--dry-run` `--no-install` `--no-sync`
+
+```bash
+bos upgrade
+bos upgrade --dry-run       # preview version bumps
+bos upgrade --no-sync       # only upgrade packages, skip template sync
+```
+
+→ [`init-upgrade`](.) skill for catalog strategy, legacy import rewrites, and upgrade+publish flow.
+
+### `bos status`
+
+Show project health: package versions, parent reachability, last sync, env file status, and update availability.
+
+```bash
+bos status
+```
+
+Output includes installed vs latest versions for each workspace package, whether the parent extends reference is reachable, whether `.env` exists, and when the last sync ran. No flags.
+
+## Publishing
+
+### `bos publish`
+
+Publish `bos.config.json` to the FastKV on-chain registry. Optionally build and deploy workspaces first.
+
+**Flags:** `--deploy` `--dry-run` `--network <mainnet|testnet>` `--private-key <key>` `--env <production|staging>` `--packages <list>`
+
+```bash
+bos publish                    # publish current config snapshot
+bos publish --deploy           # build all + deploy + publish
+bos publish --dry-run          # preview what would be published
+bos publish --network testnet  # publish to testnet registry
+```
+
+→ [`publish-sync`](.) skill for config sections, SRI integrity, rollback, and FastKV troubleshooting.
+
+### `bos deploy`
+
+Publish config and trigger a Railway redeploy. Builds and deploys by default.
+
+**Flags:** `--env <production|staging>` `--no-build` `--dry-run` `--network <mainnet|testnet>` `--private-key <key>` `--service <name>` `--packages <list>`
+
+```bash
+bos deploy                        # build + publish + trigger deploy
+bos deploy --no-build             # publish only, skip workspace build
+bos deploy --service my-railway   # override Railway service name
+```
+
+→ [`publish-sync`](.) skill and [`super-app`](.) for tenant-aware deploy considerations.
+
+### `bos key publish`
+
+Generate a publish access key (NEAR function-call key) scoped to the FastKV registry contract.
+
+**Flags:** `--allowance <amount>` (default: `0.25NEAR`)
+
+```bash
+bos key publish                    # generate key with default allowance
+bos key publish --allowance 1NEAR  # custom allowance
+```
+
+Outputs the public key, private key, and registry contract address. The generated key can only call the set and get methods on the BOS registry contract — it cannot transfer funds or call other contracts.
+
+## Plugins
+
+### `bos plugin add`
+
+Add a plugin attachment to `bos.config.json` from a local path, BOS reference, or remote URL.
+
+**Flags:** `<source>` (positional) `--as <alias>` `--production <url>`
+
+```bash
+bos plugin add local:plugins/my-plugin                         # local plugin
+bos plugin add bos://account/gateway                           # from BOS registry
+bos plugin add https://cdn.example.com/remoteEntry.js           # remote URL
+bos plugin add local:plugins/my-plugin --as my-alias            # with alias
+bos plugin add local:plugins/my-plugin --production <prod-url>  # separate prod URL
+```
+
+→ [`plugin-development`](.) skill for plugin anatomy, contract/service/index pattern, and registration.
+
+### `bos plugin remove`
+
+Remove a plugin attachment from `bos.config.json`.
+
+**Flags:** `<key>` (positional)
+
+```bash
+bos plugin remove my-plugin
+```
+
+### `bos plugin list`
+
+List all configured plugins with their sources (local vs remote), versions, and integrity hashes.
+
+```bash
+bos plugin list
+```
+
+Outputs each plugin's key, development source, production URL, local path, version, and SRI integrity hash.
+
+### `bos plugin publish`
+
+Build and publish a single plugin to Zephyr CDN, then update `bos.config.json` with the production URL and SRI integrity hash.
+
+**Flags:** `<key>` (positional)
+
+```bash
+bos plugin publish my-plugin
+```
+
+→ [`plugin-development`](.) skill for build config (rspack.config.js), CLI lifecycle, and deploy workflow.
+
+## Types & DB
+
+### `bos types gen`
+
+Generate and fetch type definitions from configured API and plugin contracts. Runs automatically on `bun install`, `bos dev`, `bos build`, `bos plugin add`, and `bos plugin remove`.
+
+**Flags:** `--env <development|production>` `--dry-run`
+
+```bash
+bos types gen                     # development mode (local + remote sources)
+bos types gen --env production    # production mode (remote sources only)
+bos types gen --dry-run           # preview without writing files
+```
+
+Generated files: `api-types.gen.ts`, `auth-types.gen.ts` (ui, api, host), `plugins-types.gen.ts`, `plugin-sidebar.gen.ts`. Uses `local:` sources in dev and production URLs in production mode.
+
+### `bos db studio`
+
+Open Drizzle Studio for inspecting a plugin's database.
+
+**Flags:** `<plugin>` (positional, default: `api`)
+
+```bash
+bos db studio             # open Drizzle Studio for the API database
+bos db studio auth        # open for the auth plugin
+bos db studio my-plugin   # open for a custom plugin
+```
+
+Requires the `DATABASE_URL` secret to be set on the target plugin. Uses the plugin's drizzle.config.ts for schema discovery.