PRD: Agent-First Gitee CLI for gitee.com

[hex2dec]

PRD: Agent-First Gitee CLI for gitee.com

Problem Statement

There is no focused CLI for gitee.com that AI agents and automation scripts can call reliably for core collaboration workflows. Today, common tasks such as creating pull requests, creating issues, reading issue history, reviewing prior comments, and posting follow-up comments usually require a mix of manual website actions, raw Git commands, or hand-written HTTP requests.

That creates several problems:

• Agents cannot complete high-frequency Gitee workflows through a stable, scriptable, non-interactive interface.
• The Gitee web UI is optimized for human interaction, not unattended automation.
• Calling the Gitee OpenAPI directly forces every caller to reimplement authentication, repository context resolution, pagination, output shaping, and error handling.
• Teams that already use GitHub gh as a mental model do not have an equivalent Gitee-focused tool for shared human and agent workflows.

The goal is to build a Gitee CLI inspired by GitHub gh, but with a different priority order: v1 must be optimized first for AI agents and automation scripts, and only second for interactive human usage. The initial scope should cover the highest-value workflows: authentication, repository context inspection, pull request creation and inspection, issue creation and inspection, comment history retrieval, and posting replies to issues or pull requests.

This product is not intended to be a thin wrapper around the entire Gitee OpenAPI. It should provide a small, opinionated, high-value command surface with stable behavior and strong testability.

Solution

Build an agent-first CLI for gitee.com that follows the general workflow style of GitHub gh, while explicitly preferring deterministic, non-interactive automation over prompt-driven UX.

The v1 solution should:

• Provide a small, high-frequency command set centered on auth, repo, pr, and issue.
• Default to human-readable output, while requiring all core commands to support stable --json output for machine consumption.
• Prefer explicit inputs from flags, stdin, files, or repository context; missing prerequisites should fail fast rather than trigger hidden prompts.
• Integrate deeply with the local Git repository to infer owner/repo, current branch, upstream branch, and default branch when safe.
• Use a minimum-cost authentication strategy: Personal Access Token plus environment variables and a local config file.
• Wrap high-frequency Gitee APIs instead of exposing a raw API passthrough command.
• Use Rust as the v1 implementation language, with a conventional Rust CLI stack, to match the desired long-term direction even though Go would be more familiar.

Recommended v1 command surface:

• gitee auth login
• gitee auth status
• gitee auth logout
• gitee repo view
• gitee repo clone
• gitee pr create
• gitee pr view
• gitee pr list
• gitee pr status
• gitee pr checkout
• gitee pr comment
• gitee issue create
• gitee issue view
• gitee issue list
• gitee issue comment

Core agent-facing behavior:

• Every core command supports --json with a stable field contract.
• Successful output goes to stdout; errors go to stderr.
• Exit codes are stable and distinguish authentication failures, argument errors, missing resources, local Git precondition failures, and API/network failures.
• The CLI never silently summarizes or truncates important remote state.
• Comment retrieval is explicit; callers must choose whether to fetch comments, how many to fetch, and whether to paginate.
• All write operations accept content from flags, files, or stdin so they can be driven by an agent without prompts.

User Stories

