@percepta/create 3.0.0

package/templates/webapp/deploy/ryvn/environments/percepta-test/installations/__APP_NAME__.env.percepta-test.serviceinstallation.yaml

@@ -0,0 +1,121 @@
+kind: ServiceInstallation
+metadata:
+  name: __APP_NAME__
+spec:
+  service: __APP_NAME__
+  environment: percepta-test
+  config: |
+    replicaCount: 1
+
+    service:
+      port: 3000
+
+    livenessEnabled: true
+    readinessEnabled: true
+
+    resources:
+      requests:
+        cpu: "100m"
+        memory: "256Mi"
+      limits:
+        cpu: "500m"
+        memory: "512Mi"
+
+    ingress:
+      enabled: true
+      className: external-nginx
+      annotations:
+        cert-manager.io/cluster-issuer: external-issuer
+        nginx.ingress.kubernetes.io/ssl-redirect: "true"
+      hosts:
+        - host: __APP_NAME__.percepta-test.aitco.dev
+          paths:
+            - path: /
+              pathType: Prefix
+      tls:
+        - secretName: __APP_NAME__-tls
+          hosts:
+            - __APP_NAME__.percepta-test.aitco.dev
+
+    env:
+      # Database (shared percepta-test RDS, provisioned by percepta-internal-terraform)
+      - name: DATABASE_HOST
+        valueFrom:
+          secretKeyRef:
+            name: "{{ .ryvn.installations.percepta_internal_terraform.outputs.postgresql_secret_name }}"
+            key: host
+      - name: DATABASE_PORT
+        valueFrom:
+          secretKeyRef:
+            name: "{{ .ryvn.installations.percepta_internal_terraform.outputs.postgresql_secret_name }}"
+            key: port
+      - name: DATABASE_USERNAME
+        valueFrom:
+          secretKeyRef:
+            name: "{{ .ryvn.installations.percepta_internal_terraform.outputs.postgresql_secret_name }}"
+            key: username
+      - name: DATABASE_PASSWORD
+        valueFrom:
+          secretKeyRef:
+            name: "{{ .ryvn.installations.percepta_internal_terraform.outputs.postgresql_secret_name }}"
+            key: password
+      - name: DATABASE_NAME
+        value: "__DB_NAME__"
+      - name: DATABASE_USE_SSL
+        value: "true"
+
+      - name: NODE_ENV
+        value: "production"
+      - name: PORT
+        value: "3000"
+  env:
+    # App identity
+    - key: APP_BASE_URL
+      value: https://__APP_NAME__.percepta-test.aitco.dev
+    - key: BETTER_AUTH_URL
+      value: https://__APP_NAME__.percepta-test.aitco.dev
+
+    # Auth — generated random, set in Ryvn UI (openssl rand -base64 32)
+    - key: BETTER_AUTH_SECRET
+      isSecret: true
+
+    # Encryption — generated random, set in Ryvn UI (openssl rand -hex 16)
+    - key: ENCRYPTION_SECRET_KEY
+      isSecret: true
+
+    # Inngest (shared percepta-test instance)
+    - key: INNGEST_BASE_URL
+      value: http://inngest.percepta-test.svc.cluster.local:8288
+    - key: INNGEST_EVENT_KEY
+      value: c0766e61c95af6afd18911698080b4fea4d311f60b02033d673234ded333ff39
+    - key: INNGEST_SIGNING_KEY
+      value: signkey-dev-7782b39265d2ca61d083fe1b230b468b10f01434d49486051fd108363da736f2
+    - key: INNGEST_APP_URL
+      value: http://__APP_NAME__-web-server.percepta-test.svc.cluster.local:3000/api/inngest
+    - key: INNGEST_SERVE_HOST
+      value: http://__APP_NAME__-web-server.percepta-test.svc.cluster.local:3000/api/inngest
+
+    # Langfuse (shared percepta-test instance) — secret key set in Ryvn UI from 1Password
+    - key: LANGFUSE_BASE_URL
+      value: https://percepta-test.aitco.dev/evals
+    - key: LANGFUSE_PUBLIC_KEY
+      value: pk-lf-cc45f2c9-5286-4966-849b-42fd45059390
+    - key: LANGFUSE_SECRET_KEY
+      isSecret: true
+
+    # OpenTelemetry
+    - key: OTEL_METRICS_EXPORTER_OTLP_ENDPOINT
+      value: http://otel-collector-opentelemetry-collector.percepta-test.svc.cluster.local:4318/v1/metrics
+    - key: OTEL_EXPORT_INTERVAL_MS
+      value: "60000"
+    - key: LOG_LEVEL
+      value: debug
+
+  # Set the values for these in the Ryvn UI after the infra PR merges:
+  #   BETTER_AUTH_SECRET    — generate: openssl rand -base64 32
+  #   ENCRYPTION_SECRET_KEY — generate: openssl rand -hex 16
+  #   LANGFUSE_SECRET_KEY   — copy from 1Password "Percepta Test Secrets"
+  secrets:
+    - name: BETTER_AUTH_SECRET
+    - name: ENCRYPTION_SECRET_KEY
+    - name: LANGFUSE_SECRET_KEY

