aios-core 2.1.5 → 2.2.0

package/.aios-core/infrastructure/templates/project-docs/coding-standards-tmpl.md

@@ -0,0 +1,346 @@
+# {{PROJECT_NAME}} Coding Standards
+
+> **Auto-generated by AIOS** on {{GENERATED_DATE}}
+> **Mode:** {{INSTALLATION_MODE}}
+> **Tech Stack:** {{TECH_STACK}}
+
+## Overview
+
+This document defines the coding standards and conventions for **{{PROJECT_NAME}}**.
+
+---
+
+{{#if IS_NODE}}
+## JavaScript/TypeScript Standards
+
+### Language Version
+
+- **ECMAScript:** ES2022+
+- **TypeScript:** {{TYPESCRIPT_VERSION}} (if applicable)
+- **Node.js:** {{NODE_VERSION}}
+
+### Formatting
+
+| Rule | Value |
+|------|-------|
+| Indentation | 2 spaces |
+| Quotes | Single quotes `'` |
+| Semicolons | {{SEMICOLONS}} |
+| Max line length | 100 characters |
+| Trailing commas | ES5 compatible |
+
+### ESLint Configuration
+
+```javascript
+// .eslintrc.js
+module.exports = {
+  env: {
+    node: true,
+    es2022: true,
+    jest: true,
+  },
+  extends: [
+    'eslint:recommended',
+{{#if IS_TYPESCRIPT}}
+    '@typescript-eslint/recommended',
+{{/if}}
+  ],
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+  },
+  rules: {
+    'indent': ['error', 2],
+    'quotes': ['error', 'single'],
+    'semi': ['error', '{{SEMICOLONS_RULE}}'],
+    'no-unused-vars': 'warn',
+    'no-console': 'warn',
+  },
+};
+```
+
+### Prettier Configuration
+
+```json
+{
+  "semi": {{PRETTIER_SEMI}},
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100
+}
+```
+
+### Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Variables | camelCase | `userName` |
+| Constants | SCREAMING_SNAKE | `MAX_RETRIES` |
+| Functions | camelCase | `getUserById()` |
+| Classes | PascalCase | `UserService` |
+| Files | kebab-case | `user-service.js` |
+| React Components | PascalCase | `UserProfile.tsx` |
+
+### Function Guidelines
+
+```javascript
+/**
+ * Short description of function purpose
+ *
+ * @param {string} userId - User identifier
+ * @param {Object} options - Configuration options
+ * @returns {Promise<User>} The user object
+ * @throws {NotFoundError} When user doesn't exist
+ */
+async function getUserById(userId, options = {}) {
+  // Implementation
+}
+```
+
+### Import Order
+
+1. Node.js built-in modules
+2. External dependencies (npm packages)
+3. Internal modules (absolute paths)
+4. Relative imports
+5. Type imports (TypeScript)
+
+```javascript
+// 1. Built-in
+const fs = require('fs');
+const path = require('path');
+
+// 2. External
+const express = require('express');
+const lodash = require('lodash');
+
+// 3. Internal
+const { config } = require('@/config');
+const { UserService } = require('@/services/user');
+
+// 4. Relative
+const { helper } = require('./utils');
+```
+{{/if}}
+
+{{#if IS_PYTHON}}
+## Python Standards
+
+### Language Version
+
+- **Python:** {{PYTHON_VERSION}}
+- **Package Manager:** pip / poetry
+
+### Formatting
+
+| Rule | Value |
+|------|-------|
+| Indentation | 4 spaces |
+| Max line length | 88 characters (Black default) |
+| Quotes | Double quotes `"` |
+| Docstring style | Google style |
+
+### Black Configuration
+
+```toml
+# pyproject.toml
+[tool.black]
+line-length = 88
+target-version = ['py{{PYTHON_SHORT_VERSION}}']
+include = '\.pyi?$'
+```
+
+### Flake8 Configuration
+
+```ini
+# .flake8
+[flake8]
+max-line-length = 88
+extend-ignore = E203, W503
+exclude = .git,__pycache__,build,dist
+```
+
+### Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Variables | snake_case | `user_name` |
+| Constants | SCREAMING_SNAKE | `MAX_RETRIES` |
+| Functions | snake_case | `get_user_by_id()` |
+| Classes | PascalCase | `UserService` |
+| Files | snake_case | `user_service.py` |
+| Private | Leading underscore | `_internal_method()` |
+
+### Function Guidelines
+
+```python
+def get_user_by_id(user_id: str, options: dict = None) -> User:
+    """Short description of function purpose.
+
+    Args:
+        user_id: User identifier
+        options: Configuration options
+
+    Returns:
+        The user object
+
+    Raises:
+        NotFoundError: When user doesn't exist
+    """
+    # Implementation
+    pass
+```
+
+### Import Order
+
+1. Standard library imports
+2. Related third-party imports
+3. Local application imports
+
+```python
+# 1. Standard library
+import os
+import sys
+from pathlib import Path
+
+# 2. Third-party
+import requests
+from fastapi import FastAPI
+
+# 3. Local
+from {{PYTHON_PACKAGE_NAME}}.config import settings
+from {{PYTHON_PACKAGE_NAME}}.services.user import UserService
+```
+{{/if}}
+
+{{#if IS_GO}}
+## Go Standards
+
+### Language Version
+
+- **Go:** {{GO_VERSION}}
+
+### Formatting
+
+- Use `gofmt` for all formatting
+- Use `goimports` for import management
+
+### Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Variables | camelCase | `userName` |
+| Constants | PascalCase or camelCase | `MaxRetries` |
+| Functions (exported) | PascalCase | `GetUserByID` |
+| Functions (private) | camelCase | `getUserByID` |
+| Packages | lowercase | `userservice` |
+| Files | snake_case | `user_service.go` |
+
+### Function Guidelines
+
+```go
+// GetUserByID retrieves a user by their unique identifier.
+//
+// It returns the user and any error encountered.
+func GetUserByID(ctx context.Context, userID string) (*User, error) {
+    // Implementation
+}
+```
+
+### Import Order
+
+1. Standard library
+2. Third-party packages
+3. Local packages
+
+```go
+import (
+    // Standard library
+    "context"
+    "fmt"
+
+    // Third-party
+    "github.com/gin-gonic/gin"
+
+    // Local
+    "{{GO_MODULE}}/internal/config"
+    "{{GO_MODULE}}/internal/services"
+)
+```
+{{/if}}
+
+---
+
+## Common Standards (All Languages)
+
+### Error Handling
+
+- Always handle errors explicitly
+- Provide meaningful error messages
+- Include context in error messages
+- Use appropriate error types/codes
+
+### Comments
+
+- Write comments that explain "why", not "what"
+- Keep comments up-to-date with code
+- Use JSDoc/docstrings for public APIs
+- Avoid commented-out code in commits
+
+### Git Commit Messages
+
+Follow conventional commits:
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+Example:
+```
+feat(auth): add OAuth2 login support
+
+- Implement Google OAuth provider
+- Add token refresh mechanism
+- Update user model with OAuth fields
+
+Closes #123
+```
+
+### Code Review Guidelines
+
+1. **Functionality:** Does it work as intended?
+2. **Readability:** Is it easy to understand?
+3. **Maintainability:** Is it easy to modify?
+4. **Performance:** Are there obvious bottlenecks?
+5. **Security:** Are there vulnerabilities?
+6. **Tests:** Is it adequately tested?
+
+---
+
+## Tools & Automation
+
+### Pre-commit Hooks
+
+The project uses pre-commit hooks for:
+- Linting
+- Formatting
+- Type checking (if applicable)
+
+### CI/CD Quality Gates
+
+All PRs must pass:
+{{#each QUALITY_GATES}}
+- [ ] {{this}}
+{{/each}}
+
+---
+
+*Generated by AIOS Documentation Integrity System*
+*Template Version: 1.0.0*

package/.aios-core/infrastructure/templates/project-docs/source-tree-tmpl.md

@@ -0,0 +1,177 @@
+# {{PROJECT_NAME}} Source Tree Standard
+
+> **Auto-generated by AIOS** on {{GENERATED_DATE}}
+> **Mode:** {{INSTALLATION_MODE}}
+> **Tech Stack:** {{TECH_STACK}}
+
+## Overview
+
+This document defines the directory structure and file organization standards for **{{PROJECT_NAME}}**.
+
+## Directory Structure
+
+```
+{{PROJECT_NAME}}/
+├── .aios-core/                    # AIOS configuration
+│   └── core-config.yaml           # Project configuration
+│
+├── .github/                       # GitHub configuration
+│   └── workflows/                 # CI/CD workflows
+│       ├── quality-gates.yml      # Quality checks
+│       └── deploy.yml             # Deployment automation
+│
+├── docs/                          # Documentation
+│   ├── architecture/              # Project architecture docs
+│   │   ├── source-tree.md         # THIS FILE
+│   │   ├── coding-standards.md    # Coding conventions
+│   │   └── tech-stack.md          # Technology decisions
+│   ├── guides/                    # User guides
+│   └── api/                       # API documentation
+│
+{{#if IS_NODE}}
+├── src/                           # Source code
+│   ├── index.{{FILE_EXT}}         # Entry point
+│   ├── config/                    # Configuration modules
+│   ├── services/                  # Business logic
+│   ├── utils/                     # Utility functions
+│   └── types/                     # TypeScript types (if applicable)
+│
+├── tests/                         # Test files
+│   ├── unit/                      # Unit tests
+│   ├── integration/               # Integration tests
+│   └── fixtures/                  # Test fixtures
+│
+├── scripts/                       # Build and utility scripts
+│
+├── package.json                   # Node.js dependencies
+├── tsconfig.json                  # TypeScript config (if applicable)
+{{/if}}
+{{#if IS_PYTHON}}
+├── {{PYTHON_PACKAGE_NAME}}/       # Python package
+│   ├── __init__.py                # Package init
+│   ├── main.py                    # Entry point
+│   ├── config/                    # Configuration
+│   ├── services/                  # Business logic
+│   └── utils/                     # Utilities
+│
+├── tests/                         # Test files
+│   ├── unit/                      # Unit tests
+│   ├── integration/               # Integration tests
+│   └── conftest.py                # Pytest configuration
+│
+├── requirements.txt               # Python dependencies
+├── pyproject.toml                 # Project configuration
+{{/if}}
+{{#if IS_GO}}
+├── cmd/                           # Command entry points
+│   └── {{PROJECT_NAME}}/
+│       └── main.go                # Main entry point
+│
+├── internal/                      # Private packages
+│   ├── config/                    # Configuration
+│   ├── services/                  # Business logic
+│   └── utils/                     # Utilities
+│
+├── pkg/                           # Public packages
+│
+├── go.mod                         # Go modules
+├── go.sum                         # Dependency checksums
+{{/if}}
+│
+├── .gitignore                     # Git ignore rules
+├── .env.example                   # Environment template
+└── README.md                      # Project documentation
+```
+
+## File Placement Rules
+
+### Documentation Files
+
+| File Pattern | Location | Purpose |
+|--------------|----------|---------|
+| `*.md` (project docs) | `docs/` | Project documentation |
+| Architecture docs | `docs/architecture/` | Technical standards |
+| User guides | `docs/guides/` | How-to documentation |
+| API docs | `docs/api/` | API reference |
+
+### Source Code
+
+| File Pattern | Location | Purpose |
+|--------------|----------|---------|
+{{#if IS_NODE}}
+| `*.js`, `*.ts` | `src/` | Application source code |
+| `*.test.js`, `*.test.ts` | `tests/` | Test files |
+| `*.d.ts` | `src/types/` | TypeScript declarations |
+{{/if}}
+{{#if IS_PYTHON}}
+| `*.py` | `{{PYTHON_PACKAGE_NAME}}/` | Application source code |
+| `test_*.py` | `tests/` | Test files |
+{{/if}}
+{{#if IS_GO}}
+| `*.go` | `cmd/`, `internal/`, `pkg/` | Go source files |
+| `*_test.go` | Same as source | Test files |
+{{/if}}
+
+### Configuration Files
+
+| File | Location | Purpose |
+|------|----------|---------|
+| `.aios-core/core-config.yaml` | Root | AIOS configuration |
+| `.env`, `.env.*` | Root | Environment variables |
+| `.gitignore` | Root | Git ignore rules |
+{{#if IS_NODE}}
+| `package.json` | Root | Node.js dependencies |
+| `tsconfig.json` | Root | TypeScript configuration |
+| `.eslintrc.*` | Root | ESLint configuration |
+| `.prettierrc` | Root | Prettier configuration |
+{{/if}}
+{{#if IS_PYTHON}}
+| `pyproject.toml` | Root | Python project config |
+| `requirements.txt` | Root | Python dependencies |
+| `.flake8` | Root | Flake8 configuration |
+{{/if}}
+
+## Anti-Patterns (Files NOT Allowed at Root)
+
+The following files should NOT be placed at the project root:
+
+| Pattern | Correct Location | Reason |
+|---------|------------------|--------|
+| `*.md` (except README) | `docs/` | Documentation belongs in docs |
+{{#if IS_NODE}}
+| `*.js`, `*.ts` (source) | `src/` | Source code belongs in src |
+| `*.test.js` | `tests/` | Tests belong in tests |
+{{/if}}
+{{#if IS_PYTHON}}
+| `*.py` (source) | `{{PYTHON_PACKAGE_NAME}}/` | Source code belongs in package |
+| `test_*.py` | `tests/` | Tests belong in tests |
+{{/if}}
+| Temporary files | N/A | Should not be committed |
+
+## Naming Conventions
+
+### Directories
+
+- Use **kebab-case** for directory names: `my-feature/`
+- Use lowercase: `services/` not `Services/`
+
+### Files
+
+{{#if IS_NODE}}
+- Source files: **kebab-case** - `user-service.js`
+- Test files: **kebab-case** with `.test` suffix - `user-service.test.js`
+- React components: **PascalCase** - `UserProfile.tsx`
+{{/if}}
+{{#if IS_PYTHON}}
+- Source files: **snake_case** - `user_service.py`
+- Test files: **snake_case** with `test_` prefix - `test_user_service.py`
+{{/if}}
+{{#if IS_GO}}
+- Source files: **snake_case** - `user_service.go`
+- Test files: **snake_case** with `_test` suffix - `user_service_test.go`
+{{/if}}
+
+---
+
+*Generated by AIOS Documentation Integrity System*
+*Template Version: 1.0.0*