summercms/docs/console/utilities.md

title, description, section, order

title	description	section	order
Utilities	The summer commands for API parity testing and for building, syncing and previewing this documentation, with their flags.	console	50

Utilities

Besides building and scaffolding, the summer tool carries two groups of utility commands: API parity testing, used when you port an existing backend, and the documentation build.

API parity commands

When you port an existing backend to SummerCMS, its real responses are the contract your port must meet. The parity commands wrap tide: they record fixtures from the reference backend and replay them against the port. Every address they listen on or connect to must be a loopback address, and captured secrets go to a variables file with mode 0600, outside the committed fixtures.

Command	Flags	Purpose
summer parity:proxy	--listen (default 127.0.0.1:8422), --upstream (default http://127.0.0.1:8423), --session, --rules, --vars, --fixtures, --update	Runs a recording reverse proxy in front of the reference backend. Point a real client at it; each named session (from the X-Parity-Session header, or --session) is written as one fixture.
summer parity:record	--spec, --target, --output, --rules, --vars, --update; --manifest, --fixtures, --next-batch, --resume, --allow-incomplete, --require-recorded	Sends the requests of a YAML spec to a target and records the responses as a fixture, or records the missing cases of a route manifest in batches of at most 15.
summer parity:replay	--fixtures, --target, --vars, --manifest, --self-check, --require-recorded	Replays recorded fixtures against a backend and reports the differences after masking IDs and timestamps.
summer parity:broadcasts	--flow, --target, --vars, --listen (default 127.0.0.1:8424), --out, --name, --step, --ids, --rules, --api-key, --settle (default 500ms), --pending	Runs a flow against the reference backend with a fake Centrifugo server and records the realtime publications it sends into a golden file.

A typical port records once against the reference backend and replays against the Go backend on every change:

summer parity:record --spec testdata/parity/posts.spec.yaml --target http://127.0.0.1:8000 --output testdata/parity/posts.yaml --vars /tmp/parity/vars.yaml
summer parity:replay --fixtures testdata/parity --target http://127.0.0.1:8080 --vars /tmp/parity/vars.yaml

Documentation commands

These docs are Markdown files under docs/, plus every module README, built into a static site by summer. Run the commands from the framework root.

Command	Flags	Purpose
summer docs:build	--root (default .), --src, --out, --base-url, --site-url, --site-label, --check	Checks every page and writes the site to site/ (or --out): HTML pages, a raw .md copy of each page, llms.txt, llms-full.txt and the search index. With --check it only reports problems and writes nothing.
summer docs:sync	--root (default .), --src	Rewrites every code block that has a src= reference from its source file.
summer docs:serve	--root (default .), --src, --base-url, --site-url, --site-label, --addr (default 127.0.0.1:8088), --allow-remote	Builds the site into a temporary directory, serves it and rebuilds when a page, a module or a referenced source changes. A failed rebuild prints its problems and keeps serving the last good build.

docs/site.yaml accepts two optional keys, site_url and site_label, that add a link back to the main site to every page header. With site_url: https://acme.example/ the link reads "acme.example". Without site_label the label is the URL's host, or Home when site_url is a path such as /. site_url must be an http:// or https:// URL with a host, or a path starting with a single /. The --site-url and --site-label flags override the two keys the way --base-url overrides base_url.

summer docs:build --check
summer docs:sync
summer docs:serve

docs:build fails, and writes nothing, when a page names an identifier that does not exist, links to a missing page or anchor, shows a command that neither summer nor an application binary has, or has a src= code block that differs from its source. It also fails on a Go code block (including golang) without a src= reference, a src= code block inside a callout, blockquote or list item (src= blocks must be top-level), and a src= code block in a module README. A src= target must be code go test ./... compiles and runs, that is a file in the default build, inside a Test function or an Example with an // Output: comment, or a function one of them calls. After you change code that a page shows, run summer docs:sync to refresh the copies.

docs:serve listens only on a loopback address unless you pass --allow-remote. Use it to preview search, which browsers block when you open the built files directly from disk.