Design on scafctl

Solutions

Mon, 01 Jan 0001 00:00:00 +0000

Solutions#

Implementation Status#

Feature	Status	Notes
Solution structure (apiVersion/kind/metadata/spec)	✅ Implemented	`pkg/solution/solution.go`
Metadata fields	✅ Implemented	Includes icon/banner beyond original design
Catalog fields	✅ Implemented	visibility, beta, disabled
Spec with resolvers	✅ Implemented	`pkg/solution/spec.go`
Workflow with actions/finally	✅ Implemented	Uses `workflow.actions` and `workflow.finally`
Dependencies (plugins)	⏳ Planned	Declared under `bundle.plugins` — see catalog-build-bundling.md
Validation	✅ Implemented	`pkg/solution/spec_validation.go`
Run command	✅ Implemented	`scafctl run solution`
Render command	✅ Implemented	`scafctl render solution`

Purpose#

A solution is the top-level unit of configuration in scafctl. It defines what exists, how data is obtained, and what actions should occur.

Resolvers

Mon, 01 Jan 0001 00:00:00 +0000

Resolvers#

Purpose#

Resolvers produce named data values. They exist to gather, normalize, validate, and emit data in a deterministic way so that actions and other resolvers can consume it without re-computation or implicit behavior.

Resolvers are the only mechanism for introducing data into a solution. Actions never fetch or derive data on their own.

Resolvers do not cause side effects. They only compute values.

Implementation Status#

Feature	Status	Location
Resolver struct (Name, Description, Type, When, etc.)	✅ Implemented	`pkg/resolver/resolver.go`
Resolver Context (`sync.Map`, thread-safe)	✅ Implemented	`pkg/resolver/context.go`
ValueRef (Literal, Resolver, Expr, Tmpl)	✅ Implemented	`pkg/spec/valueref.go`
Phase-based execution (DAG ordering)	✅ Implemented	`pkg/resolver/phase.go`
Dependency extraction (CEL, templates, `dependsOn`)	✅ Implemented	`pkg/resolver/graph.go`
Cycle detection	✅ Implemented	Uses `pkg/dag`
Type coercion (string, int, float, bool, array, object, any)	✅ Implemented	`pkg/spec/types.go`
Additional types: `time`, `duration`	✅ Implemented	`pkg/spec/types.go`
Special symbols (`__self`, `__item`, `__index`)	✅ Implemented	`pkg/resolver/executor.go`
Iteration aliases (`item`, `index` in forEach)	✅ Implemented	`pkg/spec/foreach.go`
Error handling (ExecutionError, AggregatedValidationError)	✅ Implemented	`pkg/resolver/errors.go`
Redaction for sensitive values	✅ Implemented	`RedactedError`, snapshots
Timeout configuration (resolver, phase, default)	✅ Implemented	`ExecutorOption` functions
Concurrency control (`maxConcurrency`)	✅ Implemented	`WithMaxConcurrency()`
Progress callbacks	✅ Implemented	`ProgressCallback` interface
Snapshots	✅ Implemented	`pkg/resolver/snapshot.go`
Graph visualization (DOT, Mermaid, ASCII, JSON)	✅ Implemented	`pkg/resolver/graph.go`
Prometheus metrics	✅ Implemented	`pkg/resolver/metrics.go`
forEach in transform	✅ Implemented	`ForEachClause`
forEach `keepSkipped` (nil retention opt-in)	✅ Implemented	`ForEachClause.KeepSkipped`
forEach nil filtering (default behavior)	✅ Implemented	`pkg/resolver/executor.go`, `pkg/spec/foreach.go` (`KeepSkipped`)
`onError` behavior	✅ Implemented	`ErrorBehavior` type
ValidateAll mode (`--validate-all`)	✅ Implemented	`WithValidateAll()`
SkipValidation mode (`--skip-validation`)	✅ Implemented	`WithSkipValidation()`
Value size limits	✅ Implemented	`WarnValueSize`, `MaxValueSize`
Run resolver command	✅ Implemented	`pkg/cmd/scafctl/run/resolver.go`

Responsibilities#

A resolver is responsible for:

Providers

Mon, 01 Jan 0001 00:00:00 +0000

Providers#

Purpose#

Providers are stateless execution primitives. They perform a single, well-defined operation given validated inputs and return either a result or an error.

Providers do not own orchestration, control flow, dependency resolution, or lifecycle decisions. This separation keeps solutions deterministic, testable, and explicit.

Providers are used by:

Resolvers (during resolve, transform, and validate phases)
Actions (during execution or render)

Providers are never invoked implicitly. A provider runs only when explicitly referenced.

Actions

Mon, 01 Jan 0001 00:00:00 +0000

Actions#

Purpose#

Actions describe side effects as a declarative execution graph. They exist to model what should be done, not how data is derived.

Actions consume resolved data, declare dependencies, and reference results from other actions in a structured way. Actions may be executed directly by scafctl or rendered for execution by another system.

Resolvers compute data. Actions perform work.

Responsibilities#

An action is responsible for:

Declaring an executable operation
Selecting a provider
Declaring dependencies on other actions
Consuming resolver values and action results
Defining execution conditions

An action is not responsible for:

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Authentication and Authorization#

Purpose#

Authentication in scafctl is declarative, provider-driven, and execution-agnostic.

