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.

Getting Started

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

Getting Started with scafctl#

This guide will help you get up and running with scafctl in under 10 minutes.

What is scafctl?#

scafctl is a CLI tool for declarative configuration and workflow automation. It uses:

Resolvers to gather and transform data
Actions to perform side effects
Providers as the execution primitives for both

Think of it as a way to define “what you want” (data + operations) in YAML, and let scafctl figure out “how to do it” (dependency order, parallelization, error handling).

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:

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:

Solution Scaffolding Tutorial

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

Solution Scaffolding Tutorial#

This tutorial covers using scafctl new solution to quickly scaffold new solution files with the correct structure, providers, and best practices.

Overview#

The new solution command generates a complete, valid solution YAML file based on your inputs. Instead of writing YAML from scratch (and getting field names wrong), scaffolding gives you a working starting point.

flowchart LR
 A["Parameters<br/>(name, etc)"] --> B["scafctl<br/>new solution"] --> C["Solution<br/>YAML File"]

1. Quick Start#

Generate a Basic Solution#

Bash

scafctl new solution \
 --name my-app \
 --description "My application configuration" \
 --output my-app.yaml

PowerShell

scafctl new solution `
 --name my-app `
 --description "My application configuration" `
 --output my-app.yaml

This generates a valid solution file with:

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:

Resolver Tutorial

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

Resolver Tutorial#

This tutorial walks you through using scafctl resolvers to dynamically resolve configuration values. You’ll learn how to define resolvers, use different providers, handle dependencies, and implement common patterns.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax
Understanding of environment variables

Table of Contents#

Your First Resolver
Using Parameters
Resolver Dependencies
Transformations
Validation
Conditional Execution
Error Handling
Working with HTTP APIs
Common Patterns

Your First Resolver#

Let’s create a simple solution with one resolver that returns a static value.

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:

Run Resolver Tutorial

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

Run Resolver Tutorial#

This tutorial covers the scafctl run resolver command — a debugging and inspection tool for executing resolvers without running actions. You’ll learn how to run all resolvers, target specific resolvers, inspect execution metadata, skip phases, and visualize dependencies.

Prerequisites#

scafctl installed and available in your PATH
Familiarity with resolvers
A solution file with defined resolvers

Table of Contents#

Run All Resolvers
Run Specific Resolvers
Execution Metadata
Skipping Phases
Dependency Graph
Snapshots
Output Formats
Debugging Dependencies
Working with Parameters
Common Workflows

A note on __execution metadata: When using JSON or YAML output, run resolver automatically includes an __execution key containing execution metadata (timing, dependency graph, provider stats). Throughout this tutorial, examples use --hide-execution to keep output focused on resolver values. See Execution Metadata for details on this feature.

Run Provider Tutorial

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

Run Provider Tutorial#

This tutorial covers the scafctl run provider command — a tool for executing individual providers directly without a solution or resolver file. This is useful for testing, debugging, and exploring providers in isolation.

Prerequisites#

scafctl installed and available in your PATH
Familiarity with providers

Table of Contents#

Basic Usage
Passing Inputs
File-Based Inputs
Capabilities
Dry Run
Output Formats
Plugin Providers
Discovering Providers
Common Examples

Basic Usage#

The scafctl run provider command takes a provider name as its first argument. Provider inputs can be passed as positional key=value arguments or via the traditional --input flag:

Actions Tutorial

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

Actions Tutorial#

This tutorial introduces the Actions feature in scafctl, which enables executing side-effect operations as a declarative action graph.

Overview#

Actions are the execution phase of a scafctl solution. While resolvers compute and gather data, actions perform work based on that data.

flowchart LR
 A["Resolvers<br/>(compute)"] --> B["Actions<br/>(execute)"] --> C["Results<br/>(outputs)"]

Key Principles:

Resolvers compute data, actions perform work
All resolvers evaluate before any action executes
Actions can depend on other actions
Actions can access results from completed actions

Quick Start#

1. Hello World#

The simplest action workflow. Create a file called hello-actions.yaml:

Authentication Tutorial

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

Authentication Tutorial#

This tutorial walks you through setting up and using authentication in scafctl. You’ll learn how to authenticate with Microsoft Entra ID, GitHub, and Google Cloud Platform, manage credentials, and use authenticated HTTP requests in your solutions.

Prerequisites#

scafctl installed and available in your PATH
For Entra: Access to a Microsoft Entra ID tenant
For GitHub: A GitHub account (or GitHub Enterprise Server instance)
For GCP: A Google Cloud account
A web browser for completing the device code flow

Table of Contents#

Understanding Auth in scafctl
Logging In
Checking Auth Status
Listing and Sorting Cached Tokens
Using Auth in HTTP Providers
Getting Tokens for Debugging
Configuration
Logging Out
Auth Diagnostics
Troubleshooting

Understanding Auth in scafctl#

Authentication in scafctl follows these principles:

Docker Credential Helper Tutorial

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

Docker Credential Helper Tutorial#

This tutorial shows how to use scafctl as a Docker/Podman credential helper, exposing scafctl’s AES-256-GCM encrypted credential store to the container ecosystem.

Prerequisites#

scafctl installed and available in your PATH
Docker, Podman, or Buildah installed
Familiarity with Authentication Tutorial

Table of Contents#

Overview
Quick Setup
Manual Setup
Per-Registry Configuration
How It Works
Using with Podman/Buildah
Verification
Composing with catalog login
Uninstall
Troubleshooting

Overview#

The Docker credential helper protocol allows external programs to manage registry credentials for Docker, Podman, and Buildah. By using scafctl as a credential helper, you get:

GCP Custom OAuth Client Setup

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

GCP Custom OAuth Client Setup#

By default, scafctl auth login gcp runs a native browser OAuth flow using Google’s well-known ADC client credentials — the same ones used by gcloud auth application-default login. This works out of the box with no gcloud installation required.

You may want to set up your own OAuth client if:

Your organization restricts which OAuth client IDs are allowed
You need specific OAuth consent screen branding or approval
You want full control over the client lifecycle and scopes

Note: If you were previously seeing invalid_grant - reauth related error (invalid_rapt) errors, upgrading scafctl to the latest version resolves this — the native browser OAuth flow is no longer affected by gcloud’s RAPT token expiry.

Eval Tutorial

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

Eval Tutorial#

This tutorial covers using the scafctl eval command group to test CEL expressions, render Go templates, and validate solution files — all without running a full solution.

Overview#

The eval commands are developer tools for quick iteration:

eval cel — Evaluate CEL expressions with inline or file-based data
eval template — Render Go templates against JSON/YAML data

For solution file validation, use the separate scafctl lint command (covered in Section 3 below).

Linting Tutorial

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

Linting Tutorial#

This tutorial covers using scafctl’s lint commands to validate solution files, explore available lint rules, and understand how to fix issues.

Overview#

scafctl includes a built-in linter that checks solution YAML files for:

Schema violations — Invalid field names, wrong types, missing required fields
Best practices — Missing descriptions, unused resolvers, naming conventions
Correctness — Broken resolver references, invalid CEL expressions, circular dependencies

flowchart LR
 A["Solution<br/>YAML"] --> B["scafctl<br/>lint"] --> C["Findings<br/>(warnings, errors)"]

1. Linting a Solution#

Basic Lint#

Bash

scafctl lint -f solution.yaml

PowerShell

scafctl lint -f solution.yaml

If your solution file is in a well-known location (solution.yaml, scafctl.yaml, etc. in the current directory or scafctl//.scafctl/ subdirectories), you can omit -f:

CEL Expressions Tutorial

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

CEL Expressions Tutorial#

This tutorial covers using CEL (Common Expression Language) expressions in scafctl for data transformation, conditional logic, and dynamic configuration.

Overview#

CEL is used throughout scafctl for dynamic evaluation:

Resolver transforms — Compute derived values from other resolvers
Action inputs — Build dynamic commands and configurations
Conditions — Conditionally skip actions with when
forEach — Generate iteration lists dynamically

flowchart LR
 A["Resolver<br/>Data"] -- "_ namespace" --> B["CEL<br/>Expression"] --> C["Result<br/>Value"]

Key principle: In CEL expressions, all resolved values are available under the _ namespace (e.g., _.appName, _.config.port).

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.

REST API Server Tutorial

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

REST API Server#

scafctl includes a built-in REST API server that exposes all major CLI features as HTTP endpoints. The server uses chi for routing and Huma for OpenAPI-compliant endpoint registration.

Starting the Server#

# Start with defaults (port 8080, host 127.0.0.1)
scafctl serve

# Start on a custom port
scafctl serve --port 9090

# Start with TLS
scafctl serve --enable-tls --tls-cert cert.pem --tls-key key.pem

# Custom API version prefix
scafctl serve --api-version v2

Configuration#

The server reads its configuration from the apiServer section of the scafctl config file:

Go Templates Tutorial

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

Go Templates Tutorial#

This tutorial walks you through using Go templates in scafctl to generate structured text output like configuration files, documentation, and code scaffolding. You’ll start with a simple template and progressively learn conditionals, loops, whitespace control, file-based templates, custom delimiters, and multi-file generation.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax
Completion of the Resolver Tutorial and Actions Tutorial

Table of Contents#

Your First Template
Using Conditionals
Iterating Over Lists
Iterating Over Maps
Controlling Whitespace
Loading Templates from Files
Handling Missing Keys
Injecting Additional Data
Using Custom Delimiters
Using tmpl for Dynamic Inputs
Generating Multiple Files with ForEach
Rendering Template Directories
Putting It All Together: README Generator
Using Sprig Functions
Converting Data to HCL with toHcl
Serializing and Parsing YAML with toYaml / fromYaml
DNS-Safe Strings with slugify / toDnsString
Filtering Lists with where / selectField
Inline CEL with cel
Debugging Template Type Errors
Discovering Available Functions

Overview#

scafctl supports Go templates in two ways:

Catalog Tutorial

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

Catalog Tutorial#

This tutorial walks you through using scafctl’s local catalog to build, version, inspect, export, and share solutions. You’ll start by building your first solution into the catalog and progressively work through versioning, cleanup, air-gapped transfers, remote registries, tagging, and advanced bundling with file dependencies.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax
Completion of the Resolver Tutorial

Table of Contents#

Building Your First Solution
Running from the Catalog
Listing and Inspecting
Managing Multiple Versions
Deleting and Pruning
Exporting and Importing
Tagging Artifacts
Remote Registries
Bundling File Dependencies
Verifying and Extracting Bundles
Comparing Bundle Versions

Building Your First Solution#

Let’s build a simple solution and store it in the local catalog so you can run it by name from anywhere.

MCP Server Tutorial

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

MCP Server Tutorial#

This tutorial walks you through setting up scafctl’s Model Context Protocol (MCP) server so that AI agents — GitHub Copilot, Claude, Cursor, Windsurf, and others — can discover and invoke scafctl tools programmatically.

Prerequisites#

scafctl installed and on your $PATH (scafctl version should work)
An MCP-compatible AI client (VS Code with Copilot, Claude Desktop, Cursor, or Windsurf)

What Is the MCP Server?#

The MCP server is a local process that translates between the AI agent’s JSON-RPC protocol and scafctl’s Go library functions. When an AI agent decides to use a tool (e.g., “lint this solution”), it sends a structured request to the MCP server, which calls the same code that the CLI commands use and returns structured JSON results.

Security Hardening

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

Security Hardening Guide#

This guide covers scafctl’s built-in security protections and how to configure them for production environments.

HTTP Provider Security#

Response Body Size Limits#

The HTTP provider limits the amount of data it will read from any single response to prevent denial-of-service via unbounded responses. The default limit is 100 MB.

# config.yaml — adjust the limit
httpClient:
 maxResponseBodySize: 104857600 # 100 MB (default)

The limit applies to both direct requests and each page in paginated requests. If a response exceeds the limit, the provider returns an error rather than consuming unbounded memory.

REST API Server Tutorial

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

REST API Server Tutorial#

This tutorial walks you through starting scafctl’s REST API server and interacting with its endpoints. The API mirrors all major CLI features — solutions, providers, catalogs, schemas, eval, config, and more — over HTTP with OpenAPI documentation.

Prerequisites#

scafctl installed and on your $PATH (scafctl version should work)
curl or any HTTP client for testing

Quick Start#

Start the Server#

scafctl serve

The server starts on http://localhost:8080 by default.

Validation Patterns Tutorial

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

Validation Patterns Tutorial#

Learn how to validate resolver outputs, enforce constraints on inputs, and use schema validation to catch issues early.

Overview#

scafctl offers multiple validation layers that work together to ensure configuration correctness:

block-beta
 columns 4
 block:top:4
 A["Solution YAML"]
 end
 B["Lint<br/>Rules"] C["Schema<br/>Helper Tags"] D["Validate<br/>Provider"] E["Result<br/>Schema"]
 block:bottom:4
 F["Runtime Validation (CEL + Regex)"]
 end

Schema helper tags — provider-level input constraints (type, length, pattern, enum)
Validation provider — runtime regex and CEL-based checks on resolver values
Result schemas — JSON Schema validation of action outputs
Lint rules — static analysis at scafctl lint time

1. Schema-Level Validation with Provider Inputs#

Provider schemas use JSON Schema constraints to reject invalid input before execution.

Provider Output Shapes

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

Provider Output Shapes#

Quick reference for what each built-in provider returns in resolver output — the data shape you can access via _.resolverName in CEL expressions and Go templates.

How Provider Output Works#

When a resolver uses a provider, the resolved value becomes accessible to other resolvers. The output shape determines what fields are available:

flowchart LR
 A["Resolver: api_data<br/>provider: http<br/>output: body, statusCode, headers"] --> B["Resolver: summary<br/>expr: _.api_data<br/>.body.items | size()"]

Tip: Use the MCP tool get_provider_output_shape to query output schemas programmatically, or get_provider_schema for full provider documentation.

Message Provider Tutorial

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

Message Provider Tutorial#

This tutorial covers using the message provider for rich terminal output during solution execution — styled messages with icons, colors, and dynamic interpolation via tmpl:/expr: ValueRefs.

Overview#

The message provider replaces awkward exec + echo patterns with first-class terminal messaging that integrates with scafctl’s --quiet, --no-color, and --dry-run flags.

flowchart LR
 A["Resolver<br/>Data"] --> B["Message<br/>Provider"]
 B -- "styled output" --> C["Terminal<br/>(stdout/stderr)"]
 B -- "data" --> D["Output<br/>{success, message}"]

Key features:

Built-in message types: success, warning, error, info, debug, plain
Custom styling: colors (hex or named), bold, italic, custom icons/emoji
Contextual labels: dimmed [label] prefixes for step tracking (e.g., [step 2/5], [deploy])
Dynamic interpolation via framework tmpl: and expr: ValueRefs (with automatic dependency detection)
Respects --quiet flag (messages suppressed in quiet mode)
Trailing newline control via the newline field
Dry-run awareness via --dry-run

Quick Start#

Step 1: Create the Solution File#

Create a file called message-basics.yaml:

Snapshots Tutorial

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

Snapshots Tutorial#

This tutorial covers using execution snapshots for debugging, testing, and comparing solution runs.

Overview#

Snapshots capture the state of resolver execution — values, timing, status, errors, and parameters — as a JSON file. They’re useful for:

Debugging — Inspect what every resolver produced
Testing — Compare before/after to catch regressions
Auditing — Record what ran and what it produced
Sharing — Send a snapshot to a teammate for review (with redaction for secrets)

flowchart LR
 A["render<br/>solution"] --> B["Snapshot<br/>(JSON)"] --> C["show / diff<br/>commands"]

When to Use Snapshots#

Snapshots are flag-triggered (--snapshot), never automatically created. Here are the real-world scenarios where they provide value:

Functional Testing

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

Functional Testing#

Functional testing lets you define automated tests for your solutions directly in the solution YAML. Tests execute scafctl commands in isolated sandboxes and validate output using assertions, snapshots, and CEL expressions.

This tutorial walks through every feature of scafctl test functional — from basic tests to advanced CI integration.

Writing Your First Test#

Add a testing section to your solution’s spec. Create a file called solution.yaml:

apiVersion: scafctl.io/v1
kind: Solution
metadata:
 name: my-solution
spec:
 resolvers:
 greeting:
 description: A greeting message
 resolve:
 with:
 - provider: static
 inputs:
 value: Hello, World!

 testing:
 cases:
 render-basic:
 description: Verify solution renders successfully
 command: [render, solution]
 assertions:
 - expression: __exitCode == 0
 - contains: greeting

Run the test:

Solution Diff Tutorial

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

This tutorial covers comparing two solution files structurally to understand what changed between versions. The soldiff package detects additions, removals, and modifications across metadata, resolvers, actions, and testing sections.

Overview#

Solution diffing answers the question: “What structurally changed between two versions of a solution?” Unlike git diff which shows text changes, soldiff understands the solution schema and reports meaningful structural differences.

┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ solution-v1 │ │ soldiff │ │ Result │
│ .yaml │ ──► │ .Compare() │ ──► │ (changes, │
│ │ │ │ │ summary) │
│ solution-v2 │ ──► │ │ │ │
│ .yaml │ │ │ │ │
└──────────────┘ └──────────────┘ └──────────────┘

When to Use Solution Diff#

Use Case	Scenario
Code review	Review structural impact of solution YAML changes before merging
Configuration drift	Detect when a deployed solution has drifted from the expected baseline
Refactoring validation	Confirm a refactor didn’t accidentally add/remove resolvers or actions
Version comparison	Compare v1 and v2 of a solution to document what changed

CLI Usage#

Basic Comparison#

Bash

scafctl solution diff -f solution-v1.yaml -f solution-v2.yaml

PowerShell

scafctl solution diff -f solution-v1.yaml -f solution-v2.yaml

Output:

Dry-Run Tutorial

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

Dry-Run Tutorial#

This tutorial covers using --dry-run to preview what a solution execution would do without performing any side effects.

Overview#

Dry-run mode resolves all values and builds an action execution plan, but never executes actions. This gives you a complete picture of what would happen:

flowchart LR
 A["Solution<br/>(.yaml)"] --> B["Dry-Run Generator<br/>⚠️ No side effects!"] --> C["Report<br/>(resolvers, actions, phases)"]

When to Use Dry-Run#

Use Case	Scenario
Pre-flight check	Verify all resolvers produce expected values before executing actions
Action plan review	See the execution order, phases, and dependencies before running
CI validation	Assert resolver outputs in a pipeline without side effects
Debugging	Understand why a solution behaves unexpectedly by inspecting resolved values
Documentation	Generate a report of what a solution does for review or audit

CLI Usage#

Dry-Run a Full Solution#

Bash

scafctl run solution -f solution.yaml --dry-run

PowerShell

scafctl run solution -f solution.yaml --dry-run

This resolves all values and shows the action plan without executing any actions.

Output Directory Tutorial

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

Output Directory Tutorial#

This tutorial walks you through using the --output-dir flag to redirect action output to a specific directory. You’ll learn the phase-based directory model, how resolvers and actions differ in path handling, and how to reference the original working directory with __cwd.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax and solution files
Completion of the Getting Started tutorial

Table of Contents#

Overview
Phase-Based Directory Model
Basic Usage
Using __cwd for Original Directory Access
Combining with Dry-Run
Per-Provider Usage
Default via Configuration
Absolute Paths Are Never Rewritten
Affected Providers
Common Patterns

Overview#

By default, actions resolve relative paths against the current working directory (CWD). The --output-dir flag changes this so actions write to a designated output directory instead, while resolvers continue reading from CWD.

Auto-Discovery Tutorial

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

Auto-Discovery Tutorial#

This tutorial explains how scafctl automatically discovers solution files, making the -f flag optional for most commands.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax and solution files
Completion of the Getting Started tutorial

Table of Contents#

Overview
How Auto-Discovery Works
Search Order
Supported Commands
Examples
Interaction with --cwd
When Auto-Discovery Fails
Best Practices

Overview#

Many scafctl commands accept a -f / --file flag to specify the solution file path. When this flag is omitted, scafctl searches the current directory (or the --cwd target) for a solution file using a well-defined search order.

Configuration Management

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

Configuration Management Tutorial#

This tutorial covers managing scafctl’s application configuration using the config CLI commands.

Overview#

scafctl uses a YAML configuration file to control application behavior including logging, HTTP client settings, resolver timeouts, catalog locations, and more.

Command	Description
`config init`	Create config file
`config view`	View current config
`config get/set`	Read/write values
`config validate`	Validate config
`config schema`	View JSON schema
`config paths`	Show XDG paths

Quick Start#

1. Initialize Configuration#

Create a new config file:

File Provider Tutorial

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

File Provider Tutorial#

This tutorial walks you through using the file provider to read, write, check existence, delete files, and write multiple files at once with write-tree. You’ll learn how to use conflict strategies, backups, append with deduplication, and dry-run mode.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax and solution files

Table of Contents#

Reading Files
Writing Files
Checking File Existence
Deleting Files
Writing Multiple Files (write-tree)
Conflict Strategies
Append with Deduplication
Backups
Per-Entry Overrides in write-tree
CLI Flags
Dry-Run Mode
Common Patterns

Reading Files#

The read operation reads the contents of a file. Create a file called read-file.yaml:

Exec Provider Tutorial

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

Exec Provider Tutorial#

This tutorial walks you through using the exec provider to run shell commands cross-platform. You’ll learn how the embedded POSIX shell works, how to use pipes, environment variables, timeouts, and when to use external shells like bash or PowerShell.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax and solution files
(Optional) bash and/or pwsh installed for external shell examples

Table of Contents#

How It Works
Running Simple Commands
Pipes and Shell Features
Arguments
Environment Variables
Working Directory
Standard Input
Timeouts
Shell Types
Cross-Platform Patterns
Error Handling
Common Patterns

How It Works#

The exec provider uses an embedded POSIX shell (powered by mvdan.cc/sh ) as its default execution engine. This means:

Directory Provider Tutorial

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

Directory Provider Tutorial#

This tutorial walks you through using the directory provider to list, scan, create, remove, and copy directories. You’ll learn how to use filtering, recursive traversal, content reading, and checksums for filesystem-oriented workflows.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax and solution files
A local directory with some files to experiment with

Table of Contents#

Listing Directory Contents
Recursive Traversal
Filtering with Globs and Regex
Reading File Contents
Computing Checksums
Creating Directories
Removing Directories
Copying Directories
Dry Run Mode
Common Patterns

Listing Directory Contents#

The simplest use of the directory provider is listing files and directories in a given path. Create a file called list-dir.yaml:

Logging & Debugging

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

Logging & Debugging Tutorial#

This tutorial covers controlling scafctl’s log output — verbosity, format, destination, and environment variable overrides.

Overview#

By default, scafctl produces no structured log output. Only styled user messages (errors, warnings, success indicators) are shown. This keeps the CLI clean for human users and pipe-friendly for scripts.

When you need to see what’s happening under the hood — debugging a solution, reporting a bug, or feeding structured logs to a log aggregation system — scafctl gives you full control over log verbosity, format, and destination.

HCL Provider Tutorial

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

HCL Provider Tutorial#

This tutorial walks you through using the hcl provider to parse Terraform and OpenTofu configuration files. You’ll learn how to extract variables, resources, modules, outputs, and other block types from HCL content.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax and solution files
Basic understanding of Terraform/OpenTofu configuration syntax

Table of Contents#

Parsing Inline HCL Content
Parsing HCL Files
Multi-File and Directory Support
Extracting Variables
Extracting Resources
Working with Modules
Terraform Block Extraction
Combining with CEL Expressions
Transform Capability
Expression Handling
Common Patterns
Formatting HCL Content
Validating HCL Syntax
Generating HCL from Structured Data
Generating Terraform JSON (.tf.json)

Parsing Inline HCL Content#

The simplest way to use the HCL provider is with inline content. Create a file called parse-hcl.yaml:

Telemetry (Traces, Metrics, Logs)

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

Telemetry Tutorial#

scafctl emits all three OpenTelemetry signals — logs, traces, and metrics. By default, telemetry is silent (noop providers). When you point scafctl at an OTLP endpoint every signal is exported for backend analysis.

Overview#

Signal	Default output	With `--otel-endpoint`
Logs	slog text/JSON → stderr (via `--log-level`)	Also batched via OTLP gRPC
Traces	Disabled (noop)	Exported via OTLP gRPC
Metrics	Prometheus `/metrics` (MCP server)	Also pushed via OTLP gRPC

Configuration#

Flags (per-invocation)#

Bash

# Point at a local OTel Collector
scafctl run solution -f solution.yaml \
 --otel-endpoint localhost:4317 \
 --otel-insecure # disable TLS (development only)

# Override with environment variable instead
OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317 \
 scafctl run solution -f solution.yaml

PowerShell

# Point at a local OTel Collector
scafctl run solution -f solution.yaml `
 --otel-endpoint localhost:4317 `
 --otel-insecure # disable TLS (development only)

# Override with environment variable instead
$env:OTEL_EXPORTER_OTLP_ENDPOINT = 'localhost:4317'
scafctl run solution -f solution.yaml

Flag	Env override	Default	Description
`--otel-endpoint`	`OTEL_EXPORTER_OTLP_ENDPOINT`	(none)	OTLP gRPC endpoint. When unset, tracing is disabled (noop).
`--otel-insecure`	(none)	`false`	Skip TLS verification. Use in local dev only.

Signals in Detail#

Logs#

Logs use the go-logr/logr interface throughout the codebase. The underlying sink is a multiSink that fans out to:

Template Directory Rendering

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

Template Directory Rendering Tutorial#

This tutorial walks you through the recommended pattern for rendering a directory tree of Go templates into output files while preserving the directory structure. You’ll learn how to combine three providers — directory, go-template, and file — in a single solution to scaffold entire projects from templates.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with solution files and Go template syntax

Table of Contents#

Overview
Setting Up Templates
Reading Templates with the Directory Provider
Batch Rendering with render-tree
Writing Files with write-tree
Path Transformation with outputPath
Putting It All Together
Advanced Patterns

Overview#

A common scaffolding task is:

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

Cache Tutorial

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

Managing the Cache#

This tutorial covers how to use scafctl’s cache management commands to view and clear cached data.

What is Cached?#

scafctl caches certain data to improve performance:

Cache Type	Description	Use Case
HTTP Cache	Responses from HTTP provider requests	Avoid repeated network calls
Build Cache	Incremental build fingerprints	Skip unchanged solution rebuilds
Remote Artifact Cache	Auto-cached artifacts from remote catalogs	Offline access to previously fetched solutions

Caching reduces network latency, speeds up builds, and allows offline access to previously fetched resources.

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:

Provider Reference

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

Provider Reference#

This document provides a reference for all built-in providers in scafctl.

Note: All YAML examples in this reference show only the relevant resolver or action snippet. To use them, place each snippet inside a complete solution file with apiVersion, kind, metadata, and spec sections. See the Getting Started tutorial for the full solution structure.

Overview#

Providers are execution primitives used by resolvers and actions. Each provider has capabilities that determine where it can be used:

Extension Concepts

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

Extension Concepts#

scafctl is built on two types of extensions: providers and auth handlers. Each can be delivered as a builtin (compiled into the scafctl binary) or as a plugin (a standalone binary communicating over gRPC).

This page defines the core terminology and links to the detailed development guides.

Terminology#

Term	Definition
Provider	A stateless execution unit that performs a single operation: fetching data (`from`), transforming values (`transform`), validating inputs (`validation`), executing side effects (`action`), or authenticating requests (`authentication`). Providers are the building blocks used inside solution resolvers.
Auth Handler	A stateful authentication manager that handles identity verification, credential storage, token acquisition, and request injection. Auth handlers manage OAuth flows, cache tokens across invocations, and are used by providers (like `http`) to authenticate outgoing requests.
Builtin	An extension compiled directly into the scafctl binary. Builtin extensions are registered at startup and require no external binaries. Contributing a builtin extension means adding code to the scafctl repository.
Plugin	An extension delivered as a standalone executable that communicates with scafctl over gRPC using hashicorp/go-plugin . Plugins run as separate processes, can be written in any gRPC-capable language, and are distributed independently via OCI catalogs, Go modules, or binary releases.
Extension	Umbrella term for any provider or auth handler, whether builtin or plugin.
Capability	A declared feature of a provider (e.g., `from`, `transform`, `action`) or auth handler (e.g., `scopes_on_login`, `tenant_id`). Capabilities let scafctl adapt behavior dynamically without hardcoded knowledge of each extension.

Extension Matrix#

	Builtin	Plugin
Provider	Compiled into scafctl; 16 built-in providers (http, cel, exec…)	Standalone gRPC binary; auto-fetched from OCI catalogs
Auth Handler	Compiled into scafctl; 3 built-in handlers (entra, github, gcp)	Standalone gRPC binary; auto-fetched from OCI catalogs

When to Choose Builtin vs Plugin#

Factor	Builtin	Plugin
Distribution	Ships with scafctl	Distributed independently
Language	Go only	Any language with gRPC support
Dependency management	Part of scafctl’s `go.mod`	Isolated dependencies
Process isolation	Runs in-process	Separate process (crash isolation)
Update cycle	Tied to scafctl releases	Independent release cadence
Use case	Core functionality, general-purpose	Third-party integrations, proprietary logic
Contributing	PR to scafctl repo	Publish to any OCI registry

Key Differences: Providers vs Auth Handlers#

Aspect	Provider	Auth Handler
Interface	2 methods: `Descriptor()`, `Execute()`	8+ methods: `Login()`, `Logout()`, `Status()`, `GetToken()`, `InjectAuth()`, …
State	Stateless — each execution is independent	Stateful — manages cached tokens, refresh tokens, sessions
Used by	Solution resolvers (via `from`, `transform`, etc.)	Providers (e.g., `http` provider calls `InjectAuth()` on requests)
Registry	`provider.Registry` (versioned, overwrite-protected)	`auth.Registry` (name-keyed)
Capabilities	`from`, `transform`, `validation`, `action`, `authentication`	`scopes_on_login`, `scopes_on_token_request`, `tenant_id`, `hostname`, `federated_token`
Plugin artifact kind	`provider`	`auth-handler`

Plugin Communication#

Both provider plugins and auth handler plugins use hashicorp/go-plugin with gRPC:

Provider Development Guide

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

Provider Development Guide#

This guide explains how to create custom providers for scafctl. Providers are the building blocks that perform operations like fetching data, transforming values, validating inputs, and executing actions.

Providers can be delivered in two ways:

	Builtin	Plugin
Where it lives	Compiled into the scafctl binary	Separate executable (any language with gRPC)
Registration	`registry.Register(...)` in `builtin.go`	Discovered at runtime from plugin cache or catalog
Crash isolation	Shares process with scafctl	Isolated process — plugin crash doesn’t take down CLI
Distribution	Ships with scafctl releases	OCI catalog artifact (`kind: provider`) or standalone binary
Interface	`provider.Provider` (2 methods)	`plugin.ProviderPlugin` (3 methods)

Prerequisite: Read the Extension Concepts page for terminology (provider vs plugin vs auth handler).

Auth Handler Development Guide

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

Auth Handler Development Guide#

This guide explains how to create custom auth handlers for scafctl. Auth handlers manage identity verification, credential storage, and token acquisition for identity providers (e.g., Entra ID, GitHub, GCP, Okta, AWS SSO).

Auth handlers can be delivered in two ways:

	Builtin	Plugin
Where it lives	Compiled into the scafctl binary	Separate executable (any language with gRPC)
Registration	`authRegistry.Register(...)` in `root.go`	Discovered at runtime from plugin cache or catalog
Credential storage	Uses `pkg/secrets` (OS keychain)	Plugin manages its own credential storage
Crash isolation	Shares process with scafctl	Isolated process — plugin crash doesn’t take down CLI
Distribution	Ships with scafctl releases	OCI catalog artifact (`kind: auth-handler`) or standalone binary
Interface	`auth.Handler` (8 methods)	`plugin.AuthHandlerPlugin` (7 methods)

Prerequisite: Read the Extension Concepts page for terminology (provider vs auth handler vs plugin).

Plugin Development Guide

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

Plugin Development Guide#

This page is an overview. Detailed plugin development instructions are now part of each extension type’s development guide.

What is a Plugin?#

A plugin is a standalone executable that extends scafctl by communicating over gRPC using hashicorp/go-plugin . Plugins run in separate processes, providing crash isolation and independent distribution.

scafctl supports two types of plugins:

Plugin Type	Artifact Kind	Interface	Guide
Provider Plugin	`provider`	`plugin.ProviderPlugin` (3 methods)	Provider Development Guide — Delivering as a Plugin
Auth Handler Plugin	`auth-handler`	`plugin.AuthHandlerPlugin` (7 methods)	Auth Handler Development Guide — Delivering as a Plugin

Architecture#

flowchart LR
 A["scafctl<br/>- Discovers plugin<br/>- Calls extension<br/>- Manages lifecycle"] <-- "gRPC" --> B["Your Plugin<br/>- Implements gRPC<br/>- Exposes handlers<br/>- Handles execution"]

Each plugin binary exposes one extension type (provider OR auth handler). The handshake cookie determines which type the host expects.

Plugin Auto-Fetching

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

Plugin Auto-Fetching from Catalogs#

This tutorial explains how scafctl automatically fetches plugin binaries from remote catalogs at runtime. You can declare plugin dependencies in your solution, and scafctl will resolve, download, cache, and load them without a prior build step.

Overview#

The plugin auto-fetch flow:

Solution declares Catalog chain Plugin cache Provider
plugin dependencies → resolves version → checks cache → registration
 (local → remote) (cache hit/miss) (gRPC plugin)

Declare plugin dependencies in your solution’s bundle.plugins section
Resolve — scafctl looks up the plugin version in the catalog chain (local first, then remote OCI registries)
Cache — if the binary is already cached locally, it’s reused; otherwise it’s fetched and written to the cache
Load — the cached binary is launched as a gRPC plugin and its providers are registered

Declaring Plugin Dependencies#

Add a bundle.plugins section to your solution:

Multi-Platform Plugin Build Tutorial

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

Multi-Platform Plugin Build Tutorial#

This tutorial walks through building and distributing multi-platform plugin artifacts using OCI image indexes.

Overview#

Plugin artifacts (providers, auth handlers) are platform-specific binaries. To distribute a single plugin that works on multiple OS/architecture combinations, scafctl stores them as an OCI image index (also called a “fat manifest”). At runtime, scafctl automatically selects the correct binary for the current platform.

Supported Platforms#

Platform	Description
`linux/amd64`	Linux x86-64
`linux/arm64`	Linux ARM64 (e.g. AWS Graviton)
`darwin/amd64`	macOS Intel
`darwin/arm64`	macOS Apple Silicon
`windows/amd64`	Windows x86-64

Prerequisites#

scafctl CLI installed
Go toolchain (for cross-compilation)
Plugin source code that builds for multiple platforms

Step 1: Cross-Compile the Plugin#

Use Go’s cross-compilation to build binaries for each target platform:

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.