@vzn/vx 0.0.591 → 0.0.595

package/src/cli/watch-fs.ts

@@ -77,10 +77,10 @@ export function pollWatcher(
    */
   skipDir: (rel: string) => boolean = (rel) => POLL_SKIP.has(path.basename(rel)),
 ): WatchHandle {
-  let previous = new Map<string, number>()
+  let previous = new Map<string, string>()
   let first = true
   const scan = (): void => {
-    const current = new Map<string, number>()
+    const current = new Map<string, string>()
     const walk = (abs: string, rel: string): void => {
       let entries: fs.Dirent[]
       try {
@@ -95,15 +95,23 @@ export function pollWatcher(
           if (recursive && !skipDir(childRel)) walk(path.join(abs, e.name), childRel)
           continue
         }
-        if (!e.isFile()) continue
+        // A link is an input as its target string (watch-judge.ts), so that
+        // string is sampled, never the target's times: a retarget inside
+        // one clock tick carries the same times.
+        const link = e.isSymbolicLink()
+        if (!e.isFile() && !link) continue
         try {
           // The later of the two clocks, as `modifiedBefore` reads them: a
           // replacement that carries the old file's mtime (`cp -p`, `rsync
           // -a`, `mv` of a file stamped the same) moved nothing under mtime
           // alone, and the poller never ran it where the native watcher did.
           // A rename or a write moves ctime, and no process can set it.
-          const st = fs.statSync(path.join(abs, e.name))
-          current.set(childRel, Math.max(st.mtimeMs, st.ctimeMs))
+          const p = path.join(abs, e.name)
+          if (link) current.set(childRel, `link:${fs.readlinkSync(p)}`)
+          else {
+            const st = fs.statSync(p)
+            current.set(childRel, String(Math.max(st.mtimeMs, st.ctimeMs)))
+          }
         } catch {
           // raced with a delete; the next scan settles it
         }
@@ -111,8 +119,8 @@ export function pollWatcher(
     }
     walk(dir, '')
     if (!first) {
-      for (const [rel, mtime] of current) {
-        if (previous.get(rel) !== mtime) onEvent(rel)
+      for (const [rel, stamp] of current) {
+        if (previous.get(rel) !== stamp) onEvent(rel)
       }
       for (const rel of previous.keys()) {
         if (!current.has(rel)) onEvent(rel)
@@ -237,6 +245,12 @@ export function armWatcher(
  */
 function treeWatcher(root: string, listener: (filename: string) => void): WatchHandle {
   const watchers = new Map<string, fs.FSWatcher>()
+  // Which directory each watch holds: inotify follows the inode, so a name
+  // removed and made again before its event is handled stats as a
+  // directory still, and the watch on the deleted one heard nothing more.
+  // The birth time too: a freed inode number goes to the next directory.
+  const held = new Map<string, string>()
+  const idOf = (st: fs.Stats): string => `${st.dev}:${st.ino}:${st.birthtimeMs}`
   let closed = false
   let armed = false
   let warned = false
@@ -249,6 +263,7 @@ function treeWatcher(root: string, listener: (filename: string) => void): WatchH
       if (key !== rel && !key.startsWith(rel + '/')) continue
       w.close()
       watchers.delete(key)
+      held.delete(key)
     }
   }
   const watchDir = (rel: string, report: boolean): void => {
@@ -269,7 +284,10 @@ function treeWatcher(root: string, listener: (filename: string) => void): WatchH
           return
         }
         if (!st.isDirectory()) return
-        if (watchers.has(child)) return
+        if (watchers.has(child)) {
+          if (held.get(child) === idOf(st)) return
+          drop(child)
+        }
         watchDir(child, true)
       })
     } catch (err) {
@@ -289,6 +307,11 @@ function treeWatcher(root: string, listener: (filename: string) => void): WatchH
     }
     w.on('error', () => drop(rel))
     watchers.set(rel, w)
+    try {
+      held.set(rel, idOf(fs.statSync(abs)))
+    } catch {
+      held.set(rel, '')
+    }
     let entries: fs.Dirent[]
     try {
       entries = fs.readdirSync(abs, { withFileTypes: true })
@@ -314,6 +337,7 @@ function treeWatcher(root: string, listener: (filename: string) => void): WatchH
       closed = true
       for (const w of watchers.values()) w.close()
       watchers.clear()
+      held.clear()
     },
   }
 }

package/src/cli/watch-judge.ts

@@ -77,7 +77,7 @@ export class ChangeJudge {
   // are judged one window after the run ends, all together — an edit made
   // meanwhile still differs from what the loop last saw and re-runs.
   readonly pending = new Map<string, string>()
-  /** The last cycle's wall window; a write inside it is the run's own. */
+  /** The last cycle's window, its start on the mtime clock (`fsClockNow`); a write inside it is the run's own. */
   lastCycle: { start: number; end: number } | undefined
   // Declared outputs are ignored by PATH above. A task with no `cache`
   // block declares none and still writes into its project, and the

package/src/cli/watch.ts

@@ -55,6 +55,12 @@ function sayCannot(what: string, err: unknown): void {
 
 /** Wait this long after the last filesystem event before re-running. */
 const DEBOUNCE_MS = 150
+/**
+ * ...but no longer than this after the first: a writer that never pauses
+ * for a window (a dev server logging into its project every 50 ms) reset
+ * the timer forever, and an edit made meanwhile never ran.
+ */
+const DEBOUNCE_MAX_MS = 1_000
 
 /**
  * The run flags a watch loop cannot honour, as the refusal line it prints; null
@@ -80,7 +86,7 @@ export function watchRefusal(parsed: RunArgs): string | null {
 export async function watchCmd(args: readonly string[]): Promise<number> {
   const parsed = parseRunArgs(args, 'watch')
   if (parsed.error) {
-    process.stderr.write(`vx watch: ${parsed.error}\n`)
+    process.stderr.write(`vx watch: ${parsed.error}${seeHelp('watch')}\n`)
     return 1
   }
 
@@ -131,10 +137,13 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   // worth; every cycle after an edit must load and list live.
   delete opts.staged
   delete opts.discovered
-  process.once('SIGINT', () => {
-    process.stdout.write('\nvx watch: stopped\n')
-    stop.abort('SIGINT')
-  })
+  process.once('SIGINT', () => stop.abort('SIGINT'))
+  // Said once the loop is down, the last line: written as the signal
+  // landed, the aborted cycle's summary printed below it.
+  const stopped = (): number => {
+    if (stop.signal.reason === 'SIGINT') process.stdout.write('\nvx watch: stopped\n')
+    return 0
+  }
   process.once('SIGTERM', () => stop.abort('SIGTERM'))
   // A task runs in its own session (exec/kill-tree.ts): the terminal
   // closing reaches the loop alone, and the loop passes it on.
@@ -200,7 +209,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   }
   if (stop.signal.aborted) {
     await held?.stop(forwardedSignal(stop.signal.reason))
-    return 0
+    return stopped()
   }
   if (refusedToStart) return 1
   // After the initial run, so a `pkg#task` naming no project gets the
@@ -228,7 +237,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
       ...fingerprintClaims(plugins).keys(),
       ...(opts.frozen === true ? [LOCKFILE_NAME] : []),
     ])
-  return await runWatchLoop({
+  await runWatchLoop({
     opts,
     held,
     stop: stop.signal,
@@ -279,6 +288,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
     // The RESOLVED cache dir, not the `.vx` literal — see `makeWatchIgnore`.
     cacheDir: opts.cacheDir ?? ws.cacheDir,
   })
+  return stopped()
 }
 
 interface WatchLoopArgs {
@@ -339,7 +349,7 @@ interface Rediscovered {
   fenceDirs: readonly string[]
 }
 
-async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
+async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   const { opts, stop, workspaceRoot, projects, cacheDir } = args
   // The watched set as of the last cycle: `rearm` replaces these after an
   // event that can change it, and every filter below reads the current one.
@@ -365,11 +375,15 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
   /** The cycle in flight, so the stop path can wait for its teardown before resolving. */
   let inFlight: Promise<void> = Promise.resolve()
   let debounceTimer: ReturnType<typeof setTimeout> | null = null
+  let windowOpened = 0
 
   const trigger = (label: string, abs: string): void => {
     if (!changes.pending.has(abs)) changes.pending.set(abs, label)
     if (running) return
-    if (debounceTimer) clearTimeout(debounceTimer)
+    if (debounceTimer) {
+      if (Date.now() - windowOpened >= DEBOUNCE_MAX_MS) return
+      clearTimeout(debounceTimer)
+    } else windowOpened = Date.now()
     debounceTimer = setTimeout(() => {
       debounceTimer = null
       if (running) return
@@ -393,7 +407,10 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
           await held?.stop()
           held = undefined
           restartTimings()
-          const start = Date.now()
+          // On the mtime clock, as the arm is: from `Date.now()` a write the
+          // run made within a tick of it carried an earlier mtime and read as
+          // an edit (WD-20). The end needs no stamp: an mtime never leads it.
+          const start = fsClockNow(cacheDir)
           const cycle = await runOrchestrator(opts)
           held = cycle.persistent
           if (cycle.refused !== undefined) process.stderr.write(`vx watch: ${cycle.refused}\n`)
@@ -491,7 +508,9 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
       const handle = arm(proj.dir, true, (filename) => {
         const abs = path.join(proj.dir, filename)
         if (isIgnoredPath(proj.dir, filename) || fenced(proj.dir, abs)) return
-        if (shapesWatchedSet(filename)) reread = true
+        // A module the config imports from inside the project is the config
+        // too: its edit can add an output or a `workspaceFiles` input.
+        if (shapesWatchedSet(filename) || configImportFiles.includes(abs)) reread = true
         trigger(`${proj.name} ${filename}`, abs)
       })
       perProject.set(proj.dir, handle)
@@ -512,8 +531,14 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
           // / .git / .vx and declared outputs out of what remains.
           arm(workspaceRoot, true, (filename) => {
             if (!matters(filename) || isIgnoredPath(workspaceRoot, filename)) return
-            if (shapesWatchedSet(filename) || filename === LOCKFILE_NAME) reread = true
-            trigger(`root ${filename}`, path.join(workspaceRoot, filename))
+            const abs = path.join(workspaceRoot, filename)
+            if (
+              shapesWatchedSet(filename) ||
+              filename === LOCKFILE_NAME ||
+              configImportFiles.includes(abs)
+            )
+              reread = true
+            trigger(`root ${filename}`, abs)
           })
         : // The root itself, non-recursive, beside the per-project arms, so
           // lockfile + pnpm-workspace.yaml edits trigger re-runs even when
@@ -820,7 +845,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
 
   process.stdout.write(`\n${watchingLine(projects.length)}; press Ctrl+C to stop\n`)
 
-  return await new Promise<number>((resolve) => {
+  return await new Promise<void>((resolve) => {
     const cleanup = async (): Promise<void> => {
       pool.closeAll()
       if (debounceTimer) clearTimeout(debounceTimer)
@@ -828,7 +853,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
       // it has returned, so the process never exits over a live child.
       await inFlight
       await held?.stop(forwardedSignal(stop.reason))
-      resolve(0)
+      resolve()
     }
     if (stop.aborted) {
       void cleanup()

package/src/cli/why.ts

@@ -7,7 +7,7 @@
 
 import path from 'node:path'
 import { Cache } from '../cache/index.js'
-import { flagHint, seeHelp } from './help.js'
+import { flagHint, formatValue, seeHelp } from './help.js'
 import { splitTaskId } from '../graph/index.js'
 import {
   cacheKeyDiff,
@@ -70,17 +70,8 @@ export function parseWhyArgs(args: readonly string[]): WhyArgs {
       continue
     }
     if (a === '--format' || a.startsWith('--format=')) {
-      const fv = a === '--format' ? args[++i] : a.slice(9)
-      if (fv !== 'pretty' && fv !== 'json') {
-        // An omitted value reads as empty, not as the literal word "undefined".
-        return {
-          ...out,
-          error:
-            fv === undefined || fv === ''
-              ? '--format requires a value (pretty | json)'
-              : `invalid --format: ${fv} (expected pretty | json)`,
-        }
-      }
+      const fv = formatValue(a === '--format' ? args[++i] : a.slice(9), 'why')
+      if (typeof fv === 'object') return { ...out, ...fv }
       out.format = fv
       continue
     }
@@ -235,7 +226,7 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
     const why = whyDidThisRerun(db, runId, taskId)
     if (!why.found) {
       throw new UserError(
-        `vx why: run ${runId} has no row for ${taskId}; \`vx last --list\` shows the recorded runs, \`vx last <runId>\` what one ran`,
+        `vx why: run ${runId} has no row for ${taskId}; \`vx last --list\` shows the recorded runs, \`vx last RUNID\` what one ran`,
       )
     }
     const diff = cacheKeyDiff(db, runId, taskId)

package/src/cli/workspace-config.ts

@@ -23,7 +23,7 @@ import {
   resolveStoreRoot,
 } from '../workspace/index.js'
 
-export interface CliWorkspace {
+interface CliWorkspace {
   workspaceConfig: WorkspaceConfig | null
   plugins: readonly VxPlugin[]
   cacheDir: string

package/src/config.ts

@@ -510,9 +510,9 @@ export interface CacheInputs {
    * project files" (gitignore-aware), or narrow as needed. An empty
    * array means no file inputs at all.
    *
-   * Declared outputs and any nested-project files are excluded
-   * automatically — a task cannot invalidate itself, and cannot read
-   * across project boundaries.
+   * Declared outputs (both `outputs` fields) and any nested-project
+   * files are excluded automatically — a task cannot invalidate itself,
+   * and cannot read across project boundaries.
    */
   files: string[]
   /**
@@ -525,8 +525,8 @@ export interface CacheInputs {
    * NO project-boundary rule applies: these globs may match files
    * inside other projects' directories. Deliberate escape hatch —
    * prefer project-relative `files` declarations where possible.
-   * Declared `outputs.workspaceFiles` are excluded automatically (a
-   * task cannot invalidate itself).
+   * Declared outputs (both `outputs` fields) are excluded
+   * automatically (a task cannot invalidate itself).
    */
   workspaceFiles?: string[]
   /**

package/src/exec/env.ts

@@ -33,6 +33,11 @@ export const ESSENTIAL_ENV: readonly string[] = [
   'NO_COLOR',
   'CI',
   'NODE_OPTIONS',
+  // Where corepack and pnpm keep their own binaries, as HOME is: a machine
+  // path, never task output. Without them a corepack shim re-downloads its
+  // manager (offline or sandboxed: fails) and pnpm loses its global dir.
+  'COREPACK_HOME',
+  'PNPM_HOME',
 ]
 
 /**
@@ -125,11 +130,9 @@ export function packageManagerPath(root: string): string | null {
   if (known !== undefined) return known
   let name: string | undefined
   try {
-    const field = (
-      JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8')) as {
-        packageManager?: unknown
-      }
-    ).packageManager
+    // A byte-order mark is stripped, as npm and discovery strip it.
+    const manifest = readFileSync(path.join(root, 'package.json'), 'utf8').replace(/^\uFEFF/, '')
+    const field = (JSON.parse(manifest) as { packageManager?: unknown }).packageManager
     if (typeof field === 'string') name = MANAGERS.find((m) => field.startsWith(`${m}@`))
   } catch {}
   name ??= LOCKFILES.find(([f]) => existsSync(path.join(root, f)))?.[1]

package/src/exec/index.ts

@@ -18,6 +18,7 @@ export {
   exitSignal,
   type CaptureConfig,
   execWord,
+  maskCaptured,
 } from './runner.js'
 export {
   initSandbox,

package/src/exec/proc-sample.ts

@@ -134,12 +134,16 @@ async function psTable(): Promise<Map<number, Proc> | undefined> {
   return table
 }
 
-/** `ps`'s `time`: `[[dd-]hh:]mm:ss[.cc]`, macOS printing hundredths. */
+/**
+ * `ps`'s `time`: `[[dd-]hh:]mm:ss[.cc]`, macOS printing hundredths after
+ * the locale's decimal point — `0:01,50` under a German or French locale.
+ */
 export function psTimeMs(s: string): number | undefined {
   const dash = s.indexOf('-')
   const days = dash === -1 ? 0 : Number(s.slice(0, dash))
   const parts = s
     .slice(dash + 1)
+    .replace(',', '.')
     .split(':')
     .map(Number)
   if (parts.length < 2 || parts.some((n) => !Number.isFinite(n)) || !Number.isFinite(days)) {