docs(cli): README / AGENTS.md / CHANGELOG + CI parity test
Wire-contract documentation and the CI check that keeps it honest.
* cli/README.md gains a verbatim --help block (top-level + subtrees),
an Exit codes table covering 0/1/2/3/4/5/6/7/10/124/130, a "Status
vs check" verb-pair subtable, and a "doc wait" paragraph spelling out
the four exit codes (0 / 1 / 124 / 130). The api passthrough note
trims storage provider out of the deep-config list now that
kb create --storage-provider is a polished flag.
* cli/AGENTS.md becomes the contributor guide: build/test, CRUD flag
conventions, the status/check verb pattern, long-poll wait commands,
the SetAgentHelp pattern, and a full Error code reference with 35
typed codes mapped to namespaces, exit codes, retryable / hint
guidance. Reference section is bracketed by HTML markers so a CI
parity test can keep it in sync with AllCodes().
* cli/internal/cmdutil/errors_doc_test.go enforces parity: every code
in AllCodes() must appear in AGENTS.md inside the markers, and
AGENTS.md must not reference codes that no longer exist. Fails CI
if a new typed code is added without documentation.
* CHANGELOG.md gets the v0.6 entry: BREAKING (--json / --no-stream /
WEKNORA_SDK_DEBUG / kb create --name), Added (--format / --jq /
doc wait / --log-level / kb-and-agent status & check / multi-id
delete / api --paginate / MCP schema extension / SetAgentHelp /
signal-aware ctx / kb create --storage-provider / new operation.*
namespace), Changed (multi-id partial-failure exit code, doc upload
FlagError, --log-level FlagError, multi-id stdout cleanup, README /
AGENTS.md changes), with a Migration from v0.5 section walking
every BREAKING through its v0.6 replacement.
2026-05-17 17:38:42 +00:00
package cmdutil
import (
"os"
"path/filepath"
"strings"
"testing"
)
2026-08-19 09:31:55 +00:00
// loadErrorReferenceSection returns the body of the cli/AGENTS.md "Error code
// reference" section, delimited by the ERROR_REFERENCE_START/END markers.
func loadErrorReferenceSection ( t * testing . T ) string {
t . Helper ( )
docs(cli): README / AGENTS.md / CHANGELOG + CI parity test
Wire-contract documentation and the CI check that keeps it honest.
* cli/README.md gains a verbatim --help block (top-level + subtrees),
an Exit codes table covering 0/1/2/3/4/5/6/7/10/124/130, a "Status
vs check" verb-pair subtable, and a "doc wait" paragraph spelling out
the four exit codes (0 / 1 / 124 / 130). The api passthrough note
trims storage provider out of the deep-config list now that
kb create --storage-provider is a polished flag.
* cli/AGENTS.md becomes the contributor guide: build/test, CRUD flag
conventions, the status/check verb pattern, long-poll wait commands,
the SetAgentHelp pattern, and a full Error code reference with 35
typed codes mapped to namespaces, exit codes, retryable / hint
guidance. Reference section is bracketed by HTML markers so a CI
parity test can keep it in sync with AllCodes().
* cli/internal/cmdutil/errors_doc_test.go enforces parity: every code
in AllCodes() must appear in AGENTS.md inside the markers, and
AGENTS.md must not reference codes that no longer exist. Fails CI
if a new typed code is added without documentation.
* CHANGELOG.md gets the v0.6 entry: BREAKING (--json / --no-stream /
WEKNORA_SDK_DEBUG / kb create --name), Added (--format / --jq /
doc wait / --log-level / kb-and-agent status & check / multi-id
delete / api --paginate / MCP schema extension / SetAgentHelp /
signal-aware ctx / kb create --storage-provider / new operation.*
namespace), Changed (multi-id partial-failure exit code, doc upload
FlagError, --log-level FlagError, multi-id stdout cleanup, README /
AGENTS.md changes), with a Migration from v0.5 section walking
every BREAKING through its v0.6 replacement.
2026-05-17 17:38:42 +00:00
// From cli/internal/cmdutil/, go up two levels to find cli/AGENTS.md.
docPath , err := filepath . Abs ( "../../AGENTS.md" )
if err != nil {
t . Fatalf ( "abs: %v" , err )
}
content , err := os . ReadFile ( docPath )
if err != nil {
t . Fatalf ( "read %s: %v" , docPath , err )
}
doc := string ( content )
const startMarker = "<!-- ERROR_REFERENCE_START -->"
const endMarker = "<!-- ERROR_REFERENCE_END -->"
startIdx := strings . Index ( doc , startMarker )
endIdx := strings . Index ( doc , endMarker )
if startIdx == - 1 || endIdx == - 1 || endIdx <= startIdx {
t . Fatalf ( "error-reference markers missing or malformed in %s:\n start=%d end=%d" , docPath , startIdx , endIdx )
}
2026-08-19 09:31:55 +00:00
return doc [ startIdx : endIdx ]
}
// documentedCodes extracts the codes listed in the first column of the error
// reference table. Only the first column is read: hint cells also carry
// backticked flags, paths, and commands that are not error codes.
func documentedCodes ( refSection string ) [ ] string {
var codes [ ] string
for _ , line := range strings . Split ( refSection , "\n" ) {
line = strings . TrimSpace ( line )
if ! strings . HasPrefix ( line , "|" ) {
continue
}
cells := strings . Split ( strings . Trim ( line , "|" ) , "|" )
if len ( cells ) == 0 {
continue
}
// Skips the header ("Code") and separator ("---") rows, which carry no
// backticks in the first column.
first := strings . TrimSpace ( cells [ 0 ] )
if len ( first ) < 3 || ! strings . HasPrefix ( first , "`" ) || ! strings . HasSuffix ( first , "`" ) {
continue
}
codes = append ( codes , strings . Trim ( first , "`" ) )
}
return codes
}
// TestAllCodes_DocumentedInAGENTS verifies every typed code returned by
// AllCodes() surfaces in cli/AGENTS.md "Error code reference" section
// (delimited by ERROR_REFERENCE_START/END markers).
//
// Prevents drift: a contributor adding a new ErrorCode without updating
// the doc fails this test, forcing the doc to stay current.
func TestAllCodes_DocumentedInAGENTS ( t * testing . T ) {
refSection := loadErrorReferenceSection ( t )
docs(cli): README / AGENTS.md / CHANGELOG + CI parity test
Wire-contract documentation and the CI check that keeps it honest.
* cli/README.md gains a verbatim --help block (top-level + subtrees),
an Exit codes table covering 0/1/2/3/4/5/6/7/10/124/130, a "Status
vs check" verb-pair subtable, and a "doc wait" paragraph spelling out
the four exit codes (0 / 1 / 124 / 130). The api passthrough note
trims storage provider out of the deep-config list now that
kb create --storage-provider is a polished flag.
* cli/AGENTS.md becomes the contributor guide: build/test, CRUD flag
conventions, the status/check verb pattern, long-poll wait commands,
the SetAgentHelp pattern, and a full Error code reference with 35
typed codes mapped to namespaces, exit codes, retryable / hint
guidance. Reference section is bracketed by HTML markers so a CI
parity test can keep it in sync with AllCodes().
* cli/internal/cmdutil/errors_doc_test.go enforces parity: every code
in AllCodes() must appear in AGENTS.md inside the markers, and
AGENTS.md must not reference codes that no longer exist. Fails CI
if a new typed code is added without documentation.
* CHANGELOG.md gets the v0.6 entry: BREAKING (--json / --no-stream /
WEKNORA_SDK_DEBUG / kb create --name), Added (--format / --jq /
doc wait / --log-level / kb-and-agent status & check / multi-id
delete / api --paginate / MCP schema extension / SetAgentHelp /
signal-aware ctx / kb create --storage-provider / new operation.*
namespace), Changed (multi-id partial-failure exit code, doc upload
FlagError, --log-level FlagError, multi-id stdout cleanup, README /
AGENTS.md changes), with a Migration from v0.5 section walking
every BREAKING through its v0.6 replacement.
2026-05-17 17:38:42 +00:00
missing := [ ] string { }
for _ , c := range AllCodes ( ) {
needle := "`" + string ( c ) + "`"
if ! strings . Contains ( refSection , needle ) {
missing = append ( missing , string ( c ) )
}
}
if len ( missing ) > 0 {
t . Errorf ( "the following error codes are registered in AllCodes() but not listed in cli/AGENTS.md \"Error code reference\" section between the ERROR_REFERENCE markers:\n - %s\n\nAdd a row for each missing code to keep agent-facing docs in sync." ,
strings . Join ( missing , "\n - " ) )
}
}
2026-08-19 09:31:55 +00:00
// TestDocumentedCodes_RegisteredInAllCodes is the reverse of
// TestAllCodes_DocumentedInAGENTS: every code the doc advertises must still be
// a code the CLI can emit.
//
// Without this direction a removed code lingers in the doc forever, and agents
// branch on codes that will never arrive — the failure mode that left three
// `mcp.*` codes documented for two minor versions after they were deleted.
func TestDocumentedCodes_RegisteredInAllCodes ( t * testing . T ) {
refSection := loadErrorReferenceSection ( t )
registered := make ( map [ string ] bool , len ( AllCodes ( ) ) )
for _ , c := range AllCodes ( ) {
registered [ string ( c ) ] = true
}
documented := documentedCodes ( refSection )
// Guards against the parser silently matching nothing, which would make this
// check pass vacuously if the table format ever changes.
if len ( documented ) == 0 {
t . Fatal ( "parsed zero error codes out of the reference table; the table format or the parser changed" )
}
stale := [ ] string { }
for _ , c := range documented {
if ! registered [ c ] {
stale = append ( stale , c )
}
}
if len ( stale ) > 0 {
2026-08-20 08:49:32 +00:00
t . Errorf ( "the following error codes are documented in cli/AGENTS.md " +
"\"Error code reference\" but are not registered in AllCodes():\n - %s\n\n" +
"Drop the row if the code was removed, or register the code if the row is correct." ,
2026-08-19 09:31:55 +00:00
strings . Join ( stale , "\n - " ) )
}
}