@visulima/vis 1.0.0-alpha.5 → 1.0.0-alpha.7

package/dist/staged/git/diff.d.ts

@@ -0,0 +1,76 @@
+declare const DEFAULT_DIFF_FILTER = "ACMR";
+/**
+ * Lists paths staged as "intent to add" (`git add -N`). These entries crash
+ * `git stash create` with `Entry 'path' not uptodate. Cannot merge.`
+ * We detect them via `git diff-files --raw`, which emits an all-zero new sha
+ * with status `A` for intent-to-add entries (regular worktree-vs-index diffs
+ * show a real blob sha for unstaged edits).
+ *
+ * The caller temporarily unstages them before the backup stash runs, and
+ * restores the intent-to-add state in cleanup. See lint-staged issue #990.
+ */
+export declare const getIntentToAddPaths: (cwd: string) => Promise<string[]>;
+/**
+ * Lists untracked, non-ignored files in the working tree. Used by
+ * `--autoStage` to pick up files a task created during the run.
+ */
+export declare const getUntrackedFiles: (cwd: string) => Promise<string[]>;
+/** Removes the listed paths from the index (`git rm --cached`), leaving the on-disk content alone. */
+export declare const removeFromIndex: (paths: ReadonlyArray<string>, options: {
+    readonly cwd: string;
+}) => Promise<void>;
+/**
+ * Lists files captured by the current diff — by default, staged files
+ * matching the `ACMR` filter. When `diff` is set the range overrides
+ * `--staged` (matching lint-staged's `--diff` CLI flag).
+ */
+export declare const getFiles: (options: {
+    readonly cwd: string;
+    readonly diff?: string;
+    readonly diffFilter?: string;
+    readonly workTree?: string;
+}) => Promise<string[]>;
+/**
+ * Captures the unstaged delta for a list of paths as a git patch. The
+ * resulting buffer can be re-applied with `git apply` after tasks run.
+ * Returns `null` when there are no unstaged changes for any of the paths.
+ *
+ * Splits `paths` into batches to stay under `ARG_MAX` on large staged
+ * sets. Patch fragments from each batch concatenate cleanly because
+ * every fragment starts with its own `diff --git` header.
+ *
+ * Appends a trailing newline when git's stdout doesn't end in one —
+ * `git apply` rejects patches without a final newline as "corrupt patch
+ * at line N" even with `--recount --unidiff-zero`.
+ */
+export declare const capturePatch: (paths: ReadonlyArray<string>, options: {
+    readonly cwd: string;
+}) => Promise<Buffer | null>;
+/**
+ * Returns the worktree-relative paths that have both staged and unstaged modifications.
+ *
+ * `git status --porcelain=v1 -z` uses NUL record separators and splits rename/copy entries
+ * across two records: the status+new-path record, then a second record holding the old path.
+ * We walk the records, consuming the trailing old-path record for R/C statuses so they
+ * don't leak into the next iteration as a malformed status line.
+ */
+export declare const getPartiallyStagedFiles: (cwd: string) => Promise<string[]>;
+/**
+ * Restores working-tree content for the given paths from the index.
+ * Uses `--pathspec-from-file` with NUL-separated stdin so huge lists
+ * don't blow past `ARG_MAX`.
+ */
+export declare const checkoutPaths: (paths: ReadonlyArray<string>, options: {
+    readonly cwd: string;
+}) => Promise<void>;
+/**
+ * Refreshes the index against the working tree. Runs `git update-index --again`
+ * first (lint-staged v17 behaviour — improves compatibility when the original
+ * commit used a pathspec instead of an explicit `git add`), then falls back
+ * to `git add -u` against the originally-staged paths to handle deletions
+ * that `update-index --again` can't express.
+ */
+export declare const updateIndexAgain: (paths: ReadonlyArray<string>, options: {
+    readonly cwd: string;
+}) => Promise<void>;
+export { DEFAULT_DIFF_FILTER };

package/dist/staged/git/exec.d.ts

