rook-cli 1.0.0

package/README.md

@@ -0,0 +1,71 @@
+# 🚀 ROOK CLI — Shopify Component Tool
+
+CLI para instalar componentes Shopify de um repositório centralizado no GitHub.
+
+## Instalação
+
+```bash
+# Instalar dependências
+npm install
+
+# Linkar globalmente (para usar o comando "rook" no terminal)
+npm link
+```
+
+## Uso
+
+```bash
+# Abre o menu interativo
+rook
+
+# Comando direto
+rook add
+```
+
+Caso tenha algum repositorio privado, você pode configurar o token de acesso:
+
+```bash
+rook config
+```
+
+# 1. Configurar o token (uma única vez)
+
+```bash
+node bin/rook.js config
+```
+
+# 2. Usar normalmente — autenticação é automática
+
+```bash
+node bin/rook.js add
+```
+
+## Estrutura do Projeto
+
+```
+src/
+├── app.js                  # Classe principal (Composition Root)
+├── commands/
+│   └── AddCommand.js       # Comando "add" — orquestra o fluxo
+├── ui/
+│   └── PromptUI.js         # Menus interativos (Inquirer)
+├── services/
+│   ├── GitHubService.js    # Comunicação com GitHub API
+│   └── DownloadService.js  # Download via tiged
+├── filesystem/
+│   ├── FileMapper.js       # Mapeamento de diretórios Shopify
+│   └── ConflictResolver.js # Tratamento de conflitos
+├── config/
+│   └── constants.js        # Constantes globais
+└── utils/
+    └── logger.js           # Logger com feedback visual
+```
+
+## Tecnologias
+
+- **Node.js** (ESM) — Ambiente de execução
+- **Commander** — Parser de comandos CLI
+- **Inquirer** — Menus interativos
+- **tiged** — Download eficiente sem `.git`
+- **fs-extra** — Manipulação de arquivos
+- **picocolors** — Estilo visual no terminal

package/bin/rook.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+/**
+ * Ponto de entrada do CLI — ROOK CLI
+ * 
+ * Este arquivo é o entry point registrado no package.json.
+ * Sua única responsabilidade é inicializar a aplicação.
+ */
+
+import 'dotenv/config';
+import { App } from '../src/app.js';
+
+const app = new App();
+app.run();

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "rook-cli",
+  "version": "1.0.0",
+  "description": "CLI para instalar componentes Shopify de um repositório centralizado",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chesslabdev/rook-cli.git"
+  },
+  "type": "module",
+  "bin": {
+    "rook": "bin/rook.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "start": "node bin/rook.js",
+    "test": "echo \"No tests yet\" && exit 0"
+  },
+  "keywords": [
+    "shopify",
+    "cli",
+    "components",
+    "themes"
+  ],
+  "author": "ROOK",
+  "license": "ISC",
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.0",
+    "commander": "^14.0.3",
+    "dotenv": "^17.3.1",
+    "fs-extra": "^11.3.3",
+    "picocolors": "^1.1.1",
+    "tiged": "^2.12.7"
+  }
+}

package/src/app.js

@@ -0,0 +1,93 @@
+/**
+ * App — Classe principal da aplicação.
+ * 
+ * Responsável por:
+ * - Registrar comandos no Commander
+ * - Instanciar e injetar dependências (Composition Root)
+ * - Iniciar o CLI
+ * 
+ * Princípio: Inversão de Dependência (DIP) — atua como Composition Root
+ * Princípio: Aberto/Fechado (OCP) — novos comandos são adicionados sem alterar o existente
+ */
+
+import { Command } from 'commander';
+import { Logger } from './utils/logger.js';
+import { PromptUI } from './ui/PromptUI.js';
+import { TokenManager } from './auth/TokenManager.js';
+import { GitHubService } from './services/GitHubService.js';
+import { DownloadService } from './services/DownloadService.js';
+import { FileMapper } from './filesystem/FileMapper.js';
+import { ConflictResolver } from './filesystem/ConflictResolver.js';
+import { AddCommand } from './commands/AddCommand.js';
+import { ConfigCommand } from './commands/ConfigCommand.js';
+import { CLI_NAME } from './config/constants.js';
+
+export class App {
+
+    constructor() {
+        // -- Instância do Commander (parser de comandos) --
+        this.programa = new Command();
+
+        // -- Instanciação de dependências (Composition Root) --
+        this.logger = new Logger();
+        this.promptUI = new PromptUI();
+        this.tokenManager = new TokenManager(this.logger);
+        this.githubService = new GitHubService(this.logger, this.tokenManager);
+        this.downloadService = new DownloadService(this.logger, this.tokenManager);
+        this.conflictResolver = new ConflictResolver(this.logger);
+        this.fileMapper = new FileMapper(this.logger, this.conflictResolver);
+
+        // -- Comandos --
+        this.addCommand = new AddCommand(
+            this.logger,
+            this.promptUI,
+            this.githubService,
+            this.downloadService,
+            this.fileMapper
+        );
+
+        this.configCommand = new ConfigCommand(
+            this.logger,
+            this.tokenManager
+        );
+    }
+
+    /**
+     * Configura e executa o CLI.
+     * Registra todos os comandos e faz o parse dos argumentos.
+     */
+    run() {
+        this.programa
+            .name(CLI_NAME)
+            .description('CLI para instalar componentes Shopify de um repositório centralizado')
+            .version('1.0.0');
+
+        // Comando: rook add
+        this.programa
+            .command('add')
+            .description('Adiciona kits ou componentes ao tema Shopify atual')
+            .action(async () => {
+                this.logger.banner();
+                await this.addCommand.executar();
+            });
+
+        // Comando: rook config
+        this.programa
+            .command('config')
+            .description('Configura o token de acesso para repositórios privados do GitHub')
+            .action(async () => {
+                this.logger.banner();
+                await this.configCommand.executar();
+            });
+
+        // Comando padrão (sem argumentos) — abre o menu interativo
+        this.programa
+            .action(async () => {
+                this.logger.banner();
+                await this.addCommand.executar();
+            });
+
+        // Parse dos argumentos
+        this.programa.parse(process.argv);
+    }
+}

