@clubedge/create-clubedge-app 0.2.0 → 0.3.0

package/template/apps/web/src/server/cache.ts

@@ -0,0 +1,38 @@
+import "server-only";
+import {
+  createRateLimiter as createLimiter,
+  createRedisCache,
+  type RateLimiter,
+} from "@clubedge/cache";
+import { getRedisUrl } from "@/env/server";
+
+export type { RateLimiter, RateLimitResult } from "@clubedge/cache";
+
+/**
+ * Uses Redis when REDIS_URL is configured, otherwise a per-process memory limiter. The
+ * backend is chosen on first use so module-level limiters do not read env at import time.
+ */
+export function createRateLimiter(requests = 10, windowSeconds = 60): RateLimiter {
+  let limiter: RateLimiter | undefined;
+  return {
+    limit(identifier) {
+      limiter ??= createLimiter({
+        requests,
+        windowSeconds,
+        redisUrl: getRedisUrl(),
+      });
+      return limiter.limit(identifier);
+    },
+  };
+}
+
+/** Cache reads miss and writes are skipped while Redis is not configured. */
+export async function cacheGet<T>(key: string): Promise<T | null> {
+  const url = getRedisUrl();
+  return url ? createRedisCache(url).get<T>(key) : null;
+}
+
+export async function cacheSet(key: string, value: unknown, ttlSeconds: number): Promise<void> {
+  const url = getRedisUrl();
+  if (url) await createRedisCache(url).set(key, value, ttlSeconds);
+}

package/template/apps/web/src/server/db.ts

@@ -0,0 +1,16 @@
+import "server-only";
+import { createDb, type Database } from "@clubedge/db";
+import { getServerEnv } from "@/env/server";
+
+const globalForDb = globalThis as typeof globalThis & { clubedgeDb?: Database };
+
+/** Creates the connection pool on first use and reuses it across dev hot reloads. */
+export function getDb(): Database {
+  if (globalForDb.clubedgeDb) return globalForDb.clubedgeDb;
+  const env = getServerEnv();
+  globalForDb.clubedgeDb = createDb({
+    url: env.DATABASE_URL,
+    maxConnections: env.NODE_ENV === "production" ? 10 : 1,
+  });
+  return globalForDb.clubedgeDb;
+}

package/template/apps/web/src/server/storage.ts

@@ -0,0 +1,39 @@
+import "server-only";
+import type { StorageProvider } from "@clubedge/storage";
+import { createS3Storage } from "@clubedge/storage/s3";
+import { createSupabaseStorage } from "@clubedge/storage/supabase";
+import { getServerEnv } from "@/env/server";
+import { getSupabaseClient } from "./auth";
+
+export type { SignedUrlOptions, StorageProvider, UploadInput } from "@clubedge/storage";
+
+let provider: StorageProvider | undefined;
+
+function resolveProvider(): StorageProvider {
+  if (provider) return provider;
+  const env = getServerEnv();
+  provider =
+    env.STORAGE_PROVIDER === "supabase"
+      ? createSupabaseStorage({
+          bucket: env.SUPABASE_STORAGE_BUCKET || undefined,
+          getClient: getSupabaseClient,
+        })
+      : createS3Storage({
+          bucket: env.STORAGE_BUCKET || undefined,
+          region: env.STORAGE_REGION,
+          endpoint: env.STORAGE_ENDPOINT || undefined,
+          accessKeyId: env.STORAGE_ACCESS_KEY_ID || undefined,
+          secretAccessKey: env.STORAGE_SECRET_ACCESS_KEY || undefined,
+          publicUrl: env.STORAGE_PUBLIC_URL || undefined,
+        });
+  return provider;
+}
+
+/** The configured storage provider, resolved on first use so imports stay side-effect free. */
+export const storage: StorageProvider = {
+  upload: (input) => resolveProvider().upload(input),
+  download: (key) => resolveProvider().download(key),
+  delete: (key) => resolveProvider().delete(key),
+  exists: (key) => resolveProvider().exists(key),
+  getSignedUrl: (key, options) => resolveProvider().getSignedUrl(key, options),
+};

package/template/apps/web/src/server/users.ts

