@simple-auth-kit/cli 1.0.0

package/registry/README.md

@@ -0,0 +1,312 @@
+# `registry/` — layout convention
+
+This is the source the CLI copies into consumer projects. Nothing here is ever installed as a
+dependency.
+
+Every combo ships in **two variants**, chosen by the consumer at `simple-auth-kit add` time:
+
+| Variant | CLI | What it is |
+|---|---|---|
+| `base` | `simple-auth-kit add <combo>` (default) | Roles and permissions are global to the deployment. Real join tables (`RoleUser`, `PermissionRole`, `PermissionUser`); direct grants attach to the user. |
+| `workspaces` | `simple-auth-kit add <combo> --workspaces` | A user belongs to any number of workspaces and holds different roles in each. `Workspace` + `WorkspaceMember`; `Role` unique per `[workspaceId, slug]`; membership-scoped join tables (`RoleMember`, `PermissionMember`); direct grants attach to the *membership*. Workspace-scoped requests carry `X-Workspace-Id`. |
+
+The emitted project contains exactly one variant. A consumer cannot tell the other exists.
+
+## `kind`: this doc covers `api` combos specifically
+
+Every combo also has a `kind` (`api`, `admin`, or `mobile`, in `packages/cli/registry.json` — absent means
+`api`, since every combo predating that field is one) and an `installMode` (`merge` or
+`scaffold`). This file is entirely about **`kind: "api"`** combos — `registry/combos/*`, `merge`
+mode, a source fragment the CLI composes into an *existing* project's `src/lib/auth`. Everything
+here (the byte-identical rule, the two-variant model, `shared/`+`variants/*`, the seeder,
+enforcement) is specific to that shape.
+
+`kind: "admin"` (`registry/admin-apps/*`) and `kind: "mobile"` (`registry/mobile-apps/*`) combos
+share the same `shared/`+`variants/{base,workspaces}` composition and the same byte-identical
+hoisting rule, but `installMode: "scaffold"`: the CLI writes a **whole standalone app** — its own
+`package.json`, its own `src/`, everything — directly into the target directory, not a fragment
+merged into a host project. See `registry/admin-apps/README.md` and
+`registry/mobile-apps/README.md` for what's specific to those two.
+
+## Directory layout
+
+`registry/combos/nestjs-prisma` is the reference. Every other combo mirrors this shape exactly.
+
+```
+registry/
+├── core/                      variant-agnostic auth logic. Knows nothing about workspaces,
+│                              and must stay that way — it receives already-resolved roles and
+│                              permissions; resolving them is the combo's job.
+└── combos/<combo>/
+    ├── package.json           scripts below; never copied to consumers
+    ├── tsconfig.json          editor/tooling only; never copied
+    ├── .env                   local dev only (base variant's DATABASE_URL); never copied
+    ├── scripts/
+    │   ├── materialize.mjs    composes .variant/<variant>/ from shared/ + variants/<variant>/
+    │   ├── migrate.mjs        authors a migration for a variant, copies it back into variants/
+    │   ├── prove-cycle.mjs    runs the black-box proof against each variant
+    │   └── seed.mjs           runs a variant's seeder against this combo's dev database
+    ├── shared/                ← COPIED FOR BOTH VARIANTS
+    │   ├── .gitignore
+    │   ├── prisma.config.ts   (Prisma combos only)
+    │   └── src/**
+    ├── variants/
+    │   ├── base/              ← COPIED FOR `add <combo>`
+    │   │   ├── .env.example
+    │   │   ├── prisma/schema.prisma
+    │   │   ├── prisma/migrations/**
+    │   │   ├── src/**
+    │   │   └── test/variant-hooks.ts
+    │   └── workspaces/        ← COPIED FOR `add <combo> --workspaces`
+    │       └── (same shape)
+    ├── test/                  shared proof harness; never copied to consumers
+    │   ├── bootstrap.ts
+    │   ├── harness.ts
+    │   └── prove-cycle.ts
+    └── .variant/              gitignored build output — a composed, runnable variant
+```
+
+**The rule for deciding where a file goes: write both variants, then hoist every file that comes
+out byte-identical into `shared/`.** Anything that differs — even by one line — stays in both
+`variants/*` directories. There is no third category and no conditional code: a file must not
+branch on which variant it is in.
+
+Composition is `shared/` copied first, then `variants/<variant>/` copied over the top. Both the
+CLI (`packages/cli/lib/copy.ts`) and `scripts/materialize.mjs` do exactly this, so what the combo
+typechecks and proves is what the CLI emits.
+
+### Which files ended up where, in the reference combo
+
+`shared/src`: the identity/session/2FA machinery and everything both variants use unchanged —
+`auth.config.ts`, `auth.controller.ts`, `auth.guard.ts`, `ability.ts`, `ability.guard.ts`,
+`route-tiers.ts`, `permission-cache.ts`, `request-context.ts`, `response.interceptor.ts`,
+`pagination.ts`, `id.helper.ts`, `key-provider.ts`, `rate-limit.store.ts`,
+`auth-core-error.filter.ts`, the `session/two-factor/password-reset/oauth` repositories,
+`dto/auth.dto.ts`.
+
+`variants/<variant>/src`: everything whose implementation depends on how authorization is
+scoped — `auth.module.ts`, `auth.service.ts`, `admin.controller.ts`, `authz.guard.ts`,
+`rbac.repository.ts`, `rbac.defaults.ts`, `audit-log.repository.ts`, `seed.ts`,
+`dto/admin.dto.ts`, and the content-domain repositories
+(`country/language/customer.repository.ts`, this combo only). Plus, in `base` only,
+`audit-log.gateway.ts` (the socket.io feed) and `docs.ts`; in `workspaces` only,
+`workspace.controller.ts`, `workspace.repository.ts`, `dto/workspace.dto.ts`.
+
+`rbac.defaults.ts` is per variant rather than shared because the catalogs differ by one slug
+(`members:manage` exists only where there are members to manage), and a file must not branch on
+its variant. See "Enforcement" below — it is the file the whole authorization story hangs off.
+
+`variants/<variant>/.env.example`: not shared. The workspace variant's seeder reads one variable
+the base variant has no concept of (`SEED_WORKSPACE_NAME`), and an emitted project must not
+document a variable it will never read — that is the same "a consumer cannot tell the other
+variant exists" rule the byte-identical test enforces everywhere else.
+
+### The seam that keeps the shared half shared
+
+Authentication and authorization are separate request-scoped objects (`shared/src/request-context.ts`):
+
+- `req.auth` — the verified access-token claims. Set by the shared `AuthGuard`. Identity only —
+  **nothing about authorization is ever in the token.**
+- `req.authz` — the roles and permissions that apply to *this request*, resolved from the
+  database. Set by `AuthzGuard`, which is the one guard each variant writes for itself:
+  - `base` resolves the caller's global roles/permissions on the `userId`.
+  - `workspaces` reads the `X-Workspace-Id` header, resolves the membership on the
+    `[userId, workspaceId]` unique index, then that membership's roles and permissions — its
+    `AuthzContext` also carries `workspaceId`/`memberId`, which is what scopes every admin
+    query to one workspace without a second check.
+
+Both variants resolve through `PermissionCache` (version-key invalidation, single-flight), so
+the steady-state cost is a cache read while the semantics stay "read from the database": a
+grant or revocation lands on the caller's **next request**, not their next token, and
+`POST /auth/logout`'s denylist is the instant kill for a live access token.
+
+`AuthzGuard` also builds `req.ability` — the CASL ability over the resolved permission slugs —
+which is what the shared `AbilityGuard` checks. `AbilityGuard` only ever reads what the
+variant's `AuthzGuard` resolved, which is why it can be shared.
+
+## Working on a combo
+
+```bash
+cd registry/combos/<combo>
+npm run materialize -- workspaces   # compose one variant into .variant/workspaces
+npm run prisma:generate             # compose both + generate their Prisma clients
+npm run typecheck                   # both variants
+npm run prove-cycle                 # both variants, end to end, against Postgres
+npm run migrate -- workspaces --name init   # author migrations, written back into variants/
+npm run seed -- workspaces          # run that variant's seeder against its dev database
+```
+
+Each variant owns its own database (`auth_reference`, `auth_reference_workspaces`) — their
+schemas are different shapes, not different states of one schema.
+
+Migrations are **regenerated clean per variant**, never amended with drop-column migrations:
+the CLI copies the migration directory verbatim into every consumer's repo, so a migration that
+exists only to undo a decision this library already reversed is permanent archaeology in
+someone else's project.
+
+## The proof
+
+`npm run prove-cycle` runs `test/prove-cycle.ts` against each materialized variant. That file is
+variant-agnostic and speaks HTTP only — **do not branch on the variant name in it**. The things
+that genuinely differ come from `variants/<variant>/test/variant-hooks.ts`, which implements
+the `VariantHooks` contract in `test/harness.ts`:
+
+- `makeAdmin` — give a user administrative authority, and say how to make admin calls as them.
+- `admitUser` — bring a user into that admin's scope (a no-op in `base`).
+- `proveVariantProperties` — the assertions only that variant can make. For `workspaces` this
+  is the security property the model rests on: **a role held in workspace A grants nothing in
+  workspace B.** That test is not optional.
+
+`test/harness.ts` also exports `adminRouteProbes()`: admin routes paired with the permission
+slug each is gated on, in an order that undoes itself (assign before revoke, block before
+unblock) so the whole list can be run repeatedly against one target user. `prove-cycle.ts` runs
+it once per catalog slug, against a caller holding that one permission and a role that carries
+nothing, and asserts the routes it names succeed and every other route 403s. Mirroring a combo
+means porting that table, not re-deriving it.
+
+## The seeder
+
+Roles and the permission catalog are seeded data, so a freshly migrated database has no
+`Permission` rows and no `Role` rows and authorization has nothing to check against. Every combo
+ships `variants/<variant>/src/seed.ts` to close that gap. It is **consumer-facing source**, not
+repo tooling: it is copied into the emitted project like any other file under `src/`, and the
+consumer runs it as `npm run seed`. `scripts/seed.mjs` runs the same file against this combo's
+own dev database, so what is exercised here is exactly what a consumer runs.
+
+**The contract every combo's seeder implements.** Mirroring it to another combo is a translation
+of these rules into that combo's ORM, not a redesign:
+
+1. **Idempotent by construction.** Every write is an upsert keyed on the natural unique key
+   (`Permission.slug`, `Role.slug` / `[workspaceId, slug]`, the join-table composite ids,
+   `User.email`, `[userId, workspaceId]`). Nothing is ever deleted, so a re-run is additive: a
+   permission attached to a seeded role by hand survives it.
+2. **The permission catalog comes from `rbac.defaults.ts`** (see "Enforcement"), one
+   `noun:verb` slug per capability the admin API actually exposes — not a speculative list.
+3. **Two default roles.** `admin` carries the whole catalog; `member` is the signup/new-membership
+   default and carries the empty set, because every slug in the catalog is administrative. No
+   guard checks for a role name — the names are load-bearing only as the default a new user or
+   membership is given, and as `SEED_ADMIN_ROLES` (`["admin", "member"]`, so the admin is also
+   an ordinary user).
+4. **The initial admin comes from `SEED_ADMIN_EMAIL` + `SEED_ADMIN_PASSWORD`, or not at all.**
+   No default and no generated password: with either variable missing the seeder prints why it
+   is skipping the admin and exits 0. The password is hashed with core's `hashPassword`, the
+   same call signup makes, so the seeded admin can actually log in. An admin who already exists
+   keeps their current password — the seeder never rewrites one it did not set.
+5. **The workspace variant also seeds the first workspace** (`SEED_WORKSPACE_NAME`, defaulting to
+   `"Default workspace"`) and makes the admin an `["admin", "member"]` member of it. The
+   workspace and its roles are seeded whether or not credentials were supplied — roles are
+   scoped to a workspace in this variant, so without one there is nowhere for them to exist.
+   Workspace names are not unique in the schema, so a re-run adopts the workspace it created
+   last time by name rather than making a second one.
+6. **`DATABASE_URL` and the `SEED_*` variables are read from the environment**, falling back to
+   the working directory's `.env` via `process.loadEnvFile()` — which never overrides a variable
+   the process was already given. No `dotenv` dependency is added to the consumer's project.
+
+The seeder does not own the catalog or the role definitions — `rbac.defaults.ts` does, and the
+seeder is one of its callers. See "Enforcement" below for why that matters and who the other
+callers are.
+
+## Enforcement
+
+**Three route tiers, checked at startup.** Every route is exactly one of `@Public()`,
+authenticated-only, or `@CheckAbility("<slug>")`; `route-tiers.ts` walks the route table at
+boot and a route carrying none of them **crashes the boot, naming itself** — a new admin route
+cannot ship open by omission. There is **no role-based bypass** anywhere in a combo: a role
+that carries no permissions confers no authority, whatever it is called.
+
+### `rbac.defaults.ts` — the one definition, and what mirrors it
+
+`variants/<variant>/src/rbac.defaults.ts` is the single source of truth, and every other piece
+reads it rather than keeping a copy:
+
+- **`PERMISSION_CATALOG`** — `noun:verb` slug → display name, description, group. One entry per
+  capability the admin API exposes: in the reference combo, 18 slugs in `base`, 19 in
+  `workspaces` (+`members:manage`); 9/10 in the other combos, which have no content domains.
+  The full slug list and the route → slug mapping live in `docs/backend-api.md`.
+- **`PermissionSlug`** = `keyof typeof PERMISSION_CATALOG`, and `@CheckAbility` takes **that
+  type, not `string`**. A route cannot demand a slug the catalog does not define, so "this
+  route requires something nothing can ever grant" is a compile error rather than a 403 nobody
+  can explain. Deployments may mint new slugs at runtime (`POST /auth/admin/permissions`
+  accepts any string), but those cannot gate a route this library ships.
+- **`DEFAULT_ROLES`** — `admin` carries the whole catalog, `member` carries nothing.
+- **`provisionDefaultRoles(db[, workspaceId])`** — writes catalog + default roles into a
+  database. `db` is typed structurally so it accepts either the client or a transaction
+  client. Every insert is `ON CONFLICT DO NOTHING` on the natural unique key, so it is
+  idempotent *and* safe to run concurrently, and nothing is ever deleted.
+
+Its callers: `src/seed.ts` (both variants), `src/workspace.repository.ts` (workspaces only), and
+the variant hooks in `test/`. The seeder is a *caller* of this definition, not its owner —
+which is what makes it impossible for what gets seeded and what the routes demand to drift.
+
+Resolution at request time (`AuthzGuard` → `PermissionCache` → `RbacRepository`) unions role
+permissions with direct grants and dedupes; `AbilityGuard` then checks the route's slug against
+the resulting CASL ability. Fail-closed in both directions: no resolved context, or the slug
+absent from it, is a 403.
+
+### Ungated on purpose
+
+Three workspace routes are deliberately not gated, and the catalog mints no slugs for them.
+`POST /workspaces` and `GET /workspaces` act *outside* every workspace — any authenticated user
+may create one or list their own, and gating them on a permission granted inside some other
+workspace would mean your first workspace could only be created by someone who already had one.
+`GET /workspaces/members` is gated on membership itself, which the guard chain has already
+proved; seeing who else is in a room you are in is not an administrative capability.
+
+### The lockout trap, and how it is closed
+
+In the workspaces variant `Role` is unique per workspace, so **a newly created workspace has no
+`Role` rows at all**. `POST /workspaces` makes its creator an `["admin", "member"]` member, but
+with no `Role`/`PermissionRole` rows in that workspace those are two names with nothing behind
+them, resolving to zero permissions. The moment routes enforce permissions, the creator is
+locked out of the workspace they just made — permanently, since every route that could fix it
+is one of the gated ones. The seeder does not help: it only provisions the workspace *it*
+creates.
+
+`WorkspaceRepository.create` therefore calls `provisionDefaultRoles(tx, workspace.id)` **inside
+the same transaction** that creates the workspace and the creator's membership, so a workspace
+never exists without the roles that make it administrable. `prove-cycle` proves it end to end:
+create a brand-new workspace, then exercise the administrative capabilities inside it as the
+person who created it. Remove the provisioning call and that section fails immediately — as
+does most of the rest of the workspaces run, since the proof's own admin gets their authority
+from a workspace they create.
+
+The second half of the same trap — an admin removing their own authority — is closed at the
+route layer: `cannot change your own roles` (admin roles route and the workspace
+member-roles route), `cannot block/deactivate/delete your own account`. Assigning to yourself
+is allowed; only the self-directed operations that could strand a deployment or a workspace
+without an administrator are refused.
+
+The base variant has no equivalent trap: roles are global, so the seeder is the only bootstrap
+and the only failure mode is "run the seeder", already spelled out in the CLI's postInstall
+notes (*"Nothing is authorized until it has run at least once"*).
+
+## Adding a combo (or migrating one)
+
+This section is for `kind: "api"` combos specifically — see `registry/admin-apps/README.md` or
+`registry/mobile-apps/README.md` if you're adding an admin console or mobile app instead; those
+follow the same byte-identical shared/variant rule but skip most of the steps below (no seeder,
+no enforcement table, no `prove-cycle` — a `scaffold`-mode combo is verified by generating it
+and running its own build/typecheck, not this file's proof harness).
+
+1. Split the existing flat `src/` into `shared/src` and `variants/base/src` by the byte-identical
+   rule above.
+2. Write `variants/workspaces/` against the reference combo's schema and endpoint shapes.
+3. Copy `scripts/*.mjs` from `nestjs-prisma` — they are combo-agnostic apart from the Prisma/
+   Drizzle migration command in `migrate.mjs`.
+4. Port `variants/<variant>/src/rbac.defaults.ts` first — the catalog, `PermissionSlug`,
+   `DEFAULT_ROLES` and `provisionDefaultRoles` — then `variants/<variant>/src/seed.ts` and the
+   `SEED_*` block of each variant's `.env.example`, following the contract in "The seeder" above.
+   Translating `provisionDefaultRoles` into that combo's ORM is the only real work; keep it
+   idempotent, transaction-client-friendly, and `ON CONFLICT DO NOTHING`.
+5. Put `@CheckAbility` on every admin route per the mapping in `docs/backend-api.md`, wire the
+   startup route-tier check, and — in the workspace variant — provision the default roles
+   inside the workspace-creation transaction. A combo that seeds a catalog it does not enforce
+   is worse than one that does neither: the admin console hides UI the server would have
+   allowed anyway.
+6. Add `sharedDir`, `variantsDir` and `variants: ["base", "workspaces"]` to the combo's entry in
+   `packages/cli/registry.json`, plus the `npm run seed` line in its `postInstall` notes — the CLI never
+   edits a consumer's `package.json`, so the script has to be spelled out for them, and the path
+   it points at is `<installPath>/src/seed.ts`, i.e. `tsx src/lib/auth/src/seed.ts` by default
+   (a combo's `src/**` lands under the install directory's own `src/`, not directly in it).
+7. `npm run typecheck && npm run prove-cycle` must pass for both variants, and `npm run seed`
+   must be safe to run twice against the same database.

package/registry/admin-apps/README.md

@@ -0,0 +1,71 @@
+# `registry/admin-apps/` — admin console templates
+
+Two products, each with the same `shared/` + `variants/{base,workspaces}` composition
+`registry/README.md` describes for backend combos — same byte-identical-hoisting rule, same "a
+file must not branch on which variant it's in" discipline — but a different `installMode`.
+
+| Product | `kind` in `packages/cli/registry.json` | Extracted from |
+|---|---|---|
+| `admin-react` | `admin` | `apps/admin-react` + `apps/admin-react-workspaces` |
+| `admin-nextjs` | `admin` | `apps/admin-nextjs` + `apps/admin-nextjs-workspaces` |
+
+## `installMode: "scaffold"`, not `"merge"`
+
+Backend combos merge a source fragment into an *existing* project's `src/lib/auth`. An admin
+console isn't a fragment — it's a whole standalone app. `simple-auth-kit add admin-react --into <dir>`
+writes `shared/` then `variants/<variant>/` **directly into `<dir>`**: `package.json`, `src/App.tsx`,
+everything. `packages/cli/lib/copy.ts`'s `SCAFFOLD_NEVER_COPY` (vs. the api-combo `NEVER_COPY`) reflects
+this: `package.json`/`tsconfig.json` are real, consumer-facing content here, not the registry's own
+dev wiring.
+
+`package.json`'s `name`/`description` are templated from `--name` (falling back to the target
+directory's basename) after the copy — see `installScaffold` in `packages/cli/simple-auth-kit.ts`.
+
+## `admin-react`: the clean case
+
+The two source apps decompose almost entirely into shared+variant deltas: ~75% of files are
+byte-identical, the rest (App.tsx, ability.ts, auth-client.ts, the stores, and the
+countries/customers/languages/users pages) carry small, mechanical workspace-scoping diffs —
+`observer()` wrapping, `activeWorkspaceId` folded into query keys, an `X-Workspace-Id`-aware
+`authClient` resolver. `workspace-switcher.tsx`, `CreateWorkspaceDialog.tsx`, `workspace-store.ts`,
+and `MembersPage.tsx` are workspaces-only additions; `AddRolePage.tsx`/`EditRolePage.tsx`/
+`EditUserPage.tsx` are base-only (workspaces folds editing into dialogs instead of separate
+routes). Dependencies are otherwise identical between the two source apps' `package.json`.
+
+## `admin-nextjs`: a deliberate trust-model split, not an oversight
+
+This one doesn't decompose as cleanly, and that's kept rather than forced. Only about half the
+shared-path pages are safely shareable; the rest (roles, permissions, users, dashboard, audit-log,
+account, login) are independently-implemented pages with real behavioral differences, not just
+superficial variant deltas — written to both `variants/base` and `variants/workspaces` unmodified,
+per the byte-identical-or-nothing rule.
+
+The one worth calling out explicitly: **`base` and `workspaces` use different route-guarding trust
+models**, and that's a deliberate, permanent difference, not something a future pass should
+"fix" by unifying them:
+
+- `variants/base` ships `src/proxy.ts` + `src/auth.ts` + `src/app/api/auth/[...nextauth]/route.ts`
+  — NextAuth v5 edge middleware, re-checking the access token against `GET /auth/me` on every
+  protected navigation, server-side, before the page ever renders.
+- `variants/workspaces` has no NextAuth at all. It re-checks the session client-side
+  (`AuthStore.verifySession()`, called on every route change) — a real but different guarantee:
+  a revoked session is caught at the *next* navigation, same as `base`, but the check itself runs
+  in the browser, not at the edge, since this variant never adopted NextAuth's server-side model.
+
+Neither is a bug. `base`'s model is stronger (a compromised client can't be made to skip the
+check); `workspaces`' is what was actually built and ships a real, tested guarantee of its own.
+Don't try to backport NextAuth into `variants/workspaces` to "match" `base`, and don't strip it out
+of `variants/base` to "simplify" — that would be changing the security model of a generated app as
+a side effect of a registry refactor, which is exactly the kind of false unification the
+byte-identical rule exists to prevent.
+
+`variants/base` also ships 36 shadcn UI primitives `variants/workspaces` doesn't (a larger kit was
+generated for it and never pruned) — harmless, just asymmetric file counts between the two
+variants; not evidence of drift to reconcile.
+
+## `@simple-auth-kit/auth-client`
+
+Both products' `package.json` declare `"@simple-auth-kit/auth-client": "^1.0.0"`, resolved from
+the published package on npm: https://www.npmjs.com/package/@simple-auth-kit/auth-client. A
+`scaffold`-mode generated app stands alone with a plain `npm install` — no monorepo/pnpm
+workspace required.

