@vsuite/config

The vsuite.json schema (zod), its JSON Schema export, and reading/writing the config file. Non-goals: prompting users (@krizic/vsuite), catalog contents (@vsuite/catalog), and generating artifacts (@vsuite/core).

This is a private, source-only workspace package (exports → ./src/index.ts). It is bundled into the @krizic/vsuite CLI and is not published to npm. Workspace consumers depend on it with "@vsuite/config": "workspace:*".

Public API

Export	Kind	Signature	Description
`configFilename`	const	`"vsuite.json"`	Config file name at the project root.
`readConfig`	function	`(root: string) => Promise<VsuiteConfig>`	Reads and parses `<root>/vsuite.json`; missing file error suggests `vsuite init`.
`writeJsonAtomically`	function	`(path: string, value: unknown) => Promise<void>`	Writes 2-space JSON to a temp file, then renames it into place.
`configSchema`	const	zod object schema	Strict schema with cross-field checks (duplicates, wiring, project skills directory, model profiles, preferences).
`skillNameSchema`	const	zod string schema	Lowercase kebab-case skill name.
`parseConfig`	function	`(input: unknown) => VsuiteConfig`	Validates input; throws `Invalid vsuite.json: <path>: <message>; ...`.
`modelSelectorSchema`	const	zod union schema	`model` value: non-empty string, or strict object with optional `default`, `opencode`, `claude-code`, `github-copilot` (at least one).
`ModelSelector`	type	`z.infer<typeof modelSelectorSchema>`	Parsed `model` value.
`resolveModel`	function	`(selector: ModelSelector, target: TargetId) => string \| undefined`	String applies to all targets; object resolves `selector[target] ?? selector.default`.
`modelIdIssue`	function	`(target: TargetId, model: string) => string \| undefined`	Returns the OpenCode `provider/model-id` error message for an invalid OpenCode value; `undefined` otherwise.
`VsuiteConfig`	type	`z.infer<typeof configSchema>`	Parsed config (defaults applied).
`vsuiteJsonSchema`	const	`VsuiteJsonSchema`	Draft 2020-12 JSON Schema derived from `configSchema`.
`VsuiteJsonSchema`	type	`interface { $schema; title; properties: { version: { const: number } } }`	Shape of the exported schema.
`schemaPackagePath`	const	`"schema/vsuite.schema.json"`	Location of the schema inside the published package.
`deriveGraph`, `coordinatorOf`, `calledBy`, `configuredAgents`, `effectiveSkills`, `graphWarnings`	functions		The agent graph derived from `agents` (callers, coordinator, effective skills, graph warnings).
`packNameSchema`, `packSourcePattern`, `entrySourceSchema`	consts		Pack names and `path:`/`npm:`/`git:` sources; `catalog` or `pack:<name>` entry sources.
`agentFeatures`, `enabledFeatures`, `stackIds`	functions		Capabilities and stack ids that a config enables.

Dependencies

Workspace: @vsuite/catalog.
Third-party: zod.
Used by: @vsuite/core, @vsuite/packs, @vsuite/workflows, @krizic/vsuite, and the UI main process.

Diagrams

flowchart LR
  F["vsuite.json"] --> R["readConfig(root)"]
  R --> P["JSON.parse"]
  P -- "ENOENT" --> E1["Error: run vsuite init"]
  P -- "read or parse error" --> E2["Error: Cannot read path"]
  P --> Z["parseConfig: configSchema.safeParse (zod)"]
  Z -- success --> C["VsuiteConfig"]
  Z -- failure --> E3["Error: Invalid vsuite.json"]

flowchart TD
  M["model for agent, selected target"] --> T{"string?"}
  T -- yes --> V["resolved value"]
  T -- no --> K{"target key set?"}
  K -- yes --> V
  K -- no --> D{"default set?"}
  D -- yes --> V
  D -- no --> E1["no model for target #quot;#lt;target#gt;#quot; (add #quot;#lt;target#gt;#quot; or #quot;default#quot;)"]
  V --> O{"target is opencode?"}
  O -- no --> OK["use value"]
  O -- yes --> S{"matches provider/model-id?"}
  S -- yes --> OK
  S -- no --> E2["must be #quot;provider/model-id#quot; for opencode (for example #quot;github-copilot/claude-opus-5.5#quot;)"]

Usage

import { parseConfig, readConfig } from "@vsuite/config";
 
const config = await readConfig(process.cwd());
const same = parseConfig(JSON.parse(text));

Testing

pnpm vitest run --project @vsuite/config