@percepta/create 3.1.3 → 3.1.5

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "@percepta/create",
-  "version": "3.1.3",
+  "version": "3.1.5",
   "description": "Scaffold a new Mosaic package",
-  "type": "module",
+  "keywords": [
+    "cli",
+    "create",
+    "mosaic",
+    "nextjs",
+    "percepta",
+    "scaffold",
+    "template"
+  ],
+  "license": "MIT",
   "bin": {
     "create": "./dist/index.js"
   },
@@ -11,6 +20,10 @@
     "templates",
     "template-versions.json"
   ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
@@ -24,36 +37,22 @@
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^24.1.0",
     "@types/validate-npm-package-name": "^4.0.2",
-    "tsup": "^8.4.0",
-    "typescript": "^5.7.3",
     "vitest": "^4.0.0",
-    "@percepta/build": "0.4.1"
+    "@percepta/build": "0.5.0"
   },
   "engines": {
     "node": ">=18.0.0"
   },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "create",
-    "template",
-    "nextjs",
-    "mosaic",
-    "percepta",
-    "scaffold",
-    "cli"
-  ],
-  "license": "MIT",
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "create:local": "pnpm build && node dist/index.js",
-    "dev": "tsup src/index.ts --format esm --watch",
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "clean": "rimraf dist",
     "typecheck": "tsc --noEmit",
-    "sync-template": "tsx scripts/sync-template.ts",
-    "template:tag": "tsx scripts/template-tag.ts",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:template": "bash scripts/test-template.sh"
+    "test:template": "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/webapp/AGENTS.md

@@ -8,7 +8,7 @@ Next.js 15 full-stack application scaffolded from the Mosaic webapp template via
 - `pnpm build` — production build
 - `pnpm lint` — run ESLint
 - `pnpm test` — run Vitest tests
-- `pnpm docker:up` / `pnpm docker:down` — start/stop PostgreSQL
+- `pnpm docker:up` / `pnpm docker:down` — start PostgreSQL and wait for health / stop PostgreSQL
 - `pnpm inngest:dev` — start local Inngest dev server when working on background jobs
 - `pnpm db:generate` — generate Drizzle migrations
 - `pnpm db:migrate` — apply migrations

package/templates/webapp/README.md

@@ -85,7 +85,7 @@ src/
 | `pnpm build` | Build for production |
 | `pnpm start` | Start production server |
 | `pnpm lint` | Run ESLint |
-| `pnpm docker:up` | Start PostgreSQL container |
+| `pnpm docker:up` | Start PostgreSQL container and wait until it is healthy |
 | `pnpm docker:down` | Stop PostgreSQL container |
 | `pnpm inngest:dev` | Start the local Inngest dev server for this app |
 | `pnpm db:generate` | Generate Drizzle migrations |

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

@@ -38,7 +38,11 @@ export * from "./documents";
 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.
+This creates a new SQL migration file and normalizes generated foreign key
+references so they stay schema-relative when `DATABASE_SCHEMA` is set in
+`percepta-test`. **Review the generated SQL** — Drizzle generates it
+automatically but you should verify it's correct, especially for new foreign
+keys and destructive changes.
 
 ### 4. Apply the migration
 

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

@@ -12,7 +12,7 @@ This is the existing-environment deploy motion: `percepta-test` already owns the
 - `deploy/ryvn/environments/percepta-test/installations/__APP_NAME__-terraform.env.percepta-test.serviceinstallation.yaml` — schema installation.
 - `.github/workflows/__APP_NAME__-ryvn-release.yaml` — builds the Docker image and creates the web Ryvn release.
 - `.github/workflows/__APP_NAME__-terraform-ryvn-release.yaml` — creates the schema Terraform Ryvn release.
-- `deploy/ryvn/percepta-test.secrets.env` — generated locally and ignored by git; patched into Ryvn by the deploy helper.
+- `deploy/ryvn/percepta-test.secrets.env` — generated locally and ignored by git; injected into the app installation as Ryvn secrets by the deploy helper.
 
 See [`deploy/README.md`](../deploy/README.md) for the file-by-file breakdown.
 
@@ -42,7 +42,7 @@ The helper:
 6. Creates or replaces the schema installation and approves the Terraform plan.
 7. Runs the web release workflow.
 8. Creates or replaces the web installation.
-9. Patches `BETTER_AUTH_SECRET` and `ENCRYPTION_SECRET_KEY` from `deploy/ryvn/percepta-test.secrets.env`.
+9. Creates or updates app-scoped Ryvn installation secrets for `BETTER_AUTH_SECRET` and `ENCRYPTION_SECRET_KEY` from `deploy/ryvn/percepta-test.secrets.env`. On first install, the helper injects them into the create manifest so the first pod starts with auth configured.
 10. Waits for Ryvn health and checks `/api/healthz`, `/api/readyz`, and the protected app route.
 
 The app will be available at **https://__APP_NAME__.percepta-test.aitco.dev**.