package/src/auth/TokenManager.js

@@ -0,0 +1,118 @@
+/**
+ * TokenManager — Gerenciamento do token de acesso GitHub.
+ * 
+ * Armazena e recupera o Personal Access Token (PAT) do GitHub
+ * em um arquivo de configuração na home do usuário (~/.rookrc).
+ * O token NUNCA é commitado no repositório do projeto.
+ * 
+ * Princípio: Responsabilidade Única (SRP) — apenas gerencia credenciais
+ */
+
+import path from 'path';
+import os from 'os';
+import fs from 'fs-extra';
+
+/** Caminho do arquivo de configuração (~/.rookrc) */
+const CONFIG_PATH = path.join(os.homedir(), '.rookrc');
+
+export class TokenManager {
+
+    /**
+     * @param {import('../utils/logger.js').Logger} logger
+     */
+    constructor(logger) {
+        this.logger = logger;
+    }
+
+    /**
+     * Lê a configuração salva no disco.
+     * @returns {Promise<Object>} Objeto de configuração
+     * @private
+     */
+    async _lerConfig() {
+        try {
+            if (await fs.pathExists(CONFIG_PATH)) {
+                const conteudo = await fs.readFile(CONFIG_PATH, 'utf-8');
+                return JSON.parse(conteudo);
+            }
+        } catch {
+            // Se o arquivo estiver corrompido, retorna vazio
+            this.logger.aviso('Arquivo de configuração corrompido. Recriando...');
+        }
+        return {};
+    }
+
+    /**
+     * Salva a configuração no disco.
+     * @param {Object} config - Objeto de configuração
+     * @private
+     */
+    async _salvarConfig(config) {
+        await fs.writeFile(CONFIG_PATH, JSON.stringify(config, null, 2), 'utf-8');
+    }
+
+    /**
+     * Salva o token de acesso do GitHub.
+     * @param {string} token - Personal Access Token (PAT) do GitHub
+     */
+    async salvarToken(token) {
+        const config = await this._lerConfig();
+        config.githubToken = token;
+        await this._salvarConfig(config);
+        this.logger.sucesso(`Token salvo em: ${CONFIG_PATH}`);
+    }
+
+    /**
+     * Recupera o token de acesso do GitHub.
+     * @returns {Promise<string|null>} Token salvo ou null se não existir
+     */
+    async obterToken() {
+        // 1. Prioridade: variável de ambiente
+        if (process.env.GITHUB_TOKEN) {
+            return process.env.GITHUB_TOKEN;
+        }
+
+        // 2. Fallback: arquivo de configuração
+        const config = await this._lerConfig();
+        return config.githubToken || null;
+    }
+
+    /**
+     * Verifica se existe um token configurado.
+     * @returns {Promise<boolean>}
+     */
+    async temToken() {
+        const token = await this.obterToken();
+        return token !== null && token.length > 0;
+    }
+
+    /**
+     * Remove o token salvo.
+     */
+    async removerToken() {
+        const config = await this._lerConfig();
+        delete config.githubToken;
+        await this._salvarConfig(config);
+        this.logger.sucesso('Token removido com sucesso.');
+    }
+
+    /**
+     * Retorna os headers de autenticação para uso nas requisições.
+     * Se não houver token, retorna headers sem autenticação.
+     * 
+     * @returns {Promise<Object>} Headers HTTP com ou sem Authorization
+     */
+    async obterHeaders() {
+        const headers = {
+            'Accept': 'application/vnd.github.v3+json',
+        };
+
+        const token = await this.obterToken();
+
+        if (token) {
+            headers['Authorization'] = `Bearer ${token}`;
+        }
+
+        return headers;
+    }
+}

package/src/commands/AddCommand.js

