@vzn/vx 0.0.636 → 0.0.638

package/src/util/index.ts

@@ -13,6 +13,8 @@ export {
   isPermissionError,
   isUserError,
   PERMISSION_HINT,
+  refusal,
+  type RefusalParts,
   UserError,
   gitSpawnRefusal,
   isExecutableMissing,
@@ -21,7 +23,12 @@ export {
   OUT_OF_FDS_HINT,
   wantsJson,
 } from './errors.js'
-export { configErrorFrame } from './config-frame.js'
+export { configErrorFrame, configRefusal } from './config-frame.js'
+export { detectColors, ERROR, paint, SUCCESS, WARN, type ColorSupport } from './colors.js'
+export { gradientRule } from './report.js'
+import * as ui from './ui.js'
+export { refusalNotice, sayLine, sayNotice } from './refusal-notice.js'
+export { ui }
 export { xxh3, xxh3hex } from './hash.js'
 export {
   beginRun,
@@ -45,6 +52,8 @@ export {
   outputMatcher,
   printable,
   relPosix,
+  DOT_VX_GITATTRIBUTES,
+  DOT_VX_GITIGNORE,
   splitNegations,
   staticPrefix,
   stripTrailingSlash,
@@ -58,10 +67,12 @@ export {
   claimExitForSignal,
   exitClaimedBySignal,
   killGraceMs,
+  setSettleBounds,
+  type SettleBound,
   settleWithin,
   teardownTimeoutMs,
 } from './settle.js'
-export { formatBytes, parseDuration, parseSize } from './size.js'
+export { formatBytes, parseDuration, parseSize, treeBytes } from './size.js'
 export {
   cgroupCpuQuota,
   cgroupMemoryLimitBytes,
@@ -73,11 +84,13 @@ export { appendTail, createTail, resetTail, tailText, type Tail } from './tail.j
 export { ulid } from './ulid.js'
 export { splitTaskId } from './task-id.js'
 export { editDistance, listed, nearMatches, nearest } from './edit-distance.js'
-export { CORE_VERBS, MOVED_VERBS } from './verbs.js'
+export { CORE_VERBS } from './verbs.js'
 export { isUnsupportedBun, MIN_BUN, unsupportedBunMessage } from './bun-version.js'
 export { executablePath, shellArgv, taskShell } from './which.js'
 export { procfsIsOwn } from './procfs.js'
 export { hangupIgnored } from './hangup.js'
+export { ESSENTIAL_ENV } from './essential-env.js'
+export { gitEnv, helperEnv, hideEnvFromTasks } from './hide-env.js'
 export { realPath, realpathOf } from './real-path.js'
 export {
   maskedCommand,

package/src/util/paths.ts

@@ -11,6 +11,16 @@ export function toPosix(p: string): string {
   return IS_POSIX ? p : p.split(path.sep).join('/')
 }
 
+/**
+ * `.vx/.gitignore`: git ignores the machine-local `.vx/cache` and nothing
+ * else in `.vx`, so the workspace config and the lock beside it are
+ * committed. `vx init` and the cache write it when missing.
+ */
+export const DOT_VX_GITIGNORE = '/cache\n'
+
+/** `.vx/.gitattributes`' text: GitHub collapses the machine lock in a diff. */
+export const DOT_VX_GITATTRIBUTES = 'projects.lock.json linguist-generated=true\n'
+
 export function relPosix(from: string, to: string): string {
   return toPosix(path.relative(from, to))
 }

package/src/util/refusal-notice.ts

@@ -0,0 +1,111 @@
+// Every refusal vx prints, as one `ui.notice`: the parts a refusal
+// carries, a config refusal's frame, or a plain message laid out a fact a
+// line. The flat message stays what `--format json` and logs carry.
+
+import { configRefusal } from './config-frame.js'
+import type { RefusalParts } from './errors.js'
+import { notice, print, type Block, type Inline, type Tone } from './ui.js'
+
+// A sentence break before a capital, a backtick or a paren: vx joins
+// its facts with these.
+const BREAK = /(?<=[.?!])\s+(?=[A-Z`(])/
+// `(see \`vx run --help\`)`: where to read more.
+const SEE = /\s*\(see `([^`]+)`\)/
+// `(did you mean --concurrency?)`, `. Did you mean build?`: the fix.
+const MEANT = /\s*(?:\(did you mean ([^?]+)\?\)|(?:^|[.;—]\s*)[Dd]id you mean ([^?]+)\?)/
+
+const bare = (s: string): string => s.trim().replace(/[.:]$/, '')
+
+/** A plain message in parts: its first sentence heads, each later one is a line. */
+export function messageParts(message: string): RefusalParts {
+  const [head = '', ...rest] = message.split('\n')
+  let first = head
+  const see = SEE.exec(first)
+  if (see !== null) first = first.replace(SEE, '')
+  const meant = MEANT.exec(first)
+  if (meant !== null) first = first.replace(MEANT, '')
+  const sentences = first
+    .split(BREAK)
+    .map(bare)
+    .filter((s) => s !== '')
+  const [headline = bare(first), ...what] = sentences
+  for (const l of rest) {
+    if (l.trim() !== '') what.push(...l.replace(/^ {2}/, '').split(BREAK).map(bare))
+  }
+  const fix = meant !== null ? (meant[1] ?? meant[2])!.trim() : undefined
+  return {
+    headline,
+    ...(what.length > 0 ? { what } : {}),
+    ...(see !== null ? { why: `see ${see[1]}` } : {}),
+    ...(fix !== undefined ? { fix } : {}),
+  }
+}
+
+/**
+ * `✗ <verb>  <headline>` with what is wrong, why, and the fix under it.
+ * `headline` set: that is the status line and the refusal's own headline
+ * joins what is wrong (`vx lock  lock not written`).
+ */
+export function refusalNotice(
+  verb: string,
+  message: string,
+  parts?: RefusalParts,
+  opts: { headline?: string; cwd?: string } = {},
+): Block {
+  const c = parts === undefined ? configRefusal(message, opts.cwd ?? process.cwd()) : undefined
+  if (c !== undefined) {
+    const what: Inline[] = [{ style: 'bold', text: c.where }, c.problem]
+    return notice({
+      tone: 'error',
+      verb,
+      headline: opts.headline ?? 'config refused',
+      what,
+      ...(c.allowed !== undefined ? { why: `allowed: ${c.allowed}` } : {}),
+      code: c.frame,
+      ...(c.fix !== undefined ? { fix: c.fix } : {}),
+    })
+  }
+  const p = parts ?? messageParts(message)
+  const what = opts.headline !== undefined ? [p.headline, ...(p.what ?? [])] : (p.what ?? [])
+  return notice({
+    tone: p.tone ?? 'error',
+    verb,
+    headline: opts.headline ?? p.headline,
+    ...(what.length > 0 ? { what } : {}),
+    ...(p.why !== undefined ? { why: p.why } : {}),
+    ...(p.fix !== undefined ? { fix: p.fix } : {}),
+  })
+}
+
+/** A message of `tone` from `verb`, a fact a line. */
+function messageNotice(tone: Tone, verb: string, message: string): Block {
+  const p = messageParts(message)
+  return notice({
+    tone,
+    verb,
+    headline: p.headline,
+    ...(p.what !== undefined ? { what: p.what } : {}),
+    ...(p.why !== undefined ? { why: p.why } : {}),
+    ...(p.fix !== undefined ? { fix: p.fix } : {}),
+  })
+}
+
+/** A line that may open with its verb (`vx why: …`), as `messageNotice` draws it. */
+export function lineNotice(tone: Tone, line: string, verb = 'vx'): Block {
+  const named = /^(vx(?: [a-z][\w-]*)?): /.exec(line)
+  return messageNotice(
+    tone,
+    named?.[1] ?? verb,
+    named === null ? line : line.slice(named[0].length),
+  )
+}
+
+/** `messageNotice` on stderr. */
+export function sayNotice(tone: Tone, verb: string, message: string): void {
+  print('err', messageNotice(tone, verb, message))
+}
+
+/** `lineNotice` on stderr. */
+export function sayLine(tone: Tone, line: string, verb = 'vx'): void {
+  print('err', lineNotice(tone, line, verb))
+}

package/src/util/report.ts

@@ -0,0 +1,31 @@
+import { paint, type ColorSupport } from './colors.js'
+
+// Brand gradient for the rule: identity violet → pink (the project /
+// task hues), faded across the dash run. Plain dashes when colors
+// are off.
+const GRADIENT_FROM = [0xa7, 0x8b, 0xfa] as const
+const GRADIENT_TO = [0xf4, 0x72, 0xb6] as const
+// Rule ends flush with the bars: 2 indent + 8 label + 2 gap + 50 cells.
+const RULE_DASHES = 57
+
+/** Total visible rule width: `─ <mark> ` + dashes. Shared by the run summary and every report. */
+export function gradientRule(colors: ColorSupport, mark = 'vx'): string {
+  const head = `─ `
+  const dashes = '─'.repeat(Math.max(8, RULE_DASHES + 2 - mark.length))
+  if (!colors.enabled) return `${head}${mark} ${dashes}`
+  const chunks = 8
+  const per = Math.ceil(RULE_DASHES / chunks)
+  let out = ''
+  for (let i = 0; i < chunks; i++) {
+    const seg = dashes.slice(i * per, (i + 1) * per)
+    if (seg.length === 0) break
+    const f = i / (chunks - 1)
+    const hex = `#${GRADIENT_FROM.map((c, j) =>
+      Math.round(c + (GRADIENT_TO[j]! - c) * f)
+        .toString(16)
+        .padStart(2, '0'),
+    ).join('')}`
+    out += paint(hex, seg, colors)
+  }
+  return `${paint(`#${GRADIENT_FROM.map((c) => c.toString(16).padStart(2, '0')).join('')}`, head, colors)}${paint('', mark, colors, { bold: true })} ${out}`
+}

package/src/util/settle.ts

@@ -2,49 +2,68 @@
 // wrote; it must not hold the run's exit hostage.
 
 import { MAX_TIMEOUT_MS } from './num.js'
+import { parseDuration } from './size.js'
 
 /** Default upper bound on one end-of-run flush/teardown await. */
 const DEFAULT_TIMEOUT_MS = 3000
 
+/** A bound the run resolved from its flag or `.vx/workspace`. */
+export interface SettleBound {
+  readonly ms: number
+  readonly from: 'flag' | 'workspace'
+}
+
+let teardownSet: SettleBound | undefined
+let killGraceSet: SettleBound | undefined
+
 /**
- * The bound to apply, read per call so a test can drive the deadline
- * instead of waiting it out.
+ * The run's `run.teardownTimeout` and `run.killGrace` from its flag or
+ * workspace (the orchestrator resolves them; util sits below settings).
+ * The variable, read per call, sits between the two, so a test drives the
+ * deadline instead of waiting it out.
  */
-export function teardownTimeoutMs(): number {
-  const raw = process.env['VX_TEARDOWN_TIMEOUT_MS']
-  // Out-of-range falls back to the DEFAULT rather than clamping to
-  // MAX_TIMEOUT_MS, and the distinction matters. This value is a BOUND, not a
-  // duration: there is no "no limit" option here, because the whole reason the
-  // deadline exists is that a plugin's flush must not hold the run's exit
-  // hostage. Clamping would honour "wait ~24.8 days", which defeats it — the
-  // run would hang. Unbounded is worse still (the delay becomes 1 ms, so every
-  // flush times out and every buffered record is dropped). Falling back keeps
-  // the bound real in both directions.
-  if (raw !== undefined && /^[0-9]+$/.test(raw)) {
-    const n = Number(raw)
-    if (n <= MAX_TIMEOUT_MS) return n
+export function setSettleBounds(b: { teardown?: SettleBound; killGrace?: SettleBound }): void {
+  teardownSet = b.teardown
+  killGraceSet = b.killGrace
+}
+
+/**
+ * A flag's bound, else the variable's (a positive duration inside the
+ * timer's range: the CLI refuses any other before a run, and an embedder's
+ * falls back), else the workspace's.
+ */
+function bound(name: string, set: SettleBound | undefined, zero = false): number | undefined {
+  if (set?.from === 'flag') return set.ms
+  const raw = process.env[name]
+  if (raw !== undefined && raw !== '') {
+    const n = parseDuration(raw)
+    if (n !== null && (n > 0 || zero) && n <= MAX_TIMEOUT_MS) return n
   }
-  return DEFAULT_TIMEOUT_MS
+  return set?.ms
 }
 
 /**
- * The SIGTERM→SIGKILL grace a run grants a child that ignores SIGTERM: the
- * one-shot timeout escalation (`exec/runner.ts`), the signal teardown
- * (`orchestrator/signals.ts`) and the end-of-run persistent shutdown
- * (`orchestrator/persistent.ts`) share it. Two seconds
+ * The bound on one end-of-run flush or teardown (`run.teardownTimeout`).
+ * There is no "no limit": the deadline exists so a plugin's flush cannot
+ * hold the run's exit hostage, so a timer past the platform's range (which
+ * would fire at once and drop every buffered record) is no value.
+ */
+export function teardownTimeoutMs(): number {
+  return bound('VX_RUN_TEARDOWN_TIMEOUT', teardownSet, true) ?? DEFAULT_TIMEOUT_MS
+}
+
+/**
+ * The SIGTERM→SIGKILL grace a run grants a child that ignores SIGTERM
+ * (`run.killGrace`): the one-shot timeout escalation (`exec/runner.ts`),
+ * the signal teardown (`orchestrator/signals.ts`) and the end-of-run
+ * persistent shutdown (`orchestrator/persistent.ts`) share it. Two seconds
  * is generous for a real server's cleanup and is what every run waits when
- * a child wedges. `VX_KILL_GRACE_MS` overrides it, read per call and bounded
- * like the teardown deadline (out of range falls back to the default): the
- * tests that prove the escalation used to wait the full two seconds each,
- * a third of the suite's wall time for a claim a 200 ms grace proves too.
+ * a child wedges; the tests that prove the escalation used to wait the
+ * full two seconds each, a third of the suite's wall time for a claim a
+ * 200 ms grace proves too.
  */
 export function killGraceMs(defaultMs: number): number {
-  const raw = process.env['VX_KILL_GRACE_MS']
-  if (raw !== undefined && /^[0-9]+$/.test(raw)) {
-    const n = Number(raw)
-    if (n > 0 && n <= MAX_TIMEOUT_MS) return n
-  }
-  return defaultMs
+  return bound('VX_RUN_KILL_GRACE', killGraceSet) ?? defaultMs
 }
 
 /**

package/src/util/size.ts

@@ -1,3 +1,5 @@
+import { lstatSync, readdirSync } from 'node:fs'
+import path from 'node:path'
 import { parseDecimalInt } from './num.js'
 
 /**
@@ -20,25 +22,34 @@ export function parseSize(input: string): number | null {
 }
 
 /**
- * Parse `<n><unit>` where unit is s/m/h/d, case-insensitively (`parseSize`
+ * Parse `<n><unit>` where unit is ms/s/m/h/d, case-insensitively (`parseSize`
  * has always been case-insensitive; this matched only lowercase, so `30D`
  * was rejected while `1GB` and `1gb` both worked).
  */
 export function parseDuration(input: string): number | null {
-  const m = input.match(/^(\d+)([smhd])$/i)
+  const m = input.match(/^(\d+)(ms|[smhd])$/i)
   if (!m) return null
   const n = parseDecimalInt(m[1]!)
   if (n === null) return null
   // Lowercase before the switch: with the /i flag an uppercase `M` would
   // otherwise fall through to the days branch.
   const unit = m[2]!.toLowerCase()
-  const mult = unit === 's' ? 1000 : unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000
+  const mult =
+    unit === 'ms'
+      ? 1
+      : unit === 's'
+        ? 1000
+        : unit === 'm'
+          ? 60_000
+          : unit === 'h'
+            ? 3_600_000
+            : 86_400_000
   return n * mult
 }
 
 /**
  * Human-readable byte size with KB/MB/GB/TB/PB suffixes and one
- * decimal of precision below 10 of any unit. Used by `vx info`, `vx cache prune` and the
+ * decimal of precision below 10 of any unit. Used by `vx info`, `vx cache clean` and the
  * run's `cacheRetention` line.
  */
 export function formatBytes(n: number): string {
@@ -51,3 +62,11 @@ export function formatBytes(n: number): string {
   }
   return `${v.toFixed(0)} PB`
 }
+
+/** Bytes under `p` on disk, links not followed; 0 when it is missing. */
+export function treeBytes(p: string): number {
+  const st = lstatSync(p, { throwIfNoEntry: false })
+  if (st === undefined) return 0
+  if (!st.isDirectory()) return st.size
+  return readdirSync(p).reduce((n, e) => n + treeBytes(path.join(p, e)), 0)
+}

package/src/util/timing.ts

@@ -1,4 +1,5 @@
-// Stage timing for the run path, printed to stderr when `VX_TIMING` is set.
+// Stage timing for the run path, printed to stderr when `VX_DEBUG_TIMING` is
+// true (`debug.timing`; util reads it itself, below src/settings.ts).
 //
 // The CPU profiler attributes a tight loop's cost unreliably and hides
 // where an `await` waited; a stage table answers "where did the warm run
@@ -8,7 +9,7 @@
 // prints (a push per stage, ~15 a run): a telemetry sink draws them as
 // spans (`stageTimes`). The per-call `span`s stay off unless enabled.
 
-const enabled = process.env.VX_TIMING !== undefined && process.env.VX_TIMING !== ''
+const enabled = process.env.VX_DEBUG_TIMING === 'true' || process.env.VX_DEBUG_TIMING === '1'
 let t0 = Bun.nanoseconds()
 // The wall clock at t0, read then: `performance.timeOrigin` plus the
 // monotonic clock drifted 34 ms from `Date.now()` on macOS CI, so stages

package/src/util/ui.ts

@@ -0,0 +1,186 @@
+// vx's output components (org/devex/log-design.md). A verb or a plugin
+// composes these instead of writing raw lines: each component owns its
+// color, indent and spacing, so every surface shares one look. Colors
+// are decided at print time, per stream.
+
+import { detectColors, ERROR, paint, SUCCESS, WARN, type ColorSupport } from './colors.js'
+import { gradientRule } from './report.js'
+
+export type Tone = 'ok' | 'warn' | 'error' | 'info'
+
+const INFO = '#06b6d4'
+const PROJECT = '#a78bfa'
+const TASK = '#f472b6'
+const HUE: Record<Tone, string> = { ok: SUCCESS, warn: WARN, error: ERROR, info: INFO }
+const SYMBOL: Record<Tone, string> = { ok: '✓', warn: '!', error: '✗', info: '›' }
+const INDENT = '  '
+const LABEL_MIN = 8
+
+type Style = Tone | 'dim' | 'bold' | 'id'
+
+/** Styled text inside a component: a plain string, a token, or a run of them. */
+export type Inline = string | { readonly style: Style; readonly text: string } | readonly Inline[]
+
+/** A laid-out piece of output; `render` and `print` space blocks apart. */
+export interface Block {
+  readonly lines: (colors: ColorSupport) => string[]
+}
+
+/** A `project#task` id, in the run's project and task hues. */
+export const id = (text: string): Inline => ({ style: 'id', text })
+/** A path, glob or file: bold. */
+export const path = (text: string): Inline => ({ style: 'bold', text })
+/** A command to type: bold. */
+export const cmd = (text: string): Inline => ({ style: 'bold', text })
+/** A secondary fact. */
+export const dim = (text: string): Inline => ({ style: 'dim', text })
+/** Text in a tone's color. */
+export const tone = (t: Tone, text: string): Inline => ({ style: t, text })
+
+function inline(x: Inline, c: ColorSupport): string {
+  if (typeof x === 'string') return x
+  if (Array.isArray(x)) return (x as readonly Inline[]).map((p) => inline(p, c)).join('')
+  const { style, text } = x as { style: Style; text: string }
+  switch (style) {
+    case 'dim':
+      return paint('', text, c, { dim: true })
+    case 'bold':
+      return paint('', text, c, { bold: true })
+    case 'id': {
+      const hash = text.lastIndexOf('#')
+      if (hash < 0) return paint(PROJECT, text, c)
+      return paint(PROJECT, text.slice(0, hash), c) + paint(TASK, text.slice(hash), c)
+    }
+    default:
+      return paint(HUE[style], text, c)
+  }
+}
+
+const block = (lines: (c: ColorSupport) => string[]): Block => ({ lines })
+const lines = (x: Inline, c: ColorSupport): string[] => inline(x, c).split('\n')
+const visible = (s: string): number => Bun.stringWidth(s)
+
+/** `✗ vx lock  lock not written`: the tone's symbol, the bold verb, the headline. */
+export function status(t: Tone, verb: string, headline: Inline): Block {
+  return block((c) => [
+    `${paint(HUE[t], SYMBOL[t], c)} ${paint('', verb, c, { bold: true })}  ${inline(headline, c)}`,
+  ])
+}
+
+/** Indented short lines: what is wrong, or what happened. */
+export function text(...items: Inline[]): Block {
+  return block((c) => items.flatMap((i) => lines(i, c).map((l) => `${INDENT}${l}`)))
+}
+
+/** An indented dim line: why it matters. */
+export function why(line: Inline): Block {
+  return block((c) => lines(line, c).map((l) => `${INDENT}${paint('', l, c, { dim: true })}`))
+}
+
+/** A label and its values; values after the first sit under it. `null` is a blank line. */
+export type FieldRow = readonly [label: string, ...values: Inline[]] | null
+
+/** A dim label column with the values aligned beside it; `next` and `fix` are bold. */
+export function fields(rows: readonly FieldRow[]): Block {
+  return block((c) => {
+    const width = Math.max(LABEL_MIN, ...rows.map((r) => (r === null ? 0 : r[0].length)))
+    const out: string[] = []
+    for (const row of rows) {
+      if (row === null) {
+        out.push('')
+        continue
+      }
+      const [label, ...values] = row
+      const strong = label === 'next' || label === 'fix'
+      values
+        .flatMap((v) => lines(v, c))
+        .forEach((v, i) => {
+          const head =
+            i === 0 ? paint('', label.padEnd(width), c, { dim: true }) : ' '.repeat(width)
+          const value = strong ? paint('', v, c, { bold: true }) : v
+          out.push(`${INDENT}${head}  ${value}`.trimEnd())
+        })
+    }
+    return out
+  })
+}
+
+/** `fix  <action>`: what to do about it. */
+export function fix(action: Inline): Block {
+  return labelled('fix', action)
+}
+
+/** `next  <command>`: the command to type next. */
+export function next(command: Inline): Block {
+  return labelled('next', command)
+}
+
+function labelled(label: string, value: Inline): Block {
+  return block((c) => [
+    `${INDENT}${paint('', label, c, { dim: true })}  ${paint('', inline(value, c), c, { bold: true })}`,
+  ])
+}
+
+/** A report: a blank line, the brand rule naming `mark`, then its fields. */
+export function report(mark: string, rows: readonly FieldRow[]): Block {
+  return block((c) => ['', gradientRule(c, mark), ...fields(rows).lines(c)])
+}
+
+/** Aligned columns under a dim header. */
+export function table(columns: readonly string[], rows: readonly (readonly Inline[])[]): Block {
+  return block((c) => {
+    const cells = rows.map((r) => r.map((x) => inline(x, c)))
+    const widths = columns.map((h, i) =>
+      Math.max(h.length, ...cells.map((r) => visible(r[i] ?? ''))),
+    )
+    const pad = (s: string, i: number): string =>
+      i === columns.length - 1 ? s : s + ' '.repeat(widths[i]! - visible(s))
+    return [
+      `${INDENT}${paint('', columns.map((h, i) => pad(h, i)).join('  '), c, { dim: true })}`.trimEnd(),
+      ...cells.map((r) => `${INDENT}${r.map(pad).join('  ')}`.trimEnd()),
+    ]
+  })
+}
+
+/** A source frame (`> 1 | …` and its caret), indented. */
+export function code(frame: string): Block {
+  return block(() => frame.split('\n').map((l) => (l === '' ? '' : `${INDENT}${l}`)))
+}
+
+export interface NoticeParts {
+  tone: Tone
+  verb: string
+  headline: Inline
+  /** What is wrong, one fact a line. */
+  what?: readonly Inline[]
+  why?: Inline
+  /** A source frame, below the facts. */
+  code?: string
+  fix?: Inline
+}
+
+/** A refusal or a warning: status, then what and why, the frame, and the fix, a blank line apart. */
+export function notice(p: NoticeParts): Block {
+  return block((c) => {
+    const parts: Block[] = [status(p.tone, p.verb, p.headline)]
+    const body = [
+      ...(p.what !== undefined ? [text(...p.what)] : []),
+      ...(p.why !== undefined ? [why(p.why)] : []),
+    ]
+    if (body.length > 0) parts.push(block((cc) => body.flatMap((b) => b.lines(cc))))
+    if (p.code !== undefined) parts.push(code(p.code))
+    if (p.fix !== undefined) parts.push(fix(p.fix))
+    return parts.flatMap((b, i) => (i === 0 ? b.lines(c) : ['', ...b.lines(c)]))
+  })
+}
+
+/** The blocks as text, a blank line apart, ending in a newline. */
+export function render(blocks: readonly Block[], colors: ColorSupport): string {
+  return `${blocks.map((b) => b.lines(colors).join('\n')).join('\n\n')}\n`
+}
+
+/** Write the blocks to stdout (`out`) or stderr (`err`), colored for that stream. */
+export function print(stream: 'out' | 'err', ...blocks: Block[]): void {
+  const s = stream === 'out' ? process.stdout : process.stderr
+  s.write(render(blocks, detectColors(s)))
+}

package/src/util/ulid.ts

@@ -1,6 +1,6 @@
 // Run-id generator. Thin wrapper over `Bun.randomUUIDv7()` so the
 // `runId` column on `runs` carries a timestamp-ordered identifier —
-// `vx stats --since` queries can range-scan without an index on the
+// time-range queries can range-scan without an index on the
 // time column, and the IDs lexicographically sort by creation time
 // for grouping.
 //

package/src/util/verbs.ts

@@ -19,18 +19,3 @@ export const CORE_VERBS = [
   'help',
   'version',
 ] as const
-
-/**
- * Verbs core owned once and a package owns now. Not core verbs: a plugin
- * may declare them, and the dispatcher prints the
- * pointer only when no declared plugin claimed the name.
- */
-export const MOVED_VERBS: Readonly<Record<string, string>> = {
-  migrate:
-    'vx migrate moved to @vzn/vx-migrate: run `bunx @vzn/vx-migrate` (turbo.json or an Nx ' +
-    'project graph → vx.config.ts); `vx init` reads package.json scripts',
-  prune:
-    'vx prune comes from @vzn/vx-lockfile: declare pnpm(), bun(), npm() or yarn() in ' +
-    'vx.workspace.ts',
-  stats: 'vx stats was removed (H-19): run `vx info`, which prints the same report',
-}