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

package/dist/config/index.d.ts

@@ -0,0 +1,1818 @@
+import { TaskResult, Task, TargetConfiguration, ConstraintsConfig, NamedInputs, TaskRunnerOptions } from '@visulima/task-runner';
+import { Hookable } from 'hookable';
+/**
+* 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<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 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 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;
+}
+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[]) => Promise<unknown> | 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;
+    };
+  };
+}
+/**
+* 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[];
+  /**
+  * Override the workspace `strictEnv` setting for this target. When
+  * truthy, the target fails if its command references an env var
+  * that resolves to neither the task's effective env nor
+  * `process.env`. When `false`, the target opts out of a workspace
+  * `strictEnv: true` (e.g. for a one-off command that legitimately
+  * tolerates an unset variable).
+  *
+  * @see VisConfig.strictEnv
+  */
+  strictEnv?: boolean;
+  /**
+  * When true, the task is serialized with respect to parallel execution
+  * and must be run on the main process (claims stdin). Used for commands
+  * that read from the terminal.
+  * @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;
+  /**
+  * Marks this target as a long-lived service that can be started via
+  * `vis service start <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;
+  /**
+  * 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;
+}
+interface CodeownersConfig {
+  /** Workspace-level paths that apply outside any project (e.g., `.github/**`). */
+  globalPaths?: Record<string, string[]>;
+  /** Sort order for generated entries — mirrors moon's `orderBy`. */
+  orderBy?: "file-source" | "project-id";
+  /** Provider determines whether `channel` is emitted (GitHub supports it via comment). */
+  provider?: "bitbucket" | "github" | "gitlab" | "other";
+}
+/**
+* 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`. */
+  targets?: 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 or application. */
+  projectType?: "application" | "library";
+  /** 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 scope predicate used by {@link VisConfig.taskDefaults}.
+* All listed constraints must match for the block to apply.
+*/
+interface TaskDefaultsScope {
+  /** Match on primary language. */
+  language?: string | string[];
+  /** Match on project layer. */
+  layer?: ProjectJson["layer"] | ProjectJson["layer"][];
+  /** Match on project type. */
+  projectType?: "application" | "library";
+  /** Match on project stack. */
+  stack?: ProjectJson["stack"] | ProjectJson["stack"][];
+  /** Match projects tagged with any of these tags. */
+  tags?: string[];
+}
+/**
+* A single task-defaults block — a set of target defaults gated by an
+* optional scope predicate.
+*/
+interface TaskDefaultsBlock {
+  /** Optional scope predicate; if omitted, the block applies universally. */
+  scope?: TaskDefaultsScope;
+  /** Target default configurations. */
+  targets: 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;
+  };
+  /**
+  * When `true`, every task command is scanned for `${VAR}` / `$VAR`
+  * references before spawn. If a referenced var is unset in the
+  * task's effective env (envFile + service env + per-task `env` +
+  * `process.env`), the task fails with an actionable error
+  * naming the missing variable, instead of letting the shell
+  * silently substitute an empty string.
+  *
+  * Override per run with `--strict-env` / `--no-strict-env`.
+  * Override per target with `options.strictEnv`.
+  * @default false
+  */
+  strictEnv?: boolean;
+  /**
+  * Scope the task-runner cache directory by the current git branch.
+  * When `true`, caches are stored under `&lt;cacheDir>/branches/&lt;slug>`
+  * so `main` and feature branches stop thrashing each other —
+  * 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>;
+  };
+  /**
+  * 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[];
+  };
+  /**
+  * Installer backend selection for `vis install` / `vis add` /
+  * `vis remove` / `vis update` / `vis ci`.
+  *
+  * Lets users opt into [aube](https://github.com/endevco/aube) — a
+  * Rust-native package manager that reads/writes pnpm/npm/yarn/bun
+  * lockfiles in place — as the default installer, while keeping a
+  * single switch to fall back to the conventional PM detected from
+  * the lockfile.
+  *
+  * Resolution precedence (highest first):
+  * 1. CLI flag (`--installer &lt;name>` / `--no-aube`)
+  * 2. Env var `VIS_INSTALLER`
+  * 3. This config field
+  * 4. Auto-detect (the default)
+  *
+  * Aube must be installed separately — `vis` does not bundle it.
+  * Install via `npm i -g @endevco/aube`, `mise use -g aube`, or
+  * `brew install endevco/tap/aube`.
+  */
+  install?: {
+    /**
+    * Which package manager performs install/add/remove/etc.
+    * - `auto` (default): use `aube` when it is on PATH; otherwise
+    *   fall back to the lockfile-detected PM.
+    * - explicit name: always use that PM. Errors when the named
+    *   binary is missing rather than silently falling back.
+    * @default "auto"
+    */
+    backend?: "aube" | "auto" | "bun" | "npm" | "pnpm" | "yarn";
+  };
+  /**
+  * Auto-create targets from detected config files (Project Crystal-style).
+  * Inferred targets sit *below* explicit ones — anything in
+  * `package.json#scripts`, `project.json#targets`, or `vis.task.ts`
+  * 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;
+  /**
+  * 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[];
+  /**
+  * 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;
+  };
+  /**
+  * 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?: {
+    /**
+    * 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` setting.
+    * @example
+    * ```
+    * allowBuilds: {
+    *   "esbuild": true,
+    *   "core-js": false,
+    *   "@prisma/client": true,
+    * }
+    * ```
+    */
+    allowBuilds?: Record<string, 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;
+    /**
+    * Minimum number of minutes that must pass after a version is published
+    * before vis will allow installation. Reduces risk of installing
+    * compromised packages that are typically discovered within hours.
+    * Equivalent to pnpm's `minimumReleaseAge`.
+    * @default 0
+    * @example 1440 // 24 hours
+    */
+    minimumReleaseAge?: number;
+    /**
+    * Package names/patterns excluded from minimumReleaseAge check.
+    * Equivalent to pnpm's `minimumReleaseAgeExclude`.
+    * @example ["webpack", "react", "@myorg/*"]
+    */
+    minimumReleaseAgeExclude?: string[];
+    /**
+    * Socket.dev security intelligence configuration.
+    * When enabled, vis fetches package security scores, alerts, and report
+    * data from the Socket.dev API during install, update, and check commands.
+    * @see https://socket.dev
+    */
+    socket?: {
+      /**
+      * Packages whose low Socket.dev scores or alerts have been reviewed
+      * and explicitly accepted. These packages skip the confirmation
+      * prompt during `vis add` and show as "acknowledged" in `vis audit`.
+      *
+      * 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,
+      *   },
+      * }
+      * ```
+      */
+      acceptedRisks?: Record<string, {
+        /** ISO 8601 timestamp when the risk was accepted. */
+        acceptedAt: string;
+        /** The overall Socket.dev score at the time of acceptance. */
+        acceptedScore: number;
+        /** User-provided reason for accepting the risk. */
+        reason: string;
+      }>;
+      /**
+      * 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;
+      /**
+      * Minimum overall Socket.dev score (0–1) for a package to be
+      * accepted without a confirmation prompt during `vis add`.
+      * Packages scoring below this threshold trigger an interactive
+      * prompt asking the user to confirm. Set to 0 to disable.
+      * @default 0.4
+      */
+      minimumScore?: number;
+      /**
+      * Request timeout in milliseconds for the Socket.dev API.
+      * @default 15_000 (15 seconds)
+      */
+      timeoutMs?: number;
+    };
+    /**
+    * When true, installation will fail (exit non-zero) if any dependencies
+    * have unreviewed build scripts. Equivalent to pnpm's `strictDepBuilds`.
+    * @default false
+    */
+    strictDepBuilds?: boolean;
+    /**
+    * Trust level checking for package publishing.
+    * - "off": No trust checking (default)
+    * - "no-downgrade": Fail if a package's trust level has decreased
+    *   compared to previous releases (e.g., was published by trusted
+    *   publisher, now only has provenance).
+    * Equivalent to pnpm's `trustPolicy`.
+    * @default "off"
+    */
+    trustPolicy?: "no-downgrade" | "off";
+    /**
+    * Package selectors excluded from trust policy checks.
+    * Equivalent to pnpm's `trustPolicyExclude`.
+    * @example ["chokidar@4.0.3", "@babel/core@7.28.5"]
+    */
+    trustPolicyExclude?: string[];
+    /**
+    * Ignore the trust policy check for packages published more than
+    * the specified number of minutes ago. Useful for older packages
+    * that pre-date provenance support.
+    * Equivalent to pnpm's `trustPolicyIgnoreAfter` (10.27+).
+    * @example 43200 // 30 days
+    */
+    trustPolicyIgnoreAfter?: 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>/.task-runner-cache` to the *main*
+  * worktree's `.task-runner-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?: {
+    /** Alphabetize script commands (default: false) */
+    sortScripts?: 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;
+  /** Target default configurations */
+  targetDefaults?: Record<string, Partial<VisTargetConfiguration>>;
+  /**
+  * Cascading task-default blocks. Each block may scope its targets to a
+  * subset of projects via `scope`. Blocks are evaluated in order; later
+  * blocks override earlier ones when the same field is set.
+  *
+  * Scope matching is additive — if `scope` is omitted, the block applies
+  * to every project.
+  * @example
+  * ```
+  * taskDefaults: [
+  *   { scope: { tags: ["frontend"] }, targets: { build: { cache: true } } },
+  *   { scope: { projectType: "library" }, targets: { lint: { cache: true } } },
+  * ]
+  * ```
+  */
+  taskDefaults?: TaskDefaultsBlock[];
+  /**
+  * 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`, `targetDefaults`, etc.
+  * See `TaskRunnerOptions` for the full surface.
+  */
+  taskRunnerOptions?: Partial<TaskRunnerOptions>;
+  /**
+  * 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;
+    /**
+    * 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;
+    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;
+}
+/**
+* Extended project configuration exposed on the discovered workspace.
+* Adds vis-specific metadata (layer, stack, language, owners) on top of
+* the task-runner `ProjectConfiguration`.
+*/
+/**
+ * @since 1.0.0
+ */
+interface Context {
+  /**
+   * Get a value from the context.
+   *
+   * @param key key which identifies a context value
+   */
+  getValue(key: symbol): unknown;
+  /**
+   * Create a new context which inherits from this context and has
+   * the given key set to the given value.
+   *
+   * @param key context key for which to set the value
+   * @param value value to set for the given key
+   */
+  setValue(key: symbol, value: unknown): Context;
+  /**
+   * Return a new context which inherits from this context but does
+   * not contain a value for the given key.
+   *
+   * @param key context key for which to clear a value
+   */
+  deleteValue(key: symbol): Context;
+}
+/**
+ * Attributes is a map from string to attribute values.
+ *
+ * Note: only the own enumerable keys are counted as valid attribute keys.
+ *
+ * @since 1.3.0
+ */
+interface Attributes {
+  [attributeKey: string]: AttributeValue | undefined;
+}
+/**
+ * Attribute values may be any non-nullish primitive value except an object.
+ *
+ * null or undefined attribute values are invalid and will result in undefined behavior.
+ *
+ * @since 1.3.0
+ */
+type AttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
+interface ExceptionWithCode {
+  code: string | number;
+  name?: string;
+  message?: string;
+  stack?: string;
+}
+interface ExceptionWithMessage {
+  code?: string | number;
+  message: string;
+  name?: string;
+  stack?: string;
+}
+interface ExceptionWithName {
+  code?: string | number;
+  message?: string;
+  name: string;
+  stack?: string;
+}
+/**
+ * Defines Exception.
+ *
+ * string or an object with one of (message or name or code) and optional stack
+ *
+ * @since 1.0.0
+ */
+type Exception = ExceptionWithCode | ExceptionWithMessage | ExceptionWithName | string;
+/**
+ * Defines High-Resolution Time.
+ *
+ * The first number, HrTime[0], is UNIX Epoch time in seconds since 00:00:00 UTC on 1 January 1970.
+ * The second number, HrTime[1], represents the partial second elapsed since Unix Epoch time represented by first number in nanoseconds.
+ * For example, 2021-01-01T12:30:10.150Z in UNIX Epoch time in milliseconds is represented as 1609504210150.
+ * The first number is calculated by converting and truncating the Epoch time in milliseconds to seconds:
+ * HrTime[0] = Math.trunc(1609504210150 / 1000) = 1609504210.
+ * The second number is calculated by converting the digits after the decimal point of the subtraction, (1609504210150 / 1000) - HrTime[0], to nanoseconds:
+ * HrTime[1] = Number((1609504210.150 - HrTime[0]).toFixed(9)) * 1e9 = 150000000.
+ * This is represented in HrTime format as [1609504210, 150000000].
+ *
+ * @since 1.0.0
+ */
+type HrTime = [number, number];
+/**
+ * Defines TimeInput.
+ *
+ * hrtime, epoch milliseconds, performance.now() or Date
+ *
+ * @since 1.0.0
+ */
+type TimeInput = HrTime | number | Date;
+/**
+ * @deprecated please use {@link Attributes}
+ * @since 1.0.0
+ */
+type SpanAttributes = Attributes;
+/**
+ * @deprecated please use {@link AttributeValue}
+ * @since 1.0.0
+ */
+type SpanAttributeValue = AttributeValue;
+/**
+ * @since 1.0.0
+ */
+interface TraceState {
+  /**
+   * Create a new TraceState which inherits from this TraceState and has the
+   * given key set.
+   * The new entry will always be added in the front of the list of states.
+   *
+   * @param key key of the TraceState entry.
+   * @param value value of the TraceState entry.
+   */
+  set(key: string, value: string): TraceState;
+  /**
+   * Return a new TraceState which inherits from this TraceState but does not
+   * contain the given key.
+   *
+   * @param key the key for the TraceState entry to be removed.
+   */
+  unset(key: string): TraceState;
+  /**
+   * Returns the value to which the specified key is mapped, or `undefined` if
+   * this map contains no mapping for the key.
+   *
+   * @param key with which the specified value is to be associated.
+   * @returns the value to which the specified key is mapped, or `undefined` if
+   *     this map contains no mapping for the key.
+   */
+  get(key: string): string | undefined;
+  /**
+   * Serializes the TraceState to a `list` as defined below. The `list` is a
+   * series of `list-members` separated by commas `,`, and a list-member is a
+   * key/value pair separated by an equals sign `=`. Spaces and horizontal tabs
+   * surrounding `list-members` are ignored. There can be a maximum of 32
+   * `list-members` in a `list`.
+   *
+   * @returns the serialized string.
+   */
+  serialize(): string;
+}
+/**
+ * A SpanContext represents the portion of a {@link Span} which must be
+ * serialized and propagated along side of a {@link Baggage}.
+ *
+ * @since 1.0.0
+ */
+interface SpanContext {
+  /**
+   * The ID of the trace that this span belongs to. It is worldwide unique
+   * with practically sufficient probability by being made as 16 randomly
+   * generated bytes, encoded as a 32 lowercase hex characters corresponding to
+   * 128 bits.
+   */
+  traceId: string;
+  /**
+   * The ID of the Span. It is globally unique with practically sufficient
+   * probability by being made as 8 randomly generated bytes, encoded as a 16
+   * lowercase hex characters corresponding to 64 bits.
+   */
+  spanId: string;
+  /**
+   * Only true if the SpanContext was propagated from a remote parent.
+   */
+  isRemote?: boolean;
+  /**
+   * Trace flags to propagate.
+   *
+   * It is represented as 1 byte (bitmap). Bit to represent whether trace is
+   * sampled or not. When set, the least significant bit documents that the
+   * caller may have recorded trace data. A caller who does not record trace
+   * data out-of-band leaves this flag unset.
+   *
+   * see {@link TraceFlags} for valid flag values.
+   */
+  traceFlags: number;
+  /**
+   * Tracing-system-specific info to propagate.
+   *
+   * The tracestate field value is a `list` as defined below. The `list` is a
+   * series of `list-members` separated by commas `,`, and a list-member is a
+   * key/value pair separated by an equals sign `=`. Spaces and horizontal tabs
+   * surrounding `list-members` are ignored. There can be a maximum of 32
+   * `list-members` in a `list`.
+   * More Info: https://www.w3.org/TR/trace-context/#tracestate-field
+   *
+   * Examples:
+   *     Single tracing system (generic format):
+   *         tracestate: rojo=00f067aa0ba902b7
+   *     Multiple tracing systems (with different formatting):
+   *         tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE
+   */
+  traceState?: TraceState;
+}
+/**
+ * @since 1.0.0
+ */
+interface SpanStatus {
+  /** The status code of this message. */
+  code: SpanStatusCode;
+  /** A developer-facing error message. */
+  message?: string;
+}
+/**
+ * An enumeration of status codes.
+ *
+ * @since 1.0.0
+ */
+declare enum SpanStatusCode {
+  /**
+   * The default status.
+   */
+  UNSET = 0,
+  /**
+   * The operation has been validated by an Application developer or
+   * Operator to have completed successfully.
+   */
+  OK = 1,
+  /**
+   * The operation contains an error.
+   */
+  ERROR = 2,
+}
+/**
+ * A pointer from the current {@link Span} to another span in the same trace or
+ * in a different trace.
+ * Few examples of Link usage.
+ * 1. Batch Processing: A batch of elements may contain elements associated
+ *    with one or more traces/spans. Since there can only be one parent
+ *    SpanContext, Link is used to keep reference to SpanContext of all
+ *    elements in the batch.
+ * 2. Public Endpoint: A SpanContext in incoming client request on a public
+ *    endpoint is untrusted from service provider perspective. In such case it
+ *    is advisable to start a new trace with appropriate sampling decision.
+ *    However, it is desirable to associate incoming SpanContext to new trace
+ *    initiated on service provider side so two traces (from Client and from
+ *    Service Provider) can be correlated.
+ *
+ * @since 1.0.0
+ */
+interface Link {
+  /** The {@link SpanContext} of a linked span. */
+  context: SpanContext;
+  /** A set of {@link SpanAttributes} on the link. */
+  attributes?: SpanAttributes;
+  /** Count of attributes of the link that were dropped due to collection limits */
+  droppedAttributesCount?: number;
+}
+/**
+ * An interface that represents a span. A span represents a single operation
+ * within a trace. Examples of span might include remote procedure calls or a
+ * in-process function calls to sub-components. A Trace has a single, top-level
+ * "root" Span that in turn may have zero or more child Spans, which in turn
+ * may have children.
+ *
+ * Spans are created by the {@link Tracer.startSpan} method.
+ *
+ * @since 1.0.0
+ */
+interface Span {
+  /**
+   * Returns the {@link SpanContext} object associated with this Span.
+   *
+   * Get an immutable, serializable identifier for this span that can be used
+   * to create new child spans. Returned SpanContext is usable even after the
+   * span ends.
+   *
+   * @returns the SpanContext object associated with this Span.
+   */
+  spanContext(): SpanContext;
+  /**
+   * Sets an attribute to the span.
+   *
+   * Sets a single Attribute with the key and value passed as arguments.
+   *
+   * @param key the key for this attribute.
+   * @param value the value for this attribute. Setting a value null or
+   *              undefined is invalid and will result in undefined behavior.
+   */
+  setAttribute(key: string, value: SpanAttributeValue): this;
+  /**
+   * Sets attributes to the span.
+   *
+   * @param attributes the attributes that will be added.
+   *                   null or undefined attribute values
+   *                   are invalid and will result in undefined behavior.
+   */
+  setAttributes(attributes: SpanAttributes): this;
+  /**
+   * Adds an event to the Span.
+   *
+   * @param name the name of the event.
+   * @param [attributesOrStartTime] the attributes that will be added; these are
+   *     associated with this event. Can be also a start time
+   *     if type is {@type TimeInput} and 3rd param is undefined
+   * @param [startTime] start time of the event.
+   */
+  addEvent(name: string, attributesOrStartTime?: SpanAttributes | TimeInput, startTime?: TimeInput): this;
+  /**
+   * Adds a single link to the span.
+   *
+   * Links added after the creation will not affect the sampling decision.
+   * It is preferred span links be added at span creation.
+   *
+   * @param link the link to add.
+   */
+  addLink(link: Link): this;
+  /**
+   * Adds multiple links to the span.
+   *
+   * Links added after the creation will not affect the sampling decision.
+   * It is preferred span links be added at span creation.
+   *
+   * @param links the links to add.
+   */
+  addLinks(links: Link[]): this;
+  /**
+   * Sets the status of the span.
+   *
+   * By default, a span has status {@link SpanStatusCode.UNSET}.
+   * Calling this method overrides that default.
+   *
+   * The status codes have a total order: `OK > ERROR > UNSET`.
+   *
+   * - Once {@link SpanStatusCode.OK} is set, any further attempts to change
+   *   the status are ignored.
+   * - Any attempt to set {@link SpanStatusCode.UNSET} is always ignored.
+   *
+   * The `message` field is only used when {@link SpanStatusCode.ERROR} is set.
+   * For all other status codes, `message` is ignored.
+   *
+   * @param status The {@link SpanStatus} to set.
+   */
+  setStatus(status: SpanStatus): this;
+  /**
+   * Updates the Span name.
+   *
+   * This will override the name provided via {@link Tracer.startSpan}.
+   *
+   * Upon this update, any sampling behavior based on Span name will depend on
+   * the implementation.
+   *
+   * @param name the Span name.
+   */
+  updateName(name: string): this;
+  /**
+   * Marks the end of Span execution.
+   *
+   * Call to End of a Span MUST not have any effects on child spans. Those may
+   * still be running and can be ended later.
+   *
+   * Do not return `this`. The Span generally should not be used after it
+   * is ended so chaining is not desired in this context.
+   *
+   * @param [endTime] the time to set as Span's end time. If not provided,
+   *     use the current time as the span's end time.
+   */
+  end(endTime?: TimeInput): void;
+  /**
+   * Returns the flag whether this span will be recorded.
+   *
+   * @returns true if this Span is active and recording information like events
+   *     with the `AddEvent` operation and attributes using `setAttributes`.
+   */
+  isRecording(): boolean;
+  /**
+   * Sets exception as a span event
+   * @param exception the exception the only accepted values are string or Error
+   * @param [time] the time to set as Span's event time. If not provided,
+   *     use the current time.
+   */
+  recordException(exception: Exception, time?: TimeInput): void;
+}
+/**
+ * @since 1.0.0
+ */
+declare enum SpanKind {
+  /** Default value. Indicates that the span is used internally. */
+  INTERNAL = 0,
+  /**
+   * Indicates that the span covers server-side handling of an RPC or other
+   * remote request.
+   */
+  SERVER = 1,
+  /**
+   * Indicates that the span covers the client-side wrapper around an RPC or
+   * other remote request.
+   */
+  CLIENT = 2,
+  /**
+   * Indicates that the span describes producer sending a message to a
+   * broker. Unlike client and server, there is no direct critical path latency
+   * relationship between producer and consumer spans.
+   */
+  PRODUCER = 3,
+  /**
+   * Indicates that the span describes consumer receiving a message from a
+   * broker. Unlike client and server, there is no direct critical path latency
+   * relationship between producer and consumer spans.
+   */
+  CONSUMER = 4,
+}
+/**
+ * Options needed for span creation
+ *
+ * @since 1.0.0
+ */
+interface SpanOptions {
+  /**
+   * The SpanKind of a span
+   * @default {@link SpanKind.INTERNAL}
+   */
+  kind?: SpanKind;
+  /** A span's attributes */
+  attributes?: Attributes;
+  /** {@link Link}s span to other spans */
+  links?: Link[];
+  /** A manually specified start time for the created `Span` object. */
+  startTime?: TimeInput;
+  /** The new span should be a root span. (Ignore parent from context). */
+  root?: boolean;
+}
+/**
+ * Tracer provides an interface for creating {@link Span}s.
+ *
+ * @since 1.0.0
+ */
+interface Tracer {
+  /**
+   * Starts a new {@link Span}. Start the span without setting it on context.
+   *
+   * This method do NOT modify the current Context.
+   *
+   * @param name The name of the span
+   * @param [options] SpanOptions used for span creation
+   * @param [context] Context to use to extract parent
+   * @returns Span The newly created span
+   * @example
+   *     const span = tracer.startSpan('op');
+   *     span.setAttribute('key', 'value');
+   *     span.end();
+   */
+  startSpan(name: string, options?: SpanOptions, context?: Context): Span;
+  /**
+   * Starts a new {@link Span} and calls the given function passing it the
+   * created span as first argument.
+   * Additionally the new span gets set in context and this context is activated
+   * for the duration of the function call.
+   *
+   * @param name The name of the span
+   * @param [options] SpanOptions used for span creation
+   * @param [context] Context to use to extract parent
+   * @param fn function called in the context of the span and receives the newly created span as an argument
+   * @returns return value of fn
+   * @example
+   *     const something = tracer.startActiveSpan('op', span => {
+   *       try {
+   *         do some work
+   *         span.setStatus({code: SpanStatusCode.OK});
+   *         return something;
+   *       } catch (err) {
+   *         span.setStatus({
+   *           code: SpanStatusCode.ERROR,
+   *           message: err.message,
+   *         });
+   *         throw err;
+   *       } finally {
+   *         span.end();
+   *       }
+   *     });
+   *
+   * @example
+   *     const span = tracer.startActiveSpan('op', span => {
+   *       try {
+   *         do some work
+   *         return span;
+   *       } catch (err) {
+   *         span.setStatus({
+   *           code: SpanStatusCode.ERROR,
+   *           message: err.message,
+   *         });
+   *         throw err;
+   *       }
+   *     });
+   *     do some more work
+   *     span.end();
+   */
+  startActiveSpan<F extends (span: Span) => unknown>(name: string, fn: F): ReturnType<F>;
+  startActiveSpan<F extends (span: Span) => unknown>(name: string, options: SpanOptions, fn: F): ReturnType<F>;
+  startActiveSpan<F extends (span: Span) => unknown>(name: string, options: SpanOptions, context: Context, fn: F): ReturnType<F>;
+}
+interface OtelPluginOptions {
+  /**
+  * Rename incoming `project:target` IDs before they become OTel
+  * 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;
+/** 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[];
+/**
+* Secure-by-default security settings based on npm supply chain best practices.
+*
+* These defaults are 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: Required<Pick<NonNullable<VisConfig["security"]>, "blockExoticSubdeps" | "strictDepBuilds" | "trustPolicy" | "trustPolicyIgnoreAfter">>;
+/**
+* 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.
+* @returns The loaded and resolved configuration with secure defaults applied.
+*/
+declare const loadVisConfig: (workspaceRoot: 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: {
+*         allowBuilds: {
+*             esbuild: true,
+*             "@prisma/client": true,
+*         },
+*     },
+* });
+* ```
+* @example
+* ```typescript
+* // vis.config.ts — override a default
+* import { defineConfig } from "@visulima/vis/config";
+*
+* export default defineConfig({
+*     security: {
+*         // Relax cooldown to 24 hours instead of the default 14 days
+*         minimumReleaseAge: 1440,
+*         allowBuilds: { esbuild: true },
+*     },
+* });
+* ```
+*/
+declare const defineConfig: (config: VisConfig) => VisConfig;
+/**
+* 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.
+*/
+declare const definePlugin: (plugin: VisPlugin) => VisPlugin;
+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 };