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

package/README.md

@@ -6,7 +6,7 @@
 
 </a>
 
-<h3 align="center">A CLI task runner for monorepo workspaces</h3>
+<h3 align="center">A CLI task runner for monorepo workspaces, powered by @visulima/task-runner</h3>
 
 <!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
@@ -40,6 +40,7 @@
 - **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
@@ -61,6 +62,24 @@ yarn add @visulima/vis
 pnpm add @visulima/vis
 ```
 
+### Cold start (no Node? no manager?)
+
+One-liner bootstrap that installs a version manager, Node LTS, and `vis` in one go.
+
+**Linux / macOS / WSL** (bash):
+
+```sh
+curl -fsSL https://visulima.com/install.sh | bash
+```
+
+**Windows** (PowerShell 5.1+):
+
+```powershell
+irm https://visulima.com/install.ps1 | iex
+```
+
+Pass `--yes --manager=proto` (POSIX) or `-Yes -Manager proto` (PowerShell) for non-interactive / CI usage. See [`vis toolchain` docs](./docs/commands/toolchain.mdx#cold-start--no-node-no-manager) for details.
+
 ## Quick Start
 
 ```bash
@@ -86,16 +105,238 @@ vis update --interactive
 vis hook install
 ```
 
+## Installer backend (aube)
+
+`vis install`, `vis add`, `vis remove`, `vis update`, `vis dlx`, `vis exec`, `vis link`, `vis unlink`, `vis dedupe`, `vis why`, `vis outdated`, `vis info`, and `vis pm` honor [aube](https://github.com/endevco/aube) — a Rust-native package manager that reads and writes pnpm/npm/yarn/bun lockfiles in place — as a drop-in installer. Aube also supports the pnpm `catalog:` and `catalog:<name>` protocol from `pnpm-workspace.yaml`, including walk-up resolution from subpackages.
+
+`vis` does not bundle aube. Install it once via your tool of choice and `vis` will auto-detect it on `PATH`:
+
+```bash
+npm install -g @endevco/aube       # or
+mise use -g aube                   # or
+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
+
+```ts
+// vis.config.ts — pin the installer for the team
+import { defineConfig } from "@visulima/vis/config";
+
+export default defineConfig({
+    install: { backend: "aube" }, // "auto" | "aube" | "pnpm" | "npm" | "yarn" | "bun"
+});
+```
+
+### Lockfile drift
+
+Aube reuses pnpm/npm/yarn/bun lockfile formats but its serialized output isn't byte-identical to the original tool's. The first install on a workspace whose lockfile was written by another PM produces a one-time churn diff; teams that mix tools on the same lockfile see ongoing drift. `vis install` warns when this is about to happen — pin `install.backend` to keep the team consistent.
+
+### Lifecycle scripts
+
+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.
+
 ## Commands
 