1. As an AI coding agent, I want to authenticate with a Gitee personal access token, so that I can call Gitee APIs without browser-based OAuth.
2. As an AI coding agent, I want the CLI to read credentials from environment variables or a local config file, so that I can run unattended in scripts and sandboxed environments.
3. As an AI coding agent, I want auth status to verify the current login and identity, so that I can fail fast before starting a workflow.
4. As an AI coding agent, I want every core command to support --json, so that I can parse results without scraping human-readable text.
5. As an AI coding agent, I want stable exit codes, so that I can branch my workflow on auth failures, invalid arguments, missing resources, and local Git problems.
6. As an AI coding agent, I want the CLI to infer the current repository from local Git remotes, so that I do not need to repeat owner/repo on every command.
7. As an AI coding agent, I want to override repository inference with an explicit --repo, so that I can target a repository deterministically outside a local checkout.
8. As an AI coding agent, I want repo view to return canonical repository metadata and the default branch, so that downstream PR and issue operations have a trusted context.
9. As an AI coding agent, I want repo clone to clone by repository slug and explicit transport preference, so that I can bootstrap a working copy predictably.
10. As an AI coding agent, I want pr create to create a pull request from the current branch with explicit title and body inputs, so that I can publish a code change without visiting the website.
11. As an AI coding agent, I want pr create to derive a sensible default base branch from repository metadata, so that the common case needs fewer flags.
12. As an AI coding agent, I want pr create to fail clearly when the local branch is not pushed or cannot be resolved safely, so that I do not create a PR against the wrong head branch.
13. As an AI coding agent, I want pr create to accept body content from a file or stdin, so that I can generate and submit long-form PR descriptions programmatically.
14. As an AI coding agent, I want pr view to fetch a single pull request with structured metadata, so that I can inspect status, author, branches, URLs, and merge state.
15. As an AI coding agent, I want pr list to filter by state, author, assignee, base, or head, so that I can find the exact PR I need to reason about.
16. As an AI coding agent, I want pr status to summarize pull requests related to the current user or current branch, so that I can understand outstanding work quickly.
17. As an AI coding agent, I want pr checkout to fetch and check out the head branch of an existing pull request, so that I can inspect or continue work locally.
18. As an AI coding agent, I want pr comment to post a general pull request comment from a string, file, or stdin, so that I can publish review conclusions back to the PR thread.
19. As an AI coding agent, I want issue create to create a new issue with explicit title and body inputs, so that I can report bugs, tasks, or follow-up work without visiting the website.
20. As an AI coding agent, I want issue create to accept body content from a string, file, or stdin, so that I can generate detailed issue descriptions programmatically.
21. As an AI coding agent, I want issue create to work with either explicit --repo input or inferred local repository context, so that I can open issues deterministically in scripts and local checkouts.
22. As an AI coding agent, I want issue list to filter by state and keyword, so that I can discover relevant bug reports before making changes.
23. As an AI coding agent, I want issue view to fetch the issue body and, when requested, its full comment history, so that I can understand prior discussion before attempting a fix.
24. As an AI coding agent, I want issue comment to reply to an issue thread programmatically, so that I can report findings or remediation steps after making a change.
25. As a human developer, I want readable default terminal output, so that I can use the same tool manually without always requesting JSON.
26. As a human developer, I want explicit, actionable error messages, so that I can correct missing authentication, repository context, or branch state quickly.
27. As a maintainer, I want a small and stable v1 command surface, so that documentation, compatibility guarantees, and tests remain manageable.
28. As a maintainer, I want a deep repository-context module, so that Git parsing logic is centralized and independently testable rather than duplicated across commands.
29. As a maintainer, I want a deep Gitee API client module, so that token injection, pagination, retries, and error normalization are implemented once and reused everywhere.
30. As a maintainer, I want command handlers to stay thin, so that the product can evolve without repeated CLI glue rewrites.
31. As a future contributor, I want core domain and transport contracts to be implementation-stable, so that internals can evolve without changing user-visible behavior.

Implementation Decisions

• v1 is intentionally agent-first rather than a full reimplementation of GitHub gh interaction patterns.
• v1 supports only gitee.com and does not target self-hosted or enterprise-private Gitee deployments.
• v1 does not include a raw API passthrough command.
• Rust is the primary implementation language for v1.
• The CLI layer should use a conventional Rust command framework so that subcommands, help output, argument validation, and shell completion remain predictable.
• Rust is chosen deliberately even though Go would be faster to deliver initially, because the desired direction is to invest in the Rust implementation rather than treat it as a later rewrite.
• The command layer should remain thin and focus on argument parsing, output rendering, and exit-code mapping.
• A dedicated configuration and authentication module should own token source precedence, config loading, secure file writes, and login-state verification.
• Token precedence should be explicit: login writes to local config, while runtime reads prefer environment variables first and config file second.
• A repository-context module should infer owner/repo, current branch, upstream branch, and default branch from local Git state when safe.
• A Gitee API client module should centralize HTTP transport, token injection, pagination, retries where appropriate, and normalized error handling.
• An output module should centralize text rendering and stable --json serialization so commands do not format output independently.
• JSON field stability is a product contract; changes to that contract should be treated as compatibility events.
• The CLI should define stable exit codes for at least these classes: success, generic failure, invalid arguments, authentication failure, not found, and local Git precondition failure.
• repo view should return core repository metadata including canonical identifier, default branch, repository URL, clone URLs, and fork status.
• repo clone should clone by owner/repo and support an explicit transport choice such as SSH or HTTPS.
• pr create should cover the highest-frequency case: creating a pull request from the current branch or an explicit --head into an explicit or inferred --base.
• pr create should not automatically create forks or attempt to support complex multi-remote collaboration topologies in v1.
• pr create should support --title, --body, --body-file, stdin input, and explicit --repo.
• pr create should fail rather than guess when the local branch has not been pushed, the remote mapping is ambiguous, or repository context cannot be resolved safely.
• pr view and pr list should wrap the official pull request APIs and expose only the most useful filters in v1.
• pr status should summarize the pull request state around the current user and current repository context rather than attempt to replace advanced search.
• pr checkout should integrate with local Git, fetch the relevant remote refs, create or switch a local branch, and report the resulting checkout state.
• pr comment should support general pull request comments in v1, which is sufficient for the primary review-reply use case.
• Line-level diff comments are supported by the upstream API but are out of scope for the initial release in order to keep the command model simple.
• issue create should be part of the v1 command surface so issue authoring is covered alongside issue reading and commenting.
• issue create should support --title, --body, --body-file, stdin input, and explicit --repo.
• issue create should reuse repository-context resolution so it works both inside a local checkout and against an explicitly targeted repository.
• issue create should fail rather than guess when required title input is missing, repository context is ambiguous, or repository resolution cannot be performed safely.
• issue list and issue view should prioritize reading issue history and discussion context.
• issue view should support explicit comment inclusion, but should not silently fetch unbounded comment history by default.
• issue comment should support content from direct flags, files, or stdin.
• All read commands should expose explicit pagination or count controls to avoid hidden truncation and unpredictable network usage.
• All write commands should remain non-interactive by default and fail fast when required input is missing.
• Configuration persistence should use a local config file with strict file permissions; system keychain integration is out of scope for v1.
• The architecture should keep domain behavior decoupled from transport details so the implementation stays testable and maintainable.

