magus

README

---

title: magus description: A fast cross-platform task orchestrator for polyglot monorepos. Single binary, code as configuration, statically typed, no second toolchain. tags: [magus, readme, task orchestrator, build system, monorepo, polyglot, buzz, affected, cache]

magus

A fast cross-platform task orchestrator for polyglot (mono)repos.

Magus computes affected projects from your changes, caches the results, and runs the minimum rebuild set after a change.

It is a single statically typed binary that takes its configuration as code, with no second toolchain to install.

---

Documentation

Full docs live at eli.gladman.cc/magus.[^docs-source] The major sections:

• Core concepts - Targets, Spells, Charms, Operations, Services
• Running at scale - CI, Daemon, Remote caching, MCP, Telemetry
• Reference - Man pages, Standard library modules, Debugging, Tips and tricks

Install

magus ships as a single self-contained binary. See the Download guide.

---

Development

For the full contributor reference - the Contributing guide, per-project target catalogs (run order + dependency graphs), and the config reference - see the Development page.

Building magus needs Go. The full toolchain - Go itself, plus Node and esbuild for the docs site and TinyGo for the WebAssembly playground - is pinned in mise.toml; mise installs it in one step. From a fresh clone:

git clone https://github.com/egladman/magus
cd magus
mise install           # installs the pinned Go, Node, esbuild, and TinyGo
go build -o magus ./cmd/magus

Only building the magus binary? Go alone is enough and you can skip mise install; you need it for the docs site (magus run generate website) and the playground.

Run the tests through magus itself - the whole point is that magus builds and tests magus:

magus run ci

Project layout

magus/
├── cmd/
│   ├── magus/            CLI entry point
│   ├── magus-utils/      release signing + config-doc generators
│   ├── magus-docs/       stdlib module doc generator
│   └── magus-manpage/    man-page generator
├── internal/             core engine (~30 packages), the notable ones:
│   ├── depgraph/         affected-set computation over the project graph
│   ├── cache/            content-addressed build cache
│   ├── run/              target scheduling and the run hierarchy
│   ├── sandbox/          filesystem + exec isolation for target runs
│   ├── service/          long-running shared service ops (+ serviceident, serviceaudit)
│   ├── ward/             coded op diagnostics (the MGSxxxx wards)
│   ├── mcp/              Model Context Protocol server
│   ├── workspace/        project + magusfile discovery
│   ├── observability/    OpenTelemetry traces and metrics
│   └── ...               (proc, retry, selfupdate, render, report, doctor, describe, ...)
├── gopherbuzz/           the embedded Buzz interpreter
├── std/                  magusfile stdlib (fs, os, http, json, crypto, ...)
├── spells/               built-in language spells (go, rust, typescript, ...)
├── schema/               generated magus.yaml / MAGUS_* config inventory
├── docs/                 documentation source (rendered by `magus run generate website`)
└── website/              docs-site generator (Buzz-based static site)

[^docs-source]: Source: website/.

Documentation

Overview

Package magus is the high-level library for the magus build orchestrator.

Entry points: Open returns a Magus for build/test cycles, Inspect for read-only commands. A Magus runs work via Magus.Run (one target), Magus.RunCI (the configured CI pipeline), and Magus.RunAffected (only projects touched since a baseline). Behavior is tuned with Option values passed to Open/Inspect (e.g. WithLimiter). Limiter caps concurrent spell executions and can be shared across daemon workspaces.

Boundary: the library links the engine-agnostic interp surface and the Buzz VM, but deliberately not the host bindings (interp/bindings) or the Buzz engine backend — cmd/magus blank-imports those. So a script-driven backend (e.g. the spell-backed remote backend) reaches the library only through registered hooks such as cache.RegisterRemoteBackendOpener, never a direct import.

Index

• Constants
• func ApplyUnionSandbox(ctx context.Context, roots []string) error
• func ComposeGraph(ws types.WorkspaceRepository, opts ...ComposeOption) types.GraphOutput
• func DefaultConcurrency() int
• func FindRoot(dir string) (string, error)
• func IgnoreGlob(pattern string) types.IgnorePattern
• func IgnoreLiteral(pattern string) types.IgnorePattern
• func IgnoreRegex(pattern string) types.IgnorePattern
• func Inspect(ctx context.Context, root string, opts ...Option) (types.WorkspaceRepository, error)
• func TargetLabel(targets []types.Target, source string) string
• func WithWorkspaceRegistryContext(ctx context.Context, reg *WorkspaceRegistry) context.Context
• type BindingOption
  • func WithClaim(globs ...string) BindingOption
  • func WithClaimWeight(weight int) BindingOption
  • func WithoutClaim(globs ...string) BindingOption