@@ -0,0 +1,121 @@
+/**
+ * AddCommand — Comando "add" do CLI.
+ * 
+ * Orquestra o fluxo de instalação:
+ * 1. Exibe menu de seleção (kit ou componente)
+ * 2. Lista itens disponíveis via GitHub
+ * 3. Realiza download via tiged
+ * 4. Distribui arquivos nas pastas corretas
+ * 
+ * Princípio: Inversão de Dependência (DIP) — todas as dependências são injetadas
+ * Princípio: Responsabilidade Única (SRP) — orquestra apenas o fluxo do comando "add"
+ */
+
+import path from 'path';
+import os from 'os';
+import fs from 'fs-extra';
+
+export class AddCommand {
+
+    /**
+     * @param {import('../utils/logger.js').Logger} logger
+     * @param {import('../ui/PromptUI.js').PromptUI} promptUI
+     * @param {import('../services/GitHubService.js').GitHubService} githubService
+     * @param {import('../services/DownloadService.js').DownloadService} downloadService
+     * @param {import('../filesystem/FileMapper.js').FileMapper} fileMapper
+     */
+    constructor(logger, promptUI, githubService, downloadService, fileMapper) {
+        this.logger = logger;
+        this.promptUI = promptUI;
+        this.githubService = githubService;
+        this.downloadService = downloadService;
+        this.fileMapper = fileMapper;
+    }
+
+    /**
+     * Executa o fluxo principal do comando "add".
+     * @returns {Promise<void>}
+     */
+    async executar() {
+        try {
+            // 1. Menu principal
+            const tipoInstalacao = await this.promptUI.menuPrincipal();
+
+            // 2. Delega para o fluxo correto
+            if (tipoInstalacao === 'kit') {
+                await this._instalarKit();
+            } else {
+                await this._instalarComponentes();
+            }
+
+        } catch (erro) {
+            // Trata cancelamento do usuário (Ctrl+C)
+            if (erro.name === 'ExitPromptError') {
+                this.logger.aviso('Operação cancelada pelo usuário.');
+                return;
+            }
+            this.logger.erro(`Erro durante a instalação: ${erro.message}`);
+        }
+    }
+
+    /**
+     * Fluxo de instalação de um kit completo.
+     * @private
+     */
+    async _instalarKit() {
+        // Lista kits disponíveis
+        const kits = await this.githubService.listarKits();
+        const kitSelecionado = await this.promptUI.selecionarKit(kits);
+
+        this.logger.destaque(`\n📥 Instalando kit: ${kitSelecionado.nome}\n`);
+
+        // Baixa e distribui
+        await this._baixarEDistribuir(kitSelecionado.caminho, kitSelecionado.nome);
+    }
+
+    /**
+     * Fluxo de instalação de componentes individuais.
+     * @private
+     */
+    async _instalarComponentes() {
+        // Lista componentes disponíveis
+        const componentes = await this.githubService.listarComponentes();
+        const selecionados = await this.promptUI.selecionarComponentes(componentes);
+
+        this.logger.destaque(`\n📥 Instalando ${selecionados.length} componente(s)...\n`);
+
+        // Baixa e distribui cada componente
+        for (const componente of selecionados) {
+            await this._baixarEDistribuir(componente.caminho, componente.nome);
+        }
+    }
+
+    /**
+     * Processo genérico: baixa do repositório e distribui nas pastas locais.
+     * 
+     * @param {string} caminhoRemoto - Caminho no repositório (ex: "components/whatsapp-btn")
+     * @param {string} nomePacote - Nome do pacote para exibição nos logs
+     * @private
+     */
+    async _baixarEDistribuir(caminhoRemoto, nomePacote) {
+        // Cria pasta temporária para o download
+        const pastaTmp = path.join(os.tmpdir(), `rook-cli-${Date.now()}`);
+
+        try {
+            await fs.ensureDir(pastaTmp);
+
+            // Download via tiged
+            await this.downloadService.baixar(caminhoRemoto, pastaTmp);
+
+            // Distribui nas pastas Shopify locais
+            const diretorioAtual = process.cwd();
+            const totalCopiados = await this.fileMapper.distribuir(pastaTmp, diretorioAtual);
+
+            this.logger.sucesso(`\n🎉 "${nomePacote}" instalado! (${totalCopiados} arquivo(s) copiados)\n`);
+
+        } finally {
+            // Limpa pasta temporária
+            await fs.remove(pastaTmp);
+        }
+    }
+}

package/src/commands/ConfigCommand.js

