@warpgogol/werkstatt-shared 0.2.0

package/src/ontology/schemas/capability.ts

@@ -0,0 +1,104 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0288: the closed capability catalog record schema — one YAML file per
+AI-agent-invocable action (packages/werkstatt-site/src/domain/ontology/capabilities/*.yaml). The
+input/output shape is a deliberately closed JSON-Schema subset chosen for
+lossless projection to both OpenAPI (RFC-0289) and MCP tool schemas (RFC-0290).
+</purpose>
+<non-goals>
+  <item>Do not resolve entitlements or active-capability logic here — that is
+        @warpgogol/werkstatt-shared/share/agent/capability.ts (resolveActiveCapabilities).</item>
+  <item>Do not widen the JSON-Schema subset beyond what OpenAPI + MCP both
+        accept verbatim — widening requires an RFC amending RFC-0288.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0288: initial capability record schema.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+/** Localized string map: language code → string. At least one entry required. */
+const localizedStringSchema = z
+  .record(z.string().min(1), z.string().min(1))
+  .refine((v) => Object.keys(v).length > 0, { message: "must declare at least one language" });
+
+const capabilityPropertySchema = z
+  .object({
+    type: z.enum(["string", "boolean", "integer"]),
+    format: z.enum(["email", "uuid", "uri", "date"]).optional(),
+    minLength: z.number().int().nonnegative().optional(),
+    maxLength: z.number().int().positive().optional(),
+  })
+  .strict();
+
+/**
+ * RFC-0288: the closed JSON-Schema subset. Deliberately small — every field
+ * here must be losslessly projectable to an OpenAPI 3.1 schema object AND an
+ * MCP tool inputSchema verbatim, with no transformation.
+ */
+export const capabilityInputOutputSchema = z
+  .object({
+    type: z.literal("object"),
+    required: z.array(z.string().min(1)).optional(),
+    additionalProperties: z.literal(false),
+    properties: z.record(z.string().min(1), capabilityPropertySchema),
+  })
+  .strict()
+  .refine((schema) => (schema.required ?? []).every((key) => key in schema.properties), {
+    message: "required[] entries must all exist in properties",
+  });
+
+export type CapabilityInputOutputSchema = z.infer<typeof capabilityInputOutputSchema>;
+
+const capabilityIntegrationSchema = z
+  .object({
+    eventKind: z.enum(["lead", "message", "appointment"]),
+    source: z.literal("agent"),
+  })
+  .strict();
+
+const capabilityRequiresSchema = z
+  .object({
+    entitlements: z.array(z.string().min(1)).default([]),
+    sections: z.array(z.string().min(1)).default([]),
+  })
+  .strict();
+
+const capabilityHumanEquivalentSchema = z
+  .object({
+    sectionType: z.string().min(1),
+  })
+  .strict();
+
+const capabilityLimitsSchema = z
+  .object({
+    perMinutePerIp: z.number().int().positive(),
+    maxPayloadBytes: z.number().int().positive(),
+  })
+  .strict();
+
+/** RFC-0288: one capability catalog record (packages/werkstatt-site/src/domain/ontology/capabilities/<id>.yaml). */
+export const capabilityRecordSchema = z
+  .object({
+    /** Dot-separated, lowercase; the file stem MUST equal this id. */
+    id: z
+      .string()
+      .regex(/^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/, "id must be dot-separated lowercase"),
+    /** Integer; bump on breaking input/output change (by RFC). */
+    version: z.number().int().positive(),
+    kind: z.literal("action"),
+    title: localizedStringSchema,
+    description: localizedStringSchema,
+    input: capabilityInputOutputSchema,
+    output: capabilityInputOutputSchema,
+    integration: capabilityIntegrationSchema,
+    requires: capabilityRequiresSchema,
+    humanEquivalent: capabilityHumanEquivalentSchema,
+    limits: capabilityLimitsSchema,
+  })
+  .strict();
+
+export type CapabilityRecord = z.infer<typeof capabilityRecordSchema>;

package/src/ontology/schemas/constellation.ts

@@ -0,0 +1,114 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Zod schema for Constellation definition files (packages/werkstatt-site/src/domain/ontology/constellations/*.yaml).
+A Constellation is a named, reusable composition pattern — an ordered sequence of
+section archetypes that forms a proven page structure for a given intent
+(DNA-23, RFC-0025).
+</purpose>
+<non-goals>
+  <item>Do not parse YAML here; the caller is responsible for parsing.</item>
+  <item>Do not add rendering or runtime logic.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Wave 1 (RFC-0025): Initial creation.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+import { planetNameSchema } from "../cosmic/planet-catalog.ts";
+import { starNameSchema } from "../cosmic/star-catalog.ts";
+
+// ---------------------------------------------------------------------------
+// Constellation slot schema
+// ---------------------------------------------------------------------------
+
+/**
+ * One step in the constellation sequence — references a section archetype by
+ * its cosmicName (PlanetName) and states why it appears at that position.
+ */
+export const constellationSlotSchema = z.object({
+  /**
+   * The section cosmicName that occupies this position.
+   * **Exactly ONE Planet per slot.** If a constellation accepts more than one
+   * archetype at a given narrative position (e.g. "DNA-style feature list" OR
+   * "approach-style card grid"), model it as TWO separate slots, each marked
+   * `optional: true`. Do NOT introduce arrays/unions here — schema simplicity
+   * is the contract. See packages/AGENTS.md "Constellation slots".
+   * Must reference a value from PlanetCatalog.
+   */
+  cosmicName: planetNameSchema,
+
+  /**
+   * Human-readable label for this slot in documentation / tooling output.
+   * Example: "Value proposition hero", "Social proof band"
+   */
+  label: z.string().min(1),
+
+  /**
+   * Why this section appears at this position in the sequence.
+   * Describes the conversion / trust / narrative logic.
+   */
+  rationale: z.string().min(1),
+
+  /**
+   * When true, this slot is optional — the constellation is still valid
+   * without it. Validators warn but do not fail on missing optional slots.
+   * Default: false.
+   */
+  optional: z.boolean().optional().default(false),
+});
+
+export type ConstellationSlot = z.infer<typeof constellationSlotSchema>;
+
+// ---------------------------------------------------------------------------
+// Constellation schema
+// ---------------------------------------------------------------------------
+
+/**
+ * A Constellation definition — a named, reusable page-composition pattern.
+ * Stored as packages/werkstatt-site/src/domain/ontology/constellations/<slug>.yaml.
+ */
+export const constellationSchema = z.object({
+  /**
+   * Stable kebab-case identifier for this constellation.
+   * Used as the reference key in system.yaml `constellations[]`.
+   * Example: "nonprofit-donation-funnel"
+   */
+  id: z
+    .string()
+    .regex(/^[a-z][a-z0-9-]*$/, "id must be kebab-case (lowercase letters, digits, hyphens)"),
+
+  /**
+   * Display name for tooling, docs, and the Cosmic Passport map.
+   * Example: "Nonprofit Donation Funnel"
+   */
+  name: z.string().min(1),
+
+  /**
+   * One-sentence description of the pattern's purpose and audience.
+   */
+  description: z.string().min(1),
+
+  /**
+   * The star (page) archetype this constellation is designed for.
+   * Ensures the composition pattern is matched to the right page layer.
+   */
+  forStar: starNameSchema,
+
+  /**
+   * Ordered sequence of section slots composing this constellation.
+   * Position is meaningful — validators check order compliance when
+   * constellation.compose.validate is run.
+   */
+  slots: z.array(constellationSlotSchema).min(1),
+
+  /**
+   * Semantic version of this constellation definition.
+   * Increment minor when slots are added; major when order changes.
+   */
+  version: z.string().regex(/^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/i, "version must be valid semver"),
+});
+
+export type Constellation = z.infer<typeof constellationSchema>;

package/src/ontology/schemas/dns-records.ts

@@ -0,0 +1,53 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0753: Zod schema for DNS record declaration files (systems-cache/<id>/dns-records.yaml).
+Defines the canonical structure for version-controlled DNS record declarations
+that are synced to Cloudflare via the dns.record.* command family.
+</purpose>
+<non-goals>
+  <item>Do not define Cloudflare API response shapes — those live in the API client.</item>
+  <item>Do not include private key material — only public TXT values are declared.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0753: initial DNS record declaration schema — dnsRecordTypeSchema, dnsRecordDeclarationSchema, dnsRecordFileSchema.</item>
+  <item>RFC-0786: add ttl?: number field to dnsRecordDeclarationSchema for DNS-AID records.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const dnsRecordTypeSchema = z.enum([
+  "A",
+  "AAAA",
+  "CNAME",
+  "MX",
+  "TXT",
+  "SRV",
+  "CAA",
+  "SVCB",
+  "HTTPS",
+]);
+
+export const dnsRecordDeclarationSchema = z.object({
+  name: z.string().min(1),
+  type: dnsRecordTypeSchema,
+  content: z.string(),
+  priority: z.number().int().min(0).max(65535).optional(),
+  proxied: z.boolean().optional().default(false),
+  ttl: z.number().int().min(1).max(86400).optional(),
+  comment: z.string().optional(),
+});
+
+export const dnsRecordFileSchema = z.object({
+  kind: z.literal("dns-records"),
+  schemaVersion: z.literal(1),
+  zone: z.string().min(1),
+  updatedAt: z.string(),
+  records: z.array(dnsRecordDeclarationSchema),
+});
+
+export type DnsRecordType = z.infer<typeof dnsRecordTypeSchema>;
+export type DnsRecordDeclaration = z.infer<typeof dnsRecordDeclarationSchema>;
+export type DnsRecordFile = z.infer<typeof dnsRecordFileSchema>;

package/src/ontology/schemas/index.ts

@@ -0,0 +1,95 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Barrel export for @warpgogol/werkstatt-shared/ontology/schemas sub-path.
+Re-exports the Constellation, Biome, SiteFamily, and SystemManifest schemas and types.
+</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Wave 1 (RFC-0025): Initial creation.</item>
+  <item>RFC-0071: Re-export site-family contract and expanded biome surface.</item>
+  <item>RFC-0371: Re-export biome font entry schema and types.</item>
+  <item>Architecture review 2026-07-10: extracted platform operations schemas to @warpgogol/werkstatt-shared/ontology/operations; re-export getSectionPropsSchema from manifest-resolver.ts.</item>
+</CHANGE_SUMMARY>
+*/
+
+export { constellationSchema, constellationSlotSchema } from "./constellation.ts";
+export type { Constellation, ConstellationSlot } from "./constellation.ts";
+
+export {
+  biomeSchema,
+  biomeAxesSchema,
+  biomeConstraintsSchema,
+  biomeFontEntrySchema,
+  biomeFontsSchema,
+  biomeGeometrySchema,
+  biomeMotionSchema,
+  biomePaletteSchema,
+  biomeProvenanceSchema,
+  biomeSiteBackgroundSchema,
+  biomeSpacingSchema,
+  biomeTypographySchema,
+} from "./biome.ts";
+export type {
+  Biome,
+  BiomeAxes,
+  BiomeConstraints,
+  BiomeFontEntry,
+  BiomeFontsConfig,
+  BiomeGeometry,
+  BiomeMotion,
+  BiomePalette,
+  BiomeProvenance,
+  BiomeSiteBackground,
+  BiomeSpacing,
+  BiomeTypography,
+} from "./biome.ts";
+
+export {
+  SiteFamilyContract,
+  siteFamilyDetectionSchema,
+  siteFamilyRecipeSchema,
+  siteFamilySchema,
+} from "./site-family.ts";
+export type { SiteFamily, SiteFamilyDetection, SiteFamilyRecipe } from "./site-family.ts";
+
+export { sectionArchetypeSchema } from "./section-archetype.ts";
+export type {
+  SectionArchetypeContract,
+  SectionArchetypeId,
+  SectionArchetypeLayoutHint,
+} from "./section-archetype.ts";
+
+export { systemManifestSchema } from "./system.ts";
+export type { SystemManifest, SystemPagePin, SystemPlanetPin } from "./system.ts";
+
+// Architecture review 2026-07-10: Re-export growthVendorSchema for @warpgogol/werkstatt-site/growth/config.ts.
+export { growthVendorSchema } from "./system.ts";
+export type { GrowthVendor } from "./system.ts";
+
+export { PageEntrySchema, BlockEntrySchema } from "./page-entry.ts";
+export type { PageEntry, BlockEntry } from "./page-entry.ts";
+// getSectionPropsSchema is NOT re-exported here — it lives in manifest-resolver.ts
+// which imports node:fs/promises. Re-exporting it from this barrel pulls Node-only
+// modules into the Vite client bundle (growth/config.ts imports growthVendorSchema
+// from this barrel). Node-side consumers import from
+// @warpgogol/werkstatt-shared/ontology/schemas/manifest-resolver directly.
+
+// RFC-0288: Agent Surface closed capability catalog record.
+export { capabilityInputOutputSchema, capabilityRecordSchema } from "./capability.ts";
+export type { CapabilityInputOutputSchema, CapabilityRecord } from "./capability.ts";
+
+// RFC-0753: DNS record declaration file schema
+export {
+  dnsRecordTypeSchema,
+  dnsRecordDeclarationSchema,
+  dnsRecordFileSchema,
+} from "./dns-records.ts";
+export type { DnsRecordType, DnsRecordDeclaration, DnsRecordFile } from "./dns-records.ts";
+
+// Platform operations schemas (handoff, sternsystem, werkstatt, mission,
+// release, leitstand, notausgang, materialization, artifact-store,
+// naming-policy) have been extracted to @warpgogol/werkstatt-shared/ontology/operations.

package/src/ontology/schemas/manifest-resolver.ts

@@ -0,0 +1,123 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Manifest resolver: reads section/component manifest YAML from packages/ui/src
+and returns the composed propsSchema for a given cosmicName. Concentrates all
+filesystem I/O, YAML parsing, and fragment composition behind one interface.
+</purpose>
+<non-goals>
+  <item>Do not define Zod schemas here — pure resolution and I/O.</item>
+  <item>Do not validate cross-system.yaml references — that is page.block.validate's job.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Architecture review 2026-07-10: extracted from page-entry.ts to separate declarative schemas from runtime I/O.</item>
+  <item>RFC-0484: suppress console.debug for directories without manifests — group directories are expected to have none.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { sectionManifestSchema } from "../manifest.ts";
+import { composeManifestPropsSchema } from "../shared-section-props/index.ts";
+
+/**
+ * Reads the manifest YAML for the section assigned to `planetName` and returns
+ * its `propsSchema` (JSON Schema object) along with the section's `semanticId`
+ * and current `version`.
+ *
+ * Returns null when no manifest is found for the given planet name, or when
+ * the manifest has no `propsSchema` declared.
+ *
+ * @param cosmicName — PlanetCatalog or passport-reserved MoonCatalog name
+ * @param packagesUiRoot — absolute path to packages/ui/src (for locating manifests)
+ *
+ * Usage (in page.block.validate):
+ * ```ts
+ * const schema = await getSectionPropsSchema("Europa", "/workspace/packages/ui/src");
+ * ```
+ */
+export async function getSectionPropsSchema(
+  cosmicName: string,
+  packagesUiRoot: string,
+): Promise<{
+  propsSchema: Record<string, unknown>;
+  semanticId: string;
+  version: string;
+} | null> {
+  // Scan section AND component manifests — the five PASSPORT-RESERVED moons
+  // resolve to component manifests (passport components are invoked as
+  // page-blocks on cosmic/passport and cosmic/star-map routes — RFC-0028).
+  const candidates: Array<{ dir: string; layer: "sections" | "components" }> = [];
+  for (const layer of ["sections", "components"] as const) {
+    const layerDir = join(packagesUiRoot, layer);
+    try {
+      const entries = await readdir(layerDir);
+      for (const e of entries) candidates.push({ dir: e, layer });
+    } catch (err) {
+      console.debug(
+        `[manifest-resolver] ${layerDir} not readable — skipping (${err instanceof Error ? err.message : String(err)})`,
+      );
+    }
+  }
+
+  for (const { dir, layer } of candidates) {
+    const layerSuffix = layer === "sections" ? "-section" : "-component";
+    const layerDir = join(packagesUiRoot, layer);
+    const manifestPath = join(layerDir, dir, `${dir}${layerSuffix}.manifest.yaml`);
+    const manifestPathAlt = join(layerDir, dir, `${dir}.manifest.yaml`);
+
+    let raw: string | null = null;
+    try {
+      raw = await readFile(manifestPath, "utf8");
+    } catch {
+      try {
+        raw = await readFile(manifestPathAlt, "utf8");
+      } catch {
+        // No manifest file found for this directory — expected for group
+        // directories (effects, section-body, seo) that contain sub-components
+        // but are not components themselves. Skip silently (RFC-0484).
+        continue;
+      }
+    }
+
+    if (!raw) continue;
+
+    let parsed: unknown;
+    try {
+      parsed = parseYaml(raw);
+    } catch (err) {
+      console.debug(
+        `[manifest-resolver] YAML parse failed for ${dir}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      continue;
+    }
+
+    const result = sectionManifestSchema.safeParse(parsed);
+    if (!result.success) continue;
+
+    if (result.data.cosmicName === cosmicName) {
+      const compose = result.data.propsSchemaCompose;
+      const local = result.data.propsSchema;
+
+      // RFC-0101 + RFC-0102 + RFC-0103: when the manifest declares
+      // propsSchemaCompose, merge the referenced shared fragments before
+      // validation. A manifest without either field disables strict prop
+      // validation (existing behaviour preserved).
+      if (!compose && !local) return null;
+
+      const composed = composeManifestPropsSchema({
+        compose,
+        local: local as Record<string, unknown> | undefined,
+      });
+      return {
+        propsSchema: composed,
+        semanticId: result.data.semanticId,
+        version: result.data.version,
+      };
+    }
+  }
+
+  return null;
+}