@vzn/vx 0.0.203 → 0.0.205

package/README.md

@@ -216,7 +216,7 @@ every commit. The schema may still change; what 1.0 will promise is in
 | Surface                                            | Maturity             |
 | -------------------------------------------------- | -------------------- |
 | Core task runner + caching                         | **production-ready** |
-| Plugin pipeline (13 hooks, `commands` included)    | **shippable**        |
+| Plugin pipeline (14 hooks, `commands` included)    | **shippable**        |
 | `vx init` / `@vzn/vx-migrate` (scripts; Turbo, Nx) | **shippable**        |
 | First-party plugins (table above)                  | **shippable**        |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.203",
+  "version": "0.0.205",
   "description": "A fast, correct task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -17,10 +17,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.203",
-    "@vzn/vx-linux-arm64": "0.0.203",
-    "@vzn/vx-darwin-x64": "0.0.203",
-    "@vzn/vx-darwin-arm64": "0.0.203"
+    "@vzn/vx-linux-x64": "0.0.205",
+    "@vzn/vx-linux-arm64": "0.0.205",
+    "@vzn/vx-darwin-x64": "0.0.205",
+    "@vzn/vx-darwin-arm64": "0.0.205"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cli/select.ts

@@ -15,7 +15,6 @@ import {
   type LoadReads,
   type FingerprintClaims,
   FROZEN_WITHOUT_LOCK,
-  listProjects,
   loadProjectConfig,
   loadWorkspace,
   parseFilter,
@@ -28,7 +27,12 @@ import type { ProjectEntry } from '../workspace/index.js'
 import { parseDependencySpec } from '../graph/index.js'
 import { nearest, UserError } from '../util/index.js'
 import { claimedAffected, fingerprintClaims } from '../orchestrator/index.js'
-import { type CliLoadOptions, loadCliProjects, loadCliWorkspace } from './workspace-config.js'
+import {
+  type CliLoadOptions,
+  discoverCliProjects,
+  loadCliProjects,
+  loadCliWorkspace,
+} from './workspace-config.js'
 
 /**
  * The projects whose tasks declare a `cache.inputs.workspaceFiles` glob
@@ -110,7 +114,7 @@ async function workspaceFingerprintClaims(
 async function loadWorkspaceProjects(cwd: string): Promise<ProjectMeta[]> {
   const reads: LoadReads = new Map()
   const root = await findWorkspaceRoot(cwd, reads)
-  return await listProjects(await loadWorkspace(root, reads))
+  return await discoverCliProjects(await loadWorkspace(root, reads))
 }
 
 export async function findCwdProject(cwd: string): Promise<string | null> {

package/src/cli/show.ts

@@ -10,11 +10,10 @@ import type { ProjectConfig, TaskConfig } from '../config.js'
 import { declaredTask } from '../graph/index.js'
 import { flagHint, seeHelp } from './help.js'
 import { nearMatches, relPosix, secretMask, UserError } from '../util/index.js'
-import { loadCliProjects } from './workspace-config.js'
+import { discoverCliProjects, loadCliProjects } from './workspace-config.js'
 import {
   findWorkspaceRoot,
   type LoadReads,
-  listProjects,
   loadWorkspace,
   type ProjectEntry,
   type ProjectMeta,
@@ -60,7 +59,7 @@ export async function showCmd(args: readonly string[]): Promise<number> {
   }
   const reads: LoadReads = new Map()
   const root = await findWorkspaceRoot(process.cwd(), reads)
-  const metas = await listProjects(await loadWorkspace(root, reads))
+  const metas = await discoverCliProjects(await loadWorkspace(root, reads))
   const byName = new Map(metas.map((m) => [m.name, m]))
 
   const hashAt = parsed.target?.indexOf('#') ?? -1

package/src/cli/task-verb.ts

@@ -5,9 +5,9 @@
 // name would change meaning the day a plugin declares that verb.
 
 import { nxProjectTarget } from '../orchestrator/index.js'
-import { findWorkspaceRoot, listProjects, loadWorkspace } from '../workspace/index.js'
+import { findWorkspaceRoot, loadWorkspace } from '../workspace/index.js'
 import { findCwdProject } from './select.js'
-import { loadCliProjects } from './workspace-config.js'
+import { discoverCliProjects, loadCliProjects } from './workspace-config.js'
 
 /** The `vx run` a task typed as a verb means, or null when no project declares it. */
 export async function taskVerbHint(
@@ -64,9 +64,14 @@ async function workspaceProjects(
 ): Promise<Awaited<ReturnType<typeof loadCliProjects>> | null> {
   try {
     const root = await findWorkspaceRoot(cwd)
-    return await loadCliProjects(root, await listProjects(await loadWorkspace(root)), 'all', {
-      noCreate: true,
-    })
+    return await loadCliProjects(
+      root,
+      await discoverCliProjects(await loadWorkspace(root)),
+      'all',
+      {
+        noCreate: true,
+      },
+    )
   } catch {
     // No workspace, or a config that does not load: the caller's plain line stands.
     return null

package/src/cli/watch.ts

@@ -26,13 +26,12 @@ import {
 import {
   findWorkspaceRoot,
   type LoadReads,
-  listProjects,
   loadWorkspace,
   LOCKFILE_NAME,
   memberBaseDirs,
   type ProjectMeta,
 } from '../workspace/index.js'
-import { type CliLoadOptions, loadCliWorkspace } from './workspace-config.js'
+import { type CliLoadOptions, discoverCliProjects, loadCliWorkspace } from './workspace-config.js'
 import {
   isIgnoredWatchPath,
   isWorkspaceConfigFile,
@@ -148,7 +147,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   const reads: LoadReads = new Map()
   const workspaceRoot = await findWorkspaceRoot(cwd, reads)
   const workspace = await loadWorkspace(workspaceRoot, reads)
-  const allProjects = await listProjects(workspace)
+  const allProjects = await discoverCliProjects(workspace)
   const inScope = (all: readonly ProjectMeta[]): ProjectMeta[] =>
     opts.projects === undefined ? [...all] : all.filter((p) => opts.projects!.includes(p.name))
   const scope = inScope(allProjects)
@@ -226,7 +225,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
     // dependency of it.
     rediscover: async () => {
       const workspace = await loadWorkspace(workspaceRoot)
-      const all = await listProjects(workspace)
+      const all = await discoverCliProjects(workspace)
       const sweep = await sweepConfigs(all, workspaceRoot, load, opts.tasks)
       const now = await watchedProjects(workspaceRoot, all, inScope(all), load, sweep.staged)
       return {

package/src/cli/workspace-config.ts

@@ -9,12 +9,13 @@ import path from 'node:path'
 import type { WorkspaceConfig } from '../config.js'
 import { UserError } from '../util/index.js'
 import { Cache, noteSchemaReset } from '../cache/index.js'
-import { loadProjects, loadWorkspacePlugins } from '../orchestrator/index.js'
+import { discoverProjects, loadProjects, loadWorkspacePlugins } from '../orchestrator/index.js'
 import type { VxPlugin } from '../orchestrator/index.js'
 import {
   buildPackageGraph,
   computeWorkspaceFingerprint,
   FROZEN_WITHOUT_LOCK,
+  type Workspace,
   type ProjectEntry,
   type ProjectMeta,
   readLockfile,
@@ -36,6 +37,15 @@ export async function loadCliWorkspace(workspaceRoot: string): Promise<CliWorksp
   return { workspaceConfig, plugins, cacheDir: resolveCacheDir(workspaceRoot, workspaceConfig) }
 }
 
+/**
+ * The workspace's projects as a run discovers them: core's, then the
+ * plugin `discover` stage, with the cache dir the run uses.
+ */
+export async function discoverCliProjects(workspace: Workspace): Promise<ProjectMeta[]> {
+  const { plugins, cacheDir } = await loadCliWorkspace(workspace.root)
+  return await discoverProjects(workspace, plugins, cacheDir, warnToStderr)
+}
+
 /**
  * `--cache-dir <path>` / `--cache-dir=<path>` for a verb that reads the
  * cache a run wrote — `why`, `last`, `info`, `cache prune`. Same rules as

package/src/config.ts

@@ -56,6 +56,7 @@ export interface Plugin {
   /** The package name — set by `definePlugin`, never by the plugin. */
   readonly name: string
   config?(workspace: unknown, ctx: unknown): unknown
+  discover?(ctx: unknown): unknown
   project?(config: unknown, ctx: unknown): unknown
   graph?(nodes: unknown, ctx: unknown): unknown
   key?(task: unknown, ctx: unknown): unknown
@@ -80,6 +81,7 @@ export interface Plugin {
  */
 export const PLUGIN_HOOKS = [
   'config',
+  'discover',
   'project',
   'graph',
   'key',

package/src/index.ts

@@ -161,6 +161,8 @@ export type {
   ScheduleHookContext,
   AdmitContext,
   WorkspaceHookContext,
+  DiscoverContext,
+  NamedProject,
   PluginSetupContext,
 } from './orchestrator/index.js'
 // The per-task execution contract a plugin's `executor` capability returns.

package/src/orchestrator/doctor.ts

@@ -24,7 +24,6 @@ import {
   computeWorkspaceFingerprint,
   findWorkspaceRoot,
   type LoadReads,
-  listProjects,
   loadProjectConfig,
   loadWorkspace,
   lockfilePath,
@@ -33,7 +32,7 @@ import {
 } from '../workspace/index.js'
 import { flakyTasks, type FlakyTask } from './failure-mode.js'
 import type { VxPlugin } from './plugin.js'
-import { loadProjects, loadWorkspacePlugins } from './projects.js'
+import { discoverProjects, loadProjects, loadWorkspacePlugins } from './projects.js'
 
 const warnToStderr = (message: string): void => {
   process.stderr.write(`${message}\n`)
@@ -114,12 +113,12 @@ export async function collectInfo(cwd: string, opts: CollectInfoOptions = {}): P
   const warn = opts.warn ?? warnToStderr
   const reads: LoadReads = new Map()
   const root = await findWorkspaceRoot(cwd, reads)
-  const metas = await listProjects(await loadWorkspace(root, reads))
   const { workspaceConfig, plugins } = await loadWorkspacePlugins(root, warn)
   const cacheDir =
     opts.cacheDir === undefined
       ? resolveCacheDir(root, workspaceConfig)
       : path.resolve(cwd, opts.cacheDir)
+  const metas = await discoverProjects(await loadWorkspace(root, reads), plugins, cacheDir, warn)
   const cache = Cache.inspect(cacheDir)
   noteSchemaReset(cache, warn)
   let stats

package/src/orchestrator/index.ts

@@ -4,6 +4,7 @@
 export { run, planRun, nxProjectTarget } from './run.js'
 export { prepareRun, type PreparedRun } from './prepare.js'
 export {
+  discoverProjects,
   loadProjects,
   loadResolvedProjects,
   loadWorkspacePlugins,
@@ -70,6 +71,8 @@ export {
   type ScheduleHookContext,
   type AdmitContext,
   type WorkspaceHookContext,
+  type DiscoverContext,
+  type NamedProject,
   type InstallPluginsArgs,
   type Plugin,
   type PluginContext,

package/src/orchestrator/plugin-host.ts

@@ -14,16 +14,19 @@ import type { ProjectConfig, WorkspaceConfig } from '../config.js'
 import { checkGraph, type TaskNode } from '../graph/index.js'
 import type {
   CacheContext,
+  DiscoverContext,
   ExecutorContext,
   FingerprintChange,
   FingerprintContext,
   GraphHookContext,
   KeyHookContext,
+  NamedProject,
   ProjectHookContext,
   ScheduleHookContext,
   VxPlugin,
   WorkspaceHookContext,
 } from './plugin.js'
+import type { ProjectMeta } from '../workspace/index.js'
 
 /** `a string`, `an array`, `null`, `a number` — for a refusal that names what came back. */
 function describeValue(v: unknown): string {
@@ -97,7 +100,7 @@ async function safe<T>(plugin: VxPlugin, hook: string, fn: () => T | Promise<T>)
 
 export function hasHook(
   plugins: readonly VxPlugin[],
-  hook: 'config' | 'project' | 'graph' | 'key' | 'schedule' | 'admit',
+  hook: 'config' | 'discover' | 'project' | 'graph' | 'key' | 'schedule' | 'admit',
 ): boolean {
   for (const p of plugins) if (p[hook] !== undefined) return true
   return false
@@ -118,6 +121,32 @@ export async function applyConfigHooks(
   }
 }
 
+/**
+ * `discover` stage: each plugin names directories to add to `projects`,
+ * seeing the ones earlier plugins added. `add` turns one name into a meta
+ * (null: already there) or refuses it.
+ */
+export async function applyDiscoverHooks(
+  plugins: readonly VxPlugin[],
+  projects: ProjectMeta[],
+  ctx: Omit<DiscoverContext, 'projects'>,
+  add: (named: NamedProject, plugin: VxPlugin) => Promise<ProjectMeta | null>,
+): Promise<void> {
+  for (const plugin of plugins) {
+    if (plugin.discover === undefined) continue
+    const named = await safe(plugin, 'discover', () => plugin.discover!({ ...ctx, projects }))
+    if (!Array.isArray(named)) {
+      throw new UserError(
+        `plugin '${plugin.name}' failed in discover: expected an array, got ${describeValue(named)}`,
+      )
+    }
+    for (const n of named as readonly NamedProject[]) {
+      const meta = await add(n, plugin)
+      if (meta !== null) projects.push(meta)
+    }
+  }
+}
+
 /** `project` stage: every plugin edits one project's config in place. */
 export async function applyProjectHooks(
   plugins: readonly VxPlugin[],

package/src/orchestrator/plugin.ts

@@ -60,6 +60,17 @@ export interface VxPlugin {
    */
   config?(workspace: WorkspaceConfig, ctx: WorkspaceHookContext): void | Promise<void>
 
+  /**
+   * Directories to make projects beyond the package manager's members, as
+   * `{ dir, name }` (`dir` absolute or relative to the workspace root): a
+   * runner's root tasks, a project no member glob lists. Runs once per
+   * discovery, before any project config loads; each plugin sees core's
+   * projects and the ones earlier plugins named. A named directory keeps
+   * a `package.json` of the same name, if it has one; a name or directory
+   * already taken otherwise, or one outside the root, is refused.
+   */
+  discover?(ctx: DiscoverContext): readonly NamedProject[] | Promise<readonly NamedProject[]>
+
   /**
    * One project's validated config, right after it loaded and before the
    * graph is built. Add, remove or edit tasks. Runs for every loaded project
@@ -243,6 +254,18 @@ export interface WorkspaceHookContext {
   warn(message: string): void
 }
 
+export interface DiscoverContext extends WorkspaceHookContext {
+  /** Where vx's cache lives: a plugin may keep what it read to answer here. */
+  readonly cacheDir: string
+  /** The projects found so far: core's, then earlier plugins'. */
+  readonly projects: readonly ProjectMeta[]
+}
+
+export interface NamedProject {
+  readonly dir: string
+  readonly name: string
+}
+
 export interface ProjectHookContext extends BaseContext {
   /** The package name (`package.json#name`). */
   readonly name: string

package/src/orchestrator/prepare.ts

@@ -29,7 +29,6 @@ import {
   computeWorkspaceFingerprints,
   findWorkspaceRoot,
   type LoadReads,
-  listProjects,
   loadWorkspace,
   FROZEN_WITHOUT_LOCK,
   readLockfile,
@@ -53,7 +52,12 @@ import {
   resolveCache,
   teardownPlugins,
 } from './plugin-host.js'
-import { loadProjects, loadWorkspacePlugins, type LoadedProjects } from './projects.js'
+import {
+  discoverProjects,
+  loadProjects,
+  loadWorkspacePlugins,
+  type LoadedProjects,
+} from './projects.js'
 import { keyExcludedDependencies } from './excluded-keys.js'
 import { FingerprintWatch } from './fingerprint-watch.js'
 import type { VxPlugin } from './plugin.js'
@@ -184,10 +188,15 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     log.status(m),
   )
   mark('workspace config')
+  // `--cache-dir <path>` (RunOptions.cacheDir) overrides the workspace
+  // `cacheDir` field + the `.vx/cache` default; resolved relative to cwd.
+  const cacheDir = options.cacheDir
+    ? path.resolve(options.cwd, options.cacheDir)
+    : resolveCacheDir(workspaceRoot, workspaceConfig)
   const projectMetas =
     options.discovered?.root === workspaceRoot
       ? options.discovered.projects
-      : await listProjects(workspace)
+      : await discoverProjects(workspace, plugins, cacheDir, (m) => log.status(m))
   mark('discover projects')
 
   // SCOPED config loading: configs are programs, and evaluating 1090
@@ -220,13 +229,8 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   mark('package graph')
 
   // The local cache opens BEFORE the configs load: it is also where their
-  // cached evaluations live. `--cache-dir <path>` (RunOptions.cacheDir)
-  // overrides the workspace `cacheDir` field + the `.vx/cache` default;
-  // resolved relative to cwd.
+  // cached evaluations live.
   const policy: CachePolicy = options.cache ?? FULL_CACHE_POLICY
-  const cacheDir = options.cacheDir
-    ? path.resolve(options.cwd, options.cacheDir)
-    : resolveCacheDir(workspaceRoot, workspaceConfig)
   const localCache = new Cache(
     cacheDir,
     { read: policy.localRead, write: policy.localWrite },

package/src/orchestrator/projects.ts

@@ -15,6 +15,7 @@ import {
   type PackageGraph,
   type ProjectEntry,
   type ProjectMeta,
+  type Workspace,
 } from '../workspace/index.js'
 import type { WorkspaceConfig } from '../config.js'
 import { Cache } from '../cache/index.js'
@@ -25,11 +26,12 @@ import {
   listProjects,
   loadWorkspace,
   loadWorkspaceConfig,
+  namedProject,
   resolveCacheDir,
   validateWorkspace,
 } from '../workspace/index.js'
 import { parseDependencySpec } from '../graph/index.js'
-import { applyConfigHooks, applyProjectHooks, hasHook } from './plugin-host.js'
+import { applyConfigHooks, applyDiscoverHooks, applyProjectHooks, hasHook } from './plugin-host.js'
 import type { VxPlugin } from './plugin.js'
 
 /**
@@ -54,6 +56,27 @@ export async function loadWorkspacePlugins(
   return { workspaceConfig, plugins }
 }
 
+/**
+ * The workspace's projects: core's discovery, then the plugin `discover`
+ * stage. With no plugin declaring it, `listProjects` alone.
+ */
+export async function discoverProjects(
+  workspace: Workspace,
+  plugins: readonly VxPlugin[],
+  cacheDir: string,
+  warn: (message: string) => void,
+): Promise<ProjectMeta[]> {
+  const projects = await listProjects(workspace)
+  if (!hasHook(plugins, 'discover')) return projects
+  await applyDiscoverHooks(
+    plugins,
+    projects,
+    { workspaceRoot: workspace.root, cacheDir, warn },
+    (named, plugin) => namedProject(workspace, projects, named, plugin.name),
+  )
+  return projects.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+}
+
 export interface LoadProjectsArgs {
   workspaceRoot: string
   cacheDir: string
@@ -249,9 +272,14 @@ export async function loadResolvedProjects(
 ): Promise<Map<string, ProjectEntry>> {
   const warn = opts.warn ?? ((): void => {})
   const reads: LoadReads = new Map()
-  const metas = await listProjects(await loadWorkspace(workspaceRoot, reads))
   const { workspaceConfig, plugins } = await loadWorkspacePlugins(workspaceRoot, warn)
   const cacheDir = resolveCacheDir(workspaceRoot, workspaceConfig)
+  const metas = await discoverProjects(
+    await loadWorkspace(workspaceRoot, reads),
+    plugins,
+    cacheDir,
+    warn,
+  )
   // Opened as `vx last` opens it: a reader makes no index where there is
   // none and never resets an earlier schema's (C-5). One it cannot read
   // serves nothing; the configs evaluate live.

package/src/workspace/index.ts

@@ -46,6 +46,7 @@ export {
 export {
   findWorkspaceRoot,
   listProjects,
+  namedProject,
   loadWorkspace,
   unreachedHint,
   unreachedPackages,
@@ -54,6 +55,7 @@ export {
   resolveCacheDir,
   type ProjectEntry,
   type ProjectMeta,
+  type Workspace,
 } from './workspace.js'
 export type { LoadReads } from './load-reads.js'
 // The migration seam (see migration.ts) and core's own mapper, the scripts one.

package/src/workspace/workspace.ts

@@ -596,3 +596,63 @@ export async function listProjects(workspace: Workspace): Promise<ProjectMeta[]>
   // all any consumer needs.
   return projects.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
 }
+
+/**
+ * A directory a plugin's `discover` hook names, as a project meta; null
+ * when `known` already holds it under that name. `by` names the plugin in
+ * a refusal. A directory without a `package.json` is a project by the
+ * plugin's name alone.
+ */
+export async function namedProject(
+  workspace: Workspace,
+  known: readonly ProjectMeta[],
+  named: { readonly dir: string; readonly name: string },
+  by: string,
+): Promise<ProjectMeta | null> {
+  const where = `plugin '${by}' named project`
+  if (typeof named?.name !== 'string' || named.name === '' || typeof named.dir !== 'string') {
+    throw new UserError(`${where} ${JSON.stringify(named)}: expected { dir: string, name: string }`)
+  }
+  const dir = path.resolve(workspace.root, named.dir)
+  const rel = relPosix(workspace.root, dir)
+  if (rel === '..' || rel.startsWith('../') || path.isAbsolute(rel)) {
+    throw new UserError(`${where} "${named.name}" at ${dir}: outside the workspace root`)
+  }
+  const shown = rel === '' ? '.' : rel
+  for (const p of known) {
+    if (p.dir === dir && p.name === named.name) return null
+    if (p.dir === dir) {
+      throw new UserError(`${where} "${named.name}" at ${shown}: already the project "${p.name}"`)
+    }
+    if (p.name === named.name) {
+      throw new UserError(
+        `${where} "${named.name}" at ${shown}: the name is taken by ${relPosix(workspace.root, p.dir) || '.'}`,
+      )
+    }
+  }
+  const pkgJsonPath = dir + path.sep + 'package.json'
+  const [configPath, text] = await Promise.all([
+    findConfigFile(dir),
+    Bun.file(pkgJsonPath)
+      .text()
+      .catch((err: unknown) => absent(err, null)),
+  ])
+  if (
+    text === null &&
+    !(await stat(dir).then(
+      (st) => st.isDirectory(),
+      () => false,
+    ))
+  ) {
+    throw new UserError(`${where} "${named.name}" at ${shown}: no such directory`)
+  }
+  const parsed: Partial<PackageJson> = text === null ? {} : parsePackageJson(text, pkgJsonPath)
+  // A nameless manifest names nothing to disagree with (Nx's own projects).
+  const pkg: PackageJson = { ...parsed, name: parsed.name ?? named.name }
+  if (pkg.name !== named.name) {
+    throw new UserError(
+      `${where} "${named.name}" at ${shown}: its package.json names it "${pkg.name ?? ''}"`,
+    )
+  }
+  return { name: named.name, dir, packageJson: pkg, configPath }
+}