@@ -0,0 +1,43 @@
+export interface GitExecOptions {
+    readonly cwd: string;
+    /** Environment overrides merged on top of `process.env`. */
+    readonly env?: Record<string, string>;
+    /** Pipe stdin as a Buffer (used for `git apply`). */
+    readonly input?: Buffer | string;
+    /** Ignore non-zero exit codes; useful for `rev-parse` checks. */
+    readonly lenient?: boolean;
+}
+export interface GitExecResult {
+    readonly exitCode: number;
+    readonly stderr: string;
+    readonly stdout: string;
+}
+/** Runs `git` with the given args. Throws `GitError` on non-zero unless `lenient`. */
+export declare const git: (args: ReadonlyArray<string>, options: GitExecOptions) => Promise<GitExecResult>;
+/** Convenience: returns trimmed stdout from a successful git invocation. */
+export declare const gitOut: (args: ReadonlyArray<string>, options: GitExecOptions) => Promise<string>;
+/** Returns true if `cwd` is inside a git working tree. */
+export declare const isGitRepo: (cwd: string) => Promise<boolean>;
+/** Returns the absolute path to the repository's `.git` directory. */
+export declare const getGitDirectory: (cwd: string) => Promise<string>;
+/** Returns the absolute path to the working-tree root. */
+export declare const getWorkTree: (cwd: string) => Promise<string>;
+/** Returns the current index tree sha (via `git write-tree`). */
+export declare const writeIndexTree: (cwd: string) => Promise<string>;
+/** Returns the tree sha for `HEAD`. Empty string when there is no commit yet. */
+export declare const headTreeSha: (cwd: string) => Promise<string>;
+/** Minimum git version required by the staged workflow — matches lint-staged v17. */
+export declare const MIN_GIT_VERSION: {
+    readonly major: 2;
+    readonly minor: 32;
+};
+/**
+ * Parses `git --version` output (e.g. `git version 2.45.1.windows.2`) into a
+ * `{ major, minor }` tuple. Returns `null` when the shape isn't recognised.
+ */
+export declare const parseGitVersion: (output: string) => {
+    major: number;
+    minor: number;
+} | null;
+/** Throws `GitError` when the installed git is older than {@link MIN_GIT_VERSION}. */
+export declare const assertGitVersion: (cwd: string) => Promise<void>;

package/dist/staged/git/index.d.ts

@@ -0,0 +1,77 @@
+import type { RunOptions } from "../types.d.ts";
+/**
+ * Encapsulates the full git side-effect sequence around task execution:
+ * take a backup stash, hide unstaged deltas, run tasks, re-stage fixes,
+ * reapply hidden deltas, and revert on failure. Mirrors lint-staged's
+ * GitWorkflow state machine with equivalent flag behavior.
+ */
+export declare class GitWorkflow {
+    stagedFiles: string[];
+    partiallyStaged: string[];
+    workTree: string;
+    gitDir: string;
+    /** Index tree sha captured at the end of `prepare()`, before tasks run. */
+    preTaskIndexTree: string;
+    /** Index tree sha captured at the end of `applyModifications()`, after tasks' in-place edits are staged. */
+    postTaskIndexTree: string;
+    /** HEAD tree sha captured in `prepare()` — used to detect empty-after-revert commits. */
+    headTree: string;
+    /** Becomes true after a successful `revert()` so the caller can skip the unstaged-patch re-apply that would duplicate the restored deltas. */
+    revertApplied: boolean;
+    /** Emitted by `prepare()` when we skip the backup stash but still have partially-staged files — the caller can surface this to the user. */
+    warnings: string[];
+    private readonly cwd;
+    private readonly options;
+    private patch;
+    private backupStashSha;
+    private merge;
+    private readonly shouldStash;
+    private readonly shouldHidePartial;
+    private readonly shouldHideUnstaged;
+    private readonly shouldHideAll;
+    /** Sha of the hide-all push stash (if `--hide-all` is set), tracked separately from the create+store backup. */
+    private hideAllStashSha;
+    /** Paths that were `git add -N`'d (intent-to-add) — removed from the index before stashing, restored after. */
+    private intentToAddPaths;
+    /** Untracked files observed at the end of `prepare()`. Diffed post-run to detect task-created files for `--autoStage`. */
+    private preTaskUntracked;
+    constructor(options: RunOptions);
+    prepare(): Promise<void>;
+    /**
+     * Refreshes the index against the working tree, so task edits
+     * (including deletions of already-tracked files) are re-staged.
+     * Uses `git update-index --again` for parity with lint-staged v17,
+     * which behaves correctly when the original commit used a pathspec.
+     */
+    applyModifications({ autoStage }?: {
+        readonly autoStage?: boolean;
+    }): Promise<void>;
+    /** True when tasks modified at least one staged file's content (index tree changed). */
+    indexTreeChanged(): boolean;
+    /** True when the post-task index tree matches HEAD — i.e. tasks reverted every staged change. */
+    postTaskIndexMatchesHead(): boolean;
+    /**
+     * Re-applies the hidden unstaged patch. Falls back to 3-way on conflict.
+     * Skips silently when `revert()` already restored the working tree from the backup stash,
+     * since the stash already carries those deltas and re-applying would duplicate them.
+     * When `--hide-all` is active this is also a no-op — the `popHideAllStash()` call in
+     * `cleanup()` handles restore for that mode.
+     */
+    restoreUnstagedChanges(): Promise<void>;
+    /** Restores index + working tree from the backup stash and drops it. */
+    revert(): Promise<void>;
+    /**
+     * On success, drops the backup stash and pops the hide-all stash (if any).
+     * On failure without --revert, leaves the backup stash in place so the
+     * user can recover manually.
+     */
+    cleanup(success: boolean): Promise<void>;
+    /**
+     * Returns a user-facing hint that points at the backup stash when
+     * tasks failed and we kept it around (no --revert).
+     */
+    recoveryHint(): string | null;
+    private hideUnstagedChanges;
+    private snapshotMergeState;
+    private restoreMergeState;
+}

