Metadata-Version: 2.4
Name: inovagio-atlassian
Version: 0.1.0
Summary: Standalone, zero-pip-dep Python 3.12+ CLI for Atlassian operations and AI-agent-driven autonomous development workflows
Author-email: Inovagio <engineering@inovagio.com>
Maintainer-email: Inovagio <engineering@inovagio.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/inovagio/atlassiancli
Project-URL: Documentation, https://github.com/inovagio/atlassiancli/blob/main/docs/USAGE.md
Project-URL: Repository, https://github.com/inovagio/atlassiancli
Project-URL: Issues, https://github.com/inovagio/atlassiancli/issues
Project-URL: Changelog, https://github.com/inovagio/atlassiancli/blob/main/CHANGELOG.md
Keywords: atlassian,jira,confluence,cli,agent,ai-agent,autonomous-development,story-quality,doc-framework
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# atlassiancli

[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![CI](https://github.com/inovagio/atlassiancli/actions/workflows/ci.yml/badge.svg)](https://github.com/inovagio/atlassiancli/actions/workflows/ci.yml)
<!-- Once the first PyPI publish ships, uncomment:
[![PyPI version](https://img.shields.io/pypi/v/atlassiancli.svg)](https://pypi.org/project/atlassiancli/)
[![Python versions](https://img.shields.io/pypi/pyversions/atlassiancli.svg)](https://pypi.org/project/atlassiancli/)
-->

A standalone, pip-installable Python 3.12+ CLI for Jira and Confluence with
**zero runtime dependencies** and a **stable JSON / exit-code contract** that
makes it safe to drive from AI coding agents. Engineers use it interactively
for daily Atlassian work; autonomous-development agents use it as the
ticket-to-PR control surface.

## Why atlassiancli

Most Atlassian tooling falls into one of two traps. Either it lives inside
one organisation's monorepo and is non-portable, or it pulls a tower of PyPI
packages that fight every other project's pinning policy. atlassiancli avoids
both:

- **Drop-in portable.** Copy `src/atlassiancli/` into any repo, or
  `pip install` it — same behaviour, no project-specific assumptions baked
  into the source.
- **Stdlib-only at runtime.** Python 3.12 standard library is the only
  dependency. No `requests`, no `pyyaml`, no `python-dotenv` — the CLI ships
  its own minimal HTTP client, YAML codec, and `.env` loader. CI images and
  air-gapped environments install instantly.
- **Designed to be machine-driven.** Every analyse / write subcommand emits
  a stable `AgentResponse` JSON envelope under `--json`, follows a fixed
  exit-code contract (`0` / `1` / `2` / `75` / `77`), and is idempotent on
  retry. Agents and CI loops can branch on results without parsing prose.
- **Cleanly extensible.** A DDD-layered Python package
  (`domain` / `application` / `infrastructure` / `cli`) keeps adapters
  swappable and tests fast.

## Two ways to use it

**As an engineer's CLI.** Create epics and stories, transition workflow,
balance sprints, run quality / velocity / health reports, push markdown to
Confluence, link PRs back to issues. One tool covers most of what you'd
otherwise stitch together from `acli`, scripts, and the Jira UI.

**As agent-callable infrastructure.** Wire it into an autonomous-development
loop — the kind of system where an AI coding agent picks an unassigned
story, runs a Definition-of-Ready gate, marks the story in-progress, opens
a PR, and transitions to Done. The JSON envelope and idempotency guarantees
exist to make that loop safe. See
[docs/AGENT_INTEGRATION.md](docs/AGENT_INTEGRATION.md) for the full contract.

## Capability tiers

| Tier | What it does | Agent-callable |
|---|---|---|
| **1. Atlassian basics** | Create / transition / assign / comment issues; sprint operations (current, stories, move, balance, split); Confluence page CRUD; markdown-to-Confluence import; quality / velocity / themes / health reports. | Yes — write commands are idempotent. |
| **2. Story analysis + enhancement** | `analyze lint` (0–100 score against the 11-section AI-implementable schema), `analyze atomicity` (5-criteria PR-sized check), `analyze ready` (composite Definition-of-Ready gate), `analyze description` / `architecture` / `fetch`, `enhance` (review-then-apply), `template` (story / epic scaffolds). | Yes — primary agent surface. |
| **3. Doc framework bridge** | `framework create-stories`, `verify-stories`, `reverse-sync`, `sync-docs` — manifest-driven Jira sync from per-product YAML under `docs/<product>/stories/manifests/`, plus repo-markdown to Confluence. | Yes — every subcommand supports `--json`. |
| **4. Project bootstrap** | `framework bootstrap --product <handle>` validates a product's configured-state (`.docframework.yaml`, credentials, hub page, epics) so a new project can adopt the framework cleanly. | Read-only validation. |

The full subcommand surface is in [docs/USAGE.md](docs/USAGE.md). The
end-to-end agent contract — JSON schema, exit codes, idempotency rules,
canonical invocation patterns — is in
[docs/AGENT_INTEGRATION.md](docs/AGENT_INTEGRATION.md).

## Quick start

Five minutes from zero to a working setup.

### 1. Install

```bash
# From PyPI (once published):
pip install inovagio-atlassian

# Or from a clone, for development:
git clone https://github.com/inovagio/atlassiancli.git
cd atlassiancli
pip install -e ".[dev]"
```

Requires Python 3.12 or newer. Runtime install pulls **zero** third-party
packages. The optional `dev` extra adds `ruff`, `build`, `twine`,
`mypy`, and `pytest` for contributors.

> **Naming note.** The PyPI package is `inovagio-atlassian`; the installed
> binary command is `atlassiancli`. So `pip install inovagio-atlassian`
> gives you `atlassiancli --version` on your PATH. The split exists because
> PyPI's name normalizer treats `atlassiancli` and the already-taken
> `atlassian-cli` as the same canonical name.

### 2. Configure

Set credentials via environment variables (preferred for CI):

```bash
export ATLASSIAN_EMAIL=you@example.com
export ATLASSIAN_TOKEN=<atlassian api token>
export ATLASSIAN_SITE=<your-site>.atlassian.net
```

A `.env` file at the project root works too — atlassiancli's stdlib `.env`
loader picks it up automatically. Get an API token at
[id.atlassian.com](https://id.atlassian.com/manage-profile/security/api-tokens)
under Profile -> Security -> API tokens.

### 3. Verify

```bash
atlassiancli --version                         # confirms install
atlassiancli template story                    # confirms the rule engine
atlassiancli --json sprint current --board 42  # confirms auth + transport
```

If the third command returns a parseable JSON envelope, you're done.

### 4. First real commands

```bash
# Find the active sprint and pick the highest-priority unassigned story
atlassiancli --json sprint current --board 42
atlassiancli --json sprint stories --sprint <id> --unassigned --priority-order

# Run the Definition-of-Ready gate against a story
atlassiancli --json analyze ready PROJ-247

# Lint a story's quality score against the 11-section schema
atlassiancli analyze lint PROJ-247

# Verify per-product YAML manifests against Jira (doc-framework users)
atlassiancli framework verify-stories --product myproduct
```

For the full install walkthrough — auth troubleshooting, optional GitHub
Actions / pre-commit / cron integrations — see
[docs/INSTALL.md](docs/INSTALL.md).

## Use cases

### Engineer driving daily Atlassian operations

You've just cut a feature branch and want to wire it to a Jira story without
leaving the terminal:

```bash
# Pick up a sprint story
atlassiancli transition PROJ-247 --to "In Progress" --execute
atlassiancli assign PROJ-247 --user you@example.com

# When the PR is up
atlassiancli link-pr PROJ-247 --pr-url https://github.com/org/repo/pull/123
atlassiancli comment PROJ-247 --body "PR opened — ready for review"

# End of sprint: pull the quality + velocity rollup
atlassiancli report quality  --project PROJ
atlassiancli report velocity --board 42
```

No clicking through screens, no tab-juggling, no shell scripts wrapping
`curl`.

### AI coding agent driving an autonomous ticket-to-PR cycle

An autonomous-development agent uses atlassiancli as the Jira / Confluence
control surface. The whole loop is JSON in, JSON out:

```bash
# Phase 1 — fetch sprint item
atlassiancli --json sprint current --board 42
atlassiancli --json sprint stories --sprint $SPRINT --unassigned --priority-order

# Phase 2 — validate against the Definition-of-Ready gate
atlassiancli --json analyze ready $ISSUE
# verdict == "READY"  → continue
# verdict == "NOT_READY" → halt, surface findings to operator

# Phase 3 — claim the story (all idempotent on retry)
atlassiancli transition $ISSUE --to "In Progress" --execute
atlassiancli assign $ISSUE --user "$ATLASSIAN_EMAIL"
atlassiancli comment $ISSUE --body "Run id: $RUN_ID" --idempotency-key "$RUN_ID"

# ... agent writes code, opens PR ...

# Phase 4 — close out
atlassiancli transition $ISSUE --to "Done" --execute
atlassiancli link-pr    $ISSUE --pr-url "$PR_URL"
```

Exit codes drive the agent's state machine: `0` proceeds, `75` retries with
backoff, `77` halts on auth, `1` surfaces the finding to the operator.
Idempotent writes mean the agent can be killed and restarted at any point
without producing duplicate comments, transitions, or PR links.

## Differentiators

- **Zero pip dependencies at runtime.** `pyproject.toml` `dependencies = []`.
  Matters when you're shipping into hardened CI images, air-gapped
  environments, or codebases with strict supply-chain rules.
- **JSON output + exit-code contract.** Every analyse / write subcommand
  emits the same `AgentResponse` envelope on stdout and returns one of
  five documented exit codes (`0` / `1` / `2` / `75` / `77`). Schemas and
  fixtures in [docs/AGENT_INTEGRATION.md](docs/AGENT_INTEGRATION.md).
- **Project-agnostic + copy-deployable.** No Jira project keys, Confluence
  ids, or label namespaces hardcoded in source. Per-project config lives in
  `.atlassiancli.yaml`; per-product framework config in
  `docs/<product>/.docframework.yaml`. `cp -R src/atlassiancli/ <target>/`
  is a supported deployment path.
- **DDD-layered architecture.** `domain` / `application` / `infrastructure`
  / `cli` boundaries are enforced; tests substitute alternate adapters at
  any layer. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
- **Idempotent writes.** `transition`, `assign`, `comment` (with
  `--idempotency-key`), `link-pr`, and every `framework` subcommand are
  safe to replay.

## Documentation

| Doc | What's in it |
|---|---|
| [docs/USAGE.md](docs/USAGE.md) | Every subcommand with arguments and examples |
| [docs/INSTALL.md](docs/INSTALL.md) | Install, auth, troubleshooting, optional CI / pre-commit / cron integrations |
| [docs/AGENT_INTEGRATION.md](docs/AGENT_INTEGRATION.md) | JSON schema, exit-code contract, idempotency rules, canonical invocation patterns |
| [docs/RUNBOOK.md](docs/RUNBOOK.md) | Operational procedures: setup, daily flows, doc-framework operations, gotchas, verification gates |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | DDD layered overview |
| [docs/EXAMPLES/](docs/EXAMPLES/) | Runnable starter projects: Jira-only, doc-framework, agent-driven workflow |
| [PLAN.md](PLAN.md) | Vision, four-tier capability map, configuration model, build-out history |
| [CHANGELOG.md](CHANGELOG.md) | Release notes |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup, test runner choices, lint conventions |

## Project status

Version **0.1.0** — initial release. The full subcommand surface across all
four tiers is shipped and tested; the agent-callable contract (JSON
envelope + exit codes + idempotency) is stable. A small number of polish
items (interactive `configure` wizard, multi-profile `--profile` switch)
are tracked in [CHANGELOG.md](CHANGELOG.md) and PLAN §11.

## Contributing

Issues and pull requests welcome. atlassiancli is intentionally small and
focused — extensions live in the `cli/handlers/` layer with corresponding
domain / application services. See [CONTRIBUTING.md](CONTRIBUTING.md) for
dev setup, the test runner matrix (stdlib `unittest` is the default;
`pytest` runs the same tests unchanged), and lint conventions.

## License

MIT — see [LICENSE](LICENSE).
