Schema Discover Heroku · Heroku To AWS · aws/agent-toolkit-for-aws · Skills Docs

Schema Discover Heroku · Heroku To AWS · aws/agent-toolkit-for-aws · Skills Docs

{
  "metadata": {
    "discovery_timestamp": "2026-03-15T10:30:00Z",
    "total_apps_discovered": 4,
    "discovery_sources": ["terraform", "procfile"],
    "confidence": "full|reduced",
    "confidence_note": "Terraform had parse errors on some files (if reduced)"
  },
  "apps": [
    {
      "app_name": "my-web-app",
      "app_id": "01234567-89ab-cdef-0123-456789abcdef",
      "heroku_generation": "cedar|fir|unknown",
      "generation_action": "detect_only",
      "generation_diagnostics": [],
      "space": null,
      "discovery_status": "success|discovery_failed",
      "failure_reason": null,
      "procfile_parse_warning": null,
      "app_json_parse_warning": null
    }
  ],
  "resources": [
    {
      "resource_id": "formation:my-web-app:web",
      "resource_type": "formation",
      "heroku_app": "my-web-app",
      "config": {}
    }
  ],
  "billing_profile": {},
  "terraform_metadata": {},
  "live_metadata": {}
}

Field	Type	Required	Description
`discovery_timestamp`	string (ISO 8601)	✅	When discovery was executed
`total_apps_discovered`	integer	✅	Count of Heroku apps found
`discovery_sources`	string[]	✅	Sources used: `"terraform"`, `"procfile"`, `"billing"`, `"live"`
`confidence`	string	✅	`"full"` (primary source(s) parsed/captured successfully) or `"reduced"` (partial data, e.g., Terraform parse errors, failed/skipped live captures, missing expected resources)
`confidence_note`	string	❌	Explanation when confidence is `"reduced"`

Field	Type	Required	Description
`app_name`	string	✅	Heroku app name
`app_id`	string (UUID)	✅	Heroku app UUID
`heroku_generation`	string	✅	`"cedar"`, `"fir"`, or `"unknown"`
`generation_action`	string	✅	Always `"detect_only"` in v1
`generation_diagnostics`	string[]	✅	Diagnostic reasons (empty array if resolved cleanly; contains `"generation_unresolved"` on timeout/error)
`space`	string \| null	✅	Private Space name, or `null` if not in a space
`discovery_status`	string	✅	`"success"` or `"discovery_failed"`
`failure_reason`	string \| null	✅	Error description when `discovery_status` is `"discovery_failed"`, otherwise `null`
`procfile_parse_warning`	string \| null	✅	Warning text if Procfile parsing failed, otherwise `null`
`app_json_parse_warning`	string \| null	✅	Warning text if app.json parsing failed, otherwise `null`

Field	Type	Required	Description
`resource_id`	string	✅	Unique identifier (format below)
`resource_type`	string	✅	One of: `"formation"`, `"addon"`, `"space"`, `"pipeline"`, `"domain"`, `"config"`
`heroku_app`	string	✅	App name this resource belongs to, or `"unassociated"`
`config`	object	✅	Type-specific configuration (see per-type schemas below)
`source`	string	❌	Discovery provenance: `"terraform"`, `"live"`, or `"live+terraform"` (merged)
`unmanaged_by_terraform`	boolean	❌	Set `true` when live discovery found the resource but Terraform does not manage it (drift)
`not_found_live`	boolean	❌	Set `true` when Terraform declares the resource but live discovery did not find it deployed

Field	Type	Required	Description
`available`	boolean	✅	Whether billing data was successfully parsed
`total_monthly_cost`	number	✅	Total monthly spend in declared currency
`currency`	string	✅	ISO 4217 currency code (e.g., `"USD"`)
`billing_period`	string	✅	YYYY-MM format billing period
`line_items`	object[]	✅	Per-resource cost breakdown

Field	Type	Required	Description
`found`	boolean	✅	Whether Terraform files with `heroku_*` resources were found
`tf_files_scanned`	integer	✅	Number of `.tf` files scanned
`resource_types_extracted`	string[]	✅	List of extracted resource types (e.g., `"heroku_app"`, `"heroku_addon"`)
`parse_warnings`	string[]	✅	Any parse warnings encountered during extraction

