@visulima/vis 1.0.0-alpha.11 → 1.0.0-alpha.13

package/dist/config/index.d.ts

@@ -1,5 +1,6 @@
 import { TaskResult, Task, TargetConfiguration, ConstraintsConfig, NamedInputs, TaskRunnerOptions } from '@visulima/task-runner';
 import { Hookable } from 'hookable';
+import { Tracer } from '@opentelemetry/api';
 /**
 * Typed hook surface exposed to vis plugins.
 *
@@ -82,6 +83,25 @@ interface VisPlugin {
   */
   setup?: (hooks: Hookable<VisHooks>) => Promise<void> | void;
 }
+/**
+* One family of upstream-coupled packages.
+*
+* `members` is an exact-match list. `prefixes` accept any dep whose
+* name starts with the prefix — useful for monorepos that ship many
+* subpackages under one scope (e.g. `@babel/`, `@storybook/`,
+* `@nx/`). A family can use either or both; a dep matching either
+* list belongs to the family.
+*/
+interface SimilarDepFamily {
+  /** Stable id; used in report output and config overrides. */
+  id: string;
+  /** Pretty label for the report. Defaults to `id` when omitted. */
+  label?: string;
+  /** Dep names that belong to this family verbatim. */
+  members?: string[];
+  /** Dep-name prefixes (literal, no glob). Match if `depName.startsWith(prefix)`. */
+  prefixes?: string[];
+}
 type VersionManagerName = "asdf" | "corepack" | "fnm" | "mise" | "none" | "nvm" | "proto" | "self-activate" | "volta";
 type RuntimeTool = "bun" | "deno" | "go" | "node" | "npm" | "pnpm" | "python" | "ruby" | "rust" | "yarn";
 interface ToolchainConfig {
@@ -106,7 +126,7 @@ interface ToolchainConfig {
 * and returns a promise that resolves on success or rejects on failure.
 */
 interface CustomTask {
-  readonly task: (files: string[]) => Promise<unknown> | unknown;
+  readonly task: (files: string[]) => unknown;
   readonly title: string;
 }
 /**
@@ -228,17 +248,6 @@ interface VisTargetOptions {
   */
   envFile?: boolean | string | string[];
   /**
-  * Override the workspace `strictEnv` setting for this target. When
-  * truthy, the target fails if its command references an env var
-  * that resolves to neither the task's effective env nor
-  * `process.env`. When `false`, the target opts out of a workspace
-  * `strictEnv: true` (e.g. for a one-off command that legitimately
-  * tolerates an unset variable).
-  *
-  * @see VisConfig.strictEnv
-  */
-  strictEnv?: boolean;
-  /**
   * When true, the task is serialized with respect to parallel execution
   * and must be run on the main process (claims stdin). Used for commands
   * that read from the terminal.
@@ -329,8 +338,22 @@ interface VisTargetOptions {
   */
   runInCI?: RunInCI;
   /**
+  * Capability tags that gate this task to runners advertising the
+  * same tag. The CLI's `--runner-tags=gpu,slow` flag (or
+  * `VIS_RUNNER_TAGS` env var) tells vis what the current runner
+  * supports; tasks whose `runnerTags` share at least one tag with
+  * the runner set are eligible. Untagged tasks (no `runnerTags` or
+  * an empty array) are general-purpose and always run.
+  *
+  * Use this for special-purpose CI lanes — e.g. a GPU runner that
+  * should only pick up visual-regression suites, or a nightly job
+  * that runs `slow` integration tests. When neither flag nor env
+  * is set, the filter is inactive and every task runs.
+  */
+  runnerTags?: string[];
+  /**
   * Marks this target as a long-lived service that can be started via
-  * `vis service start <id>` and auto-attached when other tasks declare
+  * `vis service start &lt;id>` and auto-attached when other tasks declare
   * it in `dependsOn`. Implies persistent + non-cacheable behaviour
   * (set `preset: "server"` to inherit the rest of the bundle).
   *
@@ -346,6 +369,16 @@ interface VisTargetOptions {
   */
   shell?: string;
   /**
+  * Override the workspace `strictEnv` setting for this target. When
+  * truthy, the target fails if its command references an env var
+  * that resolves to neither the task's effective env nor
+  * `process.env`. When `false`, the target opts out of a workspace
+  * `strictEnv: true` (e.g. for a one-off command that legitimately
+  * tolerates an unset variable).
+  * @see VisConfig.strictEnv
+  */
+  strictEnv?: boolean;
+  /**
   * Maximum wall-clock milliseconds a single task run is allowed to
   * take before being killed. `0` / `undefined` means no timeout.
   *
@@ -414,6 +447,32 @@ interface CodeownersConfig {
   provider?: "bitbucket" | "github" | "gitlab" | "other";
 }
 /**
+* One user-declared customTypes entry. See `policy.customTypes.extraTypes`
+* for the full contract — this is just the row shape.
+*/
+interface ExtraCustomType {
+  /**
+  * Required when `strategy === "string"`. The dep-cluster key the bare
+  * version string at `path` should be associated with.
+  */
+  depName?: string;
+  /**
+  * Display name for this customType. Used as the cluster key prefix in
+  * lint output and JSON. Must not collide with the built-in names.
+  */
+  name: string;
+  /** Dot-separated walk into package.json (e.g. `pnpm.overrides`, `myTool.runtime`). */
+  path: string;
+  /**
+  * How to interpret the JSON found at `path`.
+  * - `name@version` — single string `pnpm@9.0.0` (with optional `+sha512.…` hash).
+  * - `name~version` — single string `node~20.0.0`, mirrors syncpack's tilde form.
+  * - `string` — bare version literal (requires `depName`).
+  * - `versionsByName` — `{ name: version }` object such as `engines`.
+  */
+  strategy: "name@version" | "name~version" | "string" | "versionsByName";
+}
+/**
 * Declared code-owner assignment for a path glob within a project.
 * Mirrors moon's `owners` shape so migrations can round-trip cleanly.
 */
@@ -511,19 +570,6 @@ interface VisConfig {
     provider?: string;
   };
   /**
-  * When `true`, every task command is scanned for `${VAR}` / `$VAR`
-  * references before spawn. If a referenced var is unset in the
-  * task's effective env (envFile + service env + per-task `env` +
-  * `process.env`), the task fails with an actionable error
-  * naming the missing variable, instead of letting the shell
-  * silently substitute an empty string.
-  *
-  * Override per run with `--strict-env` / `--no-strict-env`.
-  * Override per target with `options.strictEnv`.
-  * @default false
-  */
-  strictEnv?: boolean;
-  /**
   * Scope the task-runner cache directory by the current git branch.
   * When `true`, caches are stored under `&lt;cacheDir>/branches/&lt;slug>`
   * so `main` and feature branches stop thrashing each other —
@@ -612,6 +658,13 @@ interface VisConfig {
     templates?: Record<string, string>;
   };
   /**
+  * Discover `.editorconfig` for indent / line-ending defaults during
+  * file transformations (sort-package-json, migrate, hook, pm overrides,
+  * workspace catalog rewrites). Per-command flags can still override.
+  * @default true
+  */
+  editorconfig?: boolean;
+  /**
   * Inherit configuration from one or more parent configs. Entries are
   * resolved left-to-right (later wins) and the consumer's own values
   * always override anything pulled in from `extends`.
@@ -675,37 +728,6 @@ interface VisConfig {
     templates?: string[];
   };
   /**
-  * Installer backend selection for `vis install` / `vis add` /
-  * `vis remove` / `vis update` / `vis ci`.
-  *
-  * Lets users opt into [aube](https://github.com/endevco/aube) — a
-  * Rust-native package manager that reads/writes pnpm/npm/yarn/bun
-  * lockfiles in place — as the default installer, while keeping a
-  * single switch to fall back to the conventional PM detected from
-  * the lockfile.
-  *
-  * Resolution precedence (highest first):
-  * 1. CLI flag (`--installer &lt;name>` / `--no-aube`)
-  * 2. Env var `VIS_INSTALLER`
-  * 3. This config field
-  * 4. Auto-detect (the default)
-  *
-  * Aube must be installed separately — `vis` does not bundle it.
-  * Install via `npm i -g @endevco/aube`, `mise use -g aube`, or
-  * `brew install endevco/tap/aube`.
-  */
-  install?: {
-    /**
-    * Which package manager performs install/add/remove/etc.
-    * - `auto` (default): use `aube` when it is on PATH; otherwise
-    *   fall back to the lockfile-detected PM.
-    * - explicit name: always use that PM. Errors when the named
-    *   binary is missing rather than silently falling back.
-    * @default "auto"
-    */
-    backend?: "aube" | "auto" | "bun" | "npm" | "pnpm" | "yarn";
-  };
-  /**
   * Auto-create targets from detected config files (Project Crystal-style).
   * Inferred targets sit *below* explicit ones — anything in
   * `package.json#scripts`, `project.json#targets`, or `vis.task.ts`
@@ -767,6 +789,51 @@ interface VisConfig {
   */
   inferTargets?: Record<string, boolean> | boolean;
   /**
+  * Installer backend selection for `vis install` / `vis add` /
+  * `vis remove` / `vis update` / `vis ci`.
+  *
+  * Lets users opt into [aube](https://github.com/endevco/aube) — a
+  * Rust-native package manager that reads/writes pnpm/npm/yarn/bun
+  * lockfiles in place — as the default installer, while keeping a
+  * single switch to fall back to the conventional PM detected from
+  * the lockfile.
+  *
+  * Resolution precedence (highest first):
+  * 1. CLI flag (`--installer &lt;name>` / `--no-aube`)
+  * 2. Env var `VIS_INSTALLER`
+  * 3. This config field
+  * 4. Auto-detect (the default)
+  *
+  * Aube must be installed separately — `vis` does not bundle it.
+  * Install via npm (`@endevco/aube`), `mise use -g aube`, or
+  * `brew install endevco/tap/aube`.
+  */
+  install?: {
+    /**
+    * Which package manager performs install/add/remove/etc.
+    * - `auto` (default): use `aube` when it is on PATH; otherwise
+    *   fall back to the lockfile-detected PM.
+    * - explicit name: always use that PM. Errors when the named
+    *   binary is missing rather than silently falling back.
+    * @default "auto"
+    */
+    backend?: "aube" | "auto" | "bun" | "npm" | "pnpm" | "yarn";
+    /**
+    * Whether to dispatch PM invocations through `corepack`.
+    * - `"auto"` (default): use corepack only when the workspace
+    *   pins a PM via the `packageManager` field AND `corepack` is
+    *   on PATH AND the PM is one corepack manages (pnpm/yarn/npm).
+    * - `true`: always prefix `corepack` when the binary is on PATH
+    *   and the PM is corepack-managed (errors loudly otherwise).
+    * - `false`: never go through corepack — invoke the PM directly.
+    *
+    * Mirrors nypm's `corepack: true` flag. Bun, deno, and aube are
+    * never wrapped — corepack does not manage them.
+    * @default "auto"
+    */
+    corepack?: "auto" | boolean;
+  };
+  /**
   * Named input patterns inherited by every project target. Equivalent
   * to task-runner's `namedInputs` but configurable from the vis config.
   */
@@ -781,6 +848,290 @@ interface VisConfig {
   */
   plugins?: VisPlugin[];
   /**
+  * Workspace dep-policy lints exposed via `vis lint`. Each block opts in
+  * to a single rule; the command flags (`--workspace-protocol`,
+  * `--no-redefine-root`, `--banned-deps`) toggle them per-run.
+  */
+  policy?: {
+    /**
+    * Map of dep names or globs → reason (or `{ reason, replacement, packages?, paths? }`).
+    * Internal/workspace deps are never flagged here; the
+    * workspace-protocol lint owns those.
+    *
+    * Optional `packages` (globs over the declaring package's `name`) and
+    * `paths` (globs over the workspace-relative `packageDir`) narrow where
+    * the rule applies. With both set, either match is enough. Omit both
+    * to ban anywhere — the default.
+    * @example
+    * ```
+    * bannedDeps: {
+    *   request: "deprecated; use undici",
+    *   moment: { reason: "huge bundle, frozen upstream", replacement: "date-fns" },
+    *   "@radix-ui/*": "we standardized on shadcn",
+    *   react: { reason: "no react in shared libs", paths: ["packages/shared/*"] },
+    *   "next": { reason: "apps only", packages: ["@app/*"] },
+    * }
+    * ```
+    */
+    bannedDeps?: Record<string, string | {
+      packages?: string[];
+      paths?: string[];
+      reason: string;
+      replacement?: string;
+    }>;
+    /**
+    * Tweak the custom-types lint that flags drift in `engines.{node,pnpm,...}`,
+    * `packageManager`, `volta.{node,pnpm,yarn}`, and the proposed
+    * `devEngines.{runtime,packageManager}` array form.
+    *
+    * Each (customType × name) cluster is tracked independently —
+    * `engines.node` and `volta.node` don't cross-couple here. Use a
+    * versionGroup once that lands if you need to enforce they agree.
+    */
+    customTypes?: {
+      /**
+      * Three-state autofix opt-out. See `workspaceProtocol.autofix`
+      * for the contract — same semantics, applied to drift rewrites
+      * across engines / packageManager / volta / devEngines.
+      *
+      * Note: `--fix` strips any `+sha512.&lt;hash&gt;` suffix from
+      * `packageManager` on bump — content-integrity hashes are tied
+      * to a specific package, not a version, so users must regenerate
+      * via their PM (`pnpm install` re-pins; `corepack use pnpm@X` etc.).
+      * @default true
+      */
+      autofix?: "prompt" | boolean;
+      /**
+      * User-defined custom-type pin locations. Each entry tells the
+      * customTypes lint to read additional version pins from a
+      * non-standard JSON path inside every workspace package.json,
+      * cluster them by `(name × depName)` like the built-in types,
+      * and rewrite them with `--fix`.
+      *
+      * The original built-ins (`engines`, `volta`, `packageManager`,
+      * `devEngines.runtime`, `devEngines.packageManager`) keep
+      * running unconditionally — these layer on top.
+      *
+      * Strategies:
+      * - `versionsByName`: the JSON at `path` is `{ [depName]: version }`
+      *   (like `engines` or `pnpm.overrides`).
+      * - `name@version`: the JSON at `path` is a string of the form
+      *   `name@version` (like `packageManager`). The leading `name@`
+      *   is preserved; only the version segment is rewritten.
+      * - `string`: the JSON at `path` is a bare version string. The
+      *   `depName` field is required and identifies the dep cluster.
+      *
+      * `name` must not collide with a built-in type name. `path` is
+      * a dot-separated walk into the package.json (e.g. `pnpm.overrides`).
+      * @example
+      * ```ts
+      * extraTypes: [
+      *   { name: "pnpmOverridesLegacy", path: "pnpm.overrides", strategy: "versionsByName" },
+      *   { name: "myToolPin",           path: "myTool.runtime", strategy: "name@version" },
+      *   { name: "minNode",             path: "config.minNode", strategy: "string", depName: "node" },
+      * ]
+      * ```
+      */
+      extraTypes?: ExtraCustomType[];
+      /**
+      * Dep names exempt from the drift check (exact match against the
+      * field name within the block — e.g. `node`, `pnpm`).
+      */
+      ignore?: string[];
+      /**
+      * Resolution strategy used when `--fix` runs.
+      * - `highest` (default): align every drifting instance to the
+      *   highest declared version.
+      * - `lowest`: align to the lowest.
+      * @default "highest"
+      */
+      resolve?: "highest" | "lowest";
+    };
+    /**
+    * Tweak the dead-workspace-patterns lint that flags entries in
+    * `pnpm-workspace.yaml#packages` / `package.json#workspaces` which
+    * resolve to zero on-disk directories.
+    */
+    deadWorkspacePatterns?: {
+      /**
+      * Three-state autofix opt-out. See `workspaceProtocol.autofix`
+      * for the contract — applied here to dropping unmatched patterns
+      * from the workspace config file.
+      * @default true
+      */
+      autofix?: "prompt" | boolean;
+    };
+    /**
+    * Tweak the empty-deps lint that flags empty `dependencies` /
+    * `devDependencies` / `peerDependencies` / `optionalDependencies`
+    * blocks across the workspace.
+    */
+    emptyDeps?: {
+      /**
+      * Three-state autofix opt-out. See `workspaceProtocol.autofix`
+      * for the contract — applied here to removing the empty key.
+      * @default true
+      */
+      autofix?: "prompt" | boolean;
+      /**
+      * Block names exempt from the rule (e.g. `["peerDependencies"]`
+      * to keep the key around as a marker even when empty).
+      */
+      ignoreBlocks?: ("dependencies" | "devDependencies" | "optionalDependencies" | "peerDependencies")[];
+    };
+    /**
+    * Tweak the redefine-root lint that flags non-root packages duplicating
+    * deps already pinned at the workspace root.
+    */
+    redefineRoot?: {
+      /** Dep names that are exempt from the redefine-root rule (exact match). */
+      ignore?: string[];
+    };
+    /**
+    * Tweak the root-deps lint that flags runtime `dependencies` declared
+    * on the private workspace root (they should live in `devDependencies`).
+    */
+    rootDeps?: {
+      /**
+      * Three-state autofix opt-out. See `workspaceProtocol.autofix`
+      * for the contract — applied here to moving entries from
+      * `dependencies` to `devDependencies` on the root package.json.
+      * @default true
+      */
+      autofix?: "prompt" | boolean;
+    };
+    /**
+    * Tweak the root-package-manager lint that flags a missing or
+    * malformed `packageManager` field on the workspace root.
+    */
+    rootPackageManager?: {
+      /**
+      * Three-state autofix opt-out. See `workspaceProtocol.autofix`
+      * for the contract. `--fix` only writes when `suggested` is set —
+      * a missing `packageManager` field has no canonical default.
+      * @default true
+      */
+      autofix?: "prompt" | boolean;
+      /**
+      * Canonical specifier (`name@version`) to write when `--fix` runs
+      * and the field is absent. Required to enable autofix —
+      * vis won't guess the workspace's preferred manager.
+      * @example "pnpm@10.32.1"
+      */
+      suggested?: string;
+    };
+    /**
+    * Tweak the root-private lint that flags a workspace root package.json
+    * missing `"private": true`. Only fires when the root looks like a
+    * workspace (npm/yarn/bun `workspaces` field or `pnpm-workspace.yaml`).
+    */
+    rootPrivate?: {
+      /**
+      * Three-state autofix opt-out. See `workspaceProtocol.autofix`
+      * for the contract — applied here to inserting `"private": true`.
+      * @default true
+      */
+      autofix?: "prompt" | boolean;
+    };
+    /**
+    * Tweak the similar-deps lint that flags drift across related dep
+    * families (e.g. `react` and `react-dom`, all of `@babel/*`).
+    *
+    * The lint is report-only — aligning a family requires picking a
+    * single canonical specifier across heterogeneous range syntaxes
+    * (`^`, `~`, exact), which is too lossy without user input.
+    */
+    similarDeps?: {
+      /**
+      * Additional families merged with the built-ins. Same `id` wins
+      * → user override fully replaces the built-in entry.
+      * @example
+      * ```
+      * extraFamilies: [
+      *   { id: "vue", label: "Vue", members: ["vue", "vue-router", "pinia"] },
+      * ]
+      * ```
+      */
+      extraFamilies?: SimilarDepFamily[];
+      /** Family ids to skip entirely (matches `SimilarDepFamily.id`). */
+      ignoreFamilies?: string[];
+    };
+    /**
+    * Tweak the types-in-deps lint that flags `@types/*` declared in
+    * `dependencies` on a private package (they belong in
+    * `devDependencies` since the package never ships).
+    */
+    typesInDeps?: {
+      /**
+      * Three-state autofix opt-out. See `workspaceProtocol.autofix`
+      * for the contract — applied here to moving the entry to
+      * `devDependencies`. Existing dev pins are preserved on conflict.
+      * @default true
+      */
+      autofix?: "prompt" | boolean;
+      /** Dep names exempt from the rule (exact match, e.g. `@types/node`). */
+      ignore?: string[];
+    };
+    /**
+    * Tweak the workspace-protocol lint that flags internal deps not
+    * using the `workspace:` protocol.
+    */
+    workspaceProtocol?: {
+      /**
+      * Three-state autofix opt-out. Some workspaces want detection
+      * without rewrite (e.g. dual-licensed packages where `workspace:*`
+      * is unsafe).
+      * - `true` (default): `--fix` rewrites the specifier.
+      * - `false`: never rewrite — report the violation only.
+      * - `"prompt"`: ask before each rewrite. Falls back to report-only
+      *   when stdin isn't a TTY (CI). Reserved; not yet implemented.
+      *
+      * Note: when `false` (or `"prompt"`), `--fix` still **fails CI** on
+      * detected violations — the rule is "report only", not "ignore".
+      * Drop the rule from the lint selection if you want a clean exit.
+      * @default true
+      * @example
+      * ```
+      * policy: {
+      *   workspaceProtocol: { autofix: false },
+      * }
+      * ```
+      */
+      autofix?: "prompt" | boolean;
+    };
+    /**
+    * Tweak the workspace-versions lint that flags external deps declared
+    * at inconsistent versions across the workspace.
+    */
+    workspaceVersions?: {
+      /**
+      * Three-state autofix opt-out. See `workspaceProtocol.autofix`
+      * for the contract — same semantics, applied to drift rewrites.
+      *
+      * Also gates the `--propose-min` catalog suggestion writer:
+      * when `false` / `"prompt"`, `--fix --propose-min` reports the
+      * proposed catalog entries but does not write
+      * `pnpm-workspace.yaml`. Same "report only, still fails CI"
+      * note applies as on `workspaceProtocol.autofix`.
+      * @default true
+      */
+      autofix?: "prompt" | boolean;
+      /** Dep names exempt from the version-drift check (exact match). */
+      ignore?: string[];
+      /**
+      * Resolution strategy used when `--fix` runs.
+      * - `highest` (default): rewrite every drifting instance to the
+      *   highest sibling specifier.
+      * - `lowest`: rewrite to the lowest.
+      * - `catalog`: rewrite any dep already pinned in a workspace catalog
+      *   to `catalog:` / `catalog:&lt;name>`. Catalog must exist; this lint
+      *   does not create the catalog (see `vis lint --resolve catalog --propose`).
+      * @default "highest"
+      */
+      resolve?: "catalog" | "highest" | "lowest";
+    };
+  };
+  /**
   * Pre-flight checks fired before `vis run` starts the orchestrator.
   * Each check is opt-out (`false`) — defaults are sensible for the
   * common monorepo case.
@@ -1013,10 +1364,37 @@ interface VisConfig {
   sharedWorktreeCache?: boolean;
   /** sort-package-json command defaults */
   sortPackageJson?: {
+    /** Discover `.editorconfig` for indent / line-ending defaults (default: true). */
+    editorconfig?: boolean;
+    /** Collapse `bugs: { url }` to the bare string form when `url` is the only field (default: true). */
+    formatBugs?: boolean;
+    /** Collapse `repository: { type, url }` to the GitHub `owner/repo` shorthand (default: true). */
+    formatRepository?: boolean;
+    /** Sort `exports` condition keys in canonical order (default: true). */
+    sortExports?: boolean;
     /** Alphabetize script commands (default: false) */
     sortScripts?: boolean;
   };
   /**
+  * Sponsorship notice shown after successful commands.
+  *
+  * vis prints a one-line "consider sponsoring visulima" notice at most
+  * once every 14 days (skipped in CI, non-TTY, and when
+  * `VIS_NO_SPONSOR=1` is set). Set `enabled: false` to silence it
+  * permanently for this workspace.
+  * @example
+  * ```
+  * sponsor: { enabled: false }
+  * ```
+  */
+  sponsor?: {
+    /**
+    * Show the sponsor notice on successful command completion.
+    * @default true
+    */
+    enabled?: boolean;
+  };
+  /**
   * Staged file patterns and commands (replaces lint-staged).
   *
   * Accepts all lint-staged config forms:
@@ -1027,6 +1405,19 @@ interface VisConfig {
   * - A top-level generate-task function
   */
   staged?: StagedConfig;
+  /**
+  * When `true`, every task command is scanned for `${VAR}` / `$VAR`
+  * references before spawn. If a referenced var is unset in the
+  * task's effective env (envFile + service env + per-task `env` +
+  * `process.env`), the task fails with an actionable error
+  * naming the missing variable, instead of letting the shell
+  * silently substitute an empty string.
+  *
+  * Override per run with `--strict-env` / `--no-strict-env`.
+  * Override per target with `options.strictEnv`.
+  * @default false
+  */
+  strictEnv?: boolean;
   /** Target default configurations */
   targetDefaults?: Record<string, Partial<VisTargetConfiguration>>;
   /**
@@ -1120,6 +1511,13 @@ interface VisConfig {
     includeLocked?: boolean;
     install?: boolean;
     /**
+    * Maximum number of concurrent registry requests during outdated checks.
+    * Higher values speed up large workspaces but risk hitting registry rate
+    * limits or self-hosted Verdaccio caps.
+    * @default 8
+    */
+    maxConcurrentRequests?: number;
+    /**
     * Minimum number of minutes since a version was published before
     * vis will consider it for updates. This mirrors pnpm's
     * `minimumReleaseAge` — a single setting that applies to both
@@ -1145,6 +1543,20 @@ interface VisConfig {
     */
     packageMode?: Record<string, "latest" | "minor" | "patch">;
     prerelease?: boolean;
+    /**
+    * Which release channels to consider when picking the target version.
+    * - `"stable"` (default) — only ship stable releases (no prereleases).
+    * - `"same"` — match the prerelease channel of the *current* range:
+    *   if you're on `react@19.0.0-rc.1`, only `rc.*` candidates qualify;
+    *   if you're on a stable, only stable candidates. Prevents
+    *   accidentally promoting a prerelease pin to a stable major bump.
+    * - `"any"` — equivalent to `--prerelease`. Any channel is fair game.
+    *
+    * `--release-channel` on the CLI overrides this. If `prerelease: true`
+    * is set without `releaseChannel`, vis treats it as `"any"`.
+    * @default "stable"
+    */
+    releaseChannel?: "any" | "same" | "stable";
     security?: boolean;
     target?: "latest" | "minor" | "patch";
   };
@@ -1158,504 +1570,6 @@ interface VisConfig {
   */
   versionConstraint?: string;
 }
-/**
-* Extended project configuration exposed on the discovered workspace.
-* Adds vis-specific metadata (layer, stack, language, owners) on top of
-* the task-runner `ProjectConfiguration`.
-*/
-/**
- * @since 1.0.0
- */
-interface Context {
-  /**
-   * Get a value from the context.
-   *
-   * @param key key which identifies a context value
-   */
-  getValue(key: symbol): unknown;
-  /**
-   * Create a new context which inherits from this context and has
-   * the given key set to the given value.
-   *
-   * @param key context key for which to set the value
-   * @param value value to set for the given key
-   */
-  setValue(key: symbol, value: unknown): Context;
-  /**
-   * Return a new context which inherits from this context but does
-   * not contain a value for the given key.
-   *
-   * @param key context key for which to clear a value
-   */
-  deleteValue(key: symbol): Context;
-}
-/**
- * Attributes is a map from string to attribute values.
- *
- * Note: only the own enumerable keys are counted as valid attribute keys.
- *
- * @since 1.3.0
- */
-interface Attributes {
-  [attributeKey: string]: AttributeValue | undefined;
-}
-/**
- * Attribute values may be any non-nullish primitive value except an object.
- *
- * null or undefined attribute values are invalid and will result in undefined behavior.
- *
- * @since 1.3.0
- */
-type AttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
-interface ExceptionWithCode {
-  code: string | number;
-  name?: string;
-  message?: string;
-  stack?: string;
-}
-interface ExceptionWithMessage {
-  code?: string | number;
-  message: string;
-  name?: string;
-  stack?: string;
-}
-interface ExceptionWithName {
-  code?: string | number;
-  message?: string;
-  name: string;
-  stack?: string;
-}
-/**
- * Defines Exception.
- *
- * string or an object with one of (message or name or code) and optional stack
- *
- * @since 1.0.0
- */
-type Exception = ExceptionWithCode | ExceptionWithMessage | ExceptionWithName | string;
-/**
- * Defines High-Resolution Time.
- *
- * The first number, HrTime[0], is UNIX Epoch time in seconds since 00:00:00 UTC on 1 January 1970.
- * The second number, HrTime[1], represents the partial second elapsed since Unix Epoch time represented by first number in nanoseconds.
- * For example, 2021-01-01T12:30:10.150Z in UNIX Epoch time in milliseconds is represented as 1609504210150.
- * The first number is calculated by converting and truncating the Epoch time in milliseconds to seconds:
- * HrTime[0] = Math.trunc(1609504210150 / 1000) = 1609504210.
- * The second number is calculated by converting the digits after the decimal point of the subtraction, (1609504210150 / 1000) - HrTime[0], to nanoseconds:
- * HrTime[1] = Number((1609504210.150 - HrTime[0]).toFixed(9)) * 1e9 = 150000000.
- * This is represented in HrTime format as [1609504210, 150000000].
- *
- * @since 1.0.0
- */
-type HrTime = [number, number];
-/**
- * Defines TimeInput.
- *
- * hrtime, epoch milliseconds, performance.now() or Date
- *
- * @since 1.0.0
- */
-type TimeInput = HrTime | number | Date;
-/**
- * @deprecated please use {@link Attributes}
- * @since 1.0.0
- */
-type SpanAttributes = Attributes;
-/**
- * @deprecated please use {@link AttributeValue}
- * @since 1.0.0
- */
-type SpanAttributeValue = AttributeValue;
-/**
- * @since 1.0.0
- */
-interface TraceState {
-  /**
-   * Create a new TraceState which inherits from this TraceState and has the
-   * given key set.
-   * The new entry will always be added in the front of the list of states.
-   *
-   * @param key key of the TraceState entry.
-   * @param value value of the TraceState entry.
-   */
-  set(key: string, value: string): TraceState;
-  /**
-   * Return a new TraceState which inherits from this TraceState but does not
-   * contain the given key.
-   *
-   * @param key the key for the TraceState entry to be removed.
-   */
-  unset(key: string): TraceState;
-  /**
-   * Returns the value to which the specified key is mapped, or `undefined` if
-   * this map contains no mapping for the key.
-   *
-   * @param key with which the specified value is to be associated.
-   * @returns the value to which the specified key is mapped, or `undefined` if
-   *     this map contains no mapping for the key.
-   */
-  get(key: string): string | undefined;
-  /**
-   * Serializes the TraceState to a `list` as defined below. The `list` is a
-   * series of `list-members` separated by commas `,`, and a list-member is a
-   * key/value pair separated by an equals sign `=`. Spaces and horizontal tabs
-   * surrounding `list-members` are ignored. There can be a maximum of 32
-   * `list-members` in a `list`.
-   *
-   * @returns the serialized string.
-   */
-  serialize(): string;
-}
-/**
- * A SpanContext represents the portion of a {@link Span} which must be
- * serialized and propagated along side of a {@link Baggage}.
- *
- * @since 1.0.0
- */
-interface SpanContext {
-  /**
-   * The ID of the trace that this span belongs to. It is worldwide unique
-   * with practically sufficient probability by being made as 16 randomly
-   * generated bytes, encoded as a 32 lowercase hex characters corresponding to
-   * 128 bits.
-   */
-  traceId: string;
-  /**
-   * The ID of the Span. It is globally unique with practically sufficient
-   * probability by being made as 8 randomly generated bytes, encoded as a 16
-   * lowercase hex characters corresponding to 64 bits.
-   */
-  spanId: string;
-  /**
-   * Only true if the SpanContext was propagated from a remote parent.
-   */
-  isRemote?: boolean;
-  /**
-   * Trace flags to propagate.
-   *
-   * It is represented as 1 byte (bitmap). Bit to represent whether trace is
-   * sampled or not. When set, the least significant bit documents that the
-   * caller may have recorded trace data. A caller who does not record trace
-   * data out-of-band leaves this flag unset.
-   *
-   * see {@link TraceFlags} for valid flag values.
-   */
-  traceFlags: number;
-  /**
-   * Tracing-system-specific info to propagate.
-   *
-   * The tracestate field value is a `list` as defined below. The `list` is a
-   * series of `list-members` separated by commas `,`, and a list-member is a
-   * key/value pair separated by an equals sign `=`. Spaces and horizontal tabs
-   * surrounding `list-members` are ignored. There can be a maximum of 32
-   * `list-members` in a `list`.
-   * More Info: https://www.w3.org/TR/trace-context/#tracestate-field
-   *
-   * Examples:
-   *     Single tracing system (generic format):
-   *         tracestate: rojo=00f067aa0ba902b7
-   *     Multiple tracing systems (with different formatting):
-   *         tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE
-   */
-  traceState?: TraceState;
-}
-/**
- * @since 1.0.0
- */
-interface SpanStatus {
-  /** The status code of this message. */
-  code: SpanStatusCode;
-  /** A developer-facing error message. */
-  message?: string;
-}
-/**
- * An enumeration of status codes.
- *
- * @since 1.0.0
- */
-declare enum SpanStatusCode {
-  /**
-   * The default status.
-   */
-  UNSET = 0,
-  /**
-   * The operation has been validated by an Application developer or
-   * Operator to have completed successfully.
-   */
-  OK = 1,
-  /**
-   * The operation contains an error.
-   */
-  ERROR = 2,
-}
-/**
- * A pointer from the current {@link Span} to another span in the same trace or
- * in a different trace.
- * Few examples of Link usage.
- * 1. Batch Processing: A batch of elements may contain elements associated
- *    with one or more traces/spans. Since there can only be one parent
- *    SpanContext, Link is used to keep reference to SpanContext of all
- *    elements in the batch.
- * 2. Public Endpoint: A SpanContext in incoming client request on a public
- *    endpoint is untrusted from service provider perspective. In such case it
- *    is advisable to start a new trace with appropriate sampling decision.
- *    However, it is desirable to associate incoming SpanContext to new trace
- *    initiated on service provider side so two traces (from Client and from
- *    Service Provider) can be correlated.
- *
- * @since 1.0.0
- */
-interface Link {
-  /** The {@link SpanContext} of a linked span. */
-  context: SpanContext;
-  /** A set of {@link SpanAttributes} on the link. */
-  attributes?: SpanAttributes;
-  /** Count of attributes of the link that were dropped due to collection limits */
-  droppedAttributesCount?: number;
-}
-/**
- * An interface that represents a span. A span represents a single operation
- * within a trace. Examples of span might include remote procedure calls or a
- * in-process function calls to sub-components. A Trace has a single, top-level
- * "root" Span that in turn may have zero or more child Spans, which in turn
- * may have children.
- *
- * Spans are created by the {@link Tracer.startSpan} method.
- *
- * @since 1.0.0
- */
-interface Span {
-  /**
-   * Returns the {@link SpanContext} object associated with this Span.
-   *
-   * Get an immutable, serializable identifier for this span that can be used
-   * to create new child spans. Returned SpanContext is usable even after the
-   * span ends.
-   *
-   * @returns the SpanContext object associated with this Span.
-   */
-  spanContext(): SpanContext;
-  /**
-   * Sets an attribute to the span.
-   *
-   * Sets a single Attribute with the key and value passed as arguments.
-   *
-   * @param key the key for this attribute.
-   * @param value the value for this attribute. Setting a value null or
-   *              undefined is invalid and will result in undefined behavior.
-   */
-  setAttribute(key: string, value: SpanAttributeValue): this;
-  /**
-   * Sets attributes to the span.
-   *
-   * @param attributes the attributes that will be added.
-   *                   null or undefined attribute values
-   *                   are invalid and will result in undefined behavior.
-   */
-  setAttributes(attributes: SpanAttributes): this;
-  /**
-   * Adds an event to the Span.
-   *
-   * @param name the name of the event.
-   * @param [attributesOrStartTime] the attributes that will be added; these are
-   *     associated with this event. Can be also a start time
-   *     if type is {@type TimeInput} and 3rd param is undefined
-   * @param [startTime] start time of the event.
-   */
-  addEvent(name: string, attributesOrStartTime?: SpanAttributes | TimeInput, startTime?: TimeInput): this;
-  /**
-   * Adds a single link to the span.
-   *
-   * Links added after the creation will not affect the sampling decision.
-   * It is preferred span links be added at span creation.
-   *
-   * @param link the link to add.
-   */
-  addLink(link: Link): this;
-  /**
-   * Adds multiple links to the span.
-   *
-   * Links added after the creation will not affect the sampling decision.
-   * It is preferred span links be added at span creation.
-   *
-   * @param links the links to add.
-   */
-  addLinks(links: Link[]): this;
-  /**
-   * Sets the status of the span.
-   *
-   * By default, a span has status {@link SpanStatusCode.UNSET}.
-   * Calling this method overrides that default.
-   *
-   * The status codes have a total order: `OK > ERROR > UNSET`.
-   *
-   * - Once {@link SpanStatusCode.OK} is set, any further attempts to change
-   *   the status are ignored.
-   * - Any attempt to set {@link SpanStatusCode.UNSET} is always ignored.
-   *
-   * The `message` field is only used when {@link SpanStatusCode.ERROR} is set.
-   * For all other status codes, `message` is ignored.
-   *
-   * @param status The {@link SpanStatus} to set.
-   */
-  setStatus(status: SpanStatus): this;
-  /**
-   * Updates the Span name.
-   *
-   * This will override the name provided via {@link Tracer.startSpan}.
-   *
-   * Upon this update, any sampling behavior based on Span name will depend on
-   * the implementation.
-   *
-   * @param name the Span name.
-   */
-  updateName(name: string): this;
-  /**
-   * Marks the end of Span execution.
-   *
-   * Call to End of a Span MUST not have any effects on child spans. Those may
-   * still be running and can be ended later.
-   *
-   * Do not return `this`. The Span generally should not be used after it
-   * is ended so chaining is not desired in this context.
-   *
-   * @param [endTime] the time to set as Span's end time. If not provided,
-   *     use the current time as the span's end time.
-   */
-  end(endTime?: TimeInput): void;
-  /**
-   * Returns the flag whether this span will be recorded.
-   *
-   * @returns true if this Span is active and recording information like events
-   *     with the `AddEvent` operation and attributes using `setAttributes`.
-   */
-  isRecording(): boolean;
-  /**
-   * Sets exception as a span event
-   * @param exception the exception the only accepted values are string or Error
-   * @param [time] the time to set as Span's event time. If not provided,
-   *     use the current time.
-   */
-  recordException(exception: Exception, time?: TimeInput): void;
-}
-/**
- * @since 1.0.0
- */
-declare enum SpanKind {
-  /** Default value. Indicates that the span is used internally. */
-  INTERNAL = 0,
-  /**
-   * Indicates that the span covers server-side handling of an RPC or other
-   * remote request.
-   */
-  SERVER = 1,
-  /**
-   * Indicates that the span covers the client-side wrapper around an RPC or
-   * other remote request.
-   */
-  CLIENT = 2,
-  /**
-   * Indicates that the span describes producer sending a message to a
-   * broker. Unlike client and server, there is no direct critical path latency
-   * relationship between producer and consumer spans.
-   */
-  PRODUCER = 3,
-  /**
-   * Indicates that the span describes consumer receiving a message from a
-   * broker. Unlike client and server, there is no direct critical path latency
-   * relationship between producer and consumer spans.
-   */
-  CONSUMER = 4,
-}
-/**
- * Options needed for span creation
- *
- * @since 1.0.0
- */
-interface SpanOptions {
-  /**
-   * The SpanKind of a span
-   * @default {@link SpanKind.INTERNAL}
-   */
-  kind?: SpanKind;
-  /** A span's attributes */
-  attributes?: Attributes;
-  /** {@link Link}s span to other spans */
-  links?: Link[];
-  /** A manually specified start time for the created `Span` object. */
-  startTime?: TimeInput;
-  /** The new span should be a root span. (Ignore parent from context). */
-  root?: boolean;
-}
-/**
- * Tracer provides an interface for creating {@link Span}s.
- *
- * @since 1.0.0
- */
-interface Tracer {
-  /**
-   * Starts a new {@link Span}. Start the span without setting it on context.
-   *
-   * This method do NOT modify the current Context.
-   *
-   * @param name The name of the span
-   * @param [options] SpanOptions used for span creation
-   * @param [context] Context to use to extract parent
-   * @returns Span The newly created span
-   * @example
-   *     const span = tracer.startSpan('op');
-   *     span.setAttribute('key', 'value');
-   *     span.end();
-   */
-  startSpan(name: string, options?: SpanOptions, context?: Context): Span;
-  /**
-   * Starts a new {@link Span} and calls the given function passing it the
-   * created span as first argument.
-   * Additionally the new span gets set in context and this context is activated
-   * for the duration of the function call.
-   *
-   * @param name The name of the span
-   * @param [options] SpanOptions used for span creation
-   * @param [context] Context to use to extract parent
-   * @param fn function called in the context of the span and receives the newly created span as an argument
-   * @returns return value of fn
-   * @example
-   *     const something = tracer.startActiveSpan('op', span => {
-   *       try {
-   *         do some work
-   *         span.setStatus({code: SpanStatusCode.OK});
-   *         return something;
-   *       } catch (err) {
-   *         span.setStatus({
-   *           code: SpanStatusCode.ERROR,
-   *           message: err.message,
-   *         });
-   *         throw err;
-   *       } finally {
-   *         span.end();
-   *       }
-   *     });
-   *
-   * @example
-   *     const span = tracer.startActiveSpan('op', span => {
-   *       try {
-   *         do some work
-   *         return span;
-   *       } catch (err) {
-   *         span.setStatus({
-   *           code: SpanStatusCode.ERROR,
-   *           message: err.message,
-   *         });
-   *         throw err;
-   *       }
-   *     });
-   *     do some more work
-   *     span.end();
-   */
-  startActiveSpan<F extends (span: Span) => unknown>(name: string, fn: F): ReturnType<F>;
-  startActiveSpan<F extends (span: Span) => unknown>(name: string, options: SpanOptions, fn: F): ReturnType<F>;
-  startActiveSpan<F extends (span: Span) => unknown>(name: string, options: SpanOptions, context: Context, fn: F): ReturnType<F>;
-}
 interface OtelPluginOptions {
   /**
   * Rename incoming `project:target` IDs before they become OTel
@@ -1735,9 +1649,16 @@ declare const findVisTaskConfigFile: (projectDirectory: string) => string | unde
 *
 * Falls back to secure defaults if no config file is found.
 * @param workspaceRoot The workspace root directory to search for the config file.
+* @param options Optional loader options.
+* @param options.explicitConfigPath Overrides discovery — used by the
+* global `--config` flag so users can point at any file regardless of
+* cwd. The path must exist; otherwise an error is thrown so the
+* config-loader plugin can surface it to the user.
 * @returns The loaded and resolved configuration with secure defaults applied.
 */
-declare const loadVisConfig: (workspaceRoot: string) => Promise<VisConfig>;
+declare const loadVisConfig: (workspaceRoot: string, options?: {
+  explicitConfigPath?: string;
+}) => Promise<VisConfig>;
 /**
 * Load the per-package `vis.task.ts` overlay for a project, if any.
 *