package/dist/staged/git/stash.d.ts

@@ -0,0 +1,37 @@
+/** Message prefix stored on the stash entry. A per-process suffix is appended at creation time so concurrent `vis staged` invocations don't collide. */
+declare const STASH_MESSAGE_PREFIX = "vis_staged_automatic_backup";
+/**
+ * Creates and stores a hidden backup stash. Uses `git stash create +
+ * store` instead of `git stash push` so the working tree and index are
+ * left untouched — pushing would mutate the worktree, which breaks
+ * concurrent editors and file watchers.
+ *
+ * Returns the stash commit sha, or `null` when there is nothing to
+ * stash (e.g. a fresh repo with only an initial commit).
+ */
+export declare const createBackupStash: (cwd: string) => Promise<string | null>;
+/**
+ * Stashes every unstaged change and untracked file on top of the index,
+ * leaving only staged content in the working tree. Unlike
+ * {@link createBackupStash}, this uses `git stash push --include-untracked`
+ * because `git stash create` cannot capture untracked files.
+ *
+ * Returns the stash commit sha so the caller can drop or apply it later.
+ */
+export declare const createHideAllStash: (cwd: string) => Promise<string | null>;
+/** Drops the stash entry that resolves to `sha`, if one is present. */
+export declare const dropBackupStash: (cwd: string, sha: string | null) => Promise<void>;
+/**
+ * Restores the working tree and index from the backup stash. Used by
+ * the revert path when tasks failed and we need to leave the repo in
+ * its pre-task state.
+ */
+export declare const applyBackupStash: (cwd: string, sha: string | null) => Promise<void>;
+/**
+ * Pops the hide-all stash back onto the working tree — restoring
+ * previously-hidden unstaged edits and untracked files. The index is
+ * left untouched so task-driven edits that we already re-staged
+ * survive the restore.
+ */
+export declare const popHideAllStash: (cwd: string, sha: string | null) => Promise<void>;
+export { STASH_MESSAGE_PREFIX };

package/dist/staged/index.d.ts

@@ -0,0 +1,13 @@
+import type { RunOptions, RunResult } from "./types.d.ts";
+/**
+ * Runs staged tasks end-to-end: backup, hide unstaged, match files,
+ * execute commands, re-stage fixes, reapply unstaged deltas, cleanup.
+ * Returns `{ success, ranTasks, failedCommands }`.
+ *
+ * Throws on setup-level failures (no git repo, invalid config). Task
+ * failures are reported via the return value when `continueOnError` is
+ * enabled, otherwise they end the run with `success: false`.
+ */
+export declare const runStaged: (options?: RunOptions) => Promise<RunResult>;
+export { ApplyEmptyCommitError, ConfigError, GetBackupStashError, GitError, RestoreOriginalStateError, StagedError, TaskError } from "./index.d.ts";
+export type { RunOptions, RunResult, StagedConfig } from "./types.d.ts";

package/dist/staged/match.d.ts

