@forgeailab/spark 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# `spark` CLI
+
+The `spark` CLI manages feature packs in a project scaffolded with `create-spark`. Run it from your project root.
+
+## Install
+
+`spark` is invoked through Bun. Inside this monorepo:
+
+```bash
+bun packages/spark/src/cli.ts <command>
+```
+
+After publishing:
+
+```bash
+bunx spark <command>
+```
+
+A scaffolded project has `spark` available in scripts; in dev you can also alias it locally.
+
+## Commands
+
+### `list`
+
+Show all known packs grouped by category. Marks installed packs from `.spark/state.json` and shows scaffold compatibility.
+
+```bash
+spark list
+```
+
+### `info <pack>`
+
+Print everything the install would do — files touched, env vars added, deps installed, skills shipped, tasks seeded. Same surface as `add --dry-run` for a single pack.
+
+```bash
+spark info payments-stripe
+```
+
+For **hybrid** packs (those with a `[runtime_package]` block in their manifest), `info` also prints:
+
+- `Install mode: hybrid` (vs `copy` for the rest)
+- `Runtime helper: <package> (range <X>, resolved <Y>)` — the npm name + manifest version range + the version currently installed in the project's `package.json` (or `not installed`).
+
+For copy packs `info` prints `Install mode: copy` and omits the helper line.
+
+### `add <pack...> [--dry-run]`
+
+Resolve the requested packs against the registry + installed set + active scaffold, then apply. Idempotent: running it twice with the same args is a no-op.
+
+```bash
+spark add db-sqlite ui-shadcn
+spark add payments-stripe --dry-run
+```
+
+The resolver enforces:
+
+- **Closed capability enums.** `requires` / `provides` / `conflicts` reference pack-capability tags; `requires_runtime` references template-capability tags. Unknown values are rejected.
+- **Exclusivity.** Capabilities classified exclusive (`db`, `auth`, `payments`, `ui-kit`, `sync`) reject double-installs. Non-exclusive caps (`ai-sdk`, `analytics`, `email`, `blob-storage`, `e2e`, `deploy-target`, `local-runtime`) coexist.
+- **Scaffold compatibility.** A pack with `compatible_scaffolds = ["nextjs"]` refuses to install on a `vite-react` project.
+
+**Hybrid pack install.** When a pack declares `[runtime_package]`, the CLI adds the helper package to the same `bun add` batch as the pack's explicit runtime deps. Two resolution modes:
+
+- **Dev mode** — `SPARK_ROOT` is set and `${SPARK_ROOT}/libs/<helper>/` exists. The helper is linked via `file:` to the workspace path. Used by the reference app and `/tmp/spark-validate` smoke installs.
+- **Published mode** — otherwise. The helper is installed by `<npm-name>@<range>` from the manifest's `[runtime_package].version`.
+
+Either way the pack's `[dependencies].runtime` array MUST NOT also list the helper — the CLI handles it implicitly (see Decision 6 in the runtime-packages design doc).
+
+### `preset <name>`
+
+Apply a named bundle from `presets/<name>.toml`. Refuses if the active scaffold is not in the preset's `compatible_scaffolds`.
+
+```bash
+spark preset lean-saas
+```
+
+### `check`
+
+Audit `.spark/state.json` against the filesystem. Reports missing files, missing env vars in `.env.local`, deleted seeded tasks. For each installed **hybrid** pack, also verifies the helper package is still listed in the consumer's `package.json` (under `dependencies` or `devDependencies`) — surfaces a `drift: helper packages` section when a helper has been removed manually. **Does not repair.**
+
+```bash
+spark check
+```
+
+## What's not here
+
+- No `remove` / `uninstall` / `update`. v1 trusts git for reversal; `git revert` undoes a pack install.
+- No `post_install` / shell hooks in pack manifests — installs are fully declarative.
+
+## How state works
+
+`.spark/state.json` records, per installed pack: files written, env vars appended, tasks seeded. The CLI never deletes project files based on this — its sole purpose is drift detection via `check`.
+
+## See also
+
+- `docs/pack-spec.md` — writing a new pack
+- `templates/README.md` — registering a new scaffold template
+- `docs/spec/AGENTS.md` — spec-driven workflow contract

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@forgeailab/spark",
+  "version": "0.1.0",
+  "description": "CLI for managing feature packs in an spark-scaffolded project.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "bin": {
+    "spark": "./src/cli.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@forgeailab/spark-schema": "workspace:*",
+    "@forgeailab/spark-state": "workspace:*",
+    "@forgeailab/spark-skill-utils": "workspace:*",
+    "@forgeailab/spark-board": "workspace:*",
+    "@clack/prompts": "latest",
+    "citty": "latest",
+    "picocolors": "latest",
+    "smol-toml": "latest"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "latest"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env bun
+import { defineCommand, runMain } from 'citty';
+import { addCommand } from './commands/add.ts';
+import { checkCommand } from './commands/check.ts';
+import { infoCommand } from './commands/info.ts';
+import { listCommand } from './commands/list.ts';
+import { presetCommand } from './commands/preset.ts';
+
+const subCommands = {
+  list: listCommand,
+  info: infoCommand,
+  check: checkCommand,
+  add: addCommand,
+  preset: presetCommand,
+};
+
+const mainCommand = defineCommand({
+  meta: {
+    name: 'spark',
+    description: 'Composable spark scaffold pack manager',
+  },
+  subCommands,
+});
+
+function guardUnknownSubcommand(argv: readonly string[]): void {
+  const command = argv.find((arg) => !arg.startsWith('-'));
+  if (!command || Object.hasOwn(subCommands, command)) {
+    return;
+  }
+
+  if (command === 'remove' || command === 'uninstall' || command === 'update') {
+    console.error(
+      `unknown subcommand "${command}". spark does not support uninstall/update in v1; use git revert to undo a pack install.`,
+    );
+    process.exit(1);
+  }
+
+  console.error(`unknown subcommand "${command}".`);
+  process.exit(1);
+}
+
+if (import.meta.main) {
+  guardUnknownSubcommand(process.argv.slice(2));
+  await runMain(mainCommand);
+}
+
+export { mainCommand };

