@mezzanine-stack/cms-core 0.1.0

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@mezzanine-stack/cms-core",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@mezzanine-stack/content-schema": "0.1.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import * as api from "./index.js";
+
+describe("public api exports", () => {
+  it("exports serializer functions", () => {
+    expect(typeof api.serializeMarkdown).toBe("function");
+    expect(typeof api.deserializeMarkdown).toBe("function");
+    expect(typeof api.serializeJson).toBe("function");
+    expect(typeof api.deserializeJson).toBe("function");
+  });
+});

package/src/index.ts

@@ -0,0 +1,25 @@
+// cms-core 公開 API
+
+// 型定義
+export type {
+  FieldValues,
+  CatalogEntry,
+  EntryModel,
+  SaveResult,
+  AssetItem,
+  GitProvider,
+} from "./types.js";
+
+// Markdown シリアライザ
+export {
+  serializeMarkdown,
+  deserializeMarkdown,
+  type MarkdownParseResult,
+} from "./serializer/markdown.js";
+
+// JSON シリアライザ
+export {
+  serializeJson,
+  deserializeJson,
+  type JsonParseResult,
+} from "./serializer/json.js";

package/src/serializer/json.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it } from "vitest";
+import {
+  boolean,
+  date,
+  file,
+  image,
+  list,
+  object,
+  relation,
+  richText,
+  select,
+  text,
+} from "@mezzanine-stack/content-schema";
+import { deserializeJson, serializeJson } from "./json.js";
+
+const fields = [
+  text({ name: "title", label: "Title", default: "untitled" }),
+  richText({ name: "body", label: "Body" }),
+  date({ name: "publishedAt", label: "Published" }),
+  image({ name: "thumbnail", label: "Thumb" }),
+  file({ name: "attachment", label: "Attachment" }),
+  relation({ name: "author", label: "Author", collection: "authors", valueField: "id", searchFields: ["name"] }),
+  boolean({ name: "draft", label: "Draft", default: false }),
+  select({ name: "category", label: "Category", options: ["news", "tech"], default: "news" }),
+  select({ name: "tags", label: "Tags", options: ["a", "b"], multiple: true }),
+  object({
+    name: "meta",
+    label: "Meta",
+    fields: [
+      text({ name: "author", label: "Author", default: "anonymous" }),
+      boolean({ name: "featured", label: "Featured", default: true }),
+      richText({ name: "notes", label: "Notes" }),
+    ],
+  }),
+  list({
+    name: "sections",
+    label: "Sections",
+    fields: [
+      text({ name: "heading", label: "Heading", default: "h" }),
+      select({ name: "kind", label: "Kind", options: ["text", "image"], default: "text" }),
+      boolean({ name: "visible", label: "Visible", default: true }),
+      richText({ name: "summary", label: "Summary" }),
+    ],
+  }),
+  list({ name: "images", label: "Images", itemType: "image" }),
+  { name: "legacy", label: "Legacy", type: "unknown" } as never,
+];
+
+describe("serializeJson / deserializeJson", () => {
+  it("serializes field values with type normalization", () => {
+    const json = serializeJson(
+      {
+        title: 123,
+        body: null,
+        publishedAt: "2026-01-01",
+        thumbnail: null,
+        attachment: "/files/doc.pdf",
+        author: 42,
+        draft: 0,
+        category: null,
+        tags: "a",
+        meta: "invalid-object",
+        sections: [{ heading: "Intro" }, "fallback"],
+        images: ["/a.jpg", 99],
+        legacy: { keep: true },
+      },
+      fields,
+    );
+
+    const parsed = JSON.parse(json) as Record<string, unknown>;
+    expect(parsed.title).toBe("123");
+    expect(parsed.body).toBe("");
+    expect(parsed.thumbnail).toBe("");
+    expect(parsed.author).toBe("42");
+    expect(parsed.draft).toBe(false);
+    expect(parsed.category).toBe("");
+    expect(parsed.tags).toEqual([]);
+    expect(parsed.meta).toEqual({ author: "anonymous", featured: true, notes: "" });
+    expect(parsed.sections).toEqual([
+      { heading: "Intro", kind: "text", visible: true, summary: "" },
+      "fallback",
+    ]);
+    expect(parsed.images).toEqual(["/a.jpg", "99"]);
+    expect(parsed.legacy).toEqual({ keep: true });
+    expect(json.endsWith("\n")).toBe(true);
+  });
+
+  it("coerces values from JSON including defaults and fallback branches", () => {
+    const parsed = deserializeJson(
+      JSON.stringify({
+        title: 7,
+        body: 8,
+        publishedAt: null,
+        thumbnail: 5,
+        attachment: 4,
+        author: 3,
+        draft: "",
+        category: 123,
+        tags: "not-array",
+        meta: [],
+        sections: [{ heading: 10, visible: "", summary: null }, "plain"],
+        images: ["single", 2],
+        legacy: "passthrough",
+      }),
+      fields,
+    );
+
+    expect(parsed.values.title).toBe("7");
+    expect(parsed.values.body).toBe("8");
+    expect(parsed.values.publishedAt).toBe("");
+    expect(parsed.values.thumbnail).toBe("5");
+    expect(parsed.values.attachment).toBe("4");
+    expect(parsed.values.author).toBe("3");
+    expect(parsed.values.draft).toBe(false);
+    expect(parsed.values.category).toBe("123");
+    expect(parsed.values.tags).toEqual([]);
+    expect(parsed.values.meta).toEqual({ author: "anonymous", featured: true, notes: "" });
+    expect(parsed.values.sections).toEqual([
+      { heading: "10", kind: "text", visible: false, summary: "" },
+      "plain",
+    ]);
+    expect(parsed.values.images).toEqual(["single", "2"]);
+    expect(parsed.values.legacy).toBe("passthrough");
+  });
+
+  it("fills defaults when values are missing", () => {
+    const parsed = deserializeJson("{}", fields);
+    expect(parsed.values.title).toBe("untitled");
+    expect(parsed.values.body).toBe("");
+    expect(parsed.values.draft).toBe(false);
+    expect(parsed.values.category).toBe("news");
+    expect(parsed.values.tags).toEqual([]);
+    expect(parsed.values.meta).toEqual({});
+    expect(parsed.values.sections).toEqual([]);
+    expect(parsed.values.images).toEqual([]);
+    expect(parsed.values.legacy).toBeNull();
+  });
+
+  it("preserves nested object values when object input is valid", () => {
+    const json = serializeJson(
+      {
+        meta: { author: "Jane", featured: false, notes: "ok" },
+      },
+      fields,
+    );
+
+    const parsed = JSON.parse(json) as Record<string, unknown>;
+    expect(parsed.meta).toEqual({ author: "Jane", featured: false, notes: "ok" });
+  });
+
+  it("coerces object field from valid object input", () => {
+    const parsed = deserializeJson(
+      JSON.stringify({
+        meta: { author: "Jane", featured: true, notes: "ok" },
+      }),
+      fields,
+    );
+
+    expect(parsed.values.meta).toEqual({ author: "Jane", featured: true, notes: "ok" });
+  });
+
+  it("throws on invalid JSON", () => {
+    expect(() => deserializeJson("{", fields)).toThrow(SyntaxError);
+  });
+});