Providers declare what kind of token they require. scafctl or an external executor decides how that token is obtained and supplied. For local users, scafctl can initiate interactive authentication flows. For APIs and workflow engines, credentials are injected explicitly.

Authentication is a system concern, not a provider implementation detail.

Terminology#

Auth Handler: A component that implements the auth.Handler interface and manages identity verification, credential storage, and token acquisition for a specific identity provider (e.g., Entra, GitHub). Auth handlers are registered in the auth registry.
Auth Provider (in provider inputs): The authProvider field in HTTP provider inputs that specifies which auth handler to use for a request.
Provider: Action/resolver providers that perform work (e.g., HTTP, shell, file). Distinct from auth handlers.
Auth Handler Artifact: A go-plugin binary distributed via the catalog that exposes one or more auth handlers.

Built-in vs External Auth Handlers#

scafctl provides built-in auth handlers for common identity providers:

CEL Integration

Mon, 01 Jan 0001 00:00:00 +0000

CEL Integration Architecture#

Overview#

This document describes the architecture and best practices for integrating Common Expression Language (CEL) into scafctl. The design emphasizes performance through intelligent caching, thread safety through isolated execution contexts, and correctness through dependency-based execution ordering.

Architecture Principles#

Single Global CEL Environment#

One CEL environment per application instance
Created at application startup
Contains all built-in and custom extension functions
Never recreated during runtime
Shared across all requests and commands
Enables effective AST caching

Why?

GitHub Auth Handler

Mon, 01 Jan 0001 00:00:00 +0000

GitHub Auth Handler Implementation Plan#

Overview#

Implement a builtin GitHub auth handler (github) following the established patterns from the Entra handler. The handler supports four authentication flows:

Interactive (OAuth Authorization Code + PKCE) — Browser-based login for local development (default)
Device Code — Headless/SSH fallback using OAuth device authorization grant
PAT — Personal Access Token from environment variables for CI/CD
GitHub App — Installation token for service-to-service automation

Design Decisions#

Authentication Flows#

Flow	Use Case	Mechanism
Interactive	Local development (default)	OAuth 2.0 Authorization Code + PKCE via browser redirect
Device Code	Headless / SSH environments	OAuth 2.0 device authorization grant via GitHub OAuth App
PAT	CI/CD pipelines, automation	Read `GITHUB_TOKEN` or `GH_TOKEN` from environment variables
GitHub App	Service-to-service automation	JWT → installation access token via GitHub App credentials

Rationale: Interactive (browser) flow is the modern standard for CLI tools (gh, az, gcloud all use it as their default). Device code is the fallback for headless environments. PAT from environment mirrors the Entra handler’s service principal pattern and aligns with GitHub Actions’ GITHUB_TOKEN injection. GitHub App flow enables automated workflows that need repository access without a user context.

Catalog

Mon, 01 Jan 0001 00:00:00 +0000

scafctl Catalog System#

Overview#

scafctl manages artifact lifecycle through a workflow analogous to container images, using OCI artifacts for storage and distribution. This design enables version control, dependency management, and consistent deployment across environments for solutions, providers, auth handlers, and other scafctl artifacts.

Core Concepts#

Artifacts#

The catalog system supports multiple artifact types:

Solutions: YAML configuration files that define resolvers, actions, and dependencies
Providers: Binary executables that provide custom providers using hashicorp/go-plugin over gRPC
Auth Handlers: Binary executables that provide authentication handlers using hashicorp/go-plugin over gRPC
Future artifact types: TBD as the system evolves

Catalogs#

Local catalog: Functions like Docker’s local image store, caching built and pulled artifacts
Remote catalog: Centralized OCI registry with GUI frontend for artifact discovery and distribution

Artifact Identification#

Artifacts are distinguished using OCI media types and annotations:

GCP Auth Handler

Mon, 01 Jan 0001 00:00:00 +0000

GCP Auth Handler Implementation Plan#

Overview#

Implement a builtin GCP auth handler (gcp) following the established patterns from the Entra and GitHub handlers. The handler will support four authentication flows: Application Default Credentials (ADC) for interactive use, Service Account Key for CI/CD, Workload Identity Federation for GKE/cross-cloud, and GCE Metadata Server for cloud-hosted workloads. Service account impersonation will be supported across all flows.

Design Decisions#

Authentication Flows#

Flow	Use Case	Mechanism
ADC (Application Default Credentials)	Interactive CLI use	OAuth 2.0 authorization code + PKCE via browser, with gcloud ADC fallback
Service Account Key	CI/CD pipelines, automation	JWT assertion from JSON key file via `GOOGLE_APPLICATION_CREDENTIALS`
Workload Identity Federation	GKE, cross-cloud (AWS/Azure/OIDC)	STS token exchange for federated external tokens
Metadata Server	GCE, Cloud Run, GKE	Token from `http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token`

Flow auto-detection priority: Workload Identity Federation > Metadata Server > Service Account Key > ADC (stored credentials).

CLI

Mon, 01 Jan 0001 00:00:00 +0000

CLI Usage#

This document describes how to invoke scafctl from the command line. The CLI follows a kubectl-style structure where verbs, kinds, and names are explicit and positional.

The general pattern is:

scafctl <verb> <kind> <name[@version(or constraint)]> [flags]

