@squadbase/vantage-template 0.0.2 → 0.1.0-dev.47d956c

package/README.md

@@ -56,6 +56,8 @@ npx @squadbase/vantage-template add funnel --force      # Overwrite existing fil
 
 Switch the chart color preset. Rewrites a marked block of `--chart-1`–`--chart-5` inside the project's `styles.css` (under `src/` when that layout is in use), leaving any other overrides in that file intact. Re-running replaces the block rather than stacking.
 
+A new project starts on the `blue` preset — the base template ships that block already written, so `init` and the gallery previews show the same colors. This command swaps it for another preset.
+
 ```bash
 npx @squadbase/vantage-template chart ocean
 npx @squadbase/vantage-template chart forest --dry-run

package/base-template/.squadbase/skills/adamas-automation/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: adamas-automation
+description: automation(データパイプライン)の作り方。automation/<name>/ のファイル配置、automation.yml v1 の書き方(GitHub Actions サブセット)、adamas @task / outputs / partition の宣言 API、実行と検証の流れ(lintAutomations → runAutomation dryRun → 本実行)。外部データを定期的に取り込んで Squadbase DB に同期するパイプラインを作る・直すときに参照する。
+---
+
+# Automation(adamas データパイプライン)
+
+外部データを定期取得して project の Squadbase DB へ同期するパイプライン。定義の正本は
+この repo の `automation/` ディレクトリで、コミットすると platform に自動同期される。
+ダッシュボード(`src/`)とは独立していて、互いのファイルには触れない。
+
+## ファイル配置
+
+```
+automation/
+├── pyproject.toml       # 共有 Python 環境(全 automation で 1 つ)。依存は `uv add`
+├── uv.lock
+└── <name>/              # automation 名 = ディレクトリ名 = ^[a-z0-9][a-z0-9_-]{0,63}$
+    ├── automation.yml   # 宣言(トリガ・ステップ)。1 automation = 1 ファイル
+    └── tasks.py         # adamas @task の実装(pipeline step が暗黙に読む。ファイル名固定)
+```
+
+- 初回だけ `automation/pyproject.toml` を作り `uv add adamas` する(全 automation で共有。
+  automation ごとに venv を作らない)
+- `automation/` が無いディレクトリ構成でも、上の形で新規作成すればよい
+
+## automation.yml v1 — GitHub Actions のサブセット
+
+GHA ワークフロー YAML の意味論をそのまま使う。**GHA との差分は次の 7 点だけ**。
+それ以外の書き方(`on:` / `steps:` / `- id:` / `if:` / `${{ }}` / `steps.<id>.outputs.<name>`)
+は GHA の知識どおりに書く:
+
+| # | 差分 |
+|---|---|
+| 1 | step は `uses:`/`run:` でなく型付きキー 1 個(`pipeline` / `agent` / `query` / `write` / `notify`)。v1 で実行できるのは `pipeline` のみ(他は宣言だけで UI に載る) |
+| 2 | `on.schedule` は単一オブジェクトで `timezone` / `enabled` を持つ(cron 配列は不可) |
+| 3 | 手動トリガは `on.manual`(GHA の `workflow_dispatch` の改名) |
+| 4 | inputs の `type` は `string | boolean | daterange` の 3 種 |
+| 5 | 式 `${{ }}` は dot 参照のみ(関数・演算子・パイプは不可)。context は `trigger.inputs.<name>` と `steps.<id>.outputs.<name>` だけ。前方・自己参照は不可 |
+| 6 | pipeline step のタスク実体は同ディレクトリ `tasks.py` 固定(automation 1 個につき pipeline step は最大 1) |
+| 7 | pipeline step に `destination`(取り込み先 Squadbase DB の connection uuid)を書ける。省略時は project 唯一の Squadbase DB が既定 |
+
+例(実行可能な最小形):
+
+```yaml
+version: 1
+name: Daily ad spend sync
+on:
+  schedule: { cron: "0 6 * * *", timezone: Asia/Tokyo }
+  manual:
+    inputs:
+      backfill: { type: daterange, required: false }
+steps:
+  - id: sync
+    pipeline:
+      backfill: ${{ trigger.inputs.backfill }}
+      connections:                 # ctx.connection(name) で使う接続の配線(任意)
+        warehouse: <connection-uuid>
+```
+
+- スケジュールは年 2 回以上の頻度が必要(それ未満は同期時に拒否される)
+- `agent` / `query` / `write` / `notify` step を含む automation はスケジュール実行できない
+  (宣言と UI 表示のみ)
+
+## tasks.py — adamas の宣言 API
+
+```python
+from adamas import task, output, by_date, source
+
+@task(
+    name="ad-spend",                       # 出力データセット名(省略時は関数名)
+    table="ad_spend",                      # Squadbase DB のテーブル名
+    pk=["date", "campaign_id"],            # upsert / ignore では必須
+    mode="upsert",                         # append | ignore(先勝ち) | upsert(後勝ち)
+    schema={"date": "string", "campaign_id": "string", "cost": "float64"},
+    partition=by_date("2026-01-01"),       # 1 日 1 パーティション(付けると増分実行になる)
+    inputs=[source.connection("warehouse")],
+)
+def ad_spend(ctx):
+    date = ctx.partition.inputs["date"]    # 自分のスライスは ctx.partition.inputs から読む
+    conn = ctx.connection("warehouse")     # automation.yml の connections で配線した接続
+    yield from conn.query(
+        f"SELECT ... WHERE date = '{date}'", chunk_rows=10_000
+    )
+```
+
+押さえること:
+
+- 戻り値は pandas/polars DataFrame・pyarrow Table、またはそれらの yield(チャンクで
+  メモリ有界にする)。複数出力は `outputs={...}` + `yield ("<dataset>", chunk)`
+- `schema` は Parquet 型を固定する列型宣言。**schema の無い出力は Squadbase DB へ
+  取り込まれない**ので必ず書く。pk 列は schema に含める
+- partition プランは `by_date(start)`(日次)か `by_list(keys)`(キー列挙)。
+  partition 付きタスクは単一出力
+- 1 テーブル 1 書き手(別タスクが同じテーブルを書くとエラー)
+- 抽出・再試行・冪等性(どこまで取ったか)は adamas と台帳が管理する。自前で
+  チェックポイントや重複排除を実装しない
+
+## 検証と実行の流れ
+
+1. ファイルを作成・編集したら **`lintAutomations`** で検証し、指摘を直す
+2. **`runAutomation` を `dryRun: true` で実行**(オフライン: ローカル一時ディレクトリに
+   書き、platform の台帳・ストレージには何も書かない)。まず 1 パーティションだけ
+   `partitions: ["2026-01-01"]` のように絞ると速い
+3. コミットすると宣言が platform に自動同期され、スケジュールが有効になる
+4. 本実行(`dryRun` なし)はユーザーがデータを求めたときだけ。結果の `adamasStatus` に
+   タスクごとの done / failed / outstanding と失敗の内訳(error / category)が載るので、
+   それを根拠に報告・修正する
+5. 失敗を直したら `retryFailed: true` で失敗パーティションだけ再実行。過去範囲の
+   取り直しは `backfill: "START:END"`(両端含む)
+
+## 落とし穴
+
+- automation 名にハイフンは使えるが、Python module 名には使わない(module は常に
+  `tasks.py` 固定なので気にしなくてよい)
+- `${{ }}` に式や関数を書かない(`| length > 0` などの Jinja 方言は不可)
+- cron は 5 フィールド・64 文字以内
+- `automation.yml` に未知のキーを書くと lint エラー(黙って無視されない)

package/base-template/.squadbase/skills/project-storage/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: project-storage
+description: Squadbase の Project Storage(アップロード済みファイル)を @squadbase/react の useStorage() でブラウザから扱う手順。ファイル一覧、画像 / 動画 / PDF の埋め込み、中身の読み取り、アップロードと削除・移動。ページやコンポーネントがアップロード済みファイルを表示・埋め込み・アップロードするときに参照する。
+---
+
+# Project Storage(ブラウザ側)
+
+Squadbase の **Project Storage** を React コンポーネントから読み書きする手順。Squadbase 上で
+動くアプリでは資格情報も設定も要らず、そのまま動く。サーバー(`server/api/**`)からストレージを
+触る API は別物で、ここでは扱わない。
+
+## import は `@squadbase/react` から直接
+
+「import は `@squadbase/vantage` のサブパス経由」はフレームワークが所有するものの話。
+**`@squadbase/react` は Squadbase プラットフォームの SDK なので直接 import する**
+(`SquadbaseProvider` / `useUser` と同じ)。
+
+```tsx
+import { useStorage } from "@squadbase/react"
+
+const storage = useStorage()
+// 呼び出しはすべて storage.uploads.* の下
+```
+
+`useStorage()` が返すクライアントは安定なので、コンポーネント先頭で呼んで `useQuery` /
+`useMutation` の中で使ってよい。データ取得のフックは `@squadbase/vantage/query` から取る
+(`@tanstack/*` は直接 import しない)。
+
+## API
+
+すべて async。`key` はストレージ内の**相対**パス(例: `reports/2025-q1.pdf`)で、先頭に
+スラッシュを付けない。
+
+読み取り:
+
+- `list(prefix?, options?)` → `{ objects, commonPrefixes, nextCursor? }`。`objects` は
+  `{ key, size, lastModified }[]`。`options.delimiter = "/"` でフォルダ表示(サブフォルダが
+  `commonPrefixes` に入る)、省略すると再帰的なフラット一覧。`options.limit` / `options.cursor`
+  でページング(`cursor` は前回の `nextCursor`)
+- `head(key)` → `{ key, size, contentType, createdAt }`。メタ情報だけで本体は取らない
+- `getUrl(key)` → `{ url, expiresAt }`。埋め込み用の一時 URL
+- `get(key)` → 生の `Response`。`.json()` / `.text()` / `.blob()` / `.arrayBuffer()` で読む
+
+書き込み:
+
+- `put(key, data, options?)` → `void`。`data` は `Blob`(`File` を含む) / `ArrayBuffer` /
+  `Uint8Array` / `string`
+- `delete(key)` → `void`
+- `copy(srcKey, destKey, options?)` / `move(srcKey, destKey, options?)` → `void`
+
+## 一覧を出す
+
+```tsx
+import { useStorage } from "@squadbase/react"
+import { useQuery } from "@squadbase/vantage/query"
+
+const storage = useStorage()
+const { data, isPending, isError } = useQuery({
+  queryKey: ["storage", "list", prefix],
+  queryFn: () => storage.uploads.list(prefix, { delimiter: "/" }),
+})
+```
+
+`data.commonPrefixes` をフォルダ、`data.objects` をファイルとして描く。プレフィックス配下を
+まとめて出すなら `delimiter` を省く。
+
+## 画像 / 動画 / PDF を埋め込む
+
+埋め込みには URL が要るので `getUrl` を使う。**URL には期限がある**ので、切れる前に取り直す:
+
+```tsx
+import { useStorage } from "@squadbase/react"
+import { useQuery } from "@squadbase/vantage/query"
+
+function useStorageUrl(key: string) {
+  const storage = useStorage()
+  return useQuery({
+    queryKey: ["storage", "url", key],
+    queryFn: () => storage.uploads.getUrl(key),
+    refetchInterval: (query) => {
+      const expiresAt = query.state.data?.expiresAt
+      if (!expiresAt) return false
+      // 期限の 60 秒前に取り直す
+      return Math.max(0, new Date(expiresAt).getTime() - Date.now() - 60_000)
+    },
+  })
+}
+```
+
+```tsx
+import { ErrorState, Loading } from "@squadbase/vantage/ui"
+
+const { data, isPending, isError } = useStorageUrl("reports/cover.png")
+if (isPending) return <Loading />
+if (isError) return <ErrorState message="ファイルを読み込めませんでした" />
+return <img src={data.url} alt="" className="w-full rounded-lg" />
+```
+
+動画は `<video src={data.url} controls className="w-full rounded-lg" />`、PDF は
+`<iframe src={data.url} className="h-[80vh] w-full rounded-lg border border-border" />`。
+
+## 中身を JS で読む
+
+```tsx
+const { data } = useQuery({
+  queryKey: ["storage", "content", key],
+  queryFn: async () => {
+    const res = await storage.uploads.get(key)
+    return (await res.json()) as Row[] // または res.text()
+  },
+})
+```
+
+## アップロードする
+
+```tsx
+import { useStorage } from "@squadbase/react"
+import { useMutation, useQueryClient } from "@squadbase/vantage/query"
+
+const storage = useStorage()
+const queryClient = useQueryClient()
+const upload = useMutation({
+  mutationFn: (file: File) =>
+    storage.uploads.put(`uploads/${file.name}`, file, { contentType: file.type }),
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ["storage", "list"] }),
+})
+
+<input
+  type="file"
+  onChange={(e) => {
+    const file = e.target.files?.[0]
+    if (file) upload.mutate(file)
+  }}
+/>
+```
+
+`File` はそのまま `put` に渡す。書き込み後は該当する `["storage", "list", …]` を invalidate して
+UI を追従させる。
+
+## 落とし穴
+
+- **`getUrl` の URL は短命。** 結果を永続化したり長寿命のキャッシュに入れたりしない。
+  `expiresAt` の前に取り直す(上のフック)。`<img src>` に一度入れて放置すると、開いたままの
+  画面で後から読み込まれた分が失敗する
+- **`put` の `contentType` の既定は `application/octet-stream`。** 後で埋め込むもの(画像・動画・
+  PDF)には `file.type` を必ず渡す。付けないとブラウザが表示せずダウンロードに落ちる
+- **`key` は相対パス。** 先頭にスラッシュを付けない。`getUrl` を通さず `<img src="/foo.png">` の
+  ような静的パスで参照しない ― ストレージはアプリの `public/` ではない
+- **`copy` / `move` は既定で既存の宛先を上書きする。** 残したいときは `{ overwrite: false }`
+- **サーバー(`server/api/**`)からは呼ばない。** `useStorage` はブラウザ側の API
+
+---
+
+## 関連スキル
+
+- `vantage-add-feature` — ページ / API / コンポーネントを 1 つ足す手順
+- `vantage-pitfalls` — UI・配色・ルーティングの落とし穴

package/base-template/.squadbase/skills/vantage-pitfalls/SKILL.md

@@ -35,6 +35,28 @@ Base UI の `SelectValue` は選択中の **value をそのまま描き**、`Sel
 
 トリガーに `kanto` や `/sales` と生の値が出たら、まずこれを疑う。
 
+## 配色:素のパレット + `dark:` ではなく、セマンティックトークンで書く
+
+色は `text-foreground` / `text-muted-foreground` / `bg-card` / `border-border` などの
+トークンで書く。トークンはライト / ダークの両方を持っているので、`dark:` を並べる必要が無い。
+
+`text-slate-900 dark:text-slate-100` のような素の Tailwind パレット + `dark:` の組は、
+**トークンで塗られた周囲と食い違う**。ダークトークンが効くのは祖先に `.dark` /
+`[data-theme="dark"]` が付いているときだけで、`dark:` ユーティリティも同じスイッチに
+繋がっている(`theme.css` の `@custom-variant dark`)。つまり自分でクラスを付けない限り
+アプリは常にライトで動くのに、素のパレットを使うとその 1 か所だけ手動で両モードを
+管理することになる。
+
+```tsx
+// ✗ 手動で 2 モードを管理することになる
+<div className="font-medium text-slate-900 dark:text-slate-100">{name}</div>
+// ✓ トークンなら 1 つで済む
+<div className="font-medium text-foreground">{name}</div>
+```
+
+`--muted` / `--accent` / `--secondary` / `--border` は**背景・境界用**で、ライトではほぼ白。
+文字色に使うと読めなくなる ― 弱い文字色は `text-muted-foreground`。
+
 ## チャート:`EChart` の配色はトークン追従。上書きは `option.color`
 
 系列色は `--chart-1..5`、軸・凡例・ツールチップは文字色/境界色のトークンから組まれる

package/base-template/AGENTS.md

@@ -36,6 +36,11 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
 - **クライアントに届く env は `PUBLIC_` 接頭辞のものだけ。** `import.meta.env.PUBLIC_FOO`。
   それ以外を `import.meta.env` で読むと `PUBLIC_ENV_MISUSE` 警告。シークレットは
   `ApiContext.env`(server/ 内)にだけ届く。
+- **色はセマンティックトークンで書く。** `text-foreground`・`text-muted-foreground`・`bg-card`・
+  `border-border`。トークンがライト / ダークの両方を持つので `dark:` を並べる必要が無い。
+  素のパレット + `dark:`(`text-slate-900 dark:text-slate-100`)を混ぜると、その 1 か所だけ
+  手動で 2 モードを管理することになる(→「ダークモードは opt-in」)。`--muted`・`--accent`・
+  `--secondary`・`--border` は背景・境界用で、文字色に使うと読めない。
 - **`.vantage/` と `dist/` は生成物。** 編集しない・読みにいかない(gitignore 済み)。任意の CLI
   コマンド、または `vantage upgrade` で再生成される。
 - **`definePage` の値はリテラルで書く。** title/description/navLabel はビルド時に静的抽出される
@@ -318,6 +323,16 @@ const save = useApiMutation<Customer, Payload>("/api/customers", { method: "POST
   `ui: data-table` と `block: sales-overview` の 2 つだけ。それ以外の名前は import 専用で
   `add` の対象ではない(未知名で実行すると候補が一覧表示される)。
 
+### ダークモードは opt-in
+
+ダークのトークンが効くのは、祖先に `.dark` か `[data-theme="dark"]` が付いているときだけ。
+**OS / ブラウザの設定(`prefers-color-scheme`)は見ない。** `dark:` ユーティリティも同じ
+スイッチに繋いであるので(`theme.css` の `@custom-variant dark`)、自分でクラスを付けない限り
+アプリは常にライトで描かれる ― `dark:` を書いてもそこだけダークになることはない。
+
+明暗を切り替えたいときは、レイアウトのルート要素などに `.dark` / `data-theme="dark"` を
+自分で付ける。
+
 ## ドキュメントを引く(`vantage docs` / `vantage search`)
 
 ```bash
@@ -364,6 +379,7 @@ body・レスポンスの status と形)まで出る。`vantage check --json` /
 - **`vantage-app`** — アプリを一から作る / 構成を広げるときの進め方と検証の順序
 - **`vantage-add-feature`** — 既存アプリに page / api / ui を 1 つ足す定型
 - **`vantage-pitfalls`** — Base UI(≠ Radix)の癖など、静かに壊れる落とし穴のリファレンス
+- **`project-storage`** — Squadbase の Project Storage(アップロード済みファイル)をブラウザから読み書きする
 
 手順書の本体は `SKILL.md` というファイルで、置き場所はアプリによって違う(ルート直下・
 `.claude/skills/`・`.squadbase/skills/` など)。**探す必要はない ― CLI が探す:**
@@ -391,8 +407,9 @@ vantage add skill --all --dir .claude/skills   # 置き場所を指定(既定は
 > フレームワーク規約と矛盾する場合は**こちらが優先**します。
 >
 > `vantage upgrade` はこのファイルをフレームワーク同梱の正本で丸ごと上書きするため、
-> このセクションは消えます。消えたら squadbase-templates リポジトリの `agents/vantage/`
-> から貼り直してください(リポジトリ側では `npm run agents` が正本と結合して再生成します)。
+> このセクションは消えます。消えたら squadbase-monorepo の
+> `packages/vantage-template/agents/vantage/` から貼り直してください
+> (リポジトリ側では `npm run agents` が正本と結合して再生成します)。
 
 ## Squadbase の Connection / Query からデータを読む
 
@@ -469,3 +486,33 @@ const res = await fetch(`${baseUrl}/queries/${QUERY_ID}?since=2026-01-01`, {
   body: JSON.stringify({ customerId: "c_123" }),
 })
 ```
+
+## 構築中の一時的なエラーを「進行中」に見せる(`components/build-recovery.tsx`)
+
+ページを書いている途中は、ファイルが書き終わる順番の都合で一瞬だけページが throw する
+(まだ存在しないモジュールの import、書きかけのコンポーネント)。これを受け止めるのは
+**Vantage の既定エラー画面**(`Something went wrong`)で、**テンプレートからは差し替えられない** —
+`_error.tsx` はルートルート専用で、ページごとの `errorComponent` は現行プロトタイプでは
+まだ結線されていない。しかも掴んでいるのは TanStack の CatchBoundary なので、HMR で
+ソースが差し替わってもリセットされず、**リロードするまでエラー画面が貼り付く**。
+
+`components/build-recovery.tsx` の `BuildRecovery` が、その画面を DOM から検知して
+`Working on it…` 表示を被せ、dev では 1.2 秒待ってから自動でリロードして復帰させる
+(上限 3 回。使い切ったら「再読み込み」の案内に降格し、無事に描けたら残数が戻る)。
+降格した画面にはエラー本文をそのまま出し、`Copy log` でコピーできるようにしてある —
+自力で直らないときに本文をそのまま貼り戻してもらうため。
+`_error.tsx` も同じ `RecoveringState` を描くので、ルートレイアウトが throw したときの
+見た目と復帰の仕方は揃っている。
+
+### 追加の不変条件
+
+- **`_layout.tsx` の `<BuildRecovery>` を外さない。** `<Outlet />` を包む形で 1 回だけ使う。
+  外すと、書き込み途中の一瞬のエラーが `Something went wrong` のまま残る。
+- **`components/build-recovery.tsx` と `_error.tsx` を消さない・作り直さない。** ページ側に
+  独自のエラー UI を足す必要はない(足しても既定エラー画面より内側には入れない)。
+- **`role="alert"` の中に `h2` を置かない。** これが既定エラー画面の目印なので、ページが
+  同じ形を描くと `BuildRecovery` が誤検知して中身を覆ってしまう。UI キットの `Alert` /
+  `ErrorState` は見出しを `div` / `p` で描くのでそのまま使ってよい。
+- **データ取得の失敗は各ページが `ErrorState` で出す。** `BuildRecovery` が拾うのは
+  「レンダリングが throw した」場合だけで、`useApiQuery` の `isError` はページの責任
+  (→ フレームワーク規約の「データ取得」)。