Metadata-Version: 2.4
Name: spectryn
Version: 1.0.0
Summary: A production-grade CLI tool for synchronizing markdown specifications with issue trackers
Author-email: Adrian Darian <adrian.the.hactus@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/adriandarian/spectryn
Project-URL: Documentation, https://github.com/adriandarian/spectryn#readme
Project-URL: Repository, https://github.com/adriandarian/spectryn.git
Project-URL: Issues, https://github.com/adriandarian/spectryn/issues
Project-URL: Changelog, https://github.com/adriandarian/spectryn/blob/main/CHANGELOG.md
Keywords: jira,github,azure-devops,linear,markdown,sync,issue-tracker,agile,project-management,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Bug Tracking
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: async
Requires-Dist: aiohttp>=3.8.0; extra == "async"
Provides-Extra: redis
Requires-Dist: redis>=4.5.0; extra == "redis"
Provides-Extra: gitlab
Requires-Dist: python-gitlab>=4.0.0; extra == "gitlab"
Provides-Extra: bitbucket
Requires-Dist: atlassian-python-api>=3.0.0; extra == "bitbucket"
Provides-Extra: telemetry
Requires-Dist: opentelemetry-api>=1.20.0; extra == "telemetry"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "telemetry"
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "telemetry"
Requires-Dist: opentelemetry-exporter-prometheus>=0.41b0; extra == "telemetry"
Provides-Extra: prometheus
Requires-Dist: prometheus_client>=0.17.0; extra == "prometheus"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.5.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.3.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Requires-Dist: mutmut>=2.4; extra == "dev"
Requires-Dist: aiohttp>=3.8.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Requires-Dist: redis>=4.5.0; extra == "dev"
Requires-Dist: types-redis>=4.5.0; extra == "dev"
Provides-Extra: all
Requires-Dist: aiohttp>=3.8.0; extra == "all"
Requires-Dist: redis>=4.5.0; extra == "all"
Requires-Dist: python-gitlab>=4.0.0; extra == "all"
Requires-Dist: atlassian-python-api>=3.0.0; extra == "all"
Requires-Dist: opentelemetry-api>=1.20.0; extra == "all"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "all"
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "all"
Requires-Dist: opentelemetry-exporter-prometheus>=0.41b0; extra == "all"
Requires-Dist: prometheus_client>=0.17.0; extra == "all"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Provides-Extra: tui
Requires-Dist: textual>=0.85.0; extra == "tui"
Dynamic: license-file

# spectryn

<div align="center">

