@percepta/create 3.1.4 → 3.2.0

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "@percepta/create",
-  "version": "3.1.4",
+  "version": "3.2.0",
   "description": "Scaffold a new Mosaic package",
-  "type": "module",
+  "keywords": [
+    "cli",
+    "create",
+    "mosaic",
+    "nextjs",
+    "percepta",
+    "scaffold",
+    "template"
+  ],
+  "license": "MIT",
   "bin": {
     "create": "./dist/index.js"
   },
@@ -11,6 +20,10 @@
     "templates",
     "template-versions.json"
   ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
@@ -24,36 +37,22 @@
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^24.1.0",
     "@types/validate-npm-package-name": "^4.0.2",
-    "tsup": "^8.4.0",
-    "typescript": "^5.7.3",
     "vitest": "^4.0.0",
-    "@percepta/build": "0.4.1"
+    "@percepta/build": "0.5.1"
   },
   "engines": {
     "node": ">=18.0.0"
   },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "create",
-    "template",
-    "nextjs",
-    "mosaic",
-    "percepta",
-    "scaffold",
-    "cli"
-  ],
-  "license": "MIT",
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "create:local": "pnpm build && node dist/index.js",
-    "dev": "tsup src/index.ts --format esm --watch",
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "clean": "rimraf dist",
     "typecheck": "tsc --noEmit",
-    "sync-template": "tsx scripts/sync-template.ts",
-    "template:tag": "tsx scripts/template-tag.ts",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:template": "bash scripts/test-template.sh"
+    "test:template": "bash scripts/test-template.sh",
+    "create:local": "pnpm build && node dist/index.js",
+    "sync-template": "tsx scripts/sync-template.ts",
+    "template:tag": "tsx scripts/template-tag.ts"
   }
 }

package/template-versions.json

@@ -1,4 +1,4 @@
 {
-  "webapp": "1.0.0",
+  "webapp": "1.1.0",
   "library": "1.0.0"
 }

package/templates/monorepo/.github/workflows/access-control.yml

