cmx-sdk 0.2.7 → 0.2.9

package/dist/{interactive-menu-QKE6FMPN.js → interactive-menu-FYVOQSTL.js}

@@ -31,7 +31,7 @@ async function interactiveMenu() {
       return updateStudio({});
     }
     case "update-sdk": {
-      const { updateSdk } = await import("./update-sdk-ZDFOSMN4.js");
+      const { updateSdk } = await import("./update-sdk-KJZ6VB4M.js");
       return updateSdk({});
     }
     case "studio": {

package/dist/{update-sdk-ZDFOSMN4.js → update-sdk-KJZ6VB4M.js}

@@ -2,7 +2,7 @@
 import {
   resolveRequestedVersion,
   updateSdk
-} from "./chunk-S3TFTN6H.js";
+} from "./chunk-EZMBZWH7.js";
 import "./chunk-EDXXR5BE.js";
 export {
   resolveRequestedVersion,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cmx-sdk",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "CMX SDK - Official SDK for building content-driven websites with CMX",
   "type": "module",
   "license": "MIT",
@@ -26,6 +26,7 @@
   ],
   "files": [
     "dist",
+    "templates",
     "README.md"
   ],
   "exports": {
@@ -34,6 +35,19 @@
       "import": "./dist/index.js"
     }
   },
+  "scripts": {
+    "prebuild": "node scripts/copy-api-client.js",
+    "sync:starter-kit-docs": "pnpm --filter @cmx/api-server generate:openapi && node scripts/sync-starter-kit-docs.mjs --write",
+    "sync:starter-kit-docs:check": "pnpm --filter @cmx/api-server generate:openapi && node scripts/sync-starter-kit-docs.mjs --check",
+    "check:sdk-command-api-usage": "node scripts/check-sdk-command-api-usage.mjs",
+    "check:generated-sync": "node scripts/check-generated-sync.mjs",
+    "test:contracts": "tsx scripts/check-cli-contracts.ts",
+    "verify:release": "pnpm run check:sdk-command-api-usage && pnpm run check:generated-sync && pnpm run test:contracts",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm run verify:release && pnpm run sync:starter-kit-docs:check && pnpm run build"
+  },
   "dependencies": {
     "@inquirer/prompts": "^8.2.1",
     "@mdx-js/mdx": "^3.1.1",
@@ -56,17 +70,5 @@
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
-  },
-  "scripts": {
-    "prebuild": "node scripts/copy-api-client.js",
-    "sync:starter-kit-docs": "pnpm --filter @cmx/api-server generate:openapi && node scripts/sync-starter-kit-docs.mjs --write",
-    "sync:starter-kit-docs:check": "pnpm --filter @cmx/api-server generate:openapi && node scripts/sync-starter-kit-docs.mjs --check",
-    "check:sdk-command-api-usage": "node scripts/check-sdk-command-api-usage.mjs",
-    "check:generated-sync": "node scripts/check-generated-sync.mjs",
-    "test:contracts": "tsx scripts/check-cli-contracts.ts",
-    "verify:release": "pnpm run check:sdk-command-api-usage && pnpm run check:generated-sync && pnpm run test:contracts",
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit"
   }
-}
+}

package/templates/AGENTS.md

