@kaki-cli/cli

v0.1.2

Published

4 months ago

Multi-product Kaki CLI guided installer and operations tooling.

0High
0Medium
0Low

Kaki CLI

Kaki CLI 是 Kaki 產品的 umbrella command。第一版先支援 Kaki Assets Cloud Run self-host guided installer，未來會加入 kaki travel、kaki spend 等 product module。

目前 repo 已落地 TypeScript CLI scaffold、read-only doctor、image-only update-cloud-run、可 dry-run / 可確認後執行的 first install deploy-cloud-run、TDCC reference data warmup，以及 read-only HTTP smoke-test。

Command Map

本機開發可先從本 repo build 後執行：

macOS / Linux：

cd /Users/sean/MyGitRepo/kaki-cli
npm_config_cache=.npm-cache npm install
npm_config_cache=.npm-cache npm run build
node dist/cli.js assets doctor --project kaki-assets-pilot

Windows PowerShell：

cd C:\Users\<you>\MyGitRepo\kaki-cli
$env:npm_config_cache = ".npm-cache"
npm install
npm run build
node dist/cli.js assets doctor --project kaki-assets-pilot

正式 npm package command shape：

npx -y "@kaki-cli/cli@latest" assets doctor --project kaki-assets-pilot
npx -y "@kaki-cli/cli@latest" assets deploy-cloud-run --project kaki-assets-pilot --dry-run
npx -y "@kaki-cli/cli@latest" assets deploy-cloud-run --project kaki-assets-pilot --firebase-web-api-key ... --firebase-web-app-id ... --super-admin-emails ... --yes
npx -y "@kaki-cli/cli@latest" assets update-cloud-run --tag v2.4.3 --project kaki-assets-pilot --dry-run
npx -y "@kaki-cli/cli@latest" assets update-cloud-run --tag v2.4.3 --project kaki-assets-pilot --yes
npx -y "@kaki-cli/cli@latest" assets warmup-reference-data --market TW --project kaki-assets-pilot --dry-run
npx -y "@kaki-cli/cli@latest" assets smoke-test --url https://example.run.app
npx -y "@kaki-cli/cli@latest" assets show-config

First Install

第一次自架 Kaki Assets Cloud Run，請從 Kaki Assets Cloud Run 自架安裝手冊開始。它會照順序帶你完成 Firebase / Google Cloud Console manual steps、deploy-cloud-run --dry-run、真實 deploy、Firebase Auth authorized domains、smoke-test 與日後 update-cloud-run。手冊內同時提供 macOS / Linux 與 Windows PowerShell 指令。

README 保留 command map 與設計邊界；正式 step-by-step 安裝流程集中在 docs/INSTALL_ASSETS_CLOUD_RUN.md。

正式 npm package 的 assets doctor 可接受：

npx -y "@kaki-cli/cli@latest" assets doctor \
  --project kaki-assets-pilot \
  --region asia-east1 \
  --service-id kaki-assets-web \
  --repository kaki-assets

也支援 env fallback：

KAKI_ASSETS_PROJECT_ID
KAKI_ASSETS_REGION
KAKI_ASSETS_SERVICE_ID
KAKI_ASSETS_REPOSITORY

Kaki Assets v1 目標

kaki assets deploy-cloud-run 是 guided installer。使用者完成必要 Console 設定後，CLI 會一路處理可自動化的 terminal 步驟：

preflight 檢查工具、登入、project、API、Firestore、Docker/GHCR/Artifact Registry 狀態。
從 GHCR release image copy/tag/push 到使用者自己的 Artifact Registry。
建立 Cloud Run runtime service account、IAM、Secret Manager secrets。
部署 Cloud Run production-safe env vars 與 secret mappings。
部署 bundled Firestore rules/indexes。
寫入 TDCC 台股名稱 reference data cache，降低新站第一次輸入台股代號的等待時間。
印出 Firebase Auth authorized domain manual step。
執行 read-only smoke test，並提示後續 browser manual checks。

CLI 的產品定位不是工程師腳本，而是可信任的安裝精靈：預設互動式、防呆、可重跑，錯誤訊息要短、清楚、可行動。

Deploy Cloud Run First Install

