Ticketron (tix)

Ticketron (tix)

LLM を活用した、JIRA 用のスマートなコマンドラインヘルパーです。

概要

Ticketron（tix）を使えば、コマンドラインから JIRA を直接操作できます。jira-mcp-server と OpenAI を介して大規模言語モデル（LLM）の能力を活用し、自然言語または簡潔なコマンドで JIRA チケットを作成、検索できます。主な目的は、関連するコンテキストを自動的に追加し、チケット管理をより迅速かつ直感的にすることで、ワークフローを効率化することです。

機能

• 自然言語で JIRA イシューを作成（tix create ...）
• JQL で JIRA イシューを検索（tix search ...）
• LLM によるコンテキストに応じたチケット生成（OpenAI を使用）
• 設定管理（tix config init|show|locate|set-key）
• API キーの安全な保存（OS のキーチェーンまたは環境変数）
• LLM コンテキストの管理（tix context show|edit|add）
• シェル補完に対応（Bash、Zsh、Fish、PowerShell）
• 構造化出力形式（JSON、YAML、TSV）
• デバッグを容易にする構造化ログ

インストール

前提条件

• Go： バージョン 1.23.8 以降。
• jira-mcp-server： jira-mcp-server の稼働中のインスタンスへのアクセス（JIRA との通信に必要）。
• OpenAI API キー： LLM 機能に必要です。
• Make： 開発作業（ビルド、テスト、リンティング）に必要です。

インストールコマンド

go install github.com/karolswdev/ticketron/cmd/tix@latest

$GOPATH/bin または $HOME/go/bin が PATH に含まれていることを確認してください。

シェル補完

tix は Bash、Zsh、Fish、PowerShell 用のシェル補完スクリプトの生成に対応しています。

お使いのシェル用のスクリプトを生成するには、completion コマンドを使用します。

# For Bash
tix completion bash

# For Zsh
tix completion zsh

# For Fish
tix completion fish

# For PowerShell
tix completion powershell

コマンドの出力に表示される手順に従って、現在のセッションで補完を読み込むか、自動的に読み込まれるよう設定してください。

Bash の例（~/.bashrc または ~/.bash_profile に追加）：

source <(tix completion bash)

Zsh の例（~/.zshrc に追加）：

# Ensure compinit is loaded
autoload -U compinit; compinit

# Load completions
source <(tix completion zsh)

お使いの環境に最適な設定手順については、tix completion [your-shell] の出力を参照してください。

クイックスタート

1. tix をインストールします：

   go install github.com/karolswdev/ticketron/cmd/tix@latest
   

   （$GOPATH/bin または $HOME/go/bin が PATH に含まれていることを確認してください）

2. 設定を初期化します：

   tix config init
   

   （デフォルトファイルを含む ~/.ticketron/ を作成します。mcp_server.url を設定するには、~/.ticketron/config.yaml を編集してください。）

3. OpenAI API キーを設定します：

   # 推奨：OS のキーチェーンを使用
   tix config set-key <your-openai-api-key>
   
   # 代替方法：環境変数を使用
   # export TICKETRON_LLM_API_KEY="<your-openai-api-key>"
   

4. 最初のチケットを作成します：

   # 例：バグ報告を作成（説明が指定されている場合は LLM を使用）
   tix create bug "Login button unresponsive" --description "When clicking the login button on the main page, nothing happens. Check console logs."
   

設定

Ticketron では、~/.ticketron/ に保存される設定ファイルが必要です。以下を使用して、デフォルトの設定ディレクトリとテンプレートファイルを初期化できます。

tix config init

このコマンドは、~/.ticketron/ ディレクトリが存在しない場合は作成し、デフォルトのテンプレートファイル（config.yaml、links.yaml、system_prompt.txt、context.md）を配置します。API キーの設定は行いません。

OpenAI API Key

LLM 機能には OpenAI API キーが必要です。セキュリティ上の理由から、別途設定する必要があります。次の 2 つの方法があります。

1. 推奨：OS のキーチェーンを使用する：

   tix config set-key <your-openai-api-key>
   

   このコマンドは、キーをオペレーティングシステムのキーチェーンに安全に保存します。ticketron はそこから自動的に取得します。

