feat(Calibre): add a CLI-Anything harness for Calibre Desktop

[27494539a-hub]

Description

This PR adds a new in-repo CLI-Anything harness for Calibre at calibre/agent-harness, built from scratch.

The harness wraps Calibre’s real native CLI surfaces instead of reimplementing Calibre internals:

• calibredb for library CRUD/search/export/backup flows
• ebook-meta for standalone ebook metadata inspection and update
• ebook-convert for format conversion pipelines

It is packaged as cli-anything-calibre and supports both one-shot commands and REPL/session workflows.

What This Adds

Stable capabilities

• runtime and library inspection (library info, library stats, library list-fields)
• library-scoped book operations (book add/list/get/search/remove/set-field)
• standalone file metadata operations (meta show/set/set-cover/clear)
• export and backup flows (export book/catalog/backup)
• conversion workflows with presets (convert formats/presets/run)
• session-aware CLI behavior (session status/undo/redo/history/save)
• machine-readable output via --json across command groups
• robust CLI subprocess usage with clear dependency errors

Design Notes

• Uses official/native Calibre command surfaces whenever available.
• Keeps translation risk low by delegating core behavior to real binaries.
• Adds a stateful session layer for agent-oriented workflows without replacing backend semantics.
• Treats backend dependencies as hard requirements and fails loudly when missing.
• Uses explicit file/library paths to keep automation deterministic on Windows.
• Keeps test assertions artifact-based (existence, non-empty files, format signatures where applicable).

Type of Change

• New Software CLI (in-repo) — adds a CLI harness inside this monorepo
• New Software CLI (standalone repo) — registry-only PR pointing to an external repo
• New Feature — adds new functionality to an existing harness or the plugin
• Bug Fix — fixes incorrect behavior
• Documentation — updates docs only
• Other — please describe:

For New Software CLIs (in-repo)

• <SOFTWARE>.md SOP document exists at <software>/agent-harness/<SOFTWARE>.md
• Canonical SKILL.md exists at skills/cli-anything-<software>/SKILL.md
• Packaged compatibility SKILL.md exists at cli_anything/<software>/skills/SKILL.md
• Unit tests at cli_anything/<software>/tests/test_core.py are present and pass without backend
• E2E tests at cli_anything/<software>/tests/test_full_e2e.py are present
• README.md includes the new software (with link to harness directory)
• registry.json includes an entry with source_url: null (see Contributing guide)
• repl_skin.py in utils/ is an unmodified copy from the plugin

General Checklist

• Code follows existing patterns and conventions
• --json flag is supported on any new commands
• Commit messages follow the conventional format (feat:, fix:, docs:, test:)
• I have tested my changes locally

Validation

Validated locally with:

• python -m pytest -q with CLI_ANYTHING_FORCE_INSTALLED=1 → 25 passed in 61.35s
• python -m pytest -v -s cli_anything\calibre\tests\test_full_e2e.py → 8 passed in 20.62s
• python -m pytest cli_anything/calibre/tests/test_full_e2e.py::test_workflow_library_mutation -v -s → 1 passed in 6.83s

Agent test (CLI-only, Sonnet 4.6) completed with full task chain:

library stats -> book add -> book search -> export book -> convert run -> meta show

Final structured output:

{"book_id":1,"export_dir":"D:\\AgentTest\\out","exported_epub":"D:\\AgentTest\\out\\Agent Test Book - OpenCode Bot.epub","converted_file":"D:\\AgentTest\\out\\converted\\agent-test.mobi","all_exit_zero":true}

GUI round-trip validation summary:

• Opened same library path in Calibre GUI (D:\Books\Calibre Library)
• Verified title/author consistency for the CLI-created book
• Verified exported EPUB and converted MOBI artifacts exist and are non-empty

Test Coverage

Coverage includes:

• unit tests for session lifecycle, library validation, parse helpers, preset handling
• subprocess and command-resolution behavior (CLI_ANYTHING_FORCE_INSTALLED=1)
• live E2E workflows using real Calibre binaries
• ingest/search/export/convert and metadata update workflows
• artifact integrity checks (existence, non-empty output, format-level verification where applicable)
• Windows-specific stability handling (path-length and console decoding robustness)

Known Limitations

• requires real Calibre binaries on PATH (calibredb, ebook-meta, ebook-convert)
• does not provide GUI automation itself; GUI round-trip is a separate/manual validation step
• conversion outcomes depend on Calibre conversion backend behavior and selected preset
• file-level metadata updates and library-record metadata updates are distinct workflows and should be validated accordingly
• no direct replacement of Calibre internals; behavior follows upstream CLI constraints

[27494539a-hub]

Description

This PR adds a new in-repo CLI-Anything harness for Calibre at calibre/agent-harness, built from scratch.

The harness wraps Calibre’s real native CLI surfaces instead of reimplementing Calibre internals:

• calibredb for library CRUD/search/export/backup flows
• ebook-meta for standalone ebook metadata inspection and update
• ebook-convert for format conversion pipelines

It is packaged as cli-anything-calibre and supports both one-shot commands and REPL/session workflows.

What This Adds

Stable capabilities

