@forgeailab/create-spark 0.1.0 → 0.1.2

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"]

package/src/paths.ts

@@ -1,8 +1,8 @@
 import { readFileSync, statSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 
-const monorepoRootError =
-  'Must be run from inside the spark monorepo or set SPARK_ROOT env var pointing to it';
+const catalogRootError =
+  'Catalog directories (templates/, packs/) not found. Set SPARK_ROOT to point at the spark monorepo, or install via the published @forgeailab/create-spark npm package.';
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -32,6 +32,15 @@ function hasWorkspacePackageJson(dir: string): boolean {
   }
 }
 
+// A catalog root is any directory containing the `templates/` and `packs/`
+// folders we need. Two cases produce one:
+//   1) The monorepo root (dev). Also has a `package.json` with `workspaces`.
+//   2) The published @forgeailab/create-spark package directory (npm install).
+//      The publish script bundles templates/ and packs/ into the tarball.
+function isCatalogRoot(dir: string): boolean {
+  return isDirectory(join(dir, 'templates')) && isDirectory(join(dir, 'packs'));
+}
+
 function isMonorepoRoot(dir: string): boolean {
   return hasWorkspacePackageJson(dir) && isDirectory(join(dir, 'templates'));
 }
@@ -42,15 +51,24 @@ export function findMonorepoRoot(startDir: string = import.meta.dir): string {
     return resolve(override);
   }
 
