@forgeailab/spark 0.1.3 → 0.2.0

package/src/internal/skill-utils.ts

@@ -0,0 +1,233 @@
+type FrontmatterBlockMap = Map<string, string[]>;
+
+const rawBlocksSymbol = Symbol.for('@forgeailab/spark-skill-utils.rawBlocks');
+const requiredFrontmatterKeys = ['name', 'description'] as const;
+const codexFrontmatterKeys = ['name', 'description', 'model'] as const;
+
+type FrontmatterWithBlocks = Record<string, unknown> & {
+  [rawBlocksSymbol]?: FrontmatterBlockMap;
+};
+
+export type ParsedSkillMarkdown = {
+  frontmatter: Record<string, unknown>;
+  body: string;
+};
+
+function hasOwn(record: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+
+function attachRawBlocks<T extends Record<string, unknown>>(
+  frontmatter: T,
+  blocks: FrontmatterBlockMap,
+): T {
+  Object.defineProperty(frontmatter, rawBlocksSymbol, {
+    value: blocks,
+    enumerable: false,
+  });
+
+  return frontmatter;
+}
+
+function rawBlocks(frontmatter: Record<string, unknown>): FrontmatterBlockMap | undefined {
+  return (frontmatter as FrontmatterWithBlocks)[rawBlocksSymbol];
+}
+
+function splitFrontmatter(source: string): { frontmatter: string; body: string } {
+  const normalized = source.replace(/\r\n/g, '\n');
+  const lines = normalized.split('\n');
+
+  if (lines[0] !== '---') {
+    throw new Error('SKILL.md must start with YAML frontmatter');
+  }
+
+  const closingIndex = lines.findIndex((line, index) => index > 0 && line === '---');
+  if (closingIndex === -1) {
+    throw new Error('SKILL.md frontmatter is missing a closing --- delimiter');
+  }
+
+  return {
+    frontmatter: lines.slice(1, closingIndex).join('\n'),
+    body: lines.slice(closingIndex + 1).join('\n'),
+  };
+}
+
+function parseScalar(value: string): unknown {
+  const trimmed = value.trim();
+
+  if (trimmed === 'true') {
+    return true;
+  }
+
+  if (trimmed === 'false') {
+    return false;
+  }
+
+  return trimmed;
+}
+
+function parseBlockValue(lines: string[]): unknown {
+  const [firstLine, ...rest] = lines;
+  const valueStart = firstLine.indexOf(':') + 1;
+  const firstValue = firstLine.slice(valueStart);
+
+  if (rest.length === 0) {
+    return parseScalar(firstValue);
+  }
+
+  if (
+    firstValue.trim() === '' &&
+    rest.every((line) => line.trim() === '' || /^\s*-\s+/u.test(line))
+  ) {
+    return rest
+      .filter((line) => line.trim() !== '')
+      .map((line) => parseScalar(line.replace(/^\s*-\s+/u, '')));
+  }
+
+  return [firstValue.trim(), ...rest].join('\n');
+}
+
+function parseFrontmatterBlocks(frontmatter: string): Record<string, unknown> {
+  const blocks: FrontmatterBlockMap = new Map();
+  const parsed: Record<string, unknown> = {};
+  let currentKey: string | undefined;
+
+  for (const line of frontmatter.split('\n')) {
+    const match = /^([A-Za-z][A-Za-z0-9_-]*):(.*)$/u.exec(line);
+
+    if (match) {
+      currentKey = match[1];
+      if (blocks.has(currentKey)) {
+        throw new Error(`Duplicate frontmatter key: ${currentKey}`);
+      }
+      blocks.set(currentKey, [`${currentKey}:${match[2]}`]);
+      continue;
+    }
+
+    if (!currentKey) {
+      if (line.trim() === '' || line.trim().startsWith('#')) {
+        continue;
+      }
+      throw new Error(`Unexpected frontmatter line before a key: ${line}`);
+    }
+
+    blocks.get(currentKey)?.push(line);
+  }
+
+  for (const key of requiredFrontmatterKeys) {
+    if (!blocks.has(key)) {
+      throw new Error(`Missing required frontmatter key: ${key}`);
+    }
+  }
+
+  for (const [key, lines] of blocks) {
+    parsed[key] = parseBlockValue(lines);
+  }
+
+  return attachRawBlocks(parsed, blocks);
+}
+
+function copyRawBlock(
+  source: FrontmatterBlockMap | undefined,
+  target: FrontmatterBlockMap,
+  key: string,
+): void {
+  const block = source?.get(key);
+  if (block) {
+    target.set(key, [...block]);
+  }
+}
+
+function assertRequiredFrontmatter(frontmatter: Record<string, unknown>): void {
+  for (const key of requiredFrontmatterKeys) {
+    if (!hasOwn(frontmatter, key)) {
+      throw new Error(`Missing required frontmatter key: ${key}`);
+    }
+  }
+}
+
+function serializeScalar(value: unknown): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  return String(value);
+}
+
+function serializeKeyValue(key: string, value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return [`${key}:`, ...value.map((item) => `  - ${serializeScalar(item)}`)];
+  }
+
+  if (typeof value === 'string' && value.includes('\n')) {
+    const [firstLine, ...rest] = value.split('\n');
+    return [`${key}: ${firstLine}`, ...rest];
+  }
+
+  return [`${key}: ${serializeScalar(value)}`];
+}
+
+export function parseSkillFrontmatter(source: string): ParsedSkillMarkdown {
+  const { frontmatter, body } = splitFrontmatter(source);
+
+  return {
+    frontmatter: parseFrontmatterBlocks(frontmatter),
+    body,
+  };
+}
+
+export function toCodexFrontmatter(claude: Record<string, unknown>): Record<string, unknown> {
+  assertRequiredFrontmatter(claude);
+
+  const sourceBlocks = rawBlocks(claude);
+  const codex: Record<string, unknown> = {};
+  const codexBlocks: FrontmatterBlockMap = new Map();
+
+  for (const key of codexFrontmatterKeys) {
+    if (!hasOwn(claude, key)) {
+      continue;
+    }
+
+    codex[key] = claude[key];
+    copyRawBlock(sourceBlocks, codexBlocks, key);
+  }
+
+  return attachRawBlocks(codex, codexBlocks);
+}
+
+export function toClaudeFrontmatter(codex: Record<string, unknown>): Record<string, unknown> {
+  assertRequiredFrontmatter(codex);
+
+  const sourceBlocks = rawBlocks(codex);
+  const claude: Record<string, unknown> = {};
+  const claudeBlocks: FrontmatterBlockMap = new Map();
+
+  for (const key of Object.keys(codex)) {
+    claude[key] = codex[key];
+    copyRawBlock(sourceBlocks, claudeBlocks, key);
+  }
+
+  return attachRawBlocks(claude, claudeBlocks);
+}
+
+export function serializeSkillFrontmatter(
+  frontmatter: Record<string, unknown>,
+  options: { trailingComments?: readonly string[] } = {},
+): string {
+  const blocks = rawBlocks(frontmatter);
+  const output: string[] = [];
+
+  for (const key of Object.keys(frontmatter)) {
+    const block = blocks?.get(key);
+    if (block) {
+      output.push(...block);
+      continue;
+    }
+
+    output.push(...serializeKeyValue(key, frontmatter[key]));
+  }
+
+  output.push(...(options.trailingComments ?? []));
+
+  return output.join('\n');
+}

