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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visulima/vis",
-  "version": "1.0.0-alpha.25",
+  "version": "1.0.0-alpha.27",
   "description": "A monorepo dev toolkit — task runner, remote caching, security scanning, git hooks, and AI agent integrations — powered by @visulima/task-runner",
   "keywords": [
     "build",
@@ -80,8 +80,8 @@
   "dependencies": {
     "@visulima/secret-scanner": "1.0.0-alpha.4",
     "@visulima/tabular": "4.0.0-alpha.12",
-    "@visulima/task-runner": "1.0.0-alpha.16",
-    "@visulima/tui": "1.0.0-alpha.20",
+    "@visulima/task-runner": "1.0.0-alpha.18",
+    "@visulima/tui": "1.0.0-alpha.21",
     "jiti": "^2.7.0",
     "module-replacements": "^2.11.0",
     "module-replacements-codemods": "^1.2.1",
@@ -110,14 +110,14 @@
     }
   },
   "optionalDependencies": {
-    "@visulima/vis-binding-darwin-arm64": "1.0.0-alpha.25",
-    "@visulima/vis-binding-darwin-x64": "1.0.0-alpha.25",
-    "@visulima/vis-binding-linux-arm64-musl": "1.0.0-alpha.25",
-    "@visulima/vis-binding-linux-arm64-gnu": "1.0.0-alpha.25",
-    "@visulima/vis-binding-linux-x64-gnu": "1.0.0-alpha.25",
-    "@visulima/vis-binding-linux-x64-musl": "1.0.0-alpha.25",
-    "@visulima/vis-binding-win32-arm64-msvc": "1.0.0-alpha.25",
-    "@visulima/vis-binding-win32-x64-msvc": "1.0.0-alpha.25"
+    "@visulima/vis-binding-darwin-arm64": "1.0.0-alpha.27",
+    "@visulima/vis-binding-darwin-x64": "1.0.0-alpha.27",
+    "@visulima/vis-binding-linux-arm64-gnu": "1.0.0-alpha.27",
+    "@visulima/vis-binding-linux-arm64-musl": "1.0.0-alpha.27",
+    "@visulima/vis-binding-linux-x64-gnu": "1.0.0-alpha.27",
+    "@visulima/vis-binding-win32-arm64-msvc": "1.0.0-alpha.27",
+    "@visulima/vis-binding-linux-x64-musl": "1.0.0-alpha.27",
+    "@visulima/vis-binding-win32-x64-msvc": "1.0.0-alpha.27"
   },
   "engines": {
     "node": "^22.14.0 || >=24.10.0"

package/schemas/project.schema.json

@@ -178,6 +178,10 @@
                     "type": "string",
                     "description": "Workspace-level concurrency group this target opts into. The scheduler caps the *combined* in-flight count of every task whose target carries the same group name to the value declared in  {@link  TaskRunnerOptions.concurrencyGroups } . Use this when several targets share an external resource (a single Postgres, a developer's Docker daemon, an account-wide deploy lock) so the cap follows the resource, not any single target name.\n\nTargets that name a group not declared in `concurrencyGroups` run uncapped — a typo shouldn't deadlock the graph. Caps don't apply to tasks marked `always: true`; those run in a separate finalisation phase outside the scheduler."
                 },
+                "concurrencyWeight": {
+                    "type": "number",
+                    "description": "Per-task slot weight against the global `parallel` cap. Defaults to `1`. A task with `concurrencyWeight: 2` consumes two slots; with `parallel: 4` only two such tasks can run concurrently (or one weight-2 plus two weight-1). Use for CPU-pinning tasks — bundlers, `tsc`, native compiles — where the runner shouldn't keep over-subscribing the box just because slots are nominally free.\n\nThe scheduler always lets a single task run even if its weight exceeds the remaining budget; otherwise a heavy task on a `parallel: 1` pool would deadlock. Values `<= 0`, non-finite, or non-integer are ignored (treated as `1`)."
+                },
                 "configurations": {
                     "type": "object",
                     "additionalProperties": {
@@ -380,6 +384,10 @@
                     "type": "boolean",
                     "description": "Whether this target supports parallel execution"
                 },
+                "pty": {
+                    "type": "boolean",
+                    "description": "Per-target PTY override. When `true`, every task spawned from this target runs inside a pseudo-terminal (so `isatty()` returns true and the child preserves color / progress UI). When `false`, the workspace-level PTY toggle is suppressed for this target. Useful when most targets are happy with piped stdio but one tool (vitest, prettier, a colorising linter) needs a real TTY, or vice versa.\n\nAbsent means \"follow the workspace default\" — the executor decides based on its own toggles."
+                },
                 "warningPattern": {
                     "anyOf": [
                         {
@@ -651,9 +659,16 @@
                     },
                     "description": "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."
                 },
+                "arguments": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/TaskArgument"
+                    },
+                    "description": "Declarative argument schema for this target. Forwarded CLI args (`vis run <target> -- --flag value`) are validated against it, surfaced by per-task `--help`, and exposed to the command as `VIS_ARG_<NAME>` environment variables."
+                },
                 "description": {
                     "type": "string",
-                    "description": "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": "One-line description surfaced by `vis list` and per-task `--help`. Kept short — longer docs belong in project READMEs or vis.config.ts comments."
                 },
                 "inferred": {
                     "type": "boolean",
@@ -676,6 +691,69 @@
             "additionalProperties": false,
             "description": "An extended target configuration that adds the vis-specific options on top of task-runner's `TargetConfiguration`."
         },
