feat(desktop): bundle the document-generation stack (ADR 0092 D1)

[mabry1985]

What

Bakes the document-generation stack (python-docx, openpyxl, python-pptx, reportlab; Pillow+lxml transitively) into the frozen desktop app, on by default — so the knowledge-work surface actually produces files on desktop.

This is Track 1a of the cowork-docs initiative and ships ADR 0092.

Why

ADR 0058 D2 refuses any plugin whose requires_pip isn't importable in the read-only bundle, with "install it on a server/Docker build instead." Real hits:

• cowork (knowledge-work skill pack) declares the 4 doc libs as hard deps → the whole plugin is refused on desktop, so its docx/xlsx/pptx/pdf skills can't produce a file.
• protobanana is refused over pillow>=10.

For the "own your stack" demographic (migrating off Claude Cowork / OpenAI Codex to a local-first agent), "the desktop app can't make a .docx" is a credibility gap, not an edge case. cowork is a first-party flagship, so it gets a platform answer.

How

• apps/desktop/sidecar/requirements-docs.txt (committed) — installed in the desktop-build CI sidecar step.
• DOC_COLLECT_ALL in build_sidecar.py — find_spec-guarded exactly like the Google OPTIONAL_COLLECT_ALL tier, so a lean local freeze without the extra still succeeds. --collect-all (not bare hidden-imports) is required: reportlab ships font/AFM data and python-docx/pptx ship their default templates as package data that an import-scan misses.

Effect: once the libs are importable, _deps_satisfied short-circuits and cowork's hard requires_pip is simply satisfied — cowork installs and works on desktop with zero manifest change, and protobanana's pillow refusal disappears.

This expands 0058's bundle baseline; it does not ship pip — libs are baked at build time (0058's sanctioned mechanism, same as the plugins/ tree + Google libs).

Not in this PR (specced in ADR 0092, follow-ups in-track)

• D2 — a binary "download artifact" tier in the artifact plugin (bytes + mime + derived text preview → versioned, diffable, download card).
• D3 — an explicit save_file_artifact(path, title) tool cowork's skills call so outputs become versioned artifacts.
• ADR 0093 (separate track) — the general pip-less wheel installer for any plugin's unbundled deps (plugins: opt-in to install non-bundled requires_pip deps in the frozen desktop app #1631 Scope A).

Test / verify

• ruff ✅, docs-nav --check ✅ (ADR 0092 in nav), tests/test_mcp_routes.py + tests/test_bundled_config_assets.py ✅ (the two suites that touch build_sidecar.py).
• True verification needs the desktop-build workflow — CI can only simulate the frozen path locally. Follow-up: extend scripts/live_smoke.py --bin to assert import docx, openpyxl, pptx, reportlab in the actual frozen binary.
• ⚠️ Watch the desktop-build job for bundle-size delta (~15–25 MB expected) and per-platform wheel availability (all four ship mac arm64/x86_64 + Windows wheels).

Refs #1631, #1953

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@mabry1985, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 45 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: f8a1a83b-c90b-406c-94f7-639e143a2395

📥 Commits

Reviewing files that changed from the base of the PR and between b080884 and 0c599dd.

📒 Files selected for processing (5)

• .github/workflows/desktop-build.yml
• apps/desktop/sidecar/build_sidecar.py
• apps/desktop/sidecar/requirements-docs.txt
• docs/adr/0092-desktop-document-baseline-and-versioned-file-artifacts.md
• plugins/docs/nav.json

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/bundle-doc-stack

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[protoreview]

QA panel review — PASS

code-review-structural · head ff28641f847a · formal

[review-synthesizer completed: workflow code-review-structural:report]

Prose Brief

Overall risk: Low. The change adds six document-format packages (python-docx, openpyxl, python-pptx, reportlab, lxml, Pillow) to the sidecar build, gated behind the same find_spec → skip-with-note pattern already used by the Google tier. Missing packages silently degrade without hard errors. CI now installs requirements-docs.txt before the sidecar build, and the ADR + nav entries are mechanically consistent. No refuted claims; all finder assertions about refactoring equivalence, import-name correctness, CI ordering, and local-dev resilience were verified as SUPPORTED.

