diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2bde7f7..99f6879 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,12 +7,27 @@ First off, thank you for considering contributing! It's people like you that mak - [Code of Conduct](#code-of-conduct) - [How Can I Contribute?](#how-can-i-contribute) - [Development Setup](#development-setup) +- [Architecture Overview](#architecture-overview) - [Adding New Technology Stacks](#adding-new-technology-stacks) - [Git Workflow and Pull Requests](#git-workflow-and-pull-requests) - [Coding Style and Principles](#coding-style-and-principles) - [Commit Message Guidelines](#commit-message-guidelines) - [Testing](#testing) +## Architecture Overview + +Before contributing, please familiarize yourself with the project architecture: + +- **[📐 Architecture Guide](docs/ARCHITECTURE.md)** - Complete overview of the monorepo structure, design principles, and component interactions +- **[🏛️ ADRs](docs/adr/)** - Architectural decision records explaining key design choices +- **[🛠️ 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 +- Write better tests and documentation + ## Code of Conduct This project is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. @@ -371,3 +386,9 @@ docs(readme): 📝 update installation instructions Our CI pipeline will run these tests automatically on your PR. 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 32a829d..8691d6c 100644 --- a/README.md +++ b/README.md @@ -102,11 +102,28 @@ This is the best approach for ensuring everyone on a project uses the exact same npx stc commit ``` +## 📚 Documentation + +For detailed information about the project: + +- **[📐 Architecture Guide](docs/ARCHITECTURE.md)** - Understand the project structure, design principles, and component interactions +- **[🤝 Contributing Guide](docs/CONTRIBUTING.md)** - Development workflow, coding standards, and how to contribute +- **[🛠️ Technology Stacks](docs/STACKS.md)** - Complete list of supported frameworks and project templates +- **[🚀 Self-Hosting Guide](docs/SELF_HOSTING_GUIDE.md)** - Deploy and customize StackCode for your organization +- **[🏛️ ADRs](docs/adr/)** - Architectural decision records documenting key design choices + +### 🌐 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)* + +*Want to help translate the documentation? Check our [contribution guide](docs/CONTRIBUTING.md#internationalization)!* + ## 🤝 Want to Contribute? Awesome! StackCode is an open-source project, and we welcome contributions. -To get started, please read our **[Contribution Guide](CONTRIBUTING.md)**. It has everything you need to know about our workflow, code standards, and how to submit your pull requests. +To get started, please read our **[Contribution Guide](docs/CONTRIBUTING.md)**. It has everything you need to know about our workflow, code standards, and how to submit your pull requests. ## 📝 License diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..901a6ab --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,294 @@ +# StackCode Architecture + +StackCode is a comprehensive DevOps toolkit designed as a monorepo with multiple interconnected packages. This document outlines the project's architecture, design principles, and component interactions. + +## 🏗️ High-Level Architecture + +StackCode follows a **modular monorepo architecture** with clear separation of concerns across different packages. The project is structured to maximize code reuse, maintainability, and extensibility. + +``` +┌─────────────────────────────────────────────────────────────┐ +│ StackCode Ecosystem │ +├─────────────────────────────────────────────────────────────┤ +│ CLI Package │ VS Code Extension │ +│ (@stackcode/cli) │ (stackcode-vscode) │ +│ ┌─────────────────┐ │ ┌─────────────────────────────┐ │ +│ │ Command Layer │ │ │ Extension Commands │ │ +│ │ ├─ init │ │ │ ├─ Dashboard Provider │ │ +│ │ ├─ generate │ │ │ ├─ File/Git Monitors │ │ +│ │ ├─ commit │ │ │ ├─ Notification Manager │ │ +│ │ ├─ git │ │ │ └─ Webview UI │ │ +│ │ ├─ release │ │ └─────────────────────────────┘ │ +│ │ ├─ validate │ │ │ +│ │ └─ config │ │ │ +│ └─────────────────┘ │ │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Shared Foundation │ +├─────────────────────────────────────────────────────────────┤ +│ Core Package │ i18n Package │ +│ (@stackcode/core) │ (@stackcode/i18n) │ +│ ┌─────────────────┐ │ ┌─────────────────────────────┐ │ +│ │ Business Logic │ │ │ Internationalization │ │ +│ │ ├─ Generators │ │ │ ├─ Locale Management │ │ +│ │ ├─ Validators │ │ │ ├─ Translation System │ │ +│ │ ├─ GitHub API │ │ │ └─ Language Detection │ │ +│ │ ├─ Release Mgmt │ │ └─────────────────────────────┘ │ +│ │ ├─ Scaffolding │ │ │ +│ │ └─ Templates │ │ │ +│ └─────────────────┘ │ │ +└─────────────────────────────────────────────────────────────┘ +``` + +## 📦 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/ +│ ├── index.ts # Main CLI entry point +│ ├── commands/ # Command implementations +│ │ ├── init.ts # Project scaffolding +│ │ ├── generate.ts # File generation +│ │ ├── commit.ts # Conventional commits +│ │ ├── git.ts # Git workflow management +│ │ ├── release.ts # Version management +│ │ ├── validate.ts # Commit validation +│ │ └── config.ts # Configuration management +│ └── types/ # CLI-specific type definitions +└── test/ # Command tests +``` + +### 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 +- **Release Management:** Semantic versioning and changelog generation +- **Template System:** Configurable project templates + +**Architecture:** +```typescript +core/ +├── src/ +│ ├── index.ts # Core exports +│ ├── generators.ts # Project/file generators +│ ├── validator.ts # Validation logic +│ ├── github.ts # GitHub API integration +│ ├── release.ts # Version management +│ ├── scaffold.ts # Project scaffolding +│ ├── utils.ts # Shared utilities +│ ├── types.ts # Core type definitions +│ └── templates/ # Project templates +│ ├── common/ # Shared template files +│ ├── node-js/ # Node.js templates +│ ├── react/ # React templates +│ ├── vue/ # Vue.js templates +│ ├── python/ # Python templates +│ ├── java/ # Java templates +│ ├── go/ # Go templates +│ ├── php/ # PHP templates +│ ├── gitignore/ # .gitignore templates +│ └── readme/ # README templates +└── test/ # Core logic tests +``` + +### 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/ +│ ├── index.ts # i18n exports +│ └── locales/ # Translation files +│ ├── en.json # English translations +│ └── pt.json # Portuguese translations +``` + +### 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 +- **Dashboard Provider:** Interactive project dashboard +- **Webview UI:** Rich user interface components +- **Notification System:** Proactive user guidance + +**Architecture:** +```typescript +vscode-extension/ +├── src/ +│ ├── extension.ts # Extension entry point +│ ├── commands/ # VS Code commands +│ ├── config/ # Configuration management +│ ├── monitors/ # File and Git monitoring +│ ├── notifications/ # Notification system +│ ├── providers/ # VS Code providers +│ ├── services/ # Extension services +│ └── webview-ui/ # React-based UI +└── test/ # Extension tests +``` + +## 🔄 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` +4. **i18n Processing:** Localized messages via `@stackcode/i18n` +5. **Output:** Results displayed to user + +### Cross-Package Dependencies +```mermaid +graph TD + A[CLI Package] --> C[Core Package] + A --> D[i18n Package] + B[VS Code Extension] --> C + B --> D + C --> D +``` + +## 🎯 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 +- **GitHub Actions:** CI/CD pipeline + +## 📁 File Organization Strategy + +### Monorepo Structure +``` +StackCode/ +├── packages/ # All packages +│ ├── cli/ # CLI package +│ ├── core/ # Core business logic +│ ├── i18n/ # Internationalization +│ └── vscode-extension/ # VS Code extension +├── docs/ # Project documentation +├── scripts/ # Build and utility scripts +└── types/ # Shared type definitions +``` + +### Package Structure Conventions +Each package follows consistent patterns: +- `src/` - Source code +- `test/` - Test files +- `dist/` - Compiled output +- `package.json` - Package configuration +- `tsconfig.json` - TypeScript configuration +- `README.md` - Package documentation +- `CHANGELOG.md` - Version history + +## 🔧 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 + +## 🧪 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 + +### 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 + +## 📚 Additional Resources + +- **[Contributing Guide](../CONTRIBUTING.md):** Development workflow and standards +- **[Stacks Documentation](STACKS.md):** Supported technology stacks +- **[Self-Hosting Guide](SELF_HOSTING_GUIDE.md):** Deployment options +- **[ADR Directory](adr/):** Architectural decision records diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..50e9c7f --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,237 @@ +# Contributing Guide + +Thank you for considering contributing to StackCode! This guide provides all the information you need to contribute effectively to the project. + +## 📋 Quick Navigation + +- **[Architecture Overview](#architecture-overview)** - Understand the project structure +- **[Development Setup](#development-setup)** - Get your environment ready +- **[Contributing Types](#how-to-contribute)** - Different ways to contribute +- **[Code Standards](#coding-standards)** - Follow our guidelines +- **[Internationalization](#internationalization)** - Help with translations + +## 🏗️ Architecture Overview + +Before contributing, familiarize yourself with the project architecture: + +- **[📐 Architecture Guide](ARCHITECTURE.md)** - Complete overview of the monorepo structure, design principles, and component interactions +- **[🏛️ ADRs](adr/)** - Architectural decision records explaining key design choices +- **[🛠️ 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 +- Write better tests and documentation + +## 🚀 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 + ``` + +## 🤝 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 + git checkout -b feat/your-feature-name + ``` + +2. **Make Your Changes** + - Follow coding standards + - Add tests for new functionality + - Update documentation as needed + +3. **Test Thoroughly** + ```bash + npm test + npm run lint + npm run build + ``` + +4. **Commit Your Changes** + ```bash + # Use conventional commits with emojis + git commit -m "feat(cli): ✨ add new project template" + ``` + +5. **Push and Create PR** + ```bash + git push origin feat/your-feature-name + # Open PR against develop branch + ``` + +## 🎨 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 +- Use descriptive test names + +## 🌐 Internationalization + +We welcome contributions to support more languages: + +### Current Structure +``` +packages/i18n/src/locales/ +├── en.json # English (primary) +└── pt.json # Portuguese +``` + +### 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": { + "init": { + "description": "Inicializar un nuevo proyecto" + } + } + } + ``` + +3. **Test the Translation** + ```bash + STACKCODE_LANG=es node packages/cli/dist/index.js --help + ``` + +### Future Structure (Planned) +``` +docs/ +├── pt-BR/ # Portuguese (Brazil) +├── es/ # Spanish +├── fr/ # French +└── de/ # German +``` + +## 📏 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 +- Adherence to project standards +- Breaking change considerations + +## 🏷️ Issue Labels + +- `good-first-issue` - Perfect for newcomers +- `help-wanted` - Community help needed +- `bug` - Something isn't working +- `enhancement` - New feature or improvement +- `documentation` - Documentation related +- `question` - Further information needed + +## 📋 Contribution Checklist + +Before submitting your PR, ensure: + +- [ ] Code follows project standards +- [ ] Tests are added and passing +- [ ] Documentation is updated +- [ ] Commit messages follow convention +- [ ] PR targets the `develop` branch +- [ ] Breaking changes are documented +- [ ] Performance impact is considered + +## 🆘 Getting Help + +Need help contributing? + +- **[GitHub Discussions](https://github.com/YagoBorba/StackCode/discussions)** - Ask questions +- **[Discord/Slack](#)** - Real-time community chat (if available) +- **[Issues](https://github.com/YagoBorba/StackCode/issues)** - Report problems + +## 🙏 Recognition + +All contributors are recognized in: +- [Contributors section](../README.md#contributors) in README +- Git commit history +- Release notes for significant contributions + +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 new file mode 100644 index 0000000..a97c867 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,109 @@ +# 📚 StackCode Documentation + +Welcome to the StackCode documentation hub! This directory contains comprehensive documentation for developers, contributors, and organizations using StackCode. + +## 📋 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) + - [ADR-003: CLI Design](adr/003-cli-design.md) + - [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)* + +## 🎯 **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 + +## 🔧 **Technical Reference** + +### Project Structure +``` +docs/ +├── README.md # This file +├── ARCHITECTURE.md # Technical architecture +├── CONTRIBUTING.md # Contribution guidelines +├── SELF_HOSTING_GUIDE.md # Deployment guide +├── STACKS.md # Supported technologies +├── adr/ # Architecture Decision Records +│ ├── README.md +│ ├── 001-monorepo-structure.md +│ ├── 002-typescript-esm.md +│ ├── 003-cli-design.md +│ └── 004-i18n-strategy.md +├── pt-BR/ # Portuguese translations +│ └── README.md +└── es/ # Spanish translations + └── README.md +``` + +### 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 +- **Internationalization**: Multi-language support across all interfaces + +## 🤝 **Contributing to Documentation** + +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 + +See our [Contributing Guide](CONTRIBUTING.md) for detailed instructions. + +## 🔗 **External Resources** + +- **[GitHub Repository](https://github.com/YagoBorba/StackCode)** - Source code and issues +- **[NPM Package](https://www.npmjs.com/package/@stackcode/cli)** - Published CLI package +- **[VS Code Extension](https://marketplace.visualstudio.com/items?itemName=YagoBorba.stackcode-vscode)** - VS Code Marketplace + +## 📞 **Getting Help** + +Need help with StackCode? + +- **[GitHub Issues](https://github.com/YagoBorba/StackCode/issues)** - Bug reports and feature requests +- **[GitHub Discussions](https://github.com/YagoBorba/StackCode/discussions)** - Questions and community support +- **[Contributing Guide](CONTRIBUTING.md)** - How to get involved + +--- + +*Last updated: September 2025 | StackCode Documentation Team* diff --git a/docs/SELF_HOSTING_GUIDE.md b/docs/SELF_HOSTING_GUIDE.md new file mode 100644 index 0000000..c3b8399 --- /dev/null +++ b/docs/SELF_HOSTING_GUIDE.md @@ -0,0 +1,276 @@ +# Self-Hosting Guide + +This guide explains how to deploy and customize StackCode for your organization, including setting up private instances and customizing the tool for your specific development workflow. + +## 🏢 Why Self-Host StackCode? + +Self-hosting StackCode provides several benefits for organizations: + +- **Customization**: Tailor templates and workflows to your company's standards +- **Security**: Keep your development processes within your infrastructure +- **Control**: Manage updates and features according to your timeline +- **Integration**: Integrate with internal tools and services +- **Compliance**: Meet specific regulatory or security requirements + +## 🚀 Deployment Options + +### Option 1: Local Development Installation + +For development and testing purposes: + +```bash +# Clone the repository +git clone https://github.com/YagoBorba/StackCode.git +cd StackCode + +# Install dependencies +npm install + +# Build the project +npm run build + +# Link for global usage +cd packages/cli +npm link +``` + +### Option 2: NPM Registry Mirror + +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 + { + "name": "@your-org/stackcode-cli", + "publishConfig": { + "registry": "https://your-npm-registry.com" + } + } + ``` + +3. **Build and Publish** + ```bash + npm run build + npm publish --registry https://your-npm-registry.com + ``` + +### Option 3: Docker Deployment + +Create a containerized version for consistent deployments: + +```dockerfile +# Dockerfile +FROM node:18-alpine + +WORKDIR /app +COPY . . + +RUN npm install && npm run build +RUN npm link packages/cli + +ENTRYPOINT ["stc"] +``` + +```bash +# Build and use +docker build -t your-org/stackcode . +docker run -it your-org/stackcode init +``` + +## 🔧 Customization Options + +### 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 + # Modify folder structures + ``` + +3. **Update Type Definitions** + ```typescript + // In packages/core/src/types.ts + 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 + { + "defaultAuthor": "Your Organization", + "defaultLicense": "Proprietary", + "organizationTemplates": true, + "privateRegistry": "https://your-npm-registry.com" + } + ``` + +2. **Environment Variables** + ```bash + # Set organization defaults + export STACKCODE_DEFAULT_AUTHOR="Your Organization" + export STACKCODE_PRIVATE_REGISTRY="https://your-npm-registry.com" + export STACKCODE_TEMPLATE_PATH="/path/to/custom/templates" + ``` + +### Internationalization + +Add support for your organization's languages: + +```bash +# Add new locale files +echo '{"welcome": "Bienvenido"}' > packages/i18n/src/locales/es.json +echo '{"welcome": "Willkommen"}' > packages/i18n/src/locales/de.json +``` + +## 🔒 Security Considerations + +### Code Review Process + +1. **Fork and Review**: Always fork the repository and review changes +2. **Dependency Scanning**: Regularly scan dependencies for vulnerabilities +3. **Access Control**: Restrict who can modify templates and configurations + +### Network Security + +1. **Private Registries**: Use private NPM registries for internal packages +2. **VPN Access**: Require VPN for accessing internal StackCode instances +3. **Audit Logging**: Log all template generations and modifications + +### Template Security + +1. **Sanitize Inputs**: Validate all user inputs in templates +2. **Restrict File Access**: Limit template file system access +3. **Code Review Templates**: Review all custom templates for security issues + +## 🔄 Update Management + +### Versioning Strategy + +1. **Semantic Versioning**: Follow semver for your organization's version +2. **Release Notes**: Maintain detailed changelog for internal releases +3. **Testing Pipeline**: Test all changes before deploying to teams + +### Update Process + +```bash +# Update from upstream +git remote add upstream https://github.com/YagoBorba/StackCode.git +git fetch upstream +git merge upstream/develop + +# Review changes and test +npm test +npm run build + +# Deploy to your organization +npm publish --registry https://your-npm-registry.com +``` + +## 🏗️ Architecture for Organizations + +### Centralized Configuration + +``` +Organization Setup: +├── stackcode-config/ +│ ├── templates/ # Custom organization templates +│ ├── configs/ # Default configurations +│ └── policies/ # Development policies +├── private-registry/ # Internal NPM registry +└── deployment/ # Deployment scripts +``` + +### Team Integration + +1. **Team Templates**: Create templates specific to different teams +2. **Approval Workflows**: Implement approval processes for new templates +3. **Usage Analytics**: Track template usage across teams + +## 🛠️ Troubleshooting + +### Common Issues + +1. **Permission Errors** + ```bash + # Fix NPM permissions + sudo chown -R $(whoami) ~/.npm + npm config set prefix ~/.npm-global + ``` + +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 + ``` + +### Support and Maintenance + +1. **Internal Documentation**: Maintain organization-specific documentation +2. **Support Channels**: Set up internal support channels for StackCode issues +3. **Regular Updates**: Schedule regular updates from the upstream repository + +## 📋 Deployment Checklist + +- [ ] Repository forked and customized +- [ ] Custom templates created and tested +- [ ] Configuration files distributed to teams +- [ ] Private registry configured (if applicable) +- [ ] Security review completed +- [ ] Team training conducted +- [ ] Monitoring and logging set up +- [ ] Update process documented +- [ ] Support process established + +## 🤝 Contributing Back + +Consider contributing improvements back to the main StackCode project: + +1. **Generic Features**: Submit features that benefit all users +2. **Bug Fixes**: Report and fix bugs found during self-hosting +3. **Documentation**: Improve documentation based on your experience + +## 📞 Support + +For self-hosting support: + +- **Community**: [GitHub Discussions](https://github.com/YagoBorba/StackCode/discussions) +- **Issues**: [GitHub Issues](https://github.com/YagoBorba/StackCode/issues) +- **Documentation**: [Main Documentation](../README.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 182b3b8..0074d9c 100644 --- a/docs/STACKS.md +++ b/docs/STACKS.md @@ -1,103 +1,159 @@ # Supported Technology Stacks -StackCode supports multiple technology stacks, each designed with best practices and optimal project structures. This document provides an overview of all supported stacks and their features. +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. -## 📋 Available Stacks +## 📋 Currently Available Stacks ### Frontend Stacks #### React + TypeScript +**Template Location:** `packages/core/src/templates/react/` - **Framework**: React 18 with TypeScript - **Build Tool**: Vite -- **Styling**: TailwindCSS -- **Routing**: React Router DOM +- **Styling**: TailwindCSS + PostCSS - **Testing**: Vitest - **Features**: Modern JSX Transform, ESLint configuration, component structure **Generated Structure:** - ``` ├── src/ │ ├── components/ -│ │ ├── common/ # Reusable components -│ │ └── pages/ # Page components -│ ├── styles/ +│ ├── App.tsx │ └── main.tsx ├── index.html ├── package.json ├── tsconfig.json +├── tsconfig.node.json ├── vite.config.ts -└── tailwind.config.js +├── tailwind.config.js +└── postcss.config.js ``` #### Vue.js + TypeScript +**Template Location:** `packages/core/src/templates/vue/` - **Framework**: Vue 3 with Composition API and TypeScript - **Build Tool**: Vite -- **Styling**: TailwindCSS -- **Routing**: Vue Router +- **Styling**: TailwindCSS + PostCSS - **Testing**: Vitest - **Features**: SFC (Single File Components), modern Vue patterns **Generated Structure:** - ``` ├── src/ -│ ├── components/ # Reusable components -│ ├── views/ # Page views -│ ├── styles/ +│ ├── components/ +│ ├── App.vue │ └── main.ts ├── index.html ├── package.json ├── tsconfig.json +├── tsconfig.node.json ├── vite.config.ts -└── tailwind.config.js +├── tailwind.config.js +└── postcss.config.js ``` ### Backend Stacks #### Node.js + JavaScript +**Template Location:** `packages/core/src/templates/node-js/` - **Runtime**: Node.js with ES6+ - **Testing**: Jest -- **Features**: Express.js structure, middleware, controllers, routes +- **Linting**: ESLint +- **Features**: Express.js structure, environment variables, testing setup **Generated Structure:** - ``` ├── src/ -│ ├── controllers/ # Request handlers -│ ├── middleware/ # Custom middleware -│ ├── routes/ # Route definitions -│ ├── utils/ # Utility functions +│ ├── controllers/ +│ ├── middleware/ +│ ├── routes/ +│ ├── utils/ │ └── index.js ├── test/ ├── package.json -└── jest.config.js +├── jest.config.js +├── .eslintrc.cjs +├── .env.example +└── README.md ``` #### Node.js + TypeScript +**Template Location:** `packages/core/src/templates/node-ts/` - **Runtime**: Node.js with TypeScript - **Testing**: Vitest - **Features**: Type-safe development, modern TypeScript configuration **Generated Structure:** - ``` ├── src/ -│ ├── controllers/ # Type-safe controllers -│ ├── utils/ # Utility functions +│ ├── controllers/ +│ ├── utils/ │ └── index.ts ├── tests/ ├── package.json -└── tsconfig.json +├── tsconfig.json +└── .gitignore ``` -#### Python + FastAPI +#### Python + Modern Setup +**Template Location:** `packages/core/src/templates/python/` -- **Framework**: FastAPI +- **Package Management**: pip with pyproject.toml +- **Features**: Modern Python project structure, dependency management + +**Generated Structure:** +``` +├── src/ +│ └── main.py +└── pyproject.toml +``` + +#### Java + Maven +**Template Location:** `packages/core/src/templates/java/` + +- **Build Tool**: Maven +- **Features**: Standard Java project structure, Maven configuration + +**Generated Structure:** +``` +├── src/ +│ └── main/ +│ └── java/ +└── pom.xml +``` + +#### 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 +- **Package Management**: Composer +- **Features**: MVC structure, environment variables + +**Generated Structure:** +``` +├── app/ +├── bootstrap/ +├── resources/ +├── routes/ +├── composer.json +└── .env.example +``` - **Package Management**: pip with pyproject.toml - **Features**: Modern Python async API development @@ -154,40 +210,88 @@ StackCode supports multiple technology stacks, each designed with best practices └── composer.json ``` +## � Additional .gitignore Support + +Beyond the main project templates, StackCode provides comprehensive `.gitignore` support for: + +**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__ +- **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 ### Automatic Configuration -Each stack includes: +Each stack template includes: -- ✅ **Optimized package.json** (or equivalent) with relevant dependencies -- ✅ **TypeScript configuration** (where applicable) -- ✅ **Build tool setup** (Vite, Maven, etc.) -- ✅ **Linting and formatting** configured -- ✅ **Testing framework** integrated -- ✅ **Best practice folder structure** +- ✅ **Package configuration** (`package.json`, `pyproject.toml`, `pom.xml`, `composer.json`, `go.mod`) +- ✅ **TypeScript configuration** (where applicable - React, Vue, Node-TS) +- ✅ **Build tool setup** (Vite for frontend, Maven for Java) +- ✅ **Linting and formatting** (ESLint for Node.js projects) +- ✅ **Testing framework** (Jest for Node.js, Vitest for TypeScript projects) +- ✅ **Environment variables** (`.env.example` for Node.js and PHP) +- ✅ **Best practice folder structure** with organized source directories ### Smart Package Management -StackCode automatically uses the appropriate package manager: +StackCode automatically uses the appropriate package manager based on the project type: -- **npm** for Node.js-based stacks (React, Vue, Node.js) -- **pip** for Python projects +- **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 -### Docker Support +### 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) + +### Template System Features + +- **Variable replacement**: Templates use `{{projectName}}`, `{{description}}`, `{{authorName}}` +- **Modular composition**: Combines base templates with additional features +- **Consistent structure**: All templates follow established patterns for their respective ecosystems + +### Optional Features + +When initializing projects, you can enable additional features: -All stacks can include Docker configuration when the Docker feature is selected during project initialization. +- **Docker Support**: Adds Dockerfile and docker-compose configurations +- **Husky Integration**: Sets up Git hooks for commit validation +- **Conventional Commits**: Enforces commit message standards ### Git Integration Every generated project includes: -- ✅ **Stack-specific .gitignore** files +- ✅ **Intelligent .gitignore** files (stack + tools + IDE specific) - ✅ **Git repository initialization** -- ✅ **Conventional commit setup** (with Husky) +- ✅ **Conventional commit setup** (when Husky feature is selected) ## 🚀 Usage diff --git a/docs/adr/001-monorepo-structure.md b/docs/adr/001-monorepo-structure.md new file mode 100644 index 0000000..8f2163a --- /dev/null +++ b/docs/adr/001-monorepo-structure.md @@ -0,0 +1,58 @@ +# 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 +- Facilitates coordinated releases +- 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 +- Unified versioning strategy + +## 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 +- **Coordinated Releases**: All packages can be versioned and released together +- **Reduced Duplication**: Common utilities and types are centralized +- **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 +- Establish clear guidelines for cross-package dependencies diff --git a/docs/adr/002-typescript-esm.md b/docs/adr/002-typescript-esm.md new file mode 100644 index 0000000..b2dd031 --- /dev/null +++ b/docs/adr/002-typescript-esm.md @@ -0,0 +1,86 @@ +# 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 +- Maintain high code quality and developer experience +- 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 +- Copy non-TypeScript assets (templates, locales) during build + +## 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 +- **Tree Shaking**: ESM enables better dead code elimination +- **Future Compatibility**: ESM is the standard going forward +- **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 +- **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 +- Update CI/CD pipeline to include TypeScript compilation step + +## 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 new file mode 100644 index 0000000..113fc5b --- /dev/null +++ b/docs/adr/003-cli-design.md @@ -0,0 +1,142 @@ +# 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 +- Support internationalization +- Provide consistent help and error messages +- 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 +- Debug mode for troubleshooting + +## 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 +- **User Guidance**: Interactive prompts guide users through complex workflows +- **Validation**: Built-in argument validation and type checking +- **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 +├── generate # File generation +├── commit # Conventional commits +├── git # Git workflow management +│ ├── start # Start feature branch +│ └── finish # Finish feature branch +├── release # Version management +├── validate # Commit validation +├── config # Configuration management +└── github # GitHub integration +``` + +### 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', + builder: (yargs) => { + 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 +- Environment variable support for CI/CD scenarios + +## 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 +4. Keep help text concise but comprehensive diff --git a/docs/adr/004-i18n-strategy.md b/docs/adr/004-i18n-strategy.md new file mode 100644 index 0000000..8437b37 --- /dev/null +++ b/docs/adr/004-i18n-strategy.md @@ -0,0 +1,179 @@ +# 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 +- Be extensible for additional languages +- Maintain performance with locale loading +- Support dynamic language switching + +We needed to decide: +- i18n library and approach +- Locale file organization +- Language detection strategy +- Fallback mechanisms +- 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 +- Automatic fallback to English +- 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 +- **Performance**: Lazy loading of locale files +- **Type Safety**: TypeScript interfaces for locale keys +- **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 + +### Technical Implementation + +#### Locale File Structure +```json +{ + "commands": { + "init": { + "description": "Initialize a new project", + "prompts": { + "projectName": "What is your project name?", + "techStack": "Select a technology stack:" + } + }, + "commit": { + "description": "Create a conventional commit", + "validation": { + "invalidType": "Invalid commit type: {type}" + } + } + }, + "errors": { + "fileNotFound": "File not found: {filename}", + "networkError": "Network error occurred" + } +} +``` + +#### API Design +```typescript +// Basic translation +t('commands.init.description') + +// With interpolation +t('errors.fileNotFound', { filename: 'package.json' }) + +// Pluralization +t('files.count', { count: 5 }) +``` + +### Language Detection Priority +1. `STACKCODE_LANG` environment variable +2. User configuration file +3. System locale (`process.env.LANG`) +4. Fallback to English + +### 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/ +│ ├── index.ts # Main i18n API +│ └── locales/ +│ ├── en.json # English (primary) +│ └── pt.json # Portuguese +``` + +### Future Expansion Strategy +- Additional languages in `locales/` directory +- Community contributions for translations +- Possible locale validation tools +- Right-to-left (RTL) language support consideration + +## 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 +- Regular updates when English text changes diff --git a/docs/adr/README.md b/docs/adr/README.md index 537e083..7b6f244 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -18,10 +18,20 @@ Each ADR follows this structure: ## Index -- [ADR-001: Monorepo Structure](./001-monorepo-structure.md) -- [ADR-002: TypeScript and ES Modules](./002-typescript-esm.md) -- [ADR-003: Command Line Interface Design](./003-cli-design.md) -- [ADR-004: Internationalization Strategy](./004-i18n-strategy.md) +Currently documented architectural decisions: + +- **[ADR-001: Monorepo Structure](./001-monorepo-structure.md)** - Decision to organize the project as a monorepo with npm workspaces +- **[ADR-002: TypeScript and ES Modules](./002-typescript-esm.md)** - Choice of TypeScript with ESM as the primary development stack +- **[ADR-003: Command Line Interface Design](./003-cli-design.md)** - CLI framework selection and command architecture +- **[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 +- Release Management Process +- Testing Strategy ## Template diff --git a/docs/es/ARCHITECTURE.md b/docs/es/ARCHITECTURE.md new file mode 100644 index 0000000..d5cfac8 --- /dev/null +++ b/docs/es/ARCHITECTURE.md @@ -0,0 +1,30 @@ +# Arquitectura de StackCode + +*Esta es una traducción del documento original en inglés. Para la versión más actualizada, consulte [docs/ARCHITECTURE.md](../ARCHITECTURE.md).* + +--- + +## 🚧 Traducción en Progreso + +Este documento está siendo traducido al español. + +### Estado de la Traducción: ⏳ Planeado + +Para contribuir con la traducción de este documento: + +1. **Fork** el repositorio +2. **Traduzca** el contenido manteniendo el formato original +3. **Mantenga** los enlaces a los archivos originales en inglés cuando sea apropiado +4. **Abra un Pull Request** con sus traducciones + +### Contenido Original + +El documento original completo está disponible en: [**📐 Guía de Arquitectura (English)**](../ARCHITECTURE.md) + +## 🤝 Cómo Contribuir + +Vea la [guía de contribución](../CONTRIBUTING.md#internationalization) para más detalles sobre cómo ayudar con las traducciones. + +--- + +*Para la documentación en inglés, visite [docs/](../)* diff --git a/docs/es/CONTRIBUTING.md b/docs/es/CONTRIBUTING.md new file mode 100644 index 0000000..bc69d56 --- /dev/null +++ b/docs/es/CONTRIBUTING.md @@ -0,0 +1,30 @@ +# Guía de Contribución + +*Esta es una traducción del documento original en inglés. Para la versión más actualizada, consulte [docs/CONTRIBUTING.md](../CONTRIBUTING.md).* + +--- + +## 🚧 Traducción en Progreso + +Este documento está siendo traducido al español. + +### Estado de la Traducción: ⏳ Planeado + +Para contribuir con la traducción de este documento: + +1. **Fork** el repositorio +2. **Traduzca** el contenido manteniendo el formato original +3. **Mantenga** los enlaces a los archivos originales en inglés cuando sea apropiado +4. **Abra un Pull Request** con sus traducciones + +### Contenido Original + +El documento original completo está disponible en: [**🤝 Guía de Contribución (English)**](../CONTRIBUTING.md) + +## 🤝 Cómo Contribuir + +Vea la [guía de contribución](../CONTRIBUTING.md#internationalization) para más detalles sobre cómo ayudar con las traducciones. + +--- + +*Para la documentación en inglés, visite [docs/](../)* diff --git a/docs/es/README.md b/docs/es/README.md new file mode 100644 index 0000000..54fa0be --- /dev/null +++ b/docs/es/README.md @@ -0,0 +1,55 @@ +# StackCode - Documentación en Español + +Esta carpeta contiene la documentación de StackCode traducida al español. + +## 📚 Documentos Disponibles + +- **[📐 Guía de Arquitectura](ARCHITECTURE.md)** *(Próximamente)* - Vista completa de la estructura del proyecto +- **[🤝 Guía de Contribución](CONTRIBUTING.md)** *(Próximamente)* - Cómo contribuir al proyecto +- **[🛠️ Stacks Soportados](STACKS.md)** *(Próximamente)* - Lista de tecnologías y plantillas +- **[🚀 Guía de Auto-hospedaje](SELF_HOSTING_GUIDE.md)** *(Próximamente)* - Despliegue personalizado +- **[🏛️ ADRs](adr/)** *(Próximamente)* - Registros de decisiones arquitecturales + +## 🌐 Estado de la Traducción + +| Documento | Estado | Última Actualización | +|-----------|--------|---------------------| +| README.md | ⏳ Planeado | - | +| ARCHITECTURE.md | ⏳ Planeado | - | +| CONTRIBUTING.md | ⏳ Planeado | - | +| STACKS.md | ⏳ Planeado | - | +| SELF_HOSTING_GUIDE.md | ⏳ Planeado | - | +| adr/README.md | ⏳ Planeado | - | +| adr/001-monorepo-structure.md | ⏳ Planeado | - | +| adr/002-typescript-esm.md | ⏳ Planeado | - | +| adr/003-cli-design.md | ⏳ Planeado | - | +| adr/004-i18n-strategy.md | ⏳ Planeado | - | + +## 🤝 Cómo Contribuir con Traducciones + +¿Quieres ayudar a traducir la documentación? Consulta nuestra [guía de contribución](../CONTRIBUTING.md#internationalization). + +### Proceso de Traducción + +1. **Elige un documento** de la lista anterior +2. **Crea un issue** informando que vas a traducir +3. **Traduce el documento** manteniendo el formato +4. **Abre un Pull Request** con la traducción +5. **Espera la revisión** de otros hablantes nativos + +### Directrices de Traducción + +- **Mantén el formato** original (enlaces, código, etc.) +- **Usa lenguaje claro** y accesible +- **Sé consistente** con la terminología técnica +- **Adapta ejemplos** cuando sea necesario para el contexto hispano + +## 📞 Contacto + +Para dudas sobre traducciones: +- Abre un [issue en GitHub](https://github.com/YagoBorba/StackCode/issues) +- Usa las etiquetas `translation` y `documentation` + +--- + +*Para la documentación en inglés, visita [docs/](../)* diff --git a/docs/es/SELF_HOSTING_GUIDE.md b/docs/es/SELF_HOSTING_GUIDE.md new file mode 100644 index 0000000..4ba31b1 --- /dev/null +++ b/docs/es/SELF_HOSTING_GUIDE.md @@ -0,0 +1,30 @@ +# Guía de Auto-hospedaje + +*Esta es una traducción del documento original en inglés. Para la versión más actualizada, consulte [docs/SELF_HOSTING_GUIDE.md](../SELF_HOSTING_GUIDE.md).* + +--- + +## 🚧 Traducción en Progreso + +Este documento está siendo traducido al español. + +### Estado de la Traducción: ⏳ Planeado + +Para contribuir con la traducción de este documento: + +1. **Fork** el repositorio +2. **Traduzca** el contenido manteniendo el formato original +3. **Mantenga** los enlaces a los archivos originales en inglés cuando sea apropiado +4. **Abra un Pull Request** con sus traducciones + +### Contenido Original + +El documento original completo está disponible en: [**🚀 Guía de Auto-hospedaje (English)**](../SELF_HOSTING_GUIDE.md) + +## 🤝 Cómo Contribuir + +Vea la [guía de contribución](../CONTRIBUTING.md#internationalization) para más detalles sobre cómo ayudar con las traducciones. + +--- + +*Para la documentación en inglés, visite [docs/](../)* diff --git a/docs/es/STACKS.md b/docs/es/STACKS.md new file mode 100644 index 0000000..889ef56 --- /dev/null +++ b/docs/es/STACKS.md @@ -0,0 +1,30 @@ +# Stacks de Tecnología Soportados + +*Esta es una traducción del documento original en inglés. Para la versión más actualizada, consulte [docs/STACKS.md](../STACKS.md).* + +--- + +## 🚧 Traducción en Progreso + +Este documento está siendo traducido al español. + +### Estado de la Traducción: ⏳ Planeado + +Para contribuir con la traducción de este documento: + +1. **Fork** el repositorio +2. **Traduzca** el contenido manteniendo el formato original +3. **Mantenga** los enlaces a los archivos originales en inglés cuando sea apropiado +4. **Abra un Pull Request** con sus traducciones + +### Contenido Original + +El documento original completo está disponible en: [**🛠️ Stacks Soportados (English)**](../STACKS.md) + +## 🤝 Cómo Contribuir + +Vea la [guía de contribución](../CONTRIBUTING.md#internationalization) para más detalles sobre cómo ayudar con las traducciones. + +--- + +*Para la documentación en inglés, visite [docs/](../)* diff --git a/docs/es/adr/001-monorepo-structure.md b/docs/es/adr/001-monorepo-structure.md new file mode 100644 index 0000000..7698cc2 --- /dev/null +++ b/docs/es/adr/001-monorepo-structure.md @@ -0,0 +1,30 @@ +# ADR-001: Estructura Monorepo + +*Esta es una traducción del documento original en inglés. Para la versión más actualizada, consulte [docs/adr/001-monorepo-structure.md](../../adr/001-monorepo-structure.md).* + +--- + +## 🚧 Traducción en Progreso + +Este documento está siendo traducido al español. + +### Estado de la Traducción: ⏳ Planeado + +Para contribuir con la traducción de este documento: + +1. **Fork** el repositorio +2. **Traduzca** el contenido manteniendo el formato original +3. **Mantenga** los enlaces a los archivos originales en inglés cuando sea apropiado +4. **Abra un Pull Request** con sus traducciones + +### Contenido Original + +El documento original completo está disponible en: [**ADR-001: Monorepo Structure (English)**](../../adr/001-monorepo-structure.md) + +## 🤝 Cómo Contribuir + +Vea la [guía de contribución](../../CONTRIBUTING.md#internationalization) para más detalles sobre cómo ayudar con las traducciones. + +--- + +*Para la documentación en inglés, visite [docs/adr/](../../adr/)* diff --git a/docs/es/adr/002-typescript-esm.md b/docs/es/adr/002-typescript-esm.md new file mode 100644 index 0000000..6237ca0 --- /dev/null +++ b/docs/es/adr/002-typescript-esm.md @@ -0,0 +1,30 @@ +# ADR-002: TypeScript y ES Modules + +*Esta es una traducción del documento original en inglés. Para la versión más actualizada, consulte [docs/adr/002-typescript-esm.md](../../adr/002-typescript-esm.md).* + +--- + +## 🚧 Traducción en Progreso + +Este documento está siendo traducido al español. + +### Estado de la Traducción: ⏳ Planeado + +Para contribuir con la traducción de este documento: + +1. **Fork** el repositorio +2. **Traduzca** el contenido manteniendo el formato original +3. **Mantenga** los enlaces a los archivos originales en inglés cuando sea apropiado +4. **Abra un Pull Request** con sus traducciones + +### Contenido Original + +El documento original completo está disponible en: [**ADR-002: TypeScript and ES Modules (English)**](../../adr/002-typescript-esm.md) + +## 🤝 Cómo Contribuir + +Vea la [guía de contribución](../../CONTRIBUTING.md#internationalization) para más detalles sobre cómo ayudar con las traducciones. + +--- + +*Para la documentación en inglés, visite [docs/adr/](../../adr/)* diff --git a/docs/es/adr/003-cli-design.md b/docs/es/adr/003-cli-design.md new file mode 100644 index 0000000..581c3f1 --- /dev/null +++ b/docs/es/adr/003-cli-design.md @@ -0,0 +1,30 @@ +# ADR-003: Diseño de Interfaz de Línea de Comandos + +*Esta es una traducción del documento original en inglés. Para la versión más actualizada, consulte [docs/adr/003-cli-design.md](../../adr/003-cli-design.md).* + +--- + +## 🚧 Traducción en Progreso + +Este documento está siendo traducido al español. + +### Estado de la Traducción: ⏳ Planeado + +Para contribuir con la traducción de este documento: + +1. **Fork** el repositorio +2. **Traduzca** el contenido manteniendo el formato original +3. **Mantenga** los enlaces a los archivos originales en inglés cuando sea apropiado +4. **Abra un Pull Request** con sus traducciones + +### Contenido Original + +El documento original completo está disponible en: [**ADR-003: Command Line Interface Design (English)**](../../adr/003-cli-design.md) + +## 🤝 Cómo Contribuir + +Vea la [guía de contribución](../../CONTRIBUTING.md#internationalization) para más detalles sobre cómo ayudar con las traducciones. + +--- + +*Para la documentación en inglés, visite [docs/adr/](../../adr/)* diff --git a/docs/es/adr/004-i18n-strategy.md b/docs/es/adr/004-i18n-strategy.md new file mode 100644 index 0000000..21c0607 --- /dev/null +++ b/docs/es/adr/004-i18n-strategy.md @@ -0,0 +1,30 @@ +# ADR-004: Estrategia de Internacionalización + +*Esta es una traducción del documento original en inglés. Para la versión más actualizada, consulte [docs/adr/004-i18n-strategy.md](../../adr/004-i18n-strategy.md).* + +--- + +## 🚧 Traducción en Progreso + +Este documento está siendo traducido al español. + +### Estado de la Traducción: ⏳ Planeado + +Para contribuir con la traducción de este documento: + +1. **Fork** el repositorio +2. **Traduzca** el contenido manteniendo el formato original +3. **Mantenga** los enlaces a los archivos originales en inglés cuando sea apropiado +4. **Abra un Pull Request** con sus traducciones + +### Contenido Original + +El documento original completo está disponible en: [**ADR-004: Internationalization Strategy (English)**](../../adr/004-i18n-strategy.md) + +## 🤝 Cómo Contribuir + +Vea la [guía de contribución](../../CONTRIBUTING.md#internationalization) para más detalles sobre cómo ayudar con las traducciones. + +--- + +*Para la documentación en inglés, visite [docs/adr/](../../adr/)* diff --git a/docs/es/adr/README.md b/docs/es/adr/README.md new file mode 100644 index 0000000..bafd09b --- /dev/null +++ b/docs/es/adr/README.md @@ -0,0 +1,75 @@ +# 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 carpeta contiene los Registros de Decisiones Arquitecturales (ADRs) que documentan las importantes decisiones arquitecturales tomadas durante el desarrollo de StackCode. + +## ¿Qué es un ADR? + +Un Registro de Decisión Arquitectural (ADR) es un documento que captura una decisión arquitectural importante tomada junto con su contexto y consecuencias. + +## Formato + +Cada ADR sigue esta estructura: + +- **Título**: ¿Cuál es la decisión arquitectural? +- **Estado**: ¿Cuál es el estado? (Propuesto, Aceptado, Deprecado, Reemplazado) +- **Contexto**: ¿Cuál es el problema que estamos viendo que está motivando esta decisión o cambio? +- **Decisión**: ¿Cuál es el cambio que estamos proponiendo o hemos acordado implementar? +- **Consecuencias**: ¿Qué se vuelve más fácil o más difícil de hacer y qué riesgos introduce este cambio? + +## Índice + +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 + +### 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 +- Proceso de Gestión de Releases +- Estrategia de Pruebas + +## Plantilla + +```markdown +# ADR-XXX: [Título] + +## Estado + +[Propuesto | Aceptado | Deprecado | Reemplazado] + +## Contexto + +[Describa el contexto y declaración del problema] + +## Decisión + +[Describa la respuesta a estas fuerzas] + +## Consecuencias + +[Describa el contexto resultante después de aplicar la decisión] +``` + +## 🤝 Cómo Contribuir + +Para contribuir con las traducciones de los ADRs: + +1. **Elija un ADR** de la lista anterior +2. **Traduzca** manteniendo la estructura y formato +3. **Mantenga** los enlaces técnicos y referencias +4. **Abra un Pull Request** con la traducción + +Vea la [guía de contribución](../../CONTRIBUTING.md#internationalization) para más detalles. + +--- + +*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 new file mode 100644 index 0000000..ba564dd --- /dev/null +++ b/docs/pt-BR/ARCHITECTURE.md @@ -0,0 +1,30 @@ +# Arquitetura do StackCode + +*Esta é uma tradução do documento original em inglês. Para a versão mais atualizada, consulte [docs/ARCHITECTURE.md](../ARCHITECTURE.md).* + +--- + +## 🚧 Tradução em Andamento + +Este documento está sendo traduzido para o português brasileiro. + +### Status da Tradução: ⏳ Planejado + +Para contribuir com a tradução deste documento: + +1. **Fork** o repositório +2. **Traduza** o conteúdo mantendo a formatação original +3. **Mantenha** os links para os arquivos originais em inglês quando apropriado +4. **Abra um Pull Request** com suas traduções + +### Conteúdo Original + +O documento original completo está disponível em: [**📐 Guia de Arquitetura (English)**](../ARCHITECTURE.md) + +## 🤝 Como Contribuir + +Veja o [guia de contribuição](../CONTRIBUTING.md#internationalization) para mais detalhes sobre como ajudar com as traduções. + +--- + +*Para a documentação em inglês, visite [docs/](../)* diff --git a/docs/pt-BR/CONTRIBUTING.md b/docs/pt-BR/CONTRIBUTING.md new file mode 100644 index 0000000..82e4716 --- /dev/null +++ b/docs/pt-BR/CONTRIBUTING.md @@ -0,0 +1,30 @@ +# Guia de Contribuição + +*Esta é uma tradução do documento original em inglês. Para a versão mais atualizada, consulte [docs/CONTRIBUTING.md](../CONTRIBUTING.md).* + +--- + +## 🚧 Tradução em Andamento + +Este documento está sendo traduzido para o português brasileiro. + +### Status da Tradução: ⏳ Planejado + +Para contribuir com a tradução deste documento: + +1. **Fork** o repositório +2. **Traduza** o conteúdo mantendo a formatação original +3. **Mantenha** os links para os arquivos originais em inglês quando apropriado +4. **Abra um Pull Request** com suas traduções + +### Conteúdo Original + +O documento original completo está disponível em: [**🤝 Guia de Contribuição (English)**](../CONTRIBUTING.md) + +## 🤝 Como Contribuir + +Veja o [guia de contribuição](../CONTRIBUTING.md#internationalization) para mais detalhes sobre como ajudar com as traduções. + +--- + +*Para a documentação em inglês, visite [docs/](../)* diff --git a/docs/pt-BR/README.md b/docs/pt-BR/README.md new file mode 100644 index 0000000..c4648a3 --- /dev/null +++ b/docs/pt-BR/README.md @@ -0,0 +1,55 @@ +# StackCode - Documentação em Português + +Esta pasta contém a documentação do StackCode traduzida para o português brasileiro. + +## 📚 Documentos Disponíveis + +- **[📐 Guia de Arquitetura](ARCHITECTURE.md)** *(Em breve)* - Visão completa da estrutura do projeto +- **[🤝 Guia de Contribuição](CONTRIBUTING.md)** *(Em breve)* - Como contribuir para o projeto +- **[🛠️ Stacks Suportados](STACKS.md)** *(Em breve)* - Lista de tecnologias e templates +- **[🚀 Guia de Auto-hospedagem](SELF_HOSTING_GUIDE.md)** *(Em breve)* - Deploy personalizado +- **[🏛️ ADRs](adr/)** *(Em breve)* - Registros de decisões arquiteturais + +## 🌐 Status da Tradução + +| Documento | Status | Último Update | +|-----------|--------|---------------| +| README.md | ⏳ Planejado | - | +| ARCHITECTURE.md | ⏳ Planejado | - | +| CONTRIBUTING.md | ⏳ Planejado | - | +| STACKS.md | ⏳ Planejado | - | +| SELF_HOSTING_GUIDE.md | ⏳ Planejado | - | +| adr/README.md | ⏳ Planejado | - | +| adr/001-monorepo-structure.md | ⏳ Planejado | - | +| adr/002-typescript-esm.md | ⏳ Planejado | - | +| adr/003-cli-design.md | ⏳ Planejado | - | +| adr/004-i18n-strategy.md | ⏳ Planejado | - | + +## 🤝 Como Contribuir com Traduções + +Quer ajudar a traduzir a documentação? Veja nosso [guia de contribuição](../CONTRIBUTING.md#internationalization). + +### Processo de Tradução + +1. **Escolha um documento** da lista acima +2. **Crie um issue** informando que vai traduzir +3. **Traduza o documento** mantendo a formatação +4. **Abra um Pull Request** com a tradução +5. **Aguarde a revisão** de outros falantes nativos + +### Diretrizes de Tradução + +- **Mantenha a formatação** original (links, código, etc.) +- **Use linguagem clara** e acessível +- **Seja consistente** com a terminologia técnica +- **Adapte exemplos** quando necessário para o contexto brasileiro + +## 📞 Contato + +Para dúvidas sobre traduções: +- Abra um [issue no GitHub](https://github.com/YagoBorba/StackCode/issues) +- Use a tag `translation` e `documentation` + +--- + +*Para a documentação em inglês, visite [docs/](../)* diff --git a/docs/pt-BR/SELF_HOSTING_GUIDE.md b/docs/pt-BR/SELF_HOSTING_GUIDE.md new file mode 100644 index 0000000..2ab7e8e --- /dev/null +++ b/docs/pt-BR/SELF_HOSTING_GUIDE.md @@ -0,0 +1,30 @@ +# Guia de Auto-hospedagem + +*Esta é uma tradução do documento original em inglês. Para a versão mais atualizada, consulte [docs/SELF_HOSTING_GUIDE.md](../SELF_HOSTING_GUIDE.md).* + +--- + +## 🚧 Tradução em Andamento + +Este documento está sendo traduzido para o português brasileiro. + +### Status da Tradução: ⏳ Planejado + +Para contribuir com a tradução deste documento: + +1. **Fork** o repositório +2. **Traduza** o conteúdo mantendo a formatação original +3. **Mantenha** os links para os arquivos originais em inglês quando apropriado +4. **Abra um Pull Request** com suas traduções + +### Conteúdo Original + +O documento original completo está disponível em: [**🚀 Guia de Auto-hospedagem (English)**](../SELF_HOSTING_GUIDE.md) + +## 🤝 Como Contribuir + +Veja o [guia de contribuição](../CONTRIBUTING.md#internationalization) para mais detalhes sobre como ajudar com as traduções. + +--- + +*Para a documentação em inglês, visite [docs/](../)* diff --git a/docs/pt-BR/STACKS.md b/docs/pt-BR/STACKS.md new file mode 100644 index 0000000..793a8e2 --- /dev/null +++ b/docs/pt-BR/STACKS.md @@ -0,0 +1,30 @@ +# Stacks de Tecnologia Suportados + +*Esta é uma tradução do documento original em inglês. Para a versão mais atualizada, consulte [docs/STACKS.md](../STACKS.md).* + +--- + +## 🚧 Tradução em Andamento + +Este documento está sendo traduzido para o português brasileiro. + +### Status da Tradução: ⏳ Planejado + +Para contribuir com a tradução deste documento: + +1. **Fork** o repositório +2. **Traduza** o conteúdo mantendo a formatação original +3. **Mantenha** os links para os arquivos originais em inglês quando apropriado +4. **Abra um Pull Request** com suas traduções + +### Conteúdo Original + +O documento original completo está disponível em: [**🛠️ Stacks Suportados (English)**](../STACKS.md) + +## 🤝 Como Contribuir + +Veja o [guia de contribuição](../CONTRIBUTING.md#internationalization) para mais detalhes sobre como ajudar com as traduções. + +--- + +*Para a documentação em inglês, visite [docs/](../)* diff --git a/docs/pt-BR/adr/001-monorepo-structure.md b/docs/pt-BR/adr/001-monorepo-structure.md new file mode 100644 index 0000000..9668998 --- /dev/null +++ b/docs/pt-BR/adr/001-monorepo-structure.md @@ -0,0 +1,30 @@ +# ADR-001: Estrutura Monorepo + +*Esta é uma tradução do documento original em inglês. Para a versão mais atualizada, consulte [docs/adr/001-monorepo-structure.md](../../adr/001-monorepo-structure.md).* + +--- + +## 🚧 Tradução em Andamento + +Este documento está sendo traduzido para o português brasileiro. + +### Status da Tradução: ⏳ Planejado + +Para contribuir com a tradução deste documento: + +1. **Fork** o repositório +2. **Traduza** o conteúdo mantendo a formatação original +3. **Mantenha** os links para os arquivos originais em inglês quando apropriado +4. **Abra um Pull Request** com suas traduções + +### Conteúdo Original + +O documento original completo está disponível em: [**ADR-001: Monorepo Structure (English)**](../../adr/001-monorepo-structure.md) + +## 🤝 Como Contribuir + +Veja o [guia de contribuição](../../CONTRIBUTING.md#internationalization) para mais detalhes sobre como ajudar com as traduções. + +--- + +*Para a documentação em inglês, visite [docs/adr/](../../adr/)* diff --git a/docs/pt-BR/adr/002-typescript-esm.md b/docs/pt-BR/adr/002-typescript-esm.md new file mode 100644 index 0000000..4ba09af --- /dev/null +++ b/docs/pt-BR/adr/002-typescript-esm.md @@ -0,0 +1,30 @@ +# ADR-002: TypeScript e ES Modules + +*Esta é uma tradução do documento original em inglês. Para a versão mais atualizada, consulte [docs/adr/002-typescript-esm.md](../../adr/002-typescript-esm.md).* + +--- + +## 🚧 Tradução em Andamento + +Este documento está sendo traduzido para o português brasileiro. + +### Status da Tradução: ⏳ Planejado + +Para contribuir com a tradução deste documento: + +1. **Fork** o repositório +2. **Traduza** o conteúdo mantendo a formatação original +3. **Mantenha** os links para os arquivos originais em inglês quando apropriado +4. **Abra um Pull Request** com suas traduções + +### Conteúdo Original + +O documento original completo está disponível em: [**ADR-002: TypeScript and ES Modules (English)**](../../adr/002-typescript-esm.md) + +## 🤝 Como Contribuir + +Veja o [guia de contribuição](../../CONTRIBUTING.md#internationalization) para mais detalhes sobre como ajudar com as traduções. + +--- + +*Para a documentação em inglês, visite [docs/adr/](../../adr/)* diff --git a/docs/pt-BR/adr/003-cli-design.md b/docs/pt-BR/adr/003-cli-design.md new file mode 100644 index 0000000..7247e18 --- /dev/null +++ b/docs/pt-BR/adr/003-cli-design.md @@ -0,0 +1,30 @@ +# ADR-003: Design da Interface de Linha de Comando + +*Esta é uma tradução do documento original em inglês. Para a versão mais atualizada, consulte [docs/adr/003-cli-design.md](../../adr/003-cli-design.md).* + +--- + +## 🚧 Tradução em Andamento + +Este documento está sendo traduzido para o português brasileiro. + +### Status da Tradução: ⏳ Planejado + +Para contribuir com a tradução deste documento: + +1. **Fork** o repositório +2. **Traduza** o conteúdo mantendo a formatação original +3. **Mantenha** os links para os arquivos originais em inglês quando apropriado +4. **Abra um Pull Request** com suas traduções + +### Conteúdo Original + +O documento original completo está disponível em: [**ADR-003: Command Line Interface Design (English)**](../../adr/003-cli-design.md) + +## 🤝 Como Contribuir + +Veja o [guia de contribuição](../../CONTRIBUTING.md#internationalization) para mais detalhes sobre como ajudar com as traduções. + +--- + +*Para a documentação em inglês, visite [docs/adr/](../../adr/)* diff --git a/docs/pt-BR/adr/004-i18n-strategy.md b/docs/pt-BR/adr/004-i18n-strategy.md new file mode 100644 index 0000000..b786c22 --- /dev/null +++ b/docs/pt-BR/adr/004-i18n-strategy.md @@ -0,0 +1,30 @@ +# ADR-004: Estratégia de Internacionalização + +*Esta é uma tradução do documento original em inglês. Para a versão mais atualizada, consulte [docs/adr/004-i18n-strategy.md](../../adr/004-i18n-strategy.md).* + +--- + +## 🚧 Tradução em Andamento + +Este documento está sendo traduzido para o português brasileiro. + +### Status da Tradução: ⏳ Planejado + +Para contribuir com a tradução deste documento: + +1. **Fork** o repositório +2. **Traduza** o conteúdo mantendo a formatação original +3. **Mantenha** os links para os arquivos originais em inglês quando apropriado +4. **Abra um Pull Request** com suas traduções + +### Conteúdo Original + +O documento original completo está disponível em: [**ADR-004: Internationalization Strategy (English)**](../../adr/004-i18n-strategy.md) + +## 🤝 Como Contribuir + +Veja o [guia de contribuição](../../CONTRIBUTING.md#internationalization) para mais detalhes sobre como ajudar com as traduções. + +--- + +*Para a documentação em inglês, visite [docs/adr/](../../adr/)* diff --git a/docs/pt-BR/adr/README.md b/docs/pt-BR/adr/README.md new file mode 100644 index 0000000..8cf065b --- /dev/null +++ b/docs/pt-BR/adr/README.md @@ -0,0 +1,75 @@ +# 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 pasta contém os Registros de Decisões Arquiteturais (ADRs) que documentam as importantes decisões arquiteturais tomadas durante o desenvolvimento do StackCode. + +## O que é um ADR? + +Um Registro de Decisão Arquitetural (ADR) é um documento que captura uma decisão arquitetural importante feita junto com seu contexto e consequências. + +## Formato + +Cada ADR segue esta estrutura: + +- **Título**: Qual é a decisão arquitetural? +- **Status**: Qual é o status? (Proposto, Aceito, Depreciado, Substituído) +- **Contexto**: Qual é o problema que estamos vendo que está motivando essa decisão ou mudança? +- **Decisão**: Qual é a mudança que estamos propondo ou concordamos em implementar? +- **Consequências**: O que fica mais fácil ou mais difícil de fazer e quaisquer riscos introduzidos por essa mudança? + +## Índice + +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 + +### 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 +- Processo de Gerenciamento de Releases +- Estratégia de Testes + +## Template + +```markdown +# ADR-XXX: [Título] + +## Status + +[Proposto | Aceito | Depreciado | Substituído] + +## Contexto + +[Descreva o contexto e declaração do problema] + +## Decisão + +[Descreva a resposta a essas forças] + +## Consequências + +[Descreva o contexto resultante após aplicar a decisão] +``` + +## 🤝 Como Contribuir + +Para contribuir com as traduções dos ADRs: + +1. **Escolha um ADR** da lista acima +2. **Traduza** mantendo a estrutura e formatação +3. **Mantenha** os links técnicos e referências +4. **Abra um Pull Request** com a tradução + +Veja o [guia de contribuição](../../CONTRIBUTING.md#internationalization) para mais detalhes. + +--- + +*Para a documentação em inglês, visite [docs/adr/](../../adr/)*