@forgeailab/spark-schema 0.1.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@forgeailab/spark-schema",
+  "version": "0.1.0",
+  "description": "Shared Zod schemas + TOML parsers for spark pack and template manifests.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": "./src/index.ts",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "smol-toml": "latest",
+    "zod": "latest"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "latest"
+  }
+}

package/src/capabilities.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+
+export const PACK_CAPABILITY_VALUES = [
+  'db',
+  'db-pg',
+  'auth',
+  'payments',
+  'email',
+  'ui-kit',
+  'local-runtime',
+  'deploy-target',
+  'e2e',
+  'ai-sdk',
+  'blob-storage',
+  'analytics',
+  'sync',
+] as const;
+
+export const TEMPLATE_CAPABILITY_VALUES = ['static', 'server', 'react', 'native', 'vue', 'svelte', 'mdx-content', 'edge-runtime'] as const;
+
+export const PackCapability = z.enum(PACK_CAPABILITY_VALUES);
+export type PackCapability = z.infer<typeof PackCapability>;
+
+export const TemplateCapability = z.enum(TEMPLATE_CAPABILITY_VALUES);
+export type TemplateCapability = z.infer<typeof TemplateCapability>;
+
+const templateCapabilityLookup: ReadonlySet<string> = new Set(TEMPLATE_CAPABILITY_VALUES);
+const capabilityOverlap = PACK_CAPABILITY_VALUES.filter((tag) => templateCapabilityLookup.has(tag));
+
+if (capabilityOverlap.length > 0) {
+  throw new Error(
+    `PackCapability and TemplateCapability must not overlap: ${capabilityOverlap.join(', ')}`,
+  );
+}
+
+export const EXCLUSIVE_CAPABILITIES: ReadonlySet<PackCapability> = new Set<PackCapability>([
+  'db',
+  'auth',
+  'payments',
+  'ui-kit',
+  'sync',
+]);
+
+export const NON_EXCLUSIVE_CAPABILITIES: ReadonlySet<PackCapability> = new Set<PackCapability>([
+  'ai-sdk',
+  'analytics',
+  'email',
+  'blob-storage',
+  'e2e',
+  'deploy-target',
+  'local-runtime',
+]);

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './capabilities.ts';
+export * from './pack.ts';
+export * from './parse.ts';
+export * from './preset.ts';
+export * from './state.ts';
+export * from './template.ts';

