npm package: @specnote/cli
Description: CLI tool for SpecNote backend management
Author: Anderson D. Rosa
Latest version: 1.0.3

# SpecNote CLI

Interface de linha de comando para gerenciar o backend do SpecNote com suporte a múltiplos perfis de autenticação (Multi-Auth).

## 📚 Documentação

- [Autenticação e Perfis](./docs/auth-command.md) - Sistema completo de autenticação multi-perfis
- [Requisições HTTP](./docs/request-command.md) - Interface curl-like para API
- [Organizações](./docs/organizations-command.md) - Gerenciamento de empresas/clientes
- [Projetos](./docs/projects-command.md) - Gerenciamento de projetos
- [Escopos](./docs/scopes-command.md) - Escopos de trabalho e entregas
- [Aplicações](./docs/applications-command.md) - Aplicações e sistemas desenvolvidos
- [Tarefas](./docs/tasks-command.md) - Gerenciamento detalhado de tarefas
- [Requisitos](./docs/requirements-command.md) - Requisitos funcionais e não-funcionais
- [Guia Técnico](./docs/technical-guide.md) - Arquitetura e desenvolvimento

## 🚨 Mudanças Importantes (v1.0.2+)

### Melhorias Implementadas:
1. **Comandos modulares** - Comandos grandes divididos em subcomandos especializados
2. **Novo padrão de entrada** - `--data` para entrada JSON, `--json` apenas para formatação de saída
3. **SDK gerado automaticamente** - SDK TypeScript gerado a partir do OpenAPI do backend com nomes de métodos limpos
4. **Publicado no NPM** - Instalação global disponível como `@specnote/cli`
5. **Novo comando `request`** - Interface estilo curl para requisições HTTP com autenticação automática
6. **Filtro por organização** - Projetos, escopos e tarefas agora são filtrados automaticamente pela organização do token
7. **IDs nas tabelas** - Comandos `projects list` e `scopes list` agora mostram IDs truncados (8 dígitos)
8. **Filtro por escopo** - `tasks list --scope-id` aceita IDs parciais (8 dígitos) ou completos

### Correções:
- ✅ Compatibilidade com diferentes formatos de resposta (local vs produção)
- ✅ SDK com métodos nomeados corretamente (listTasks ao invés de getApiV1Tasks)
- ✅ Estrutura modular de comandos para melhor manutenibilidade
- ✅ Removido postinstall script para instalação global funcionar
- ✅ Segurança: usuários só veem dados da organização autenticada
- ✅ Filtro por scopeId em tasks funcionando corretamente

## Instalação

### Global (Recomendado)
```bash
npm install -g @specnote/cli
# ou
sudo npm install -g @specnote/cli
```

### Local (Para desenvolvimento)
```bash
cd packages/cli
pnpm install
pnpm build
```

## 🚀 Quick Start (Início Rápido)

```bash
# 1. Inicializar configuração
specnote init
# → Pergunta a URL da API (padrão: http://localhost:3000)
# → Pergunta o nome do perfil (padrão: default)

# 2. Fazer login
specnote auth login -e seu@email.com -p suasenha

# 3. Verificar se está funcionando
specnote auth me

# Pronto! Agora você pode usar todos os comandos
```

## Configuração Inicial

### Método 1: Usando o comando `init` (RECOMENDADO)

```bash
# Configuração interativa
specnote init
```

