provisioning/docs/src/infrastructure/infrastructure-from-code-guide.md

# Infrastructure-from-Code (IaC) Guide

## Overview

The Infrastructure-from-Code system automatically detects technologies in your project and infers infrastructure requirements based on organization-specific rules. It consists of three main commands:

- **detect**: Scan a project and identify technologies
- **complete**: Analyze gaps and recommend infrastructure components
- **ifc**: Full-pipeline orchestration (workflow)

## Quick Start

### 1. Detect Technologies in Your Project

Scan a project directory for detected technologies:

```bash
provisioning detect /path/to/project --out json
```plaintext

**Output Example:**

```json
{
  "detections": [
    {"technology": "nodejs", "confidence": 0.95},
    {"technology": "postgres", "confidence": 0.92}
  ],
  "overall_confidence": 0.93
}
```plaintext

### 2. Analyze Infrastructure Gaps

Get a completeness assessment and recommendations:

```bash
provisioning complete /path/to/project --out json
```plaintext

**Output Example:**

```json
{
  "completeness": 1.0,
  "changes_needed": 2,
  "is_safe": true,
  "change_summary": "+ Adding: postgres-backup, pg-monitoring"
}
```plaintext

### 3. Run Full Workflow

Orchestrate detection → completion → assessment pipeline:

```bash
provisioning ifc /path/to/project --org default
```plaintext

**Output:**

```plaintext
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔄 Infrastructure-from-Code Workflow
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

STEP 1: Technology Detection
────────────────────────────
✓ Detected 2 technologies

STEP 2: Infrastructure Completion
─────────────────────────────────
✓ Completeness: 1%

✅ Workflow Complete
```plaintext

## Command Reference

### detect

Scan and detect technologies in a project.

**Usage:**

```bash
provisioning detect [PATH] [OPTIONS]
```plaintext

**Arguments:**

- `PATH`: Project directory to analyze (default: current directory)

**Options:**

- `-o, --out TEXT`: Output format - `text`, `json`, `yaml` (default: `text`)
- `-C, --high-confidence-only`: Only show detections with confidence > 0.8
- `--pretty`: Pretty-print JSON/YAML output
- `-x, --debug`: Enable debug output

**Examples:**

```bash
# Detect with default text output
provisioning detect /path/to/project

# Get JSON output for parsing
provisioning detect /path/to/project --out json | jq '.detections'

# Show only high-confidence detections
provisioning detect /path/to/project --high-confidence-only

# Pretty-printed YAML output
provisioning detect /path/to/project --out yaml --pretty
```plaintext

### complete

Analyze infrastructure completeness and recommend changes.

**Usage:**

```bash
provisioning complete [PATH] [OPTIONS]
```plaintext

**Arguments:**

- `PATH`: Project directory to analyze (default: current directory)

**Options:**

- `-o, --out TEXT`: Output format - `text`, `json`, `yaml` (default: `text`)
- `-c, --check`: Check mode (report only, no changes)
- `--pretty`: Pretty-print JSON/YAML output
- `-x, --debug`: Enable debug output

**Examples:**

```bash
# Analyze completeness
provisioning complete /path/to/project

# Get detailed JSON report
provisioning complete /path/to/project --out json

# Check mode (dry-run, no changes)
provisioning complete /path/to/project --check
```plaintext

### ifc (workflow)

Run the full Infrastructure-from-Code pipeline.

**Usage:**

```bash
provisioning ifc [PATH] [OPTIONS]
```plaintext

**Arguments:**

- `PATH`: Project directory to process (default: current directory)

**Options:**

- `--org TEXT`: Organization name for rule loading (default: `default`)
- `-o, --out TEXT`: Output format - `text`, `json` (default: `text`)
- `--apply`: Apply recommendations (future feature)
- `-v, --verbose`: Verbose output with timing
- `--pretty`: Pretty-print output
- `-x, --debug`: Enable debug output

**Examples:**

```bash
# Run workflow with default rules
provisioning ifc /path/to/project

# Run with organization-specific rules
provisioning ifc /path/to/project --org acme-corp

# Verbose output with timing
provisioning ifc /path/to/project --verbose

# JSON output for automation
provisioning ifc /path/to/project --out json
```plaintext

