@percepta/create 3.1.0 → 3.1.3

package/templates/webapp/src/components/form/FormItem.tsx

@@ -34,7 +34,7 @@ export const FormItem: React.FC<FormItemProps> = ({
     return (
       <p
         id={messageId}
-        className="text-destructive-foreground text-sm"
+        className="text-sm text-destructive-foreground"
         data-slot="form-message"
       >
         {body}
@@ -70,7 +70,7 @@ export const FormItem: React.FC<FormItemProps> = ({
       {description != null && (
         <p
           id={descriptionId}
-          className="text-muted-foreground text-sm"
+          className="text-sm text-muted-foreground"
           data-slot="form-description"
         >
           {description}

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

@@ -3,6 +3,7 @@ import { Pool } from "pg";
 import { getEnvConfig } from "../config/getEnvConfig";
 import * as schema from "./schema";
 import { getPgSearchPathOption } from "./searchPath";
+import { getPgSslConfig } from "./ssl";
 
 export const { client, db } = createDb();
 
@@ -23,7 +24,7 @@ function createDb(): { client: Pool; db: NodePgDatabase<typeof schema> } {
     user,
     password,
     database,
-    ssl: useSSL,
+    ssl: getPgSslConfig(useSSL),
     options: getPgSearchPathOption(databaseSchema),
   });
 

package/templates/webapp/src/drizzle/migrations/0000_eager_grandmaster.sql

@@ -52,6 +52,6 @@ CREATE TABLE "verification" (
 	"updated_at" timestamp
 );
 --> statement-breakpoint
-ALTER TABLE "account" ADD CONSTRAINT "account_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "session" ADD CONSTRAINT "session_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-CREATE UNIQUE INDEX "lower_email_index" ON "users" USING btree (lower("email"));
+ALTER TABLE "account" ADD CONSTRAINT "account_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "session" ADD CONSTRAINT "session_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "lower_email_index" ON "users" USING btree (lower("email"));

package/templates/webapp/src/drizzle/migrations/meta/0000_snapshot.json

@@ -99,12 +99,8 @@
           "name": "account_user_id_users_id_fk",
           "tableFrom": "account",
           "tableTo": "users",
-          "columnsFrom": [
-            "user_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
           "onDelete": "cascade",
           "onUpdate": "no action"
         }
@@ -180,12 +176,8 @@
           "name": "session_user_id_users_id_fk",
           "tableFrom": "session",
           "tableTo": "users",
-          "columnsFrom": [
-            "user_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
           "onDelete": "cascade",
           "onUpdate": "no action"
         }
@@ -195,9 +187,7 @@
         "session_token_unique": {
           "name": "session_token_unique",
           "nullsNotDistinct": false,
-          "columns": [
-            "token"
-          ]
+          "columns": ["token"]
         }
       },
       "policies": {},
@@ -303,9 +293,7 @@
         "users_email_unique": {
           "name": "users_email_unique",
           "nullsNotDistinct": false,
-          "columns": [
-            "email"
-          ]
+          "columns": ["email"]
         }
       },
       "policies": {},
@@ -373,4 +361,4 @@
     "schemas": {},
     "tables": {}
   }
-}
+}

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

@@ -0,0 +1,5 @@
+export function getPgSslConfig(
+  useSSL: boolean,
+): false | { rejectUnauthorized: false } {
+  return useSSL ? { rejectUnauthorized: false } : false;
+}

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/lib/auth/index.ts

@@ -1,12 +1,12 @@
 import { betterAuth } from "better-auth";
 import { drizzleAdapter } from "better-auth/adapters/drizzle";
 import { admin } from "better-auth/plugins";
+import { getEnvConfig } from "../../config/getEnvConfig";
 import { db } from "../../drizzle/db";
 import { accounts } from "../../drizzle/schema/auth/accounts";
 import { sessions } from "../../drizzle/schema/auth/sessions";
 import { users } from "../../drizzle/schema/auth/users";
 import { verifications } from "../../drizzle/schema/auth/verifications";
-import { getEnvConfig } from "../../config/getEnvConfig";
 import { getLogger } from "../../services/logger/AppLogger";
 
 // eslint-disable-next-line n/no-process-env -- detecting Next.js build phase

package/templates/webapp/src/lib/auth-client.ts

@@ -1,5 +1,5 @@
-import { createAuthClient } from "better-auth/react";
 import { adminClient } from "better-auth/client/plugins";
+import { createAuthClient } from "better-auth/react";
 
 export const authClient = createAuthClient({
   plugins: [adminClient()],

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/src/services/observability/initFaro.ts

@@ -1,7 +1,7 @@
 "use client";
 
-import { createFaroInstance } from "@percepta/next-utils/faro";
 import { TracingInstrumentation } from "@grafana/faro-web-tracing";
+import { createFaroInstance } from "@percepta/next-utils/faro";
 import { getClientEnvConfig } from "../../config/clientEnvConfig";
 
 const {

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