<verb> describes what you want to do
<kind> identifies the type of object
<name> identifies the object
@version is optional and resolved via the catalog ( or constraint)

Implementation Status#

Command	Status	Notes
`run solution`	✅ Implemented	Requires workflow (errors if no workflow defined; use `run resolver` for resolver-only)
`run resolver`	✅ Implemented	Resolver-only execution for debugging and inspection
`render solution`	✅ Implemented	Includes action-graph and snapshot modes
`get solution/provider/resolver`	✅ Implemented
`explain solution/provider`	✅ Implemented
`config *`	✅ Implemented	view, get, set, unset, add-catalog, remove-catalog, use-catalog, init, schema, validate
`snapshot show/diff`	✅ Implemented
`solution diff`	✅ Implemented	Structural comparison of two solution files
`secrets *`	✅ Implemented	list, get, set, delete, exists, export, import, rotate
`auth *`	✅ Implemented	login, logout, status, token
`resolver graph`	❌ Removed	Use `run resolver --graph` instead
`build solution`	✅ Implemented	Catalog feature
`catalog list/inspect/delete/prune`	✅ Implemented	Catalog management
`catalog save/load`	✅ Implemented	Offline distribution
`eval cel`	✅ Implemented	Evaluate CEL expressions from CLI
`eval template`	✅ Implemented	Evaluate Go templates from CLI
`eval validate`	✅ Implemented	Validate solution files from CLI
`new solution`	✅ Implemented	Scaffold a new solution from template
`lint rules`	✅ Implemented	List all available lint rules
`lint explain`	✅ Implemented	Explain a specific lint rule
`examples list`	✅ Implemented	List available example configurations
`examples get`	✅ Implemented	Get/download an example file
`push solution/plugin`	📋 Planned	Remote catalog feature
`pull solution/plugin`	📋 Planned	Remote catalog feature
`tag solution/plugin`	📋 Planned	Catalog feature
`--catalog` flag	📋 Planned	Catalog feature
Version constraints (`@^1.2`)	📋 Planned	Requires catalog

Core Concepts#

Kinds#

solution
provider
resolver
catalog (planned)

Names and Versions#

Names identify an object within a kind.

Plugins

Mon, 01 Jan 0001 00:00:00 +0000

Plugins#

Purpose#

Plugins are the extension mechanism for scafctl. They allow external binaries to contribute functionality to the system in a controlled, versioned, and discoverable way.

The primary purpose of plugins is to supply providers and auth handlers. “Plugin” is an internal implementation term - users interact with “providers” and “auth handlers” as catalog artifact kinds.

Terminology#

Plugin: Internal term for a go-plugin binary. Not exposed to users.
Provider Artifact: A plugin binary distributed via the catalog that exposes one or more providers. Users push/pull “providers” not “plugins”.
Auth Handler Artifact: A plugin binary distributed via the catalog that exposes one or more auth handlers.

What a Plugin Is#

A plugin is an external process that implements one or more scafctl extension interfaces and communicates with scafctl over RPC.

Testing

Mon, 01 Jan 0001 00:00:00 +0000

Purpose#

Testing in scafctl ensures that solutions behave correctly, deterministically, and safely before performing side effects.

scafctl separates data resolution, transformation, and execution. Solution-level testing requires no mocks — render mode produces a fully concrete execution plan without side effects. At the package level, providers and services use test doubles to isolate external dependencies.

Testing is an outcome of the design, not a separate subsystem.

Core Principles#

All data enters through resolvers
All computation is provider-backed
All side effects are isolated to actions
Render mode produces a fully concrete execution plan

Because of this:

Miscellaneous

Mon, 01 Jan 0001 00:00:00 +0000

Miscellaneous Design Considerations#

This document captures cross-cutting concepts that are intentionally not core primitives, but are required to make scafctl safe, predictable, and operable at scale.

These concerns apply across resolvers, actions, providers, plugins, and solutions.

Implementation Status#

Concern	Status	Notes
Schema and Typing Model	✅ Implemented	Provider `Descriptor` with `Schema` and `OutputSchemas`
Provider Contracts	✅ Implemented	Full descriptor with input/output schemas, capabilities
Provider Capabilities	✅ Implemented	`from`, `transform`, `validation`, `authentication`, `action`
Secrets and Sensitive Data	✅ Implemented	`pkg/secrets` with AES-256-GCM, keychain integration
Secret Redaction	✅ Implemented	`RedactedError`, `--redact` flag on snapshots
Stateless Core	✅ Implemented	Providers are stateless, no persistent state
Error Model	✅ Implemented	Rich error types with location, cause, context
Determinism Rules	✅ Implemented	Resolver purity enforced, `WhatIf` functions declared
Resolver DAG Visualization	✅ Implemented	ASCII, DOT, Mermaid, JSON formats
Action DAG Visualization	✅ Implemented	ASCII, DOT, Mermaid, JSON formats via `--action-graph`
Validation	✅ Implemented	Schema, dependency, type validation
Linting	✅ Implemented	`scafctl lint` with error/warning/info severities
Extensibility (Providers/Plugins)	✅ Implemented	Plugin system for external providers
Render vs Run Separation	✅ Implemented	`scafctl render` vs `scafctl run`
Dry-run Mode	✅ Implemented	`--dry-run` flag, `WhatIf` on Descriptor, `DryRunFromContext()` for provider-level

