diff --git a/.stackcoderc.json b/.stackcoderc.json index a7925ec..ce9c728 100644 --- a/.stackcoderc.json +++ b/.stackcoderc.json @@ -1,5 +1,5 @@ { "features": { - "commitValidation": false + "commitValidation": true } } diff --git a/CHANGELOG.md b/CHANGELOG.md index dc18ed0..594e3e4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,11 @@ +# Changelog + +## [Unreleased] + +### Added + +- feat: 🦺 add system dependency validation - Intelligent validation of required tools before project initialization with helpful installation instructions + ## (2025-07-27) - fix: 🐛 Add missing build script to core package ([abe05e0](https://github.com/YagoBorba/StackCode/commit/abe05e0)) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99f6879..f7523f0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,6 +23,7 @@ Before contributing, please familiarize yourself with the project architecture: - **[🛠️ Technology Stacks](docs/STACKS.md)** - Supported frameworks and project templates Understanding the architecture will help you: + - Choose the right package for your changes - Follow established patterns and conventions - Understand cross-package dependencies @@ -220,10 +221,33 @@ Update the stack choices in `packages/cli/src/commands/ui.ts`: #### Step 6: Update Package Manager Logic -If your stack uses a different package manager, update the dependency installation logic in `packages/cli/src/commands/init.ts`: +When adding a new stack, you need to update two areas to handle dependency management: + +**A. Add stack dependencies mapping in `packages/core/src/utils.ts`:** + +```typescript +export function getStackDependencies(stack: string): string[] { + const stackMap: Record = { + go: ["go"], + php: ["composer", "php"], + java: ["mvn", "java"], + python: ["pip", "python"], + "your-stack-name": ["your-tool", "another-tool"], // Add your stack here + // Node.js stacks use npm + "node-js": ["npm"], + "node-ts": ["npm"], + react: ["npm"], + vue: ["npm"], + }; + return stackMap[stack] || ["npm"]; +} +``` + +**B. Update dependency installation logic in `packages/cli/src/commands/init.ts`:** ```typescript -// Install dependencies based on the stack type +// The validation is now handled automatically, but you still need to +// specify the installation command for your stack if (answers.stack === "python") { await runCommand("pip", ["install", "-e", "."], { cwd: projectPath }); } else if (answers.stack === "java") { @@ -240,7 +264,63 @@ if (answers.stack === "python") { } ``` -### 3. Best Practices for New Stacks +**C. Add installation instructions in i18n files:** + +Add entries to both `packages/i18n/src/locales/en.json` and `packages/i18n/src/locales/pt.json`: + +```json +{ + "init": { + "dependencies": { + "install_your_tool": " - Your Tool: https://example.com/install" + } + } +} +``` + +### 3. System Dependency Validation + +StackCode now includes intelligent dependency validation that checks if required tools are installed before attempting to create projects. This prevents crashes and provides helpful guidance to users. + +#### How It Works + +1. **Pre-validation**: Before installing dependencies, StackCode checks if required tools are available in the system PATH +2. **User feedback**: If tools are missing, users see: + - Clear warnings about missing dependencies + - Direct download links for each missing tool + - Option to continue without installing dependencies +3. **Graceful handling**: Even if dependencies fail to install, the project structure is still created successfully + +#### Supported Stack Dependencies + +| Stack | Required Tools | Validation | +| ------------------------------------ | ----------------- | ---------- | +| `go` | `go` | ✅ | +| `php` | `composer`, `php` | ✅ | +| `java` | `mvn`, `java` | ✅ | +| `python` | `pip`, `python` | ✅ | +| `node-js`, `node-ts`, `react`, `vue` | `npm` | ✅ | + +#### Testing Dependency Validation + +To test the validation system: + +```bash +# Test with missing dependencies (assuming Go is not installed) +stc init +# Choose "Go + Gin" stack +# You should see warnings and installation instructions + +# Test validation programmatically +node -e " +const { validateStackDependencies } = require('@stackcode/core'); +validateStackDependencies('go').then(result => + console.log('Result:', result) +); +" +``` + +### 4. Best Practices for New Stacks #### Template Structure Guidelines: @@ -390,5 +470,6 @@ Thank you again for your interest in contributing! --- ## Documentation + - [Architecture Guide](docs/ARCHITECTURE.md) - [Self-Hosting Guide](docs/SELF_HOSTING_GUIDE.md) diff --git a/README.md b/README.md index 8691d6c..ecdaa01 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ Our goal is to make best practices the easiest path. StackCode is a suite of tools designed to work together seamlessly: - 🚀 **Effortless Project Scaffolding (`init`):** - Generate a complete, production-ready project structure in seconds. Choose from multiple technology stacks including Node.js, React, Vue.js, Python, Java, Go, and PHP—each with best practices and optimal folder structures. + Generate a complete, production-ready project structure in seconds. Choose from multiple technology stacks including Node.js, React, Vue.js, Python, Java, Go, and PHP—each with best practices and optimal folder structures. **Now with intelligent dependency validation** that checks if required tools are installed before proceeding, providing helpful installation instructions when needed. - 📝 **Intelligent File Generation (`generate`):** Need a `.gitignore`? Don't just get one—get a perfect one. Our composable template engine combines rules for your stack, IDE, and tools (like Docker) into a single, organized file. @@ -114,10 +114,10 @@ For detailed information about the project: ### 🌐 Documentation in Other Languages -- **[🇧🇷 Português (Brasil)](docs/pt-BR/)** - Documentação em português *(em desenvolvimento)* -- **[🇪🇸 Español](docs/es/)** - Documentación en español *(en desarrollo)* +- **[🇧🇷 Português (Brasil)](docs/pt-BR/)** - Documentação em português _(em desenvolvimento)_ +- **[🇪🇸 Español](docs/es/)** - Documentación en español _(en desarrollo)_ -*Want to help translate the documentation? Check our [contribution guide](docs/CONTRIBUTING.md#internationalization)!* +_Want to help translate the documentation? Check our [contribution guide](docs/CONTRIBUTING.md#internationalization)!_ ## 🤝 Want to Contribute? diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 901a6ab..81cc36e 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -45,15 +45,18 @@ StackCode follows a **modular monorepo architecture** with clear separation of c ## 📦 Package Structure ### 1. **@stackcode/cli** - Command Line Interface + **Purpose:** Primary user interface for StackCode functionality. **Key Components:** + - **Command Layer:** Entry points for all CLI operations - **Command Handlers:** Individual command implementations - **Interactive Prompts:** User guidance and input collection - **Error Handling:** Consistent error reporting and recovery **Architecture:** + ```typescript cli/ ├── src/ @@ -71,16 +74,20 @@ cli/ ``` ### 2. **@stackcode/core** - Business Logic Engine + **Purpose:** Contains all business logic, utilities, and templates. **Key Components:** + - **Generators:** Project and file generation logic -- **Validators:** Commit message and project validation +- **Validators:** Commit message validation and system dependency validation - **GitHub Integration:** API interactions and automation - **Release Management:** Semantic versioning and changelog generation - **Template System:** Configurable project templates +- **Dependency Validation:** Intelligent system tool validation **Architecture:** + ```typescript core/ ├── src/ @@ -107,15 +114,18 @@ core/ ``` ### 3. **@stackcode/i18n** - Internationalization + **Purpose:** Manages multi-language support across all packages. **Features:** + - Dynamic locale detection - Translation loading and caching - Language switching - Fallback mechanisms **Architecture:** + ```typescript i18n/ ├── src/ @@ -126,9 +136,11 @@ i18n/ ``` ### 4. **stackcode-vscode** - VS Code Extension + **Purpose:** Integrates StackCode functionality directly into VS Code. **Key Components:** + - **Extension Commands:** VS Code command palette integration - **File Monitors:** Real-time file change detection - **Git Monitors:** Git state monitoring @@ -137,6 +149,7 @@ i18n/ - **Notification System:** Proactive user guidance **Architecture:** + ```typescript vscode-extension/ ├── src/ @@ -154,6 +167,7 @@ vscode-extension/ ## 🔄 Data Flow and Interactions ### Command Execution Flow + 1. **User Input:** CLI command or VS Code action 2. **Command Parsing:** Yargs (CLI) or VS Code API 3. **Core Logic:** Business logic execution in `@stackcode/core` @@ -161,6 +175,7 @@ vscode-extension/ 5. **Output:** Results displayed to user ### Cross-Package Dependencies + ```mermaid graph TD A[CLI Package] --> C[Core Package] @@ -173,42 +188,110 @@ graph TD ## 🎯 Design Principles ### 1. **Separation of Concerns** + - **CLI Package:** User interface and command handling - **Core Package:** Business logic and utilities - **i18n Package:** Internationalization concerns - **VS Code Extension:** IDE integration ### 2. **Dependency Inversion** + - Higher-level modules don't depend on lower-level modules - Both depend on abstractions (interfaces) - External dependencies are injected, not hardcoded ### 3. **Single Responsibility** + - Each package has a clearly defined purpose - Functions and classes have single, well-defined responsibilities - Templates are modular and composable ### 4. **Open/Closed Principle** + - System is open for extension (new templates, commands) - Closed for modification (core logic remains stable) -## 🛠️ Technology Stack +## � System Validation Architecture + +### Dependency Validation System + +StackCode implements a comprehensive dependency validation system to ensure smooth project initialization across different technology stacks. + +#### Core Components + +**1. Command Availability Detection (`isCommandAvailable`)** + +```typescript +// Cross-platform command detection +const isAvailable = await isCommandAvailable("go"); +// Uses 'which' (Unix) or 'where' (Windows) +``` + +**2. Stack Dependency Mapping (`getStackDependencies`)** + +```typescript +const stackMap = { + go: ["go"], + php: ["composer", "php"], + java: ["mvn", "java"], + python: ["pip", "python"], + react: ["npm"], + vue: ["npm"], +}; +``` + +**3. Comprehensive Validation (`validateStackDependencies`)** + +```typescript +const result = await validateStackDependencies("go"); +// Returns: { isValid, missingDependencies, availableDependencies } +``` + +#### Validation Flow + +```mermaid +graph TD + A[User runs 'stc init'] --> B[Select Technology Stack] + B --> C[Validate Stack Dependencies] + C --> D{All Dependencies Available?} + D -->|Yes| E[✅ Proceed with Installation] + D -->|No| F[⚠️ Show Missing Dependencies] + F --> G[Display Installation Instructions] + G --> H{User Chooses to Continue?} + H -->|Yes| I[🚧 Create Project Structure Only] + H -->|No| J[❌ Cancel Operation] + E --> K[🎉 Complete Project Setup] + I --> L[⚠️ Manual Dependency Installation Required] +``` + +#### Error Handling Strategy + +- **Graceful Degradation:** Project creation succeeds even without dependencies +- **Informative Messaging:** Clear installation instructions with official URLs +- **User Choice:** Option to proceed or cancel when dependencies are missing +- **i18n Support:** Error messages localized in multiple languages + +## �🛠️ Technology Stack ### Core Technologies + - **TypeScript:** Type safety and modern JavaScript features - **Node.js:** Runtime environment - **ESM:** Modern module system ### CLI-Specific + - **Yargs:** Command-line argument parsing - **Inquirer:** Interactive command-line prompts ### VS Code Extension-Specific + - **VS Code API:** Extension development framework - **React:** Webview UI components - **Vite:** Build tool for webview assets ### Development Tools + - **Vitest/Jest:** Testing frameworks - **ESLint:** Code linting - **Prettier:** Code formatting @@ -217,6 +300,7 @@ graph TD ## 📁 File Organization Strategy ### Monorepo Structure + ``` StackCode/ ├── packages/ # All packages @@ -230,7 +314,9 @@ StackCode/ ``` ### Package Structure Conventions + Each package follows consistent patterns: + - `src/` - Source code - `test/` - Test files - `dist/` - Compiled output @@ -242,11 +328,13 @@ Each package follows consistent patterns: ## 🔧 Build System ### TypeScript Compilation + - **Monorepo Build:** `tsc --build` for cross-package dependencies - **Asset Copying:** Templates and locales copied to `dist/` - **Executable Permissions:** CLI entry point marked as executable ### VS Code Extension Build + - **Extension Compilation:** TypeScript to JavaScript - **Webview Build:** Vite for React components - **Package Generation:** `.vsix` file creation @@ -254,34 +342,89 @@ Each package follows consistent patterns: ## 🧪 Testing Strategy ### Unit Testing + - **Core Logic:** Comprehensive tests for business logic - **CLI Commands:** Command execution and error handling - **Validators:** Input validation and error cases ### Integration Testing + - **Cross-Package:** Ensure packages work together - **Template Generation:** Verify output correctness - **GitHub Integration:** API interaction testing -## 🚀 Deployment and Distribution +## �️ Dependency Validation System + +### Architecture Overview + +StackCode includes an intelligent dependency validation system that prevents crashes and provides helpful guidance when required tools are missing. + +### Components + +#### 1. **Command Detection (`isCommandAvailable`)** + +```typescript +// Checks if a command exists in system PATH +const isGoAvailable = await isCommandAvailable("go"); +``` + +#### 2. **Stack Mapping (`getStackDependencies`)** + +```typescript +// Maps each stack to its required tools +const goDeps = getStackDependencies("go"); // Returns: ['go'] +const phpDeps = getStackDependencies("php"); // Returns: ['composer', 'php'] +``` + +#### 3. **Validation Engine (`validateStackDependencies`)** + +```typescript +// Comprehensive validation with detailed results +const result = await validateStackDependencies("go"); +// Returns: { isValid: boolean, missingDependencies: string[], availableDependencies: string[] } +``` + +### Validation Flow + +1. **Pre-Installation Check:** Before attempting dependency installation +2. **User Notification:** Clear warnings about missing tools +3. **Installation Guidance:** Direct links to download missing dependencies +4. **Graceful Degradation:** Option to continue without tools +5. **Error Handling:** Controlled failure instead of crashes + +### Supported Stack Dependencies + +| Stack | Required Tools | Validation Status | +| ------------------------------------ | ----------------- | ----------------- | +| `go` | `go` | ✅ | +| `php` | `composer`, `php` | ✅ | +| `java` | `mvn`, `java` | ✅ | +| `python` | `pip`, `python` | ✅ | +| `node-js`, `node-ts`, `react`, `vue` | `npm` | ✅ | + +## �🚀 Deployment and Distribution ### NPM Packages + - **@stackcode/cli:** Published to NPM for global installation - **@stackcode/core:** Internal package, not published separately - **@stackcode/i18n:** Internal package, not published separately ### VS Code Extension + - **Marketplace:** Published to VS Code Marketplace - **VSIX:** Direct installation package available ## 🔮 Extensibility Points ### Template System + - **Custom Templates:** Easy addition of new project types - **Template Composition:** Combining multiple template sources - **Dynamic Configuration:** Runtime template customization ### Command System + - **Plugin Architecture:** Future support for custom commands - **Middleware Support:** Pre/post command hooks - **Configuration Extension:** Custom validation and generation rules diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 50e9c7f..376293d 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -19,6 +19,7 @@ Before contributing, familiarize yourself with the project architecture: - **[🛠️ Technology Stacks](STACKS.md)** - Supported frameworks and project templates Understanding the architecture will help you: + - Choose the right package for your changes - Follow established patterns and conventions - Understand cross-package dependencies @@ -27,26 +28,30 @@ Understanding the architecture will help you: ## 🚀 Development Setup 1. **Fork and Clone** + ```bash git clone https://github.com/your-username/StackCode.git cd StackCode ``` 2. **Install Dependencies** + ```bash npm install ``` 3. **Build the Project** + ```bash npm run build ``` 4. **Test Your Setup** + ```bash # Run tests npm test - + # Test CLI locally node packages/cli/dist/index.js --help ``` @@ -54,34 +59,46 @@ Understanding the architecture will help you: ## 🤝 How to Contribute ### 🐛 Bug Reports + - Check [existing issues](https://github.com/YagoBorba/StackCode/issues) first - Provide clear reproduction steps - Include environment details (OS, Node.js version, etc.) - Use the bug report template ### ✨ Feature Requests + - Open an issue to discuss the feature first - Explain the use case and benefits - Consider if it fits the project's scope - Provide implementation ideas if possible ### 📝 Documentation Improvements + - Fix typos, improve clarity, add examples - Update docs when adding new features - Help with translations (see [Internationalization](#internationalization)) ### 🛠️ Code Contributions + - Pick up issues labeled `good-first-issue` or `help-wanted` - Follow the [development workflow](#development-workflow) - Ensure all tests pass - Add tests for new functionality ### 🌐 Adding New Technology Stacks + See the comprehensive guide in [main CONTRIBUTING.md](../CONTRIBUTING.md#adding-new-technology-stacks). +**Important**: When adding new stacks, ensure you update the dependency validation system by: + +- Adding stack dependencies to `getStackDependencies()` in `packages/core/src/utils.ts` +- Adding installation instructions to i18n files (`packages/i18n/src/locales/`) +- Testing the validation flow with and without required tools installed + ## 🔄 Development Workflow 1. **Create a Feature Branch** + ```bash git checkout develop git pull origin develop @@ -94,6 +111,7 @@ See the comprehensive guide in [main CONTRIBUTING.md](../CONTRIBUTING.md#adding- - Update documentation as needed 3. **Test Thoroughly** + ```bash npm test npm run lint @@ -101,6 +119,7 @@ See the comprehensive guide in [main CONTRIBUTING.md](../CONTRIBUTING.md#adding- ``` 4. **Commit Your Changes** + ```bash # Use conventional commits with emojis git commit -m "feat(cli): ✨ add new project template" @@ -115,18 +134,21 @@ See the comprehensive guide in [main CONTRIBUTING.md](../CONTRIBUTING.md#adding- ## 🎨 Coding Standards ### General Principles + - **Clean Code**: Write readable, maintainable code - **SOLID Principles**: Follow SOLID design principles - **Single Responsibility**: Each function/class should have one purpose - **Documentation**: Use TSDoc comments for public APIs ### TypeScript Guidelines + - Use strict TypeScript configuration - Prefer explicit types over `any` - Use interfaces for object shapes - Follow ESLint rules ### Testing Requirements + - Add unit tests for new functionality - Maintain or improve test coverage - Test both success and error scenarios @@ -137,6 +159,7 @@ See the comprehensive guide in [main CONTRIBUTING.md](../CONTRIBUTING.md#adding- We welcome contributions to support more languages: ### Current Structure + ``` packages/i18n/src/locales/ ├── en.json # English (primary) @@ -146,12 +169,14 @@ packages/i18n/src/locales/ ### Adding New Languages 1. **Create Locale File** + ```bash # Example for Spanish cp packages/i18n/src/locales/en.json packages/i18n/src/locales/es.json ``` 2. **Translate Strings** + ```json { "commands": { @@ -168,6 +193,7 @@ packages/i18n/src/locales/ ``` ### Future Structure (Planned) + ``` docs/ ├── pt-BR/ # Portuguese (Brazil) @@ -179,12 +205,14 @@ docs/ ## 📏 Code Review Process ### For Contributors + - Keep PRs focused and small - Write clear PR descriptions - Respond to feedback promptly - Update documentation as needed ### Review Criteria + - Code quality and maintainability - Test coverage and quality - Documentation completeness @@ -223,6 +251,7 @@ Need help contributing? ## 🙏 Recognition All contributors are recognized in: + - [Contributors section](../README.md#contributors) in README - Git commit history - Release notes for significant contributions @@ -232,6 +261,7 @@ Thank you for helping make StackCode better! 🚀 --- For more details, see: + - **[Main README](../README.md)** - Project overview - **[Architecture Guide](ARCHITECTURE.md)** - Technical details - **[Self-Hosting Guide](SELF_HOSTING_GUIDE.md)** - Deployment options diff --git a/docs/README.md b/docs/README.md index a97c867..49a5848 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,12 +5,14 @@ Welcome to the StackCode documentation hub! This directory contains comprehensiv ## 📋 Quick Navigation ### 🏗️ **Core Documentation** + - **[📐 Architecture Guide](ARCHITECTURE.md)** - Complete technical overview of the monorepo structure, design principles, and component interactions - **[🛠️ Technology Stacks](STACKS.md)** - Detailed list of supported frameworks, templates, and project types - **[🤝 Contributing Guide](CONTRIBUTING.md)** - Everything you need to know to contribute to StackCode - **[🚀 Self-Hosting Guide](SELF_HOSTING_GUIDE.md)** - Deploy and customize StackCode for your organization ### 🏛️ **Architecture Decisions** + - **[ADR Directory](adr/)** - Architectural Decision Records documenting key design choices - [ADR-001: Monorepo Structure](adr/001-monorepo-structure.md) - [ADR-002: TypeScript and ES Modules](adr/002-typescript-esm.md) @@ -18,25 +20,32 @@ Welcome to the StackCode documentation hub! This directory contains comprehensiv - [ADR-004: Internationalization Strategy](adr/004-i18n-strategy.md) ### 🌐 **Translations** -- **[🇧🇷 Português (Brasil)](pt-BR/)** - Documentação em português *(em desenvolvimento)* -- **[🇪🇸 Español](es/)** - Documentación en español *(en desarrollo)* + +- **[🇧🇷 Português (Brasil)](pt-BR/)** - Documentação em português _(em desenvolvimento)_ +- **[🇪🇸 Español](es/)** - Documentación en español _(en desarrollo)_ ## 🎯 **Documentation by Audience** ### 👩‍💻 **For Developers Using StackCode** + Start here if you want to use StackCode in your projects: + 1. [Main README](../README.md) - Project overview and getting started 2. [Technology Stacks](STACKS.md) - See what project types are supported 3. [Self-Hosting Guide](SELF_HOSTING_GUIDE.md) - Deploy for your organization ### 🛠️ **For Contributors** + Start here if you want to contribute to StackCode: + 1. [Contributing Guide](CONTRIBUTING.md) - How to contribute effectively 2. [Architecture Guide](ARCHITECTURE.md) - Understand the codebase 3. [ADR Directory](adr/) - Learn about architectural decisions ### 🏢 **For Organizations** + Start here if you want to deploy StackCode internally: + 1. [Self-Hosting Guide](SELF_HOSTING_GUIDE.md) - Deployment and customization 2. [Architecture Guide](ARCHITECTURE.md) - Technical overview 3. [Contributing Guide](CONTRIBUTING.md) - How to contribute improvements back @@ -44,6 +53,7 @@ Start here if you want to deploy StackCode internally: ## 🔧 **Technical Reference** ### Project Structure + ``` docs/ ├── README.md # This file @@ -64,6 +74,7 @@ docs/ ``` ### Key Concepts + - **Monorepo Architecture**: StackCode uses a monorepo with multiple packages - **Template System**: Configurable project templates for different technologies - **CLI + VS Code Extension**: Multiple interfaces for the same core functionality @@ -74,16 +85,19 @@ docs/ We welcome improvements to our documentation! Here's how to help: ### Quick Fixes + - Fix typos, broken links, or unclear explanations - Add examples or improve existing ones - Update outdated information ### Major Contributions + - Write new guides or tutorials - Create documentation for new features - Help with translations ### Translation Help + - Translate existing documentation to your language - Review translations by other contributors - Maintain consistency across translations @@ -106,4 +120,4 @@ Need help with StackCode? --- -*Last updated: September 2025 | StackCode Documentation Team* +_Last updated: September 2025 | StackCode Documentation Team_ diff --git a/docs/SELF_HOSTING_GUIDE.md b/docs/SELF_HOSTING_GUIDE.md index c3b8399..04a2079 100644 --- a/docs/SELF_HOSTING_GUIDE.md +++ b/docs/SELF_HOSTING_GUIDE.md @@ -39,12 +39,14 @@ npm link For organizations with private NPM registries: 1. **Fork the Repository** + ```bash git clone https://github.com/your-org/StackCode.git cd StackCode ``` 2. **Customize Package Configuration** + ```json // In packages/cli/package.json { @@ -89,15 +91,17 @@ docker run -it your-org/stackcode init ### Template Customization 1. **Add Custom Templates** + ```bash # Create your organization's templates mkdir packages/core/src/templates/your-org-stack - + # Add template files with .tpl extension # Use {{variableName}} for replacements ``` 2. **Modify Existing Templates** + ```bash # Edit existing templates in packages/core/src/templates/ # Update package.json dependencies @@ -107,15 +111,13 @@ docker run -it your-org/stackcode init 3. **Update Type Definitions** ```typescript // In packages/core/src/types.ts - export type SupportedStack = - | "node-js" - | "react" - | "your-custom-stack" // Add your stack + export type SupportedStack = "node-js" | "react" | "your-custom-stack"; // Add your stack ``` ### Configuration Customization 1. **Default Configuration** + ```json // Create .stackcoderc in your users' home directories { @@ -213,6 +215,7 @@ Organization Setup: ### Common Issues 1. **Permission Errors** + ```bash # Fix NPM permissions sudo chown -R $(whoami) ~/.npm @@ -220,19 +223,21 @@ Organization Setup: ``` 2. **Template Not Found** + ```bash # Verify template location ls packages/core/src/templates/ - + # Check build output ls packages/core/dist/templates/ ``` 3. **Registry Issues** + ```bash # Check registry configuration npm config get registry - + # Test registry connectivity npm ping --registry https://your-registry.com ``` @@ -273,4 +278,4 @@ For self-hosting support: --- -*For more information about StackCode architecture and development, see the [Architecture Guide](ARCHITECTURE.md).* +_For more information about StackCode architecture and development, see the [Architecture Guide](ARCHITECTURE.md)._ diff --git a/docs/STACKS.md b/docs/STACKS.md index 0074d9c..f13b503 100644 --- a/docs/STACKS.md +++ b/docs/STACKS.md @@ -2,11 +2,38 @@ StackCode supports multiple technology stacks, each designed with best practices and optimal project structures. This document provides an overview of all **currently implemented** stacks based on the available templates in the core package. -## 📋 Currently Available Stacks +## � Dependency Validation + +StackCode automatically validates that all required tools for your chosen stack are installed before proceeding with project creation. This ensures a smooth setup experience and prevents common installation errors. + +### How It Works + +1. **Automatic Detection**: When you run `stc init`, StackCode checks if the required tools are available in your system PATH +2. **Clear Feedback**: If tools are missing, you'll see exactly which ones need to be installed +3. **Installation Guidance**: Direct links to official installation pages for missing tools +4. **Flexible Continuation**: Option to proceed with project creation even if some tools are missing + +### Stack Dependencies + +| Stack | Required Tools | Validation | +| ------------------------ | ----------------- | ------------ | +| **React + TypeScript** | `npm` | ✅ Automatic | +| **Vue.js + TypeScript** | `npm` | ✅ Automatic | +| **Node.js + Express** | `npm` | ✅ Automatic | +| **Node.js + TypeScript** | `npm` | ✅ Automatic | +| **Go + Gin** | `go` | ✅ Automatic | +| **PHP + Laravel** | `composer`, `php` | ✅ Automatic | +| **Java + Spring Boot** | `mvn`, `java` | ✅ Automatic | +| **Python + FastAPI** | `pip`, `python` | ✅ Automatic | + +> **💡 Tip**: If you see dependency warnings, you can still create the project structure. You'll just need to install the dependencies manually afterward. + +## �📋 Currently Available Stacks ### Frontend Stacks #### React + TypeScript + **Template Location:** `packages/core/src/templates/react/` - **Framework**: React 18 with TypeScript @@ -16,6 +43,7 @@ StackCode supports multiple technology stacks, each designed with best practices - **Features**: Modern JSX Transform, ESLint configuration, component structure **Generated Structure:** + ``` ├── src/ │ ├── components/ @@ -31,6 +59,7 @@ StackCode supports multiple technology stacks, each designed with best practices ``` #### Vue.js + TypeScript + **Template Location:** `packages/core/src/templates/vue/` - **Framework**: Vue 3 with Composition API and TypeScript @@ -40,6 +69,7 @@ StackCode supports multiple technology stacks, each designed with best practices - **Features**: SFC (Single File Components), modern Vue patterns **Generated Structure:** + ``` ├── src/ │ ├── components/ @@ -57,6 +87,7 @@ StackCode supports multiple technology stacks, each designed with best practices ### Backend Stacks #### Node.js + JavaScript + **Template Location:** `packages/core/src/templates/node-js/` - **Runtime**: Node.js with ES6+ @@ -65,6 +96,7 @@ StackCode supports multiple technology stacks, each designed with best practices - **Features**: Express.js structure, environment variables, testing setup **Generated Structure:** + ``` ├── src/ │ ├── controllers/ @@ -81,6 +113,7 @@ StackCode supports multiple technology stacks, each designed with best practices ``` #### Node.js + TypeScript + **Template Location:** `packages/core/src/templates/node-ts/` - **Runtime**: Node.js with TypeScript @@ -88,6 +121,7 @@ StackCode supports multiple technology stacks, each designed with best practices - **Features**: Type-safe development, modern TypeScript configuration **Generated Structure:** + ``` ├── src/ │ ├── controllers/ @@ -100,12 +134,14 @@ StackCode supports multiple technology stacks, each designed with best practices ``` #### Python + Modern Setup + **Template Location:** `packages/core/src/templates/python/` - **Package Management**: pip with pyproject.toml - **Features**: Modern Python project structure, dependency management **Generated Structure:** + ``` ├── src/ │ └── main.py @@ -113,12 +149,14 @@ StackCode supports multiple technology stacks, each designed with best practices ``` #### Java + Maven + **Template Location:** `packages/core/src/templates/java/` - **Build Tool**: Maven - **Features**: Standard Java project structure, Maven configuration **Generated Structure:** + ``` ├── src/ │ └── main/ @@ -127,18 +165,21 @@ StackCode supports multiple technology stacks, each designed with best practices ``` #### Go + Modules + **Template Location:** `packages/core/src/templates/go/` - **Package Management**: Go modules - **Features**: Simple Go project with module support **Generated Structure:** + ``` ├── main.go └── go.mod ``` #### PHP + Laravel + **Template Location:** `packages/core/src/templates/php/` - **Framework**: Laravel-style structure @@ -146,6 +187,7 @@ StackCode supports multiple technology stacks, each designed with best practices - **Features**: MVC structure, environment variables **Generated Structure:** + ``` ├── app/ ├── bootstrap/ @@ -154,6 +196,7 @@ StackCode supports multiple technology stacks, each designed with best practices ├── composer.json └── .env.example ``` + - **Package Management**: pip with pyproject.toml - **Features**: Modern Python async API development @@ -217,27 +260,32 @@ Beyond the main project templates, StackCode provides comprehensive `.gitignore` **Template Location:** `packages/core/src/templates/gitignore/` ### Mobile Development + - **Android** (`android.tpl`) - Android Studio, Gradle, APK files - **Flutter** (`flutter.tpl`) - Dart, Flutter build files, platform-specific files - **React Native** (`react_native.tpl`) - Metro bundler, platform builds - **Swift** (`swift.tpl`) - Xcode, iOS development files ### Frontend Frameworks + - **Angular** (`angular.tpl`) - Angular CLI, build artifacts - **Svelte** (`svelte.tpl`) - SvelteKit, build outputs ### Backend & Languages + - **Go** (`go.tpl`) - Go binaries, vendor directories - **Java** (`java.tpl`) - Maven, Gradle, IDE files - **Node.js** (`node-js.tpl`, `node-ts.tpl`) - npm, yarn, build outputs - **PHP** (`php.tpl`) - Composer, Laravel artifacts -- **Python** (`python.tpl`) - pip, virtual environments, __pycache__ +- **Python** (`python.tpl`) - pip, virtual environments, **pycache** - **JavaScript** (`javascript.tpl`) - General JS project files ### Development Tools + - **IDEs** (`ides.tpl`) - VS Code, IntelliJ, Eclipse configurations ### Usage + When creating projects, StackCode automatically selects the appropriate `.gitignore` template based on your chosen stack, and can combine multiple templates when using features like Docker or specific IDEs. ## 🔧 Stack Features @@ -261,12 +309,13 @@ StackCode automatically uses the appropriate package manager based on the projec - **npm** for Node.js-based stacks (React, Vue, Node.js, Node-TS) - **pip** for Python projects (with pyproject.toml) - **maven** for Java projects -- **go mod** for Go projects +- **go mod** for Go projects - **composer** for PHP projects ### Intelligent .gitignore Generation Every project gets a customized `.gitignore` file that combines: + - **Stack-specific rules** (based on chosen technology) - **IDE-specific rules** (common development environments) - **Additional tool rules** (Docker, package managers, build artifacts) diff --git a/docs/adr/001-monorepo-structure.md b/docs/adr/001-monorepo-structure.md index 8f2163a..34d77d9 100644 --- a/docs/adr/001-monorepo-structure.md +++ b/docs/adr/001-monorepo-structure.md @@ -1,16 +1,20 @@ # ADR-001: Monorepo Structure ## Status + Accepted ## Context + StackCode consists of multiple related packages that share common functionality: + - A CLI tool for command-line usage - A VS Code extension for IDE integration - Core business logic that both interfaces use - Internationalization support across all components We needed to decide how to organize these related but distinct packages in a way that: + - Enables code sharing between packages - Maintains clear boundaries between components - Simplifies dependency management @@ -18,13 +22,16 @@ We needed to decide how to organize these related but distinct packages in a way - Reduces development complexity ## Decision + We will use a monorepo structure with the following packages: + - `@stackcode/cli` - Command-line interface - `@stackcode/core` - Shared business logic and utilities - `@stackcode/i18n` - Internationalization support - `stackcode-vscode` - VS Code extension The monorepo will be managed using npm workspaces, providing: + - Shared dependency management - Cross-package linking - Coordinated build processes @@ -33,6 +40,7 @@ The monorepo will be managed using npm workspaces, providing: ## Consequences ### Positive + - **Code Reuse**: Core business logic can be shared between CLI and VS Code extension - **Consistent APIs**: All packages use the same underlying interfaces and types - **Simplified Development**: Single repository checkout provides access to all components @@ -41,17 +49,20 @@ The monorepo will be managed using npm workspaces, providing: - **Easier Testing**: Integration tests can span multiple packages ### Negative + - **Build Complexity**: Build system must handle multiple packages and their dependencies - **Repository Size**: Single repository contains all components, potentially increasing size - **Tool Limitations**: Some tools may not handle monorepos optimally - **Dependency Management**: Changes in core packages affect all dependents ### Risks + - **Circular Dependencies**: Must be careful to avoid circular references between packages - **Build Order**: Package build order becomes important - **Version Coordination**: All packages typically need to be versioned together ### Mitigation Strategies + - Use TypeScript project references to handle build dependencies - Implement clear package boundaries and interfaces - Use npm workspaces for dependency management diff --git a/docs/adr/002-typescript-esm.md b/docs/adr/002-typescript-esm.md index b2dd031..5660ece 100644 --- a/docs/adr/002-typescript-esm.md +++ b/docs/adr/002-typescript-esm.md @@ -1,10 +1,13 @@ # ADR-002: TypeScript and ES Modules ## Status + Accepted ## Context + StackCode is a developer tool that needs to: + - Provide type safety for complex business logic - Support modern JavaScript features - Be compatible with Node.js and browser environments @@ -12,26 +15,31 @@ StackCode is a developer tool that needs to: - Support tree-shaking for optimal bundle sizes We needed to choose: + - Programming language (JavaScript vs TypeScript) - Module system (CommonJS vs ES Modules) - Build tooling and compilation strategy ## Decision + We will use TypeScript with ES Modules (ESM) as our primary development stack: ### TypeScript + - All source code will be written in TypeScript - Strict TypeScript configuration with comprehensive type checking - Shared type definitions across packages - Generate declaration files for published packages ### ES Modules (ESM) + - Use ES Modules as the primary module system - Configure `"type": "module"` in all package.json files - Use `.js` extensions in import statements (TypeScript requirement for ESM) - Support Node.js native ESM loading ### Build Strategy + - Compile TypeScript to JavaScript with ESM output - Use TypeScript project references for monorepo builds - Generate source maps for debugging @@ -40,6 +48,7 @@ We will use TypeScript with ES Modules (ESM) as our primary development stack: ## Consequences ### Positive + - **Type Safety**: Comprehensive compile-time type checking reduces runtime errors - **Modern JavaScript**: Access to latest language features and improvements - **Better IDE Support**: Enhanced autocomplete, refactoring, and navigation @@ -48,24 +57,28 @@ We will use TypeScript with ES Modules (ESM) as our primary development stack: - **Performance**: Native ESM loading in Node.js improves startup time ### Negative + - **Build Complexity**: Requires compilation step and build tooling - **Learning Curve**: Team members need TypeScript knowledge - **Bundle Size**: TypeScript runtime helpers may increase bundle size - **ESM Migration**: Some dependencies may still use CommonJS ### Technical Considerations + - **Import Extensions**: Must use `.js` extensions in TypeScript imports for ESM compatibility - **Dynamic Imports**: Use `import()` for conditional module loading -- **__dirname Replacement**: Use `import.meta.url` for file path resolution +- **\_\_dirname Replacement**: Use `import.meta.url` for file path resolution - **Package Exports**: Define clear entry points in package.json exports field ### Tooling Requirements + - **TypeScript Compiler**: For compilation and type checking - **ESLint with TypeScript**: For code quality and consistency - **Prettier**: For code formatting - **Vitest/Jest**: Testing frameworks with TypeScript support ### Migration Strategy + - Convert all existing JavaScript to TypeScript gradually - Update import statements to use explicit `.js` extensions - Configure build tools to handle TypeScript compilation @@ -74,13 +87,16 @@ We will use TypeScript with ES Modules (ESM) as our primary development stack: ## Alternatives Considered ### JavaScript with JSDoc + - **Pros**: No compilation step, simpler tooling - **Cons**: Less robust type checking, worse IDE support ### CommonJS Modules + - **Pros**: Better ecosystem compatibility, simpler Node.js integration - **Cons**: No tree shaking, legacy module system, worse performance ### Mixed Module System + - **Pros**: Gradual migration, better compatibility - **Cons**: Complexity, confusion, maintenance overhead diff --git a/docs/adr/003-cli-design.md b/docs/adr/003-cli-design.md index 113fc5b..e35b729 100644 --- a/docs/adr/003-cli-design.md +++ b/docs/adr/003-cli-design.md @@ -1,10 +1,13 @@ # ADR-003: Command Line Interface Design ## Status + Accepted ## Context + StackCode provides a comprehensive CLI tool that needs to: + - Support multiple complex commands with subcommands - Provide interactive prompts for user guidance - Handle configuration management @@ -13,33 +16,39 @@ StackCode provides a comprehensive CLI tool that needs to: - Be extensible for future commands We needed to choose: + - CLI framework/library - Command structure and organization - Interactive prompt system - Error handling strategy ## Decision + We will use Yargs as our primary CLI framework with Inquirer for interactive prompts: ### Yargs Framework + - Use Yargs for command parsing, validation, and help generation - Implement command-based architecture with clear separation - Support aliases and shortcuts for common commands - Provide comprehensive help and usage information ### Command Structure + - Each command is implemented as a separate module - Commands follow a consistent interface pattern - Support for subcommands where appropriate (e.g., `git start`, `git finish`) - Global options available across all commands ### Interactive Prompts + - Use Inquirer.js for complex user interactions - Provide guided workflows for complex operations - Validate user input at prompt level - Support default values and smart suggestions ### Error Handling + - Consistent error message formatting - Localized error messages through i18n system - Graceful handling of common error scenarios @@ -48,6 +57,7 @@ We will use Yargs as our primary CLI framework with Inquirer for interactive pro ## Consequences ### Positive + - **Developer Experience**: Yargs provides excellent help generation and validation - **Consistency**: Uniform command structure and behavior across all commands - **Extensibility**: Easy to add new commands following established patterns @@ -56,11 +66,13 @@ We will use Yargs as our primary CLI framework with Inquirer for interactive pro - **Documentation**: Auto-generated help text keeps documentation in sync ### Negative + - **Bundle Size**: Yargs and Inquirer add significant dependencies - **Complexity**: Learning curve for command configuration - **Performance**: Startup time increased due to framework initialization ### Command Architecture + ``` CLI Commands: ├── init # Project scaffolding @@ -76,32 +88,36 @@ CLI Commands: ``` ### Command Interface Pattern + Each command module exports a function that returns a Yargs command configuration: + ```typescript export function getCommandName(): CommandModule { return { - command: 'command-name [args]', - describe: 'Command description', + command: "command-name [args]", + describe: "Command description", builder: (yargs) => { - return yargs.option('option', { - type: 'string', - describe: 'Option description' + return yargs.option("option", { + type: "string", + describe: "Option description", }); }, handler: async (argv) => { // Command implementation - } + }, }; } ``` ### Interactive Prompt Strategy + - Use prompts for complex multi-step workflows - Provide sensible defaults based on project context - Validate inputs and provide immediate feedback - Support both interactive and non-interactive modes ### Global Configuration + - Support global and project-local configuration - Configuration stored in standard locations (`~/.stackcode`, `.stackcode.json`) - Command-line options override configuration files @@ -110,32 +126,38 @@ export function getCommandName(): CommandModule { ## Alternatives Considered ### Commander.js + - **Pros**: Lighter weight, simpler API - **Cons**: Less feature-rich, manual help generation ### Native Node.js argument parsing + - **Pros**: No dependencies, full control - **Cons**: Significant development effort, poor developer experience ### CLI frameworks (Oclif, Gluegun) + - **Pros**: More opinionated, additional features - **Cons**: More complex, additional abstractions ## Implementation Guidelines ### Command Development + 1. Each command should have comprehensive tests 2. All user-facing strings must support internationalization 3. Commands should validate inputs early and provide clear error messages 4. Support both interactive and programmatic usage ### Error Handling + 1. Use consistent error message formats 2. Provide actionable error messages with suggestions 3. Log detailed error information in debug mode 4. Handle common scenarios gracefully (network issues, permission errors) ### Help and Documentation + 1. Provide clear command descriptions and examples 2. Document all options and their effects 3. Include usage examples in help text diff --git a/docs/adr/004-i18n-strategy.md b/docs/adr/004-i18n-strategy.md index 8437b37..73ff145 100644 --- a/docs/adr/004-i18n-strategy.md +++ b/docs/adr/004-i18n-strategy.md @@ -1,10 +1,13 @@ # ADR-004: Internationalization Strategy ## Status + Accepted ## Context + StackCode is designed to be used by developers worldwide and needs to: + - Support multiple languages for all user-facing text - Provide localized error messages and prompts - Support both CLI and VS Code extension interfaces @@ -13,6 +16,7 @@ StackCode is designed to be used by developers worldwide and needs to: - Support dynamic language switching We needed to decide: + - i18n library and approach - Locale file organization - Language detection strategy @@ -20,9 +24,11 @@ We needed to decide: - Integration across packages ## Decision + We will implement a custom i18n system with a dedicated package: ### @stackcode/i18n Package + - Centralized internationalization logic - JSON-based locale files - Runtime locale switching @@ -30,24 +36,28 @@ We will implement a custom i18n system with a dedicated package: - Shared across all packages ### Locale Management + - JSON files for each supported language in `locales/` directory - Hierarchical key structure for organization - Support for interpolation and pluralization - Template literal style for better developer experience ### Language Detection + - Environment variable (`STACKCODE_LANG`) - System locale detection as fallback - User configuration override - VS Code extension uses VS Code's locale ### Supported Languages (Initial) + - English (en) - Primary/fallback language - Portuguese (pt) - Secondary language ## Consequences ### Positive + - **Global Accessibility**: Supports international developer community - **Consistent Localization**: Same i18n system across CLI and VS Code extension - **Extensible**: Easy to add new languages by adding JSON files @@ -56,6 +66,7 @@ We will implement a custom i18n system with a dedicated package: - **Developer Experience**: Simple API for developers ### Negative + - **Maintenance Overhead**: All user-facing strings need translation - **Coordination**: Changes require updates to all locale files - **Testing Complexity**: Need to test multiple language scenarios @@ -63,6 +74,7 @@ We will implement a custom i18n system with a dedicated package: ### Technical Implementation #### Locale File Structure + ```json { "commands": { @@ -88,18 +100,20 @@ We will implement a custom i18n system with a dedicated package: ``` #### API Design + ```typescript // Basic translation -t('commands.init.description') +t("commands.init.description"); // With interpolation -t('errors.fileNotFound', { filename: 'package.json' }) +t("errors.fileNotFound", { filename: "package.json" }); // Pluralization -t('files.count', { count: 5 }) +t("files.count", { count: 5 }); ``` ### Language Detection Priority + 1. `STACKCODE_LANG` environment variable 2. User configuration file 3. System locale (`process.env.LANG`) @@ -108,21 +122,25 @@ t('files.count', { count: 5 }) ### Package Integration #### CLI Package + - Initialize i18n before command parsing - Use locale for help text and prompts - Support `--lang` flag for temporary override #### VS Code Extension + - Use VS Code's built-in locale detection - Respect VS Code's language settings - Provide language switching in extension settings #### Core Package + - All user-facing error messages support i18n - Template descriptions and comments localized - GitHub integration messages localized ### File Organization + ``` packages/i18n/ ├── src/ @@ -133,6 +151,7 @@ packages/i18n/ ``` ### Future Expansion Strategy + - Additional languages in `locales/` directory - Community contributions for translations - Possible locale validation tools @@ -141,38 +160,45 @@ packages/i18n/ ## Alternatives Considered ### i18next + - **Pros**: Mature, feature-rich, ecosystem support - **Cons**: Heavy dependency, over-engineered for our needs ### React i18n (for VS Code extension only) + - **Pros**: React ecosystem integration - **Cons**: Doesn't solve CLI internationalization ### No internationalization + - **Pros**: Simpler development and maintenance - **Cons**: Limits global adoption and accessibility ## Implementation Guidelines ### Translation Keys + - Use hierarchical dot notation for organization - Descriptive key names that indicate context - Consistent naming patterns across components - Avoid deeply nested structures ### String Management + - All user-facing strings must use i18n system - No hardcoded English strings in code - Include context comments for translators - Use interpolation for dynamic content ### Testing Strategy + - Test default (English) locale thoroughly - Spot check key translations - Test locale switching functionality - Ensure fallbacks work correctly ### Contribution Guidelines + - Native speakers preferred for translations - Translation reviews by multiple contributors - Consistent terminology across all strings diff --git a/docs/adr/README.md b/docs/adr/README.md index 7b6f244..e50641f 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -26,7 +26,9 @@ Currently documented architectural decisions: - **[ADR-004: Internationalization Strategy](./004-i18n-strategy.md)** - Multi-language support implementation approach ### Future ADRs + Additional architectural decisions to be documented: + - VS Code Extension Architecture - Template System Design - GitHub Integration Strategy diff --git a/docs/es/ARCHITECTURE.md b/docs/es/ARCHITECTURE.md index 6606315..4b3bde8 100644 --- a/docs/es/ARCHITECTURE.md +++ b/docs/es/ARCHITECTURE.md @@ -45,15 +45,18 @@ StackCode sigue una **arquitectura de monorepo modular** con clara separación d ## 📦 Estructura de Paquetes ### 1. **@stackcode/cli** - Interfaz de Línea de Comandos + **Propósito:** Interfaz primaria del usuario para las funcionalidades de StackCode. **Componentes Principales:** + - **Capa de Comandos:** Puntos de entrada para todas las operaciones CLI - **Manejadores de Comandos:** Implementaciones de comandos individuales - **Prompts Interactivos:** Orientación al usuario y recolección de entrada - **Manejo de Errores:** Reporte de errores consistente y recuperación **Arquitectura:** + ```typescript cli/ ├── src/ @@ -71,9 +74,11 @@ cli/ ``` ### 2. **@stackcode/core** - Motor de Lógica de Negocio + **Propósito:** Contiene toda la lógica de negocio, utilidades y plantillas. **Componentes Principales:** + - **Generadores:** Lógica de generación de proyectos y archivos - **Validadores:** Validación de mensajes de commit y proyectos - **Integración GitHub:** Interacciones API y automatización @@ -81,6 +86,7 @@ cli/ - **Sistema de Plantillas:** Plantillas de proyecto configurables **Arquitectura:** + ```typescript core/ ├── src/ @@ -107,15 +113,18 @@ core/ ``` ### 3. **@stackcode/i18n** - Internationalization + **Purpose:** Manages multi-language support across all packages. **Features:** + - Dynamic locale detection - Translation loading and caching - Language switching - Fallback mechanisms **Architecture:** + ```typescript i18n/ ├── src/ @@ -126,9 +135,11 @@ i18n/ ``` ### 4. **stackcode-vscode** - VS Code Extension + **Purpose:** Integrates StackCode functionality directly into VS Code. **Key Components:** + - **Extension Commands:** VS Code command palette integration - **File Monitors:** Real-time file change detection - **Git Monitors:** Git state monitoring @@ -137,6 +148,7 @@ i18n/ - **Notification System:** Proactive user guidance **Architecture:** + ```typescript vscode-extension/ ├── src/ @@ -154,6 +166,7 @@ vscode-extension/ ## 🔄 Data Flow and Interactions ### Command Execution Flow + 1. **User Input:** CLI command or VS Code action 2. **Command Parsing:** Yargs (CLI) or VS Code API 3. **Core Logic:** Business logic execution in `@stackcode/core` @@ -161,6 +174,7 @@ vscode-extension/ 5. **Output:** Results displayed to user ### Cross-Package Dependencies + ```mermaid graph TD A[CLI Package] --> C[Core Package] @@ -173,42 +187,50 @@ graph TD ## 🎯 Design Principles ### 1. **Separation of Concerns** + - **CLI Package:** User interface and command handling - **Core Package:** Business logic and utilities - **i18n Package:** Internationalization concerns - **VS Code Extension:** IDE integration ### 2. **Dependency Inversion** + - Higher-level modules don't depend on lower-level modules - Both depend on abstractions (interfaces) - External dependencies are injected, not hardcoded ### 3. **Single Responsibility** + - Each package has a clearly defined purpose - Functions and classes have single, well-defined responsibilities - Templates are modular and composable ### 4. **Open/Closed Principle** + - System is open for extension (new templates, commands) - Closed for modification (core logic remains stable) ## 🛠️ Technology Stack ### Core Technologies + - **TypeScript:** Type safety and modern JavaScript features - **Node.js:** Runtime environment - **ESM:** Modern module system ### CLI-Specific + - **Yargs:** Command-line argument parsing - **Inquirer:** Interactive command-line prompts ### VS Code Extension-Specific + - **VS Code API:** Extension development framework - **React:** Webview UI components - **Vite:** Build tool for webview assets ### Development Tools + - **Vitest/Jest:** Testing frameworks - **ESLint:** Code linting - **Prettier:** Code formatting @@ -217,6 +239,7 @@ graph TD ## 📁 File Organization Strategy ### Monorepo Structure + ``` StackCode/ ├── packages/ # All packages @@ -230,7 +253,9 @@ StackCode/ ``` ### Package Structure Conventions + Each package follows consistent patterns: + - `src/` - Source code - `test/` - Test files - `dist/` - Compiled output @@ -242,11 +267,13 @@ Each package follows consistent patterns: ## 🔧 Build System ### TypeScript Compilation + - **Monorepo Build:** `tsc --build` for cross-package dependencies - **Asset Copying:** Templates and locales copied to `dist/` - **Executable Permissions:** CLI entry point marked as executable ### VS Code Extension Build + - **Extension Compilation:** TypeScript to JavaScript - **Webview Build:** Vite for React components - **Package Generation:** `.vsix` file creation @@ -254,11 +281,13 @@ Each package follows consistent patterns: ## 🧪 Testing Strategy ### Unit Testing + - **Core Logic:** Comprehensive tests for business logic - **CLI Commands:** Command execution and error handling - **Validators:** Input validation and error cases ### Integration Testing + - **Cross-Package:** Ensure packages work together - **Template Generation:** Verify output correctness - **GitHub Integration:** API interaction testing @@ -266,22 +295,26 @@ Each package follows consistent patterns: ## 🚀 Deployment and Distribution ### NPM Packages + - **@stackcode/cli:** Published to NPM for global installation - **@stackcode/core:** Internal package, not published separately - **@stackcode/i18n:** Internal package, not published separately ### VS Code Extension + - **Marketplace:** Published to VS Code Marketplace - **VSIX:** Direct installation package available ## 🔮 Extensibility Points ### Template System + - **Custom Templates:** Easy addition of new project types - **Template Composition:** Combining multiple template sources - **Dynamic Configuration:** Runtime template customization ### Command System + - **Plugin Architecture:** Future support for custom commands - **Middleware Support:** Pre/post command hooks - **Configuration Extension:** Custom validation and generation rules diff --git a/docs/es/CONTRIBUTING.md b/docs/es/CONTRIBUTING.md index 46389bb..d65ddb4 100644 --- a/docs/es/CONTRIBUTING.md +++ b/docs/es/CONTRIBUTING.md @@ -19,6 +19,7 @@ Antes de contribuir, familiarízate con la arquitectura del proyecto: - **[🛠️ Stacks Tecnológicos](STACKS.md)** - Frameworks soportados y plantillas de proyecto Comprender la arquitectura te ayudará a: + - Elegir el paquete correcto para tus cambios - Seguir patrones y convenciones establecidas - Entender dependencias entre paquetes @@ -27,28 +28,33 @@ Comprender la arquitectura te ayudará a: ## 🚀 Configuración de Desarrollo 1. **Fork y Clonar** + ```bash git clone https://github.com/tu-usuario/StackCode.git cd StackCode ``` 2. **Instalar Dependencias** + ```bash npm install ``` 3. **Construir el Proyecto** + ```bash npm run build ``` 4. **Vincular CLI para Desarrollo** + ```bash cd packages/cli npm link ``` 5. **Ejecutar Tests** + ```bash npm test ``` @@ -78,27 +84,34 @@ Comprender la arquitectura te ayudará a: ### 1. Reportar Bugs Antes de reportar un bug: + - Verifica que no esté ya reportado en [Issues](https://github.com/YagoBorba/StackCode/issues) - Usa la plantilla de bug report - Proporciona información detallada sobre reproducción **Plantilla de Bug Report:** + ```markdown ## Descripción + Descripción clara del bug. ## Pasos para Reproducir + 1. Ejecuta `stc init` 2. Selecciona template 'react' 3. Ve el error ## Comportamiento Esperado + Lo que esperabas que sucediera. ## Comportamiento Actual + Lo que realmente sucedió. ## Entorno + - OS: [macOS/Windows/Linux] - Node.js: [versión] - StackCode: [versión] @@ -107,6 +120,7 @@ Lo que realmente sucedió. ### 2. Sugerir Funcionalidades Para sugerir nuevas funcionalidades: + - Revisa las [Discussions](https://github.com/YagoBorba/StackCode/discussions) - Usa la plantilla de feature request - Explica el caso de uso y beneficios @@ -116,23 +130,27 @@ Para sugerir nuevas funcionalidades: #### Tipos de Contribuciones de Código **a) Corrección de Bugs** + - Identifica el bug en el código - Escribe un test que reproduzca el bug - Implementa la corrección - Verifica que todos los tests pasen **b) Nuevas Funcionalidades** + - Discute la funcionalidad en Issues/Discussions - Sigue los principios de arquitectura - Incluye tests completos - Actualiza documentación **c) Mejoras de Performance** + - Benchmarking antes y después - Mantén compatibilidad con API existente - Incluye tests de rendimiento **d) Refactorización** + - Mantén comportamiento existente - Mejora legibilidad o estructura - Incluye tests que verifiquen no regression @@ -140,6 +158,7 @@ Para sugerir nuevas funcionalidades: #### Flujo de Desarrollo 1. **Crear Branch** + ```bash git checkout -b feature/nueva-funcionalidad # o @@ -152,6 +171,7 @@ Para sugerir nuevas funcionalidades: - Actualiza documentación 3. **Commit** + ```bash # Usa conventional commits git commit -m "feat(cli): add support for new template" @@ -166,6 +186,7 @@ Para sugerir nuevas funcionalidades: ### 4. Mejorar Documentación Tipos de mejoras de documentación: + - Corregir errores tipográficos - Mejorar claridad de explicaciones - Agregar ejemplos @@ -202,10 +223,10 @@ npm run format:check ```typescript // Orden de imports -import { something } from 'node:fs'; // Node.js built-ins -import { yargs } from 'yargs'; // External dependencies -import { helper } from '@stackcode/core'; // Internal packages -import { local } from './localFile.js'; // Local files +import { something } from "node:fs"; // Node.js built-ins +import { yargs } from "yargs"; // External dependencies +import { helper } from "@stackcode/core"; // Internal packages +import { local } from "./localFile.js"; // Local files // Orden de exports export type { TypeDefinition }; @@ -215,14 +236,14 @@ export default defaultExport; #### Documentación de Código -```typescript +````typescript /** * Genera un nuevo proyecto basado en una plantilla. - * + * * @param template - El nombre de la plantilla a usar * @param options - Opciones de configuración para la generación * @returns Promise que resuelve con el resultado de la generación - * + * * @example * ```typescript * const result = await generateProject('react', { @@ -233,11 +254,11 @@ export default defaultExport; */ export async function generateProject( template: SupportedTemplate, - options: GenerationOptions + options: GenerationOptions, ): Promise { // Implementación... } -``` +```` ### Testing @@ -251,29 +272,29 @@ export async function generateProject( #### Estructura de Tests ```typescript -describe('TemplateGenerator', () => { - describe('generateProject', () => { - it('should create project with correct structure', async () => { +describe("TemplateGenerator", () => { + describe("generateProject", () => { + it("should create project with correct structure", async () => { // Arrange - const template = 'react'; - const options = { directory: './test-project' }; - + const template = "react"; + const options = { directory: "./test-project" }; + // Act const result = await generator.generateProject(template, options); - + // Assert expect(result.success).toBe(true); - expect(fs.existsSync('./test-project/package.json')).toBe(true); + expect(fs.existsSync("./test-project/package.json")).toBe(true); }); - it('should handle invalid template gracefully', async () => { + it("should handle invalid template gracefully", async () => { // Arrange - const template = 'invalid-template' as SupportedTemplate; - + const template = "invalid-template" as SupportedTemplate; + // Act & Assert - await expect( - generator.generateProject(template, {}) - ).rejects.toThrow('Template not supported'); + await expect(generator.generateProject(template, {})).rejects.toThrow( + "Template not supported", + ); }); }); }); @@ -283,13 +304,13 @@ describe('TemplateGenerator', () => { ```typescript // Mock external dependencies -jest.mock('node:fs', () => ({ +jest.mock("node:fs", () => ({ existsSync: jest.fn(), writeFileSync: jest.fn(), })); // Mock internal modules -jest.mock('@stackcode/core', () => ({ +jest.mock("@stackcode/core", () => ({ generateTemplate: jest.fn(), })); ``` @@ -309,6 +330,7 @@ Seguimos la especificación [Conventional Commits](https://conventionalcommits.o ``` **Tipos:** + - `feat`: Nueva funcionalidad - `fix`: Corrección de bug - `docs`: Cambios en documentación @@ -318,6 +340,7 @@ Seguimos la especificación [Conventional Commits](https://conventionalcommits.o - `chore`: Tareas de mantenimiento **Scopes:** + - `cli`: CLI package - `core`: Core package - `i18n`: Internationalization package @@ -326,6 +349,7 @@ Seguimos la especificación [Conventional Commits](https://conventionalcommits.o - `build`: Build system **Ejemplos:** + ```bash feat(cli): add support for Vue 3 template fix(core): resolve path resolution issue on Windows @@ -367,6 +391,7 @@ StackCode soporta múltiples idiomas y valoramos contribuciones de traducción. ### Agregar Traducciones 1. **Localizar Archivos de Idioma** + ``` packages/i18n/src/locales/ ├── en.json (base) @@ -376,11 +401,13 @@ StackCode soporta múltiples idiomas y valoramos contribuciones de traducción. ``` 2. **Crear Nuevo Archivo de Idioma** + ```bash cp packages/i18n/src/locales/en.json packages/i18n/src/locales/fr.json ``` 3. **Traducir Contenido** + ```json { "commands": { @@ -397,7 +424,7 @@ StackCode soporta múltiples idiomas y valoramos contribuciones de traducción. 4. **Actualizar Configuración** ```typescript // En packages/i18n/src/index.ts - const supportedLocales = ['en', 'pt', 'es', 'fr']; + const supportedLocales = ["en", "pt", "es", "fr"]; ``` ### Directrices de Traducción @@ -413,6 +440,7 @@ StackCode soporta múltiples idiomas y valoramos contribuciones de traducción. Para traducir documentación (como este archivo): 1. **Crear Estructura de Directorios** + ``` docs/ ├── README.md (inglés) @@ -431,11 +459,14 @@ Para traducir documentación (como este archivo): - Misma estructura de encabezados 3. **Referencias Internas** + ```markdown + [Architecture Guide](ARCHITECTURE.md) - + + [English Version](../README.md) ``` @@ -444,6 +475,7 @@ Para traducir documentación (como este archivo): ### Antes del Pull Request 1. **Auto-verificación** + ```bash npm run lint npm run test @@ -492,6 +524,7 @@ open coverage/lcov-report/index.html ``` **Objetivos:** + - **Global**: >80% - **Funciones**: >85% - **Líneas**: >80% @@ -543,10 +576,11 @@ node --inspect packages/cli/dist/index.js init - Se abre nueva ventana con extensión cargada 2. **Debug Console** + ```typescript // En código de extensión - console.log('Debug info:', data); - + console.log("Debug info:", data); + // Ver en VS Code Developer Tools // Help > Toggle Developer Tools ``` @@ -589,6 +623,7 @@ node --inspect packages/cli/dist/index.js init ### Hall of Fame Los contribuidores destacados son reconocidos en: + - README principal del proyecto - Releases notes - Documentación oficial @@ -597,30 +632,34 @@ Los contribuidores destacados son reconocidos en: --- ¿Tienes preguntas? No dudes en: + - Abrir una [Discussion](https://github.com/YagoBorba/StackCode/discussions) - Crear un [Issue](https://github.com/YagoBorba/StackCode/issues) - Revisar documentación existente ¡Esperamos tu contribución! 🚀 - git clone https://github.com/your-username/StackCode.git - cd StackCode - ``` +git clone https://github.com/your-username/StackCode.git +cd StackCode + +```` 2. **Install Dependencies** - ```bash - npm install - ``` +```bash +npm install +```` 3. **Build the Project** + ```bash npm run build ``` 4. **Test Your Setup** + ```bash # Run tests npm test - + # Test CLI locally node packages/cli/dist/index.js --help ``` @@ -628,34 +667,40 @@ Los contribuidores destacados son reconocidos en: ## 🤝 How to Contribute ### 🐛 Bug Reports + - Check [existing issues](https://github.com/YagoBorba/StackCode/issues) first - Provide clear reproduction steps - Include environment details (OS, Node.js version, etc.) - Use the bug report template ### ✨ Feature Requests + - Open an issue to discuss the feature first - Explain the use case and benefits - Consider if it fits the project's scope - Provide implementation ideas if possible ### 📝 Documentation Improvements + - Fix typos, improve clarity, add examples - Update docs when adding new features - Help with translations (see [Internationalization](#internationalization)) ### 🛠️ Code Contributions + - Pick up issues labeled `good-first-issue` or `help-wanted` - Follow the [development workflow](#development-workflow) - Ensure all tests pass - Add tests for new functionality ### 🌐 Adding New Technology Stacks + See the comprehensive guide in [main CONTRIBUTING.md](../CONTRIBUTING.md#adding-new-technology-stacks). ## 🔄 Development Workflow 1. **Create a Feature Branch** + ```bash git checkout develop git pull origin develop @@ -668,6 +713,7 @@ See the comprehensive guide in [main CONTRIBUTING.md](../CONTRIBUTING.md#adding- - Update documentation as needed 3. **Test Thoroughly** + ```bash npm test npm run lint @@ -675,6 +721,7 @@ See the comprehensive guide in [main CONTRIBUTING.md](../CONTRIBUTING.md#adding- ``` 4. **Commit Your Changes** + ```bash # Use conventional commits with emojis git commit -m "feat(cli): ✨ add new project template" @@ -689,18 +736,21 @@ See the comprehensive guide in [main CONTRIBUTING.md](../CONTRIBUTING.md#adding- ## 🎨 Coding Standards ### General Principles + - **Clean Code**: Write readable, maintainable code - **SOLID Principles**: Follow SOLID design principles - **Single Responsibility**: Each function/class should have one purpose - **Documentation**: Use TSDoc comments for public APIs ### TypeScript Guidelines + - Use strict TypeScript configuration - Prefer explicit types over `any` - Use interfaces for object shapes - Follow ESLint rules ### Testing Requirements + - Add unit tests for new functionality - Maintain or improve test coverage - Test both success and error scenarios @@ -711,6 +761,7 @@ See the comprehensive guide in [main CONTRIBUTING.md](../CONTRIBUTING.md#adding- We welcome contributions to support more languages: ### Current Structure + ``` packages/i18n/src/locales/ ├── en.json # English (primary) @@ -720,12 +771,14 @@ packages/i18n/src/locales/ ### Adding New Languages 1. **Create Locale File** + ```bash # Example for Spanish cp packages/i18n/src/locales/en.json packages/i18n/src/locales/es.json ``` 2. **Translate Strings** + ```json { "commands": { @@ -742,6 +795,7 @@ packages/i18n/src/locales/ ``` ### Future Structure (Planned) + ``` docs/ ├── pt-BR/ # Portuguese (Brazil) @@ -753,12 +807,14 @@ docs/ ## 📏 Code Review Process ### For Contributors + - Keep PRs focused and small - Write clear PR descriptions - Respond to feedback promptly - Update documentation as needed ### Review Criteria + - Code quality and maintainability - Test coverage and quality - Documentation completeness @@ -797,6 +853,7 @@ Need help contributing? ## 🙏 Recognition All contributors are recognized in: + - [Contributors section](../README.md#contributors) in README - Git commit history - Release notes for significant contributions @@ -806,6 +863,7 @@ Thank you for helping make StackCode better! 🚀 --- For more details, see: + - **[Main README](../README.md)** - Project overview - **[Architecture Guide](ARCHITECTURE.md)** - Technical details - **[Self-Hosting Guide](SELF_HOSTING_GUIDE.md)** - Deployment options diff --git a/docs/es/README.md b/docs/es/README.md index dbc9235..099dc2e 100644 --- a/docs/es/README.md +++ b/docs/es/README.md @@ -5,12 +5,14 @@ ## � Navegación Rápida ### 🏗️ **Documentación Principal** + - **[📐 Guía de Arquitectura](ARCHITECTURE.md)** - Visión técnica completa de la estructura del monorepo, principios de diseño e interacciones entre componentes - **[🛠️ Stacks de Tecnología](STACKS.md)** - Lista detallada de frameworks, plantillas y tipos de proyecto soportados - **[🤝 Guía de Contribución](CONTRIBUTING.md)** - Todo lo que necesitas saber para contribuir a StackCode - **[🚀 Guía de Auto-hospedaje](SELF_HOSTING_GUIDE.md)** - Despliega y personaliza StackCode para tu organización ### 🏛️ **Decisiones Arquitecturales** + - **[Directorio ADR](adr/)** - Registros de Decisiones Arquitecturales documentando decisiones de diseño importantes - [ADR-001: Estructura Monorepo](adr/001-monorepo-structure.md) - [ADR-002: TypeScript y ES Modules](adr/002-typescript-esm.md) @@ -18,26 +20,33 @@ - [ADR-004: Estrategia de Internacionalización](adr/004-i18n-strategy.md) ### 🌐 **Traducciones** -- **[🇪🇸 Español](es/)** - Documentación en español *(actual)* + +- **[🇪🇸 Español](es/)** - Documentación en español _(actual)_ - **[🇧🇷 Português (Brasil)](../pt-BR/)** - Documentação em português -- **[🇺🇸 English](../)** - English documentation *(original)* +- **[🇺🇸 English](../)** - English documentation _(original)_ ## 🎯 **Documentación por Audiencia** ### 👩‍💻 **Para Desarrolladores Usando StackCode** + Comienza aquí si quieres usar StackCode en tus proyectos: + 1. [README Principal](../../README.md) - Visión general del proyecto y primeros pasos 2. [Stacks de Tecnología](STACKS.md) - Ve qué tipos de proyecto son soportados 3. [Guía de Auto-hospedaje](SELF_HOSTING_GUIDE.md) - Despliega para tu organización ### 🛠️ **Para Contribuidores** + Comienza aquí si quieres contribuir a StackCode: + 1. [Guía de Contribución](CONTRIBUTING.md) - Cómo contribuir efectivamente 2. [Guía de Arquitectura](ARCHITECTURE.md) - Entiende la base de código 3. [Directorio ADR](adr/) - Aprende sobre decisiones arquitecturales ### � **Para Organizaciones** + Comienza aquí si quieres desplegar StackCode internamente: + 1. [Guía de Auto-hospedaje](SELF_HOSTING_GUIDE.md) - Despliegue y personalización 2. [Guía de Arquitectura](ARCHITECTURE.md) - Visión técnica general 3. [Guía de Contribución](CONTRIBUTING.md) - Cómo contribuir mejoras de vuelta @@ -45,6 +54,7 @@ Comienza aquí si quieres desplegar StackCode internamente: ## 🔧 **Referencia Técnica** ### Estructura del Proyecto + ``` docs/ ├── README.md # Este archivo @@ -65,6 +75,7 @@ docs/ ``` ### Conceptos Clave + - **Arquitectura Monorepo**: StackCode usa un monorepo con múltiples paquetes - **Sistema de Plantillas**: Plantillas de proyecto configurables para diferentes tecnologías - **CLI + Extensión VS Code**: Múltiples interfaces para la misma funcionalidad principal @@ -75,16 +86,19 @@ docs/ ¡Acogemos mejoras a nuestra documentación! Así es como puedes ayudar: ### Correcciones Rápidas + - Corrige errores tipográficos, enlaces rotos o explicaciones poco claras - Añade ejemplos o mejora los existentes - Actualiza información desactualizada ### Contribuciones Principales + - Escribe nuevas guías o tutoriales - Crea documentación para nuevas características - Ayuda con traducciones ### Ayuda con Traducciones + - Traduce documentación existente a tu idioma - Revisa traducciones de otros contribuidores - Mantén consistencia entre traducciones @@ -107,4 +121,4 @@ Ve nuestra [Guía de Contribución](CONTRIBUTING.md) para instrucciones detallad --- -*Última actualización: Septiembre 2025 | Equipo de Documentación StackCode* +_Última actualización: Septiembre 2025 | Equipo de Documentación StackCode_ diff --git a/docs/es/SELF_HOSTING_GUIDE.md b/docs/es/SELF_HOSTING_GUIDE.md index 7cffd32..8ce6f62 100644 --- a/docs/es/SELF_HOSTING_GUIDE.md +++ b/docs/es/SELF_HOSTING_GUIDE.md @@ -39,12 +39,14 @@ npm link For organizations with private NPM registries: 1. **Fork the Repository** + ```bash git clone https://github.com/your-org/StackCode.git cd StackCode ``` 2. **Customize Package Configuration** + ```json // In packages/cli/package.json { @@ -89,15 +91,17 @@ docker run -it your-org/stackcode init ### Template Customization 1. **Add Custom Templates** + ```bash # Create your organization's templates mkdir packages/core/src/templates/your-org-stack - + # Add template files with .tpl extension # Use {{variableName}} for replacements ``` 2. **Modify Existing Templates** + ```bash # Edit existing templates in packages/core/src/templates/ # Update package.json dependencies @@ -107,15 +111,13 @@ docker run -it your-org/stackcode init 3. **Update Type Definitions** ```typescript // In packages/core/src/types.ts - export type SupportedStack = - | "node-js" - | "react" - | "your-custom-stack" // Add your stack + export type SupportedStack = "node-js" | "react" | "your-custom-stack"; // Add your stack ``` ### Configuration Customization 1. **Default Configuration** + ```json // Create .stackcoderc in your users' home directories { @@ -213,6 +215,7 @@ Organization Setup: ### Common Issues 1. **Permission Errors** + ```bash # Fix NPM permissions sudo chown -R $(whoami) ~/.npm @@ -220,19 +223,21 @@ Organization Setup: ``` 2. **Template Not Found** + ```bash # Verify template location ls packages/core/src/templates/ - + # Check build output ls packages/core/dist/templates/ ``` 3. **Registry Issues** + ```bash # Check registry configuration npm config get registry - + # Test registry connectivity npm ping --registry https://your-registry.com ``` @@ -273,4 +278,4 @@ For self-hosting support: --- -*For more information about StackCode architecture and development, see the [Architecture Guide](ARCHITECTURE.md).* +_For more information about StackCode architecture and development, see the [Architecture Guide](ARCHITECTURE.md)._ diff --git a/docs/es/STACKS.md b/docs/es/STACKS.md index db6527f..6dffe41 100644 --- a/docs/es/STACKS.md +++ b/docs/es/STACKS.md @@ -7,6 +7,7 @@ StackCode soporta múltiples stacks de tecnología, cada uno diseñado con las m ### Stacks Frontend #### React + TypeScript + **Ubicación de la Plantilla:** `packages/core/src/templates/react/` - **Framework**: React 18 con TypeScript @@ -16,6 +17,7 @@ StackCode soporta múltiples stacks de tecnología, cada uno diseñado con las m - **Características**: Modern JSX Transform, configuración ESLint, estructura de componentes **Estructura Generada:** + ``` ├── src/ │ ├── components/ @@ -31,6 +33,7 @@ StackCode soporta múltiples stacks de tecnología, cada uno diseñado con las m ``` #### Vue.js + TypeScript + **Ubicación de la Plantilla:** `packages/core/src/templates/vue/` - **Framework**: Vue 3 con Composition API y TypeScript @@ -40,6 +43,7 @@ StackCode soporta múltiples stacks de tecnología, cada uno diseñado con las m - **Características**: SFC (Single File Components), patrones modernos de Vue **Estructura Generada:** + ``` ├── src/ │ ├── components/ @@ -57,6 +61,7 @@ StackCode soporta múltiples stacks de tecnología, cada uno diseñado con las m ### Stacks Backend #### Node.js + JavaScript + **Ubicación de la Plantilla:** `packages/core/src/templates/node-js/` - **Runtime**: Node.js con ES6+ @@ -65,6 +70,7 @@ StackCode soporta múltiples stacks de tecnología, cada uno diseñado con las m - **Características**: estructura Express.js, variables de entorno, configuración de pruebas **Estructura Generada:** + ``` ├── src/ │ ├── controllers/ @@ -81,6 +87,7 @@ StackCode soporta múltiples stacks de tecnología, cada uno diseñado con las m ``` #### Node.js + TypeScript + **Ubicación de la Plantilla:** `packages/core/src/templates/node-ts/` - **Runtime**: Node.js con TypeScript @@ -88,6 +95,7 @@ StackCode soporta múltiples stacks de tecnología, cada uno diseñado con las m - **Características**: desarrollo type-safe, configuración moderna de TypeScript **Estructura Generada:** + ``` ├── src/ │ ├── controllers/ @@ -100,12 +108,14 @@ StackCode soporta múltiples stacks de tecnología, cada uno diseñado con las m ``` #### Python + Configuración Moderna + **Ubicación de la Plantilla:** `packages/core/src/templates/python/` - **Gestión de Paquetes**: pip con pyproject.toml - **Características**: estructura de proyecto Python moderna, gestión de dependencias **Estructura Generada:** + ``` ├── src/ │ └── main.py @@ -113,12 +123,14 @@ StackCode soporta múltiples stacks de tecnología, cada uno diseñado con las m ``` #### Java + Maven + **Ubicación de la Plantilla:** `packages/core/src/templates/java/` - **Herramienta de Build**: Maven - **Características**: estructura estándar de proyecto Java, configuración Maven **Estructura Generada:** + ``` ├── src/ │ └── main/ @@ -127,18 +139,21 @@ StackCode soporta múltiples stacks de tecnología, cada uno diseñado con las m ``` #### Go + Modules + **Ubicación de la Plantilla:** `packages/core/src/templates/go/` - **Gestión de Paquetes**: Go modules - **Características**: proyecto Go simple con soporte de módulos **Estructura Generada:** + ``` ├── main.go └── go.mod ``` #### PHP + Laravel + **Ubicación de la Plantilla:** `packages/core/src/templates/php/` - **Framework**: estructura estilo Laravel @@ -146,6 +161,7 @@ StackCode soporta múltiples stacks de tecnología, cada uno diseñado con las m - **Características**: estructura MVC, variables de entorno **Estructura Generada:** + ``` ├── app/ ├── bootstrap/ @@ -162,27 +178,32 @@ Además de las plantillas principales de proyecto, StackCode proporciona soporte **Ubicación de la Plantilla:** `packages/core/src/templates/gitignore/` ### Desarrollo Móvil + - **Android** (`android.tpl`) - Android Studio, Gradle, archivos APK - **Flutter** (`flutter.tpl`) - Dart, archivos de build Flutter, archivos específicos de plataforma - **React Native** (`react_native.tpl`) - Metro bundler, builds de plataforma - **Swift** (`swift.tpl`) - Xcode, archivos de desarrollo iOS ### Frameworks Frontend + - **Angular** (`angular.tpl`) - Angular CLI, artefactos de build - **Svelte** (`svelte.tpl`) - SvelteKit, outputs de build ### Backend y Lenguajes + - **Go** (`go.tpl`) - binarios Go, directorios vendor - **Java** (`java.tpl`) - Maven, Gradle, archivos IDE - **Node.js** (`node-js.tpl`, `node-ts.tpl`) - npm, yarn, outputs de build - **PHP** (`php.tpl`) - Composer, artefactos Laravel -- **Python** (`python.tpl`) - pip, entornos virtuales, __pycache__ +- **Python** (`python.tpl`) - pip, entornos virtuales, **pycache** - **JavaScript** (`javascript.tpl`) - archivos generales de proyecto JS ### Herramientas de Desarrollo + - **IDEs** (`ides.tpl`) - configuraciones VS Code, IntelliJ, Eclipse ### Uso + Al crear proyectos, StackCode selecciona automáticamente la plantilla `.gitignore` apropiada basada en el stack elegido, y puede combinar múltiples plantillas al usar características como Docker o IDEs específicos. ## 🔧 Características de los Stacks @@ -206,12 +227,13 @@ StackCode usa automáticamente el gestor de paquetes apropiado basado en el tipo - **npm** para stacks basados en Node.js (React, Vue, Node.js, Node-TS) - **pip** para proyectos Python (con pyproject.toml) - **maven** para proyectos Java -- **go mod** para proyectos Go +- **go mod** para proyectos Go - **composer** para proyectos PHP ### Generación Inteligente de .gitignore Todo proyecto recibe un archivo `.gitignore` personalizado que combina: + - **Reglas específicas del stack** (basadas en la tecnología elegida) - **Reglas específicas del IDE** (entornos de desarrollo comunes) - **Reglas de herramientas adicionales** (Docker, gestores de paquetes, artefactos de build) diff --git a/docs/es/adr/001-monorepo-structure.md b/docs/es/adr/001-monorepo-structure.md index 5107b90..097c89e 100644 --- a/docs/es/adr/001-monorepo-structure.md +++ b/docs/es/adr/001-monorepo-structure.md @@ -1,16 +1,20 @@ # ADR-001: Estructura Monorepo ## Estado + Aceptado ## Contexto + StackCode consiste en múltiples paquetes relacionados que comparten funcionalidad común: + - Una herramienta CLI para uso en línea de comandos - Una extensión VS Code para integración con IDE - Lógica de negocio principal que ambas interfaces usan - Soporte de internacionalización en todos los componentes Necesitábamos decidir cómo organizar estos paquetes relacionados pero distintos de una manera que: + - Permita compartir código entre paquetes - Mantenga límites claros entre componentes - Simplifique la gestión de dependencias @@ -18,13 +22,16 @@ Necesitábamos decidir cómo organizar estos paquetes relacionados pero distinto - Reduzca la complejidad de desarrollo ## Decisión + Usaremos una estructura monorepo con los siguientes paquetes: + - `@stackcode/cli` - Interfaz de línea de comandos - `@stackcode/core` - Lógica de negocio compartida y utilidades - `@stackcode/i18n` - Soporte de internacionalización - `stackcode-vscode` - Extensión VS Code El monorepo será gestionado usando npm workspaces, proporcionando: + - Gestión compartida de dependencias - Linking entre paquetes - Procesos de build coordinados @@ -33,6 +40,7 @@ El monorepo será gestionado usando npm workspaces, proporcionando: ## Consecuencias ### Positivas + - **Reutilización de Código**: La lógica de negocio principal puede ser compartida entre CLI y extensión VS Code - **APIs Consistentes**: Todos los paquetes usan las mismas interfaces y tipos subyacentes - **Desarrollo Simplificado**: Checkout de repositorio único proporciona acceso a todos los componentes @@ -41,17 +49,20 @@ El monorepo será gestionado usando npm workspaces, proporcionando: - **Pruebas Más Fáciles**: Las pruebas de integración pueden abarcar múltiples paquetes ### Negativas + - **Complejidad de Build**: El sistema de build debe manejar múltiples paquetes y sus dependencias - **Tamaño del Repositorio**: Repositorio único contiene todos los componentes, potencialmente aumentando el tamaño - **Limitaciones de Herramientas**: Algunas herramientas pueden no manejar monorepos de forma óptima - **Gestión de Dependencias**: Cambios en paquetes principales afectan todos los dependientes ### Riesgos + - **Dependencias Circulares**: Se debe tener cuidado para evitar referencias circulares entre paquetes - **Orden de Build**: El orden de build de los paquetes se vuelve importante - **Coordinación de Versión**: Todos los paquetes típicamente necesitan ser versionados juntos ### Estrategias de Mitigación + - Usar referencias de proyecto TypeScript para manejar dependencias de build - Implementar límites e interfaces claros entre paquetes - Usar npm workspaces para gestión de dependencias diff --git a/docs/es/adr/002-typescript-esm.md b/docs/es/adr/002-typescript-esm.md index 6722e93..2bed7b5 100644 --- a/docs/es/adr/002-typescript-esm.md +++ b/docs/es/adr/002-typescript-esm.md @@ -1,10 +1,13 @@ # ADR-002: TypeScript y Módulos ES ## Estado + Aceptado ## Contexto + StackCode es una herramienta para desarrolladores que necesita: + - Proporcionar seguridad de tipos para lógica de negocio compleja - Soportar características modernas de JavaScript - Ser compatible con entornos Node.js y navegador @@ -12,26 +15,31 @@ StackCode es una herramienta para desarrolladores que necesita: - Soportar tree-shaking para tamaños óptimos de bundle Necesitábamos elegir: + - Lenguaje de programación (JavaScript vs TypeScript) - Sistema de módulos (CommonJS vs ES Modules) - Herramientas de build y estrategia de compilación ## Decisión + Usaremos TypeScript con ES Modules (ESM) como nuestro stack principal de desarrollo: ### TypeScript + - Todo el código fuente será escrito en TypeScript - Configuración estricta de TypeScript con verificación comprensiva de tipos - Definiciones de tipos compartidas entre paquetes - Generar archivos de declaración para paquetes publicados ### ES Modules (ESM) + - Usar ES Modules como sistema de módulos primario - Configurar `"type": "module"` en todos los archivos package.json - Use `.js` extensions in import statements (TypeScript requirement for ESM) - Support Node.js native ESM loading ### Build Strategy + - Compile TypeScript to JavaScript with ESM output - Use TypeScript project references for monorepo builds - Generate source maps for debugging @@ -40,6 +48,7 @@ Usaremos TypeScript con ES Modules (ESM) como nuestro stack principal de desarro ## Consequences ### Positive + - **Type Safety**: Comprehensive compile-time type checking reduces runtime errors - **Modern JavaScript**: Access to latest language features and improvements - **Better IDE Support**: Enhanced autocomplete, refactoring, and navigation @@ -48,24 +57,28 @@ Usaremos TypeScript con ES Modules (ESM) como nuestro stack principal de desarro - **Performance**: Native ESM loading in Node.js improves startup time ### Negative + - **Build Complexity**: Requires compilation step and build tooling - **Learning Curve**: Team members need TypeScript knowledge - **Bundle Size**: TypeScript runtime helpers may increase bundle size - **ESM Migration**: Some dependencies may still use CommonJS ### Technical Considerations + - **Import Extensions**: Must use `.js` extensions in TypeScript imports for ESM compatibility - **Dynamic Imports**: Use `import()` for conditional module loading -- **__dirname Replacement**: Use `import.meta.url` for file path resolution +- **\_\_dirname Replacement**: Use `import.meta.url` for file path resolution - **Package Exports**: Define clear entry points in package.json exports field ### Tooling Requirements + - **TypeScript Compiler**: For compilation and type checking - **ESLint with TypeScript**: For code quality and consistency - **Prettier**: For code formatting - **Vitest/Jest**: Testing frameworks with TypeScript support ### Migration Strategy + - Convert all existing JavaScript to TypeScript gradually - Update import statements to use explicit `.js` extensions - Configure build tools to handle TypeScript compilation @@ -74,13 +87,16 @@ Usaremos TypeScript con ES Modules (ESM) como nuestro stack principal de desarro ## Alternatives Considered ### JavaScript with JSDoc + - **Pros**: No compilation step, simpler tooling - **Cons**: Less robust type checking, worse IDE support ### CommonJS Modules + - **Pros**: Better ecosystem compatibility, simpler Node.js integration - **Cons**: No tree shaking, legacy module system, worse performance ### Mixed Module System + - **Pros**: Gradual migration, better compatibility - **Cons**: Complexity, confusion, maintenance overhead diff --git a/docs/es/adr/003-cli-design.md b/docs/es/adr/003-cli-design.md index a7b6374..26062aa 100644 --- a/docs/es/adr/003-cli-design.md +++ b/docs/es/adr/003-cli-design.md @@ -1,10 +1,13 @@ # ADR-003: Diseño de Interfaz de Línea de Comandos ## Estado + Aceptado ## Contexto + StackCode proporciona una herramienta CLI integral que necesita: + - Soportar múltiples comandos complejos con subcomandos - Proporcionar prompts interactivos para orientación del usuario - Manejar gestión de configuración @@ -13,33 +16,39 @@ StackCode proporciona una herramienta CLI integral que necesita: - Ser extensible para comandos futuros Necesitábamos elegir: + - Framework/biblioteca CLI - Estructura y organización de comandos - Sistema de prompts interactivos - Estrategia de manejo de errores ## Decisión + Usaremos Yargs como nuestro framework CLI primario con Inquirer para prompts interactivos: ### Framework Yargs + - Usar Yargs para parseo de comandos, validación y generación de ayuda - Implementar arquitectura basada en comandos con separación clara - Soportar aliases y atajos para comandos comunes - Proporcionar información comprensiva de ayuda y uso ### Estructura de Comandos + - Each command is implemented as a separate module - Commands follow a consistent interface pattern - Support for subcommands where appropriate (e.g., `git start`, `git finish`) - Global options available across all commands ### Interactive Prompts + - Use Inquirer.js for complex user interactions - Provide guided workflows for complex operations - Validate user input at prompt level - Support default values and smart suggestions ### Error Handling + - Consistent error message formatting - Localized error messages through i18n system - Graceful handling of common error scenarios @@ -48,6 +57,7 @@ Usaremos Yargs como nuestro framework CLI primario con Inquirer para prompts int ## Consequences ### Positive + - **Developer Experience**: Yargs provides excellent help generation and validation - **Consistency**: Uniform command structure and behavior across all commands - **Extensibility**: Easy to add new commands following established patterns @@ -56,11 +66,13 @@ Usaremos Yargs como nuestro framework CLI primario con Inquirer para prompts int - **Documentation**: Auto-generated help text keeps documentation in sync ### Negative + - **Bundle Size**: Yargs and Inquirer add significant dependencies - **Complexity**: Learning curve for command configuration - **Performance**: Startup time increased due to framework initialization ### Command Architecture + ``` CLI Commands: ├── init # Project scaffolding @@ -76,32 +88,36 @@ CLI Commands: ``` ### Command Interface Pattern + Each command module exports a function that returns a Yargs command configuration: + ```typescript export function getCommandName(): CommandModule { return { - command: 'command-name [args]', - describe: 'Command description', + command: "command-name [args]", + describe: "Command description", builder: (yargs) => { - return yargs.option('option', { - type: 'string', - describe: 'Option description' + return yargs.option("option", { + type: "string", + describe: "Option description", }); }, handler: async (argv) => { // Command implementation - } + }, }; } ``` ### Interactive Prompt Strategy + - Use prompts for complex multi-step workflows - Provide sensible defaults based on project context - Validate inputs and provide immediate feedback - Support both interactive and non-interactive modes ### Global Configuration + - Support global and project-local configuration - Configuration stored in standard locations (`~/.stackcode`, `.stackcode.json`) - Command-line options override configuration files @@ -110,32 +126,38 @@ export function getCommandName(): CommandModule { ## Alternatives Considered ### Commander.js + - **Pros**: Lighter weight, simpler API - **Cons**: Less feature-rich, manual help generation ### Native Node.js argument parsing + - **Pros**: No dependencies, full control - **Cons**: Significant development effort, poor developer experience ### CLI frameworks (Oclif, Gluegun) + - **Pros**: More opinionated, additional features - **Cons**: More complex, additional abstractions ## Implementation Guidelines ### Command Development + 1. Each command should have comprehensive tests 2. All user-facing strings must support internationalization 3. Commands should validate inputs early and provide clear error messages 4. Support both interactive and programmatic usage ### Error Handling + 1. Use consistent error message formats 2. Provide actionable error messages with suggestions 3. Log detailed error information in debug mode 4. Handle common scenarios gracefully (network issues, permission errors) ### Help and Documentation + 1. Provide clear command descriptions and examples 2. Document all options and their effects 3. Include usage examples in help text diff --git a/docs/es/adr/004-i18n-strategy.md b/docs/es/adr/004-i18n-strategy.md index b805ffa..364924c 100644 --- a/docs/es/adr/004-i18n-strategy.md +++ b/docs/es/adr/004-i18n-strategy.md @@ -1,10 +1,13 @@ # ADR-004: Estrategia de Internacionalización ## Estado + Aceptado ## Contexto + StackCode está diseñado para ser usado por desarrolladores mundialmente y necesita: + - Soportar múltiples idiomas para todo el texto orientado al usuario - Proporcionar mensajes de error y prompts localizados - Soportar tanto interfaces CLI como extensión VS Code @@ -13,6 +16,7 @@ StackCode está diseñado para ser usado por desarrolladores mundialmente y nece - Soportar cambio dinámico de idioma Necesitábamos decidir: + - Biblioteca y enfoque i18n - Organización de archivos de locale - Estrategia de detección de idioma @@ -20,9 +24,11 @@ Necesitábamos decidir: - Integración entre paquetes ## Decisión + Implementaremos un sistema i18n personalizado con un paquete dedicado: ### Paquete @stackcode/i18n + - Lógica de internacionalización centralizada - Archivos de locale basados en JSON - Cambio de locale en tiempo de ejecución @@ -30,24 +36,28 @@ Implementaremos un sistema i18n personalizado con un paquete dedicado: - Compartido entre todos los paquetes ### Locale Management + - JSON files for each supported language in `locales/` directory - Hierarchical key structure for organization - Support for interpolation and pluralization - Template literal style for better developer experience ### Language Detection + - Environment variable (`STACKCODE_LANG`) - System locale detection as fallback - User configuration override - VS Code extension uses VS Code's locale ### Supported Languages (Initial) + - English (en) - Primary/fallback language - Portuguese (pt) - Secondary language ## Consequences ### Positive + - **Global Accessibility**: Supports international developer community - **Consistent Localization**: Same i18n system across CLI and VS Code extension - **Extensible**: Easy to add new languages by adding JSON files @@ -56,6 +66,7 @@ Implementaremos un sistema i18n personalizado con un paquete dedicado: - **Developer Experience**: Simple API for developers ### Negative + - **Maintenance Overhead**: All user-facing strings need translation - **Coordination**: Changes require updates to all locale files - **Testing Complexity**: Need to test multiple language scenarios @@ -63,6 +74,7 @@ Implementaremos un sistema i18n personalizado con un paquete dedicado: ### Technical Implementation #### Locale File Structure + ```json { "commands": { @@ -88,18 +100,20 @@ Implementaremos un sistema i18n personalizado con un paquete dedicado: ``` #### API Design + ```typescript // Basic translation -t('commands.init.description') +t("commands.init.description"); // With interpolation -t('errors.fileNotFound', { filename: 'package.json' }) +t("errors.fileNotFound", { filename: "package.json" }); // Pluralization -t('files.count', { count: 5 }) +t("files.count", { count: 5 }); ``` ### Language Detection Priority + 1. `STACKCODE_LANG` environment variable 2. User configuration file 3. System locale (`process.env.LANG`) @@ -108,21 +122,25 @@ t('files.count', { count: 5 }) ### Package Integration #### CLI Package + - Initialize i18n before command parsing - Use locale for help text and prompts - Support `--lang` flag for temporary override #### VS Code Extension + - Use VS Code's built-in locale detection - Respect VS Code's language settings - Provide language switching in extension settings #### Core Package + - All user-facing error messages support i18n - Template descriptions and comments localized - GitHub integration messages localized ### File Organization + ``` packages/i18n/ ├── src/ @@ -133,6 +151,7 @@ packages/i18n/ ``` ### Future Expansion Strategy + - Additional languages in `locales/` directory - Community contributions for translations - Possible locale validation tools @@ -141,38 +160,45 @@ packages/i18n/ ## Alternatives Considered ### i18next + - **Pros**: Mature, feature-rich, ecosystem support - **Cons**: Heavy dependency, over-engineered for our needs ### React i18n (for VS Code extension only) + - **Pros**: React ecosystem integration - **Cons**: Doesn't solve CLI internationalization ### No internationalization + - **Pros**: Simpler development and maintenance - **Cons**: Limits global adoption and accessibility ## Implementation Guidelines ### Translation Keys + - Use hierarchical dot notation for organization - Descriptive key names that indicate context - Consistent naming patterns across components - Avoid deeply nested structures ### String Management + - All user-facing strings must use i18n system - No hardcoded English strings in code - Include context comments for translators - Use interpolation for dynamic content ### Testing Strategy + - Test default (English) locale thoroughly - Spot check key translations - Test locale switching functionality - Ensure fallbacks work correctly ### Contribution Guidelines + - Native speakers preferred for translations - Translation reviews by multiple contributors - Consistent terminology across all strings diff --git a/docs/es/adr/README.md b/docs/es/adr/README.md index bafd09b..787adc7 100644 --- a/docs/es/adr/README.md +++ b/docs/es/adr/README.md @@ -1,6 +1,6 @@ # Registros de Decisiones Arquitecturales (ADRs) -*Esta es una traducción del documento original en inglés. Para la versión más actualizada, consulte [docs/adr/README.md](../../adr/README.md).* +_Esta es una traducción del documento original en inglés. Para la versión más actualizada, consulte [docs/adr/README.md](../../adr/README.md)._ --- @@ -24,13 +24,15 @@ Cada ADR sigue esta estructura: Decisiones arquitecturales actualmente documentadas: -- **[ADR-001: Estructura Monorepo](./001-monorepo-structure.md)** *(⏳ Planeado)* - Decisión de organizar el proyecto como un monorepo con npm workspaces -- **[ADR-002: TypeScript y ES Modules](./002-typescript-esm.md)** *(⏳ Planeado)* - Elección de TypeScript con ESM como stack de desarrollo principal -- **[ADR-003: Diseño de Interfaz de Línea de Comandos](./003-cli-design.md)** *(⏳ Planeado)* - Selección del framework CLI y arquitectura de comandos -- **[ADR-004: Estrategia de Internacionalización](./004-i18n-strategy.md)** *(⏳ Planeado)* - Enfoque de implementación de soporte multi-idioma +- **[ADR-001: Estructura Monorepo](./001-monorepo-structure.md)** _(⏳ Planeado)_ - Decisión de organizar el proyecto como un monorepo con npm workspaces +- **[ADR-002: TypeScript y ES Modules](./002-typescript-esm.md)** _(⏳ Planeado)_ - Elección de TypeScript con ESM como stack de desarrollo principal +- **[ADR-003: Diseño de Interfaz de Línea de Comandos](./003-cli-design.md)** _(⏳ Planeado)_ - Selección del framework CLI y arquitectura de comandos +- **[ADR-004: Estrategia de Internacionalización](./004-i18n-strategy.md)** _(⏳ Planeado)_ - Enfoque de implementación de soporte multi-idioma ### ADRs Futuros + Decisiones arquitecturales adicionales a ser documentadas: + - Arquitectura de la Extensión VS Code - Diseño del Sistema de Plantillas - Estrategia de Integración GitHub @@ -72,4 +74,4 @@ Vea la [guía de contribución](../../CONTRIBUTING.md#internationalization) para --- -*Para la documentación en inglés, visite [docs/adr/](../../adr/)* +_Para la documentación en inglés, visite [docs/adr/](../../adr/)_ diff --git a/docs/pt-BR/ARCHITECTURE.md b/docs/pt-BR/ARCHITECTURE.md index 261ca90..307ed83 100644 --- a/docs/pt-BR/ARCHITECTURE.md +++ b/docs/pt-BR/ARCHITECTURE.md @@ -45,23 +45,28 @@ O StackCode segue uma **arquitetura de monorepo modular** com clara separação ## 📦 Estrutura de Pacotes ### 1. **@stackcode/cli** - Interface de Linha de Comando + **Propósito:** Interface primária do usuário para funcionalidades do StackCode. **Componentes Principais:** + - **Comandos**: Implementações dos comandos CLI (`init`, `generate`, `commit`, etc.) - **Manipuladores de Argumentos**: Parsing e validação de argumentos usando Yargs - **Utilitários**: Funções auxiliares específicas da CLI **Responsabilidades:** + - Parsing de argumentos de linha de comando - Interação com o usuário via terminal - Orquestração de chamadas para o pacote core - Tratamento de erros e apresentação de resultados ### 2. **@stackcode/core** - Lógica de Negócio Central + **Propósito:** Implementa toda a lógica de negócio principal e funcionalidades centrais. **Componentes Principais:** + - **Geradores**: Criação de projetos a partir de templates - **Validadores**: Validação de código e configurações - **Integração GitHub**: API e funcionalidades de integração @@ -70,6 +75,7 @@ O StackCode segue uma **arquitetura de monorepo modular** com clara separação - **Utilitários**: Funções compartilhadas entre pacotes **Responsabilidades:** + - Processamento de templates e scaffolding - Integração com APIs externas (GitHub) - Validação de estruturas de projeto @@ -77,23 +83,28 @@ O StackCode segue uma **arquitetura de monorepo modular** com clara separação - Gerenciamento de dependências e configurações ### 3. **@stackcode/i18n** - Internacionalização + **Propósito:** Fornece suporte multi-idioma para toda a suite StackCode. **Componentes Principais:** + - **Gerenciador de Locales**: Carregamento e gerenciamento de traduções - **Sistema de Tradução**: API de tradução e fallbacks - **Detecção de Idioma**: Detecção automática do idioma preferido do usuário **Responsabilidades:** + - Carregamento de arquivos de tradução - Fornecimento de strings localizadas - Gerenciamento de idiomas suportados - Fallback para idioma padrão quando necessário ### 4. **stackcode-vscode** - Extensão VS Code + **Propósito:** Integração nativa com VS Code para experiência de desenvolvimento aprimorada. **Componentes Principais:** + - **Comandos da Extensão**: Comandos VS Code que utilizam funcionalidades do StackCode - **Providers**: Providers de dashboard, tree view e webview - **Monitores**: Monitoramento de arquivos e mudanças do Git @@ -101,6 +112,7 @@ O StackCode segue uma **arquitetura de monorepo modular** com clara separação - **UI Webview**: Interface de usuário rica baseada na web **Responsabilidades:** + - Integração com comandos VS Code - Monitoramento de atividade do workspace - Fornecimento de UI rica via webviews @@ -109,16 +121,19 @@ O StackCode segue uma **arquitetura de monorepo modular** com clara separação ## 🔄 Fluxo de Dados e Interações ### Fluxo Típico de Comando CLI + ``` Usuário → CLI Input → Yargs Parser → Command Handler → @stackcode/core → Execução → Resultado ``` ### Fluxo da Extensão VS Code + ``` Ação do Usuário → Comando VS Code → Extension Handler → @stackcode/core → Atualização UI → Feedback Visual ``` ### Fluxo de Internacionalização + ``` Solicitação de String → i18n Manager → Carregamento de Locale → String Traduzida → Interface do Usuário ``` @@ -126,28 +141,34 @@ Solicitação de String → i18n Manager → Carregamento de Locale → String T ## 🎯 Princípios de Design ### 1. **Separação de Responsabilidades** + Cada pacote tem responsabilidades claramente definidas: + - **CLI**: Interação com usuário e parsing de comandos - **Core**: Lógica de negócio e processamento - **i18n**: Localização e traduções - **VSCode**: Integração com editor e UI rica ### 2. **Reutilização de Código** + - Funcionalidades centrais ficam no pacote `@stackcode/core` - Interfaces (CLI e VS Code) consomem a mesma lógica de negócio - Sistema de templates compartilhado entre todos os pontos de entrada ### 3. **Extensibilidade** + - Sistema de templates permite adição fácil de novos stacks - Arquitetura de plugins para extensões futuras - APIs bem definidas entre pacotes ### 4. **Type Safety** + - TypeScript em todo o projeto - Tipos compartilhados entre pacotes - Validação de runtime com schemas quando necessário ### 5. **Testabilidade** + - Unidades testáveis pequenas e focadas - Mocking de dependências externas - Testes de integração entre pacotes @@ -155,22 +176,26 @@ Cada pacote tem responsabilidades claramente definidas: ## 🔧 Tecnologias e Dependências ### Tecnologias Core + - **TypeScript**: Linguagem principal para type safety - **Node.js**: Runtime para CLI e extensão - **ESM**: Módulos ES para estrutura moderna - **Yargs**: Biblioteca CLI para parsing de argumentos ### Ferramentas de Build + - **TypeScript Compiler**: Transpilação de TypeScript - **ESBuild**: Bundling rápido para a extensão VS Code - **npm workspaces**: Gerenciamento de monorepo ### Testes e Qualidade + - **Jest**: Framework de testes principal - **ESLint**: Linting de código - **Prettier**: Formatação de código ### Integrações Externas + - **GitHub API**: Para funcionalidades de repositório - **VS Code API**: Para integração com editor - **npm registry**: Para publicação de pacotes @@ -178,6 +203,7 @@ Cada pacote tem responsabilidades claramente definidas: ## 📁 Organização de Código ### Estrutura de Diretórios + ``` packages/ ├── cli/ # Interface linha de comando @@ -208,6 +234,7 @@ packages/ ``` ### Convenções de Nomenclatura + - **Arquivos**: camelCase para arquivos TypeScript - **Classes**: PascalCase para classes e interfaces - **Constantes**: UPPER_SNAKE_CASE para constantes @@ -216,16 +243,19 @@ packages/ ## 🔒 Considerações de Segurança ### Validação de Input + - Todas as entradas do usuário são validadas e sanitizadas - Uso de esquemas de validação onde apropriado - Prevenção de path traversal em operações de arquivo ### Gerenciamento de Dependências + - Auditoria regular de dependências para vulnerabilidades - Pinning de versões de dependências críticas - Uso de dependências mínimas necessárias ### Tratamento de Dados Sensíveis + - Tokens e credenciais nunca são logados - Uso de variáveis de ambiente para dados sensíveis - Criptografia para dados persistidos quando necessário @@ -233,11 +263,13 @@ packages/ ## 🚀 Estratégia de Release ### Versionamento + - **Semantic Versioning**: Major.Minor.Patch - **Versões Synchronized**: Todos os pacotes mantêm versão sincronizada - **Changelog**: Changelog detalhado para cada release ### Pipeline de Release + 1. **Desenvolvimento**: Feature branches com PRs 2. **Testes**: CI/CD automatizado com testes completos 3. **Staging**: Release candidates para testes @@ -245,6 +277,7 @@ packages/ 5. **Documentação**: Atualização de docs e guias ### Compatibilidade + - **Breaking Changes**: Apenas em major versions - **Deprecations**: Avisos em minor versions antes de remoção - **Migrations**: Guias de migração para breaking changes @@ -252,6 +285,7 @@ packages/ ## 🔄 Fluxos de Desenvolvimento ### Adicionando Novo Stack de Tecnologia + 1. Criar template em `packages/core/src/templates/novo-stack/` 2. Adicionar tipo em `packages/core/src/types.ts` 3. Implementar gerador em `packages/core/src/generators.ts` @@ -259,6 +293,7 @@ packages/ 5. Atualizar documentação ### Adicionando Novo Comando CLI + 1. Criar handler em `packages/cli/src/commands/` 2. Registrar comando em `packages/cli/src/index.ts` 3. Implementar lógica em `packages/core/src/` @@ -266,6 +301,7 @@ packages/ 5. Atualizar documentação de comandos ### Adicionando Funcionalidade VS Code + 1. Implementar comando em `packages/vscode-extension/src/commands/` 2. Registrar em `package.json` da extensão 3. Adicionar UI necessária em webview @@ -275,16 +311,19 @@ packages/ ## 📊 Métricas e Monitoramento ### Métricas de Qualidade + - **Cobertura de Testes**: >80% para todos os pacotes - **Type Coverage**: >95% TypeScript coverage - **Linting**: Zero issues ESLint/Prettier ### Métricas de Performance + - **Bundle Size**: Monitorar tamanho da extensão VS Code - **Startup Time**: Tempo de inicialização da CLI - **Memory Usage**: Uso de memória durante geração de projetos ### Métricas de Uso + - **Downloads**: Estatísticas npm registry - **Comando Usage**: Telemetria anônima de comandos populares - **Error Rates**: Monitoramento de erros em produção @@ -292,25 +331,29 @@ packages/ ## 🔮 Evolução da Arquitetura ### Próximas Iterações + - **Plugin System**: Sistema de plugins para extensibilidade - **Cloud Integration**: Integração com serviços cloud - **AI Templates**: Templates gerados por IA - **Real-time Collaboration**: Funcionalidades colaborativas ### Considerações de Escalabilidade + - **Micro-frontends**: Possível divisão da extensão VS Code - **Service Architecture**: Migração para arquitetura de serviços - **Caching**: Sistema de cache para templates e metadados --- -*Para mais informações sobre desenvolvimento e contribuição, veja o [Guia de Contribuição](CONTRIBUTING.md).* +_Para mais informações sobre desenvolvimento e contribuição, veja o [Guia de Contribuição](CONTRIBUTING.md)._ + - **Command Layer:** Entry points for all CLI operations - **Command Handlers:** Individual command implementations - **Interactive Prompts:** User guidance and input collection - **Error Handling:** Consistent error reporting and recovery **Architecture:** + ```typescript cli/ ├── src/ @@ -328,9 +371,11 @@ cli/ ``` ### 2. **@stackcode/core** - Business Logic Engine + **Purpose:** Contains all business logic, utilities, and templates. **Key Components:** + - **Generators:** Project and file generation logic - **Validators:** Commit message and project validation - **GitHub Integration:** API interactions and automation @@ -338,6 +383,7 @@ cli/ - **Template System:** Configurable project templates **Architecture:** + ```typescript core/ ├── src/ @@ -364,15 +410,18 @@ core/ ``` ### 3. **@stackcode/i18n** - Internationalization + **Purpose:** Manages multi-language support across all packages. **Features:** + - Dynamic locale detection - Translation loading and caching - Language switching - Fallback mechanisms **Architecture:** + ```typescript i18n/ ├── src/ @@ -383,9 +432,11 @@ i18n/ ``` ### 4. **stackcode-vscode** - VS Code Extension + **Purpose:** Integrates StackCode functionality directly into VS Code. **Key Components:** + - **Extension Commands:** VS Code command palette integration - **File Monitors:** Real-time file change detection - **Git Monitors:** Git state monitoring @@ -394,6 +445,7 @@ i18n/ - **Notification System:** Proactive user guidance **Architecture:** + ```typescript vscode-extension/ ├── src/ @@ -411,6 +463,7 @@ vscode-extension/ ## 🔄 Data Flow and Interactions ### Command Execution Flow + 1. **User Input:** CLI command or VS Code action 2. **Command Parsing:** Yargs (CLI) or VS Code API 3. **Core Logic:** Business logic execution in `@stackcode/core` @@ -418,6 +471,7 @@ vscode-extension/ 5. **Output:** Results displayed to user ### Cross-Package Dependencies + ```mermaid graph TD A[CLI Package] --> C[Core Package] @@ -430,42 +484,50 @@ graph TD ## 🎯 Design Principles ### 1. **Separation of Concerns** + - **CLI Package:** User interface and command handling - **Core Package:** Business logic and utilities - **i18n Package:** Internationalization concerns - **VS Code Extension:** IDE integration ### 2. **Dependency Inversion** + - Higher-level modules don't depend on lower-level modules - Both depend on abstractions (interfaces) - External dependencies are injected, not hardcoded ### 3. **Single Responsibility** + - Each package has a clearly defined purpose - Functions and classes have single, well-defined responsibilities - Templates are modular and composable ### 4. **Open/Closed Principle** + - System is open for extension (new templates, commands) - Closed for modification (core logic remains stable) ## 🛠️ Technology Stack ### Core Technologies + - **TypeScript:** Type safety and modern JavaScript features - **Node.js:** Runtime environment - **ESM:** Modern module system ### CLI-Specific + - **Yargs:** Command-line argument parsing - **Inquirer:** Interactive command-line prompts ### VS Code Extension-Specific + - **VS Code API:** Extension development framework - **React:** Webview UI components - **Vite:** Build tool for webview assets ### Development Tools + - **Vitest/Jest:** Testing frameworks - **ESLint:** Code linting - **Prettier:** Code formatting @@ -474,6 +536,7 @@ graph TD ## 📁 File Organization Strategy ### Monorepo Structure + ``` StackCode/ ├── packages/ # All packages @@ -487,7 +550,9 @@ StackCode/ ``` ### Package Structure Conventions + Each package follows consistent patterns: + - `src/` - Source code - `test/` - Test files - `dist/` - Compiled output @@ -499,11 +564,13 @@ Each package follows consistent patterns: ## 🔧 Build System ### TypeScript Compilation + - **Monorepo Build:** `tsc --build` for cross-package dependencies - **Asset Copying:** Templates and locales copied to `dist/` - **Executable Permissions:** CLI entry point marked as executable ### VS Code Extension Build + - **Extension Compilation:** TypeScript to JavaScript - **Webview Build:** Vite for React components - **Package Generation:** `.vsix` file creation @@ -511,11 +578,13 @@ Each package follows consistent patterns: ## 🧪 Testing Strategy ### Unit Testing + - **Core Logic:** Comprehensive tests for business logic - **CLI Commands:** Command execution and error handling - **Validators:** Input validation and error cases ### Integration Testing + - **Cross-Package:** Ensure packages work together - **Template Generation:** Verify output correctness - **GitHub Integration:** API interaction testing @@ -523,22 +592,26 @@ Each package follows consistent patterns: ## 🚀 Deployment and Distribution ### NPM Packages + - **@stackcode/cli:** Published to NPM for global installation - **@stackcode/core:** Internal package, not published separately - **@stackcode/i18n:** Internal package, not published separately ### VS Code Extension + - **Marketplace:** Published to VS Code Marketplace - **VSIX:** Direct installation package available ## 🔮 Extensibility Points ### Template System + - **Custom Templates:** Easy addition of new project types - **Template Composition:** Combining multiple template sources - **Dynamic Configuration:** Runtime template customization ### Command System + - **Plugin Architecture:** Future support for custom commands - **Middleware Support:** Pre/post command hooks - **Configuration Extension:** Custom validation and generation rules diff --git a/docs/pt-BR/CONTRIBUTING.md b/docs/pt-BR/CONTRIBUTING.md index 31bc475..7b8ef37 100644 --- a/docs/pt-BR/CONTRIBUTING.md +++ b/docs/pt-BR/CONTRIBUTING.md @@ -19,6 +19,7 @@ Antes de contribuir, familiarize-se com a arquitetura do projeto: - **[🛠️ Stacks de Tecnologia](STACKS.md)** - Frameworks suportados e templates de projeto Entender a arquitetura ajudará você a: + - Escolher o pacote certo para suas mudanças - Seguir padrões e convenções estabelecidos - Entender dependências entre pacotes @@ -27,26 +28,30 @@ Entender a arquitetura ajudará você a: ## 🚀 Configuração de Desenvolvimento 1. **Fork e Clone** + ```bash git clone https://github.com/seu-usuario/StackCode.git cd StackCode ``` 2. **Instalar Dependências** + ```bash npm install ``` 3. **Construir o Projeto** + ```bash npm run build ``` 4. **Testar sua Configuração** + ```bash # Executar testes npm test - + # Testar CLI localmente node packages/cli/dist/index.js --help ``` @@ -54,34 +59,40 @@ Entender a arquitetura ajudará você a: ## 🤝 Como Contribuir ### 🐛 Relatórios de Bug + - Verifique [issues existentes](https://github.com/YagoBorba/StackCode/issues) primeiro - Forneça passos claros de reprodução - Inclua detalhes do ambiente (OS, versão Node.js, etc.) - Use o template de relatório de bug ### ✨ Solicitações de Recursos + - Abra uma issue para discutir o recurso primeiro - Explique o caso de uso e benefícios - Considere se se encaixa no escopo do projeto - Forneça ideias de implementação se possível ### 📝 Melhorias na Documentação + - Corrija erros de digitação, melhore a clareza, adicione exemplos - Atualize docs ao adicionar novos recursos - Ajude com traduções (veja [Internacionalização](#internationalization)) ### 🛠️ Contribuições de Código + - Escolha issues marcadas com `good-first-issue` ou `help-wanted` - Siga o [fluxo de trabalho de desenvolvimento](#development-workflow) - Garanta que todos os testes passem - Adicione testes para nova funcionalidade ### 🌐 Adicionando Novos Stacks de Tecnologia + Veja o guia abrangente em [CONTRIBUTING.md principal](../../CONTRIBUTING.md#adding-new-technology-stacks). ## � Fluxo de Trabalho de Desenvolvimento 1. **Criar um Branch de Feature** + ```bash git checkout develop git pull origin develop @@ -94,6 +105,7 @@ Veja o guia abrangente em [CONTRIBUTING.md principal](../../CONTRIBUTING.md#addi - Atualize documentação conforme necessário 3. **Testar Completamente** + ```bash npm test npm run lint @@ -101,6 +113,7 @@ Veja o guia abrangente em [CONTRIBUTING.md principal](../../CONTRIBUTING.md#addi ``` 4. **Commit suas Mudanças** + ```bash # Use commits convencionais com emojis git commit -m "feat(cli): ✨ adicionar novo template de projeto" @@ -115,18 +128,21 @@ Veja o guia abrangente em [CONTRIBUTING.md principal](../../CONTRIBUTING.md#addi ## 🎨 Padrões de Codificação ### Princípios Gerais + - **Código Limpo**: Escreva código legível e manutenível - **Princípios SOLID**: Siga princípios de design SOLID - **Responsabilidade Única**: Cada função/classe deve ter um propósito - **Documentação**: Use comentários TSDoc para APIs públicas ### Diretrizes TypeScript + - Use configuração TypeScript estrita - Prefira tipos explícitos sobre `any` - Use interfaces para formas de objeto - Siga regras ESLint ### Requisitos de Teste + - Adicione testes unitários para nova funcionalidade - Mantenha ou melhore cobertura de testes - Teste tanto cenários de sucesso quanto de erro @@ -137,6 +153,7 @@ Veja o guia abrangente em [CONTRIBUTING.md principal](../../CONTRIBUTING.md#addi Acolhemos contribuições para suportar mais idiomas: ### Estrutura Atual + ``` packages/i18n/src/locales/ ├── en.json # Inglês (primário) @@ -146,12 +163,14 @@ packages/i18n/src/locales/ ### Adicionando Novos Idiomas 1. **Criar Arquivo de Locale** + ```bash # Exemplo para espanhol cp packages/i18n/src/locales/en.json packages/i18n/src/locales/es.json ``` 2. **Traduzir Strings** + ```json { "commands": { @@ -168,6 +187,7 @@ packages/i18n/src/locales/ ``` ### Estrutura Futura (Planejada) + ``` docs/ ├── pt-BR/ # Português (Brasil) @@ -179,12 +199,14 @@ docs/ ## 📏 Processo de Revisão de Código ### Para Contribuidores + - Mantenha PRs focados e pequenos - Escreva descrições claras de PR - Responda ao feedback prontamente - Atualize documentação conforme necessário ### Critérios de Revisão + - Qualidade e manutenibilidade do código - Cobertura e qualidade de testes - Completude da documentação @@ -223,6 +245,7 @@ Precisa de ajuda contribuindo? ## 🙏 Reconhecimento Todos os contribuidores são reconhecidos em: + - [Seção de contribuidores](../../README.md#contributors) no README - Histórico de commits do Git - Notas de release para contribuições significativas @@ -232,43 +255,53 @@ Obrigado por ajudar a tornar o StackCode melhor! 🚀 --- Para mais detalhes, veja: + - **[README Principal](../../README.md)** - Visão geral do projeto - **[Guia de Arquitetura](ARCHITECTURE.md)** - Detalhes técnicos - **[Guia de Auto-hospedagem](SELF_HOSTING_GUIDE.md)** - Opções de deployment - node packages/cli/dist/index.js --help - ``` + node packages/cli/dist/index.js --help + + ``` + + ``` ## 🤝 How to Contribute ### 🐛 Bug Reports + - Check [existing issues](https://github.com/YagoBorba/StackCode/issues) first - Provide clear reproduction steps - Include environment details (OS, Node.js version, etc.) - Use the bug report template ### ✨ Feature Requests + - Open an issue to discuss the feature first - Explain the use case and benefits - Consider if it fits the project's scope - Provide implementation ideas if possible ### 📝 Documentation Improvements + - Fix typos, improve clarity, add examples - Update docs when adding new features - Help with translations (see [Internationalization](#internationalization)) ### 🛠️ Code Contributions + - Pick up issues labeled `good-first-issue` or `help-wanted` - Follow the [development workflow](#development-workflow) - Ensure all tests pass - Add tests for new functionality ### 🌐 Adding New Technology Stacks + See the comprehensive guide in [main CONTRIBUTING.md](../CONTRIBUTING.md#adding-new-technology-stacks). ## 🔄 Development Workflow 1. **Create a Feature Branch** + ```bash git checkout develop git pull origin develop @@ -281,6 +314,7 @@ See the comprehensive guide in [main CONTRIBUTING.md](../CONTRIBUTING.md#adding- - Update documentation as needed 3. **Test Thoroughly** + ```bash npm test npm run lint @@ -288,6 +322,7 @@ See the comprehensive guide in [main CONTRIBUTING.md](../CONTRIBUTING.md#adding- ``` 4. **Commit Your Changes** + ```bash # Use conventional commits with emojis git commit -m "feat(cli): ✨ add new project template" @@ -302,18 +337,21 @@ See the comprehensive guide in [main CONTRIBUTING.md](../CONTRIBUTING.md#adding- ## 🎨 Coding Standards ### General Principles + - **Clean Code**: Write readable, maintainable code - **SOLID Principles**: Follow SOLID design principles - **Single Responsibility**: Each function/class should have one purpose - **Documentation**: Use TSDoc comments for public APIs ### TypeScript Guidelines + - Use strict TypeScript configuration - Prefer explicit types over `any` - Use interfaces for object shapes - Follow ESLint rules ### Testing Requirements + - Add unit tests for new functionality - Maintain or improve test coverage - Test both success and error scenarios @@ -324,6 +362,7 @@ See the comprehensive guide in [main CONTRIBUTING.md](../CONTRIBUTING.md#adding- We welcome contributions to support more languages: ### Current Structure + ``` packages/i18n/src/locales/ ├── en.json # English (primary) @@ -333,12 +372,14 @@ packages/i18n/src/locales/ ### Adding New Languages 1. **Create Locale File** + ```bash # Example for Spanish cp packages/i18n/src/locales/en.json packages/i18n/src/locales/es.json ``` 2. **Translate Strings** + ```json { "commands": { @@ -355,6 +396,7 @@ packages/i18n/src/locales/ ``` ### Future Structure (Planned) + ``` docs/ ├── pt-BR/ # Portuguese (Brazil) @@ -366,12 +408,14 @@ docs/ ## 📏 Code Review Process ### For Contributors + - Keep PRs focused and small - Write clear PR descriptions - Respond to feedback promptly - Update documentation as needed ### Review Criteria + - Code quality and maintainability - Test coverage and quality - Documentation completeness @@ -410,6 +454,7 @@ Need help contributing? ## 🙏 Recognition All contributors are recognized in: + - [Contributors section](../README.md#contributors) in README - Git commit history - Release notes for significant contributions @@ -419,6 +464,7 @@ Thank you for helping make StackCode better! 🚀 --- For more details, see: + - **[Main README](../README.md)** - Project overview - **[Architecture Guide](ARCHITECTURE.md)** - Technical details - **[Self-Hosting Guide](SELF_HOSTING_GUIDE.md)** - Deployment options diff --git a/docs/pt-BR/README.md b/docs/pt-BR/README.md index a2cd85f..c1d29e8 100644 --- a/docs/pt-BR/README.md +++ b/docs/pt-BR/README.md @@ -5,12 +5,14 @@ Bem-vindo ao hub de documentação do StackCode! Este diretório contém documen ## � Navegação Rápida ### 🏗️ **Documentação Principal** + - **[📐 Guia de Arquitetura](ARCHITECTURE.md)** - Visão técnica completa da estrutura do monorepo, princípios de design e interações entre componentes - **[🛠️ Stacks de Tecnologia](STACKS.md)** - Lista detalhada de frameworks, templates e tipos de projeto suportados - **[🤝 Guia de Contribuição](CONTRIBUTING.md)** - Tudo que você precisa saber para contribuir com o StackCode - **[🚀 Guia de Auto-hospedagem](SELF_HOSTING_GUIDE.md)** - Implante e personalize o StackCode para sua organização ### 🏛️ **Decisões Arquiteturais** + - **[Diretório ADR](adr/)** - Registros de Decisões Arquiteturais documentando escolhas de design importantes - [ADR-001: Estrutura Monorepo](adr/001-monorepo-structure.md) - [ADR-002: TypeScript e ES Modules](adr/002-typescript-esm.md) @@ -18,26 +20,33 @@ Bem-vindo ao hub de documentação do StackCode! Este diretório contém documen - [ADR-004: Estratégia de Internacionalização](adr/004-i18n-strategy.md) ### 🌐 **Traduções** -- **[🇧🇷 Português (Brasil)](pt-BR/)** - Documentação em português *(atual)* + +- **[🇧🇷 Português (Brasil)](pt-BR/)** - Documentação em português _(atual)_ - **[🇪🇸 Español](../es/)** - Documentación en español -- **[🇺🇸 English](../)** - English documentation *(original)* +- **[🇺🇸 English](../)** - English documentation _(original)_ ## 🎯 **Documentação por Público** ### 👩‍💻 **Para Desenvolvedores Usando StackCode** + Comece aqui se você quer usar o StackCode em seus projetos: + 1. [README Principal](../../README.md) - Visão geral do projeto e primeiros passos 2. [Stacks de Tecnologia](STACKS.md) - Veja quais tipos de projeto são suportados 3. [Guia de Auto-hospedagem](SELF_HOSTING_GUIDE.md) - Implante para sua organização ### 🛠️ **Para Contribuidores** + Comece aqui se você quer contribuir com o StackCode: + 1. [Guia de Contribuição](CONTRIBUTING.md) - Como contribuir efetivamente 2. [Guia de Arquitetura](ARCHITECTURE.md) - Entenda a base de código 3. [Diretório ADR](adr/) - Aprenda sobre decisões arquiteturais ### � **Para Organizações** + Comece aqui se você quer implantar o StackCode internamente: + 1. [Guia de Auto-hospedagem](SELF_HOSTING_GUIDE.md) - Implantação e personalização 2. [Guia de Arquitetura](ARCHITECTURE.md) - Visão técnica geral 3. [Guia de Contribuição](CONTRIBUTING.md) - Como contribuir com melhorias de volta @@ -45,6 +54,7 @@ Comece aqui se você quer implantar o StackCode internamente: ## 🔧 **Referência Técnica** ### Estrutura do Projeto + ``` docs/ ├── README.md # Este arquivo @@ -65,6 +75,7 @@ docs/ ``` ### Conceitos Principais + - **Arquitetura Monorepo**: StackCode usa um monorepo com múltiplos pacotes - **Sistema de Templates**: Templates de projeto configuráveis para diferentes tecnologias - **CLI + Extensão VS Code**: Múltiplas interfaces para a mesma funcionalidade principal @@ -75,16 +86,19 @@ docs/ Nós acolhemos melhorias em nossa documentação! Veja como ajudar: ### Correções Rápidas + - Corrija erros de digitação, links quebrados ou explicações pouco claras - Adicione exemplos ou melhore os existentes - Atualize informações desatualizadas ### Contribuições Principais + - Escreva novos guias ou tutoriais - Crie documentação para novos recursos - Ajude com traduções ### Ajuda com Traduções + - Traduza documentação existente para seu idioma - Revise traduções de outros contribuidores - Mantenha consistência entre traduções @@ -107,4 +121,4 @@ Precisa de ajuda com o StackCode? --- -*Última atualização: Setembro 2025 | Equipe de Documentação StackCode* +_Última atualização: Setembro 2025 | Equipe de Documentação StackCode_ diff --git a/docs/pt-BR/SELF_HOSTING_GUIDE.md b/docs/pt-BR/SELF_HOSTING_GUIDE.md index 7bd08ca..4666264 100644 --- a/docs/pt-BR/SELF_HOSTING_GUIDE.md +++ b/docs/pt-BR/SELF_HOSTING_GUIDE.md @@ -39,12 +39,14 @@ npm link Para organizações com registros NPM privados: 1. **Fork do Repositório** + ```bash git clone https://github.com/sua-org/StackCode.git cd StackCode ``` 2. **Personalizar Configuração do Pacote** + ```json // Em packages/cli/package.json { @@ -89,15 +91,17 @@ docker run -it sua-org/stackcode init ### Personalização de Templates 1. **Adicionar Templates Personalizados** + ```bash # Criar templates da sua organização mkdir packages/core/src/templates/seu-stack-org - + # Adicionar arquivos de template com extensão .tpl # Use {{nomeVariavel}} para substituições ``` 2. **Modificar Templates Existentes** + ```bash # Editar templates existentes em packages/core/src/templates/ # Atualizar dependências package.json @@ -107,15 +111,13 @@ docker run -it sua-org/stackcode init 3. **Atualizar Definições de Tipo** ```typescript // Em packages/core/src/types.ts - export type SupportedStack = - | "node-js" - | "react" - | "seu-stack-personalizado" // Adicionar seu stack + export type SupportedStack = "node-js" | "react" | "seu-stack-personalizado"; // Adicionar seu stack ``` ### Personalização de Configuração 1. **Configuração Padrão** + ```json // Criar .stackcoderc nos diretórios home dos usuários { @@ -213,6 +215,7 @@ Configuração da Organização: ### Problemas Comuns 1. **Erros de Permissão** + ```bash # Corrigir permissões NPM sudo chown -R $(whoami) ~/.npm @@ -220,19 +223,21 @@ Configuração da Organização: ``` 2. **Template Não Encontrado** + ```bash # Verificar localização do template ls packages/core/src/templates/ - + # Verificar saída do build ls packages/core/dist/templates/ ``` 3. **Problemas de Registro** + ```bash # Verificar configuração do registro npm config get registry - + # Testar conectividade do registro npm ping --registry https://seu-registro.com ``` @@ -273,12 +278,14 @@ Para suporte de auto-hospedagem: --- -*Para mais informações sobre arquitetura e desenvolvimento do StackCode, veja o [Guia de Arquitetura](ARCHITECTURE.md).* +_Para mais informações sobre arquitetura e desenvolvimento do StackCode, veja o [Guia de Arquitetura](ARCHITECTURE.md)._ # Link for global usage + cd packages/cli npm link -``` + +```` ### Option 2: NPM Registry Mirror @@ -288,9 +295,10 @@ For organizations with private NPM registries: ```bash git clone https://github.com/your-org/StackCode.git cd StackCode - ``` +```` 2. **Customize Package Configuration** + ```json // In packages/cli/package.json { @@ -335,15 +343,17 @@ docker run -it your-org/stackcode init ### Template Customization 1. **Add Custom Templates** + ```bash # Create your organization's templates mkdir packages/core/src/templates/your-org-stack - + # Add template files with .tpl extension # Use {{variableName}} for replacements ``` 2. **Modify Existing Templates** + ```bash # Edit existing templates in packages/core/src/templates/ # Update package.json dependencies @@ -353,15 +363,13 @@ docker run -it your-org/stackcode init 3. **Update Type Definitions** ```typescript // In packages/core/src/types.ts - export type SupportedStack = - | "node-js" - | "react" - | "your-custom-stack" // Add your stack + export type SupportedStack = "node-js" | "react" | "your-custom-stack"; // Add your stack ``` ### Configuration Customization 1. **Default Configuration** + ```json // Create .stackcoderc in your users' home directories { @@ -459,6 +467,7 @@ Organization Setup: ### Common Issues 1. **Permission Errors** + ```bash # Fix NPM permissions sudo chown -R $(whoami) ~/.npm @@ -466,19 +475,21 @@ Organization Setup: ``` 2. **Template Not Found** + ```bash # Verify template location ls packages/core/src/templates/ - + # Check build output ls packages/core/dist/templates/ ``` 3. **Registry Issues** + ```bash # Check registry configuration npm config get registry - + # Test registry connectivity npm ping --registry https://your-registry.com ``` @@ -519,4 +530,4 @@ For self-hosting support: --- -*For more information about StackCode architecture and development, see the [Architecture Guide](ARCHITECTURE.md).* +_For more information about StackCode architecture and development, see the [Architecture Guide](ARCHITECTURE.md)._ diff --git a/docs/pt-BR/STACKS.md b/docs/pt-BR/STACKS.md index a6ff1a3..b346c95 100644 --- a/docs/pt-BR/STACKS.md +++ b/docs/pt-BR/STACKS.md @@ -2,11 +2,38 @@ O StackCode suporta múltiplos stacks de tecnologia, cada um projetado com as melhores práticas e estruturas de projeto otimizadas. Este documento fornece uma visão geral de todos os stacks **atualmente implementados** baseados nos templates disponíveis no pacote principal. -## 📋 Stacks Atualmente Disponíveis +## � Validação de Dependências + +O StackCode valida automaticamente se todas as ferramentas necessárias para o stack escolhido estão instaladas antes de prosseguir com a criação do projeto. Isso garante uma experiência de configuração tranquila e previne erros comuns de instalação. + +### Como Funciona + +1. **Detecção Automática**: Quando você executa `stc init`, o StackCode verifica se as ferramentas necessárias estão disponíveis no PATH do seu sistema +2. **Feedback Claro**: Se faltarem ferramentas, você verá exatamente quais precisam ser instaladas +3. **Orientação de Instalação**: Links diretos para páginas oficiais de instalação das ferramentas em falta +4. **Continuação Flexível**: Opção de prosseguir com a criação do projeto mesmo se algumas ferramentas estiverem ausentes + +### Dependências dos Stacks + +| Stack | Ferramentas Necessárias | Validação | +| ------------------------ | ----------------------- | ------------- | +| **React + TypeScript** | `npm` | ✅ Automática | +| **Vue.js + TypeScript** | `npm` | ✅ Automática | +| **Node.js + Express** | `npm` | ✅ Automática | +| **Node.js + TypeScript** | `npm` | ✅ Automática | +| **Go + Gin** | `go` | ✅ Automática | +| **PHP + Laravel** | `composer`, `php` | ✅ Automática | +| **Java + Spring Boot** | `mvn`, `java` | ✅ Automática | +| **Python + FastAPI** | `pip`, `python` | ✅ Automática | + +> **💡 Dica**: Se você vir avisos de dependência, ainda pode criar a estrutura do projeto. Você só precisará instalar as dependências manualmente depois. + +## �📋 Stacks Atualmente Disponíveis ### Stacks Frontend #### React + TypeScript + **Localização do Template:** `packages/core/src/templates/react/` - **Framework**: React 18 com TypeScript @@ -16,6 +43,7 @@ O StackCode suporta múltiplos stacks de tecnologia, cada um projetado com as me - **Recursos**: Modern JSX Transform, configuração ESLint, estrutura de componentes **Estrutura Gerada:** + ``` ├── src/ │ ├── components/ @@ -31,6 +59,7 @@ O StackCode suporta múltiplos stacks de tecnologia, cada um projetado com as me ``` #### Vue.js + TypeScript + **Localização do Template:** `packages/core/src/templates/vue/` - **Framework**: Vue 3 com Composition API e TypeScript @@ -40,6 +69,7 @@ O StackCode suporta múltiplos stacks de tecnologia, cada um projetado com as me - **Recursos**: SFC (Single File Components), padrões modernos do Vue **Estrutura Gerada:** + ``` ├── src/ │ ├── components/ @@ -57,6 +87,7 @@ O StackCode suporta múltiplos stacks de tecnologia, cada um projetado com as me ### Stacks Backend #### Node.js + JavaScript + **Localização do Template:** `packages/core/src/templates/node-js/` - **Runtime**: Node.js com ES6+ @@ -65,6 +96,7 @@ O StackCode suporta múltiplos stacks de tecnologia, cada um projetado com as me - **Recursos**: estrutura Express.js, variáveis de ambiente, configuração de testes **Estrutura Gerada:** + ``` ├── src/ │ ├── controllers/ @@ -81,6 +113,7 @@ O StackCode suporta múltiplos stacks de tecnologia, cada um projetado com as me ``` #### Node.js + TypeScript + **Localização do Template:** `packages/core/src/templates/node-ts/` - **Runtime**: Node.js com TypeScript @@ -88,6 +121,7 @@ O StackCode suporta múltiplos stacks de tecnologia, cada um projetado com as me - **Recursos**: desenvolvimento type-safe, configuração moderna do TypeScript **Estrutura Gerada:** + ``` ├── src/ │ ├── controllers/ @@ -100,12 +134,14 @@ O StackCode suporta múltiplos stacks de tecnologia, cada um projetado com as me ``` #### Python + Configuração Moderna + **Localização do Template:** `packages/core/src/templates/python/` - **Gerenciamento de Pacotes**: pip com pyproject.toml - **Recursos**: estrutura de projeto Python moderna, gerenciamento de dependências **Estrutura Gerada:** + ``` ├── src/ │ └── main.py @@ -113,12 +149,14 @@ O StackCode suporta múltiplos stacks de tecnologia, cada um projetado com as me ``` #### Java + Maven + **Localização do Template:** `packages/core/src/templates/java/` - **Ferramenta de Build**: Maven - **Recursos**: estrutura padrão de projeto Java, configuração Maven **Estrutura Gerada:** + ``` ├── src/ │ └── main/ @@ -127,18 +165,21 @@ O StackCode suporta múltiplos stacks de tecnologia, cada um projetado com as me ``` #### Go + Modules + **Localização do Template:** `packages/core/src/templates/go/` - **Gerenciamento de Pacotes**: Go modules - **Recursos**: projeto Go simples com suporte a módulos **Estrutura Gerada:** + ``` ├── main.go └── go.mod ``` #### PHP + Laravel + **Localização do Template:** `packages/core/src/templates/php/` - **Framework**: estrutura estilo Laravel @@ -146,6 +187,7 @@ O StackCode suporta múltiplos stacks de tecnologia, cada um projetado com as me - **Recursos**: estrutura MVC, variáveis de ambiente **Estrutura Gerada:** + ``` ├── app/ ├── bootstrap/ @@ -162,27 +204,32 @@ Além dos templates de projeto principais, o StackCode fornece suporte abrangent **Localização do Template:** `packages/core/src/templates/gitignore/` ### Desenvolvimento Mobile + - **Android** (`android.tpl`) - Android Studio, Gradle, arquivos APK - **Flutter** (`flutter.tpl`) - Dart, arquivos de build Flutter, arquivos específicos da plataforma - **React Native** (`react_native.tpl`) - Metro bundler, builds de plataforma - **Swift** (`swift.tpl`) - Xcode, arquivos de desenvolvimento iOS ### Frameworks Frontend + - **Angular** (`angular.tpl`) - Angular CLI, artefatos de build - **Svelte** (`svelte.tpl`) - SvelteKit, outputs de build ### Backend & Linguagens + - **Go** (`go.tpl`) - binários Go, diretórios vendor - **Java** (`java.tpl`) - Maven, Gradle, arquivos IDE - **Node.js** (`node-js.tpl`, `node-ts.tpl`) - npm, yarn, outputs de build - **PHP** (`php.tpl`) - Composer, artefatos Laravel -- **Python** (`python.tpl`) - pip, ambientes virtuais, __pycache__ +- **Python** (`python.tpl`) - pip, ambientes virtuais, **pycache** - **JavaScript** (`javascript.tpl`) - arquivos gerais de projeto JS ### Ferramentas de Desenvolvimento + - **IDEs** (`ides.tpl`) - configurações VS Code, IntelliJ, Eclipse ### Uso + Ao criar projetos, o StackCode seleciona automaticamente o template `.gitignore` apropriado baseado no stack escolhido, e pode combinar múltiplos templates ao usar recursos como Docker ou IDEs específicas. ## 🔧 Recursos dos Stacks @@ -206,12 +253,13 @@ O StackCode usa automaticamente o gerenciador de pacotes apropriado baseado no t - **npm** para stacks baseados em Node.js (React, Vue, Node.js, Node-TS) - **pip** para projetos Python (com pyproject.toml) - **maven** para projetos Java -- **go mod** para projetos Go +- **go mod** para projetos Go - **composer** para projetos PHP ### Geração Inteligente de .gitignore Todo projeto recebe um arquivo `.gitignore` personalizado que combina: + - **Regras específicas do stack** (baseadas na tecnologia escolhida) - **Regras específicas da IDE** (ambientes de desenvolvimento comuns) - **Regras de ferramentas adicionais** (Docker, gerenciadores de pacotes, artefatos de build) diff --git a/docs/pt-BR/adr/001-monorepo-structure.md b/docs/pt-BR/adr/001-monorepo-structure.md index 59cb1d0..6340dc2 100644 --- a/docs/pt-BR/adr/001-monorepo-structure.md +++ b/docs/pt-BR/adr/001-monorepo-structure.md @@ -1,16 +1,20 @@ # ADR-001: Estrutura Monorepo ## Status + Aceito ## Contexto + O StackCode consiste em múltiplos pacotes relacionados que compartilham funcionalidade comum: + - Uma ferramenta CLI para uso em linha de comando - Uma extensão VS Code para integração com IDE - Lógica de negócio principal que ambas as interfaces usam - Suporte de internacionalização em todos os componentes Precisávamos decidir como organizar esses pacotes relacionados mas distintos de uma forma que: + - Permita compartilhamento de código entre pacotes - Mantenha limites claros entre componentes - Simplifique o gerenciamento de dependências @@ -18,13 +22,16 @@ Precisávamos decidir como organizar esses pacotes relacionados mas distintos de - Reduza a complexidade de desenvolvimento ## Decisão + Usaremos uma estrutura monorepo com os seguintes pacotes: + - `@stackcode/cli` - Interface de linha de comando - `@stackcode/core` - Lógica de negócio compartilhada e utilitários - `@stackcode/i18n` - Suporte de internacionalização - `stackcode-vscode` - Extensão VS Code O monorepo será gerenciado usando npm workspaces, fornecendo: + - Gerenciamento compartilhado de dependências - Linking entre pacotes - Processos de build coordenados @@ -33,6 +40,7 @@ O monorepo será gerenciado usando npm workspaces, fornecendo: ## Consequências ### Positivas + - **Reutilização de Código**: Lógica de negócio principal pode ser compartilhada entre CLI e extensão VS Code - **APIs Consistentes**: Todos os pacotes usam as mesmas interfaces e tipos subjacentes - **Desenvolvimento Simplificado**: Checkout de repositório único fornece acesso a todos os componentes @@ -41,17 +49,20 @@ O monorepo será gerenciado usando npm workspaces, fornecendo: - **Testes Mais Fáceis**: Testes de integração podem abranger múltiplos pacotes ### Negativas + - **Complexidade de Build**: Sistema de build deve lidar com múltiplos pacotes e suas dependências - **Tamanho do Repositório**: Repositório único contém todos os componentes, potencialmente aumentando o tamanho - **Limitações de Ferramentas**: Algumas ferramentas podem não lidar com monorepos de forma otimizada - **Gerenciamento de Dependências**: Mudanças em pacotes principais afetam todos os dependentes ### Riscos + - **Dependências Circulares**: Deve-se ter cuidado para evitar referências circulares entre pacotes - **Ordem de Build**: Ordem de build dos pacotes se torna importante - **Coordenação de Versão**: Todos os pacotes tipicamente precisam ser versionados juntos ### Estratégias de Mitigação + - Usar referências de projeto TypeScript para lidar com dependências de build - Implementar limites e interfaces claros entre pacotes - Usar npm workspaces para gerenciamento de dependências diff --git a/docs/pt-BR/adr/002-typescript-esm.md b/docs/pt-BR/adr/002-typescript-esm.md index 8d2a63d..725654e 100644 --- a/docs/pt-BR/adr/002-typescript-esm.md +++ b/docs/pt-BR/adr/002-typescript-esm.md @@ -1,10 +1,13 @@ # ADR-002: TypeScript e Módulos ES ## Status + Aceito ## Contexto + O StackCode é uma ferramenta para desenvolvedores que precisa: + - Fornecer type safety para lógica de negócio complexa - Suportar recursos modernos do JavaScript - Ser compatível com ambientes Node.js e browser @@ -12,20 +15,24 @@ O StackCode é uma ferramenta para desenvolvedores que precisa: - Suportar tree-shaking para tamanhos ótimos de bundle Precisávamos escolher: + - Linguagem de programação (JavaScript vs TypeScript) - Sistema de módulos (CommonJS vs ES Modules) - Ferramentas de build e estratégia de compilação ## Decisão + Utilizaremos TypeScript com ES Modules (ESM) como nossa stack principal de desenvolvimento: ### TypeScript + - Todo código fonte será escrito em TypeScript - Configuração strict do TypeScript com verificação abrangente de tipos - Definições de tipos compartilhadas entre pacotes - Gerar arquivos de declaração para pacotes publicados ### ES Modules (ESM) + - Usar ES Modules como sistema de módulos primário - Configurar `"type": "module"` em todos os arquivos package.json - Usar sintaxe `import/export` em todo o código base @@ -34,6 +41,7 @@ Utilizaremos TypeScript com ES Modules (ESM) como nossa stack principal de desen ## Fundamentos ### Benefícios do TypeScript + 1. **Type Safety**: Prevenção de erros em tempo de compilação 2. **IntelliSense**: Melhor experiência de desenvolvimento com autocomplete 3. **Refatoração**: Refatoração segura com suporte de IDE @@ -41,6 +49,7 @@ Utilizaremos TypeScript com ES Modules (ESM) como nossa stack principal de desen 5. **Qualidade**: Força padrões de código consistentes ### Benefícios dos ES Modules + 1. **Padrão Moderno**: Padrão JavaScript oficial 2. **Tree Shaking**: Eliminação de código morto 3. **Lazy Loading**: Carregamento dinâmico de módulos @@ -50,6 +59,7 @@ Utilizaremos TypeScript com ES Modules (ESM) como nossa stack principal de desen ## Implementação ### Configuração TypeScript + ```json { "compilerOptions": { @@ -70,6 +80,7 @@ Utilizaremos TypeScript com ES Modules (ESM) como nossa stack principal de desen ``` ### Estrutura de Pacotes + ``` packages/ ├── cli/ @@ -85,6 +96,7 @@ packages/ ``` ### Estratégia de Build + - **Desenvolvimento**: Compilação TypeScript para ESM - **Distribuição**: Arquivos .js + .d.ts para npm - **Bundling**: ESBuild para extensão VS Code @@ -93,6 +105,7 @@ packages/ ## Consequências ### Positivas + - **Type Safety**: Redução significativa de bugs relacionados a tipos - **DX Melhorada**: Melhor experiência de desenvolvimento com IntelliSense - **Futuro-prova**: Alinhamento com padrões modernos do JavaScript @@ -100,26 +113,30 @@ packages/ - **Manutenibilidade**: Código mais fácil de refatorar e manter ### Negativas + - **Curva de Aprendizado**: Equipe precisa conhecer TypeScript - **Tempo de Build**: Compilação adicional no processo de build - **Complexidade**: Configuração mais complexa comparada a JS puro - **Compatibilidade**: Possíveis problemas com bibliotecas CommonJS legadas ### Neutras + - **Tamanho de Bundle**: Impacto mínimo no bundle final - **Runtime**: Zero overhead em runtime (apenas em build time) ## Mitigações ### Para Compatibilidade CommonJS + ```typescript // Para bibliotecas que ainda usam CommonJS -import { createRequire } from 'module'; +import { createRequire } from "module"; const require = createRequire(import.meta.url); -const legacyLib = require('legacy-commonjs-lib'); +const legacyLib = require("legacy-commonjs-lib"); ``` ### Para Desenvolvimentos + ```typescript // Usar caminhos relativos explícitos import { helper } from './utils/helper.js'; // .js extension required @@ -135,32 +152,36 @@ import { helper } from './utils/helper.js'; // .js extension required ``` ### Para Testes + ```javascript // Jest configuration for ESM + TypeScript export default { - preset: 'ts-jest/presets/default-esm', - extensionsToTreatAsEsm: ['.ts'], + preset: "ts-jest/presets/default-esm", + extensionsToTreatAsEsm: [".ts"], globals: { - 'ts-jest': { - useESM: true - } - } + "ts-jest": { + useESM: true, + }, + }, }; ``` ## Alternativas Consideradas ### 1. JavaScript Puro com CommonJS + - **Prós**: Simplicidade, sem build step - **Contras**: Ausência de type safety, experiência de desenvolvimento inferior - **Decisão**: Rejeitado pela falta de type safety ### 2. TypeScript com CommonJS + - **Prós**: Type safety, compatibilidade ampla - **Contras**: Não suporta tree-shaking, padrão legado - **Decisão**: Rejeitado por não ser futuro-prova ### 3. JavaScript com JSDoc Types + - **Prós**: Type checking sem compilação - **Contras**: Tipos verbosos, limitações de expressividade - **Decisão**: Rejeitado pela experiência inferior de desenvolvimento @@ -168,21 +189,25 @@ export default { ## Impacto nos Pacotes ### @stackcode/cli + - Comandos Yargs tipados - Validação de argumentos com tipos - Auto-complete melhorado em IDEs ### @stackcode/core + - APIs fortemente tipadas - Tipos compartilhados entre pacotes - Validação de schemas com tipos ### @stackcode/i18n + - Tipos para chaves de tradução - Type safety para interpolação - Inferência automática de tipos de locale ### stackcode-vscode + - VS Code API totalmente tipada - Webview messaging tipado - Configurações tipadas @@ -190,21 +215,25 @@ export default { ## Cronograma de Implementação ### Fase 1: Configuração Base (Concluída) + - [x] Configurar tsconfig.json base - [x] Configurar ESM em todos os packages - [x] Migrar build scripts ### Fase 2: Migração Core (Concluída) + - [x] Migrar @stackcode/core para TypeScript - [x] Definir tipos centrais - [x] Atualizar testes ### Fase 3: Migração CLI (Concluída) + - [x] Migrar @stackcode/cli para TypeScript - [x] Tipar comandos Yargs - [x] Atualizar testes CLI ### Fase 4: Extensão VS Code (Concluída) + - [x] Migrar extensão para TypeScript - [x] Configurar bundling ESBuild - [x] Testes de integração @@ -212,11 +241,13 @@ export default { ## Monitoramento ### Métricas de Qualidade + - **Type Coverage**: >95% do código com tipos explícitos - **Build Success**: 100% de builds bem-sucedidos - **Test Coverage**: Manter >80% de cobertura com testes tipados ### Indicadores de Sucesso + - Redução de bugs relacionados a tipos em produção - Melhoria na velocidade de desenvolvimento - Feedback positivo da equipe sobre experiência de desenvolvimento @@ -224,11 +255,13 @@ export default { --- -*Este ADR será revisado a cada 6 meses ou quando surgirem problemas significativos com a abordagem atual.* +_Este ADR será revisado a cada 6 meses ou quando surgirem problemas significativos com a abordagem atual._ + - Use `.js` extensions in import statements (TypeScript requirement for ESM) - Support Node.js native ESM loading ### Build Strategy + - Compile TypeScript to JavaScript with ESM output - Use TypeScript project references for monorepo builds - Generate source maps for debugging @@ -237,6 +270,7 @@ export default { ## Consequences ### Positive + - **Type Safety**: Comprehensive compile-time type checking reduces runtime errors - **Modern JavaScript**: Access to latest language features and improvements - **Better IDE Support**: Enhanced autocomplete, refactoring, and navigation @@ -245,24 +279,28 @@ export default { - **Performance**: Native ESM loading in Node.js improves startup time ### Negative + - **Build Complexity**: Requires compilation step and build tooling - **Learning Curve**: Team members need TypeScript knowledge - **Bundle Size**: TypeScript runtime helpers may increase bundle size - **ESM Migration**: Some dependencies may still use CommonJS ### Technical Considerations + - **Import Extensions**: Must use `.js` extensions in TypeScript imports for ESM compatibility - **Dynamic Imports**: Use `import()` for conditional module loading -- **__dirname Replacement**: Use `import.meta.url` for file path resolution +- **\_\_dirname Replacement**: Use `import.meta.url` for file path resolution - **Package Exports**: Define clear entry points in package.json exports field ### Tooling Requirements + - **TypeScript Compiler**: For compilation and type checking - **ESLint with TypeScript**: For code quality and consistency - **Prettier**: For code formatting - **Vitest/Jest**: Testing frameworks with TypeScript support ### Migration Strategy + - Convert all existing JavaScript to TypeScript gradually - Update import statements to use explicit `.js` extensions - Configure build tools to handle TypeScript compilation @@ -271,13 +309,16 @@ export default { ## Alternatives Considered ### JavaScript with JSDoc + - **Pros**: No compilation step, simpler tooling - **Cons**: Less robust type checking, worse IDE support ### CommonJS Modules + - **Pros**: Better ecosystem compatibility, simpler Node.js integration - **Cons**: No tree shaking, legacy module system, worse performance ### Mixed Module System + - **Pros**: Gradual migration, better compatibility - **Cons**: Complexity, confusion, maintenance overhead diff --git a/docs/pt-BR/adr/003-cli-design.md b/docs/pt-BR/adr/003-cli-design.md index 1f15567..2349388 100644 --- a/docs/pt-BR/adr/003-cli-design.md +++ b/docs/pt-BR/adr/003-cli-design.md @@ -1,10 +1,13 @@ # ADR-003: Design da Interface de Linha de Comando ## Status + Aceito ## Contexto + O StackCode fornece uma ferramenta CLI abrangente que precisa: + - Suportar múltiplos comandos complexos com subcomandos - Fornecer prompts interativos para orientação do usuário - Lidar com gerenciamento de configuração @@ -13,21 +16,25 @@ O StackCode fornece uma ferramenta CLI abrangente que precisa: - Ser extensível para comandos futuros Precisávamos escolher: + - Framework/biblioteca CLI - Estrutura e organização de comandos - Sistema de prompts interativos - Estratégia de tratamento de erros ## Decisão + Utilizaremos Yargs como nosso framework CLI primário com Inquirer para prompts interativos: ### Framework Yargs + - Usar Yargs para parsing de comandos, validação e geração de ajuda - Implementar arquitetura baseada em comandos com separação clara - Suportar aliases e atalhos para comandos comuns - Fornecer informações abrangentes de ajuda e uso ### Estrutura de Comandos + ``` stc [subcomando] [opções] @@ -43,6 +50,7 @@ Comandos Principais: ``` ### Sistema de Prompts Interativos + - Usar Inquirer.js para prompts complexos - Implementar fluxos condicionais baseados em respostas - Suporte a diferentes tipos de input (text, select, checkbox, etc.) @@ -51,6 +59,7 @@ Comandos Principais: ## Fundamentos ### Benefícios do Yargs + 1. **Parsing Robusto**: Parsing automático de argumentos com validação 2. **Help Generation**: Geração automática de mensagens de ajuda 3. **Type Safety**: Integração excelente com TypeScript @@ -58,6 +67,7 @@ Comandos Principais: 5. **Standards**: Segue convenções padrão de CLI ### Benefícios do Inquirer + 1. **UX Rica**: Interface interativa rica para usuários 2. **Validação**: Validação integrada de inputs 3. **Flexibilidade**: Múltiplos tipos de prompts @@ -67,33 +77,35 @@ Comandos Principais: ## Implementação ### Estrutura Base do CLI + ```typescript #!/usr/bin/env node -import yargs from 'yargs'; -import { hideBin } from 'yargs/helpers'; +import yargs from "yargs"; +import { hideBin } from "yargs/helpers"; const cli = yargs(hideBin(process.argv)) - .scriptName('stc') - .usage('$0 [opções]') + .scriptName("stc") + .usage("$0 [opções]") .help() .version() .strict() .recommendCommands() - .demandCommand(1, 'Você deve especificar um comando para executar.'); + .demandCommand(1, "Você deve especificar um comando para executar."); // Registrar comandos -cli.commandDir('commands', { - extensions: ['js', 'ts'], - exclude: /\.test\./ +cli.commandDir("commands", { + extensions: ["js", "ts"], + exclude: /\.test\./, }); cli.parse(); ``` ### Estrutura de Comando Individual + ```typescript -import type { CommandModule } from 'yargs'; -import inquirer from 'inquirer'; +import type { CommandModule } from "yargs"; +import inquirer from "inquirer"; interface InitArgs { template?: string; @@ -102,81 +114,84 @@ interface InitArgs { } const initCommand: CommandModule<{}, InitArgs> = { - command: 'init [template]', - describe: 'Inicializar um novo projeto', - + command: "init [template]", + describe: "Inicializar um novo projeto", + builder: (yargs) => { return yargs - .positional('template', { - describe: 'Template do projeto', - type: 'string', - choices: ['node-js', 'react', 'vue', 'go', 'python'] + .positional("template", { + describe: "Template do projeto", + type: "string", + choices: ["node-js", "react", "vue", "go", "python"], }) - .option('directory', { - alias: 'd', - describe: 'Diretório de destino', - type: 'string' + .option("directory", { + alias: "d", + describe: "Diretório de destino", + type: "string", }) - .option('force', { - alias: 'f', - describe: 'Sobrescrever arquivos existentes', - type: 'boolean', - default: false + .option("force", { + alias: "f", + describe: "Sobrescrever arquivos existentes", + type: "boolean", + default: false, }); }, handler: async (argv) => { const { template, directory, force } = argv; - + // Se template não especificado, prompt interativo if (!template) { - const answers = await inquirer.prompt([{ - type: 'list', - name: 'template', - message: 'Qual template você gostaria de usar?', - choices: [ - { name: 'Node.js', value: 'node-js' }, - { name: 'React', value: 'react' }, - { name: 'Vue.js', value: 'vue' }, - { name: 'Go', value: 'go' }, - { name: 'Python', value: 'python' } - ] - }]); - + const answers = await inquirer.prompt([ + { + type: "list", + name: "template", + message: "Qual template você gostaria de usar?", + choices: [ + { name: "Node.js", value: "node-js" }, + { name: "React", value: "react" }, + { name: "Vue.js", value: "vue" }, + { name: "Go", value: "go" }, + { name: "Python", value: "python" }, + ], + }, + ]); + argv.template = answers.template; } - + // Executar lógica de inicialização await executeInit(argv); - } + }, }; export default initCommand; ``` ### Sistema de Configuração + ```typescript interface StackCodeConfig { defaultAuthor?: string; defaultLicense?: string; gitHubToken?: string; preferredTemplates?: string[]; - language?: 'en' | 'pt' | 'es'; + language?: "en" | "pt" | "es"; } class ConfigManager { - private configPath = path.join(os.homedir(), '.stackcoderc'); - + private configPath = path.join(os.homedir(), ".stackcoderc"); + async get( - key: K + key: K, ): Promise { const config = await this.load(); return config[key]; } - + async set( - key: K, - value: StackCodeConfig[K] + key: K, + value: StackCodeConfig[K], ): Promise { const config = await this.load(); config[key] = value; @@ -188,7 +203,9 @@ class ConfigManager { ## Padrões de Design ### 1. Command Pattern + Cada comando é implementado como módulo independente: + ```typescript interface CommandModule { command: string; @@ -199,43 +216,46 @@ interface CommandModule { ``` ### 2. Progressive Disclosure + - Comandos básicos são simples e diretos - Opções avançadas disponíveis via flags - Prompts interativos para usuários iniciantes ### 3. Error-First Design + ```typescript try { await executeCommand(args); process.exit(0); } catch (error) { - console.error(chalk.red('Erro:'), error.message); - + console.error(chalk.red("Erro:"), error.message); + if (args.verbose) { console.error(error.stack); } - + process.exit(1); } ``` ### 4. Consistent Output + ```typescript class OutputManager { success(message: string) { - console.log(chalk.green('✓'), message); + console.log(chalk.green("✓"), message); } - + error(message: string) { - console.error(chalk.red('✗'), message); + console.error(chalk.red("✗"), message); } - + warning(message: string) { - console.warn(chalk.yellow('⚠'), message); + console.warn(chalk.yellow("⚠"), message); } - + info(message: string) { - console.log(chalk.blue('ℹ'), message); + console.log(chalk.blue("ℹ"), message); } } ``` @@ -243,6 +263,7 @@ class OutputManager { ## Consequências ### Positivas + - **Experiência Consistente**: Interface unificada em todos os comandos - **Descobribilidade**: Sistema de ajuda abrangente e sugestões - **Flexibilidade**: Suporte tanto para uso scriptable quanto interativo @@ -250,18 +271,21 @@ class OutputManager { - **Type Safety**: Argumentos e opções totalmente tipados ### Negativas + - **Dependências**: Dependência de libraries externas (Yargs, Inquirer) - **Complexidade**: Setup inicial mais complexo - **Bundle Size**: Tamanho ligeiramente maior do pacote - **Learning Curve**: Desenvolvedores precisam aprender convenções ### Neutras + - **Performance**: Impacto mínimo na performance de startup - **Manutenção**: Necessidade de manter comandos atualizados ## Padrões de Uso ### Modo Não-Interativo (Scripting) + ```bash # Para automação e scripts stc init react --directory ./my-app --force @@ -270,6 +294,7 @@ stc commit --auto --type feat --scope ui ``` ### Modo Interativo (Guided) + ```bash # Para usuários explorando funcionalidades stc init # Prompts para template, diretório, etc. @@ -278,6 +303,7 @@ stc commit # Guided commit com conventional commits ``` ### Modo Híbrido + ```bash # Combinação de argumentos e prompts stc init react # Template especificado, prompt para outros detalhes @@ -287,26 +313,31 @@ stc generate component # Tipo especificado, prompt para name/path ## Implementação de Comandos ### Comando Init + - **Propósito**: Scaffolding de novos projetos - **Interações**: Template selection, project details, configuration - **Outputs**: Project structure, dependency installation, git setup ### Comando Generate + - **Propósito**: Geração de código e arquivos - **Interações**: Type selection, naming, placement - **Outputs**: Generated files, updated imports/exports ### Comando Commit + - **Propósito**: Commits assistidos com conventional commits - **Interações**: Type selection, scope, description - **Outputs**: Formatted commit message, git commit ### Comando Git + - **Propósito**: Operações Git abstraídas e simplificadas - **Subcomandos**: setup, flow, hooks, cleanup - **Outputs**: Git configuration, branch operations ### Comando Release + - **Propósito**: Gerenciamento automatizado de releases - **Interações**: Version bump, changelog generation - **Outputs**: Tagged release, updated changelog, npm publish @@ -314,6 +345,7 @@ stc generate component # Tipo especificado, prompt para name/path ## Internacionalização ### Estrutura de Mensagens + ```typescript interface CLIMessages { commands: { @@ -335,46 +367,48 @@ interface CLIMessages { ``` ### Implementação i18n + ```typescript -import { t } from '@stackcode/i18n'; +import { t } from "@stackcode/i18n"; const initCommand: CommandModule = { - command: 'init [template]', - describe: t('commands.init.description'), - + command: "init [template]", + describe: t("commands.init.description"), + handler: async (argv) => { - const answers = await inquirer.prompt([{ - message: t('commands.init.prompts.template'), - // ... - }]); - } + const answers = await inquirer.prompt([ + { + message: t("commands.init.prompts.template"), + // ... + }, + ]); + }, }; ``` ## Testes ### Estratégia de Testes + ```typescript -describe('init command', () => { - test('should create project with template', async () => { - const args = { template: 'react', directory: './test-project' }; +describe("init command", () => { + test("should create project with template", async () => { + const args = { template: "react", directory: "./test-project" }; await initCommand.handler(args); - - expect(fs.existsSync('./test-project/package.json')).toBe(true); - expect(fs.existsSync('./test-project/src/App.tsx')).toBe(true); + + expect(fs.existsSync("./test-project/package.json")).toBe(true); + expect(fs.existsSync("./test-project/src/App.tsx")).toBe(true); }); - - test('should prompt for template when not provided', async () => { + + test("should prompt for template when not provided", async () => { // Mock inquirer prompts - jest.mocked(inquirer.prompt).mockResolvedValue({ template: 'vue' }); - + jest.mocked(inquirer.prompt).mockResolvedValue({ template: "vue" }); + const args = {}; await initCommand.handler(args); - + expect(inquirer.prompt).toHaveBeenCalledWith( - expect.arrayContaining([ - expect.objectContaining({ name: 'template' }) - ]) + expect.arrayContaining([expect.objectContaining({ name: "template" })]), ); }); }); @@ -383,31 +417,36 @@ describe('init command', () => { ## Monitoramento e Métricas ### Usage Analytics + - Comandos mais utilizados - Templates mais populares - Padrões de erro comuns - Performance de comandos ### Error Tracking + - Tipos de erro por comando - Stack traces para debugging - User feedback e relatórios --- -*Este ADR será revisado conforme feedback dos usuários e evolução das necessidades da CLI.* +_Este ADR será revisado conforme feedback dos usuários e evolução das necessidades da CLI._ + - Each command is implemented as a separate module - Commands follow a consistent interface pattern - Support for subcommands where appropriate (e.g., `git start`, `git finish`) - Global options available across all commands ### Interactive Prompts + - Use Inquirer.js for complex user interactions - Provide guided workflows for complex operations - Validate user input at prompt level - Support default values and smart suggestions ### Error Handling + - Consistent error message formatting - Localized error messages through i18n system - Graceful handling of common error scenarios @@ -416,6 +455,7 @@ describe('init command', () => { ## Consequences ### Positive + - **Developer Experience**: Yargs provides excellent help generation and validation - **Consistency**: Uniform command structure and behavior across all commands - **Extensibility**: Easy to add new commands following established patterns @@ -424,11 +464,13 @@ describe('init command', () => { - **Documentation**: Auto-generated help text keeps documentation in sync ### Negative + - **Bundle Size**: Yargs and Inquirer add significant dependencies - **Complexity**: Learning curve for command configuration - **Performance**: Startup time increased due to framework initialization ### Command Architecture + ``` CLI Commands: ├── init # Project scaffolding @@ -444,32 +486,36 @@ CLI Commands: ``` ### Command Interface Pattern + Each command module exports a function that returns a Yargs command configuration: + ```typescript export function getCommandName(): CommandModule { return { - command: 'command-name [args]', - describe: 'Command description', + command: "command-name [args]", + describe: "Command description", builder: (yargs) => { - return yargs.option('option', { - type: 'string', - describe: 'Option description' + return yargs.option("option", { + type: "string", + describe: "Option description", }); }, handler: async (argv) => { // Command implementation - } + }, }; } ``` ### Interactive Prompt Strategy + - Use prompts for complex multi-step workflows - Provide sensible defaults based on project context - Validate inputs and provide immediate feedback - Support both interactive and non-interactive modes ### Global Configuration + - Support global and project-local configuration - Configuration stored in standard locations (`~/.stackcode`, `.stackcode.json`) - Command-line options override configuration files @@ -478,32 +524,38 @@ export function getCommandName(): CommandModule { ## Alternatives Considered ### Commander.js + - **Pros**: Lighter weight, simpler API - **Cons**: Less feature-rich, manual help generation ### Native Node.js argument parsing + - **Pros**: No dependencies, full control - **Cons**: Significant development effort, poor developer experience ### CLI frameworks (Oclif, Gluegun) + - **Pros**: More opinionated, additional features - **Cons**: More complex, additional abstractions ## Implementation Guidelines ### Command Development + 1. Each command should have comprehensive tests 2. All user-facing strings must support internationalization 3. Commands should validate inputs early and provide clear error messages 4. Support both interactive and programmatic usage ### Error Handling + 1. Use consistent error message formats 2. Provide actionable error messages with suggestions 3. Log detailed error information in debug mode 4. Handle common scenarios gracefully (network issues, permission errors) ### Help and Documentation + 1. Provide clear command descriptions and examples 2. Document all options and their effects 3. Include usage examples in help text diff --git a/docs/pt-BR/adr/004-i18n-strategy.md b/docs/pt-BR/adr/004-i18n-strategy.md index 7b7779d..a044957 100644 --- a/docs/pt-BR/adr/004-i18n-strategy.md +++ b/docs/pt-BR/adr/004-i18n-strategy.md @@ -1,10 +1,13 @@ # ADR-004: Estratégia de Internacionalização ## Status + Aceito ## Contexto + O StackCode é projetado para ser usado por desenvolvedores mundialmente e precisa: + - Suportar múltiplos idiomas para todo texto voltado ao usuário - Fornecer mensagens de erro e prompts localizados - Suportar tanto interfaces CLI quanto extensão VS Code @@ -13,6 +16,7 @@ O StackCode é projetado para ser usado por desenvolvedores mundialmente e preci - Suportar troca dinâmica de idioma Precisávamos decidir: + - Biblioteca e abordagem i18n - Organização de arquivos de locale - Estratégia de detecção de idioma @@ -20,9 +24,11 @@ Precisávamos decidir: - Integração entre pacotes ## Decisão + Implementaremos um sistema i18n customizado com um pacote dedicado: ### Pacote @stackcode/i18n + - Lógica centralizada de internacionalização - Arquivos de locale baseados em JSON - Troca de locale em runtime @@ -30,6 +36,7 @@ Implementaremos um sistema i18n customizado com um pacote dedicado: - Compartilhado entre todos os pacotes ### Estrutura de Locales + ``` packages/i18n/src/locales/ ├── en.json # Inglês (padrão) @@ -39,6 +46,7 @@ packages/i18n/src/locales/ ``` ### Detecção de Idioma + 1. **Configuração explícita**: Configuração do usuário em `~/.stackcoderc` 2. **Variável de ambiente**: `STACKCODE_LANG` ou `LANG` 3. **Detecção do sistema**: `process.env.LANG` ou APIs do sistema @@ -47,6 +55,7 @@ packages/i18n/src/locales/ ## Fundamentos ### Benefícios do Sistema Customizado + 1. **Controle Total**: Controle completo sobre funcionalidades 2. **Performance**: Carregamento otimizado de locales 3. **Flexibilidade**: Customização específica para nossas necessidades @@ -54,6 +63,7 @@ packages/i18n/src/locales/ 5. **Type Safety**: Integração com TypeScript para type safety ### Estrutura de Tradução + ```typescript interface LocaleMessages { // Comandos CLI @@ -119,11 +129,12 @@ interface LocaleMessages { ## Implementação ### API Principal do i18n + ```typescript export class I18nManager { - private currentLocale: string = 'en'; + private currentLocale: string = "en"; private messages: Map = new Map(); - private fallbackLocale: string = 'en'; + private fallbackLocale: string = "en"; constructor() { this.loadLocale(this.fallbackLocale); @@ -133,9 +144,9 @@ export class I18nManager { // Traduzir chave com interpolação t(key: string, params?: Record): string { const message = this.getMessage(key); - + if (!params) return message; - + return message.replace(/{{(\w+)}}/g, (match, paramName) => { return params[paramName] ?? match; }); @@ -161,7 +172,7 @@ export class I18nManager { // Buscar mensagem com fallback private getMessage(key: string): string { - const keys = key.split('.'); + const keys = key.split("."); const currentMessages = this.messages.get(this.currentLocale); const fallbackMessages = this.messages.get(this.fallbackLocale); @@ -169,9 +180,9 @@ export class I18nManager { return path.reduce((current, segment) => current?.[segment], obj); }; - return getValue(currentMessages, keys) || - getValue(fallbackMessages, keys) || - key; // Retorna a chave se nenhuma tradução for encontrada + return ( + getValue(currentMessages, keys) || getValue(fallbackMessages, keys) || key + ); // Retorna a chave se nenhuma tradução for encontrada } // Detecção automática de idioma @@ -180,22 +191,23 @@ export class I18nManager { const envLocale = process.env.STACKCODE_LANG || process.env.LANG; const systemLocale = this.getSystemLocale(); - const locale = configLocale || - this.normalizeLocale(envLocale) || - this.normalizeLocale(systemLocale) || - this.fallbackLocale; + const locale = + configLocale || + this.normalizeLocale(envLocale) || + this.normalizeLocale(systemLocale) || + this.fallbackLocale; this.setLocale(locale); } private normalizeLocale(locale?: string): string | undefined { if (!locale) return undefined; - + // pt_BR -> pt, en_US -> en, etc. - const normalized = locale.split('_')[0].toLowerCase(); - + const normalized = locale.split("_")[0].toLowerCase(); + // Verificar se temos suporte para o idioma - const supportedLocales = ['en', 'pt', 'es']; + const supportedLocales = ["en", "pt", "es"]; return supportedLocales.includes(normalized) ? normalized : undefined; } } @@ -210,39 +222,44 @@ export const t = (key: string, params?: Record): string => { ``` ### Integração CLI + ```typescript -import { t } from '@stackcode/i18n'; +import { t } from "@stackcode/i18n"; const initCommand: CommandModule = { - command: 'init [template]', - describe: t('commands.init.description'), - + command: "init [template]", + describe: t("commands.init.description"), + builder: (yargs) => { - return yargs - .positional('template', { - describe: t('commands.init.prompts.template'), - type: 'string' - }); + return yargs.positional("template", { + describe: t("commands.init.prompts.template"), + type: "string", + }); }, handler: async (argv) => { try { await executeInit(argv); - console.log(t('commands.init.success', { - projectName: argv.projectName - })); + console.log( + t("commands.init.success", { + projectName: argv.projectName, + }), + ); } catch (error) { - console.error(t('commands.init.errors.general', { - error: error.message - })); + console.error( + t("commands.init.errors.general", { + error: error.message, + }), + ); } - } + }, }; ``` ### Integração VS Code Extension + ```typescript -import { t } from '@stackcode/i18n'; +import { t } from "@stackcode/i18n"; export class DashboardProvider implements vscode.WebviewViewProvider { resolveWebviewView(webviewView: vscode.WebviewView): void { @@ -254,12 +271,12 @@ export class DashboardProvider implements vscode.WebviewViewProvider { - ${t('extension.dashboard.title')} + ${t("extension.dashboard.title")} -

