@percepta/create 3.0.0

package/templates/webapp/src/server/trpc.ts

@@ -0,0 +1,61 @@
+import { TRPCError, initTRPC } from "@trpc/server";
+import { headers } from "next/headers";
+import superjson from "superjson";
+import { type BetterAuthSession, auth } from "../lib/auth";
+import { AuthContextService } from "../services/AuthContextService";
+import { getTracer } from "../services/logger/AppLogger";
+
+export interface Context {
+  session: BetterAuthSession | null;
+  services: {
+    authContext: AuthContextService;
+  };
+}
+
+export interface ProtectedContext extends Context {
+  session: BetterAuthSession;
+}
+
+export async function createContext(): Promise<Context> {
+  const session = await auth.api.getSession({
+    headers: await headers(),
+  });
+
+  const services: Context["services"] = {
+    authContext: AuthContextService.create(),
+  };
+
+  return { session, services };
+}
+
+export const { router, procedure } = initTRPC.context<Context>().create({
+  transformer: superjson,
+  errorFormatter({ shape }) {
+    const tracer = getTracer();
+    return {
+      ...shape,
+      data: {
+        ...(tracer != null && { traceId: tracer.traceId }),
+        ...shape.data,
+      },
+    };
+  },
+});
+
+export const protectedProcedure = procedure.use(
+  ({ ctx, next }): ReturnType<typeof next<ProtectedContext>> => {
+    const {
+      session,
+      services: { authContext },
+    } = ctx;
+    if (session?.user == null) {
+      throw new TRPCError({ code: "UNAUTHORIZED" });
+    }
+
+    return authContext.withSession(session, () =>
+      next({
+        ctx,
+      }),
+    );
+  },
+);

package/templates/webapp/src/services/AuthContextService.ts

@@ -0,0 +1,63 @@
+import { trace } from "@opentelemetry/api";
+import { TRPCError } from "@trpc/server";
+import type { BetterAuthSession } from "../lib/auth";
+
+export type AuthSession = BetterAuthSession;
+
+export class AuthContextService {
+  private static SINGLETON: AuthContextService | undefined;
+  public static create(): AuthContextService {
+    if (AuthContextService.SINGLETON == null) {
+      AuthContextService.SINGLETON = new AuthContextService();
+    }
+
+    return AuthContextService.SINGLETON;
+  }
+
+  private authAsyncLocalStorage = new AsyncLocalStorage<LocalStorage>();
+
+  private constructor() {}
+
+  public withSession<TReturn>(
+    session: AuthSession,
+    callback: () => TReturn,
+  ): TReturn {
+    // Set user email on the active OpenTelemetry span
+    const activeSpan = trace.getActiveSpan();
+    if (
+      activeSpan != null &&
+      session.user.email != null &&
+      session.user.id != null
+    ) {
+      activeSpan.setAttribute("user.email", session.user.email);
+      activeSpan.setAttribute("user.id", session.user.id);
+    }
+
+    return this.authAsyncLocalStorage.run<TReturn>({ session }, () =>
+      callback(),
+    );
+  }
+
+  public getSession(): AuthSession | undefined {
+    const context = this.authAsyncLocalStorage.getStore();
+    if (context == null) {
+      return undefined;
+    }
+
+    const { session } = context;
+    return session;
+  }
+
+  public getSessionOrThrow(): AuthSession {
+    const session = this.getSession();
+    if (session == null) {
+      throw new TRPCError({ code: "UNAUTHORIZED" });
+    }
+
+    return session;
+  }
+}
+
+interface LocalStorage {
+  session: AuthSession;
+}

package/templates/webapp/src/services/DatabaseService.ts

@@ -0,0 +1,54 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { type NodePgDatabase } from "drizzle-orm/node-postgres";
+import { db } from "../drizzle/db";
+import type * as schema from "../drizzle/schema";
+
+export class DatabaseService {
+  private static SINGLETON: DatabaseService | undefined;
+  public static create(): DatabaseService {
+    if (DatabaseService.SINGLETON == null) {
+      DatabaseService.SINGLETON = new DatabaseService(db);
+    }
+
+    return DatabaseService.SINGLETON;
+  }
+
+  private transactionAsyncLocalStorage = new AsyncLocalStorage<LocalStorage>();
+
+  private constructor(private database: NodePgDatabase<typeof schema>) {}
+
+  public async createTransaction<TReturn>(
+    callback: (txn: NodePgDatabase<typeof schema>) => Promise<TReturn>,
+  ): Promise<TReturn> {
+    const currentContext = this.transactionAsyncLocalStorage.getStore();
+    if (currentContext != null) {
+      const { txn } = currentContext;
+
+      // Already in a transaction.
+      return callback(txn);
+    }
+
+    return this.database.transaction((txn) => {
+      return this.transactionAsyncLocalStorage.run<Promise<TReturn>>(
+        { txn },
+        () => callback(txn),
+      );
+    });
+  }
+
+  public getDatabase(): Database {
+    const context = this.transactionAsyncLocalStorage.getStore();
+    if (context == null) {
+      return this.database;
+    }
+
+    const { txn } = context;
+    return txn;
+  }
+}
+
+type Database = Omit<NodePgDatabase<typeof schema>, "transaction">;
+
+interface LocalStorage {
+  txn: NodePgDatabase<typeof schema>;
+}

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

