@percepta/create 4.1.15 → 4.2.0

package/templates/monorepo/package.json.template

@@ -10,7 +10,7 @@
     "setup": "pnpm run docker:up && pnpm run db:setup-local && pnpm run auth:db:migrate && pnpm run access:apply-local && pnpm -r --filter './packages/*' --if-present run db:migrate && pnpm -r --filter './packages/*' --if-present run db:seed",
     "docker:up": "docker compose up -d --wait",
     "docker:down": "docker compose down",
-    "db:setup-local": "node scripts/setup-local-databases.mjs",
+    "db:setup-local": "percepta-db setup-local",
     "dev": "pnpm -r --parallel --if-present run dev",
     "build": "turbo run build",
     "clean": "turbo run clean",
@@ -32,6 +32,7 @@
   "devDependencies": {
     "@percepta/access-control": "^1.0.0",
     "@percepta/build": "^1.0.0",
+    "@percepta/database": "0.1.4",
     "@types/node": "^24.1.0",
     "oxfmt": "^0.47.0",
     "oxlint": "^1.61.0",

package/templates/webapp/.github/workflows/__APP_NAME__-ryvn-release.yaml

@@ -1,6 +1,7 @@
 name: Build & Release __APP_NAME__
 
 on:
+  workflow_dispatch:
   push:
     branches:
       - "main"
@@ -13,97 +14,29 @@ on:
       - "pnpm-lock.yaml"
       - "pnpm-workspace.yaml"
       - ".github/workflows/__APP_NAME__-ryvn-release.yaml"
-  workflow_dispatch:
-
-env:
-  SERVICE_NAME: __APP_NAME__
+  pull_request:
+    paths:
+      - "packages/__APP_NAME__/src/**"
+      - "packages/__APP_NAME__/scripts/**"
+      - "packages/__APP_NAME__/Dockerfile"
+      - "packages/__APP_NAME__/package.json"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - ".github/workflows/__APP_NAME__-ryvn-release.yaml"
 
 jobs:
-  build-and-release:
-    name: Build and Release
-    runs-on: ubuntu-latest
+  release:
+    uses: ryvn-technologies/ryvn-build-action/.github/workflows/release.yml@v2
+    with:
+      service_name: __APP_NAME__
     permissions:
       contents: write
       id-token: write
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Install Ryvn CLI
-        uses: ryvn-technologies/install-ryvn-cli@v1.0.0
-
-      - name: Generate Release Tag
-        id: generate-tag
-        env:
-          RYVN_CLIENT_ID: ${{ secrets.RYVN_CLIENT_ID }}
-          RYVN_CLIENT_SECRET: ${{ secrets.RYVN_CLIENT_SECRET }}
-        run: |
-          tag_info=$(ryvn generate-release-tag "$SERVICE_NAME" --prefix="${SERVICE_NAME}@" -o json --default-bump-minor)
-
-          version=$(echo "$tag_info" | jq -r '.version')
-          new_tag=$(echo "$tag_info" | jq -r '.tag')
-          channel=$(echo "$tag_info" | jq -r '.channel')
-          isPreview=$(echo "$tag_info" | jq -r '.isPreview')
-
-          echo "version=$version" >> $GITHUB_OUTPUT
-          echo "new_tag=$new_tag" >> $GITHUB_OUTPUT
-          echo "channel=$channel" >> $GITHUB_OUTPUT
-          echo "isPreview=$isPreview" >> $GITHUB_OUTPUT
-
-      - name: Build and Push
-        uses: ryvn-technologies/ryvn-build-action@v2
-        with:
-          service_name: ${{ env.SERVICE_NAME }}
-          version: ${{ steps.generate-tag.outputs.version }}
-          build_only: ${{ !(github.ref == format('refs/heads/{0}', github.event.repository.default_branch) || steps.generate-tag.outputs.isPreview == 'true') }}
-          build_secrets: |
-            NPM_TOKEN=${{ secrets.NPM_TOKEN }}
-          ryvn_client_id: ${{ secrets.RYVN_CLIENT_ID }}
-          ryvn_client_secret: ${{ secrets.RYVN_CLIENT_SECRET }}
-
-      - name: Create Ryvn Release
-        if: |
-          !contains(github.event.head_commit.message, '[skip-release]') &&
-          !contains(github.event.pull_request.title, '[skip-release]') &&
-          (steps.generate-tag.outputs.isPreview == 'true' || github.ref == format('refs/heads/{0}', github.event.repository.default_branch))
-        env:
-          RYVN_CLIENT_ID: ${{ secrets.RYVN_CLIENT_ID }}
-          RYVN_CLIENT_SECRET: ${{ secrets.RYVN_CLIENT_SECRET }}
-        run: |
-          version="${{ steps.generate-tag.outputs.new_tag }}"
-          version="${version#"${SERVICE_NAME}@"}"
-          version="${version#@}"
-          channel="${{ steps.generate-tag.outputs.channel }}"
-
-          if [ -n "$channel" ] && [ "$channel" != "null" ]; then
-            ryvn create release "$SERVICE_NAME" "$version" --channel "$channel"
-          else
-            ryvn create release "$SERVICE_NAME" "$version"
-          fi
-
-      - name: Create GitHub Tag
-        if: |
-          github.ref == format('refs/heads/{0}', github.event.repository.default_branch) &&
-          !contains(github.event.head_commit.message, '[skip-release]') &&
-          !contains(github.event.pull_request.title, '[skip-release]')
-        run: |
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
-          git config --global user.name "github-actions[bot]"
-          git tag "${{ steps.generate-tag.outputs.new_tag }}"
-          git push origin "${{ steps.generate-tag.outputs.new_tag }}"
-
-      - name: Create GitHub Release
-        if: |
-          github.ref == format('refs/heads/{0}', github.event.repository.default_branch) &&
-          !contains(github.event.head_commit.message, '[skip-release]') &&
-          !contains(github.event.pull_request.title, '[skip-release]')
-        uses: softprops/action-gh-release@v1
-        with:
-          tag_name: ${{ steps.generate-tag.outputs.new_tag }}
-          name: ${{ steps.generate-tag.outputs.new_tag }}
-          generate_release_notes: true
-          draft: false
-          prerelease: false
+    secrets:
+      RYVN_CLIENT_ID: ${{ secrets.RYVN_CLIENT_ID }}
+      RYVN_CLIENT_SECRET: ${{ secrets.RYVN_CLIENT_SECRET }}
+      BUILD_SECRETS: |
+        NPM_TOKEN=${{ secrets.NPM_TOKEN }}
+        TURBO_TOKEN=${{ secrets.TURBO_TOKEN }}
+        TURBO_TEAM=${{ vars.TURBO_TEAM }}

package/templates/webapp/AGENTS.md

@@ -16,7 +16,7 @@ Next.js 16 full-stack application scaffolded from the Mosaic webapp template via
 - `pnpm db:generate` — generate Drizzle migrations
 - `pnpm db:migrate` — apply migrations
 - `pnpm db:studio` — run migrations, then open Drizzle Studio
-- `pnpm db:seed` — seed shared-auth dev users and local grants for customer admin, app admin, app user, and app non-user personas; username/password scaffolds set the dev password to `password`
+- `pnpm db:seed` — seed shared-auth dev users and local grants for customer admin, app admin, app user, and app non-user personas; sign in via Authentik (dev password `password`, set in the monorepo's `authentik/blueprints/local-dev.yaml`)
 
 **Package manager**: Always use `pnpm`, never `npm` or `yarn`.
 
@@ -54,7 +54,7 @@ src/                        # Application source
 │   ├── langfuse/           # LLM observability
 │   ├── llm/                # LLM provider selection and call helpers
 │   ├── logger/             # App logger setup (wraps @percepta/logger)
-│   └── observability/      # OpenTelemetry setup
+│   └── observability/      # Frontend observability setup
 └── utils/                  # Helpers (cn, pathEncryption, etc.)
 
 deploy/                     # Optional release metadata
@@ -245,10 +245,10 @@ Better Auth is configured in the customer monorepo's shared `@__REPO_NAME__/auth
 
 - **Server-side**: `auth.api.getSession({ headers: await headers() })` — get session in server components or tRPC context
 - **Client-side**: `authClient.useSession()` — React hook from `src/lib/auth-client.ts`
-- **Sign in**: `authClient.signIn.email({ email, password })` — client-side
+- **Sign in**: `authClient.signIn.oauth2({ providerId: "authentik", callbackURL })` — Authentik SSO; there is no password sign-in
 - **Sign out**: `authClient.signOut()` — client-side
 - **API route**: `src/app/api/auth/[...all]/route.ts` — Better Auth handler
-- **Env vars**: `BETTER_AUTH_SECRET` (required), optional `BETTER_AUTH_URL` override, `AUTH_DATABASE_URL` for deployed shared auth DB wiring
+- **Env vars**: `BETTER_AUTH_SECRET` (required) plus `AUTHENTIK_ISSUER` / `AUTHENTIK_CLIENT_ID` / `AUTHENTIK_CLIENT_SECRET` (required — SSO); optional `BETTER_AUTH_URL` override; `AUTH_DATABASE_URL` for deployed shared auth DB wiring
 
 ### Background Jobs
 

package/templates/webapp/README.md

@@ -7,7 +7,7 @@ Design theme: `__MOSAIC_DESIGN_THEME__`
 ## Features
 
 - **Next.js 16** with App Router
-- **Authentication** via Better Auth (__AUTH_MODE_LABEL__)
+- **Authentication** via Better Auth brokered through Authentik SSO
 - **Database** with PostgreSQL, Drizzle ORM, and migrations
 - **Access Control** with SpiceDB schema authoring and manifest validation
 - **Logging** with Pino and structured safe/unsafe data separation
@@ -147,46 +147,34 @@ logger.error({ safe: { documentId } }, "Processing failed", error);
 
 This app consumes the customer monorepo's shared [Better Auth](https://better-auth.com) package, `@__REPO_NAME__/auth`. The app still serves local development auth routes, but the users, sessions, accounts, groups, and group memberships live in the shared customer auth database. Deployed apps should receive that shared database through `AUTH_DATABASE_URL` from the monorepo auth Secret; `DATABASE_URL` is reserved for this app's own database.
 
-This app was scaffolded with `__AUTH_MODE_LABEL__` as its auth setup. New apps
-inherit the customer monorepo's workspace auth setup from
-`.mosaic-workspace.json` by default, and individual apps can override that
-default with `AUTH_MODE`.
+This app authenticates **only via Authentik SSO** — there is no username/password
+sign-in. The required `AUTHENTIK_ISSUER` / `AUTHENTIK_CLIENT_ID` /
+`AUTHENTIK_CLIENT_SECRET` come from the monorepo's local Authentik container in
+development (see the monorepo README) and from the per-app Authentik provider in
+deployments. Other upstream IdPs (Okta, Entra, Google Workspace) are configured
+as Authentik _sources_, not app-level settings.
 
 Every app requires:
 
 ```bash
-AUTH_MODE=__AUTH_MODE__
 BETTER_AUTH_SECRET=generate-with-openssl-rand-base64-32
+# Local dev (provisioned by the monorepo's Authentik container + blueprint):
+AUTHENTIK_ISSUER=http://localhost:9000/application/o/mosaic-local/
+AUTHENTIK_CLIENT_ID=mosaic-local-client
+AUTHENTIK_CLIENT_SECRET=mosaic-local-secret
 ```
 
 Auth uses `BETTER_AUTH_URL`, `APP_BASE_URL`, or `http://localhost:3000`, in
-that order, for its base URL.
+that order, for its base URL. The Better Auth OAuth callback is
+`/api/auth/oauth2/callback/authentik`; deployed Authentik providers must allow
+`https://<app-host>/api/auth/oauth2/callback/authentik`.
 
-For username/password auth, local setup creates credential users and app access
-grants. Google OAuth sign-in requires `GOOGLE_CLIENT_ID` and
-`GOOGLE_CLIENT_SECRET`; optionally set `GOOGLE_HOSTED_DOMAIN`. Register these
-redirect URIs in the Google OAuth client:
-
-```text
-http://localhost:3000/api/auth/callback/google
-https://<app-host>/api/auth/callback/google
-```
-
-Okta OIDC sign-in requires `OKTA_CLIENT_ID`, `OKTA_CLIENT_SECRET`, and
-`OKTA_ISSUER`. The issuer usually looks like
-`https://dev-xxxxx.okta.com/oauth2/default`. Register these redirect URIs in
-the Okta app integration:
-
-```text
-http://localhost:3000/api/auth/oauth2/callback/okta
-https://<app-host>/api/auth/oauth2/callback/okta
-```
-
-OAuth users still pass through the app's SpiceDB access gate after sign-in. In
-local development, `pnpm db:seed` creates access principals for the example
-emails; provider sign-ins with the same verified email can link to those users.
-For other emails, grant app access from the settings UI or seed/apply an access
-grant before expecting the protected app pages to load.
+Authentik users still pass through the app's SpiceDB access gate after sign-in.
+`pnpm run setup` seeds the example users (`app-admin@example.com`, etc.) as local
+principals with grants; the first Authentik sign-in links to them by email
+(Authentik is a trusted provider, so linking does not require pre-verification).
+For other users, grant app access from the settings UI or seed a grant before
+the protected pages will load.
 
 Remote deployments should also set `AUTH_DATABASE_URL` from the shared auth
 database Secret. Local development can omit it and use the root-created local
@@ -200,7 +188,8 @@ pnpm db:seed
 # Creates app-admin@example.com as an app admin
 # Creates app-user@example.com as an app user
 # Creates non-user@example.com with no app access
-# Username/password scaffolds also set each password to: password
+# Sign in as any of them via Authentik (password "password", set in the
+# monorepo's authentik/blueprints/local-dev.yaml).
 ```
 
 ## Access Control

package/templates/webapp/agent-skills/langfuse.md

@@ -22,18 +22,15 @@ Langfuse is an open-source LLM observability platform. It captures traces, spans
 The template uses Next.js's instrumentation hook (called on server startup) to bootstrap OTEL with both the environment collector and optional Langfuse:
 
 ```typescript
-import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
-import { NodeSDK, tracing } from "@opentelemetry/sdk-node";
-import { createLangfuseSpanProcessor } from "@percepta/ai";
-
-const sdk = new NodeSDK({
-  spanProcessors: [
-    new tracing.BatchSpanProcessor(otlpTraceExporter),
-    createLangfuseSpanProcessor(env, logger),
-  ],
-  instrumentations: [getNodeAutoInstrumentations()],
+import { startPerceptaNodeTelemetry } from "@percepta/ai";
+import { getEnvConfig } from "./config/getEnvConfig";
+import { getLogger } from "./services/logger/AppLogger";
+
+startPerceptaNodeTelemetry({
+  appName: "__APP_NAME__",
+  getEnv: getEnvConfig,
+  getLogger,
 });
-sdk.start();
 ```
 
 - `getNodeAutoInstrumentations()` automatically instruments HTTP calls, database queries, and other standard Node.js operations.

package/templates/webapp/agent-skills/oneshot.md

@@ -36,7 +36,7 @@ Ask all that are relevant:
 4. **What are the key workflows?** (e.g., "User uploads a document → system extracts text → user reviews results")
 5. **Does this app call LLMs?** If yes, which provider (OpenAI, Bedrock/Claude, both)? What for?
 6. **Does this app need background jobs?** Long-running tasks, scheduled jobs, multi-step pipelines?
-7. **Auth requirements?** Which provider — Google, Okta, Credentials, or just use the template default?
+7. **Auth requirements?** All apps authenticate via Authentik SSO (local + deployed); the monorepo's local Authentik container handles dev. Anything beyond the template default?
 8. **Any external integrations?** APIs, webhooks, third-party services?
 
 ### Open-Ended

package/templates/webapp/e2e/rbac.spec.ts

@@ -124,14 +124,38 @@ test.describe("RBAC access", () => {
   });
 });
 
+// Apps authenticate via Authentik SSO (there is no password form), so sign-in
+// drives Authentik's hosted login flow. `pnpm run setup` starts the monorepo's
+// local Authentik and seeds these users (password "password") via its blueprint.
+// The provider uses implicit consent, so there is no consent screen. Inputs are
+// targeted by Authentik's stable field names; each stage is submitted via its
+// submit button (Authentik's web-component form doesn't submit on Enter). The
+// identification stage is awaited to detach before the password stage so the two
+// stages don't race during the in-place re-render. (Verified end-to-end against
+// a live local Authentik: each user yields a valid OAuth code + state.)
 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");
+  await page.getByRole("button", { name: /Continue with Authentik/i }).click();
+
+  await page.waitForURL(/\/\/localhost:9000\//);
+  const identifier = page.locator('input[name="uidField"]');
+  await identifier.waitFor({ state: "visible" });
+  await identifier.fill(email);
+  await page.locator('button[type="submit"]').first().click();
+  await identifier.waitFor({ state: "detached" });
+
+  const passwordField = page.locator('input[name="password"]');
+  await passwordField.waitFor({ state: "visible" });
+  await passwordField.fill(password);
+  await page.locator('button[type="submit"]').first().click();
+
+  // Back on the app once Authentik redirects through the OAuth callback.
+  await page.waitForURL(
+    (url) =>
+      !url.href.includes("localhost:9000") && url.pathname !== "/auth/signin",
+  );
 }
 
 async function expectNotFound(page: Page) {

package/templates/webapp/env.example.template

@@ -6,19 +6,15 @@ APP_BASE_URL=http://localhost:3000
 # App Database
 DATABASE_URL=postgresql://postgres:postgres@localhost:5434/__DB_NAME__
 
-# Authentication (Better Auth)
-# App auth setup selected by @percepta/create: __AUTH_MODE_LABEL__
-# Defaults to the workspace auth setup unless this app was scaffolded with an override.
-AUTH_MODE=__AUTH_MODE__
+# Authentication (Better Auth via Authentik SSO)
 BETTER_AUTH_SECRET=generate-with-openssl-rand-base64-32
-# Google OAuth apps should fill these:
-# GOOGLE_CLIENT_ID=
-# GOOGLE_CLIENT_SECRET=
-# GOOGLE_HOSTED_DOMAIN=
-# Okta OIDC apps should fill these:
-# OKTA_CLIENT_ID=
-# OKTA_CLIENT_SECRET=
-# OKTA_ISSUER=
+# These point at the monorepo's local Authentik container (brought up by
+# `pnpm run setup`) and the shared local OIDC client provisioned by its
+# blueprint. Deployed environments override them with the per-app Authentik
+# provider's issuer/credentials.
+AUTHENTIK_ISSUER=http://localhost:9000/application/o/mosaic-local/
+AUTHENTIK_CLIENT_ID=mosaic-local-client
+AUTHENTIK_CLIENT_SECRET=mosaic-local-secret
 
 # Shared Auth Database
 # Deployed apps should set this from the customer monorepo auth database Secret.

package/templates/webapp/package.json.template

@@ -40,17 +40,16 @@
     "@mantine/hooks": "^8.3.1",
     "@next/env": "^16.2.6",
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.75.0",
-    "@opentelemetry/exporter-trace-otlp-proto": "^0.217.0",
     "@opentelemetry/sdk-node": "^0.217.0",
     "@__REPO_NAME__/auth": "workspace:*",
     "@percepta/access-control": "^1.0.0",
-    "@percepta/ai": "^0.1.0",
-    "@percepta/database": "0.1.3",
+    "@percepta/ai": "^0.1.1",
+    "@percepta/auth": "^0.1.7",
+    "@percepta/database": "0.1.4",
     "@percepta/design": "^0.4.1",
     "@percepta/inngest": "^0.1.0",
     "@percepta/logger": "^0.1.0",
-    "@percepta/next-utils": "^0.2.2",
+    "@percepta/next-utils": "^0.2.3",
     "@percepta/utils": "^0.1.11",
     "@radix-ui/react-slot": "^1.2.3",
     "@tanstack/react-query": "^5.81.5",

package/templates/webapp/scripts/seed.ts

@@ -16,38 +16,36 @@ const nextEnv =
   (nextEnvModule as { default?: typeof nextEnvModule }).default ??
   nextEnvModule;
 
+// Local users mirror the accounts in the monorepo's Authentik seed blueprint
+// (same emails, password "password"). Seeding creates the local user row +
+// SpiceDB grants; the first Authentik sign-in links to it by email.
 const SEEDED_USERS = [
   {
     access: "customer_admin",
     email: "customer-admin@example.com",
     name: "Customer Admin",
-    password: "password",
     role: "admin",
   },
   {
     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",
   },
 ] as const;
 
-type AuthMode = "username-password" | "google" | "okta";
 interface AdminCreateUserApi {
   createUser(input: {
     body: {
@@ -58,24 +56,8 @@ interface AdminCreateUserApi {
   }): Promise<{ user: { id: string } }>;
 }
 
-const DEFAULT_AUTH_MODE: AuthMode = "__AUTH_MODE__" as AuthMode;
-
-function isAuthMode(value: string | undefined): value is AuthMode {
-  return (
-    value === "username-password" || value === "google" || value === "okta"
-  );
-}
-
-function getAuthMode(): AuthMode {
-  return isAuthMode(process.env.AUTH_MODE)
-    ? process.env.AUTH_MODE
-    : DEFAULT_AUTH_MODE;
-}
-
 async function main(): Promise<void> {
   nextEnv.loadEnvConfig(process.cwd());
-  const authMode = getAuthMode();
-  process.env.AUTH_MODE = authMode;
   // oxlint-disable-next-line typescript/no-explicit-any
   (globalThis as any).AsyncLocalStorage = AsyncLocalStorage;
 
@@ -85,10 +67,12 @@ async function main(): Promise<void> {
   const { getAccessControl, toUserSubject } =
     await import("../src/services/access/AppAccessControl");
   const { getEnvConfig } = await import("../src/config/getEnvConfig");
+  const { getLogger } = await import("../src/services/logger/AppLogger");
   const { createCustomerAccessControl } =
     await import("@percepta/access-control");
   const { eq, sql } = await import("drizzle-orm");
 
+  const logger = getLogger().child({ safe: { component: "db-seed" } });
   const envConfig = getEnvConfig();
   const access = getAccessControl();
   const appNamespace = access.manifest.appNamespace;
@@ -108,44 +92,36 @@ async function main(): Promise<void> {
     let userId: string;
     if (existing != null) {
       userId = existing.id;
-      console.log(
-        `Seed user "${seededUser.email}" already exists (id: ${existing.id}).`,
+      logger.info(
+        { safe: { email: seededUser.email, userId: existing.id } },
+        "Seed user already exists.",
       );
     } else {
-      if (authMode === "username-password") {
-        // Use Better Auth's signUpEmail API to create the user with a hashed password.
-        const res = await auth.api.signUpEmail({
-          body: {
-            email: seededUser.email,
-            name: seededUser.name,
-            password: seededUser.password,
-          },
-        });
-        userId = res.user.id;
-      } else {
-        // The admin plugin can create local access principals when this app
-        // starts with an external OAuth provider instead of credentials.
-        const adminApi = auth.api as typeof auth.api & AdminCreateUserApi;
-        const res = await adminApi.createUser({
-          body: {
-            email: seededUser.email,
-            name: seededUser.name,
-          },
-        });
-        userId = res.user.id;
-      }
-
-      console.log(`Seed user created: ${seededUser.email} (id: ${userId})`);
-      if (authMode === "username-password") {
-        console.log(`  Password: ${seededUser.password}`);
-      }
+      // Apps authenticate via Authentik, so create the local user row with the
+      // admin plugin (no password). SpiceDB grants attach to this row, and the
+      // first Authentik sign-in links the OIDC identity to it by email.
+      const adminApi = auth.api as typeof auth.api & AdminCreateUserApi;
+      const res = await adminApi.createUser({
+        body: {
+          email: seededUser.email,
+          name: seededUser.name,
+        },
+      });
+      userId = res.user.id;
+      logger.info(
+        { safe: { email: seededUser.email, userId } },
+        "Seed user created.",
+      );
     }
 
     await authDb
       .update(users)
       .set({ role: seededUser.role })
       .where(eq(users.id, userId));
-    console.log(`  Ensured role: ${seededUser.role}`);
+    logger.info(
+      { safe: { email: seededUser.email, role: seededUser.role } },
+      "Seed user role ensured.",
+    );
 
     const subject = toUserSubject(userId);
     switch (seededUser.access) {
@@ -169,7 +145,7 @@ async function main(): Promise<void> {
     }
   }
 
-  console.log("Ensured local customer and app access grants.");
+  logger.info(undefined, "Ensured local customer and app access grants.");
   process.exit(0);
 }
 

package/templates/webapp/scripts/with-local-env.ts

@@ -1,75 +1,23 @@
 #!/usr/bin/env tsx
 
-import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
+import { runCommandWithEnvFile } from "@percepta/database";
 
-type EnvMap = Record<string, string>;
-
-const LOCAL_ENV_PATH = path.join(
-  homedir(),
-  ".config",
-  "percepta",
-  "create.env",
-);
-
-function parseEnvFile(filePath: string): EnvMap {
-  if (!existsSync(filePath)) return {};
-
-  const env: EnvMap = {};
-  const content = readFileSync(filePath, "utf8");
-  for (const rawLine of content.split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (!line || line.startsWith("#")) continue;
-
-    const normalized = line.startsWith("export ") ? line.slice(7).trim() : line;
-    const separatorIndex = normalized.indexOf("=");
-    if (separatorIndex === -1) continue;
-
-    const key = normalized.slice(0, separatorIndex).trim();
-    const rawValue = normalized.slice(separatorIndex + 1).trim();
-    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
-
-    env[key] = unquote(rawValue);
-  }
-
-  return env;
-}
-
-function unquote(value: string): string {
-  if (
-    (value.startsWith('"') && value.endsWith('"')) ||
-    (value.startsWith("'") && value.endsWith("'"))
-  ) {
-    return value.slice(1, -1);
-  }
-
-  return value;
-}
+const LOCAL_ENV_DIR = path.join(homedir(), ".config", "percepta");
+const LOCAL_ENV_FILE = "create.env";
 
 const [command, ...args] = process.argv.slice(2);
 if (!command) {
   throw new Error("Usage: tsx scripts/with-local-env.ts <command> [...args]");
 }
 
-const child = spawn(command, args, {
-  env: {
-    ...parseEnvFile(LOCAL_ENV_PATH),
-    ...process.env,
-  },
-  stdio: "inherit",
-});
-
-child.on("error", (error) => {
-  throw error;
-});
-
-child.on("exit", (code, signal) => {
-  if (signal) {
-    process.kill(process.pid, signal);
-    return;
-  }
-
-  process.exit(code ?? 1);
-});
+process.exit(
+  await runCommandWithEnvFile({
+    args,
+    allowedEnvFileNames: [LOCAL_ENV_FILE],
+    command,
+    envFileBaseDir: LOCAL_ENV_DIR,
+    envFilePath: LOCAL_ENV_FILE,
+  }),
+);