@notion-headless-cms/core 0.3.25 → 0.5.0

package/README.md

@@ -127,12 +127,12 @@ import { memoryCache } from "@notion-headless-cms/core/cache/memory";
 
 ## ランタイム別レシピ
 
-- [Node.js スクリプト](../../docs/recipes/nodejs-script.md)
-- [Cloudflare Workers + R2 + KV](../../docs/recipes/cloudflare-workers.md)
-- [Next.js App Router](../../docs/recipes/nextjs-app-router.md)
-- [カスタムデータソース](../../docs/recipes/custom-source.md)
+- [Node.js スクリプト](../../docs/ja/recipes/nodejs-script.md)
+- [Cloudflare Workers + R2 + KV](../../docs/ja/recipes/cloudflare-workers.md)
+- [Next.js App Router](../../docs/ja/recipes/nextjs-app-router.md)
+- [カスタムデータソース](../../docs/ja/recipes/custom-source.md)
 
 ## 詳細ドキュメント
 
-- [クイックスタート](../../docs/quickstart.md)
-- [CMS メソッド一覧](../../docs/api/cms-methods.md)
+- [クイックスタート](../../docs/ja/quickstart.md)
+- [CMS メソッド一覧](../../docs/ja/api/cms-methods.md)

package/dist/cache/memory.d.mts

