@mezzanine-stack/cms-core 0.1.0

package/src/serializer/markdown.ts

@@ -0,0 +1,504 @@
+/**
+ * Markdown (frontmatter + body) のシリアライザ / デシリアライザ。
+ *
+ * 対応フォーマット:
+ *   ---
+ *   key: value
+ *   ---
+ *   Markdown 本文
+ *
+ * MezzField 定義を手がかりとして型付き変換を行い、
+ * 外部 YAML ライブラリ不要でラウンドトリップを保証する。
+ */
+
+import type {
+  MezzField,
+  MezzListField,
+  MezzObjectField,
+  MezzSelectField,
+} from "@mezzanine-stack/content-schema";
+import type { FieldValues } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Serialization: EntryModel → Markdown string
+// ---------------------------------------------------------------------------
+
+/**
+ * フィールド値と本文テキストを Markdown 文字列にシリアライズする。
+ * rich-text フィールドは body に入るため frontmatter からは除外する。
+ */
+export function serializeMarkdown(
+  values: FieldValues,
+  body: string,
+  fields: MezzField[]
+): string {
+  const lines: string[] = [];
+
+  for (const field of fields) {
+    if (field.type === "rich-text") continue;
+    const value = values[field.name];
+    if (value === undefined) continue;
+    appendField(field, value, lines, 0);
+  }
+
+  const frontmatter = lines.join("\n");
+  const normalizedBody = body.endsWith("\n") ? body : `${body}\n`;
+  return `---\n${frontmatter}\n---\n${normalizedBody}`;
+}
+
+function appendField(
+  field: MezzField,
+  value: unknown,
+  lines: string[],
+  indent: number
+): void {
+  const pad = " ".repeat(indent);
+  const key = `${pad}${field.name}`;
+
+  switch (field.type) {
+    case "text":
+    case "date":
+    case "image":
+    case "file":
+    case "relation":
+      lines.push(`${key}: ${yamlString(value == null ? "" : String(value))}`);
+      break;
+
+    case "boolean":
+      lines.push(`${key}: ${value ? "true" : "false"}`);
+      break;
+
+    case "select": {
+      const sf = field as MezzSelectField;
+      if (sf.multiple) {
+        const arr = Array.isArray(value) ? value : [];
+        if (arr.length === 0) {
+          lines.push(`${key}: []`);
+        } else {
+          lines.push(`${key}:`);
+          for (const item of arr) {
+            lines.push(`${pad}  - ${yamlString(String(item))}`);
+          }
+        }
+      } else {
+        lines.push(`${key}: ${yamlString(String(value ?? ""))}`);
+      }
+      break;
+    }
+
+    case "list": {
+      const lf = field as MezzListField;
+      const arr = Array.isArray(value) ? value : [];
+      if (arr.length === 0) {
+        lines.push(`${key}: []`);
+        break;
+      }
+      if (lf.fields && lf.fields.length > 0) {
+        lines.push(`${key}:`);
+        for (const item of arr) {
+          const obj = item as Record<string, unknown>;
+          let isFirst = true;
+          for (const subField of lf.fields) {
+            const sv = obj[subField.name];
+            if (sv === undefined) continue;
+            const subLines: string[] = [];
+            appendField(subField, sv, subLines, 0);
+            if (isFirst) {
+              lines.push(`${pad}  - ${subLines[0].trimStart()}`);
+              for (const sl of subLines.slice(1)) {
+                lines.push(`${pad}    ${sl.trimStart()}`);
+              }
+              isFirst = false;
+            } else {
+              for (const sl of subLines) {
+                lines.push(`${pad}    ${sl.trimStart()}`);
+              }
+            }
+          }
+        }
+      } else {
+        lines.push(`${key}:`);
+        for (const item of arr) {
+          lines.push(`${pad}  - ${yamlString(String(item))}`);
+        }
+      }
+      break;
+    }
+
+    case "object": {
+      const of_ = field as MezzObjectField;
+      const obj = (typeof value === "object" && value !== null ? value : {}) as Record<string, unknown>;
+      lines.push(`${key}:`);
+      for (const subField of of_.fields) {
+        const sv = obj[subField.name];
+        if (sv !== undefined) {
+          appendField(subField, sv, lines, indent + 2);
+        }
+      }
+      break;
+    }
+
+    default:
+      lines.push(`${key}: ${yamlString(String(value ?? ""))}`);
+  }
+}
+
+/** 必要に応じてダブルクォートで囲む */
+function yamlString(value: string): string {
+  if (value === "") return '""';
+  // YAML の特殊文字・予約語・マルチラインを含む場合はクォート
+  const needsQuote =
+    /[:#\[\]{},|>&*!%@`]/.test(value) ||
+    /^[\s]|[\s]$/.test(value) ||
+    /^(true|false|null|~|yes|no|on|off)$/i.test(value) ||
+    value.includes("\n") ||
+    value.startsWith('"') ||
+    value.startsWith("'");
+  return needsQuote ? JSON.stringify(value) : value;
+}
+
+// ---------------------------------------------------------------------------
+// Deserialization: Markdown string → { values, body }
+// ---------------------------------------------------------------------------
+
+export interface MarkdownParseResult {
+  values: FieldValues;
+  body: string;
+}
+
+/**
+ * Markdown 文字列をフィールド値と本文テキストにデシリアライズする。
+ * MezzField 定義を使って型変換を行う。
+ */
+export function deserializeMarkdown(
+  content: string,
+  fields: MezzField[]
+): MarkdownParseResult {
+  const { frontmatter, body } = splitFrontmatter(content);
+  const raw = parseFrontmatter(frontmatter);
+  const values = coerceValues(raw, fields);
+  return { values, body };
+}
+
+// ---------------------------------------------------------------------------
+// frontmatter 分割
+// ---------------------------------------------------------------------------
+
+function splitFrontmatter(content: string): {
+  frontmatter: string;
+  body: string;
+} {
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") {
+    return { frontmatter: "", body: content };
+  }
+  let endIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i]?.trim() === "---") {
+      endIdx = i;
+      break;
+    }
+  }
+  if (endIdx === -1) {
+    return { frontmatter: "", body: content };
+  }
+  return {
+    frontmatter: lines.slice(1, endIdx).join("\n"),
+    body: lines.slice(endIdx + 1).join("\n"),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// シンプル YAML パーサ (serializeMarkdown が出力するサブセット専用)
+// ---------------------------------------------------------------------------
+
+type YamlPrimitive = string | boolean | null;
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+interface YamlObject extends Record<string, YamlValue> {}
+type YamlValue = YamlPrimitive | YamlValue[] | YamlObject;
+
+function parseFrontmatter(yaml: string): Record<string, YamlValue> {
+  const lines = yaml.split("\n");
+  return parseMapping(lines, 0).result;
+}
+
+interface MappingResult {
+  result: Record<string, YamlValue>;
+  /** 消費した行数 */
+  consumed: number;
+}
+
+function parseMapping(lines: string[], startIdx: number): MappingResult {
+  const result: Record<string, YamlValue> = {};
+  let i = startIdx;
+  const baseIndent = getIndent(lines[startIdx] ?? "");
+
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line === undefined) break;
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) {
+      i++;
+      continue;
+    }
+    const indent = getIndent(line);
+    if (indent < baseIndent && i > startIdx) break;
+
+    const colonIdx = trimmed.indexOf(":");
+    if (colonIdx === -1) {
+      i++;
+      continue;
+    }
+    const key = trimmed.slice(0, colonIdx).trim();
+    const rest = trimmed.slice(colonIdx + 1).trim();
+
+    if (rest === "" || rest === "|" || rest === ">") {
+      const { value, consumed } = parseBlock(lines, i + 1, indent);
+      result[key] = value;
+      i += consumed + 1;
+    } else {
+      result[key] = parseScalar(rest);
+      i++;
+    }
+  }
+
+  return { result, consumed: i - startIdx };
+}
+
+interface BlockResult {
+  value: YamlValue;
+  consumed: number;
+}
+
+function parseBlock(
+  lines: string[],
+  startIdx: number,
+  parentIndent: number
+): BlockResult {
+  let i = startIdx;
+  let blockIndent = -1;
+  const blockLines: string[] = [];
+
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line === undefined) break;
+    if (line.trim() === "") {
+      i++;
+      continue;
+    }
+    const indent = getIndent(line);
+    if (indent <= parentIndent) break;
+    if (blockIndent === -1) blockIndent = indent;
+    if (indent < blockIndent) break;
+    blockLines.push(line);
+    i++;
+  }
+
+  const consumed = i - startIdx;
+  if (blockLines.length === 0) return { value: null, consumed };
+
+  const firstTrimmed = blockLines[0]?.trim() ?? "";
+  if (firstTrimmed.startsWith("- ") || firstTrimmed === "-") {
+    return { value: parseSequence(blockLines, blockIndent), consumed };
+  }
+  return { value: parseMapping(blockLines, 0).result, consumed };
+}
+
+function parseSequence(lines: string[], baseIndent: number): YamlValue[] {
+  const result: YamlValue[] = [];
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line) break;
+    const indent = getIndent(line);
+    if (indent < baseIndent) break;
+
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("- ") && trimmed !== "-") {
+      i++;
+      continue;
+    }
+
+    const itemStr = trimmed.startsWith("- ") ? trimmed.slice(2).trim() : "";
+
+    if (itemStr === "") {
+      // ブロック形式の object アイテム
+      const subLines: string[] = [];
+      let j = i + 1;
+      while (j < lines.length) {
+        const sl = lines[j];
+        if (!sl) { j++; continue; }
+        if (getIndent(sl) <= indent) break;
+        subLines.push(sl);
+        j++;
+      }
+      result.push(subLines.length > 0 ? parseMapping(subLines, 0).result : null);
+      i = j;
+    } else {
+      // インライン: `- key: value` 形式かスカラか
+      const colonIdx = itemStr.indexOf(":");
+      if (colonIdx !== -1) {
+        const firstKey = itemStr.slice(0, colonIdx).trim();
+        const firstVal = parseScalar(itemStr.slice(colonIdx + 1).trim());
+        const obj: Record<string, YamlValue> = { [firstKey]: firstVal };
+        // 追加プロパティを収集
+        let j = i + 1;
+        while (j < lines.length) {
+          const sl = lines[j];
+          if (!sl || sl.trim() === "") { j++; continue; }
+          const slIndent = getIndent(sl);
+          if (slIndent <= indent) break;
+          if (sl.trim().startsWith("- ")) break;
+          const slColon = sl.indexOf(":");
+          if (slColon !== -1) {
+            const k = sl.slice(0, slColon).trim();
+            const v = parseScalar(sl.slice(slColon + 1).trim());
+            obj[k] = v;
+          }
+          j++;
+        }
+        result.push(obj);
+        i = j;
+      } else {
+        result.push(parseScalar(itemStr));
+        i++;
+      }
+    }
+  }
+
+  return result;
+}
+
+function parseScalar(value: string): YamlValue {
+  if (value === "null" || value === "~" || value === "") return null;
+  if (value === "true" || value === "yes" || value === "on") return true;
+  if (value === "false" || value === "no" || value === "off") return false;
+  if (value === "[]") return [];
+  if (value === "{}") return {};
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value.slice(1, -1);
+    }
+  }
+  return value;
+}
+
+function getIndent(line: string): number {
+  return line.match(/^(\s*)/)?.[1].length ?? 0;
+}
+
+// ---------------------------------------------------------------------------
+// 型強制: raw YAML → FieldValues
+// ---------------------------------------------------------------------------
+
+function coerceValues(
+  raw: Record<string, YamlValue>,
+  fields: MezzField[]
+): FieldValues {
+  const result: FieldValues = {};
+  for (const field of fields) {
+    if (field.type === "rich-text") continue;
+    const rawVal = raw[field.name];
+    result[field.name] =
+      rawVal === undefined || rawVal === null
+        ? defaultValue(field)
+        : coerceField(field, rawVal);
+  }
+  return result;
+}
+
+function coerceField(field: MezzField, value: YamlValue): unknown {
+  switch (field.type) {
+    case "text":
+    case "date":
+    case "image":
+    case "file":
+    case "relation":
+      return value === null ? "" : String(value);
+
+    case "boolean":
+      return typeof value === "boolean"
+        ? value
+        : value === "true" || value === "yes" || value === "on";
+
+    case "select": {
+      const sf = field as MezzSelectField;
+      if (sf.multiple) {
+        if (Array.isArray(value)) return value.map(String);
+        return value === null ? [] : [String(value)];
+      }
+      return value === null ? "" : String(value);
+    }
+
+    case "list": {
+      if (!Array.isArray(value)) return [];
+      const lf = field as MezzListField;
+      if (lf.fields && lf.fields.length > 0) {
+        return value.map((item) => {
+          if (
+            typeof item === "object" &&
+            !Array.isArray(item) &&
+            item !== null
+          ) {
+            const obj: Record<string, unknown> = {};
+            for (const sf of lf.fields!) {
+              const sv = (item as Record<string, YamlValue>)[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, YamlValue>)
+          : {};
+      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 "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 {};
+    case "rich-text":
+      return "";
+    default:
+      return null;
+  }
+}

package/src/types.ts

@@ -0,0 +1,110 @@
+// cms-core の公開型定義
+
+import type { MezzCollection } from "@mezzanine-stack/content-schema";
+
+// ---------------------------------------------------------------------------
+// 共通値型
+// ---------------------------------------------------------------------------
+
+export type FieldValues = Record<string, unknown>;
+
+// ---------------------------------------------------------------------------
+// GitProvider contract
+// ---------------------------------------------------------------------------
+
+/** コレクション一覧画面で各エントリを表す型 */
+export interface CatalogEntry {
+  /** folder collection: slug、file collection: file 名 */
+  entryId: string;
+  title?: string;
+  draft?: boolean;
+  updatedAt?: string;
+  /** GitHub 上のファイルパス (例: src/content/blog/hello.md) */
+  sourcePath: string;
+  /** GitHub blob SHA — 保存時の optimistic concurrency に使う */
+  revision: string;
+}
+
+/** エントリ編集画面で使う完全なモデル */
+export interface EntryModel {
+  collection: MezzCollection;
+  entryId: string;
+  sourcePath: string;
+  /** フォーム用の正規化済み値 */
+  values: FieldValues;
+  /** Markdown 本文 (rich-text フィールドが存在する場合のみ) */
+  body?: string;
+  revision: string;
+}
+
+/** saveEntry の戻り値 */
+export interface SaveResult {
+  /** 保存後の新しい GitHub blob SHA */
+  revision: string;
+}
+
+/** アセット（画像・ファイル）の一覧エントリ */
+export interface AssetItem {
+  /** ファイル名 (例: "photo.jpg") */
+  name: string;
+  /** リポジトリ内パス (例: "public/uploads/photo.jpg") */
+  path: string;
+  /** Web 上の公開パス (例: "/uploads/photo.jpg") */
+  publicPath: string;
+  /** ファイルサイズ (bytes) */
+  size: number;
+}
+
+/** Git プロバイダ非依存のストレージ契約 */
+export interface GitProvider {
+  /**
+   * 指定ディレクトリ配下のエントリ一覧を返す。
+   * @param folder - リポジトリルートからの相対パス (例: "src/content/blog")
+   */
+  listEntries(folder: string): Promise<CatalogEntry[]>;
+
+  /**
+   * 指定パスのファイルを取得する。
+   * @returns ファイルの生テキスト内容と blob SHA
+   */
+  getEntry(sourcePath: string): Promise<{ content: string; revision: string }>;
+
+  /**
+   * ファイルを作成または更新して commit する。
+   * @param sha - 既存ファイルの場合は blob SHA を渡す (楽観的排他制御)。新規の場合は undefined。
+   */
+  saveEntry(
+    sourcePath: string,
+    content: string,
+    options: {
+      sha?: string;
+      message: string;
+    }
+  ): Promise<SaveResult>;
+
+  /**
+   * ファイルを削除して commit する。
+   * @param sha - 削除対象の blob SHA
+   */
+  deleteEntry(
+    sourcePath: string,
+    sha: string,
+    message: string
+  ): Promise<void>;
+
+  /**
+   * 指定ディレクトリ配下のアセット一覧を返す。
+   * @param folder - リポジトリルートからの相対パス (例: "public/uploads")
+   */
+  listAssets(folder: string): Promise<AssetItem[]>;
+
+  /**
+   * バイナリアセット (画像など) をアップロードして commit する。
+   * @returns リポジトリ内の保存パス
+   */
+  uploadAsset(
+    sourcePath: string,
+    content: Uint8Array,
+    message: string
+  ): Promise<string>;
+}

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"]
+}

package/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+    coverage: {
+      include: ["src/**/*.ts"],
+      exclude: ["src/**/*.test.ts", "src/types.ts"],
+    },
+  },
+});