Schema and Typing Model#

Status: ✅ Implemented in pkg/provider/provider.go

CLI Contributing

Mon, 01 Jan 0001 00:00:00 +0000

CLI Implementation Guide#

This document describes how to implement CLI commands in scafctl. It provides patterns, code examples, and best practices based on the existing codebase.

Architecture Overview#

The scafctl CLI follows a kubectl-style command structure:

scafctl <verb> <kind> <name[@version]> [flags]

The CLI is built using Cobra and organized into a hierarchical command tree:

Functional Testing

Mon, 01 Jan 0001 00:00:00 +0000

Functional Testing#

Purpose#

Functional testing validates that solutions behave correctly by executing scafctl commands against them and asserting on the output. Solution authors define test cases inline in their solution spec. The scafctl test functional command discovers tests, sets up isolated sandboxes, runs builtin and user-defined tests, and reports results.

This is the primary mechanism for validating solutions in CI and during development.

Implementation Status#

Feature	Status	Notes
`test functional` CLI command	✅ Done	`pkg/cmd/scafctl/test/functional.go`
`test list` CLI subcommand	✅ Done	`pkg/cmd/scafctl/test/list.go`
Test spec types	✅ Done	`pkg/solution/soltesting/types.go`
Builtin tests	✅ Done	Parse, resolve, render, lint in `builtins.go`
Command-based test execution	✅ Done	In-process cobra execution via `CommandBuilder`
CEL assertions	✅ Done	`pkg/solution/soltesting/assertions.go`
Regex assertions	✅ Done
Contains assertions	✅ Done
Negation assertions	✅ Done	`notContains`, `notRegex`
Golden file snapshots	✅ Done	`pkg/solution/soltesting/snapshot.go`
Init scripts (exec provider)	✅ Done	`InitStep` with exec provider schema
Test file includes	✅ Done	`TestInclude` discovery source in bundler
Temp directory sandbox	✅ Done	`pkg/solution/soltesting/sandbox.go`
JUnit XML reporting	✅ Done	`pkg/solution/soltesting/junit.go`
Compose support for tests	✅ Done	`mergeTests()` and `mergeTestConfig()` in compose
Parallel test execution	✅ Done	Semaphore-based concurrency control
CEL assertion diagnostics	✅ Done	`pkg/solution/soltesting/diagnostics.go`
Suite-level setup	✅ Done	`testing.config.setup` with base sandbox copy
Test tags and filtering	✅ Done	`--tag` flag, `tags` field on test cases
Per-test environment variables	✅ Done	`env` field on test cases
Cleanup steps	✅ Done	`cleanup` field, runs even on failure
Test inheritance (extends)	✅ Done	`pkg/solution/soltesting/inheritance.go`
Assertion target (stderr)	✅ Done	`target` field: `stdout`, `stderr`, `combined`
File assertions (`__files`)	✅ Done	Diff-based sandbox file change detection
Fail-fast (per-solution)	✅ Done	`--fail-fast` stops remaining tests per solution
Test name validation	✅ Done	Enforced in `TestCase.Validate()`
Selective builtin skip	✅ Done	`SkipBuiltinsValue` with custom unmarshal
In-process command execution	✅ Done	`Root()` with `*RootOptions`, `CommandBuilder`
Concurrency control	✅ Done	`-j` flag, `--sequential` as sugar for `-j 1`
Conditional skip (CEL `skip` expression)	✅ Done	CEL-based runtime skip evaluation
Test retries	✅ Done	`retries` field for flaky test resilience
Suite-level cleanup	✅ Done	`testing.config.cleanup` for teardown after all tests
File size guard	✅ Done	Cap `files[].content` at 10MB to prevent OOM
In-process execution safety	✅ Done	`Root()` accepts `*RootOptions`, no package-level state
Unused template lint warning	✅ Done	`unused-template` lint rule
Solution filtering (`--solution`)	✅ Done	Glob-based solution name filtering
`--filter` solution/test format	✅ Done	`--filter "solution/test-name"` glob support
`--dry-run` flag	✅ Done	Validate test definitions without executing
Suite-level `env`	✅ Done	`testing.config.env` shared across all tests
Binary file content guard	✅ Done	Non-UTF-8 files get `content` set to `"<binary file>"`
Test execution ordering	✅ Done	Alphabetical by name; builtins first
Field max limits	✅ Done	`assertions: 100`, `files: 50`, `tags: 20`, extends depth: 10
Glob zero-match error	✅ Done	Test `files` globs matching zero files produce `error`
Environment precedence chain	✅ Done	process → `testing.config.env` → `TestCase.env` → `InitStep.env`
`TestCase.Validate()`	✅ Done	Comprehensive test case validation method
Extends non-existent error	✅ Done	`extends` referencing non-existent test names is a parse-time error
Tests per solution limit	✅ Done	Max 500 tests per solution
Watch mode (`--watch`)	✅ Done	`fsnotify`-based file watcher in `soltesting/watch.go`
Auto-generated tests (`-o test`)	✅ Done	`pkg/solution/soltesting/generate.go`; wired into `render solution`, `run resolver`, `run solution`

Test Definition#

Location#