@@ -0,0 +1,12 @@
+export interface MatchOptions {
+    readonly caseInsensitive?: boolean;
+}
+export declare const matchFiles: (pattern: string, files: ReadonlyArray<string>, cwd: string, options?: MatchOptions) => string[];
+/**
+ * Filters a staged file list against a top-level ignore list. A file is
+ * dropped when any of the ignore patterns matches — basename-style for
+ * patterns without a path separator, path-style relative to `cwd`
+ * otherwise. Mirrors the `matchFiles` semantics (including `caseInsensitive`)
+ * so users don't have to think twice about the ignore syntax.
+ */
+export declare const applyIgnore: (files: ReadonlyArray<string>, ignore: ReadonlyArray<string> | undefined, cwd: string, options?: MatchOptions) => string[];

package/dist/staged/renderer/index.d.ts

@@ -0,0 +1,9 @@
+import type { Renderer, RunOptions } from "../types.d.ts";
+/**
+ * Picks the right renderer for the runtime environment and option flags.
+ * Plain renderer runs in CI, non-TTY terminals, and when `debug`, `quiet`,
+ * or `TERM=dumb` is set. Everywhere else the Ink tree renderer engages.
+ */
+export declare const pickRenderer: (options: RunOptions) => Promise<Renderer>;
+export { createInkRenderer } from "./index.d.ts";
+export { createPlainRenderer } from "./plain.d.ts";

package/dist/staged/renderer/ink/index.d.ts

@@ -0,0 +1,4 @@
+import type { Renderer } from "../../types.d.ts";
+export declare const createInkRenderer: (options?: {
+    readonly verbose?: boolean;
+}) => Renderer;

package/dist/staged/renderer/plain.d.ts

@@ -0,0 +1,12 @@
+import type { Renderer } from "../types.d.ts";
+interface PlainRendererOptions {
+    readonly quiet?: boolean;
+    readonly verbose?: boolean;
+}
+/**
+ * Line-based renderer suitable for CI, non-TTY terminals, and `--debug` /
+ * `--quiet` runs. Matches listr2's verbose renderer contract: one line
+ * per lifecycle event, no cursor manipulation, stable output for logs.
+ */
+export declare const createPlainRenderer: (options?: PlainRendererOptions) => Renderer;
+export {};

package/dist/staged/tasks/build.d.ts

@@ -0,0 +1,13 @@
+import type { CustomTask, PatternDescriptor, StagedTask } from "../types.d.ts";
+declare const isCustomTask: (value: unknown) => value is CustomTask;
+export interface BuildTaskGraphOptions {
+    /** Match globs case-insensitively — enable on HFS+/APFS (macOS) and NTFS (Windows). */
+    readonly caseInsensitive?: boolean;
+    readonly config: Readonly<Record<string, StagedTask>>;
+    readonly cwd: string;
+    readonly files: ReadonlyArray<string>;
+    readonly relative?: boolean;
+}
+/** Builds the list of pattern descriptors that the runner will execute. */
+export declare const buildTaskGraph: (options: BuildTaskGraphOptions) => Promise<PatternDescriptor[]>;
+export { isCustomTask };

