@forgeailab/create-spark 0.1.1 → 0.1.2

package/packs/db-supabase/skills/supabase-patterns/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: supabase-patterns
+description: Apply Supabase client, server, and RLS patterns in Next.js apps without leaking authorization into the browser.
+---
+
+# Skill: supabase-patterns
+
+## Goal
+
+Use Supabase as the database boundary for a Next.js app while keeping data
+access explicit, RLS-backed, and easy to review. Client code may improve user
+experience, but database authorization belongs in Postgres policies.
+
+## Client Choice
+
+- Use the browser client only inside Client Components and browser utilities.
+- Use the server client inside Server Components, Server Actions, and Route Handlers.
+- Use the service role key only in server-only code.
+- Never expose the service role key through `NEXT_PUBLIC_` variables.
+- Keep client creation in `lib/supabase/client.ts` and `lib/supabase/server.ts`.
+- Import those helpers instead of constructing clients throughout the app.
+
+## RLS Baseline
+
+- Enable RLS on every user-facing table before shipping.
+- Write one policy per action: select, insert, update, delete.
+- Start restrictive, then add policies for real workflows.
+- Prefer `auth.uid()` ownership checks for user-owned rows.
+- Prefer membership tables for team or organization access.
+- Avoid policies that only check whether a user is signed in.
+- Avoid policies that mirror UI visibility without enforcing ownership.
+
+## Schema Patterns
+
+- Add `user_id uuid references auth.users(id)` for personal records.
+- Add `organization_id` plus a membership table for multi-tenant data.
+- Use `created_at` and `updated_at` consistently.
+- Add indexes for policy predicates such as `user_id` and `organization_id`.
+- Keep public profile data separate from private account data.
+- Do not join to private tables from public views unless the policy is clear.
+
+## Server Reads And Writes
+
+- Prefer server reads when data is needed for initial page render.
+- Put writes in Server Actions or Route Handlers when they affect trusted state.
+- Re-check authorization in SQL policies, even when the server action checks it.
+- Use `select()` projections instead of fetching whole rows by default.
+- Return typed view models to Client Components.
+- Avoid passing raw Supabase errors directly into user-facing copy.
+
+## Browser Reads
+
+- Browser reads are fine for realtime lists, optimistic UI, and user-owned data.
+- Keep filters aligned with RLS policies so results are predictable.
+- Treat browser filters as performance hints, not authorization.
+- Use loading, empty, and error states for every browser query.
+- Do not fetch admin data from the browser, even behind hidden UI.
+
+## Auth And Cookies
+
+- Middleware should refresh auth cookies before protected routes read sessions.
+- Use `getUser()` or claims validation on the server before trusted actions.
+- Avoid trusting session data that only came from local storage.
+- Redirect unauthenticated users at route boundaries.
+- Keep callback routes small: exchange the code, then redirect.
+
+## Service Role Use
+
+- Reserve the service role for background jobs and admin workflows.
+- Create a separate helper for service-role clients.
+- Keep service-role operations narrow and logged.
+- Never use the service role to bypass missing user policies in normal flows.
+- If a user action needs service role access, reconsider the table design.
+
+## Review Checklist
+
+- Every exposed table has RLS enabled.
+- Every policy has a named workflow it supports.
+- Server-only keys are not imported by Client Components.
+- Client queries cannot reveal another tenant's data.
+- Seeded sample data matches the policies.
+- Error states do not expose table names or policy details.

package/packs/db-supabase/tasks.yaml

@@ -0,0 +1,6 @@
+epic: Database
+tasks:
+  - id: DB-101
+    title: Configure RLS policies
+    acceptance:
+      - RLS enabled on all user-facing tables

package/packs/deploy-vercel/files/docs/deploy.md

@@ -0,0 +1,21 @@
+# Vercel Deploy Checklist
+
+Use this checklist after installing the `deploy-vercel` pack.
+
+## Project setup
+
+- Create or link the Vercel project.
+- Confirm the project framework preset is `Next.js`.
+- Set `VERCEL_PROJECT_ID` and `VERCEL_ORG_ID` locally when using Vercel CLI automation.
+
+## Environment variables
+
+- Add every required pack environment variable to Vercel.
+- Keep preview and production values separate when credentials differ.
+- Redeploy after changing environment variables.
+
+## Preview deploys
+
+- Enable pull request preview deploys.
+- Confirm preview deploys run against non-production services.
+- Keep production-only credentials out of preview environments.

