@vzn/vx 0.0.594 → 0.0.595

package/src/cache/inputs.ts

@@ -182,11 +182,14 @@ export type ProjectFilesCache = Map<
 >
 
 export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedInputs> {
+  const projectRel = path.relative(args.workspaceRoot, args.projectDir).split(path.sep).join('/')
   const { files: projectFiles, listing } = await resolveFiles({
     projectDir: args.projectDir,
     workspaceRoot: args.workspaceRoot,
     files: args.inputs?.files,
     ownOutputs: args.ownOutputs,
+    ownWorkspaceOutputs: args.ownWorkspaceOutputs ?? [],
+    projectRel,
     nestedProjectDirs: args.nestedProjectDirs,
     ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
     ...(args.projectFilesCache !== undefined ? { projectFilesCache: args.projectFilesCache } : {}),
@@ -199,6 +202,8 @@ export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedIn
       workspaceRoot: args.workspaceRoot,
       workspaceFiles: wsDecl,
       ownWorkspaceOutputs: args.ownWorkspaceOutputs ?? [],
+      ownOutputs: args.ownOutputs,
+      projectRel,
       ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
       ...(args.workspaceFilesCache !== undefined ? { memo: args.workspaceFilesCache } : {}),
     })
@@ -258,6 +263,9 @@ function resolveWorkspaceFiles(args: {
   workspaceRoot: string
   workspaceFiles: readonly string[]
   ownWorkspaceOutputs: readonly string[]
+  /** The task's project-relative `outputs.files`, and its project's root-relative directory. */
+  ownOutputs: readonly string[]
+  projectRel: string
   gitFilesCache?: GitFilesCache
   memo?: WorkspaceFilesCache
 }): { files: Promise<string[]>; listing: InputListing } | undefined {
@@ -274,6 +282,11 @@ function resolveWorkspaceFiles(args: {
   // A path the task's own outputs take back with `!` is no output, so it
   // stays an input (A-44).
   const ownOutput = outputMatcher(args.ownWorkspaceOutputs)
+  // Its project outputs too, which a root-anchored glob can reach as well:
+  // left in, the task's own build moved its key, and no run was ever saved.
+  let ownProjectOutput: ((rel: string) => boolean) | undefined
+  const ownProject = (rel: string): boolean =>
+    (ownProjectOutput ??= underProject(args.projectRel, outputMatcher(args.ownOutputs)))(rel)
   const positiveGlobs = asTrees(positive).map(globFor)
   // Workspace-wide partition, keyed by the workspace root. Populated
   // up-front by `populateGitFilesCache(..., workspaceWide: true)` when
@@ -293,9 +306,15 @@ function resolveWorkspaceFiles(args: {
   const memoKey =
     args.memo === undefined
       ? undefined
-      : JSON.stringify([positive, negative, args.ownWorkspaceOutputs])
+      : JSON.stringify([
+          positive,
+          negative,
+          args.ownWorkspaceOutputs,
+          args.ownOutputs,
+          args.projectRel,
+        ])
   let isPositive: ((rel: string) => boolean) | undefined
-  const excluded = (rel: string): boolean => isExcluded(rel) || ownOutput(rel)
+  const excluded = (rel: string): boolean => isExcluded(rel) || ownOutput(rel) || ownProject(rel)
   const listing: InputListing = {
     root: args.workspaceRoot,
     listed: gitFiles,
@@ -352,6 +371,24 @@ async function resolveWorkspaceFilesOver(
   return candidates.filter((abs) => oids?.has(abs) === true || isInputOnDisk(abs)).sort()
 }
 
+/** A project-relative matcher asked of root-relative paths: false outside the project. */
+function underProject(
+  projectRel: string,
+  matches: (rel: string) => boolean,
+): (rel: string) => boolean {
+  if (projectRel === '') return matches
+  const prefix = `${projectRel}/`
+  return (rel) => rel.startsWith(prefix) && matches(rel.slice(prefix.length))
+}
+
+/** A root-relative matcher asked of project-relative paths. */
+function inProject(
+  projectRel: string,
+  matches: (rel: string) => boolean,
+): (rel: string) => boolean {
+  return projectRel === '' ? matches : (rel) => matches(`${projectRel}/${rel}`)
+}
+
 /** Anything at the path — file, directory, symlink to anything or to nothing. */
 function existsOnDisk(abs: string): boolean {
   try {
@@ -712,25 +749,13 @@ export async function cleanOutputs(args: {
   projectDir: string
   outputs: string[]
   nestedProjectDirs: string[]
-  /**
-   * Before a miss: keep the directory each wildcard glob is rooted at
-   * (`dist` for `dist/**`). The task writes its matches under it, so a
-   * remove there bought only an rmdir and the task's mkdir: 0.4 ms of a
-   * 4.9 ms one-file miss (B-49). A restore prunes it, since the entry's
-   * shape decides there.
-   */
-  keepGlobRoots?: boolean
 }): Promise<string[]> {
   const files = await resolveOutputs(args)
   // `force: true` makes rm tolerate ENOENT (e.g. when two output
   // globs overlap and a sibling already deleted a path mid-iteration).
   // A symlink is unlinked, never followed.
   const removed = await removeAll(files, args.projectDir)
-  await pruneEmptiedDirs(
-    args.projectDir,
-    removed,
-    args.keepGlobRoots === true ? globRoots(args.projectDir, args.outputs) : undefined,
-  )
+  await pruneEmptiedDirs(args.projectDir, removed, pruneScope(args.projectDir, args.outputs))
   // Project-relative posix paths of what was removed — the caller
   // feeds these to GitFilesCache.markOutputsChanged after a restore.
   return files.map((f) => relPosix(args.projectDir, f))
@@ -740,15 +765,20 @@ export async function cleanOutputs(args: {
  * Remove exactly these project-relative paths — the recorded rows of an
  * ADDITIVE task's own artifact (item 588), never a glob: the glob would
  * take the upstream's files the task adds beside. Emptied directories are
- * pruned as `cleanOutputs` prunes them, and stop at one the upstream still
- * fills.
+ * pruned as `cleanOutputs` prunes them, only inside the declared `outputs`
+ * (`pruneScope`), and stop at one the upstream still fills.
  */
 export async function cleanOutputPaths(args: {
   projectDir: string
   rels: readonly string[]
+  outputs: readonly string[]
 }): Promise<void> {
   const files = args.rels.map((r) => path.resolve(args.projectDir, r))
-  await pruneEmptiedDirs(args.projectDir, await removeAll(files, args.projectDir))
+  await pruneEmptiedDirs(
+    args.projectDir,
+    await removeAll(files, args.projectDir),
+    pruneScope(args.projectDir, args.outputs),
+  )
 }
 
 /**
@@ -914,7 +944,10 @@ function notThroughLink(files: readonly string[], root: string): string[] {
       return null
     }
   }
-  const realRoot = real(root) ?? root
+  // Resolved only once a directory exists to compare: after a clean pruned
+  // the outputs (the common restore) nothing does, and the call was most
+  // of an empty clean.
+  let realRoot: string | undefined
   const own = new Map<string, boolean>()
   return files.filter((f) => {
     const dir = path.dirname(f)
@@ -923,7 +956,8 @@ function notThroughLink(files: readonly string[], root: string): string[] {
       // A directory already gone has nothing to delete through; its path
       // stays so the prune still reaches the parents it emptied.
       const r = real(dir)
-      ok = r === null || r === path.join(realRoot, path.relative(root, dir))
+      ok =
+        r === null || r === path.join((realRoot ??= real(root) ?? root), path.relative(root, dir))
       own.set(dir, ok)
     }
     return ok
@@ -937,12 +971,13 @@ function notThroughLink(files: readonly string[], root: string): string[] {
  * wrote `dist/out/…` and now writes `dist/out`) blocks the rename, and an
  * empty directory is not an output anyone declared. A directory that still
  * holds something — a stray the globs do not cover — stays, and the restore
- * says so if it is in the way.
+ * says so if it is in the way. With a `scope`, only a directory inside it
+ * goes (`pruneScope`).
  */
 async function pruneEmptiedDirs(
   root: string,
   removed: readonly string[],
-  keep?: ReadonlySet<string>,
+  scope?: PruneScope,
 ): Promise<void> {
   const rootResolved = path.resolve(root)
   // LEVEL ORDER, not a walk-up per directory. A parent is attempted only
@@ -960,7 +995,9 @@ async function pruneEmptiedDirs(
     const parents = new Set<string>()
     const dirs = [...level].filter(
       (dir) =>
-        dir !== rootResolved && dir.startsWith(rootResolved + path.sep) && keep?.has(dir) !== true,
+        dir !== rootResolved &&
+        dir.startsWith(rootResolved + path.sep) &&
+        (scope === undefined || inScope(dir, scope)),
     )
     const gone = (err: NodeJS.ErrnoException): boolean => err.code === 'ENOENT'
     if (dirs.length <= SYNC_CLEAN_MAX) {
@@ -983,19 +1020,42 @@ async function pruneEmptiedDirs(
   }
 }
 
+interface PruneScope {
+  /** Wildcard globs' roots (`dist` for `dist/**`): prune strictly below. */
+  below: string[]
+  /** Literal outputs (`out` as a tree): prune the path itself and below. */
+  atOrBelow: string[]
+}
+
 /**
- * The directories the wildcard output globs are rooted at, absolute. A
- * literal names a file or a tree whose shape the task decides, so it has
- * none; nor has a glob rooted at the project itself.
+ * Where a clean, before a miss or a restore, may prune: only the trees the
+ * task declared. A directory above a glob's root or holding a literal
+ * output (`out` for `out/a.txt`) stays: a sibling task running beside this
+ * one may have just made it and not yet written into it, and pruning it
+ * failed that task "Directory nonexistent". A glob's root stays: the task
+ * writes under it, and a remove there bought only an rmdir and the task's
+ * mkdir (B-49). A literal's own path goes: the entry or the task may need
+ * a file there. A glob rooted at the project prunes nothing.
  */
-function globRoots(projectDir: string, outputs: readonly string[]): Set<string> {
-  const roots = new Set<string>()
+function pruneScope(base: string, outputs: readonly string[]): PruneScope {
+  const scope: PruneScope = { below: [], atOrBelow: [] }
   for (const g of outputs) {
-    if (g.startsWith('!') || isLiteralPattern(g)) continue
+    if (g.startsWith('!')) continue
+    if (isLiteralPattern(g)) {
+      scope.atOrBelow.push(path.resolve(base, stripTrailingSlash(normalizeGlob(g))))
+      continue
+    }
     const prefix = staticPrefix(g)
-    if (prefix !== '.') roots.add(path.resolve(projectDir, prefix))
+    if (prefix !== '.') scope.below.push(path.resolve(base, prefix))
   }
-  return roots
+  return scope
+}
+
+function inScope(dir: string, scope: PruneScope): boolean {
+  return (
+    scope.below.some((r) => dir.startsWith(r + path.sep)) ||
+    scope.atOrBelow.some((r) => dir === r || dir.startsWith(r + path.sep))
+  )
 }
 
 /**
@@ -1033,7 +1093,11 @@ export async function cleanWorkspaceOutputs(args: {
   outputs: string[]
 }): Promise<string[]> {
   const files = await resolveWorkspaceOutputs(args)
-  await pruneEmptiedDirs(args.workspaceRoot, await removeAll(files, args.workspaceRoot))
+  await pruneEmptiedDirs(
+    args.workspaceRoot,
+    await removeAll(files, args.workspaceRoot),
+    pruneScope(args.workspaceRoot, args.outputs),
+  )
   return files.map((f) => relPosix(args.workspaceRoot, f))
 }
 
@@ -1133,6 +1197,9 @@ interface ResolveFilesArgs {
   workspaceRoot: string
   files: string[] | undefined
   ownOutputs: string[]
+  /** Root-relative `outputs.workspaceFiles`, and the project's root-relative directory. */
+  ownWorkspaceOutputs: readonly string[]
+  projectRel: string
   nestedProjectDirs: string[]
   gitFilesCache?: GitFilesCache
   projectFilesCache?: ProjectFilesCache
@@ -1324,6 +1391,8 @@ async function resolveFiles(
   const { positive, negative, isExcluded, ownOutput, positiveGlobs, isPositive } = plan
 
   const nested = inNestedProject(args.projectDir, args.nestedProjectDirs)
+  // Its root-anchored outputs that land in the project, as `files` sees them.
+  const ownWsOutput = inProject(args.projectRel, outputMatcher(args.ownWorkspaceOutputs))
 
   // Defer to git for the file set (Turbo / Nx parity). Nested .gitignore
   // files, .git/info/exclude, and global excludes all participate
@@ -1335,7 +1404,7 @@ async function resolveFiles(
   // duration of one orchestrator run.
   // Everything below the snapshot that decides the result: the project, what
   // it declares, what it excludes as its own outputs, and the boundaries.
-  const memoKey = `${args.projectDir}\0${positive.join('\u0001')}\0${negative.join('\u0001')}\0${args.ownOutputs.join('\u0001')}\0${args.nestedProjectDirs.join('\u0001')}`
+  const memoKey = `${args.projectDir}\0${positive.join('\u0001')}\0${negative.join('\u0001')}\0${args.ownOutputs.join('\u0001')}\0${args.ownWorkspaceOutputs.join('\u0001')}\0${args.nestedProjectDirs.join('\u0001')}`
   let gitFiles = args.gitFilesCache?.snapshotFor(args.projectDir, positiveGlobs)
   let undecodable = args.gitFilesCache?.undecodableNames
   if (gitFiles !== undefined) {
@@ -1346,7 +1415,7 @@ async function resolveFiles(
     if (memo !== undefined && memo.snapshot === gitFiles) {
       return {
         files: [...memo.result],
-        listing: listingFor(args.projectDir, gitFiles, plan, nested),
+        listing: listingFor(args.projectDir, gitFiles, plan, nested, ownWsOutput),
       }
     }
   }
@@ -1397,7 +1466,7 @@ async function resolveFiles(
       input = isPositive(rel) && !isExcluded(rel) && !ownOutput(rel)
       verdicts.set(rel, input)
     }
-    if (!input || nested(rel)) continue
+    if (!input || nested(rel) || ownWsOutput(rel)) continue
     candidates.push(base === undefined ? path.resolve(args.projectDir, rel) : base + rel)
   }
   const unmatchedLiterals = unanswered(plan.literals, gitFiles)
@@ -1424,7 +1493,10 @@ async function resolveFiles(
   // Stored only on the way out: a declaration whose literal named an
   // invisible file threw above, and every task sharing it must throw too.
   args.projectFilesCache?.set(memoKey, { snapshot: gitFiles, result: resolved })
-  return { files: [...resolved], listing: listingFor(args.projectDir, gitFiles, plan, nested) }
+  return {
+    files: [...resolved],
+    listing: listingFor(args.projectDir, gitFiles, plan, nested, ownWsOutput),
+  }
 }
 
 function listingFor(
@@ -1432,11 +1504,12 @@ function listingFor(
   listed: readonly string[],
   plan: FilesPlan,
   nested: (rel: string) => boolean,
+  ownWsOutput: (rel: string) => boolean,
 ): InputListing {
   return {
     root,
     listed,
-    isInput: (rel) => inPlan(plan, rel),
+    isInput: (rel) => inPlan(plan, rel) && !ownWsOutput(rel),
     nested,
     prefixes: plan.prefixes,
     literals: plan.literals,

package/src/cache/layered-cache.ts

@@ -185,7 +185,27 @@ class ScopedRemote implements RemoteCacheLayer {
   }
 
   async has(hash: string): Promise<boolean> {
-    return (await this.remote.has(this.scoped(hash))) || this.remote.has(hash)
+    return this.fallThrough(
+      () => this.remote.has(this.scoped(hash)),
+      () => this.remote.has(hash),
+    )
+  }
+
+  /**
+   * The scope's answer, else the trusted one. A scope lookup that fails
+   * still asks the trusted key, so a hit there is not lost; its error is
+   * rethrown (and warned) when the trusted key fails or has nothing too.
+   */
+  private async fallThrough<T>(own: () => Promise<T>, trusted: () => Promise<T>): Promise<T> {
+    let found: T
+    try {
+      found = await own()
+    } catch (err) {
+      const fallback = await trusted().catch(() => undefined)
+      if (!fallback) throw err
+      return fallback
+    }
+    return found || trusted()
   }
 
   private async scopedHasMany(hashes: readonly string[]): Promise<Set<string> | null> {
@@ -207,7 +227,10 @@ class ScopedRemote implements RemoteCacheLayer {
     hash: string,
   ): Promise<{ body: Blob | Response; durationMs: number | undefined } | null> {
     if (this.trustedOnly.has(hash)) return this.remote.get(hash)
-    return (await this.remote.get(this.scoped(hash))) ?? this.remote.get(hash)
+    return this.fallThrough(
+      () => this.remote.get(this.scoped(hash)),
+      () => this.remote.get(hash),
+    )
   }
 
   put(hash: string, body: Blob, meta: { durationMs: number }): Promise<void> {

package/src/cache/tar-stream.ts

@@ -11,7 +11,7 @@
 // short entry. Non-regular entries are reported with their type and their
 // bodies skipped; the caller decides what to materialise (nothing but `0`).
 
-export interface TarEntry {
+interface TarEntry {
   name: string
   size: number
   /** POSIX typeflag: '0' regular, '5' directory, '2' symlink, … */

package/src/cli/cache.ts

@@ -185,19 +185,9 @@ async function pruneCmd(args: readonly string[]): Promise<number> {
     printPruned({ evicted: 0, bytesFreed: 0, orphans: 0, orphanBytes: 0 }, dry, json)
     return 0
   }
-  if (parsed.dryRun === true) {
-    const earlier = await Cache.orphansBeforeReset(dir)
-    if (earlier !== null) {
-      warnToStderr(
-        `[vx] the cache index is schema ${earlier.found} from another vx version: the prune resets it first, and every artifact past the hour's grace is then an orphan`,
-      )
-      printPruned({ evicted: 0, bytesFreed: 0, ...earlier }, true, json)
-      return 0
-    }
-  }
   const cache =
     parsed.dryRun === true
-      ? new Cache(dir, undefined, undefined, undefined, 'inspect', storeRoot)
+      ? new Cache(dir, undefined, undefined, undefined, 'preview', storeRoot)
       : new Cache(dir, undefined, root, undefined, 'open', storeRoot)
   // A prune deletes rows and artifacts; a cache this user cannot write is
   // refused up front with the directory named, as a run refuses it, rather

package/src/cli/completions.ts

@@ -8,6 +8,13 @@
 import { acceptedFlags, CORE_VERBS, flagHint, seeHelp } from './help.js'
 import { nearest } from '../util/index.js'
 
+/** A flag whose value is one of a fixed set; the tests hold each to its parser. */
+export const FLAG_VALUES: Readonly<Record<string, readonly string[]>> = {
+  '--format': ['pretty', 'json'],
+  '--output-logs': ['full', 'errors-only', 'hash-only', 'none'],
+  '--download': ['all', 'toplevel', 'none'],
+}
+
 export type CompletionShell = 'bash' | 'zsh' | 'fish'
 const SHELLS: readonly CompletionShell[] = ['bash', 'zsh', 'fish']
 
@@ -36,6 +43,14 @@ export function completionScript(shell: CompletionShell, verbs: readonly string[
       ...((CORE_VERBS as readonly string[]).includes(v) ? verbFlags(v) : ['--help']),
     ],
   }))
+  // `vx run --output-logs <Tab>` offered the flags again; a flag with a
+  // fixed value set offers that set.
+  const values = table.flatMap((t) =>
+    t.words.flatMap((w) => {
+      const vs = FLAG_VALUES[w]
+      return vs === undefined ? [] : [{ verb: t.verb, flag: w, values: vs.join(' ') }]
+    }),
+  )
   switch (shell) {
     case 'bash':
       return [
@@ -43,10 +58,23 @@ export function completionScript(shell: CompletionShell, verbs: readonly string[
         '_vx() {',
         '  local cur="${COMP_WORDS[COMP_CWORD]}"',
         '  local verb="${COMP_WORDS[1]}"',
+        '  local prev="${COMP_WORDS[COMP_CWORD-1]}"',
         '  if [ "$COMP_CWORD" -eq 1 ]; then',
         `    COMPREPLY=($(compgen -W "${verbs.join(' ')}" -- "$cur"))`,
         '    return',
         '  fi',
+        // bash splits `--format=js` at the `=` (COMP_WORDBREAKS).
+        '  if [ "$cur" = "=" ]; then',
+        '    cur=""',
+        '  elif [ "$prev" = "=" ]; then',
+        '    prev="${COMP_WORDS[COMP_CWORD-2]}"',
+        '  fi',
+        '  case "$verb $prev" in',
+        ...values.map(
+          (v) =>
+            `    "${v.verb} ${v.flag}") COMPREPLY=($(compgen -W "${v.values}" -- "$cur")); return ;;`,
+        ),
+        '  esac',
         '  case "$verb" in',
         ...table.map(
           (t) => `    ${t.verb}) COMPREPLY=($(compgen -W "${t.words.join(' ')}" -- "$cur")) ;;`,
@@ -66,6 +94,9 @@ export function completionScript(shell: CompletionShell, verbs: readonly string[
         `    compadd -- ${verbs.join(' ')}`,
         '    return',
         '  fi',
+        '  case "${words[2]} ${words[CURRENT-1]}" in',
+        ...values.map((v) => `    "${v.verb} ${v.flag}") compadd -- ${v.values}; return ;;`),
+        '  esac',
         '  case "${words[2]}" in',
         ...table.map((t) => `    ${t.verb}) compadd -- ${t.words.join(' ')} ;;`),
         '  esac',
@@ -86,11 +117,14 @@ export function completionScript(shell: CompletionShell, verbs: readonly string[
         'complete -c vx -f',
         ...verbs.map((v) => `complete -c vx -n __fish_use_subcommand -a ${v}`),
         ...table.flatMap((t) =>
-          t.words.map((w) =>
-            w.startsWith('--')
-              ? `complete -c vx -n "__fish_seen_subcommand_from ${t.verb}" -l ${w.slice(2)}`
-              : `complete -c vx -n "__fish_seen_subcommand_from ${t.verb}" -a ${w}`,
-          ),
+          t.words.map((w) => {
+            const on = `complete -c vx -n "__fish_seen_subcommand_from ${t.verb}"`
+            if (!w.startsWith('--')) return `${on} -a ${w}`
+            const vs = FLAG_VALUES[w]
+            return vs === undefined
+              ? `${on} -l ${w.slice(2)}`
+              : `${on} -l ${w.slice(2)} -x -a "${vs.join(' ')}"`
+          }),
         ),
         '',
       ].join('\n')
@@ -111,7 +145,9 @@ export async function completionsCmd(
       return 1
     }
     const one = shell !== undefined && args.length === 1
-    const best = one ? nearest(shell, SHELLS) : undefined
+    // One edit: shell names are three or four letters, so two edits took
+    // `tcsh` to `bash`, a different shell.
+    const best = one ? nearest(shell, SHELLS, 1) : undefined
     process.stderr.write(
       `vx completions: expected one shell — bash, zsh or fish${one ? ` (got ${shell})` : ''}${best === undefined ? '' : `. Did you mean ${best}?`}${seeHelp('completions')}\n`,
     )

package/src/cli/foreign-flags.ts

@@ -36,6 +36,17 @@ const list = (v: string | undefined): string[] =>
     .map((s) => s.trim())
     .filter((s) => s !== '')
 
+// Nx's `--projects` labels (find-matching-projects, 23.2.1): `name:` and
+// `directory:` say which match to make; vx's filter says it by form. `tag:`
+// is a filter form already.
+const nxPattern = (p: string): string => {
+  const neg = p.startsWith('!') ? '!' : ''
+  const s = neg === '' ? p : p.slice(1)
+  if (s.startsWith('name:')) return `${neg}${s.slice(5)}`
+  if (s.startsWith('directory:')) return `${neg}./${s.slice(10)}`
+  return p
+}
+
 const GRAPH_IMAGE = /\.(svg|png|jpe?g|pdf|json|html|mermaid)$/i
 
 export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
@@ -142,7 +153,14 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     outcome: 'same',
     vx: '`--output-logs full|errors-only|hash-only|none`',
   },
-  { runner: 'turbo', names: ['--no-cache'], value: false, outcome: 'same', vx: '`--no-cache`' },
+  {
+    runner: 'turbo',
+    names: ['--no-cache'],
+    value: false,
+    outcome: 'same',
+    // Turbo 2.11's own help: "Equivalent to `--cache=local:r,remote:r`".
+    vx: "`--no-cache` reads nothing either; Turbo's (reads, no writes) is `--cache local:r,remote:r`",
+  },
   {
     runner: 'turbo',
     names: ['--cache'],
@@ -407,12 +425,15 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     names: ['-p', '--projects'],
     value: true,
     outcome: 'alias',
-    vx: "`--filter <pattern>`, one per project; a list opening with `!` starts from all (`--filter '*'`)",
+    vx: "`--filter <pattern>`, one per project (`directory:<d>` is `./<d>`, `name:<n>` is `<n>`); a list opening with `!` starts from all (`--filter '*'`)",
     // Nx reads a leading exclusion as "all projects but": `-p '!b,a'` is
     // every project except b, where vx's filters alone would select a.
     to: (v) => {
       const ps = list(v)
-      return [...(ps[0]?.startsWith('!') ? ['*'] : []), ...ps].flatMap((p) => ['--filter', p])
+      return [...(ps[0]?.startsWith('!') ? ['*'] : []), ...ps].flatMap((p) => [
+        '--filter',
+        nxPattern(p),
+      ])
     },
   },
   {
@@ -421,7 +442,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     value: true,
     outcome: 'alias',
     vx: "`--filter '!<pattern>'`, one per project",
-    to: (v) => list(v).flatMap((p) => ['--filter', `!${p}`]),
+    to: (v) => list(v).flatMap((p) => ['--filter', `!${nxPattern(p)}`]),
   },
   {
     runner: 'nx',

package/src/cli/help.ts

@@ -111,7 +111,7 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  vx lock [--check]',
     '  vx init [--dry] [--force] [--mjs] [--plugin <seam>]',
     '  vx upgrade [TAG]',
-    '  vx show [PROJECT[#TASK] | TASK] [--format pretty|json]',
+    '  vx show [PROJECT[#TASK] | TASK] [--filter <pattern>] [--affected[=<ref>]] [--format pretty|json]',
     '  vx info [--format pretty|json] [--cache-dir <path>]',
     '  vx why (TASK | PKG#TASK) [--run RUNID] [--format pretty|json] [--cache-dir <path>]',
     '  vx last [RUNID] [--list[=N]] [--failed] [--format pretty|json] [--cache-dir <path>]',
@@ -140,8 +140,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                                  to its flags; unnamed layers keep their value. Examples:',
     '                                  local:rw,remote:r (remote read-only), remote: (remote off),',
     '                                  local:r (local read-only).',
-    '      --cache-dir <path>          Cache directory override (cwd-relative). Beats the workspace',
-    '                                  cacheDir field + the .vx/cache default.',
+    '      --cache-dir <path>          Cache directory override (cwd-relative). Beats VX_CACHE_DIR,',
+    '                                  the workspace cacheDir field and the ~/.vx/<id>/cache default.',
     '      --retry <n>                 Re-run a failed task up to <n> more times (default for tasks',
     "                                  without their own exec.retries; explicit config wins). Doesn't",
     '                                  affect cache keys.',
@@ -209,6 +209,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                       evaluation, not the lock), one block per task.',
     "  vx show <pkg>#<task> Print a single task's resolved config.",
     '  vx show <task>       That task in every project declaring it.',
+    "      --filter <pattern>  The list (or a task's projects) as `vx run --filter` selects.",
+    '      --affected[=<ref>]  Only what `vx run --affected` selects: changed and dependents.',
     '      --format <fmt>   pretty (default) | json.',
     '  vx info              Workspace doctor: vx/bun/git versions, project +',
     '                       task counts, cache dir/entries/size, recent runs,',

package/src/cli/init.ts

@@ -369,7 +369,7 @@ function namelessNotes(root: string, dirs: readonly string[]): string[] {
   const withScripts = dirs
     .filter((dir) => {
       const scripts = (
-        JSON.parse(readText(path.join(dir, 'package.json')) || '{}') as {
+        JSON.parse(readText(path.join(dir, 'package.json')).replace(/^\uFEFF/, '') || '{}') as {
           scripts?: unknown
         }
       ).scripts

package/src/cli/plan-format.ts

@@ -29,6 +29,7 @@ export function formatPlanText(plan: RunPlan): string {
   let miss = 0
   let nocache = 0
   let noop = 0
+  let idle = 0
   for (const t of real) {
     // `@noop`: the run succeeds it without running, whatever its key says.
     const skipped = t.executor === 'noop'
@@ -56,6 +57,7 @@ export function formatPlanText(plan: RunPlan): string {
     else if (t.cacheStatus === 'hit-remote') remote++
     else if (t.cacheStatus === 'miss') miss++
     else if (t.cacheStatus === 'no-cache') nocache++
+    else if (t.cacheStatus === 'not-started') idle++
   }
 
   const hitParts: string[] = []
@@ -67,6 +69,7 @@ export function formatPlanText(plan: RunPlan): string {
   if (miss > 0) summary.push(`${miss} would run`)
   if (nocache > 0) summary.push(`${nocache} no-cache`)
   if (noop > 0) summary.push(`${noop} noop`)
+  if (idle > 0) summary.push(`${idle} not started`)
   lines.push('')
   lines.push(summary.join(', ') + '.')
 
@@ -199,6 +202,8 @@ function symbolFor(s: CacheStatus): string {
       return '·'
     case 'group':
       return '○'
+    case 'not-started':
+      return '−'
   }
 }
 
@@ -214,6 +219,8 @@ function describe(s: CacheStatus): string {
       return 'no-cache (would exec)'
     case 'group':
       return 'group task'
+    case 'not-started':
+      return 'not started (unneeded)'
   }
 }
 
@@ -229,5 +236,7 @@ function dotColor(s: CacheStatus): string {
       return '#e5e7eb' // gray-200
     case 'group':
       return '#f5d0fe' // fuchsia-200
+    case 'not-started':
+      return '#ffffff'
   }
 }