@@ -0,0 +1,38 @@
+name: Access Control
+
+on:
+  pull_request: {}
+
+env:
+  PNPM_VERSION: 10.x
+
+jobs:
+  access-control:
+    name: Merge and Validate Access Schema
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup PNPM
+        uses: pnpm/action-setup@v4
+        with:
+          version: ${{ env.PNPM_VERSION }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Merge and validate access schema
+        run: |
+          if find packages -path '*/src/access/access.manifest.ts' | grep -q .; then
+            pnpm access:validate
+          else
+            echo "No app access manifests found yet; skipping access schema validation."
+          fi

package/templates/monorepo/README.md

@@ -1,6 +1,6 @@
 # __APP_TITLE__
 
-A monorepo powered by [pnpm workspaces](https://pnpm.io/workspaces).
+A customer monorepo powered by [pnpm workspaces](https://pnpm.io/workspaces).
 
 ## Getting Started
 
@@ -11,6 +11,12 @@ pnpm install
 # Run development mode for all packages
 pnpm dev
 
+# Set up local services, access-control topology, databases, and seed users
+pnpm run setup
+
+# Merge and validate customer access-control schema
+pnpm access:validate
+
 # Build all packages
 pnpm build
 
@@ -24,10 +30,43 @@ pnpm lint
 ## Structure
 
 ```
+access/              # Customer-level SpiceDB fixtures and generated merge artifacts
+auth/                # Shared Better Auth users/groups package for this customer
 packages/
-  └── your-package/    # Add your packages here
+  └── your-package/  # Application and library packages
+```
+
+## Access Control
+
+Application builders define app-local Zed schemas in each package's
+`src/access/` directory. The root access scripts merge those schemas with the
+shared `core/*` schema and apply customer-owned grants such
+as application owners, application members, and bootstrap customer admins.
+
+```bash
+pnpm access:merge
+pnpm access:validate
+pnpm access:apply
 ```
 
+PR CI merges the customer schema and runs static schema/manifest validation.
+`access:apply` is reserved for trusted deploy jobs and should run once per
+target environment with that environment's SpiceDB credentials.
+
+For local development, copy the example fixture files in `access/`, fill in
+customer-global user/group IDs from `auth/`, then run:
+
+```bash
+pnpm access:seed-grants
+pnpm access:bootstrap-customer-admin -- --subject core/user:<user-id>
+```
+
+## Shared Auth
+
+The `auth/` workspace owns the customer-global Better Auth schema, including
+`users`, `groups`, and `group_members`. Apps should consume this shared
+identity layer instead of creating app-local users or groups.
+
 ## Adding a new package
 
 Create a new directory in `packages/` with its own `package.json`:

package/templates/monorepo/access/README.md

@@ -0,0 +1,39 @@
+# Customer Access Control
+
+This directory owns the customer-level SpiceDB deployment surface:
+
+- `pnpm access:merge` combines every app's `src/access/schema.zed` with the shared core schema.
+- `pnpm access:validate` validates the merged schema and app manifests.
+- `pnpm access:apply` writes the merged schema and stable application topology links to SpiceDB.
+- `pnpm access:seed-grants` and `pnpm access:apply-bootstrap-grants` apply YAML fixture grants.
+- `pnpm access:bootstrap-customer-admin` creates the first direct customer-admin grant.
+- `pnpm access:reconcile` repairs SpiceDB from an explicit local projection.
+
+The source of truth for app-specific permissions remains the app's authored Zed
+file. This package owns only customer-level composition and customer-admin
+bootstrap.
+
+## Local Bootstrap
+
+```bash
+pnpm access:merge
+pnpm access:validate
+cp access/bootstrap-grants.yaml.example access/bootstrap-grants.yaml
+pnpm access:apply-local
+pnpm access:apply-bootstrap-grants -- --endpoint localhost:50051 --insecure --key dev-spicedb-token
+```
+
+Use `core/user:<users.id>` and `core/group:<groups.id>#member` subjects. The IDs
+come from the shared `auth/` package tables, not from per-app user tables.
+
+## Production Promotion
+
+Run `pnpm access:validate` in PR CI. Run `pnpm access:apply` only from trusted deploy jobs
+with the target environment's SpiceDB credentials. Promote the same merged
+schema artifact through environments before app code that depends on new
+relations or permissions.
+
+Use expand/contract for destructive changes: add the new shape, deploy
+dual-write/dual-read code, backfill with idempotent relationship writes,
+reconcile, then remove old relationships and schema definitions in a later
+deploy.

package/templates/monorepo/access/bootstrap-grants.yaml.example

@@ -0,0 +1,9 @@
+# Production bootstrap grants for first deploy / break-glass access.
+# Copy to bootstrap-grants.yaml, replace IDs with auth.users.id values, then run:
+#   pnpm access:apply-bootstrap-grants
+customerAdmins:
+  - userId: "00000000-0000-0000-0000-000000000000"
+
+applications: []
+appRoles: []
+resourceRelations: []

package/templates/monorepo/access/dev-grants.yaml.example

@@ -0,0 +1,19 @@
+# Local development grants. Copy to dev-grants.yaml and replace IDs with rows
+# from the shared auth.users / auth.groups tables.
+customerAdmins:
+  - userId: "00000000-0000-0000-0000-000000000000"
+
+applications:
+  - appNamespace: "people_app"
+    owners:
+      - userId: "00000000-0000-0000-0000-000000000000"
+    members:
+      - groupId: "11111111-1111-1111-1111-111111111111"
+
+appRoles:
+  - appNamespace: "people_app"
+    role: "admin"
+    subjects:
+      - groupId: "11111111-1111-1111-1111-111111111111"
+
+resourceRelations: []

package/templates/monorepo/access/dev-groups.yaml.example

@@ -0,0 +1,8 @@
+# Future fixture source for the auth-owned groupSync adapter.
+# SCIM/JIT is the production source of truth; this file is only for local dev.
+groups:
+  - externalId: "dev-group-admins"
+    name: "Development Admins"
+    source: "fixture"
+    members:
+      - userExternalId: "dev-admin"

package/templates/monorepo/access/reconcile.yaml.example

@@ -0,0 +1,11 @@
+# Explicit local projection for access:reconcile.
+applications:
+  - appNamespace: "people_app"
+
+groupMemberships:
+  - groupId: "11111111-1111-1111-1111-111111111111"
+    userIds:
+      - "00000000-0000-0000-0000-000000000000"
+
+deletedUserIds: []
+deletedGroupIds: []

package/templates/monorepo/auth/README.md

@@ -0,0 +1,26 @@
+# Shared Auth
+
+This workspace owns the customer-global Better Auth database schema. Apps in the
+customer monorepo should import this package for session validation and user /
+group table references instead of creating app-local auth tables.
+
+Import auth as `@__APP_NAME__/auth`, the database handle as
+`@__APP_NAME__/auth/db`, and table definitions as `@__APP_NAME__/auth/schema`
+from app packages.
+
+The important identity invariant is:
+
+- `core/user:<id>` uses `users.id` from this package.
+- `core/group:<id>#member` uses `groups.id` from this package.
+- `group_members` is the local projection that reconcile uses to repair
+  SpiceDB group membership relationships.
+
+SCIM/JIT protocol handlers are intentionally not implemented here yet; they
+should feed the access-control `groupSync` ingestion contract when that adapter
+lands.
+
+## Database
+
+By default this package uses the customer monorepo database name generated at
+scaffold time. Override with `AUTH_DATABASE_NAME` or `AUTH_DATABASE_URL` when
+the shared auth database lives somewhere else.

package/templates/monorepo/auth/drizzle.config.ts

@@ -0,0 +1,13 @@
+import type { Config } from "drizzle-kit";
+import { getAuthDatabaseConnectionString } from "./src/config/database";
+
+const config: Config = {
+  schema: "./src/drizzle/schema",
+  out: "./src/drizzle/migrations",
+  dialect: "postgresql",
+  dbCredentials: {
+    url: getAuthDatabaseConnectionString(),
+  },
+};
+
+export default config;

package/templates/monorepo/auth/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@__APP_NAME__/auth",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Shared customer identity package.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./db": "./src/drizzle/db.ts",
+    "./schema": "./src/drizzle/schema/index.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:setup": "tsx ./scripts/setup-database.ts",
+    "db:setup-and-migrate": "pnpm db:setup && pnpm db:migrate"
+  },
+  "dependencies": {
+    "@percepta/access-control": "0.3.2",
+    "better-auth": "^1.6.4",
+    "drizzle-orm": "^0.45.2",
+    "pg": "^8.16.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.1.0",
+    "@types/pg": "^8.15.4",
+    "drizzle-kit": "^0.31.4",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
+  }
+}

package/templates/monorepo/auth/scripts/setup-database.ts

@@ -0,0 +1,57 @@
+import { Pool } from "pg";
+import { getAuthDatabaseConfig } from "../src/config/database";
+
+const SHARED_DATABASES = new Set(["demos", "internal_apps"]);
+
+async function main(): Promise<void> {
+  const { database, host, password, port, url, user } = getAuthDatabaseConfig();
+
+  if (url != null && url.length > 0) {
+    console.log("AUTH_DATABASE_URL is set; skipping CREATE DATABASE.");
+    return;
+  }
+
+  console.log(`Setting up shared auth database: ${database}`);
+  console.log(`Host: ${host}:${port}`);
+  console.log(`User: ${user}`);
+
+  if (SHARED_DATABASES.has(database)) {
+    console.log(`${database} is a shared infra-managed database; skipping.`);
+    return;
+  }
+
+  const adminClient = new Pool({
+    database: "postgres",
+    host,
+    password,
+    port,
+    user,
+  });
+
+  try {
+    const result = await adminClient.query(
+      "SELECT 1 FROM pg_database WHERE datname = $1",
+      [database],
+    );
+
+    if (result.rows.length === 0) {
+      await adminClient.query(
+        `CREATE DATABASE ${escapePgIdentifier(database)}`,
+      );
+      console.log(`Database ${database} created successfully.`);
+    } else {
+      console.log(`Database ${database} already exists.`);
+    }
+  } finally {
+    await adminClient.end();
+  }
+}
+
+function escapePgIdentifier(identifier: string): string {
+  return `"${identifier.replaceAll('"', '""')}"`;
+}
+
+void main().catch((error) => {
+  console.error("Shared auth database setup failed:", error);
+  process.exit(1);
+});

package/templates/monorepo/auth/src/auth.ts

@@ -0,0 +1,77 @@
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { admin } from "better-auth/plugins";
+import { db } from "./drizzle/db";
+import { accounts } from "./drizzle/schema/auth/accounts";
+import { sessions } from "./drizzle/schema/auth/sessions";
+import { verifications } from "./drizzle/schema/auth/verifications";
+import { users } from "./drizzle/schema/users";
+
+// eslint-disable-next-line n/no-process-env -- detecting Next.js build phase
+const isBuildPhase = process.env.NEXT_PHASE === "phase-production-build";
+
+function requiredEnv(name: string): string {
+  const value = process.env[name];
+  if (value == null || value.length === 0) {
+    throw new Error(`${name} is required.`);
+  }
+  return value;
+}
+
+function getSecret(): string {
+  if (isBuildPhase) {
+    return "build-placeholder-not-used-at-runtime";
+  }
+
+  return requiredEnv("BETTER_AUTH_SECRET");
+}
+
+function createAuth() {
+  return betterAuth({
+    baseURL: process.env.BETTER_AUTH_URL ?? "http://localhost:3000",
+    secret: getSecret(),
+    database: drizzleAdapter(db, {
+      provider: "pg",
+      schema: {
+        user: users,
+        session: sessions,
+        account: accounts,
+        verification: verifications,
+      },
+    }),
+    emailAndPassword: {
+      enabled: true,
+    },
+    plugins: [admin()],
+    advanced: {
+      database: {
+        generateId: false,
+      },
+    },
+  });
+}
+
+type Auth = ReturnType<typeof createAuth>;
+
+let authInstance: Auth | undefined;
+
+function getAuth(): Auth {
+  authInstance ??= createAuth();
+  return authInstance;
+}
+
+/**
+ * Lazy proxy so app builds can import the shared auth package without requiring
+ * runtime secrets until Better Auth is actually used.
+ */
+export const auth: Auth = new Proxy({} as Auth, {
+  get(_target, prop, receiver) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return Reflect.get(getAuth(), prop, receiver);
+  },
+  has(_target, prop) {
+    return Reflect.has(getAuth(), prop);
+  },
+});
+
+export type BetterAuthSession = typeof auth.$Infer.Session;

