docs: define full Comfy CLI MCP Skills parity

Author: loong10k

docs/architecture/comfy-java-sdk-full-parity-architecture.md

@@ -1,48 +1,225 @@
-# Design: comfy-java-sdk CLI and MCP parity
+# Design: Comfy Java SDK Full Parity
 
-## Architecture
+## 1. Architecture
 
+~~~text
 Application
   -> ComfyClient
-      -> ComfyCli -> ComfyCliExecutor -> comfy
-      -> ComfyMcpClient -> MCP stdio JSON-RPC -> comfy-mcp -> comfy
+      -> CLI route: ComfyCli -> executor/stream session -> comfy
+      -> MCP route: ComfyMcpClient -> 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.
+The Python CLI and MCP server remain authoritative. Java adds type-safe requests, process ownership, async/streaming abstractions, compatibility discovery, structured errors/results, bounded memory, deterministic cleanup and production diagnostics.
 
-## 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.
+## 2. Canonical implementation
 
-Global JSON parsing uses ComfyJsonEnvelope, preserving JsonNode data/error fields to remain forward compatible with the CLI self-describing contract.
+Use feature/2.0.x as the canonical behavior-development line because it currently contains the newest subprocess and MCP hardening.
 
-GenerateOptions models common stable flags and supports param(name,value) for model-specific beta parameters.
+After canonical behavior is green:
 
-## 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.
+1. back-port identical behavior to feature/1.0.x,
+2. forward-port identical behavior to feature/3.0.x,
+3. normalize allowed Jackson/JDK differences and compare,
+4. run the same fixtures on all three.
 
-Every JSON-RPC request owns:
-- a monotonically increasing id
-- one CompletableFuture
-- one timeout guard
-- one pending-map entry
+No feature is complete until all three lines pass.
 
-Completion, timeout, serialization/write failure and close all remove the exact pending entry.
+## 3. CLI API
 
-stdout is the MCP protocol channel. stderr is drained concurrently into a capped diagnostic tail so the child cannot deadlock on pipe backpressure.
+### Three layers
 
-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.
+A. Typed stable API for high-frequency stable commands.
 
-## 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().
+B. Command-family API so each current first-party family is reachable without a shell.
 
-## 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.
+C. Generic execute(String...) for future/unknown commands.
 
