@vertile-ai/iac 0.0.1 → 0.1.0

package/README.md

@@ -24,7 +24,7 @@ Terraform and can be used offline.
 ```bash
 vertile-iac render --target=all --env=production
 vertile-iac plan --target=vercel --env=preview
-vertile-iac apply --target=aws --env=production --yes
+vertile-iac apply --target=aws --deployment=prod --yes
 
 vertile-iac sync-env --repo-root ../noop --variants=local,staging,test
 vertile-iac env --repo-root ../noop --scope=all --targets=preview,production
@@ -34,6 +34,8 @@ vertile-iac domains --repo-root ../noop
 
 The `render`, `plan`, and `apply` commands read `infrastructure/iac/iac.json`
 and write generated Terraform workspaces to `.vertile/terraform/<target>/`.
+When `--deployment=<name>` maps to a provider deployment, the workspace is
+`.vertile/terraform/<target>/<deployment>/`.
 
 Apply is guarded. Non-interactive apply requires `--yes`, which passes
 Terraform `-auto-approve`.
@@ -55,12 +57,12 @@ The new Terraform flow expects the target project to have:
 
 ```text
 infrastructure/iac/iac.json
-infrastructure/shared/.env.development
-infrastructure/shared/.env.staging
-infrastructure/shared/.env.production
-infrastructure/<app-key>/.env.development
-infrastructure/<app-key>/.env.staging
-infrastructure/<app-key>/.env.production
+.vertile-iac/env/shared/.env.development
+.vertile-iac/env/shared/.env.staging
+.vertile-iac/env/shared/.env.production
+.vertile-iac/env/<app-key>/.env.development
+.vertile-iac/env/<app-key>/.env.staging
+.vertile-iac/env/<app-key>/.env.production
 ```
 
 Minimal `iac.json` example:
@@ -70,10 +72,26 @@ Minimal `iac.json` example:
   "$schema": "./node_modules/@vertile-ai/iac/schema/iac.schema.json",
   "version": 1,
   "project": { "name": "example" },
-  "environments": ["development", "preview", "production"],
+  "environments": ["development", "uat", "production"],
   "providers": {
     "vercel": { "team": "example-team" },
-    "aws": { "region": "us-east-1" },
+    "aws": {
+      "region": "us-east-1",
+      "deployments": {
+        "uat": {
+          "environment": "uat",
+          "region": "us-east-1",
+          "profile": "example-uat",
+          "tags": { "Stage": "uat" }
+        },
+        "prod": {
+          "environment": "production",
+          "region": "us-east-1",
+          "profile": "example-prod",
+          "tags": { "Stage": "prod" }
+        }
+      }
+    },
     "digitalocean": {}
   },
   "apps": [
@@ -86,7 +104,11 @@ Minimal `iac.json` example:
     }
   ],
   "env": {
-    "sourceDir": "infrastructure",
+    "environments": {
+      "development": { "files": [".env.development"] },
+      "uat": { "files": [".env.uat"] },
+      "production": { "files": [".env.production"] }
+    },
     "sync": {
       "apps": ["web"]
     }
@@ -109,16 +131,13 @@ Provider-specific Terraform resources can be added under
 `providers.<target>.resources` as `{ "type", "name", "values" }` objects while
 the manifest schema stays narrow.
 
-The compatibility Vercel commands expect the target project to have:
+Provider deployments map user-defined stage names such as `uat`, `nightly`, or
+`prod` to logical environments and provider-specific inputs. AWS uses deployment
+values for provider region/profile, generated workspace path, resource names,
+and default tags. The logical environment still controls env file selection.
 
-```text
-infrastructure/shared/.env.development
-infrastructure/shared/.env.staging
-infrastructure/shared/.env.production
-infrastructure/<project-key>/.env.development
-infrastructure/<project-key>/.env.staging
-infrastructure/<project-key>/.env.production
-```
+By default, Vercel env reconciliation reads `.env.*` files from
+`.vertile-iac/env/shared` and `.vertile-iac/env/<project-key>`.
 
 When the old compatibility files exist, they are used directly:
 
@@ -132,26 +151,28 @@ When they do not exist, the Vercel commands derive equivalent manifests from
 `iac.json`:
 
 - `providers.vercel.teamSlug` or `providers.vercel.team` becomes the Vercel team.
-- `env.sourceDir` selects the env source folder and defaults to `infrastructure`.
+- `env.sourceDir` selects the env source folder and defaults to `.vertile-iac/env`.
+- `env.environments.<name>.files` maps logical environments to ordered env files.
 - `apps[].key`, `apps[].id` or `apps[].projectId`, and `apps[].name` become managed Vercel projects.
 - `apps[].rootDirectory`, `apps[].nodeVersion`, and
   `apps[].enableAffectedProjectsDeployments` become project settings.
 - `apps[].domains` and top-level `domains[]` become project domains.
 
-Vercel targets map to env files as follows:
+Vercel targets map to logical environments as follows by default:
 
-- `development` -> `.env.development`
-- `preview` -> `.env.staging`
-- `production` -> `.env.production`
+- `development` -> `development`
+- `preview` -> `staging`
+- `production` -> `production`
 
-Pure local env files such as `.env.local` are intentionally not synced to
-Vercel. The default manifest location can be overridden:
+Those logical environments then resolve through `env.environments`. For example,
+`staging` defaults to `.env.staging`, but can be configured as
+`"staging": { "files": [".env.preview", ".env.staging"] }`.
+The default manifest location can be overridden:
 
 ```bash
 vertile-iac env \
   --repo-root ../some-project \
