@percepta/create 3.0.0

package/templates/webapp/AGENTS.md

@@ -0,0 +1,240 @@
+# Webapp Template
+
+Next.js 15 full-stack application scaffolded from the Mosaic webapp template via `@percepta/create`. Uses React 19, TypeScript, Tailwind CSS v4, tRPC, Drizzle ORM, Better Auth, and Inngest.
+
+## Build & Dev Commands
+
+- `pnpm dev` — start dev server with Turbopack
+- `pnpm build` — production build
+- `pnpm lint` — run ESLint
+- `pnpm test` — run Vitest tests
+- `pnpm docker:up` / `pnpm docker:down` — start/stop PostgreSQL
+- `pnpm db:generate` — generate Drizzle migrations
+- `pnpm db:migrate` — apply migrations
+- `pnpm db:setup-and-migrate` — create DB + migrate
+- `pnpm db:studio` — open Drizzle Studio
+- `pnpm db:seed` — seed default dev user (admin@example.com / password)
+
+**Package manager**: Always use `pnpm`, never `npm` or `yarn`.
+
+## Code Style
+
+- Double quotes for strings
+- `no-console` is enforced — use `@percepta/logger` instead (see below)
+- Logger messages must be plain string literals, not variables or templates
+- `no-process-env` is enforced — use `getEnvConfig()` from `src/config/`
+- Use `@percepta/design` components before writing custom UI
+- Use `AsyncContent` from `@percepta/components` for loading/error states
+- Tailwind CSS for all styling; icons from `lucide-react`
+
+## Project Structure
+
+```
+src/                        # Application source
+├── app/                    # Next.js App Router pages, layouts, and API route handlers
+├── components/             # React components
+├── config/                 # Env config (clientEnvConfig, getEnvConfig)
+├── drizzle/                # Schema definitions & SQL migrations
+│   ├── schema/
+│   └── migrations/
+├── lib/                    # Auth config, tRPC client, API middleware
+├── server/                 # tRPC router definitions
+│   ├── trpc.ts             # Context & procedure builders
+│   └── api/root.ts         # Root appRouter
+├── services/
+│   ├── inngest/            # Background job definitions
+│   ├── langfuse/           # LLM observability
+│   ├── logger/             # App logger setup (wraps @percepta/logger)
+│   └── observability/      # OpenTelemetry setup
+└── utils/                  # Helpers (cn, pathEncryption, etc.)
+
+deploy/                     # Infrastructure-as-code for Ryvn deployments
+└── ryvn/
+    ├── __APP_NAME__.service.yaml                                       # Ryvn Service definition
+    └── environments/<env>/installations/__APP_NAME__.env.<env>.serviceinstallation.yaml
+```
+
+## @percepta Packages
+
+### @percepta/design — UI Component Library
+
+47+ accessible components built on Radix UI. Import styles and theme in your app:
+
+```tsx
+// src/app/layout.tsx
+import "@percepta/design/styles";
+
+// src/styles/globals.css
+@import "@percepta/design/theme";
+```
+
+**Tailwind v4 + globals.css:** This project uses Tailwind CSS v4, which is CSS-based — there is no `tailwind.config.js`. Do not create one.
+
+- Import order in globals.css matters: `@import "tailwindcss"` must come before `@import "@percepta/design/theme"` so design tokens layer correctly
+- Custom theme values go in the `@theme inline` block in CSS, not a JS config file
+- Use `@import "tailwindcss"`, not the old v3 directives (`@tailwind base`, `@tailwind components`, `@tailwind utilities`)
+
+Import components directly:
+
+```tsx
+import {
+  Button, Dialog, DropdownMenu, Select, Tabs,
+  Input, Checkbox, Switch, Card, Badge, Table,
+  Tooltip, Popover, Accordion, Avatar, Calendar,
+  // ... 47+ components available
+} from "@percepta/design";
+```
+
+Also includes composite components: `ButtonWithDropdown`, `Combobox`, `IconButton`, `InputGroup`, `MosaicDialog`, `MarkdownEditor`.
+
+**Discovering components and props:** These are shadcn-style components wrapping Radix UI, shipped as an npm package. To explore what's available:
+
+- Full export list: read `node_modules/@percepta/design/dist/src/index.d.ts`
+- Component props and variants: read `node_modules/@percepta/design/dist/src/components/ui/<name>.d.ts` (e.g., `button.d.ts`)
+- Composite components: `node_modules/@percepta/design/dist/src/components/composite/<Name>.d.ts`
+- Props follow standard Radix UI patterns — if you know Radix, you know these components
+
+### @percepta/build — Shared Build Configs
+
+Provides centralized ESLint, Prettier, TypeScript, 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...
+];
+```
+
+```json
+// tsconfig.json
+{ "extends": "@percepta/build/tsconfig/web" }
+```
+
+Vitest config is also available via `@percepta/build/vitest`.
+
+### @percepta/components — React Utilities
+
+Async data handling and hooks for React Query:
+
+- **`AsyncContent<T>`** — renders loading spinner, error state, or children based on a React Query result. Use this for all data-fetching UI.
+- **`AsyncArrayContent<T[]>`** — same but for multiple parallel queries
+- **`ErrorContainer`** — consistent error display
+- **`useBoolean`** — boolean state with `setTrue`, `setFalse`, `toggle`
+- **`useDebouncedUpdate`** — debounced value updates with callback
+- **`useSafeParseQueryParams`** — Zod-based URL query param validation
+
+### @percepta/logger — Structured Logging
+
+PII-safe logging with `safe`/`unsafe` field separation. Unsafe data is automatically redacted.
+
+```tsx
+import { getLogger } from "@/services/logger/AppLogger";
+const logger = getLogger();
+
+// safe data appears as-is; unsafe data (PII) is redacted
+logger.info({ safe: { requestId }, unsafe: { email } }, "User action completed");
+
+// errors go as the third argument
+logger.error({ safe: { documentId } }, "Processing failed", error);
+```
+
+The app's logger is initialized in `src/services/logger/AppLogger.ts` using `createLogFactory()` and `createTracerFactory()` from this package. It uses `AsyncLocalStorage` for automatic request context propagation.
+
+### @percepta/utils — Shared Utilities
+
+- **`assertNever(value)`** — TypeScript exhaustiveness check (throws on impossible cases)
+- **`batchAsync(items, fn, concurrency)`** — process items in batched parallel
+- **`getEnvConfig()`** — typed environment variable loading
+- **`zodKeyedTypeUnion()`** — Zod schemas for discriminated unions
+
+### @percepta/next-utils — Next.js Middleware
+
+Request context management and observability for Next.js:
+
+- **`createRequestContextMiddleware()`** — middleware that adds `X-Request-ID` headers
+- **`withRequestContext(handler)`** — wraps Pages Router API handlers
+- **`withAppRouterRequestContext(handler)`** — wraps App Router handlers
+- **`getRequestId()`** — extracts or generates request IDs
+- **Faro integration** — `@percepta/next-utils/faro` for Grafana frontend observability
+
+### @percepta/chat-components — Agent Chat UI
+
+Pre-built components for conversational AI interfaces:
+
+- **`ChatContainer`** — main chat wrapper (manages agent slug, threads, messages)
+- **`MessageList`** — renders message history
+- **`MessageSender`** — input UI for sending messages
+- **`MosaicContextProvider`** — context provider for chat state
+- Hooks: `useCreateThread`, `useMessages`, `useSendMessage`
+
+Requires `@percepta/mosaic-typescript-sdk` as a peer dependency.
+
+## Skill Guides
+
+Detailed how-to guides for each major stack component. Read the relevant guide when working with that technology.
+
+| Guide | File | When to read |
+|-------|------|-------------|
+| Background Jobs (Inngest) | [agent-skills/inngest.md](agent-skills/inngest.md) | Adding async tasks, scheduled jobs, or agent workflows |
+| LLM Observability (Langfuse) | [agent-skills/langfuse.md](agent-skills/langfuse.md) | App uses LLMs and needs trace/eval monitoring |
+| Database (Drizzle) | [agent-skills/database.md](agent-skills/database.md) | Adding tables, writing migrations, querying data |
+| Deployment (Ryvn) | [agent-skills/ryvn.md](agent-skills/ryvn.md) | Ryvn overview and Percepta environment context |
+| Deploy to percepta-test | [agent-skills/deploy.md](agent-skills/deploy.md) | Step-by-step deploy using the pre-scaffolded `deploy/ryvn/` IaC files |
+| Build App (Oneshot) | [agent-skills/oneshot.md](agent-skills/oneshot.md) | Building a complete app from requirements end-to-end |
+
+## Key Patterns
+
+### tRPC
+
+Type-safe API layer. Define routers in `src/server/api/`, compose in `root.ts`:
+
+```tsx
+// src/server/api/root.ts
+import { router } from "../trpc";
+export const appRouter = router({ /* add routers here */ });
+export type AppRouter = typeof appRouter;
+```
+
+Client-side usage via `src/lib/trpc.ts`.
+
+### Authentication
+
+Better Auth configured in `src/lib/auth/`. Email/password credentials enabled by default.
+
+- **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 out**: `authClient.signOut()` — client-side
+- **API route**: `src/app/api/auth/[...all]/route.ts` — Better Auth handler
+- **Env vars**: `BETTER_AUTH_SECRET` (required), `BETTER_AUTH_URL` (defaults to `http://localhost:3000`)
+
+### Background Jobs
+
+Inngest for async task processing. Define functions in `src/services/inngest/`. Configure via `INNGEST_*` env vars.
+
+### Database
+
+PostgreSQL with Drizzle ORM. Schema in `src/drizzle/schema/`, migrations in `src/drizzle/migrations/`. Connection managed by `src/services/DatabaseService.ts`.
+
+### Observability
+
+OpenTelemetry initialized in `src/instrumentation.ts`. Langfuse for LLM tracking in `src/services/langfuse/`. Faro for frontend monitoring via `@percepta/next-utils/faro`.
+
+## Deployment
+
+To deploy this app to percepta-test, follow [agent-skills/deploy.md](agent-skills/deploy.md). The Ryvn service definition and percepta-test installation YAML are already scaffolded at `deploy/ryvn/` with all values filled in — deploy is mostly "copy these two files into the infra repo, open a PR, set three secrets in the Ryvn UI."
+
+The release CI/CD workflow is already included at `.github/workflows/ryvn-release.yaml`.
+
+For Ryvn CLI operations, use the `/use-ryvn` skill.
+
+## Template Sync
+
+This app tracks its template origin in `.mosaic-template.json`. Two Claude commands are available:
+
+- **`/sync`** — pull downstream changes from the mosaic template into this app
+- **`/upstream`** — propose app improvements back to the mosaic template
+
+Both commands use `@percepta/create` CLI under the hood. Check `mosaic-template-notes.md` for documented intentional divergences from the template.

