@forgeailab/create-spark 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeailab/create-spark",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Interactive scaffolder for spark projects with guided pack picker.",
   "type": "module",
   "publishConfig": {
@@ -8,14 +8,17 @@
   },
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "templates",
+    "packs",
+    "presets"
   ],
   "bin": {
     "create-spark": "./src/cli.ts"
   },
   "dependencies": {
-    "@forgeailab/spark": "workspace:*",
-    "@forgeailab/spark-schema": "workspace:*",
+    "@forgeailab/spark": "^0.1.2",
+    "@forgeailab/spark-schema": "^0.1.2",
     "@clack/prompts": "latest",
     "citty": "latest",
     "picocolors": "latest"

package/packs/README.md

@@ -0,0 +1,132 @@
+# Packs
+
+A **pack** is a self-contained unit of capability — auth, db, payments, UI, AI SDK, email, deploy target, … — that the `spark` CLI can install into a scaffolded project. Packs are TOML-manifested, declarative (no shell hooks), and capability-resolved.
+
+## Directory layout
+
+```
+packs/<name>/
+├── pack.toml         # manifest (REQUIRED)
+├── files/            # tree of files to copy into the project (optional)
+├── skills/           # SKILL.md folders shipped with this pack (optional)
+└── tasks.yaml        # board tasks seeded into .ai/board.md on install (optional)
+```
+
+## `pack.toml`
+
+See [`docs/pack-spec.md`](../docs/pack-spec.md) for the full schema. The Zod source of truth is `packages/spark-schema/src/pack.ts`.
+
+A minimum-viable pack:
+
+```toml
+name = "db-sqlite"
+version = "0.1.0"
+category = "db"
+description = "Local SQLite database via bun:sqlite + drizzle-orm."
+
+provides = ["db"]
+requires = []
+conflicts = ["db"]
+requires_runtime = ["server"]
+compatible_scaffolds = ["nextjs"]
+
+[dependencies]
+runtime = ["drizzle-orm"]
+dev = ["drizzle-kit"]
+
+[env]
+required = ["DATABASE_URL"]
+
+[[files]]
+mode = "create"
+from = "files/lib/db.ts"
+to = "lib/db.ts"
+
+[tasks]
+file = "tasks.yaml"
+```
+
+## File modes
+
+| Mode | Behavior |
+|---|---|
+| `create` | Fails if the destination already exists |
+| `append` | Idempotent; uses `# >>> spark:<pack> >>>` / `# <<<` markers |
+| `merge-json` | Deep-merges into an existing JSON file with deterministic key order |
+| `template` | Handlebars-style substitution from `spark.config.json` (e.g. `{{appName}}`) |
+
+## Capability enums (closed)
+
+**Pack capabilities** (`provides` / `requires` / `conflicts`):
+`db, auth, payments, email, ui-kit, local-runtime, deploy-target, e2e, ai-sdk, blob-storage, analytics, sync`
+
+Exclusive (one provider per project): `db, auth, payments, ui-kit, sync`
+Non-exclusive (multiple providers OK): `ai-sdk, analytics, email, blob-storage, e2e, deploy-target, local-runtime`
+
+**Template capabilities** (`requires_runtime`):
+`static, server, react, native, vue, svelte, mdx-content, edge-runtime`
+
+The two enums are separate and never overlap. Adding a new value requires a registry-wide change.
+
+## What is NOT allowed
+
+- `post_install`, `hooks`, `pre_add`, `scripts` — packs MUST be declarative. If your pack needs a setup step that can't be expressed in `[[files]]`, ship it as a seeded board task the user runs manually.
+- Pack-name conflicts (`conflicts = ["other-pack-name"]`). Use capability tags only.
+- Cross-pack file ownership. Two packs MUST NOT write the same `to` path with `create` mode.
+
+## Adding a new pack
+
+```bash
+# In Claude Code:
+/new-pack realtime-supabase category=db
+```
+
+Then fill in the generated `packs/realtime-supabase/pack.toml`. Validate with:
+
+```bash
+bun -e "import {parsePackToml} from './packages/spark-schema/src/parse.ts'; import {readFileSync} from 'node:fs'; const r = parsePackToml(readFileSync('packs/realtime-supabase/pack.toml','utf8')); console.log(r.ok ? 'OK' : r.error);"
+```
+
+See `packs/example/pack.toml` for a manifest that exercises every field.
+
+## v1 catalog
+
+Each pack is either **copy** (ships file trees the user owns) or **hybrid** (ships thin wiring + imports runtime logic from a versioned `@forgeailab/spark-*` helper under `libs/`). The mode is inferred from the presence of a `[runtime_package]` block in the manifest.
+
+| Pack | Category | Mode | Runtime helper |
+|---|---|---|---|
+| `auth-better-auth` | auth | **hybrid** | `@forgeailab/spark-auth-better-auth` (SQLite) |
+| `auth-better-auth-pg` | auth | **hybrid** | `@forgeailab/spark-auth-better-auth` (Postgres) |
+| `auth-supabase` | auth | copy | — |
+| `db-sqlite` | db | copy | — |
+| `db-postgres` | db | copy | — |
+| `db-supabase` | db | copy | — |
+| `sync-zero` | infra | **hybrid** | `@forgeailab/spark-sync-zero` |
+| `payments-stripe` | payments | **hybrid** | `@forgeailab/spark-stripe-helpers` |
+| `ai-anthropic` | ai | **hybrid** | `@forgeailab/spark-anthropic` |
+| `ai-openai` | ai | copy | — |
+| `ui-shadcn` | ui | copy | — |
+| `email-resend` | email | copy | — |
+| `analytics-posthog` | analytics | copy | — |
+| `docker-compose-dev` | infra | copy | — |
+| `testing-playwright` | testing | copy | — |
+| `deploy-vercel` | deploy | copy | — |
+
+### Picking a db + auth pair
+
+`auth-better-auth` and `auth-better-auth-pg` share the same runtime helper
+(`@forgeailab/spark-auth-better-auth`) — they differ only in the `provider:`
+their generated `lib/auth.ts` template hands to `drizzleAdapter`. Pair them:
+
+- `db-sqlite` + `auth-better-auth` — fastest path, single file db, no infra.
+- `db-postgres` + `auth-better-auth-pg` — production-shaped, **required for `sync-zero`** (Zero needs Postgres logical replication).
+- `db-supabase` + `auth-better-auth-pg` — Supabase-hosted Postgres + Better Auth on top.
+
+The two auth packs both `conflicts = ["auth"]`, so the resolver prevents
+installing both. Mixing wrong pairs (e.g. `db-sqlite` + `auth-better-auth-pg`)
+typechecks but fails at runtime — the drizzle adapter will reject sqlite tables
+with `provider: 'pg'`.
+
+The hybrid packs were authored against [`reference/full-stack-saas/`](../reference/full-stack-saas/) — the canonical integration showing all four helpers working together. When debugging a hybrid pack, start there.
+
+See the root `README.md` for the catalog summary.

package/packs/ai-anthropic/files/app/api/ai/route.ts

@@ -0,0 +1,57 @@
+import { anthropic, streamResponse, type AnthropicChatMessage } from '@/lib/anthropic';
+import { NextResponse, type NextRequest } from 'next/server';
+
+export const runtime = 'nodejs';
+
+const DEFAULT_MODEL = 'claude-sonnet-4-5';
+const DEFAULT_MAX_TOKENS = 1_024;
+const HARD_MAX_TOKENS = 4_096;
+
+type ChatRequest = {
+  messages?: unknown;
+  system?: string;
+  model?: string;
+  maxTokens?: number;
+};
+
+function normalizeMessages(value: unknown): AnthropicChatMessage[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const messages: AnthropicChatMessage[] = [];
+  for (const entry of value) {
+    if (typeof entry !== 'object' || entry === null) return undefined;
+    const role = 'role' in entry ? entry.role : undefined;
+    const content = 'content' in entry ? entry.content : undefined;
+    if ((role !== 'user' && role !== 'assistant') || typeof content !== 'string') return undefined;
+    messages.push({ role, content });
+  }
+  return messages.length > 0 ? messages : undefined;
+}
+
+export async function POST(request: NextRequest) {
+  const body = (await request.json().catch(() => ({}))) as ChatRequest;
+  const messages = normalizeMessages(body.messages);
+
+  if (!messages) {
+    return NextResponse.json(
+      { error: 'messages must be a non-empty array of user/assistant strings' },
+      { status: 400 },
+    );
+  }
+
+  const maxTokens = Math.min(Math.max(1, body.maxTokens ?? DEFAULT_MAX_TOKENS), HARD_MAX_TOKENS);
+
+  const stream = streamResponse(anthropic, {
+    model: body.model ?? DEFAULT_MODEL,
+    max_tokens: maxTokens,
+    system: body.system,
+    messages,
+  });
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+    },
+  });
+}