package/templates/monorepo/auth/src/config/database.ts

@@ -0,0 +1,31 @@
+export interface AuthDatabaseConfig {
+  readonly database: string;
+  readonly host: string;
+  readonly password: string;
+  readonly port: number;
+  readonly url?: string;
+  readonly user: string;
+}
+
+export function getAuthDatabaseConfig(): AuthDatabaseConfig {
+  return {
+    database: process.env.AUTH_DATABASE_NAME ?? "__DB_NAME__",
+    host: process.env.DATABASE_HOST ?? "localhost",
+    password: process.env.DATABASE_PASSWORD ?? "postgres",
+    port: Number(process.env.DATABASE_PORT ?? 5434),
+    url: process.env.AUTH_DATABASE_URL,
+    user: process.env.DATABASE_USERNAME ?? "postgres",
+  };
+}
+
+export function getAuthDatabaseConnectionString(): string {
+  const { database, host, password, port, url, user } = getAuthDatabaseConfig();
+  if (url != null && url.length > 0) {
+    return url;
+  }
+
+  return (
+    `postgresql://${encodeURIComponent(user)}:${encodeURIComponent(password)}` +
+    `@${host}:${port}/${encodeURIComponent(database)}`
+  );
+}

package/templates/monorepo/auth/src/drizzle/db.ts

