@vzn/vx 0.0.636 → 0.0.638

package/src/orchestrator/plugin.ts

@@ -11,21 +11,28 @@
 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 {
+  absentPluginCache,
+  type Cache,
+  type PluginCache,
+  type RemoteCacheLayer,
+} 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 type { TaskNode, TaskOutcome, TaskStatus } from '../graph/index.js'
 import { maskedLine, nearest, UserError } from '../util/index.js'
 import type { ProjectMeta } from '../workspace/index.js'
 import type { EventBus, RunStartInfo } from './events.js'
+import type { CiContext } from './run-context.js'
 import type { TelemetryContext, TelemetrySink } from './telemetry.js'
+import type { Logger } from './logger.js'
 
 /**
  * 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
+ * executed. Registered explicitly in .vx/workspace.ts via
  * defineWorkspace({ plugins: [...] }). No auto-discovery.
  *
  * Made by `definePlugin(import.meta, hooks)` only: the loader refuses a
@@ -59,24 +66,32 @@ 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.
+   * Projects beyond the directories holding a vx.config, their names, and
+   * edges between projects, as `DiscoveredProject`s (each directory
+   * absolute or relative to the workspace root): a lockfile's importers,
+   * their package names and the dependencies it records; a runner's root
+   * tasks. Runs once per discovery, before any project config loads; each
+   * plugin sees the locked projects and the ones earlier plugins added,
+   * without their edges. A directory that is not a project becomes one
+   * (with no config; named by `name`, else its path). A project named by
+   * its path takes `name`; one its config names keeps that name, and a
+   * different name from an earlier plugin is refused, as is a directory
+   * outside the root. Two projects of one name are refused once the stage
+   * ends. `deps` and `reach` from every plugin union then; a target that is
+   * no project is refused.
    */
-  discover?(ctx: DiscoverContext): readonly NamedProject[] | Promise<readonly NamedProject[]>
+  discover?(
+    ctx: DiscoverContext,
+  ): readonly DiscoveredProject[] | Promise<readonly DiscoveredProject[]>
 
   /**
    * 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.
+   * on every run — a locked config is the user's file, and the hook is
+   * applied on top of it live. A project with NO config file (a
+   * `discover` plugin added it) is loaded too, as `{ tasks: {} }`, so a
+   * plugin can give it tasks; with no `project` plugin such a project is
+   * never visited.
    */
   project?(config: ProjectConfig, ctx: ProjectHookContext): void | Promise<void>
 
