teai/internal/cli/dailyops_commands.go

// dailyops_commands.go — 日常操作命令的 CLI 接線（#8）：issues、pulls、
// labels、milestones、releases、repos、organizations、api（tea 對等指令）。
//
// 規則：
//   - 寫入類命令（create／close／comment／merge…）一律要求 --yes，
//     未帶 --yes 時不產生任何遠端變更（exit 2，用法錯誤）。
//   - `teai pulls` 相容 #6 的工作流用法（無子命令＝工作流清單 --mine/--reviewer）；
//     有子命令（list/create/view/merge/comment）時走日常操作。
//   - 輸出走 internal/gitea 的 Printer（--output json|table）。
package cli

import (
	"context"
	"encoding/json"
	"flag"
	"fmt"
	"os"
	"os/exec"
	"path/filepath"
	"strconv"
	"strings"

	"gitea.alterminal.com/alterminal/teai/internal/dailyops"
	"gitea.alterminal.com/alterminal/teai/internal/gitea"
)

func init() {
	register := func(c *command) { commands[c.name] = c }
	register(&command{name: "issues", usage: "issues 管理（list/view/create/close/comment；list 支援 --labels 過濾）", run: runIssues})
	register(&command{name: "pulls", usage: "PR 管理（list/view/create/merge/approve/close/checkout/comment；無子命令＝工作流清單）", run: runPullsDaily})
	register(&command{name: "comment", usage: "對 issue 或 PR 留言（--repo owner/repo <number> --body …）", run: runCommentDirect})
	register(&command{name: "labels", usage: "標籤管理（list/create）", run: runLabels})
	register(&command{name: "milestones", usage: "里程碑（跨倉庫總覽；list/create 管理單倉庫）", run: runMilestones})
	register(&command{name: "releases", usage: "發佈清單（list）", run: runReleases})
	register(&command{name: "repos", usage: "倉庫查詢（list）", run: runRepos})
	register(&command{name: "organizations", usage: "組織管理（list/create/delete；tea organizations 對等）", run: runOrganizations})
	register(&command{name: "api", usage: "任意 API 呼叫（--method/--data；寫入動詞需 --yes）", run: runAPIDirect})
}

// requireYes 檢查寫入閘門：未帶 --yes 回 ErrUsage（exit 2），不觸發任何請求。
func requireYes(yes bool, what string) error {
	if !yes {
		return &ErrUsage{Msg: what + " 是寫入操作，需 --yes 明確確認（未確認，未產生任何遠端變更）"}
	}
	return nil
}

// splitRepoFlag 把 --repo owner/repo 拆成兩段；空值回 ("", "", nil)。
func splitRepoFlag(v string) (string, string, error) {
	if v == "" {
		return "", "", nil
	}
	parts := strings.SplitN(v, "/", 2)
	if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
		return "", "", &ErrUsage{Msg: errNoRepoFlag.Error()}
	}
	return parts[0], parts[1], nil
}

// newOpsClient 依全域選項建立 dailyops 用戶端。
func newOpsClient(env *Env) (*dailyops.Ops, error) {
	token, _, err := gitea.ResolveToken(gitea.AuthOptions{
		FlagToken:  env.Globals.Token,
		SiteURL:    env.Globals.URL,
		ConfigPath: env.Globals.ConfigPath,
	})
	if err != nil {
		return nil, err
	}
	client, err := gitea.New(env.Globals.URL, token, env.Globals.Timeout)
	if err != nil {
		return nil, err
	}
	return &dailyops.Ops{Client: client}, nil
}

// parseNumber 把位置參數解析為 issue／PR 編號。
func parseNumber(s string) (int64, error) {
	n, err := strconv.ParseInt(s, 10, 64)
	if err != nil || n <= 0 {
		return 0, &ErrUsage{Msg: fmt.Sprintf("無效的編號 %q", s)}
	}
	return n, nil
}

// joinOrEmpty 把清單型欄位格式化為逗號分隔（table 用）。
func joinOrEmpty(v any) string {
	switch x := v.(type) {
	case string:
		return x
	case []string:
		return strings.Join(x, ",")
	default:
		return fmt.Sprint(x)
	}
}

// issueRowsFields 是 issues 清單的欄位定義（與值順序對應）。
func issueListFields() []gitea.Field {
	return []gitea.Field{
		{Name: "number"}, {Name: "title"}, {Name: "state"},
		{Name: "author"}, {Name: "assignees", ValueFmt: joinOrEmpty}, {Name: "updated_at"},
	}
}

// ---- issues ----

// runIssues：teai issues [list|view|create|close|comment] …
func runIssues(env *Env, args []string) error {
	if len(args) == 0 {
		return &ErrUsage{Msg: "issues 需要子命令：list | view | create | close | comment"}
	}
	sub, rest := args[0], args[1:]
	switch sub {
	case "list":
		return runIssuesList(env, rest)
	case "view":
		return runIssuesView(env, rest)
	case "create":
		return runIssuesCreate(env, rest)
	case "close":
		return runIssuesClose(env, rest)
	case "comment":
		return runComment(env, rest, false)
	default:
		return &ErrUsage{Msg: fmt.Sprintf("issues 未知子命令 %q（可用：list | view | create | close | comment）", sub)}
	}
}