• type ComposeOption
  • func WithComposeRoots(paths ...string) ComposeOption
  • func WithComposeSpell(name string) ComposeOption
  • func WithGraphHistory(h *forecast.History, target string) ComposeOption
  • func WithGraphInput(g *types.Graph) ComposeOption
  • func WithUpstream() ComposeOption
• type Limiter
  • func NewLimiter(n int) *Limiter
  • func (l *Limiter) Capacity() int
• type Magus
  • func Open(ctx context.Context, root string, opts ...Option) (*Magus, error)
  • func (m *Magus) Affected(ctx context.Context, base string) (*types.AffectedResult, error)
  • func (m *Magus) AffectedFromPaths(ctx context.Context, paths []string) (*types.AffectedResult, error)
  • func (m *Magus) Affinity(ctx context.Context, opts types.InsightOptions) (types.AffinityOutput, error)
  • func (m *Magus) All() []*types.Project
  • func (m *Magus) CleanCache(ctx context.Context, projects ...*types.Project) error
  • func (m *Magus) CleanOutputs(ctx context.Context, projects []*types.Project, dryRun bool) ([]string, error)
  • func (m *Magus) Close() error
  • func (m *Magus) DescribeEvaluatedProjects() types.EvaluatedProjectsOutput
  • func (m *Magus) DescribeGraph() types.TargetGraphOutput
  • func (m *Magus) DescribeProjects() types.ProjectsOutput
  • func (*Magus) DescribeSpells() types.SpellsOutput
  • func (m *Magus) DescribeTarget(t types.Target) (types.EvaluatedTargetsOutput, error)
  • func (m *Magus) DescribeTargets() types.TargetsOutput
  • func (m *Magus) DescribeWorkspaces(cfg types.WorkspaceConfig) types.WorkspacesOutput
  • func (m *Magus) ExpandAffected(ctx context.Context, target string, baseRef string) (targets []types.Target, source string, fellBack bool, err error)
  • func (m *Magus) ExpandCwd(t types.Target) (targets []types.Target, found bool, err error)
  • func (m *Magus) ExpandPath(t types.Target) ([]types.Target, error)
  • func (m *Magus) ExportCache(ctx context.Context, w io.Writer) error
  • func (m *Magus) FindOutputOwner(absPath string) *types.Project
  • func (m *Magus) Get(path string) *types.Project
  • func (m *Magus) Graph() (*types.Graph, error)
  • func (m *Magus) Hotspots(ctx context.Context, opts types.InsightOptions) (types.HotspotOutput, error)
  • func (m *Magus) ImportCache(ctx context.Context, r io.Reader) error
  • func (m *Magus) LogScope(label, source string)
  • func (m *Magus) Ownership(ctx context.Context, opts types.InsightOptions) (types.OwnershipOutput, error)
  • func (m *Magus) Plan(ctx context.Context, target string, opts PlanOptions) (types.ShardPlan, error)
  • func (m *Magus) PruneCache(ctx context.Context, cutoff time.Time, dryRun bool) (removed int, freed int64, err error)
  • func (m *Magus) PruneRemoteCache(ctx context.Context, olderThan time.Duration, keepLast int, dryRun bool) error
  • func (m *Magus) ResolveProjects(targets []types.Target) []*types.Project
  • func (m *Magus) Root() string
  • func (m *Magus) Run(ctx context.Context, targets []types.Target, opts ...RunOption) error
  • func (m *Magus) RunAffected(ctx context.Context, target string, opts ...RunOption) error
  • func (m *Magus) RunCI(ctx context.Context, targets []types.Target, opts ...RunOption) error
  • func (m *Magus) SetGraphObserver(o types.Observer)
  • func (m *Magus) Stream(ctx context.Context, r io.Reader, target string, errFn func(error), ...) error
  • func (m *Magus) TailLog(projectPath, target string) (logPath string, err error)
  • func (m *Magus) Trend(ctx context.Context, opts types.InsightOptions) (types.TrendOutput, error)
  • func (m *Magus) VCSOptions() types.VCSOptions
  • func (m *Magus) Where(dir string) (*types.Project, bool)
