@caretcms/zod 0.1.0

package/README.md

@@ -0,0 +1,34 @@
+# @caretcms/zod
+
+Derive [CaretCMS](https://github.com/web-stacked/caretcms) Studio schemas from the Zod schemas you already have.
+
+CaretCMS's Studio consumes plain JSON Schema, and `@caretcms/core` stays deliberately Zod-agnostic (zero runtime deps). If you already describe a content collection with Zod — e.g. in Astro's `content.config.ts` — this helper turns that one source into the JSON-Schema map you hand to `caret({ schemas })`, so field definitions, labels, and widget hints live in a single place.
+
+```sh
+npm install @caretcms/zod zod
+```
+
+```js
+// astro.config.mjs
+import caret from '@caretcms/core';
+import { schemasFromZod } from '@caretcms/zod';
+import { blogSchema, pageSchema } from './src/schemas.mjs';
+
+export default defineConfig({
+  integrations: [
+    caret({ schemas: schemasFromZod({ blog: blogSchema, page: pageSchema }) }),
+  ],
+});
+```
+
+What the conversion does beyond `z.toJSONSchema`:
+
+- **Dates** (`z.date()` / `z.coerce.date()`) become `{ type: "string", format: "date" }` so the Studio renders a date widget.
+- **`description` → `title`**: Zod `.describe("Headline")` becomes the field's Studio label (an explicit `title` wins; `description` is kept).
+- **`override` hook** for per-node tweaks: `schemaFromZod(schema, { override: ({ jsonSchema }) => { … } })`.
+
+API: `schemaFromZod(zodObjectSchema, options?)` for one collection, `schemasFromZod({ name: schema, … }, options?)` for the whole map.
+
+Requires Zod v4 (peer dependency, uses `z.toJSONSchema`). Nothing here is imported by `@caretcms/core` — its Zod-agnostic boundary stays intact.
+
+MIT © CaretCMS contributors

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @caretcms/zod — derive CaretCMS Studio schemas from your Zod content-collection schemas.
+ *
+ * CaretCMS's Studio consumes plain JSON Schema, and `@caretcms/core` stays
+ * deliberately Zod-agnostic (zero runtime deps). If you already describe a
+ * content collection with Zod (Astro's `content.config.ts`), this helper turns
+ * that ONE source into the JSON-Schema map you hand to `caret({ schemas })` — so
+ * field definitions, labels, and widget hints live in a single place instead of
+ * being duplicated in a hand-written `caret.schemas` file.
+ *
+ *   import { schemasFromZod } from "@caretcms/zod";
+ *   caret({ schemas: schemasFromZod({ blog: blogSchema, page: pageSchema }) });
+ *
+ * Requires Zod v4 (uses `z.toJSONSchema`). Zod is a PEER dependency; nothing here
+ * is imported by `@caretcms/core`, preserving its Zod-agnostic boundary.
+ */
+import { z } from "zod";
+/** A JSON Schema object node. Structurally what core's `CollectionSchema`
+ *  expects: `{ type: "object", properties: { ... } }`. */
+export type JsonSchema = Record<string, unknown>;
+export interface DeriveOptions {
+    /** Extra per-node tweaks, applied AFTER the built-in date handling. Use this to
+     *  map project-specific Zod shapes to CaretCMS widget `format` hints. */
+    override?: (ctx: {
+        zodSchema: unknown;
+        jsonSchema: JsonSchema;
+    }) => void;
+}
+/**
+ * Convert ONE Zod object schema into a CaretCMS-ready JSON Schema.
+ *
+ * Bridges the gaps a raw `z.toJSONSchema` leaves for the Studio:
+ *  - `z.date()` / `z.coerce.date()` → `{ type: "string", format: "date" }`.
+ *    (Raw conversion throws "Date cannot be represented in JSON Schema" — the
+ *    stored value is an ISO string, so a string with a date widget is correct.)
+ *  - `description` → `title`, so each field gets a friendly label.
+ *  - Custom widget hints (`image`, `html`, …) travel via `.meta({ format: "…" })`.
+ *
+ * Throws if the schema is not a Zod object — a collection schema must be an object.
+ */
+export declare function schemaFromZod(schema: z.ZodType, options?: DeriveOptions): JsonSchema;
+/**
+ * Convert a map of `collectionName -> Zod object schema` into the
+ * `Record<string, JsonSchema>` you pass to `caret({ schemas })`.
+ */
+export declare function schemasFromZod(schemas: Record<string, z.ZodType>, options?: DeriveOptions): Record<string, JsonSchema>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;0DAC0D;AAC1D,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,MAAM,WAAW,aAAa;IAC5B;6EACyE;IACzE,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE,KAAK,IAAI,CAAC;CAC1E;AAwBD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,OAAO,GAAE,aAAkB,GAAG,UAAU,CAuBxF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAClC,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAM5B"}

package/dist/index.js

@@ -0,0 +1,84 @@
+/**
+ * @caretcms/zod — derive CaretCMS Studio schemas from your Zod content-collection schemas.
+ *
+ * CaretCMS's Studio consumes plain JSON Schema, and `@caretcms/core` stays
+ * deliberately Zod-agnostic (zero runtime deps). If you already describe a
+ * content collection with Zod (Astro's `content.config.ts`), this helper turns
+ * that ONE source into the JSON-Schema map you hand to `caret({ schemas })` — so
+ * field definitions, labels, and widget hints live in a single place instead of
+ * being duplicated in a hand-written `caret.schemas` file.
+ *
+ *   import { schemasFromZod } from "@caretcms/zod";
+ *   caret({ schemas: schemasFromZod({ blog: blogSchema, page: pageSchema }) });
+ *
+ * Requires Zod v4 (uses `z.toJSONSchema`). Zod is a PEER dependency; nothing here
+ * is imported by `@caretcms/core`, preserving its Zod-agnostic boundary.
+ */
+import { z } from "zod";
+function isObjectSchema(node) {
+    return node.type === "object" && typeof node.properties === "object" && node.properties !== null;
+}
+/**
+ * Promote Zod `description` → JSON Schema `title` (the Studio renders `title` as
+ * the field label). Recurses into nested object properties and array items.
+ * Non-destructive: an explicit `title` wins, and `description` is left intact.
+ */
+function promoteTitles(node) {
+    if (!node || typeof node !== "object")
+        return;
+    if (typeof node.description === "string" && typeof node.title !== "string") {
+        node.title = node.description;
+    }
+    const props = node.properties;
+    if (props && typeof props === "object") {
+        for (const child of Object.values(props))
+            promoteTitles(child);
+    }
+    const items = node.items;
+    if (items && typeof items === "object")
+        promoteTitles(items);
+}
+/**
+ * Convert ONE Zod object schema into a CaretCMS-ready JSON Schema.
+ *
+ * Bridges the gaps a raw `z.toJSONSchema` leaves for the Studio:
+ *  - `z.date()` / `z.coerce.date()` → `{ type: "string", format: "date" }`.
+ *    (Raw conversion throws "Date cannot be represented in JSON Schema" — the
+ *    stored value is an ISO string, so a string with a date widget is correct.)
+ *  - `description` → `title`, so each field gets a friendly label.
+ *  - Custom widget hints (`image`, `html`, …) travel via `.meta({ format: "…" })`.
+ *
+ * Throws if the schema is not a Zod object — a collection schema must be an object.
+ */
+export function schemaFromZod(schema, options = {}) {
+    const json = z.toJSONSchema(schema, {
+        unrepresentable: "any",
+        io: "input",
+        override: (ctx) => {
+            const def = ctx.zodSchema?._zod?.def;
+            if (def?.type === "date") {
+                ctx.jsonSchema.type = "string";
+                ctx.jsonSchema.format = "date";
+            }
+            options.override?.(ctx);
+        },
+    });
+    delete json.$schema;
+    promoteTitles(json);
+    if (!isObjectSchema(json)) {
+        throw new Error("@caretcms/zod: each collection schema must be a Zod object (z.object({ ... })).");
+    }
+    return json;
+}
+/**
+ * Convert a map of `collectionName -> Zod object schema` into the
+ * `Record<string, JsonSchema>` you pass to `caret({ schemas })`.
+ */
+export function schemasFromZod(schemas, options = {}) {
+    const out = {};
+    for (const [collection, schema] of Object.entries(schemas)) {
+        out[collection] = schemaFromZod(schema, options);
+    }
+    return out;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,SAAS,cAAc,CAAC,IAAgB;IACtC,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI,CAAC;AACnG,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,IAAgB;IACrC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO;IAC9C,IAAI,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC3E,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC;IAChC,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,UAAoD,CAAC;IACxE,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;YAAE,aAAa,CAAC,KAAK,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAA+B,CAAC;IACnD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,aAAa,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,MAAiB,EAAE,UAAyB,EAAE;IAC1E,MAAM,IAAI,GAAG,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE;QAClC,eAAe,EAAE,KAAK;QACtB,EAAE,EAAE,OAAO;QACX,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE;YAChB,MAAM,GAAG,GAAI,GAAG,CAAC,SAAoD,EAAE,IAAI,EAAE,GAAG,CAAC;YACjF,IAAI,GAAG,EAAE,IAAI,KAAK,MAAM,EAAE,CAAC;gBACzB,GAAG,CAAC,UAAU,CAAC,IAAI,GAAG,QAAQ,CAAC;gBAC/B,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,MAAM,CAAC;YACjC,CAAC;YACD,OAAO,CAAC,QAAQ,EAAE,CAAC,GAAqD,CAAC,CAAC;QAC5E,CAAC;KACF,CAAe,CAAC;IAEjB,OAAO,IAAI,CAAC,OAAO,CAAC;IACpB,aAAa,CAAC,IAAI,CAAC,CAAC;IAEpB,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,iFAAiF,CAClF,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAkC,EAClC,UAAyB,EAAE;IAE3B,MAAM,GAAG,GAA+B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3D,GAAG,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@caretcms/zod",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Derive CaretCMS Studio schemas from your Zod content-collection schemas — single source of truth.",
+  "license": "MIT",
+  "keywords": [
+    "astro",
+    "cms",
+    "caret",
+    "zod",
+    "json-schema",
+    "content-collections"
+  ],
+  "homepage": "https://github.com/web-stacked/caretcms/tree/main/packages/zod#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/web-stacked/caretcms.git",
+    "directory": "packages/zod"
+  },
+  "bugs": {
+    "url": "https://github.com/web-stacked/caretcms/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "25.6.0",
+    "typescript": "6.0.3",
+    "zod": "4.4.3"
+  }
+}