uncaged/workflow
10
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: restructure CLI commands (workflow/thread/step/turn) #467

Merged
xiaomo merged 6 commits from fix/463-http-methods into main 2026-05-24 11:37:51 +00:00
Conversation 2 Commits 6 Files Changed 8
+734 -383
xiaoju commented 2026-05-24 11:05:02 +00:00
Owner
Copy Link
Copy Source

Fixes #463

Fixes #463
xiaoju added 4 commits 2026-05-24 11:05:02 +00:00
refactor(cli): reorganize CLI commands into four-layer model (#463) 7b50969307 
Implement comprehensive CLI refactoring to clarify the four-layer model:
workflow → thread → step → turn

## Breaking Changes

### Renamed Commands
- `uwf workflow put` → `uwf workflow add`
- `uwf thread step` → `uwf thread exec`

### Removed Commands
- `uwf thread running` (merged into `thread list --status running`)
- `uwf thread kill` (split into `thread stop` and `thread cancel`)

### Moved Commands
- `uwf thread steps` → `uwf step list`
- `uwf thread step-details` → `uwf step show`
- `uwf thread fork` → `uwf step fork`

## New Commands

### Thread Commands
- `uwf thread list --status <idle|running|completed>` - Filter threads by status
- `uwf thread stop <thread-id>` - Stop background execution (keep thread active)
- `uwf thread cancel <thread-id>` - Cancel thread (stop + archive to history)

### Step Command Group (New)
- `uwf step list <thread-id>` - List all steps in a thread
- `uwf step show <step-hash>` - Show step details
- `uwf step read <step-hash> [--before N]` - Read step output as markdown
- `uwf step fork <step-hash>` - Fork thread from a step

## Implementation Details

### Files Modified
- `packages/cli-workflow/src/commands/workflow.ts` - Renamed cmdWorkflowPut → cmdWorkflowAdd
- `packages/cli-workflow/src/commands/thread.ts`:
  - Renamed cmdThreadStep → cmdThreadExec
  - Added cmdThreadStop and cmdThreadCancel (split from cmdThreadKill)
  - Updated cmdThreadList to support --status filter with idle/running/completed
  - Removed cmdThreadSteps, cmdThreadStepDetails, cmdThreadFork
- `packages/cli-workflow/src/commands/step.ts` - New module with:
  - cmdStepList (moved from cmdThreadSteps)
  - cmdStepShow (moved from cmdThreadStepDetails)
  - cmdStepFork (moved from cmdThreadFork)
  - cmdStepRead (new, stub implementation pending #462)
- `packages/cli-workflow/src/cli.ts` - Updated all CLI command registrations

### Tests Updated
- `packages/cli-workflow/src/__tests__/thread-step-count.test.ts` - Updated references from "thread step" to "thread exec"
- `packages/cli-workflow/src/__tests__/thread.test.ts` - Updated imports to use cmdStepShow from step.ts

## Test Results
All 124 tests pass in cli-workflow package.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
docs(cli): add deprecation handlers and update documentation (#463) 031c3aa632 
Complete the CLI refactoring with deprecation error handlers, updated
help text, and comprehensive migration guide.

## Changes

### Deprecation Handlers
Add error handlers for all removed commands with helpful migration messages:
- `workflow put` → suggests `workflow add`
- `thread step` → suggests `thread exec`
- `thread steps` → suggests `step list`
- `thread step-details` → suggests `step show`
- `thread fork` → suggests `step fork`
- `thread kill` → suggests `thread stop` or `thread cancel`
- `thread running` → suggests `thread list --status running`

Error messages follow the format:
```
Error: Command 'X' has been removed.
Use 'Y' instead.

For more information, see: uwf help Y
```

### Help Documentation
Updated CLI help text to explain four-layer architecture:
- Main help shows architecture diagram with Chinese labels
- Command group descriptions reference layers:
  - `workflow` → "Workflow definitions (layer 1: templates)"
  - `thread` → "Thread execution (layer 2: instances)"
  - `step` → "Step results (layer 3: single cycle)"
- Deprecated commands appear in help with [DEPRECATED] tag

### README Updates
Comprehensive documentation updates:
- Added "Four-Layer Architecture" section with diagram
- Updated all command tables with new command names
- Added complete migration guide with:
  - Renamed commands table
  - Merged commands table
  - Split commands table
  - Moved commands table
  - Example deprecation error output
- Updated "Internal Structure" to show new step.ts module

## Testing
- ✅ All 124 tests pass
- ✅ Build completes successfully
- ✅ Deprecation handlers tested manually
- ✅ Help output verified for main, thread, and step commands

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
fix(cli): resolve lint errors and unused imports (#463) 1f13b1e79c 
Fix all lint errors flagged by biome check to ensure clean codebase.

## Changes

### Removed Unused Imports
- `packages/cli-workflow/src/commands/thread.ts`:
  - Removed `StartEntry` (moved to step.ts)
  - Removed `StepEntry` (moved to step.ts)
  - Removed `ThreadForkOutput` (moved to step.ts)
  - Removed `ThreadStepsOutput` (moved to step.ts)

- `packages/cli-workflow/src/cli.ts`:
  - Removed unused `yamlStringify` import from yaml package

### Fixed Unused Parameter
- `packages/cli-workflow/src/commands/step.ts`:
  - Prefixed unused `before` parameter with underscore in `cmdStepRead`
  - Parameter is part of the function signature for future use (awaiting #462)

### Fixed Import Order
- `packages/cli-workflow/src/__tests__/thread.test.ts`:
  - Reordered imports to follow biome's organization rules
  - Moved cmdStepShow import before cmdThreadRead imports

## Test Results
- ✅ `bun run check` passes (typecheck + lint + log tags)
- ✅ All 124 tests passing
- ✅ Build completes successfully

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
fix(agent-claude-code): add missing workflow-util dependency c40007eeaf 
The claude-code agent imports createLogger from @uncaged/workflow-util
but was missing the dependency declaration, causing test failures.
xiaoju added 1 commit 2026-05-24 11:12:55 +00:00
feat(step): expand detail CAS refs by default in step list 650313b1c2 
Previously step list showed raw CAS refs for detail fields.
Now detail is recursively expanded (like output already was),
since every turn is individually hashed and walkable.

Refs #463
xiaomo requested changes 2026-05-24 11:19:56 +00:00
Dismissed
xiaomo left a comment
Owner
Copy Link
Copy Source

重构方向正确，命令拆分合理，废弃提示完整 👍 几个问题需要修：

必须修

1. step.ts 里 walkChain / expandDeep 等大量代码是从 thread.ts 复制的

walkChain、expandDeep、expandValue、expandCasRefField、expandAnyOfField、expandArrayField、expandObjectField、collectOrderedSteps、expandOutput — 这些函数在 thread.ts 里本来就有，现在 step.ts 里又写了一遍。

应该提取到一个共享模块（比如 src/chain.ts 或 src/cas-expand.ts），两边 import。代码重复是 bug 的温床。

2. step read 是个半成品

// TODO: Implement progressive turn reading with --before N
// For now, return a placeholder
return JSON.stringify(outputNode.payload, null, 2);

CLI 已注册、README 已写、migration guide 也列了，但实现是 TODO + JSON fallback。要么这个 PR 不暴露 step read 命令（注释掉 CLI 注册），要么实现它。半成品命令暴露给用户会造成困惑。

建议：这个 PR 先不注册 step read，README 里标注 (coming soon)，等 #462 合并后再加。

3. cmdThreadKill 没删

thread.ts 里 cmdThreadKill 函数还在（文件末尾），但 CLI 已经注册了 deprecation handler 指向 stop/cancel。函数本身不再被任何 CLI 命令调用。应该删掉，避免死代码。

4. thread list --status completed 的逻辑有 bug

// Add completed threads if requested
if (statusFilter === "completed" || statusFilter === null) {
  // ... load history
}

// Apply status filter if provided
if (statusFilter !== null) {
  return items.filter((item) => item.status === statusFilter);
}

当 statusFilter === "idle" 时，不加载 history（正确），但也不 filter active threads（走到最后 return items，包含了所有 active = idle + running）。实际上 --status idle 会返回 running 的 thread。

修法：filter 应该在 return 之前统一做，或者把 active threads 的加载也条件化。

建议（不阻塞）

5. StepEntry.detail 类型从 CasRef 改成 unknown

workflow-protocol/src/types.ts 里把 detail: CasRef 改成了 detail: unknown。这是 protocol 层的 breaking change，影响所有消费者。虽然 step list 需要展开 detail，但 protocol 类型应该保持 CAS 语义（是引用），展开是 CLI 层的事。

建议：protocol 保持 CasRef，CLI 输出类型单独定义。

6. PR 标题和 branch 名

小橘提醒了，标题是 fix: add explicit return types for GET/POST methods，branch 是 fix/463-http-methods，跟实际内容（CLI 命令重构）完全不搭。建议改一下 PR title。

7. workflow-agent-claude-code/package.json 加了 workflow-util 依赖

这个改动跟 CLI 重构无关，应该在单独的 commit/PR 里。

重构方向正确，命令拆分合理，废弃提示完整 👍 几个问题需要修： ## 必须修 ### 1. `step.ts` 里 `walkChain` / `expandDeep` 等大量代码是从 `thread.ts` 复制的 `walkChain`、`expandDeep`、`expandValue`、`expandCasRefField`、`expandAnyOfField`、`expandArrayField`、`expandObjectField`、`collectOrderedSteps`、`expandOutput` — 这些函数在 `thread.ts` 里本来就有，现在 `step.ts` 里又写了一遍。 应该提取到一个共享模块（比如 `src/chain.ts` 或 `src/cas-expand.ts`），两边 import。代码重复是 bug 的温床。 ### 2. `step read` 是个半成品 ```ts // TODO: Implement progressive turn reading with --before N // For now, return a placeholder return JSON.stringify(outputNode.payload, null, 2); ``` CLI 已注册、README 已写、migration guide 也列了，但实现是 TODO + JSON fallback。要么这个 PR 不暴露 `step read` 命令（注释掉 CLI 注册），要么实现它。半成品命令暴露给用户会造成困惑。 建议：这个 PR 先不注册 `step read`，README 里标注 `(coming soon)`，等 #462 合并后再加。 ### 3. `cmdThreadKill` 没删 `thread.ts` 里 `cmdThreadKill` 函数还在（文件末尾），但 CLI 已经注册了 deprecation handler 指向 `stop`/`cancel`。函数本身不再被任何 CLI 命令调用。应该删掉，避免死代码。 ### 4. `thread list --status completed` 的逻辑有 bug ```ts // Add completed threads if requested if (statusFilter === "completed" || statusFilter === null) { // ... load history } // Apply status filter if provided if (statusFilter !== null) { return items.filter((item) => item.status === statusFilter); } ``` 当 `statusFilter === "idle"` 时，不加载 history（正确），但也不 filter active threads（走到最后 return items，包含了所有 active = idle + running）。实际上 `--status idle` 会返回 running 的 thread。 修法：filter 应该在 return 之前统一做，或者把 active threads 的加载也条件化。 ## 建议（不阻塞） ### 5. `StepEntry.detail` 类型从 `CasRef` 改成 `unknown` `workflow-protocol/src/types.ts` 里把 `detail: CasRef` 改成了 `detail: unknown`。这是 protocol 层的 breaking change，影响所有消费者。虽然 `step list` 需要展开 detail，但 protocol 类型应该保持 CAS 语义（是引用），展开是 CLI 层的事。 建议：protocol 保持 `CasRef`，CLI 输出类型单独定义。 ### 6. PR 标题和 branch 名 小橘提醒了，标题是 `fix: add explicit return types for GET/POST methods`，branch 是 `fix/463-http-methods`，跟实际内容（CLI 命令重构）完全不搭。建议改一下 PR title。 ### 7. `workflow-agent-claude-code/package.json` 加了 `workflow-util` 依赖 这个改动跟 CLI 重构无关，应该在单独的 commit/PR 里。
xiaoju added 1 commit 2026-05-24 11:33:19 +00:00
refactor: address review feedback for CLI restructure 669af841e1 
- Extract shared module (shared.ts) — walkChain, expandDeep, etc. deduplicated
- Hide step read command (half-baked, not ready for users)
- Remove cmdThreadKill dead code
- Revert unrelated protocol type change
- Revert unrelated package.json change
- Fix unused imports (biome)

Refs #463
xiaoju changed title from fix: add explicit return types for GET/POST methods to feat: restructure CLI commands (workflow/thread/step/turn) 2026-05-24 11:33:26 +00:00
xiaomo approved these changes 2026-05-24 11:37:49 +00:00
xiaomo left a comment
Owner
Copy Link
Copy Source

LGTM 👍 四个必须修的问题都解决了。

两个小瑕疵不阻塞合并，合并后顺手清理：

  1. cmdThreadRunning 函数还在 thread.ts 里但没有调用方了，可以删掉
  2. README 表格列了 step read 但命令没注册，建议标注 (coming soon) 或先去掉
LGTM 👍 四个必须修的问题都解决了。 两个小瑕疵不阻塞合并，合并后顺手清理： 1. `cmdThreadRunning` 函数还在 `thread.ts` 里但没有调用方了，可以删掉 2. README 表格列了 `step read` 但命令没注册，建议标注 `(coming soon)` 或先去掉
xiaomo merged commit 5c0eabda8e into main 2026-05-24 11:37:51 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
xiaomo
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
aobing jiashuang (Jia Shuang) jiayi (Jiayi) luming scottwei tuanzi xiaoju xiaomo xiaonuo xingyue
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: uncaged/workflow#467
Delete Branch "fix/463-http-methods"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?