@forgeailab/create-spark 0.1.1 → 0.1.3

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 };

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

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { cn } from '@/lib/utils';
+
+export function Card({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      className={cn('rounded-lg border bg-card text-card-foreground shadow-sm', className)}
+      {...props}
+    />
+  );
+}
+
+export function CardHeader({ className, ...props }: React.ComponentProps<'div'>) {
+  return <div className={cn('flex flex-col space-y-1.5 p-6', className)} {...props} />;
+}
+
+export function CardTitle({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div className={cn('text-2xl font-semibold leading-none tracking-tight', className)} {...props} />
+  );
+}
+
+export function CardDescription({ className, ...props }: React.ComponentProps<'div'>) {
+  return <div className={cn('text-sm text-muted-foreground', className)} {...props} />;
+}
+
+export function CardContent({ className, ...props }: React.ComponentProps<'div'>) {
+  return <div className={cn('p-6 pt-0', className)} {...props} />;
+}
+
+export function CardFooter({ className, ...props }: React.ComponentProps<'div'>) {
+  return <div className={cn('flex items-center p-6 pt-0', className)} {...props} />;
+}

package/packs/ui-shadcn/files/lib/utils.ts

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

package/packs/ui-shadcn/files/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+
+export default config;

package/packs/ui-shadcn/files/tailwind.config.ts

@@ -0,0 +1,57 @@
+import type { Config } from 'tailwindcss';
+
+const config: Config = {
+  darkMode: ['class'],
+  content: [
+    './app/**/*.{ts,tsx,mdx}',
+    './components/**/*.{ts,tsx,mdx}',
+    './lib/**/*.{ts,tsx,mdx}',
+  ],
+  theme: {
+    extend: {
+      borderRadius: {
+        lg: 'var(--radius)',
+        md: 'calc(var(--radius) - 2px)',
+        sm: 'calc(var(--radius) - 4px)',
+      },
+      colors: {
+        background: 'hsl(var(--background))',
+        foreground: 'hsl(var(--foreground))',
+        card: {
+          DEFAULT: 'hsl(var(--card))',
+          foreground: 'hsl(var(--card-foreground))',
+        },
+        popover: {
+          DEFAULT: 'hsl(var(--popover))',
+          foreground: 'hsl(var(--popover-foreground))',
+        },
+        primary: {
+          DEFAULT: 'hsl(var(--primary))',
+          foreground: 'hsl(var(--primary-foreground))',
+        },
+        secondary: {
+          DEFAULT: 'hsl(var(--secondary))',
+          foreground: 'hsl(var(--secondary-foreground))',
+        },
+        muted: {
+          DEFAULT: 'hsl(var(--muted))',
+          foreground: 'hsl(var(--muted-foreground))',
+        },
+        accent: {
+          DEFAULT: 'hsl(var(--accent))',
+          foreground: 'hsl(var(--accent-foreground))',
+        },
+        destructive: {
+          DEFAULT: 'hsl(var(--destructive))',
+          foreground: 'hsl(var(--destructive-foreground))',
+        },
+        border: 'hsl(var(--border))',
+        input: 'hsl(var(--input))',
+        ring: 'hsl(var(--ring))',
+      },
+    },
+  },
+  plugins: [],
+};
+
+export default config;

package/packs/ui-shadcn/pack.toml

@@ -0,0 +1,44 @@
+name = "ui-shadcn"
+version = "1.0.0"
+category = "ui"
+description = "Shadcn-style UI primitives for Next.js dashboards."
+provides = ["ui-kit"]
+requires = []
+conflicts = ["ui-kit"]
+requires_runtime = ["react"]
+compatible_scaffolds = ["nextjs"]
+
+[dependencies]
+runtime = [
+  "@radix-ui/react-slot",
+  "class-variance-authority",
+  "clsx",
+  "tailwind-merge",
+  "lucide-react",
+]
+
+[[files]]
+mode = "create"
+from = "lib/utils.ts"
+to = "lib/utils.ts"
+
+[[files]]
+mode = "create"
+from = "components/ui/button.tsx"
+to = "components/ui/button.tsx"
+
+[[files]]
+mode = "create"
+from = "components/ui/card.tsx"
+to = "components/ui/card.tsx"
+
+[[files]]
+mode = "append"
+from = "app/globals.css"
+to = "app/globals.css"
+
+[skills]
+copy = ["skills/shadcn-dashboard-patterns"]
+
+[tasks]
+file = "tasks.yaml"

