@vzn/vx 0.0.632 → 0.0.633

package/src/cli/upgrade.ts

@@ -13,7 +13,7 @@
 // deno upgrade — "update" is what package managers do to indexes.
 
 import { constants } from 'node:fs'
-import { access, chmod, chown, link, rename, rm, stat } from 'node:fs/promises'
+import { access, chmod, chown, link, mkdtemp, rename, rm, stat } from 'node:fs/promises'
 import path from 'node:path'
 import { flagHint, seeHelp } from './help.js'
 import { UserError } from '../util/index.js'
@@ -247,8 +247,20 @@ export async function replaceBinary(
       `vx upgrade: the download did not match the release's SHA-256 (expected ${sha256}, got ${got}) — nothing replaced; try again, and if it repeats the asset is not the one the release published`,
     )
   }
-  const tmp = `${dest}.upgrade-${process.pid}`
-  const old = `${dest}.previous-${process.pid}`
+  // A fresh directory beside the binary, not a name built from the pid:
+  // anyone who can write the install directory could plant a link at a
+  // predictable name, and a `sudo vx upgrade` wrote through it as root.
+  let stage: string
+  try {
+    stage = await mkdtemp(path.join(dir, '.vx-upgrade-'))
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    throw new UserError(
+      `vx upgrade: could not stage the new binary in ${dir} (${msg}) — nothing replaced; check the permissions of ${dir}`,
+    )
+  }
+  const tmp = path.join(stage, 'new')
+  const old = path.join(stage, 'previous')
   let kept = false
   try {
     const was = await stat(dest).catch(() => null)
@@ -265,18 +277,18 @@ export async function replaceBinary(
     }
     await rename(tmp, dest)
   } catch (err) {
-    await rm(tmp, { force: true })
-    if (kept) await rm(old, { force: true })
+    await rm(stage, { recursive: true, force: true })
     const msg = err instanceof Error ? err.message : String(err)
     throw new UserError(
       `vx upgrade: could not replace ${dest} (${msg}) — nothing replaced; check the permissions of ${dest} and its directory`,
     )
   }
   if (starts === undefined || starts(dest)) {
-    if (kept) await rm(old, { force: true })
+    await rm(stage, { recursive: true, force: true })
     return
   }
   if (kept) await rename(old, dest)
+  await rm(stage, { recursive: true, force: true })
   throw new UserError(
     `vx upgrade: the new binary did not start on this machine (\`${dest} --version\` failed)${kept ? ' — the previous vx is back in place' : ''}. Nothing else changed; report it with this os/arch`,
   )

package/src/graph/task-graph.ts

@@ -109,7 +109,7 @@ export function isGroupTask(node: TaskNode): boolean {
   return node.config.exec === undefined
 }
 
-/** The default `build` (orchestrator/projects.ts): a config cannot key a group, so it is the one keyed group. */
+/** A keyed group: the default `build` (orchestrator/projects.ts), or a config's group with `cache`. */
 function isKeyedGroup(task: TaskConfig): boolean {
   return task.exec === undefined && task.cache !== undefined
 }
