@vzn/vx 0.0.16 → 0.0.21

package/src/orchestrator/plugin.ts

@@ -1,64 +1,172 @@
-// Plugin API — in-process extensions on top of the run event bus.
+// Plugin API — the ONE `VxPlugin` contract (docs/design/pipeline-2026-09.md).
 //
-// Collapses what `architecture-review-2026-06.md §4.1` calls the
-// in-process subscriber + the WS subscriber into ONE Plugin contract.
-// Users register plugins via defineWorkspace({ plugins }); each plugin
-// receives a PluginContext with the bus + workspace metadata and can
-// install lifecycle hooks. Plugins observe; they do not redirect.
+// Users register plugins via defineWorkspace({ plugins }). Behaviour
+// capabilities (`cache`, `executor`) return objects core calls INTO;
+// observe capabilities (`telemetry`, `setup` on the bus) can only read.
 //
-// Crash isolation: a plugin that throws on setup() is wrapped in a
-// UserError-style failure message naming the plugin (clean abort, no
-// stack), matching the existing 'broken vx.config.ts' error style. A
-// plugin that throws inside a hook is logged + the plugin is disabled
-// for the remainder of the run (mirrors the deleted Observer's
-// makeSafeObserver pattern; surfaces are isolated from execution).
-//
-// Hook return values: today every hook is fire-and-forget (the bus IS
-// the message pipe; hooks just give users an ergonomic place to read
-// it). One write-capable hook is reserved for a future iteration —
-// onCacheLookup returning { skip: true } — but not in v1.
+// Crash isolation: a plugin that throws in a load-bearing hook aborts the
+// run with a clean UserError naming plugin + hook. A plugin that throws
+// inside a bus hook is logged and disabled for the remainder of the run.
 
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 import type { Cache, CacheLayer, CachePolicy } from '../cache/index.js'
+import { PLUGIN_PACKAGE, type ProjectConfig, type WorkspaceConfig } from '../config.js'
+import type { TaskExecutor } from '../exec/index.js'
 import type { TaskNode, TaskOutcome } from '../graph/index.js'
 import { UserError } from '../util/index.js'
