@fatecannotbealtered-/jira-cli 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.4] - 2026-05-31
+
+### Fixed
+
+- **`issue get` description** — `description` is now included in the default flat output and selectable via `--fields description` (previously only reachable through `--raw`). Bulk outputs (`issue list`, `search`, `filter run`, `sprint issues`) stay lean and omit `description` by default to preserve token efficiency. Handles both Data Center (plain string) and Cloud/v3 (ADF) descriptions.
+
+## [1.0.3] - 2026-05-26
+
+### Fixed
+
+- **Semantic exit codes** — validation, auth, and config failures now return non-zero exit codes (via `SilentErr`); `doctor` and `login` work correctly in CI scripts.
+- **Audit logging on failed writes** — write commands are logged even when the operation fails.
+- **`FilterSprintFields`** — camelCase sprint fields (`startDate`, `endDate`) filter correctly with `--fields`.
+- **Config file corruption detection** — invalid JSON in `~/.jira-cli/config.json` returns a clear parse error.
+- **`issue edit --description`** — plain text is converted to ADF, matching `issue create`.
+- **Agile API pagination** — sprint/board list, backlog, epics, and epic issues fetch all pages instead of truncating at ~50 items.
+- **`ListWorklogs` pagination** — worklogs beyond the first page are included.
+- **`search --order-by`** — skips appending `ORDER BY` when JQL already contains one.
+- **`issue delete --dry-run`** — no longer prompts for confirmation before previewing.
+- **`issue bulk-transition`** — `skipped` and `failed` counts are reported separately in JSON output.
+- **E2E script** — sprint move (K7) runs before issue cleanup; `JIRA_E2E_CLEANUP=0` is honored.
+
+### Added
+
+- **`cmd.Run()` / `Main()`** — testable CLI entry point with correct exit code propagation.
+- **Comprehensive unit tests** — 100% statement coverage across all packages; httptest-based command integration tests.
+- **`internal/api/agile_page.go`** — shared pagination helper for Jira Agile API endpoints.
+
+### Changed
+
+- **Minimum Go version** — `go.mod` updated to Go 1.24 (uses `testing.T.Chdir` in tests).
+
+### Documentation
+
+- Clarify `search --fields` (Jira fetch) vs `issue get/list --fields` (output trimming).
+- Document `issue delete --dry-run` skips confirmation; remove misleading `sprint close --force` wording.
+- Add `epic list` / `epic issues` to README; document `filter run --raw/--fields`.
+- Document stdout (success JSON) vs stderr (error JSON); `doctor` exit code and `authValid` checks.
+- Note npm install requires `curl`; add `install-skill` and `issue list` vs `search` JSON/jq examples.
+
 ## [1.0.2] - 2026-05-14
 
 ### Fixed
@@ -73,7 +113,8 @@ Initial release of jira-cli for Jira Data Center.
 - SKILL.md with JSON output schemas, error codes, exit codes, and complete flag reference.
 - GitHub PR template for contributors.
 
-[Unreleased]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.2...HEAD
+[Unreleased]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.3...HEAD
+[1.0.3]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/fatecannotbealtered/jira-cli/releases/tag/v1.0.0

package/README.md

@@ -36,21 +36,22 @@ This project is shared for **personal learning, research, and everyday productiv
 
 ### Quick start
 
-Recommended flow: install the CLI from npm, then install the AI Agent Skill with `npx skills add`.
+Copy the block below to your agent (or run it yourself):
 
 ```bash
-# Install CLI
+# Please install jira-cli and use it for all Jira DC operations going forward (always pass --json).
+# Install CLI (requires curl on PATH — used to download the binary)
 npm install -g @fatecannotbealtered-/jira-cli
 
-# Install CLI Skill
+# Install CLI Skill (required) — copies into your agent-supported skills directory
 npx skills add fatecannotbealtered/jira-cli -y -g
 
 # Login and verify
 jira-cli login
-jira-cli doctor
+jira-cli doctor --json
 ```
 