package/packs/ai-anthropic/files/lib/anthropic.ts

@@ -0,0 +1,15 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import { createAnthropicClient, streamResponse } from '@forgeailab/spark-anthropic';
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}
+
+export const anthropic = createAnthropicClient(requireEnv('ANTHROPIC_API_KEY'));
+
+export { streamResponse };
+export type AnthropicChatMessage = Anthropic.Messages.MessageParam;

package/packs/ai-anthropic/pack.toml

@@ -0,0 +1,32 @@
+name = "ai-anthropic"
+version = "1.0.0"
+category = "ai"
+description = "Anthropic SDK client and streaming chat endpoint."
+provides = ["ai-sdk"]
+requires = []
+conflicts = []
+requires_runtime = ["server"]
+compatible_scaffolds = []
+
+[runtime_package]
+package = "@forgeailab/spark-anthropic"
+version = "^0.1"
+
+[env]
+required = ["ANTHROPIC_API_KEY"]
+
+[[files]]
+mode = "create"
+from = "lib/anthropic.ts"
+to = "lib/anthropic.ts"
+
+[[files]]
+mode = "create"
+from = "app/api/ai/route.ts"
+to = "app/api/ai/route.ts"
+
+[skills]
+copy = ["skills/ai-feature-patterns"]
+
+[tasks]
+file = "tasks.yaml"