@@ -0,0 +1,5 @@
+import { type InngestFunction } from "inngest";
+
+export interface InngestFunctionCollection {
+  functions: InngestFunction.Like[];
+}

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

@@ -0,0 +1,71 @@
+import { validationMiddleware } from "@inngest/middleware-validation";
+import { EventSchemas, Inngest } from "inngest";
+import { getEnvConfig } from "../../config/getEnvConfig";
+import { AppEvents } from "./events/AppEvents";
+
+export interface PollOpts {
+  maxAttempts: number;
+  delayMs: number;
+}
+
+export interface AppInngest extends AppInngestInternal {
+  // Externally, we should never call createFunction on the client interface.
+  createFunction: never;
+}
+type AppInngestInternal = Inngest<{
+  id: string;
+  schemas: typeof EVENT_SCHEMAS;
+}>;
+
+export class InngestService {
+  private static SINGLETON: InngestService | undefined;
+  public static create(): InngestService {
+    if (InngestService.SINGLETON == null) {
+      InngestService.SINGLETON = new InngestService();
+    }
+    return InngestService.SINGLETON;
+  }
+
+  private _signingKey: string | undefined;
+  private inngest: AppInngestInternal;
+
+  private constructor() {
+    const {
+      INNGEST_BASE_URL: baseUrl,
+      INNGEST_SIGNING_KEY: signingKey,
+      INNGEST_EVENT_KEY: eventKey,
+    } = getEnvConfig();
+
+    if (baseUrl == null) {
+      throw new Error("INNGEST_BASE_URL is not set.");
+    }
+
+    this._signingKey = signingKey;
+    this.inngest = new Inngest({
+      id: "__APP_NAME__",
+      eventKey,
+      baseUrl,
+      schemas: EVENT_SCHEMAS,
+      middleware: [validationMiddleware()],
+    });
+  }
+
+  public get client(): AppInngest {
+    return this.inngest as never;
+  }
+
+  public get signingKey(): string | undefined {
+    return this._signingKey;
+  }
+
+  public createFunction: Inngest.CreateFunction<AppInngest> = (
+    options,
+    trigger,
+    handler,
+  ) => {
+    // TODO: Add context plumbing here.
+    return this.inngest.createFunction(options, trigger, handler) as never;
+  };
+}
+
+const EVENT_SCHEMAS = new EventSchemas().fromSchema(AppEvents);

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

@@ -0,0 +1,34 @@
+import z from "zod";
+import { ExampleEventPayload } from "./payloads/ExampleEventPayload";
+
+/**
+ * Define all Inngest events for the application here.
+ *
+ * Each event should have:
+ * - A unique name (conventionally "app/event.name")
+ * - A Zod schema for the event data
+ *
+ * @example
+ * ```ts
+ * export const AppEvents = {
+ *   "app/user.created": z.object({
+ *     data: z.object({
+ *       userId: z.string(),
+ *       email: z.string(),
+ *     }),
+ *   }),
+ *   "app/order.completed": z.object({
+ *     data: z.object({
+ *       orderId: z.string(),
+ *       total: z.number(),
+ *     }),
+ *   }),
+ * };
+ * ```
+ */
+export const AppEvents = {
+  // Example event - replace with your actual events
+  "app/example.event": z.object({
+    data: ExampleEventPayload.SCHEMA,
+  }),
+};

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

@@ -0,0 +1,14 @@
+import z from "zod";
+
+/**
+ * Example event payload schema.
+ * Replace this with your actual event payloads.
+ */
+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()),
+  });
+}

package/templates/webapp/src/services/langfuse/LangfuseService.ts