-## 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.
+Typed option objects remain Java 8-compatible and copyable.
+
+### Capability discovery
+
+Add a runtime surface model populated from:
+
+~~~text
+comfy --help-json
+comfy --json discover
+comfy --json discover --schemas-only
+~~~
+
+It records current CLI version, command/subcommand/schema availability, error-code contract, typed-wrapper availability and generic fallback requirements.
+
+### Machine envelope
+
+ComfyJsonEnvelope retains stable fields, data, error and raw JSON. Truncated machine output must never be accepted as a valid envelope.
+
+## 4. CLI streaming
+
+The synchronous executor remains correct for short commands. Long-running run/jobs/download/build/deploy operations need incremental output.
+
+~~~text
+ComfyCliStreamExecutor
+  -> Process
+  -> stdout reader -> NDJSON decoder -> ComfyCliEvent -> listener
+  -> stderr reader -> listener/bounded diagnostic tail
+  -> completion future
+~~~
+
+Required invariants:
+
+- events arrive before process exit,
+- listener failures do not leak the child,
+- cancellation kills/reaps the child,
+- close is idempotent,
+- stdout/stderr stay drained,
+- retained memory is bounded,
+- final envelope/error remains queryable.
+
+Public behavior must remain Java 8-compatible through ordinary threads and CompletableFuture.
+
+## 5. MCP lifecycle
+
+~~~text
+NEW
+ |
+ v
+CONNECTING ----failure----> NEW
+ |
+ v
+CONNECTED ----transport failure----> NEW
+ |
+ +-------------------------------> CLOSED
+NEW -----------------------------> CLOSED
+~~~
+
+CLOSED is terminal.
+
+Unexpected child death must transition away from CONNECTED.
+
+Introduce one internal fatal-transport cleanup path responsible for:
+
+1. transition state,
+2. fail pending RPCs,
+3. close writer,
+4. destroy/reap child,
+5. close child streams,
+6. stop/join readers,
+7. clear references.
+
+Use it for stdout EOF, frame overflow, write failure, failed initialize and close.
+
+## 6. MCP RPC registry
+
+pendingRpcs contains active calls only.
+
+~~~text
+allocate id
+put(id, future)
+schedule timeout
+write
+ |
+ +-- response -> remove -> complete
+ +-- rpc error -> remove -> exceptional complete
+ +-- timeout -> remove -> exceptional complete
+ +-- write error -> remove -> exceptional complete
+ +-- transport close -> failAllPending
+~~~
+
+Every request has one id, Future, pending entry and timeout guard.
+
+## 7. MCP complete tool facade
+
+The reviewed server exposes 40 first-party tools. Each receives a direct convenience method while generic callTool remains.
+
+Use stable Java types for stable inputs and forward-compatible Map/DTO structures where upstream parameters are intentionally dynamic.
+
+## 8. MCP notifications and elicitation
+
+Frames must be classified as:
+
+- response: id plus result/error,
+- server request: id plus method,
+- notification: method without id.
+
+Add ComfyMcpNotification and ComfyMcpListener for generic/progress notifications.
+
+If elicitation support is configured, add ComfyMcpElicitationHandler and advertise the capability. Otherwise do not advertise it.
+
+## 9. MCP content
+
+ComfyMcpContent keeps type, text, MIME, URI, encoded data accessor and raw JSON. Avoid eagerly duplicating large encoded payloads.
+
+## 10. Skills
+
+Treat comfy-cli as the source of truth for local skills.
+
+Typed operations:
+
+- install,
+- uninstall,
+- list,
+- show,
+- status,
+- validate.
+
+Options cover user/project scope, repeated target, repeated skill and dry-run.
+
+Do not vendor skill contents.
+
+## 11. Memory boundaries
+
+CLI configuration covers stdout cap, stderr cap, command timeout, probe timeout, process shutdown grace and one shared stream-drain deadline.
+
+MCP configuration covers frame chars, concatenated text chars, stderr tail chars, request timeout, initialize timeout and shutdown grace.
+
+All limits are validated and all unbounded semantics are explicit.
+
+## 12. Security
+
+Use argv-safe ProcessBuilder execution and never concatenate shell command strings.
+
+Prefer environment variables for secrets, never log environment values, and redact/avoid secret-bearing argv in diagnostics.
+
+Do not silently bypass upstream confirmation gates for spend, network exposure, node installation, version switching/update-all or killing untracked listeners.
+
+## 13. Doctor / compatibility
+
+Expand doctor into:
+
+- CLI binary/version check,
+- workspace/env/discover check,
+- minimum-supported version check,
+- optional comfy-mcp initialize/tools-list check,
+- optional local ComfyUI server-info check,
+- runtime CLI/MCP typed-parity report.
+
+Diagnostics contain no secret values.
+
+## 14. CI / branch parity
+
+JaCoCo prepare-agent must reach the forked test JVM. CI fails if jacoco.exec/report is missing or coverage is below threshold. haltOnFailure is true for production validation.
+
+Commit one identical parity manifest on all three branches.
+
+Each branch validates CLI families, MCP tools, Skills and lifecycle invariants against that manifest.
+
+A normalized comparison may fetch other branches and ignore only Jackson imports, JDK adapters, POM/dependency/build differences.
+
+## 15. Dependencies
+
+Baseline targets at review time:
+
+- 1.x: Jackson at least 2.18.10 on Java 8,
+- 2.x: current patched Jackson 2 release compatible with Java 17,
+- 3.x: Jackson at least 3.2.2.
+
+Revalidate exact patch versions when implementing.
+
+## 16. Tests
+
+Unit tests cover option builders, argv, parsing and validation.
+
+Hermetic process fixtures cover stdout/stderr, huge output, timeout, inherited pipes, stdin, UTF-8 and early exit.
+
+Fake MCP E2E covers initialize, all typed wrapper request shapes, generic calls, concurrency, timeout, stderr flood, child crash, malformed/oversized frames, mixed content, notifications and elicitation if enabled.
+
+Soak tests assert zero pending RPCs, no live child, no accumulating reader/timer threads and bounded diagnostics.

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