-The CLI package provides the `jira-cli` binary; the Skill package teaches compatible AI coding assistants how to use it safely. If you are an AI Agent helping a user set this up, run the same steps and ask the user to complete any interactive browser or terminal prompts.
+Optional: `jira-cli install-skill` copies the bundled skill to `~/.openclaw/skills` for OpenClaw-compatible agents.
 
 ### Alternative: Go install
 
@@ -91,7 +92,7 @@ Environment variables take precedence over the config file. This is the recommen
 ```bash
 export JIRA_HOST=https://jira.company.com
 export JIRA_TOKEN=<your-personal-access-token>
-jira-cli doctor --json
+jira-cli doctor --json   # verify authValid is true
 ```
 
 ### Generating a PAT
@@ -115,7 +116,8 @@ jira-cli issue create --project PROJ --summary "Fix login bug" --type Bug
 jira-cli issue create --project PROJ --summary "Sized story" --field "Story Points=5"
 jira-cli issue edit PROJ-123 --priority High --assignee me
 jira-cli issue edit PROJ-123 --field "Story Points=8" --field "Team=Backend"
-jira-cli issue delete PROJ-123 --force          # --force skips confirmation
+jira-cli issue delete PROJ-123 --force          # --force skips confirmation prompt
+jira-cli issue delete PROJ-123 --dry-run --json   # preview delete (no confirmation prompt)
 
 # Clone
 jira-cli issue clone PROJ-123
@@ -165,7 +167,16 @@ jira-cli sprint list --board 42
 jira-cli sprint active --board 42
 jira-cli sprint create --board 42 --name "Sprint 5" --start-date 2024-02-01 --end-date 2024-02-14
 jira-cli sprint move --sprint 10 --issues PROJ-123,PROJ-124
-jira-cli sprint close --sprint 10 --force
+jira-cli sprint close --sprint 10
+jira-cli sprint close --sprint 10 --dry-run       # preview without closing
+```
+
+### Epic Management
+
+```bash
+jira-cli epic list --board 42
+jira-cli epic list --board 42 --done             # completed epics only
+jira-cli epic issues PROJ-1 --board 42
 ```
 
 ### Board & Backlog
@@ -186,31 +197,52 @@ jira-cli user search --query "john"
 jira-cli user me
 jira-cli filter list
 jira-cli filter run <filterId>
+jira-cli filter run <filterId> --json --fields key,summary,status
+jira-cli filter run <filterId> --json --raw
 ```
 
 ## JSON Output
 
-All commands support `--json` for machine-readable output. By default, issue and sprint data is returned in a **flat, token-efficient format** (ideal for AI Agents):
+All commands support `--json` for machine-readable output. **Success JSON goes to stdout; error JSON goes to stderr** — pipe or capture stdout for data, check `$?` and stderr for failures.
+
+By default, issue and sprint data is returned in a **flat, token-efficient format** (ideal for AI Agents):
 
 ```bash
 # Flat JSON (default) — minimal fields, low token cost
 jira-cli issue get PROJ-123 --json
 jira-cli search "project = PROJ" --json | jq '.issues[].key'
 
-# Select only the fields you need
+# issue list returns a bare array; search wraps issues in pagination metadata
+# filter run with --fields also returns a bare trimmed array
+jira-cli issue list --project PROJ --json | jq '.[].key'
+jira-cli search "project = PROJ" --json | jq '.issues[].key'
+jira-cli filter run 12345 --json --fields key,summary | jq '.[].key'
+
+# Trim flat JSON output (issue get / issue list / sprint / filter run)
 jira-cli issue get PROJ-123 --json --fields key,summary,status,assignee
 
+# search --fields controls which fields Jira fetches (API request), not output trimming
+jira-cli search "project = PROJ" --fields summary,status,customfield_10001 --json
+
 # Raw Jira API response (full nested structure)
 jira-cli issue get PROJ-123 --json --raw
 
-# Clean output for scripts (suppress all non-JSON noise)
+# Clean output for scripts (suppress all non-JSON noise on stdout)
 jira-cli issue get PROJ-123 --json --quiet
 
 # Preview destructive operations without executing
 jira-cli issue delete PROJ-123 --dry-run --json
 ```
 