deploy-cloud-run 是 first install guided flow。建議先跑 --dry-run：它會收集/檢查必要輸入、執行 read-only preflight、列出 Phase A Console checklist，並印出 Phase B terminal command plan；不會修改外部 cloud resources。若沒有傳 --tag，CLI 會使用 bundled recommended release tag，仍會落到明確的 vX.Y.Z image，不使用 Docker latest。

npx -y "@kaki-cli/cli@latest" assets deploy-cloud-run \
  --project kaki-assets-pilot \
  --firebase-web-api-key "Firebase Web App apiKey" \
  --firebase-web-app-id "Firebase Web App appId" \
  --super-admin-emails "[email protected]" \
  --dry-run

確認 plan 後再執行真實安裝：

npx -y "@kaki-cli/cli@latest" assets deploy-cloud-run \
  --project kaki-assets-pilot \
  --firebase-web-api-key "Firebase Web App apiKey" \
  --firebase-web-app-id "Firebase Web App appId" \
  --super-admin-emails "[email protected]" \
  --yes

如果不加 --yes，CLI 會先印出 manual checklist、input checks、command plan，然後詢問：

Continue with Cloud Run first install? [y/N]

若在互動式 terminal 執行，缺少必要輸入時 CLI 會逐步詢問 project、Firebase Web App apiKey/appId、super admin emails；region、service id、repository 可直接接受預設值。release tag 預設使用 CLI bundled recommendation，進階使用者可用 --tag vX.Y.Z override。--yes 只跳過確認問題，不會替你填缺少的輸入。CI 或 non-TTY 環境請使用 flags/env。

也可用 env 提供部署輸入：

KAKI_ASSETS_RELEASE_TAG (optional override)
KAKI_ASSETS_FIREBASE_WEB_API_KEY
KAKI_ASSETS_FIREBASE_WEB_APP_ID
KAKI_ASSETS_SUPER_ADMIN_EMAILS
TWELVE_DATA_API_KEY

deploy-cloud-run 會規劃並在確認後執行：

enable required Google Cloud APIs。
create/reuse Artifact Registry repository。
copy GHCR image into Artifact Registry。
create/reuse Cloud Run runtime service account。
grant IAM roles。
create/update Secret Manager secrets。
deploy Cloud Run with production-safe env vars and secret mappings。
read Cloud Run URL。
deploy bundled Firestore rules/indexes from CLI resources, not an Assetbase source checkout。
warm up TDCC Taiwan reference data cache in Firestore。

Secret Manager values 只透過 stdin / --data-file=- 傳入 gcloud，不會出現在 command line、log 或 local config。Firebase Web API key、Firebase App ID、super admin emails、Twelve Data API key 不會寫入 local config；使用者可見輸出會 redacted。

成功後 CLI 只會保存 non-secret deployment locator，並印出最後一個 manual step：把 Cloud Run service domain 加到 Firebase Auth authorized domains。

Reference Data Warmup

kaki assets warmup-reference-data --market TW 會抓取 TDCC 台股基本資料，將正常且 TWD 計價的證券名稱寫入使用者自己的 Firestore：

marketReferenceData/tw-security-names/securities/{SYMBOL}

建議先 dry-run：

npx -y "@kaki-cli/cli@latest" assets warmup-reference-data --market TW --project kaki-assets-pilot --dry-run

真實寫入需要使用目前 gcloud 登入身份的 Firestore write 權限：

npx -y "@kaki-cli/cli@latest" assets warmup-reference-data --market TW --project kaki-assets-pilot --yes

deploy-cloud-run 會在 Firestore rules/indexes 部署後自動執行一次 warmup。若 TDCC 暫時不可用或 Firestore write 權限不足，first install 會保留成功，只把 warmup 顯示為 WARN，之後可重跑本 command。

Assets Doctor

kaki assets doctor 是 read-only preflight。它會檢查本機工具與已知 project 狀態，但不會建立、不會啟用、不會更新任何 Cloud/Firebase/Docker resource。

Doctor 狀態判讀：

