@vistta/cli 1.1.0 → 1.2.1

package/README.md

@@ -27,25 +27,198 @@ npm install @vistta/cli
 - `vistta bundle <filename> [outdir]`  
   Bundle an entry file and its dependencies.
 
+- `vistta check [patterns] [--fix]`
+  Runs the enabled formatting, lint, and type checks. Read-only by default;
+  `--fix` applies formatting and lint fixes. Any failed stage, including lint
+  warnings, produces a nonzero exit status. Patterns limit formatting and lint;
+  type checking still covers the whole configured project.
+
+- `vistta lint [patterns] [--fix]`
+  Runs project-local ESLint against the configured files or supplied patterns.
+  `--fix` applies available fixes. Errors and warnings produce a nonzero exit
+  status.
+
+- `vistta fmt [patterns] [--check|--write]`
+  Checks formatting with project-local Prettier without changing files by
+  default. `--check` makes that mode explicit; `--write` formats files in place.
+  `--fix` is also accepted as a write alias. Check and write modes cannot be
+  combined.
+
+- `vistta types`
+  Checks the complete TypeScript or JavaScript project using its configuration.
+  Never emits files and does not accept file patterns.
+
+- `vistta config [--sources]`
+  Prints the merged project configuration, including built-in tool defaults.
+  `--sources` also shows the selected config file and the origin of each setting.
+
+- `vistta task <name> [-- args]`
+  Runs a configured task, package script, or registered command with its task
+  dependencies. Stops on the first failure and forwards arguments after `--`
+  only to the requested task's executable command or script.
+
+- `vistta run <name> [-- args]`
+  Alias for `vistta task` in the base CLI. Frameworks can override it:
+  `@vistta/js` uses `run` to launch applications, so use `vistta task` there.
+
 - `vistta project name`
   Outputs the current project name from `package.json`.
 
-- `vistta project version [major|minor|patch]`  
-  Outputs the current project version. If a level (`major`, `minor`, `patch`) is provided, it increments the version accordingly.
+- `vistta project version [increment|version] [prerelease-id]`
+  Prints the current project version, increments it (for example, `patch` or
+  `prerelease`), or sets an explicit version such as `1.2.3`.
+
+- `vistta project outdated [dependency]`
+  Shows installed (`Current`), range-compatible (`Wanted`), and `Latest`
+  versions, plus the owning manifest and dependency type, using `npm outdated`,
+  respecting npm registry settings and policies such as `min-release-age`.
+  Inside a workspace package, only that package's dependencies are checked;
+  running from the workspace root checks all workspace consumers.
+  Linked workspace packages are excluded. Available compatible updates cause a
+  nonzero exit status; newer versions outside the declared range are informational.
+
+- `vistta project update [dependency] [--compatible] [--dry-run]`
+  Updates declared dependency ranges to latest versions by default, which may
+  include major upgrades. `--compatible` selects npm's wanted version within
+  each dependency's existing range instead. `--dry-run` previews the exact
+  manifest changes without writing files.
+
+- `vistta project patch [dependency] [--dry-run]`
+  Backward-compatible alias for `project update --compatible`. Despite the
+  historical name, this can select a compatible minor update, not just patches.
+
+Dependency updates only edit `package.json` ranges; run `npm install` afterward
+to update installed versions and the lockfile. Workspace-root updates preserve
+each consumer's own target version. If no ranges need changing, the command
+says so explicitly. A dependency filter selects matching outdated entries; no
+match means no outdated entry was found, not that the dependency exists.
+
+```sh
+vistta project --help
+vistta project update --help
+vistta project outdated react
+vistta project update --compatible --dry-run
+vistta project update react --compatible
+vistta project update react --dry-run
+```
 
-- `vistta project outdated`  
-  Lists all outdated dependencies in the project.
+- `vistta test [...patterns] [--filter=pattern] [--only]`
+  Runs matching test files with the base CLI's Node runner. `--filter` selects
+  test names using a case-insensitive regular expression; `--only` selects tests
+  or suites marked as exclusive. Frameworks can provide a different test runner.
 