• type Option
  • func WithConfigFile(path string) Option
  • func WithLimiter(l *Limiter) Option
  • func WithLoadedConfig(cfg config.Config) Option
  • func WithWorkspaceRegistry(reg *WorkspaceRegistry) Option
• type PlanOptions
• type ProjectOption
  • func WithDependsOn(paths ...string) ProjectOption
  • func WithExclusive() ProjectOption
  • func WithOutputs(paths ...string) ProjectOption
  • func WithSpell(name string, opts ...BindingOption) ProjectOption
  • func WithTarget(name string, opts ...TargetOption) ProjectOption
  • func WithWatchIgnore(patterns ...types.IgnorePattern) ProjectOption
• type ReportWriter
  • func NewReportWriter(dst io.Writer, filter []string) (*ReportWriter, error)
  • func (rw *ReportWriter) Close() error
  • func (rw *ReportWriter) GraphObserver() types.Observer
  • func (rw *ReportWriter) RecordShardTotal(shardID string, nShards int, duration time.Duration) error
• type RunOption
  • func WithBaseRef(ref string) RunOption
  • func WithCharms(charms ...string) RunOption
  • func WithDryRun() RunOption
  • func WithExtraArgs(args []string) RunOption
  • func WithNoFlakeRetry() RunOption
  • func WithRace() RunOption
  • func WithRaceReplay() RunOption
  • func WithReport(rw *ReportWriter) RunOption
  • func WithReportWriter(w io.Writer) RunOption
  • func WithSpellFilter(name string) RunOption
  • func WithStep() RunOption
  • func WithTargetNameNormalizer(n types.TargetNameNormalizer) RunOption
  • func WithWrite() RunOption
• type StreamOption
  • func WithStreamDryRun() StreamOption
  • func WithStreamExtraArgs(args []string) StreamOption
  • func WithStreamNull() StreamOption
• type TargetHandler
• type TargetOption
  • func Exclusive() TargetOption
  • func FailOnDrift() TargetOption
  • func RetryOnFlake() TargetOption
• type WorkspaceRegistry
  • func NewWorkspaceRegistry() *WorkspaceRegistry
  • func WorkspaceRegistryFromContext(ctx context.Context) *WorkspaceRegistry

Examples

• Inspect
• Magus.ExpandAffected
• Open
• WorkspaceRegistry (WithSpell)

Constants

const StreamAllSentinel = "\x00ALL"

StreamAllSentinel is a stream-batch marker that triggers a full-workspace selection. The NUL prefix ensures it cannot collide with a real file path.

Functions

func ApplyUnionSandbox

func ApplyUnionSandbox(ctx context.Context, roots []string) error

ApplyUnionSandbox unions the landlock policies of every workspace root and applies the combined ruleset to the current process exactly once. Roots whose config disables the sandbox still contribute filesystem rules but no binding-layer policy (MGS2011). It is a no-op (returns nil) when no root requests kernel sandboxing.

This is the multi-workspace (daemon) counterpart to the per-workspace sandbox that Run applies. It lives in the library so callers — the CLI daemon in particular — never import internal/sandbox directly: policy assembly and application stay behind one seam, so the two paths cannot drift.

func ComposeGraph

func ComposeGraph(ws types.WorkspaceRepository, opts ...ComposeOption) types.GraphOutput

ComposeGraph assembles the structured graph view. Edges to unknown projects are dropped.

func DefaultConcurrency

func DefaultConcurrency() int

DefaultConcurrency returns the concurrency cap used when no explicit cap is set, resolved by precedence: the MAGUS_CONCURRENCY env var if set to a positive int, then 4 on GitHub-hosted runners (GITHUB_ACTIONS=true and RUNNER_ENVIRONMENT is not self-hosted), then min(NumCPU, 8).

func FindRoot

func FindRoot(dir string) (string, error)

FindRoot walks up from dir (or cwd when empty) to find the nearest workspace root.

func IgnoreGlob

func IgnoreGlob(pattern string) types.IgnorePattern

IgnoreGlob constructs a doublestar-glob ignore pattern.

func IgnoreLiteral

func IgnoreLiteral(pattern string) types.IgnorePattern

IgnoreLiteral constructs a literal ignore pattern matching any path segment at any depth.

func IgnoreRegex

func IgnoreRegex(pattern string) types.IgnorePattern

IgnoreRegex constructs a Go-regexp ignore pattern.

func Inspect

func Inspect(ctx context.Context, root string, opts ...Option) (types.WorkspaceRepository, error)

Inspect discovers the workspace without opening the cache (for introspection commands).