package/packs/ai-anthropic/skills/ai-feature-patterns/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: ai-feature-patterns
+description: Build Anthropic-backed AI features with streaming UX, prompt discipline, and cost controls. Use when implementing or reviewing features after the ai-anthropic pack is installed.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+---
+
+# Skill: ai-feature-patterns
+
+## Goal
+
+Add one focused AI capability that helps the product journey without turning the
+MVP into a generic chat app. Keep prompts inspectable, streams responsive, and
+cost bounded by server-side controls.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5 for prompt architecture and evaluation. Sonnet 4.6 or GPT-5
+family executor for endpoint, UI, and test wiring.
+
+## Inputs
+
+Read these before changing AI behavior:
+
+- `.ai/product-spec.md` for the user workflow and non-goals
+- `.ai/architecture.md` for persistence, auth, and runtime boundaries
+- `.ai/board.md` for the exact AI task and acceptance criteria
+- `lib/anthropic.ts` for shared client setup
+- `app/api/ai/route.ts` for request, stream, and guardrail behavior
+
+If the spec does not name the decision or artifact the AI should improve, stop
+and ask. Do not add chat just because an AI SDK is installed.
+
+## Prompt Patterns
+
+- Put durable behavior in a server-owned system prompt.
+- Put user-specific state in structured context, not prose pasted from the UI.
+- Keep task prompts narrow: role, input facts, output format, refusal boundary.
+- Prefer JSON or Markdown output contracts only when the UI actually needs them.
+- Do not ask the model to enforce authorization, billing, or data access rules.
+- Include the smallest useful context window; retrieve or summarize before
+  sending long histories.
+
+## Streaming UX
+
+- Stream text when the user is waiting on generation or analysis.
+- Show partial output in the destination surface, not a separate debug pane.
+- Preserve a cancel path when requests can take more than a few seconds.
+- Persist the final answer only after the stream completes successfully.
+- Treat stream errors as recoverable UI state with a retry action.
+
+## Cost Controls
+
+- Cap `max_tokens` on the server, even when the client sends a smaller hint.
+- Rate limit by user, organization, or IP before calling Anthropic.
+- Add a cheap preflight check for empty prompts and unsupported file sizes.
+- Log model, token caps, latency, and user/account id for cost review.
+- Use smaller models or cached summaries for low-stakes transformations.
+- Keep generated artifacts small enough to review and edit.
+
+## Safety and Privacy
+
+- Send only the data needed for the requested feature.
+- Redact secrets and credentials from context before model calls.
+- Avoid storing raw prompts if they may contain sensitive customer data.
+- Make model output advisory unless the product spec explicitly automates action.
+- Require human confirmation before sending emails, charging users, or deleting data.
+
+## Common Pitfalls
+
+- Do not stream from the browser directly with the API key.
+- Do not let the client choose unlimited tokens or arbitrary expensive models.
+- Do not hide prompt changes in component code; keep prompts close to API routes.
+- Do not make acceptance criteria depend on subjective model quality alone.
+- Do not add vector search, agents, or tool calls unless the board asks for them.
+
+## Verification
+
+Use a small real prompt and confirm all of these:
+
+- The endpoint streams incremental `text` events.
+- The final event is `done`.
+- Invalid input returns a 400 before calling Anthropic.
+- Token caps and rate limits are enforced server-side.

