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

package/dist/target-options.d.ts

@@ -0,0 +1,261 @@
+import type { TargetConfiguration } from "@visulima/task-runner";
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export type AffectedFilesMode = "args" | "both" | "env" | false;
+/** Supported OS filters for target execution. */
+export 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.
+ */
+export 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[];
+}
+/**
+ * Evaluates a `when` condition against the current process state.
+ * Returns `true` when the task should run, `false` when it should be
+ * skipped. Unknown shapes default to `true` — we'd rather over-run
+ * than silently hide tasks on malformed config.
+ */
+export declare const evaluateWhen: (when: TargetConditionObject | string | undefined, environment?: Record<string, string | undefined>, platform?: NodeJS.Platform) => boolean;
+export 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`.
+ */
+export 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;
+}
+/**
+ * Apply preset defaults to a target configuration. Returns a new
+ * object — never mutates its input.
+ */
+export declare const applyPreset: (target: VisTargetConfiguration) => VisTargetConfiguration;
+/** Detects the current operating system as a {@link TargetOsType}. */
+export declare const detectCurrentOs: () => TargetOsType;
+/**
+ * Returns `true` if the given OS matches the target's `osType` filter.
+ * Tasks without an `osType` option always match.
+ */
+export declare const matchesOs: (options: VisTargetOptions | undefined, currentOs?: TargetOsType) => boolean;
+/**
+ * Returns `true` if the task should run in the current environment based
+ * on its `runInCI` option. `affectedInCi` should indicate whether the
+ * project is in the current affected set (only relevant for `"affected"`).
+ */
+export declare const shouldRunInCI: (options: VisTargetOptions | undefined, isCi: boolean, affectedInCi?: boolean) => boolean;
+/**
+ * Resolves the `envFile` target option into a merged env map.
+ *
+ * - `string` → load that single file
+ * - `string[]` → load each in order; later entries win on key collision
+ * - `true` → load the Next/Vite cascade:
+ *   `.env` → `.env.{NODE_ENV}` → `.env.local` → `.env.{NODE_ENV}.local`
+ *   (`.env.local` skipped for NODE_ENV=test, matching Next.js)
+ *
+ * Silently skips files that don't exist. Returns `{}` when no file in
+ * the cascade is present — safe to merge directly into the child env.
+ */
+export declare const loadEnvFile: (projectRoot: string, envFile: boolean | string | string[]) => Record<string, string>;
+/**
+ * Pick the effective shell for a target on the current platform.
+ * Returns `undefined` if no per-target shell is configured.
+ */
+export declare const resolveTargetShell: (options: VisTargetOptions | undefined, currentOs?: TargetOsType) => string | undefined;
+/**
+ * Returns the default `cache` value implied by the target type.
+ * - `build`: cached by default.
+ * - `run`: never cached.
+ * - `test`: cached by default.
+ */
+export declare const defaultCacheForType: (type: TargetType | undefined) => boolean | undefined;

package/dist/tui/components/OutputPanel.d.ts

@@ -1,3 +1,4 @@
+import type { ScrollViewRef } from "@visulima/tui";
 import type { TaskRowData } from "./TaskRow.d.ts";
 interface OutputPanelProps {
     /** Duration in ms (for top-right border display). */
@@ -6,7 +7,7 @@ interface OutputPanelProps {
     /** Whether interactive input mode is active (keystrokes forwarded to PTY). */
     interactiveMode?: boolean;
     output: string;
-    scrollRef?: React.RefObject<import("@visulima/tui").ScrollViewRef>;
+    scrollRef?: React.RefObject<ScrollViewRef | null>;
     /** Whether to show "&lt;enter> full screen" hint in bottom border. */
     showFullscreenHint?: boolean;
     status: TaskRowData["status"] | undefined;

package/dist/tui/components/TaskListPanel.d.ts

@@ -11,7 +11,7 @@ interface TaskListPanelProps {
     parallelSlots?: number;
     pinnedTaskIds: [string | null, string | null];
     rows: TaskRowData[];
-    scrollRef: React.RefObject<ScrollViewRef>;
+    scrollRef: React.RefObject<ScrollViewRef | null>;
     selectedIndex: number;
     title: string;
 }

package/dist/tui/components/TaskStore.d.ts

@@ -47,7 +47,7 @@ export declare class TaskStore {
     #private;
     constructor(tasks: Task[]);
     getSnapshot: () => TaskState;
-    subscribe: (listener: Listener) => () => void;
+    subscribe: (listener: Listener) => (() => void);
     startTasks(started: Task[]): void;
     endTasks(results: TaskResult[]): void;
     addOutput(taskId: string, output: string): void;

package/dist/tui/components/devcontainer/DevcontainerStore.d.ts

@@ -35,7 +35,7 @@ export declare class DevcontainerStore {
     #private;
     constructor(config: DevcontainerConfig | null, hadComments: boolean, detectedPm?: PackageManager | null);
     getSnapshot: () => DevcontainerState;
-    subscribe: (listener: Listener) => () => void;
+    subscribe: (listener: Listener) => (() => void);
     setSection(section: SectionId): void;
     nextSection(): void;
     previousSection(): void;

package/dist/tui/components/devcontainer/catalogs/mount-suggestions.d.ts

@@ -16,4 +16,4 @@ export declare const FEATURE_MOUNTS: {
  * Get suggested mounts based on the package manager and enabled features.
  * Returns only mounts that are not already in the current config.
  */
-export declare const getSuggestedMounts: (pm: PackageManager | null, enabledFeatures: Record<string, Record<string, unknown> | string>, currentMounts: Array<MountEntry | string>) => MountEntry[];
+export declare const getSuggestedMounts: (pm: PackageManager | null, enabledFeatures: Record<string, Record<string, unknown> | string>, currentMounts: (MountEntry | string)[]) => MountEntry[];

package/dist/tui/components/devcontainer/sections/GeneralSection.d.ts

@@ -8,5 +8,5 @@ interface GeneralSectionProps {
 }
 declare const GeneralSection: ({ config, fieldEditing, fieldIndex, onUpdate }: GeneralSectionProps) => React.JSX.Element;
 export declare const GENERAL_FIELD_COUNT: number;
-export declare const GENERAL_BOOLEAN_FIELDS: readonly ("privileged" | "overrideCommand")[];
+export declare const GENERAL_BOOLEAN_FIELDS: ReadonlyArray<"privileged" | "overrideCommand">;
 export default GeneralSection;

package/dist/tui/components/devcontainer/sections/PreviewPanel.d.ts

@@ -5,7 +5,7 @@ interface PreviewPanelProps {
     readonly hadComments: boolean;
     readonly jsonPreview: string;
     readonly mode: "create" | "edit";
-    readonly scrollRef: React.RefObject<ScrollViewRef>;
+    readonly scrollRef: React.RefObject<ScrollViewRef | null>;
 }
 declare const PreviewPanel: ({ focused, hadComments, jsonPreview, mode, scrollRef }: PreviewPanelProps) => React.JSX.Element;
 export default PreviewPanel;

package/dist/tui/components/devcontainer/types.d.ts

@@ -29,16 +29,16 @@ export interface DevcontainerConfig {
     };
     dockerComposeFile?: string | string[];
     features?: Record<string, Record<string, unknown> | string>;
-    forwardPorts?: Array<number | string>;
+    forwardPorts?: (number | string)[];
     image?: string;
-    mounts?: Array<MountEntry | string>;
+    mounts?: (MountEntry | string)[];
     name?: string;
     onCreateCommand?: string | string[];
     overrideCommand?: boolean;
+    portsAttributes?: Record<string, PortAttributes>;
     postAttachCommand?: string | string[];
     postCreateCommand?: string | string[];
     postStartCommand?: string | string[];
-    portsAttributes?: Record<string, PortAttributes>;
     privileged?: boolean;
     remoteEnv?: Record<string, string>;
     remoteUser?: string;
@@ -50,4 +50,4 @@ export interface DevcontainerConfig {
     workspaceMount?: string;
 }
 export type SectionId = "compose" | "environment" | "extensions" | "features" | "general" | "lifecycle" | "mounts" | "ports";
-export declare const SECTION_ORDER: readonly SectionId[];
+export declare const SECTION_ORDER: ReadonlyArray<SectionId>;

package/dist/tui/components/graph/GraphStore.d.ts

@@ -25,7 +25,7 @@ export declare class GraphStore {
     #private;
     constructor(projectGraph: ProjectGraph);
     getSnapshot: () => GraphState;
-    subscribe: (listener: Listener) => () => void;
+    subscribe: (listener: Listener) => (() => void);
     getFilteredNodes(): GraphNode[];
     getStats(): {
         apps: number;

package/dist/tui/components/graph/ProjectDetailPanel.d.ts

@@ -4,7 +4,7 @@ import type { GraphNode } from "./GraphStore.d.ts";
 interface ProjectDetailPanelProps {
     focused: boolean;
     node: GraphNode | null;
-    scrollRef?: React.RefObject<ScrollViewRef>;
+    scrollRef?: React.RefObject<ScrollViewRef | null>;
 }
 declare const ProjectDetailPanel: ({ focused, node, scrollRef }: ProjectDetailPanelProps) => React.JSX.Element;
 export default ProjectDetailPanel;

package/dist/tui/components/optimize/OptimizeDetailPanel.d.ts

@@ -3,7 +3,7 @@ import type { OptimizeEntry } from "./OptimizeStore.d.ts";
 interface OptimizeDetailPanelProps {
     entry: OptimizeEntry | null;
     focused: boolean;
-    scrollRef?: React.RefObject<ScrollViewRef>;
+    scrollRef?: React.RefObject<ScrollViewRef | null>;
 }
 declare const OptimizeDetailPanel: ({ entry, focused, scrollRef }: OptimizeDetailPanelProps) => React.JSX.Element;
 export default OptimizeDetailPanel;

package/dist/tui/components/optimize/OptimizeStore.d.ts

@@ -32,7 +32,7 @@ declare class OptimizeStore {
     #private;
     constructor(entries: OptimizeEntry[]);
     getSnapshot: () => OptimizeState;
-    subscribe: (listener: Listener) => () => void;
+    subscribe: (listener: Listener) => (() => void);
     getFilteredEntries: () => OptimizeEntry[];
     select(index: number): void;
     toggleCheck(packageName: string): void;

package/dist/tui/components/update/PackageDetailPanel.d.ts

@@ -6,7 +6,7 @@ interface PackageDetailPanelProps {
     entry: OutdatedEntry | null;
     focused: boolean;
     recommendation?: AiRecommendation;
-    scrollRef?: React.RefObject<ScrollViewRef>;
+    scrollRef?: React.RefObject<ScrollViewRef | null>;
 }
 declare const PackageDetailPanel: ({ changelogUrl, entry, focused, recommendation, scrollRef }: PackageDetailPanelProps) => React.JSX.Element;
 export default PackageDetailPanel;

package/dist/tui/components/update/PackageListPanel.d.ts

@@ -4,9 +4,9 @@ interface PackageListPanelProps {
     checkedEntries: Set<string>;
     entries: OutdatedEntry[];
     filterActive: boolean;
+    filteredOutCount: number;
     filterText: string;
     filterType: FilterType;
-    filteredOutCount: number;
     focused: boolean;
     groupedByCatalog: Map<string, OutdatedEntry[]>;
     isDryRun: boolean;
@@ -17,5 +17,5 @@ interface PackageListPanelProps {
     totalEntries: number;
     viewportHeight: number;
 }
-declare const PackageListPanel: ({ checkedEntries, entries, filterActive, filterText, filterType, filteredOutCount, focused, groupedByCatalog, isDryRun, scrollOffset, selectedIndex, totalCatalogEntries, totalChecked, totalEntries, viewportHeight, }: PackageListPanelProps) => React.JSX.Element;
+declare const PackageListPanel: ({ checkedEntries, entries, filterActive, filteredOutCount, filterText, filterType, focused, groupedByCatalog, isDryRun, scrollOffset, selectedIndex, totalCatalogEntries, totalChecked, totalEntries, viewportHeight, }: PackageListPanelProps) => React.JSX.Element;
 export default PackageListPanel;

package/dist/tui/components/update/UpdateStore.d.ts

@@ -38,7 +38,7 @@ export declare class UpdateStore {
     #private;
     constructor(entries: OutdatedEntry[], aiResult?: AiAnalysisResult | null);
     getSnapshot: () => UpdateState;
-    subscribe: (listener: Listener) => () => void;
+    subscribe: (listener: Listener) => (() => void);
     /** Get the currently filtered + visible entries. */
     getFilteredEntries(): OutdatedEntry[];
     /** Get AI recommendation for a specific package. */

package/dist/tui/components/update/VisUpdateApp.d.ts

@@ -7,12 +7,12 @@ interface VisUpdateAppProps {
     changelogUrls?: Map<string, string>;
     /** Total unique packages checked by the registry. */
     checkedCount?: number;
-    /** Total catalog entries (before deduplication). */
-    totalCatalogEntries?: number;
     /** Packages that have newer versions but were filtered out by the target constraint. */
     filteredOutEntries?: OutdatedEntry[];
     isDryRun: boolean;
     store: UpdateStore;
+    /** Total catalog entries (before deduplication). */
+    totalCatalogEntries?: number;
 }
-declare const VisUpdateApp: ({ autoExitSeconds, changelogUrls, checkedCount, filteredOutEntries, isDryRun, store, totalCatalogEntries }: VisUpdateAppProps) => React.JSX.Element;
+declare const VisUpdateApp: ({ autoExitSeconds, changelogUrls, checkedCount, filteredOutEntries, isDryRun, store, totalCatalogEntries, }: VisUpdateAppProps) => React.JSX.Element;
 export default VisUpdateApp;

package/dist/tui/dynamic-life-cycle.d.ts

@@ -1,5 +1,6 @@
 import type { LifeCycleInterface, Task } from "@visulima/task-runner";
 import { TaskStore } from "./components/TaskStore.d.ts";
+import type { StdinEntry } from "./types.d.ts";
 interface DynamicOutputOptions {
     args: {
         parallel?: boolean | number;
@@ -9,7 +10,7 @@ interface DynamicOutputOptions {
     autoExit?: boolean | number;
     projectNames: string[];
     /** Registry of writable stdin entries keyed by task ID, for interactive input. */
-    stdinRegistry?: Map<string, import("./types").StdinEntry>;
+    stdinRegistry?: Map<string, StdinEntry>;
     tasks: Task[];
 }
 interface DynamicOutputResult {

package/dist/tui/static-life-cycle.d.ts

@@ -1,8 +1,14 @@
-import type { LifeCycleInterface, Task, TaskResult, TaskStatus } from "@visulima/task-runner";
+import type { LifeCycleInterface, LogReporter, Task, TaskResult, TaskStatus } from "@visulima/task-runner";
 interface StaticOutputOptions {
     args: {
         targets: string[];
     };
+    /**
+     * Optional {@link LogReporter} that takes over `printTaskTerminalOutput`
+     * when the user picks a `--log` mode. Absent, the CI-style
+     * separator+status formatting is kept (vis's default).
+     */
+    logReporter?: LogReporter;
     projectNames: string[];
     tasks: Task[];
 }

package/dist/watch.d.ts

@@ -0,0 +1,65 @@
+import type { TaskResults } from "@visulima/task-runner";
+/**
+ * Debounced multi-directory file watcher. Watches one or more project
+ * roots recursively and invokes `onChange` at most once per debounce
+ * window. Ignores edits inside `node_modules` and `.git`.
+ *
+ * `node:fs.watch({ recursive: true })` is supported on Linux, macOS,
+ * and Windows since Node 20+, so no additional dependency is needed.
+ */
+export interface WatchHandle {
+    close: () => void;
+}
+export interface WatchOptions {
+    /** Debounce window in milliseconds. Defaults to 150 ms. */
+    debounceMs?: number;
+    /**
+     * Optional predicate invoked against every raw file event
+     * (relative path as provided by `node:fs.watch`). Used by
+     * tracked-access watch mode to drop changes to files the last
+     * run didn't actually read. Return `false` to discard the event.
+     */
+    filter?: (path: string) => boolean;
+    /** Fired when a watched file changes (after debounce). */
+    onChange: (changedPaths: string[]) => void | Promise<void>;
+    /** Project roots to watch, resolved to absolute paths. */
+    paths: string[];
+}
+/**
+ * The set of workspace-relative paths that a run actually read, plus
+ * the minimal set of directories that contain them. Used by
+ * tracked-access watch mode to only re-trigger runs when a file the
+ * previous run actually consumed changes — drops noise from unrelated
+ * edits under the project roots.
+ *
+ * `files` stays workspace-relative because `node:fs.watch` emits
+ * paths relative to the watched root.
+ */
+export interface TrackedWatchTargets {
+    directories: string[];
+    files: Set<string>;
+}
+/**
+ * Extracts the set of files every task in `results` reported as an
+ * input. Returns empty sets when no task carries hash details — the
+ * caller falls back to watching project roots in that case.
+ *
+ * Directories are deduplicated and pruned so a parent dir shadows its
+ * descendants — watching both would double-fire events.
+ */
+export declare const collectTrackedWatchTargets: (results: TaskResults, workspaceRoot: string) => TrackedWatchTargets;
+/**
+ * Translates a set of workspace-relative tracked paths into a filter
+ * suitable for {@link startWatcher}. The watcher emits paths relative
+ * to its watched root — which, after pruning, may be any ancestor
+ * directory — so we match on the **suffix** of the tracked path
+ * instead of an exact comparison.
+ */
+export declare const createTrackedFileFilter: (trackedFiles: Set<string>, workspaceRoot: string, watchedDirectories: string[]) => ((path: string) => boolean);
+/**
+ * Starts recursive file watchers on the given paths and invokes
+ * {@link WatchOptions.onChange} after a debounce window.
+ * @param options Watcher configuration.
+ * @returns A handle to close all watchers.
+ */
+export declare const startWatcher: (options: WatchOptions) => WatchHandle;