cmx-sdk 0.2.6 → 0.2.8

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 デプロイ時 |

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

@@ -0,0 +1,108 @@
+---
+name: cmx-component
+description: |
+  CMX Starter Kitのカスタムコンポーネント作成・管理スキル。
+  MDXコンテンツ内で使えるカスタムReactコンポーネントの定義（JSON）、実装（TSX）、エクスポート、同期の全ワークフローを提供。
+  トリガー: 「コンポーネントを作成」「カスタムコンポーネントを追加」「MDXコンポーネントを作りたい」
+  「FeatureCardのようなコンポーネントが欲しい」「CMXにコンポーネントを同期」など。
+---
+
+# CMX Custom Component ワークフロー
+
+## ファイル構成
+
+```
+cmx/components/{name}.json       # コンポーネント定義（CMX Admin用）
+src/components/custom/{Name}.tsx   # React実装
+src/components/custom/index.ts     # エクスポート一覧
+```
+
+## ワークフロー
+
+### 1. ヒアリング
+
+ユーザーに確認:
+- 用途（何を表示するか）
+- 必須/任意のprops
+- デザインの方向性
+
+### 2. JSON定義を作成
+
+`cmx/components/{kebab-case}.json` に作成。詳細フォーマットは [references/component-schema.md](references/component-schema.md) を参照。
+
+```json
+{
+  "name": "FeatureCard",
+  "displayName": "Feature Card",
+  "description": "Display a feature with icon, title, and description",
+  "propsSchema": {
+    "title": {
+      "type": "string",
+      "description": "Feature title",
+      "required": true
+    },
+    "icon": {
+      "type": "string",
+      "description": "Emoji icon",
+      "required": false
+    },
+    "children": {
+      "type": "string",
+      "description": "Card body text",
+      "required": true
+    }
+  },
+  "examples": [
+    "title=\"Fast\" icon=\"⚡\">Lightning fast load times</FeatureCard>",
+    "title=\"Simple\">Easy to use interface</FeatureCard>"
+  ]
+}
+```
+
+### 3. React実装
+
+`src/components/custom/{PascalCase}.tsx` に作成:
+
+```tsx
+interface FeatureCardProps {
+  title: string
+  icon?: string
+  children: React.ReactNode
+}
+
+export function FeatureCard({ title, icon, children }: FeatureCardProps) {
+  return (
+    <div className="rounded-lg border bg-card p-6 shadow-sm">
+      {icon && <div className="mb-3 text-3xl">{icon}</div>}
+      <h3 className="mb-2 text-lg font-semibold">{title}</h3>
+      <div className="text-sm text-muted-foreground">{children}</div>
+    </div>
+  )
+}
+```
+
+**スタイリングルール:**
+- Tailwind CSS を使用
+- shadcn/ui の CSS変数（`bg-card`, `text-muted-foreground` 等）を活用
+- レスポンシブ対応（`md:`, `lg:` プレフィックス）
+- セマンティックHTML
+
+### 4. エクスポート追加
+
+`src/components/custom/index.ts` に追記:
+
+```ts
+export { FeatureCard } from "./FeatureCard"
+```
+
+このファイルで export されたコンポーネントは、MDXレンダリング時に自動的に利用可能になる（`src/lib/mdx/render.tsx` が `import * as customComponents` で読み込む）。
+
+## チェックリスト
+
+- [ ] `cmx/components/{name}.json` が正しいフォーマット
+- [ ] `src/components/custom/{Name}.tsx` が実装済み
+- [ ] `src/components/custom/index.ts` にエクスポート追加
+- [ ] props の型が JSON定義と TSX実装で一致
+- [ ] children を使うコンポーネントは `React.ReactNode` 型で受け取り
+- [ ] Tailwind CSS でスタイリング
+- [ ] アクセシビリティ考慮（セマンティックHTML、ARIA）

package/templates/claude/skills/cmx-component/references/component-schema.md

