@cosmic-labs/content-contract 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+
+/** A migration recorded after it has been safely applied to one site's content. */
+declare const MigrationLedgerEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    appliedAt: z.ZodString;
+    note: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    appliedAt: string;
+    note: string;
+}, {
+    id: string;
+    appliedAt: string;
+    note: string;
+}>;
+/**
+ * Checked-in intent for a site. Production truth is established separately by a
+ * deploy attestation; this manifest deliberately contains no credentials.
+ */
+declare const CapabilityManifestSchema: z.ZodObject<{
+    contractVersion: z.ZodString;
+    requestedCapabilities: z.ZodArray<z.ZodString, "many">;
+    projectId: z.ZodString;
+    dataset: z.ZodString;
+    envName: z.ZodString;
+    migrationLedger: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        appliedAt: z.ZodString;
+        note: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        appliedAt: string;
+        note: string;
+    }, {
+        id: string;
+        appliedAt: string;
+        note: string;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    contractVersion: string;
+    requestedCapabilities: string[];
+    projectId: string;
+    dataset: string;
+    envName: string;
+    migrationLedger: {
+        id: string;
+        appliedAt: string;
+        note: string;
+    }[];
+}, {
+    contractVersion: string;
+    requestedCapabilities: string[];
+    projectId: string;
+    dataset: string;
+    envName: string;
+    migrationLedger: {
+        id: string;
+        appliedAt: string;
+        note: string;
+    }[];
+}>;
+type MigrationLedgerEntry = z.infer<typeof MigrationLedgerEntrySchema>;
+type CapabilityManifest = z.infer<typeof CapabilityManifestSchema>;
+/** Metadata shape for the append-only registry; registry data is intentionally site-governed. */
+type BlockRegistryEntry = {
+    type: string;
+    introducedIn: string;
+    /** Present only for Portable Text object types rendered by Atlas. */
+    rendererCapability?: string;
+    migrationChain: string[];
+    retirementState: 'active' | 'deprecated' | 'retired';
+    examplesRef?: string;
+};
+/**
+ * Append-only registry for blocks shipped by Atlas. Removing an entry would
+ * erase the compatibility history that sites need to safely render old content.
+ */
+declare const blockRegistry: readonly BlockRegistryEntry[];
+/**
+ * Canonical JSON serializer for JSON-compatible values. Object keys are sorted
+ * by code point so its output does not depend on insertion order or runtime locale.
+ */
+declare function canonicalizeJson(value: unknown): string;
+/**
+ * Hash an unordered renderer capability set. Duplicate values and input order do
+ * not affect the SHA-256 hex result, making it safe to compare in attestations.
+ */
+declare function capabilityHash(capabilities: readonly string[]): string;
+
+export { type BlockRegistryEntry, type CapabilityManifest, CapabilityManifestSchema, type MigrationLedgerEntry, MigrationLedgerEntrySchema, blockRegistry, canonicalizeJson, capabilityHash };

package/dist/index.js

@@ -0,0 +1,118 @@
+// src/capabilities.ts
+import { createHash } from "crypto";
+import { z } from "zod";
+var MigrationLedgerEntrySchema = z.object({
+  id: z.string().min(1),
+  appliedAt: z.string().datetime(),
+  note: z.string().min(1)
+}).strict();
+var CapabilityManifestSchema = z.object({
+  contractVersion: z.string().min(1),
+  requestedCapabilities: z.array(z.string().min(1)),
+  projectId: z.string().min(1),
+  dataset: z.string().min(1),
+  envName: z.string().min(1),
+  migrationLedger: z.array(MigrationLedgerEntrySchema)
+}).strict();
+var blockRegistry = [
+  {
+    type: "statCallout",
+    introducedIn: "0.1.0",
+    rendererCapability: "statCallout",
+    migrationChain: [],
+    retirementState: "active"
+  },
+  {
+    type: "comparisonTable",
+    introducedIn: "0.1.0",
+    rendererCapability: "comparisonTable",
+    migrationChain: [],
+    retirementState: "active"
+  },
+  {
+    type: "editorialQuote",
+    introducedIn: "0.1.0",
+    rendererCapability: "editorialQuote",
+    migrationChain: [],
+    retirementState: "active"
+  },
+  {
+    type: "definitionBox",
+    introducedIn: "0.1.0",
+    rendererCapability: "definitionBox",
+    migrationChain: [],
+    retirementState: "active"
+  },
+  {
+    type: "checklistBox",
+    introducedIn: "0.1.0",
+    rendererCapability: "checklistBox",
+    migrationChain: [],
+    retirementState: "active"
+  },
+  {
+    type: "captionedImage",
+    introducedIn: "0.1.0",
+    rendererCapability: "captionedImage",
+    migrationChain: [],
+    retirementState: "active"
+  },
+  {
+    type: "botanicalDivider",
+    introducedIn: "0.1.0",
+    rendererCapability: "botanicalDivider",
+    migrationChain: [],
+    retirementState: "active"
+  },
+  {
+    type: "videoEmbed",
+    introducedIn: "0.1.0",
+    rendererCapability: "videoEmbed",
+    migrationChain: [],
+    retirementState: "active"
+  },
+  {
+    type: "fact",
+    introducedIn: "0.1.0",
+    migrationChain: [],
+    retirementState: "active"
+  }
+];
+function compareCodePoints(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+function canonicalizeJson(value) {
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError("Canonical JSON does not support non-finite numbers.");
+    }
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalizeJson).join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const record = value;
+    return `{${Object.keys(record).sort(compareCodePoints).map((key) => `${JSON.stringify(key)}:${canonicalizeJson(record[key])}`).join(",")}}`;
+  }
+  throw new TypeError(`Canonical JSON does not support ${typeof value} values.`);
+}
+function capabilityHash(capabilities) {
+  const normalized = [...new Set(capabilities.map((capability) => {
+    if (!capability) {
+      throw new TypeError("Capabilities must be non-empty strings.");
+    }
+    return capability;
+  }))].sort(compareCodePoints);
+  return createHash("sha256").update(canonicalizeJson(normalized), "utf8").digest("hex");
+}
+export {
+  CapabilityManifestSchema,
+  MigrationLedgerEntrySchema,
+  blockRegistry,
+  canonicalizeJson,
+  capabilityHash
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@cosmic-labs/content-contract",
+  "version": "0.1.0",
+  "description": "Versioned content contracts and capability manifests for Cosmic Atlas sites.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=22.14"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --target es2022",
+    "test": "vitest run --root ../.. --project content-contract --passWithNoTests",
+    "lint": "tsc --noEmit"
+  }
+}