Tests are defined under spec.testing.cases in the solution YAML. Like resolvers, tests support the compose mechanism for splitting into separate files.

Future Enhancements

Mon, 01 Jan 0001 00:00:00 +0000

Future Enhancements#

Consolidated index of planned features and future enhancements across all design docs. Each entry links back to the source design doc for full context.

Items marked ✅ have been implemented since this document was originally written.

Actions#

Source: actions.md

✅ Result Schema Validation#

Implemented. Actions can declare a resultSchema with JSON Schema and a resultSchemaMode (error, warn, ignore). Validated at runtime in the action executor. Supports workflow-level defaults. See pkg/action/result_validation.go and pkg/action/executor.go.

Dry-Run & WhatIf

Mon, 01 Jan 0001 00:00:00 +0000

Dry-Run & WhatIf Architecture#

This document describes the two complementary dry-run mechanisms in scafctl and how they interact.

Overview#

scafctl has two distinct dry-run paths:

Mechanism	Scope	Command	How it works
WhatIf (solution-level)	`run solution --dry-run`	Solution dry-run	Resolvers execute normally (side-effect-free); actions are never invoked — each action’s provider generates a WhatIf description
DryRunFromContext (provider-level)	`run provider --dry-run`	Provider dry-run	The provider’s `Execute()` method is called with `DryRunFromContext(ctx) == true`; providers return mock data

Why Two Mechanisms?#

Solution-level dry-run answers “what would this solution do?” — it needs real resolver values to materialize action inputs and generate accurate WhatIf messages. Since resolvers are side-effect-free by design, they run normally.
Provider-level dry-run answers “what would this provider return?” — useful for testing a single provider in isolation. The provider itself decides what mock data to return.

Solution-Level Dry-Run (WhatIf)#

Flow#

┌──────────────────┐ ┌────────────────────┐ ┌─────────────────┐
│ Execute resolvers │────>│ dryrun.Generate() │────>│ WhatIf Report │
│ (real data) │ │ │ │ (JSON/YAML/ │
│ │ │ For each action: │ │ table) │
│ │ │ - Materialize │ │ │
│ │ │ inputs │ │ │
│ │ │ - Call provider's │ │ │
│ │ │ DescribeWhatIf() │ │ │
└──────────────────┘ └────────────────────┘ └─────────────────┘

Resolvers execute normally — they are side-effect-free, so real data is available
dryrun.Generate() builds the action graph and materializes inputs using real resolver data
For each action, Descriptor.DescribeWhatIf(ctx, inputs) is called to get a provider-specific message
Actions are never executed — only their WhatIf descriptions are used

WhatIf on Descriptor#

Providers implement WhatIf on their Descriptor to generate context-specific descriptions:

Solution Provider

Mon, 01 Jan 0001 00:00:00 +0000

Solution Provider#

Date: February 9, 2026

Design Philosophy#

Three guiding principles:

Fail loud by default, opt into silence. Sub-solution failures should be Go errors unless the user explicitly asks for envelope-only reporting. This prevents the most common mistake (forgetting to check status).
Reuse existing types everywhere. The codebase already has ValueRef, get.Interface, resolver.Context, action.ExecutionResult, etc. The solution provider should compose these, not reinvent them.
Separation of loading vs execution. The provider should do one thing — execute a loaded solution. Loading is delegated entirely to get.Interface. This makes testing trivial and keeps the provider focused.

State

Mon, 01 Jan 0001 00:00:00 +0000

State#

Purpose#

State adds optional, per-solution persistence of resolver values across executions. It enables two primary workflows:

Re-run with same data — Execute a solution repeatedly and retain resolved values between runs without re-prompting or re-fetching.
Validation replay — A validation application can replay the exact command with the same flags and verify it produces the same results.

State is opt-in. Solutions without a state block behave exactly as they do today — stateless, deterministic, and self-contained. State does not change the resolver or provider execution model. It adds a persistence layer accessed exclusively through the provider system.

Catalog Build Bundling

Mon, 01 Jan 0001 00:00:00 +0000

Solution File Bundling#

Date: February 9, 2026

Problem Statement#

When a solution is built (scafctl build solution) and pushed to a catalog, only the solution YAML file is stored as a single OCI layer. Three categories of dependencies are lost:

Local file references — template files read by the file provider, sub-solutions used by the solution provider, or other local resources.
Multi-file solution parts — solutions split across multiple YAML files (e.g., resolvers.yaml, workflow.yaml) that compose the complete solution.
Remote catalog dependencies — sub-solutions referenced by catalog name (e.g., deploy-to-k8s@2.0.0) that must be fetched from a registry at runtime.

This means solutions are not portable across machines, teams, or environments.

Output Directory

Mon, 01 Jan 0001 00:00:00 +0000

Output Directory#

Overview#

The --output-dir flag scopes the action/workflow phase to a target directory, creating a clear phase-based separation:

Resolvers always operate in CWD (current working directory) — they gather data
Actions operate in the output directory when --output-dir is set — they produce output

When --output-dir is not set, actions continue using CWD (backward compatible).

Mental Model#

CWD (current working directory)
├── solution.yaml ← parsed by scafctl
├── templates/ ← read by resolvers
│ └── app.yaml.tpl
└── data/ ← read by resolvers
 └── config.json

