@forgeailab/create-spark 0.1.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@forgeailab/create-spark",
+  "version": "0.1.0",
+  "description": "Interactive scaffolder for spark projects with guided pack picker.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "bin": {
+    "create-spark": "./src/cli.ts"
+  },
+  "dependencies": {
+    "@forgeailab/spark": "workspace:*",
+    "@forgeailab/spark-schema": "workspace:*",
+    "@clack/prompts": "latest",
+    "citty": "latest",
+    "picocolors": "latest"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "latest"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,367 @@
+#!/usr/bin/env bun
+
+import { access, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { cancel, confirm, intro, isCancel, outro, select, text } from '@clack/prompts';
+import { runAdd } from '@forgeailab/spark/src/commands/add.ts';
+import { defineCommand, runMain } from 'citty';
+import pc from 'picocolors';
+import { copyTemplate } from './copy.ts';
+import { loadPackRegistry } from './pack-registry.ts';
+import { findMonorepoRoot } from './paths.ts';
+import {
+  filterAuthByDb,
+  filterSyncByDb,
+  groupByCategory,
+  orderedForCategory,
+  parsePacksFlag,
+  recommendedFor,
+  type DbPick,
+  type GroupedPacks,
+  type PickerCategory,
+} from './picker.ts';
+import { applyPreset } from './preset.ts';
+import { promptCategory, promptConfirmPlan, promptMultiCategory } from './prompts.ts';
+import { loadTemplateRegistry, type TemplateMetadata } from './registry.ts';
+import { syncSkills } from './skills.ts';
+
+export const PLANNED_TEMPLATE_MESSAGE = 'planned, not yet implemented';
+
+type CreateAppArgs = {
+  appName?: unknown;
+  template?: unknown;
+  preset?: unknown;
+  packs?: unknown;
+  noPacks?: unknown;
+  'no-packs'?: unknown;
+  yes?: unknown;
+};
+
+type ScaffoldConfig = {
+  appName: string;
+  template: string;
+  createdAt: string;
+};
+
+export function plannedTemplateMessage(templateName: string): string {
+  return `Template "${templateName}" is ${PLANNED_TEMPLATE_MESSAGE}. Use "nextjs" for v1 or see docs/spec/changes/add-scaffold-and-pack-registry-2026-05-21/design.md#decision-11.`;
+}
+
+function asOptionalString(value: unknown): string | undefined {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function asBoolean(value: unknown): boolean {
+  return value === true;
+}
+
+function abortIfCancel<T>(value: T | symbol): T {
+  if (isCancel(value)) {
+    cancel('Operation cancelled.');
+    process.exit(1);
+  }
+
+  return value;
+}
+
+function isPacksFlagProvided(rawArgs: CreateAppArgs): boolean {
+  return rawArgs.packs !== undefined;
+}
+
+function isNoPacks(rawArgs: CreateAppArgs): boolean {
+  return asBoolean(rawArgs.noPacks) || asBoolean(rawArgs['no-packs']);
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function promptForAppName(): Promise<string> {
+  const answer = abortIfCancel(
+    await text({
+      message: 'App name',
+      placeholder: 'my-app',
+      validate(value) {
+        return value?.trim().length ? undefined : 'Enter an app name.';
+      },
+    }),
+  );
+
+  return answer.trim();
+}
+
+function formatTemplateLabel(template: TemplateMetadata): string {
+  return template.status === 'planned' ? `${template.name} (planned)` : template.name;
+}
+
+async function promptForTemplate(templates: TemplateMetadata[]): Promise<string> {
+  const answer = abortIfCancel(
+    await select<string>({
+      message: 'Template',
+      options: templates.map((template) => ({
+        value: template.name,
+        label: formatTemplateLabel(template),
+        hint: template.description,
+      })),
+    }),
+  );
+
+  return answer;
+}
+
+async function promptForPreset(skipOptionalPrompts: boolean): Promise<string | undefined> {
+  if (skipOptionalPrompts) {
+    return undefined;
+  }
+
+  const wantsPreset = abortIfCancel(
+    await confirm({
+      message: 'Apply a preset?',
+      initialValue: false,
+    }),
+  );
+
+  if (!wantsPreset) {
+    return undefined;
+  }
+
+  const preset = abortIfCancel(
+    await text({
+      message: 'Preset name',
+      placeholder: 'saas-classic',
+      validate(value) {
+        return value?.trim().length ? undefined : 'Enter a preset name.';
+      },
+    }),
+  );
+
+  return preset.trim();
+}
+
+function findTemplate(templates: TemplateMetadata[], templateName: string): TemplateMetadata {
+  const template = templates.find((candidate) => candidate.name === templateName);
+  if (template !== undefined) {
+    return template;
+  }
+
+  const registered = templates.map((candidate) => candidate.name).join(', ');
+  throw new Error(`Unknown template "${templateName}". Registered templates: ${registered}`);
+}
+
+function addPick(picks: string[], pick: string | undefined): void {
+  if (pick !== undefined) {
+    picks.push(pick);
+  }
+}
+
+function addPicks(picks: string[], selected: readonly string[] | undefined): void {
+  if (selected !== undefined) {
+    picks.push(...selected);
+  }
+}
+
+async function collectInteractivePackPicks(groups: GroupedPacks): Promise<string[]> {
+  const picks: string[] = [];
+
+  const dbPick = (await promptCategory(
+    'db',
+    orderedForCategory('db', groups.db),
+    recommendedFor('db'),
+  )) as DbPick;
+  addPick(picks, dbPick);
+
+  if (dbPick !== undefined) {
+    const authPick = await promptCategory(
+      'auth',
+      filterAuthByDb(groups.auth, dbPick),
+      recommendedFor('auth', dbPick),
+    );
+    addPick(picks, authPick);
+
+    const syncPick = await promptCategory(
+      'sync',
+      filterSyncByDb(groups.sync, dbPick),
+      recommendedFor('sync', dbPick),
+    );
+    addPick(picks, syncPick);
+  }
+
+  addPick(
+    picks,
+    await promptCategory(
+      'ui',
+      orderedForCategory('ui', groups.ui),
+      recommendedFor('ui', dbPick),
+    ),
+  );
+  addPicks(picks, await promptMultiCategory('ai', orderedForCategory('ai', groups.ai)));
+
+  for (const category of ['email', 'analytics', 'deploy'] as const satisfies readonly PickerCategory[]) {
+    addPick(
+      picks,
+      await promptCategory(
+        category,
+        orderedForCategory(category, groups[category]),
+        recommendedFor(category, dbPick),
+      ),
+    );
+  }
+
+  addPicks(picks, await promptMultiCategory('infra', orderedForCategory('infra', groups.infra)));
+  addPicks(
+    picks,
+    await promptMultiCategory('testing', orderedForCategory('testing', groups.testing), [
+      'testing-playwright',
+    ]),
+  );
+
+  return picks;
+}
+
+function recommendedYesPicks(): string[] {
+  return ['db-sqlite', 'auth-better-auth', 'testing-playwright'];
+}
+
+async function collectPackPicks(rawArgs: CreateAppArgs, presetName: string | undefined): Promise<string[]> {
+  const yes = asBoolean(rawArgs.yes);
+  const noPacks = isNoPacks(rawArgs);
+  const packsFlagProvided = isPacksFlagProvided(rawArgs);
+
+  if (packsFlagProvided && noPacks) {
+    throw new Error('--packs cannot be combined with --no-packs.');
+  }
+
+  if (presetName !== undefined) {
+    return [];
+  }
+
+  if (noPacks) {
+    return [];
+  }
+
+  if (packsFlagProvided) {
+    return parsePacksFlag(typeof rawArgs.packs === 'string' ? rawArgs.packs : '');
+  }
+
+  if (yes) {
+    return recommendedYesPicks();
+  }
+
+  const packs = await loadPackRegistry();
+  return collectInteractivePackPicks(groupByCategory(packs));
+}
+
+async function createApp(rawArgs: CreateAppArgs): Promise<void> {
+  intro(pc.cyan('create-spark'));
+
+  const templates = await loadTemplateRegistry();
+  const appName = asOptionalString(rawArgs.appName) ?? (await promptForAppName());
+  const requestedTemplate = asOptionalString(rawArgs.template) ?? (await promptForTemplate(templates));
+  const template = findTemplate(templates, requestedTemplate);
+
+  if (template.status === 'planned') {
+    throw new Error(plannedTemplateMessage(template.name));
+  }
+
+  const targetDir = resolve(process.cwd(), appName);
+  if (await exists(targetDir)) {
+    throw new Error(`Target directory already exists: ${targetDir}`);
+  }
+
+  const skipPresetPrompt =
+    asBoolean(rawArgs.yes) || isPacksFlagProvided(rawArgs) || isNoPacks(rawArgs);
+  const presetName =
+    asOptionalString(rawArgs.preset) ?? (await promptForPreset(skipPresetPrompt));
+  const createdAt = new Date().toISOString();
+  const vars: Record<string, string> = {
+    appName,
+    template: template.name,
+    preset: presetName ?? '',
+    createdAt,
+  };
+
+  await copyTemplate(template.name, targetDir, vars);
+
+  const config: ScaffoldConfig = {
+    appName,
+    template: template.name,
+    createdAt,
+  };
+  await writeFile(join(targetDir, 'spark.config.json'), `${JSON.stringify(config, null, 2)}\n`);
+
+  const monorepoRoot = findMonorepoRoot();
+  await syncSkills(targetDir, monorepoRoot);
+
+  const packPicks = await collectPackPicks(rawArgs, presetName);
+  if (presetName === undefined && !asBoolean(rawArgs.yes)) {
+    await promptConfirmPlan(packPicks);
+  }
+  if (presetName === undefined) {
+    if (packPicks.length > 0) {
+      await runAdd(packPicks, { projectRoot: targetDir, yes: true });
+    }
+  }
+
+  if (presetName !== undefined) {
+    await applyPreset(targetDir, presetName, monorepoRoot);
+  }
+
+  outro(pc.green(`Created ${appName}`));
+}
+
+const main = defineCommand({
+  meta: {
+    name: 'create-spark',
+    description: 'Create an AI-ready spark project.',
+  },
+  args: {
+    appName: {
+      type: 'positional',
+      description: 'Application name or target directory.',
+      required: false,
+    },
+    template: {
+      type: 'string',
+      description: 'Template name.',
+      required: false,
+    },
+    preset: {
+      type: 'string',
+      description: 'Preset name to apply after scaffolding.',
+      required: false,
+    },
+    packs: {
+      type: 'string',
+      description: 'Comma-separated pack names to install after scaffolding.',
+      required: false,
+    },
+    'no-packs': {
+      type: 'boolean',
+      description: 'Skip pack installation after scaffolding.',
+      required: false,
+    },
+    yes: {
+      type: 'boolean',
+      alias: 'y',
+      description: 'Skip optional prompts.',
+      required: false,
+    },
+  },
+  async run({ args }) {
+    await createApp(args);
+  },
+});
+
+if (import.meta.main) {
+  runMain(main);
+}

package/src/copy.ts

@@ -0,0 +1,69 @@
+import { mkdir, readFile, readdir, readlink, symlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { getTemplatesDir } from './registry.ts';
+
+const placeholderPattern = /\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g;
+
+function applyTemplatePlaceholders(content: string, vars: Record<string, string>): string {
+  return content.replace(placeholderPattern, (placeholder, key: string) => {
+    return Object.prototype.hasOwnProperty.call(vars, key) ? vars[key] : placeholder;
+  });
+}
+
+function isBinaryContent(content: Buffer): boolean {
+  return content.includes(0);
+}
+
+async function copyTemplateDirectory(
+  sourceDir: string,
+  targetDir: string,
+  vars: Record<string, string>,
+): Promise<void> {
+  const entries = await readdir(sourceDir, { withFileTypes: true });
+  await mkdir(targetDir, { recursive: true });
+
+  await Promise.all(
+    entries.map(async (entry) => {
+      if (entry.name === 'template.toml') {
+        return;
+      }
+
+      const sourcePath = join(sourceDir, entry.name);
+      const targetPath = join(targetDir, entry.name);
+
+      if (entry.isDirectory()) {
+        await copyTemplateDirectory(sourcePath, targetPath, vars);
+        return;
+      }
+
+      if (entry.isSymbolicLink()) {
+        const linkTarget = await readlink(sourcePath);
+        await mkdir(dirname(targetPath), { recursive: true });
+        await symlink(linkTarget, targetPath);
+        return;
+      }
+
+      if (!entry.isFile()) {
+        return;
+      }
+
+      const content = await readFile(sourcePath);
+      await mkdir(dirname(targetPath), { recursive: true });
+
+      if (isBinaryContent(content)) {
+        await writeFile(targetPath, content);
+        return;
+      }
+
+      await writeFile(targetPath, applyTemplatePlaceholders(content.toString('utf8'), vars), 'utf8');
+    }),
+  );
+}
+
+export async function copyTemplate(
+  templateName: string,
+  targetDir: string,
+  vars: Record<string, string>,
+): Promise<void> {
+  await copyTemplateDirectory(join(getTemplatesDir(), templateName), targetDir, vars);
+}

package/src/pack-registry.ts

@@ -0,0 +1,71 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parsePackToml, type ParseError, type RuntimePackageBlock } from '@forgeailab/spark-schema';
+import { findMonorepoRoot } from './paths.ts';
+import type { PickerPack } from './picker.ts';
+
+export type PackMetadata = PickerPack;
+
+export function getPacksDir(): string {
+  return process.env.CREATE_SPARK_PACKS_DIR ?? join(findMonorepoRoot(), 'packs');
+}
+
+function formatParseError(error: ParseError): string {
+  const issues = error.issues?.map((issue) => `  - ${issue}`).join('\n');
+  return issues === undefined ? error.message : `${error.message}\n${issues}`;
+}
+
+async function readChildDirectories(root: string): Promise<string[]> {
+  const entries = await readdir(root, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith('_'))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+async function readToml(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+export async function loadPackRegistry(packsDir: string = getPacksDir()): Promise<PackMetadata[]> {
+  const entries = await Promise.all(
+    (await readChildDirectories(packsDir)).map(async (dirName) => {
+      const manifestPath = join(packsDir, dirName, 'pack.toml');
+      const raw = await readToml(manifestPath);
+      if (raw === undefined) {
+        return undefined;
+      }
+
+      const parsed = parsePackToml(raw);
+
+      if (!parsed.ok) {
+        throw new Error(`Invalid pack manifest at ${manifestPath}:\n${formatParseError(parsed.error)}`);
+      }
+
+      const manifest = parsed.data;
+      if (manifest.name !== dirName) {
+        throw new Error(`${manifestPath}: pack name "${manifest.name}" must match directory "${dirName}"`);
+      }
+
+      return {
+        name: manifest.name,
+        category: manifest.category,
+        description: manifest.description ?? '',
+        provides: manifest.provides,
+        requires: manifest.requires,
+        runtimePackage: manifest.runtime_package as RuntimePackageBlock | undefined,
+      };
+    }),
+  );
+
+  return entries
+    .filter((pack): pack is PackMetadata => pack !== undefined)
+    .sort((left, right) => left.name.localeCompare(right.name));
+}

package/src/paths.ts

@@ -0,0 +1,57 @@
+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';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT' || code === 'ENOTDIR') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function hasWorkspacePackageJson(dir: string): boolean {
+  try {
+    const parsed = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as unknown;
+    return isRecord(parsed) && Object.hasOwn(parsed, 'workspaces');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function isMonorepoRoot(dir: string): boolean {
+  return hasWorkspacePackageJson(dir) && isDirectory(join(dir, 'templates'));
+}
+
+export function findMonorepoRoot(startDir: string = import.meta.dir): string {
+  const override = process.env.SPARK_ROOT?.trim();
+  if (override) {
+    return resolve(override);
+  }
+
+  let current = resolve(startDir);
+  while (true) {
+    if (isMonorepoRoot(current)) {
+      return current;
+    }
+
+    const parent = dirname(current);
+    if (parent === current) {
+      throw new Error(monorepoRootError);
+    }
+    current = parent;
+  }
+}

package/src/picker.ts

@@ -0,0 +1,194 @@
+export type RuntimePackageMetadata = {
+  package: string;
+  version: string;
+};
+
+export type PickerPack = {
+  name: string;
+  category: string;
+  description: string;
+  provides: readonly string[];
+  requires: readonly string[];
+  runtimePackage?: RuntimePackageMetadata;
+};
+
+export type PickerCategory =
+  | 'db'
+  | 'auth'
+  | 'sync'
+  | 'ui'
+  | 'ai'
+  | 'email'
+  | 'analytics'
+  | 'deploy'
+  | 'infra'
+  | 'testing';
+
+export type DbPick = 'db-sqlite' | 'db-postgres' | 'db-supabase' | undefined;
+
+export type GroupedPacks = Record<PickerCategory, PickerPack[]>;
+
+export const pickerCategories = [
+  'db',
+  'auth',
+  'sync',
+  'ui',
+  'ai',
+  'email',
+  'analytics',
+  'deploy',
+  'infra',
+  'testing',
+] as const satisfies readonly PickerCategory[];
+
+const categorySet = new Set<PickerCategory>(pickerCategories);
+
+function emptyGroups(): GroupedPacks {
+  return {
+    db: [],
+    auth: [],
+    sync: [],
+    ui: [],
+    ai: [],
+    email: [],
+    analytics: [],
+    deploy: [],
+    infra: [],
+    testing: [],
+  };
+}
+
+function pickerCategoryFor(pack: PickerPack): PickerCategory | undefined {
+  if (pack.name === 'sync-zero' || pack.provides.includes('sync')) {
+    return 'sync';
+  }
+
+  if (categorySet.has(pack.category as PickerCategory)) {
+    return pack.category as PickerCategory;
+  }
+
+  return undefined;
+}
+
+function orderByName(packs: readonly PickerPack[], names: readonly string[]): PickerPack[] {
+  const byName = new Map(packs.map((pack) => [pack.name, pack]));
+  return names.flatMap((name) => {
+    const pack = byName.get(name);
+    return pack === undefined ? [] : [pack];
+  });
+}
+
+export function groupByCategory(packs: readonly PickerPack[]): GroupedPacks {
+  const groups = emptyGroups();
+
+  for (const pack of packs) {
+    const category = pickerCategoryFor(pack);
+    if (category !== undefined) {
+      groups[category].push(pack);
+    }
+  }
+
+  return groups;
+}
+
+export function orderedForCategory(
+  category: PickerCategory,
+  packs: readonly PickerPack[],
+): PickerPack[] {
+  switch (category) {
+    case 'db':
+      return orderByName(packs, ['db-sqlite', 'db-postgres', 'db-supabase']);
+    case 'auth':
+      return orderByName(packs, ['auth-better-auth', 'auth-better-auth-pg', 'auth-supabase']);
+    case 'sync':
+      return orderByName(packs, ['sync-zero']);
+    case 'ui':
+      return orderByName(packs, ['ui-shadcn']);
+    case 'ai':
+      return orderByName(packs, ['ai-anthropic', 'ai-openai']);
+    case 'email':
+      return orderByName(packs, ['email-resend']);
+    case 'analytics':
+      return orderByName(packs, ['analytics-posthog']);
+    case 'deploy':
+      return orderByName(packs, ['deploy-vercel']);
+    case 'infra':
+      return orderByName(packs, ['docker-compose-dev']);
+    case 'testing':
+      return orderByName(packs, ['testing-playwright']);
+  }
+}
+
+export function filterAuthByDb(
+  authPacks: readonly PickerPack[],
+  dbPick: DbPick,
+): PickerPack[] {
+  if (dbPick === 'db-sqlite') {
+    return orderByName(authPacks, ['auth-better-auth']);
+  }
+
+  if (dbPick === 'db-postgres') {
+    return orderByName(authPacks, ['auth-better-auth-pg']);
+  }
+
+  if (dbPick === 'db-supabase') {
+    return orderByName(authPacks, ['auth-supabase', 'auth-better-auth-pg']);
+  }
+
+  return [];
+}
+
+export function filterSyncByDb(
+  syncPacks: readonly PickerPack[],
+  dbPick: DbPick,
+): PickerPack[] {
+  if (dbPick === 'db-postgres' || dbPick === 'db-supabase') {
+    return orderByName(syncPacks, ['sync-zero']);
+  }
+
+  return [];
+}
+
+export function recommendedFor(category: PickerCategory, dbPick?: DbPick): string | undefined {
+  switch (category) {
+    case 'db':
+      return 'db-sqlite';
+    case 'auth':
+      if (dbPick === 'db-sqlite') {
+        return 'auth-better-auth';
+      }
+      if (dbPick === 'db-postgres') {
+        return 'auth-better-auth-pg';
+      }
+      if (dbPick === 'db-supabase') {
+        return 'auth-supabase';
+      }
+      return undefined;
+    case 'sync':
+      return dbPick === 'db-postgres' ? 'sync-zero' : undefined;
+    case 'ui':
+      return 'ui-shadcn';
+    case 'email':
+      return 'email-resend';
+    case 'analytics':
+      return 'analytics-posthog';
+    case 'deploy':
+      return 'deploy-vercel';
+    case 'testing':
+      return 'testing-playwright';
+    case 'ai':
+    case 'infra':
+      return undefined;
+  }
+}
+
+export function parsePacksFlag(raw: string | undefined): string[] {
+  if (raw === undefined) {
+    return [];
+  }
+
+  return raw
+    .split(',')
+    .map((pack) => pack.trim())
+    .filter((pack) => pack.length > 0);
+}

package/src/preset.ts

@@ -0,0 +1,35 @@
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function applyPreset(
+  targetDir: string,
+  presetName: string,
+  monorepoRoot: string,
+): Promise<void> {
+  const cliPath = join(monorepoRoot, 'packages', 'cli', 'src', 'cli.ts');
+
+  // TODO: Replace this subprocess fallback with a direct runPreset import once @forgeailab/spark exports it.
+  if (!(await exists(cliPath))) {
+    throw new Error(`Cannot apply preset "${presetName}" because packages/spark/src/cli.ts does not exist yet.`);
+  }
+
+  const proc = Bun.spawn(['bun', '--bun', cliPath, 'preset', presetName], {
+    cwd: targetDir,
+    stdout: 'inherit',
+    stderr: 'inherit',
+  });
+  const exitCode = await proc.exited;
+
+  if (exitCode !== 0) {
+    throw new Error(`Preset "${presetName}" failed with exit code ${exitCode}.`);
+  }
+}

package/src/prompts.ts

@@ -0,0 +1,117 @@
+import { cancel, confirm, isCancel, multiselect, select } from '@clack/prompts';
+import pc from 'picocolors';
+import type { PickerCategory, PickerPack } from './picker.ts';
+
+const skipValue = '__skip__';
+
+const categoryLabels: Record<PickerCategory, string> = {
+  db: 'Database',
+  auth: 'Auth',
+  sync: 'Sync',
+  ui: 'UI',
+  ai: 'AI',
+  email: 'Email',
+  analytics: 'Analytics',
+  deploy: 'Deploy',
+  infra: 'Infra',
+  testing: 'Testing',
+};
+
+function abortIfCancel<T>(value: T | symbol): T {
+  if (isCancel(value)) {
+    cancel('Operation cancelled.');
+    process.exit(1);
+  }
+
+  return value;
+}
+
+function optionLabel(pack: PickerPack, recommended: string | undefined): string {
+  return pack.name === recommended ? `${pack.name} (recommended)` : pack.name;
+}
+
+export async function promptCategory(
+  category: PickerCategory,
+  options: readonly PickerPack[],
+  recommended?: string,
+): Promise<string | undefined> {
+  if (options.length === 0) {
+    return undefined;
+  }
+
+  const answer = abortIfCancel(
+    await select<string>({
+      message: categoryLabels[category],
+      options: [
+        ...options.map((pack) => ({
+          value: pack.name,
+          label: optionLabel(pack, recommended),
+          hint: pack.description,
+        })),
+        {
+          value: skipValue,
+          label: 'skip',
+          hint: `Do not install a ${categoryLabels[category].toLowerCase()} pack.`,
+        },
+      ],
+    }),
+  );
+
+  return answer === skipValue ? undefined : answer;
+}
+
+export async function promptMultiCategory(
+  category: PickerCategory,
+  options: readonly PickerPack[],
+  defaultChecked: readonly string[] = [],
+): Promise<string[] | undefined> {
+  if (options.length === 0) {
+    return undefined;
+  }
+
+  const answer = abortIfCancel(
+    await multiselect<string>({
+      message: categoryLabels[category],
+      options: options.map((pack) => ({
+        value: pack.name,
+        label: defaultChecked.includes(pack.name) ? `${pack.name} (recommended)` : pack.name,
+        hint: pack.description,
+      })),
+      initialValues: [...defaultChecked],
+      required: false,
+    }),
+  );
+
+  return answer.length > 0 ? answer : undefined;
+}
+
+function formatSummary(picks: readonly string[]): string {
+  const title = 'Pack plan';
+  const rows = picks.length > 0 ? picks.map((pick) => `- ${pick}`) : ['No packs selected.'];
+  const width = Math.max(title.length, ...rows.map((row) => row.length));
+  const border = `+${'-'.repeat(width + 2)}+`;
+  const line = (value: string): string => `| ${value.padEnd(width)} |`;
+
+  return [
+    pc.cyan(border),
+    pc.cyan(line(title)),
+    pc.cyan(border),
+    ...rows.map((row) => pc.cyan(line(row))),
+    pc.cyan(border),
+  ].join('\n');
+}
+
+export async function promptConfirmPlan(picks: readonly string[]): Promise<void> {
+  console.log(formatSummary(picks));
+  const accepted = abortIfCancel(
+    await confirm({
+      message: 'Looks good?',
+      initialValue: true,
+    }),
+  );
+
+  if (!accepted) {
+    cancel('Cancelled');
+    process.exit(1);
+  }
+}

package/src/registry.ts

@@ -0,0 +1,56 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseTemplateToml, type ParseError, type TemplateManifest } from '@forgeailab/spark-schema';
+import { findMonorepoRoot } from './paths.ts';
+
+export type TemplateMetadata = TemplateManifest;
+
+export function getTemplatesDir(): string {
+  return process.env.CREATE_SPARK_TEMPLATES_DIR ?? join(findMonorepoRoot(), 'templates');
+}
+
+function formatParseError(error: ParseError): string {
+  const issues = error.issues?.map((issue) => `  - ${issue}`).join('\n');
+  return issues === undefined ? error.message : `${error.message}\n${issues}`;
+}
+
+async function findTemplateManifests(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const nested = await Promise.all(
+    entries.map(async (entry) => {
+      const entryPath = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        return findTemplateManifests(entryPath);
+      }
+
+      if (entry.isFile() && entry.name === 'template.toml') {
+        return [entryPath];
+      }
+
+      return [];
+    }),
+  );
+
+  return nested.flat();
+}
+
+export async function loadTemplateRegistry(
+  templatesDir: string = getTemplatesDir(),
+): Promise<TemplateMetadata[]> {
+  const manifestPaths = await findTemplateManifests(templatesDir);
+  const templates = await Promise.all(
+    manifestPaths.map(async (manifestPath) => {
+      const raw = await readFile(manifestPath, 'utf8');
+      const parsed = parseTemplateToml(raw);
+
+      if (!parsed.ok) {
+        throw new Error(`Invalid template manifest at ${manifestPath}:\n${formatParseError(parsed.error)}`);
+      }
+
+      return parsed.data;
+    }),
+  );
+
+  return templates.sort((left, right) => left.name.localeCompare(right.name));
+}

package/src/skills.ts

@@ -0,0 +1,136 @@
+import { access, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { findMonorepoRoot } from './paths.ts';
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function transformClaudeSkillForCodex(content: string): string {
+  if (!content.startsWith('---\n')) {
+    return content;
+  }
+
+  const endIndex = content.indexOf('\n---', 4);
+  if (endIndex === -1) {
+    return content;
+  }
+
+  const frontmatter = content.slice(4, endIndex).split('\n');
+  const filtered: string[] = [];
+  let skippingAllowedTools = false;
+
+  for (const line of frontmatter) {
+    if (line.startsWith('allowed-tools:')) {
+      skippingAllowedTools = true;
+      continue;
+    }
+
+    if (skippingAllowedTools) {
+      if (line.trim() === '' || /^\s+-\s/.test(line)) {
+        continue;
+      }
+
+      skippingAllowedTools = false;
+    }
+
+    filtered.push(line);
+  }
+
+  return `---\n${filtered.join('\n').trimEnd()}\n---${content.slice(endIndex + 4)}`;
+}
+
+async function copyDirectory(
+  sourceDir: string,
+  targetDir: string,
+  transform?: (relativePath: string, content: Buffer) => Buffer | string,
+  relativeBase = '',
+): Promise<void> {
+  await mkdir(targetDir, { recursive: true });
+
+  const entries = await readdir(sourceDir, { withFileTypes: true });
+  await Promise.all(
+    entries.map(async (entry) => {
+      const sourcePath = join(sourceDir, entry.name);
+      const targetPath = join(targetDir, entry.name);
+      const relativePath = join(relativeBase, entry.name);
+
+      if (entry.isDirectory()) {
+        await copyDirectory(sourcePath, targetPath, transform, relativePath);
+        return;
+      }
+
+      if (!entry.isFile()) {
+        return;
+      }
+
+      const content = await readFile(sourcePath);
+      await mkdir(dirname(targetPath), { recursive: true });
+      await writeFile(targetPath, transform?.(relativePath, content) ?? content);
+    }),
+  );
+}
+
+async function hasEntries(dir: string): Promise<boolean> {
+  try {
+    const entries = await readdir(dir);
+    return entries.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function tryRunSyncScript(monorepoRoot: string, targetDir: string): Promise<boolean> {
+  const scriptPath = join(monorepoRoot, 'scripts', 'sync-skills.ts');
+  if (!(await exists(scriptPath))) {
+    return false;
+  }
+
+  const proc = Bun.spawn(['bun', 'run', scriptPath, targetDir], {
+    cwd: monorepoRoot,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+
+  const [, , exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  return exitCode === 0;
+}
+
+async function fallbackSyncCodexSkills(targetDir: string): Promise<void> {
+  const claudeSkillsDir = join(targetDir, '.claude', 'skills');
+  const codexSkillsDir = join(targetDir, '.codex', 'skills');
+
+  await rm(codexSkillsDir, { recursive: true, force: true });
+  await copyDirectory(claudeSkillsDir, codexSkillsDir, (relativePath, content) => {
+    if (!relativePath.endsWith('.md')) {
+      return content;
+    }
+
+    return transformClaudeSkillForCodex(content.toString('utf8'));
+  });
+}
+
+export async function syncSkills(targetDir: string, monorepoRoot: string = findMonorepoRoot()): Promise<void> {
+  const canonicalSkillsDir = join(monorepoRoot, '.claude', 'skills');
+  const targetClaudeSkillsDir = join(targetDir, '.claude', 'skills');
+  const targetCodexSkillsDir = join(targetDir, '.codex', 'skills');
+
+  await mkdir(targetClaudeSkillsDir, { recursive: true });
+  await rm(join(targetClaudeSkillsDir, '.gitkeep'), { force: true });
+  await copyDirectory(canonicalSkillsDir, targetClaudeSkillsDir);
+
+  const scriptSucceeded = await tryRunSyncScript(monorepoRoot, targetDir);
+  if (!scriptSucceeded || !(await hasEntries(targetCodexSkillsDir))) {
+    await fallbackSyncCodexSkills(targetDir);
+  }
+}