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