feat(repos): accurate pagination docs and footer for list repos

The list repos endpoint always paginates (page 1, 15 per page by
default, max 50) with no unpaginated "return all" mode, so correct the
long description and example accordingly. Surface the page context in
table output with a "Showing page X of Y, total Z repos" footer from
the response envelope, mirroring list controls/environments/flows, and
make the no-repos message page-aware. Covered by a server-free unit
test plus an integration assertion.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Kh9pJ2yQbnUPhytgtPSzv

Author: claude

cmd/kosli/listRepos.go

@@ -14,13 +14,14 @@ import (
 
 const listReposShortDesc = `List repos for an org. `
 
-const listReposLongDesc = listReposShortDesc + `By default, all repos for the org are returned.
-Pass --page-limit and/or --page to paginate the results.
+const listReposLongDesc = listReposShortDesc + `The results are always paginated:
+by default the first page is returned with 15 repos per page. Use --page to select
+a page and --page-limit to change the page size (maximum 50).
 The list can be filtered by name with --name (exact match), by VCS provider with
 --provider, and by external repo ID with --repo-id.`
 
 const listReposExample = `
-# list all repos for an org:
+# list repos for an org (first page, 15 per page):
 kosli list repos \
 	--api-token yourAPIToken \
 	--org yourOrgName
@@ -38,9 +39,9 @@ kosli list repos \
 	--org yourOrgName \
 	--output json
 
-# show the second page of repos (25 per page):
+# show the second page of repos (15 per page):
 kosli list repos \
-	--page-limit 25 \
+	--page-limit 15 \
 	--page 2 \
 	--api-token yourAPIToken \
 	--org yourOrgName
@@ -117,29 +118,37 @@ func (o *listReposOptions) run(out io.Writer) error {
 		})
 }
 
-func printReposListAsTable(raw string, out io.Writer, page int) error {
-	var repos []map[string]any
-	var response struct {
-		Repos []map[string]any `json:"repos"`
-	}
+type listReposResponse struct {
+	Repos      []map[string]any `json:"repos"`
+	Page       int              `json:"page"`
+	TotalPages int              `json:"total_pages"`
+	TotalCount int              `json:"total_count"`
+}
 
-	err := json.Unmarshal([]byte(raw), &response)
-	if err != nil {
+func printReposListAsTable(raw string, out io.Writer, page int) error {
+	response := &listReposResponse{}
+	if err := json.Unmarshal([]byte(raw), response); err != nil {
 		return err
 	}
-	repos = response.Repos
 
-	if len(repos) == 0 {
-		logger.Info("No repos were found.")
+	if len(response.Repos) == 0 {
+		msg := "No repos were found"
+		if page != 1 {
+			msg = fmt.Sprintf("%s at page number %d", msg, page)
+		}
+		logger.Info(msg + ".")
 		return nil
 	}
 
 	header := []string{"NAME", "URL", "PROVIDER", "TAGS"}
 	rows := []string{}
-	for _, repo := range repos {
+	for _, repo := range response.Repos {
 		row := fmt.Sprintf("%v\t%v\t%v\t%s", repo["name"], repo["url"], repo["provider"], formatRepoTags(repo["tags"]))
 		rows = append(rows, row)
 	}
+
+	rows = append(rows, fmt.Sprintf("\nShowing page %d of %d, total %d repos", response.Page, response.TotalPages, response.TotalCount))
+
 	tabFormattedPrint(out, header, rows)
 
 	return nil

cmd/kosli/listRepos_test.go

@@ -136,6 +136,11 @@ func (suite *ListReposCommandTestSuite) TestListReposCmd() {
 			cmd:         fmt.Sprintf(`list repos %s`, suite.acmeOrgKosliArguments),
 			goldenRegex: `(?m)^list-repos-suite-org/untagged-repo\s+https://github\.com/list-repos-suite-org/untagged-repo\s+github\s*$`,
 		},
+		{
+			name:        "15-table output shows the pagination footer",
+			cmd:         fmt.Sprintf(`list repos %s`, suite.acmeOrgKosliArguments),
+			goldenRegex: `(?m)^Showing page 1 of \d+, total \d+ repos$`,
+		},
 	}
 
 	runTestCmd(suite.T(), tests)
@@ -151,11 +156,12 @@ func TestPrintReposListAsTableRendersBlankTagsCell(t *testing.T) {
 	raw := `{"repos":[
 		{"name":"o/tagged","url":"https://github.com/o/tagged","provider":"github","tags":{"team":"platform"}},
 		{"name":"o/untagged","url":"https://github.com/o/untagged","provider":"github","tags":{}}
-	]}`
+	],"page":1,"total_pages":3,"total_count":45}`
 	var buf bytes.Buffer
 	require.NoError(t, printReposListAsTable(raw, &buf, 1))
 	out := buf.String()
 	require.Regexp(t, `(?m)^NAME\s+URL\s+PROVIDER\s+TAGS\s*$`, out)
 	require.Regexp(t, `(?m)^o/tagged\s+https://github\.com/o/tagged\s+github\s+team=platform\s*$`, out)
 	require.Regexp(t, `(?m)^o/untagged\s+https://github\.com/o/untagged\s+github\s*$`, out)
+	require.Regexp(t, `(?m)^Showing page 1 of 3, total 45 repos$`, out)
 }