2. 代替方法：環境変数： TICKETRON_LLM_API_KEY 環境変数を設定します。

   export TICKETRON_LLM_API_KEY="<your-openai-api-key>"
   

   キーチェーンにキーが見つからない場合、アプリケーションはこの変数を使用します。

設定ファイル

~/.ticketron/ にある主な設定ファイル：

• config.yaml：メイン設定。
  • mcp_server.url：実行中の jira-mcp-server の URL。
  • デフォルトのプロジェクト、課題タイプ、ログレベルなどのその他の設定。
  • 注： openai.api_key はここには保存されなくなりました。
• links.yaml：プロジェクトの短縮エイリアスを、完全な JIRA プロジェクトキーおよびデフォルトの課題タイプに対応付けます。
  • 例：

    links:
      - name: WEB
        key: WEBPROJECT
        default_issue_type: Story
      - name: API
        key: BACKENDAPI
        default_issue_type: Task
      - name: DS
        key: DATASCIENCE
        default_issue_type: Bug
    

• system_prompt.txt：チケット作成時に LLM に指示するためのシステムプロンプトが含まれています。LLM の動作を調整するには、このファイルを変更してください。
• context.md：プロジェクト、チーム、一般的なチケットのパターンに関する永続的なコンテキストを LLM に提供します。

tix config show を使用して現在の設定（API キーを除く）を表示し、tix config locate を使用して設定ディレクトリを確認します。

基本的な使い方

tix --version を使用してアプリケーションのバージョンを表示します。

チケットの作成

# Create a bug with a simple title
tix create bug "Login fails on checkout page"

# Create a story for a specific project (using alias from links.yaml)
tix create --type Story --project WEB "Implement new user profile page design"

# Create a task with more detail (will be processed by LLM)
tix create task "Refactor auth module to use JWT" --description "The current session management is outdated. We need to switch to JWT for better security and scalability. Update login, logout, and token refresh endpoints."

# Create a ticket interactively (prompts for confirmation before sending)
tix create -i bug "UI glitch on settings page"

# Create a ticket and output the result as JSON
tix create task "Setup CI pipeline" -o json

チケットの検索

# Search using natural language (processed by LLM to generate JQL)
tix search "my open bugs in the WEB project"

# Search using explicit JQL
tix search --jql "project = WEB AND status = 'In Progress' ORDER BY created DESC"

# Search for unresolved tickets assigned to you
tix search --jql "assignee = currentUser() AND resolution = Unresolved"

# Search for tickets and output results as JSON
tix search "my open tasks" -o json
# Search and output specific fields as JSON
tix search "status = Done" -o json -f key,fields.summary,fields.status.name

# Search and output results as YAML
tix search "my open tasks" -o yaml

# Search and output results as TSV (Tab-Separated Values)
tix search "project = API" -o tsv

# Search and output specific fields as TSV
tix search "project = API" -o tsv -f key,fields.issuetype.name,fields.summary

設定の管理

# Initialize configuration files
tix config init

# Show current configuration values
tix config show

# Show the location of the configuration directory
tix config locate

# Securely set the OpenAI API key in the OS keychain
tix config set-key <your-openai-api-key>

LLM コンテキストの管理

context.md ファイルは、LLM に永続的なコンテキストを提供します。tix context コマンドを使用して、このファイルを管理できます。

# Show the current content of the context file
tix context show

# Open the context file in your default editor ($EDITOR)
tix context edit

# Add a new line of text to the context file
tix context add "Remember to always include the component name in bug reports."

開発

このプロジェクトでは、一般的な開発タスクを効率化するために Makefile を使用しています。make がインストールされていることを確認してください。

• ビルド： tix バイナリをコンパイルします。

  make build
  

• テスト： 単体テストと統合テストを実行します。

  make test
  

• Lint： Go リンター（golangci-lint）を実行します。

  make lint
  

• フォーマット： gofmt を使用して Go ソースコードをフォーマットします。

  make fmt
  

• すべてのチェック： フォーマット、Lint、テストのターゲットを実行します。

  make check
  

その他の利用可能なターゲットについては、Makefile を参照してください。

コントリビューション

このプロジェクトは Contributor Code of Conduct に基づいて公開されています。このプロジェクトに参加することで、その規約に従うことに同意したものとみなされます。

コントリビューション方法の詳細については、CONTRIBUTING.md を参照してください。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については LICENSE ファイルを参照してください。