package/packs/deploy-vercel/files/vercel.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "framework": "nextjs"
+}

package/packs/deploy-vercel/pack.toml

@@ -0,0 +1,30 @@
+name = "deploy-vercel"
+version = "1.0.0"
+category = "deploy"
+description = "Vercel deployment target for Next.js apps."
+provides = ["deploy-target"]
+requires = []
+conflicts = []
+requires_runtime = []
+compatible_scaffolds = ["nextjs"]
+
+[dependencies]
+runtime = []
+dev = []
+
+[env]
+required = []
+optional = ["VERCEL_PROJECT_ID", "VERCEL_ORG_ID"]
+
+[[files]]
+mode = "create"
+from = "vercel.json"
+to = "vercel.json"
+
+[[files]]
+mode = "create"
+from = "docs/deploy.md"
+to = "docs/deploy.md"
+
+[tasks]
+file = "tasks.yaml"

package/packs/deploy-vercel/tasks.yaml

@@ -0,0 +1,14 @@
+epic: Deploy
+tasks:
+  - id: DEPLOY-001
+    title: Configure environment variables in Vercel dashboard
+    status: Clarifying
+    acceptance:
+      - Required pack environment variables are present in the Vercel project.
+      - Preview and production values are documented when they differ.
+  - id: DEPLOY-002
+    title: Set up preview deploys for pull requests
+    status: Clarifying
+    acceptance:
+      - Pull requests create Vercel preview deployments.
+      - Preview deployments use non-production credentials where applicable.

package/packs/docker-compose-dev/files/.env.docker.example

@@ -0,0 +1,2 @@
+POSTGRES_PORT=5432
+REDIS_PORT=6379

package/packs/docker-compose-dev/files/compose/redis.yml

@@ -0,0 +1,17 @@
+services:
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    command: ["redis-server", "--appendonly", "yes"]
+    ports:
+      - "${REDIS_PORT:-6379}:6379"
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  redis_data:

package/packs/docker-compose-dev/files/docker-compose.include.yml

@@ -0,0 +1 @@
+  - compose/redis.yml

package/packs/docker-compose-dev/files/docker-compose.yml

@@ -0,0 +1,6 @@
+# Spark-managed Docker Compose root.
+#
+# Each infra-providing pack appends an entry below. Service definitions live
+# in compose/*.yml fragments. Run with `docker compose up -d` — Compose 2.20+
+# resolves `include:` for you.
+include:

package/packs/docker-compose-dev/pack.toml

@@ -0,0 +1,38 @@
+name = "docker-compose-dev"
+version = "1.0.0"
+category = "infra"
+description = "Local Redis for development via Docker Compose. Composes with db-postgres / sync-zero."
+provides = ["local-runtime"]
+requires = []
+conflicts = []
+requires_runtime = []
+compatible_scaffolds = []
+
+[env]
+optional = ["REDIS_PORT"]
+
+# Compose root + redis fragment. Other infra-providing packs (db-postgres,
+# sync-zero) follow the same pattern: each uses `create-or-skip` to bootstrap
+# the root file, then `append` to add their include line under a marker.
+[[files]]
+mode = "create-or-skip"
+from = "docker-compose.yml"
+to = "docker-compose.yml"
+
+[[files]]
+mode = "create"
+from = "compose/redis.yml"
+to = "compose/redis.yml"
+
+[[files]]
+mode = "append"
+from = "docker-compose.include.yml"
+to = "docker-compose.yml"
+
+[[files]]
+mode = "create"
+from = ".env.docker.example"
+to = ".env.docker.example"
+
+[tasks]
+file = "tasks.yaml"

package/packs/docker-compose-dev/tasks.yaml

@@ -0,0 +1,9 @@
+epic: Infrastructure
+
+tasks:
+  - id: INFRA-001
+    title: Run docker compose up -d and verify Postgres reachable on port 5432
+    status: Clarifying
+    acceptance:
+      - docker compose up -d starts Postgres and Redis containers.
+      - Postgres accepts connections on the configured local port.

package/packs/email-resend/files/app/api/email/test/route.ts