@@ -0,0 +1,123 @@
+# コンポーネント定義 JSON リファレンス
+
+## 必須フィールド
+
+| フィールド | 型 | 説明 |
+|-----------|------|------|
+| `name` | string | PascalCase。TSXファイル名・MDXタグ名と一致させる |
+| `displayName` | string | CMX Admin UIに表示される名前（日本語可） |
+| `description` | string | 用途の説明。1-2文 |
+| `propsSchema` | object | props定義（下記参照） |
+
+## オプションフィールド
+
+| フィールド | 型 | 説明 |
+|-----------|------|------|
+| `examples` | string[] | MDXでの使用例。2-3個推奨 |
+
+## propsSchema フォーマット
+
+```json
+"propsSchema": {
+  "propName": {
+    "type": "string",
+    "description": "Prop description",
+    "required": true
+  }
+}
+```
+
+### prop の type
+
+| type | 用途 | TSX型 |
+|------|------|-------|
+| `string` | テキスト | `string` |
+| `number` | 数値 | `number` |
+| `boolean` | フラグ | `boolean` |
+| `enum` | 列挙値 | `string` |
+| `asset` | アセットID | `string` |
+| `content` | コンテンツID | `string` |
+
+### prop のフラグ
+
+- `"required": true` — 必須prop
+- `"required": false` — 任意prop
+- `"default": value` — デフォルト値（任意）
+
+## examples フォーマット
+
+### セルフクロージング
+
+```json
+"examples": [
+  "title=\"Example\" count={42}"
+]
+```
+
+MDXでは `<ComponentName title="Example" count={42} />` として表示。
+
+### children あり
+
+```json
+"examples": [
+  "title=\"Title\">Content here</ComponentName>"
+]
+```
+
+MDXでは:
+```mdx
+<ComponentName title="Title">
+  Content here
+</ComponentName>
+```
+
+## バリデーションルール
+
+- `name`: PascalCase、英数字のみ、大文字始まり
+- `displayName`: 2-4語推奨
+- `description`: 1-2文
+- `propsSchema` の各 prop: `type` は必須
+- `type: object` / `properties` を使うJSON Schema形式は非対応
+- `examples`: 異なるpropの組み合わせを示す
+
+## 完全な例
+
+```json
+{
+  "name": "PricingCard",
+  "displayName": "Pricing Card",
+  "description": "Display a pricing plan with features list and CTA button",
+  "propsSchema": {
+    "plan": {
+      "type": "string",
+      "description": "Plan name (e.g., 'Free', 'Pro', 'Enterprise')",
+      "required": true
+    },
+    "price": {
+      "type": "string",
+      "description": "Price display text (e.g., '$9/mo', 'Custom')",
+      "required": true
+    },
+    "features": {
+      "type": "string",
+      "description": "Comma-separated feature list",
+      "required": true
+    },
+    "highlighted": {
+      "type": "boolean",
+      "description": "Highlight this card as recommended",
+      "required": false,
+      "default": false
+    },
+    "children": {
+      "type": "string",
+      "description": "Additional description or CTA content",
+      "required": false
+    }
+  },
+  "examples": [
+    "plan=\"Free\" price=\"$0/mo\" features=\"5 posts,Basic support\"",
+    "plan=\"Pro\" price=\"$29/mo\" features=\"Unlimited,Priority support\" highlighted={true}>Most popular</PricingCard>"
+  ]
+}
+```

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