@@ -1,4 +1,4 @@
-import { t as CacheAdapter } from "../cache-DS81aOcC.mjs";
+import { t as CacheAdapter } from "../cache-v9jTMnYd.mjs";
 
 //#region src/cache/memory.d.ts
 interface MemoryDocumentOptions {
@@ -16,6 +16,8 @@ interface MemoryCacheOptions extends MemoryDocumentOptions, MemoryImageOptions {
  * インメモリのキャッシュアダプタ。document + image 両方を担当する。
  * プロセス再起動でクリアされるため、ローカル開発・SSG ビルド・テスト用途。
  *
+ * `stats()` でヒット率・エントリ数・画像合計バイト数を返す。
+ *
  * @example
  * cache: [memoryCache({ maxItems: 1000 })]
  */

package/dist/cache/memory.mjs

@@ -16,11 +16,21 @@ var MemoryDocumentOps = class {
 	metas = /* @__PURE__ */ new Map();
 	contents = /* @__PURE__ */ new Map();
 	maxItems;
+	/** `cms.stats()` 用のヒット/ミス集計 (list+meta+content の合計)。 */
+	hits = 0;
+	misses = 0;
 	constructor(options) {
 		this.maxItems = options?.maxItems;
 	}
+	/** 保持エントリ数 (list / meta / content の合計)。stats() で使う。 */
+	totalEntries() {
+		return this.lists.size + this.metas.size + this.contents.size;
+	}
 	getList(collection) {
-		return Promise.resolve(this.lists.get(collection) ?? null);
+		const entry = this.lists.get(collection);
+		if (entry) this.hits++;
+		else this.misses++;
+		return Promise.resolve(entry ?? null);
 	}
 	setList(collection, data) {
 		this.lists.set(collection, data);
@@ -29,7 +39,10 @@ var MemoryDocumentOps = class {
 	getMeta(collection, slug) {
 		const key = itemKey(collection, slug);
 		const entry = this.metas.get(key);
-		if (entry) touch(this.metas, key);
+		if (entry) {
+			touch(this.metas, key);
+			this.hits++;
+		} else this.misses++;
 		return Promise.resolve(entry ?? null);
 	}
 	setMeta(collection, slug, data) {
@@ -42,7 +55,10 @@ var MemoryDocumentOps = class {
 	getContent(collection, slug) {
 		const key = itemKey(collection, slug);
 		const entry = this.contents.get(key);
-		if (entry) touch(this.contents, key);
+		if (entry) {
+			touch(this.contents, key);
+			this.hits++;
+		} else this.misses++;
 		return Promise.resolve(entry ?? null);
 	}
 	setContent(collection, slug, data) {
@@ -98,15 +114,28 @@ var MemoryImageOps = class {
 	totalBytes = 0;
 	maxItems;
 	maxSizeBytes;
+	/** `cms.stats()` 用のヒット/ミス集計。 */
+	hits = 0;
+	misses = 0;
 	constructor(options) {
 		this.maxItems = options?.maxItems;
 		this.maxSizeBytes = options?.maxSizeBytes;
 	}
 	get(hash) {
 		const entry = this.store.get(hash);
-		if (entry) touch(this.store, hash);
+		if (entry) {
+			touch(this.store, hash);
+			this.hits++;
+		} else this.misses++;
 		return Promise.resolve(entry ?? null);
 	}
+	/** stats() 用に、現在の保持エントリ数と合計バイト数を返す。 */
+	snapshot() {
+		return {
+			entries: this.store.size,
+			sizeBytes: this.totalBytes
+		};
+	}
 	set(hash, data, contentType) {
 		const existing = this.store.get(hash);
 		if (existing) {
@@ -135,15 +164,36 @@ var MemoryImageOps = class {
 * インメモリのキャッシュアダプタ。document + image 両方を担当する。
 * プロセス再起動でクリアされるため、ローカル開発・SSG ビルド・テスト用途。
 *
+* `stats()` でヒット率・エントリ数・画像合計バイト数を返す。
+*
 * @example
 * cache: [memoryCache({ maxItems: 1000 })]
 */
 function memoryCache(options) {
+	const doc = new MemoryDocumentOps(options);
+	const img = new MemoryImageOps(options);
 	return {
 		name: "memory",
 		handles: ["document", "image"],
-		doc: new MemoryDocumentOps(options),
-		img: new MemoryImageOps(options)
+		doc,
+		img,
+		async stats() {
+			const imgSnap = img.snapshot();
+			return {
+				name: "memory",
+				doc: {
+					hits: doc.hits,
+					misses: doc.misses,
+					entries: doc.totalEntries()
+				},
+				img: {
+					hits: img.hits,
+					misses: img.misses,
+					entries: imgSnap.entries,
+					sizeBytes: imgSnap.sizeBytes
+				}
+			};
+		}
 	};
 }
 //#endregion

package/dist/cache/memory.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"memory.mjs","names":[],"sources":["../../src/cache/memory.ts"],"sourcesContent":["import type {\n  BaseContentItem,\n  CacheAdapter,\n  CachedItemContent,\n  CachedItemList,\n  CachedItemMeta,\n  DocumentCacheOps,\n  ImageCacheOps,\n  InvalidateScope,\n  StorageBinary,\n} from \"../types/index\";\n\nexport interface MemoryDocumentOptions {\n  /** アイテム保持上限。未指定時は上限なし。超過時は LRU で古いものから削除。 */\n  maxItems?: number;\n}\n\nexport interface MemoryImageOptions {\n  /** エントリ保持上限。未指定時は上限なし。超過時は LRU で古いものから削除。 */\n  maxItems?: number;\n  /** 合計保持サイズ上限（バイト）。未指定時は上限なし。超過時は LRU で古いものから削除。 */\n  maxSizeBytes?: number;\n}\n\nexport interface MemoryCacheOptions\n  extends MemoryDocumentOptions,\n    MemoryImageOptions {}\n\n/**\n * Map の挿入順を LRU として扱う軽量実装。\n * `touch` で既存キーを末尾に移動、`enforceLimit` で古いキー（先頭）から削除する。\n */\nfunction touch<K, V>(map: Map<K, V>, key: K): void {\n  const v = map.get(key);\n  if (v === undefined) return;\n  map.delete(key);\n  map.set(key, v);\n}\n\nconst itemKey = (collection: string, slug: string): string =>\n  `${collection}:${slug}`;\n\n/** インメモリのドキュメントオペレーション実装。プロセス再起動でクリアされる。 */\nclass MemoryDocumentOps implements DocumentCacheOps {\n  private lists = new Map<string, CachedItemList<BaseContentItem>>();\n  private metas = new Map<string, CachedItemMeta<BaseContentItem>>();\n  private contents = new Map<string, CachedItemContent>();\n  private readonly maxItems: number | undefined;\n\n  constructor(options?: MemoryDocumentOptions) {\n    this.maxItems = options?.maxItems;\n  }\n\n  getList<T extends BaseContentItem>(\n    collection: string,\n  ): Promise<CachedItemList<T> | null> {\n    return Promise.resolve(\n      (this.lists.get(collection) as CachedItemList<T> | undefined) ?? null,\n    );\n  }\n\n  setList<T extends BaseContentItem>(\n    collection: string,\n    data: CachedItemList<T>,\n  ): Promise<void> {\n    this.lists.set(collection, data);\n    return Promise.resolve();\n  }\n\n  getMeta<T extends BaseContentItem>(\n    collection: string,\n    slug: string,\n  ): Promise<CachedItemMeta<T> | null> {\n    const key = itemKey(collection, slug);\n    const entry = this.metas.get(key) as CachedItemMeta<T> | undefined;\n    if (entry) touch(this.metas, key);\n    return Promise.resolve(entry ?? null);\n  }\n\n  setMeta<T extends BaseContentItem>(\n    collection: string,\n    slug: string,\n    data: CachedItemMeta<T>,\n  ): Promise<void> {\n    const key = itemKey(collection, slug);\n    if (this.metas.has(key)) this.metas.delete(key);\n    this.metas.set(key, data);\n    this.enforceLimit();\n    return Promise.resolve();\n  }\n\n  getContent(\n    collection: string,\n    slug: string,\n  ): Promise<CachedItemContent | null> {\n    const key = itemKey(collection, slug);\n    const entry = this.contents.get(key);\n    if (entry) touch(this.contents, key);\n    return Promise.resolve(entry ?? null);\n  }\n\n  setContent(\n    collection: string,\n    slug: string,\n    data: CachedItemContent,\n  ): Promise<void> {\n    const key = itemKey(collection, slug);\n    if (this.contents.has(key)) this.contents.delete(key);\n    this.contents.set(key, data);\n    this.enforceLimit();\n    return Promise.resolve();\n  }\n\n  invalidate(scope: InvalidateScope): Promise<void> {\n    if (scope === \"all\") {\n      this.lists.clear();\n      this.metas.clear();\n      this.contents.clear();\n      return Promise.resolve();\n    }\n    const kind = scope.kind ?? \"all\";\n    const collection = scope.collection;\n    if (\"slug\" in scope) {\n      const key = itemKey(collection, scope.slug);\n      if (kind === \"all\" || kind === \"meta\") this.metas.delete(key);\n      if (kind === \"all\" || kind === \"content\") this.contents.delete(key);\n      // 単一スラッグ無効化ではリストは触らない（リスト全体の整合は別管理）\n      return Promise.resolve();\n    }\n    // コレクション全体\n    if (kind === \"all\" || kind === \"meta\") {\n      this.lists.delete(collection);\n      const prefix = `${collection}:`;\n      for (const key of [...this.metas.keys()]) {\n        if (key.startsWith(prefix)) this.metas.delete(key);\n      }\n    }\n    if (kind === \"all\" || kind === \"content\") {\n      const prefix = `${collection}:`;\n      for (const key of [...this.contents.keys()]) {\n        if (key.startsWith(prefix)) this.contents.delete(key);\n      }\n    }\n    return Promise.resolve();\n  }\n\n  private enforceLimit(): void {\n    if (this.maxItems === undefined) return;\n    while (this.metas.size > this.maxItems) {\n      const firstKey = this.metas.keys().next().value;\n      if (firstKey === undefined) break;\n      this.metas.delete(firstKey);\n    }\n    while (this.contents.size > this.maxItems) {\n      const firstKey = this.contents.keys().next().value;\n      if (firstKey === undefined) break;\n      this.contents.delete(firstKey);\n    }\n  }\n}\n\n/** インメモリの画像オペレーション実装。 */\nclass MemoryImageOps implements ImageCacheOps {\n  private store = new Map<string, StorageBinary>();\n  private totalBytes = 0;\n  private readonly maxItems: number | undefined;\n  private readonly maxSizeBytes: number | undefined;\n\n  constructor(options?: MemoryImageOptions) {\n    this.maxItems = options?.maxItems;\n    this.maxSizeBytes = options?.maxSizeBytes;\n  }\n\n  get(hash: string): Promise<StorageBinary | null> {\n    const entry = this.store.get(hash);\n    if (entry) touch(this.store, hash);\n    return Promise.resolve(entry ?? null);\n  }\n\n  set(hash: string, data: ArrayBuffer, contentType: string): Promise<void> {\n    const existing = this.store.get(hash);\n    if (existing) {\n      this.totalBytes -= existing.data.byteLength;\n      this.store.delete(hash);\n    }\n    this.store.set(hash, { data, contentType });\n    this.totalBytes += data.byteLength;\n    this.enforceLimit();\n    return Promise.resolve();\n  }\n\n  private enforceLimit(): void {\n    while (\n      (this.maxItems !== undefined && this.store.size > this.maxItems) ||\n      (this.maxSizeBytes !== undefined && this.totalBytes > this.maxSizeBytes)\n    ) {\n      const firstKey = this.store.keys().next().value;\n      if (firstKey === undefined) break;\n      const victim = this.store.get(firstKey);\n      if (victim) this.totalBytes -= victim.data.byteLength;\n      this.store.delete(firstKey);\n    }\n  }\n}\n\n/**\n * インメモリのキャッシュアダプタ。document + image 両方を担当する。\n * プロセス再起動でクリアされるため、ローカル開発・SSG ビルド・テスト用途。\n *\n * @example\n * cache: [memoryCache({ maxItems: 1000 })]\n */\nexport function memoryCache(options?: MemoryCacheOptions): CacheAdapter {\n  return {\n    name: \"memory\",\n    handles: [\"document\", \"image\"] as const,\n    doc: new MemoryDocumentOps(options),\n    img: new MemoryImageOps(options),\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"memory.mjs","names":[],"sources":["../../src/cache/memory.ts"],"sourcesContent":["import type {\n  BaseContentItem,\n  CacheAdapter,\n  CacheAdapterStats,\n  CacheAreaStats,\n  CachedItemContent,\n  CachedItemList,\n  CachedItemMeta,\n  DocumentCacheOps,\n  ImageCacheOps,\n  InvalidateScope,\n  StorageBinary,\n} from \"../types/index\";\n\nexport interface MemoryDocumentOptions {\n  /** アイテム保持上限。未指定時は上限なし。超過時は LRU で古いものから削除。 */\n  maxItems?: number;\n}\n\nexport interface MemoryImageOptions {\n  /** エントリ保持上限。未指定時は上限なし。超過時は LRU で古いものから削除。 */\n  maxItems?: number;\n  /** 合計保持サイズ上限（バイト）。未指定時は上限なし。超過時は LRU で古いものから削除。 */\n  maxSizeBytes?: number;\n}\n\nexport interface MemoryCacheOptions\n  extends MemoryDocumentOptions,\n    MemoryImageOptions {}\n\n/**\n * Map の挿入順を LRU として扱う軽量実装。\n * `touch` で既存キーを末尾に移動、`enforceLimit` で古いキー（先頭）から削除する。\n */\nfunction touch<K, V>(map: Map<K, V>, key: K): void {\n  const v = map.get(key);\n  if (v === undefined) return;\n  map.delete(key);\n  map.set(key, v);\n}\n\nconst itemKey = (collection: string, slug: string): string =>\n  `${collection}:${slug}`;\n\n/** インメモリのドキュメントオペレーション実装。プロセス再起動でクリアされる。 */\nclass MemoryDocumentOps implements DocumentCacheOps {\n  private lists = new Map<string, CachedItemList<BaseContentItem>>();\n  private metas = new Map<string, CachedItemMeta<BaseContentItem>>();\n  private contents = new Map<string, CachedItemContent>();\n  private readonly maxItems: number | undefined;\n  /** `cms.stats()` 用のヒット/ミス集計 (list+meta+content の合計)。 */\n  hits = 0;\n  misses = 0;\n\n  constructor(options?: MemoryDocumentOptions) {\n    this.maxItems = options?.maxItems;\n  }\n\n  /** 保持エントリ数 (list / meta / content の合計)。stats() で使う。 */\n  totalEntries(): number {\n    return this.lists.size + this.metas.size + this.contents.size;\n  }\n\n  getList<T extends BaseContentItem>(\n    collection: string,\n  ): Promise<CachedItemList<T> | null> {\n    const entry = this.lists.get(collection) as CachedItemList<T> | undefined;\n    if (entry) this.hits++;\n    else this.misses++;\n    return Promise.resolve(entry ?? null);\n  }\n\n  setList<T extends BaseContentItem>(\n    collection: string,\n    data: CachedItemList<T>,\n  ): Promise<void> {\n    this.lists.set(collection, data);\n    return Promise.resolve();\n  }\n\n  getMeta<T extends BaseContentItem>(\n    collection: string,\n    slug: string,\n  ): Promise<CachedItemMeta<T> | null> {\n    const key = itemKey(collection, slug);\n    const entry = this.metas.get(key) as CachedItemMeta<T> | undefined;\n    if (entry) {\n      touch(this.metas, key);\n      this.hits++;\n    } else {\n      this.misses++;\n    }\n    return Promise.resolve(entry ?? null);\n  }\n\n  setMeta<T extends BaseContentItem>(\n    collection: string,\n    slug: string,\n    data: CachedItemMeta<T>,\n  ): Promise<void> {\n    const key = itemKey(collection, slug);\n    if (this.metas.has(key)) this.metas.delete(key);\n    this.metas.set(key, data);\n    this.enforceLimit();\n    return Promise.resolve();\n  }\n\n  getContent(\n    collection: string,\n    slug: string,\n  ): Promise<CachedItemContent | null> {\n    const key = itemKey(collection, slug);\n    const entry = this.contents.get(key);\n    if (entry) {\n      touch(this.contents, key);\n      this.hits++;\n    } else {\n      this.misses++;\n    }\n    return Promise.resolve(entry ?? null);\n  }\n\n  setContent(\n    collection: string,\n    slug: string,\n    data: CachedItemContent,\n  ): Promise<void> {\n    const key = itemKey(collection, slug);\n    if (this.contents.has(key)) this.contents.delete(key);\n    this.contents.set(key, data);\n    this.enforceLimit();\n    return Promise.resolve();\n  }\n\n  invalidate(scope: InvalidateScope): Promise<void> {\n    if (scope === \"all\") {\n      this.lists.clear();\n      this.metas.clear();\n      this.contents.clear();\n      return Promise.resolve();\n    }\n    const kind = scope.kind ?? \"all\";\n    const collection = scope.collection;\n    if (\"slug\" in scope) {\n      const key = itemKey(collection, scope.slug);\n      if (kind === \"all\" || kind === \"meta\") this.metas.delete(key);\n      if (kind === \"all\" || kind === \"content\") this.contents.delete(key);\n      // 単一スラッグ無効化ではリストは触らない（リスト全体の整合は別管理）\n      return Promise.resolve();\n    }\n    // コレクション全体\n    if (kind === \"all\" || kind === \"meta\") {\n      this.lists.delete(collection);\n      const prefix = `${collection}:`;\n      for (const key of [...this.metas.keys()]) {\n        if (key.startsWith(prefix)) this.metas.delete(key);\n      }\n    }\n    if (kind === \"all\" || kind === \"content\") {\n      const prefix = `${collection}:`;\n      for (const key of [...this.contents.keys()]) {\n        if (key.startsWith(prefix)) this.contents.delete(key);\n      }\n    }\n    return Promise.resolve();\n  }\n\n  private enforceLimit(): void {\n    if (this.maxItems === undefined) return;\n    while (this.metas.size > this.maxItems) {\n      const firstKey = this.metas.keys().next().value;\n      if (firstKey === undefined) break;\n      this.metas.delete(firstKey);\n    }\n    while (this.contents.size > this.maxItems) {\n      const firstKey = this.contents.keys().next().value;\n      if (firstKey === undefined) break;\n      this.contents.delete(firstKey);\n    }\n  }\n}\n\n/** インメモリの画像オペレーション実装。 */\nclass MemoryImageOps implements ImageCacheOps {\n  private store = new Map<string, StorageBinary>();\n  private totalBytes = 0;\n  private readonly maxItems: number | undefined;\n  private readonly maxSizeBytes: number | undefined;\n  /** `cms.stats()` 用のヒット/ミス集計。 */\n  hits = 0;\n  misses = 0;\n\n  constructor(options?: MemoryImageOptions) {\n    this.maxItems = options?.maxItems;\n    this.maxSizeBytes = options?.maxSizeBytes;\n  }\n\n  get(hash: string): Promise<StorageBinary | null> {\n    const entry = this.store.get(hash);\n    if (entry) {\n      touch(this.store, hash);\n      this.hits++;\n    } else {\n      this.misses++;\n    }\n    return Promise.resolve(entry ?? null);\n  }\n\n  /** stats() 用に、現在の保持エントリ数と合計バイト数を返す。 */\n  snapshot(): { entries: number; sizeBytes: number } {\n    return { entries: this.store.size, sizeBytes: this.totalBytes };\n  }\n\n  set(hash: string, data: ArrayBuffer, contentType: string): Promise<void> {\n    const existing = this.store.get(hash);\n    if (existing) {\n      this.totalBytes -= existing.data.byteLength;\n      this.store.delete(hash);\n    }\n    this.store.set(hash, { data, contentType });\n    this.totalBytes += data.byteLength;\n    this.enforceLimit();\n    return Promise.resolve();\n  }\n\n  private enforceLimit(): void {\n    while (\n      (this.maxItems !== undefined && this.store.size > this.maxItems) ||\n      (this.maxSizeBytes !== undefined && this.totalBytes > this.maxSizeBytes)\n    ) {\n      const firstKey = this.store.keys().next().value;\n      if (firstKey === undefined) break;\n      const victim = this.store.get(firstKey);\n      if (victim) this.totalBytes -= victim.data.byteLength;\n      this.store.delete(firstKey);\n    }\n  }\n}\n\n/**\n * インメモリのキャッシュアダプタ。document + image 両方を担当する。\n * プロセス再起動でクリアされるため、ローカル開発・SSG ビルド・テスト用途。\n *\n * `stats()` でヒット率・エントリ数・画像合計バイト数を返す。\n *\n * @example\n * cache: [memoryCache({ maxItems: 1000 })]\n */\nexport function memoryCache(options?: MemoryCacheOptions): CacheAdapter {\n  const doc = new MemoryDocumentOps(options);\n  const img = new MemoryImageOps(options);\n  return {\n    name: \"memory\",\n    handles: [\"document\", \"image\"] as const,\n    doc,\n    img,\n    async stats(): Promise<CacheAdapterStats> {\n      const imgSnap = img.snapshot();\n      const docArea: CacheAreaStats = {\n        hits: doc.hits,\n        misses: doc.misses,\n        entries: doc.totalEntries(),\n      };\n      const imgArea: CacheAreaStats = {\n        hits: img.hits,\n        misses: img.misses,\n        entries: imgSnap.entries,\n        sizeBytes: imgSnap.sizeBytes,\n      };\n      return { name: \"memory\", doc: docArea, img: imgArea };\n    },\n  };\n}\n"],"mappings":";;;;;AAkCA,SAAS,MAAY,KAAgB,KAAc;CACjD,MAAM,IAAI,IAAI,IAAI,GAAG;CACrB,IAAI,MAAM,KAAA,GAAW;CACrB,IAAI,OAAO,GAAG;CACd,IAAI,IAAI,KAAK,CAAC;AAChB;AAEA,MAAM,WAAW,YAAoB,SACnC,GAAG,WAAW,GAAG;;AAGnB,IAAM,oBAAN,MAAoD;CAClD,wBAAgB,IAAI,IAA6C;CACjE,wBAAgB,IAAI,IAA6C;CACjE,2BAAmB,IAAI,IAA+B;CACtD;;CAEA,OAAO;CACP,SAAS;CAET,YAAY,SAAiC;EAC3C,KAAK,WAAW,SAAS;CAC3B;;CAGA,eAAuB;EACrB,OAAO,KAAK,MAAM,OAAO,KAAK,MAAM,OAAO,KAAK,SAAS;CAC3D;CAEA,QACE,YACmC;EACnC,MAAM,QAAQ,KAAK,MAAM,IAAI,UAAU;EACvC,IAAI,OAAO,KAAK;OACX,KAAK;EACV,OAAO,QAAQ,QAAQ,SAAS,IAAI;CACtC;CAEA,QACE,YACA,MACe;EACf,KAAK,MAAM,IAAI,YAAY,IAAI;EAC/B,OAAO,QAAQ,QAAQ;CACzB;CAEA,QACE,YACA,MACmC;EACnC,MAAM,MAAM,QAAQ,YAAY,IAAI;EACpC,MAAM,QAAQ,KAAK,MAAM,IAAI,GAAG;EAChC,IAAI,OAAO;GACT,MAAM,KAAK,OAAO,GAAG;GACrB,KAAK;EACP,OACE,KAAK;EAEP,OAAO,QAAQ,QAAQ,SAAS,IAAI;CACtC;CAEA,QACE,YACA,MACA,MACe;EACf,MAAM,MAAM,QAAQ,YAAY,IAAI;EACpC,IAAI,KAAK,MAAM,IAAI,GAAG,GAAG,KAAK,MAAM,OAAO,GAAG;EAC9C,KAAK,MAAM,IAAI,KAAK,IAAI;EACxB,KAAK,aAAa;EAClB,OAAO,QAAQ,QAAQ;CACzB;CAEA,WACE,YACA,MACmC;EACnC,MAAM,MAAM,QAAQ,YAAY,IAAI;EACpC,MAAM,QAAQ,KAAK,SAAS,IAAI,GAAG;EACnC,IAAI,OAAO;GACT,MAAM,KAAK,UAAU,GAAG;GACxB,KAAK;EACP,OACE,KAAK;EAEP,OAAO,QAAQ,QAAQ,SAAS,IAAI;CACtC;CAEA,WACE,YACA,MACA,MACe;EACf,MAAM,MAAM,QAAQ,YAAY,IAAI;EACpC,IAAI,KAAK,SAAS,IAAI,GAAG,GAAG,KAAK,SAAS,OAAO,GAAG;EACpD,KAAK,SAAS,IAAI,KAAK,IAAI;EAC3B,KAAK,aAAa;EAClB,OAAO,QAAQ,QAAQ;CACzB;CAEA,WAAW,OAAuC;EAChD,IAAI,UAAU,OAAO;GACnB,KAAK,MAAM,MAAM;GACjB,KAAK,MAAM,MAAM;GACjB,KAAK,SAAS,MAAM;GACpB,OAAO,QAAQ,QAAQ;EACzB;EACA,MAAM,OAAO,MAAM,QAAQ;EAC3B,MAAM,aAAa,MAAM;EACzB,IAAI,UAAU,OAAO;GACnB,MAAM,MAAM,QAAQ,YAAY,MAAM,IAAI;GAC1C,IAAI,SAAS,SAAS,SAAS,QAAQ,KAAK,MAAM,OAAO,GAAG;GAC5D,IAAI,SAAS,SAAS,SAAS,WAAW,KAAK,SAAS,OAAO,GAAG;GAElE,OAAO,QAAQ,QAAQ;EACzB;EAEA,IAAI,SAAS,SAAS,SAAS,QAAQ;GACrC,KAAK,MAAM,OAAO,UAAU;GAC5B,MAAM,SAAS,GAAG,WAAW;GAC7B,KAAK,MAAM,OAAO,CAAC,GAAG,KAAK,MAAM,KAAK,CAAC,GACrC,IAAI,IAAI,WAAW,MAAM,GAAG,KAAK,MAAM,OAAO,GAAG;EAErD;EACA,IAAI,SAAS,SAAS,SAAS,WAAW;GACxC,MAAM,SAAS,GAAG,WAAW;GAC7B,KAAK,MAAM,OAAO,CAAC,GAAG,KAAK,SAAS,KAAK,CAAC,GACxC,IAAI,IAAI,WAAW,MAAM,GAAG,KAAK,SAAS,OAAO,GAAG;EAExD;EACA,OAAO,QAAQ,QAAQ;CACzB;CAEA,eAA6B;EAC3B,IAAI,KAAK,aAAa,KAAA,GAAW;EACjC,OAAO,KAAK,MAAM,OAAO,KAAK,UAAU;GACtC,MAAM,WAAW,KAAK,MAAM,KAAK,EAAE,KAAK,EAAE;GAC1C,IAAI,aAAa,KAAA,GAAW;GAC5B,KAAK,MAAM,OAAO,QAAQ;EAC5B;EACA,OAAO,KAAK,SAAS,OAAO,KAAK,UAAU;GACzC,MAAM,WAAW,KAAK,SAAS,KAAK,EAAE,KAAK,EAAE;GAC7C,IAAI,aAAa,KAAA,GAAW;GAC5B,KAAK,SAAS,OAAO,QAAQ;EAC/B;CACF;AACF;;AAGA,IAAM,iBAAN,MAA8C;CAC5C,wBAAgB,IAAI,IAA2B;CAC/C,aAAqB;CACrB;CACA;;CAEA,OAAO;CACP,SAAS;CAET,YAAY,SAA8B;EACxC,KAAK,WAAW,SAAS;EACzB,KAAK,eAAe,SAAS;CAC/B;CAEA,IAAI,MAA6C;EAC/C,MAAM,QAAQ,KAAK,MAAM,IAAI,IAAI;EACjC,IAAI,OAAO;GACT,MAAM,KAAK,OAAO,IAAI;GACtB,KAAK;EACP,OACE,KAAK;EAEP,OAAO,QAAQ,QAAQ,SAAS,IAAI;CACtC;;CAGA,WAAmD;EACjD,OAAO;GAAE,SAAS,KAAK,MAAM;GAAM,WAAW,KAAK;EAAW;CAChE;CAEA,IAAI,MAAc,MAAmB,aAAoC;EACvE,MAAM,WAAW,KAAK,MAAM,IAAI,IAAI;EACpC,IAAI,UAAU;GACZ,KAAK,cAAc,SAAS,KAAK;GACjC,KAAK,MAAM,OAAO,IAAI;EACxB;EACA,KAAK,MAAM,IAAI,MAAM;GAAE;GAAM;EAAY,CAAC;EAC1C,KAAK,cAAc,KAAK;EACxB,KAAK,aAAa;EAClB,OAAO,QAAQ,QAAQ;CACzB;CAEA,eAA6B;EAC3B,OACG,KAAK,aAAa,KAAA,KAAa,KAAK,MAAM,OAAO,KAAK,YACtD,KAAK,iBAAiB,KAAA,KAAa,KAAK,aAAa,KAAK,cAC3D;GACA,MAAM,WAAW,KAAK,MAAM,KAAK,EAAE,KAAK,EAAE;GAC1C,IAAI,aAAa,KAAA,GAAW;GAC5B,MAAM,SAAS,KAAK,MAAM,IAAI,QAAQ;GACtC,IAAI,QAAQ,KAAK,cAAc,OAAO,KAAK;GAC3C,KAAK,MAAM,OAAO,QAAQ;EAC5B;CACF;AACF;;;;;;;;;;AAWA,SAAgB,YAAY,SAA4C;CACtE,MAAM,MAAM,IAAI,kBAAkB,OAAO;CACzC,MAAM,MAAM,IAAI,eAAe,OAAO;CACtC,OAAO;EACL,MAAM;EACN,SAAS,CAAC,YAAY,OAAO;EAC7B;EACA;EACA,MAAM,QAAoC;GACxC,MAAM,UAAU,IAAI,SAAS;GAY7B,OAAO;IAAE,MAAM;IAAU,KAAK;KAV5B,MAAM,IAAI;KACV,QAAQ,IAAI;KACZ,SAAS,IAAI,aAAa;IAQQ;IAAG,KAAK;KAL1C,MAAM,IAAI;KACV,QAAQ,IAAI;KACZ,SAAS,QAAQ;KACjB,WAAW,QAAQ;IAE6B;GAAE;EACtD;CACF;AACF"}

package/dist/{cache-DS81aOcC.d.mts → cache-v9jTMnYd.d.mts}

@@ -98,6 +98,17 @@ interface DataSource<T extends BaseContentItem = BaseContentItem> {
  * ドキュメントキャッシュ用のオペレーション群。
  * `CacheAdapter.doc` に実装する。collection 名は引数で渡されるので、
  * アダプタ側で `{collection}:{slug}` のようなキー戦略を組み立てる。
+ *
+ * core 側の役割:
+ * - SWR ロジックは core の `CollectionClient` が制御し、TTL 切れの判定や差分検出を行う。
+ *   adapter は読み書きと無効化を実装するだけ。
+ * - `invalidate(scope)` の `scope` は `"all"`、コレクション全体、または単一 slug の 3 形態。
+ *   `kind: "meta" | "content" | "all"` で削除粒度を指定する。
+ *
+ * adapter 側で気をつけること:
+ * - I/O 失敗は `CMSError(code: "cache/io_failed")` でラップしてから throw する (生の Error を投げない)
+ * - 値は JSON シリアライズ可能とは限らない (例: `CachedItemContent.bodyHtml`)。バイナリ安全に保存する
+ * - 並列書き込みは core では制御しないので、必要なら adapter 内部でロック / トランザクションを取る
  */
 interface DocumentCacheOps {
   getList<T extends BaseContentItem>(collection: string): Promise<CachedItemList<T> | null>;
@@ -108,30 +119,80 @@ interface DocumentCacheOps {
   setContent(collection: string, slug: string, data: CachedItemContent): Promise<void>;
   invalidate(scope: InvalidateScope): Promise<void>;
 }
-/** 画像キャッシュ用のオペレーション群。`CacheAdapter.img` に実装する。 */
+/**
+ * 画像キャッシュ用のオペレーション群。`CacheAdapter.img` に実装する。
+ *
+ * 責務境界:
+ * - hash 計算と HTTP fetch は core (`fetchAndCacheImage` / `buildCacheImageFn`) が担当する。
+ *   adapter は `hash` をキーにしたバイナリの永続化だけを担う。
+ * - `RenderContext.cacheImage(url)` (=`cms.cacheImage`) は core 側の合成関数で、
+ *   「URL → SHA256 → adapter.set → プロキシ URL」を 1 ステップにまとめたもの。
+ *   adapter から呼び出してはいけない (依存方向の逆転になる)。
+ * - 読み取りは miss を `null` で返す。例外を投げないこと (上位の SWR が壊れる)。
+ * - 書き込みは I/O 失敗時に `CMSError(code: "cache/io_failed")` でラップ可能だが、
+ *   画像系は fail-soft 推奨 (失敗時は通常 fetch にフォールバックする想定)。
+ */
 interface ImageCacheOps {
   get(hash: string): Promise<StorageBinary | null>;
   set(hash: string, data: ArrayBuffer, contentType: string): Promise<void>;
 }
+/**
+ * 1 領域 (document / image) ぶんのキャッシュ統計。
+ * `CacheAdapter.stats()` の戻り値 / `cms.stats()` の集約形に使う。
+ */
+interface CacheAreaStats {
+  /** キャッシュヒット回数 (起動から累積)。 */
+  hits: number;
+  /** キャッシュミス回数 (起動から累積)。 */
+  misses: number;
+  /** 保持エントリ数。集計不可な adapter は省略可。 */
+  entries?: number;
+  /** 保持データの合計バイト数。集計不可な adapter は省略可。 */
+  sizeBytes?: number;
+}
+/**
+ * `CacheAdapter.stats()` が返す統計。document / image を併せ持つ adapter は両方を返す。
+ * adapter が `handles` に含めていない領域は省略する。
+ */
+interface CacheAdapterStats {
+  /** adapter 名 (`CacheAdapter.name` と同値)。`cms.stats()` 側で識別用に保持する。 */
+  name?: string;
+  doc?: CacheAreaStats;
+  img?: CacheAreaStats;
+}
 /**
  * 統一キャッシュアダプタ。`handles` で担当領域を申告し、
  * `doc` / `img` のいずれか（または両方）を実装する。
  *
- * `createClient({ cache })` には `CacheAdapter | CacheAdapter[]` を渡せる。
- * 配列で渡された場合、core は `handles` を見て document / image をそれぞれ別アダプタに振り分ける。
+ * `createClient({ cache })` には `CacheAdapter[]` を渡す (単一 adapter でも配列で渡す)。
+ *
+ * `handles` の判定ルール:
+ * - core は配列を先頭から走査し、`handles.includes("document")` を満たす最初の adapter を
+ *   document 担当に、`handles.includes("image")` を満たす最初の adapter を image 担当に割り当てる
+ * - 同じ adapter が両方の `handles` を持つ場合は単独で両領域を担当する (memoryCache はこの形)
+ * - 領域を申告する一方で対応する `doc` / `img` を実装していない場合、その領域では先勝ちにならず
+ *   次の adapter が候補になる
  *
  * @example
- * cache: memoryCache()                           // doc + image 両方
- * cache: r2Cache({ bucket })                      // image のみ
- * cache: kvCache({ namespace })                   // document のみ
- * cache: [kvCache({ ns }), r2Cache({ bucket })]   // 個別に組み合わせ
+ * cache: [memoryCache()]                          // doc + image 両方
+ * cache: [r2Cache({ bucket })]                    // image のみ
+ * cache: [kvCache({ namespace })]                 // document のみ
+ * cache: [kvCache({ ns }), r2Cache({ bucket })]   // KV: doc / R2: image を個別配線
+ *
+ * オプションの `stats()` を実装すると `cms.stats()` 経由でヒット率・サイズが取得できる。
+ * 未実装の adapter は集計から除外される (`cms.stats()` の戻り値で undefined になる)。
  */
 interface CacheAdapter {
   readonly name: string;
   readonly handles: readonly ("document" | "image")[];
   doc?: DocumentCacheOps;
   img?: ImageCacheOps;
+  /**
+   * キャッシュ統計を返す任意のフック。
+   * adapter が hit/miss を集計していない場合は実装しない (cms.stats() 側で無視される)。
+   */
+  stats?(): Promise<CacheAdapterStats>;
 }
 //#endregion
-export { InvalidateKind as a, PropertyMap as c, DataSource as i, WebhookConfig as l, DocumentCacheOps as n, InvalidateScope as o, ImageCacheOps as r, PropertyDef as s, CacheAdapter as t };
-//# sourceMappingURL=cache-DS81aOcC.d.mts.map
+export { ImageCacheOps as a, InvalidateScope as c, WebhookConfig as d, DocumentCacheOps as i, PropertyDef as l, CacheAdapterStats as n, DataSource as o, CacheAreaStats as r, InvalidateKind as s, CacheAdapter as t, PropertyMap as u };
+//# sourceMappingURL=cache-v9jTMnYd.d.mts.map

package/dist/{config-DYxyW3SR.d.mts → config-i99tKRhN.d.mts}

@@ -1,6 +1,6 @@
 import { t as BaseContentItem } from "./content-DwsfWZao.mjs";
-import { i as DataSource, t as CacheAdapter } from "./cache-DS81aOcC.mjs";
-import { i as CMSHooks, r as Logger, t as CMSPlugin } from "./plugin-Dct12kp2.mjs";
+import { o as DataSource, t as CacheAdapter } from "./cache-v9jTMnYd.mjs";
+import { a as CMSHooks, i as Logger, t as CMSPlugin } from "./plugin-BmrOz8T6.mjs";
 
 //#region src/types/sources.d.ts
 /**
@@ -59,7 +59,14 @@ interface SWRConfig {
   /** SWR の有効期間 (ミリ秒)。未設定時は TTL なし（失効まで stale を返す）。 */
   ttlMs?: number;
 }
-/** レートリミット・リトライ設定。 */
+/**
+ * `RateLimiterConfig` のデフォルト値 (Issue #313 / M2)。
+ * 型からだけでは見えない既定値を表面化することで、IDE 補完と
+ * preset の対称化 (`nodePreset` / `cloudflarePreset` / `nextPreset`) で
+ * 同じ既定が適用されることを保証する。
+ */
+declare const DEFAULT_RATE_LIMITER: Required<RateLimiterConfig>;
+/** レートリミット・リトライ設定。既定値は {@link DEFAULT_RATE_LIMITER}。 */
 interface RateLimiterConfig {
   /** 同時実行数の上限。デフォルト: 3 */
   maxConcurrent?: number;
@@ -90,6 +97,34 @@ interface CollectionDef<T extends BaseContentItem = BaseContentItem> {
   /** コレクション固有のライフサイクルフック。グローバル hooks の後に実行される。 */
   hooks?: CMSHooks<T>;
 }
+/**
+ * `CollectionDef` の strict 版。`slugField` / `statusField` が `keyof T & string` で
+ * 型ガードされており、誤フィールド名は型エラーになる (Issue #314 / M3)。
+ * CLI 生成スキーマや `defineCollection<T>()` 経由で利用される。
+ */
+interface StrictCollectionDef<T extends BaseContentItem> extends Omit<CollectionDef<T>, "slugField" | "statusField"> {
+  /** slug として使う TS フィールド名。`keyof T` で型ガードされる。 */
+  slugField: keyof T & string;
+  /** ステータスとして使う TS フィールド名。`keyof T` で型ガードされる。 */
+  statusField?: keyof T & string;
+}
+/**
+ * 型推論ヘルパー: `T` を明示してコレクション定義を作る。`slugField` / `statusField` は
+ * `keyof T & string` で補完・型ガードされ、誤フィールド名 (例: `"slag"`) で型エラーになる
+ * (Issue #314 / M3)。CLI 生成 `nhc.schema.ts` で利用される。
+ *
+ * @example
+ * ```ts
+ * type PostItem = BaseContentItem & { authorName?: string };
+ * const posts = defineCollection<PostItem>({
+ *   source: notionSource(...),
+ *   slugField: "slug",     // OK
+ *   statusField: "status", // OK
+ *   // statusField: "stat", // 型エラー
+ * });
+ * ```
+ */
+declare function defineCollection<T extends BaseContentItem>(def: StrictCollectionDef<T>): CollectionDef<T>;
 /**
  * `createClient({ collections })` の map 型。
  * キーがコレクション名、値が `CollectionDef<T>`。
@@ -146,5 +181,5 @@ interface CreateClientOptions<S extends CMSSources = CMSSources> {
   content?: ContentConfig;
 }
 //#endregion
-export { InferCollectionItem as a, RenderOptions as c, SWRConfig as d, CMSAdapter as f, CreateClientOptions as i, RendererFn as l, MergeSourceCollections as m, CollectionsConfig as n, LogLevel as o, CMSSources as p, ContentConfig as r, RateLimiterConfig as s, CollectionDef as t, RendererPluginList as u };
-//# sourceMappingURL=config-DYxyW3SR.d.mts.map
+export { MergeSourceCollections as _, DEFAULT_RATE_LIMITER as a, RateLimiterConfig as c, RendererPluginList as d, SWRConfig as f, CMSSources as g, CMSAdapter as h, CreateClientOptions as i, RenderOptions as l, defineCollection as m, CollectionsConfig as n, InferCollectionItem as o, StrictCollectionDef as p, ContentConfig as r, LogLevel as s, CollectionDef as t, RendererFn as u };
+//# sourceMappingURL=config-i99tKRhN.d.mts.map

package/dist/errors.mjs

@@ -1,4 +1,138 @@
 //#region src/errors.ts
+/**
+* 組み込みエラーコードごとのドキュメント URL アンカーと既定の次アクション。
+* `CMSError` コンストラクタが呼び出し側の `docsUrl` / `nextSteps` 未指定時のフォールバックに使用する。
+*
+* `docs/ja/errors/index.md` の各セクション ID と同期させること。
+*/
+const ERROR_DOCS_BASE = "https://github.com/kjfsm/notion-headless-cms/blob/main/docs/ja/errors/index.md";
+const BUILT_IN_ERROR_HELP = {
+	"core/config_invalid": {
+		docsAnchor: "core-config_invalid",
+		nextSteps: ["createClient の必須オプション (sources / collections) を確認する", "NOTION_TOKEN が環境変数または .dev.vars に設定されているか確認する"]
+	},
+	"core/schema_invalid": {
+		docsAnchor: "core-schema_invalid",
+		nextSteps: ["nhc generate を再実行して schema を最新化する", "PropertyMap / PropertyDef の型が定義どおりか確認する"]
+	},
+	"core/notion_orm_missing": {
+		docsAnchor: "core-notion_orm_missing",
+		nextSteps: ["@notion-headless-cms/notion-orm をインストールする", "実行ランタイムが動的 import を許可しているか確認する"]
+	},
+	"core/sort_unsupported_type": {
+		docsAnchor: "core-sort_unsupported_type",
+		nextSteps: ["sort.by に指定したフィールドの値型が string / number になっているか確認する", "別フィールドでソートするか、source 側で正規化する"]
+	},
+	"webhook/signature_invalid": {
+		docsAnchor: "webhook-signature_invalid",
+		nextSteps: ["Notion 側で発行された webhook secret が一致しているか確認する", "プロキシ / WAF がリクエストボディを書き換えていないか確認する"]
+	},
+	"webhook/payload_invalid": {
+		docsAnchor: "webhook-payload_invalid",
+		nextSteps: ["リクエストボディが JSON で送信されているか確認する", "DataSource.parseWebhook の期待するフィールド構造と一致しているか確認する"]
+	},
+	"webhook/unknown_collection": {
+		docsAnchor: "webhook-unknown_collection",
+		nextSteps: ["createClient の sources / collections に該当 collection が登録されているか確認する", "Webhook URL が `?collection=` で正しいコレクション名を指しているか確認する"]
+	},
+	"webhook/not_implemented": {
+		docsAnchor: "webhook-not_implemented",
+		nextSteps: ["対象 collection の DataSource に parseWebhook を実装する", "Webhook を使わない場合は cms.invalidate() を直接呼ぶ運用に切り替える"]
+	},
+	"source/fetch_items_failed": {
+		docsAnchor: "source-fetch_items_failed",
+		nextSteps: [
+			"NOTION_TOKEN がインテグレーションに紐づいているか確認する",
+			"Notion DB がインテグレーションに接続済みか確認する",
+			"ネットワーク / Notion API の障害状況 (status.notion.so) を確認する",
+			"rateLimiter.maxRetries / baseDelayMs を調整してリトライ余地を増やす"
+		]
+	},
+	"source/fetch_item_failed": {
+		docsAnchor: "source-fetch_item_failed",
+		nextSteps: ["slug プロパティが Notion DB に存在し、値がユニークか確認する", "対象ページがインテグレーションに共有されているか確認する"]
+	},
+	"source/load_markdown_failed": {
+		docsAnchor: "source-load_markdown_failed",
+		nextSteps: ["対象ページがアーカイブされていないか確認する", "未対応ブロック (file / video など) が原因なら fetch 戦略を `markdownFetcher()` に切り替えるか、対象ブロックを除外する"]
+	},
+	"source/load_blocks_failed": {
+		docsAnchor: "source-load_blocks_failed",
+		nextSteps: ["対象ページが削除 / アーカイブされていないか確認する", "Notion API の rate limit に当たっていないかログで確認する"]
+	},
+	"source/blocks_unsupported": {
+		docsAnchor: "source-blocks_unsupported",
+		nextSteps: ["react-renderer を使う場合は fetch 戦略を `fetchBlockTree()` に切り替える", "あるいは markdown 経路で本文表示にフォールバックする"]
+	},
+	"cache/io_failed": {
+		docsAnchor: "cache-io_failed",
+		nextSteps: [
+			"KV / R2 / メモリキャッシュの binding (env.DOC_CACHE / env.IMG_BUCKET) が正しいか確認する",
+			"wrangler.toml の binding 名と createClient に渡した env が一致しているか確認する",
+			"一時的な障害なら SWR が次回読み込み時に自己回復する"
+		]
+	},
+	"cache/image_fetch_failed": {
+		docsAnchor: "cache-image_fetch_failed",
+		nextSteps: ["Notion 署名 URL の有効期限 (約 1 時間) が切れていないか確認する", "Worker / Node のアウトバウンドネットワークが許可されているか確認する"]
+	},
+	"cache/image_invalid_content_type": {
+		docsAnchor: "cache-image_invalid_content_type",
+		nextSteps: ["Notion 画像 URL を直接ブラウザで開いて image/* を返すか確認する", "プロキシ / CDN が Content-Type を書き換えていないか確認する"]
+	},
+	"renderer/failed": {
+		docsAnchor: "renderer-failed",
+		nextSteps: ["renderer に渡している remark / rehype プラグインの組み合わせを確認する", "fetch 戦略と renderer の組み合わせが整合しているか (Notion enhanced markdown には notionMarkdownRenderer が必要) を確認する"]
+	},
+	"swr/item_check_failed": {
+		docsAnchor: "swr-item_check_failed",
+		nextSteps: ["ログで cause を確認し、source/fetch_item_failed と同じ手順で原因を切り分ける", "バックグラウンドの失敗は次回 SWR で自動再試行されるため恒久対処不要なケースもある"]
+	},
+	"swr/list_check_failed": {
+		docsAnchor: "swr-list_check_failed",
+		nextSteps: ["ログで cause を確認し、source/fetch_items_failed と同じ手順で原因を切り分ける", "Notion API の rate limit に近い場合は rateLimiter を絞る"]
+	},
+	"swr/content_rebuild_failed": {
+		docsAnchor: "swr-content_rebuild_failed",
+		nextSteps: ["renderer / loadMarkdown が一時的に失敗しただけならログを確認のうえ放置可", "恒常的に再発する場合は対象 slug を fresh: true で取り直して再現を確認する"]
+	},
+	"cli/config_invalid": {
+		docsAnchor: "cli-config_invalid",
+		nextSteps: ["nhc.config.ts が defineConfig() を default export しているか確認する", "collections に少なくとも 1 件、databaseId または dbName が指定されているか確認する"]
+	},
+	"cli/config_load_failed": {
+		docsAnchor: "cli-config_load_failed",
+		nextSteps: ["nhc.config.ts に構文エラーがないか tsc / エディタで確認する", "ESM の import パスが拡張子付き (.js) になっているか確認する"]
+	},
+	"cli/schema_invalid": {
+		docsAnchor: "cli-schema_invalid",
+		nextSteps: ["Notion DB のプロパティ型が CLI 対応 (title / richText / select / status / multiSelect / date / number / checkbox / url) のいずれかか確認する", "未対応プロパティをスキップするか、Notion 側で型を変える"]
+	},
+	"cli/generate_failed": {
+		docsAnchor: "cli-generate_failed",
+		nextSteps: ["--verbose を付けて再実行し、失敗箇所のスタックトレースを確認する", "出力先ディレクトリの書き込み権限を確認する"]
+	},
+	"cli/init_failed": {
+		docsAnchor: "cli-init_failed",
+		nextSteps: ["出力先パスに既存ファイルがある場合は --force を付けるか別パスを指定する", "親ディレクトリの書き込み権限を確認する"]
+	},
+	"cli/notion_api_failed": {
+		docsAnchor: "cli-notion_api_failed",
+		nextSteps: [
+			"NOTION_TOKEN がインテグレーションに紐づいているか確認する",
+			"対象 DB がインテグレーションに接続されているか (Notion DB → … → Connections) 確認する",
+			"DB 名で解決している場合は完全一致 (前後空白 / 全角半角) を確認する",
+			"--verbose で Notion API レスポンスの status / code を確認する"
+		]
+	},
+	"cli/env_file_not_found": {
+		docsAnchor: "cli-env_file_not_found",
+		nextSteps: ["--env-file で指定したパスを実ファイルパスで確認する", "プロジェクトルートで実行しているか (相対パスは cwd 基準)"]
+	}
+};
+function lookupBuiltInHelp(code) {
+	return BUILT_IN_ERROR_HELP[code];
+}
 var CMSError = class extends Error {
 	code;
 	cause;
@@ -13,8 +147,9 @@ var CMSError = class extends Error {
 		this.code = params.code;
 		this.cause = params.cause;
 		this.context = params.context;
-		this.nextSteps = params.nextSteps;
-		this.docsUrl = params.docsUrl;
+		const help = lookupBuiltInHelp(params.code);
+		this.nextSteps = params.nextSteps ?? help?.nextSteps;
+		this.docsUrl = params.docsUrl ?? (help ? `${ERROR_DOCS_BASE}#${help.docsAnchor}` : void 0);
 	}
 	/** エラーコードが指定した値と一致するか判定する。 */
 	is(code) {

package/dist/errors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * ライブラリ組み込みの CMS エラーコード。\n *\n * | コード | 発生条件 |\n * |---|---|\n * | `core/config_invalid` | 設定不備（token 未設定など） |\n * | `core/schema_invalid` | schema/mapping の型不整合 |\n * | `core/notion_orm_missing` | `@notion-headless-cms/notion-orm` の動的ロード失敗 |\n * | `core/sort_unsupported_type` | ソートキーの値型が string / number でない |\n * | `webhook/signature_invalid` | Webhook 署名検証失敗 |\n * | `webhook/payload_invalid` | Webhook ペイロード形式不正 |\n * | `webhook/unknown_collection` | Webhook の対象コレクションが未知 |\n * | `webhook/not_implemented` | DataSource が parseWebhook を実装していない |\n * | `source/fetch_items_failed` | `DataSource.list()` 失敗 |\n * | `source/fetch_item_failed` | `DataSource.findByProp()` 失敗 |\n * | `source/load_markdown_failed` | `DataSource.loadMarkdown()` 失敗 |\n * | `source/load_blocks_failed` | `DataSource.loadBlocks()` 失敗 |\n * | `source/blocks_unsupported` | 選択した fetch 戦略が NotionBlockTree 取得を提供していない (markdown 戦略選択時など) |\n * | `cache/io_failed` | document / image キャッシュの I/O 失敗 |\n * | `cache/image_fetch_failed` | Notion 画像の HTTP 取得失敗 |\n * | `cache/image_invalid_content_type` | 画像レスポンスの Content-Type が不正 |\n * | `renderer/failed` | Markdown → HTML 変換失敗 |\n * | `swr/item_check_failed` | SWR バックグラウンドのアイテム差分チェック失敗 |\n * | `swr/list_check_failed` | SWR バックグラウンドのリスト差分チェック失敗 |\n * | `swr/content_rebuild_failed` | SWR バックグラウンドの本文再生成失敗 |\n * | `cli/config_invalid` | `nhc.config.ts` の内容不整合 |\n * | `cli/config_load_failed` | 設定ファイルの読み込み / 評価失敗 |\n * | `cli/schema_invalid` | CLI が受け取ったスキーマ / マッピング不整合 |\n * | `cli/generate_failed` | `nhc generate` の処理失敗 |\n * | `cli/init_failed` | `nhc init` の処理失敗 |\n * | `cli/notion_api_failed` | CLI が Notion API を呼び出す際の失敗 |\n * | `cli/env_file_not_found` | `--env-file` で指定したファイルが存在しない |\n *\n * サードパーティアダプタが独自コードを追加したい場合は `CMSErrorCode` を参照。\n */\nexport type BuiltInCMSErrorCode =\n  | \"core/config_invalid\"\n  | \"core/schema_invalid\"\n  | \"core/notion_orm_missing\"\n  | \"core/sort_unsupported_type\"\n  | \"webhook/signature_invalid\"\n  | \"webhook/payload_invalid\"\n  | \"webhook/unknown_collection\"\n  | \"webhook/not_implemented\"\n  | \"source/fetch_items_failed\"\n  | \"source/fetch_item_failed\"\n  | \"source/load_markdown_failed\"\n  | \"source/load_blocks_failed\"\n  | \"source/blocks_unsupported\"\n  | \"cache/io_failed\"\n  | \"cache/image_fetch_failed\"\n  | \"cache/image_invalid_content_type\"\n  | \"renderer/failed\"\n  | \"swr/item_check_failed\"\n  | \"swr/list_check_failed\"\n  | \"swr/content_rebuild_failed\"\n  | \"cli/config_invalid\"\n  | \"cli/config_load_failed\"\n  | \"cli/schema_invalid\"\n  | \"cli/generate_failed\"\n  | \"cli/init_failed\"\n  | \"cli/notion_api_failed\"\n  | \"cli/env_file_not_found\";\n\n/**\n * CMS エラーコード。\n * `BuiltInCMSErrorCode` のリテラル補完を維持しつつ、\n * サードパーティアダプタが独自コードを定義できるよう `string & {}` で拡張可能にする。\n */\nexport type CMSErrorCode = BuiltInCMSErrorCode | (string & {});\n\nexport interface CMSErrorContext {\n  operation: string;\n  slug?: string;\n  dataSourceId?: string;\n  pageId?: string;\n  [key: string]: string | number | boolean | null | undefined;\n}\n\nexport class CMSError extends Error {\n  readonly code: CMSErrorCode;\n  override readonly cause?: unknown;\n  readonly context: CMSErrorContext;\n  /** エラーを解消するための次のアクション（表示用）。 */\n  readonly nextSteps?: readonly string[];\n  /** 詳細ドキュメントへの URL（表示用）。 */\n  readonly docsUrl?: string;\n\n  constructor(params: {\n    code: CMSErrorCode;\n    message: string;\n    cause?: unknown;\n    context: CMSErrorContext;\n    nextSteps?: readonly string[];\n    docsUrl?: string;\n  }) {\n    super(params.message, { cause: params.cause });\n    this.name = \"CMSError\";\n    this.code = params.code;\n    this.cause = params.cause;\n    this.context = params.context;\n    this.nextSteps = params.nextSteps;\n    this.docsUrl = params.docsUrl;\n  }\n\n  /** エラーコードが指定した値と一致するか判定する。 */\n  is(code: CMSErrorCode): boolean {\n    return this.code === code;\n  }\n\n  /** エラーコードが指定した名前空間に属するか判定する（例: `\"source/\"`）。 */\n  inNamespace(namespace: string): boolean {\n    return this.code.startsWith(namespace);\n  }\n\n  /**\n   * nextSteps と docsUrl を含む人間向けの詳細メッセージを返す。\n   * エラーダイアログ・ログ出力時に使う。\n   */\n  format(): string {\n    const lines: string[] = [this.message];\n    if (this.nextSteps?.length) {\n      lines.push(\"\\n次にやること:\");\n      for (const step of this.nextSteps) {\n        lines.push(`  - ${step}`);\n      }\n    }\n    if (this.docsUrl) {\n      lines.push(`\\n詳細: ${this.docsUrl}`);\n    }\n    return lines.join(\"\\n\");\n  }\n}\n\nexport function isCMSError(error: unknown): error is CMSError {\n  return error instanceof CMSError;\n}\n\n/** エラーコードが特定の名前空間に属するかを判定する（例: \"source/\"）。 */\nexport function isCMSErrorInNamespace(\n  error: unknown,\n  namespace: string,\n): error is CMSError {\n  return isCMSError(error) && error.code.startsWith(namespace);\n}\n\ntype CMSErrorHandler<R> = (err: CMSError) => R;\n\n/**\n * `CMSError` を switch 式のように分岐して処理するユーティリティ。\n * `_` キーはフォールバック（CMSError 以外 or 未マッチ時）に使われる。\n *\n * @example\n * matchCMSError(err, {\n *   \"source/fetch_items_failed\": (e) => handleFetchError(e),\n *   _: (e) => { throw e; },\n * });\n */\nexport function matchCMSError<R>(\n  error: unknown,\n  handlers: Partial<Record<CMSErrorCode, CMSErrorHandler<R>>> & {\n    _?: (err: unknown) => R;\n  },\n): R | undefined {\n  if (!isCMSError(error)) {\n    return handlers._?.(error);\n  }\n  const handler =\n    handlers[error.code as CMSErrorCode] ??\n    (handlers._ as CMSErrorHandler<R> | undefined);\n  return handler?.(error);\n}\n"],"mappings":";AA+EA,IAAa,WAAb,cAA8B,MAAM;CAClC;CACA;CACA;;CAEA;;CAEA;CAEA,YAAY,QAOT;EACD,MAAM,OAAO,SAAS,EAAE,OAAO,OAAO,MAAM,CAAC;EAC7C,KAAK,OAAO;EACZ,KAAK,OAAO,OAAO;EACnB,KAAK,QAAQ,OAAO;EACpB,KAAK,UAAU,OAAO;EACtB,KAAK,YAAY,OAAO;EACxB,KAAK,UAAU,OAAO;CACxB;;CAGA,GAAG,MAA6B;EAC9B,OAAO,KAAK,SAAS;CACvB;;CAGA,YAAY,WAA4B;EACtC,OAAO,KAAK,KAAK,WAAW,SAAS;CACvC;;;;;CAMA,SAAiB;EACf,MAAM,QAAkB,CAAC,KAAK,OAAO;EACrC,IAAI,KAAK,WAAW,QAAQ;GAC1B,MAAM,KAAK,WAAW;GACtB,KAAK,MAAM,QAAQ,KAAK,WACtB,MAAM,KAAK,OAAO,MAAM;EAE5B;EACA,IAAI,KAAK,SACP,MAAM,KAAK,SAAS,KAAK,SAAS;EAEpC,OAAO,MAAM,KAAK,IAAI;CACxB;AACF;AAEA,SAAgB,WAAW,OAAmC;CAC5D,OAAO,iBAAiB;AAC1B;;AAGA,SAAgB,sBACd,OACA,WACmB;CACnB,OAAO,WAAW,KAAK,KAAK,MAAM,KAAK,WAAW,SAAS;AAC7D;;;;;;;;;;;AAcA,SAAgB,cACd,OACA,UAGe;CACf,IAAI,CAAC,WAAW,KAAK,GACnB,OAAO,SAAS,IAAI,KAAK;CAK3B,QAFE,SAAS,MAAM,SACd,SAAS,KACK,KAAK;AACxB"}
+{"version":3,"file":"errors.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * ライブラリ組み込みの CMS エラーコード。\n *\n * | コード | 発生条件 |\n * |---|---|\n * | `core/config_invalid` | 設定不備（token 未設定など） |\n * | `core/schema_invalid` | schema/mapping の型不整合 |\n * | `core/notion_orm_missing` | `@notion-headless-cms/notion-orm` の動的ロード失敗 |\n * | `core/sort_unsupported_type` | ソートキーの値型が string / number でない |\n * | `webhook/signature_invalid` | Webhook 署名検証失敗 |\n * | `webhook/payload_invalid` | Webhook ペイロード形式不正 |\n * | `webhook/unknown_collection` | Webhook の対象コレクションが未知 |\n * | `webhook/not_implemented` | DataSource が parseWebhook を実装していない |\n * | `source/fetch_items_failed` | `DataSource.list()` 失敗 |\n * | `source/fetch_item_failed` | `DataSource.findByProp()` 失敗 |\n * | `source/load_markdown_failed` | `DataSource.loadMarkdown()` 失敗 |\n * | `source/load_blocks_failed` | `DataSource.loadBlocks()` 失敗 |\n * | `source/blocks_unsupported` | 選択した fetch 戦略が NotionBlockTree 取得を提供していない (markdown 戦略選択時など) |\n * | `cache/io_failed` | document / image キャッシュの I/O 失敗 |\n * | `cache/image_fetch_failed` | Notion 画像の HTTP 取得失敗 |\n * | `cache/image_invalid_content_type` | 画像レスポンスの Content-Type が不正 |\n * | `renderer/failed` | Markdown → HTML 変換失敗 |\n * | `swr/item_check_failed` | SWR バックグラウンドのアイテム差分チェック失敗 |\n * | `swr/list_check_failed` | SWR バックグラウンドのリスト差分チェック失敗 |\n * | `swr/content_rebuild_failed` | SWR バックグラウンドの本文再生成失敗 |\n * | `cli/config_invalid` | `nhc.config.ts` の内容不整合 |\n * | `cli/config_load_failed` | 設定ファイルの読み込み / 評価失敗 |\n * | `cli/schema_invalid` | CLI が受け取ったスキーマ / マッピング不整合 |\n * | `cli/generate_failed` | `nhc generate` の処理失敗 |\n * | `cli/init_failed` | `nhc init` の処理失敗 |\n * | `cli/notion_api_failed` | CLI が Notion API を呼び出す際の失敗 |\n * | `cli/env_file_not_found` | `--env-file` で指定したファイルが存在しない |\n *\n * サードパーティアダプタが独自コードを追加したい場合は `CMSErrorCode` を参照。\n */\nexport type BuiltInCMSErrorCode =\n  | \"core/config_invalid\"\n  | \"core/schema_invalid\"\n  | \"core/notion_orm_missing\"\n  | \"core/sort_unsupported_type\"\n  | \"webhook/signature_invalid\"\n  | \"webhook/payload_invalid\"\n  | \"webhook/unknown_collection\"\n  | \"webhook/not_implemented\"\n  | \"source/fetch_items_failed\"\n  | \"source/fetch_item_failed\"\n  | \"source/load_markdown_failed\"\n  | \"source/load_blocks_failed\"\n  | \"source/blocks_unsupported\"\n  | \"cache/io_failed\"\n  | \"cache/image_fetch_failed\"\n  | \"cache/image_invalid_content_type\"\n  | \"renderer/failed\"\n  | \"swr/item_check_failed\"\n  | \"swr/list_check_failed\"\n  | \"swr/content_rebuild_failed\"\n  | \"cli/config_invalid\"\n  | \"cli/config_load_failed\"\n  | \"cli/schema_invalid\"\n  | \"cli/generate_failed\"\n  | \"cli/init_failed\"\n  | \"cli/notion_api_failed\"\n  | \"cli/env_file_not_found\";\n\n/**\n * CMS エラーコード。\n * `BuiltInCMSErrorCode` のリテラル補完を維持しつつ、\n * サードパーティアダプタが独自コードを定義できるよう `string & {}` で拡張可能にする。\n */\nexport type CMSErrorCode = BuiltInCMSErrorCode | (string & {});\n\nexport interface CMSErrorContext {\n  operation: string;\n  slug?: string;\n  dataSourceId?: string;\n  pageId?: string;\n  [key: string]: string | number | boolean | null | undefined;\n}\n\n/**\n * 組み込みエラーコードごとのドキュメント URL アンカーと既定の次アクション。\n * `CMSError` コンストラクタが呼び出し側の `docsUrl` / `nextSteps` 未指定時のフォールバックに使用する。\n *\n * `docs/ja/errors/index.md` の各セクション ID と同期させること。\n */\nconst ERROR_DOCS_BASE =\n  \"https://github.com/kjfsm/notion-headless-cms/blob/main/docs/ja/errors/index.md\";\n\ninterface ErrorHelp {\n  readonly docsAnchor: string;\n  readonly nextSteps: readonly string[];\n}\n\nconst BUILT_IN_ERROR_HELP: Record<BuiltInCMSErrorCode, ErrorHelp> = {\n  \"core/config_invalid\": {\n    docsAnchor: \"core-config_invalid\",\n    nextSteps: [\n      \"createClient の必須オプション (sources / collections) を確認する\",\n      \"NOTION_TOKEN が環境変数または .dev.vars に設定されているか確認する\",\n    ],\n  },\n  \"core/schema_invalid\": {\n    docsAnchor: \"core-schema_invalid\",\n    nextSteps: [\n      \"nhc generate を再実行して schema を最新化する\",\n      \"PropertyMap / PropertyDef の型が定義どおりか確認する\",\n    ],\n  },\n  \"core/notion_orm_missing\": {\n    docsAnchor: \"core-notion_orm_missing\",\n    nextSteps: [\n      \"@notion-headless-cms/notion-orm をインストールする\",\n      \"実行ランタイムが動的 import を許可しているか確認する\",\n    ],\n  },\n  \"core/sort_unsupported_type\": {\n    docsAnchor: \"core-sort_unsupported_type\",\n    nextSteps: [\n      \"sort.by に指定したフィールドの値型が string / number になっているか確認する\",\n      \"別フィールドでソートするか、source 側で正規化する\",\n    ],\n  },\n  \"webhook/signature_invalid\": {\n    docsAnchor: \"webhook-signature_invalid\",\n    nextSteps: [\n      \"Notion 側で発行された webhook secret が一致しているか確認する\",\n      \"プロキシ / WAF がリクエストボディを書き換えていないか確認する\",\n    ],\n  },\n  \"webhook/payload_invalid\": {\n    docsAnchor: \"webhook-payload_invalid\",\n    nextSteps: [\n      \"リクエストボディが JSON で送信されているか確認する\",\n      \"DataSource.parseWebhook の期待するフィールド構造と一致しているか確認する\",\n    ],\n  },\n  \"webhook/unknown_collection\": {\n    docsAnchor: \"webhook-unknown_collection\",\n    nextSteps: [\n      \"createClient の sources / collections に該当 collection が登録されているか確認する\",\n      \"Webhook URL が `?collection=` で正しいコレクション名を指しているか確認する\",\n    ],\n  },\n  \"webhook/not_implemented\": {\n    docsAnchor: \"webhook-not_implemented\",\n    nextSteps: [\n      \"対象 collection の DataSource に parseWebhook を実装する\",\n      \"Webhook を使わない場合は cms.invalidate() を直接呼ぶ運用に切り替える\",\n    ],\n  },\n  \"source/fetch_items_failed\": {\n    docsAnchor: \"source-fetch_items_failed\",\n    nextSteps: [\n      \"NOTION_TOKEN がインテグレーションに紐づいているか確認する\",\n      \"Notion DB がインテグレーションに接続済みか確認する\",\n      \"ネットワーク / Notion API の障害状況 (status.notion.so) を確認する\",\n      \"rateLimiter.maxRetries / baseDelayMs を調整してリトライ余地を増やす\",\n    ],\n  },\n  \"source/fetch_item_failed\": {\n    docsAnchor: \"source-fetch_item_failed\",\n    nextSteps: [\n      \"slug プロパティが Notion DB に存在し、値がユニークか確認する\",\n      \"対象ページがインテグレーションに共有されているか確認する\",\n    ],\n  },\n  \"source/load_markdown_failed\": {\n    docsAnchor: \"source-load_markdown_failed\",\n    nextSteps: [\n      \"対象ページがアーカイブされていないか確認する\",\n      \"未対応ブロック (file / video など) が原因なら fetch 戦略を `markdownFetcher()` に切り替えるか、対象ブロックを除外する\",\n    ],\n  },\n  \"source/load_blocks_failed\": {\n    docsAnchor: \"source-load_blocks_failed\",\n    nextSteps: [\n      \"対象ページが削除 / アーカイブされていないか確認する\",\n      \"Notion API の rate limit に当たっていないかログで確認する\",\n    ],\n  },\n  \"source/blocks_unsupported\": {\n    docsAnchor: \"source-blocks_unsupported\",\n    nextSteps: [\n      \"react-renderer を使う場合は fetch 戦略を `fetchBlockTree()` に切り替える\",\n      \"あるいは markdown 経路で本文表示にフォールバックする\",\n    ],\n  },\n  \"cache/io_failed\": {\n    docsAnchor: \"cache-io_failed\",\n    nextSteps: [\n      \"KV / R2 / メモリキャッシュの binding (env.DOC_CACHE / env.IMG_BUCKET) が正しいか確認する\",\n      \"wrangler.toml の binding 名と createClient に渡した env が一致しているか確認する\",\n      \"一時的な障害なら SWR が次回読み込み時に自己回復する\",\n    ],\n  },\n  \"cache/image_fetch_failed\": {\n    docsAnchor: \"cache-image_fetch_failed\",\n    nextSteps: [\n      \"Notion 署名 URL の有効期限 (約 1 時間) が切れていないか確認する\",\n      \"Worker / Node のアウトバウンドネットワークが許可されているか確認する\",\n    ],\n  },\n  \"cache/image_invalid_content_type\": {\n    docsAnchor: \"cache-image_invalid_content_type\",\n    nextSteps: [\n      \"Notion 画像 URL を直接ブラウザで開いて image/* を返すか確認する\",\n      \"プロキシ / CDN が Content-Type を書き換えていないか確認する\",\n    ],\n  },\n  \"renderer/failed\": {\n    docsAnchor: \"renderer-failed\",\n    nextSteps: [\n      \"renderer に渡している remark / rehype プラグインの組み合わせを確認する\",\n      \"fetch 戦略と renderer の組み合わせが整合しているか (Notion enhanced markdown には notionMarkdownRenderer が必要) を確認する\",\n    ],\n  },\n  \"swr/item_check_failed\": {\n    docsAnchor: \"swr-item_check_failed\",\n    nextSteps: [\n      \"ログで cause を確認し、source/fetch_item_failed と同じ手順で原因を切り分ける\",\n      \"バックグラウンドの失敗は次回 SWR で自動再試行されるため恒久対処不要なケースもある\",\n    ],\n  },\n  \"swr/list_check_failed\": {\n    docsAnchor: \"swr-list_check_failed\",\n    nextSteps: [\n      \"ログで cause を確認し、source/fetch_items_failed と同じ手順で原因を切り分ける\",\n      \"Notion API の rate limit に近い場合は rateLimiter を絞る\",\n    ],\n  },\n  \"swr/content_rebuild_failed\": {\n    docsAnchor: \"swr-content_rebuild_failed\",\n    nextSteps: [\n      \"renderer / loadMarkdown が一時的に失敗しただけならログを確認のうえ放置可\",\n      \"恒常的に再発する場合は対象 slug を fresh: true で取り直して再現を確認する\",\n    ],\n  },\n  \"cli/config_invalid\": {\n    docsAnchor: \"cli-config_invalid\",\n    nextSteps: [\n      \"nhc.config.ts が defineConfig() を default export しているか確認する\",\n      \"collections に少なくとも 1 件、databaseId または dbName が指定されているか確認する\",\n    ],\n  },\n  \"cli/config_load_failed\": {\n    docsAnchor: \"cli-config_load_failed\",\n    nextSteps: [\n      \"nhc.config.ts に構文エラーがないか tsc / エディタで確認する\",\n      \"ESM の import パスが拡張子付き (.js) になっているか確認する\",\n    ],\n  },\n  \"cli/schema_invalid\": {\n    docsAnchor: \"cli-schema_invalid\",\n    nextSteps: [\n      \"Notion DB のプロパティ型が CLI 対応 (title / richText / select / status / multiSelect / date / number / checkbox / url) のいずれかか確認する\",\n      \"未対応プロパティをスキップするか、Notion 側で型を変える\",\n    ],\n  },\n  \"cli/generate_failed\": {\n    docsAnchor: \"cli-generate_failed\",\n    nextSteps: [\n      \"--verbose を付けて再実行し、失敗箇所のスタックトレースを確認する\",\n      \"出力先ディレクトリの書き込み権限を確認する\",\n    ],\n  },\n  \"cli/init_failed\": {\n    docsAnchor: \"cli-init_failed\",\n    nextSteps: [\n      \"出力先パスに既存ファイルがある場合は --force を付けるか別パスを指定する\",\n      \"親ディレクトリの書き込み権限を確認する\",\n    ],\n  },\n  \"cli/notion_api_failed\": {\n    docsAnchor: \"cli-notion_api_failed\",\n    nextSteps: [\n      \"NOTION_TOKEN がインテグレーションに紐づいているか確認する\",\n      \"対象 DB がインテグレーションに接続されているか (Notion DB → … → Connections) 確認する\",\n      \"DB 名で解決している場合は完全一致 (前後空白 / 全角半角) を確認する\",\n      \"--verbose で Notion API レスポンスの status / code を確認する\",\n    ],\n  },\n  \"cli/env_file_not_found\": {\n    docsAnchor: \"cli-env_file_not_found\",\n    nextSteps: [\n      \"--env-file で指定したパスを実ファイルパスで確認する\",\n      \"プロジェクトルートで実行しているか (相対パスは cwd 基準)\",\n    ],\n  },\n};\n\nfunction lookupBuiltInHelp(code: CMSErrorCode): ErrorHelp | undefined {\n  return BUILT_IN_ERROR_HELP[code as BuiltInCMSErrorCode];\n}\n\nexport class CMSError extends Error {\n  readonly code: CMSErrorCode;\n  override readonly cause?: unknown;\n  readonly context: CMSErrorContext;\n  /** エラーを解消するための次のアクション（表示用）。 */\n  readonly nextSteps?: readonly string[];\n  /** 詳細ドキュメントへの URL（表示用）。 */\n  readonly docsUrl?: string;\n\n  constructor(params: {\n    code: CMSErrorCode;\n    message: string;\n    cause?: unknown;\n    context: CMSErrorContext;\n    nextSteps?: readonly string[];\n    docsUrl?: string;\n  }) {\n    super(params.message, { cause: params.cause });\n    this.name = \"CMSError\";\n    this.code = params.code;\n    this.cause = params.cause;\n    this.context = params.context;\n\n    // 呼び出し側が nextSteps / docsUrl を指定していない場合は、組み込みコード向けの既定値で補完する。\n    // サードパーティコードや未登録コードは undefined のままにする。\n    const help = lookupBuiltInHelp(params.code);\n    this.nextSteps = params.nextSteps ?? help?.nextSteps;\n    this.docsUrl =\n      params.docsUrl ??\n      (help ? `${ERROR_DOCS_BASE}#${help.docsAnchor}` : undefined);\n  }\n\n  /** エラーコードが指定した値と一致するか判定する。 */\n  is(code: CMSErrorCode): boolean {\n    return this.code === code;\n  }\n\n  /** エラーコードが指定した名前空間に属するか判定する（例: `\"source/\"`）。 */\n  inNamespace(namespace: string): boolean {\n    return this.code.startsWith(namespace);\n  }\n\n  /**\n   * nextSteps と docsUrl を含む人間向けの詳細メッセージを返す。\n   * エラーダイアログ・ログ出力時に使う。\n   */\n  format(): string {\n    const lines: string[] = [this.message];\n    if (this.nextSteps?.length) {\n      lines.push(\"\\n次にやること:\");\n      for (const step of this.nextSteps) {\n        lines.push(`  - ${step}`);\n      }\n    }\n    if (this.docsUrl) {\n      lines.push(`\\n詳細: ${this.docsUrl}`);\n    }\n    return lines.join(\"\\n\");\n  }\n}\n\nexport function isCMSError(error: unknown): error is CMSError {\n  return error instanceof CMSError;\n}\n\n/** エラーコードが特定の名前空間に属するかを判定する（例: \"source/\"）。 */\nexport function isCMSErrorInNamespace(\n  error: unknown,\n  namespace: string,\n): error is CMSError {\n  return isCMSError(error) && error.code.startsWith(namespace);\n}\n\ntype CMSErrorHandler<R> = (err: CMSError) => R;\n\n/**\n * `CMSError` を switch 式のように分岐して処理するユーティリティ。\n * `_` キーはフォールバック（CMSError 以外 or 未マッチ時）に使われる。\n *\n * @example\n * matchCMSError(err, {\n *   \"source/fetch_items_failed\": (e) => handleFetchError(e),\n *   _: (e) => { throw e; },\n * });\n */\nexport function matchCMSError<R>(\n  error: unknown,\n  handlers: Partial<Record<CMSErrorCode, CMSErrorHandler<R>>> & {\n    _?: (err: unknown) => R;\n  },\n): R | undefined {\n  if (!isCMSError(error)) {\n    return handlers._?.(error);\n  }\n  const handler =\n    handlers[error.code as CMSErrorCode] ??\n    (handlers._ as CMSErrorHandler<R> | undefined);\n  return handler?.(error);\n}\n"],"mappings":";;;;;;;AAqFA,MAAM,kBACJ;AAOF,MAAM,sBAA8D;CAClE,uBAAuB;EACrB,YAAY;EACZ,WAAW,CACT,uDACA,+CACF;CACF;CACA,uBAAuB;EACrB,YAAY;EACZ,WAAW,CACT,qCACA,yCACF;CACF;CACA,2BAA2B;EACzB,YAAY;EACZ,WAAW,CACT,6CACA,gCACF;CACF;CACA,8BAA8B;EAC5B,YAAY;EACZ,WAAW,CACT,sDACA,8BACF;CACF;CACA,6BAA6B;EAC3B,YAAY;EACZ,WAAW,CACT,8CACA,oCACF;CACF;CACA,2BAA2B;EACzB,YAAY;EACZ,WAAW,CACT,gCACA,kDACF;CACF;CACA,8BAA8B;EAC5B,YAAY;EACZ,WAAW,CACT,qEACA,qDACF;CACF;CACA,2BAA2B;EACzB,YAAY;EACZ,WAAW,CACT,mDACA,iDACF;CACF;CACA,6BAA6B;EAC3B,YAAY;EACZ,WAAW;GACT;GACA;GACA;GACA;EACF;CACF;CACA,4BAA4B;EAC1B,YAAY;EACZ,WAAW,CACT,0CACA,8BACF;CACF;CACA,+BAA+B;EAC7B,YAAY;EACZ,WAAW,CACT,0BACA,mFACF;CACF;CACA,6BAA6B;EAC3B,YAAY;EACZ,WAAW,CACT,+BACA,0CACF;CACF;CACA,6BAA6B;EAC3B,YAAY;EACZ,WAAW,CACT,6DACA,iCACF;CACF;CACA,mBAAmB;EACjB,YAAY;EACZ,WAAW;GACT;GACA;GACA;EACF;CACF;CACA,4BAA4B;EAC1B,YAAY;EACZ,WAAW,CACT,6CACA,2CACF;CACF;CACA,oCAAoC;EAClC,YAAY;EACZ,WAAW,CACT,8CACA,0CACF;CACF;CACA,mBAAmB;EACjB,YAAY;EACZ,WAAW,CACT,oDACA,kGACF;CACF;CACA,yBAAyB;EACvB,YAAY;EACZ,WAAW,CACT,0DACA,6CACF;CACF;CACA,yBAAyB;EACvB,YAAY;EACZ,WAAW,CACT,2DACA,gDACF;CACF;CACA,8BAA8B;EAC5B,YAAY;EACZ,WAAW,CACT,oDACA,gDACF;CACF;CACA,sBAAsB;EACpB,YAAY;EACZ,WAAW,CACT,6DACA,4DACF;CACF;CACA,0BAA0B;EACxB,YAAY;EACZ,WAAW,CACT,4CACA,yCACF;CACF;CACA,sBAAsB;EACpB,YAAY;EACZ,WAAW,CACT,4HACA,iCACF;CACF;CACA,uBAAuB;EACrB,YAAY;EACZ,WAAW,CACT,yCACA,uBACF;CACF;CACA,mBAAmB;EACjB,YAAY;EACZ,WAAW,CACT,4CACA,qBACF;CACF;CACA,yBAAyB;EACvB,YAAY;EACZ,WAAW;GACT;GACA;GACA;GACA;EACF;CACF;CACA,0BAA0B;EACxB,YAAY;EACZ,WAAW,CACT,mCACA,kCACF;CACF;AACF;AAEA,SAAS,kBAAkB,MAA2C;CACpE,OAAO,oBAAoB;AAC7B;AAEA,IAAa,WAAb,cAA8B,MAAM;CAClC;CACA;CACA;;CAEA;;CAEA;CAEA,YAAY,QAOT;EACD,MAAM,OAAO,SAAS,EAAE,OAAO,OAAO,MAAM,CAAC;EAC7C,KAAK,OAAO;EACZ,KAAK,OAAO,OAAO;EACnB,KAAK,QAAQ,OAAO;EACpB,KAAK,UAAU,OAAO;EAItB,MAAM,OAAO,kBAAkB,OAAO,IAAI;EAC1C,KAAK,YAAY,OAAO,aAAa,MAAM;EAC3C,KAAK,UACH,OAAO,YACN,OAAO,GAAG,gBAAgB,GAAG,KAAK,eAAe,KAAA;CACtD;;CAGA,GAAG,MAA6B;EAC9B,OAAO,KAAK,SAAS;CACvB;;CAGA,YAAY,WAA4B;EACtC,OAAO,KAAK,KAAK,WAAW,SAAS;CACvC;;;;;CAMA,SAAiB;EACf,MAAM,QAAkB,CAAC,KAAK,OAAO;EACrC,IAAI,KAAK,WAAW,QAAQ;GAC1B,MAAM,KAAK,WAAW;GACtB,KAAK,MAAM,QAAQ,KAAK,WACtB,MAAM,KAAK,OAAO,MAAM;EAE5B;EACA,IAAI,KAAK,SACP,MAAM,KAAK,SAAS,KAAK,SAAS;EAEpC,OAAO,MAAM,KAAK,IAAI;CACxB;AACF;AAEA,SAAgB,WAAW,OAAmC;CAC5D,OAAO,iBAAiB;AAC1B;;AAGA,SAAgB,sBACd,OACA,WACmB;CACnB,OAAO,WAAW,KAAK,KAAK,MAAM,KAAK,WAAW,SAAS;AAC7D;;;;;;;;;;;AAcA,SAAgB,cACd,OACA,UAGe;CACf,IAAI,CAAC,WAAW,KAAK,GACnB,OAAO,SAAS,IAAI,KAAK;CAK3B,QAFE,SAAS,MAAM,SACd,SAAS,KACK,KAAK;AACxB"}

package/dist/hooks.d.mts

@@ -1,5 +1,5 @@
 import { t as BaseContentItem } from "./content-DwsfWZao.mjs";
-import { i as CMSHooks, r as Logger, t as CMSPlugin } from "./plugin-Dct12kp2.mjs";
+import { a as CMSHooks, i as Logger, t as CMSPlugin } from "./plugin-BmrOz8T6.mjs";
 
 //#region src/hooks.d.ts
 /**
@@ -12,6 +12,14 @@ declare function mergeHooks<T extends BaseContentItem>(plugins: CMSPlugin<T>[],
 declare function mergeLoggers(plugins: Array<{
   logger?: Partial<Logger>;
 }>, directLogger?: Logger): Logger | undefined;
+/**
+ * 既存 Logger をラップし、全ログコンテキストに `traceId` を自動で付与する。
+ * 呼び出し側が明示的に traceId を渡した場合はその値を優先する。
+ *
+ * `createClient` がクライアント単位の trace ID を発行し、ネストした操作
+ * (list / find / SWR 再生成 / retry) で同じ ID をログに伝搬するために使う。
+ */
+declare function withTraceId(logger: Logger | undefined, traceId: string): Logger | undefined;
 //#endregion
-export { mergeHooks, mergeLoggers };
+export { mergeHooks, mergeLoggers, withTraceId };
 //# sourceMappingURL=hooks.d.mts.map