@wzrdtech/core 0.2.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@wzrdtech/core",
+  "version": "0.2.0",
+  "private": false,
+  "description": "Core Zap recipe schema, planning, and registry utilities.",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gratitude5dee/Zap.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/gratitude5dee/Zap/issues"
+  },
+  "homepage": "https://zap.wzrd.tech",
+  "exports": {
+    ".": "./src/index.ts",
+    "./manifest": "./src/manifest.ts",
+    "./planner": "./src/planner.ts",
+    "./schema": "./src/schema.ts"
+  },
+  "dependencies": {
+    "yaml": "^2.8.1",
+    "zod": "4.4.3"
+  },
+  "engines": {
+    "node": "24.x"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./manifest.ts";
+export * from "./planner.ts";
+export * from "./schema.ts";

package/src/manifest.ts

@@ -0,0 +1,55 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+export type SkillManifestEntry = {
+  fileCount: number;
+  hash: string;
+  path: string;
+  skill: string;
+};
+
+export type SkillManifest = {
+  generatedAt: string;
+  skills: SkillManifestEntry[];
+  version: 1;
+};
+
+export async function generateSkillManifest(skillsDir: string): Promise<SkillManifest> {
+  const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+  const skills: SkillManifestEntry[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const root = path.join(skillsDir, entry.name);
+    const files = await listFiles(root);
+    const hash = createHash("sha256");
+    for (const file of files) {
+      const relative = path.relative(root, file);
+      hash.update(relative);
+      hash.update(await fs.readFile(file));
+    }
+    skills.push({
+      fileCount: files.length,
+      hash: hash.digest("hex"),
+      path: path.relative(process.cwd(), root),
+      skill: entry.name,
+    });
+  }
+
+  return {
+    generatedAt: new Date().toISOString(),
+    skills: skills.sort((left, right) => left.skill.localeCompare(right.skill)),
+    version: 1,
+  };
+}
+
+async function listFiles(root: string): Promise<string[]> {
+  const entries = await fs.readdir(root, { withFileTypes: true });
+  const files = await Promise.all(entries.map(async (entry) => {
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) return listFiles(fullPath);
+    return [fullPath];
+  }));
+  return files.flat().sort();
+}

package/src/planner.ts

@@ -0,0 +1,78 @@
+import type { ZapSpec, ZapStep } from "./schema.ts";
+
+export type PlannedZapStep = ZapStep & {
+  originalId: string;
+  repeatIndex?: number;
+};
+
+export type ZapPlan = {
+  budgetCapUsd: number;
+  estimateUsd: number;
+  extendCount: number;
+  steps: PlannedZapStep[];
+  zap: string;
+};
+
+const modelRates: Record<string, { perSecond?: number; perRequest?: number }> = {
+  "fal-ai/flux/dev": { perRequest: 0.03 },
+  "fal-ai/kling-video/v2.1/pro/image-to-video": { perSecond: 0.28 },
+  "fal-ai/veo3.1": { perSecond: 0.45 },
+  "gemini-omni-flash-preview": { perSecond: 0.1 },
+  "happyhorse-1.1-i2v": { perSecond: 0.28 },
+  "seedance-2-0-260128": { perSecond: 0.07 },
+  "seedance-2-0-260128-upscale": { perSecond: 0.056 },
+};
+
+export function planZapRun(zap: ZapSpec, extendCount: number): ZapPlan {
+  const steps = expandRepeatSteps(zap, extendCount);
+  const estimateUsd = steps.reduce((sum, step) => sum + quoteStep(step), 0);
+  return {
+    budgetCapUsd: zap.budget.cap_usd,
+    estimateUsd,
+    extendCount,
+    steps,
+    zap: zap.zap,
+  };
+}
+
+export function assertWithinBudget(plan: ZapPlan) {
+  if (plan.estimateUsd > plan.budgetCapUsd) {
+    throw new Error(`Run quote $${plan.estimateUsd.toFixed(2)} exceeds recipe cap $${plan.budgetCapUsd}.`);
+  }
+}
+
+export function validateRequiredInputs(zap: ZapSpec, inputs: Record<string, unknown>) {
+  for (const [name, spec] of Object.entries(zap.inputs)) {
+    if (spec.required && inputs[name] === undefined) {
+      throw new Error(`Missing required input ${name}.`);
+    }
+  }
+}
+
+export function isLocalStep(step: ZapStep) {
+  return step.kind === "stitch" || step.kind === "keyframes";
+}
+
+export function quoteStep(step: ZapStep) {
+  if (isLocalStep(step)) return 0;
+  const model = step.model ?? "local";
+  const rate = modelRates[model];
+  if (!rate) return 0;
+  if (rate.perRequest !== undefined) return rate.perRequest;
+  return (rate.perSecond ?? 0) * (step.duration_s ?? 1);
+}
+
+export function expandRepeatSteps(zap: ZapSpec, extendCount: number): PlannedZapStep[] {
+  return zap.steps.flatMap((step) => {
+    if (step.kind !== "video.extend") return [{ ...step, originalId: step.id }];
+    const max = step.repeat?.max ?? 64;
+    const min = step.repeat?.min ?? 0;
+    const count = Math.max(min, Math.min(extendCount, max));
+    return Array.from({ length: count }, (_, index) => ({
+      ...step,
+      id: `${step.id}_${index + 1}`,
+      originalId: step.id,
+      repeatIndex: index + 1,
+    }));
+  });
+}

