@buddy-works/docs-schema

Fetches Buddy's YAML and REST API schemas and resolves them into shapes you can render or search. It follows $ref pointers, flattens allOf, and keeps enums, constraints and examples.

Installation

npm install @buddy-works/docs-schema

Usage

import { BuddySchema } from "@buddy-works/docs-schema";

const parser = await BuddySchema.load();

await parser.actions.list();                  // every action a pipeline can run
await parser.actions.get("AMAZON_S3");        // one action, in full
await parser.actions.search("notify");        // the ones that send notifications
await parser.search("deploy to s3");          // across YAML and the REST API
await parser.api.endpoint("GET", "/workspaces/{workspace_domain}/projects");

How it gets the schemas

BuddySchema.load() reads from a local cache and revalidates over HTTP with an ETag once the cache is 3 hours old. A 304 keeps the cached copy and starts the window again. A 200 replaces the document. Nothing is fetched until a call needs it, so a process that only asks about actions never downloads the OpenAPI document.

In a long-running process such as an MCP server, the check runs in the background and the call answers from memory. A query never waits on the network. When a 200 lands, the new document takes over and the shaped results derived from the old one are dropped. A query already in flight finishes against the graph it started with.

A response that does not parse, or that lacks the key its scope depends on, is refused. The previous good copy stays in place rather than being overwritten by an error page. If the server cannot be reached at all, the cached copy keeps being served and stats() reports staleSince for that document.

It reads production unless environment says otherwise. The other names are "stage", "master" and "dev". Each one caches separately, so a process can hold two at once:

const live = await BuddySchema.load();
const stage = await BuddySchema.load({ environment: "stage" });

Supplying the documents yourself

If you already have the schemas, hand them over instead of letting the package fetch. This covers a pinned version, a file on disk, or a schema that is not published. Nothing is fetched and nothing is cached:

import { readFileSync } from "node:fs";

const parser = BuddySchema.from({
  pipelines: JSON.parse(readFileSync("yaml-schema.json", "utf8")),
});

The keys are documents, not scopes, and pipelines backs two of them:

Reaching a scope whose document you did not supply throws and names what was given.

Methods

Ten scopes over those nine documents. What a scope offers depends on what its schema declares, and the types enforce it. parser.agents.list() does not compile, because the agents schema has no union.

Every YAML scope

Scopes with a root

pipelines, targets, environments, sandboxes, agents, domains, customActions, distributions

root() gives the document's entry type: what a YAML file at that path may contain. await parser.pipelines.root() returns the PipelineYaml document.

Scopes with a union

actions, targets, environments

pipelines

api

On the client

Options

await BuddySchema.load({ environment, cacheDir, ttlMs, results });
BuddySchema.from(documents, { results });

environment is one of the names above. cacheDir and ttlMs fall back to the variables below. results bounds how many shaped documents are held. Pass false to shape every call afresh.

Errors

• DocumentUnavailableError: nothing fetched and no cached copy. Names the URL and points at BuddySchema.from().
• MissingDocumentError: a scope was reached whose document from() was not given. Lists what was.
• ScopeUnsupportedError: a supplied document is not the schema that scope needs. Says what was expected, what was found, and the nearest existing name.

Validating a YAML file

@buddy-works/docs-schema/validate checks a YAML file against the schema of a scope with a root, the same schema the methods above read. Any other scope throws.

import { validateYaml } from "@buddy-works/docs-schema/validate";

const report = await validateYaml(parser, "pipelines", yaml);

The report holds findings, checked and blocked. blocked is true only when the file cannot be read as that scope's document at all. Every other finding is advice, and what to refuse on is the caller's call.

Each finding has a severity, a message and a path such as pipelines[0].actions[1].type, which together read as one line. For anything else, use the rest:

• at: the same location as segments, [0, "actions", 1, "type"]. A finding about a key points at the key.

• code: what went wrong, with the details beside it:

  code	Details	Meaning
  syntax	line?, column?	The YAML does not parse, or an alias in it has no anchor or expands without end. Blocks. Aliases carry no position.
  document	expected, got	Not the kind of file the scope takes, a list of entries or one entry. An empty file is neither. Blocks.
  empty		A list with no entries.
  shape	expected, got	A value of the wrong kind, such as a word where an object belongs.
  missingType	key	An item that does not name its type.
  unknownType	key, value, suggestion?	A type the union does not have, with the nearest one it has when one is close.
  missingKey	key	A required key that is absent.
  emptyValue	key	A required key written with no value. A warning: Buddy saves it as an empty string.
  emptyItem		A list item written with no value. Buddy refuses the file.
  unknownKey	key, suggestion?	A key the schema does not declare. An error where the schema closes the object, a warning where it leaves it open, nothing where it checks such keys by a rule of its own (a value that breaks the rule is a schema finding).
  schema	keyword, params	Any other rule of the schema.

• declaredIn: on an unknown key, where the keys allowed there are declared, either an action type or a definition in a scope. Point a reader at it, such as with parser.actions.get(type) or parser.pipelines.def(name).

checked lists each entry, list item and object section that could be matched to a definition and checked against it. An item missing its type, of a type the union lacks, or of the wrong kind is not on it. Each one comes with that definition (a plain value has none) and the variant a union chose. A node passed when no finding's at starts with its own.

After Buddy saves a file, it may have dropped keys or renamed them. reconcileWithSaved(findings, sentYaml, savedYaml) compares the file that was sent with the file that was saved:

• It drops a finding about a key the saved file has, under that name or under another.
• It marks an unknown key that the saved file lost as not saved by Buddy.

Requirements

Node 20.19 or newer, or Bun.

The cache lives in ~/.buddy/docs-schema, one pair of files per document: the body and its ETag. Two environment variables override the defaults:

• BUDDY_DOCS_SCHEMA_CACHE: cache directory.
• BUDDY_DOCS_SCHEMA_TTL: milliseconds a cached copy stays fresh. 0 revalidates on every access. Infinity pins a run to the version it started with.