Skip to content

docs: add guide for optional output-format dependencies and strict JSON consumer validation - #350

Open
bogusdeck wants to merge 2 commits into
basefoundry:mainfrom
bogusdeck:docs-updates
Open

bogusdeck wants to merge 2 commits into
basefoundry:mainfrom
bogusdeck:docs-updates

Conversation

@bogusdeck

@bogusdeck bogusdeck commented Sep 14, 2026

Copy link
Copy Markdown

Summary

This PR addresses two documentation issues:

  1. docs: add a focused guide for optional output-format dependencies #346: Add a guide for optional output-format dependencies.
  2. docs: document strict JSON consumer validation with Node #345: Document strict JSON consumer validation with Node.js.

Changes

  • docs/output-contracts.md

    • Added a table documenting optional output-format dependencies, including yaml and rich.
  • docs/json-contracts.md

    • Added a section explaining how to validate base CLI JSON and NDJSON output using Node.js's JSON.parse.

Notes

Both changes are documentation-only and follow the acceptance criteria defined in their respective issues.

Comment thread docs/json-contracts.md
// Validate the envelope structure
if (parsed.schema_version !== 1) {
throw new Error('Unsupported schema_version');
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cleanup: the new "Contract fixtures and validator" section is a near-verbatim duplicate of the paragraph already present ~25 lines above it in the same file (both describe CI validating fixtures against packaged schemas via a Python validator and a Node.js reader). Consider merging to avoid having to update the same claim in two places.

Comment thread docs/output-contracts.md
is unavailable or fails.

## Optional output-format dependencies

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doc accuracy: this table says a missing PyYAML surfaces a raw ImportError: No module named 'yaml', but the code never lets that propagate — require_yaml() (lib/python/base_cli/_dependencies.py) catches ImportError and re-raises a RuntimeError with an actionable install hint, which the caller wraps into OutputFormatError. A user grepping logs for the documented string won't find it, and the doc omits the actual (more useful) message the CLI produces.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants