@percepta/create 3.0.0

package/templates/webapp/scripts/setup-readonly-user.ts

@@ -0,0 +1,193 @@
+#!/usr/bin/env tsx
+
+import {
+  GetSecretValueCommand,
+  SecretsManagerClient,
+} from "@aws-sdk/client-secrets-manager";
+import { loadEnvConfig } from "@next/env";
+import { Pool } from "pg";
+import { getEnvConfig } from "../src/config/getEnvConfig";
+
+interface ReadonlyCredentials {
+  username: string;
+  password: string;
+  host: string;
+  port: number;
+  database: string;
+  engine: string;
+}
+
+async function getReadonlyCredentials(): Promise<ReadonlyCredentials> {
+  const client = new SecretsManagerClient({});
+
+  // Get the secret name from environment
+  // Example format: rds-{app}-readonly-{name}-{environment}-*
+  const { READONLY_SECRET_NAME: secretName } = getEnvConfig();
+  if (secretName == null) {
+    throw new Error("READONLY_SECRET_NAME environment variable not set");
+  }
+
+  const command = new GetSecretValueCommand({ SecretId: secretName });
+  const response = await client.send(command);
+
+  if (!response.SecretString) {
+    throw new Error("Secret value is empty");
+  }
+
+  return JSON.parse(response.SecretString) as ReadonlyCredentials;
+}
+
+async function setupReadonlyUser(): Promise<number> {
+  console.log("🔐 Fetching readonly user credentials from Secrets Manager...");
+
+  let credentials: ReadonlyCredentials;
+  try {
+    credentials = await getReadonlyCredentials();
+    console.log(`✅ Retrieved credentials for user: ${credentials.username}`);
+  } catch (error) {
+    console.error(
+      "❌ Failed to retrieve credentials from Secrets Manager:",
+      error,
+    );
+    return 1;
+  }
+
+  // Connect as master user
+  const {
+    DATABASE_HOST: host,
+    DATABASE_PORT: port,
+    DATABASE_USERNAME: user,
+    DATABASE_PASSWORD: password,
+    DATABASE_NAME: database,
+    DATABASE_USE_SSL: useSSL,
+  } = getEnvConfig();
+  const masterPool = new Pool({
+    host,
+    port,
+    user,
+    password,
+    database,
+    ssl: useSSL ? { rejectUnauthorized: false } : false,
+  });
+
+  let client;
+  try {
+    client = await masterPool.connect();
+    console.log("✅ Connected to database as master user");
+
+    // Check if readonly user already exists
+    const userExistsResult = await client.query(
+      "SELECT 1 FROM pg_roles WHERE rolname = $1",
+      [credentials.username],
+    );
+
+    let userCreated = false;
+    if (userExistsResult.rows.length === 0) {
+      // Create the readonly user
+      console.log(`📝 Creating user: ${credentials.username}`);
+      await client.query(
+        `
+        CREATE USER ${credentials.username} WITH LOGIN PASSWORD $1
+      `,
+        [credentials.password],
+      );
+      userCreated = true;
+      console.log(`✅ User ${credentials.username} created`);
+    } else {
+      // Update password to ensure it matches Secrets Manager
+      console.log(
+        `📝 Updating password for existing user: ${credentials.username}`,
+      );
+      await client.query(
+        `
+        ALTER USER ${credentials.username} WITH PASSWORD $1
+      `,
+        [credentials.password],
+      );
+      console.log(`✅ Password updated for ${credentials.username}`);
+    }
+
+    // Grant CONNECT privilege on database
+    await client.query(`
+      GRANT CONNECT ON DATABASE ${database} TO ${credentials.username}
+    `);
+    console.log("✅ Granted CONNECT on database");
+
+    // Get all schemas (excluding system schemas)
+    const schemasResult = await client.query<{ schema_name: string }>(`
+      SELECT schema_name 
+      FROM information_schema.schemata 
+      WHERE schema_name NOT IN ('pg_catalog', 'information_schema', 'pg_toast')
+    `);
+
+    for (const row of schemasResult.rows) {
+      const schemaName = row.schema_name;
+      console.log(`📝 Configuring access for schema: ${schemaName}`);
+
+      // Grant USAGE on schema
+      await client.query(`
+        GRANT USAGE ON SCHEMA ${schemaName} TO ${credentials.username}
+      `);
+
+      // Grant SELECT on all existing tables in schema
+      await client.query(`
+        GRANT SELECT ON ALL TABLES IN SCHEMA ${schemaName} TO ${credentials.username}
+      `);
+
+      // Set default privileges for future tables in schema
+      // Grant on tables created by the master user
+      await client.query(`
+        ALTER DEFAULT PRIVILEGES IN SCHEMA ${schemaName}
+        GRANT SELECT ON TABLES TO ${credentials.username}
+      `);
+
+      console.log(`✅ Configured access for schema: ${schemaName}`);
+    }
+
+    // Test the readonly user connection
+    console.log("🧪 Testing readonly user connection...");
+    const readonlyPool = new Pool({
+      host,
+      port,
+      user: credentials.username,
+      password: credentials.password,
+      database,
+      ssl: useSSL ? { rejectUnauthorized: false } : false,
+    });
+
+    try {
+      const readonlyClient = await readonlyPool.connect();
+      await readonlyClient.query("SELECT 1");
+      readonlyClient.release();
+      console.log("✅ Readonly user connection test successful");
+    } catch (error) {
+      console.error("⚠️  Readonly user connection test failed:", error);
+      return 1;
+    } finally {
+      await readonlyPool.end();
+    }
+
+    console.log("✅ Readonly user setup completed successfully");
+
+    // Return exit code 2 if user already existed (idempotent case)
+    // Return exit code 0 if user was created
+    return userCreated ? 0 : 2;
+  } catch (error) {
+    console.error("❌ Error setting up readonly user:", error);
+    return 1;
+  } finally {
+    if (client) {
+      client.release();
+    }
+    await masterPool.end();
+  }
+}
+
+async function main(): Promise<void> {
+  loadEnvConfig(process.cwd());
+
+  const exitCode = await setupReadonlyUser();
+  process.exit(exitCode);
+}
+
+void main();

