@vzn/vx 0.0.641 → 0.0.643

package/src/report/status-line.ts

@@ -56,6 +56,11 @@ export interface OutputWriter {
   settle(): void
   /** Permanently remove the status display; later set* is a no-op. */
   clearStatus(): void
+  /**
+   * Erase the status display and draw none until the returned release:
+   * a prompt on the terminal (a secret's) waits for its answer there.
+   */
+  hold(): () => void
 }
 
 export interface OutputWriterOptions {
@@ -108,6 +113,7 @@ export function createOutputWriter(
   // `regionRows`.
   let shownRows = 0
   let dead = false
+  let holds = 0
   let lastDraw = -Infinity
   // Trailing draw scheduled when a forced set lands inside the floor.
   let trailing: ReturnType<typeof setTimeout> | null = null
@@ -196,7 +202,7 @@ export function createOutputWriter(
   const set = (lines: readonly string[], o: { force?: boolean }): void => {
     if (!enabled || dead) return
     current = lines
-    if (!atLineStart) return
+    if (!atLineStart || holds > 0) return
     const since = now() - lastDraw
     if (o.force) {
       if (since >= forceFloorMs) {
@@ -209,7 +215,7 @@ export function createOutputWriter(
       if (trailing === null) {
         trailing = setTimeout(() => {
           trailing = null
-          if (dead || current === null || !atLineStart) return
+          if (dead || current === null || !atLineStart || holds > 0) return
           draw()
         }, forceFloorMs - since)
         trailing.unref?.()
@@ -241,7 +247,7 @@ export function createOutputWriter(
       }
       stream.write(chunk)
       if (chunk.length > 0) atLineStart = chunk.endsWith('\n')
-      if (!dead && current !== null && atLineStart) draw()
+      if (!dead && current !== null && atLineStart && holds === 0) draw()
     },
     writeTo(target, chunk) {
       if (target === stream) return this.write(chunk)
@@ -257,7 +263,7 @@ export function createOutputWriter(
         shownRows = 0
       }
       target.write(chunk)
-      if (!dead && current !== null && atLineStart) draw()
+      if (!dead && current !== null && atLineStart && holds === 0) draw()
     },
     setStatus(line, o = {}) {
       set([line], o)
@@ -280,6 +286,23 @@ export function createOutputWriter(
         shownRows = 0
       }
     },
+    hold() {
+      if (!enabled || dead) return () => undefined
+      holds++
+      cancelTrailing()
+      if (shown) {
+        stream.write(eraseSeq())
+        shown = false
+        shownRows = 0
+      }
+      let released = false
+      return () => {
+        if (released) return
+        released = true
+        holds--
+        if (holds === 0 && !dead && current !== null && atLineStart) draw()
+      }
+    },
   }
 }
 
@@ -310,6 +333,8 @@ export interface StatusRegionState {
   blocked?: readonly (BlockedTask | null)[]
   /** Running tasks beyond the displayed slots. */
   overflow: number
+  /** The run was stopped: running rows say `aborting`, idle rows leave. */
+  stopping?: boolean
   /**
    * vx's own steps still running, shown below the worker rows: no worker
    * slot or `--concurrency` bounds them (M, 2026-10-15).
@@ -428,6 +453,7 @@ export function formatStatusRegion(
   // One task running has no path to compare against.
   const busy = s.slots.filter((x) => x !== null).length
   for (const [row, slot] of s.slots.entries()) {
+    if (slot === null && s.stopping === true) continue
     if (slot === null) {
       const w = s.blocked?.[row]
       lines.push(
@@ -440,6 +466,21 @@ export function formatStatusRegion(
     }
     // What waits on it, after the id: the row to watch is the one the
     // longest chain waits on, and the one the most tasks wait on.
+    if (s.stopping === true) {
+      lines.push(
+        formatTaskRow(
+          ' ',
+          Math.max(0, s.nowMs - slot.startedMs),
+          'aborting',
+          WARN,
+          '',
+          '',
+          paintPinnedId(slot.id, colors),
+          colors,
+        ),
+      )
+      continue
+    }
     const waiting = s.blocks?.get(slot.id) ?? 0
     const notes: string[] = []
     if (s.critical === slot.id && busy > 1) notes.push(paint(WARN, 'critical path', colors))

package/src/report/summary.ts

@@ -81,9 +81,9 @@ export interface SummaryStats {
   /** Ended OK — executed successes AND cache hits. */
   successful: number
   skipped: number
-  /** Killed by a shutdown signal (final summary only). Not in `total`. */
+  /** Killed by a shutdown signal, shown as `aborted`. Not in `total`. */
   aborted?: number
-  /** Reached by the stop before they ran (final summary only). Not in `total`. */
+  /** Reached by the stop before they ran. Not in `total`. */
   notRun?: number
   total: number
   upToDate: number
@@ -183,9 +183,13 @@ export interface RunContext {
   version: string
   /** Projects with a real task in the graph — the "affected" half of the bar. */
   packageCount: number
+  /** The run's whole id, as `vx last` takes it; shown on the `info` row. */
+  runId?: string | undefined
   /** Worker-pool size for this run; shown on the `info` row. */
   concurrency?: number
   remoteCacheEnabled: boolean
+  /** The run's cache scope, named after the cache mode: `scope vznjs/vx:feat-x`. */
+  cacheScope?: string | undefined
   /**
    * The cache layers the run used, so the legend reads `local 1= 2↓ 4↑ ·
    * remote 3↓ 4↑`. Absent: the plain `N miss` legend.
@@ -405,6 +409,7 @@ export function formatSummarySection(
     if (context.concurrency !== undefined)
       info.push(`${context.concurrency} worker${context.concurrency === 1 ? '' : 's'}`)
     info.push(context.remoteCacheEnabled ? 'local + remote cache' : 'local cache')
+    if (context.cacheScope !== undefined) info.push(`scope ${context.cacheScope}`)
     // The plugin's hand on the run: a task a policy held with a worker
     // free would otherwise have started; without the line nothing says
     // the policy acted. The duration is the waits summed, task-seconds
@@ -415,6 +420,7 @@ export function formatSummarySection(
         `admit held ${stats.held.count} task${stats.held.count === 1 ? '' : 's'}, ${formatElapsed(stats.held.sumMs)} in all`,
       )
     }
+    if (context.runId !== undefined) info.push(`run ${context.runId}`)
     lines.push('', row('info', join(info)), timeRow)
   } else {
     lines.push('', timeRow)

package/src/settings.ts

@@ -43,6 +43,12 @@ export interface Setting {
 const SCHEDULES = ['most-work', 'critical-path', 'direct-dependents', 'ready-order'] as const
 
 export const SETTINGS: readonly Setting[] = [
+  {
+    path: 'baseBranch',
+    kind: { type: 'string' },
+    default: "origin/HEAD's branch, then main, then master",
+    doc: 'The default branch: a run on it has no cache scope and a bare `--affected` no base; elsewhere both use the merge base with `origin/<baseBranch>`.',
+  },
   {
     path: 'run.concurrency',
     kind: { type: 'concurrency' },
@@ -57,12 +63,6 @@ export const SETTINGS: readonly Setting[] = [
     doc: 'Which ready task starts first when there are more than workers.',
     flag: { verb: 'run', name: '--schedule' },
   },
-  {
-    path: 'run.affectedBase',
-    kind: { type: 'string' },
-    default: 'origin/HEAD, then the trunk, else HEAD~1',
-    doc: 'The git ref a bare `--affected` compares with.',
-  },
   {
     path: 'run.branch',
     kind: { type: 'string' },
@@ -137,9 +137,9 @@ export const SETTINGS: readonly Setting[] = [
   {
     path: 'cache.scope',
     kind: { type: 'string' },
-    default: 'none (the default keys)',
-    doc: "Where cache writes land (`'pr-123'`): reads try the default key, then the scope's.",
-    flag: { verb: 'run', name: '--cache-scope' },
+    default: "the branch's, `<owner>/<repo>:<branch>`, with a remote cache off `baseBranch`",
+    doc: "A branch's remote entries (`'vznjs/vx:feat-x'`): tasks the branch changed read the scope's key, the rest the default key; the local cache never uses it. Empty: no scope.",
+    config: false,
   },
   {
     path: 'cache.download',
@@ -220,7 +220,7 @@ export const SETTINGS: readonly Setting[] = [
   },
 ]
 
-/** The `.vx/workspace` groups that hold settings; `plugins` is the other key. */
+/** The `.vx/workspace` groups that hold settings; `baseBranch` and `plugins` are the other keys. */
 export const SETTING_GROUPS = ['run', 'cache', 'lock', 'watch'] as const
 
 const BY_PATH = new Map(SETTINGS.map((s) => [s.path, s]))
@@ -229,7 +229,7 @@ export function setting(path: string): Setting {
   return BY_PATH.get(path)!
 }
 
-/** `run.affectedBase` → `VX_RUN_AFFECTED_BASE`. */
+/** `run.branch` → `VX_RUN_BRANCH`. */
 export function envName(path: string): string {
   return `VX_${path
     .replace(/([a-z0-9])([A-Z])/g, '$1_$2')

package/src/util/errors.ts

@@ -97,7 +97,7 @@ export function wantsJson(argv: readonly string[]): boolean {
 /**
  * The JSON a verb that answers JSON prints for a refusal: one line. A
  * core code (`VX_E_…`) links its section of cli.md, which says the fix;
- * `vx docs <code>` prints the same section offline. A plugin's code has none.
+ * `vx docs <code>` prints the same section. A plugin's code has none.
  */
 export function errorDocument(code: string, message: string): string {
   const docs = code.startsWith('VX_E_')

package/src/util/hidden-prompt.ts

@@ -0,0 +1,74 @@
+// A secret asked for on the terminal: hidden, one line, only where someone can answer.
+
+/** Where a missing secret is asked for. */
+export interface SecretTerminal {
+  /** stdin and stderr are both terminals: someone can answer. */
+  interactive(): boolean
+  /** Ask `question` on stderr with the answer hidden; resolves the line typed. */
+  ask(question: string): Promise<string>
+}
+
+interface HiddenInput {
+  isRaw?: boolean
+  setRawMode(mode: boolean): unknown
+  on(event: 'data', fn: (chunk: Buffer | string) => void): unknown
+  off(event: 'data', fn: (chunk: Buffer | string) => void): unknown
+  resume(): unknown
+  pause(): unknown
+}
+
+/**
+ * Read one line from a raw-mode terminal, echoing nothing; backspace edits.
+ * Ctrl-D answers nothing. Raw mode delivers no SIGINT, so Ctrl-C answers
+ * nothing and raises it: the run stops as it would at any other moment.
+ */
+function askHidden(
+  question: string,
+  input: HiddenInput,
+  output: { write(s: string): unknown },
+  interrupt: () => void,
+): Promise<string> {
+  output.write(question)
+  const wasRaw = input.isRaw === true
+  input.setRawMode(true)
+  input.resume()
+  return new Promise((resolve) => {
+    let line = ''
+    const done = () => {
+      input.off('data', onData)
+      input.setRawMode(wasRaw)
+      input.pause()
+      output.write('\n')
+    }
+    const onData = (chunk: Buffer | string) => {
+      for (const ch of String(chunk)) {
+        if (ch === '\r' || ch === '\n') {
+          done()
+          resolve(line)
+          return
+        }
+        if (ch === '\u0003' || ch === '\u0004') {
+          done()
+          resolve('')
+          if (ch === '\u0003') interrupt()
+          return
+        }
+        if (ch === '\u007f' || ch === '\b') line = line.replace(/.$/u, '')
+        else if (ch >= ' ') line += ch
+      }
+    }
+    input.on('data', onData)
+  })
+}
+
+/** A process's terminal: asked only when its stdin and stderr are both TTYs. */
+export function terminalOf(
+  stdin: HiddenInput & { isTTY?: boolean },
+  stderr: { isTTY?: boolean; write(s: string): unknown },
+  interrupt: () => void = () => process.kill(process.pid, 'SIGINT'),
+): SecretTerminal {
+  return {
+    interactive: () => stdin.isTTY === true && stderr.isTTY === true,
+    ask: (question) => askHidden(question, stdin, stderr, interrupt),
+  }
+}

package/src/util/index.ts

@@ -58,9 +58,8 @@ export {
   GLOB_WILDCARDS,
   normalizeBunGlob,
   normalizeGlob,
-  namesNodeModules,
-  OUTPUT_NEVER,
   outputMatcher,
+  outputNever,
   restorableOutput,
   printable,
   relPosix,
@@ -74,6 +73,7 @@ export {
   taskGlob,
   wholeSubtreePrefixes,
   slashBraceExpansions,
+  braceAlternatives,
 } from './paths.js'
 export {
   claimExitForSignal,
@@ -119,3 +119,13 @@ export {
   secretNamed,
   type SecretMask,
 } from './secret-mask.js'
+export {
+  isSecretUnavailable,
+  SecretBroker,
+  type PluginSecrets,
+  type SecretRequest,
+  type SecretStore,
+  type SecretUnavailable,
+  type SecretUnavailableReason,
+} from './secrets.js'
+export { terminalOf, type SecretTerminal } from './hidden-prompt.js'

package/src/util/paths.ts

@@ -387,18 +387,36 @@ export function outputMatcher(globs: readonly string[]): (rel: string) => boolea
 }
 
 /**
- * What no output glob reaches. An output is otherwise taken as written —
- * `node_modules/**` IS an install task's output — but no task produces
- * these, and a root project declaring `**` would otherwise wipe its
- * repository and the cache it is restoring from (2026-09-16). `.vx` whole
- * and each `vx.lock.json` are vx's own: as outputs, the clean deleted an
- * uncommitted workspace config and a hit restored a lock or ignore file the
- * key does not see over the current one.
+ * What no output glob reaches, relative to the project: its root's `.git`
+ * and `.vx`, and the `vx.lock.json` beside its config. An output is
+ * otherwise taken as written — `node_modules/**` IS an install task's
+ * output — but a root project declaring `**` would otherwise wipe its
+ * repository and the cache it is restoring from (2026-09-16), the clean
+ * deleted an uncommitted workspace config, and a hit restored a lock or
+ * ignore file the key does not see over the current one. Only where vx
+ * writes them: reserved at any depth, a hit dropped a build's own
+ * `dist/.git/**` and `dist/sub/vx.lock.json` (2026-10-17).
  */
-export const OUTPUT_NEVER = ['**/.git/**', '**/.vx/**', '**/vx.lock.json']
+const OUTPUT_NEVER = ['.git/**', '.vx/**', 'vx.lock.json']
+
+/**
+ * `OUTPUT_NEVER` relative to the workspace root, for `outputs.workspaceFiles`:
+ * those globs cross into other projects, and every project's `vx.lock.json`
+ * is vx's.
+ */
+const WORKSPACE_OUTPUT_NEVER = [...OUTPUT_NEVER, '**/vx.lock.json']
+
+/**
+ * What `globs` may not reach in `scope`: its never-list, and every
+ * `node_modules` unless a glob names one.
+ */
+export function outputNever(globs: readonly string[], scope: 'project' | 'workspace'): string[] {
+  const never = scope === 'project' ? OUTPUT_NEVER : WORKSPACE_OUTPUT_NEVER
+  return namesNodeModules(globs) ? never : [...never, '**/node_modules/**']
+}
 
 /** Whether a positive glob in `globs` names a `node_modules` directory. */
-export function namesNodeModules(globs: readonly string[]): boolean {
+function namesNodeModules(globs: readonly string[]): boolean {
   return globs.some(
     (g) => !g.startsWith('!') && normalizeGlob(g).split('/').includes('node_modules'),
   )
@@ -411,11 +429,12 @@ export function namesNodeModules(globs: readonly string[]): boolean {
  * artifact naming anything else was not written by this task's save, and
  * none of it is restored (2026-10-16).
  */
-export function restorableOutput(globs: readonly string[]): (rel: string) => boolean {
+export function restorableOutput(
+  globs: readonly string[],
+  scope: 'project' | 'workspace' = 'project',
+): (rel: string) => boolean {
   const isOutput = outputMatcher(globs)
-  const never = anyTaskGlob(
-    namesNodeModules(globs) ? OUTPUT_NEVER : [...OUTPUT_NEVER, '**/node_modules/**'],
-  )
+  const never = anyTaskGlob(outputNever(globs, scope))
   return (rel) => isOutput(rel) && !never(rel)
 }
 
@@ -430,7 +449,7 @@ export function slashBraceExpansions(pattern: string): string[] {
 }
 
 /** `pattern` with every brace group of two or more alternatives expanded. */
-function braceAlternatives(pattern: string): string[] {
+export function braceAlternatives(pattern: string): string[] {
   return expandBraces(pattern, false)
 }
 

package/src/util/secrets.ts

@@ -0,0 +1,150 @@
+// A plugin's secrets, kept in the OS keychain (`Bun.secrets`) under the
+// plugin's own name, and asked for on the terminal when a plugin offers a
+// prompt and someone can answer (owner, 2026-10-17). Core reads no
+// environment here: a variable, an option or a config file is the
+// plugin's to check first, so the keychain is always the last source.
+
+import { type SecretTerminal, terminalOf } from './hidden-prompt.js'
+
+/** What `ctx.secret` is asked: the entry's name, and the question to ask on a terminal. */
+export interface SecretRequest {
+  /** The entry's name within the plugin's keychain service: one per remote, say. */
+  readonly key: string
+  /** Asked when the keychain lacks the entry. Omitted: never asked, a miss is `not-found`. */
+  readonly prompt?: string
+}
+
+/** A plugin's keychain, on the contexts of the hooks that run before the first task. */
+export interface PluginSecrets {
+  /**
+   * The entry, else the terminal's answer (then saved), else a rejection a
+   * `isSecretUnavailable` guard names. Once per run per key: concurrent asks
+   * share the answer.
+   */
+  secret(req: SecretRequest): Promise<string>
+  /** Delete the entry (a server refused it), so the next run asks again. Never throws. */
+  forgetSecret(req: { readonly key: string }): Promise<void>
+}
+
+/**
+ * Why `secret` had nothing: the keychain lacks it and no prompt was given
+ * (`not-found`), a prompt was given and nobody can answer — CI, no TTY, or
+ * the status line already up (`no-terminal`), the answer was empty
+ * (`declined`), or there is no keychain and no answer (`store-unavailable`).
+ */
+export type SecretUnavailableReason = 'not-found' | 'no-terminal' | 'declined' | 'store-unavailable'
+
+export interface SecretUnavailable extends Error {
+  readonly reason: SecretUnavailableReason
+}
+
+const NAME = 'SecretUnavailable'
+
+/** A `secret` rejection that is a missing secret, not a fault. By name: a plugin may load its own copy of core. */
+export function isSecretUnavailable(err: unknown): err is SecretUnavailable {
+  return err instanceof Error && err.name === NAME && 'reason' in err
+}
+
+function unavailable(key: string, reason: SecretUnavailableReason): SecretUnavailable {
+  return Object.assign(new Error(`secret '${key}' unavailable: ${reason}`), { name: NAME, reason })
+}
+
+/** The keychain as the broker reads and writes it: `Bun.secrets`, or a test's stand-in. */
+export interface SecretStore {
+  get(o: { service: string; name: string }): Promise<string | null>
+  set(o: { service: string; name: string; value: string }): Promise<void>
+  delete(o: { service: string; name: string }): Promise<boolean>
+}
+
+// Reached only when asked: touching `process.stdin` opens the stream.
+const processTerminal: SecretTerminal = {
+  interactive: () => terminalOf(process.stdin, process.stderr).interactive(),
+  ask: (question) => terminalOf(process.stdin, process.stderr).ask(question),
+}
+
+/**
+ * One run's secrets for every plugin. A prompt waits for the one before
+ * it, so two plugins never ask at once, and none is asked once
+ * `closePrompts` says the status line is up.
+ */
+export class SecretBroker {
+  private readonly memo = new Map<string, Promise<string>>()
+  private prompting: Promise<unknown> = Promise.resolve()
+  private closed = false
+
+  constructor(
+    private readonly ci: boolean,
+    private readonly warn: (message: string) => void,
+    private readonly store: SecretStore = Bun.secrets,
+    private readonly terminal: SecretTerminal = processTerminal,
+    /** Quiets the terminal's live region until the release it returns. */
+    private readonly quiet: () => () => void = () => () => undefined,
+  ) {}
+
+  /** `plugin`'s keychain: its entries live under its package name. */
+  for(plugin: string): PluginSecrets {
+    return {
+      secret: (req) => {
+        const memoKey = `${plugin}\0${req.key}`
+        let pending = this.memo.get(memoKey)
+        if (pending === undefined) {
+          pending = this.resolve(plugin, req)
+          this.memo.set(memoKey, pending)
+        }
+        return pending
+      },
+      forgetSecret: async ({ key }) => {
+        this.memo.delete(`${plugin}\0${key}`)
+        try {
+          await this.store.delete({ service: plugin, name: key })
+        } catch {
+          // no keychain to delete from
+        }
+      },
+    }
+  }
+
+  /** The status line is about to start: from here a prompt would be drawn over. */
+  closePrompts(): void {
+    this.closed = true
+  }
+
+  private async resolve(service: string, req: SecretRequest): Promise<string> {
+    const entry = { service, name: req.key }
+    let storeDown = false
+    try {
+      const stored = await this.store.get(entry)
+      if (stored) return stored
+    } catch {
+      // No keychain (headless Linux without libsecret).
+      storeDown = true
+    }
+    if (req.prompt === undefined)
+      throw unavailable(req.key, storeDown ? 'store-unavailable' : 'not-found')
+    const asked = this.prompting.then(() => this.ask(req.key, req.prompt!))
+    this.prompting = asked.catch(() => undefined)
+    const answer = await asked
+    try {
+      await this.store.set({ ...entry, value: answer })
+    } catch (err) {
+      this.warn(
+        `[vx] could not save '${req.key}' to the OS keychain (${err instanceof Error ? err.message : String(err)}); used for this run only`,
+      )
+    }
+    return answer
+  }
+
+  private async ask(key: string, prompt: string): Promise<string> {
+    if (this.ci || this.closed || !this.terminal.interactive())
+      throw unavailable(key, 'no-terminal')
+    const release = this.quiet()
+    let answer: string
+    try {
+      answer = (await this.terminal.ask(prompt)).trim()
+    } finally {
+      release()
+    }
+    if (answer === '') throw unavailable(key, 'declined')
+    return answer
+  }
+}