// runIssuesList：teai issues list --repo owner/repo [--state open|closed|all] [--labels a,b]
func runIssuesList(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai issues list", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	state := fs.String("state", "open", "狀態：open|closed|all")
	labels := fs.String("labels", "", "標籤過濾（逗號分隔，可選；多標籤為 AND）")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	if fs.NArg() != 0 {
		return &ErrUsage{Msg: "issues list 不接受位置參數"}
	}
	owner, name, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: "issues list 需要 --repo owner/repo"}
	}
	var labelList []string
	if strings.TrimSpace(*labels) != "" {
		for _, l := range strings.Split(*labels, ",") {
			if l = strings.TrimSpace(l); l != "" {
				labelList = append(labelList, l)
			}
		}
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	issues, err := ops.ListIssues(context.Background(), owner, name, *state, labelList)
	if err != nil {
		return err
	}
	p := printer(env)
	rows := make([]gitea.Values, 0, len(issues))
	for i := range issues {
		it := &issues[i]
		rows = append(rows, gitea.Values{
			it.Number, it.Title, it.State, it.Author(),
			it.AssigneeNames(), it.UpdatedAt,
		})
	}
	return p.PrintList(issueListFields(), rows)
}

// runIssuesView：teai issues view --repo owner/repo <number> [--comments]
func runIssuesView(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai issues view", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	withComments := fs.Bool("comments", false, "連留言一起輸出")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	owner, name, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: "issues view 需要 --repo owner/repo"}
	}
	if fs.NArg() != 1 {
		return &ErrUsage{Msg: "issues view 需要恰好一個編號"}
	}
	num, err := parseNumber(fs.Arg(0))
	if err != nil {
		return err
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	it, err := ops.GetIssue(context.Background(), owner, name, num)
	if err != nil {
		return err
	}
	p := printer(env)
	fields := []gitea.Field{
		{Name: "number"}, {Name: "title"}, {Name: "state"},
		{Name: "author"}, {Name: "assignees", ValueFmt: joinOrEmpty},
		{Name: "labels", ValueFmt: joinOrEmpty}, {Name: "body"},
		{Name: "url"}, {Name: "updated_at"},
	}
	row := gitea.Values{
		it.Number, it.Title, it.State, it.Author(),
		it.AssigneeNames(), it.LabelNames(), it.Body,
		it.HTMLURL, it.UpdatedAt,
	}
	if err := p.PrintOne(fields, row); err != nil {
		return err
	}
	if !*withComments {
		return nil
	}
	return printComments(env, ops, owner, name, num)
}

// printComments 輸出 issue／PR 的留言清單（view --comments 共用）。
func printComments(env *Env, ops *dailyops.Ops, owner, repo string, number int64) error {
	comments, err := ops.ListComments(context.Background(), owner, repo, number)
	if err != nil {
		return err
	}
	p := printer(env)
	rows := make([]gitea.Values, 0, len(comments))
	for i := range comments {
		c := &comments[i]
		rows = append(rows, gitea.Values{c.Author(), c.CreatedAt, c.Body})
	}
	return p.PrintList([]gitea.Field{
		{Name: "author"}, {Name: "created_at"}, {Name: "body"},
	}, rows)
}

// runIssuesCreate：teai issues create --repo owner/repo --title … [--body …] [--assignees a,b] --yes
func runIssuesCreate(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai issues create", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	title := fs.String("title", "", "標題（必填）")
	body := fs.String("body", "", "內文")
	assignees := fs.String("assignees", "", "assignees（逗號分隔，可選）")
	yes := fs.Bool("yes", false, "確認寫入")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	owner, name, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: "issues create 需要 --repo owner/repo"}
	}
	if strings.TrimSpace(*title) == "" {
		return &ErrUsage{Msg: "issues create 需要 --title"}
	}
	if err := requireYes(*yes, "issues create"); err != nil {
		return err
	}
	var assigneeList []string
	if strings.TrimSpace(*assignees) != "" {
		for _, a := range strings.Split(*assignees, ",") {
			if a = strings.TrimSpace(a); a != "" {
				assigneeList = append(assigneeList, a)
			}
		}
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	issue, err := ops.CreateIssue(context.Background(), owner, name, *title, *body, assigneeList)
	if err != nil {
		return err
	}
	return printer(env).PrintOne([]gitea.Field{
		{Name: "number"}, {Name: "title"}, {Name: "url"},
	}, gitea.Values{issue.Number, issue.Title, issue.HTMLURL})
}