-| Command                 | Alias | Description                                           |
-| ----------------------- | ----- | ----------------------------------------------------- |
-| `vis run <target>`      |       | Run a target across workspace projects with caching   |
-| `vis affected <target>` |       | Run tasks only on projects affected by git changes    |
-| `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 hook <action>`     |       | Manage git hooks (install, uninstall, migrate)        |
+| 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 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 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.
+
+```sh
+vis secrets                         # scan the workspace (grouped, colourised output)
+vis secrets --staged                # pre-commit mode: scan staged files only
+vis secrets --since main            # scan files changed since the `main` branch
+vis secrets --affected              # scan only files affected by the current branch
+vis secrets --init                  # scaffold an initial .secrets-baseline.json
+vis secrets --list-rules            # print all bundled detection rules
+vis secrets --enable-rule tag:preset:weak-passwords  # enable an opt-in rule group additively
+vis secrets --exclude 'dist/**' --exclude-from .secretsignore    # extra walker exclusions
+vis secrets --include-rule stripe-access-token                   # check a single rule
+vis secrets --exclude-rule generic-api-key                       # drop a noisy rule
+vis secrets --baseline .secrets-baseline.json   # suppress triaged findings; print diff
+vis secrets --update-baseline       # merge current findings into the baseline
+vis secrets --format sarif > report.sarif       # SARIF for GitHub code-scanning
+```
+
+**Suppression** — inline (`// gitleaks:allow`), block (`gitleaks:allow-start` … `gitleaks:allow-end`), or a baseline JSON (sole fingerprint store). See the [secret-scanner README](../secret-scanner/README.md#suppression) for details.
+
+**CI example** (GitHub Actions, SARIF upload):
+
+```yaml
+name: Secrets
+on: [push, pull_request]
+jobs:
+    scan:
+        runs-on: ubuntu-latest
+        permissions: { security-events: write, contents: read }
+        steps:
+            - uses: actions/checkout@v4
+            - uses: pnpm/action-setup@v4
+            - run: pnpm install
+            - run: pnpm vis secrets --format sarif > report.sarif
+              continue-on-error: true
+            - uses: github/codeql-action/upload-sarif@v3
+              with: { sarif_file: report.sarif }
+```
+
+### Migrations
+
+`vis migrate` now speaks two security tools:
+
+```sh
+vis migrate gitleaks     # keeps gitleaks.toml, rewrites scripts/hooks to `vis secrets`
+vis migrate secretlint   # removes @secretlint/*, rewrites scripts/hooks, notes active rules
+```
+
+Every destructive step writes a `.bak` sidecar first and prompts for confirmation (skip with `-y`). Dry-run previews are available via `--dry-run`.
+
+### Running tasks on staged files
+
+`vis staged` is a built-in replacement for `lint-staged` — the same config shape, no peer dependency, and an integrated task renderer. Requires Git ≥ 2.32.
+
+Declare the patterns and tasks under `staged` in `vis.config.ts`:
+
+```ts
+// vis.config.ts
+import { defineConfig } from "@visulima/vis/config";
+
+export default defineConfig({
+    staged: {
+        "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
+        "*.md": "prettier --write",
+        "package.json": (files) => `sort-package-json ${files.join(" ")}`,
+    },
+});
+```
+
+Each key is a glob (basename or path-style — path-style matches resolve relative to `cwd`). Each value is one of:
+
+- a command string — split into argv, invoked with matched files appended;
+- a `string[]` array — commands run serially for that pattern;
+- a function `(files) => string | string[] | {title, task}` — generate dynamic commands or a custom task;
+- a `{ title, task }` object — runs `task(files)` with no argv construction, useful for in-process side effects.
+
+`vis.config.ts` is the single source of truth — no standalone `.lintstagedrc*` or `.vis-staged.*` files are read at runtime. Migrating from lint-staged or nano-staged? Run `vis migrate lint-staged` (or `vis migrate nano-staged`) to move the config in and remove the legacy files.
+
+#### Command-line flags
+
+```sh
+vis staged                          # run tasks on the current staged set
+vis staged --verbose                # show stdout/stderr on success as well as failure
+vis staged --no-stash               # skip the backup stash (faster, but no recovery on failure)
+vis staged --diff HEAD~1            # operate on a range instead of `--staged`
+vis staged --diff-filter=ACM        # override the default ACMR filter
+vis staged --concurrent 4           # cap parallel pattern execution
+vis staged --continue-on-error      # don't short-circuit on the first failure
+vis staged --fail-on-changes        # non-zero exit if tasks modified staged content
+vis staged --hide-unstaged          # hide all unstaged edits on tracked files
+vis staged --hide-all               # hide unstaged edits AND untracked files
+vis staged --relative               # pass paths relative to cwd to tasks
+vis staged --revert                 # restore pre-task state on failure
+vis staged --allow-empty            # allow a commit when tasks revert everything
+vis staged --auto-stage             # auto-stage new files tasks create (codegen, lockfile regen, …)
+vis staged --force-kill             # kill in-flight tasks with SIGKILL on fast-fail (default: SIGTERM)
+```
+
+#### Environment variables
+
+| Variable                | Description                                                                                                                                                                           |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `VIS_STAGED_CONCURRENT` | Concurrency fallback when `--concurrent` is not passed. Same value shape as the flag (`true`, `false`, or an integer). Useful in CI so you don't repeat the flag on every invocation. |
+
+#### How it behaves
+
+1. A hidden backup stash is created (via `git stash create` + `git stash store`, so the working tree is untouched).
+2. For partially-staged files, the unstaged delta is captured as a patch and the working tree is reset to the staged content. `--hide-all` extends this to every unstaged change _and_ untracked files via a single `git stash push --include-untracked`.
+3. Tasks run — patterns in parallel (capped at `os.availableParallelism()` by default), commands within a pattern serially.
+4. Task-driven edits are re-staged with `git update-index --again` (with a `git add -u` fallback for deletions), so commits made via pathspec (`git commit -m "…" .`) keep working.
+5. The unstaged patch — or the hide-all stash — is re-applied and the backup stash is dropped on success. On failure without `--revert`, the backup stash is preserved and the recovery sha is surfaced to the user. Ctrl+C aborts in-flight commands and still runs the restore path; a second Ctrl+C exits immediately.
+
+#### Migrating from lint-staged
+
+```sh
+vis migrate lint-staged    # moves the config into vis.config.ts and rewrites hooks
+```
+
+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.
 
 ## Documentation