@@ -0,0 +1,80 @@
+import { Langfuse } from "langfuse";
+import { getEnvConfig } from "../../config/getEnvConfig";
+import { getLogger } from "../logger/AppLogger";
+
+export class LangfuseService {
+  private static SINGLETON: LangfuseService | undefined;
+
+  public static create(): LangfuseService {
+    if (LangfuseService.SINGLETON == null) {
+      LangfuseService.SINGLETON = new LangfuseService();
+    }
+    return LangfuseService.SINGLETON;
+  }
+
+  private readonly client: Langfuse | undefined;
+
+  private constructor() {
+    const config = getEnvConfig();
+    const baseUrl = config.LANGFUSE_BASE_URL;
+    const publicKey = config.LANGFUSE_PUBLIC_KEY;
+    const secretKey = config.LANGFUSE_SECRET_KEY;
+
+    if (baseUrl && publicKey && secretKey) {
+      this.client = new Langfuse({
+        baseUrl,
+        publicKey,
+        secretKey,
+      });
+    }
+  }
+
+  /**
+   * Check if Langfuse is configured.
+   */
+  public isConfigured(): boolean {
+    return this.client != null;
+  }
+
+  /**
+   * Update a Langfuse trace with metadata.
+   * Uses trace.update() which merges with existing metadata.
+   *
+   * @param traceId - The trace ID (same as documentPipelineRuns.id)
+   * @param metadata - The metadata to save (must be JSON-serializable)
+   */
+  public async updateTraceMetadata<T extends object>(
+    traceId: string,
+    metadata: T,
+  ): Promise<void> {
+    if (!this.isConfigured()) {
+      getLogger().warn(
+        { safe: { traceId } },
+        "[LangfuseService] Langfuse not configured, skipping trace update",
+      );
+      return;
+    }
+
+    // Capture client after isConfigured() guard for type narrowing
+    const client = this.client!;
+
+    try {
+      // Attach to existing trace by ID and update metadata
+      const trace = client.trace({ id: traceId });
+      trace.update({ metadata });
+
+      // Flush to ensure the update is sent
+      await client.flushAsync();
+
+      getLogger().info(
+        { safe: { traceId } },
+        "[LangfuseService] Updated trace with metadata",
+      );
+    } catch (error) {
+      getLogger().error(
+        { safe: { traceId }, unsafe: { error: String(error) } },
+        "[LangfuseService] Failed to update trace metadata",
+      );
+    }
+  }
+}

package/templates/webapp/src/services/logger/AppLogger.ts

@@ -0,0 +1,61 @@
+import {
+  type MosaicLogger,
+  createLogFactory,
+  createTracerFactory,
+} from "@percepta/logger";
+import { assertNever } from "@percepta/utils";
+import pino, { type Logger } from "pino";
+import pretty from "pino-pretty";
+import { getEnvConfig } from "../../config/getEnvConfig";
+
+/**
+ * The main application logger.
+ * Uses Pino under the hood with AsyncLocalStorage for request context.
+ *
+ * Usage:
+ *   getLogger().info({ safe: { key: value } }, "message");
+ *   getLogger().error({ unsafe: { pii: data } }, "error message", error);
+ *
+ * All logs automatically include request context (reqId, method, path, host)
+ * when called within a request scope established by withLogContext().
+ */
+export const { getLogger, withLogContext } = createLogFactory(
+  createBasePinoInstance(),
+  () => new AsyncLocalStorage<MosaicLogger>(),
+);
+
+/**
+ * Tracer for request context propagation.
+ * Uses AsyncLocalStorage to pass trace IDs through async boundaries.
+ */
+export const { getTracer, withTracer } = createTracerFactory(
+  () => new AsyncLocalStorage(),
+);
+
+// TODO(@dzhao): Generalize this and move to createPinoInstance.ts.
+function createBasePinoInstance(): Logger {
+  const { NODE_ENV: nodeEnv, LOG_LEVEL: level } = getEnvConfig();
+
+  switch (nodeEnv) {
+    case "production":
+      return pino({
+        level,
+        formatters: {
+          level: (label) => ({ level: label }),
+        },
+      });
+    case "development":
+    case "test":
+      // Development: use pino-pretty synchronously (avoids worker thread issues with Next.js/Turbopack)
+      return pino(
+        { level },
+        pretty({
+          colorize: true,
+          translateTime: "SYS:standard",
+          ignore: "pid,hostname",
+        }),
+      );
+    default:
+      return assertNever(nodeEnv);
+  }
+}

package/templates/webapp/src/services/logger/withRequestContext.ts

@@ -0,0 +1,27 @@
+import {
+  type RequestContext,
+  createRequestContextFromNextApiRequest,
+  createRequestContextFromRequest,
+  createRequestContextMiddleware,
+  getRequestId,
+} from "@percepta/next-utils";
+import { withLogContext, withTracer } from "./AppLogger";
+
+/**
+ * Request context middleware with injected dependencies.
+ * Uses the local withLogContext and withTracer implementations.
+ */
+const { withRequestContext, withAppRouterRequestContext } =
+  createRequestContextMiddleware({
+    withLogContext,
+    withTracer,
+  });
+
+export {
+  withRequestContext,
+  withAppRouterRequestContext,
+  createRequestContextFromNextApiRequest,
+  createRequestContextFromRequest,
+  getRequestId,
+  type RequestContext,
+};

package/templates/webapp/src/services/observability/initFaro.ts

