@vzn/vx 0.0.254 → 0.0.256

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.254",
+  "version": "0.0.256",
   "description": "A fast, correct task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -17,10 +17,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.254",
-    "@vzn/vx-linux-arm64": "0.0.254",
-    "@vzn/vx-darwin-x64": "0.0.254",
-    "@vzn/vx-darwin-arm64": "0.0.254"
+    "@vzn/vx-linux-x64": "0.0.256",
+    "@vzn/vx-linux-arm64": "0.0.256",
+    "@vzn/vx-darwin-x64": "0.0.256",
+    "@vzn/vx-darwin-arm64": "0.0.256"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cli/init.ts

@@ -216,11 +216,17 @@ function remoteCacheSignal(root: string, runner: 'turbo' | 'nx'): string | undef
       } catch {
         continue
       }
-      if (typeof rc === 'object' && rc !== null && (rc as { enabled?: unknown }).enabled !== false)
+      if (typeof rc === 'object' && rc !== null) {
+        // Turned off in turbo.json is off, whatever CI sets.
+        if ((rc as { enabled?: unknown }).enabled === false) return undefined
         return `${f} names a remoteCache`
+      }
     }
   }
   const variable = REMOTE_CACHE_ENV[runner]
+  // A line that sets it (`TURBO_TOKEN: …`, `TURBO_TOKEN=…`), not one that
+  // names it: a comment or a doc line counted as "sets" (J's lead).
+  const sets = new RegExp(`^(?!\\s*#).*\\b${variable}\\s*[:=]`, 'm')
   const workflows = new Bun.Glob('.github/workflows/*.{yml,yaml}')
   const files = [...workflows.scanSync({ cwd: root, dot: true })].sort().concat(CI_FILES)
   for (const f of files) {
@@ -230,7 +236,7 @@ function remoteCacheSignal(root: string, runner: 'turbo' | 'nx'): string | undef
     } catch {
       continue
     }
-    if (text.includes(variable)) return `${f} sets ${variable}`
+    if (sets.test(text)) return `${f} sets ${variable}`
   }
   return undefined
 }

package/src/cli/plugin-templates.ts

