gitlink-cli/docs/pr-draft-issue-batch.md

feat(issue): add batch maintenance shortcuts

Summary

This PR adds focused Issue batch maintenance shortcuts:

• issue +batch-list
• issue +batch-close
• issue +batch-label

The commands help maintainers inspect and act on groups of Issues with safe defaults and structured output.

Motivation

Maintainers often need to find stale or labeled Issues, preview a batch action, and then execute it carefully. Existing single-Issue commands are useful, but they do not provide a guarded batch maintenance workflow.

Changes

• Add issue +batch-list for read-only candidate listing.
• Upgrade issue +batch-close to use filter-based selection, default dry-run, and explicit --yes execution.
• Add issue +batch-label for dry-run label maintenance planning.
• Add batch DTOs and table/json rendering inside the issue shortcut package.
• Add long help text with examples and safety notes.
• Add tests and documentation for the batch workflow.

Safety

• issue +batch-list is read-only.
• issue +batch-close and issue +batch-label default to dry-run.
• --yes is required before any remote mutation is attempted.
• Batch close requires --older-than-days.
• Batch close rejects --older-than-days values lower than 7.
• --limit is capped at 100.
• Per-item failures are recorded in errors and do not hide partial failures.
• issue +batch-label --yes does not fake success when a label write endpoint is unavailable.

Tests

gofmt -w shortcuts/issue/*.go shortcuts/common/*.go
go test ./shortcuts/issue
go test ./...

Coverage includes filtering, dry-run behavior, JSON/table rendering, httptest API list responses, and per-item write failure reporting.

Documentation

• README.md
• README.zh-CN.md
• docs/issue-batch-design.md
• docs/issue-batch-test-report.md

Known Limitations

• Label mutation is intentionally not executed until a stable GitLink add-label endpoint is confirmed.
• The current candidate fetch uses one page with the requested limit.