@@ -0,0 +1,158 @@
+---
+name: cmx-content
+description: |
+  CMX Starter Kit のコンテンツ作成・投入スキル。Admin API 経由でのテストデータ投入、既存サイトからのコンテンツ移行、MDX テンプレート。
+  トリガー: 「テストデータを入れたい」「記事を投入」「シードデータ」「サイト移行」
+  「コンテンツを移行」「既存サイトからインポート」「スクレイピングして記事を作成」
+  「ダミーデータ」「サンプル記事」「テスト用の記事」など。
+---
+
+# CMX コンテンツ作成・投入
+
+## 事前確認
+
+1. `.env.local`（または `.env`）に `CMX_API_KEY` と `CMX_API_URL` が設定済みか確認
+2. Admin 側でコレクションが登録済みか確認（未登録なら `/setup/03_schema` を先に）
+3. `cmx/site-config.md` と `workflows/style-guide.md` を読み、トーン・スタイルに合った記事を生成する
+
+## 2つのユースケース
+
+### A. テストデータ投入（新規サイト）
+
+初期構築時に表示確認用の記事を作成する。詳細は [references/seed-patterns.md](references/seed-patterns.md) を参照。
+
+### B. サイト移行（既存コンテンツ取り込み）
+
+既存サイトのページをスクレイピング → MDX に変換 → Admin API で投入。詳細は [references/migration-patterns.md](references/migration-patterns.md) を参照。
+
+## ステータス運用ルール
+
+コンテンツ作成後のステータスは、タスクの性質に応じて使い分ける。**明示的に「公開して」と指示されない限り、公開（publish）は行わない。**
+
+| タスクの性質 | 保存先ステータス | 例 |
+|------------|----------------|-----|
+| 案出し・探索的なタスク | **draft**（下書き） | 「いくつか記事のアイデアを出して」「テスト記事を作って」 |
+| タスク内で記事作成が完結する場合 | **review**（レビュー依頼） | 「新しく記事を作成して」「移行記事を投入して」 |
+| ユーザーが明示的に公開を指示した場合のみ | **published**（公開） | 「公開して」「publishして」 |
+
+## Admin API でのコンテンツ作成
+
+CMX SDK CLIコマンドでコンテンツを作成します：
+
+```bash
+npx cmx-sdk create-content --collection blog --json '{
+  "title": "記事タイトル",
+  "slug": "article-slug",
+  "description": "記事の説明文",
+  "mdx": "# 見出し\n\n本文..."
+}'
+```
+
+または、ファイルから読み込む場合：
+
+```bash
+npx cmx-sdk create-content --collection blog --file content.json
+```
+
+コマンドの出力例：
+```json
+{
+  "id": "uuid",
+  "slug": "article-slug"
+}
+```
+
+初期ステータスは `draft` です。作成されたコンテンツIDを控えておいてください。
+
+### レビューに送る場合（タスク完結時）
+
+コンテンツを作成した後、レビューステータスに変更：
+
+```bash
+npx cmx-sdk request-review-content --id {contentId}
+```
+
+これにより、ステータスが `draft` → `review` に変更されます。
+
+### 公開する場合（ユーザーが明示的に指示した場合のみ）
+
+公開には `review` ステータスが前提です。まだ `draft` の場合は `request-review-content` を先に実行してください。
+
+```bash
+npx cmx-sdk publish-content --id {contentId}
+```
+
+これにより、ステータスが `review` → `published` に変更され、公開URLが返されます。
+
+> **注意**: `publish-content` は `review` ステータスのコンテンツにのみ実行可能です。`draft` から直接公開することはできません。
+
+### コレクション一覧の確認
+
+```bash
+npx cmx-sdk list-collections
+```
+
+このコマンドで、コレクションの slug や ID を確認できます。`create-content` コマンドでは `--collection` オプションに slug を指定すれば、自動的に ID に変換されます。
+
+## データタイプのテストデータ
+
+### グローバルデータタイプ（公開サイトに直接表示）
+
+公開サイトに直接表示されるデータタイプ（スタッフ、商品、店舗等）のエントリを作成する場合、`published` フィールドを `true` に設定する必要があります（デフォルトは `false`）。
+
+```bash
+# 例: スタッフ情報のエントリを作成（published: true で公開）
+npx cmx-sdk create-data-entry --type-slug staff --json '{"name":"山田太郎","role":"エンジニア","published":true}'
+
+# 例: 店舗情報のエントリを作成（published: true で公開）
+npx cmx-sdk create-data-entry --type-slug locations --json '{"name":"東京オフィス","address":"東京都渋谷区...","published":true}'
+
+# カスタム: 商品情報のエントリを作成
+npx cmx-sdk create-data-entry --type-slug products --json '{"name":"商品A","price":1000,"published":true}'
+```
+
+**重要:** `published: false` または未設定の場合、Public API では取得できません。
+
+### コレクション付属データタイプ（カテゴリ・タグ等）
+
+コレクションに付属データタイプ（カテゴリ・タグ等）がある場合、エントリ作成→コンテンツへの参照設定が必要。
+
+#### 1. 付属データタイプのエントリ作成
+
+```bash
+# コレクションの付属データタイプを確認
+npx cmx-sdk list-collection-data-types --collection blog
+
+# カテゴリエントリを作成
+npx cmx-sdk create-data-entry --type-slug blog-categories --json '{"name":"技術ブログ","description":"テック系の記事"}'
+npx cmx-sdk create-data-entry --type-slug blog-categories --json '{"name":"デザイン","description":"デザイン系の記事"}'
+
+# タグエントリを作成
+npx cmx-sdk create-data-entry --type-slug blog-tags --json '{"name":"Next.js"}'
+npx cmx-sdk create-data-entry --type-slug blog-tags --json '{"name":"TypeScript"}'
+```
+
+#### 2. コンテンツに参照を設定
+
+コンテンツ作成後、CLIコマンドで参照を設定:
+
+```bash
+npx cmx-sdk set-content-references --id {contentId} --json '{
+  "references": [
+    { "fieldSlug": "categories", "dataEntryIds": ["カテゴリエントリのUUID"] },
+    { "fieldSlug": "tags", "dataEntryIds": ["タグ1のUUID", "タグ2のUUID"] }
+  ]
+}'
+```
+
+または、ファイルから読み込む場合：
+
+```bash
+npx cmx-sdk set-content-references --id {contentId} --file references.json
+```
+
+## 変更後
+
+1. Admin の投稿一覧で記事が作成されていることを確認
+2. フロントの開発サーバーで記事が表示されることを確認
+3. テストデータは確認後に削除可能（Admin の投稿一覧から）