@@ -0,0 +1,173 @@
+# CMX Starter Kit — AI Agent Instructions
+
+このファイルはAIコーディングエージェント（Claude Code, Cursor, GitHub Copilot, Google Jules 等）向けの共通指示書です。
+
+> **注意:** `<!-- cmx-sdk:start -->` ～ `<!-- cmx-sdk:end -->` の範囲は `npx cmx-sdk update-sdk` で自動更新されます。
+> その範囲外はカスタマイズ可能です。
+
+## サイト設定
+
+サイト固有の設定は以下を参照:
+
+→ cmx/site-config.md — 開発方針（種別・トーン・デザイン方針・禁止事項）
+→ cmx-workflow/style-guide.md — 執筆ルール（文体・用語・記事構成、別配布）
+
+すべてのコード変更・提案は site-config.md の方針と矛盾しないことを確認すること。
+コンテンツ生成時は style-guide.md のトーン・フォーマットに従うこと。
+
+---
+
+<!-- cmx-sdk:start id="architecture" -->
+## アーキテクチャ
+
+CMX Starter Kit はヘッドレスCMSのフロントエンドテンプレートです。
+
+```
+CMX Admin（サービス側）              Starter Kit（このリポジトリ）
+┌─────────────────────┐            ┌──────────────────────────┐
+│ コレクション / データタイプ │  Public  │ Next.js 16 (App Router)   │
+│ 投稿 / アセット / フォーム │  API    │ cmx-sdk でデータ取得       │
+│                     │◄─────────│ Cloudflare Workers デプロイ │
+│ APIキー ─────────────────────────│ .env の CMX_API_KEY で認証  │
+└─────────────────────┘            └──────────────────────────┘
+```
+
+### 厳守ルール
+
+- **すべてのデータ取得は `cmx-sdk` 経由。** DB直接アクセスは存在しない
+- **サーバーコンポーネントがデフォルト。** クライアントコンポーネントは必要最小限に
+- **CMXデータを取得するページには `export const dynamic = "force-dynamic"` を必ず付ける**
+- **MDXレンダリングは `src/lib/mdx/render.tsx` の `renderMdx` を使う。** 独自のMDX処理を書かない
+- **カスタムコンポーネントは `src/components/custom/index.ts` から export する。** export すれば MDX 内で自動的に使用可能になる
+- **`cmx/generated/` 配下のファイルは手動編集禁止。** `npx cmx-sdk codegen types` で再生成する
+
+### 独自実装の禁止
+
+- **独自の API クライアントや fetch ラッパーを作成しない。** `cmx-sdk` と `@/lib/` 配下の既存関数のみ使用する
+- **`cmx-sdk` にない機能が必要な場合、独自実装せずユーザーに相談する**
+
+### エラー時の行動規範
+
+1. **1回リトライ**する
+2. リトライでも解決しない場合、**代替手段を勝手に実装せず、ユーザーに報告して確認を取る**
+<!-- cmx-sdk:end -->
+
+---
+
+<!-- cmx-sdk:start id="env-vars" -->
+## 環境変数
+
+| 変数名 | 必須 | 説明 |
+|--------|------|------|
+| `CMX_API_KEY` | 必須 | CMX Admin で発行した API キー |
+| `CMX_API_URL` | 必須 | CMX Admin インスタンスの URL |
+| `CMX_WORKSPACE_ID` | 任意 | ワークスペースID（APIキーから自動判定） |
+| `NEXT_PUBLIC_SITE_URL` | 必須 | 公開サイトの URL |
+| `REVALIDATE_API_KEY` | 任意 | リバリデーション用の秘密鍵 |
+<!-- cmx-sdk:end -->
+
+---
+
+<!-- cmx-sdk:start id="commands" -->
+## コマンド
+
+```bash
+pnpm dev                   # 開発サーバー起動（Turbopack, port 4000）
+pnpm build                 # Next.js ビルド
+pnpm build:cf              # Cloudflare Workers 向けビルド
+pnpm deploy                # Cloudflare Workers デプロイ
+pnpm typecheck             # TypeScript 型チェック
+pnpm lint                  # ESLint
+npx cmx-sdk sync-components       # カスタムコンポーネントを Admin に同期
+npx cmx-sdk components scaffold --name FeatureCard   # コンポーネント雛形を生成
+npx cmx-sdk codegen types       # スキーマから型付きコードを自動生成
+npx cmx-sdk codegen pages --template layered  # ページ雛形（resolver/meta/view分離）を生成
+npx cmx-sdk codegen check       # 生成コードと import/tsconfig の整合を検証
+npx cmx-sdk codegen all         # types → pages → check を一括実行
+npx cmx-sdk mdx validate        # MDX本文の構文/禁止構文/props を検証
+npx cmx-sdk mdx doctor          # MDX定義JSONと実装/exportの整合を検証
+npx cmx-sdk create-collection --json '...'  # コレクションを API 経由で作成
+npx cmx-sdk create-data-type --json '...'   # データタイプを API 経由で作成
+npx cmx-sdk create-data-entry --type-slug {slug} --json '...'  # データエントリを作成
+npx cmx-sdk list-collection-data-types --collection {slug}    # コレクションの付属データタイプ一覧
+npx cmx-sdk list-collection-presets --type {type}             # プリセット一覧（おすすめ/その他）
+npx cmx-sdk update-sdk          # SDK・コマンド・スキルを最新版に更新
+```
+<!-- cmx-sdk:end -->
+
+---
+
+<!-- cmx-sdk:start id="setup-flow" -->
+## 開発フロー
+
+### 初期構築
+
+```
+1. サイトコンフィグ作成    cmx/site-config.md を作成
+2. 環境セットアップ        .env.local 設定 → pnpm install → pnpm dev
+3. スキーマ設計            コレクション・データタイプの JSON 定義を作成
+                          → create-collection / create-data-type コマンドで登録
+4. テストデータ投入        Admin 側でコンテンツを作成し「公開」にする
+5. コード生成              npx cmx-sdk codegen types で型付き関数を生成
+6. 雛形生成（任意）        npx cmx-sdk codegen pages --template layered
+7. ページ実装              一覧ページ・詳細ページ・静的ページを作成
+8. コンポーネント作成      MDX 用カスタムコンポーネントを定義・実装・同期
+9. デプロイ                pnpm build:cf && pnpm deploy
+```
+<!-- cmx-sdk:end -->
+
+---
+
+<!-- cmx-sdk:start id="api-patterns" -->
+## API パターン
+
+### データ取得
+
+```tsx
+// cmx-sdk 直接（汎用）
+import { getCollectionContents, getCollectionContentDetail, getDataEntries, getDataEntry } from "cmx-sdk"
+
+// re-export 経由（推奨）
+import { getCollectionContents, getCollectionContentDetail, getDataEntries } from "@/lib/api/admin-client"
+
+// エラー時 throw するラッパー（ページで使用）
+import { requireFetchContents, requireFetchContent, requireDataEntries } from "@/lib/utils/data-fetching"
+
+// 型付き自動生成関数（npx cmx-sdk codegen types 後）
+import { getBlogContents, getBlogContentDetail } from "@cmx/generated"
+import { getStaff, getStaffById } from "@cmx/generated"
+```
+
+### ページテンプレート: コレクション一覧
+
+```tsx
+// src/app/{collection}/page.tsx
+import { COLLECTION_SLUGS } from "@/lib/constants/collections"
+import { requireFetchContents } from "@/lib/utils/data-fetching"
+
+export const dynamic = "force-dynamic"
+
+export default async function ListPage() {
+  const { collection, contents } = await requireFetchContents(COLLECTION_SLUGS.xxx)
+  return (/* 一覧 UI */)
+}
+```
+
+### ページテンプレート: コレクション詳細
+
+```tsx
+// src/app/{collection}/[slug]/page.tsx
+import { COLLECTION_SLUGS } from "@/lib/constants/collections"
+import { requireFetchContent } from "@/lib/utils/data-fetching"
+import { renderMdx } from "@/lib/mdx/render"
+
+export const dynamic = "force-dynamic"
+
+export default async function DetailPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params
+  const { content, references } = await requireFetchContent(COLLECTION_SLUGS.xxx, slug)
+  const { content: rendered } = await renderMdx(content.mdx, references)
+  return <article className="prose prose-lg max-w-none">{rendered}</article>
+}
+```
+<!-- cmx-sdk:end -->

