@augmenting-integrations/create-spoke 8.4.1 → 8.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@augmenting-integrations/create-spoke",
-  "version": "8.4.1",
+  "version": "8.5.0",
   "description": "Scaffold a new product subdomain (spoke) for an augint-* tenant. Generates a Next 16 + Auth.js v5 app with TenantConfig wired up, library-owned route handlers, a Prisma canonical schema fragment, and a deployable template.yaml + GitHub workflow. Single command: pnpm dlx @augmenting-integrations/create-spoke my-spoke.",
   "license": "MIT",
   "publishConfig": {

package/templates/README.md.tmpl

@@ -1,17 +1,18 @@
 # __SPOKE_NAME__
 
 Generated by `@augmenting-integrations/create-spoke`. This is a Next.js 16
-product subdomain ("spoke") inside an augint tenant. Auth, billing, and
-admin route handlers come from `@augmenting-integrations/*` libraries —
-your job is the product surface in `src/app/` plus any product-specific
-Prisma models.
+product subdomain ("spoke") inside an augint tenant. Auth, billing,
+settings, invitations, and admin route handlers all come from
+`@augmenting-integrations/*` libraries — your job is the product surface
+in `src/app/` plus any product-specific Prisma models.
 
 ## Local dev
 
 ```bash
 cp .env.example .env
-# fill in the tenant identity values; AWS creds may stay blank for local dev
+# fill in tenant identity values; AWS creds may stay blank for local dev
 pnpm install
+pnpm exec augint validate-spoke   # validates prisma/schema.prisma against app.manifest.json
 pnpm dev
 ```
 
@@ -19,29 +20,63 @@ You should see `Not signed in.` on `/`. Sign-in flow requires a working
 apex (the apex app is the only OAuth callback in the tenant — it sets the
 shared cookie and redirects you back).
 
+## The manifest is the source of truth
+
+Edit `app.manifest.json` to change the spoke's identity, access policy,
+feature enablement, or data plane. The manifest is read at build time by
+`src/lib/auth.ts` (drives the access policy) and at deploy time by the
+shared deploy tooling (drives the registry registration). You should not
+need to thread the same values through `.env` + workflow files + Studio
+forms — that drift is the bug class this contract closes.
+
 ## Per-tenant adoption checklist
 
-1. **Tenant identity** in `.env` — replace `tenant.example.com` with your real apex.
-2. **AWS resources** — `AUTH_SECRET_ARN`, `DB_SECRET_ARN`, Cognito ids, etc. come from your tenant infra stack (the same SSM params the apex reads).
-3. **Prisma** — `prisma/schema.prisma` ships with canonical User/Invitation/PaymentMethod/CreditTransaction. Add your product models below the marker comment.
-4. **Brand** — drop a `config/brand.json` in if you want this spoke's name in the chrome.
-5. **App registry** — register this spoke in your apex's DynamoDB app registry (slug `__SPOKE_SLUG__`, subdomain `__SPOKE_SUBDOMAIN__`).
+1. **Manifest** (`app.manifest.json`) — edit `tenantSlug`, `appSlug`,
+   `subdomain`, `displayName`, `navOrder`, `access.requiredIdentityGroups`,
+   and `features.*`.
+2. **`.env`** — fill in `AUTH_SECRET_ARN`, `DB_SECRET_ARN`, Cognito ids,
+   etc. These come from your tenant infra stack.
+3. **Prisma** — `prisma/schema.prisma` ships with canonical User /
+   Invitation / PaymentMethod / CreditTransaction / ActivityLog. Add
+   your product-domain models below the marker comment. Run
+   `pnpm exec augint validate-spoke` to confirm the canonical fragments
+   satisfy the contract implied by your manifest's `features.*`.
+4. **Brand** — drop a `config/brand.json` in if you want this spoke's
+   name in the chrome.
 
 ## Deploy
 
-This scaffold ships only the application code. Infrastructure (CloudFront
-distribution, Lambda runtime, Aurora cluster + RDS Proxy, migrate-runner
-Lambda) is per-tenant and varies; copy the `template.yaml` from your
-tenant's other spokes (e.g. the example leads-marketplace) and edit the
-slug + subdomain.
+The shared workflow + `template.yaml` provision the Lambda + CloudFront +
+DNS + IAM. The deploy step invokes:
+
+```bash
+pnpm exec augint validate-spoke
+pnpm build
+pnpm exec augint package-next-lambda
+```
+
+The `package-next-lambda` command does the Next standalone staging, the
+pnpm symlink flatten, the Prisma `.prisma` hoist, and the `.pnpm` purge
+that every spoke needs. This logic lives in the shared
+`@augmenting-integrations/deploy-tools` package -- do NOT copy it back
+into your `.github/workflows/deploy.yaml`.
+
+Spoke kernel infra (Lambda + CloudFront + DNS + IAM + optional Aurora
+data plane) is documented in
+`augint-common-web/docs/spoke-kernel.md`. The current generated
+`template.yaml` mirrors the leads-marketplace reference; over time it
+will be replaced by a nested-stack consumer of the shared kernel
+provisioned in `<tenant>-infra`.
 
 ## What you can NOT customize without diverging from the library
 
 - Canonical schema fields (`User.credit_balance`, `CreditTransaction.type`,
   `PaymentMethod.stripe_payment_method_id`, etc.). The library's billing
-  factory assumes these.
-- `/api/billing/*` URL paths (the client widgets bake them in).
+  factory assumes these. The validator catches drift before deploy.
+- `/api/billing/*`, `/api/auth/me`, `/api/invitations/[token]`,
+  `/api/settings/*` URL paths -- the library and the client widgets bake
+  them in.
 - Auth.js v5 + Cognito as the provider chain.
 
-For product-specific routes (`/api/leads`, `/api/quotes`, `/api/products`),
+For product-specific routes (`/api/leads`, `/api/quotes`, `/api/widgets`),
 add them under `src/app/api/` — they're yours to design.

package/templates/app.manifest.json.tmpl

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": 1,
+  "tenantSlug": "TENANT_PLACEHOLDER",
+  "appSlug": "__SPOKE_SLUG__",
+  "role": "spoke",
+  "subdomain": "__SPOKE_SUBDOMAIN__",
+  "displayName": "__SPOKE_NAME__",
+  "navOrder": 10,
+  "access": {
+    "requiredIdentityGroups": []
+  },
+  "features": {
+    "billing": true,
+    "settings": true,
+    "invitations": true,
+    "impersonation": true
+  },
+  "dataPlane": {
+    "type": "app-aurora",
+    "migrations": true
+  }
+}

