npm - @maka/maka-cli - Versions diffs - 5.3.0 → 5.3.2 - Mend

@maka/maka-cli 5.3.0 → 5.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1283) hide show

package/.claude/codebase-overview.md DELETED Viewed

@@ -1,736 +0,0 @@
-# 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*