package/templates/webapp/Dockerfile

@@ -0,0 +1,64 @@
+# Base image with PNPM:
+ARG NODE_VERSION=24.4.1
+FROM node:${NODE_VERSION}-slim AS base
+WORKDIR /app
+RUN npm install -g pnpm
+
+# Build stage:
+FROM base AS builder
+
+COPY . .
+
+# Create .npmrc with build-time token for private packages:
+ARG NPM_TOKEN
+RUN echo "@percepta:registry=https://registry.npmjs.org/" > .npmrc && \
+    echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" >> .npmrc
+
+# Add BASE_PATH as a build argument
+ARG BASE_PATH
+ENV BASE_PATH=${BASE_PATH}
+
+RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
+
+RUN NODE_ENV=production NODE_OPTIONS="--max-old-space-size=4096" pnpm build
+
+# Remove .npmrc for security (contains auth token):
+RUN rm -f .npmrc
+
+# Production stage - create the final image:
+FROM base AS production
+
+# Install PostgreSQL client:
+USER root
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        postgresql-client \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set production environment:
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+
+# Copy BASE_PATH from the builder stage
+ENV BASE_PATH=${BASE_PATH}
+
+# Copy built app from builder stage
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/.next/static ./.next/static
+COPY --from=builder /app/public ./public
+
+# Copy scripts and source files needed for start.sh and runtime
+COPY --from=builder /app/scripts ./scripts
+COPY --from=builder /app/src ./src
+COPY --from=builder /app/node_modules ./node_modules
+
+
+# Expose the port:
+EXPOSE 3000
+
+# Set correct permissions and user:
+RUN chown -R 1000:1000 /app && chmod +x /app/scripts/start.sh
+USER 1000
+
+# Start the application:
+CMD ["./scripts/start.sh"]

