npm package: @hoiltd/azure-marketplace-generator
Description: CLI tool for generating Azure Storage marketplace managed applications with enhanced security and data protection features
Author: Home & Office Improvements Ltd
Latest version: 3.1.2

# Azure Marketplace Generator

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)](https://www.typescriptlang.org/)
[![Version](https://img.shields.io/npm/v/@hoiltd/azure-marketplace-generator)](https://www.npmjs.com/package/@hoiltd/azure-marketplace-generator)
[![npm](https://img.shields.io/npm/dt/@hoiltd/azure-marketplace-generator)](https://www.npmjs.com/package/@hoiltd/azure-marketplace-generator)
[![Tests](https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azure-marketplace-generator/workflows/CI/badge.svg)](https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azure-marketplace-generator/actions)

Enterprise-grade CLI tool for generating Azure Storage marketplace managed applications with comprehensive security and data protection features.

## Features

###  Core Capabilities

- **Storage-focused managed application generation** with production-ready templates
- **ARM template validation** with Microsoft ARM-TTK integration
- **Marketplace-ready package creation** for Azure Marketplace submission
- **TypeScript with full type safety** for reliability and maintainability
- **Extensible plugin architecture** for custom templates and commands (v3.1.0 - [OK] Fully Operational)
  - Install plugins from npm or use local plugins
  - Extend with custom Handlebars helpers
  - Add CLI commands dynamically
  - First official plugin: [@hoiltd/azmp-plugin-vm@2.1.0](https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azmp-plugin-vm) - [OK] 98% ARM-TTK Compliance

###  Enhanced Security Features (v3.0.0)

- **Blob Public Access Control** - Prevent anonymous access to blobs
- **TLS Version Enforcement** - Require minimum TLS 1.2 for all connections
- **HTTPS-Only Traffic** - Enforce secure transport for all requests
- **Public Network Access Control** - Restrict access to selected networks
- **OAuth Default Authentication** - Prioritize Microsoft Entra ID (Azure AD) authentication
- **Shared Key Access Management** - Disable legacy shared key authentication
- **Infrastructure Encryption** - Double encryption for data at rest

### ️ Data Protection Features (v3.0.0)

- **Blob Soft Delete** - Configurable retention (7-365 days) for deleted blobs
- **Container Soft Delete** - Configurable retention (7-365 days) for deleted containers
- **Blob Versioning** - Automatic version tracking for blob modifications
- **Change Feed** - Ordered transaction log for all changes
- **Last Access Time Tracking** - Monitor and optimize storage costs

> **Note:** All parameters are verified against [official Microsoft Azure documentation](https://learn.microsoft.com/en-us/azure/storage/) for production compliance.


## Installation

### From NPM (Recommended)

```bash
# Install globally
npm install -g @hoiltd/azure-marketplace-generator

# Verify installation
azmp --version
```

### From Source

```bash
# Clone and install
git clone https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azure-marketplace-generator.git
cd azure-marketplace-generator
npm install

# Install ARM-TTK for validation
npm run install-arm-ttk

# Build the CLI
npm run build
```

## Quick Links

-  **[NPM Package](https://www.npmjs.com/package/@hoiltd/azure-marketplace-generator)** - Install the latest version
-  **[GitHub Wiki](https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azure-marketplace-generator/wiki)** - Comprehensive guides and tutorials
-  **[Releases](https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azure-marketplace-generator/releases)** - Version history and changelogs
-  **[Discussions](https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azure-marketplace-generator/discussions)** - Community support and ideas
-  **[Issues](https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azure-marketplace-generator/issues)** - Bug reports and feature requests
-  **[Plugin: VM](https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azmp-plugin-vm)** - Virtual Machine plugin (@hoiltd/azmp-plugin-vm@2.1.0) - [OK] Marketplace Certified

## Usage

### Create Storage Solution

```bash
azmp create storage --publisher "MyCompany" --name "MyStorageApp"
```

**Generated templates include:**

- [OK] All security parameters (7) configured with secure defaults
- [OK] All data protection features (5) with recommended settings
- [OK] Production-ready ARM templates validated against Azure specifications
- [OK] UI definitions with intuitive configuration steps

For detailed parameter configuration, see [SECURITY_FEATURES.md](docs/SECURITY_FEATURES.md) and [DATA_PROTECTION_GUIDE.md](docs/DATA_PROTECTION_GUIDE.md).

### Validate Templates

```bash
azmp validate ./output
```

### Package for Marketplace

```bash
azmp package ./output
```

## Commands

| Command | Description |
|---------|-------------|
| `azmp create storage` | Create new storage managed application |
| `azmp validate <path>` | Validate ARM templates with ARM-TTK |
| `azmp package <path>` | Package templates for marketplace submission |

## Output Structure

```text
output/
--- mainTemplate.json          # ARM template
--- createUiDefinition.json    # UI definition  
--- viewDefinition.json        # Management view
--- nestedtemplates/           # Nested templates
    --- storageAccount.json
```

## Samples

Canonical reference templates (for comparison, testing, and authoring) are now stored under the `samples/` directory:

```text
samples/
--- storage/        # Canonical storage managed application (mainTemplate, createUiDefinition, viewDefinition)
--- vm/             # Reference VM sample from plugin (not generated in core mode)
```

Use these samples to:

- Quickly diff future template changes against a known-good baseline
- Validate ARM-TTK regression behavior without invoking the generator
- Prototype enhancements before wiring them into Handlebars templates

### Removed Debug Fixtures

Legacy experimental folders `test-debug/` and `test-debug-no-gallery/` have been removed to keep the repository lean. Their advanced configuration patterns (security, data protection, optional service/event features) are fully represented in `samples/storage/`. If you need to experiment with stripped-down variants (e.g. without gallery metadata), duplicate `samples/storage/createUiDefinition.json` and remove the `gallery` block—no other changes required.

Rationale for removal:
- Eliminated duplicate template parameter sets
- Reduced cognitive overhead for contributors
- Ensured a single canonical advanced storage baseline

If a future minimal “basic” sample is required, it can be derived from the current storage sample by removing the `serviceSelection` and `eventGridSection` steps plus related parameters and outputs.

### Core-Only Mode (Plugin Disabled)

The repository defaults to a "core-only" mode for smoke testing by disabling the VM plugin in `azmp.config.json`:

```jsonc
{
  "plugins": [
    {
      "package": "/home/msalsouri/Projects/azmp-plugin-vm/dist",
      "enabled": false
    }
  ]
}
```

Re‑enable the plugin by setting `enabled: true` or adding additional plugin entries. In core-only mode, only built-in storage generation commands are available which keeps the validation surface minimal and fast.

### Smoke Test

A Jest smoke test (`src/__tests__/smoke-core.test.ts`) exercises the full core pipeline:

1. Build the CLI
2. Generate a storage application
3. Validate with ARM‑TTK
4. Package into a zip

Run it directly:

```bash
npm run build
npx jest src/__tests__/smoke-core.test.ts
```

This test is intentionally minimal and avoids plugin dependency to keep CI fast and isolate core regressions.

### Partner Center Preflight Validation

Before you upload a package to Azure Partner Center, you can run a deeper structural validation that simulates common certification checks.

We added a dedicated test (`src/__tests__/listing-validation.test.ts`) that verifies:

| Check | Purpose |
|-------|---------|
| Core file presence | Ensures `mainTemplate.json`, `createUiDefinition.json`, `viewDefinition.json` exist |
| Parameter coverage | Confirms all 16 storage, security, and data protection parameters are declared |
| Resource topology | Validates storage account + blobServices resources and dependency chain |
| UI outputs mapping | Ensures every required parameter is exported from `createUiDefinition.json` |
| View definitions | Confirms security & data protection status outputs are referenced in `viewDefinition.json` |

Run it directly:

```bash
npx jest src/__tests__/listing-validation.test.ts
```

#### Manual Partner Center Checklist

1. Generate package:
  ```bash
  azmp create storage -p "Your Publisher" -n "Your Offer Name" -o ./output
  azmp validate ./output   # (Optional but recommended – ARM-TTK)
  azmp package ./output -o offer-v1.zip
  ```
2. Inspect ZIP contents (must contain exactly the three core JSON files unless you add nested templates):
  ```bash
  unzip -l offer-v1.zip
  ```
3. Open `mainTemplate.json` and verify:
  - `$schema` points to deploymentTemplate.json
  - At least one resource of type `Microsoft.Storage/storageAccounts`
  - Parameters align to pricing/config tiers you intend to expose
4. Open `createUiDefinition.json` and confirm:
  - `$schema` uses the preview or current schema URL
  - `gallery` section exists (unless intentionally removed for private preview)
  - Every parameter needed by the template appears in `parameters.outputs`
5. Open `viewDefinition.json` and ensure:
  - Overview + Properties + Metrics sections present
  - Security/Data Protection references resolve to outputs (no typos)
6. Upload ZIP to Partner Center offer technical configuration
7. Use Preview to deploy internally (test with production subscription)
8. Capture deployment success evidence (screenshots, deployment JSON) for certification notes

> Tip: If you need a gallery‑less variant for private preview, remove the `gallery` block from `createUiDefinition.json` after generation – no other changes required.

## Package Artifact Policy

To keep the repository lean and reproducible:

- Root-level ZIP files produced by `azmp package` are transient and should not be committed.
- The `.gitignore` rules ignore all `*.zip` except curated, versioned examples stored under `marketplace-packages/`.
- Curated samples (e.g. `storage-offer-v1.0.zip`) demonstrate expected package contents; regenerate others locally as needed.
- If you create a new canonical sample, place it in `marketplace-packages/` with a semantic version in the filename and update this section.

Rationale: Prevent stale or ambiguous artifacts, encourage deterministic regeneration, and reduce merge noise.

## Packaging Output Filename Precedence

When running `azmp package <path>` the tool selects the output ZIP file name using a clear precedence order:

1. CLI argument `-o, --output <file>` (highest precedence)
2. `packaging.defaultFileName` from `azmp.config.json` (if provided and CLI flag omitted)
3. Built-in fallback: `managed-app-package.zip`

Examples:

```bash
# Uses explicit CLI value
azmp package ./output -o my-offer-v1.zip

# Uses config defaultFileName if defined
azmp package ./output --config ./azmp.config.json

# Falls back to built-in default if neither CLI nor config provides a name
azmp package ./output
```

Minimal `azmp.config.json` snippet:

```json
{
  "packaging": {
    "defaultFileName": "my-default-package.zip"
  }
}
```

> Tip: Avoid committing generated ZIPs—use the precedence system to keep builds reproducible.

## Requirements

- Node.js 18+
- PowerShell (for ARM-TTK validation)

## Development

```bash
# Run in development mode
npm run dev

# Run tests  
npm test

# Lint code
npm run lint
```

## Documentation

### References User Guides
- **[Configuration Guide](docs/CONFIGURATION_GUIDE.md)** - Learn how to use config files for consistent settings
- **[Security Features](docs/SECURITY_FEATURES.md)** - Comprehensive guide to all 7 security parameters
- **[Data Protection Guide](docs/DATA_PROTECTION_GUIDE.md)** - Complete guide to data protection features and recovery

### Fixes Developer Resources
- **[Production Features](docs/PRODUCTION_FEATURES.md)** - Summary of all production-ready enhancements
- **[Development Log](docs/DEVELOPMENT_LOG.md)** - Version history and development phases
- **[Changelog](CHANGELOG.md)** - Detailed changelog following Keep a Changelog format
- **[Azure Live Testing](docs/AZURE_LIVE_TESTING.md)** - Comprehensive Azure deployment testing guide
- **[Plugin Architecture](docs/PLUGIN_ARCHITECTURE.md)** - Extensibility framework for custom templates (v3.0.0+)

###  Official Resources
- [Azure Storage Documentation](https://learn.microsoft.com/en-us/azure/storage/)
- [Azure Verified Modules](https://github.com/Azure/bicep-registry-modules)
- [@azure/arm-storage SDK](https://learn.microsoft.com/en-us/javascript/api/@azure/arm-storage/)

## Roadmap

### [OK] v3.0.0 (Released - October 2024)

- [OK] Plugin interface foundation
- [OK] 12 security and data protection parameters
- [OK] Comprehensive documentation (9 guides)
- [OK] Full Azure live testing (35/35 tests)

### [OK] v3.1.0 (Released - December 2024)

**Plugin System Implementation:**

- [OK] Plugin loader with dynamic discovery
- [OK] Automatic plugin registration from config files
- [OK] CLI command extensions support
- [OK] Template type registration API
- [OK] Handlebars helper registration API
- [OK] Security validations (path traversal, workspace protection)
- [OK] Conflict detection for helpers, commands, templates
- [OK] Error isolation and timeout handling
- [OK] Comprehensive test suite (119 tests passing)
- [OK] Published to NPM registry
- [OK] GitHub Actions security hardening (CodeQL alerts fixed)

**Official Plugin Available:**

 **[@hoiltd/azmp-plugin-vm@2.1.0](https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azmp-plugin-vm)** - Virtual Machine plugin with comprehensive Azure VM support

**Latest: v2.1.0 (October 31, 2025)**
- [OK] **98% ARM-TTK Compliance** (46/47 tests passing)
- [OK] **Marketplace Certified** - Production-ready templates
- [OK] **801 passing tests** (92% of 872 total test suite)
- [OK] **178 Handlebars helpers** for advanced template generation
- [OK] **44 CLI commands** for VM configuration
-  **Features:** VM sizes, OS images, networking, security, identity, HA, backup, monitoring

**Installation:**
```bash
npm install @hoiltd/azmp-plugin-vm@^2.1.0
```

**Configuration Example:**
```json
{
  "plugins": [
    {
      "package": "@hoiltd/azmp-plugin-vm",
      "enabled": true,
      "options": {
        "defaultVmSize": "Standard_D2s_v3",
        "security": {
          "enableTrustedLaunch": true
        }
      }
    }
  ]
}
```

**Resources:**
-  [Plugin Documentation](https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azmp-plugin-vm#readme)
- Checklist [Release Notes v2.1.0](https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azmp-plugin-vm/releases/tag/v2.1.0)
- Fixes [Integration Guide](https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azmp-plugin-vm/blob/main/INTEGRATION_GUIDE.md)

###  v3.2.0 (In Development)

**Core Improvements:**

- [ ] Semver validation for plugin versions
- [ ] Eager template validation on plugin load
- [ ] Plugin performance optimizations
- [ ] Enhanced error messages and debugging

**Plugin Ecosystem:**

- [ ] Plugin documentation improvements
- [ ] Plugin testing utilities
- [ ] Community plugin registry

**Storage Features:**

- [ ] Private endpoint configuration
- [ ] Customer-managed encryption keys (CMK)
- [ ] Immutability policies for compliance
- [ ] Advanced network security rules
- [ ] Azure AD RBAC role assignments
- [ ] Diagnostic settings and monitoring

###  Future Releases

**Q1 2026: Compliance & Policy Guardrails Plugin**

️ **Enterprise Compliance Made Effortless**

Next generation plugin for automatic governance and compliance frameworks:

**Core Features:**
-  **One-click compliance** frameworks (CIS, NIST 800-53, Azure Security Benchmark)
-  **Automatic security baselines** with Defender for Cloud integration
- Checklist **Policy as Code** with pre-built Azure Policy initiatives
- Alert **Continuous monitoring** with compliance dashboards and alerting
- Matrix **Compliance evidence** generation for Partner Center submissions

**Enterprise Value:**
-  **Enterprise trust** - Built-in governance reduces security concerns
-  **Premium pricing** - Compliance commands higher deal values
-  **Customer retention** - Governance creates switching costs
-  **Competitive advantage** - Most marketplace tools ignore compliance

**Target Frameworks:**
- CIS Azure Foundations Benchmark (Level 1 & 2)
- NIST 800-53 (Moderate/High impact controls)
- Azure Security Benchmark (Microsoft official baseline)
- ISO 27001 Information Security Management
- Industry-specific: HIPAA, PCI DSS, FedRAMP, GDPR

```bash
# Example usage
azmp create vm-solution --compliance=cis-level1
azmp create vm-solution --compliance=nist-800-53
azmp create storage --compliance=azure-security-benchmark
```

 **[Full Proposal](docs/COMPLIANCE_PLUGIN_PROPOSAL.md)** - Detailed technical specifications and implementation roadmap

**Advanced Extensibility:**

- [ ] MCP (Model Context Protocol) server support
- [ ] Remote plugin loading from registries
- [ ] Plugin security scanning and verification
- [ ] Advanced plugin APIs and lifecycle management
- [ ] Plugin performance monitoring

**Storage Features:**

- [ ] Multi-region deployment support
- [ ] Geo-replication configuration
- [ ] Disaster recovery templates
- [ ] Advanced monitoring dashboards

> **Note:** See [PLUGIN_ARCHITECTURE.md](docs/PLUGIN_ARCHITECTURE.md) for detailed plugin development guide and [GitHub Wiki](https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azure-marketplace-generator/wiki) for roadmap updates.

## Contributing

Contributions are welcome! Please ensure:

1. All tests pass (`npm test`)
2. Code follows TypeScript and ESLint standards
3. Documentation is updated
4. Commit messages follow conventional commits

## Support

For issues, questions, or contributions:

- **Issues:** [GitHub Issues](https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azure-marketplace-generator/issues)
- **Discussions:** [GitHub Discussions](https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azure-marketplace-generator/discussions)
- **Wiki:** [GitHub Wiki](https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azure-marketplace-generator/wiki)

## License

MIT  Home & Office Improvements Ltd