@percepta/create 3.3.0 → 3.4.1

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.1",
   "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/auth/package.json

@@ -7,6 +7,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./db": "./src/drizzle/db.ts",
+    "./principals": "./src/principals.ts",
     "./schema": "./src/drizzle/schema/index.ts"
   },
   "scripts": {
@@ -17,7 +18,7 @@
     "db:setup-and-migrate": "pnpm db:setup && pnpm db:migrate"
   },
   "dependencies": {
-    "@percepta/auth": "0.1.0",
+    "@percepta/auth": "0.1.1",
     "drizzle-orm": "^0.45.2"
   },
   "devDependencies": {

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

@@ -0,0 +1,11 @@
+import { listAuthPrincipals } from "@percepta/auth/drizzle";
+import { db } from "./drizzle/db";
+import { groups, users } from "./drizzle/schema";
+
+export function listPrincipals() {
+  return listAuthPrincipals({
+    db,
+    groupsTable: groups,
+    usersTable: users,
+  });
+}

package/templates/monorepo/package.json.template

@@ -28,7 +28,7 @@
     "pnpm": ">=9"
   },
   "devDependencies": {
-    "@percepta/access-control": "0.3.2",
+    "@percepta/access-control": "0.6.1",
     "@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

@@ -98,6 +98,32 @@ src/
 | `pnpm db:setup-and-migrate` | Setup and migrate database |
 | `pnpm db:studio` | Setup/migrate the database, then open Drizzle Studio |
 | `pnpm db:seed` | Seed default shared-auth dev users and local access grants |
+| `pnpm test:e2e:install` | Install the Chromium browser used by Playwright |
+| `pnpm test:e2e` | Run Playwright e2e tests after local setup |
+| `pnpm test:e2e:ui` | Run Playwright e2e tests in UI mode after local setup |
+
+## End-to-End Tests
+
+This template includes focused Playwright coverage for seeded RBAC flows. Before
+the first run, install the browser binary:
+
+```bash
+pnpm test:e2e:install
+```
+
+Then run:
+
+```bash
+pnpm test:e2e
+```
+
+The e2e script runs local setup first, then starts the Next.js dev server via
+Playwright. To point the tests at an already-running app, set
+`PLAYWRIGHT_BASE_URL`, for example:
+
+```bash
+PLAYWRIGHT_BASE_URL=http://localhost:3000 pnpm test:e2e
+```
 
 ## Logging
 
@@ -134,11 +160,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/e2e/rbac.spec.ts

@@ -0,0 +1,136 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { expect, test, type Page } from "@playwright/test";
+
+const execFileAsync = promisify(execFile);
+const password = "password";
+
+const users = {
+  appAdmin: "app-admin@example.com",
+  appUser: "app-user@example.com",
+  customerAdmin: "customer-admin@example.com",
+  nonAppUser: "non-user@example.com",
+} as const;
+
+test.describe("RBAC access", () => {
+  test("customer admin can manage role mappings but cannot enter the main app", async ({
+    page,
+  }) => {
+    test.setTimeout(60_000);
+    await signIn(page, users.customerAdmin, "/admin?tab=assignments");
+
+    await expect(page.getByRole("heading", { name: "RBAC" })).toBeVisible();
+    await expect(page.getByRole("link", { name: "Admin" })).toBeVisible();
+
+    const userAssignments = page.getByRole("button", {
+      name: "User assignments",
+    });
+    const adminAssignments = page.getByRole("button", {
+      name: "Admin assignments",
+    });
+
+    await expect(userAssignments).toHaveAttribute("aria-disabled", "false");
+    await expect(adminAssignments).toHaveAttribute("aria-disabled", "false");
+
+    await userAssignments.click();
+    await expect(page.getByPlaceholder("Search users or groups")).toBeVisible();
+
+    let shouldResetSeedData = false;
+    try {
+      await page.getByRole("option", { name: /App Non User/ }).click();
+      shouldResetSeedData = true;
+      await expect(userAssignments).toContainText("App Non User");
+      await expect(userAssignments).toHaveAttribute("aria-busy", "false");
+
+      await page.reload();
+      await expect(
+        page.getByRole("button", { name: "User assignments" }),
+      ).toContainText("App Non User");
+    } finally {
+      if (shouldResetSeedData) {
+        await resetSeedData();
+      }
+    }
+
+    await page.reload();
+    await expect(
+      page.getByRole("button", { name: "User assignments" }),
+    ).not.toContainText("App Non User");
+
+    await page.goto("/");
+    await expect(page.getByRole("heading", { name: /Welcome to/ })).toHaveCount(
+      0,
+    );
+    await expectNotFound(page);
+  });
+
+  test("app admin can see RBAC and main app but cannot edit default role mappings", async ({
+    page,
+  }) => {
+    await signIn(page, users.appAdmin, "/admin?tab=assignments");
+
+    await expect(page.getByRole("heading", { name: "RBAC" })).toBeVisible();
+    await expect(
+      page
+        .getByText("Only customer admins can edit default application roles.")
+        .first(),
+    ).toBeVisible();
+
+    await expect(
+      page.getByRole("button", { name: "User assignments" }),
+    ).toHaveAttribute("aria-disabled", "true");
+    await expect(
+      page.getByRole("button", { name: "Admin assignments" }),
+    ).toHaveAttribute("aria-disabled", "true");
+
+    await page.goto("/");
+    await expect(
+      page.getByRole("heading", { name: /Welcome to/ }),
+    ).toBeVisible();
+  });
+
+  test("app user can enter the main app but cannot reach admin", async ({
+    page,
+  }) => {
+    await signIn(page, users.appUser, "/");
+
+    await expect(
+      page.getByRole("heading", { name: /Welcome to/ }),
+    ).toBeVisible();
+    await expect(page.getByRole("link", { name: "Admin" })).toHaveCount(0);
+
+    await page.goto("/admin");
+    await expect(page.getByRole("heading", { name: "RBAC" })).toHaveCount(0);
+    await expectNotFound(page);
+  });
+
+  test("non app user cannot enter the app", async ({ page }) => {
+    await signIn(page, users.nonAppUser, "/");
+
+    await expect(page.getByRole("heading", { name: /Welcome to/ })).toHaveCount(
+      0,
+    );
+    await expect(page.getByRole("heading", { name: "RBAC" })).toHaveCount(0);
+    await expectNotFound(page);
+  });
+});
+
+async function signIn(page: Page, email: string, callbackUrl: string) {
+  await page.goto(
+    `/auth/signin?callbackUrl=${encodeURIComponent(callbackUrl)}`,
+  );
+  await page.getByLabel("Email").fill(email);
+  await page.getByLabel("Password").fill(password);
+  await page.getByRole("button", { name: "Sign In" }).click();
+  await page.waitForURL((url) => url.pathname !== "/auth/signin");
+}
+
+async function expectNotFound(page: Page) {
+  await expect(
+    page.getByText(/This page could not be found|404/i).first(),
+  ).toBeVisible();
+}
+
+async function resetSeedData() {
+  await execFileAsync("pnpm", ["db:seed"], { cwd: process.cwd() });
+}

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,10 @@ export default [
       "n/no-process-env": "off",
     },
   },
