npm package: @mdp-framework/mlang
Description: MLang CLI - Policy compiler, PR governance, and developer tools
Author: MDP Framework Contributors
Latest version: 1.1.99

# MLang CLI

Policy compiler, PR governance, and AI-powered developer tools for the MDP Framework.

## Installation

```bash
npm install -g @mdp-framework/mlang
```

## Quick Start

```bash
# Initialize MLang in your project
mlang init

# Compile policies
mlang policy build --in policies/ --out .mlang/policies

# Evaluate a PR
mlang evaluate --file pr-data.json

# Run AI workflow
mlang workflow run --capsule feature-123 --agents pm,architect,engineer

# Check component similarity
mlang aoi check --component "Button" --framework github.com/your/framework
```

## Commands

### Core Commands

#### `mlang init`
Initialize MLang in your project.

```bash
mlang init [--force] [--verbose]
```

**Options:**
- `--force`: Reinitialize even if `.mlang` directory exists
- `--verbose`: Show detailed initialization steps

#### `mlang doctor`
Check MLang environment and dependencies.

```bash
mlang doctor [--ci] [--verbose]
```

**Options:**
- `--ci`: Run in CI mode (requires `GITHUB_TOKEN`)
- `--verbose`: Show detailed check information

### Policy Commands

#### `mlang policy init`
Initialize a new policy file.

```bash
mlang policy init --id <id> --scope <scope> --out <file>
```

**Options:**
- `--id <id>`: Policy ID (e.g., `eng.pr.review`)
- `--scope <scope>`: Policy scope (e.g., `pr/governance`)
- `--out <file>`: Output file path

#### `mlang policy build`
Compile Markdown policies to unsigned PolicyCards.

```bash
mlang policy build --in <dir> --out <dir> [--version <version>] [--strict]
```

**Options:**
- `--in <dir>`: Input directory (policies/\*.md)
- `--out <dir>`: Output directory for unsigned JSON
- `--version <version>`: Override version (default: YYYY.MM.DD)
- `--strict`: Fail on warnings

#### `mlang policy sign`
Sign compiled policies with ed25519.

```bash
mlang policy sign --in <dir> --out <dir> --key-file <file>
```

**Options:**
- `--in <dir>`: Input directory (unsigned JSON)
- `--out <dir>`: Output directory for signed JSON
- `--key-file <file>`: Private key file (ed25519)

#### `mlang policy verify`
Verify signed policy signatures.

```bash
mlang policy verify --in <path> [--key-file <file>]
```

**Options:**
- `--in <path>`: File or directory to verify
- `--key-file <file>`: Public key file (default: `.mlang/keys/*.pub`)

### Evaluation Commands

#### `mlang evaluate`
Evaluate PR or local changes against policies.

```bash
mlang evaluate --file <file> [--policies <dir>] [--format <format>] [--execute] [--dry-run]
```

**Options:**
- `--pr <number>`: PR number (requires GitHub token)
- `--file <file>`: Load PR data from JSON file
- `--policies <dir>`: Policy directory (default: `.mlang/policies`)
- `--format <format>`: Output format: `text` or `json` (default: `text`)
- `--execute`: Execute ActionPlan (requires GitHub token)
- `--dry-run`: Execute ActionPlan in dry-run mode
- `--github-token <token>`: GitHub token for execution

**Example:**
```bash
mlang evaluate --file pr-123.json --format json
```

#### `mlang pr review`
Review PR against policies (CI entrypoint).

```bash
mlang pr review --pr <number> [--repo <repo>] [--check-name <name>] [--emit-envelope <file>] [--dry-run]
```

**Options:**
- `--pr <number>`: PR number to review
- `--repo <repo>`: Repository (owner/repo) - auto-inferred if not provided
- `--check-name <name>`: GitHub check name (default: `mdp-governance`)
- `--emit-envelope <file>`: Emit envelope JSON to file
- `--dry-run`: Skip action execution (evaluation only)

