@percepta/create 3.1.3 → 3.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percepta/create",
-  "version": "3.1.3",
+  "version": "3.1.4",
   "description": "Scaffold a new Mosaic package",
   "type": "module",
   "bin": {

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",

package/templates/webapp/scripts/deploy-percepta-test.ts

@@ -81,6 +81,11 @@ interface Installation {
   name?: string;
   status?: string;
   health?: string;
+  release?: {
+    commitSha?: string;
+    currentVersion?: string;
+    targetVersion?: string;
+  };
 }
 
 interface VariableGroup {
@@ -91,6 +96,17 @@ interface VariableGroup {
   }>;
 }
 
+interface Release {
+  version?: string;
+  commit?: {
+    sha?: string;
+  };
+}
+
+interface ReleaseList {
+  releases?: Release[];
+}
+
 function parseArgs(argv: string[]): Options {
   const options: Options = {
     yes: false,
@@ -151,6 +167,22 @@ function run(
   return typeof result === "string" ? result.trim() : "";
 }
 
+function runWithInput(
+  command: string,
+  args: string[],
+  cwd: string,
+  inputText: string,
+): string {
+  const result = execFileSync(command, args, {
+    cwd,
+    encoding: "utf8",
+    input: inputText,
+    stdio: ["pipe", "inherit", "inherit"],
+  });
+
+  return typeof result === "string" ? result.trim() : "";
+}
+
 function runJson<T>(command: string, args: string[], cwd: string): T {
   const outputText = run(command, args, cwd, "pipe");
   return JSON.parse(outputText) as T;
@@ -248,7 +280,7 @@ async function ensureGitHubRepo(
         "repo",
         "create",
         repoSlug,
-        "--private",
+        "--internal",
         "--source",
         monorepoRoot,
         "--remote",
@@ -301,6 +333,10 @@ function upsertService(manifestPath: string, monorepoRoot: string): void {
   run("ryvn", ["replace", "-f", manifestPath], monorepoRoot);
 }
 
+function getCurrentCommitSha(monorepoRoot: string): string {
+  return run("git", ["rev-parse", "HEAD"], monorepoRoot, "pipe");
+}
+
 function getInstallation(
   name: string,
   monorepoRoot: string,
@@ -335,6 +371,39 @@ function installationExists(name: string, monorepoRoot: string): boolean {
   return getInstallation(name, monorepoRoot) !== null;
 }
 
+function isHealthyAtCommit(
+  installation: Installation | null,
+  commitSha: string,
+): boolean {
+  return (
+    installation?.status === "UP_TO_DATE" &&
+    installation.health === "HEALTHY" &&
+    installation.release?.commitSha === commitSha
+  );
+}
+
+function getReleaseForCommit(
+  serviceName: string,
+  commitSha: string,
+  monorepoRoot: string,
+): Release | null {
+  try {
+    const releaseList = runJson<ReleaseList>(
+      "ryvn",
+      ["get", "release", "--service", serviceName, "-o", "json"],
+      monorepoRoot,
+    );
+
+    return (
+      releaseList.releases?.find(
+        (release) => release.commit?.sha === commitSha,
+      ) ?? null
+    );
+  } catch {
+    return null;
+  }
+}
+
 function assertHealthyPlatformInstallation(
   installation: Installation | null,
   name: string,
@@ -429,19 +498,170 @@ function upsertInstallation(
   name: string,
   manifestPath: string,
   monorepoRoot: string,
+  expectedCommitSha: string,
+  manifestContents?: string,
+): void {
+  const existingInstallation = getInstallation(name, monorepoRoot);
+  if (isHealthyAtCommit(existingInstallation, expectedCommitSha)) {
+    console.log(
+      `${name} is already healthy at ${expectedCommitSha.slice(0, 7)}; skipping installation replace.`,
+    );
+    return;
+  }
+
+  const action = existingInstallation == null ? "create" : "replace";
+  try {
+    if (existingInstallation == null) {
+      if (manifestContents == null) {
+        run("ryvn", ["create", "-f", manifestPath], monorepoRoot);
+      } else {
+        runWithInput(
+          "ryvn",
+          ["create", "-f", "-"],
+          monorepoRoot,
+          manifestContents,
+        );
+      }
+    } else if (manifestContents == null) {
+      run("ryvn", ["replace", "-f", manifestPath], monorepoRoot);
+    } else {
+      runWithInput(
+        "ryvn",
+        ["replace", "-f", "-"],
+        monorepoRoot,
+        manifestContents,
+      );
+    }
+  } catch (error) {
+    const currentInstallation = getInstallation(name, monorepoRoot);
+    if (isHealthyAtCommit(currentInstallation, expectedCommitSha)) {
+      console.log(
+        `${name} ${action} returned an error, but Ryvn now reports it healthy at ${expectedCommitSha.slice(0, 7)}; continuing.`,
+      );
+      return;
+    }
+
+    throw error;
+  }
+}
+
+function printFailedWorkflowLog(
+  repoSlug: string,
+  runId: number,
+  monorepoRoot: string,
 ): void {
-  if (installationExists(name, monorepoRoot)) {
-    run("ryvn", ["replace", "-f", manifestPath], monorepoRoot);
-  } else {
-    run("ryvn", ["create", "-f", manifestPath], monorepoRoot);
+  try {
+    console.log("");
+    console.log(`Failed workflow log for ${runId}:`);
+    run(
+      "gh",
+      ["run", "view", String(runId), "--repo", repoSlug, "--log-failed"],
+      monorepoRoot,
+    );
+  } catch {
+    console.log(`Could not fetch failed workflow logs for ${runId}.`);
+  }
+}
+
+async function ensureReleaseForCurrentCommit(
+  serviceName: string,
+  repoSlug: string,
+  workflowFile: string,
+  monorepoRoot: string,
+  options: Options,
+  commitSha: string,
+): Promise<Release> {
+  const existingRelease = getReleaseForCommit(
+    serviceName,
+    commitSha,
+    monorepoRoot,
+  );
+  if (existingRelease != null) {
+    console.log(
+      `${serviceName} release ${existingRelease.version ?? "unknown"} already exists for ${commitSha.slice(0, 7)}.`,
+    );
+    return existingRelease;
+  }
+
+  await triggerWorkflow(
+    serviceName,
+    repoSlug,
+    workflowFile,
+    monorepoRoot,
+    options,
+    commitSha,
+  );
+
+  const release = getReleaseForCommit(serviceName, commitSha, monorepoRoot);
+  if (release == null) {
+    throw new Error(
+      `No Ryvn release for ${serviceName} at ${commitSha} after ${workflowFile}.`,
+    );
+  }
+
+  return release;
+}
+
+function assertReleaseExistsForSkippedWorkflow(
+  serviceName: string,
+  commitSha: string,
+  monorepoRoot: string,
+): Release {
+  const release = getReleaseForCommit(serviceName, commitSha, monorepoRoot);
+  if (release == null) {
+    throw new Error(
+      `--skip-workflows was set, but no ${serviceName} Ryvn release exists for commit ${commitSha}. Rerun without --skip-workflows or confirm the release was created.`,
+    );
+  }
+
+  return release;
+}
+
+function logReleaseSummary(serviceName: string, release: Release): void {
+  console.log(
+    `${serviceName} release ready: ${release.version ?? "unknown version"}.`,
+  );
+}
+
+function requireReleaseForCurrentCommit(
+  serviceName: string,
+  repoSlug: string,
+  workflowFile: string,
+  monorepoRoot: string,
+  options: Options,
+  commitSha: string,
+): Promise<Release> {
+  if (options.skipWorkflows) {
+    return Promise.resolve(
+      assertReleaseExistsForSkippedWorkflow(
+        serviceName,
+        commitSha,
+        monorepoRoot,
+      ),
+    );
   }
+
+  return ensureReleaseForCurrentCommit(
+    serviceName,
+    repoSlug,
+    workflowFile,
+    monorepoRoot,
+    options,
+    commitSha,
+  );
+}
+
+function isRetryableReleaseFailure(error: unknown): boolean {
+  return error instanceof Error;
 }
 
 async function triggerWorkflow(
+  serviceName: string,
   repoSlug: string,
   workflowFile: string,
   monorepoRoot: string,
   options: Options,
+  commitSha: string,
 ): Promise<void> {
   if (options.skipWorkflows) return;
 
@@ -501,18 +721,32 @@ async function triggerWorkflow(
   }
 
   console.log(`Watching ${runInfo.url}`);
-  run(
-    "gh",
-    [
-      "run",
-      "watch",
-      String(runInfo.databaseId),
-      "--repo",
-      repoSlug,
-      "--exit-status",
-    ],
-    monorepoRoot,
-  );
+  try {
+    run(
+      "gh",
+      [
+        "run",
+        "watch",
+        String(runInfo.databaseId),
+        "--repo",
+        repoSlug,
+        "--exit-status",
+      ],
+      monorepoRoot,
+    );
+  } catch (error) {
+    printFailedWorkflowLog(repoSlug, runInfo.databaseId, monorepoRoot);
+
+    const release = getReleaseForCommit(serviceName, commitSha, monorepoRoot);
+    if (release != null && isRetryableReleaseFailure(error)) {
+      console.log(
+        `${workflowFile} reported a failure, but ${serviceName} release ${release.version ?? "unknown"} exists for ${commitSha.slice(0, 7)}; continuing.`,
+      );
+      return;
+    }
+
+    throw error;
+  }
 }
 
 function latestTask(tasks: InstallationTask[]): InstallationTask | null {
@@ -619,12 +853,11 @@ function parseEnvFile(
     );
 }
 
-async function patchInstallationSecrets(
+async function readInstallationSecrets(
   packageDir: string,
-  monorepoRoot: string,
   options: Options,
-): Promise<void> {
-  if (options.skipSecrets) return;
+): Promise<Array<{ name: string; value: string }>> {
+  if (options.skipSecrets) return [];
 
   const secretsPath = path.join(
     packageDir,
@@ -636,20 +869,42 @@ async function patchInstallationSecrets(
     console.log(
       `No secrets file found at ${secretsPath}; skipping secret patch.`,
     );
-    return;
+    return [];
+  }
+
+  return parseEnvFile(await readFile(secretsPath, "utf8"));
+}
+
+function appendInstallationSecrets(
+  manifestContents: string,
+  secrets: Array<{ name: string; value: string }>,
+): string {
+  if (secrets.length === 0) return manifestContents;
+
+  const marker = "  variableGroups:\n";
+  if (!manifestContents.includes(marker)) {
+    throw new Error("Installation manifest is missing variableGroups marker.");
   }
 
-  const secrets = parseEnvFile(await readFile(secretsPath, "utf8"));
+  const secretYaml = [
+    "  secrets:",
+    ...secrets.flatMap(({ name, value }) => [
+      `    - name: ${name}`,
+      `      value: ${JSON.stringify(value)}`,
+    ]),
+    "",
+  ].join("\n");
+
+  return manifestContents.replace(marker, `${secretYaml}${marker}`);
+}
+
+function patchExistingInstallationSecrets(
+  secrets: Array<{ name: string; value: string }>,
+  monorepoRoot: string,
+): void {
   if (secrets.length === 0) return;
 
-  const secretEnv = secrets.map(({ name, value }) => ({
-    key: name,
-    value,
-    isSecret: true,
-  }));
-  // Strategic merge preserves existing non-secret env entries while upserting
-  // these generated secrets by key.
-  const patch = JSON.stringify({ spec: { env: secretEnv, secrets } });
+  const patch = JSON.stringify({ spec: { secrets } });
   const result = spawnSync(
     "ryvn",
     [
@@ -672,7 +927,7 @@ async function patchInstallationSecrets(
   );
 
   if (result.status !== 0) {
-    throw new Error(`Failed to patch secrets for ${APP_NAME}.`);
+    throw new Error(`Failed to patch generated app secrets for ${APP_NAME}.`);
   }
 }
 
@@ -776,6 +1031,7 @@ async function main(): Promise<void> {
 
   const repoSlug = await ensureGitHubRepo(monorepoRoot, options);
   ensureCleanAndPushed(monorepoRoot, options);
+  const commitSha = getCurrentCommitSha(monorepoRoot);
 
   const ryvnDir = path.join(packageDir, "deploy", "ryvn");
   const serviceManifest = path.join(ryvnDir, `${APP_NAME}.service.yaml`);
@@ -802,27 +1058,46 @@ async function main(): Promise<void> {
   upsertService(terraformServiceManifest, monorepoRoot);
   upsertService(serviceManifest, monorepoRoot);
 
-  await triggerWorkflow(
+  const terraformRelease = await requireReleaseForCurrentCommit(
+    TERRAFORM_SERVICE_NAME,
     repoSlug,
     `${TERRAFORM_SERVICE_NAME}-ryvn-release.yaml`,
     monorepoRoot,
     options,
+    commitSha,
   );
+  logReleaseSummary(TERRAFORM_SERVICE_NAME, terraformRelease);
   upsertInstallation(
     TERRAFORM_SERVICE_NAME,
     terraformInstallationManifest,
     monorepoRoot,
+    commitSha,
   );
   await waitForTerraformApply(monorepoRoot, options);
 
-  await triggerWorkflow(
+  const appRelease = await requireReleaseForCurrentCommit(
+    APP_NAME,
     repoSlug,
     `${APP_NAME}-ryvn-release.yaml`,
     monorepoRoot,
     options,
+    commitSha,
+  );
+  logReleaseSummary(APP_NAME, appRelease);
+  const secrets = await readInstallationSecrets(packageDir, options);
+  if (installationExists(APP_NAME, monorepoRoot)) {
+    patchExistingInstallationSecrets(secrets, monorepoRoot);
+  }
+  upsertInstallation(
+    APP_NAME,
+    installationManifest,
+    monorepoRoot,
+    commitSha,
+    appendInstallationSecrets(
+      await readFile(installationManifest, "utf8"),
+      secrets,
+    ),
   );
-  upsertInstallation(APP_NAME, installationManifest, monorepoRoot);
-  await patchInstallationSecrets(packageDir, monorepoRoot, options);
   await waitForHealthy(monorepoRoot, options);
 
   await verifyDeployment();

package/templates/webapp/scripts/generate-migrations.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env tsx
+
+import { execFileSync } from "node:child_process";
+import { readFileSync, readdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { normalizeSchemaRelativeReferences } from "../src/drizzle/migrationSql";
+
+const migrationsDir = path.resolve("src", "drizzle", "migrations");
+
+function main(): void {
+  execFileSync("drizzle-kit", ["generate"], {
+    cwd: process.cwd(),
+    stdio: "inherit",
+  });
+
+  for (const fileName of readdirSync(migrationsDir)) {
+    if (!fileName.endsWith(".sql")) continue;
+
+    const filePath = path.join(migrationsDir, fileName);
+    const original = readFileSync(filePath, "utf8");
+    const normalized = normalizeSchemaRelativeReferences(original);
+    if (normalized !== original) {
+      writeFileSync(filePath, normalized);
+    }
+  }
+}
+
+main();

package/templates/webapp/src/drizzle/__tests__/migrationSql.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { normalizeSchemaRelativeReferences } from "../migrationSql";
+
+describe("normalizeSchemaRelativeReferences", () => {
+  it("keeps generated foreign keys schema-relative for DATABASE_SCHEMA deploys", () => {
+    expect(
+      normalizeSchemaRelativeReferences(
+        'ALTER TABLE "child" ADD CONSTRAINT "child_parent_fk" FOREIGN KEY ("parent_id") REFERENCES "public"."parent"("id") ON DELETE cascade;',
+      ),
+    ).toBe(
+      'ALTER TABLE "child" ADD CONSTRAINT "child_parent_fk" FOREIGN KEY ("parent_id") REFERENCES "parent"("id") ON DELETE cascade;',
+    );
+  });
+
+  it("leaves already schema-relative references unchanged", () => {
+    expect(
+      normalizeSchemaRelativeReferences(
+        'ALTER TABLE "child" ADD CONSTRAINT "child_parent_fk" FOREIGN KEY ("parent_id") REFERENCES "parent"("id");',
+      ),
+    ).toBe(
+      'ALTER TABLE "child" ADD CONSTRAINT "child_parent_fk" FOREIGN KEY ("parent_id") REFERENCES "parent"("id");',
+    );
+  });
+});

package/templates/webapp/src/drizzle/migrationSql.ts

@@ -0,0 +1,8 @@
+const PUBLIC_SCHEMA_REFERENCE_PATTERN = /REFERENCES\s+"public"\."([^"]+)"/g;
+
+export function normalizeSchemaRelativeReferences(sql: string): string {
+  return sql.replace(
+    PUBLIC_SCHEMA_REFERENCE_PATTERN,
+    (_match, tableName: string) => `REFERENCES "${tableName}"`,
+  );
+}

package/templates/webapp/src/services/inngest/AppWorkflowService.ts

@@ -0,0 +1,19 @@
+import { type AppInngest, InngestService } from "./InngestService";
+import { type ExampleEventPayload } from "./events/payloads/ExampleEventPayload";
+
+type AppWorkflowClient = Pick<AppInngest, "send">;
+
+export class AppWorkflowService {
+  public static create(): AppWorkflowService {
+    return new AppWorkflowService(InngestService.create().client);
+  }
+
+  public constructor(private inngestClient: AppWorkflowClient) {}
+
+  public async sendExampleEvent(payload: ExampleEventPayload): Promise<void> {
+    await this.inngestClient.send({
+      name: "app/example.event",
+      data: payload,
+    });
+  }
+}

package/templates/webapp/src/services/inngest/__tests__/AppWorkflowService.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it, vi } from "vitest";
+import { AppWorkflowService } from "../AppWorkflowService";
+import { AppEvents } from "../events/AppEvents";
+
+describe("AppWorkflowService", () => {
+  it("sends event data in the shape validated by AppEvents", async () => {
+    const payload = { exampleId: "example-1" };
+    const send = vi.fn().mockResolvedValue(undefined);
+    const service = new AppWorkflowService({ send } as never);
+
+    await service.sendExampleEvent(payload);
+
+    expect(AppEvents["app/example.event"].parse(payload)).toEqual(payload);
+    expect(send).toHaveBeenCalledWith({
+      name: "app/example.event",
+      data: payload,
+    });
+  });
+});

package/templates/webapp/src/services/inngest/events/AppEvents.ts

@@ -1,4 +1,3 @@
-import z from "zod";
 import { ExampleEventPayload } from "./payloads/ExampleEventPayload";
 
 /**
@@ -6,29 +5,24 @@ import { ExampleEventPayload } from "./payloads/ExampleEventPayload";
  *
  * Each event should have:
  * - A unique name (conventionally "app/event.name")
- * - A Zod schema for the event data
+ * - A Zod schema for event.data. Do not wrap the payload in another
+ *   `{ data: ... }` object here.
  *
  * @example
  * ```ts
  * export const AppEvents = {
  *   "app/user.created": z.object({
- *     data: z.object({
- *       userId: z.string(),
- *       email: z.string(),
- *     }),
+ *     userId: z.string(),
+ *     email: z.string(),
  *   }),
  *   "app/order.completed": z.object({
- *     data: z.object({
- *       orderId: z.string(),
- *       total: z.number(),
- *     }),
+ *     orderId: z.string(),
+ *     total: z.number(),
  *   }),
  * };
  * ```
  */
 export const AppEvents = {
   // Example event - replace with your actual events
-  "app/example.event": z.object({
-    data: ExampleEventPayload.SCHEMA,
-  }),
+  "app/example.event": ExampleEventPayload.SCHEMA,
 };

package/templates/webapp/src/services/inngest/events/payloads/ExampleEventPayload.ts

@@ -7,8 +7,6 @@ import z from "zod";
 export type ExampleEventPayload = z.infer<typeof ExampleEventPayload.SCHEMA>;
 export namespace ExampleEventPayload {
   export const SCHEMA = z.object({
-    // Add your event properties here
-    // exampleId: z.string(),
-    // data: z.record(z.unknown()),
+    exampleId: z.string(),
   });
 }