--output-dir /path/to/output
├── app.yaml ← written by actions
├── config/
│ └── settings.json ← written by actions
└── scripts/
 └── deploy.sh ← written by actions

Phase Semantics#

Phase	Directory	Behavior
Resolver	CWD (always)	`file` provider reads from CWD, `directory` lists CWD, etc.
Action (with `--output-dir`)	Output directory	`file` write goes to output-dir, `directory` mkdir goes to output-dir
Action (without flag)	CWD	Same as today — full backward compatibility

Usage#

CLI Flag#

# Actions write to /tmp/output instead of CWD
scafctl run solution -f solution.yaml --output-dir /tmp/output

# Dry-run with output-dir shows target paths
scafctl run solution -f solution.yaml --output-dir /tmp/output --dry-run

# Run resolvers only (--output-dir accepted but has no effect)
scafctl run resolver -f solution.yaml --output-dir /tmp/output -o json

# Run a specific provider in action mode with output-dir
scafctl run provider file --capability action --output-dir /tmp/output \
 -i '{"operation": "write", "path": "hello.txt", "content": "world"}'

Default Setting#

A default output directory can be configured in the app config so you don’t need to pass the flag every time:

Catalog CLI Design Decision

Mon, 01 Jan 0001 00:00:00 +0000

Catalog CLI Design Decision: Push/Pull Reference Patterns#

Status: Decided — Option B
Created: 2026-02-06
Decided: 2026-02-07
Decision: Keep current --catalog flag approach with config-based default catalog resolution.

Context#

Currently, scafctl catalog push requires a --catalog flag to specify the target registry:

scafctl catalog push my-solution@1.0.0 --catalog ghcr.io/myorg
# Pushes to: ghcr.io/myorg/solutions/my-solution:1.0.0

This differs from docker/podman, which uses full image names:

docker tag my-image ghcr.io/myorg/my-image:1.0.0
docker push ghcr.io/myorg/my-image:1.0.0

We need to decide if we should align with the docker pattern, keep the current approach, or support both.

Working Directory (--cwd)

Mon, 01 Jan 0001 00:00:00 +0000

Working Directory (`--cwd`)#

Overview#

The --cwd (short: -C) global flag changes the logical working directory for all path resolution without mutating the process CWD. It behaves similarly to git -C:

scafctl --cwd /path/to/project run solution -f solution.yaml
scafctl -C /path/to/project run resolver -f demo.yaml -o json

When --cwd is set, all relative paths—including -f, --output-dir, snapshot paths, and auto-discovery—resolve against the specified directory instead of the process CWD.

Architecture#

Context-Based Resolution#

The --cwd flag is injected into the Go context.Context via provider.WithWorkingDirectory(), avoiding global state mutation. This design:

JSON Schema Migration Decision

Mon, 01 Jan 0001 00:00:00 +0000

Provider Schema Migration: Custom SchemaDefinition → JSON Schema#

Status: Implemented
Created: 2026-02-07
Author: (team discussion)

Context#

Provider input and output schemas are currently defined using custom types — SchemaDefinition and PropertyDefinition — in pkg/provider/provider.go. These types were purpose-built early in development and serve their role for simple, flat property definitions.

Meanwhile, the codebase already uses github.com/google/jsonschema-go (v0.4.2) for action result validation (Action.ResultSchema), where it provides full JSON Schema 2020-12 support including $ref, allOf/anyOf/oneOf, nested objects, and more.

File Conflict Strategies

Mon, 01 Jan 0001 00:00:00 +0000

File Conflict Strategies#

Overview#

The file provider currently writes files unconditionally — os.WriteFile() silently overwrites any existing content. This creates problems for scaffolding workflows where solutions are run repeatedly during development: generated files may overwrite user edits, there is no feedback about what changed, and no way to control write behavior per-file.

This design introduces a conflict strategy system (onConflict) to the file provider’s write and write-tree operations. It adds content-based change detection (SHA256 checksums), optional file backups, an append mode with line-level deduplication, and detailed per-file status reporting.

Hugo Guide

Mon, 01 Jan 0001 00:00:00 +0000

Hugo Guide for scafctl#

This guide explains how to set up and use Hugo for the scafctl documentation site.

Prerequisites#

Go 1.21+ installed (Hugo extended is recommended)

Installation#

Option 1: Using Homebrew (macOS)#

brew install hugo

Option 2: Using Go#

go install github.com/gohugoio/hugo@latest

Option 3: Download Binary#

Download from Hugo Releases and add to your PATH.

Verify Installation#

hugo version

Initial Setup (One-time)#

After cloning the repository, initialize Hugo modules and download the theme:

Identity Provider

Mon, 01 Jan 0001 00:00:00 +0000

Identity Provider#

The identity provider exposes authentication identity information from auth handlers. It returns non-sensitive identity data such as claims, authentication status, and identity type. It never exposes tokens or other secrets.

Operations#

Operation	Description	Scope Support
`claims`	Returns identity claims (name, email, subject, etc.)	Yes — parse scoped access token JWT
`status`	Returns authentication status, expiry, identity type	Yes — return scoped token metadata
`groups`	Returns Entra group memberships (ObjectIDs)	No
`list`	Lists all registered auth handlers	No

Inputs#

