https://github.com/avinava/mule-build
A type-safe CLI and library for MuleSoft application build automation.
https://github.com/avinava/mule-build
build cli mule mulesoft
Last synced: 5 months ago
JSON representation
A type-safe CLI and library for MuleSoft application build automation.
- Host: GitHub
- URL: https://github.com/avinava/mule-build
- Owner: Avinava
- Created: 2025-12-16T20:45:14.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2026-01-10T08:41:39.000Z (5 months ago)
- Last Synced: 2026-01-13T19:44:39.253Z (5 months ago)
- Topics: build, cli, mule, mulesoft
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@sfdxy/mule-build
- Size: 340 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Mule-Build
A type-safe CLI and library for MuleSoft application build automation.
[](https://www.npmjs.com/package/@sfdxy/mule-build)
[](https://opensource.org/licenses/MIT)
## Features
- 🔒 **Safe by Default** - Properties are never modified unless explicitly requested
- 📦 **Flexible Builds** - Support for normal, local dev, and production builds
- 🚀 **Local Development** - One command to build and deploy locally
- 🏷️ **Release Automation** - Semantic versioning and git tagging
- 🔌 **Dual Interface** - Both CLI and programmatic API (MCP-ready)
- 📝 **TypeScript** - Full type safety and exported types
## Installation
```bash
# Global installation
npm install -g @sfdxy/mule-build
# Local installation
npm install @sfdxy/mule-build
# Or use npx directly
npx @sfdxy/mule-build --help
```
## Quick Start
```bash
# Normal build (properties untouched)
mule-build package
# Build with stripped secure:: prefixes for local development
mule-build package --strip-secure
# Build for production (enforces secure:: prefixes)
mule-build package -e production
# Check for unsecured sensitive properties
mule-build enforce
```
## CLI Commands
### `package`
Build the MuleSoft application package.
```bash
mule-build package [options]
Options:
--strip-secure Strip secure:: prefixes for local development (explicit opt-in)
-e, --env Target environment: production (enforces secure::)
-s, --with-source Include source code in package (Studio importable)
-S, --skip-tests Skip MUnit tests
--version Override version from pom.xml
-o, --output Output directory for built JAR (defaults to target/)
```
**Examples:**
```bash
# Normal build - properties are NOT modified (safe default)
mule-build package
# Build with secure:: prefixes stripped for local Anypoint Studio
mule-build package --strip-secure --skip-tests
# Production build - validates all sensitive properties have secure::
mule-build package -e production
# Build and output to a custom directory
mule-build package --strip-secure --skip-tests -o /tmp/builds
```
### Build Modes
| Command | Behavior | Use Case |
|---------|----------|----------|
| `mule-build package` | Normal build, no modifications | General purpose |
| `mule-build package --strip-secure` | Strips `secure::` prefixes | Local dev / Studio |
| `mule-build package -e production` | Enforces `secure::` present | CloudHub / RTF |
> **Important:** The `--strip-secure` flag is mutually exclusive with `-e production`.
### `run`
Build and deploy to local Mule runtime.
```bash
mule-build run [options]
Options:
-d, --debug Enable remote debugging on port 5005
-c, --clean Run mvn clean before building
--strip-secure Strip secure:: prefixes for local development
-S, --skip-tests Skip MUnit tests
```
> **Note:** Requires `MULE_HOME` environment variable to be set.
### `release`
Bump version and create a release.
```bash
mule-build release -b [options]
Options:
-b, --bump Version bump type: major | minor | patch (required)
--no-tag Skip git tag creation
--no-push Skip git push
```
**Examples:**
```bash
# Minor version bump with tag and push
mule-build release -b minor
# Patch release without pushing
mule-build release -b patch --no-push
```
### `strip`
Strip `secure::` prefixes from XML files. Use this for manual stripping.
```bash
mule-build strip [options]
Options:
-f, --file Process single file
-d, --dir Process all XML files in directory (default: src/main/mule)
--dry-run Show changes without modifying files
```
This transforms:
- `${secure::db.password}` → `${db.password}`
- `Mule::p('secure::api.key')` → `Mule::p('api.key')`
### `enforce`
Check for unsecured sensitive properties.
```bash
mule-build enforce [options]
Options:
-f, --file Check single file
-d, --dir Check all XML files in directory (default: src/main/mule)
```
## Programmatic API
All commands are available as typed async functions:
```typescript
import { packageProject, stripSecure, enforceSecure, releaseVersion } from 'mule-build';
// Normal build (no property modifications)
const result = await packageProject({
skipTests: true,
});
// Build with stripped secure:: prefixes
const localResult = await packageProject({
stripSecure: true,
withSource: true,
});
// Production build with enforcement
const prodResult = await packageProject({
environment: 'production',
});
// Build to a custom output directory
const customOutputResult = await packageProject({
stripSecure: true,
skipTests: true,
outputDir: '/tmp/builds',
});
if (result.success) {
console.log(`Built: ${result.data.jarPath}`);
}
// Strip secure prefixes manually
const stripResult = await stripSecure({
directory: 'src/main/mule',
dryRun: true,
});
// Enforce security
const enforceResult = await enforceSecure({
directory: 'src/main/mule',
});
if (!enforceResult.data.valid) {
console.error('Violations:', enforceResult.data.violations);
}
```
## Configuration
Create an optional `mule-build.yaml` in your project root:
```yaml
project:
name: "my-api" # Optional, defaults to pom.xml name
profiles:
production:
description: "CI/CD Artifacts"
mavenProfile: "prod"
secureProperties: "enforce"
includeSource: false
enforceGitClean: true
```
### Default Behavior
Without a config file, sensible defaults are used:
| Command | Maven Profile | Secure Props | Include Source |
|---------|---------------|--------------|----------------|
| `package` | none | unchanged | false |
| `package --strip-secure` | none | stripped | false |
| `package -e production` | prod | enforced | false |
## TypeScript Support
All types are exported:
```typescript
import type {
PackageOptions,
PackageResult,
StripOptions,
StripResult,
EnforceOptions,
EnforceResult,
ReleaseOptions,
ReleaseResult,
Result,
BuildEnvironment,
BumpType,
} from 'mule-build';
```
## AI Agent Integration (MCP)
This tool exposes a **Model Context Protocol (MCP)** server, allowing AI agents (like Claude Desktop, IDE assistants) to directly interact with your build system to inspect projects, run builds, and manage releases.
### Features
**Tools** (all support optional `cwd` parameter for remote project directories):
| Tool | Description |
|------|-------------|
| `run_build` | Build Mule application package |
| `run_app` | Deploy to local Mule runtime |
| `stop_app` | Stop local Mule runtime |
| `check_app_status` | Check runtime status and port 8081 |
| `release_version` | Bump version and create git tag |
| `enforce_security` | Scan for unsecured properties |
| `strip_secure` | Strip `secure::` prefixes for local dev |
| `system_check` | Pre-flight environment validation |
**Resources**:
- `mule-build://config` - Project configuration
- `mule-build://docs/design` - Design documentation
- `mule-build://docs/best-practices` - Best practices guide
- `mule-build://docs/folder-structure` - Project structure conventions
### Setup for VS Code (Recommended)
Create `.vscode/mcp.json` in your workspace:
```json
{
"servers": {
"mule-build": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@sfdxy/mule-build", "mcp"]
}
}
}
```
The agent will now be able to "see" your MuleSoft project structure and offer build/release actions autonomously.
### Setup for Claude Desktop
Add the following to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"mule-build": {
"command": "npx",
"args": ["-y", "@sfdxy/mule-build", "mcp"]
}
}
}
```
## Requirements
- Node.js >= 18
- Maven (for build operations)
- Git (for release operations)
- MULE_HOME environment variable (for run command)
## Development
```bash
# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test
# Lint
npm run lint
# Format
npm run format
```
## Architecture
```
mule-build/
├── src/
│ ├── index.ts # Package exports
│ ├── cli.ts # CLI implementation
│ ├── api/ # Public API functions
│ ├── engine/ # Core logic
│ ├── config/ # Configuration
│ ├── types/ # TypeScript types
│ └── utils/ # Utilities
├── test/ # Tests and fixtures
└── docs/ # Documentation
```
See [docs/design.md](docs/design.md) for detailed technical documentation.
## Migration from Bash Script
| Bash Script | CLI Equivalent |
|------------|----------------|
| `./build.sh sandbox` | `mule-build package --strip-secure` |
| `./build.sh production` | `mule-build package -e production` |
## License
MIT
---
Built with 🚀 Antigravity