package/dist/staged/tasks/exec.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Minimal quote-aware argv splitter. Handles single and double quotes,
+ * backslash escapes (both outside and inside double quotes, matching
+ * POSIX shell semantics), and collapses runs of whitespace — enough for
+ * the shell-like syntax users put in their staged config without
+ * dragging in `string-argv`.
+ *
+ * Inside single quotes everything is literal (POSIX semantics). Inside
+ * double quotes, `\"` and `\\` are interpreted; other backslash
+ * sequences are preserved verbatim.
+ *
+ * Throws `ConfigError` on unterminated quotes so typos in config fail
+ * fast instead of silently swallowing the rest of the command.
+ */
+export declare const parseCommandString: (input: string) => string[];
+/**
+ * Platform-aware default for the maximum per-invocation argv byte length.
+ *
+ * Linux `execve()` caps `ARG_MAX` at ~128 KiB on most kernels; macOS sits at
+ * 256 KiB. Windows `CreateProcess` caps the full command line at 32,767
+ * UTF-16 code units (~65 KiB in the worst ASCII case, tighter for non-ASCII),
+ * so we pick a conservative 28 KiB limit there to leave headroom for the
+ * argv prefix and environment overhead that Node splices in.
+ */
+declare const DEFAULT_MAX_ARG_LENGTH: number;
+/**
+ * Splits `files` into chunks whose combined byte length (plus a shared
+ * fixed-prefix length) does not exceed `maxArgLength`. Guarantees at
+ * least one file per chunk so extremely long individual paths still
+ * make it through.
+ */
+export declare const chunkFiles: (files: ReadonlyArray<string>, fixedPrefixLength: number, maxArgLength: number) => string[][];
+export interface ExecCommandOptions {
+    readonly cwd: string;
+    readonly env?: Record<string, string>;
+    /**
+     * Signal delivered to the child process when `signal` fires. Defaults to `SIGTERM`
+     * (graceful). Use `SIGKILL` for fast-fail runs where graceful shutdown is not
+     * worth the wait.
+     */
+    readonly killSignal?: NodeJS.Signals;
+    readonly maxArgLength?: number;
+    /** Aborted when the caller cancels the run (e.g. another task failed without `continueOnError`). */
+    readonly signal?: AbortSignal;
+}
+export interface ExecCommandResult {
+    readonly durationMs: number;
+    readonly output: string;
+}
+/**
+ * Runs a command once per file-chunk, concatenating stdout/stderr for
+ * renderer consumption. Throws `TaskError` on the first failing chunk
+ * or when the caller's `AbortSignal` fires mid-invocation.
+ */
+export declare const execCommand: (command: string, files: ReadonlyArray<string>, options: ExecCommandOptions) => Promise<ExecCommandResult>;
+export { DEFAULT_MAX_ARG_LENGTH };

package/dist/staged/tasks/run.d.ts

@@ -0,0 +1,26 @@
+import type { PatternDescriptor, Renderer } from "../types.d.ts";
+export interface RunTasksOptions {
+    readonly concurrent: boolean | number;
+    readonly continueOnError: boolean;
+    readonly cwd: string;
+    /** External cancellation (e.g. SIGINT handler). When fired, cancels like a task failure. */
+    readonly externalSignal?: AbortSignal;
+    /** Signal delivered to in-flight child processes when the run cancels. Defaults to `SIGTERM`. */
+    readonly killSignal?: NodeJS.Signals;
+    readonly maxArgLength?: number;
+    readonly verbose?: boolean;
+}
+export interface RunTasksResult {
+    readonly failedCommands: string[];
+    readonly success: boolean;
+}
+/**
+ * Runs pattern tasks with pattern-level concurrency and command-level
+ * serial execution. Emits lifecycle events through the renderer.
+ *
+ * When a command fails and `continueOnError` is off, the shared
+ * `AbortController` is aborted so any execa children currently running
+ * in other workers exit promptly rather than running to completion on
+ * a doomed run.
+ */
+export declare const runTasks: (patterns: ReadonlyArray<PatternDescriptor>, renderer: Renderer, options: RunTasksOptions) => Promise<RunTasksResult>;