Example

ExampleInspect shows how to discover projects in a workspace without opening the cache. Inspect is the right entry point for read-only commands (list, graph, describe) where cache overhead is unnecessary.

// Create a minimal workspace with one project for illustration.
root, err := os.MkdirTemp("", "magus-example-*")
if err != nil {
	fmt.Println("setup error:", err)
	return
}
defer os.RemoveAll(root)

// A directory is a project if it contains a magusfile.buzz.
projDir := filepath.Join(root, "myapp")
if err := os.MkdirAll(projDir, 0o755); err != nil {
	fmt.Println("setup error:", err)
	return
}
if err := os.WriteFile(filepath.Join(projDir, "magusfile.buzz"), []byte(""), 0o644); err != nil {
	fmt.Println("setup error:", err)
	return
}

ws, err := Inspect(context.Background(), root)
if err != nil {
	fmt.Println("inspect error:", err)
	return
}

for _, p := range ws.All() {
	fmt.Println(p.Path)
}

Output:
myapp

func TargetLabel

func TargetLabel(targets []types.Target, source string) string

TargetLabel returns a one-line summary of a target slice suitable for log headers.

func WithWorkspaceRegistryContext

func WithWorkspaceRegistryContext(ctx context.Context, reg *WorkspaceRegistry) context.Context

WithWorkspaceRegistryContext installs reg in ctx so interpreters can retrieve it.

Types

type BindingOption

type BindingOption = workspace.BindingOption

BindingOption mutates a spell Binding at registration time.

func WithClaim

func WithClaim(globs ...string) BindingOption

WithClaim extends the spell's declared claims with additional globs.

func WithClaimWeight

func WithClaimWeight(weight int) BindingOption

WithClaimWeight sets the binding's claim weight; higher weight wins on overlap, ties go last-wins.

func WithoutClaim

func WithoutClaim(globs ...string) BindingOption

WithoutClaim removes globs from a spell's effective claims.

type ComposeOption

type ComposeOption func(*compose)

ComposeOption configures a ComposeGraph call.

func WithComposeRoots

func WithComposeRoots(paths ...string) ComposeOption

WithComposeRoots restricts the graph to the listed project paths.

func WithComposeSpell

func WithComposeSpell(name string) ComposeOption

WithComposeSpell limits the graph to projects that use the named spell.

func WithGraphHistory

func WithGraphHistory(h *forecast.History, target string) ComposeOption

WithGraphHistory enables per-node DurationMs prediction in ComposeGraph using adaptive CI history for the given target (typically "ci" or "test").

func WithGraphInput

func WithGraphInput(g *types.Graph) ComposeOption

WithGraphInput enables blast-radius enrichment.

func WithUpstream

func WithUpstream() ComposeOption

WithUpstream switches graph direction to upstream (dependents instead of dependencies).

type Limiter

type Limiter struct {
	// contains filtered or unexported fields
}

Limiter is a weighted semaphore that caps concurrent spell executions. Obtain one with NewLimiter and share it across daemon workspaces via WithLimiter.

func NewLimiter

func NewLimiter(n int) *Limiter

NewLimiter creates a Limiter with capacity n. n ≤ 0 defaults to DefaultConcurrency.

func (*Limiter) Capacity

func (l *Limiter) Capacity() int

Capacity returns the configured concurrency cap.

type Magus

type Magus struct {
	// contains filtered or unexported fields
}

Magus is the high-level orchestrator. Not safe for concurrent use. Inspect-constructed workspaces have no cache.

func Open

func Open(ctx context.Context, root string, opts ...Option) (*Magus, error)

Open opens a Magus orchestrator rooted at root with cache and telemetry. It evaluates magusfiles first, so project registration and any remote-cache wiring are set up before the cache is built. Use Inspect for read-only callers that need no cache.

Example

ExampleOpen shows the canonical entry point: open a Magus orchestrator rooted at "." and run a target across every project.

m, err := Open(context.Background(), ".")
if err != nil {
	fmt.Fprintln(os.Stderr, err)
	return
}
targets, err := m.ExpandPath(types.Target{Name: "build"})
if err != nil {
	fmt.Fprintln(os.Stderr, err)
	return
}
if err := m.Run(context.Background(), targets); err != nil {
	fmt.Fprintln(os.Stderr, err)
}

func (*Magus) Affected

func (m *Magus) Affected(ctx context.Context, base string) (*types.AffectedResult, error)