@@ -0,0 +1,38 @@
+import WelcomeEmail from "@/emails/welcome";
+import { sendEmail } from "@/lib/email";
+import { NextResponse, type NextRequest } from "next/server";
+
+export const runtime = "nodejs";
+
+type TestEmailRequest = {
+  to?: string;
+  name?: string;
+  productName?: string;
+};
+
+export async function POST(request: NextRequest) {
+  if (process.env.NODE_ENV !== "development") {
+    return NextResponse.json({ error: "Not found" }, { status: 404 });
+  }
+
+  if (request.headers.get("x-spark-dev-email") !== "true") {
+    return NextResponse.json({ error: "Dev email flag is required" }, { status: 403 });
+  }
+
+  const body = (await request.json().catch(() => ({}))) as TestEmailRequest;
+
+  if (!body.to) {
+    return NextResponse.json({ error: "to is required" }, { status: 400 });
+  }
+
+  const result = await sendEmail({
+    to: body.to,
+    subject: `Welcome to ${body.productName ?? "the app"}`,
+    react: WelcomeEmail({
+      name: body.name,
+      productName: body.productName,
+    }),
+  });
+
+  return NextResponse.json({ id: result.data?.id });
+}

package/packs/email-resend/files/emails/welcome.tsx

@@ -0,0 +1,66 @@
+import {
+  Body,
+  Container,
+  Head,
+  Heading,
+  Html,
+  Preview,
+  Section,
+  Text,
+} from "@react-email/components";
+
+export type WelcomeEmailProps = {
+  name?: string;
+  productName?: string;
+};
+
+export default function WelcomeEmail({
+  name = "there",
+  productName = "the app",
+}: WelcomeEmailProps) {
+  return (
+    <Html>
+      <Head />
+      <Preview>Welcome to {productName}</Preview>
+      <Body style={body}>
+        <Container style={container}>
+          <Section>
+            <Heading style={heading}>Welcome, {name}</Heading>
+            <Text style={paragraph}>
+              Your account is ready. You can now continue setting up {productName}.
+            </Text>
+            <Text style={paragraph}>
+              Keep this email as a simple delivery check while the product email
+              system is being wired up.
+            </Text>
+          </Section>
+        </Container>
+      </Body>
+    </Html>
+  );
+}
+
+const body = {
+  backgroundColor: "#f6f7f9",
+  color: "#111827",
+  fontFamily: "Arial, sans-serif",
+};
+
+const container = {
+  backgroundColor: "#ffffff",
+  margin: "40px auto",
+  padding: "32px",
+  maxWidth: "560px",
+};
+
+const heading = {
+  fontSize: "24px",
+  lineHeight: "32px",
+  margin: "0 0 16px",
+};
+
+const paragraph = {
+  fontSize: "16px",
+  lineHeight: "24px",
+  margin: "0 0 16px",
+};

package/packs/email-resend/files/lib/email.ts

@@ -0,0 +1,40 @@
+import type { ReactElement } from "react";
+import { Resend } from "resend";
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+
+  return value;
+}
+
+export const resend = new Resend(requireEnv("RESEND_API_KEY"));
+
+export type SendEmailInput = {
+  to: string | string[];
+  subject: string;
+  from?: string;
+  replyTo?: string | string[];
+  react?: ReactElement;
+  html?: string;
+  text?: string;
+};
+
+export async function sendEmail(input: SendEmailInput) {
+  if (!input.react && !input.html && !input.text) {
+    throw new Error("sendEmail requires react, html, or text content");
+  }
+
+  return resend.emails.send({
+    from: input.from ?? process.env.RESEND_FROM ?? "App <onboarding@resend.dev>",
+    to: input.to,
+    subject: input.subject,
+    replyTo: input.replyTo,
+    react: input.react,
+    html: input.html,
+    text: input.text,
+  });
+}

package/packs/email-resend/pack.toml