package/src/commands/add.ts

@@ -0,0 +1,367 @@
+import { confirm, isCancel } from '@clack/prompts';
+import { defineCommand } from 'citty';
+import pc from 'picocolors';
+import type { StateInstalledPack } from '@forgeailab/spark-schema';
+import { readConfig, type AppSkillsConfig } from '../config.ts';
+import {
+  resolveInstallPlan,
+  type InstallPlan,
+  type ResolverError,
+  type ResolverRegistry,
+  type ResolverTemplate,
+} from '../resolver.ts';
+import { applyFileOperations, preflightFileOperations, type FileApplyRecord } from '../io/files.ts';
+import { appendEnvVars } from '../io/env.ts';
+import { installDependencies, type DependencyRunner } from '../io/deps.ts';
+import { readRegistry, type Registry } from '../io/registry.ts';
+import { addInstalledPack, installedPackNames, readState, writeState } from '../io/state.ts';
+import { seedBoardTasks } from '../io/board.ts';
+import { copyPackSkills } from '../io/skills.ts';
+import { assertRuntimeHelperNotRedeclared, resolveRuntimeHelper } from '../runtime-package.ts';
+
+type AddOutput = Pick<Console, 'log' | 'error'>;
+
+export type AddOptions = {
+  projectRoot?: string;
+  dryRun?: boolean;
+  yes?: boolean;
+  registry?: Registry;
+  config?: AppSkillsConfig;
+  dependencyRunner?: DependencyRunner;
+  output?: AddOutput;
+};
+
+export type AddResult = {
+  status: 'already-installed' | 'dry-run' | 'installed';
+  plan: InstallPlan;
+};
+
+function formatResolverError(error: ResolverError): string {
+  if (error.type === 'missing-capability') {
+    const providers =
+      error.providers.length > 0 ? ` Providers: ${error.providers.join(', ')}` : ' No providers found.';
+    return `${error.pack} requires missing capability "${error.capability}".${providers}`;
+  }
+
+  if (error.type === 'exclusive-conflict') {
+    const suggestion =
+      error.source === 'exclusive-capability'
+        ? ' Use git reset or revert the existing pack install before choosing an alternative.'
+        : '';
+    return `${error.packs[0]} conflicts with ${error.packs[1]} on capability "${error.capability}".${suggestion}`;
+  }
+
+  if (error.type === 'scaffold-incompat') {
+    return `${error.pack} is not compatible with scaffold "${error.activeScaffold}". Compatible scaffolds: ${error.compatibleScaffolds.join(', ')}`;
+  }
+
+  if (error.type === 'runtime-incompat') {
+    return `${error.pack} requires runtime "${error.missingRuntime}", but scaffold "${error.activeScaffold}" provides: ${error.providedRuntime.join(', ')}`;
+  }
+
+  if (error.type === 'circular') {
+    return `Circular pack dependency detected: ${error.cycle.join(' -> ')}`;
+  }
+
+  return `Unknown pack: ${error.pack}`;
+}
+
+async function packRuntimeDependencies(plan: InstallPlan): Promise<string[]> {
+  const dependencies: string[] = [];
+
+  for (const pack of plan.packs) {
+    assertRuntimeHelperNotRedeclared(pack.name, pack.manifest);
+    dependencies.push(...(pack.manifest.dependencies?.runtime ?? []));
+
+    const helper = await resolveRuntimeHelper(pack.manifest);
+    if (helper) {
+      dependencies.push(helper);
+    }
+  }
+
+  return dependencies;
+}
+
+function packDevDependencies(plan: InstallPlan): string[] {
+  return plan.packs.flatMap((pack) => pack.manifest.dependencies?.dev ?? []);
+}
+
+function renderPlan(
+  plan: InstallPlan,
+  runtimeDependencies: readonly string[],
+  devDependencies: readonly string[],
+): string {
+  if (plan.packs.length === 0) {
+    return 'No packs to install.';
+  }
+
+  const lines = ['Install plan:'];
+  for (const pack of plan.packs) {
+    lines.push(`- ${pack.name}`);
+    for (const file of pack.manifest.files ?? []) {
+      lines.push(`  ${file.mode}: ${file.from} -> ${file.to}`);
+    }
+    for (const key of pack.manifest.env?.required ?? []) {
+      lines.push(`  env: ${key}`);
+    }
+    for (const skill of pack.manifest.skills?.copy ?? []) {
+      lines.push(`  skill: ${skill}`);
+    }
+    if (pack.manifest.tasks?.file) {
+      lines.push(`  tasks: ${pack.manifest.tasks.file}`);
+    }
+  }
+
+  if (runtimeDependencies.length > 0) {
+    lines.push(`runtime deps: ${[...new Set(runtimeDependencies)].sort().join(', ')}`);
+  }
+  if (devDependencies.length > 0) {
+    lines.push(`dev deps: ${[...new Set(devDependencies)].sort().join(', ')}`);
+  }
+
+  return lines.join('\n');
+}
+
+function activeTemplateFromRegistry(config: AppSkillsConfig, registry: Registry): ResolverTemplate {
+  const template = registry.templates.get(config.template);
+  if (!template) {
+    throw new Error(`Template "${config.template}" is not registered in the spark template registry.`);
+  }
+
+  if (template.manifest.status === 'planned') {
+    throw new Error(`Template "${config.template}" is planned; template not yet implemented.`);
+  }
+
+  return template.manifest;
+}
+
+async function preflightPlanFiles(
+  projectRoot: string,
+  registry: ResolverRegistry,
+  config: AppSkillsConfig,
+  plan: InstallPlan,
+): Promise<void> {
+  const createTargets = new Map<string, string>();
+
+  for (const pack of plan.packs) {
+    const entry = registry.packs.get(pack.name);
+    if (!entry?.dir) {
+      throw new Error(`Pack "${pack.name}" has no registry directory.`);
+    }
+
+    for (const operation of pack.manifest.files ?? []) {
+      if (operation.mode !== 'create') {
+        continue;
+      }
+
+      const existingPack = createTargets.get(operation.to);
+      if (existingPack) {
+        throw new Error(
+          `create mode conflict: ${pack.name} and ${existingPack} both target ${operation.to}`,
+        );
+      }
+      createTargets.set(operation.to, pack.name);
+    }
+
+    await preflightFileOperations({
+      projectRoot,
+      packRoot: entry.dir,
+      packName: pack.name,
+      config,
+      operations: pack.manifest.files ?? [],
+    });
+  }
+}
+
+function stateEntryForPack(
+  packName: string,
+  version: string,
+  fileRecords: readonly FileApplyRecord[],
+  envVars: readonly string[],
+  taskIds: readonly string[],
+  skillFiles: readonly string[],
+  touchedEnvFiles: readonly string[],
+): StateInstalledPack {
+  const fileTargets = [
+    ...fileRecords.map((record) => record.to),
+    ...skillFiles,
+    ...touchedEnvFiles,
+    ...(taskIds.length > 0 ? ['.ai/board.md'] : []),
+  ];
+
+  return {
+    name: packName,
+    version,
+    files: [...new Set(fileTargets)].sort(),
+    appended_blocks: fileRecords
+      .filter((record) => record.marker)
+      .map((record) => ({
+        to: record.to,
+        marker: record.marker ?? '',
+        content_hash: record.contentHash,
+      })),
+    env: [...new Set(envVars)].sort(),
+    tasks: [...new Set(taskIds)].sort(),
+  };
+}
+
+export async function runAdd(requestedPacks: readonly string[], options: AddOptions = {}): Promise<AddResult> {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const output = options.output ?? console;
+  const requested = requestedPacks.filter((pack) => pack.length > 0);
+
+  if (requested.length === 0) {
+    throw new Error('add requires at least one pack name');
+  }
+
+  const [config, registry, state] = await Promise.all([
+    options.config ? Promise.resolve(options.config) : readConfig(projectRoot),
+    options.registry ? Promise.resolve(options.registry) : readRegistry(projectRoot),
+    readState(projectRoot),
+  ]);
+  const activeTemplate = activeTemplateFromRegistry(config, registry);
+  const resolution = resolveInstallPlan(requested, installedPackNames(state), registry, activeTemplate);
+
+  if (!resolution.ok) {
+    throw new Error(formatResolverError(resolution.error));
+  }
+
+  const plan = resolution.data;
+  if (plan.packs.length === 0) {
+    output.log(`${requested.join(', ')} already installed`);
+    return {
+      status: 'already-installed',
+      plan,
+    };
+  }
+
+  const runtimeDependencies = await packRuntimeDependencies(plan);
+  const devDependencies = packDevDependencies(plan);
+
+  if (options.dryRun) {
+    output.log(renderPlan(plan, runtimeDependencies, devDependencies));
+    return {
+      status: 'dry-run',
+      plan,
+    };
+  }
+
+  if (!options.yes) {
+    const accepted = await confirm({
+      message: `Install ${plan.packs.map((pack) => pack.name).join(', ')}?`,
+      initialValue: false,
+    });
+
+    if (isCancel(accepted) || !accepted) {
+      throw new Error('Install cancelled');
+    }
+  }
+
+  await preflightPlanFiles(projectRoot, registry, config, plan);
+
+  let nextState = state;
+  const stateEntries: StateInstalledPack[] = [];
+  for (const pack of plan.packs) {
+    const entry = registry.packs.get(pack.name);
+    if (!entry?.dir) {
+      throw new Error(`Pack "${pack.name}" has no registry directory.`);
+    }
+
+    const fileRecords = await applyFileOperations({
+      projectRoot,
+      packRoot: entry.dir,
+      packName: pack.name,
+      config,
+      operations: pack.manifest.files ?? [],
+    });
+    const envVars = pack.manifest.env?.required ?? [];
+    const envResults = await appendEnvVars(projectRoot, envVars);
+    const touchedEnvFiles = envResults
+      .filter((result) => result.added.length > 0)
+      .map((result) => result.file);
+    const taskIds = await seedBoardTasks(
+      projectRoot,
+      pack.name,
+      entry.dir,
+      pack.manifest.tasks?.file,
+    );
+    const skillFiles = await copyPackSkills(
+      projectRoot,
+      entry.dir,
+      pack.manifest.skills?.copy ?? [],
+    );
+
+    stateEntries.push(
+      stateEntryForPack(
+        pack.name,
+        pack.manifest.version,
+        fileRecords,
+        envVars,
+        taskIds,
+        skillFiles,
+        touchedEnvFiles,
+      ),
+    );
+  }
+
+  await installDependencies(
+    projectRoot,
+    runtimeDependencies,
+    devDependencies,
+    options.dependencyRunner,
+  );
+
+  for (const entry of stateEntries) {
+    nextState = addInstalledPack(nextState, entry);
+  }
+  await writeState(projectRoot, nextState);
+
+  output.log(pc.green(`Installed ${plan.packs.map((pack) => pack.name).join(', ')}`));
+  return {
+    status: 'installed',
+    plan,
+  };
+}
+
+function parseAddArgs(rawArgs: readonly string[]): { packs: string[]; dryRun: boolean; yes: boolean } {
+  const packs: string[] = [];
+  let dryRun = false;
+  let yes = false;
+
+  for (const arg of rawArgs) {
+    if (arg === '--dry-run') {
+      dryRun = true;
+    } else if (arg === '--yes' || arg === '-y') {
+      yes = true;
+    } else if (!arg.startsWith('-')) {
+      packs.push(arg);
+    }
+  }
+
+  return { packs, dryRun, yes };
+}
+
+export const addCommand = defineCommand({
+  meta: {
+    name: 'add',
+    description: 'Install one or more spark packs',
+  },
+  args: {
+    dryRun: {
+      type: 'boolean',
+      description: 'Print the install plan without writing files',
+    },
+    yes: {
+      type: 'boolean',
+      alias: 'y',
+      description: 'Skip confirmation prompt',
+    },
+  },
+  async run() {
+    const parsed = parseAddArgs(process.argv.slice(3));
+    await runAdd(parsed.packs, {
+      dryRun: parsed.dryRun,
+      yes: parsed.yes,
+    });
+  },
+});

