# Pi Jira extension

Open-source Jira Cloud integration for Pi using the REST API v3.

## Features

- Verify the Jira connection and authenticated user.
- Search issues with JQL.
- Read, create, and update issues.
- Add comments, apply transitions, and manage assignees.
- Require interactive confirmation for every write operation.
- Support read-only mode and protect non-interactive writes.

## Install from GitHub

```powershell
pi install https://github.com/Lollyz/pi-jira-extension
```

Start Pi and run the guided setup:

```text
/jira-setup
```

The wizard verifies the connection, stores non-sensitive preferences in `~/.pi/agent/jira/config.json`, and saves the API token in the operating system keychain. If Pi was already running during installation, run `/reload` first.

To update this package:

```powershell
pi update --extension https://github.com/Lollyz/pi-jira-extension
```

To remove it:

```powershell
pi remove https://github.com/Lollyz/pi-jira-extension
```

## Configuration

Create a personal API token at <https://id.atlassian.com/manage-profile/security/api-tokens>, then start the wizard in Pi:

```text
/jira-setup
```

The wizard asks for the Jira URL, email address, API token, default project, default issue type, and read-only mode. The token is masked during input, verified against Jira, and stored in the Windows, macOS, or Linux keychain. It is never written to the configuration file.

Management commands:

- `/jira-config`: show the active configuration without secrets.
- `/jira-status`: verify credentials and connectivity.
- `/jira-logout`: delete the token from the keychain.
- `/jira-setup`: reconfigure the integration.

### Environment variables for automation

Environment variables remain available for CI and advanced use when no complete `/jira-setup` configuration exists. A complete guided setup—saved preferences plus a keychain token—takes precedence, preventing an inherited stale `JIRA_API_TOKEN` from replacing the newly configured token:

```powershell
$env:JIRA_BASE_URL = "https://company.atlassian.net"
$env:JIRA_EMAIL = "name@company.example"
$env:JIRA_API_TOKEN = "token"
$env:JIRA_PROJECT_KEY = "PRX"                 # optional
$env:JIRA_DEFAULT_ISSUE_TYPE = "Task"         # optional
```

Never store the token in the repository, Pi prompts, or Pi sessions. Each user should use their own Jira account and API token.

## Verification

In Pi:

```text
/jira-status
```

Alternatively, ask the agent to use `jira_status`.

Local checks:

```powershell
npm test
npm run verify
```

## Available tools

- `jira_status`
- `jira_search`
- `jira_get_issue`
- `jira_create_issue`
- `jira_update_issue`
- `jira_comment`
- `jira_transition` (`list` or `apply`)
- `jira_assign`

## Write safety

Every write operation requires interactive confirmation. Writes are denied by default in non-interactive mode.

- `JIRA_READ_ONLY=true`: block all writes.
- `JIRA_ALLOW_NONINTERACTIVE_WRITES=true`: allow writes without a UI; use only in controlled automation.

Pi extensions run with the local user's permissions. Always review the source code and install updates only from trusted sources.