package/src/internal/state.ts

@@ -0,0 +1,89 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { StateFileSchema, type StateFile, type StateInstalledPack } from '@forgeailab/spark-schema';
+
+function stateFilePath(projectRoot: string): string {
+  return join(projectRoot, '.spark', 'state.json');
+}
+
+function initialState(): StateFile {
+  return StateFileSchema.parse({
+    schema_version: 1,
+  });
+}
+
+function uniqueSorted(values: readonly string[]): string[] {
+  return [...new Set(values)].sort();
+}
+
+function normalizeInstalledPack(pack: StateInstalledPack): StateInstalledPack {
+  return {
+    ...pack,
+    files: uniqueSorted(pack.files),
+    appended_blocks: [...pack.appended_blocks].sort((left, right) =>
+      `${left.to}:${left.marker}`.localeCompare(`${right.to}:${right.marker}`),
+    ),
+    env: uniqueSorted(pack.env),
+    tasks: uniqueSorted(pack.tasks),
+  };
+}
+
+function normalizeState(state: StateFile): StateFile {
+  const parsed = StateFileSchema.parse(state);
+
+  return {
+    schema_version: 1,
+    installed_packs: [...parsed.installed_packs]
+      .map(normalizeInstalledPack)
+      .sort((left, right) => left.name.localeCompare(right.name)),
+  };
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function parseStateFile(path: string, raw: string): StateFile {
+  try {
+    return normalizeState(StateFileSchema.parse(JSON.parse(raw)));
+  } catch (error) {
+    throw new Error(`Failed to parse state file at ${path}: ${errorMessage(error)}`, {
+      cause: error,
+    });
+  }
+}
+
+export async function readState(projectRoot: string): Promise<StateFile> {
+  const path = stateFilePath(projectRoot);
+  let raw: string;
+
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return initialState();
+    }
+    throw error;
+  }
+
+  return parseStateFile(path, raw);
+}
+
+export async function writeState(projectRoot: string, state: StateFile): Promise<void> {
+  const path = stateFilePath(projectRoot);
+  const parsed = normalizeState(state);
+
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`);
+}
+
+export async function withState(
+  projectRoot: string,
+  mutator: (state: StateFile) => StateFile | Promise<StateFile>,
+): Promise<StateFile> {
+  const current = await readState(projectRoot);
+  const next = normalizeState(await mutator(current));
+
+  await writeState(projectRoot, next);
+  return next;
+}

package/src/io/board.ts

@@ -3,20 +3,20 @@ import { join, resolve, sep } from 'node:path';
 import {
   BoardTaskStatus,
   seedTasks as seedPackageTasks,
-} from '@forgeailab/spark-board';
+} from '../internal/board';
 
 export {
   BoardTaskStatus,
   readBoard,
   seedTasks,
   updateStatus,
-} from '@forgeailab/spark-board';
+} from '../internal/board';
 export type {
   Board,
   BoardEpic,
   BoardTask as ParsedBoardTask,
   SeedTask,
-} from '@forgeailab/spark-board';
+} from '../internal/board';
 
 export type BoardTask = {
   id: string;

package/src/io/skills.ts

@@ -4,7 +4,7 @@ import {
   parseSkillFrontmatter,
   serializeSkillFrontmatter,
   toCodexFrontmatter,
-} from '@forgeailab/spark-skill-utils';
+} from '../internal/skill-utils';
 
 type SkillCopyRecord = {
   claudeFiles: string[];

package/src/io/state.ts

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
 import { StateFileSchema, type StateFile, type StateInstalledPack } from '@forgeailab/spark-schema';
-export { readState, writeState, withState } from '@forgeailab/spark-state';
+export { readState, writeState, withState } from '../internal/state';
 
 export function emptyState(): StateFile {
   return StateFileSchema.parse({

package/src/runtime-package.ts

@@ -1,132 +0,0 @@
-import { readFile, stat } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
-import type { PackManifest } from '@forgeailab/spark-schema';
-
-type RuntimePackage = NonNullable<PackManifest['runtime_package']>;
-
-type PackageJson = {
-  dependencies?: Record<string, string>;
-  devDependencies?: Record<string, string>;
-};
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function stringRecord(value: unknown): Record<string, string> | undefined {
-  if (!isRecord(value)) {
-    return undefined;
-  }
-
-  const entries = Object.entries(value).filter(
-    (entry): entry is [string, string] => typeof entry[1] === 'string',
-  );
-  return Object.fromEntries(entries);
-}
-
-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 helperDirectoryName(packageName: string): string {
-  return packageName.split('/').at(-1) ?? packageName;
-}
-
-function packageNameFromSpecifier(specifier: string): string {
-  const trimmed = specifier.trim();
-  if (trimmed.startsWith('@')) {
-    const slashIndex = trimmed.indexOf('/');
-    if (slashIndex === -1) {
-      return trimmed;
-    }
-
-    const versionIndex = trimmed.indexOf('@', slashIndex + 1);
-    return versionIndex === -1 ? trimmed : trimmed.slice(0, versionIndex);
-  }
-
-  const versionIndex = trimmed.indexOf('@');
-  return versionIndex === -1 ? trimmed : trimmed.slice(0, versionIndex);
-}
-
-async function readPackageJson(projectRoot: string): Promise<PackageJson> {
-  let raw: string;
-  try {
-    raw = await readFile(join(projectRoot, 'package.json'), 'utf8');
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-      return {};
-    }
-    throw error;
-  }
-
-  const parsed = JSON.parse(raw) as unknown;
-  if (!isRecord(parsed)) {
-    return {};
-  }
-
-  return {
-    dependencies: stringRecord(parsed.dependencies),
-    devDependencies: stringRecord(parsed.devDependencies),
-  };
-}
-
-export function assertRuntimeHelperNotRedeclared(packName: string, manifest: PackManifest): void {
-  const runtimePackage = manifest.runtime_package;
-  if (!runtimePackage) {
-    return;
-  }
-
-  const duplicate = (manifest.dependencies?.runtime ?? []).find(
-    (specifier) => packageNameFromSpecifier(specifier) === runtimePackage.package,
-  );
-  if (!duplicate) {
-    return;
-  }
-
-  throw new Error(
-    `${packName} declares runtime helper ${runtimePackage.package} in both [runtime_package] and [dependencies].runtime (${duplicate}). Decision 6 requires declaring the helper only in [runtime_package].`,
-  );
-}
-
-export async function resolveRuntimeHelper(manifest: PackManifest): Promise<string | undefined> {
-  const runtimePackage = manifest.runtime_package;
-  if (!runtimePackage) {
-    return undefined;
-  }
-
-  const sparkRoot = process.env.SPARK_ROOT?.trim();
-  if (sparkRoot) {
-    const helperDir = resolve(sparkRoot, 'libs', helperDirectoryName(runtimePackage.package));
-    if (await fileExists(join(helperDir, 'package.json'))) {
-      return `file:${helperDir}`;
-    }
-  }
-
-  return `${runtimePackage.package}@${runtimePackage.version}`;
-}
-
-export async function installedRuntimeHelperSpecifier(
-  projectRoot: string,
-  runtimePackage: RuntimePackage,
-): Promise<string | undefined> {
-  const packageJson = await readPackageJson(projectRoot);
-  return (
-    packageJson.dependencies?.[runtimePackage.package] ??
-    packageJson.devDependencies?.[runtimePackage.package]
-  );
-}
-
-export async function formatResolvedRuntimeHelper(
-  projectRoot: string,
-  runtimePackage: RuntimePackage,
-): Promise<string> {
-  return (await installedRuntimeHelperSpecifier(projectRoot, runtimePackage)) ?? 'not installed';
-}