@squadbase/vantage 0.2.2 → 0.2.3

package/dist/index.d.ts

@@ -10,6 +10,6 @@ import 'react';
  */
 
 /** Framework version, kept in sync with package.json at build time. */
-declare const VERSION = "0.2.2";
+declare const VERSION = "0.2.3";
 
 export { VERSION };

package/dist/index.js

@@ -6,7 +6,7 @@ function definePage(config) {
 }
 
 // src/index.ts
-var VERSION = "0.2.2";
+var VERSION = "0.2.3";
 
 export { VERSION, definePage };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/runtime/define-page.ts","../src/index.ts"],"names":[],"mappings":";;;AAyCO,SAAS,WAAW,MAAA,EAAgC;AACzD,EAAA,OAAO,MAAA;AACT;;;AChCO,IAAM,OAAA,GAAU","file":"index.js","sourcesContent":["import type { ComponentType, ReactNode } from \"react\"\n\n/**\n * Optional per-page configuration. The only required part of a page module is\n * its default-exported component; `definePage` covers everything else.\n */\nexport interface PageConfig {\n  /** Document title applied when this route is active. */\n  title?: string\n  /** Description metadata for the page. */\n  description?: string\n  /**\n   * Short label for navigation built from `useRoutes()`. Defaults to `title`,\n   * which is often too long for a nav (\"Overview · Acme Analytics\").\n   */\n  navLabel?: string\n  /**\n   * Component rendered while the route is loading.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  pendingComponent?: ComponentType\n  /**\n   * Component rendered when the route throws.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  errorComponent?: ComponentType<{ error: unknown }>\n  /**\n   * Validate/transform the URL search params for this route.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  validateSearch?: (search: Record<string, unknown>) => Record<string, unknown>\n}\n\n/**\n * Declare optional page configuration.\n *\n * ```tsx\n * export const page = definePage({ title: \"Monthly Analysis\" })\n * export default function MonthlyAnalysis() { return <div/> }\n * ```\n */\nexport function definePage(config: PageConfig): PageConfig {\n  return config\n}\n\n/** Convenience type for a Vantage page component. */\nexport type PageComponent = ComponentType & { (): ReactNode }\n","/**\n * `@squadbase/vantage` — public runtime surface.\n *\n * The only import most pages need. Server state lives in\n * `@squadbase/vantage/query`, navigation in `@squadbase/vantage/router`,\n * UI in `@squadbase/vantage/ui`, and API types in `@squadbase/vantage/server`.\n */\nexport { definePage } from \"./runtime/define-page\"\nexport type { PageConfig, PageComponent } from \"./runtime/define-page\"\n\n/** Framework version, kept in sync with package.json at build time. */\nexport const VERSION = \"0.2.2\"\n"]}
+{"version":3,"sources":["../src/runtime/define-page.ts","../src/index.ts"],"names":[],"mappings":";;;AAyCO,SAAS,WAAW,MAAA,EAAgC;AACzD,EAAA,OAAO,MAAA;AACT;;;AChCO,IAAM,OAAA,GAAU","file":"index.js","sourcesContent":["import type { ComponentType, ReactNode } from \"react\"\n\n/**\n * Optional per-page configuration. The only required part of a page module is\n * its default-exported component; `definePage` covers everything else.\n */\nexport interface PageConfig {\n  /** Document title applied when this route is active. */\n  title?: string\n  /** Description metadata for the page. */\n  description?: string\n  /**\n   * Short label for navigation built from `useRoutes()`. Defaults to `title`,\n   * which is often too long for a nav (\"Overview · Acme Analytics\").\n   */\n  navLabel?: string\n  /**\n   * Component rendered while the route is loading.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  pendingComponent?: ComponentType\n  /**\n   * Component rendered when the route throws.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  errorComponent?: ComponentType<{ error: unknown }>\n  /**\n   * Validate/transform the URL search params for this route.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  validateSearch?: (search: Record<string, unknown>) => Record<string, unknown>\n}\n\n/**\n * Declare optional page configuration.\n *\n * ```tsx\n * export const page = definePage({ title: \"Monthly Analysis\" })\n * export default function MonthlyAnalysis() { return <div/> }\n * ```\n */\nexport function definePage(config: PageConfig): PageConfig {\n  return config\n}\n\n/** Convenience type for a Vantage page component. */\nexport type PageComponent = ComponentType & { (): ReactNode }\n","/**\n * `@squadbase/vantage` — public runtime surface.\n *\n * The only import most pages need. Server state lives in\n * `@squadbase/vantage/query`, navigation in `@squadbase/vantage/router`,\n * UI in `@squadbase/vantage/ui`, and API types in `@squadbase/vantage/server`.\n */\nexport { definePage } from \"./runtime/define-page\"\nexport type { PageConfig, PageComponent } from \"./runtime/define-page\"\n\n/** Framework version, kept in sync with package.json at build time. */\nexport const VERSION = \"0.2.3\"\n"]}