@@ -1,36 +1,108 @@
-# Comfy CLI / MCP parity proposal
+# Change Proposal: Comfy Java SDK Full CLI / MCP / Skills Parity
+
+## Why
+
+comfy-java-sdk exists to provide complete Java integration with first-party comfy-cli and local comfy-mcp.
+
+The current SDK already has a strong two-route foundation, but parity is incomplete:
+
+- the three maintained branches are not yet behaviorally aligned,
+- CLI coverage still trails the current first-party command tree,
+- long-running CLI operations need real streaming/async APIs,
+- the typed MCP facade does not yet expose the complete current tool catalog,
+- MCP progress/notifications and optional elicitation are not surfaced,
+- abnormal MCP child termination needs stronger state recovery,
+- JaCoCo is configured but the agent is not actually reaching Surefire,
+- dependency/security and cross-branch parity need automated release gates.
 
 ## 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
+Deliver one business contract for comfy-java-sdk that fully integrates:
+
+1. current first-party comfy-cli,
+2. current local comfy-mcp,
+3. first-party CLI Skills management,
+4. JSON envelope and streaming event contracts,
+5. production-safe subprocess/MCP lifecycle behavior,
+6. automated branch parity across Java 8, 17 and 21 lines.
+
+## 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://docs.comfy.org/comfy-cli/getting-started
+- https://docs.comfy.org/comfy-cli/reference
 - 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
+Baseline source snapshots reviewed on 2026-09-20:
+
+- Comfy-Org/comfy-cli b08adc50cca24f2d29d2115e80719cb8299e6ddf
+- Comfy-Org/comfy-mcp e5f768d31de21ea32829381cebdda5336492a8ac
+- Comfy-Org/comfy-skills d50722a53585d0ab4fd1909fd59294b978aad449
+
+## Branch Contract
+
+All maintained feature branches MUST expose the same Java-level business operations, semantics, safety behavior and logical test suite:
+
+- feature/1.0.x: Java 8 / Jackson 2
+- feature/2.0.x: Java 17 / Jackson 2
+- feature/3.0.x: Java 21 / Jackson 3 / Maven 4
+
+Only JDK/Jackson/Maven compatibility differences are permitted.
 
 ## 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.
+
+### CLI
+
+- Cover every current first-party command family.
+- Add typed stable option objects for high-frequency operations.
+- Preserve execute(String...) as the forward-compatible escape hatch.
+- Use discover and --help-json as a runtime capability contract.
+- Add true streaming/async execution for NDJSON and progress-producing commands.
+
+### MCP
+
+- Preserve generic tools/list and callTool.
+- Add typed convenience methods for the complete current first-party local tool catalog.
+- Harden state transitions, process failure recovery, timeout cleanup, stderr drain and process/thread/timer release.
+- Preserve all MCP content types.
+- Surface notifications/progress.
+- Support elicitation only when a real handler is configured and advertised.
+
+### Skills
+
+- Support install, uninstall, list, show, status and validate.
+- Support scope, target, skill selection and dry-run.
+- Do not hard-code skill bodies or volatile model/template/node catalogs.
+
+### Production readiness
+
+- Fix effective JaCoCo execution.
+- Add dependency/security audit.
+- Add resource/memory soak tests.
+- Add branch-parity CI and capability manifest.
 
 ## 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.
+- Freeze dynamic partner model schemas into permanent Java enums.
+- Hard-code currently available templates, models, node ids or skill bodies.
+- Add hosted Comfy Cloud MCP transport unless separately specified.
+
+## Success Criteria
+
+The change is complete only when all three maintained branches:
+
+- pass the same logical parity suite,
+- expose the same public business surface,
+- can reach the complete current CLI and local MCP capabilities,
+- provide streaming for long-running CLI workflows,
+- clean up every subprocess/thread/timer/Future on all terminal paths,
+- enforce bounded memory,
+- pass security/dependency checks,
+- generate real JaCoCo coverage and enforce the configured threshold,
+- pass automated cross-branch parity checks.