package/templates/claude/skills/cmx-content/references/migration-patterns.md

@@ -0,0 +1,120 @@
+# サイト移行パターン
+
+## 移行フロー
+
+```
+1. 既存サイトの URL 一覧を取得（sitemap.xml or 手動リスト）
+2. 各ページをスクレイピングしてコンテンツを取得
+3. HTML → MDX に変換
+4. Admin API で draft として投入
+5. 内容を確認・調整
+6. 問題なければ publish
+```
+
+## ステップ 1: URL 一覧の取得
+
+### sitemap.xml から
+
+```typescript
+const sitemapUrl = "https://old-site.com/sitemap.xml"
+const response = await fetch(sitemapUrl)
+const xml = await response.text()
+// XML をパースして <loc> タグから URL を抽出
+```
+
+### 手動リスト
+
+ユーザーに URL リストを提供してもらう。
+
+## ステップ 2: スクレイピング
+
+```typescript
+const response = await fetch(url)
+const html = await response.text()
+// HTML をパースして記事コンテンツを抽出
+```
+
+**抽出対象:**
+- タイトル（`<h1>` or `<title>`）
+- 本文（`<article>` or `<main>` 内のコンテンツ）
+- メタ説明文（`<meta name="description">`）
+- 公開日（`<time>` or meta タグ）
+- アイキャッチ画像（OG image or 最初の画像）
+
+## ステップ 3: HTML → MDX 変換
+
+### 基本変換ルール
+
+| HTML | MDX |
+|------|-----|
+| `<h2>` | `## ` |
+| `<h3>` | `### ` |
+| `<p>` | そのまま（タグ除去） |
+| `<strong>` | `**テキスト**` |
+| `<em>` | `*テキスト*` |
+| `<a href="url">` | `[テキスト](url)` |
+| `<ul><li>` | `- テキスト` |
+| `<ol><li>` | `1. テキスト` |
+| `<blockquote>` | `> テキスト` |
+| `<code>` | `` `テキスト` `` |
+| `<pre><code>` | ` ```lang\nコード\n``` ` |
+| `<img>` | `![alt](src)` |
+| `<table>` | Markdown テーブル |
+
+### 注意点
+
+- `<script>`, `<style>`, `<iframe>` は除去
+- クラス名・ID は除去
+- インライン style は除去
+- 相対 URL は絶対 URL に変換
+- 画像は外部 URL のまま（後で Admin にアップロード可能）
+
+## ステップ 4: CLIコマンドで投入
+
+各ページのデータをJSONファイルに保存し、CLIコマンドで投入:
+
+```bash
+# 各ページごとにコンテンツを作成
+for page in convertedPages; do
+  npx cmx-sdk create-content --collection blog --json '{
+    "title": "'"$page.title"'",
+    "slug": "'"$page.slug"'",
+    "description": "'"$page.description"'",
+    "mdx": "'"$page.mdx"'"
+  }'
+done
+```
+
+または、JSONファイルから一括投入する場合：
+
+```bash
+# content1.json, content2.json などのファイルを作成しておき
+npx cmx-sdk create-content --collection blog --file content1.json
+npx cmx-sdk create-content --collection blog --file content2.json
+# ...
+```
+
+## ステップ 5: 確認・調整
+
+- Admin の投稿一覧で全記事が作成されていることを確認
+- プレビューで MDX のレンダリングを確認
+- 変換エラー（崩れたテーブル、欠落した画像等）を手動修正
+
+## コレクションの振り分け
+
+移行元のページ構造に応じて振り分ける:
+
+| 移行元 | 振り分け先 |
+|--------|-----------|
+| ブログ記事 | post タイプのコレクション |
+| ニュース・お知らせ | news タイプのコレクション |
+| 固定ページ（会社概要等） | page タイプのコレクション |
+| ヘルプ・ドキュメント | doc タイプのコレクション |
+
+## slug の生成
+
+移行元の URL パスから生成:
+
+- `https://old-site.com/blog/2024/01/my-article` → `my-article`
+- 日本語 URL の場合はローマ字化 or 英語に変換
+- 重複チェック: `search_posts` で既存 slug と衝突しないか確認