Affected computes projects touched by VCS changes since base.

func (*Magus) AffectedFromPaths

func (m *Magus) AffectedFromPaths(ctx context.Context, paths []string) (*types.AffectedResult, error)

AffectedFromPaths computes the affected set from an explicit file list.

func (*Magus) Affinity

func (m *Magus) Affinity(ctx context.Context, opts types.InsightOptions) (types.AffinityOutput, error)

Affinity is the temporal-coupling lens: projects that change together, with the pairs that lack any declared dependency between them flagged as hidden affinity.

func (*Magus) All

func (m *Magus) All() []*types.Project

func (*Magus) CleanCache

func (m *Magus) CleanCache(ctx context.Context, projects ...*types.Project) error

CleanCache removes all cached build entries for the given projects. Pass no projects to clear the entire cache.

func (*Magus) CleanOutputs

func (m *Magus) CleanOutputs(ctx context.Context, projects []*types.Project, dryRun bool) ([]string, error)

CleanOutputs removes files matched by each project's declared Outputs globs. It returns the list of removed absolute file paths. When dryRun is true, no files are deleted — only the matched paths are collected and returned.

func (*Magus) Close

func (m *Magus) Close() error

Close releases workspace resources (VM pools); cache and limiter are caller-owned.

func (*Magus) DescribeEvaluatedProjects

func (m *Magus) DescribeEvaluatedProjects() types.EvaluatedProjectsOutput

DescribeEvaluatedProjects returns the fully-evaluated project inventory.

func (*Magus) DescribeGraph

func (m *Magus) DescribeGraph() types.TargetGraphOutput

DescribeGraph returns the target dependency graph of each project, extracted statically from its magusfile (no target body is evaluated). Buzz magusfiles are supported; a project on any other engine yields an engine-tagged entry with no nodes until that extractor lands.

func (*Magus) DescribeProjects

func (m *Magus) DescribeProjects() types.ProjectsOutput

DescribeProjects returns the project inventory of the workspace.

func (*Magus) DescribeSpells

func (*Magus) DescribeSpells() types.SpellsOutput

DescribeSpells returns the catalog of registered spells, sorted by name.

func (*Magus) DescribeTarget

func (m *Magus) DescribeTarget(t types.Target) (types.EvaluatedTargetsOutput, error)

DescribeTarget returns the fully-evaluated dispatch plan for t.

func (*Magus) DescribeTargets

func (m *Magus) DescribeTargets() types.TargetsOutput

DescribeTargets enumerates targets known in the workspace.

func (*Magus) DescribeWorkspaces

func (m *Magus) DescribeWorkspaces(cfg types.WorkspaceConfig) types.WorkspacesOutput

DescribeWorkspaces returns the single-entry view of m's workspace. A *Magus is always exactly one workspace; the CLI's `describe workspaces` merges these across the daemon's declared roots when daemon.workspaces is set.

func (*Magus) ExpandAffected

func (m *Magus) ExpandAffected(ctx context.Context, target string, baseRef string) (targets []types.Target, source string, fellBack bool, err error)

ExpandAffected resolves targets for VCS-affected projects; falls back to all projects on VCS failure. fellBack is true precisely when the VCS couldn't compute a definitive set and every project was selected as a safety net — a typed signal callers can act on (e.g. annotate the plan) rather than parsing the free-text source string, which on the fallback path carries the underlying error message.

Example

ExampleMagus_ExpandAffected shows how to compute the VCS-diff affected project set, with automatic fallback to all projects when the VCS command is unavailable (shallow clone, missing binary, etc.).

m, err := Open(context.Background(), ".")
if err != nil {
	fmt.Fprintln(os.Stderr, err)
	return
}
targets, source, _, err := m.ExpandAffected(context.Background(), "test", "")
if err != nil {
	fmt.Fprintln(os.Stderr, err)
	return
}
fmt.Printf("[%s]\n", source)
for _, t := range targets {
	fmt.Println(" ", t.Path)
}

func (*Magus) ExpandCwd

func (m *Magus) ExpandCwd(t types.Target) (targets []types.Target, found bool, err error)

ExpandCwd resolves t for the project containing cwd; found=false when cwd is not inside any project.

func (*Magus) ExpandPath

func (m *Magus) ExpandPath(t types.Target) ([]types.Target, error)

ExpandPath resolves the target pattern to concrete per-project targets; empty or "/" fans out to all.

func (*Magus) ExportCache