+        "TaskArgument": {
+            "type": "object",
+            "properties": {
+                "alias": {
+                    "type": "string",
+                    "description": "Short single-character alias (e.g. `r` for `--reporter`, used as `-r`). Must be exactly one character — enforced at run time by  {@link  validateArgumentSchema } ."
+                },
+                "choices": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Allowed values when  {@link  TaskArgument.type }  is `\"enum\"`. Must be non-empty (and is required) for `enum` — enforced at run time by  {@link  validateArgumentSchema } ."
+                },
+                "default": {
+                    "$ref": "#/$defs/TaskArgumentValue",
+                    "description": "Value applied when the argument is omitted. Skips the required check."
+                },
+                "description": {
+                    "type": "string",
+                    "description": "One-line help text surfaced by per-task `--help`."
+                },
+                "name": {
+                    "type": "string",
+                    "description": "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 } ."
+                },
+                "positional": {
+                    "type": "boolean",
+                    "description": "Consume the value from the next free positional argument instead of a `--flag`. Positional args are filled in declaration order."
+                },
+                "required": {
+                    "type": "boolean",
+                    "description": "Fail the task when the argument is absent and has no `default`."
+                },
+                "type": {
+                    "$ref": "#/$defs/TaskArgumentType",
+                    "description": "Value type for coercion + validation. Defaults to `\"string\"`."
+                }
+            },
+            "required": [
+                "name"
+            ],
+            "additionalProperties": false,
+            "description": "A single declared argument for a task target."
+        },
+        "TaskArgumentValue": {
+            "type": [
+                "boolean",
+                "number",
+                "string"
+            ],
+            "description": "A coerced task-argument value."
+        },
+        "TaskArgumentType": {
+            "type": "string",
+            "enum": [
+                "boolean",
+                "enum",
+                "number",
+                "string"
+            ],
+            "description": "Value type a  {@link  TaskArgument }  coerces to and validates against."
+        },
         "VisTargetOptions": {
             "type": "object",
             "properties": {
@@ -785,6 +863,13 @@
                     "type": "string",
                     "description": "Per-target shell override. When set, the command runs through this shell instead of the platform default."
                 },
+                "shellArgs": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "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.\n\nMust be non-empty when set — an empty array would drop the interpreter flag entirely, so the runtime falls back to `-c` defensively."
+                },
                 "strictEnv": {
                     "type": "boolean",
                     "description": "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 `process.env`. When `false`, the target opts out of a workspace `strictEnv: true` (e.g. for a one-off command that legitimately tolerates an unset variable)."

package/schemas/vis-config.schema.json

@@ -36,11 +36,6 @@
             "$ref": "#/$defs/CodeownersConfig",
             "description": "Code ownership configuration. Controls how `vis sync codeowners` renders the generated CODEOWNERS file."
         },
-        "defaultBase": {
-            "type": "string",
-            "description": "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.\n\nResolved 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.\n\nMigrated automatically from `nx.json#affected.defaultBase` / `nx.json#defaultBase` by `vis migrate nx`.",
-            "default": "main"
-        },
         "constraints": {
             "type": "object",
             "properties": {
@@ -176,6 +171,11 @@
             "additionalProperties": false,
             "description": "Configuration for the `vis create` scaffolding command. Controls template downloads (via giget), default options, and post-creation behavior."
         },
+        "defaultBase": {
+            "type": "string",
+            "description": "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.\n\nResolved 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.\n\nMigrated automatically from `nx.json#affected.defaultBase` / `nx.json#defaultBase` by `vis migrate nx`.",
+            "default": "main"
+        },
         "editorconfig": {
             "type": "boolean",
             "description": "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.",
@@ -205,6 +205,52 @@
             },
             "description": "Named file-group patterns, reusable from target `inputs` via the `@filegroup:&lt;name>` token. File groups are resolved relative to each project root at discovery time."
         },