package/templates/CLAUDE.md

@@ -0,0 +1,28 @@
+# Claude Code 設定
+
+> **注意:** `<!-- cmx-sdk:start -->` ～ `<!-- cmx-sdk:end -->` の範囲は `npx cmx-sdk update-sdk` で自動更新されます。
+> その範囲外はカスタマイズ可能です。
+
+<!-- cmx-sdk:start id="project-rules" -->
+## プロジェクトルール
+
+CMX Starter Kit のルール・アーキテクチャ・API パターンは `AGENTS.md` を参照。
+
+### コミット前
+
+変更を加えたらコミット前に必ずチェックを実行:
+
+```bash
+pnpm typecheck   # TypeScript 型チェック
+pnpm build       # ビルド確認
+npx cmx-sdk codegen check  # 生成コード整合チェック
+```
+
+または Studio の「チェック」ボタンを使用。
+<!-- cmx-sdk:end -->
+
+---
+
+## プロジェクト固有の設定
+
+<!-- ここにプロジェクト固有のルールやメモを追記してください -->

package/templates/claude/commands/check.md

@@ -0,0 +1,64 @@
+---
+name: Check
+description: ビルド・型・整合性を一括チェック
+disable-model-invocation: true
+allowed-tools: Bash
+continuation-mode: auto
+---
+
+# Check（ビルド・整合性チェック）
+
+## 実行内容
+
+以下をこの順番で実行する。エラーがあれば即座に報告して止まる。
+
+### 1. TypeScript 型チェック
+
+```bash
+pnpm typecheck
+```
+
+### 2. ビルド確認
+
+```bash
+pnpm build
+```
+
+### 3. 生成コードと import/tsconfig の整合チェック
+
+```bash
+npx cmx-sdk codegen check
+```
+
+## 出力フォーマット
+
+成功時:
+
+```
+## チェック結果
+
+- [x] TypeScript: 型エラーなし
+- [x] ビルド: 成功
+- [x] 整合性: 問題なし
+
+✅ すべてのチェックが通りました。
+```
+
+エラー時:
+
+```
+## チェック結果
+
+- [x] TypeScript: 型エラーなし
+- [ ] ビルド: ❌ エラー {n} 件
+- [ ] 整合性: スキップ（ビルドエラーのため）
+
+修正すべき箇所:
+1. {ファイル名}:{行番号} - {エラー内容}
+```
+
+## ルール
+
+- エラーが出たステップで止め、以降のステップはスキップする
+- エラー内容は要約せず、そのまま出力する
+- 修正案がある場合は箇条書きで提示する

