[Bug] Bundle the correct pinned OfficeCLI per desktop target

[Astro-Han]

What task are you trying to do?

As a PawWork user, I want Word, Excel, and PowerPoint file handling to use the intended bundled OfficeCLI version, so document workflows keep improving as OfficeCLI ships fixes and new capabilities. This matters more as #100 makes file attach route more Office files into the local document-processing path, and it also connects to the longer-term #30 direction where OfficeCLI should become a first-party desktop plugin instead of an implicit bundled binary.

What do you do today?

Today packages/desktop-electron/resources/tools/officecli is a tracked binary bundled into the desktop app through electron-builder.config.ts. The download helper points at the latest OfficeCLI release asset, but packages/desktop-electron/scripts/download-tools.ts skips the download whenever the binary already exists. predev and prebuild do not refresh it.

On 2026-04-21, local verification found the checked-in macOS arm64 binary was 1.0.45, while the latest upstream release was v1.0.53, published on 2026-04-19. Running officecli --version locally can also self-update the binary in place, which dirties the git worktree without an intentional PawWork change.

What would a good result look like?

PawWork should make bundled OfficeCLI versioning explicit and release-safe.

A good near-term result:

• Decide the intended OfficeCLI version for each PawWork desktop release.
• Refresh the bundled binary intentionally during release prep, rather than depending on ad hoc local self-update behavior.
• Add a check that reports the bundled OfficeCLI version and fails or warns when it does not match the expected release version.
• Avoid dirtying the repo during ordinary verification, for example by documenting or enforcing OFFICECLI_SKIP_UPDATE=1 when checking the bundled binary.
• Keep this scoped to the current bundled-tool model.

A good longer-term result, connected to #30:

• Treat OfficeCLI as a first-party desktop plugin with explicit install, update, enable, and version state.
• The plugin-management UI should eventually own OfficeCLI visibility and upgrades, instead of hiding it as a silent resource under resources/tools.

Which audience does this matter to most?

Both

Extra context

Related issues:

• [Feature] Unified file attach that routes to vision, workspace, or reject based on model capability #100, unified file attach will route Office files into the local document-processing path more often.
• [Feature] Plugin management GUI in the desktop app #30, plugin management GUI is the likely long-term home for first-party tools such as OfficeCLI.

Current code pointers:

• Bundled binary: packages/desktop-electron/resources/tools/officecli
• Bundle config: packages/desktop-electron/electron-builder.config.ts
• Download helper: packages/desktop-electron/scripts/download-tools.ts
• Desktop prebuild path: packages/desktop-electron/scripts/prebuild.ts
• Desktop predev path: packages/desktop-electron/scripts/predev.ts
• Document skill: skills/document-processing/SKILL.md

[Astro-Han]

Additional finding from packaged-tool verification on 2026-04-29: this is more urgent than a version-governance enhancement because the current bundled-tool pipeline appears cross-platform unsafe.

Verified locally on macOS arm64: packages/desktop-electron/resources/tools/officecli is executable, officecli --help works, PATH injection via process.resourcesPath/tools works, and an unpacked macOS app contains Contents/Resources/tools/officecli that can create/view a .docx. So macOS arm64 is not broken in the same way the old built-in trash tool surface was.

However, the repository currently tracks only packages/desktop-electron/resources/tools/officecli, and that file is a macOS arm64 Mach-O binary. There is no tracked officecli.exe, and neither .github/workflows/build.yml nor .github/workflows/desktop-smoke.yml calls packages/desktop-electron/scripts/download-tools.ts before packaging. The Electron Builder config copies resources/tools/ wholesale into every package. That means the Windows release path likely packages the macOS binary instead of the Windows OfficeCLI executable.

Recommended acceptance criteria for this issue now include: download or materialize OfficeCLI per target platform/arch before packaging; ensure Windows packages include Resources/tools/officecli.exe; ensure macOS x64 packages do not receive the arm64 binary; pin or explicitly record the intended OfficeCLI version instead of relying on GitHub latest; and add package smoke checks that verify the bundled OfficeCLI exists, matches the target platform/arch, runs --version, and can perform a minimal create/view operation where practical.