@@ -0,0 +1,128 @@
+/**
+ * ConfigCommand — Comando "config" do CLI.
+ * 
+ * Permite ao usuário configurar o token de acesso
+ * para repositórios privados do GitHub.
+ * 
+ * Princípio: Responsabilidade Única (SRP) — só gerencia configuração
+ * Princípio: Inversão de Dependência (DIP) — recebe dependências via construtor
+ */
+
+import { password, select } from '@inquirer/prompts';
+
+export class ConfigCommand {
+
+    /**
+     * @param {import('../utils/logger.js').Logger} logger
+     * @param {import('../auth/TokenManager.js').TokenManager} tokenManager
+     */
+    constructor(logger, tokenManager) {
+        this.logger = logger;
+        this.tokenManager = tokenManager;
+    }
+
+    /**
+     * Executa o fluxo de configuração.
+     * @returns {Promise<void>}
+     */
+    async executar() {
+        try {
+            const temToken = await this.tokenManager.temToken();
+
+            const acao = await select({
+                message: '⚙️  O que deseja configurar?',
+                choices: [
+                    {
+                        name: temToken
+                            ? '🔑 Atualizar token do GitHub (já configurado ✔)'
+                            : '🔑 Configurar token do GitHub (necessário para repos privados)',
+                        value: 'token',
+                    },
+                    {
+                        name: '🗑️  Remover token salvo',
+                        value: 'remover',
+                        disabled: !temToken ? '(nenhum token salvo)' : false,
+                    },
+                    {
+                        name: '📋 Verificar status da configuração',
+                        value: 'status',
+                    },
+                ],
+            });
+
+            switch (acao) {
+                case 'token':
+                    await this._configurarToken();
+                    break;
+                case 'remover':
+                    await this.tokenManager.removerToken();
+                    break;
+                case 'status':
+                    await this._exibirStatus();
+                    break;
+            }
+
+        } catch (erro) {
+            if (erro.name === 'ExitPromptError') {
+                this.logger.aviso('Configuração cancelada.');
+                return;
+            }
+            this.logger.erro(`Erro na configuração: ${erro.message}`);
+        }
+    }
+
+    /**
+     * Solicita e salva o token do GitHub.
+     * @private
+     */
+    async _configurarToken() {
+        this.logger.info('Para acessar repositórios privados, você precisa de um Personal Access Token (PAT).');
+        this.logger.sutil('Crie um em: https://github.com/settings/tokens');
+        this.logger.sutil('Permissões necessárias: repo (acesso completo a repos privados)\n');
+
+        const token = await password({
+            message: '🔑 Cole seu GitHub Personal Access Token:',
+            mask: '•',
+            validate: (valor) => {
+                if (!valor || valor.trim().length === 0) {
+                    return 'O token não pode ser vazio.';
+                }
+                if (valor.trim().length < 10) {
+                    return 'Token parece inválido (muito curto).';
+                }
+                return true;
+            },
+        });
+
+        await this.tokenManager.salvarToken(token.trim());
+        this.logger.sucesso('Token configurado com sucesso! Agora você pode acessar repositórios privados. 🔓');
+    }
+
+    /**
+     * Exibe o status atual da configuração.
+     * @private
+     */
+    async _exibirStatus() {
+        const temToken = await this.tokenManager.temToken();
+
+        console.log('');
+        this.logger.destaque('📊 Status da configuração:');
+        console.log('');
+
+        if (temToken) {
+            this.logger.sucesso('Token GitHub: Configurado ✔');
+
+            // Indica a origem do token
+            if (process.env.GITHUB_TOKEN) {
+                this.logger.sutil('Origem: variável de ambiente GITHUB_TOKEN');
+            } else {
+                this.logger.sutil('Origem: arquivo ~/.rookrc');
+            }
+        } else {
+            this.logger.aviso('Token GitHub: Não configurado ✖');
+            this.logger.sutil('Execute "rook config" para configurar.');
+        }
+
+        console.log('');
+    }
+}

package/src/config/constants.js

@@ -0,0 +1,40 @@
+/**
+ * Constantes globais do projeto.
+ * 
+ * Centraliza todas as configurações fixas do CLI,
+ * como URLs do repositório e diretórios válidos do Shopify.
+ */
+
+/** Repositório de origem no GitHub (owner/repo) */
+export const GITHUB_REPO = process.env.GITHUB_REPO;
+
+/** URL base da API do GitHub para conteúdo do repositório */
+export const GITHUB_API_BASE = `https://api.github.com/repos/${GITHUB_REPO}/contents`;
+
+/** URL base para download via tiged */
+export const TIGED_BASE = `github:${GITHUB_REPO}`;
+
+/**
+ * Diretórios padrão da estrutura de um tema Shopify.
+ * Usados para mapear os arquivos do repositório remoto
+ * para as pastas corretas no tema local.
+ */
+export const SHOPIFY_DIRS = [
+    'assets',
+    'blocks',
+    'config',
+    'layout',
+    'locales',
+    'sections',
+    'snippets',
+    'templates',
+];
+
+/** Pastas raiz do repositório remoto */
+export const REMOTE_PATHS = {
+    KITS: 'kits',
+    COMPONENTS: 'components',
+};
+
+/** Nome do CLI exibido nos logs */
+export const CLI_NAME = 'rook';

package/src/filesystem/ConflictResolver.js