-Error responses include machine-readable error codes and actionable hints:
+### Verify connectivity (`doctor`)
+
+When using `--json`, check the `authValid` field (exit code 3 on auth/config failure):
+
+```bash
+jira-cli doctor --json | jq '.authValid'   # must be true
+```
+
+Error responses (stderr) include machine-readable error codes and actionable hints:
 
 ```json
 {
@@ -260,13 +292,15 @@ Credentials stored at `~/.jira-cli/config.json` (permissions: 0600):
 
 | Flag | Commands | Description |
 |---|---|---|
-| `--raw` | `issue get`, `issue list`, `search`, `sprint list`, `sprint issues`, `sprint active` | Return raw Jira API response instead of flat format |
-| `--fields` | `issue get`, `issue list`, `sprint list`, `sprint issues` | Output only specified fields (e.g. `--fields key,summary,status`) |
+| `--raw` | `issue get`, `issue list`, `search`, `filter run`, `sprint list`, `sprint issues`, `sprint active` | Return raw Jira API response instead of flat format |
+| `--fields` | `issue get`, `issue list`, `sprint list`, `sprint issues`, `filter run` | **Output trimming** — include only listed fields in flat JSON (e.g. `--fields key,summary,status`) |
+| `--fields` | `search` only | **Jira fetch fields** — comma-separated fields to request from the API (e.g. `--fields summary,status,customfield_10001`); does not trim flat output |
 
 ## Troubleshooting
 
 | Issue | Solution |
 |---|---|
+| npm install fails / curl not found | Ensure `curl` is on PATH (required by npm postinstall to download the binary) |
 | Config not found | Run `jira-cli login` or set `JIRA_HOST` and `JIRA_TOKEN` env vars |
 | Authentication failed | Regenerate PAT in your Jira DC profile settings |
 | Permission denied | Check your PAT scope and project permissions |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fatecannotbealtered-/jira-cli",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Full-featured Jira Data Center CLI for humans and AI Agents — manage issues, sprints, boards, epics, projects, users, and filters from your terminal",
   "keywords": [
     "jira",

package/skills/jira-cli/SKILL.md

@@ -8,9 +8,20 @@ metadata: {"openclaw":{"emoji":"🎯","requires":{"bins":["jira-cli"]}}}
 
 Jira Data Center CLI for humans and AI Agents. Supports **Jira DC only** (self-hosted), not Jira Cloud.
 
-> Install CLI: `npm install -g @fatecannotbealtered-/jira-cli`
->
-> Install Skill: `npx skills add fatecannotbealtered/jira-cli -y -g`
+```bash
+# Please install jira-cli and use it for all Jira DC operations going forward (always pass --json).
+# Install CLI (requires curl on PATH)
+npm install -g @fatecannotbealtered-/jira-cli
+
+# Install CLI Skill (required) — copies into your agent-supported skills directory
+npx skills add fatecannotbealtered/jira-cli -y -g
+
+# Login and verify
+jira-cli login
+jira-cli doctor --json
+```
+
+Optional: `jira-cli install-skill` → `~/.openclaw/skills`.
 
 ## Prerequisites
 
@@ -20,15 +31,18 @@ Before using any command, authenticate with a Jira DC instance. Follow these ste
 2. Ask the user for a **Personal Access Token (PAT)**. If they don't have one, guide them:
    "Log in to your Jira DC → click your profile avatar → Personal Access Tokens → Create token."
 3. Run `jira-cli login --host <URL> --token <PAT>` to save credentials.
-4. Run `jira-cli doctor --json` to verify connectivity. If `authValid` is `true`, you're ready.
+4. Run `jira-cli doctor --json` to verify connectivity. Check that `authValid` is `true` (exit code 3 on auth/config failure).
 
 **Important:** Credentials are saved locally at `~/.jira-cli/config.json`. Environment variables `JIRA_HOST` and `JIRA_TOKEN` override the config file — use them for CI or when the user prefers not to save credentials.
 
 **Always use `--json` flag when parsing output.** Without it, output is human-formatted and not suitable for programmatic use.
 
+**Stdout vs stderr:** Success JSON is written to **stdout**; error JSON is written to **stderr**. Capture stdout for data; check exit code and stderr for failures.
+
 ## Safety
 
 - **Do NOT use `--force` on destructive commands unless the user explicitly asks.** Commands like `issue delete` prompt for confirmation by default. Skipping confirmation with `--force` is irreversible.
+- **`issue delete --dry-run` skips confirmation** — dry-run is evaluated before the confirmation prompt.
 - **Use `--dry-run` before write operations** to preview what will happen without executing. Example: `issue create --project PROJ --summary "test" --type Task --dry-run --json`.
 - **AI Agents can make mistakes.** Always confirm with the user before executing `issue delete`, `issue bulk-transition`, `sprint close`, or any operation that modifies multiple issues.
 - All write operations are recorded in `~/.jira-cli/audit/` for traceability.
@@ -38,11 +52,10 @@ Before using any command, authenticate with a Jira DC instance. Follow these ste
 ```bash
 # View issues (flat JSON by default — token-efficient)
 jira-cli issue get PROJ-123 --json
