@percepta/create 3.2.0 → 3.4.0

package/README.md

@@ -8,7 +8,7 @@ Scaffold and manage Mosaic packages.
 npx @percepta/create
 ```
 
-That's it. The CLI prompts you for the package type, repo name, and package name as needed. Defaults yield a running app — sign in as `admin@example.com` / `password`.
+That's it. The CLI prompts you for the package type, repo name, and package name as needed. Defaults yield a running app — sign in as `app-admin@example.com` / `password`.
 
 ## Options (mostly for automation)
 
@@ -43,11 +43,11 @@ The bare command above is the canonical UX. The flags below exist for tests and
 When you scaffold a webapp (the default flow), `create` automatically runs:
 
 1. `pnpm install` (at the monorepo root)
-2. `pnpm run setup` — Docker Compose Postgres + Drizzle migrations + seed user
+2. `pnpm run setup` — Docker Compose Postgres + Drizzle migrations + seed users
 3. `pnpm dev` — Next.js dev server
 4. Opens the served URL in your default browser
 
-Sign in as `admin@example.com` / `password` to start building.
+Sign in as `app-admin@example.com` / `password` to start building.
 
 To bail out of the auto-run and get manual next-steps instead, pass `--skip-install`. Then you can run install / setup / dev yourself when ready.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percepta/create",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Scaffold a new Mosaic package",
   "keywords": [
     "cli",
@@ -38,7 +38,7 @@
     "@types/node": "^24.1.0",
     "@types/validate-npm-package-name": "^4.0.2",
     "vitest": "^4.0.0",
-    "@percepta/build": "0.5.1"
+    "@percepta/build": "1.1.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/templates/monorepo/README.md

@@ -41,7 +41,7 @@ packages/
 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.
+as application admins, application users, and bootstrap customer admins.
 
 ```bash
 pnpm access:merge
@@ -53,8 +53,10 @@ 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:
+For local development, `pnpm run setup` seeds the generated app's default dev
+users and access grants. For additional local grants, copy the example fixture
+files in `access/`, fill in customer-global user/group IDs from `auth/`, then
+run:
 
 ```bash
 pnpm access:seed-grants
@@ -63,9 +65,10 @@ 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.
+The `auth/` workspace wires the customer-global Better Auth schema from
+`@percepta/auth`, 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
 

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

@@ -5,15 +5,10 @@ customerAdmins:
 
 applications:
   - appNamespace: "people_app"
-    owners:
+    admins:
       - userId: "00000000-0000-0000-0000-000000000000"
-    members:
-      - groupId: "11111111-1111-1111-1111-111111111111"
-
-appRoles:
-  - appNamespace: "people_app"
-    role: "admin"
-    subjects:
+    users:
       - groupId: "11111111-1111-1111-1111-111111111111"
 
+appRoles: []
 resourceRelations: []

package/templates/monorepo/auth/README.md

@@ -1,8 +1,9 @@
 # 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.
+This workspace wires the customer-global Better Auth database schema from
+`@percepta/auth`. 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`

package/templates/monorepo/auth/package.json

@@ -17,14 +17,11 @@
     "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"
+    "@percepta/auth": "0.1.0",
+    "drizzle-orm": "^0.45.2"
   },
   "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

@@ -1,54 +1,8 @@
-import { Pool } from "pg";
+import { setupAuthDatabase } from "@percepta/auth";
 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('"', '""')}"`;
