[object Object]

← back to Cli Printing Press

fix(cli): gate provenance diagnostic on wantsHumanTable (#1280)

f5348488fe100fc150c1a363875542a3b3c956aa · 2026-05-13 11:45:06 -0700 · Trevin Chow

* fix(cli): gate provenance diagnostic on wantsHumanTable to keep machine-format stdout clean

Generated list commands called `printProvenance` unconditionally before the
format-branching code. The helper itself routes to stderr but only suppresses
when stdout is non-TTY, so interactive runs with `--json`/`--csv`/`--compact`/
`--quiet`/`--plain`/`--select` still emitted the `N results (live)` line that
visually merged with stdout JSON in PowerShell/iTerm. Wrap the call in a
`wantsHumanTable(cmd.OutOrStdout(), flags)` gate in both the multi-endpoint
and promoted-command templates so machine-format flags suppress it.

A new generator test asserts the gate is present in both template outputs
and that no ungated call sneaks in alongside it. SYNC markers in the two
templates flag the parallel block so future edits stay aligned.

* fix(cli): tighten provenance-gate test to verify call lies inside the gate's braces

The previous assertion only checked that `printProvenance` appeared somewhere
after the `if wantsHumanTable(...)` opening line, so a regression that moved
the call past the gate's closing brace would still satisfy the test. Find the
matching close brace via brace-balance from the gate's opening `{`, then
assert the call's offset is strictly less than the close-brace offset.

Files touched

Diff

commit f5348488fe100fc150c1a363875542a3b3c956aa
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Wed May 13 11:45:06 2026 -0700

    fix(cli): gate provenance diagnostic on wantsHumanTable (#1280)
    
    * fix(cli): gate provenance diagnostic on wantsHumanTable to keep machine-format stdout clean
    
    Generated list commands called `printProvenance` unconditionally before the
    format-branching code. The helper itself routes to stderr but only suppresses
    when stdout is non-TTY, so interactive runs with `--json`/`--csv`/`--compact`/
    `--quiet`/`--plain`/`--select` still emitted the `N results (live)` line that
    visually merged with stdout JSON in PowerShell/iTerm. Wrap the call in a
    `wantsHumanTable(cmd.OutOrStdout(), flags)` gate in both the multi-endpoint
    and promoted-command templates so machine-format flags suppress it.
    
    A new generator test asserts the gate is present in both template outputs
    and that no ungated call sneaks in alongside it. SYNC markers in the two
    templates flag the parallel block so future edits stay aligned.
    
    * fix(cli): tighten provenance-gate test to verify call lies inside the gate's braces
    
    The previous assertion only checked that `printProvenance` appeared somewhere
    after the `if wantsHumanTable(...)` opening line, so a regression that moved
    the call past the gate's closing brace would still satisfy the test. Find the
    matching close brace via brace-balance from the gate's opening `{`, then
    assert the call's offset is strictly less than the close-brace offset.
---
 internal/generator/generator_test.go               | 110 +++++++++++++++++++++
 .../generator/templates/command_endpoint.go.tmpl   |   8 +-
 .../generator/templates/command_promoted.go.tmpl   |   8 +-
 internal/generator/templates/skill.md.tmpl         |   2 +-
 .../printing-press-rich-auth/SKILL.md              |   2 +-
 .../printing-press-golden/SKILL.md                 |   2 +-
 .../internal/cli/projects_list.go                  |   8 +-
 .../internal/cli/projects_tasks_list-project.go    |   8 +-
 .../internal/cli/promoted_public.go                |   8 +-
 .../internal/cli/promoted_games.go                 |   8 +-
 .../internal/cli/promoted_leagues.go               |   8 +-
 .../internal/cli/items_enterprise.go               |   8 +-
 .../tier-routing-golden/internal/cli/items_list.go |   8 +-
 .../internal/cli/items_premium.go                  |   8 +-
 14 files changed, 173 insertions(+), 23 deletions(-)

diff --git a/internal/generator/generator_test.go b/internal/generator/generator_test.go
index 038c6537..4d9fa1dc 100644
--- a/internal/generator/generator_test.go
+++ b/internal/generator/generator_test.go
@@ -4456,6 +4456,116 @@ func TestWrapWithProvenance_NonJSONEmbeddedAsString(t *testing.T) {
 	runGoCommand(t, outputDir, "test", "./internal/cli", "-run", "TestUnwrapSingleKeyArray|TestWrapWithProvenance_")
 }
 
+// findMatchingBrace returns the index of the `}` that closes the `{` at
+// openIdx. Treats `{` and `}` as raw bytes — only safe for generated Go
+// regions known to contain no string literals or comments holding braces.
+// Returns -1 when no match is found.
+func findMatchingBrace(src string, openIdx int) int {
+	if openIdx >= len(src) || src[openIdx] != '{' {
+		return -1
+	}
+	depth := 0
+	for i := openIdx; i < len(src); i++ {
+		switch src[i] {
+		case '{':
+			depth++
+		case '}':
+			depth--
+			if depth == 0 {
+				return i
+			}
+		}
+	}
+	return -1
+}
+
+// TestGeneratedListCommand_ProvenanceGatedByHumanTable asserts that the
+// `N results (live|cached ...)` diagnostic is gated by wantsHumanTable in
+// every generated list command. Without the gate the line leaks into stdout
+// of agent-piped consumers — every printed CLI ships the same list-handler
+// shape, so a template regression here re-introduces the leak everywhere.
+func TestGeneratedListCommand_ProvenanceGatedByHumanTable(t *testing.T) {
+	t.Parallel()
+
+	apiSpec := &spec.APISpec{
+		Name:    "provenancegate",
+		Version: "0.1.0",
+		BaseURL: "https://api.example.com",
+		Auth:    spec.AuthConfig{Type: "none"},
+		Config:  spec.ConfigSpec{Format: "toml", Path: "~/.config/provenancegate-pp-cli/config.toml"},
+		Resources: map[string]spec.Resource{
+			// Multi-endpoint resource exercises command_endpoint.go.tmpl.
+			"items": {
+				Description: "Items",
+				Endpoints: map[string]spec.Endpoint{
+					"list": {
+						Method:      "GET",
+						Path:        "/items",
+						Description: "List items",
+						Response:    spec.ResponseDef{Type: "array"},
+					},
+					"get": {
+						Method:      "GET",
+						Path:        "/items/{id}",
+						Description: "Get one item",
+						Params:      []spec.Param{{Name: "id", Type: "string", Required: true, Positional: true, PathParam: true}},
+					},
+				},
+			},
+			// Single-endpoint resource exercises command_promoted.go.tmpl.
+			"things": {
+				Description: "Things",
+				Endpoints: map[string]spec.Endpoint{
+					"list": {
+						Method:      "GET",
+						Path:        "/things",
+						Description: "List things",
+						Response:    spec.ResponseDef{Type: "array"},
+					},
+				},
+			},
+		},
+	}
+
+	outputDir := filepath.Join(t.TempDir(), naming.CLI(apiSpec.Name))
+	gen := New(apiSpec, outputDir)
+	gen.VisionSet = VisionTemplateSet{Store: true}
+	require.NoError(t, gen.Generate())
+
+	cases := []struct {
+		name string
+		file string
+	}{
+		{"endpoint template", "items_list.go"},
+		{"promoted template", "promoted_things.go"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			body, err := os.ReadFile(filepath.Join(outputDir, "internal", "cli", tc.file))
+			require.NoError(t, err, "generated list command file must exist")
+			src := string(body)
+
+			require.Equal(t, 1, strings.Count(src, "printProvenance(cmd,"),
+				"exactly one printProvenance call should remain; a second ungated call would re-leak the diagnostic")
+
+			gateIdx := strings.Index(src, "if wantsHumanTable(cmd.OutOrStdout(), flags) {")
+			require.GreaterOrEqual(t, gateIdx, 0,
+				"printProvenance call must be wrapped in a wantsHumanTable gate")
+			require.Equal(t, -1, strings.Index(src[:gateIdx], "printProvenance(cmd,"),
+				"no ungated printProvenance call may precede the wantsHumanTable gate")
+
+			openBraceOffset := strings.Index(src[gateIdx:], "{")
+			require.GreaterOrEqual(t, openBraceOffset, 0, "gate must have an opening brace")
+			closeBraceIdx := findMatchingBrace(src, gateIdx+openBraceOffset)
+			require.Greater(t, closeBraceIdx, gateIdx, "gate must have a matching closing brace")
+			provIdx := strings.Index(src[gateIdx:], "printProvenance(cmd,")
+			require.GreaterOrEqual(t, provIdx, 0, "printProvenance must appear after the gate opens")
+			require.Less(t, gateIdx+provIdx, closeBraceIdx,
+				"printProvenance must appear between the gate's open and close braces, not after the block")
+		})
+	}
+}
+
 // --- Unit 3: Top-Level Command Promotion Tests ---
 
 func TestToKebab(t *testing.T) {
diff --git a/internal/generator/templates/command_endpoint.go.tmpl b/internal/generator/templates/command_endpoint.go.tmpl
index 912a7713..8ffc98a6 100644
--- a/internal/generator/templates/command_endpoint.go.tmpl
+++ b/internal/generator/templates/command_endpoint.go.tmpl
@@ -519,8 +519,12 @@ func new{{camel .FuncPrefix}}{{camel .EndpointName}}Cmd(flags *rootFlags) *cobra
 {{- end}}
 {{- if or (eq .Endpoint.Method "GET") (eq .Endpoint.Method "HEAD")}}
 {{- if .HasStore}}
-			// Print provenance to stderr for human-facing output
-			{
+			// Print provenance to stderr for human-facing output only.
+			// Machine-format flags (--json, --csv, --compact, --quiet, --plain,
+			// --select) and piped stdout suppress this line; the JSON envelope
+			// already carries meta.source for those consumers.
+			// SYNC: keep this gate aligned with command_promoted.go.tmpl.
+			if wantsHumanTable(cmd.OutOrStdout(), flags) {
 				var countItems []json.RawMessage
 				_ = json.Unmarshal(data, &countItems)
 				printProvenance(cmd, len(countItems), prov)
diff --git a/internal/generator/templates/command_promoted.go.tmpl b/internal/generator/templates/command_promoted.go.tmpl
index aa6e4862..01be306b 100644
--- a/internal/generator/templates/command_promoted.go.tmpl
+++ b/internal/generator/templates/command_promoted.go.tmpl
@@ -234,8 +234,12 @@ func new{{camel .PromotedName}}PromotedCmd(flags *rootFlags) *cobra.Command {
 			// so output helpers see the inner data, not the wrapper.
 			data = extractResponseData(data)
 
-			// Print provenance to stderr
-			{
+			// Print provenance to stderr for human-facing output only.
+			// Machine-format flags (--json, --csv, --compact, --quiet, --plain,
+			// --select) and piped stdout suppress this line; the JSON envelope
+			// already carries meta.source for those consumers.
+			// SYNC: keep this gate aligned with command_endpoint.go.tmpl.
+			if wantsHumanTable(cmd.OutOrStdout(), flags) {
 				var countItems []json.RawMessage
 				if json.Unmarshal(data, &countItems) != nil {
 					// Single object, not an array
diff --git a/internal/generator/templates/skill.md.tmpl b/internal/generator/templates/skill.md.tmpl
index 9417618c..38553899 100644
--- a/internal/generator/templates/skill.md.tmpl
+++ b/internal/generator/templates/skill.md.tmpl
@@ -292,7 +292,7 @@ Commands that read from the local store or the API wrap output in a provenance e
 }
 ```
 
-Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.
+Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout.
 {{- end}}
 
 ## Agent Feedback
diff --git a/testdata/golden/expected/generate-golden-api-rich-auth/printing-press-rich-auth/SKILL.md b/testdata/golden/expected/generate-golden-api-rich-auth/printing-press-rich-auth/SKILL.md
index 4c02acbf..7cc3442c 100644
--- a/testdata/golden/expected/generate-golden-api-rich-auth/printing-press-rich-auth/SKILL.md
+++ b/testdata/golden/expected/generate-golden-api-rich-auth/printing-press-rich-auth/SKILL.md
@@ -89,7 +89,7 @@ Commands that read from the local store or the API wrap output in a provenance e
 }
 ```
 
-Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.
+Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout.
 
 ## Agent Feedback
 
diff --git a/testdata/golden/expected/generate-golden-api/printing-press-golden/SKILL.md b/testdata/golden/expected/generate-golden-api/printing-press-golden/SKILL.md
index a6e1aa68..a00c4e7a 100644
--- a/testdata/golden/expected/generate-golden-api/printing-press-golden/SKILL.md
+++ b/testdata/golden/expected/generate-golden-api/printing-press-golden/SKILL.md
@@ -98,7 +98,7 @@ Commands that read from the local store or the API wrap output in a provenance e
 }
 ```
 
-Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.
+Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout.
 
 ## Agent Feedback
 
diff --git a/testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/projects_list.go b/testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/projects_list.go
index 471f181c..53c56072 100644
--- a/testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/projects_list.go
+++ b/testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/projects_list.go
@@ -50,8 +50,12 @@ func newProjectsListCmd(flags *rootFlags) *cobra.Command {
 			if err != nil {
 				return classifyAPIError(err, flags)
 			}
-			// Print provenance to stderr for human-facing output
-			{
+			// Print provenance to stderr for human-facing output only.
+			// Machine-format flags (--json, --csv, --compact, --quiet, --plain,
+			// --select) and piped stdout suppress this line; the JSON envelope
+			// already carries meta.source for those consumers.
+			// SYNC: keep this gate aligned with command_promoted.go.tmpl.
+			if wantsHumanTable(cmd.OutOrStdout(), flags) {
 				var countItems []json.RawMessage
 				_ = json.Unmarshal(data, &countItems)
 				printProvenance(cmd, len(countItems), prov)
diff --git a/testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/projects_tasks_list-project.go b/testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/projects_tasks_list-project.go
index 5ac7f8d9..63c515e3 100644
--- a/testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/projects_tasks_list-project.go
+++ b/testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/projects_tasks_list-project.go
@@ -55,8 +55,12 @@ func newProjectsTasksListProjectCmd(flags *rootFlags) *cobra.Command {
 			if err != nil {
 				return classifyAPIError(err, flags)
 			}
-			// Print provenance to stderr for human-facing output
-			{
+			// Print provenance to stderr for human-facing output only.
+			// Machine-format flags (--json, --csv, --compact, --quiet, --plain,
+			// --select) and piped stdout suppress this line; the JSON envelope
+			// already carries meta.source for those consumers.
+			// SYNC: keep this gate aligned with command_promoted.go.tmpl.
+			if wantsHumanTable(cmd.OutOrStdout(), flags) {
 				var countItems []json.RawMessage
 				_ = json.Unmarshal(data, &countItems)
 				printProvenance(cmd, len(countItems), prov)
diff --git a/testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/promoted_public.go b/testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/promoted_public.go
index 967f9f59..a570d0a1 100644
--- a/testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/promoted_public.go
+++ b/testdata/golden/expected/generate-golden-api/printing-press-golden/internal/cli/promoted_public.go
@@ -35,8 +35,12 @@ func newPublicPromotedCmd(flags *rootFlags) *cobra.Command {
 			// so output helpers see the inner data, not the wrapper.
 			data = extractResponseData(data)
 
-			// Print provenance to stderr
-			{
+			// Print provenance to stderr for human-facing output only.
+			// Machine-format flags (--json, --csv, --compact, --quiet, --plain,
+			// --select) and piped stdout suppress this line; the JSON envelope
+			// already carries meta.source for those consumers.
+			// SYNC: keep this gate aligned with command_endpoint.go.tmpl.
+			if wantsHumanTable(cmd.OutOrStdout(), flags) {
 				var countItems []json.RawMessage
 				if json.Unmarshal(data, &countItems) != nil {
 					// Single object, not an array
diff --git a/testdata/golden/expected/generate-sync-walker-api/sync-walker-golden/internal/cli/promoted_games.go b/testdata/golden/expected/generate-sync-walker-api/sync-walker-golden/internal/cli/promoted_games.go
index 4df2359a..772a1de3 100644
--- a/testdata/golden/expected/generate-sync-walker-api/sync-walker-golden/internal/cli/promoted_games.go
+++ b/testdata/golden/expected/generate-sync-walker-api/sync-walker-golden/internal/cli/promoted_games.go
@@ -35,8 +35,12 @@ func newGamesPromotedCmd(flags *rootFlags) *cobra.Command {
 			// so output helpers see the inner data, not the wrapper.
 			data = extractResponseData(data)
 
-			// Print provenance to stderr
-			{
+			// Print provenance to stderr for human-facing output only.
+			// Machine-format flags (--json, --csv, --compact, --quiet, --plain,
+			// --select) and piped stdout suppress this line; the JSON envelope
+			// already carries meta.source for those consumers.
+			// SYNC: keep this gate aligned with command_endpoint.go.tmpl.
+			if wantsHumanTable(cmd.OutOrStdout(), flags) {
 				var countItems []json.RawMessage
 				if json.Unmarshal(data, &countItems) != nil {
 					// Single object, not an array
diff --git a/testdata/golden/expected/generate-sync-walker-api/sync-walker-golden/internal/cli/promoted_leagues.go b/testdata/golden/expected/generate-sync-walker-api/sync-walker-golden/internal/cli/promoted_leagues.go
index bd549e9e..49e56a5f 100644
--- a/testdata/golden/expected/generate-sync-walker-api/sync-walker-golden/internal/cli/promoted_leagues.go
+++ b/testdata/golden/expected/generate-sync-walker-api/sync-walker-golden/internal/cli/promoted_leagues.go
@@ -49,8 +49,12 @@ func newLeaguesPromotedCmd(flags *rootFlags) *cobra.Command {
 			// so output helpers see the inner data, not the wrapper.
 			data = extractResponseData(data)
 
-			// Print provenance to stderr
-			{
+			// Print provenance to stderr for human-facing output only.
+			// Machine-format flags (--json, --csv, --compact, --quiet, --plain,
+			// --select) and piped stdout suppress this line; the JSON envelope
+			// already carries meta.source for those consumers.
+			// SYNC: keep this gate aligned with command_endpoint.go.tmpl.
+			if wantsHumanTable(cmd.OutOrStdout(), flags) {
 				var countItems []json.RawMessage
 				if json.Unmarshal(data, &countItems) != nil {
 					// Single object, not an array
diff --git a/testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/items_enterprise.go b/testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/items_enterprise.go
index e1b61c22..53d47351 100644
--- a/testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/items_enterprise.go
+++ b/testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/items_enterprise.go
@@ -31,8 +31,12 @@ func newItemsEnterpriseCmd(flags *rootFlags) *cobra.Command {
 			if err != nil {
 				return classifyAPIError(err, flags)
 			}
-			// Print provenance to stderr for human-facing output
-			{
+			// Print provenance to stderr for human-facing output only.
+			// Machine-format flags (--json, --csv, --compact, --quiet, --plain,
+			// --select) and piped stdout suppress this line; the JSON envelope
+			// already carries meta.source for those consumers.
+			// SYNC: keep this gate aligned with command_promoted.go.tmpl.
+			if wantsHumanTable(cmd.OutOrStdout(), flags) {
 				var countItems []json.RawMessage
 				_ = json.Unmarshal(data, &countItems)
 				printProvenance(cmd, len(countItems), prov)
diff --git a/testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/items_list.go b/testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/items_list.go
index d6468679..d761e73f 100644
--- a/testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/items_list.go
+++ b/testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/items_list.go
@@ -31,8 +31,12 @@ func newItemsListCmd(flags *rootFlags) *cobra.Command {
 			if err != nil {
 				return classifyAPIError(err, flags)
 			}
-			// Print provenance to stderr for human-facing output
-			{
+			// Print provenance to stderr for human-facing output only.
+			// Machine-format flags (--json, --csv, --compact, --quiet, --plain,
+			// --select) and piped stdout suppress this line; the JSON envelope
+			// already carries meta.source for those consumers.
+			// SYNC: keep this gate aligned with command_promoted.go.tmpl.
+			if wantsHumanTable(cmd.OutOrStdout(), flags) {
 				var countItems []json.RawMessage
 				_ = json.Unmarshal(data, &countItems)
 				printProvenance(cmd, len(countItems), prov)
diff --git a/testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/items_premium.go b/testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/items_premium.go
index 15ca2c6f..43fb4b67 100644
--- a/testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/items_premium.go
+++ b/testdata/golden/expected/generate-tier-routing-api/tier-routing-golden/internal/cli/items_premium.go
@@ -31,8 +31,12 @@ func newItemsPremiumCmd(flags *rootFlags) *cobra.Command {
 			if err != nil {
 				return classifyAPIError(err, flags)
 			}
-			// Print provenance to stderr for human-facing output
-			{
+			// Print provenance to stderr for human-facing output only.
+			// Machine-format flags (--json, --csv, --compact, --quiet, --plain,
+			// --select) and piped stdout suppress this line; the JSON envelope
+			// already carries meta.source for those consumers.
+			// SYNC: keep this gate aligned with command_promoted.go.tmpl.
+			if wantsHumanTable(cmd.OutOrStdout(), flags) {
 				var countItems []json.RawMessage
 				_ = json.Unmarshal(data, &countItems)
 				printProvenance(cmd, len(countItems), prov)

← a8192b52 chore(ci): enable greptile status checks (#1268)  ·  back to Cli Printing Press  ·  fix(cli): route in:query params to URL on PUT/DELETE/POST/PA b8488ee4 →