arcrun — AI workflow execution engine (clean history)
Self-hosted 開源：WASM 零件 + recipe + cypher-executor，跑在你自己的 Cloudflare。 此為重建的乾淨歷史起點（移除曾誤 commit 的 GCP SA 金鑰，舊歷史保留在 richblack/arcrun 與本地 backup 分支）。含： - acr init --self-hosted installer（建 KV/R2 + codeload 拉預編譯 wasm + wrangler deploy + seed recipe） - recipe push 把關（資料外流提醒 + 打通檢查） - 19 個正當零件預編譯 wasm（claude_api/km_writer/kbdb_upsert_block 排除：違反 DECISIONS §1） - CLI / cypher-executor / registry / 完整 SDD Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
uncle6me-web
@@ -0,0 +1,381 @@
|
||||
# arcrun — 進度與待辦
|
||||
|
||||
> 設計細節見 `arcrun/README.md`（產品說明）和 `arcrun/BETA_TEST.md`（封測指南）。
|
||||
> 這份文件只記錄：目前狀態、還差什麼、封測能不能啟動。
|
||||
|
||||
---
|
||||
|
||||
## 一、封測目標場景
|
||||
|
||||
封測者是工程師朋友，有自己的網頁，需要後端自動化。目標是他能在 AI 協助下，一次或很少次完成以下完整流程：
|
||||
|
||||
1. `acr init` 取得 api_key
|
||||
2. `acr parts scaffold` 查零件格式，AI 幫寫 workflow YAML
|
||||
3. 若內建零件不足，`acr recipe push` 增加打外部 API 的 recipe
|
||||
4. `acr creds push` 上傳 OAuth token（gmail / google_sheets 等）
|
||||
5. `acr push` 部署 workflow，取得 Webhook URL
|
||||
6. 網頁 POST /webhooks/named/{name}/trigger，結果存 Google Sheets
|
||||
|
||||
---
|
||||
|
||||
## 二、場景各步驟驗證狀態
|
||||
|
||||
### Step 1：acr init → api_key
|
||||
- [x] `acr init` Standard 模式完成，api_key 存入 `~/.arcrun/config.yaml`
|
||||
- [x] 已驗證：`mode: standard, api_key: ak_...` 正確
|
||||
|
||||
### Step 2：acr parts scaffold → AI 看到零件格式
|
||||
- [x] `acr parts` 列出 21 個零件，完全內建，不依賴 registry.arcrun.dev
|
||||
- [x] `acr parts scaffold google_sheets` 輸出 spreadsheet_id / range / operation / values 格式與 credentials.yaml 範本
|
||||
- [x] 已驗證：輸出可直接貼入 YAML
|
||||
|
||||
### Step 3：acr recipe push → 打外部 API
|
||||
- [x] `acr recipe push` 上傳成功，回傳 rec_hash
|
||||
- [x] workflow 使用 `component: rec_xxxxxxxx`，acr push 後 trigger 能正確呼叫外部 API
|
||||
- [x] 已驗證（2026-04-18）：httpbin_post recipe → trigger → httpbin.org/post 回傳正確 ✅
|
||||
|
||||
### Step 4：acr creds push → 自動注入 token
|
||||
- [x] `POST /credentials` API 完成，以 `{api_key}:cred:{name}` 存入 KV
|
||||
- [x] Webhook trigger 時 injectCredentials 從 KV 取得 token 自動注入
|
||||
- [x] `/register` 現在回傳 `encryption_key`，`acr init` 自動存入 config
|
||||
- [x] `acr creds push` 從 config 讀 encryption_key，不再需要手動設定環境變數
|
||||
- [x] 已驗證（2026-04-18）：beta@arcrun.dev 帳號完整流程：init → creds push → trigger → credential 注入成功 ✅
|
||||
|
||||
### Step 5：acr push → Webhook URL
|
||||
- [x] `acr push workflow.yaml` 部署成功，顯示 Webhook URL 和完整 curl 範例
|
||||
- [x] config 中的 `component` / 參數在 push 時套入 graph 節點
|
||||
- [x] 已驗證（2026-04-18）：sheet-test workflow push 成功 ✅
|
||||
|
||||
### Step 6：網頁 POST → 執行 → 結果到 Google Sheets
|
||||
- [x] `POST /webhooks/named/{name}/trigger -H 'X-Arcrun-API-Key: ...'` 觸發執行正常
|
||||
- [x] google_sheets 零件有實作（append row 到 Sheets API）
|
||||
- [x] 已驗證（2026-04-18）：trigger sheet-test → 報「缺少 credential」（符合預期，credential 未上傳）✅
|
||||
- [ ] **未驗證**：真實 google_oauth token + acr creds push → trigger → Google Sheets 實際寫入
|
||||
- 需要真實 OAuth token 才能完整驗證
|
||||
|
||||
---
|
||||
|
||||
## 三、封測啟動阻擋項
|
||||
|
||||
P0 全部清除才啟動封測。
|
||||
|
||||
| # | 項目 | 狀態 | 說明 |
|
||||
|---|------|------|------|
|
||||
| 1 | acr parts scaffold 正確輸出 | ✅ 完成 | 21 個零件內建清單 |
|
||||
| 2 | acr recipe push 端對端 | ✅ 完成 | httpbin_post 驗證通過 |
|
||||
| 3 | acr creds push 代碼 | ✅ 完成 | 需 ARCRUN_ENCRYPTION_KEY |
|
||||
| 4 | credential 注入端對端 | ✅ 完成 | 無 token 時錯誤訊息正確 |
|
||||
| 5 | acr push + webhook trigger | ✅ 完成 | 端對端驗證通過 |
|
||||
| 6 | acr creds push 實測 | ✅ 完成 | /register 回傳 encryption_key，acr init 自動存入 config（CLI 1.0.9）|
|
||||
| 7 | Google Sheets 真實寫入 | ⚠️ 部分驗證 | credential 注入已驗證；實際 Sheets 寫入需真實 OAuth token |
|
||||
| 8 | 第三方服務認證 recipe | ✅ 完成 | 20 個服務（Notion/Slack/GitHub/OpenAI 等），CLI 1.1.0 |
|
||||
| **9** | **cypher-executor outbound HTTP fetch 全失效** | ✅ **已解決 2026-05-13**（CF 同 zone 自循環死鎖，改走 workers.dev）| 詳見下方專段 |
|
||||
| **10** | **multi-node chain context propagation 漏失** | ✅ **已解決 2026-05-13**（ON_SUCCESS/ON_FAIL/IF/ON_CLICK 沒 spread baseCtx）| 詳見下方專段 |
|
||||
|
||||
**目前狀況**：P0 全部解決。
|
||||
- #9 修復方式：component worker URL 從 `*.arcrun.dev`（同 cypher zone）改走 `arcrun-{name}.{WORKER_SUBDOMAIN}.workers.dev`（避開同 zone 自循環）
|
||||
- #10 修復方式：4 個 edge type 補 `{...baseCtx, ...result}`，跟 PIPE/FOREACH 一致
|
||||
|
||||
兩個 P0 解完 mira 7 節點 workflow 端對端通（含真 Claude 16 秒呼叫）。
|
||||
|
||||
---
|
||||
|
||||
### ✅ P0 #9（2026-05-13 已解決）：cypher-executor outbound fetch 全失效
|
||||
|
||||
**完整事件報告（含誤判路徑）**：[docs/incidents/2026-05-13-cypher-outbound-522.md](../../../docs/incidents/2026-05-13-cypher-outbound-522.md)
|
||||
|
||||
**修復方式**：cypher-executor fetch component worker 從 `*.arcrun.dev`（同 zone）改走 `arcrun-{name}.{WORKER_SUBDOMAIN}.workers.dev`。對外 `cypher.arcrun.dev` 不變，用戶 0 感知。
|
||||
|
||||
**改動檔案**（2026-05-13）：
|
||||
- `cypher-executor/src/lib/component-loader.ts`：`wasmWorkerUrl(canonicalId, subdomain)` 簽名加 subdomain 參數 + URL pattern 改 workers.dev
|
||||
- `cypher-executor/src/actions/auth-dispatcher.ts`：同步新簽名
|
||||
- `cypher-executor/src/types.ts`：`Bindings` 加 `WORKER_SUBDOMAIN: string`
|
||||
- `cypher-executor/wrangler.toml`：`[vars]` 加 `WORKER_SUBDOMAIN = "uncle6-me"`
|
||||
- 5 個 component worker 在 dashboard 啟用 workers.dev URL（kbdb-get / kbdb-ingest / kbdb-create-block / kbdb-patch-block / claude-api，**未來新 component 也都要開**）
|
||||
|
||||
**驗證**：cypher-executor → kbdb-get / claude-api 從 522 → 200。mira `acr run wiki_synthesis` 5 節點 workflow 跑通前 3 節點（kbdb_get chain）。
|
||||
|
||||
**Self-hosted fork 注意**：必須改 `wrangler.toml [vars] WORKER_SUBDOMAIN` 為自己的 CF 帳號 subdomain，並把所有 component worker 在 dashboard 啟用 workers.dev URL。
|
||||
|
||||
---
|
||||
|
||||
### ✅ P0 #10（2026-05-13 已解決）：multi-node chain context propagation 漏失
|
||||
|
||||
**現象**：cypher binding workflow 從第 2 個節點開始，原始 input context（top-level `api_key` / `mira_token` 等）丟失，下游節點 `{{api_key}}` 模板原文未替換傳給零件 → 401 Unauthorized 或類似錯。
|
||||
|
||||
**測試重現**：
|
||||
|
||||
```yaml
|
||||
flow:
|
||||
- "input >> ON_SUCCESS >> n1"
|
||||
- "n1 >> ON_SUCCESS >> n2"
|
||||
config:
|
||||
n1: { component: kbdb_get, api_key: "{{api_key}}", block_id: "{{b1}}" }
|
||||
n2: { component: kbdb_get, api_key: "{{api_key}}", block_id: "{{b2}}" }
|
||||
context: { api_key: "ak_xxx", b1: "...", b2: "..." }
|
||||
```
|
||||
|
||||
n1 收到 ctx 含 `api_key / b1 / b2` ✓ → 跑通。
|
||||
n2 收到的 ctx 只有 `n1.output spread`（blocks/count/success/block_id），**`api_key / b1 / b2` 不見**，`{{api_key}}` 原文傳到零件回 401。
|
||||
|
||||
**根因**：`graph-executor.ts` 在 PIPE / FOREACH 邊類型已修「baseCtx ∪ result」，但 **ON_SUCCESS / ON_FAIL / IF / ON_CLICK 四個 edge type 沒套同模式**，直接把 `result` 當下游 ctx 傳，丟掉原始 context。
|
||||
|
||||
**修法**（`cypher-executor/src/graph-executor.ts` line 407 / 415 / 423 / 472）：
|
||||
|
||||
```typescript
|
||||
// 改前
|
||||
result = await this.executeNode(nextNode, graph, result, ...);
|
||||
|
||||
// 改後（同 PIPE/FOREACH 模式）
|
||||
const baseCtx = (typeof context === 'object' && context !== null) ? context as Record<string, unknown> : {};
|
||||
const baseResult = (typeof result === 'object' && result !== null) ? result as Record<string, unknown> : {};
|
||||
const mergedCtx = { ...baseCtx, ...baseResult };
|
||||
result = await this.executeNode(nextNode, graph, mergedCtx, ...);
|
||||
```
|
||||
|
||||
**驗證**：mira `acr run wiki_synthesis` 7 節點 workflow 端對端跑通（16 秒，含真 Claude 呼叫）。每個節點都拿到正確 `api_key` 不再 401。
|
||||
|
||||
**歷史脈絡**：類似問題 2026-05-07 commit e8fca33 在 FOREACH edge 已修一次（"FOREACH preserves outer context"），但當時沒同步處理另外 4 個 edge type。本次補完。
|
||||
|
||||
---
|
||||
|
||||
### ✅ P0 #10 補完三個衍生問題（2026-05-13 晚 ~ 2026-05-14）
|
||||
|
||||
P0 #10 修完後 mira 嘗試做 wiki 多段結構，又踩出三個 cypher binding 設計缺陷。**都是同一天解掉**。
|
||||
|
||||
#### A. interpolateData() 不遞迴 nested object
|
||||
|
||||
**現象**：`set` / `kbdb_create_block` 的 `values: { text: "{{classify.data.text}}" }`、`tags_json: ["facet:{{paragraph.facet}}"]` 等 nested config 內的 `{{x}}` 不被替換，原文傳給零件。
|
||||
|
||||
**根因**：`interpolateData()` 只 iterate top-level，對非 string 值（object / array）直接 pass-through 不下沉。
|
||||
|
||||
**修法**：拆 `interpolateString` + `interpolateValue`（遞迴 object / array），`interpolateData` 改 call `interpolateValue`。
|
||||
|
||||
**測試**：`set values: { text: "hello {{name}}", arr: ["item {{name}}"] }` 帶 `name=world` → 全展開。
|
||||
|
||||
#### B. ctx 沒存上游 output 的 node id namespace
|
||||
|
||||
**現象**：`{{classify.data.text}}` 找不到上游 classify 的 output；只能用 `{{data.text}}`（直接 spread 取），但會被下個節點覆蓋，多節點 chain 用不了。
|
||||
|
||||
**根因**：`propagateCtx` 只把上游 result spread 進 ctx，沒額外存 `[node.id]: result`。
|
||||
|
||||
**修法**：`propagateCtx` 改回傳 `{ ...baseCtx, ...baseResult, [upstreamNodeId]: upstreamResult }`。讓下游能用 `{{node_id.data.text}}` 從 namespace 取，永不被覆蓋。
|
||||
|
||||
**測試**：5 節點 chain 用 `{{load_schema.blocks.0.content}}` / `{{classify.data.text}}` 全展開。
|
||||
|
||||
#### C. FOREACH 找 iterable 只看 result，不看 ctx + 不看 nested
|
||||
|
||||
**現象**：mira wiki_synthesis 雙重 FOREACH（外層 `對每個 paragraph`、內層 `對每個 triplet`），外層 OK，內層跑 0 次。
|
||||
|
||||
**根因 (C1)**：`getIterableFromContext(result, key)` 只看當前節點 output。`result` 是 `create_paragraph` output（`{data, success}`），不含 paragraphs。但 `paragraphs` 早就在 ctx 從 classify spread 來。
|
||||
|
||||
**根因 (C2)**：當外層 FOREACH 把 `paragraph` item 注入 ctx，內層 FOREACH 要找 `paragraph.triplets`。`getIterableFromContext` 只看 top-level，看不到 `paragraph` 物件裡的 `triplets`。
|
||||
|
||||
**修法**：
|
||||
- (C1) FOREACH `result` 找不到 iterable → fallback 找 `context`
|
||||
- (C2) `getIterableFromContext` 加一輪「掃 ctx 內每個 object 找 nested key」
|
||||
|
||||
**測試**：mira wiki_synthesis 3 層樹（wiki-page → paragraphs → triplets）端對端跑通，KBDB 內驗證 `物理 AI` wiki 有 2 段 paragraph + 4 個 triplet，parent_id 正確接到對應 paragraph。
|
||||
|
||||
#### Edge type 一致化
|
||||
|
||||
抽 `propagateCtx(context, result, upstreamNodeId)` helper，5 個 edge type（PIPE / ON_SUCCESS / ON_FAIL / IF / ON_CLICK / FOREACH）全部用同一 function 組下游 ctx。**未來新 edge type 必須用這 helper**，避免再漏。
|
||||
|
||||
#### CLI validator 同步
|
||||
|
||||
`cli/src/lib/yaml-parser.ts` validateRelations 加 regex 支援 `對每個 X` / `FOREACH X` 迭代器命名（之前 validator 字串完全比對擋住，但 graph-builder 執行端早已支援）。
|
||||
|
||||
---
|
||||
|
||||
### 三-A、P1 待改進（不擋封測，但 mira 已踩到）
|
||||
|
||||
#### ✅ P1 #3：cypher-executor `scheduled()` handler（2026-05-14 完成）
|
||||
|
||||
**原痛點**：cron 零件只做 expression validation；cypher-executor 沒 `scheduled()` handler。寫了 cron 首節點的 workflow 不會真的跑。
|
||||
|
||||
**之前的 workaround**（已撤）：mira 寫了個 `/mira/wiki-from-raw` route 從前端 fire-and-forget 觸發 wiki_synthesis。但這違反「一律 arcrun-native」原則，也讓 arcrun 永遠補不齊缺失。**已刪 route，回 arcrun-native 路線**。
|
||||
|
||||
**落地**：
|
||||
1. `wrangler.toml`：`[triggers] crons = ["* * * * *"]`（每分鐘 tick）
|
||||
2. `src/lib/cron-match.ts`：5 欄位 cron expression matcher（支援 `*` / `N` / `*/N` / `1-5` / `5,10` 組合）
|
||||
3. `src/scheduled.ts`：scheduled handler 掃 KV `cron-idx:` prefix，比對 controller.scheduledTime，匹配就 `executeWebhookGraph` 背景跑
|
||||
4. `routes/webhooks-named.ts`：acr push 偵測首節點是 cron 零件 → 抽 `cron_expr` 存進 record + 額外寫 `cron-idx:{api_key}:{name}` 輕量 index entry。DELETE 一併清理
|
||||
5. `src/index.ts`：export default 改 `{ fetch, scheduled }`
|
||||
6. cypher-executor 自己加 `workers_dev = true` 給未來 self-trigger 用（fork 用 path-based 子 trigger 也走 workers.dev 避同 zone）
|
||||
|
||||
**workflow YAML 慣例**：
|
||||
```yaml
|
||||
flow:
|
||||
- "my_cron >> ON_SUCCESS >> downstream_node"
|
||||
config:
|
||||
my_cron:
|
||||
component: cron
|
||||
cron_expr: "*/5 * * * *" # 每 5 分鐘
|
||||
```
|
||||
acr push 就會自動建立 cron-idx 並開始定時觸發。
|
||||
|
||||
**測試**：`tests/arcrun-test/cron_heartbeat.yaml` — 每分鐘 fire 一次 + set 節點 log。
|
||||
`wrangler tail arcrun-cypher-executor` 應看 `[scheduled] trigger cron_heartbeat ...`。
|
||||
|
||||
**對應 use case**：mira `mira_feed_watcher`（7B.3h，下一輪做）/ RSS 每日抓 / voice-stt 每小時掃 / 等所有 cron-driven source。
|
||||
|
||||
---
|
||||
|
||||
#### P1 #1：workflow 缺 IF/branch 能力（2026-05-14 mira 7B.3f 提出）
|
||||
|
||||
**現象**：mira 想做「找有則 PATCH 沒則 CREATE」（index-entry upsert），arcrun 目前只有 `ON_SUCCESS` + `對每個 X`（FOREACH）+ 已存在但壞掉的 `if_control`（見已知限制 #1），沒有 `>> ON_TRUE >>` / `>> ON_FALSE >>` 條件路由。
|
||||
|
||||
**短期 workaround**（已採用，2026-05-14）：建 `kbdb_upsert_block` 零件，把分支邏輯封進零件內部（GET by page_name → 找到 PATCH 沒找到 POST）。caller 看到的是單純的 upsert 介面。
|
||||
|
||||
**長期解**：升 `if_control` false branch 路由 / 加 `>> ON_TRUE >>` edge type，讓 workflow 層可表達分支。對未來所有「找則改否則建」/「條件分流」場景都會撞到，不只 mira。
|
||||
|
||||
**位置**：cypher-executor/src/graph-executor.ts edge type 處理（5 個 edge type 抽出 `propagateCtx` 後新增 IF 應該不難）+ cli/src/lib/yaml-parser.ts validator。
|
||||
|
||||
---
|
||||
|
||||
#### P0 #11（2026-05-14 已解決）：interpolateString stringify array 撐爆下游
|
||||
|
||||
**現象**：mira_feed_watcher 用 `items: "{{list_raws.blocks}}"` 把 kbdb_get 拿到的 blocks 陣列傳給 filter 零件。watcher 跑 264ms 完成、0 raw 處理。
|
||||
|
||||
**根因**：`interpolateString` 看到模板就用 `String.replace`，非 string 值（陣列）一律 `JSON.stringify`。filter 零件收到字串 `"[{...},{...}]"` 不是 array，items 被忽略 → 0 matches → FOREACH 跑 0 次。
|
||||
|
||||
**修法**：`interpolateString` 加 single-ref pass-through 規則：若整個值是純單一 `{{x}}` 引用，回 raw value（保留 array / object 型別）。多 ref / 混合文字仍 stringify 拼接字串。
|
||||
|
||||
**測試**：mira_feed_watcher 推到 prod 後下一個 cron tick 觀察 wiki-processed tag 是否在 raws 上出現。
|
||||
|
||||
---
|
||||
|
||||
### 三-B、新零件加入紀錄
|
||||
|
||||
| 日期 | 零件 | 動機 | 對應 SDD |
|
||||
|---|---|---|---|
|
||||
| 2026-05-14 | `kbdb_upsert_block` | mira 7B.3f index-entry per-entity upsert，繞過 workflow 缺 IF/branch 能力（P1 #1）。內部 GET by page_name → 找到 PATCH 沒找到 POST。page_name 當 idempotency key。 | polaris/mira/.agents/specs/mira-app/design.md §3.5.12.4.1 |
|
||||
|
||||
**新零件 checklist（避免 P1 #1 重蹈 kbdb_upsert_block 漏白名單覆轍）**：
|
||||
|
||||
每加一個 API/data 零件（不是 logic primitive），都要：
|
||||
- [ ] `registry/components/{name}/main.go` + `component.contract.yaml` + `go.mod`
|
||||
- [ ] `tinygo build -target=wasi` 通
|
||||
- [ ] `.component-builds/{name}/` 完整 4 檔（`wrangler.toml` 含 `workers_dev = true` + `pnpm-lock.yaml` + `tsconfig.json` + `src/index.ts`）
|
||||
- [ ] **`cypher-executor/src/lib/component-loader.ts` 的 `WASM_HTTP_RUNNER_IDS` 加 canonical_id**（漏這條 cypher-executor 永遠拋「找不到零件」，端對端會死靜悄悄）
|
||||
- [ ] `acr validate workflow.yaml` 通
|
||||
- [ ] 直接 curl `https://{kebab}.arcrun.dev` + `https://arcrun-{kebab}.{WORKER_SUBDOMAIN}.workers.dev` 都 200
|
||||
|
||||
---
|
||||
|
||||
### 三-C、P1 #2：workers_dev = true 全 component 自動化（2026-05-14 已收）
|
||||
|
||||
**原痛點**：每新部署一個 component worker，要去 CF Dashboard 手動 Enable workers.dev URL，否則 cypher-executor fetch 該 worker 會 404。
|
||||
|
||||
**解**：32 個 `.component-builds/*/wrangler.toml` 全部加 `workers_dev = true`。CI 每次 deploy 自動啟用對應 workers.dev URL，零手動。
|
||||
|
||||
**未來新 component**：模板 (`component-worker-template/`) 應該預設帶 `workers_dev = true`，新人 fork 不會踩。已列入「新零件 checklist」第 3 條。
|
||||
|
||||
**為何不走 `*.acr-comp.uncle6.me` 自訂 zone**：CF Universal SSL 只發一層子域，sub-sub `*.acr-comp.uncle6.me` 不蓋；要 ACM ($10/月) 才能簽。違反 arcrun「fork 後 self-host 用 free tier 跑得起來」核心目標。workers_dev=true 走 CF 默認的 workers.dev cert，free tier OK，更乾淨。
|
||||
|
||||
---
|
||||
|
||||
### 原 P0 #9 調查紀錄（保留作歷史參考）
|
||||
|
||||
**現象**：cypher-executor 的 `makeHttpRunner` (`cypher-executor/src/lib/component-loader.ts:142`) 對任何 outbound URL fetch 都回 CF **522 (origin timeout, ~1000ms)**。
|
||||
|
||||
**測試矩陣**（mira repo `polaris/mira/arcrun/wiki_synthesis.yaml` 端對端壓測時發現）：
|
||||
|
||||
| 路徑 | 結果 | 證明 |
|
||||
|---|---|---|
|
||||
| 本機 curl → kbdb-get.arcrun.dev | 200 (22ms) | KBDB worker 本身健康 |
|
||||
| cypher-executor → kbdb-get.arcrun.dev (HTTP) | **522** (1002ms) | outbound HTTP fetch 壞 |
|
||||
| cypher-executor → claude-api.arcrun.dev (HTTP) | **522** | 同 zone 也壞 |
|
||||
| cypher-executor → httpbin.org (外部) | **522** | 不只是 same-account loop |
|
||||
| cypher-executor → string_ops (Service Binding) | 200 ✅ | SVC_* 路徑正常 |
|
||||
| acr run hello (built-in via SB) | ✅ | hello.yaml 仍跑得通 |
|
||||
|
||||
**衍生小 bug**：`set` 零件 input schema 變了（要 `assignments` 陣列或 `values` 物件，不是 `value`）。tests/arcrun-test/hello.yaml 跑 string_ops 沒踩到。
|
||||
|
||||
**影響範圍（封測啟動阻擋）**：
|
||||
|
||||
- 任何用戶 workflow 含 outbound HTTP 都壞：
|
||||
- 用戶 `acr recipe push` 後 trigger → 打外部 API 全 522（推翻 P0 #2 4/18 紀錄）
|
||||
- 用戶要存資料進 arcrun 內建 KBDB → 522（mira 7B.3c 卡這裡）
|
||||
- 任何 auth primitive 走獨立 Worker URL 路徑 → 522
|
||||
- Google Sheets 寫入 → 522（推翻 P0 #7「待真實 OAuth 驗證」評估，根本還沒到 OAuth 步驟就壞）
|
||||
- 只有「全內建邏輯零件 + 純 service binding」workflow 還能跑
|
||||
|
||||
**根因（2026-05-13 確認）：5/8-5/9 9 次 manual `wrangler deploy` 把含 WIP bug 的 cypher-executor 推上 prod**
|
||||
|
||||
調查路徑（按時序）：
|
||||
|
||||
1. 一開始懷疑 free tier CPU cap（10ms / invocation）→ 對照測試「5 節點 SB chain」跑了 2.2 秒卻通過，**推翻**
|
||||
2. 換懷疑 CF zone 規則 / Bot Fight Mode → dashboard bindings 乾淨無攔截，**推翻**
|
||||
3. 用戶補繳費恢復 Workers Paid → 重測仍全 522，**徹底排除付費假設**
|
||||
4. 看 dashboard Version History：5/8 4 次 + 5/9 5 次 = **9 次 manual `wrangler deploy by uncle6.me`**
|
||||
5. 對照 GitHub Actions：4/24 後完全沒 deploy（最後是 commit e222116 `fix(wasi-shim)`）
|
||||
6. 對照 git：本機 main **領先 origin/main 3 commits 未 push**，含：
|
||||
- `497f92a feat(arcrun): recipe system + resumable workflow + component registry canon`
|
||||
- `e8fca33 feat(cypher): 3-node wiki workflow end-to-end (FOREACH + nested interp + unified parsing)`
|
||||
- `519423c feat(arcrun): mira wiki page with tag filter + accumulated WIP`（自描含 `cypher-executor: auth-dispatcher / wasi-shim adjustments (WIP)`）
|
||||
|
||||
**結論**：那 9 次 manual deploy 把上面 3 個 unpushed commit 的 cypher-executor 改動推上 prod，其中至少一個改動破壞了 outbound fetch（最可能是 519423c WIP 內的 wasi-shim / auth-dispatcher 改動）。GitHub Actions 因為沒 push 沒跑，CI 沒 catch，4/18-4/24 那段 SDD「驗證通過」的紀錄是 truth，現在 prod 是壞的版本。
|
||||
|
||||
**為何 SB 路徑沒事 / HTTP 路徑全死**：SB 走 cypher-executor 內部 service binding API（`env.SVC_X.fetch()`），不經過 outbound HTTP code path。HTTP 路徑走 `makeHttpRunner` (component-loader.ts:142) 的 `fetch(url, ...)`，這條路被 WIP code 弄壞。具體壞在哪要 diff 那 3 個 commit 的 cypher-executor 改動才知道。
|
||||
|
||||
**驗證 wrangler tail 證據**：trigger 任何 outbound HTTP 的 graph，cypher-executor 自己 `wallTime: 497ms, cpuTime: 2ms, outcome: ok`、無 logs、無 exceptions。代表 cypher-executor 把「fetch 失敗的 522 response」當作 component 正常輸出包回 client，自己沒撞任何錯。
|
||||
|
||||
**解法（三選一）**：
|
||||
|
||||
- **A. Rollback prod 到 4/24 的 e222116** — CF dashboard → arcrun-cypher-executor → Deployments → 找 4/24 那筆 → Rollback。5 分鐘恢復 outbound fetch，丟失 wiki workflow / recipe / resumable 等 cypher 端 WIP 改動（但前端、registry components、KBDB blocks 都不丟，因為它們是別的 worker / 別的儲存）。**richblack 操作。**
|
||||
- **B. Diff 3 個 unpushed commit 找出壞掉的改動修掉** — 不丟功能，但要動 src code 走 SDD 協議，30min - 數小時。
|
||||
- **C. 架構切換**（mira 老闆 2026-05-13 提的）：sub-workflow 自殺交棒模式，cypher-executor 不再做集中 graph executor。從根本繞開「cypher-executor 一個 invocation 跑長 graph」這條脆弱路徑。一勞永逸但是大改。
|
||||
|
||||
**衍生小 bug 仍要修**（跟付費無關）：`set` 零件 input schema 變了（要 `assignments` 陣列或 `values` 物件，不是 `value`）。要嘛 update set 零件 contract 容錯，要嘛文件化新 schema。
|
||||
|
||||
**為什麼這直接擋封測**：
|
||||
|
||||
封測場景 Step 6「網頁 POST → 結果存 Google Sheets」走 google_sheets 零件 (HTTP outbound to googleapis.com)。如果 cypher-executor outbound 全壞，**封測者跑任何含外部 API 的 workflow 都會 522**，不是「Google Sheets 實際寫入未驗證」級別的小事。
|
||||
|
||||
**也直接擋 mira**：[polaris/mira/.agents/specs/mira-app/tasks.md] 7B.3c-f（wiki 合成 workflow）卡這裡。
|
||||
|
||||
---
|
||||
|
||||
## 四、封測前 P3（啟動當天）
|
||||
|
||||
- [ ] 用封測者 email 呼叫 `/register`，取得 api_key
|
||||
- [ ] 將 ARCRUN_ENCRYPTION_KEY 以安全方式提供給封測者
|
||||
- [ ] 確認聯絡管道
|
||||
|
||||
---
|
||||
|
||||
## 五、已知限制（封測期間不修）
|
||||
|
||||
1. `if_control` false branch 不路由（條件 false 時後續節點不執行）→ 升級計畫見 P1 #1，2026-05-14 mira 用 `kbdb_upsert_block` workaround
|
||||
2. 多節點 context 不自動解包（上游輸出 flat merge，下游需從 `data.result` 取值）
|
||||
3. 用戶自製邏輯零件（Phase 5）封測後才實作
|
||||
|
||||
---
|
||||
|
||||
## 六、實作進度
|
||||
|
||||
| Phase | 內容 | 狀態 |
|
||||
|-------|------|------|
|
||||
| 0 | Workers 部署、CI/CD、DNS | ✅ |
|
||||
| 1 | CLI 基礎（init / validate / run / parts） | ✅ |
|
||||
| 2 | /register、/cypher/execute、21 個零件 | ✅ |
|
||||
| 3 | Service Binding 架構、{{variable}} 插值、ON_FAIL 修正 | ✅ |
|
||||
| 4 | 動態 Recipe KV（CRUD）、acr recipe 指令 | ✅ |
|
||||
| 5 | 用戶自製邏輯零件（WASM push） | ⏸ 封測後 |
|
||||
| 6 | Credential 多租戶（{api_key}:cred:{name}）、acr creds push | ✅ |
|
||||
| 7 | acr parts 內建清單、acr parts scaffold | ✅ |
|
||||
| 8 | /webhooks/named、acr push 改版、config 套入 graph | ✅ |
|
||||
|
||||
### CLI 版本
|
||||
|
||||
| 版本 | 變更 |
|
||||
|------|------|
|
||||
| 1.1.0 | auth recipe 系統：20 個服務預建（Notion/Slack/GitHub/OpenAI/Google SA 等）；acr auth-recipe 指令 |
|
||||
| 1.0.9 | /register 回傳 encryption_key；acr init 自動儲存；creds push 不需手動設環境變數 |
|
||||
| 1.0.8 | acr push → webhooks/named；config 套入 graph；acr parts 內建清單 |
|
||||
| 1.0.7 | acr creds push → POST /credentials |
|
||||
| 1.0.6 | acr recipe push / list / delete |
|
||||
| 1.0.5 | hello.yaml 改 string_ops，--version 修正 |
|
||||
| 1.0.4 | config/context 分離 |
|
||||
| 1.0.3 | 初始發布 |
|
||||
@@ -0,0 +1,274 @@
|
||||
# Auth Recipe System — SDD
|
||||
|
||||
> 文件類型：SDD（Software Design Document）
|
||||
> 建立：2026-04-19
|
||||
> 狀態：實作中
|
||||
|
||||
---
|
||||
|
||||
## 一、目標
|
||||
|
||||
封測前完成，讓封測者碰到「我要連 X 服務」都有辦法，而不是「還沒做」。
|
||||
|
||||
**精神**：`http_request` 是容器零件，auth recipe 是「如何對這個服務認證」的設定層，兩者分離。新增一個服務 = 寫一份 YAML，不需要改程式碼、不需要重新部署 Worker。
|
||||
|
||||
---
|
||||
|
||||
## 二、三層模型
|
||||
|
||||
```
|
||||
Layer 3: Auth Recipe (YAML/JSON in RECIPES KV)
|
||||
公共，描述「如何對某服務認證」
|
||||
key: auth_recipe:{service}
|
||||
例: auth_recipe:notion, auth_recipe:slack
|
||||
↓ 引用
|
||||
Layer 2: Auth Primitive (TypeScript in Worker)
|
||||
四個通用認證邏輯：static_key | oauth2 | service_account | mtls
|
||||
封測只做 static_key 和 service_account (Google JWT)
|
||||
↑ 使用
|
||||
Layer 1: Tenant Secret (CREDENTIALS_KV)
|
||||
每個 tenant 自己的加密 credential
|
||||
key: {api_key}:cred:{name}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、Auth Recipe Schema
|
||||
|
||||
```typescript
|
||||
interface AuthRecipeDefinition {
|
||||
kind: 'auth_recipe'; // 區別 RecipeDefinition 用
|
||||
service: string; // canonical_id, e.g. "notion"
|
||||
version: number;
|
||||
primitive: 'static_key' | 'oauth2' | 'service_account' | 'mtls';
|
||||
base_url: string;
|
||||
display_name?: string;
|
||||
description?: string;
|
||||
|
||||
// service_account 用
|
||||
service_account_kind?: 'google_jwt';
|
||||
token_exchange?: {
|
||||
endpoint: string; // e.g. https://oauth2.googleapis.com/token
|
||||
scopes: string[];
|
||||
};
|
||||
|
||||
required_secrets: Array<{
|
||||
key: string; // CREDENTIALS_KV 的名稱
|
||||
label: string; // UI/CLI 顯示
|
||||
type?: 'string' | 'json_blob'; // default: string
|
||||
help?: string;
|
||||
help_url?: string;
|
||||
}>;
|
||||
|
||||
inject: {
|
||||
header?: Record<string, string>; // "Authorization": "Bearer {{secret.token}}"
|
||||
query?: Record<string, string>;
|
||||
body?: Record<string, string>;
|
||||
// path：注入 endpoint URL path 的 secret（2026-05-29 加）。
|
||||
// 解 telegram 類「token 在 URL path」（/bot{token}/）—— header/query/body 都不適用。
|
||||
// key = 模板變數名，API recipe 的 endpoint 用 {{auth.K}} 引用。
|
||||
// 例：auth_recipe:telegram inject.path = { bot_token: "{{secret.telegram_bot_token}}" }
|
||||
// recipe:telegram_send endpoint = "https://api.telegram.org/bot{{auth.bot_token}}/sendMessage"
|
||||
path?: Record<string, string>;
|
||||
};
|
||||
|
||||
created_at: number;
|
||||
updated_at: number;
|
||||
}
|
||||
```
|
||||
|
||||
**Template 語法**：
|
||||
- `{{secret.KEY}}` → 從 tenant 的 CREDENTIALS_KV 解密取值
|
||||
- `{{runtime.access_token}}` → service_account JWT exchange 後取得的短期 token
|
||||
|
||||
---
|
||||
|
||||
## 四、KV 儲存
|
||||
|
||||
沿用現有 `RECIPES` KV namespace，不新增 binding。
|
||||
|
||||
```
|
||||
auth_recipe:{service} → AuthRecipeDefinition JSON
|
||||
```
|
||||
|
||||
與現有 `recipe:{id}` / `idx:{hash}` 的 key 不衝突。
|
||||
|
||||
---
|
||||
|
||||
## 五、執行流程
|
||||
|
||||
### 5.1 static_key（涵蓋 ~80% 服務）
|
||||
|
||||
```
|
||||
trigger → graph-executor
|
||||
→ injectCredentials(componentId, input, env, apiKey)
|
||||
→ resolveAuthRecipe("notion", RECIPES KV)
|
||||
→ 取得 required_secrets: [{key: "notion_token", ...}]
|
||||
→ 從 CREDENTIALS_KV 讀 "{api_key}:cred:notion_token"
|
||||
→ AES-GCM 解密
|
||||
→ 展開 inject.header templates ({{secret.notion_token}} → 實際值)
|
||||
→ 注入 _auth_headers, _auth_query, _auth_body 到 input
|
||||
→ makeAuthRecipeRunner(recipe)
|
||||
→ 合併 _auth_headers 到 fetch headers
|
||||
→ 呼叫 recipe.base_url + input._path
|
||||
→ 回傳結果
|
||||
```
|
||||
|
||||
### 5.2 service_account（Google 家族）
|
||||
|
||||
```
|
||||
injectCredentials
|
||||
→ resolveAuthRecipe("google_sheets_sa", RECIPES KV)
|
||||
→ 解密 service_account_json (JSON blob)
|
||||
→ signGoogleJwt(serviceAccountJson, scopes) via crypto.subtle (RSASSA-PKCS1-v1_5 + SHA-256)
|
||||
→ POST token_exchange.endpoint → 取得 access_token
|
||||
→ 展開 inject.header: { Authorization: "Bearer {{runtime.access_token}}" }
|
||||
→ 注入 _auth_headers
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、Context key 慣例
|
||||
|
||||
注入後的認證資訊以 `_auth_` 前綴攜帶，不污染業務欄位：
|
||||
|
||||
| Key | 說明 |
|
||||
|---|---|
|
||||
| `_auth_headers` | `Record<string, string>` — 要合併進 fetch headers |
|
||||
| `_auth_query` | `Record<string, string>` — 要附加到 URL query string |
|
||||
| `_auth_body` | `Record<string, string>` — 要合併進 request body |
|
||||
| `_auth_path` | `Record<string, string>` — endpoint URL path 用（2026-05-29 加）。`makeRecipeRunner` 的 endpoint interpolate 用 `{{auth.K}}` 從這裡取值 |
|
||||
|
||||
`makeAuthRecipeRunner` / `makeRecipeRunner` 在發出 fetch 前讀取這些 `_auth_*` 欄位，
|
||||
之後從 auto-body 中剔除所有 `_` 前綴欄位（不洩漏給下游）。
|
||||
|
||||
## 七、API recipe 的 auth_service（多 recipe 共用一把 auth，2026-05-29 加）
|
||||
|
||||
`RecipeDefinition` 加 `auth_service?: string` 欄位：API recipe **自報它屬於哪個服務**，
|
||||
auth-dispatcher 用它查 `auth_recipe:{auth_service}`，而非假設 componentId == service name。
|
||||
|
||||
- 讓多個 recipe 共用同一把 auth：`recipe:kbdb_get` / `kbdb_create_block` 都設 `auth_service: "kbdb"`
|
||||
→ 共用唯一的 `auth_recipe:kbdb`，加新 action 不必複製 auth recipe。
|
||||
- auth-dispatcher 解析順序：先查 `recipe:{componentId}` 拿 `auth_service`，有就用它；
|
||||
沒有則 fallback 把 componentId 當 service name（向後相容舊行為）。
|
||||
- 這是「服務身分標籤」非「許可清單」：auth_recipe 只定義「怎麼認證」，不含「誰准用」。
|
||||
授權由發 API key 的服務裁決，arcrun 不做內部授權判斷（見 DECISIONS.md「arcrun 不做授權判斷」）。
|
||||
|
||||
---
|
||||
|
||||
## 七、向後相容
|
||||
|
||||
- 現有 `BUILTIN_API_RECIPES`（gmail, google_sheets, telegram, line_notify）**不動**
|
||||
- 現有 `BUILTIN_CREDENTIALS_MAP` **不動**
|
||||
- auth recipe 解析在 component-loader step 5.5（新增），在 step 6 KV recipe 和 step 7 builtin 之前
|
||||
- 若 `auth_recipe:{service}` 不存在 → 繼續往下走，行為與現在完全相同
|
||||
|
||||
---
|
||||
|
||||
## 八、新增/修改的檔案
|
||||
|
||||
| 檔案 | 類型 | 說明 |
|
||||
|---|---|---|
|
||||
| `cypher-executor/src/routes/recipes.ts` | 修改 | 加 `AuthRecipeDefinition` 型別、`resolveAuthRecipe`、`/auth-recipes` CRUD routes |
|
||||
| `cypher-executor/src/actions/credential-injector.ts` | 修改 | 加 auth recipe 分支：static_key + service_account |
|
||||
| `cypher-executor/src/lib/jwt-signer.ts` | 新增 | Google JWT signing via crypto.subtle |
|
||||
| `cypher-executor/src/lib/component-loader.ts` | 修改 | step 5.5 auth recipe lookup + `makeAuthRecipeRunner` |
|
||||
| `cypher-executor/src/lib/auth-recipe-seeds.ts` | 新增 | 20 個常用服務的 auth recipe 定義 |
|
||||
| `cli/src/commands/auth-recipe.ts` | 新增 | `acr auth-recipe list/info/scaffold` |
|
||||
| `cli/src/commands/parts.ts` | 修改 | `cmdPartsScaffold` fallback 到 auth recipe |
|
||||
| `cli/src/index.ts` | 修改 | 註冊 auth-recipe 指令 |
|
||||
|
||||
---
|
||||
|
||||
## 九、封測前預計的 Auth Recipe 清單（20 個）
|
||||
|
||||
### static_key 類（~80% 服務）
|
||||
|
||||
| service | 認證方式 | credential key |
|
||||
|---|---|---|
|
||||
| `notion` | Bearer token (header) | `notion_token` |
|
||||
| `slack` | Bot Token (Bearer) | `slack_bot_token` |
|
||||
| `github` | PAT (Bearer) | `github_token` |
|
||||
| `openai` | API key (Bearer) | `openai_api_key` |
|
||||
| `anthropic` | API key (x-api-key) | `anthropic_api_key` |
|
||||
| `airtable` | PAT (Bearer) | `airtable_token` |
|
||||
| `discord` | Bot token ("Bot TOKEN") | `discord_bot_token` |
|
||||
| `stripe` | Secret key (Bearer) | `stripe_secret_key` |
|
||||
| `twilio` | AccountSid + AuthToken (Basic Auth) | `twilio_account_sid`, `twilio_auth_token` |
|
||||
| `sendgrid` | API key (Bearer) | `sendgrid_api_key` |
|
||||
| `hubspot` | Private App token (Bearer) | `hubspot_token` |
|
||||
| `linear` | API key (Bearer) | `linear_api_key` |
|
||||
| `shopify` | Admin API token (X-Shopify-Access-Token) | `shopify_access_token` |
|
||||
| `resend` | API key (Bearer) | `resend_api_key` |
|
||||
| `supabase` | Service role key (Bearer + apikey) | `supabase_service_key` |
|
||||
| `typeform` | PAT (Bearer) | `typeform_token` |
|
||||
| `jira` | API token + email (Basic Auth) | `jira_api_token`, `jira_email` |
|
||||
|
||||
### service_account 類（Google 家族，JWT signing）
|
||||
|
||||
| service | scopes | credential key |
|
||||
|---|---|---|
|
||||
| `google_sheets_sa` | spreadsheets | `google_service_account` |
|
||||
| `google_gmail_sa` | gmail.send | `google_service_account` |
|
||||
| `google_drive_sa` | drive | `google_service_account` |
|
||||
|
||||
> 注意：三個 Google 服務可共用同一個 `google_service_account` credential，只是 scope 不同。
|
||||
|
||||
---
|
||||
|
||||
## 十、實作進度
|
||||
|
||||
### Server (cypher-executor)
|
||||
|
||||
- [x] `AuthRecipeDefinition` 型別 + `resolveAuthRecipe`
|
||||
- [x] `/auth-recipes` CRUD routes
|
||||
- [x] `injectFromAuthRecipe` — static_key primitive
|
||||
- [x] `lib/jwt-signer.ts` — Google JWT via crypto.subtle
|
||||
- [x] `injectFromAuthRecipe` — service_account primitive
|
||||
- [x] `makeAuthRecipeRunner` in component-loader
|
||||
- [x] step 5.5 in createComponentLoader
|
||||
- [x] auth-recipe-seeds.ts (20 services)
|
||||
- [x] seed script / deploy seeds to KV（2026-04-19 全部 ✅）
|
||||
|
||||
### CLI (arcrun)
|
||||
|
||||
- [x] `commands/auth-recipe.ts` — list / info / scaffold
|
||||
- [x] 更新 `commands/parts.ts` — scaffold fallback
|
||||
- [x] 更新 `index.ts` — 註冊指令
|
||||
- [x] 版本升 1.1.0
|
||||
- [x] npm publish（arcrun@1.1.0）
|
||||
|
||||
### 驗證
|
||||
|
||||
- [ ] notion (static_key) 端對端
|
||||
- [ ] google_sheets_sa (service_account) 端對端
|
||||
- [ ] 舊有 google_sheets builtin 向後相容確認
|
||||
|
||||
---
|
||||
|
||||
## 十一、長期演進：TinyGo WASM Primitive（封測後）
|
||||
|
||||
> 參考：`docs/user_requirements/arcrun/credential_parts.md`
|
||||
|
||||
**目前封測版**：Layer 2 primitive 邏輯在 `cypher-executor` TypeScript 中實作（`credential-injector.ts`）。
|
||||
|
||||
**長期目標**：四個 primitive 各自編譯為獨立 TinyGo WASM，取代現有 TS 實作：
|
||||
|
||||
```
|
||||
arcrun/registry/components/auth_static_key/ ← TinyGo WASM
|
||||
arcrun/registry/components/auth_oauth2/ ← TinyGo WASM
|
||||
arcrun/registry/components/auth_service_account/ ← TinyGo WASM
|
||||
arcrun/registry/components/auth_mtls/ ← TinyGo WASM
|
||||
```
|
||||
|
||||
每個 primitive 實作統一 interface（`Authenticate` / `NeedsRefresh` / `Refresh` / `Test`）。
|
||||
切換時 `cypher-executor` 的 `injectFromAuthRecipe` 改為呼叫對應 WASM，邏輯不變。
|
||||
|
||||
**何時做**：封測驗證完成、TinyGo crypto 支援確認後（特別是 RS256/ES256 JWT signing）。
|
||||
在此之前，**不建立任何 TypeScript SDK 或 Python SDK 來包裝 credential 邏輯**。
|
||||
|
||||
### 禁止的做法
|
||||
|
||||
- ❌ 建立 `js-sdk/`、`python-sdk/` 包裝 credential 加解密
|
||||
- ❌ 在 client 端重實作 AES-GCM encrypt/decrypt
|
||||
- ❌ 用 TypeScript 重寫已計劃用 TinyGo 實作的 primitive 邏輯
|
||||
@@ -0,0 +1,178 @@
|
||||
# Design Document: Credential Primitives TS → WASM 改寫
|
||||
|
||||
## Overview
|
||||
|
||||
將 `cypher-executor` 中以 TypeScript 實作的 credential 注入邏輯，改寫為 4 個獨立的 WASM 零件。這是 `credential_parts.md` 長期規格的實現，不再是「未來 Phase」。
|
||||
|
||||
**動機**：TS 實作無法在地端（workerd）和邊緣端（Wazero）執行。WASM 零件跨 runtime 可攜，符合 u6u 三層部署架構。
|
||||
|
||||
**嚴格規範（richblack 2026-04-19 確認）**：cypher-executor TS **完全不實作**任何 credential / auth / template / JWT / 解密邏輯。所有業務邏輯必須在 TinyGo WASM 零件內。TS 僅負責 HTTP routing + 呼叫 WASM + host function 提供 runtime primitive（crypto.subtle / KV / fetch）。
|
||||
|
||||
---
|
||||
|
||||
## 現有 TS 實作（要刪除的）
|
||||
|
||||
| 檔案 | 功能 | 對應 WASM Primitive |
|
||||
|------|------|---------------------|
|
||||
| `credential-injector.ts` — `injectFromAuthRecipe()` | static_key template 展開 | `auth_static_key` |
|
||||
| `credential-injector.ts` — service_account 分支 | JWT signing + token exchange | `auth_service_account` |
|
||||
| `credential-injector.ts` — `decryptCredential()` | AES-GCM 解密 | host function（所有 primitive 共用） |
|
||||
| `credential-injector.ts` — `interpolateTemplate()` | `{{secret.KEY}}` 替換 | 內建在各 primitive |
|
||||
| `jwt-signer.ts` — `exchangeGoogleJwt()` | PEM→PKCS8→RS256→token | `auth_service_account` |
|
||||
| `component-loader.ts` — BUILTIN_API_RECIPES | gmail/telegram/line/gsheets 寫死邏輯 | 刪除，改用 auth recipe + `http_request` 零件 |
|
||||
| `credential-injector.ts` — BUILTIN_CREDENTIALS_MAP | 舊路徑 flat injection | 刪除，統一走 auth recipe |
|
||||
| `arcrun/credentials/` | 重複的 credentials Worker | 刪除，路由已在 cypher-executor |
|
||||
|
||||
---
|
||||
|
||||
## 4 個 WASM Primitive 設計
|
||||
|
||||
### 統一 I/O 介面（stdin/stdout JSON）
|
||||
|
||||
```
|
||||
stdin（Worker → WASM）：
|
||||
{
|
||||
"action": "authenticate" | "needs_refresh" | "refresh" | "test",
|
||||
"api_key": "ak_xxx", // 租戶識別，用來組 KV key
|
||||
"service": "openai", // 對應 auth_recipe:{service}
|
||||
"request": { "method": "GET", "url": "/path", "headers": {}, "body": null }
|
||||
}
|
||||
|
||||
WASM 內部流程：
|
||||
1. recipeJSON = kv_get("auth_recipe:" + service)
|
||||
2. 依 recipe.required_secrets 逐一 kv_get("{api_key}:cred:{name}") → {encrypted, iv}
|
||||
3. secrets[name] = crypto_decrypt(encrypted, iv)
|
||||
4. （service_account）crypto_sign_rs256(jwt, pkcs8) + http_request 換 token
|
||||
5. 展開 recipe.inject 的 {{secret.X}} / {{runtime.X}} 模板
|
||||
|
||||
stdout（WASM → Worker）：
|
||||
{
|
||||
"success": true,
|
||||
"auth_headers": { "Authorization": "Bearer xxx" },
|
||||
"auth_query": {},
|
||||
"auth_body": {},
|
||||
"runtime": { ... updated runtime state，供下次 refresh 用 }
|
||||
}
|
||||
```
|
||||
|
||||
### auth_static_key
|
||||
|
||||
**位置**：`arcrun/registry/components/auth_static_key/`
|
||||
**語言**：TinyGo 或 AssemblyScript
|
||||
|
||||
功能：
|
||||
1. 讀取 `recipe.inject.header/query/body` 模板
|
||||
2. 用 `secrets` 展開 `{{secret.KEY}}` 模板
|
||||
3. 回傳 `auth_headers` / `auth_query` / `auth_body`
|
||||
|
||||
涵蓋：~80% 服務（Bearer token, API Key, Basic Auth, custom header）
|
||||
|
||||
### auth_service_account
|
||||
|
||||
**位置**：`arcrun/registry/components/auth_service_account/`
|
||||
**語言**：TinyGo 或 AssemblyScript
|
||||
|
||||
功能：
|
||||
1. 從 `secrets.service_account_json` 解析 private key
|
||||
2. JWT signing（RS256：PEM→PKCS8→sign）
|
||||
3. POST token exchange endpoint → 取得 access_token
|
||||
4. 展開 `{{runtime.access_token}}` 模板
|
||||
|
||||
**crypto 考量**：
|
||||
- TinyGo 的 `crypto/rsa` + `crypto/x509` 支援有限
|
||||
- 若 TinyGo 不支援 RS256：使用 host function 讓 Worker 的 `crypto.subtle` 代簽
|
||||
- 或改用 AssemblyScript（有 as-crypto 套件）
|
||||
|
||||
### auth_oauth2（新建）
|
||||
|
||||
**位置**：`arcrun/registry/components/auth_oauth2/`
|
||||
|
||||
功能：
|
||||
1. `needs_refresh`：檢查 `runtime.expires_at` 是否過期
|
||||
2. `refresh`：用 `runtime.refresh_token` + `secrets.client_secret` 換新 token
|
||||
3. `authenticate`：展開 `{{runtime.access_token}}` 到 headers
|
||||
|
||||
### auth_mtls（新建）
|
||||
|
||||
**位置**：`arcrun/registry/components/auth_mtls/`
|
||||
|
||||
功能：
|
||||
1. 從 `secrets` 讀取 client cert + key
|
||||
2. 回傳 TLS 設定（由 Worker runtime 執行實際 mTLS handshake）
|
||||
|
||||
---
|
||||
|
||||
## cypher-executor 改動
|
||||
|
||||
### 保留（TS routing 層）
|
||||
|
||||
- `routes/credentials.ts` — HTTP CRUD for credentials（接收加密的 payload）
|
||||
- `routes/recipes.ts` — HTTP CRUD for auth recipes
|
||||
- `routes/auth.ts` — OAuth flow routing
|
||||
- `graph-executor.ts` — workflow 執行排程
|
||||
- `lib/wasi-shim.ts` — WASM runtime + host functions（加解密 / KV / 簽章 / HTTP 實際由 `crypto.subtle` / env binding / fetch 執行，但**呼叫時機由 WASM 決定**）
|
||||
|
||||
### 修改
|
||||
|
||||
- `actions/credential-injector.ts` — **整檔刪除**，改為新檔 `actions/auth-dispatcher.ts`（約 30 行）：
|
||||
1. 查 `resolveAuthRecipe(componentId)` 取得 `primitive` 名稱（static_key / service_account / oauth2 / mtls）
|
||||
2. 載入對應的 `auth_{primitive}.wasm`
|
||||
3. 送 stdin：`{ action, api_key, service, request }`（**不送 secrets、不送 recipe plaintext**）
|
||||
4. WASM 透過 host function 自行 `kv_get` 讀 recipe + 加密 secret，`crypto_decrypt` 解密
|
||||
5. 讀 stdout → 合併 `_auth_headers` / `_auth_query` / `_auth_body` 進 ctx
|
||||
|
||||
- `lib/component-loader.ts` — **刪除 `BUILTIN_API_RECIPES`**（含 http_request / gmail / telegram / line_notify / google_sheets 的 TS 實作），全部改走 WASM runner。每個 `.wasm` 零件都已編譯並以獨立 Worker 部署（`{canonical-id-kebab}.arcrun.dev`）。loader 新增的「WASM runner」路徑就是「canonical_id → HTTP URL 查表後 fetch」，**不做** WASM instantiate。
|
||||
- **R2 動態注入 WASM 路徑作廢**（richblack 2026-04-19 確認：CF workerd 無法以 R2 物件臨時 instantiate WASM）。用戶自製零件（Phase 5）同樣走「產生獨立 Worker」流程，不從 R2 讀。
|
||||
|
||||
### 刪除
|
||||
|
||||
- `lib/jwt-signer.ts` — 整檔刪除，RS256 簽章移入 `auth_service_account` WASM（透過 host function `crypto_sign_rs256`）
|
||||
- `credential-injector.ts` 整檔刪除（見上）
|
||||
- `component-loader.ts` 的 `BUILTIN_API_RECIPES` 整段刪除
|
||||
- `BUILTIN_CREDENTIALS_MAP` 已在 `credential-injector.ts` 內，隨檔一併刪
|
||||
|
||||
---
|
||||
|
||||
## Host Functions（WASM ↔ Worker 的橋接）
|
||||
|
||||
auth primitive WASM 需要呼叫外部能力時，透過 host function。全部放 `u6u` namespace。**錯誤回傳非零 uint32；成功 = 0 且把結果寫入 `outPtr` 指向的 buffer**。
|
||||
|
||||
| Host Function | TinyGo 簽章 | 用途 |
|
||||
|---|---|---|
|
||||
| `http_request` | `(urlPtr/Len, methodPtr/Len, headersPtr/Len, bodyPtr/Len, outPtr, outLenPtr) uint32` | HTTP 請求（已實作） |
|
||||
| `kv_get` | `(keyPtr, keyLen, outPtr, outLenPtr) uint32` | 讀 KV。Worker 依 key 前綴路由到 `CREDENTIALS_KV` / `RECIPES` |
|
||||
| `crypto_decrypt` | `(encPtr, encLen, ivPtr, ivLen, outPtr, outLenPtr) uint32` | AES-GCM 解密。encryption key 由 Worker 從 `env.ENCRYPTION_KEY` 內部讀取，**永遠不暴露給 WASM** |
|
||||
| `crypto_sign_rs256` | `(dataPtr, dataLen, pkcs8Ptr, pkcs8Len, outPtr, outLenPtr) uint32` | Worker 用 `crypto.subtle.sign('RSASSA-PKCS1-v1_5' + SHA-256)`；private key 以 PKCS8 bytes 傳入 |
|
||||
|
||||
這些 host function 在 `lib/wasi-shim.ts` 中以 WASI import 提供。
|
||||
|
||||
### 安全邊界
|
||||
|
||||
- `ENCRYPTION_KEY` 只在 `crypto_decrypt` host function 內部使用，**絕不**經 stdin / 回傳值 / 任何路徑傳給 WASM
|
||||
- `api_key` 經 stdin 傳入 WASM（讓 WASM 自己組 `{api_key}:cred:{name}` KV key）
|
||||
- `kv_get` 在 Worker 側檢查 key 前綴：
|
||||
- `auth_recipe:*` → 讀 `RECIPES`
|
||||
- `{api_key}:cred:*` → 讀 `CREDENTIALS_KV`，且 `{api_key}` 必須等於 stdin 傳入的 api_key（防越權）
|
||||
- 其他前綴 → 回傳錯誤
|
||||
|
||||
---
|
||||
|
||||
## 關於解密位置
|
||||
|
||||
採用**方案 B（唯一方案）**：WASM 透過 host function `crypto_decrypt()` 自行解密。
|
||||
|
||||
- cypher-executor TS 完全不解密、不知道 plaintext
|
||||
- `ENCRYPTION_KEY` 永遠留在 Worker host function 內
|
||||
- WASM 知道要解哪份 ciphertext（經 `kv_get` 讀到的 `{encrypted, iv}`），但拿不到 encryption key
|
||||
- 這樣 TS 層完全沒有零件業務邏輯，符合 CLAUDE.md §禁止行為 1/6
|
||||
|
||||
（歷史註記：曾規劃方案 A「TS 先解密再送 stdin」，已廢棄 — 違反「TS 不得實作零件邏輯」。）
|
||||
|
||||
---
|
||||
|
||||
## 不做的事
|
||||
|
||||
- ❌ 不改 recipe YAML schema — 沿用現有格式
|
||||
- ❌ 不改 KV 儲存結構 — `auth_recipe:{service}` / `{api_key}:cred:{name}` 不變
|
||||
- ❌ 不改 SDK API — SDK 仍是 HTTP thin wrapper
|
||||
- ❌ 不建新的 Worker — 在 cypher-executor 內完成
|
||||
@@ -0,0 +1,168 @@
|
||||
# Implementation Tasks: Credential Primitives TS → WASM
|
||||
|
||||
**嚴格規範（richblack 2026-04-19）**：cypher-executor TS 不得實作任何 credential / auth / template / JWT / 解密邏輯。全部走 TinyGo WASM + host functions（方案 B）。
|
||||
|
||||
**封測狀態**：推遲（richblack 2026-04-19 決定）。先完成 Phase 1-3 清除違規 TS，再啟動封測。
|
||||
|
||||
---
|
||||
|
||||
## Phase 0：核心合併（u6u-core → arcrun）
|
||||
|
||||
- [x] 0.1 把 `u6u-core/builtins/` 搬到 `arcrun/builtins/`
|
||||
- [x] 0.2 確認 `arcrun/registry/components/` 21 個零件的 contract.yaml 完整（21/21）
|
||||
- [x] 0.3 刪除 `arcrun/credentials/` 整個目錄（重複，credential route 已在 cypher-executor）
|
||||
- [x] 0.4 更新 `arcrun/cypher-executor/wrangler.toml`：確認 CREDENTIALS_KV binding 存在
|
||||
- [x] 0.5 刪除 `matrix/u6u-core/` 整個目錄（2026-04-19 完成，只剩 credentials/ 已被 cypher-executor 取代）
|
||||
- [x] 0.6 在 `cypher-executor/src/lib/wasi-shim.ts` 新增 host functions：
|
||||
- `u6u.kv_get(keyPtr, keyLen, outPtr, outLenPtr) uint32` — 依 key 前綴路由到 `CREDENTIALS_KV` / `RECIPES`，越權檢查 api_key
|
||||
- `u6u.crypto_decrypt(encPtr, encLen, ivPtr, ivLen, outPtr, outLenPtr) uint32` — 用 `env.ENCRYPTION_KEY` + `crypto.subtle` AES-GCM 解密；key 不暴露給 WASM
|
||||
- `u6u.crypto_sign_rs256(dataPtr, dataLen, pkcs8Ptr, pkcs8Len, outPtr, outLenPtr) uint32` — `crypto.subtle.sign('RSASSA-PKCS1-v1_5' + SHA-256)`
|
||||
- 2026-04-19 完成：wasi-shim.ts 新增 `createArcrunHostFunctions(env, apiKey)` factory，集中 AES-GCM 解密 + RSA sign + KV 前綴路由越權檢查。WASI imports 的 u6u namespace wiring 本來就已接好（只是當時沒有實作 factory）。typecheck 通過。
|
||||
- [x] 0.7 在 `cypher-executor/src/lib/component-loader.ts` 新增 WASM runner 路徑：
|
||||
- 所有 WASM 零件（含 auth primitive、API 零件、未來用戶自製）一律走 HTTP URL（`{canonical-id-kebab}.arcrun.dev`）到獨立 Worker
|
||||
- **R2 動態注入路徑作廢**（richblack 2026-04-19 確認：CF workerd 不支援以 R2 物件臨時 instantiate WASM；用戶自製零件同樣走「產生獨立 Worker」流程，不走 R2）
|
||||
- cypher-executor 本身**不做** WASM instantiate，也不直接呼叫 `createArcrunHostFunctions`；那個 factory 是**零件 Worker 側**（`.component-builds/{name}/src/index.ts`）用的，在 Phase 1 建立 auth_static_key Worker 時接上
|
||||
- 2026-04-19 完成：`component-loader.ts` 新增 `WASM_HTTP_RUNNER_IDS`（10 個 canonical_id，6 個 API 零件 + 4 個 auth primitive）＋ `wasmWorkerUrl()` URL 慣例輔助函數；解析鏈新增為第 8 層（放在 `BUILTIN_API_RECIPES` fallback 之後，避免 Phase 3 尚未完成時 API 零件 Worker 未部署造成 404；Phase 3 刪除 `BUILTIN_API_RECIPES` 後，API 零件會自然落到此層）。auth primitive 從此層進入。`tsc --noEmit` 通過。
|
||||
|
||||
---
|
||||
|
||||
## Phase 1：auth_static_key WASM（優先，涵蓋 80% 服務）
|
||||
|
||||
方案 B：WASM 自行讀 KV + 解密，TS 不碰 plaintext。
|
||||
|
||||
- [x] 1.1 建立 `arcrun/registry/components/auth_static_key/` 目錄
|
||||
- [x] 1.2 寫 `component.contract.yaml`（input: `{action, api_key, service, request}` → output: `{success, auth_headers, auth_query, auth_body, runtime}`）
|
||||
- [x] 1.3 實作 `main.go`（TinyGo）：
|
||||
- 宣告 host imports：`kv_get` / `crypto_decrypt`（static_key 不需要 http_request）
|
||||
- 從 stdin 讀 `{action, api_key, service}`
|
||||
- `kv_get("auth_recipe:" + service)` → recipe JSON → 驗證 `primitive == "static_key"`
|
||||
- 對每個 non-optional `recipe.required_secrets`：`kv_get("{api_key}:cred:{name}")` → `{encrypted, iv}` → `crypto_decrypt` → plaintext
|
||||
- 展開 `{{secret.X}}` / `{{runtime.X}}` 模板於 `inject.header/query/body`；未知 key 展空字串（與 TS parity）；其他 namespace 的 `{{...}}` 原樣保留
|
||||
- 輸出 stdout JSON `{success, auth_headers, auth_query, auth_body, runtime}`
|
||||
- [x] 1.4 `tinygo build -o auth_static_key.wasm -target=wasi main.go` — 2026-04-19 編譯通過（1.1MB，在 contract 限制 2MB 內）
|
||||
- [🔄] 1.5 建立 `.component-builds/auth_static_key/`（用 `component-worker-template`）並部署到 `auth-static-key.arcrun.dev`
|
||||
- 2026-04-20 完成**建置**部分:`.component-builds/auth_static_key/{wrangler.toml, package.json, tsconfig.json, src/index.ts, component.wasm}` 全數到位
|
||||
- 方案 A:`src/index.ts` 直接 import `../../../cypher-executor/src/lib/wasi-shim` 的 `createWasiShim` + `createArcrunHostFunctions`(以 `ArcrunHostEnv` 結構型別相容);AES 解密邏輯仍只存在於 wasi-shim.ts 一處(rule 02 §2.2)
|
||||
- 綁同組 KV:CREDENTIALS_KV (e7f4320f88d343f187e35e3543dd74c9) / RECIPES (9cf9db905c6241f78503199e58b2ffe0);ENCRYPTION_KEY 走 `wrangler secret put`
|
||||
- `wrangler deploy --dry-run` 通過(1192 KiB, 419 KiB gzip);實際 `wrangler deploy` + `secret put ENCRYPTION_KEY` 留給 richblack 執行
|
||||
- [x] 1.6 建立 `auth-dispatcher.ts`（取代 `credential-injector.ts`）：查 auth recipe → HTTP POST 到對應 auth primitive URL → 合併 `_auth_headers` 進 ctx
|
||||
- 2026-04-20 完成:`cypher-executor/src/actions/auth-dispatcher.ts` 新建,export `tryAuthDispatch(componentId, input, env, apiKey)`
|
||||
- 流程:查 `resolveAuthRecipe` → primitive 在 `SUPPORTED_PRIMITIVES`(目前只有 `static_key`)→ fetch `wasmWorkerUrl('auth_static_key')` → 合併 `_auth_headers/_auth_query/_auth_body`
|
||||
- 自引用防護:`AUTH_PRIMITIVE_IDS` set 排除 4 個 `auth_*` componentId
|
||||
- `wasmWorkerUrl` 從 `component-loader.ts` export 出來共用
|
||||
- `graph-executor.ts` 改為:先試 `tryAuthDispatch`(新路徑),沒命中 fallback 到舊 `injectCredentials`(Phase 1.9 刪)
|
||||
- 檢查過 auth-dispatcher.ts 無 `crypto.subtle` / `interpolate` / `{{secret.` / hard-code API URL,符合 rule 02 §2.2
|
||||
- `tsc --noEmit` 通過
|
||||
- [ ] 1.7 端對端測試：openai recipe → 成功注入 `Authorization: Bearer <openai_key>`
|
||||
- [ ] 1.8 端對端測試：twilio recipe（Basic Auth）→ 成功注入
|
||||
- [ ] 1.9 **刪除 `credential-injector.ts` 整檔**（`decryptCredential` / `decryptSecrets` / `interpolateTemplate` / `BUILTIN_CREDENTIALS_MAP` 全刪）
|
||||
|
||||
---
|
||||
|
||||
## Phase 2：auth_service_account WASM
|
||||
|
||||
- [🔄] 2.1 建立 `arcrun/registry/components/auth_service_account/` 目錄
|
||||
- [🔄] 2.2 寫 `component.contract.yaml`
|
||||
- [🔄] 2.3 實作 `main.go`：
|
||||
- 從 stdin 讀 `{api_key, service}` + `kv_get` 拿 recipe + 解密 SA JSON
|
||||
- 解析 SA JSON 取 `client_email` / `private_key`（PEM）
|
||||
- PEM → PKCS8 bytes（純 Go，base64 decode + 去 header/footer）
|
||||
- 組 JWT header + payload（base64url），呼叫 `crypto_sign_rs256(signingInput, pkcs8)` 拿 signature
|
||||
- 組完整 JWT → `http_request` POST `token_uri` → 拿 `access_token`
|
||||
- 展開 `{{runtime.access_token}}` 模板
|
||||
- [x] 2.4 `tinygo build -o auth_service_account.wasm -target=wasi main.go` — 2026-04-20 編譯通過（1.1MB,在 contract 限制 2MB 內）
|
||||
- [x] 2.5 建立 `.component-builds/auth_service_account/` 並部署到 `auth-service-account.arcrun.dev`
|
||||
- 2026-04-20 完成**建置**部分:`.component-builds/auth_service_account/{wrangler.toml, package.json, tsconfig.json, src/index.ts, component.wasm}` 全數到位
|
||||
- 方案 A:`src/index.ts` 重用 `createArcrunHostFunctions` 提供 kv_get/crypto_decrypt/crypto_sign_rs256,**額外加 `http_request` host function**(token exchange 用,非 crypto 不受 §2.2 約束)。http_request 直接回 response body 原文(WASM 端 json.Unmarshal 找 access_token)
|
||||
- 綁同組 KV:CREDENTIALS_KV / RECIPES;ENCRYPTION_KEY 走 `wrangler secret put`
|
||||
- `wrangler deploy --dry-run` 通過(1248 KiB, 440 KiB gzip);實際 `wrangler deploy` + `secret put ENCRYPTION_KEY` 留給 richblack 執行
|
||||
- `auth-dispatcher.ts` 的 `SUPPORTED_PRIMITIVES` 加入 `'service_account'`,workflow 用 google SA recipe 會自動走新 WASM 路徑
|
||||
- [ ] 2.6 端對端測試：google_sheets_sa recipe → 成功取得 access_token → 注入 header
|
||||
- [x] 2.7 **刪除 `lib/jwt-signer.ts` 整檔** — 2026-04-20 完成
|
||||
- `cypher-executor/src/lib/jwt-signer.ts` 已刪除(RS256 JWT 邏輯移入 `auth_service_account.wasm`)
|
||||
- `credential-injector.ts` 原 line 23 `import { exchangeGoogleJwt }` 移除
|
||||
- `credential-injector.ts` 原 line 140-150 service_account 分支改為 throw(任何 service_account recipe 已被 auth-dispatcher 攔截;這條 TS fallback 若被觸發即表架構錯亂,直接爆錯比沈默解密更安全)
|
||||
- `cypher-executor` tsc --noEmit 通過
|
||||
|
||||
---
|
||||
|
||||
## Phase 3：清理 component-loader 的 TS 實作（全刪）
|
||||
|
||||
目標：`BUILTIN_API_RECIPES` 整段刪除，所有服務走 WASM runner（HTTP URL 路徑）。
|
||||
|
||||
- [x] 3.1 確認 `http_request.wasm` / `gmail.wasm` / `telegram.wasm` / `line_notify.wasm` / `google_sheets.wasm` 都在 `registry/components/` 且可執行 — 2026-04-20 驗證 6 個(含 cron)全數存在,main.go + .wasm 齊備
|
||||
- [x] 3.2 確認上述零件 Worker 都已部署（`{name}.arcrun.dev` 可用） — 2026-04-20 完成**建置**部分
|
||||
- 6 個 Worker 建置到位:`.component-builds/{http_request, gmail, telegram, line_notify, google_sheets, cron}/{wrangler.toml, package.json, tsconfig.json, src/index.ts, component.wasm}`
|
||||
- 方案 A:5 個需 http_request 的零件(http_request/gmail/telegram/line_notify/google_sheets)`src/index.ts` 共用模板;cron 是純計算不註冊 host function
|
||||
- 全部透過 `createWasiShim` 複用 cypher-executor/src/lib/wasi-shim.ts(rule 02 §2.2 邊界)
|
||||
- 6 個 `wrangler deploy --dry-run` 全通過(~1.17 MB / ~413 KB gzip 每個);實際 `wrangler deploy` 留給 richblack 執行
|
||||
- [x] 3.3 `component-loader.ts` 的內建路徑改為查對應 Worker URL → HTTP POST — 2026-04-20 完成
|
||||
- 原本第 7 層是 `BUILTIN_API_RECIPES` fallback、第 8 層是 `WASM_HTTP_RUNNER_IDS` (HTTP URL);兩層合併為第 7 層 `WASM_HTTP_RUNNER_IDS` 直接走 `makeHttpRunner(wasmWorkerUrl(id))`
|
||||
- 解析鏈新編號 1-8,順序不變(外部 URL → recipe hash → component hash → R2 → Service Binding → auth recipe runner → WASM HTTP runner → 找不到)
|
||||
- [x] 3.4 **刪除 `BUILTIN_API_RECIPES` 整個 Record**（`http_request` / `gmail` / `telegram` / `line_notify` / `google_sheets` / `cron` 的 TS 實作全刪） — 2026-04-20 完成
|
||||
- `cypher-executor/src/lib/component-loader.ts` 原 line 253-326 `BUILTIN_API_RECIPES` 常數 + fallback lookup 全刪(約 80 行)
|
||||
- 全域搜尋確認:`gmail.googleapis.com/...messages/send` / `api.telegram.org/bot.*sendMessage` / `sheets.googleapis.com/v4/spreadsheets` / `notify-api.line.me/api/notify` 在 cypher-executor TS 中已不存在(auth-recipe-seeds.ts 的 `base_url` 是 recipe 資料欄位,不是 hard-coded API call)
|
||||
- `cypher-executor` tsc --noEmit 通過
|
||||
- [ ] 3.5 端對端測試：workflow 用 gmail auth recipe + gmail.wasm Worker → 成功發信
|
||||
- [ ] 3.6 端對端測試：workflow 用 http_request.wasm Worker + auth_static_key 注入 → 成功呼叫任意 API
|
||||
|
||||
---
|
||||
|
||||
## Phase 4：auth_oauth2 + auth_mtls WASM（封測後）
|
||||
|
||||
- [ ] 4.1 建立 `arcrun/registry/components/auth_oauth2/`
|
||||
- [ ] 4.2 實作：`needs_refresh` / `refresh` / `authenticate` 三個 action
|
||||
- [ ] 4.3 建立 `arcrun/registry/components/auth_mtls/`
|
||||
- [ ] 4.4 實作：輸出 TLS cert/key（實際 mTLS handshake 由 Worker runtime 執行，WASM 無法做 socket）
|
||||
|
||||
---
|
||||
|
||||
## Phase 5：封測啟動門檻 — 核心穩定驗證
|
||||
|
||||
**全部通過才能啟動封測**。
|
||||
|
||||
- [ ] 5.1 所有 20 個 auth recipe seed 可正常運作（static_key 17 個 + service_account 3 個）
|
||||
- [ ] 5.2 `cypher-executor/src/actions/credential-injector.ts` **不存在**
|
||||
- [ ] 5.3 `cypher-executor/src/lib/jwt-signer.ts` **不存在**
|
||||
- [ ] 5.4 `cypher-executor/src/lib/component-loader.ts` 無 `BUILTIN_API_RECIPES` / `BUILTIN_CREDENTIALS_MAP`
|
||||
- [ ] 5.5 `cypher-executor/src/` 全域搜尋 `crypto.subtle.decrypt` 只出現在 `wasi-shim.ts` 的 `crypto_decrypt` host function
|
||||
- [ ] 5.6 `cypher-executor/src/` 全域搜尋 `crypto.subtle.sign` 只出現在 `wasi-shim.ts` 的 `crypto_sign_rs256` host function
|
||||
- [ ] 5.7 `cypher-executor/src/` 全域搜尋 `interpolate` 回傳 0 筆（template 展開全在 WASM）
|
||||
- [ ] 5.8 全域搜尋 `{{secret\.` / `{{runtime\.` 在 TS 檔案中回傳 0 筆
|
||||
|
||||
---
|
||||
|
||||
## Phase 6:通用 CI/CD deploy workflow
|
||||
|
||||
**背景**(2026-04-20 richblack 決定):現 `.github/workflows/deploy.yml` 只部署 cypher-executor + registry + 已刪除的 credentials,漏掉 Phase 1-3 產出的 8 個 Worker,且硬編碼每個 job 導致未來新增 Worker 都要改 CI。改為**通用掃描式 workflow**:任何含 `wrangler.toml` 的目錄 = 部署單位,改到該目錄下任何檔案 = 觸發重新 deploy。
|
||||
|
||||
**關鍵決策**:
|
||||
- 零件 `.wasm` 由 CI build(不 commit):`registry/components/{name}/main.go` 改動時才重 build,用 timestamp / content hash 判斷
|
||||
- `.component-builds/{name}/component.wasm` 由 CI 從 `registry/components/{name}/{name}.wasm` 複製產生(deploy 前一步)
|
||||
- 統一用 pnpm(`.component-builds/*` 本來就是;順勢把 cypher-executor 的 `package-lock.json` 砍了)
|
||||
- runtime secret(`ENCRYPTION_KEY`)不進 CI,由 richblack 一次性 `wrangler secret put`
|
||||
- registry Worker 的 `wrangler.toml` 現階段不改(職責是合約管理,與封測無關;`sandboxAcceptance.ts` 的 rule 02 §2.2 審查留到 Phase 5 用戶自製零件啟動時)
|
||||
|
||||
### Tasks
|
||||
|
||||
- [x] 6.1 改寫 `.github/workflows/deploy.yml`:動態掃描所有含 `wrangler.toml` 的目錄(排除 `node_modules/` + Pages 專案),用 matrix job fanout 部署;分兩層(tier1=`.component-builds/*`,tier2=其他),tier1 全綠後才 tier2(避免 service binding target 未存在)
|
||||
- [x] 6.2 加上 TinyGo build 步驟:tier1 matrix 一律 setup-tinygo + 從 `registry/components/{name}/main.go` rebuild `.wasm` → copy 到 `.component-builds/{name}/component.wasm`
|
||||
- [x] 6.3 diff-aware:push 到 main 時比對 `github.event.before..github.sha`,只 deploy 有 diff 的 Worker(含 `registry/components/{name}/` 連動 `.component-builds/{name}/`);`workflow_dispatch` 提供 `force_all` + `only` 選項
|
||||
- [x] 6.4 統一 pnpm:刪除 `cypher-executor/package-lock.json` + `registry/package-lock.json`;workflow 優先 `pnpm install --frozen-lockfile`,若該目錄無 `pnpm-lock.yaml` 則 fallback 到 `--no-frozen-lockfile`(混合期容錯)
|
||||
- [x] 6.5 加 `max-parallel: 5` 控制 Workers API rate limit(tier1 和 tier2 各自)
|
||||
- [x] 6.6 驗證:`workflow_dispatch` + `force_all=true` 手動跑一次,24 個 Worker 全綠 — 2026-04-20 完成
|
||||
- 最終綠色 run 24668903627(28/28 jobs,含 discover + summary):tier1 24 個零件 Worker + tier2 2 個 orchestration Worker(cypher-executor / registry)全 success
|
||||
- 過程中修兩輪:先修 `setup-node` 的 `cache: 'pnpm'` 對 legacy `package-lock.json` 目錄失效(改為不用 cache);再修 tier2 三個 package.json(cypher-executor/registry/builtins)遺漏 `wrangler` devDependency + regen pnpm-lock.yaml
|
||||
- ENCRYPTION_KEY secret 已由 richblack 授權、CC 從 .env pipe 到三個 Worker:`arcrun-auth-static-key`、`arcrun-auth-service-account`、`arcrun-cypher-executor`(不顯示內容)
|
||||
- [x] 6.7 文件:在 `.claude/rules/` 加一份 `05-deploy-convention.md`(「新增 Worker = 新目錄 + wrangler.toml,不用改 CI」)
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- 方案 B 是唯一方案（方案 A 已廢棄，違反 CLAUDE.md §禁止行為）
|
||||
- Phase 0.6（host functions）+ 0.7（WASM runner）是 Phase 1-3 的硬前置，必須先做
|
||||
- 若 TinyGo `encoding/base64` 可用就直接用；若不可用則自行實作（見 gmail/main.go 的 `base64URLEncode`）
|
||||
- `auth_mtls` 的 TLS handshake 無法在 WASM 內做（WASI preview1 沒 socket），只能輸出 cert/key 讓 Worker 在 fetch 時用
|
||||
- **每個 auth primitive WASM 都是獨立部署的 Worker**（透過 `component-worker-template/`），不是從 R2 動態載入
|
||||
- Cypher binding = workflow YAML 裡的 URL 清單，不是 Cloudflare service binding
|
||||
@@ -0,0 +1,25 @@
|
||||
# CODING AGENTS: READ THIS FIRST
|
||||
|
||||
This is a **handoff bundle** from Claude Design (claude.ai/design).
|
||||
|
||||
A user mocked up designs in HTML/CSS/JS using an AI design tool, then exported this bundle so a coding agent can implement the designs for real.
|
||||
|
||||
## What you should do — IMPORTANT
|
||||
|
||||
**Read the chat transcripts first.** There are 1 chat transcript(s) in `arcrun/chats/`. The transcripts show the full back-and-forth between the user and the design assistant — they tell you **what the user actually wants** and **where they landed** after iterating. Don't skip them. The final HTML files are the output, but the chat is where the intent lives.
|
||||
|
||||
**Find the primary design file under `arcrun/project/` and read it top to bottom.** The chat transcripts will tell you which file the user was last iterating on. Then **follow its imports**: open every file it pulls in (shared components, CSS, scripts) so you understand how the pieces fit together before you start implementing.
|
||||
|
||||
**If anything is ambiguous, ask the user to confirm before you start implementing.** It's much cheaper to clarify scope up front than to build the wrong thing.
|
||||
|
||||
## About the design files
|
||||
|
||||
The design medium is **HTML/CSS/JS** — these are prototypes, not production code. Your job is to **recreate them pixel-perfectly** in whatever technology makes sense for the target codebase (React, Vue, native, whatever fits). Match the visual output; don't copy the prototype's internal structure unless it happens to fit.
|
||||
|
||||
**Don't render these files in a browser or take screenshots unless the user asks you to.** Everything you need — dimensions, colors, layout rules — is spelled out in the source. Read the HTML and CSS directly; a screenshot won't tell you anything they don't.
|
||||
|
||||
## Bundle contents
|
||||
|
||||
- `arcrun/README.md` — this file
|
||||
- `arcrun/chats/` — conversation transcripts (read these!)
|
||||
- `arcrun/project/` — the `arcrun` project files (HTML prototypes, assets, components)
|
||||
@@ -0,0 +1,56 @@
|
||||
// App root — screen switcher with persistent route
|
||||
const { useState, useEffect } = React;
|
||||
|
||||
const SCREENS = [
|
||||
{ id: 'landing', label: 'Landing' },
|
||||
{ id: 'auth', label: 'Auth' },
|
||||
{ id: 'dashboard', label: 'Dashboard' },
|
||||
{ id: 'keys', label: 'API Keys' },
|
||||
{ id: 'workflow', label: 'Workflow' },
|
||||
];
|
||||
|
||||
// Synonyms from sidebar ids
|
||||
const aliases = { apps: 'dashboard', workflows: 'dashboard', docs: 'landing', settings: 'keys' };
|
||||
|
||||
function App() {
|
||||
const [screen, setScreen] = useState(() => {
|
||||
const saved = localStorage.getItem('arcrun:screen');
|
||||
return saved && SCREENS.some(s => s.id === saved) ? saved : 'landing';
|
||||
});
|
||||
|
||||
useEffect(() => {
|
||||
localStorage.setItem('arcrun:screen', screen);
|
||||
window.scrollTo(0, 0);
|
||||
}, [screen]);
|
||||
|
||||
const nav = (id) => {
|
||||
const resolved = aliases[id] || id;
|
||||
if (SCREENS.some(s => s.id === resolved)) setScreen(resolved);
|
||||
};
|
||||
|
||||
const Current = {
|
||||
landing: Landing,
|
||||
auth: Auth,
|
||||
dashboard: Dashboard,
|
||||
keys: ApiKeys,
|
||||
workflow: WorkflowViewer,
|
||||
}[screen];
|
||||
|
||||
return (
|
||||
<div className="app">
|
||||
<Current onNav={nav} />
|
||||
|
||||
<div className="proto-switch" role="tablist" aria-label="Screen switcher">
|
||||
{SCREENS.map(s => (
|
||||
<button key={s.id}
|
||||
className={screen === s.id ? 'active' : ''}
|
||||
onClick={() => nav(s.id)}>
|
||||
{s.label}
|
||||
</button>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
ReactDOM.createRoot(document.getElementById('root')).render(<App />);
|
||||
@@ -0,0 +1,92 @@
|
||||
// Top nav and sidebar
|
||||
|
||||
const TopNav = ({ onNav, current }) => {
|
||||
const [scrolled, setScrolled] = React.useState(false);
|
||||
React.useEffect(() => {
|
||||
const onScroll = () => setScrolled(window.scrollY > 8);
|
||||
window.addEventListener('scroll', onScroll);
|
||||
return () => window.removeEventListener('scroll', onScroll);
|
||||
}, []);
|
||||
return (
|
||||
<nav className={`topnav ${scrolled ? 'scrolled' : ''}`}>
|
||||
<div className="flex gap-12" style={{alignItems: 'center'}}>
|
||||
<Logo onClick={() => onNav('landing')} />
|
||||
<div className="nav-links" style={{marginLeft: 20}}>
|
||||
<a>Product</a>
|
||||
<a>Docs</a>
|
||||
<a>Pricing</a>
|
||||
<a>Changelog</a>
|
||||
</div>
|
||||
</div>
|
||||
<div className="flex gap-8" style={{alignItems: 'center'}}>
|
||||
<button className="btn btn-ghost" onClick={() => onNav('auth')}>Log in</button>
|
||||
<button className="btn btn-primary" onClick={() => onNav('auth')}>
|
||||
Get started <Icon name="arrow_right" size={14} />
|
||||
</button>
|
||||
</div>
|
||||
</nav>
|
||||
);
|
||||
};
|
||||
|
||||
const Footer = ({ onNav }) => (
|
||||
<footer className="footer">
|
||||
<div className="flex gap-12" style={{alignItems: 'center'}}>
|
||||
<Logo size="sm" />
|
||||
<span>© 2026 Arcrun Labs</span>
|
||||
</div>
|
||||
<div className="footer-links">
|
||||
<a>Docs</a>
|
||||
<a>Pricing</a>
|
||||
<a>Changelog</a>
|
||||
<a>Status</a>
|
||||
<a>Privacy</a>
|
||||
</div>
|
||||
</footer>
|
||||
);
|
||||
|
||||
// App shell with sidebar for logged-in screens
|
||||
const Sidebar = ({ current, onNav }) => {
|
||||
const items = [
|
||||
{ id: 'dashboard', label: 'Dashboard', icon: 'home' },
|
||||
{ id: 'apps', label: 'Apps', icon: 'grid', count: 6 },
|
||||
{ id: 'workflows', label: 'Workflows', icon: 'workflow', count: 12 },
|
||||
{ id: 'keys', label: 'API Keys', icon: 'key' },
|
||||
{ id: 'docs', label: 'Docs', icon: 'book' },
|
||||
];
|
||||
const bottom = [
|
||||
{ id: 'settings', label: 'Settings', icon: 'settings' },
|
||||
];
|
||||
return (
|
||||
<aside className="sidebar">
|
||||
<div className="sidebar-head">
|
||||
<Logo size="md" onClick={() => onNav('landing')} />
|
||||
</div>
|
||||
<div className="sidebar-section">Workspace</div>
|
||||
{items.map(it => (
|
||||
<div key={it.id}
|
||||
className={`sidebar-item ${current === it.id ? 'active' : ''}`}
|
||||
onClick={() => onNav(it.id)}>
|
||||
<span className="sb-ico"><Icon name={it.icon} size={15} /></span>
|
||||
<span>{it.label}</span>
|
||||
{it.count != null && <span className="sb-count">{it.count}</span>}
|
||||
</div>
|
||||
))}
|
||||
<div style={{flex: 1}} />
|
||||
{bottom.map(it => (
|
||||
<div key={it.id} className="sidebar-item" onClick={() => onNav(it.id)}>
|
||||
<span className="sb-ico"><Icon name={it.icon} size={15} /></span>
|
||||
<span>{it.label}</span>
|
||||
</div>
|
||||
))}
|
||||
<div className="sidebar-foot">
|
||||
<div className="avatar-circ">MR</div>
|
||||
<div className="meta">
|
||||
<div className="name">Maya Rivera</div>
|
||||
<div className="email">maya@northwind.co</div>
|
||||
</div>
|
||||
</div>
|
||||
</aside>
|
||||
);
|
||||
};
|
||||
|
||||
Object.assign(window, { TopNav, Footer, Sidebar });
|
||||
@@ -0,0 +1,86 @@
|
||||
// Shared primitives: icons, logo, etc.
|
||||
|
||||
const Icon = ({ name, size = 16, stroke = 1.7 }) => {
|
||||
const paths = {
|
||||
arrow_right: <path d="M5 12h14M13 6l6 6-6 6" />,
|
||||
arrow_left: <path d="M19 12H5M11 6l-6 6 6 6" />,
|
||||
plus: <path d="M12 5v14M5 12h14" />,
|
||||
copy: <><rect x="9" y="9" width="13" height="13" rx="2" /><path d="M5 15V5a2 2 0 0 1 2-2h10" /></>,
|
||||
check: <path d="M20 6L9 17l-5-5" />,
|
||||
close: <path d="M18 6L6 18M6 6l12 12" />,
|
||||
eye: <><path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z" /><circle cx="12" cy="12" r="3" /></>,
|
||||
search: <><circle cx="11" cy="11" r="7" /><path d="M21 21l-4.35-4.35" /></>,
|
||||
warn: <><path d="M10.3 3.86L1.82 18a2 2 0 001.72 3h16.92a2 2 0 001.72-3L13.7 3.86a2 2 0 00-3.4 0z" /><line x1="12" y1="9" x2="12" y2="13" /><circle cx="12" cy="17" r="0.5" fill="currentColor" /></>,
|
||||
home: <><path d="M3 10l9-7 9 7v10a2 2 0 01-2 2h-4a2 2 0 01-2-2v-5h-2v5a2 2 0 01-2 2H5a2 2 0 01-2-2V10z" /></>,
|
||||
grid: <><rect x="3" y="3" width="7" height="7" rx="1" /><rect x="14" y="3" width="7" height="7" rx="1" /><rect x="3" y="14" width="7" height="7" rx="1" /><rect x="14" y="14" width="7" height="7" rx="1" /></>,
|
||||
workflow: <><circle cx="5" cy="6" r="2" /><circle cx="19" cy="12" r="2" /><circle cx="5" cy="18" r="2" /><path d="M7 6h4a4 4 0 014 4v0m0 4a4 4 0 01-4 4H7" /></>,
|
||||
key: <><circle cx="7.5" cy="15.5" r="4.5" /><path d="M10.68 12.32L21 2M17 6l3 3M15 8l3 3" /></>,
|
||||
book: <><path d="M2 3h6a4 4 0 014 4v14a3 3 0 00-3-3H2zM22 3h-6a4 4 0 00-4 4v14a3 3 0 013-3h7z" /></>,
|
||||
settings: <><circle cx="12" cy="12" r="3" /><path d="M19.4 15a1.65 1.65 0 00.33 1.82l.06.06a2 2 0 01-2.83 2.83l-.06-.06a1.65 1.65 0 00-1.82-.33 1.65 1.65 0 00-1 1.51V21a2 2 0 01-4 0v-.09A1.65 1.65 0 009 19.4a1.65 1.65 0 00-1.82.33l-.06.06a2 2 0 01-2.83-2.83l.06-.06a1.65 1.65 0 00.33-1.82 1.65 1.65 0 00-1.51-1H3a2 2 0 010-4h.09A1.65 1.65 0 004.6 9a1.65 1.65 0 00-.33-1.82l-.06-.06a2 2 0 012.83-2.83l.06.06A1.65 1.65 0 009 4.6a1.65 1.65 0 001-1.51V3a2 2 0 014 0v.09A1.65 1.65 0 0015 4.6a1.65 1.65 0 001.82-.33l.06-.06a2 2 0 012.83 2.83l-.06.06A1.65 1.65 0 0019.4 9v0a1.65 1.65 0 001.51 1H21a2 2 0 010 4h-.09a1.65 1.65 0 00-1.51 1z" /></>,
|
||||
chevron_right: <path d="M9 6l6 6-6 6" />,
|
||||
chevron_down: <path d="M6 9l6 6 6-6" />,
|
||||
external: <><path d="M18 13v6a2 2 0 01-2 2H5a2 2 0 01-2-2V8a2 2 0 012-2h6" /><path d="M15 3h6v6M10 14L21 3" /></>,
|
||||
trash: <><polyline points="3 6 5 6 21 6" /><path d="M19 6l-1 14a2 2 0 01-2 2H8a2 2 0 01-2-2L5 6M10 11v6M14 11v6" /></>,
|
||||
spark: <path d="M12 3l2.5 6.5L21 12l-6.5 2.5L12 21l-2.5-6.5L3 12l6.5-2.5L12 3z" />,
|
||||
bolt: <path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z" />,
|
||||
github: <path d="M12 2C6.48 2 2 6.48 2 12c0 4.42 2.87 8.17 6.84 9.5.5.08.66-.22.66-.48v-1.7c-2.78.6-3.36-1.34-3.36-1.34-.46-1.15-1.12-1.46-1.12-1.46-.92-.62.07-.6.07-.6 1.01.07 1.55 1.04 1.55 1.04.9 1.54 2.36 1.1 2.94.84.09-.65.35-1.1.64-1.35-2.22-.25-4.55-1.11-4.55-4.94 0-1.09.39-1.98 1.03-2.68-.1-.25-.45-1.27.1-2.65 0 0 .84-.27 2.75 1.02A9.5 9.5 0 0112 6.8c.85 0 1.7.11 2.5.33 1.9-1.3 2.75-1.02 2.75-1.02.55 1.38.2 2.4.1 2.65.64.7 1.03 1.6 1.03 2.68 0 3.84-2.34 4.69-4.57 4.93.36.31.68.92.68 1.85V21c0 .27.16.57.67.48A10 10 0 0022 12c0-5.52-4.48-10-10-10z" fill="currentColor" stroke="none" />,
|
||||
google: <><path d="M21.35 11.1h-9.17v2.73h5.24c-.23 1.41-1.69 4.13-5.24 4.13-3.15 0-5.73-2.62-5.73-5.86 0-3.24 2.58-5.86 5.73-5.86 1.8 0 3 .77 3.69 1.43l2.5-2.4C16.95 3.74 14.8 2.8 12.18 2.8c-5.26 0-9.53 4.25-9.53 9.5s4.27 9.5 9.53 9.5c5.51 0 9.15-3.87 9.15-9.32 0-.63-.07-1.1-.15-1.38z" fill="currentColor" stroke="none" /></>,
|
||||
share: <><circle cx="18" cy="5" r="3" /><circle cx="6" cy="12" r="3" /><circle cx="18" cy="19" r="3" /><path d="M8.59 13.51l6.83 3.98M15.41 6.51l-6.82 3.98" /></>,
|
||||
download: <><path d="M21 15v4a2 2 0 01-2 2H5a2 2 0 01-2-2v-4" /><polyline points="7 10 12 15 17 10" /><line x1="12" y1="15" x2="12" y2="3" /></>,
|
||||
zoom_in: <><circle cx="11" cy="11" r="7" /><line x1="21" y1="21" x2="16.65" y2="16.65" /><line x1="11" y1="8" x2="11" y2="14" /><line x1="8" y1="11" x2="14" y2="11" /></>,
|
||||
zoom_out: <><circle cx="11" cy="11" r="7" /><line x1="21" y1="21" x2="16.65" y2="16.65" /><line x1="8" y1="11" x2="14" y2="11" /></>,
|
||||
maximize: <><path d="M8 3H5a2 2 0 00-2 2v3M21 8V5a2 2 0 00-2-2h-3M3 16v3a2 2 0 002 2h3M16 21h3a2 2 0 002-2v-3" /></>,
|
||||
slack: <><rect x="13" y="2" width="3" height="8" rx="1.5" /><rect x="2" y="13" width="8" height="3" rx="1.5" /><rect x="14" y="14" width="8" height="3" rx="1.5" /><rect x="8" y="8" width="3" height="8" rx="1.5" /></>,
|
||||
database: <><ellipse cx="12" cy="5" rx="9" ry="3" /><path d="M3 5v7c0 1.66 4.03 3 9 3s9-1.34 9-3V5M3 12v7c0 1.66 4.03 3 9 3s9-1.34 9-3v-7" /></>,
|
||||
mail: <><rect x="2" y="4" width="20" height="16" rx="2" /><path d="M2 6l10 7 10-7" /></>,
|
||||
filter: <path d="M3 4h18l-7 9v6l-4-2v-4L3 4z" />,
|
||||
star: <polygon points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2" />,
|
||||
linear: <><rect x="3" y="3" width="18" height="18" rx="4" /><path d="M7 11l5 5M7 15l3 3M7 7l10 10M11 7l6 6M15 7l2 2" /></>,
|
||||
clock: <><circle cx="12" cy="12" r="9" /><polyline points="12 7 12 12 16 14" /></>,
|
||||
send: <><path d="M22 2L11 13M22 2l-7 20-4-9-9-4 20-7z" /></>,
|
||||
terminal: <><path d="M4 17l6-6-6-6M12 19h8" /></>,
|
||||
logout: <><path d="M9 21H5a2 2 0 01-2-2V5a2 2 0 012-2h4M16 17l5-5-5-5M21 12H9" /></>,
|
||||
};
|
||||
|
||||
return (
|
||||
<svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={stroke} strokeLinecap="round" strokeLinejoin="round" style={{display: 'block', flexShrink: 0}}>
|
||||
{paths[name]}
|
||||
</svg>
|
||||
);
|
||||
};
|
||||
|
||||
// Arcrun wordmark — custom "arc" glyph made of an arc stroke + ascending dot/node
|
||||
const Logo = ({ size = 'md', onClick }) => {
|
||||
const dims = size === 'sm' ? { w: 18, h: 18, f: 10 } : size === 'lg' ? { w: 28, h: 28, f: 14 } : { w: 22, h: 22, f: 12 };
|
||||
return (
|
||||
<div className="logo" onClick={onClick}>
|
||||
<span className="logo-mark" style={{width: dims.w, height: dims.h}}>
|
||||
<svg width={dims.w} height={dims.h} viewBox="0 0 24 24" fill="none">
|
||||
<path d="M5 17 Q 12 4, 19 17" stroke="white" strokeWidth="2.4" strokeLinecap="round" fill="none" opacity="0.95" />
|
||||
<circle cx="19" cy="17" r="2.2" fill="white" />
|
||||
</svg>
|
||||
</span>
|
||||
<span>Arcrun</span>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
// App icon with gradient background
|
||||
const AppIcon = ({ tone = 'indigo', children, size = 38 }) => {
|
||||
const tones = {
|
||||
indigo: 'linear-gradient(135deg, #6366F1, #8B5CF6)',
|
||||
orange: 'linear-gradient(135deg, #F59E0B, #EF4444)',
|
||||
green: 'linear-gradient(135deg, #10B981, #22C55E)',
|
||||
pink: 'linear-gradient(135deg, #EC4899, #8B5CF6)',
|
||||
blue: 'linear-gradient(135deg, #3B82F6, #06B6D4)',
|
||||
slate: 'linear-gradient(135deg, #475569, #334155)',
|
||||
amber: 'linear-gradient(135deg, #F59E0B, #D97706)',
|
||||
};
|
||||
return (
|
||||
<div className="app-icon" style={{ background: tones[tone], width: size, height: size, color: 'white' }}>
|
||||
{children}
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
Object.assign(window, { Icon, Logo, AppIcon });
|
||||
@@ -0,0 +1,95 @@
|
||||
# Chat
|
||||
|
||||
_Started 2026-04-23 04:37 UTC_
|
||||
|
||||
---
|
||||
|
||||
## User
|
||||
|
||||
|
||||
|
||||
## Assistant
|
||||
|
||||
I'll design Arcrun as a cohesive 5-screen system. Let me plan and build this as an interactive prototype with all screens navigable.
|
||||
|
||||
_[tool: update_todos]_
|
||||
|
||||
Let me plan the architecture. I'll build a single HTML file with React, using multiple JSX component files, with screen navigation via state.
|
||||
|
||||
Design system note: I'll use Inter, electric indigo #6366F1 primary, #0F0F0F bg, #1A1A1A cards, with subtle indigo→violet gradients on CTAs. Dark, minimal, developer-focused. "Arcrun" wordmark will be original — a stylized "↯" or arc mark paired with the name.
|
||||
|
||||
Let me start building.
|
||||
|
||||
_[tool: write_file]_
|
||||
|
||||
_[tool: write_file]_
|
||||
|
||||
Now the primitives and chrome components:
|
||||
|
||||
_[tool: write_file]_
|
||||
|
||||
_[tool: write_file]_
|
||||
|
||||
_[tool: snip]_
|
||||
|
||||
Now the 5 screens. Let me write them concisely.
|
||||
|
||||
_[tool: write_file]_
|
||||
|
||||
_[tool: write_file]_
|
||||
|
||||
_[tool: snip]_
|
||||
|
||||
_[tool: write_file]_
|
||||
|
||||
_[tool: write_file]_
|
||||
|
||||
_[tool: snip]_
|
||||
|
||||
_[tool: write_file]_
|
||||
|
||||
_[tool: write_file]_
|
||||
|
||||
_[tool: snip]_
|
||||
|
||||
_[tool: update_todos]_
|
||||
|
||||
_[tool: register_assets]_
|
||||
|
||||
_[tool: done]_
|
||||
|
||||
_[tool: snip]_
|
||||
|
||||
_[tool: list_files]_
|
||||
|
||||
The file exists. The error may have been transient. Let me verify by checking the page loads.
|
||||
|
||||
_[tool: show_html]_
|
||||
|
||||
_[tool: snip]_
|
||||
|
||||
_[tool: done]_
|
||||
|
||||
The CSS exists but isn't loading through the preview path. Let me inline it to eliminate the dependency.
|
||||
|
||||
_[tool: read_file]_
|
||||
|
||||
_[tool: run_script]_
|
||||
|
||||
_[tool: snip]_
|
||||
|
||||
_[tool: done]_
|
||||
|
||||
_[tool: fork_verifier_agent]_
|
||||
|
||||
Built **Arcrun** as a cohesive 5-screen dark-mode prototype — Landing, Auth, API Keys, Dashboard, and Workflow Viewer — all navigable via the floating screen switcher at the bottom.
|
||||
|
||||
**Highlights**
|
||||
- **Landing** — hero with grid/glow bg, two-path split (developer terminal w/ npm·pip·bun tabs + Claude-style chat preview showing an Arcrun tool call)
|
||||
- **Auth** — centered card, Sign in / Sign up tabs, GitHub + Google OAuth, email + password
|
||||
- **API Keys** — first-time key callout with copy + hide-again warning, full keys table with live status toggles
|
||||
- **Dashboard** — sidebar shell, 3-col apps grid (+ empty-state card), workflows table below
|
||||
- **Workflow Viewer** — full-bleed dark canvas, 8 connected nodes with left-to-right bezier arrows, selectable with detail panel (I/O schema, editable triplet config for the AI node), minimap + zoom controls, prominent "Edit in Claude" CTA
|
||||
|
||||
Screen state persists in localStorage so reloads land you where you were.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,128 @@
|
||||
const ApiKeys = ({ onNav }) => {
|
||||
const [newKeyCopied, setNewKeyCopied] = React.useState(false);
|
||||
const [keys, setKeys] = React.useState([
|
||||
{ id: 'k_dev', name: 'Local Development', prefix: 'ar_dev_', created: 'Mar 12, 2026', lastUsed: '2 min ago', active: true },
|
||||
{ id: 'k_prod', name: 'Production — Northwind API', prefix: 'ar_live_', created: 'Feb 3, 2026', lastUsed: '12 sec ago', active: true },
|
||||
{ id: 'k_staging', name: 'Staging — Vercel', prefix: 'ar_test_', created: 'Jan 28, 2026', lastUsed: '4 hours ago', active: true },
|
||||
{ id: 'k_ci', name: 'CI/CD (GitHub Actions)', prefix: 'ar_live_', created: 'Jan 10, 2026', lastUsed: 'Yesterday', active: false },
|
||||
{ id: 'k_old', name: 'Legacy — Zapier import', prefix: 'ar_live_', created: 'Nov 4, 2025', lastUsed: '3 weeks ago', active: false, revoked: true },
|
||||
]);
|
||||
|
||||
const newKey = 'ar_live_sk_7x9Qf2vLm8nR4TpW6ZjKc3bEhN1aSyU5oP0dI';
|
||||
|
||||
const copyKey = () => {
|
||||
setNewKeyCopied(true);
|
||||
setTimeout(() => setNewKeyCopied(false), 1800);
|
||||
};
|
||||
|
||||
const toggleKey = (id) => {
|
||||
setKeys(keys.map(k => k.id === id ? { ...k, active: !k.active } : k));
|
||||
};
|
||||
|
||||
return (
|
||||
<div className="shell">
|
||||
<Sidebar current="keys" onNav={onNav} />
|
||||
<div className="main">
|
||||
<div className="main-head">
|
||||
<div>
|
||||
<div className="crumb">
|
||||
<span>Workspace</span>
|
||||
<span className="sep"><Icon name="chevron_right" size={11} /></span>
|
||||
<span>Settings</span>
|
||||
</div>
|
||||
<h1>API Keys</h1>
|
||||
<div className="sub">Scoped credentials for calling the Arcrun API from your code and CI.</div>
|
||||
</div>
|
||||
<div className="flex gap-8">
|
||||
<button className="btn btn-secondary"><Icon name="book" size={14} /> API docs</button>
|
||||
<button className="btn btn-primary"><Icon name="plus" size={14} /> Create new key</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="main-body" style={{maxWidth: 1080}}>
|
||||
<div className="new-key-box">
|
||||
<div className="warn-row">
|
||||
<span className="warn-icon"><Icon name="warn" size={12} /></span>
|
||||
<span><strong style={{color: '#FBBF24'}}>Save this key now.</strong> For security, we won't show it again — if you lose it, you'll need to create a new one.</span>
|
||||
</div>
|
||||
<h3>Your new API key</h3>
|
||||
<p className="desc">Key named <strong style={{color: 'var(--text)'}}>"Production — Northwind API"</strong> · created just now · all scopes</p>
|
||||
<div className="key-display">
|
||||
<span className="key-val">{newKey}</span>
|
||||
<button className={`copy-btn ${newKeyCopied ? 'copied' : ''}`} onClick={copyKey}>
|
||||
<Icon name={newKeyCopied ? 'check' : 'copy'} size={12} />
|
||||
{newKeyCopied ? 'Copied' : 'Copy'}
|
||||
</button>
|
||||
</div>
|
||||
<div style={{marginTop: 14, display: 'flex', gap: 16, fontSize: 12, color: 'var(--text-mute)', alignItems: 'center'}}>
|
||||
<span className="flex gap-6" style={{alignItems: 'center'}}><Icon name="check" size={12} /> Full workspace access</span>
|
||||
<span className="flex gap-6" style={{alignItems: 'center'}}><Icon name="clock" size={12} /> Never expires</span>
|
||||
<span style={{marginLeft: 'auto'}}><span className="link">Add expiry or restrict scopes →</span></span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="section-head">
|
||||
<div>
|
||||
<h2>All keys</h2>
|
||||
<div className="subtle" style={{marginTop: 2}}>{keys.filter(k => !k.revoked).length} active · {keys.filter(k => k.revoked).length} revoked</div>
|
||||
</div>
|
||||
<div className="flex gap-8">
|
||||
<button className="btn btn-secondary btn-sm"><Icon name="filter" size={12} /> Filter</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="table-wrap">
|
||||
<table className="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th style={{width: '32%'}}>Name</th>
|
||||
<th>Key</th>
|
||||
<th>Created</th>
|
||||
<th>Last used</th>
|
||||
<th>Status</th>
|
||||
<th style={{width: 60, textAlign: 'right'}}></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{keys.map(k => (
|
||||
<tr key={k.id}>
|
||||
<td>
|
||||
<div style={{fontWeight: 500, fontSize: 13.5}}>{k.name}</div>
|
||||
</td>
|
||||
<td className="mono">{k.prefix}••••{k.id.slice(-4)}</td>
|
||||
<td className="dim" style={{fontSize: 12.5}}>{k.created}</td>
|
||||
<td className="dim" style={{fontSize: 12.5}}>{k.lastUsed}</td>
|
||||
<td>
|
||||
{k.revoked ? (
|
||||
<span className="pill revoked"><span className="pdot" /> Revoked</span>
|
||||
) : (
|
||||
<div className="flex gap-8" style={{alignItems: 'center'}}>
|
||||
<span className={`toggle ${k.active ? 'on' : ''}`} onClick={() => toggleKey(k.id)} />
|
||||
<span className={`pill ${k.active ? 'active' : 'idle'}`}>
|
||||
<span className="pdot" /> {k.active ? 'Active' : 'Paused'}
|
||||
</span>
|
||||
</div>
|
||||
)}
|
||||
</td>
|
||||
<td style={{textAlign: 'right'}}>
|
||||
{!k.revoked && (
|
||||
<button className="btn btn-danger-ghost btn-sm"><Icon name="trash" size={12} /></button>
|
||||
)}
|
||||
</td>
|
||||
</tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<div style={{marginTop: 18, fontSize: 12, color: 'var(--text-mute)', display: 'flex', alignItems: 'center', gap: 8}}>
|
||||
<Icon name="warn" size={12} />
|
||||
<span>Revoking a key stops all in-flight requests within 60 seconds. This cannot be undone.</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
window.ApiKeys = ApiKeys;
|
||||
@@ -0,0 +1,90 @@
|
||||
const Auth = ({ onNav }) => {
|
||||
const [mode, setMode] = React.useState('signin');
|
||||
const [email, setEmail] = React.useState('');
|
||||
const [pw, setPw] = React.useState('');
|
||||
const [remember, setRemember] = React.useState(true);
|
||||
|
||||
const submit = (e) => { e.preventDefault(); onNav('dashboard'); };
|
||||
|
||||
return (
|
||||
<div className="auth-wrap">
|
||||
<div className="hero-bg" />
|
||||
<div className="hero-bg-grid" />
|
||||
|
||||
<div style={{position: 'absolute', top: 24, left: 24, zIndex: 2}}>
|
||||
<Logo onClick={() => onNav('landing')} />
|
||||
</div>
|
||||
|
||||
<div className="auth-card">
|
||||
<h2 className="auth-h1">{mode === 'signin' ? 'Welcome back' : 'Create your account'}</h2>
|
||||
<p className="auth-sub">{mode === 'signin' ? 'Sign in to your Arcrun workspace.' : 'Start building AI workflows in minutes.'}</p>
|
||||
|
||||
<div className="tabs">
|
||||
<button className={mode === 'signin' ? 'active' : ''} onClick={() => setMode('signin')}>Sign in</button>
|
||||
<button className={mode === 'signup' ? 'active' : ''} onClick={() => setMode('signup')}>Sign up</button>
|
||||
</div>
|
||||
|
||||
<div className="oauth-row">
|
||||
<button className="oauth-btn github" onClick={() => onNav('dashboard')}>
|
||||
<Icon name="github" size={17} stroke={0} /> Continue with GitHub
|
||||
</button>
|
||||
<button className="oauth-btn google" onClick={() => onNav('dashboard')}>
|
||||
<Icon name="google" size={15} stroke={0} /> Continue with Google
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<div className="divider">or continue with email</div>
|
||||
|
||||
<form onSubmit={submit}>
|
||||
{mode === 'signup' && (
|
||||
<div className="field">
|
||||
<label>Full name</label>
|
||||
<input className="input" type="text" placeholder="Maya Rivera" />
|
||||
</div>
|
||||
)}
|
||||
<div className="field">
|
||||
<label>Work email</label>
|
||||
<input className="input" type="email" placeholder="you@company.com" value={email} onChange={e => setEmail(e.target.value)} />
|
||||
</div>
|
||||
<div className="field">
|
||||
<div className="field-row">
|
||||
<label>Password</label>
|
||||
{mode === 'signin' && <span className="link">Forgot password?</span>}
|
||||
</div>
|
||||
<input className="input" type="password" placeholder="••••••••••" value={pw} onChange={e => setPw(e.target.value)} />
|
||||
</div>
|
||||
|
||||
{mode === 'signin' && (
|
||||
<div style={{display: 'flex', alignItems: 'center', gap: 8, fontSize: 12.5, color: 'var(--text-dim)', marginBottom: 14}}>
|
||||
<div onClick={() => setRemember(!remember)}
|
||||
style={{width: 15, height: 15, borderRadius: 4, border: '1px solid var(--line-2)',
|
||||
background: remember ? 'var(--primary)' : 'transparent',
|
||||
display: 'flex', alignItems: 'center', justifyContent: 'center', cursor: 'pointer'}}>
|
||||
{remember && <Icon name="check" size={11} />}
|
||||
</div>
|
||||
<span onClick={() => setRemember(!remember)} style={{cursor: 'pointer'}}>Keep me signed in for 30 days</span>
|
||||
</div>
|
||||
)}
|
||||
|
||||
<button className="btn btn-primary auth-submit btn-lg" type="submit">
|
||||
{mode === 'signin' ? 'Sign in' : 'Create account'} <Icon name="arrow_right" size={14} />
|
||||
</button>
|
||||
</form>
|
||||
|
||||
{mode === 'signup' && (
|
||||
<p style={{fontSize: 11.5, color: 'var(--text-mute)', textAlign: 'center', marginTop: 14, lineHeight: 1.5}}>
|
||||
By signing up, you agree to our <span className="link" style={{fontSize: 11.5}}>Terms</span> and <span className="link" style={{fontSize: 11.5}}>Privacy Policy</span>.
|
||||
</p>
|
||||
)}
|
||||
|
||||
<div className="auth-foot">
|
||||
{mode === 'signin'
|
||||
? <>New to Arcrun? <span className="link" onClick={() => setMode('signup')}>Create an account</span></>
|
||||
: <>Already have an account? <span className="link" onClick={() => setMode('signin')}>Sign in</span></>}
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
window.Auth = Auth;
|
||||
@@ -0,0 +1,126 @@
|
||||
const Dashboard = ({ onNav }) => {
|
||||
const apps = [
|
||||
{ id: 'digest', name: 'Weekly Digest', desc: 'Summarize customer activity into a Monday email for the revenue team.', icon: 'mail', tone: 'indigo' },
|
||||
{ id: 'triage', name: 'Support Triage', desc: 'Classify inbound tickets, attach context from the CRM, and route.', icon: 'filter', tone: 'orange' },
|
||||
{ id: 'seo', name: 'SEO Brief Generator', desc: 'Turn a keyword into a draft brief with outline, FAQs, and SERP notes.', icon: 'search', tone: 'green' },
|
||||
{ id: 'slack', name: 'Standup Bot', desc: 'Collect Linear updates and post a tidy engineering standup to Slack.', icon: 'slack', tone: 'pink' },
|
||||
{ id: 'doc', name: 'Docs Sync', desc: 'Keep Notion runbooks in sync with the production API surface.', icon: 'book', tone: 'blue' },
|
||||
];
|
||||
|
||||
const workflows = [
|
||||
{ id: 'digest_weekly', name: 'digest/weekly', nodes: 9, modified: '2 hours ago', runs: '147 runs', status: 'healthy' },
|
||||
{ id: 'triage_inbound', name: 'triage/inbound-email', nodes: 14, modified: 'Yesterday', runs: '2,318 runs', status: 'healthy' },
|
||||
{ id: 'seo_brief', name: 'seo/brief-from-keyword', nodes: 7, modified: '3 days ago', runs: '42 runs', status: 'healthy' },
|
||||
{ id: 'standup', name: 'slack/standup-collector', nodes: 6, modified: '1 week ago', runs: '24 runs', status: 'idle' },
|
||||
{ id: 'docs_sync', name: 'docs/sync-notion', nodes: 11, modified: '2 weeks ago', runs: '8 runs', status: 'failed' },
|
||||
];
|
||||
|
||||
return (
|
||||
<div className="shell">
|
||||
<Sidebar current="dashboard" onNav={onNav} />
|
||||
<div className="main">
|
||||
<div className="main-head">
|
||||
<div>
|
||||
<div className="crumb">
|
||||
<span>Northwind</span>
|
||||
<span className="sep"><Icon name="chevron_right" size={11} /></span>
|
||||
<span>Dashboard</span>
|
||||
</div>
|
||||
<h1>Welcome back, Maya</h1>
|
||||
<div className="sub">5 apps running · 12 workflows · 2,538 runs this week</div>
|
||||
</div>
|
||||
<div className="flex gap-8">
|
||||
<button className="btn btn-secondary"><Icon name="book" size={14} /> Templates</button>
|
||||
<button className="btn btn-primary"><Icon name="plus" size={14} /> New app</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="main-body">
|
||||
{/* Apps grid */}
|
||||
<div className="section-head">
|
||||
<div>
|
||||
<h2>My Apps</h2>
|
||||
<div className="subtle" style={{marginTop: 2}}>Packaged workflows your team can run from chat or code</div>
|
||||
</div>
|
||||
<span className="subtle">{apps.length} apps</span>
|
||||
</div>
|
||||
|
||||
<div className="apps-grid">
|
||||
{apps.map(a => (
|
||||
<div key={a.id} className="app-card">
|
||||
<AppIcon tone={a.tone}><Icon name={a.icon} size={17} /></AppIcon>
|
||||
<h4>{a.name}</h4>
|
||||
<p className="dsc">{a.desc}</p>
|
||||
<div className="row">
|
||||
<a className="open" onClick={() => onNav('workflow')}>Open app <Icon name="arrow_right" size={12} /></a>
|
||||
<button className="chip-btn">
|
||||
<Icon name="spark" size={11} /> Edit in Claude
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
))}
|
||||
<div className="app-card app-empty">
|
||||
<div className="plus"><Icon name="plus" size={16} /></div>
|
||||
<div style={{fontSize: 13, fontWeight: 500}}>Create new app</div>
|
||||
<div style={{fontSize: 12, opacity: 0.75}}>Start from scratch or template</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{/* Workflows */}
|
||||
<div className="wf-table">
|
||||
<div className="section-head">
|
||||
<div>
|
||||
<h2>My Workflows</h2>
|
||||
<div className="subtle" style={{marginTop: 2}}>The graphs that power your apps</div>
|
||||
</div>
|
||||
<div className="flex gap-8">
|
||||
<button className="btn btn-secondary btn-sm"><Icon name="filter" size={12} /> All workflows</button>
|
||||
<button className="btn btn-secondary btn-sm" onClick={() => onNav('workflow')}><Icon name="plus" size={12} /> New</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="table-wrap">
|
||||
<table className="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th style={{width: '34%'}}>Workflow</th>
|
||||
<th>Nodes</th>
|
||||
<th>Last modified</th>
|
||||
<th>Activity</th>
|
||||
<th>Status</th>
|
||||
<th style={{width: 100, textAlign: 'right'}}></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{workflows.map(w => (
|
||||
<tr key={w.id}>
|
||||
<td>
|
||||
<div className="wf-row-name">
|
||||
<span className="dot" />
|
||||
<span className="mono" style={{fontSize: 13}}>{w.name}</span>
|
||||
</div>
|
||||
</td>
|
||||
<td className="dim">{w.nodes}</td>
|
||||
<td className="dim" style={{fontSize: 12.5}}>{w.modified}</td>
|
||||
<td className="dim" style={{fontSize: 12.5}}>{w.runs}</td>
|
||||
<td>
|
||||
<span className={`pill ${w.status === 'healthy' ? 'active' : w.status === 'failed' ? 'revoked' : 'idle'}`}>
|
||||
<span className="pdot" /> {w.status}
|
||||
</span>
|
||||
</td>
|
||||
<td style={{textAlign: 'right'}}>
|
||||
<button className="btn btn-secondary btn-sm" onClick={() => onNav('workflow')}>View</button>
|
||||
</td>
|
||||
</tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
window.Dashboard = Dashboard;
|
||||
@@ -0,0 +1,168 @@
|
||||
const Landing = ({ onNav }) => {
|
||||
const [installer, setInstaller] = React.useState('npm');
|
||||
const installCmds = {
|
||||
npm: '$ npm install arcrun',
|
||||
pip: '$ pip install arcrun',
|
||||
bun: '$ bun add arcrun',
|
||||
};
|
||||
|
||||
return (
|
||||
<div>
|
||||
<TopNav onNav={onNav} current="landing" />
|
||||
|
||||
<div className="container">
|
||||
<section className="hero">
|
||||
<div className="hero-bg" />
|
||||
<div className="hero-bg-grid" />
|
||||
<div className="hero-eyebrow">
|
||||
<span className="dot" />
|
||||
<span>Now in public beta — MCP-native</span>
|
||||
</div>
|
||||
<h1>Build AI workflows<br/><span className="grad">without the glue code.</span></h1>
|
||||
<p className="sub">Connect your tools, automate your work. Orchestrate workflows from Claude.ai, your IDE, or a few lines of code — Arcrun handles auth, retries, and state.</p>
|
||||
<div className="hero-ctas">
|
||||
<button className="btn btn-primary btn-lg" onClick={() => onNav('auth')}>
|
||||
Start free <Icon name="arrow_right" size={15} />
|
||||
</button>
|
||||
<button className="btn btn-secondary btn-lg">
|
||||
<Icon name="book" size={14} /> Read the docs
|
||||
</button>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section className="paths">
|
||||
{/* Developer path */}
|
||||
<div className="path-card">
|
||||
<div className="path-label">
|
||||
<Icon name="terminal" size={13} /> For Developers
|
||||
</div>
|
||||
<h3>Three lines, any runtime.</h3>
|
||||
<p className="lede">Install once, call Arcrun from Node, Python, or your edge runtime. OAuth, rate limits, and retries are handled.</p>
|
||||
|
||||
<div className="install-tabs">
|
||||
{Object.keys(installCmds).map(k => (
|
||||
<button key={k} className={installer === k ? 'active' : ''} onClick={() => setInstaller(k)}>{k}</button>
|
||||
))}
|
||||
</div>
|
||||
|
||||
<div className="terminal" style={{marginBottom: 12}}>
|
||||
<div className="terminal-head">
|
||||
<div className="dots"><span/><span/><span/></div>
|
||||
<div className="title">terminal</div>
|
||||
</div>
|
||||
<div className="terminal-body">
|
||||
<div><span className="dim">{installCmds[installer]}</span></div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="terminal">
|
||||
<div className="terminal-head">
|
||||
<div className="dots"><span/><span/><span/></div>
|
||||
<div className="title">{installer === 'pip' ? 'app.py' : 'app.ts'}</div>
|
||||
</div>
|
||||
<div className="terminal-body">
|
||||
{installer === 'pip' ? (
|
||||
<>
|
||||
<div><span className="c1">from</span> <span className="c2">arcrun</span> <span className="c1">import</span> <span className="c2">Arcrun</span></div>
|
||||
<div className="sp-4"/>
|
||||
<div><span className="c2">client</span> = <span className="c4">Arcrun</span>(<span className="c2">token</span>=<span className="c2">os</span>.<span className="c4">getenv</span>(<span className="c3">"ARCRUN_KEY"</span>))</div>
|
||||
<div><span className="c2">run</span> = <span className="c2">client</span>.<span className="c4">run</span>(<span className="c3">"digest/weekly"</span>, <span className="c2">inputs</span>={'{'}<span className="c3">"user"</span>: <span className="c3">"u_219"</span>{'}'})</div>
|
||||
</>
|
||||
) : (
|
||||
<>
|
||||
<div><span className="c1">import</span> {'{'} <span className="c2">Arcrun</span> {'}'} <span className="c1">from</span> <span className="c3">"arcrun"</span>;</div>
|
||||
<div className="sp-4"/>
|
||||
<div><span className="c1">const</span> <span className="c2">client</span> = <span className="c1">new</span> <span className="c4">Arcrun</span>({'{'} <span className="c2">token</span>: <span className="c2">process</span>.<span className="c2">env</span>.<span className="c2">ARCRUN_KEY</span> {'}'});</div>
|
||||
<div><span className="c1">const</span> <span className="c2">run</span> = <span className="c1">await</span> <span className="c2">client</span>.<span className="c4">run</span>(<span className="c3">"digest/weekly"</span>, {'{'} <span className="c2">user</span>: <span className="c3">"u_219"</span> {'}'});</div>
|
||||
</>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="sp-16" />
|
||||
<div className="flex gap-12" style={{fontSize: 12.5, color: 'var(--text-mute)'}}>
|
||||
<span className="flex gap-6" style={{alignItems: 'center'}}><Icon name="check" size={12} /> Typed SDKs</span>
|
||||
<span className="flex gap-6" style={{alignItems: 'center'}}><Icon name="check" size={12} /> Idempotent runs</span>
|
||||
<span className="flex gap-6" style={{alignItems: 'center'}}><Icon name="check" size={12} /> Self-host ready</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{/* Everyone path */}
|
||||
<div className="path-card">
|
||||
<div className="path-label">
|
||||
<Icon name="spark" size={13} /> For Everyone
|
||||
</div>
|
||||
<h3>Talk to your workflows.</h3>
|
||||
<p className="lede">Install Arcrun inside your AI assistant and run your apps by asking. Trigger workflows, fetch data, or draft messages — in plain English.</p>
|
||||
|
||||
<div className="chat-preview">
|
||||
<div className="chat-head">
|
||||
<span className="brand-dot">AI</span>
|
||||
<span>Your assistant — Arcrun connected</span>
|
||||
<span style={{marginLeft: 'auto'}} className="pill active"><span className="pdot" />2 apps</span>
|
||||
</div>
|
||||
<div className="chat-body">
|
||||
<div className="chat-msg user">
|
||||
<div className="avatar">M</div>
|
||||
<div className="bubble">Send this week's customer digest to the revenue team.</div>
|
||||
</div>
|
||||
<div className="chat-msg ai">
|
||||
<div className="avatar">A</div>
|
||||
<div className="bubble">
|
||||
Running <span style={{color: 'var(--primary)', fontWeight: 500}}>digest/weekly</span> for 147 accounts, then posting to #revenue.
|
||||
<div className="tool-card">
|
||||
<div className="tool-icon">AR</div>
|
||||
<div className="tool-meta">
|
||||
<div className="tool-name">arcrun · digest/weekly</div>
|
||||
<div className="tool-sub">4 of 5 steps complete · 00:12 elapsed</div>
|
||||
</div>
|
||||
<span className="pill active"><span className="pdot" />running</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div className="chat-input">
|
||||
<span>Reply to your assistant…</span>
|
||||
<span className="caret" />
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="sp-16" />
|
||||
<div className="flex gap-12" style={{fontSize: 12.5, color: 'var(--text-mute)'}}>
|
||||
<span className="flex gap-6" style={{alignItems: 'center'}}><Icon name="check" size={12} /> One-click connect</span>
|
||||
<span className="flex gap-6" style={{alignItems: 'center'}}><Icon name="check" size={12} /> Works in your IDE</span>
|
||||
<span className="flex gap-6" style={{alignItems: 'center'}}><Icon name="check" size={12} /> Audit trail</span>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section className="strip">
|
||||
<div className="cell">
|
||||
<div className="ico"><Icon name="bolt" size={15} /></div>
|
||||
<h4>Run anywhere</h4>
|
||||
<p>Node, Python, Deno, Bun, Cloudflare Workers. One API, same semantics.</p>
|
||||
</div>
|
||||
<div className="cell">
|
||||
<div className="ico"><Icon name="workflow" size={15} /></div>
|
||||
<h4>Composable steps</h4>
|
||||
<p>Model calls, HTTP, database, branching — wire them visually or in code.</p>
|
||||
</div>
|
||||
<div className="cell">
|
||||
<div className="ico"><Icon name="key" size={15} /></div>
|
||||
<h4>Scoped keys</h4>
|
||||
<p>Per-workflow API keys with fine-grained scopes and live revocation.</p>
|
||||
</div>
|
||||
<div className="cell">
|
||||
<div className="ico"><Icon name="eye" size={15} /></div>
|
||||
<h4>Observable</h4>
|
||||
<p>Every run is replayable. Inspect inputs, outputs, and token usage.</p>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<Footer onNav={onNav} />
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
window.Landing = Landing;
|
||||
@@ -0,0 +1,255 @@
|
||||
const WorkflowViewer = ({ onNav }) => {
|
||||
const nodes = [
|
||||
{ id: 'trigger', x: 60, y: 260, title: 'Weekly Schedule', type: 'trigger', badge: 'CRON', icon: 'clock', tone: '#22C55E',
|
||||
inputs: [], outputs: [{k: 'timestamp', t: 'ISO8601'}, {k: 'runId', t: 'string'}] },
|
||||
{ id: 'fetch', x: 320, y: 140, title: 'Fetch Accounts', type: 'database.query', badge: 'DB', icon: 'database', tone: '#3B82F6',
|
||||
inputs: [{k: 'segment', t: 'string'}], outputs: [{k: 'accounts', t: 'Account[]'}, {k: 'count', t: 'number'}] },
|
||||
{ id: 'events', x: 320, y: 380, title: 'Pull Events', type: 'segment.events', badge: 'API', icon: 'bolt', tone: '#F59E0B',
|
||||
inputs: [{k: 'since', t: 'ISO8601'}], outputs: [{k: 'events', t: 'Event[]'}] },
|
||||
{ id: 'summarize', x: 600, y: 260, title: 'Summarize with Claude', type: 'ai.completion', badge: 'AI', icon: 'spark', tone: '#8B5CF6',
|
||||
inputs: [{k: 'accounts', t: 'Account[]'}, {k: 'events', t: 'Event[]'}, {k: 'prompt', t: 'string'}],
|
||||
outputs: [{k: 'digest', t: 'Digest'}, {k: 'tokens', t: 'number'}] },
|
||||
{ id: 'filter', x: 880, y: 160, title: 'Filter — priority ≥ 2', type: 'logic.filter', badge: 'IF', icon: 'filter', tone: '#64748B',
|
||||
inputs: [{k: 'digest', t: 'Digest'}], outputs: [{k: 'items', t: 'Item[]'}] },
|
||||
{ id: 'slack', x: 1140, y: 100, title: 'Post to #revenue', type: 'slack.message', badge: 'OUT', icon: 'slack', tone: '#EC4899',
|
||||
inputs: [{k: 'channel', t: 'string'}, {k: 'blocks', t: 'Block[]'}], outputs: [{k: 'ts', t: 'string'}] },
|
||||
{ id: 'mail', x: 1140, y: 260, title: 'Email Digest', type: 'mail.send', badge: 'OUT', icon: 'mail', tone: '#6366F1',
|
||||
inputs: [{k: 'to', t: 'string[]'}, {k: 'subject', t: 'string'}, {k: 'html', t: 'string'}], outputs: [{k: 'messageId', t: 'string'}] },
|
||||
{ id: 'log', x: 880, y: 400, title: 'Log run metadata', type: 'arcrun.log', badge: 'LOG', icon: 'terminal', tone: '#475569',
|
||||
inputs: [{k: 'runId', t: 'string'}, {k: 'stats', t: 'Stats'}], outputs: [] },
|
||||
];
|
||||
|
||||
const edges = [
|
||||
['trigger', 'fetch'],
|
||||
['trigger', 'events'],
|
||||
['fetch', 'summarize'],
|
||||
['events', 'summarize'],
|
||||
['summarize', 'filter'],
|
||||
['summarize', 'log'],
|
||||
['filter', 'slack'],
|
||||
['filter', 'mail'],
|
||||
];
|
||||
|
||||
const [selectedId, setSelectedId] = React.useState('summarize');
|
||||
const [title, setTitle] = React.useState('digest/weekly');
|
||||
const [zoom, setZoom] = React.useState(100);
|
||||
|
||||
const selected = nodes.find(n => n.id === selectedId);
|
||||
|
||||
// Edit triplet inline (for the summarize node's prompt config)
|
||||
const [triplet, setTriplet] = React.useState({
|
||||
model: 'claude-haiku-4-5',
|
||||
temperature: '0.3',
|
||||
prompt: 'Summarize this week\'s account activity for the revenue team.',
|
||||
});
|
||||
|
||||
// Measure node widths for edge endpoint accuracy
|
||||
const nodeRefs = React.useRef({});
|
||||
const [sizes, setSizes] = React.useState({});
|
||||
React.useEffect(() => {
|
||||
const ns = {};
|
||||
for (const n of nodes) {
|
||||
const el = nodeRefs.current[n.id];
|
||||
if (el) ns[n.id] = { w: el.offsetWidth, h: el.offsetHeight };
|
||||
}
|
||||
setSizes(ns);
|
||||
}, []);
|
||||
|
||||
const getPort = (id, side) => {
|
||||
const n = nodes.find(x => x.id === id);
|
||||
const sz = sizes[id] || { w: 200, h: 60 };
|
||||
return {
|
||||
x: side === 'out' ? n.x + sz.w : n.x,
|
||||
y: n.y + sz.h / 2,
|
||||
};
|
||||
};
|
||||
|
||||
return (
|
||||
<div className="wf-viewer">
|
||||
<div className="wf-topbar">
|
||||
<div className="back" onClick={() => onNav('dashboard')} title="Back to dashboard">
|
||||
<Icon name="arrow_left" size={16} />
|
||||
</div>
|
||||
<Logo size="sm" onClick={() => onNav('landing')} />
|
||||
<div className="sep" />
|
||||
<div className="wf-breadcrumb">
|
||||
<span className="cr" onClick={() => onNav('dashboard')}>Workflows</span>
|
||||
<Icon name="chevron_right" size={11} />
|
||||
<input
|
||||
className="wf-title mono"
|
||||
value={title}
|
||||
onChange={e => setTitle(e.target.value)}
|
||||
/>
|
||||
</div>
|
||||
<span className="wf-saved">
|
||||
<span style={{width: 6, height: 6, borderRadius: '50%', background: '#22C55E', boxShadow: '0 0 0 3px rgba(34,197,94,0.18)'}} />
|
||||
Saved · 2m ago
|
||||
</span>
|
||||
<div className="spacer" />
|
||||
<button className="btn btn-ghost btn-sm"><Icon name="share" size={13} /> Share</button>
|
||||
<button className="btn btn-secondary btn-sm"><Icon name="download" size={13} /> Export YAML</button>
|
||||
<button className="wf-edit-in-claude">
|
||||
<Icon name="spark" size={13} /> Edit in Claude <Icon name="external" size={12} />
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<div className="wf-canvas">
|
||||
<svg className="wf-edges" width="100%" height="100%">
|
||||
<defs>
|
||||
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
|
||||
<path d="M0,0 L10,5 L0,10 z" fill="#6366F1" />
|
||||
</marker>
|
||||
<marker id="arrow-dim" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
|
||||
<path d="M0,0 L10,5 L0,10 z" fill="#3a3a3a" />
|
||||
</marker>
|
||||
</defs>
|
||||
{edges.map(([a, b], i) => {
|
||||
const p1 = getPort(a, 'out');
|
||||
const p2 = getPort(b, 'in');
|
||||
const dx = Math.max(40, (p2.x - p1.x) * 0.5);
|
||||
const d = `M ${p1.x} ${p1.y} C ${p1.x + dx} ${p1.y}, ${p2.x - dx} ${p2.y}, ${p2.x - 2} ${p2.y}`;
|
||||
const highlight = a === selectedId || b === selectedId;
|
||||
return (
|
||||
<path key={i} d={d}
|
||||
stroke={highlight ? '#6366F1' : '#3a3a3a'}
|
||||
strokeWidth={highlight ? 2 : 1.5}
|
||||
fill="none"
|
||||
markerEnd={`url(#${highlight ? 'arrow' : 'arrow-dim'})`}
|
||||
opacity={highlight ? 0.95 : 0.6} />
|
||||
);
|
||||
})}
|
||||
</svg>
|
||||
|
||||
<div className="wf-nodes">
|
||||
{nodes.map(n => (
|
||||
<div key={n.id}
|
||||
ref={el => (nodeRefs.current[n.id] = el)}
|
||||
className={`wf-node ${selectedId === n.id ? 'selected' : ''}`}
|
||||
style={{left: n.x, top: n.y}}
|
||||
onClick={() => setSelectedId(n.id)}>
|
||||
{n.inputs.length > 0 && <span className="port in" />}
|
||||
{n.outputs.length > 0 && <span className="port out" />}
|
||||
<div className="node-row-top">
|
||||
<span className="node-icon" style={{background: n.tone}}>
|
||||
<Icon name={n.icon} size={12} />
|
||||
</span>
|
||||
<span className="node-title">{n.title}</span>
|
||||
<span className="node-badge">{n.badge}</span>
|
||||
</div>
|
||||
<div className="node-sub">{n.type}</div>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
|
||||
{/* Detail panel */}
|
||||
{selected && (
|
||||
<div className="wf-detail">
|
||||
<div className="dt-head">
|
||||
<span className="dt-icon" style={{background: selected.tone}}>
|
||||
<Icon name={selected.icon} size={15} />
|
||||
</span>
|
||||
<div className="dt-meta">
|
||||
<h3>{selected.title}</h3>
|
||||
<div className="dt-type">{selected.type}</div>
|
||||
</div>
|
||||
<button className="close-btn" onClick={() => setSelectedId(null)}>
|
||||
<Icon name="close" size={14} />
|
||||
</button>
|
||||
</div>
|
||||
<div className="dt-body">
|
||||
<div className="dt-section">
|
||||
<h4>Input schema</h4>
|
||||
{selected.inputs.length === 0 ? (
|
||||
<div style={{fontSize: 12, color: 'var(--text-mute)', fontStyle: 'italic'}}>No inputs — this is a trigger.</div>
|
||||
) : selected.inputs.map(f => (
|
||||
<div key={f.k} className="schema-field">
|
||||
<span className="k">{f.k}</span>
|
||||
<span className="t">{f.t}</span>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
|
||||
<div className="dt-section">
|
||||
<h4>Output schema</h4>
|
||||
{selected.outputs.length === 0 ? (
|
||||
<div style={{fontSize: 12, color: 'var(--text-mute)', fontStyle: 'italic'}}>No outputs — terminal node.</div>
|
||||
) : selected.outputs.map(f => (
|
||||
<div key={f.k} className="schema-field">
|
||||
<span className="k">{f.k}</span>
|
||||
<span className="t">{f.t}</span>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
|
||||
{selected.id === 'summarize' && (
|
||||
<div className="dt-section">
|
||||
<h4>Configuration</h4>
|
||||
<div className="triplet">
|
||||
<div className="trow">
|
||||
<div className="tkey">model</div>
|
||||
<input className="tval" value={triplet.model} onChange={e => setTriplet({...triplet, model: e.target.value})} />
|
||||
</div>
|
||||
<div className="trow">
|
||||
<div className="tkey">temp</div>
|
||||
<input className="tval" value={triplet.temperature} onChange={e => setTriplet({...triplet, temperature: e.target.value})} />
|
||||
</div>
|
||||
<div className="trow">
|
||||
<div className="tkey">prompt</div>
|
||||
<input className="tval" value={triplet.prompt} onChange={e => setTriplet({...triplet, prompt: e.target.value})} />
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
|
||||
<div className="dt-section">
|
||||
<h4>Last run</h4>
|
||||
<div style={{display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 8, fontSize: 12}}>
|
||||
<div style={{background: 'rgba(255,255,255,0.02)', border: '1px solid var(--line)', borderRadius: 7, padding: '8px 10px'}}>
|
||||
<div style={{color: 'var(--text-mute)', fontSize: 10.5, textTransform: 'uppercase', letterSpacing: '0.06em'}}>Duration</div>
|
||||
<div style={{fontFamily: 'JetBrains Mono, monospace', marginTop: 3}}>2.4s</div>
|
||||
</div>
|
||||
<div style={{background: 'rgba(255,255,255,0.02)', border: '1px solid var(--line)', borderRadius: 7, padding: '8px 10px'}}>
|
||||
<div style={{color: 'var(--text-mute)', fontSize: 10.5, textTransform: 'uppercase', letterSpacing: '0.06em'}}>Status</div>
|
||||
<div style={{marginTop: 2}}><span className="pill active"><span className="pdot" />success</span></div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<button className="btn btn-primary" style={{width: '100%', marginTop: 4}}>
|
||||
<Icon name="spark" size={13} /> Edit this node in Claude
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
|
||||
{/* Minimap */}
|
||||
<div className="wf-minimap">
|
||||
<div className="mini-label">Overview</div>
|
||||
{nodes.map(n => {
|
||||
const sz = sizes[n.id] || {w: 180, h: 60};
|
||||
return (
|
||||
<div key={n.id} className="mini-box" style={{
|
||||
left: 8 + (n.x / 1400) * 164,
|
||||
top: 18 + (n.y / 500) * 80,
|
||||
width: Math.max(6, (sz.w / 1400) * 164),
|
||||
height: Math.max(4, (sz.h / 500) * 80),
|
||||
opacity: selectedId === n.id ? 1 : 0.5,
|
||||
background: selectedId === n.id ? 'var(--primary)' : 'var(--primary-soft)',
|
||||
}} />
|
||||
);
|
||||
})}
|
||||
</div>
|
||||
|
||||
{/* Zoom controls */}
|
||||
<div className="wf-controls">
|
||||
<button onClick={() => setZoom(Math.max(40, zoom - 10))}><Icon name="zoom_out" size={13} /></button>
|
||||
<div className="zoom-val">{zoom}%</div>
|
||||
<button onClick={() => setZoom(Math.min(200, zoom + 10))}><Icon name="zoom_in" size={13} /></button>
|
||||
<button><Icon name="maximize" size={13} /></button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
window.WorkflowViewer = WorkflowViewer;
|
||||
@@ -0,0 +1,300 @@
|
||||
# Frontend Redesign — Design
|
||||
|
||||
> 讀此檔前請先讀 `requirements.md` 和 `design-source/index.html`。
|
||||
> 視覺 spec 的 single source of truth 是 `design-source/`（Claude Design 匯出的 HTML/JSX prototype）。
|
||||
|
||||
---
|
||||
|
||||
## 1. 架構總覽
|
||||
|
||||
```
|
||||
landing/ (Next.js 15 App Router)
|
||||
├── app/
|
||||
│ ├── layout.tsx ← 全站 layout：next/font + design tokens + 全域 CSS 匯入
|
||||
│ ├── globals.css ← 匯入 design-tokens.css；Tailwind @import
|
||||
│ ├── design-tokens.css ← 新增：從 design-source 抽出的 CSS variables（:root {...}）
|
||||
│ ├── page.tsx ← Landing（RSC）
|
||||
│ ├── auth/
|
||||
│ │ └── page.tsx ← Auth（"use client"）
|
||||
│ ├── dashboard/
|
||||
│ │ └── page.tsx ← Dashboard（"use client"，仍靠 middleware 保護）
|
||||
│ ├── keys/
|
||||
│ │ └── page.tsx ← API Keys（"use client"）
|
||||
│ ├── workflows/
|
||||
│ │ ├── page.tsx ← Workflows 清單（redirect 到 dashboard 的 table，本身極簡）
|
||||
│ │ └── [name]/page.tsx ← Workflow Viewer（"use client"）
|
||||
│ ├── integrations/page.tsx ← 保留現有
|
||||
│ ├── api-docs/page.tsx ← 保留現有
|
||||
│ └── login/page.tsx ← 保留現有（redirect /auth 同義；見 §9 遷移策略）
|
||||
├── components/
|
||||
│ ├── shell/
|
||||
│ │ ├── Logo.tsx
|
||||
│ │ ├── Icon.tsx
|
||||
│ │ ├── TopNav.tsx
|
||||
│ │ ├── Footer.tsx
|
||||
│ │ └── Sidebar.tsx
|
||||
│ ├── primitives/
|
||||
│ │ ├── Button.tsx ← btn / btn-primary / btn-secondary / btn-ghost 對應 class
|
||||
│ │ ├── Pill.tsx
|
||||
│ │ ├── Toggle.tsx
|
||||
│ │ ├── Terminal.tsx ← landing hero 右卡用
|
||||
│ │ └── ChatPreview.tsx ← landing hero 右卡用
|
||||
│ └── workflow/
|
||||
│ ├── Canvas.tsx ← wf-viewer 本體（節點 + SVG edges）
|
||||
│ ├── NodeCard.tsx
|
||||
│ ├── DetailPanel.tsx
|
||||
│ ├── Minimap.tsx
|
||||
│ └── ZoomControls.tsx
|
||||
├── lib/
|
||||
│ ├── api.ts ← typed fetch wrapper（fetch ${API_BASE}${path}, credentials: 'include'）
|
||||
│ ├── workflows.ts ← listWorkflows / getWorkflow / getWorkflowYaml
|
||||
│ ├── apiKeys.ts ← listKeys / createKey / patchKey / deleteKey
|
||||
│ └── me.ts ← 已存在邏輯，集中到此
|
||||
├── middleware.ts ← 擴展 matcher（加 /keys, /workflows/*）
|
||||
└── ...（既有 package.json / wrangler.toml 不變）
|
||||
```
|
||||
|
||||
**路由對照設計稿的 5 screen**：
|
||||
|
||||
| Screen | Route |
|
||||
|---|---|
|
||||
| Landing | `/` |
|
||||
| Auth | `/auth`（新增；`/login` 保留並內部 `redirect('/auth')`） |
|
||||
| Dashboard | `/dashboard` |
|
||||
| API Keys | `/keys` |
|
||||
| Workflow Viewer | `/workflows/[name]` |
|
||||
|
||||
---
|
||||
|
||||
## 2. Design tokens 對應
|
||||
|
||||
設計稿所有 CSS 變數抄進 `app/design-tokens.css`，**不解析、不改名**：
|
||||
|
||||
```css
|
||||
:root {
|
||||
--bg: #0F0F0F;
|
||||
--bg-1: #141414;
|
||||
--card: #1A1A1A;
|
||||
--card-2: #222222;
|
||||
--line: #262626;
|
||||
--line-2: #303030;
|
||||
--text: #EDEDED;
|
||||
--text-dim: #A0A0A0;
|
||||
--text-mute: #6B6B6B;
|
||||
--primary: #6366F1;
|
||||
--primary-2: #8B5CF6;
|
||||
--primary-soft: rgba(99, 102, 241, 0.12);
|
||||
--primary-ring: rgba(99, 102, 241, 0.32);
|
||||
--success: #22C55E;
|
||||
--warn: #F59E0B;
|
||||
--danger: #EF4444;
|
||||
--gradient: linear-gradient(135deg, #6366F1 0%, #8B5CF6 100%);
|
||||
--gradient-soft: linear-gradient(135deg, rgba(99,102,241,0.16) 0%, rgba(139,92,246,0.16) 100%);
|
||||
}
|
||||
```
|
||||
|
||||
並在 Tailwind v4 的 `@theme inline` block 內對應出：
|
||||
|
||||
```css
|
||||
@theme inline {
|
||||
--color-bg: var(--bg);
|
||||
--color-card: var(--card);
|
||||
--color-card-2: var(--card-2);
|
||||
--color-line: var(--line);
|
||||
--color-line-2: var(--line-2);
|
||||
--color-text: var(--text);
|
||||
--color-text-dim: var(--text-dim);
|
||||
--color-text-mute: var(--text-mute);
|
||||
--color-primary: var(--primary);
|
||||
--color-primary-2: var(--primary-2);
|
||||
}
|
||||
```
|
||||
|
||||
這樣 JSX 裡可用 `bg-bg / text-text-dim / border-line`，又保留 CSS 變數語義。
|
||||
|
||||
**現有的 `--background: #0a0a0a` 要換成 `#0F0F0F`**（視覺 breaking change；受影響：所有沿用 `bg-[#0a0a0a]` 的 inline 值）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 字型
|
||||
|
||||
```tsx
|
||||
// app/layout.tsx
|
||||
import { Inter, JetBrains_Mono } from 'next/font/google';
|
||||
|
||||
const inter = Inter({
|
||||
subsets: ['latin'],
|
||||
variable: '--font-inter',
|
||||
weight: ['300', '400', '500', '600', '700', '800'],
|
||||
});
|
||||
const mono = JetBrains_Mono({
|
||||
subsets: ['latin'],
|
||||
variable: '--font-mono',
|
||||
weight: ['400', '500', '600'],
|
||||
});
|
||||
|
||||
// body class = `${inter.variable} ${mono.variable}`
|
||||
```
|
||||
|
||||
`globals.css` 中的 `body { font-family: var(--font-inter), -apple-system, sans-serif; }`，`.mono` class 用 `font-family: var(--font-mono)`。
|
||||
|
||||
**移除**：
|
||||
- `design-source/index.html` 第 7-9 行的 `<link rel="preconnect"> / <link href="fonts.googleapis.com">`（不寫入 production）。
|
||||
- React / Babel standalone script 標籤（prototype 專用，不進 production）。
|
||||
|
||||
---
|
||||
|
||||
## 4. 元件 porting 規則
|
||||
|
||||
Claude Design 用了 `window.Icon / window.Logo / window.AppIcon / window.TopNav ...` 的 globals 風格 — 那是 prototype 專用。Port 到 Next.js 時：
|
||||
|
||||
1. 每個元件拆單檔、具名 export。
|
||||
2. 用 Tailwind + `className` 模板字串；共用 variant（如 btn）用 `cva`-style helper 即可（自己寫 5 行的 `clsx`-alike 函式），**不引入 class-variance-authority / clsx 套件**（避免新依賴）。
|
||||
3. Icon 的 `paths` 直接搬，但每個 icon 拆成自己的 functional component 或集中在一個 `<Icon name="..." />`（沿用 design source 的 pattern）。
|
||||
4. SVG arc wordmark 的 logo 直接 port。
|
||||
|
||||
---
|
||||
|
||||
## 5. 各 screen 實作細節
|
||||
|
||||
### 5.1 Landing — `app/page.tsx`
|
||||
|
||||
- 結構：`<TopNav />` + `<Hero />` + `<Paths />` + `<Strip />` + `<Footer />`。
|
||||
- Hero：heading、eyebrow、CTA、radial grid bg（純 CSS）。
|
||||
- Paths 左卡（Developer）：install tabs (`npm` / `pip` / `bun`) + 兩個 terminal block；**code 範例用 dogfooding 範例**（`acr` CLI），不留 `Arcrun` SDK 假 API。
|
||||
- Paths 右卡（Everyone）：chat preview 結構保留；assistant 對話中的 tool call 用「arcrun · digest/weekly」不動。
|
||||
- Strip：4 cell。
|
||||
- `LandingClientTabs` 因為有 tabs state，需標 `"use client"`；外層保持 RSC。
|
||||
|
||||
### 5.2 Auth — `app/auth/page.tsx`
|
||||
|
||||
- `"use client"`。state：`mode: 'signin' | 'signup'`, `email`, `pw`, `remember`。
|
||||
- Submit：`fetch(${API_BASE}/auth/password-login, { method: 'POST', credentials: 'include' })`（**若 cypher-executor 尚未支援 password auth，先顯示「Password 登入尚未開放，請用 OAuth」警示，不偽造成功流程**）。
|
||||
- OAuth 按鈕：直接 `<a href={API_BASE}/auth/google/start?redirect=/dashboard>`，和現行 `/login` 同樣機制。
|
||||
- 下標提示「By signing up, you agree to our Terms ...」保留 static 字串。
|
||||
- 保留 `/login` 路由向後相容（RSC 裡 `redirect('/auth')`）。
|
||||
|
||||
### 5.3 Dashboard — `app/dashboard/page.tsx`
|
||||
|
||||
- `"use client"` 或 split（外層 RSC 抓 /me，內層 Client）。
|
||||
- 由 `<Sidebar current="dashboard" />` + main。
|
||||
- 主要區塊：
|
||||
- Main head：breadcrumb「{email 的 domain} › Dashboard」、heading「Welcome back, {display_name}」、subtitle 顯示 app/workflow 總數（從 `/apps` + `/workflows` 計算；若 endpoint 404 → 顯示 `—`）。
|
||||
- Apps Grid：`/apps` 的結果渲染；每列永遠有一個 `app-empty` 卡（新建 CTA）。
|
||||
- Workflows Table：`/workflows` 的結果渲染；空時改為全寬「No workflows yet. Run `acr push` to add one.」內嵌指令框。
|
||||
- 「Open app」「View」按鈕導向 `/workflows/[name]`。
|
||||
- 「Edit in Claude」按鈕本次不做動作，僅保 UI（disabled + tooltip「Coming soon」）。
|
||||
|
||||
### 5.4 API Keys — `app/keys/page.tsx`
|
||||
|
||||
- `"use client"`。
|
||||
- Fetch `/api-keys`：若回傳為空陣列但 `/me` 有 api_key，fallback 顯示 `/me.api_key` 為唯一一列（單 key 相容模式）。
|
||||
- 頂部 new-key-box：只在「剛剛建立新 key」的一次性狀態顯示（`useState` + `sessionStorage` flag，reload 後消失）。
|
||||
- 表格、toggle、trash：對應 PATCH / DELETE。
|
||||
- 「Create new key」按鈕：呼叫 `POST /api-keys`，拿到後打 highlight box。
|
||||
- Revoke 警告文字維持設計稿「within 60 seconds」。
|
||||
|
||||
### 5.5 Workflow Viewer — `app/workflows/[name]/page.tsx`
|
||||
|
||||
- `"use client"`，param `name` 來自動態路由。
|
||||
- Mount 後呼叫 `GET /workflows/:name`：後端回傳 `{ name, nodes: Node[], edges: Edge[], yaml, last_run: {...} }`（若 endpoint 未實作 → 顯示「Workflow viewer 尚未啟用」empty state，不用假資料）。
|
||||
- `<Canvas>` 內：
|
||||
- SVG 的 `<marker>`, `<path>` 定義抄設計稿。
|
||||
- Node 用絕對定位（x/y 直接用 API 資料；資料沒有 coord 時做自動 layout — 階段性做簡單 dagre-free 的「column by depth」排版，避免新依賴）。
|
||||
- 點選節點 → 右側 detail panel 顯示 input/output schema；若 type 含 `ai.*`，顯示 triplet 編輯器（model / temp / prompt）— 編輯本次 **read-only**（disabled input + 「Edit via acr CLI」提示）。
|
||||
- 「Export YAML」按 `GET /workflows/:name/yaml` → `download` blob。
|
||||
- 「Edit in Claude」：本次只開新 tab 到 `https://claude.ai/new?q=...`（文案「coming soon」按鈕），避免偽裝已整合。
|
||||
- Zoom controls、minimap：純 UI，`zoom` state 實際不套 transform（或簡單 `style={{ transform: scale(zoom/100) }}` 套在 `.wf-nodes` + svg）。
|
||||
|
||||
---
|
||||
|
||||
## 6. API wrapper（`lib/api.ts`）
|
||||
|
||||
```ts
|
||||
export const API_BASE = process.env.NEXT_PUBLIC_API_BASE ?? 'https://cypher.arcrun.dev';
|
||||
|
||||
export async function arcrunFetch<T>(path: string, init: RequestInit = {}): Promise<T> {
|
||||
const res = await fetch(`${API_BASE}${path}`, {
|
||||
credentials: 'include',
|
||||
headers: { 'Accept': 'application/json', ...(init.headers ?? {}) },
|
||||
...init,
|
||||
});
|
||||
if (res.status === 401 && typeof window !== 'undefined') {
|
||||
window.location.href = `/auth?redirect=${encodeURIComponent(location.pathname)}`;
|
||||
throw new Error('unauthenticated');
|
||||
}
|
||||
if (!res.ok) throw new Error(`arcrun ${path}: ${res.status}`);
|
||||
return res.json() as Promise<T>;
|
||||
}
|
||||
```
|
||||
|
||||
所有頁面透過這個 wrapper。**禁止在 page.tsx 裡 hard-code `fetch('https://...')`**（測試可以 grep）。
|
||||
|
||||
---
|
||||
|
||||
## 7. Middleware
|
||||
|
||||
```ts
|
||||
export const config = {
|
||||
matcher: ['/dashboard/:path*', '/keys/:path*', '/workflows/:path*'],
|
||||
};
|
||||
```
|
||||
|
||||
現有邏輯（讀 `arcrun_session` cookie，沒有就 redirect `/login?redirect=...`）保留，`/login` 改為內部 redirect `/auth`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 不做的設計稿功能
|
||||
|
||||
| 設計元素 | 取捨 |
|
||||
|---|---|
|
||||
| 底部的 `proto-switch`（5 個 screen 切換 pill） | **刪**。那是 prototype 用的 demo 切換器，不進 production。 |
|
||||
| Sidebar 的 `count` badge | 先保留；數字從 `/workflows` / `/apps` 的長度派生；無資料時藏起來。 |
|
||||
| Sidebar bottom 的 avatar + "Maya Rivera / maya@northwind.co" | 換成 `{display_name} / {email}`（真資料）。 |
|
||||
| Workflow Viewer 的 triplet 可編輯 | 本次 disabled，僅顯示。 |
|
||||
| 「Edit in Claude」整合 | 按鈕保留，點擊開新 tab 到 claude.ai，不串 MCP/API。 |
|
||||
| 多 workspace breadcrumb | 固定顯示用戶 email domain 或「Personal」。 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 既有頁面遷移
|
||||
|
||||
| 既有 | 處理 |
|
||||
|---|---|
|
||||
| `/page.tsx` | **rewrite**：沿用設計稿結構，code demo 字串改為 `acr` 實際指令（現有的 `auth.bind(...)` 寫法可保留在 Python tab） |
|
||||
| `/login` | 改為 `redirect('/auth')`（Next.js RSC redirect），保留舊連結相容 |
|
||||
| `/dashboard` | **rewrite**：舊 dashboard 變成 API Keys 獨立頁 + 新 Dashboard 總覽。原本 dashboard 裡的 Key 卡片搬到 `/keys`。 |
|
||||
| `/api-docs` | 不動 |
|
||||
| `/integrations` | 不動；在 Dashboard Apps Grid 旁提供 link |
|
||||
|
||||
---
|
||||
|
||||
## 10. 開發順序（高度相依）
|
||||
|
||||
見 `tasks.md`。總則：
|
||||
|
||||
1. 先做 design tokens + shell（Logo / Icon / Button / Sidebar / TopNav / Footer） — 其他頁面都吃這些。
|
||||
2. 然後 Landing（可直接驗證視覺基準）。
|
||||
3. 然後 Auth（獨立）。
|
||||
4. 然後 API Keys（後端依賴少）。
|
||||
5. 然後 Dashboard（依賴 `/workflows` + `/apps`，若未實作先 empty state）。
|
||||
6. 最後 Workflow Viewer（依賴最重，多 endpoint）。
|
||||
|
||||
---
|
||||
|
||||
## 11. 風險與未解
|
||||
|
||||
| 風險 | 緩解 |
|
||||
|---|---|
|
||||
| cypher-executor 尚未有 `/workflows`, `/apps`, `/api-keys` CRUD | 前端先做，統一走 404 → empty state；另開 task 去 cypher-executor SDD 增補。本次 SDD 不負責後端實作。 |
|
||||
| Password auth 沒實作 | Auth 頁 email/password form 在 submit 時顯示「OAuth only」提示 |
|
||||
| `acr push` 未記錄 node 座標 | Canvas 自動排版（by topological depth），不強制 YAML 載入 layout |
|
||||
| `next-on-pages` 對 `"use client"` 大量頁面的 edge runtime 支援 | 本來就用 `next-on-pages`，問題不大；必要時 per-page `export const runtime = 'edge'` |
|
||||
| 舊 `/dashboard` 的 bookmark 使用者 | 現行 `/dashboard` 的 Key 管理被搬走；保留 Key 區塊 + 顯示提示「New page: /keys」引導 |
|
||||
|
||||
---
|
||||
|
||||
## 12. 與封測的關係
|
||||
|
||||
此 SDD 的實作**不解除封測阻擋**（封測阻擋在 Credential Primitives WASM）。此重設計與 Phase 0.6 / 0.7 / 1-3 是並行軌道。richblack 可決定先後順序，但本 SDD 獨立可 ship。
|
||||
|
||||
@@ -0,0 +1,159 @@
|
||||
# Frontend Redesign — Requirements
|
||||
|
||||
> 來源：Claude Design bundle `JAdpACs3cSyw_vN6Ketj1Q`（已歸檔於 `design-source/`）。
|
||||
> 此 SDD 擴展 `../landing-page.md` 的範圍：landing 從「單頁 + OAuth + Dashboard」升級為「5 screen app shell」。
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景
|
||||
|
||||
`arcrun/landing/` 目前只提供：
|
||||
|
||||
- `/` — Landing hero + code demo
|
||||
- `/login` — Google / GitHub OAuth
|
||||
- `/dashboard` — API Key 管理
|
||||
- `/api-docs` — Swagger UI（外部）
|
||||
- `/integrations` — 20 個 recipe 靜態清單
|
||||
|
||||
Claude Design 交付一套完整 5 screen 設計（Landing / Auth / API Keys / Dashboard / Workflow Viewer），與現有前端相比多了：
|
||||
|
||||
- **Dashboard 的 Apps Grid 與 Workflows Table**（現在沒有應用/workflow 清單 UI）
|
||||
- **API Keys 獨立頁**（現在和 dashboard 混在一起）
|
||||
- **Workflow Viewer**：node-based canvas，對應 YAML workflow 的視覺化（目前 acr push YAML 後只有 CLI 輸出）
|
||||
|
||||
---
|
||||
|
||||
## 2. User Stories
|
||||
|
||||
### US-1：新訪客認識 arcrun
|
||||
- 作為沒用過 arcrun 的工程師，我要在 landing 看到兩條路（For Developers / For Everyone），5 秒內判斷這是否符合我要的用法。
|
||||
- 驗收：hero + 雙 path card + feature strip 在首屏呈現；CTA「Start free」可點擊到 `/auth`。
|
||||
|
||||
### US-2：取得 / 登入會員
|
||||
- 作為訪客，我要用 GitHub / Google / Email 登入建立帳號。
|
||||
- 驗收：`/auth` 支援 Sign in / Sign up tabs、GitHub + Google OAuth、Email + Password 表單。OAuth 成功後導向 `/dashboard`。
|
||||
|
||||
### US-3：看見應用全貌
|
||||
- 作為已登入用戶，我要在 Dashboard 看到我已部署的 App（packaged workflow）和 Workflow 清單。
|
||||
- 驗收：
|
||||
- Apps Grid：每個 app 卡片顯示名稱、描述、「Open app」「Edit in Claude」。
|
||||
- Workflows Table：顯示 workflow 名稱、節點數、最後修改、執行次數、狀態。
|
||||
- 若 app / workflow 為空，顯示新建 CTA（非硬編 mock）。
|
||||
|
||||
### US-4：管理 API Keys
|
||||
- 作為已登入用戶，我要建立、檢視、停用、刪除 API Key。
|
||||
- 驗收：
|
||||
- 剛產生的 Key 顯示在頂部高亮卡片（含警示文字「不會再顯示」）。
|
||||
- 全部 Keys 在下方表格顯示（名稱、遮蔽後 key、建立時間、最後使用、狀態、toggle、trash）。
|
||||
- Rotate / Revoke 立即生效（呼叫 cypher-executor）。
|
||||
|
||||
### US-5：檢視 Workflow graph
|
||||
- 作為已登入用戶，我要點 workflow 進到 viewer，看到節點 DAG 與每個節點的 I/O schema 與參數。
|
||||
- 驗收：
|
||||
- Canvas 顯示節點（含 icon / type badge），節點以 bezier 曲線相連。
|
||||
- 選中節點後右側面板顯示 input / output schema、configuration（針對 ai.completion 等節點顯示 triplet 編輯器）。
|
||||
- 工具列含 Share / Export YAML / Edit in Claude。
|
||||
- Minimap + zoom 控制顯示可用。
|
||||
- 「Export YAML」呼叫 cypher-executor 取得該 workflow 的原始 YAML。
|
||||
|
||||
### US-6：Dogfooding
|
||||
- 作為 arcrun 核心維護者，我要前端所有與服務打交道的動作都透過 arcrun 自家 API（cypher-executor）完成，不依賴第三方 OAuth / workflow / backend 服務。
|
||||
- 驗收（見 §6）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 非功能需求
|
||||
|
||||
| 項目 | 規範 |
|
||||
|---|---|
|
||||
| 技術棧 | Next.js 15 App Router、React 19、Tailwind v4、TypeScript（沿用 `landing/` 現有堆疊） |
|
||||
| 部署 | Cloudflare Pages（`@cloudflare/next-on-pages`），沿用 `landing/wrangler.toml` |
|
||||
| 字型 | Inter、JetBrains Mono — 用 `next/font/google`，不拉 unpkg / fonts.googleapis.com `<link>` |
|
||||
| 依賴 | 僅 Next / React / Tailwind；禁止 tRPC、React Query、SWR、Auth.js/Clerk、ReactFlow/XYFlow、Radix、shadcn CLI install、animation library（framer-motion）等第三方 |
|
||||
| 狀態管理 | React 內建（useState / useReducer / Context）；持久化用 `localStorage` 或 server session cookie |
|
||||
| 國際化 | 延後；本次一律英文（與設計稿一致）。現有 `?lang=zh` 不擴展 |
|
||||
| 無障礙 | 按鈕 `aria-label`、Form 控件有 `<label>`；鍵盤可完成登入 / 複製 key 流程 |
|
||||
| 效能 | Landing 首屏無阻塞 JS（RSC）；Dashboard / Workflow Viewer 可為 Client Component |
|
||||
|
||||
---
|
||||
|
||||
## 4. 視覺基準
|
||||
|
||||
| 項目 | 值（source of truth：`design-source/index.html` 的 CSS 變數） |
|
||||
|---|---|
|
||||
| 主背景 | `#0F0F0F`（現有是 `#0a0a0a` — 本次改為 `#0F0F0F`） |
|
||||
| Card | `#1A1A1A` |
|
||||
| Line | `#262626` / `#303030` |
|
||||
| Primary | `#6366F1`（indigo） → `#8B5CF6`（violet）漸層 |
|
||||
| Text | `#EDEDED` / dim `#A0A0A0` / mute `#6B6B6B` |
|
||||
| 字型 | Inter 300/400/500/600/700/800；Mono 400/500/600 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 範圍界線
|
||||
|
||||
### 納入
|
||||
- 5 screen（Landing、Auth、Dashboard、API Keys、Workflow Viewer）
|
||||
- Logo（SVG arc wordmark）、Icon set（inline SVG，從 primitives.jsx port）
|
||||
- TopNav / Footer / Sidebar 三個 shell 元件
|
||||
|
||||
### 不納入（本次 SDD）
|
||||
- **Multi-tenant workspace 切換**（設計稿有 "Northwind" breadcrumb，本次純顯示用戶 email）
|
||||
- **Multi-API-key CRUD 後端**（cypher-executor 現只支援每帳號一把 key，多 key table 先以「目前只支援一把」狀態呈現 — 見 §6.2）
|
||||
- **Workflow 編輯**（只做 read-only viewer；編輯仍走 acr CLI / YAML）
|
||||
- **即時執行狀態 stream**（minimap / zoom 僅 UI，不做真實 pan-zoom transform）
|
||||
- **i18n 中英切換**、**Hall of Fame**、**Donate**
|
||||
- **Swagger UI 頁（/api-docs）** — 保留現狀
|
||||
|
||||
---
|
||||
|
||||
## 6. API 依賴（全部打 `cypher.arcrun.dev`）
|
||||
|
||||
### 6.1 既有（已實作於 cypher-executor）
|
||||
- `GET /me` — 取得登入用戶 + api_key（driver：dashboard 側欄 avatar / API Keys 頁的單把 key）
|
||||
- `PUT /me/api-key/rotate`、`DELETE /me/api-key` — Rotate / Revoke
|
||||
- `GET /auth/google/start`、`GET /auth/github/start` — OAuth 起點
|
||||
- `POST /auth/logout`
|
||||
- `POST /webhooks/named/{name}/trigger` — 觸發（給 Landing 文案展示）
|
||||
|
||||
### 6.2 需新增的 endpoint（阻擋項；**本 SDD 只定義契約，cypher-executor 實作歸屬於另一個 task**）
|
||||
|
||||
| Method | Path | 說明 | 用途 |
|
||||
|---|---|---|---|
|
||||
| GET | `/workflows` | 列出當前 api_key 名下的 workflow（名稱、nodes、modified、run_count、status） | Dashboard / Workflows Table |
|
||||
| GET | `/workflows/:name` | 取得 workflow 詳細（含 graph 節點 + edges + YAML） | Workflow Viewer |
|
||||
| GET | `/workflows/:name/yaml` | 下載 raw YAML | Workflow Viewer Export |
|
||||
| GET | `/apps` | 列出 app（= workflow 標上 icon/tone/description metadata） | Dashboard / Apps Grid |
|
||||
| GET | `/api-keys` | 列出多把 key（若後端仍是單把，回傳單元素 array） | API Keys 頁 |
|
||||
| POST | `/api-keys` | 建立新 key | API Keys 頁「Create new key」 |
|
||||
| PATCH | `/api-keys/:id` | `{ active: boolean }` 切換 | API Keys 頁 toggle |
|
||||
| DELETE | `/api-keys/:id` | 刪除 | API Keys 頁 trash |
|
||||
|
||||
**在後端尚未實作前**：前端用型別化 fetch wrapper 封裝呼叫；遇到 404 顯示 empty state（而非假資料）。本 SDD 明確禁止 hard-code mock fixture。
|
||||
|
||||
### 6.3 登入前後可用的公開資訊
|
||||
- Integrations 清單（20 個 recipe）：現有 `/integrations` 頁已有靜態清單，繼續複用。
|
||||
|
||||
---
|
||||
|
||||
## 7. Dogfooding 紅線
|
||||
|
||||
| 禁止 | 用哪個 arcrun 內部替代 |
|
||||
|---|---|
|
||||
| Auth0 / Clerk / Supabase Auth | cypher-executor `/auth/*` + session cookie（現行 `arcrun_session`） |
|
||||
| Segment / PostHog | 不加，或用後續 arcrun `analytics` 零件 |
|
||||
| Vercel KV / Upstash | Cloudflare KV（經 cypher-executor） |
|
||||
| 直接寫第三方 API（Slack / Notion 等）作 dashboard demo | 透過 arcrun workflow + trigger 模擬 |
|
||||
| ReactFlow / XYFlow | 純 SVG 手刻（設計稿本來就是手刻） |
|
||||
|
||||
---
|
||||
|
||||
## 8. 驗收總清單
|
||||
|
||||
- [ ] 5 個 screen 全部在 `/`, `/auth`, `/dashboard`, `/keys`, `/workflows/[id]` 可達。
|
||||
- [ ] 設計稿的 spacing / color / border-radius 100% 對得上（以 `design-source/index.html` CSS 變數為準）。
|
||||
- [ ] middleware 保護 `/dashboard`, `/keys`, `/workflows/*`（未登入 → `/auth?redirect=...`）。
|
||||
- [ ] 只打 `cypher.arcrun.dev`（可透過 `NEXT_PUBLIC_API_BASE` override），grep 結果不含其他外部 API host。
|
||||
- [ ] `package.json` 新增依賴 = 0（本次不引入新 npm 套件）。
|
||||
- [ ] 無 mock 資料：若後端未實作，顯示 loading 或 empty state，不編假陣列給 UI。
|
||||
- [ ] `pnpm build` 通過，`next-on-pages` 輸出無 edge-runtime 錯誤。
|
||||
@@ -0,0 +1,140 @@
|
||||
# Frontend Redesign — Tasks
|
||||
|
||||
> 進度來源：本檔。完成一項立刻 `[x]`，不批次。
|
||||
> 本 SDD 建立於 2026-04-23；richblack 尚未下令動工，**所有 task 預設 `[ ]`**。
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — SDD 建立（本次）
|
||||
|
||||
- [x] 取得 Claude Design bundle，歸檔至 `design-source/`
|
||||
- [x] 撰寫 `requirements.md`
|
||||
- [x] 撰寫 `design.md`
|
||||
- [x] 撰寫 `tasks.md`（本檔）
|
||||
- [ ] richblack review + 認可 → 開 Phase 1
|
||||
|
||||
**等 richblack 明確說「開始動工」之前，不觸 `landing/` 任何檔案。**
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Tokens + Shell（無外部 API 依賴）
|
||||
|
||||
- [ ] 1.1 建 `landing/app/design-tokens.css`，抄 design-source CSS :root 變數
|
||||
- [ ] 1.2 更新 `landing/app/globals.css`：`@import './design-tokens.css'`，`@theme inline` 對應 token → Tailwind color
|
||||
- [ ] 1.3 `layout.tsx` 引入 `next/font/google` 的 Inter + JetBrains Mono；body bg 改 `var(--bg)`
|
||||
- [ ] 1.4 建 `landing/components/shell/Icon.tsx`（港設計稿 primitives.jsx 的所有 icon）
|
||||
- [ ] 1.5 建 `landing/components/shell/Logo.tsx`（SVG arc wordmark）
|
||||
- [ ] 1.6 建 `landing/components/shell/TopNav.tsx`
|
||||
- [ ] 1.7 建 `landing/components/shell/Footer.tsx`
|
||||
- [ ] 1.8 建 `landing/components/shell/Sidebar.tsx`（含頭像、項目清單、登出按鈕）
|
||||
- [ ] 1.9 建 `landing/components/primitives/Button.tsx`（variants: primary / secondary / ghost / danger-ghost / sm / lg）
|
||||
- [ ] 1.10 建 `landing/components/primitives/Pill.tsx`、`Toggle.tsx`
|
||||
- [ ] 1.11 Lint + build pass
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Landing（`/`）
|
||||
|
||||
- [ ] 2.1 Rewrite `app/page.tsx`，結構照 design-source/screens/Landing.jsx
|
||||
- [ ] 2.2 Hero：heading / eyebrow / CTA / radial-grid bg（CSS only）
|
||||
- [ ] 2.3 Paths 左卡：install tabs 元件（Client Component）+ terminal code blocks（字串改 `acr` 實際指令）
|
||||
- [ ] 2.4 Paths 右卡：chat preview（靜態）
|
||||
- [ ] 2.5 Feature strip（4 cell）
|
||||
- [ ] 2.6 TopNav / Footer 接上
|
||||
- [ ] 2.7 Responsive（≤ 768px: paths 單欄、hero h1 縮 1 級）
|
||||
- [ ] 2.8 視覺比對 design-source/index.html（截圖對比 / DOM spec 檢查）
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Auth（`/auth`，`/login` redirect）
|
||||
|
||||
- [ ] 3.1 建 `app/auth/page.tsx`（Client）
|
||||
- [ ] 3.2 Sign in / Sign up tabs + OAuth buttons（Google / GitHub）接既有 `/auth/google/start` / `/auth/github/start`
|
||||
- [ ] 3.3 Email / Password form — submit 顯示「OAuth only」提示（待後端支援）
|
||||
- [ ] 3.4 `/login` 頁改為 `redirect('/auth')`
|
||||
- [ ] 3.5 視覺比對 design-source/screens/Auth.jsx
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — API Keys（`/keys`）
|
||||
|
||||
- [ ] 4.1 建 `lib/api.ts` fetch wrapper
|
||||
- [ ] 4.2 建 `lib/apiKeys.ts`（listKeys / createKey / patchKey / deleteKey）— 後端未實作時回 `[{ ...from /me }]` 的 fallback
|
||||
- [ ] 4.3 建 `app/keys/page.tsx`：頂部 new-key-box（sessionStorage flag）、全表格
|
||||
- [ ] 4.4 「Create new key」呼叫 `POST /api-keys`（後端未實作 → 顯示「coming soon」toast）
|
||||
- [ ] 4.5 Toggle active / trash 接 PATCH / DELETE
|
||||
- [ ] 4.6 middleware.ts matcher 加 `/keys/:path*`
|
||||
- [ ] 4.7 原 `/dashboard` 頁的 Key 卡區塊移除，放提示「API Keys 已搬到 /keys」
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Dashboard（`/dashboard`）
|
||||
|
||||
- [ ] 5.1 建 `lib/workflows.ts`、`lib/apps.ts`
|
||||
- [ ] 5.2 Rewrite `app/dashboard/page.tsx`（保留 /me session 檢查）
|
||||
- [ ] 5.3 Main head：breadcrumb / greeting / summary counters
|
||||
- [ ] 5.4 Apps Grid + empty-state 卡（`/apps` 404 → 只顯示 empty-state）
|
||||
- [ ] 5.5 Workflows Table（`/workflows` 404 → 顯示「no workflows — acr push」CTA）
|
||||
- [ ] 5.6 Sidebar 接真實 user（email / display_name）、登出按鈕接 `/auth/logout`
|
||||
- [ ] 5.7 視覺比對 design-source/screens/Dashboard.jsx
|
||||
|
||||
---
|
||||
|
||||
## Phase 6 — Workflow Viewer（`/workflows/[name]`）
|
||||
|
||||
- [ ] 6.1 建 `app/workflows/[name]/page.tsx`（Client）
|
||||
- [ ] 6.2 Topbar：back / logo / breadcrumb / title / saved indicator / share / export / edit-in-claude
|
||||
- [ ] 6.3 `<Canvas>`：SVG defs + 節點定位 + bezier edges；資料從 `GET /workflows/:name`
|
||||
- [ ] 6.4 Auto-layout：topological depth → columns，同 depth 平均分配 y
|
||||
- [ ] 6.5 NodeCard 點擊 → DetailPanel
|
||||
- [ ] 6.6 DetailPanel：input / output schema、triplet（disabled）、last run stats（可選）
|
||||
- [ ] 6.7 Export YAML：`GET /workflows/:name/yaml` → blob download
|
||||
- [ ] 6.8 Minimap（純顯示）、ZoomControls（簡單 scale）
|
||||
- [ ] 6.9 middleware.ts matcher 加 `/workflows/:path*`
|
||||
|
||||
---
|
||||
|
||||
## Phase 7 — 清理 + 收尾
|
||||
|
||||
- [ ] 7.1 刪除舊 `/dashboard` 不再用的 code（rotate/revoke 若全搬到 /keys）
|
||||
- [ ] 7.2 Grep 檢查：除 `cypher.arcrun.dev` 外無任何第三方 API host
|
||||
- [ ] 7.3 Grep 檢查：無 `mock` / `fixture` / 硬編的假資料陣列（`app-empty` 的字串常數除外）
|
||||
- [ ] 7.4 Grep 檢查：無新增 npm 依賴（`git diff landing/package.json` 應只改版本，不加條目）
|
||||
- [ ] 7.5 `pnpm build` 通過；`next-on-pages` 通過
|
||||
- [ ] 7.6 local `pnpm dev` 手工巡覽 5 screen，每個截圖比對 design-source
|
||||
- [ ] 7.7 更新 `.agents/specs/arcrun/arcrun.md`，加一段「CLI 1.2.0 搭配新 landing」之類的進度註記
|
||||
- [ ] 7.8 richblack 認可 → 合併 / deploy
|
||||
|
||||
---
|
||||
|
||||
## 需要 cypher-executor 搭配的 endpoint（不屬於本 SDD）
|
||||
|
||||
若 richblack 決定新 endpoint 要和前端同 PR 做：
|
||||
|
||||
- [ ] 後端：`GET /workflows`
|
||||
- [ ] 後端：`GET /workflows/:name` + `/yaml`
|
||||
- [ ] 後端：`GET /apps`
|
||||
- [ ] 後端：`GET /api-keys`、`POST /api-keys`、`PATCH /api-keys/:id`、`DELETE /api-keys/:id`
|
||||
|
||||
否則：以 empty state 呈現，封測也能運作。
|
||||
|
||||
---
|
||||
|
||||
## KBDB 整合（配合 matrix/kbdb/.agents/specs/arcrun-key-auth/）
|
||||
|
||||
Arcrun 用戶的 `ak_xxx` Key 同時可用於 KBDB（捆綁服務，自動開通）。
|
||||
cypher-executor 需在以下時機呼叫 KBDB：
|
||||
|
||||
- [ ] 後端：OAuth callback 成功 → `POST /partners`（建立 KBDB partner 記錄）
|
||||
- [ ] 後端：`PUT /me/api-key/rotate` → 舊 partner revoke + 建新 partner 記錄
|
||||
- [ ] 後端：`DELETE /me/api-key` → KBDB partner revoke
|
||||
|
||||
詳細設計見 `matrix/kbdb/.agents/specs/arcrun-key-auth/design.md`。
|
||||
|
||||
---
|
||||
|
||||
## 目前狀態
|
||||
|
||||
- **進度**：Phase 0 已完成（4/5；最後一項等 richblack 認可）。
|
||||
- **阻擋**：richblack 認可 + 「開始動工」指令。
|
||||
- **未啟動**：Phase 1-7 全部 `[ ]`。
|
||||
@@ -0,0 +1,325 @@
|
||||
# arcrun.dev Landing Page — SDD
|
||||
|
||||
> **目標**：給工程師一個門面，可以取得 API Key、管理 Key、探索 API（Swagger），同時藉此獲得會員 Email。
|
||||
> **原則**：先快速可用，不追求功能完整。榮譽牆、Python Lib 是後期。
|
||||
|
||||
---
|
||||
|
||||
## 0. 範圍（這份 SDD 涵蓋）
|
||||
|
||||
| 功能 | 說明 |
|
||||
|---|---|
|
||||
| 首頁 Hero | 說明 arcrun 是什麼，CTA 取得 API Key |
|
||||
| OAuth 登入 | Google / GitHub（用自己的 auth recipe — dogfooding） |
|
||||
| API Key 管理 | 查看、Rotate、Revoke |
|
||||
| Swagger UI | 嵌入 `/api`，讓工程師直接試打 |
|
||||
| 榮譽牆 `/integrations` | 靜態骨架，先列 20 個 recipe，無動態數字 |
|
||||
| 中英切換 | `?lang=zh` |
|
||||
|
||||
**不在本次範圍**：Python lib、Donate 整合、Social Proof 即時數字、貢獻者排行。
|
||||
|
||||
---
|
||||
|
||||
## 1. 技術選型
|
||||
|
||||
### 1.1 框架：Next.js（App Router）
|
||||
|
||||
**選 Next.js 而非 Astro 的原因**：
|
||||
- `finally-click` 已有完整 Next.js + OAuth 回調實作，可直接複用模式
|
||||
- API Key 管理頁有登入態保護需求，Next.js 的 middleware 最直接
|
||||
- Cloudflare Pages 支援 Next.js（`@cloudflare/next-on-pages`）
|
||||
- Astro 在動態路由保護上摩擦較多
|
||||
|
||||
### 1.2 部署：Cloudflare Pages
|
||||
|
||||
```
|
||||
arcrun.dev → Cloudflare Pages（Next.js）
|
||||
API calls → cypher.arcrun.dev（現有 Worker）
|
||||
```
|
||||
|
||||
### 1.3 儲存：現有 cypher-executor CREDENTIALS_KV + 新增 USERS_KV
|
||||
|
||||
現有 cypher-executor Worker 已有：
|
||||
- `CREDENTIALS_KV`：`{api_key}:cred:{name}` 存 tenant credentials
|
||||
- `RECIPES`：auth recipes
|
||||
|
||||
新增需求：
|
||||
- **USERS_KV**：存 user 帳號，key = `user:{provider}:{provider_user_id}`
|
||||
- value: `{ email, display_name, api_key, created_at, provider }`
|
||||
- **SESSIONS_KV**：存 login session，key = `sess:{session_id}`
|
||||
- value: `{ api_key, email, expires_at }`
|
||||
- TTL = 7 天
|
||||
|
||||
兩個 KV 都加到 cypher-executor `wrangler.toml`。
|
||||
|
||||
### 1.4 OAuth — Dogfooding 自己的 Auth Recipe
|
||||
|
||||
登入用 arcrun 自己的 auth recipe：
|
||||
- 不是用 arcrun auth recipe 的 `http_request` runner 去打第三方
|
||||
- 而是 **直接複用 recipe YAML 裡定義的 OAuth App 設定（client_id/secret）**
|
||||
- Worker 端實作 standard OAuth2 authorization_code flow
|
||||
|
||||
**支援提供商（MVP）**：
|
||||
- Google（google_drive recipe 的 OAuth App，或另建 arcrun-login Google App）
|
||||
- GitHub（github recipe 的 OAuth App）
|
||||
|
||||
登入 OAuth App 與 auth recipe 的 OAuth App **可以是同一個**（只要 scopes 包含 `openid profile email`），但更乾淨的做法是登入用獨立的 Google/GitHub App（只要 email scope），auth recipe 用的是資源存取 App。
|
||||
|
||||
**決策：登入用獨立 OAuth App**
|
||||
- `GOOGLE_CLIENT_ID`、`GOOGLE_CLIENT_SECRET` — 只申請 `openid profile email`
|
||||
- `GITHUB_CLIENT_ID`、`GITHUB_CLIENT_SECRET` — 只申請 `read:user` + `user:email`
|
||||
- 以 Worker Secret 方式存入 cypher-executor
|
||||
|
||||
---
|
||||
|
||||
## 2. 頁面結構
|
||||
|
||||
```
|
||||
arcrun.dev/
|
||||
├── / 首頁（Hero + Code snippet + CTA）
|
||||
├── /login 登入頁（Google / GitHub 按鈕）
|
||||
├── /auth/callback OAuth callback（Pages Function）
|
||||
├── /dashboard API Key 管理（需登入）
|
||||
├── /api Swagger UI（嵌入 swagger.json）
|
||||
└── /integrations 服務目錄（靜態，20 個 recipe）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 登入 / OAuth 流程
|
||||
|
||||
### 3.1 流程圖
|
||||
|
||||
```
|
||||
用戶點「Google 登入」
|
||||
→ GET /auth/google/start（Worker 端）
|
||||
→ redirect 到 Google OAuth（state = random, 存 SESSIONS_KV sess:state:{state} = {provider, redirect_back}）
|
||||
→ 用戶同意
|
||||
→ GET /auth/callback?code=...&state=...（Worker 端）
|
||||
→ 驗 state
|
||||
→ 用 code 換 access_token（POST google token endpoint）
|
||||
→ 用 token 取 userinfo（GET google userinfo）
|
||||
→ upsert USERS_KV user:{provider}:{provider_id} = {email, display_name, api_key, ...}
|
||||
→ 若新用戶：呼叫現有 /register?email=... 取得 arcrun API Key
|
||||
→ 建立 session：SESSIONS_KV sess:{session_id} = {api_key, email, ...}，TTL=7d
|
||||
→ Set-Cookie: arcrun_session={session_id}; HttpOnly; Secure; SameSite=Lax
|
||||
→ redirect 到 /dashboard
|
||||
```
|
||||
|
||||
### 3.2 「若新用戶取得 API Key」的邏輯
|
||||
|
||||
現有 `/register` endpoint 接受 `email` 回傳 `api_key`（HMAC 確定性）。
|
||||
但 landing page 需要的是**真正綁定到用戶帳號的 key**，且用戶可以 rotate/revoke。
|
||||
|
||||
**方案：延伸現有 register endpoint**
|
||||
|
||||
`/register` 目前：`HMAC(secret, email)` → 確定性 api_key，存 CREDENTIALS_KV
|
||||
|
||||
新增邏輯：
|
||||
1. 若 USERS_KV 已有此 user → 直接用記錄裡的 api_key
|
||||
2. 若新 user → 呼叫現有 `/register`（保持 HMAC 確定性邏輯）→ 拿到 api_key → 存入 USERS_KV
|
||||
|
||||
**好處**：不破壞現有 register 邏輯；登入後的 dashboard 顯示的 key = 現有 key = 封測用的 key。
|
||||
|
||||
### 3.3 Rotate / Revoke
|
||||
|
||||
- **Rotate**：產生新 UUID v4 key → 更新 USERS_KV 記錄 → 舊 key 失效（透過把新 key 加到 CREDENTIALS_KV，舊 key 的資料都跟著 API Key 命名空間走，所以 credentials 會留在舊 namespace）
|
||||
- 簡化版：Rotate 後顯示提示「您的 workflow credentials 已和舊 Key 分離，請重新設定」
|
||||
- **Revoke**：USERS_KV 記錄 `revoked: true` → Worker middleware 拒絕此 key
|
||||
|
||||
---
|
||||
|
||||
## 4. API 端點（新增到 cypher-executor）
|
||||
|
||||
```
|
||||
GET /auth/google/start → redirect 到 Google OAuth
|
||||
GET /auth/github/start → redirect 到 GitHub OAuth
|
||||
GET /auth/callback?code=&state= → 換 token、建立 session
|
||||
POST /auth/logout → 清 session cookie
|
||||
GET /me → 回傳當前登入用戶資訊（需 session cookie 或 API Key）
|
||||
PUT /me/api-key/rotate → 產生新 key
|
||||
DELETE /me/api-key → Revoke（標記撤銷）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 前端頁面設計
|
||||
|
||||
### 5.1 首頁（/）
|
||||
|
||||
```
|
||||
Hero:
|
||||
Stop fighting OAuth.
|
||||
One API key. Every service. Works anywhere.
|
||||
|
||||
[Get API Key — Free] [View on GitHub]
|
||||
|
||||
Before/After:
|
||||
40 行 OAuth 程式碼 → auth.bind("google_drive")
|
||||
|
||||
Code Demo（三個 tab）：
|
||||
Python / JavaScript / HTTP（n8n 用戶）
|
||||
|
||||
[Get Free API Key] 按鈕
|
||||
```
|
||||
|
||||
### 5.2 登入頁（/login）
|
||||
|
||||
```
|
||||
arcrun
|
||||
|
||||
登入或建立帳號
|
||||
|
||||
[Continue with Google]
|
||||
[Continue with GitHub]
|
||||
|
||||
不需要信用卡。API Key 立即可用。
|
||||
```
|
||||
|
||||
### 5.3 Dashboard（/dashboard）
|
||||
|
||||
```
|
||||
歡迎，{display_name}
|
||||
|
||||
您的 API Key
|
||||
┌────────────────────────────────┐
|
||||
│ ak_xxxxxxxxxxxxxxxxxxxx [複製] │
|
||||
└────────────────────────────────┘
|
||||
|
||||
[Rotate Key] [Revoke Key]
|
||||
|
||||
使用說明：
|
||||
Authorization: Bearer {key}
|
||||
或 X-Arcrun-API-Key: {key}
|
||||
|
||||
[登出]
|
||||
```
|
||||
|
||||
### 5.4 Swagger UI（/api）
|
||||
|
||||
- 嵌入 `<SwaggerUIBundle>` JS（CDN）
|
||||
- `url: 'https://cypher.arcrun.dev/swagger.json'`（現有 Worker 已有 `/docs` openapi endpoint）
|
||||
- 頂部說明：「這是 arcrun 的原始 API。Python / JS lib 是它的包裝，任何能發 HTTP request 的工具都能直接用。」
|
||||
|
||||
### 5.5 服務目錄（/integrations）
|
||||
|
||||
- 靜態列出 20 個 auth recipe（從 seed data 產生）
|
||||
- 每個 recipe：名稱、認證方式（static_key / service_account）、所需 credentials
|
||||
- 「找不到你要的服務？開 PR 貢獻 Recipe」CTA
|
||||
|
||||
---
|
||||
|
||||
## 6. 檔案結構
|
||||
|
||||
```
|
||||
arcrun/landing/ ← 新 Next.js 專案
|
||||
├── app/
|
||||
│ ├── layout.tsx
|
||||
│ ├── page.tsx 首頁
|
||||
│ ├── login/
|
||||
│ │ └── page.tsx
|
||||
│ ├── dashboard/
|
||||
│ │ ├── page.tsx
|
||||
│ │ └── middleware.ts （或 root middleware）
|
||||
│ ├── api-docs/
|
||||
│ │ └── page.tsx Swagger UI
|
||||
│ └── integrations/
|
||||
│ └── page.tsx
|
||||
├── middleware.ts 保護 /dashboard（讀 cookie）
|
||||
├── lib/
|
||||
│ └── auth.ts session helpers
|
||||
├── public/
|
||||
├── next.config.ts
|
||||
├── package.json
|
||||
└── wrangler.toml CF Pages 設定
|
||||
```
|
||||
|
||||
cypher-executor 新增：
|
||||
```
|
||||
arcrun/cypher-executor/src/routes/
|
||||
├── auth.ts ← 新增（OAuth start/callback/logout/me）
|
||||
```
|
||||
|
||||
cypher-executor wrangler.toml 新增：
|
||||
```toml
|
||||
[[kv_namespaces]]
|
||||
binding = "USERS_KV"
|
||||
id = "<to be created>"
|
||||
|
||||
[[kv_namespaces]]
|
||||
binding = "SESSIONS_KV"
|
||||
id = "455d0505c7534883a4d4985ab8295857"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 環境變數 / Secrets
|
||||
|
||||
### cypher-executor（Worker Secrets）
|
||||
|
||||
```
|
||||
GOOGLE_CLIENT_ID Google OAuth App client_id（僅 openid profile email scope）
|
||||
GOOGLE_CLIENT_SECRET Google OAuth App client_secret
|
||||
GITHUB_CLIENT_ID GitHub OAuth App client_id（read:user + user:email scope）
|
||||
GITHUB_CLIENT_SECRET GitHub OAuth App client_secret
|
||||
SESSION_SECRET 隨機 32 bytes，用於 HMAC session ID（或直接用 UUID）
|
||||
```
|
||||
|
||||
### landing（Pages Environment Variables）
|
||||
|
||||
```
|
||||
NEXT_PUBLIC_API_BASE https://cypher.arcrun.dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 實作步驟（Checklist）
|
||||
|
||||
### Phase 1：cypher-executor 後端擴充
|
||||
|
||||
- [x] `wrangler kv:namespace create USERS_KV` → 填入 wrangler.toml (id: 25bef01d079148919578894434d58c4d)
|
||||
- [x] `wrangler kv:namespace create SESSIONS_KV` → 填入 wrangler.toml (id: 455d0505c7534883a4d4985ab8295857)
|
||||
- [x] 建立 `arcrun/cypher-executor/src/routes/auth.ts`
|
||||
- [x] GET `/auth/google/start`
|
||||
- [x] GET `/auth/github/start`
|
||||
- [x] GET `/auth/callback`（換 token → userinfo → upsert USERS_KV → 建 session → Set-Cookie → redirect）
|
||||
- [x] POST `/auth/logout`
|
||||
- [x] GET `/me`（讀 session cookie 或 API Key header）
|
||||
- [x] PUT `/me/api-key/rotate`
|
||||
- [x] DELETE `/me/api-key`（revoke）
|
||||
- [x] 在 `src/index.ts` 掛載 `authRouter`
|
||||
- [ ] `wrangler secret put GOOGLE_CLIENT_ID` 等 4 個 secrets ← **用戶需自建 Google/GitHub OAuth App**
|
||||
- [x] `wrangler deploy` ← 已部署（Worker version 7877857b）
|
||||
|
||||
### Phase 2：Next.js Landing 專案
|
||||
|
||||
- [x] `npx create-next-app@latest arcrun/landing --typescript --tailwind --app`
|
||||
- [x] 設定 `@cloudflare/next-on-pages`（Next.js 15 + .npmrc legacy-peer-deps）
|
||||
- [ ] 建立 `middleware.ts`（保護 /dashboard，讀 `arcrun_session` cookie）← 待做
|
||||
- [x] 首頁（`app/page.tsx`）：Hero + Code Demo tab + CTA
|
||||
- [x] 登入頁（`app/login/page.tsx`）：Google / GitHub 按鈕（href 到 cypher.arcrun.dev/auth/google/start）
|
||||
- [x] Dashboard（`app/dashboard/page.tsx`）：顯示 API Key，Rotate / Revoke 按鈕
|
||||
- [x] Swagger UI（`app/api-docs/page.tsx`）：client component，動態 import swagger-ui CDN
|
||||
- [x] 服務目錄（`app/integrations/page.tsx`）：靜態，列 20 個 recipe
|
||||
- [ ] 中英切換 ← 低優先，可延後
|
||||
- [x] `wrangler pages deploy` → https://42a8d302.arcrun-landing.pages.dev
|
||||
- [ ] Cloudflare dashboard 設定 arcrun.dev custom domain → arcrun-landing Pages project
|
||||
|
||||
### Phase 3：驗收（待 OAuth Secrets 填入後）
|
||||
|
||||
- [ ] Google / GitHub OAuth 完整流程（登入 → dashboard → 看到 key）
|
||||
- [ ] Rotate：新 key 出現
|
||||
- [ ] Revoke：舊 key 的 API 呼叫回傳 401
|
||||
- [ ] Swagger UI 正常載入，可試打 `/health`
|
||||
- [x] `/integrations` 正確列出 20 個服務
|
||||
|
||||
---
|
||||
|
||||
## 9. 待決事項（開始實作前確認）
|
||||
|
||||
| 問題 | 預設決策 |
|
||||
|---|---|
|
||||
| Google OAuth App 是否要另建（只有 email scope）? | 是，另建；auth recipe 的 App 不動 |
|
||||
| Rotate 後舊 credentials 是否遷移？ | 不遷移，顯示提示 |
|
||||
| Domain arcrun.dev 是否已購入且在 Cloudflare？ | 假設是（wrangler.toml 有設 zone_name） |
|
||||
| 登入後 redirect 預設到 /dashboard | 是，可從 `?redirect=` 覆寫 |
|
||||
@@ -0,0 +1,281 @@
|
||||
# Design Document: arcrun SDK Libraries + Website
|
||||
|
||||
## Overview
|
||||
|
||||
本設計涵蓋 arcrun 的三個新增交付物：
|
||||
1. Python SDK lib（`pip install arcrun`）
|
||||
2. JS/TS SDK lib（`npm install arcrun` 或 `@arcrun/sdk`）
|
||||
3. arcrun.dev 網站完善（零件列表、recipe 列表、登入管理）
|
||||
|
||||
**設計原則：修改不重建。** SDK 是 `cypher.arcrun.dev` HTTP API 的 thin wrapper。不在 client 端重新實作任何 server 端已有的邏輯（workflow 執行、credential 注入、auth recipe 解析）。唯一在 client 做的是 AES-GCM 加密（因為 server 的 POST /credentials 期望收到加密後的 payload）。
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### 系統關係圖
|
||||
|
||||
```
|
||||
使用者程式碼
|
||||
├── CLI（acr） → cypher.arcrun.dev（HTTP API）
|
||||
├── Python SDK（arcrun） → cypher.arcrun.dev（HTTP API）
|
||||
└── JS SDK（arcrun / @arcrun/sdk） → cypher.arcrun.dev（HTTP API）
|
||||
|
||||
arcrun.dev 網站（Next.js / Cloudflare Pages）
|
||||
├── /login → /auth/google/start, /auth/github/start（cypher.arcrun.dev）
|
||||
├── /dashboard → /me, /me/api-key/rotate（cypher.arcrun.dev）
|
||||
├── /integrations → /auth-recipes（cypher.arcrun.dev）
|
||||
└── /components → /recipes + 靜態零件清單（embedded）
|
||||
|
||||
cypher.arcrun.dev（Cloudflare Worker — cypher-executor，不改）
|
||||
├── POST /credentials ← 接收 { name, encrypted, iv }
|
||||
├── GET /credentials ← 列出 credential 名稱
|
||||
├── DELETE /credentials/:name ← 刪除 credential
|
||||
├── GET /auth-recipes ← 列出 20 個 auth recipe
|
||||
├── GET /auth-recipes/:service ← 單一 recipe 詳情
|
||||
├── POST /webhooks/named ← 部署 workflow
|
||||
├── POST /webhooks/named/:name/trigger ← 觸發 workflow
|
||||
├── GET /webhooks/named ← 列出 workflow
|
||||
├── POST /register ← 註冊取得 API Key
|
||||
├── GET /me ← 當前用戶資訊
|
||||
└── /auth/* ← OAuth 流程
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Python SDK（`arcrun/python-sdk/`）
|
||||
|
||||
### 目錄結構
|
||||
|
||||
```
|
||||
arcrun/python-sdk/
|
||||
├── pyproject.toml ← hatchling build, name="arcrun", deps=[httpx>=0.27, cryptography>=42]
|
||||
├── README.md
|
||||
└── arcrun/
|
||||
├── __init__.py ← from .client import Arcrun
|
||||
├── client.py ← Arcrun class（主入口）
|
||||
├── crypto.py ← AES-GCM 加密（client 端，用 cryptography 套件）
|
||||
├── creds.py ← CredentialsClient（push/list/delete）
|
||||
├── auth.py ← AuthClient（setup/bind/get_token/list_services）
|
||||
└── workflows.py ← WorkflowClient（run/push/list/delete）
|
||||
```
|
||||
|
||||
### API 設計
|
||||
|
||||
```python
|
||||
from arcrun import Arcrun
|
||||
|
||||
# 建構 — api_key 從參數 > 環境變數 > ~/.arcrun/config.yaml 自動取得
|
||||
client = Arcrun()
|
||||
# 或明確指定
|
||||
client = Arcrun(api_key="ak_xxx", encryption_key="hexstring")
|
||||
|
||||
# Auth：設定並綁定服務
|
||||
client.auth.setup("openai", api_key="sk-xxx") # 加密 + 上傳
|
||||
openai_client = client.auth.bind("openai") # 取回 pre-auth client
|
||||
response = openai_client.get("/models") # httpx.Client
|
||||
token = client.auth.get_token("openai") # raw token string
|
||||
services = client.auth.list_services() # [{ service, display_name, ... }]
|
||||
|
||||
# Credentials：低階操作
|
||||
client.creds.push("my_token", "value123")
|
||||
names = client.creds.list()
|
||||
client.creds.delete("my_token")
|
||||
|
||||
# Workflows
|
||||
result = client.workflows.run("my-flow", {"email": "user@example.com"})
|
||||
url = client.workflows.push("my-flow", graph_dict)
|
||||
workflows = client.workflows.list()
|
||||
```
|
||||
|
||||
### Credential 加密流程
|
||||
|
||||
```
|
||||
setup("openai", api_key="sk-xxx")
|
||||
1. GET /auth-recipes/openai → recipe（含 required_secrets, inject）
|
||||
2. 對應 required_secrets[0].key = "openai_api_key"
|
||||
3. crypto.py 用 encryption_key AES-GCM 加密 "sk-xxx"
|
||||
4. POST /credentials → { name: "openai_api_key", encrypted, iv }
|
||||
5. 本地 _cred_cache["openai_api_key"] = "sk-xxx"（供 bind() 用）
|
||||
|
||||
bind("openai")
|
||||
1. GET /auth-recipes/openai → recipe.inject.header = { Authorization: "Bearer {{secret.openai_api_key}}" }
|
||||
2. 用 _cred_cache["openai_api_key"] 替換 template → "Bearer sk-xxx"
|
||||
3. 回傳 AuthenticatedClient(base_url="https://api.openai.com/v1", headers={"Authorization": "Bearer sk-xxx"})
|
||||
```
|
||||
|
||||
**注意**：`bind()` 依賴 `setup()` 在同一 session 建立的 `_cred_cache`。跨 session 使用時（credential 已上傳但 cache 不存在），`bind()` 無法解析 template — 此時 `get_token()` 也無法返回值。**這是已知限制，封測期間先接受。** 長期解法是 server 提供 `/credentials/:name/secret` 解密端點（u6u-core/credentials 已有）。
|
||||
|
||||
### 關鍵差異：crypto.py 的定位
|
||||
|
||||
`crypto.py` 只做 **加密**（encrypt），不做解密。
|
||||
功能等同 `u6u-core/credentials/src/actions/crypto.ts` 的 `encrypt()` 函數。
|
||||
解密只在 server 端發生（cypher-executor 的 `credential-injector.ts` 或 `u6u-core/credentials/getCredentialSecret.ts`）。
|
||||
|
||||
---
|
||||
|
||||
## JS/TS SDK（`arcrun/js-sdk/`）
|
||||
|
||||
### 目錄結構
|
||||
|
||||
```
|
||||
arcrun/js-sdk/
|
||||
├── package.json ← name TBD（arcrun vs @arcrun/sdk），tsup build
|
||||
├── tsconfig.json ← ES2020, NodeNext
|
||||
└── src/
|
||||
├── index.ts ← export class Arcrun
|
||||
├── crypto.ts ← Web Crypto API AES-GCM encrypt（client 端）
|
||||
├── creds.ts ← CredentialsClient（push/list/delete）
|
||||
├── auth.ts ← AuthClient（setup/bind/getToken/listServices）
|
||||
└── workflows.ts ← WorkflowClient（run/push/list/delete）
|
||||
```
|
||||
|
||||
### API 與 Python SDK 對等
|
||||
|
||||
```typescript
|
||||
import { Arcrun } from 'arcrun' // or '@arcrun/sdk'
|
||||
|
||||
const client = new Arcrun() // reads ARCRUN_API_KEY from env
|
||||
|
||||
await client.auth.setup('openai', { api_key: 'sk-xxx' })
|
||||
const oai = await client.auth.bind('openai')
|
||||
const models = await (await oai.get('/models')).json()
|
||||
|
||||
const token = await client.auth.getToken('openai')
|
||||
const services = await client.auth.listServices()
|
||||
|
||||
await client.creds.push('my_token', 'value')
|
||||
const names = await client.creds.list()
|
||||
|
||||
const result = await client.workflows.run('my-flow', { email: 'user@example.com' })
|
||||
```
|
||||
|
||||
### Build 產物
|
||||
|
||||
```
|
||||
dist/
|
||||
├── index.js ← ESM
|
||||
├── index.cjs ← CJS
|
||||
├── index.d.ts ← TypeScript 型別
|
||||
└── index.d.cts
|
||||
```
|
||||
|
||||
### Crypto 實作
|
||||
|
||||
使用 Web Crypto API（`crypto.subtle`），相容 Node 18+ / browsers / CF Workers / Deno：
|
||||
|
||||
```typescript
|
||||
async function encrypt(plaintext: string, hexKey: string): Promise<{ encrypted: string; iv: string }> {
|
||||
const key = await crypto.subtle.importKey('raw', hexToBytes(hexKey), { name: 'AES-GCM' }, false, ['encrypt']);
|
||||
const iv = crypto.getRandomValues(new Uint8Array(12));
|
||||
const ciphertext = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, new TextEncoder().encode(plaintext));
|
||||
return { encrypted: toBase64(ciphertext), iv: toBase64(iv.buffer) };
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## arcrun.dev 網站
|
||||
|
||||
### 現有狀態（`arcrun/landing/`）
|
||||
|
||||
已完成：
|
||||
- [x] `/` — Hero + Code Demo（Python/JS/HTTP tabs）
|
||||
- [x] `/login` — Google + GitHub OAuth 按鈕（前端 OK，需設 OAuth secrets）
|
||||
- [x] `/dashboard` — API Key 查看/Copy/Rotate/Revoke（依賴 `/me` API）
|
||||
- [x] `/integrations` — 20 個 recipe 靜態卡片
|
||||
- [x] `/api-docs` — Swagger UI CDN 嵌入
|
||||
- [x] `middleware.ts` — 保護 `/dashboard`（未登入 → `/login`）
|
||||
- [x] Cloudflare Pages 部署
|
||||
|
||||
待完成：
|
||||
- [ ] OAuth secrets 設定（`GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` / `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET`）
|
||||
- [ ] `/components` 頁面（零件列表 — 21 個 WASM 零件的 input/output/config_example）
|
||||
- [ ] 首頁 code demo 更新為三種使用方式（CLI / Python / JS）
|
||||
- [ ] 登入流程真實驗證
|
||||
|
||||
### 新增頁面：`/components`
|
||||
|
||||
```
|
||||
/components
|
||||
├── 零件卡片（21 個）
|
||||
│ ├── canonical_id
|
||||
│ ├── display_name
|
||||
│ ├── description
|
||||
│ ├── input_schema（required / optional 欄位）
|
||||
│ ├── output_schema
|
||||
│ ├── credentials_required（if any）
|
||||
│ └── config_example（YAML code block）
|
||||
└── 分類篩選（邏輯 / API / 控制流）
|
||||
```
|
||||
|
||||
資料來源：靜態嵌入（從 `registry/components/*/component.contract.yaml` 在 build 時讀取），不依賴 runtime API。
|
||||
|
||||
### OAuth 設定（待 richblack 操作）
|
||||
|
||||
需要在 Cloudflare Worker 設定以下 secrets：
|
||||
|
||||
```bash
|
||||
wrangler secret put GOOGLE_CLIENT_ID --name arcrun-cypher-executor
|
||||
wrangler secret put GOOGLE_CLIENT_SECRET --name arcrun-cypher-executor
|
||||
wrangler secret put GITHUB_CLIENT_ID --name arcrun-cypher-executor
|
||||
wrangler secret put GITHUB_CLIENT_SECRET --name arcrun-cypher-executor
|
||||
wrangler secret put SESSION_SIGNING_SECRET --name arcrun-cypher-executor
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## server 端需要的修改
|
||||
|
||||
### cypher-executor 修改（最小化）
|
||||
|
||||
目前 `POST /credentials` 端點（`routes/credentials.ts`）接收 `{ name, encrypted, iv }` 後直接存 KV。
|
||||
|
||||
SDK 需要的改動：
|
||||
|
||||
1. **`GET /auth-recipes` 回應格式**：目前 list 端點回 `{ recipes: [...] }` 但 recipe 的 `service` 欄位是 key — SDK 已在 list_services() 正確處理 ✅
|
||||
|
||||
2. **`GET /auth-recipes/:service` 回應格式**：目前回 `{ success: true, recipe: {...} }` — SDK 需讀 `body.recipe` 而非 body 本身 ✅
|
||||
|
||||
3. **`POST /credentials` 不需改動** — SDK 自己做 AES-GCM 加密後送 `{ name, encrypted, iv }` ✅
|
||||
|
||||
4. **未來**：新增 `GET /credentials/:name/secret` 端點（解密返回 plaintext），讓跨 session 的 `bind()` 能工作。但此端點在 `u6u-core/credentials/src/actions/getCredentialSecret.ts` 已有實作 — 需要在 cypher-executor 整合或 Service Binding 到 u6u-credentials Worker。**封測後再做。**
|
||||
|
||||
---
|
||||
|
||||
## 不做的事（明確排除）
|
||||
|
||||
- ❌ 不在 SDK 裡做 workflow 解析或 YAML 處理 — 那是 CLI 的職責
|
||||
- ❌ 不在 SDK 裡做 server-side 解密 — 解密只在 server 端
|
||||
- ❌ 不建新的 credentials Worker — 用現有的
|
||||
- ❌ 不建新的 KV namespace — 用現有的 CREDENTIALS_KV
|
||||
- ❌ 不改 cypher-executor 的 credential-injector.ts — 那已經完成且測試通過
|
||||
|
||||
---
|
||||
|
||||
## 實作順序
|
||||
|
||||
```
|
||||
Phase 1：Python SDK 重建 + 測試
|
||||
1.1 重建 arcrun/python-sdk/（按本 SDD 的結構）
|
||||
1.2 修正上次的 bug：recipe 回應 wrapper、inject key "header" vs "headers"、secret key mapping
|
||||
1.3 對 cypher.arcrun.dev live 測試全部 API
|
||||
1.4 本地安裝測試（pip install -e .）
|
||||
|
||||
Phase 2：JS SDK 重建 + 測試
|
||||
2.1 重建 arcrun/js-sdk/（按本 SDD 的結構）
|
||||
2.2 同步修正 Python SDK 發現的所有 recipe 格式問題
|
||||
2.3 build（tsup）+ 本地測試
|
||||
|
||||
Phase 3：arcrun.dev 網站補完
|
||||
3.1 新增 /components 頁面
|
||||
3.2 更新首頁 code demo（三種使用方式）
|
||||
3.3 OAuth secrets 設定（需 richblack 操作 GCP / GitHub）
|
||||
3.4 登入流程驗證
|
||||
|
||||
Phase 4：GitHub README + 發布
|
||||
4.1 更新 arcrun/README.md — 三種 Quick Start
|
||||
4.2 pip publish（arcrun）
|
||||
4.3 npm publish（TBD 套件名）
|
||||
4.4 最終驗證：從零開始 pip install / npm install / 打 API
|
||||
```
|
||||
@@ -0,0 +1,131 @@
|
||||
# Requirements: arcrun SDK Libraries + Website
|
||||
|
||||
## Introduction
|
||||
|
||||
arcrun 目前有三個使用介面：
|
||||
1. **CLI**（`acr` 指令）— 已完成，用 YAML 定義 workflow 並推送執行
|
||||
2. **Python / JS SDK lib**（本次新增）— `pip install arcrun` / `npm install arcrun`，讓開發者在寫程式時直接用 arcrun 功能
|
||||
3. **arcrun.dev 網站**（本次完成）— 登入取得 API Key、管理 Key、瀏覽零件 / recipe 列表
|
||||
|
||||
**核心原則**：SDK lib 是 `cypher.arcrun.dev` HTTP API 的 thin wrapper。所有業務邏輯（加解密、credential 注入、workflow 執行）都在 server 端完成。Client 端不重做 server 已有的邏輯。
|
||||
|
||||
**現有基礎設施**（不重建，直接使用）：
|
||||
- `cypher.arcrun.dev`：cypher-executor Worker（workflow 執行、credential 管理、auth recipe、webhook）
|
||||
- `u6u-core/credentials`：credential Worker（AES-GCM 加解密）— arcrun/credentials 是其 cherry-pick
|
||||
- `arcrun/cli`：CLI 工具（已發布 npm `arcrun@1.1.0`）
|
||||
- `arcrun/landing`：Next.js 前端（已部署 Cloudflare Pages，有 hero/login/dashboard/integrations 骨架）
|
||||
|
||||
---
|
||||
|
||||
## Glossary
|
||||
|
||||
- **SDK lib**：Python / JS 套件，wrapping `cypher.arcrun.dev` HTTP API，安裝後可在程式碼中直接使用
|
||||
- **auth.setup()**：上傳一個服務的 credential（如 Notion token、OpenAI API Key）到 arcrun
|
||||
- **auth.bind()**：取回已設定服務的 pre-authenticated HTTP client
|
||||
- **auth.get_token()**：取回某服務的 raw token（escape hatch，給官方 SDK 用）
|
||||
- **workflows.run()**：觸發已部署的 workflow
|
||||
- **workflows.push()**：上傳 workflow 定義
|
||||
- **Recipe**：描述「如何對某服務認證」的 YAML 設定，存在 RECIPES KV
|
||||
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement 1：Python SDK（`pip install arcrun`）
|
||||
|
||||
**User Story:** As a Python 開發者, I want `pip install arcrun` 後在程式碼中使用 arcrun, so that 不用離開寫程式環境就能串接 20+ 服務。
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Python SDK SHALL 以 `arcrun` 套件名發布到 PyPI，支援 Python 3.10+。
|
||||
2. THE SDK SHALL 提供以下 API：
|
||||
- `Arcrun(api_key=, base_url=)` — 建構 client，api_key 支援從環境變數 `ARCRUN_API_KEY` 或 `~/.arcrun/config.yaml` 自動讀取
|
||||
- `client.health()` — 健康檢查
|
||||
- `client.auth.list_services()` — 列出可用 auth recipe 服務
|
||||
- `client.auth.setup(service, **kwargs)` — 上傳 credential
|
||||
- `client.auth.bind(service)` — 取得 pre-authenticated HTTP client
|
||||
- `client.auth.get_token(service)` — 取得 raw token
|
||||
- `client.creds.push(name, value)` — 上傳加密 credential
|
||||
- `client.creds.list()` — 列出 credential 名稱
|
||||
- `client.creds.delete(name)` — 刪除 credential
|
||||
- `client.workflows.run(name, input)` — 觸發 workflow
|
||||
- `client.workflows.push(name, graph)` — 上傳 workflow
|
||||
- `client.workflows.list()` — 列出已部署 workflow
|
||||
3. THE SDK 的 credential 加密 SHALL 在 client 端完成（使用 `cryptography` 套件 AES-GCM），然後以 `POST /credentials` 上傳加密後的 `{ name, encrypted, iv }` 到 server。
|
||||
4. THE `auth.bind()` SHALL 從 server 取得 auth recipe 的 inject template，在 client 端用 cache 的 plaintext 值填入，回傳 pre-configured `httpx.Client`。
|
||||
5. THE SDK SHALL 使用 `httpx` 做 HTTP client（async 版使用 `httpx.AsyncClient`）。
|
||||
6. THE SDK 位置 SHALL 為 `arcrun/python-sdk/`，build 系統用 `hatchling`（`pyproject.toml`）。
|
||||
|
||||
---
|
||||
|
||||
### Requirement 2：JavaScript/TypeScript SDK（`npm install arcrun`）
|
||||
|
||||
**User Story:** As a JS/TS 開發者, I want `npm install arcrun` 後在程式碼中使用 arcrun, so that 可以嵌入現有 Node.js / Deno / Cloudflare Workers 專案。
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE JS SDK SHALL 以 `arcrun` 套件名發布到 npm，提供 ESM + CJS 雙格式 + TypeScript 型別定義。
|
||||
2. THE SDK SHALL 提供與 Python SDK 對等的 API（camelCase 版）：
|
||||
- `new Arcrun({ apiKey?, baseUrl? })` — 讀 `process.env.ARCRUN_API_KEY`
|
||||
- `client.health()` — 回傳 `Promise<unknown>`
|
||||
- `client.auth.listServices()` / `setup()` / `bind()` / `getToken()`
|
||||
- `client.creds.push()` / `list()` / `delete()`
|
||||
- `client.workflows.run()` / `push()` / `list()` / `delete()`
|
||||
3. THE SDK 的 credential 加密 SHALL 使用 Web Crypto API（`crypto.subtle` AES-GCM），相容 Node 18+、browsers、Cloudflare Workers、Deno。
|
||||
4. THE `auth.bind()` SHALL 回傳一個有 `get/post/put/delete/patch` 方法的 `AuthenticatedClient`，base URL + auth headers 已配置。
|
||||
5. THE SDK SHALL 使用原生 `fetch()` API，不依賴外部 HTTP client 套件。
|
||||
6. THE SDK 位置 SHALL 為 `arcrun/js-sdk/`，build 用 `tsup`（ESM + CJS + DTS），`tsconfig.json` target ES2020 + NodeNext module。
|
||||
7. THE JS SDK 套件名與 CLI 套件名衝突（都叫 `arcrun`），SHALL 使用 `@arcrun/sdk` 或由 richblack 決定套件名。
|
||||
|
||||
---
|
||||
|
||||
### Requirement 3：arcrun.dev 網站完成
|
||||
|
||||
**User Story:** As a 潛在用戶, I want 在 arcrun.dev 上登入取得 API Key、瀏覽零件和 recipe 列表, so that 我可以評估 arcrun 是否符合需求並立即開始使用。
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE 網站 SHALL 在 `arcrun.dev` 提供以下頁面：
|
||||
- `/` — 首頁 Hero + 三種使用方式（CLI / Python / JS）
|
||||
- `/login` — Google + GitHub OAuth 登入
|
||||
- `/dashboard` — 登入後顯示 API Key（查看/Copy/Rotate/Revoke）
|
||||
- `/integrations` — 列出 20 個 auth recipe 服務，可按分類篩選
|
||||
- `/components` — 列出所有零件（21 個 WASM 零件），顯示 input/output schema、config_example
|
||||
- `/api-docs` — Swagger UI，可直接試打 API
|
||||
2. THE 登入 SHALL 使用 Google + GitHub OAuth，流程走 `cypher.arcrun.dev` 的 `/auth/*` 端點。
|
||||
3. THE 登入後 SHALL 自動對該 email 呼叫 `/register` 取得 API Key（若已有則取回現有 key）。
|
||||
4. THE `/dashboard` SHALL 允許 Rotate（生成新 key）、Revoke（標記失效）、Copy to clipboard。
|
||||
5. THE 網站 SHALL 部署在 Cloudflare Pages（現有 `arcrun/landing`），使用 Next.js App Router。
|
||||
6. THE 首頁 code demo 區 SHALL 包含三個 tab：Python、JavaScript、HTTP/curl，展示三種使用方式。
|
||||
|
||||
---
|
||||
|
||||
### Requirement 4：GitHub README 更新
|
||||
|
||||
**User Story:** As a GitHub 訪客, I want README 清楚說明三種使用方式, so that 我能選擇最適合的方式開始用 arcrun。
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE `arcrun/README.md` SHALL 包含三種 Quick Start：
|
||||
- **CLI**：`npm i -g arcrun && acr init && acr push workflow.yaml && acr run`
|
||||
- **Python**：`pip install arcrun && from arcrun import Arcrun && ...`
|
||||
- **JavaScript**：`npm install arcrun && import { Arcrun } from 'arcrun' && ...`
|
||||
2. THE README SHALL 包含完整零件列表（21 個）和 auth recipe 列表（20 個服務）。
|
||||
3. THE README SHALL 連結到 `arcrun.dev`（取得 API Key）和 Swagger UI（API 文件）。
|
||||
|
||||
---
|
||||
|
||||
### Requirement 5：SDK 發布
|
||||
|
||||
**User Story:** As a SDK 使用者, I want 公開安裝並直接使用, so that 不需要從原始碼 build。
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Python SDK SHALL 發布到 PyPI，`pip install arcrun` 可安裝。
|
||||
2. THE JS SDK SHALL 發布到 npm，`npm install arcrun`（或 `@arcrun/sdk`）可安裝。
|
||||
3. THE 發布前 SHALL 完成以下測試（對 `cypher.arcrun.dev` live API）：
|
||||
- `health()` ✅
|
||||
- `auth.list_services()` ✅
|
||||
- `auth.setup()` + `auth.bind()` ✅（至少一個 static_key 服務如 openai）
|
||||
- `creds.push()` + `creds.list()` ✅
|
||||
- `workflows.list()` ✅
|
||||
@@ -0,0 +1,224 @@
|
||||
# Design 補充：`acr init --self-hosted` 一鍵自動化（installer 模式）
|
||||
|
||||
> 2026-06-01 初稿 → 2026-06-02 定案改寫（richblack 拍板 installer 形態）。
|
||||
> 本檔是 `sdk-and-website/design.md` 的單檔補充（規則 02 §4.3 允許）。
|
||||
> **狀態：design 已與 richblack 對齊；實作前讀 §6 前置依賴。**
|
||||
> 背景：戰法從 SaaS 轉 self-hosted 開源（docs/HANDOFF-self-host-harness.md §0）。
|
||||
|
||||
---
|
||||
|
||||
## 1. 定案形態（richblack 2026-06-02）
|
||||
|
||||
**arcrun CLI = installer / orchestrator**（類似 rustup / nvm：工具本身小，按需從遠端拉真正內容）。
|
||||
|
||||
### 用戶只做 4 件事，中間什麼都不用懂：
|
||||
1. 申請 CF 帳號
|
||||
2. 安裝 CF CLI（`wrangler`）
|
||||
3. 安裝 arcrun CLI（`npm i -g arcrun`）
|
||||
4. `acr init --self-hosted`（貼 CF Account ID + API Token）→ **完成，其餘看機器跑**
|
||||
|
||||
### CLI 自動做（用戶無感）：
|
||||
- 驗 CF token 權限
|
||||
- 建 7 個 KV namespace + 1 個 R2 bucket（冪等）
|
||||
- **從 GitHub release 下載預編譯部署物**（含 24 個 `.wasm` + 各 Worker 的 wrangler.toml + cypher-executor/registry）
|
||||
- 把建好的 KV namespace id 注入各 wrangler.toml + cypher-executor 的 `WORKER_SUBDOMAIN`
|
||||
- **`wrangler deploy` 部署全部 Worker**（用戶已裝 wrangler）
|
||||
- seed auth recipe + API recipe 進 RECIPES KV
|
||||
- 寫回 `~/.arcrun/config.yaml`
|
||||
- 印出「手動 `wrangler secret put ENCRYPTION_KEY` ×3」提示（secret 不自動化，rule 05）
|
||||
|
||||
### 關鍵技術決策（richblack 2026-06-02）
|
||||
| 決策 | 選擇 | 理由 |
|
||||
|---|---|---|
|
||||
| 零件部署物 | **預編譯 `.wasm`**（不在用戶端 build）| 用戶不懂 tinygo、也不該懂。下載即用。 |
|
||||
| 部署工具 | **wrangler**（shell out）| 用戶已裝 CF CLI；self-host 本來就有上傳能力。CLI 不自己重寫 CF Script Upload API。 |
|
||||
| 源碼來源 | **GitHub release tarball**（含預編譯 wasm）| 版本明確、不需用戶有 git、`acr update` 拉新 release 同一條路。 |
|
||||
| 為何不是 git clone | repo **沒 commit `.wasm`**（rule 05 build 產物不 commit）→ clone 拿不到 wasm | 必須走含 wasm 的 release artifact。 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 為什麼是 installer 而非「repo 內掃 wrangler.toml」（推翻初稿）
|
||||
|
||||
初稿假設「用戶在 repo 內跑、CLI 掃 wrangler.toml」。**推翻**，因為：
|
||||
- npm 全域裝的 `acr` 手上**沒有** 24 個 Worker 源碼。
|
||||
- repo 沒 commit `.wasm`（已查證 `git ls-files .component-builds | grep .wasm` = 0）→ 連 clone 都拿不到可部署的 wasm。
|
||||
- 用戶不該需要懂 git / tinygo / repo 結構。
|
||||
|
||||
→ 正解：CLI 當 installer，從 **GitHub release（含預編譯 wasm）** 拉部署物到暫存目錄，在暫存目錄注入 KV id 後 `wrangler deploy`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 流程設計（`initSelfHosted` 改寫）
|
||||
|
||||
```
|
||||
acr init --self-hosted
|
||||
│
|
||||
├─ 1. 問 2 輸入：CF Account ID + CF API Token
|
||||
│ （wrangler 是否已裝？which wrangler；沒裝 → 提示先裝 CF CLI 再來）
|
||||
│ 驗 token：CF API GET /accounts/{id}/tokens/verify + GET /accounts/{id}
|
||||
│ 缺權限（Workers Scripts Edit / KV Edit / R2 Edit）→ exit 1 指出缺哪個 scope
|
||||
│
|
||||
├─ 2. 建資源（冪等：先 list 已存在就重用）
|
||||
│ 7 KV：WEBHOOKS / CREDENTIALS_KV / RECIPES / USERS_KV /
|
||||
│ SESSIONS_KV / ANALYTICS_KV / EXEC_CONTEXT（rule 01 資料儲存表）
|
||||
│ 1 R2：WASM_BUCKET
|
||||
│
|
||||
├─ 3. 下載部署物：GitHub release tarball → 解壓到暫存目錄 (~/.arcrun/.deploy-<ver>/)
|
||||
│ 內含：cypher-executor/ + registry/ + .component-builds/*（每個含預編譯 component.wasm + wrangler.toml）
|
||||
│
|
||||
├─ 4. 注入設定到暫存目錄的 wrangler.toml（不改用戶 repo，改暫存副本）
|
||||
│ - 各 Worker 的 KV binding id ← step 2 建立的
|
||||
│ - cypher-executor [vars] WORKER_SUBDOMAIN ← CF API GET /accounts/{id}/workers/subdomain
|
||||
│
|
||||
├─ 5. 部署：對暫存目錄每個含 wrangler.toml 的 dir，shell out
|
||||
│ `wrangler deploy`（env CLOUDFLARE_API_TOKEN=<token>, CLOUDFLARE_ACCOUNT_ID=<id>）
|
||||
│ 分兩層：tier1 = .component-builds/*（先）→ tier2 = cypher-executor / registry（後）
|
||||
│ 每個 wrangler.toml 已含 workers_dev = true → workers.dev URL 自動啟用
|
||||
│
|
||||
├─ 6. seed recipe 進 RECIPES KV（部署後打新 cypher URL，或直接 CF KV API 寫）
|
||||
│ - auth recipe：重用 AUTH_RECIPE_SEEDS（cypher-executor/src/lib/auth-recipe-seeds.ts）
|
||||
│ - API recipe：新增 seed-api-recipes.ts（見 §5）
|
||||
│
|
||||
├─ 7. 寫回 config（mode: self-hosted + 所有 id + cypher_executor_url = 部署後 workers.dev URL）
|
||||
│
|
||||
└─ 8. 印手動 secret 提示：
|
||||
wrangler secret put ENCRYPTION_KEY --name arcrun-cypher-executor
|
||||
wrangler secret put ENCRYPTION_KEY --name arcrun-auth-static-key
|
||||
wrangler secret put ENCRYPTION_KEY --name arcrun-auth-service-account
|
||||
（三 Worker 共用同一把 key，見 memory: encryption-key-drift-trap）
|
||||
```
|
||||
|
||||
### `acr update`（同一條路，未來新零件）
|
||||
- 拉新 GitHub release → 解壓 → 注入既有 config 的 KV id → wrangler deploy 變動的 Worker。
|
||||
- 第一期至少做到「重跑等效 init 的部署步驟」；diff-only 部署可後續優化。
|
||||
|
||||
---
|
||||
|
||||
## 4. 動到的檔案
|
||||
|
||||
| 檔案 | 動作 |
|
||||
|---|---|
|
||||
| `cli/src/commands/init.ts` | 改寫 `initSelfHosted()`（line 105-131）為 installer 流程 |
|
||||
| `cli/src/lib/cf-api.ts` | 擴充：KV namespace 建立/list、R2 bucket 建立、subdomain 查詢、token verify |
|
||||
| 新增 `cli/src/lib/deploy.ts`（暫定）| 下載 release tarball + 解壓 + 注入 wrangler.toml + shell out wrangler deploy |
|
||||
| 新增 `cli/src/commands/update.ts`（暫定）| `acr update`：拉新 release 重部署 |
|
||||
| 新增 `cli/src/lib/api-recipe-seeds.ts` | API recipe **種子資料**（installer 用；放 CLI 端，**不放 cypher-executor/src**——rule 02 §2.2 hook 擋 cypher-executor TS hard-code endpoint，且 seed 資料本就屬 installer 職責）|
|
||||
| 新增 `cypher-executor/scripts/seed-api-recipes.ts` | seed **腳本**（給 prod 補灌用，import CLI 的種子資料；`scripts/` 不受 §2.2 hook 管）|
|
||||
| `cli/src/index.ts` | 註冊 `acr update` 指令 |
|
||||
|
||||
**不動**：cypher-executor 執行路徑、既有零件 wasm 源碼、config 讀取端（config.ts:52 已支援 self-hosted）。
|
||||
|
||||
---
|
||||
|
||||
## 5. API recipe seed（新增 seed-api-recipes.ts，richblack 2026-06-02 定）
|
||||
|
||||
codebase 只有 auth recipe seed。新增 `seed-api-recipes.ts`，把現役 API recipe hard-code 成種子。
|
||||
|
||||
### 現役 API recipe（從 prod KV 查得，2026-06-01）
|
||||
- `kbdb_get`（+ create_block / patch_block / delete / ingest）→ auth_service: kbdb
|
||||
- `gmail_send` → google_gmail_sa
|
||||
- `google_sheets_append` / `google_sheets_read` → google_sheets_sa
|
||||
- `telegram_send` → telegram
|
||||
- `line_notify_send` → line_notify
|
||||
|
||||
### KBDB recipe 採 Supabase 模式（richblack 2026-06-02）
|
||||
- **KBDB 是 richblack 提供的服務**（跟 arcrun 一樣），採「基礎免費、大量收費」。
|
||||
- KBDB recipe **進 seed**（展示能力 = 引子，Supabase 模式）。使用者要用 → 去 **arcrun 取統一 API Key**（已有 /register 入口），把 key 設成 credential。
|
||||
- ⚠️ **FOLLOW-UP（交 KBDB 端）**：現役 endpoint 是 `kbdb.finally.click{{_path}}`。richblack：這是 KBDB 端要改的問題——KBDB 該用統一對外網址提供大家用，不是 finally.click。**seed 先照現況進；KBDB 端改網址後同步更新 seed。** 此事不擋 init 實作。
|
||||
|
||||
---
|
||||
|
||||
## 6. 部署物產製：commit wasm 進 repo + codeload tarball（richblack 2026-06-02 定案）
|
||||
|
||||
> 此節**取代初稿的「GitHub release artifact」構想**。richblack 拍板更輕的做法：
|
||||
> 直接把預編譯 wasm commit 進 repo，CLI 從 GitHub codeload tarball 拿。不需 release.yml 機制。
|
||||
|
||||
### 6.1 策略
|
||||
|
||||
- **repo 自帶可部署的 wasm**：刪 `.gitignore` 的 `*.wasm` 排除，commit 預編譯 wasm 進 repo。
|
||||
→ repo 本身就是部署來源，CLI 直接拿、用戶用自己的 CF token deploy。
|
||||
- **CLI 走 codeload tarball**：`https://codeload.github.com/richblack/arcrun/tar.gz/{ref}`
|
||||
（ref = main 或 tag）。用戶不需 git、版本可控（tag）。`acr update` 拉新 ref。
|
||||
- **理由**（richblack）：「我在我的 CF 能用 = 我已擁有 wasm；用戶指向我的 GitHub 取得 wasm，
|
||||
用他自己的 CF credential deploy。開源，看不看源碼不重要，體驗好最重要。」
|
||||
|
||||
### 6.2 ⚠️ 推翻既有鐵律（rule 05）— 需同步改規則
|
||||
|
||||
`.claude/rules/05-deploy-convention.md` 明文「`.component-builds/{name}/component.wasm` **不 commit 進 repo**
|
||||
（build 產物）」「Phase 1-3 暫時 commit 過，**之後會加 .gitignore 清理**」。
|
||||
**本決策反向**：commit wasm 進 repo（self-host 需 repo 自帶可部署 wasm）。
|
||||
→ **實作時必須同步改 rule 05 + .gitignore**，否則 pre-write hook / 規則與實作打架。
|
||||
→ deploy.yml 的 CI rebuild 步驟仍保留（CI 部署 prod 時用最新 source rebuild，與 commit 的 wasm 不衝突；
|
||||
commit 的 wasm 是給「self-host 用戶 + acr init」用的部署來源）。
|
||||
|
||||
### 6.3 只 commit 部署所需的 wasm（省空間）
|
||||
|
||||
- 實況（2026-06-02 查）：`registry/components/*.wasm` 23 個（build 中間產物）+
|
||||
`.component-builds/*/component.wasm` 22 個（部署物），共 **~50MB**。
|
||||
- **部署只需 `.component-builds/*/component.wasm`**（wrangler deploy 認這個）。
|
||||
→ **只 commit `.component-builds/*/component.wasm`（22 個），不必 commit registry 那 23 個**（省一半）。
|
||||
`.gitignore` 改成：保留排除 `registry/components/**/*.wasm`（中間產物），只放行 `.component-builds/**/component.wasm`。
|
||||
- ⚠️ **誠實 trade-off**（mindset §7）：commit wasm 進 repo → 每次 wasm rebuild 都在 git 歷史累積二進位，
|
||||
**repo 長期會膨脹**。可接受（self-host 體驗優先），但記錄此代價；未來若膨脹過劇，再考慮 release artifact / git-lfs。
|
||||
|
||||
### 6.3.1 「錯做成零件」的 3 個不 commit（richblack 2026-06-02）
|
||||
|
||||
實際 commit 的是 **19 個正當零件**，不是 22。排除的 3 個：`claude_api` / `km_writer` / `kbdb_upsert_block`。
|
||||
- **原因（richblack 修正「待刪」說法）**：它們**不是 endpoint 薄殼，是把工作流硬塞進零件**（違反 DECISIONS §1）。
|
||||
例：`kbdb_upsert_block` 的 upsert 邏輯應在 KBDB API 那邊（API 提供 upsert endpoint），零件只該驅動它；
|
||||
現在卻把「GET 找→有則 PATCH 無則 POST」整段工作流塞進零件。本質是工作流/recipe，被錯做成零件。
|
||||
- **為何「現在就不 commit」而非「先 commit 之後刪」**：commit 二進位進 git 歷史後，即使日後 `git rm`，
|
||||
歷史裡仍永久殘留（repo 體積已被佔），除非 rewrite history（很麻煩）。**錯誤的東西不灌進永久歷史。**
|
||||
- **落地**：`.gitignore` 放行 22 個後**再排除這 3 個**（後出現規則勝出）；`deploy.ts discoverWorkerDirs`
|
||||
只部署「同時有 wrangler.toml + component.wasm」的目錄 → self-host 用戶 codeload 拿到的目錄缺這 3 個 wasm → 自然跳過。
|
||||
- **後續**：這 3 個的降級（變回工作流/recipe）是 BACKLOG 既有待辦，本次不處理，但確保它們不進 self-host 部署來源。
|
||||
|
||||
### 6.4 CLI deploy 流程（deploy.ts downloadAndDeploy 補實作）
|
||||
|
||||
```
|
||||
1. 下載 codeload tarball（ref 預設 main，acr update 可帶 tag）→ 解壓 ~/.arcrun/.deploy-<ref>/
|
||||
2. 讀解壓出的 .component-builds/* + cypher-executor/ + registry/
|
||||
3. 各 wrangler.toml 注入 ctx.kvNamespaceIds + cypher-executor WORKER_SUBDOMAIN
|
||||
4. tier1=.component-builds/*（先）→ tier2=cypher-executor/registry（後）
|
||||
每個 dir：pnpm install（若有 lock）→ CLOUDFLARE_API_TOKEN=<用戶> wrangler deploy
|
||||
5. 回 cypherExecutorUrl = https://arcrun-cypher-executor.<subdomain>.workers.dev
|
||||
```
|
||||
|
||||
注意：tier2（cypher-executor/registry）是 TS，wrangler deploy 會在用戶端用內建 esbuild bundle
|
||||
（不需額外工具，richblack 確認源碼可見不重要、體驗優先 → artifact 含 TS 源碼即可）。
|
||||
|
||||
### 6.5 實作順序
|
||||
|
||||
1. 改 `.gitignore`（放行 `.component-builds/**/component.wasm`）+ commit 22 個 wasm。
|
||||
2. 同步改 rule 05（記錄此決策推翻原慣例）。
|
||||
3. 補實 `deploy.ts downloadAndDeploy`（codeload 下載 + 注入 + wrangler deploy）。
|
||||
4. **在 1-2 完成前，downloadAndDeploy 維持誠實 unimplemented，不假裝（mindset §7）。**
|
||||
|
||||
### 6.6 未來方向：零件按需安裝（richblack 2026-06-02，現在不做）
|
||||
|
||||
- 現在 `acr init --self-hosted` **全裝基礎零件**（22 個一次部署）。簡單、夠用。
|
||||
- **未來若零件數量真的變很多**，再思考「按需安裝」（只裝 workflow 實際用到的零件 / 用戶選裝）。
|
||||
- **現在不做的理由**（DECISIONS 附錄「會不會累積成債」）：零件目前少且未來絕大多數是 recipe
|
||||
（不需 deploy）→ 為「零件爆量」做按需安裝基建 = 為不存在的規模做自動化 = 過度工程。
|
||||
零件真的爆量再回頭做，屆時是「未來一次性處理的設計點」，現在不必焦慮。
|
||||
|
||||
---
|
||||
|
||||
## 7. 驗收標準（客觀證據，mindset §7）
|
||||
|
||||
1. richblack 用**全新 CF 帳號** + wrangler 已裝 + 一個 CF API Token 跑 `acr init --self-hosted`
|
||||
→ 全程無手動建 KV / 無手動 clone / 無 tinygo / 無手動填 namespace id。
|
||||
2. 跑完印 secret 提示，richblack 手動 `wrangler secret put ENCRYPTION_KEY` ×3。
|
||||
3. `acr push` 一個含 http_request + 自建 recipe 的 workflow → trigger → **HTTP 2xx + execution trace**。
|
||||
4. 冪等：重跑 init 不重建已存在 KV / 不報錯。
|
||||
5. `acr update` 拉新 codeload tarball（tag）→ 重部署成功。
|
||||
|
||||
---
|
||||
|
||||
## 8. 為何不違反鐵律
|
||||
|
||||
- 只動 `cli/` + 新增 `cypher-executor/scripts/`（seed 腳本，非執行路徑業務邏輯）。
|
||||
- 不在 `registry/components/` 寫 TS；不在 cypher-executor TS 實作 credential/auth/JWT。
|
||||
- 不新增 Service Binding。
|
||||
- secret 不進自動化（§3 step 8 手動）。
|
||||
- 不重寫部署輪子（用 wrangler，不自寫 CF Script Upload）。
|
||||
@@ -0,0 +1,138 @@
|
||||
# Implementation Plan: arcrun SDK Libraries + Website
|
||||
|
||||
## Overview
|
||||
|
||||
按 Design 的四個 Phase 實作。原則：修改不重建，SDK 是 HTTP API thin wrapper，加密只在 client 做 encrypt（不做 decrypt）。
|
||||
|
||||
**前置依賴**：必須先完成 `credential-primitives-wasm/tasks.md` 的 Phase 0-3（核心合併 + WASM primitives），確認核心穩定後才開始建三個介面。
|
||||
|
||||
---
|
||||
|
||||
## Phase 0（前置）：核心合併 + WASM 改寫
|
||||
|
||||
> 詳見 `.agents/specs/arcrun/credential-primitives-wasm/tasks.md`
|
||||
>
|
||||
> 摘要：
|
||||
> - 合併 u6u-core → arcrun（搬 builtins、刪重複 credentials）
|
||||
> - credential-injector TS → auth_static_key / auth_service_account WASM
|
||||
> - 刪除 component-loader 內建 API recipes TS
|
||||
> - 驗證 20 個 auth recipe 正常運作
|
||||
|
||||
---
|
||||
|
||||
## Phase 1：Python SDK
|
||||
|
||||
- [ ] 1. 建立 `arcrun/python-sdk/` 目錄
|
||||
- [ ] 1.1 `pyproject.toml`：name=arcrun, deps=[httpx>=0.27, cryptography>=42], build-system=hatchling
|
||||
- [ ] 1.2 `arcrun/__init__.py`：`from .client import Arcrun`
|
||||
- [ ] 1.3 `arcrun/crypto.py`：AES-GCM encrypt only（使用 `cryptography` 套件）
|
||||
- [ ] 1.4 `arcrun/creds.py`：CredentialsClient — push（加密 + POST /credentials）、list（GET /credentials）、delete
|
||||
- [ ] 1.5 `arcrun/auth.py`：AuthClient — setup（fetch recipe → match secrets → encrypt → push）、bind（fetch recipe → resolve headers from cache → return AuthenticatedClient）、get_token、list_services
|
||||
- [ ] 1.6 `arcrun/workflows.py`：WorkflowClient — run（POST /webhooks/named/{name}/trigger）、push（POST /webhooks/named）、list（GET /webhooks/named）、delete
|
||||
- [ ] 1.7 `arcrun/client.py`：Arcrun class — 讀 api_key / encryption_key 從 param > env > config.yaml
|
||||
|
||||
- [ ] 2. 修正上次已知的 bug
|
||||
- [ ] 2.1 `_fetch_recipe()` 回應是 `{ success: true, recipe: {...} }`，需讀 `.recipe` 欄位
|
||||
- [ ] 2.2 `inject` 下的 key 是 `header`（singular），不是 `headers`
|
||||
- [ ] 2.3 `required_secrets[].key` 是 prefixed（如 `openai_api_key`），setup() 的 kwargs alias 要能對應
|
||||
- [ ] 2.4 `list_services()` 回應的 recipe 用 `service` 欄位（不是 `service_id`）
|
||||
|
||||
- [ ] 3. 測試（對 cypher.arcrun.dev live API）
|
||||
- [ ] 3.1 `health()` → `{"ok": true}`
|
||||
- [ ] 3.2 `auth.list_services()` → 20 個服務
|
||||
- [ ] 3.3 `auth.setup("openai", api_key="sk-test-dummy")` → 成功
|
||||
- [ ] 3.4 `auth.bind("openai")` → AuthenticatedClient with Authorization header
|
||||
- [ ] 3.5 `auth.get_token("openai")` → "sk-test-dummy"
|
||||
- [ ] 3.6 `creds.push("test_token", "value123")` → 成功
|
||||
- [ ] 3.7 `creds.list()` → 含 "test_token"（注意 KV eventual consistency）
|
||||
- [ ] 3.8 `workflows.list()` → []
|
||||
- [ ] 3.9 cleanup: `creds.delete("test_token")`
|
||||
|
||||
---
|
||||
|
||||
## Phase 2：JS/TS SDK
|
||||
|
||||
- [ ] 4. 建立 `arcrun/js-sdk/` 目錄
|
||||
- [ ] 4.1 `package.json`：name TBD（arcrun vs @arcrun/sdk），deps=devDeps only（tsup, typescript, @types/node）
|
||||
- [ ] 4.2 `tsconfig.json`：ES2020, NodeNext
|
||||
- [ ] 4.3 `src/crypto.ts`：Web Crypto API AES-GCM encrypt only
|
||||
- [ ] 4.4 `src/creds.ts`：CredentialsClient — push/list/delete via fetch
|
||||
- [ ] 4.5 `src/auth.ts`：AuthClient — setup/bind/getToken/listServices
|
||||
- [ ] 4.6 `src/workflows.ts`：WorkflowClient — run/push/list/delete
|
||||
- [ ] 4.7 `src/index.ts`：export class Arcrun + re-exports
|
||||
|
||||
- [ ] 5. 同步修正（與 Python SDK 同樣的 recipe 格式問題）
|
||||
- [ ] 5.1 `_fetchRecipe()` 讀 `body.recipe`
|
||||
- [ ] 5.2 inject key: `header` not `headers`
|
||||
- [ ] 5.3 setup() secret key alias matching
|
||||
- [ ] 5.4 listServices() 用 `service` 欄位
|
||||
|
||||
- [ ] 6. Build + 測試
|
||||
- [ ] 6.1 `tsup` build → dist/index.js + dist/index.cjs + dist/index.d.ts
|
||||
- [ ] 6.2 Node.js 腳本對 live API 測試（同 Python 測試項目）
|
||||
|
||||
---
|
||||
|
||||
## Phase 3：arcrun.dev 網站
|
||||
|
||||
- [ ] 7. 新增 `/components` 頁面
|
||||
- [ ] 7.1 從 `registry/components/*/component.contract.yaml` 讀取 21 個零件資料
|
||||
- [ ] 7.2 卡片顯示：canonical_id, display_name, description, input required/optional, credentials_required, config_example
|
||||
- [ ] 7.3 分類篩選：邏輯類 / API 類 / 控制流類
|
||||
|
||||
- [ ] 8. 更新首頁
|
||||
- [ ] 8.1 Code demo tabs 改為 CLI / Python / JS 三個
|
||||
- [ ] 8.2 CLI tab 展示 `acr init → acr push → acr run`
|
||||
- [ ] 8.3 Python tab 展示 `pip install arcrun → Arcrun() → auth.setup → auth.bind`
|
||||
- [ ] 8.4 JS tab 展示 `npm install arcrun → new Arcrun() → auth.setup → auth.bind`
|
||||
|
||||
- [ ] 9. OAuth 流程補完
|
||||
- [ ] 9.1 確認 cypher-executor 的 `/auth/google/start`、`/auth/github/start`、`/auth/callback` 路由正確
|
||||
- [ ] 9.2 提供 richblack OAuth secrets 設定指令清單
|
||||
- [ ] 9.3 richblack 設定 secrets 後驗證登入流程
|
||||
|
||||
- [ ] 10. 部署
|
||||
- [ ] 10.1 Cloudflare Pages build + deploy
|
||||
- [ ] 10.2 驗證所有頁面可存取
|
||||
|
||||
---
|
||||
|
||||
## Phase 4：README + 發布
|
||||
|
||||
- [ ] 11. 更新 `arcrun/README.md`
|
||||
- [ ] 11.1 三種 Quick Start（CLI / Python / JS）
|
||||
- [ ] 11.2 零件列表（21 個）
|
||||
- [ ] 11.3 Auth Recipe 列表（20 個服務）
|
||||
- [ ] 11.4 連結到 arcrun.dev 和 Swagger UI
|
||||
|
||||
- [ ] 12. 發布
|
||||
- [ ] 12.1 Python SDK：`pip install build && python -m build && twine upload dist/*`
|
||||
- [ ] 12.2 JS SDK：`npm run build && npm publish`
|
||||
- [ ] 12.3 驗證：從零開始 `pip install arcrun` / `npm install arcrun` + hello world
|
||||
|
||||
---
|
||||
|
||||
## Phase 5：acr init --self-hosted installer（2026-06-02 新增）
|
||||
|
||||
> 定稿 design：`self-hosted-init.md`。CLI = installer：建 KV/R2 + 拉預編譯 wasm + wrangler deploy + seed。
|
||||
> 用戶只做：申請 CF 帳號 → 裝 wrangler → 裝 acr → acr init --self-hosted。其餘自動。
|
||||
> 背景：戰法轉 self-hosted 開源（docs/HANDOFF-self-host-harness.md）。
|
||||
|
||||
- [x] 13.1 API recipe 種子 — **位置修正**：種子資料放 `cli/src/lib/api-recipe-seeds.ts`（installer 用，避開 cypher §2.2 hook），seed 腳本 `cypher-executor/scripts/seed-api-recipes.ts`（import 種子，給 prod 補灌）。10 個現役 recipe（kbdb_*/gmail_send/google_sheets_*/telegram_send/line_notify_send）。KBDB Supabase 模式進 seed（finally.click 是 KBDB 端 follow-up，已註於 api-recipe-seeds.ts）
|
||||
- [x] 13.2 `cli/src/lib/cf-api.ts` 新增 `CfAccountClient`：verifyAccess / listKvNamespaces / ensureKvNamespace（冪等）/ ensureR2Bucket（冪等）/ getWorkersSubdomain
|
||||
- [x] 13.3 `cli/src/commands/init.ts` `initSelfHosted()` 改寫：驗 token → 建 7 KV + R2 → 查 subdomain → downloadAndDeploy → 寫 config → seed（部署完成時）→ 印 secret 提示。誠實：部署未自動化時明說，不假綠
|
||||
- [x] 13.4 `cli/src/lib/deploy.ts`：REQUIRED_KV/R2/SECRET 常數 + wranglerAvailable() + **downloadAndDeploy 已補實**（codeload tarball 下載 + 解壓 + discoverWorkerDirs 分 tier + injectWranglerConfig 注入 KV id/subdomain + runWranglerDeploy；部分失敗誠實收集回報，不假綠）
|
||||
- [x] 13.5 `cli/src/commands/update.ts` + index.ts 註冊 `acr update`（self-hosted 重部署，同走 downloadAndDeploy）
|
||||
- [x] 13.6 部署物產製：**改用 commit wasm 進 repo + codeload**（取代 release artifact，richblack 2026-06-02，§6）
|
||||
- `.gitignore` 否定規則放行 `.component-builds/**/component.wasm`（registry 中間產物仍排除）→ 已驗 git check-ignore
|
||||
- rule 05 同步改（記錄推翻「wasm 不 commit」+ trade-off）
|
||||
- commit 22 個 `.component-builds/*/component.wasm` 進 repo
|
||||
- [ ] 13.7 驗收：全新 CF 帳號跑 acr init --self-hosted 全自動；acr push workflow → trigger 2xx + trace（**待 richblack 用第二帳號實測** + push 含 wasm 的 commit 到 GitHub 後 codeload 才拿得到）
|
||||
- [x] 13.8 typecheck：cli `tsc --noEmit` exit 0
|
||||
|
||||
## Notes
|
||||
|
||||
- JS SDK 套件名需 richblack 決定（`arcrun` 已被 CLI 佔用 → 可能用 `@arcrun/sdk`）
|
||||
- OAuth secrets 設定需 richblack 手動操作（GCP Console + GitHub Settings）
|
||||
- `bind()` 跨 session 限制是已知的，封測期間先接受
|
||||
- credential 加密用的 `encryption_key` 目前由 `/register` 回傳，`acr init` 自動存入 config
|
||||
Reference in New Issue
Block a user