@augmenting-integrations/create-spoke 8.3.0 → 8.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Augmenting Integrations LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @augmenting-integrations/create-spoke
+
+Scaffold a new product subdomain (spoke) for an augint-\* tenant.
+
+```bash
+pnpm dlx @augmenting-integrations/create-spoke my-spoke
+pnpm dlx @augmenting-integrations/create-spoke my-spoke --subdomain=foo --slug=bar
+```
+
+## What gets generated
+
+A Next.js 16 + Auth.js v5 app pre-wired for the augint tenant ecosystem:
+
+- `loadTenantConfig({ role: "spoke" })` in `src/lib/auth.ts` (single env-var read)
+- `<TenantBootScript>` + `<TenantProvider>` mounted in the root layout
+- Library-owned route handlers for `/api/auth/me`, `/api/billing/*`,
+  `/api/invitations/[token]`, and `/api/admin/users/[id]/impersonate` —
+  each is a 2-line re-export from `@augmenting-integrations/auth/server` or
+  `@augmenting-integrations/billing/server`
+- Canonical Prisma fragments (`User`, `Invitation`, `PaymentMethod`,
+  `CreditTransaction`, `ActivityLog`) in `prisma/schema.prisma` — your
+  product models live below the marker comment
+- `prisma/seed.mjs` with the `STAGE=staging` gate so seeds never fire
+  against a production database
+
+## What you still have to do per-tenant
+
+The generated app is portable; the AWS infra around it is per-tenant:
+
+- Provision your tenant's Cognito user pool, hosted zone, app registry
+  table, secrets, GitHub OIDC role (copy `template.yaml` from an existing
+  spoke in the same tenant — see `augint-example-leads-marketplace` for
+  the reference).
+- Register this spoke in the apex's DynamoDB app registry (slug, subdomain,
+  displayName, navOrder) so it shows up in every other spoke's AppShell.
+
+## Bringing your product
+
+The kernel ships only auth/billing/admin route handlers. Product routes
+(`/api/leads`, `/api/quotes`, `/api/widgets`) are yours to design under
+`src/app/api/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@augmenting-integrations/create-spoke",
-  "version": "8.3.0",
+  "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": {
@@ -15,15 +15,15 @@
     "templates",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsup",
-    "clean": "rm -rf dist",
-    "test": "vitest run --passWithNoTests"
-  },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
     "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "test": "vitest run --passWithNoTests"
   }
-}
+}

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>;

package/templates/.env.example.tmpl

@@ -1,25 +0,0 @@
-# Tenant identity (everything else flows from these)
-APP_DOMAIN=__SPOKE_SUBDOMAIN__.tenant.example.com
-APP_SLUG=__SPOKE_SLUG__
-APEX_DOMAIN=tenant.example.com
-AUTH_COOKIE_DOMAIN=.tenant.example.com
-AUTH_ALLOWED_PARENT_DOMAIN=.tenant.example.com
-
-# AWS resources (typically pulled from SSM in deployed Lambda; local dev only)
-AWS_REGION=us-east-1
-AUTH_SECRET_ARN=
-AUTH_COGNITO_ID=
-AUTH_COGNITO_ISSUER=
-DB_SECRET_ARN=
-DB_HOST=
-DB_NAME=
-APP_REGISTRY_TABLE=
-STRIPE_SECRET_ARN=
-STRIPE_WEBHOOK_SECRET_ARN=
-
-# Comma-separated emails auto-promoted to role=admin on first sign-in
-ADMIN_EMAILS=
-
-# Local-dev fallback for testing without Secrets Manager
-AUTH_SECRET=dev-only-fallback-not-for-prod
-NODE_ENV=development