package/packs/ai-anthropic/tasks.yaml

@@ -0,0 +1,9 @@
+epic: AI
+
+tasks:
+  - id: AI-001
+    title: Add cost guardrails (token caps, rate limits)
+    status: Clarifying
+    acceptance:
+      - AI requests have server-side max token caps.
+      - Repeated requests are rate limited before calling Anthropic.

package/packs/ai-openai/files/app/api/ai-openai/route.ts

@@ -0,0 +1,55 @@
+import { getOpenAIClient, OPENAI_CHAT_MODEL, type OpenAIChatMessage } from "../../../lib/openai";
+
+export const runtime = "nodejs";
+
+type ChatRequest = {
+  messages?: OpenAIChatMessage[];
+  prompt?: string;
+};
+
+function normalizeMessages(body: ChatRequest): OpenAIChatMessage[] {
+  if (Array.isArray(body.messages) && body.messages.length > 0) {
+    return body.messages;
+  }
+
+  if (body.prompt) {
+    return [{ role: "user", content: body.prompt }];
+  }
+
+  throw new Error("Request body must include messages or prompt.");
+}
+
+export async function POST(request: Request): Promise<Response> {
+  const body = (await request.json()) as ChatRequest;
+  const messages = normalizeMessages(body);
+
+  const stream = await getOpenAIClient().chat.completions.create({
+    model: OPENAI_CHAT_MODEL,
+    messages,
+    stream: true,
+  });
+
+  const encoder = new TextEncoder();
+  const readable = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      try {
+        for await (const chunk of stream) {
+          const content = chunk.choices[0]?.delta?.content;
+          if (content) {
+            controller.enqueue(encoder.encode(content));
+          }
+        }
+        controller.close();
+      } catch (error) {
+        controller.error(error);
+      }
+    },
+  });
+
+  return new Response(readable, {
+    headers: {
+      "Cache-Control": "no-cache",
+      "Content-Type": "text/plain; charset=utf-8",
+    },
+  });
+}

package/packs/ai-openai/files/lib/openai.ts