// runIssuesClose：teai issues close --repo owner/repo <number> --yes
func runIssuesClose(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai issues close", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	yes := fs.Bool("yes", false, "確認寫入")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	owner, name, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: "issues close 需要 --repo owner/repo"}
	}
	if fs.NArg() != 1 {
		return &ErrUsage{Msg: "issues close 需要恰好一個編號"}
	}
	num, err := parseNumber(fs.Arg(0))
	if err != nil {
		return err
	}
	if err := requireYes(*yes, "issues close"); err != nil {
		return err
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	issue, err := ops.SetIssueState(context.Background(), owner, name, num, "closed")
	if err != nil {
		return err
	}
	return printer(env).PrintOne([]gitea.Field{
		{Name: "number"}, {Name: "title"}, {Name: "state"}, {Name: "url"},
	}, gitea.Values{issue.Number, issue.Title, issue.State, issue.HTMLURL})
}

// runComment：teai issues comment / teai pulls comment 共用。
// 相容 tea 用法：留言可作為位置參數（tea comment --repo a/b <index> "內容"），
// 亦可 teai 慣用的 --body；兩者同時給時位置參數優先（與 tea 行為一致）。
func runComment(env *Env, args []string, isPR bool) error {
	name := "issues comment"
	if isPR {
		name = "pulls comment"
	}
	fs := flag.NewFlagSet("teai "+name, flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	body := fs.String("body", "", "留言內容（可改用位置參數）")
	yes := fs.Bool("yes", false, "確認寫入")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	owner, rname, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: name + " 需要 --repo owner/repo"}
	}
	// 位置參數：<number> [body…]；尾端多餘引數以空格接成一則留言（tea 相容）。
	if fs.NArg() < 1 {
		return &ErrUsage{Msg: name + " 需要恰好一個編號（可選加留言位置參數）"}
	}
	num, err := parseNumber(fs.Arg(0))
	if err != nil {
		return err
	}
	text := strings.TrimSpace(*body)
	if fs.NArg() > 1 {
		text = strings.TrimSpace(strings.Join(fs.Args()[1:], " "))
	}
	if text == "" {
		return &ErrUsage{Msg: name + " 需要留言內容（--body 或位置參數）"}
	}
	if err := requireYes(*yes, name); err != nil {
		return err
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	comment, err := ops.AddComment(context.Background(), owner, rname, num, text)
	if err != nil {
		return err
	}
	return printer(env).PrintOne([]gitea.Field{
		{Name: "author"}, {Name: "created_at"}, {Name: "body"},
	}, gitea.Values{comment.Author(), comment.CreatedAt, comment.Body})
}

// ---- pulls ----

// runPullsDaily：teai pulls [list|view|create|merge|comment] …；
// 無子命令時沿用 #6 的工作流清單（teai pulls [--mine|--reviewer] [--repo]）。
func runPullsDaily(env *Env, args []string) error {
	if len(args) == 0 || strings.HasPrefix(args[0], "-") {
		// 相容 #6：teai pulls / teai pulls --mine …（工作流清單）。
		return runPulls(env, args)
	}
	sub, rest := args[0], args[1:]
	switch sub {
	case "list":
		return runPullsList(env, rest)
	case "view":
		return runPullsView(env, rest)
	case "create":
		return runPullsCreate(env, rest)
	case "merge":
		return runPullsMerge(env, rest)
	case "approve":
		return runPullsApprove(env, rest)
	case "close":
		return runPullsClose(env, rest)
	case "checkout":
		return runPullsCheckout(env, rest)
	case "comment":
		return runComment(env, rest, true)
	default:
		return &ErrUsage{Msg: fmt.Sprintf("pulls 未知子命令 %q（可用：list | view | create | merge | approve | close | checkout | comment；或無子命令＝工作流清單）", sub)}
	}
}

// runCommentDirect：teai comment --repo owner/repo <number> <body> [--yes]。
// tea 的通用留言指令：issue 與 PR 共用同一端點（Gitea 以 number 定位，
// issues/<n>/comments 對兩者皆有效），故不需 --type 旗標。
func runCommentDirect(env *Env, args []string) error {
	return runComment(env, args, false)
}

// runPullsList：teai pulls list --repo owner/repo [--state open|closed|all]
func runPullsList(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai pulls list", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	state := fs.String("state", "open", "狀態：open|closed|all")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	owner, name, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: "pulls list 需要 --repo owner/repo"}
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	pulls, err := ops.ListPulls(context.Background(), owner, name, *state)
	if err != nil {
		return err
	}
	p := printer(env)
	rows := make([]gitea.Values, 0, len(pulls))
	for i := range pulls {
		pr := &pulls[i]
		rows = append(rows, gitea.Values{
			pr.Number, pr.Title, pr.State, pr.Author(),
			pr.HeadRef(), pr.BaseRef(), pr.UpdatedAt,
		})
	}
	return p.PrintList([]gitea.Field{
		{Name: "number"}, {Name: "title"}, {Name: "state"},
		{Name: "author"}, {Name: "head"}, {Name: "base"}, {Name: "updated_at"},
	}, rows)
}