package/templates/webapp/scripts/start.sh

@@ -0,0 +1,52 @@
+# Check if database connection variables are set
+if [ -z "$DATABASE_HOST" ] || [ -z "$DATABASE_USERNAME" ] || [ -z "$DATABASE_NAME" ]; then
+    echo "⚠️  Database connection not configured. Skipping migration."
+    echo "Required environment variables: DATABASE_HOST, DATABASE_USERNAME, DATABASE_NAME"
+    echo "❌ Error: Missing required database environment variables."
+    exit 1
+else
+    echo "Database configuration found:"
+    echo "  HOST: $DATABASE_HOST"
+    echo "  USER: $DATABASE_USERNAME"
+    echo "  DATABASE: $DATABASE_NAME"
+    echo "  SSL: ${DATABASE_USE_SSL:-false}"
+fi
+
+# Run database migrations only if database is configured
+echo "Running database migrations..."
+if pnpm db:setup-and-migrate; then
+    echo "✅ Database migrations completed successfully"
+else
+    echo "❌ Database migration failed. App will start anyway."
+    echo "Check your database configuration and connectivity."
+fi
+
+# Setup readonly database user for EDW (only if READONLY_SECRET_NAME is set)
+if [ -n "$READONLY_SECRET_NAME" ]; then
+    echo "Setting up readonly database user for EDW..."
+    if pnpm db:setup-readonly; then
+        echo "✅ Readonly user setup completed"
+    else
+        EXIT_CODE=$?
+        if [ $EXIT_CODE -eq 2 ]; then
+            echo "ℹ️  Readonly user already exists and is configured correctly"
+        else
+            echo "⚠️  Failed to setup readonly user. Check logs for details."
+        fi
+    fi
+else
+    echo "ℹ️  READONLY_SECRET_NAME not set, skipping readonly user setup"
+fi
+
+if [ -n "$ADMIN_USERNAME" ] && [ -n "$ADMIN_PASSWORD" ] && [ -n "$ADMIN_NAME" ]; then
+    echo "Creating admin user..."
+    if pnpm exec tsx scripts/create-user.ts "$ADMIN_USERNAME" "$ADMIN_PASSWORD" --name "$ADMIN_NAME"; then
+        echo "✅ Admin user created (or already exists)."
+    else
+        echo "⚠️  Failed to create admin user."
+    fi
+fi
+
+# Start the Next.js application
+echo "Starting Next.js server on port ${PORT:-3000}..."
+exec pnpm start

