@vzn/vx 0.0.0 → 0.0.12

package/src/cli/show.ts

@@ -0,0 +1,201 @@
+// `vx show [target]` — introspect the workspace's LIVE resolved configs.
+// No target: one line per project. `<project>`: every task's resolved
+// config, evaluated with the same loader the run path uses (scoped to
+// that single project). `<pkg>#<task>`: one task. This is deliberately
+// NOT the lock — vx-lock.json is already the frozen JSON; `show` answers
+// "what would a live run see here, now".
+
+import type { ProjectConfig, TaskConfig } from '../config.js'
+import { relPosix, UserError } from '../util/index.js'
+import {
+  findWorkspaceRoot,
+  listProjects,
+  loadProjectConfig,
+  loadWorkspace,
+  type ProjectMeta,
+} from '../workspace/index.js'
+
+export interface ShowArgs {
+  target?: string
+  format: 'pretty' | 'json'
+  error?: string
+}
+
+export function parseShowArgs(args: readonly string[]): ShowArgs {
+  const out: ShowArgs = { format: 'pretty' }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!
+    let format: string | undefined
+    if (a === '--format') format = args[++i] ?? ''
+    else if (a.startsWith('--format=')) format = a.slice('--format='.length)
+    else if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}` }
+    else if (out.target !== undefined) return { ...out, error: `unexpected argument: ${a}` }
+    else out.target = a
+
+    if (format !== undefined) {
+      if (format !== 'pretty' && format !== 'json') {
+        return { ...out, error: '--format must be pretty or json' }
+      }
+      out.format = format
+    }
+  }
+  return out
+}
+
+export async function showCmd(args: readonly string[]): Promise<number> {
+  const parsed = parseShowArgs(args)
+  if (parsed.error) {
+    process.stderr.write(`vx show: ${parsed.error}\n`)
+    return 1
+  }
+  const root = await findWorkspaceRoot(process.cwd())
+  const metas = await listProjects(await loadWorkspace(root))
+
+  if (parsed.target === undefined) {
+    process.stdout.write(await renderList(root, metas, parsed.format))
+    return 0
+  }
+
+  const hashAt = parsed.target.indexOf('#')
+  const projectName = hashAt === -1 ? parsed.target : parsed.target.slice(0, hashAt)
+  const taskName = hashAt === -1 ? undefined : parsed.target.slice(hashAt + 1)
+  if (taskName === '') throw new UserError(`missing task name after '#' in "${parsed.target}"`)
+
+  const meta = metas.find((m) => m.name === projectName)
+  if (!meta) {
+    throw new UserError(
+      `unknown project: "${projectName}"${suggest(
+        projectName,
+        metas.map((m) => m.name),
+      )}`,
+    )
+  }
+  const config = meta.configPath === null ? null : await loadProjectConfig(meta.configPath)
+  const dir = projectDir(root, meta)
+
+  if (taskName === undefined) {
+    process.stdout.write(renderProject(meta.name, dir, config, parsed.format))
+    return 0
+  }
+
+  const task = config?.tasks?.[taskName]
+  if (task === undefined) {
+    throw new UserError(
+      `unknown task: "${meta.name}#${taskName}"${suggest(
+        taskName,
+        Object.keys(config?.tasks ?? {}),
+      )}`,
+    )
+  }
+  process.stdout.write(renderTask(meta.name, dir, taskName, task, parsed.format))
+  return 0
+}
+
+/** Simple includes-match in both directions, case-insensitive. */
+function suggest(query: string, candidates: readonly string[]): string {
+  const q = query.toLowerCase()
+  const near = candidates.filter((c) => {
+    const n = c.toLowerCase()
+    return n.includes(q) || q.includes(n)
+  })
+  return near.length > 0 ? ` — did you mean ${near.join(', ')}?` : ''
+}
+
+function projectDir(root: string, meta: ProjectMeta): string {
+  const rel = relPosix(root, meta.dir)
+  return rel === '' ? '.' : rel
+}
+
+async function renderList(
+  root: string,
+  metas: readonly ProjectMeta[],
+  format: 'pretty' | 'json',
+): Promise<string> {
+  const rows = await Promise.all(
+    metas.map(async (meta) => {
+      const config = meta.configPath === null ? null : await loadProjectConfig(meta.configPath)
+      return {
+        name: meta.name,
+        dir: projectDir(root, meta),
+        tasks: Object.keys(config?.tasks ?? {}),
+        configured: meta.configPath !== null,
+      }
+    }),
+  )
+  if (format === 'json') {
+    return `${JSON.stringify(
+      rows.map(({ name, dir, tasks }) => ({ name, dir, tasks })),
+      null,
+      2,
+    )}\n`
+  }
+  const nameW = Math.max(...rows.map((r) => r.name.length))
+  const dirW = Math.max(...rows.map((r) => r.dir.length))
+  const lines = rows.map((r) => {
+    const tasks = r.configured
+      ? `${r.tasks.length} task${r.tasks.length === 1 ? '' : 's'}`
+      : '(no vx config)'
+    return `${r.name.padEnd(nameW)}  ${r.dir.padEnd(dirW)}  ${tasks}`
+  })
+  return `${lines.join('\n')}\n`
+}
+
+function renderProject(
+  name: string,
+  dir: string,
+  config: ProjectConfig | null,
+  format: 'pretty' | 'json',
+): string {
+  if (format === 'json') {
+    // Round-trip so the printed object is exactly the JSON form of the
+    // resolved config (drops `undefined` fields).
+    return `${JSON.stringify(JSON.parse(JSON.stringify({ name, dir, config })), null, 2)}\n`
+  }
+  const head = `${name} — ${dir}`
+  if (config === null) return `${head}\n  (no vx config)\n`
+  const tasks = Object.entries(config.tasks ?? {})
+  if (tasks.length === 0) return `${head}\n  (no tasks declared)\n`
+  const blocks = tasks.map(([taskName, task]) => taskBlock(taskName, task))
+  return `${head}\n\n${blocks.join('\n')}`
+}
+
+function renderTask(
+  name: string,
+  dir: string,
+  taskName: string,
+  task: TaskConfig,
+  format: 'pretty' | 'json',
+): string {
+  if (format === 'json') {
+    const obj = { name, dir, task: taskName, config: task }
+    return `${JSON.stringify(JSON.parse(JSON.stringify(obj)), null, 2)}\n`
+  }
+  return `${name} — ${dir}\n\n${taskBlock(taskName, task)}`
+}
+
+function taskBlock(taskName: string, task: TaskConfig): string {
+  const rows: [string, string][] = []
+  if (task.description !== undefined) rows.push(['description', task.description])
+  rows.push(['command', task.exec?.command ?? '(group)'])
+  if (task.dependsOn !== undefined) rows.push(['dependsOn', task.dependsOn.join(', ')])
+  if (task.cache !== undefined) {
+    rows.push(['inputs.files', task.cache.inputs.files.join(', ')])
+    if (task.cache.inputs.env !== undefined) {
+      rows.push(['inputs.env', task.cache.inputs.env.join(', ')])
+    }
+    if (task.cache.inputs.tasks !== undefined) {
+      rows.push(['inputs.tasks', task.cache.inputs.tasks.join(', ')])
+    }
+    rows.push(['outputs.files', task.cache.outputs.files.join(', ')])
+  }
+  if (task.exec?.timeout !== undefined) rows.push(['timeout', `${task.exec.timeout}ms`])
+  const persistent = task.exec?.persistent
+  if (persistent !== undefined) {
+    const fields: string[] = []
+    if (persistent.readyWhen !== undefined) fields.push(`readyWhen: ${persistent.readyWhen}`)
+    rows.push(['persistent', fields.length > 0 ? fields.join(', ') : 'yes'])
+  }
+  const labelW = Math.max(...rows.map(([label]) => label.length))
+  const body = rows.map(([label, value]) => `  ${`${label}:`.padEnd(labelW + 1)} ${value}`)
+  return `${taskName}\n${body.join('\n')}\n`
+}

package/src/cli/upgrade.ts

@@ -0,0 +1,103 @@
+// `vx upgrade [tag]` — self-update the compiled binary in place.
+// Mirrors install.sh: download the release asset for this os/arch,
+// write next to the current executable, atomic rename over it.
+// Named `upgrade` (not `update`) per CLI convention: bun upgrade,
+// deno upgrade — "update" is what package managers do to indexes.
+
+import { chmod, rename, rm } from 'node:fs/promises'
+import { UserError } from '../util/index.js'
+import { VERSION } from '../version.js'
+
+const REPO = 'vznjs/vx'
+
+/**
+ * A Bun standalone-binary path lives under the bunfs virtual root.
+ * Marker differs by platform / Bun version: `/$bunfs/...` (posix) and
+ * `B:\~BUN\...` or `B:/~BUN/...` (windows).
+ */
+export function isBunfsPath(p: string): boolean {
+  return p.startsWith('/$bunfs') || p.startsWith('B:\\~BUN') || p.startsWith('B:/~BUN')
+}
+
+/**
+ * True when running as a `bun build --compile` binary. Keys off
+ * `Bun.main` (and argv[1]) rather than `import.meta.path`: with
+ * `--minify --bytecode` — vx's release build flags — `import.meta.path`
+ * reports the ORIGINAL SOURCE path, not the bunfs path, so the old
+ * check silently failed for every curl-installed binary and `vx
+ * upgrade` refused with "running from source". `Bun.main` stays the
+ * bunfs path under every compile-flag combination.
+ */
+function isCompiledBinary(): boolean {
+  return (
+    isBunfsPath(Bun.main) || isBunfsPath(process.argv[1] ?? '') || isBunfsPath(import.meta.path)
+  )
+}
+
+function assetName(): string {
+  const os = process.platform === 'darwin' ? 'darwin' : process.platform
+  const arch = process.arch === 'x64' || process.arch === 'arm64' ? process.arch : null
+  if ((os !== 'darwin' && os !== 'linux') || arch === null) {
+    throw new UserError(`vx upgrade: unsupported platform ${process.platform}/${process.arch}`)
+  }
+  return `vx-${os}-${arch}`
+}
+
+/**
+ * Download `url` and atomically replace `dest` with it. Exported for
+ * tests (which point `url` at a local server and `dest` at a tmp
+ * file); the CLI wires it to the GitHub release asset and
+ * process.execPath.
+ */
+export async function replaceBinary(dest: string, url: string): Promise<void> {
+  const res = await fetch(url, { redirect: 'follow' })
+  if (!res.ok) {
+    throw new UserError(`vx upgrade: download failed (${res.status}) — ${url}`)
+  }
+  const bytes = new Uint8Array(await res.arrayBuffer())
+  if (bytes.byteLength === 0) {
+    throw new UserError(`vx upgrade: empty download — ${url}`)
+  }
+  const tmp = `${dest}.upgrade-${process.pid}`
+  try {
+    await Bun.write(tmp, bytes)
+    await chmod(tmp, 0o755)
+    await rename(tmp, dest)
+  } catch (err) {
+    await rm(tmp, { force: true })
+    const msg = err instanceof Error ? err.message : String(err)
+    throw new UserError(
+      `vx upgrade: could not replace ${dest} (${msg}) — ` +
+        `check permissions, or reinstall via install.sh with VX_INSTALL_DIR set`,
+    )
+  }
+}
+
+export async function upgradeCmd(args: readonly string[]): Promise<number> {
+  const tag = args.find((a) => !a.startsWith('-'))
+  const unknown = args.find((a) => a.startsWith('-'))
+  if (unknown !== undefined) {
+    process.stderr.write(`vx upgrade: unknown flag: ${unknown}\n`)
+    return 1
+  }
+  if (!isCompiledBinary()) {
+    throw new UserError(
+      'vx upgrade only works for the compiled binary (install.sh). ' +
+        'You are running from source — use git pull instead.',
+    )
+  }
+  const asset = assetName()
+  const url =
+    tag === undefined
+      ? `https://github.com/${REPO}/releases/latest/download/${asset}`
+      : `https://github.com/${REPO}/releases/download/${tag}/${asset}`
+  const dest = process.execPath
+  process.stdout.write(`vx upgrade: ${VERSION} → ${tag ?? 'latest'} (${dest})\n`)
+  await replaceBinary(dest, url)
+  // Report the replaced binary's own version — the new build speaks
+  // for itself rather than this process guessing.
+  const proc = Bun.spawnSync({ cmd: [dest, '--version'], stdout: 'pipe', stderr: 'pipe' })
+  const v = new TextDecoder().decode(proc.stdout).trim()
+  process.stdout.write(`vx upgrade: installed ${v || '(version check failed)'}\n`)
+  return 0
+}

