# Nova Platform

> Nova Platform — infrastructure delivery, simplified. A consumer declares
> intent in a YAML contract; the platform resolves it to a stack, compiles
> it through the Terraform adapter, and applies it. Every deployment is
> reproducible from the shell, not just in CI.

Nova Platform is the **infrastructure-delivery core** of the Nova model.
The DevSecOps, identity, audit-ledger, and central CI-pipeline-contract
machinery of the reference are intentionally removed. What remains: a
consumer writes a small YAML contract that names one or more modules by
name + version, selects an environment, and supplies module-specific
inputs. The platform resolves the contract to a stack instance, compiles
it through the Terraform adapter, and applies it.

- **Consumer guide:** [`docs/consumer-guide.md`](docs/consumer-guide.md)
- **Contracts:** [`docs/contracts/`](docs/contracts/index.md)
- **Environments:** [`docs/environments/`](docs/environments/index.md)
- **Architecture:** [`docs/architecture.md`](docs/architecture.md)
- **Modules:** [`docs/modules/`](docs/modules/index.md)

## How to run

### Quick start (offline, no AWS required)

The fastest way to verify the platform works — no AWS credentials, no
bootstrap, no cost.

```bash
# Install test dependencies
pip install -r requirements-test.txt

# 1. Run the test suite (all offline)
python3 -m pytest tests/ -q

# 2. Run the platform in check-only mode (offline — contract -> resolve ->
#    adapter -> structure validation). Uses the default sample contract.
bash scripts/run_platform.sh --check-only contracts/static-assets.yml
# Expected: "=== PLATFORM CHECK OK ==="

# 3. Reproduce the full CI pipeline locally (lint -> test -> check-only)
bash scripts/run_ci.sh
# Expected: "=== CI PIPELINE OK ==="

# Show all run_platform.sh flags:
bash scripts/run_platform.sh --help
```

### Run against live AWS (requires credentials + bootstrap)

> Prerequisites: a platform-managed environment (see
> [docs/environments/](docs/environments/index.md); `core/environments/dev.json`
> is the sample), AWS credentials for dev (in `.ciagent/.env.secrets`,
> gitignored; see [Credentials](#credentials)), `terraform` (pin `>= 1.9, < 1.10`),
> `python3` + `boto3` + `jsonschema` + `pyyaml`.

```bash
# 1. Bootstrap the AWS state backend + runner IAM user (one-time, idempotent)
#    See terraform/bootstrap/README.md for the full runbook.
export NOVA_BOOTSTRAP_AWS_ACCESS_KEY_ID="<root key>"
export NOVA_BOOTSTRAP_AWS_SECRET_ACCESS_KEY="<root secret>"
export AWS_DEFAULT_REGION="us-east-1"
python3 terraform/bootstrap/create_state_backend.py
python3 terraform/bootstrap/create_iam_user.py   # prints the initial key
bash scripts/rotate_spike_key.sh                  # writes .ciagent/.env.secrets

# 2. Run the full platform pipeline (contract -> environment check -> stack ->
#    adapter -> terraform init/validate/plan -> apply).
bash scripts/run_platform.sh contracts/microservice.yml
# Expected: "=== PLATFORM APPLY OK ==="

# Or plan-only (contract -> stack -> adapter -> terraform plan; no apply):
bash scripts/run_platform.sh --plan-only contracts/static-assets.yml

# Add --quiet to suppress streaming (output to log files only):
bash scripts/run_platform.sh --quiet contracts/static-assets.yml
```

### run_platform.sh flags (D-031)

| Flag | Mode | AWS required | Description |
|------|------|--------------|-------------|
| `--check-only` | offline | no | contract → resolve → adapter → structure validation |
| `--plan-only` | AWS | yes | above + `terraform init`/`validate`/`plan` (no apply) |
| `--quiet` | any | — | suppress streaming output |
| `-h`, `--help` | — | — | show usage |
| *(none)* | apply | yes | full path: above + `terraform apply -auto-approve` |

## Repository layout

| Path | Purpose | Status |
|------|---------|--------|
| `core/` | Platform code: contract resolver, environment check, environments | active |
| `schemas/` | JSON Schemas (draft 2020-12): contract, stack, environment | active |
| `adapters/terraform/` | The Terraform adapter — the only engine-specific code | active |
| `terraform/` | State backend (S3 + DynamoDB) + bootstrap scripts + platform/onboarding/ci-vpc | active |
| `modules/` | L1 primitives (13) + L2 patterns (2) + `registry.json`. Each module has `interface.json` + `terraform/` | active |
| `contracts/` | Sample consumer contracts (`static-assets.yml`, `microservice.yml`) + per-env variants | active |
| `scripts/` | `run_platform.sh` (pipeline runner), `run_ci.sh` (local CI mirror), `rotate_spike_key.sh` | active |
| `tests/` | Pytest suite (all offline — resolver, adapter, schemas, engine boundary, environment check) | active |
| `docs/` | Documentation: consumer guide, contracts, environments, architecture, modules | active |
| `.ciagent/` | CIAgent config + locked decisions (`ARCHITECTURE.md`, `PROJECT.md`, `CLARIFY.md`) | active |

## Credentials

Nova Platform uses a **static AWS key** for dev/local operation. There is no
zero-trust federation layer in v1.0 — that is out of scope.

- The runner key is stored in **`.ciagent/.env.secrets`** (gitignored,
  `chmod 600`) using the `NOVA_AWS_*` prefix (D-032):
  `NOVA_AWS_ACCESS_KEY_ID`, `NOVA_AWS_SECRET_ACCESS_KEY`.
- `scripts/run_platform.sh` copies `NOVA_AWS_*` to the standard `AWS_*`
  env vars before invoking Terraform, then unsets the `NOVA_*` copies.
- Bootstrap uses a one-shot root key via `NOVA_BOOTSTRAP_AWS_*` env vars
  (never committed, never echoed). See
  [`terraform/bootstrap/README.md`](terraform/bootstrap/README.md) for the
  full bootstrap runbook (state backend + runner IAM user + key rotation).
- Onboarding creates a per-consumer IAM **role** (cross-account assume-role
  pattern, D-025) — not a user, not federation. See
  `terraform/onboarding/main.tf`.

## Consumer guide

A step-by-step guide for a consumer to create a repo, write a contract,
validate it offline, and run it against AWS is at
[`docs/consumer-guide.md`](docs/consumer-guide.md). The guide is generic
across all modules; `static-assets` is the worked example.