@percepta/create 3.1.2 → 3.1.4

package/templates/webapp/deploy/README.md

@@ -1,65 +1,66 @@
 # Deploy
 
-This directory holds infrastructure-as-code for deploying __APP_TITLE__ to Percepta environments.
+This directory holds Ryvn infrastructure-as-code for deploying __APP_TITLE__ to Percepta environments.
 
 ```
 deploy/
 └── ryvn/
-    ├── __APP_NAME__.service.yaml                                           # Ryvn Service definition
+    ├── __APP_NAME__.service.yaml
+    ├── __APP_NAME__-terraform.service.yaml
     └── environments/
         └── percepta-test/
             └── installations/
-                └── __APP_NAME__.env.percepta-test.serviceinstallation.yaml # percepta-test installation
+                ├── __APP_NAME__.env.percepta-test.serviceinstallation.yaml
+                └── __APP_NAME__-terraform.env.percepta-test.serviceinstallation.yaml
 ```
 
-These files are pre-filled with all base values needed to deploy to `https://__APP_NAME__.percepta-test.aitco.dev`. The generated deploy helper opens the required `Percepta-Core/infra` PRs in two phases.
+These files deploy to `https://__APP_NAME__.percepta-test.aitco.dev`.
 
-## Deploying
-
-Tell Claude "deploy this app to percepta-test" — it'll follow [`agent-skills/deploy.md`](../agent-skills/deploy.md), which runs the generated PR helper and then verifies Ryvn.
+The default deploy helper performs the existing-environment deploy motion: it assumes the target Ryvn environment already has the shared platform services installed, then wires this app into them. For `percepta-test`, that means shared Postgres, Inngest, the OTEL collector, the LGTM stack, and Langfuse must already exist before app deploy starts. Fresh-environment platform bootstrap is a separate motion and should be handled by a Ryvn blueprint or environment-specific platform rollout.
 
-## What's in these files
+The helper talks directly to Ryvn: it preflights the existing platform services, creates/updates the services, runs the GitHub Actions release workflows, creates the schema installation, approves the schema Terraform plan, creates or updates app-scoped Ryvn secrets, creates the web installation, waits for health, and verifies the health and app routes.
 
