@vertile-ai/iac 0.0.1

package/README.md

@@ -0,0 +1,255 @@
+# @vertile-ai/iac
+
+Opinionated infrastructure-as-code tooling.
+
+Install once, define infrastructure once, then run `vertile-iac plan` or
+guarded `vertile-iac apply` to manage Vercel, AWS, and DigitalOcean changes
+from the same IaC source of truth.
+
+Product repos keep their own manifests and env source files, while this package
+renders provider-specific Terraform workspaces and keeps the existing
+Vercel reconciliation flow available as compatibility commands.
+
+## Install
+
+```bash
+pnpm add -D @vertile-ai/iac
+```
+
+Terraform is required for `vertile-iac plan`. The `render` command does not call
+Terraform and can be used offline.
+
+## Commands
+
+```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 sync-env --repo-root ../noop --variants=local,staging,test
+vertile-iac env --repo-root ../noop --scope=all --targets=preview,production
+vertile-iac projects --repo-root ../noop
+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>/`.
+
+Apply is guarded. Non-interactive apply requires `--yes`, which passes
+Terraform `-auto-approve`.
+
+The `env`, `projects`, and `domains` commands reconcile Vercel through the
+Vercel API. They still read the older compatibility manifest files when those
+files exist, and otherwise derive the same desired state from
+`infrastructure/iac/iac.json`.
+
+Apply mode requires `VERCEL_TOKEN`, `VERCEL_API_KEY`, or a token file:
+
+```bash
+VERCEL_TOKEN=... vertile-iac env --repo-root ../noop --apply
+```
+
+## Manifest Layout
+
+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
+```
+
+Minimal `iac.json` example:
+
+```json
+{
+  "$schema": "./node_modules/@vertile-ai/iac/schema/iac.schema.json",
+  "version": 1,
+  "project": { "name": "example" },
+  "environments": ["development", "preview", "production"],
+  "providers": {
+    "vercel": { "team": "example-team" },
+    "aws": { "region": "us-east-1" },
+    "digitalocean": {}
+  },
+  "apps": [
+    {
+      "key": "web",
+      "name": "example-web",
+      "framework": "nextjs",
+      "rootDirectory": "apps/web",
+      "domains": ["web.example.com"]
+    }
+  ],
+  "env": {
+    "sourceDir": "infrastructure",
+    "sync": {
+      "apps": ["web"]
+    }
+  },
+  "domains": []
+}
+```
+
+Portable concepts currently include:
+
+- `apps`
+- `domains`
+- `objectStorage`
+- `databases`
+- `queues`
+- `sandboxes`
+- `clusters`
+
+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:
+
+```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
+```
+
+When the old compatibility files exist, they are used directly:
+
+```text
+infrastructure/iac/env-manifest.json
+infrastructure/iac/project-settings.json
+infrastructure/iac/project-domains.json
+```
+
+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`.
+- `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:
+
+- `development` -> `.env.development`
+- `preview` -> `.env.staging`
+- `production` -> `.env.production`
+
+Pure local env files such as `.env.local` are intentionally not synced to
+Vercel. The default manifest location can be overridden:
+
+```bash
+vertile-iac env \
+  --repo-root ../some-project \
+  --manifest ./deploy/env-manifest.json \
+  --infra-dir infrastructure
+```
+
+## Env File Sync
+
+`vertile-iac sync-env` generates package-local `.env.*` files from the env
+source tree declared by `iac.json`. This is separate from `vertile-iac env`,
+which reconciles Vercel remote environment variables.
+
+The boundary is:
+
+- `env.sourceDir` is the source tree, defaulting to `infrastructure`.
+- `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.
+- `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.
+
+Examples:
+
+```json
+{
+  "env": {
+    "sourceDir": "infrastructure",
+    "sync": {
+      "apps": ["landing", "web-client", "web-server"],
+      "sharedKey": "shared"
+    }
+  },
+  "apps": [
+    {
+      "key": "web-client",
+      "rootDirectory": "packages/web-client",
+      "env": { "sharedPrefix": "WEB_CLIENT_" }
+    }
+  ]
+}
+```
+
+Supported local sync variants are `local`, `staging`, `preview`, `production`,
+and `test`. `preview` is an alias for `.env.staging`.
+
+## Shared Options
+
+- `--repo-root <path>`: product repo root containing `infrastructure/`.
+- `--iac-dir <path>`: manifest directory, default `infrastructure/iac`.
+- `--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.
+- `--iac-manifest <path>`: source-of-truth IaC manifest, default `<iac-dir>/iac.json`.
+- `--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`.
+- `--terraform-bin <path>`: Terraform executable for `plan`, default `terraform`.
+- `--yes`: allow non-interactive `apply` with Terraform auto-approve.
+
+## Docs
+
+Public-facing docs live in `docs/`. The static docs website entrypoint is:
+
+```text
+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.
+
+## Schema
+
+The manifest schema is published as JSON Schema Draft 2020-12:
+
+```text
+schema/iac.schema.json
+```
+
+Product manifests can reference the package copy:
+
+```json
+{
+  "$schema": "./node_modules/@vertile-ai/iac/schema/iac.schema.json"
+}
+```
+
+## Publishing
+
+Publish with public access:
+
+```bash
+pnpm publish --access public
+```

package/docs/README.md

@@ -0,0 +1,40 @@
+# Vertile AI IaC Docs
+
+Vertile AI IaC is an app-first infrastructure abstraction for solo builders and
+small teams. Define infrastructure intent once, then compile it into
+provider-specific infrastructure without adopting Kubernetes as a control plane.
+
+## Start Here
+
+- [Positioning](./positioning.md)
+- [Roadmap](./roadmap.md)
+- [Manifest Guide](./manifest.md)
+- [Static Website](./index.html)
+
+## Core Idea
+
+Crossplane is Kubernetes-first platform infrastructure.
+Terraform and OpenTofu are provider-specific execution engines.
+Vertile AI IaC is app-first portable infrastructure intent.
+
+The user-authored source of truth is:
+
+```text
+infrastructure/iac/iac.json
+```
+
+Generated Terraform lives under:
+
+```text
+.vertile/terraform/<provider>/
+```
+
+Users edit the manifest. Vertile AI IaC renders provider-specific infrastructure.
+
+## Commands
+
+```bash
+vertile-iac render --target=all --env=production
+vertile-iac plan --target=aws --env=production
+vertile-iac apply --target=aws --env=production --yes
+```

package/docs/index.html

@@ -0,0 +1,276 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Vertile AI IaC</title>
+    <style>
+      :root {
+        color-scheme: light;
+        --bg: #fbfaf7;
+        --ink: #161615;
+        --muted: #66615b;
+        --line: #ddd7ce;
+        --panel: #ffffff;
+        --accent: #0f766e;
+        --accent-ink: #0b4f4a;
+        --code: #f1eee8;
+      }
+
+      * {
+        box-sizing: border-box;
+      }
+
+      body {
+        margin: 0;
+        background: var(--bg);
+        color: var(--ink);
+        font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+        line-height: 1.55;
+      }
+
+      header,
+      main,
+      footer {
+        width: min(1080px, calc(100% - 40px));
+        margin: 0 auto;
+      }
+
+      header {
+        min-height: 78vh;
+        display: grid;
+        align-content: center;
+        padding: 56px 0 40px;
+        border-bottom: 1px solid var(--line);
+      }
+
+      nav {
+        position: absolute;
+        top: 20px;
+        left: 50%;
+        transform: translateX(-50%);
+        width: min(1080px, calc(100% - 40px));
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 20px;
+      }
+
+      nav a {
+        color: var(--muted);
+        text-decoration: none;
+        font-size: 14px;
+      }
+
+      .brand {
+        color: var(--ink);
+        font-weight: 700;
+      }
+
+      .links {
+        display: flex;
+        gap: 18px;
+        flex-wrap: wrap;
+        justify-content: flex-end;
+      }
+
+      h1 {
+        max-width: 820px;
+        margin: 0;
+        font-size: clamp(46px, 8vw, 90px);
+        line-height: 0.98;
+        letter-spacing: 0;
+      }
+
+      .lede {
+        max-width: 720px;
+        margin: 26px 0 0;
+        color: var(--muted);
+        font-size: clamp(18px, 2.3vw, 24px);
+      }
+
+      .actions {
+        display: flex;
+        gap: 14px;
+        flex-wrap: wrap;
+        margin-top: 34px;
+      }
+
+      .button {
+        display: inline-flex;
+        min-height: 44px;
+        align-items: center;
+        justify-content: center;
+        border: 1px solid var(--ink);
+        border-radius: 6px;
+        padding: 10px 16px;
+        color: var(--ink);
+        text-decoration: none;
+        font-weight: 650;
+      }
+
+      .button.primary {
+        border-color: var(--accent);
+        background: var(--accent);
+        color: #fff;
+      }
+
+      main {
+        padding: 42px 0 64px;
+      }
+
+      section {
+        padding: 34px 0;
+        border-bottom: 1px solid var(--line);
+      }
+
+      h2 {
+        margin: 0 0 14px;
+        font-size: 28px;
+        line-height: 1.15;
+        letter-spacing: 0;
+      }
+
+      p {
+        max-width: 780px;
+      }
+
+      .grid {
+        display: grid;
+        grid-template-columns: repeat(3, minmax(0, 1fr));
+        gap: 14px;
+        margin-top: 22px;
+      }
+
+      .tile {
+        min-height: 160px;
+        border: 1px solid var(--line);
+        border-radius: 8px;
+        background: var(--panel);
+        padding: 18px;
+      }
+
+      .tile h3 {
+        margin: 0 0 8px;
+        font-size: 18px;
+      }
+
+      .tile p {
+        margin: 0;
+        color: var(--muted);
+      }
+
+      pre {
+        overflow: auto;
+        border: 1px solid var(--line);
+        border-radius: 8px;
+        background: var(--code);
+        padding: 18px;
+      }
+
+      code {
+        font-family: "SFMono-Regular", Consolas, "Liberation Mono", monospace;
+        font-size: 0.94em;
+      }
+
+      footer {
+        padding: 28px 0 42px;
+        color: var(--muted);
+        font-size: 14px;
+      }
+
+      @media (max-width: 760px) {
+        header {
+          min-height: 84vh;
+        }
+
+        nav {
+          align-items: flex-start;
+          flex-direction: column;
+        }
+
+        .links {
+          justify-content: flex-start;
+        }
+
+        .grid {
+          grid-template-columns: 1fr;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <nav>
+      <a class="brand" href="#top">Vertile AI IaC</a>
+      <div class="links">
+        <a href="#manifest">Manifest</a>
+        <a href="#providers">Providers</a>
+        <a href="#roadmap">Roadmap</a>
+      </div>
+    </nav>
+
+    <header id="top">
+      <h1>App-first infrastructure intent.</h1>
+        <p class="lede">Define infrastructure once, then render, plan, and apply provider-specific Terraform for Vercel, AWS, DigitalOcean, and future app infrastructure providers.</p>
+      <div class="actions">
+        <a class="button primary" href="#manifest">Read the manifest guide</a>
+        <a class="button" href="./roadmap.md">View roadmap</a>
+      </div>
+    </header>
+
+    <main>
+      <section id="manifest">
+        <h2>One Source Of Truth</h2>
+        <p>The user-authored source of truth is <code>infrastructure/iac/iac.json</code>. Terraform files are generated output under <code>.vertile/terraform/&lt;provider&gt;/</code>.</p>
+        <pre><code>{
+  "version": 1,
+  "project": { "name": "example" },
+  "environments": ["development", "preview", "production"],
+  "providers": {
+    "vercel": { "team": "example-team" },
+    "aws": { "region": "us-east-1" },
+    "digitalocean": {}
+  },
+  "apps": [{ "key": "web", "domains": ["web.example.com"] }],
+  "objectStorage": [{ "key": "uploads" }],
+  "databases": [{ "key": "appdb", "engine": "postgres" }],
+  "queues": [{ "key": "jobs" }],
+  "sandboxes": [{ "key": "runner" }],
+  "clusters": [{ "key": "workers", "size": 2 }]
+}</code></pre>
+      </section>
+
+      <section id="providers">
+        <h2>Provider Adapters</h2>
+        <p>Vertile AI IaC keeps portable concepts in the manifest and compiles them into provider-specific resources. Provider overrides are available when a platform has unique behavior.</p>
+        <div class="grid">
+          <div class="tile">
+            <h3>Vercel</h3>
+            <p>Apps, domains, env vars, and project settings for frontend and serverless deployments.</p>
+          </div>
+          <div class="tile">
+            <h3>AWS</h3>
+            <p>Object storage, databases, queues, compute, and clusters for broader infrastructure needs.</p>
+          </div>
+          <div class="tile">
+            <h3>DigitalOcean</h3>
+            <p>Spaces, managed databases, app hosting, droplets, and pragmatic compute defaults.</p>
+          </div>
+        </div>
+      </section>
+
+      <section id="roadmap">
+        <h2>Built For Small Teams And AI Workflows</h2>
+        <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>
+      </section>
+    </main>
+
+    <footer>
+      Crossplane is Kubernetes-first platform infrastructure. Terraform/OpenTofu is provider-specific execution. Vertile AI IaC is app-first portable infrastructure intent.
+    </footer>
+  </body>
+</html>

package/docs/manifest.md

@@ -0,0 +1,130 @@
+# Manifest Guide
+
+The manifest is the source of truth for app infrastructure intent.
+
+```text
+infrastructure/iac/iac.json
+```
+
+Generated Terraform is an implementation detail:
+
+```text
+.vertile/terraform/vercel/
+.vertile/terraform/aws/
+.vertile/terraform/digitalocean/
+```
+
+## Minimal Manifest
+
+```json
+{
+  "$schema": "./node_modules/@vertile-ai/iac/schema/iac.schema.json",
+  "version": 1,
+  "project": { "name": "example" },
+  "environments": ["development", "preview", "production"],
+  "providers": {
+    "vercel": { "team": "example-team" },
+    "aws": { "region": "us-east-1" },
+    "digitalocean": {}
+  },
+  "apps": [
+    {
+      "key": "web",
+      "name": "example-web",
+      "framework": "nextjs",
+      "rootDirectory": "apps/web",
+      "domains": ["web.example.com"]
+    }
+  ],
+  "domains": [],
+  "objectStorage": [{ "key": "uploads", "visibility": "private" }],
+  "databases": [{ "key": "appdb", "engine": "postgres" }],
+  "queues": [{ "key": "jobs" }],
+  "sandboxes": [{ "key": "runner" }],
+  "clusters": [{ "key": "workers", "size": 2 }]
+}
+```
+
+The schema is published as JSON Schema Draft 2020-12 at
+`schema/iac.schema.json`.
+
+## Provider Overrides
+
+Portable concepts should be shared by default, with provider-specific overrides
+only where the provider really differs.
+
+```json
+{
+  "objectStorage": [
+    {
+      "key": "assets",
+      "visibility": "private",
+      "providers": {
+        "aws": { "storageClass": "standard" },
+        "digitalocean": { "region": "nyc3" }
+      }
+    }
+  ]
+}
+```
+
+## Escape Hatch
+
+Provider-specific Terraform resources can be expressed under
+`providers.<target>.resources` while the portable schema matures.
+
+```json
+{
+  "providers": {
+    "aws": {
+      "resources": [
+        {
+          "type": "aws_s3_bucket",
+          "name": "assets",
+          "values": {
+            "bucket": "example-assets"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+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.
+
+## Supported Concepts
+
+| Concept | Vercel | AWS | DigitalOcean |
+| --- | --- | --- | --- |
+| `apps` | Vercel Project | - | - |
+| `domains` | Vercel Project Domain | - | - |
+| `objectStorage` | - | S3 Bucket | Spaces Bucket |
+| `databases` | - | RDS Instance | Managed Database Cluster |
+| `queues` | - | SQS Queue | - |
+| `sandboxes` | - | EC2 Instance | Droplet |
+| `clusters` | - | EC2 Instance group | Droplet group |
+
+Unsupported provider cells are intentionally blank. Use provider-specific
+resources or another provider for those capabilities.
+
+## Commands
+
+Render generated Terraform:
+
+```bash
+vertile-iac render --target=all --env=production
+```
+
+Preview changes with Terraform:
+
+```bash
+vertile-iac plan --target=aws --env=production
+```
+
+Apply changes with explicit non-interactive approval:
+
+```bash
+vertile-iac apply --target=aws --env=production --yes
+```