Fix-first item: None urgent. The one UNCERTAIN item — whether _importable in the installer correctly resolves distribution-name → import-name mismatches (e.g., python-docx → docx) under --collect-all — is pre-existing (same pattern as the Google tier) and would be caught by a sidecar smoke test. A follow-up smoke-test run is the pragmatic next step before merging.

Panel disagreements: None. All finder claims converged; the verifier confirmed every substantive claim.

What verification changed: The verifier elevated no new blocker/major/minor findings. The _importable metadata-fallback uncertainty (pre-existing, not introduced by this diff) is reported below as a nit for visibility.

Gaps: The structural-analysis pass (code-review-structural:verify) completed and its concerns were folded into the verification table. No structural pass was skipped. Coverage note: build_sidecar.py was the most-changed production file; the refactoring there is mechanically sound, and the only residual concern is the cross-file _importable interaction below.

[
  {
    "file": "apps/desktop/sidecar/build_sidecar.py",
    "line": 0,
    "severity": "nit",
    "category": "cross-file",
    "claim": "Installer `_importable` metadata fallback may produce false negatives for packages where the import name differs from the distribution name (e.g., `python-docx` → `docx`). The `find_spec` fallback calls `pkg.replace('-', '_')`, yielding `python_docx` rather than `docx`; if PyInstaller's `--collect-all docx` does not also collect `python_docx-*.dist-info` metadata, `_importable('python-docx')` could return False despite the package being collected. Same pre-existing pattern as the Google tier — not introduced by this diff.",
    "evidence": "The diff adds `'docx': 'python-docx'` (and analogous `pptx`/`PIL` mappings) to `DOC_COLLECT_ALL` in `build_sidecar.py`. The installer's `_importable` function resolves `python-docx` via `importlib.metadata.version('python-docx')` → fallback `find_spec('python_docx')`, which does not match the actual module name `docx`. Identical pattern exists for `google-cloud-*` packages in the pre-existing Google tier.",
    "verdict": "uncertain",
    "note": "`_importable('python-docx')` tries `md.version('python-docx')` then `find_spec('python_docx')`. The fallback uses `pkg.replace('-','_')` — for `python-docx`→`python_docx` (not `docx`), `python-pptx`→`python_pptx` (not `pptx`), `Pillow`→`Pillow` (not `PIL`). Whether `--collect-all docx` also collects `python_docx-*.dist-info` depends on PyInstaller's distribution-name resolution. Smoke test would catch. Same pattern as pre-existing Google tier — not a new-introduced defect."
  }
]

[protoreview]

Promoting the PASS verdict for head ff28641f847a: all checks terminal-green, zero unresolved review threads. (approve-on-green)

[mabry1985]

Good catch on the _importable metadata nit — it's uncertain and load-bearing (if it false-negatives, cowork stays refused even with the libs bundled), so I made it deterministic in 0c599dd rather than rely on PyInstaller's collect-all metadata behavior:

DOC_COLLECT_ALL now carries (import_name, distribution_name), and the build emits --copy-metadata <dist> alongside --collect-all <import> for each. So importlib.metadata.version("python-docx") — the first thing installer._importable checks — resolves in the frozen app regardless of whether --collect-all docx happened to pull the python_docx-*.dist-info. That closes the exact dist≠import cases (python-docx→docx, python-pptx→pptx, Pillow→PIL).

Also updated ADR 0092's verification note so the follow-up frozen smoke asserts both import docx… and importlib.metadata.version("python-docx") (the latter is what the gate actually checks) — the real proof still needs the desktop-build run, as you noted.

[protoreview]

QA panel review — PASS

code-review-structural · head 0c599ddf1b24 · formal

[review-synthesizer completed: workflow code-review-structural:report]

I don't have the findings to synthesize — your message appears to have been cut off after the verifier status note and the setup.py mention. The actual annotated findings array that the verifier produced (even if partial) isn't present in what reached me.

Could you re-supply the verifier-annotated findings? I need the JSON array (or arrays) from the finder panel, each with at minimum file, line, severity, claim, evidence, and whatever verdict / note fields the verifier attached. Once I have that, I can dedup, re-grade, drop the refuted, carry verdicts forward, and produce the brief + canonical fenced JSON.

[protoreview]

Promoting the PASS verdict for head 0c599ddf1b24: all checks terminal-green, zero unresolved review threads. (approve-on-green)