-];
+  {
+    files: ["playwright.config.ts"],
+    rules: {
+      "n/no-process-env": "off",
+    },
+  },
+);

package/templates/webapp/gitignore.template

@@ -12,6 +12,8 @@
 
 # testing
 /coverage
+/playwright-report
+/test-results
 
 # next.js
 /.next/

package/templates/webapp/package.json.template

@@ -27,6 +27,9 @@
     "deploy:percepta-test": "tsx ./scripts/deploy-percepta-test.ts",
     "deploy:percepta-test:pr": "tsx ./scripts/open-ryvn-deploy-pr.ts",
     "test": "vitest run",
+    "test:e2e": "pnpm run setup && playwright test",
+    "test:e2e:install": "playwright install chromium",
+    "test:e2e:ui": "pnpm run setup && playwright test --ui",
     "test:watch": "vitest"
   },
   "dependencies": {
@@ -55,7 +58,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.1",
     "@percepta/design": "0.3.2",
     "@percepta/logger": "0.0.6",
     "@percepta/next-utils": "0.1.0",
@@ -102,7 +105,9 @@
     "zod": "^4.1.5"
   },
   "devDependencies": {
+    "@eslint/js": "^9.18.0",
     "@next/eslint-plugin-next": "^15.3.5",
+    "@playwright/test": "^1.58.2",
     "@percepta/build": "0.4.0",
     "@tailwindcss/postcss": "^4.1.11",
     "@types/formidable": "^3.4.5",
@@ -121,9 +126,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/playwright.config.ts

@@ -0,0 +1,33 @@
+import { defineConfig, devices } from "@playwright/test";
+
+const port = Number(process.env.PLAYWRIGHT_PORT ?? 3000);
+const baseURL = process.env.PLAYWRIGHT_BASE_URL ?? `http://127.0.0.1:${port}`;
+
+export default defineConfig({
+  testDir: "./e2e",
+  fullyParallel: false,
+  forbidOnly: Boolean(process.env.CI),
+  retries: process.env.CI ? 2 : 0,
+  reporter: process.env.CI ? [["list"], ["html", { open: "never" }]] : "list",
+  use: {
+    baseURL,
+    trace: "on-first-retry",
+  },
+  webServer: process.env.PLAYWRIGHT_BASE_URL
+    ? undefined
+    : {
+        command: `pnpm dev -- --hostname 127.0.0.1 --port ${port}`,
+        env: {
+          SKIP_INNGEST_SYNC: "true",
+        },
+        reuseExistingServer: !process.env.CI,
+        timeout: 120_000,
+        url: baseURL,
+      },
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+});