Field	Type	Required	Description
`operation`	string	Yes	Operation to perform: `status`, `claims`, `groups`, `list`
`handler`	string	No	Auth handler name (e.g., `entra`). Defaults to the first authenticated handler.
`scope`	string	No	OAuth scope for scoped token operations. When set, `claims` and `status` operations mint a token with this scope and return its details instead of stored metadata.

Default Behavior (without scope)#

When no scope is provided, the identity provider reads stored metadata from the auth handler’s local session. This metadata was extracted from the OIDC ID token JWT at login time:

Go Template LRU Cache

Mon, 01 Jan 0001 00:00:00 +0000

Go Template LRU Cache#

Overview#

The pkg/gotmpl package includes a thread-safe LRU (Least Recently Used) cache for compiled Go templates. The cache avoids redundant parsing of identical template content across evaluations, significantly improving performance for solutions that evaluate the same templates repeatedly (e.g., during resolver phases with shared template logic).

Motivation#

Go’s text/template.Parse() is the dominant cost in template evaluation. In large solutions with many resolvers or actions that use similar templates, the same template content is re-parsed on every invocation. The LRU cache stores compiled *template.Template objects keyed by a SHA-256 hash of their content and configuration, eliminating redundant parse operations while bounding memory usage.

Implementation Gaps

Mon, 01 Jan 0001 00:00:00 +0000

Implementation Gaps#

Generated: 2026-02-25

This document tracks features described in design documents that are not yet fully implemented. Fully implemented features are omitted. For complete design specs, see the linked source documents.

Deferred (Explicitly Planned for Future)#

Conditional Retry (`retryIf`)#

Source: actions.md

Retry policies with a retryIf condition to retry only on specific error types. Requires an __error namespace with message, statusCode, code, retryable, and attempt fields.

Matrix Strategy#

Source: actions.md

MCP Server for scafctl Solutions

Mon, 01 Jan 0001 00:00:00 +0000

MCP Server for scafctl Solutions#

Overview#

This document evaluates building a Model Context Protocol (MCP) server for scafctl solutions. An MCP server exposes tools, resources, and prompts over JSON-RPC 2.0 (typically via stdio or SSE) so that AI agents (Claude, Copilot, etc.) can discover and invoke them programmatically.

How an MCP Server Works Internally#

The Big Picture#

An MCP server is a long-running process that sits between an AI agent (e.g., Claude, Copilot) and your application. It speaks a specific protocol (JSON-RPC 2.0) so the AI knows what capabilities are available and how to call them.

MCP Server Implementation Guide

Mon, 01 Jan 0001 00:00:00 +0000

MCP Server Implementation Guide#

This document is the detailed, step-by-step implementation guide for building the MCP server into scafctl. It is the companion to the MCP Server design document which covers the why — this document covers the how.

Prerequisites#

Before starting implementation, the following must be true:

All preparatory refactoring is complete (see mcp-server.md § Completed Preparatory Refactoring )
pkg/mcp/context.go exists with NewContext() and functional options
pkg/cmd/scafctl/run/execute.go exports ValidateSolution(), ExecuteResolvers(), ResolverExecutionConfigFromContext()
pkg/solution/prepare/prepare.go exports Solution() with functional options
pkg/cmd/scafctl/explain/results.go exports BuildSolutionExplanation(), LoadSolution(), LookupProvider()
pkg/cmd/scafctl/get/celfunction/celfunction.go provides the cel-functions command

Decisions Summary#

These decisions were made during planning and are final for this implementation:

MCP Server Enhancements & CLI Parity

Mon, 01 Jan 0001 00:00:00 +0000

MCP Server Enhancements & CLI Parity#

This document is the implementation plan for the next phase of MCP server improvements and the introduction of CLI parity for MCP-only tools. It builds on the existing MCP Server design and Implementation Guide .

Table of Contents#

Motivation
Part 1: CLI Parity — Exposing MCP Tools as CLI Commands
Part 2: New MCP Tools
Part 3: New MCP Prompts
Part 4: New MCP Resources
- Phase 4A: solution://{name}/tests Resource
Part 5: Architecture & Quality Improvements
Implementation Order
Testing Strategy

Motivation#

The MCP server currently exposes 26 tools, 9 prompts, and 5 resources. After analyzing the full codebase, two categories of improvements have been identified:

Mon, 01 Jan 0001 00:00:00 +0000

API Surface Design#

Detailed API surface for the scafctl REST API server. All endpoints use JSON request/response bodies and follow REST conventions.

Base URL#

http://localhost:8080

Version-prefixed endpoints use /{apiVersion}/ (default: /v1/).

Authentication#

Method: Entra OIDC (Azure AD) JWT Bearer tokens
Header: Authorization: Bearer <token>
Public endpoints: Health probes and metrics bypass authentication
Admin endpoints: Require authentication + admin role claim (or localhost-only when auth is disabled)

Response Format#

Success (single resource)#

{
 "fieldA": "value",
 "fieldB": 42
}

Success (collection with pagination)#

{
 "items": [...],
 "pagination": {
 "page": 1,
 "per_page": 100,
 "total_items": 250,
 "total_pages": 3,
 "has_more": true
 }
}

Error (RFC 7807 Problem Details)#

{
 "title": "Bad Request",
 "status": 400,
 "detail": "validation failed: name is required"
}

Naming Conventions#