@@ -74,12 +74,14 @@ curl -s https://__APP_NAME__.percepta-test.aitco.dev/api/readyz
 curl -I https://__APP_NAME__.percepta-test.aitco.dev/
 ```
 
+For apps with tRPC routes, also verify at least one endpoint that initializes Better Auth or app services. `healthz` can be green even when app-specific secrets or workflow wiring are wrong.
+
 ## Troubleshooting
 
 - **Image build fails fetching @percepta packages** → check the Percepta-Core org-level `NPM_TOKEN` secret. Do not add a repo-level token unless the org secret is unavailable.
 - **Ryvn release already exists** → commit a new change or re-run with `--skip-workflows` if the current releases are already present.
 - **Terraform plan needs approval** → the helper approves it when run with `--yes`; without `--yes`, approve the prompt.
-- **Auth/sign-in routes fail after install** → verify the deploy helper patched `BETTER_AUTH_SECRET` and `ENCRYPTION_SECRET_KEY`.
+- **Auth/sign-in or tRPC routes fail after install** → verify the `__APP_NAME__` installation has `BETTER_AUTH_SECRET` and `ENCRYPTION_SECRET_KEY` secrets from `deploy/ryvn/percepta-test.secrets.env`, then redeploy `__APP_NAME__` so the pod reloads them.
 - **Pod crash-looping** → check `ryvn logs`; migration or database connectivity failures are the most common fresh-deploy causes.
 - **Database schema missing** → check `ryvn get installation __APP_NAME__-terraform -e percepta-test`.
 - **Inngest can't reach the app** → `INNGEST_APP_URL` must use the k8s service name `__APP_NAME__-web-server`.

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

@@ -31,13 +31,13 @@ Add the event to the central `AppEvents` registry:
 import { DocumentProcessedPayload } from "./payloads/DocumentProcessedPayload";
 
 export const AppEvents = {
-  "app/document.processed": z.object({
-    data: DocumentProcessedPayload.SCHEMA,
-  }),
+  "app/document.processed": DocumentProcessedPayload.SCHEMA,
 };
 ```
 
-Event names follow the convention `"app/<entity>.<action>"`.
+Event names follow the convention `"app/<entity>.<action>"`. `AppEvents`
+schemas validate `event.data`, so do not wrap payload schemas in another
+`{ data: ... }` object.
 
 ## Adding a New Function
 
@@ -93,13 +93,18 @@ const functionCollections: InngestFunctionCollection[] = compact([
 ## Sending Events
 
 ```typescript
-const inngest = InngestService.create();
-await inngest.client.send({
-  name: "app/document.processed",
-  data: { documentId: "abc", userId: "user-1", pageCount: 5 },
+await AppWorkflowService.create().sendDocumentProcessed({
+  documentId: "abc",
+  userId: "user-1",
+  pageCount: 5,
 });
 ```
 
+Prefer adding typed methods to `AppWorkflowService` instead of calling
+`InngestService.create().client.send(...)` directly from routers or route
+handlers. Keep a unit test that asserts the method sends the same payload shape
+that `AppEvents` validates.
+
 ## Running Inngest Locally
 
 ### 1. Start the Inngest Dev Server

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

@@ -193,7 +193,7 @@ git add -A
 git commit -m "Initial implementation of <app-name>"
 
 # Create the repo under the Percepta-Core org
-gh repo create Percepta-Core/<app-name> --private --source=. --push
+gh repo create Percepta-Core/<app-name> --internal --source=. --push
 ```
 
 If `gh` is not authenticated, tell the user to run `gh auth login` and then continue.

package/templates/webapp/deploy/README.md

@@ -18,7 +18,7 @@ These files deploy to `https://__APP_NAME__.percepta-test.aitco.dev`.
 
 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.
 
-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 the web installation, patches generated secrets, waits for health, and verifies the health and app routes.
+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.
 
 ## Deploying
 
@@ -40,7 +40,7 @@ The helper expects a clean, committed git worktree because GitHub Actions builds
 
 **`__APP_NAME__-terraform.env.percepta-test.serviceinstallation.yaml`** — schema installation for `percepta-test`.
 
-**`percepta-test.secrets.env`** — generated locally and ignored by git. The deploy helper patches app-specific auth/encryption secrets into the Ryvn installation; shared Langfuse and LLM demo keys are inherited from a Ryvn variable group.
+**`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.
 
 ## Platform Wiring
 

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

@@ -94,9 +94,9 @@ spec:
       value: https://__APP_NAME__.percepta-test.aitco.dev
     - key: BETTER_AUTH_URL
       value: https://__APP_NAME__.percepta-test.aitco.dev
-    # deploy:percepta-test patches BETTER_AUTH_SECRET and ENCRYPTION_SECRET_KEY
-    # from deploy/ryvn/percepta-test.secrets.env 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 platform service)
     - key: INNGEST_BASE_URL

package/templates/webapp/package.json.template

@@ -11,10 +11,10 @@
     "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",
     "inngest:dev": "pnpm dlx inngest-cli@latest dev -u http://localhost:3000/api/inngest",
-    "db:generate": "drizzle-kit generate",
+    "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",