package/registry/admin-apps/nextjs/shared/components.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "radix-nova",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "registries": {}
+}

package/registry/admin-apps/nextjs/shared/next.config.ts

@@ -0,0 +1,9 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  reactStrictMode: true,
+  // Don't auto-generate AGENTS.md/CLAUDE.md into the app directory on every dev/build run.
+  agentRules: false,
+};
+
+export default nextConfig;

package/registry/admin-apps/nextjs/shared/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/registry/admin-apps/nextjs/shared/src/app/globals.css

@@ -0,0 +1,159 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+
+/* `next-themes` toggles a `.dark` class on `<html>` — drive `dark:` from that instead of Tailwind v4's default `prefers-color-scheme` media query. */
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-border: var(--border);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --font-heading: var(--font-sans);
+  --font-sans: var(--font-sans);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-chart-5: var(--chart-5);
+  --color-chart-4: var(--chart-4);
+  --color-chart-3: var(--chart-3);
+  --color-chart-2: var(--chart-2);
+  --color-chart-1: var(--chart-1);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-accent: var(--accent);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --radius-sm: calc(var(--radius) * 0.6);
+  --radius-md: calc(var(--radius) * 0.8);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) * 1.4);
+  --radius-2xl: calc(var(--radius) * 1.8);
+  --radius-3xl: calc(var(--radius) * 2.2);
+  --radius-4xl: calc(var(--radius) * 2.6);
+}
+
+:root {
+  --muted: oklch(0.967 0.001 286.375);
+  --muted-foreground: oklch(0.552 0.016 285.938);
+  --border: oklch(0.92 0.004 286.32);
+  --primary: oklch(0.21 0.006 285.885);
+  --primary-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --destructive-foreground: oklch(0.985 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.141 0.005 285.823);
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.141 0.005 285.823);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.141 0.005 285.823);
+  --secondary: oklch(0.967 0.001 286.375);
+  --secondary-foreground: oklch(0.21 0.006 285.885);
+  --accent: oklch(0.967 0.001 286.375);
+  --accent-foreground: oklch(0.21 0.006 285.885);
+  --input: oklch(0.92 0.004 286.32);
+  --ring: oklch(0.705 0.015 286.067);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --radius: 0.625rem;
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.141 0.005 285.823);
+  --sidebar-primary: oklch(0.21 0.006 285.885);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.967 0.001 286.375);
+  --sidebar-accent-foreground: oklch(0.21 0.006 285.885);
+  --sidebar-border: oklch(0.92 0.004 286.32);
+  --sidebar-ring: oklch(0.705 0.015 286.067);
+}
+
+/* Applied by `next-themes` when the resolved theme (explicit choice, or `system` following the OS) is dark. */
+.dark {
+    --background: oklch(0.141 0.005 285.823);
+    --foreground: oklch(0.985 0 0);
+    --card: oklch(0.21 0.006 285.885);
+    --card-foreground: oklch(0.985 0 0);
+    --popover: oklch(0.21 0.006 285.885);
+    --popover-foreground: oklch(0.985 0 0);
+    --primary: oklch(0.92 0.004 286.32);
+    --primary-foreground: oklch(0.21 0.006 285.885);
+    --secondary: oklch(0.274 0.006 286.033);
+    --secondary-foreground: oklch(0.985 0 0);
+    --muted: oklch(0.274 0.006 286.033);
+    --muted-foreground: oklch(0.705 0.015 286.067);
+    --accent: oklch(0.274 0.006 286.033);
+    --accent-foreground: oklch(0.985 0 0);
+    --destructive: oklch(0.704 0.191 22.216);
+    --destructive-foreground: oklch(0.985 0 0);
+    --border: oklch(1 0 0 / 10%);
+    --input: oklch(1 0 0 / 15%);
+    --ring: oklch(0.552 0.016 285.938);
+    --chart-1: oklch(0.488 0.243 264.376);
+    --chart-2: oklch(0.696 0.17 162.48);
+    --chart-3: oklch(0.769 0.188 70.08);
+    --chart-4: oklch(0.627 0.265 303.9);
+    --chart-5: oklch(0.645 0.246 16.439);
+    --sidebar: oklch(0.21 0.006 285.885);
+    --sidebar-foreground: oklch(0.985 0 0);
+    --sidebar-primary: oklch(0.488 0.243 264.376);
+    --sidebar-primary-foreground: oklch(0.985 0 0);
+    --sidebar-accent: oklch(0.274 0.006 286.033);
+    --sidebar-accent-foreground: oklch(0.985 0 0);
+    --sidebar-border: oklch(1 0 0 / 10%);
+    --sidebar-ring: oklch(0.552 0.016 285.938);
+}
+
+
+@theme {
+  --animate-caret-blink: caret-blink 1.25s ease-out infinite;
+  --animate-spin-slow: spin-slow 3s linear infinite;
+  --animate-spin-reverse: spin-reverse 1.5s linear infinite;
+  --animate-progress-indeterminate: progress-indeterminate 1.5s ease-in-out infinite;
+
+  @keyframes caret-blink {
+    0%, 70%, 100% { opacity: 1; }
+    20%, 50% { opacity: 0; }
+  }
+  @keyframes spin-slow {
+    from { transform: rotate(0deg); }
+    to { transform: rotate(360deg); }
+  }
+  @keyframes spin-reverse {
+    from { transform: rotate(360deg); }
+    to { transform: rotate(0deg); }
+  }
+  @keyframes progress-indeterminate {
+    0% { transform: translateX(-100%); }
+    100% { transform: translateX(400%); }
+  }
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+  html {
+    @apply font-sans;
+  }
+}

