@forgeailab/spark 0.2.0 → 0.4.0

package/src/io/board.ts

@@ -1,17 +1,23 @@
 import { readFile } from 'node:fs/promises';
-import { join, resolve, sep } from 'node:path';
+import { resolve, sep } from 'node:path';
 import {
   BoardTaskStatus,
+  readAllChangeTasks,
   seedTasks as seedPackageTasks,
 } from '../internal/board';
 
 export {
   BoardTaskStatus,
+  parseBoardMarkdown,
+  parseTasksMarkdown,
+  readAllChangeTasks,
   readBoard,
+  renderBuildStatus,
   seedTasks,
   updateStatus,
 } from '../internal/board';
 export type {
+  AggregatedTask,
   Board,
   BoardEpic,
   BoardTask as ParsedBoardTask,
@@ -33,16 +39,12 @@ function stripYamlValue(value: string): string {
   ) {
     return trimmed.slice(1, -1);
   }
-
   return trimmed;
 }
 
 function parseKeyValue(line: string): { key: string; value: string } | undefined {
   const index = line.indexOf(':');
-  if (index === -1) {
-    return undefined;
-  }
-
+  if (index === -1) return undefined;
   return {
     key: line.slice(0, index).trim(),
     value: stripYamlValue(line.slice(index + 1)),
@@ -57,9 +59,7 @@ export function parseTasksYaml(raw: string): BoardTask[] {
 
   for (const line of raw.split(/\r?\n/u)) {
     const trimmed = line.trim();
-    if (trimmed.length === 0 || trimmed.startsWith('#')) {
-      continue;
-    }
+    if (trimmed.length === 0 || trimmed.startsWith('#')) continue;
 
     if (!trimmed.startsWith('- ') && parseKeyValue(trimmed)?.key === 'epic') {
       defaultEpic = parseKeyValue(trimmed)?.value || defaultEpic;
@@ -68,20 +68,13 @@ export function parseTasksYaml(raw: string): BoardTask[] {
 
     if (trimmed.startsWith('- id:')) {
       const id = stripYamlValue(trimmed.slice('- id:'.length));
-      current = {
-        id,
-        title: id,
-        epic: defaultEpic,
-        acceptance: [],
-      };
+      current = { id, title: id, epic: defaultEpic, acceptance: [] };
       tasks.push(current);
       inAcceptance = false;
       continue;
     }
 
-    if (!current) {
-      continue;
-    }
+    if (!current) continue;
 
     if (trimmed === 'acceptance:' || trimmed === 'acceptance_criteria:') {
       inAcceptance = true;
@@ -94,9 +87,7 @@ export function parseTasksYaml(raw: string): BoardTask[] {
     }
 
     const kv = parseKeyValue(trimmed);
-    if (!kv) {
-      continue;
-    }
+    if (!kv) continue;
 
     if (kv.key === 'title') {
       current.title = kv.value;
@@ -112,66 +103,40 @@ export function parseTasksYaml(raw: string): BoardTask[] {
   return tasks.filter((task) => task.id.length > 0);
 }
 
-async function readExisting(path: string): Promise<string> {
-  try {
-    return await readFile(path, 'utf8');
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-      return '# Board\n';
-    }
-    throw error;
-  }
-}
-
-function escapeRegex(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-function boardHasTask(board: string, taskId: string): boolean {
-  return new RegExp(`\\b${escapeRegex(taskId)}\\b`).test(board);
-}
-
-function formatTaskDescription(task: BoardTask, packName: string): string {
-  const acceptance =
-    task.acceptance.length > 0
-      ? task.acceptance.map((item) => `  - ${item}`)
-      : ['  - Confirm acceptance criteria for this pack task.'];
-
-  return [`requires_pack: ${packName}`, 'acceptance:', ...acceptance].join('\n');
-}
-
 function assertInsidePack(packRoot: string, path: string): string {
   const resolvedRoot = resolve(packRoot);
   const resolvedPath = resolve(packRoot, path);
-
   if (resolvedPath !== resolvedRoot && !resolvedPath.startsWith(`${resolvedRoot}${sep}`)) {
     throw new Error(`Refusing to read tasks file outside pack root: ${path}`);
   }
-
   return resolvedPath;
 }
 
+// The pack-install change's task lines carry "Status: Clarifying" + "requires_pack:"
+// (added by internal/board.ts); here we only contribute the acceptance sub-bullets.
+function formatTaskDescription(task: BoardTask): string {
+  const acceptance =
+    task.acceptance.length > 0
+      ? task.acceptance.map((item) => `  - ${item}`)
+      : ['  - Confirm acceptance criteria for this pack task.'];
+  return ['acceptance:', ...acceptance].join('\n');
+}
+
 export async function seedBoardTasks(
   projectRoot: string,
   packName: string,
   packRoot: string,
   tasksFile?: string,
 ): Promise<string[]> {
-  if (!tasksFile) {
-    return [];
-  }
+  if (!tasksFile) return [];
 
   const rawTasks = await readFile(assertInsidePack(packRoot, tasksFile), 'utf8');
   const tasks = parseTasksYaml(rawTasks);
-  if (tasks.length === 0) {
-    return [];
-  }
+  if (tasks.length === 0) return [];
 
   const taskIds = tasks.map((task) => task.id);
   const missingBefore = await missingBoardTasks(projectRoot, taskIds);
-  if (missingBefore.length === 0) {
-    return [];
-  }
+  if (missingBefore.length === 0) return [];
 
   const missing = new Set(missingBefore);
   await seedPackageTasks(
@@ -184,7 +149,7 @@ export async function seedBoardTasks(
         id: task.id,
         title: task.title,
         status: BoardTaskStatus.Todo,
-        description: formatTaskDescription(task, packName),
+        description: formatTaskDescription(task),
       })),
   );
 
@@ -196,8 +161,7 @@ export async function missingBoardTasks(
   projectRoot: string,
   taskIds: readonly string[],
 ): Promise<string[]> {
-  const boardPath = join(projectRoot, '.ai', 'board.md');
-  const board = await readExisting(boardPath);
-
-  return taskIds.filter((taskId) => !boardHasTask(board, taskId)).sort();
+  if (taskIds.length === 0) return [];
+  const existingIds = new Set((await readAllChangeTasks(projectRoot)).map((task) => task.id));
+  return taskIds.filter((id) => !existingIds.has(id)).sort();
 }

package/src/io/env.ts

@@ -25,8 +25,13 @@ function hasEnvVar(content: string, key: string): boolean {
   return new RegExp(`^\\s*(?:export\\s+)?${escapeRegex(key)}\\s*=`, 'm').test(content);
 }
 
-async function appendEnvVarsToFile(path: string, vars: readonly string[]): Promise<string[]> {
-  const current = await readExisting(path);
+async function appendEnvVarsToFile(
+  path: string,
+  vars: readonly string[],
+  createIfMissing = false,
+): Promise<string[]> {
+  const existing = await readExisting(path);
+  const current = existing === undefined && createIfMissing ? '' : existing;
   if (current === undefined) {
     return [];
   }
@@ -50,7 +55,7 @@ export async function appendEnvVars(
   const results: EnvApplyResult[] = [];
 
   for (const file of ['.env.example', '.env.local']) {
-    const added = await appendEnvVarsToFile(join(projectRoot, file), uniqueVars);
+    const added = await appendEnvVarsToFile(join(projectRoot, file), uniqueVars, file === '.env.example');
     results.push({ file, added });
   }
 

package/src/io/files.ts

@@ -1,6 +1,6 @@
 import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
-import { dirname, resolve, sep } from 'node:path';
+import { dirname, extname, resolve, sep } from 'node:path';
 import type { PackManifest } from '@forgeailab/spark-schema';
 import type { AppSkillsConfig } from '../config.ts';
 
@@ -60,6 +60,20 @@ function hashContent(content: string): string {
   return createHash('sha256').update(content).digest('hex');
 }
 
+function commentSyntax(path: string): { start: string; end: string } {
+  const extension = extname(path).slice(1).toLowerCase();
+
+  if (['css', 'scss', 'less', 'js', 'cjs', 'mjs', 'ts', 'tsx', 'jsx', 'json5'].includes(extension)) {
+    return { start: '/* ', end: ' */' };
+  }
+
+  if (['html', 'htm', 'xml', 'svg', 'vue'].includes(extension)) {
+    return { start: '<!-- ', end: ' -->' };
+  }
+
+  return { start: '# ', end: '' };
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -114,15 +128,16 @@ export function renderTemplate(template: string, config: AppSkillsConfig): strin
   );
 }
 
-function appendBlock(packName: string, content: string): { marker: string; block: string } {
+function appendBlock(packName: string, content: string, destinationPath: string): { marker: string; block: string } {
   const marker = `spark:${packName}`;
-  const begin = `# >>> ${marker} >>>`;
-  const end = `# <<< ${marker} <<<`;
+  const { start, end } = commentSyntax(destinationPath);
+  const begin = `${start}>>> ${marker} >>>${end}`.trim();
+  const finish = `${start}<<< ${marker} <<<${end}`.trim();
   const trimmedContent = content.replace(/\s+$/u, '');
 
   return {
     marker,
-    block: `${begin}\n${trimmedContent}\n${end}\n`,
+    block: `${begin}\n${trimmedContent}\n${finish}\n`,
   };
 }
 
@@ -189,10 +204,10 @@ export async function applyFileOperation(
   }
 
   if (operation.mode === 'append') {
-    const { marker, block } = appendBlock(options.packName, sourceContent);
+    const { marker, block } = appendBlock(options.packName, sourceContent, destination);
     const current = (await fileExists(destination)) ? await readFile(destination, 'utf8') : '';
 
-    if (current.includes(`# >>> ${marker} >>>`)) {
+    if (current.includes(marker)) {
       return {
         to: operation.to,
         mode: operation.mode,

package/packs/README.md

@@ -1,130 +0,0 @@
-# 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
-
-| Pack | Category |
-|---|---|
-| `auth-better-auth` | auth |
-| `auth-better-auth-pg` | auth |
-| `auth-supabase` | auth |
-| `db-sqlite` | db |
-| `db-postgres` | db |
-| `db-supabase` | db |
-| `sync-zero` | infra |
-| `payments-stripe` | payments |
-| `ai-anthropic` | ai |
-| `ai-openai` | ai |
-| `ui-shadcn` | ui |
-| `email-resend` | email |
-| `analytics-posthog` | analytics |
-| `docker-compose-dev` | infra |
-| `testing-playwright` | testing |
-| `deploy-vercel` | deploy |
-
-### Picking a db + auth pair
-
-`auth-better-auth` and `auth-better-auth-pg` share the same Better Auth factory
-code in their generated `lib/auth.ts` templates — they differ only in the
-`provider:` handed 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 copy-mode packs were authored against [`reference/full-stack-saas/`](../reference/full-stack-saas/) — the canonical integration showing the copied templates working together. When debugging one of these packs, start there.
-
-See the root `README.md` for the catalog summary.

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

@@ -1,57 +0,0 @@
-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

@@ -1,58 +0,0 @@
-import Anthropic from '@anthropic-ai/sdk';
-
-export function createAnthropicClient(
-  apiKey: string,
-  options?: ConstructorParameters<typeof Anthropic>[0],
-): Anthropic {
-  return new Anthropic({ apiKey, ...options });
-}
-
-const encoder = new TextEncoder();
-
-function isContentBlockDeltaEvent(event: unknown): event is { type: 'content_block_delta' } {
-  return (
-    typeof event === 'object' &&
-    event !== null &&
-    (event as { type?: unknown }).type === 'content_block_delta'
-  );
-}
-
-function encodeSse(payload: unknown) {
-  return encoder.encode(`data: ${JSON.stringify(payload)}\n\n`);
-}
-
-export function streamResponse(
-  client: Anthropic,
-  params: Parameters<Anthropic['messages']['stream']>[0],
-): ReadableStream<Uint8Array> {
-  return new ReadableStream<Uint8Array>({
-    async start(controller) {
-      try {
-        const stream = client.messages.stream(params);
-
-        for await (const event of stream) {
-          if (isContentBlockDeltaEvent(event)) {
-            controller.enqueue(encodeSse(event));
-          }
-        }
-
-        controller.enqueue(encoder.encode('data: [DONE]\n\n'));
-        controller.close();
-      } catch (error) {
-        controller.error(error);
-      }
-    },
-  });
-}
-
-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 type AnthropicChatMessage = Anthropic.Messages.MessageParam;

package/packs/ai-anthropic/pack.toml

@@ -1,31 +0,0 @@
-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 = []
-
-[dependencies]
-runtime = ["@anthropic-ai/sdk"]
-
-[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

@@ -1,87 +0,0 @@
----
-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

@@ -1,9 +0,0 @@
-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.