Polish docs and contract coverage

Author: robzolkos

README.md

@@ -82,22 +82,29 @@ sudo rpm -i fizzy-cli_VERSION_linux_amd64.rpm
 
 </details>
 
-## Usage
+## Next Steps
+
+Start with a few common commands:
+
+```bash
+fizzy board list
+fizzy card list
+fizzy card show 42
+fizzy search "authentication"
+fizzy comment create --card 42 --body "Looks good!"
+```
+
+Then branch out as needed:
 
 ```bash
-fizzy board list                          # List boards
 fizzy board accesses --board ID           # Show board access settings and users
 fizzy activity list --board ID            # List recent board activity
-fizzy card list                           # List cards on default board
-fizzy card show 42                        # Show card details
-fizzy card create --board ID --title "Fix login bug"  # Create card
-fizzy card close 42                       # Close card
-fizzy search "authentication"             # Search across cards
-fizzy comment create --card 42 --body "Looks good!"   # Add comment
-fizzy webhook deliveries --board ID WEBHOOK_ID         # List webhook deliveries
-fizzy user export-create USER_ID          # Create a user data export
+fizzy webhook deliveries --board ID WEBHOOK_ID
+fizzy user export-create USER_ID
 ```
 
+For the full command surface, run `fizzy commands --json` or read [`skills/fizzy/SKILL.md`](skills/fizzy/SKILL.md).
+
 ### Attachments
 
 Simple mode uses repeatable `--attach` and appends inline attachments to the end of card descriptions or comment bodies:

e2e/cli_tests/output_contract_test.go

@@ -5,6 +5,7 @@ import (
 	"strconv"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/basecamp/fizzy-cli/e2e/harness"
 )
@@ -241,3 +242,74 @@ func TestOutputContractShowCommands(t *testing.T) {
 		})
 	}
 }
+
+func TestOutputContractWebhookDeliveries(t *testing.T) {
+	h := newHarness(t)
+	boardID := createBoard(t, h)
+	cardNum := createCard(t, h, boardID)
+	create := h.Run("webhook", "create", "--board", boardID, "--name", "Output Contract Hook", "--url", "https://example.com/fizzy-cli-output-contract", "--actions", "card_closed")
+	assertOK(t, create)
+	webhookID := create.GetIDFromLocation()
+	if webhookID == "" {
+		webhookID = create.GetDataString("id")
+	}
+	if webhookID == "" {
+		t.Fatal("expected webhook ID in create response")
+	}
+	t.Cleanup(func() { newHarness(t).Run("webhook", "delete", "--board", boardID, webhookID) })
+
+	assertOK(t, h.Run("card", "close", strconv.Itoa(cardNum)))
+
+	var ready bool
+	for attempt := 0; attempt < 15; attempt++ {
+		result := h.Run("webhook", "deliveries", "--board", boardID, webhookID)
+		if result.ExitCode == harness.ExitSuccess && len(result.GetDataArray()) > 0 {
+			ready = true
+			break
+		}
+		time.Sleep(200 * time.Millisecond)
+	}
+	if !ready {
+		t.Fatal("expected webhook deliveries to contain at least one item")
+	}
+
+	baseArgs := []string{"webhook", "deliveries", "--board", boardID, webhookID}
+	for _, f := range listFlagSuite() {
+		f := f
+		t.Run(f.name, func(t *testing.T) {
+			args := append(append([]string(nil), baseArgs...), f.extra...)
+			result := h.Run(args...)
+			if result.ExitCode != harness.ExitSuccess {
+				t.Fatalf("expected exit code 0, got %d\nstdout: %s\nstderr: %s", result.ExitCode, result.Stdout, result.Stderr)
+			}
+			f.check(t, result)
+		})
+	}
+}
+
+func TestOutputContractUserExportShow(t *testing.T) {
+	h := newHarness(t)
+	userID := currentUserID(t, h)
+	create := h.Run("user", "export-create", userID)
+	assertOK(t, create)
+	exportID := create.GetDataString("id")
+	if exportID == "" {
+		exportID = mapValueString(create.GetDataMap(), "id")
+	}
+	if exportID == "" {
+		t.Fatal("expected user export ID in create response")
+	}
+
+	baseArgs := []string{"user", "export-show", userID, exportID}
+	for _, f := range showFlagSuite() {
+		f := f
+		t.Run(f.name, func(t *testing.T) {
+			args := append(append([]string(nil), baseArgs...), f.extra...)
+			result := h.Run(args...)
+			if result.ExitCode != harness.ExitSuccess {
+				t.Fatalf("expected exit code 0, got %d\nstdout: %s\nstderr: %s", result.ExitCode, result.Stdout, result.Stderr)
+			}
+			f.check(t, result)
+		})
+	}
+}

e2e/cli_tests/syntax_contract_test.go

@@ -68,3 +68,37 @@ func TestAccountEntropyRejectsInvalidZeroValue(t *testing.T) {
 	result := h.Run("account", "entropy", "--auto_postpone_period_in_days", "0")
 	assertResult(t, result, harness.ExitUsage)
 }
+
+func TestUserExportCommandsUsePositionalIDs(t *testing.T) {
+	h := newHarness(t)
+	userID := currentUserID(t, h)
+
+	create := h.Run("user", "export-create", userID)
+	assertOK(t, create)
+	exportID := create.GetDataString("id")
+	if exportID == "" {
+		exportID = mapValueString(create.GetDataMap(), "id")
+	}
+	if exportID == "" {
+		t.Fatal("expected export ID from user export-create")
+	}
+
+	assertOK(t, h.Run("user", "export-show", userID, exportID))
+}
+
+func TestWebhookDeliveriesUsesBoardFlagAndWebhookID(t *testing.T) {
+	h := newHarness(t)
+	boardID := createBoard(t, h)
+	cardNum := createCard(t, h, boardID)
+	create := h.Run("webhook", "create", "--board", boardID, "--name", "Syntax Contract Hook", "--url", "https://example.com/fizzy-cli-syntax", "--actions", "card_closed")
+	assertOK(t, create)
+	webhookID := create.GetIDFromLocation()
+	if webhookID == "" {
+		webhookID = create.GetDataString("id")
+	}
+	if webhookID == "" {
+		t.Fatal("expected webhook ID from webhook create")
+	}
+	assertOK(t, h.Run("card", "close", strconv.Itoa(cardNum)))
+	assertOK(t, h.Run("webhook", "deliveries", "--board", boardID, webhookID))
+}