package/templates/webapp/src/app/(app)/layout.tsx

@@ -0,0 +1,21 @@
+import React from "react";
+import Header from "../../components/Header";
+
+export default function AppLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <>
+      <Header />
+      <main>
+        <div className="py-8">
+          <div className="mx-auto max-w-6xl">
+            <div className="rounded-lg bg-white p-8">{children}</div>
+          </div>
+        </div>
+      </main>
+    </>
+  );
+}

package/templates/webapp/src/app/(app)/page.tsx

@@ -0,0 +1,30 @@
+import type { Metadata } from "next";
+import { headers } from "next/headers";
+import { redirect } from "next/navigation";
+import { auth } from "../../lib/auth";
+
+export const metadata: Metadata = {
+  title: "__APP_TITLE__",
+  description: "__APP_TITLE__",
+};
+
+export default async function HomePage() {
+  const session = await auth.api.getSession({
+    headers: await headers(),
+  });
+
+  if (session?.user == null) {
+    redirect("/auth/signin");
+  }
+
+  return (
+    <div className="space-y-8">
+      <h1 className="text-center text-2xl font-bold text-foreground">
+        Welcome to __APP_TITLE__
+      </h1>
+      <p className="mx-auto max-w-xl text-center text-sm text-muted-foreground">
+        You are logged in. Start building your application!
+      </p>
+    </div>
+  );
+}

package/templates/webapp/src/app/(auth)/auth/signin/CredentialsSignInForm.tsx

@@ -0,0 +1,103 @@
+"use client";
+
+import { zodResolver } from "@hookform/resolvers/zod";
+import { Button, Input } from "@percepta/design";
+import { useRouter, useSearchParams } from "next/navigation";
+import React, { useCallback } from "react";
+import { Controller, useForm } from "react-hook-form";
+import { toast } from "sonner";
+import z from "zod";
+import { FormItem } from "../../../../components/form/FormItem";
+import { authClient } from "../../../../lib/auth-client";
+import { IS_DEV } from "../../../../config/isDev";
+
+const CREDENTIALS_SCHEMA = z.object({
+  email: z.string().min(1, "Email is required"),
+  password: z.string().min(1, "Password is required"),
+});
+
+type Credentials = z.infer<typeof CREDENTIALS_SCHEMA>;
+
+// Defaults are empty in production so deployed instances don't suggest seeded
+// credentials. In dev we prefill with the seeded user from `pnpm db:seed` so a
+// fresh scaffold is one click away from authed.
+const DEFAULTS: Credentials = IS_DEV
+  ? { email: "admin@example.com", password: "password" }
+  : { email: "", password: "" };
+
+export function CredentialsSignInForm() {
+  const router = useRouter();
+  const searchParams = useSearchParams();
+
+  const {
+    control,
+    formState: { isSubmitting },
+    handleSubmit,
+  } = useForm<Credentials>({
+    resolver: zodResolver(CREDENTIALS_SCHEMA),
+    defaultValues: DEFAULTS,
+  });
+
+  const callbackUrl = searchParams.get("callbackUrl") ?? "/";
+
+  const submit = useCallback(
+    async ({ email, password }: Credentials): Promise<void> => {
+      const { error } = await authClient.signIn.email({
+        email,
+        password,
+        callbackURL: callbackUrl,
+      });
+
+      if (error != null) {
+        toast.error(
+          error.message ??
+            "Invalid email or password. Please check your credentials and try again.",
+        );
+        return;
+      }
+
+      router.push(callbackUrl);
+      router.refresh();
+    },
+    [callbackUrl, router],
+  );
+
+  return (
+    <div className="space-y-8">
+      <div className="text-center">
+        <h1 className="text-2xl font-bold text-foreground">Sign In</h1>
+      </div>
+      <form className="space-y-6" onSubmit={handleSubmit(submit)}>
+        <div className="space-y-4">
+          <Controller
+            control={control}
+            name="email"
+            render={({ field, fieldState }) => (
+              <FormItem label="Email" fieldState={fieldState}>
+                <Input {...field} type="email" autoComplete="email" />
+              </FormItem>
+            )}
+          />
+          <Controller
+            control={control}
+            name="password"
+            render={({ field, fieldState }) => (
+              <FormItem label="Password" fieldState={fieldState}>
+                <Input
+                  {...field}
+                  type="password"
+                  autoComplete="current-password"
+                />
+              </FormItem>
+            )}
+          />
+        </div>
+        <div className="flex justify-end">
+          <Button type="submit" loading={isSubmitting}>
+            Sign In
+          </Button>
+        </div>
+      </form>
+    </div>
+  );
+}