@@ -0,0 +1,70 @@
+/**
+ * ConflictResolver — Tratamento de conflitos de arquivos.
+ * 
+ * Quando um arquivo de destino já existe, este módulo
+ * solicita confirmação do usuário antes de sobrescrever.
+ * Implementa o RF04 do PRD.
+ * 
+ * Princípio: Responsabilidade Única (SRP) — só trata conflitos
+ */
+
+import { confirm } from '@inquirer/prompts';
+
+export class ConflictResolver {
+
+    /**
+     * @param {import('../utils/logger.js').Logger} logger
+     */
+    constructor(logger) {
+        this.logger = logger;
+
+        /**
+         * Cache de decisão do usuário para "aplicar a todos".
+         * null = não decidido, true = sobrescrever tudo, false = pular tudo
+         * @type {boolean|null}
+         */
+        this._decisaoGlobal = null;
+    }
+
+    /**
+     * Pergunta ao usuário se deseja sobrescrever o arquivo existente.
+     * 
+     * @param {string} nomeArquivo - Nome do arquivo em conflito
+     * @returns {Promise<boolean>} true para sobrescrever, false para pular
+     */
+    async resolver(nomeArquivo) {
+        // Se já tem uma decisão global, usa ela
+        if (this._decisaoGlobal !== null) {
+            if (!this._decisaoGlobal) {
+                this.logger.aviso(`  ⏩ Pulando: ${nomeArquivo} (decisão global)`);
+            }
+            return this._decisaoGlobal;
+        }
+
+        this.logger.aviso(`Arquivo já existe: ${nomeArquivo}`);
+
+        const sobrescrever = await confirm({
+            message: `Sobrescrever "${nomeArquivo}"?`,
+            default: false,
+        });
+
+        return sobrescrever;
+    }
+
+    /**
+     * Define uma decisão global para todos os conflitos restantes.
+     * Útil para opção "sobrescrever todos" ou "pular todos".
+     * 
+     * @param {boolean} decisao - true para sobrescrever, false para pular
+     */
+    definirDecisaoGlobal(decisao) {
+        this._decisaoGlobal = decisao;
+    }
+
+    /**
+     * Reseta a decisão global (para novo ciclo de instalação).
+     */
+    resetar() {
+        this._decisaoGlobal = null;
+    }
+}

package/src/filesystem/FileMapper.js

@@ -0,0 +1,123 @@
+/**
+ * FileMapper — Mapeamento e distribuição de arquivos.
+ * 
+ * Responsável por identificar a estrutura de arquivos baixados
+ * e distribuí-los nas pastas corretas do tema Shopify local,
+ * conforme o padrão de diretórios definido no RF02.
+ * 
+ * Princípio: Responsabilidade Única (SRP) — só mapeia e move
+ * Princípio: Inversão de Dependência (DIP) — recebe dependências via construtor
+ */
+
+import path from 'path';
+import fs from 'fs-extra';
+import { SHOPIFY_DIRS } from '../config/constants.js';
+
+export class FileMapper {
+
+    /**
+     * @param {import('../utils/logger.js').Logger} logger
+     * @param {import('./ConflictResolver.js').ConflictResolver} conflictResolver
+     */
+    constructor(logger, conflictResolver) {
+        this.logger = logger;
+        this.conflictResolver = conflictResolver;
+    }
+
+    /**
+     * Distribui os arquivos de uma pasta temporária para o diretório
+     * de trabalho atual, respeitando a estrutura Shopify.
+     * 
+     * @param {string} pastaOrigem - Caminho da pasta temporária com os arquivos baixados
+     * @param {string} pastaDestino - Diretório raiz do tema Shopify local (cwd)
+     * @returns {Promise<number>} Número de arquivos copiados
+     */
+    async distribuir(pastaOrigem, pastaDestino) {
+        let totalCopiados = 0;
+
+        // Itera sobre cada diretório padrão do Shopify
+        for (const dir of SHOPIFY_DIRS) {
+            const origemDir = path.join(pastaOrigem, dir);
+
+            // Verifica se o diretório existe no conteúdo baixado
+            if (!await fs.pathExists(origemDir)) {
+                continue;
+            }
+
+            const destinoDir = path.join(pastaDestino, dir);
+
+            // Garante que o diretório de destino existe
+            await fs.ensureDir(destinoDir);
+
+            // Lista os arquivos dentro do diretório
+            const arquivos = await this._listarArquivosRecursivo(origemDir);
+
+            for (const arquivoRelativo of arquivos) {
+                const arquivoOrigem = path.join(origemDir, arquivoRelativo);
+                const arquivoDestino = path.join(destinoDir, arquivoRelativo);
+
+                // Verifica conflito antes de copiar
+                const deveCopiar = await this._verificarConflito(arquivoDestino, arquivoRelativo);
+
+                if (deveCopiar) {
+                    await fs.ensureDir(path.dirname(arquivoDestino));
+                    await fs.copy(arquivoOrigem, arquivoDestino);
+                    this.logger.sucesso(`  → ${dir}/${arquivoRelativo}`);
+                    totalCopiados++;
+                }
+            }
+        }
+
+        return totalCopiados;
+    }
+
+    /**
+     * Lista todos os arquivos de um diretório de forma recursiva.
+     * Retorna caminhos relativos ao diretório base.
+     * 
+     * @param {string} diretorio - Caminho absoluto do diretório
+     * @param {string} [base=''] - Caminho base para relativizar
+     * @returns {Promise<string[]>} Lista de caminhos relativos dos arquivos
+     * @private
+     */
+    async _listarArquivosRecursivo(diretorio, base = '') {
+        const itens = await fs.readdir(diretorio, { withFileTypes: true });
+        let arquivos = [];
+
+        for (const item of itens) {
+            const caminhoRelativo = base ? path.join(base, item.name) : item.name;
+
+            if (item.isDirectory()) {
+                // Recursa em subdiretórios
+                const subArquivos = await this._listarArquivosRecursivo(
+                    path.join(diretorio, item.name),
+                    caminhoRelativo
+                );
+                arquivos = arquivos.concat(subArquivos);
+            } else {
+                arquivos.push(caminhoRelativo);
+            }
+        }
+
+        return arquivos;
+    }
+
+    /**
+     * Verifica se existe conflito e delega ao ConflictResolver.
+     * 
+     * @param {string} caminhoDestino - Caminho absoluto do arquivo de destino
+     * @param {string} nomeArquivo - Nome do arquivo para exibição
+     * @returns {Promise<boolean>} true se deve copiar, false se cancelado
+     * @private
+     */
+    async _verificarConflito(caminhoDestino, nomeArquivo) {
+        const existe = await fs.pathExists(caminhoDestino);
+
+        if (!existe) {
+            return true;
+        }
+
+        // Delega ao ConflictResolver (RF04)
+        return this.conflictResolver.resolver(nomeArquivo);
+    }
+}