package/templates/claude/commands/next-action.md

@@ -0,0 +1,66 @@
+---
+name: Next Action
+description: 迷ったときに現在地を確認し、次にやるべきことを案内
+disable-model-invocation: true
+allowed-tools: Bash, Read, Glob, Grep
+continuation-mode: auto
+---
+
+# Next Action
+
+## チェック項目
+
+### 環境
+
+- `.env.local` が存在するか
+- `CMX_API_KEY` が設定されているか
+
+### サイトコンフィグ
+
+- `cmx/site-config.md` が記入済みか（「未設定」が残っていないか）
+
+### スキーマ
+
+- `src/lib/constants/collections.ts` の登録スラッグ一覧
+- `cmx/generated/` の生成済みファイル一覧
+- 両者の不一致がないか
+
+### ページ
+
+- `src/app/` 配下のページ一覧
+- 登録済みコレクションに対応するページが全て存在するか
+- データタイプに対応するページが存在するか
+
+### コンポーネント
+
+- `cmx/components/` の JSON 定義一覧
+- `src/components/custom/index.ts` のエクスポート一覧
+- 定義と実装の不一致がないか
+
+## 判定ルール
+
+- 未完了（✗ または △）の項目が1つでもある場合は、未完了優先で次アクションを案内する
+- すべて完了（✓）の場合は、保守・改善フェーズ向けの追加提案を出す
+
+## 出力フォーマット
+
+```
+## Next Action（現在地）
+
+- [x] 環境: 設定済み
+- [ ] サイトコンフィグ: 一部未設定（未設定: {項目名...}）
+- [x] スキーマ: 整合済み（コレクション {n} / データタイプ {n}）
+- [ ] ページ: 未実装 {n} 件（{slug...}）
+- [x] コンポーネント: 整合済み（定義 {n} / 実装 {n}）
+
+### Next Action（最優先）
+- {1件だけ。具体的なコマンド付きで提示}
+  例: `/setup/05_pages` で未実装ページを作成する
+
+### 追加提案
+- 未完了がある場合:
+  - 未完了項目に直結する提案を最大2件
+- すべて完了している場合:
+  - 保守・改善に進む提案を最大2件
+  - 例: `/maintain/component`, `/maintain/style`, `/deploy`
+```