@@ -1505,8 +1505,8 @@ interface Side {
  * `inputs.files` rebased to the root against another task's
  * `outputs.workspaceFiles`, which may land in any project (X-135). A task's own outputs are
  * already subtracted from its inputs, and an output the reader's `!` entries
- * take back whole is no overlap. A keyed group is exempt: the default
- * `build` reads `**` of a config-less dependency and runs nothing, and its
+ * take back whole is no overlap. A keyed group is exempt: it runs nothing
+ * (the default `build` reads `**` of a config-less dependency), and its
  * key waits as before.
  */
 function detectInputOverlaps(nodes: Map<string, TaskNode>, workspaceRoot?: string): void {

package/src/orchestrator/metrics.ts

@@ -610,10 +610,17 @@ export interface CacheKeyDiff {
   note: string
 }
 
-function loadEntryInputs(db: Database, entryHash: string): TaskInputComponent[] {
-  return db
-    .query('SELECT kind, name, hash FROM entry_inputs WHERE entry_hash = ?')
-    .all(entryHash) as TaskInputComponent[]
+/** An entry's key components, from its one `entry_inputs` row (v34); none when it has none. */
+export function loadEntryInputs(db: Database, entryHash: string): TaskInputComponent[] {
+  const row = db
+    .query('SELECT components FROM entry_inputs WHERE entry_hash = ?')
+    .get(entryHash) as { components: string } | null
+  if (row === null) return []
+  return (JSON.parse(row.components) as [string, string, string][]).map(([kind, name, hash]) => ({
+    kind,
+    name,
+    hash,
+  }))
 }
 
 /**

package/src/orchestrator/miss-reason.ts

@@ -4,11 +4,11 @@
 //
 // Paid only when a telemetry sink exists, and only on a miss: one scan of
 // `entries` for the newest entry per task, the first time a miss asks, then
-// one primary-key read of that entry's `entry_inputs` per miss.
+// one primary-key read of that entry's `entry_inputs` row per miss.
 
 import type { Database } from 'bun:sqlite'
 import type { InputChanges } from '../graph/index.js'
-import { diffKeyComponents } from './metrics.js'
+import { diffKeyComponents, loadEntryInputs } from './metrics.js'
 import type { TaskInputComponent } from './task-hash.js'
 
 /** How many changed components a miss names; `count` says how many there were. */
@@ -37,9 +37,7 @@ export function createMissExplainer(db: Database): MissExplainer {
       )
       const prev = newest.get(taskId)
       if (prev === undefined) return undefined
-      const before = db
-        .query('SELECT kind, name, hash FROM entry_inputs WHERE entry_hash = ?')
-        .all(prev) as TaskInputComponent[]
+      const before = loadEntryInputs(db, prev)
       // Pruned, or saved before fingerprints were kept: nothing to compare.
       if (before.length === 0) return undefined
       const { entries } = diffKeyComponents(before, components)

package/src/orchestrator/miss-save.ts

@@ -191,11 +191,12 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
     endSave()
     if (a.measure === true) {
       facts.saveMs = Math.round(performance.now() - saveStart)
-      try {
-        facts.artifactBytes = statSync(cache.outputsPath(a.hash)).size
-      } catch {
-        // No local artifact (local writes off): no size to say.
-      }
+      // No local artifact (local writes off): no size to say.
+      const size =
+        cache.artifactSize !== undefined
+          ? cache.artifactSize(a.hash)
+          : statSync(cache.outputsPath(a.hash), { throwIfNoEntry: false })?.size
+      if (size !== undefined) facts.artifactBytes = size
     }
     // The files the task just wrote are the entry's bytes: stamp them,
     // so the next hit can tell them from another entry's with the same

package/src/orchestrator/projects.ts

@@ -328,8 +328,8 @@ export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjec
  * one (owner, 2026-10-04): a group behind `^build`, keyed on every file of
  * the project. A package consumed as source then carries its files to every
  * dependent behind `^build`, in the key and in `--affected`, and the chain
- * through it to deeper builds holds. The one keyed group: a config cannot
- * declare `cache` on a group (config-schema.ts), so nothing else is.
+ * through it to deeper builds holds. A keyed group, as a config may
+ * declare one (config-schema.ts).
  */
 const DEFAULT_BUILD: TaskConfig = Object.freeze({
   dependsOn: Object.freeze(['^build']),

package/src/orchestrator/task-hash.ts

@@ -411,8 +411,8 @@ function hashTaskConfig(cfg: TaskConfig, hashCache?: HashCache): string {
  * in place. Its one behavioural case is a config with NO `exec`, where
  * the spread would add `exec: {}` — and nothing reaches here that way,
  * proven by throwing on a no-exec config and running the whole suite:
- * a group takes `computeGroupKey`, and the one keyed group (the default
- * `build`) declares no `remote`. `timeout`/`retries` stay folded — their keys are
+ * a group takes `computeGroupKey`, and a keyed group has no `exec`, so no
+ * `remote`. `timeout`/`retries` stay folded — their keys are
  * distinct by design (see the decision log); stripping them retroactively
  * would bump CACHE_VERSION.
  */
@@ -423,8 +423,8 @@ function hashableConfig(cfg: TaskConfig): unknown {
 }
 
 /**
- * A group's key: its upstream, and for a keyed group — the default
- * `build` (projects.ts), the one group with `cache` — its own inputs too,
+ * A group's key: its upstream, and for a keyed group — one with `cache`,
+ * the default `build` (projects.ts) or a config's — its own inputs too,
  * the way a task's key folds them.
  */
 export async function computeGroupKey(args: ComputeHashArgs): Promise<string> {

package/src/util/verbs.ts

@@ -14,6 +14,7 @@ export const CORE_VERBS = [
   'info',
   'why',
   'last',
+  'docs',
   'completions',
   'help',
   'version',

package/src/workspace/config-schema.ts

@@ -616,15 +616,12 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
       // so a dependant's `^build` finds it and waits on nothing
       // (the quickstart). The comment here used to call that case
       // "almost certainly a config mistake" while the docs taught it.
-      if (dependsOn === undefined) {
+      // A keyed group (`cache` with no `exec`) is a declaration on its own:
+      // its inputs are a key that dependants fold, with no process.
+      if (dependsOn === undefined && cache === undefined) {
         throw new UserError(
-          `${where}: a task with no \`exec\` must declare \`dependsOn\` ` +
-            `(group tasks exist to chain dependencies)`,
-        )
-      }
-      if (cache !== undefined) {
-        throw new UserError(
-          `${where}: \`cache\` requires \`exec\` — a group task has nothing to cache`,
+          `${where}: a task with no \`exec\` must declare \`dependsOn\` or \`cache.inputs\` ` +
+            `(group tasks exist to chain dependencies or carry a key)`,
         )
       }
     }
@@ -852,6 +849,11 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
       if (wsOutputs !== undefined) {
         validateWorkspaceGlobs(wsOutputs, `${where}.cache.outputs.workspaceFiles`, false)
       }
+      if (exec === undefined && (outFiles.length > 0 || wsOutputs !== undefined)) {
+        throw new UserError(
+          `${where}.cache.outputs: a task with no \`exec\` writes nothing — \`outputs: { files: [] }\``,
+        )
+      }
     }
   }
 }

package/src/workspace/migration.ts

@@ -261,6 +261,11 @@ export interface ApplyMigrationArgs {
    * and compiled the config into its dist (TanStack/query, 2026-09-11).
    */
   format?: MigrationFormat
+  /**
+   * With `dry`: one JSON document on stdout (`schemas/init.json`) in place
+   * of the files and the report, so an agent reads the plan as data.
+   */
+  json?: boolean
 }
 
 export type MigrationFormat = 'ts' | 'mjs'
@@ -360,11 +365,11 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     const existing = metas.find((m) => m.dir === p.dir)?.configPath
     if (existing && existing !== path.join(p.dir, configName)) replaced.push(existing)
   }
-  if (dry) {
+  if (dry && args.json !== true) {
     for (const f of files) {
       process.stdout.write(`── ${f.relPath} ──\n${f.contents}\n`)
     }
-  } else {
+  } else if (!dry) {
     for (const f of files) await Bun.write(f.abs, f.contents)
     for (const f of replaced) await unlink(f)
   }
@@ -476,7 +481,29 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     ...(inGitWorkTree(root) ? [] : ['git init']),
     ...(empty ? [`declare a task as the example shows`] : []),
   ]
-  report.push('', `next: ${steps.length === 0 ? run : `${steps.join(', ')}, then ${run}`}`)
+  const next = steps.length === 0 ? run : `${steps.join(', ')}, then ${run}`
+  if (args.json === true) {
+    process.stdout.write(
+      `${JSON.stringify({
+        dry,
+        source,
+        files: files.map((f) => ({ path: f.relPath, contents: f.contents })),
+        kept,
+        replaced: replaced.map((f) => relPosix(root, f)),
+        todos: [...todos].map(([reason, tasks]) => ({ reason, tasks })),
+        notes: [
+          ...(empty && unreached.length > 0 ? [unreachedHint(unreached, root)] : []),
+          ...(empty ? noMembers : []),
+          ...(args.notes ?? []),
+          ...plan.headerNotes,
+          ...plan.notes,
+        ],
+        next,
+      })}\n`,
+    )
+    return 0
+  }
+  report.push('', `next: ${next}`)
   process.stdout.write(`${report.join('\n')}\n`)
   return 0
 }