-jira-cli issue get PROJ-123 --json --fields key,summary,status,assignee   # Only specific fields
+jira-cli issue get PROJ-123 --json --fields key,summary,status,assignee   # Output trimming (flat JSON)
 jira-cli issue get PROJ-123 --json --raw                                  # Full Jira API response
-jira-cli issue list --project PROJ --json
-jira-cli issue list --project PROJ --status "In Progress" --assignee me --json
-jira-cli issue list --project PROJ --type Bug --priority High --limit 20 --json
+jira-cli issue list --project PROJ --json                                 # Returns bare array of flat issues
+jira-cli issue list --project PROJ --json --fields key,summary,status     # Trimmed array
 
 # Create and edit
 jira-cli issue create --project PROJ --summary "Fix login bug" --type Bug --json
@@ -51,6 +64,7 @@ jira-cli issue create --project PROJ --summary "Sized story" --type Story --fiel
 jira-cli issue edit PROJ-123 --summary "Updated summary" --priority Medium
 jira-cli issue edit PROJ-123 --field "Story Points=8" --field "Team=Backend"
 jira-cli issue delete PROJ-123 --force          # Skip confirmation prompt
+jira-cli issue delete PROJ-123 --dry-run --json   # Preview delete (no confirmation prompt)
 
 # Clone an issue
 jira-cli issue clone PROJ-123 --json                                # Clone with default summary
@@ -110,7 +124,7 @@ jira-cli search "project = PROJ" --limit 100 --json
 jira-cli search "project = PROJ" --all --json          # Fetch ALL results (auto-paginate)
 jira-cli search "project = PROJ" --count               # Only show total count
 jira-cli search "project = PROJ" --order-by updated --json
-jira-cli search "type = Bug AND priority = High" --fields key,summary,status --json
+jira-cli search "type = Bug AND priority = High" --fields summary,status,customfield_10001 --json  # Jira fetch fields (API request)
 ```
 
 ## Sprint Management
@@ -124,7 +138,8 @@ jira-cli sprint issues --sprint 10 --json
 jira-cli sprint create --board 42 --name "Sprint 5" --start-date 2024-02-01 --end-date 2024-02-14 --json
 jira-cli sprint update --sprint 10 --goal "Complete payment refactor"
 jira-cli sprint move --sprint 10 --issues PROJ-123,PROJ-124,PROJ-125
-jira-cli sprint close --sprint 10 --force                          # --force skips confirmation
+jira-cli sprint close --sprint 10 --json
+jira-cli sprint close --sprint 10 --dry-run --json   # Preview without closing (no confirmation prompt)
 ```
 
 ## Board & Backlog