package/dist/staged/types.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Public types for the in-house staged-files workflow that replaces
+ * the `lint-staged` peer dependency. The surface mirrors lint-staged's
+ * so existing configs and the `vis staged` command contract survive.
+ */
+/** Status of a single task or pattern in the runner lifecycle. */
+export type TaskStatus = "failed" | "pending" | "running" | "skipped" | "success";
+/**
+ * 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.
+ */
+export 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.
+ */
+export type StagedTask = CustomTask | StagedTaskFunction | ReadonlyArray<CustomTask | StagedTaskFunction | string> | string | ReadonlyArray<string>;
+export type StagedTaskFunction = (files: string[]) => Promise<StagedTaskResult> | StagedTaskResult;
+export 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.
+ */
+export type StagedConfig = Readonly<Record<string, StagedTask>> | StagedConfigFunction;
+export type StagedConfigFunction = (files: string[]) => Promise<Record<string, StagedTask>> | Record<string, StagedTask>;
+/** Options accepted by `runStaged`. Mirrors the lint-staged CLI surface. */
+export interface RunOptions {
+    /** Allow empty commits when tasks revert every staged change. */
+    readonly allowEmpty?: boolean;
+    /**
+     * When a task writes *new* files that sit outside the originally-staged
+     * set, automatically stage them too. Defaults to `false` — only tasks
+     * explicitly called out to produce new artefacts should set this (e.g.
+     * codegen, lockfile regeneration). Closes nano-staged #43.
+     */
+    readonly autoStage?: boolean;
+    /** Concurrency: `true` (unbounded), `false` (serial), or a positive integer. */
+    readonly concurrent?: boolean | number;
+    /** Inline staged config — the single source of truth at runtime. Supplied by `vis staged` from `vis.config.ts`. */
+    readonly config?: StagedConfig;
+    /** Run all tasks to completion even if one fails. */
+    readonly continueOnError?: boolean;
+    /** Working directory used for git and task execution. */
+    readonly cwd?: string;
+    /** Enable debug logging and force the plain renderer. */
+    readonly debug?: boolean;
+    /** Override the default `--staged` diff scope with an arbitrary git range. Implies `--no-stash`. */
+    readonly diff?: string;
+    /** Override the default `--diff-filter=ACMR`. */
+    readonly diffFilter?: string;
+    /** Exit with a non-zero status if tasks modified tracked files. Implies `--no-revert`. */
+    readonly failOnChanges?: boolean;
+    /**
+     * Hide every unstaged change *and* every untracked file before running
+     * tasks. Useful for tools like Knip that inspect the whole worktree.
+     * Backed by a `git stash --include-untracked` so restore is automatic.
+     */
+    readonly hideAll?: boolean;
+    /** Hide unstaged edits on partially-staged files (default: `true`). Set `false` to disable. */
+    readonly hidePartiallyStaged?: boolean;
+    /** Hide unstaged changes on every tracked file, not only partially-staged ones. */
+    readonly hideUnstaged?: boolean;
+    /**
+     * Glob patterns for files to exclude from every task. Applied to the
+     * staged file list before pattern matching, so an `ignore` hit drops
+     * a file from *all* tasks regardless of which globs would otherwise
+     * have picked it up. Closes lint-staged issue #1722.
+     */
+    readonly ignore?: ReadonlyArray<string>;
+    /**
+     * Signal used to kill in-flight task subprocesses when the run is
+     * cancelled (another task failed without `continueOnError`, or the
+     * user hit Ctrl+C). Defaults to `SIGTERM`, which lets well-behaved
+     * tools flush before exiting. Use `SIGKILL` for fast-fail runs
+     * where graceful shutdown is not worth the wait.
+     * @default "SIGTERM"
+     */
+    readonly killSignal?: NodeJS.Signals;
+    /** Cap on combined argv byte length per command invocation. Defaults to a conservative OS limit. */
+    readonly maxArgLength?: number;
+    /** Suppress progress output entirely. */
+    readonly quiet?: boolean;
+    /** Pass matched paths to tasks relative to `cwd` instead of absolute. */
+    readonly relative?: boolean;
+    /** Revert the working tree from the backup stash when a task fails. */
+    readonly revert?: boolean;
+    /** Take a backup stash before running tasks (default: `true`). Set `false` to disable. */
+    readonly stash?: boolean;
+    /** Show task stdout/stderr on success, not only on failure. */
+    readonly verbose?: boolean;
+}
+/** A runtime descriptor for a single command belonging to a pattern. */
+export interface CommandDescriptor {
+    /** Resolved command template; absent for custom tasks. */
+    readonly command?: string;
+    /** Matched files (absolute or relative, per `relative` option). */
+    readonly files: ReadonlyArray<string>;
+    /** A stable id for renderer lookups. */
+    readonly id: string;
+    /** Custom task callback; only set when `source === "custom"`. */
+    readonly run?: (files: string[]) => Promise<unknown> | unknown;
+    readonly source: "custom" | "function" | "string";
+    readonly title: string;
+}
+/** A runtime descriptor for a glob pattern and its resolved commands. */
+export interface PatternDescriptor {
+    readonly commands: ReadonlyArray<CommandDescriptor>;
+    readonly files: ReadonlyArray<string>;
+    readonly id: string;
+    readonly pattern: string;
+    readonly title: string;
+}
+/** Events emitted by the runner and consumed by a renderer. */
+export interface RunnerEvents {
+    commandEnd: {
+        readonly commandId: string;
+        readonly durationMs: number;
+        readonly error?: Error;
+        readonly output?: string;
+        readonly patternId: string;
+        readonly status: TaskStatus;
+    };
+    commandStart: {
+        readonly commandId: string;
+        readonly patternId: string;
+    };
+    error: {
+        readonly error?: Error;
+        readonly message: string;
+    };
+    info: {
+        readonly message: string;
+    };
+    patternEnd: {
+        readonly patternId: string;
+        readonly status: TaskStatus;
+    };
+    patternStart: {
+        readonly patternId: string;
+    };
+    start: {
+        readonly patterns: ReadonlyArray<PatternDescriptor>;
+    };
+    warn: {
+        readonly message: string;
+    };
+}
+/** Abstract renderer contract — plain and Ink implementations conform. */
+export interface Renderer {
+    commandEnd: (payload: RunnerEvents["commandEnd"]) => void;
+    commandStart: (payload: RunnerEvents["commandStart"]) => void;
+    error: (payload: RunnerEvents["error"]) => void;
+    info: (payload: RunnerEvents["info"]) => void;
+    patternEnd: (payload: RunnerEvents["patternEnd"]) => void;
+    patternStart: (payload: RunnerEvents["patternStart"]) => void;
+    start: (payload: RunnerEvents["start"]) => void;
+    stop: () => Promise<void> | void;
+    warn: (payload: RunnerEvents["warn"]) => void;
+}
+/** Outcome of a `runStaged` invocation. */
+export interface RunResult {
+    readonly failedCommands: ReadonlyArray<string>;
+    readonly ranTasks: boolean;
+    readonly success: boolean;
+}