@@ -20,8 +20,8 @@ export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: s
   },
   executor: {
     plugin:
-      "// `executor`: where a task's command runs. This one runs it here, in a\n// shell of its own, and stops the shell's whole process group when core\n// aborts the request (a stop, or `exec.timeout`): core cannot reach a\n// process an executor spawned.\nimport { definePlugin, type TaskExecutor, type VxPlugin } from '@vzn/vx'\n\nexport function shellExecutor(): VxPlugin {\n  const executor: TaskExecutor = {\n    name: 'shell',\n    async execute(req) {\n      const started = Date.now()\n      const child = Bun.spawn(['sh', '-c', [req.command, ...req.forwardArgs].join(' ')], {\n        cwd: req.cwd,\n        env: req.env,\n        stdout: 'pipe',\n        stderr: 'pipe',\n        detached: true,\n      })\n      const stop = (): void => {\n        try {\n          process.kill(-child.pid, 'SIGTERM')\n        } catch {\n          // already gone\n        }\n      }\n      req.signal?.addEventListener('abort', stop, { once: true })\n      const drain = async (stream: ReadableStream<Uint8Array>, on: (s: string) => void) => {\n        const decoder = new TextDecoder()\n        let all = ''\n        for await (const chunk of stream) {\n          const text = decoder.decode(chunk, { stream: true })\n          all += text\n          on(text)\n        }\n        return all\n      }\n      const [stdout, stderr, exitCode] = await Promise.all([\n        drain(child.stdout, req.onStdout),\n        drain(child.stderr, req.onStderr),\n        child.exited,\n      ])\n      req.signal?.removeEventListener('abort', stop)\n      return {\n        exitCode,\n        durationMs: Date.now() - started,\n        stdout,\n        stderr,\n        violations: [],\n        where: 'shell',\n      }\n    },\n  }\n  return definePlugin(import.meta, { executor: () => executor })\n}\n",
-    test: "// A test for the example `executor` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { run, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-executor-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  await writeFile(path.join(dir, 'vx.config.mjs'), config)\n  return dir\n}\n\n/** A `vx.workspace.mjs` declaring `call`, e.g. `shellExecutor()`, from the plugin file beside this test. */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'executor.ts'))\n  await writeFile(\n    path.join(root, 'vx.workspace.mjs'),\n    `import { shellExecutor } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit('runs the command and says where; stops it on exec.timeout', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: {\n      hello: { exec: { command: 'echo hi > out.txt' } },\n      slow: { exec: { command: 'exec sleep 30', timeout: 300 } },\n    } }`,\n  )\n  await workspace('shellExecutor()')\n  const ok = await run({ cwd: root, tasks: ['hello'], log: log(), handleSignals: false })\n  expect(ok.outcomes.map((o) => [o.node.id, o.status, o.where])).toEqual([\n    ['a#hello', 'success', 'shell'],\n  ])\n  expect(await Bun.file(path.join(dir, 'out.txt')).text()).toBe('hi\\n')\n  const started = Date.now()\n  const slow = await run({ cwd: root, tasks: ['slow'], log: log(), handleSignals: false })\n  expect(slow.outcomes.map((o) => [o.node.id, o.status, o.timedOut === true])).toEqual([\n    ['a#slow', 'failed', true],\n  ])\n  expect(Date.now() - started).toBeLessThan(10_000)\n}, 20_000)\n",
+      "// `executor`: where a task's command runs. This one runs it here, in a\n// shell of its own, and stops the shell's whole process group when core\n// aborts the request (a stop, or `exec.timeout`): core cannot reach a\n// process an executor spawned.\nimport { definePlugin, type TaskExecutor, type VxPlugin } from '@vzn/vx'\n\nexport function shellExecutor(): VxPlugin {\n  const executor: TaskExecutor = {\n    name: 'shell',\n    async execute(req) {\n      const started = Date.now()\n      // vx's own `sh`: a bare name is looked up on `req.env`'s PATH, which\n      // leads with the project's node_modules/.bin, where a dependency's\n      // `sh` would run every command.\n      const sh = Bun.which('sh') ?? '/bin/sh'\n      const child = Bun.spawn([sh, '-c', [req.command, ...req.forwardArgs].join(' ')], {\n        cwd: req.cwd,\n        env: req.env,\n        stdout: 'pipe',\n        stderr: 'pipe',\n        detached: true,\n      })\n      const stop = (): void => {\n        try {\n          process.kill(-child.pid, 'SIGTERM')\n        } catch {\n          // already gone\n        }\n      }\n      req.signal?.addEventListener('abort', stop, { once: true })\n      const drain = async (stream: ReadableStream<Uint8Array>, on: (s: string) => void) => {\n        const decoder = new TextDecoder()\n        let all = ''\n        for await (const chunk of stream) {\n          const text = decoder.decode(chunk, { stream: true })\n          all += text\n          on(text)\n        }\n        return all\n      }\n      const [stdout, stderr, exitCode] = await Promise.all([\n        drain(child.stdout, req.onStdout),\n        drain(child.stderr, req.onStderr),\n        child.exited,\n      ])\n      req.signal?.removeEventListener('abort', stop)\n      return {\n        exitCode,\n        durationMs: Date.now() - started,\n        stdout,\n        stderr,\n        violations: [],\n        where: 'shell',\n      }\n    },\n  }\n  return definePlugin(import.meta, { executor: () => executor })\n}\n",
+    test: "// A test for the example `executor` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { run, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-executor-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  await writeFile(path.join(dir, 'vx.config.mjs'), config)\n  return dir\n}\n\n/** A `vx.workspace.mjs` declaring `call`, e.g. `shellExecutor()`, from the plugin file beside this test. */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'executor.ts'))\n  await writeFile(\n    path.join(root, 'vx.workspace.mjs'),\n    `import { shellExecutor } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit('runs the command and says where; stops it on exec.timeout', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: {\n      hello: { exec: { command: 'echo hi > out.txt' } },\n      slow: { exec: { command: 'exec sleep 30', timeout: 300 } },\n    } }`,\n  )\n  await workspace('shellExecutor()')\n  const ok = await run({ cwd: root, tasks: ['hello'], log: log(), handleSignals: false })\n  expect(ok.outcomes.map((o) => [o.node.id, o.status, o.where])).toEqual([\n    ['a#hello', 'success', 'shell'],\n  ])\n  expect(await Bun.file(path.join(dir, 'out.txt')).text()).toBe('hi\\n')\n  const started = Date.now()\n  const slow = await run({ cwd: root, tasks: ['slow'], log: log(), handleSignals: false })\n  expect(slow.outcomes.map((o) => [o.node.id, o.status, o.timedOut === true])).toEqual([\n    ['a#slow', 'failed', true],\n  ])\n  expect(Date.now() - started).toBeLessThan(10_000)\n}, 20_000)\n\nit(\"runs the command through this machine's sh, not a project's node_modules/.bin sh\", async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { hello: { exec: { command: 'echo real' } } } }`,\n  )\n  await mkdir(path.join(dir, 'node_modules', '.bin'), { recursive: true })\n  await writeFile(path.join(dir, 'node_modules', '.bin', 'sh'), '#!/bin/sh\\necho planted\\n', {\n    mode: 0o755,\n  })\n  await workspace('shellExecutor()')\n  const out: string[] = []\n  const r = await run({\n    cwd: root,\n    tasks: ['hello'],\n    log: { ...log(), taskStdout: (_n, chunk) => void out.push(chunk) },\n    handleSignals: false,\n  })\n  expect([r.outcomes.map((o) => o.status), out.join('')]).toEqual([['success'], 'real\\n'])\n}, 20_000)\n",
   },
   graph: {
     plugin:

package/src/config.ts

@@ -261,8 +261,10 @@ export interface SandboxGrants {
    */
   write?: string[]
   /**
-   * Reachable domains. `true` allows all, `['*.example.com']` a pattern.
-   * Omitted means no network at all.
+   * Reachable domains, `['*.example.com']` a pattern. The proxy is the
+   * run's: it filters every sandboxed task against the union of the lists
+   * the run's tasks declare, so `true` adds no domain and reaches only
+   * those (none in a run with no list). Omitted adds none either.
    */
   network?: true | string[]
   /**

package/src/exec/sandbox-runtime.ts

@@ -9,8 +9,9 @@
 //   This module adds nothing implicit on top — no /tmp, no project dir —
 //   so what a task may touch is its vx.config.ts plus those baselines.
 //
-// Network is opt-in per task. By default the sandbox blocks all outbound
-// traffic; tasks that need it set `sandbox.network: true`.
+// Network is a domain list, and the run's: SRT's one proxy filters every
+// sandboxed task against the union of the lists the run's tasks declare.
+// With no list, no domain is reachable; `sandbox.network: true` adds none.
 //
 // Platform reality:
 //   macOS — `SandboxViolationStore` is populated from the system log
@@ -520,9 +521,8 @@ function hostHasIpv6(): boolean {
  * servers + (on macOS) the violation log monitor. Safe to call repeatedly
  * — SRT itself returns early on the second call.
  *
- * The base config sets network to "block everything" (empty allowedDomains).
- * Per-task wrapping passes a customConfig that re-enables network for
- * tasks with `sandbox.network: true`.
+ * The base config sets network to "block everything" (empty allowedDomains)
+ * unless `allowedDomains` names some; `sandbox.network: true` adds none.
  *
  * @param opts.allowedDomains every domain any sandboxed task in this run
  * declared. SRT's filtering proxy is per-RUN and reads its allowlist from
@@ -2007,15 +2007,21 @@ async function wantsStraceDetection(): Promise<false | 'plain' | 'seccomp'> {
     })
     const out = await new Response(p.stdout).text()
     await p.exited
-    if (p.exitCode !== 0) straceAvailableCache = false
-    else {
+    if (p.exitCode !== 0) {
+      straceAvailableCache = false
+      warnUntraced(`strace --version exited ${p.exitCode}`)
+    } else {
       const m = /version (\d+)\.(\d+)/.exec(out)
       const [major, minor] = m ? [Number(m[1]), Number(m[2])] : [0, 0]
       const form = major > 5 || (major === 5 && minor >= 3) ? 'seccomp' : 'plain'
       straceAvailableCache = (await traceAttaches(form)) ? form : false
     }
   } catch {
+    // Not on PATH. Said as the refused attach is: without it an undeclared
+    // read is denied but never reported, so a task that tolerates the miss
+    // passes and caches with no word of it (J's lead).
     straceAvailableCache = false
+    warnUntraced('strace is not on PATH')
   }
   return straceAvailableCache
 }
@@ -2048,14 +2054,17 @@ async function traceAttaches(form: 'plain' | 'seccomp'): Promise<boolean> {
   )
   const err = await new Response(p.stderr).text()
   if ((await p.exited) === 0) return true
-  if (!warnedNoTrace) {
-    warnedNoTrace = true
-    process.stderr.write(
-      `[vx] sandbox: strace cannot trace here (${err.trim().split('\n')[0] ?? `exit ${p.exitCode}`}), ` +
-        `so sandboxed tasks run without the report of the reads the sandbox denied; ` +
-        `the sandbox still enforces\n`,
-    )
-  }
+  warnUntraced(`strace cannot trace here (${err.trim().split('\n')[0] ?? `exit ${p.exitCode}`})`)
   return false
 }
 let warnedNoTrace = false
+
+/** Said once per process: why sandboxed tasks run untraced, and what that loses. */
+function warnUntraced(why: string): void {
+  if (warnedNoTrace) return
+  warnedNoTrace = true
+  process.stderr.write(
+    `[vx] sandbox: ${why}, so sandboxed tasks run without the report of the reads the sandbox denied; ` +
+      `the sandbox still enforces\n`,
+  )
+}

package/src/orchestrator/sandbox-request.ts

@@ -81,9 +81,10 @@ export function sandboxRunUnion(nodes: Iterable<TaskNode>): SandboxRunUnion | nu
   for (const n of sandboxed) {
     const allow = n.config.exec?.sandbox?.allow
     const net = allow?.network
-    // `network: true` is deliberately absent from the union: it SKIPS the
-    // proxy rather than going through it, so folding it in as `*` would
+    // `network: true` adds nothing to the union: folded in as `*` it would
     // widen the allowlist every OTHER task in the run is filtered against.
+    // It does not skip the proxy either, so it reaches only the domains
+    // some task of the run lists (schema.md § network is per-RUN).
     if (Array.isArray(net)) for (const d of net) domains.add(d)
     for (const d of n.config.exec?.sandbox?.deny?.network ?? []) denied.add(d)
     const sockets = allow?.unixSockets

package/src/workspace/project-loader.ts

@@ -256,9 +256,11 @@ export function configLoadError(err: unknown, configPath: string, kind: string):
   if (name === 'ResolveMessage') {
     const spec = /Cannot find (?:package|module) ['"]([^'"]+)['"]/.exec(message)?.[1]
     const what = spec === undefined ? message.replace(BUST_QUERY, '') : `cannot find '${spec}'`
+    // The package the specifier names (`@vzn/vx-otel/x` → `@vzn/vx-otel`):
+    // a missing plugin was told to install core (J-59).
     const hint =
       spec?.startsWith('@vzn/vx') === true
-        ? `; install it in the workspace: bun add -d @vzn/vx`
+        ? `; install it in the workspace: bun add -d ${spec.split('/').slice(0, 2).join('/')}`
         : ''
     return new UserError(`${kind} config ${configPath}: ${what}${hint}`)
   }