@percepta/create 3.1.2 → 3.1.4

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/scripts/migrate.ts

@@ -6,10 +6,13 @@ async function main(): Promise<void> {
   loadEnvConfig(process.cwd());
 
   // Dynamically load because we need to load the environment variables before importing modules that depend on them.
+  const { getEnvConfig } = await import("../src/config/getEnvConfig");
   const { client } = await import("../src/drizzle/db");
+  const { DATABASE_SCHEMA: databaseSchema } = getEnvConfig();
 
   await migrate(drizzle(client), {
     migrationsFolder: "./src/drizzle/migrations",
+    ...(databaseSchema ? { migrationsSchema: databaseSchema } : {}),
   });
 
   await client.end();

package/templates/webapp/scripts/open-ryvn-deploy-pr.ts

@@ -32,7 +32,9 @@ function parseArgs(argv: string[]): Options {
 
   for (let index = 0; index < argv.length; index++) {
     const arg = argv[index];
-    if (arg === "--yes" || arg === "-y") {
+    if (arg === "--") {
+      continue;
+    } else if (arg === "--yes" || arg === "-y") {
       options.yes = true;
     } else if (arg === "--no-clone") {
       options.noClone = true;
@@ -357,7 +359,7 @@ function getPrBody(phase: DeployPhase): string {
       "1. Let GitOps import the service.",
       "2. Approve/apply the percepta-internal Terraform task if one is created.",
       "3. Push the app to main or run the release workflow so Ryvn has a first release.",
-      `4. Open the installation PR with pnpm deploy:percepta-test -- --phase installation --yes.`,
+      `4. Open the installation PR with pnpm deploy:percepta-test:pr -- --phase installation --yes.`,
     ].join("\n");
   }
 
@@ -383,7 +385,7 @@ function printNextSteps(phase: DeployPhase): void {
     );
     console.log("4. Push the app to main or run the release workflow.");
     console.log(
-      "5. Run: pnpm deploy:percepta-test -- --phase installation --yes",
+      "5. Run: pnpm deploy:percepta-test:pr -- --phase installation --yes",
     );
     return;
   }

package/templates/webapp/scripts/with-local-env.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env tsx
+
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+type EnvMap = Record<string, string>;
+
+const LOCAL_ENV_PATH = path.join(
+  homedir(),
+  ".config",
+  "percepta",
+  "create.env",
+);
+
+function parseEnvFile(filePath: string): EnvMap {
+  if (!existsSync(filePath)) return {};
+
+  const env: EnvMap = {};
+  const content = readFileSync(filePath, "utf8");
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const normalized = line.startsWith("export ") ? line.slice(7).trim() : line;
+    const separatorIndex = normalized.indexOf("=");
+    if (separatorIndex === -1) continue;
+
+    const key = normalized.slice(0, separatorIndex).trim();
+    const rawValue = normalized.slice(separatorIndex + 1).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+
+    env[key] = unquote(rawValue);
+  }
+
+  return env;
+}
+
+function unquote(value: string): string {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+
+  return value;
+}
+
+const [command, ...args] = process.argv.slice(2);
+if (!command) {
+  throw new Error("Usage: tsx scripts/with-local-env.ts <command> [...args]");
+}
+
+const child = spawn(command, args, {
+  env: {
+    ...parseEnvFile(LOCAL_ENV_PATH),
+    ...process.env,
+  },
+  stdio: "inherit",
+});
+
+child.on("error", (error) => {
+  throw error;
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  process.exit(code ?? 1);
+});

package/templates/webapp/src/config/getEnvConfig.ts

@@ -44,12 +44,26 @@ export const { getEnvConfig, schema: ENV_CONFIG_SCHEMA } = createEnvConfig(
     LANGFUSE_PUBLIC_KEY: z.string().optional(),
     LANGFUSE_SECRET_KEY: z.string().optional(),
 
+    // OpenTelemetry:
+    OTEL_SERVICE_NAME: z.string().optional(),
+    OTEL_RESOURCE_ATTRIBUTES: z.string().optional(),
+    OTEL_TRACES_EXPORTER: z.string().optional(),
+    OTEL_METRICS_EXPORTER: z.string().optional(),
+    OTEL_EXPORTER_OTLP_PROTOCOL: z.string().optional(),
+    OTEL_EXPORTER_OTLP_ENDPOINT: z.string().optional(),
+    OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: z.string().optional(),
+    OTEL_EXPORTER_OTLP_METRICS_ENDPOINT: z.string().optional(),
+    OTEL_METRIC_EXPORT_INTERVAL: z.string().optional(),
+
     // Security:
     ENCRYPTION_SECRET_KEY: z.string().optional(),
     TRIGGER_ENDPOINT_API_KEY: z.string().optional(),
 
     // LLM/AI providers:
+    ANTHROPIC_API_KEY: z.string().optional(),
     OPENAI_API_KEY: z.string().optional(),
+    LLM_PROVIDER: z.enum(["anthropic", "openai"]).optional(),
+    LLM_MODEL: z.string().optional(),
 
     // Readonly database (scripts):
     READONLY_SECRET_NAME: z.string().optional(),

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/instrumentation.ts

@@ -1,34 +1,126 @@
 import { LangfuseSpanProcessor } from "@langfuse/otel";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
-import { NodeSDK } from "@opentelemetry/sdk-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
+import { NodeSDK, tracing } from "@opentelemetry/sdk-node";
 import { compact } from "lodash-es";
 import { getEnvConfig } from "./config/getEnvConfig";
 import { getLogger } from "./services/logger/AppLogger";
 
-function getSpanProcessor(): LangfuseSpanProcessor | undefined {
+type SpanProcessor = tracing.SpanProcessor;
+type ReadableSpan = Parameters<SpanProcessor["onEnd"]>[0];
+type OnStartArgs = Parameters<SpanProcessor["onStart"]>;
+
+class FilteringSpanProcessor implements SpanProcessor {
+  public constructor(
+    private delegate: SpanProcessor,
+    private shouldExport: (span: ReadableSpan) => boolean,
+  ) {}
+
+  public forceFlush(): Promise<void> {
+    return this.delegate.forceFlush();
+  }
+
+  public onStart(...args: OnStartArgs): void {
+    this.delegate.onStart(...args);
+  }
+
+  public onEnd(span: ReadableSpan): void {
+    if (this.shouldExport(span)) {
+      this.delegate.onEnd(span);
+    }
+  }
+
+  public shutdown(): Promise<void> {
+    return this.delegate.shutdown();
+  }
+}
+
+function isAiSdkSpan(span: ReadableSpan): boolean {
+  const operationId = span.attributes["ai.operationId"];
+  if (typeof operationId === "string" && operationId.startsWith("ai.")) {
+    return true;
+  }
+
+  if (span.name.startsWith("ai.")) {
+    return true;
+  }
+
+  return Object.keys(span.attributes).some((key) => key.startsWith("gen_ai."));
+}
+
+function getOtlpTracesEndpoint(): string | undefined {
+  const {
+    OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: tracesEndpoint,
+    OTEL_EXPORTER_OTLP_ENDPOINT: baseEndpoint,
+  } = getEnvConfig();
+
+  if (tracesEndpoint) return tracesEndpoint;
+
+  if (!baseEndpoint) return undefined;
+
+  return `${baseEndpoint.replace(/\/$/, "")}/v1/traces`;
+}
+
+function getOtlpSpanProcessor(): tracing.BatchSpanProcessor | undefined {
+  const { OTEL_TRACES_EXPORTER: tracesExporter } = getEnvConfig();
+  if (tracesExporter === "none") {
+    getLogger().debug(
+      undefined,
+      "OTEL_TRACES_EXPORTER=none. Skipping OTLP trace export.",
+    );
+    return undefined;
+  }
+
+  const tracesEndpoint = getOtlpTracesEndpoint();
+  if (!tracesEndpoint) {
+    getLogger().debug(
+      undefined,
+      "No OTLP trace endpoint found. Skipping OTLP trace export.",
+    );
+    return undefined;
+  }
+
+  getLogger().debug(
+    { safe: { tracesEndpoint } },
+    "Registering OTLP trace exporter.",
+  );
+  return new tracing.BatchSpanProcessor(
+    new OTLPTraceExporter({ url: tracesEndpoint }),
+  );
+}
+
+function getLangfuseSpanProcessor(): SpanProcessor | undefined {
   const {
     LANGFUSE_BASE_URL: baseUrl,
     LANGFUSE_PUBLIC_KEY: publicKey,
     LANGFUSE_SECRET_KEY: secretKey,
   } = getEnvConfig();
-  if (baseUrl == null) {
+  if (!baseUrl || !publicKey || !secretKey) {
     getLogger().debug(
       undefined,
-      "No Langfuse base URL found. Skipping Langfuse OpenTelemetry.",
+      "Langfuse environment is incomplete. Skipping Langfuse OpenTelemetry.",
     );
     return undefined;
   }
 
   getLogger().debug(undefined, "Registering Langfuse OpenTelemetry.");
-  return new LangfuseSpanProcessor({
-    baseUrl,
-    publicKey,
-    secretKey,
-  });
+  return new FilteringSpanProcessor(
+    new LangfuseSpanProcessor({
+      baseUrl,
+      publicKey,
+      secretKey,
+    }),
+    isAiSdkSpan,
+  );
 }
 
+const spanProcessors: tracing.SpanProcessor[] = compact([
+  getOtlpSpanProcessor(),
+  getLangfuseSpanProcessor(),
+]);
+
 const sdk = new NodeSDK({
-  spanProcessors: compact([getSpanProcessor()]),
+  spanProcessors,
   instrumentations: [getNodeAutoInstrumentations()],
 });
 

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(),
   });
 }

package/templates/webapp/src/services/llm/LLMService.ts

@@ -0,0 +1,88 @@
+import { generateText, streamText } from "ai";
+import { type LlmProviderName, LlmProviderService } from "./LlmProviderService";
+
+type GenerateTextOptions = Omit<Parameters<typeof generateText>[0], "model"> & {
+  modelId?: string;
+  provider?: LlmProviderName;
+  telemetryFunctionId?: string;
+};
+
+type StreamTextOptions = Omit<Parameters<typeof streamText>[0], "model"> & {
+  modelId?: string;
+  provider?: LlmProviderName;
+  telemetryFunctionId?: string;
+};
+
+export class LLMService {
+  private static SINGLETON: LLMService | undefined;
+
+  public static create(): LLMService {
+    if (LLMService.SINGLETON == null) {
+      LLMService.SINGLETON = new LLMService(LlmProviderService.create());
+    }
+
+    return LLMService.SINGLETON;
+  }
+
+  private constructor(private llmProviderService: LlmProviderService) {}
+
+  public generateText(
+    options: GenerateTextOptions,
+  ): ReturnType<typeof generateText> {
+    const { modelId, provider, telemetryFunctionId, ...generateOptions } =
+      options;
+    const selection = this.llmProviderService.getLanguageModel({
+      modelId,
+      provider,
+    });
+
+    const aiOptions = {
+      ...generateOptions,
+      model: selection.model,
+      experimental_telemetry: {
+        ...generateOptions.experimental_telemetry,
+        isEnabled: generateOptions.experimental_telemetry?.isEnabled ?? true,
+        functionId:
+          telemetryFunctionId ??
+          generateOptions.experimental_telemetry?.functionId ??
+          "llm.generateText",
+        metadata: {
+          ...generateOptions.experimental_telemetry?.metadata,
+          llmProvider: selection.provider,
+          llmModel: selection.modelId,
+        },
+      },
+    } as Parameters<typeof generateText>[0];
+
+    return generateText(aiOptions);
+  }
+
+  public streamText(options: StreamTextOptions): ReturnType<typeof streamText> {
+    const { modelId, provider, telemetryFunctionId, ...streamOptions } =
+      options;
+    const selection = this.llmProviderService.getLanguageModel({
+      modelId,
+      provider,
+    });
+
+    const aiOptions = {
+      ...streamOptions,
+      model: selection.model,
+      experimental_telemetry: {
+        ...streamOptions.experimental_telemetry,
+        isEnabled: streamOptions.experimental_telemetry?.isEnabled ?? true,
+        functionId:
+          telemetryFunctionId ??
+          streamOptions.experimental_telemetry?.functionId ??
+          "llm.streamText",
+        metadata: {
+          ...streamOptions.experimental_telemetry?.metadata,
+          llmProvider: selection.provider,
+          llmModel: selection.modelId,
+        },
+      },
+    } as Parameters<typeof streamText>[0];
+
+    return streamText(aiOptions);
+  }
+}

package/templates/webapp/src/services/llm/LlmProviderService.ts

@@ -0,0 +1,85 @@
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createOpenAI } from "@ai-sdk/openai";
+import { type LanguageModel } from "ai";
+import { getEnvConfig } from "../../config/getEnvConfig";
+
+export type LlmProviderName = "anthropic" | "openai";
+
+export interface LanguageModelSelection {
+  model: LanguageModel;
+  modelId: string;
+  provider: LlmProviderName;
+}
+
+interface GetLanguageModelOptions {
+  modelId?: string;
+  provider?: LlmProviderName;
+}
+
+const DEFAULT_ANTHROPIC_MODEL = "claude-sonnet-4-5-20250929";
+const DEFAULT_OPENAI_MODEL = "gpt-4.1";
+
+export class LlmProviderService {
+  private static SINGLETON: LlmProviderService | undefined;
+
+  public static create(): LlmProviderService {
+    if (LlmProviderService.SINGLETON == null) {
+      LlmProviderService.SINGLETON = new LlmProviderService();
+    }
+
+    return LlmProviderService.SINGLETON;
+  }
+
+  private constructor() {}
+
+  public getLanguageModel(
+    options: GetLanguageModelOptions = {},
+  ): LanguageModelSelection {
+    const config = getEnvConfig();
+    const provider =
+      options.provider ??
+      config.LLM_PROVIDER ??
+      (config.ANTHROPIC_API_KEY ? "anthropic" : undefined) ??
+      (config.OPENAI_API_KEY ? "openai" : undefined);
+
+    if (provider === "anthropic") {
+      if (!config.ANTHROPIC_API_KEY) {
+        throw new Error(
+          "LLM_PROVIDER=anthropic but ANTHROPIC_API_KEY is not configured.",
+        );
+      }
+
+      const modelId =
+        options.modelId ?? config.LLM_MODEL ?? DEFAULT_ANTHROPIC_MODEL;
+      return {
+        provider,
+        modelId,
+        model: createAnthropic({
+          apiKey: config.ANTHROPIC_API_KEY,
+        }).languageModel(modelId),
+      };
+    }
+
+    if (provider === "openai") {
+      if (!config.OPENAI_API_KEY) {
+        throw new Error(
+          "LLM_PROVIDER=openai but OPENAI_API_KEY is not configured.",
+        );
+      }
+
+      const modelId =
+        options.modelId ?? config.LLM_MODEL ?? DEFAULT_OPENAI_MODEL;
+      return {
+        provider,
+        modelId,
+        model: createOpenAI({
+          apiKey: config.OPENAI_API_KEY,
+        }).languageModel(modelId),
+      };
+    }
+
+    throw new Error(
+      "No LLM provider is configured. Set ANTHROPIC_API_KEY or OPENAI_API_KEY locally, or deploy to an environment with a shared LLM variable group.",
+    );
+  }
+}

package/templates/webapp/terraform/schema/main.tf

@@ -0,0 +1,4 @@
+resource "postgresql_schema" "demo" {
+  database = var.database_name
+  name     = var.schema_name
+}

package/templates/webapp/terraform/schema/outputs.tf

@@ -0,0 +1,9 @@
+output "database_name" {
+  description = "Database containing the demo schema."
+  value       = var.database_name
+}
+
+output "schema_name" {
+  description = "Created demo schema name."
+  value       = postgresql_schema.demo.name
+}

package/templates/webapp/terraform/schema/variables.tf

@@ -0,0 +1,19 @@
+variable "aws_region" {
+  description = "AWS region containing the shared Percepta internal database secret."
+  type        = string
+}
+
+variable "database_secret_name" {
+  description = "AWS Secrets Manager secret name containing shared Postgres credentials."
+  type        = string
+}
+
+variable "database_name" {
+  description = "Database where the demo app schema should be created."
+  type        = string
+}
+
+variable "schema_name" {
+  description = "Postgres schema name for this demo app."
+  type        = string
+}