@percepta/create 3.0.1 → 3.1.0

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

@@ -130,6 +130,7 @@ pnpm docker:down
 | `DATABASE_USERNAME` | `postgres` | Database user |
 | `DATABASE_PASSWORD` | `postgres` | Database password |
 | `DATABASE_NAME` | `__DB_NAME__` | Database name |
+| `DATABASE_SCHEMA` | - | Optional Postgres schema/search path |
 | `DATABASE_USE_SSL` | `false` | Enable SSL connections |
 
 ## Key Concepts

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

@@ -10,7 +10,7 @@ When this app was created with `@percepta/create`, the IaC files were generated
 - `deploy/ryvn/environments/percepta-test/installations/__APP_NAME__.env.percepta-test.serviceinstallation.yaml` — percepta-test installation
 - `.github/workflows/__APP_NAME__-ryvn-release.yaml` (at the repo root) — release workflow that builds the Docker image and creates a Ryvn release on push to `main`. Path filter scoped to `packages/__APP_NAME__/` so unrelated changes don't trigger builds.
 
-Per-app values (URLs, k8s service names, database name) are substituted at create-time. Shared platform values (Inngest, Langfuse, OTel endpoints) are baked in as literals — they're stable across percepta-test apps. Three secrets stay in the Ryvn UI.
+Per-app values (URLs, k8s service names, database schema) are substituted at create-time. The Better Auth and encryption secrets are declared as Ryvn-managed secrets so their values are set after the infra PR merges, not committed to git. Shared platform values (Inngest and OTel endpoints) are baked in as literals because they're stable across percepta-test apps.
 
 See [`deploy/README.md`](../deploy/README.md) for the file-by-file breakdown.
 
@@ -19,43 +19,39 @@ See [`deploy/README.md`](../deploy/README.md) for the file-by-file breakdown.
 - The app repo is under the `Percepta-Core` GitHub org. If not yet, run `gh repo create Percepta-Core/__APP_NAME__ --private --source=. --push` from the monorepo root.
 - The Percepta-Core org has `RYVN_CLIENT_ID`, `RYVN_CLIENT_SECRET`, and `NPM_TOKEN` as org-level GitHub secrets (already in place).
 - The `percepta-internal-terraform` installation provides the shared PostgreSQL — already deployed on percepta-test.
-- The infra repo (`Percepta-Core/infra`) is checked out locally, typically at `../../infra` relative to this package.
+- `git` and `gh` are installed and authenticated.
+- The infra repo (`Percepta-Core/infra`) is checked out locally or can be cloned by the deploy script.
 
 ## Deploy
 
 ### Step 1: Open the infra PR
 
-Copy the two scaffolded files into the infra repo and open a PR:
+Run the generated deploy helper from this package directory:
 
 ```bash
-INFRA=../../infra   # adjust to your local path
-NAME=__APP_NAME__
-
-cp deploy/ryvn/$NAME.service.yaml \
-   $INFRA/ryvn/$NAME.service.yaml
+pnpm deploy:percepta-test -- --yes
+```
 
-cp deploy/ryvn/environments/percepta-test/installations/$NAME.env.percepta-test.serviceinstallation.yaml \
-   $INFRA/ryvn/environments/percepta-test/installations/$NAME.env.percepta-test.serviceinstallation.yaml
+This script:
 