### Workflow Commands (Stream 6)

Multi-agent workflow orchestration with PM, Architect, Engineer, and Designer agents.

#### `mlang workflow run`
Run a multi-agent workflow on a capsule.

```bash
mlang workflow run [--capsule <id>] [--workflow <name>] [--agents <agents>] [--json] [--verbose]
```

**Options:**
- `--capsule <id>`: Capsule ID to run workflow on
- `--workflow <name>`: Workflow definition name (from `.mlang/workflows/`)
- `--agents <agents>`: Comma-separated agent names (e.g., `pm,architect,engineer`)
- `--json`: Output as JSON
- `--verbose`: Show detailed reasoning and context

**Examples:**
```bash
# Run default workflow (PM → Architect → Engineer)
mlang workflow run --capsule feature-auth-123

# Run custom workflow from definition
mlang workflow run --capsule feature-auth-123 --workflow feature-analysis

# Run with custom agent sequence
mlang workflow run --capsule feature-auth-123 --agents pm,designer,engineer

# Output as JSON
mlang workflow run --capsule feature-auth-123 --json
```

**Workflow Definition Format** (`.mlang/workflows/*.json`):
```json
{
  "name": "feature-analysis",
  "description": "Analyze feature requirements",
  "agents": [
    {
      "type": "pm",
      "config": {
        "focus": "requirements"
      }
    },
    {
      "type": "architect",
      "config": {
        "focus": "design"
      }
    }
  ],
  "metadata": {
    "author": "team-name",
    "created_at": "2025-01-12T00:00:00Z"
  }
}
```

#### `mlang workflow status`
Show workflow status for a capsule.

```bash
mlang workflow status --capsule <id> [--json] [--verbose]
```

**Options:**
- `--capsule <id>`: Capsule ID (required)
- `--json`: Output as JSON
- `--verbose`: Show detailed information

**Example:**
```bash
mlang workflow status --capsule feature-auth-123 --verbose
```

#### `mlang workflow list`
List available workflow definitions.

```bash
mlang workflow list [--json] [--verbose]
```

**Options:**
- `--json`: Output as JSON
- `--verbose`: Show detailed information

**Example:**
```bash
mlang workflow list
```

### AOI Commands (Stream 6)

Architecture of Intent (AOI) operations for detecting missing framework components and generating specifications.

#### `mlang aoi generate`
Manually trigger AOI spec generation for a PR.

```bash
mlang aoi generate --pr <file> [--policy <id>] [--json] [--verbose]
```

**Options:**
- `--pr <file>`: PR data file (JSON) (required)
- `--policy <id>`: Policy ID (defaults to first AOI-enabled policy)
- `--json`: Output as JSON
- `--verbose`: Show detailed information

**Example:**
```bash
mlang aoi generate --pr pr-123.json --policy ios.swiftui.design-system
```

**Output:**
- AOI specification
- Similarity check results
- Generated actions (Jira issues, counter-PRs, notifications)

#### `mlang aoi check`
Check if a component exists via similarity search.

```bash
mlang aoi check --component <query> [--framework <repo>] [--threshold <number>] [--json] [--verbose]
```

**Options:**
- `--component <query>`: Component name or description (required)
- `--framework <repo>`: Framework repository
- `--threshold <number>`: Similarity threshold 0.0-1.0 (default: `0.8`)
- `--json`: Output as JSON
- `--verbose`: Show detailed information

**Examples:**
```bash
# Check if authentication component exists
mlang aoi check --component "JWT authentication manager" --framework github.com/company/framework

# Lower threshold for broader matching
mlang aoi check --component "authentication" --threshold 0.7

# Output as JSON
mlang aoi check --component "Button" --framework github.com/company/design-system --json
```

**Output:**
- Component existence status
- Closest match with similarity score
- Recommendation (use existing or create new)

#### `mlang aoi actions`
List pending AOI actions.