@@ -0,0 +1,9 @@
+import { type NodePgDatabase, drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import { getAuthDatabaseConnectionString } from "../config/database";
+import * as schema from "./schema";
+
+export const client = new Pool({
+  connectionString: getAuthDatabaseConnectionString(),
+});
+export const db: NodePgDatabase<typeof schema> = drizzle(client, { schema });

package/templates/monorepo/auth/src/drizzle/migrations/0000_shared_auth.sql

@@ -0,0 +1,89 @@
+CREATE TABLE "users" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"external_id" text,
+	"name" text NOT NULL,
+	"email" text NOT NULL,
+	"email_verified" boolean DEFAULT false NOT NULL,
+	"image" text,
+	"role" text DEFAULT 'user' NOT NULL,
+	"banned" boolean DEFAULT false,
+	"ban_reason" text,
+	"ban_expires" timestamp,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "users_email_unique" UNIQUE("email")
+);
+--> statement-breakpoint
+CREATE TABLE "account" (
+	"id" text PRIMARY KEY NOT NULL,
+	"user_id" uuid NOT NULL,
+	"account_id" text NOT NULL,
+	"provider_id" text NOT NULL,
+	"access_token" text,
+	"refresh_token" text,
+	"expires_at" integer,
+	"access_token_expires_at" timestamp,
+	"refresh_token_expires_at" timestamp,
+	"scope" text,
+	"id_token" text,
+	"password" text,
+	"created_at" timestamp NOT NULL,
+	"updated_at" timestamp NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "session" (
+	"id" text PRIMARY KEY NOT NULL,
+	"user_id" uuid NOT NULL,
+	"token" text NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"ip_address" text,
+	"user_agent" text,
+	"impersonated_by" text,
+	"created_at" timestamp NOT NULL,
+	"updated_at" timestamp NOT NULL,
+	CONSTRAINT "session_token_unique" UNIQUE("token")
+);
+--> statement-breakpoint
+CREATE TABLE "verification" (
+	"id" text PRIMARY KEY NOT NULL,
+	"identifier" text NOT NULL,
+	"value" text NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"created_at" timestamp,
+	"updated_at" timestamp
+);
+--> statement-breakpoint
+CREATE TABLE "groups" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"external_id" text NOT NULL,
+	"name" text NOT NULL,
+	"source" text NOT NULL,
+	"deleted_at" timestamp,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "group_members" (
+	"group_id" uuid NOT NULL,
+	"user_id" uuid NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "group_members_pkey" PRIMARY KEY("group_id","user_id")
+);
+--> statement-breakpoint
+ALTER TABLE "account" ADD CONSTRAINT "account_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+ALTER TABLE "session" ADD CONSTRAINT "session_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+ALTER TABLE "group_members" ADD CONSTRAINT "group_members_group_id_groups_id_fk" FOREIGN KEY ("group_id") REFERENCES "groups"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+ALTER TABLE "group_members" ADD CONSTRAINT "group_members_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+CREATE UNIQUE INDEX "users_lower_email_index" ON "users" USING btree (lower("email"));
+--> statement-breakpoint
+CREATE UNIQUE INDEX "users_external_id_index" ON "users" USING btree ("external_id") WHERE "users"."external_id" IS NOT NULL;
+--> statement-breakpoint
+CREATE UNIQUE INDEX "groups_live_external_id_index" ON "groups" USING btree ("external_id") WHERE "groups"."deleted_at" IS NULL;
+--> statement-breakpoint
+CREATE INDEX "groups_source_index" ON "groups" USING btree ("source");
+--> statement-breakpoint
+CREATE INDEX "group_members_user_id_index" ON "group_members" USING btree ("user_id");

package/templates/monorepo/auth/src/drizzle/migrations/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1777511400000,
+      "tag": "0000_shared_auth",
+      "breakpoints": true
+    }
+  ]
+}