[![CI](https://github.com/adriandarian/spectryn/actions/workflows/pr.yml/badge.svg)](https://github.com/adriandarian/spectryn/actions/workflows/pr.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

**The Universal Bridge between Product Specifications and Issue Trackers**

*Synchronize Markdown, YAML, JSON, and Notion specs with Jira, GitHub, Linear, Azure DevOps, Asana, GitLab, Trello, Monday.com, Shortcut, ClickUp, Bitbucket, YouTrack, and Confluence*

[Core Features](#-core-features) •
[Installation](#-installation) •
[Quick Start](#-quick-start) •
[Supported Platforms](#-supported-platforms) •
[AI-Assisted Sync](#-ai-assisted-sync) •
[Architecture](#-architecture)

</div>

---

## 🚀 Overview

**spectryn** is a production-grade CLI tool designed to eliminate the gap between product documentation and issue tracking. It allows teams to maintain their product specifications as "Docs-as-Code" while keeping project management tools perfectly in sync.

Whether you write stories in Markdown, manage roadmaps in YAML, or organize features in Notion, **spectryn** provides a unified command-line interface to synchronize them across multiple enterprise trackers.

---

## ✨ Core Features

- 🔄 **Universal Sync** - Multi-platform support for Jira, GitHub, Linear, Azure DevOps, Asana, GitLab, Trello, Monday.com, Shortcut, ClickUp, Bitbucket, YouTrack, and Confluence.
- 📝 **Rich Input Formats** - Support for Markdown, YAML, TOML, JSON, CSV, and even Notion.
- 🤖 **AI-Assisted Fixing** - Intelligent validation and auto-fixing of specifications using Claude, Ollama, or Aider.
- 🛡️ **Safe by Design** - Mandatory dry-runs, detailed diff previews, and automatic backups.
- ⚡ **Developer Experience** - Watch mode, shell completions, and TUI dashboards.
- 📊 **Enterprise Readiness** - Audit trails, OpenTelemetry tracing, and conflict detection.

---

## 🛠 Supported Platforms

| **Inputs (Parsers)** | **Outputs (Trackers)** |
|:--- |:--- |
| ✅ **Markdown** (Standard & GFM) | ✅ **Jira** (Cloud & Data Center) |
| ✅ **YAML** | ✅ **GitHub Issues** |
| ✅ **TOML** | ✅ **Linear** |
| ✅ **JSON** | ✅ **Azure DevOps** |
| ✅ **CSV/Excel** | ✅ **Confluence** |
| ✅ **AsciiDoc** | ✅ **Asana** |
| ✅ **Notion** | ✅ **GitLab** |
| ✅ **TOON** | ✅ **Trello** |
|  | ✅ **Monday.com** |
|  | ✅ **Shortcut** |
|  | ✅ **ClickUp** |
|  | ✅ **Bitbucket** |
|  | ✅ **YouTrack** |

---

## 📦 Installation

### Using pipx (Recommended)
```bash
pipx install spectryn
```

### Using Homebrew (macOS/Linux)
```bash
brew tap adriandarian/spectra https://github.com/adriandarian/spectra
brew install spectra
```

### From Source
```bash
git clone https://github.com/adriandarian/spectryn.git
cd spectryn
pip install -e ".[dev]"
```

---

## 🏁 Quick Start

### 1. Configure your environment
Create a `.spectryn.yaml` file in your project root:

```yaml
# Tracker Configuration
jira:
  url: https://your-company.atlassian.net
  email: your-email@company.com
  api_token: your-api-token
  project: PROJ

# Sync Preferences
sync:
  execute: false      # Dry-run by default
  no_confirm: false   # Ask for confirmation
  backup_enabled: true
```

### 2. Validate your specifications
Check your markdown or YAML file for formatting issues:

```bash
spectryn --validate --markdown EPIC.md
```

### 3. Synchronize
Preview the changes (dry-run) and then execute when ready:

```bash
# Preview changes
spectryn --markdown EPIC.md --epic PROJ-123

# Execute sync
spectryn --markdown EPIC.md --epic PROJ-123 --execute
```

---

## 🤖 AI-Assisted Sync

**spectryn** integrates with modern LLMs to help you maintain high-quality specifications.

- **Auto-Fix**: Automatically correct formatting errors in your markdown.
- **Guided Generation**: Generate new epic templates from existing tracker data.
- **Smart Matching**: Fuzzy title matching to connect local specs with remote issues.

```bash
# Detect available AI tools
spectryn --list-ai-tools

# Auto-fix markdown formatting
spectryn --validate --markdown EPIC.md --auto-fix --ai-tool claude
```

---

## 🏗 Architecture

Built on **Clean Architecture** principles, spectryn ensures maximum extensibility through its Ports-and-Adapters (Hexagonal) design.

```text
src/spectryn/
├── core/           # Domain Layer (Entities, Enums, Ports)
├── adapters/       # Infrastructure (Parsers, API Clients, Trackers)
├── application/    # Use Cases (Sync Orchestration, Command Handlers)
└── cli/            # Interface (Commands, TUI, Output Formatting)
```

- **Ports & Adapters**: Core logic remains agnostic of external platforms.
- **Command Pattern**: Every write operation is recorded for auditability and rollback.
- **Domain-Driven**: Rich entities like `UserStory` and `Epic` encapsulate business rules.

---

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on our development workflow and standards.

```bash
# Run quality checks before submitting
ruff format src tests && ruff check src tests --fix && mypy src/spectryn && pytest
```

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

<div align="center">
Made with ❤️ by <a href="https://github.com/adriandarian">Adrian Darian</a>
</div>