```bash
mlang aoi actions [--pr <number>] [--status <status>] [--json] [--verbose]
```

**Options:**
- `--pr <number>`: Filter by PR number
- `--status <status>`: Filter by status (`pending`, `completed`, `failed`)
- `--json`: Output as JSON
- `--verbose`: Show detailed information

**Examples:**
```bash
# List all pending actions
mlang aoi actions --status pending

# List actions for specific PR
mlang aoi actions --pr 123

# List all actions
mlang aoi actions
```

**Action Types:**
- `create_issue`: Jira issue created for framework team
- `create_counter_pr`: Counter-PR created in framework repo
- `create_followup_pr`: Follow-up PR to migrate original code
- `notify_owners`: Slack notification sent to owners

#### `mlang aoi config`
Show AOI configuration.

```bash
mlang aoi config [--json] [--verbose]
```

**Options:**
- `--json`: Output as JSON
- `--verbose`: Show policy-specific settings

**Example:**
```bash
mlang aoi config --verbose
```

**Configuration File** (`.mlang/aoi-config.json`):
```json
{
  "enabled": true,
  "similarity_threshold": 0.8,
  "auto_create_counter_pr": false,
  "auto_create_followup_pr": false,
  "include_tests": true,
  "frameworks": [
    "github.com/company/design-system"
  ],
  "policies": {
    "ios.swiftui.design-system": {
      "threshold": 0.85,
      "framework": "github.com/company/ios-framework"
    }
  }
}
```

### Registry Commands

#### `mlang registry head`
Show latest version on channel.

```bash
mlang registry head <id> [--channel <channel>]
```

**Options:**
- `--channel <channel>`: Channel name (`stable`, `preview`, `dev`) (default: `stable`)

#### `mlang registry get`
Fetch policy by ID.

```bash
mlang registry get <id> [--version <version>] [--save <file>]
```

**Options:**
- `--version <version>`: Specific version (YYYY.MM.DD)
- `--save <file>`: Save policy to file

#### `mlang registry verify`
Verify policy signature.

```bash
mlang registry verify <file>
```

#### `mlang registry list`
List all policies in registry.

```bash
mlang registry list [prefix]
```

### Capsule Commands

#### `mlang capsule prune`
Prune old capsules based on retention policy.

```bash
mlang capsule prune [--apply] [--keep-days <days>] [--yes]
```

**Options:**
- `--apply`: Actually delete capsules (default is dry-run)
- `--keep-days <days>`: Override retention days
- `--yes`: Skip confirmation prompts

#### `mlang capsule export`
Export capsules to NDJSON file.

```bash
mlang capsule export [--capsule <id>] [--kind <kind>] [--out <file>]
```

**Options:**
- `--capsule <id>`: Export specific capsule by ID
- `--kind <kind>`: Export all capsules of a kind (`pr`, `feature`, `aoi`)
- `--out <file>`: Output file (default: stdout)

#### `mlang capsule import`
Import capsules from NDJSON file.

```bash
mlang capsule import --file <file> [--overwrite]
```

**Options:**
- `--file <file>`: Input NDJSON file (required)
- `--overwrite`: Overwrite existing capsules

### Gateway Commands

#### `mlang gateway`
Run gateway in MCP server mode.

```bash
mlang gateway [--mode <mode>] [--stdio] [--http] [--port <port>]
```

**Options:**
- `--mode <mode>`: Gateway mode (only `mcp` supported) (default: `mcp`)
- `--stdio`: Use stdio transport (default)
- `--http`: Use HTTP transport
- `--port <port>`: HTTP port (default: `8080`)

### Keys Commands

#### `mlang keys generate`
Generate ed25519 signing keypair.

```bash
mlang keys generate --out <path> [--name <name>]
```

**Options:**
- `--out <path>`: Output path (will create `.ed25519` and `.pub` files)
- `--name <name>`: Key name/identifier (for documentation)

## Environment Variables