func (m *Magus) ExportCache(ctx context.Context, w io.Writer) error

ExportCache writes the entire cache to w as a gzip-compressed tar archive. Returns types.ErrNoCache on Inspect workspaces.

func (*Magus) FindOutputOwner

func (m *Magus) FindOutputOwner(absPath string) *types.Project

FindOutputOwner returns the first project whose declared Outputs globs match absPath. absPath must be an absolute filesystem path. Returns nil when no project claims the path.

func (*Magus) Get

func (m *Magus) Get(path string) *types.Project

func (*Magus) Graph

func (m *Magus) Graph() (*types.Graph, error)

func (*Magus) Hotspots

func (m *Magus) Hotspots(ctx context.Context, opts types.InsightOptions) (types.HotspotOutput, error)

Hotspots is the churn × complexity lens. The project view is the dependency graph heat-coloured by churn (with authors, recency, blast radius, and CI duration on each node); --files ranks individual files by edit frequency weighted by complexity.

func (*Magus) ImportCache

func (m *Magus) ImportCache(ctx context.Context, r io.Reader) error

ImportCache extracts a gzip-compressed tar archive produced by Magus.ExportCache. Returns types.ErrNoCache on Inspect workspaces.

func (*Magus) LogScope

func (m *Magus) LogScope(label, source string)

LogScope emits a scope header through the cache logger. No-op on Inspect workspaces.

func (*Magus) Ownership

func (m *Magus) Ownership(ctx context.Context, opts types.InsightOptions) (types.OwnershipOutput, error)

Ownership is the knowledge-risk lens: author concentration, bus factor, and abandonment (projects gone quiet in the recent half of the window).

func (*Magus) Plan

func (m *Magus) Plan(ctx context.Context, target string, opts PlanOptions) (types.ShardPlan, error)

Plan computes a provider-neutral CI shard plan for the affected project set using target as the CI target (typically "ci"). Adaptive sharding is applied when runtime history is available at the resolved HistoryPath.

func (*Magus) PruneCache

func (m *Magus) PruneCache(ctx context.Context, cutoff time.Time, dryRun bool) (removed int, freed int64, err error)

PruneCache removes entries older than cutoff and GC-collects orphaned blobs.

func (*Magus) PruneRemoteCache

func (m *Magus) PruneRemoteCache(ctx context.Context, olderThan time.Duration, keepLast int, dryRun bool) error

PruneRemoteCache evicts entries from the configured remote cache backend per a retention policy (age and/or newest-N). Errors when no remote backend is wired, the backend can't prune, or it's inactive here. Scalar args keep this public facade free of the internal cache.RetentionPolicy type.

func (*Magus) ResolveProjects

func (m *Magus) ResolveProjects(targets []types.Target) []*types.Project

ResolveProjects resolves targets to project records; unmatched targets are silently dropped.

func (*Magus) Root

func (m *Magus) Root() string

func (*Magus) Run

func (m *Magus) Run(ctx context.Context, targets []types.Target, opts ...RunOption) error

Run executes targets against their projects. Independent pairs run concurrently up to the limiter budget. "ci" is an ordinary magusfile target (compose its pipeline with magus.needs); magus no longer hardcodes a CI chain.

func (*Magus) RunAffected

func (m *Magus) RunAffected(ctx context.Context, target string, opts ...RunOption) error

RunAffected computes the VCS-diff target set and runs target on it.

func (*Magus) RunCI

func (m *Magus) RunCI(ctx context.Context, targets []types.Target, opts ...RunOption) error

RunCI runs the ci target(s) with write mode forced off. "ci" is an ordinary magusfile-defined target; magus keeps it only as the affected-set anchor, not a hardcoded preflight...test chain. The magusfile composes the pipeline order via magus.needs.

func (*Magus) SetGraphObserver

func (m *Magus) SetGraphObserver(o types.Observer)

SetGraphObserver installs an observer on the workspace; pass nil to clear.

func (*Magus) Stream

func (m *Magus) Stream(ctx context.Context, r io.Reader, target string, errFn func(error), opts ...StreamOption) error

Stream reads file-path batches from r and runs target on the affected projects. Builds run synchronously; batches arriving during a build are merged and run after. StreamAllSentinel triggers a full-workspace build. Per-batch errors go to errFn.

func (*Magus) TailLog

func (m *Magus) TailLog(projectPath, target string) (logPath string, err error)

TailLog returns the log-file path of the most recent cache entry for projectPath, optionally restricted to target. Wraps fs.ErrNotExist when not found; types.ErrNoCache on Inspect.

