Jira Assistant (jra)

CLI para gerenciar e listar tarefas no Jira diretamente no seu terminal, com suporte robusto para API Token e OAuth 2.0.

🚀 Instalação

Certifique-se de que possui o Node.js instalado (v18+ recomendado).

# Clone ou acesse o diretório do repositório
cd jira-assistant

# Instale as dependências
npm install

# Instale a CLI globalmente
npm link

🔐 Configuração de Autenticação

A CLI suporta dois métodos distintos e completamente separados de autenticação. Escolha o que melhor se adaptar ao seu cenário:

Opção 1: API Token (Recomendado para uso Pessoal Simples)

O método de API Token utiliza o modelo de Basic Auth estático (usa o seu email normal + um token longo gerado no painel da conta).

Como obter as credenciais:

1. Acesse: Atlassian API Tokens.
2. Clique em Create API token.
3. Escolha um nome para identificar (ex: cli-jra) e copie a chave gerada.

Como configurar na CLI: Execute o comando de configuração wizard:

jra config

Ele lhe perguntará preenchendo as chaves:

• Email Jira: Seu email de acesso atual à Atlassian.
• API Token Jira: A chave de segurança que você acabou de gerar.
• Domain Jira: A sua URL base (ex: sua-empresa.atlassian.net).

Opção 2: OAuth 2.0 (Recomendado para Integrações de Terceiros)

O OAuth 2.0 é um sistema baseado em autorização na web. Utiliza tokens dinâmicos que se renovam automaticamente e interagem através de um "Aplicativo Terceiro" configurado.

Como obter Client ID e Client Secret: Para que esse fluxo funcione, você precisará ter um App registrado na modalidade "OAuth 2.0 (3LO)".

1. Acesse o Atlassian Developer Console.
2. Clique em Create -> OAuth 2.0 integration.
3. Dê um nome ao seu novo aplicativo CLI, aceite os termos e cliquem em criar.
4. No menu lateral esquerdo, acesse a aba Permissions e clique em "Add" na lacuna correspondente a Jira API.
5. Na listagem de "Jira API", clique em Configure, e em seguida vá na tab "Classic Scopes". Adicione no mínimo as permissões base:
   • read:jira-work
   • write:jira-work
6. Retorne ao menu lateral e acesse Authorization (provavelmente listado sob o próprio painel OAuth 2.0).
7. Encontre o campo de URL chamado Callback URL. Você precisará digitar/colar a porta local embutida no projeto e salvar as mudanças. Defina EXATAMENTE este valor: 👉 http://localhost:3000/callback
8. Pronto! Agora vá no menu lateral esquerdo em Settings. Lá estarão os seus Client ID e Client Secret. Copie e não os compartilhe!

Como configurar na CLI: Inicie o processo de login digitando o comando:

jra login

Ele fará uma bateria de perguntas interativas via prompt pedindo o seu Client ID e seu Secret. Logo após confirmar, subirá o concentimento da web.

Dica: Para não ter que ficar colando toda hora, você pode adicionar variáveis no seu ~/.bashrc ou terminal (ex: export JIRA_CLIENT_ID="..." e export JIRA_CLIENT_SECRET="..."). O script puxa de lá de forma inteligente.

📋 Comandos Disponíveis (jra)

Aqui estão todos os comandos utilitários que você pode aplicar no seu dia-a-dia a partir do momento em que estiver logado em um de seus apps:

• jra list O que faz: Printa no terminal as tarefas que não estão finalizadas e que têm você como responsável ativo no Board. O retorno é uma tabela organizada filtrando por status e prioridades (High/Medium/Low).

• jra start <PROJ-213> O que faz: Altera instantaneamente a tarefa selecionada para o estágio inicial da sua organização (como In Progress ou Em Desenvolvimento). Logo em sequência o conteúdo/descrição completa do ticket JIRA será imediatamente copiado pro teclado Clipboard (Ctrl+C) da sua estação de trabalho (sem precisar sequer abrir o navegador)!

• jra finish <PROJ-213> O que faz: Ferramenta inteligente de entrega do card! Busca ativamente pela sua coluna de revisão (ex: Code Review) e te dá a opção expressa de jogar a task direto para lá com um único "Yes". Se a coluna não existir (ou se apertar "No"), ele te apresenta a lista de transições normal para você escolher o destino do ticket.

• jra status <PROJ-213> O que faz: Puxa os status lógicos criados para ser transicionados na coluna daquele ticket específico. A CLI abrirá uma lista interativa onde usando as setas do seu teclado você navega por "Code Review", "Done", "Homolog", "Testing" e os injeta instantaneamente.

• jra config O que faz: Wizard auxiliar puramente focado em salvar novas instâncias de Email e senha em API Tokens.

• jra login O que faz: Wizard focado puramente na injeção de consentimentos OAuth 2.0 (abertura do browser local).

• jra profile <ação> [nome] O que faz: Permite separar o Jira em múltiplas contas e workspaces!

  • list: Lista todos os perfis contidos na máquina e mostra o ativo.
  • add <nome>: Cria um perfil novo (ex: jra profile add empresa) e o seleciona.
  • use <nome>: Alterna instantaneamente de perfil.
  • remove <nome>: Apaga dados do perfil.

• jra desc <PROJ-213> O que faz: Busca apenas o título e a descrição do ticket e os copia silenciosamente no seu teclado (Clipboard), para facilitar seu workflow de leitura sem abrir o site. Semelhante ao comando start, porém sem transição de status.

• jra help O que faz: Invoca a documentação básica com os subcomandos na tela.