Recommended deep modules:

• Configuration and authentication: token discovery, config persistence, login-state validation.
• Repository context: Git remote parsing, branch inference, repository identity resolution.
• Gitee API client: transport, token injection, pagination, and normalized remote errors.
• Pull request workflows: create, view, list, status, checkout, and comment behavior.
• Issue workflows: create, view, list, and comment behavior.
• Output rendering: stable text and JSON contracts.

Testing Decisions

• A good test validates external behavior rather than internal implementation details.
• Tests should primarily cover visible outcomes: exit codes, stdout and stderr behavior, HTTP request intent, Git precondition handling, and --json output shape.
• Tests should not become brittle when internal function boundaries, command wiring, or transport helpers are refactored.
• The configuration and authentication module must be tested.
• The repository-context module must be tested.
• The Gitee API client module must be tested.
• pr create parameter resolution and failure paths must be tested.
• issue create parameter resolution and failure paths must be tested.
• Issue and pull request comment retrieval plus structured output must be tested.
• pr checkout should be tested against controlled Git fixtures or fake remotes so fetch and checkout behavior is validated through observable results.
• --json output should be covered by contract tests or golden tests that lock down field names and key semantics.
• The API client should use HTTP mock servers to cover success cases, authentication failures, not found responses, pagination, and multiple remote error shapes.
• Repository-context tests should use temporary Git repositories to cover HTTPS remotes, SSH remotes, missing upstreams, detached HEAD state, and default-branch lookup failures.
• Write commands should test title and body input via direct flags, body files, and stdin.
• The repository is currently empty, so there is no prior art in the codebase for tests.
• A fresh testing baseline should be established with table-driven unit tests, HTTP mock integration tests, Git fixture tests, and JSON golden tests.

Out of Scope

• Support for self-hosted or enterprise-private Gitee deployments.
• Raw OpenAPI passthrough commands.
• Browser OAuth, device flow, or keychain-based authentication.
• Full feature parity with every GitHub gh command and flag.
• Automatic fork creation and full cross-fork pull request workflows.
• Line-level diff review comments and complex review approval workflows.
• Labels, milestones, releases, actions, notifications, and other non-core command groups.
• Prompt-heavy interactive forms, wizards, or terminal UIs.
• Maintaining a separate Go implementation in parallel with the Rust implementation.

Further Notes

• The current Gitee Swagger documentation exposes the API surface needed for this v1 scope, including pull requests, issues, issue comments, pull request comments, forks, and authenticated user lookups.
• The current Gitee OpenAPI widely uses access_token in query or form parameters, which makes a PAT plus config-file approach viable for v1.
• If delivery pressure increases, the project should still preserve behavior-first contracts such as JSON output shape, exit codes, and command semantics rather than weakening them for short-term speed.
• Future expansions could include JSON Lines output, templated rendering, richer review-comment support, or more advanced pagination helpers, but those should not be forced into the initial release.