@squadbase/vantage 0.3.0 → 0.4.0

package/docs/en/cli-reference.md

@@ -324,6 +324,66 @@ vantage build --api-base-url https://api.example.com
 The flag takes precedence over `PUBLIC_API_BASE_URL` from `.env`. Unset means empty (same-origin
 relative paths). See [Build & deploy](build-and-deploy) for details.
 
+## `--port` — the dev / preview port
+
+`vantage dev` (default `:5173`) and `vantage preview` (default `:4173`) accept `--port`.
+
+```bash
+vantage dev --port 3000
+vantage preview --port 8080
+```
+
+**An explicit `--port` is exact: if the port is taken, the server does not start and the command
+exits 1.** Writing `--port 3000` means the port is a contract with something outside the process — a
+reverse proxy, a container port mapping, an OAuth redirect URI — so quietly binding 3001 instead is a
+silent failure, not a recovery (a supervisor that only checks "is anything listening on 3000" will
+happily report a server nobody can reach).
+
+**Without `--port`**, a busy default port still walks to the next free one, so running several
+projects side by side takes no ceremony. Two flags override that default:
+
+| Flag | Meaning |
+|---|---|
+| `--strict-port` | Fail instead of walking, even when the port came from the default |
+| `--no-strict-port` | Walk to the next free port, even when `--port` was explicit |
+
+```bash
+vantage dev --port 3000 --no-strict-port   # 3000 busy → starts on 3001
+vantage dev --strict-port                  # will not start unless 5173 is free
+```
+
+> [!NOTE]
+> A `--port` value that is not an integer, or out of range, is an error — it never falls back to the
+> default silently. A fullstack `preview` binds its Node server to exactly one port, so it is **always**
+> strict and `--no-strict-port` has no effect there.
+
+## `VANTAGE_PROFILE` — measure before you tune
+
+Set `VANTAGE_PROFILE=1` on any command to see how long each phase took.
+
+```bash
+VANTAGE_PROFILE=1 vantage dev
+```
+
+```text
+[vantage:profile] scan                          1.6ms  @0.146s
+[vantage:profile] diagnostics                   2.1ms  @0.148s
+[vantage:profile] generate                      1.5ms  @0.159s
+[vantage:profile] vite:createServer            16.2ms  @0.165s
+[vantage:profile] vite:listen                  41.3ms  @0.206s
+```
+
+The left column is the duration; `@` is the time since the process started. The
+phases are `scan` (route discovery), `diagnostics` (the static checks),
+`generate` (writing `.vantage/`), `vite:*`, and `build:client` / `build:server`.
+
+> [!NOTE]
+> Everything goes to **stderr**. stdout stays clean, so this composes with `--json`.
+>
+> ```bash
+> VANTAGE_PROFILE=1 vantage check --json > result.json
+> ```
+
 ## Static diagnostics (`check`)
 
 `vantage check` detects these eight diagnostics (six errors, two warnings).

package/docs/ja/changelog.md

@@ -8,6 +8,71 @@ Vantage のリリースごとの変更点です。新しいものが上に来ま
 > まだプロトタイプ(**0.x**)です。0.x の間は **minor が実質のメジャー**扱いで、後方互換性の
 > ない変更は minor で入ることがあります。patch は後方互換の機能追加とバグ修正のみです。
 