package/registry/admin-apps/nextjs/shared/src/app/signup/page.tsx

@@ -0,0 +1,72 @@
+"use client";
+
+import { observer } from "mobx-react-lite";
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { useState, type FormEvent } from "react";
+import { Alert } from "@/components/ui/alert";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { errorMessage } from "@/lib/error";
+import { useAuthStore } from "@/lib/stores/store-context";
+
+export default observer(function SignupPage() {
+  const store = useAuthStore();
+  const router = useRouter();
+
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+
+  async function handleSubmit(event: FormEvent) {
+    event.preventDefault();
+    setError(null);
+    setSubmitting(true);
+    try {
+      await store.signup({ email, password });
+      router.push("/");
+    } catch (err) {
+      setError(errorMessage(err));
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  return (
+    <div className="flex min-h-screen items-center justify-center p-4">
+      <Card className="w-full max-w-sm">
+        <CardHeader>
+          <CardTitle>Create an account</CardTitle>
+          <CardDescription>
+            New accounts start with no administrative permissions. An admin can grant you some once you&apos;ve signed up.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="flex flex-col gap-4">
+          {error && <Alert variant="destructive">{error}</Alert>}
+          <form className="flex flex-col gap-4" onSubmit={handleSubmit}>
+            <div className="flex flex-col gap-1.5">
+              <Label htmlFor="email">Email</Label>
+              <Input id="email" type="email" required value={email} onChange={(e) => setEmail(e.target.value)} placeholder="you@example.com" />
+            </div>
+            <div className="flex flex-col gap-1.5">
+              <Label htmlFor="password">Password</Label>
+              <Input id="password" type="password" required minLength={8} value={password} onChange={(e) => setPassword(e.target.value)} />
+            </div>
+            <Button type="submit" disabled={submitting}>
+              {submitting ? "Creating account…" : "Sign up"}
+            </Button>
+          </form>
+          <p className="text-center text-sm text-muted-foreground">
+            Already have an account?{" "}
+            <Link href="/login" className="font-medium text-foreground underline underline-offset-2">
+              Sign in
+            </Link>
+          </p>
+        </CardContent>
+      </Card>
+    </div>
+  );
+});