+  // Published-package case: this file lives at <package>/src/paths.ts ->
+  // walk up one dir to <package>/ which the publish script populates with
+  // templates/ and packs/.
+  const packageRoot = resolve(import.meta.dir, '..');
+  if (isCatalogRoot(packageRoot)) {
+    return packageRoot;
+  }
+
+  // Dev / monorepo case: walk up from cwd or src looking for the monorepo.
   let current = resolve(startDir);
   while (true) {
-    if (isMonorepoRoot(current)) {
+    if (isMonorepoRoot(current) || isCatalogRoot(current)) {
       return current;
     }
 
     const parent = dirname(current);
     if (parent === current) {
-      throw new Error(monorepoRootError);
+      throw new Error(catalogRootError);
     }
     current = parent;
   }

package/templates/README.md

@@ -0,0 +1,43 @@
+# Template Authoring
+
+Templates live under `templates/<name>/` and register a base scaffold for `create-spark`. Each template directory must contain a `template.toml` manifest and may contain scaffold files when the template is stable.
+
+## `template.toml`
+
+`template.toml` is parsed with `TemplateManifestSchema` from `packages/spark-schema/src/template.ts`.
+
+Required fields:
+
+- `name`: lowercase template id matching `^[a-z][a-z0-9-]*$`.
+- `status`: `stable` or `planned`.
+- `provides`: array of template capability tags.
+- `description`: one-line human-readable summary.
+
+Example:
+
+```toml
+name = "nextjs"
+status = "stable"
+provides = ["server", "static", "spa"]
+description = "Next.js App Router scaffold for TypeScript web apps."
+```
+
+## Template Capabilities
+
+Template capabilities describe what the base scaffold runtime provides. They are separate from pack capabilities such as `db`, `auth`, or `payments`.
+
+Current accepted template capabilities:
+
+- `server`: can run server-side application code.
+- `spa`: supports client-side single-page app behavior.
+- `native`: supports native app targets.
+- `edge`: supports edge runtime deployment.
+- `library`: is intended as a reusable package or library scaffold.
+- `monorepo`: is a multi-package workspace scaffold.
+- `static`: can emit static assets or static pages.
+
+Use only these exact values until the schema changes. Planned templates should still include a valid `template.toml` so packs and presets can declare compatibility before the full scaffold ships.
+
+## Promoting Planned Templates
+
+To promote a template from `planned` to `stable`, add the runnable scaffold files under `templates/<name>/`, update `status = "stable"`, and run the manifest parser against every template. Stable templates should be copyable into a new project and runnable without requiring auth, database, billing, email, UI libraries, or AI SDK setup by default.

package/templates/astro/README.md

@@ -0,0 +1,3 @@
+# Astro Template
+
+This template is registered for pack compatibility planning, but it is not implemented yet. The planned scope is an Astro content-site scaffold with server rendering, static output support, MDX-oriented content workflows once the template capability schema supports that tag, and the same AI workflow artifacts as the stable Next.js template.

package/templates/astro/template.toml

@@ -0,0 +1,4 @@
+name = "astro"
+status = "planned"
+provides = ["server", "static", "mdx-content"]
+description = "Planned Astro scaffold for content sites with partial hydration."

package/templates/astro-starlight/README.md

@@ -0,0 +1,3 @@
+# Astro Starlight Template
+
+This template is registered for pack compatibility planning, but it is not implemented yet. The planned scope is a static documentation scaffold based on Astro Starlight, with content-focused defaults and the same AI workflow artifacts as the stable Next.js template.

package/templates/astro-starlight/template.toml

@@ -0,0 +1,4 @@
+name = "astro-starlight"
+status = "planned"
+provides = ["static", "mdx-content"]
+description = "Planned Astro Starlight scaffold for documentation sites."

package/templates/nextjs/.ai/architecture.md

@@ -0,0 +1,13 @@
+# Architecture
+
+## Stack
+
+## Repo structure
+
+## Data model
+
+## API surface
+
+## Pack plan
+
+## Non-goals

package/templates/nextjs/.ai/board.md

@@ -0,0 +1,7 @@
+# Board
+
+Status flow: `Clarifying` -> `Approved for planning` -> `Approved for execution` -> `In progress` -> `Needs review` -> `Validated`
+
+Side states: `Blocked`, `Cut from MVP`
+
+## Backlog

package/templates/nextjs/.ai/product-spec.md

@@ -0,0 +1,11 @@
+# Product Spec
+
+## Vision
+
+## Users
+
+## Core flows
+
+## Constraints
+
+## Out of scope

package/templates/nextjs/AGENTS.md

@@ -0,0 +1,95 @@
+# AGENTS.md
+
+Operating rules for any agent (Codex, Claude Code, or otherwise) working in this repo. Mirror of the workflow encoded in `.claude/skills/`, so the system stays portable.
+
+<!-- SPEC:START -->
+## Spec workflow
+
+For proposals/specs/plans, new capabilities, breaking changes, architecture shifts, or behavior-changing perf/security work, keep the source of truth in this project's `.ai/` artifacts first. If the project later adopts formal spec deltas, place them under `docs/spec/changes/<id>-YYYY-MM-DD/`; truth specs after archive live under `docs/spec/specs/`.
+<!-- SPEC:END -->
+
+## Operating model
+
+This project runs a **planner / implementer / evaluator** loop. The same agent should not plan, build, and grade its own work. Use a strong reasoning model (Opus 4.7 / GPT-5.5) for planning and review; use a faster executor (Sonnet 4.6 / GPT-5 family) for routine implementation.
+
+## Source of truth
+
+The truth is in repo artifacts, not in chat:
+
+- `.ai/product-spec.md` — what the MVP is. Source of acceptance criteria and non-goals.
+- `.ai/architecture.md` — the stack and the cutline (what we are NOT building yet).
+- `.ai/ux-theme.md` — visual direction. Empty / loading / error patterns live here.
+- `.ai/board.md` — every task, with status, dependencies, owners, validation state, linked PR.
+- `.ai/decision-log.md` — locked-in decisions and the reasoning.
+- `.ai/execution-log.md` — append-only history of state changes.
+
+If an answer is not in these files, ask the user — do not invent it.
+
+## Workflow phases
+
+1. **Grill the idea** until it is buildable. Max 5 questions per round. Only questions that change scope or architecture.
+2. **Write the spec.** One MVP slice. Non-goals are mandatory.
+3. **Cut the architecture.** Boring stack > clever stack. Every choice has a "not building yet" sibling.
+4. **Theme the UX.** One vibe, one reference product, concrete tokens.
+5. **Build the board.** Tasks sized for one focused session. Declare `Depends on:` and `Parallel-safe:`.
+6. **Review the board.** Approval gate between planning and execution. No task starts until it is `Approved for execution`.
+7. **Brief each task** before execution. Self-contained, with files-to-inspect, acceptance criteria verbatim, and a verification command.
+8. **Execute one task at a time.** Stay inside the declared file list. No bonus refactors.
+9. **Review independently.** A separate pass checks the diff against acceptance criteria, security, and scope.
+10. **QA-verify** by actually running the app and walking the core user journey.
+11. **Sync the board** from git reality. Trust git, not claims.
+
+## Board statuses
+
+`Clarifying` → `Approved for planning` → `Approved for execution` → `In progress` → `Needs review` → `Validated`
+
+Side states: `Blocked`, `Cut from MVP`.
+
+`Validated` requires both a `/code-review` pass and a `/qa-verify` pass for user-facing changes. Execution never grades itself.
+
+## Hard rules
+
+- Do not edit files outside the current task's declared scope. New discoveries become new tasks in `Clarifying`, not silent edits.
+- Do not pick a stack outside `.ai/architecture.md`. Propose a decision-log update first.
+- Do not mark tasks `Validated` without independent review.
+- Do not move a task to `Approved for execution` from execution skills. Only board-review can.
+- Treat the `Non-goals` section of the spec and the `What we are NOT building yet` section of architecture as a `do-not-build` list. Violations are scope creep, not features.
+- Verification commands must actually run. Type-check passing is not the same as feature working.
+- When `git status` and a self-report disagree, trust git.
+
+## Skill / command equivalents
+
+Claude Code skills live in `.claude/skills/`. The same operations on Codex should be triggered through the matching workflow names:
+
+| Stage | Skill |
+| --- | --- |
+| Grill | `mvp-grill`, `idea-sharpen` |
+| Spec | `mvp-spec` |
+| Architecture | `architecture-cutline` |
+| Theme | `ux-theme` |
+| Board | `mvp-board`, `board-review` |
+| Schedule | `parallel-execution`, `next-task` |
+| Execute | `implementation-brief`, `execute-task` |
+| Evaluate | `code-review`, `qa-verify` |
+| Sync | `sync-board` |
+| Watch | `risk-check` |
+
+## Model assignment defaults
+
+- Planning / reviewing / scoping: **Opus 4.7** or **GPT-5.5**.
+- Routine execution: **Sonnet 4.6** or a GPT-5 family executor.
+- High-risk tasks (auth, payments, migrations, security): planning-quality model for both build and review.
+
+## Conventions
+
+- Stable task IDs (e.g. `AUTH-001`). Never renumber.
+- Append to `.ai/decision-log.md` whenever a non-obvious choice is made, with: decision, context, alternatives considered, why, risk, revisit condition.
+- Append to `.ai/execution-log.md` one line per state change in `.ai/board.md`.
+- Do not delete board tasks. Move them to `Cut from MVP` with a reason.
+
+## Packs
+
+Feature packs are installed with the `spark` CLI.
+Use `pack-resolve` to choose the scaffold and pack set, `pack-add` to dry-run
+and install declarative pack changes, then `sync-board` to reconcile `.ai/board.md`
+with the installed capabilities and current repository state.

package/templates/nextjs/CLAUDE.md

@@ -0,0 +1,3 @@
+# CLAUDE.md
+
+Follow `AGENTS.md` for the operating contract. Keep `.ai/board.md` as the task source of truth, and use the `spark` CLI when adding packs or checking installed capabilities.

package/templates/nextjs/README.md

@@ -0,0 +1,20 @@
+# Next.js Spark Template
+
+This is the minimal Next.js 15 + TypeScript scaffold used by `create-spark`.
+
+## Development
+
+Install dependencies, then start the dev server:
+
+```sh
+bun install
+bun dev
+```
+
+## Next Steps
+
+Read `AGENTS.md`, fill in the `.ai/` planning files, and keep `.ai/board.md` current before implementing. Add capabilities only when the board calls for them:
+
+```sh
+spark add <pack>
+```

package/templates/nextjs/anvil.config.json

@@ -0,0 +1,4 @@
+{
+  "appName": "{{appName}}",
+  "template": "nextjs"
+}

package/templates/nextjs/app/(app)/home/page.tsx

@@ -0,0 +1,43 @@
+import Link from 'next/link';
+import { getSessionUser } from '@/lib/auth-placeholder';
+import { PostsPanel } from './posts-panel';
+
+export default async function AppHome() {
+  const user = await getSessionUser();
+
+  return (
+    <main className="mx-auto max-w-3xl px-6 py-12">
+      <header className="flex items-center justify-between">
+        <div>
+          <p className="text-xs font-semibold uppercase tracking-[0.2em] text-slate-500">
+            Home
+          </p>
+          <h1 className="mt-1 text-2xl font-semibold tracking-tight text-slate-900">
+            {user ? `Hello ${user.name}` : 'Hello, friend'}
+          </h1>
+        </div>
+        {!user && (
+          <Link
+            href="/login"
+            className="rounded-md border border-slate-300 bg-white px-3 py-1.5 text-xs font-medium text-slate-700 shadow-sm hover:bg-slate-50"
+          >
+            Sign in
+          </Link>
+        )}
+      </header>
+
+      {!user && (
+        <p className="mt-4 rounded-md border border-amber-200 bg-amber-50 px-4 py-3 text-sm text-amber-900">
+          No session detected. Install the{' '}
+          <code className="rounded bg-amber-100 px-1">auth-better-auth</code>{' '}
+          pack to wire real authentication.
+        </p>
+      )}
+
+      <section className="mt-8">
+        <h2 className="text-sm font-semibold text-slate-700">Your posts</h2>
+        <PostsPanel />
+      </section>
+    </main>
+  );
+}