@percepta/create 3.1.2 → 3.1.3

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/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/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
+}

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

@@ -0,0 +1,38 @@
+terraform {
+  required_version = ">= 1.5.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+    postgresql = {
+      source  = "cyrilgdn/postgresql"
+      version = "~> 1.22"
+    }
+  }
+
+  backend "kubernetes" {}
+}
+
+provider "aws" {
+  region = var.aws_region
+}
+
+data "aws_secretsmanager_secret_version" "database" {
+  secret_id = var.database_secret_name
+}
+
+locals {
+  database_credentials = jsondecode(data.aws_secretsmanager_secret_version.database.secret_string)
+}
+
+provider "postgresql" {
+  host            = local.database_credentials.host
+  port            = tonumber(local.database_credentials.port)
+  username        = local.database_credentials.username
+  password        = local.database_credentials.password
+  sslmode         = "require"
+  connect_timeout = 15
+  superuser       = false
+}

package/templates/webapp/.github/workflows/__APP_NAME__-terraform.yml

@@ -1,28 +0,0 @@
-name: Terraform Validate (__APP_NAME__)
-
-on:
-  push:
-    paths:
-      - "packages/__APP_NAME__/terraform/**"
-      - ".github/workflows/__APP_NAME__-terraform.yml"
-
-jobs:
-  terraform-validate:
-    name: Validate Terraform
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Setup Terraform
-        uses: hashicorp/setup-terraform@v3
-
-      - name: Terraform Init
-        run: terraform -chdir=packages/__APP_NAME__/terraform init -backend=false
-
-      - name: Terraform Format Check
-        run: terraform fmt -check -recursive packages/__APP_NAME__/terraform/
-
-      - name: Terraform Validate
-        run: terraform -chdir=packages/__APP_NAME__/terraform validate