cmx-sdk 0.2.7 → 0.2.9

package/templates/claude/skills/cmx-form/references/form-template.md

@@ -0,0 +1,152 @@
+# フォームテンプレート
+
+## 基本構造
+
+```tsx
+// src/app/{path}/contact-form.tsx
+"use client"
+
+import { useState } from "react"
+import { z } from "zod"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Textarea } from "@/components/ui/textarea"
+import { Label } from "@/components/ui/label"
+
+const formSchema = z.object({
+  name: z.string().min(1, "お名前を入力してください"),
+  email: z.string().email("正しいメールアドレスを入力してください"),
+  message: z.string().min(1, "メッセージを入力してください"),
+})
+
+type FormData = z.infer<typeof formSchema>
+
+export function ContactForm() {
+  const [formData, setFormData] = useState<FormData>({ name: "", email: "", message: "" })
+  const [honeypot, setHoneypot] = useState("")
+  const [errors, setErrors] = useState<Partial<Record<keyof FormData, string>>>({})
+  const [status, setStatus] = useState<"idle" | "submitting" | "success" | "error">("idle")
+  const [errorMessage, setErrorMessage] = useState("")
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setErrors({})
+    setErrorMessage("")
+
+    // バリデーション
+    const result = formSchema.safeParse(formData)
+    if (!result.success) {
+      const fieldErrors: Partial<Record<keyof FormData, string>> = {}
+      for (const issue of result.error.issues) {
+        const field = issue.path[0] as keyof FormData
+        fieldErrors[field] = issue.message
+      }
+      setErrors(fieldErrors)
+      return
+    }
+
+    setStatus("submitting")
+
+    try {
+      const response = await fetch(
+        `${process.env.NEXT_PUBLIC_CMX_API_URL}/api/v1/sdk/submissions/contact`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ ...result.data, _hp: honeypot }),
+        }
+      )
+
+      if (!response.ok) {
+        throw new Error("送信に失敗しました")
+      }
+
+      setStatus("success")
+      setFormData({ name: "", email: "", message: "" })
+    } catch {
+      setStatus("error")
+      setErrorMessage("送信に失敗しました。しばらく経ってから再度お試しください。")
+    }
+  }
+
+  if (status === "success") {
+    return (
+      <div className="rounded-lg border bg-card p-8 text-center">
+        <h3 className="text-lg font-semibold mb-2">送信完了</h3>
+        <p className="text-muted-foreground">お問い合わせありがとうございます。</p>
+      </div>
+    )
+  }
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-6">
+      {/* ハニーポット（非表示） */}
+      <div className="hidden" aria-hidden="true">
+        <input
+          type="text"
+          name="_hp"
+          tabIndex={-1}
+          autoComplete="off"
+          value={honeypot}
+          onChange={(e) => setHoneypot(e.target.value)}
+        />
+      </div>
+
+      <div className="space-y-2">
+        <Label htmlFor="name">お名前 *</Label>
+        <Input
+          id="name"
+          value={formData.name}
+          onChange={(e) => setFormData((prev) => ({ ...prev, name: e.target.value }))}
+          aria-invalid={!!errors.name}
+          aria-describedby={errors.name ? "name-error" : undefined}
+        />
+        {errors.name && <p id="name-error" className="text-sm text-destructive">{errors.name}</p>}
+      </div>
+
+      <div className="space-y-2">
+        <Label htmlFor="email">メールアドレス *</Label>
+        <Input
+          id="email"
+          type="email"
+          value={formData.email}
+          onChange={(e) => setFormData((prev) => ({ ...prev, email: e.target.value }))}
+          aria-invalid={!!errors.email}
+          aria-describedby={errors.email ? "email-error" : undefined}
+        />
+        {errors.email && <p id="email-error" className="text-sm text-destructive">{errors.email}</p>}
+      </div>
+
+      <div className="space-y-2">
+        <Label htmlFor="message">メッセージ *</Label>
+        <Textarea
+          id="message"
+          rows={5}
+          value={formData.message}
+          onChange={(e) => setFormData((prev) => ({ ...prev, message: e.target.value }))}
+          aria-invalid={!!errors.message}
+          aria-describedby={errors.message ? "message-error" : undefined}
+        />
+        {errors.message && <p id="message-error" className="text-sm text-destructive">{errors.message}</p>}
+      </div>
+
+      {errorMessage && (
+        <div className="rounded-lg border border-destructive bg-destructive/10 p-4 text-sm text-destructive">
+          {errorMessage}
+        </div>
+      )}
+
+      <Button type="submit" disabled={status === "submitting"}>
+        {status === "submitting" ? "送信中..." : "送信する"}
+      </Button>
+    </form>
+  )
+}
+```
+
+## カスタマイズポイント
+
+- `formSchema`: フィールドに合わせて Zod スキーマを変更
+- `formSlug`: Admin で定義したフォームのスラッグに合わせる
+- スタイリング: site-config.md のデザイン方針に沿って調整
+- 送信後の挙動: サンクスメッセージ or リダイレクト

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