package/templates/package.json.tmpl

@@ -16,6 +16,7 @@
     "@augmenting-integrations/billing": "^8.0.0",
     "@augmenting-integrations/brand": "^8.0.0",
     "@augmenting-integrations/db-secret-loader": "^8.0.0",
+    "@augmenting-integrations/platform": "^8.0.0",
     "@augmenting-integrations/themes": "^8.0.0",
     "@augmenting-integrations/ui": "^8.0.0",
     "@prisma/client": "^6.0.0",

package/templates/src/app/Providers.tsx.tmpl

@@ -6,7 +6,7 @@ import { SessionProvider } from "@augmenting-integrations/ui";
 import {
   TenantProvider,
   type TenantPublicConfig,
-} from "@augmenting-integrations/auth/client";
+} from "@augmenting-integrations/platform/client";
 
 export function Providers({
   children,

package/templates/src/app/api/admin/users/[id]/impersonate/route.ts.tmpl

@@ -1,13 +1,13 @@
 import { createImpersonateHandlers } from "@augmenting-integrations/auth/server";
 import { auth } from "@/lib/auth";
-import { getDb } from "@/lib/db";
-import { getOrCreateAppUser } from "@/lib/users";
+import { getAuthHandlersDb } from "@/platform/repositories";
+import { getMeAppUser } from "@/platform/app-user";
 
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 
 export const { POST, DELETE } = createImpersonateHandlers({
   auth,
-  getDb: getDb as never,
-  getOrCreateAppUser: getOrCreateAppUser as never,
+  getDb: getAuthHandlersDb,
+  getOrCreateAppUser: getMeAppUser,
 });

package/templates/src/app/api/auth/me/route.ts.tmpl

@@ -1,13 +1,13 @@
 import { createMeHandler } from "@augmenting-integrations/auth/server";
 import { auth } from "@/lib/auth";
-import { getDb } from "@/lib/db";
-import { getOrCreateAppUser } from "@/lib/users";
+import { getAuthHandlersDb } from "@/platform/repositories";
+import { getMeAppUser } from "@/platform/app-user";
 
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 
 export const { GET } = createMeHandler({
   auth,
-  getDb: getDb as never,
-  getOrCreateAppUser: getOrCreateAppUser as never,
+  getDb: getAuthHandlersDb,
+  getOrCreateAppUser: getMeAppUser,
 });

package/templates/src/app/api/invitations/[token]/route.ts.tmpl

@@ -1,7 +1,7 @@
 import { createInvitationHandlers } from "@augmenting-integrations/auth/server";
-import { getDb } from "@/lib/db";
+import { getAuthHandlersDb } from "@/platform/repositories";
 
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 
-export const { GET, POST } = createInvitationHandlers({ getDb: getDb as never });
+export const { GET, POST } = createInvitationHandlers({ getDb: getAuthHandlersDb });

package/templates/src/app/layout.tsx.tmpl

@@ -5,7 +5,7 @@ import {
   THEME_VARIANT_COOKIE_KEY,
 } from "@augmenting-integrations/themes";
 import { ThemeBootScript } from "@augmenting-integrations/ui";
-import { TenantBootScript, publicSubset } from "@augmenting-integrations/auth/server";
+import { TenantBootScript, publicSubset } from "@augmenting-integrations/platform/server";
 import { auth, tenant } from "@/lib/auth";
 import { Providers } from "./Providers";
 import "./globals.css";

package/templates/src/lib/auth.ts.tmpl

@@ -1,5 +1,19 @@
-import { createAuth, loadTenantConfig } from "@augmenting-integrations/auth/server";
+import { createAuth } from "@augmenting-integrations/auth/server";
+import { loadTenantConfig } from "@augmenting-integrations/platform/server";
+import { validateManifest } from "@augmenting-integrations/platform/manifest";
 import { getSecret } from "@augmenting-integrations/aws/server";
+import manifestJson from "../../app.manifest.json";
+
+// app.manifest.json is the local source of truth for slug / subdomain /
+// access policy / feature enablement. Validate at module init so a bad
+// manifest fails the deploy loudly with the field-by-field error list.
+const manifestResult = validateManifest(manifestJson);
+if (!manifestResult.ok) {
+  throw new Error(
+    `app.manifest.json failed validation: ${manifestResult.errors.map((e) => `${e.path}: ${e.message}`).join("; ")}`,
+  );
+}
+export const manifest = manifestResult.value;
 
 // Single tenant configuration source.
 export const tenant = loadTenantConfig({ role: "spoke" });
@@ -12,4 +26,7 @@ export const { handlers, auth, signIn, signOut } = createAuth({
   tenant,
   authedRoutePrefixes: ["/"],
   authSecret,
+  appAccess: {
+    requiredIdentityGroups: manifest.access.requiredIdentityGroups,
+  },
 });

package/templates/src/lib/billing.ts.tmpl

@@ -1,11 +1,14 @@
 import { createBillingHandlers } from "@augmenting-integrations/billing/server";
 import { auth } from "./auth.js";
-import { getDb } from "./db.js";
-import { getOrCreateAppUser } from "./users.js";
+import { getBillingDb } from "../platform/repositories.js";
+import { getBillingAppUser } from "../platform/app-user.js";
 
 // One factory call. Each /api/billing/* route file re-exports from this.
+// The platform adapters keep this wiring free of `as never` casts; if the
+// canonical schema drifts, the schema validator (augint validate-spoke)
+// fails CI before this file is reached.
 export const billingHandlers = createBillingHandlers({
   auth,
-  getDb: getDb as never,
-  getOrCreateAppUser: getOrCreateAppUser as never,
+  getDb: getBillingDb,
+  getOrCreateAppUser: getBillingAppUser,
 });

package/templates/src/lib/users.ts.tmpl

@@ -1,5 +1,10 @@
-import { createGetOrCreateAppUser } from "@augmenting-integrations/auth/server";
-import { getDb } from "./db.js";
+import {
+  createGetOrCreateAppUser,
+  type AppUserWithImpersonation,
+} from "@augmenting-integrations/auth/server";
+import type { User } from "@prisma/client";
+
+import { getJitDb } from "../platform/repositories.js";
 
 // Default $500 for admins/owners, $100 for everyone else. Tune per spoke.
 function computeCreditBalance(role: string): number {
@@ -7,8 +12,10 @@ function computeCreditBalance(role: string): number {
   return 100;
 }
 
-export const getOrCreateAppUser = createGetOrCreateAppUser({
-  db: getDb,
+export type AppUser = AppUserWithImpersonation<User>;
+
+export const getOrCreateAppUser = createGetOrCreateAppUser<User>({
+  db: getJitDb,
   defaultRole: "member",
   computeCreditBalance,
   adminEmails: (process.env.ADMIN_EMAILS ?? "")
@@ -17,5 +24,3 @@ export const getOrCreateAppUser = createGetOrCreateAppUser({
     .filter(Boolean),
   extraCreateFields: { is_active: true, must_change_password: false },
 });
-
-export type { AppUser } from "@augmenting-integrations/auth/server";

package/templates/src/platform/app-user.ts.tmpl

@@ -0,0 +1,22 @@
+import "server-only";
+
+import type { Session } from "next-auth";
+import type { BillingUser } from "@augmenting-integrations/billing/server";
+import type { MeAppUser } from "@augmenting-integrations/auth/server";
+
+import { getOrCreateAppUser } from "../lib/users.js";
+
+// Platform user adapter. Bridges the spoke's getOrCreateAppUser (which
+// returns the full generated User row) to the narrow shapes library
+// handler factories consume (MeAppUser, BillingUser).
+//
+// Split from src/platform/repositories.ts to avoid an import cycle with
+// src/lib/users.ts (which imports the DB adapter). See repositories.ts
+// for the schema-contract rationale.
+
+export const getMeAppUser: (session: Session) => Promise<MeAppUser> = async (session) =>
+  (await getOrCreateAppUser(session)) as unknown as MeAppUser;
+
+export const getBillingAppUser: (session: Session) => Promise<BillingUser> = async (
+  session,
+) => (await getOrCreateAppUser(session)) as unknown as BillingUser;

package/templates/src/platform/repositories.ts.tmpl

@@ -0,0 +1,31 @@
+import "server-only";
+
+import type { BillingDb } from "@augmenting-integrations/billing/server";
+import type {
+  AuthHandlersDb,
+  PrismaLikeClient,
+} from "@augmenting-integrations/auth/server";
+import type { User } from "@prisma/client";
+
+import { getDb } from "../lib/db.js";
+
+// Platform DB adapter. Bridges the generated PrismaClient to the structural
+// shapes library handler factories consume (BillingDb, AuthHandlersDb,
+// PrismaLikeClient<User>). The boundary lives here once; route handlers and
+// factory wiring stay free of `as never` and similar unsafe casts.
+//
+// The library cannot import generated Prisma types -- it would have to know
+// every spoke's schema. Instead it declares minimal structural row shapes
+// and method signatures. Both sides agree on the canonical contract
+// (User / Invitation / PaymentMethod / CreditTransaction / ActivityLog).
+// The schema validator (`pnpm exec augint validate-spoke`) checks it at
+// CI time so the contract cannot silently drift.
+
+export const getBillingDb: () => Promise<BillingDb> = async () =>
+  (await getDb()) as unknown as BillingDb;
+
+export const getAuthHandlersDb: () => Promise<AuthHandlersDb> = async () =>
+  (await getDb()) as unknown as AuthHandlersDb;
+
+export const getJitDb: () => Promise<PrismaLikeClient<User>> = async () =>
+  (await getDb()) as unknown as PrismaLikeClient<User>;