From a47ef836815cea51479e4ef05e63d245310b1ca7 Mon Sep 17 00:00:00 2001 From: choiyounggi <74581798+choiyounggi@users.noreply.github.com> Date: Mon, 28 Sep 2026 10:39:45 +0900 Subject: [PATCH] knowledge: ingest 1 verified insight (bun native addon without its .node: blocked vs failed lifecycle script) --- .dev-loop/INGEST_REPORT.md | 246 ++++++++---------- INDEX.md | 2 +- log.md | 2 + wiki/platforms/environment/path-resolution.md | 2 +- wiki/platforms/index.md | 1 + .../toolchains/compiler-sysroot-on-macos.md | 2 +- ...-addon-binary-missing-after-bun-install.md | 90 +++++++ .../toolchains/version-management.md | 2 +- .../tools/plugin-mcp-server-registration.md | 2 +- wiki/security/dependencies/supply-chain.md | 2 +- 10 files changed, 210 insertions(+), 141 deletions(-) create mode 100644 wiki/platforms/toolchains/native-addon-binary-missing-after-bun-install.md diff --git a/.dev-loop/INGEST_REPORT.md b/.dev-loop/INGEST_REPORT.md index 939e9fb..ae5aea7 100644 --- a/.dev-loop/INGEST_REPORT.md +++ b/.dev-loop/INGEST_REPORT.md @@ -1,149 +1,125 @@ -# Knowledge ingest — WebMCP as the development standard: 2 pages re-verified, 2 new pages, routing widened +# Knowledge flush — 1 insight (1 new page; 7 plan-gap rows retired as local-layer candidates) -Trigger: a Korean WebMCP explainer video (2026-09) pasted for evaluation. Its own content -(declarative vs imperative API, shared page logic, token savings vs browser agents) was already -covered by the two pages ingested 2026-08-18; adoption advocacy and proposal history were again -left out. Verifying the video's claims against primary sources found the wiki a month behind its -sources; the owner then decided (2026-09-28) that the additive WebMCP tool layer is the -development standard for web UI work, QA, and bug fixes, which changes routing. +Run id `20260928-103002-67743` (auto-flush child; lock inherited via `DEV_LOOP_FLUSH_RUN_ID`). +Claimed 8 queue rows: `27c34a17ce1d6612` (bun native addon) and 7 `plan-gaps` rows for the +`dace` Android repo (`30c9b935faa64ba8`, `639657eea8ef0550`, `2b1e21589c1987ea`, +`a81012fb435b7e21`, `79f42a83701cab51`, `86a1fcda7460b479`, `3deebdb303656afe`). ## Verified best-practice -### 1. `consequentialHint` / `debugging` annotations, ChatGPT site-tools constraints, DevTools pane → **verified** - -- https://webmachinelearning.github.io/webmcp/ — Draft Community Group Report dated 2026-09-26; - IDL `partial interface Document { readonly attribute ModelContext modelContext }` (Document - only); `dictionary ToolAnnotations { readOnlyHint, untrustedContentHint, consequentialHint, - debugging }`; no user-confirmation primitive defined. (fetched 2026-09-28) -- https://developer.chrome.com/docs/ai/webmcp/imperative-api — page dated 2026-09-21; - `document.modelContext.registerTool({ name, description, inputSchema, execute, annotations }, - { signal, exposedTo })`; `consequentialHint` "allows agents and browsers to enforce mandatory - user confirmation prompts before executing high-stakes tools"; `debugging` Chrome 156+; no - `requestUserInteraction` mention (the security page's old note on it was removed). -- https://developer.chrome.com/docs/devtools/application/webmcp — page dated 2026-05-12; the - WebMCP pane is in the Application panel; Available Tools (name, description, invocation count), - Invoked Tools (status, input, output), Run tool with manual parameters, schema-mismatch errors - in the output pane. -- https://learn.chatgpt.com/docs/webmcp — "Site tools are ChatGPT's implementation of the - proposed WebMCP standard"; feature-detects `document.modelContext.registerTool`; declarative - API and iframe registrations unsupported; "Each tool invocation receives a safety review before - it runs"; GPT-5.6 Sol / GPT-6 Sol only, Luna disabled; desktop app; not in Enterprise/Edu; - surfaces: built-in browser, ChatGPT Work, Codex; user toggle under Settings → Browser → - Permissions. (help.openai.com's site-tools article was dropped as a source: it returns 403 to - fetchers, so its claims could not be verified.) -- https://developer.chrome.com/docs/ai/webmcp/secure-tools — page dated 2026-09-01; budgets - 30 / 500 / 150 / 1.5K. Contains no auth-state guidance, so the parity gate's both-auth-states - row is derived from security-agent-exposure-in-session-tool-exposure (PII via read tools, - server-side authz unchanged), not from this page. -- https://developer.chrome.com/docs/ai/webmcp — page dated 2026-08-07; origin trial from Chrome - 149; Model Context Tool Inspector extension; prompts go to `gemini-3-flash-preview`. - -### 2. WebMCP-as-standard routing (owner decision) → **policy, not a sourced claim** - -The widened triggers (any new or changed user action in a web UI) and the parity gate's -"every action has a tool unless on the exclusion list" are the owner's development standard, -stated as such in log.md. Every mechanical directive inside those pages is sourced as above. -The standard keeps the existing "human UI primary, tool layer additive" directive unchanged. +### 1. A native addon has no `.node` binary after `bun install` — `confidence: verified` + +**Harvested claim (row `27c34a17ce1d6612`):** a `bun install -g` CLI dies with "Could not +locate the bindings file" because bun skips lifecycle scripts for packages not in +`trustedDependencies`; remedy: run `prebuild-install` / `node-gyp rebuild` by hand or +reinstall with `--trust`. + +**Verification changed the claim.** The stated cause is refuted for the harvested case and +the page states the corrected mechanism: + +- `bun pm default-trusted` (bun 1.3.11, run in `~/.bun/install/global`) lists 367 packages and + **includes `better-sqlite3` (line 117) and `sqlite3`**; the upstream + `src/install/default-trusted-dependencies.txt` confirms both. `bun pm untrusted` in that + install root lists tree-sitter-* and node-llama-cpp as blocked but **not better-sqlite3**. + So bun ran its script; it was the `prebuild-install || node-gyp rebuild --release` chain + (better-sqlite3's own `package.json` install script) that produced no binary. +- Reproduction (scratch project under the seagrass `.claude/tmp/`, deleted afterwards): + a trusted `file:` dep whose install script exits 1 → `bun install` exits 1 with + `error: install script from "failing-dep" exited with 1`, leaves `build/Release/obj`, + writes no lockfile (`bun pm untrusted` → `error: Lockfile not found`). An unlisted dep → + exit 0 with `Blocked 1 postinstall. Run \`bun pm untrusted\` for details.`; `bun pm trust + blocked-dep` ran the script and wrote `trustedDependencies`. The "only obj dirs, no .node" + state in the harvested evidence matches the *failed* branch, not the *blocked* branch. +- Official docs checked (context7 `/oven-sh/bun` + WebFetch): https://bun.com/docs/pm/lifecycle + (default-secure allowlist; default list applies to npm sources only; `--ignore-scripts`), + https://bun.com/docs/pm/cli/pm (`untrusted` / `trust` / `default-trusted` / `ls --trusted`; + a set `trustedDependencies` **replaces** the default list), + https://bun.com/docs/guides/install/trusted (same replace-not-extend note), + https://github.com/nodejs/node-gyp#installation (Xcode CLT + supported Python; `--python`, + `npm_config_python`, `PYTHON`; `rebuild` = clean+configure+build). +- Field half kept as evidence in the page's Sources: the qmd MCP server (global bun install, + better-sqlite3 12.8.0, launcher `#!/bin/sh` → Node 26.7) had no prebuilt for that ABI; + `node-gyp rebuild --release --python=<3.11>` produced `better_sqlite3.node` and the server + connected (originating session transcript `d5eb45d9…`, `claude mcp list` output). +- Not substantiated and therefore left out: the harvested `--trust` remedy for a + default-listed package (it would re-run the same failing compile and, by writing + `trustedDependencies`, drop the rest of the default allowlist — recorded as an *Instead of* + row). + +### 2–8. Seven `plan-gaps` rows (t6b-calendar-trip-integration, repo `dace`) — not ingested + +Each directive names the dace repository's own types and files (`CalendarBarItem`, +`CalendarWeekSegmentLayout`, `CalendarViewModel`/`TripApi`, `MonthGridPanel`, +`CalendarWeekRow`, `PendingInAppRouteBox`, `AppContainer`, `MainTabScaffold`, `TripTabRoot`) +and would be wrong in any other codebase. Layer test (wiki-ingest step 3) → local layer; see +`## Local-layer candidates`. Their general residue is already covered: +`mobile/navigation/deep-links-and-entry-points` (pending-route ownership, cited by the rows +themselves) and `testing/mocking/what-to-mock`. ## Existing-layer check -Pages read: frontend-agent-interfaces-agent-facing-tool-surfaces, security-agent-exposure-in-session-tool-exposure, qa-process-release-gates, testing-strategy-differential-testing, testing-strategy-cross-layer-effect-tests, testing-strategy-failing-test-first +Pages read: platforms-toolchains-version-management, platforms-toolchains-compiler-sysroot-on-macos, platforms-environment-path-resolution, security-dependencies-supply-chain, platforms-tools-plugin-mcp-server-registration, qa-deliverables-documented-behavior-of-a-third-party-tool + +- Routing via `INDEX.md` → `wiki/platforms/index.md` (toolchains; also read shells/tools rows), + `wiki/infrastructure/index.md`, `wiki/backend/node/index.md`, `wiki/debugging/index.md`. +- Repo-wide grep for `bun|native addon|node-gyp|prebuild-install|lifecycle script|postinstall|trustedDependencies|bindings file` + across `wiki/` (no truncation): 3 files — `frontend/design/design-canvas-workflow.md` (bun as + a prerequisite only), `security/dependencies/supply-chain.md` (one directive: review + install scripts, allowlist them — same *principle*, no diagnostic/remedy), `qa/deliverables/ + documented-behavior-of-a-third-party-tool.md` (`npm ls -g` lookup only). No page covers the + blocked-vs-failed distinction, `bun pm untrusted/trust`, or the ABI/runtime rebuild. +- `wiki_search` (k=5) on the trigger sentence: qa-deliverables-documented-behavior-of-a-third-party-tool (0.75), + infrastructure-containers-image-builds ×4 (0.72–0.75) — none describes this situation, so + **created new**: `wiki/platforms/toolchains/native-addon-binary-missing-after-bun-install.md` + (id `platforms-toolchains-native-addon-binary-missing-after-bun-install`, 90 lines total). +- Conflicts: none. `security-dependencies-supply-chain` says "disable install scripts by + default and allowlist"; the new page is the downstream diagnostic when that allowlist (or a + failed script) leaves a native addon without its binary — complementary, linked both ways. +- Related links added both ways: platforms-toolchains-version-management, + platforms-toolchains-compiler-sysroot-on-macos (node-gyp compile on macOS), + platforms-environment-path-resolution (which `node` the launcher resolves), + security-dependencies-supply-chain, platforms-tools-plugin-mcp-server-registration (MCP + server dying at connect). +- Plumbing: `wiki/platforms/index.md` toolchains row; `INDEX.md` platforms route line + extended (no open PR rewrites that row — checked #223/#225/#226 diffs on `INDEX.md`); + `log.md` ingest entry. +- Lint: `node scripts/wiki-lint-prohibitions.js` — no finding on the new page; no banned + qualifiers in directive sentences. -Whole-wiki grep `webmcp|modelContext|toolname|agent-friendly|answer engine` → 7 files (the two -WebMCP pages, their two domain indexes, INDEX.md, log.md, platforms/tools/plugin-mcp-server- -registration which matches only on a modelcontextprotocol URL). skills/, hooks/, agents/, -templates/, AGENTS.md → 0 mentions. qa/testing/debugging indexes → no WebMCP routing line (the -one qa hit is the model-coupled-guidance-aging-detector page, unrelated). `wiki_search` was -unavailable (dev-loop-wiki MCP server failed to connect this session); the category pages were -read directly per the skill's fallback. - -Merge targets: both existing WebMCP pages were **revised in place** (same trigger, same -directive, newer sources) — no new page for that material. The two new pages have new triggers -(a release gate; a test strategy) that no existing qa/testing page covers: release-gates is the -generic checklist page and is linked, not extended; differential-testing / cross-layer-effect- -tests / failing-test-first are referenced from the testing page's edge cases. +## Open-PR check -Related links added both ways: qa-process-release-gates ↔ qa-process-agent-tool-parity-gate; -testing-strategy-cross-layer-effect-tests ↔ testing-strategy-agent-tool-shared-handler-tests; -frontend agent-facing-tool-surfaces and security in-session-tool-exposure ↔ both new pages. +Open `knowledge/*` heads (`gh pr list --state open --search "head:knowledge/"`): +#226 `knowledge/choiyounggi-20260928-092831`, #225 `knowledge/choiyounggi-20260928-082803`, +#223 `knowledge/choiyounggi-20260927-220735`. Each fetched and diffed against `origin/main` +under `wiki/` with the overlap grep above: -## Open-PR check +| Candidate | #226 | #225 | #223 | Verdict | +|-----------|------|------|------|---------| +| `27c34a17ce1d6612` bun native addon | 0 hits | 1 hit (`postinstall` in an unrelated Kotlin/Gradle page) | 1 hit (unrelated `bun` mention) | **new** | +| 7 dace plan-gap rows | — | — | — | not general; local-layer (see below), no wiki edit here | -`gh pr list --state open` (2026-09-28): one open PR, #223 (knowledge/choiyounggi-20260927-220735, -15 insights). Its file list contains none of the four WebMCP-related pages; the only overlap is -appended log.md entries (union merge). +#223 touches `wiki/platforms/index.md` (shells and tools rows) and `INDEX.md`; my edits are in +the toolchains table and the platforms route line, which none of the three PRs rewrite. ## Routing decision -- frontend/agent-interfaces/agent-facing-tool-surfaces — revised (owning artifact: the UI code). -- security/agent-exposure/in-session-tool-exposure — revised (confirmation gating). -- **qa/process/agent-tool-parity-gate** — new page in the existing `process` category beside - release-gates: it is a release-decision checklist for one surface, so it belongs where - release-gates and regression-scope live; no new category. -- **testing/strategy/agent-tool-shared-handler-tests** — new page in the existing `strategy` - category beside test-level-choice / cross-layer-effect-tests: it decides what to test and at - which level for a two-entry-point action; no new category. -- AGENTS.md routing step 7 — one row added (web UI user action → frontend agent-interfaces, - then the qa parity gate); tests/review-routing.bats pin 6 → 7 rows in the same commit. -- INDEX.md frontend / qa / testing route lines and the three domain indexes updated; log.md - gained two ingest entries and two revise entries. - -## Verification - -- `node scripts/wiki-lint-prohibitions.js wiki` → directives 79, violations 0 (pin unchanged). -- `node scripts/wiki-structure-checks.js wiki --layer bundled` → pages 353, findings 0. -- bats: tests/wiki-*.bats + tests/review-routing.bats + tests/orchestrate-review-pass.bats → - 273/273 ok (one earlier `Recall@5` flake re-ran green; baseline on an untouched HEAD worktree - measured the same 0.87). -- Body lines: frontend 110, security 76, qa 70, testing 66 (limit 120). - -## Independent review (before commit) - -- General reviewer (feature-dev:code-reviewer, fresh context): FAIL → 2 major + 4 minor, all - applied: `consequentialHint` scope aligned with the security page's class table; gate edge row - for a vanished runtime (human-UI release not blocked); logout added to the AbortSignal edge - row and the Registration test; step 2/3 of the testing page conditioned on imperative vs - declarative; AGENTS.md step-7 row admits the exclusion list; qa index clause matched to the - page trigger. -- Adversarial fact-checker (fresh context, every source re-fetched): 8/8 targeted claims - confirmed; FAIL on 2 unsupported sentences + 8 imprecisions, all applied: dropped the - `navigator.modelContext` history (no cited source has it); Run tool no longer claimed to write - Invoked Tools (that log is agent↔page); `consequentialHint` quote re-attributed (draft: "client - or agent"; Chrome: "agents and browsers"); secure-tools' stale `requestUserInteraction()` - mention recorded; `readOnlyHint` "requested" → "in its read-only example"; budgets labelled - as Chrome's recommendations applied as limits, parameter names included; cross-origin edge - row now names `allow="tools"` + `exposedTo` + `getTools({ fromOrigins })`; origin trial and - local flag separated; `SubmitEvent.agentInvoked` / `respondWith()` added to the declarative - test directive. - -## CI agent gate (run 36329841491) — blocker refuted, advisories applied - -- Blocker claimed the CG draft has no "client or agent … selectively enforce" language. Ground - truth (`curl -sL https://webmachinelearning.github.io/webmcp/`, 504,537 bytes, tags stripped, - 2026-09-28): the phrase occurs once, in §6 Security considerations under the mitigation for - "Misrepresentation of Intent": "A boolean consequentialHint annotation acts as a signal to the - client or agent that the tool performs a consequential action … This way they can selectively - enforce mandatory user confirmation prompts before executing high-stakes tools". The gate's - fetch read a truncated page. The page now names the section beside the quote. -- Advisory (chromestatus unverifiable from CI): confirmed via the JSON API — stage 150 - desktop/Android 149–156; Firefox and Safari "No signal". The source line now records the API - path. -- Advisory (Run tool vs Invoked Tools): Do 8 no longer implies manual runs are excluded from the - log; it states only what the DevTools page states. -- Advisory (cross-link gap): qa parity gate ↔ backend-common-api-design-agent-tool-granularity - linked both ways, with one sentence placing the parity table as the release-time reading of - that page's design-time capability map. - -## CI agent gate, second run (36330523418) — blocker applied, quote advisory stands - -- Blocker: the frontend page stated "the development standard is an additive WebMCP tool per - action" as unconditional fact under confidence: verified. Applied: the trigger, the frontend - domain description and load-when line, and the INDEX.md frontend row now condition on "this - wiki's development standard (owner decision, log.md 2026-09-28, a policy rather than a sourced - fact)". Routing width is unchanged; the sentence is a policy the wiki declares, not a claim about - the world. -- Advisory (§6 quote unverifiable from CI): the gate's fetch truncates before §6.3.2 and curl is - blocked in its sandbox; it records the quote as unverifiable, not refuted. Ground-truth grep is in - the PR comment; the two sources lines name the section. -- Advisory (duplication with test-level-choice's extract-and-wire edge row): linked both ways and - named in step 1 as the general rule applied to two entry points. +| Insight | Target | Why this category | +|---------|--------|-------------------| +| bun native addon without `.node` | `platforms/toolchains/native-addon-binary-missing-after-bun-install` (new page) | The fault sits between a package manager's script policy and a compiler toolchain (node-gyp, Python, Xcode CLT, runtime ABI) — the toolchains category already holds `compiler-sysroot-on-macos`, `version-management`, `environment-resync-removes-undeclared-packages`. Not `backend/node` (no application code) and not `security/dependencies` (that page owns the policy, not the diagnosis). No new category. | + +## Local-layer candidates + +Project `dace` (`/Users/choeyeong-gi/Desktop/workspace/linkly-calendar/dace`, task +t6b-calendar-trip-integration) — run `wiki-ingest` inside that project: + +| Row | Target | +|-----|--------| +| `30c9b935faa64ba8` CalendarBarItem sealed union + id prefixes | `wiki-local/mobile/presentation/calendar-bar-item-union.md` | +| `639657eea8ef0550` shared greedy lane layout over mixed bar items | `wiki-local/mobile/presentation/calendar-week-lane-layout.md` | +| `2b1e21589c1987ea` asymmetric error isolation for parallel events/trips fetch | `wiki-local/mobile/networking/calendar-parallel-fetch-error-isolation.md` | +| `a81012fb435b7e21` trip bar color/icon parity with iOS | `wiki-local/mobile/presentation/calendar-trip-bar-rendering.md` | +| `79f42a83701cab51` trip-bar tap routing (`onTripTap`, isCenter-only) | `wiki-local/mobile/navigation/calendar-trip-bar-tap-routing.md` | +| `86a1fcda7460b479` PendingInAppRouteBox owned by AppContainer | `wiki-local/mobile/navigation/pending-in-app-route-ownership.md` | +| `3deebdb303656afe` 5th tab index/icon + TripTabRoot stub consumption | `wiki-local/mobile/navigation/trip-tab-and-pending-route-consumption.md` | + +All 8 claimed rows are retired in the queue by this run (1 ingested, 7 local-layer). diff --git a/INDEX.md b/INDEX.md index e947472..0a0b685 100644 --- a/INDEX.md +++ b/INDEX.md @@ -19,7 +19,7 @@ follow the cross-pointers in their index or take the next matching seeded domain | [qa](wiki/qa/index.md) | **seeded** | Release-quality process: release gates, regression scoping, bug reports, severity/priority triage, evidence for completion claims, the agent-tool parity gate for a web UI release, acting on code-review feedback, adversarial review of high-risk diffs, exploratory testing (guarded-path coverage, override matrices), scope-purity gates, sourcing deliverable documents from generated artifacts, verifying the quantitative claims in a document before publishing it, a documented claim about a third-party tool's side effects, an obligation row in a tier/policy table that another contract also pins, rationale prose left behind by a config-value change, automated verification of document deliverables (spec/RFC gates), an aging detector for model-coupled agent guidance, capturing an app's own screen content without Screen Recording permission (writing automated test code → testing) | | [debugging](wiki/debugging/index.md) | **seeded** | Diagnosing a failure — finding what is wrong and why: reproducing, bisection, hypothesis testing, traces/logs, intermittent failures (fixing the diagnosed fault → its owning domain) | | [security](wiki/security/index.md) | **seeded** | Trust-boundary decisions: input validation, session-vs-token auth choice, per-resource authorization (IDOR), secrets hygiene (including ciphertext orphaned by a regenerated encryption key), dependency trust, PII handling, in-session agent tool exposure (prompt-injection blast radius), the author identity a commit publishes to a public repository, host-compromise triage / incident response (verifying assumed security agents, identifying masquerading processes) (XSS rendering → frontend; CI secrets → infrastructure; JWT implementation → backend/frontend auth) | -| [platforms](wiki/platforms/index.md) | **seeded** | OS-level differences breaking code across macOS/Linux/Windows: shell portability, BSD-vs-GNU CLI, filesystem case/line endings, Unicode normalization in text/file-name matching, commands inspected before execution, permission deny rules for bypass-mode agent workers, background services/cron, invoking prompt-capable CLIs non-interactively, toolchain version pinning | +| [platforms](wiki/platforms/index.md) | **seeded** | OS-level differences breaking code across macOS/Linux/Windows: shell portability, BSD-vs-GNU CLI, filesystem case/line endings, Unicode normalization in text/file-name matching, commands inspected before execution, permission deny rules for bypass-mode agent workers, background services/cron, invoking prompt-capable CLIs non-interactively, toolchain version pinning, a native addon left without its `.node` binary after a bun install (blocked vs failed lifecycle script) | | [mobile](wiki/mobile/index.md) | **seeded** | App-side iOS/Android/cross-platform: process death/state survival, offline-first sync, mobile-network calls, store rollout/hotfix strategy, startup time, modal presentation (several sheets/covers on one host, screen-level error sheets) | All ten domains are seeded. New categories grow via `skills/wiki-ingest/SKILL.md`. diff --git a/log.md b/log.md index 72b6053..7edfe18 100644 --- a/log.md +++ b/log.md @@ -208,3 +208,5 @@ Append-only. Format: `## [YYYY-MM-DD] " exited with 1` = script ran and failed → fix the node-gyp prerequisite and rebuild under the runtime the launcher uses); `bun pm untrusted` distinguishes the two after the fact; a set `trustedDependencies` replaces the default allowlist, so list default-listed packages too. diff --git a/wiki/platforms/environment/path-resolution.md b/wiki/platforms/environment/path-resolution.md index 2e12187..abc78b4 100644 --- a/wiki/platforms/environment/path-resolution.md +++ b/wiki/platforms/environment/path-resolution.md @@ -12,7 +12,7 @@ sources: - https://www.sudo.ws/docs/man/sudoers.man/ - https://docs.brew.sh/FAQ last_verified: 2026-09-03 -related: [platforms-toolchains-version-management, platforms-processes-background-services, platforms-shells-env-var-off-switches, platforms-toolchains-compiler-sysroot-on-macos, infrastructure-agent-orchestration-verify-command-in-a-worker-brief, infrastructure-agent-orchestration-gate-evidence-exit-code-class] +related: [platforms-toolchains-version-management, platforms-processes-background-services, platforms-shells-env-var-off-switches, platforms-toolchains-compiler-sysroot-on-macos, infrastructure-agent-orchestration-verify-command-in-a-worker-brief, infrastructure-agent-orchestration-gate-evidence-exit-code-class, platforms-toolchains-native-addon-binary-missing-after-bun-install] --- # The Wrong Binary (or None) Resolving From PATH diff --git a/wiki/platforms/index.md b/wiki/platforms/index.md index 557391b..c490002 100644 --- a/wiki/platforms/index.md +++ b/wiki/platforms/index.md @@ -76,6 +76,7 @@ Match your situation to a "load when" line; load only matching pages. | [environment-resync-removes-undeclared-packages](toolchains/environment-resync-removes-undeclared-packages.md) | A package that was working (pytest, ruff, a scratch library) vanished after an unrelated dependency change and imports fail across unrelated test files; adding or dropping a dependency while a long job/test run/experiment is in flight; deciding whether dev-only tools belong in a dependency group or an ad-hoc `pip install`; deciding whether a manager's command prunes packages absent from the lockfile (`uv add` vs `uv remove` vs `uv sync` vs `uv run` exactness) | | [regeneration-silently-drops-hand-edited-state](toolchains/regeneration-silently-drops-hand-edited-state.md) | A generator-owned file (XcodeGen's `.xcodeproj` regenerated from `project.yml`, or a similar codegen-plus-hand-edit setup) is about to be regenerated to make one small change; deciding whether to trust regenerated output before committing it; a GUI-added target, a shared scheme, or another hand-edit is missing after regeneration even though the build still succeeds | | [uv-state-directories-under-a-relocated-home](toolchains/uv-state-directories-under-a-relocated-home.md) | A test suite, sandbox, or hook points `HOME` (or `XDG_CACHE_HOME`/`XDG_DATA_HOME`) at a scratch directory and then runs `uv run`/`uv tool run`, especially `--offline`; uv reports a package "not found in the cache" that resolves from your shell, or picks a different Python than it does interactively; uv-dependent test cases report `skip` on a machine where uv works; choosing between `UV_CACHE_DIR`, `UV_PYTHON_INSTALL_DIR`, `UV_TOOL_DIR` | +| [native-addon-binary-missing-after-bun-install](toolchains/native-addon-binary-missing-after-bun-install.md) | A CLI, MCP stdio server, or app installed with `bun install`/`bun install -g` dies with `Could not locate the bindings file` or another missing-`.node` error for a native dependency (better-sqlite3, sharp, tree-sitter); `build/Release/` holds `obj` directories and no `.node`; deciding between `bun pm trust`, `--trust`, and a hand rebuild with `prebuild-install`/`node-gyp` under the runtime the launcher uses; adding `trustedDependencies` to a package.json that relied on bun's default allowlist | ## Planned (unseeded categories) diff --git a/wiki/platforms/toolchains/compiler-sysroot-on-macos.md b/wiki/platforms/toolchains/compiler-sysroot-on-macos.md index 19b1c12..b0c857f 100644 --- a/wiki/platforms/toolchains/compiler-sysroot-on-macos.md +++ b/wiki/platforms/toolchains/compiler-sysroot-on-macos.md @@ -11,7 +11,7 @@ sources: - https://clang.llvm.org/docs/DiagnosticsReference.html - https://discourse.llvm.org/t/stdio-h-not-found-on-mac-how-to-add-system-headers-includes-into-clang/77604 last_verified: 2026-08-29 -related: [platforms-toolchains-version-management, platforms-environment-path-resolution, debugging-signals-reading-error-messages, infrastructure-agent-orchestration-verify-command-in-a-worker-brief] +related: [platforms-toolchains-version-management, platforms-environment-path-resolution, debugging-signals-reading-error-messages, infrastructure-agent-orchestration-verify-command-in-a-worker-brief, platforms-toolchains-native-addon-binary-missing-after-bun-install] --- # A Non-Apple Compiler Resolving the macOS SDK diff --git a/wiki/platforms/toolchains/native-addon-binary-missing-after-bun-install.md b/wiki/platforms/toolchains/native-addon-binary-missing-after-bun-install.md new file mode 100644 index 0000000..f92346b --- /dev/null +++ b/wiki/platforms/toolchains/native-addon-binary-missing-after-bun-install.md @@ -0,0 +1,90 @@ +--- +id: platforms-toolchains-native-addon-binary-missing-after-bun-install +domain: platforms +category: toolchains +applies_to: [node, general] +confidence: verified +sources: + - https://bun.com/docs/pm/lifecycle + - https://bun.com/docs/pm/cli/pm + - https://bun.com/docs/guides/install/trusted + - https://github.com/oven-sh/bun/blob/main/src/install/default-trusted-dependencies.txt + - https://github.com/nodejs/node-gyp#installation + - https://github.com/WiseLibs/better-sqlite3/blob/master/package.json +last_verified: 2026-09-28 +related: [platforms-toolchains-version-management, platforms-toolchains-compiler-sysroot-on-macos, platforms-environment-path-resolution, security-dependencies-supply-chain, platforms-tools-plugin-mcp-server-registration] +--- + +# A Native Addon Has No `.node` Binary After `bun install` + +## When this applies + +A CLI, MCP stdio server, or app installed with `bun install` or `bun install -g` +dies at startup with `Could not locate the bindings file` (or another missing +`.node` error) for a native dependency such as better-sqlite3, sqlite3, sharp or a +tree-sitter grammar; the dependency's `build/Release/` holds `obj*` directories and +no `.node`; deciding between `bun pm trust`, `--trust`, and rebuilding by hand. + +## Do this + +1. **Read bun's own install notice before choosing a remedy.** bun reports a + skipped script and a failed script differently, and only one of them is a + trust problem: + +| `bun install` printed | What happened | Do | +|-----------------------|---------------|----| +| `Blocked N postinstall. Run \`bun pm untrusted\` for details.` and exit 0 | The package is not on the allowlist, so its script never ran | `bun pm trust ` in the install root: it runs the blocked script now and appends the name to `trustedDependencies` | +| `error: install script from "" exited with 1` and exit 1 | The script ran and failed; a partial build dir stays behind and no lockfile is written | Fix the build prerequisite (step 3), then re-run `bun install` | + +2. **When the install output is gone**, run `bun pm untrusted` in the install + root (`~/.bun/install/global` for a `-g` install): + +| `bun pm untrusted` says | Then | +|-------------------------|------| +| Lists the package and its script | It was blocked: `bun pm trust ` | +| Does not list it and `bun pm default-trusted` contains it | Its script ran and produced no usable binary: step 3 | +| `error: Lockfile not found` | The install itself failed: re-run `bun install` and read its error | + +3. **Rebuild under the runtime that will load the binary.** The launcher decides: + a `#!/usr/bin/env node` or `#!/bin/sh` bin runs under the `node` on PATH, a + `#!/usr/bin/env bun` bin under bun. In the dependency's directory run + `npx prebuild-install` (downloads a prebuilt for that runtime's ABI; exits + non-zero when none is published for it), then + `npx node-gyp rebuild --release --python=`. node-gyp needs + Xcode Command Line Tools on macOS and a supported Python (`--python`, + `npm_config_python`, or `PYTHON`). Confirm with `ls build/Release/*.node`, then + re-run the CLI itself. +4. **When you add `trustedDependencies` to a package.json, also list every + default-allowlisted package you rely on** (`bun pm default-trusted` prints the + list): the field replaces bun's default allowlist instead of extending it, and + the default list applies only to packages installed from npm, never to + `file:`, `link:`, `git:` or `github:` sources. + +## Edge cases + +| Case | Then | +|------|------| +| The package is on the default list but the project's `trustedDependencies` omits it | It is blocked from now on; add it to the field | +| Node was upgraded after the install (Homebrew major bump) | The compiled addon targets the old ABI; rebuild with step 3 under the new `node` | +| The CLI's bin is a `#!/bin/sh` script and you test it with `bun ` | bun parses the shell script as JavaScript and reports `Syntax Error`; run the bin directly | +| `--ignore-scripts` is set (flag, `bunfig.toml`, `.npmrc`) | It skips the project's own scripts; dependency scripts are governed by the allowlist alone, so it does not explain a blocked dependency | +| The symptom is an MCP server that reports `CONNECTION_CLOSED` at connect | Run the server command by hand; the bindings error is on its stderr, which the client does not surface | + +## Instead of + +| If you are about to | Do this instead | Why | +|---------------------|-----------------|-----| +| Reinstall with `--trust` for a package already on `bun pm default-trusted` | Run `bun pm untrusted`, then step 3 | The script already ran; `--trust` re-runs the same failing compile and, by writing `trustedDependencies`, drops every other default-list package | +| Delete `node_modules` and reinstall to reset the failure | Read the install error and fix the prerequisite it names | The compile prerequisite is unchanged, so the same script fails again | +| Conclude from the missing `.node` that bun blocked the script | Distinguish blocked from failed with the notices in step 1 | A failed script also leaves no `.node`, but it leaves `obj` directories and an exit 1 | + +## Sources + +- https://bun.com/docs/pm/lifecycle — bun runs lifecycle scripts only for allowlisted packages; the default list applies to npm sources only; `--ignore-scripts` +- https://bun.com/docs/pm/cli/pm — `bun pm untrusted`, `bun pm trust`, `bun pm default-trusted`, `bun pm ls --trusted`; a set `trustedDependencies` replaces the default list +- https://bun.com/docs/guides/install/trusted — default allowlist note and the replace-not-extend rule +- https://github.com/oven-sh/bun/blob/main/src/install/default-trusted-dependencies.txt — better-sqlite3 and sqlite3 are on the default list +- https://github.com/nodejs/node-gyp#installation — Xcode CLT and supported Python requirements; `--python`, `npm_config_python`, `PYTHON`; `rebuild` = clean + configure + build +- https://github.com/WiseLibs/better-sqlite3/blob/master/package.json — install script `prebuild-install || node-gyp rebuild --release` +- Reproduction, bun 1.3.11, 2026-09-28: a trusted `file:` dependency whose install script exits 1 makes `bun install` exit 1 with `error: install script from "failing-dep" exited with 1`, leaves `build/Release/obj`, and writes no lockfile (`bun pm untrusted` then reports `Lockfile not found`); an unlisted dependency yields `Blocked 1 postinstall` with exit 0, and `bun pm trust` runs its script and writes `trustedDependencies` +- Field case, 2026-09-28: a globally bun-installed MCP server depending on better-sqlite3 12.8.0 launched under Node 26 with only `obj` directories in `build/Release`; better-sqlite3 was on the default list and absent from `bun pm untrusted`; `prebuild-install` had no binary for that ABI and `node-gyp rebuild --release --python=<3.11>` produced `better_sqlite3.node`, after which the server connected diff --git a/wiki/platforms/toolchains/version-management.md b/wiki/platforms/toolchains/version-management.md index b1d18f1..13036ae 100644 --- a/wiki/platforms/toolchains/version-management.md +++ b/wiki/platforms/toolchains/version-management.md @@ -10,7 +10,7 @@ sources: - https://mise.jdx.dev/configuration.html - https://docs.npmjs.com/cli/v11/configuring-npm/package-json last_verified: 2026-07-10 -related: [platforms-processes-background-services, platforms-shells-portable-shell-scripts, platforms-toolchains-compiler-sysroot-on-macos, platforms-toolchains-environment-resync-removes-undeclared-packages, infrastructure-agent-orchestration-verify-command-in-a-worker-brief, platforms-toolchains-regeneration-silently-drops-hand-edited-state] +related: [platforms-processes-background-services, platforms-shells-portable-shell-scripts, platforms-toolchains-compiler-sysroot-on-macos, platforms-toolchains-environment-resync-removes-undeclared-packages, infrastructure-agent-orchestration-verify-command-in-a-worker-brief, platforms-toolchains-regeneration-silently-drops-hand-edited-state, platforms-toolchains-native-addon-binary-missing-after-bun-install] --- # Pinning Tool Versions So Every Machine Runs the Same Toolchain diff --git a/wiki/platforms/tools/plugin-mcp-server-registration.md b/wiki/platforms/tools/plugin-mcp-server-registration.md index 890f056..8730a1a 100644 --- a/wiki/platforms/tools/plugin-mcp-server-registration.md +++ b/wiki/platforms/tools/plugin-mcp-server-registration.md @@ -9,7 +9,7 @@ sources: - https://code.claude.com/docs/en/mcp - https://github.com/modelcontextprotocol/typescript-sdk/issues/216 last_verified: 2026-08-12 -related: [platforms-tools-version-keyed-artifact-cache, platforms-tools-harness-mediated-tool-results, infrastructure-config-environment-config, infrastructure-agent-orchestration-gate-evidence-exit-code-class] +related: [platforms-tools-version-keyed-artifact-cache, platforms-tools-harness-mediated-tool-results, infrastructure-config-environment-config, infrastructure-agent-orchestration-gate-evidence-exit-code-class, platforms-toolchains-native-addon-binary-missing-after-bun-install] --- # A Plugin-Bundled MCP Server That Does Not Appear in the Harness diff --git a/wiki/security/dependencies/supply-chain.md b/wiki/security/dependencies/supply-chain.md index 06cb50d..403c062 100644 --- a/wiki/security/dependencies/supply-chain.md +++ b/wiki/security/dependencies/supply-chain.md @@ -11,7 +11,7 @@ sources: - https://owasp.org/Top10/A06_2021-Vulnerable_and_Outdated_Components/ - https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates last_verified: 2026-07-10 -related: [security-secrets-secrets-in-code, security-dependencies-agent-skill-supply-chain] +related: [security-secrets-secrets-in-code, security-dependencies-agent-skill-supply-chain, platforms-toolchains-native-addon-binary-missing-after-bun-install] --- # Trusting and Maintaining Third-Party Dependencies