@squadbase/vantage 0.0.1 → 0.1.1

package/docs/ja/agent-skills.md

@@ -0,0 +1,87 @@
+# エージェントと Skills
+
+> Vantage に同梱された Claude Code の Agent Skills。vantage add skill でアプリの .claude/skills/ に配置し、エージェントに手順を伴うワークフローを教える。
+
+Vantage は **Claude Code の Agent Skills** を同梱しています。Skill は「手順を伴うワークフロー」を、
+エージェントが必要なときだけ呼び出せる形にしたものです。UI キットや CLI の使い方といった
+静的な参照(このドキュメント)とは別に、**再現可能な段取り**をエージェントに渡すのが目的です。
+
+## 何が同梱されているか
+
+いずれも「Vantage **アプリを作るエージェント**」向けの手順です。
+
+| skill | 扱う手順 |
+|---|---|
+| `vantage-app` | アプリの新規作成と、`index.tsx` 単体の SPA から `server/api`・ネストレイアウト・動的ルート・404/error を備えた fullstack への拡張 |
+| `vantage-add-feature` | ページ / API / UI / ブロックの追加(`vantage add` + `check` / `routes` までの一連) |
+| `vantage-pitfalls` | 落とし穴リファレンス(Base UI ≠ Radix、`SelectValue` の挙動、クライアントから `server/` を import しない など) |
+
+## 配置する
+
+Skill のソースは `@squadbase/vantage` パッケージに同梱されています。`vantage add skill` で、
+対象アプリの `.claude/skills/` にコピーします。
+
+```bash
+vantage add skill --all          # 同梱スキルをすべて配置
+vantage add skill vantage-app    # 名前を指定して1つだけ配置
+vantage add skill vantage-app --force   # 既存を上書き
+```
+
+配置後のレイアウト:
+
+```text
+your-app/
+├── index.tsx
+├── package.json
+└── .claude/
+    └── skills/
+        ├── vantage-app/SKILL.md
+        ├── vantage-add-feature/SKILL.md
+        └── vantage-pitfalls/SKILL.md
+```
+
+`.claude/skills/` は Claude Code が自動で認識します。エージェントはタスクに応じて、対応する
+Skill の手順を読み込んで実行します。
+
+> [!NOTE]
+> `.claude/` はツール用の設定であり、アプリのコードではありません。`vantage check` の静的診断は
+> このディレクトリを走査しないため、置いてもビルドや検査には影響しません。
+
+## 配布と更新の方針
+
+- **source-of-truth はパッケージ内**にあります。Skill はフレームワークのバージョンと一緒に
+  配布・更新されるため、`@squadbase/vantage` を上げれば最新の手順が手に入ります。配置済みの
+  コピーを更新したいときは `vantage add skill --all --force` を実行します。
+- **Squadbase テンプレートには配置済み**です。テンプレートから作ったアプリには、最初から
+  `.claude/skills/` が入っています。手で作ったアプリには `vantage add skill` で足してください。
+
+## `AGENTS.md`(アプリの地図)
+
+Skill が「手順書」なら、`AGENTS.md` は**エージェントが最初に読む「地図」**です。Vantage の
+不変条件・import サブパスの地図・ルーティング規約・データ取得/API/env の最小レシピを 1 ページに
+まとめてあり、**それだけ読んで最小アプリを組める**ことを狙っています。手順の深掘りは上の Skill へ
+名前で誘導し、内容は重複させません。
+
+Skill と同じく **source-of-truth はパッケージ内**にあり、`vantage add agents` でアプリルートへ
+配置します。
+
+```bash
+vantage add agents           # AGENTS.md をアプリルートに配置
+vantage add agents --force    # 既存を上書き
+```
+
+配置済みの `AGENTS.md` は `vantage upgrade` で正本と同期されます(差分があるときだけ書き換え、
+まだ配置していないアプリには作りません)。フレームワークの規約が変わっても、**正本 1 箇所の更新**が
+`upgrade` でアプリへ反映されます。Squadbase テンプレートには最初から配置済みです。
+
+## 責務の切り分け
+
+Skill は「**手順を伴うワークフロー**」だけを担います。次のものとは役割を分け、内容を重複させません。
+
+- **このドキュメント**(仕様・リファレンス)― 何がどう動くかの静的な説明。ブラウザを開けない
+  エージェントには、同じ内容が [`vantage docs`](cli-reference) でそのまま読めます
+  (`vantage docs button` で props の表、`vantage docs --json` で機械可読。名前が
+  分からなければ `vantage search <やりたいこと>`)。
+- **`AGENTS.md`**(静的な地図)― 構成やファイルの居場所。`vantage add agents` で配置します。
+- Skill 同士 ― 落とし穴などの共通内容は各 Skill に写経せず、**名前で相互参照**します
+  (例: `vantage-app` の手順中から `vantage-pitfalls` を指す)。

