diff --git a/.github/workflows/cli.yml b/.github/workflows/cli.yml index 1227dd76..f154e1bc 100644 --- a/.github/workflows/cli.yml +++ b/.github/workflows/cli.yml @@ -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 diff --git a/cli/AGENTS.md b/cli/AGENTS.md index 64d6f287..6aef3641 100644 --- a/cli/AGENTS.md +++ b/cli/AGENTS.md @@ -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 | @@ -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 --message ` 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 --message ` 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. diff --git a/cli/internal/cmdutil/errors_doc_test.go b/cli/internal/cmdutil/errors_doc_test.go index 13833fd2..6271bf52 100644 --- a/cli/internal/cmdutil/errors_doc_test.go +++ b/cli/internal/cmdutil/errors_doc_test.go @@ -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 - ")) + } +} diff --git a/cli/internal/cmdutil/exit.go b/cli/internal/cmdutil/exit.go index 2f189194..2acac1c8 100644 --- a/cli/internal/cmdutil/exit.go +++ b/cli/internal/cmdutil/exit.go @@ -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) — diff --git a/cli/scripts/check-skill-wire-vocab.sh b/cli/scripts/check-skill-wire-vocab.sh index 068bd0f3..8f0d9ba5 100755 --- a/cli/scripts/check-skill-wire-vocab.sh +++ b/cli/scripts/check-skill-wire-vocab.sh @@ -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