@visulima/vis 1.0.0-alpha.2 → 1.0.0-alpha.20

package/dist/config/index.d.ts

@@ -0,0 +1,2795 @@
+import { TargetConfiguration, TaskResult, Task, FingerprintContributor, ConstraintsConfig, NamedInputs, TaskRunnerOptions } from '@visulima/task-runner';
+export { type FingerprintContributor } from '@visulima/task-runner';
+import { Hookable } from 'hookable';
+/**
+* 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 {
+  /**
+  * When a tool pin doesn't match the running version, try to fix it
+  * automatically before `vis run` / `vis ci` proceed. Defaults to
+  * `true` when {@link findInstalledManagers} reports at least one
+  * installed manager, `false` otherwise.
+  *
+  * Set to `false` to keep the doctor-style warning behaviour and
+  * make users run `vis toolchain install` themselves.
+  */
+  readonly autoInstall?: boolean;
+  /** Explicit manager override, useful in CI. */
+  readonly preferredManager?: VersionManagerName;
+  /** Overrides for engines/packageManager-derived pins. */
+  readonly tools?: Partial<Record<RuntimeTool, string>>;
+}
+/**
+* Custom task form — `{ title, task }` — analogous to lint-staged's
+* listr-style task objects. `task` receives the matched absolute paths
+* and returns a promise that resolves on success or rejects on failure.
+*/
+interface CustomTask {
+  readonly task: (files: string[]) => unknown;
+  readonly title: string;
+}
+/**
+* A task value as authored by the user. Command strings are split into
+* argv and invoked with the matched file paths appended. Arrays run
+* serially. Functions receive the matched paths and return further
+* task values (possibly async). `{ title, task }` objects run `task`
+* directly with no argv construction.
+*/
+type StagedTask = CustomTask | StagedTaskFunction | ReadonlyArray<CustomTask | StagedTaskFunction | string> | string | ReadonlyArray<string>;
+type StagedTaskFunction = (files: string[]) => Promise<StagedTaskResult> | StagedTaskResult;
+type StagedTaskResult = CustomTask | ReadonlyArray<CustomTask | string> | string | ReadonlyArray<string>;
+/**
+* Config object mapping glob patterns (basename or path-style) to tasks.
+* A top-level function form lets the user generate the entire config
+* from the staged file list.
+*/
+type StagedConfig = Readonly<Record<string, StagedTask>> | StagedConfigFunction;
+type StagedConfigFunction = (files: string[]) => Promise<Record<string, StagedTask>> | Record<string, StagedTask>;
+/**
+* Configuration block declared on a target to mark it as a long-lived
+* "service" — eligible to be started/stopped via `vis service` and
+* auto-attached when other tasks depend on it.
+*
+* Targets must also carry `preset: "server"` (or the equivalent
+* `persistent: true`) for the service-mode lifecycle to apply.
+*/
+interface ServiceConfig {
+  /**
+  * Env vars to expose to dependent tasks when this service is
+  * registered. Merged into the dependent task's env after the task's
+  * own envFile and before the task's explicit `env` overrides — the
+  * dependent task wins on key collisions.
+  *
+  * Note: only this `env` map propagates to dependents. The service
+  * target's own `envFile` is loaded into the **service process** at
+  * start time but is *not* forwarded — dependents must declare any
+  * shared values they need either here or in their own envFile. This
+  * boundary is intentional: envFiles often contain operator-only
+  * secrets (deploy keys, admin tokens) that should not leak into
+  * downstream test commands.
+  */
+  env?: Record<string, string>;
+  /**
+  * Grace period in milliseconds between SIGTERM and SIGKILL when the
+  * service is stopped.
+  * @default 5000
+  */
+  killGracePeriodMs?: number;
+  /**
+  * Optional port the service listens on. Used as the default for
+  * `readiness.tcp.port` when no explicit probe is configured, and
+  * surfaced by `vis service list`.
+  */
+  port?: number;
+  /** Readiness probe configuration. v1 supports TCP only. */
+  readiness?: {
+    tcp: {
+      host?: string;
+      port: number;
+      timeoutMs?: number;
+    };
+  };
+}
+/**
+* Persisted registry entry. One JSON file per running service in
+* `~/.vis-services/&lt;workspaceHash>/&lt;slug>.json`.
+*/
+interface ServiceEntry {
+  /** Resolved command actually spawned. Used for stale-PID detection. */
+  command: string;
+  /** Service config captured at start time. */
+  config: ServiceConfig;
+  cwd: string;
+  /**
+  * Env vars to forward to dependents. Resolved at start time —
+  * defaults to `config.env`, but a future `--env-from` flag could
+  * extend this without touching the registry consumer.
+  */
+  env: Record<string, string>;
+  /** Target id, e.g. `apps/api:db`. */
+  id: string;
+  /** Absolute path to the captured stdout/stderr log file. */
+  logFile: string;
+  pid: number;
+  /**
+  * Filesystem-safe slug of `id`. `apps/api:db` → `apps_api__db`.
+  * Used as the entry's filename so registry reads can map slug → entry.
+  */
+  slug: string;
+  /** ISO 8601 timestamp of when the service was started. */
+  startedAt: string;
+  /**
+  * vis version that started this service. Auto-attach refuses entries
+  * from a mismatched version — protects against schema drift.
+  */
+  visVersion: string;
+}
+/**
+* Semantic classification for a target.
+* - `build`: Generates one or more artifacts; cached by default.
+* - `test`: Validation task (lint, typecheck, unit test). Default type.
+* - `run`: One-off or long-running process. Not cached by default.
+*/
+type TargetType = "build" | "run" | "test";
+/**
+* Preset bundles of target options.
+* - `server`: Long-running local dev server — caching off, not in CI,
+*   interactive, persistent.
+* - `utility`: Short-lived helper — caching off, not in CI.
+*/
+type TargetPreset = "server" | "utility";
+/**
+* Controls whether a target runs in CI.
+* - `true` (default): Always run.
+* - `false`: Never run in CI (local-only).
+* - `"affected"`: Only when the project is affected by the current change set.
+* - `"always"`: Always run, even if unaffected.
+*/
+type RunInCI = "affected" | "always" | boolean;
+/**
+* Controls how affected files are forwarded to a task.
+* - `false` (default): Do not forward.
+* - `"args"`: Append affected paths as additional command arguments.
+* - `"env"`: Expose them via `VIS_AFFECTED_FILES` environment variable.
+* - `"both"`: Both of the above.
+*/
+type AffectedFilesMode = "args" | "both" | "env" | false;
+/**
+* Vis-specific target options that extend the task-runner's
+* base `TargetConfiguration`. These live under `target.options` and are
+* interpreted by vis before handing the task off to task-runner.
+*
+* Conditional execution (`when:`) and finally tasks (`always:`) live at
+* the target top level, not under `options` — they're handled by the
+* task-runner orchestrator. See `@visulima/task-runner`'s `WhenCondition`.
+*/
+interface VisTargetOptions {
+  /**
+  * How to forward affected files to the task process.
+  * Only used when invoked via `vis affected &lt;target>`.
+  * @default false
+  */
+  affectedFiles?: AffectedFilesMode;
+  /**
+  * Load environment variables from dotenv file(s) before running.
+  * - `string`: a single file path (relative to project root).
+  * - `string[]`: multiple files — later entries override earlier ones,
+  *   so put more-specific files last (e.g. `[".env", ".env.local"]`).
+  * - `true`: auto-cascade in the Next/Vite order:
+  *   `.env` → `.env.{NODE_ENV}` → `.env.local` → `.env.{NODE_ENV}.local`.
+  *   Skips `.env.local` when NODE_ENV is `test`, matching Next.js.
+  */
+  envFile?: boolean | string | string[];
+  /**
+  * 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.
+  * @default false
+  */
+  interactive?: boolean;
+  /**
+  * When true, the task is hidden from CLI listings and can only be invoked
+  * as a dependency of another task.
+  * @default false
+  */
+  internal?: boolean;
+  /**
+  * Milliseconds the timeout watchdog waits between sending SIGTERM
+  * and SIGKILL when the `timeout` budget fires. Tasks that ignore
+  * SIGTERM (e.g. test runners holding open child processes) get
+  * force-killed after this grace window so a stuck task can't outlive
+  * its budget.
+  *
+  * Set to `0` to skip escalation and rely on SIGTERM only.
+  * @default 5000
+  */
+  killGracePeriodMs?: number;
+  /**
+  * Serializes all tasks that share the same mutex name. Useful for tasks
+  * that contend on a shared resource (e.g., a database migration).
+  */
+  mutex?: string;
+  /**
+  * Per-target output verbosity. Overrides the global `--output-style`
+  * flag for this specific target.
+  *
+  * - `"normal"` (default): print every task's terminal output
+  * - `"quiet"`: only print output when the task fails. Successful
+  *   and cached tasks contribute their status line and timing, but
+  *   their captured stdout/stderr is suppressed.
+  *
+  * Useful when a routinely-noisy task (a linter or test runner with
+  * verbose progress output) should stay quiet during green builds
+  * but reveal everything when it fails.
+  */
+  outputStyle?: "normal" | "quiet";
+  /**
+  * When true, the task is a long-running / never-ending process.
+  * Persistent tasks are scheduled last, execute after all cacheable
+  * tasks complete, and are never cached.
+  * @default false
+  */
+  persistent?: boolean;
+  /**
+  * A preset that pre-fills a common bundle of options.
+  * User-provided fields always take precedence over the preset.
+  */
+  preset?: TargetPreset;
+  /**
+  * Run the task through a pseudo-terminal so color-aware tools
+  * (vitest, eslint, biome, …) render as if attached to a real TTY
+  * instead of a pipe. Output is captured via task-runner's
+  * `TerminalBuffer` so ANSI escapes are normalized into the final
+  * rendered state before reaching the reporter.
+  *
+  * Forces cache to off — PTY output can include timing-dependent
+  * frames (spinners) that aren't safe to replay from a cache.
+  * @default false
+  */
+  pty?: boolean;
+  /**
+  * Number of times to retry the task on failure. Uses an exponential
+  * backoff by default (1s, 2s, 4s, ...).
+  * @default 0
+  */
+  retryCount?: number;
+  /**
+  * Delay between retry attempts in milliseconds, or `"exponential"`
+  * for 2^attempt * 1000 ms.
+  * @default "exponential"
+  */
+  retryDelay?: number | "exponential";
+  /**
+  * When true, the command executes with the workspace root as CWD
+  * instead of the project root.
+  * @default false
+  */
+  runFromWorkspaceRoot?: boolean;
+  /**
+  * Controls whether the task runs in CI environments.
+  * @default true
+  */
+  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 &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).
+  *
+  * The presence of this block — not `preset: "server"` alone — is
+  * what makes a target eligible for the cross-invocation registry.
+  * `preset: "server"` without `service` keeps today's in-run-only
+  * behaviour.
+  */
+  service?: ServiceConfig;
+  /**
+  * Per-target shell override. When set, the command runs through this
+  * shell instead of the platform default.
+  */
+  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.
+  *
+  * When the timeout fires the task is sent SIGTERM and, if it has
+  * not exited within `killGracePeriodMs`, SIGKILL. The task exits
+  * with a failure status carrying the `[timeout]` marker in
+  * `terminalOutput`. Retries count per-attempt, not cumulatively.
+  *
+  * Use this to prevent runaway tasks from eating CI wall-clock time
+  * up to the job-level cutoff.
+  */
+  timeout?: number;
+  /**
+  * Per-target unix shell override, used on Linux and macOS.
+  * Takes precedence over `shell` on unix-like systems.
+  */
+  unixShell?: string;
+  /**
+  * Per-target windows shell override, used on Windows.
+  * Takes precedence over `shell` on Windows.
+  */
+  windowsShell?: string;
+}
+/**
+* An extended target configuration that adds the vis-specific options
+* on top of task-runner's `TargetConfiguration`.
+*/
+interface VisTargetConfiguration extends Omit<TargetConfiguration, "options"> {
+  /**
+  * Alternate names that resolve to this target on the CLI. Useful
+  * for shortening long canonical names (`test` ↔ `t`) or for
+  * offering migration-friendly aliases when renaming targets.
+  * Aliases must be globally unique within the workspace.
+  */
+  aliases?: string[];
+  /**
+  * One-line description surfaced by `vis list` and (in future)
+  * per-task `--help`. Kept short — longer docs belong in project
+  * READMEs or vis.config.ts comments.
+  */
+  description?: string;
+  /**
+  * True when the target was synthesized by a Project Crystal-style
+  * detector (see {@link ../inference}) rather than declared by a
+  * package.json script, project.json, or vis.task.ts file. Surfaced
+  * by `vis list --inferred` and used by tooling to distinguish
+  * implicit defaults from explicit user intent.
+  */
+  inferred?: boolean;
+  /** Vis-specific target options. */
+  options?: VisTargetOptions;
+  /** Preset applied before user-specified options. */
+  preset?: TargetPreset;
+  /**
+  * Semantic task type. Affects caching defaults and CI filtering.
+  * @default "test"
+  */
+  type?: TargetType;
+}
+/**
+* Typed hook surface exposed to vis plugins.
+*
+* Plugins subscribe via `hooks.hook(name, handler)` — handlers are
+* awaited sequentially in registration order. Returning a promise
+* delays the next hook firing until it resolves, so plugins can
+* safely perform async setup/teardown.
+*
+* Naming deliberately mirrors vite-task / webpack-style verbs:
+*   before/after for boundaries, on&lt;Event> for passive observation.
+*/
+interface VisHooks {
+  /**
+  * Fired after the entire task graph completes (including any
+  * failures). `results` maps task ID → {@link TaskResult}.
+  */
+  "run:after": (results: Map<string, TaskResult>) => Promise<void> | void;
+  /**
+  * Fired once before any task in the graph starts, after workspace
+  * discovery and graph construction. Throwing aborts the run.
+  */
+  "run:before": (context: {
+    tasks: Task[];
+    workspaceRoot: string;
+  }) => Promise<void> | void;
+  /**
+  * Fired after `vis run` auto-attaches to one or more registered
+  * services. `taskIds` lists the in-graph dependents that consumed
+  * the service's `env` block; an empty array means the service was
+  * registered but no kept task depended on it.
+  */
+  "service:attach": (entry: ServiceEntry, taskIds: ReadonlyArray<string>) => Promise<void> | void;
+  /**
+  * Fired after a service is registered and its readiness probe
+  * succeeds. Sourced from both `vis service start` (and `restart`'s
+  * post-start phase) and any future programmatic call sites.
+  */
+  "service:start": (entry: ServiceEntry) => Promise<void> | void;
+  /**
+  * Fired after a registered service is stopped (SIGTERM/SIGKILL
+  * acknowledged, registry entry deleted). Not fired when stop is
+  * called against an unknown id — only when there was an alive
+  * entry to terminate.
+  */
+  "service:stop": (entry: ServiceEntry) => Promise<void> | void;
+  /**
+  * Fired after a task completes (success, failure, or cache hit).
+  * Receives the final {@link TaskResult}.
+  */
+  "task:after": (task: Task, result: TaskResult) => Promise<void> | void;
+  /**
+  * Fired before each task begins execution — after scheduling, before
+  * the executor runs the command. Throwing aborts that single task.
+  */
+  "task:before": (task: Task) => Promise<void> | void;
+  /** Fired when a task hit the local or remote cache. */
+  "task:cacheHit": (task: Task, result: TaskResult) => Promise<void> | void;
+  /**
+  * Fired when auto-fingerprint cache diagnostics reports a miss,
+  * carrying the human-readable reason string.
+  */
+  "task:cacheMiss": (task: Task, reasons: string) => Promise<void> | void;
+  /** Fired when a task exits non-zero. */
+  "task:failure": (task: Task, result: TaskResult) => Promise<void> | void;
+  /**
+  * Fired during fingerprint construction, after built-in inputs are
+  * gathered and before the hash is sealed. Plugins call
+  * `contributor.contribute(key, value)` to mix arbitrary strings
+  * into the task hash — the hasher namespaces and sorts contributions
+  * deterministically so call order doesn't change the result.
+  *
+  * Throwing aborts hashing for the offending task and surfaces as a
+  * task failure before any cache lookup runs. Use this to guarantee
+  * a buggy plugin can't quietly poison cache state.
+  */
+  "task:fingerprint": (task: Task, contributor: FingerprintContributor) => Promise<void> | void;
+  /**
+  * Fired right before a failed task is re-spawned by the retry
+  * controller. `attempt` is 1-indexed and counts the retry that's
+  * about to start (so the original failed run was attempt 0).
+  * `prevExitCode` is the failing exit status that triggered the
+  * retry (the full TaskResult isn't materialized at the retry
+  * boundary — only the per-attempt close event is available).
+  *
+  * Throwing aborts the retry; the previous failure becomes the final
+  * result.
+  */
+  "task:retry": (task: Task, attempt: number, prevExitCode: number) => Promise<void> | void;
+  /**
+  * Fired with a stderr chunk as a running task emits it. Plugins
+  * that ship logs live (Slack, Datadog) should prefer this over
+  * `task:after` so they don't wait for the full buffer.
+  */
+  "task:stderr": (task: Task, chunk: string) => Promise<void> | void;
+  /**
+  * Fired with a stdout chunk as a running task emits it. See
+  * `task:stderr` for semantics.
+  */
+  "task:stdout": (task: Task, chunk: string) => Promise<void> | void;
+}
+/**
+* Public plugin contract. Implementations register handlers by
+* returning a partial {@link VisHooks} map from `hooks`, or by
+* mutating the Hookable instance directly via `setup(hooks)` for
+* advanced cases (dynamic registration, removeHook, etc.).
+*
+* Plugins are loaded in the order they appear in `visConfig.plugins`.
+* Handler execution order within a hook follows registration order,
+* so earlier plugins see events first.
+*/
+interface VisPlugin {
+  /**
+  * Declarative handlers — the common shape. One entry per hook
+  * name; pass a function or an array of functions (all run serially
+  * in order).
+  */
+  hooks?: Partial<{ [K in keyof VisHooks]: VisHooks[K] | VisHooks[K][] }>;
+  /** Plugin name — surfaced in debug logs. */
+  name: string;
+  /**
+  * Imperative setup — receives the shared Hookable instance so the
+  * plugin can register hooks conditionally, unregister later, or
+  * use advanced APIs like `hookOnce`/`beforeEach`/`afterEach`.
+  */
+  setup?: (hooks: Hookable<VisHooks>) => Promise<void> | void;
+}
+/**
+* The 8 Socket.dev-style supply-chain policies. Used in `security.policies`
+* and `security.acceptedRisks[*].policies`. Kept as a const tuple so callers
+* can import the runtime array (`POLICY_NAMES`) for iteration without
+* drifting from the union type.
+*/
+declare const POLICY_NAMES: readonly ["firstSeen", "installScripts", "license", "malware", "publisherChange", "score", "unexpectedDeps", "vulnerability"];
+type PolicyName = (typeof POLICY_NAMES)[number];
+/**
+* Recognised input sources for the codeowners aggregator.
+*
+* - `project-json` — owners declared on each project's `project.json`.
+*   Canonical source; takes precedence over the other two on path conflicts.
+* - `nested-codeowners` — `CODEOWNERS` files placed at arbitrary depth
+*   in the workspace tree (excluding the generated root file).
+* - `package-json-maintainers` — fallback that reads each project's
+*   `package.json#maintainers` and emits one entry per project root for
+*   projects with no `project.json owners`. GitHub handles are extracted
+*   from each maintainer's `url` (e.g. `https://github.com/&lt;handle&gt;`).
+*/
+type CodeownersSource = "nested-codeowners" | "package-json-maintainers" | "project-json";
+interface CodeownersConfig {
+  /** Markers that bracket the generated block when `preserveBlock` is set. */
+  blockMarker?: {
+    begin: string;
+    end: string;
+  };
+  /** Workspace-level paths that apply outside any project (e.g., `.github/**`). */
+  globalPaths?: Record<string, string[]>;
+  /** Glob patterns used to discover nested `CODEOWNERS` files. Defaults to `["**\/CODEOWNERS"]`. */
+  nestedIncludes?: string[];
+  /** Sort order for generated entries — mirrors moon's `orderBy`. */
+  orderBy?: "file-source" | "project-id";
+  /**
+  * When set, the generated content is spliced between
+  * {@link CodeownersConfig.blockMarker} markers in the existing file
+  * (markers are appended if missing) instead of overwriting the file.
+  */
+  preserveBlock?: boolean;
+  /** Provider determines whether `channel` is emitted (GitHub supports it via comment). */
+  provider?: "bitbucket" | "github" | "gitlab" | "other";
+  /**
+  * Header instruction shown to reviewers. Replaces the default
+  * "Update each project's project.json `owners` field…" line. Useful
+  * when the canonical regenerate path is a custom script.
+  */
+  regenerationCommand?: string;
+  /** Enabled input sources. Defaults to `["project-json"]`. */
+  sources?: CodeownersSource[];
+}
+/**
+* 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.
+*/
+interface OwnersEntry {
+  /** Optional notification channel (e.g. Slack, Teams). */
+  channel?: string;
+  /** Owner handles (e.g. `@visulima/core-team`). */
+  owners: string[];
+  /** File/glob pattern relative to the project root. */
+  path: string;
+}
+/**
+* Per-project TypeScript overlay loaded from `vis.task.ts`. Adds a
+* dynamic, type-safe layer for target overrides on top of `project.json`,
+* which stays the canonical home for static metadata (`tags`, `layer`,
+* `stack`, `language`, `owners`, `projectType`, `sourceRoot`,
+* `implicitDependencies`).
+*
+* `vis.task.ts` is opt-in. A package without one behaves identically to
+* before its introduction. Targets defined here merge over `project.json`'s
+* `targets` block — see `design-config-layering.md` for the full
+* precedence stack.
+*/
+interface VisTaskConfig {
+  /** Per-target overrides — same shape as `project.json#targets`. */
+  tasks?: Record<string, VisTargetConfiguration>;
+}
+/**
+* Per-project metadata surfaced by `project.json`. Extended beyond the
+* minimal `projectType` / `tags` / `sourceRoot` fields we historically
+* parsed to include targets, owners, and layer/stack classification.
+*/
+interface ProjectJson {
+  /** Implicit dependencies on other projects. */
+  implicitDependencies?: string[];
+  /** Primary language — informational and query-able. */
+  language?: string;
+  /** Project layer, used for constraint inheritance and query filtering. */
+  layer?: "application" | "automation" | "configuration" | "library" | "scaffolding" | "tool";
+  /** Code owners for paths inside this project. */
+  owners?: OwnersEntry[];
+  /** Project-level metadata. */
+  project?: {
+    channel?: string;
+    description?: string;
+    maintainers?: string[];
+    owner?: string;
+    title?: string;
+  };
+  /**
+  * Project type — `library`, `application`, `service`, or `tool`.
+  *
+  * - `library` — reusable code consumed by other workspace projects.
+  * - `application` — end-user-facing build target (web app, mobile app).
+  * - `service` — long-running HTTP / worker process deployed independently.
+  * - `tool` — CLI or developer tooling shipped as an executable.
+  */
+  projectType?: "application" | "library" | "service" | "tool";
+  /** Source root, used for display and language inference. */
+  sourceRoot?: string;
+  /** Tech stack. */
+  stack?: "backend" | "data" | "frontend" | "infrastructure" | "systems";
+  /** Filterable tags. */
+  tags?: string[];
+  /** Vis-style target definitions (merged on top of package.json scripts). */
+  targets?: Record<string, VisTargetConfiguration>;
+}
+/**
+* A predicate used by {@link VisConfig.scopedTasks}.
+* All listed constraints must match for the block to apply.
+*/
+interface ScopedTasksMatch {
+  /** Match on primary language. */
+  language?: string | string[];
+  /** Match on project layer. */
+  layer?: ProjectJson["layer"] | ProjectJson["layer"][];
+  /** Match on project type. */
+  projectType?: "application" | "library" | "service" | "tool";
+  /** Match on project stack. */
+  stack?: ProjectJson["stack"] | ProjectJson["stack"][];
+  /** Match projects tagged with any of these tags. */
+  tags?: string[];
+}
+/**
+* A single scoped-tasks block — a set of task defaults gated by an
+* optional match predicate.
+*/
+interface ScopedTasksBlock {
+  /** Optional match predicate; if omitted, the block applies universally. */
+  match?: ScopedTasksMatch;
+  /** Task default configurations, keyed by target name. */
+  tasks: Record<string, Partial<VisTargetConfiguration>>;
+}
+interface VisConfig {
+  /** AI analysis configuration */
+  ai?: {
+    /** Cache TTL in milliseconds. Overrides default (1h / 30min for security). */
+    cacheTtl?: number;
+    /** Override default provider priority. Higher number = preferred. */
+    priority?: Record<string, number>;
+    /** Use a specific provider instead of auto-detecting (e.g., `"claude"`, `"gemini"`). */
+    provider?: string;
+  };
+  /**
+  * 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 —
+  * generated artefacts (schemas, `.d.ts` snapshots) that legitimately
+  * differ across branches no longer oscillate the cache contents.
+  *
+  * Falls back to the unscoped path on detached HEAD, non-git
+  * workspaces, or when git isn't available.
+  * @default false
+  */
+  branchScopedCache?: boolean;
+  /**
+  * Code ownership configuration. Controls how `vis sync codeowners`
+  * renders the generated CODEOWNERS file.
+  */
+  codeowners?: CodeownersConfig;
+  /**
+  * Project dependency constraints.
+  * Enforced after building the project graph, before running tasks.
+  */
+  constraints?: ConstraintsConfig;
+  /**
+  * Configuration for the `vis create` scaffolding command.
+  * Controls template downloads (via giget), default options, and
+  * post-creation behavior.
+  */
+  create?: {
+    /**
+    * Authorization token for downloading private repository templates.
+    * Passed as Bearer token to the git host API.
+    * Can also be set via GIGET_AUTH, GITHUB_TOKEN, or GH_TOKEN environment variables.
+    */
+    auth?: string;
+    /**
+    * Default editor to configure after scaffolding.
+    * When set, `vis create` automatically generates editor config files.
+    * @example "vscode"
+    */
+    defaultEditor?: "vscode";
+    /**
+    * Default package manager for new standalone projects.
+    * When set, skips the PM selection prompt in interactive mode.
+    */
+    defaultPm?: "bun" | "npm" | "pnpm" | "yarn";
+    /**
+    * Default giget provider for `owner/repo` shorthand inputs.
+    * @default "github"
+    */
+    defaultProvider?: "bitbucket" | "github" | "gitlab" | "sourcehut";
+    /**
+    * Initialize a git repository after scaffolding standalone projects.
+    * @default false
+    */
+    gitInit?: boolean;
+    /**
+    * Install dependencies automatically after scaffolding.
+    * @default true
+    */
+    install?: boolean;
+    /**
+    * Prefer locally cached templates over re-downloading.
+    * Useful for offline development or slow connections.
+    * @default false
+    */
+    preferOffline?: boolean;
+    /**
+    * Custom template registry URL.
+    * When set, giget checks this registry for template metadata
+    * before falling back to direct provider resolution.
+    * Set to `false` to disable registry lookup entirely.
+    * @see https://github.com/unjs/giget#custom-registry
+    */
+    registry?: false | string;
+    /**
+    * Named template aliases for quick access.
+    * Maps short names to full giget source strings.
+    * @example
+    * ```
+    * templates: {
+    *   "react": "github:vitejs/vite/packages/create-vite/template-react-ts",
+    *   "lib": "github:my-org/lib-template",
+    *   "internal": "gitlab:company/templates/node-service",
+    * }
+    * ```
+    */
+    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`.
+  *
+  * Each entry is either:
+  * - a relative path (`./shared.config.ts`, `../shared.config.ts`) —
+  *   resolved against the file declaring `extends`;
+  * - an npm package name (`@acme/vis-preset`) — resolved via Node.js
+  *   module resolution from the consumer file.
+  *
+  * Absolute paths are rejected — they break across machines and CI.
+  * Cycles raise `VisConfigCycleError` during load.
+  * @example
+  * ```
+  * extends: ["@acme/vis-preset", "./shared/security.config.ts"]
+  * ```
+  */
+  extends?: string | string[];
+  /**
+  * Named file-group patterns, reusable from target `inputs` via the
+  * `@filegroup:&lt;name>` token. File groups are resolved relative to each
+  * project root at discovery time.
+  * @example
+  * ```
+  * fileGroups: {
+  *   sources: ["src/**\/*.ts", "!src/**\/*.test.ts"],
+  *   tests: ["**\/*.test.ts"],
+  * }
+  * ```
+  */
+  fileGroups?: Record<string, string[]>;
+  /**
+  * Configuration for the `vis generate` in-repo scaffolding command.
+  * Points at additional template directories beyond the defaults
+  * (`.vis/templates/` and `.moon/templates/`).
+  */
+  generator?: {
+    /**
+    * Authorization token forwarded to giget when fetching
+    * `git://`/`npm://` remote templates. Falls back to
+    * `GIGET_AUTH` / `GITHUB_TOKEN` / `GH_TOKEN` env vars.
+    */
+    auth?: string;
+    /**
+    * Prefer locally cached remote templates over re-downloading.
+    * Overridable per invocation via `--prefer-offline`.
+    * @default false
+    */
+    preferOffline?: boolean;
+    /**
+    * Extra directories to scan for templates. Each directory is
+    * checked for both native templates (`&lt;name>.ts`) and
+    * moon-format directories (containing `template.yml`).
+    * @example
+    * ```
+    * generator: {
+    *   templates: ["./tools/generators", "./packages/scaffolding/templates"],
+    * }
+    * ```
+    */
+    templates?: string[];
+  };
+  /**
+  * 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`
+  * wins per-key, so opting in never overrides existing setups.
+  *
+  * Built-in detectors and the targets they synthesize:
+  *
+  * - **App frameworks** — `nuxt` (build/dev/preview/generate),
+  *   `next` (build/dev/start), `remix` (build/dev/start), `astro`
+  *   (build/dev), `gatsby` (build/develop/serve), `docusaurus`
+  *   (build/start/serve).
+  * - **Bundlers** — `vite` (build/dev/preview), `rolldown` (build),
+  *   `tsdown` (build), `tsup` (build), `packem` (build), `rollup`
+  *   (build), `webpack` (build).
+  * - **Docs sites** — `vitepress` (docs:build/docs:dev/docs:preview),
+  *   `typedoc` (docs).
+  * - **Server frameworks** — `nest` (build/start/start:dev).
+  * - **Test runners** — `vitest` (test/test:watch), `jest`
+  *   (test/test:watch), `bun` (test), `playwright` (test:e2e),
+  *   `cypress` (test:e2e/cypress:open).
+  * - **Stories** — `storybook` (storybook/build-storybook).
+  * - **Type checking** — `typescript` (typecheck via `tsc --noEmit`).
+  * - **Lint / format** — `eslint` (lint), `prettier` (format /
+  *   format:check), `biome` (lint, format), `oxlint` (lint),
+  *   `oxfmt` (format / format:check), `stylelint` (lint:css),
+  *   `knip` (knip).
+  * - **Runtimes** — `deno` (test/lint/fmt/check).
+  * - **Database tooling** — `prisma` (db:generate/db:migrate/
+  *   db:push/db:studio), `drizzle` (db:generate/db:migrate/
+  *   db:push/db:studio).
+  * - **Codegen / release** — `graphql-codegen` (codegen),
+  *   `api-extractor` (api-extract), `changeset` (changeset:version /
+  *   changeset:publish / changeset:status).
+  *
+  * Trigger: presence of any matching config file in the project root.
+  * Most detectors additionally match when their framework appears in
+  * `dependencies` / `devDependencies` / `peerDependencies` /
+  * `optionalDependencies` — covering convention-only setups (e.g.
+  * vitest with default config). Detectors that intentionally require
+  * a config file (because the package frequently appears transitively
+  * and a dep-only match would synthesize broken commands): `vite`,
+  * `rolldown`, `rollup`, `webpack`, `storybook`, `nest`, `remix`,
+  * `vitepress`, `bun`, `deno`, `changeset`.
+  *
+  * Conflict resolution: detectors are evaluated in registration order
+  * (see `BUILT_IN_DETECTORS`) and the first to claim a target name
+  * wins. Per-name priorities: `build` → nuxt > next > remix > astro
+  * > gatsby > docusaurus > vite > nest > rolldown > tsdown > tsup >
+  * packem > rollup > webpack; `test` → vitest > jest > bun > deno;
+  * `test:e2e` → playwright > cypress; `lint` → eslint > biome >
+  * oxlint > deno; `format` → prettier > biome > oxfmt; `db:*` →
+  * prisma > drizzle.
+  *
+  * Also accepts an object form (`{ vite: false, vitest: true }`) to
+  * opt individual detectors in or out by name. Detectors omitted from
+  * the object run at their default (enabled). Useful when one
+  * detector misfires for a given workspace without disabling the rest.
+  * @default false
+  */
+  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;
+  };
+  /**
+  * `vis-mcp` promotion notice shown after successful commands when an
+  * AI CLI (Claude Code, Cursor, Windsurf, Continue, Zed, Cline) is
+  * installed but `@visulima/vis-mcp` is not wired into its config.
+  *
+  * Shown at most once every 14 days; skipped in CI, non-TTY shells,
+  * during `--help`/`--version`/`ai`/`mcp` invocations, and when
+  * `VIS_NO_MCP_PROMOTE=1` is set. Set `enabled: false` to silence
+  * permanently for this workspace.
+  * @example
+  * ```
+  * mcpPromote: { enabled: false }
+  * ```
+  */
+  mcpPromote?: {
+    /**
+    * Show the vis-mcp promotion notice on successful command completion.
+    * @default true
+    */
+    enabled?: boolean;
+  };
+  /**
+  * Named input patterns inherited by every project target. Equivalent
+  * to task-runner's `namedInputs` but configurable from the vis config.
+  */
+  namedInputs?: NamedInputs;
+  /** Package override mappings applied during migration (e.g., `{ "lodash": "lodash-es" }`) */
+  overrides?: Record<string, string>;
+  /**
+  * Plugins — each plugin registers typed hooks that fire at run /
+  * task / cache boundaries. See {@link VisPlugin} for the contract.
+  * Prefer plugins over per-target shell hooks when behaviour needs
+  * access to task metadata, results, or cache state.
+  */
+  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.
+  */
+  preflight?: {
+    /**
+    * Detect "lockfile changed but `node_modules` is stale" before
+    * running tasks. Compares lockfile mtime against the
+    * package-manager-specific install marker
+    * (`node_modules/.modules.yaml` for pnpm, `.package-lock.json`
+    * for npm, etc.). Warns in TTY, hard-fails in CI.
+    * @default true
+    */
+    lockfile?: boolean;
+  };
+  /**
+  * Behavior of `vis run` when invoked tasks declare service dependencies
+  * that aren't running in the workspace registry. CLI `--services=&lt;mode>`
+  * overrides this block.
+  */
+  run?: {
+    /**
+    * Wrap each task's CI log block in collapsible groups so users
+    * can fold/unfold per-task output in the host CI's web UI.
+    * Failed tasks always render expanded so the failure is visible
+    * without an extra click.
+    *
+    * - `auto` (default): pick the format from the detected runner —
+    *   `GITHUB_ACTIONS=true` → `github` (`::group::`),
+    *   `GITLAB_CI=true` → `gitlab` (`section_start:` ANSI sequences),
+    *   `BUILDKITE=true` → `buildkite` (`---` collapsed headers),
+    *   `TF_BUILD=True` → `azure` (`##[group]`),
+    *   no grouping otherwise.
+    * - `off`: never group (raw separators only — useful when
+    *   piping through tools that mangle the directives).
+    * - `azure` / `buildkite` / `github` / `gitlab`: force the format
+    *   regardless of detected environment (useful for self-hosted
+    *   runners that don't set the standard env vars).
+    *
+    * CircleCI is intentionally not auto-detected: its 2.0+ format
+    * has no inline grouping directive — steps auto-group in the
+    * web UI without any markup from the runner.
+    */
+    ciGrouping?: "auto" | "azure" | "buildkite" | "github" | "gitlab" | "off";
+    /**
+    * One knob controlling auto-start of missing service deps.
+    * - `auto` (default in TTY): pick by task — `dev` → ephemeral,
+    *   others → persistent.
+    * - `ephemeral`: services die with the run (no registry entry).
+    * - `persistent`: services persist across runs in the registry.
+    * - `off` (default in CI / non-TTY): print diagnostics and abort.
+    */
+    services?: "auto" | "ephemeral" | "off" | "persistent";
+  };
+  /**
+  * Cascading scoped-task blocks. Each block may narrow its tasks to a
+  * subset of projects via `match`. Blocks are evaluated in order; later
+  * blocks override earlier ones when the same field is set.
+  *
+  * Match predicates are additive — if `match` is omitted, the block applies
+  * to every project.
+  * @example
+  * ```
+  * scopedTasks: [
+  *   { match: { tags: ["frontend"] }, tasks: { build: { cache: true } } },
+  *   { match: { projectType: "library" }, tasks: { lint: { cache: true } } },
+  * ]
+  * ```
+  */
+  scopedTasks?: ScopedTasksBlock[];
+  /**
+  * Default options for `vis secrets`. CLI flags always take precedence;
+  * this block provides workspace-wide defaults so teams can commit config
+  * once and every invocation picks it up.
+  */
+  secrets?: {
+    /** Path to a baseline of previously-triaged findings (relative to workspace root). */
+    baseline?: string;
+    /** Where the ruleset comes from. Omit for the bundled gitleaks default. */
+    config?: {
+      /** Layer the user's rules on top of the bundled ruleset. Default: `true`. */
+      extendBundled?: boolean;
+      /** Inline rule overrides. Wins over `path` when both are set. */
+      inline?: {
+        allowlist?: unknown;
+        allowlists?: unknown[];
+        description?: string;
+        rules?: unknown[];
+        title?: string;
+      };
+      /** Path to a JSON config (gitleaks-compatible). */
+      path?: string;
+      /** Bundled presets layered on top of the default ruleset (e.g. `"weak-passwords"`). */
+      presets?: string[];
+    };
+    /** Redact secret values in findings. */
+    redact?: boolean;
+    /** Rule-id filters applied after scanning. */
+    rules?: {
+      /** Drop findings whose ruleId matches. */
+      exclude?: string[];
+      /** Only report findings whose ruleId matches. */
+      include?: string[];
+    };
+    /** Walker / filesystem traversal. */
+    walk?: {
+      /**
+      * Paths to additional `.gitignore`-syntax files (e.g. `.secretsignore`).
+      */
+      excludeFromFiles?: string[];
+      /**
+      * Gitignore-syntax patterns (supports negation, directory markers, leading `/`).
+      * Applied on top of `.gitignore`.
+      */
+      excludePatterns?: string[];
+      /** Respect `.gitignore`. Default: `true`. */
+      gitignore?: boolean;
+      /** Include hidden (dotfile) entries. Default: `false`. */
+      includeHidden?: boolean;
+      /** Max file size in bytes. Default 10 MiB. */
+      maxFileSize?: number;
+    };
+  };
+  /**
+  * Supply chain security settings.
+  * These settings are inspired by pnpm's security features and are applied
+  * universally across all package managers (pnpm, npm, yarn, bun).
+  *
+  * For pnpm users: these map directly to pnpm-workspace.yaml settings.
+  * For npm/yarn/bun users: vis enforces these at the vis layer since
+  * those package managers lack native support.
+  */
+  security?: {
+    /**
+    * Packages whose policy findings have been reviewed and explicitly
+    * accepted. Matched against every policy unless `policies` narrows the
+    * scope. Replaces the legacy `security.socket.acceptedRisks` map.
+    *
+    * Key format: package name (`"lodash"`), name@version
+    * (`"lodash@4.17.21"`), or glob (`"@myorg/*"`). Unversioned keys match
+    * all versions of that package.
+    * @example
+    * ```
+    * acceptedRisks: {
+    *   "some-risky-pkg": {
+    *     reason: "Internal fork, low score expected",
+    *     acceptedAt: "2026-03-15T10:00:00Z",
+    *     acceptedScore: 0.25,
+    *     policies: ["score"],
+    *     expiresAt: "2026-12-31",
+    *   },
+    * }
+    * ```
+    */
+    acceptedRisks?: Record<string, {
+      /** ISO 8601 timestamp when the risk was accepted. */
+      acceptedAt: string;
+      /**
+      * The overall Socket.dev score at the time of acceptance,
+      * in the range `[0, 1]` (mirrors `policies.score.minimum`).
+      * Only relevant for the `score` policy; ignored elsewhere.
+      */
+      acceptedScore?: number;
+      /**
+      * ISO 8601 date (or datetime). After this point the acceptance
+      * stops applying and vis emits a warning. Leave undefined for
+      * non-expiring entries. Values that fail to parse as a Date
+      * are rejected by the loader rather than silently treated as
+      * "always expired".
+      */
+      expiresAt?: string;
+      /**
+      * Which policies this acceptance covers. When undefined the
+      * acceptance applies to every policy finding on this package.
+      */
+      policies?: PolicyName[];
+      /** User-provided reason for accepting the risk. */
+      reason: string;
+    }>;
+    /**
+    * Map of bin names (or `pkg#bin` qualifiers) blessed for shadowing.
+    * When two installed packages expose the same bin name, vis flags
+    * the collision in `vis security list` and the post-install drift
+    * report — set the bin (or `pkg#bin`) to `true` here to suppress
+    * the warning once you've reviewed the conflict.
+    *
+    * Port of LavaMoat allow-scripts' experimental `allowBins`.
+    * Bare names match any conflicting bin with that name; the
+    * `pkg#bin` form scopes the approval to a single package's bin.
+    * @example
+    * ```
+    * allowBins: {
+    *   tsc: true,                // bless any 'tsc' bin
+    *   "typescript#tsc": true,   // bless only typescript's 'tsc'
+    * }
+    * ```
+    */
+    allowBins?: Record<string, boolean>;
+    /**
+    * Offline OSV advisory + `vis audit` configuration.
+    *
+    * Controls `vis audit --offline` and `vis advisories sync` behavior:
+    * - `audit.advisories.source` is the OSV mirror to download from. It
+    *   must be `https://` and resolve to a host in `allowedHosts` (or one
+    *   of the built-in defaults).
+    * - `audit.offlineByDefault` flips the default of `--offline`.
+    *
+    * Vulnerability severity gating and reachability filtering live under
+    * `policies.vulnerability` (see below).
+    */
+    audit?: {
+      /**
+      * Offline advisory cache settings.
+      */
+      advisories?: {
+        /**
+        * Extra hosts permitted as `audit.advisories.source`. The
+        * built-in allowlist is enforced even if this field is
+        * omitted; entries here add to it.
+        * @example ["mirror.corp.example.com"]
+        */
+        allowedHosts?: string[];
+        /**
+        * Number of hours after `lastSyncIso` before `vis audit`
+        * prints a "your advisory cache may be stale" notice.
+        * `vis audit` never auto-syncs — the user runs
+        * `vis advisories sync` themselves.
+        * @default 24
+        */
+        refreshIntervalHours?: number;
+        /**
+        * OSV mirror base URL (no trailing slash). Defaults to the
+        * public Google Cloud Storage bucket. Override to point at a
+        * corporate mirror; the hostname must appear in `allowedHosts`
+        * (or one of the built-in defaults) and the scheme must be
+        * `https://`.
+        * @default "https://osv-vulnerabilities.storage.googleapis.com"
+        */
+        source?: string;
+        /**
+        * Sigstore signature verification for the OSV dump.
+        * Requires the native binding to be built with the
+        * `verify-signatures` Cargo feature (default in the release
+        * build). Off by default — the upstream OSV bucket does not
+        * ship signatures today.
+        */
+        verify?: {
+          /**
+          * Enable signature verification. The sync flow downloads
+          * `&lt;eco>/all.zip.sig` next to the zip and aborts if it
+          * cannot verify against `expectedIssuer` / `expectedSubject`.
+          * @default false
+          */
+          enabled?: boolean;
+          /** OIDC issuer that signed the bundle. */
+          expectedIssuer?: string;
+          /** OIDC subject (workload identity) that signed the bundle. */
+          expectedSubject?: string;
+        };
+      };
+      /**
+      * Gates for the auto-fix flow (`vis audit --fix` /
+      * `--fix-transitive`). The CLI prompts outside CI; inside CI
+      * the flags refuse to run unless `--yes` is set and, for
+      * transitives, `apply.transitive.enabled = true`.
+      */
+      apply?: {
+        /**
+        * Gates for `vis audit --fix-transitive`. Two-lock: the
+        * CLI requires `--yes` AND this flag set to `true` before
+        * it will rewrite override entries in CI.
+        */
+        transitive?: {
+          /**
+          * When true, allows `--fix-transitive` to run in CI
+          * environments. Defaults to false because rewriting
+          * overrides is a higher blast radius than bumping a
+          * direct dep.
+          * @default false
+          */
+          enabled?: boolean;
+        };
+      };
+      /**
+      * When true, `vis audit` skips network calls and queries the
+      * offline cache. Equivalent to the CLI `--offline` flag.
+      * @default false
+      */
+      offlineByDefault?: boolean;
+    };
+    /**
+    * When true, prevents transitive dependencies from using exotic sources
+    * (git repositories, direct tarball URLs). Only direct dependencies may
+    * use such sources. Equivalent to pnpm's `blockExoticSubdeps`.
+    * @default false
+    */
+    blockExoticSubdeps?: boolean;
+    /**
+    * Pre-install marshall pipeline — packument-derived supply-chain
+    * gates (author, provenance, new-bin, metadata, downloads,
+    * expired-domains, signatures, archived-repo) that run before
+    * `vis add` / `vis install &lt;pkg>` / `vis update &lt;pkg>` hand off to
+    * the underlying package manager. Every entry is optional; omit a
+    * key and the marshall runs with defaults. Set `enabled: false`
+    * on a specific marshall to skip it without touching env vars.
+    */
+    marshalls?: {
+      /** Archived-repo marshall (GitHub repository status). */
+      archivedRepo?: {
+        /** Package names to skip. */
+        allowlist?: string[];
+        /** Default: marshall is on. Set false to disable. */
+        enabled?: boolean;
+        /** GitHub PAT for the API call (5k/hr vs 60/hr). */
+        githubToken?: string;
+      };
+      /** Author / publisher heuristics. */
+      author?: {
+        allowlist?: string[]; /** Days since the publisher's last release before flagging as error. */
+        dormantErrorDays?: number;
+        /** Days since the publisher's last release before flagging as warning. */
+        dormantWarnDays?: number;
+        enabled?: boolean; /** Window for the "new publisher on an established package" check. */
+        newPublisherWindowDays?: number;
+        /** Days since the resolved version was published — error threshold. */
+        recentVersionErrorDays?: number;
+        /** Days since the resolved version was published — warning threshold. */
+        recentVersionWarnDays?: number;
+      };
+      /** Monthly download-count floor. */
+      downloads?: {
+        allowlist?: string[];
+        enabled?: boolean; /** Below this monthly count → error (default: 20). */
+        errorThreshold?: number;
+        /** Below this monthly count → warning (default: 1000). */
+        warnThreshold?: number;
+      };
+      /** Maintainer-email-domain NS lookup. */
+      expiredDomains?: {
+        /** Domains exempted from the check (legacy / internal). */
+        allowDomains?: string[];
+        allowlist?: string[]; /** DNS resolvers to query (default: system). */
+        dnsServers?: string[];
+        enabled?: boolean; /** Per-domain DNS timeout (default: 5000). */
+        timeoutMs?: number;
+      };
+      /** README / license / repository presence checks. */
+      metadata?: {
+        allowlist?: string[]; /** Subset of checks to run. Default: all three. */
+        checks?: ("license" | "readme" | "repo")[];
+        enabled?: boolean;
+      };
+      /** New CLI-bin script introduced in this version. */
+      newBin?: {
+        allowlist?: string[];
+        enabled?: boolean;
+      };
+      /** Provenance regression check. */
+      provenance?: {
+        allowlist?: string[];
+        enabled?: boolean;
+      };
+      /**
+      * ECDSA P-256 verification against npm's signing keys. Disabled
+      * by default because npm coverage still has gaps that produce
+      * noisy warnings on legitimate packages.
+      */
+      signatures?: {
+        allowlist?: string[]; /** Default: marshall is *off*. Set true to enable. */
+        enabled?: boolean;
+        /** Override the keys endpoint (default: npm registry). */
+        keysUrl?: string;
+        /** How to treat an expired-but-known key. Default: "warning". */
+        treatExpiredAs?: "error" | "warning";
+      };
+    };
+    /**
+    * When true, `security.policies.installScripts.allow` keys are matched
+    * as `name@version`. A version bump on an approved package drops it from
+    * the allowlist until the new version is explicitly re-approved (port
+    * of LavaMoat allow-scripts' version-aware policy matcher).
+    *
+    * After a version bump, run `vis approve-builds` or `vis security list`
+    * — both surface a "Version drift" block with the suggested new key
+    * (`old-key  →  new-key`) so you can update `vis.config.ts` by hand.
+    * @default false
+    */
+    pinVersions?: boolean;
+    /**
+    * Supply-chain policy gates. Each sub-block enables one policy and
+    * configures its behavior. When a sub-block is omitted the policy is
+    * inactive. `acceptedRisks` (above) silences specific packages without
+    * disabling a policy globally.
+    *
+    * The 8 policies are inspired by Socket.dev's classification:
+    * - `malware`            — Socket-flagged malicious packages
+    * - `firstSeen`         — packages published less than N minutes ago
+    * - `unexpectedDeps`    — packages outside an allow-list / baseline
+    * - `publisherChange`   — maintainer set changed between installs
+    * - `installScripts`    — preinstall/install/postinstall scripts
+    * - `score`              — Socket overall score below threshold
+    * - `vulnerability`      — OSV vulnerability findings
+    * - `license`            — SPDX allow / deny lists
+    */
+    policies?: {
+      /**
+      * Minimum number of minutes that must pass after a version is
+      * published before vis will allow installation. Migrated from
+      * the legacy `security.minimumReleaseAge` field. Equivalent to
+      * pnpm's `minimumReleaseAge`.
+      * @default 0
+      * @example { minutes: 1440, exclude: ["@myorg/*"] } // 24 hours
+      */
+      firstSeen?: {
+        /**
+        * Package names/patterns excluded from the firstSeen check.
+        * Equivalent to pnpm's `minimumReleaseAgeExclude`.
+        * @example ["webpack", "react", "@myorg/*"]
+        */
+        exclude?: string[];
+        /** Minutes after publish before install is allowed. */
+        minutes?: number;
+      };
+      /**
+      * Build-script (pre/install/postinstall/prepare) controls.
+      * Migrated from the legacy `security.allowBuilds` /
+      * `security.strictDepBuilds` fields.
+      * @example { allow: { esbuild: true }, strict: true }
+      */
+      installScripts?: {
+        /**
+        * Map of package names/patterns to allow (true) or deny
+        * (false) build scripts. Packages not listed are denied
+        * by default. Equivalent to pnpm's `allowBuilds`.
+        */
+        allow?: Record<string, boolean>;
+        /**
+        * When true, installation will fail (exit non-zero) if any
+        * dependencies have unreviewed build scripts. Equivalent to
+        * pnpm's `strictDepBuilds`.
+        * @default false
+        */
+        strict?: boolean;
+      };
+      /**
+      * SPDX license allow / deny lists. Deny wins on any sub-license
+      * match in SPDX expressions (`(MIT OR GPL-3.0)` against
+      * `deny: ["GPL-3.0"]` is blocked). Packages with no declared
+      * license are flagged when `allow` is set.
+      * @example
+      * ```
+      * license: {
+      *   allow: ["MIT", "Apache-2.0", "BSD-3-Clause"],
+      *   deny: ["GPL-3.0", "AGPL-3.0"],
+      * }
+      * ```
+      */
+      license?: {
+        /**
+        * SPDX identifiers that are explicitly permitted. When set,
+        * any package whose declared license is not on this list is
+        * blocked.
+        */
+        allow?: string[];
+        /**
+        * SPDX identifiers that are explicitly forbidden. Always
+        * wins over `allow` when both reference the same identifier.
+        */
+        deny?: string[];
+      };
+      /**
+      * Behavior when the Socket.dev feed flags a package as malicious
+      * (`alerts[].type === "Malware"`).
+      *
+      * The default is cross-field: `{ mode: "block" }` whenever
+      * `security.socket.enabled !== false` (the engine cannot evaluate
+      * malware without Socket data), and `"off"` otherwise. Consumers
+      * resolve this default at evaluation time.
+      */
+      malware?: {
+        /**
+        * - `"block"` — emit a block decision.
+        * - `"warn"`  — surface as a warning; do not gate exit code.
+        * - `"off"`   — disable the policy entirely.
+        */
+        mode?: "block" | "off" | "warn";
+      };
+      /**
+      * Trust-level checking for package publishing. Migrated from the
+      * legacy `security.trustPolicy*` fields. Equivalent to pnpm's
+      * `trustPolicy`.
+      * @example { mode: "no-downgrade", ignoreAfter: 43200 } // 30 days
+      */
+      publisherChange?: {
+        /**
+        * Package selectors excluded from the check.
+        * Equivalent to pnpm's `trustPolicyExclude`.
+        * @example ["chokidar@4.0.3"]
+        */
+        exclude?: string[];
+        /**
+        * Ignore packages published more than N minutes ago. Useful
+        * for older packages that pre-date provenance support.
+        * Equivalent to pnpm's `trustPolicyIgnoreAfter`.
+        */
+        ignoreAfter?: number;
+        /**
+        * - `"off"`           — no trust checking (default).
+        * - `"no-downgrade"`  — block when a package's trust level
+        *   has decreased compared to previous releases (e.g., was
+        *   published by trusted publisher, now only has provenance).
+        */
+        mode?: "no-downgrade" | "off";
+      };
+      /**
+      * Socket.dev overall-score threshold. Packages scoring below
+      * `minimum` trigger a block decision (or interactive prompt
+      * during `vis add`). Migrated from the legacy
+      * `security.socket.minimumScore` field.
+      * @example { minimum: 0.4 }
+      */
+      score?: {
+        /**
+        * Minimum overall Socket.dev score (0–1). Set to 0 to
+        * disable the gate while keeping Socket data fetched.
+        *
+        * Consulted by `vis add`, `audit`, `doctor`, `check`, and
+        * `update`; resolved once in `buildSocketOptions`, then
+        * threaded through every consumer. Falls back to
+        * `DEFAULT_LOW_SCORE_THRESHOLD` (`0.4`) when unset.
+        */
+        minimum?: number;
+      };
+      /**
+      * Net-new transitive dependency detection. Either provide a
+      * static allow-list, a baseline lockfile path (recommended), or
+      * both — the intersection is enforced.
+      * @example { baselineLockfile: "./security/lockfile.baseline.yaml" }
+      */
+      unexpectedDeps?: {
+        /**
+        * Allow-list of dependency names that may appear in the
+        * resolved package set. Glob patterns are supported.
+        * @example ["lodash", "axios", "@myorg/*"]
+        */
+        allow?: string[];
+        /**
+        * Path (absolute or relative to the workspace root) to a
+        * baseline lockfile snapshot. The policy diffs the current
+        * lockfile against this baseline and flags any package that
+        * didn't exist before.
+        * @example "./security/lockfile.baseline.yaml"
+        */
+        baselineLockfile?: string;
+      };
+      /**
+      * OSV vulnerability gating. Migrated from the legacy
+      * `security.audit.failOn` + `security.audit.usage` fields.
+      */
+      vulnerability?: {
+        /**
+        * Severity threshold that makes `vis audit` exit non-zero.
+        * Equivalent to the CLI `--fail-on` flag.
+        * @example "high"
+        */
+        failOn?: "critical" | "high" | "low" | "medium";
+        /**
+        * Reachability filter — only report vulnerabilities in
+        * packages the workspace statically imports.
+        */
+        usage?: {
+          /**
+          * Packages to always treat as reachable even if no
+          * static import is found.
+          * @example ["esbuild", "webpack-cli"]
+          */
+          alwaysAssumeUsed?: string[];
+          /**
+          * Enable the reachability filter by default. Equivalent
+          * to `--usage` on the CLI; `--no-usage` disables.
+          * @default false
+          */
+          enabled?: boolean;
+        };
+      };
+    };
+    /**
+    * Socket.dev data-source configuration. Connection knobs only — score
+    * thresholds and accepted-risk overrides moved to `policies.score` and
+    * `security.acceptedRisks` respectively.
+    * @see https://socket.dev
+    */
+    socket?: {
+      /**
+      * Custom Socket.dev API token. Falls back to the public API token.
+      * Set via VIS_SOCKET_TOKEN environment variable or here.
+      */
+      apiToken?: string;
+      /**
+      * Cache TTL in milliseconds for Socket.dev reports.
+      * @default 3_600_000 (1 hour)
+      */
+      cacheTtlMs?: number;
+      /**
+      * Enable Socket.dev security scanning on install/update/check commands.
+      * @default false
+      */
+      enabled?: boolean;
+      /**
+      * Request timeout in milliseconds for the Socket.dev API.
+      * @default 15_000 (15 seconds)
+      */
+      timeoutMs?: number;
+    };
+    /**
+    * Package names to skip during typosquat detection.
+    * Use this for internal packages or known-safe names that happen to
+    * look similar to popular packages.
+    * @example ["my-internal-axois", "@myorg/recat"]
+    */
+    typosquatAllowlist?: string[];
+  };
+  /**
+  * Share the cache between sibling git worktrees. When the workspace is a
+  * linked worktree (created with `git worktree add`), the cache root is
+  * relocated from `&lt;linkedRoot>/.vis/cache` to the *main*
+  * worktree's `.vis/cache`. Multiple parallel agents working in
+  * sibling worktrees then share a single cache instead of rebuilding the
+  * same hash N times.
+  *
+  * Single-checkout repos (where `.git` is a directory) are unaffected.
+  *
+  * Set to `false` to opt out — useful when worktrees deliberately need
+  * independent caches, e.g. for hermetic experiments.
+  * @default true
+  */
+  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:
+  * - `string` or `string[]` commands
+  * - Sync/async functions returning `string | string[]`
+  * - `{ title, task }` objects for named side-effect tasks
+  * - Mixed arrays of strings and functions
+  * - 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;
+  /**
+  * Named bundles of target dependencies, referenceable from any task's
+  * `dependsOn`. `dependsOn: [{ group: "lint" }]` expands to every entry
+  * in the named group; nested groups are resolved recursively and a
+  * cycle raises during discovery.
+  */
+  taskGroups?: Record<string, (string | {
+    dependencies?: boolean;
+    projects?: string | string[];
+    target: string;
+  } | {
+    group: string;
+  })[]>;
+  /**
+  * Task runner options forwarded verbatim to `defaultTaskRunner`.
+  *
+  * Includes `remoteCache` (HTTP or REAPI gRPC backend), `cacheDirectory`,
+  * `parallel`, `globalEnv`, `globalInputs`, etc.
+  * See `TaskRunnerOptions` for the full surface.
+  */
+  taskRunner?: Partial<TaskRunnerOptions>;
+  /**
+  * Workspace-wide task defaults keyed by target name. Applied universally
+  * to every project that exposes a matching target. Use `scopedTasks` when
+  * defaults should only apply to a subset of projects.
+  */
+  tasks?: Record<string, Partial<VisTargetConfiguration>>;
+  /**
+  * Toolchain (Node / pnpm / python / rust / ...) management. vis
+  * delegates to whichever version manager (proto, mise, fnm, volta,
+  * asdf, nvm, corepack) the developer already has — it does not ship
+  * its own.
+  *
+  * Re-exported from `./toolchain` so the public config type stays
+  * in lockstep with the resolver implementation. `self-activate` is
+  * narrowed out of `preferredManager` here — it's auto-resolved for
+  * pnpm/yarn `packageManager` pins and isn't meaningful as an
+  * override.
+  */
+  toolchain?: Omit<ToolchainConfig, "preferredManager"> & {
+    readonly preferredManager?: Exclude<VersionManagerName, "self-activate">;
+  };
+  /** Terminal UI configuration */
+  tui?: {
+    /**
+    * Auto-exit the TUI after tasks complete.
+    * - `false`: Stay open until the user presses `q` (default)
+    * - `true`: Show quit dialog with 3-second countdown after completion
+    * - `number`: Show quit dialog with custom countdown in seconds
+    */
+    autoExit?: boolean | number;
+  };
+  /** Update command defaults */
+  update?: {
+    /**
+    * Dependency fields to scan for outdated packages.
+    * Beyond the standard fields, supports:
+    * - `"overrides"` (npm)
+    * - `"resolutions"` (yarn)
+    * - `"pnpm.overrides"`
+    * @default ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]
+    */
+    depFields?: string[];
+    exclude?: string[];
+    format?: "json" | "minimal" | "table";
+    /**
+    * Package names or glob patterns to permanently ignore during updates.
+    * Ignored packages are skipped and listed in the output so you know
+    * they were not checked.
+    * @example ["eslint", "@types/*"]
+    */
+    ignore?: string[];
+    include?: string[];
+    /**
+    * Include packages with pinned/exact versions (no `^` or `~` prefix).
+    * By default, pinned versions are skipped during update checks.
+    * @default false
+    */
+    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
+    * install and update.
+    *
+    * Not set by default. If your package manager config
+    * (`pnpm-workspace.yaml`) has `minimumReleaseAge`, vis will
+    * read it from there as a fallback.
+    * @example 1440 // 24 hours
+    */
+    minimumReleaseAge?: number;
+    /**
+    * Package names/patterns excluded from the minimumReleaseAge check.
+    * @example ["webpack", "@myorg/*"]
+    */
+    minimumReleaseAgeExclude?: string[];
+    /**
+    * Per-package or per-pattern update target overrides.
+    * Keys are exact package names, glob patterns, or regex patterns
+    * wrapped in `/` (e.g., `/^@vue/`).
+    * Values are `"latest"`, `"minor"`, or `"patch"`.
+    * @example { "typescript": "minor", "/^@vue/": "patch" }
+    */
+    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";
+  };
+  /**
+  * Minimum vis CLI version required by this workspace. When the
+  * running vis binary is older than this constraint, vis exits with
+  * an actionable error before executing any command.
+  *
+  * Accepts a semver range string (e.g. `">=1.0.0"`, `"^1.2.0"`).
+  * @example ">=1.0.0"
+  */
+  versionConstraint?: string;
+}
+/**
+ * @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
+  * span names. Defaults to passing the id through unchanged.
+  */
+  renameSpan?: (task: Task) => string;
+  /** Tracer used to emit spans. Pass the one from `@opentelemetry/api`'s `trace.getTracer("vis")`. */
+  tracer: Tracer;
+}
+/**
+* Reference plugin that maps vis hook lifecycle events to OTel spans.
+*
+* Emits:
+* - one **root span** named `vis.run` spanning `run:before` → `run:after`
+* - one **child span** per task spanning `task:before` → `task:after`
+*   with attributes `vis.task.id`, `vis.task.project`, `vis.task.target`,
+*   `vis.task.cache_status`, `vis.task.exit_code`
+* - `task:failure` sets span status to ERROR and records the exit code
+*
+* Streaming stdout/stderr events are intentionally **not** emitted as
+* span events — high-frequency chunks would blow up OTel backends. Use
+* a log exporter if you need stream-level visibility.
+* @example
+* ```ts
+* import { trace } from "@opentelemetry/api";
+* import { defineConfig } from "@visulima/vis/config";
+* import { otelPlugin } from "@visulima/vis/plugins/otel";
+*
+* const tracer = trace.getTracer("vis", "1.0.0");
+*
+* export default defineConfig({
+*     plugins: [otelPlugin({ tracer })],
+* });
+* ```
+*/
+declare const otelPlugin: (options: OtelPluginOptions) => VisPlugin;
+/**
+* Type-safe helper for defining a vis plugin. Pure identity — exists
+* only so plugin authors get inference from the `VisPlugin` contract
+* without needing a `satisfies` annotation.
+*
+* Lives in its own module so plugins can import it without going
+* through `config.ts`, which re-exports plugins like `otelPlugin` and
+* would otherwise form an import cycle.
+*/
+declare const definePlugin: (plugin: VisPlugin) => VisPlugin;
+/** Supported config file names, checked in priority order. */
+declare const CONFIG_FILES: string[];
+/** Per-package overlay file names, checked in priority order. */
+declare const TASK_CONFIG_FILES: string[];
+/**
+* Default `security.policies.firstSeen.minutes` applied by `vis init`.
+* 2 days — long enough to filter out most rage-published malware while
+* staying short enough that genuine fixes still land in a working week.
+*
+* Note: this is NOT merged into `SECURITY_DEFAULTS` — leaving it undefined
+* preserves the "no opinion" semantics that downstream drift checks rely
+* on. `vis init` writes the value explicitly into the generated config.
+*/
+
+/**
+* Secure-by-default security settings based on npm supply chain best practices.
+*
+* Applied automatically when using `defineConfig()` or `loadVisConfig()`.
+* Users can override any value — their settings always take precedence.
+* @see https://github.com/lirantal/awesome-npm-security-best-practices
+*/
+declare const SECURITY_DEFAULTS: NonNullable<VisConfig["security"]>;
+/**
+* Apply secure defaults to a raw config object.
+* Merges `SECURITY_DEFAULTS` into `config.security`, preserving all user overrides.
+*/
+declare const applyDefaults: (config: VisConfig) => VisConfig;
+/**
+* Find the vis config file in a directory.
+*
+* Reads the directory listing once and intersects it with the known
+* config filenames rather than `stat`-ing each candidate — one syscall
+* instead of up to six. Priority order is preserved via
+* `CONFIG_FILES` so `.ts` still wins over `.mjs` when both exist.
+* @param directory The directory to search in.
+* @returns The absolute path to the config file, or `undefined` if not found.
+*/
+declare const findVisConfigFile: (directory: string) => string | undefined;
+/**
+* Find the per-package `vis.task.ts` overlay in a project directory.
+* Same single-readdir lookup pattern as {@link findVisConfigFile}.
+*/
+declare const findVisTaskConfigFile: (projectDirectory: string) => string | undefined;
+/**
+* Load the vis configuration from a `vis.config.ts` (or `.js`, `.mjs`, `.cjs`, `.mts`, `.cts`) file.
+*
+* Resolves the entire `extends` chain, post-order, and folds it into a
+* single merged config (extends first, root last — child wins). The
+* cache key covers every file in the chain, so editing any extended
+* file invalidates the cache.
+*
+* 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, options?: {
+  explicitConfigPath?: string;
+}) => Promise<VisConfig>;
+/**
+* Load the per-package `vis.task.ts` overlay for a project, if any.
+*
+* Returns `undefined` when no overlay file exists. Otherwise compiles
+* the file via jiti and caches the result under
+* `node_modules/.cache/vis/task-configs/&lt;project>.json`, keyed by the
+* file's content hash. Editing one project's overlay does not invalidate
+* the root config cache.
+*
+* Errors thrown by the file are wrapped in `VisConfigLoadError` so the
+* source path is reported instead of an opaque workspace.ts failure.
+* @param workspaceRoot Absolute workspace root path (cache scope).
+* @param projectDirectory Absolute path of the project to probe.
+* @param projectName Project identifier — used to scope the cache file.
+*/
+declare const loadVisTaskConfig: (workspaceRoot: string, projectDirectory: string, projectName: string) => Promise<VisTaskConfig | undefined>;
+/**
+* Type-safe helper for defining a per-package `vis.task.ts` overlay.
+* Pure identity — exists only so users get type inference and
+* autocomplete from the `VisTaskConfig` shape.
+* @example
+* ```typescript
+* // packages/api/crud/vis.task.ts
+* import { defineTaskConfig } from "@visulima/vis/config";
+*
+* export default defineTaskConfig({
+*     targets: {
+*         build: {
+*             inputs: ["@inherit", "src/proto/**\/*.proto"],
+*             outputs: ["dist/**\/*"],
+*         },
+*     },
+* });
+* ```
+*/
+declare const defineTaskConfig: (config: VisTaskConfig) => VisTaskConfig;
+/**
+* Type-safe helper for defining vis configuration.
+* Provides full TypeScript autocomplete when used in `vis.config.ts`.
+*
+* Secure defaults are applied automatically — you only need to specify overrides.
+* To see the active defaults, run `vis check --security-config`.
+* @example
+* ```typescript
+* // vis.config.ts — minimal config, fully secured by defaults
+* import { defineConfig } from "@visulima/vis/config";
+*
+* export default defineConfig({
+*     security: {
+*         policies: {
+*             installScripts: {
+*                 allow: {
+*                     esbuild: true,
+*                     "@prisma/client": true,
+*                 },
+*             },
+*         },
+*     },
+* });
+* ```
+* @example
+* ```typescript
+* // vis.config.ts — override a default
+* import { defineConfig } from "@visulima/vis/config";
+*
+* export default defineConfig({
+*     security: {
+*         policies: {
+*             // Relax cooldown to 24 hours instead of the default 14 days
+*             firstSeen: { minutes: 1440 },
+*             installScripts: { allow: { esbuild: true } },
+*         },
+*     },
+* });
+* ```
+*/
+declare const defineConfig: (config: VisConfig) => VisConfig;
+export { CONFIG_FILES, type OtelPluginOptions, SECURITY_DEFAULTS, TASK_CONFIG_FILES, type VisConfig, type VisHooks, type VisPlugin, type VisTaskConfig, applyDefaults, defineConfig, definePlugin, defineTaskConfig, findVisConfigFile, findVisTaskConfigFile, loadVisConfig, loadVisTaskConfig, otelPlugin };