O comando `init` irá perguntar:
- URL da API (padrão: http://localhost:3000)
- Nome do perfil (padrão: default)
- Se deseja definir como perfil padrão

### Método 2: Configuração manual

```bash
# 1. Configurar URL da API
specnote config set --api-url http://localhost:3000 --profile dev
specnote config set --api-url https://api.specnote.com --profile prod

# 2. Fazer Login
specnote auth login -e usuario@example.com -p senha123

# Login com perfil específico (MUDOU!)
specnote auth login -e user@specnote.com -p senha --profile user
specnote auth login -e admin@specnote.com -p senha --profile admin
specnote auth login -e developer@specnote.com -p senha --profile dev
```

⚠️ **Nota**: O parâmetro mudou de `--save-as` para `--profile` para manter consistência

### ⚠️ Formatos de Data

Ao criar ou atualizar projetos, as datas devem estar no formato ISO 8601 completo:
- **Formato correto**: `2024-01-15T00:00:00Z`
- **Formato incorreto**: `2024-01-15` (causará erro de validação)

Exemplo:
```bash
# ✅ Correto
--start-date "2024-01-15T00:00:00Z"

# ❌ Incorreto
--start-date "2024-01-15"
```

### 3. Verificar Configuração

```bash
# Listar perfis disponíveis
specnote auth profiles

# Trocar perfil padrão
specnote auth use user

# Usar perfil temporário em comando
specnote --profile admin users list
```

## Comandos Disponíveis

### Inicialização (`init`)

```bash
# Configuração inicial interativa
specnote init

# Com parâmetros diretos
specnote init --url http://localhost:3000 --profile local
```

### Configuração (`config`)

```bash
# Definir URL da API
specnote config set --api-url http://localhost:3000/api/v1

# Configurar perfil específico
specnote config set --api-url http://localhost:3000/api/v1 --profile user
specnote config set --api-url https://api.specnote.com/v1 --profile production

# Mostrar configuração
specnote config show           # Mostra config do perfil ativo
specnote config show --all     # Mostra config de todos os perfis

# Limpar configuração
specnote config clear          # Com confirmação
specnote config clear --force  # Sem confirmação
specnote config clear --profile user  # Limpar perfil específico
specnote config clear --all    # Limpar todos os perfis
```

### Autenticação (`auth`)

Gerencia autenticação e múltiplos perfis. [Documentação completa →](./docs/auth-command.md)

```bash
# Login
specnote auth login -e email@example.com -p senha
specnote auth login -e email@example.com -p senha --profile admin

# Ver usuário e perfis
specnote auth me
specnote auth profiles
specnote auth use admin

# Logout
specnote auth logout
```

### Usuários (`users`)

```bash
# Operações básicas
specnote users list --search "john"
specnote users show <user-id>
specnote users create -n "Nome" -e "email@example.com" -p "password"
specnote users update <user-id> --active false
specnote users delete <user-id>
```

### Organizações (`organizations`)

Gerenciamento de empresas/clientes. [Documentação completa →](./docs/organizations-command.md)

```bash
# Listar e buscar
specnote organizations list
specnote orgs list --search "tech"

# Criar e gerenciar
specnote orgs create -n "Tech Corp" -s "tech-corp"
specnote orgs update <id> --website "https://tech.com"
specnote orgs delete <id>
```

### Requisitos (`requirements`)

Requisitos funcionais e não-funcionais. [Documentação completa →](./docs/requirements-command.md)

```bash
# Listar e buscar
specnote requirements list
specnote specs list                     # Alias
specnote specs list --type FUNCTIONAL
specnote specs list --priority HIGH

# Criar requisito
specnote specs create \
  --project-id <id> --code "RF001" \
  --title "Sistema de autenticação" \
  --type "FUNCTIONAL" --priority "HIGH"

# Atualizar e gerenciar
specnote specs update <id> --status APPROVED
specnote specs delete <id>
```

### Projetos (`projects`)

Gerenciamento de projetos. [Documentação completa →](./docs/projects-command.md)

```bash
# Operações básicas
specnote projects list --status ACTIVE
specnote proj show <project-id>
specnote proj create --organization-id <id> --name "Novo Projeto" --slug "novo-projeto"
specnote proj update <id> --budget 75000
specnote proj status <id> COMPLETED
specnote proj delete <id>
```

### Escopos (`scopes`)

```bash
# Operações básicas
specnote scopes list                          # Lista todos os escopos da organização
specnote scopes list --project-id <id>        # Filtra por projeto
specnote scopes list --json                   # Saída em JSON
specnote scope show <scope-id>
specnote scope create --project-id <id> --name "Autenticação" --original-price 12500
specnote scope close <id>
specnote scope deliver <id>
specnote scope stats

# Nota: A listagem agora mostra ID do escopo e ID do projeto (8 primeiros dígitos)
```

### Tarefas (`tasks`)

Gerenciamento de tarefas técnicas. [Documentação completa →](./docs/tasks-command.md)

```bash
# Listar e buscar
specnote tasks list
specnote tasks list --status IN_PROGRESS
specnote tasks list --scope-id <id>           # Filtra por escopo (aceita ID parcial de 8 dígitos)
specnote tasks list --project-id <id>         # Filtra por projeto
specnote tasks list --json                    # Saída em JSON
specnote tasks get TASK-001

# Criar tarefa
specnote tasks create \
  --project-id <id> --scope-id <id> --application-id <id> \
  --title "Implementar autenticação" \
  --complexity "MEDIUM" --estimated-hours 8

# Atualizar e gerenciar
specnote tasks update <task-id> --status COMPLETED
specnote tasks doc <task-id>
specnote tasks delete <task-id>
```

### Aplicações (`applications`)

Aplicações e sistemas desenvolvidos. [Documentação completa →](./docs/applications-command.md)

```bash
# Operações básicas
specnote applications list --type WEB
specnote apps show <id>
specnote apps create --project-id <id> --type WEB --name "Portal" --price 16000
specnote apps update <id> --status DEPLOYED
specnote apps delete <id>
```

### Requisições HTTP (`request`)

Interface estilo curl para requisições HTTP. [Documentação completa →](./docs/request-command.md)

```bash
# GET
specnote request /api/v1/users
specnote req /api/v1/users --json

# POST, PUT, DELETE
specnote req /api/v1/users --post -d '{"name":"João"}'
specnote req /api/v1/users/123 --put -d '{"active":false}'
specnote req /api/v1/users/123 --delete

# Com pipes
specnote req /api/v1/users --json | jq '.users | length'
```

## Modos de Uso

### Multi-Profile (Múltiplos Perfis)

O CLI permite trabalhar com vários perfis simultaneamente:

```bash
# Opção 1: Usar --profile em qualquer comando
specnote --profile user users list
specnote --profile admin users create ...

# Opção 2: Trocar perfil padrão
specnote auth use admin
specnote users list  # Usará perfil admin

# Opção 3: Scripts pré-configurados
pnpm sn:user users list
pnpm sn:admin users list

# Opção 4: Variável de ambiente
export SPECNOTE_PROFILE=production
specnote users list
```

### Modo Não-Interativo (Padrão)

Todos os comandos agora funcionam de forma não-interativa, recebendo parâmetros via linha de comando:

```bash
specnote users create \
  -n "João Silva" \
  -e "joao@example.com" \
  -p "senha123"
```

### Confirmações

Comandos destrutivos solicitam confirmação por padrão, mas podem ser executados com `--force`:

```bash
# Com confirmação
specnote users delete <id>
specnote config clear

# Sem confirmação
specnote users delete <id> --force
specnote config clear --force
```

## Desenvolvimento

Para informações sobre desenvolvimento, arquitetura e contribuição, consulte o [Guia Técnico](./docs/technical-guide.md).

### Quick Start

```bash
# Desenvolvimento local
pnpm cli <comando>

# Build
pnpm build

# Executar após build
pnpm specnote <comando>
```

## Troubleshooting

### Problemas Comuns

#### "Cannot connect to server"
```bash
# Verifique se o servidor está rodando
cd apps/backend
pnpm dev

# Em outro terminal, tente novamente
specnote auth me
```

#### "API endpoint not found" (404)
```bash
# Verifique a URL da API
specnote config show

# Se estiver errada, corrija:
specnote config set --api-url http://localhost:3000
```

#### "Authentication failed" (401)
```bash
# Suas credenciais estão incorretas
# Verifique email e senha e tente novamente
specnote auth login -e correto@email.com -p senhaCorreta
```

### Problemas com Perfis

#### "Profile not found" ou "No active profile"
```bash
# Ver quais perfis existem
specnote auth profiles

# Se nenhum perfil existe, fazer login
specnote auth login -e seu@email.com -p senha --profile default

# Se perfil existe mas não é o padrão
specnote auth use nome-do-perfil
```

#### "Token expired" ou erro 401
```bash
# Fazer login novamente no perfil problemático
specnote auth login -e seu@email.com -p senha --profile nome-do-perfil

# Ou logout e login
specnote auth logout --profile nome-do-perfil
specnote auth login -e seu@email.com -p senha --profile nome-do-perfil
```

#### Perfil usando API URL errada
```bash
# Verificar configuração do perfil
specnote auth profiles

# Corrigir URL da API
specnote config set --api-url http://localhost:3000/api/v1 --profile nome-do-perfil

# Ou fazer login novamente com URL correta
specnote config set --api-url http://localhost:3000/api/v1 --profile nome-do-perfil
specnote auth login -e seu@email.com -p senha --profile nome-do-perfil
```

#### Múltiplos perfis confusos
```bash
# Ver qual perfil está ativo
specnote auth current

# Ver todos os perfis e suas configurações
specnote auth profiles

# Limpar perfil problemático
specnote auth remove-profile nome-problemático

# Resetar completamente (CUIDADO!)
specnote config clear --all
rm -rf ~/.specnote-cli
```

### Problemas Gerais

#### Erro de autenticação
```bash
# Verificar se o token não expirou
specnote auth me

# Se não funcionar, fazer login novamente
specnote auth login -e seu@email.com -p senha
```

#### Comando não funciona
```bash
# Verificar se API URL está correta
specnote config show

# Testar conectividade com debug
specnote --debug auth me

# Usar perfil específico para testar
specnote --profile nome-do-perfil auth me
```

#### Limpar configuração
```bash
# Limpar apenas configuração (mantém perfis)
specnote config clear

# Limpar tudo (remove todos os perfis)
specnote config clear --all
rm -rf ~/.specnote-cli
```

## Sistema Multi-Perfis

O CLI suporta múltiplos perfis para trabalhar com diferentes usuários e ambientes. [Documentação completa →](./docs/auth-command.md#sistema-multi-auth-múltiplos-perfis)

### Configuração Rápida

```bash
# 1. Login com perfis nomeados
specnote auth login -e admin@company.com -p senha --profile admin
specnote auth login -e dev@company.com -p senha --profile dev

# 2. Usar perfis
specnote --profile admin users list
specnote auth use dev
export SPECNOTE_PROFILE=prod
```

### Suporte a JSON (--json)

Todos os comandos de criação e atualização suportam entrada via JSON através do stdin:

```bash
# Criar usuário via JSON
echo '{
  "name": "Maria Santos",
  "email": "maria@example.com", 
  "password": "senha123"
}' | specnote users create --json

# Atualizar com JSON (CLI options têm prioridade)
echo '{"name": "Novo Nome"}' | specnote users update <id> --json --active false

# Criar usuário via arquivo JSON
cat user.json | specnote users create --json
```

### Modo Debug (--debug)

Adicione `--debug` a qualquer comando para habilitar o modo debug:

```bash
# Ativa o header X-Debug-Mode em todas as requisições
specnote --debug users create ...
specnote --debug users list

# Funciona com JSON também
echo '{}' | specnote --debug users update <id> --json
```

## Exemplos de Uso

### Fluxo completo de gerenciamento de usuários

```bash
# 1. Login como admin
specnote auth login -e admin@specnote.com -p senha --profile admin

# 2. Criar usuário (usando perfil admin)
specnote --profile admin users create \
  -n "Maria Silva" \
  -e "maria@example.com" \
  -p "senha123"

# 3. Verificar criação
specnote --profile admin users list | grep Maria

# 4. Ver detalhes
specnote --profile admin users show <user-id>
```

### Gerenciamento de Organizações

```bash
# 1. Criar uma organização
specnote organizations create \
  -n "Tech Solutions" \
  -s "tech-solutions" \
  -d "Empresa de desenvolvimento de software" \
  -w "https://techsolutions.com"

# 2. Listar organizações que você tem acesso
specnote organizations list

# 3. Ver detalhes completos
specnote organizations show <org-id>

# 4. Atualizar informações
specnote organizations update <org-id> \
  --contact-email "contato@techsolutions.com" \
  --contact-phone "+55 11 99999-9999"

# 5. Usar JSON para criar organização
echo '{
  "name": "Nova Empresa",
  "slug": "nova-empresa",
  "description": "Descrição da empresa",
  "website": "https://nova-empresa.com"
}' | specnote organizations create --json
```

### Gerenciamento de Requisitos

```bash
# 1. Listar todos os requisitos de um projeto
specnote requirements list --project-id <project-id>

# 2. Criar requisito funcional
specnote requirements create \
  --project-id <project-id> \
  --code "RF001" \
  --title "Sistema de autenticação" \
  --description "O sistema deve permitir login com email e senha" \
  --type "FUNCTIONAL" \
  --priority "HIGH"

# 3. Criar requisito não-funcional
specnote requirements create \
  --project-id <project-id> \
  --code "RNF001" \
  --title "Performance de carregamento" \
  --description "A página deve carregar em menos de 2 segundos" \
  --type "NON_FUNCTIONAL" \
  --priority "MEDIUM"

# 4. Filtrar requisitos por tipo e prioridade
specnote requirements list \
  --project-id <project-id> \
  --type "FUNCTIONAL" \
  --priority "HIGH"

# 5. Atualizar prioridade de um requisito
specnote requirements update <requirement-id> --priority "URGENT"

# 6. Ver detalhes completos de um requisito
specnote requirements get <requirement-id>

# 7. Criar múltiplos requisitos via JSON
echo '{
  "projectId": "<project-id>",
  "code": "RF002",
  "title": "Sistema de cadastro",
  "description": "O sistema deve permitir cadastro de novos usuários",
  "type": "FUNCTIONAL",
  "priority": "HIGH"
}' | specnote requirements create --json

# 8. Buscar requisitos por termo
specnote requirements list --search "autenticação"
```

### Trabalhar com Múltiplos Perfis

```bash
# Configurar perfis
specnote auth login -e user@specnote.com -p senha --profile user
specnote auth login -e admin@specnote.com -p senha --profile admin

# User: Ver seus próprios dados
specnote --profile user auth me

# Admin: Gerenciar usuários
specnote --profile admin users list
specnote --profile admin users create ...

# Scripts rápidos
pnpm sn:admin users list
pnpm sn:user auth me
pnpm sn:admin requirements list
pnpm sn:admin requirements create --project-id <id> --code RF001 --title "Test" --description "Test req" --type FUNCTIONAL
```

### Documentar Tarefas com Markdown

```bash
# 1. Listar tarefas com IDs completos
specnote tasks list --full-id

# 2. Buscar ID pelo código da task
specnote tasks get-id TASK-001
# Output: 02d3f230-6461-446f-85f0-a27aaeae123d

# 3. Adicionar documentação de arquivo
specnote tasks update-doc 02d3f230-6461-446f-85f0-a27aaeae123d --file docs/task-001.md

# 4. Adicionar documentação via editor
specnote tasks update-doc TASK-001

# 5. Ver documentação
specnote tasks doc TASK-001

# 6. Pipeline com markdown
cat <<EOF | specnote tasks update-doc TASK-001 --stdin
# Documentação da Task

## Visão Geral
Esta task implementa a funcionalidade X

## Detalhes Técnicos
- Tecnologia: React + TypeScript
- Padrão: Repository Pattern
- Testes: Jest + Testing Library

## Estimativas
- Backend: 8h
- Frontend: 8h
- Total: 16h
EOF
```

### Usar JSON para automação

```bash
# Script para criar múltiplos usuários
for i in {1..5}; do
  echo "{
    \"name\": \"User $i\",
    \"email\": \"user$i@example.com\",
    \"password\": \"senha123\"
  }" | specnote users create --json
done

# Pipeline com jq
cat users.json | jq -c '.[]' | while read item; do
  echo "$item" | specnote users create --json
done
```

### Debug Mode para troubleshooting

```bash
# Ver logs detalhados de uma operação
specnote --debug users create \
  -n "Debug User" \
  -e "debug@example.com" \
  -p "senha123"

# Combinar debug com JSON
echo '{"name": "Updated Name"}' | specnote --debug users update <id> --json
```


## Futuros Comandos (Roadmap)

### Apps (`apps`)
- `specnote apps list` - Listar aplicações do projeto
- `specnote apps create` - Criar nova aplicação
- `specnote apps update <id>` - Atualizar aplicação

### Packages (`packages`)
- `specnote packages list` - Listar pacotes do projeto
- `specnote packages create` - Criar novo pacote
- `specnote packages update <id>` - Atualizar pacote

### Expertise (`expertise`)
- `specnote expertise list` - Listar especialidades da organização
- `specnote expertise create` - Criar nova especialidade

### Análise de Valor (`value-analysis`)
- `specnote analysis create` - Criar análise de valor
- `specnote analysis list` - Listar análises
- `specnote analysis show <id>` - Ver detalhes da análise
- `specnote analysis report <id>` - Gerar relatório de ROI