toolcraft-openapi: support CLI-friendly file inputs and binary output paths for generated commands

[kamilio]

Problem

A concrete consumer, OmniVoice's Toolcraft CLI, has many handwritten commands whose core shape is simple HTTP I/O:

1. read a local audio file path,
2. send it as a multipart form-data file field,
3. receive a binary audio response,
4. write it to an output path,
5. return structured metadata such as byte length and response headers.

Today toolcraft-openapi can represent multipart binary fields and binary responses at the wire level, but the generated CLI shape is not ergonomic for humans or agents:

• multipart binary fields are modeled as base64 strings,
• binary responses return { encoding: "base64", data: ... },
• callers must hand-write path resolution and writeFile(...),
• each wrapper repeats FormData, Blob, readFile, arrayBuffer, and output metadata handling.

That makes simple API tools become custom wrappers.

OmniVoice examples

From OmniVoice-Studio/tools/omnivoice-toolcraft/src/commands.js:

• speak writes a generated /generate binary response to --output (commands.js:187-206).
• generateLineWav repeats the same /generate multipart + binary-output flow for story segments (commands.js:1382-1400).
• createCloneProfile uploads ref_audio as multipart from a local path (commands.js:2241-2257).
• cleanAudioViaBackend uploads audio, receives binary WAV, and writes --output (commands.js:2260-2278).
• synthesizeFromDesignedVoice uploads optional ref_audio and writes binary output (commands.js:2281-2308).
• resolveUserPath repeats INIT_CWD || process.cwd() path behavior (commands.js:2617-2619).

These wrappers contain domain logic too, but a large amount is generic Toolcraft/OpenAPI file plumbing.

Requested feature

Add first-class generated-command support for file path params and output path params, aimed at CLI/MCP/SDK parity without forcing base64 into the human path.

Possible shape:

# future toolcraft.yml or generator option
operations:
  post /generate:
    files:
      ref_audio:
        param: refAudio
        contentType: audio/wav
    binaryResponse:
      outputParam: output
      defaultFileName: omnivoice-output.wav
      includeHeaders:
        audioId: x-audio-id
        audioDuration: x-audio-duration

Generated CLI behavior could be:

omnivoice generate --text "hello" --ref-audio ./voice.wav --output ./out.wav

Generated SDK behavior could allow either bytes/base64 or file-path adapters, but the CLI should optimize for local paths.

Acceptance criteria

• OpenAPI multipart fields with type: string, format: binary can be exposed as CLI file path options.
• The runtime reads the file, sets a useful filename, and sends multipart FormData without command-specific glue.
• Binary responses can be written directly to an --output path, while preserving the current base64 response mode for SDK/MCP where useful.
• Generated result includes at least { output, byteLength, contentType } and optionally configured response headers.
• Path resolution is consistent with Toolcraft CLI cwd semantics, so consumers do not need local resolveUserPath(...) helpers.
• Existing generated behavior remains available for APIs that prefer base64-in/base64-out.

Why this helps

This would let simple media/file endpoints stay generated from OpenAPI instead of becoming handwritten commands. For agent-facing tools, it also keeps the invocation simple: pass a path, get a path back, inspect structured metadata.

[kamilio]

Resolved in de9796f.

Implemented CLI-friendly multipart file inputs and binary response output paths for generated toolcraft-openapi commands, including generated-code and dynamic runtime paths.

Validation:

• npx vitest run packages/toolcraft-openapi/src
• npm run build --workspace toolcraft-openapi
• npx eslint packages/toolcraft-openapi/src --ext ts
• npm run lint:types
• pre-push unit suite: 742 files / 12,668 tests passed

Release verification:

• Release: https://github.com/poe-platform/poe-code/actions/runs/27485910941
• Release toolcraft packages: https://github.com/poe-platform/poe-code/actions/runs/27485910934
• Publish Schemas to GitHub Pages: https://github.com/poe-platform/poe-code/actions/runs/27485910933