PASS：已確認沒問題。
PLANNED：first install 前預期還不存在，deploy-cloud-run 會建立或啟用。
WARN：需要注意或權限不足導致無法確認；請看 Fix 訊息。
FAIL：阻擋 deploy，必須先修。
MANUAL：Console UI 步驟，CLI 無法代按，請人工確認。

可自動檢查：

Node.js、npm/npx、gcloud、Docker CLI 與 Docker daemon。
active gcloud account。
project access。
Billing / Blaze plan best-effort。
required Google Cloud APIs。
Firestore (default) database 與 location。
Artifact Registry repository、Cloud Run service、Secret Manager secrets 是否已存在。

只能 manual checklist：

Firebase Web App 是否已建立並保留 apiKey / appId。
Firebase Authentication Google provider 是否 enabled。
Firebase project public name / support email 是否已填。
deploy 後 Cloud Run domain 是否已加入 Firebase Auth authorized domains。

Exit code 規則：

有任何 FAIL：exit code 1。
沒有 FAIL，即使有 PLANNED、WARN、MANUAL、INFO、SKIP、PASS：exit code 0。

Update Cloud Run Image

kaki assets update-cloud-run --tag vX.Y.Z 會執行已存在 Cloud Run service 的 image-only update。

它會做：

inspect GHCR release image，確認支援 linux/amd64。
pull/tag/push image 到使用者自己的 Artifact Registry。
執行 gcloud run services update --image。
讀回 Cloud Run URL。
成功後只把 non-secret deployment locator 寫回 ~/.config/kaki/assets.json。

它不會做：

不會使用 gcloud run deploy。
不會使用 --set-env-vars 或 --set-secrets。
不會改 Cloud Run env vars、secrets、service account、port。
不會部署 Firestore rules/indexes。

建議先 dry-run：

npx -y "@kaki-cli/cli@latest" assets update-cloud-run \
  --tag v2.4.3 \
  --project kaki-assets-pilot \
  --dry-run

確認後執行：

npx -y "@kaki-cli/cli@latest" assets update-cloud-run \
  --tag v2.4.3 \
  --project kaki-assets-pilot \
  --yes

如果不加 --yes，CLI 會在通過 precheck 後要求互動確認。latest 與非 vX.Y.Z tag 會被拒絕。

Smoke Test

kaki assets smoke-test 是部署後的 read-only HTTP 驗證。它不登入、不寫入資料、不修改 Cloud resources。

npx -y "@kaki-cli/cli@latest" assets smoke-test --url https://example.run.app

如果沒有傳 --url，CLI 會依序使用 local config 的 cloudRunUrl，或用 --project/--region/--service-id 透過 read-only gcloud run services describe 讀取 URL：

npx -y "@kaki-cli/cli@latest" assets smoke-test \
  --project kaki-assets-pilot \
  --region asia-east1 \
  --service-id kaki-assets-web

自動檢查項目：

GET /assetbase-config.js 是否可讀，且 runtime config 是 production intent。
GET /login 是否可開。
GET /dashboard 是否 200 或 redirect 到 /login。
GET /api/admin/status 無 token 時是否回 401。

結尾仍會列出 manual checklist：Firebase Auth authorized domain、Google sign-in、/dashboard / /settings browser flow、最小資料寫入檢查。

Local Config

Kaki Assets 的 reusable non-secret config 規劃放在：

~/.config/kaki/assets.json

可存：

{
  "productId": "assets",
  "projectId": "kaki-assets-pilot",
  "region": "asia-east1",
  "serviceId": "kaki-assets-web",
  "repository": "kaki-assets",
  "imageName": "kaki-assets-web",
  "ghcrOwner": "seanyen0512",
  "runtimeServiceAccount": "[email protected]",
  "cloudRunUrl": "https://example.run.app",
  "lastDeployedTag": "v2.4.2"
}

不可存 secret value，例如 KAKI_ASSETS_SUPER_ADMIN_EMAILS、TWELVE_DATA_API_KEY、GitHub token、service account JSON。

Development

npm install
npm run typecheck
npm test
npm run build
node dist/cli.js assets show-config

若 npm cache 權限錯誤：

npm_config_cache=.npm-cache npm install

更多規範請看 docs/DEVELOPMENT.md 與 docs/ARCHITECTURE.md。