A task config has no place for settings another tool reads, so keeping them beside the task takes a patch to Vite+

The task schema is UserTaskConfig in crates/vt_graph/src/config/user.rs, where unknown fields are denied; the issue asks for one ignored metadata field there. The generated type is crates/vt_graph/run-config.ts, and the static run path is in packages/cli/binding/src/cli/handler.rs. Shipping this needs a maintainer decision on the design across two repositories first, so check with them before writing code.

Written by an AI agent (Claude) on behalf of @jasonkuhrt.

What happens

A task rejects keys that Vite Task doesn't know: UserTaskConfig denies unknown fields (crates/vt_graph/src/config/user.rs:317-320 at a3c087a7, the revision Vite+ 1.4.0 pins), and since #815 the error names the field. That catches typos, which is right. But it also leaves no room for a setting that another tool reads from the same task.

The types close the same door. Task is generated from Vite Task's types as a type alias (crates/vt_graph/run-config.ts), and Vite+ ships it as one, so a tool can't add to it with declaration merging, the way it can extend Vite's UserConfig interface.

Stripping the keys before Vite Task decodes the config doesn't work for every config either. Vite+ first tries to extract run statically and decodes it in Rust (packages/cli/binding/src/cli/handler.rs:167-176 in Vite+ 1.4.0). Only a config it can't read statically reaches the JavaScript callback, which is decoded by the same Rust type. So a literal task that carries another tool's setting fails to load:

export default defineConfig({
  run: { tasks: { check: { command: 'true', ci: { job: true } } } },
});
// vp run → unknown field `ci`

The case that motivates it

We generate our CI workflows from the task graph. Whether a task gets a CI job, and its schedule, are per-task settings that belong beside the task. Today a patch to Vite+ adds them to Task's type and strips them in resolveUniversalViteConfig. That works only for configs built through helpers, which skip the static path. The patch has to be reapplied on every Vite+ release, and any edit to it changes the lockfile's patch hash, so every task that fingerprints its dependencies misses once.

The ask

A metadata key on a task that Vite Task accepts and never reads. Cargo does this with package.metadata, for the same reason #815 names unknown fields: "Cargo by default will warn about unused keys in Cargo.toml to assist in detecting typos and such. The package.metadata table, however, is completely ignored by Cargo and will not be warned about." (Cargo: the metadata table)

// in a tool's types
declare module 'vite-plus' {
  interface TaskMetadata {
    ci?: { job?: boolean };
  }
}

// in a config
tasks: {
  'test:e2e': {
    command: 'playwright test',
    metadata: { ci: { job: true } },
  },
}

What it means in each case:

• Its value must be a JSON object. Anything else (a number, an array, null) is a config error, like any other mistyped field.
• Inside it, Vite Task decodes nothing, validates nothing and outputs nothing, in any listing or in --json output either. Tools read it from the config. Only JSON reaches Vite Task, as for every field: the JavaScript path serializes run to JSON before Rust decodes it.
• It isn't in any cache key. Editing it re-keys nothing.
• Outside metadata, checking stays as strict as today, so #815's errors stay.
• The static path reads it like any other field and ignores it, the same as the JavaScript path.
• Types: metadata?: TaskMetadata, where TaskMetadata is an empty interface that tools extend. By convention each tool takes one top-level key.

Where it goes, in two repositories:

• Vite Task: an ignored metadata field on UserTaskConfig, with a ts-rs type override so that the generated run-config.ts refers to TaskMetadata by name.
• Vite+: export interface TaskMetadata {}, declared and exported from its entry (packages/cli/src/index.ts). Today that entry exports no run-config type.

This keeps the task schema lean. Vite Task gains one field it never interprets, instead of fields shaped by each tool. #277 asks for description, a key Vite Task would own and display; this is the opposite, a place for keys it never reads.

Alternatives considered

• Allow unknown keys. That loses #815's errors.
• A top-level key of the tool's own, keyed by task name. This works today: Vite's UserConfig can be extended, and the static path reads only run. But each task's settings then sit in a second map in the same file, every tool repeats that map, and renaming a task leaves its settings behind under the old name.
• A helper in each config that strips the tool's keys. Every package's config has to call it, and the tool can't then read what the helper stripped from the config Vite Task got.