@forgeailab/create-spark 0.1.1 → 0.1.2

package/packs/payments-stripe/files/lib/stripe.ts

@@ -0,0 +1,60 @@
+import {
+  createStripeClient,
+  createCheckoutSession as createStripeCheckoutSession,
+  createBillingPortalSession as createStripeBillingPortalSession,
+  verifyWebhookSignature as verifyStripeWebhookSignature,
+} from '@forgeailab/spark-stripe-helpers';
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}
+
+export const stripe = createStripeClient(requireEnv('STRIPE_SECRET_KEY'), {
+  appInfo: { name: 'spark payments-stripe' },
+});
+
+export function getStripePublishableKey(): string {
+  return requireEnv('NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY');
+}
+
+export type CheckoutInput = {
+  origin: string;
+  priceId: string;
+  customerEmail?: string;
+  customerId?: string;
+  successUrl?: string;
+  cancelUrl?: string;
+  metadata?: Record<string, string>;
+};
+
+export async function createCheckoutSession(input: CheckoutInput) {
+  return createStripeCheckoutSession(stripe, {
+    priceId: input.priceId,
+    customerId: input.customerId,
+    customerEmail: input.customerEmail,
+    successUrl:
+      input.successUrl ?? `${input.origin}/billing/success?session_id={CHECKOUT_SESSION_ID}`,
+    cancelUrl: input.cancelUrl ?? `${input.origin}/billing`,
+    metadata: input.metadata,
+  });
+}
+
+export type PortalInput = { customerId: string; returnUrl: string };
+
+export async function createBillingPortalSession(input: PortalInput) {
+  return createStripeBillingPortalSession(stripe, input);
+}
+
+export type WebhookInput = { payload: string; signature: string; secret?: string };
+
+export function verifyWebhookSignature(input: WebhookInput) {
+  return verifyStripeWebhookSignature(stripe, {
+    payload: input.payload,
+    signatureHeader: input.signature,
+    secret: input.secret ?? requireEnv('STRIPE_WEBHOOK_SECRET'),
+  });
+}

package/packs/payments-stripe/pack.toml

@@ -0,0 +1,49 @@
+name = "payments-stripe"
+version = "1.0.0"
+category = "payments"
+description = "Stripe Checkout, customer portal, and webhook handlers for subscriptions."
+provides = ["payments"]
+requires = ["db", "auth"]
+conflicts = ["payments"]
+requires_runtime = ["server"]
+compatible_scaffolds = ["nextjs"]
+
+[runtime_package]
+package = "@forgeailab/spark-stripe-helpers"
+version = "^0.1"
+
+[dependencies]
+runtime = ["@stripe/stripe-js"]
+
+[env]
+required = [
+  "STRIPE_SECRET_KEY",
+  "STRIPE_WEBHOOK_SECRET",
+  "NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY",
+]
+
+[[files]]
+mode = "create"
+from = "lib/stripe.ts"
+to = "lib/stripe.ts"
+
+[[files]]
+mode = "create"
+from = "app/api/checkout/route.ts"
+to = "app/api/checkout/route.ts"
+
+[[files]]
+mode = "create"
+from = "app/api/webhooks/stripe/route.ts"
+to = "app/api/webhooks/stripe/route.ts"
+
+[[files]]
+mode = "create"
+from = "app/api/billing-portal/route.ts"
+to = "app/api/billing-portal/route.ts"
+
+[skills]
+copy = ["skills/stripe-patterns"]
+
+[tasks]
+file = "tasks.yaml"

