@sfdxy/mule-build 1.0.0

package/README.md

@@ -0,0 +1,301 @@
+# Mule-Build
+
+A type-safe CLI and library for MuleSoft application build automation.
+
+[![npm version](https://badge.fury.io/js/mule-build.svg)](https://badge.fury.io/js/mule-build)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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 <environment>  Target environment: production (enforces secure::)
+  -s, --with-source        Include source code in package (Studio importable)
+  -S, --skip-tests         Skip MUnit tests
+  --version <version>      Override version from pom.xml
+```
+
+**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 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. Automatically strips `secure::` prefixes.
+
+```bash
+mule-build run [options]
+
+Options:
+  -d, --debug   Enable remote debugging on port 5005
+  -c, --clean   Run mvn clean before building
+```
+
+> **Note:** Requires `MULE_HOME` environment variable to be set.
+
+### `release`
+
+Bump version and create a release.
+
+```bash
+mule-build release -b <type> [options]
+
+Options:
+  -b, --bump <type>  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 <path>   Process single file
+  -d, --dir <path>    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 <path>   Check single file
+  -d, --dir <path>    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',
+});
+
+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';
+```
+
+## 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
+
+---
+
+<p align="center">
+  <sub>Built with 🚀 <a href="https://github.com/google-deepmind/antigravity">Antigravity</a></sub>
+</p>

package/dist/bin/mule-build.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * Mule-Build CLI Entry Point
+ *
+ * This file is the entry point for the `npx mule-build` command.
+ */
+export {};
+//# sourceMappingURL=mule-build.d.ts.map

package/dist/bin/mule-build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mule-build.d.ts","sourceRoot":"","sources":["../../bin/mule-build.ts"],"names":[],"mappings":";AAEA;;;;GAIG"}

package/dist/bin/mule-build.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Mule-Build CLI Entry Point
+ *
+ * This file is the entry point for the `npx mule-build` command.
+ */
+import { run } from '../src/cli.js';
+run().catch((error) => {
+    console.error(`Fatal error: ${error.message}`);
+    process.exit(1);
+});
+//# sourceMappingURL=mule-build.js.map

package/dist/bin/mule-build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mule-build.js","sourceRoot":"","sources":["../../bin/mule-build.ts"],"names":[],"mappings":";AAEA;;;;GAIG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAEpC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IAClB,OAAO,CAAC,KAAK,CAAC,gBAAgB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC,CAAC,CAAC"}

package/dist/src/api/enforce.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Enforce API
+ *
+ * Programmatic interface for validating secure:: enforcement.
+ */
+import { Result, EnforceOptions, EnforceResult } from '../types/index.js';
+/**
+ * Check files for unsecured sensitive properties
+ */
+export declare function enforceSecure(options?: EnforceOptions): Promise<Result<EnforceResult>>;
+//# sourceMappingURL=enforce.d.ts.map

package/dist/src/api/enforce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enforce.d.ts","sourceRoot":"","sources":["../../../src/api/enforce.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,MAAM,EAAW,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAInF;;GAEG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAgDhG"}

package/dist/src/api/enforce.js

@@ -0,0 +1,58 @@
+/**
+ * Enforce API
+ *
+ * Programmatic interface for validating secure:: enforcement.
+ */
+import { join } from 'path';
+import { existsSync } from 'fs';
+import { ok, err } from '../types/index.js';
+import { enforceSecure as enforceSecureEngine } from '../engine/XmlProcessor.js';
+import { logger } from '../utils/logger.js';
+/**
+ * Check files for unsecured sensitive properties
+ */
+export async function enforceSecure(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    // Determine target
+    let target;
+    if (options.file) {
+        target = options.file.startsWith('/') ? options.file : join(cwd, options.file);
+        if (!existsSync(target)) {
+            return err(new Error(`File not found: ${target}`));
+        }
+    }
+    else if (options.directory) {
+        target = options.directory.startsWith('/') ? options.directory : join(cwd, options.directory);
+        if (!existsSync(target)) {
+            return err(new Error(`Directory not found: ${target}`));
+        }
+    }
+    else {
+        // Default to src/main/mule
+        target = join(cwd, 'src', 'main', 'mule');
+        if (!existsSync(target)) {
+            return err(new Error(`Default directory not found: ${target}`));
+        }
+    }
+    const result = await enforceSecureEngine(target, {
+        sensitivePatterns: options.sensitivePatterns,
+        cwd,
+    });
+    if (!result.success || !result.data) {
+        return err(result.error ?? new Error('Enforce operation failed'));
+    }
+    const data = result.data;
+    logger.info(`Checked ${data.filesChecked.length} files`);
+    if (data.valid) {
+        logger.success('All sensitive properties are properly secured');
+    }
+    else {
+        logger.error(`Found ${data.violations.length} unsecured sensitive properties:`);
+        for (const v of data.violations) {
+            logger.error(`  ${v.file}:${v.line} - ${v.value}`);
+            logger.info(`    Suggestion: ${v.suggestion}`);
+        }
+    }
+    return ok(data);
+}
+//# sourceMappingURL=enforce.js.map

package/dist/src/api/enforce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enforce.js","sourceRoot":"","sources":["../../../src/api/enforce.ts"],"names":[],"mappings":"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"}

package/dist/src/api/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Public API Exports
+ *
+ * All programmatic functions for MCP and direct library usage.
+ */
+export { packageProject } from './package.js';
+export { runLocal } from './run.js';
+export { releaseVersion } from './release.js';
+export { stripSecure } from './strip.js';
+export { enforceSecure } from './enforce.js';
+export type { PackageOptions, PackageResult, RunOptions, RunResult, ReleaseOptions, ReleaseResult, StripOptions, StripResult, EnforceOptions, EnforceResult, DeploymentInfo, BuildEnvironment, BumpType, } from '../types/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG7C,YAAY,EACV,cAAc,EACd,aAAa,EACb,UAAU,EACV,SAAS,EACT,cAAc,EACd,aAAa,EACb,YAAY,EACZ,WAAW,EACX,cAAc,EACd,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,QAAQ,GACT,MAAM,mBAAmB,CAAC"}

package/dist/src/api/index.js

@@ -0,0 +1,12 @@
+/**
+ * Public API Exports
+ *
+ * All programmatic functions for MCP and direct library usage.
+ */
+// API Functions
+export { packageProject } from './package.js';
+export { runLocal } from './run.js';
+export { releaseVersion } from './release.js';
+export { stripSecure } from './strip.js';
+export { enforceSecure } from './enforce.js';
+//# sourceMappingURL=index.js.map

package/dist/src/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,gBAAgB;AAChB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/src/api/package.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Package API
+ *
+ * Programmatic interface for building MuleSoft projects.
+ */
+import { Result, PackageOptions, PackageResult } from '../types/index.js';
+/**
+ * Build a MuleSoft project package
+ *
+ * By default, builds without modifying any files.
+ * Use `stripSecure: true` to strip secure:: prefixes for local development.
+ * Use `environment: 'production'` to enforce secure:: prefixes.
+ */
+export declare function packageProject(options?: PackageOptions): Promise<Result<PackageResult>>;
+//# sourceMappingURL=package.d.ts.map

package/dist/src/api/package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../../src/api/package.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,OAAO,EAAE,MAAM,EAAW,cAAc,EAAE,aAAa,EAAkB,MAAM,mBAAmB,CAAC;AAuEnG;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CA6MjG"}