npm install fails (macOS apple silicon, latest v26)

[nullfx]

appears you may need to add a process.arch: in there for x64 and arm64 on the latest macOSs

steve@Steves-MacBook-Pro:~$ npm install -g @tobilu/qmd
npm warn deprecated prebuild-install@7.1.3: No longer maintained. Please contact the author of the relevant native addon; alternatives are available.
npm error code 1
npm error path /usr/local/lib/node_modules/@tobilu/qmd/node_modules/node-llama-cpp
npm error command failed
npm error command sh -c node ./dist/cli/cli.js postinstall
npm error [node-llama-cpp] llama.cpp is not supported under Rosetta on Apple Silicone Macs. Ensure that you're using a native arm64 node.js installation.
npm error [node-llama-cpp] process.platform: darwin, process.arch: x64
npm error [node-llama-cpp] troubleshooting: https://node-llama-cpp.withcat.ai/guide/troubleshooting#illegal-hardware-instruction
npm error A complete log of this run can be found in: /Users/steve/.npm/_logs/2026-06-02T01_02_44_581Z-debug-0.log
steve@Steves-MacBook-Pro:~$ cd tmp/qmd
steve@Steves-MacBook-Pro:~/tmp/qmd$ npm install
npm warn deprecated prebuild-install@7.1.3: No longer maintained. Please contact the author of the relevant native addon; alternatives are available.
npm error code 1
npm error path /Users/steve/tmp/qmd/node_modules/node-llama-cpp
npm error command failed
npm error command sh -c node ./dist/cli/cli.js postinstall
npm error [node-llama-cpp] llama.cpp is not supported under Rosetta on Apple Silicone Macs. Ensure that you're using a native arm64 node.js installation.
npm error [node-llama-cpp] process.platform: darwin, process.arch: x64
npm error [node-llama-cpp] troubleshooting: https://node-llama-cpp.withcat.ai/guide/troubleshooting#illegal-hardware-instruction
npm error A complete log of this run can be found in: /Users/steve/.npm/_logs/2026-06-02T01_03_06_928Z-debug-0.log
steve@Steves-MacBook-Pro:~/tmp/qmd$ sw_vers
ProductName:		macOS
ProductVersion:		26.6
BuildVersion:		25G5028f

[tobi]

Decision: make node-llama-cpp an optional dependency with graceful degradation

After reviewing the three options, option (b) is the right fix.

Why not the others

• (a) Arch detection in qmd doctor: Doctor can't run if npm install already aborted. Useful as a secondary check but doesn't fix the root cause. We'll add it anyway as a bonus.
• (c) Docs-only: Leaves users stranded with a bare npm error code 1 and zero path forward without reading docs. Not good enough.

Chosen approach: optionalDependencies + graceful degradation

Exact mechanism:

1. Move node-llama-cpp from dependencies → optionalDependencies in package.json. npm/pnpm treat optional postinstall failures as non-fatal — the package installs successfully even if node-llama-cpp's own postinstall aborts.

2. In src/llm.ts, wrap the loadNodeLlamaCpp() dynamic import in a try/catch that returns null when the module fails to load (absent or errored postinstall).

3. In callers that need LLM (embed, query w/ expansion/reranking, vsearch, pull): throw a clear, actionable error:

   node-llama-cpp is not available (postinstall failed — likely Rosetta/x64 Node on Apple Silicon). Install a native arm64 Node from nodejs.org and reinstall: npm install -g @tobilu/qmd

4. Add a qmd doctor arch check: if process.platform === 'darwin' && process.arch === 'x64', emit a warning pointing users to native arm64 Node.

No-llama path behavior (explicit contract)

After this change, the CLI installs and these commands work without node-llama-cpp:

• qmd search (BM25/FTS)
• qmd ls, qmd get, qmd multi-get
• qmd collection add/list/remove/rename
• qmd context add/list/check/rm
• qmd status, qmd doctor
• qmd mcp (BM25 search tools work; LLM tools fail gracefully per-call)
• qmd update (re-indexing without embedding)

These commands fail with a clear error (not a crash) when node-llama-cpp is absent:

• qmd embed
• qmd query (uses LLM expansion/reranking by default — fallback to qmd search is documented)
• qmd vsearch
• qmd pull

llama backend: optional, not required

The LLM backend becomes explicitly optional. The CLI is fully functional for keyword search and document retrieval without it. LLM-backed paths (embedding, vector search, query expansion, reranking) require a native-arch Node installation.

Note on #448 (Intel Mac x64)

This is a separate bug — install succeeds on Intel but the arm64 Metal binary gets loaded at runtime. The graceful-degradation wrapper in llm.ts will at least prevent a hard crash for commands that don't need LLM (e.g. qmd search will work even if the native module fails on load), but the root cause of the wrong binary loading needs a separate fix.