@@ -0,0 +1,17 @@
+import "server-only";
+import type { AuthUser } from "@clubedge/auth";
+import { upsertUserProfile } from "@clubedge/db";
+import { getDb } from "./db";
+
+/**
+ * Keeps the app-owned users row in step with the identity provider. Failures are logged
+ * rather than thrown so a database outage does not block an otherwise valid sign-in.
+ */
+export async function ensureUserProfile(user: AuthUser | null): Promise<void> {
+  if (!user?.email) return;
+  try {
+    await upsertUserProfile(getDb(), { authUserId: user.id, email: user.email });
+  } catch (error) {
+    console.error("Could not sync the user profile", error);
+  }
+}

package/template/apps/web/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    "../../packages/ui/src/**/*.ts",
+    "../../packages/ui/src/**/*.tsx"
+  ],
+  "exclude": ["node_modules"]
+}

package/template/clubedge.template.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "name": "clubedge-starter",
+  "packageManager": "pnpm",
+  "app": "apps/web",
+  "siteConfig": "apps/web/src/config/site.json",
+  "env": {
+    "example": ".env.example",
+    "target": "apps/web/.env.local"
+  },
+  "dockerImage": "clubedge-starter",
+  "exclude": ["clubedge.template.json", "scripts/template-manifest.test.ts"]
+}

package/template/docker-compose.yml

@@ -0,0 +1,8 @@
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    env_file:
+      - ./apps/web/.env.local
+    restart: unless-stopped

package/template/eslint.config.mjs