-**`__APP_NAME__.service.yaml`** — tells Ryvn how to build the Docker image. Points at `Percepta-Core/__APP_NAME__` (change the repo if you've named the GitHub repo differently). The release workflow passes `NPM_TOKEN` as a build arg from GitHub org secrets.
+## Deploying
 
-**`__APP_NAME__.env.percepta-test.serviceinstallation.yaml`** — configures the deployment on `percepta-test`. Three categories of values are baked in:
+Tell Claude "deploy this app to percepta-test" or run:
 
-1. **Per-app values** that vary by app name (URLs, k8s service names, database schema) — substituted at create-time.
-2. **Shared platform values** (Inngest and OTel endpoints) — copied as literals from existing percepta-test installations. These are stable across percepta-test apps.
-3. **Database wiring** — points at the shared `demos` database and a per-app schema created by the infra PR.
+```bash
+pnpm deploy:percepta-test -- --yes
+```
 
-**`percepta-test.secrets.env`** — generated locally and ignored by git. Import it in the Ryvn UI for `BETTER_AUTH_SECRET` and `ENCRYPTION_SECRET_KEY`; deployment secret values are intentionally not committed to GitOps IaC.
+The helper expects a clean, committed git worktree because GitHub Actions builds from the pushed repo. It can create `Percepta-Core/__REPO_NAME__` if it does not exist yet, and it pushes the current branch to `main` before triggering releases.
 
-## Deployment order
+## What's in these files
 
-Use two infra PRs. The Service must exist before the first release can be created, and the first release must exist before the ServiceInstallation can be imported.
+**`__APP_NAME__.service.yaml`** — Ryvn server service for the web app. It points at `Percepta-Core/__REPO_NAME__` and builds from `packages/__APP_NAME__/`.
 
-1. Open and merge the service/schema PR:
+**`__APP_NAME__-terraform.service.yaml`** — Ryvn Terraform service that owns the per-app Postgres schema in the shared `demos` database.
 
-   ```bash
-   pnpm deploy:percepta-test -- --phase service --yes
-   ```
+**`__APP_NAME__.env.percepta-test.serviceinstallation.yaml`** — web app installation for `percepta-test`. It wires the shared platform services, ingress, health probes, database connection, Inngest, OTEL/LGTM telemetry, the Langfuse base URL, and the shared demo variable group.
 
-2. Wait for GitOps to import the service. If the schema change creates a `percepta-internal-terraform` task in Ryvn, approve/apply it.
+**`__APP_NAME__-terraform.env.percepta-test.serviceinstallation.yaml`** — schema installation for `percepta-test`.
 
-3. Push the app to `main` or run the release workflow so Ryvn has a first release for `__APP_NAME__`.
+**`percepta-test.secrets.env`** — generated locally and ignored by git. The deploy helper injects app-specific auth/encryption secrets into the Ryvn installation create manifest so the first pod starts with auth configured; shared Langfuse and LLM demo keys are inherited from a Ryvn variable group.
 
-4. Open and merge the installation PR:
+## Platform Wiring
 
-   ```bash
-   pnpm deploy:percepta-test -- --phase installation --yes
-   ```
+`pnpm deploy:percepta-test` checks these existing `percepta-test` installations before it mutates GitHub or Ryvn app resources:
 
-5. After GitOps imports the installation, import `deploy/ryvn/percepta-test.secrets.env` into the Ryvn UI for the `__APP_NAME__` installation secrets.
+- `percepta-internal-terraform` for the shared Postgres instance.
+- `inngest-test` for background jobs and function callbacks.
+- `otel-collector` for trace, metric, and log collection.
+- `lgtm-stack-helm` for Loki, Grafana, Tempo, and Mimir.
+- `langfuse` for LLM tracing and eval observability.
+- `demos-commons` variable group for shared demo configuration, including the Anthropic API key and Langfuse demo project keys.
 
-The `--` is the pnpm argument delimiter; it passes the flags after it through to `scripts/open-ryvn-deploy-pr.ts`.
+The service installation sets `LANGFUSE_BASE_URL` to the shared `percepta-test` Langfuse URL, sets `LLM_PROVIDER=anthropic`, and attaches `demos-commons` for `ANTHROPIC_API_KEY`, `LANGFUSE_PUBLIC_KEY`, and sensitive `LANGFUSE_SECRET_KEY`. Individual demo apps do not need LLM or Langfuse keys in `percepta-test.secrets.env`.
 
-## Repo layout note
+## Notes
 
-These files assume this repo is a **monorepo** with the app at `packages/__APP_NAME__/` (the layout produced by `@percepta/create`). The `service.yaml` sets `context: packages/__APP_NAME__` accordingly. If you've flattened this into a single-package repo, change `context:` and `dockerfile:` to `.` and `Dockerfile`.
+The release workflows live at the repo root under `.github/workflows/`. The web workflow uses the org-level `NPM_TOKEN` secret for private `@percepta/*` packages; do not add a repo-level token unless the org secret is unavailable.
 
-The release workflow lives at `.github/workflows/__APP_NAME__-ryvn-release.yaml` (at the repo root, where GitHub Actions picks it up). It's path-filtered to `packages/__APP_NAME__/`, so changes to other packages won't trigger this app's deploy. Multiple webapps in the same monorepo each get their own `<name>-ryvn-release.yaml` and don't collide.
+For the old GitOps PR path, use `pnpm deploy:percepta-test:pr -- --phase service --yes` and then `pnpm deploy:percepta-test:pr -- --phase installation --yes`.
 
-## Adding more environments
+## Adding More Environments
 
-Copy `environments/percepta-test/installations/__APP_NAME__.env.percepta-test.serviceinstallation.yaml` to a new `environments/<env>/installations/__APP_NAME__.env.<env>.serviceinstallation.yaml` and change the `environment:`, host, and any environment-specific values.
+Copy the two `percepta-test` installation manifests to `environments/<env>/installations/`, then change the `environment:`, host, and environment-specific config.

package/templates/webapp/deploy/ryvn/__APP_NAME__-terraform.service.yaml

@@ -0,0 +1,10 @@
+kind: Service
+metadata:
+  name: __APP_NAME__-terraform
+spec:
+  type: terraform
+  repo: Percepta-Core/__REPO_NAME__
+  autoApprove: false
+  build:
+    path: packages/__APP_NAME__/terraform/schema
+    tagPrefix: __APP_NAME__-terraform@

package/templates/webapp/deploy/ryvn/__APP_NAME__.service.yaml

@@ -3,7 +3,7 @@ metadata:
   name: __APP_NAME__
 spec:
   type: server
-  repo: Percepta-Core/__APP_NAME__
+  repo: Percepta-Core/__REPO_NAME__
   build:
-    context: packages/__APP_NAME__
+    context: .
     dockerfile: packages/__APP_NAME__/Dockerfile

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

@@ -0,0 +1,11 @@
+kind: ServiceInstallation
+metadata:
+  name: __APP_NAME__-terraform
+spec:
+  service: __APP_NAME__-terraform
+  environment: percepta-test
+  config: |
+    aws_region: {{ .ryvn.env.state.cluster_region }}
+    database_secret_name: {{ .ryvn.installations.percepta_internal_terraform.outputs.percepta_internal_secrets_manager_secret_name }}
+    database_name: demos
+    schema_name: __APP_NAME_SNAKE__

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

@@ -54,8 +54,9 @@ spec:
 
     env:
       # Database — shared `demos` DB on the percepta-internal Postgres instance.
-      # Tables live under a per-app schema created by the infra PR. DATABASE_SCHEMA
-      # pins the connection search_path so Drizzle migrations + queries land there.
+      # Tables live under a per-app schema created by the __APP_NAME__-terraform
+      # Ryvn service. DATABASE_SCHEMA pins the connection search_path so Drizzle
+      # migrations + queries land there.
       - name: DATABASE_HOST
         valueFrom:
           secretKeyRef:
@@ -93,11 +94,11 @@ spec:
       value: https://__APP_NAME__.percepta-test.aitco.dev
     - key: BETTER_AUTH_URL
       value: https://__APP_NAME__.percepta-test.aitco.dev
-    # Import BETTER_AUTH_SECRET and ENCRYPTION_SECRET_KEY from
-    # deploy/ryvn/percepta-test.secrets.env in the Ryvn UI after the installation
-    # exists. Secret values are intentionally not declared in GitOps IaC.
+    # deploy:percepta-test injects BETTER_AUTH_SECRET and ENCRYPTION_SECRET_KEY
+    # from deploy/ryvn/percepta-test.secrets.env into the create request.
+    # Secret values are intentionally not declared here.
 
-    # Inngest (shared percepta-test instance)
+    # Inngest (shared percepta-test platform service)
     - key: INNGEST_BASE_URL
       value: http://inngest.percepta-test.svc.cluster.local:8288
     - key: INNGEST_EVENT_KEY
@@ -109,10 +110,45 @@ spec:
     - key: INNGEST_SERVE_HOST
       value: http://__APP_NAME__-web-server.percepta-test.svc.cluster.local:3000/api/inngest
 
-    # OpenTelemetry
-    - key: OTEL_METRICS_EXPORTER_OTLP_ENDPOINT
+    # Observability (shared percepta-test OTEL collector + LGTM stack)
+    # Application logs are emitted to stdout and collected by the shared OTEL
+    # collector. Traces and metrics are exported over OTLP HTTP.
+    - key: OTEL_SERVICE_NAME
+      value: __APP_NAME__
+    - key: OTEL_RESOURCE_ATTRIBUTES
+      value: service.namespace=__REPO_NAME__,deployment.environment=percepta-test
+    - key: OTEL_TRACES_EXPORTER
+      value: otlp
+    - key: OTEL_METRICS_EXPORTER
+      value: otlp
+    - key: OTEL_LOGS_EXPORTER
+      value: none
+    - key: OTEL_EXPORTER_OTLP_PROTOCOL
+      value: http/protobuf
+    - key: OTEL_EXPORTER_OTLP_ENDPOINT
+      value: http://otel-collector-opentelemetry-collector.percepta-test.svc.cluster.local:4318
+    - key: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
+      value: http://otel-collector-opentelemetry-collector.percepta-test.svc.cluster.local:4318/v1/traces
+    - key: OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
       value: http://otel-collector-opentelemetry-collector.percepta-test.svc.cluster.local:4318/v1/metrics
-    - key: OTEL_EXPORT_INTERVAL_MS
+    - key: OTEL_METRIC_EXPORT_INTERVAL
       value: "60000"
+    - key: NEXT_PUBLIC_FARO_APP_NAME
+      value: __APP_NAME__
+    - key: NEXT_PUBLIC_FARO_APP_VERSION
+      value: "0.1.0"
+    - key: NEXT_PUBLIC_FARO_APP_ENVIRONMENT
+      value: percepta-test
     - key: LOG_LEVEL
       value: debug
+
+    # Langfuse (shared percepta-test platform service). Project keys come from
+    # the demos-commons Ryvn variable group below.
+    - key: LANGFUSE_BASE_URL
+      value: https://langfuse.percepta-test.aitco.dev
+
+    # LLM provider (shared demo Anthropic key comes from demos-commons).
+    - key: LLM_PROVIDER
+      value: anthropic
+  variableGroups:
+    - name: demos-commons

package/templates/webapp/env.example.template

@@ -19,9 +19,9 @@ BETTER_AUTH_URL=http://localhost:3000
 ENCRYPTION_SECRET_KEY=generate-with-node-e-console-log-require-crypto-randomBytes-16-toString-hex
 
 # Inngest (Background Jobs)
-# INNGEST_BASE_URL=
+INNGEST_BASE_URL=http://localhost:8288
 # INNGEST_SIGNING_KEY=
-# INNGEST_EVENT_KEY=
+INNGEST_EVENT_KEY=local
 
 # Grafana Faro (client-side observability)
 # Leave NEXT_PUBLIC_FARO_COLLECTOR_URL empty to disable in local development.
@@ -36,6 +36,24 @@ NEXT_PUBLIC_FARO_APP_ENVIRONMENT=development
 # LANGFUSE_PUBLIC_KEY=
 # LANGFUSE_SECRET_KEY=
 
+# LLM providers
+# Deployed percepta-test apps inherit ANTHROPIC_API_KEY from the demos-commons
+# Ryvn variable group. For local LLM testing, set ANTHROPIC_API_KEY once in your
+# shell profile or ~/.config/percepta/create.env.
+# ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=
+# LLM_PROVIDER=anthropic
+# LLM_MODEL=claude-sonnet-4-5-20250929
+
+# OpenTelemetry (server-side traces and metrics)
+# OTEL_SERVICE_NAME=__APP_NAME__
+# OTEL_TRACES_EXPORTER=otlp
+# OTEL_METRICS_EXPORTER=otlp
+# OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
+# OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:4318/v1/metrics
+
 # AWS (uses default credential chain in development)
 # AWS_REGION=us-east-1
 # AWS_ACCESS_KEY_ID=

package/templates/webapp/eslint.config.mjs

@@ -57,4 +57,10 @@ export default [
       "n/no-process-env": "off",
     },
   },