package/src/serializer/json.ts

@@ -0,0 +1,198 @@
+/**
+ * JSON file のシリアライザ / デシリアライザ。
+ * file collection (profile など固定 JSON ファイル) の読み書きに使う。
+ *
+ * JSON ファイルは frontmatter を持たないため、
+ * ファイル全体が JSON オブジェクトとなる。
+ * MezzField 定義を使って型強制を行う。
+ */
+
+import type { MezzField, MezzListField, MezzObjectField, MezzSelectField } from "@mezzanine-stack/content-schema";
+import type { FieldValues } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Serialization: FieldValues → JSON string
+// ---------------------------------------------------------------------------
+
+/**
+ * フィールド値を JSON 文字列にシリアライズする。
+ * rich-text フィールドも JSON に含める (file collection は body を持たない)。
+ */
+export function serializeJson(values: FieldValues, fields: MezzField[]): string {
+  const obj: Record<string, unknown> = {};
+  for (const field of fields) {
+    const value = values[field.name];
+    if (value !== undefined) {
+      obj[field.name] = normalizeForJson(field, value);
+    }
+  }
+  return JSON.stringify(obj, null, 2) + "\n";
+}
+
+function normalizeForJson(field: MezzField, value: unknown): unknown {
+  switch (field.type) {
+    case "text":
+    case "rich-text":
+    case "date":
+    case "image":
+    case "file":
+    case "relation":
+      return value === null || value === undefined ? "" : String(value);
+
+    case "boolean":
+      return Boolean(value);
+
+    case "select": {
+      const sf = field as MezzSelectField;
+      if (sf.multiple) {
+        return Array.isArray(value) ? value.map(String) : [];
+      }
+      return value === null || value === undefined ? "" : String(value);
+    }
+
+    case "list": {
+      const lf = field as MezzListField;
+      const arr = Array.isArray(value) ? value : [];
+      if (lf.fields && lf.fields.length > 0) {
+        return arr.map((item) => {
+          if (typeof item === "object" && item !== null && !Array.isArray(item)) {
+            const obj: Record<string, unknown> = {};
+            for (const sf of lf.fields!) {
+              const sv = (item as Record<string, unknown>)[sf.name];
+              obj[sf.name] = sv !== undefined ? normalizeForJson(sf, sv) : defaultValue(sf);
+            }
+            return obj;
+          }
+          return String(item);
+        });
+      }
+      return arr.map(String);
+    }
+
+    case "object": {
+      const of_ = field as MezzObjectField;
+      const obj =
+        typeof value === "object" && !Array.isArray(value) && value !== null
+          ? (value as Record<string, unknown>)
+          : {};
+      const result: Record<string, unknown> = {};
+      for (const sf of of_.fields) {
+        const sv = obj[sf.name];
+        result[sf.name] = sv !== undefined ? normalizeForJson(sf, sv) : defaultValue(sf);
+      }
+      return result;
+    }
+
+    default:
+      return value;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Deserialization: JSON string → FieldValues
+// ---------------------------------------------------------------------------
+
+export interface JsonParseResult {
+  values: FieldValues;
+}
+
+/**
+ * JSON 文字列をフィールド値にデシリアライズする。
+ * MezzField 定義を使って型変換を行う。
+ * @throws {SyntaxError} JSON パースエラー時
+ */
+export function deserializeJson(content: string, fields: MezzField[]): JsonParseResult {
+  const raw = JSON.parse(content) as Record<string, unknown>;
+  const values: FieldValues = {};
+  for (const field of fields) {
+    const rawVal = raw[field.name];
+    values[field.name] =
+      rawVal === undefined || rawVal === null
+        ? defaultValue(field)
+        : coerceField(field, rawVal);
+  }
+  return { values };
+}
+
+function coerceField(field: MezzField, value: unknown): unknown {
+  switch (field.type) {
+    case "text":
+    case "rich-text":
+    case "date":
+    case "image":
+    case "file":
+    case "relation":
+      return value === null || value === undefined ? "" : String(value);
+
+    case "boolean":
+      return Boolean(value);
+
+    case "select": {
+      const sf = field as MezzSelectField;
+      if (sf.multiple) {
+        return Array.isArray(value) ? value.map(String) : [];
+      }
+      return value === null || value === undefined ? "" : String(value);
+    }
+
+    case "list": {
+      const lf = field as MezzListField;
+      if (!Array.isArray(value)) return [];
+      if (lf.fields && lf.fields.length > 0) {
+        return value.map((item) => {
+          if (typeof item === "object" && item !== null && !Array.isArray(item)) {
+            const obj: Record<string, unknown> = {};
+            for (const sf of lf.fields!) {
+              const sv = (item as Record<string, unknown>)[sf.name];
+              obj[sf.name] = sv !== undefined ? coerceField(sf, sv) : defaultValue(sf);
+            }
+            return obj;
+          }
+          return String(item);
+        });
+      }
+      return value.map(String);
+    }
+
+    case "object": {
+      const of_ = field as MezzObjectField;
+      const obj =
+        typeof value === "object" && !Array.isArray(value) && value !== null
+          ? (value as Record<string, unknown>)
+          : {};
+      const result: Record<string, unknown> = {};
+      for (const sf of of_.fields) {
+        const sv = obj[sf.name];
+        result[sf.name] = sv !== undefined ? coerceField(sf, sv) : defaultValue(sf);
+      }
+      return result;
+    }
+
+    default:
+      return value;
+  }
+}
+
+function defaultValue(field: MezzField): unknown {
+  switch (field.type) {
+    case "text":
+    case "rich-text":
+    case "date":
+    case "image":
+    case "file":
+    case "relation":
+      return (field as { default?: string }).default ?? "";
+    case "boolean":
+      return (field as { default?: boolean }).default ?? false;
+    case "select":
+      return (field as MezzSelectField).multiple
+        ? []
+        : ((field as { default?: string }).default ?? "");
+    case "list":
+      return [];
+    case "object":
+      return {};
+    default:
+      return null;
+  }
+}

package/src/serializer/markdown.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, it } from "vitest";
+import {
+  boolean,
+  date,
+  file,
+  image,
+  list,
+  object,
+  relation,
+  richText,
+  select,
+  text,
+} from "@mezzanine-stack/content-schema";
+import { deserializeMarkdown, serializeMarkdown } from "./markdown.js";
+
+const fields = [
+  text({ name: "title", label: "Title", default: "untitled" }),
+  date({ name: "publishedAt", label: "Published" }),
+  image({ name: "thumbnail", label: "Thumbnail" }),
+  file({ name: "attachment", label: "Attachment" }),
+  relation({ name: "author", label: "Author", collection: "authors", valueField: "id", searchFields: ["name"] }),
+  boolean({ name: "draft", label: "Draft", default: false }),
+  select({ name: "category", label: "Category", options: ["news", "tech"], default: "news" }),
+  select({ name: "tags", label: "Tags", options: ["a", "b"], multiple: true }),
+  list({ name: "images", label: "Images", itemType: "image" }),
+  list({
+    name: "sections",
+    label: "Sections",
+    fields: [
+      text({ name: "heading", label: "Heading", default: "h" }),
+      boolean({ name: "visible", label: "Visible", default: true }),
+      richText({ name: "summary", label: "Summary" }),
+    ],
+  }),
+  list({
+    name: "blocks",
+    label: "Blocks",
+    fields: [
+      select({ name: "flags", label: "Flags", options: ["a", "b"], multiple: true }),
+      text({ name: "label", label: "Label", default: "none" }),
+    ],
+  }),
+  object({
+    name: "meta",
+    label: "Meta",
+    fields: [
+      text({ name: "owner", label: "Owner", default: "anon" }),
+      select({ name: "state", label: "State", options: ["open", "closed"], default: "open" }),
+      richText({ name: "notes", label: "Notes" }),
+    ],
+  }),
+  richText({ name: "body", label: "Body" }),
+  { name: "legacy", label: "Legacy", type: "unknown" } as never,
+];
+
+describe("serializeMarkdown / deserializeMarkdown", () => {
+  it("serializes complex values including quoting and nested blocks", () => {
+    const content = serializeMarkdown(
+      {
+        title: " true ",
+        publishedAt: "2026-01-01",
+        thumbnail: "/img.jpg",
+        attachment: "/file.pdf",
+        author: "users/me",
+        draft: false,
+        category: "tech",
+        tags: [],
+        images: ["one", "two"],
+        sections: [{ heading: "Intro", visible: true }, { summary: "line1\nline2" }],
+        blocks: [{ flags: ["a", "b"], label: "hero" }],
+        meta: { owner: "#tag", notes: "multi\nline" },
+        body: "ignored",
+        legacy: "legacy-value",
+      },
+      "# Heading\n\nBody text.",
+      fields,
+    );
+
+    expect(content).toContain('title: " true "');
+    expect(content).toContain("tags:");
+    expect(content).toContain("tags: []");
+    expect(content).toContain("images:");
+    expect(content).toContain("  - one");
+    expect(content).toContain("  - two");
+    expect(content).toContain("sections:");
+    expect(content).toContain("  - heading: Intro");
+    expect(content).toContain("blocks:");
+    expect(content).toContain("    - a");
+    expect(content).toContain("    - b");
+    expect(content).toContain('  owner: "#tag"');
+    expect(content).toContain('legacy: legacy-value');
+    expect(content).toContain("---\n# Heading");
+  });
+
+  it("serializes empty primitive list as []", () => {
+    const content = serializeMarkdown(
+      {
+        images: [],
+      },
+      "body",
+      fields,
+    );
+
+    expect(content).toContain("images: []");
+  });
+
+  it("deserializes edge-case frontmatter structures and coercions", () => {
+    const parsed = deserializeMarkdown(
+      [
+        "---",
+        "# comment",
+        "invalid-line",
+        "title: \"hello\"",
+        "publishedAt: ~",
+        "thumbnail: /img.png",
+        "attachment: /f.pdf",
+        "author: users/1",
+        "draft: on",
+        "category: true",
+        "tags: yes",
+        "images:",
+        "",
+        "  - one",
+        "  ignored line",
+        "  - two",
+        "sections:",
+        "",
+        "  - heading: Start",
+        "    visible: off",
+        "    summary: ''",
+        "  -",
+        "    heading: Next",
+        "sectionsScalar:",
+        "  - just-text",
+        "meta:",
+        "  owner: admin",
+        "  state: {}",
+        "blocks: x",
+        "legacy: '{}'",
+        "emptyBlock: |",
+        "---",
+        "body line",
+      ].join("\n"),
+      fields,
+    );
+
+    expect(parsed.body).toBe("body line");
+    expect(parsed.values.title).toBe("hello");
+    expect(parsed.values.publishedAt).toBe("");
+    expect(parsed.values.draft).toBe(true);
+    expect(parsed.values.category).toBe("true");
+    expect(parsed.values.tags).toEqual(["true"]);
+    expect(parsed.values.images).toEqual(["one", "two"]);
+    expect(parsed.values.sections).toEqual([
+      { heading: "Start", visible: false, summary: "" },
+      { heading: "Next", visible: true, summary: "" },
+    ]);
+    expect(parsed.values.meta).toEqual({ owner: "admin", state: "[object Object]", notes: "" });
+    expect(parsed.values.blocks).toEqual([]);
+    expect(parsed.values.legacy).toBe("{}");
+  });
+
+  it("supports sequence block objects and scalar parsing variants", () => {
+    const parsed = deserializeMarkdown(
+      [
+        "---",
+        "tags:",
+        "  - a",
+        "  - b",
+        "sections:",
+        "  -",
+        "    heading: Item1",
+        "    visible: yes",
+        "",
+        "  - heading: Item2",
+        "    visible: no",
+        "  - plain",
+        "meta:",
+        "  owner: 'single-quoted'",
+        "  notes: '\"broken'",
+        "draft: maybe",
+        "---",
+        "text",
+      ].join("\n"),
+      fields,
+    );
+
+    expect(parsed.values.tags).toEqual(["a", "b"]);
+    expect(parsed.values.sections).toEqual([
+      { heading: "Item1", visible: true, summary: "" },
+      { heading: "Item2", visible: false, summary: "" },
+      "plain",
+    ]);
+    expect(parsed.values.meta).toEqual({ owner: "single-quoted", state: "open", notes: '"broken' });
+    expect(parsed.values.draft).toBe(false);
+  });
+
+  it("coerces object field to empty object when YAML scalar is array literal", () => {
+    const parsed = deserializeMarkdown(
+      [
+        "---",
+        "meta: []",
+        "---",
+        "text",
+      ].join("\n"),
+      fields,
+    );
+
+    expect(parsed.values.meta).toEqual({ owner: "anon", state: "open", notes: "" });
+  });
+
+  it("returns body as-is when frontmatter is missing or unclosed", () => {
+    const noFrontmatter = deserializeMarkdown("just markdown body", fields);
+    expect(noFrontmatter.body).toBe("just markdown body");
+
+    const unclosed = deserializeMarkdown("---\ntitle: a", fields);
+    expect(unclosed.body).toBe("---\ntitle: a");
+    expect(unclosed.values.title).toBe("untitled");
+    expect(unclosed.values.draft).toBe(false);
+    expect(unclosed.values.tags).toEqual([]);
+  });
+});