package/dist/vite/index.js

@@ -1,4 +1,4 @@
-export { vantagePlugin } from '../chunk-UHZ7XSAN.js';
+export { vantagePlugin } from '../chunk-3QKPNWKJ.js';
 import '../chunk-46QI6GFC.js';
 import '../chunk-B7LLBNLV.js';
 //# sourceMappingURL=index.js.map

package/docs/en/changelog.md

@@ -9,6 +9,30 @@ What changed in each Vantage release. Newest is on top.
 > minor release may include backwards-incompatible changes. A patch is limited to
 > backwards-compatible additions and bug fixes.
 
+## v0.2.3
+
+`vantage routes` can be narrowed to one side of the map, and can print the spec of
+every route. Additions only, so it is backwards-compatible.
+
+### Added
+
+- **`vantage routes` takes `--pages` / `--apis`** (see
+  [CLI reference](cli-reference)) — pages only (plus layout / 404 / error), or
+  API routes only. They are not exclusive: passing both, or neither, prints
+  everything exactly as before.
+- **`--detail` adds each route's static spec** — for a page, the `definePage`
+  title / navLabel / description and its path params; for an API, **per method**,
+  the query keys read through `searchParams`, the request body (`json` /
+  `formData` / `text`, with its keys when destructured), the response status,
+  content type and object keys, and the status and message of every `HttpError`.
+  It answers "how do I call this endpoint?" without opening the handler.
+  - With `--json`, every entry gains a `spec`. The existing keys (`route`,
+    `file`, `dynamic`, `params`) are untouched, so current readers keep working.
+  - Everything is **inferred by reading the source** — like `check`, your code is
+    never imported or executed. Keys assembled at runtime, or input and output
+    hidden inside helper functions, will not show up: treat the output as a
+    **draft** of the spec, not a contract.
+
 ## v0.2.2
 
 `vantage add skill` now scans for where the skills already are, and charts follow

package/docs/en/cli-reference.md

@@ -12,7 +12,7 @@
 | `vantage build` | Build client + optional server → `dist/` |
 | `vantage preview` | Run the production build locally (fullstack default `:4173`; spa via Vite preview) |
 | `vantage check` | Static checks (routes, boundaries, forbidden files). Exit 1 on error |