## Organization-Specific Inference Rules

Customize how infrastructure is inferred for your organization.

### Understanding Inference Rules

An inference rule tells the system: "If we detect technology X, we should recommend taskservice Y."

**Rule Structure:**

```yaml
version: "1.0.0"
organization: "your-org"
rules:
  - name: "rule-name"
    technology: ["detected-tech"]
    infers: "required-taskserv"
    confidence: 0.85
    reason: "Why this taskserv is needed"
    required: true
```plaintext

### Creating Custom Rules

Create an organization-specific rules file:

```bash
# ACME Corporation rules
cat > $PROVISIONING/config/inference-rules/acme-corp.yaml << 'EOF'
version: "1.0.0"
organization: "acme-corp"
description: "ACME Corporation infrastructure standards"

rules:
  - name: "nodejs-to-redis"
    technology: ["nodejs", "express"]
    infers: "redis"
    confidence: 0.85
    reason: "Node.js applications need caching"
    required: false

  - name: "postgres-to-backup"
    technology: ["postgres"]
    infers: "postgres-backup"
    confidence: 0.95
    reason: "All databases require backup strategy"
    required: true

  - name: "all-services-monitoring"
    technology: ["nodejs", "python", "postgres"]
    infers: "monitoring"
    confidence: 0.90
    reason: "ACME requires monitoring on production services"
    required: true
EOF
```plaintext

Then use them:

```bash
provisioning ifc /path/to/project --org acme-corp
```plaintext

### Default Rules

If no organization rules are found, the system uses sensible defaults:

- Node.js + Express → Redis (caching)
- Node.js → Nginx (reverse proxy)
- Database → Backup (data protection)
- Docker → Kubernetes (orchestration)
- Python → Gunicorn (WSGI server)
- PostgreSQL → Monitoring (production safety)

## Output Formats

### Text Output (Default)

Human-readable format with visual indicators:

```plaintext
STEP 1: Technology Detection
────────────────────────────
✓ Detected 2 technologies

STEP 2: Infrastructure Completion
─────────────────────────────────
✓ Completeness: 1%
```plaintext

### JSON Output

Structured format for automation and parsing:

```bash
provisioning detect /path/to/project --out json | jq '.detections[0]'
```plaintext

Output:

```json
{
  "technology": "nodejs",
  "confidence": 0.8333333134651184,
  "evidence_count": 1
}
```plaintext

### YAML Output

Alternative structured format:

```bash
provisioning detect /path/to/project --out yaml
```plaintext

## Practical Examples

### Example 1: Node.js + PostgreSQL Project

```bash
# Step 1: Detect
$ provisioning detect my-app
✓ Detected: nodejs, express, postgres, docker

# Step 2: Complete
$ provisioning complete my-app
✓ Changes needed: 3
  - redis (caching)
  - nginx (reverse proxy)
  - pg-backup (database backup)

# Step 3: Full workflow
$ provisioning ifc my-app --org acme-corp
```plaintext

### Example 2: Python Django Project

```bash
$ provisioning detect django-app --out json
{
  "detections": [
    {"technology": "python", "confidence": 0.95},
    {"technology": "django", "confidence": 0.92}
  ]
}

# Inferred requirements (with gunicorn, monitoring, backup)
```plaintext

### Example 3: Microservices Architecture

```bash
$ provisioning ifc microservices/ --org mycompany --verbose
🔍 Processing microservices/
  - service-a: nodejs + postgres
  - service-b: python + redis
  - service-c: go + mongodb

✓ Detected common patterns
✓ Applied 12 inference rules
✓ Generated deployment plan
```plaintext

## Integration with Automation

### CI/CD Pipeline Example

```bash
#!/bin/bash
# Check infrastructure completeness in CI/CD

PROJECT_PATH=${1:-.}
COMPLETENESS=$(provisioning complete $PROJECT_PATH --out json | jq '.completeness')

if (( $(echo "$COMPLETENESS < 0.9" | bc -l) )); then
    echo "❌ Infrastructure completeness too low: $COMPLETENESS"
    exit 1
fi

echo "✅ Infrastructure is complete: $COMPLETENESS"
```plaintext