package/docs/ja/api-and-server.md

@@ -0,0 +1,84 @@
+# API とサーバー
+
+> server/ を足すと API が有効になる。ApiContext・HttpError・HTTP メソッドの規約。
+
+Vantage の**サーバーはオプション**です。プロジェクトに `server/` ディレクトリを追加すると
+API が有効になり、ビルドは `fullstack` モードに切り替わります。無ければアプリはクライアントのみ
+（SPA）で、`/api/*` は単なるクライアントルートとして扱われます（本番と一致）。
+
+## API ルートの規約
+
+API は `server/api/**` から、ページと同じファイル名規約で導出されます。
+
+| ファイル | エンドポイント |
+|---|---|
+| `server/api/customers.ts` | `/api/customers` |
+| `server/api/customers/[id].ts` | `/api/customers/:id` |
+| `server/api/monthly-analysis.ts` | `/api/monthly-analysis` |
+
+各ファイルは HTTP メソッド名の関数をエクスポートします。使えるメソッドは
+`GET` / `POST` / `PUT` / `PATCH` / `DELETE` / `OPTIONS`。
+
+```ts
+// server/api/customers/[id].ts  →  /api/customers/:id
+import type { ApiContext } from "@squadbase/vantage/server";
+import { HttpError } from "@squadbase/vantage/server";
+
+export async function GET({ params, env }: ApiContext) {
+  const customer = await findCustomer(params.id!);
+  if (!customer) throw new HttpError(404, "Customer not found");
+  return Response.json(customer);
+}
+```
+
+> [!NOTE]
+> 有効な HTTP メソッドを 1 つもエクスポートしていない API ファイルは、`vantage check` が
+> `INVALID_API_EXPORT` エラーで指摘します（小文字で書いた場合はヒントを出します）。
+
+## ApiContext
+
+ハンドラは Web 標準の型で話します。引数の `ApiContext` は次を持ちます。
+
+| プロパティ | 内容 |
+|---|---|
+| `request` | 標準の `Request` |
+| `params` | 動的パラメータ（`params.id` など） |
+| `env` | サーバー側の環境変数・シークレット |
+| `waitUntil` | レスポンス後のバックグラウンド処理（撃ちっぱなし） |
+
+戻り値は標準の `Response`。`Response.json(...)` か、ヘルパーの `json()` を使えます。
+
+```ts
+import { json } from "@squadbase/vantage/server";
+
+export async function GET() {
+  return json({ ok: true });
+}
+```
+
+## エラーの扱い
+
+クライアントに見せたいエラーは `HttpError(status, message)` を throw します。これはステータスと
+メッセージがそのままクライアントへ届きます。
+
+```ts
+if (!authorized) throw new HttpError(403, "Forbidden");
+```
+
+それ以外の throw されたエラーはサーバーにログされ、クライアントには**汎用の 500** として
+返されます（内部情報は漏れません）。
+
+## dev と prod は同一に振る舞う
+
+リクエストのディスパッチ（ルートのマッチ・405 処理・request-id 付与）は dev と prod で
+**共有された 1 つのコア**を通ります。開発時に見えた挙動が、本番でもそのまま再現されます。
+
+## シークレットはサーバーだけ
+
+`ApiContext.env` はサーバー側でのみ読めます。**クライアントには決して届きません**。API キーや
+DB 接続情報などはここから読みます。クライアントに露出させたい値の扱いは
+[環境変数](environment-variables)を参照してください。
+
+## 次に読む
+
+- [環境変数](environment-variables) — シークレットと公開値の境界