package/templates/{webapp → monorepo/auth}/src/drizzle/schema/auth/accounts.ts

@@ -1,11 +1,6 @@
 import { integer, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
-import { users } from "./users";
+import { users } from "../users";
 
-/**
- * Better Auth account table.
- * Stores OAuth provider links and credential password hashes.
- * @see https://better-auth.com/docs/concepts/database
- */
 export const accounts = pgTable("account", {
   id: text("id")
     .$defaultFn(() => crypto.randomUUID())

package/templates/{webapp → monorepo/auth}/src/drizzle/schema/auth/sessions.ts

@@ -1,10 +1,6 @@
 import { pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
-import { users } from "./users";
+import { users } from "../users";
 
-/**
- * Better Auth session table.
- * @see https://better-auth.com/docs/concepts/database
- */
 export const sessions = pgTable("session", {
   id: text("id")
     .$defaultFn(() => crypto.randomUUID())

package/templates/{webapp → monorepo/auth}/src/drizzle/schema/auth/verifications.ts

@@ -1,9 +1,5 @@
 import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
 
-/**
- * Better Auth verification table.
- * @see https://better-auth.com/docs/concepts/database
- */
 export const verifications = pgTable("verification", {
   id: text("id")
     .$defaultFn(() => crypto.randomUUID())