package/templates/webapp/docker-compose.yml

@@ -0,0 +1,19 @@
+services:
+  postgres:
+    image: postgres:16
+    ports:
+      - "5434:5432"
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: __DB_NAME__
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d __DB_NAME__"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres_data: {}

package/templates/webapp/drizzle.config.ts

@@ -0,0 +1,30 @@
+import { loadEnvConfig } from "@next/env";
+import type { Config } from "drizzle-kit";
+import { getEnvConfig } from "./src/config/getEnvConfig";
+
+loadEnvConfig(process.cwd());
+
+const {
+  DATABASE_HOST: host,
+  DATABASE_PORT: port,
+  DATABASE_USERNAME: user,
+  DATABASE_PASSWORD: password,
+  DATABASE_NAME: database,
+  DATABASE_USE_SSL: useSSL,
+} = getEnvConfig();
+
+const config: Config = {
+  schema: "./src/drizzle/schema",
+  out: "./src/drizzle/migrations",
+  dialect: "postgresql",
+  dbCredentials: {
+    host,
+    port,
+    user,
+    password,
+    database,
+    ssl: useSSL ? "require" : false,
+  },
+};
+
+export default config;

package/templates/webapp/env.example.template

@@ -0,0 +1,44 @@
+# Application
+NODE_ENV=development
+APP_BASE_URL=http://localhost:3000
+
+# Database
+DATABASE_HOST=localhost
+DATABASE_PORT=5434
+DATABASE_USERNAME=postgres
+DATABASE_PASSWORD=postgres
+DATABASE_NAME=__DB_NAME__
+DATABASE_USE_SSL=false
+
+# Authentication (Better Auth)
+BETTER_AUTH_SECRET=generate-with-openssl-rand-base64-32
+BETTER_AUTH_URL=http://localhost:3000
+
+# Security
+ENCRYPTION_SECRET_KEY=generate-with-node-e-console-log-require-crypto-randomBytes-16-toString-hex
+
+# Inngest (Background Jobs)
+# INNGEST_BASE_URL=
+# INNGEST_SIGNING_KEY=
+# INNGEST_EVENT_KEY=
+
+# Grafana Faro (client-side observability)
+# Leave NEXT_PUBLIC_FARO_COLLECTOR_URL empty to disable in local development.
+# In production, point to your Grafana Alloy receiver endpoint.
+NEXT_PUBLIC_FARO_COLLECTOR_URL=
+NEXT_PUBLIC_FARO_APP_NAME=__APP_NAME__
+NEXT_PUBLIC_FARO_APP_VERSION=0.0.0
+NEXT_PUBLIC_FARO_APP_ENVIRONMENT=development
+
+# Langfuse (LLM Observability)
+# LANGFUSE_BASE_URL=
+# LANGFUSE_PUBLIC_KEY=
+# LANGFUSE_SECRET_KEY=
+
+# AWS (uses default credential chain in development)
+# AWS_REGION=us-east-1
+# AWS_ACCESS_KEY_ID=
+# AWS_SECRET_ACCESS_KEY=
+
+# NPM (for installing @percepta packages)
+# NPM_TOKEN=