+  {
+    files: ["scripts/with-local-env.ts"],
+    rules: {
+      "n/no-process-env": "off",
+    },
+  },
 ];

package/templates/webapp/next.config.ts

@@ -1,8 +1,17 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import type { NextConfig } from "next";
 
+const appDir = path.dirname(fileURLToPath(import.meta.url));
+const monorepoRoot = path.resolve(appDir, "../..");
+
 const nextConfig: NextConfig = {
   // Enable standalone output for Docker:
   output: "standalone",
+  outputFileTracingRoot: monorepoRoot,
+  turbopack: {
+    root: monorepoRoot,
+  },
 };
 
 export default nextConfig;

package/templates/webapp/package.json.template

@@ -6,14 +6,15 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "dev": "next dev --turbopack",
+    "dev": "tsx ./scripts/with-local-env.ts 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:up": "docker compose up -d --wait",
     "docker:down": "docker compose down",
-    "db:generate": "drizzle-kit generate",
+    "inngest:dev": "pnpm dlx inngest-cli@latest dev -u http://localhost:3000/api/inngest",
+    "db:generate": "tsx ./scripts/generate-migrations.ts",
     "db:migrate": "tsx ./scripts/migrate.ts",
     "db:setup": "tsx ./scripts/setup-database.ts",
     "db:setup-and-migrate": "pnpm db:setup && pnpm db:migrate",
@@ -21,11 +22,13 @@
     "db:studio": "drizzle-kit studio",
     "db:create-user": "tsx ./scripts/create-user.ts",
     "db:seed": "tsx ./scripts/seed.ts",
-    "deploy:percepta-test": "tsx ./scripts/open-ryvn-deploy-pr.ts",
+    "deploy:percepta-test": "tsx ./scripts/deploy-percepta-test.ts",
+    "deploy:percepta-test:pr": "tsx ./scripts/open-ryvn-deploy-pr.ts",
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "dependencies": {
+    "@ai-sdk/anthropic": "^2.0.23",
     "@ai-sdk/openai": "^2.0.23",
     "@aws-sdk/client-s3": "^3.888.0",
     "@aws-sdk/client-secrets-manager": "^3.914.0",
@@ -47,6 +50,7 @@
     "@next/env": "^15.3.5",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/auto-instrumentations-node": "^0.62.1",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.203.0",
     "@opentelemetry/sdk-node": "^0.203.0",
     "@percepta/design": "0.3.2",
     "@percepta/logger": "0.0.6",