cmx-sdk 0.2.7 → 0.2.9

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

@@ -0,0 +1,266 @@
+---
+name: cmx-dev
+description: |
+  CMX Starter Kitの開発ガイド。cmx-sdkを使ったページ作成、データ取得、MDXレンダリング、コード生成を支援。
+  トリガー: 「ページを追加」「ブログページを作りたい」「データを表示」「コレクションページ」
+  「データ型のページ」「MDXをレンダリング」「型を生成」「npx cmx-sdk codegen types」
+  「CMXからデータを取得」「新しいルートを作成」「プレビューページ」など。
+---
+
+# CMX Starter Kit 開発ガイド
+
+## プロジェクト構成
+
+```
+src/
+├── app/                          # Next.js App Router ページ
+│   ├── blog/page.tsx             # コレクション一覧ページ
+│   ├── blog/[slug]/page.tsx      # コレクション記事詳細ページ
+│   └── preview/[token]/page.tsx  # プレビューページ
+├── components/custom/            # カスタムMDXコンポーネント
+├── lib/
+│   ├── api/
+│   │   ├── admin-client.ts       # cmx-sdk の re-export
+│   │   └── public-client.ts      # エラーハンドリング付きラッパー
+│   ├── mdx/render.tsx            # MDXレンダリング（カスタムコンポーネント注入）
+│   ├── utils/
+│   │   ├── data-fetching.ts      # requireFetchContents, requireFetchContent
+│   │   ├── metadata.ts           # generateCollectionMetadata, generateContentMetadata
+│   │   └── date.ts               # formatContentDate
+│   └── constants/collections.ts  # COLLECTION_SLUGS 定義
+```
+
+## タスク判定ツリー
+
+- **コレクション（ブログ/ニュース等）のページを追加** → [コレクションページ作成](#コレクションページ作成)
+- **データ型（チームメンバー/FAQ等）のページを追加** → [データ型ページ作成](#データ型ページ作成)
+- **静的ページを追加** → [静的ページ作成](#静的ページ作成)
+- **型安全なAPIコードを生成** → [コード生成](#コード生成)
+- **API関数の詳細を知りたい** → [references/api-patterns.md](references/api-patterns.md) を参照
+
+## コレクションページ作成
+
+CMX Admin で管理されたコレクション（ブログ、ニュース等）のページを作成する。
+
+### 一覧ページ
+
+```tsx
+// src/app/{collection}/page.tsx
+import type { Metadata } from "next"
+import { COLLECTION_SLUGS } from "@/lib/constants/collections"
+import { requireFetchContents } from "@/lib/utils/data-fetching"
+import { generateCollectionMetadata } from "@/lib/utils/metadata"
+import { formatContentDate } from "@/lib/utils/date"
+
+export const dynamic = "force-dynamic"
+
+export async function generateMetadata(): Promise<Metadata> {
+  return generateCollectionMetadata(COLLECTION_SLUGS.blog)
+}
+
+export default async function BlogListPage() {
+  const { collection, contents } = await requireFetchContents(COLLECTION_SLUGS.blog)
+
+  return (
+    <div className="container mx-auto px-4 py-12">
+      <h1 className="text-4xl font-bold mb-8">{collection.name}</h1>
+      <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+        {contents.map((item) => (
+          <a key={item.id} href={`/blog/${item.slug}`}>
+            <h2>{item.title}</h2>
+            <p>{item.description}</p>
+            {item.publishedAt && <time>{formatContentDate(item.publishedAt)}</time>}
+          </a>
+        ))}
+      </div>
+    </div>
+  )
+}
+```
+
+### 詳細ページ（MDXレンダリング付き）
+
+```tsx
+// src/app/{collection}/[slug]/page.tsx
+import type { Metadata } from "next"
+import { COLLECTION_SLUGS } from "@/lib/constants/collections"
+import { requireFetchContent } from "@/lib/utils/data-fetching"
+import { generateContentMetadata } from "@/lib/utils/metadata"
+import { renderMdx } from "@/lib/mdx/render"
+
+export const dynamic = "force-dynamic"
+
+interface PageProps {
+  params: Promise<{ slug: string }>
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { slug } = await params
+  return generateContentMetadata(COLLECTION_SLUGS.blog, slug)
+}
+
+export default async function BlogPostPage({ params }: PageProps) {
+  const { slug } = await params
+  const { content, references } = await requireFetchContent(COLLECTION_SLUGS.blog, slug)
+  const { content: renderedContent } = await renderMdx(content.mdx, references)
+
+  return (
+    <article className="container mx-auto px-4 py-12">
+      <div className="max-w-3xl mx-auto">
+        <h1 className="text-4xl font-bold mb-4">{content.title}</h1>
+        <div className="prose prose-lg max-w-none">{renderedContent}</div>
+      </div>
+    </article>
+  )
+}
+```
+
+### 新しいコレクションを追加する際の手順
+
+1. `src/lib/constants/collections.ts` に slug を追加
+2. `src/app/{slug}/page.tsx` — 一覧ページ作成
+3. `src/app/{slug}/[slug]/page.tsx` — 詳細ページ作成
+
+## データ型ページ作成
+
+CMX Admin で管理されたデータ型（チームメンバー、FAQ等）を表示するページ。
+
+```tsx
+// src/app/team/page.tsx
+import { getDataEntries } from "@/lib/api/admin-client"
+
+export const dynamic = "force-dynamic"
+
+interface TeamMember {
+  id: string
+  name?: string
+  role?: string
+  bio?: string
+  image?: string
+}
+
+export default async function TeamPage() {
+  const data = await getDataEntries("team-members", {
+    sortBy: "createdAt",
+    sortOrder: "asc",
+    // status: "published", // デフォルト。全ステータス取得は "all"
+  })
+  if (!data) throw new Error("Failed to fetch team members")
+  const members = data.items as unknown as TeamMember[]
+
+  return (
+    <div className="container mx-auto px-4 py-12">
+      <h1 className="text-4xl font-bold mb-8">チーム</h1>
+      <div className="grid grid-cols-1 md:grid-cols-3 gap-8">
+        {members.map((m) => (
+          <div key={m.id} className="text-center">
+            <h3 className="font-semibold">{m.name}</h3>
+            <p className="text-muted-foreground">{m.role}</p>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+```
+
+**型安全にしたい場合:** [コード生成](#コード生成)で型付き関数を生成。
+
+## 静的ページ作成
+
+CMX APIを使わない単純なページ。
+
+```tsx
+// src/app/about/page.tsx
+export const metadata = {
+  title: "About | CMX",
+  description: "About us page",
+}
+
+export default function AboutPage() {
+  return (
+    <div className="container mx-auto px-4 py-12">
+      <h1 className="text-4xl font-bold mb-4">About</h1>
+      <p>Your content here</p>
+    </div>
+  )
+}
+```
+
+## コード生成
+
+`cmx-sdk` CLI でワークスペースのスキーマから型付きTypeScript関数を自動生成。
+
+### 実行
+
+<!-- cmx-sync:start id="skill-cmx-dev-codegen-command-block" -->
+```bash
+npx cmx-sdk codegen types                              # デフォルト: cmx/generated/
+npx cmx-sdk codegen types --output cmx/generated           # 出力先を明示（通常は省略可）
+```
+<!-- cmx-sync:end -->
+
+**前提:** `.env.local`（または `.env`）に `CMX_API_URL` と `CMX_API_KEY` が設定されていること。
+
+### 生成されるもの
+
+```
+cmx/generated/
+├── index.ts                  # 全エクスポート
+├── collections/
+│   ├── blog.ts               # getBlogContents(), getBlogContentDetail()
+│   └── pages.ts              # getPagesContents(), getPagesContentDetail()
+└── data-types/
+    ├── team-members.ts        # TeamMember型, getTeamMembers(), getTeamMemberById()
+    └── faq.ts                 # Faq型, getFaqs(), getFaqById()
+```
+
+### 使い方
+
+```tsx
+// Before（汎用、型なし）
+import { getDataEntries } from "cmx-sdk"
+const { items } = await getDataEntries("team-members")
+// items[0].name は unknown
+
+// After（型付き、自動生成）
+import { getTeamMembers, getTeamMemberById } from "@cmx/generated"
+const { items } = await getTeamMembers()
+// items[0].name は string ✅
+const member = await getTeamMemberById("uuid")
+// member.name は string ✅
+```
+
+### スキーマ変更時
+
+CMX Admin でコレクションやデータ型を変更した場合は再実行:
+
+<!-- cmx-sync:start id="skill-cmx-dev-regenerate-command-block" -->
+```bash
+npx cmx-sdk codegen types
+```
+<!-- cmx-sync:end -->
+
+## 共通パターン
+
+### `export const dynamic = "force-dynamic"`
+
+全てのCMXデータ取得ページに必須。ビルド時にAPIコールが失敗しないようにする。
+
+### MDXレンダリング
+
+常に `src/lib/mdx/render.tsx` の `renderMdx` を使用。カスタムコンポーネントが自動注入される。
+
+```tsx
+import { renderMdx } from "@/lib/mdx/render"
+const { content } = await renderMdx(content.mdx, references)
+// content を JSX として直接レンダリング
+```
+
+### メタデータ生成
+
+コレクションページには既存ユーティリティを使用:
+
+```tsx
+import { generateCollectionMetadata, generateContentMetadata } from "@/lib/utils/metadata"
+```

package/templates/claude/skills/cmx-dev/references/api-patterns.md

@@ -0,0 +1,220 @@
+# CMX SDK API リファレンス
+
+## コンテンツ取得関数
+
+### getCollectionContents(slug, options?)
+
+コレクションの記事一覧を取得。
+
+```tsx
+import { getCollectionContents } from "@/lib/api/admin-client"
+// または直接: import { getCollectionContents } from "cmx-sdk"
+
+const data = await getCollectionContents("blog", {
+  sortBy: "publishedAt",
+  sortOrder: "desc",
+  limit: 10,
+  status: "published", // デフォルト。"all" で全ステータス、"draft,review" でカンマ区切り複数指定
+})
+// data.collection: { name, slug, description }
+// data.contents: Array<{ id, title, slug, description, publishedAt, status }>
+```
+
+**ユースケース:**
+- `status: "published"`（デフォルト）: 公開済みのみ取得（フロント表示用）
+- `status: "all"`: 全ステータス取得（AI執筆時の参照用）
+- `status: "draft,review"`: 複数ステータス指定
+
+### getCollectionContentDetail(collectionSlug, contentSlug)
+
+記事の詳細とMDX本文・リファレンスを取得。
+
+```tsx
+import { getCollectionContentDetail } from "@/lib/api/admin-client"
+
+const data = await getCollectionContentDetail("blog", "my-post")
+// data.collection: { name, slug }
+// data.content: { id, title, slug, description, mdx, publishedAt, ... }
+// data.references: { contents: {...}, assets: {...} }
+```
+
+### getDataEntries(typeSlug, options?)
+
+データ型のエントリ一覧を取得。
+
+```tsx
+import { getDataEntries } from "@/lib/api/admin-client"
+
+const data = await getDataEntries("team-members", {
+  sortBy: "createdAt",    // ソートフィールド
+  sortOrder: "desc",       // "asc" | "desc"
+  limit: 10,               // 取得件数
+  status: "published",     // デフォルト。"all" で全ステータス
+})
+// data.items: Array<{ id, ...フィールド }>
+```
+
+**ステータスフィルタ:**
+- `status: "published"`（デフォルト）: 公開済みのみ
+- `status: "all"`: 全ステータス（draft, published）
+
+### getDataEntry(typeSlug, id)
+
+データ型の単一エントリを取得。
+
+```tsx
+import { getDataEntry } from "@/lib/api/admin-client"
+
+const entry = await getDataEntry("team-members", "entry-uuid")
+```
+
+### getPreviewByToken(token)
+
+プレビュートークンでコンテンツを取得（認証不要）。
+
+```tsx
+import { getPreviewByToken } from "@/lib/api/admin-client"
+
+const data = await getPreviewByToken(token)
+if (data) {
+  // data.content: { title, mdx, status, environment, ... }
+  // data.collection: { name, slug }
+  // data.references: { contents, assets }
+}
+```
+
+## ラッパー関数
+
+`src/lib/utils/data-fetching.ts` のヘルパー。失敗時にエラーをthrowする。
+
+```tsx
+import {
+  requireFetchContents,  // getCollectionContents のラッパー
+  requireFetchContent,   // getCollectionContentDetail のラッパー
+  requireDataEntries,    // getDataEntries のラッパー
+} from "@/lib/utils/data-fetching"
+
+// 失敗時は Error をthrow（ページレベルでcatch）
+const { collection, contents } = await requireFetchContents("blog")
+const { content, references } = await requireFetchContent("blog", "my-post")
+const { items } = await requireDataEntries("faq")
+```
+
+## MDXレンダリング
+
+```tsx
+import { renderMdx } from "@/lib/mdx/render"
+
+// references はAPI応答から取得したもの
+const { content } = await renderMdx(item.mdx, references)
+
+// content はReactElement → JSXに直接埋め込み可能
+<div className="prose prose-lg max-w-none">{content}</div>
+```
+
+`renderMdx` は内部で `src/components/custom/index.ts` の全エクスポートを自動注入する。
+
+## コレクション付属データタイプ API
+
+### コレクションのデータタイプ一覧（SDK API）
+
+```
+GET /api/v1/sdk/manage/collections/{slug}/data-types
+```
+
+### コレクションにデータタイプを追加（SDK API）
+
+```
+POST /api/v1/sdk/manage/collections/{slug}/data-types
+Body: { "presetSlug": "categories" }  // プリセットから追加
+Body: { "slug": "custom", "name": "カスタム", "referenceType": "single", "fields": [...] }  // カスタム
+```
+
+### コレクションからデータタイプを削除（SDK API）
+
+```
+DELETE /api/v1/sdk/manage/collections/{slug}/data-types/{dtSlug}
+```
+
+### プリセット一覧（SDK API）
+
+```
+GET /api/v1/sdk/manage/collection-presets?type=post
+→ { "recommended": [...], "others": [...] }
+```
+
+### コンテンツの参照取得/設定（SDK API）
+
+```
+GET  /api/v1/sdk/manage/contents/{id}/references
+PUT  /api/v1/sdk/manage/contents/{id}/references
+Body: { "references": [{ "fieldSlug": "categories", "dataEntryIds": ["uuid"] }] }
+```
+
+### MCP API（AI向け）
+
+```
+GET /api/mcp/collections/{slug}/data-types                    # データタイプ一覧
+GET /api/mcp/collections/{slug}/data-types/{dtSlug}/entries   # エントリ一覧
+GET /api/mcp/collection-presets?type=post                     # プリセット一覧
+```
+
+## キャッシュタグ
+
+Next.js のオンデマンド再検証用:
+
+```tsx
+import { CACHE_TAGS } from "@/lib/api/admin-client"
+import { revalidateTag } from "next/cache"
+
+CACHE_TAGS.collections           // 全コレクション
+CACHE_TAGS.collection("blog")    // 特定コレクション
+CACHE_TAGS.content("blog", "slug") // 特定記事
+CACHE_TAGS.data                  // 全データ型
+CACHE_TAGS.dataType("faq")       // 特定データ型
+
+// 再検証
+revalidateTag(CACHE_TAGS.collection("blog"))
+```
+
+## メタデータ生成
+
+```tsx
+import {
+  generateCollectionMetadata,  // 一覧ページ用
+  generateContentMetadata,     // 詳細ページ用
+} from "@/lib/utils/metadata"
+
+// 一覧ページ
+export async function generateMetadata() {
+  return generateCollectionMetadata("blog")
+  // → { title: "ブログ | CMX", description: "..." }
+}
+
+// 詳細ページ
+export async function generateMetadata({ params }) {
+  const { slug } = await params
+  return generateContentMetadata("blog", slug)
+  // → { title: "記事タイトル | ブログ | CMX", description: "..." }
+}
+```
+
+## 型インポート
+
+```tsx
+import type {
+  CollectionContentsResponse,
+  CollectionContentDetailResponse,
+  DataListResponse,
+  DataEntryItem,
+  PreviewResponse,
+  References,
+} from "cmx-sdk"
+
+// エイリアス（admin-client.ts で定義済み）
+import type {
+  CollectionInfo,   // PublicCollectionInfo のエイリアス
+  ContentListItem,  // PublicContentListItem のエイリアス
+  ContentDetail,    // PublicContentDetail のエイリアス
+} from "@/lib/api/admin-client"
+```

package/templates/claude/skills/cmx-dev/references/cli-reference.md

@@ -0,0 +1,54 @@
+# cmx-sdk CLI リファレンス
+
+## コード生成
+
+<!-- cmx-sync:start id="skill-cmx-dev-cli-codegen-table" -->
+| コマンド | 説明 | 冪等性 |
+|---------|------|--------|
+| `npx cmx-sdk codegen types` | スキーマから TypeScript 型・取得関数を生成（`cmx/generated/`） | はい（何度でも再実行可能） |
+| `npx cmx-sdk codegen types --output <dir>` | 出力先を明示指定 | はい |
+| `npx cmx-sdk codegen pages --template layered` | ページ雛形を生成（`src/app/`, `src/features/`） | 既存ファイルは上書きしない |
+| `npx cmx-sdk codegen pages --template layered --only {category}:{slug}` | 特定のコレクション/データタイプ/フォームのみ生成 | 既存ファイルは上書きしない |
+<!-- cmx-sync:end -->
+
+**category** は `collections`, `data-types`, `forms` のいずれか。
+
+## スキーマ管理
+
+| コマンド | 説明 |
+|---------|------|
+| `npx cmx-sdk list-collections` | コレクション一覧 |
+| `npx cmx-sdk list-data-types` | グローバルデータタイプ一覧 |
+| `npx cmx-sdk list-forms` | フォーム一覧 |
+| `npx cmx-sdk list-collection-data-types --collection {slug}` | コレクション付属データタイプ一覧 |
+| `npx cmx-sdk list-collection-presets --type {type}` | プリセット一覧 |
+| `npx cmx-sdk create-collection --json '{...}'` | コレクション作成 |
+| `npx cmx-sdk create-data-type --json '{...}'` | グローバルデータタイプ作成 |
+| `npx cmx-sdk create-form --json '{...}'` | フォーム作成 |
+| `npx cmx-sdk add-collection-data-type --collection {slug} --preset {preset}` | 付属データタイプ追加（プリセット） |
+| `npx cmx-sdk add-collection-data-type --collection {slug} --json '{...}'` | 付属データタイプ追加（カスタム） |
+
+## コンテンツ管理
+
+| コマンド | 説明 |
+|---------|------|
+| `npx cmx-sdk create-content --collection {slug} --json '{...}'` | コンテンツ作成（draft ステータス） |
+| `npx cmx-sdk create-content --collection {slug} --file {path}` | ファイルから作成 |
+| `npx cmx-sdk request-review-content --id {contentId}` | レビュー依頼（draft → review） |
+| `npx cmx-sdk publish-content --id {contentId}` | 公開（review → published） |
+| `npx cmx-sdk set-content-references --id {contentId} --json '{...}'` | 参照設定（カテゴリ・タグ） |
+| `npx cmx-sdk create-data-entry --type-slug {slug} --json '{...}'` | データタイプエントリ作成 |
+
+## コンポーネント
+
+<!-- cmx-sync:start id="skill-cmx-dev-cli-components-table" -->
+| コマンド | 説明 |
+|---------|------|
+| `npx cmx-sdk components scaffold --name {Name}` | コンポーネント雛形生成 |
+| `npx cmx-sdk sync-components` | `cmx/components/` の JSON 定義を Admin に同期 |
+<!-- cmx-sync:end -->
+
+## 前提
+
+- `.env.local`（または `.env`）に `CMX_API_KEY` と `CMX_API_URL` が設定されていること
+- `npx cmx-sdk` はプロジェクトルートから実行すること

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

@@ -0,0 +1,103 @@
+---
+name: cmx-form
+description: |
+  CMX Starter Kit のフォーム実装スキル。Admin 側フォーム定義からフロント UI、submissions API 送信、バリデーション、スパム対策までの一貫ワークフロー。
+  トリガー: 「フォームを作りたい」「お問い合わせ」「コンタクトフォーム」「送信機能」
+  「フォームを追加」「submissions」「フォームバリデーション」など。
+---
+
+# CMX フォーム実装
+
+## ワークフロー
+
+### 1. フォーム設計
+
+ユーザーに確認:
+- 用途（お問い合わせ、資料請求、予約等）
+- 必要なフィールドと種類
+- バリデーション要件
+- 送信後の挙動（サンクスメッセージ、リダイレクト）
+
+### 2. Admin 側フォーム定義
+
+**2-1. 既存フォームの確認**
+
+まず既存のフォーム定義を確認して、重複がないことを確認:
+
+```bash
+npx cmx-sdk list-forms
+```
+
+**2-2. JSON生成とユーザー確認**
+
+フォーム定義 JSON を生成し、ユーザーに確認:
+
+```
+以下のフォームを Admin に登録します:
+
+- 名前: {name}
+- スラッグ: {slug}
+- フィールド数: {n}
+
+重複はありません。こちらで登録してもよろしいですか？
+```
+
+**2-3. cmx-sdk で登録**
+
+承認されたら、`cmx-sdk` コマンドで登録:
+
+```bash
+npx cmx-sdk create-form --json '{
+  "slug": "contact",
+  "name": "お問い合わせ",
+  "description": "お問い合わせフォーム",
+  "fields": [
+    {"key": "name", "label": "お名前", "type": "text", "required": true},
+    {"key": "email", "label": "メールアドレス", "type": "email", "required": true},
+    {"key": "message", "label": "メッセージ", "type": "textarea", "required": true}
+  ]
+}'
+```
+
+### 3. フロント実装
+
+クライアントコンポーネント（`"use client"`）として作成。
+
+テンプレート: [references/form-template.md](references/form-template.md)
+
+実装ポイント:
+- `useState` でフォーム状態・送信状態・エラーを管理
+- Zod スキーマでクライアントバリデーション
+- ハニーポットフィールド（`_hp`）を隠しフィールドとして設置
+- `POST /api/v1/sdk/submissions/{formSlug}` に送信
+- 送信は `cmx-sdk` の関数 or 直接 fetch（APIキーは不要、公開エンドポイント）
+
+### 4. 送信処理
+
+```tsx
+const response = await fetch(`${process.env.NEXT_PUBLIC_CMX_API_URL}/api/v1/sdk/submissions/${formSlug}`, {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ ...formData, _hp: honeypotValue }),
+})
+```
+
+- `_hp` フィールドが空でない場合、サーバー側でスパムとして弾く
+- 成功: 200 → サンクスメッセージ表示
+- エラー: 4xx/5xx → エラーメッセージ表示
+
+### 5. 動作確認
+
+- フォーム送信テスト
+- Admin 側で送信一覧に表示されることを確認
+- バリデーションエラーの表示を確認
+- ハニーポットが機能することを確認
+
+## チェックリスト
+
+- [ ] クライアントコンポーネント（`"use client"`）として作成
+- [ ] Zod バリデーション
+- [ ] ハニーポットフィールド（`_hp`）設置
+- [ ] 送信中・成功・エラーの UI 状態
+- [ ] site-config.md のトーン・デザインに沿ったスタイリング
+- [ ] アクセシビリティ（label、aria、エラーメッセージの関連付け）