-cd $INFRA
-git checkout -b deploy/$NAME-percepta-test
-git add ryvn/$NAME.service.yaml ryvn/environments/percepta-test/installations/$NAME.env.percepta-test.serviceinstallation.yaml
-git commit -m "Add $NAME service + percepta-test installation"
-git push -u origin deploy/$NAME-percepta-test
-gh pr create --fill
-```
+- uses `INFRA_REPO` or `--infra <path>` when provided
+- otherwise uses a sibling `../infra` checkout, cloning `Percepta-Core/infra` there if needed
+- copies the Ryvn service and installation YAML into infra
+- appends a `postgresql_schema "__APP_NAME_SNAKE__"` resource to `terraform/percepta-internal/databases.tf`
+- opens one PR against `Percepta-Core/infra`
 
 Get the PR reviewed and merged.
 
-### Step 2: Set the three secrets in the Ryvn UI
+### Step 2: Set Ryvn secrets
 
-After the infra PR merges, Ryvn creates the installation. Open the Ryvn UI for the `__APP_NAME__` installation in `percepta-test` and set:
+After the infra PR merges, set the base Ryvn secrets for this installation:
+
+```bash
+BETTER_AUTH_SECRET=$(openssl rand -base64 32)
+ENCRYPTION_SECRET_KEY=$(openssl rand -hex 16)
+```
 
-| Secret | Value |
-|--------|-------|
-| `BETTER_AUTH_SECRET` | `openssl rand -base64 32` |
-| `ENCRYPTION_SECRET_KEY` | `openssl rand -hex 16` |
-| `LANGFUSE_SECRET_KEY` | from 1Password: "Percepta Test Secrets" |
+Also set any app-specific secrets the implementation added, such as `OPENAI_API_KEY`.
 
 ### Step 3: Trigger the first deploy
 
@@ -76,16 +72,17 @@ The app will be available at **https://__APP_NAME__.percepta-test.aitco.dev**.
 
 ## Troubleshooting
 
-- **Pod crash-looping** → secrets probably aren't set yet (Step 2). Check `ryvn logs`.
+- **Pod crash-looping** → check `ryvn logs`; missing Ryvn secrets from Step 2 are the most common cause after a fresh deploy.
 - **Database connection refused** → verify `DATABASE_USE_SSL=true` and that `percepta-internal-terraform` is deployed.
+- **Database schema missing** → verify the infra PR added `postgresql_schema "__APP_NAME_SNAKE__"` and Ryvn applied `percepta-internal-terraform`.
 - **Inngest can't reach the app** → `INNGEST_APP_URL` must use the k8s service name `__APP_NAME__-web-server`. The scaffolded YAML gets this right; if you renamed anything, double-check.
-- **Image build fails** → check `NPM_TOKEN` in the service definition is current. Build context is `packages/__APP_NAME__`.
+- **Image build fails fetching @percepta packages** → check the `NPM_TOKEN` GitHub org secret. The workflow passes it as a build arg.
 
 For Ryvn CLI operations, use the `/use-ryvn` skill.
 
 ## Updating shared platform values
 
-The Inngest/Langfuse/OTel URLs are baked as literals in every webapp's installation YAML. If percepta-test infra ever changes those endpoints, update them with a single grep across the infra repo:
+The Inngest and OTel URLs are baked as literals in every webapp's installation YAML. If percepta-test infra ever changes those endpoints, update them with a single grep across the infra repo:
 
 ```bash
 grep -rl "inngest.percepta-test.svc.cluster.local:8288" ryvn/environments/percepta-test/installations/

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

@@ -122,7 +122,7 @@ If it fails, fix the errors before moving to the next chunk. Do not accumulate b
 ### Implementation Rules
 
 - **Use `@percepta/design` components.** Do not write custom UI for things that exist in the design system (Button, Dialog, Table, Card, Input, etc.). Read `node_modules/@percepta/design/dist/src/index.d.ts` to see what's available.
-- **Use `AsyncContent` for loading states.** Every data-fetching UI should use `AsyncContent` from `@percepta/components`.
+- **Use robust loading states.** `@percepta/components` is optional; add it first if you want `AsyncContent`.
 - **Use `getEnvConfig()` for env vars.** Never use `process.env` directly.
 - **Use `getLogger()` for logging.** Never use `console.log`. Use safe/unsafe field separation.
 - **Follow the singleton pattern** for new services. Follow the existing `DatabaseService` singleton pattern in the codebase.
@@ -179,8 +179,8 @@ git init
 git add -A
 git commit -m "Initial implementation of <app-name>"
 
-# Create the repo under percepta-ai org
-gh repo create percepta-ai/<app-name> --private --source=. --push
+# Create the repo under the Percepta-Core org
+gh repo create Percepta-Core/<app-name> --private --source=. --push
 ```
 
 If `gh` is not authenticated, tell the user to run `gh auth login` and then continue.

package/templates/webapp/deploy/README.md

@@ -12,21 +12,23 @@ deploy/
                 └── __APP_NAME__.env.percepta-test.serviceinstallation.yaml # percepta-test installation
 ```
 