### Configuration as Code Integration

```bash
# Generate JSON for infrastructure config
provisioning detect /path/to/project --out json > infra-report.json

# Use in your config processing
cat infra-report.json | jq '.detections[]' | while read -r tech; do
    echo "Processing technology: $tech"
done
```plaintext

## Troubleshooting

### "Detector binary not found"

**Solution:** Ensure the provisioning project is properly built:

```bash
cd $PROVISIONING/platform
cargo build --release --bin provisioning-detector
```plaintext

### No technologies detected

**Check:**

1. Project path is correct: `provisioning detect /actual/path`
2. Project contains recognizable technologies (package.json, Dockerfile, requirements.txt, etc.)
3. Use `--debug` flag for more details: `provisioning detect /path --debug`

### Organization rules not being applied

**Check:**

1. Rules file exists: `$PROVISIONING/config/inference-rules/{org}.yaml`
2. Organization name is correct: `provisioning ifc /path --org myorg`
3. Verify rules structure with: `cat $PROVISIONING/config/inference-rules/myorg.yaml`

## Advanced Usage

### Custom Rule Template

Generate a template for a new organization:

```bash
# Template will be created with proper structure
provisioning rules create --org neworg
```plaintext

### Validate Rule Files

```bash
# Check for syntax errors
provisioning rules validate /path/to/rules.yaml
```plaintext

### Export Rules for Integration

Export as Rust code for embedding:

```bash
provisioning rules export myorg --format rust > rules.rs
```plaintext

## Best Practices

1. **Organize by Organization**: Keep separate rules for different organizations
2. **High Confidence First**: Start with rules you're confident about (confidence > 0.8)
3. **Document Reasons**: Always fill in the `reason` field for maintainability
4. **Test Locally**: Run on sample projects before applying organization-wide
5. **Version Control**: Commit inference rules to version control
6. **Review Changes**: Always inspect recommendations with `--check` first

## Related Commands

```bash
# View available taskservs that can be inferred
provisioning taskserv list

# Create inferred infrastructure
provisioning taskserv create {inferred-name}

# View current configuration
provisioning env | grep PROVISIONING
```plaintext

## Support and Documentation

- **Full CLI Help**: `provisioning help`
- **Specific Command Help**: `provisioning help detect`
- **Configuration Guide**: See `CONFIG_ENCRYPTION_GUIDE.md`
- **Task Services**: See `SERVICE_MANAGEMENT_GUIDE.md`

---

## Quick Reference

### 3-Step Workflow

```bash
# 1. Detect technologies
provisioning detect /path/to/project

# 2. Analyze infrastructure gaps
provisioning complete /path/to/project

# 3. Run full workflow (detect + complete)
provisioning ifc /path/to/project --org myorg
```plaintext

### Common Commands

| Task | Command |
|------|---------|
| **Detect technologies** | `provisioning detect /path` |
| **Get JSON output** | `provisioning detect /path --out json` |
| **Check completeness** | `provisioning complete /path` |
| **Dry-run (check mode)** | `provisioning complete /path --check` |
| **Full workflow** | `provisioning ifc /path --org myorg` |
| **Verbose output** | `provisioning ifc /path --verbose` |
| **Debug mode** | `provisioning detect /path --debug` |

### Output Formats

```bash
# Text (human-readable)
provisioning detect /path --out text

# JSON (for automation)
provisioning detect /path --out json | jq '.detections'

# YAML (for configuration)
provisioning detect /path --out yaml
```plaintext

### Organization Rules

#### Use Organization Rules

```bash
provisioning ifc /path --org acme-corp
```plaintext

#### Create Rules File

```bash
mkdir -p $PROVISIONING/config/inference-rules
cat > $PROVISIONING/config/inference-rules/myorg.yaml << 'EOF'
version: "1.0.0"
organization: "myorg"
rules:
  - name: "nodejs-to-redis"
    technology: ["nodejs"]
    infers: "redis"
    confidence: 0.85
    reason: "Caching layer"
    required: false
EOF
```plaintext

