@percepta/create 4.1.15 → 4.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percepta/create",
-  "version": "4.1.15",
+  "version": "4.1.16",
   "description": "Scaffold a new Mosaic package",
   "keywords": [
     "cli",
@@ -50,7 +50,10 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:template": "bash scripts/test-template.sh",
+    "lint:templates:logging": "oxlint -c oxlint.template-logging.config.json templates --no-error-on-unmatched-pattern",
+    "test:template": "pnpm lint:templates:logging && pnpm test:template:contract && pnpm build && pnpm test:template:build",
+    "test:template:contract": "vitest run src/commands/create-output.test.ts",
+    "test:template:build": "bash scripts/test-template.sh",
     "create:local": "pnpm build && node dist/index.js",
     "sync-template": "tsx scripts/sync-template.ts",
     "template:tag": "tsx scripts/template-tag.ts"

package/templates/monorepo/auth/package.json

@@ -16,7 +16,7 @@
     "db:migrate": "drizzle-kit migrate"
   },
   "dependencies": {
-    "@percepta/auth": "^0.1.4",
+    "@percepta/auth": "^0.1.7",
     "better-auth": "^1.6.4",
     "drizzle-orm": "^0.45.2"
   },

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

@@ -1,120 +1,26 @@
-import { createLazyAuth, createPerceptaAuth } from "@percepta/auth/better-auth";
-import type { BetterAuthOptions } from "better-auth";
-import { admin } from "better-auth/plugins";
-import { genericOAuth, okta } from "better-auth/plugins/generic-oauth";
+import {
+  createLazyAuth,
+  createPerceptaAuthFromEnv,
+  type PerceptaAuthMode,
+} from "@percepta/auth/better-auth";
 import { db } from "./drizzle/db";
 import { accounts } from "./drizzle/schema/auth/accounts";
 import { sessions } from "./drizzle/schema/auth/sessions";
 import { verifications } from "./drizzle/schema/auth/verifications";
 import { users } from "./drizzle/schema/users";
 