-These files are pre-filled with all values needed to deploy to `https://__APP_NAME__.percepta-test.aitco.dev`. The only manual steps are: open a PR in `Percepta-Core/infra` to copy them in, and set three secrets in the Ryvn UI.
+These files are pre-filled with all base values needed to deploy to `https://__APP_NAME__.percepta-test.aitco.dev`. The generated `pnpm deploy:percepta-test -- --yes` helper opens the required `Percepta-Core/infra` PR.
 
 ## Deploying
 
-Tell Claude "deploy this app to percepta-test" — it'll follow [`agent-skills/deploy.md`](../agent-skills/deploy.md), which walks through copying these files into the infra repo, opening the PR, and the manual Ryvn UI step.
+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.
 
 ## What's in these files
 
-**`__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 `NPM_TOKEN` build arg is a read-only npm token shared across all Percepta apps for installing `@percepta/*` packages — it's not a secret.
+**`__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.
 
 **`__APP_NAME__.env.percepta-test.serviceinstallation.yaml`** — configures the deployment on `percepta-test`. Three categories of values are baked in:
 
-1. **Per-app values** that vary by app name (URLs, k8s service names) — substituted at create-time.
-2. **Shared platform values** (Inngest, Langfuse, OTel endpoints) — copied as literals from the `tc-emo` reference installation. These are stable across percepta-test apps.
-3. **Secrets** (`BETTER_AUTH_SECRET`, `ENCRYPTION_SECRET_KEY`, `LANGFUSE_SECRET_KEY`) — declared in the YAML, value entered once in the Ryvn UI.
+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.
+
+`BETTER_AUTH_SECRET` and `ENCRYPTION_SECRET_KEY` are declared as Ryvn-managed secrets. Set their values in Ryvn after the infra PR merges; the scaffold does not commit deployment secret values to git.
 
 ## Repo layout note
 

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

@@ -5,7 +5,5 @@ spec:
   type: server
   repo: Percepta-Core/__APP_NAME__
   build:
-    args:
-      NPM_TOKEN: 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
     context: packages/__APP_NAME__
     dockerfile: packages/__APP_NAME__/Dockerfile

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

@@ -38,29 +38,33 @@ spec:
             - __APP_NAME__.percepta-test.aitco.dev
 
     env:
-      # Database (shared percepta-test RDS, provisioned by percepta-internal-terraform)
+      # 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.
       - name: DATABASE_HOST
         valueFrom:
           secretKeyRef:
-            name: "{{ .ryvn.installations.percepta_internal_terraform.outputs.postgresql_secret_name }}"
+            name: "{{ .ryvn.installations.percepta_internal_terraform.outputs.percepta_internal_postgresql_secret_name }}"
             key: host
       - name: DATABASE_PORT
         valueFrom:
           secretKeyRef:
-            name: "{{ .ryvn.installations.percepta_internal_terraform.outputs.postgresql_secret_name }}"
+            name: "{{ .ryvn.installations.percepta_internal_terraform.outputs.percepta_internal_postgresql_secret_name }}"
             key: port
       - name: DATABASE_USERNAME
         valueFrom:
           secretKeyRef:
-            name: "{{ .ryvn.installations.percepta_internal_terraform.outputs.postgresql_secret_name }}"
+            name: "{{ .ryvn.installations.percepta_internal_terraform.outputs.percepta_internal_postgresql_secret_name }}"
             key: username
       - name: DATABASE_PASSWORD
         valueFrom:
           secretKeyRef:
-            name: "{{ .ryvn.installations.percepta_internal_terraform.outputs.postgresql_secret_name }}"
+            name: "{{ .ryvn.installations.percepta_internal_terraform.outputs.percepta_internal_postgresql_secret_name }}"
             key: password
       - name: DATABASE_NAME
-        value: "__DB_NAME__"
+        value: "demos"
+      - name: DATABASE_SCHEMA
+        value: "__APP_NAME_SNAKE__"
       - name: DATABASE_USE_SSL
         value: "true"
 
@@ -74,12 +78,9 @@ spec:
       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)
+    # Set these in Ryvn after the infra PR merges.
     - key: BETTER_AUTH_SECRET
       isSecret: true
-
-    # Encryption — generated random, set in Ryvn UI (openssl rand -hex 16)
     - key: ENCRYPTION_SECRET_KEY
       isSecret: true
 
@@ -95,14 +96,6 @@ spec:
     - 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
@@ -110,12 +103,3 @@ spec:
       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/drizzle.config.ts

@@ -1,6 +1,7 @@
 import { loadEnvConfig } from "@next/env";
 import type { Config } from "drizzle-kit";
 import { getEnvConfig } from "./src/config/getEnvConfig";
+import { getPgSearchPathOption } from "./src/drizzle/searchPath";
 
 loadEnvConfig(process.cwd());
 
@@ -10,20 +11,28 @@ const {
   DATABASE_USERNAME: user,
   DATABASE_PASSWORD: password,
   DATABASE_NAME: database,
+  DATABASE_SCHEMA: databaseSchema,
   DATABASE_USE_SSL: useSSL,
 } = getEnvConfig();
 
+const schemaFilter = databaseSchema?.trim() || undefined;
+const searchPathOption = getPgSearchPathOption(schemaFilter);
+const connectionParams = new URLSearchParams();
+if (useSSL) connectionParams.set("sslmode", "require");
+if (searchPathOption) connectionParams.set("options", searchPathOption);
+
+const connectionString =
+  `postgresql://${encodeURIComponent(user)}:${encodeURIComponent(password)}` +
+  `@${host}:${port}/${encodeURIComponent(database)}` +
+  (connectionParams.size > 0 ? `?${connectionParams.toString()}` : "");
+
 const config: Config = {
   schema: "./src/drizzle/schema",
   out: "./src/drizzle/migrations",
   dialect: "postgresql",
+  ...(schemaFilter ? { schemaFilter: [schemaFilter] } : {}),
   dbCredentials: {
-    host,
-    port,
-    user,
-    password,
-    database,
-    ssl: useSSL ? "require" : false,
+    url: connectionString,
   },
 };
 

package/templates/webapp/env.example.template

@@ -8,6 +8,7 @@ DATABASE_PORT=5434
 DATABASE_USERNAME=postgres
 DATABASE_PASSWORD=postgres
 DATABASE_NAME=__DB_NAME__
+# DATABASE_SCHEMA=
 DATABASE_USE_SSL=false
 
 # Authentication (Better Auth)

package/templates/webapp/eslint.config.mjs

@@ -24,6 +24,7 @@ export default [
     rules: {
       ...nextPlugin.configs.recommended.rules,
       ...nextPlugin.configs["core-web-vitals"].rules,
+      "react/react-in-jsx-scope": "off",
     },
   },
   {
@@ -49,4 +50,10 @@ export default [
       "n/no-process-env": "error",
     },
   },
+  {
+    files: ["src/config/clientEnvConfig.ts"],
+    rules: {
+      "n/no-process-env": "off",
+    },
+  },
 ];

package/templates/webapp/package.json.template

@@ -21,6 +21,7 @@
     "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",
     "test": "vitest run",
     "test:watch": "vitest"
   },
@@ -47,11 +48,10 @@
     "@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",
+    "@percepta/design": "0.3.2",
+    "@percepta/logger": "0.0.6",
+    "@percepta/next-utils": "0.1.0",
+    "@percepta/utils": "0.1.10",
     "@radix-ui/react-slot": "^1.2.3",
     "@tanstack/react-query": "^5.81.5",
     "@tanstack/react-virtual": "^3.13.12",
@@ -95,7 +95,7 @@
   },
   "devDependencies": {
     "@next/eslint-plugin-next": "^15.3.5",
-    "@percepta/build": "^0.1.3",
+    "@percepta/build": "0.4.0",
     "@tailwindcss/postcss": "^4.1.11",
     "@types/formidable": "^3.4.5",
     "@types/he": "^1.2.3",