Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
41 commits
Select commit Hold shift + click to select a range
6d1cefd
test(terraform): add reproducible lifecycle field scenarios
osterman Oct 28, 2026
4d0a58e
docs(plugins): publish the component plugin and Terragrunt PRDs ahead…
osterman Oct 31, 2026
0e7a965
docs(terragrunt): drop the link to an unpublished pilot commit
osterman Nov 1, 2026
230df87
docs(plugins): publish the SDK and Starlark filesystem documentation …
osterman Nov 1, 2026
1d89094
ci: allow image-spec licenses and let plugin coverage pick its module…
osterman Nov 8, 2026
fb6075b
fix(plugin): bump auth-secrets to 1.1.2 for the SDK README input
osterman Nov 8, 2026
6556747
test(terraform): isolate field-test cases and clean up timed-out PTY …
osterman Nov 10, 2026
c638fd5
test(terraform): wait for PTY child exit and drain output before closing
osterman Nov 10, 2026
ffcbf31
docs(test): add a reproducible procedure to the cache field fixture
osterman Nov 10, 2026
e6a3a11
refactor(describe): let static describe merge stacks from other sources
osterman Nov 11, 2026
52a2184
docs(plugins): correct planned component support status
osterman Nov 11, 2026
cbeb8e3
docs(starlark): remove unavailable directory helpers
osterman Nov 11, 2026
7f69b59
test(terraform): check generated variables and plan arguments
osterman Nov 11, 2026
4075016
test(terraform): strengthen field fixture observations
osterman Nov 11, 2026
adcf1c7
test(terraform): inspect failure and affected outcomes
osterman Nov 11, 2026
0c90976
docs(test): distinguish relative source fixture copies
osterman Nov 11, 2026
23ea88f
test(terraform): inspect selectors hooks and shared callers
osterman Nov 11, 2026
c9ac272
test(terraform): observe progress and cancellation while running
osterman Nov 11, 2026
06ffdd5
docs(test): isolate registry cache field scenarios
osterman Nov 11, 2026
b144f55
test(runner): budget process tree startup before timeout
osterman Nov 12, 2026
a183e5c
ci(link-check): check the Cursor marketplace over HTTP/1.1
osterman Nov 12, 2026
3896752
Merge remote-tracking branch 'origin/fix/terraform-lifecycle-safety' …
osterman Nov 12, 2026
ef3e592
Merge origin/fix/terraform-lifecycle-safety into test/terraform-lifec…
osterman Nov 12, 2026
f0750c8
test(terraform): fail field runners on failed checks and nested output
osterman Nov 13, 2026
a485f40
Merge origin/fix/terraform-lifecycle-safety into test/terraform-lifec…
osterman Nov 13, 2026
724fc4f
test(retry): synchronize SIGINT with backoff and preserve evidence
osterman Nov 14, 2026
415b04f
Merge updated Terraform lifecycle safety into field fixtures
osterman Nov 14, 2026
ed65a74
fix(terraform): use the target identity's GCP credentials in the GCS …
osterman Nov 14, 2026
128e581
Merge remote-tracking branch 'origin/fix/terraform-lifecycle-safety' …
osterman Nov 14, 2026
baaa9c2
Merge remote-tracking branch 'origin/fix/terraform-lifecycle-safety' …
osterman Nov 14, 2026
7fc7dc8
fix(terraform-backend): fail GCS state reads when the identity token …
osterman Nov 15, 2026
b75f4be
Merge branch 'fix/terraform-lifecycle-safety' into test/terraform-lif…
osterman Nov 15, 2026
31600cf
Merge branch 'fix/terraform-lifecycle-safety' into test/terraform-lif…
osterman Nov 15, 2026
981ae5f
Merge branch 'fix/terraform-lifecycle-safety' into test/terraform-lif…
osterman Nov 16, 2026
eea62e3
Merge branch 'fix/terraform-lifecycle-safety' into test/terraform-lif…
osterman Nov 16, 2026
370c134
fix(terraform-backend): reject expired GCS identity token when creden…
osterman Nov 16, 2026
09b3c96
Merge remote-tracking branch 'origin/fix/terraform-lifecycle-safety' …
osterman Nov 16, 2026
fb2d1af
Merge remote-tracking branch 'origin/fix/terraform-lifecycle-safety' …
osterman Nov 16, 2026
d26e8d4
Merge L2 lifecycle safety checkpoint into L3 field fixtures
osterman Nov 17, 2026
337e72d
Merge L2 prerequisite and OIDC fixes into L3 field fixtures
osterman Nov 17, 2026
9479fec
Merge L2 HTTP cooldown checkpoint into L3 field fixtures
osterman Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion .github/workflows/dependency-review.yml
Original file line number Diff line number Diff line change
Expand Up @@ -54,11 +54,15 @@ jobs:
# sax: BlueOak-1.0.0 (verified at https://github.com/isaacs/sax-js/blob/main/LICENSE.md) -
# Blue Oak Model License, a permissive OSS license.
# Transitive dependency of svgo (website SVG optimization).
# github.com/opencontainers/image-spec: Apache-2.0 code; "LicenseRef-scancode-dco-1.1"
# is the contributor DCO text and "MIT" covers bundled schema tooling (see
# https://github.com/opencontainers/image-spec/blob/main/LICENSE).
# Transitive dependency of Terragrunt in plugins/terragrunt (and of the root module).
# minimatch and @isaacs/nonrecursive-glob-match: BlueOak-1.0.0 is a permissive license,
# approved for these two packages only (BlueOak-1.0.0 is deliberately not added to
# allow-licenses). They come from the website docs tooling (pnpm override of minimatch
# to v11) and the cdk-terraform example lockfile; neither ships in the atmos binary.
allow-dependencies-licenses: "pkg:golang/github.com/antlr4-go/antlr/v4, pkg:golang/github.com/google/cel-go, pkg:golang/golang.org/x/image, pkg:golang/modernc.org/libc, pkg:golang/github.com/opencontainers/go-digest, pkg:npm/pako, pkg:npm/sax, pkg:npm/minimatch, pkg:npm/%40isaacs/nonrecursive-glob-match"
allow-dependencies-licenses: "pkg:golang/github.com/antlr4-go/antlr/v4, pkg:golang/github.com/google/cel-go, pkg:golang/golang.org/x/image, pkg:golang/modernc.org/libc, pkg:golang/github.com/opencontainers/go-digest, pkg:golang/github.com/opencontainers/image-spec, pkg:npm/pako, pkg:npm/sax, pkg:npm/minimatch, pkg:npm/%40isaacs/nonrecursive-glob-match"

