📦 INSECTARIUM (terra-insectarium)

💡 What is Insectarium?

Insectarium is a modern, zero-runtime-dependency Infrastructure as Code (IaC) engine designed to orchestrate both native Terra ecosystem applications (terra_rolla_ball, terra_webbl_site, terra_combase_db, terra_maskito_stress) and industry multicloud providers (AWS, Azure, GCP, Cloudflare, GitHub) through a unified dependency graph.

Built as an open, portable alternative to rigid HCL workflows, Insectarium liberates developers with:

1. Multi-Syntax Freedom: Configure infrastructure seamlessly using JSON (biome.json), YAML (biome.yaml), HCL/Terraform (main.tf), or full programmatic TypeScript (biome.ts).
2. Portable Stacks ("Biomes"): Export, share, and import fully functional infrastructure architectures with cryptographic signatures and Zero-Leak Secret Masking.
3. The Vivarium (100% Local Web Console): A glassmorphic real-time visualizer running on localhost:4200 featuring interactive SVG DAG topology, deep property diffs, Biome Studio, and Drift monitors—cross-platform for Windows, Linux, and Android Termux.
4. $0 Remote State Native: Free distributed state storage in private GitHub vaults (.insectarium-storage) with atomic Git ref locking.
5. Triad of Shields:
   • Secret Masking: Sensitive tokens and passwords never leak in CLI outputs, logs, or Biome exports.
   • Transactional Auto-Rollback: Mid-flight provision failures automatically trigger reverse compensation to guarantee zero orphan resources.
   • Topological DAG Engine: Auto-detects dependencies and resolves concurrency tiers for maximum parallelization without cycles.

🚀 Quick Start

Installation

npm install -g terra-insectarium
# or locally
npm install terra-insectarium

1. Initialize a Biome

Create a starter infrastructure definition in your preferred syntax:

# JSON (default)
insectarium init --format json

# YAML
insectarium init --format yaml

# Terraform HCL
insectarium init --format hcl

# TypeScript
insectarium init --format ts

2. Preview Plan

Generate deep property diffs between desired configuration and live state:

insectarium plan --file biome.json

3. Apply Desired State

Materialize resources through the topological DAG with auto-rollback protection:

insectarium apply --file biome.json

4. Open "The Vivarium" Local Console

Launch the visual dashboard locally on any workstation, laptop, or mobile device via Termux:

insectarium console --port 4200

Open http://localhost:4200 in your browser to inspect the live SVG dependency graph and state diffs.

🧬 Biome Syntax Examples

JSON (biome.json)

{
  "name": "media-delivery-biome",
  "version": "1.0.0",
  "providers": {
    "terra": { "region": "local" },
    "aws": { "region": "us-east-1" }
  },
  "variables": {
    "api_key": { "type": "string", "sensitive": true }
  },
  "resources": {
    "terra_rolla_ball.media_vault": {
      "bucket": "global-video-vault",
      "encryption": "AES256"
    },
    "terra_webbl_site.frontend": {
      "domain": "portal.webbl.site",
      "ttl": 86400,
      "dependsOn": ["terra_rolla_ball.media_vault"]
    },
    "aws_s3_bucket.replica": {
      "bucket": "media-cold-storage"
    }
  }
}

YAML (biome.yaml)

name: media-delivery-biome
version: 1.0.0
providers:
  terra:
    region: local
resources:
  terra_rolla_ball.media_vault:
    bucket: global-video-vault
  terra_webbl_site.frontend:
    domain: portal.webbl.site
    dependsOn:
      - terra_rolla_ball.media_vault

Programmatic TypeScript (biome.ts)

import { BiomeBuilder } from 'terra-insectarium';

export const biome = new BiomeBuilder('media-delivery-biome')
  .addProvider('terra', { region: 'local' })
  .addVariable('db_pass', { type: 'string', sensitive: true })
  .addResource('terra_rolla_ball', 'media_vault', {
    bucket: 'global-video-vault'
  })
  .addResource('terra_webbl_site', 'frontend', {
    domain: 'portal.webbl.site'
  }, { dependsOn: ['terra_rolla_ball.media_vault'] })
  .build();

export default biome;

🛡️ Triad of Shields

| Shield | Mechanism | Benefit | | :--- | :--- | :--- | | Topological DAG Engine | Kahn algorithm + expression reference parser | High-speed parallel deployment tiers with cycle prevention | | Secret Masking | Dynamic pattern matching ((sensitive: hash)) | Zero-leak exports and leak-proof CLI stdout and state diffs | | Transactional Auto-Rollback | LIFO reverse compensation execution | Automatic cleanup and state restoration if an apply fails midway |

🔄 $0 Autonomous Drift Detection & Self-Healing

Generate a zero-cost GitHub Actions workflow that periodically inspects live infrastructure against recorded state:

insectarium drift workflow --output .github/workflows/insectarium-drift.yml

The sentinel workflow automatically identifies configuration drift and reapplies the desired state without manual intervention.

📱 Cross-Platform: Windows, Linux & Android Termux

Insectarium is 100% dependency-free and built on Node.js native primitives. It runs anywhere Node.js >= 18 is present, including on Android via Termux (pkg install nodejs && npm i -g terra-insectarium), allowing you to manage and visualize your cloud infrastructure directly on mobile and tablet devices locally.

📄 License

MIT © AMG Logicalis / Terra Ecosystem