package/packs/payments-stripe/skills/stripe-patterns/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: stripe-patterns
+description: Build Stripe subscription flows with Checkout, Billing Portal, and signed webhooks. Use when implementing or reviewing billing behavior after the payments-stripe pack is installed.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+---
+
+# Skill: stripe-patterns
+
+## Goal
+
+Ship a small, reliable subscription billing slice: Checkout creates the initial
+subscription, Billing Portal handles plan and payment-method changes, and
+webhooks update the app database as the billing source of truth changes.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5 for pricing and lifecycle decisions. Sonnet 4.6 or GPT-5
+family executor for routine route and UI wiring.
+
+## Inputs
+
+Read these before changing billing code:
+
+- `.ai/product-spec.md` for the monetization promise and non-goals
+- `.ai/architecture.md` for the chosen auth and database providers
+- `.ai/board.md` for the exact billing task and acceptance criteria
+- `lib/stripe.ts` for shared Stripe client setup
+- `app/api/webhooks/stripe/route.ts` for event handling
+
+If the spec does not say what users buy or what paid access unlocks, stop and
+ask. Do not invent pricing rules inside implementation.
+
+## Subscription Model
+
+- Treat Stripe as the source of truth for payment state.
+- Treat the app database as a query cache for product access decisions.
+- Store Stripe customer id on the app user or organization record.
+- Store subscription id, price id, status, current period dates, and cancel flag.
+- Grant access from database state, not from client-side checkout responses.
+- Prefer Stripe Checkout for first purchase and Billing Portal for later changes.
+- Keep product and price creation in the Stripe dashboard unless the board says
+  the product catalog must be managed in-app.
+
+## Webhook Rules
+
+- Verify signatures with `STRIPE_WEBHOOK_SECRET` and the raw request body.
+- Process webhooks idempotently by storing Stripe event ids in the database.
+- Use an atomic insert or unique index for event id de-duplication.
+- Acknowledge duplicate events with success, not an error.
+- Update access on `checkout.session.completed`,
+  `customer.subscription.updated`, and `customer.subscription.deleted`.
+- Add invoice event handling only when the product spec needs grace periods,
+  failed payment messaging, or invoice history.
+
+## Checkout Rules
+
+- Never accept price amounts from the browser.
+- Accept only Stripe price ids that the server has allowlisted or loaded from
+  trusted configuration.
+- Create or reuse exactly one Stripe customer for each billable account.
+- Send stable metadata, such as user id or organization id, on Checkout Sessions.
+- Redirect only to same-origin success and cancel URLs unless explicitly needed.
+
+## Customer Portal Rules
+
+- Require an authenticated user before creating a portal session.
+- Resolve the Stripe customer id from the database, not from request body trust.
+- Use the portal for payment method changes, cancellations, and plan changes
+  unless custom billing UX is required by the board.
+
+## Common Pitfalls
+
+- Do not mark a user paid immediately after `checkout.sessions.create`.
+- Do not parse JSON before webhook signature verification.
+- Do not skip webhook idempotency because Stripe retries events.
+- Do not trust `customerEmail` as identity; it is only a checkout convenience.
+- Do not create a new customer on every checkout attempt.
+- Do not build custom plan management before Billing Portal is exhausted.
+
+## Verification
+
+Use Stripe CLI forwarding for local webhook tests:
+
+```bash
+stripe listen --forward-to localhost:3000/api/webhooks/stripe
+```
+
+Then create a Checkout Session, complete the test payment, and confirm the app
+database changes only after the signed webhook is processed.

package/packs/payments-stripe/tasks.yaml

@@ -0,0 +1,16 @@
+epic: Payments
+
+tasks:
+  - id: PAY-001
+    title: Configure products + prices in Stripe dashboard
+    status: Clarifying
+    acceptance:
+      - Stripe dashboard has at least one active subscription product and recurring price.
+      - The selected price ID is available to the checkout flow.
+
+  - id: PAY-002
+    title: Test webhook signing locally with stripe listen
+    status: Clarifying
+    acceptance:
+      - Local webhook forwarding reaches app/api/webhooks/stripe.
+      - A signed test event is accepted and unsigned payloads are rejected.

package/packs/sync-zero/files/components/ZeroProvider.tsx

@@ -0,0 +1,3 @@
+'use client';
+
+export { ZeroProvider } from '@forgeailab/spark-sync-zero';

package/packs/sync-zero/files/compose/zero-cache.yml