package/src/commands/check.ts

@@ -0,0 +1,166 @@
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { defineCommand } from 'citty';
+import pc from 'picocolors';
+import { readConfig, type AppSkillsConfig } from '../config.ts';
+import { missingBoardTasks } from '../io/board.ts';
+import { readRegistry, type Registry } from '../io/registry.ts';
+import { readState } from '../io/state.ts';
+import { installedRuntimeHelperSpecifier } from '../runtime-package.ts';
+
+type CheckOutput = Pick<Console, 'log' | 'error'>;
+
+export type DriftReport = {
+  missingFiles: string[];
+  missingEnv: string[];
+  missingTasks: string[];
+  missingHelpers: string[];
+};
+
+export type CheckOptions = {
+  config?: AppSkillsConfig;
+  registry?: Registry;
+};
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    const info = await stat(path);
+    return info.isFile();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function hasEnvVar(content: string, key: string): boolean {
+  return new RegExp(`^\\s*(?:export\\s+)?${escapeRegex(key)}\\s*=`, 'm').test(content);
+}
+
+async function readEnvLocal(projectRoot: string): Promise<string> {
+  try {
+    return await readFile(join(projectRoot, '.env.local'), 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return '';
+    }
+    throw error;
+  }
+}
+
+export async function runCheck(
+  projectRoot = process.cwd(),
+  output: CheckOutput = console,
+  options: CheckOptions = {},
+): Promise<DriftReport> {
+  const [, registry, state] = await Promise.all([
+    options.config ? Promise.resolve(options.config) : readConfig(projectRoot),
+    options.registry ? Promise.resolve(options.registry) : readRegistry(projectRoot),
+    readState(projectRoot),
+  ]);
+  const recordedFiles = [
+    ...new Set(state.installed_packs.flatMap((pack) => pack.files)),
+  ].sort();
+  const recordedEnv = [...new Set(state.installed_packs.flatMap((pack) => pack.env))].sort();
+  const recordedTasks = [...new Set(state.installed_packs.flatMap((pack) => pack.tasks))].sort();
+
+  const missingFiles: string[] = [];
+  for (const file of recordedFiles) {
+    if (!(await fileExists(join(projectRoot, file)))) {
+      missingFiles.push(file);
+    }
+  }
+
+  const envLocal = await readEnvLocal(projectRoot);
+  const missingEnv = recordedEnv.filter((key) => !hasEnvVar(envLocal, key));
+  const missingTasks = await missingBoardTasks(projectRoot, recordedTasks);
+  const missingHelpers: string[] = [];
+
+  for (const pack of state.installed_packs) {
+    const runtimePackage = registry.packs.get(pack.name)?.manifest.runtime_package;
+    if (!runtimePackage) {
+      continue;
+    }
+
+    if (!(await installedRuntimeHelperSpecifier(projectRoot, runtimePackage))) {
+      missingHelpers.push(
+        `${pack.name}: helper package ${runtimePackage.package} missing from package.json`,
+      );
+    }
+  }
+
+  if (
+    missingFiles.length === 0 &&
+    missingEnv.length === 0 &&
+    missingTasks.length === 0 &&
+    missingHelpers.length === 0
+  ) {
+    output.log(pc.green('OK: spark state matches the project filesystem.'));
+    return {
+      missingFiles,
+      missingEnv,
+      missingTasks,
+      missingHelpers,
+    };
+  }
+
+  output.error(pc.red('Drift detected. spark check does not repair files.'));
+  if (missingFiles.length > 0) {
+    output.error('drift: missing files');
+    for (const file of missingFiles) {
+      output.error(`  ${file}`);
+    }
+    output.error('suggestion: git restore the missing file or re-run the affected pack install');
+  }
+
+  if (missingEnv.length > 0) {
+    output.error('missing env');
+    for (const key of missingEnv) {
+      output.error(`  ${key}`);
+    }
+  }
+
+  if (missingTasks.length > 0) {
+    output.error('missing tasks');
+    for (const taskId of missingTasks) {
+      output.error(`  ${taskId}`);
+    }
+  }
+
+  if (missingHelpers.length > 0) {
+    output.error('drift: helper packages');
+    for (const helper of missingHelpers) {
+      output.error(`  ${helper}`);
+    }
+  }
+
+  return {
+    missingFiles,
+    missingEnv,
+    missingTasks,
+    missingHelpers,
+  };
+}
+
+export const checkCommand = defineCommand({
+  meta: {
+    name: 'check',
+    description: 'Report drift between state.json and the project filesystem',
+  },
+  async run() {
+    const report = await runCheck();
+    if (
+      report.missingFiles.length > 0 ||
+      report.missingEnv.length > 0 ||
+      report.missingTasks.length > 0 ||
+      report.missingHelpers.length > 0
+    ) {
+      process.exitCode = 1;
+    }
+  },
+});