@forgeailab/create-spark 0.1.1 → 0.1.3

package/scripts/sync-skills.ts

@@ -0,0 +1,223 @@
+import { mkdtemp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  parseSkillFrontmatter,
+  serializeSkillFrontmatter,
+  toCodexFrontmatter,
+} from "@forgeailab/spark-skill-utils";
+
+type SkillOutput = {
+  name: string;
+  content: string;
+};
+
+type Diff =
+  | { type: "missing"; path: string }
+  | { type: "extra"; path: string }
+  | { type: "changed"; path: string };
+
+type SyncResult = {
+  ok: boolean;
+  count: number;
+  diffs: Diff[];
+};
+
+type TreeEntry = {
+  type: "dir" | "file";
+  content?: string;
+};
+
+export function transformSkillMarkdown(markdown: string, skillName: string): string {
+  const { frontmatter, body } = parseSkillFrontmatter(markdown);
+  const codexFrontmatter = toCodexFrontmatter(frontmatter);
+  const outputFrontmatter = serializeSkillFrontmatter(codexFrontmatter, {
+    trailingComments: [
+      `# Generated from .claude/skills/${skillName}/SKILL.md — DO NOT EDIT directly`,
+    ],
+  });
+
+  return `---\n${outputFrontmatter}\n---\n${body}`;
+}
+
+async function collectSkillOutputs(root: string): Promise<SkillOutput[]> {
+  const sourceRoot = join(root, ".claude", "skills");
+  const entries = await readdir(sourceRoot, { withFileTypes: true });
+  const outputs: SkillOutput[] = [];
+
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const skillName = entry.name;
+    const sourceFile = join(sourceRoot, skillName, "SKILL.md");
+    if (!existsSync(sourceFile)) {
+      continue;
+    }
+
+    const source = await readFile(sourceFile, "utf8");
+    outputs.push({
+      name: skillName,
+      content: transformSkillMarkdown(source, skillName),
+    });
+  }
+
+  return outputs;
+}
+
+async function writeOutputs(targetRoot: string, outputs: SkillOutput[]): Promise<void> {
+  await rm(targetRoot, { force: true, recursive: true });
+  await mkdir(targetRoot, { recursive: true });
+
+  for (const output of outputs) {
+    const skillDir = join(targetRoot, output.name);
+    await mkdir(skillDir, { recursive: true });
+    await writeFile(join(skillDir, "SKILL.md"), output.content, "utf8");
+  }
+}
+
+async function collectTree(root: string): Promise<Map<string, TreeEntry>> {
+  const tree = new Map<string, TreeEntry>();
+
+  if (!existsSync(root)) {
+    return tree;
+  }
+
+  async function walk(dir: string): Promise<void> {
+    const entries = await readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const absolutePath = join(dir, entry.name);
+      const relativePath = relative(root, absolutePath).split(sep).join("/");
+
+      if (entry.isDirectory()) {
+        tree.set(relativePath, { type: "dir" });
+        await walk(absolutePath);
+        continue;
+      }
+
+      if (entry.isFile()) {
+        tree.set(relativePath, {
+          type: "file",
+          content: await readFile(absolutePath, "utf8"),
+        });
+      }
+    }
+  }
+
+  await walk(root);
+  return tree;
+}
+
+async function diffTrees(expectedRoot: string, actualRoot: string): Promise<Diff[]> {
+  const expected = await collectTree(expectedRoot);
+  const actual = await collectTree(actualRoot);
+  const paths = Array.from(new Set([...expected.keys(), ...actual.keys()])).sort();
+  const diffs: Diff[] = [];
+
+  for (const path of paths) {
+    const expectedEntry = expected.get(path);
+    const actualEntry = actual.get(path);
+
+    if (!expectedEntry) {
+      diffs.push({ type: "extra", path });
+      continue;
+    }
+
+    if (!actualEntry) {
+      diffs.push({ type: "missing", path });
+      continue;
+    }
+
+    if (
+      expectedEntry.type !== actualEntry.type ||
+      (expectedEntry.type === "file" && expectedEntry.content !== actualEntry.content)
+    ) {
+      diffs.push({ type: "changed", path });
+    }
+  }
+
+  return diffs;
+}
+
+export async function syncSkills(
+  targetRoot = process.cwd(),
+  options: { check?: boolean } = {},
+): Promise<SyncResult> {
+  const root = resolve(targetRoot);
+  const targetRootPath = join(root, ".codex", "skills");
+  const outputs = await collectSkillOutputs(root);
+
+  if (!options.check) {
+    await writeOutputs(targetRootPath, outputs);
+    return { ok: true, count: outputs.length, diffs: [] };
+  }
+
+  const tempRoot = await mkdtemp(join(tmpdir(), "sync-skills-"));
+  const expectedRoot = join(tempRoot, "skills");
+
+  try {
+    await writeOutputs(expectedRoot, outputs);
+    const diffs = await diffTrees(expectedRoot, targetRootPath);
+    return { ok: diffs.length === 0, count: outputs.length, diffs };
+  } finally {
+    await rm(tempRoot, { force: true, recursive: true });
+  }
+}
+
+function parseArgs(argv: string[]): { check: boolean; root: string } {
+  const positional: string[] = [];
+  let check = false;
+
+  for (const arg of argv) {
+    if (arg === "--check") {
+      check = true;
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+
+    positional.push(arg);
+  }
+
+  if (positional.length > 1) {
+    throw new Error("Expected at most one positional argument: target project root");
+  }
+
+  return {
+    check,
+    root: positional[0] ?? process.cwd(),
+  };
+}
+
+function printDiffs(diffs: Diff[]): void {
+  for (const diff of diffs) {
+    console.error(`${diff.type}: ${diff.path}`);
+  }
+}
+
+if (import.meta.main) {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const result = await syncSkills(args.root, { check: args.check });
+
+    if (!result.ok) {
+      console.error(".codex/skills is out of sync. Run bun run scripts/sync-skills.ts.");
+      printDiffs(result.diffs);
+      process.exit(1);
+    }
+
+    if (args.check) {
+      console.log(`.codex/skills is in sync (${result.count} skills).`);
+    } else {
+      console.log(`Synced ${result.count} skills into .codex/skills.`);
+    }
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}

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/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>
+  );
+}