// runPullsView：teai pulls view --repo owner/repo <number> [--comments]
func runPullsView(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai pulls view", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	withComments := fs.Bool("comments", false, "連留言一起輸出")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	owner, name, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: "pulls view 需要 --repo owner/repo"}
	}
	if fs.NArg() != 1 {
		return &ErrUsage{Msg: "pulls view 需要恰好一個編號"}
	}
	num, err := parseNumber(fs.Arg(0))
	if err != nil {
		return err
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	pr, err := ops.GetPull(context.Background(), owner, name, num)
	if err != nil {
		return err
	}
	p := printer(env)
	fields := []gitea.Field{
		{Name: "number"}, {Name: "title"}, {Name: "state"},
		{Name: "author"}, {Name: "head"}, {Name: "base"}, {Name: "body"},
		{Name: "url"}, {Name: "updated_at"},
	}
	row := gitea.Values{
		pr.Number, pr.Title, pr.State, pr.Author(),
		pr.HeadRef(), pr.BaseRef(), pr.Body, pr.HTMLURL, pr.UpdatedAt,
	}
	if err := p.PrintOne(fields, row); err != nil {
		return err
	}
	if !*withComments {
		return nil
	}
	return printComments(env, ops, owner, name, num)
}

// runPullsCreate：teai pulls create --repo owner/repo --head <branch> --base <branch> --title … [--body …] --yes
func runPullsCreate(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai pulls create", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	head := fs.String("head", "", "來源分支（必填）")
	base := fs.String("base", "main", "目標分支（預設 main）")
	title := fs.String("title", "", "標題（必填）")
	body := fs.String("body", "", "說明")
	yes := fs.Bool("yes", false, "確認寫入")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	owner, name, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: "pulls create 需要 --repo owner/repo"}
	}
	if *head == "" || *title == "" {
		return &ErrUsage{Msg: "pulls create 需要 --head 與 --title"}
	}
	if err := requireYes(*yes, "pulls create"); err != nil {
		return err
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	pr, err := ops.CreatePull(context.Background(), owner, name, *title, *body, *head, *base)
	if err != nil {
		return err
	}
	return printer(env).PrintOne([]gitea.Field{
		{Name: "number"}, {Name: "title"}, {Name: "url"},
	}, gitea.Values{pr.Number, pr.Title, pr.HTMLURL})
}

// runPullsMerge：teai pulls merge --repo owner/repo <number> [--style merge|rebase|squash] --yes
func runPullsMerge(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai pulls merge", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	style := fs.String("style", "merge", "合併方式：merge|rebase|rebase-merge|squash")
	yes := fs.Bool("yes", false, "確認寫入")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	owner, name, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: "pulls merge 需要 --repo owner/repo"}
	}
	if fs.NArg() != 1 {
		return &ErrUsage{Msg: "pulls merge 需要恰好一個編號"}
	}
	num, err := parseNumber(fs.Arg(0))
	if err != nil {
		return err
	}
	switch *style {
	case "merge", "rebase", "rebase-merge", "squash":
	default:
		return &ErrUsage{Msg: "pulls merge 的 --style 需為 merge|rebase|rebase-merge|squash"}
	}
	if err := requireYes(*yes, "pulls merge"); err != nil {
		return err
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	if err := ops.MergePull(context.Background(), owner, name, num, *style); err != nil {
		return err
	}
	return printer(env).PrintOne([]gitea.Field{
		{Name: "number"}, {Name: "state"},
	}, gitea.Values{num, "merged"})
}

// runPullsApprove：teai pulls approve --repo owner/repo [--body …] --yes <number>。
// tea 相容：意見也可作為位置參數（teai pulls approve --repo a/b <n> "驗證通過。"）。
func runPullsApprove(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai pulls approve", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	body := fs.String("body", "", "審核意見（可改用位置參數）")
	yes := fs.Bool("yes", false, "確認寫入")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	owner, name, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: "pulls approve 需要 --repo owner/repo"}
	}
	if fs.NArg() < 1 {
		return &ErrUsage{Msg: "pulls approve 需要恰好一個編號（可選加意見位置參數）"}
	}
	num, err := parseNumber(fs.Arg(0))
	if err != nil {
		return err
	}
	text := strings.TrimSpace(*body)
	if fs.NArg() > 1 {
		text = strings.TrimSpace(strings.Join(fs.Args()[1:], " "))
	}
	if err := requireYes(*yes, "pulls approve"); err != nil {
		return err
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	review, err := ops.ApprovePull(context.Background(), owner, name, num, text)
	if err != nil {
		return err
	}
	return printer(env).PrintOne([]gitea.Field{
		{Name: "number"}, {Name: "state"}, {Name: "author"}, {Name: "body"},
	}, gitea.Values{review.Number, review.State, review.Author(), review.Body})
}

