Arcrun/.agents/specs/arcrun/sdk-and-website/requirements.md

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() ✅