### Example: Node.js + PostgreSQL

```bash
$ provisioning detect myapp
✓ Detected: nodejs, postgres

$ provisioning complete myapp
✓ Changes: +redis, +nginx, +pg-backup

$ provisioning ifc myapp --org default
✓ Detection: 2 technologies
✓ Completion: recommended changes
✅ Workflow complete
```plaintext

### CI/CD Integration

```bash
#!/bin/bash
# Check infrastructure is complete before deploy
COMPLETENESS=$(provisioning complete . --out json | jq '.completeness')

if (( $(echo "$COMPLETENESS < 0.9" | bc -l) )); then
    echo "Infrastructure incomplete: $COMPLETENESS"
    exit 1
fi
```plaintext

### JSON Output Examples

#### Detect Output

```json
{
  "detections": [
    {"technology": "nodejs", "confidence": 0.95},
    {"technology": "postgres", "confidence": 0.92}
  ],
  "overall_confidence": 0.93
}
```plaintext

#### Complete Output

```json
{
  "completeness": 1.0,
  "changes_needed": 2,
  "is_safe": true,
  "change_summary": "+ redis, + monitoring"
}
```plaintext

### Flag Reference

| Flag | Short | Purpose |
|------|-------|---------|
| `--out TEXT` | `-o` | Output format: text, json, yaml |
| `--debug` | `-x` | Enable debug output |
| `--pretty` | | Pretty-print JSON/YAML |
| `--check` | `-c` | Dry-run (detect/complete) |
| `--org TEXT` | | Organization name (ifc) |
| `--verbose` | `-v` | Verbose output (ifc) |
| `--apply` | | Apply changes (ifc, future) |

### Troubleshooting

| Issue | Solution |
|-------|----------|
| "Detector binary not found" | `cd $PROVISIONING/platform && cargo build --release` |
| No technologies detected | Check file types (.py, .js, go.mod, package.json, etc.) |
| Organization rules not found | Verify file exists: `$PROVISIONING/config/inference-rules/{org}.yaml` |
| Invalid path error | Use absolute path: `provisioning detect /full/path` |

### Environment Variables

| Variable | Purpose |
|----------|---------|
| `$PROVISIONING` | Path to provisioning root |
| `$PROVISIONING_ORG` | Default organization (optional) |

### Default Inference Rules

- Node.js + Express → Redis (caching)
- Node.js → Nginx (reverse proxy)
- Database → Backup (data protection)
- Docker → Kubernetes (orchestration)
- Python → Gunicorn (WSGI)
- PostgreSQL → Monitoring (production)

### Useful Aliases

```bash
# Add to shell config
alias detect='provisioning detect'
alias complete='provisioning complete'
alias ifc='provisioning ifc'

# Usage
detect /my/project
complete /my/project
ifc /my/project --org myorg
```plaintext

### Tips & Tricks

**Parse JSON in bash:**

```bash
provisioning detect . --out json | \
  jq '.detections[] | .technology' | \
  sort | uniq
```plaintext

**Watch for changes:**

```bash
watch -n 5 'provisioning complete . --out json | jq ".completeness"'
```plaintext

**Generate reports:**

```bash
provisioning detect . --out yaml > detection-report.yaml
provisioning complete . --out yaml > completion-report.yaml
```plaintext

**Validate all organizations:**

```bash
for org in $PROVISIONING/config/inference-rules/*.yaml; do
    org_name=$(basename "$org" .yaml)
    echo "Testing $org_name..."
    provisioning ifc . --org "$org_name" --check
done
```plaintext

### Related Guides

- Full guide: `docs/user/INFRASTRUCTURE_FROM_CODE_GUIDE.md`
- Inference rules: `docs/user/INFRASTRUCTURE_FROM_CODE_GUIDE.md#organization-specific-inference-rules`
- Service management: `docs/user/SERVICE_MANAGEMENT_QUICKREF.md`
- Configuration: `docs/user/CONFIG_ENCRYPTION_QUICKREF.md`