### Required (for AI operations)

- `ANTHROPIC_API_KEY`: Anthropic API key for Claude models
- `OPENAI_API_KEY`: OpenAI API key for GPT models

### Optional

- `GITHUB_TOKEN`: GitHub token for PR operations
- `MLANG_BASE_PATH`: Override default `.mlang` directory
- `MLANG_LOG_LEVEL`: Log level (`debug`, `info`, `warn`, `error`)

## Configuration

MLang uses a `.mlang/` directory in your project root:

```
.mlang/
├── workflows/              # Workflow definitions
│   └── *.json
├── state/
│   └── capsules/          # State capsules
│       └── *.json
├── aoi/
│   ├── actions.json       # Pending AOI actions
│   └── specs/             # Generated AOI specs
│       └── *.json
├── aoi-config.json        # AOI configuration
├── packs/
│   ├── stable/            # Stable policies
│   ├── preview/           # Preview policies
│   └── dev/               # Development policies
├── keys/                  # Signing keys
│   ├── *.ed25519          # Private keys
│   └── *.pub              # Public keys
└── config.json            # MLang configuration
```

## Examples

### Example 1: Run Multi-Agent Workflow

```bash
# Create capsule for feature
echo '{
  "id": "feature-auth-123",
  "kind": "feature",
  "evidence": ["Implement JWT authentication"],
  "metadata": {"title": "Add authentication"}
}' > .mlang/state/capsules/feature-auth-123.json

# Run workflow
mlang workflow run --capsule feature-auth-123 --agents pm,architect,engineer --verbose
```

### Example 2: Check Component Similarity

```bash
# Check if button component exists
mlang aoi check \
  --component "Primary action button with ripple effect" \
  --framework github.com/company/design-system \
  --threshold 0.8
```

### Example 3: Generate AOI Spec

```bash
# Create PR data file
echo '{
  "number": 123,
  "title": "Add custom button",
  "files": [{"path": "Button.tsx", "status": "added"}]
}' > pr-123.json

# Generate AOI spec
mlang aoi generate --pr pr-123.json --policy ui.design-system
```

### Example 4: CI Integration

```yaml
# .github/workflows/pr-check.yml
name: PR Governance
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install -g @mdp-framework/mlang
      - run: mlang pr review --pr ${{ github.event.pull_request.number }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```

## Troubleshooting

### "Command not found: mlang"
Install the CLI globally:
```bash
npm install -g @mdp-framework/mlang
```

### "No API key detected"
Set the API key:
```bash
export ANTHROPIC_API_KEY="your-key-here"
```

### "Capsule not found"
Ensure capsule exists in `.mlang/state/capsules/`

### "Policy not found"
Compile policies first:
```bash
mlang policy build --in policies/ --out .mlang/packs/stable
```

### "Workflow failed: timeout"
Increase timeout in workflow config or use fewer agents

## Development

```bash
# Clone repository
git clone https://github.com/mdp-labs/mdp-mlang.git
cd mdp-mlang

# Install dependencies
npm install

# Build CLI
cd packages/cli
npm run build

# Run tests
npm test

# Run in development mode
npm run dev
```

## Contributing

See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

## License

MIT

## Support

- [GitHub Issues](https://github.com/mdp-labs/mdp-mlang/issues)
- [Documentation](https://github.com/mdp-labs/mdp-mlang/tree/main/Docs)
- [Contract Documents](../../Docs/contracts/)

## Related

- [Stream 6 Contract](../../Docs/contracts/STREAM-6-CLI-AI-COMMANDS.md)
- [Stream 5 Multi-Agent](../../Docs/contracts/STREAM-5-MULTI-AGENT.md)
- [Stream 4 AOI Coordinator](../../Docs/contracts/STREAM-4-AOI-COORDINATOR.md)
- [Stream 2 AI Evaluators](../../Docs/contracts/STREAM-2-AI-EVALUATORS.md)