docs(openspec): plan Comfy CLI and MCP parity

Author: loong10k

openspec/changes/comfy-cli-parity/design.md

@@ -0,0 +1,48 @@
+# Design: comfy-java-sdk CLI and MCP parity
+
+## Architecture
+
+Application
+  -> ComfyClient
+      -> ComfyCli -> ComfyCliExecutor -> comfy
+      -> ComfyMcpClient -> MCP stdio JSON-RPC -> comfy-mcp -> comfy
+
+The Java SDK remains an orchestration/integration SDK. The Python CLI and MCP server stay authoritative for Comfy behavior.
+
+## CLI design
+ComfyCli exposes typed methods for documented stable command families and keeps execute(String...) for newly-added or beta options. Option objects use Java 8-compatible mutable builders but support copy construction so high-level helpers never mutate caller-owned options.
+
+Global JSON parsing uses ComfyJsonEnvelope, preserving JsonNode data/error fields to remain forward compatible with the CLI self-describing contract.
+
+GenerateOptions models common stable flags and supports param(name,value) for model-specific beta parameters.
+
+## MCP design
+ComfyMcpClient owns exactly one comfy-mcp child process. Lifecycle is NEW -> CONNECTING -> CONNECTED -> CLOSED. A failed connect cleans resources and returns to NEW so callers may retry.
+
+Every JSON-RPC request owns:
+- a monotonically increasing id
+- one CompletableFuture
+- one timeout guard
+- one pending-map entry
+
+Completion, timeout, serialization/write failure and close all remove the exact pending entry.
+
+stdout is the MCP protocol channel. stderr is drained concurrently into a capped diagnostic tail so the child cannot deadlock on pipe backpressure.
+
+close() is idempotent, closes stdin, destroys the process, waits a bounded grace interval, escalates to destroyForcibly, fails all pending RPCs and shuts down the scheduler.
+
+## Resource and memory boundaries
+- CLI stdout/stderr capture limits are configurable; <=0 means unbounded.
+- MCP frame, accumulated content and stderr diagnostic caps are configurable.
+- Capped buffers retain a prefix and record truncation instead of growing without bound.
+- No long-lived executor exists on the CLI path.
+- MCP scheduler is daemon-backed and always shutdown by close().
+
+## Security
+- Credentials are expected through environment variables (COMFY_API_KEY, COMFY_BIN); no SDK logging of environment values.
+- Arguments are passed as argv without a shell.
+- Executable paths are treated as a literal executable, not parsed shell text.
+- Network-exposure and spend-consent policy remains enforced by upstream comfy/comfy-mcp.
+
+## Compatibility strategy
+The source is kept Java 8 syntax-compatible wherever possible. Branch 3 changes only Jackson imports/API details and Maven/JDK baseline. Tests assert identical command argv and MCP behavior.

openspec/changes/comfy-cli-parity/proposal.md

@@ -0,0 +1,36 @@
+# Comfy CLI / MCP parity proposal
+
+## Goal
+Bring comfy-java-sdk to parity with the documented Comfy CLI and the first-party local comfy-mcp surface while preserving one business contract across feature/1.0.x, feature/2.0.x and feature/3.0.x.
+
+## Sources of truth
+- https://docs.comfy.org/agent-tools/cli
+- https://docs.comfy.org/comfy-cli/getting-started
+- https://docs.comfy.org/comfy-cli/reference
+- https://docs.comfy.org/agent-tools/mcp
+- https://docs.comfy.org/agent-tools/skills
+- https://github.com/Comfy-Org/comfy-cli
+- https://github.com/Comfy-Org/comfy-mcp
+- https://github.com/Comfy-Org/comfy-skills
+- easy-4-java/codex-java-sdk hardening patterns
+
+## Branch contract
+All three feature branches expose the same Java-level business operations and tests. Only runtime baseline differences are allowed:
+- 1.0.x: Java 8 / Jackson 2
+- 2.0.x: Java 17 / Jackson 2
+- 3.0.x: Java 21 / Jackson 3 / Maven 4
+
+## Scope
+1. Expand typed CLI wrappers for setup, cloud auth, routing, lifecycle, generate, workflows, jobs, templates, nodes, models, transfer, skills and tracking.
+2. Preserve raw execute(...) and generic MCP callTool(...) escape hatches.
+3. Add JSON envelope parsing and a doctor/environment report.
+4. Harden subprocess execution: independent probe timeout, literal executable handling, bounded captures, UTF-8, environment merge.
+5. Harden MCP stdio lifecycle: state machine, stderr draining, request timeout cleanup, write-failure cleanup, process reaping and idempotent close.
+6. Add typed convenience methods for stable first-party local comfy-mcp tools.
+7. Extend MCP content handling beyond text while retaining raw JSON.
+8. Add branch-equivalent tests and production-readiness review.
+
+## Non-goals
+- Reimplement Comfy CLI business logic in Java.
+- Freeze beta partner-model flags. Dynamic model-specific flags remain extensible.
+- Replace comfy-mcp with a Java MCP server.

openspec/changes/comfy-cli-parity/tasks.md

@@ -0,0 +1,22 @@
+# Tasks: comfy-java-sdk CLI / MCP parity
+
+- [ ] T1 Add OpenSpec proposal/design/tasks to all three branches.
+- [ ] T2 Fix ComfyCliExecutor probe timeout to use localProbeTimeoutSeconds.
+- [ ] T3 Add configurable bounded stdout/stderr capture and truncation metadata.
+- [ ] T4 Treat localExecutable as literal argv executable and keep UTF-8 decoding branch-compatible.
+- [ ] T5 Expand ComfyCli typed wrappers for setup/cloud/lifecycle/generate/run/jobs/templates/workflow/nodes/models/upload/download/skills/tracking.
+- [ ] T6 Add dynamic generate param support and validate per-call --where.
+- [ ] T7 Make ComfyClient.generateJson copy options instead of mutating caller input.
+- [ ] T8 Add ComfyJsonEnvelope and ComfyDoctorReport plus discoverJson/doctor helpers.
+- [ ] T9 Harden ComfyMcpClient lifecycle and duplicate-connect behavior.
+- [ ] T10 Drain comfy-mcp stderr with a bounded diagnostic buffer.
+- [ ] T11 Remove pending RPCs on timeout, completion and write failure.
+- [ ] T12 Reap MCP process on close and keep close idempotent.
+- [ ] T13 Add structured ComfyMcpContent while preserving raw result JSON.
+- [ ] T14 Add typed convenience methods for core first-party local comfy-mcp tools.
+- [ ] T15 Add/extend unit and fake-server E2E tests for every regression.
+- [ ] T16 Port identical business behavior to 1.0.x / 2.0.x / 3.0.x with only Jackson/JDK differences.
+- [ ] T17 Run full Maven verify on each branch.
+- [ ] T18 Run dependency/vulnerability audit and inspect CI.
+- [ ] T19 Production readiness review: process/thread/stream/Future cleanup, deadlocks, backpressure, OOM boundaries, command injection, sensitive logging, race conditions and resource leaks.
+- [ ] T20 Record branch SHAs, test totals, CI status and residual risks.