@@ -0,0 +1,501 @@
+---
+name: cmx-migrate
+description: |
+  既存サイトをCMXに移行するためのスキル。Firecrawl CLI と agent-browser を使ったサイト解析、
+  スキーマ自動提案、コンテンツ一括移行、スタイル移行を支援する。
+  トリガー: 「サイトを移行」「既存HPをCMXに」「サイトを解析」「ホームページを移行」
+  「移行」「マイグレーション」「既存サイトをインポート」「サイト構造を分析」
+---
+
+# CMX サイト移行スキル
+
+既存サイトのURLひとつから、CMXサイトとして再構築するための5ステップ移行フローを提供する。
+
+## ツール構成
+
+| ツール | 用途 | インストール |
+|-------|------|------------|
+| Firecrawl CLI | URL発見・クロール・構造化抽出 | `npm i -g firecrawl-cli` |
+| agent-browser | スクショ撮影・スタイル情報抽出 | スキルとして利用可能 |
+| cmx-sdk CLI | スキーマ登録・コード生成・コンテンツ投入 | プロジェクト内蔵 |
+
+## エージェント設計原則
+
+### 親エージェント（メインコンテキスト）が担当
+
+- サイト構造の把握・判断
+- ユーザーとの対話・確認
+- スキーマ設計・マッピング
+- 子エージェントの起動と結果集約
+
+### 子エージェント（Task tool で起動）に委譲
+
+**以下のタスクは必ず子エージェントに委譲する。親のコンテキストウィンドウを節約するため。**
+
+1. **コンテンツ変換・投入**（Step 4）
+   - crawl-result.json の各ページを MDX に変換
+   - `npx cmx-sdk create-content` で投入
+   - 5-10件/バッチで処理
+2. **設定ファイル生成**（Step 3 の一部）
+   - site-config.md, style-guide.md の生成
+3. **コンポーネント作成**（Step 3 の一部）
+   - componentCandidates に基づくコンポーネント実装
+4. **スクショ比較**（Step 5）
+   - 移行元と移行先のビジュアル比較
+
+### 子エージェントへの指示ルール
+
+子に渡すもの:
+- 対象データ（URLリスト or ページデータ）
+- 変換ルール（[references/html-to-mdx.md](references/html-to-mdx.md) の内容を簡潔に）
+- 使用コマンド
+- 期待する出力フォーマット（JSON）
+
+子に渡さないもの:
+- site-config.md 全文
+- 他のページのデータ
+- スキーマ設計の経緯
+- migration-plan.json 全体（該当部分のみ抜粋）
+
+### 子エージェントの出力フォーマット
+
+```json
+{
+  "batch_id": "batch-001",
+  "results": [
+    { "url": "/blog/post-1", "status": "success", "contentId": "uuid", "slug": "post-1", "title": "記事タイトル" },
+    { "url": "/blog/post-2", "status": "error", "error": "変換エラー: テーブル構造が複雑" }
+  ],
+  "summary": { "total": 10, "success": 9, "error": 1 }
+}
+```
+
+---
+
+## Step 1: 解析
+
+### 1-1. URL発見
+
+```bash
+firecrawl map {url} --limit 1000 -o cmx/migration/urls.json
+```
+
+`urls.json` からURL一覧を読み取り、以下を分析:
+
+- URLパターンのグルーピング（`/blog/*`, `/news/*`, `/about` 等）
+- 各グループのページ数
+- 一覧ページ vs 詳細ページの推定
+
+### 1-2. 全ページクロール
+
+```bash
+firecrawl crawl {url} --limit 200 --max-depth 3 --wait --progress -o cmx/migration/crawl-result.json
+```
+
+全ページの Markdown + メタデータ（title, description, OGP）が取得される。
+
+### 1-3. 構造化データ抽出
+
+各ページグループの代表的な一覧ページに対して Firecrawl の scrape + JSON フォーマットで構造を抽出する。
+
+```bash
+firecrawl scrape {list_page_url} --format json --json-prompt "Extract the list structure: what fields does each item have (title, date, category, thumbnail, author, description)? What categories or tags exist?" -o cmx/migration/structure/{group_slug}.json
+```
+
+抽出結果から:
+- コレクションのフィールド候補を推定
+- カテゴリ/タグの既存値を収集
+- データタイプのフィールド構造を推定
+
+### 1-4. ビジュアル解析（agent-browser）
+
+代表ページ（3-5ページ）に対して agent-browser で:
+
+1. **スクリーンショット撮影**
+   ```
+   open {url}
+   screenshot cmx/migration/screenshots/home.png
+   ```
+
+2. **スタイル情報抽出**（JS 実行）
+   ```
+   eval "JSON.stringify({
+     bodyBg: getComputedStyle(document.body).backgroundColor,
+     bodyColor: getComputedStyle(document.body).color,
+     bodyFont: getComputedStyle(document.body).fontFamily,
+     h1Font: document.querySelector('h1') ? getComputedStyle(document.querySelector('h1')).fontFamily : null,
+     h1Size: document.querySelector('h1') ? getComputedStyle(document.querySelector('h1')).fontSize : null,
+     linkColor: document.querySelector('a') ? getComputedStyle(document.querySelector('a')).color : null,
+     navBg: document.querySelector('nav') ? getComputedStyle(document.querySelector('nav')).backgroundColor : null
+   })"
+   ```
+
+3. **ナビゲーション構造の取得**
+   ```
+   snapshot
+   ```
+   → セマンティック構造から nav, header, footer, main を特定
+
+### 1-5. 成果物の生成
+
+上記の情報を統合して以下を生成:
+
+**`cmx/migration/site-analysis.md`** — 人間が読む解析レポート
+
+```markdown
+# サイト解析レポート
+
+## 基本情報
+- 移行元URL: {url}
+- 解析日: {date}
+- 発見URL数: {n}件
+
+## ページ構成
+### コレクション候補
+- /blog/* (25件) → post型コレクション「ブログ」
+- /news/* (15件) → news型コレクション「お知らせ」
+
+### 固定ページ
+- /about → 会社概要
+- /contact → お問い合わせ（フォームあり）
+
+### データタイプ候補
+- スタッフ一覧（/about 内、5名）
+- FAQ（/faq 内、12件）
+
+## スタイル情報
+- メインカラー: {color}
+- フォント: {font}
+- トーン: {tone}
+```
+
+**`cmx/migration/site-map.json`** — 構造化データ（フォーマット詳細は [references/intermediate-format.md](references/intermediate-format.md) を参照）
+
+---
+
+## Step 2: 計画
+
+`site-map.json` を読み込み、ユーザーと対話的に移行計画を策定する。
+
+### 2-1. コレクション定義
+
+```
+site-map.json の pageGroups から type: "collection" を抽出
+
+提案例:
+  /blog/* → コレクション "blog"（type: post）
+    付属データタイプ: categories, tags
+  /news/* → コレクション "news"（type: news）
+    付属データタイプ: categories
+
+ユーザーに確認 → 確定
+```
+
+参考: cmx-schema スキルの [references/migration-scenarios.md](../cmx-schema/references/migration-scenarios.md)
+
+### 2-2. データタイプ定義
+
+```
+site-map.json の dataTypeCandidates を提案
+
+提案例:
+  staff — name(text), position(text), photo(image)
+  faq — question(text), answer(richtext), category(select)
+
+ユーザーに確認 → フィールドの追加・削除・型変更
+```
+
+参考: cmx-schema スキルの [references/field-types.md](../cmx-schema/references/field-types.md)
+
+### 2-3. コンポーネント候補
+
+```
+site-map.json の componentCandidates を提案
+
+提案例:
+  FeatureCard — icon, title, description（/about, / で使用）
+  FAQ — question, answer（/faq で使用）
+
+ユーザーに確認 → 必要なものだけ選択
+```
+
+### 2-4. フォーム定義
+
+```
+site-map.json の type: "form" ページを確認
+
+提案例:
+  contact — name(text), email(email), message(textarea)
+
+ユーザーに確認
+```
+
+### 2-5. ルーティングマップ
+
+```
+移行元           →  CMX
+/                →  src/app/page.tsx（トップページ）
+/blog            →  src/app/blog/page.tsx（一覧）
+/blog/*          →  src/app/blog/[slug]/page.tsx（詳細）
+/news            →  src/app/news/page.tsx（一覧）
+/about           →  src/app/about/page.tsx（固定ページ）
+/contact         →  src/app/contact/page.tsx（フォーム）
+
+ユーザーに確認
+```
+
+### 2-6. 成果物
+
+**`cmx/migration/migration-plan.json`**
+
+```json
+{
+  "sourceUrl": "https://example.com",
+  "collections": [
+    {
+      "slug": "blog",
+      "name": "ブログ",
+      "type": "post",
+      "dataTypes": ["categories", "tags"],
+      "sourcePattern": "/blog/*",
+      "pageCount": 25
+    }
+  ],
+  "dataTypes": [
+    {
+      "slug": "staff",
+      "name": "スタッフ",
+      "fields": [
+        { "key": "name", "label": "名前", "type": "text", "required": true },
+        { "key": "position", "label": "役職", "type": "text" },
+        { "key": "photo", "label": "写真", "type": "image" }
+      ],
+      "source": "/about#team",
+      "entryCount": 5
+    }
+  ],
+  "components": [
+    {
+      "name": "FeatureCard",
+      "props": ["icon", "title", "description"],
+      "foundAt": ["/about", "/"]
+    }
+  ],
+  "forms": [
+    {
+      "slug": "contact",
+      "name": "お問い合わせ",
+      "fields": [
+        { "key": "name", "type": "text", "required": true },
+        { "key": "email", "type": "email", "required": true },
+        { "key": "message", "type": "textarea", "required": true }
+      ]
+    }
+  ],
+  "routes": [
+    { "source": "/", "target": "src/app/page.tsx", "type": "static" },
+    { "source": "/blog", "target": "src/app/blog/page.tsx", "type": "collection-list" },
+    { "source": "/blog/*", "target": "src/app/blog/[slug]/page.tsx", "type": "collection-detail" },
+    { "source": "/about", "target": "src/app/about/page.tsx", "type": "static" },
+    { "source": "/contact", "target": "src/app/contact/page.tsx", "type": "form" }
+  ],
+  "style": {
+    "colors": { "primary": "#2563eb", "text": "#1e293b", "background": "#ffffff" },
+    "fonts": { "heading": "Noto Sans JP", "body": "Noto Sans JP" },
+    "tone": "プロフェッショナル・クリーン"
+  }
+}
+```
+
+---
+
+## Step 3: 構築
+
+### 3-1. スキーマ登録（親エージェント）
+
+```bash
+# コレクション登録
+npx cmx-sdk create-collection --json '{"type":"post","slug":"blog","name":"ブログ","dataTypes":["categories","tags"]}'
+
+# グローバルデータタイプ登録
+npx cmx-sdk create-data-type --json '{"slug":"staff","name":"スタッフ","fields":[...]}'
+
+# 既存カテゴリ・タグのエントリ作成
+npx cmx-sdk create-data-entry --type-slug blog-categories --json '{"name":"技術"}'
+npx cmx-sdk create-data-entry --type-slug blog-tags --json '{"name":"Next.js"}'
+```
+
+### 3-2. コード生成（親エージェント）
+
+<!-- cmx-sync:start id="skill-cmx-migrate-codegen-block" -->
+```bash
+npx cmx-sdk codegen types
+npx cmx-sdk codegen pages --template layered
+```
+<!-- cmx-sync:end -->
+
+### 3-3. 設定ファイル生成（子エージェントに委譲）
+
+子エージェントに以下を渡す:
+- `migration-plan.json` の `style` セクション
+- site-analysis.md のスタイル情報
+- スクリーンショット
+
+子が `cmx/site-config.md` と `workflows/style-guide.md` を生成。
+
+### 3-4. コンポーネント作成（子エージェントに委譲）
+
+子エージェントに以下を渡す:
+- `migration-plan.json` の `components` セクション
+- cmx-component スキルの参照情報
+
+子が各コンポーネントの JSON定義 + TSX実装 + index.ts 更新を実施。
+
+### 3-5. 成果物
+
+**`cmx/migration/build-result.json`**
+
+```json
+{
+  "collections": [
+    { "slug": "blog", "id": "uuid", "dataTypes": ["blog-categories", "blog-tags"] }
+  ],
+  "dataTypes": [
+    { "slug": "staff", "id": "uuid" }
+  ],
+  "dataEntries": {
+    "blog-categories": [
+      { "name": "技術", "id": "uuid" },
+      { "name": "デザイン", "id": "uuid" }
+    ],
+    "blog-tags": [
+      { "name": "Next.js", "id": "uuid" }
+    ]
+  },
+  "components": ["FeatureCard", "FAQ"],
+  "generatedPages": ["src/app/blog/page.tsx", "src/app/blog/[slug]/page.tsx"]
+}
+```
+
+---
+
+## Step 4: コンテンツ投入
+
+### 4-1. バッチ分割（親エージェント）
+
+```
+crawl-result.json のページ一覧を読み込み
+migration-plan.json のコレクションマッピングで振り分け
+
+batch-001: blog の post-1 〜 post-10
+batch-002: blog の post-11 〜 post-20
+batch-003: news の news-1 〜 news-10
+```
+
+### 4-2. 子エージェントに委譲
+
+各バッチごとに子エージェントを起動（Task tool）。
+
+**子への指示テンプレート:**
+
+```
+以下の {n} 件のページをMDXに変換し、CMXに投入してください。
+
+コレクション: {collection_slug}
+変換ルール:
+- HTML→MDX変換テーブル（references/html-to-mdx.md の内容を簡潔に記載）
+- script, style, iframe は除去
+- 相対URLは絶対URLに変換
+- 画像は外部URLのまま維持
+
+使用コマンド:
+npx cmx-sdk create-content --collection {slug} --json '{"title":"...","slug":"...","description":"...","mdx":"..."}'
+
+ページデータ:
+{crawl-result.json から該当ページのデータを抜粋}
+
+結果を以下のJSON形式で返してください:
+{ "batch_id": "...", "results": [...], "summary": { "total": n, "success": n, "error": n } }
+```
+
+### 4-3. 参照設定（親エージェント）
+
+コンテンツ投入後、カテゴリ・タグの参照を設定:
+
+```bash
+npx cmx-sdk set-content-references --id {contentId} --json '{
+  "references": [
+    { "fieldSlug": "categories", "dataEntryIds": ["{categoryId}"] },
+    { "fieldSlug": "tags", "dataEntryIds": ["{tagId1}", "{tagId2}"] }
+  ]
+}'
+```
+
+### 4-4. 成果物
+
+**`cmx/migration/content-result.json`**
+
+```json
+{
+  "total": 40,
+  "success": 38,
+  "error": 2,
+  "collections": {
+    "blog": { "total": 25, "success": 24, "error": 1 },
+    "news": { "total": 15, "success": 14, "error": 1 }
+  },
+  "errors": [
+    { "url": "/blog/complex-table-post", "error": "テーブル変換エラー" },
+    { "url": "/news/special-format", "error": "特殊なHTML構造" }
+  ]
+}
+```
+
+---
+
+## Step 5: スタイル調整
+
+### 5-1. スクショ比較
+
+agent-browser で移行後のページのスクショを撮影し、Step 1 で取得した移行元のスクショと並べて比較。
+
+**子エージェントに委譲:**
+- 各ページのスクショ撮影
+- 移行元スクショとの差分ポイント列挙
+
+### 5-2. 差分報告
+
+```
+移行元 vs 移行後の主な差分:
+
+1. ヘッダーの背景色が異なる（元: #1a1a2e → 現: デフォルト白）
+2. フォントサイズが全体的に小さい
+3. カードのシャドウが効いていない
+4. フッターのレイアウトが2カラムだったが1カラムになっている
+```
+
+### 5-3. 調整実施
+
+ユーザーと確認しながら、cmx-style スキルを使ってTailwind CSSで調整。
+
+---
+
+## 中間ファイル一覧
+
+```
+cmx/migration/
+├── urls.json              ← Step 1: firecrawl map の結果
+├── crawl-result.json      ← Step 1: firecrawl crawl の結果
+├── site-analysis.md       ← Step 1: 人間向け解析レポート
+├── site-map.json          ← Step 1: 構造化データ
+├── screenshots/
+│   ├── original/          ← Step 1: 移行元スクリーンショット
+│   └── migrated/          ← Step 5: 移行後スクリーンショット
+├── structure/             ← Step 1: 構造化抽出結果
+│   └── {group}.json
+├── migration-plan.json    ← Step 2: 確定した移行計画
+├── build-result.json      ← Step 3: 構築結果（登録済みID）
+└── content-result.json    ← Step 4: 投入結果
+```
+
+これらのファイルはセッション間の引き継ぎに使用する。`.gitignore` に `cmx/migration/` を追加することを推奨（crawl-result.json が大きいため）。