// runPullsClose：teai pulls close --repo owner/repo --yes <number>。
// 關閉不合併；工作流約定 merge 才是正途（AGENTS.md 6.2），本指令提供語義對等。
func runPullsClose(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai pulls close", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	yes := fs.Bool("yes", false, "確認寫入")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	owner, name, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: "pulls close 需要 --repo owner/repo"}
	}
	if fs.NArg() != 1 {
		return &ErrUsage{Msg: "pulls close 需要恰好一個編號"}
	}
	num, err := parseNumber(fs.Arg(0))
	if err != nil {
		return err
	}
	if err := requireYes(*yes, "pulls close"); err != nil {
		return err
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	pr, err := ops.ClosePull(context.Background(), owner, name, num)
	if err != nil {
		return err
	}
	return printer(env).PrintOne([]gitea.Field{
		{Name: "number"}, {Name: "title"}, {Name: "state"}, {Name: "url"},
	}, gitea.Values{pr.Number, pr.Title, pr.State, pr.HTMLURL})
}

// runPullsCheckout：teai pulls checkout --repo owner/repo <number> [--dir <path>]。
// 唯讀輔助指令：取得 PR head 資訊，在本機以 git 取得工作副本——
// 同倉庫分支 → git fetch --quiet origin <ref> && git checkout -B <ref> FETCH_HEAD
// （在 --dir 指定的既有 git 工作樹內執行；預設當前目錄）；
// 跨倉庫 head → git clone --branch <ref> <clone_url> <dir>（--dir 必填，目錄不得已存在）。
// teai 不碰認證：clone 走 https 公開網址，私有倉庫時請自備 git 認證（credential helper）。
func runPullsCheckout(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai pulls checkout", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	dir := fs.String("dir", "", "工作樹目錄（預設當前目錄；跨倉庫 head 時必填且不得已存在）")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	owner, name, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: "pulls checkout 需要 --repo owner/repo"}
	}
	if fs.NArg() != 1 {
		return &ErrUsage{Msg: "pulls checkout 需要恰好一個編號"}
	}
	num, err := parseNumber(fs.Arg(0))
	if err != nil {
		return err
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	info, err := ops.PullHeadInfo(context.Background(), owner, name, num)
	if err != nil {
		return err
	}
	if info.Ref == "" {
		return fmt.Errorf("PR #%d 缺少 head 分支資訊", num)
	}
	workDir := *dir
	if workDir == "" {
		workDir = "."
	}
	// git 指令一律固定參數（不經 shell、不插入使用者字串），分支名僅作為
	// git 自身剖析的引數傳入；錯誤訊息往 env.Err，成功輸出到 env.Out。
	// 注意：git clone 的目標目錄是位置參數，cmd.Dir 不可指向不存在目錄，
	// 故 clone 一律在當前目錄執行（--dir 以絕對路徑傳入）。
	runGit := func(dir string, args ...string) error {
		cmd := exec.Command("git", args...)
		cmd.Dir = dir
		cmd.Stdout = env.Out
		cmd.Stderr = env.Err
		return cmd.Run()
	}
	if info.Repo == "" {
		// 同倉庫：fetch 指定分支並建立／更新本地分支。
		if err := runGit(workDir, "fetch", "--quiet", "origin", "--", info.Ref); err != nil {
			return fmt.Errorf("git fetch origin %s 失敗（在 %s）：%w", info.Ref, workDir, err)
		}
		if err := runGit(workDir, "checkout", "-q", "-B", info.Ref, "FETCH_HEAD"); err != nil {
			return fmt.Errorf("git checkout -B %s 失敗：%w", info.Ref, err)
		}
		return printer(env).PrintOne([]gitea.Field{
			{Name: "number"}, {Name: "branch"}, {Name: "workdir"},
		}, gitea.Values{num, info.Ref, workDir})
	}
	// 跨倉庫 head：clone 到 --dir（不得已存在）。
	if *dir == "" {
		return &ErrUsage{Msg: "pulls checkout：跨倉庫 head（" + info.Repo + "）需要 --dir <目錄>"}
	}
	if st, err := os.Stat(*dir); err == nil && st.IsDir() {
		return &ErrUsage{Msg: "pulls checkout：--dir 已存在（跨倉庫 head 需要新目錄）：" + *dir}
	}
	if info.CloneURL == "" {
		return fmt.Errorf("PR #%d 的 head 倉庫 %s 未提供 clone 網址", num, info.Repo)
	}
	abs, err := filepath.Abs(*dir)
	if err != nil {
		return &ErrUsage{Msg: "pulls checkout：無效的 --dir：" + err.Error()}
	}
	if err := runGit(".", "clone", "--quiet", "--branch", info.Ref, "--", info.CloneURL, abs); err != nil {
		return fmt.Errorf("git clone %s 失敗：%w", info.CloneURL, err)
	}
	return printer(env).PrintOne([]gitea.Field{
		{Name: "number"}, {Name: "branch"}, {Name: "repo"}, {Name: "workdir"},
	}, gitea.Values{num, info.Ref, info.Repo, *dir})
}

