@visulima/vis 1.0.0-alpha.9 → 1.0.1

package/README.md

@@ -6,7 +6,7 @@
 
 </a>
 
-<h3 align="center">A CLI task runner for monorepo workspaces, powered by @visulima/task-runner</h3>
+<h3 align="center">A monorepo dev toolkit — task runner, remote caching, security scanning, git hooks, and AI agent integrations — powered by @visulima/task-runner</h3>
 
 <!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
@@ -36,17 +36,59 @@
 
 ## Features
 
-- **Workspace-aware**: Automatically discovers projects from `pnpm-workspace.yaml` or `package.json` workspaces
-- **Task caching**: Powered by `@visulima/task-runner` with local and remote caching support
-- **Dependency-aware scheduling**: Runs tasks in topological order with configurable parallelism
-- **Affected detection**: Only runs tasks for projects changed since a given git ref
-- **Pluggable installer**: Defaults to the lockfile-detected PM (pnpm/npm/yarn/bun); auto-uses [aube](https://github.com/endevco/aube) when on `PATH`, with a single switch (`install.backend` / `--installer` / `--no-aube`) to pin or bypass it
-- **Catalog management**: Check and update dependencies in pnpm/bun workspace catalogs
-- **Security scanning**: Check for known vulnerabilities via OSV.dev
-- **Graph visualization**: View your project dependency graph in ASCII, DOT, JSON, or HTML
-- **Git hooks**: Install, manage, and migrate git hooks (husky migration supported)
-- **Configurable**: `vis.json` for target defaults, cache settings, and task runner options
-- **Built on Cerebro**: Uses `@visulima/cerebro` for a robust CLI experience with built-in help, version, and completion
+### Built for AI agents
+
+- **MCP server** — `@visulima/vis-mcp` exposes 8 read-only introspection tools to Claude / Cursor / Copilot (project graph, target list, run logs, cache-why, template schema), plus a paired Claude Skill that documents optimal usage
+- **`vis ai heal`** — reads failing tasks, asks the configured AI provider for a structured patch, validates by re-running, posts a markdown comment to the PR/MR. `/vis heal accept` from an allow-listed maintainer lands the fix as a signed commit (GitHub Actions, GitLab CI, Buildkite)
+- **Worktree-aware shared cache** — N parallel agents in N sibling git worktrees automatically share one cache instead of rebuilding the same hash N times
+
+### Production-grade caching
+
+- **REAPI gRPC + HTTP backends** — drop-in support for [bazel-remote](https://github.com/buchgr/bazel-remote), BuildBuddy, BuildBarn, EngFlow alongside Turbo-compatible HTTP. `vis cache doctor` probes reachability, capabilities, and latency for CI gating
+- **`vis cache why <task>`** — diff hash buckets (`command`, `nodes`, `runtime`, `implicitDeps`) against the previous run to pinpoint exactly what rotated the hash
+- **HMAC-SHA256 signed artifacts** — `verifyOnDownload` locks production caches against tampering with constant-time comparison
+- **Cache restoration fidelity** — preserves mtime + permission bits + colorized output; `vis cache verify <task>` flags drift between cached archive and live workspace
+- **Retention controls** — `vis cache prune --keep-last/--max-age-days/--max-size`
+
+### Cross-invocation devloop
+
+- **`vis service start|stop|list`** — long-lived DB / mock / devserver lifecycle that survives across `vis run` calls within a shell session; auto-attached when targets declare `service:` in their config (no more "I keep restarting Postgres between every test run")
+- **`vis run --watch`** — Vitest-style keybinds (`r/Enter/a/p/q/Ctrl+C/h/?`), Windows-clean SIGINT
+- **`vis run --output-style=quiet`** — swallow stdout from successful and cached tasks, keep failures fully visible
+
+### Workspace orchestration
+
+- **Workspace-aware** — discovers projects from `pnpm-workspace.yaml`, `package.json` workspaces, and bun
+- **Topological scheduling** with configurable parallelism and runner-tag filtering
+- **Affected detection** — `vis affected <target>`, plus `${affected.files}` / `$AFFECTED_FILES` token forwarding to the underlying script
+- **Conditional + finally tasks** — `when:` (os/env/branch/ci) and top-level `always: true`
+- **Per-package overlay + extends chain** — root `vis-config.ts` + per-project `vis.task.ts`, with bare-specifier preset resolution
+- **Inferred targets** (Project Crystal-style) — optional synthesis of `build`/`test`/`dev`/`lint`/`format` from 36 tools (Vite, Vitest, Next, Nuxt, packem, ESLint, Biome, Prisma, …). Opt in with `inferTargets: true`; explicit scripts and `project.json`/`vis.task.ts` overrides always win
+- **URI-based input format** — `inputs` accepts `file://`, `glob://`, `env://`, `func://`, `dep://` strings as forward-compat sugar
+- **Plugin / fingerprint hooks** — 14 typed hooks via `definePlugin` (lifecycle, streaming, retry, fingerprint, services), built on `hookable`
+- **Strict env mode** — `--strict-env` extracts `${VAR}` references from each command and fails the task if any are unset
+- **Lockfile preflight** — warns in TTY, hard-fails in CI when the lockfile is newer than the install marker
+- **Project graph** — view dependencies in ASCII, DOT, JSON, or HTML
+
+### Adjacent tooling that ships in-box
+
+- **`vis catalog check / update`** — pnpm + bun workspace catalog management
+- **`vis secrets`** — Rust-native secret scanning (gitleaks detection engine)
+- **`vis audit`** — OSV.dev vulnerability scanning with pluggable supply-chain providers ([Socket.dev](https://socket.dev) and [Google deps.dev](https://deps.dev), merged when both are enabled). `--explain` adds a plain-English AI explanation per finding (auto-detects an installed AI CLI, cached, no API key) in the terminal, JSON, and HTML report
+- **`vis docker scaffold`** — lockfile pruning for pnpm / npm / yarn classic + berry / bun, matching turbo's killer Docker-cache feature
+- **`vis hook install / migrate`** — git hooks (husky migration supported)
+- **`vis staged`** — built-in `lint-staged` replacement, no peer dependency
+- **`vis migrate gitleaks|secretlint`** — incremental migration paths
+- **`vis replay <runId>`** — re-render any past run summary without re-execution
+
+### Toolchain & runtime
+
+- **Pluggable installer** — defaults to the lockfile-detected PM (pnpm/npm/yarn/bun); auto-uses [aube](https://github.com/endevco/aube) when on `PATH`, with a single switch (`install.backend` / `--installer` / `--no-aube`) to pin or bypass it
+- **Cold-start one-liner** — `curl -fsSL https://visulima.com/install.sh | bash` (Linux/macOS/WSL) or PowerShell equivalent installs the latest Node LTS (or a version manager on request) and `vis`
+- **`vis toolchain`** — delegates to proto / mise / fnm / volta
+- **Built on Cerebro** — robust CLI with built-in help, version, and shell completion
+
+> **New to vis?** See [Why vis vs. Vite Task / Turbo / Nx / moon](./docs/guides/why-vis.mdx) for the side-by-side capability matrix.
 
 ## Install
 
@@ -62,9 +104,17 @@ yarn add @visulima/vis
 pnpm add @visulima/vis
 ```
 
+### Binaries
+
+`@visulima/vis` installs four executables:
+
+- `vis` — the full CLI (recommended; use this in scripts and CI).
+- `v` — a short alias for `vis`. Note that `v` collides with the [V language](https://vlang.io/) compiler and is a common personal shell alias, so it may be shadowed. Prefer `vis` for anything you commit; see [`docs/guides/shell-alias.mdx`](./docs/guides/shell-alias.mdx) if you want your own short alias.
+- `vx` / `visx` — the lean `dlx`-only entry point for one-off package execution.
+
 ### Cold start (no Node? no manager?)
 
-One-liner bootstrap that installs a version manager, Node LTS, and `vis` in one go.
+One-liner bootstrap that installs Node and `vis` in one go. When no Node is found it installs the latest Node LTS directly by default (OS package manager, falling back to the official nodejs.org build); a version manager (proto / fnm / mise / volta) is offered as an opt-in alternative. Pin a specific major with `VIS_NODE_MAJOR`.
 
 **Linux / macOS / WSL** (bash):
 
@@ -98,7 +148,9 @@ vis check
 # Check with security vulnerability scanning
 vis check --security
 
-# Update catalog dependencies interactively
+# Update catalog dependencies interactively, plus any
+# GitHub Actions, Dockerfile, docker-compose, or GitLab CI
+# references in the workspace (auto-detected).
 vis update --interactive
 
 # Install git hooks
@@ -119,10 +171,12 @@ brew install endevco/tap/aube
 
 Resolution precedence (highest first):
 
-1. `--installer <name>` CLI flag (or `--no-aube` to force the lockfile-detected PM for one run)
-2. `VIS_INSTALLER` environment variable
-3. `install.backend` in `vis.config.ts`
-4. Auto-detect — uses `aube` when it's on `PATH`, otherwise the lockfile-detected PM
+1. `--installer <name>` CLI flag — `auto`, `aube`, `pnpm`, `npm`, `yarn`, or `bun` (or `--no-aube` to force the lockfile-detected PM for a single run; `--no-aube` wins over every other source).
+2. `VIS_INSTALLER` environment variable — same accepted values as the flag.
+3. `install.backend` in `vis.config.ts` — same accepted values; the team-wide pin.
+4. Auto-detect — `aube` when it's on `PATH` or `aube-lock.yaml` is present, otherwise the lockfile-detected PM (`pnpm-lock.yaml` → pnpm, `package-lock.json` → npm, `yarn.lock` → yarn, `bun.lockb` → bun).
+
+Each step is consulted in order; the first one that resolves to a concrete backend wins. Picking an explicit value (`pnpm`, `npm`, …) at any level always beats the auto-detect step below it, so you can override the team default for a single shell session via `VIS_INSTALLER=pnpm vis install` without touching the config file.
 
 ```ts
 // vis.config.ts — pin the installer for the team
@@ -141,32 +195,98 @@ Aube reuses pnpm/npm/yarn/bun lockfile formats but its serialized output isn't b
 
 Aube already skips dependency lifecycle scripts by default. `--ignore-scripts` is a no-op under aube (`vis install` warns when you pass it). To opt specific packages back in, run `aube approve-builds` — the inverse direction from the pnpm/npm `--ignore-scripts` model.
 
+### Audit delegation
+
+When aube is the active installer, `vis audit` delegates to `aube audit` so a single, consistent vulnerability scan runs regardless of entry point. Resolution mirrors the installer chain:
+
+1. `--backend <name>` CLI flag — `auto`, `aube`, or `vis`.
+2. `VIS_AUDIT_BACKEND` env var.
+3. `security.audit.backend` in `vis.config.ts`.
+4. Defaults to `auto` — delegates only when `install.backend` (or `VIS_INSTALLER`) resolves to aube AND `aube` is on `PATH`.
+
+Vis-only features (`--report`, `--fix-transitive`, `--usage`, `--policies`, `--format sarif|csaf|cyclonedx-vex|gitlab|junit`, `--ecosystem` beyond npm) print a warning and are dropped when delegating; pass `--backend vis` to force the built-in OSV/Socket scanner.
+
+### Doctor visibility
+
+When aube is the installer, `vis doctor` surfaces aube's effective hardening posture (`paranoid`, `trustPolicy`, `blockExoticSubdeps`, `jailBuilds`, `strictDepBuilds`, `minimumReleaseAge`, `allowBuilds`) alongside the existing vis `security.policies.*` findings, reading from `aube-workspace.yaml` (or falling back to `pnpm-workspace.yaml`). Aube's defaults are already hardened, so most entries render as `ok` — the section turns into a positive confirmation rather than a wall of warnings.
+
 ## Commands
 
-| Command                 | Alias  | Description                                                          |
-| ----------------------- | ------ | -------------------------------------------------------------------- |
-| `vis create [template]` |        | Scaffold a new project from templates, npm packages, or git repos    |
-| `vis generate [name]`   |        | Scaffold files from an in-repo template (native TS or moon-format)   |
-| `vis init`              |        | Initialize vis.config.ts with security defaults                      |
-| `vis run <target>`      |        | Run a target across workspace projects with caching                  |
-| `vis affected <target>` |        | Run tasks only on projects affected by git changes                   |
-| `vis ignore <project>`  |        | CI build gating for Vercel / Netlify "Ignored Build Step"            |
-| `vis graph`             |        | Visualize the project dependency graph                               |
-| `vis check [packages]`  | `c`    | Check for outdated dependencies in workspace catalogs                |
-| `vis update [packages]` | `up`   | Update packages to their latest versions                             |
-| `vis install`           | `i`    | Install dependencies via the detected package manager                |
-| `vis info <package>`    | `view` | Show npm registry metadata for a package (wraps `npm view` et al.)   |
-| `vis dlx <package>`     |        | Execute a remote package without permanent installation              |
-| `vis audit`             |        | Audit dependencies for security vulnerabilities                      |
-| `vis clean`             |        | Remove build artifacts, caches, and node_modules                     |
-| `vis hook <action>`     |        | Manage git hooks (install, uninstall, migrate)                       |
-| `vis secrets [paths]`   |        | Scan for hardcoded secrets / credentials (Rust-native)               |
-| `vis toolchain <cmd>`   |        | Inspect / delegate to the version manager (proto, mise, fnm, volta…) |
-| `vis staged`            |        | Run tasks on staged files (built-in `lint-staged` replacement)       |
-| `vis migrate <type>`    |        | Migrate from other tools — now including `gitleaks` and `secretlint` |
+| Command                 | Alias  | Description                                                                            |
+| ----------------------- | ------ | -------------------------------------------------------------------------------------- |
+| `vis create [template]` |        | Scaffold a new project from templates, npm packages, or git repos                      |
+| `vis generate [name]`   |        | Scaffold files from an in-repo template (native TS or moon-format)                     |
+| `vis init`              |        | Initialize vis.config.ts with security defaults                                        |
+| `vis run <target>`      |        | Run a target across workspace projects with caching                                    |
+| `vis affected <target>` |        | Run tasks only on projects affected by git changes                                     |
+| `vis ignore <project>`  |        | CI build gating for Vercel / Netlify "Ignored Build Step"                              |
+| `vis graph`             |        | Visualize the project dependency graph                                                 |
+| `vis check [packages]`  | `c`    | Check for outdated dependencies in workspace catalogs                                  |
+| `vis update [packages]` | `up`   | Update packages, GitHub Actions, Dockerfiles, and GitLab CI refs                       |
+| `vis install`           | `i`    | Install dependencies via the detected package manager                                  |
+| `vis info <package>`    | `view` | Show npm registry metadata for a package (wraps `npm view` et al.)                     |
+| `vis dlx <package>`     |        | Execute a remote package without permanent installation                                |
+| `vis audit`             |        | Audit dependencies for security vulnerabilities                                        |
+| `vis clean`             |        | Remove build artifacts, caches, and node_modules                                       |
+| `vis cache <action>`    |        | Inspect cache (`list`, `size`, `hash`, `why`), or `prune` / `clean`                    |
+| `vis hook <action>`     |        | Manage git hooks (install, uninstall, migrate)                                         |
+| `vis secrets [paths]`   |        | Scan for hardcoded secrets / credentials (Rust-native)                                 |
+| `vis toolchain <cmd>`   |        | Inspect / delegate to the version manager (proto, mise, fnm, volta…)                   |
+| `vis lint [files]`      |        | Orchestrate detected source-code linters (oxlint, biome, eslint, stylelint, deno-lint) |
+| `vis fmt [files]`       |        | Orchestrate detected formatters (oxfmt, biome, dprint, prettier, deno-fmt)             |
+| `vis staged`            |        | Run tasks on staged files (built-in `lint-staged` replacement)                         |
+| `vis migrate <type>`    |        | Migrate from other tools — now including `gitleaks` and `secretlint`                   |
 
 For `vis ignore`, see the [command reference](./docs/commands/ignore.mdx) and the [deployment build gating section](./docs/guides/ci-cd.mdx#deployment-build-gating) of the CI/CD guide.
 
+### Diagnosing cache misses
+
+When a task you expected to be cached re-ran, ask vis what changed:
+
+```sh
+vis cache why @myorg/app:build           # human-friendly diff vs. previous run
+vis cache why @myorg/app:build --json    # stable shape for CI
+vis cache hash @myorg/app:build          # just print the hash + per-bucket inputs
+```
+
+`vis cache why` reads `.task-runner/last-summary.json` and diffs the task's `hashDetails` (`command`, `nodes`, `runtime`, `implicitDeps`) against the previous run, so you can pinpoint exactly which bucket rotated. Past runs only land in `.task-runner/runs/` when you pass `--summarize`, so use `vis run :build --summarize` (or set it as a default in CI) for diffs you'll want to inspect later.
+
+### Cache retention
+
+`vis cache prune` evicts entries by any combination of age, total size, and count:
+
+```sh
+vis cache prune --max-age-days=7              # drop entries older than a week
+vis cache prune --max-size=2GB                # evict oldest until under 2 GB
+vis cache prune --keep-last=30                # keep only the 30 newest entries
+vis cache prune --keep-last=30 --max-age-days=14   # combine: 30-newest floor, then age cap
+```
+
+`--keep-last` enforces a count floor first (newest-first by mtime), then `--max-age-days` and `--max-size` apply.
+
+### Sharing the cache across git worktrees
+
+When the workspace is a linked worktree (created with `git worktree add`), vis stores the cache at `<mainWorktreeRoot>/.task-runner-cache` so sibling worktrees driven by parallel agents share one cache instead of rebuilding the same hash N times. Set `sharedWorktreeCache: false` in `vis.config.ts` to opt out, or use `--scope=worktree|shared|all` on `vis cache list/size/prune` to inspect or operate on a specific store.
+
+### Quieting successful runs
+
+`--output-style=quiet` skips stdout/stderr from successful and cached tasks while keeping failures fully visible. Pair it with per-target `options.outputStyle` to mute a single noisy task — or to keep one critical task verbose under a global quiet flag:
+
+```sh
+vis run :build --output-style=quiet     # only failures print
+```
+
+```json
+{
+    "targets": {
+        "lint": { "options": { "outputStyle": "quiet" } },
+        "migrate": { "options": { "outputStyle": "normal" } }
+    }
+}
+```
+
+See the [`vis cache`](./docs/commands/cache.mdx) and [`vis run`](./docs/commands/run.mdx) command references for the full surface.
+
 ### Scanning for secrets
 
 `vis secrets` wraps [`@visulima/secret-scanner`](../secret-scanner) — a Rust port of the gitleaks detection engine — with ergonomic flags for the common workflows.
@@ -289,6 +409,42 @@ vis migrate lint-staged    # moves the config into vis.config.ts and rewrites ho
 
 The migrator detects `package.json` keys, `.lintstagedrc*` files, and `lint-staged.config.*`, prompts before rewriting husky/vis hooks to call `vis staged`, and removes `lint-staged` from the dependency list.
 
+## Configuration API
+
+The `@visulima/vis/config` subpath export is the programmatic surface for typed config and the plugin system. It ships more than `defineConfig`:
+
+| Export                                                                                               | Kind     | Purpose                                                            |
+| ---------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------ |
+| `defineConfig`                                                                                       | function | Type-checked `vis.config.ts` helper (root config).                 |
+| `defineTaskConfig`                                                                                   | function | Type-checked task-only config (`vis.task.config.ts`).              |
+| `definePlugin`                                                                                       | function | Author a vis plugin (hooks, fingerprint contributors, OTel, …).    |
+| `otelPlugin`                                                                                         | function | Built-in OpenTelemetry plugin factory.                             |
+| `loadVisConfig` / `loadVisTaskConfig`                                                                | function | Resolve + load the config from disk programmatically.              |
+| `findVisConfigFile` / `findVisTaskConfigFile`                                                        | function | Locate the config file without loading it.                         |
+| `applyDefaults`                                                                                      | function | Merge a partial config with vis defaults.                          |
+| `CONFIG_FILES` / `TASK_CONFIG_FILES`                                                                 | const    | The recognised config filenames, in resolution order.              |
+| `SECURITY_DEFAULTS`                                                                                  | const    | The default audit/security policy applied when none is configured. |
+| `VisConfig`, `VisTaskConfig`, `VisPlugin`, `VisHooks`, `OtelPluginOptions`, `FingerprintContributor` | type     | Public config & plugin types.                                      |
+
+```ts
+import { defineConfig, definePlugin, otelPlugin } from "@visulima/vis/config";
+
+const auditLogger = definePlugin({
+    name: "audit-logger",
+    hooks: {
+        "task:after": (task, result) => {
+            console.log(`${task.id} finished with exit code ${result.exitCode}`);
+        },
+    },
+});
+
+export default defineConfig({
+    plugins: [auditLogger, otelPlugin({ serviceName: "my-monorepo" })],
+});
+```
+
+See [`docs/configuration.mdx`](./docs/configuration.mdx) for the full config model and [`docs/guides/plugins.mdx`](./docs/guides/plugins.mdx) for the plugin authoring guide. A `@visulima/vis/generate` subpath export is also available for programmatic scaffolding.
+
 ## Documentation
 
 For full documentation including command reference, configuration options, best practices, and CI/CD integration guides, see the [docs](./docs) folder.
@@ -309,6 +465,26 @@ If you would like to help take a look at the [list of issues](https://github.com
 - [Daniel Bannert](https://github.com/prisis)
 - [All Contributors](https://github.com/visulima/visulima/graphs/contributors)
 
+### Migration sources
+
+`vis migrate` ports configuration, scripts, and hooks from the following projects. Huge thanks to their authors and maintainers for the prior art that shaped vis's surface area.
+
+| Project                                                    | Migrates with             | Replaces                    |
+| ---------------------------------------------------------- | ------------------------- | --------------------------- |
+| [Husky](https://github.com/typicode/husky)                 | `vis hook migrate`        | Git hook manager            |
+| [lint-staged](https://github.com/lint-staged/lint-staged)  | `vis migrate lint-staged` | Pre-commit task runner      |
+| [nano-staged](https://github.com/usmanyunusov/nano-staged) | `vis migrate nano-staged` | Pre-commit task runner      |
+| [Turborepo](https://github.com/vercel/turborepo)           | `vis migrate turborepo`   | Monorepo task runner        |
+| [Nx](https://github.com/nrwl/nx)                           | `vis migrate nx`          | Monorepo task runner        |
+| [Moon](https://github.com/moonrepo/moon)                   | `vis migrate moon`        | Monorepo task runner        |
+| [Gitleaks](https://github.com/gitleaks/gitleaks)           | `vis migrate gitleaks`    | Secret scanner              |
+| [Kingfisher](https://github.com/mongodb/kingfisher)        | `vis migrate kingfisher`  | Secret scanner (MongoDB)    |
+| [Secretlint](https://github.com/secretlint/secretlint)     | `vis migrate secretlint`  | Secret linter               |
+| [Syncpack](https://github.com/JamieMason/syncpack)         | `vis migrate syncpack`    | Workspace dependency policy |
+| [Sherif](https://github.com/QuiiBz/sherif)                 | `vis migrate sherif`      | Monorepo linter             |
+
+After migrating a task runner, run `vis migrate verify-graph` to prove the migration preserved the task graph and cache-key surface — it diffs the original `turbo` / `nx` / `moon` config against the generated `vis.config.*` across six axes (target set, `dependsOn`, `inputs`, `outputs`, `env`, `cache`) and exits non-zero on any dropped task or narrowed cache key, so it can gate CI.
+
 ## Made with ❤️ at Anolilab
 
 This is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. [Anolilab](https://www.anolilab.com/open-source) is a Development and AI Studio. Contact us at [hello@anolilab.com](mailto:hello@anolilab.com) if you need any help with these technologies or just want to say hi!

package/bin/resolve-binary.mjs

@@ -0,0 +1,85 @@
+// Platform resolution for the native `vis` CLI binary. Shared by the launcher
+// (`bin/vis.mjs`) and the integration tests so there is a single source of truth
+// for where the binary lives and how the platform -> binding-package target slug
+// is computed (mirroring the NAPI loader matrix in `index.js`).
+
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+const require = createRequire(import.meta.url);
+
+// Best-effort musl detection for Linux. Defaults to glibc on any uncertainty.
+const isMusl = () => {
+    const report = typeof process.report?.getReport === "function" ? process.report.getReport() : undefined;
+
+    if (report && Array.isArray(report.sharedObjects)) {
+        return report.sharedObjects.some((object) => object.includes("libc.musl-") || object.includes("ld-musl-"));
+    }
+
+    // Default to glibc on uncertainty (no report). musl is identified by the
+    // absence of glibcVersionRuntime; matches handler.ts's copy.
+    return report ? !report.header?.glibcVersionRuntime : false;
+};
+
+// Static platform+arch -> target slug table for the non-Linux targets (Linux is
+// libc-dependent, so it is resolved separately).
+const STATIC_TARGETS = {
+    "darwin:arm64": "darwin-arm64",
+    "darwin:x64": "darwin-x64",
+    "win32:arm64": "win32-arm64-msvc",
+    "win32:x64": "win32-x64-msvc",
+};
+
+// Compute the binding-package target slug for the current platform, or undefined
+// for platforms with no published binary.
+const nativeTarget = () => {
+    const { arch, platform } = process;
+
+    if (platform === "linux") {
+        const libc = isMusl() ? "musl" : "gnu";
+
+        if (arch === "arm64" || arch === "x64") {
+            return `linux-${arch}-${libc}`;
+        }
+
+        return undefined;
+    }
+
+    return STATIC_TARGETS[`${platform}:${arch}`];
+};
+
+// Resolve the platform-specific `vis` binary, or undefined if none is available
+// (e.g. the optional binding package was not installed for this platform).
+// Resolution order, most specific first:
+//   1. VIS_NATIVE_BIN env override (dev / CI / tests).
+//   2. A binary placed next to the package (local `build:native:cli` output).
+//   3. The matching `@visulima/vis-binding-<target>` optional dependency.
+const resolveNativeBinary = (packageRoot) => {
+    const override = process.env.VIS_NATIVE_BIN;
+
+    if (override && existsSync(override)) {
+        return override;
+    }
+
+    const exe = process.platform === "win32" ? "vis-native-cli.exe" : "vis-native-cli";
+    const local = join(packageRoot, exe);
+
+    if (existsSync(local)) {
+        return local;
+    }
+
+    const target = nativeTarget();
+
+    if (target === undefined) {
+        return undefined;
+    }
+
+    try {
+        return require.resolve(`@visulima/vis-binding-${target}/${exe}`);
+    } catch {
+        return undefined;
+    }
+};
+
+export { nativeTarget, resolveNativeBinary };

package/bin/vis.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// Native front-end launcher for `vis`.
+//
+// This is the npm `bin` entry. Its only jobs are to (1) route the small set of
+// natively-implemented commands to the platform Rust binary, and (2) fall
+// through to the existing in-process Node CLI for everything else. The
+// fall-through path is byte-identical to running `dist/bin.js` directly, so the
+// launcher adds no extra Node boot for delegated commands — it `import()`s the
+// same entry in the same process.
+//
+// As commands are ported off Node, their names are added to NATIVE_COMMANDS and
+// the binary grows to handle them; the binary itself delegates anything it does
+// not implement back to `dist/bin.js` via the VIS_* contract.
+
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { constants } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { resolveNativeBinary } from "./resolve-binary.mjs";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+// VIS_FALLBACK_ENTRY lets tests (and the native binary's own delegation) point
+// the Node entry elsewhere; production resolves it next to the package.
+const fallbackEntry = process.env.VIS_FALLBACK_ENTRY ?? join(packageRoot, "dist", "bin.js");
+
+// Commands answered by the native binary. Every entry here MUST be handled by
+// the binary (natively or via its own Node delegation), with VERIFIED parity to
+// the Node behavior. Unknown commands never reach the binary — they take the
+// in-process path below, unchanged. NOTE: `-v` is cerebro's verbose flag (not
+// version), so it is deliberately absent.
+//
+// `exec` parity was verified empirically against cerebro: tool flags after the
+// command are forwarded to the tool on both the native path and the Node handler
+// (src/commands/exec/handler.ts), which was fixed to stop dropping them.
+const NATIVE_COMMANDS = new Set(["--version", "-V", "__native-info", "__pm-shim", "dedupe", "exec", "link", "outdated", "pm", "remove", "unlink", "why", "x"]);
+
+const command = process.argv[2] ?? "";
+
+if (NATIVE_COMMANDS.has(command)) {
+    const binary = resolveNativeBinary(packageRoot);
+
+    if (binary !== undefined) {
+        const { version } = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+
+        const { error, signal, status } = spawnSync(binary, process.argv.slice(2), {
+            env: {
+                ...process.env,
+                VIS_FALLBACK_ENTRY: fallbackEntry,
+                VIS_NODE: process.execPath,
+                VIS_VERSION: version,
+            },
+            stdio: "inherit",
+        });
+
+        if (error) {
+            // Binary unusable (e.g. corrupt install) — fall through to Node.
+            process.env.VIS_NATIVE_BIN_FAILED = "1";
+        } else if (signal) {
+            // Signal-terminated: follow the shell convention (128 + signal number)
+            // so the exit code matches the binary's own delegation path.
+            process.exit(128 + (constants.signals[signal] ?? 1));
+        } else {
+            process.exit(status ?? 1);
+        }
+    }
+    // No binary for this platform: fall through to the Node CLI below.
+}
+
+// In-process Node CLI. Same module graph and behaviour as invoking dist/bin.js
+// directly — no extra process boot. fallbackEntry is an internally-resolved path
+// (never user input); pathToFileURL keeps the dynamic import valid on Windows.
+// eslint-disable-next-line no-unsanitized/method -- fallbackEntry is resolved internally, not from user input
+await import(pathToFileURL(fallbackEntry).href);