Field	Type	Required	Description
`found`	boolean	✅	Whether live capture produced usable data
`captured_at`	string	✅	ISO 8601 timestamp of the CLI capture run
`apps_captured`	integer	✅	Number of apps successfully captured
`apps_failed`	integer	✅	Number of apps whose captures failed (e.g., 403 on team apps)
`capture_warnings`	string[]	✅	Failed/skipped capture notes carried from `live-capture/manifest.json`
`limitations`	string[]	✅	Known live-discovery blind spots (e.g., formations scaled to zero)
`default_heroku_domains_skipped`	integer	❌	Count of default `*.herokuapp.com` hostnames skipped (not recorded as domain resources)
`drift`	object	❌	Present only when Terraform AND live both ran: `resources_live_only` (int), `resources_terraform_only` (int), `config_conflicts[]` (`{resource_id, field, terraform_value, live_value}`)

Resource Type	ID Format	Example
`formation`	`formation:{app_name}:{process_type}`	`formation:my-web-app:web`
`addon`	`addon:{app_name}:{addon_service}:{plan}`	`addon:my-web-app:heroku-postgresql:standard-0`
`space`	`space:{space_name}`	`space:my-private-space`
`pipeline`	`pipeline:{pipeline_name}`	`pipeline:my-pipeline`
`domain`	`domain:{app_name}:{hostname}`	`domain:my-web-app:www.example.com`
`config`	`config:{app_name}`	`config:my-web-app`

{
  "process_type": "web|worker|release|clock|<custom>",
  "command": "npm start",
  "dyno_type": "eco|basic|standard-1x|standard-2x|performance-m|performance-l|performance-l-ram|performance-xl|performance-2xl|private-s|private-m|private-l|private-l-ram|private-xl|private-2xl|shield-s|shield-m|shield-l|shield-l-ram|shield-xl|shield-2xl",
  "quantity": 2
}

Field	Type	Required	Description
`process_type`	string	✅	Process type name from Procfile
`command`	string	✅	Start command from Procfile
`dyno_type`	string	✅	Heroku dyno size, lowercased (authoritative tier list: `knowledge/design/` sizing tables)
`quantity`	integer (0–100)	✅	Number of dynos running

{
  "space_name": "my-private-space",
  "region": "virginia",
  "shield": false,
  "peering": {
    "detected": true,
    "vpc_id": "vpc-0123456789abcdef0",
    "peer_cidr": "10.0.0.0/16"
  }
}

Field	Type	Required	Description
`space_name`	string	✅	Private Space name
`region`	string	✅	Heroku region
`shield`	boolean	✅	Whether Shield compliance is enabled
`peering`	object	✅	VPC peering information
`peering.detected`	boolean	✅	Whether VPC peering was found
`peering.vpc_id`	string \| null	✅	Peered VPC ID (null if not detected or unavailable)
`peering.peer_cidr`	string \| null	✅	Peer CIDR block (null if not detected)

{
  "pipeline_name": "my-pipeline",
  "stages": [
    { "stage": "development", "app": "my-web-app-dev" },
    { "stage": "staging", "app": "my-web-app-staging" },
    { "stage": "production", "app": "my-web-app" }
  ],
  "review_apps_enabled": true,
  "detection_status": "detect-only"
}

Field	Type	Required	Description
`pipeline_name`	string	✅	Pipeline name
`stages`	object[]	✅	Stage definitions
`stages[].stage`	string	✅	Stage name: `"review"`, `"development"`, `"staging"`, `"production"`
`stages[].app`	string	✅	App name assigned to this stage
`review_apps_enabled`	boolean	✅	Whether Review Apps are enabled
`detection_status`	string	✅	Always `"detect-only"` in v1

Level	Meaning	When Used
`full`	Every source that ran produced complete data	Terraform parsed without errors and/or every live capture for the selected apps succeeded
`reduced`	Partial data from at least one source	Terraform parse errors, failed/skipped live captures (e.g., 403 on team apps, missing CLI plugin), or missing expected resources

{
  "metadata": {
    "discovery_timestamp": "2026-03-15T10:30:00Z",
    "total_apps_discovered": 4,
    "discovery_sources": ["terraform", "procfile"],
    "confidence": "full"
  },
  "apps": [
    {
      "app_name": "my-web-app",
      "app_id": "01234567-89ab-cdef-0123-456789abcdef",
      "heroku_generation": "cedar",