@visulima/vis 1.0.0-alpha.8 → 1.0.0-alpha.9

package/dist/config.d.ts

@@ -1,82 +1,1087 @@
-import type { VisPlugin } from "./hooks.d.ts";
-import type { VisConfig } from "./workspace.d.ts";
+import { TaskResult, Task, TargetConfiguration, ConstraintsConfig, NamedInputs } 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;
+}
+/**
+* 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>;
+/**
+* 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;
+/** Supported OS filters for target execution. */
+type TargetOsType = "linux" | "macos" | "windows";
+/**
+* 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.
+*/
+/**
+* Object form of the `when` gate. Matches against process.env or
+* process.platform — deliberately small surface area so conditions
+* stay auditable and declarative.
+*/
+interface TargetConditionObject {
+  /** Env var name to compare against `equals` or `in`. */
+  env?: string;
+  /** Value that `env` must match exactly. */
+  equals?: string;
+  /** Any value in this list matches. Ignored when `equals` is set. */
+  in?: string[];
+  /** Run only on this platform (or one of these). */
+  platform?: NodeJS.Platform | NodeJS.Platform[];
+}
+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;
+  /**
+  * 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;
+  /**
+  * Restricts execution to specific operating systems. Tasks run on
+  * unmatched platforms are skipped with a warning.
+  */
+  osType?: TargetOsType | TargetOsType[];
+  /**
+  * 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;
+  /**
+  * 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 then SIGKILL
+  * (via the concurrent runner's `killSignal`/`killTimeout`
+  * semantics) and the task exits with a failure status carrying the
+  * `[timeout]` marker in `terminalOutput`. Retries count against
+  * this 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;
+  /**
+  * Conditional gate: the task is scheduled only when `when` evaluates
+  * truthy. Shapes:
+  * - `"$VAR"` — run only if the env var is non-empty
+  * - `"!VAR"` — run only if the env var is empty/unset
+  * - `{ env: "NAME", equals: "value" }` — run only if env equals
+  * - `{ env: "NAME", in: ["a", "b"] }` — run only if env is in set
+  * - `{ platform: "darwin" | "linux" | "win32" }` — OS gate
+  *
+  * Kept declarative on purpose — no dynamic code execution. For
+  * richer logic, use osType/runInCI or a pre-hook script.
+  */
+  when?: TargetConditionObject | 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;
+  /** 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;
+}
+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>>;
+}
+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 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>;
+  };
+  /**
+  * 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[];
+  };
+  /**
+  * 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[];
+  /**
+  * 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[];
+  };
+  /** 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 */
+  taskRunnerOptions?: Record<string, unknown>;
+  /**
+  * 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;
+  };
+  /**
+  * 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 <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";
+  };
+  /** 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;
+}
+/**
+* Resolves glob-like workspace patterns to actual directories.
+* Supports simple patterns like "packages/*" and "packages/**".
+*/
+/**
+* Minimal OTel-shaped span. Deliberately structural so users can pass
+* an `@opentelemetry/api` Tracer, an `@opentelemetry/sdk-node` one, or
+* a custom implementation without the plugin depending on any
+* particular OTel package.
+*/
+interface OtelSpan {
+  end: () => void;
+  recordException?: (error: unknown) => void;
+  setAttribute?: (key: string, value: boolean | number | string) => void;
+  setStatus?: (status: {
+    code: number;
+    message?: string;
+  }) => void;
+}
+/**
+* Minimal Tracer contract. Accepts the real
+* `@opentelemetry/api`'s `Tracer.startSpan(name, options?)` shape —
+* the plugin only calls the two methods it strictly needs.
+*/
+interface OtelTracer {
+  startSpan: (name: string, options?: {
+    attributes?: Record<string, string | number | boolean>;
+  }) => OtelSpan;
+}
+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. Required — pass the one from `@opentelemetry/api`'s `trace.getTracer("vis")`. */
+  tracer: OtelTracer;
+}
+/**
+* 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[];
 /**
- * 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
- */
+* 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.
- */
+* 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.
- */
+* 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;
 /**
- * Load the vis configuration from a `vis.config.ts` (or `.js`, `.mjs`, `.cjs`, `.mts`, `.cts`) file.
- *
- * Uses a file-hash based cache to avoid repeated jiti compilations.
- * 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.
- */
+* Load the vis configuration from a `vis.config.ts` (or `.js`, `.mjs`, `.cjs`, `.mts`, `.cts`) file.
+*
+* Uses a file-hash based cache to avoid repeated jiti compilations.
+* 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>;
 /**
- * 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 },
- *     },
- * });
- * ```
- */
+* 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.
- */
+* 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 type { VisHooks, VisPlugin } from "./hooks.d.ts";
-export type { OtelPluginOptions, OtelSpan, OtelTracer } from "./plugins/otel.d.ts";
-export { otelPlugin } from "./plugins/otel.d.ts";
-export { applyDefaults, CONFIG_FILES, defineConfig, definePlugin, findVisConfigFile, loadVisConfig, SECURITY_DEFAULTS };
+export { CONFIG_FILES, type OtelPluginOptions, type OtelSpan, type OtelTracer, SECURITY_DEFAULTS, type VisHooks, type VisPlugin, applyDefaults, defineConfig, definePlugin, findVisConfigFile, loadVisConfig, otelPlugin };