cfl: remove resource-read -o json (BREAKING) [#392] (#396)

* feat!: remove resource-read -o json from cfl

JSON is reserved for round-trip payloads and control-plane envelopes
per cli-common docs/output-and-rendering.md §2. Today's surviving JSON
surface is cfl set-credential --json (control-plane envelope, §1.5.2);
no resource command emits JSON.

The global -o/--output flag now accepts only {table, plain}; -o json,
-o yaml, or any other value errors uniformly at the root prerun
("invalid output format: \"json\" (valid formats: table, plain)"),
before config or keyring work runs. 23 JSON branches across page/,
space/, attachment/, search/ (including create/edit/delete/upload
mutation-success renderers) are deleted along with their tests and
docs/examples. me/ had no production JSON branch; only its fixture is
removed.

BREAKING CHANGE: cfl <resource> -o json now errors. Scripts that piped
"cfl page create -o json | jq -r '.id'" can extract the ID from the
default text output via "awk -F': ' '/^ID:/ {print $2}'"; the bundled
roundtrip-test.sh is updated in this PR to use that pattern.

Closes #392

* test+docs: add local-flag smoke test; inline-mark obsolete JSON rows

- TestRoot_LocalJSONFlag_NotRejectedByOutputGuard pins the invariant
  that the root's closed-set output guard does not interfere with
  child-command local boolean --json flags (set-credential's §1.5.2
  control-plane envelope).
- Inline-mark obsolete JSON rows in integration-tests.md and
  test-plan-writes.md with ~~strikethrough~~ + #392 so the matrix
  itself signals which rows now error rather than relying on the
  top-of-file banner alone.
- Replace the page-create ID-capture row's command with the awk-based
  text-output parser (matches the updated roundtrip-test.sh).

* test: assert attachment empty-result banners now always print

#392 removed the `opts.Output != "json"` skip from attachment/list.go
so the 'No attachments found.' / 'No unused attachments found.'
stderr banners now print unconditionally. Pin that with assertions on
TestRunList_Empty and TestRunList_UnusedFlag_NoUnused.

* test+docs+script: real-root set-credential test; harden awk; fix obsolete row expecteds

Daemon feedback (PR #396):

- Add TestSetCredential_ThroughRealRoot_LocalJSONFlagPreserved which
  dispatches set-credential --json through root.NewCmd() with the
  production PersistentPreRunE chain wired. Prior probe-stub test in
  root_test.go covers the general invariant; this version exercises
  the exact production path so a future regression in
  PersistentPreRunE + set-credential interaction is caught.
- Harden roundtrip-test.sh ID extraction: capture create_output first
  (no more '|| true' masking non-zero exit codes), then run awk with
  gsub-based whitespace trim so 'ID:  12345' / 'ID:\t12345' still
  yield '12345'. Failure paths now include the raw cfl output.
- Update the 'Expected Result' cells of the inline-marked obsolete
  rows in integration-tests.md to say 'Errors: invalid output format'
  instead of stale 'Valid JSON array' / 'Valid JSON object' text.

Author: rianjs

docs/ARTIFACT_CONTRACT.md

@@ -60,7 +60,7 @@ Some commands expose a `--raw` mode for source-faithful content where transforma
 
 ## Output Format
 
-JTK uses text-first output. The `-o json/plain/table` flag has been removed from JTK (CFL retains it). JTK commands render through presenters; `automation export` is the only command that emits JSON directly.
+JTK and CFL both use text-first output. The `-o json` resource surface has been removed from both tools (JTK earlier, then CFL via #392); CFL retains `-o table` and `-o plain` only. Both tools render through presenters; JSON is reserved for control-plane envelopes (`cfl set-credential --json`, `jtk set-credential --json`) and round-trip payloads (`jtk automation export`).
 
 **Text output modes:**
 - Default = focused output for human and agent consumption (defined per-command)

tools/cfl/README.md

@@ -231,10 +231,6 @@ cfl me
 # Show only the account ID (for scripting)
 cfl me --id
 # → 60e09bae7fcd820073089249
-
-# -o json falls through to the one-liner — there is no JSON representation of `cfl me`.
-cfl me -o json
-# → 60e09bae7fcd820073089249 | Rian Stockbower | rian@example.com
 ```
 
 | Flag | Short | Default | Description |
@@ -253,7 +249,7 @@ List Confluence spaces.
 cfl space list
 cfl space list --type global
 cfl space list --type personal
-cfl space list -l 50 -o json
+cfl space list -l 50
 ```
 
 | Flag | Short | Default | Description |
@@ -273,7 +269,6 @@ List pages in a space.
 cfl page list --space DEV
 cfl page list -s DEV -l 50
 cfl page list -s DEV --status archived
-cfl page list -s DEV -o json
 ```
 
 | Flag | Short | Default | Description |
@@ -292,7 +287,6 @@ View a Confluence page. **Content is displayed as markdown by default.**
 cfl page view 12345
 cfl page view 12345 --raw
 cfl page view 12345 --web
-cfl page view 12345 -o json
 cfl page view 12345 --content-only             # Output only content (no headers)
 cfl page view 12345 --show-macros --content-only | cfl page edit 12345 --legacy  # Roundtrip with macros
 ```
@@ -402,7 +396,7 @@ cfl page edit 12345 --file content.md --legacy
 echo "<p>Updated</p>" | cfl page edit 12345 --storage
 
 # Extract, transform, and re-upload storage-format content
-cfl page view 12345 --output json | jq -r '.body.storage.value' | \
+cfl page view 12345 --raw --content-only | \
   sed 's/old/new/g' | cfl page edit 12345 --storage
 ```
 
@@ -497,9 +491,6 @@ cfl search "kubernetes" --space DEV --type page --label infrastructure
 
 # Raw CQL for power users (find pages modified in last 7 days)
 cfl search --cql "type=page AND space=DEV AND lastModified > now('-7d')"
-
-# Output as JSON for scripting
-cfl search "config" -o json
 ```
 
 | Flag | Short | Default | Description |
@@ -581,7 +572,6 @@ List attachments on a page.
 ```bash
 cfl attachment list --page 12345
 cfl attachment list -p 12345 -l 50
-cfl attachment list -p 12345 -o json
 
 # List unused (orphaned) attachments not referenced in page content
 cfl attachment list --page 12345 --unused
@@ -881,10 +871,15 @@ Use `--output` or `-o` to change output format:
 
 ```bash
 cfl space list -o table  # Default: human-readable table
-cfl space list -o json   # JSON for scripting/automation
 cfl space list -o plain  # Tab-separated for piping to other tools
 ```
 
+**Breaking change (#392):** resource `-o json` has been removed. JSON is
+reserved for control-plane envelopes per cli-common
+`docs/output-and-rendering.md` §2. The surviving JSON surface is
+[`cfl set-credential --json`](#cfl-set-credential), which emits a §1.5.2
+write-confirmation envelope for scripted credential rotation.
+
 ---
 
 ## Shell Completion

tools/cfl/chaos-testing.md

@@ -3,6 +3,12 @@
 **Started:** 2026-01-03
 **Focus:** Read-only operations (list, view, download)
 
+> **Historical note (#392):** The `-o json` rows below describe behavior from
+> a session that pre-dates the removal of resource-read JSON. As of #392 the
+> closed set is `{table, plain}`; the `-o json` and `-o yaml` rows below are
+> no longer reproducible — both now error at the root with the same
+> "invalid output format" message.
+
 ---
 
 ## Bugs Found

tools/cfl/integration-tests.md

@@ -2,6 +2,8 @@
 
 This document catalogs the manual integration test suite for `cfl`. These tests verify real-world behavior against a live Confluence instance and catch edge cases that are difficult to cover with unit tests.
 
+> **#392 update:** Rows that exercise `-o json` / `--output json` on resource commands are obsolete — the resource JSON surface has been removed. They now error at the root with `invalid output format: "json" (valid formats: table, plain)`. Skip those rows. The surviving JSON surface is `cfl set-credential --json` (control-plane envelope per cli-common §1.5.2); test that one normally.
+
 ## Auth Methods
 
 cfl supports two authentication methods. The full integration test suite should be run with both:
@@ -61,7 +63,7 @@ All cfl commands should work with both auth methods (no scope limitations for Co
 |-----------|---------|-----------------|
 | List pages in space | `cfl page list --space confluence` | Shows table of pages with ID, title, status, version |
 | List with limit | `cfl page list --space confluence --limit 5` | Shows only 5 pages with "showing first N results" message |
-| JSON output | `cfl page list --space confluence --output json` | Valid JSON array |
+| ~~JSON output~~ (#392 removed) | `cfl page list --space confluence --output json` | Errors: invalid output format |
 | Plain output | `cfl page list --space confluence --output plain` | Tab-separated values |
 | List trashed pages | `cfl page list --space confluence --status trashed` | Shows deleted pages |
 | List archived pages | `cfl page list --space confluence --status archived` | Shows archived pages |
@@ -73,13 +75,13 @@ All cfl commands should work with both auth methods (no scope limitations for Co
 |-----------|---------|-----------------|
 | View page content | `cfl page view <page-id>` | Shows title, ID, version, and markdown content |
 | View raw HTML | `cfl page view <page-id> --raw` | Shows Confluence storage format (XHTML) |
-| JSON output | `cfl page view <page-id> --output json` | Full page object as JSON |
+| ~~JSON output~~ (#392 removed) | `cfl page view <page-id> --output json` | Errors: invalid output format |
 | Non-existent page | `cfl page view 99999999999` | Error: 404 not found |
 | View content only | `cfl page view <id> --content-only` | Markdown only, no Title/ID/Version headers |
 | Content only with raw | `cfl page view <id> --content-only --raw` | XHTML only, no headers |
 | Content only with macros | `cfl page view <id> --content-only --show-macros` | Markdown with [TOC] etc., no headers |
 | Roundtrip macros (content-only) | `cfl page view <id> --show-macros --content-only \| cfl page edit <id> --legacy` | Macros preserved |
-| Content only JSON error | `cfl page view <id> --content-only -o json` | Error: incompatible flags |
+| ~~Content only JSON error~~ (#392 removed; -o json itself errors before --content-only checks) | `cfl page view <id> --content-only -o json` | Errors: invalid output format |
 | Content only web error | `cfl page view <id> --content-only --web` | Error: incompatible flags |
 
 ### page create
@@ -152,7 +154,7 @@ All cfl commands should work with both auth methods (no scope limitations for Co
 |-----------|---------|-----------------|
 | List attachments | `cfl attachment list --page <id>` | Table of attachments with ID, title, type, size |
 | No attachments | List on page with none | "No attachments found" |
-| JSON output | `cfl attachment list --page <id> --output json` | Valid JSON array with full attachment metadata |
+| ~~JSON output~~ (#392 removed) | `cfl attachment list --page <id> --output json` | Errors: invalid output format |
 | List unused attachments | `cfl attachment list --page <id> --unused` | Only attachments not referenced in page content |
 | No unused attachments | `--unused` on page using all attachments | "No unused attachments found" |
 
@@ -196,15 +198,15 @@ All cfl commands should work with both auth methods (no scope limitations for Co
 | Test Case | Command | Expected Result |
 |-----------|---------|-----------------|
 | List all spaces | `cfl space list` | Table of spaces with key, name, type |
-| JSON output | `cfl space list --output json` | Valid JSON array |
+| ~~JSON output~~ (#392 removed) | `cfl space list --output json` | Errors: invalid output format |
 | Limit results | `cfl space list --limit 5` | Shows first 5 spaces |
 
 ### space view
 
 | Test Case | Command | Expected Result |
 |-----------|---------|-----------------|
 | View space by key | `cfl space view confluence` | Key-value pairs: KEY, NAME, ID, TYPE, STATUS, DESCRIPTION |
-| JSON output | `cfl space view confluence -o json` | Valid JSON object with id, key, name, type, status, description |
+| ~~JSON output~~ (#392 removed) | `cfl space view confluence -o json` | Errors: invalid output format |
 | Non-existent space | `cfl space view NONEXISTENT` | Error: Space with key 'NONEXISTENT' not found |
 | View personal space | `cfl space view ~accountid` | Shows personal space details (if accessible) |
 | Alias: get | `cfl space get confluence` | Same output as `space view` |
@@ -214,7 +216,7 @@ All cfl commands should work with both auth methods (no scope limitations for Co
 | Test Case | Command | Expected Result |
 |-----------|---------|-----------------|
 | Create global space | `cfl space create --key INTTEST --name "[Test] Integration" --description "Test space"` | Space created, shows KEY, NAME, URL |
-| Create with JSON output | `cfl space create --key INTTEST2 --name "[Test] Int2" -o json` | Valid JSON with id, key, name, type |
+| ~~Create with JSON output~~ (#392 removed) | `cfl space create --key INTTEST2 --name "[Test] Int2" -o json` | Errors: invalid output format |
 | Missing key flag | `cfl space create --name "Test"` | Error: required flag(s) "key" not set |
 | Missing name flag | `cfl space create --key TST` | Error: required flag(s) "name" not set |
 | Duplicate key | `cfl space create --key INTTEST --name "Duplicate"` (after creating INTTEST) | Error: API rejects duplicate key |
@@ -226,7 +228,7 @@ All cfl commands should work with both auth methods (no scope limitations for Co
 | Update name | `cfl space update INTTEST --name "[Test] Updated Name"` | Shows updated key and name |
 | Update description | `cfl space update INTTEST --description "Updated description"` | Shows updated key and name |
 | Update both | `cfl space update INTTEST --name "[Test] Both" --description "Both updated"` | Both name and description changed |
-| JSON output | `cfl space update INTTEST --name "[Test] JSON" -o json` | Valid JSON with updated fields |
+| ~~JSON output~~ (#392 removed) | `cfl space update INTTEST --name "[Test] JSON" -o json` | Errors: invalid output format |
 | No flags provided | `cfl space update INTTEST` | Error: at least one of --name or --description required |
 | Non-existent space | `cfl space update NONEXISTENT --name "X"` | Error: not found |
 | Verify update | `cfl space view INTTEST` | Shows new name and description |
@@ -238,7 +240,7 @@ All cfl commands should work with both auth methods (no scope limitations for Co
 | Delete with confirmation | `cfl space delete INTTEST` (type "y") | Space deleted after confirmation prompt |
 | Delete cancelled | `cfl space delete INTTEST` (type "n") | "Deletion cancelled" message |
 | Delete with --force | `cfl space delete INTTEST --force` | Space deleted without confirmation |
-| JSON output | `cfl space delete INTTEST --force -o json` | `{"status": "deleted", "space_key": "INTTEST", "name": "..."}` |
+| ~~JSON output~~ (#392 removed) | `cfl space delete INTTEST --force -o json` | Errors: invalid output format |
 | Non-existent space | `cfl space delete NONEXISTENT --force` | Error: not found |
 
 ### Space CRUD End-to-End (sequential)
@@ -250,7 +252,7 @@ All cfl commands should work with both auth methods (no scope limitations for Co
 | 3. Update name | `cfl space update INTTEST --name "[Test] Updated"` | Name updated |
 | 4. Verify update | `cfl space view INTTEST` | Shows new name |
 | 5. Update desc | `cfl space update INTTEST --description "New description"` | Description updated |
-| 6. List includes it | `cfl space list -o json \| jq '.[] \| select(.key == "INTTEST")'` | Space appears in list |
+| 6. List includes it | `cfl space list \| grep INTTEST` | Space appears in list (was `-o json \| jq` pre-#392) |
 | 7. Delete | `cfl space delete INTTEST --force` | "Deleted space INTTEST" |
 | 8. Verify gone | `cfl space view INTTEST` | Error: not found |
 
@@ -269,7 +271,7 @@ All cfl commands should work with both auth methods (no scope limitations for Co
 | Search by label | `cfl search --label test-label` | Content with specified label |
 | Combined filters | `cfl search "deploy" --space DEV --type page` | Filtered results |
 | Raw CQL | `cfl search --cql "type=page AND space=DEV"` | CQL executed directly |
-| JSON output | `cfl search "test" -o json` | Valid JSON with results and _meta |
+| ~~JSON output~~ (#392 removed) | `cfl search "test" -o json` | Errors: invalid output format |
 | Plain output | `cfl search "test" -o plain` | Tab-separated values |
 | Limit results | `cfl search "test" --limit 5` | Max 5 results |
 | No results | `cfl search "xyznonexistent123"` | "No results found" message |
@@ -531,7 +533,7 @@ Copies in the TEST space (originals from INT, CUS, PROD, PLAYBOOK):
 |-----------|---------|-----------------|
 | View ADF page (default) | `cfl page view <adf-id>` | Shows markdown content (not "(No content)") |
 | View ADF page (raw) | `cfl page view <adf-id> --raw` | Shows raw XHTML (or ADF JSON if storage was empty) |
-| View ADF page (JSON) | `cfl page view <adf-id> -o json` | `body.storage` populated (or `body.atlas_doc_format` if storage was empty) |
+| ~~View ADF page (JSON)~~ (#392 removed) | `cfl page view <adf-id> -o json` | Errors: invalid output format |
 | View ADF page (content-only) | `cfl page view <adf-id> --content-only` | Shows content without headers |
 | View legacy page (no regression) | `cfl page view <legacy-id>` | Shows markdown content via storage path |
 
@@ -578,7 +580,7 @@ Copies in the TEST space (originals from INT, CUS, PROD, PLAYBOOK):
 | Format | Flag | Verified With |
 |--------|------|---------------|
 | Table (default) | (none) | Visual inspection |
-| JSON | `--output json` | `jq .` parsing |
+| ~~JSON~~ (#392 removed) | `--output json` | errors at root |
 | Plain | `--output plain` | Tab-separated, scriptable |
 
 ---
@@ -620,7 +622,7 @@ All cfl commands work with both auth methods (no scope restrictions for Confluen
 #### ADF Body Fallback (#150)
 - [ ] View ADF page with empty storage → content displayed via ADF fallback
 - [ ] View ADF page (raw) → shows ADF JSON
-- [ ] View ADF page (JSON output) → body.atlas_doc_format populated
+- [ ] ~~View ADF page (JSON output)~~ (#392 removed)
 - [ ] Edit ADF page (title only) → ADF body preserved
 - [ ] Edit ADF page (new content) → submitted as ADF
 - [ ] View/edit legacy page → no regression (storage path used)
@@ -646,15 +648,15 @@ All cfl commands work with both auth methods (no scope restrictions for Confluen
 - [ ] Full-text search returns results
 - [ ] Space filter works
 - [ ] Type filter works
-- [ ] JSON output is valid
+- [ ] ~~JSON output is valid~~ (#392 removed; -o json errors at root)
 - [ ] Raw CQL works
 
 #### Space CRUD
 - [ ] View space (table output)
-- [ ] View space (JSON output)
+- [ ] ~~View space (JSON output)~~ (#392 removed)
 - [ ] View non-existent space (expect error)
 - [ ] Create space with key, name, description
-- [ ] Create space (JSON output)
+- [ ] ~~Create space (JSON output)~~ (#392 removed)
 - [ ] Create duplicate key (expect error)
 - [ ] Update space name
 - [ ] Update space description
@@ -713,7 +715,7 @@ All cfl commands work with both auth methods (no scope restrictions for Confluen
 #### ADF Body Fallback (#150)
 - [ ] View ADF page with empty storage → content displayed via ADF fallback
 - [ ] View ADF page (raw) → shows ADF JSON
-- [ ] View ADF page (JSON output) → body.atlas_doc_format populated
+- [ ] ~~View ADF page (JSON output)~~ (#392 removed)
 - [ ] Edit ADF page (title only) → ADF body preserved
 - [ ] Edit ADF page (new content) → submitted as ADF
 - [ ] View/edit legacy page → no regression (storage path used)
@@ -739,15 +741,15 @@ All cfl commands work with both auth methods (no scope restrictions for Confluen
 - [ ] Full-text search returns results
 - [ ] Space filter works
 - [ ] Type filter works
-- [ ] JSON output is valid
+- [ ] ~~JSON output is valid~~ (#392 removed; -o json errors at root)
 - [ ] Raw CQL works
 
 #### Space CRUD
 - [ ] View space (table output)
-- [ ] View space (JSON output)
+- [ ] ~~View space (JSON output)~~ (#392 removed)
 - [ ] View non-existent space (expect error)
 - [ ] Create space with key, name, description
-- [ ] Create space (JSON output)
+- [ ] ~~Create space (JSON output)~~ (#392 removed)
 - [ ] Create duplicate key (expect error)
 - [ ] Update space name
 - [ ] Update space description

tools/cfl/internal/cmd/attachment/delete.go

@@ -76,14 +76,6 @@ func runDeleteAttachment(ctx context.Context, attachmentID string, opts *deleteO
 		return fmt.Errorf("deleting attachment: %w", err)
 	}
 
-	if opts.Output == "json" {
-		return v.JSON(map[string]string{
-			"status":        "deleted",
-			"attachment_id": attachmentID,
-			"title":         attachment.Title,
-		})
-	}
-
 	v.Success("Deleted attachment: %s (ID: %s)", attachment.Title, attachmentID)
 
 	return nil

tools/cfl/internal/cmd/attachment/list.go

@@ -97,7 +97,7 @@ func runList(ctx context.Context, opts *listOptions) error {
 		rows = append(rows, []string{att.ID, att.Title, att.MediaType, size})
 	}
 
-	if len(attachments) == 0 && opts.Output != "json" {
+	if len(attachments) == 0 {
 		if opts.unused {
 			_, _ = fmt.Fprintln(opts.Stderr, "No unused attachments found.")
 		} else {
@@ -108,7 +108,7 @@ func runList(ctx context.Context, opts *listOptions) error {
 
 	_ = v.RenderList(headers, rows, result.HasMore())
 
-	if result.HasMore() && opts.Output != "json" {
+	if result.HasMore() {
 		fmt.Fprintf(os.Stderr, "\n(showing first %d results, use --limit to see more)\n", len(attachments))
 	}
 

tools/cfl/internal/cmd/attachment/list_test.go

@@ -69,6 +69,9 @@ func TestRunList_Empty(t *testing.T) {
 
 	err := runList(context.Background(), opts)
 	testutil.RequireNoError(t, err)
+	// The empty-results banner used to be suppressed under -o json; #392
+	// removed that skip, so the banner now always prints to stderr.
+	testutil.Contains(t, rootOpts.Stderr.(*bytes.Buffer).String(), "No attachments found.")
 }
 
 func TestRunList_APIError(t *testing.T) {
@@ -94,33 +97,6 @@ func TestRunList_APIError(t *testing.T) {
 	testutil.Contains(t, err.Error(), "listing attachments")
 }
 
-func TestRunList_JSONOutput(t *testing.T) {
-	t.Parallel()
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		w.WriteHeader(http.StatusOK)
-		_, _ = w.Write([]byte(`{
-			"results": [
-				{"id": "att1", "title": "doc.pdf", "mediaType": "application/pdf", "fileSize": 1024}
-			]
-		}`))
-	}))
-	defer server.Close()
-
-	rootOpts := newListTestRootOptions()
-	rootOpts.Output = "json"
-	client := api.NewClient(server.URL, "test@example.com", "token")
-	rootOpts.SetAPIClient(client)
-
-	opts := &listOptions{
-		Options: rootOpts,
-		pageID:  "12345",
-		limit:   25,
-	}
-
-	err := runList(context.Background(), opts)
-	testutil.RequireNoError(t, err)
-}
-
 func TestRunList_InvalidOutputFormat(t *testing.T) {
 	t.Parallel()
 	// Don't need a server - should fail before API call
@@ -352,4 +328,5 @@ func TestRunList_UnusedFlag_NoUnused(t *testing.T) {
 
 	err := runList(context.Background(), opts)
 	testutil.RequireNoError(t, err)
+	testutil.Contains(t, rootOpts.Stderr.(*bytes.Buffer).String(), "No unused attachments found.")
 }

tools/cfl/internal/cmd/attachment/upload.go

@@ -66,10 +66,6 @@ func runUpload(ctx context.Context, opts *uploadOptions) error {
 
 	v := opts.View()
 
-	if opts.Output == "json" {
-		return v.JSON(attachment)
-	}
-
 	v.Success("Uploaded: %s", filename)
 	v.RenderKeyValue("ID", attachment.ID)
 	v.RenderKeyValue("Title", attachment.Title)