feat(repos): migrate get repo to the dedicated endpoint, surface id and tags (#1004)

* feat(repos): migrate get repo to the dedicated endpoint, surface id and tags

Use `GET /api/v2/repos/{org}/{repo_name}` (added in kosli-dev/server#6156)
instead of filtering the list endpoint client-side. The response is a
single repo object, so the table output now includes the repo's internal
ID (needed for tagging) and its tags, and not-found/ambiguity errors come
from the server. The `--repo-id` flag is filtering by internal ID. In case
of overlapping names `--provider` is the disambiguator.

* fix(repo): improve testing, add flag consistency and loosen unmarshall type handling

* Update cmd/kosli/getRepo.go

Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

* chore(repo): remove duplication, add comments

* test(repo): expand test coverage

---------

Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

Author: mbevc1

cmd/kosli/getRepo.go

@@ -6,6 +6,8 @@ import (
 	"io"
 	"net/http"
 	neturl "net/url"
+	"sort"
+	"strings"
 
 	"github.com/kosli-dev/cli/internal/output"
 	"github.com/kosli-dev/cli/internal/requests"
@@ -15,19 +17,27 @@ import (
 const getRepoShortDesc = `Get a repo for an org.`
 
 const getRepoLongDesc = getRepoShortDesc + `
-The name of the repo is specified as an argument (e.g. "my-org/my-repo").
-Use --provider or --repo-id to narrow down the result when multiple repos
-match the given name.`
+The repo is identified either by its name, specified as an argument
+(e.g. "my-org/my-repo"), or unambiguously by its internal ID via --repo-id.
+The output includes the repo's internal ID, which is the identifier used
+to tag the repo (see: kosli tag).
+Use --provider to disambiguate when multiple repos share the same name
+across VCS providers.`
 
 const getRepoExample = `
 # get a repo
 kosli get repo my-org/my-repo \
 	--api-token yourAPIToken \
 	--org KosliOrgName
 
-# get a repo filtering by provider
+# get a repo whose name exists across multiple VCS providers
 kosli get repo my-org/my-repo \
 	--provider github \
+	--api-token yourAPIToken \
+	--org KosliOrgName
+
+# get a repo by its internal ID
+kosli get repo --repo-id yourRepoID \
 	--api-token yourAPIToken \
 	--org KosliOrgName`
 
@@ -40,16 +50,23 @@ type getRepoOptions struct {
 func newGetRepoCmd(out io.Writer) *cobra.Command {
 	o := new(getRepoOptions)
 	cmd := &cobra.Command{
-		Use:     "repo REPO-NAME",
+		Use:     "repo [REPO-NAME]",
 		Short:   getRepoShortDesc,
 		Long:    getRepoLongDesc,
 		Example: getRepoExample,
-		Args:    cobra.ExactArgs(1),
+		Args:    cobra.MaximumNArgs(1),
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			err := RequireGlobalFlags(global, []string{"Org", "ApiToken"})
 			if err != nil {
 				return ErrorBeforePrintingUsage(cmd, err.Error())
 			}
+			// error unless exactly one of the REPO-NAME arg or --repo-id is set (XOR)
+			if (len(args) == 1) == (o.repoID != "") {
+				return ErrorBeforePrintingUsage(cmd, "exactly one of the REPO-NAME argument or --repo-id must be provided")
+			}
+			if o.provider != "" && o.repoID != "" {
+				return ErrorBeforePrintingUsage(cmd, "--provider cannot be combined with --repo-id")
+			}
 			return nil
 		},
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -58,26 +75,33 @@ func newGetRepoCmd(out io.Writer) *cobra.Command {
 	}
 
 	cmd.Flags().StringVarP(&o.output, "output", "o", "table", outputFlag)
-	cmd.Flags().StringVar(&o.provider, "provider", "", "[optional] The VCS provider to filter repos by (e.g. github, gitlab).")
-	cmd.Flags().StringVar(&o.repoID, "repo-id", "", "[optional] The external repo ID to filter repos by.")
+	cmd.Flags().StringVar(&o.provider, "provider", "", "[optional] The VCS provider of the repo (e.g. github, gitlab). Required when multiple repos share the same name across providers.")
+	cmd.Flags().StringVar(&o.repoID, "repo-id", "", "[optional] The repo's internal ID (as shown in the repo output). Identifies the repo unambiguously; cannot be combined with the REPO-NAME argument.")
 
 	return cmd
 }
 
 func (o *getRepoOptions) run(out io.Writer, args []string) error {
-	params := neturl.Values{}
-	params.Set("name", args[0])
-	if o.provider != "" {
-		params.Set("provider", o.provider)
-	}
-	if o.repoID != "" {
-		params.Set("repo_id", o.repoID)
+	// the endpoint's path is the repo name; when fetching by internal id the
+	// server keys off the ?id= query param and ignores the path, so the id
+	// intentionally doubles as the path segment instead of a placeholder
+	pathName := o.repoID
+	if len(args) == 1 {
+		pathName = args[0]
 	}
-	base, err := neturl.JoinPath(global.Host, "api/v2/repos", global.Org)
+	reqURL, err := neturl.JoinPath(global.Host, "api/v2/repos", global.Org, pathName)
 	if err != nil {
 		return err
 	}
-	reqURL := base + "?" + params.Encode()
+	params := neturl.Values{}
+	if o.repoID != "" {
+		params.Set("id", o.repoID)
+	} else if o.provider != "" {
+		params.Set("provider", o.provider)
+	}
+	if len(params) > 0 {
+		reqURL += "?" + params.Encode()
+	}
 
 	reqParams := &requests.RequestParams{
 		Method: http.MethodGet,
@@ -89,46 +113,88 @@ func (o *getRepoOptions) run(out io.Writer, args []string) error {
 		return err
 	}
 
-	var parsed struct {
-		Repos []map[string]any `json:"repos"`
-	}
-	if err := json.Unmarshal([]byte(response.Body), &parsed); err != nil {
-		return err
-	}
-	if len(parsed.Repos) > 1 {
-		return fmt.Errorf("found %d repos matching %q. Use --provider or --repo-id to narrow down the search", len(parsed.Repos), args[0])
-	}
-
 	return output.FormattedPrint(response.Body, o.output, out, 0,
 		map[string]output.FormatOutputFunc{
 			"table": printRepoAsTable,
 			"json":  output.PrintJson,
 		})
 }
 
-func printRepoAsTable(raw string, out io.Writer, page int) error {
-	var response struct {
-		Repos []map[string]any `json:"repos"`
+// fetchRepoInnerID resolves a repo name to its internal id via the get repo
+// endpoint. An empty provider means no provider disambiguation.
+func fetchRepoInnerID(org, repoName, provider string) (string, error) {
+	reqURL, err := neturl.JoinPath(global.Host, "api/v2/repos", org, repoName)
+	if err != nil {
+		return "", err
+	}
+	if provider != "" {
+		params := neturl.Values{}
+		params.Set("provider", provider)
+		reqURL += "?" + params.Encode()
 	}
 
-	err := json.Unmarshal([]byte(raw), &response)
+	reqParams := &requests.RequestParams{
+		Method: http.MethodGet,
+		URL:    reqURL,
+		Token:  global.ApiToken,
+	}
+	response, err := kosliClient.Do(reqParams)
 	if err != nil {
-		return err
+		return "", err
+	}
+
+	var repo struct {
+		ID string `json:"id"`
+	}
+	if err := json.Unmarshal([]byte(response.Body), &repo); err != nil {
+		return "", err
+	}
+	if repo.ID == "" {
+		return "", fmt.Errorf("could not resolve repo %q to an id", repoName)
 	}
+	return repo.ID, nil
+}
+
+func printRepoAsTable(raw string, out io.Writer, page int) error {
+	var repo map[string]any
 
-	repos := response.Repos
-	if len(repos) == 0 {
-		logger.Info("Repo was not found.")
-		return nil
+	err := json.Unmarshal([]byte(raw), &repo)
+	if err != nil {
+		return err
 	}
 
-	repo := repos[0]
+	tagsOutput := formatRepoTags(repo["tags"])
+	if tagsOutput == "" {
+		tagsOutput = "None"
+	}
 	rows := []string{
-		fmt.Sprintf("Name:\t%s", repo["name"]),
-		fmt.Sprintf("URL:\t%s", repo["url"]),
-		fmt.Sprintf("Provider:\t%s", repo["provider"]),
+		fmt.Sprintf("Name:\t%v", repo["name"]),
+		fmt.Sprintf("ID:\t%v", repo["id"]),
+		fmt.Sprintf("URL:\t%v", repo["url"]),
+		fmt.Sprintf("Provider:\t%v", repo["provider"]),
+		fmt.Sprintf("Tags:\t%s", tagsOutput),
 	}
 
 	tabFormattedPrint(out, []string{}, rows)
 	return nil
 }
+
+// formatRepoTags renders a repo's tags map as sorted "key=value" pairs, or ""
+// when there are no tags. Following the flow/env table conventions, list
+// columns show the empty string while the get repo detail view shows "None".
+func formatRepoTags(rawTags any) string {
+	tags, ok := rawTags.(map[string]any)
+	if !ok || len(tags) == 0 {
+		return ""
+	}
+	keys := make([]string, 0, len(tags))
+	for key := range tags {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	pairs := make([]string, 0, len(tags))
+	for _, key := range keys {
+		pairs = append(pairs, fmt.Sprintf("%s=%v", key, tags[key]))
+	}
+	return strings.Join(pairs, ", ")
+}