package/src/cli/watch.ts

@@ -0,0 +1,287 @@
+// `vx watch <task>` — re-run on file changes.
+//
+// Initial run uses the same orchestrator path as `vx run`. After it
+// finishes, set up recursive filesystem watchers on every project's
+// directory in the resolved scope. Filesystem changes trigger a
+// debounced re-invocation of the orchestrator with the same options.
+//
+// The cache does the heavy lifting: re-runs are typically cache hits
+// (input hash matches), so spurious events from edits outside any
+// task's `cache.inputs.files` cost ~tens of ms of orchestrator
+// overhead. We deliberately don't try to filter events through the
+// per-task input globs — the cache key is the source of truth, and
+// filtering would mean re-doing the glob/boundary work on every event.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { parseRunArgs, resolveRunOptions } from './run.js'
+import { run as runOrchestrator, type RunOptions } from '../orchestrator/index.js'
+import {
+  findWorkspaceRoot,
+  listProjects,
+  loadProjectConfig,
+  loadWorkspace,
+  type ProjectMeta,
+} from '../workspace/index.js'
+
+/** Wait this long after the last filesystem event before re-running. */
+const DEBOUNCE_MS = 150
+
+/** Paths whose changes never trigger a re-run. */
+const IGNORED_SEGMENTS = ['node_modules', '.git', '.vx']
+const IGNORED_SUFFIXES = ['.tsbuildinfo', '~']
+
+export async function watchCmd(args: readonly string[]): Promise<number> {
+  const parsed = parseRunArgs(args)
+  if (parsed.error) {
+    process.stderr.write(`vx watch: ${parsed.error}\n`)
+    return 1
+  }
+
+  if (parsed.dry !== undefined || parsed.graph !== undefined) {
+    process.stderr.write(`vx watch: --dry / --graph are not supported in watch mode\n`)
+    return 1
+  }
+  if (parsed.summarize !== undefined || parsed.profile !== undefined) {
+    process.stderr.write(
+      `vx watch: --summarize / --profile are not supported in watch mode (would overwrite per cycle)\n`,
+    )
+    return 1
+  }
+  if (parsed.tasks.length === 0) {
+    process.stderr.write(`vx watch: missing task name\n`)
+    return 1
+  }
+
+  const cwd = process.cwd()
+  const resolved = await resolveRunOptions(parsed, cwd, parsed.tasks)
+  if ('error' in resolved) {
+    process.stderr.write(`vx watch: ${resolved.error}\n`)
+    return 1
+  }
+  // The watch loop owns SIGINT/SIGTERM for its whole lifetime (the
+  // process.once handlers below close watchers and resolve 0). A
+  // cycle's run() must not install its exit-the-process handlers —
+  // Ctrl-C mid-cycle would kill the loop with 130 instead of the
+  // loop's own clean shutdown.
+  const opts: RunOptions = { ...resolved, handleSignals: false }
+
+  // Enumerate projects-in-scope so we know what dirs to watch.
+  // `opts.projects` is the resolved scope; undefined means "every
+  // project". We watch only those (plus the workspace root, for
+  // lockfile changes).
+  const workspaceRoot = await findWorkspaceRoot(cwd)
+  const allProjects = await listProjects(await loadWorkspace(workspaceRoot))
+  const scope =
+    opts.projects === undefined
+      ? allProjects
+      : allProjects.filter((p) => opts.projects!.includes(p.name))
+
+  if (scope.length === 0) {
+    process.stderr.write(`vx watch: no projects in scope\n`)
+    return 1
+  }
+
+  // Initial run — same code path as `vx run`.
+  process.stdout.write('vx watch: initial run...\n\n')
+  await runOrchestrator(opts)
+
+  return await runWatchLoop({
+    opts,
+    workspaceRoot,
+    projects: scope,
+    workspaceWide: await anyTaskUsesWorkspaceFiles(allProjects),
+  })
+}
+
+/**
+ * `inputs.workspaceFiles` globs have no project boundary — any file in
+ * the workspace can be an input. When any config declares them, the
+ * per-project watchers can't see all triggering paths, so the loop
+ * switches to one recursive root watcher. Checked across ALL projects
+ * (not just the scope) because dependsOn can pull tasks from anywhere;
+ * a broken out-of-scope config is skipped, matching scoped-run
+ * semantics (it surfaces when that project enters scope).
+ */
+async function anyTaskUsesWorkspaceFiles(projects: readonly ProjectMeta[]): Promise<boolean> {
+  for (const p of projects) {
+    if (p.configPath === null) continue
+    try {
+      const config = await loadProjectConfig(p.configPath)
+      for (const task of Object.values(config.tasks ?? {})) {
+        if ((task.cache?.inputs?.workspaceFiles?.length ?? 0) > 0) return true
+      }
+    } catch {
+      // broken config — out of this concern's scope
+    }
+  }
+  return false
+}
+
+interface WatchLoopArgs {
+  opts: RunOptions
+  workspaceRoot: string
+  projects: readonly ProjectMeta[]
+  workspaceWide: boolean
+}
+
+async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
+  const { opts, workspaceRoot, projects, workspaceWide } = args
+
+  // Reentrancy guard — never two orchestrator runs in flight. While
+  // one is running, any further events set `pending = true` and the
+  // loop drains it after the current run finishes.
+  let running = false
+  let pending = false
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null
+
+  const trigger = (label: string): void => {
+    if (debounceTimer) clearTimeout(debounceTimer)
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null
+      void cycle(label)
+    }, DEBOUNCE_MS)
+  }
+
+  const cycle = async (label: string): Promise<void> => {
+    if (running) {
+      pending = true
+      return
+    }
+    running = true
+    try {
+      do {
+        pending = false
+        process.stdout.write(`\nvx watch: ${label}; re-running...\n\n`)
+        try {
+          await runOrchestrator(opts)
+        } catch (err) {
+          // A re-run can fail catastrophically when the workspace
+          // itself moved out from under us — e.g. the user deleted
+          // the project dir, or git lost its repo (the watch loop
+          // outlives its own cwd in test teardown). Surface the
+          // message but DON'T let it crash the watch loop; the next
+          // FS event (if any) will retry. The dispose() on SIGINT
+          // is the canonical exit; we don't unilaterally abort here.
+          const message = err instanceof Error ? err.message : String(err)
+          process.stderr.write(`vx watch: cycle failed: ${message}\n`)
+        }
+        // If a change arrived mid-run, loop again immediately.
+      } while (pending)
+    } finally {
+      running = false
+    }
+  }
+
+  // Filter out events for paths we don't care about. We watch each
+  // project's dir recursively, so a `node_modules` write under a
+  // project would otherwise trigger every save during `bun install`.
+  const isIgnoredPath = (rel: string): boolean => {
+    const segments = rel.split(path.sep)
+    if (segments.some((s) => IGNORED_SEGMENTS.includes(s))) return true
+    if (IGNORED_SUFFIXES.some((suf) => rel.endsWith(suf))) return true
+    return false
+  }
+
+  const watchers: fs.FSWatcher[] = []
+
+  if (workspaceWide) {
+    // workspaceFiles inputs in play: any file in the workspace can be
+    // an input, so one recursive root watcher replaces the per-project
+    // ones (it also covers lockfile / pnpm-workspace.yaml edits). The
+    // ignore filter keeps node_modules / .git / .vx churn out; edits
+    // outside any task's inputs still cost only a cache-hit cycle.
+    try {
+      const w = fs.watch(
+        workspaceRoot,
+        { recursive: true, persistent: true },
+        (_event, filename) => {
+          if (filename == null || typeof filename !== 'string') return
+          if (isIgnoredPath(filename)) return
+          trigger(`root ${filename}`)
+        },
+      )
+      watchers.push(w)
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      process.stderr.write(`vx watch: cannot watch workspace root: ${msg}\n`)
+    }
+  } else {
+    // One recursive watcher per project. Each project owns its own
+    // subtree; we don't watch the workspace root recursively (would
+    // cover every project + node_modules + caches).
+    for (const proj of projects) {
+      try {
+        const w = fs.watch(proj.dir, { recursive: true, persistent: true }, (_event, filename) => {
+          if (filename == null) return
+          if (typeof filename !== 'string') return
+          if (isIgnoredPath(filename)) return
+          trigger(`${proj.name} ${filename}`)
+        })
+        watchers.push(w)
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err)
+        process.stderr.write(`vx watch: cannot watch ${proj.dir}: ${msg}\n`)
+      }
+    }
+
+    // Plus the workspace root itself (non-recursive) so lockfile +
+    // pnpm-workspace.yaml edits trigger re-runs even when no project
+    // dir saw the change.
+    try {
+      const w = fs.watch(
+        workspaceRoot,
+        { recursive: false, persistent: true },
+        (_event, filename) => {
+          if (filename == null || typeof filename !== 'string') return
+          if (isWorkspaceFingerprintFile(filename)) trigger(`root ${filename}`)
+        },
+      )
+      watchers.push(w)
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      process.stderr.write(`vx watch: cannot watch workspace root: ${msg}\n`)
+    }
+  }
+
+  // The orchestrator's writes into `.vx/cache/` don't trigger
+  // re-runs because IGNORED_SEGMENTS includes `.vx`. Users who
+  // relocate the cache dir outside `.vx/` need their own filtering.
+
+  process.stdout.write(
+    workspaceWide
+      ? `\nvx watch: watching the workspace root (workspaceFiles inputs in use); press Ctrl+C to stop\n`
+      : `\nvx watch: watching ${projects.length} project(s); press Ctrl+C to stop\n`,
+  )
+
+  return await new Promise<number>((resolve) => {
+    const cleanup = (): void => {
+      for (const w of watchers) {
+        try {
+          w.close()
+        } catch {
+          // ignore
+        }
+      }
+      if (debounceTimer) clearTimeout(debounceTimer)
+      resolve(0)
+    }
+    process.once('SIGINT', () => {
+      process.stdout.write('\nvx watch: stopped\n')
+      cleanup()
+    })
+    process.once('SIGTERM', cleanup)
+  })
+}
+
+function isWorkspaceFingerprintFile(name: string): boolean {
+  return (
+    name === 'pnpm-lock.yaml' ||
+    name === 'package-lock.json' ||
+    name === 'npm-shrinkwrap.json' ||
+    name === 'yarn.lock' ||
+    name === 'bun.lock' ||
+    name === 'bun.lockb' ||
+    name === 'pnpm-workspace.yaml'
+  )
+}