package/templates/webapp/eslint.config.mjs

@@ -0,0 +1,52 @@
+// @ts-check
+import nextPlugin from "@next/eslint-plugin-next";
+import createEslintConfig from "@percepta/build/eslint";
+import nodePlugin from "eslint-plugin-n";
+
+export default [
+  ...createEslintConfig({
+    type: "react",
+    dirname: import.meta.dirname,
+  }),
+  {
+    ignores: [
+      "pnpm-lock.yaml",
+      ".next/**",
+      "next-env.d.ts",
+      "public/**",
+      "terraform/**",
+    ],
+  },
+  {
+    plugins: {
+      "@next/next": nextPlugin,
+    },
+    rules: {
+      ...nextPlugin.configs.recommended.rules,
+      ...nextPlugin.configs["core-web-vitals"].rules,
+    },
+  },
+  {
+    files: ["src/**/*"],
+    rules: {
+      "no-console": "error",
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "CallExpression[callee.property.name=/^(debug|info|warn|error)$/][callee.object.type='CallExpression'][callee.object.callee.name='getLogger'] > :nth-child(2):not(Literal)",
+          message:
+            "Logger message must be a plain string literal, not a variable or template. Use the first parameter (args) for dynamic data.",
+        },
+      ],
+    },
+  },
+  {
+    plugins: {
+      n: nodePlugin,
+    },
+    rules: {
+      "n/no-process-env": "error",
+    },
+  },
+];

package/templates/webapp/gitignore.template

@@ -0,0 +1,53 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+!.env.example
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# terraform
+.terraform
+.terraform.lock.hcl
+
+# IDE
+.cursor/**/*.log
+
+# mosaic sync (temporary context files)
+.mosaic-sync-context.md
+.mosaic-upstream-context.md

package/templates/webapp/next.config.ts

@@ -0,0 +1,8 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  // Enable standalone output for Docker:
+  output: "standalone",
+};
+
+export default nextConfig;

package/templates/webapp/npmrc.template

@@ -0,0 +1,4 @@
+@percepta:registry=https://registry.npmjs.org/
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+
+engine-strict=true

package/templates/webapp/package.json.template

