@fatecannotbealtered-/jira-cli 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-05-03
+
+Initial release of jira-cli for Jira Data Center.
+
+### Features
+
+- **Jira Data Center only**: Bearer PAT authentication, DC `name`-based user references, `/rest/api/2/` exclusively.
+- **Complete coverage**: issues, sprints, boards, epics, projects, users, filters — CRUD + advanced operations.
+- **AI Agent friendly**:
+  - `--json` outputs token-efficient flat format by default; `--raw` returns full Jira API response.
+  - `--fields key,summary,status` to output only specified fields.
+  - `--quiet` suppresses all non-JSON stdout (clean pipe output).
+  - `--dry-run` on all write commands — previews without executing.
+  - `--force` skips interactive confirmation prompts.
+  - Machine-readable error codes (`errorCode`) and actionable hints (`hint`) in JSON error responses.
+  - Semantic exit codes: 0=OK, 2=bad args, 3=auth, 4=not found, 5=forbidden, 6=rate limited, 7=network.
+  - `reference` command: structured markdown listing of all commands and flags for AI self-discovery.
+- **Smart retry**: automatic exponential backoff on 429 rate limits and 5xx errors.
+- **Beautiful output**: colored tables with CJK character width support.
+- **Custom fields**: set custom fields during create and edit via `--field "Name=Value"`.
+- **Environment variables**: `JIRA_HOST` and `JIRA_TOKEN` override config file for CI/Agent use.
+- **npm distribution**: `npm install -g @fatecannotbealtered-/jira-cli` with bundled AI Agent Skill.
+- **Cross-platform**: Linux, macOS, Windows (x64 + arm64) via GoReleaser.
+- **E2E test scripts**: Comprehensive PowerShell E2E script (`scripts/e2e-full.ps1`) covering all 55+ commands against a real Jira DC instance, with CSV report output and read-only mode.
+- **Audit logging**: Automatic JSONL audit trail for all write commands (`~/.jira-cli/audit/`), with monthly file rotation and configurable retention (default 3 months). Disable with `JIRA_NO_AUDIT=1`.
+
+### Documentation
+
+- Bilingual README (English + Chinese) with CI/Report Card/License/npm badges.
+- 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.0...HEAD
+[1.0.0]: https://github.com/fatecannotbealtered/jira-cli/releases/tag/v1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+Thank you for improving jira-cli. This document describes how to build, test, and submit changes.
+
+**Note:** This is a side project shared for learning and personal use; maintainers do not offer commercial support or production guarantees�see the readme disclaimer.
+
+## Development setup
+
+- Go **1.23+** (see `go.mod`)
+- Optional: **Node.js 16+** if you work on npm install scripts
+- Optional: **golangci-lint** (CI runs it on Linux)
+
+Clone and verify:
+
+```bash
+git clone https://github.com/fatecannotbealtered/jira-cli.git
+cd jira-cli
+go mod download
+go test ./...
+go build -o bin/jira-cli ./cmd/jira-cli
+./bin/jira-cli --help
+```
+
+If `go mod download` is slow, try a regional proxy, for example:
+
+```bash
+# Example (China)
+set GOPROXY=https://goproxy.cn,direct
+```
+
+## Commands
+
+| Goal | Command |
+|------|---------|
+| Run tests (race) | `go test -race ./...` |
+| Format | `gofmt -w .` |
+| Vet | `go vet ./...` |
+| Lint | `golangci-lint run ./...` (or `make lint` on Unix) |
+| Build with version | `make build` (Unix) or `go build -ldflags "-s -w -X github.com/fatecannotbealtered/jira-cli/cmd.version=dev" -o bin/jira-cli.exe ./cmd/jira-cli` (Windows) |
+
+CI mirrors `.github/workflows/ci.yml`: tidy modules, `gofmt` check (Linux), golangci-lint, `go vet`, build, `go test -race`, and a `--help` smoke test.
+
+## Pull requests
+
+1. **One logical change per PR** when possible.
+2. **Tests**: add or update tests for behavior changes in `internal/` or stable CLI contracts.
+3. **Docs**: update `README.md` / `README_zh.md` if user-facing flags or flows change; add a line to `CHANGELOG.md` under *Unreleased*.
+4. **Commits**: clear messages; no secrets or real tokens in code or docs.
+
+## AI Agent skill bundle
+
+Bundled skills live under `skills/`. After editing, run `jira-cli install-skill` from a built binary (or from repo root with `./skills`) to confirm files copy correctly. npm installs place the binary under `bin/` and skills under `../skills` relative to the binary; the CLI resolves both layouts.
+
+## Security
+
+Do not open public issues for undisclosed security vulnerabilities. See [SECURITY.md](SECURITY.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 fatecannotbealtered
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,397 @@
+# jira-cli
+
+[![CI](https://github.com/fatecannotbealtered/jira-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/fatecannotbealtered/jira-cli/actions/workflows/ci.yml)
+[![Go Report Card](https://goreportcard.com/badge/github.com/fatecannotbealtered/jira-cli)](https://goreportcard.com/report/github.com/fatecannotbealtered/jira-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/@fatecannotbealtered-/jira-cli.svg)](https://www.npmjs.com/package/@fatecannotbealtered-/jira-cli)
+
+English | [中文](README_zh.md)
+
+Full-featured Jira Data Center CLI for humans and AI Agents. Manage issues, sprints, boards, epics, projects, users, and filters — all from your terminal.
+
+Built with Go. Single static binary (small dependency footprint via `go.mod`). No separate runtime to install.
+
+[Installation](#installation) · [Authentication](#authentication) · [Commands](#commands) · [JSON Output](#json-output) · [Security](#security) · [Contributing](#contributing) · [Disclaimer](#disclaimer)
+
+## Disclaimer
+
+This project is shared for **personal learning, research, and everyday productivity**—not as a product with SLAs. The maintainers do not offer commercial support or make any **fitness-for-production** promise. If you use it at work, that is your call: follow your org's rules. Software is provided "as is," without warranty of any kind.
+
+## Features
+
+| Capability | Description |
+|---|---|
+| 🎯 **Complete Coverage** | Issues, Sprints, Boards, Epics, Projects, Users, Filters |
+| 🤖 **AI Friendly** | `--json` flat output (token-efficient), `--quiet`, `--dry-run`, `--force`, `--fields`, `--raw` |
+| ⚡ **Single Binary** | Download and run; no JVM/Node required for the CLI itself |
+| 🔄 **Smart Retry** | Auto-retry on 429 rate limits and 5xx errors with exponential backoff |
+| 🌈 **Beautiful Output** | Colored tables with CJK character support |
+| 🔍 **Powerful Search** | Full JQL support with auto-pagination |
+| 🔧 **Custom Fields** | Set custom fields during create and edit |
+| 🔐 **PAT Auth** | Bearer token authentication (Personal Access Token) |
+| 🌐 **Env Vars** | `JIRA_HOST` and `JIRA_TOKEN` override config file for CI/Agent use |
+| 📋 **Audit Log** | Automatic JSONL audit trail for all write commands with auto-rotation |
+
+## Installation
+
+### Quick start
+
+Recommended flow: install the CLI from npm, then install the AI Agent Skill with `npx skills add`.
+
+```bash
+# Install CLI
+npm install -g @fatecannotbealtered-/jira-cli
+
+# Install CLI Skill
+npx skills add fatecannotbealtered/jira-cli -y -g
+
+# Login and verify
+jira-cli login
+jira-cli doctor
+```
+
+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.
+
+### Alternative: Go install
+
+```bash
+go install github.com/fatecannotbealtered/jira-cli/cmd/jira-cli@latest
+```
+
+### Alternative: Download binary
+
+Download from [GitHub Releases](https://github.com/fatecannotbealtered/jira-cli/releases) and add to your PATH.
+
+## Authentication
+
+jira-cli supports **Jira Data Center** (private deployments) with **Personal Access Token (PAT)** authentication.
+
+### Interactive login
+
+```bash
+jira-cli login
+# Jira host: https://jira.company.com
+# Personal Access Token (PAT): ****
+# ✔ Logged in as John Doe (johndoe)
+
+jira-cli doctor    # Verify connectivity
+jira-cli logout    # Remove credentials
+```
+
+### Non-interactive login (CI / AI Agent)
+
+```bash
+jira-cli login --host https://jira.company.com --token <PAT>
+```
+
+### Environment variables
+
+Environment variables take precedence over the config file. This is the recommended approach for CI pipelines and AI Agents:
+
+```bash
+export JIRA_HOST=https://jira.company.com
+export JIRA_TOKEN=<your-personal-access-token>
+jira-cli doctor --json
+```
+
+### Generating a PAT
+
+1. Log into your Jira Data Center instance
+2. Go to **Profile** → **Personal Access Tokens**
+3. Create a new token with appropriate permissions
+
+## Commands
+
+### Issue Management
+
+```bash
+# View
+jira-cli issue get PROJ-123
+jira-cli issue list --project PROJ
+jira-cli issue list --project PROJ --status "In Progress" --assignee me
+
+# Create & Edit
+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
+
+# Clone
+jira-cli issue clone PROJ-123
+jira-cli issue clone PROJ-123 --summary "New title" --with-links
+
+# Status
+jira-cli issue transitions PROJ-123          # List available transitions
+jira-cli issue transition PROJ-123 "Done"    # Status name required as argument
+
+# Bulk Transition
+jira-cli issue bulk-transition "Done" --issues PROJ-1,PROJ-2,PROJ-3
+jira-cli issue bulk-transition "In Progress" --jql "sprint = 10 AND status = 'To Do'"
+
+# Collaboration
+jira-cli issue assign PROJ-123 me               # Assign to current user
+jira-cli issue assign PROJ-123 johndoe          # Assign by username (DC uses name, not accountId)
+jira-cli issue watch PROJ-123
+jira-cli issue vote PROJ-123
+
+# Comments
+jira-cli issue comment add PROJ-123 --body "Fixed in PR #42"
+jira-cli issue comment list PROJ-123
+
+# Worklogs
+jira-cli issue worklog add PROJ-123 --time 2h --comment "Debugging"
+jira-cli issue worklog list PROJ-123
+
+# Links & Attachments
+jira-cli issue link PROJ-123 --to PROJ-456 --type "blocks"
+jira-cli issue attach PROJ-123 --file ./screenshot.png
+jira-cli issue remote-link PROJ-123 --url https://pr.url --title "PR #42"
+```
+
+### Search (JQL)
+
+```bash
+jira-cli search "assignee = currentUser() AND status != Done"
+jira-cli search "project = PROJ AND sprint in openSprints()" --all
+jira-cli search "type = Bug AND priority = High" --count
+jira-cli search "project = PROJ" --limit 100 --order-by updated
+```
+
+### Sprint Management
+
+```bash
+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
+```
+
+### Board & Backlog
+
+```bash
+jira-cli board list
+jira-cli board backlog --board 42
+jira-cli board epics --board 42
+```
+
+### Projects, Users & Filters
+
+```bash
+jira-cli project list
+jira-cli project versions PROJ --unreleased
+jira-cli project fields --custom              # List custom fields
+jira-cli user search --query "john"
+jira-cli user me
+jira-cli filter list
+jira-cli filter run <filterId>
+```
+
+## 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):
+
+```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
+jira-cli issue get PROJ-123 --json --fields key,summary,status,assignee
+
+# Raw Jira API response (full nested structure)
+jira-cli issue get PROJ-123 --json --raw
+
+# Clean output for scripts (suppress all non-JSON noise)
+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:
+
+```json
+{
+  "error": "Jira API error 404: Issue does not exist",
+  "statusCode": 404,
+  "errorCode": "NOT_FOUND",
+  "hint": "Verify the issue key exists and you have permission to view it"
+}
+```
+
+Set `NO_COLOR=1` to disable colored output (useful in CI/CD).
+
+Run `jira-cli reference` to get a complete listing of all commands and flags in structured markdown.
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `JIRA_HOST` | Jira Data Center host URL (overrides config file) |
+| `JIRA_TOKEN` | Personal Access Token (overrides config file) |
+| `NO_COLOR` | Set to any value to disable colored output ([no-color.org](https://no-color.org)) |
+| `JIRA_CLI_USER_AGENT` | Custom User-Agent string for HTTP requests |
+| `JIRA_NO_AUDIT` | Set to `1` to disable audit logging |
+| `JIRA_AUDIT_RETENTION_MONTHS` | Auto-delete audit files older than N months (default: `3`, `0` = keep forever) |
+
+## Config File
+
+Credentials stored at `~/.jira-cli/config.json` (permissions: 0600):
+
+```json
+{
+  "host": "https://jira.company.com",
+  "token": "your-personal-access-token"
+}
+```
+
+## Global Flags
+
+| Flag | Description |
+|---|---|
+| `--json` | Output as JSON (flat format by default; use `--raw` for full Jira response) |
+| `--force` | Skip interactive confirmation prompts |
+| `--quiet` | Suppress non-JSON stdout output (for scripts and AI Agents) |
+| `--dry-run` | Show what would be done without executing (write commands only) |
+
+### Per-command flags
+
+| 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`) |
+
+## Troubleshooting
+
+| Issue | Solution |
+|---|---|
+| 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 |
+| Resource not found | Verify the issue key or project key exists |
+| Rate limited (429) | The CLI auto-retries; reduce request frequency if persistent |
+| Host must start with https:// | Ensure your host URL includes the `https://` protocol |
+
+## Security
+
+- Credentials are stored locally at `~/.jira-cli/config.json` with `0600` file permissions (user-only readable)
+- Config directory is created with `0700` permissions
+- PAT input is hidden during `jira-cli login` (uses terminal secure input)
+- All communication uses HTTPS (host must start with `https://`)
+- No credentials are logged or transmitted to third parties
+- Environment variables `JIRA_HOST` and `JIRA_TOKEN` take precedence over config file
+
+> **AI Agent Note:** This tool can be invoked by AI Agents to automate Jira operations. Use `--force` to skip interactive prompts and `--json` for structured output. Set `JIRA_HOST` and `JIRA_TOKEN` environment variables for non-interactive authentication.
+
+For vulnerability reports, see [SECURITY.md](SECURITY.md).
+
+## Audit Logging
+
+Every write command (create, edit, delete, transition, assign, comment, etc.) is automatically logged to `~/.jira-cli/audit/` in JSONL format — one JSON object per line, one file per month.
+
+```bash
+# Example: view today's audit log
+cat ~/.jira-cli/audit/audit-2026-05.jsonl
+
+# Each entry looks like:
+# {"ts":"2026-05-03T14:22:01+08:00","cmd":"issue edit","args":["issue","edit","PROJ-123","--summary","new"],"exit":0,"ms":2031}
+```
+
+### Configuration
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `JIRA_NO_AUDIT` | (unset) | Set to `1` to disable audit logging entirely |
+| `JIRA_AUDIT_RETENTION_MONTHS` | `3` | Auto-delete audit files older than N months. Set to `0` to keep forever. |
+
+Cleanup runs lazily on each write command — no background process or cron needed.
+
+## E2E Integration Tests
+
+A comprehensive E2E test script covers **every jira-cli command** (55+ operations) against a real Jira Data Center instance.
+
+### Quick start
+
+```bash
+# Read-only mode (safe — no data is modified)
+export JIRA_HOST=https://jira.company.com
+export JIRA_TOKEN=<your-pat>
+export JIRA_E2E_MUTATE=0
+pwsh ./scripts/e2e-full.ps1
+```
+
+### Full test (creates and deletes test issues, filters)
+
+```bash
+pwsh ./scripts/e2e-full.ps1
+```
+
+### With sprint write tests
+
+```bash
+export JIRA_E2E_SPRINT=1
+pwsh ./scripts/e2e-full.ps1
+```
+
+The script produces:
+- Terminal summary with PASS / FAIL / SKIP counts
+- `scripts/e2e-report.csv` — machine-readable results for CI dashboards
+
+### Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `JIRA_HOST` | required | Jira DC host URL |
+| `JIRA_TOKEN` | required | Personal Access Token |
+| `JIRA_CLI_BIN` | `jira-cli` | Path to binary |
+| `JIRA_E2E_PROJECT` | auto-detect | Force a project key |
+| `JIRA_E2E_MUTATE` | `1` | Set `0` for read-only tests |
+| `JIRA_E2E_SPRINT` | `0` | Set `1` for sprint write tests |
+| `JIRA_E2E_CLEANUP` | `1` | Set `0` to keep test resources |
+
+## Project Structure
+
+```
+jira-cli/
+├── cmd/
+│   ├── jira-cli/
+│   │   └── main.go          # Entry point (semantic exit codes)
+│   ├── root.go              # Root command, global flags, error handling
+│   ├── login.go             # Authentication (PAT-only, non-interactive)
+│   ├── doctor.go            # Diagnostics
+│   ├── issue.go             # Issue CRUD
+│   ├── issue_*.go           # Issue sub-commands
+│   ├── flatten.go           # Flat JSON output helpers (issues, sprints)
+│   ├── reference.go         # Self-documenting command reference
+│   ├── sprint.go            # Sprint management
+│   ├── board.go             # Board operations
+│   ├── project.go           # Project management
+│   ├── search.go            # JQL search
+│   ├── user.go              # User operations
+│   ├── filter.go            # Saved filters
+│   └── epic.go              # Epic operations
+├── internal/
+│   ├── api/                 # Jira REST API v2 client + types
+│   ├── audit/               # Write-operation audit logging (JSONL)
+│   ├── config/              # Config file + env var management
+│   └── output/              # Output formatting (tables, colors, flatten types)
+├── scripts/
+│   ├── install.js           # npm postinstall (downloads binary)
+│   ├── run.js               # npm bin wrapper
+│   └── e2e-full.ps1         # Full E2E integration tests (all commands)
+├── skills/                  # AI Agent Skill (bundled for install-skill)
+├── package.json             # npm distribution
+├── .goreleaser.yml          # Release automation
+├── Makefile                 # Local development
+└── .github/workflows/       # CI/CD
+```
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md). Release notes: [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT © fatecannotbealtered

package/SECURITY.md

@@ -0,0 +1,28 @@
+# Security
+
+## Supported versions
+
+Security fixes are applied to the latest minor release on the default branch (`main`). Release binaries are published via GitHub Releases and the npm package `@fatecannotbealtered-/jira-cli`.
+
+## Reporting a vulnerability
+
+Please **do not** file a public GitHub issue for undisclosed security vulnerabilities.
+
+Instead, report privately via [GitHub Security Advisories](https://github.com/fatecannotbealtered/jira-cli/security/advisories/new) for this repository, or contact the maintainers through the contact options on the repository homepage.
+
+Include:
+
+- Description of the issue and impact
+- Steps to reproduce (if safe to share)
+- Affected versions or install methods (binary / npm / `go install`)
+
+You should receive an acknowledgment as capacity allows. Thank you for helping keep users safe.
+
+## Credential handling (design)
+
+- Credentials are stored only in `~/.jira-cli/config.json` with file mode `0600` and directory `0700`.
+- API tokens are read with hidden input in interactive terminals.
+- Traffic is HTTPS-only to the configured Jira Data Center host (host must start with `https://`).
+- Environment variables `JIRA_HOST` and `JIRA_TOKEN` take precedence over config file; prefer them in CI/Agent workflows to avoid persisting credentials on disk.
+
+Review these assumptions when integrating jira-cli into automation or AI agent workflows.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@fatecannotbealtered-/jira-cli",
+  "version": "1.0.0",
+  "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",
+    "cli",
+    "atlassian",
+    "ai-agent",
+    "devtools",
+    "sprint",
+    "issue-tracker",
+    "openclaw"
+  ],
+  "author": "guosong6886@gmail.com",
+  "homepage": "https://github.com/fatecannotbealtered/jira-cli#readme",
+  "bugs": {
+    "url": "https://github.com/fatecannotbealtered/jira-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fatecannotbealtered/jira-cli.git"
+  },
+  "license": "MIT",
+  "bin": {
+    "jira-cli": "scripts/run.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js"
+  },
+  "files": [
+    "scripts/install.js",
+    "scripts/run.js",
+    "skills/",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md"
+  ],
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "engines": {
+    "node": ">=16"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { execFileSync } = require("child_process");
+const os = require("os");
+
+const VERSION = require("../package.json").version;
+const REPO = "fatecannotbealtered/jira-cli";
+const NAME = "jira-cli";
+
+const PLATFORM_MAP = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+};
+
+const ARCH_MAP = {
+  x64: "amd64",
+  arm64: "arm64",
+};
+
+const platform = PLATFORM_MAP[process.platform];
+let arch = ARCH_MAP[process.arch];
+
+// Windows ARM64: fall back to amd64 (runs via emulation)
+if (process.platform === "win32" && process.arch === "arm64") {
+  console.log("Windows ARM64 detected, falling back to x64 binary (runs via emulation)");
+  arch = "amd64";
+}
+
+if (!platform || !arch) {
+  console.error(`Unsupported platform: ${process.platform}-${process.arch}`);
+  console.error(`\nManually download from:\n  https://github.com/${REPO}/releases`);
+  process.exit(1);
+}
+
+const isWindows = process.platform === "win32";
+const ext = isWindows ? ".zip" : ".tar.gz";
+const archiveName = `${NAME}-${VERSION}-${platform}-${arch}${ext}`;
+const GITHUB_URL = `https://github.com/${REPO}/releases/download/v${VERSION}/${archiveName}`;
+
+const binDir = path.join(__dirname, "..", "bin");
+const dest = path.join(binDir, NAME + (isWindows ? ".exe" : ""));
+
+fs.mkdirSync(binDir, { recursive: true });
+
+function download(url, destPath) {
+  const args = [
+    "--fail", "--location", "--silent", "--show-error",
+    "--connect-timeout", "15", "--max-time", "120",
+    "--output", destPath, url,
+  ];
+  if (isWindows) {
+    args.unshift("--ssl-revoke-best-effort");
+  }
+  execFileSync("curl", args, { stdio: ["ignore", "ignore", "pipe"] });
+}
+
+function verifyChecksum(filePath, expectedHash) {
+  const fileBuffer = fs.readFileSync(filePath);
+  const hash = crypto.createHash("sha256").update(fileBuffer).digest("hex");
+  if (hash !== expectedHash) {
+    throw new Error(
+      `Checksum mismatch!\n  Expected: ${expectedHash}\n  Actual:   ${hash}`
+    );
+  }
+}
+
+function install() {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "jira-cli-"));
+  const archivePath = path.join(tmpDir, archiveName);
+  const checksumURL = `https://github.com/${REPO}/releases/download/v${VERSION}/checksums.txt`;
+  const checksumPath = path.join(tmpDir, "checksums.txt");
+
+  try {
+    console.log(`Downloading ${NAME} v${VERSION} for ${platform}-${arch}...`);
+    download(GITHUB_URL, archivePath);
+
+    // Verify checksum
+    try {
+      download(checksumURL, checksumPath);
+      const checksumContent = fs.readFileSync(checksumPath, "utf8");
+      const line = checksumContent
+        .split("\n")
+        .find((l) => l.includes(archiveName));
+      if (line) {
+        const expectedHash = line.trim().split(/\s+/)[0];
+        verifyChecksum(archivePath, expectedHash);
+        console.log("✔ Checksum verified");
+      } else {
+        console.warn("Warning: archive not found in checksums.txt, skipping verification");
+      }
+    } catch (checksumErr) {
+      if (checksumErr.message.includes("Checksum mismatch")) {
+        throw checksumErr;
+      }
+      console.warn("Warning: could not verify checksum —", checksumErr.message);
+    }
+
+    // Extract binary
+    if (isWindows) {
+      execFileSync("powershell", [
+        "-Command",
+        `Expand-Archive -Path '${archivePath}' -DestinationPath '${tmpDir}' -Force`,
+      ], { stdio: "ignore" });
+    } else {
+      execFileSync("tar", ["-xzf", archivePath, "-C", tmpDir], {
+        stdio: "ignore",
+      });
+    }
+
+    const binaryName = NAME + (isWindows ? ".exe" : "");
+    const extractedBinary = path.join(tmpDir, binaryName);
+
+    fs.copyFileSync(extractedBinary, dest);
+    if (!isWindows) {
+      fs.chmodSync(dest, 0o755);
+    }
+    console.log(`✔ ${NAME} v${VERSION} installed successfully`);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+try {
+  install();
+} catch (err) {
+  console.error(`Failed to install ${NAME}:`, err.message);
+  console.error(
+    `\nManually download from:\n  https://github.com/${REPO}/releases\n`
+  );
+  process.exit(1);
+}

package/scripts/run.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+
+const ext = process.platform === "win32" ? ".exe" : "";
+const bin = path.join(__dirname, "..", "bin", "jira-cli" + ext);
+
+try {
+  execFileSync(bin, process.argv.slice(2), { stdio: "inherit" });
+} catch (e) {
+  if (e.code === "ENOENT") {
+    console.error("Binary not found. Run 'npm install -g @fatecannotbealtered-/jira-cli' to reinstall.");
+  }
+  process.exit(e.status || 1);
+}

package/skills/jira-cli/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: jira-cli
+description: Full Jira Data Center control from the terminal. Manage issues, sprints, boards, epics, projects, users, and filters. Use --json flag for machine-readable output when parsing results programmatically.
+metadata: {"openclaw":{"emoji":"🎯","requires":{"bins":["jira-cli"]}}}
+---
+
+# jira-cli
+
+Jira Data Center CLI for humans and AI Agents. Supports **Jira DC only** (self-hosted), not Jira Cloud.
+
+## Prerequisites
+
+Before using any command, authenticate with a Jira DC instance. Follow these steps in order:
+
+1. Ask the user for their Jira DC URL (e.g. `https://jira.company.com`). It must start with `https://`.
+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.
+
+**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.
+
+## 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.
+- **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.
+
+## Issue Management
+
+```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 --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
+
+# Create and edit
+jira-cli issue create --project PROJ --summary "Fix login bug" --type Bug --json
+jira-cli issue create --project PROJ --summary "New feature" --type Story --assignee me --priority High --json
+jira-cli issue create --project PROJ --summary "Sized story" --type Story --field "Story Points=5" --json
+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
+
+# Clone an issue
+jira-cli issue clone PROJ-123 --json                                # Clone with default summary
+jira-cli issue clone PROJ-123 --summary "New title" --json          # Clone with custom summary
+jira-cli issue clone PROJ-123 --with-links --json                   # Clone with issue links
+
+# Status transitions
+jira-cli issue transitions PROJ-123 --json          # List available transitions
+jira-cli issue transition PROJ-123 "In Progress"    # Transition to status (name required)
+jira-cli issue transition PROJ-123 "Done" --json
+
+# Bulk transition
+jira-cli issue bulk-transition "Done" --issues PROJ-1,PROJ-2,PROJ-3 --json
+jira-cli issue bulk-transition "In Progress" --jql "project = PROJ AND sprint = 10 AND status = 'To Do'" --json
+
+# Assignment and watching
+jira-cli issue assign PROJ-123 me                   # Assign to current user
+jira-cli issue assign PROJ-123 johndoe              # Assign by username (DC uses name, not accountId)
+jira-cli issue unassign PROJ-123
+jira-cli issue watch PROJ-123
+jira-cli issue unwatch PROJ-123
+jira-cli issue watchers PROJ-123 --json
+jira-cli issue vote PROJ-123
+jira-cli issue unvote PROJ-123
+
+# Comments
+jira-cli issue comment add PROJ-123 --body "Fixed in PR #42" --json
+jira-cli issue comment list PROJ-123 --json
+jira-cli issue comment delete PROJ-123 --id <commentId>
+
+# Worklogs
+jira-cli issue worklog add PROJ-123 --time 2h --comment "Debugging session" --json
+jira-cli issue worklog add PROJ-123 --time 1h30m --started "2024-01-15T10:00:00.000+0000"
+jira-cli issue worklog list PROJ-123 --json
+
+# Links
+jira-cli issue link-types --json                                    # List available link types
+jira-cli issue link PROJ-123 --to PROJ-456 --type "blocks"
+jira-cli issue unlink <linkId>
+jira-cli issue remote-link PROJ-123 --url https://pr.url --title "PR #42"
+jira-cli issue remote-links PROJ-123 --json
+
+# Attachments
+jira-cli issue attach PROJ-123 --file ./screenshot.png
+jira-cli issue attachments PROJ-123 --json
+```
+
+## Search (JQL)
+
+```bash
+# Basic search
+jira-cli search "assignee = currentUser() AND status != Done" --json
+jira-cli search "project = PROJ AND sprint in openSprints()" --json
+
+# Advanced options
+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
+```
+
+## Sprint Management
+
+```bash
+jira-cli board list --json                                          # Find board IDs first
+jira-cli sprint list --board 42 --json
+jira-cli sprint list --board 42 --state active --json
+jira-cli sprint active --board 42 --json                           # Active sprint + issues
+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
+```
+
+## Board & Backlog
+
+```bash
+jira-cli board list --json
+jira-cli board list --project PROJ --type scrum --json
+jira-cli board get --board 42 --json
+jira-cli board backlog --board 42 --json
+jira-cli board epics --board 42 --json
+jira-cli board sprints --board 42 --state active --json
+```
+
+## Epic Management
+
+```bash
+jira-cli epic list --board 42 --json
+jira-cli epic list --board 42 --done --json              # Completed epics only
+jira-cli epic issues PROJ-1 --board 42 --json
+```
+
+## Project Management
+
+```bash
+jira-cli project list --json
+jira-cli project list --type software --json
+jira-cli project get PROJ --json
+jira-cli project components PROJ --json
+jira-cli project versions PROJ --json
+jira-cli project versions PROJ --unreleased --json
+jira-cli project issue-types PROJ --json
+jira-cli project fields --json                       # List all fields (system + custom)
+jira-cli project fields --custom --json              # List custom fields only
+```
+
+## User Search
+
+```bash
+jira-cli user me --json                                  # Current user info
+jira-cli user search --query "john" --json
+jira-cli user search --query "john" --assignable --project PROJ --json
+```
+
+## Filters
+
+```bash
+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 delete <filterId>
+```
+
+## Workflow Examples
+
+### Find and update an issue
+```bash
+# 1. Search for issues
+jira-cli search "project = PROJ AND assignee = me AND status = 'In Progress'" --json
+
+# 2. Get issue details
+jira-cli issue get PROJ-123 --json
+
+# 3. Check available transitions
+jira-cli issue transitions PROJ-123 --json
+
+# 4. Transition to Done
+jira-cli issue transition PROJ-123 "Done"
+
+# 5. Add a comment
+jira-cli issue comment add PROJ-123 --body "Completed and deployed to staging"
+```
+
+### Sprint planning workflow
+```bash
+# 1. Find the board
+jira-cli board list --json
+
+# 2. Check active sprint
+jira-cli sprint active --board 42 --json
+
+# 3. View backlog
+jira-cli board backlog --board 42 --json
+
+# 4. Create next sprint
+jira-cli sprint create --board 42 --name "Sprint 6" --start-date 2024-02-15 --end-date 2024-02-28 --json
+
+# 5. Move issues to sprint
+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
+- 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)
+- `issue transition` requires the status name as the second argument (no interactive selection)
+- When searching for usernames to use with `issue assign`, use `user search --query <name> --json` first
+- DC uses **username** (not accountId) for user references. Use `jira-cli user me --json` to find your username
+
+## Global Flags
+
+- `--json` — Output as JSON (machine-readable, flat format by default)
+- `--force` — Skip interactive confirmation prompts (for CI/Agent automation)
+- `--quiet` — Suppress non-JSON stdout output (ideal for scripts and AI Agents)
+- `--dry-run` — Show what would be done without executing (write commands only)
+
+## Output Control Flags
+
+These flags are available on read commands (`issue get`, `issue list`, `search`, `sprint list`, `sprint issues`):
+
+- `--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)
+
+## JSON Output Schemas
+
+### Flat Issue (default with --json)
+
+```json
+{
+  "key": "PROJ-123",
+  "summary": "Fix login bug",
+  "status": "In Progress",
+  "type": "Bug",
+  "assignee": "johndoe",
+  "reporter": "janedoe",
+  "priority": "High",
+  "created": "2024-01-15T10:30:00.000+0000",
+  "updated": "2024-01-16T14:20:00.000+0000",
+  "labels": "backend,urgent",
+  "component": "auth",
+  "parent": "PROJ-100"
+}
+```
+
+### Flat Sprint
+
+```json
+{
+  "id": 42,
+  "name": "Sprint 5",
+  "state": "active",
+  "startDate": "2024-02-01",
+  "endDate": "2024-02-14",
+  "goal": "Complete payment module"
+}
+```
+
+### Error Response (with --json)
+
+```json
+{
+  "error": "Jira API error 404: Issue does not exist",
+  "statusCode": 404,
+  "errorCode": "NOT_FOUND",
+  "hint": "Verify the issue key exists and you have permission to view it"
+}
+```
+
+### Error Codes
+
+| Code | Status | Hint |
+|------|--------|------|
+| `AUTH_REQUIRED` | 401 | Run `jira-cli login` or set JIRA_HOST and JIRA_TOKEN |
+| `FORBIDDEN` | 403 | Check your PAT scope and project permissions |
+| `NOT_FOUND` | 404 | Verify the resource key/ID exists |
+| `RATE_LIMITED` | 429 | Wait and retry; reduce request frequency |
+| `SERVER_ERROR` | 5xx | Jira server error; retry later |
+| `NETWORK_ERROR` | — | Check host URL and network connectivity |
+| `CONFIG_ERROR` | — | Run `jira-cli login` or set env vars |
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 2 | Bad arguments |
+| 3 | Authentication error |
+| 4 | Resource not found |
+| 5 | Forbidden |
+| 6 | Rate limited |
+| 7 | Network/server error |
+
+## Audit Logging
+
+All write commands are automatically logged to `~/.jira-cli/audit/` in JSONL format (one file per month). Each entry records the command, arguments, exit code, and duration.
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `JIRA_NO_AUDIT` | (unset) | Set `1` to disable audit logging |
+| `JIRA_AUDIT_RETENTION_MONTHS` | `3` | Auto-delete files older than N months (`0` = keep forever) |
+
+## Self-Description
+
+```bash
+jira-cli reference   # Print all commands, subcommands, and flags in structured markdown
+```