fix(word-addin): harden the local dev experience against its three silent traps
WHY THIS MATTERS A cloner's first hour with the add-in is dominated not by the code but by three failure modes that give no useful error. All three were hit in real use on a machine that had run the add-in before; each now either self-heals or is documented with its exact recovery. TRAP 1 - CERTIFICATE TRUST DRIFT (the nastiest) The dev certificate expires after ~30 days, and the tooling silently regenerates it WITH A NEW SIGNING CA (the webpack dev server triggers this on startup). The OS keychain still trusts only the old CA, so desktop Word rejects the pane with an opaque "content is blocked because it isn't signed by a valid security certificate" - while `office-addin-dev-certs verify` reports "trusted", because it only checks that a CA *by that name* exists, not that it signed the current cert. Worse, `install` then refuses to reinstall for the same reason. Fix: scripts/dev.sh now asks the OS for its verdict on the ACTUAL leaf (`security verify-cert -c localhost.crt -p ssl -s localhost` on macOS; tool fallback elsewhere). On drift it forces uninstall→install, falls back to trusting the current ca.crt directly, re-verifies, and exits non-zero with a README pointer instead of launching into a broken Word. README Troubleshooting documents the by-hand recovery. TRAP 2 - STALE SIDELOAD REGISTRATION office-addin-debugging registers the add-in by hard-linking manifest.xml into Word's wef folder; a crashed run leaves the link behind and the next `npm start` dies with an opaque EEXIST. New scripts/clear-sideload.js runs as the npm `prestart` hook: best-effort deregistration before every start, cross-platform, and deliberately never fails (a broken stop must not block start - start surfaces the more actionable error). TRAP 3 - WORD ON THE WEB LOADS NOTHING, SILENTLY Word online's editor frame is a public origin; Chrome's Local Network Access checks block it from iframing https://localhost:3000 with no visible error - the pane simply never appears. Deployed add-ins are unaffected; dev sideloads are dead on arrival. New e2e-live/manual-session.mjs launches a browser with those checks disabled, reuses the persistent Microsoft profile, sideloads the manifest, opens the pane, and hands the window over for manual testing. The README's Word-on-the-web section now leads with this caveat. ALSO IN THE README - Prerequisites now state up front that a Mike user account and a funded LLM key (or the keyless stand-in) are needed - previously discovered only at first sign-in / first chat. - New "Testing without an LLM key" section documents e2e-live/anthropic-stub.mjs: a local server speaking the Anthropic streaming protocol with scripted answers, so the full real stack (Supabase auth, backend, SSE, Word tracked changes) runs without any API spend. - Troubleshooting gains entries for the EEXIST trap and the port-3000 collision with the web app's dev server.
| Repository | open-legal-products/mike |
|---|---|
| Author | Amalanand Muthukumaran <mamalanand3@gmail.com> |
| Authored | |
| Committed | |
| Parents | b29a8583 |
| Stats | 5 files changed , +230 , -9 |
| Part of | Add a Word add-in for chat and tracked rewrites |
Capture this commit into my fork
Download a Markdown prompt that tells Claude how to port this
exact commit into your working tree. Run it via
claude -p < capture-commit-08f53486.md
from inside the repo you want the change in.