@vzn/vx 0.0.631 → 0.0.633

package/src/cli/docs.ts

@@ -0,0 +1,167 @@
+// `vx docs <query> [--limit N] [--format pretty|json]` — search vx's
+// reference offline, for an agent that cannot reach the site: each page is
+// cut at its headings, and the sections holding every query word print
+// whole, best first.
+
+import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
+
+const SITE = 'https://vznjs.github.io/vx/'
+const DEFAULT_LIMIT = 3
+
+interface DocsArgs {
+  terms: string[]
+  limit: number
+  json: boolean
+  error?: string
+}
+
+function parseDocsArgs(args: readonly string[]): DocsArgs {
+  const out: DocsArgs = { terms: [], limit: DEFAULT_LIMIT, json: false }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!
+    if (a === '--format' || a.startsWith('--format=')) {
+      const fv = formatValue(a === '--format' ? args[++i] : a.slice('--format='.length), 'docs')
+      if (typeof fv === 'object') return { ...out, error: fv.error }
+      out.json = fv === 'json'
+    } else if (a === '--limit' || a.startsWith('--limit=')) {
+      const v = a === '--limit' ? args[++i] : a.slice('--limit='.length)
+      const n = Number(v)
+      if (!Number.isInteger(n) || n < 1) {
+        return {
+          ...out,
+          error: `--limit takes a whole number above 0 (got ${v ?? 'nothing'})${seeHelp('docs')}`,
+        }
+      }
+      out.limit = n
+    } else if (a.startsWith('-')) {
+      return { ...out, error: `${refusedWord(a)}: ${a}${flagHint('docs', a)}${seeHelp('docs')}` }
+    } else out.terms.push(...words(a))
+  }
+  return out
+}
+
+export interface DocsHit {
+  page: string
+  heading: string
+  url: string
+  text: string
+}
+
+function words(s: string): string[] {
+  return s.toLowerCase().match(/[a-z0-9][a-z0-9._-]*/g) ?? []
+}
+
+/** GitHub's heading anchor, which Starlight shares: lowercase, punctuation dropped, spaces to `-`. */
+function anchor(heading: string): string {
+  return heading
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N} _-]/gu, '')
+    .replace(/ /g, '-')
+}
+
+/** A page's URL on the site; `features.md` is served as `all-features/`. */
+function pageUrl(page: string): string {
+  return `${SITE}${page === 'features' ? 'all-features' : page}/`
+}
+
+interface Section {
+  page: string
+  heading: string
+  text: string
+}
+
+/** Cut a page at its headings (outside code fences); the text before the first is the page's own. */
+function sections(page: string, md: string): Section[] {
+  const out: Section[] = []
+  let heading = ''
+  let lines: string[] = []
+  let fence = false
+  const flush = () => {
+    const text = lines.join('\n').trim()
+    if (text !== '') out.push({ page, heading, text })
+  }
+  for (const line of md.split('\n')) {
+    if (/^\s*(```|~~~)/.test(line)) fence = !fence
+    const h = fence ? null : /^#{1,4} (.+)$/.exec(line)
+    if (h !== null) {
+      flush()
+      heading = h[1]!.replace(/`/g, '').trim()
+      lines = [line]
+    } else lines.push(line)
+  }
+  flush()
+  return out
+}
+
+function count(hay: string, term: string): number {
+  let n = 0
+  for (let i = hay.indexOf(term); i !== -1; i = hay.indexOf(term, i + term.length)) n++
+  return n
+}
+
+/** The sections holding every term, best first: a term in the heading outweighs any count in the text. */
+export function searchDocs(
+  pages: Readonly<Record<string, string>>,
+  terms: readonly string[],
+  limit: number,
+): DocsHit[] {
+  const scored: { s: Section; score: number; order: number }[] = []
+  let order = 0
+  for (const [page, md] of Object.entries(pages)) {
+    for (const s of sections(page, md)) {
+      order++
+      const head = s.heading.toLowerCase()
+      const body = s.text.toLowerCase()
+      let score = 0
+      let all = true
+      for (const t of terms) {
+        const inBody = count(body, t)
+        if (inBody === 0) all = false
+        score += (head.includes(t) ? 10 : 0) + Math.min(inBody, 5)
+      }
+      if (all) scored.push({ s, score, order })
+    }
+  }
+  scored.sort((a, b) => b.score - a.score || a.order - b.order)
+  return scored.slice(0, limit).map(({ s }) => ({
+    page: s.page,
+    heading: s.heading,
+    url: s.heading === '' ? pageUrl(s.page) : `${pageUrl(s.page)}#${anchor(s.heading)}`,
+    text: s.text,
+  }))
+}
+
+export async function docsCmd(args: readonly string[]): Promise<number> {
+  const parsed = parseDocsArgs(args)
+  if (parsed.error) return refuse('docs', args, parsed.error, 'VX_E_USAGE')
+  if (parsed.terms.length === 0) {
+    return refuse(
+      'docs',
+      args,
+      `name what to look for, as in \`vx docs cache inputs\`${seeHelp('docs')}`,
+      'VX_E_USAGE',
+    )
+  }
+  const { PAGES } = await import('./docs-corpus.js')
+  const hits = searchDocs(PAGES, parsed.terms, parsed.limit)
+  const query = parsed.terms.join(' ')
+  if (parsed.json) {
+    process.stdout.write(`${JSON.stringify({ query, hits })}\n`)
+    return 0
+  }
+  if (hits.length === 0) {
+    process.stdout.write(
+      `vx docs: no section of ${Object.keys(PAGES).join(', ')} holds every word of "${query}"; try fewer words, or ${SITE}llms.txt\n`,
+    )
+    return 0
+  }
+  process.stdout.write(
+    hits
+      .map(
+        (h) =>
+          `── ${h.page}.md${h.heading === '' ? '' : ` § ${h.heading}`} · ${h.url}\n\n${h.text}\n`,
+      )
+      .join('\n'),
+  )
+  return 0
+}

