# hatake

> 業務定義（YAML / JSON / 各言語 DSL）から、業務画面（Flutter）とバックエンドの API ロジック（Java / TypeScript：バリデーション・クエリ組み立て）を生成する宣言型フレームワーク。AI は実装（src/）を読まず、「定義の書き方」と「使える名前（ページ種別・フィールド型・フォーマッタ／コンバータ／バリデータ）」だけ知れば使える。全言語で同じ定義に収束し、フォーマッタ等の出力はコンフォーマンステストで3言語一致を担保している。

このファイルは LLM 向けの入口。まず「AI チートシート」を読めば、実装を読まずに定義を書ける。

## はじめに（これだけで書ける）
- [AI チートシート](https://github.com/ASIL-E-Hatake/hatake/raw/main/docs/api-cheatsheet.ja.md): ページ種別・フィールド型・フォーマッタ/コンバータ/バリデータの一覧＋オプション＋最小例
- [DSL リファレンス（機械可読）](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/reference.json): **全キーの索引**。ノードごとのキー・型・既定値・取れる値・どのページ種別で有効か＋`keyIndex`（キー名 → 書ける場所）。仕様書を読む代わりにここを引く。JSON Schema から生成しているので仕様とズレない
- [例のカタログ（機械可読）](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/examples/index.json): 「やりたいこと → 例」。近い例を1つ選んで直すのが一番速い（[人向けの表](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/examples/README.md)）
- [よくある間違い（機械可読）](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/pitfalls.json): 「間違い → なぜ駄目か → 正しい書き方」。書ける場所を間違える系（ページ直下に `columns`／`form` の直下に `fields`）と、**落ちないけど意図と違う**系（`groupBy` に `sort` が無い／`metric` が件数になる）。各項目は CI で検証済み（間違いは本当に落ち、正しい方は本当に通る）
- [DSL 仕様書](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/dsl-spec.ja.md): 定義の全仕様（読み物）
- [JSON Schema](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/hatake-page.schema.json): 定義の機械検証用（YAML に `# yaml-language-server: $schema=<この URL>` を書くと補完・検証が効く）

## MCP サーバ（対応クライアントならこれが一番速い）
Claude Code / Claude Desktop などに繋ぐと、**このファイルを読まなくても**必要なときに仕様を引ける。道具は `hatake_reference`（キーを引く）/ `hatake_examples`（近い例を取る）/ `hatake_validate`（検証）/ `hatake_new_page`（雛形）/ `hatake_pitfalls`（よくある間違い）/ `hatake_diff`（直した影響）/ `hatake_explain`（書いた定義を日本語で読み返す・変更を言い直す）/ `hatake_fix`（一意な直しだけ機械にやらせる）/ `hatake_minimize`（既定値と同じ指定を落として短く）/ `hatake_refs`（アプリ側に何を登録すればいいか）/ `hatake_api_shape`（API の形）。
- 入れ方: [MCP ガイド](https://github.com/ASIL-E-Hatake/hatake/raw/main/docs/guide/mcp.ja.md)（`claude mcp add hatake -- node <repo>/typescript/dist/mcp.js`）

## 書いた定義を検証する（CLI）
定義を書いたら、推測で終わらせずにこれで確認する。問題があれば終了コード 1。
```bash
npx hatake validate page.yaml     # strict（知らないキーを弾く）。--json で機械可読
npx hatake new <kind> --id <id> --title <title>   # 雛形（crud/search/master/detail/form/wizard/dashboard/report）
npx hatake reference <キー名>      # そのキーの型・既定値・書ける場所（--page-kind で絞る）
npx hatake examples <やりたいこと> # 近い例を引く
npx hatake pitfalls <キー名>       # よくある間違い → 正しい書き方
npx hatake failures <キー名>       # 実際に転んだ実例（なぜそう書くか付き）
npx hatake explain page.yaml       # この定義は何をする画面か（日本語で読み返す）
npx hatake explain page.yaml --brief        # 1行の要約（app なら画面一覧の表）
npx hatake explain --diff <前> <後>          # 何を変えたのか、画面の言葉で（人への報告用）
npx hatake explain --diff --git main...HEAD <file>  # 変更前は git から取る（PR の中身をそのまま）
npx hatake explain page.yaml --review       # レビュー用の1枚（説明＋助言。終了コードは変えない）
npx hatake explain page.yaml --markdown     # PR 本文に貼れる形（--review / --diff / --brief にも付く）
npx hatake fix page.yaml           # 綴り違いなど**一意な直し**だけ機械にやらせる（--write で上書き）
npx hatake advise page.yaml        # 書き足したほうがいい所（助言。警告ではない）
npx hatake advise page.yaml --rules team.json  # 案件ごとの決めごとで見る（規則を切る／目盛りを変える／必ず書くキーを足す）
npx hatake index definitions/ --find "顧客 検索"   # どこに何の画面があるか（--json で索引を丸ごと）
npx hatake diagram app.yaml --out app.svg  # 画面とメニューと遷移の図
npx hatake diagram app.yaml --role admin   # その役割で通れる道だけ（権限は入口から辿って数える）
npx hatake minimize page.yaml      # 既定値と同じ指定を落として短く（意味は変えない）
npx hatake diff <前> <後>          # 既にある定義を直したとき：契約・画面・権限・アプリ構成への影響
npx hatake fix page.yaml --todo    # 機械が直せなかった分だけを「次の1往復で渡す形」にする
npx hatake refs app.yaml --unused  # 逆向き：登録してあるのに、どの定義も使っていないもの
npx hatake paper report.yaml       # 帳票を「刷ったらどう見えるか」に開く（文字で・行が無くても見本を作る）
npx hatake refs page.yaml --needs-registration  # アプリ側に何を登録すればいいか（Repository / プラグイン名 / 出す口）
npx hatake wire app.yaml --base /api  # その配線（Flutter の HatakeScope）の下書き。中身は TODO で空ける
npx hatake registry lib/main.dart --out hatake-registry.json  # 実装を読んで「登録済み」の一覧を作る
```
`validate` は**解析は通るのに意図どおり動かない書き方**も警告する（宣言していない行アクション／存在しないページへの遷移／`sort` の無い `groupBy`／条件で使えない演算子／`field` の無い集計など）。エラーではないが**画面を見ても気づけない**類なので、警告が出たら直す。`--warn-as-error` で CI を落とせる。
未知キーは場所と直し方まで出る: `page.table.columns[0]: 知らないキー "witdh"（width の間違い？）`
**定義の外との食い違い**も見られる。`repository:` や `plugin:` の名前がアプリ側で登録されていなければ、画面は出るのにデータが来ない／押しても何も起きない。`refs` で「何を登録すればいいか」を出し、`registry` で「実装が何を登録しているか」を読み、`validate --registry <file>` で突き合わせると名前の食い違いを機械で拾える（定義の隣に `hatake-registry.json` を置けば `--registry` は省ける）。`registry` は**その場に書いてある文字列しか読めない**ので、読めない登録があれば終了コード 1 で報告する（黙って落とすと嘘の一覧になるため）。
**`validate` が見るのは綴りと構造だけ。** 条件の向きを間違えた・意図と違う項目を必須にした、は全部通る。書けたら `explain` で日本語に開いて読み返し、頼まれたことと違っていたら直す（キー名は出ないので、そのまま人にレビューさせてもよい）。実際に転んだ実例は `failures` に溜めてあり、**機械では拾えない件も載っている**（そこには「レビューでどこを見るか」が書いてある）。
`diff` は変更を3段で返す。`✗ 破壊的`＝呼び出し側が壊れる、`△ 要確認`＝壊れないが人に確かめてほしい（列・ボタン・選択肢が消えた／権限が変わった／ページ・メニューが消えた）、`・安全`＝増えただけ。**要確認は黙って進めず、意図した変更か確かめる**こと。
**既定値をわざわざ書かない。** `type: text` / `required: false` / `validators: []` のような指定は、書いても何も足していない。書いてしまったら `minimize` で落とせる（意味は変えない＝落とすたびに解析後のモデルが変わらないことを確かめている）。短い定義のほうが、人のレビューも次に読む AI のコンテキストも軽い。
**直した内容を人に報告するときは `explain --diff`。** `diff` が返すのは機械の言葉（`ui / column-format-changed / …`）だが、こちらは「枠「請求先」は、区分 が 法人 のときだけ出るようになりました」と画面の言葉で言う。判定（壊すか）は `diff`、言い直し（何が変わったか）は `explain --diff`。後者は終了コードを変えない。
**人にレビューさせる紙は1枚で出す。** `explain --review` は説明（できること・**できないこと**）と助言（書き足したほうがいい所）をまとめて出す。助言は好みなので、案件の決めごとがあるなら `--rules team.json` で物差しを差し替える（知らないキー・知らない規則名はエラー＝設定が黙って効かないことを作らない）。
**項目間の検証は `compare`。** 「開始日 ≤ 終了日」「合計＝明細の和」は1つの項目では書けないので、`validators` に `{ type: compare, operator: gte, field: startDate }` と書く（`operator` は equals/notEquals/gt/gte/lt/lte、既定 gte）。明細と比べるなら `aggregate: sum, of: amount`。比べ方は**数として読めれば数、読めなければ文字**（ISO の日付は文字の大小＝日付の前後）。**判定できないときは通す**（自分が空なら required の担当）。相手の項目名を間違えると黙って通るので、`validate` が警告で言う。
**権限は入口から辿るしかない。** ページに `roles` は書けない（書けるのはメニュー項目とボタン、列・項目・カード）ので、「この画面は誰に見えるか」はメニューとボタンの `roles` から辿って数える。`diagram` はそれを箱の中に書き、**誰でも開けて消す/持ち出せる画面**（赤枠）と**誰も開けない画面**（点線＝入口の権限が食い違っている）を色で分ける。どちらも1枚ずつ読んでも出てこない。
**データの口と URL は用意してある。** REST に繋ぐなら opt-in の `hatake_http`（`npx hatake openapi` が宣言する形と1対1。通信は持たないので送る関数だけ渡す。失敗は型で返る＝401/403・400 の項目別エラー・宣言と違う形）。`app:` を `HatakeApp` で描くと **Web では URL が画面に付く**（`/画面id?params`。リンク・リロード・戻るが効く。params は文字で戻る）。**アプリ側に何を登録すればいいか**は `npx hatake refs --needs-registration`（Repository・プラグイン・出す口）で引けて、`validate --registry` に渡すと繋いでいない口まで言う。
**紙は定義から出せる。** 帳票に `{ id: printPdf, type: print, label: 印刷 }` を置けば印刷ボタンが出る（`type: print` は帳票専用。`report` の無い画面に置くと警告）。Framework が渡すのは**紙の中身まで**（帳票の定義・いま画面に出ている行・役割・フォーマッタ）で、PDF のバイト列にするのは opt-in の `hatake_print`、それをプリンタやファイルに送るのはアプリ（`HatakeScope(printSink:)`）。刷る前に紙を読むなら `npx hatake paper`。
**画面の索引はどのエディションにもある。** CLI の `index` と同じものが Dart 版（`ScreenIndex.ofApp(app)` / `buildScreenIndex`）と Java 版（`ScreenIndex.build`）にもあるので、アプリの中から自分の画面を探せる。種別の見出し語は `spec/vocabulary.json` が正で、3つのエディションはそれを転記している。

## 用途別（1〜2ファイルだけ読めばいい）
- [ドキュメント目次](https://github.com/ASIL-E-Hatake/hatake/raw/main/docs/index.ja.md): 「やりたいこと → 読むファイル」の索引
- [導入](https://github.com/ASIL-E-Hatake/hatake/raw/main/docs/getting-started.ja.md): インストール〜最小コードで1画面出すまで（Repository の実装例つき）
- [レシピ: マスタメンテ](https://github.com/ASIL-E-Hatake/hatake/raw/main/docs/cookbook/master-maintenance.ja.md): 検索＋一覧＋CRUD の1画面
- [レシピ: 一覧→詳細](https://github.com/ASIL-E-Hatake/hatake/raw/main/docs/cookbook/search-list-detail.ja.md): `app:` でメニュー付きアプリ化・`navigate` で遷移
- [レシピ: 消費税/インボイス](https://github.com/ASIL-E-Hatake/hatake/raw/main/docs/cookbook/invoice-tax.ja.md): 税率別合計・端数処理
- [仕組みと責務分担](https://github.com/ASIL-E-Hatake/hatake/raw/main/docs/guide/concepts.ja.md): 利用者が書くのは定義とRepositoryだけ／正規化→検証→永続化の順／Frameworkが持たない領域
- [ページ種別の選び方](https://github.com/ASIL-E-Hatake/hatake/raw/main/docs/guide/page-types.ja.md): crud/master/search/detail/form/wizard/dashboard/report の判断表
- [入力検証](https://github.com/ASIL-E-Hatake/hatake/raw/main/docs/guide/validation.ja.md): 実行順・空値スキップ・独自ルール登録・メッセージi18n
- [バックエンド連携](https://github.com/ASIL-E-Hatake/hatake/raw/main/docs/guide/backend.ja.md): サーバ側バリデーション・QuerySpec・JPAアダプタ

## 例（そのまま真似られる・CI でスキーマ検証済み）
- [顧客マスタ / crud](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/examples/customer_master.yaml)
- [商品照会 / search](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/examples/product_search.yaml)
- [部門マスタ / master](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/examples/dept_master.yaml)
- [顧客詳細 / detail](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/examples/customer_detail.yaml)
- [顧客入力 / form](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/examples/customer_form.yaml)
- [顧客登録 / wizard（ステップ入力）](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/examples/customer_wizard.yaml)
- [受注入力 / 親子・明細（subTable）](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/examples/order_entry.yaml)
- [売上ダッシュボード / dashboard（metric・chart・table のカード）](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/examples/sales_dashboard.yaml)
- [売上明細表 / report（帳票。グループ・小計・CSV出力）](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/examples/sales_report.yaml)
- [販売管理アプリ / app（メニュー＋8ページ＋遷移）](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/examples/sales_app.yaml)

## English
英語で読ませたいときは [llms-en.txt](https://github.com/ASIL-E-Hatake/hatake/raw/main/llms-en.txt) と [AI cheat sheet](https://github.com/ASIL-E-Hatake/hatake/raw/main/docs/api-cheatsheet.md) を渡す（DSL 仕様は [dsl-spec.md](https://github.com/ASIL-E-Hatake/hatake/raw/main/spec/dsl-spec.md)）。リファレンス・例・落とし穴の機械可読ファイルは共通（落とし穴は ja/en 両方入っている）。

## 拡張・内部（必要なときだけ）
- [Plugin ガイド](https://github.com/ASIL-E-Hatake/hatake/raw/main/flutter/docs/plugins.ja.md): 独自フォーマッタ/バリデータ/フィールド型/Renderer の登録
- [開発ロードマップ](https://github.com/ASIL-E-Hatake/hatake/raw/main/docs/roadmap.ja.md): 対応状況と方針