hermes-agent/tests-js/package-json-lazy-deps.test.ts
teknium1 38137d2b6e test: purge low-value tests, lane js06 (375 removed)
Change-detectors, tautologies, source-reading tests, redundant duplicates,
mock-echo tests and dead/unrunnable tests. Per-test rationale in the lane
ledger (category + reason for every removal).
2026-09-23 03:15:26 -07:00

82 lines
3.9 KiB
TypeScript

/**
* Invariants for what is eager vs lazy in the root ``package.json``.
*
* The root ``package.json`` is installed by ``hermes update`` on every user,
* including users who never opted into a given browser backend. Anything
* listed in ``dependencies`` therefore runs its npm postinstall script for
* everyone, and — per #43564 — is also part of the npm workspace install
* graph, where a workspace-scoped ``npm ci`` (``--workspace ui-tui
* --workspace web``) can silently prune it right back out on the next
* ``hermes update``.
*
* The contract:
*
* - ``agent-browser`` is NOT a root dependency. It used to be eager (see
* #27055, which reasoned its postinstall was small enough to keep eager
* unlike Camofox's) but #43564 found that keeping ANY dependency in root
* ``package.json`` — however small its postinstall — entangles it with
* the ui-tui/web workspace install and risks it being pruned. It now
* resolves at runtime via ``npx agent-browser`` (see
* ``tools/browser_tool.py::_find_agent_browser``), which sidesteps the
* workspace graph entirely. ``hermes update`` and ``hermes doctor --fix``
* both fire-and-forget ``warm_agent_browser_npx_cache()`` to keep npx's
* own cache warm, preserving the "available before any session starts"
* property #27055 cared about without re-entangling the dependency.
*
* - ``@streamdown/math`` is NOT a root dependency either. It's imported only
* by desktop's own TS code (``apps/desktop/src/...``), so it belongs in
* ``apps/desktop/package.json`` (alongside its sibling ``@streamdown/code``)
* — not root, where it was subject to the exact same pruning risk.
*
* - ``@askjo/camofox-browser`` is NOT eager. It is an explicit opt-in
* alternative browser backend, selected by the user via
* ``hermes tools`` → Browser Automation → Camofox, and only used at
* runtime when ``CAMOFOX_URL`` is set. Its postinstall fetches a ~300MB
* Firefox-fork binary, which silently blocked ``hermes update`` for
* multi-minute stretches on slow / network-restricted connections
* (notably users in China running through a VPN). The package is
* installed on demand by ``tools_config.py`` ``post_setup_key ==
* "camofox"`` when the user actually selects Camofox.
*
* If a future PR re-adds any of these to root ``dependencies``, this test
* fails — read the lazy-install guidance in the ``hermes-agent-dev`` skill
* before changing the expectations.
*/
import assert from 'node:assert/strict'
import fs from 'node:fs'
import path from 'node:path'
import { test } from 'vitest'
const REPO_ROOT = path.resolve(__dirname, '..')
const ROOT_PKG = path.join(REPO_ROOT, 'package.json')
function rootPackageJson(): Record<string, unknown> {
return JSON.parse(fs.readFileSync(ROOT_PKG, 'utf-8'))
}
test('camofox is not in root dependencies (must stay opt-in)', () => {
const deps = (rootPackageJson().dependencies ?? {}) as Record<string, string>
assert.ok(
!('@askjo/camofox-browser' in deps),
'Camofox is a ~300MB binary-postinstall backend that must stay ' +
'out of root package.json dependencies. It belongs in the ' +
'Camofox post_setup handler in hermes_cli/tools_config.py so it ' +
'only installs when the user explicitly selects Camofox via ' +
'`hermes tools` → Browser Automation → Camofox.'
)
})
test('agent-browser is not in root dependencies (resolves via npx, #43564)', () => {
const deps = (rootPackageJson().dependencies ?? {}) as Record<string, string>
assert.ok(
!('agent-browser' in deps),
'agent-browser must not be a root package.json dependency — it ' +
'resolves lazily via `npx agent-browser` instead (see ' +
'tools/browser_tool.py::_find_agent_browser and ' +
'warm_agent_browser_npx_cache). Putting it back in root ' +
'dependencies re-entangles it with the ui-tui/web workspace ' +
'install graph and reintroduces #43564.'
)
})