package/src/cli/foreign-flags.ts

@@ -361,7 +361,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     names: ['--json'],
     value: false,
     outcome: 'refuse',
-    vx: "use `--dry=json` for the plan, `--summarize[=<path>]` for the run's JSON record",
+    vx: "use `--format json` for the run's result on stdout, `--dry=json` for the plan",
   },
   {
     runner: 'turbo',

package/src/cli/help.ts

@@ -1,5 +1,5 @@
 import type { ColorSupport, paint as Paint } from '../orchestrator/index.js'
-import { CORE_VERBS, nearest } from '../util/index.js'
+import { CORE_VERBS, errorDocument, maskedLine, nearest, wantsJson } from '../util/index.js'
 
 export async function printHelp(
   pluginCommands: readonly string[] = [],
@@ -108,13 +108,14 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  vx run [OPTIONS] [TASK | PKG#TASK ...] [-- forwarded-args...]',
     '  vx watch [OPTIONS] TASK [-- forwarded-args...]',
     '  vx cache prune [--older-than <duration>] [--max-size <size>] [--dry-run] [--format pretty|json] [--cache-dir <path>]',
-    '  vx lock [--check]',
-    '  vx init [--dry] [--force] [--mjs] [--plugin <seam>]',
+    '  vx lock [--check] [--format pretty|json]',
+    '  vx init [--dry [--format pretty|json]] [--force] [--mjs] [--native|--keep] [--plugin <seam>]',
     '  vx upgrade [TAG]',
     '  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>]',
+    '  vx last [RUNID] [--list[=N]] [--failed] [--log <task>] [--format pretty|json] [--cache-dir <path>]',
+    '  vx docs <query> [--limit N] [--format pretty|json]',
     '  vx completions bash|zsh|fish',
     '  vx help [VERB]',
     '  vx version',
@@ -161,6 +162,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '      --graph[=<path>]     Emit Graphviz DOT (stdout if no path).',
     '',
     'Artifacts (for run):',
+    '      --format <fmt>        pretty (default) | json: print the --summarize document',
+    '                            on stdout when the run ends; every other line goes to stderr.',
     '      --summarize[=<path>]  Write per-run JSON to <cacheDir>/runs/<run_id>.json.',
     '      --profile[=<path>]    Write Chrome-trace JSON (default profile.json).',
     '      --report[=markdown]   Print a markdown run report to stdout after the run.',
@@ -227,6 +230,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                       table, failures first. No re-execution, no cache probe.',
     '      --list[=N]       List the N most recent runs (default 10) with run ids.',
     '      --failed         Only failed runs: the latest one, or with --list the list.',
+    "      --log <task>     That task's output in the run (latest that ran it): a failure's",
+    '                       or the cached log; none for an uncached pass.',
     '      --format <fmt>   pretty (default) | json.',
     '  info, why and last:',
     '      --cache-dir <path>  Read the cache a run with the same flag uses.',
@@ -235,14 +240,17 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  vx init              Generate vx.workspace.ts + one vx.config.ts per package',
     '                       from package.json scripts. Unmappable settings become',
     '                       TODO(vx-migrate) comments. Beside turbo.json or nx.json:',
-    '                       only vx.workspace.ts, declaring turbo() or nx().',
+    '                       runs @vzn/vx-migrate, which asks native or keep.',
     '      --dry            Print the generated files instead of writing them.',
+    '      --format json    With --dry: the plan as one JSON document (schemas/init.json).',
     '      --force          Overwrite existing vx.config.* files.',
     '      --mjs            Write .mjs files (no type import) instead of .ts.',
+    '      --native         Turbo or Nx: write a vx.config.ts per package (no question).',
+    '      --keep           Turbo or Nx: only vx.workspace.ts, declaring turbo() or nx().',
     '      --plugin <seam>  Instead: write plugins/<seam>.ts, a runnable plugin, and its',
     '                       test (executor, cache, telemetry, schedule, admit, commands,',
     '                       project, graph, key).',
-    '  From turbo.json or an Nx project graph: `bunx @vzn/vx-migrate` (its own package).',
+    '  From turbo.json or an Nx project graph: `vx init` runs `@vzn/vx-migrate` (its own package).',
     '',
     'Shell completions:',
     '  vx completions <shell>   Print a completion script for bash, zsh or fish: the',
@@ -250,6 +258,13 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                           every flag of each. `eval "$(vx completions bash)"`,',
     '                           or write it where the shell loads completions from.',
     '',
+    'Docs:',
+    '  vx docs <query>      Search the reference offline (cli, schema, caching, execution,',
+    '                       patterns, security, features): the sections holding every',
+    '                       word of the query print whole, best first, with their URL.',
+    '      --limit N        How many sections (default 3).',
+    '      --format json    {query, hits: [{page, heading, url, text}]}.',
+    '',
     'Config lock:',
     '  vx lock              Evaluate every vx.config in the current environment and',
     '                       freeze the resolved objects into vx-lock.json. Plain runs',
@@ -258,7 +273,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  vx lock --check      Audit the lock: file-changed hash report PLUS a full',
     '                       re-evaluation compared against the frozen objects. Exits 1',
     '                       on drift (e.g. configs that read env vars). Run it before',
-    '                       `vx run --frozen` in CI.',
+    '                       `vx run --frozen` in CI. With --format json it prints',
+    '                       {upToDate, audited, notAudited, problems}.',
     '',
     ...(pluginCommands.length > 0 ? ['Plugin commands:', ...pluginCommands, ''] : []),
   ].join('\n')
@@ -353,6 +369,7 @@ export const WATCH_REFUSED_FLAGS: readonly string[] = [
   '--report',
   '--report-file',
   '--verbosity',
+  '--format',
 ]
 
 /**
@@ -380,3 +397,21 @@ export function acceptedFlags(verb: string): string[] {
 }
 
 export { CORE_VERBS } from '../util/index.js'
+
+/**
+ * A refusal a verb prints itself rather than throws: one line on stderr,
+ * exit 1, and under `--format json` / `--dry=json` the same as the error
+ * document on stdout that `bin.ts` prints for a thrown one (cli.md § Error
+ * codes), so an agent reads a code.
+ */
+export function refuse(
+  verb: string,
+  args: readonly string[],
+  message: string,
+  code: string,
+): number {
+  const line = `vx ${verb}: ${message}`
+  process.stderr.write(`${line}\n`)
+  if (wantsJson(args)) process.stdout.write(errorDocument(code, maskedLine(line)))
+  return 1
+}

package/src/cli/index.ts

@@ -4,7 +4,15 @@
 import { VERSION } from '../version.js'
 import { CORE_VERBS, flagHint, printHelp, refusedWord, seeHelp } from './help.js'
 import { FOREIGN_VERBS } from './foreign-flags.js'
-import { isUserError, MOVED_VERBS, nearest, UserError } from '../util/index.js'
+import {
+  errorDocument,
+  isUserError,
+  maskedLine,
+  MOVED_VERBS,
+  nearest,
+  UserError,
+  wantsJson,
+} from '../util/index.js'
 
 // Every verb is imported when invoked, `run` included, and so is the
 // plugin-verb lookup: each pulls in the orchestrator and the workspace
@@ -101,6 +109,8 @@ export async function run(argv: readonly string[]): Promise<number> {
       return await (await import('./cache.js')).cacheCmd(rest)
     case 'lock':
       return await (await import('./lock.js')).lockCmd(rest)
+    case 'docs':
+      return await (await import('./docs.js')).docsCmd(rest)
     case 'init':
       return await (await import('./init.js')).initCmd(rest)
     case 'upgrade':
@@ -151,6 +161,14 @@ export async function run(argv: readonly string[]): Promise<number> {
       // both things: the verb is unknown HERE, and why the lookup could not
       // finish — a typo still reads as a typo, and a real plugin verb still
       // points at the file that broke it.
+      // Every answer below is "no such verb here": under --format json the
+      // agent reads it as one code, as a verb's own refusal gives one.
+      const unknown = (text: string, code = 'VX_E_UNKNOWN_COMMAND'): number => {
+        process.stderr.write(text)
+        if (wantsJson(rest))
+          process.stdout.write(errorDocument(code, maskedLine(text.split('\n')[0]!)))
+        return 1
+      }
       const loadNote =
         resolved !== null && 'loadError' in resolved
           ? `\n  (plugin verbs could not be looked up: vx.workspace failed to load: ${resolved.loadError})`
@@ -160,8 +178,7 @@ export async function run(argv: readonly string[]): Promise<number> {
       // workspace that declares a plugin verb of that name keeps it.
       const moved = MOVED_VERBS[command] ?? FOREIGN_VERBS[command]
       if (moved !== undefined) {
-        process.stderr.write(`${moved}${loadNote}\n`)
-        return 1
+        return unknown(`${moved}${loadNote}\n`)
       }
       // A task typed where the verb goes (`turbo build`, `nx build app`),
       // `turbo dev` included: a repo's own `dev` task beats the no-service note.
@@ -176,8 +193,7 @@ export async function run(argv: readonly string[]): Promise<number> {
             ).taskVerbHint(command, rest, process.cwd(), guess === '' && !command.startsWith('-'))
           : null
       if (task !== null) {
-        process.stderr.write(`vx: ${task}\n`)
-        return 1
+        return unknown(`vx: ${task}\n`)
       }
       if (command === 'serve' || command === 'dev') {
         // vx core is only a task runner — it has no service layer of its
@@ -186,13 +202,12 @@ export async function run(argv: readonly string[]): Promise<number> {
         // We keep this neutral hint for the common muscle-memory verbs, but
         // core names no specific plugin package: any package can provide
         // these.
-        process.stderr.write(
+        return unknown(
           `vx: '${command}' is not a vx core command.\n` +
             `  vx core runs tasks in-process. A dashboard, remote cache, and\n` +
             `  distributed execution come from plugins — not core. See the plugin\n` +
             `  guide: https://vznjs.github.io/vx/guides/plugins/\n`,
         )
-        return 1
       }
       // One line, as a verb's own unknown flag or subcommand gets; the full
       // help after a typo was a hundred lines past the hint that mattered.
@@ -208,16 +223,15 @@ export async function run(argv: readonly string[]): Promise<number> {
       if (command.startsWith('-')) {
         // `-v` / `-V` is another tool's version flag, far from both names.
         const flag = /^-v$/i.test(command) ? '--version' : nearest(command, ['--help', '--version'])
-        process.stderr.write(
+        return unknown(
           `vx: unknown flag: ${command}${flag === undefined ? '' : ` (did you mean ${flag}?)`}; a verb's flags follow the verb (see \`vx help\`)\n`,
+          'VX_E_USAGE',
         )
-        return 1
       }
-      process.stderr.write(
+      return unknown(
         `vx: unknown command: ${command}${guess}${loadNote} (see \`vx help\`)\n` +
           (guess === '' && loadNote === '' ? verbSourceNote(resolved, declaredVerbs) : ''),
       )
-      return 1
     }
   }
 }

package/src/cli/info.ts

@@ -4,8 +4,9 @@
 // from the orchestrator's `collectInfo` (doctor.ts), which `vx mcp` reads
 // too; this file parses the flags and renders the rows.
 
+import os from 'node:os'
 import { collectInfo, type FlakyTask, type InfoFacts } from '../orchestrator/index.js'
-import { flagHint, formatValue, refusedWord, seeHelp } from './help.js'
+import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
 import { namedCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
 import { formatBytes } from './format.js'
 import { MIN_BUN } from '../util/index.js'
@@ -44,10 +45,7 @@ export function parseInfoArgs(args: readonly string[]): InfoArgs {
 
 export async function infoCmd(args: readonly string[]): Promise<number> {
   const parsed = parseInfoArgs(args)
-  if (parsed.error) {
-    process.stderr.write(`vx info: ${parsed.error}\n`)
-    return 1
-  }
+  if (parsed.error) return refuse('info', args, parsed.error, 'VX_E_USAGE')
   // `collectInfo` takes a resolved directory from `vx mcp` too, where one
   // not made yet is a workspace that never ran; the flag is the user's,
   // and a directory it names that is not there is a typo (item 900).
@@ -75,7 +73,7 @@ export function renderInfo(f: InfoFacts): string {
     ],
     ['git', f.git ?? '(not found)'],
     ['git status cache', renderGitStatusCache(f.gitStatusCache)],
-    ['workspace root', f.workspaceRoot],
+    ['workspace root', tildePath(f.workspaceRoot)],
     ['projects', describeProjects(f)],
     // Only when a config did not load: the count above says "zero" for
     // it, and this row says which and why.
@@ -88,10 +86,16 @@ export function renderInfo(f: InfoFacts): string {
     ['plugins', describePlugins(f.plugins)],
     ['workers', describeWorkers(f.workers)],
     ['memory', describeMemory(f.memory)],
-    ['cache dir', f.cacheDir],
-    ['cache store', f.cacheStore ?? 'none: the cache dir holds the entries'],
+    ['cache dir', tildePath(f.cacheDir)],
+    [
+      'cache store',
+      f.cacheStore === null ? 'none: the cache dir holds the entries' : tildePath(f.cacheStore),
+    ],
     ['cache versions', `keys ${f.cacheVersion} · index schema ${f.schemaVersion}`],
-    ['cache entries', `${f.cacheEntries} (${formatBytes(f.cacheBytes)})`],
+    ['cache entries', describeEntries(f)],
+    ...(f.cacheRetention !== null
+      ? ([['cache retention', describeRetention(f.cacheRetention)]] as [string, string][])
+      : []),
     // Only when there is something to say.
     ...(f.orphans.artifacts > 0
       ? ([
@@ -118,6 +122,31 @@ export function renderInfo(f: InfoFacts): string {
   return rows.map(([label, value]) => `${`${label}:`.padEnd(labelW + 1)} ${value}`).join('\n')
 }
 
+/** `812 (1.2 GB)`, or against `cacheRetention.maxSize`: `812 (1.2 GB of 10 GB, 12%)`. */
+function describeEntries(f: InfoFacts): string {
+  const max = f.cacheRetention?.maxBytes
+  const size =
+    max === undefined
+      ? formatBytes(f.cacheBytes)
+      : `${formatBytes(f.cacheBytes)} of ${formatBytes(max)}, ${Math.round((f.cacheBytes / max) * 100)}%`
+  return `${f.cacheEntries} (${size})`
+}
+
+/** What a run's end evicts: `entries unused for 30d, and the oldest entries past 10G`. */
+function describeRetention(r: NonNullable<InfoFacts['cacheRetention']>): string {
+  const parts = [
+    ...(r.olderThan !== undefined ? [`entries unused for ${r.olderThan}`] : []),
+    ...(r.maxSize !== undefined ? [`the oldest entries past ${r.maxSize}`] : []),
+  ]
+  return `each run evicts ${parts.join(', and ')}`
+}
+
+/** A path under the home directory as `~/…`: shorter, and no user name in a pasted report. */
+function tildePath(p: string): string {
+  const home = os.homedir()
+  return p === home ? '~' : p.startsWith(`${home}/`) ? `~${p.slice(home.length)}` : p
+}
+
 /**
  * `available (3 tasks declare exec.sandbox)`, with `, untraced — <why>, so
  * the reads it denies go unreported` where no strace can trace, or