@@ -0,0 +1,63 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import tseslint from "typescript-eslint";
+
+// Architecture boundaries. Shared packages stay framework-agnostic so any app (Next.js today,
+// other frameworks later) can reuse them; apps reach providers only through src/server.
+const frameworkImports = {
+  group: ["next", "next/*", "@tanstack/*", "react", "react-dom", "react/*", "server-only"],
+  message: "Shared packages must stay framework-agnostic. Accept dependencies as arguments.",
+};
+const appImports = {
+  group: ["@/*", "**/apps/**"],
+  message: "Packages must not import application code.",
+};
+const providerImports = {
+  group: ["@supabase/*", "@aws-sdk/*", "redis", "postgres", "drizzle-orm/postgres-js"],
+  message: "Use the composition root in src/server instead of a provider SDK.",
+};
+
+export default defineConfig([
+  ...tseslint.configs.recommended,
+  {
+    files: ["packages/{auth,cache,core,db,storage}/**/*.ts"],
+    rules: {
+      "no-restricted-imports": ["error", { patterns: [frameworkImports, appImports] }],
+    },
+  },
+  {
+    files: ["packages/core/**/*.ts"],
+    rules: {
+      "no-restricted-imports": [
+        "error",
+        {
+          patterns: [
+            frameworkImports,
+            appImports,
+            {
+              group: ["@clubedge/*"],
+              message: "@clubedge/core must not depend on other packages.",
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    files: ["apps/*/src/**/*.{ts,tsx}"],
+    ignores: ["apps/*/src/server/**"],
+    rules: {
+      "no-restricted-imports": ["error", { patterns: [providerImports] }],
+    },
+  },
+  globalIgnores([
+    "**/node_modules/**",
+    "**/.next/**",
+    "**/.turbo/**",
+    ".pnpm-store/**",
+    "out/**",
+    "build/**",
+    "**/next-env.d.ts",
+    "test-results/**",
+    "playwright-report/**",
+  ]),
+]);

package/template/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "clubedge-starter-v1",
+  "version": "0.3.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "packageManager": "pnpm@10.9.0",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "dev": "turbo run dev --filter=@clubedge/web",
+    "build": "turbo run build --filter=@clubedge/web",
+    "start": "node scripts/start-standalone.mjs",
+    "lint": "eslint .",
+    "typecheck": "turbo run typecheck",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "db:generate": "pnpm --filter @clubedge/db db:generate",
+    "db:migrate": "pnpm --filter @clubedge/db db:migrate",
+    "db:push": "pnpm --filter @clubedge/db db:push",
+    "db:studio": "pnpm --filter @clubedge/db db:studio",
+    "db:check": "pnpm --filter @clubedge/db db:check",
+    "db:seed": "pnpm --filter @clubedge/db db:seed",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "docker:dev": "docker compose up --build",
+    "docker:build": "docker build -t clubedge-starter .",
+    "docker:start": "docker run --rm -p 3000:3000 --env-file apps/web/.env.local clubedge-starter"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.55.0",
+    "@types/node": "^22.18.6",
+    "eslint": "^10.12.0",
+    "prettier": "^3.6.2",
+    "turbo": "^2.5.0",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.71.1",
+    "vitest": "^5.0.3"
+  },
+  "pnpm": {
+    "overrides": {
+      "esbuild": "^0.25.0"
+    }
+  }
+}

package/template/packages/auth/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@clubedge/auth",
+  "version": "0.3.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./supabase": "./src/supabase.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clubedge/core": "workspace:*",
+    "@supabase/ssr": "^0.6.1",
+    "@supabase/supabase-js": "^2.57.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2"
+  }
+}

package/template/packages/auth/src/index.ts

@@ -0,0 +1,9 @@
+export type {
+  AuthProvider,
+  AuthUser,
+  CookieOptions,
+  CookieStore,
+  CookieToSet,
+  Credentials,
+  SignUpOutcome,
+} from "./types";

package/template/packages/auth/src/supabase.test.ts

@@ -0,0 +1,126 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { CookieStore } from "./types";
+
+const supabaseAuth = {
+  getUser: vi.fn(),
+  signInWithPassword: vi.fn(),
+  signUp: vi.fn(),
+  exchangeCodeForSession: vi.fn(),
+  signOut: vi.fn(),
+};
+let cookieMethods: { getAll(): unknown; setAll(values: unknown): void } | undefined;
+
+vi.mock("@supabase/ssr", () => ({
+  createServerClient: vi.fn(
+    (_url: string, _key: string, options: { cookies: typeof cookieMethods }) => {
+      cookieMethods = options.cookies;
+      return { auth: supabaseAuth };
+    },
+  ),
+}));
+
+const { createSupabaseAuth } = await import("./supabase");
+
+const supabaseUser = { id: "user-1", email: "ada@example.com" };
+
+function setup() {
+  const cookies: CookieStore = {
+    getAll: vi.fn(() => [{ name: "sb", value: "token" }]),
+    setAll: vi.fn(),
+  };
+  const auth = createSupabaseAuth({ url: "https://x.supabase.co", publishableKey: "pk", cookies });
+  return { auth, cookies };
+}
+
+describe("createSupabaseAuth", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("bridges the framework cookie store to Supabase", () => {
+    const { cookies } = setup();
+    expect(cookieMethods?.getAll()).toEqual([{ name: "sb", value: "token" }]);
+    const values = [{ name: "sb", value: "next", options: { path: "/" } }];
+    cookieMethods?.setAll(values);
+    expect(cookies.setAll).toHaveBeenCalledWith(values);
+  });
+
+  it("returns the verified user, or null when Supabase rejects the session", async () => {
+    const { auth } = setup();
+    supabaseAuth.getUser.mockResolvedValueOnce({ data: { user: supabaseUser }, error: null });
+    expect(await auth.getUser()).toEqual({ id: "user-1", email: "ada@example.com" });
+
+    supabaseAuth.getUser.mockResolvedValueOnce({
+      data: { user: null },
+      error: new Error("expired"),
+    });
+    expect(await auth.getUser()).toBeNull();
+  });
+
+  it("maps sign-in results without leaking provider errors", async () => {
+    const { auth } = setup();
+    const credentials = { email: "ada@example.com", password: "correct horse" };
+
+    supabaseAuth.signInWithPassword.mockResolvedValueOnce({
+      data: { user: supabaseUser },
+      error: null,
+    });
+    expect(await auth.signInWithPassword(credentials)).toEqual({
+      ok: true,
+      value: { id: "user-1", email: "ada@example.com" },
+    });
+
+    supabaseAuth.signInWithPassword.mockResolvedValueOnce({
+      data: { user: null },
+      error: new Error("Invalid login credentials"),
+    });
+    expect(await auth.signInWithPassword(credentials)).toEqual({
+      ok: false,
+      error: "invalid-credentials",
+    });
+  });
+
+  it("reports when sign-up needs email confirmation", async () => {
+    const { auth } = setup();
+    supabaseAuth.signUp.mockResolvedValueOnce({
+      data: { user: supabaseUser, session: null },
+      error: null,
+    });
+
+    const result = await auth.signUp({
+      email: "ada@example.com",
+      password: "correct horse",
+      emailRedirectTo: "https://app.example/auth/callback",
+    });
+
+    expect(supabaseAuth.signUp).toHaveBeenCalledWith({
+      email: "ada@example.com",
+      password: "correct horse",
+      options: { emailRedirectTo: "https://app.example/auth/callback" },
+    });
+    expect(result).toEqual({
+      ok: true,
+      value: { user: { id: "user-1", email: "ada@example.com" }, needsConfirmation: true },
+    });
+  });
+
+  it("maps sign-up and code exchange failures", async () => {
+    const { auth } = setup();
+    supabaseAuth.signUp.mockResolvedValueOnce({ data: {}, error: new Error("taken") });
+    expect(
+      await auth.signUp({ email: "a@b.co", password: "12345678", emailRedirectTo: "https://a.b" }),
+    ).toEqual({ ok: false, error: "signup-failed" });
+
+    supabaseAuth.exchangeCodeForSession.mockResolvedValueOnce({
+      data: { user: null },
+      error: new Error("bad code"),
+    });
+    expect(await auth.exchangeCodeForSession("code")).toEqual({ ok: false, error: "invalid-code" });
+  });
+
+  it("throws when sign-out fails", async () => {
+    const { auth } = setup();
+    supabaseAuth.signOut.mockResolvedValueOnce({ error: new Error("network") });
+    await expect(auth.signOut()).rejects.toThrow("network");
+  });
+});

