@vzn/vx 0.0.651 → 0.0.653

package/src/cli/why.ts

@@ -7,12 +7,14 @@
 
 import { indexDb, Cache } from '../cache/index.js'
 import { anchoredSpecError, flagHint, formatValue, seeHelp } from './help.js'
-import { buildTaskGraph, isGroupTask, splitTaskId } from '../graph/index.js'
+import { buildTaskGraph, isDefaultBuild, isGroupTask, splitTaskId } from '../graph/index.js'
 import {
   cacheKeyDiff,
   explainCacheKey,
   inputWriters,
   latestRunId,
+  LocalHistoryProvider,
+  recordedTasks,
   rootCauses,
   upstreamTask,
   whyDidThisRerun,
@@ -20,6 +22,7 @@ import {
 import { resolveRunId } from '../orchestrator/index.js'
 import { MASKED, nearMatches, printable, refusal, UserError } from '../util/index.js'
 import * as ui from '../ui/index.js'
+import type { InputWriter, RootCause } from '../history/index.js'
 import type { Style } from '../ui/index.js'
 import { runRules } from '../settings.js'
 import { buildPackageGraph, findWorkspaceRoot } from '../workspace/index.js'
@@ -139,7 +142,7 @@ function suggest(query: string, ids: readonly string[], invoked: boolean): strin
   // No near name: say where to look, or that there is nothing yet.
   // A run of only group tasks records no task row: "nothing has run" was
   // false there, and its advice re-ran the group to the same answer.
-  if (ids.length > 0) return '; `vx last --list` shows what has run'
+  if (ids.length > 0) return '; `vx last --stats` lists the tasks that ran'
   return invoked
     ? '; no recorded run executed a task (a group records none: ask about a task it depends on)'
     : `; nothing has run here yet (vx run ${query}, then vx why)`
@@ -155,7 +158,8 @@ async function resolveTarget(
   cache: Cache,
   target: string,
   cwdProject: () => Promise<string | null>,
-  declared: () => Promise<boolean>,
+  declared: () => Promise<Declared>,
+  declaresId: (id: string) => Promise<Declared>,
 ): Promise<string> {
   const db = indexDb(cache)
   if (target.includes('#')) {
@@ -164,22 +168,40 @@ async function resolveTarget(
     // the error's suggestions and the bare-name form only.
     const [project, task] = splitTaskId(target)
     const hit = db
-      .query('SELECT 1 FROM runs WHERE project = ? AND task = ? ORDER BY id DESC LIMIT 1')
+      .query('SELECT 1 FROM main.runs WHERE project = ? AND task = ? ORDER BY id DESC LIMIT 1')
       .get(project, task)
     if (hit !== null) return target
+    if ((await declaresId(target)) === 'group') throw groupRefusal(target)
   } else {
     // A bare name reads only its own task's rows: the DISTINCT over every
     // pair sorted the whole history (24 of 26 ms at 58k rows), and its list
     // serves only the miss's suggestions below.
     const matches = (
-      db.query('SELECT DISTINCT project FROM runs WHERE task = ? ORDER BY project').all(target) as {
+      db
+        .query('SELECT DISTINCT project FROM main.runs WHERE task = ? ORDER BY project')
+        .all(target) as {
         project: string
       }[]
     ).map((r) => `${r.project}#${target}`)
+    // Asked even when no project ran it: the cwd project's own that never
+    // ran read as a name nobody declares.
+    const here = await cwdProject()
+    if (here !== null) {
+      const own = `${here}#${target}`
+      if (matches.includes(own)) return own
+      // `vx run build` here runs this project's own: another project's
+      // runs were explained in its place, unsaid.
+      const kind = await declaresId(own)
+      if (kind === 'group') throw groupRefusal(own)
+      if (kind !== false) {
+        throw refusal(
+          { tone: 'info', headline: `no runs of ${own} yet`, fix: `vx run ${target}` },
+          { code: 'VX_E_NO_HISTORY', message: `vx why: no recorded runs for "${own}"` },
+        )
+      }
+    }
     if (matches.length === 1) return matches[0]!
     if (matches.length > 1) {
-      const here = await cwdProject()
-      if (here !== null && matches.includes(`${here}#${target}`)) return `${here}#${target}`
       throw new UserError(
         `vx why: "${target}" ran in ${matches.length} projects — pick one:\n` +
           matches.map((m) => `  ${m}`).join('\n'),
@@ -187,17 +209,18 @@ async function resolveTarget(
       )
     }
   }
-  const pairs = db
-    .query('SELECT DISTINCT project, task FROM runs ORDER BY project, task')
-    .all() as Array<{ project: string; task: string }>
-  const ids = pairs.map((p) => `${p.project}#${p.task}`)
+  const ids = new LocalHistoryProvider(db).recentTaskIds()
   const invoked = ids.length === 0 && db.query('SELECT 1 FROM invocations LIMIT 1').get() !== null
   if (ids.length === 0 && !invoked) {
     // `vx run` of a task no project declares is refused: its advice was that.
     const known = await declared()
+    // Where the cwd's project does not declare it (a monorepo root), a bare
+    // `vx run build` is refused too: that advice sent the user in a circle.
+    const here = known && !target.includes('#') ? await cwdProject() : null
+    const all = here !== null && (await declaresId(`${here}#${target}`)) === false ? ' --all' : ''
     throw refusal(
       known
-        ? { tone: 'info', headline: `no runs of ${target} yet`, fix: `vx run ${target}` }
+        ? { tone: 'info', headline: `no runs of ${target} yet`, fix: `vx run ${target}${all}` }
         : {
             tone: 'info',
             headline: `no project declares ${target}`,
@@ -271,16 +294,12 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
       target,
       () => findCwdProject(process.cwd()),
       () => declares(root, target),
+      // The cwd project's own: a bare `vx run` there skips its default build.
+      (id) => declares(root, id, true),
     )
     let runId: string | null
     if (parsed.runId !== undefined) {
-      // A stopped run keeps rows but no header (item 854), and `vx last
-      // --log` prints its id, so the whole id is taken from its rows too.
-      runId =
-        resolveRunId(db, parsed.runId, 'vx why') ??
-        (db.query('SELECT 1 FROM runs WHERE run_id = ? LIMIT 1').get(parsed.runId) !== null
-          ? parsed.runId
-          : null)
+      runId = resolveRunId(db, parsed.runId, 'vx why')
       // An unknown id read as a known run missing the task (X-18).
       if (runId === null) {
         throw new UserError(
@@ -329,18 +348,16 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
     // each moved dependency in this run down to the tasks whose own
     // inputs moved, so one `vx why` names the file, not the next task.
     // A group records no run: the graph names what it gathers.
+    const recorded = recordedTasks(db, runId)
     const unrecorded = diff.entries.filter(
-      (e) =>
-        e.kind === 'upstream' &&
-        e.change === 'changed' &&
-        !cacheKeyDiff(db, runId, upstreamTask(e.name)).found,
+      (e) => e.kind === 'upstream' && e.change === 'changed' && !recorded.has(upstreamTask(e.name)),
     )
     const groups = unrecorded.length > 0 ? await groupMembers(root, taskId) : new Map()
     const roots = rootCauses(db, runId, taskId, diff.entries, groups)
-    const writers = inputWriters(db, root, taskId, diff.entries, roots)
+    const writers = inputWriters(db, runId, root, taskId, diff.entries, roots)
 
     if (parsed.format === 'json') {
-      ui.data('out', `${JSON.stringify({ taskId, runId, why, diff, roots, writers })}\n`)
+      await ui.dataPieces('out', jsonPieces({ taskId, runId, why, diff }, roots, writers))
       return 0
     }
 
@@ -407,8 +424,18 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
           const what = r.entries.map((e) =>
             e.name === e.kind ? e.kind : `${e.kind} ${printable(e.name)}`,
           )
+          // A 20,000-task chain printed whole is one 389 KB line.
+          const chain = r.chain
+          const ids =
+            chain.length > CHAIN_SHOWN
+              ? [
+                  ...chain.slice(0, 2).map((id) => ui.id(id)),
+                  ui.dim(`${chain.length - 5} more`),
+                  ...chain.slice(-3).map((id) => ui.id(id)),
+                ]
+              : chain.map((id) => ui.id(id))
           return [
-            ...r.chain.flatMap((id, i) => [...(i > 0 ? [ui.dim(' \u2190 ')] : []), ui.id(id)]),
+            ...ids.flatMap((id, i) => [...(i > 0 ? [ui.dim(' \u2190 ')] : []), id]),
             ui.dim(' \u2190 '),
             ui.strong(
               `${what.slice(0, 3).join(', ')}${what.length > 3 ? ` and ${what.length - 3} more` : ''}`,
@@ -470,6 +497,33 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
 
 const ROOTS_SHOWN = 5
 
+/** Longer root-cause chains print their two ends around a count. */
+const CHAIN_SHOWN = 6
+
+/** Bytes of roots per piece written. */
+const PIECE_BYTES = 1 << 20
+
+/**
+ * `{ ...head, roots, writers }` as one `JSON.stringify` of it gives, in
+ * pieces: every root carries its whole chain, so a 20,000-task chain's
+ * roots hold 2×10⁸ ids, more than one string holds.
+ */
+function* jsonPieces(
+  head: object,
+  roots: readonly RootCause[],
+  writers: readonly InputWriter[],
+): Generator<string> {
+  let piece = `${JSON.stringify(head).slice(0, -1)},"roots":[`
+  for (let i = 0; i < roots.length; i++) {
+    piece += `${i > 0 ? ',' : ''}${JSON.stringify(roots[i])}`
+    if (piece.length >= PIECE_BYTES) {
+      yield piece
+      piece = ''
+    }
+  }
+  yield `${piece}],"writers":${JSON.stringify(writers)}}\n`
+}
+
 const CHANGE_HUE: Record<string, Style> = { added: 'ok', removed: 'error', changed: 'warn' }
 
 type DiffEntry = ReturnType<typeof cacheKeyDiff>['entries'][number]
@@ -508,21 +562,41 @@ function upstreamTodo(upstream: readonly DiffEntry[], unrecorded: readonly DiffE
   return out
 }
 
-/** Whether a project declares `target` (`pkg#task`, or a bare task); true when no config loads. */
-async function declares(root: string, target: string): Promise<boolean> {
+/** A declared group (no `exec`) records no run: `group` when every declaration is one. */
+type Declared = false | 'task' | 'group'
+
+/** Whether a project declares `target` (`pkg#task`, or a bare task); `task` when no config loads. */
+async function declares(root: string, target: string, own = false): Promise<Declared> {
   try {
     const projects = await loadCliProjects(root, await discoverCliProjects(root), 'all')
     const [project, task] = target.includes('#') ? splitTaskId(target) : [undefined, target]
-    return [...projects.values()].some(
-      (p) =>
-        (project === undefined || p.name === project) && Object.hasOwn(p.config.tasks ?? {}, task),
-    )
+    const found = [...projects.values()].flatMap((p) => {
+      const t = p.config.tasks?.[task]
+      return (project === undefined || p.name === project) &&
+        Object.hasOwn(p.config.tasks ?? {}, task) &&
+        !(own && isDefaultBuild(t))
+        ? [t]
+        : []
+    })
+    if (found.length === 0) return false
+    // The default build is a group too, but no one declared it.
+    return found.every((t) => t?.exec === undefined && !isDefaultBuild(t)) ? 'group' : 'task'
   } catch {
     // quiet: with no lock or a broken config, the run says why itself
-    return true
+    return 'task'
   }
 }
 
+function groupRefusal(id: string): UserError {
+  return refusal(
+    { tone: 'info', headline: `${id} is a group, which records no run`, fix: `vx show ${id}` },
+    {
+      code: 'VX_E_NO_HISTORY',
+      message: `vx why: ${id} is a group, which records no run (vx show ${id} names what it gathers)`,
+    },
+  )
+}
+
 /**
  * Each group in `taskId`'s graph with the tasks it gathers. Empty when a
  * config no longer loads: the advice then names the group to `vx show`.

package/src/cli/workspace-config.ts

@@ -7,6 +7,7 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
 import type { WorkspaceConfig } from '../config.js'
+import type { LazyGitEnumeration } from '../cache/index.js'
 import { UserError } from '../util/index.js'
 import { sayLine } from '../ui/index.js'
 import {
@@ -65,10 +66,19 @@ export async function loadCliWorkspace(
 export async function discoverCliProjects(
   root: string,
   load: CliLoadOptions = {},
+  /** The whole-tree enumeration the caller started; the run reuses it with the discovery. */
+  git?: LazyGitEnumeration,
 ): Promise<ProjectMeta[]> {
   const warn = load.warn ?? warnToStderr
   const ws = await loadCliWorkspace(root, warn)
-  return await discoverProjects(root, lockReader(root), ws.plugins, stageCacheDir(ws, load), warn)
+  return await discoverProjects(
+    root,
+    lockReader(root),
+    ws.plugins,
+    stageCacheDir(ws, load),
+    warn,
+    git,
+  )
 }
 
 /**

package/src/config.ts

@@ -28,6 +28,10 @@ export interface WorkspaceConfig {
   baseBranch?: string
   run?: RunSettings
   cache?: CacheSettings
+  /** Input defaults for every task. */
+  inputs?: WorkspaceInputs
+  /** Output defaults for every task. */
+  outputs?: WorkspaceOutputs
   lock?: LockSettings
   watch?: WatchSettings
   /**
@@ -76,6 +80,18 @@ export interface RunSettings {
   rules?: WorkspaceRules
 }
 
+/** `WorkspaceConfig.inputs`. */
+export interface WorkspaceInputs {
+  /** The `inputs.stability` of every task that does not set its own. */
+  stability?: InputStability
+}
+
+/** `WorkspaceConfig.outputs`. */
+export interface WorkspaceOutputs {
+  /** The `outputs.clean` of every task that does not set its own. */
+  clean?: boolean
+}
+
 /** `WorkspaceConfig.cache`: where the cache lives and what a run does with it. */
 export interface CacheSettings {
   /**
@@ -93,10 +109,6 @@ export interface CacheSettings {
   policy?: string
   /** Which remote hits land on disk: `all` (the default), only the requested tasks' (`toplevel`), or `none`. */
   download?: 'all' | 'toplevel' | 'none'
-  /** The `cache.inputStability` of every task that does not set its own. */
-  inputStability?: InputStability
-  /** The `cache.outputs.clean` of every task that does not set its own. */
-  outputs?: { clean?: boolean }
   /**
    * Which runs keep a failed task's log and the files its outputs left in
    * the remote: CI runs (`'ci'`, the default), runs off CI (`'local'`), or
@@ -305,13 +317,15 @@ export interface TaskConfig {
    * keyed group: its inputs are a key its dependents fold, with no process.
    */
   inputs?: InputsConfig
+  /** What the task produces: saved on a miss, restored on a hit. Needs `cache: true`. */
+  outputs?: TaskOutputs
   /**
-   * Caching configuration. **Caching is opt-in.** If this field is omitted,
-   * the task always runs and nothing is read from or written to the cache.
-   * Requires `exec` and `inputs`: the key is the task's inputs, and a group
-   * runs nothing to cache.
+   * `true` caches the task. **Caching is opt-in.** Omitted or `false`, the
+   * task always runs and nothing is read from or written to the cache.
+   * Requires `exec`, `inputs` and `outputs`: the key is the task's inputs,
+   * and a group runs nothing to cache.
    */
-  cache?: CacheConfig
+  cache?: boolean
 }
 
 /**
@@ -335,7 +349,7 @@ export interface TaskConfig {
  * from the other coupled them both ways — a declaration added for
  * caching silently widened the sandbox, and a path the task needed had
  * to be laundered through the cache key to get it (2026-09-05).
- * A declared `cache.outputs` is NOT a write grant; the request
+ * A declared `outputs` is NOT a write grant; the request
  * `sandbox-request.ts` builds carries no write of its own and binds
  * `allow.write` alone. This comment claimed the opposite — here and on
  * both grant fields — while the file beside it and `schema.md` both said
@@ -391,6 +405,13 @@ export interface SandboxConfig {
   weakerWhenNested?: boolean
   /** Accept weaker network isolation (host proxy) for lower overhead. */
   weakerNetworkIsolation?: boolean
+  /**
+   * Refuse every read outside the workspace too (`/usr`, `~/.cache`, the
+   * system toolchain), not only the workspace's other projects. A path
+   * outside it is readable only when `allow.read` names it; the shell a
+   * task runs in stays readable, so a task can start.
+   */
+  hermetic?: boolean
 }
 
 /** The denials `sandbox.ignore` can leave out of the report: patterns per class. */
@@ -410,9 +431,9 @@ export interface SandboxGrants {
   read?: readonly string[]
   /**
    * Writable paths or globs. The task can write NOTHING without these:
-   * declaring `cache.outputs.files` grants no write, and a task whose
+   * declaring `outputs.files` grants no write, and a task whose
    * only declaration is its outputs writes into a tmpfs that evaporates
-   * (vx then warns that `cache.outputs` matched no files).
+   * (vx then warns that `outputs` matched no files).
    */
   write?: readonly string[]
   /**
@@ -476,6 +497,15 @@ export interface ExecConfig {
    * it on a worker that is. Omitted → anywhere.
    */
   platforms?: readonly Platform[]
+  /**
+   * The worker type to run it on, by name (`'ubuntu'`), when an executor
+   * that names worker types (`TaskExecutor.workers`, `@vzn/vx-dte`'s
+   * `workers`) runs it: only that type's machines take it, and a run
+   * whose executor has no such type, or none on one of `platforms`, is
+   * refused before it starts. Placement only: not in the key, and a run
+   * on this machine ignores it. Omitted → the first type that fits.
+   */
+  worker?: string
   /** Environment exposed to the child process. */
   env?: ExecEnv
   /**
@@ -585,17 +615,6 @@ export interface ExecEnv {
   secret?: readonly string[]
 }
 
-export interface CacheConfig {
-  /** What this task produces. Captured for restore on a cache hit. */
-  outputs: CacheOutputs
-  /**
-   * What a write to an input while the command runs means. Each field,
-   * highest first: its env var, this, the workspace's `inputStability`,
-   * the default (`'immutable'`, `'warn'`).
-   */
-  inputStability?: InputStability
-}
-
 export interface InputStability {
   /**
    * `'immutable'` (the default): any write to an input during the command
@@ -615,7 +634,7 @@ export interface InputStability {
   severity?: 'warn' | 'error'
 }
 
-export interface CacheOutputs {
+export interface TaskOutputs {
   /**
    * Files produced by this task, as project-relative globs. Pass `[]`
    * when the task has no files to capture (e.g. `lint`, `typecheck`).
@@ -640,7 +659,7 @@ export interface CacheOutputs {
    * (tsc's `.tsbuildinfo`) instead of removing them first. A run that
    * leaves a file it found untouched saves nothing, so an entry holds only
    * what a clean run would leave. A retry still starts clean. Omitted →
-   * the workspace's `cache.outputs.clean`, else `true`.
+   * the workspace's `outputs.clean`, else `true`.
    */
   clean?: boolean
 }
@@ -716,6 +735,13 @@ export interface InputsConfig {
    * tool versions, OS info, etc.
    */
   workspaceRuntime?: readonly string[]
+  /**
+   * What a write to an input while the command runs means for the save.
+   * Each field, highest first: its env var, this, the workspace's
+   * `inputs.stability`, the default (`'immutable'`, `'warn'`). Needs
+   * `cache: true`.
+   */
+  stability?: InputStability
 }
 
 /**
@@ -785,9 +811,7 @@ export function defineProject<const T extends ProjectConfig>(
           dependsOn?: readonly DependsOnEntry<Extract<keyof NonNullable<T['tasks']>, string>>[]
           exec?: Known<At<NonNullable<T['tasks']>[K], 'exec'>, ExecConfig>
           inputs?: Known<At<NonNullable<T['tasks']>[K], 'inputs'>, InputsConfig>
-          cache?: Known<At<NonNullable<T['tasks']>[K], 'cache'>, CacheConfig> & {
-            outputs?: Known<At<At<NonNullable<T['tasks']>[K], 'cache'>, 'outputs'>, CacheOutputs>
-          }
+          outputs?: Known<At<NonNullable<T['tasks']>[K], 'outputs'>, TaskOutputs>
         }
       }
     },
@@ -801,9 +825,11 @@ export function defineWorkspace<T extends WorkspaceConfig>(
       run?: Known<At<T, 'run'>, RunSettings> & {
         rules?: Known<At<At<T, 'run'>, 'rules'>, WorkspaceRules>
       }
-      cache?: Known<At<T, 'cache'>, CacheSettings> & {
-        inputStability?: Known<At<At<T, 'cache'>, 'inputStability'>, InputStability>
+      cache?: Known<At<T, 'cache'>, CacheSettings>
+      inputs?: Known<At<T, 'inputs'>, WorkspaceInputs> & {
+        stability?: Known<At<At<T, 'inputs'>, 'stability'>, InputStability>
       }
+      outputs?: Known<At<T, 'outputs'>, WorkspaceOutputs>
       lock?: Known<At<T, 'lock'>, LockSettings>
       watch?: Known<At<T, 'watch'>, WatchSettings>
     },

package/src/exec/env.ts

@@ -39,7 +39,9 @@ export interface BuildEnvOptions {
 }
 
 export function buildIsolatedEnv(opts: BuildEnvOptions): NodeJS.ProcessEnv {
-  const out: NodeJS.ProcessEnv = {}
+  // No prototype: on `{}`, a name `__proto__` hit the setter and reached
+  // no task, though the key folded it.
+  const out: NodeJS.ProcessEnv = Object.create(null)
 
   for (const name of ESSENTIAL_ENV) {
     const value = opts.source[name]