// ---- labels ----

// runLabels：teai labels list --repo owner/repo｜teai labels create … --yes
func runLabels(env *Env, args []string) error {
	if len(args) == 0 {
		return &ErrUsage{Msg: "labels 需要子命令：list | create"}
	}
	sub, rest := args[0], args[1:]
	switch sub {
	case "list":
		return runLabelsList(env, rest)
	case "create":
		return runLabelsCreate(env, rest)
	default:
		return &ErrUsage{Msg: fmt.Sprintf("labels 未知子命令 %q（可用：list | create）", sub)}
	}
}

// runLabelsList：teai labels list --repo owner/repo
func runLabelsList(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai labels list", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	owner, name, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: "labels list 需要 --repo owner/repo"}
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	labels, err := ops.ListLabels(context.Background(), owner, name)
	if err != nil {
		return err
	}
	rows := make([]gitea.Values, 0, len(labels))
	for _, l := range labels {
		rows = append(rows, gitea.Values{l.Name, l.Color, l.Description})
	}
	return printer(env).PrintList([]gitea.Field{
		{Name: "name"}, {Name: "color"}, {Name: "description"},
	}, rows)
}

// runLabelsCreate：teai labels create --repo owner/repo --name … [--color …] [--description …] --yes
func runLabelsCreate(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai labels create", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	labelName := fs.String("name", "", "標籤名（必填）")
	color := fs.String("color", "#ffffff", "顏色（#RRGGBB，預設 #ffffff）")
	desc := fs.String("description", "", "說明")
	yes := fs.Bool("yes", false, "確認寫入")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	owner, name, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: "labels create 需要 --repo owner/repo"}
	}
	if *labelName == "" {
		return &ErrUsage{Msg: "labels create 需要 --name"}
	}
	if err := requireYes(*yes, "labels create"); err != nil {
		return err
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	label, err := ops.CreateLabel(context.Background(), owner, name, *labelName, *color, *desc)
	if err != nil {
		return err
	}
	return printer(env).PrintOne([]gitea.Field{
		{Name: "name"}, {Name: "color"}, {Name: "description"},
	}, gitea.Values{label.Name, label.Color, label.Description})
}

// ---- milestones ----

// runMilestones：teai milestones [list|create] …；不帶子命令時輸出
// 跨倉庫里程碑總覽（#31，對應 gitea.py milestones）。帶 --repo 直接
// 跟在 milestones 之後時維持現行單倉庫 list 語義。
func runMilestones(env *Env, args []string) error {
	if len(args) == 0 {
		return runMilestonesOverview(env)
	}
	sub, rest := args[0], args[1:]
	switch sub {
	case "list":
		return runMilestonesList(env, rest)
	case "create":
		return runMilestonesCreate(env, rest)
	default:
		if !strings.HasPrefix(sub, "-") {
			return &ErrUsage{Msg: fmt.Sprintf("milestones 未知子命令 %q（可用：list | create；或不帶參數輸出跨倉庫總覽）", sub)}
		}
		// milestones 之後直接跟旗標（非子命令）：帶 --repo → 整串轉發，
		// 維持現行單倉庫 list 語義（--state 等旗標一併生效）；否則為
		// 跨倉庫總覽（總覽不接受任何命令旗標，空 FlagSet 讓未知旗標
		// 報用法錯誤）。
		hasRepo := false
		for _, a := range args {
			if a == "--repo" || strings.HasPrefix(a, "--repo=") {
				hasRepo = true
				break
			}
		}
		if hasRepo {
			return runMilestonesList(env, args)
		}
		fs := flag.NewFlagSet("teai milestones", flag.ContinueOnError)
		fs.SetOutput(env.Err)
		if err := parseFlags(fs, args); err != nil {
			return err
		}
		if fs.NArg() != 0 {
			return &ErrUsage{Msg: "milestones 不接受位置參數（子命令：list | create）"}
		}
		return runMilestonesOverview(env)
	}
}

// runMilestonesList：teai milestones list --repo owner/repo [--state open|closed|all]
func runMilestonesList(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai milestones list", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	state := fs.String("state", "open", "狀態：open|closed|all")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	owner, name, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: "milestones list 需要 --repo owner/repo"}
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	ms, err := ops.ListMilestones(context.Background(), owner, name, *state)
	if err != nil {
		return err
	}
	rows := make([]gitea.Values, 0, len(ms))
	for _, m := range ms {
		rows = append(rows, gitea.Values{m.Title, m.State, m.Description, m.DueOn})
	}
	return printer(env).PrintList([]gitea.Field{
		{Name: "title"}, {Name: "state"}, {Name: "description"}, {Name: "due_on"},
	}, rows)
}

