CLI name collision: `mex` conflicts with TeX Live's mex binary on macOS

[theDakshJaitly]

Describe the bug
On macOS machines with TeX Live installed, command -v mex resolves to TeX Live's mex binary instead of our CLI. The lookup returns cleanly - but for the wrong program. Any setup step, doc, or script that checks for mex by name can pass while mex-agent isn't actually installed or runnable, and users can invoke the wrong binary without an obvious error. Reported by Jang Young Jeong (@akillness) in a hands-on audit: https://akillness.github.io/posts/mex-macos-command-collision/

To Reproduce

1. On macOS with TeX Live installed, run command -v mex
2. It resolves to the TeX Live binary, not mex-agent
3. Install/verify steps that check mex by name pass incorrectly

Expected behavior
Install verification and docs should verify capability (the resolved binary actually responds as mex-agent, e.g. via mex --version signature), not just the name - or at minimum detect the collision and warn with the exact path conflict.

Command output
See the audit above for the reporter's exact output and his capability-check wrapper.

Environment

• mex version: 0.7.1 runtime (0.8.2 source inspected separately in the audit)
• Node.js version: see audit
• OS: macOS with TeX Live installed
• Install method: npm global

Additional context
Possible directions (open to discussion): collision detection + warning at install/first run; capability-based verification in setup and docs; README troubleshooting entry (alias / PATH ordering / wrapper); longer-term evaluation of the CLI name or an alternate alias (breaking-change territory, separate discussion). The same audit flags two other things worth their own issues if confirmed: a stale graph line-range until clean rebuild, and mex-mcp source present with no published npm package. Thanks @akillness for the careful writeup.

[akillness]

Thank you for opening this and for incorporating my feedback so thoughtfully. I really appreciate it.

[theDakshJaitly]

appreciate that man - your audit was genuinely the most thorough external look anyone's given mex. the capability-over-name point reframed how we're thinking about install verification, not just this collision.

if you're up for it, come hang in the discord - people who actually stress-test things are exactly who we want in there: https://discord.gg/FEdNsQ4Qt4

[nitesh32]

Hi @theDakshJaitly , I'd like to work on this. Can you assign it to me?

I found two places where the code only checks the name mex, so it can pick up TeX's mex by mistake:

setup.sh: if any mex exists, it uses it. With TeX installed, setup runs the wrong program.
src/watch.ts: the git hook falls back to npx mex, which may not run our package. It should be npx mex-agent.

My plan:

In setup.sh, confirm it's really our CLI by running mex capabilities --json. If that fails, show a warning and use the local build instead.
In watch.ts, change npx mex to npx mex-agent, and add a test.
Add a short note to the README on how to fix the TeX clash.

I won't rename the CLI. Does this plan sound good?

[theDakshJaitly]

yeah sure @nitesh32 pls drop a PR

[nitesh32]

PR is up: #262. setup.sh and sync.sh now verify mex capabilities --json before using a mex on PATH, and the watch hook falls back to npx mex-agent. I left the README note and CHANGELOG out to keep it small, so happy to add them if you want.