[Astro-Han]

Design direction for #106

This issue should be treated as a release-safety and third-party attribution fix, not only as a version-governance enhancement.

Decisions

OfficeCLI is a PawWork desktop bundled third-party tool. It is not a user-installed dependency, not an npm dependency, and not yet part of the future plugin-management surface. PawWork desktop owns how the binary is selected, downloaded, verified, packaged, and credited.

PawWork releases must use an explicitly pinned OfficeCLI version. Release packaging must not download latest. A future follow-up can automate checking upstream OfficeCLI releases and opening a PR to bump the pinned version, but the release workflow itself must only consume the version declared in the repo.

The pinned OfficeCLI version and asset mapping should live in a small bundled-tool manifest, for example packages/desktop-electron/bundled-tools.json. This manifest should be the single source of truth for the OfficeCLI version and target asset names.

PawWork should not track platform OfficeCLI binaries in git. packages/desktop-electron/resources/tools/ should remain a generated local or packaging directory. The currently tracked macOS arm64 resources/tools/officecli should be removed so Windows and macOS x64 packages cannot accidentally inherit the wrong binary.

Before packaging, the desktop build should download the pinned OfficeCLI asset for the selected target platform and architecture, verify it against upstream SHA256SUMS, set executable permissions where needed, and fail the build if the asset cannot be verified.

Bundled OfficeCLI should not self-update in place inside the PawWork app bundle or install directory. PawWork should set OFFICECLI_SKIP_UPDATE=1 for agent shell commands so the bundled binary remains the version that the PawWork release declared and packaged.

PawWork should credit OfficeCLI as a third-party Apache-2.0 open-source project by iOfficeAI. README credit should be lightweight and include thanks. The binary distribution should include a full third-party license attribution, for example via THIRD_PARTY_NOTICES.md packaged into app resources.

This issue should not add a product UI for third-party licenses. If PawWork later needs an About or Third-party licenses page, that should be a separate issue.

Acceptance criteria

• packages/desktop-electron/resources/tools/officecli is no longer tracked as a platform binary.
• A bundled-tool manifest pins the OfficeCLI version and maps supported target assets.
• The release and desktop smoke packaging paths prepare OfficeCLI for the selected target platform and architecture before electron-builder runs.
• Packaging never uses OfficeCLI latest.
• Downloaded OfficeCLI assets are verified against SHA256SUMS.
• Windows x64 packages receive officecli.exe, not the macOS officecli binary.
• macOS arm64 and macOS x64 packages receive the matching macOS binary for their architecture.
• Package checks verify the bundled OfficeCLI file exists, has the expected name, has the expected architecture where practical, and reports the pinned version with OFFICECLI_SKIP_UPDATE=1.
• PawWork agent shell commands set OFFICECLI_SKIP_UPDATE=1 so the bundled binary does not update itself in place.
• THIRD_PARTY_NOTICES.md includes OfficeCLI attribution and the Apache-2.0 license text.
• The desktop package includes THIRD_PARTY_NOTICES.md in app resources.
• README.md and README_CN.md lightly credit OfficeCLI and thank iOfficeAI.

Non-goals

• Do not build a plugin-management UI.
• Do not add an in-product third-party licenses page.
• Do not implement automatic OfficeCLI upgrades for end users.
• Do not add an OfficeCLI bump workflow in this PR.
• Do not govern every bundled tool in this PR; keep the implementation scoped to OfficeCLI.

Follow-up issue

Open a separate follow-up for an OfficeCLI bump workflow. The workflow can periodically or manually check iOfficeAI/OfficeCLI releases, compare the latest release with PawWork's pinned manifest version, update the manifest when needed, run the bundled-tool verification, and open a PR such as chore: bump bundled OfficeCLI to vX.Y.Z.