package/templates/claude/skills/cmx-cache/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: cmx-cache
+description: |
+  CMX Starter Kit のキャッシュ戦略スキル。force-dynamic → ISR 切り替え、sdkFetchWithTags、CACHE_TAGS、リバリデーション設定、Cloudflare R2 キャッシュ。
+  トリガー: 「キャッシュを設定」「ISRに切り替え」「リバリデーションを設定」
+  「force-dynamicを外す」「キャッシュタグを設定」「パフォーマンス改善」
+  「ページの表示速度を上げたい」「キャッシュ戦略」「R2キャッシュ」
+  「revalidateを設定」「オンデマンド再検証」など。
+---
+
+# CMX キャッシュ戦略
+
+## 現状の構成
+
+スターターキットの初期状態は全ページ `export const dynamic = "force-dynamic"`（毎リクエスト SSR）。ISR 基盤（R2 バケット、リバリデーション API）は構築済み。
+
+## ISR 移行の判断基準
+
+| 条件 | 推奨 |
+|------|------|
+| コンテンツ更新頻度が低い | ISR（revalidate: 3600 等） |
+| リアルタイム性が必要 | force-dynamic のまま |
+| プレビューページ | 常に force-dynamic |
+| 静的ページ（about 等） | ISR（revalidate: 86400）または静的生成 |
+
+## 移行手順
+
+詳細は [references/cache-patterns.md](references/cache-patterns.md) を参照。
+
+### 1. ページの revalidate 設定
+
+`export const dynamic = "force-dynamic"` を削除し `export const revalidate = 秒数` に変更。
+
+### 2. タグ付き fetch に切り替え
+
+`sdkFetchWithTags` を使い、CACHE_TAGS でタグを付与。
+
+### 3. リバリデーション API の確認
+
+`/api/revalidate` エンドポイントが動作することを確認。`REVALIDATE_API_KEY` 環境変数が必要。
+
+### 4. Cloudflare R2 の確認
+
+`wrangler.jsonc` で R2 バケットバインディング `NEXT_INC_CACHE_R2_BUCKET` が設定済みか確認。
+
+## 変更後
+
+1. デプロイ後にページの `Cache-Control` ヘッダーを確認
+2. コンテンツ更新後にリバリデーションが動作することを確認
+3. プレビューページが常に最新データを返すことを確認

package/templates/claude/skills/cmx-cache/references/cache-patterns.md

