@soulcraft/kit-schema 2.0.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@soulcraft/kit-schema",
+  "version": "2.0.0",
+  "description": "Shared kit manifest schema for Soulcraft platform kits (Venue, Workshop, and future products)",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  },
+  "dependencies": {
+    "@soulcraft/theme": "^1.0.0",
+    "zod": "^4.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * @module @soulcraft/kit-schema
+ * @description Shared kit manifest schema for the Soulcraft platform ecosystem.
+ *
+ * This package defines the contract between Soulcraft platform products (Venue,
+ * Workshop) and the kits that configure them for specific verticals or use cases.
+ *
+ * ## What is a Kit?
+ *
+ * A kit is a directory containing:
+ * - `kit.json` — The manifest: metadata, feature flags, theme, experience types
+ * - `files/` — Template files (CMS content, email templates, waiver text)
+ * - `skills/` — AI skill definitions in SKILL.md format
+ *
+ * ## Key Exports
+ *
+ * - **Types** — `VenueKitConfig`, `KitManifest`, `VenueFeatures`, etc.
+ * - **Schemas** — Zod schemas for validating `kit.json` files
+ * - **Loader** — `loadKitFromDirectory()`, `loadVenueKit()`
+ * - **Skills** — `parseSkillFile()` for SKILL.md frontmatter parsing
+ * - **Variables** — `substituteVariables()` for `{{key}}` template substitution
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { loadVenueKit } from '@soulcraft/kit-schema';
+ *
+ * const kit = await loadVenueKit('./kits/wicks-and-whiskers');
+ * const { features, theme, experienceTypes } = kit.manifest.venue;
+ * ```
+ */
+
+export * from './types.js';
+export * from './schema.js';
+export * from './loader.js';
+export * from './skills.js';
+export * from './variables.js';

package/src/loader.ts

@@ -0,0 +1,183 @@
+/**
+ * @module @soulcraft/kit-schema/loader
+ * @description Kit manifest loader and directory validator for Soulcraft platform kits.
+ *
+ * This module provides the reference implementation for loading and validating kits
+ * from the filesystem. Platform applications (Venue, Workshop) use this to mount
+ * kits at startup.
+ *
+ * The loader:
+ * 1. Reads `kit.json` from the kit directory
+ * 2. Validates it against the Zod schema
+ * 3. Discovers and parses all SKILL.md files in `skills/`
+ * 4. Returns a fully typed {@link LoadedKit} with manifest + skills
+ *
+ * @example
+ * ```ts
+ * import { loadKitFromDirectory } from '@soulcraft/kit-schema/loader';
+ *
+ * const kit = await loadKitFromDirectory('/app/kits/wicks-and-whiskers');
+ * console.log(kit.manifest.name); // 'Wicks & Whiskers'
+ * console.log(kit.skills.length); // 4
+ * ```
+ */
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { KitManifestSchema } from './schema.js';
+import { parseSkillFile } from './skills.js';
+import type { KitManifest, ParsedSkill, SoulcraftKitConfig, VenueKitConfig } from './types.js';
+
+/**
+ * A fully loaded and validated kit, ready for use by the platform.
+ */
+export interface LoadedKit {
+	/** Validated and typed kit manifest from `kit.json`. */
+	manifest: KitManifest;
+	/** All SKILL.md files discovered and parsed from `skills/`. */
+	skills: ParsedSkill[];
+	/** Resolved absolute path to the kit directory root. */
+	kitDir: string;
+}
+
+/**
+ * A fully loaded Venue kit with the manifest narrowed to {@link VenueKitConfig}.
+ */
+export interface LoadedVenueKit extends LoadedKit {
+	manifest: VenueKitConfig;
+}
+
+/**
+ * A fully loaded unified Soulcraft kit with the manifest narrowed to {@link SoulcraftKitConfig}.
+ */
+export interface LoadedSoulcraftKit extends LoadedKit {
+	manifest: SoulcraftKitConfig;
+}
+
+/**
+ * Load and validate a kit from its directory on the filesystem.
+ *
+ * Reads `kit.json`, validates it with the Zod schema, then discovers all
+ * `skills/{name}/SKILL.md` files and parses their frontmatter.
+ *
+ * @param kitDir - Absolute path to the kit directory (must contain `kit.json`).
+ * @returns A {@link LoadedKit} with validated manifest and parsed skills.
+ * @throws {Error} If `kit.json` is missing, invalid JSON, or fails schema validation.
+ * @throws {Error} If any SKILL.md file has malformed frontmatter.
+ *
+ * @example
+ * ```ts
+ * const kit = await loadKitFromDirectory('/app/kits/wicks-and-whiskers');
+ * ```
+ */
+export async function loadKitFromDirectory(kitDir: string): Promise<LoadedKit> {
+	const manifestPath = join(kitDir, 'kit.json');
+
+	let rawManifest: unknown;
+	try {
+		const content = await readFile(manifestPath, 'utf-8');
+		rawManifest = JSON.parse(content);
+	} catch (err) {
+		const message = err instanceof SyntaxError
+			? `kit.json at ${manifestPath} is not valid JSON: ${err.message}`
+			: `Could not read kit.json at ${manifestPath}: ${String(err)}`;
+		throw new Error(message);
+	}
+
+	// Strip the JSON Schema $schema key — it's an editor hint, not part of the kit spec.
+	if (rawManifest !== null && typeof rawManifest === 'object' && '$schema' in rawManifest) {
+		const { $schema: _, ...rest } = rawManifest as Record<string, unknown>;
+		rawManifest = rest;
+	}
+
+	const result = KitManifestSchema.safeParse(rawManifest);
+	if (!result.success) {
+		const formatted = result.error.issues
+			.map((issue) => `  ${issue.path.join('.')}: ${issue.message}`)
+			.join('\n');
+		throw new Error(`Invalid kit manifest at ${manifestPath}:\n${formatted}`);
+	}
+
+	const skills = await loadSkillsFromDirectory(kitDir);
+
+	return {
+		manifest: result.data,
+		skills,
+		kitDir
+	};
+}
+
+/**
+ * Load and validate a Venue kit, narrowing the manifest type to {@link VenueKitConfig}.
+ *
+ * Also accepts `type: 'soulcraft'` kits that declare a `venue` config block —
+ * these are valid Venue kits in the unified kit system. The manifest is returned
+ * as-is (typed as `VenueKitConfig` for backward compatibility), so callers must
+ * check `manifest.type === 'soulcraft'` and access `manifest.venue` directly when
+ * they need the venue config.
+ *
+ * @param kitDir - Absolute path to the Venue kit directory.
+ * @returns A {@link LoadedVenueKit} with a narrowed manifest type, or a
+ *   {@link LoadedSoulcraftKit} when the kit is `type: 'soulcraft'`.
+ * @throws {Error} If the loaded kit is not a Venue or Soulcraft kit.
+ *
+ * @example
+ * ```ts
+ * const kit = await loadVenueKit('/app/kits/wicks-and-whiskers');
+ * if (kit.manifest.type === 'venue') {
+ *   const { features } = kit.manifest.venue;
+ * } else if (kit.manifest.type === 'soulcraft') {
+ *   const { features } = kit.manifest.venue ?? {};
+ * }
+ * ```
+ */
+export async function loadVenueKit(kitDir: string): Promise<LoadedVenueKit | LoadedSoulcraftKit> {
+	const kit = await loadKitFromDirectory(kitDir);
+	if (kit.manifest.type === 'venue') {
+		return kit as LoadedVenueKit;
+	}
+	if (kit.manifest.type === 'soulcraft') {
+		return kit as LoadedSoulcraftKit;
+	}
+	throw new Error(
+		`Expected a Venue or Soulcraft kit at ${kitDir} but found type: "${kit.manifest.type}"`
+	);
+}
+
+/**
+ * Discover and parse all SKILL.md files in a kit's `skills/` subdirectory.
+ *
+ * Scans for files matching `skills/{name}/SKILL.md`. Non-matching files and
+ * directories without a `SKILL.md` are silently skipped.
+ *
+ * @param kitDir - Absolute path to the kit directory root.
+ * @returns Array of parsed skills. Empty array if the `skills/` directory does not exist.
+ */
+async function loadSkillsFromDirectory(kitDir: string): Promise<ParsedSkill[]> {
+	const skillsDir = join(kitDir, 'skills');
+
+	try {
+		const skillsStat = await stat(skillsDir);
+		if (!skillsStat.isDirectory()) return [];
+	} catch {
+		return [];
+	}
+
+	const skills: ParsedSkill[] = [];
+	const entries = await readdir(skillsDir, { withFileTypes: true });
+
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const skillPath = join(skillsDir, entry.name, 'SKILL.md');
+
+		try {
+			const content = await readFile(skillPath, 'utf-8');
+			const skill = parseSkillFile(content, skillPath);
+			skills.push(skill);
+		} catch {
+			// SKILL.md does not exist or failed to parse — skip this entry
+		}
+	}
+
+	return skills;
+}