@vzn/vx 0.0.16 → 0.0.21

package/src/orchestrator/logger.ts

@@ -3,6 +3,7 @@ import { detectColors, type ColorSupport } from './colors.js'
 import {
   formatFrameClose,
   formatFrameOpen,
+  formatPersistentTailBlock,
   formatTaskBlock,
   formatTaskExecutedLine,
   formatTaskHitLine,
@@ -17,6 +18,9 @@ import {
 } from './status-line.js'
 import { formatDuration, formatSummarySection, type RunContext } from './summary.js'
 import { isGroupTask } from '../graph/index.js'
+import { appendTail, createTail, resetTail, tailText, type Tail } from '../util/index.js'
+import { isCacheHit } from './telemetry.js'
+import { outcomeWord } from './events.js'
 
 export interface Logger {
   /** Header / footer / status text. Written verbatim, one trailing \n added. */
@@ -41,6 +45,8 @@ export interface Logger {
     requestedCount?: number
     /** Run banner context — so the live region footer matches the final summary. */
     context?: RunContext
+    /** The run's canonical start (epoch ms) — equals the final summary's `startedAt`. */
+    startedAtMs?: number
   }): void
   taskStart?(node: TaskNode): void
   /** Run finished (any outcome). Idempotent. */
@@ -56,6 +62,11 @@ export interface Logger {
  *                 Today's CI behavior; also the programmatic default.
  *   errors-only — only failed tasks print.
  *   none        — no per-task output at all.
+ *   hash-only   — one line per task: outcome word, task id, cache key.
+ *                 No frames, no log replay (Turbo `--output-logs
+ *                 hash-only` parity); the end-of-run summary still
+ *                 renders. The line is the run's audit trail: which key
+ *                 each task resolved to, without any build output.
  *   focused     — requested nodes stream raw output live (running the
  *                 task should feel like running the command directly);
  *                 dependency-pulled nodes are silent unless they fail.
@@ -71,7 +82,7 @@ export interface Logger {
  * line even if stdout happens to be a TTY.
  */
 export interface OutputView {
-  mode: 'full' | 'errors-only' | 'none' | 'focused' | 'broad'
+  mode: 'full' | 'errors-only' | 'none' | 'focused' | 'broad' | 'hash-only'
   gha?: boolean
   ci?: boolean
 }
@@ -81,22 +92,47 @@ function truthyEnv(v: string | undefined): boolean {
   return v !== undefined && v !== '' && v !== '0' && v !== 'false'
 }
 
-/** The unified outcome vocabulary word for a non-failed outcome. */
-function outcomeWord(o: TaskOutcome): string {
-  switch (o.status) {
-    case 'success':
-      return 'success'
-    case 'cache-hit':
-      return o.restored === false ? 'up-to-date' : 'restored-local'
-    case 'cache-hit-remote':
-      return o.restored === false ? 'up-to-date' : 'restored-remote'
-    default:
-      return o.status
-  }
+// ── GitHub Actions workflow-command escaping ────────────────────────
+// The runner parses `::`-prefixed LINES out of the log, so anything
+// interpolated into one has to be encoded or it changes the command's shape.
+// Both halves are reachable without malice: a task name is an arbitrary TS
+// object key (the loader accepts newlines — `run-report.ts` already escapes
+// them for the same reason), and a task can legitimately print
+// command-shaped text (a test asserting on annotation formatting, a nested
+// tool emitting its own workflow commands).
+// https://docs.github.com/actions/reference/workflow-commands-for-github-actions
+
+/** Message text. `%` first, or we would re-escape our own escapes. */
+function ghaData(value: string): string {
+  return value.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A')
+}
+
+/**
+ * A property VALUE additionally reserves `:` and `,` — the delimiters
+ * between a command's name, its properties and its message. Without this an
+ * id containing `::` truncates the annotation mid-title.
+ */
+function ghaProperty(value: string): string {
+  return ghaData(value).replace(/:/g, '%3A').replace(/,/g, '%2C')
+}
+
+/**
+ * Fence untrusted text so the runner stops interpreting workflow commands
+ * inside it. `token` must be unguessable by the fenced text itself — a fixed
+ * one could simply be printed by the task — so it is a per-run UUID.
+ */
+function ghaFence(body: string, token: string): string {
+  return `::stop-commands::${token}\n${body}::${token}::\n`
 }
 
+const cacheWordOf = (n: TaskNode): 'miss' | 'no-cache' =>
+  n.config.cache === undefined ? 'no-cache' : 'miss'
+
 export function resolveOutputView(
-  options: { outputLogs?: 'full' | 'errors-only' | 'none'; flow?: 'focused' | 'broad' },
+  options: {
+    outputLogs?: 'full' | 'errors-only' | 'none' | 'hash-only'
+    flow?: 'focused' | 'broad'
+  },
   env: Record<string, string | undefined> = process.env,
 ): OutputView {
   const ci = truthyEnv(env['CI'])
@@ -136,8 +172,6 @@ export function defaultLogger(
   // a one-liner or streamed output since the last block does.
   let lineEmitted = false
   let streamedSinceBlock = false
-  // Ids whose output went straight to the terminal (focused mode).
-  const streamed = new Set<string>()
   // True while the live stream sits mid-line (chunk without trailing
   // newline) — the frame close must not glue onto partial output.
   let streamMidLine = false
@@ -153,6 +187,28 @@ export function defaultLogger(
     return arr.length === 1 ? arr[0]! : arr.join('')
   }
 
+  // `none` is the ONE mode whose contract guarantees the output is
+  // discarded — "no per-task output at all" (docs/cli.md) — so its chunks
+  // are dropped on arrival instead of accumulated and thrown away at
+  // `taskComplete`. Buffering output the mode promises never to print made
+  // `--output-logs none`, the obvious mitigation for a chatty task, cost
+  // exactly as much memory as printing it: 400 MB of task stdout drove the
+  // vx process to 852 MiB RSS, unbounded and linear, and a warm CACHE HIT
+  // paid it too (the stored stdout is replayed through this same path).
+  //
+  // Deliberately ONLY the modes that PROMISE never to print task output —
+  // `none` and `hash-only`. The boundary is the point: `full`, `broad`,
+  // `focused` and `errors-only` all PRINT this output — for `errors-only` a
+  // failed task's log is precisely what the user asked to see — and
+  // silently truncating someone's build log is a worse failure than the
+  // memory it costs. So those modes stay unbounded by decision, not by
+  // oversight.
+  const discardsOutput = view.mode === 'none' || view.mode === 'hash-only'
+
+  // One per run, and only in GHA mode: the fence token must be something the
+  // fenced task output cannot print.
+  const ghaToken = view.gha === true ? crypto.randomUUID() : ''
+
   // All stdout flows through the writer so the status line can never
   // interleave with content. Inert (pure passthrough) on non-TTY
   // streams and in CI.
@@ -189,6 +245,8 @@ export function defaultLogger(
   let slots: (WorkerSlot | null)[] = []
   const slotQueue: WorkerSlot[] = []
   let succeeded = 0
+  // Executed with no `cache` block: never a miss, counted apart.
+  let noCache = 0
   let upToDate = 0
   let restoredLocal = 0
   let restoredRemote = 0
@@ -207,6 +265,28 @@ export function defaultLogger(
   const deferredFailures: string[] = []
   const pinnedPersistent: string[] = []
   let flushedFailures = false
+  // A persistent task (dev server, watcher, daemon) is the one task kind
+  // nothing bounds: a one-shot command's output ends when it exits, but a
+  // server writes for as long as the run lasts. So its chunks route into a
+  // bounded tail for its WHOLE life, not the unbounded per-task buffers —
+  // registered at `taskStart` and drained at `taskComplete` for the frame,
+  // then reset to keep capturing what it writes after its outcome landed
+  // (which arrives at READY, while the child keeps running) and flushed as
+  // one trailing block at runEnd.
+  //
+  // Registering only at READY was the defect: a `readyWhen` that never
+  // matches never reaches `taskComplete`, so the 64 KiB cap never engaged
+  // and its output accumulated in the ordinary per-task buffer instead —
+  // ~100 MiB/s, with no `exec.timeout` needed to reach it.
+  //
+  // `outcome` is absent until the task completes. Registration is
+  // unconditional (the bound is a memory invariant, not a display choice);
+  // only the flush is view-gated.
+  const persistentTails = new Map<
+    string,
+    { node: TaskNode; outcome?: TaskOutcome; out: Tail; err: Tail }
+  >()
+  let flushedPersistent = false
 
   const refresh = (force: boolean): void => {
     if (statusDead) return
@@ -221,7 +301,8 @@ export function defaultLogger(
         upToDate,
         restoredLocal,
         restoredRemote,
-        miss: succeeded + failed,
+        miss: succeeded + failed - noCache,
+        noCache,
         left: total - done,
         spread:
           spreadCount > 0
@@ -325,6 +406,11 @@ export function defaultLogger(
         emitLine(formatFrameOpen(node, colors))
         return
       }
+      // Bound a persistent task's output from its FIRST chunk. Waiting for
+      // its outcome would leave a never-ready one uncapped forever.
+      if (node.config.exec?.persistent !== undefined && !persistentTails.has(node.id)) {
+        persistentTails.set(node.id, { node, out: createTail(), err: createTail() })
+      }
       const slot: WorkerSlot = { id: node.id, startedMs: Date.now() }
       const free = slots.indexOf(null)
       if (free >= 0) slots[free] = slot
@@ -333,6 +419,38 @@ export function defaultLogger(
     },
     runEnd() {
       killStatus()
+      // Persistent tails first: they are context for whatever ran against
+      // the server, so they read above the failures they explain. `none`
+      // and `errors-only` state their contracts absolutely (no per-task
+      // output / only failed tasks print), so they stay silent — the tail
+      // is still captured and still bounded, just never printed. Guarded
+      // like the failures below: run() calls runEnd twice on the success
+      // path (once before the summary, once in its finally), and a
+      // kept-alive child keeps writing between the two.
+      if (!flushedPersistent) {
+        flushedPersistent = true
+        if (view.mode !== 'none' && view.mode !== 'errors-only') {
+          for (const t of persistentTails.values()) {
+            // No outcome means the task never completed — it is still
+            // pre-ready, so there is no "since ready" window to render and
+            // its buffered output belongs to the frame it never got.
+            if (t.outcome === undefined) continue
+            emitBlock(
+              formatPersistentTailBlock(
+                t.node,
+                t.outcome,
+                { stdout: tailText(t.out), stderr: tailText(t.err) },
+                { stdout: t.out.dropped, stderr: t.err.dropped },
+                colors,
+              ),
+            )
+          }
+        }
+        for (const t of persistentTails.values()) {
+          resetTail(t.out)
+          resetTail(t.err)
+        }
+      }
       // Failures end the log: every deferred frame replays here, right
       // above the summary — the ✗ one-liners marked them in the
       // stream, the full diagnostics read last where eyes land.
@@ -343,28 +461,50 @@ export function defaultLogger(
       }
     },
     taskStdout(node, chunk) {
+      if (discardsOutput) return
       if (streamsLive(node)) {
-        streamed.add(node.id)
         streamedSinceBlock = true
         if (chunk.length > 0) streamMidLine = !chunk.endsWith('\n')
         writer.write(chunk)
         return
       }
+      const tail = persistentTails.get(node.id)
+      if (tail !== undefined) {
+        appendTail(tail.out, chunk)
+        return
+      }
       pushChunk(stdoutBuffers, node.id, chunk)
     },
     taskStderr(node, chunk) {
+      if (discardsOutput) return
       if (streamsLive(node)) {
-        streamed.add(node.id)
         streamedSinceBlock = true
         if (chunk.length > 0) streamMidLine = !chunk.endsWith('\n')
         writer.write(chunk)
         return
       }
+      const tail = persistentTails.get(node.id)
+      if (tail !== undefined) {
+        appendTail(tail.err, chunk)
+        return
+      }
       pushChunk(stderrBuffers, node.id, chunk)
     },
     taskComplete(node, outcome) {
-      const stdout = takeChunks(stdoutBuffers, node.id)
-      const stderr = takeChunks(stderrBuffers, node.id)
+      // A persistent task buffered into its bounded tail rather than the
+      // per-task buffers (see taskStart), so its frame is drained from
+      // there — carrying how much the cap dropped, since a truncated log
+      // that reads as complete is worse than one that says what it lost.
+      const preReady = persistentTails.get(node.id)
+      const stdout = preReady ? tailText(preReady.out) : takeChunks(stdoutBuffers, node.id)
+      const stderr = preReady ? tailText(preReady.err) : takeChunks(stderrBuffers, node.id)
+      const dropped =
+        preReady && (preReady.out.dropped > 0 || preReady.err.dropped > 0)
+          ? { droppedStdout: preReady.out.dropped, droppedStderr: preReady.err.dropped }
+          : {}
+      // The pre-ready window closed either way: a failed task is over, and
+      // a ready one starts a fresh post-ready tail below.
+      persistentTails.delete(node.id)
       // An aborted task (child killed by a shutdown signal) reverts
       // to pending: free its worker slot, but never count or render it
       // — the run is tearing down and it has no honest outcome.
@@ -383,11 +523,18 @@ export function defaultLogger(
         done++
         if (outcome.status === 'failed') {
           failed++
+          if (node.config.cache === undefined) noCache++
         } else if (node.config.exec?.persistent !== undefined && outcome.status === 'success') {
           // A persistent task's outcome arrives at READY; the child
           // keeps running until the orchestrator SIGTERMs it at run
           // end — pin it so its liveness stays visible.
           pinnedPersistent.push(node.id)
+          // …and capture what it writes from here on. A live-streaming
+          // node already owns the terminal, so buffering it would emit
+          // its output twice.
+          if (!streamsLive(node)) {
+            persistentTails.set(node.id, { node, outcome, out: createTail(), err: createTail() })
+          }
         }
         // Free the task's slot; the longest-waiting queued task
         // (if any) takes it over, keeping lowest-index-first reuse.
@@ -400,6 +547,7 @@ export function defaultLogger(
         switch (outcome.status) {
           case 'success':
             succeeded++
+            if (node.config.cache === undefined) noCache++
             break
           case 'cache-hit':
             if (outcome.restored === false) upToDate++
@@ -422,14 +570,24 @@ export function defaultLogger(
         refresh(true)
       }
       if (isGroupTask(node)) return
-      const isHit = outcome.status === 'cache-hit' || outcome.status === 'cache-hit-remote'
+      const isHit = isCacheHit(outcome.status)
       switch (view.mode) {
         case 'none':
           return
+        case 'hash-only': {
+          // The word carries the outcome (skips/failures included); the
+          // key is what this mode exists to show — absent for a task
+          // that never computed one (skipped, uncacheable).
+          const key = outcome.hash === undefined ? '' : ` ${outcome.hash}`
+          emitLine(`${outcomeWord(outcome)} ${node.id}${key}`)
+          return
+        }
         case 'errors-only':
           if (outcome.status !== 'failed') return
-          emitLine(formatFailureLine(node.id, outcome.durationMs, colors))
-          deferredFailures.push(formatTaskBlock(node, outcome, { stdout, stderr }, colors))
+          emitLine(formatFailureLine(node.id, outcome.durationMs, colors, cacheWordOf(node)))
+          deferredFailures.push(
+            formatTaskBlock(node, outcome, { stdout, stderr, ...dropped }, colors),
+          )
           return
         case 'broad':
           // News only: executed work gets a one-liner, failures get
@@ -438,8 +596,10 @@ export function defaultLogger(
           // surface in the end-of-run summary.
           if (outcome.status === 'failed') {
             // ✗ marker now; the full frame replays at runEnd.
-            emitLine(formatFailureLine(node.id, outcome.durationMs, colors))
-            deferredFailures.push(formatTaskBlock(node, outcome, { stdout, stderr }, colors))
+            emitLine(formatFailureLine(node.id, outcome.durationMs, colors, cacheWordOf(node)))
+            deferredFailures.push(
+              formatTaskBlock(node, outcome, { stdout, stderr, ...dropped }, colors),
+            )
           } else if (outcome.status === 'success') {
             emitLine(formatTaskExecutedLine(node, outcome, colors))
           }
@@ -471,20 +631,24 @@ export function defaultLogger(
             // to runEnd like everywhere else; everything else emits
             // ONE atomic block from the buffered output.
             if (outcome.status === 'failed') {
-              emitLine(formatFailureLine(node.id, outcome.durationMs, colors))
-              deferredFailures.push(formatTaskBlock(node, outcome, { stdout, stderr }, colors))
+              emitLine(formatFailureLine(node.id, outcome.durationMs, colors, cacheWordOf(node)))
+              deferredFailures.push(
+                formatTaskBlock(node, outcome, { stdout, stderr, ...dropped }, colors),
+              )
               return
             }
             // forceCommand: a requested task's frame shows `$ cmd`
             // whether it ran or was cached — same frame every run.
-            emitBlock(formatTaskBlock(node, outcome, { stdout, stderr }, colors, true))
+            emitBlock(formatTaskBlock(node, outcome, { stdout, stderr, ...dropped }, colors, true))
             return
           }
           // Dependency-pulled nodes: silent on success; failures get
           // the ✗ marker now and their frame replayed at runEnd.
           if (outcome.status === 'failed') {
-            emitLine(formatFailureLine(node.id, outcome.durationMs, colors))
-            deferredFailures.push(formatTaskBlock(node, outcome, { stdout, stderr }, colors))
+            emitLine(formatFailureLine(node.id, outcome.durationMs, colors, cacheWordOf(node)))
+            deferredFailures.push(
+              formatTaskBlock(node, outcome, { stdout, stderr, ...dropped }, colors),
+            )
           }
           return
         case 'full': {
@@ -502,17 +666,26 @@ export function defaultLogger(
             emitLine(formatTaskSkippedLine(node, colors))
             return
           }
-          const block = formatTaskBlock(node, outcome, { stdout, stderr }, colors)
+          const block = formatTaskBlock(node, outcome, { stdout, stderr, ...dropped }, colors)
           if (block.length === 0) return
           if (view.gha) {
+            // The block is the task's own output — fenced, so a task that
+            // prints `::endgroup::` can't close vx's group early and an
+            // `::error` line in its output can't become a real annotation.
+            const body = ghaFence(block, ghaToken)
             // Failed tasks stay pre-expanded in the Actions viewer:
             // an ::error annotation instead of a collapsed group.
             if (outcome.status === 'failed') {
-              emitBlock(`::error title=${node.id}::failed (exit ${outcome.exitCode})\n${block}`)
+              // The message is ours (a literal + an integer); only the title
+              // carries user input.
+              emitBlock(
+                `::error title=${ghaProperty(node.id)}::failed (exit ${outcome.exitCode})\n${body}`,
+              )
             } else {
               emitBlock(
-                `::group::${node.id} (${outcomeWord(outcome)} ${formatDuration(outcome.durationMs)})\n` +
-                  `${block}::endgroup::\n`,
+                `::group::${ghaData(
+                  `${node.id} (${outcomeWord(outcome)} ${formatDuration(outcome.durationMs)})`,
+                )}\n${body}::endgroup::\n`,
               )
             }
             return