@vzn/vx 0.0.645 → 0.0.648

package/src/cli/plan-format.ts

@@ -1,7 +1,17 @@
 // Formatters for `--dry` (human / JSON).
 
 import type { AffectedReason, CacheStatus, RunPlan } from '../orchestrator/index.js'
-import { formatBytes, formatElapsed, maskedCommand } from '../util/index.js'
+import { skippedReason } from '../report/index.js'
+import {
+  formatBytes,
+  formatElapsed,
+  maskedCommand,
+  paint,
+  SUCCESS,
+  ui,
+  WARN,
+  type ColorSupport,
+} from '../util/index.js'
 
 /**
  * Human-readable preview. One line per real task (groups hidden, same
@@ -16,25 +26,36 @@ import { formatBytes, formatElapsed, maskedCommand } from '../util/index.js'
  *   3 task(s) planned, 2 cache hits (1 local, 1 remote), 1 would run.
  *   predicted: ~1.20s wall · ~1.20s total execution
  */
-export function formatPlanText(plan: RunPlan): string {
-  const real = plan.tasks.filter((t) => t.cacheStatus !== 'group')
-  if (real.length === 0) return 'No tasks planned.\n'
+export function formatPlanText(plan: RunPlan, c: ColorSupport = { enabled: false }): string {
+  // A group the platform skip reaches is still a group: it runs nothing.
+  const real = plan.tasks.filter(
+    (t) =>
+      t.cacheStatus !== 'group' &&
+      (t.cacheStatus !== 'skipped' || t.node.config.exec !== undefined),
+  )
+  const dim = (s: string): string => paint('', s, c, { dim: true })
+  if (real.length === 0) return `${dim('No tasks planned.')}\n`
 
   const idWidth = Math.max(...real.map((t) => t.node.id.length))
   const tagWidth = 24
 
-  const lines: string[] = ['would run:']
+  const lines: string[] = [paint('', 'would run:', c, { bold: true })]
   let local = 0
   let remote = 0
   let miss = 0
   let nocache = 0
   let noop = 0
   let idle = 0
+  let platform = 0
   for (const t of real) {
     // `@noop`: the run succeeds it without running, whatever its key says.
-    const skipped = t.executor === 'noop'
+    const skipped = t.executor === 'noop' && t.cacheStatus !== 'skipped'
     const sym = skipped ? '·' : symbolFor(t.cacheStatus)
-    const desc = skipped ? 'noop — would not run' : describe(t.cacheStatus)
+    const desc = skipped
+      ? 'noop — would not run'
+      : t.cacheStatus === 'skipped'
+        ? `skipped — ${skippedReason(t)}`
+        : describe(t.cacheStatus)
     const shortHash = t.hash ? t.hash.slice(0, 8) : ''
     const executes = !skipped && (t.cacheStatus === 'miss' || t.cacheStatus === 'no-cache')
     const eta = executes && t.p50Ms !== undefined ? `  ~${formatElapsed(t.p50Ms)}` : ''
@@ -43,17 +64,18 @@ export function formatPlanText(plan: RunPlan): string {
     // tier, and a task placed on a named executor is what the reader can
     // act on. Present only when the workspace declared a choice.
     const where = t.executor !== undefined ? `  @${t.executor}` : ''
+    const hue = skipped ? '' : HUE[t.cacheStatus]
     lines.push(
-      `  ${sym}  ${t.node.id.padEnd(idWidth)}  ${desc.padEnd(tagWidth)}  ${shortHash}${eta}${where}`,
+      `  ${paint(hue, sym, c, { dim: hue === '' })}  ${ui.inline(ui.id(t.node.id), c)}${' '.repeat(idWidth - t.node.id.length)}  ${paint(hue, desc.padEnd(tagWidth), c, { dim: hue === '' })}  ${dim(shortHash)}${dim(eta)}${where}`,
     )
     // Optional one-line description from the task config, indented
     // under the id so the eye picks up the task → blurb mapping.
     const taskDesc = shownDescription(t)
     if (taskDesc) {
-      lines.push(`     ${' '.repeat(idWidth)}  ${taskDesc}`)
+      lines.push(`     ${' '.repeat(idWidth)}  ${dim(taskDesc)}`)
     }
     if (t.affected !== undefined) {
-      lines.push(`     ${' '.repeat(idWidth)}  affected: ${describeReason(t.affected)}`)
+      lines.push(`     ${' '.repeat(idWidth)}  ${dim(`affected: ${describeReason(t.affected)}`)}`)
     }
     if (skipped) noop++
     else if (t.cacheStatus === 'hit-local') local++
@@ -61,6 +83,7 @@ export function formatPlanText(plan: RunPlan): string {
     else if (t.cacheStatus === 'miss') miss++
     else if (t.cacheStatus === 'no-cache') nocache++
     else if (t.cacheStatus === 'not-started') idle++
+    else if (t.cacheStatus === 'skipped') platform++
   }
 
   const hitParts: string[] = []
@@ -77,8 +100,9 @@ export function formatPlanText(plan: RunPlan): string {
   if (nocache > 0) summary.push(`${nocache} no-cache`)
   if (noop > 0) summary.push(`${noop} noop`)
   if (idle > 0) summary.push(`${idle} not started`)
+  if (platform > 0) summary.push(`${platform} skipped`)
   lines.push('')
-  lines.push(summary.join(', ') + '.')
+  lines.push(dim(summary.join(', ') + '.'))
 
   // `--cache-download` is invisible without this: the eligibility gate silently
   // keeps producers eager, so a user who asked for `none` and got no
@@ -89,11 +113,14 @@ export function formatPlanText(plan: RunPlan): string {
   if (deferred.length > 0 || downgrades.length > 0) {
     lines.push('')
     lines.push(
-      `download: ${deferred.length} task(s) would keep outputs remote` +
-        (downgrades.length > 0 ? `, ${downgrades.length} kept eager:` : '.'),
+      dim(
+        `download: ${deferred.length} task(s) would keep outputs remote` +
+          (downgrades.length > 0 ? `, ${downgrades.length} kept eager:` : '.'),
+      ),
     )
-    for (const d of downgrades.slice(0, 3)) lines.push(`    ${d.taskId} — ${d.reason}`)
-    if (downgrades.length > 3) lines.push(`    …and ${downgrades.length - 3} more`)
+    for (const d of downgrades.slice(0, 3))
+      lines.push(`    ${ui.inline(ui.id(d.taskId), c)} ${dim(`— ${d.reason}`)}`)
+    if (downgrades.length > 3) lines.push(dim(`    …and ${downgrades.length - 3} more`))
   }
 
   // Time prediction — only when history gave us something to say: at least
@@ -106,7 +133,7 @@ export function formatPlanText(plan: RunPlan): string {
     if (p.unknownCount > 0) {
       parts.push(`${p.unknownCount} task${p.unknownCount === 1 ? '' : 's'} without history (+?)`)
     }
-    lines.push(parts.join(' · '))
+    lines.push(dim(parts.join(' · ')))
   }
   return lines.join('\n') + '\n'
 }
@@ -149,6 +176,8 @@ export interface PlanTaskJson {
   download?: 'deferred'
   description?: string
   affected?: AffectedReason
+  otherPlatform?: { readonly needs: readonly string[]; readonly host: string }
+  blockedBy?: string
 }
 
 /** `affectedBase`: the ref a bare `--affected` guessed (or was given), so a reader knows what the diff was against. */
@@ -157,42 +186,51 @@ export function formatPlanJson(
   affectedBase?: string,
 ): string {
   return (
-    JSON.stringify(
-      {
-        ...(affectedBase !== undefined ? { affectedBase } : {}),
-        tasks: plan.tasks.map((t): PlanTaskJson => {
-          const description = shownDescription(t)
-          return {
-            id: t.node.id,
-            project: t.node.projectName,
-            task: t.node.taskName,
-            hash: t.hash,
-            cacheStatus: t.cacheStatus,
-            deps: t.deps,
-            ...(t.p50Ms !== undefined ? { p50Ms: t.p50Ms } : {}),
-            ...(t.executor !== undefined ? { executor: t.executor } : {}),
-            ...(t.download !== undefined ? { download: t.download } : {}),
-            ...(description !== undefined ? { description } : {}),
-            ...(t.affected !== undefined ? { affected: t.affected } : {}),
-          }
-        }),
-        ...(plan.predicted !== undefined ? { predicted: plan.predicted } : {}),
-        // The gate's refusals belong on the SCRIPTING surface too: a CI job
-        // asking "did --cache-download=none actually defer anything, and if not
-        // why" reads this, not the human table. (This object enumerates its
-        // fields deliberately — the plan's internal shape is not the wire —
-        // which is exactly why a new PlannedTask field does not appear here
-        // for free, and why `download` above had to be added by hand.)
-        ...(plan.downloadDowngrades !== undefined
-          ? { downloadDowngrades: plan.downloadDowngrades }
-          : {}),
-      },
-      null,
-      2,
-    ) + '\n'
+    JSON.stringify({
+      ...(affectedBase !== undefined ? { affectedBase } : {}),
+      tasks: plan.tasks.map((t): PlanTaskJson => {
+        const description = shownDescription(t)
+        return {
+          id: t.node.id,
+          project: t.node.projectName,
+          task: t.node.taskName,
+          hash: t.hash,
+          cacheStatus: t.cacheStatus,
+          deps: t.deps,
+          ...(t.p50Ms !== undefined ? { p50Ms: t.p50Ms } : {}),
+          ...(t.executor !== undefined ? { executor: t.executor } : {}),
+          ...(t.download !== undefined ? { download: t.download } : {}),
+          ...(description !== undefined ? { description } : {}),
+          ...(t.affected !== undefined ? { affected: t.affected } : {}),
+          ...(t.otherPlatform !== undefined ? { otherPlatform: t.otherPlatform } : {}),
+          ...(t.blockedBy !== undefined ? { blockedBy: t.blockedBy } : {}),
+        }
+      }),
+      ...(plan.predicted !== undefined ? { predicted: plan.predicted } : {}),
+      // The gate's refusals belong on the SCRIPTING surface too: a CI job
+      // asking "did --cache-download=none actually defer anything, and if not
+      // why" reads this, not the human table. (This object enumerates its
+      // fields deliberately — the plan's internal shape is not the wire —
+      // which is exactly why a new PlannedTask field does not appear here
+      // for free, and why `download` above had to be added by hand.)
+      ...(plan.downloadDowngrades !== undefined
+        ? { downloadDowngrades: plan.downloadDowngrades }
+        : {}),
+    }) + '\n'
   )
 }
 
+/** A hit is green, a task that would run is yellow, the rest dim. */
+const HUE: Record<CacheStatus, string> = {
+  'hit-local': SUCCESS,
+  'hit-remote': SUCCESS,
+  miss: WARN,
+  'no-cache': WARN,
+  group: '',
+  'not-started': '',
+  skipped: '',
+}
+
 function symbolFor(s: CacheStatus): string {
   switch (s) {
     case 'hit-local':
@@ -207,6 +245,8 @@ function symbolFor(s: CacheStatus): string {
       return '○'
     case 'not-started':
       return '−'
+    case 'skipped':
+      return '·'
   }
 }
 
@@ -224,5 +264,7 @@ function describe(s: CacheStatus): string {
       return 'group task'
     case 'not-started':
       return 'not started (unneeded)'
+    case 'skipped':
+      return 'skipped'
   }
 }

package/src/cli/plugin-commands.ts

@@ -9,9 +9,23 @@
 
 import type { CachePolicy, PluginCache, ResolvedRemote } from '../cache/index.js'
 import type { WorkspaceConfig } from '../config.js'
-import type { BranchFacts, VxPlugin, PluginCommand, CommandContext } from '../orchestrator/index.js'
+import type {
+  BranchFacts,
+  VxPlugin,
+  PluginCommand,
+  CommandContext,
+  CacheFacts,
+  TaskArtifacts,
+} from '../orchestrator/index.js'
 import { configuredBaseBranch, findWorkspaceRoot } from '../workspace/index.js'
-import { machineParallelism, maskedLine } from '../util/index.js'
+import {
+  machineParallelism,
+  maskedLine,
+  SecretBroker,
+  thrownMessage,
+  ui,
+  UserError,
+} from '../util/index.js'
 import { resolveSetting } from '../settings.js'
 
 export interface ResolvedPluginCommand {
@@ -45,7 +59,7 @@ async function workspacePlugins(cwd: string): Promise<
   | {
       workspaceRoot: string
       cacheDir: string
-      storeRoot: Promise<string | null>
+      storeRoot: () => Promise<string | null>
       workspaceConfig: WorkspaceConfig | null
       concurrency: number
       plugins: readonly VxPlugin[]
@@ -65,7 +79,7 @@ async function workspacePlugins(cwd: string): Promise<
     const { loadCliWorkspace } = await import('./workspace-config.js')
     ws = await loadCliWorkspace(workspaceRoot)
   } catch (err) {
-    return { loadError: err instanceof Error ? err.message : String(err) }
+    return { loadError: thrownMessage(err) }
   }
   return {
     workspaceRoot,
@@ -97,8 +111,10 @@ export async function resolvePluginCommand(
   const declaredVerbs = new Set<string>()
   for (const plugin of ws.plugins) {
     for (const declared of Object.keys(plugin.commands ?? {})) declaredVerbs.add(declared)
-    const command = plugin.commands?.[verb]
-    if (command === undefined) continue
+    // Own keys only: `vx toString` found Object.prototype's and crashed.
+    const commands = plugin.commands
+    if (commands === undefined || !Object.hasOwn(commands, verb)) continue
+    const command = commands[verb]!
     return {
       plugin,
       command,
@@ -111,6 +127,8 @@ export async function resolvePluginCommand(
           : [process.execPath, Bun.main],
         warn,
         cache: lazyCache(() => verbCache(ws, plugin.name)),
+        artifacts: lazyArtifacts(() => verbArtifacts(ws)),
+        artifactsFor: (facts) => lazyArtifacts(() => verbArtifacts(ws, facts)),
       },
     }
   }
@@ -118,7 +136,7 @@ export async function resolvePluginCommand(
 }
 
 const warn = (m: string): void => {
-  process.stderr.write(`${maskedLine(m)}\n`)
+  ui.say('warn', maskedLine(m))
 }
 
 /** Read-only: a verb reads what runs stored, and only a run's policy may write. */
@@ -138,7 +156,7 @@ async function verbCache(
   ws: Exclude<Awaited<ReturnType<typeof workspacePlugins>>, UnresolvedPluginCommand | null>,
   plugin: string,
 ): Promise<PluginCache> {
-  const [{ Cache, pluginCache }, { cacheRefs, resolveCache, resolveCacheScope }] =
+  const [{ Cache, pluginCache }, { cacheRefs, openRemotes, resolveCache, resolveCacheScope }] =
     await Promise.all([import('../cache/index.js'), import('../orchestrator/index.js')])
   const scope = resolveCacheScope(
     ws.workspaceRoot,
@@ -152,7 +170,7 @@ async function verbCache(
     ws.workspaceRoot,
     undefined,
     'open',
-    await ws.storeRoot,
+    await ws.storeRoot(),
   )
   const remotes: ResolvedRemote[] = []
   await resolveCache(ws.plugins, {
@@ -160,14 +178,123 @@ async function verbCache(
     cacheDir: ws.cacheDir,
     warn,
     scope,
-    refs: cacheRefs(ws.workspaceRoot, configuredBaseBranch(ws.workspaceConfig)),
+    refs: cacheRefs(ws.workspaceRoot, configuredBaseBranch(ws.workspaceConfig), ws.branch.refs),
     localCache,
     policy: VERB_POLICY,
     remotes,
   })
+  await openVerbRemotes(remotes, openRemotes)
   return pluginCache(plugin, { db: localCache.dbHandle(), policy: VERB_POLICY, remotes, scope })
 }
 
+/**
+ * The verb's `ctx.artifacts`: the workspace's cache as a run opens it, its
+ * policy and scope, a laptop writing no remote unless the policy names it.
+ * With `facts` (`ctx.artifactsFor`), under another run's refs and lent access.
+ */
+async function verbArtifacts(
+  ws: Exclude<Awaited<ReturnType<typeof workspacePlugins>>, UnresolvedPluginCommand | null>,
+  facts?: () => CacheFacts | undefined,
+): Promise<TaskArtifacts> {
+  const [
+    { Cache, FULL_CACHE_POLICY, parseCachePolicy },
+    {
+      cacheRefs,
+      namesRemote,
+      openRemotes,
+      resolveCache,
+      resolveCacheScope,
+      taskArtifacts,
+      workspaceCachePolicy,
+    },
+    { onCI },
+  ] = await Promise.all([
+    import('../cache/index.js'),
+    import('../orchestrator/index.js'),
+    import('./run.js'),
+  ])
+  // `VX_CACHE_POLICY` beats the workspace's `cache.policy`, as it does for a
+  // run, refused as `parseRunArgs` refuses it (cli/run.ts).
+  const envSpec = process.env['VX_CACHE_POLICY'] || undefined
+  let asked: CachePolicy
+  if (envSpec === undefined) {
+    asked = workspaceCachePolicy(ws.workspaceConfig) ?? FULL_CACHE_POLICY
+  } else {
+    if (!envSpec.split(',').some((seg) => seg.trim().length > 0))
+      throw new UserError(
+        'VX_CACHE_POLICY needs a spec like local:r, local:rw, remote:, or local:,remote:rw',
+        'VX_E_USAGE',
+      )
+    try {
+      asked = parseCachePolicy(envSpec)
+    } catch (err) {
+      throw new UserError(
+        `VX_CACHE_POLICY: ${err instanceof Error ? err.message : String(err)}`,
+        'VX_E_USAGE',
+      )
+    }
+  }
+  const policy: CachePolicy =
+    onCI(process.env['CI']) || namesRemote(envSpec ?? ws.workspaceConfig?.cache?.policy)
+      ? asked
+      : { ...asked, remoteWrite: false }
+  const scope = resolveCacheScope(
+    ws.workspaceRoot,
+    ws.branch.trusted === true ? null : ws.branch.scope,
+    ws.plugins.some((p) => p.cache !== undefined),
+    configuredBaseBranch(ws.workspaceConfig),
+  )
+  const localCache = new Cache(
+    ws.cacheDir,
+    { read: policy.localRead, write: policy.localWrite },
+    ws.workspaceRoot,
+    undefined,
+    'open',
+    await ws.storeRoot(),
+  )
+  const remotes: ResolvedRemote[] = []
+  const cache = await resolveCache(ws.plugins, {
+    workspaceRoot: ws.workspaceRoot,
+    cacheDir: ws.cacheDir,
+    warn,
+    scope,
+    refs:
+      facts?.()?.refs ??
+      cacheRefs(ws.workspaceRoot, configuredBaseBranch(ws.workspaceConfig), ws.branch.refs),
+    localCache,
+    policy,
+    remotes,
+    ...(facts === undefined ? {} : { lentBy: () => facts()?.lent }),
+  })
+  await openVerbRemotes(remotes, openRemotes)
+  return taskArtifacts(cache, ws.workspaceRoot)
+}
+
+/**
+ * Each remote's `open`, as a run's: a remote that takes its token there
+ * (turboCache's OIDC exchange, a lent token) had none, so an agent's
+ * uploads went nowhere and its run could not restore them.
+ */
+async function openVerbRemotes(
+  remotes: readonly ResolvedRemote[],
+  open: (typeof import('../orchestrator/index.js'))['openRemotes'],
+): Promise<void> {
+  const ci = (await import('./run.js')).onCI(process.env['CI'])
+  await open(remotes, ci, new SecretBroker(ci, warn))
+}
+
+function lazyArtifacts(open: () => Promise<TaskArtifacts>): TaskArtifacts {
+  let opened: Promise<TaskArtifacts> | undefined
+  const artifacts = (): Promise<TaskArtifacts> => (opened ??= open())
+  return {
+    save: async (key, task, run) => (await artifacts()).save(key, task, run),
+    restore: async (key, task) => (await artifacts()).restore(key, task),
+    output: async (key) => (await artifacts()).output(key),
+    share: async (key) => (await artifacts()).share(key),
+    resend: async (key) => (await artifacts()).resend(key),
+  }
+}
+
 function lazyCache(open: () => Promise<PluginCache>): PluginCache {
   let opened: Promise<PluginCache> | undefined
   const cache = (): Promise<PluginCache> => (opened ??= open())
@@ -202,8 +329,30 @@ export async function pluginCommandHelp(cwd = process.cwd()): Promise<string[]>
     for (const [verb, command] of Object.entries(plugin.commands ?? {})) {
       if (seen.has(verb)) continue
       seen.add(verb)
-      lines.push(`  vx ${verb.padEnd(17)} ${command.description} (${plugin.name})`)
+      lines.push(
+        ...helpLines(`  vx ${verb.padEnd(17)} `, `${command.description} (${plugin.name})`),
+      )
     }
   }
   return lines
 }
+
+/**
+ * One help entry: `head` then `text` wrapped at word breaks under the
+ * column `head` ends at, at core's reference width, so a plugin's long
+ * description reads as core's own entries do.
+ */
+function helpLines(head: string, text: string, width = 88): string[] {
+  const indent = ' '.repeat(head.length)
+  const lines: string[] = []
+  let line = head
+  for (const word of text.split(/\s+/)) {
+    const fresh = line === head || line === indent
+    if (!fresh && line.length + 1 + word.length > width) {
+      lines.push(line)
+      line = indent + word
+    } else line += fresh ? word : ` ${word}`
+  }
+  lines.push(line)
+  return lines
+}