package/packs/ui-shadcn/skills/shadcn-dashboard-patterns/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: shadcn-dashboard-patterns
+description: Compose shadcn-style primitives into dense, practical dashboard layouts without drifting into marketing UI.
+---
+
+# Skill: shadcn-dashboard-patterns
+
+## Goal
+
+Build dashboard screens from small primitives that stay easy to scan, resize,
+and extend. Use the shadcn component style as a starting point, not as a reason
+to turn every section into a card.
+
+## Defaults
+
+- Start with the user's job, not the component catalog.
+- Put navigation, filters, and primary actions where repeat users expect them.
+- Prefer one clear page title, one toolbar, and one main content region.
+- Use cards for repeated objects, stat summaries, forms, and modal content.
+- Do not wrap the whole page in a decorative card.
+- Keep radii at `rounded-lg` or below unless the app theme says otherwise.
+- Use `cn()` for class merging and keep variants close to the component.
+
+## Layout
+
+- Use a shell with a sidebar or top nav only when there are real destinations.
+- Keep dashboard width constrained with `mx-auto w-full max-w-7xl px-4`.
+- Use `gap-4` or `gap-6`; avoid ornamental whitespace in operational views.
+- Put status, owner, date, and filters near the table or list they affect.
+- Align destructive actions away from the primary happy path.
+- Keep tables full width and let dense data breathe through row height.
+- Use sticky headers only when the table is long enough to justify them.
+
+## Cards
+
+- A card should represent one thing: a metric, a record, a form, or a chart.
+- Do not nest cards inside cards.
+- Use `CardHeader`, `CardContent`, and `CardFooter` only when each region helps.
+- Small metric cards should use compact labels, one strong value, and a trend.
+- Empty cards should show the empty state for that object, not generic help copy.
+- Repeated cards need stable height or clear wrapping behavior.
+
+## Buttons
+
+- Primary buttons create or commit work.
+- Secondary buttons reveal adjacent options.
+- Ghost buttons belong in rows, toolbars, and low-emphasis actions.
+- Icon buttons need an accessible label.
+- Use `asChild` when routing through `Link`, not nested buttons or anchors.
+- Keep button labels short and concrete: `Save`, `Invite`, `Export`.
+- Avoid full-width buttons on desktop unless the panel itself is narrow.
+
+## Forms
+
+- Group fields by workflow, not by database table.
+- Put validation text next to the field that caused it.
+- Use disabled and pending states during server actions.
+- Use destructive copy only for irreversible actions.
+- Keep advanced settings collapsed until they are needed.
+- Use consistent input widths inside the same form group.
+
+## Tables And Lists
+
+- Use a table when users compare many rows across the same fields.
+- Use a list when records have mixed metadata and short actions.
+- Keep row actions at the trailing edge.
+- Expose bulk actions only after selection exists.
+- Use badges sparingly for status, plan, role, or risk.
+- Do not use color as the only status signal.
+
+## Empty, Loading, Error
+
+- Empty states should offer the next valid action.
+- Loading states should preserve the final layout shape.
+- Error states should say what failed and offer retry or recovery.
+- Avoid giant empty illustrations inside work dashboards.
+- Do not teach the whole product in an empty state.
+
+## Motion And Polish
+
+- Prefer subtle color, border, and shadow changes over large motion.
+- Keep hover states predictable across cards, rows, and buttons.
+- Respect reduced motion when adding transitions.
+- Check mobile wrapping for toolbar actions and long entity names.
+- Make the first useful workflow visible without a landing page.

package/packs/ui-shadcn/tasks.yaml

@@ -0,0 +1,6 @@
+epic: UI
+tasks:
+  - id: UI-001
+    title: Build first dashboard page
+    acceptance:
+      - First dashboard page uses the installed UI primitives for a real app workflow

package/presets/docs-site.toml

@@ -0,0 +1,4 @@
+name = "docs-site"
+description = "Documentation site (placeholder -- activates once astro-starlight template ships)."
+compatible_scaffolds = ["astro-starlight"]
+packs = []

package/presets/internal-tool.toml

@@ -0,0 +1,4 @@
+name = "internal-tool"
+description = "Internal admin tool -- Supabase auth, shadcn UI, local docker for dev."
+compatible_scaffolds = ["nextjs"]
+packs = ["db-supabase", "auth-supabase", "ui-shadcn", "docker-compose-dev"]

package/presets/lean-saas.toml

@@ -0,0 +1,4 @@
+name = "lean-saas"
+description = "Lean SaaS -- no Supabase. SQLite + Better Auth + shadcn + Vercel."
+compatible_scaffolds = ["nextjs"]
+packs = ["db-sqlite", "auth-better-auth", "ui-shadcn", "deploy-vercel"]

package/presets/local-ai-mvp.toml

@@ -0,0 +1,4 @@
+name = "local-ai-mvp"
+description = "Local-first AI MVP -- SQLite + Claude + shadcn on Next.js, with Playwright tests."
+compatible_scaffolds = ["nextjs"]
+packs = ["db-sqlite", "ai-anthropic", "ui-shadcn", "testing-playwright"]

package/presets/saas-classic.toml

@@ -0,0 +1,4 @@
+name = "saas-classic"
+description = "Classic SaaS stack -- Supabase + Stripe + Resend on Next.js."
+compatible_scaffolds = ["nextjs"]
+packs = ["db-supabase", "auth-supabase", "payments-stripe", "email-resend", "ui-shadcn", "deploy-vercel"]