• runtime and library inspection (library info, library stats, library list-fields)
• library-scoped book operations (book add/list/get/search/remove/set-field)
• standalone file metadata operations (meta show/set/set-cover/clear)
• export and backup flows (export book/catalog/backup)
• conversion workflows with presets (convert formats/presets/run)
• session-aware CLI behavior (session status/undo/redo/history/save)
• machine-readable output via --json across command groups
• robust CLI subprocess usage with clear dependency errors

Design Notes

• Uses official/native Calibre command surfaces whenever available.
• Keeps translation risk low by delegating core behavior to real binaries.
• Adds a stateful session layer for agent-oriented workflows without replacing backend semantics.
• Treats backend dependencies as hard requirements and fails loudly when missing.
• Uses explicit file/library paths to keep automation deterministic on Windows.
• Keeps test assertions artifact-based (existence, non-empty files, format signatures where applicable).

Type of Change

• New Software CLI (in-repo) — adds a CLI harness inside this monorepo
• New Software CLI (standalone repo) — registry-only PR pointing to an external repo
• New Feature — adds new functionality to an existing harness or the plugin
• Bug Fix — fixes incorrect behavior
• Documentation — updates docs only
• Other — please describe:

For New Software CLIs (in-repo)

• <SOFTWARE>.md SOP document exists at <software>/agent-harness/<SOFTWARE>.md
• Canonical SKILL.md exists at skills/cli-anything-<software>/SKILL.md
• Packaged compatibility SKILL.md exists at cli_anything/<software>/skills/SKILL.md
• Unit tests at cli_anything/<software>/tests/test_core.py are present and pass without backend
• E2E tests at cli_anything/<software>/tests/test_full_e2e.py are present
• README.md includes the new software (with link to harness directory)
• registry.json includes an entry with source_url: null (see Contributing guide)
• repl_skin.py in utils/ is an unmodified copy from the plugin

General Checklist

• Code follows existing patterns and conventions
• --json flag is supported on any new commands
• Commit messages follow the conventional format (feat:, fix:, docs:, test:)
• I have tested my changes locally

Validation

Validated locally with:

• python -m pytest -q with CLI_ANYTHING_FORCE_INSTALLED=1 → 25 passed in 61.35s
• python -m pytest -v -s cli_anything\calibre\tests\test_full_e2e.py → 8 passed in 20.62s
• python -m pytest cli_anything/calibre/tests/test_full_e2e.py::test_workflow_library_mutation -v -s → 1 passed in 6.83s

Agent test (CLI-only, Sonnet 4.6) completed with full task chain:

library stats -> book add -> book search -> export book -> convert run -> meta show

Final structured output:

{"book_id":1,"export_dir":"D:\\AgentTest\\out","exported_epub":"D:\\AgentTest\\out\\Agent Test Book - OpenCode Bot.epub","converted_file":"D:\\AgentTest\\out\\converted\\agent-test.mobi","all_exit_zero":true}

GUI round-trip validation summary:

• Opened same library path in Calibre GUI (D:\Books\Calibre Library)
• Verified title/author consistency for the CLI-created book
• Verified exported EPUB and converted MOBI artifacts exist and are non-empty

Test Coverage

Coverage includes:

• unit tests for session lifecycle, library validation, parse helpers, preset handling
• subprocess and command-resolution behavior (CLI_ANYTHING_FORCE_INSTALLED=1)
• live E2E workflows using real Calibre binaries
• ingest/search/export/convert and metadata update workflows
• artifact integrity checks (existence, non-empty output, format-level verification where applicable)
• Windows-specific stability handling (path-length and console decoding robustness)

Known Limitations

• requires real Calibre binaries on PATH (calibredb, ebook-meta, ebook-convert)
• does not provide GUI automation itself; GUI round-trip is a separate/manual validation step
• conversion outcomes depend on Calibre conversion backend behavior and selected preset
• file-level metadata updates and library-record metadata updates are distinct workflows and should be validated accordingly
• no direct replacement of Calibre internals; behavior follows upstream CLI constraints

[yuh-yang]

Thanks for the Calibre harness. I checked the current branch and the new Calibre Python files compile, and the unit suite passes from calibre/agent-harness (8 passed). There are still a few blockers before this is safe to merge.

First, the PR includes a lot of unrelated churn outside Calibre: ComfyUI files are rewritten line-for-line, and several unrelated scripts lose their executable bit. Please remove those changes so the diff is limited to Calibre, docs, registry, skills, and the required .gitignore entries.

Second, the .gitignore allowlist is incomplete. It adds !/calibre, but this repo's deny-by-default pattern needs the full top-level/inner/agent-harness allowlist, matching the other harnesses: !/calibre/, /calibre/*, /calibre/.*, and !/calibre/agent-harness/.

Third, the registry.json entry does not follow the current schema. It is missing source_url: null, uses contributor / contributor_url instead of the contributors array, and points skill_md at the packaged skill even though the PR also adds the canonical root skill. Please point it at skills/cli-anything-calibre/SKILL.md.

There is also trailing whitespace reported by git diff --check in AGENT_TEST_PROMPT.md and test_full_e2e.py. Once those are cleaned up, this will be much easier to review against the existing open Calibre PR.