-import type { EventBus, RunStartInfo, WireEvent } from './events.js'
-import type { RunBackend, RunRequest } from './protocol.js'
+import type { ProjectMeta } from '../workspace/index.js'
+import type { EventBus, RunStartInfo } from './events.js'
 import type { TelemetryContext, TelemetrySink } from './telemetry.js'
 
 /**
- * A vx plugin. Contributes any subset of three RUN-LEVEL infrastructure
- * capabilities — where work routes (backend), which cache is used (cache),
- * who observes the run (eventSink). It NEVER changes how a task executes
- * (Architecture principle #3: shell is the API). Registered explicitly in
- * vx.workspace.ts via defineWorkspace({ plugins: [...] }). No auto-discovery.
+ * A vx plugin. Contributes any subset of the run-level capabilities —
+ * where work runs (executor), which cache is used (cache), who
+ * observes the run (telemetry). It never changes WHAT a task is (the
+ * command string — principle #3), only where and how that command is
+ * executed. Registered explicitly in vx.workspace.ts via
+ * defineWorkspace({ plugins: [...] }). No auto-discovery.
  *
  * The old observe-only `Plugin` (`{ name, setup(ctx) }`) is a subset of
  * this shape: a plugin with only `setup` installs and runs exactly as
- * before via `installPlugins`. The new capabilities are consulted by
- * `plugin-host.ts`, each falling back to today's default.
+ * before via `installPlugins`. The capabilities are consulted by
+ * `plugin-host.ts`; core's own executor and cache are plugins too
+ * (src/plugins/), declared by the workspace — there is no fallback
+ * outside the list.
  */
 export interface VxPlugin {
-  /** Stable identifier, convention `'org/name'`. Used in errors + precedence logs. */
+  /**
+   * The name of the package the plugin was defined in — set by
+   * `definePlugin` from the nearest `package.json`, never by the plugin.
+   * Heads every warning about the plugin, every `vx info` line, and the
+   * key material a `key` hook contributes.
+   */
   readonly name: string
 
-  // --- BEHAVIOR capabilities (change WHAT/HOW work runs — opt-in) -----------
+  // --- PIPELINE stages (shape the run before it executes — opt-in) ----------
+  //
+  // Each receives the object core is about to use and edits it IN PLACE;
+  // core re-validates after the last plugin, so a plugin cannot produce what
+  // the loader would refuse from a user. Declaration order is the order.
+  // Whatever a stage changes reaches the cache key by construction: the key
+  // hashes the task config AFTER `project` ran. See
+  // docs/design/pipeline-2026-09.md.
+
+  /**
+   * The workspace config, before anything is derived from it (concurrency,
+   * cacheDir, timeout, …). `plugins` is already fixed by the time this runs.
+   */
+  config?(workspace: WorkspaceConfig, ctx: WorkspaceHookContext): void | Promise<void>
+
+  /**
+   * 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
+   * on every run — a config's cached evaluation is the user's file, and the
+   * hook is applied on top of it live. A package with NO config file is
+   * loaded too, as `{ tasks: {} }`, so a plugin can give tasks to packages
+   * that never wrote one (`ctx.packageJson` carries their scripts); with no
+   * `project` plugin such a package is never visited.
+   */
+  project?(config: ProjectConfig, ctx: ProjectHookContext): void | Promise<void>
+
+  /**
+   * The task graph, after `dependsOn` expansion and before scheduling. Add
+   * or drop edges (`node.deps`), mark tasks requested, adjust resources. A
+   * dep naming a task that is not in the graph, or a cycle, is refused with
+   * the plugin's name.
+   */
+  graph?(nodes: Map<string, TaskNode>, ctx: GraphHookContext): void | Promise<void>
+
+  /**
+   * Extra cache-key material for one task: a `{ name: value }` record that
+   * is folded into the key (and named in `vx why`) — a tool version, a
+   * feature flag, anything the declared inputs cannot see. Runs once per
+   * task per run, before any key is derived. Return undefined to add
+   * nothing. Values must be deterministic for the same inputs or the key
+   * never hits.
+   */
+  key?(
+    task: TaskNode,
+    ctx: KeyHookContext,
+  ):
+    | Readonly<Record<string, string>>
+    | undefined
+    | Promise<Readonly<Record<string, string>> | undefined>
+
+  /**
+   * Workspace-root files this plugin keys on its own, taken OUT of the
+   * workspace fingerprint. Core folds every lockfile it knows into every
+   * task's key, so one `pnpm install` re-keys the whole workspace. A plugin
+   * that reads the lockfile and folds each project's own dependency
+   * closure through `key` claims the file here: core leaves it out of the
+   * fingerprint every key sees (the config-evaluation cache still keys on
+   * it — a config may import a dependency), and `--affected` asks
+   * `affected` which projects a change to it touches instead of selecting
+   * every project. A file has one claimant; a name core does not fold is
+   * refused, since there is nothing to take out.
+   */
+  readonly fingerprint?: FingerprintClaim
+
+  /**
+   * Scheduling priorities: task id → weight, higher runs first among READY
+   * tasks (merged over the structural baseline, which stays the tie-break).
+   * Runs once, after the graph is final. A later plugin's weight for a task
+   * overrides an earlier one's. Return undefined to leave the baseline.
+   */
+  schedule?(
+    nodes: ReadonlyMap<string, TaskNode>,
+    ctx: ScheduleHookContext,
+  ): ReadonlyMap<string, number> | undefined | Promise<ReadonlyMap<string, number> | undefined>
 
   /**
-   * Contribute a run backend. Returns a RunBackend (run(request) → result),
-   * or undefined to decline (core then tries the next plugin, else the
-   * fallback). Consulted ONCE per run, before scheduling. At most one
-   * plugin's backend is used (first non-undefined, in declaration order).
+   * Admission over the worker count: asked for every task about to start
+   * on this machine, with the tasks running here right now. Return `false`
+   * to hold it until something finishes (it is asked again then). Asked
+   * many times per run, so it must be cheap and synchronous; a throw is
+   * reported once and the plugin admits from then on — a policy never
+   * breaks a run. Restore-tier hits and tasks on an executor pool hold no
+   * local resources and are never asked. When several plugins answer, all
+   * must admit. Core keeps no notion of what a task needs: a plugin that
+   * packs memory or CPU learns or declares the numbers itself
+   * (`@vzn/vx-schedule-history` packs what past executions used).
    */
-  backend?(ctx: BackendContext): RunBackend | undefined | Promise<RunBackend | undefined>
+  admit?(task: TaskNode, ctx: AdmitContext): boolean
+
+  // --- CLI verbs (opt-in) ---------------------------------------------------
+
+  /**
+   * Verbs this plugin adds to the `vx` CLI, keyed by name. Consulted only
+   * for a verb core does not know — core's own verbs always win — and only
+   * when the cwd is inside a workspace that declares the plugin. `vx help`
+   * lists them under "Plugin commands". A verb's exit code is the process
+   * exit code; a thrown `UserError` prints cleanly, like core's own.
+   */
+  readonly commands?: Readonly<Record<string, PluginCommand>>
+
+  // --- BEHAVIOR capabilities (change WHAT/HOW work runs — opt-in) -----------
 
   /**
    * Contribute a cache layer. Returns a CacheLayer wrapping (or replacing)
    * the local Cache, or undefined to decline. Consulted ONCE per prepareRun.
-   * Precedence: first non-undefined plugin cache wins; else core's env-var
-   * Turbo-wire LayeredCache; else the bare local Cache.
+   * Precedence: first non-undefined plugin cache wins, in declaration
+   * order, ahead of core's own `.vx/cache` handle at the tail. A layer
+   * that WRAPS the local handle subsumes that tail, so it is not written
+   * twice.
    */
   cache?(ctx: CacheContext): CacheLayer | undefined | Promise<CacheLayer | undefined>
 
+  /**
+   * Contribute a task executor — WHERE one task's command runs. Consulted
+   * ONCE per run; every contributed executor is kept, in declaration order,
+   * and per task the first whose `accepts()` passes executes it. Nothing is
+   * appended in front: core's own local executor is always the TAIL, so
+   * declining a task hands it back to this machine rather than failing
+   * the run. Persistent tasks never reach an executor (local by
+   * construction).
+   */
+  executor?(ctx: ExecutorContext): TaskExecutor | undefined | Promise<TaskExecutor | undefined>
+
   // --- OBSERVE-ONLY capability (cannot change behavior — by construction) ---
 
   /**
@@ -78,15 +186,6 @@ export interface VxPlugin {
     | undefined
     | Promise<TelemetrySink | TelemetrySink[] | undefined>
 
-  /**
-   * @deprecated Prefer `telemetry`. Contribute an event sink — a consumer of
-   * the serializable WireEvent stream, subscribed for the whole run via
-   * wireForwarder. Fire-and-forget; a throwing sink is isolated and cannot
-   * break the run. Kept as a back-compat path; `telemetry` is the canonical,
-   * analytics-shaped export contract.
-   */
-  eventSink?(ctx: EventSinkContext): EventSink | undefined | Promise<EventSink | undefined>
-
   /**
    * Optional one-time setup before any capability is consulted (validate the
    * workspace, open a connection, read a token). Throwing aborts the run with
@@ -98,12 +197,6 @@ export interface VxPlugin {
   teardown?(): void | Promise<void>
 }
 
-/** A WireEvent consumer. onEvent is fire-and-forget; flush is awaited at teardown. */
-export interface EventSink {
-  onEvent(event: WireEvent): void
-  flush?(): Promise<void>
-}
-
 /** Shared, read-only context every capability factory receives. */
 interface BaseContext {
   readonly workspaceRoot: string
@@ -113,11 +206,89 @@ interface BaseContext {
 }
 
 export interface PluginSetupContext extends BaseContext {}
-export interface EventSinkContext extends BaseContext {}
 
-export interface BackendContext extends BaseContext {
-  /** The resolved RunRequest about to be executed — cwd, tasks, policy, flow. */
-  readonly request: RunRequest
+/** One CLI verb contributed by a plugin. */
+export interface PluginCommand {
+  /** One line for `vx help`. */
+  readonly description: string
+  run(argv: readonly string[], ctx: CommandContext): number | Promise<number>
+}
+
+export interface CommandContext extends BaseContext {}
+
+/** `config` runs before the cache dir is known — it may be what the hook changes. */
+export interface WorkspaceHookContext {
+  readonly workspaceRoot: string
+  warn(message: string): void
+}
+
+export interface ProjectHookContext extends BaseContext {
+  /** The package name (`package.json#name`). */
+  readonly name: string
+  /** The project's directory, absolute. */
+  readonly dir: string
+  /** The parsed `package.json`, read-only. */
+  readonly packageJson: Readonly<Record<string, unknown>>
+  /**
+   * Every package the workspace discovered — the one being visited, the
+   * rest of the run's scope and the packages outside it, config file or
+   * not — as core read them at startup. A plugin whose mapping needs the
+   * whole workspace (a `dependsOn` is only valid against every package's
+   * scripts at once) reads it here instead of walking the workspace a
+   * second time. The same array is handed to every visit of a run and a
+   * new one to the next run — a plugin instance outlives a run under `vx
+   * watch`, so a per-run memo keys on this array's identity, never on the
+   * process.
+   */
+  readonly projects: readonly ProjectMeta[]
+}
+
+export interface GraphHookContext extends BaseContext {
+  /** Task ids the user asked for (the rest were pulled in by `dependsOn`). */
+  readonly requested: readonly string[]
+}
+
+export interface KeyHookContext extends BaseContext {}
+
+/** A plugin's claim on workspace fingerprint files — see `VxPlugin.fingerprint`. */
+export interface FingerprintClaim {
+  /** Root-relative names from `WORKSPACE_FINGERPRINT_FILES`, e.g. `['pnpm-lock.yaml']`. */
+  readonly files: readonly string[]
+  /**
+   * The projects (package names) a change to a claimed file affects. Called
+   * by `--affected` with the file's bytes at the base ref and in the
+   * working tree (`null` where it does not exist). Return `undefined` to
+   * select every project — the answer a claimant gives when it cannot
+   * tell, and what core does for an unclaimed file.
+   */
+  affected(
+    change: FingerprintChange,
+    ctx: FingerprintContext,
+  ): Iterable<string> | undefined | Promise<Iterable<string> | undefined>
+}
+
+export interface FingerprintChange {
+  /** The claimed file's root-relative name. */
+  readonly file: string
+  readonly before: Uint8Array | null
+  readonly after: Uint8Array | null
+}
+
+export interface FingerprintContext extends BaseContext {
+  /** Every project in the workspace: package name and absolute directory. */
+  readonly projects: ReadonlyArray<{ readonly name: string; readonly dir: string }>
+}
+
+export interface AdmitContext {
+  /** The tasks executing on this machine right now, in dispatch order. */
+  readonly running: readonly TaskNode[]
+  /** The run's worker count — the ceiling the count gate already applies. */
+  readonly concurrency: number
+}
+
+export interface ScheduleHookContext extends BaseContext {
+  /** The run's local cache handle — its `dbHandle()` holds the run history a policy can learn from. */
+  readonly localCache: Cache
 }
 
 export interface CacheContext extends BaseContext {
@@ -127,6 +298,11 @@ export interface CacheContext extends BaseContext {
   readonly policy: CachePolicy
 }
 
+export interface ExecutorContext extends BaseContext {
+  /** The run's worker count — an executor that paces itself reads it here. */
+  readonly concurrency: number
+}
+
 export interface PluginContext {
   /** Where the workspace lives on disk. */
   readonly workspaceRoot: string
@@ -170,12 +346,76 @@ export interface Plugin {
    * be installed synchronously inside setup() so no events are missed.
    *
    * OPTIONAL: a capability-only plugin (one that contributes
-   * `backend`/`cache`/`eventSink` but no `setup`) is simply skipped by
+   * `cache`/`executor`/`telemetry` but no `setup`) is simply skipped by
    * `installPlugins` — its capabilities are consulted by `plugin-host.ts`.
    */
   setup?(ctx: PluginContext): void | Promise<void>
 }
 
+/** What a plugin author writes: every hook, and no name. */
+export type PluginHooks = Omit<VxPlugin, 'name'>
+
+/**
+ * Where a plugin is defined — `import.meta` of its module. `dir` is Bun's
+ * field; `url` is the standard one, for a module evaluated elsewhere.
+ */
+export interface PluginOrigin {
+  readonly dir?: string
+  readonly url?: string
+}
+
+const packageNameByDir = new Map<string, string>()
+
+/** The name of the nearest `package.json` above `dir` — the one that owns it. */
+function pluginPackageName(dir: string): string {
+  const memo = packageNameByDir.get(dir)
+  if (memo !== undefined) return memo
+  for (let d = dir; ;) {
+    let text: string | undefined
+    try {
+      text = readFileSync(path.join(d, 'package.json'), 'utf8')
+    } catch {
+      /* not here; look one level up */
+    }
+    if (text !== undefined) {
+      const name = (JSON.parse(text) as { name?: unknown }).name
+      if (typeof name !== 'string' || name.length === 0) {
+        throw new UserError(
+          `definePlugin: ${path.join(d, 'package.json')} has no name — a plugin is a package, and its name is the package's`,
+        )
+      }
+      packageNameByDir.set(dir, name)
+      return name
+    }
+    const parent = path.dirname(d)
+    if (parent === d) {
+      throw new UserError(
+        `definePlugin: no package.json above ${dir} — a plugin is a package, and its name is the package's`,
+      )
+    }
+    d = parent
+  }
+}
+
+/**
+ * The one way to make a plugin: `definePlugin(import.meta, { ...hooks })`.
+ * The name is read from the package the calling module belongs to — the
+ * nearest `package.json` above it — and stamped where the workspace loader
+ * checks for it, so a plugin cannot be named anything but its package.
+ */
+export function definePlugin(origin: PluginOrigin, hooks: PluginHooks): VxPlugin {
+  if ('name' in hooks) {
+    throw new UserError(`definePlugin: a plugin's name is its package name — drop the 'name' field`)
+  }
+  const dir =
+    origin.dir ?? (origin.url !== undefined ? path.dirname(fileURLToPath(origin.url)) : undefined)
+  if (dir === undefined) {
+    throw new UserError(`definePlugin: the first argument must be the plugin module's import.meta`)
+  }
+  const name = pluginPackageName(dir)
+  return { ...hooks, name, [PLUGIN_PACKAGE]: name } as VxPlugin
+}
+
 export interface InstallPluginsArgs {
   plugins: readonly Plugin[]
   workspaceRoot: string
@@ -195,8 +435,8 @@ export interface InstallPluginsArgs {
  * hooks are subscribed before the next plugin's setup runs. Throws if any
  * plugin's setup() throws (the run cannot start with a broken plugin).
  *
- * A plugin without a `setup` is a capability-only plugin (backend / cache
- * / eventSink) — skipped here; those capabilities are consulted by
+ * A plugin without a `setup` is a capability-only plugin (cache
+ * / executor / telemetry) — skipped here; those capabilities are consulted by
  * `plugin-host.ts`.
  */
 export async function installPlugins(args: InstallPluginsArgs): Promise<() => void> {
@@ -209,7 +449,7 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
     if (typeof plugin.name !== 'string' || plugin.name.length === 0) {
       throw new UserError('plugin missing `name` field')
     }
-    // No setup → a capability-only plugin (backend / cache / eventSink),
+    // No setup → a capability-only plugin (cache / executor / telemetry),
     // consulted by plugin-host.ts; skip the hook install. A setup that's
     // present but not callable is a real authoring error — reject it.
     if (plugin.setup === undefined) continue