package/template/packages/auth/src/supabase.ts

@@ -0,0 +1,65 @@
+import { createServerClient, type CookieMethodsServer } from "@supabase/ssr";
+import type { User } from "@supabase/supabase-js";
+import { err, ok } from "@clubedge/core";
+import type { AuthProvider, AuthUser, CookieStore } from "./types";
+
+export interface SupabaseAuthConfig {
+  url: string;
+  publishableKey: string;
+  cookies: CookieStore;
+}
+
+/** A request-scoped Supabase client. Storage adapters can reuse it for user-scoped access. */
+export function createSupabaseServerClient({ url, publishableKey, cookies }: SupabaseAuthConfig) {
+  return createServerClient(url, publishableKey, {
+    cookies: {
+      getAll: () => cookies.getAll(),
+      setAll: (values) => cookies.setAll(values),
+    } satisfies CookieMethodsServer,
+  });
+}
+
+function toAuthUser(user: User): AuthUser {
+  return { id: user.id, email: user.email ?? null };
+}
+
+export function createSupabaseAuth(config: SupabaseAuthConfig): AuthProvider {
+  const supabase = createSupabaseServerClient(config);
+
+  return {
+    async getUser() {
+      const { data, error } = await supabase.auth.getUser();
+      if (error || !data.user) return null;
+      return toAuthUser(data.user);
+    },
+    async signInWithPassword(credentials) {
+      const { data, error } = await supabase.auth.signInWithPassword(credentials);
+      if (error || !data.user) return err("invalid-credentials");
+      return ok(toAuthUser(data.user));
+    },
+    async signUp({ emailRedirectTo, ...credentials }) {
+      const { data, error } = await supabase.auth.signUp({
+        ...credentials,
+        options: { emailRedirectTo },
+      });
+      if (error) return err("signup-failed");
+      return ok({
+        user: data.user ? toAuthUser(data.user) : null,
+        needsConfirmation: !data.session,
+      });
+    },
+    async exchangeCodeForSession(code) {
+      const { data, error } = await supabase.auth.exchangeCodeForSession(code);
+      if (error) return err("invalid-code");
+      return ok(data.user ? toAuthUser(data.user) : null);
+    },
+    async refreshSession() {
+      // getUser() validates the JWT with Supabase and rotates the cookies when needed.
+      await supabase.auth.getUser();
+    },
+    async signOut() {
+      const { error } = await supabase.auth.signOut();
+      if (error) throw error;
+    },
+  };
+}

package/template/packages/auth/src/types.ts

