@visulima/vis 1.0.0-alpha.26 → 1.0.0-alpha.27

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+## @visulima/vis [1.0.0-alpha.27](https://github.com/visulima/visulima/compare/@visulima/vis@1.0.0-alpha.26...@visulima/vis@1.0.0-alpha.27) (2026-06-02)
+
+### Features
+
+* **task-runner,vis:** per-task pty + concurrency weight, abort cache gate, fspy scaffolds ([#656](https://github.com/visulima/visulima/issues/656)) ([ca64010](https://github.com/visulima/visulima/commit/ca64010b236903e08273680ea65dec7046fcd18b))
+* **vis:** declarative task arguments + per-target script mode ([#662](https://github.com/visulima/visulima/issues/662)) ([417ca53](https://github.com/visulima/visulima/commit/417ca5395728a0776cbfcd0122ae21e3159a4c48))
+* **vis:** lint + fmt orchestrator ([3a78ed7](https://github.com/visulima/visulima/commit/3a78ed709922e6a35648e0d0eb3f41cc49f89b7a))
+
+### Bug Fixes
+
+* **task-runner:** tolerate dev-only dependency cycles ([#664](https://github.com/visulima/visulima/issues/664)) ([9ad384e](https://github.com/visulima/visulima/commit/9ad384e34927b40823ae104d6b05a581dcd05705)), closes [#411](https://github.com/visulima/visulima/issues/411)
+* **vis:** correct flag name in conflicting-schema error (--projects) ([#667](https://github.com/visulima/visulima/issues/667)) ([c56122b](https://github.com/visulima/visulima/commit/c56122bc6bc654e4a9e118e96b9ba852bc9b784f))
+* **vis:** require explicit opt-in to apply ecosystem updates ([#663](https://github.com/visulima/visulima/issues/663)) ([90cf12d](https://github.com/visulima/visulima/commit/90cf12dffa9dd53cc21849e9a41488dfbe2c8221))
+
+
+### Dependencies
+
+* **@visulima/task-runner:** upgraded to 1.0.0-alpha.18
+* **@visulima/tui:** upgraded to 1.0.0-alpha.21
+* **@visulima/error:** upgraded to 6.0.0-alpha.31
+* **@visulima/fs:** upgraded to 5.0.0-alpha.29
+* **@visulima/package:** upgraded to 5.0.0-alpha.28
+
 ## @visulima/vis [1.0.0-alpha.26](https://github.com/visulima/visulima/compare/@visulima/vis@1.0.0-alpha.25...@visulima/vis@1.0.0-alpha.26) (2026-05-29)
 
 ### Bug Fixes

package/LICENSE.md

@@ -1751,6 +1751,23 @@ Repository: git+https://github.com/visulima/visulima.git
 > > OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 > > SOFTWARE.
 >
+> ---------------------------------------
+>
+> ## terminal-size
+> License: MIT
+> By: Sindre Sorhus
+> Repository: sindresorhus/terminal-size
+>
+> > MIT License
+> >
+> > Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+> >
+> > Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+> >
+> > The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+> >
+> > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+>
 >
 >
 >
@@ -8355,23 +8372,6 @@ Repository: git://github.com/spencermountain/suffix-thumb.git
 
 ---------------------------------------
 
-## terminal-size
-License: MIT
-By: Sindre Sorhus
-Repository: sindresorhus/terminal-size
-
-> MIT License
->
-> Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
->
-> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
->
-> The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
->
-> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
----------------------------------------
-
 ## validate-npm-package-license
 License: Apache-2.0
 By: Kyle E. Mitchell, Mark Stacey

package/README.md

@@ -204,28 +204,30 @@ When aube is the installer, `vis doctor` surfaces aube's effective hardening pos
 
 ## 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, 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 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.
 

package/dist/bin.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import"./packem_shared/index-CS6a2wFB.js";import"./packem_chunks/bin.js";import"./packem_chunks/config.js";import"./packem_shared/readFileSync-CGmzMUF2-D6rUjGDn.js";
+import"./packem_shared/index-efSniSRN.js";import"./packem_chunks/bin.js";import"./packem_chunks/config.js";import"./packem_shared/readFileSync-CGmzMUF2-D6rUjGDn.js";

package/dist/binx.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import{N as r,m as o,i as c,T as i,w as a,a as n}from"./packem_shared/index-CS6a2wFB.js";r();process.argv.includes("--no-color")&&(process.env.NO_COLOR="1",process.env.FORCE_COLOR="0");process.argv.slice(2).some(s=>s==="--version"||s==="-v"||s==="-V")&&(process.stdout.write(`${o.version}
+import{N as r,m as o,i as c,T as i,w as a,a as n}from"./packem_shared/index-efSniSRN.js";r();process.argv.includes("--no-color")&&(process.env.NO_COLOR="1",process.env.FORCE_COLOR="0");process.argv.slice(2).some(s=>s==="--version"||s==="-v"||s==="-V")&&(process.stdout.write(`${o.version}
 `),process.exit(0));process.argv.splice(2,0,"dlx");c();const e=i("visx",{packageName:"visx",packageVersion:o.version}),p=process.argv.includes("--debug")||!!process.env.DEBUG;e.addPlugin(a({detailed:p,exitOnError:!1}));e.addCommand(n);(async()=>{try{await e.run({shouldExitProcess:!1})}catch{process.exitCode=process.exitCode||1}finally{process.exit(process.exitCode??0)}})();

package/dist/config/index.d.ts

@@ -20,6 +20,10 @@ interface SimilarDepFamily {
   /** Dep-name prefixes (literal, no glob). Match if `depName.startsWith(prefix)`. */
   prefixes?: string[];
 }
+/** Adapter IDs that can format (adapter `kind` is `"fmt"` or `"both"`). */
+type FmtAdapterId = "biome" | "deno-fmt" | "dprint" | "oxfmt" | "prettier" | "ruff-fmt";
+/** Adapter IDs that can lint (adapter `kind` is `"lint"` or `"both"`). */
+type LintAdapterId = "biome" | "deno-lint" | "eslint" | "markdownlint" | "oxlint" | "ruff-check" | "shellcheck" | "stylelint";
 type VersionManagerName = "asdf" | "corepack" | "fnm" | "mise" | "none" | "nvm" | "proto" | "self-activate" | "volta";
 type RuntimeTool = "aube" | "bun" | "deno" | "go" | "node" | "npm" | "pnpm" | "python" | "ruby" | "rust" | "yarn";
 interface ToolchainConfig {
@@ -144,6 +148,54 @@ interface ServiceEntry {
   visVersion: string;
 }
 /**
+* First-class task arguments: a declarative schema per target that lets a
+* task define its named/positional arguments, validate what the user passes
+* on the CLI, and render a per-task `--help`. The validated values are also
+* exposed to the command as `VIS_ARG_<NAME>` environment variables so the
+* underlying script can read them without re-parsing argv.
+*
+* This module is intentionally pure (no IO) so it is trivially unit-testable;
+* the run handler wires it to the forwarded-args vector and the task env.
+*/
+/** Value type a {@link TaskArgument} coerces to and validates against. */
+type TaskArgumentType = "boolean" | "enum" | "number" | "string";
+/** A coerced task-argument value. */
+type TaskArgumentValue = boolean | number | string;
+/** A single declared argument for a task target. */
+interface TaskArgument {
+  /**
+  * Short single-character alias (e.g. `r` for `--reporter`, used as `-r`).
+  * Must be exactly one character — enforced at run time by
+  * {@link validateArgumentSchema}.
+  */
+  alias?: string;
+  /**
+  * Allowed values when {@link TaskArgument.type} is `"enum"`. Must be
+  * non-empty (and is required) for `enum` — enforced at run time by
+  * {@link validateArgumentSchema}.
+  */
+  choices?: string[];
+  /** Value applied when the argument is omitted. Skips the required check. */
+  default?: TaskArgumentValue;
+  /** One-line help text surfaced by per-task `--help`. */
+  description?: string;
+  /**
+  * Canonical name, without the leading `--` (kebab-case by convention).
+  * Must start with a letter and contain only letters, digits, `-`, `_` —
+  * enforced at run time by {@link validateArgumentSchema}.
+  */
+  name: string;
+  /**
+  * Consume the value from the next free positional argument instead of a
+  * `--flag`. Positional args are filled in declaration order.
+  */
+  positional?: boolean;
+  /** Fail the task when the argument is absent and has no `default`. */
+  required?: boolean;
+  /** Value type for coercion + validation. Defaults to `"string"`. */
+  type?: TaskArgumentType;
+}
+/**
 * Semantic classification for a target.
 * - `build`: Generates one or more artifacts; cached by default.
 * - `test`: Validation task (lint, typecheck, unit test). Default type.
@@ -321,6 +373,18 @@ interface VisTargetOptions {
   */
   shell?: string;
   /**
+  * Arguments passed to the per-target shell/interpreter before the command
+  * string. Defaults to `["-c"]` (POSIX shells, pwsh). Set this to run the
+  * command under an interpreter that uses a different flag — e.g.
+  * `shell: "node", shellArgs: ["-e"]` runs the command as inline JS
+  * ("script mode"), or `shellArgs: ["-lc"]` for a login shell. Only applies
+  * when `shell`/`unixShell`/`windowsShell` resolves to a custom shell.
+  *
+  * Must be non-empty when set — an empty array would drop the interpreter
+  * flag entirely, so the runtime falls back to `-c` defensively.
+  */
+  shellArgs?: string[];
+  /**
   * Override the workspace `strictEnv` setting for this target. When
   * truthy, the target fails if its command references an env var
   * that resolves to neither the task's effective env nor
@@ -367,9 +431,16 @@ interface VisTargetConfiguration extends Omit<TargetConfiguration, "options"> {
   */
   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.
+  * Declarative argument schema for this target. Forwarded CLI args
+  * (`vis run &lt;target> -- --flag value`) are validated against it, surfaced
+  * by per-task `--help`, and exposed to the command as `VIS_ARG_&lt;NAME>`
+  * environment variables.
+  */
+  arguments?: TaskArgument[];
+  /**
+  * One-line description surfaced by `vis list` and per-task `--help`.
+  * Kept short — longer docs belong in project READMEs or
+  * vis.config.ts comments.
   */
   description?: string;
   /**
@@ -517,6 +588,25 @@ interface VisPlugin {
   setup?: (hooks: Hookable<VisHooks>) => Promise<void> | void;
 }
 /**
+* Per-adapter override applied by `vis lint` / `vis fmt`. Keyed by
+* adapter id under `lint.adapters` / `fmt.adapters`. Every field is
+* optional — set only what you need to change.
+*/
+interface LintFmtAdapterOverride {
+  /**
+  * Set to `false` to skip this adapter even when its config file or
+  * package.json entry is detected. Defaults to `true` (run when
+  * detected).
+  */
+  enabled?: boolean;
+  /**
+  * Extra arguments appended verbatim to every invocation of this
+  * adapter. Useful for tool-specific flags vis doesn't expose
+  * directly (e.g. `eslint --rulesdir`).
+  */
+  extraArgs?: string[];
+}
+/**
 * The 8 Socket.dev-style supply-chain policies. Used in `security.policies`
 * and `security.acceptedRisks[*].policies`. Kept as a const tuple so callers
 * can import the runtime array (`POLICY_NAMES`) for iteration without
@@ -726,19 +816,6 @@ interface VisConfig {
   */
   codeowners?: CodeownersConfig;
   /**
-  * Default base branch used by `vis affected`, `vis ci`, and `vis run --affected`
-  * when no explicit `--base` is passed and no CI smart-resolver fires.
-  *
-  * Resolved as `origin/<defaultBase>` against the local clone; should be a
-  * branch name (not a fully-qualified ref) such as `main`, `master`, or `trunk`.
-  * Falls back to `main` when omitted.
-  *
-  * Migrated automatically from `nx.json#affected.defaultBase` /
-  * `nx.json#defaultBase` by `vis migrate nx`.
-  * @default "main"
-  */
-  defaultBase?: string;
-  /**
   * Project dependency constraints.
   * Enforced after building the project graph, before running tasks.
   */
@@ -810,6 +887,19 @@ interface VisConfig {
     templates?: Record<string, string>;
   };
   /**
+  * Default base branch used by `vis affected`, `vis ci`, and `vis run --affected`
+  * when no explicit `--base` is passed and no CI smart-resolver fires.
+  *
+  * Resolved as `origin/&lt;defaultBase>` against the local clone; should be a
+  * branch name (not a fully-qualified ref) such as `main`, `master`, or `trunk`.
+  * Falls back to `main` when omitted.
+  *
+  * Migrated automatically from `nx.json#affected.defaultBase` /
+  * `nx.json#defaultBase` by `vis migrate nx`.
+  * @default "main"
+  */
+  defaultBase?: string;
+  /**
   * Discover `.editorconfig` for indent / line-ending defaults during
   * file transformations (sort-package-json, migrate, hook, pm overrides,
   * workspace catalog rewrites). Per-command flags can still override.
@@ -849,6 +939,45 @@ interface VisConfig {
   */
   fileGroups?: Record<string, string[]>;
   /**
+  * Configuration for `vis fmt` — the formatter orchestrator.
+  *
+  * Tunes adapter detection precedence, per-extension routing, and
+  * per-adapter overrides. Flags on the CLI always win over config.
+  *
+  * The default fmt precedence is `oxfmt → biome → dprint → prettier
+  * → deno-fmt`. When multiple adapters claim the same extension,
+  * the first in this order owns it unless overridden here.
+  * @example
+  * ```
+  * fmt: {
+  *   order: ["biome", "prettier"],
+  *   extensionOverrides: { md: "dprint" },
+  *   adapters: { "deno-fmt": { enabled: false } },
+  * }
+  * ```
+  */
+  fmt?: {
+    /**
+    * Per-adapter overrides. Keyed by `AdapterId`. Set
+    * `enabled: false` to skip an adapter even when detected, or
+    * `extraArgs` to append flags verbatim.
+    */
+    adapters?: Partial<Record<FmtAdapterId, LintFmtAdapterOverride>>;
+    /**
+    * Pin a file extension (without the leading dot) to a specific
+    * adapter, overriding the registry's "first detected adapter
+    * wins" routing. Use to e.g. send `.md` to `dprint` even when
+    * both prettier and dprint are present.
+    */
+    extensionOverrides?: Record<string, FmtAdapterId>;
+    /**
+    * Override the adapter precedence order. Adapters omitted from
+    * this list still run (appended at the end in registry order),
+    * but those listed earlier get priority for extension routing.
+    */
+    order?: FmtAdapterId[];
+  };
+  /**
   * Configuration for the `vis generate` in-repo scaffolding command.
   * Points at additional template directories beyond the defaults
   * (`.vis/templates/` and `.moon/templates/`).
@@ -995,6 +1124,37 @@ interface VisConfig {
     corepack?: "auto" | boolean;
   };
   /**
+  * Configuration for `vis lint` — the linter orchestrator.
+  *
+  * Tunes adapter detection precedence and per-adapter overrides.
+  * Flags on the CLI always win over config.
+  *
+  * The default lint precedence is `oxlint → biome → eslint →
+  * stylelint → deno-lint`. Override with `order` to e.g. let biome
+  * fire before oxlint when the workspace standardises on biome.
+  * @example
+  * ```
+  * lint: {
+  *   order: ["biome", "eslint"],
+  *   adapters: { "deno-lint": { enabled: false } },
+  * }
+  * ```
+  */
+  lint?: {
+    /**
+    * Per-adapter overrides. Keyed by `AdapterId`. Set
+    * `enabled: false` to skip an adapter even when detected, or
+    * `extraArgs` to append flags verbatim.
+    */
+    adapters?: Partial<Record<LintAdapterId, LintFmtAdapterOverride>>;
+    /**
+    * Override the adapter precedence order. Adapters omitted from
+    * this list still run (appended at the end in registry order)
+    * unless explicitly disabled under `adapters[id].enabled`.
+    */
+    order?: LintAdapterId[];
+  };
+  /**
   * `vis-mcp` promotion notice shown after successful commands when an
   * AI CLI (Claude Code, Cursor, Windsurf, Continue, Zed, Cline) is
   * installed but `@visulima/vis-mcp` is not wired into its config.