-- `vistta patch [module-name]` or `vistta project patch [module-name]`
-  Updates the version of a specific module (or all outdated modules if none is specified) to the latest patch version in `package.json`.
+For browser-based test harnesses, import `TestRunner` from `@vistta/cli/test-runner` to avoid bundling Node-only CLI modules.
 
-- `vistta update [module-name]` or `vistta project update [module-name]`
-  Updates the version of a specific module (or all outdated modules if none is specified) to its latest available version in `package.json`.
+### Unified Project Configuration
 
-- `vistta test [pattern]`  
-  Run tests matching the specified pattern.
+Keep VISTTA settings in the `cli` block of `tsconfig.json` or `jsconfig.json`.
+Comments and trailing commas are supported. If both files exist, `tsconfig.json`
+takes precedence. The existing `cliOptions` block remains supported; `cli` wins
+when both specify the same setting.
 
-For browser-based test harnesses, import `TestRunner` from `@vistta/cli/test-runner` to avoid bundling Node-only CLI modules.
+Install the tools you want to use locally:
+
+```sh
+npm install --save-dev eslint prettier typescript
+```
+
+```jsonc
+{
+  "$schema": "./node_modules/@vistta/cli/config.schema.json",
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": true,
+    "noEmit": true,
+  },
+  "include": ["src/**/*.js", "src/**/*.ts"],
+  "exclude": ["dist"],
+  "cli": {
+    "check": { "format": true, "lint": true, "types": true },
+    "format": {
+      "engine": "prettier",
+      "options": { "printWidth": 120, "semi": true },
+    },
+    "lint": {
+      "engine": "eslint",
+      "rules": { "no-unused-vars": "warn" },
+    },
+    "tasks": {
+      "validate": { "dependsOn": ["check", "test"] },
+      "release": { "dependsOn": ["validate"], "script": "publish:package" },
+    },
+  },
+}
+```
+
+The optional `$schema` enables completion and validation for VISTTA settings.
+The schema leaves other TypeScript and framework settings open; TypeScript
+validates compiler options during `vistta types` or `vistta check`.
+
+```sh
+vistta check
+vistta check --fix
+vistta lint "src/**/*.js" --fix
+vistta fmt --check
+vistta fmt --write
+vistta types
+vistta config
+vistta config --sources
+vistta task validate
+vistta run validate
+```
+
+- `check` runs formatting, linting, and type checking by default. Disable a stage
+  with `cli.check`. All enabled stages run, and any failure produces a nonzero
+  exit code. Lint warnings also fail the check.
+- Checks are read-only unless `--fix` or `fmt --write` is supplied. Fix mode
+  applies Prettier formatting and ESLint fixes; type checking never emits files.
+- Tools are resolved from the current project, not downloaded automatically.
+  Only enabled tools need to be installed. ESLint 9+ and Prettier 3 are supported.
+- `format.include` and `lint.include` override top-level `include`. Explicit
+  command-line patterns override both and are relative to the working directory.
+  The corresponding `exclude` settings, `compilerOptions.outDir`, dependencies,
+  and Git metadata are excluded. Inherited patterns are relative to their owning
+  configuration file. Type checking always covers the whole configured project.
+- Existing ESLint and Prettier configs are used when present. Inline settings
+  override them. Without an ESLint config, inline rules/options provide the flat
+  config. `lint.options` contains flat-config properties, not ESLint constructor
+  options. Without explicit includes, lint scans JS/TS and formatting scans files
+  supported by Prettier. An empty match set passes without changing files.
+- For plugins, parsers, or other executable settings, set `lint.config` or
+  `format.config` to a module path such as `"./tools/eslint.js"`. It must default
+  export the relevant tool configuration. Relative paths resolve from the owning
+  config file; package references resolve from that same directory. Referenced
+  lint configs replace ESLint config discovery; inline settings still win.
+
+### Presets And Tasks
+
+`extends` accepts a relative JSON/JSONC config, a package config export, or an
+array of either. Parents apply left to right, then local settings override them.
+Objects merge recursively; arrays and scalar values replace inherited values.
+Circular presets, malformed JSONC, and invalid VISTTA tool/task settings fail
+explicitly. `vistta config --sources` shows the merged configuration and the
+file responsible for each leaf setting, including built-in check defaults.
+
+Workspace packages can extend a shared root/preset config and override `cli`
+locally. Commands run in the current package directory; they do not automatically
+fan out across workspaces. Existing `compilerOptions`, `bundlerOptions`, and
+custom commands continue to work.
+
+Tasks run their `dependsOn` dependencies once, in order, before their optional
+package `script`. Dependencies can name other tasks, current-package scripts, or
+registered commands such as `check`, `lint`, `fmt`, `types`, `test`, and `bundle`
+(or `build` when provided by a framework).
+Missing tasks/scripts and dependency cycles fail before execution. The first
+failed command stops the plan and propagates its exit status. Arguments after
+`--` are forwarded only to the requested task's command or script:
+
+```sh
+vistta task release -- --dry-run
+```
+
+`vistta run` is a task alias in the base CLI. Framework command overrides are
+preserved: `@vistta/js` keeps its application-oriented `run`, so use `vistta task`
+there. Task caching and automatic cross-workspace scheduling are not implemented.
 
 ## Extending the CLI
 