@@ -0,0 +1,21 @@
+import OpenAI from "openai";
+
+let client: OpenAI | undefined;
+
+export type OpenAIChatMessage = {
+  role: "developer" | "system" | "user" | "assistant";
+  content: string;
+};
+
+export const OPENAI_CHAT_MODEL = "gpt-5.2";
+
+export function getOpenAIClient(): OpenAI {
+  const apiKey = process.env.OPENAI_API_KEY;
+
+  if (!apiKey) {
+    throw new Error("OPENAI_API_KEY is required to use the OpenAI client.");
+  }
+
+  client ??= new OpenAI({ apiKey });
+  return client;
+}

package/packs/ai-openai/pack.toml

@@ -0,0 +1,30 @@
+name = "ai-openai"
+version = "1.0.0"
+category = "ai"
+description = "OpenAI SDK client wrapper and streaming chat endpoint."
+provides = ["ai-sdk"]
+requires = []
+conflicts = []
+requires_runtime = ["server"]
+compatible_scaffolds = []
+
+[dependencies]
+runtime = ["openai"]
+dev = []
+
+[env]
+required = ["OPENAI_API_KEY"]
+optional = []
+
+[[files]]
+mode = "create"
+from = "lib/openai.ts"
+to = "lib/openai.ts"
+
+[[files]]
+mode = "create"
+from = "app/api/ai-openai/route.ts"
+to = "app/api/ai-openai/route.ts"
+
+[tasks]
+file = "tasks.yaml"

package/packs/ai-openai/tasks.yaml

@@ -0,0 +1,9 @@
+epic: AI
+tasks:
+  - id: AI-101
+    title: Add usage tracking + cost guardrails
+    status: Clarifying
+    acceptance:
+      - OpenAI requests record model, token usage, and user or workspace context.
+      - The endpoint enforces a documented per-user or per-workspace usage limit.
+      - Over-limit requests return a clear non-200 response without calling OpenAI.

package/packs/analytics-posthog/files/components/PostHogProvider.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { useEffect } from "react";
+import posthog from "posthog-js";
+import { PostHogProvider as Provider } from "posthog-js/react";
+import { getPostHogClient } from "../lib/posthog/client";
+
+type PostHogProviderProps = {
+  children: ReactNode;
+};
+
+export function PostHogProvider({ children }: PostHogProviderProps) {
+  useEffect(() => {
+    getPostHogClient();
+  }, []);
+
+  return <Provider client={posthog}>{children}</Provider>;
+}

package/packs/analytics-posthog/files/lib/posthog/client.ts

@@ -0,0 +1,20 @@
+"use client";
+
+import posthog from "posthog-js";
+
+const DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com";
+
+export function getPostHogClient(): typeof posthog {
+  const key = process.env.NEXT_PUBLIC_POSTHOG_KEY;
+  const host = process.env.NEXT_PUBLIC_POSTHOG_HOST ?? DEFAULT_POSTHOG_HOST;
+  const loaded = (posthog as typeof posthog & { __loaded?: boolean }).__loaded;
+
+  if (typeof window !== "undefined" && key && !loaded) {
+    posthog.init(key, {
+      api_host: host,
+      capture_pageview: false,
+    });
+  }
+
+  return posthog;
+}

package/packs/analytics-posthog/files/lib/posthog/server.ts

@@ -0,0 +1,24 @@
+import { PostHog } from "posthog-node";
+
+const DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com";
+
+let client: PostHog | undefined;
+
+export function getPostHogServerClient(): PostHog | undefined {
+  const key = process.env.NEXT_PUBLIC_POSTHOG_KEY;
+
+  if (!key) {
+    return undefined;
+  }
+
+  client ??= new PostHog(key, {
+    host: process.env.NEXT_PUBLIC_POSTHOG_HOST ?? DEFAULT_POSTHOG_HOST,
+  });
+
+  return client;
+}
+
+export async function shutdownPostHogServerClient(): Promise<void> {
+  await client?.shutdown();
+  client = undefined;
+}

package/packs/analytics-posthog/pack.toml