+  await setupAuthDatabase({ config: getAuthDatabaseConfig() });
 }
 
 void main().catch((error) => {

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

@@ -1,6 +1,4 @@
-import { betterAuth } from "better-auth";
-import { drizzleAdapter } from "better-auth/adapters/drizzle";
-import { admin } from "better-auth/plugins";
+import { createLazyAuth, createPerceptaAuth } from "@percepta/auth/better-auth";
 import { db } from "./drizzle/db";
 import { accounts } from "./drizzle/schema/auth/accounts";
 import { sessions } from "./drizzle/schema/auth/sessions";
@@ -27,51 +25,23 @@ function getSecret(): string {
 }
 
 function createAuth() {
-  return betterAuth({
+  return createPerceptaAuth({
     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,
-      },
+    database: db,
+    schema: {
+      user: users,
+      session: sessions,
+      account: accounts,
+      verification: verifications,
     },
+    secret: getSecret(),
   });
 }
 
-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 const auth = createLazyAuth(createAuth);
 
 export type BetterAuthSession = typeof auth.$Infer.Session;

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

@@ -1,31 +1,15 @@
-export interface AuthDatabaseConfig {
-  readonly database: string;
-  readonly host: string;
-  readonly password: string;
-  readonly port: number;
-  readonly url?: string;
-  readonly user: string;
-}
+import {
+  createAuthDatabaseConnectionString,
+  readAuthDatabaseConfig,
+  type AuthDatabaseConfig,
+} from "@percepta/auth";
+
+export type { AuthDatabaseConfig } from "@percepta/auth";
 
 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",
-  };
+  return readAuthDatabaseConfig({ defaultDatabaseName: "__DB_NAME__" });
 }
 
 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)}`
-  );
+  return createAuthDatabaseConnectionString(getAuthDatabaseConfig());
 }

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

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

package/templates/monorepo/auth/src/drizzle/schema/auth/accounts.ts

@@ -1,28 +1,7 @@
-import { integer, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { createAccountsTable } from "@percepta/auth/drizzle";
 import { users } from "../users";
 
-export const accounts = pgTable("account", {
-  id: text("id")
-    .$defaultFn(() => crypto.randomUUID())
-    .primaryKey(),
-  userId: uuid("user_id")
-    .notNull()
-    .references(() => users.id, { onDelete: "cascade" }),
-  accountId: text("account_id").notNull(),
-  providerId: text("provider_id").notNull(),
-  accessToken: text("access_token"),
-  refreshToken: text("refresh_token"),
-  expiresAt: integer("expires_at"),
-  accessTokenExpiresAt: timestamp("access_token_expires_at", { mode: "date" }),
-  refreshTokenExpiresAt: timestamp("refresh_token_expires_at", {
-    mode: "date",
-  }),
-  scope: text("scope"),
-  idToken: text("id_token"),
-  password: text("password"),
-  createdAt: timestamp("created_at", { mode: "date" }).notNull(),
-  updatedAt: timestamp("updated_at", { mode: "date" }).notNull(),
-});
+export const accounts = createAccountsTable({ usersTable: users });
 
 export type Account = typeof accounts.$inferSelect;
 export type NewAccount = typeof accounts.$inferInsert;

package/templates/monorepo/auth/src/drizzle/schema/auth/sessions.ts

@@ -1,21 +1,7 @@
-import { pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { createSessionsTable } from "@percepta/auth/drizzle";
 import { users } from "../users";
 
-export const sessions = pgTable("session", {
-  id: text("id")
-    .$defaultFn(() => crypto.randomUUID())
-    .primaryKey(),
-  userId: uuid("user_id")
-    .notNull()
-    .references(() => users.id, { onDelete: "cascade" }),
-  token: text("token").notNull().unique(),
-  expiresAt: timestamp("expires_at", { mode: "date" }).notNull(),
-  ipAddress: text("ip_address"),
-  userAgent: text("user_agent"),
-  impersonatedBy: text("impersonated_by"),
-  createdAt: timestamp("created_at", { mode: "date" }).notNull(),
-  updatedAt: timestamp("updated_at", { mode: "date" }).notNull(),
-});
+export const sessions = createSessionsTable({ usersTable: users });
 
 export type Session = typeof sessions.$inferSelect;
 export type NewSession = typeof sessions.$inferInsert;

package/templates/monorepo/auth/src/drizzle/schema/auth/verifications.ts

@@ -1,15 +1,6 @@
-import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
+import { createVerificationsTable } from "@percepta/auth/drizzle";
 
-export const verifications = pgTable("verification", {
-  id: text("id")
-    .$defaultFn(() => crypto.randomUUID())
-    .primaryKey(),
-  identifier: text("identifier").notNull(),
-  value: text("value").notNull(),
-  expiresAt: timestamp("expires_at", { mode: "date" }).notNull(),
-  createdAt: timestamp("created_at", { mode: "date" }),
-  updatedAt: timestamp("updated_at", { mode: "date" }),
-});
+export const verifications = createVerificationsTable();
 
 export type Verification = typeof verifications.$inferSelect;
 export type NewVerification = typeof verifications.$inferInsert;

package/templates/monorepo/auth/src/drizzle/schema/groups.ts

@@ -1,7 +1,7 @@
 import {
   createGroupMembersTable,
   createGroupsTable,
-} from "@percepta/access-control/drizzle";
+} from "@percepta/auth/drizzle";
 import { users } from "./users";
 
 export const groups = createGroupsTable();

package/templates/monorepo/auth/src/drizzle/schema/users.ts

@@ -1,4 +1,4 @@
-import { createUsersTable } from "@percepta/access-control/drizzle";
+import { createUsersTable } from "@percepta/auth/drizzle";
 
 export const users = createUsersTable();
 

package/templates/monorepo/package.json.template

@@ -28,7 +28,7 @@
     "pnpm": ">=9"
   },
   "devDependencies": {
-    "@percepta/access-control": "0.3.2",
+    "@percepta/access-control": "0.6.0",
     "@types/node": "^24.1.0",
     "eslint": "^9.18.0",
     "rimraf": "^5.0.5",

package/templates/webapp/AGENTS.md

@@ -17,7 +17,7 @@ Next.js 15 full-stack application scaffolded from the Mosaic webapp template via
 - `pnpm db:migrate` — apply migrations
 - `pnpm db:setup-and-migrate` — create DB + migrate
 - `pnpm db:studio` — setup/migrate the database, then open Drizzle Studio
-- `pnpm db:seed` — seed default shared-auth dev users and local access grants (admin@example.com and user@example.com / password)
+- `pnpm db:seed` — seed shared-auth dev users and local grants for customer admin, app admin, app user, and app non-user personas (all use password)
 
 **Package manager**: Always use `pnpm`, never `npm` or `yarn`.
 
@@ -109,15 +109,14 @@ Also includes composite components: `ButtonWithDropdown`, `Combobox`, `IconButto
 
 ### @percepta/build — Shared Build Configs
 
