trello-cli-unofficial 0.13.13 → 0.14.0

package/README.md

@@ -8,788 +8,48 @@
 [![CI/CD](https://img.shields.io/github/actions/workflow/status/JaegerCaiser/trello-cli-unofficial/ci.yml?branch=main&label=CI)](https://github.com/JaegerCaiser/trello-cli-unofficial/actions)
 [![Release](https://img.shields.io/github/actions/workflow/status/JaegerCaiser/trello-cli-unofficial/release.yml?branch=main&label=Release)](https://github.com/JaegerCaiser/trello-cli-unofficial/actions)
 
-An unofficial Trello CLI using Power-Up authentication, built with Bun for maximum performance. Features automated dependency management with Bun installation during setup.
+Um CLI não-oficial para Trello com autenticação Power-Up, feito em Bun e TypeScript. Permite gerenciar boards, lists e cards com saídas modernas e suporte a múltiplos perfis.
 
-## 🚀 Features
-
-- ⚡ **Ultra-fast**: Built with Bun (10-50x faster than Node.js)
-- 🔐 **Power-Up Authentication**: Compatible with Trello's newer authentication system
-- 💾 **Persistent Configuration**: Automatically saves your token
-- 🎯 **Interactive Interface**: Intuitive menu with interactive prompts
-- 📋 **Complete Management**: Boards, lists, cards with detailed information
-- ✏️ **CRUD Operations**: Create, read, update, and delete cards
-- 📦 **Move Cards**: Between lists in the same board
-- 👀 **Detailed Views**: Show comprehensive board and card details
-- 📊 **Multiple Output Formats**: Table, JSON, CSV formats
-- 🏷️ **Rich Metadata**: Labels, members, checklists, and attachments support
-- 🛠️ **Traditional CLI**: Also works as a command-line tool
-- 🌍 **Internationalization**: Support for Portuguese (pt-BR) and English (en) with auto-detection
-- 🤖 **Automated CI/CD**: Semantic versioning and NPM publishing on every release
-- 🧪 **Quality Gates**: 95% test coverage threshold enforced in CI/CD
-- 🔐 **Secure Publishing**: NPM provenance with GitHub Actions OIDC
-
-## 📦 Installation
-
-### Prerequisites
-
-- **[Node.js 16+](https://nodejs.org/) (Required)**
-- **[Bun](https://bun.sh/) (Required)** - Deve ser instalado separadamente
-- Trello account with Power-Up enabled
-- **Supported Platforms:** Linux, macOS, Windows
-
-### NPM Installation (Recommended)
-
-O CLI requer Bun para funcionar. Instale-o primeiro:
+## Quick Start
 
 ```bash
-# 1. Instale o Bun primeiro
-curl -fsSL https://bun.sh/install | bash
-# ou no Windows: powershell -c "irm bun.sh/install.ps1 | iex"
-
-# 2. Instale o CLI
 npm install -g trello-cli-unofficial
-
-# 3. Use
-tcu --version
-```
-
-**Ready to use immediately!**
-
-`tcu --version`
-
-#### Windows Installation
-
-Para usuários Windows, primeiro instale o Bun, depois o CLI:
-
-```powershell
-# 1. Instale o Bun
-powershell -c "irm bun.sh/install.ps1 | iex"
-
-# 2. Instale o CLI
-npm install -g trello-cli-unofficial
-
-# 3. Use
-tcu --version
 ```
 
-**Nota:** No Windows, você pode precisar reiniciar o terminal após instalar o Bun.
-
-### Manual Installation (Development)
-
-```bash
-# Clone the repository
-git clone https://github.com/JaegerCaiser/trello-cli-unofficial.git
-cd trello-cli-unofficial
-
-# Install dependencies
-bun install
-
-# Install globally (optional)
-bun link
-```
-
-## 🔧 Configuration
-
-### First Run Setup
-
-On first run, the CLI will guide you through setup:
-
-```bash
-# Run the CLI
-tcu
-
-# Or if running from source
-bun run main.ts
-```
-
-The CLI will ask for your Trello token. To get it:
-
-1. Go to [https://trello.com/power-ups/admin](https://trello.com/power-ups/admin)
-2. Create a new Power-Up or use an existing one
-3. Copy the "API Key" and generate a token
-4. Paste the token when prompted (starts with `ATTA...`)
-
-### Manual Configuration
-
 ```bash
-# Configure token interactively
 tcu setup
-
-# View current configuration
-tcu config
-```
-
-### Configuration File
-
-The token is automatically saved in `~/.trello-cli-unofficial/config.json`:
-
-```json
-{
-  "apiKey": "630a01228b85df706aa520f3611e6490",
-  "token": "ATTA..."
-}
-```
-
-### Environment Variables
-
-You can configure the CLI using environment variables instead of the configuration file:
-
-```bash
-# Copy the example file
-cp .env.example .env
-
-# Edit with your credentials
-nano .env
-```
-
-Available environment variables:
-
-- `TRELLO_API_KEY`: Your Trello API key (optional, defaults to built-in key)
-- `TRELLO_TOKEN`: Your Trello token (optional, will be prompted if not set)
-
-Example `.env` file:
-
-```bash
-# Trello CLI Unofficial - Environment Variables
-TRELLO_TOKEN=ATTA...
-TRELLO_API_KEY=your-custom-api-key
-```
-
-**Security Note**: Never commit your `.env` file to version control. The `.env.example` file contains safe defaults.
-
-## Internationalization (i18n)
-
-The CLI automatically detects your system language and displays messages in the appropriate language.
-
-### Supported Languages
-
-- 🇧🇷 **Portuguese (pt-BR)** - Default for Portuguese-speaking systems
-- 🇺🇸 **English (en)** - Default for other systems
-
-### Language Detection
-
-The language is automatically detected from your system's `LANG` environment variable:
-
-```bash
-# Force Portuguese
-LANG=pt_BR.UTF-8 tcu
-
-# Force English
-LANG=en_US.UTF-8 tcu
-```
-
-### Manual Language Switching
-
-```typescript
-import { changeLanguage } from "trello-cli-unofficial";
-
-// Switch to Portuguese
-changeLanguage("pt-BR");
-
-// Switch to English
-changeLanguage("en");
-```
-
-## 📖 Usage
-
-### Interactive Mode (Recommended)
-
-```bash
-# Start interactive mode
-tcu
-
-# Or the full command name
-trello-cli-unofficial
-```
-
-Main menu options:
-
-- 📋 View my boards
-- 📝 Explore board
-- ➕ Create card
-- ⚙️ Settings
-- 🚪 Exit
-
-### Direct Commands
-
-```bash
-# View all boards
-tcu boards list
-
-# Show detailed board information
-tcu boards show <boardId>
-
-# View lists in a board
-tcu lists list <boardId>
-
-# View cards in a list
-tcu cards list <listId>
-
-# Show detailed card information
-tcu cards show <cardId>
-
-# Create a new card
-tcu cards create <listId> <name> [--desc "description"]
-
-# Update an existing card
-tcu cards update <cardId> --name "new name" [--desc "new description"]
-
-# Move a card to another list
-tcu cards move <cardId> --to <listId>
-
-# Delete a card
-tcu cards delete <cardId>
-
-# Start interactive mode
-tcu interactive
-
-# Configure token
-tcu setup
-
-# Show version
-tcu --version
-
-# Output format options (available for most commands)
-tcu boards list --format json
-tcu boards list --format csv
-tcu boards list --format table  # default
-```
-
-## 🏗️ Command Structure
-
-The CLI uses a hierarchical subcommand structure for better organization:
-
-```
-tcu [command] [subcommand] [options] [arguments]
-```
-
-### Main Commands
-
-- **`boards`** - Manage Trello boards
-  - `list` - List all boards
-  - `show <boardId>` - Show detailed board information
-  - `create <name>` - Create a new board
-  - `delete <boardId>` - Delete a board
-
-- **`lists`** - Manage Trello lists
-  - `list <boardId>` - List all lists in a board
-  - `create <boardId> <name>` - Create a new list
-  - `delete <listId>` - Delete a list
-  - `move <listId> <position>` - Move list to new position
-
-- **`cards`** - Manage Trello cards
-  - `list <listId>` - List all cards in a list
-  - `show <cardId>` - Show detailed card information
-  - `create <listId> <name>` - Create a new card
-  - `update <cardId>` - Update an existing card
-  - `move <cardId>` - Move card to another list
-  - `delete <cardId>` - Delete a card
-
-- **`config`** - Configuration management
-  - `setup` - Configure Trello token
-  - `show` - Display current configuration
-
-### Global Options
-
-- `--format <format>` - Output format: `table` (default), `json`, `csv`
-- `--help` - Show help for any command
-- `--version` - Show CLI version
-
-### Interactive Mode
-
-```bash
-# Start interactive menu
-tcu
-
-# Or explicitly
 tcu interactive
 ```
 
-## 📚 Usage Examples
-
-### View Boards
-
-```bash
-# List all your boards
-tcu boards list
-
-# Show detailed information about a specific board
-tcu boards show 60d5ecb74e2b8c3b8c8c8c8c
+## Features
 
-# Export boards to JSON
-tcu boards list --format json
-
-# Export boards to CSV
-tcu boards list --format csv
-```
+- 🚀 Modo interativo com menu guiado
+- 📊 Saída em JSON, table e CSV
+- 🌍 Suporte a i18n (pt-BR / en)
+- 🔐 Autenticação Power-Up para Trello
+- 👤 Suporte a múltiplos perfis e configuração persistente
 
-### Manage Lists
+## Commands
 
 ```bash
-# List all lists in a board
-tcu lists list 60d5ecb74e2b8c3b8c8c8c8c
-```
-
-### Manage Cards
-
-```bash
-# List all cards in a list
-tcu cards list 60d5ecb74e2b8c3b8c8c8c8d
-
-# Show detailed information about a card
-tcu cards show 60d5ecb74e2b8c3b8c8c8c8e
-
-# Create a new card
-tcu cards create 60d5ecb74e2b8c3b8c8c8c8d "Implement new feature" --desc "Add support for card templates"
-
-# Update an existing card
-tcu cards update 60d5ecb74e2b8c3b8c8c8c8e --name "Updated feature name" --desc "Updated description"
-
-# Move a card to another list
-tcu cards move 60d5ecb74e2b8c3b8c8c8c8e --to 60d5ecb74e2b8c3b8c8c8c8f
+tcu boards
 
-# Delete a card
-tcu cards delete 60d5ecb74e2b8c3b8c8c8c8e
-```
-
-### Create a Card
-
-```bash
-# Interactive mode
-tcu
-# Select "➕ Create card"
-# Choose board → list → enter name and description
-```
-
-### Explore a Board
+tcu lists
 
-```bash
-# Interactive mode
-tcu
-# Select "📝 Explore board"
-# Choose board → list → see cards
-# Optionally: edit, delete, or move cards
-```
+tcu cards
 
-### Show Card Details
-
-```bash
-# Show detailed information about a card, including checklists, members, labels and attachments
-tcu cards show <cardId>
-```
-
-### Output Formats
-
-```bash
-# Table format (default)
-tcu boards list
-
-# JSON format
-tcu boards list --format json
-
-# CSV format
-tcu boards list --format csv
-
-# All formats work with most commands
-tcu cards list <listId> --format json
-tcu lists list <boardId> --format csv
-```
-
-## 🔄 Backward Compatibility
-
-### Legacy Command Support
-
-During the transition period, the CLI maintains backward compatibility with older command formats. These legacy commands will show deprecation warnings but continue to work:
-
-```bash
-# Legacy commands (show deprecation warnings)
-tcu boards                    # → Use "tcu boards list" instead
-tcu lists legacy <boardName>  # → Use "tcu lists list <boardId>" instead
-tcu cards legacy <boardName> <listName>  # → Use "tcu cards list <listId>" instead
-
-# Legacy card management commands
-tcu create-card <boardName> <listName> <cardName>
-tcu move-card <cardId> <listName>
-tcu delete-card <cardId>
-```
-
-### Migration Guide
-
-| Old Command | New Command | Status |
-|-------------|-------------|--------|
-| `tcu boards` | `tcu boards list` | ⚠️ Deprecated |
-| `tcu lists <boardName>` | `tcu lists list <boardId>` | ⚠️ Deprecated |
-| `tcu cards <boardName> <listName>` | `tcu cards list <listId>` | ⚠️ Deprecated |
-| `tcu create-card <boardName> <listName> <name>` | `tcu cards create <listId> <name>` | ⚠️ Deprecated |
-| `tcu move-card <cardId> <listName>` | `tcu cards move <cardId> --to <listId>` | ⚠️ Deprecated |
-| `tcu delete-card <cardId>` | `tcu cards delete <cardId>` | ⚠️ Deprecated |
-
-**Migration Timeline:**
-- **Current:** Legacy commands work with deprecation warnings
-- **Future:** Legacy commands will be removed (TBD)
-
-### Why the Changes?
-
-The new command structure provides:
-- **Better organization** with hierarchical subcommands
-- **Improved discoverability** with `tcu <command> --help`
-- **Consistency** with modern CLI patterns
-- **Future extensibility** for additional subcommands
-
-## 🤖 CI/CD & Automation
-
-This project uses automated CI/CD with semantic versioning based on **commit messages**:
-
-### Version Bumping
-
-- `feat:` commits → **Minor version bump** (0.5.0 → 0.6.0)
-- `fix:` commits → **Patch version bump** (0.5.0 → 0.5.1)
-- `BREAKING CHANGE:` in commit body → **Major version bump** (0.5.0 → 1.0.0)
-- Other commits (docs, test, chore) → **No release**
-
-### Automated Publishing
-
-Every push to `main` branch triggers:
-
-1. **CI Pipeline**: Linting, type checking, tests, coverage, and build
-2. **Release Pipeline**: Automatic version bump based on commit message
-3. **NPM Publishing**: Package published with provenance and signed builds
-4. **GitHub Release**: Automatic release notes and changelog
-
-### Conventional Commits
-
-```bash
-# Feature commit (minor version bump)
-git commit -m "feat: add new card templates"
-
-# Bug fix (patch version bump)
-git commit -m "fix: handle network timeouts gracefully"
-
-# Breaking change (major version bump) - Method 1
-git commit -m "feat!: redesign authentication flow"
-
-# Breaking change (major version bump) - Method 2
-git commit -m "feat: redesign authentication flow
-
-BREAKING CHANGE: token format changed from legacy API to Power-Up"
-
-# Non-releasing commits
-git commit -m "docs: update installation guide"
-git commit -m "test: add integration tests"
-git commit -m "chore: update dependencies"
-```
-
-**Important:** Version bumps are **automatic** and based on the **commit message when merged to main**, not PR titles or descriptions.
-
-## 🛠️ Development
-
-### Project Structure
-
-```
-trello-cli-unofficial/
-├── src/
-│   ├── domain/           # Business logic & entities
-│   ├── application/      # Use cases & orchestration
-│   ├── infrastructure/   # External implementations
-│   └── presentation/     # CLI controllers & UI
-├── tests/                # Test suite (57 tests)
-├── .github/workflows/    # CI/CD pipelines
-├── main.ts              # Entry point
-├── package.json         # Dependencies & scripts
-└── README.md           # This documentation
-```
-
-### Dependencies
-
-- `commander`: CLI framework
-- `inquirer`: Interactive prompts
-- `fs-extra`: File operations
-- `dotenv`: Environment variables
-
-### Available Scripts
-
-```bash
-# Run locally
-bun run main.ts
-
-# Development with watch mode
-bun run --watch main.ts
-
-# Build for production
-bun run build
-
-# Run tests
-bun test
-
-# Run tests with coverage
-bun test:coverage
-
-# Validation (lint + typecheck + test)
-bun run validate
-
-# Type checking only
-bun run typecheck
-
-# Linting only
-bun run lint
-```
-
-## 🔧 Architecture & Extensibility
-
-### Domain-Driven Design Structure
-
-The CLI follows Domain-Driven Design principles with clear separation of concerns:
-
-```
-src/
-├── domain/           # Business logic & entities
-│   ├── entities/     # Board, List, Card entities
-│   ├── repositories/ # Repository interfaces
-│   └── services/     # Domain services (Authentication)
-├── application/      # Use cases & business logic
-│   └── use-cases/    # Business operations
-├── infrastructure/   # External implementations
-│   ├── repositories/ # Trello API, File system implementations
-│   └── external/     # External service integrations
-├── presentation/     # CLI interface layer
-│   └── cli/         # Command controllers & UI
-└── shared/          # Cross-cutting concerns
-    ├── ErrorHandler.ts
-    ├── OutputFormatter.ts
-    └── types.ts
-```
-
-### Adding New Commands
-
-To extend the CLI with new functionality:
-
-1. **Create a Use Case** in `src/application/use-cases/`
-2. **Implement Repository Interface** if needed
-3. **Add Controller Method** in appropriate CLI controller
-4. **Register Command** in `CommandController.ts`
-5. **Add Tests** following the existing pattern
-
-### Output Formatters
-
-The CLI supports multiple output formats through the `OutputFormatter` class:
-
-- **Table**: Human-readable tabular output (default)
-- **JSON**: Machine-readable structured data
-- **CSV**: Spreadsheet-compatible format
-
-All formatters handle complex nested data structures automatically.
-
-## 🧪 Cross-Platform Development Testing
-
-This project includes tools for testing cross-platform compatibility during development:
-
-### Quick Cross-Platform Test
-
-```bash
-# Run comprehensive cross-platform tests
-bun run test:cross-platform
-
-# This will test:
-# ✅ Build process
-# ✅ Installation process
-# ✅ CLI functionality (--version, --help)
-# ✅ File system operations
-# ✅ Environment variable handling
-# ✅ Platform-specific features
-```
-
-### Individual Test Commands
-
-```bash
-# Test build process only
-bun run test:build
-
-# Test installation process
-bun run test:install
-
-# Quick smoke tests
-bun run test:smoke
-```
-
-### Docker-Based Cross-Platform Testing
-
-For comprehensive testing across platforms, use Docker containers:
-
-```bash
-# Test on all platforms (Linux + Windows when available)
-npm run test:docker
-
-# Test specific platforms
-npm run test:docker:ubuntu    # Ubuntu Linux
-npm run test:docker:alpine    # Alpine Linux
-npm run test:docker:windows   # Windows (requires Windows host or WSL2)
-```
-
-**Platform Support:**
-- ✅ **Linux**: Ubuntu 22.04, Ubuntu 20.04, Alpine Linux
-- ✅ **Windows**: Windows Server Core 2022 (via Docker Desktop)
-- ✅ **macOS**: Tested via GitHub Actions CI/CD
-
-**Requirements:**
-- Docker Desktop installed
-- 4GB+ RAM allocated to Docker
-- For Windows containers: Windows 10/11 Pro+ or WSL2
-
-See [`WINDOWS_TESTING.md`](./WINDOWS_TESTING.md) for detailed Windows setup instructions.
-
-### Manual Windows Testing Checklist
-
-When testing on Windows, verify these scenarios:
-
-1. **Installation Methods:**
-   ```powershell
-   # Method 1: NPM global install
-   npm install -g trello-cli-unofficial
-
-   # Method 2: From source
-   bun install
-   bun link  # or bun run install-global
-   ```
-
-2. **Command Availability:**
-   ```powershell
-   # Test both command names
-   tcu --version
-   trello-cli-unofficial --version
-
-   # Test in different terminals
-   # - Command Prompt (cmd)
-   # - PowerShell
-   # - Windows Terminal
-   ```
-
-3. **PATH Configuration:**
-   ```powershell
-   # Check if commands are in PATH
-   where tcu
-   where trello-cli-unofficial
-
-   # Refresh environment (PowerShell)
-   $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
-   ```
-
-4. **File System Operations:**
-   - Config directory creation: `%USERPROFILE%\.trello-cli-unofficial\`
-   - File read/write permissions
-   - Path separator handling (`\` vs `/`)
-
-5. **Environment Variables:**
-   - `TRELLO_TOKEN` handling
-   - Language detection (`LANG`, `LC_ALL`, etc.)
-   - Node.js/Bun path resolution
-
-### Common Windows Issues & Solutions
-
-| Issue | Symptom | Solution |
-|-------|---------|----------|
-| PATH not updated | `tcu command not found` | Restart terminal or run `refreshenv` |
-| Permission denied | Installation fails | Run as Administrator |
-| Antivirus blocking | Installation interrupted | Temporarily disable or whitelist |
-| Node version conflicts | Runtime errors | Use Node 18+ or Bun 1.0+ |
-
-## 🔒 Security
-
-- Token saved locally in protected file (`~/.trello-cli-unofficial/config.json`)
-- No data sent to external servers
-- Uses HTTPS for all Trello API communications
-- Compatible with Trello's Power-Up authentication
-- NPM packages published with provenance attestation
-
-## 🐛 Troubleshooting
-
-### 401 Unauthorized Error
-
-- Verify the token is correct and starts with `ATTA`
-- Confirm the Power-Up has necessary permissions
-- Try generating a new token from [trello.com/power-ups/admin](https://trello.com/power-ups/admin)
-
-### Network Error
-
-- Check your internet connection
-- Confirm `api.trello.com` is accessible
-- Try again in a few minutes
-
-### Configuration Not Saving
-
-- Check write permissions in `~/.trello-cli-unofficial/`
-- Run as user with appropriate permissions
-- Try running `tcu setup` again
-
-### Installation Issues
-
-- **Runtime Required:** Ensure Bun or Node.js 16+ is installed
-- **Package Manager Fallback:** Try `npm install -g trello-cli-unofficial` if Bun fails
-- **PATH Issues:** Check that `tcu` command is in your PATH
-- **Permission Issues:** Try running as administrator/sudo
-
-#### Windows-specific Issues
-
-- **PATH not updated:** Restart your terminal or run `refreshenv` in PowerShell
-- **Permission errors:** Run PowerShell/Command Prompt as Administrator
-- **Node.js version:** Ensure you have Node.js 16+ or Bun 1.0+
-- **Antivirus blocking:** Some antivirus software may block global NPM installations
-
-## 🤝 Contributing
-
-Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) before submitting PRs.
-
-1. Fork the project
-2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
-3. Commit your changes using conventional commits (`git commit -m 'feat: add some amazing feature'`)
-4. Run the tests (`bun run validate`)
-5. Push to the branch (`git push origin feature/AmazingFeature`)
-6. Open a Pull Request
-
-### Development Setup
-
-```bash
-# Clone and setup
-git clone https://github.com/JaegerCaiser/trello-cli-unofficial.git
-cd trello-cli-unofficial
-bun install
-
-# Run tests
-bun test
-
-# Start development
-bun run --watch main.ts
+tcu config
 ```
 
-## 📜 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## 🙏 Acknowledgments
-
-- [Trello API](https://developer.atlassian.com/cloud/trello/) - Official Trello REST API
-- [Bun](https://bun.sh/) - Ultra-fast JavaScript runtime
-- [Inquirer](https://github.com/SBoudrias/Inquirer.js) - Interactive command-line interface
-- [Commander](https://github.com/tj/commander.js) - CLI framework for Node.js
-- [GitHub Actions](https://github.com/features/actions) - CI/CD automation
-
-## 📊 Project Status
-
-- 🚀 195 tests passing (100% coverage)
-- 📦 Clean Domain-Driven Design architecture
-- 🎨 ESLint + TypeScript strict mode
-- ⚡ Performance optimized with Bun
-- 🤖 Automated CI/CD with semantic versioning
-- 🔒 Secure publishing with NPM provenance
-- 🌍 Internationalization (pt-BR/en)
-- 📊 Multiple output formats (table/json/csv)
-- 🏗️ Hierarchical command structure
-
----
+*Para ver todos os parâmetros e opções, execute `tcu <comando> --help` no seu terminal.*
 
----
+## 📚 Documentação Completa
 
-**Note**: This is an unofficial project and is not affiliated with Atlassian or Trello.
+- [./docs/commands.md](./docs/commands.md)
+- [./docs/architecture.md](./docs/architecture.md)
+- [./docs/migration-guide.md](./docs/migration-guide.md)
+- [./docs/troubleshooting.md](./docs/troubleshooting.md)
 
----
+## Contribuição
 
-**Made with ❤️, Bun, and automated CI/CD**
+Quer ajudar a melhorar o projeto? Veja nosso [Guia de Contribuição](CONTRIBUTING.md).