package/src/pack.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { PackCapability, TemplateCapability } from './capabilities.ts';
+
+const packNamePattern = /^[a-z][a-z0-9-]*$/;
+const npmPackageNamePattern =
+  /^(?=.{1,214}$)(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+const semverPattern =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+export const PackCategory = z.enum([
+  'db',
+  'auth',
+  'payments',
+  'email',
+  'ui',
+  'ai',
+  'infra',
+  'testing',
+  'deploy',
+  'analytics',
+  'storage',
+]);
+export type PackCategory = z.infer<typeof PackCategory>;
+
+export const FileMode = z.enum(['create', 'create-or-skip', 'append', 'merge-json', 'template']);
+export type FileMode = z.infer<typeof FileMode>;
+
+export const PackName = z.string().regex(packNamePattern, {
+  message: 'Pack names must match /^[a-z][a-z0-9-]*$/',
+});
+export type PackName = z.infer<typeof PackName>;
+
+export const SemverString = z.string().regex(semverPattern, {
+  message: 'Version must be a valid semver string',
+});
+
+export const PackDependenciesSchema = z
+  .object({
+    runtime: z.array(z.string().min(1)).optional(),
+    dev: z.array(z.string().min(1)).optional(),
+  })
+  .strict();
+
+export const PackEnvSchema = z
+  .object({
+    required: z.array(z.string().min(1)).optional(),
+    optional: z.array(z.string().min(1)).optional(),
+  })
+  .strict();
+
+export const PackFileOperationSchema = z
+  .object({
+    mode: FileMode,
+    from: z.string().min(1),
+    to: z.string().min(1),
+  })
+  .strict();
+
+export const PackSkillsSchema = z
+  .object({
+    copy: z.array(z.string().min(1)).optional(),
+  })
+  .strict();
+
+export const PackTasksSchema = z
+  .object({
+    file: z.string().min(1).optional(),
+  })
+  .strict();
+
+const RuntimePackageBlockSchema = z
+  .object({
+    package: z.string().regex(npmPackageNamePattern, {
+      message: 'Runtime package names must be valid npm package names',
+    }),
+    version: z.string().min(1),
+  })
+  .strict();
+
+export const PackManifestSchema = z
+  .object({
+    name: PackName,
+    version: SemverString,
+    category: PackCategory,
+    description: z.string().min(1).optional(),
+    provides: z.array(PackCapability),
+    requires: z.array(PackCapability),
+    conflicts: z.array(PackCapability),
+    requires_runtime: z.array(TemplateCapability),
+    compatible_scaffolds: z.array(z.string().min(1)).optional().default([]),
+    dependencies: PackDependenciesSchema.optional(),
+    env: PackEnvSchema.optional(),
+    files: z.array(PackFileOperationSchema).optional(),
+    skills: PackSkillsSchema.optional(),
+    tasks: PackTasksSchema.optional(),
+    runtime_package: RuntimePackageBlockSchema.optional(),
+  })
+  .strict();
+
+export type RuntimePackageBlock = z.infer<typeof RuntimePackageBlockSchema>;
+export type PackManifest = z.infer<typeof PackManifestSchema>;

package/src/parse.ts

@@ -0,0 +1,115 @@
+import { parse } from 'smol-toml';
+import { z } from 'zod';
+import { PackManifestSchema, type PackManifest } from './pack.ts';
+import { PresetManifestSchema, type PresetManifest } from './preset.ts';
+import { TemplateManifestSchema, type TemplateManifest } from './template.ts';
+
+export type ParseError = {
+  message: string;
+  issues?: string[];
+};
+
+export type Result<TData, TError> =
+  | {
+      ok: true;
+      data: TData;
+    }
+  | {
+      ok: false;
+      error: TError;
+    };
+
+const forbiddenPackKeys = [
+  'post_install',
+  'hooks',
+  'pre_add',
+  'pre_install',
+  'post_add',
+  'scripts',
+] as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function formatIssuePath(path: PropertyKey[]): string {
+  return path.length === 0 ? '<root>' : path.map(String).join('.');
+}
+
+function toParseError(error: unknown): ParseError {
+  if (error instanceof z.ZodError) {
+    return {
+      message: 'Manifest validation failed',
+      issues: error.issues.map((issue) => `${formatIssuePath(issue.path)}: ${issue.message}`),
+    };
+  }
+
+  if (error instanceof Error) {
+    return {
+      message: error.message,
+    };
+  }
+
+  return {
+    message: 'Unknown TOML parse error',
+  };
+}
+
+export function assertNoForbiddenPackFields(parsed: unknown): void {
+  if (!isRecord(parsed)) {
+    return;
+  }
+
+  for (const key of forbiddenPackKeys) {
+    if (Object.hasOwn(parsed, key)) {
+      throw new Error(
+        `Unsupported pack manifest field "${key}" is forbidden; pack installs are declarative and cannot run shell hooks.`,
+      );
+    }
+  }
+}
+
+export function parsePackToml(raw: string): Result<PackManifest, ParseError> {
+  try {
+    const parsed = parse(raw);
+    assertNoForbiddenPackFields(parsed);
+
+    return {
+      ok: true,
+      data: PackManifestSchema.parse(parsed),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: toParseError(error),
+    };
+  }
+}
+
+export function parseTemplateToml(raw: string): Result<TemplateManifest, ParseError> {
+  try {
+    return {
+      ok: true,
+      data: TemplateManifestSchema.parse(parse(raw)),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: toParseError(error),
+    };
+  }
+}
+
+export function parsePresetToml(raw: string): Result<PresetManifest, ParseError> {
+  try {
+    return {
+      ok: true,
+      data: PresetManifestSchema.parse(parse(raw)),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: toParseError(error),
+    };
+  }
+}

package/src/preset.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+const packNamePattern = /^[a-z][a-z0-9-]*$/;
+
+export const PresetManifestSchema = z
+  .object({
+    name: z
+      .string()
+      .regex(packNamePattern, {
+        message: 'Preset names must match /^[a-z][a-z0-9-]*$/',
+      })
+      .optional(),
+    description: z.string().min(1).optional(),
+    compatible_scaffolds: z.array(z.string().min(1)),
+    packs: z.array(
+      z.string().regex(packNamePattern, {
+        message: 'Pack names must match /^[a-z][a-z0-9-]*$/',
+      }),
+    ),
+  })
+  .strict();
+
+export type PresetManifest = z.infer<typeof PresetManifestSchema>;

package/src/state.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+
+export const StateAppendedBlockSchema = z
+  .object({
+    to: z.string().min(1),
+    marker: z.string().min(1),
+    content_hash: z.string().min(1).optional(),
+  })
+  .strict();
+
+export const StateInstalledPackSchema = z
+  .object({
+    name: z.string().min(1),
+    version: z.string().min(1),
+    files: z.array(z.string().min(1)).default([]),
+    appended_blocks: z.array(StateAppendedBlockSchema).default([]),
+    env: z.array(z.string().min(1)).default([]),
+    tasks: z.array(z.string().min(1)).default([]),
+  })
+  .strict();
+
+export const StateFileSchema = z
+  .object({
+    schema_version: z.literal(1),
+    installed_packs: z.array(StateInstalledPackSchema).default([]),
+  })
+  .strict();
+
+export type StateAppendedBlock = z.infer<typeof StateAppendedBlockSchema>;
+export type StateInstalledPack = z.infer<typeof StateInstalledPackSchema>;
+export type StateFile = z.infer<typeof StateFileSchema>;

package/src/template.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { TemplateCapability } from './capabilities.ts';
+
+const templateNamePattern = /^[a-z][a-z0-9-]*$/;
+
+export const TemplateStatus = z.enum(['stable', 'planned']);
+export type TemplateStatus = z.infer<typeof TemplateStatus>;
+
+export const TemplateManifestSchema = z
+  .object({
+    name: z.string().regex(templateNamePattern, {
+      message: 'Template names must match /^[a-z][a-z0-9-]*$/',
+    }),
+    status: TemplateStatus,
+    provides: z.array(TemplateCapability),
+    description: z.string().min(1),
+  })
+  .strict();
+
+export type TemplateManifest = z.infer<typeof TemplateManifestSchema>;