@vzn/vx 0.0.16 → 0.0.21

package/src/cli/plan-format.ts

@@ -1,17 +1,20 @@
 // Formatters for `--dry-run` (human / JSON) and `--graph` (DOT).
 
 import type { CacheStatus, RunPlan } from '../orchestrator/index.js'
+import { formatDuration } from '../orchestrator/index.js'
 
 /**
  * Human-readable preview. One line per real task (groups hidden, same
- * as the live runner), tagged with predicted cache outcome.
+ * as the live runner), tagged with predicted cache outcome. A would-run
+ * task with recorded history also shows its typical duration (~p50).
  *
  *   would run:
  *     ✓  @vzn/vx#lint       cache hit (local)        abc12345
  *     ↓  @vzn/vx#test       cache hit (remote)       def67890
- *     ▶  @vzn/vx#build      cache miss — would exec  fedcba98
+ *     ▶  @vzn/vx#build      cache miss — would exec  fedcba98  ~1.2s
  *
  *   3 task(s) planned: 2 cache hits (1 local, 1 remote), 1 would run.
+ *   predicted: ~1.2s wall · ~1.2s total execution
  */
 export function formatPlanText(plan: RunPlan): string {
   const real = plan.tasks.filter((t) => t.cacheStatus !== 'group')
@@ -29,7 +32,16 @@ export function formatPlanText(plan: RunPlan): string {
     const sym = symbolFor(t.cacheStatus)
     const desc = describe(t.cacheStatus)
     const shortHash = t.hash ? t.hash.slice(0, 8) : ''
-    lines.push(`  ${sym}  ${t.node.id.padEnd(idWidth)}  ${desc.padEnd(tagWidth)}  ${shortHash}`)
+    const executes = t.cacheStatus === 'miss' || t.cacheStatus === 'no-cache'
+    const eta = executes && t.p50Ms !== undefined ? `  ~${formatDuration(t.p50Ms)}` : ''
+    // Placement, by EXECUTOR NAME rather than a local/remote word: the
+    // summary line below already spends "local" and "remote" on the cache
+    // 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}` : ''
+    lines.push(
+      `  ${sym}  ${t.node.id.padEnd(idWidth)}  ${desc.padEnd(tagWidth)}  ${shortHash}${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 = t.node.config.description
@@ -52,6 +64,35 @@ export function formatPlanText(plan: RunPlan): string {
   if (nocache > 0) summary.push(`${nocache} no-cache`)
   lines.push('')
   lines.push(summary.join(', ') + '.')
+
+  // `--download` is invisible without this: the eligibility gate silently
+  // keeps producers eager, so a user who asked for `none` and got no
+  // deferral has nothing to read. Say what WOULD stay remote, and name the
+  // refusals when nothing would.
+  const deferred = real.filter((t) => t.download === 'deferred')
+  const downgrades = plan.downloadDowngrades ?? []
+  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:` : '.'),
+    )
+    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`)
+  }
+
+  // Time prediction — only when history gave us something to say: at least
+  // one would-run task has a p50 (an all-unknown prediction is pure noise).
+  const p = plan.predicted
+  const executes = miss + nocache
+  if (p !== undefined && executes > 0 && executes > p.unknownCount) {
+    const parts = [`predicted: ~${formatDuration(p.wallMs)} wall`]
+    parts.push(`~${formatDuration(p.workMs)} total execution`)
+    if (p.unknownCount > 0) {
+      parts.push(`${p.unknownCount} task${p.unknownCount === 1 ? '' : 's'} without history (+?)`)
+    }
+    lines.push(parts.join(' · '))
+  }
   return lines.join('\n') + '\n'
 }
 
@@ -66,10 +107,24 @@ export function formatPlanJson(plan: RunPlan): string {
           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 } : {}),
+
           ...(t.node.config.description !== undefined
             ? { description: t.node.config.description }
             : {}),
         })),
+        ...(plan.predicted !== undefined ? { predicted: plan.predicted } : {}),
+        // The gate's refusals belong on the SCRIPTING surface too: a CI job
+        // asking "did --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,
@@ -89,19 +144,30 @@ export function formatPlanJson(plan: RunPlan): string {
 export function formatGraphDot(plan: RunPlan): string {
   const lines: string[] = ['digraph TaskGraph {', '  rankdir=LR;', '  node [shape=box];']
   for (const t of plan.tasks) {
-    const label = `${t.node.id}\\n${t.hash.slice(0, 8)}`
     const color = dotColor(t.cacheStatus)
-    lines.push(`  "${t.node.id}" [label="${label}", style="filled", fillcolor="${color}"];`)
+    lines.push(
+      `  ${dotString(t.node.id)} [label=${dotString(`${t.node.id}\n${t.hash.slice(0, 8)}`)}, style="filled", fillcolor="${color}"];`,
+    )
   }
   for (const t of plan.tasks) {
     for (const dep of t.deps) {
-      lines.push(`  "${dep}" -> "${t.node.id}";`)
+      lines.push(`  ${dotString(dep)} -> ${dotString(t.node.id)};`)
     }
   }
   lines.push('}')
   return lines.join('\n') + '\n'
 }
 
+/**
+ * A DOT double-quoted ID. A task name is any object key in a config, so
+ * `"`, `\` and a newline are all reachable; unescaped they end the
+ * string early and the document stops parsing. `\n` is DOT's own line
+ * break inside a label.
+ */
+function dotString(s: string): string {
+  return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\r?\n/g, '\\n')}"`
+}
+
 function symbolFor(s: CacheStatus): string {
   switch (s) {
     case 'hit-local':

package/src/cli/plugin-commands.ts

@@ -0,0 +1,103 @@
+// Plugin-contributed CLI verbs (`VxPlugin.commands`).
+//
+// Consulted only when the dispatcher has no core verb for the word: the
+// workspace config is loaded from the cwd, and the first plugin (in
+// declaration order) declaring the verb runs it. Outside a workspace, or
+// with no plugin declaring it, the answer is null and the dispatcher
+// reports an unknown command as it always did. Core's verbs are matched
+// before this is asked, so a plugin cannot shadow `run`.
+
+import type { VxPlugin, PluginCommand, CommandContext } from '../orchestrator/index.js'
+import { findWorkspaceRoot } from '../workspace/index.js'
+import { loadCliWorkspace } from './workspace-config.js'
+
+export interface ResolvedPluginCommand {
+  plugin: VxPlugin
+  command: PluginCommand
+  ctx: CommandContext
+}
+
+/**
+ * Why a verb could not be looked up: the workspace file failed to load.
+ * Surfaced next to "unknown command" rather than as the whole answer — a
+ * typo'd verb must still read as a typo, and a real plugin verb must still
+ * point at the file that broke it.
+ */
+export interface UnresolvedPluginCommand {
+  loadError: string
+}
+
+async function workspacePlugins(
+  cwd: string,
+): Promise<
+  | { workspaceRoot: string; cacheDir: string; plugins: readonly VxPlugin[] }
+  | UnresolvedPluginCommand
+  | null
+> {
+  let workspaceRoot: string
+  try {
+    workspaceRoot = await findWorkspaceRoot(cwd)
+  } catch {
+    return null
+  }
+  let ws
+  try {
+    ws = await loadCliWorkspace(workspaceRoot)
+  } catch (err) {
+    return { loadError: err instanceof Error ? err.message : String(err) }
+  }
+  return { workspaceRoot, cacheDir: ws.cacheDir, plugins: ws.plugins }
+}
+
+/**
+ * The plugin verb named `verb` for the workspace around `cwd`; null when
+ * there is none; the load error when the workspace file could not say.
+ */
+export async function resolvePluginCommand(
+  verb: string,
+  cwd = process.cwd(),
+): Promise<ResolvedPluginCommand | UnresolvedPluginCommand | null> {
+  const ws = await workspacePlugins(cwd)
+  if (ws === null) return null
+  if ('loadError' in ws) return ws
+  for (const plugin of ws.plugins) {
+    const command = plugin.commands?.[verb]
+    if (command === undefined) continue
+    return {
+      plugin,
+      command,
+      ctx: {
+        workspaceRoot: ws.workspaceRoot,
+        cacheDir: ws.cacheDir,
+        warn: (m) => process.stderr.write(`${m}\n`),
+      },
+    }
+  }
+  return null
+}
+
+/** `vx help` lines for every plugin verb in the workspace around `cwd`. */
+/** The plugin verbs the workspace around `cwd` declares, in declaration order; none when it does not load. */
+export async function pluginVerbs(cwd = process.cwd()): Promise<string[]> {
+  const ws = await workspacePlugins(cwd).catch(() => null)
+  if (ws === null || 'loadError' in ws) return []
+  const verbs = new Set<string>()
+  for (const plugin of ws.plugins)
+    for (const verb of Object.keys(plugin.commands ?? {})) verbs.add(verb)
+  return [...verbs]
+}
+
+export async function pluginCommandHelp(cwd = process.cwd()): Promise<string[]> {
+  const ws = await workspacePlugins(cwd).catch(() => null)
+  if (ws === null || 'loadError' in ws) return []
+  const lines: string[] = []
+  const seen = new Set<string>()
+  for (const plugin of ws.plugins) {
+    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})`)
+    }
+  }
+  return lines
+}