feat(arcrun): implement arcrun MVP — open-source AI workflow engine
Phase 1-5 complete per .agents/specs/u6u-core-mvp/: **Phase 1 — Cherry-pick & cleanup** - Create arcrun/ from cypher-executor, credentials, builtins, registry - Remove 9 InkStone Service Bindings (KBDB, REGISTRY, CLINIC_*, AICEO, MINI_ME) - Rewrite component-loader: 3-layer (builtin → WASM_BUCKET R2 → error) - Remove autoPublishMissing.ts, proxy.ts (AICEO), execution-logger.ts (KBDB) - Clean all KV namespace IDs and InkStone internal URLs from config files **Phase 2 — contract.yaml completeness** - Add credentials_required to gmail, google_sheets, telegram, line_notify - Add config_example to all 21 components with annotated field descriptions **Phase 3 — Credential injection** - Add credential-injector.ts: AES-GCM decrypt from CREDENTIALS_KV - Integrate into GraphExecutor before WASM execution - Structured errors with repair instructions when credential missing **Phase 4 — CLI (acr)** - cli/package.json: arcrun package, bin: acr, deps: commander/js-yaml/chalk/ora - 8 commands: init, creds push, push, run, validate, parts, list, logs - Standard mode: writes directly to user's CF KV via CF REST API - acr init: interactive setup with arcrun.dev API Key registration **Phase 5 — Open source release prep** - README.md: 5-minute quickstart, component table, workflow YAML syntax - CONTRIBUTING.md: TinyGo dev env, component scaffolding, submission flow - Security audit: no InkStone internal URLs/IDs in committed files - .gitignore: exclude credentials.yaml, .wrangler, *.wasm https://claude.ai/code/session_01BnCdSLVH8tUed9VrrPavgT
This commit is contained in:
Claude
@@ -0,0 +1,66 @@
|
||||
// 確保 KBDB 中存在 tpl-component Template Block
|
||||
// Requirements: 12.1
|
||||
|
||||
import type { Bindings } from '../types';
|
||||
|
||||
const TEMPLATE_ID = 'tpl-component';
|
||||
|
||||
const SLOT_KEYS = [
|
||||
'canonical_id',
|
||||
'display_name',
|
||||
'category',
|
||||
'version',
|
||||
'wasi_target',
|
||||
'stability',
|
||||
'runtime_compat',
|
||||
'component_type',
|
||||
'max_size_kb',
|
||||
'max_cold_start_ms',
|
||||
'no_network_syscall',
|
||||
'input_schema',
|
||||
'output_schema',
|
||||
'gherkin_tests',
|
||||
'wasm_r2_key',
|
||||
'cypher_binding_url',
|
||||
'service_binding_key',
|
||||
'description',
|
||||
'tags',
|
||||
'success_rate',
|
||||
'avg_duration_ms',
|
||||
'call_count',
|
||||
'status',
|
||||
'deprecated_at',
|
||||
];
|
||||
|
||||
export async function ensureTemplate(env: Bindings): Promise<{ created: boolean; template_id: string }> {
|
||||
const kbdbUrl = env.KBDB_URL || 'https://kbdb.finally.click';
|
||||
const headers = {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${env.KBDB_INTERNAL_TOKEN}`,
|
||||
};
|
||||
|
||||
// 先嘗試取得現有 template
|
||||
const getRes = await fetch(`${kbdbUrl}/templates/${TEMPLATE_ID}`, { headers });
|
||||
if (getRes.ok) {
|
||||
return { created: false, template_id: TEMPLATE_ID };
|
||||
}
|
||||
|
||||
// 不存在則建立
|
||||
const createRes = await fetch(`${kbdbUrl}/templates`, {
|
||||
method: 'POST',
|
||||
headers,
|
||||
body: JSON.stringify({
|
||||
template_id: TEMPLATE_ID,
|
||||
name: 'Component',
|
||||
description: 'u6u 零件合約 Template，每個零件版本對應一個 Block',
|
||||
slot_keys: SLOT_KEYS,
|
||||
}),
|
||||
});
|
||||
|
||||
if (!createRes.ok) {
|
||||
const errText = await createRes.text();
|
||||
throw new Error(`建立 tpl-component 失敗（${createRes.status}）：${errText.slice(0, 200)}`);
|
||||
}
|
||||
|
||||
return { created: true, template_id: TEMPLATE_ID };
|
||||
}
|
||||
@@ -0,0 +1,236 @@
|
||||
// 回傳 Markdown 格式開發指引
|
||||
// Requirements: 11.1, 11.2, 11.3
|
||||
|
||||
export function getGuide(): string {
|
||||
return `# u6u Component Authoring Guide
|
||||
|
||||
## 概覽
|
||||
|
||||
u6u 零件是以 WASI preview1 格式編譯的 WebAssembly 模組，唯一合法的 I/O 模型是 **stdin/stdout JSON**。
|
||||
|
||||
---
|
||||
|
||||
## TinyGo 白名單 {#tinygo-whitelist}
|
||||
|
||||
第一波內部零件使用 TinyGo 開發。**只允許**以下 import：
|
||||
|
||||
\`\`\`go
|
||||
import (
|
||||
"os" // 只用 os.Stdin / os.Stdout / os.Stderr
|
||||
"io" // io.ReadAll(os.Stdin)
|
||||
"encoding/json" // json.Unmarshal / json.Marshal
|
||||
)
|
||||
\`\`\`
|
||||
|
||||
### 允許的操作
|
||||
|
||||
- \`io.ReadAll(os.Stdin)\` 讀取 input JSON
|
||||
- \`json.Unmarshal\` 解析 input
|
||||
- \`json.Marshal\` + \`os.Stdout.Write\` 輸出 output JSON
|
||||
- 基本型別操作（string、int64、float64、bool、[]byte、map[string]interface{}）
|
||||
- 錯誤用 stdout 輸出：\`{"error": "說明"}\`，不要 panic
|
||||
|
||||
---
|
||||
|
||||
## 禁止行為 {#forbidden-behaviors}
|
||||
|
||||
以下行為會導致沙盒驗收失敗：
|
||||
|
||||
- **網路 syscall**：\`net/*\`、\`sock_connect\`、\`sock_accept\` 等
|
||||
- **檔案系統 syscall**：\`os.Open\`、\`os.Create\`、\`path_open\` 等
|
||||
- **goroutine / channel**：WASM 環境不支援
|
||||
- **syscall.*\`**：任何直接 syscall
|
||||
- **第三方 module**：只用標準庫
|
||||
- **打包 runtime**：不得打包 QuickJS、Node.js 等
|
||||
- **超過 2MB**：體積上限 2048KB
|
||||
- **混合前後端邏輯**：一個零件只做一件事
|
||||
|
||||
---
|
||||
|
||||
## I/O 模型 {#io-model}
|
||||
|
||||
唯一合法的 I/O 模型：\`stdin_stdout_json\`
|
||||
|
||||
\`\`\`
|
||||
stdin → JSON.stringify(input) → 零件讀取
|
||||
stdout ← JSON.stringify(output) ← 零件輸出
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
## TinyGo 最小可運行範例 {#tinygo-example}
|
||||
|
||||
\`\`\`go
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"io"
|
||||
"os"
|
||||
)
|
||||
|
||||
type Input struct {
|
||||
JsonString string \`json:"json_string"\`
|
||||
}
|
||||
|
||||
type Output struct {
|
||||
Valid bool \`json:"valid"\`
|
||||
Error string \`json:"error,omitempty"\`
|
||||
}
|
||||
|
||||
func main() {
|
||||
data, err := io.ReadAll(os.Stdin)
|
||||
if err != nil {
|
||||
writeError("讀取 stdin 失敗: " + err.Error())
|
||||
return
|
||||
}
|
||||
|
||||
var input Input
|
||||
if err := json.Unmarshal(data, &input); err != nil {
|
||||
writeError("解析 input JSON 失敗: " + err.Error())
|
||||
return
|
||||
}
|
||||
|
||||
var result interface{}
|
||||
valid := json.Unmarshal([]byte(input.JsonString), &result) == nil
|
||||
|
||||
out := Output{Valid: valid}
|
||||
if !valid {
|
||||
out.Error = "不合法的 JSON 格式"
|
||||
}
|
||||
|
||||
outBytes, _ := json.Marshal(out)
|
||||
os.Stdout.Write(outBytes)
|
||||
}
|
||||
|
||||
func writeError(msg string) {
|
||||
out, _ := json.Marshal(map[string]string{"error": msg})
|
||||
os.Stdout.Write(out)
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
## component.contract.yaml 完整範例 {#contract-example}
|
||||
|
||||
\`\`\`yaml
|
||||
canonical_id: "validate_json"
|
||||
display_name: "JSON 格式驗證器"
|
||||
category: "logic"
|
||||
version: "v1"
|
||||
wasi_target: "preview1"
|
||||
stability: "floating"
|
||||
|
||||
runtime_compat:
|
||||
- "cf-workers"
|
||||
- "workerd"
|
||||
- "wazero"
|
||||
|
||||
constraints:
|
||||
max_size_kb: 2048
|
||||
max_cold_start_ms: 50
|
||||
no_network_syscall: true
|
||||
io_model: "stdin_stdout_json"
|
||||
|
||||
input_schema:
|
||||
type: object
|
||||
required: ["json_string"]
|
||||
properties:
|
||||
json_string:
|
||||
type: string
|
||||
description: "待驗證的 JSON 字串"
|
||||
|
||||
output_schema:
|
||||
type: object
|
||||
properties:
|
||||
valid:
|
||||
type: boolean
|
||||
error:
|
||||
type: string
|
||||
|
||||
gherkin_tests:
|
||||
- scenario: "合法 JSON 通過驗證"
|
||||
given: '{"json_string":"{\\"key\\":\\"value\\"}"}'
|
||||
then_contains: '{"valid":true}'
|
||||
- scenario: "非法 JSON 回傳錯誤"
|
||||
given: '{"json_string":"not-json"}'
|
||||
then_contains: '{"valid":false,"error":'
|
||||
|
||||
tags: ["validation", "json", "utility"]
|
||||
description: "驗證輸入字串是否為合法 JSON 格式"
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
## 本地測試指令 {#local-testing}
|
||||
|
||||
使用 \`wasmtime\` 在本地測試零件：
|
||||
|
||||
\`\`\`bash
|
||||
# 編譯（TinyGo）
|
||||
tinygo build -o validate_json.wasm -target wasi ./main.go
|
||||
|
||||
# 測試 happy path
|
||||
echo '{"json_string":"{}"}' | wasmtime validate_json.wasm
|
||||
# 預期輸出：{"valid":true}
|
||||
|
||||
# 測試 error path
|
||||
echo '{"json_string":"not-json"}' | wasmtime validate_json.wasm
|
||||
# 預期輸出：{"valid":false,"error":"..."}
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
## syscall 限制 {#syscall-constraints}
|
||||
|
||||
沙盒驗收會掃描 .wasm binary 中的 import，以下 syscall 一律拒絕：
|
||||
|
||||
- \`sock_connect\`、\`sock_accept\`、\`sock_recv\`、\`sock_send\`、\`sock_shutdown\`
|
||||
- \`fd_open\`、\`path_open\`、\`path_create_directory\`、\`path_remove_directory\`
|
||||
- \`path_rename\`、\`path_unlink_file\`、\`path_filestat_get\`
|
||||
|
||||
---
|
||||
|
||||
## 常見錯誤與解法 {#common-errors}
|
||||
|
||||
| 錯誤 | 原因 | 解法 |
|
||||
|---|---|---|
|
||||
| \`size_check 失敗\` | .wasm 超過 2048KB | 移除不必要的依賴，使用 TinyGo 而非 Go |
|
||||
| \`syscall_scan 失敗\` | 含有網路/檔案 syscall | 移除 \`net/*\`、\`os.Open\` 等 import |
|
||||
| \`gherkin_tests 失敗\` | 輸出不符合預期 | 確認 stdout 輸出為合法 JSON |
|
||||
| \`contract 驗證失敗\` | 缺少必填欄位 | 參考上方 contract 範例補齊欄位 |
|
||||
|
||||
---
|
||||
|
||||
## contract.yaml JSON Schema {#contract-schema}
|
||||
|
||||
\`\`\`json
|
||||
{
|
||||
"type": "object",
|
||||
"required": ["canonical_id", "display_name", "category", "version", "wasi_target", "stability", "runtime_compat", "constraints", "input_schema", "output_schema", "gherkin_tests"],
|
||||
"properties": {
|
||||
"canonical_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" },
|
||||
"display_name": { "type": "string" },
|
||||
"category": { "type": "string", "enum": ["logic", "api", "ui", "style", "anim"] },
|
||||
"version": { "type": "string", "pattern": "^v\\\\d+$" },
|
||||
"wasi_target": { "type": "string", "enum": ["preview1"] },
|
||||
"stability": { "type": "string", "enum": ["floating", "stable", "pinned"] },
|
||||
"runtime_compat": { "type": "array", "items": { "type": "string", "enum": ["cf-workers", "workerd", "wazero"] }, "minItems": 1 },
|
||||
"constraints": {
|
||||
"type": "object",
|
||||
"required": ["max_size_kb", "max_cold_start_ms", "no_network_syscall", "io_model"],
|
||||
"properties": {
|
||||
"max_size_kb": { "type": "number", "maximum": 2048 },
|
||||
"max_cold_start_ms": { "type": "number", "maximum": 50 },
|
||||
"no_network_syscall": { "type": "boolean" },
|
||||
"io_model": { "type": "string", "enum": ["stdin_stdout_json"] }
|
||||
}
|
||||
},
|
||||
"input_schema": { "type": "object" },
|
||||
"output_schema": { "type": "object" },
|
||||
"gherkin_tests": { "type": "array", "minItems": 2 }
|
||||
}
|
||||
}
|
||||
\`\`\`
|
||||
`;
|
||||
}
|
||||
@@ -0,0 +1,162 @@
|
||||
// queryComponents — 查詢零件合約與語意搜尋
|
||||
// Requirements: 12.2, 12.3
|
||||
|
||||
import type { Bindings } from '../types';
|
||||
|
||||
export interface ComponentVersion {
|
||||
canonical_id: string;
|
||||
display_name: string;
|
||||
version: string;
|
||||
category: string;
|
||||
stability: string;
|
||||
status: string;
|
||||
description: string;
|
||||
tags: string[];
|
||||
success_rate: number;
|
||||
avg_duration_ms: number;
|
||||
call_count: number;
|
||||
wasm_r2_key?: string;
|
||||
cypher_binding_url?: string;
|
||||
score: number;
|
||||
}
|
||||
|
||||
/** 從 KBDB 取得零件的最優版本合約 */
|
||||
export async function getComponent(
|
||||
canonicalId: string,
|
||||
env: Bindings,
|
||||
): Promise<ComponentVersion | null> {
|
||||
const kbdbUrl = env.KBDB_URL || 'https://kbdb.finally.click';
|
||||
const headers = {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${env.KBDB_INTERNAL_TOKEN}`,
|
||||
};
|
||||
|
||||
// 搜尋所有版本（block_id 前綴 comp-{id}-）
|
||||
const res = await fetch(
|
||||
`${kbdbUrl}/records/search?template_id=tpl-component&canonical_id=${encodeURIComponent(canonicalId)}&limit=20`,
|
||||
{ headers },
|
||||
);
|
||||
|
||||
if (!res.ok) return null;
|
||||
|
||||
const data = await res.json() as { records?: Array<{ record_id: string; values: Record<string, string> }> };
|
||||
const records = (data.records ?? []).filter(r =>
|
||||
r.values.canonical_id === canonicalId && r.values.status !== 'tombstone'
|
||||
);
|
||||
|
||||
if (records.length === 0) return null;
|
||||
|
||||
// 選取評分最高的版本（floating 策略）
|
||||
const scored = records.map(r => ({
|
||||
...r.values,
|
||||
score: computeScore(r.values),
|
||||
}));
|
||||
scored.sort((a, b) => b.score - a.score);
|
||||
const best = scored[0];
|
||||
|
||||
return toComponentVersion(best);
|
||||
}
|
||||
|
||||
/** 取得零件所有版本清單（含評分排序） */
|
||||
export async function getComponentVersions(
|
||||
canonicalId: string,
|
||||
env: Bindings,
|
||||
): Promise<ComponentVersion[]> {
|
||||
const kbdbUrl = env.KBDB_URL || 'https://kbdb.finally.click';
|
||||
const headers = {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${env.KBDB_INTERNAL_TOKEN}`,
|
||||
};
|
||||
|
||||
const res = await fetch(
|
||||
`${kbdbUrl}/records/search?template_id=tpl-component&canonical_id=${encodeURIComponent(canonicalId)}&limit=20`,
|
||||
{ headers },
|
||||
);
|
||||
|
||||
if (!res.ok) return [];
|
||||
|
||||
const data = await res.json() as { records?: Array<{ record_id: string; values: Record<string, string> }> };
|
||||
const records = (data.records ?? []).filter(r =>
|
||||
r.values.canonical_id === canonicalId && r.values.status !== 'tombstone'
|
||||
);
|
||||
|
||||
return records
|
||||
.map(r => ({ ...r.values, score: computeScore(r.values) }))
|
||||
.sort((a, b) => b.score - a.score)
|
||||
.slice(0, 10)
|
||||
.map(toComponentVersion);
|
||||
}
|
||||
|
||||
/** 語意搜尋零件（透過 KBDB Vectorize） */
|
||||
export async function searchComponents(
|
||||
query: string,
|
||||
env: Bindings,
|
||||
): Promise<ComponentVersion[]> {
|
||||
const kbdbUrl = env.KBDB_URL || 'https://kbdb.finally.click';
|
||||
const headers = {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${env.KBDB_INTERNAL_TOKEN}`,
|
||||
};
|
||||
|
||||
// 透過 KBDB 語意搜尋（Vectorize）
|
||||
const res = await fetch(`${kbdbUrl}/search`, {
|
||||
method: 'POST',
|
||||
headers,
|
||||
body: JSON.stringify({
|
||||
query,
|
||||
type: 'suggest',
|
||||
topK: 10,
|
||||
filter: { template_id: 'tpl-component' },
|
||||
}),
|
||||
});
|
||||
|
||||
if (!res.ok) return [];
|
||||
|
||||
const data = await res.json() as { matches?: Array<{ block_id: string; score: number; metadata?: Record<string, string> }> };
|
||||
const matches = data.matches ?? [];
|
||||
|
||||
// 取得每個匹配的完整合約
|
||||
const results: ComponentVersion[] = [];
|
||||
for (const match of matches.slice(0, 10)) {
|
||||
const blockRes = await fetch(`${kbdbUrl}/records/${match.block_id}`, { headers });
|
||||
if (!blockRes.ok) continue;
|
||||
const block = await blockRes.json() as { values: Record<string, string> };
|
||||
if (block.values.status === 'tombstone') continue;
|
||||
results.push(toComponentVersion({ ...block.values, score: match.score }));
|
||||
}
|
||||
|
||||
return results;
|
||||
}
|
||||
|
||||
// ── 內部工具函數 ──────────────────────────────────────────────────────────────
|
||||
|
||||
/** 計算零件評分：成功率 × 速度評分 × log(被調用次數 + 1) */
|
||||
function computeScore(v: Record<string, string>): number {
|
||||
const successRate = parseFloat(v.success_rate ?? '1');
|
||||
const avgDuration = parseFloat(v.avg_duration_ms ?? '10');
|
||||
const callCount = parseInt(v.call_count ?? '0', 10);
|
||||
// 速度評分：越快越高，50ms 為基準
|
||||
const speedScore = Math.max(0, 1 - avgDuration / 1000);
|
||||
return successRate * speedScore * Math.log(callCount + 2);
|
||||
}
|
||||
|
||||
function toComponentVersion(v: Record<string, string | number>): ComponentVersion {
|
||||
return {
|
||||
canonical_id: String(v.canonical_id ?? ''),
|
||||
display_name: String(v.display_name ?? ''),
|
||||
version: String(v.version ?? 'v1'),
|
||||
category: String(v.category ?? 'logic'),
|
||||
stability: String(v.stability ?? 'floating'),
|
||||
status: String(v.status ?? 'active'),
|
||||
description: String(v.description ?? ''),
|
||||
tags: (() => {
|
||||
try { return JSON.parse(String(v.tags ?? '[]')); } catch { return []; }
|
||||
})(),
|
||||
success_rate: parseFloat(String(v.success_rate ?? '1')),
|
||||
avg_duration_ms: parseFloat(String(v.avg_duration_ms ?? '0')),
|
||||
call_count: parseInt(String(v.call_count ?? '0'), 10),
|
||||
wasm_r2_key: v.wasm_r2_key ? String(v.wasm_r2_key) : undefined,
|
||||
cypher_binding_url: v.cypher_binding_url ? String(v.cypher_binding_url) : undefined,
|
||||
score: typeof v.score === 'number' ? v.score : parseFloat(String(v.score ?? '0')),
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,96 @@
|
||||
// 沙盒驗收流程：五個步驟依序執行
|
||||
// Requirements: 2.1, 2.2, 2.3
|
||||
|
||||
import { FORBIDDEN_SYSCALLS } from '../types';
|
||||
import type { ComponentContract, SandboxResult, SandboxStep } from '../types';
|
||||
|
||||
// ── 步驟 (a)：體積檢查 ────────────────────────────────────────────────────────
|
||||
|
||||
function checkSize(wasmBytes: Uint8Array, contract: ComponentContract): string | null {
|
||||
const maxSizeKb = contract.constraints.max_size_kb;
|
||||
const actualKb = wasmBytes.byteLength / 1024;
|
||||
if (actualKb > maxSizeKb) {
|
||||
return `體積 ${actualKb.toFixed(1)}KB 超過上限 ${maxSizeKb}KB`;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
// ── 步驟 (b)：冷啟動時間（Phase 0 mock 0ms）────────────────────────────────────
|
||||
|
||||
function checkColdStart(_wasmBytes: Uint8Array, _contract: ComponentContract): string | null {
|
||||
// Phase 0：mock 通過，記錄 0ms
|
||||
// Phase 2 再實作真實測量
|
||||
return null;
|
||||
}
|
||||
|
||||
// ── 步驟 (c)：syscall 掃描 ────────────────────────────────────────────────────
|
||||
|
||||
function scanSyscalls(wasmBytes: Uint8Array): string | null {
|
||||
// 將 .wasm binary 轉為文字，搜尋禁止的 import 字串
|
||||
// WASM binary 中 import section 的函數名稱以 UTF-8 字串形式存在
|
||||
const text = new TextDecoder('utf-8', { fatal: false }).decode(wasmBytes);
|
||||
|
||||
for (const syscall of FORBIDDEN_SYSCALLS) {
|
||||
if (text.includes(syscall)) {
|
||||
return `發現禁止的 syscall：${syscall}`;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
// ── 步驟 (d)：Gherkin 測試（Phase 0 mock 通過）────────────────────────────────
|
||||
|
||||
function runGherkinTests(_wasmBytes: Uint8Array, _contract: ComponentContract): string | null {
|
||||
// Phase 0：mock 通過
|
||||
// Phase 1 再實作真實 Gherkin 執行
|
||||
return null;
|
||||
}
|
||||
|
||||
// ── 步驟 (e)：runtime 相容測試（Phase 0 mock 通過）────────────────────────────
|
||||
|
||||
function checkRuntimeCompat(_wasmBytes: Uint8Array, _contract: ComponentContract): string | null {
|
||||
// Phase 0：mock 通過
|
||||
// Phase 2 再實作真實多 runtime 測試
|
||||
return null;
|
||||
}
|
||||
|
||||
// ── 主流程 ────────────────────────────────────────────────────────────────────
|
||||
|
||||
interface StepDef {
|
||||
name: SandboxStep;
|
||||
run: (wasmBytes: Uint8Array, contract: ComponentContract) => string | null;
|
||||
guideAnchor: string;
|
||||
}
|
||||
|
||||
const STEPS: StepDef[] = [
|
||||
{ name: 'size_check', run: checkSize, guideAnchor: '#common-errors' },
|
||||
{ name: 'cold_start', run: checkColdStart, guideAnchor: '#common-errors' },
|
||||
{ name: 'syscall_scan', run: scanSyscalls, guideAnchor: '#syscall-constraints' },
|
||||
{ name: 'gherkin_tests', run: runGherkinTests, guideAnchor: '#local-testing' },
|
||||
{ name: 'runtime_compat', run: checkRuntimeCompat, guideAnchor: '#contract-example' },
|
||||
];
|
||||
|
||||
export function runSandboxAcceptance(
|
||||
wasmBytes: Uint8Array,
|
||||
contract: ComponentContract,
|
||||
): SandboxResult {
|
||||
for (const step of STEPS) {
|
||||
const error = step.run(wasmBytes, contract);
|
||||
if (error !== null) {
|
||||
return {
|
||||
success: false,
|
||||
failed_step: step.name,
|
||||
reason: error,
|
||||
guide_anchor: step.guideAnchor,
|
||||
component_id: contract.canonical_id,
|
||||
version: contract.version,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
success: true,
|
||||
component_id: contract.canonical_id,
|
||||
version: contract.version,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,90 @@
|
||||
// 零件提交：沙盒驗收 → 寫入 KBDB Block → 上傳 R2
|
||||
// Requirements: 2.1, 2.2, 2.3
|
||||
|
||||
import { runSandboxAcceptance } from './sandboxAcceptance';
|
||||
import type { ComponentContract, SandboxResult, Bindings } from '../types';
|
||||
|
||||
export async function submitComponent(
|
||||
wasmBytes: Uint8Array,
|
||||
contract: ComponentContract,
|
||||
env: Bindings,
|
||||
): Promise<SandboxResult & { wasm_r2_key?: string }> {
|
||||
// 1. 沙盒驗收
|
||||
const sandboxResult = runSandboxAcceptance(wasmBytes, contract);
|
||||
if (!sandboxResult.success) {
|
||||
return sandboxResult;
|
||||
}
|
||||
|
||||
const blockId = `comp-${contract.canonical_id}-${contract.version}`;
|
||||
const r2Key = `components/${contract.canonical_id}/${contract.version}.wasm`;
|
||||
|
||||
// 2. 上傳 .wasm 至 R2
|
||||
await env.WASM_BUCKET.put(r2Key, wasmBytes, {
|
||||
httpMetadata: { contentType: 'application/wasm' },
|
||||
});
|
||||
|
||||
// 3. 寫入 KBDB Block（冪等：先嘗試取得，存在則更新，不存在則建立）
|
||||
const kbdbUrl = env.KBDB_URL || 'https://kbdb.finally.click';
|
||||
const headers = {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${env.KBDB_INTERNAL_TOKEN}`,
|
||||
};
|
||||
|
||||
const slots: Record<string, string> = {
|
||||
canonical_id: contract.canonical_id,
|
||||
display_name: contract.display_name,
|
||||
category: contract.category,
|
||||
version: contract.version,
|
||||
wasi_target: contract.wasi_target,
|
||||
stability: contract.stability,
|
||||
runtime_compat: JSON.stringify(contract.runtime_compat),
|
||||
component_type: contract.component_type ?? 'wasm',
|
||||
max_size_kb: String(contract.constraints.max_size_kb),
|
||||
max_cold_start_ms: String(contract.constraints.max_cold_start_ms),
|
||||
no_network_syscall: String(contract.constraints.no_network_syscall),
|
||||
input_schema: JSON.stringify(contract.input_schema),
|
||||
output_schema: JSON.stringify(contract.output_schema),
|
||||
gherkin_tests: JSON.stringify(contract.gherkin_tests),
|
||||
wasm_r2_key: r2Key,
|
||||
description: contract.description ?? '',
|
||||
tags: JSON.stringify(contract.tags ?? []),
|
||||
success_rate: '1',
|
||||
avg_duration_ms: '0',
|
||||
call_count: '0',
|
||||
status: 'active',
|
||||
deprecated_at: '',
|
||||
};
|
||||
|
||||
if (contract.cypher_binding_url) slots.cypher_binding_url = contract.cypher_binding_url;
|
||||
if (contract.service_binding_key) slots.service_binding_key = contract.service_binding_key;
|
||||
|
||||
// 冪等：先查是否存在
|
||||
const existRes = await fetch(`${kbdbUrl}/records/${blockId}`, { headers });
|
||||
|
||||
if (existRes.ok) {
|
||||
// 已存在：更新 slots
|
||||
await fetch(`${kbdbUrl}/records/${blockId}`, {
|
||||
method: 'PUT',
|
||||
headers,
|
||||
body: JSON.stringify({ values: slots }),
|
||||
});
|
||||
} else {
|
||||
// 不存在：建立新 Block
|
||||
await fetch(`${kbdbUrl}/records`, {
|
||||
method: 'POST',
|
||||
headers,
|
||||
body: JSON.stringify({
|
||||
record_id: blockId,
|
||||
template_id: 'tpl-component',
|
||||
values: slots,
|
||||
}),
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
success: true,
|
||||
component_id: contract.canonical_id,
|
||||
version: contract.version,
|
||||
wasm_r2_key: r2Key,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
// 驗證 component.contract.yaml 所有必填欄位
|
||||
// Requirements: 1.1, 1.2, 11.5
|
||||
|
||||
import { ComponentContractSchema } from '../types';
|
||||
import type { ComponentContract } from '../types';
|
||||
|
||||
export interface ValidateContractResult {
|
||||
valid: boolean;
|
||||
missing_fields: string[];
|
||||
errors: string[];
|
||||
contract?: ComponentContract;
|
||||
}
|
||||
|
||||
export function validateContract(raw: unknown): ValidateContractResult {
|
||||
const result = ComponentContractSchema.safeParse(raw);
|
||||
|
||||
if (result.success) {
|
||||
return { valid: true, missing_fields: [], errors: [], contract: result.data };
|
||||
}
|
||||
|
||||
const missing_fields: string[] = [];
|
||||
const errors: string[] = [];
|
||||
|
||||
for (const issue of result.error.issues) {
|
||||
const path = issue.path.join('.');
|
||||
if (issue.code === 'invalid_type' && issue.received === 'undefined') {
|
||||
missing_fields.push(path || issue.message);
|
||||
} else {
|
||||
errors.push(path ? `${path}: ${issue.message}` : issue.message);
|
||||
}
|
||||
}
|
||||
|
||||
return { valid: false, missing_fields, errors };
|
||||
}
|
||||
@@ -0,0 +1,28 @@
|
||||
// Component Registry Worker — 零件合約管理 HTTP endpoints
|
||||
// index.ts 只做路由宣告，業務邏輯在 actions/（INV Layer 1）
|
||||
|
||||
import { Hono } from 'hono';
|
||||
import { cors } from 'hono/cors';
|
||||
import type { Bindings } from './types';
|
||||
import guideRoute from './routes/guide';
|
||||
import validateContractRoute from './routes/validateContract';
|
||||
import componentsRoute from './routes/components';
|
||||
import queryRoute from './routes/query';
|
||||
import initRoute from './routes/init';
|
||||
|
||||
const app = new Hono<{ Bindings: Bindings }>();
|
||||
app.use('*', cors());
|
||||
|
||||
// Health check
|
||||
app.get('/', c => c.json({ service: 'component-registry', version: '1.0.0', status: 'ok' }));
|
||||
|
||||
// === Component Registry 端點 ===
|
||||
app.route('/components/guide', guideRoute);
|
||||
app.route('/components/validate-contract', validateContractRoute);
|
||||
app.route('/components', queryRoute); // GET /components/search, /:id, /:id/versions
|
||||
app.route('/components', componentsRoute); // POST /components
|
||||
|
||||
// === 初始化端點（建立 tpl-component template）===
|
||||
app.route('/init', initRoute);
|
||||
|
||||
export default app;
|
||||
@@ -0,0 +1,86 @@
|
||||
// POST /components — 零件提交端點（沙盒驗收流程）
|
||||
// Requirements: 2.1, 2.2, 2.3
|
||||
|
||||
import { Hono } from 'hono';
|
||||
import type { Bindings } from '../types';
|
||||
import { validateContract } from '../actions/validateContract';
|
||||
import { submitComponent } from '../actions/submitComponent';
|
||||
|
||||
const app = new Hono<{ Bindings: Bindings }>();
|
||||
|
||||
app.post('/', async c => {
|
||||
// 接受 multipart/form-data：contract（JSON 字串）+ wasm（binary）
|
||||
let contract: unknown;
|
||||
let wasmBytes: Uint8Array;
|
||||
|
||||
const contentType = c.req.header('content-type') ?? '';
|
||||
|
||||
if (contentType.includes('multipart/form-data')) {
|
||||
const formData = await c.req.formData();
|
||||
const contractStr = formData.get('contract');
|
||||
const wasmFile = formData.get('wasm');
|
||||
|
||||
if (!contractStr || typeof contractStr !== 'string') {
|
||||
return c.json({ success: false, error: '缺少 contract 欄位' }, 400);
|
||||
}
|
||||
if (!wasmFile || !(wasmFile instanceof File)) {
|
||||
return c.json({ success: false, error: '缺少 wasm 欄位' }, 400);
|
||||
}
|
||||
|
||||
try {
|
||||
contract = JSON.parse(contractStr);
|
||||
} catch {
|
||||
return c.json({ success: false, error: 'contract 必須為合法 JSON' }, 400);
|
||||
}
|
||||
|
||||
wasmBytes = new Uint8Array(await wasmFile.arrayBuffer());
|
||||
} else {
|
||||
// 也支援純 JSON（用於測試，wasm 以 base64 傳入）
|
||||
let body: Record<string, unknown>;
|
||||
try {
|
||||
body = await c.req.json();
|
||||
} catch {
|
||||
return c.json({ success: false, error: 'request body 必須為 multipart/form-data 或 JSON' }, 400);
|
||||
}
|
||||
|
||||
contract = body.contract;
|
||||
const wasmBase64 = body.wasm_base64;
|
||||
|
||||
if (!contract) {
|
||||
return c.json({ success: false, error: '缺少 contract 欄位' }, 400);
|
||||
}
|
||||
if (!wasmBase64 || typeof wasmBase64 !== 'string') {
|
||||
return c.json({ success: false, error: '缺少 wasm_base64 欄位' }, 400);
|
||||
}
|
||||
|
||||
// base64 decode
|
||||
const binaryStr = atob(wasmBase64);
|
||||
wasmBytes = new Uint8Array(binaryStr.length);
|
||||
for (let i = 0; i < binaryStr.length; i++) {
|
||||
wasmBytes[i] = binaryStr.charCodeAt(i);
|
||||
}
|
||||
}
|
||||
|
||||
// 驗證 contract 格式
|
||||
const validation = validateContract(contract);
|
||||
if (!validation.valid) {
|
||||
return c.json({
|
||||
success: false,
|
||||
failed_step: 'contract_validation',
|
||||
reason: `合約格式驗證失敗：${validation.errors.join(', ')}`,
|
||||
missing_fields: validation.missing_fields,
|
||||
guide_anchor: '#contract-example',
|
||||
}, 422);
|
||||
}
|
||||
|
||||
// 執行沙盒驗收 + 寫入 KBDB + 上傳 R2
|
||||
const result = await submitComponent(wasmBytes, validation.contract!, c.env);
|
||||
|
||||
if (!result.success) {
|
||||
return c.json(result, 422);
|
||||
}
|
||||
|
||||
return c.json(result, 201);
|
||||
});
|
||||
|
||||
export default app;
|
||||
@@ -0,0 +1,15 @@
|
||||
// GET /components/guide
|
||||
// Requirements: 11.1, 11.2, 11.3
|
||||
|
||||
import { Hono } from 'hono';
|
||||
import type { Bindings } from '../types';
|
||||
import { getGuide } from '../actions/getGuide';
|
||||
|
||||
const app = new Hono<{ Bindings: Bindings }>();
|
||||
|
||||
app.get('/', c => {
|
||||
const markdown = getGuide();
|
||||
return c.text(markdown, 200, { 'Content-Type': 'text/markdown; charset=utf-8' });
|
||||
});
|
||||
|
||||
export default app;
|
||||
@@ -0,0 +1,20 @@
|
||||
// POST /init — 確保 tpl-component template 存在（冪等）
|
||||
// Requirements: 12.1
|
||||
|
||||
import { Hono } from 'hono';
|
||||
import type { Bindings } from '../types';
|
||||
import { ensureTemplate } from '../actions/ensureTemplate';
|
||||
|
||||
const app = new Hono<{ Bindings: Bindings }>();
|
||||
|
||||
app.post('/', async c => {
|
||||
try {
|
||||
const result = await ensureTemplate(c.env);
|
||||
return c.json({ success: true, ...result });
|
||||
} catch (err) {
|
||||
const message = err instanceof Error ? err.message : String(err);
|
||||
return c.json({ success: false, error: message }, 500);
|
||||
}
|
||||
});
|
||||
|
||||
export default app;
|
||||
@@ -0,0 +1,43 @@
|
||||
// GET /components/:id — 取得零件最優版本合約
|
||||
// GET /components/:id/versions — 取得所有版本清單（含評分）
|
||||
// GET /components/search?q=... — 語意搜尋零件
|
||||
// Requirements: 12.2, 12.3
|
||||
|
||||
import { Hono } from 'hono';
|
||||
import type { Bindings } from '../types';
|
||||
import { getComponent, getComponentVersions, searchComponents } from '../actions/queryComponents';
|
||||
|
||||
const app = new Hono<{ Bindings: Bindings }>();
|
||||
|
||||
// 語意搜尋（必須在 /:id 之前，避免 "search" 被當作 id）
|
||||
app.get('/search', async c => {
|
||||
const q = c.req.query('q');
|
||||
if (!q || q.trim() === '') {
|
||||
return c.json({ success: false, error: 'q 參數必填' }, 400);
|
||||
}
|
||||
|
||||
const results = await searchComponents(q.trim(), c.env);
|
||||
return c.json({ success: true, data: { results, count: results.length } });
|
||||
});
|
||||
|
||||
// 取得所有版本
|
||||
app.get('/:id/versions', async c => {
|
||||
const id = c.req.param('id');
|
||||
const versions = await getComponentVersions(id, c.env);
|
||||
if (versions.length === 0) {
|
||||
return c.json({ success: false, error: `零件 ${id} 不存在` }, 404);
|
||||
}
|
||||
return c.json({ success: true, data: { versions, count: versions.length } });
|
||||
});
|
||||
|
||||
// 取得最優版本
|
||||
app.get('/:id', async c => {
|
||||
const id = c.req.param('id');
|
||||
const component = await getComponent(id, c.env);
|
||||
if (!component) {
|
||||
return c.json({ success: false, error: `零件 ${id} 不存在` }, 404);
|
||||
}
|
||||
return c.json({ success: true, data: component });
|
||||
});
|
||||
|
||||
export default app;
|
||||
@@ -0,0 +1,31 @@
|
||||
// POST /components/validate-contract
|
||||
// Requirements: 1.1, 1.2, 11.5
|
||||
|
||||
import { Hono } from 'hono';
|
||||
import type { Bindings } from '../types';
|
||||
import { validateContract } from '../actions/validateContract';
|
||||
|
||||
const app = new Hono<{ Bindings: Bindings }>();
|
||||
|
||||
app.post('/', async c => {
|
||||
let body: unknown;
|
||||
try {
|
||||
body = await c.req.json();
|
||||
} catch {
|
||||
return c.json({ valid: false, missing_fields: [], errors: ['request body 必須為合法 JSON'] }, 400);
|
||||
}
|
||||
|
||||
const result = validateContract(body);
|
||||
|
||||
if (result.valid) {
|
||||
return c.json({ valid: true, missing_fields: [], errors: [] }, 200);
|
||||
}
|
||||
|
||||
return c.json({
|
||||
valid: false,
|
||||
missing_fields: result.missing_fields,
|
||||
errors: result.errors,
|
||||
}, 422);
|
||||
});
|
||||
|
||||
export default app;
|
||||
@@ -0,0 +1,99 @@
|
||||
// Component Registry Worker 型別定義
|
||||
|
||||
import { z } from 'zod';
|
||||
|
||||
// ── Cloudflare Bindings ──────────────────────────────────────────────────────
|
||||
|
||||
export type Bindings = {
|
||||
WASM_BUCKET: R2Bucket;
|
||||
AI: Ai;
|
||||
KBDB_URL: string;
|
||||
KBDB_INTERNAL_TOKEN: string;
|
||||
ENVIRONMENT: string;
|
||||
};
|
||||
|
||||
// ── Component Contract Schema（Zod）─────────────────────────────────────────
|
||||
|
||||
export const ConstraintsSchema = z.object({
|
||||
max_size_kb: z.number().positive().max(2048),
|
||||
max_cold_start_ms: z.number().positive().max(50),
|
||||
no_network_syscall: z.boolean(),
|
||||
io_model: z.literal('stdin_stdout_json'),
|
||||
});
|
||||
|
||||
export const GherkinTestSchema = z.object({
|
||||
scenario: z.string().min(1),
|
||||
given: z.string().min(1),
|
||||
then_contains: z.string().min(1),
|
||||
});
|
||||
|
||||
export const ComponentContractSchema = z.object({
|
||||
canonical_id: z.string().min(1).regex(/^[a-z][a-z0-9_]*$/, 'canonical_id 必須為小寫底線格式'),
|
||||
display_name: z.string().min(1),
|
||||
category: z.enum(['logic', 'api', 'ui', 'style', 'anim']),
|
||||
version: z.string().min(1).regex(/^v\d+$/, 'version 格式必須為 vN'),
|
||||
wasi_target: z.literal('preview1'),
|
||||
stability: z.enum(['floating', 'stable', 'pinned']),
|
||||
runtime_compat: z.array(z.enum(['cf-workers', 'workerd', 'wazero'])).min(1),
|
||||
constraints: ConstraintsSchema,
|
||||
input_schema: z.record(z.unknown()),
|
||||
output_schema: z.record(z.unknown()),
|
||||
gherkin_tests: z.array(GherkinTestSchema).min(2, '至少需要一個 happy path 和一個 error path'),
|
||||
// 選填欄位
|
||||
component_type: z.enum(['wasm', 'service_binding']).optional(),
|
||||
max_size_kb: z.number().optional(),
|
||||
max_cold_start_ms: z.number().optional(),
|
||||
no_network_syscall: z.boolean().optional(),
|
||||
service_binding_key: z.string().optional(),
|
||||
description: z.string().optional(),
|
||||
tags: z.array(z.string()).optional(),
|
||||
});
|
||||
|
||||
export type ComponentContract = z.infer<typeof ComponentContractSchema>;
|
||||
|
||||
// ── 沙盒驗收步驟 ─────────────────────────────────────────────────────────────
|
||||
|
||||
export type SandboxStep = 'size_check' | 'cold_start' | 'syscall_scan' | 'gherkin_tests' | 'runtime_compat';
|
||||
|
||||
export interface SandboxResult {
|
||||
success: boolean;
|
||||
failed_step?: SandboxStep;
|
||||
reason?: string;
|
||||
guide_anchor?: string;
|
||||
component_id: string;
|
||||
version: string;
|
||||
}
|
||||
|
||||
// ── KBDB Block 格式 ──────────────────────────────────────────────────────────
|
||||
|
||||
export interface KbdbBlock {
|
||||
block_id: string;
|
||||
template_id: string;
|
||||
user_id?: string;
|
||||
page_name?: string;
|
||||
}
|
||||
|
||||
export interface KbdbSlots {
|
||||
[key: string]: string;
|
||||
}
|
||||
|
||||
// ── 禁止的 WASM syscall（網路 + 檔案系統）────────────────────────────────────
|
||||
|
||||
export const FORBIDDEN_SYSCALLS = [
|
||||
'sock_connect',
|
||||
'sock_accept',
|
||||
'sock_recv',
|
||||
'sock_send',
|
||||
'sock_shutdown',
|
||||
'fd_open',
|
||||
'path_open',
|
||||
'path_create_directory',
|
||||
'path_remove_directory',
|
||||
'path_rename',
|
||||
'path_unlink_file',
|
||||
'path_filestat_get',
|
||||
'path_filestat_set_times',
|
||||
'path_link',
|
||||
'path_readlink',
|
||||
'path_symlink',
|
||||
] as const;
|
||||
Reference in New Issue
Block a user