package/templates/webapp/src/app/(auth)/auth/signin/page.tsx

@@ -0,0 +1,30 @@
+import type { Metadata } from "next";
+import { headers } from "next/headers";
+import { redirect } from "next/navigation";
+import { Suspense } from "react";
+import { auth } from "../../../../lib/auth";
+import { CredentialsSignInForm } from "./CredentialsSignInForm";
+
+export const metadata: Metadata = {
+  title: "Sign In — __APP_TITLE__",
+};
+
+export default async function SignInPage() {
+  const session = await auth.api.getSession({
+    headers: await headers(),
+  });
+
+  if (session?.user != null) {
+    redirect("/");
+  }
+
+  return (
+    <Suspense
+      fallback={
+        <p className="text-center text-sm text-muted-foreground">Loading…</p>
+      }
+    >
+      <CredentialsSignInForm />
+    </Suspense>
+  );
+}

package/templates/webapp/src/app/(auth)/layout.tsx

@@ -0,0 +1,15 @@
+import React from "react";
+
+export default function AuthLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center bg-muted/40 p-4">
+      <div className="w-full max-w-md rounded-lg border border-border bg-card p-8 shadow-sm">
+        {children}
+      </div>
+    </div>
+  );
+}

package/templates/webapp/src/app/api/auth/[...all]/route.ts

@@ -0,0 +1,4 @@
+import { toNextJsHandler } from "better-auth/next-js";
+import { auth } from "../../../../lib/auth";
+
+export const { GET, POST } = toNextJsHandler(auth);

package/templates/webapp/src/app/api/healthz/route.ts

@@ -0,0 +1,10 @@
+import { checkStartup } from "../../../startup-checks";
+
+export async function GET() {
+  const isHealthy = await checkStartup();
+  if (!isHealthy) {
+    return new Response(null, { status: 503 });
+  }
+
+  return new Response(null, { status: 200 });
+}

package/templates/webapp/src/app/api/inngest/route.ts

@@ -0,0 +1,31 @@
+import { serve } from "inngest/next";
+import { compact } from "lodash-es";
+import { type InngestFunctionCollection } from "../../../services/inngest/InngestFunctionCollection";
+import { InngestService } from "../../../services/inngest/InngestService";
+
+export const dynamic = "force-dynamic";
+
+const functionCollections: InngestFunctionCollection[] = compact([]);
+
+// InngestService.create() reads env vars and throws if INNGEST_BASE_URL is
+// unset. Defer initialization until request time so `next build` can compile
+// this route without those vars present.
+type Handlers = ReturnType<typeof serve>;
+
+let cachedHandlers: Handlers | undefined;
+
+function getHandlers(): Handlers {
+  if (cachedHandlers == null) {
+    const inngestService = InngestService.create();
+    cachedHandlers = serve({
+      client: inngestService.client,
+      functions: functionCollections.flatMap(({ functions }) => functions),
+      signingKey: inngestService.signingKey,
+    });
+  }
+  return cachedHandlers;
+}
+
+export const GET: Handlers["GET"] = (...args) => getHandlers().GET(...args);
+export const POST: Handlers["POST"] = (...args) => getHandlers().POST(...args);
+export const PUT: Handlers["PUT"] = (...args) => getHandlers().PUT(...args);