package/src/services/DownloadService.js

@@ -0,0 +1,151 @@
+/**
+ * DownloadService — Motor de download de componentes.
+ * 
+ * Suporta dois modos de download:
+ * - Repositórios públicos: usa tiged (rápido, sem .git)
+ * - Repositórios privados: usa GitHub API (tarball autenticado)
+ * 
+ * Princípio: Responsabilidade Única (SRP) — só faz download
+ * Princípio: Inversão de Dependência (DIP) — recebe dependências via construtor
+ */
+
+import tiged from 'tiged';
+import path from 'path';
+import fs from 'fs-extra';
+import { pipeline } from 'stream/promises';
+import { createWriteStream } from 'fs';
+import { execSync } from 'child_process';
+import { TIGED_BASE, GITHUB_REPO } from '../config/constants.js';
+
+export class DownloadService {
+
+    /**
+     * @param {import('../utils/logger.js').Logger} logger - Instância do logger
+     * @param {import('../auth/TokenManager.js').TokenManager} tokenManager - Gerenciador de tokens
+     */
+    constructor(logger, tokenManager) {
+        this.logger = logger;
+        this.tokenManager = tokenManager;
+    }
+
+    /**
+     * Realiza o download de um subdiretório do repositório.
+     * Escolhe automaticamente o método baseado na disponibilidade do token.
+     * 
+     * @param {string} caminhoRemoto - Subcaminho no repositório (ex: "kits/base")
+     * @param {string} destinoLocal - Caminho absoluto para a pasta de destino
+     * @returns {Promise<void>}
+     */
+    async baixar(caminhoRemoto, destinoLocal) {
+        const temToken = await this.tokenManager.temToken();
+
+        if (temToken) {
+            // Repositório privado: download via GitHub API
+            await this._baixarViaAPI(caminhoRemoto, destinoLocal);
+        } else {
+            // Repositório público: download via tiged (mais rápido)
+            await this._baixarViaTiged(caminhoRemoto, destinoLocal);
+        }
+    }
+
+    /**
+     * Download via GitHub API — funciona com repos privados.
+     * Baixa o tarball do repositório e extrai apenas o subdiretório desejado.
+     * 
+     * @param {string} caminhoRemoto - Subcaminho no repositório
+     * @param {string} destinoLocal - Pasta de destino
+     * @private
+     */
+    async _baixarViaAPI(caminhoRemoto, destinoLocal) {
+        this.logger.info(`Baixando (modo autenticado): ${caminhoRemoto}...`);
+
+        const headers = await this.tokenManager.obterHeaders();
+        const tarballUrl = `https://api.github.com/repos/${GITHUB_REPO}/tarball`;
+
+        try {
+            const resposta = await fetch(tarballUrl, {
+                headers,
+                redirect: 'follow',
+            });
+
+            if (!resposta.ok) {
+                throw new Error(`Erro ao baixar tarball: HTTP ${resposta.status}`);
+            }
+
+            // Salva o tarball em arquivo temporário
+            const tarballPath = path.join(destinoLocal, '..', `rook-download-${Date.now()}.tar.gz`);
+            const extractDir = path.join(destinoLocal, '..', `rook-extract-${Date.now()}`);
+
+            await fs.ensureDir(extractDir);
+
+            // Escreve o tarball no disco
+            const fileStream = createWriteStream(tarballPath);
+            await pipeline(resposta.body, fileStream);
+
+            // Extrai o tarball
+            execSync(`tar -xzf "${tarballPath}" -C "${extractDir}"`, { stdio: 'pipe' });
+
+            // O tarball do GitHub cria uma pasta com o nome do repo + hash
+            // Precisamos encontrar essa pasta raiz
+            const extraidos = await fs.readdir(extractDir);
+            const pastaRaiz = path.join(extractDir, extraidos[0]);
+
+            // Copia apenas o subdiretório desejado para o destino
+            const pastaDesejada = path.join(pastaRaiz, caminhoRemoto);
+
+            if (!await fs.pathExists(pastaDesejada)) {
+                throw new Error(`Caminho "${caminhoRemoto}" não encontrado no repositório.`);
+            }
+
+            await fs.copy(pastaDesejada, destinoLocal);
+
+            // Limpa arquivos temporários
+            await fs.remove(tarballPath);
+            await fs.remove(extractDir);
+
+            this.logger.sucesso(`Download concluído: ${caminhoRemoto}`);
+
+        } catch (erro) {
+            this.logger.erro(`Falha no download de "${caminhoRemoto}": ${erro.message}`);
+            throw erro;
+        }
+    }
+
+    /**
+     * Download via tiged — funciona apenas com repos públicos.
+     * Mais rápido pois baixa diretamente o subdiretório.
+     * 
+     * @param {string} caminhoRemoto - Subcaminho no repositório
+     * @param {string} destinoLocal - Pasta de destino
+     * @private
+     */
+    async _baixarViaTiged(caminhoRemoto, destinoLocal) {
+        const origem = `${TIGED_BASE}/${caminhoRemoto}`;
+
+        this.logger.info(`Baixando: ${caminhoRemoto}...`);
+
+        try {
+            const emitter = tiged(origem, {
+                disableCache: true,
+                force: true,
+                verbose: false,
+            });
+
+            // Escuta eventos do tiged para feedback
+            emitter.on('info', (info) => {
+                this.logger.sutil(info.message);
+            });
+
+            emitter.on('warn', (warning) => {
+                this.logger.aviso(warning.message);
+            });
+
+            await emitter.clone(destinoLocal);
+
+            this.logger.sucesso(`Download concluído: ${caminhoRemoto}`);
+        } catch (erro) {
+            this.logger.erro(`Falha no download de "${caminhoRemoto}": ${erro.message}`);
+            throw erro;
+        }
+    }
+}