-type AuthMode = "username-password" | "google" | "okta";
-
-const DEFAULT_AUTH_MODE: AuthMode = "__AUTH_MODE__" as AuthMode;
-const isBuildPhase = process.env.NEXT_PHASE === "phase-production-build";
-
-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;
-}
-
-function requiredEnv(name: string): string {
-  const value = process.env[name];
-  if (value == null || value.length === 0) {
-    throw new Error(`${name} is required.`);
-  }
-  return value;
-}
-
-function optionalEnv(name: string): string | undefined {
-  const value = process.env[name];
-  return value == null || value.length === 0 ? undefined : value;
-}
-
-function getSecret(): string {
-  if (isBuildPhase) {
-    return "build-placeholder-not-used-at-runtime";
-  }
-
-  return requiredEnv("BETTER_AUTH_SECRET");
-}
-
-function getBaseUrl(): string {
-  return (
-    process.env.BETTER_AUTH_URL ??
-    process.env.APP_BASE_URL ??
-    "http://localhost:3000"
-  );
-}
-
-function getSocialProviders(
-  authMode: AuthMode,
-): BetterAuthOptions["socialProviders"] {
-  if (authMode !== "google") return undefined;
-
-  const clientId = optionalEnv("GOOGLE_CLIENT_ID");
-  const clientSecret = optionalEnv("GOOGLE_CLIENT_SECRET");
-  if (clientId == null || clientSecret == null) return undefined;
-
-  const hostedDomain = optionalEnv("GOOGLE_HOSTED_DOMAIN");
-  return {
-    google: {
-      clientId,
-      clientSecret,
-      ...(hostedDomain == null ? {} : { hd: hostedDomain }),
-    },
-  };
-}
-
-function getPlugins(authMode: AuthMode): BetterAuthOptions["plugins"] {
-  if (authMode !== "okta") return undefined;
-
-  const clientId = optionalEnv("OKTA_CLIENT_ID");
-  const clientSecret = optionalEnv("OKTA_CLIENT_SECRET");
-  const issuer = optionalEnv("OKTA_ISSUER");
-  if (clientId == null || clientSecret == null || issuer == null) {
-    return undefined;
-  }
-
-  return [
-    admin(),
-    genericOAuth({
-      config: [
-        okta({
-          clientId,
-          clientSecret,
-          issuer,
-        }),
-      ],
-    }),
-  ];
-}
+const DEFAULT_AUTH_MODE = "__AUTH_MODE__" satisfies PerceptaAuthMode;
 
 function createAuth() {
-  const authMode = getAuthMode();
-
-  return createPerceptaAuth({
-    baseURL: getBaseUrl(),
+  return createPerceptaAuthFromEnv({
     database: db,
-    emailAndPassword: {
-      enabled: authMode === "username-password",
-    },
-    plugins: getPlugins(authMode),
+    defaultAuthMode: DEFAULT_AUTH_MODE,
     schema: {
       user: users,
       session: sessions,
       account: accounts,
       verification: verifications,
     },
-    secret: getSecret(),
-    socialProviders: getSocialProviders(authMode),
   });
 }
 

package/templates/monorepo/oxlint.config.ts.template

@@ -1,3 +1,7 @@
 import { defineOxlintMonorepoConfig } from "@percepta/build/oxlint";
 
-export default defineOxlintMonorepoConfig();
+export default defineOxlintMonorepoConfig({
+  rules: {
+    "no-console": "error",
+  },
+});

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

@@ -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

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/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

@@ -11,6 +11,10 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { execFileSync } from "node:child_process";
 import * as nextEnvModule from "@next/env";
 import type { SubjectRef } from "@percepta/access-control";
+import {
+  ensurePerceptaAuthModeEnv,
+  type PerceptaAuthMode,
+} from "@percepta/auth/better-auth";
 
 const nextEnv =
   (nextEnvModule as { default?: typeof nextEnvModule }).default ??
@@ -47,7 +51,6 @@ const SEEDED_USERS = [
   },
 ] as const;
 
-type AuthMode = "username-password" | "google" | "okta";
 interface AdminCreateUserApi {
   createUser(input: {
     body: {
@@ -58,24 +61,13 @@ 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;
-}
+const DEFAULT_AUTH_MODE = "__AUTH_MODE__" satisfies PerceptaAuthMode;
 
 async function main(): Promise<void> {
   nextEnv.loadEnvConfig(process.cwd());
-  const authMode = getAuthMode();
-  process.env.AUTH_MODE = authMode;
+  const authMode = ensurePerceptaAuthModeEnv({
+    defaultAuthMode: DEFAULT_AUTH_MODE,
+  });
   // oxlint-disable-next-line typescript/no-explicit-any
   (globalThis as any).AsyncLocalStorage = AsyncLocalStorage;
 
@@ -85,10 +77,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,8 +102,9 @@ 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") {
@@ -135,9 +130,18 @@ async function main(): Promise<void> {
         userId = res.user.id;
       }
 
-      console.log(`Seed user created: ${seededUser.email} (id: ${userId})`);
+      logger.info(
+        { safe: { email: seededUser.email, userId } },
+        "Seed user created.",
+      );
       if (authMode === "username-password") {
-        console.log(`  Password: ${seededUser.password}`);
+        logger.info(
+          {
+            safe: { email: seededUser.email },
+            unsafe: { password: seededUser.password },
+          },
+          "Seed user password configured.",
+        );
       }
     }
 
@@ -145,7 +149,10 @@ async function main(): Promise<void> {
       .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 +176,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,
+  }),
+);

package/templates/webapp/src/drizzle/db.ts

@@ -1,5 +1,5 @@
-import { createPgPool, readDatabaseConfig } from "@percepta/database";
-import { type NodePgDatabase, drizzle } from "drizzle-orm/node-postgres";
+import { createDrizzlePgDatabase } from "@percepta/database";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
 import type { Pool } from "pg";
 import { getEnvConfig } from "../config/getEnvConfig";
 
@@ -7,11 +7,7 @@ export const { client, db } = createDb();
 
 function createDb(): { client: Pool; db: NodePgDatabase } {
   const { DATABASE_URL: databaseUrl, NODE_ENV: nodeEnv } = getEnvConfig();
-  const pool = createPgPool(
-    readDatabaseConfig({
-      env: { DATABASE_URL: databaseUrl, NODE_ENV: nodeEnv },
-    }),
-  );
-
-  return { client: pool, db: drizzle(pool) };
+  return createDrizzlePgDatabase({
+    env: { DATABASE_URL: databaseUrl, NODE_ENV: nodeEnv },
+  });
 }

package/templates/webapp/src/instrumentation.ts

@@ -1,76 +1,9 @@
-import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
-import { NodeSDK, tracing } from "@opentelemetry/sdk-node";
-import { createLangfuseSpanProcessor } from "@percepta/ai";
-import { compact } from "lodash-es";
+import { startPerceptaNodeTelemetry } from "@percepta/ai";
 import { getEnvConfig } from "./config/getEnvConfig";
 import { getLogger } from "./services/logger/AppLogger";
 
-type SpanProcessor = tracing.SpanProcessor;
-
-function setDefaultOpenTelemetryEnv(): void {
-  const { DEPLOYMENT_ENVIRONMENT: deploymentEnvironment, NODE_ENV: nodeEnv } =
-    getEnvConfig();
-
-  process.env.OTEL_SERVICE_NAME ??= "__APP_NAME__";
-  process.env.OTEL_RESOURCE_ATTRIBUTES ??= `deployment.environment=${deploymentEnvironment ?? nodeEnv}`;
-}
-
-function getOtlpTracesEndpoint(): string | undefined {
-  const {
-    OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: tracesEndpoint,
-    OTEL_EXPORTER_OTLP_ENDPOINT: baseEndpoint,
-  } = getEnvConfig();
-
-  if (tracesEndpoint) return tracesEndpoint;
-
-  if (!baseEndpoint) return undefined;
-
-  return `${baseEndpoint.replace(/\/$/, "")}/v1/traces`;
-}
-
-function getOtlpSpanProcessor(): tracing.BatchSpanProcessor | undefined {
-  const { OTEL_TRACES_EXPORTER: tracesExporter } = getEnvConfig();
-  if (tracesExporter === "none") {
-    getLogger().debug(
-      undefined,
-      "OTEL_TRACES_EXPORTER=none. Skipping OTLP trace export.",
-    );
-    return undefined;
-  }
-
-  const tracesEndpoint = getOtlpTracesEndpoint();
-  if (!tracesEndpoint) {
-    getLogger().debug(
-      undefined,
-      "No OTLP trace endpoint found. Skipping OTLP trace export.",
-    );
-    return undefined;
-  }
-
-  getLogger().debug(
-    { safe: { tracesEndpoint } },
-    "Registering OTLP trace exporter.",
-  );
-  return new tracing.BatchSpanProcessor(
-    new OTLPTraceExporter({ url: tracesEndpoint }),
-  );
-}
-
-function getLangfuseSpanProcessor(): SpanProcessor | undefined {
-  return createLangfuseSpanProcessor(getEnvConfig(), getLogger());
-}
-
-setDefaultOpenTelemetryEnv();
-
-const spanProcessors: tracing.SpanProcessor[] = compact([
-  getOtlpSpanProcessor(),
-  getLangfuseSpanProcessor(),
-]);
-
-const sdk = new NodeSDK({
-  spanProcessors,
-  instrumentations: [getNodeAutoInstrumentations()],
+startPerceptaNodeTelemetry({
+  appName: "__APP_NAME__",
+  getEnv: getEnvConfig,
+  getLogger,
 });
-
-sdk.start();

package/templates/webapp/src/lib/auth/app-auth-mode.ts

@@ -1,20 +1,12 @@
-export type AuthMode = "username-password" | "google" | "okta";
+import {
+  ensurePerceptaAuthModeEnv,
+  type PerceptaAuthMode,
+} from "@percepta/auth/better-auth";
 
-const APP_AUTH_MODE: AuthMode = "__AUTH_MODE__" as AuthMode;
-
-function isAuthMode(value: string | undefined): value is AuthMode {
-  return (
-    value === "username-password" || value === "google" || value === "okta"
-  );
-}
+export type AuthMode = PerceptaAuthMode;
 
-export function ensureAppAuthModeEnv(): AuthMode {
-  if (isAuthMode(process.env.AUTH_MODE)) {
-    return process.env.AUTH_MODE;
-  }
-
-  process.env.AUTH_MODE = APP_AUTH_MODE;
-  return APP_AUTH_MODE;
-}
+const APP_AUTH_MODE: AuthMode = "__AUTH_MODE__" as AuthMode;
 
-export const AUTH_MODE = ensureAppAuthModeEnv();
+export const AUTH_MODE = ensurePerceptaAuthModeEnv({
+  defaultAuthMode: APP_AUTH_MODE,
+});

package/templates/webapp/src/services/DatabaseService.ts

@@ -1,53 +1,5 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { createTransactionalDatabaseServiceFactory } from "@percepta/database";
 import { db } from "../drizzle/db";
 
-export class DatabaseService {
-  private static SINGLETON: DatabaseService | undefined;
-  public static create(): DatabaseService {
-    if (DatabaseService.SINGLETON == null) {
-      DatabaseService.SINGLETON = new DatabaseService(db);
-    }
-
-    return DatabaseService.SINGLETON;
-  }
-
-  private transactionAsyncLocalStorage = new AsyncLocalStorage<LocalStorage>();
-
-  private constructor(private database: NodePgDatabase) {}
-
-  public async createTransaction<TReturn>(
-    callback: (txn: NodePgDatabase) => Promise<TReturn>,
-  ): Promise<TReturn> {
-    const currentContext = this.transactionAsyncLocalStorage.getStore();
-    if (currentContext != null) {
-      const { txn } = currentContext;
-
-      // Already in a transaction.
-      return callback(txn);
-    }
-
-    return this.database.transaction((txn) => {
-      return this.transactionAsyncLocalStorage.run<Promise<TReturn>>(
-        { txn },
-        () => callback(txn),
-      );
-    });
-  }
-
-  public getDatabase(): Database {
-    const context = this.transactionAsyncLocalStorage.getStore();
-    if (context == null) {
-      return this.database;
-    }
-
-    const { txn } = context;
-    return txn;
-  }
-}
-
-type Database = Omit<NodePgDatabase, "transaction">;
-
-interface LocalStorage {
-  txn: NodePgDatabase;
-}
+export const DatabaseService = createTransactionalDatabaseServiceFactory(db);
+export type DatabaseService = ReturnType<typeof DatabaseService.create>;

package/templates/webapp/src/services/observability/initFaro.ts

@@ -1,22 +1,10 @@
 "use client";
 
-import { TracingInstrumentation } from "@grafana/faro-web-tracing";
-import { createFaroInstance } from "@percepta/next-utils/faro";
+import { createPerceptaFaroInstance } from "@percepta/next-utils/faro";
 import { getClientEnvConfig } from "../../config/clientEnvConfig";
 
-const {
-  FARO_COLLECTOR_URL,
-  FARO_APP_NAME,
-  FARO_APP_VERSION,
-  FARO_APP_ENVIRONMENT,
-} = getClientEnvConfig();
-
-export const faroInstance = createFaroInstance({
-  collectorUrl: FARO_COLLECTOR_URL,
-  app: {
-    name: FARO_APP_NAME,
-    version: FARO_APP_VERSION,
-    environment: FARO_APP_ENVIRONMENT,
-  },
-  extraInstrumentations: [new TracingInstrumentation()],
+export const faroInstance = createPerceptaFaroInstance({
+  defaultAppName: "__APP_NAME__",
+  defaultEnvironment: process.env.NODE_ENV,
+  env: getClientEnvConfig(),
 });

package/templates/monorepo/scripts/setup-local-databases.mjs

@@ -1,183 +0,0 @@
-#!/usr/bin/env node
-
-import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const LOCAL_POSTGRES_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
-const LOCAL_POSTGRES_PORT = "5434";
-const POSTGRES_SERVICE = "postgres";
-const POSTGRES_USER = "postgres";
-const ROOT_DIR = path.resolve(
-  path.dirname(fileURLToPath(import.meta.url)),
-  "..",
-);
-const PACKAGES_DIR = path.join(ROOT_DIR, "packages");
-
-const databases = new Set(["auth"]);
-
-for (const packageDir of listPackageDirs()) {
-  const database = readPackageDatabaseName(packageDir);
-  if (database != null) {
-    databases.add(database);
-  }
-}
-
-for (const database of [...databases].sort()) {
-  ensureDatabase(database);
-}
-
-function listPackageDirs() {
-  if (!existsSync(PACKAGES_DIR)) return [];
-
-  return readdirSync(PACKAGES_DIR, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => packageDirFor(entry.name));
-}
-
-function packageDirFor(packageName) {
-  if (
-    packageName === "." ||
-    packageName === ".." ||
-    packageName.includes("/") ||
-    packageName.includes("\\")
-  ) {
-    throw new Error(`Unexpected package directory name: ${packageName}`);
-  }
-
-  return path.join(PACKAGES_DIR, packageName);
-}
-
-function readPackageDatabaseName(packageDir) {
-  const env = readPackageEnvFile(packageDir);
-  const databaseUrl = env.DATABASE_URL;
-  if (databaseUrl == null || databaseUrl.length === 0) return null;
-
-  let url;
-  try {
-    url = new URL(databaseUrl);
-  } catch {
-    throw new Error(
-      `Invalid DATABASE_URL in ${path.relative(ROOT_DIR, packageDir)}/.env.local`,
-    );
-  }
-
-  if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") {
-    throw new Error(
-      `DATABASE_URL in ${path.relative(ROOT_DIR, packageDir)}/.env.local must use postgres or postgresql.`,
-    );
-  }
-
-  const port = url.port || "5432";
-  if (!LOCAL_POSTGRES_HOSTS.has(url.hostname) || port !== LOCAL_POSTGRES_PORT) {
-    console.log(
-      `Skipping non-local app database for ${path.relative(ROOT_DIR, packageDir)}.`,
-    );
-    return null;
-  }
-
-  const database = decodeURIComponent(url.pathname.replace(/^\/+/, ""));
-  if (database.length === 0) {
-    throw new Error(
-      `DATABASE_URL in ${path.relative(ROOT_DIR, packageDir)}/.env.local must include a database name.`,
-    );
-  }
-
-  return database;
-}
-
-function readPackageEnvFile(packageDir) {
-  const safePackageDir = assertPackageDir(packageDir);
-  const envPath = path.join(safePackageDir, ".env.local");
-  if (!existsSync(envPath)) return {};
-
-  const env = {};
-  const content = readFileSync(envPath, "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 assertPackageDir(packageDir) {
-  const resolvedPackageDir = path.resolve(packageDir);
-  const relative = path.relative(PACKAGES_DIR, resolvedPackageDir);
-
-  if (
-    relative.length === 0 ||
-    relative.startsWith("..") ||
-    path.isAbsolute(relative) ||
-    relative.includes(path.sep)
-  ) {
-    throw new Error(`Unexpected package directory: ${packageDir}`);
-  }
-
-  return resolvedPackageDir;
-}
-
-function unquote(value) {
-  if (
-    (value.startsWith('"') && value.endsWith('"')) ||
-    (value.startsWith("'") && value.endsWith("'"))
-  ) {
-    return value.slice(1, -1);
-  }
-
-  return value;
-}
-
-function ensureDatabase(database) {
-  const exists = execDockerCompose([
-    "exec",
-    "-T",
-    POSTGRES_SERVICE,
-    "psql",
-    "-U",
-    POSTGRES_USER,
-    "-d",
-    "postgres",
-    "-tAc",
-    `SELECT 1 FROM pg_database WHERE datname = ${quotePgLiteral(database)}`,
-  ]).trim();
-
-  if (exists === "1") {
-    console.log(`Database ${database} already exists.`);
-    return;
-  }
-
-  execDockerCompose([
-    "exec",
-    "-T",
-    POSTGRES_SERVICE,
-    "createdb",
-    "-U",
-    POSTGRES_USER,
-    database,
-  ]);
-  console.log(`Database ${database} created.`);
-}
-
-function execDockerCompose(args) {
-  return execFileSync("docker", ["compose", ...args], {
-    cwd: ROOT_DIR,
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "inherit"],
-  });
-}
-
-function quotePgLiteral(value) {
-  return `'${value.replaceAll("'", "''")}'`;
-}

package/templates/webapp/src/drizzle/schema/utils/jsonbFromZod.ts

@@ -1,25 +0,0 @@
-import { customType } from "drizzle-orm/pg-core";
-import type { z } from "zod";
-
-export function jsonbFromZod<TValue>(schema: z.Schema<TValue>): ReturnType<
-  typeof customType<{
-    data: TValue;
-    driverData: string;
-  }>
-> {
-  return customType<{
-    data: TValue;
-    driverData: string;
-  }>({
-    dataType() {
-      return "jsonb";
-    },
-    toDriver(value) {
-      return JSON.stringify(schema.parse(value));
-    },
-    fromDriver(raw) {
-      const parsed = schema.parse(raw);
-      return parsed;
-    },
-  });
-}