package/templates/nextjs/app/(app)/home/posts-panel.tsx

@@ -0,0 +1,83 @@
+'use client';
+
+import { useState, type FormEvent } from 'react';
+import { usePosts } from '@/lib/posts-placeholder';
+
+export function PostsPanel() {
+  const { posts, createPost } = usePosts();
+  const [title, setTitle] = useState('');
+  const [body, setBody] = useState('');
+  const [pending, setPending] = useState(false);
+
+  async function onSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (!title.trim()) return;
+    setPending(true);
+    try {
+      await createPost({ title: title.trim(), body: body.trim() });
+      setTitle('');
+      setBody('');
+    } finally {
+      setPending(false);
+    }
+  }
+
+  return (
+    <div className="mt-3 space-y-4">
+      <form
+        onSubmit={onSubmit}
+        className="rounded-xl border border-slate-200 bg-white p-4 shadow-sm"
+      >
+        <input
+          value={title}
+          onChange={(e) => setTitle(e.target.value)}
+          placeholder="Post title"
+          className="block w-full rounded-md border border-slate-300 px-3 py-2 text-sm placeholder:text-slate-400 focus:border-slate-900 focus:outline-none focus:ring-1 focus:ring-slate-900"
+        />
+        <textarea
+          value={body}
+          onChange={(e) => setBody(e.target.value)}
+          placeholder="Write something…"
+          rows={2}
+          className="mt-2 block w-full rounded-md border border-slate-300 px-3 py-2 text-sm placeholder:text-slate-400 focus:border-slate-900 focus:outline-none focus:ring-1 focus:ring-slate-900"
+        />
+        <div className="mt-3 flex items-center justify-end">
+          <button
+            type="submit"
+            disabled={pending || !title.trim()}
+            className="inline-flex items-center justify-center rounded-md bg-slate-900 px-4 py-1.5 text-sm font-medium text-white shadow-sm transition hover:bg-slate-800 disabled:cursor-not-allowed disabled:opacity-50"
+          >
+            {pending ? 'Posting…' : 'Post'}
+          </button>
+        </div>
+      </form>
+
+      {posts.length === 0 ? (
+        <div className="rounded-xl border border-dashed border-slate-300 bg-white/60 px-4 py-8 text-center text-sm text-slate-500">
+          No posts yet. Install the{' '}
+          <code className="rounded bg-slate-100 px-1">sync-zero</code> pack to
+          persist and sync posts in real time.
+        </div>
+      ) : (
+        <ul className="space-y-2">
+          {posts.map((post) => (
+            <li
+              key={post.id}
+              className="rounded-xl border border-slate-200 bg-white p-4 shadow-sm"
+            >
+              <h3 className="text-sm font-semibold text-slate-900">
+                {post.title}
+              </h3>
+              {post.body && (
+                <p className="mt-1 text-sm text-slate-600">{post.body}</p>
+              )}
+              <p className="mt-2 text-xs text-slate-400">
+                {post.createdAt.toLocaleString()}
+              </p>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

package/templates/nextjs/app/(app)/layout.tsx

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+
+// Placeholder authed-route layout.
+//
+// The `auth-better-auth` pack will replace this with a server-side guard that
+// calls `getSessionUser()` and `redirect('/login')` when there is no session.
+// Until then this just renders children so the scaffold compiles and runs.
+export default function AppLayout({ children }: { children: ReactNode }) {
+  return (
+    <div className="min-h-screen bg-slate-50 text-slate-900">{children}</div>
+  );
+}