@@ -105,22 +120,14 @@ export interface VxPlugin {
     | 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 root file core does NOT fold is claimed the same way when the
-   * plugin's stages read it: `turbo()` shapes every task from
-   * `turbo.json`, so an edit to it re-keys tasks through their resolved
-   * configs while no project owns the path. Nothing is taken out;
-   * `--affected` asks `affected` (undefined: every project) and `vx watch`
-   * re-runs on an edit (item 961). A claim is a bare name at the root.
+   * Workspace-root files this plugin keys on: core folds no root file into
+   * any key, so a plugin that reads one (a lockfile it folds per project
+   * through `key`, `turbo.json` that shapes every task through its
+   * `project` stage) claims it here. `--affected` asks `affected` which
+   * projects a change to it touches (undefined: every project), `vx watch`
+   * re-runs on an edit (item 961), and a task that rewrites one during the
+   * run withholds every later save. A claim is a bare name at the root; a
+   * file has one claimant.
    */
   readonly fingerprint?: FingerprintClaim
 
@@ -167,14 +174,14 @@ export interface VxPlugin {
   // --- 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.
-   * Every contributed layer is kept and chained in declaration order,
-   * ahead of core's own `.vx/cache` handle at the tail: a lookup walks
-   * them until one hits, a save reaches each. A layer that WRAPS the local
-   * handle subsumes that tail, so it is not written twice.
+   * Contribute a remote cache: the wire (`has`, `get`, `put`, optional
+   * `hasMany`), or undefined to decline. Consulted ONCE per prepareRun.
+   * Core layers each one behind its own local cache and owns the rest:
+   * the local store is asked first, then each remote in declaration order;
+   * the run's policy and scope gate every remote; a remote's throw is a
+   * miss and a warning naming the plugin, never a failed run.
    */
-  cache?(ctx: CacheContext): CacheLayer | undefined | Promise<CacheLayer | undefined>
+  cache?(ctx: CacheContext): RemoteCacheLayer | undefined | Promise<RemoteCacheLayer | undefined>
 
   /**
    * Contribute a task executor — WHERE one task's command runs. Consulted
@@ -206,19 +213,65 @@ export interface VxPlugin {
     | undefined
     | Promise<TelemetrySink | TelemetrySink[] | undefined>
 
+  /**
+   * Take the terminal for this run: return the `Logger` that renders it
+   * (the contract `run({ log })` takes), or `undefined` to leave core's
+   * renderer in place. The first plugin, in declaration order, that
+   * returns one renders the run; the rest are not asked. Not consulted
+   * when an embedder passed its own `log`. A logger that throws hands the
+   * rest of the run back to core's renderer with one warning.
+   */
+  output?(ctx: OutputContext): Logger | undefined | Promise<Logger | undefined>
+
   /**
    * Optional one-time setup per run (validate the workspace, open a
    * connection, read a token). Throwing aborts the run with a clean
    * UserError naming the plugin. It is not a guard over the pipeline: the
-   * config, project, cache, graph, key and schedule stages have run by the
-   * time it is called, and a plan (`--dry`, `planRun`) never calls it. It
-   * precedes the executors, the telemetry sinks, admission and the first
-   * task (tests/plugin-e2e.test.ts).
+   * config, project, cache, graph and key stages have run by the time it
+   * is called, and a plan (`--dry`, `planRun`) never calls it. It
+   * precedes the schedule stage, the executors, the telemetry sinks,
+   * admission and the first task (tests/plugin-e2e.test.ts).
    */
   setup?(ctx: PluginSetupContext): void | Promise<void>
 
-  /** Optional teardown at end-of-run (flush a sink, close a socket). Errors are logged, never thrown. */
-  teardown?(): void | Promise<void>
+  /**
+   * Optional teardown at end-of-run (flush a sink, close a socket). Errors
+   * are logged, never thrown. A run that ran to its end passes its
+   * `RunReport`; every other exit (a refused setup, a stop) passes none.
+   */
+  teardown?(run?: RunReport): void | Promise<void>
+}
+
+/**
+ * What a finished run hands each plugin's `teardown`: its facts and every
+ * task, with the names core kept the task's bytes under. Core keeps them
+ * only when a remote takes the run's writes (CI by default): a failed
+ * task's log and the files its outputs left, an uncached task's log. Read
+ * them with `ctx.cache.getRun(name)`. Core keeps no manifest of its own; a
+ * plugin that wants one writes it from here (`ctx.cache.put`).
+ */
+export interface RunReport {
+  /** The `run_id` the run's history rows and telemetry carry. */
+  readonly runId: string
+  /** `HEAD`'s commit, null outside a git worktree. */
+  readonly commit: string | null
+  /** What the CI provider says about this run: provider, run URL, pipeline, job, attempt. */
+  readonly ciRun: CiContext
+  readonly ok: boolean
+  /** Every task the run decided, in completion order; group tasks are left out. */
+  readonly tasks: readonly RunReportTask[]
+}
+
+export interface RunReportTask {
+  readonly id: string
+  readonly status: TaskStatus
+  readonly durationMs: number
+  /** The task's cache key, when one was computed. */
+  readonly key?: string
+  /** Its output (both streams, secrets masked), when core kept it: `ctx.cache.getRun(log)`. */
+  readonly log?: string
+  /** A tar of the files its declared outputs left, when core kept it: `ctx.cache.getRun(outputs)`. */
+  readonly outputs?: string
 }
 
 /** Shared, read-only context every capability factory receives. */
@@ -231,6 +284,12 @@ interface BaseContext {
 
 /** What `setup` receives: the run's lifecycle, observe-only. */
 export interface PluginSetupContext extends BaseContext {
+  /** This plugin's entries in the workspace's cache (`PluginCache`). */
+  readonly cache: PluginCache
+  /** The run is on CI (`CI` set, or a provider core detects). */
+  readonly ci: boolean
+  /** The run's branch (`currentBranch`): `run.branch`, else git's, else the CI provider's. */
+  readonly branch: string | null
   /**
    * Subscribe a lifecycle handler; it leaves with the run. A throw or a
    * rejection warns once and switches the plugin's handlers off for the run.
@@ -248,7 +307,7 @@ export interface PluginCommand {
 export interface CommandContext extends BaseContext {
   /**
    * The worker count a `vx run` here uses unless `--concurrency` says
-   * otherwise: `vx.workspace`'s `concurrency`, else what the machine allows.
+   * otherwise: `.vx/workspace`'s `concurrency`, else what the machine allows.
    * A verb that budgets a run (`vx history`) reads it here; its own
    * `machineParallelism()` said 4 cores beside `concurrency: 1` (item 1068).
    */
@@ -256,10 +315,16 @@ export interface CommandContext extends BaseContext {
   /**
    * The argv that runs this vx again: the binary alone when compiled, the
    * runtime and its entry script from source. A verb that runs tasks
-   * (`vx mcp`'s `runTasks`) spawns `[...vx, 'run', …]` rather than guess
+   * spawns `[...vx, 'run', …]` rather than guess
    * which `vx` a PATH holds.
    */
   readonly vx: readonly string[]
+  /**
+   * This plugin's entries in the workspace's cache, as `setup` reaches them
+   * (`PluginCache`), read-only: the local store, then each remote the
+   * workspace's cache plugins supply, under the run's scope. Opened on first use.
+   */
+  readonly cache: PluginCache
 }
 
 /** `config` runs before the cache dir is known — it may be what the hook changes. */
@@ -271,7 +336,7 @@ export interface WorkspaceHookContext {
 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'. */
+  /** The projects found so far: the lock's, then earlier plugins'. */
   readonly projects: readonly ProjectMeta[]
   /**
    * What `git status` lists in the workspace, workspace-relative: modified,
@@ -283,30 +348,46 @@ export interface DiscoverContext extends WorkspaceHookContext {
   worktreeChanges(): Promise<readonly string[] | null>
 }
 
-export interface NamedProject {
+/** What a `discover` hook returns per directory — see `VxPlugin.discover`. */
+export interface DiscoveredProject {
+  /** Absolute or relative to the workspace root. */
   readonly dir: string
-  readonly name: string
+  /**
+   * Its name, when its config names none: replaces a path name, never a
+   * config's; a different name from an earlier plugin is refused. Unset on
+   * a new directory: its root-relative path.
+   */
+  readonly name?: string
+  /** Directories this project builds after: `^task` order, and reach for `--filter` and `--affected`. */
+  readonly deps?: readonly string[]
+  /** Directories a change reaches this project through (`--filter`, `--affected`), with no order. */
+  readonly reach?: readonly string[]
 }
 
 export interface ProjectHookContext extends BaseContext {
-  /** The package name (`package.json#name`). */
+  /** The project's name (`ProjectMeta.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
+   * Every project the workspace discovered — the one being visited, the
+   * rest of the run's scope and the projects outside it, config file or
+   * not — as the `discover` stage left them. 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[]
+  /**
+   * True when `vx lock` (or `--check`) visits: the one pass that checks the
+   * configs, so the place to report what a plugin's mapping could not say.
+   * A run checks nothing (the lock model), so such a report there repeats
+   * on every run.
+   */
+  readonly lock: boolean
 }
 
 export interface GraphHookContext extends BaseContext {
@@ -320,16 +401,16 @@ export interface GraphHookContext extends BaseContext {
 
 export interface KeyHookContext extends BaseContext {}
 
-/** A plugin's claim on workspace fingerprint files — see `VxPlugin.fingerprint`. */
+/** A plugin's claim on workspace-root files — see `VxPlugin.fingerprint`. */
 export interface FingerprintClaim {
-  /** Bare names at the workspace root: a lockfile core folds (`pnpm-lock.yaml`) or a file the plugin reads (`turbo.json`). */
+  /** Bare names at the workspace root the plugin reads: a lockfile (`pnpm-lock.yaml`), a settings file, `turbo.json`. */
   readonly files: readonly string[]
   /**
-   * The projects (package names) a change to a claimed file affects. Called
+   * The projects (by name) 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.
+   * tell.
    */
   affected(
     change: FingerprintChange,
@@ -345,7 +426,7 @@ export interface FingerprintChange {
 }
 
 export interface FingerprintContext extends BaseContext {
-  /** Every project in the workspace: package name and absolute directory. */
+  /** Every project in the workspace: name and absolute directory. */
   readonly projects: ReadonlyArray<{ readonly name: string; readonly dir: string }>
 }
 
@@ -364,13 +445,29 @@ export interface AdmitContext {
 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
+  /** The run's branch (`currentBranch`), the timings a forecast reads first: pass it to `LocalHistoryProvider`. */
+  readonly branch: string | null
+  /** This plugin's entries in the workspace's cache, as `setup` has them. */
+  readonly cache: PluginCache
 }
 
+/** A `cache` hook's context: the workspace and the run's scope, never the local store or the policy, which core owns. */
 export interface CacheContext extends BaseContext {
-  /** The local Cache handle the plugin may wrap (LayeredCache(local, remote)). */
-  readonly localCache: Cache
-  /** The run's cache policy (the 4 read/write axes). */
-  readonly policy: CachePolicy
+  /**
+   * The run's `cache.scope` (`'pr-123'`), `undefined` when none. Core already keys a scoped run's
+   * writes apart; a remote reads it to pick a credential or check a token's
+   * claims (an OIDC branch) for every call it makes.
+   */
+  readonly scope: string | undefined
+}
+
+export interface OutputContext extends BaseContext {
+  /** Core would write to a terminal: stdout (stderr under `json`) is a TTY. */
+  readonly isTTY: boolean
+  /** The run is on CI (`CI` set, or a provider core detects). */
+  readonly ci: boolean
+  /** `--format json`: stdout carries the machine-readable result. */
+  readonly json: boolean
 }
 
 export interface ExecutorContext extends BaseContext {
@@ -585,6 +682,12 @@ export interface InstallPluginsArgs {
    * `run:status` channel.
    */
   warn?: (message: string) => void
+  /** Each plugin's `ctx.cache`, by plugin name. Default: a cache with no layer. */
+  cache?: (plugin: string) => PluginCache
+  /** Default false. */
+  ci?: boolean
+  /** Default null. */
+  branch?: string | null
 }
 
 /**
@@ -641,6 +744,9 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
       workspaceRoot,
       cacheDir,
       warn,
+      cache: args.cache?.(plugin.name) ?? absentPluginCache,
+      ci: args.ci ?? false,
+      branch: args.branch ?? null,
       // A subscription made past the hooks leaves with the run like a
       // hook's does: the bus can outlive the run (`RunOptions.bus`), and
       // one left behind hears every later run on it (item 635).