@vzn/vx 0.0.645 → 0.0.648

package/src/orchestrator/plugin.ts

@@ -20,10 +20,20 @@ import {
 import { PLUGIN_PACKAGE, type ProjectConfig, type WorkspaceConfig } from '../config.js'
 import type { TaskExecutor } from '../exec/index.js'
 import type { TaskNode, TaskOutcome, TaskStatus } from '../graph/index.js'
-import { maskedLine, nearest, type PluginSecrets, SecretBroker, UserError } from '../util/index.js'
+import {
+  errorCode,
+  maskedLine,
+  nearest,
+  type PluginSecrets,
+  SecretBroker,
+  thrownMessage,
+  ui,
+  UserError,
+} from '../util/index.js'
 import type { ProjectMeta } from '../workspace/index.js'
 import type { EventBus, Logger, RunStartInfo } from '../report/index.js'
 import type { CiContext } from './run-context.js'
+import type { CacheFacts, TaskArtifacts } from './task-artifacts.js'
 import type { TelemetryContext, TelemetrySink } from './telemetry.js'
 
 /**
@@ -59,7 +69,8 @@ export interface VxPlugin {
 
   /**
    * The workspace config, before anything is derived from it (concurrency,
-   * cacheDir, timeout, …). `plugins` is already fixed by the time this runs.
+   * cacheDir, timeout, …). `plugins` is already fixed by the time this runs:
+   * an edit to it is refused.
    * Core re-validates after each plugin, as it does a user's file.
    * `ctx.setBranch` names what the CI knows of the branch: its cache scope
    * and the commit it is compared with.
@@ -77,7 +88,7 @@ export interface VxPlugin {
    * (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
+   * outside the root and the name `//` away from it. 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.
    */
@@ -92,7 +103,7 @@ export interface VxPlugin {
    * 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.
+   * never visited. Its `name` is fixed by then: a change is refused.
    */
   project?(config: ProjectConfig, ctx: ProjectHookContext): void | Promise<void>
 
@@ -153,13 +164,13 @@ export interface VxPlugin {
    * 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, or
-   * an answer that is a Promise, is reported once and the plugin admits
+   * an answer that is a Promise or not a boolean or undefined, is reported once and the plugin admits
    * from then on — a policy never
    * breaks a run. Restore-tier hits, tasks on an executor pool and groups
    * hold no local resources: never asked, never in `ctx.running`. 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).
+   * (`@vzn/vx-history` packs what past executions used).
    */
   admit?(task: TaskNode, ctx: AdmitContext): boolean
 
@@ -222,8 +233,10 @@ export interface VxPlugin {
    * (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.
+   * when an embedder passed its own `log`. A logger that throws or rejects
+   * hands the rest of the run back to core's renderer with one warning; a
+   * hook that does not answer within the teardown bound (3 s) is passed
+   * over with one.
    */
   output?(ctx: OutputContext): Logger | undefined | Promise<Logger | undefined>
 
@@ -239,8 +252,10 @@ export interface VxPlugin {
   setup?(ctx: PluginSetupContext): 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
+   * Optional teardown at end-of-run (flush a sink, close a socket), in
+   * declaration order, a plugin with `cache` after every other: the
+   * others may still write through its remote. 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>
@@ -334,6 +349,20 @@ export interface CommandContext extends BaseContext {
    * workspace's cache plugins supply, under the run's scope. Opened on first use.
    */
   readonly cache: PluginCache
+  /**
+   * Task entries by key in the workspace's cache, under a run's policy and
+   * scope (a laptop writes no remote unless the workspace's policy names
+   * it): what a verb that runs a run's tasks on this machine saves and
+   * restores through (`TaskArtifacts`). Opened on first use.
+   */
+  readonly artifacts: TaskArtifacts
+  /**
+   * `artifacts` read as another machine's run would read them: under its
+   * refs, with the access its remotes lent (`CacheFacts`, asked on each
+   * request, so a token it lends again replaces the last). Opened on first
+   * use; until `facts` answers, under this machine's own.
+   */
+  artifactsFor(facts: () => CacheFacts | undefined): TaskArtifacts
 }
 
 /** `config` runs before the cache dir is known — it may be what the hook changes. */
@@ -343,17 +372,22 @@ export interface WorkspaceHookContext {
 }
 
 /**
- * What a CI knows of the run's branch (owner, 2026-10-17): `scope`, the
+ * What a CI knows of the run's branch (2026-10-17): `scope`, the
  * cache scope (`'vznjs/vx:feat-x'`; `VX_CACHE_SCOPE` beats it, and it
  * beats the one git names), and `base`, the commit the branch is compared
  * with (a pull request's base), for a bare `--affected`. `trusted`: the
- * run has no scope, whatever git names (a merge queue's run, owner
- * 2026-10-18). The scope keys plugin entries only. A later plugin's field wins.
+ * run has no scope, whatever git names (a merge queue's run,
+ * 2026-10-18). The scope keys plugin entries only. `refs`: the refs a
+ * remote reads, in order (`CacheContext.refs`; 2026-10-25: a pull
+ * request its head branch, then its base, then the default branch; a
+ * merge queue or train only its base); unset, git's. A later plugin's
+ * field wins.
  */
 export interface BranchFacts {
   scope?: string
   base?: string
   trusted?: boolean
+  refs?: readonly string[]
 }
 
 export interface ConfigContext extends WorkspaceHookContext {
@@ -437,7 +471,7 @@ export interface FingerprintClaim {
    * 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.
+   * tell. A name that is not one of `ctx.projects` is refused.
    */
   affected(
     change: FingerprintChange,
@@ -449,9 +483,14 @@ export interface FingerprintClaim {
    * path and hashes nowhere, or a `file:` dependency's directory. A change
    * to one, or under one, asks `affected` about the file naming it, with
    * `change.extras`. Without it, a `bun.lock` patch edit selects every
-   * project.
+   * project. Asked on every `--affected` diff, so a claimant that memoises
+   * its parse answers from `ctx.cacheDir`.
    */
-  extraFiles?(file: string, bytes: Uint8Array): readonly string[]
+  extraFiles?(
+    file: string,
+    bytes: Uint8Array,
+    ctx: FingerprintContext,
+  ): readonly string[] | Promise<readonly string[]>
 }
 
 export interface FingerprintChange {
@@ -492,14 +531,33 @@ export interface ScheduleHookContext extends BaseContext {
   readonly localCache: Cache
   /** The run's branch (`currentBranch`), the timings a forecast reads first: pass it to `LocalHistoryProvider`. */
   readonly branch: string | null
+  /** The refs the run reads, in order (`CacheContext.refs`): a remote's timings are read by them too. */
+  readonly refs: readonly string[]
   /** This plugin's entries in the workspace's cache, as `setup` has them. */
   readonly cache: PluginCache
   /**
    * Replace this plugin's weights while the run goes on: the tasks not yet
    * started re-rank at once. For weights that arrive late (timings fetched
    * from a remote). Ignored in a plan and once the run's tasks are done.
+   * Given a promise, the weights it resolves to, if any, when it does:
+   * `refining()` waits for it meanwhile.
+   */
+  refine(
+    weights: ReadonlyMap<string, number> | Promise<ReadonlyMap<string, number> | undefined>,
+  ): void
+  /**
+   * Settles once every refine promised so far (a promise to `refine`) has
+   * landed or failed, its listeners called: a plugin that sizes the run by
+   * the fetched data waits for it here rather than guessing without it.
+   */
+  refining(): Promise<void>
+  /**
+   * Calls `listener` each time another plugin `refine`s: the late data it
+   * waited for (timings fetched from a remote) has landed in history, so a
+   * plugin that read history in `schedule` may read it again. Never called
+   * in a plan.
    */
-  refine(weights: ReadonlyMap<string, number>): void
+  onRefine(listener: () => void): void
 }
 
 /** A `cache` hook's context: the workspace and the run's scope, never the local store or the policy, which core owns. */
@@ -515,6 +573,13 @@ export interface CacheContext extends BaseContext {
    * keys or scopes its entries by them; core keys task entries by none.
    */
   readonly refs: readonly string[]
+  /**
+   * The token a run lent this plugin's remote (`RemoteCacheLayer.lend`),
+   * on a machine that runs that run's tasks (`CommandContext.artifactsFor`);
+   * undefined anywhere else. Read it per request: a run lends again before
+   * a token ends. A plugin uses it only when it has no access of its own.
+   */
+  readonly lent?: () => string | undefined
 }
 
 export interface OutputContext extends BaseContext {
@@ -527,6 +592,14 @@ export interface OutputContext extends BaseContext {
 export interface ExecutorContext extends BaseContext {
   /** The run's worker count — an executor that paces itself reads it here. */
   readonly concurrency: number
+  /** Task entries by key in the run's cache, for a task another machine ran (`TaskArtifacts`). */
+  readonly artifacts: TaskArtifacts
+  /**
+   * What a machine that runs this run's tasks reads the cache under
+   * (`CacheFacts`): the run's refs, and each remote's lent access, asked
+   * now. Ask again before `expiresAt`.
+   */
+  cacheFacts(): Promise<CacheFacts>
 }
 
 export interface PluginContext extends PluginSetupContext {
@@ -569,7 +642,7 @@ export interface PluginHookHandlers {
 }
 
 export interface Plugin {
-  /** Logged on errors; the convention is `'org/plugin-name'`. */
+  /** The plugin's package name (`definePlugin` sets it), logged on errors. */
   readonly name: string
   /**
    * Called once at the start of every run. Register hooks via
@@ -598,10 +671,15 @@ export interface PluginOrigin {
 
 const packageNameByDir = new Map<string, string>()
 
-/** The name of the nearest `package.json` above `dir` — the one that owns it. */
+/** The name of the nearest named `package.json` above `dir` — the one that owns it. */
 function pluginPackageName(dir: string): string {
   const memo = packageNameByDir.get(dir)
   if (memo !== undefined) return memo
+  // A package.json with no `name` below the package root is no package:
+  // dual builds (tshy) write `{ "type": "module" }` into `dist/esm/`. The
+  // walk passes it, as Vite's package lookup does; with no named one
+  // above, the nearest is refused.
+  let nameless: string | undefined
   for (let d = dir; ;) {
     let text: string | undefined
     try {
@@ -622,18 +700,22 @@ function pluginPackageName(dir: string): string {
         )
       }
       const name = pkg?.name
-      if (typeof name !== 'string' || name.length === 0) {
+      if (name === undefined) nameless ??= path.join(d, 'package.json')
+      else 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`,
         )
+      } else {
+        packageNameByDir.set(dir, name)
+        return name
       }
-      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`,
+        nameless === undefined
+          ? `definePlugin: no package.json above ${dir} — a plugin is a package, and its name is the package's`
+          : `definePlugin: ${nameless} has no name — a plugin is a package, and its name is the package's`,
       )
     }
     d = parent
@@ -643,10 +725,24 @@ function pluginPackageName(dir: string): string {
 /**
  * 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
+ * nearest `package.json` above it that has a name — 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 {
+  // The hooks are copied by spread, which takes own fields only: a class
+  // instance's methods stayed on its prototype and the plugin loaded
+  // without them, saying nothing.
+  const proto: unknown =
+    hooks !== null && typeof hooks === 'object' ? Object.getPrototypeOf(hooks) : undefined
+  if (proto !== Object.prototype && proto !== null) {
+    const got =
+      hooks === null || typeof hooks !== 'object'
+        ? String(hooks)
+        : `a ${(hooks as object).constructor?.name || 'class instance'}`
+    throw new UserError(
+      `definePlugin: the hooks must be a plain object ({ setup() { … } }), got ${got}`,
+    )
+  }
   if ('name' in hooks) {
     throw new UserError(`definePlugin: a plugin's name is its package name — drop the 'name' field`)
   }
@@ -668,9 +764,11 @@ type OptionKind<V> = [V] extends [string]
       ? 'boolean'
       : [V] extends [(...args: never[]) => unknown]
         ? 'function'
-        : [V] extends [object]
-          ? 'object'
-          : 'any'
+        : [V] extends [readonly unknown[]]
+          ? 'array'
+          : [V] extends [object]
+            ? 'object'
+            : 'any'
 
 /**
  * Every option a factory takes, each with the one kind its type allows
@@ -702,7 +800,8 @@ export function refuseUnknownOptions<T>(
   const known = kinds as Readonly<Record<string, string>>
   const names = Object.keys(known)
   for (const [key, value] of Object.entries(options)) {
-    const kind = known[key]
+    // Own keys only: the record's prototype answers `constructor`.
+    const kind = Object.hasOwn(known, key) ? known[key] : undefined
     if (kind === undefined) {
       const near = nearest(key, names)
       throw new UserError(
@@ -714,12 +813,14 @@ export function refuseUnknownOptions<T>(
     const ok =
       kind === 'object'
         ? value !== null && typeof value === 'object' && !Array.isArray(value)
-        : typeof value === kind
+        : kind === 'array'
+          ? Array.isArray(value)
+          : typeof value === kind
     if (!ok) {
       const got =
         typeof value === 'function' ? 'a function' : (JSON.stringify(value) ?? String(value))
       throw new UserError(
-        `${factory} option "${key}" must be ${kind === 'object' ? 'an' : 'a'} ${kind}, got ${got}`,
+        `${factory} option "${key}" must be ${kind === 'object' || kind === 'array' ? 'an' : 'a'} ${kind}, got ${got}`,
       )
     }
   }
@@ -731,7 +832,7 @@ export interface InstallPluginsArgs {
   cacheDir: string
   bus: EventBus
   /**
-   * Where plugin-throw warnings go. Defaults to console.error; passing
+   * Where plugin-throw warnings go. Defaults to `ui.say` on stderr; passing
    * a callback lets the orchestrator funnel into the framed-output
    * `run:status` channel.
    */
@@ -757,8 +858,9 @@ export class PluginSetupError extends UserError {
   constructor(
     readonly plugin: Plugin,
     message: string,
+    code = 'VX_E_REFUSED',
   ) {
-    super(message)
+    super(message, code)
   }
 }
 
@@ -774,7 +876,7 @@ export class PluginSetupError extends UserError {
  */
 export async function installPlugins(args: InstallPluginsArgs): Promise<() => void> {
   const { plugins, bus, workspaceRoot, cacheDir } = args
-  const warn = args.warn ?? ((m) => console.error(m))
+  const warn = args.warn ?? ((m) => ui.say('warn', m))
   const secrets = args.secrets ?? new SecretBroker(args.ci ?? false, warn)
   const disposers: Array<() => void> = []
   // By object, not name: one package can export two plugins.
@@ -796,7 +898,7 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
       if (disabled.has(plugin)) return
       disabled.add(plugin)
       warn(
-        `[vx] plugin '${plugin.name}' threw in ${where}; disabled for this run: ${err instanceof Error ? err.message : String(err)}`,
+        `[vx] plugin '${plugin.name}' threw in ${where}; disabled for this run: ${thrownMessage(err)}`,
       )
     }
     const ctx: PluginContext = {
@@ -813,6 +915,11 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
       bus: {
         emit: (event) => bus.emit(event),
         subscribe(subscriber) {
+          if (typeof subscriber !== 'function') {
+            throw new Error(
+              `ctx.bus.subscribe: the subscriber is ${subscriber === null ? 'null' : typeof subscriber}, not a function`,
+            )
+          }
           // Isolated like an `on` handler: the bus itself swallows a throw.
           const dispose = bus.subscribe((event) => {
             if (disabled.has(plugin)) return
@@ -837,6 +944,12 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
             `ctx.on: unknown hook '${String(hook)}' (one of ${Object.keys(HOOK_NAMES).join(', ')})`,
           )
         }
+        // Taken, it threw at the first event and switched the whole plugin off.
+        if (typeof handler !== 'function') {
+          throw new Error(
+            `ctx.on: the handler for '${hook}' is ${handler === null ? 'null' : typeof handler}, not a function`,
+          )
+        }
         const onFail = (err: unknown): void => fail(hook, err)
         const dispose = bus.subscribe((event) => {
           if (disabled.has(plugin)) return
@@ -893,9 +1006,9 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
       throw new PluginSetupError(
         plugin,
         // Masked at the source, as plugin-host.ts's `safe()` does (L-11).
-        maskedLine(
-          `plugin '${plugin.name}' failed in setup: ${err instanceof Error ? err.message : String(err)}`,
-        ),
+        maskedLine(`plugin '${plugin.name}' failed in setup: ${thrownMessage(err)}`),
+        // The plugin's own code survives, as `safe()` keeps it.
+        errorCode(err) === 'VX_E_INTERNAL' ? 'VX_E_REFUSED' : errorCode(err),
       )
     }
   }