@@ -0,0 +1,122 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint .",
+    "setup": "pnpm docker:up && pnpm db:setup-and-migrate && pnpm db:seed",
+    "docker:up": "docker compose up -d",
+    "docker:down": "docker compose down",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "tsx ./scripts/migrate.ts",
+    "db:setup": "tsx ./scripts/setup-database.ts",
+    "db:setup-and-migrate": "pnpm db:setup && pnpm db:migrate",
+    "db:setup-readonly": "tsx ./scripts/setup-readonly-user.ts",
+    "db:studio": "drizzle-kit studio",
+    "db:create-user": "tsx ./scripts/create-user.ts",
+    "db:seed": "tsx ./scripts/seed.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^2.0.23",
+    "@aws-sdk/client-s3": "^3.888.0",
+    "@aws-sdk/client-secrets-manager": "^3.914.0",
+    "@aws-sdk/client-sts": "^3.913.0",
+    "@aws-sdk/credential-providers": "^3.913.0",
+    "@aws-sdk/s3-request-presigner": "^3.891.0",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/modifiers": "^9.0.0",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@grafana/faro-react": "^1.14.0",
+    "@grafana/faro-web-sdk": "^1.14.0",
+    "@grafana/faro-web-tracing": "^1.14.0",
+    "@hookform/resolvers": "^5.2.2",
+    "@inngest/middleware-validation": "^0.0.5",
+    "@langfuse/otel": "^4.0.0",
+    "@langfuse/tracing": "^4.0.0",
+    "@mantine/hooks": "^8.3.1",
+    "@next/env": "^15.3.5",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.62.1",
+    "@opentelemetry/sdk-node": "^0.203.0",
+    "@percepta/design": "^0.1.6",
+    "@percepta/components": "^0.0.6",
+    "@percepta/logger": "^0.0.4",
+    "@percepta/next-utils": "^0.1.0",
+    "@percepta/utils": "^0.1.5",
+    "@radix-ui/react-slot": "^1.2.3",
+    "@tanstack/react-query": "^5.81.5",
+    "@tanstack/react-virtual": "^3.13.12",
+    "@trpc/client": "^11.4.3",
+    "@trpc/server": "^11.4.3",
+    "@trpc/tanstack-react-query": "^11.4.3",
+    "ai": "^5.0.24",
+    "better-auth": "^1.6.4",
+    "clsx": "^2.1.1",
+    "date-fns": "^4.1.0",
+    "drizzle-orm": "^0.44.2",
+    "drizzle-zod": "^0.8.3",
+    "formidable": "^3.5.4",
+    "he": "^1.2.0",
+    "import-in-the-middle": "^1.14.2",
+    "inngest": "^3.44.3",
+    "keyed-type-union": "^0.1.0",
+    "langfuse": "^3.38.6",
+    "lodash-es": "^4.17.21",
+    "lucide-react": "^0.542.0",
+    "mime-types": "^3.0.1",
+    "next": "^15.3.5",
+    "numeral": "^2.0.6",
+    "pg": "^8.16.3",
+    "pino": "^10.1.0",
+    "pino-pretty": "^13.1.3",
+    "pluralize": "^8.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-hook-form": "^7.62.0",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "require-in-the-middle": "^7.5.2",
+    "scroll-into-view-if-needed": "^3.1.0",
+    "sonner": "^2.0.7",
+    "superjson": "^2.2.2",
+    "tailwind-merge": "^3.0.2",
+    "tsx": "^4.20.3",
+    "uuid": "^13.0.0",
+    "zod": "^4.1.5"
+  },
+  "devDependencies": {
+    "@next/eslint-plugin-next": "^15.3.5",
+    "@percepta/build": "^0.1.3",
+    "@tailwindcss/postcss": "^4.1.11",
+    "@types/formidable": "^3.4.5",
+    "@types/he": "^1.2.3",
+    "@types/lodash-es": "^4.17.12",
+    "@types/mime-types": "^3.0.1",
+    "@types/node": "^24.1.0",
+    "@types/numeral": "^2.0.5",
+    "@types/pg": "^8.15.4",
+    "@types/pluralize": "^0.0.33",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "@types/yargs": "^17.0.33",
+    "drizzle-kit": "^0.31.4",
+    "eslint": "^9.18.0",
+    "eslint-plugin-n": "^17.23.1",
+    "eslint-plugin-react": "^7.37.4",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "husky": "^9.1.7",
+    "tailwindcss": "^4.0.12",
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.1",
+    "yargs": "^17.7.2"
+  }
+}

package/templates/webapp/postcss.config.mjs

@@ -0,0 +1,5 @@
+const config = {
+  plugins: ["@tailwindcss/postcss"],
+};
+
+export default config;

package/templates/webapp/scripts/create-user.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env tsx
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { loadEnvConfig } from "@next/env";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+async function main(): Promise<void> {
+  loadEnvConfig(process.cwd());
+  globalThis.AsyncLocalStorage = AsyncLocalStorage;
+
+  const { email, password, name } = yargs(hideBin(process.argv))
+    .usage(
+      "Usage: tsx scripts/create-user.ts <email> <password> [--name <name>]",
+    )
+    .command("$0 <email> <password>", "Create a new user.")
+    .positional("email", {
+      type: "string",
+      demandOption: true,
+    })
+    .positional("password", {
+      type: "string",
+      demandOption: true,
+    })
+    .option("name", {
+      alias: "n",
+      describe: "Display name for the user.",
+      type: "string",
+      demandOption: true,
+    })
+    .strict()
+    .help(false)
+    .parseSync();
+
+  // Dynamically load because we need to load the environment variables before importing modules that depend on them.
+  const { auth } = await import("../src/lib/auth");
+
+  // Create user via Better Auth's signUpEmail API (handles password hashing + account creation)
+  const { user } = await auth.api.signUpEmail({
+    body: { email, password, name },
+  });
+
+  console.log(`User "${user.id}" created successfully.`);
+  process.exit(0);
+}
+
+void main();

package/templates/webapp/scripts/migrate.ts