-| `vantage routes` | Print the page + API URL map |
+| `vantage routes` | Print the page + API URL map (`--pages` / `--apis` for one side only, `--detail` for each route's spec) |
 | `vantage add <kind> <name>` | Scaffold or place a `page` / `api` / `ui` / `block` / `skill` / `agents` (`--force` to overwrite; `skill` scans for copies already placed and skips them, `--dir` picks the destination) |
 | `vantage docs [name]` | Show the bundled guide and component reference |
 | `vantage search <query>` | Search that same reference in full text (natural language or `--regex`) |
@@ -51,6 +51,57 @@ vantage check ./demo/index.tsx # a file argument still checks its parent directo
 > `add`, `docs` and `search` use their positionals for their own arguments (`add page dashboard`,
 > `docs button`, `search date picker`) rather than a path, so they are excluded from this shortcut.
 
+## `vantage routes` — the URL map, with specs
+
+With no flags it prints the URL map of pages, layouts and API routes. Flags narrow it to **one
+side** or add the **static spec** of every route.
+
+| Flag | Meaning |
+|---|---|
+| `--pages` | Pages only (plus layout / 404 / error) |
+| `--apis` | API routes only |
+| `--detail` | Add each route's spec (pages: path params + `definePage` metadata; APIs: methods, request, response) |
+| `--json` | Machine-readable output (with `--detail`, every entry gains a `spec`) |
+
+`--pages` and `--apis` are not exclusive — passing both, or neither, prints everything.
+
+```bash
+vantage routes --pages           # pages only
+vantage routes --apis --detail   # APIs with their specs
+vantage routes --detail --json   # machine-readable, specs included
+```
+
+```text
+Pages
+  /sales/:customerId           sales/[customerId].tsx
+      title    Customer detail
+      params   :customerId
+
+API
+  /api/customers/:id           server/api/customers/[id].ts
+      GET
+        path     :id
+        response 200 application/json
+        error    404 "Customer ${params.id} not found"
+```
+
+`--detail` reads these shapes:
+
+| Line | Where it comes from |
+|---|---|
+| `title` / `nav` / `desc` | String literals in `definePage({ ... })` |
+| `params` | `[id]` / `[...rest]` in the filename |
+| Method | HTTP method exports such as `export function GET` |
+| `query` | `searchParams.get/getAll/has("x")` |
+| `body` | `request.json()` / `formData()` / `text()` (plus the keys of `const { a, b } = await request.json()`) |
+| `response` | Status, content type and object-literal keys of `Response.json(…)` / `json(…)` / `new Response(…)` |
+| `error` | `new HttpError(status, "message")` |
+
+> [!NOTE]
+> Like `check`, `--detail` is **static text analysis** — your code is never imported or executed. Keys
+> assembled at runtime, or input/output hidden inside helper functions, will not show up. Treat the
+> output as a draft of the spec, not a contract.
+
 ## `vantage docs` — read the docs from the CLI
 
 The content of this site is **bundled into the package**, so `vantage docs` prints it as plain

package/docs/ja/changelog.md

@@ -8,6 +8,28 @@ Vantage のリリースごとの変更点です。新しいものが上に来ま
 > まだプロトタイプ(**0.x**)です。0.x の間は **minor が実質のメジャー**扱いで、後方互換性の
 > ない変更は minor で入ることがあります。patch は後方互換の機能追加とバグ修正のみです。
 
+## v0.2.3
+
+`vantage routes` を片側だけに絞れるようになり、各ルートの仕様も出せるようになりました。
+すべて追加のみで後方互換です。
+
+### 追加
+
+- **`vantage routes` に `--pages` / `--apis` が付きました**(→ [CLI リファレンス](cli-reference))
+  ― ページ(+ layout / 404 / error)だけ、API ルートだけに絞れます。排他ではないので、両方
+  付けても、どちらも付けなくても今までどおり全部出ます。
+- **`--detail` で各ルートの静的な仕様を併記します** ― ページは `definePage` の
+  title / navLabel / description とパスパラメータ、API は**メソッドごと**に
+  `searchParams` で読むクエリキー・リクエストボディ(`json` / `formData` / `text`。
+  分割代入していればキーも)・レスポンスの status と content-type とオブジェクトのキー・
+  `HttpError` の status とメッセージが並びます。既存 API の呼び方を確かめるのに、
+  ハンドラを開かずに済みます。
+  - `--json` と併せると、各要素に `spec` が増えます。既存のキー(`route` / `file` /
+    `dynamic` / `params`)はそのままなので、今の読み手を壊しません。
+  - 取れるのは**ソースを読んだだけの推定**です(`check` と同じく、アプリのコードを import も
+    実行もしません)。実行時に組み立てるキーや、ヘルパー関数の中に隠れた入出力は出てきません
+    ― 仕様の**下書き**であって契約ではありません。
+
 ## v0.2.2
 
 `vantage add skill` が配置先を走査するようになり、チャートがスタイルシートの差し替えにも

package/docs/ja/cli-reference.md

@@ -12,7 +12,7 @@
 | `vantage build` | クライアント + オプションのサーバーをビルド → `dist/` |
 | `vantage preview` | 本番ビルドをローカルで起動（fullstack は既定 `:4173`、spa は Vite プレビュー） |
 | `vantage check` | 静的検査（ルート・境界・禁止ファイル）。エラーがあれば exit 1 |
-| `vantage routes` | ページ + API の URL マップを表示 |
+| `vantage routes` | ページ + API の URL マップを表示（`--pages` / `--apis` で片側だけ、`--detail` で仕様つき） |
 | `vantage add <kind> <name>` | `page` / `api` / `ui` / `block` / `skill` / `agents` を雛形生成・配置（`--force` で上書き、`skill` は配置済みを走査してスキップ・`--dir` で配置先を指定） |
 | `vantage docs [name]` | 同梱のガイド + コンポーネントリファレンスを表示 |
 | `vantage search <query>` | 同じリファレンスを全文検索（自然言語 or `--regex`） |
@@ -51,6 +51,57 @@ vantage check ./demo/index.tsx # ファイル指定でも親ディレクトリ
 > `add`・`docs`・`search` はパス引数ではなく positional を自分の引数（`add page dashboard`・
 > `docs button`・`search 日付の選択`）に使うため、この短縮形の対象外です。
 
+## `vantage routes` — URL マップと仕様
+
+引数なしで、ページ・レイアウト・API の URL マップを出します。フラグで**片側だけ**に絞ったり、
+各ルートの**静的な仕様**を足したりできます。
+
+| フラグ | 意味 |
+|---|---|
+| `--pages` | ページ（+ layout / 404 / error）だけを表示 |
+| `--apis` | API ルートだけを表示 |
+| `--detail` | 各ルートの仕様を併記（ページはパスパラメータと `definePage` のメタ、API はメソッド・リクエスト・レスポンス） |
+| `--json` | 機械可読出力（`--detail` を付けると各要素に `spec` が付く） |
+
+`--pages` と `--apis` は排他ではありません。両方付けても、どちらも付けなくても全部出ます。
+
+```bash
+vantage routes --pages           # ページだけ
+vantage routes --apis --detail   # API を仕様つきで
+vantage routes --detail --json   # 仕様つきの機械可読出力
+```
+
+```text
+Pages
+  /sales/:customerId           sales/[customerId].tsx
+      title    Customer detail
+      params   :customerId
+
+API
+  /api/customers/:id           server/api/customers/[id].ts
+      GET
+        path     :id
+        response 200 application/json
+        error    404 "Customer ${params.id} not found"
+```
+
+`--detail` が拾うのは次の書き方です。
+
+| 行 | 何を読むか |
+|---|---|
+| `title` / `nav` / `desc` | `definePage({ ... })` の文字列リテラル |
+| `params` | ファイル名の `[id]` / `[...rest]` |
+| メソッド | `export function GET` などの HTTP メソッド export |
+| `query` | `searchParams.get/getAll/has("x")` |
+| `body` | `request.json()` / `formData()` / `text()`（`const { a, b } = await request.json()` ならキーも） |
+| `response` | `Response.json(…)` / `json(…)` / `new Response(…)` の status・content-type・オブジェクトリテラルのキー |
+| `error` | `new HttpError(status, "message")` |
+
+> [!NOTE]
+> `--detail` は `check` と同じく**ソースを読むだけの静的解析**で、アプリのコードを import も実行も
+> しません。実行時に組み立てるキーや、ヘルパー関数の中に隠れた入出力は出てきません（出力は
+> 「仕様の下書き」であって契約ではありません）。
+
 ## `vantage docs` — ドキュメントを CLI で読む
 
 このサイトの内容は**パッケージに同梱**されていて、`vantage docs` でそのまま読めます。ネット接続も

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squadbase/vantage",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Data dashboard framework for Squadbase Editor. Vite-powered, config-free, one-file first.",
   "type": "module",
   "license": "MIT",

package/skills/vantage-add-feature/SKILL.md

@@ -133,11 +133,21 @@ vantage check     # 規約違反が無いか(exit 1 ならエラーあり)
 vantage dev       # 実際に動くか(console は開発ターミナルに [browser:…] で転送)
 ```
 
+`vantage routes` は `--pages` / `--apis` で片側だけに絞れる。`--detail` を足すと各ルートの静的な
+仕様(ページ: パスパラメータ + `definePage` のメタ / API: メソッド・`searchParams` のキー・
+リクエストボディ・レスポンスの status と形・`HttpError`)まで出るので、**既存 API の呼び方を
+確かめる**ときはこれが速い(ソースを読むだけの推定で、実行はしない)。
+
+```bash
+vantage routes --apis --detail   # 既存 API のメソッド/入出力を確認
+```
+
 エージェントで自動処理するなら機械可読出力を使う:
 
 ```bash
-vantage routes --json   # { pages, layouts, notFound, error, apis, hasServer }
-vantage check --json    # { ok, errorCount, warningCount, diagnostics[] }
+vantage routes --json            # { pages, layouts, notFound, error, apis, hasServer }
+vantage routes --apis --detail --json  # { apis: [{ route, file, params, spec }], hasServer }
+vantage check --json             # { ok, errorCount, warningCount, diagnostics[] }
 ```
 
 `vantage check` が出しうる診断コード(参考):

package/templates/AGENTS.md

@@ -309,8 +309,10 @@ pnpm preview   # 本番ビルドをローカル実行
 ```
 
 `vantage-manifest.json` の `mode`(`spa` / `fullstack`)は `server/` の有無から自動で決まる
-(手で書かない)。`vantage check --json` / `vantage routes --json` はエージェント向けの機械
-可読出力。`console.*` とランタイムエラーは開発ターミナルに `[browser:…]` として転送される。
+(手で書かない)。`vantage routes` は `--pages` / `--apis` で片側だけに絞れ、`--detail` を足すと
+各ルートの静的な仕様(ページ: パスパラメータ + `definePage` のメタ / API: メソッド・query・
+body・レスポンスの status と形)まで出る。`vantage check --json` / `vantage routes --json` は
+エージェント向けの機械可読出力。`console.*` とランタイムエラーは開発ターミナルに `[browser:…]` として転送される。
 
 ## さらに詳しく(同梱 Skill)