func (*Magus) Trend

func (m *Magus) Trend(ctx context.Context, opts types.InsightOptions) (types.TrendOutput, error)

Trend is the rising/cooling lens: each project's churn in the recent vs earlier half of the window.

func (*Magus) VCSOptions

func (m *Magus) VCSOptions() types.VCSOptions

func (*Magus) Where

func (m *Magus) Where(dir string) (*types.Project, bool)

type Option

type Option = workspace.Option

Option configures Open or Inspect.

func WithConfigFile

func WithConfigFile(path string) Option

WithConfigFile causes the constructor to load magus.yaml from path instead of <root>/magus.yaml.

func WithLimiter

func WithLimiter(l *Limiter) Option

WithLimiter injects a pre-built Limiter (e.g. shared across daemon workspaces). When omitted, Open constructs a private limiter from magus.yaml/Concurrency.

func WithLoadedConfig

func WithLoadedConfig(cfg config.Config) Option

WithLoadedConfig injects an already-parsed configuration, bypassing the default magus.yaml discovery. Env-var and flag overrides should be applied before calling this.

func WithWorkspaceRegistry

func WithWorkspaceRegistry(reg *WorkspaceRegistry) Option

WithWorkspaceRegistry injects a pre-built WorkspaceRegistry, replacing the default one.

type PlanOptions

type PlanOptions struct {
	// MaxShards caps the number of CI shards. -1 = unlimited; 0 uses the
	// value from magus.yaml (CI.MaxShards).
	MaxShards int
	// RunnerPoolBudget limits cross-shard concurrency. 0 = unlimited.
	RunnerPoolBudget int
	// HistoryPath overrides the configured history_path when non-empty.
	HistoryPath string
}

PlanOptions configures a Magus.Plan call.

type ProjectOption

type ProjectOption = workspace.ProjectOption

ProjectOption mutates a Project at registration time. A non-nil error aborts Open.

func WithDependsOn

func WithDependsOn(paths ...string) ProjectOption

WithDependsOn adds upstream project paths as dependencies (repo-relative or project-relative).

func WithExclusive

func WithExclusive() ProjectOption

WithExclusive marks a project as must-not-run-alongside-peers (also serializes multi-spell fan-out).

func WithOutputs

func WithOutputs(paths ...string) ProjectOption

WithOutputs declares the project-relative file globs this project produces.

func WithSpell

func WithSpell(name string, opts ...BindingOption) ProjectOption

WithSpell registers a built-in spell by name; multiple calls fan out in parallel (sequential with WithExclusive).

func WithTarget

func WithTarget(name string, opts ...TargetOption) ProjectOption

WithTarget attaches a behavioural policy to the named target; multiple calls are merged.

func WithWatchIgnore

func WithWatchIgnore(patterns ...types.IgnorePattern) ProjectOption

WithWatchIgnore appends patterns to the project's watch ignore list; malformed patterns error at Open.

type ReportWriter

type ReportWriter struct {
	// contains filtered or unexported fields
}

ReportWriter is an async JSONL event sink for run telemetry. Create one with NewReportWriter, pass it to Run via WithReport, and close it after the run completes.

func NewReportWriter

func NewReportWriter(dst io.Writer, filter []string) (*ReportWriter, error)

NewReportWriter constructs a ReportWriter that writes JSONL events to dst. filter is an optional list of event-type terms; an empty or nil slice disables filtering (all events pass through).

func (*ReportWriter) Close

func (rw *ReportWriter) Close() error

Close flushes and closes the writer. Must be called after the run finishes.

func (*ReportWriter) GraphObserver

func (rw *ReportWriter) GraphObserver() types.Observer

GraphObserver returns an types.Observer that records graph-traversal events to this writer. Pass the result to Magus.SetGraphObserver.

func (*ReportWriter) RecordShardTotal

func (rw *ReportWriter) RecordShardTotal(shardID string, nShards int, duration time.Duration) error

RecordShardTotal appends a shard-level wall-clock observation (job start → last project end) for adaptive CI forecast. Call after the run completes when running in a CI matrix; shardID and nShards come from --shard / --n-shards.

type RunOption

type RunOption func(*run)

RunOption configures a Magus.Run, Magus.RunCI, or Magus.RunAffected invocation.

func WithBaseRef

func WithBaseRef(ref string) RunOption

WithBaseRef overrides MAGUS_VCS_BASE_REF for RunAffected invocations.