# Fail on moderate or higher severity vulnerabilities
fail-on-severity: moderate
Expand Down
3 changes: 3 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -1290,6 +1290,9 @@ jobs:
env:
CGO_ENABLED: "0"
GOWORK: "off"
# Each package module pins its own Go version; plugins/terragrunt needs a newer
# toolchain than the root go.mod this job installs.
GOTOOLCHAIN: auto
run: |
# Each official package is a separate module with an independent version.
printf 'mode: set\n' > plugins-coverage.out
Expand Down
131 changes: 91 additions & 40 deletions docs/prd/plugins/extensions/component-engines.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/prd/plugins/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ A **plugin** is an installable, independently versioned package managed by `atmo

## Foundation and architectural direction

Atmos's existing registries are the integration points, but they are uneven. The [gap analysis](platform/gap-analysis.md) inventories each one: most replace silently on duplicate registration, two live in Go-internal packages, three interfaces carry no `context.Context`, and several surfaces still dispatch through closed lists rather than a registry. Terraform, Helmfile, and Packer are not registered as component engines; validation has no engine registry; credentials have no versioned type.
Atmos's existing registries are the integration points, but they are uneven. The [gap analysis](platform/gap-analysis.md) inventories each one: most replace silently on duplicate registration, two live in Go-internal packages, three interfaces carry no `context.Context`, and several surfaces still dispatch through closed lists rather than a registry. Terraform now uses the component registry. Helmfile and Packer still use legacy execution paths. The [component extension](extensions/component-engines.md) separates configuration providers from engines; its protocol and explicit host activation API are implemented, while CLI stack and execution integration remain pending. Other entries in the gap analysis describe the platform design baseline and must be checked against the implemented adapters.

Auth now dispatches built-in and plugin provider and identity constructors through `pkg/auth/registry`. Preserve existing configuration and behavior as additional auth adapters are introduced.

Expand Down
2 changes: 1 addition & 1 deletion docs/prd/plugins/platform/gap-analysis.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ Prerequisites: P0.1 (registry completion), P0.2 (credential types). Follow-on: [
| Aspect | Finding |
|---|---|
| Registry | `component.Register(provider ComponentProvider) error`; `GetProvider`, `MustGetProvider`, `ListTypes`, `ListAllComponents`. Built-ins register in `init()` through blank imports in `cmd/root.go`: ansible, aws/cloudformation, container, emulator, helm, kubernetes, mock. [`custom/provider.go`](../../../../pkg/component/custom/provider.go) registers at runtime. |
| Not registered | **terraform, helmfile, and packer never call `component.Register`.** They run through legacy paths in `internal/exec`. |
| Registry migration | Terraform now registers through `pkg/component/terraform`; its runtime is extracted from `internal/exec`. Helmfile and Packer remain on legacy paths. External configuration providers must compose with Terraform, not replace it. See [component contracts and remaining adapters](../extensions/component-engines.md). |
| Duplicate policy | "Last registration wins, allowing plugin override." |
| Closed lists | `schema.Components.GetComponentConfig` switches on built-in types; dynamic types land in `Components.Plugins map[string]any` (`mapstructure:",remain"`). `internal/exec/describe_component.go` `autoDetectComponentTypes`; `internal/exec/describe_stacks_component_processor.go` `typeEntries`; `internal/exec/describe_stacks.go` `getComponentBasePath`; three type lists in `pkg/list/extract/components.go`; `pkg/utils/component_reverse_path_utils.go` and `cmd/list/sources.go` hardcode `terraform, helmfile, packer`. Component sections (`vars`, `settings`, `env`, `hooks`, `secrets`, …) are whitelisted in the stack processor (`pkg/config/const.go`, `internal/exec/stack_processor_process_stacks_helpers_extraction.go`, `internal/exec/stack_processor_merge.go`); custom types survive only through the raw-map fallback in `internal/exec/stack_processor_process_stacks.go`. |
| Boundary leaks | `Execute(ctx *ExecutionContext)` and `GenerateArtifacts` take a struct carrying `*schema.AtmosConfiguration`, `*schema.ConfigAndStacksInfo`, and `Flags map[string]any`. |
Expand Down
11 changes: 8 additions & 3 deletions docs/prd/plugins/platform/interfaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,7 @@ Every row is checked across built-ins, YAML configuration, and all selected pack
| Namespace | Key | Built-in or YAML claimant | Outcome |
|---|---|---|---|
| Auth provider and identity kinds | `kind` | `factory` kinds | Error |
| Component types | `type` | [`component.Register`](../../../../pkg/component/registry.go) plus legacy terraform, helmfile, packer | Error |
| Component types | `type` | [`component.Register`](../../../../pkg/component/registry.go) including Terraform, plus legacy helmfile and packer | Error |
| Command names | top-level name and aliases | [`internal.Register`](../../../../cmd/internal/registry.go) and YAML `commands:` | Shortcut unavailable; `atmos plugin run <alias>` still works |
| Hook kinds | `kind` | [`hooks.RegisterKind`](../../../../pkg/hooks/kind.go) | Error |
| Step types and aliases | `type`, `aliases` (one namespace) | [`step.Register`](../../../../pkg/runner/step/registry.go) | Error |
Expand Down Expand Up @@ -373,7 +373,8 @@ An adapter implements one existing Atmos interface by calling a wire service, so
| Extension | Adapter (`pkg/plugin/adapter/...`) | Existing interface implemented | Wire service | API services | Must not cross | Phase 0 |
|---|---|---|---|---|---|---|
| Auth | `auth.ProviderAdapter`, `auth.IdentityAdapter` | [`types.Provider`](../../../../pkg/auth/types/interfaces.go): `Kind`, `Name`, `PreAuthenticate`, `Authenticate`, `Validate`, `Environment`, `Paths`, `PrepareEnvironment`, `Logout`, `GetFilesDisplayPath`, `SetRealm`. `types.Identity`: `Kind`, `GetProviderName`, `Authenticate`, `Validate`, `Environment`, `Paths`, `PrepareEnvironment`, `PostAuthenticate`, `Logout`, `CredentialsExist`, `LoadCredentials`, `SetRealm`. Optional `Provisioner`, `JustificationConsumer`. | `AuthProvider`, `AuthIdentity` | `api.Credentials`, `api.Prompt`, `api.Browser`, `api.HTTP`, `api.Log` | `types.AuthManager`, `*schema.Provider`, `*schema.Identity`, `*schema.AuthContext` | P0.1, P0.2 |
| Component | `component.Adapter` | [`ComponentProvider`](../../../../pkg/component/provider.go): `GetType`, `GetGroup`, `GetBasePath`, `ListComponents`, `ValidateComponent`, `Execute`, `GenerateArtifacts`, `GetAvailableCommands`. | `Component` | `api.Process`, `api.Toolchain`, `api.FS`, `api.Credentials`, `api.Log` | `ExecutionContext` struct, `*schema.AtmosConfiguration`, `schema.ConfigAndStacksInfo` | P0.3, P0.6 |
| Component configuration | `component.Provider`, private `component.Registry` | Planned discovery, validation, preparation, and state clients; composition with existing engines remains required. | `ComponentDiscovery`, `ComponentValidation`, `ComponentPreparation`, `ComponentState` | No process, filesystem, network, or private-credential grants yet. | `ExecutionContext`, `*schema.AtmosConfiguration`, `schema.ConfigAndStacksInfo` | P0.3, P0.6 |
| Component execution (planned) | Engine adapter | [`ComponentProvider`](../../../../pkg/component/provider.go); external engines must not replace built-in providers. | Optional execution contract | Scoped process, toolchain, filesystem, credentials, and logging services | Host execution structs and callbacks | P0.3, P0.6 |
| CI provider | `ci.Adapter` | [`provider.Provider`](../../../../pkg/ci/internal/provider/types.go): `Name`, `Detect`, `Context`, `GetStatus`, `CreateCheckRun`, `UpdateCheckRun`, `PostComment`, `OutputWriter`, `ResolveBase`. Optional `LabelReader`, `DebugModeDetector`, `LogGrouper`. | `CIProvider` | `api.HTTP`, `api.Secrets`, `api.Log` | `OutputWriter`, `io.Writer` | P0.3, P0.7 |
| Component CI | `cicomponent.Adapter` | [`plugin.Plugin`](../../../../pkg/ci/internal/plugin/types.go): `GetType`, `GetHookBindings` (`HookBinding{Event, Handler}`). | `CIComponent` | `api.CIReporter`, `api.FS`, `api.Log` | `HookHandler` func, `HookContext.Provider`, `TemplateLoader`, `CreatePlanfileStore` | P0.5 |
| Command | `command.Adapter` (lives behind `cmd/plugin`) | [`internal.CommandProvider`](../../../../cmd/internal/command.go): `GetCommand`, `GetName`, `GetGroup`, `GetFlagsBuilder`, `GetPositionalArgsBuilder`, `GetCompatibilityFlags`, `GetAliases`, `IsExperimental`. | `Commands.Run` for native plugins; in-process binding proposed for Starlark | Native command bootstrap currently grants `api.HTTP`; output uses RPC events, not inherited stdio | `*cobra.Command` | P0.3 |
Expand All @@ -392,7 +393,11 @@ An adapter implements one existing Atmos interface by calling a wire service, so

### Component

`ExecutionContext` is flattened into an `ExecuteRequest`: component and stack names, resolved `ComponentConfig` map, command, subcommand, args, flags, working directory, and a scoped environment. Output is not written to `io.Writer`s; the plugin streams output chunks that Atmos writes through its own masked writers. `GenerateArtifacts` returns file contents and relative paths, and Atmos writes them, so a plugin cannot write outside the working-directory grant. `ListComponents` and `ValidateComponent` run from manifest-declared schemas where possible and call the plugin only when the manifest declares dynamic discovery.
Separate configuration providers from component types and execution engines. `ComponentDiscovery`, `ComponentValidation`, `ComponentPreparation`, and `ComponentState` are independent versioned services. Native Terragrunt configuration composes with the registered Terraform provider; it does not replace it. These services, SDK and runtime support, package activation, and host adapters are planned.

Requests flatten host context into explicit invocation, coordinates, source/root, operation/options, effects, and typed configuration. `ComponentValue` preserves cty types, exact numbers, unknowns, nulls, and sensitivity. Generated files return literal bytes and ownership policies for host validation. State resolution is separate from preparation. Optional execution must stream through masked host I/O and provide an authoritative outcome.

Use the [component plugin PRD](../extensions/component-engines.md) for static flag metadata, collision rules, discovery/import integration, host service grants, and acceptance. The current protocol does not grant filesystem or process access merely by declaring an effect policy.

### CI provider and component CI

Expand Down
31 changes: 12 additions & 19 deletions docs/prd/plugins/platform/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -254,29 +254,22 @@ Atmos selects the command export from manifest metadata before starting the nati

The runtime writes events to caller-provided stdout/stderr writers; callers supply masked writers for terminal output. The plugin process's own stdout is reserved for the go-plugin transport, not command data. Cancellation and deadlines follow the native invocation lifecycle. There is no stdin stream, inherited interactive terminal, or TTY negotiation in this contract. The current command bootstrap starts the process in the package directory, leaves `Invocation.working_directory` unset, and grants `api.HTTP` with no auth provider's private credential namespace.

### Component
### Component configuration services

```proto
service Component {
rpc Describe(ComponentDescribeRequest) returns (ComponentDescription); rpc ListComponents(ListComponentsRequest) returns (ListComponentsResponse);
rpc Validate(ComponentRequest) returns (ValidateResponse); rpc GenerateArtifacts(ComponentRequest) returns (GenerateArtifactsResponse);
rpc Execute(ComponentRequest) returns (stream ExecuteEvent); rpc Events(ComponentRequest) returns (EventsResponse);
}
message ComponentDescription { string type = 1; string group = 2; string base_path = 3; repeated CommandInfo commands = 4; string schema = 5; }
message ComponentRequest { Invocation invocation = 1; string command = 2; string subcommand = 3; google.protobuf.Struct component_config = 4;
repeated string args = 5; google.protobuf.Struct flags = 6; }
message ListComponentsRequest { Invocation invocation = 1; string stack = 2; google.protobuf.Struct stack_config = 3; }
message ExecuteEvent { oneof event { OutputChunk chunk = 1; LifecycleEvent lifecycle = 2; OperationOutcome outcome = 3; } }
```
The component configuration protocol, generated CLI and SDK bindings, and component-specific host descriptors, package loading, and adapters are planned. CLI stack and execution integration are also unavailable. These proposed independently negotiated version-1 services replace the earlier proposed monolithic `Component` service:

`Execute` streams `OutputChunk` and optional `LifecycleEvent` messages, then exactly one `OperationOutcome`. The engine declares which statuses mean success, so a nonzero tool exit can be `CHANGES`. `Events` returns the lifecycle events a command emits so Atmos can validate hook bindings. `GenerateArtifacts` returns `ArtifactRef` entries.
| Capability | RPC | Result |
|---|---|---|
| `component.discovery` | `ComponentDiscovery.Discover` | Logical instances, source watches, and dependency edges for an explicit root/revision. |
| `component.validation` | `ComponentValidation.Validate` | Unsupported mode/command/options diagnostics before effects. |
| `component.preparation` | `ComponentPreparation.Prepare` | Fresh inputs, module, backend identity, and literal generated files. |
| `component.state` | `ComponentState.Resolve` | Backend/workspace identity without preparation. |

| RPC | Replaces on `component.ComponentProvider` |
|---|---|
| `Describe` | `GetType`, `GetGroup`, `GetAvailableCommands`, `GetBasePath` (relative to the Atmos base path). |
| `ListComponents`, `Validate`, `GenerateArtifacts`, `Execute` | `ListComponents`, `ValidateComponent`, `GenerateArtifacts`, `Execute`. |
`ComponentRequest` carries explicit invocation, provider, coordinates, root/source, operation/options, effects, resolved component configuration, and separate provider settings. It does not carry host Go structs or callbacks. `ComponentValue` uses cty type JSON plus MessagePack and sensitivity paths, preserving exact numbers, unknowns, nulls, collection types, and sensitive values. Do not use `protobuf.Struct` for these values. The SDK rejects unsupported marks and sensitivity paths that cannot be applied.

Configuration providers do not replace execution engines. Native Terragrunt units remain Terraform components executed by Atmos. Optional external execution and component CI services remain follow-on contracts: they must stream output, diagnostics/logs, lifecycle events, then exactly one authoritative outcome. Preserve detailed plan exit 2 as changes. Saved-plan identity must bind the exact applied artifact and effective configuration.

`ExecutionContext.AtmosConfig` and `ConfigAndStacksInfo` become `Invocation` plus `ComponentRequest`: resolved values, stack coordinates, working directory, scoped environment.
Static command/flag metadata, effect enforcement, host services, and CLI activation remain required. See the [component plugin PRD](../extensions/component-engines.md) for ownership, integration points, and acceptance. Protocol availability alone does not mean an installed component plugin works.

### CIProvider

Expand Down
Loading
Loading