package/src/services/GitHubService.js

@@ -0,0 +1,99 @@
+/**
+ * GitHubService — Comunicação com a API do GitHub.
+ * 
+ * Responsável por listar kits e componentes disponíveis
+ * no repositório remoto. Suporta repositórios públicos e privados
+ * através do TokenManager para autenticação.
+ * 
+ * Princípio: Responsabilidade Única (SRP)
+ * Princípio: Inversão de Dependência (DIP) — recebe logger e tokenManager via construtor
+ */
+
+import { GITHUB_API_BASE, REMOTE_PATHS } from '../config/constants.js';
+
+export class GitHubService {
+
+    /**
+     * @param {import('../utils/logger.js').Logger} logger - Instância do logger
+     * @param {import('../auth/TokenManager.js').TokenManager} tokenManager - Gerenciador de tokens
+     */
+    constructor(logger, tokenManager) {
+        this.logger = logger;
+        this.tokenManager = tokenManager;
+    }
+
+    /**
+     * Busca o conteúdo de um diretório no repositório GitHub.
+     * Usa autenticação se houver token configurado.
+     * 
+     * @param {string} caminho - Caminho relativo no repositório
+     * @returns {Promise<Array>} Lista de itens no diretório
+     */
+    async listarDiretorio(caminho) {
+        const url = `${GITHUB_API_BASE}/${caminho}`;
+        const headers = await this.tokenManager.obterHeaders();
+
+        try {
+            const resposta = await fetch(url, { headers });
+
+            if (resposta.status === 401 || resposta.status === 403) {
+                throw new Error(
+                    'Acesso negado. Verifique se o token está correto.\n' +
+                    '   Execute "rook config" para reconfigurar.'
+                );
+            }
+
+            if (resposta.status === 404) {
+                const temToken = await this.tokenManager.temToken();
+                const dica = temToken
+                    ? 'Verifique se o caminho existe no repositório.'
+                    : 'Se o repositório é privado, execute "rook config" para configurar o token.';
+                throw new Error(`Repositório ou caminho não encontrado. ${dica}`);
+            }
+
+            if (!resposta.ok) {
+                throw new Error(`Erro HTTP ${resposta.status}: ${resposta.statusText}`);
+            }
+
+            const dados = await resposta.json();
+            return dados;
+        } catch (erro) {
+            this.logger.erro(`Falha ao acessar o repositório: ${erro.message}`);
+            throw erro;
+        }
+    }
+
+    /**
+     * Lista os kits disponíveis no repositório.
+     * @returns {Promise<Array<{nome: string, caminho: string}>>} Lista de kits
+     */
+    async listarKits() {
+        this.logger.info('Buscando kits disponíveis...');
+
+        const itens = await this.listarDiretorio(REMOTE_PATHS.KITS);
+
+        return itens
+            .filter(item => item.type === 'dir')
+            .map(item => ({
+                nome: item.name,
+                caminho: `${REMOTE_PATHS.KITS}/${item.name}`,
+            }));
+    }
+
+    /**
+     * Lista os componentes individuais disponíveis no repositório.
+     * @returns {Promise<Array<{nome: string, caminho: string}>>} Lista de componentes
+     */
+    async listarComponentes() {
+        this.logger.info('Buscando componentes disponíveis...');
+
+        const itens = await this.listarDiretorio(REMOTE_PATHS.COMPONENTS);
+
+        return itens
+            .filter(item => item.type === 'dir')
+            .map(item => ({
+                nome: item.name,
+                caminho: `${REMOTE_PATHS.COMPONENTS}/${item.name}`,
+            }));
+    }
+}

package/src/ui/PromptUI.js

