@maka/maka-cli 5.1.40 → 5.1.42

package/.claude/codebase-overview.md

@@ -0,0 +1,736 @@
+# Maka-CLI Codebase Overview
+
+**Version**: 5.1.40
+**Package**: @maka/maka-cli
+**Purpose**: Command-line scaffolding and DevOps tool for MeteorJS applications
+
+## Quick Start
+
+```bash
+maka create KickTiresApp
+cd KickTiresApp
+maka run
+```
+
+## Architecture Overview
+
+### Entry Points
+
+1. **src/exec.js** - Binary executable entry point
+2. **src/maka.ts** - Main application entry
+   - Parses CLI arguments with `minimist`
+   - Sets Node.js memory limits based on system RAM
+   - Routes to main Maka command handler
+
+### Core Class Hierarchy
+
+```
+Tool (src/tool.ts:60)
+├── Command (src/command.ts:57)
+└── Generator (src/generator.ts:65)
+```
+
+#### Tool Class
+Base class providing shared utilities:
+- `docker` - Docker operations
+- `fsi` - File system interface (FSI)
+- `cfg` - Configuration management
+- `mpi` - Meteor package interface
+- `pkg` - Package management
+- `aws` - AWS SDK integration
+- `scaffold` - Template-based scaffolding
+
+Key methods:
+- `validateMakaProject()` - Check if in Maka project
+- `validateMeteorInstall()` - Check Meteor installation
+- `validateParams()` - Validate arguments and options
+- `match()` - Match command/generator names and aliases
+
+#### Command Class
+Handles CLI commands with:
+- Sub-command support
+- Validation pipeline
+- Help text generation
+- Error handling
+- Usage examples
+
+Key methods:
+- `run()` - Execute command
+- `invoke()` - Internal execution with validation
+- `processAndRunCommand()` - Route to sub-commands
+
+#### Generator Class
+Code generation with:
+- Transaction history (`.maka/history.json`)
+- Undo functionality
+- Template rendering
+- Resource naming
+
+Key methods:
+- `invoke()` - Execute generator with validation
+- `addToHistory()` - Track operations for undo
+- `undo()` - Rollback operations
+- `processAndRunGenerator()` - Route to sub-generators
+
+## Commands (src/commands/)
+
+### Core Commands
+
+| Command | File | Description |
+|---------|------|-------------|
+| `create` | create.ts | Scaffold new Meteor applications |
+| `run` | run/ | Run application with configurations |
+| `build` | build/ | Build application |
+| `generate` | generate.ts | Code generation dispatcher |
+| `install` | install.ts | Install packages/tools |
+| `uninstall` | uninstall.ts | Remove packages/tools |
+| `help` | help.ts | Display help information |
+
+### DevOps Commands
+
+| Command | File | Description |
+|---------|------|-------------|
+| `deploy` | deploy/ | Deployment utilities |
+| `proxy` | proxy.ts | HTTP proxy server |
+| `ssl` | ssl.ts | SSL certificate management |
+| `ssh` | ssh.ts | SSH operations |
+| `docker` | - | Docker operations (via tool) |
+
+### AWS Commands (aws/)
+
+- EC2 instance management
+- ECR registry operations
+- Route 53 DNS management
+- CloudFormation stack deployment
+
+### Development Commands
+
+| Command | File | Description |
+|---------|------|-------------|
+| `debug` | debug.ts | Debug utilities |
+| `lint` | lint.ts | Code linting |
+| `jsdoc` | jsdoc.ts | Generate JSDoc |
+| `logs` | logs.ts | View application logs |
+| `reconfig` | reconfig.ts | Reconfigure project |
+
+### User Commands
+
+| Command | File | Description |
+|---------|------|-------------|
+| `login` | login.ts | User authentication |
+| `logout` | logout.ts | End user session |
+| `register` | register.ts | User registration |
+| `profile` | profile.ts | User profile management |
+
+### Utility Commands
+
+| Command | File | Description |
+|---------|------|-------------|
+| `undo` | undo.ts | Undo last operation |
+| `version` | version/ | Version information |
+| `murder` | murder.ts | Kill processes |
+| `ai` / `mcp` | ai.ts | MCP server for AI assistant integration |
+| `game` | game/ | Interactive game features |
+
+## Generators (src/generators/)
+
+### Core Generators
+
+| Generator | File | Description |
+|-----------|------|-------------|
+| `g:api` | api.ts | REST/GraphQL API endpoints |
+| `g:collection` | collection.ts | MongoDB collections |
+| `g:component` | component.ts | React components |
+| `g:page` | page.ts | Full pages with routing |
+| `g:route` | route.ts | Route definitions |
+| `g:layout` | layout.ts | Layout components |
+| `g:hook` | hook.ts | React hooks |
+| `g:publish` | publish.ts | Meteor publications |
+| `g:methods` | methods.ts | Meteor methods |
+| `g:package` | package.ts | Meteor packages |
+| `g:config` | config.ts | Environment configurations |
+| `g:dbc` | dbc.ts | Database configurations |
+| `g:dockerfile` | dockerfile.ts | Docker configurations |
+
+### AWS Generators (aws/)
+
+- Infrastructure as code templates
+- CloudFormation stacks
+- Service configurations
+
+### Service Generators (services/)
+
+- Microservice scaffolding
+- API service templates
+- Test configurations
+
+## Tools & Utilities (src/tools/)
+
+### File System Interface (fsi/)
+
+**Class**: `FSI` (Singleton)
+**Purpose**: Project-aware file system operations
+
+Key methods:
+- `findProjectDirectory()` - Locate project root
+- `pathFromProject()` - Resolve paths from project root
+- `ensureDir()` - Create directories safely
+- `readFile()` / `writeFile()` - File I/O
+- `exists()` - Check file existence
+- `deepen()` - Deep copy/transform objects
+
+### Configuration (cfg/)
+
+**Class**: `CFG` (Singleton)
+**Purpose**: Manage global and project configurations
+
+Key methods:
+- `getGlobalConfig()` - User-wide settings
+- `getMakaProjectConfig()` - Project settings
+- `getAppProjectConfigs()` - Environment configs
+- `setConfig()` - Update configuration
+- `initializeGlobalConfig()` - First-time setup
+
+Configuration locations:
+- Global: `~/.maka/global-config.json`
+- Project: `.maka/config.json`
+- Environments: `.maka/config-{env}.json`
+
+### Meteor Package Interface (mpi/)
+
+**Class**: `MPI` (Singleton)
+**Purpose**: Interact with Meteor CLI and packages
+
+Key methods:
+- `meteorVersion()` - Get Meteor version
+- `maybeProxyCommandToMeteor()` - Pass-through to Meteor
+- `installPackage()` - Add Meteor package
+- `removePackage()` - Remove Meteor package
+
+### Package Management (pkg/)
+
+**Class**: `PKG` (Singleton)
+**Purpose**: npm/package.json operations
+
+Key methods:
+- `getPackageJson()` - Read package.json
+- `updatePackageJson()` - Modify package.json
+- `installDependencies()` - Run npm install
+- `addDependency()` - Add to dependencies
+- `addDevDependency()` - Add to devDependencies
+
+### AWS Integration (aws/)
+
+**Class**: `AWS` (Singleton)
+**Purpose**: AWS SDK operations
+
+Services:
+- EC2 - Instance management
+- ECR - Container registry
+- Route 53 - DNS management
+- Route 53 Domains - Domain registration
+
+### Docker (docker/)
+
+**Class**: `Docker`
+**Purpose**: Docker container and image operations
+
+Key methods:
+- `build()` - Build Docker images
+- `run()` - Run containers
+- `compose()` - Docker Compose operations
+- `exec()` - Execute in container
+
+### SSH (ssh/)
+
+**Class**: `SSH`
+**Purpose**: SSH connection and operations
+
+Key methods:
+- `connect()` - Establish SSH connection
+- `exec()` - Execute remote commands
+- `uploadFile()` - SCP file upload
+- `downloadFile()` - SCP file download
+
+### SSL (ssl/)
+
+**Class**: `SSL`
+**Purpose**: SSL certificate generation
+
+Key methods:
+- `generateSelfSigned()` - Self-signed certificates
+- `generateCSR()` - Certificate signing request
+- Uses `node-forge` for cryptography
+
+### Scaffolding (scaffold/)
+
+**Class**: `Scaffold` (Singleton)
+**Purpose**: Template-based code generation
+
+Key methods:
+- `template()` - Process EJS template
+- `copy()` - Copy template files
+- `createDir()` - Create directory structure
+- `render()` - Render template with data
+
+Template locations: `src/templates/`
+
+### Actions (actions/)
+
+**Class**: `Actions`
+**Purpose**: User interaction and prompts
+
+Key methods:
+- `ask()` - Text input
+- `confirm()` - Yes/no confirmation
+- `select()` - Selection from list
+- `multiSelect()` - Multiple selections
+- Uses `@inquirer/prompts`
+
+### Logging (log/)
+
+**Class**: `Log`
+**Purpose**: Colored terminal output
+
+Methods:
+- `error()` - Red error messages
+- `warn()` - Yellow warnings
+- `success()` - Green success messages
+- `info()` - Informational messages
+- `notice()` - Important notices
+- `header()` - Section headers
+- `bright()` - Bright text
+- `usage()` - Command usage info
+
+Features:
+- Light/dark mode support
+- Color customization
+- Uses `cli-color`
+
+### Spawn Async (spawn-async/)
+
+**Class**: `SpawnAsync`
+**Purpose**: Asynchronous process execution
+
+Key methods:
+- `spawn()` - Execute command
+- `spawnPromise()` - Promise-based execution
+- Stream handling for stdout/stderr
+- Exit code handling
+
+### Progress (progress/)
+
+**Class**: `Progress`
+**Purpose**: Terminal progress indicators
+
+Features:
+- Spinner animations
+- Progress bars
+- Status messages
+- Uses `elegant-spinner` and `single-line-log2`
+
+### MCP (mcp/)
+
+**Class**: `MCP`
+**Purpose**: Model Context Protocol server for AI assistant integration
+
+Key methods:
+- `start()` - Start MCP server with stdio transport
+- `stop()` - Stop MCP server
+- `registerTool()` - Register custom MCP tools
+- `registerResource()` - Register custom MCP resources
+
+Features:
+- Exposes Maka-CLI functionality to AI assistants (Claude Code, Claude Desktop, etc.)
+- Standard mode: Read-only informational tools
+- Advanced mode: Command execution and file operations
+- Resources: Project config, project info, global config
+- Uses `@modelcontextprotocol/sdk`
+
+Tools (Standard Mode):
+- `maka_list_generators` - List available generators
+- `maka_list_commands` - List available commands
+
+Tools (Advanced Mode):
+- `maka_execute` - Execute any Maka command
+- `maka_run_generator` - Run code generators
+- `maka_read_file` - Read file contents
+- `maka_list_directory` - List directory contents
+
+Resources:
+- `maka://config` - Project configuration
+- `maka://project-info` - Project information
+- `maka://global-config` - Global user configuration
+
+Configuration file: `src/tools/mcp/`
+Documentation: `MCP-README.md`
+
+## Templates (src/templates/)
+
+### Template Structure
+
+```
+src/templates/
+├── meteor/           # Meteor-specific templates
+│   ├── app/         # Application structure
+│   ├── collection/  # MongoDB collections
+│   ├── api/         # API endpoints
+│   ├── publish/     # Publications
+│   ├── method/      # Methods
+│   ├── template/    # UI templates
+│   ├── config/      # Configurations
+│   ├── service/     # Services
+│   ├── dbc/         # Database configs
+│   └── package/     # Package structure
+├── aws/             # AWS templates
+│   └── cloudformation/
+├── service/         # Service templates
+│   ├── docker/     # Dockerfile templates
+│   ├── test/       # Test templates
+│   └── eslint/     # ESLint configs
+└── [framework]/     # Framework-specific
+```
+
+### Template Format
+
+Templates use EJS (Embedded JavaScript):
+- Extension: `.ejs` or `.js.ts`
+- Variables: `<%= varName %>`
+- Logic: `<% if (condition) { %> ... <% } %>`
+- Includes: `<%- include('partial') %>`
+
+## Configuration Files
+
+### Global Config (~/.maka/global-config.json)
+
+```json
+{
+  "pallet": "dark",  // or "light"
+  "userId": "...",
+  "username": "...",
+  "token": "..."
+}
+```
+
+### Project Config (.maka/config.json)
+
+```json
+{
+  "name": "ProjectName",
+  "engines": {
+    "meteor": "2.x",
+    "node": ">=22.17.0"
+  },
+  "template": "react",
+  "features": [],
+  "ui": "material-ui"
+}
+```
+
+### History File (.maka/history.json)
+
+Tracks generator operations for undo:
+```json
+[
+  {
+    "generatorName": "maka:generate:page",
+    "transactionId": "uuid",
+    "details": {
+      "success": true,
+      "params": { "args": [...], "opts": {...} }
+    }
+  }
+]
+```
+
+Max size: 100KB (auto-pruning)
+
+## Command/Generator Options
+
+### IOpts Interface (src/tool.ts:32)
+
+```typescript
+{
+  name: string                      // Command/generator name
+  aliases?: string[]                // Alternative names
+  usage?: string                    // Usage text
+  shortDesc: string                 // Brief description
+  description?: string              // Full description
+  examples?: string[]               // Usage examples
+  requiredOpts?: NamedParam[]       // Required options
+  validOpts: NamedParam[]           // Valid options
+  validArgs?: string[]              // Valid arguments
+  resourceNameRequired?: boolean    // Needs resource name
+  mustBeInMakaProject?: boolean     // Project context required
+  mustHaveMeteorInstalled?: boolean // Meteor required
+  minArgLength?: number             // Min arguments
+  maxArgLength?: number             // Max arguments
+  minOptsLength?: number            // Min options
+  maxOptsLength?: number            // Max options
+  disableAuthCheck?: boolean        // Skip auth
+  isRoot?: boolean                  // Root command
+  checkWhere?: boolean              // Check where flag
+  isPro?: boolean                   // Pro feature
+  mustBeLoggedIn?: boolean          // Login required
+  experimental?: boolean            // Experimental feature
+}
+```
+
+### NamedParam Interface (src/tool.ts:23)
+
+```typescript
+{
+  name: string           // Option name
+  boolFlag?: boolean     // Boolean flag
+  hidden?: boolean       // Hidden from help
+  values?: string[]      // Valid values
+  regex?: RegExp         // Validation pattern
+  description?: string   // Help text
+}
+```
+
+## Error Handling
+
+### Custom Errors (src/error.js)
+
+- `UsageError` - Incorrect usage
+- `UsageErrorWithSubs` - Show sub-commands
+- `MustBeInProjectError` - Not in Maka project
+- `NoMeteorFoundError` - Meteor not installed
+- `NoMeteorAppFoundError` - No Meteor app
+- `MustBeLoggedIn` - Authentication required
+
+### Error Flow
+
+1. Error thrown in command/generator
+2. Caught in `invoke()` method
+3. Usage information displayed
+4. Specific error message shown
+5. Process exits with code 1
+
+## Validation Pipeline
+
+### Command Validation Order
+
+1. Check if help requested → Show usage
+2. Validate project context (if required)
+3. Validate Meteor installation (if required)
+4. Validate authentication (if required)
+5. Check argument length
+6. Check option length
+7. Validate engine requirements
+8. Validate parameters
+9. Execute handler
+
+### Generator Validation Order
+
+1. Check if help requested → Show usage
+2. Validate project context (if required)
+3. Validate Meteor installation (if required)
+4. Check argument/option lengths
+5. Validate engine requirements
+6. Validate parameters
+7. Check resource name (if required)
+8. Check `--where` flag (if required)
+9. Execute handler
+10. Add to history
+
+## Build & Development
+
+### Scripts (package.json:20-31)
+
+- `npm run build` - Clean, compile TypeScript, copy templates
+- `npm run develop` - Watch mode for development
+- `npm run lint` - ESLint with auto-fix
+- `npm run test` - Jest test suite
+- `npm run prep` - Copy templates and resources
+
+### Build Output
+
+- Source: `src/`
+- Output: `bundle/typescript/`
+- Templates copied to: `bundle/typescript/src/templates/`
+
+### TypeScript Configuration (tsconfig.json)
+
+- Target: ES modules
+- Module: ESNext
+- Output: `bundle/typescript/`
+- Source maps enabled
+
+## Key Patterns & Conventions
+
+### 1. Singleton Pattern
+Used for shared utilities:
+- `FSI.getInstance()`
+- `CFG.getInstance(fsi)`
+- `MPI.getInstance(fsi, cfg, pkg)`
+- `AWS.getInstance(fsi, cfg, scaffold)`
+- `Scaffold.getInstance(fsi, mpi)`
+
+### 2. Factory Pattern
+Command/Generator creation:
+```typescript
+Command.create(opts, handler, parent)
+Generator.create(opts, handler, undoHandler, parent)
+```
+
+### 3. Template Method Pattern
+Base `Tool` class provides template methods:
+- `validateMakaProject()`
+- `validateParams()`
+- Subclasses implement specific behavior
+
+### 4. Chain of Responsibility
+Command routing through hierarchy:
+```
+maka → command → sub-command → handler
+maka:generate → generator → sub-generator → handler
+```
+
+### 5. Transaction Pattern
+Generator operations tracked with:
+- Transaction ID (UUID)
+- Operation details
+- Undo handlers
+- History persistence
+
+## Testing
+
+### Test Structure (test/)
+
+- Integration tests
+- Located in `test/integration/`
+- Jest configuration: `jest.config.js`
+- Coverage reports
+
+### Running Tests
+
+```bash
+npm test
+```
+
+## Dependencies Highlights
+
+### Production
+- `@aws-sdk/*` - AWS integrations
+- `@inquirer/prompts` - Interactive CLI
+- `blessed` - Terminal UI framework
+- `cli-color` - ANSI colors
+- `cli-table` - Table formatting
+- `ejs` - Template engine
+- `http-proxy` - Proxy server
+- `node-forge` - Cryptography
+- `minimist` - Argument parsing
+- `semver` - Version handling
+- `tar` - Archive operations
+- `uuid` - Unique IDs
+
+### Development
+- `typescript` - Type system
+- `jest` - Testing framework
+- `eslint` - Linting
+- `concurrently` - Parallel scripts
+- `wait-on` - File watching
+
+## Project Stats
+
+- **Total Lines**: ~4,400 lines of TypeScript
+- **Commands**: 32+
+- **Generators**: 18+
+- **Tools**: 15+
+- **Templates**: 50+
+- **Node Version**: >=22.17.0
+- **License**: MIT
+
+## Common Workflows
+
+### Creating a New Command
+
+1. Create file in `src/commands/`
+2. Import Command class
+3. Define options (IOpts)
+4. Implement handler
+5. Register in `src/commands/_index.ts`
+
+Example:
+```typescript
+import { Command } from '../command.js';
+
+const MyCmd = Command.create({
+  name: 'mycmd',
+  aliases: ['mc'],
+  shortDesc: 'My command',
+  validOpts: ['option1', 'option2'],
+  mustBeInMakaProject: true
+}, async function(args, opts) {
+  // Implementation
+});
+```
+
+### Creating a New Generator
+
+1. Create file in `src/generators/`
+2. Import Generator class
+3. Define options (IOpts)
+4. Implement handler and undo handler
+5. Register in `src/generators/_index.ts`
+
+Example:
+```typescript
+import { Generator } from '../generator.js';
+
+const MyGen = Generator.create({
+  name: 'mytype',
+  aliases: ['mt'],
+  shortDesc: 'Generate my type',
+  validOpts: ['where'],
+  resourceNameRequired: true
+},
+async function(args, opts) {
+  // Generation logic
+  return { success: true };
+},
+async function(details) {
+  // Undo logic
+});
+```
+
+### Adding a Template
+
+1. Create template in `src/templates/`
+2. Use EJS syntax
+3. Reference in generator
+4. Update `prep` script if needed
+
+## Useful File Locations
+
+- Main entry: `src/maka.ts:1`
+- Command base: `src/command.ts:57`
+- Generator base: `src/generator.ts:65`
+- Tool base: `src/tool.ts:60`
+- Commands index: `src/commands/_index.ts`
+- Generators index: `src/generators/_index.ts`
+- Error definitions: `src/error.js`
+- Global types: `src/global.d.ts`
+
+## Development Tips
+
+1. **Hot Reload**: Use `npm run develop` for watch mode
+2. **Testing**: Command is `maka` after build
+3. **Debugging**: Use `maka --debug` flag
+4. **Templates**: Changes require rebuild
+5. **History**: Check `.maka/history.json` for operation tracking
+6. **Undo**: Use `maka undo` to reverse operations
+
+## Known Limitations
+
+- History file capped at 100KB
+- Undo handlers not implemented for all generators
+- Some commands hidden from help (murder, play)
+- Experimental features may be unstable
+
+---
+
+*Last Updated: 2025-10-13*
+*Maka-CLI Version: 5.1.40*