@@ -0,0 +1,35 @@
+name = "analytics-posthog"
+version = "1.0.0"
+category = "analytics"
+description = "PostHog browser and server analytics helpers."
+provides = ["analytics"]
+requires = []
+conflicts = []
+requires_runtime = ["server"]
+compatible_scaffolds = []
+
+[dependencies]
+runtime = ["posthog-js", "posthog-node"]
+dev = []
+
+[env]
+required = ["NEXT_PUBLIC_POSTHOG_KEY"]
+optional = ["NEXT_PUBLIC_POSTHOG_HOST"]
+
+[[files]]
+mode = "create"
+from = "lib/posthog/client.ts"
+to = "lib/posthog/client.ts"
+
+[[files]]
+mode = "create"
+from = "lib/posthog/server.ts"
+to = "lib/posthog/server.ts"
+
+[[files]]
+mode = "create"
+from = "components/PostHogProvider.tsx"
+to = "components/PostHogProvider.tsx"
+
+[tasks]
+file = "tasks.yaml"

package/packs/analytics-posthog/tasks.yaml

@@ -0,0 +1,15 @@
+epic: Analytics
+tasks:
+  - id: ANALYTICS-001
+    title: Wire posthog provider into app root
+    status: Clarifying
+    acceptance:
+      - The app root wraps client routes with PostHogProvider.
+      - Page views are captured intentionally, either by router events or a documented manual call.
+  - id: ANALYTICS-002
+    title: Add consent banner
+    status: Clarifying
+    acceptance:
+      - Users can accept or decline analytics before tracking starts.
+      - The consent choice persists across reloads.
+      - PostHog capture is disabled when consent is declined.

package/packs/auth-better-auth/files/app/(auth)/login/page.tsx

@@ -0,0 +1,58 @@
+'use client';
+
+import { useState, useTransition } from 'react';
+import { createAuthClient } from 'better-auth/react';
+
+const authClient = createAuthClient();
+type SocialProvider = 'github' | 'google';
+
+export default function LoginPage() {
+  const [error, setError] = useState<string | null>(null);
+  const [isPending, startTransition] = useTransition();
+
+  function signIn(provider: SocialProvider) {
+    setError(null);
+    startTransition(() => {
+      void authClient.signIn
+        .social({
+          provider,
+          callbackURL: '/',
+        })
+        .then((result) => {
+          if (result.error) {
+            setError(result.error.message ?? 'Unable to sign in.');
+          }
+        });
+    });
+  }
+
+  return (
+    <main className="mx-auto flex min-h-screen w-full max-w-sm flex-col justify-center px-6">
+      <div className="space-y-2">
+        <h1 className="text-2xl font-semibold tracking-tight">Sign in</h1>
+        <p className="text-sm text-muted-foreground">Continue with a configured OAuth provider.</p>
+      </div>
+
+      <div className="mt-8 grid gap-3">
+        <button
+          className="inline-flex h-10 items-center justify-center rounded-md border border-input bg-background px-4 text-sm font-medium hover:bg-accent hover:text-accent-foreground disabled:opacity-50"
+          disabled={isPending}
+          onClick={() => signIn('github')}
+          type="button"
+        >
+          Continue with GitHub
+        </button>
+        <button
+          className="inline-flex h-10 items-center justify-center rounded-md border border-input bg-background px-4 text-sm font-medium hover:bg-accent hover:text-accent-foreground disabled:opacity-50"
+          disabled={isPending}
+          onClick={() => signIn('google')}
+          type="button"
+        >
+          Continue with Google
+        </button>
+      </div>
+
+      {error ? <p className="mt-4 text-sm text-destructive">{error}</p> : null}
+    </main>
+  );
+}

package/packs/auth-better-auth/files/app/api/auth/[...all]/route.ts

@@ -0,0 +1,4 @@
+import { createAuthHandler } from '@forgeailab/spark-auth-better-auth';
+import { auth } from '@/lib/auth';
+
+export const { GET, POST } = createAuthHandler(auth);