func WithCharms

func WithCharms(charms ...string) RunOption

WithCharms sets execution charms propagated to spells via context.

func WithDryRun

func WithDryRun() RunOption

WithDryRun prints what would run without invoking any handler.

func WithExtraArgs

func WithExtraArgs(args []string) RunOption

WithExtraArgs forwards args to spells via project.WithExtraArgs.

func WithNoFlakeRetry

func WithNoFlakeRetry() RunOption

WithNoFlakeRetry disables the flake auto-retry logic.

func WithRace

func WithRace() RunOption

WithRace enables race-condition diagnostics (MGS4001/4002/4004). Diagnostic only.

func WithRaceReplay

func WithRaceReplay() RunOption

WithRaceReplay enables determinism replay (MGS4003). Compose with WithRace for MGS4001/4002/4004.

func WithReport

func WithReport(rw *ReportWriter) RunOption

WithReport attaches rw to receive one JSONL event per executed target. Mutually exclusive with WithReportWriter.

func WithReportWriter

func WithReportWriter(w io.Writer) RunOption

WithReportWriter streams one JSONL event per target to w; the run engine constructs and closes the report.Writer around it.

func WithSpellFilter

func WithSpellFilter(name string) RunOption

WithSpellFilter restricts Run to projects that have the named spell.

func WithStep

func WithStep() RunOption

WithStep enables per-subprocess stepping mode; forces Concurrency=1.

func WithTargetNameNormalizer

func WithTargetNameNormalizer(n types.TargetNameNormalizer) RunOption

WithTargetNameNormalizer overrides how exported-function identifiers are converted to target names. Defaults to kebab-case via lo.KebabCase.

func WithWrite

func WithWrite() RunOption

WithWrite enables mutating mode for format/generate targets; sugar for the "rw" charm.

type StreamOption

type StreamOption func(*streamOpts)

StreamOption configures a [Stream] invocation.

func WithStreamDryRun

func WithStreamDryRun() StreamOption

WithStreamDryRun prints what would run without invoking handlers.

func WithStreamExtraArgs

func WithStreamExtraArgs(args []string) StreamOption

WithStreamExtraArgs forwards args to spells via project.WithExtraArgs.

func WithStreamNull

func WithStreamNull() StreamOption

WithStreamNull expects NUL-separated paths and double-NUL batch boundaries.

type TargetHandler

type TargetHandler func(context.Context, *types.Project) error

TargetHandler runs one target on one resolved project. It is the single executor seam the run pipeline schedules: the same handler serves both a real run and a dry run - types.WithTrace(ctx) switches it, so under a tracing context the effect boundary (proc/run.Exec, fs, net) records each op's intent and skips it instead of executing. One path, two modes: no separate dry-run executor, just a tracing context over this one contract. (The in-browser evaluator in internal/dry is a different thing - it takes raw source, never a resolved *Project, so it sits before this seam and cannot implement it; see that package's doc.)

type TargetOption

type TargetOption = workspace.TargetOption

TargetOption sets a per-target execution-policy field at registration time.

func Exclusive

func Exclusive() TargetOption

Exclusive runs the target alone — no other target runs concurrently while it does.

func FailOnDrift

func FailOnDrift() TargetOption

FailOnDrift enables the drift gate: fail if the working tree is dirty after the target.

func RetryOnFlake

func RetryOnFlake() TargetOption

RetryOnFlake enables flake detection and auto-retry for this target.

type WorkspaceRegistry

type WorkspaceRegistry = workspace.WorkspaceRegistry

WorkspaceRegistry holds project-option overrides and target policies for a single Open.

Example (WithSpell)

ExampleWorkspaceRegistry_withSpell shows the recommended way to attach a spell to a project using the string-name API. The registry is passed to Inspect or Open via WithWorkspaceRegistry.

reg := NewWorkspaceRegistry()
reg.RegisterProject(
	"api",
	WithSpell("go"),
)
// pass reg to Inspect or Open:
// Inspect(ctx, root, WithWorkspaceRegistry(reg))

func NewWorkspaceRegistry

func NewWorkspaceRegistry() *WorkspaceRegistry

NewWorkspaceRegistry returns an empty WorkspaceRegistry.

func WorkspaceRegistryFromContext

func WorkspaceRegistryFromContext(ctx context.Context) *WorkspaceRegistry

WorkspaceRegistryFromContext returns the WorkspaceRegistry from ctx, or nil.