How mulhamna/jira-commands works
1. Repository shape: a Rust workspace around one shared Jira engine
- This repo is organized as a Cargo workspace with a shared library and multiple frontends.
- The central boundary is: Jira protocol/domain logic lives in jira-core, while jira, jira-mcp, and zed-jira are consumers/wrappers around it.
2. Core subsystem: crates/jira-core is the integration layer with Jira
- jira-core owns the low-level Jira client, auth handling, config loading, API error types, field caching, ADF conversion, and typed models.
- Its model layer covers the main Jira objects the product manipulates: issues, comments, attachments, links, worklogs, transitions, versions, components, users, sprints, and fields.
- This crate is the main boundary between the repo and external Jira Cloud / Jira Data Center REST APIs.
3. Authentication and profile/config flow
- The app is profile-based: config is loaded from a user config file, with environment variables able to override the active profile.
- Multiple deployments are supported through stored profiles, each carrying base URL, credentials, deployment type, API version, timeout, and project defaults.
- The auth/config path feeds the shared client, so every frontend inherits the same login model and server selection behavior.
4. Primary user-facing binary: crates/jira
- jira is the main CLI application and the most feature-rich frontend.
- It exposes subcommand groups for auth, issue management, raw API calls, plans, MCP install/doctor flows, and the TUI launcher.
- The CLI is the orchestration layer: it parses user intent, calls jira-core, and formats results back to the terminal.
5. Issue-management command pipeline
- Most operational flows go through jira issue ...: list/view/create/update/transition/move/clone/delete, attachments, worklogs, links, bulk operations, version management, and JQL builder flows.
- There is a clear request path: command arguments or interactive prompts → CLI logic → shared Jira client → Jira REST API → formatted terminal output.
- Bulk commands accept JQL, explicit keys, or manifests, so the CLI can drive both ad hoc and batch operations.
6. Interactive TUI subsystem inside crates/jira
- The TUI is a full-screen stateful frontend for browsing, editing, and bulk-managing issues without leaving the terminal.
- Its internal modules separate UI concerns: app state, columns, modes, mouse/key handling, modal dialogs, render/theme, picker/prompts, and preference persistence.
- The TUI depends on the same shared client and models, but adds richer interaction state, split master-detail rendering, and mouse-driven navigation.
7. Markdown-to-Jira content transformation
- The repo includes an ADF layer and a “render” path for converting Markdown-like input into Jira’s Atlassian Document Format JSON and/or plain text previews.
- This is important because issue descriptions/comments can be authored in more natural text but must be sent to Jira in ADF-compatible form.
- In architecture terms, this is a content transformation boundary between local text input and Jira’s structured document model.
8. Optional MCP server: crates/jira-mcp
- jira-mcp exposes Jira capabilities as typed Model Context Protocol tools for editors and AI agents.
- It sits on top of the same shared core client, so it is not a separate integration stack; it is another frontend to the same Jira domain layer.
- The server’s role is adapter-style: map MCP requests into Jira operations and normalize errors for tool consumers.
9. Editor integration and extension mirroring
- crates/zed-jira is a Zed extension packaging target, with schema/default settings and extension metadata.
- The repo also contains a plugin/ tree with Claude plugin metadata and skills, indicating the project is distributed into multiple agent/editor ecosystems.
- These integration surfaces are distinct from the CLI/MCP server, but they reuse the same Jira semantics and installation/update conventions.
10. Distribution and packaging layer
- Release artifacts are produced for several channels: Cargo, npm wrapper, Scoop, Winget, Chocolatey, and install scripts.
- The packaging/ directory and helper scripts automate generation/updates of those distribution manifests.
- This means the repo’s architecture includes a build-and-release boundary, not just runtime code.
11. Operational metadata and runtime discovery
- The app discovers custom fields at runtime and caches them, rather than hardcoding field IDs or schemas.
- That makes Jira instance differences part of the runtime model, not the build-time model.
- Related support code includes version checking/insights and notification handling inside the CLI app.
12. Quality, security, and release automation
- GitHub Actions, release-please, security workflows, and package submission scripts form the delivery pipeline.
- There is also fuzzing support for Markdown/ADF handling and a clusterfuzzlite container, which is relevant because input parsing/conversion is a likely edge-case boundary.
- These pieces do not affect day-to-day runtime architecture, but they matter for understanding how the repo is validated and shipped.
13. End-to-end data flow summary
- User input enters through one of three front doors: CLI, TUI, or MCP server.
- Those frontends converge on jira-core for auth, request construction, model decoding, and Jira REST communication.
- Jira responses come back as typed domain objects, are optionally cached/transformed, and are rendered either as terminal output, interactive UI state, or tool responses for external clients.
Main entry points: lib.rs jira-core · mod.rs Commands · Cargo.toml Cargo workspace · main.rs jira
Components 20
Workspace
Cargo workspace and shared repository boundary
- Cargo workspace · Top-level Rust workspace that ties crates together
Cargo.toml
Jira Core
Shared Jira integration and domain layer
- jira-core · Shared Jira client, config, auth, ADF, and domain models
crates/jira-core/src/lib.rs - Client · Low-level Jira request/response boundary
crates/jira-core/src/client.rs - Auth · Profile-based credentials and server selection
crates/jira-core/src/auth.rs - Config · Loads active profile and deployment settings
crates/jira-core/src/config.rs - ADF · Markdown and text conversion to Jira document format
crates/jira-core/src/adf.rs - Field cache · Caches discovered custom fields and metadata
crates/jira-core/src/field_cache.rs - Models · Typed Jira issues, comments, links, worklogs, versions, users, and related objects
crates/jira-core/src/model/mod.rs
CLI App
Primary terminal application and TUI
- jira · Main command-line frontend and orchestration layer
crates/jira/src/main.rs - Commands · Subcommand routing for auth, issues, API, plans, MCP install, and TUI launch
crates/jira/src/cli/mod.rs - Issue flow · List, view, create, update, transition, move, clone, delete, and bulk issue operations
crates/jira/src/cli/issue.rs - API calls · Direct API command path for advanced requests
crates/jira/src/cli/api.rs - Auth cmd · CLI login and profile management surface
crates/jira/src/cli/auth.rs - TUI · Full-screen issue browser and editor experience
crates/jira/src/tui/mod.rs
Integrations
MCP, editor, and plugin surfaces
- jira-mcp · Model Context Protocol server exposing Jira tools
crates/jira-mcp/src/main.rs - zed-jira · Zed extension packaging and settings surface
crates/zed-jira/src/lib.rs - Claude plugin · Plugin metadata and skills for Claude ecosystems
plugin/.claude-plugin/plugin.json
Packaging
Release and installation artifacts
- Packaging · npm, scoop, winget, chocolatey, and install scripts
packaging/npm/package.json
Connections 30
- Cargo workspace → jira-core: includes · Workspace builds the shared Jira core crate
- Cargo workspace → jira: includes · Workspace builds the main CLI binary
- Cargo workspace → jira-mcp: includes · Workspace builds the MCP server
- Cargo workspace → zed-jira: includes · Workspace includes the Zed extension crate
- jira → Commands: routes · Binary dispatches into subcommand handlers
- Commands → Auth cmd: delegates · Auth subcommands are handled separately
- Commands → Issue flow: delegates · Issue operations form the primary command pipeline
- Commands → API calls: delegates · Raw API subcommands bypass higher-level issue flows
- Commands → TUI: launches · CLI can start the TUI frontend
- Issue flow → jira-core: uses · Issue commands call the shared Jira client and models
- API calls → Client: uses · Raw API path talks to the shared client
- Auth cmd → Auth: uses · CLI auth reuses profile and credential handling
- TUI → jira-core: uses · TUI reads and writes through the shared Jira layer
- TUI → Field cache: caches · TUI benefits from runtime field metadata caching
- jira-core → Client: contains · Core crate centralizes Jira HTTP access
- jira-core → Auth: contains · Core crate owns auth handling
- jira-core → Config: contains · Core crate loads profiles and deployment settings
- jira-core → ADF: contains · Core crate handles Jira document transformation
- jira-core → Field cache: contains · Core crate caches discovered fields
- jira-core → Models: contains · Core crate defines typed Jira domain models
- jira-mcp → jira-core: adapts · MCP server maps tools onto shared Jira operations
- zed-jira → jira-core: depends on · Extension mirrors the same Jira semantics via the shared core
- Claude plugin → jira-core: reflects · Plugin skills mirror the repository's Jira operations
- Packaging → jira: packages · Distribution artifacts ship the CLI frontend
- Packaging → zed-jira: packages · Distribution artifacts include the editor extension
- CI/CD → Packaging: builds · CI automates release and submission manifests
- CI/CD → jira: validates · Workflows test and release the main CLI
- CI/CD → jira-core: validates · Workflows test the shared Jira engine
- Fuzzing → ADF: hardens · Fuzzing targets markdown and ADF conversion
- Fuzzing → jira-core: hardens · Input fuzzing protects parser and transform boundaries