${t('extension.dashboard.welcome')}

+

${t("extension.dashboard.welcome")}

-

${t('extension.dashboard.recentProjects')}

+

${t("extension.dashboard.recentProjects")}

@@ -272,6 +289,7 @@ export class DashboardProvider implements vscode.WebviewViewProvider { ## Arquivos de Locale ### Estrutura en.json (Inglês - Base) + ```json { "commands": { @@ -309,6 +327,7 @@ export class DashboardProvider implements vscode.WebviewViewProvider { ``` ### Estrutura pt.json (Português) + ```json { "commands": { @@ -348,62 +367,65 @@ export class DashboardProvider implements vscode.WebviewViewProvider { ## Type Safety ### Tipos TypeScript para i18n + ```typescript // Geração automática de tipos a partir de en.json -type LocaleKey = - | 'commands.init.description' - | 'commands.init.prompts.template' - | 'commands.init.success' - | 'common.success' - | 'common.error' - // ... todas as chaves possíveis +type LocaleKey = + | "commands.init.description" + | "commands.init.prompts.template" + | "commands.init.success" + | "common.success" + | "common.error"; +// ... todas as chaves possíveis // Função tipada para tradução export function t(key: LocaleKey, params?: Record): string; // Validação em tempo de compilação -const message = t('commands.init.description'); // ✅ Válido -const invalid = t('commands.invalid.key'); // ❌ Erro TypeScript +const message = t("commands.init.description"); // ✅ Válido +const invalid = t("commands.invalid.key"); // ❌ Erro TypeScript ``` ### Script de Geração de Tipos + ```typescript // scripts/generate-i18n-types.ts -import fs from 'fs'; -import path from 'path'; +import fs from "fs"; +import path from "path"; -function generateTypesFromLocale(localeObject: any, prefix = ''): string[] { +function generateTypesFromLocale(localeObject: any, prefix = ""): string[] { const keys: string[] = []; - + for (const [key, value] of Object.entries(localeObject)) { const fullKey = prefix ? `${prefix}.${key}` : key; - - if (typeof value === 'string') { + + if (typeof value === "string") { keys.push(`'${fullKey}'`); - } else if (typeof value === 'object') { + } else if (typeof value === "object") { keys.push(...generateTypesFromLocale(value, fullKey)); } } - + return keys; } // Executar para gerar types/i18n.d.ts -const enLocale = JSON.parse(fs.readFileSync('./src/locales/en.json', 'utf8')); +const enLocale = JSON.parse(fs.readFileSync("./src/locales/en.json", "utf8")); const keys = generateTypesFromLocale(enLocale); const typeDefinition = ` -export type LocaleKey = ${keys.join(' | ')}; +export type LocaleKey = ${keys.join(" | ")}; export function t(key: LocaleKey, params?: Record): string; `; -fs.writeFileSync('./types/i18n.d.ts', typeDefinition); +fs.writeFileSync("./types/i18n.d.ts", typeDefinition); ``` ## Processo de Tradução ### Fluxo de Adição de Novas Strings + 1. **Adicionar em en.json**: Sempre começar com versão em inglês 2. **Gerar Tipos**: Executar script de geração de tipos 3. **Implementar Uso**: Usar a nova chave no código @@ -411,6 +433,7 @@ fs.writeFileSync('./types/i18n.d.ts', typeDefinition); 5. **Testar**: Verificar todas as traduções funcionam ### Guidelines de Tradução + - **Consistência**: Manter terminologia consistente - **Contexto**: Fornecer contexto para tradutores - **Interpolação**: Usar {{parameter}} para valores dinâmicos @@ -418,29 +441,30 @@ fs.writeFileSync('./types/i18n.d.ts', typeDefinition); - **Formatação**: Preservar formatação (negrito, itálico, etc.) ### Ferramentas de Tradução + ```typescript // Utilitário para encontrar chaves ausentes export function findMissingTranslations( - baseLocale: string, - targetLocale: string + baseLocale: string, + targetLocale: string, ): string[] { const base = loadLocale(baseLocale); const target = loadLocale(targetLocale); - + const missingKeys: string[] = []; - - function traverse(obj: any, target: any, path = '') { + + function traverse(obj: any, target: any, path = "") { for (const key in obj) { const currentPath = path ? `${path}.${key}` : key; - - if (typeof obj[key] === 'object') { + + if (typeof obj[key] === "object") { traverse(obj[key], target?.[key] || {}, currentPath); } else if (!target || !(key in target)) { missingKeys.push(currentPath); } } } - + traverse(base, target); return missingKeys; } @@ -449,6 +473,7 @@ export function findMissingTranslations( ## Consequências ### Positivas + - **Acessibilidade Global**: Suporte para desenvolvedores de diferentes idiomas - **Experiência Consistente**: Tradução unificada em CLI e VS Code - **Extensibilidade**: Fácil adição de novos idiomas @@ -456,44 +481,49 @@ export function findMissingTranslations( - **Performance**: Carregamento otimizado de locales ### Negativas + - **Manutenção**: Necessidade de manter múltiplos arquivos de tradução - **Complexidade**: Lógica adicional para gerenciamento de idiomas - **Sincronização**: Risco de traduções desatualizadas - **Tamanho**: Bundle ligeiramente maior com múltiplos locales ### Neutras + - **Detecção**: Detecção automática pode não ser sempre precisa - **Fallback**: Usuários podem ver mistura de idiomas em casos extremos ## Monitoramento ### Métricas de Uso + - Distribuição de idiomas entre usuários - Frequência de troca de idioma - Chaves mais utilizadas ### Qualidade das Traduções + - Feedback de usuários sobre traduções - Relatórios de chaves ausentes - Análise de contexto perdido em traduções ### Automatização + ```typescript // CI/CD check para translations export function validateTranslations(): boolean { - const locales = ['en', 'pt', 'es']; - const baseLocale = 'en'; - + const locales = ["en", "pt", "es"]; + const baseLocale = "en"; + for (const locale of locales) { if (locale === baseLocale) continue; - + const missing = findMissingTranslations(baseLocale, locale); if (missing.length > 0) { console.error(`Missing translations in ${locale}:`, missing); return false; } } - + return true; } ``` @@ -501,17 +531,20 @@ export function validateTranslations(): boolean { ## Roadmap de Idiomas ### Fase 1 (Atual) + - [x] Inglês (en) - Base - [x] Português (pt) - Brasileiro - [x] Espanhol (es) - Internacional ### Fase 2 (Futuro) + - [ ] Francês (fr) - [ ] Alemão (de) - [ ] Japonês (ja) - [ ] Chinês Simplificado (zh-CN) ### Fase 3 (Expansão) + - [ ] Russo (ru) - [ ] Italiano (it) - [ ] Coreano (ko) @@ -519,27 +552,31 @@ export function validateTranslations(): boolean { --- -*Este ADR será atualizado conforme expandimos o suporte a idiomas e recebemos feedback da comunidade.* +_Este ADR será atualizado conforme expandimos o suporte a idiomas e recebemos feedback da comunidade._ ### Locale Management + - JSON files for each supported language in `locales/` directory - Hierarchical key structure for organization - Support for interpolation and pluralization - Template literal style for better developer experience ### Language Detection + - Environment variable (`STACKCODE_LANG`) - System locale detection as fallback - User configuration override - VS Code extension uses VS Code's locale ### Supported Languages (Initial) + - English (en) - Primary/fallback language - Portuguese (pt) - Secondary language ## Consequences ### Positive + - **Global Accessibility**: Supports international developer community - **Consistent Localization**: Same i18n system across CLI and VS Code extension - **Extensible**: Easy to add new languages by adding JSON files @@ -548,6 +585,7 @@ export function validateTranslations(): boolean { - **Developer Experience**: Simple API for developers ### Negative + - **Maintenance Overhead**: All user-facing strings need translation - **Coordination**: Changes require updates to all locale files - **Testing Complexity**: Need to test multiple language scenarios @@ -555,6 +593,7 @@ export function validateTranslations(): boolean { ### Technical Implementation #### Locale File Structure + ```json { "commands": { @@ -580,18 +619,20 @@ export function validateTranslations(): boolean { ``` #### API Design + ```typescript // Basic translation -t('commands.init.description') +t("commands.init.description"); // With interpolation -t('errors.fileNotFound', { filename: 'package.json' }) +t("errors.fileNotFound", { filename: "package.json" }); // Pluralization -t('files.count', { count: 5 }) +t("files.count", { count: 5 }); ``` ### Language Detection Priority + 1. `STACKCODE_LANG` environment variable 2. User configuration file 3. System locale (`process.env.LANG`) @@ -600,21 +641,25 @@ t('files.count', { count: 5 }) ### Package Integration #### CLI Package + - Initialize i18n before command parsing - Use locale for help text and prompts - Support `--lang` flag for temporary override #### VS Code Extension + - Use VS Code's built-in locale detection - Respect VS Code's language settings - Provide language switching in extension settings #### Core Package + - All user-facing error messages support i18n - Template descriptions and comments localized - GitHub integration messages localized ### File Organization + ``` packages/i18n/ ├── src/ @@ -625,6 +670,7 @@ packages/i18n/ ``` ### Future Expansion Strategy + - Additional languages in `locales/` directory - Community contributions for translations - Possible locale validation tools @@ -633,38 +679,45 @@ packages/i18n/ ## Alternatives Considered ### i18next + - **Pros**: Mature, feature-rich, ecosystem support - **Cons**: Heavy dependency, over-engineered for our needs ### React i18n (for VS Code extension only) + - **Pros**: React ecosystem integration - **Cons**: Doesn't solve CLI internationalization ### No internationalization + - **Pros**: Simpler development and maintenance - **Cons**: Limits global adoption and accessibility ## Implementation Guidelines ### Translation Keys + - Use hierarchical dot notation for organization - Descriptive key names that indicate context - Consistent naming patterns across components - Avoid deeply nested structures ### String Management + - All user-facing strings must use i18n system - No hardcoded English strings in code - Include context comments for translators - Use interpolation for dynamic content ### Testing Strategy + - Test default (English) locale thoroughly - Spot check key translations - Test locale switching functionality - Ensure fallbacks work correctly ### Contribution Guidelines + - Native speakers preferred for translations - Translation reviews by multiple contributors - Consistent terminology across all strings diff --git a/docs/pt-BR/adr/README.md b/docs/pt-BR/adr/README.md index 8cf065b..378fd09 100644 --- a/docs/pt-BR/adr/README.md +++ b/docs/pt-BR/adr/README.md @@ -1,6 +1,6 @@ # Registros de Decisões Arquiteturais (ADRs) -*Esta é uma tradução do documento original em inglês. Para a versão mais atualizada, consulte [docs/adr/README.md](../../adr/README.md).* +_Esta é uma tradução do documento original em inglês. Para a versão mais atualizada, consulte [docs/adr/README.md](../../adr/README.md)._ --- @@ -24,13 +24,15 @@ Cada ADR segue esta estrutura: Decisões arquiteturais atualmente documentadas: -- **[ADR-001: Estrutura Monorepo](./001-monorepo-structure.md)** *(⏳ Planejado)* - Decisão de organizar o projeto como um monorepo com npm workspaces -- **[ADR-002: TypeScript e ES Modules](./002-typescript-esm.md)** *(⏳ Planejado)* - Escolha do TypeScript com ESM como stack de desenvolvimento principal -- **[ADR-003: Design da Interface de Linha de Comando](./003-cli-design.md)** *(⏳ Planejado)* - Seleção do framework CLI e arquitetura de comandos -- **[ADR-004: Estratégia de Internacionalização](./004-i18n-strategy.md)** *(⏳ Planejado)* - Abordagem de implementação de suporte multi-idioma +- **[ADR-001: Estrutura Monorepo](./001-monorepo-structure.md)** _(⏳ Planejado)_ - Decisão de organizar o projeto como um monorepo com npm workspaces +- **[ADR-002: TypeScript e ES Modules](./002-typescript-esm.md)** _(⏳ Planejado)_ - Escolha do TypeScript com ESM como stack de desenvolvimento principal +- **[ADR-003: Design da Interface de Linha de Comando](./003-cli-design.md)** _(⏳ Planejado)_ - Seleção do framework CLI e arquitetura de comandos +- **[ADR-004: Estratégia de Internacionalização](./004-i18n-strategy.md)** _(⏳ Planejado)_ - Abordagem de implementação de suporte multi-idioma ### ADRs Futuros + Decisões arquiteturais adicionais a serem documentadas: + - Arquitetura da Extensão VS Code - Design do Sistema de Templates - Estratégia de Integração GitHub @@ -72,4 +74,4 @@ Veja o [guia de contribuição](../../CONTRIBUTING.md#internationalization) para --- -*Para a documentação em inglês, visite [docs/adr/](../../adr/)* +_Para a documentação em inglês, visite [docs/adr/](../../adr/)_ diff --git a/packages/cli/README.md b/packages/cli/README.md index 6ef52b8..7574ccd 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -15,7 +15,7 @@ The command-line interface is designed to be modular and easy to extend. - **`src/index.ts`**: The main entry point that initializes the i18n system and registers all available commands with Yargs. - **`src/commands/`**: This directory contains the implementation for each top-level command. Each file exports a `getCommand` function that returns a Yargs `CommandModule`. - - `init.ts`: Handles the project scaffolding wizard. + - `init.ts`: Handles the project scaffolding wizard with intelligent dependency validation. - `generate.ts`: Handles the generation of individual files like `.gitignore`. - `commit.ts`: Provides the interactive conventional commit wizard. - `git.ts`: Orchestrates the Gitflow subcommands. diff --git a/packages/cli/dist/commands/init.js b/packages/cli/dist/commands/init.js index dcaf917..bb795b7 100644 --- a/packages/cli/dist/commands/init.js +++ b/packages/cli/dist/commands/init.js @@ -1,6 +1,6 @@ import fs from "fs/promises"; import path from "path"; -import { scaffoldProject, setupHusky, generateReadmeContent, generateGitignoreContent, runCommand, } from "@stackcode/core"; +import { scaffoldProject, setupHusky, generateReadmeContent, generateGitignoreContent, runCommand, validateStackDependencies, } from "@stackcode/core"; import { t } from "@stackcode/i18n"; import * as ui from "./ui.js"; export const getInitCommand = () => ({ @@ -58,28 +58,81 @@ export const getInitCommand = () => ({ } ui.log.info(` ${t("init.step.git")}`); await runCommand("git", ["init"], { cwd: projectPath }); - ui.log.info(` ${t("init.step.deps")}`); - if (answers.stack === "python") { - await runCommand("pip", ["install", "-e", "."], { cwd: projectPath }); - } - else if (answers.stack === "java") { - await runCommand("mvn", ["install"], { cwd: projectPath }); + // Validate dependencies before attempting to install them + ui.log.info(` ${t("init.step.validate_deps")}`); + const dependencyValidation = await validateStackDependencies(answers.stack); + if (!dependencyValidation.isValid) { + ui.log.warning(t("init.dependencies.missing", { stack: answers.stack })); + dependencyValidation.missingDependencies.forEach(dep => { + ui.log.raw(t("init.dependencies.missing_detail", { command: dep })); + }); + ui.log.raw("\n" + t("init.dependencies.install_instructions")); + dependencyValidation.missingDependencies.forEach(dep => { + const installKey = `init.dependencies.install_${dep}`; + try { + ui.log.raw(t(installKey)); + } + catch { + // If no specific install instruction exists, show generic message + ui.log.raw(` - ${dep}: Check the official documentation for installation instructions`); + } + }); + ui.log.warning("\n" + t("init.dependencies.optional_skip")); + const shouldContinue = await ui.promptForConfirmation(t("init.dependencies.prompt_continue"), false); + if (!shouldContinue) { + ui.log.info(t("common.operation_cancelled")); + return; + } } - else if (answers.stack === "go") { - await runCommand("go", ["mod", "tidy"], { cwd: projectPath }); + else { + ui.log.success(` ${t("init.dependencies.all_available")}`); } - else if (answers.stack === "php") { - await runCommand("composer", ["install"], { cwd: projectPath }); + ui.log.info(` ${t("init.step.deps")}`); + try { + if (answers.stack === "python") { + await runCommand("pip", ["install", "-e", "."], { cwd: projectPath }); + } + else if (answers.stack === "java") { + await runCommand("mvn", ["install"], { cwd: projectPath }); + } + else if (answers.stack === "go") { + await runCommand("go", ["mod", "tidy"], { cwd: projectPath }); + } + else if (answers.stack === "php") { + await runCommand("composer", ["install"], { cwd: projectPath }); + } + else { + await runCommand("npm", ["install"], { cwd: projectPath }); + } } - else { - await runCommand("npm", ["install"], { cwd: projectPath }); + catch (error) { + ui.log.error(`\n${t("init.error.deps_install_failed", { + error: error instanceof Error ? error.message : String(error) + })}`); + ui.log.warning(t("init.error.deps_install_manual")); + ui.log.info(t("init.error.suggested_command")); + if (answers.stack === "python") { + ui.log.raw(" pip install -e ."); + } + else if (answers.stack === "java") { + ui.log.raw(" mvn install"); + } + else if (answers.stack === "go") { + ui.log.raw(" go mod tidy"); + } + else if (answers.stack === "php") { + ui.log.raw(" composer install"); + } + else { + ui.log.raw(" npm install"); + } } ui.log.divider(); ui.log.success(t("init.success.ready")); ui.log.info(`\n${t("init.success.next_steps")}`); - ui.log.raw(` 1. cd ${answers.projectName}`); - ui.log.raw(" 2. Open the project in your favorite editor."); - ui.log.raw(" 3. Start coding! 🎉"); + ui.log.raw(` ${t("init.success.step1", { projectName: answers.projectName })}`); + ui.log.raw(` ${t("init.success.step2")}`); + ui.log.raw(` ${t("init.success.step3")}`); }, }); //# sourceMappingURL=init.js.map \ No newline at end of file diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts index 7f6d675..2e0bf0f 100644 --- a/packages/cli/src/commands/init.ts +++ b/packages/cli/src/commands/init.ts @@ -7,11 +7,17 @@ import { generateReadmeContent, generateGitignoreContent, runCommand, + validateStackDependencies, type ProjectOptions, } from "@stackcode/core"; import { t } from "@stackcode/i18n"; import * as ui from "./ui.js"; +/** + * Creates and returns the init command configuration for yargs. + * This command initializes a new project with the selected stack and configurations. + * @returns The yargs command module for the init command. + */ export const getInitCommand = (): CommandModule => ({ command: "init", describe: t("init.command_description"), @@ -31,7 +37,7 @@ export const getInitCommand = (): CommandModule => ({ return; } } catch { - // Intentionally ignored + // Directory doesn't exist - proceed with creation } ui.log.divider(); @@ -83,24 +89,83 @@ export const getInitCommand = (): CommandModule => ({ ui.log.info(` ${t("init.step.git")}`); await runCommand("git", ["init"], { cwd: projectPath }); - ui.log.info(` ${t("init.step.deps")}`); - if (answers.stack === "python") { - await runCommand("pip", ["install", "-e", "."], { cwd: projectPath }); - } else if (answers.stack === "java") { - await runCommand("mvn", ["install"], { cwd: projectPath }); - } else if (answers.stack === "go") { - await runCommand("go", ["mod", "tidy"], { cwd: projectPath }); - } else if (answers.stack === "php") { - await runCommand("composer", ["install"], { cwd: projectPath }); + ui.log.info(` ${t("init.step.validate_deps")}`); + const dependencyValidation = await validateStackDependencies(answers.stack); + + if (!dependencyValidation.isValid) { + ui.log.warning(t("init.dependencies.missing", { stack: answers.stack })); + dependencyValidation.missingDependencies.forEach((dep) => { + ui.log.raw(t("init.dependencies.missing_detail", { command: dep })); + }); + + ui.log.raw("\n" + t("init.dependencies.install_instructions")); + dependencyValidation.missingDependencies.forEach((dep) => { + const installKey = `init.dependencies.install_${dep}`; + try { + ui.log.raw(t(installKey)); + } catch { + ui.log.raw( + ` - ${dep}: Check the official documentation for installation instructions`, + ); + } + }); + + ui.log.warning("\n" + t("init.dependencies.optional_skip")); + const shouldContinue = await ui.promptForConfirmation( + t("init.dependencies.prompt_continue"), + false, + ); + + if (!shouldContinue) { + ui.log.info(t("common.operation_cancelled")); + return; + } } else { - await runCommand("npm", ["install"], { cwd: projectPath }); + ui.log.success(` ${t("init.dependencies.all_available")}`); + } + + ui.log.info(` ${t("init.step.deps")}`); + try { + if (answers.stack === "python") { + await runCommand("pip", ["install", "-e", "."], { cwd: projectPath }); + } else if (answers.stack === "java") { + await runCommand("mvn", ["install"], { cwd: projectPath }); + } else if (answers.stack === "go") { + await runCommand("go", ["mod", "tidy"], { cwd: projectPath }); + } else if (answers.stack === "php") { + await runCommand("composer", ["install"], { cwd: projectPath }); + } else { + await runCommand("npm", ["install"], { cwd: projectPath }); + } + } catch (error) { + ui.log.error( + `\n${t("init.error.deps_install_failed", { + error: error instanceof Error ? error.message : String(error), + })}`, + ); + ui.log.warning(t("init.error.deps_install_manual")); + ui.log.info(t("init.error.suggested_command")); + + if (answers.stack === "python") { + ui.log.raw(" pip install -e ."); + } else if (answers.stack === "java") { + ui.log.raw(" mvn install"); + } else if (answers.stack === "go") { + ui.log.raw(" go mod tidy"); + } else if (answers.stack === "php") { + ui.log.raw(" composer install"); + } else { + ui.log.raw(" npm install"); + } } ui.log.divider(); ui.log.success(t("init.success.ready")); ui.log.info(`\n${t("init.success.next_steps")}`); - ui.log.raw(` 1. cd ${answers.projectName}`); - ui.log.raw(" 2. Open the project in your favorite editor."); - ui.log.raw(" 3. Start coding! 🎉"); + ui.log.raw( + ` ${t("init.success.step1", { projectName: answers.projectName })}`, + ); + ui.log.raw(` ${t("init.success.step2")}`); + ui.log.raw(` ${t("init.success.step3")}`); }, }); diff --git a/packages/cli/test/commands/init.test.ts b/packages/cli/test/commands/init.test.ts index 7896ea5..3f33356 100644 --- a/packages/cli/test/commands/init.test.ts +++ b/packages/cli/test/commands/init.test.ts @@ -7,6 +7,7 @@ import { generateReadmeContent, generateGitignoreContent, runCommand, + validateStackDependencies, } from "@stackcode/core"; import { getInitCommand } from "../../src/commands/init"; @@ -16,6 +17,7 @@ vi.mock("@stackcode/core", () => ({ generateReadmeContent: vi.fn(), generateGitignoreContent: vi.fn(), runCommand: vi.fn(), + validateStackDependencies: vi.fn(), })); vi.mock("inquirer"); @@ -30,6 +32,7 @@ const mockedCore = { generateReadmeContent: vi.mocked(generateReadmeContent), generateGitignoreContent: vi.mocked(generateGitignoreContent), runCommand: vi.mocked(runCommand), + validateStackDependencies: vi.mocked(validateStackDependencies), }; describe("Init Command", () => { @@ -53,6 +56,11 @@ describe("Init Command", () => { mockedFs.access.mockRejectedValue(new Error("not found")); mockedCore.generateReadmeContent.mockResolvedValue("# Test Project"); mockedCore.generateGitignoreContent.mockResolvedValue("node_modules"); + mockedCore.validateStackDependencies.mockResolvedValue({ + isValid: true, + missingDependencies: [], + availableDependencies: ["npm"], + }); // Act await handler({ _: [], $0: "stc" }); diff --git a/packages/core/README.md b/packages/core/README.md index b8027da..1a77de1 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -77,6 +77,48 @@ Checks if a string conforms to the Conventional Commits specification. - **`message`**: The commit message string to validate. - **Returns**: `true` if valid, `false` otherwise. +#### `isCommandAvailable(command: string): Promise` + +Checks if a command is available in the system PATH. + +- **`command`**: The command to check (e.g., 'go', 'composer', 'mvn'). +- **Returns**: A promise that resolves to `true` if the command is available, `false` otherwise. + +#### `getStackDependencies(stack: string): string[]` + +Gets the required dependencies for a given stack. + +- **`stack`**: The stack name (e.g., 'go', 'php', 'java', 'python'). +- **Returns**: An array of required commands for the stack. + +**Example:** + +```typescript +import { getStackDependencies } from "@stackcode/core"; + +const deps = getStackDependencies("go"); // Returns: ["go"] +const phpDeps = getStackDependencies("php"); // Returns: ["composer", "php"] +``` + +#### `validateStackDependencies(stack: string): Promise<{isValid: boolean; missingDependencies: string[]; availableDependencies: string[]}>` + +Validates if all required dependencies for a stack are available. + +- **`stack`**: The stack name to validate. +- **Returns**: A promise that resolves to an object with validation results. + +**Example:** + +```typescript +import { validateStackDependencies } from "@stackcode/core"; + +const result = await validateStackDependencies("go"); +if (!result.isValid) { + console.log("Missing dependencies:", result.missingDependencies); + // Output: ["go"] if Go is not installed +} +``` + --- ### Testing diff --git a/packages/core/dist/index.d.ts b/packages/core/dist/index.d.ts index d3e0f9b..8ccb278 100644 --- a/packages/core/dist/index.d.ts +++ b/packages/core/dist/index.d.ts @@ -2,7 +2,7 @@ * @fileoverview Main entry point for the @stackcode/core package. * It exports all the public-facing functions and types. */ -export { runCommand, getCommandOutput, getErrorMessage } from "./utils.js"; +export { runCommand, getCommandOutput, getErrorMessage, isCommandAvailable, getStackDependencies, validateStackDependencies } from "./utils.js"; export { generateGitignoreContent, generateReadmeContent, } from "./generators.js"; export { scaffoldProject, setupHusky, type ProjectOptions, } from "./scaffold.js"; export { validateCommitMessage } from "./validator.js"; diff --git a/packages/core/dist/index.js b/packages/core/dist/index.js index 6e18d13..232f512 100644 --- a/packages/core/dist/index.js +++ b/packages/core/dist/index.js @@ -2,7 +2,7 @@ * @fileoverview Main entry point for the @stackcode/core package. * It exports all the public-facing functions and types. */ -export { runCommand, getCommandOutput, getErrorMessage } from "./utils.js"; +export { runCommand, getCommandOutput, getErrorMessage, isCommandAvailable, getStackDependencies, validateStackDependencies } from "./utils.js"; export { generateGitignoreContent, generateReadmeContent, } from "./generators.js"; export { scaffoldProject, setupHusky, } from "./scaffold.js"; export { validateCommitMessage } from "./validator.js"; diff --git a/packages/core/dist/utils.d.ts b/packages/core/dist/utils.d.ts index 7fed72a..55186ad 100644 --- a/packages/core/dist/utils.d.ts +++ b/packages/core/dist/utils.d.ts @@ -19,5 +19,27 @@ export declare function runCommand(command: string, args: string[], options: Run * @returns A promise that resolves with the command's stdout string. */ export declare function getCommandOutput(command: string, args: string[], options: RunCommandOptions): Promise; +/** + * Checks if a command is available in the system PATH. + * @param command - The command to check (e.g., 'go', 'composer', 'mvn'). + * @returns A promise that resolves to true if the command is available, false otherwise. + */ +export declare function isCommandAvailable(command: string): Promise; +/** + * Gets the required dependencies for a given stack. + * @param stack - The stack name (e.g., 'go', 'php', 'java', 'python'). + * @returns An array of required commands for the stack. + */ +export declare function getStackDependencies(stack: string): string[]; +/** + * Validates if all required dependencies for a stack are available. + * @param stack - The stack name to validate. + * @returns A promise that resolves to an object with validation results. + */ +export declare function validateStackDependencies(stack: string): Promise<{ + isValid: boolean; + missingDependencies: string[]; + availableDependencies: string[]; +}>; export declare function getErrorMessage(error: unknown): string; export {}; diff --git a/packages/core/dist/utils.js b/packages/core/dist/utils.js index b41653c..d899525 100644 --- a/packages/core/dist/utils.js +++ b/packages/core/dist/utils.js @@ -66,6 +66,65 @@ export function getCommandOutput(command, args, options) { }); }); } +/** + * Checks if a command is available in the system PATH. + * @param command - The command to check (e.g., 'go', 'composer', 'mvn'). + * @returns A promise that resolves to true if the command is available, false otherwise. + */ +export async function isCommandAvailable(command) { + try { + const checkCommand = process.platform === "win32" ? "where" : "which"; + await getCommandOutput(checkCommand, [command], { cwd: process.cwd() }); + return true; + } + catch { + return false; + } +} +/** + * Gets the required dependencies for a given stack. + * @param stack - The stack name (e.g., 'go', 'php', 'java', 'python'). + * @returns An array of required commands for the stack. + */ +export function getStackDependencies(stack) { + const stackMap = { + go: ["go"], + php: ["composer", "php"], + java: ["mvn", "java"], + python: ["pip", "python"], + // Node.js stacks use npm which should be available if Node.js is installed + "node-js": ["npm"], + "node-ts": ["npm"], + react: ["npm"], + vue: ["npm"], + angular: ["npm"], + svelte: ["npm"], + }; + return stackMap[stack] || ["npm"]; +} +/** + * Validates if all required dependencies for a stack are available. + * @param stack - The stack name to validate. + * @returns A promise that resolves to an object with validation results. + */ +export async function validateStackDependencies(stack) { + const dependencies = getStackDependencies(stack); + const results = await Promise.all(dependencies.map(async (dep) => ({ + command: dep, + available: await isCommandAvailable(dep), + }))); + const missingDependencies = results + .filter(result => !result.available) + .map(result => result.command); + const availableDependencies = results + .filter(result => result.available) + .map(result => result.command); + return { + isValid: missingDependencies.length === 0, + missingDependencies, + availableDependencies, + }; +} export function getErrorMessage(error) { if (typeof error === "object" && error !== null && diff --git a/packages/core/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json b/packages/core/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json index 1788a8a..5a2f515 100644 --- a/packages/core/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json +++ b/packages/core/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json @@ -1 +1 @@ -{"version":"3.2.4","results":[[":test/release.test.ts",{"duration":5.594452999999987,"failed":false}],[":test/github.test.ts",{"duration":9.374942999999973,"failed":false}],[":test/validator.test.ts",{"duration":3.7261689999999987,"failed":false}]]} \ No newline at end of file +{"version":"3.2.4","results":[[":test/release.test.ts",{"duration":5.826772000000005,"failed":false}],[":test/github.test.ts",{"duration":5.507145000000037,"failed":false}],[":test/validator.test.ts",{"duration":3.6768339999999853,"failed":false}]]} \ No newline at end of file diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 326e66c..41d6dfc 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -3,7 +3,14 @@ * It exports all the public-facing functions and types. */ -export { runCommand, getCommandOutput, getErrorMessage } from "./utils.js"; +export { + runCommand, + getCommandOutput, + getErrorMessage, + isCommandAvailable, + getStackDependencies, + validateStackDependencies, +} from "./utils.js"; export { generateGitignoreContent, generateReadmeContent, diff --git a/packages/core/src/utils.ts b/packages/core/src/utils.ts index 445bb25..63842fd 100644 --- a/packages/core/src/utils.ts +++ b/packages/core/src/utils.ts @@ -86,6 +86,81 @@ export function getCommandOutput( }); } +/** + * Checks if a command is available in the system PATH. + * @param command - The command to check (e.g., 'go', 'composer', 'mvn'). + * @returns A promise that resolves to true if the command is available, false otherwise. + */ +export async function isCommandAvailable(command: string): Promise { + try { + const checkCommand = process.platform === "win32" ? "where" : "which"; + await getCommandOutput(checkCommand, [command], { cwd: process.cwd() }); + return true; + } catch { + return false; + } +} + +/** + * Gets the required dependencies for a given stack. + * @param stack - The stack name (e.g., 'go', 'php', 'java', 'python'). + * @returns An array of required commands for the stack. + */ +export function getStackDependencies(stack: string): string[] { + const stackMap: Record = { + go: ["go"], + php: ["composer", "php"], + java: ["mvn", "java"], + python: ["pip", "python"], + "node-js": ["npm"], + "node-ts": ["npm"], + react: ["npm"], + vue: ["npm"], + angular: ["npm"], + svelte: ["npm"], + }; + + return stackMap[stack] || ["npm"]; +} + +/** + * Validates if all required dependencies for a stack are available. + * @param stack - The stack name to validate. + * @returns A promise that resolves to an object with validation results. + */ +export async function validateStackDependencies(stack: string): Promise<{ + isValid: boolean; + missingDependencies: string[]; + availableDependencies: string[]; +}> { + const dependencies = getStackDependencies(stack); + const results = await Promise.all( + dependencies.map(async (dep) => ({ + command: dep, + available: await isCommandAvailable(dep), + })), + ); + + const missingDependencies = results + .filter((result) => !result.available) + .map((result) => result.command); + + const availableDependencies = results + .filter((result) => result.available) + .map((result) => result.command); + + return { + isValid: missingDependencies.length === 0, + missingDependencies, + availableDependencies, + }; +} + +/** + * Extracts a readable error message from various error types. + * @param error - The error object to extract message from. + * @returns A human-readable error message string. + */ export function getErrorMessage(error: unknown): string { if ( typeof error === "object" && diff --git a/packages/i18n/dist/locales/en.json b/packages/i18n/dist/locales/en.json index 103b10e..7adb6cc 100644 --- a/packages/i18n/dist/locales/en.json +++ b/packages/i18n/dist/locales/en.json @@ -173,11 +173,37 @@ "gitignore": "-> Generating .gitignore...", "husky": "-> Configuring Husky...", "git": "-> Initializing Git repository...", - "deps": "-> Installing dependencies (this may take a moment)..." + "deps": "-> Installing dependencies (this may take a moment)...", + "validate_deps": "-> Checking system dependencies..." + }, + "dependencies": { + "checking": "Checking if required tools are installed...", + "missing": "⚠️ Missing tools detected for stack '{stack}':", + "missing_detail": " - {command}: Not found in system", + "install_instructions": "📋 To continue, please install the missing tools:", + "install_go": " - Go: https://golang.org/dl/", + "install_composer": " - Composer: https://getcomposer.org/download/", + "install_maven": " - Maven: https://maven.apache.org/install.html", + "install_python": " - Python/pip: https://python.org/downloads/", + "install_pip": " - Python/pip: https://python.org/downloads/", + "install_php": " - PHP: https://php.net/downloads/", + "install_java": " - Java: https://adoptium.net/", + "install_mvn": " - Maven: https://maven.apache.org/install.html", + "all_available": "✅ All required tools are available.", + "optional_skip": "⚠️ You can continue without installing dependencies, but package installation will fail.", + "prompt_continue": "Do you want to continue anyway?" + }, + "error": { + "deps_install_failed": "⚠️ Dependency installation failed: {error}", + "deps_install_manual": "The project was created successfully, but you'll need to install dependencies manually.", + "suggested_command": "Suggested command:" }, "success": { "ready": "✅ Success! Your project is ready.", - "next_steps": "Next steps:" + "next_steps": "Next steps:", + "step1": "1. cd {projectName}", + "step2": "2. Open the project in your favorite editor.", + "step3": "3. Start coding! 🎉" } }, "release": { diff --git a/packages/i18n/dist/locales/pt.json b/packages/i18n/dist/locales/pt.json index 401776c..d0b5aa7 100644 --- a/packages/i18n/dist/locales/pt.json +++ b/packages/i18n/dist/locales/pt.json @@ -195,11 +195,37 @@ "gitignore": "-> Gerando .gitignore...", "husky": "-> Configurando o Husky...", "git": "-> Inicializando o repositório Git...", - "deps": "-> Instalando dependências (isso pode levar um momento)..." + "deps": "-> Instalando dependências (isso pode levar um momento)...", + "validate_deps": "-> Verificando dependências do sistema..." + }, + "dependencies": { + "checking": "Verificando se as ferramentas necessárias estão instaladas...", + "missing": "⚠️ Ferramentas ausentes detectadas para a stack '{stack}':", + "missing_detail": " - {command}: Não encontrado no sistema", + "install_instructions": "📋 Para continuar, instale as ferramentas em falta:", + "install_go": " - Go: https://golang.org/dl/", + "install_composer": " - Composer: https://getcomposer.org/download/", + "install_maven": " - Maven: https://maven.apache.org/install.html", + "install_python": " - Python/pip: https://python.org/downloads/", + "install_pip": " - Python/pip: https://python.org/downloads/", + "install_php": " - PHP: https://php.net/downloads/", + "install_java": " - Java: https://adoptium.net/", + "install_mvn": " - Maven: https://maven.apache.org/install.html", + "all_available": "✅ Todas as ferramentas necessárias estão disponíveis.", + "optional_skip": "⚠️ Você pode continuar sem instalar as dependências, mas a instalação de pacotes falhará.", + "prompt_continue": "Deseja continuar mesmo assim?" + }, + "error": { + "deps_install_failed": "⚠️ Falha na instalação de dependências: {error}", + "deps_install_manual": "O projeto foi criado com sucesso, mas você precisará instalar as dependências manualmente.", + "suggested_command": "Comando sugerido:" }, "success": { "ready": "✅ Sucesso! Seu projeto está pronto.", - "next_steps": "Próximos passos:" + "next_steps": "Próximos passos:", + "step1": "1. cd {projectName}", + "step2": "2. Abra o projeto no seu editor favorito.", + "step3": "3. Comece a codar! 🎉" } }, "release": { diff --git a/packages/i18n/src/locales/en.json b/packages/i18n/src/locales/en.json index 103b10e..7adb6cc 100644 --- a/packages/i18n/src/locales/en.json +++ b/packages/i18n/src/locales/en.json @@ -173,11 +173,37 @@ "gitignore": "-> Generating .gitignore...", "husky": "-> Configuring Husky...", "git": "-> Initializing Git repository...", - "deps": "-> Installing dependencies (this may take a moment)..." + "deps": "-> Installing dependencies (this may take a moment)...", + "validate_deps": "-> Checking system dependencies..." + }, + "dependencies": { + "checking": "Checking if required tools are installed...", + "missing": "⚠️ Missing tools detected for stack '{stack}':", + "missing_detail": " - {command}: Not found in system", + "install_instructions": "📋 To continue, please install the missing tools:", + "install_go": " - Go: https://golang.org/dl/", + "install_composer": " - Composer: https://getcomposer.org/download/", + "install_maven": " - Maven: https://maven.apache.org/install.html", + "install_python": " - Python/pip: https://python.org/downloads/", + "install_pip": " - Python/pip: https://python.org/downloads/", + "install_php": " - PHP: https://php.net/downloads/", + "install_java": " - Java: https://adoptium.net/", + "install_mvn": " - Maven: https://maven.apache.org/install.html", + "all_available": "✅ All required tools are available.", + "optional_skip": "⚠️ You can continue without installing dependencies, but package installation will fail.", + "prompt_continue": "Do you want to continue anyway?" + }, + "error": { + "deps_install_failed": "⚠️ Dependency installation failed: {error}", + "deps_install_manual": "The project was created successfully, but you'll need to install dependencies manually.", + "suggested_command": "Suggested command:" }, "success": { "ready": "✅ Success! Your project is ready.", - "next_steps": "Next steps:" + "next_steps": "Next steps:", + "step1": "1. cd {projectName}", + "step2": "2. Open the project in your favorite editor.", + "step3": "3. Start coding! 🎉" } }, "release": { diff --git a/packages/i18n/src/locales/pt.json b/packages/i18n/src/locales/pt.json index 401776c..d0b5aa7 100644 --- a/packages/i18n/src/locales/pt.json +++ b/packages/i18n/src/locales/pt.json @@ -195,11 +195,37 @@ "gitignore": "-> Gerando .gitignore...", "husky": "-> Configurando o Husky...", "git": "-> Inicializando o repositório Git...", - "deps": "-> Instalando dependências (isso pode levar um momento)..." + "deps": "-> Instalando dependências (isso pode levar um momento)...", + "validate_deps": "-> Verificando dependências do sistema..." + }, + "dependencies": { + "checking": "Verificando se as ferramentas necessárias estão instaladas...", + "missing": "⚠️ Ferramentas ausentes detectadas para a stack '{stack}':", + "missing_detail": " - {command}: Não encontrado no sistema", + "install_instructions": "📋 Para continuar, instale as ferramentas em falta:", + "install_go": " - Go: https://golang.org/dl/", + "install_composer": " - Composer: https://getcomposer.org/download/", + "install_maven": " - Maven: https://maven.apache.org/install.html", + "install_python": " - Python/pip: https://python.org/downloads/", + "install_pip": " - Python/pip: https://python.org/downloads/", + "install_php": " - PHP: https://php.net/downloads/", + "install_java": " - Java: https://adoptium.net/", + "install_mvn": " - Maven: https://maven.apache.org/install.html", + "all_available": "✅ Todas as ferramentas necessárias estão disponíveis.", + "optional_skip": "⚠️ Você pode continuar sem instalar as dependências, mas a instalação de pacotes falhará.", + "prompt_continue": "Deseja continuar mesmo assim?" + }, + "error": { + "deps_install_failed": "⚠️ Falha na instalação de dependências: {error}", + "deps_install_manual": "O projeto foi criado com sucesso, mas você precisará instalar as dependências manualmente.", + "suggested_command": "Comando sugerido:" }, "success": { "ready": "✅ Sucesso! Seu projeto está pronto.", - "next_steps": "Próximos passos:" + "next_steps": "Próximos passos:", + "step1": "1. cd {projectName}", + "step2": "2. Abra o projeto no seu editor favorito.", + "step3": "3. Comece a codar! 🎉" } }, "release": { diff --git a/packages/vscode-extension/src/commands/GenerateCommand.ts b/packages/vscode-extension/src/commands/GenerateCommand.ts index 2399f76..ba2f5b8 100644 --- a/packages/vscode-extension/src/commands/GenerateCommand.ts +++ b/packages/vscode-extension/src/commands/GenerateCommand.ts @@ -4,7 +4,14 @@ import { ProgressCallback } from "../types"; import { t } from "@stackcode/i18n"; import * as path from "path"; +/** + * Command to generate project files like README.md and .gitignore. + * Provides options to generate individual files or both at once. + */ export class GenerateCommand extends BaseCommand { + /** + * Executes the file generation workflow with user selection. + */ async execute(): Promise { const option = await vscode.window.showQuickPick( [ @@ -60,7 +67,7 @@ export class GenerateCommand extends BaseCommand { return; } } catch { - // File doesn't exist, which is fine + // File doesn't exist - proceed with generation } vscode.window.withProgress( @@ -129,7 +136,7 @@ export class GenerateCommand extends BaseCommand { return; } } catch { - // File doesn't exist, which is fine + // File doesn't exist - proceed with generation } const projectType = await vscode.window.showQuickPick( diff --git a/packages/vscode-extension/src/commands/GitCommand.ts b/packages/vscode-extension/src/commands/GitCommand.ts index 1fd37dc..00266ca 100644 --- a/packages/vscode-extension/src/commands/GitCommand.ts +++ b/packages/vscode-extension/src/commands/GitCommand.ts @@ -133,7 +133,7 @@ export class GitCommand extends BaseCommand { currentBranch = repo.state.HEAD.name || "current branch"; } } catch { - // Fallback to generic message + // Git API unavailable - use generic message } } diff --git a/packages/vscode-extension/src/commands/InitCommand.ts b/packages/vscode-extension/src/commands/InitCommand.ts index 42c442f..aa3817c 100644 --- a/packages/vscode-extension/src/commands/InitCommand.ts +++ b/packages/vscode-extension/src/commands/InitCommand.ts @@ -4,7 +4,14 @@ import { ProgressCallback } from "../types"; import { t } from "@stackcode/i18n"; import * as path from "path"; +/** + * Command to initialize a new project through VS Code interface. + * Provides interactive project setup with stack selection and configuration. + */ export class InitCommand extends BaseCommand { + /** + * Executes the project initialization workflow with user prompts. + */ async execute(): Promise { try { const projectName = await vscode.window.showInputBox({ @@ -86,7 +93,7 @@ export class InitCommand extends BaseCommand { return; } } catch { - // Directory doesn't exist, which is fine + // Directory doesn't exist - proceed with creation } vscode.window.withProgress( diff --git a/packages/vscode-extension/src/monitors/GitMonitor.ts b/packages/vscode-extension/src/monitors/GitMonitor.ts index 1ad205b..7a59106 100644 --- a/packages/vscode-extension/src/monitors/GitMonitor.ts +++ b/packages/vscode-extension/src/monitors/GitMonitor.ts @@ -11,6 +11,10 @@ export interface GitHubRepository { remoteUrl: string; } +/** + * Monitors Git repository changes and provides Git-related functionality. + * Tracks branch changes, detects GitHub repositories, and provides Git workflow helpers. + */ export class GitMonitor implements vscode.Disposable { private proactiveManager: ProactiveNotificationManager; private configManager: ConfigurationManager; @@ -25,6 +29,9 @@ export class GitMonitor implements vscode.Disposable { this.configManager = configManager; } + /** + * Starts monitoring Git repository changes and workspace events. + */ startMonitoring(): void { const gitExtension = vscode.extensions.getExtension("vscode.git"); if (gitExtension) { @@ -249,17 +256,14 @@ export class GitMonitor implements vscode.Disposable { try { const workspaceFolders = vscode.workspace.workspaceFolders; - // Lista de caminhos para tentar const pathsToTry: string[] = []; if (workspaceFolders && workspaceFolders.length > 0) { - // Adicionar workspace folders configurados workspaceFolders.forEach((folder) => { pathsToTry.push(folder.uri.fsPath); }); } - // Adicionar caminhos alternativos comuns em dev containers pathsToTry.push( "/workspaces/StackCode", process.cwd(), @@ -281,7 +285,6 @@ export class GitMonitor implements vscode.Disposable { const configContent = fs.readFileSync(gitConfigPath, "utf8"); console.log(`📄 [GitMonitor] Found .git/config at: ${folderPath}`); - // Procurar pela URL do remote origin const originMatch = configContent.match( /\[remote "origin"\]\s*\n\s*url\s*=\s*(.+)/, ); @@ -365,11 +368,8 @@ export class GitMonitor implements vscode.Disposable { const cleanUrl = url.replace(/\.git$/, ""); const patterns = [ - // HTTPS: https://github.com/owner/repo /^https:\/\/github\.com\/([^/]+)\/([^/]+)$/, - // SSH: git@github.com:owner/repo /^git@github\.com:([^/]+)\/([^/]+)$/, - // SSH alternative: ssh://git@github.com/owner/repo /^ssh:\/\/git@github\.com\/([^/]+)\/([^/]+)$/, ]; diff --git a/packages/vscode-extension/src/providers/DashboardProvider.ts b/packages/vscode-extension/src/providers/DashboardProvider.ts index 18ed879..fd1af4f 100644 --- a/packages/vscode-extension/src/providers/DashboardProvider.ts +++ b/packages/vscode-extension/src/providers/DashboardProvider.ts @@ -4,6 +4,10 @@ import * as fs from "fs"; import { GitHubIssuesService } from "../services/GitHubIssuesService"; import { GitHubAuthService } from "../services/GitHubAuthService"; +/** + * Provides the StackCode dashboard webview interface. + * Manages project statistics, GitHub issues, and integration with various services. + */ export class DashboardProvider implements vscode.WebviewViewProvider, vscode.Disposable { @@ -24,13 +28,7 @@ export class DashboardProvider this._authService = authService; } - public resolveWebviewView( - webviewView: vscode.WebviewView, - // eslint-disable-next-line @typescript-eslint/no-unused-vars - context: vscode.WebviewViewResolveContext, - // eslint-disable-next-line @typescript-eslint/no-unused-vars - token: vscode.CancellationToken, - ) { + public resolveWebviewView(webviewView: vscode.WebviewView) { this._view = webviewView; webviewView.webview.options = { @@ -45,14 +43,12 @@ export class DashboardProvider console.log(`[StackCode] Received command from webview: ${data.type}`); try { - // Tratar comandos específicos do webview switch (data.type) { case "webviewReady": console.log( "[StackCode] Webview reported ready, sending initial data", ); this.updateProjectStats(); - // Buscar issues automaticamente se autenticado if (this._authService?.isAuthenticated) { await this.updateIssues(); } diff --git a/packages/vscode-extension/src/test/extension.test.ts b/packages/vscode-extension/src/test/extension.test.ts index 21e92a5..0ffe6d8 100644 --- a/packages/vscode-extension/src/test/extension.test.ts +++ b/packages/vscode-extension/src/test/extension.test.ts @@ -13,7 +13,6 @@ describe("ProactiveNotificationManager Test Suite", () => { }); it("Should detect conventional commit messages correctly", () => { - // Access private method through any for testing const manager = notificationManager as unknown as { isConventionalCommit: (msg: string) => boolean; }; diff --git a/packages/vscode-extension/src/webview-ui/src/utils/i18n.ts b/packages/vscode-extension/src/webview-ui/src/utils/i18n.ts index aac9355..8b60802 100644 --- a/packages/vscode-extension/src/webview-ui/src/utils/i18n.ts +++ b/packages/vscode-extension/src/webview-ui/src/utils/i18n.ts @@ -60,11 +60,9 @@ const translations = { }; /** - * Hook para obter função de tradução + * Hook to get translation function */ export function useTranslation() { - // Por enquanto, usando português como padrão - // Em uma implementação completa, isso viria das configurações do VSCode const currentLanguage = "pt"; const t = (key: string): string => {