package/dist/target-discovery.d.ts

@@ -0,0 +1,59 @@
+import type { WorkspaceConfiguration } from "@visulima/task-runner";
+import type { ProjectOptionsIndex } from "./workspace.d.ts";
+/**
+ * Collects every unique target name across all projects in the workspace.
+ * @param workspace The discovered workspace configuration.
+ * @returns Sorted array of unique target names.
+ */
+export declare const collectAvailableTargets: (workspace: WorkspaceConfiguration) => string[];
+/**
+ * Builds a `{alias → canonicalTargetName}` lookup from declared
+ * `aliases` on any `VisTargetConfiguration` in the workspace. Aliases
+ * are treated as workspace-global — the first declaration wins and
+ * later ones are silently ignored (prefer explicit canonical names
+ * when aliases collide).
+ *
+ * Canonical target names themselves are not added to the map — only
+ * declared aliases — so `resolveTargetAlias` leaves non-alias input
+ * unchanged.
+ */
+export declare const buildAliasMap: (projectOptions: ProjectOptionsIndex) => Map<string, string>;
+/**
+ * Resolves a user-typed target name to its canonical form, or returns
+ * the input unchanged when no alias matches.
+ */
+export declare const resolveTargetAlias: (name: string, aliases: Map<string, string>) => string;
+/**
+ * Suggests the closest matching target name for a typo.
+ * @param input The unknown target name the user typed.
+ * @param available Known target names.
+ * @param maxDistance Maximum edit distance to consider (default 3).
+ * @returns The best match, or `undefined` if nothing is close enough.
+ */
+export declare const suggestTarget: (input: string, available: string[], maxDistance?: number) => string | undefined;
+/**
+ * Returns up to `limit` closest-matching target names within
+ * `maxDistance` edit distance, sorted by ascending distance.
+ *
+ * Used by the missing-target error output to offer several candidates
+ * — one suggestion often reads as authoritative, three reads as
+ * "pick whichever you meant", which is friendlier at scale.
+ */
+export declare const suggestTargets: (input: string, available: string[], limit?: number, maxDistance?: number) => string[];
+/**
+ * Formats the available targets list for display.
+ * @param targets Sorted target names.
+ * @returns Formatted string for CLI output.
+ */
+export declare const formatTargetList: (targets: string[]) => string;
+/**
+ * Prompts the user to pick a target from `targets` via an interactive
+ * numbered readline prompt. Accepts either the index (1-based) or the
+ * target name; empty input or Ctrl-C aborts with `undefined`.
+ *
+ * Uses Node's built-in readline rather than a TUI dependency — this
+ * keeps the bare `vis run` flow lightweight and works in any TTY.
+ * Mirrors vite-task's `vp run` (no args) interactive selector.
+ * @returns The chosen target name, or `undefined` if the user aborts.
+ */
+export declare const promptTargetInteractively: (targets: string[]) => Promise<string | undefined>;