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

package/dist/config/index.d.ts

@@ -0,0 +1,1739 @@
+import { TaskResult, Task, TargetConfiguration, ConstraintsConfig, NamedInputs, TaskRunnerOptions } from '@visulima/task-runner';
+import { Hookable } from 'hookable';
+import { Tracer } from '@opentelemetry/api';
+/**
+* Typed hook surface exposed to vis plugins.
+*
+* 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;
+}
+/**
+* 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;
+    };
+  };
+}
+/**
+* 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;
+}
+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";
+}
+/**
+* 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`. */
+  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;
+  };
+  /**
+  * 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;
+  };
+  /**
+  * 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;
+  };
+  /**
+  * 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?: {
+    /** 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;
+  /** 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;
+    /**
+    * 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;
+}
+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.
+* @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: {
+*         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 };