@vzn/vx 0.0.400 → 0.0.402

package/package.json

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

package/src/exec/sandbox-runtime.ts

@@ -1891,7 +1891,8 @@ async function runSandboxedOnce(
       config: args.config,
       skip: [taskTmpRoot(), ...srtDefaultWritePaths()],
     })
-    if (outside.length > 0) violations.push(outsideWritesHint(outside, baselines.denyRead))
+    if (outside.length > 0)
+      violations.push(outsideWritesHint(outside, baselines.denyRead, args.reportWithin))
   }
 
   // The one denial macOS never logs. MEASURED 2026-09-05, same machine, two
@@ -1959,12 +1960,22 @@ async function runSandboxedOnce(
 }
 
 /** The hint for writes refused outside the project, a few paths named. */
-function outsideWritesHint(paths: readonly string[], walled: readonly string[]): SandboxViolation {
+function outsideWritesHint(
+  paths: readonly string[],
+  walled: readonly string[],
+  within: string,
+): SandboxViolation {
   const shown = paths.slice(0, 5).join(', ')
   const more = paths.length > 5 ? ` and ${paths.length - 5} more` : ''
   const home = toRealPath(os.homedir())
   const dir = path.dirname(paths[0]!)
-  const spelled = atOrUnder(dir, home) ? `~${dir.slice(home.length)}` : dir
+  // In the workspace, from the project, as a committed config spells it:
+  // the absolute path held only on the machine that printed it.
+  const spelled = walled.some((w) => atOrUnder(dir, toRealPath(w)))
+    ? path.relative(toRealPath(within), dir) || '.'
+    : atOrUnder(dir, home)
+      ? `~${dir.slice(home.length)}`
+      : dir
   const refused =
     `vx: the sandbox refused writes outside the project, which are not reported as ` +
     `violations: ${shown}${more}.`
@@ -1979,10 +1990,13 @@ function outsideWritesHint(paths: readonly string[], walled: readonly string[]):
     ? `${refused} The task has its own temp directory, empty at its start: write under ` +
       `$TMPDIR (os.tmpdir() in Node and Bun) instead of a fixed path.`
     : `${refused} If the task needs one, grant its directory, e.g. ` +
-      `\`allow: { write: ['${spelled}/'] }\`.`
+      `\`allow: { write: [${jsString(`${spelled}/`)}] }\`.`
   return { timestamp: new Date(), hint: true, line }
 }
 
+/** A path as a JS string literal a config can take: a quote in it is escaped. */
+const jsString = (p: string): string => (p.includes("'") ? JSON.stringify(p) : `'${p}'`)
+
 /** The host's shared temp directories, canonical: what a fixed temp path in a tool names. */
 function hostTempRoots(): string[] {
   return [...new Set(['/tmp', '/var/tmp', os.tmpdir()].map(toRealPath))]
@@ -1997,7 +2011,7 @@ function hiddenReadsHint(paths: readonly string[], within: string): SandboxViola
     line:
       `vx: the sandbox hid paths outside the project that exist on this machine, which are ` +
       `not reported as violations: ${shown}${more}. If the task reads one, grant it, e.g. ` +
-      `\`allow: { read: ['${path.relative(toRealPath(within), paths[0]!)}'] }\`.`,
+      `\`allow: { read: [${jsString(path.relative(toRealPath(within), paths[0]!))}] }\`.`,
   }
 }
 

package/src/index.ts

@@ -149,6 +149,7 @@ export type {
   VxPlugin,
   PluginHooks,
   PluginOrigin,
+  PluginOptionKinds,
   CacheContext,
   ExecutorContext,
   CommandContext,

package/src/orchestrator/index.ts

@@ -87,6 +87,7 @@ export {
   type VxPlugin,
   definePlugin,
   refuseUnknownOptions,
+  type PluginOptionKinds,
   type PluginHooks,
   type PluginOrigin,
 } from './plugin.js'

package/src/orchestrator/plugin.ts

@@ -483,29 +483,69 @@ export function definePlugin(origin: PluginOrigin, hooks: PluginHooks): VxPlugin
   return { ...hooks, name, [PLUGIN_PACKAGE]: name } as VxPlugin
 }
 
+/** What `refuseUnknownOptions` holds an option's value to. */
+type OptionKind<V> = [V] extends [string]
+  ? 'string'
+  : [V] extends [number]
+    ? 'number'
+    : [V] extends [boolean]
+      ? 'boolean'
+      : [V] extends [(...args: never[]) => unknown]
+        ? 'function'
+        : [V] extends [object]
+          ? 'object'
+          : 'any'
+
+/**
+ * Every option a factory takes, each with the one kind its type allows
+ * (`'any'` for a union of kinds, such as `false | { … }`). Derived from
+ * the options interface, so the type checker refuses a missing option, an
+ * extra one or a wrong kind.
+ */
+export type PluginOptionKinds<T> = {
+  readonly [K in keyof Required<T>]-?: OptionKind<Required<T>[K]>
+}
+
 /**
- * Refuse an option a plugin factory does not take, as core refuses an
- * unknown config field. Bun strips a config's types, so a misspelt option
- * (`reapi({ endpont })`) reached the factory, which read it as unset and
- * quietly declined: the run went local with no word. `factory` names the
- * call in the message (`reapi()`), `known` is the options the factory reads.
+ * Refuse an option a plugin factory does not take, or a value of the wrong
+ * kind, as core refuses an unknown config field. Bun strips a config's
+ * types, so a misspelt option (`reapi({ endpont })`) reached the factory,
+ * which read it as unset and quietly declined, and a string where a number
+ * or a boolean belongs (`process.env.X`) was misread or threw a bare
+ * TypeError. `factory` names the call in the message (`reapi()`).
  */
-export function refuseUnknownOptions(
+export function refuseUnknownOptions<T>(
   factory: string,
   options: unknown,
-  known: readonly string[],
+  kinds: PluginOptionKinds<T>,
 ): void {
   if (options === undefined) return
   if (options === null || typeof options !== 'object' || Array.isArray(options)) {
     throw new UserError(`${factory}: options must be an object`)
   }
-  for (const key of Object.keys(options)) {
-    if (known.includes(key)) continue
-    const near = nearest(key, known)
-    throw new UserError(
-      `${factory} has unknown option "${key}" (allowed: ${[...known].sort().join(', ')})` +
-        (near === undefined ? '' : ` — did you mean ${near}?`),
-    )
+  const known = kinds as Readonly<Record<string, string>>
+  const names = Object.keys(known)
+  for (const [key, value] of Object.entries(options)) {
+    const kind = known[key]
+    if (kind === undefined) {
+      const near = nearest(key, names)
+      throw new UserError(
+        `${factory} has unknown option "${key}" (allowed: ${[...names].sort().join(', ')})` +
+          (near === undefined ? '' : ` — did you mean ${near}?`),
+      )
+    }
+    if (value === undefined || kind === 'any') continue
+    const ok =
+      kind === 'object'
+        ? value !== null && typeof value === 'object' && !Array.isArray(value)
+        : typeof value === kind
+    if (!ok) {
+      const got =
+        typeof value === 'function' ? 'a function' : (JSON.stringify(value) ?? String(value))
+      throw new UserError(
+        `${factory} option "${key}" must be ${kind === 'object' ? 'an' : 'a'} ${kind}, got ${got}`,
+      )
+    }
   }
 }