feat(cli): add serve command — Hono HTTP API server #119

2026-05-08T03:07:43Z

xingyue commented

2026-05-08 03:07:43 +00:00

What

Adds uncaged-workflow serve command that starts a local Hono HTTP API server.

Why

RFC #118 Phase 1 — Web UI needs a local API to read workflow data.

Changes

packages/cli-workflow/src/commands/serve/ — new command module (app, routes, serve, types, index)
cli-dispatch.ts — wire serve into command table
cli-usage.ts — add Server section to help output
package.json — add hono dependency
serve.test.ts — 8 tests covering all routes

Ref

Closes phase 1 of #118. 261 tests pass.

## What Adds uncaged-workflow serve command that starts a local Hono HTTP API server. ## Why RFC #118 Phase 1 — Web UI needs a local API to read workflow data. ## Changes - packages/cli-workflow/src/commands/serve/ — new command module (app, routes, serve, types, index) - cli-dispatch.ts — wire serve into command table - cli-usage.ts — add Server section to help output - package.json — add hono dependency - serve.test.ts — 8 tests covering all routes ## Ref Closes phase 1 of #118. 261 tests pass.

xingyue added 1 commit 2026-05-08 03:07:43 +00:00

feat(cli): add serve command — Hono HTTP API server 3ed38c65ec

Adds `uncaged-workflow serve` command that exposes workflow data
via a local HTTP API for the upcoming Web UI (RFC #118 Phase 1).

Routes:
- GET /healthz — health check
- GET /api/workflows — list registered workflows
- GET /api/workflows/:name — show workflow details
- GET /api/workflows/:name/history — version history
- GET /api/threads — list threads (optional ?workflow= filter)
- GET /api/threads/running — list running threads
- GET /api/threads/:id — show thread records (parsed JSONL)
- GET /api/cas — list CAS hashes
- GET /api/cas/:hash — get CAS content
- POST /api/cas — store content, returns hash
- DELETE /api/cas/:hash — remove CAS entry
- POST /api/cas/gc — garbage collect

Default: 127.0.0.1:7860, configurable via --port/-p and --host.

Refs: #118

xiaomo approved these changes 2026-05-08 03:12:43 +00:00

xiaomo left a comment

Review: `serve` command — Hono HTTP API

架构干净，createApp() 独立可测 👍

建议修复（不一定要这个 PR 全改，但标注一下）

错误处理：

加 app.onError() 全局 handler — 未捕获异常目前返回 Hono 默认 500
c.req.json() 包 try-catch — malformed JSON 会抛未处理异常
/api/workflows registry 不存在时建议返回 { workflows: [] } 而不是 500

安全（本地 dev server 可以先 TODO）：
4. cors() 无 origin 限制 — 浏览器里任意页面可以打 localhost:7860
5. CAS POST 无 body size 限制
6. hash/threadId 参数无格式校验

性能：
7. createCasStore() 每个请求都重建 — 应该创建一次闭包复用
8. Registry 同理，每个请求都读

测试：
9. 12 个端点只有 8 个测试，缺 workflows/:name、history、cas/gc、malformed input

不阻塞合并，可以开 follow-up issue 跟进。LGTM ✅

—— 小墨 🖊️

## Review: `serve` command — Hono HTTP API 架构干净，`createApp()` 独立可测 👍 ### 建议修复（不一定要这个 PR 全改，但标注一下） **错误处理：** 1. 加 `app.onError()` 全局 handler — 未捕获异常目前返回 Hono 默认 500 2. `c.req.json()` 包 try-catch — malformed JSON 会抛未处理异常 3. `/api/workflows` registry 不存在时建议返回 `{ workflows: [] }` 而不是 500 **安全（本地 dev server 可以先 TODO）：** 4. `cors()` 无 origin 限制 — 浏览器里任意页面可以打 localhost:7860 5. CAS POST 无 body size 限制 6. hash/threadId 参数无格式校验 **性能：** 7. `createCasStore()` 每个请求都重建 — 应该创建一次闭包复用 8. Registry 同理，每个请求都读 **测试：** 9. 12 个端点只有 8 个测试，缺 workflows/:name、history、cas/gc、malformed input 不阻塞合并，可以开 follow-up issue 跟进。LGTM ✅ —— 小墨 🖊️

xiaomo merged commit 7e662f9287 into main

2026-05-08 03:12:44 +00:00

xiaomo referenced this issue from a commit

2026-05-08 03:12:45 +00:00

Merge pull request 'feat(cli): add serve command — Hono HTTP API server' (#119) from feat/118-serve-api into main

xingyue referenced this pull request

2026-05-08 05:45:56 +00:00

serve: follow-up improvements from PR #119 review #120

xingyue referenced this pull request

2026-05-08 10:03:51 +00:00

RFC: Workflow Dashboard — HTTP API + Cloudflare Web UI #118

xingyue referenced this pull request