Import AITURK IDE 1.0.0-beta.1 from Hermes 63279301; preserve MIT license

tests-js/package-json-lazy-deps.test.ts

@@ -0,0 +1,147 @@
+/**
+ * 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')
+const ROOT_LOCK = path.join(REPO_ROOT, 'package-lock.json')
+const DESKTOP_PKG = path.join(REPO_ROOT, 'apps', 'desktop', '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.'
+  )
+})
+
+test('@streamdown/math is not in root dependencies (desktop-only import)', () => {
+  const deps = (rootPackageJson().dependencies ?? {}) as Record<string, string>
+  assert.ok(
+    !('@streamdown/math' in deps),
+    '@streamdown/math is only imported by apps/desktop\'s own TS code ' +
+      '(markdown-text.tsx, katex-memo.ts) — it belongs in ' +
+      'apps/desktop/package.json alongside its sibling @streamdown/code, ' +
+      'not root, where it\'s subject to the same workspace-pruning risk ' +
+      'agent-browser had (#43564).'
+  )
+})
+
+test('@streamdown/math is in desktop dependencies', () => {
+  const deps = (JSON.parse(fs.readFileSync(DESKTOP_PKG, 'utf-8')).dependencies ??
+    {}) as Record<string, string>
+
+  assert.ok(
+    '@streamdown/math' in deps,
+    '@streamdown/math is imported by apps/desktop\'s own TS code ' +
+      '(markdown-text.tsx, katex-memo.ts) and must be declared in ' +
+      'apps/desktop/package.json now that it is no longer a root ' +
+      'dependency.'
+  )
+})
+
+test('root lockfile has no camofox entries', () => {
+  if (!fs.existsSync(ROOT_LOCK)) {
+    // Some CI matrix shards skip lockfile materialization.
+    return
+  }
+
+  const text = fs.readFileSync(ROOT_LOCK, 'utf-8')
+  assert.ok(
+    !text.includes('@askjo/camofox-browser'),
+    'package-lock.json still references @askjo/camofox-browser. ' +
+      'Regenerate the lockfile after removing the dep: ' +
+      '`rm package-lock.json && npm install --package-lock-only ' +
+      '--ignore-scripts --no-fund --no-audit`.'
+  )
+  assert.ok(
+    !text.includes('camoufox-js'),
+    'package-lock.json still references camoufox-js (transitive of ' +
+      '@askjo/camofox-browser). Regenerate the lockfile.'
+  )
+})
+
+test('root lockfile has no agent-browser entry (#43564)', () => {
+  if (!fs.existsSync(ROOT_LOCK)) {
+    // Some CI matrix shards skip lockfile materialization.
+    return
+  }
+
+  const text = fs.readFileSync(ROOT_LOCK, 'utf-8')
+  assert.ok(
+    !text.includes('"node_modules/agent-browser"'),
+    'package-lock.json still has a node_modules/agent-browser entry. ' +
+      'It must resolve lazily via `npx agent-browser` instead — ' +
+      'regenerate the lockfile after removing the dep: ' +
+      '`rm package-lock.json && npm install --package-lock-only ' +
+      '--ignore-scripts --no-fund --no-audit`.'
+  )
+})