-Provides centralized ESLint, Prettier, TypeScript, and Vitest configuration.
+Provides centralized formatter, TypeScript, bundler, and Vitest configuration.
 
 ```js
 // eslint.config.mjs
-import createEslintConfig from "@percepta/build/eslint";
-export default [
-  ...createEslintConfig({ type: "react", dirname: import.meta.dirname }),
-  // app-specific overrides...
-];
+import eslint from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(eslint.configs.recommended, ...tseslint.configs.recommended);
 ```
 
 ```json

package/templates/webapp/README.md

@@ -134,11 +134,13 @@ BETTER_AUTH_SECRET=generate-with-openssl-rand-base64-32
 BETTER_AUTH_URL=http://localhost:3000
 ```
 
-To create a dev user:
+To create dev users:
 ```bash
 pnpm db:seed
-# Creates admin@example.com / password as an app admin
-# Creates user@example.com / password as a non-admin app member
+# Creates customer-admin@example.com / password as a customer admin
+# Creates app-admin@example.com / password as an app admin
+# Creates app-user@example.com / password as an app user
+# Creates non-user@example.com / password with no app access
 ```
 
 ## Access Control

package/templates/webapp/agent-skills/access-control.md

@@ -15,10 +15,10 @@ There are three separate authorization layers:
 | Layer | Owner | Stored as |
 |-------|-------|-----------|
 | Customer admins | Customer bootstrap / Applications admin | `core/customer:main#admin@core/user:<users.id>` |
-| Application access | Customer Applications admin | `core/application:<app>#owner/member@core/user:<users.id>` or `core/group:<groups.id>#member` |
-| App roles/resources | This app's owner/admin UI and app code | `<app>/system:main#<role>@<subject>` and app resource relationships |
+| Default application roles | Customer Applications admin | `core/application:<app>#admin/user@core/user:<users.id>` or `core/group:<groups.id>#member` |
+| App roles/resources | This app's admin UI and app code | `<app>/system:main#<role>@<subject>` and app resource relationships |
 
-Customer admins do not automatically get application access. To enter an app, a user or group must be an application `owner` or `member`.
+Customer admins do not automatically get application access. They can manage default app roles, but to enter the app as a user, a user or group must be an application `admin` or `user`.
 
 ## Source Of Truth
 
@@ -40,11 +40,7 @@ Every app-authored SpiceDB definition must live under this app's namespace:
 
 ```zed
 definition __APP_NAME_SNAKE__/system {
-  relation application: core/application
-  relation admin: core/user | core/group#member
-
-  permission access_app = application->access
-  permission manage_roles = access_app & (application->owner + admin)
+  // Add application-specific roles and permissions here.
 }
 ```
 
@@ -61,36 +57,33 @@ Do not use email addresses, IdP external IDs, group slugs, or display names in S
 
 Application access means "can open this app at all." It comes from the customer-level `core/application` object.
 
-The starter system permission is:
+The core application permission is:
 
 ```zed
-permission access_app = application->access
+permission app_access = user + admin
 ```
 
 The generated app gates the protected app layout with `canAccessApplication()`. Keep that gate in place for authenticated app pages. In tRPC, `protectedProcedure` means authenticated, `appProcedure` adds the default app-access gate, and `requirePermission` should be used for resource-specific checks.
 
