@znemz/cfn-include 4.3.1 → 4.4.0

package/INSTALL.md

@@ -0,0 +1,117 @@
+# Installation Guide — Executable YAML
+
+## Quick Start
+
+```bash
+npm install -g @znemz/cfn-include
+```
+
+That's it! The `cfn`, `yml`, and `yaml` commands are now available globally.
+
+## What Gets Installed
+
+npm automatically creates symlinks in your PATH for:
+- `cfn` → executable YAML wrapper
+- `yml` → alias to cfn
+- `yaml` → alias to cfn
+- `cfn-include` → original CLI
+
+## Verify Installation
+
+```bash
+which cfn yml yaml
+# Should show paths like:
+# /usr/local/bin/cfn
+# /usr/local/bin/yml
+# /usr/local/bin/yaml
+```
+
+## Make Your First Executable Template
+
+```bash
+# Create a template
+cat > my-stack.yaml << 'TEMPLATE'
+#!/usr/bin/env yaml
+Resources:
+  Bucket:
+    Type: AWS::S3::Bucket
+TEMPLATE
+
+# Make it executable
+chmod +x my-stack.yaml
+
+# Run it!
+./my-stack.yaml              # Preview
+./my-stack.yaml --deploy     # Deploy to AWS
+```
+
+## Troubleshooting
+
+### "command not found: cfn"
+
+**Cause:** npm bin directory not in PATH
+
+**Fix:**
+```bash
+# Find npm bin directory
+npm bin -g
+# Example output: /usr/local/bin
+
+# Add to PATH (in ~/.zshrc or ~/.bashrc)
+export PATH="$(npm bin -g):$PATH"
+```
+
+### "./my-stack.yaml: bad interpreter: /usr/bin/env: cfn: No such file or directory"
+
+**Cause:** npm global install location not in PATH, or cfn not executable
+
+**Fix:**
+```bash
+# Reinstall globally
+npm install -g @znemz/cfn-include
+
+# Verify cfn is executable
+ls -la $(npm bin -g)/cfn
+
+# Should show: lrwxr-xr-x ... /usr/local/bin/cfn -> ../lib/node_modules/@znemz/cfn-include/bin/cfn
+```
+
+### Windows Support
+
+Shebang (`#!`) is Unix/Linux/macOS only. On Windows:
+
+**Option 1: WSL (Recommended)**
+```bash
+# Install in WSL
+npm install -g @znemz/cfn-include
+
+# Executable YAML works normally
+chmod +x template.yaml
+./template.yaml --deploy
+```
+
+**Option 2: Direct CLI**
+```bash
+# Use cfn-include directly (no shebang)
+cfn-include template.yaml --deploy
+```
+
+## Examples
+
+See `examples/` directory:
+- `executable-simple.yaml` — Basic S3 bucket
+- `executable-template.yaml` — Full auto-scaling web stack
+
+Both are ready to run:
+```bash
+cd examples
+./executable-simple.yaml
+```
+
+## Uninstall
+
+```bash
+npm uninstall -g @znemz/cfn-include
+```
+
+This removes all bin symlinks automatically.

package/bin/cfn