package/templates/webapp/src/app/api/readyz/route.ts

@@ -0,0 +1,31 @@
+import { getLogger } from "../../../services/logger/AppLogger";
+import { withAppRouterRequestContext } from "../../../services/logger/withRequestContext";
+import { checkStartup } from "../../../startup-checks";
+import { syncInngestApp } from "../../../utils/syncInngestApp";
+
+let hasSynced = false;
+
+const handler = withAppRouterRequestContext(async (): Promise<Response> => {
+  const isHealthy = await checkStartup();
+  if (!isHealthy) {
+    return new Response(null, { status: 503 });
+  }
+
+  if (!hasSynced) {
+    try {
+      await syncInngestApp();
+      hasSynced = true;
+    } catch (error) {
+      getLogger().warn(
+        undefined,
+        "Failed to sync with Inngest Server during readiness",
+        error,
+      );
+      return new Response(null, { status: 503 });
+    }
+  }
+
+  return new Response(null, { status: 200 });
+});
+
+export { handler as GET };

package/templates/webapp/src/app/api/trpc/[trpc]/route.ts

@@ -0,0 +1,21 @@
+import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
+import { appRouter } from "../../../../server/api/root";
+import { createContext } from "../../../../server/trpc";
+import { getLogger } from "../../../../services/logger/AppLogger";
+import { withAppRouterRequestContext } from "../../../../services/logger/withRequestContext";
+
+const handler = withAppRouterRequestContext(
+  (req: Request): Promise<Response> => {
+    return fetchRequestHandler({
+      endpoint: "/api/trpc",
+      req,
+      router: appRouter,
+      createContext,
+      onError: ({ error }) => {
+        getLogger().error(undefined, "tRPC error.", error);
+      },
+    });
+  },
+);
+
+export { handler as GET, handler as POST };

package/templates/webapp/src/app/global-error.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+export default function GlobalError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  try {
+    const { faro } = require("@grafana/faro-web-sdk");
+    faro.api?.pushError(error);
+  } catch {
+    // Faro may not be initialized yet — don't let reporting break the error page
+  }
+
+  return (
+    <html lang="en">
+      <body suppressHydrationWarning>
+        <div style={{ padding: "2rem", textAlign: "center" }}>
+          <h1>Something went wrong</h1>
+          <button onClick={() => reset()}>Try again</button>
+        </div>
+      </body>
+    </html>
+  );
+}

package/templates/webapp/src/app/layout.tsx

@@ -0,0 +1,18 @@
+import "@percepta/design/styles";
+import "../styles/globals.css";
+import React from "react";
+import { Providers } from "../components/Providers";
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body className="antialiased" suppressHydrationWarning={true}>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}

package/templates/webapp/src/components/FaroProvider.tsx

@@ -0,0 +1,37 @@
+"use client";
+
+import { FaroProvider as BaseFaroProvider } from "@percepta/next-utils/faro";
+import { Alert, AlertTitle, AlertDescription, Button } from "@percepta/design";
+import { type ReactNode } from "react";
+
+// Import to trigger Faro initialization at module scope (earliest possible)
+import "../services/observability/initFaro";
+
+export function AppFaroProvider({ children }: { children: ReactNode }) {
+  return (
+    <BaseFaroProvider fallback={<ErrorFallback />}>
+      {children}
+    </BaseFaroProvider>
+  );
+}
+
+function ErrorFallback() {
+  return (
+    <div className="flex min-h-screen items-center justify-center p-4">
+      <Alert variant="destructive" className="max-w-md">
+        <AlertTitle>Something went wrong</AlertTitle>
+        <AlertDescription>
+          An unexpected error occurred. Please refresh the page and try again.
+        </AlertDescription>
+        <Button
+          variant="outline"
+          size="sm"
+          className="mt-4"
+          onClick={() => window.location.reload()}
+        >
+          Refresh page
+        </Button>
+      </Alert>
+    </div>
+  );
+}