@@ -175,6 +190,8 @@ jira-cli filter list --json
 jira-cli filter get <filterId> --json
 jira-cli filter create --name "My Bugs" --jql "assignee = me AND type = Bug" --json
 jira-cli filter run <filterId> --json
+jira-cli filter run <filterId> --json --fields key,summary,status   # Output trimming
+jira-cli filter run <filterId> --json --raw                         # Raw Jira search response
 jira-cli filter delete <filterId>
 ```
 
@@ -218,9 +235,9 @@ jira-cli sprint move --sprint 11 --issues PROJ-200,PROJ-201,PROJ-202
 
 ## Guardrails
 
-- Always run `jira-cli doctor --json` to verify auth before bulk operations
-- `issue delete` requires typing the issue key to confirm. Use `--force` to skip confirmation in automated workflows
-- `sprint close` is irreversible. Use `--force` to skip confirmation
+- Always run `jira-cli doctor --json` and verify **`authValid` is `true`** before bulk operations (exit code 3 on failure)
+- `issue delete` requires typing the issue key to confirm. Use `--force` to skip confirmation in automated workflows; `--dry-run` skips confirmation
+- `sprint close` has no confirmation prompt — use `--dry-run` to preview; confirm with the user before closing
 - Use `--json` flag when parsing output in scripts or AI workflows
 - Use `--dry-run` to preview what a write command would do without executing it
 - Use `--quiet` with `--json` to suppress all non-JSON output (clean pipe-friendly output)
@@ -237,13 +254,36 @@ jira-cli sprint move --sprint 11 --issues PROJ-200,PROJ-201,PROJ-202
 
 ## Output Control Flags
 
-These flags are available on read commands (`issue get`, `issue list`, `search`, `sprint list`, `sprint issues`):
+Two different meanings for `--fields`:
+
+| Command | `--fields` meaning |
+|---------|-------------------|
+| `search` | **Jira fetch fields** — comma-separated fields to request from the API (e.g. `summary,status,customfield_10001`) |
+| `issue get`, `issue list`, `sprint list`, `sprint issues`, `filter run` | **Output trimming** — include only listed keys in flat JSON (e.g. `key,summary,status`) |
 
-- `--raw` — Return the full raw Jira API response instead of the token-efficient flat format
-- `--fields key,summary,status` — Output only the specified fields (flat JSON mode only)
+Other read-command flags:
+
+- `--raw` — Return the full raw Jira API response instead of the token-efficient flat format (on `issue get/list`, `search`, `filter run`, `sprint list/issues/active`)
 
 ## JSON Output Schemas
 
+### List vs search JSON shape
+
+| Command | Flat `--json` shape |
+|---------|---------------------|
+| `issue list` | Bare array: `[{key, summary, ...}, ...]` |
+| `search`, `filter run` (default) | Object with pagination: `{total, startAt, maxResults, issues: [...]}` |
+| `filter run --fields ...` | Bare trimmed array (like `issue list --fields`) |
+| `issue get` | Single flat issue object |
+
+**jq examples:**
+
+```bash
+jira-cli issue list --project PROJ --json | jq '.[].key'
+jira-cli search "project = PROJ" --json | jq '.issues[].key'
+jira-cli filter run 12345 --json | jq '.issues[].status'
+```
+
 ### Flat Issue (default with --json)
 
 ```json
@@ -276,7 +316,7 @@ These flags are available on read commands (`issue get`, `issue list`, `search`,
 }
 ```
 
-### Error Response (with --json)
+### Error Response (with --json, written to stderr)
 
 ```json
 {