@@ -0,0 +1,34 @@
+name = "email-resend"
+version = "1.0.0"
+category = "email"
+description = "Resend client wrapper, React Email welcome template, and dev test route."
+provides = ["email"]
+requires = []
+conflicts = []
+requires_runtime = ["server"]
+compatible_scaffolds = ["nextjs"]
+
+[dependencies]
+runtime = ["resend", "react-email", "@react-email/components"]
+
+[env]
+required = ["RESEND_API_KEY"]
+optional = ["RESEND_FROM"]
+
+[[files]]
+mode = "create"
+from = "lib/email.ts"
+to = "lib/email.ts"
+
+[[files]]
+mode = "create"
+from = "emails/welcome.tsx"
+to = "emails/welcome.tsx"
+
+[[files]]
+mode = "create"
+from = "app/api/email/test/route.ts"
+to = "app/api/email/test/route.ts"
+
+[tasks]
+file = "tasks.yaml"

package/packs/email-resend/tasks.yaml

@@ -0,0 +1,9 @@
+epic: Email
+
+tasks:
+  - id: EMAIL-001
+    title: Verify sender domain in Resend dashboard
+    status: Clarifying
+    acceptance:
+      - Resend sender domain is verified for the production domain.
+      - RESEND_FROM uses the verified sender domain.

package/packs/example/pack.toml

@@ -0,0 +1,69 @@
+# Documentation-only example pack manifest.
+# Real installable pack names must match /^[a-z][a-z0-9-]*$/.
+name = "example"
+
+# Semver version for this pack.
+version = "1.0.0"
+
+# Catalog grouping. This example demonstrates a database capability.
+category = "db"
+
+# One-line human summary shown by future catalog commands.
+description = "Example database pack covering every manifest field."
+
+# Capabilities this pack adds to the project.
+provides = ["db"]
+
+# Capabilities that must already exist or be installed in the same plan.
+requires = []
+
+# Capabilities that cannot coexist with this pack.
+conflicts = ["db"]
+
+# Template capabilities required from the active scaffold.
+requires_runtime = ["server"]
+
+# Named scaffold restriction. Empty or missing means no named restriction.
+compatible_scaffolds = ["nextjs"]
+
+# Runtime and development npm dependencies to install with Bun.
+[dependencies]
+runtime = ["example-db@^1.0.0"]
+dev = ["example-db-cli@^1.0.0"]
+
+# Environment variables used by this pack.
+[env]
+required = ["EXAMPLE_DATABASE_URL"]
+optional = ["EXAMPLE_DATABASE_POOL_SIZE"]
+
+# Create mode writes a new file and refuses to overwrite an existing target.
+[[files]]
+mode = "create"
+from = "lib/example-db.ts"
+to = "lib/example-db.ts"
+
+# Append mode inserts a marked block once and stays idempotent on re-run.
+[[files]]
+mode = "append"
+from = "env.example"
+to = ".env.example"
+
+# merge-json mode deep-merges JSON with deterministic key ordering.
+[[files]]
+mode = "merge-json"
+from = "package.patch.json"
+to = "package.json"
+
+# Template mode renders Handlebars-style variables from spark.config.json.
+[[files]]
+mode = "template"
+from = "lib/example-client.ts.hbs"
+to = "lib/example-client.ts"
+
+# Skills copied into .claude/skills and mirrored into .codex/skills.
+[skills]
+copy = ["skills/example-db-patterns"]
+
+# Board tasks seeded into .ai/board.md during installation.
+[tasks]
+file = "tasks.yaml"

package/packs/payments-stripe/files/app/api/billing-portal/route.ts

@@ -0,0 +1,24 @@
+import { stripe } from "@/lib/stripe";
+import { NextResponse, type NextRequest } from "next/server";
+
+export const runtime = "nodejs";
+
+type PortalRequest = {
+  customerId?: string;
+  returnUrl?: string;
+};
+
+export async function POST(request: NextRequest) {
+  const body = (await request.json().catch(() => ({}))) as PortalRequest;
+
+  if (!body.customerId) {
+    return NextResponse.json({ error: "customerId is required" }, { status: 400 });
+  }
+
+  const session = await stripe.billingPortal.sessions.create({
+    customer: body.customerId,
+    return_url: body.returnUrl ?? `${request.nextUrl.origin}/billing`,
+  });
+
+  return NextResponse.redirect(session.url, 303);
+}

package/packs/payments-stripe/files/app/api/checkout/route.ts