@@ -0,0 +1,112 @@
+#!/bin/bash
+# cfn - Execute CloudFormation templates with cfn-include preprocessing
+# Makes CloudFormation templates directly executable via shebang
+set -eo pipefail
+
+# Find cfn-include - try local dist first, then PATH
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "${SCRIPT_DIR}/../dist/cli.js" ]; then
+    # Local installation (development or npm install in project)
+    CFN_INCLUDE="${SCRIPT_DIR}/../dist/cli.js"
+    USE_NODE=true
+elif command -v cfn-include &> /dev/null; then
+    # Global installation (npm install -g)
+    CFN_INCLUDE="cfn-include"
+    USE_NODE=false
+else
+    echo "Error: cfn-include not found. Install with: npm install -g @znemz/cfn-include" >&2
+    exit 1
+fi
+
+TEMPLATE="$1"
+
+if [ -z "$TEMPLATE" ]; then
+    echo "Usage: cfn <template.yaml> [options]" >&2
+    echo "" >&2
+    echo "Options:" >&2
+    echo "  --deploy              Deploy to AWS after processing" >&2
+    echo "  --stack-name <name>   Override stack name (default: filename)" >&2
+    echo "  --profile <profile>   AWS profile to use" >&2
+    echo "  --region <region>     AWS region" >&2
+    echo "" >&2
+    echo "Environment:" >&2
+    echo "  STACK_NAME           Override stack name" >&2
+    echo "  AWS_PROFILE          AWS profile" >&2
+    echo "  AWS_REGION           AWS region" >&2
+    exit 1
+fi
+
+# Shift past the template argument
+shift
+
+# Parse arguments
+DEPLOY=false
+STACK_NAME=""
+AWS_ARGS=()
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --deploy)
+            DEPLOY=true
+            shift
+            ;;
+        --stack-name)
+            STACK_NAME="$2"
+            shift 2
+            ;;
+        --profile)
+            AWS_ARGS+=(--profile "$2")
+            shift 2
+            ;;
+        --region)
+            AWS_ARGS+=(--region "$2")
+            shift 2
+            ;;
+        *)
+            # Pass through to cfn-include
+            CFN_ARGS+=("$1")
+            shift
+            ;;
+    esac
+done
+
+# Process with cfn-include
+OUTPUT=$(mktemp -t cfn-exec.XXXXXX.json)
+trap "rm -f '$OUTPUT'" EXIT
+
+if [ "$USE_NODE" = true ]; then
+    # Local installation - use node to run the script
+    if ! node "$CFN_INCLUDE" "$TEMPLATE" -o "$OUTPUT" "${CFN_ARGS[@]}"; then
+        echo "❌ cfn-include processing failed" >&2
+        exit 1
+    fi
+else
+    # Global installation - use cfn-include command
+    if ! "$CFN_INCLUDE" "$TEMPLATE" -o "$OUTPUT" "${CFN_ARGS[@]}"; then
+        echo "❌ cfn-include processing failed" >&2
+        exit 1
+    fi
+fi
+
+# If not deploying, just print processed template
+if [ "$DEPLOY" = false ]; then
+    cat "$OUTPUT"
+    exit 0
+fi
+
+# Determine stack name
+if [ -z "$STACK_NAME" ]; then
+    STACK_NAME=$(basename "$TEMPLATE" .yaml)
+    STACK_NAME=$(basename "$STACK_NAME" .yml)
+fi
+
+echo "🚀 Deploying stack: $STACK_NAME" >&2
+
+# Deploy to AWS
+aws cloudformation deploy \
+    --template-file "$OUTPUT" \
+    --stack-name "$STACK_NAME" \
+    --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND \
+    "${AWS_ARGS[@]}"
+
+echo "✅ Stack deployed: $STACK_NAME" >&2

package/package.json

@@ -1,12 +1,18 @@
 {
   "name": "@znemz/cfn-include",
-  "version": "4.3.1",
+  "version": "4.4.0",
   "description": "Preprocessor for CloudFormation templates with support for loops and flexible include statements",
   "keywords": [
     "aws",
     "cfn",
     "cloudformation",
-    "include"
+    "include",
+    "executable-yaml",
+    "shebang",
+    "yaml",
+    "preprocessor",
+    "devops-tools",
+    "infrastructure-as-code"
   ],
   "homepage": "https://github.com/brickhouse-tech/cfn-include#readme",
   "bugs": {
@@ -35,15 +41,22 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "cfn-include": "./dist/cli.js"
+    "cfn": "./bin/cfn",
+    "cfn-include": "./dist/cli.js",
+    "yaml": "./bin/yaml",
+    "yml": "./bin/yml"
   },
   "files": [
-    "dist/"
+    "dist/",
+    "bin/",
+    "scripts/postinstall.js",
+    "INSTALL.md"
   ],
   "scripts": {
     "better-audit": "better-npm-audit audit",
     "build": "tsc",
     "build:clean": "rm -rf dist && npm run build",
+    "postinstall": "node scripts/postinstall.js",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "prepare": "sort-package-json",

package/scripts/postinstall.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// Post-install message for executable YAML feature
+
+const isGlobalInstall = process.env.npm_config_global === 'true';
+
+if (isGlobalInstall) {
+  console.log('\n✨ cfn-include installed successfully!\n');
+  console.log('🔥 NEW: Executable YAML support is now available!\n');
+  console.log('Three shebang options to choose from:');
+  console.log('  #!/usr/bin/env cfn   (CloudFormation-specific)');
+  console.log('  #!/usr/bin/env yml   (short & clean)');
+  console.log('  #!/usr/bin/env yaml  (explicit)\n');
+  console.log('Quick start:');
+  console.log('  1. Add shebang to your template: #!/usr/bin/env yaml');
+  console.log('  2. Make it executable: chmod +x template.yaml');
+  console.log('  3. Run it: ./template.yaml --deploy\n');
+  console.log('📚 Full guide: https://github.com/brickhouse-tech/cfn-include#executable-yaml\n');
+}