Layer	Convention	Example
Config (YAML/JSON)	camelCase	`apiVersion`, `shutdownTimeout`
API response fields	snake_case	`per_page`, `total_items`, `has_more`
URL paths	lowercase, kebab-case for multi-word	`/v1/solutions`, `/v1/admin/reload-config`
Query parameters	snake_case	`per_page`, `filter`

Endpoints#

Operational (Root Router — No Auth)#

Method	Path	Description	Status Codes
GET	`/`	API root with HATEOAS links	200
GET	`/health`	Full health check with component status	200
GET	`/health/live`	Liveness probe	200
GET	`/health/ready`	Readiness probe	200, 503
GET	`/metrics`	Prometheus metrics	200

Solutions#

Method	Path	Description	Query Params	Status Codes
POST	`/v1/solutions/run`	Run a solution (resolve + execute actions)	—	200, 400, 422
POST	`/v1/solutions/render`	Resolve inputs without executing actions	—	200, 400, 422
POST	`/v1/solutions/lint`	Lint a solution	—	200, 400
POST	`/v1/solutions/inspect`	Inspect solution structure	—	200, 400
POST	`/v1/solutions/test`	Validate solution against provider registry	—	200, 400
POST	`/v1/solutions/dryrun`	Dry-run a solution (what-if analysis)	—	200, 400, 422

Providers#

Method	Path	Description	Query Params	Status Codes
GET	`/v1/providers`	List providers	`page`, `per_page`, `filter`	200, 400
GET	`/v1/providers/{name}`	Get provider details	—	200, 404
GET	`/v1/providers/{name}/schema`	Get provider schema	—	200, 404

Eval#

Method	Path	Description	Status Codes
POST	`/v1/eval/cel`	Evaluate CEL expression	200, 400
POST	`/v1/eval/template`	Evaluate Go template	200, 400

Catalogs#

Method	Path	Description	Query Params	Status Codes
GET	`/v1/catalogs`	List catalogs	`page`, `per_page`, `filter`	200, 400
GET	`/v1/catalogs/{name}`	Get catalog details	—	200, 404
GET	`/v1/catalogs/{name}/solutions`	List catalog solutions	`page`, `per_page`	200, 404
POST	`/v1/catalogs/sync`	Sync catalogs (planned)	—	200, 400

Schemas#

Method	Path	Description	Query Params	Status Codes
GET	`/v1/schemas`	List schemas	`page`, `per_page`	200
GET	`/v1/schemas/{name}`	Get schema	—	200, 404
POST	`/v1/schemas/validate`	Validate against schema	—	200, 400, 422

Config#

Method	Path	Description	Status Codes
GET	`/v1/config`	Get current config	200
GET	`/v1/settings`	Get runtime settings	200

Snapshots#

Method	Path	Description	Query Params	Status Codes
GET	`/v1/snapshots`	List snapshots (planned)	`page`, `per_page`	200
GET	`/v1/snapshots/{id}`	Get snapshot details (planned)	—	200, 404

Explain & Diff#

Method	Path	Description	Status Codes
POST	`/v1/explain`	Explain a solution	200, 400
POST	`/v1/diff`	Diff solutions	200, 400

Admin#

Method	Path	Description	Authorization	Status Codes
GET	`/v1/admin/info`	Server info	admin role / localhost	200, 403
POST	`/v1/admin/reload-config`	Hot-reload config (planned)	admin role / localhost	200, 403
POST	`/v1/admin/clear-cache`	Clear caches (planned)	admin role / localhost	200, 403

Documentation (Auto-Generated by Huma)#

Method	Path	Description	Status Codes
GET	`/v1/docs`	Interactive API documentation	200
GET	`/v1/openapi.json`	OpenAPI specification (JSON)	200

Common Query Parameters#

Parameter	Type	Description	Default	Constraints
`page`	int	Page number (1-indexed)	1	1–10000
`per_page`	int	Items per page	100	1–1000
`filter`	string	CEL filter expression	—	max 2000 chars

Global Status Codes#

These status codes can be returned by any endpoint, in addition to endpoint-specific codes:

Mon, 01 Jan 0001 00:00:00 +0000

Web API Implementation Plan#

Overview#

Add a Huma +chi -based REST API to scafctl, started via a new scafctl serve command. The API mirrors all major CLI features (run, render, lint, eval, catalog, solutions, providers, config, etc.) with Entra OIDC authentication, Prometheus metrics, OpenTelemetry tracing, audit logging, CEL-based filtering, and admin endpoints.

Architecture follows the jqapi reference implementation: chi router → layered middleware → Huma endpoint registration → handler context with dependency injection. All operations are synchronous request-response initially, with an async task model planned as future work.

Entra ID Authentication Implementation Decision

Mon, 01 Jan 0001 00:00:00 +0000

Entra ID Authentication: Manual Implementation vs MSAL#

Status#

Decided — Manual implementation retained.

Context#

The pkg/auth/entra package implements OAuth 2.0 authentication against Azure Entra ID (formerly Azure AD). A question arose whether to use the official Microsoft Authentication Library for Go (MSAL) instead of the current hand-rolled implementation.

Current Implementation#

The package manually implements all OAuth 2.0 flows using raw net/http POST calls to Azure Entra ID token endpoints. There are zero Azure SDK or MSAL dependencies in the project.