package/templates/webapp/README.md

@@ -0,0 +1,200 @@
+# __APP_TITLE__
+
+A production-ready Next.js application with authentication, database, logging, background jobs, and infrastructure as code.
+
+## Features
+
+- **Next.js 15** with App Router
+- **Authentication** via Better Auth with email/password credentials
+- **Database** with PostgreSQL, Drizzle ORM, and migrations
+- **Logging** with Pino and structured safe/unsafe data separation
+- **Background Jobs** with Inngest
+- **Observability** with OpenTelemetry and Langfuse integration
+- **Infrastructure** with Terraform modules for AWS (RDS, S3, IAM)
+- **Type Safety** with TypeScript and Zod schemas
+
+## Quick Start
+
+### 1. Start the Database
+
+```bash
+pnpm docker:up
+```
+
+### 2. Initialize the Database
+
+```bash
+pnpm db:setup-and-migrate
+```
+
+### 3. Configure Environment
+
+Copy `.env.example` to `.env.local` and configure your environment variables.
+
+### 4. Start Development Server
+
+```bash
+pnpm dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to see your app.
+
+## Project Structure
+
+```
+src/
+├── app/                    # Next.js App Router pages, layouts, and API route handlers
+├── components/             # React components
+├── config/                 # Environment configuration
+├── drizzle/                # Database schema and migrations
+├── hooks/                  # Custom React hooks
+├── lib/                    # Authentication and utilities
+├── server/                 # tRPC routers
+├── services/               # Business logic services
+│   ├── inngest/            # Background job definitions
+│   ├── langfuse/           # LLM observability
+│   └── logger/             # Structured logging
+└── utils/                  # Utility functions
+```
+
+## Available Scripts
+
+| Script | Description |
+|--------|-------------|
+| `pnpm dev` | Start development server with Turbopack |
+| `pnpm build` | Build for production |
+| `pnpm start` | Start production server |
+| `pnpm lint` | Run ESLint |
+| `pnpm docker:up` | Start PostgreSQL container |
+| `pnpm docker:down` | Stop PostgreSQL container |
+| `pnpm db:generate` | Generate Drizzle migrations |
+| `pnpm db:migrate` | Run database migrations |
+| `pnpm db:setup` | Create database and user |
+| `pnpm db:setup-and-migrate` | Setup and migrate database |
+| `pnpm db:studio` | Open Drizzle Studio |
+| `pnpm db:create-user` | Create a user account |
+| `pnpm db:seed` | Seed default dev user |
+
+## Logging
+
+This template uses structured logging with safe/unsafe data separation to protect PII:
+
+```typescript
+import { getLogger } from "@/services/logger/AppLogger";
+
+const logger = getLogger();
+
+// Safe data appears as-is in logs
+// Unsafe data (PII) is redacted
+logger.info(
+  { safe: { requestId }, unsafe: { email } },
+  "User action completed"
+);
+
+// Errors should be passed as the third parameter
+logger.error(
+  { safe: { documentId } },
+  "Processing failed",
+  error
+);
+```
+
+## Authentication
+
+This app uses [Better Auth](https://better-auth.com) for authentication with email/password credentials enabled by default.
+
+Required environment variables:
+
+```bash
+BETTER_AUTH_SECRET=generate-with-openssl-rand-base64-32
+BETTER_AUTH_URL=http://localhost:3000
+```
+
+To create a dev user:
+```bash
+pnpm db:seed
+# Creates admin@example.com / password
+```
+
+## Environment Variables
+
+### Application
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NODE_ENV` | Environment mode | `development` |
+| `APP_BASE_URL` | Base URL for the app | - |
+
+### Database
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DATABASE_HOST` | PostgreSQL host | `localhost` |
+| `DATABASE_PORT` | PostgreSQL port | `5434` |
+| `DATABASE_USERNAME` | Database user | `postgres` |
+| `DATABASE_PASSWORD` | Database password | `postgres` |
+| `DATABASE_NAME` | Database name | `__DB_NAME__` |
+| `DATABASE_USE_SSL` | Enable SSL | `false` |
+
+### Security
+
+| Variable | Description |
+|----------|-------------|
+| `ENCRYPTION_SECRET_KEY` | 32-character key for URL encryption |
+
+Generate a secret key:
+```bash
+node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"
+```
+
+### Inngest (Background Jobs)
+
+| Variable | Description |
+|----------|-------------|
+| `INNGEST_BASE_URL` | Inngest server URL |
+| `INNGEST_SIGNING_KEY` | Inngest signing key |
+| `INNGEST_EVENT_KEY` | Inngest event key |
+
+### Langfuse (LLM Observability)
+
+| Variable | Description |
+|----------|-------------|
+| `LANGFUSE_BASE_URL` | Langfuse server URL |
+| `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
+| `LANGFUSE_SECRET_KEY` | Langfuse secret key |
+
+## Local AWS Development
+
+This application uses the default AWS SDK credential provider chain:
+
+1. **Environment Variables**:
+   - `AWS_ACCESS_KEY_ID`
+   - `AWS_SECRET_ACCESS_KEY`
+   - `AWS_SESSION_TOKEN` (optional)
+   - `AWS_REGION` (defaults to `us-east-1`)
+
+2. **AWS Credentials File**: Run `aws configure` or `aws sso login`
+
+## Infrastructure (Terraform)
+
+The `terraform/` directory contains modules for AWS infrastructure:
+
+- **RDS**: PostgreSQL database
+- **S3**: File storage with logging
+- **Networking**: VPC endpoints
+- **Secrets**: AWS Secrets Manager
+- **IAM**: Roles and policies
+
+See `terraform/README.md` for deployment instructions.
+
+## Learn More
+
+- [Next.js Documentation](https://nextjs.org/docs)
+- [Drizzle ORM](https://orm.drizzle.team)
+- [Better Auth](https://better-auth.com/docs)
+- [Inngest](https://www.inngest.com/docs)
+- [Langfuse](https://langfuse.com/docs)
+
+## License
+
+MIT

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

@@ -0,0 +1,140 @@
+# Database — PostgreSQL + Drizzle ORM
+
+This template uses PostgreSQL as the database and Drizzle ORM as the query builder and migration tool. Drizzle is a TypeScript-first ORM — schemas are defined in TypeScript, queries are type-safe, and migrations are generated as plain SQL files.
+
+## Adding a New Table
+
+### 1. Define the schema
+
+Create a new schema file alongside the existing ones:
+
+```typescript
+import { pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { users } from "./auth/users";
+
+export const documents = pgTable("documents", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  title: text("title").notNull(),
+  content: text("content"),
+  userId: uuid("user_id")
+    .notNull()
+    .references(() => users.id),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull(),
+});
+```
+
+### 2. Export from the schema index
+
+Add a re-export for your new table in the schema index file:
+
+```typescript
+export * from "./documents";
+```
+
+### 3. Generate the migration
+
+```bash
+pnpm db:generate
+```
+
+This creates a new SQL migration file. **Review the generated SQL** — Drizzle generates it automatically but you should verify it's correct.
+
+### 4. Apply the migration
+
+```bash
+pnpm db:migrate
+```
+
+## Querying Data
+
+### Basic queries with DatabaseService
+
+```typescript
+import { DatabaseService } from "@/services/DatabaseService";
+import { documents } from "@/drizzle/schema";
+import { eq } from "drizzle-orm";
+
+const db = DatabaseService.create().getDatabase();
+
+// Select
+const docs = await db.select().from(documents).where(eq(documents.userId, userId));
+
+// Insert
+await db.insert(documents).values({ title: "New Doc", userId });
+
+// Update
+await db.update(documents).set({ title: "Updated" }).where(eq(documents.id, docId));
+
+// Delete
+await db.delete(documents).where(eq(documents.id, docId));
+```
+
+### Transactions
+
+`DatabaseService` propagates transactions via `AsyncLocalStorage` — any code running inside `createTransaction` automatically uses the same transaction, even across nested function calls:
+
+```typescript
+const dbService = DatabaseService.create();
+
+await dbService.createTransaction(async (txn) => {
+  // These both run in the same transaction
+  await txn.insert(documents).values({ title: "Doc 1", userId });
+  await txn.insert(documents).values({ title: "Doc 2", userId });
+
+  // If any nested function calls dbService.getDatabase(),
+  // it gets the same transaction — not a new connection
+});
+```
+
+If `createTransaction` is called while already inside a transaction, it reuses the existing one (no nested transactions).
+
+## Running PostgreSQL Locally
+
+### Start with Docker Compose
+
+```bash
+pnpm docker:up
+```
+
+This starts PostgreSQL 16 on port **5434** (not the default 5432, to avoid conflicts).
+
+### Create the database and run migrations
+
+```bash
+pnpm db:setup-and-migrate
+```
+
+This creates the database if it doesn't exist and applies all pending migrations.
+
+### Inspect the database
+
+```bash
+pnpm db:studio
+```
+
+Opens Drizzle Studio in the browser — a visual database explorer.
+
+### Stop PostgreSQL
+
+```bash
+pnpm docker:down
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DATABASE_HOST` | `localhost` | PostgreSQL host |
+| `DATABASE_PORT` | `5434` | PostgreSQL port |
+| `DATABASE_USERNAME` | `postgres` | Database user |
+| `DATABASE_PASSWORD` | `postgres` | Database password |
+| `DATABASE_NAME` | `__DB_NAME__` | Database name |
+| `DATABASE_USE_SSL` | `false` | Enable SSL connections |
+
+## Key Concepts
+
+- **Schemas are TypeScript, migrations are SQL.** You define tables in TS, then `pnpm db:generate` creates the SQL diff. Never hand-write migration SQL.
+- **DatabaseService is a singleton.** Call `DatabaseService.create()` anywhere — it always returns the same instance with the same connection pool.
+- **Transaction propagation is automatic.** Code inside `createTransaction` gets a transaction; code outside gets the raw connection. `getDatabase()` returns whichever is active.
+- **Port 5434.** The local Docker Compose uses port 5434 to avoid conflicting with any system PostgreSQL on 5432.