@@ -0,0 +1,84 @@
+/**
+ * PromptUI — Interface interativa do terminal.
+ * 
+ * Gerencia todos os menus e prompts de seleção
+ * apresentados ao usuário via @inquirer/prompts.
+ * 
+ * Princípio: Responsabilidade Única (SRP) — lida apenas com UI
+ * Princípio: Aberto/Fechado (OCP) — fácil adicionar novos menus
+ */
+
+import { select, checkbox } from '@inquirer/prompts';
+
+export class PromptUI {
+
+    /**
+     * Exibe o menu principal com as opções de instalação.
+     * 
+     * @returns {Promise<string>} Opção selecionada ('kit' ou 'componente')
+     */
+    async menuPrincipal() {
+        const escolha = await select({
+            message: 'O que você deseja instalar?',
+            choices: [
+                {
+                    name: '🎯 Kit Base — Estrutura completa para iniciar projetos',
+                    value: 'kit',
+                    description: 'Instala todos os arquivos base de um kit',
+                },
+                {
+                    name: '🧩 Componente Individual — Selecione itens específicos',
+                    value: 'componente',
+                    description: 'Escolha componentes como botões, menus, etc.',
+                },
+            ],
+        });
+
+        return escolha;
+    }
+
+    /**
+     * Exibe a lista de kits disponíveis para seleção.
+     * 
+     * @param {Array<{nome: string, caminho: string}>} kits - Kits disponíveis
+     * @returns {Promise<{nome: string, caminho: string}>} Kit selecionado
+     */
+    async selecionarKit(kits) {
+        if (kits.length === 0) {
+            throw new Error('Nenhum kit disponível no repositório.');
+        }
+
+        const caminho = await select({
+            message: '🎯 Selecione o kit para instalar:',
+            choices: kits.map(kit => ({
+                name: `📁 ${kit.nome}`,
+                value: kit.caminho,
+            })),
+        });
+
+        return kits.find(k => k.caminho === caminho);
+    }
+
+    /**
+     * Exibe a lista de componentes para seleção múltipla (checkbox).
+     * 
+     * @param {Array<{nome: string, caminho: string}>} componentes - Componentes disponíveis
+     * @returns {Promise<Array<{nome: string, caminho: string}>>} Componentes selecionados
+     */
+    async selecionarComponentes(componentes) {
+        if (componentes.length === 0) {
+            throw new Error('Nenhum componente disponível no repositório.');
+        }
+
+        const selecionados = await checkbox({
+            message: '🧩 Selecione os componentes desejados (espaço para marcar):',
+            choices: componentes.map(comp => ({
+                name: `📦 ${comp.nome}`,
+                value: comp.caminho,
+            })),
+            required: true,
+        });
+
+        return componentes.filter(c => selecionados.includes(c.caminho));
+    }
+}

package/src/utils/logger.js

@@ -0,0 +1,73 @@
+/**
+ * Logger — Responsável pela saída visual no terminal.
+ * 
+ * Encapsula o uso do picocolors para fornecer
+ * métodos semânticos de log (sucesso, erro, info, etc).
+ * 
+ * Princípio: Responsabilidade Única (SRP)
+ */
+
+import pc from 'picocolors';
+
+export class Logger {
+
+    /**
+     * Exibe uma mensagem de informação (azul).
+     * @param {string} mensagem - Texto a ser exibido
+     */
+    info(mensagem) {
+        console.log(pc.cyan(`ℹ  ${mensagem}`));
+    }
+
+    /**
+     * Exibe uma mensagem de sucesso (verde).
+     * @param {string} mensagem - Texto a ser exibido
+     */
+    sucesso(mensagem) {
+        console.log(pc.green(`✔  ${mensagem}`));
+    }
+
+    /**
+     * Exibe uma mensagem de aviso (amarelo).
+     * @param {string} mensagem - Texto a ser exibido
+     */
+    aviso(mensagem) {
+        console.log(pc.yellow(`⚠  ${mensagem}`));
+    }
+
+    /**
+     * Exibe uma mensagem de erro (vermelho).
+     * @param {string} mensagem - Texto a ser exibido
+     */
+    erro(mensagem) {
+        console.error(pc.red(`✖  ${mensagem}`));
+    }
+
+    /**
+     * Exibe o banner/header do CLI.
+     */
+    banner() {
+        console.log('');
+        console.log(pc.bold(pc.magenta('  ╔══════════════════════════════╗')));
+        console.log(pc.bold(pc.magenta('  ║    🚀  ROOK CLI  v1.0.0    ║')));
+        console.log(pc.bold(pc.magenta('  ║   Shopify Component Tool    ║')));
+        console.log(pc.bold(pc.magenta('  ╚══════════════════════════════╝')));
+        console.log('');
+    }
+
+    /**
+     * Exibe texto em destaque (negrito).
+     * @param {string} mensagem - Texto a ser exibido
+     */
+    destaque(mensagem) {
+        console.log(pc.bold(mensagem));
+    }
+
+    /**
+     * Exibe texto esmaecido (para detalhes secundários).
+     * @param {string} mensagem - Texto a ser exibido
+     */
+    sutil(mensagem) {
+        console.log(pc.dim(`   ${mensagem}`));
+    }
+}