feat(vendor): warn when vendoring from an archived GitHub repository

CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## Unreleased
+
+### Breaking Changes
+
+- `pkg/logger.NewAtmosLogger` now requires an explicit `io.Writer` second argument.
+  Pass `nil` to use the default `os.Stderr` writer.
+  Migration: `NewAtmosLogger(charmLogger)` → `NewAtmosLogger(charmLogger, nil)`.
+
+### Links
+
+- Blog: [Warn when vendoring from an archived GitHub repository](/blog/warn-vendor-archived-repo)
+  (`website/blog/2026-03-12-warn-vendor-archived-repo.mdx`)
+- Docs: [`atmos vendor pull` — ATMOS_GITHUB_ARCHIVED_CHECK_TIMEOUT](/cli/commands/vendor/pull)
+  (`website/docs/cli/commands/vendor/vendor-pull.mdx`)
+- Docs: [Environment Variables — ATMOS_GITHUB_ARCHIVED_CHECK_TIMEOUT](/cli/environment-variables)
+  (`website/docs/cli/environment-variables.mdx`)

CLAUDE.md

@@ -220,6 +220,34 @@ ALWAYS use `cmd.NewTestKit(t)` for cmd tests. Auto-cleans RootCmd state (flags,
 ### Follow-up Tracking (MANDATORY)
 When a PR defers work to a follow-up (e.g., migration, cleanup, refactor), **open a GitHub issue and link it by number** in the blog post, roadmap, and/or PR description before merging. Blog posts with "a follow-up issue will..." with no `#number` are incomplete — the work will never be tracked.
 
+### Test-Only Helpers in Production Packages (MANDATORY)
+When a test utility (seed/reset/inject) must be accessible from tests in **multiple packages**
+(e.g., `pkg/foo` and `internal/exec`), Go's `export_test.go` mechanism cannot help because
+`_test.go` files are not visible when another package imports the production package during its
+own tests. In these cases:
+- Export the helper from the production package with a clear doc comment: `// NOTE: test utility`
+- **NEVER** silently export test helpers without documentation
+- Prefer suffixes like `ForTest` or prefix with `Test` to signal intent
+- Document the limitation in both the function comment and in the audit response
+
+### Context Cancellation in Tests (MANDATORY)
+- **NEVER use `context.WithTimeout(ctx, 0)`** for "immediately expired" contexts — a zero
+  duration creates a deadline of `time.Now()` which may not be past on fast hardware.
+- **ALWAYS use `context.WithCancel` + immediate `cancel()`** for reliably cancelled contexts:
+  ```go
+  ctx, cancel := context.WithCancel(context.Background())
+  cancel() // immediately cancelled — safe on all hardware
+  defer cancel()
+  ```
+- For a past deadline: `context.WithDeadline(ctx, time.Now().Add(-time.Second))`
+
+### Global State Synchronization (MANDATORY)
+For any package-level variable mutated by test helpers and read by production functions:
+- Use `sync/atomic` for simple scalars (int64, uint64) — prefer `atomic.Int64` (Go 1.19+)
+- Use `sync.RWMutex` for complex types (structs, slices, maps)
+- Document the synchronization mechanism in the variable's doc comment
+- Test helpers that modify global state must restore it via `t.Cleanup`
+
 ### Mock Generation (MANDATORY)
 Use `go.uber.org/mock/mockgen` with `//go:generate` directives. Never manual mocks.
 

internal/exec/export_test.go

@@ -0,0 +1,16 @@
+package exec
+
+// ResetWarnedArchivedReposForTest clears the per-run warning-deduplication map so that
+// tests in other packages that call warnIfArchivedGitHubRepo indirectly (e.g., integration
+// tests that exercise the full vendor pipeline) can reset state between test runs.
+//
+// NOTE: test utility — exported via export_test.go so it is only compiled during
+// `go test ./internal/exec/...` and is not part of the production binary. Tests within
+// this package can call the unexported resetWarnedRepos helper directly; this export is
+// only needed if integration tests in other packages ever need to reset the map.
+func ResetWarnedArchivedReposForTest() {
+	warnedArchivedRepos.Range(func(k, _ any) bool {
+		warnedArchivedRepos.Delete(k)
+		return true
+	})
+}

internal/exec/terraform_generate_backends_test.go

@@ -1020,7 +1020,7 @@ components:
 		// Capture log output
 		var logBuf bytes.Buffer
 		originalLogger := log.Default()
-		testLogger := log.NewAtmosLogger(charm.New(&logBuf))
+		testLogger := log.NewAtmosLogger(charm.New(&logBuf), &logBuf)
 		testLogger.SetLevel(log.WarnLevel)
 		log.SetDefault(testLogger)
 		defer log.SetDefault(originalLogger)
@@ -1100,7 +1100,7 @@ components:
 		// Capture log output
 		var logBuf bytes.Buffer
 		originalLogger := log.Default()
-		testLogger := log.NewAtmosLogger(charm.New(&logBuf))
+		testLogger := log.NewAtmosLogger(charm.New(&logBuf), &logBuf)
 		testLogger.SetLevel(log.WarnLevel)
 		log.SetDefault(testLogger)
 		defer log.SetDefault(originalLogger)

internal/exec/vendor_component_utils.go

@@ -194,6 +194,14 @@ func ExecuteComponentVendorInternal(
 		uri, useLocalFileSystem, sourceIsLocalFile = handleLocalFileScheme(componentPath, uri)
 	}
 	pType := determinePackageType(useOciScheme, useLocalFileSystem)
+
+	// Warn if the source is an archived GitHub repository.
+	// TODO: thread context.Context through the vendor pipeline so this check cancels on Ctrl+C.
+	// See https://github.com/cloudposse/atmos/issues for the tracking issue.
+	if pType == pkgTypeRemote {
+		warnIfArchivedGitHubRepo(context.Background(), uri, component)
+	}
+
 	componentPkg := pkgComponentVendor{
 		uri:                 uri,
 		name:                component,

internal/exec/vendor_github_archive.go

@@ -0,0 +1,66 @@
+package exec
+
+import (
+	"context"
+	"sync"
+
+	gh "github.com/cloudposse/atmos/pkg/github"
+	log "github.com/cloudposse/atmos/pkg/logger"
+)
+
+// warnedArchivedRepos tracks repositories for which an archived warning has already
+// been emitted during the current run. This prevents duplicate warnings when the same
+// owner/repo pair is referenced by both vendor.yaml sources and component.yaml definitions.
+// The deduplication key is "owner/repo" (not the full URI), so different URI formats
+// pointing to the same repository (e.g., https:// vs github://) are correctly deduplicated.
+var warnedArchivedRepos sync.Map
+
+// warnIfArchivedGitHubRepo checks whether the given URI references an archived GitHub
+// repository and logs a warning if it does. The check is best-effort: any failure to
+// reach the GitHub API is logged at trace level so vendoring is never blocked.
+// The component argument is included in the warning when non-empty.
+func warnIfArchivedGitHubRepo(ctx context.Context, uri, component string) {
+	owner, repo, ok := gh.ParseGitHubOwnerRepo(uri)
+	if !ok {
+		return
+	}
+
+	archived, err := gh.IsRepoArchived(ctx, owner, repo)
+	if err != nil {
+		// Best-effort check: log at trace level and continue so vendoring is never blocked.
+		// Common causes: network unavailable, rate limit exceeded (set GITHUB_TOKEN),
+		// or repository not found.
+		log.Trace("Skipping archived-repo check", "repository", owner+"/"+repo, "error", err)
+		return
+	}
+
+	if !archived {
+		return
+	}
+
+	// Deduplicate: emit the warning only once per repo per run, even if the same
+	// repo appears in both vendor.yaml sources and component.yaml definitions.
+	repoKey := owner + "/" + repo
+	if _, loaded := warnedArchivedRepos.LoadOrStore(repoKey, struct{}{}); loaded {
+		// A warning was already emitted for this repo. Log at trace level so
+		// engineers can confirm the suppression without polluting normal output.
+		// Emit unconditionally; conditionally append the component key.
+		traceArgs := []any{"repository", repoKey}
+		if component != "" {
+			traceArgs = append(traceArgs, "component", component)
+		}
+		log.Trace("Archived-repo warning already emitted; skipping duplicate", traceArgs...)
+		return
+	}
+
+	logArgs := []any{
+		"repository", repoKey,
+	}
+	if component != "" {
+		logArgs = append(logArgs, "component", component)
+	}
+	log.Warn("GitHub repository is archived and no longer actively maintained. "+
+		"Vendoring from an archived repository may include outdated or unsupported code.",
+		logArgs...,
+	)
+}