@@ -0,0 +1,22 @@
+"use client";
+
+import { createFaroInstance } from "@percepta/next-utils/faro";
+import { TracingInstrumentation } from "@grafana/faro-web-tracing";
+import { getClientEnvConfig } from "../../config/clientEnvConfig";
+
+const {
+  FARO_COLLECTOR_URL,
+  FARO_APP_NAME,
+  FARO_APP_VERSION,
+  FARO_APP_ENVIRONMENT,
+} = getClientEnvConfig();
+
+export const faroInstance = createFaroInstance({
+  collectorUrl: FARO_COLLECTOR_URL,
+  app: {
+    name: FARO_APP_NAME,
+    version: FARO_APP_VERSION,
+    environment: FARO_APP_ENVIRONMENT,
+  },
+  extraInstrumentations: [new TracingInstrumentation()],
+});

package/templates/webapp/src/startup-checks.ts

@@ -0,0 +1,32 @@
+import { getEnvConfig } from "./config/getEnvConfig";
+import { client } from "./drizzle/db";
+import { getLogger } from "./services/logger/AppLogger";
+
+export async function checkStartup(): Promise<boolean> {
+  return validateEnvironment() && (await validateDatabaseConnection());
+}
+
+function validateEnvironment(): boolean {
+  try {
+    getEnvConfig();
+  } catch {
+    getLogger().warn(undefined, "Environment config validation failed");
+    return false;
+  }
+  return true;
+}
+
+async function validateDatabaseConnection(): Promise<boolean> {
+  try {
+    const dbCheckPromise = client.query("SELECT 1");
+
+    const timeoutPromise = new Promise((_, reject) =>
+      setTimeout(() => reject(new Error("Database check timeout")), 5000),
+    );
+    await Promise.race([dbCheckPromise, timeoutPromise]);
+  } catch {
+    getLogger().warn(undefined, "Database connection failed");
+    return false;
+  }
+  return true;
+}

package/templates/webapp/src/styles/globals.css

@@ -0,0 +1,27 @@
+@import "tailwindcss";
+@import "@percepta/design/theme";
+
+:root {
+  --background: #ffffff;
+  --foreground: #171717;
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: #0a0a0a;
+    --foreground: #ededed;
+  }
+}
+
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: Arial, Helvetica, sans-serif;
+}

package/templates/webapp/src/utils/__tests__/cn.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { cn } from "../cn";
+
+describe("cn", () => {
+  it("merges class names", () => {
+    expect(cn("foo", "bar")).toBe("foo bar");
+  });
+
+  it("handles falsy values", () => {
+    expect(cn("base", undefined, "visible")).toBe("base visible");
+  });
+
+  it("deduplicates conflicting Tailwind classes", () => {
+    expect(cn("px-2", "px-4")).toBe("px-4");
+  });
+
+  it("returns an empty string when given no arguments", () => {
+    expect(cn()).toBe("");
+  });
+});

package/templates/webapp/src/utils/cn.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}

package/templates/webapp/src/utils/syncInngestApp.ts

@@ -0,0 +1,62 @@
+import { getEnvConfig } from "../config/getEnvConfig";
+import { getLogger } from "../services/logger/AppLogger";
+
+export async function syncInngestApp(): Promise<void> {
+  const {
+    SKIP_INNGEST_SYNC: skipSync,
+    INNGEST_BASE_URL: inngestServerUrl,
+    APP_BASE_URL: appBaseUrl,
+    INNGEST_APP_URL,
+  } = getEnvConfig();
+
+  // Cascade: explicit INNGEST_APP_URL > derived from APP_BASE_URL > localhost fallback
+  const appUrl =
+    INNGEST_APP_URL ??
+    (appBaseUrl
+      ? `${appBaseUrl}/api/inngest`
+      : "http://localhost:3000/api/inngest");
+
+  if (skipSync) {
+    getLogger().info(undefined, "SKIP_INNGEST_SYNC=true, skipping auto-sync");
+    return;
+  }
+
+  // INNGEST_BASE_URL is required
+  if (!inngestServerUrl) {
+    getLogger().error(
+      undefined,
+      "INNGEST_BASE_URL environment variable is not set, skipping sync",
+    );
+    return;
+  }
+
+  const gqlEndpoint = `${inngestServerUrl}/v0/gql`;
+
+  getLogger().info(
+    { safe: { gqlEndpoint, appUrl } },
+    "Syncing with Inngest Server",
+  );
+
+  const payload = {
+    operationName: "CreateApp",
+    query:
+      "mutation CreateApp($input: CreateAppInput!) {\n createApp(input: $input) {\n url\n }\n}\n",
+    variables: {
+      input: {
+        url: appUrl,
+      },
+    },
+  };
+
+  const response = await fetch(gqlEndpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(payload),
+  });
+
+  if (response.ok) {
+    getLogger().info(undefined, "Successfully synced with Inngest Server");
+  }
+}