docs(cli): sweep stale wire vocab from AGENTS.md and close the CI gap that let it drift
The v0.9/v0.10 renames left `agent_invoke`, `session continue-stream`, and three deleted `mcp.*` error codes documented as current, so agents integrating against AGENTS.md branch on a surface the CLI no longer has. Two gaps let this drift sit undetected: - check-skill-wire-vocab.sh already banned every one of these terms, but only scanned skills/. The authoritative contract doc that skills are condensed from was never checked. Scan AGENTS.md and README.md too, and assert the scan targets exist so coverage cannot silently shrink again. CHANGELOG.md stays out of scope: recording a rename requires naming the legacy term. - errors_doc_test.go only verified code -> doc, so a removed code could linger in the reference table forever. Add the reverse direction. Also drops the matching `mcp.*` reference from the ExitCode doc comment.main
parent
8c0e634ee9
commit
a788115ef3
|
|
@ -47,7 +47,7 @@ jobs:
|
|||
run: go test -race -coverprofile=coverage.out ./...
|
||||
- name: go vet
|
||||
run: go vet ./...
|
||||
- name: Check skill wire vocabulary
|
||||
- name: Check agent-facing doc wire vocabulary
|
||||
if: runner.os == 'Linux'
|
||||
run: scripts/check-skill-wire-vocab.sh
|
||||
- name: Check for committed credentials in docs
|
||||
|
|
|
|||
|
|
@ -412,9 +412,6 @@ Agents parse the first colon to extract the typed code. The exit code class (see
|
|||
| `local.upload_file_not_found` | 1 | no | verify the path is correct and readable |
|
||||
| `local.user_aborted` | 1 | no (user said no) | no action taken; pass `-y/--yes` to skip the confirmation prompt |
|
||||
| `internal.error` | 1 | no | catch-all for an untyped error that reached the top (a bug or unmapped dependency error); a recurring one is a classification gap worth reporting |
|
||||
| `mcp.readonly_mode` | 1 | no | MCP tool surface is read-only; mutations not exposed in this mode |
|
||||
| `mcp.schema_unknown_command` | 1 | no | (no canonical hint) |
|
||||
| `mcp.tool_not_allowed` | 1 | no | MCP tool not in the curated allowlist |
|
||||
|
||||
<!-- ERROR_REFERENCE_END -->
|
||||
|
||||
|
|
@ -460,7 +457,7 @@ auto-retry this exit code — every exit 10 is a user-in-the-loop decision.
|
|||
|
||||
## Stream recovery
|
||||
|
||||
The `weknora session continue-stream <session-id> --message <msg-id>` command resumes an SSE event stream for an existing assistant message. Use cases: network-blip recovery, long-running agent invocation polling, completed-stream inspection.
|
||||
The `weknora session resume <session-id> --message <msg-id>` command resumes an SSE event stream for an existing assistant message. Use cases: network-blip recovery, long-running agent invocation polling, completed-stream inspection.
|
||||
|
||||
### Server semantics: replay-from-0, not cursor-resume
|
||||
|
||||
|
|
@ -479,7 +476,7 @@ The server **replays all stored events from the start** of the assistant message
|
|||
| `STREAM_MANAGER_TYPE=redis` | **1 hour** (server-side; not configurable from the CLI) |
|
||||
| `STREAM_MANAGER_TYPE=memory` (default) | **Process lifetime** (server restart = data loss; no explicit cleanup logic) |
|
||||
|
||||
After TTL, `weknora session continue-stream` returns the typed error `local.sse_stream_aborted`, which maps to exit code 1 per the Error code reference.
|
||||
After TTL, `weknora session resume` returns the typed error `local.sse_stream_aborted`, which maps to exit code 1 per the Error code reference.
|
||||
|
||||
## Dry-run contract
|
||||
|
||||
|
|
@ -552,7 +549,7 @@ The curated 10 tools (`cli/internal/mcp/tools.go`):
|
|||
| `search_chunks` | hybrid (vector + keyword) retrieval |
|
||||
| `chat` | stream a RAG answer; auto-creates a session if absent |
|
||||
| `agent_list` | list custom agents |
|
||||
| `agent_invoke` | run a query through a custom agent |
|
||||
| `session_ask` | run a query through a custom agent |
|
||||
|
||||
Adding a tool is a deliberate API expansion — the AI-agent-callable surface is the reason this CLI ships an MCP server, not its CLI command list, so the registration list in `registerTools` is maintained by hand.
|
||||
|
||||
|
|
|
|||
|
|
@ -7,13 +7,10 @@ import (
|
|||
"testing"
|
||||
)
|
||||
|
||||
// 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) {
|
||||
// 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()
|
||||
// From cli/internal/cmdutil/, go up two levels to find cli/AGENTS.md.
|
||||
docPath, err := filepath.Abs("../../AGENTS.md")
|
||||
if err != nil {
|
||||
|
|
@ -32,7 +29,42 @@ func TestAllCodes_DocumentedInAGENTS(t *testing.T) {
|
|||
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)
|
||||
}
|
||||
refSection := doc[startIdx:endIdx]
|
||||
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)
|
||||
|
||||
missing := []string{}
|
||||
for _, c := range AllCodes() {
|
||||
|
|
@ -46,3 +78,37 @@ func TestAllCodes_DocumentedInAGENTS(t *testing.T) {
|
|||
strings.Join(missing, "\n - "))
|
||||
}
|
||||
}
|
||||
|
||||
// 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 {
|
||||
t.Errorf("the following error codes are documented in cli/AGENTS.md \"Error code reference\" but are not registered in AllCodes():\n - %s\n\nDrop the row if the code was removed, or register the code if the row is correct.",
|
||||
strings.Join(stale, "\n - "))
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ func GetProfile() string { return globalProfile }
|
|||
// ExitCode maps an error to the documented CLI exit code.
|
||||
// - 0 success
|
||||
// - 1 generic / unknown typed error - fallback bucket: resource.already_exists,
|
||||
// resource.locked, local.*, mcp.*, operation.failed, server.session_create_failed
|
||||
// resource.locked, local.*, operation.failed, server.session_create_failed
|
||||
// (workflow-level, see special case below), and any code outside the named
|
||||
// buckets below
|
||||
// - 2 cobra-parse problem (unrecognised flag, arg-count violation) —
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#!/usr/bin/env bash
|
||||
# check-skill-wire-vocab.sh — fail if cli/skills/ still references wire
|
||||
# vocabulary that the CLI has renamed or removed. Wire-shape changes must
|
||||
# sweep skills in the same PR.
|
||||
# check-skill-wire-vocab.sh — fail if the agent-facing docs still reference wire
|
||||
# vocabulary that the CLI has renamed or removed. Wire-shape changes must sweep
|
||||
# every agent-facing doc in the same PR.
|
||||
set -euo pipefail
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
|
|
@ -18,13 +18,33 @@ BANNED=(
|
|||
"agent create --kb:agent create --attach-kb (renamed in v0.9)"
|
||||
"kb init:kb config set (renamed — kb init removed)"
|
||||
"continue-stream:session resume (renamed)"
|
||||
"retry_command:retry_argv (error envelope field renamed in v0.10)"
|
||||
)
|
||||
|
||||
# Every doc an agent or integrator reads as current truth. AGENTS.md and
|
||||
# README.md are in scope because they are the authoritative wire contract that
|
||||
# skills are condensed from — a rename that lands in skills/ but not here leaves
|
||||
# the source of truth wrong.
|
||||
#
|
||||
# CHANGELOG.md is deliberately NOT scanned: recording a rename requires naming
|
||||
# the legacy term, so scanning it would guarantee a false positive.
|
||||
SCAN_TARGETS=(skills/ AGENTS.md README.md)
|
||||
|
||||
# The v0.10 retry_command miss happened because the scan silently covered less
|
||||
# than the docs that needed covering. Fail loudly if a target disappears rather
|
||||
# than quietly shrinking coverage again.
|
||||
for target in "${SCAN_TARGETS[@]}"; do
|
||||
if [ ! -e "$target" ]; then
|
||||
echo "scan target '$target' does not exist — update SCAN_TARGETS" >&2
|
||||
exit 2
|
||||
fi
|
||||
done
|
||||
|
||||
fail=0
|
||||
for entry in "${BANNED[@]}"; do
|
||||
term="${entry%%:*}"
|
||||
why="${entry#*:}"
|
||||
if hits=$(grep -rn --include='*.md' -F "$term" skills/ 2>/dev/null); then
|
||||
if hits=$(grep -rn --include='*.md' -F "$term" "${SCAN_TARGETS[@]}" 2>/dev/null); then
|
||||
echo "BANNED wire vocab '$term' found (use: $why):"
|
||||
echo "$hits"
|
||||
fail=1
|
||||
|
|
|
|||
Loading…
Reference in New Issue