+        "fmt": {
+            "type": "object",
+            "properties": {
+                "adapters": {
+                    "type": "object",
+                    "properties": {
+                        "biome": {
+                            "$ref": "#/$defs/LintFmtAdapterOverride"
+                        },
+                        "deno-fmt": {
+                            "$ref": "#/$defs/LintFmtAdapterOverride"
+                        },
+                        "dprint": {
+                            "$ref": "#/$defs/LintFmtAdapterOverride"
+                        },
+                        "oxfmt": {
+                            "$ref": "#/$defs/LintFmtAdapterOverride"
+                        },
+                        "prettier": {
+                            "$ref": "#/$defs/LintFmtAdapterOverride"
+                        },
+                        "ruff-fmt": {
+                            "$ref": "#/$defs/LintFmtAdapterOverride"
+                        }
+                    },
+                    "additionalProperties": false,
+                    "description": "Per-adapter overrides. Keyed by `AdapterId`. Set `enabled: false` to skip an adapter even when detected, or `extraArgs` to append flags verbatim."
+                },
+                "extensionOverrides": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "$ref": "#/$defs/FmtAdapterId"
+                    },
+                    "description": "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."
+                },
+                "order": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/FmtAdapterId"
+                    },
+                    "description": "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."
+                }
+            },
+            "additionalProperties": false,
+            "description": "Configuration for `vis fmt` — the formatter orchestrator.\n\nTunes adapter detection precedence, per-extension routing, and per-adapter overrides. Flags on the CLI always win over config.\n\nThe 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."
+        },
         "generator": {
             "type": "object",
             "properties": {
@@ -276,6 +322,51 @@
             "additionalProperties": false,
             "description": "Installer backend selection for `vis install` / `vis add` / `vis remove` / `vis update` / `vis ci`.\n\nLets users opt into [aube](https://github.com/endevco/aube) — a Rust-native package manager that reads/writes pnpm/npm/yarn/bun lockfiles in place — as the default installer, while keeping a single switch to fall back to the conventional PM detected from the lockfile.\n\nResolution precedence (highest first): 1. CLI flag (`--installer &lt;name>` / `--no-aube`) 2. Env var `VIS_INSTALLER` 3. This config field 4. Auto-detect (the default)\n\nAube must be installed separately — `vis` does not bundle it. Install via npm (`@endevco/aube`), `mise use -g aube`, or `brew install endevco/tap/aube`."
         },
+        "lint": {
+            "type": "object",
+            "properties": {
+                "adapters": {
+                    "type": "object",
+                    "properties": {
+                        "biome": {
+                            "$ref": "#/$defs/LintFmtAdapterOverride"
+                        },
+                        "deno-lint": {
+                            "$ref": "#/$defs/LintFmtAdapterOverride"
+                        },
+                        "eslint": {
+                            "$ref": "#/$defs/LintFmtAdapterOverride"
+                        },
+                        "markdownlint": {
+                            "$ref": "#/$defs/LintFmtAdapterOverride"
+                        },
+                        "oxlint": {
+                            "$ref": "#/$defs/LintFmtAdapterOverride"
+                        },
+                        "ruff-check": {
+                            "$ref": "#/$defs/LintFmtAdapterOverride"
+                        },
+                        "shellcheck": {
+                            "$ref": "#/$defs/LintFmtAdapterOverride"
+                        },
+                        "stylelint": {
+                            "$ref": "#/$defs/LintFmtAdapterOverride"
+                        }
+                    },
+                    "additionalProperties": false,
+                    "description": "Per-adapter overrides. Keyed by `AdapterId`. Set `enabled: false` to skip an adapter even when detected, or `extraArgs` to append flags verbatim."
+                },
+                "order": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/LintAdapterId"
+                    },
+                    "description": "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`."
+                }
+            },
+            "additionalProperties": false,
+            "description": "Configuration for `vis lint` — the linter orchestrator.\n\nTunes adapter detection precedence and per-adapter overrides. Flags on the CLI always win over config.\n\nThe 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."
+        },
         "mcpPromote": {
             "type": "object",
             "properties": {
@@ -1823,6 +1914,11 @@
                     "description": "Enable auto-fingerprinting mode (Vite Task-style). When enabled, the task runner automatically tracks which files a task accesses during execution and uses that for cache invalidation instead of requiring manual input configuration.\n\nFalls back to explicit inputs (Nx-style) when file tracking is not supported on the current platform.\n\nThis is the workspace-wide switch. To opt a single target into traced hashing without flipping it for the whole graph, set  {@link  TargetConfiguration.hashMode }  to `\"trace\"` on that target instead.",
                     "default": false
                 },
+                "bail": {
+                    "type": "boolean",
+                    "description": "Failure-propagation policy.\n\n- `false` (default) — when a task fails, its transitive   dependents are marked `skipped`. Tasks not downstream of the   failure still run. Prevents cascade failures from running a   dependent on a missing `dist/` produced by the failed dep.\n- `true` — fail-fast. On the first failure every not-yet-started   task is marked `skipped`; in-flight tasks finish naturally.",
+                    "default": false
+                },
                 "cacheDiagnostics": {
                     "type": "boolean",
                     "description": "Whether to show cache miss diagnostics (why a cache miss occurred).",
@@ -2241,6 +2337,10 @@
                                 "type": "string",
                                 "description": "Workspace-level concurrency group this target opts into. The scheduler caps the *combined* in-flight count of every task whose target carries the same group name to the value declared in  {@link  TaskRunnerOptions.concurrencyGroups } . Use this when several targets share an external resource (a single Postgres, a developer's Docker daemon, an account-wide deploy lock) so the cap follows the resource, not any single target name.\n\nTargets that name a group not declared in `concurrencyGroups` run uncapped — a typo shouldn't deadlock the graph. Caps don't apply to tasks marked `always: true`; those run in a separate finalisation phase outside the scheduler."
                             },
+                            "concurrencyWeight": {
+                                "type": "number",
+                                "description": "Per-task slot weight against the global `parallel` cap. Defaults to `1`. A task with `concurrencyWeight: 2` consumes two slots; with `parallel: 4` only two such tasks can run concurrently (or one weight-2 plus two weight-1). Use for CPU-pinning tasks — bundlers, `tsc`, native compiles — where the runner shouldn't keep over-subscribing the box just because slots are nominally free.\n\nThe scheduler always lets a single task run even if its weight exceeds the remaining budget; otherwise a heavy task on a `parallel: 1` pool would deadlock. Values `&lt;= 0`, non-finite, or non-integer are ignored (treated as `1`)."
+                            },
                             "configurations": {
                                 "type": "object",
                                 "additionalProperties": {
@@ -2448,6 +2548,10 @@
                                 "type": "boolean",
                                 "description": "Whether this target supports parallel execution"
                             },
+                            "pty": {
+                                "type": "boolean",
+                                "description": "Per-target PTY override. When `true`, every task spawned from this target runs inside a pseudo-terminal (so `isatty()` returns true and the child preserves color / progress UI). When `false`, the workspace-level PTY toggle is suppressed for this target. Useful when most targets are happy with piped stdio but one tool (vitest, prettier, a colorising linter) needs a real TTY, or vice versa.\n\nAbsent means \"follow the workspace default\" — the executor decides based on its own toggles."
+                            },
                             "warningPattern": {
                                 "anyOf": [
                                     {
@@ -2740,9 +2844,16 @@
                         },
                         "description": "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."
                     },
+                    "arguments": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/$defs/TaskArgument"
+                        },
+                        "description": "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."
+                    },
                     "description": {
                         "type": "string",
-                        "description": "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": "One-line description surfaced by `vis list` and per-task `--help`. Kept short — longer docs belong in project READMEs or vis.config.ts comments."
                     },
                     "inferred": {
                         "type": "boolean",
@@ -2796,6 +2907,10 @@
                         "type": "string",
                         "description": "Workspace-level concurrency group this target opts into. The scheduler caps the *combined* in-flight count of every task whose target carries the same group name to the value declared in  {@link  TaskRunnerOptions.concurrencyGroups } . Use this when several targets share an external resource (a single Postgres, a developer's Docker daemon, an account-wide deploy lock) so the cap follows the resource, not any single target name.\n\nTargets that name a group not declared in `concurrencyGroups` run uncapped — a typo shouldn't deadlock the graph. Caps don't apply to tasks marked `always: true`; those run in a separate finalisation phase outside the scheduler."
                     },
+                    "concurrencyWeight": {
+                        "type": "number",
+                        "description": "Per-task slot weight against the global `parallel` cap. Defaults to `1`. A task with `concurrencyWeight: 2` consumes two slots; with `parallel: 4` only two such tasks can run concurrently (or one weight-2 plus two weight-1). Use for CPU-pinning tasks — bundlers, `tsc`, native compiles — where the runner shouldn't keep over-subscribing the box just because slots are nominally free.\n\nThe scheduler always lets a single task run even if its weight exceeds the remaining budget; otherwise a heavy task on a `parallel: 1` pool would deadlock. Values `&lt;= 0`, non-finite, or non-integer are ignored (treated as `1`)."
+                    },
                     "configurations": {
                         "type": "object",
                         "additionalProperties": {
@@ -2998,6 +3113,10 @@
                         "type": "boolean",
                         "description": "Whether this target supports parallel execution"
                     },
+                    "pty": {
+                        "type": "boolean",
+                        "description": "Per-target PTY override. When `true`, every task spawned from this target runs inside a pseudo-terminal (so `isatty()` returns true and the child preserves color / progress UI). When `false`, the workspace-level PTY toggle is suppressed for this target. Useful when most targets are happy with piped stdio but one tool (vitest, prettier, a colorising linter) needs a real TTY, or vice versa.\n\nAbsent means \"follow the workspace default\" — the executor decides based on its own toggles."
+                    },
                     "warningPattern": {
                         "anyOf": [
                             {
@@ -3565,6 +3684,50 @@
             ],
             "description": "Recognised input sources for the codeowners aggregator.\n\n- `project-json` — owners declared on each project's `project.json`.   Canonical source; takes precedence over the other two on path conflicts.\n- `nested-codeowners` — `CODEOWNERS` files placed at arbitrary depth   in the workspace tree (excluding the generated root file).\n- `package-json-maintainers` — fallback that reads each project's   `package.json#maintainers` and emits one entry per project root for   projects with no `project.json owners`. GitHub handles are extracted   from each maintainer's `url` (e.g. `https://github.com/&lt;handle&gt;`)."
         },
+        "LintFmtAdapterOverride": {
+            "type": "object",
+            "properties": {
+                "enabled": {
+                    "type": "boolean",
+                    "description": "Set to `false` to skip this adapter even when its config file or package.json entry is detected. Defaults to `true` (run when detected)."
+                },
+                "extraArgs": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Extra arguments appended verbatim to every invocation of this adapter. Useful for tool-specific flags vis doesn't expose directly (e.g. `eslint --rulesdir`)."
+                }
+            },
+            "additionalProperties": false,
+            "description": "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."
+        },
+        "FmtAdapterId": {
+            "type": "string",
+            "enum": [
+                "biome",
+                "deno-fmt",
+                "dprint",
+                "oxfmt",
+                "prettier",
+                "ruff-fmt"
+            ],
+            "description": "Adapter IDs that can format (adapter `kind` is `\"fmt\"` or `\"both\"`)."
+        },
+        "LintAdapterId": {
+            "type": "string",
+            "enum": [
+                "biome",
+                "deno-lint",
+                "eslint",
+                "markdownlint",
+                "oxlint",
+                "ruff-check",
+                "shellcheck",
+                "stylelint"
+            ],
+            "description": "Adapter IDs that can lint (adapter `kind` is `\"lint\"` or `\"both\"`)."
+        },
         "VisPlugin": {
             "type": "object",
             "properties": {
@@ -3769,9 +3932,16 @@
                                 },
                                 "description": "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."
                             },
+                            "arguments": {
+                                "type": "array",
+                                "items": {
+                                    "$ref": "#/$defs/TaskArgument"
+                                },
+                                "description": "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."
+                            },
                             "description": {
                                 "type": "string",
-                                "description": "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": "One-line description surfaced by `vis list` and per-task `--help`. Kept short — longer docs belong in project READMEs or vis.config.ts comments."
                             },
                             "inferred": {
                                 "type": "boolean",
@@ -3825,6 +3995,10 @@
                                 "type": "string",
                                 "description": "Workspace-level concurrency group this target opts into. The scheduler caps the *combined* in-flight count of every task whose target carries the same group name to the value declared in  {@link  TaskRunnerOptions.concurrencyGroups } . Use this when several targets share an external resource (a single Postgres, a developer's Docker daemon, an account-wide deploy lock) so the cap follows the resource, not any single target name.\n\nTargets that name a group not declared in `concurrencyGroups` run uncapped — a typo shouldn't deadlock the graph. Caps don't apply to tasks marked `always: true`; those run in a separate finalisation phase outside the scheduler."
                             },
+                            "concurrencyWeight": {
+                                "type": "number",
+                                "description": "Per-task slot weight against the global `parallel` cap. Defaults to `1`. A task with `concurrencyWeight: 2` consumes two slots; with `parallel: 4` only two such tasks can run concurrently (or one weight-2 plus two weight-1). Use for CPU-pinning tasks — bundlers, `tsc`, native compiles — where the runner shouldn't keep over-subscribing the box just because slots are nominally free.\n\nThe scheduler always lets a single task run even if its weight exceeds the remaining budget; otherwise a heavy task on a `parallel: 1` pool would deadlock. Values `&lt;= 0`, non-finite, or non-integer are ignored (treated as `1`)."
+                            },
                             "configurations": {
                                 "type": "object",
                                 "additionalProperties": {
@@ -4027,6 +4201,10 @@
                                 "type": "boolean",
                                 "description": "Whether this target supports parallel execution"
                             },
+                            "pty": {
+                                "type": "boolean",
+                                "description": "Per-target PTY override. When `true`, every task spawned from this target runs inside a pseudo-terminal (so `isatty()` returns true and the child preserves color / progress UI). When `false`, the workspace-level PTY toggle is suppressed for this target. Useful when most targets are happy with piped stdio but one tool (vitest, prettier, a colorising linter) needs a real TTY, or vice versa.\n\nAbsent means \"follow the workspace default\" — the executor decides based on its own toggles."
+                            },
                             "warningPattern": {
                                 "anyOf": [
                                     {
@@ -4440,6 +4618,69 @@
             "additionalProperties": false,
             "description": "A predicate used by  {@link  VisConfig.scopedTasks } . All listed constraints must match for the block to apply."
         },
+        "TaskArgument": {
+            "type": "object",
+            "properties": {
+                "alias": {
+                    "type": "string",
+                    "description": "Short single-character alias (e.g. `r` for `--reporter`, used as `-r`). Must be exactly one character — enforced at run time by  {@link  validateArgumentSchema } ."
+                },
+                "choices": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Allowed values when  {@link  TaskArgument.type }  is `\"enum\"`. Must be non-empty (and is required) for `enum` — enforced at run time by  {@link  validateArgumentSchema } ."
+                },
+                "default": {
+                    "$ref": "#/$defs/TaskArgumentValue",
+                    "description": "Value applied when the argument is omitted. Skips the required check."
+                },
+                "description": {
+                    "type": "string",
+                    "description": "One-line help text surfaced by per-task `--help`."
+                },
+                "name": {
+                    "type": "string",
+                    "description": "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 } ."
+                },
+                "positional": {
+                    "type": "boolean",
+                    "description": "Consume the value from the next free positional argument instead of a `--flag`. Positional args are filled in declaration order."
+                },
+                "required": {
+                    "type": "boolean",
+                    "description": "Fail the task when the argument is absent and has no `default`."
+                },
+                "type": {
+                    "$ref": "#/$defs/TaskArgumentType",
+                    "description": "Value type for coercion + validation. Defaults to `\"string\"`."
+                }
+            },
+            "required": [
+                "name"
+            ],
+            "additionalProperties": false,
+            "description": "A single declared argument for a task target."
+        },
+        "TaskArgumentValue": {
+            "type": [
+                "boolean",
+                "number",
+                "string"
+            ],
+            "description": "A coerced task-argument value."
+        },
+        "TaskArgumentType": {
+            "type": "string",
+            "enum": [
+                "boolean",
+                "enum",
+                "number",
+                "string"
+            ],
+            "description": "Value type a  {@link  TaskArgument }  coerces to and validates against."
+        },
         "VisTargetOptions": {
             "type": "object",
             "properties": {
@@ -4549,6 +4790,13 @@
                     "type": "string",
                     "description": "Per-target shell override. When set, the command runs through this shell instead of the platform default."
                 },
+                "shellArgs": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "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.\n\nMust be non-empty when set — an empty array would drop the interpreter flag entirely, so the runtime falls back to `-c` defensively."
+                },
                 "strictEnv": {
                     "type": "boolean",
                     "description": "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 `process.env`. When `false`, the target opts out of a workspace `strictEnv: true` (e.g. for a one-off command that legitimately tolerates an unset variable)."