@@ -0,0 +1,18 @@
+import { loadEnvConfig } from "@next/env";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
+
+async function main(): Promise<void> {
+  loadEnvConfig(process.cwd());
+
+  // Dynamically load because we need to load the environment variables before importing modules that depend on them.
+  const { client } = await import("../src/drizzle/db");
+
+  await migrate(drizzle(client), {
+    migrationsFolder: "./src/drizzle/migrations",
+  });
+
+  await client.end();
+}
+
+void main();

package/templates/webapp/scripts/seed.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env tsx
+
+/**
+ * Development seed script.
+ * Creates a default admin user for local development.
+ *
+ * Usage: pnpm db:seed
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { loadEnvConfig } from "@next/env";
+
+const DEFAULT_USER = {
+  email: "admin@example.com",
+  password: "password",
+  name: "Admin User",
+};
+
+async function main(): Promise<void> {
+  loadEnvConfig(process.cwd());
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any
+  (globalThis as any).AsyncLocalStorage = AsyncLocalStorage;
+
+  const { auth } = await import("../src/lib/auth");
+  const { db } = await import("../src/drizzle/db");
+  const { users } = await import("../src/drizzle/schema/auth/users");
+  const { eq, sql } = await import("drizzle-orm");
+
+  // Check if user already exists
+  const [existing] = await db
+    .select({ id: users.id })
+    .from(users)
+    .where(eq(sql`lower(${users.email})`, sql`lower(${DEFAULT_USER.email})`))
+    .limit(1);
+
+  if (existing != null) {
+    await db
+      .update(users)
+      .set({ role: "admin" })
+      .where(eq(users.id, existing.id));
+    console.log(
+      `Seed user "${DEFAULT_USER.email}" already exists (id: ${existing.id}). Ensured admin role.`,
+    );
+    process.exit(0);
+  }
+
+  // Use Better Auth's signUpEmail API to create the user with a hashed password
+  const res = await auth.api.signUpEmail({
+    body: DEFAULT_USER,
+  });
+
+  await db
+    .update(users)
+    .set({ role: "admin" })
+    .where(eq(users.id, res.user.id));
+
+  console.log(`Seed user created: ${DEFAULT_USER.email} (id: ${res.user.id})`);
+  console.log(`  Password: ${DEFAULT_USER.password}`);
+  process.exit(0);
+}
+
+void main();

package/templates/webapp/scripts/setup-database.ts

@@ -0,0 +1,57 @@
+import { loadEnvConfig } from "@next/env";
+import { Pool } from "pg";
+import { getEnvConfig } from "../src/config/getEnvConfig";
+
+async function main(): Promise<void> {
+  loadEnvConfig(process.cwd());
+
+  const {
+    DATABASE_HOST: host,
+    DATABASE_PORT: port,
+    DATABASE_USERNAME: user,
+    DATABASE_PASSWORD: password,
+    DATABASE_NAME: database,
+    DATABASE_USE_SSL: useSSL,
+  } = getEnvConfig();
+
+  console.log(`🔧 Setting up database: ${database}`);
+  console.log(`📍 Host: ${host}:${port}`);
+  console.log(`👤 User: ${user}`);
+
+  // First, connect to the default 'postgres' database to create our target database
+  const adminClient = new Pool({
+    host,
+    port,
+    user,
+    password,
+    database: "postgres", // Connect to default postgres database
+    ssl: useSSL,
+  });
+
+  try {
+    // Check if the target database exists
+    const result = await adminClient.query(
+      "SELECT 1 FROM pg_database WHERE datname = $1",
+      [database],
+    );
+
+    if (result.rows.length === 0) {
+      console.log(`📦 Creating database: ${database}`);
+      // Create the database (note: database names cannot be parameterized)
+      await adminClient.query(`CREATE DATABASE "${database}"`);
+      console.log(`✅ Database ${database} created successfully`);
+    } else {
+      console.log(`✅ Database ${database} already exists`);
+    }
+  } catch (error) {
+    console.error("❌ Error creating database:", error);
+    throw error;
+  } finally {
+    await adminClient.end();
+  }
+}
+
+void main().catch((error) => {
+  console.error("💥 Database setup failed:", error);
+  process.exit(1);
+});