fix(word-addin): harden the local dev experience against its three silent traps

↗ view on GitHub · Amalanand Muthukumaran · 2026-08-03 · 08f53486

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.

⬇ Download capture-commit-08f53486.md