package/docs/ja/build-and-deploy.md

@@ -0,0 +1,279 @@
+# ビルドとデプロイ
+
+> dist/ の中身と vantage-manifest.json。同一オリジン配信と、フロント/サーバーを別オリジンに分けるデプロイ(S3+CloudFront ⇄ Lambda など)。
+
+`vantage build` は本番用の成果物を `dist/` に出力します。ここから先の配信方法は 2 つに大別できます。
+サーバーとフロントを**同一オリジン**でまとめて出すか、フロントを静的ホスティング(S3+CloudFront /
+Cloudflare Pages)に、サーバーを別オリジン(Lambda / コンテナ)に**分けて**出すかです。分離構成の
+ために Vantage は「API ベースURLの切り替え」と「CORS」を用意しています。
+
+## ビルド出力
+
+```bash
+vantage build   # → dist/
+```
+
+```text
+dist/
+├── client/                クライアント(index.html + ハッシュ付きアセット、ルートごとに分割)
+├── server/index.mjs       server/ がある場合のみ(esbuild / node20 / ESM バンドル)
+└── vantage-manifest.json  デプロイ契約
+```
+
+`vantage-manifest.json` が配信側との唯一の契約です。フィールドは次の通り。
+
+| フィールド | 内容 |
+|---|---|
+| `schemaVersion` | マニフェストのスキーマ版(現在 `1`) |
+| `mode` | `"spa"`(client のみ)/ `"fullstack"`(server あり)。`server/` の有無から導出 |
+| `client` | クライアント成果物への相対パス(`"./client"`) |
+| `server` | サーバーバンドルへの相対パス(`"./server/index.mjs"`)。fullstack のみ |
+| `spaFallback` | SPA フォールバック用 HTML(`"./client/index.html"`) |
+| `runtime` | サーバーの実行環境(`"node"`) |
+
+> [!NOTE]
+> `mode` は `server/` ディレクトリの有無で自動的に決まります。`server/` が無ければ `spa`(クライアント
+> のみ)、あれば `fullstack`。`vantage check` や `vantage routes` でも同じ判定が使われます。
+
+## preview でローカル確認
+
+デプロイ前に、本番ビルドをローカルで動かして確認します。
+
+```bash
+vantage preview
+```
+
+`vantage preview` は `vantage-manifest.json` の `mode` を読み、`fullstack` なら Node サーバーを
+起動(既定 `:4173`)、`spa` なら静的プレビューを立ち上げます。
+
+## デプロイの 2 つの形
+
+### 同一オリジンにまとめる
+
+Node プロセス 1 つで client と `/api` の両方を配信。設定が最小で、CORS も不要。
+
+### フロントとサーバーを分ける
+
+フロントを S3+CloudFront 等へ、サーバーを Lambda / コンテナへ。API ベースURLの切り替えと
+CORS が必要。
+
+## 同一オリジンにまとめてデプロイ
+
+最も単純な形です。`dist/` をまるごと Node が動く環境(コンテナ / VM)に置き、生成された
+サーバーを起動します。同一プロセスが静的アセットと `/api/*` の両方を捌くため、API ベースURLの
+切り替えも CORS も不要です。
+
+```bash
+# dist/ を配置したサーバー上で
+PORT=8080 node dist/server/index.mjs
+```
+
+サーバーはポート `PORT`(未指定なら `3000`)で待ち受けます。クライアントは相対パス
+`/api/...` をそのまま同一オリジンで呼びます。
+
+> [!NOTE]
+> `spa` モード(`server/` なし)には起動するサーバーがありません。`dist/client/` を任意の静的
+> ホスティングに置き、未知パスを `index.html` にフォールバックさせれば完了です(下の SPA
+> フォールバック設定を参照)。
+
+## フロントとサーバーを分ける(S3+CloudFront ⇄ Lambda)
+
+フロントを CDN の静的ホスティングに、サーバーを別オリジンに置く構成です。よくある組み合わせは
+「`dist/client` を S3+CloudFront、`dist/server/index.mjs` を Lambda / コンテナ」です。別オリジンに
+なるため、次の 2 点が必要になります。
+
+### 1. API ベースURLを切り替える
+
+クライアントの API 呼び出しは、`@squadbase/vantage/query` の `apiFetch` / `apiUrl` を通します。
+これが `/api` を呼ぶ唯一の継ぎ目で、ベースURLをここで差し替えられます。
+
+```tsx
+import { apiFetch, useQuery } from "@squadbase/vantage/query";
+
+useQuery({
+  queryKey: ["monthly-analysis"],
+  // パスは server/api の綴りのまま(/api を含める)
+  queryFn: () => apiFetch("/api/monthly-analysis").then((r) => r.json()),
+});
+```
+
+ベースURLは `PUBLIC_API_BASE_URL` から読みます。**未設定なら空**で、従来どおり同一オリジンの
+相対パス(`/api/monthly-analysis`)になります。設定すると、その値が前置されます
+(`https://api.example.com/api/monthly-analysis`)。切り替え方法は 2 つ。
+
+**(a) 環境変数で上書き** — `.env` や CI の環境変数に置きます。`PUBLIC_` 接頭辞なので、
+そのままクライアントバンドルに焼き込まれます。
+
+```bash
+# .env（またはCIの環境変数）
+PUBLIC_API_BASE_URL=https://api.example.com
+```
+
+**(b) ビルド時にフラグで指定** — `vantage build` に `--api-base-url` を渡します。
+
+```bash
+vantage build --api-base-url https://api.example.com
+```
+
+> [!NOTE]
+> `--api-base-url` は `.env` の `PUBLIC_API_BASE_URL` より**優先**されます。CI で基本値を `.env` に
+> 置きつつ、環境ごとにフラグで上書きする、といった使い分けができます。
+
+> [!TIP]
+> `apiUrl("/api/...")` に渡すパスは、`server/api/**` の綴りのまま **`/api` を含めて**ください。
+> ベースURLは「オリジン(またはその手前まで)」を表し、パスがそのまま連結されます。
+
+### 2. CORS を許可する
+
+フロントとサーバーが別オリジンになると、ブラウザは CORS を要求します。サーバー側で
+`CORS_ORIGIN` を設定すると、`/api` に CORS(プリフライトの `OPTIONS` 応答を含む)が付きます。
+**未設定なら CORS は無効**で、同一オリジン運用はそのままです。
+
+```bash
+# サーバー(Lambda / コンテナ)の環境変数
+CORS_ORIGIN=https://app.example.com          # 単一オリジン
+# CORS_ORIGIN=https://a.example.com,https://b.example.com   # カンマ区切りで複数
+# CORS_ORIGIN=*                              # すべて許可（credentials とは併用不可）
+CORS_CREDENTIALS=true                        # Cookie / 認証情報を許可する場合のみ
+```
+
+| 変数 | 役割 |
+|---|---|
+| `CORS_ORIGIN` | 許可するオリジン。`*` / 単一 / カンマ区切りの複数。未設定なら CORS 無効 |
+| `CORS_CREDENTIALS` | `true` のとき資格情報(Cookie 等)を許可。`*` とは併用しない |
+
+許可メソッドは Vantage の API が使える `GET,POST,PUT,PATCH,DELETE,OPTIONS` が自動で設定されます。
+この挙動は dev サーバーと本番 Node サーバーで**共通**なので、開発中に CORS を確認できます。
+
+### 3. フロントを静的ホスティングに置く
+
+`dist/client/` を S3(+ CloudFront)や Cloudflare Pages にアップロードします。SPA なので、
+未知パスは `spaFallback`(`index.html`)に返す必要があります。
+
+- **S3 + CloudFront**: CloudFront の「カスタムエラーレスポンス」で `403` / `404` を
+  `/index.html`(ステータス `200`)に書き換えます。
+- **S3 静的ウェブサイトホスティング**: エラードキュメントを `index.html` にします。
+- **Cloudflare Pages**: SPA フォールバックが既定で有効です。
+
+### 4. サーバーを Lambda / コンテナに置く
+
+`dist/server/index.mjs` は `PORT` で待ち受ける Node の HTTP サーバーです(マニフェストの
+`runtime` は `"node"`)。Node プロセスが動く環境にそのまま置けます。
+
+- **コンテナ(Cloud Run / ECS·Fargate / Render / Fly など)**: `node dist/server/index.mjs` を
+  起動コマンドにし、`PORT` を渡します。
+- **AWS Lambda**: 待ち受け型の Node サーバーなので、コンテナイメージ + AWS Lambda Web Adapter
+  など「HTTP サーバーをそのまま Lambda で動かす」方式が相性の良い選択です。
+- シークレット(DB 接続情報や API キー)は**サーバー側の環境変数**として渡します。これらは
+  `ApiContext.env` からのみ読め、クライアントには決して届きません。
+
+> [!WARNING]
+> 本番の Node サーバーは**起動時に一度だけ** `process.env` をスナップショットします(dev はリクエスト
+> ごとに読み直します)。デプロイ後に環境変数を変えたら、サーバーを再起動してください。
+
+## AWS Lambda へデプロイする(具体例)
+
+生成される `dist/server/index.mjs` は `PORT` で**待ち受ける** Node の HTTP サーバーです。一方
+Lambda は「イベントでハンドラを呼ぶ」モデルなので、待ち受け型のサーバーをそのまま動かすには
+[AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter)(LWA)を挟むのが
+素直です。LWA が Function URL / API Gateway のイベントを、ローカルで動く HTTP サーバーへ
+プロキシします。Vantage 側のコード変更は不要です。
+
+### 1. コンテナイメージで動かす(推奨)
+
+esbuild が `dist/server/index.mjs` に**単一ファイルとしてバンドル**するため、`node_modules` を
+持ち込む必要はありません。
+
+```dockerfile
+# Dockerfile
+FROM public.ecr.aws/docker/library/node:20-slim
+
+# Lambda Web Adapter を拡張として同梱(バージョンは適宜更新)
+COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.9.1 /lambda-adapter /opt/extensions/lambda-adapter
+
+WORKDIR /var/task
+# dist/ ごとコピー(server は ../client を参照するためレイアウトを保つ)
+COPY dist ./dist
+
+# LWA と Node サーバーの待受ポートを一致させる(LWA の既定は 8080)
+ENV PORT=8080
+CMD ["node", "dist/server/index.mjs"]
+```
+
+```bash
+vantage build                                   # dist/ を生成
+docker build -t vantage-api .
+
+# ECR にログインして push(<acct> / <region> は自分の値に)
+aws ecr get-login-password --region ap-northeast-1 \
+  | docker login --username AWS --password-stdin <acct>.dkr.ecr.ap-northeast-1.amazonaws.com
+docker tag vantage-api <acct>.dkr.ecr.ap-northeast-1.amazonaws.com/vantage-api:latest
+docker push <acct>.dkr.ecr.ap-northeast-1.amazonaws.com/vantage-api:latest
+```
+
+この image で Lambda 関数を作成し、**Function URL** を有効にすると HTTPS エンドポイントが
+得られます。これを CloudFront の `/api/*` オリジンにするか、フロントの `PUBLIC_API_BASE_URL` に
+直接指定します。
+
+> [!TIP]
+> **zip で動かす場合**
+> コンテナを使わず zip でも動かせます。バンドル済みなので `dist/server/index.mjs`(必要なら
+> `dist/client` も)を zip し、LWA を **Lambda レイヤー**として付与、環境変数
+> `AWS_LAMBDA_EXEC_WRAPPER=/opt/bootstrap` と `PORT=8080` を設定、ランタイムは Node.js 20.x に
+> します。
+
+### 2. Lambda の環境変数を設定する
+
+サーバー設定とシークレットは Lambda の環境変数として渡します(クライアントには届きません)。
+
+| 変数 | 例 | 用途 |
+|---|---|---|
+| `CORS_ORIGIN` | `https://d111111abcdef8.cloudfront.net` | フロントのオリジンを許可 |
+| `CORS_CREDENTIALS` | `true` | Cookie / 認証情報を使う場合のみ |
+| `SECRET_*` など | `sk_live_xxx` | `ApiContext.env` から読むシークレット |
+
+`PORT` は Dockerfile で設定済みです(LWA の既定 8080 に合わせています)。
+
+> [!NOTE]
+> Function URL 自体にも CORS 設定がありますが、アプリ側(`CORS_ORIGIN`)と**二重に設定すると
+> 競合**します。Vantage の `CORS_ORIGIN` に一本化し、Function URL 側の CORS は空にしておくのが
+> 分かりやすい構成です。
+
+### 3. フロントから Lambda を指す
+
+フロントのビルド時に、Lambda(または前段の CloudFront)のオリジンを `PUBLIC_API_BASE_URL` に
+指定します。
+
+```bash
+vantage build --api-base-url https://d111111abcdef8.cloudfront.net
+```
+
+`apiUrl("/api/monthly-analysis")` はこのオリジンに `/api/monthly-analysis` を連結して呼びます。
+
+> [!WARNING]
+> Lambda はコールドスタート時にプロセスを起動し、そのとき `process.env` を読み込みます。環境変数を
+> 変更したら、新しいバージョンをデプロイして反映させてください(実行中の環境には遡って効きません)。
+
+## 本番の環境変数のまとめ
+
+境界は接頭辞で決まります([環境変数](environment-variables)も参照)。
+
+| 種類 | どこで設定 | いつ効く | 例 |
+|---|---|---|---|
+| クライアント公開値 | ビルド時(`.env` / `--api-base-url`) | ビルドに焼き込み | `PUBLIC_API_BASE_URL` |
+| サーバー設定 | サーバーの環境変数 | 起動時に読む | `PORT`, `CORS_ORIGIN`, `CORS_CREDENTIALS` |
+| シークレット | サーバーの環境変数 | 起動時に読む(`ApiContext.env`) | `SECRET_API_KEY` など |
+
+## デプロイ前チェックリスト
+
+- [ ] `vantage check` がエラーなしで通る
+- [ ] `vantage build`(分離構成なら `--api-base-url` 付き、または `.env` に `PUBLIC_API_BASE_URL`)
+- [ ] `vantage preview` でローカル動作を確認
+- [ ] 分離構成なら、サーバー側に `CORS_ORIGIN`(フロントのオリジン)を設定
+- [ ] 静的ホスティング側で SPA フォールバック(未知パス → `index.html`)を設定
+- [ ] シークレットはサーバーの環境変数にのみ置く(クライアントに出さない)
+
+## 次に読む
+
+- [CLI リファレンス](cli-reference) — `build` のフラグを含む全コマンド
+- [環境変数](environment-variables) — 公開値とシークレットの境界