@@ -0,0 +1,59 @@
+import type { Result } from "@clubedge/core";
+
+export interface AuthUser {
+  id: string;
+  email: string | null;
+}
+
+export interface Credentials {
+  email: string;
+  password: string;
+}
+
+export interface CookieOptions {
+  domain?: string;
+  path?: string;
+  expires?: Date;
+  maxAge?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  partitioned?: boolean;
+  priority?: "low" | "medium" | "high";
+  sameSite?: boolean | "lax" | "strict" | "none";
+}
+
+export interface CookieToSet {
+  name: string;
+  value: string;
+  options?: CookieOptions;
+}
+
+/**
+ * The only thing an auth adapter needs from the web framework. Each app bridges its own
+ * request and response cookies (Next.js `cookies()`, TanStack Start helpers, and so on).
+ */
+export interface CookieStore {
+  getAll(): Array<{ name: string; value: string }>;
+  /** May throw where cookies are read-only, such as React Server Components. */
+  setAll(cookies: CookieToSet[]): void;
+}
+
+export interface SignUpOutcome {
+  user: AuthUser | null;
+  /** True when the provider requires email confirmation before a session exists. */
+  needsConfirmation: boolean;
+}
+
+/** Application code depends on this interface, never on a provider SDK. */
+export interface AuthProvider {
+  /** Returns the user verified with the provider, not just decoded from a cookie. */
+  getUser(): Promise<AuthUser | null>;
+  signInWithPassword(credentials: Credentials): Promise<Result<AuthUser, "invalid-credentials">>;
+  signUp(
+    credentials: Credentials & { emailRedirectTo: string },
+  ): Promise<Result<SignUpOutcome, "signup-failed">>;
+  exchangeCodeForSession(code: string): Promise<Result<AuthUser | null, "invalid-code">>;
+  /** Validates the session and writes refreshed cookies; call it from request middleware. */
+  refreshSession(): Promise<void>;
+  signOut(): Promise<void>;
+}

package/template/packages/auth/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src/**/*.ts"]
+}

package/template/packages/cache/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@clubedge/cache",
+  "version": "0.3.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "redis": "^5.8.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2"
+  }
+}

package/template/packages/cache/src/index.test.ts

@@ -0,0 +1,67 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const redisClient = {
+  isReady: false,
+  on: vi.fn(),
+  connect: vi.fn(async () => {
+    redisClient.isReady = true;
+    return redisClient;
+  }),
+  eval: vi.fn(),
+};
+
+vi.mock("redis", () => ({ createClient: vi.fn(() => redisClient) }));
+
+const { createClient } = await import("redis");
+const { createRateLimiter } = await import("./index");
+
+describe("createRateLimiter", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    redisClient.isReady = false;
+  });
+
+  it("uses process memory when no Redis URL is configured", async () => {
+    const limiter = createRateLimiter({ requests: 1, windowSeconds: 60 });
+
+    expect((await limiter.limit("client")).success).toBe(true);
+    expect((await limiter.limit("client")).success).toBe(false);
+    expect(createClient).not.toHaveBeenCalled();
+  });
+
+  it("counts in Redis when a URL is configured", async () => {
+    redisClient.eval.mockResolvedValueOnce([3, 30_000]);
+    const limiter = createRateLimiter({
+      requests: 2,
+      windowSeconds: 60,
+      redisUrl: "redis://localhost:6379",
+    });
+
+    const result = await limiter.limit("client");
+
+    expect(redisClient.eval).toHaveBeenCalledWith(expect.any(String), {
+      keys: ["clubedge:rate-limit:client"],
+      arguments: ["60000"],
+    });
+    expect(result).toMatchObject({ success: false, limit: 2, remaining: 0 });
+  });
+
+  it("reuses one connection per Redis URL", async () => {
+    redisClient.eval.mockResolvedValue([1, 60_000]);
+    const url = "redis://reuse.example:6379";
+    const first = createRateLimiter({ redisUrl: url });
+    const second = createRateLimiter({ redisUrl: url });
+
+    await first.limit("a");
+    await second.limit("b");
+
+    expect(createClient).toHaveBeenCalledTimes(1);
+    expect(redisClient.connect).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects an unexpected Redis response", async () => {
+    redisClient.eval.mockResolvedValueOnce("nope");
+    const limiter = createRateLimiter({ redisUrl: "redis://bad.example:6379" });
+    await expect(limiter.limit("client")).rejects.toThrow("invalid rate limit response");
+  });
+});