@@ -0,0 +1,153 @@
+# キャッシュ実装パターン
+
+## CACHE_TAGS
+
+`@cmx/api-client/core` または `cmx-sdk` からインポート:
+
+```tsx
+import { CACHE_TAGS } from "@/lib/api/admin-client"
+
+CACHE_TAGS.collections             // "collections" — 全コレクション
+CACHE_TAGS.collection("blog")      // "collection:blog" — 特定コレクション
+CACHE_TAGS.content("blog", "hello") // "content:blog:hello" — 特定記事
+CACHE_TAGS.data                    // "data" — 全データタイプ
+CACHE_TAGS.dataType("faq")         // "data:faq" — 特定データタイプ
+```
+
+## force-dynamic → ISR 移行
+
+### Before（毎リクエスト SSR）
+
+```tsx
+// src/app/blog/page.tsx
+export const dynamic = "force-dynamic"
+
+export default async function BlogPage() {
+  const data = await getCollectionContents("blog")
+  // ...
+}
+```
+
+### After（ISR + キャッシュタグ）
+
+```tsx
+// src/app/blog/page.tsx
+import { CACHE_TAGS, sdkFetchWithTags } from "@/lib/api/admin-client"
+
+export const revalidate = 3600 // 1時間
+
+export default async function BlogPage() {
+  const data = await sdkFetchWithTags<CollectionContentsResponse>(
+    `/sdk/collections/blog/contents`,
+    [CACHE_TAGS.collections, CACHE_TAGS.collection("blog")],
+    3600
+  )
+  // ...
+}
+```
+
+### 記事詳細ページ
+
+```tsx
+// src/app/blog/[slug]/page.tsx
+import { CACHE_TAGS, sdkFetchWithTags } from "@/lib/api/admin-client"
+
+export const revalidate = 3600
+
+export default async function BlogPostPage({ params }: PageProps) {
+  const { slug } = await params
+  const data = await sdkFetchWithTags<CollectionContentDetailResponse>(
+    `/sdk/collections/blog/contents/${slug}`,
+    [CACHE_TAGS.collection("blog"), CACHE_TAGS.content("blog", slug)],
+    3600
+  )
+  // ...
+}
+```
+
+## 推奨 revalidate 値
+
+| ページ種類 | revalidate | 理由 |
+|-----------|-----------|------|
+| トップページ | 600（10分） | 新着表示の鮮度 |
+| コレクション一覧 | 3600（1時間） | 記事追加は頻繁ではない |
+| 記事詳細 | 3600（1時間） | 公開後の修正は稀 |
+| データタイプ表示 | 3600（1時間） | 構造データの更新頻度 |
+| 静的ページ（about等） | 86400（1日） | ほぼ変わらない |
+| プレビュー | force-dynamic | 常に最新が必須 |
+
+## リバリデーション API
+
+### エンドポイント
+
+`POST /api/revalidate`
+
+### 認証
+
+```
+X-API-Key: {REVALIDATE_API_KEY}
+```
+
+### リクエスト例
+
+```bash
+# 特定コレクションのキャッシュを無効化
+curl -X POST https://yoursite.com/api/revalidate \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: your_secret_key" \
+  -d '{"tags": ["collection:blog"]}'
+
+# 特定記事のキャッシュを無効化
+curl -X POST https://yoursite.com/api/revalidate \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: your_secret_key" \
+  -d '{"tag": "content:blog:hello-world"}'
+```
+
+### CMX Admin からの連携
+
+CMX Admin の Webhook 設定でリバリデーション API を呼び出す:
+
+1. Admin の Webhook 設定画面で URL に `https://yoursite.com/api/revalidate` を登録
+2. ヘッダーに `X-API-Key` を設定
+3. イベント（記事公開・更新・削除）ごとに対応するタグを送信
+
+## Cloudflare R2 キャッシュ構成
+
+### 設定ファイル
+
+`open-next.config.ts`:
+
+```tsx
+import { defineCloudflareConfig } from "@opennextjs/cloudflare"
+import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache"
+
+export default defineCloudflareConfig({
+  incrementalCache: r2IncrementalCache,
+})
+```
+
+### wrangler.jsonc
+
+```jsonc
+{
+  "r2_buckets": [
+    {
+      "binding": "NEXT_INC_CACHE_R2_BUCKET",
+      "bucket_name": "my-website-cache"
+    }
+  ]
+}
+```
+
+### 環境ごとのバケット
+
+- 本番: `my-website-cache`
+- ステージング: `my-website-cache-stg`（`wrangler.jsonc` の `env.stg` で設定）
+
+## 環境変数チェックリスト
+
+| 変数 | 用途 | 必須タイミング |
+|------|------|--------------|
+| `REVALIDATE_API_KEY` | リバリデーション API の認証キー | ISR 使用時 |
+| `NEXT_INC_CACHE_R2_BUCKET`（バインディング） | R2 キャッシュバケット | Cloudflare デプロイ時 |