-For resource permissions that should only be available inside the app, include `system->access_app` in the Zed expression or make the permission depend on another permission that does. If a permission is intentionally usable without app enrollment, list it in `externallyShareablePermissions` in the manifest.
+For resource permissions that should only be available inside the app, keep the API route behind `appProcedure` or another `canAccessApplication()` check, then let the resource permission model the object-specific rule. If a permission is intentionally usable without app enrollment, list it in `externallyShareablePermissions` in the manifest.
 
 ## App-Defined Roles
 
-App roles are static roles authored by the app builder in Zed and assigned by app owners/admins at runtime.
+App roles are static roles authored by the app builder in Zed and assigned by app admins at runtime.
 
 To add a role:
 
 1. Add a relation to `<appNamespace>/system` in `schema.zed`.
-2. Include the role in `system.assignableRoles` in `access.manifest.ts` if app owners may assign it.
+2. Include the role in `system.assignableRoles` in `access.manifest.ts` if app admins may assign it.
 3. Run `pnpm access:validate`.
 
 Example:
 
 ```zed
 definition __APP_NAME_SNAKE__/system {
-  relation application: core/application
-  relation admin: core/user | core/group#member
   relation hr_admin: core/user | core/group#member
 
-  permission access_app = application->access
-  permission manage_roles = access_app & (application->owner + admin)
+  permission manage_hr = hr_admin
 }
 ```
 
@@ -101,12 +94,12 @@ export const accessManifest = defineAccessManifest({
   // ...
   system: {
     // ...
-    assignableRoles: ["admin", "hr_admin"],
+    assignableRoles: ["hr_admin"],
   },
 } as const);
 ```
 
-Role assignment is additive. Assigning `admin` and then `hr_admin` leaves both grants in place until each one is revoked.
+Role assignment is additive. Assigning one app role and then another leaves both grants in place until each one is revoked.
 
 ## Permissioned Resources
 
@@ -120,8 +113,8 @@ definition __APP_NAME_SNAKE__/employee {
   relation employee_user: core/user
   relation manager: __APP_NAME_SNAKE__/employee
 
-  permission view_basic = system->access_app
-  permission view_private = system->access_app & (employee_user + manager->view_private + system->hr_admin)
+  permission view_basic = employee_user + manager->view_basic + system->hr_admin
+  permission view_private = employee_user + manager->view_private + system->hr_admin
 }
 ```
 
@@ -256,7 +249,7 @@ The `users.role` column is not the app permission source of truth. If Better Aut
 ## Debugging A Denied Check
 
 1. Confirm the user can authenticate and has the expected shared `users.id` in the auth DB.
-2. Confirm application access first: the user or one of their groups needs `core/application:<app>#member` or `#owner`.
+2. Confirm application access first: the user or one of their groups needs `core/application:<app>#user` or `#admin`.
 3. Confirm local topology exists:
 
 ```bash

package/templates/webapp/eslint.config.mjs

@@ -1,13 +1,13 @@
 // @ts-check
+import eslint from "@eslint/js";
 import nextPlugin from "@next/eslint-plugin-next";
-import createEslintConfig from "@percepta/build/eslint";
 import nodePlugin from "eslint-plugin-n";
+import reactPlugin from "eslint-plugin-react";
+import reactHooksPlugin from "eslint-plugin-react-hooks";
+import globals from "globals";
+import tseslint from "typescript-eslint";
 
-export default [
-  ...createEslintConfig({
-    type: "react",
-    dirname: import.meta.dirname,
-  }),
+export default tseslint.config(
   {
     ignores: [
       "pnpm-lock.yaml",
@@ -18,15 +18,43 @@ export default [
       "terraform/**",
     ],
   },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ["**/*.{js,mjs,cjs,ts,tsx}"],
+    languageOptions: {
+      ecmaVersion: "latest",
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+      parserOptions: {
+        ecmaFeatures: {
+          jsx: true,
+        },
+      },
+      sourceType: "module",
+    },
+  },
   {
     plugins: {
       "@next/next": nextPlugin,
+      react: reactPlugin,
+      "react-hooks": reactHooksPlugin,
     },
     rules: {
       ...nextPlugin.configs.recommended.rules,
       ...nextPlugin.configs["core-web-vitals"].rules,
+      ...reactPlugin.configs.recommended.rules,
+      ...reactHooksPlugin.configs.recommended.rules,
+      "react/jsx-uses-react": "off",
       "react/react-in-jsx-scope": "off",
     },
+    settings: {
+      react: {
+        version: "detect",
+      },
+    },
   },
   {
     files: ["src/**/*"],
@@ -63,4 +91,4 @@ export default [
       "n/no-process-env": "off",
     },
   },
-];
+);