@percepta/create 3.3.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.3.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": "1.0.0"
+    "@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

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/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",
     },
   },
-];
+);

package/templates/webapp/package.json.template

@@ -55,7 +55,7 @@
     "@opentelemetry/exporter-trace-otlp-proto": "^0.203.0",
     "@opentelemetry/sdk-node": "^0.203.0",
     "@__REPO_NAME__/auth": "workspace:*",
-    "@percepta/access-control": "0.3.2",
+    "@percepta/access-control": "0.6.0",
     "@percepta/design": "0.3.2",
     "@percepta/logger": "0.0.6",
     "@percepta/next-utils": "0.1.0",
@@ -102,6 +102,7 @@
     "zod": "^4.1.5"
   },
   "devDependencies": {
+    "@eslint/js": "^9.18.0",
     "@next/eslint-plugin-next": "^15.3.5",
     "@percepta/build": "0.4.0",
     "@tailwindcss/postcss": "^4.1.11",
@@ -121,9 +122,11 @@
     "eslint-plugin-n": "^17.23.1",
     "eslint-plugin-react": "^7.37.4",
     "eslint-plugin-react-hooks": "^5.2.0",
+    "globals": "^15.14.0",
     "husky": "^9.1.7",
     "tailwindcss": "^4.0.12",
     "typescript": "^5.7.3",
+    "typescript-eslint": "^8.33.0",
     "vitest": "^3.2.1",
     "yargs": "^17.7.2"
   }

package/templates/webapp/scripts/seed.ts

@@ -8,21 +8,36 @@
  */
 
 import { AsyncLocalStorage } from "node:async_hooks";
+import { execFileSync } from "node:child_process";
 import { loadEnvConfig } from "@next/env";