// runMilestonesCreate：teai milestones create --repo owner/repo --title … [--description …] [--due …] --yes
func runMilestonesCreate(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai milestones create", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	title := fs.String("title", "", "標題（必填）")
	desc := fs.String("description", "", "說明")
	due := fs.String("due", "", "截止日（RFC3339，可選）")
	yes := fs.Bool("yes", false, "確認寫入")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	owner, name, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: "milestones create 需要 --repo owner/repo"}
	}
	if *title == "" {
		return &ErrUsage{Msg: "milestones create 需要 --title"}
	}
	if err := requireYes(*yes, "milestones create"); err != nil {
		return err
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	m, err := ops.CreateMilestone(context.Background(), owner, name, *title, *desc, *due)
	if err != nil {
		return err
	}
	return printer(env).PrintOne([]gitea.Field{
		{Name: "id"}, {Name: "title"}, {Name: "state"}, {Name: "due_on"},
	}, gitea.Values{m.ID, m.Title, m.State, m.DueOn})
}

// ---- releases / repos / api ----

// runReleases：teai releases list --repo owner/repo
func runReleases(env *Env, args []string) error {
	if len(args) == 0 || args[0] != "list" {
		return &ErrUsage{Msg: "releases 目前支援子命令：list"}
	}
	fs := flag.NewFlagSet("teai releases list", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
	if err := parseFlags(fs, args[1:]); err != nil {
		return err
	}
	owner, name, err := splitRepoFlag(*repo)
	if err != nil {
		return err
	}
	if owner == "" {
		return &ErrUsage{Msg: "releases list 需要 --repo owner/repo"}
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	releases, err := ops.ListReleases(context.Background(), owner, name)
	if err != nil {
		return err
	}
	rows := make([]gitea.Values, 0, len(releases))
	for _, r := range releases {
		rows = append(rows, gitea.Values{r.TagName, r.Name, r.Draft, r.Prerelease, r.PublishedAt})
	}
	return printer(env).PrintList([]gitea.Field{
		{Name: "tag_name"}, {Name: "name"}, {Name: "draft"}, {Name: "prerelease"}, {Name: "published_at"},
	}, rows)
}

// runRepos：teai repos list [--org <org>]（未指定 --org 則列自己可存的倉庫）
func runRepos(env *Env, args []string) error {
	if len(args) == 0 || args[0] != "list" {
		return &ErrUsage{Msg: "repos 目前支援子命令：list"}
	}
	fs := flag.NewFlagSet("teai repos list", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	org := fs.String("org", "", "組織（未指定則列自己可存取的倉庫）")
	if err := parseFlags(fs, args[1:]); err != nil {
		return err
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	var repos []dailyops.Repo
	if *org != "" {
		repos, err = ops.ListOrgRepos(context.Background(), *org)
	} else {
		repos, err = ops.ListMyRepos(context.Background())
	}
	if err != nil {
		return err
	}
	rows := make([]gitea.Values, 0, len(repos))
	for _, r := range repos {
		rows = append(rows, gitea.Values{r.FullName, r.Private, r.Empty, r.UpdatedAt, r.HTMLURL})
	}
	return printer(env).PrintList([]gitea.Field{
		{Name: "full_name"}, {Name: "private"}, {Name: "empty"}, {Name: "updated_at"}, {Name: "url"},
	}, rows)
}

// runAPIDirect：teai api <path> [--method GET|POST|…] [--data <json>] [--yes]
func runAPIDirect(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai api", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	method := fs.String("method", "GET", "HTTP 動詞（GET 預設；非 GET 需 --yes）")
	data := fs.String("data", "", "請求 body（JSON 字串，可選）")
	yes := fs.Bool("yes", false, "確認寫入")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	if fs.NArg() != 1 {
		return &ErrUsage{Msg: "api 需要恰好一個 path（相對 api/v1，以 / 開頭）"}
	}
	path := fs.Arg(0)
	// path 內含查詢字串（如 /repos/x?state=closed）時剝離到 rawQuery，
	// 不可併進 URL path（會 404）。
	rawQuery := ""
	if q := strings.IndexByte(path, '?'); q >= 0 {
		rawQuery = path[q+1:]
		path = path[:q]
	}
	if path == "" || path[0] != '/' {
		return &ErrUsage{Msg: "api path 必須以 / 開頭（相對 api/v1）"}
	}
	upper := strings.ToUpper(strings.TrimSpace(*method))
	if upper == "" {
		upper = "GET"
	}
	switch upper {
	case "GET", "HEAD", "OPTIONS":
	default:
		if err := requireYes(*yes, "api "+upper); err != nil {
			return err
		}
	}
	var payload []byte
	if strings.TrimSpace(*data) != "" {
		if !json.Valid([]byte(*data)) {
			return &ErrUsage{Msg: "--data 必須是合法 JSON"}
		}
		payload = []byte(*data)
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	resp, err := ops.CallAPIDirect(context.Background(), upper, path, rawQuery, payload)
	if err != nil {
		return err
	}
	// 原樣輸出（teai api 是逃生口，不做欄位挑選）。
	_, err = env.Out.Write(resp)
	if len(resp) > 0 && resp[len(resp)-1] != '\n' {
		fmt.Fprintln(env.Out)
	}
	return err
}

// ---- organizations（#45，tea organizations 對等）----

// orgListFields 是 organizations 清單的欄位定義。
func orgListFields() []gitea.Field {
	return []gitea.Field{
		{Name: "name"}, {Name: "full_name"}, {Name: "website"},
		{Name: "location"}, {Name: "description"}, {Name: "visibility"},
	}
}

// runOrganizations：teai organizations [list|create|delete] …。
// tea 對等：organizations list 列出自己可存取的組織；create／delete 是
// 寫入操作，比照慣例要求 --yes。
func runOrganizations(env *Env, args []string) error {
	if len(args) == 0 {
		return &ErrUsage{Msg: "organizations 需要子命令：list | create | delete"}
	}
	sub, rest := args[0], args[1:]
	switch sub {
	case "list":
		return runOrganizationsList(env, rest)
	case "create":
		return runOrganizationsCreate(env, rest)
	case "delete":
		return runOrganizationsDelete(env, rest)
	default:
		return &ErrUsage{Msg: fmt.Sprintf("organizations 未知子命令 %q（可用：list | create | delete）", sub)}
	}
}

// runOrganizationsList：teai organizations list。
// GET /user/orgs（與 teai orgs 工作流命令同一端點，但輸出完整欄位）。
func runOrganizationsList(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai organizations list", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	if fs.NArg() != 0 {
		return &ErrUsage{Msg: "organizations list 不接受位置參數"}
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	orgs, err := ops.ListMyOrganizations(context.Background())
	if err != nil {
		return err
	}
	p := printer(env)
	rows := make([]gitea.Values, 0, len(orgs))
	for i := range orgs {
		org := &orgs[i]
		rows = append(rows, gitea.Values{
			org.Account(), org.FullName, org.Website,
			org.Location, org.Description, org.Visibility,
		})
	}
	return p.PrintList(orgListFields(), rows)
}

// runOrganizationsCreate：teai organizations create --name … [--full-name …]
// [--description …] [--website …] [--location …] [--visibility public|limited|private] --yes。
// tea 以位置參數給組織名；teai 慣例用 --name（語義等價，命名與其他 create 一致）。
func runOrganizationsCreate(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai organizations create", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	name := fs.String("name", "", "組織帳號名（必填，同 tea 的位置參數）")
	fullName := fs.String("full-name", "", "顯示名稱")
	desc := fs.String("description", "", "說明")
	website := fs.String("website", "", "網站")
	location := fs.String("location", "", "所在地")
	visibility := fs.String("visibility", "", "可見度：public|limited|private（預設服務端決定）")
	yes := fs.Bool("yes", false, "確認寫入")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	if strings.TrimSpace(*name) == "" {
		return &ErrUsage{Msg: "organizations create 需要 --name"}
	}
	switch *visibility {
	case "", "public", "limited", "private":
	default:
		return &ErrUsage{Msg: "organizations create 的 --visibility 需為 public|limited|private"}
	}
	if err := requireYes(*yes, "organizations create"); err != nil {
		return err
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	org, err := ops.CreateOrganization(context.Background(), *name, *fullName, *desc, *website, *location, *visibility)
	if err != nil {
		return err
	}
	return printer(env).PrintOne(orgListFields(), gitea.Values{
		org.Account(), org.FullName, org.Website,
		org.Location, org.Description, org.Visibility,
	})
}

// runOrganizationsDelete：teai organizations delete <name> --yes。
// tea 相容：組織名作為位置參數。
func runOrganizationsDelete(env *Env, args []string) error {
	fs := flag.NewFlagSet("teai organizations delete", flag.ContinueOnError)
	fs.SetOutput(env.Err)
	yes := fs.Bool("yes", false, "確認寫入")
	if err := parseFlags(fs, args); err != nil {
		return err
	}
	if fs.NArg() != 1 {
		return &ErrUsage{Msg: "organizations delete 需要恰好一個組織名"}
	}
	orgName := strings.TrimSpace(fs.Arg(0))
	if orgName == "" {
		return &ErrUsage{Msg: "organizations delete 需要組織名"}
	}
	if err := requireYes(*yes, "organizations delete"); err != nil {
		return err
	}
	ops, err := newOpsClient(env)
	if err != nil {
		return err
	}
	if err := ops.DeleteOrganization(context.Background(), orgName); err != nil {
		return err
	}
	return printer(env).PrintOne([]gitea.Field{{Name: "name"}, {Name: "state"}}, gitea.Values{orgName, "deleted"})
}