[codetalcott]

Two commits, reviewable separately. The second can be dropped without affecting the first.

1. feat(cli): -I library include roots for build and run

napi-mojo build and run passed exactly one -I (the framework's), so nothing built through the CLI could import another Mojo library.

• -I <dir> is now repeatable on both commands.
• Library roots always go to the compiler after the framework root. Mojo takes the first root holding a package of the imported name, silently, so a library placed first could replace napi.
• Refused with exit 1:
  • a root that is missing or not a directory;
  • the framework root passed again, or any root given twice;
  • a root holding its own napi (directory, .mojopkg or .mojoc).
• Warned: a root that is itself a package, since -I wants its parent directory.

run's build cache now hashes every root, in order. Writing those tests showed the cache was already incomplete:

• its walk skipped symlinked directories;
• it hashed only .mojo files.

So a library symlinked beside the entry (the obvious workaround before -I) kept serving the old binary after every edit behind the link. The walk now:

• follows symlinks, with a realpath cycle guard;
• also hashes .🔥, .mojopkg and .mojoc;
• skips node_modules.

The compiler's version is still not in the key. CLAUDE.md now says so instead of calling the input set complete.

Tests

• tests/cli.test.js: 19 new tests drive the CLI with a stub compiler passed via --mojo, which records each compile. Root order and every cache decision are tested without a Mojo toolchain.
• Each rule was reverted once and its test failed, 15 of 15. The entry-tree symlink test also fails on main as it stands.
• New step in the required test job, "Host-mode program with library include roots", does a real compile:
  • an import resolved through -I;
  • a cache hit;
  • an edit reaching the next run, both through the root and through a symlink beside the entry.

2. examples: m0-session, an existing Mojo library compiled through -I

m0 is mojo-http's application framework, and its wheel ships the framework's Mojo source. examples/m0-session/lib.mojo compiles m0's session and grant code, unchanged, into an addon with napi-mojo build -I <wheel>/m0/_mojo. A Node service beside an m0 app can then check m0 cookies and stream grants with m0's own code. m0 0.2.0 and the framework compile together on Mojo 1.1.0, --Werror-clean, in about 9 s.

parity.mjs runs under node --test and is named so Jest never collects it. It judges the addon against an issuer written on node:crypto, after first proving that issuer reproduces mojo-http's pinned vectors. It checks:

• those pinned vectors;
• 300 seeded random grants and sessions with non-ASCII keys and cookies, with issueSession byte-equal to the oracle;
• every refusal class, and m0's refusal messages compared whole;
• that text crosses as its UTF-8 bytes: a string past 256 bytes, an embedded NUL, a lone surrogate.

Eight reverted rules each fail it: three on the oracle side, five on the addon side. A build without the -I root fails naming m0_core.

The new m0-interop job is non-required and PR-only, like runtimes.

• It downloads the wheel from PyPI at a pinned M0_VERSION, so neither repo gains a build-time dependency on the other.
• Before compiling, it checks the wheel's gated_mojo against mojo --version, so a drifted pin fails with a message instead of a compile error.

The example ships in the npm package as a template, minus its build output (!examples/m0-session/build). Deviation from the plan: the hash exports take strings, not a Uint8Array. m0_core's public fnv1a/xxhash32 take String; the byte-pointer forms are underscore-private.

Checked locally (Linux, pinned pixi toolchain)

• build.sh; npm test: 835 passed, 12 skipped.
• The new required step's script: 4 compiles, 21 s.
• Every run: block of the new m0-interop job, taken from the YAML: all pass. Its mismatch branch exits 1 with its message.
• check-doc-samples, generate-rules-extract --check, sync-versions --check, generate-api-reference --check (in pixi).
• npm pack --dry-run ships examples/m0-session/{lib.mojo,parity.mjs,README.md} only.

Not checked locally: macOS. CI's required macOS job covers the stub tests and the new e2e step.

🤖 Generated with Claude Code

https://claude.ai/code/session_013tXV7MkRfP97g5hPfNNXHC

---

Generated by Claude Code