@@ -0,0 +1,58 @@
+import { stripe } from "@/lib/stripe";
+import { NextResponse, type NextRequest } from "next/server";
+
+export const runtime = "nodejs";
+
+type CheckoutRequest = {
+  priceId?: string;
+  customerId?: string;
+  customerEmail?: string;
+  successUrl?: string;
+  cancelUrl?: string;
+  metadata?: Record<string, string>;
+};
+
+function isMetadata(value: unknown): value is Record<string, string> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.values(value).every((entry) => typeof entry === "string")
+  );
+}
+
+export async function POST(request: NextRequest) {
+  const body = (await request.json().catch(() => ({}))) as CheckoutRequest;
+
+  if (!body.priceId) {
+    return NextResponse.json({ error: "priceId is required" }, { status: 400 });
+  }
+
+  if (!body.customerId && !body.customerEmail) {
+    return NextResponse.json(
+      { error: "customerId or customerEmail is required" },
+      { status: 400 },
+    );
+  }
+
+  const origin = request.nextUrl.origin;
+  const metadata = isMetadata(body.metadata) ? body.metadata : undefined;
+
+  const session = await stripe.checkout.sessions.create({
+    mode: "subscription",
+    customer: body.customerId,
+    customer_email: body.customerId ? undefined : body.customerEmail,
+    line_items: [
+      {
+        price: body.priceId,
+        quantity: 1,
+      },
+    ],
+    allow_promotion_codes: true,
+    success_url: body.successUrl ?? `${origin}/billing/success?session_id={CHECKOUT_SESSION_ID}`,
+    cancel_url: body.cancelUrl ?? `${origin}/billing`,
+    metadata,
+  });
+
+  return NextResponse.json({ id: session.id, url: session.url });
+}

package/packs/payments-stripe/files/app/api/webhooks/stripe/route.ts

@@ -0,0 +1,84 @@
+import { stripe } from "@/lib/stripe";
+import { headers } from "next/headers";
+import { NextResponse, type NextRequest } from "next/server";
+import type Stripe from "stripe";
+
+export const runtime = "nodejs";
+
+async function hasProcessedStripeEvent(_eventId: string): Promise<boolean> {
+  // Replace with a durable lookup in the app database before going live.
+  return false;
+}
+
+async function markStripeEventProcessed(_eventId: string): Promise<void> {
+  // Replace with an atomic insert keyed by Stripe event id before going live.
+}
+
+async function handleCheckoutCompleted(session: Stripe.Checkout.Session): Promise<void> {
+  console.log("Stripe checkout completed", {
+    customer: session.customer,
+    subscription: session.subscription,
+  });
+}
+
+async function handleSubscriptionUpdated(subscription: Stripe.Subscription): Promise<void> {
+  console.log("Stripe subscription updated", {
+    customer: subscription.customer,
+    status: subscription.status,
+  });
+}
+
+async function handleSubscriptionDeleted(subscription: Stripe.Subscription): Promise<void> {
+  console.log("Stripe subscription deleted", {
+    customer: subscription.customer,
+    status: subscription.status,
+  });
+}
+
+async function dispatchStripeEvent(event: Stripe.Event): Promise<void> {
+  switch (event.type) {
+    case "checkout.session.completed":
+      await handleCheckoutCompleted(event.data.object as Stripe.Checkout.Session);
+      break;
+    case "customer.subscription.created":
+    case "customer.subscription.updated":
+      await handleSubscriptionUpdated(event.data.object as Stripe.Subscription);
+      break;
+    case "customer.subscription.deleted":
+      await handleSubscriptionDeleted(event.data.object as Stripe.Subscription);
+      break;
+    default:
+      console.log(`Unhandled Stripe event: ${event.type}`);
+  }
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.text();
+  const signature = (await headers()).get("stripe-signature");
+
+  if (!signature) {
+    return NextResponse.json({ error: "Missing stripe-signature header" }, { status: 400 });
+  }
+
+  let event: Stripe.Event;
+
+  try {
+    event = stripe.webhooks.constructEvent(
+      body,
+      signature,
+      process.env.STRIPE_WEBHOOK_SECRET ?? "",
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid Stripe signature";
+    return NextResponse.json({ error: message }, { status: 400 });
+  }
+
+  if (await hasProcessedStripeEvent(event.id)) {
+    return NextResponse.json({ received: true, duplicate: true });
+  }
+
+  await dispatchStripeEvent(event);
+  await markStripeEventProcessed(event.id);
+
+  return NextResponse.json({ received: true });
+}