package/bin.js

@@ -22,6 +22,10 @@ const argv = [];
 const execArgv = ["--import", pathToFileURL(fs.resolve(dirname, "register.js")), "--experimental-sqlite", "--title=VISTTA"];
 for (let i = 2, len = process.argv.length; i < len; i++) {
   const [arg, value] = process.argv[i].toLowerCase().split("=");
+  if (process.argv[i] === "--") {
+    argv.push(...process.argv.slice(i));
+    break;
+  }
   const nodeOption = ENABLED_NODE_OPTIONS[arg];
   if (nodeOption) {
     if (typeof nodeOption === "string") env[nodeOption] = value || true;

package/commands/project.js

@@ -1,97 +1,137 @@
-import { COLORS } from "@vistta/console";
 import fs from "@vistta/fs";
-import { capitalize } from "@vistta/utils";
+import { relative } from "node:path";
 import { Command } from "../classes/command.js";
-import { getOutdatedPackages, importJSON, incrementPackageVersion } from "../utils.js";
+import { getOutdatedPackages, importJSON, incrementPackageVersion, parseArgs } from "../utils.js";
 
 const HELP = {
-  name: "outputs current project name",
-  version: "outputs the project version",
-  "version [increment]": "updates the project version",
-  outdated: "lists all outdated modules in the project",
-  patch: "updates the version of outdated modules to the latest patch version in the project",
-  "patch [module]": "updates the version of outdated module to the latest patch version in the project",
-  update: "updates the version of outdated modules to the latest version in the project",
-  "update [module]": "updates the version of outdated module to the latest version in the project",
+  name: ["name", "Print the project name."],
+  version: [
+    "version [increment|version] [prerelease-id]",
+    "Print or change the project version. Increments: major, minor, patch, premajor, preminor, prepatch, prerelease.",
+  ],
+  outdated: [
+    "outdated [dependency]",
+    "Compare installed, wanted (within the declared range), and latest dependency versions.",
+  ],
+  update: [
+    "update [dependency] [--compatible] [--dry-run]",
+    "Update dependency ranges to latest; this may include major upgrades. --compatible selects wanted versions instead.",
+  ],
+  patch: ["patch [dependency] [--dry-run]", "Alias for update --compatible. This is range-compatible, not patch-only."],
 };
 
 export default class extends Command {
   async help(_, command) {
-    switch (command) {
-      case "name":
-        console.print(capitalize(HELP["name"]));
-        console.print("\nUsage:");
-        console.print("vistta project name");
-        break;
-      case "version":
-        console.print(capitalize(HELP["version"]) + " or " + HELP["version [increment]"]);
-        console.print("\nUsage:");
-        console.print("vistta project version");
-        console.print("vistta project version [increment]");
-        break;
-      case "outdated":
-        console.print(capitalize(HELP["outdated"]));
-        console.print("\nUsage:");
-        console.print("vistta project outdated");
-        break;
-      case "patch":
-        console.print(capitalize(HELP["patch"]) + " or " + HELP["patch [module]"]);
-        console.print("\nUsage:");
-        console.print("vistta project patch");
-        console.print("vistta project patch [module]");
-        break;
-      case "update":
-        console.print(capitalize(HELP["update"]) + " or " + HELP["update [module]"]);
-        console.print("\nUsage:");
-        console.print("vistta project update");
-        console.print("vistta project update [module]");
-        break;
-      default:
-        console.print("Outputs the current project name or version, or updates the version");
-        console.print("\nUsage:");
-        Object.keys(HELP).forEach((key) => console.print(`vistta project ${key}\t\t\t${HELP[key]}`));
-        break;
+    if (command && !Object.hasOwn(HELP, command))
+      throw new Error(`Unknown project command "${command}". Run vistta project --help.`);
+    console.print("Project metadata and dependency maintenance\n");
+    for (const [usage, description] of command ? [HELP[command]] : Object.values(HELP)) {
+      console.print(`  vistta project ${usage}\n    ${description}\n`);
     }
+    if (!command || ["outdated", "update", "patch"].includes(command))
+      console.print(
+        "Wanted respects npm policies and dependency ranges. Updates edit package.json only; run npm install afterward.",
+      );
   }
 
   async main(_, command, ...args) {
-    console.clear();
+    if (!command || command === "help") return this.help(_, args[0]);
+    if (!Object.hasOwn(HELP, command)) return this.help(_, command);
+    const [values, options] = parseArgs(args);
+    const allowed = command === "update" ? ["compatible", "dry-run"] : command === "patch" ? ["dry-run"] : [];
+    for (const [name, value] of Object.entries(options)) {
+      if (!allowed.includes(name)) throw new Error(`Unknown option --${name} for project ${command}`);
+      if (typeof value !== "boolean") throw new Error(`--${name} must be a boolean flag`);
+    }
+    const limit = command === "name" ? 0 : command === "version" ? 2 : 1;
+    if (values.length > limit) throw new Error(`Too many arguments. Run vistta project ${command} --help.`);
     switch (command) {
       case "name":
         return console.print(process.env.PROJECT_NAME);
       case "version":
-        if (!args[0]) return console.print(process.env.PROJECT_VERSION);
+        if (!values[0]) return console.print(process.env.PROJECT_VERSION);
         return console.print(
-          await incrementPackageVersion(fs.resolve(process.env.PROJECT_PATH, "package.json"), args[0], args[1]),
+          await incrementPackageVersion(fs.resolve(process.env.PROJECT_PATH, "package.json"), values[0], values[1]),
         );
       case "outdated":
       case "patch":
       case "update":
-        return modules(command, args[0]);
+        process.exit(await dependencies(command, values[0], options));
     }
-    return this.help(_, command);
   }
 }
 
-async function modules(command, arg1) {
+async function dependencies(command, dependency, options) {
   const modules = await getOutdatedPackages(process.cwd());
-  let valid = true;
-  let update = 0;
-  for (let i = 0, len = modules.length; i < len; i++) {
-    const { name, package: packagePath, current, wanted, latest, dev } = modules[i];
-    if (command === "patch" || command === "update") {
-      if (command === "patch" && current === wanted) continue;
-      if (arg1 && name !== arg1) continue;
-      const packageObj = await importJSON(packagePath);
-      packageObj[dev ? "devDependencies" : "dependencies"][name] = "^" + (command === "patch" ? wanted : latest);
-      await fs.writeFile(packagePath, JSON.stringify(packageObj, null, 2));
-      update++;
-    } else if (current === wanted)
-      console.print(`${COLORS.CYAN}Module "${name}" has a new version (${latest})${COLORS.RESET}`);
-    else (console.print(`${COLORS.YELLOW}Module "${name}" is outdated (${latest})${COLORS.RESET}`), (valid = false));
+  const selected = modules.filter((entry) => !dependency || entry.name === dependency);
+  if (!selected.length) {
+    console.print(
+      dependency
+        ? `No outdated dependency "${dependency}" found in this scope.`
+        : "All checked dependencies are up to date.",
+    );
+    return 0;
   }
-
-  if (modules.length == 0) console.print("Everything is up to date");
-  else if (update > 0) console.print(`Updated ${update} module${update > 1 ? "s" : ""} versions in project package.`);
-  process.exit(valid ? 0 : -1);
+  if (command === "outdated") {
+    const rows = [
+      ["Dependency", "Current", "Wanted", "Latest", "Manifest", "Type"],
+      ...selected.map((entry) => [
+        entry.name,
+        entry.current || "MISSING",
+        entry.wanted || "-",
+        entry.latest || "-",
+        relative(process.cwd(), entry.package) || "package.json",
+        entry.dev ? "dev" : "prod",
+      ]),
+    ];
+    const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
+    for (const row of rows)
+      console.print(
+        row
+          .map((value, column) => value.padEnd(widths[column]))
+          .join("  ")
+          .trimEnd(),
+      );
+    const compatible = selected.filter((entry) => !entry.current || entry.current !== entry.wanted).length;
+    console.print(
+      `\n${compatible} compatible update(s) or missing dependency(s); ${selected.length - compatible} latest-only update(s).`,
+    );
+    console.print("Compatible updates cause a nonzero exit status; latest-only updates are informational.");
+    return compatible ? 1 : 0;
+  }
+  const compatible = command === "patch" || options.compatible === true;
+  const changes = new Map();
+  let count = 0;
+  for (const entry of selected) {
+    const target = compatible ? entry.wanted : entry.latest;
+    if (!target || entry.current === target) continue;
+    const manifest = changes.get(entry.package) || (await importJSON(entry.package));
+    const section = entry.dev ? "devDependencies" : "dependencies";
+    const previous = manifest[section]?.[entry.name];
+    if (typeof previous !== "string") throw new Error(`Dependency "${entry.name}" is missing from ${entry.package}`);
+    const next = "^" + target;
+    if (previous === next) continue;
+    manifest[section][entry.name] = next;
+    changes.set(entry.package, manifest);
+    count++;
+    console.print(
+      `${options["dry-run"] ? "Would update" : "Update"}: ${entry.name} ${previous} -> ${next} (${relative(process.cwd(), entry.package)}, ${section})`,
+    );
+  }
+  if (!count) {
+    console.print(
+      `No ${compatible ? "compatible " : ""}dependency range changes needed. Run npm install if installed versions are behind.`,
+    );
+    return 0;
+  }
+  if (!options["dry-run"]) {
+    for (const [path, manifest] of changes) await fs.writeFile(path, JSON.stringify(manifest, null, 2) + "\n");
+  }
+  console.print(
+    `\n${options["dry-run"] ? "Would change" : "Changed"} ${count} dependency range(s) in ${changes.size} manifest(s).`,
+  );
+  console.print(
+    options["dry-run"] ? "Dry run: no files changed." : "Run npm install to update installed packages and the lockfile.",
+  );
+  return 0;
 }

package/commands/quality.js

@@ -0,0 +1,52 @@
+import { Command } from "../classes/command.js";
+import { loadProjectConfig, mergeConfig } from "../config.js";
+import { runChecks } from "../tools.js";
+import { parseArgs } from "../utils.js";
+
+export default class extends Command {
+  help() {
+    console.log(
+      "vistta check [patterns] [--fix]\nvistta lint [patterns] [--fix]\nvistta fmt [patterns] [--write]\nvistta types\nvistta config [--sources]",
+    );
+  }
+
+  async main(command, ...argv) {
+    const [patterns, options] = parseArgs(argv);
+    const allowed = command === "config" ? ["sources"] : command === "fmt" ? ["write", "check", "fix"] : ["fix"];
+    for (const [option, value] of Object.entries(options)) {
+      if (!allowed.includes(option)) throw new Error(`Unknown option --${option}`);
+      if (typeof value !== "boolean") throw new Error(`--${option} must be a boolean flag`);
+    }
+    if (["types", "config"].includes(command) && patterns.length)
+      throw new Error(`${command} does not accept file patterns`);
+    if (command === "fmt" && options.check && (options.write || options.fix))
+      throw new Error("Use either --check or --write, not both");
+    const project = loadProjectConfig();
+    if (command === "config") {
+      const defaults = {
+        cli: {
+          check: { format: true, lint: true, types: true },
+          lint: { engine: "eslint" },
+          format: { engine: "prettier" },
+        },
+      };
+      const config = mergeConfig(defaults, project.config);
+      const sources = {
+        "cli.check.format": "<default>",
+        "cli.check.lint": "<default>",
+        "cli.check.types": "<default>",
+        "cli.lint.engine": "<default>",
+        "cli.format.engine": "<default>",
+        ...project.sources,
+      };
+      console.print(JSON.stringify(options.sources ? { file: project.file, config, sources } : config, null, 2));
+      return;
+    }
+    const names =
+      command === "check"
+        ? ["format", "lint", "types"].filter((name) => project.config.cli?.check?.[name] !== false)
+        : [command === "fmt" ? "format" : command];
+    const code = await runChecks(names, project, { patterns, fix: options.fix === true || options.write === true });
+    process.exit(code);
+  }
+}

package/commands/task.js

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { Command } from "../classes/command.js";
+import { loadProjectConfig } from "../config.js";
+import { planTasks, runTasks } from "../tools.js";
+
+export default class extends Command {
+  help() {
+    console.log("vistta task <name> [-- args]\nvistta run <name> [-- args] (unless overridden by a framework)");
+  }
+
+  async main(_, name, ...args) {
+    if (!name) return this.help();
+    const cwd = process.cwd();
+    const { config } = loadProjectConfig(cwd);
+    const { scripts = {} } = JSON.parse(readFileSync(resolve(cwd, "package.json"), "utf8"));
+    const commands = Object.keys(process.vistta.options.cli.commands).filter(
+      (name) => !["default", "run", "task"].includes(name),
+    );
+    const plan = planTasks(name, config.cli?.tasks, scripts, commands);
+    process.exit(await runTasks(plan, cwd, args[0] === "--" ? args.slice(1) : args));
+  }
+}

package/commands/test.js

@@ -45,9 +45,9 @@ export default class extends DefaultCommand {
       }
       entry = (await entries.next())?.value;
     }
-    if (!process.env.NODE_DEBUG) console.enable();
     let output = "";
     const results = await this.#testRunner.run();
+    if (!process.env.NODE_DEBUG) console.enable();
     for (let i = 0, len = results.length; i < len; i++) {
       const { name, tests } = results[i];
       let passing = 0;

package/config.js

@@ -0,0 +1,128 @@
+import { parse, printParseErrorCode } from "jsonc-parser";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+export function mergeConfig(target, source) {
+  const result = { ...target };
+  for (const [key, value] of Object.entries(source)) {
+    if (["__proto__", "constructor", "prototype"].includes(key)) continue;
+    result[key] = value && typeof value === "object" && !Array.isArray(value) ? mergeConfig(result[key], value) : value;
+  }
+  return result;
+}
+
+export function loadProjectConfig(directory = process.cwd()) {
+  const file = ["tsconfig.json", "jsconfig.json"].map((name) => resolve(directory, name)).find(existsSync);
+  if (!file) return { file: undefined, config: {}, sources: {} };
+  const active = new Set();
+  const sources = {};
+  function load(filepath) {
+    if (active.has(filepath)) throw new Error(`Circular configuration inheritance: ${filepath}`);
+    active.add(filepath);
+    const errors = [];
+    const own = parse(readFileSync(filepath, "utf8"), errors, { allowTrailingComma: true });
+    if (errors.length) throw new Error(`Invalid configuration ${filepath}: ${printParseErrorCode(errors[0].error)}`);
+    if (!own || typeof own !== "object" || Array.isArray(own))
+      throw new Error(`Expected a configuration object in ${filepath}`);
+    for (const name of ["cli", "cliOptions"]) {
+      if (own[name] !== undefined && (!own[name] || typeof own[name] !== "object" || Array.isArray(own[name])))
+        throw new Error(`${name} must be an object in ${filepath}`);
+    }
+    let inherited = {};
+    for (const parent of own.extends ? (Array.isArray(own.extends) ? own.extends : [own.extends]) : []) {
+      if (typeof parent !== "string") throw new Error(`Expected a string in extends in ${filepath}`);
+      const base = dirname(filepath);
+      let parentFile;
+      if (parent.startsWith(".") || isAbsolute(parent)) {
+        parentFile = resolve(base, parent);
+        if (!existsSync(parentFile) && existsSync(parentFile + ".json")) parentFile += ".json";
+      } else parentFile = createRequire(filepath).resolve(parent);
+      inherited = mergeConfig(inherited, load(parentFile));
+    }
+    const cli = mergeConfig(own.cliOptions, own.cli || {});
+    if (cli.commands !== undefined && (!cli.commands || typeof cli.commands !== "object" || Array.isArray(cli.commands)))
+      throw new Error(`cli.commands must be an object in ${filepath}`);
+    for (const [name, value] of Object.entries(cli.commands || {})) {
+      if (typeof value !== "string") throw new Error(`Expected a module path for cli.commands.${name} in ${filepath}`);
+      cli.commands[name] =
+        value.startsWith(".") || isAbsolute(value)
+          ? pathToFileURL(resolve(dirname(filepath), value)).href
+          : pathToFileURL(createRequire(filepath).resolve(value)).href;
+    }
+    for (const section of ["lint", "format"]) {
+      if (cli[section]?.config !== undefined && typeof cli[section].config !== "string")
+        throw new Error(`cli.${section}.config must be a module path in ${filepath}`);
+      if (typeof cli[section]?.config === "string") {
+        const value = cli[section].config;
+        cli[section].config =
+          value.startsWith(".") || isAbsolute(value)
+            ? pathToFileURL(resolve(dirname(filepath), value)).href
+            : pathToFileURL(createRequire(filepath).resolve(value)).href;
+      }
+    }
+    const normalized = { ...own, cli };
+    delete normalized.extends;
+    delete normalized.cliOptions;
+    function record(value, prefix = "") {
+      for (const [key, entry] of Object.entries(value)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (entry && typeof entry === "object" && !Array.isArray(entry)) record(entry, path);
+        else sources[path] = filepath;
+      }
+    }
+    record(normalized);
+    active.delete(filepath);
+    return mergeConfig(inherited, normalized);
+  }
+  const config = load(file);
+  function stringList(value, path) {
+    if (value !== undefined && (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")))
+      throw new Error(`${path} must be an array of strings in ${file}`);
+  }
+  for (const name of ["include", "exclude", "files"]) stringList(config[name], name);
+  for (const section of ["check", "lint", "format", "tasks"]) {
+    const value = config.cli?.[section];
+    if (value !== undefined && (!value || typeof value !== "object" || Array.isArray(value)))
+      throw new Error(`cli.${section} must be an object in ${file}`);
+  }
+  for (const [name, value] of Object.entries(config.cli?.check || {})) {
+    if (!["format", "lint", "types"].includes(name) || typeof value !== "boolean")
+      throw new Error(`cli.check.${name} must be a boolean check named format, lint, or types`);
+  }
+  for (const section of ["lint", "format"]) {
+    const options = config.cli?.[section] || {};
+    const engine = options.engine;
+    const expected = section === "lint" ? "eslint" : "prettier";
+    if (engine !== undefined && engine !== expected) throw new Error(`cli.${section}.engine must be "${expected}"`);
+    for (const name of ["include", "exclude"]) stringList(options[name], `cli.${section}.${name}`);
+    for (const name of section === "lint" ? ["rules", "languageOptions", "options"] : ["options"]) {
+      const value = options[name];
+      if (value !== undefined && (!value || typeof value !== "object" || Array.isArray(value)))
+        throw new Error(`cli.${section}.${name} must be an object in ${file}`);
+    }
+    for (const name of Object.keys(options)) {
+      if (
+        ![
+          "engine",
+          "include",
+          "exclude",
+          "options",
+          "config",
+          ...(section === "lint" ? ["rules", "languageOptions"] : []),
+        ].includes(name)
+      )
+        throw new Error(`Unknown setting cli.${section}.${name} in ${file}`);
+    }
+  }
+  for (const [name, task] of Object.entries(config.cli?.tasks || {})) {
+    if (!task || typeof task !== "object" || Array.isArray(task)) throw new Error(`cli.tasks.${name} must be an object`);
+    stringList(task.dependsOn, `cli.tasks.${name}.dependsOn`);
+    if (task.script !== undefined && typeof task.script !== "string")
+      throw new Error(`cli.tasks.${name}.script must be a package script name`);
+    for (const key of Object.keys(task))
+      if (!["dependsOn", "script"].includes(key)) throw new Error(`Unknown setting cli.tasks.${name}.${key}`);
+  }
+  return { file, config, sources };
+}