npm package: @message-in-the-middle/cli
Description: CLI tool for scaffolding Queue-Centric Design applications with message-in-the-middle
Author: Goran Novosel
Latest version: 0.1.2

# @message-in-the-middle/cli

> ⚠️ **Work in Progress**
> **Is this library production-ready?** No.
> **Is this library safe?** No.
> **When will it be ready?** Soon™ (maybe tomorrow, maybe never).
> **Why is it public?** Experiment

message-in-the-middle is to Express.js what your message queue processing is to HTTP request processing. Just as Express provides a middleware pattern for HTTP requests, this library provides a middleware pattern for processing queue messages.

## Why This Exists

Processing queue messages usually means copy-pasting the same boilerplate: parse JSON, validate, log, retry, deduplicate, route to handlers. This library lets you compose that logic as middlewares.

---

**A powerful code generator and scaffolding tool for Queue-Centric Design applications.**

## Installation

```bash
# Global installation
npm install -g @message-in-the-middle/cli

# Or use with npx (no installation required)
npx @message-in-the-middle/cli --help
```

## Quick Start

```bash
# Create a new project
mitm init my-queue-app --template express-sqs-mysql

# Generate a new queue
cd my-queue-app
mitm generate queue payments --preset critical

# Add a handler
mitm generate handler refund --queue payments

# Validate structure
mitm validate all
```

## Commands

### `mitm init <project-name>`

Create a new message-in-the-middle project with Queue-Centric Design structure.

**Options:**
- `-t, --template <name>` - Project template (default: express-sqs)
- `-pm, --package-manager <pm>` - Package manager: npm, pnpm, yarn (default: pnpm)
- `--skip-install` - Skip dependency installation
- `--git` - Initialize git repository
- `--no-examples` - Don't generate example queues

**Available Templates:**
- `minimal` - Core library only
- `express-sqs` - Express + SQS (no persistence)
- `express-sqs-mysql` - Express + SQS + MySQL (full stack)
- `nestjs-sqs` - NestJS integration
- `standalone-sqs` - Queue processing only
- `multi-queue` - Complex example with 5 queues

**Example:**
```bash
mitm init payment-processor --template express-sqs-mysql
cd payment-processor
pnpm install
pnpm dev
```

### `mitm generate queue <name>`

Generate a new queue with handlers, pipeline, events, and types.

**Aliases:** `mitm g queue`, `mitm g q`

**Options:**
- `-h, --handlers <list>` - Comma-separated handler names
- `-e, --events` - Generate events.ts file
- `-p, --preset <name>` - Use preset (critical, standard, best-effort, high-throughput)
- `-i, --interactive` - Interactive mode with prompts
- `--skip-app-update` - Don't update app.ts

**Presets:**
- `critical` - 5 retries, circuit breaker, full audit trail
- `standard` - 3 retries, error logging (default)
- `best-effort` - 1 retry, minimal overhead
- `high-throughput` - Batching, optimized for speed

**Examples:**
```bash
# Quick generation
mitm generate queue payments

# With handlers
mitm generate queue orders --handlers create,update,cancel,ship

# With preset
mitm generate queue payments --preset critical --events

# Interactive mode
mitm generate queue --interactive
```

### `mitm generate handler <name>`

Add a new handler to an existing queue.

**Aliases:** `mitm g handler`, `mitm g h`

**Options:**
- `-q, --queue <name>` - Target queue (required)
- `-a, --action <name>` - Action name (defaults to uppercase handler name)
- `-i, --interactive` - Interactive mode

**Examples:**
```bash
# Add handler to queue
mitm generate handler refund --queue payments

# Interactive mode
mitm generate handler --interactive
```

### `mitm list <target>`

List queues, handlers, or templates.

**Aliases:** `mitm ls`

**Targets:**
- `queues` - List all queues in project
- `handlers <queue>` - List handlers for specific queue
- `templates` - List available project templates

**Examples:**
```bash
mitm list queues
mitm list handlers orders
mitm list templates
```

### `mitm validate <target>`

Validate Queue-Centric Design structure.

**Targets:**
- `all` - Validate entire project
- `queue <name>` - Validate specific queue
- `structure` - Same as `all` (default)

**Options:**
- `--fix` - Auto-fix issues where possible
- `--strict` - Strict validation mode
- `--json` - Output as JSON

**Examples:**
```bash
# Validate all
mitm validate all

# Validate and fix
mitm validate all --fix

# Validate specific queue
mitm validate queue orders
```

## Development Status

**Current Version:** 0.1.0 (Phase 1 - MVP)

**Implemented:**
- ✅ CLI framework and command structure
- ✅ Type definitions
- ✅ Utility functions
- ✅ Handlebars templates
- ✅ Basic commands (init, generate, list, validate)

**In Progress:**
- 🚧 Template rendering engine
- 🚧 File generation logic
- 🚧 AST manipulation for code updates
- 🚧 Interactive prompts

**Coming Soon (Phase 2):**
- Middleware generation
- Advanced validation with auto-fix
- More templates
- Better error handling

## Project Structure

```
packages/cli/
├── src/
│   ├── commands/          # Command implementations
│   ├── generators/        # Code generators
│   ├── templates/         # Handlebars templates
│   ├── validators/        # Structure validators
│   ├── utils/            # Utility functions
│   └── types/            # Type definitions
├── templates/            # Handlebars template files
├── bin/                  # CLI executable
└── tests/               # Tests
```

## Contributing

See [CLI_PROPOSAL.md](../../CLI_PROPOSAL.md) for the complete roadmap and feature specifications.

## License

MIT

## Links

- [Documentation](../../docs)
- [Main Repository](https://github.com/gorannovosel/message-in-the-middle)
- [CLI Proposal](../../CLI_PROPOSAL.md)