+## v0.4.0
+
+明示した `--port` が厳格になりました。後方互換でない変更を含むため、0.x の方針に従って
+minor を上げています。
+
+依存を `"@squadbase/vantage": "^0.3.0"` と書いているアプリには 0.4.0 は入りません。
+`^0.4.0` に上げてください。
+
+> [!WARNING]
+> **`vantage dev --port 3000` は、3000 が埋まっていると起動せずエラーで終了します(exit 1)。**
+> これまでは黙って 3001 へずれていました。従来の挙動が必要なら `--no-strict-port` を付けて
+> ください。`--port` を**省いたとき**の挙動は変わりません(既定の 5173 / 4173 が埋まっていれば
+> 次の空きポートへずれます)。
+
+### 変更
+
+- **明示した `--port` は厳格になりました**(→ [CLI リファレンス](cli-reference))― `--port 3000`
+  と書くのは、リバースプロキシ・コンテナのポートマッピング・OAuth のリダイレクト URI など
+  **プロセスの外側との約束**があるからで、黙って 3001 で上がるのは復旧ではなく静かな失敗です
+  (「3000 で誰かが listen しているか」だけを見る監視は、誰も到達できないサーバーを「起動成功」と
+  報告してしまいます)。`--port` を省いたときは従来どおり次の空きポートへずれるので、複数の
+  プロジェクトを並べて立ち上げる手軽さは変わりません。
+- **`--port` の値が不正なときはエラーになりました** ― 整数でない・範囲外・値が無い場合、
+  これまでは黙って既定値で起動していました。
+
+### 追加
+
+- **`--strict-port`** ― `--port` を省いたときも、既定ポートが取れなければ起動しません。
+- **`--no-strict-port`** ― `--port` を明示したときも、埋まっていれば次の空きポートへずらします。
+  0.3.x までの挙動が必要なときに使ってください。
+
+fullstack の `vantage preview` は Node サーバーを 1 ポートに bind するだけなので以前から常に
+厳格で、`--no-strict-port` は効きません(その旨を表示します)。
+
+## v0.3.1
+
+CLI の起動と、開発サーバー・ビルドの立ち上がりを速くしました。挙動を変える意図の変更は
+含まれておらず、すべて後方互換です。
+
+### 速くなったもの
+
+- **`check` / `routes` / `docs` / `search` / `add` / `doctor` が約 3 倍速くなりました**
+  (実測 205ms → 65〜75ms)。これらのコマンドは Vite も Tailwind も使わないのに、CLI が
+  起動時に必ず読み込んでいました。コマンドごとに必要なものだけを読むようにしています。
+  エージェントや CI が `check` と `routes` を繰り返し叩く場面ほど効きます。
+- **`vantage dev` の起動が速くなりました** ― 起動時にプロジェクトを 4 回走査していたのを
+  1 回にしました(生成も 2 回 → 1 回)。
+- **`vantage build` でクライアントとサーバーを並列に建てるようになりました**
+  (`server/` があるプロジェクトのみ)。ログは「Building client…」「Building server…」の
+  2 行から「Building client and server…」の 1 行になります。
+- **`vantage check` が同じファイルを読み直さなくなりました** ― ページモジュールは 3 回、
+  プロジェクトツリーの走査は 2 回行われていました。大きなアプリほど差が出ます。
+- **開発サーバーの無駄な再走査を減らしました** ― ディレクトリが作られるたびに全走査して
+  いたのを、ページや API になり得る場所のときだけにしました。
+- **依存のプリバンドルを先に宣言するようになりました** ― UI キットが使う依存
+  (Base UI・ECharts・TanStack Table など)を Vite に先に伝えるので、初めてその
+  コンポーネントを使ったページを開いたときの「依存が見つかった → ページ全体がリロード」が
+  起きなくなります(`npm` / `yarn` のように依存が巻き上げられる構成のとき)。
+
+### 追加
+
+- **`VANTAGE_PROFILE=1`**(→ [CLI リファレンス](cli-reference))― 任意の `vantage` コマンドの
+  各フェーズの所要時間を **stderr** に出します。「遅い」を測ってから直すための計測口です。
+  stdout には出さないので `--json` と併用できます。
+
 ## v0.3.0
 
 ページの置き場所として `src/` を認識するようになりました。後方互換でない変更(`src/` を持つ

package/docs/ja/cli-reference.md

@@ -318,6 +318,66 @@ vantage build --api-base-url https://api.example.com
 このフラグは `.env` の `PUBLIC_API_BASE_URL` より優先されます。未指定なら空(同一オリジンの
 相対パス)。詳細は[ビルドとデプロイ](build-and-deploy)を参照してください。
 
+## `--port` — dev / preview のポート
+
+`vantage dev`(既定 `:5173`)と `vantage preview`(既定 `:4173`)は `--port` を受け付けます。
+
+```bash
+vantage dev --port 3000
+vantage preview --port 8080
+```
+
+**`--port` を明示したときは、そのポートが取れなければ起動せずエラーで終了します**(exit 1)。
+`--port 3000` と書くのは、リバースプロキシ・コンテナのポートマッピング・OAuth のリダイレクト URI
+など**プロセスの外側との約束**があるからで、黙って 3001 で上がるのは復旧ではなく静かな失敗だからです
+(「3000 で誰かが listen しているか」だけを見る監視は、誰も到達できないサーバーを "起動成功" と
+報告してしまいます)。
+
+`--port` を**省いたとき**は既定ポートが埋まっていれば**次の空きポートへ自動でずれます**。複数の
+プロジェクトを同時に立ち上げるのに手間はかかりません。この既定は 2 つのフラグで上書きできます。
+
+| フラグ | 意味 |
+|---|---|
+| `--strict-port` | `--port` を省いたときも、既定ポートが取れなければエラーで終了する |
+| `--no-strict-port` | `--port` を明示したときも、埋まっていれば次の空きポートへずらす |
+
+```bash
+vantage dev --port 3000 --no-strict-port   # 3000 が埋まっていれば 3001 で上がる
+vantage dev --strict-port                  # 5173 が取れなければ起動しない
+```
+
+> [!NOTE]
+> `--port` の値が整数でない・範囲外のときはエラーです(既定値へ黙って戻ることはありません)。
+> また fullstack の `preview` は Node サーバーを 1 ポートに bind するだけなので**常に厳格**で、
+> `--no-strict-port` は効きません。
+
+## `VANTAGE_PROFILE` — 遅いときに測る
+
+どのコマンドでも `VANTAGE_PROFILE=1` を付けると、フェーズごとの所要時間が出ます。
+
+```bash
+VANTAGE_PROFILE=1 vantage dev
+```
+
+```text
+[vantage:profile] scan                          1.6ms  @0.146s
+[vantage:profile] diagnostics                   2.1ms  @0.148s
+[vantage:profile] generate                      1.5ms  @0.159s
+[vantage:profile] vite:createServer            16.2ms  @0.165s
+[vantage:profile] vite:listen                  41.3ms  @0.206s
+```
+
+左が所要時間、右の `@` はプロセス開始からの経過です。`scan`(ルートの走査)・
+`diagnostics`(静的診断)・`generate`(`.vantage/` の生成)・`vite:*`・`build:client` /
+`build:server` が出ます。
+
+> [!NOTE]
+> 出力先は **stderr** です。stdout は汚さないので、`--json` と一緒に使っても JSON は壊れません。
+>
+> ```bash
+> VANTAGE_PROFILE=1 vantage check --json > result.json
+> ```
+
 ## 静的診断（`check`）
 
 `vantage check` が検出する診断は次の 8 種類です（エラー 6・警告 2）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squadbase/vantage",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Data dashboard framework for Squadbase Editor. Vite-powered, config-free, one-file first.",
   "type": "module",
   "license": "MIT",
@@ -86,11 +86,14 @@
     "templates"
   ],
   "scripts": {
-    "build": "node scripts/build-docs.mjs && tsup",
+    "build": "node scripts/build-docs.mjs && node scripts/build.mjs",
+    "build:js": "tsup --no-dts",
+    "build:types": "tsup --dts-only",
     "build:docs": "node scripts/build-docs.mjs",
-    "dev": "tsup --watch",
+    "dev": "tsup --watch --no-dts",
+    "dev:types": "tsc --noEmit --watch",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "node scripts/build-docs.mjs && tsup"
+    "prepublishOnly": "node scripts/build-docs.mjs && node scripts/build.mjs"
   },
   "dependencies": {
     "@base-ui/react": "^1.6.0",

package/skills/vantage-app/SKILL.md

@@ -44,7 +44,7 @@ exit 1 になる。
     "routes": "vantage routes"
   },
   "dependencies": {
-    "@squadbase/vantage": "^0.3.0",
+    "@squadbase/vantage": "^0.4.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   }

package/templates/AGENTS.md

@@ -122,7 +122,7 @@ root/
     "routes": "vantage routes"
   },
   "dependencies": {
-    "@squadbase/vantage": "^0.3.0",
+    "@squadbase/vantage": "^0.4.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   }