-  --manifest ./deploy/env-manifest.json \
-  --infra-dir infrastructure
+  --manifest ./deploy/env-manifest.json
 ```
 
 ## Env File Sync
@@ -162,13 +183,17 @@ which reconciles Vercel remote environment variables.
 
 The boundary is:
 
-- `env.sourceDir` is the source tree, defaulting to `infrastructure`.
+- `env.sourceDir` is the source tree, defaulting to `.vertile-iac/env`.
+- `env.environments.<name>.files` declares ordered source files for any logical
+  environment, including custom names such as `uat`, `nightly`, or `qa`.
 - `env.sync.sharedKey` is the shared source folder, defaulting to `shared`.
 - `env.sync.apps` limits which `apps[]` are materialized locally. Without it,
   all apps are synced.
 - Each app reads from `<env.sourceDir>/<app.key>` by default.
 - Each app writes into `apps[].rootDirectory` by default.
 - `apps[].env.sourceKey` and `apps[].env.outputDir` override those defaults.
+- When the same key exists in shared and app-specific files, the app-specific
+  value wins in generated package `.env.*` files.
 - `apps[].env.sharedPrefix` projects prefixed shared keys into one app, strips
   the prefix in that app's generated file, and keeps those prefixed keys out of
   other generated app env files.
@@ -178,7 +203,6 @@ Examples:
 ```json
 {
   "env": {
-    "sourceDir": "infrastructure",
     "sync": {
       "apps": ["landing", "web-client", "web-server"],
       "sharedKey": "shared"
@@ -194,8 +218,9 @@ Examples:
 }
 ```
 
-Supported local sync variants are `local`, `staging`, `preview`, `production`,
-and `test`. `preview` is an alias for `.env.staging`.
+Built-in local sync variants are `local`, `staging`, `preview`, `production`,
+and `test`. Custom variants declared in `env.environments` can also be selected
+with `--variants`, such as `--variants=uat,nightly`.
 
 ## Shared Options
 
@@ -204,7 +229,6 @@ and `test`. `preview` is an alias for `.env.staging`.
 - `--manifest <path>`: env manifest path.
 - `--project-settings <path>`: project settings manifest path.
 - `--project-domains <path>`: project domains manifest path.
-- `--infra-dir <path>`: override `env-manifest.json` `infraDir`.
 - `--token-file <path>`: token file, default `<repo-root>/.vercel.token`.
 - `--auto-create-keys <a,b>`: project keys allowed for Vercel auto-create.
 - `--auto-create-prefixes <a,b>`: project key prefixes allowed for Vercel auto-create.
@@ -212,6 +236,7 @@ and `test`. `preview` is an alias for `.env.staging`.
 - `--out <path>`: generated Terraform root, default `.vertile/terraform`.
 - `--target <name|all>`: `vercel`, `aws`, `digitalocean`, or `all`.
 - `--env <name>`: environment to render, plan, or apply, default `production`.
+- `--deployment <name>`: provider deployment/stage name, such as `uat` or `prod`.
 - `--terraform-bin <path>`: Terraform executable for `plan`, default `terraform`.
 - `--yes`: allow non-interactive `apply` with Terraform auto-approve.
 
@@ -225,10 +250,21 @@ docs/index.html
 
 ## Examples
 
-`examples/dynomic` is a publishable fixture project that shows the current app
-shape for Vercel project settings, domains, preview/production env
-provisioning, local package env sync, portable resource concepts, provider
-overrides, and provider-specific escape hatch resources.
+The `examples/` directory uses runtime-oriented fixture names so each project
+shape is clear at a glance:
+
+- `examples/node-api`
+- `examples/bun-hono-api`
+- `examples/react-spa`
+- `examples/next-monorepo`
+- `examples/sveltekit-web`
+- `examples/python-fastapi-api`
+- `examples/go-api`
+
+Every example keeps a portable `infrastructure/iac/iac.json`. Examples with
+provider-specific fields also include standalone provider variants such as
+`iac.aws.json`, `iac.vercel.json`, or `iac.do.json` that can be passed with
+`--iac-manifest`.
 
 ## Schema
 

package/docs/README.md

@@ -27,6 +27,7 @@ Generated Terraform lives under:
 
 ```text
 .vertile/terraform/<provider>/
+.vertile/terraform/<provider>/<deployment>/
 ```
 
 Users edit the manifest. Vertile AI IaC renders provider-specific infrastructure.
@@ -35,6 +36,6 @@ Users edit the manifest. Vertile AI IaC renders provider-specific infrastructure
 
 ```bash
 vertile-iac render --target=all --env=production
-vertile-iac plan --target=aws --env=production
-vertile-iac apply --target=aws --env=production --yes
+vertile-iac plan --target=aws --deployment=prod
+vertile-iac apply --target=aws --deployment=prod --yes
 ```

package/docs/index.html

@@ -264,8 +264,8 @@
         <p>Crossplane makes Kubernetes the infrastructure control plane. Vertile AI IaC uses a Git repo and CLI as the control surface, which is lighter for solo builders and app-first teams.</p>
         <pre><code>pnpm add -D @vertile-ai/iac
 vertile-iac render --target=all --env=production
-vertile-iac plan --target=aws --env=production
-vertile-iac apply --target=aws --env=production --yes</code></pre>
+vertile-iac plan --target=aws --deployment=prod
+vertile-iac apply --target=aws --deployment=prod --yes</code></pre>
       </section>
     </main>
 

package/docs/manifest.md

@@ -12,6 +12,7 @@ Generated Terraform is an implementation detail:
 .vertile/terraform/vercel/
 .vertile/terraform/aws/
 .vertile/terraform/digitalocean/
+.vertile/terraform/<provider>/<deployment>/
 ```
 
 ## Minimal Manifest
@@ -21,10 +22,26 @@ Generated Terraform is an implementation detail:
   "$schema": "./node_modules/@vertile-ai/iac/schema/iac.schema.json",
   "version": 1,
   "project": { "name": "example" },
-  "environments": ["development", "preview", "production"],
+  "environments": ["development", "uat", "production"],
   "providers": {
     "vercel": { "team": "example-team" },
-    "aws": { "region": "us-east-1" },
+    "aws": {
+      "region": "us-east-1",
+      "deployments": {
+        "uat": {
+          "environment": "uat",
+          "region": "us-east-1",
+          "profile": "example-uat",
+          "tags": { "Stage": "uat" }
+        },
+        "prod": {
+          "environment": "production",
+          "region": "us-east-1",
+          "profile": "example-prod",
+          "tags": { "Stage": "prod" }
+        }
+      }
+    },
     "digitalocean": {}
   },
   "apps": [
@@ -41,7 +58,14 @@ Generated Terraform is an implementation detail:
   "databases": [{ "key": "appdb", "engine": "postgres" }],
   "queues": [{ "key": "jobs" }],
   "sandboxes": [{ "key": "runner" }],
-  "clusters": [{ "key": "workers", "size": 2 }]
+  "clusters": [{ "key": "workers", "size": 2 }],
+  "env": {
+    "environments": {
+      "development": { "files": [".env.development"] },
+      "uat": { "files": [".env.uat"] },
+      "production": { "files": [".env.production"] }
+    }
+  }
 }
 ```
 
@@ -94,6 +118,15 @@ Provider-specific Terraform resources can be expressed under
 Use this as a bridge, not as the primary authoring model. The long-term goal is
 to promote common patterns into first-class portable concepts.
 
+## Environments And Deployments
+
+Logical environments control env file selection. By default, env sources live in
+`.vertile-iac/env/shared` and `.vertile-iac/env/<app-key>`.
+
+Provider deployments map stage names such as `uat` or `prod` to a logical
+environment plus provider-specific inputs. AWS uses deployment values for
+region/profile, generated workspace path, resource names, and default tags.
+
 ## Supported Concepts
 
 | Concept | Vercel | AWS | DigitalOcean |
@@ -120,11 +153,11 @@ vertile-iac render --target=all --env=production
 Preview changes with Terraform:
 
 ```bash
-vertile-iac plan --target=aws --env=production
+vertile-iac plan --target=aws --deployment=prod
 ```
 
 Apply changes with explicit non-interactive approval:
 
 ```bash
-vertile-iac apply --target=aws --env=production --yes
+vertile-iac apply --target=aws --deployment=prod --yes
 ```

package/examples/bun-hono-api/README.md

@@ -0,0 +1,9 @@
+# Bun Hono API
+
+Bun backend example using Hono-style project structure with an explicit
+DigitalOcean variant.
+
+```bash
+vertile-iac render --repo-root examples/bun-hono-api --target=all --deployment=prod
+vertile-iac render --repo-root examples/bun-hono-api --iac-manifest infrastructure/iac/iac.do.json --target=digitalocean --env=production
+```

package/examples/bun-hono-api/infrastructure/iac/iac.do.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "../../../../schema/iac.schema.json",
+  "version": 1,
+  "project": {
+    "key": "bun-hono-api",
+    "name": "bun-hono-api"
+  },
+  "environments": [
+    "development",
+    "test",
+    "uat",
+    "nightly",
+    "staging",
+    "preview",
+    "production"
+  ],
+  "providers": {
+    "digitalocean": {
+      "region": "sfo3",
+      "resources": [
+        {
+          "type": "digitalocean_project",
+          "name": "main",
+          "values": {
+            "name": "bun-hono-api"
+          }
+        }
+      ]
+    }
+  },
+  "apps": [
+    {
+      "key": "api",
+      "name": "bun-hono-api",
+      "framework": "bun",
+      "rootDirectory": "."
+    }
+  ],
+  "databases": [
+    {
+      "key": "appdb",
+      "engine": "postgres",
+      "providers": {
+        "digitalocean": {
+          "engine": "pg",
+          "version": "16",
+          "size": "db-s-1vcpu-1gb",
+          "nodeCount": 1
+        }
+      }
+    }
+  ],
+  "env": {
+    "environments": {
+      "development": {
+        "files": [
+          ".env.development"
+        ]
+      },
+      "test": {
+        "files": [
+          ".env.test"
+        ]
+      },
+      "uat": {
+        "files": [
+          ".env.uat"
+        ]
+      },
+      "nightly": {
+        "files": [
+          ".env.nightly"
+        ]
+      },
+      "staging": {
+        "files": [
+          ".env.staging"
+        ]
+      },
+      "production": {
+        "files": [
+          ".env.production"
+        ]
+      }
+    }
+  }
+}

package/examples/bun-hono-api/infrastructure/iac/iac.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "../../../../schema/iac.schema.json",
+  "version": 1,
+  "project": {
+    "key": "bun-hono-api",
+    "name": "bun-hono-api"
+  },
+  "environments": [
+    "development",
+    "test",
+    "uat",
+    "nightly",
+    "staging",
+    "preview",
+    "production"
+  ],
+  "providers": {
+    "aws": {
+      "region": "us-west-2",
+      "deployments": {
+        "dev": {
+          "environment": "development",
+          "region": "us-west-2",
+          "profile": "bun-hono-api-dev",
+          "tags": {
+            "Stage": "dev"
+          }
+        },
+        "uat": {
+          "environment": "uat",
+          "region": "us-west-2",
+          "profile": "bun-hono-api-uat",
+          "tags": {
+            "Stage": "uat"
+          }
+        },
+        "nightly": {
+          "environment": "nightly",
+          "region": "us-west-2",
+          "profile": "bun-hono-api-nightly",
+          "tags": {
+            "Stage": "nightly"
+          }
+        },
+        "prod": {
+          "environment": "production",
+          "region": "us-west-2",
+          "profile": "bun-hono-api-prod",
+          "tags": {
+            "Stage": "prod"
+          }
+        }
+      }
+    },
+    "digitalocean": {
+      "region": "sfo3"
+    }
+  },
+  "apps": [
+    {
+      "key": "api",
+      "name": "bun-hono-api",
+      "framework": "bun",
+      "rootDirectory": "."
+    }
+  ],
+  "databases": [
+    {
+      "key": "appdb",
+      "engine": "postgres"
+    }
+  ],
+  "env": {
+    "environments": {
+      "development": {
+        "files": [
+          ".env.development"
+        ]
+      },
+      "test": {
+        "files": [
+          ".env.test"
+        ]
+      },
+      "uat": {
+        "files": [
+          ".env.uat"
+        ]
+      },
+      "nightly": {
+        "files": [
+          ".env.nightly"
+        ]
+      },
+      "staging": {
+        "files": [
+          ".env.staging"
+        ]
+      },
+      "production": {
+        "files": [
+          ".env.production"
+        ]
+      }
+    }
+  }
+}

package/examples/bun-hono-api/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "bun-hono-api",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "iac:render": "vertile-iac render --repo-root . --target=all --deployment=prod"
+  },
+  "dependencies": {
+    "hono": "^4.0.0"
+  },
+  "devDependencies": {
+    "@vertile-ai/iac": "0.1.0"
+  }
+}

package/examples/bun-hono-api/src/index.ts

@@ -0,0 +1,7 @@
+import { Hono } from 'hono'
+
+const app = new Hono()
+
+app.get('/health', (context) => context.json({ ok: true, runtime: 'bun' }))
+
+export default app

package/examples/go-api/README.md

@@ -0,0 +1,8 @@
+# Go API
+
+Go HTTP backend example with AWS and DigitalOcean targets.
+
+```bash
+vertile-iac render --repo-root examples/go-api --target=all --deployment=prod
+vertile-iac render --repo-root examples/go-api --iac-manifest infrastructure/iac/iac.do.json --target=digitalocean --env=production
+```

package/examples/go-api/cmd/server/main.go

@@ -0,0 +1,16 @@
+package main
+
+import (
+	"encoding/json"
+	"net/http"
+)
+
+func main() {
+	http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"ok":      true,
+			"runtime": "go",
+		})
+	})
+	_ = http.ListenAndServe(":3000", nil)
+}

package/examples/go-api/go.mod

@@ -0,0 +1,3 @@
+module example.com/go-api
+
+go 1.24

package/examples/go-api/infrastructure/iac/iac.do.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "../../../../schema/iac.schema.json",
+  "version": 1,
+  "project": {
+    "key": "go-api",
+    "name": "go-api"
+  },
+  "environments": [
+    "development",
+    "test",
+    "uat",
+    "nightly",
+    "staging",
+    "preview",
+    "production"
+  ],
+  "providers": {
+    "digitalocean": {
+      "region": "nyc3",
+      "resources": [
+        {
+          "type": "digitalocean_project",
+          "name": "main",
+          "values": {
+            "name": "go-api"
+          }
+        }
+      ]
+    }
+  },
+  "apps": [
+    {
+      "key": "api",
+      "name": "go-api",
+      "framework": "go",
+      "rootDirectory": "."
+    }
+  ],
+  "queues": [
+    {
+      "key": "jobs"
+    }
+  ],
+  "clusters": [
+    {
+      "key": "workers",
+      "size": 2,
+      "providers": {
+        "digitalocean": {
+          "nodes": 2,
+          "sizeSlug": "s-1vcpu-1gb"
+        }
+      }
+    }
+  ],
+  "env": {
+    "environments": {
+      "development": {
+        "files": [
+          ".env.development"
+        ]
+      },
+      "test": {
+        "files": [
+          ".env.test"
+        ]
+      },
+      "uat": {
+        "files": [
+          ".env.uat"
+        ]
+      },
+      "nightly": {
+        "files": [
+          ".env.nightly"
+        ]
+      },
+      "staging": {
+        "files": [
+          ".env.staging"
+        ]
+      },
+      "production": {
+        "files": [
+          ".env.production"
+        ]
+      }
+    }
+  }
+}