@@ -0,0 +1,26 @@
+services:
+  zero-cache:
+    image: rocicorp/zero:latest
+    restart: unless-stopped
+    environment:
+      ZERO_UPSTREAM_DB: ${ZERO_UPSTREAM_DB}
+      ZERO_CVR_DB: ${ZERO_CVR_DB:-${ZERO_UPSTREAM_DB}_cvr}
+      ZERO_CHANGE_DB: ${ZERO_CHANGE_DB:-${ZERO_UPSTREAM_DB}_change}
+      ZERO_REPLICA_FILE: /zero/replica.db
+      ZERO_AUTH_SECRET: ${ZERO_AUTH_SECRET}
+      ZERO_ADMIN_PASSWORD: ${ZERO_ADMIN_PASSWORD:-change-me}
+      ZERO_PUSH_URL: ${ZERO_PUSH_URL:-http://host.docker.internal:3000/api/zero/mutate}
+      ZERO_LOG_LEVEL: ${ZERO_LOG_LEVEL:-info}
+      ZERO_NUM_SYNC_WORKERS: "1"
+    ports:
+      - "${ZERO_PORT:-4848}:4848"
+    volumes:
+      - zero_data:/zero
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+volumes:
+  zero_data:

package/packs/sync-zero/files/docker-compose.include.yml

@@ -0,0 +1 @@
+  - compose/zero-cache.yml

package/packs/sync-zero/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/sync-zero/files/lib/zero/client.ts

@@ -0,0 +1,18 @@
+'use client';
+
+import { createZeroClient as createSparkZeroClient } from '@forgeailab/spark-sync-zero';
+import type { ZeroOptions } from '@forgeailab/spark-sync-zero';
+import { schema } from './schema';
+
+const DEFAULT_ZERO_URL = 'http://localhost:4848';
+
+export function createZeroOptions(): ZeroOptions {
+  return {
+    cacheURL: process.env.NEXT_PUBLIC_ZERO_URL ?? DEFAULT_ZERO_URL,
+    schema,
+  };
+}
+
+export function createZeroClient(options: ZeroOptions = createZeroOptions()) {
+  return createSparkZeroClient(options);
+}

package/packs/sync-zero/files/lib/zero/schema.ts

@@ -0,0 +1,17 @@
+import { defineZeroSchema, number, string, table } from '@forgeailab/spark-sync-zero';
+
+// Example schema. Replace with your app's tables.
+const users = table('user')
+  .columns({
+    id: string(),
+    name: string(),
+    email: string(),
+    createdAt: number(),
+  })
+  .primaryKey('id');
+
+export const { schema, zql } = defineZeroSchema({
+  tables: [users],
+});
+
+export type Schema = typeof schema;

package/packs/sync-zero/files/zero.config.ts

@@ -0,0 +1,26 @@
+type ZeroCacheConfig = {
+  upstreamDB: string;
+  authSecret: string;
+  queryURL: string;
+  mutateURL: string;
+};
+
+export function getZeroCacheConfig(): ZeroCacheConfig {
+  const upstreamDB = process.env.ZERO_UPSTREAM_DB;
+  const authSecret = process.env.ZERO_AUTH_SECRET;
+
+  if (!upstreamDB) {
+    throw new Error("ZERO_UPSTREAM_DB is required to run zero-cache.");
+  }
+
+  if (!authSecret) {
+    throw new Error("ZERO_AUTH_SECRET is required to authenticate Zero clients.");
+  }
+
+  return {
+    upstreamDB,
+    authSecret,
+    queryURL: "http://localhost:3000/api/query",
+    mutateURL: "http://localhost:3000/api/mutate",
+  };
+}

package/packs/sync-zero/pack.toml

@@ -0,0 +1,61 @@
+name = "sync-zero"
+version = "1.0.0"
+category = "infra"
+description = "Rocicorp Zero client-first sync setup for a Postgres-backed app."
+provides = ["sync"]
+requires = ["db-pg"]
+conflicts = ["sync"]
+requires_runtime = ["server"]
+compatible_scaffolds = ["nextjs"]
+
+[runtime_package]
+package = "@forgeailab/spark-sync-zero"
+version = "^0.1"
+
+[dependencies]
+runtime = ["@rocicorp/zero"]
+
+[env]
+required = ["ZERO_AUTH_SECRET", "ZERO_UPSTREAM_DB"]
+optional = []
+
+[[files]]
+mode = "create"
+from = "zero.config.ts"
+to = "zero.config.ts"
+
+[[files]]
+mode = "create"
+from = "lib/zero/schema.ts"
+to = "lib/zero/schema.ts"
+
+[[files]]
+mode = "create"
+from = "lib/zero/client.ts"
+to = "lib/zero/client.ts"
+
+[[files]]
+mode = "create"
+from = "components/ZeroProvider.tsx"
+to = "components/ZeroProvider.tsx"
+
+[[files]]
+mode = "create-or-skip"
+from = "docker-compose.yml"
+to = "docker-compose.yml"
+
+[[files]]
+mode = "create"
+from = "compose/zero-cache.yml"
+to = "compose/zero-cache.yml"
+
+[[files]]
+mode = "append"
+from = "docker-compose.include.yml"
+to = "docker-compose.yml"
+
+[skills]
+copy = ["skills/zero-patterns"]
+
+[tasks]
+file = "tasks.yaml"

package/packs/sync-zero/skills/zero-patterns/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: zero-patterns
+description: Use when implementing Rocicorp Zero client-first sync, schema changes, queries, mutators, or zero-cache setup in an spark project.
+---
+
+# Zero Patterns
+
+## Core Model
+
+Zero is client-first. Reads should feel local because the client queries its
+local store first, then syncs with `zero-cache` and the upstream Postgres
+database in the background.
+
+Do not treat Zero as a REST wrapper. Keep query definitions and mutators as
+the product contract. Components consume those contracts through Zero React
+helpers instead of hand-building fetch calls for synced data.
+
+## Before Coding
+
+1. Check which `db` pack is installed.
+2. Find the authoritative database schema and migrations.
+3. Read `lib/zero/schema.ts`.
+4. Identify the smallest set of rows the UI needs.
+5. Confirm auth context before exposing user-scoped data.
+
+## Schema Authoring
+
+Zero schema mirrors the subset of Postgres that clients can query. Keep it
+small, explicit, and aligned with the database.
+
+Use table builders from `@rocicorp/zero`, for example `table`, `string`,
+`boolean`, `number`, `json`, and `enumeration`.
+
+Every table must have an explicit primary key. Prefer stable string IDs for
+client-created records. Avoid auto-increment IDs for records created from the
+client because mutators may run more than once.
+
+When adding fields, use an expand deploy order: database first, then server
+query or mutate code, then client usage. When removing fields, reverse that:
+client stops using it, then server stops exposing it, then database removes it.
+
+## Queries
+
+Clients should call named query helpers, not arbitrary server endpoints. Keep
+queries narrow enough that Zero can cache and update them efficiently.
+
+## Mutators
+
+Mutators are optimistic. They can run on the client and again on the server, so
+they must be deterministic and safe to replay.
+
+Generate IDs before calling the mutator and pass them as arguments. Do not
+generate random IDs, timestamps, or external side effects inside a mutator.
+
+Validate mutator arguments at the boundary. Keep authorization checks on the
+server path, even if the client path also hides unauthorized actions.
+
+## Local Development
+
+`zero-cache` needs a Postgres upstream with logical replication enabled. Keep
+`ZERO_UPSTREAM_DB` pointed at the same database your app server uses.
+
+## Review Checklist
+
+- Schema matches current migrations.
+- Client-visible rows are scoped by query and auth context.
+- Mutators are deterministic and replay-safe.
+- Query shape is indexed or intentionally small.
+- Local setup documents `ZERO_UPSTREAM_DB` and cache reset steps.

package/packs/sync-zero/tasks.yaml

@@ -0,0 +1,16 @@
+epic: Sync
+tasks:
+  - id: ZERO-001
+    title: Define initial schema in lib/zero/schema.ts
+    status: Clarifying
+    acceptance:
+      - The Zero schema matches the first database tables that need client-first reads.
+      - Every synced table has an explicit primary key and only includes fields needed by the client.
+      - Schema changes are deployed in Zero-safe expand or contract order.
+  - id: ZERO-002
+    title: Run zero-cache locally
+    status: Clarifying
+    acceptance:
+      - zero-cache starts with ZERO_UPSTREAM_DB pointed at a logical-replication-enabled Postgres database.
+      - Local app query and mutate endpoints are reachable from zero-cache.
+      - The development workflow documents how to reset the local SQLite replica.

package/packs/testing-playwright/files/e2e/example.spec.ts

@@ -0,0 +1,7 @@
+import { expect, test } from "@playwright/test";
+
+test("landing page renders a heading", async ({ page }) => {
+  await page.goto("/");
+
+  await expect(page.locator("h1")).toBeVisible();
+});

package/packs/testing-playwright/files/playwright.config.ts

@@ -0,0 +1,33 @@
+import { defineConfig, devices } from "@playwright/test";
+
+const port = Number(process.env.PORT ?? 3000);
+const baseURL = `http://127.0.0.1:${port}`;
+
+export default defineConfig({
+  testDir: "./e2e",
+  fullyParallel: true,
+  timeout: 30_000,
+  expect: {
+    timeout: 5_000,
+  },
+  reporter: process.env.CI ? [["github"], ["html", { open: "never" }]] : "list",
+  use: {
+    baseURL,
+    trace: "on-first-retry",
+  },
+  webServer: {
+    command: "bun dev",
+    url: baseURL,
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+    env: {
+      PORT: String(port),
+    },
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+});

package/packs/testing-playwright/pack.toml

@@ -0,0 +1,25 @@
+name = "testing-playwright"
+version = "1.0.0"
+category = "testing"
+description = "Playwright end-to-end test setup for the Next.js scaffold."
+provides = ["e2e"]
+requires = []
+conflicts = []
+requires_runtime = ["server"]
+compatible_scaffolds = ["nextjs"]
+
+[dependencies]
+dev = ["@playwright/test"]
+
+[[files]]
+mode = "create"
+from = "playwright.config.ts"
+to = "playwright.config.ts"
+
+[[files]]
+mode = "create"
+from = "e2e/example.spec.ts"
+to = "e2e/example.spec.ts"
+
+[tasks]
+file = "tasks.yaml"

package/packs/testing-playwright/tasks.yaml

@@ -0,0 +1,9 @@
+epic: Testing
+
+tasks:
+  - id: E2E-001
+    title: Add a smoke test for the first user-facing flow
+    status: Clarifying
+    acceptance:
+      - The first user-facing flow has a Playwright smoke test.
+      - The test runs against the local dev server through Playwright config.

package/packs/ui-shadcn/files/app/globals.css

@@ -0,0 +1,56 @@
+/* # >>> spark:ui-shadcn >>> */
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 222.2 84% 4.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 222.2 84% 4.9%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 222.2 84% 4.9%;
+    --primary: 221.2 83.2% 53.3%;
+    --primary-foreground: 210 40% 98%;
+    --secondary: 210 40% 96.1%;
+    --secondary-foreground: 222.2 47.4% 11.2%;
+    --muted: 210 40% 96.1%;
+    --muted-foreground: 215.4 16.3% 46.9%;
+    --accent: 210 40% 96.1%;
+    --accent-foreground: 222.2 47.4% 11.2%;
+    --destructive: 0 84.2% 60.2%;
+    --destructive-foreground: 210 40% 98%;
+    --border: 214.3 31.8% 91.4%;
+    --input: 214.3 31.8% 91.4%;
+    --ring: 221.2 83.2% 53.3%;
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 222.2 84% 4.9%;
+    --foreground: 210 40% 98%;
+    --card: 222.2 84% 4.9%;
+    --card-foreground: 210 40% 98%;
+    --popover: 222.2 84% 4.9%;
+    --popover-foreground: 210 40% 98%;
+    --primary: 217.2 91.2% 59.8%;
+    --primary-foreground: 222.2 47.4% 11.2%;
+    --secondary: 217.2 32.6% 17.5%;
+    --secondary-foreground: 210 40% 98%;
+    --muted: 217.2 32.6% 17.5%;
+    --muted-foreground: 215 20.2% 65.1%;
+    --accent: 217.2 32.6% 17.5%;
+    --accent-foreground: 210 40% 98%;
+    --destructive: 0 62.8% 30.6%;
+    --destructive-foreground: 210 40% 98%;
+    --border: 217.2 32.6% 17.5%;
+    --input: 217.2 32.6% 17.5%;
+    --ring: 224.3 76.3% 48%;
+  }
+
+  * {
+    @apply border-border;
+  }
+
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+/* # <<< spark:ui-shadcn <<< */

package/packs/ui-shadcn/files/components/ui/button.tsx

@@ -0,0 +1,47 @@
+import * as React from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '@/lib/utils';
+
+const buttonVariants = cva(
+  'inline-flex h-10 items-center justify-center gap-2 whitespace-nowrap rounded-md px-4 py-2 text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+        outline: 'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
+        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        ghost: 'hover:bg-accent hover:text-accent-foreground',
+        link: 'text-primary underline-offset-4 hover:underline',
+      },
+      size: {
+        default: 'h-10 px-4 py-2',
+        sm: 'h-9 rounded-md px-3',
+        lg: 'h-11 rounded-md px-8',
+        icon: 'h-10 w-10',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+    },
+  },
+);
+
+export function Button({
+  className,
+  variant,
+  size,
+  asChild = false,
+  ...props
+}: React.ComponentProps<'button'> &
+  VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+  }) {
+  const Comp = asChild ? Slot : 'button';
+
+  return <Comp className={cn(buttonVariants({ variant, size, className }))} {...props} />;
+}
+
+export { buttonVariants };