package/src/schema.ts

@@ -0,0 +1,228 @@
+import { parseDocument } from "yaml";
+import { z } from "zod";
+
+export class ZapSchemaError extends Error {
+  readonly code = "SCHEMA_INVALID";
+  readonly retryable = false;
+}
+
+export const zapInputSchema = z.object({
+  hint: z.string().optional(),
+  label: z.string().optional(),
+  options: z.array(z.string()).optional(),
+  required: z.boolean().default(false),
+  type: z.enum(["string", "textarea", "image", "video", "select", "number"]),
+});
+
+export const zapStepKindSchema = z.enum([
+  "image.gen",
+  "image.edit",
+  "video.gen",
+  "video.extend",
+  "video.edit",
+  "video.upscale",
+  "audio.tts",
+  "audio.music",
+  "audio.sfx",
+  "keyframes",
+  "stitch",
+]);
+
+export const zapProviderSchema = z.enum(["gmi", "fal", "prodia", "runware"]);
+export type ZapProvider = z.infer<typeof zapProviderSchema>;
+
+export const zapStitchSchema = z.object({
+  engine: z.enum(["auto", "local", "hyperframes"]).default("auto"),
+  fps: z.number().int().min(1).max(120).optional(),
+  format: z.enum(["mp4", "webm"]).default("mp4"),
+  quality: z.enum(["draft", "standard", "high"]).default("standard"),
+}).default({ engine: "auto", format: "mp4", quality: "standard" });
+
+export const zapStepSchema = z.object({
+  audio: z.record(z.string(), z.unknown()).optional(),
+  candidates: z.number().int().min(1).max(16).optional(),
+  duration_s: z.number().positive().optional(),
+  extend: z.object({ mode: z.enum(["chain", "anchored"]).default("chain") }).optional(),
+  first_frame: z.record(z.string(), z.unknown()).optional(),
+  id: z.string().min(1),
+  inputs: z.array(z.string()).optional(),
+  judge: z.record(z.string(), z.unknown()).optional(),
+  keyframes: z.record(z.string(), z.unknown()).optional(),
+  kind: zapStepKindSchema,
+  model: z.string().optional(),
+  prompt: z.string().optional(),
+  provider: zapProviderSchema.optional(),
+  reference_images: z.array(z.string()).optional(),
+  repeat: z.object({
+    default: z.number().int().min(0).optional(),
+    max: z.number().int().min(0).max(64).optional(),
+    min: z.number().int().min(0).optional(),
+  }).optional(),
+  retry: z.object({
+    backoff_s: z.number().min(0).max(300).default(0),
+    fallback_model: z.string().optional(),
+    fallback_provider: zapProviderSchema.optional(),
+    max: z.number().int().min(0).max(8).default(0),
+  }).optional(),
+  rlhf: z.union([z.literal("optional"), z.boolean()]).optional(),
+  shared: z.boolean().optional(),
+  stitch: zapStitchSchema.optional(),
+  tier: z.enum(["draft", "final"]).optional(),
+});
+
+export const zapPublishSchema = z.object({
+  embed: z.object({
+    allowOrigins: z.array(z.string()).default(["*"]),
+    enabled: z.boolean().default(true),
+    height: z.number().int().min(240).max(2160).default(720),
+    theme: z.enum(["auto", "dark", "light"]).default("auto"),
+    width: z.number().int().min(240).max(3840).default(1280),
+  }).optional(),
+  slug: z.string().regex(/^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/).optional(),
+  visibility: z.enum(["public", "unlisted", "private"]).default("public"),
+}).partial().optional();
+
+export const zapSpecSchema = z.object({
+  budget: z.object({
+    cap_usd: z.number().positive(),
+    estimate_usd: z.number().nonnegative(),
+  }),
+  defaults: z.object({
+    aspect: z.string().optional(),
+    models: z.record(z.string(), z.string()).default(() => ({})),
+    provider: zapProviderSchema.default("gmi"),
+  }).default(() => ({ models: {}, provider: "gmi" as const })),
+  description: z.string(),
+  inputs: z.record(z.string(), zapInputSchema).default({}),
+  output: z.string().default("Zap.mp4"),
+  publish: zapPublishSchema,
+  steps: z.array(zapStepSchema).min(1),
+  version: z.literal(2),
+  zap: z.string().regex(/^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/),
+});
+
+export type ZapInput = z.infer<typeof zapInputSchema>;
+export type ZapStep = z.infer<typeof zapStepSchema>;
+export type ZapStepKind = z.infer<typeof zapStepKindSchema>;
+export type ZapSpec = z.infer<typeof zapSpecSchema>;
+export type PublicZapSpec = ZapSpec & { title: string };
+
+export function parseZapMarkdown(markdown: string): ZapSpec {
+  const frontmatter = extractFrontmatter(markdown);
+  const parsed = parseDocument(frontmatter).toJS();
+  const spec = zapSpecSchema.parse(parsed);
+  validateSpec(spec);
+  return spec;
+}
+
+export function validateZapPromptTemplates(spec: ZapSpec, promptContents: Record<string, string>) {
+  for (const step of spec.steps) {
+    const promptRef = step.prompt;
+    if (!promptRef || !isPromptFile(promptRef)) continue;
+    const content = promptContents[promptRef];
+    if (content === undefined) {
+      throw new ZapSchemaError(`Step ${step.id} references missing prompt file ${promptRef}.`);
+    }
+    validateTemplateVariables(spec, step.id, content);
+  }
+}
+
+export function publicZapSpec(spec: ZapSpec): PublicZapSpec {
+  return { ...spec, title: titleize(spec.zap) };
+}
+
+function extractFrontmatter(markdown: string) {
+  const match = markdown.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) {
+    throw new Error("Zap recipe is missing YAML frontmatter.");
+  }
+  return match[1];
+}
+
+function validateSpec(spec: ZapSpec) {
+  validateDuplicateStepIds(spec);
+  validateStepRefs(spec);
+  validateVideoDurations(spec);
+  validateInlineVariables(spec);
+}
+
+function validateInlineVariables(spec: ZapSpec) {
+  for (const step of spec.steps) {
+    const promptRef = step.prompt ?? "";
+    if (!isPromptFile(promptRef)) validateTemplateVariables(spec, step.id, promptRef);
+  }
+}
+
+function validateDuplicateStepIds(spec: ZapSpec) {
+  const seen = new Set<string>();
+  for (const step of spec.steps) {
+    if (seen.has(step.id)) throw new Error(`Duplicate step id ${step.id}.`);
+    seen.add(step.id);
+  }
+}
+
+function validateStepRefs(spec: ZapSpec) {
+  const declaredInputs = new Set(Object.keys(spec.inputs));
+  const priorSteps = new Set<string>();
+  for (const step of spec.steps) {
+    for (const ref of [...(step.inputs ?? []), ...(step.reference_images ?? [])]) {
+      validateRef({ declaredInputs, priorSteps, ref, stepId: step.id });
+    }
+    priorSteps.add(step.id);
+  }
+}
+
+function validateRef({
+  declaredInputs,
+  priorSteps,
+  ref,
+  stepId,
+}: {
+  declaredInputs: Set<string>;
+  priorSteps: Set<string>;
+  ref: string;
+  stepId: string;
+}) {
+  if (ref.startsWith("user.")) {
+    const inputName = ref.slice("user.".length);
+    if (declaredInputs.has(inputName)) return;
+    throw new ZapSchemaError(`Step ${stepId} references undeclared input ${ref}.`);
+  }
+
+  if (ref.endsWith(".*")) {
+    const prefix = ref.slice(0, -2);
+    if (priorSteps.has(prefix)) return;
+    throw new ZapSchemaError(`Step ${stepId} references unknown repeated step ${ref}.`);
+  }
+
+  if (priorSteps.has(ref) || declaredInputs.has(ref)) return;
+  throw new ZapSchemaError(`Step ${stepId} references unknown input or step ${ref}.`);
+}
+
+function validateVideoDurations(spec: ZapSpec) {
+  for (const step of spec.steps) {
+    if (step.kind.startsWith("video.") && step.duration_s === undefined) {
+      throw new ZapSchemaError(`Video step ${step.id} is missing duration_s.`);
+    }
+  }
+}
+
+function validateTemplateVariables(spec: ZapSpec, stepId: string, template: string) {
+  const declared = new Set(Object.keys(spec.inputs));
+  for (const variable of template.matchAll(/\{([A-Z0-9_]+)\}/g)) {
+    if (!declared.has(variable[1])) {
+      throw new ZapSchemaError(`Step ${stepId} references undeclared input {${variable[1]}}.`);
+    }
+  }
+}
+
+function isPromptFile(prompt: string) {
+  return prompt.endsWith(".md") || prompt.startsWith("prompts/");
+}
+
+function titleize(slug: string) {
+  return slug
+    .split("-")
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}