@vzn/vx 0.0.15 → 0.0.18

package/src/orchestrator/plugin.ts

@@ -1,64 +1,131 @@
-// 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 type { Cache, CacheLayer, CachePolicy } from '../cache/index.js'
+import type { ProjectConfig, 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 { 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. */
   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.
+   */
+  project?(config: ProjectConfig, ctx: ProjectHookContext): void | Promise<void>
 
   /**
-   * 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).
+   * 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.
    */
-  backend?(ctx: BackendContext): RunBackend | undefined | Promise<RunBackend | undefined>
+  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>
+
+  /**
+   * 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>
+
+  // --- 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. `@vzn/vx/plugins/local-cache` hands back the bare local Cache;
+   * a list with no provider fails the run before any task starts.
    */
   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: a workspace declares `localExecutorPlugin()` (from
+   * `@vzn/vx/plugins/local-executor`) like any other, and a run with no
+   * executor at all fails before any task runs. 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 +145,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 +156,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 +165,41 @@ 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>>
+}
+
+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 {}
+
+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 +209,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,7 +257,7 @@ 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>
@@ -195,8 +282,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 +296,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