+import type { SubjectRef } from "@percepta/access-control";
 
 const SEEDED_USERS = [
   {
-    access: "owner",
-    appRole: "admin",
-    email: "admin@example.com",
-    name: "Admin User",
+    access: "customer_admin",
+    email: "customer-admin@example.com",
+    name: "Customer Admin",
     password: "password",
     role: "admin",
   },
   {
-    access: "member",
-    email: "user@example.com",
-    name: "Regular User",
+    access: "app_admin",
+    email: "app-admin@example.com",
+    name: "App Admin",
+    password: "password",
+    role: "admin",
+  },
+  {
+    access: "app_user",
+    email: "app-user@example.com",
+    name: "App User",
+    password: "password",
+    role: "user",
+  },
+  {
+    access: "none",
+    email: "non-user@example.com",
+    name: "App Non User",
     password: "password",
     role: "user",
   },
@@ -30,7 +45,7 @@ const SEEDED_USERS = [
 
 async function main(): Promise<void> {
   loadEnvConfig(process.cwd());
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   (globalThis as any).AsyncLocalStorage = AsyncLocalStorage;
 
   const { auth } = await import("@__REPO_NAME__/auth");
@@ -38,13 +53,16 @@ async function main(): Promise<void> {
   const { users } = await import("@__REPO_NAME__/auth/schema");
   const { getAccessControl, toUserSubject } =
     await import("../src/services/access/AppAccessControl");
+  const { getEnvConfig } = await import("../src/config/getEnvConfig");
   const { createCustomerAccessControl } =
     await import("@percepta/access-control");
   const { eq, sql } = await import("drizzle-orm");
 
+  const envConfig = getEnvConfig();
   const access = getAccessControl();
+  const appNamespace = access.manifest.appNamespace;
   const customerAccess = createCustomerAccessControl({
-    applications: [{ appNamespace: access.manifest.appNamespace }],
+    applications: [{ appNamespace }],
     client: access.client,
   });
 
@@ -89,25 +107,54 @@ async function main(): Promise<void> {
     }
 
     const subject = toUserSubject(userId);
-    if (seededUser.access === "owner") {
-      await customerAccess.assignApplicationOwner(
-        access.manifest.appNamespace,
-        subject,
-      );
-    } else {
-      await customerAccess.assignApplicationMember(
-        access.manifest.appNamespace,
-        subject,
-      );
-    }
-
-    if ("appRole" in seededUser) {
-      await access.app.assignAppRole(seededUser.appRole, subject);
+    switch (seededUser.access) {
+      case "customer_admin":
+        bootstrapCustomerAdmin(subject, envConfig);
+        await customerAccess.revokeApplicationAdmin(appNamespace, subject);
+        await customerAccess.revokeApplicationUser(appNamespace, subject);
+        break;
+      case "app_admin":
+        await customerAccess.assignApplicationAdmin(appNamespace, subject);
+        await customerAccess.revokeApplicationUser(appNamespace, subject);
+        break;
+      case "app_user":
+        await customerAccess.assignApplicationUser(appNamespace, subject);
+        await customerAccess.revokeApplicationAdmin(appNamespace, subject);
+        break;
+      case "none":
+        await customerAccess.revokeApplicationAdmin(appNamespace, subject);
+        await customerAccess.revokeApplicationUser(appNamespace, subject);
+        break;
     }
   }
 
-  console.log("Ensured local app access grants.");
+  console.log("Ensured local customer and app access grants.");
   process.exit(0);
 }
 
 void main();
+
+function bootstrapCustomerAdmin(
+  subject: SubjectRef,
+  envConfig: {
+    readonly SPICEDB_ENDPOINT: string;
+    readonly SPICEDB_INSECURE: boolean;
+    readonly SPICEDB_PRESHARED_KEY: string;
+  },
+): void {
+  const args = [
+    "bootstrap-customer-admin",
+    "--subject",
+    subject,
+    "--endpoint",
+    envConfig.SPICEDB_ENDPOINT,
+    "--key",
+    envConfig.SPICEDB_PRESHARED_KEY,
+  ];
+
+  if (envConfig.SPICEDB_INSECURE) {
+    args.push("--insecure");
+  }
+
+  execFileSync("percepta-access-control", args, { stdio: "inherit" });
+}

package/templates/webapp/src/access/access.manifest.ts

@@ -1,5 +1,18 @@
 import { defineAccessManifest } from "@percepta/access-control";
 
+const appRoles = [] as const;
+
+export const accessRoleDefinitions = [] as const satisfies ReadonlyArray<{
+  readonly description: string;
+  readonly editableBy: "app_admin" | "customer_admin";
+  readonly label: string;
+  readonly permissions: ReadonlyArray<{
+    readonly description: string;
+    readonly permission: string;
+  }>;
+  readonly role: (typeof appRoles)[number];
+}>;
+
 export const accessManifest = defineAccessManifest({
   adminUI: {
     enabled: true,
@@ -10,6 +23,6 @@ export const accessManifest = defineAccessManifest({
     urlEnv: "APP_BASE_URL",
   },
   system: {
-    assignableRoles: ["admin"],
+    assignableRoles: appRoles,
   },
 } as const);

package/templates/webapp/src/access/schema.zed

@@ -1,7 +1,3 @@
 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.
 }

package/templates/webapp/src/app/(admin)/admin/_components/AdminTabs.tsx

@@ -0,0 +1,33 @@
+"use client";
+
+import { Tabs, TabsList, TabsTrigger } from "@percepta/design";
+import Link from "next/link";
+
+export type AdminTab = "assignments" | "roles";
+
+const tabs = [
+  { href: "/admin?tab=roles", label: "Roles", tab: "roles" },
+  {
+    href: "/admin?tab=assignments",
+    label: "Assignments",
+    tab: "assignments",
+  },
+] as const satisfies ReadonlyArray<{
+  readonly href: string;
+  readonly label: string;
+  readonly tab: AdminTab;
+}>;
+
+export function AdminTabs({ activeTab }: { readonly activeTab: AdminTab }) {
+  return (
+    <Tabs value={activeTab}>
+      <TabsList aria-label="RBAC views">
+        {tabs.map((tab) => (
+          <TabsTrigger asChild={true} key={tab.tab} value={tab.tab}>
+            <Link href={tab.href}>{tab.label}</Link>
+          </TabsTrigger>
+        ))}
+      </TabsList>
+    </Tabs>
+  );
+}