magus

README

magus

A fast, cross-platform task orchestrator for polyglot monorepos. One statically linked binary, config as code, no second toolchain to install.

Change a file and magus works out which projects it reaches, rebuilds only those, and caches every result so the same work never runs twice.

Why magus exists

The tools you run in a monorepo, you run all day. Build, test, lint, switch branches, do it again. So friction compounds fast. A few wasted seconds a run, one flaky target, a teammate's botched merge that starts failing on your checkout, and now you are babysitting the build instead of shipping the feature. Tooling this central earns its place by getting out of the way. It should be fast, and genuinely good at the narrow thing it does.

The other half of the job is knowledge. Monorepos outgrow the people and tools reading them. Humans grep; AI agents grep faster and guess more confidently; both drown in generated files, legacy patterns, and dependency chains nobody holds in their head. magus takes the opposite bet. The build tool already has to know the repo precisely, down to every project, every target's inputs and declared outputs, and what a diff reaches, so it hands that knowledge back as answers instead of leaving everyone to rediscover it.

That is the rule for the whole surface. Every verb answers a question, deterministically, from declared sources: which projects a change affects, whether a file is generated and by what, where a symbol is used, how two things relate. Nothing in magus decides for you, plans for you, or injects itself into your workflow. Answering is the tool's job; deciding is yours, or your agent's.

The same discipline serves both audiences. A teammate on day one and an AI agent in a fresh session have the same problem: a repo they cannot yet trust their guesses about. magus gives them the same fix. Query the knowledge graph instead of grepping, run targets instead of raw tools, and let magus affected ci prove what a change touched. For agents, see Agents.

How it works

Four ideas carry most of the tool. Each has a deeper page; this is the short version.

Affected sets

magus keeps a dependency graph of your projects and knows which files each target reads. Change a file and magus affected <target> runs only the projects that change can reach, in dependency order. magus affected ci runs the full pipeline over that set, so CI does the least work a change requires and still catches breakage in a project you never opened. See CI.

Content-addressed caching

Every target declares its inputs and outputs. magus hashes the inputs, and if it has already seen that hash it replays the stored output instead of running the work again. The cache is a plain content-addressed store on disk (SHA-256): the input hash is the key, and the stored outputs are addressed by their own content hash, so a replay is a byte-for-byte reproduction of the recorded run.

The knowledge graph

Because magus already knows every project, target, spell, and how they relate, it exposes that as a graph you can query. magus query "kind:target lint" finds nodes, magus explain <node> shows a node's edges and what reaches it, and magus refs <symbol> lists where a symbol is defined and used from a SCIP index.[^scip] The same graph answers "is this file generated," "what does my diff touch," and "how do these two things relate" without grepping. See the knowledge graph.

One vocabulary

magus names a thing once and reuses the name everywhere, in the CLI, the config, and the graph. A target is a unit of work such as build, test, or lint. A spell is a language adapter that supplies a target's operations (the go spell provides go-test; the buf spell provides buf-lint). A charm is a modifier applied to a run, like rw for read-write or cd for a working directory. An op is a single tool invocation. Learn the four words and the rest of the surface reads the same way.

Getting started

Install

magus ships as a single self-contained binary, so there is no second toolchain to install. See the Download guide.

A first look

Point magus at a repo that has a magusfile.buzz at its root,[^playground] and each command returns an answer and stops:

magus ls                                  # which projects exist
magus run test                            # run a target, cache the result
magus affected ci                         # the pipeline, over only what your diff reaches
magus query "kind:spell"                  # what the graph knows
magus describe file docs/gen/index.html   # is this file generated, and by what

Nothing here plans a workflow or decides for you. describe file tells you a path is a generated output so you skip its diff; affected ci tells you which projects a change reaches so you run no more than that.

Architecture

One process (magus server start) exposes the workspace through two standing listeners, one per audience, and every browser page is a separate static asset; the binary serves no HTML. A third listener is raised only on demand: "share to phone" opens a time-boxed LAN listener that serves the read-only console to a phone on the same network, then tears itself down. The diagram below is the whole system: the clients, the transports and their guards, the shared in-memory state, the background jobs and knowledge-graph pipeline that keep it warm, and how the browser console reaches (or does without) the daemon.

flowchart LR
    cli(["Local CLI and shell<br/>magus run, status, query"])
    agent(["AI agents<br/>Claude Code, Desktop, IDE"])
    probe(["kubelet and scripts"])
    vcs(["git hook / magus server sync"])
    phone(["Phone on the LAN<br/>read-only console viewer"])

    subgraph pwa["Progressive web app - project: docs/ (static assets, loopback-locked, binary serves NO HTML)<br/>eli.gladman.cc/magus or self-hosted"]
        dash["Dashboard"]
        gexp["Graph Explorer"]
        logs["Log Viewer"]
        actv["Activity Trail"]
    end
    serve["Ephemeral loopback server<br/>graph open --serve (Safari fallback)"]

    sources["Declared sources<br/>magusfiles, docs, buzz,<br/>SCIP index, git history, CODEOWNERS"]
    gjson["Graph export -o json<br/>docs/graph.json (offline PWA)<br/>MAGUS.md (routing index)"]

    subgraph daemon["magus daemon - one process, magus server start (project: root Go module, cmd/magus + internal/*)"]
        sock["Unix domain socket<br/>proc RPC, private 0700<br/>internal/proc"]

        subgraph http["HTTP server on mcp.address, 127.0.0.1:7391<br/>internal/daemon, internal/handler/*, internal/httpx"]
            guards{{"DNS-rebind + Bearer token + CORS<br/>internal/httpx, internal/auth"}}
            mcpr["/mcp<br/>MCP Streamable HTTP + SSE<br/>internal/handler/mcp"]
            apir["/api/v1<br/>graph, status, events, insight<br/>internal/handler/{graph,status}"]
            conn["/magus.metrics.v1<br/>/magus.activity.v1 (Connect)<br/>internal/handler/{metrics,activity}"]
            sharep["/api/v1/share (POST)<br/>loopback-only trigger + bearer<br/>internal/daemon, internal/share"]
            health["/livez /readyz /healthz<br/>UNGUARDED"]
        end

        lan["Ephemeral LAN listener - on demand, time-boxed 15m<br/>read-only share token, same-origin console (CORS never engages)<br/>console static + status/events/insight/outputs + activity/metrics<br/>NO /mcp, NO share endpoint, NO mutating routes<br/>internal/share"]

        subgraph jobs["Background jobs<br/>internal/file/watch, internal/proc"]
            watch["File watchers<br/>graph invalidate + SSE"]
            idx["SCIP auto-indexer"]
            job["Graph-build job<br/>fire-and-forget, coalesced"]
        end

        subgraph st["Shared daemon state<br/>internal/knowledge, cache, service, trail"]
            pool[("Concurrency pool")]
            ws[("Workspace registry<br/>warm knowledge graph, SCIP, cache")]
            runs[("Run registry")]
            svc[("Service registry")]
            trail[("Activity trail")]
            otel[("OTel provider")]
        end
    end

    cli -->|"Unix socket: adopt run/affected, status"| sock
    cli -->|spawns| serve
    agent -->|"MCP over HTTP, bearer token"| guards
    probe -->|httpGet| health

    dash -->|"status + events (SSE), metrics + activity, bearer"| guards
    gexp -->|"graph + events (SSE), bearer"| guards
    logs -->|"activity (Connect), bearer"| guards
    actv -->|"activity (Connect), bearer"| guards

    cli -.->|"snapshot: graph / output via URL fragment"| pwa
    serve -.->|"graph blob (#src)"| gexp

    guards --> mcpr
    guards --> apir
    guards --> conn
    guards --> sharep
    dash -->|"share to phone, bearer"| guards
    sharep -->|"mints read-only token, opens"| lan
    phone -->|"same-origin, read-only share token"| lan
    lan -->|"read-only views"| ws
    health -.->|"reads status via"| sock

    sock -->|"dispatch, concurrency"| pool
    sock -->|"loaded workspaces"| ws
    sock -->|"host shared services"| svc
    mcpr -->|"query, describe, run"| ws
    apir -->|"graph, events, insight"| ws
    apir -->|"status: live runs"| runs
    conn -->|"derived metrics"| otel
    conn -->|"agent activity"| trail

    vcs -->|"submit job, Unix socket"| sock
    sock -->|"run background job"| job
    job -->|"rebuild + reindex"| ws
    watch -->|"invalidate warm graph"| ws
    watch -->|"SSE graph event"| apir
    idx -->|"refresh SCIP index"| ws
    sources -->|"extract shards"| ws
    ws -->|"graph export -o json"| gjson
    gjson -.->|"offline graph (site default)"| gexp

    classDef client fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a;
    classDef site fill:#ccfbf1,stroke:#14b8a6,color:#134e4a;
    classDef unix fill:#dcfce7,stroke:#22c55e,color:#14532d;
    classDef httproute fill:#ffedd5,stroke:#f97316,color:#7c2d12;
    classDef guard fill:#fee2e2,stroke:#ef4444,color:#7f1d1d;
    classDef health fill:#fef9c3,stroke:#ca8a04,color:#713f12;
    classDef store fill:#ede9fe,stroke:#8b5cf6,color:#4c1d95;
    classDef job fill:#e0e7ff,stroke:#6366f1,color:#312e81;

    class cli,agent,probe,vcs,phone client;
    class dash,gexp,logs,serve,lan site;
    class sock unix;
    class mcpr,apir,conn,sharep httproute;
    class guards guard;
    class health health;
    class pool,ws,runs,svc,trail,otel store;
    class sources,gjson store;
    class watch,idx,job job;

How to read the diagram

The colors group the system by role, and each region is tagged with the Go package or project that owns it, so the diagram doubles as a code map: the runtime is the root module (cmd/magus plus internal/*), the browser console is the docs/ project, and the wire contracts are the proto/magus protobufs.

Green is the Unix domain socket, the local control plane: it dispatches run/affected into one shared concurrency pool, answers magus status, and adopts nested magus calls. Fast and private (0700); the local CLI and the liveness/readiness probes use it.

Orange is the HTTP server on mcp.address, for clients that cannot reach a Unix socket. It carries MCP for agents at /mcp, the read-only /api/v1 console routes, Connect services for metrics and the activity trail, and one bearer-gated job-control service for maintenance jobs - the daemon's only mutating surface. Its request and response types are the proto/magus protobufs, generated by buf and served over Connect/JSON.

Red is the guard chain every HTTP route but health passes through: a DNS-rebind host check, a bearer token (the cli token plus named connector tokens), and CORS scoped to the site and loopback origins.

Yellow is the health routes, left unguarded so a kubelet can probe them; they answer by querying the same socket. See container probes.

Purple is shared, warm daemon state: the knowledge graph and SCIP index in the workspace registry, plus the runs, services, metrics, and trail registries, and the graph's own declared inputs and exports.

Indigo is the background jobs that keep that state fresh without a foreground command: file watchers invalidate the warm graph and push an SSE event to the console, a throttled SCIP indexer keeps symbols current, and a branch switch fires the git hook, which submits one coalesced graph-build job over the socket.

Teal is the browser console, four static surfaces on the daemon, covered in The browser console below.

The graph itself is assembled from declared sources as shards (the magusfile registry, docs, @symbols from SCIP, @vcs from git history, CODEOWNERS). magus graph export -o json writes the committed docs/graph.json that the offline console loads, and magus describe graph -o markdown writes the MAGUS.md routing index; live, the daemon serves the same graph byte-identical at /api/v1/graph.

Because the two listeners are separate, they can diverge: the socket can be healthy while the HTTP/MCP endpoint failed to bind, which is why magus status reports each one on its own line.

The browser console

magus is fully featured from the terminal, so everything here is optional. Alongside the CLI, the daemon can drive four read-only browser surfaces.

Want to see it first? Open the live demo: no install, no daemon. It fills the dashboard with synthesized activity, streams a build into the log viewer, and lets you jump between all four surfaces in demo mode. Everything below runs against your own daemon instead.

The four surfaces

The four surfaces ship as one console app; each link below opens it on the matching surface.

• Dashboard shows live daemon health, the concurrency pool, running targets, and cache activity.[^app-dashboard]
• Graph Explorer navigates targets, spells, and their dependency graph (magus graph open).[^app-graph]
• Log Viewer reads or streams any past run's captured output (magus query output <ref> --open).[^app-logs]
• Activity Trail shows the daemon's recent actions: MCP calls, background jobs, and config changes.[^app-activity]

How it stays on your machine

These are add-ons, not a runtime you depend on. Two decisions keep them that way.

The binary serves no HTML

magus never embeds a web server that ships a UI. The pages are a separate static site (built under docs/gen/, hosted at eli.gladman.cc/magus, or self-hosted from any file server). All the daemon exposes over loopback is a small API - read-only views (/api/v1/...), one bearer-gated job-control service for maintenance jobs, and the MCP endpoint. There is no page serving.

Your data never leaves the loopback

The hosted page talks only to 127.0.0.1/[::1], a loopback lock it enforces before any request, or it receives your graph inline through a URL fragment. Nothing is uploaded. You can drop the UI entirely: set console.enabled: false and the daemon runs fine without it, serving no browser API at all. See the Console reference.

Working with AI agents

magus treats an AI agent and a new teammate as the same kind of user: someone who cannot yet trust their guesses about the repo. It ships an agent surface built on the knowledge graph, so an agent asks magus instead of grepping and guessing.

• Installable skills teach an agent to query the graph, run work through targets, and triage generated files. Install them with magus agent install claude (or codex, opencode).
• The committed MAGUS.md is a routing index, regenerated from the graph, that points an agent at the exact query for a given question.
• The MCP server the daemon exposes lets an agent call magus tools directly over the protocol rather than shelling out.[^mcp]

Full detail, including which tools exist and how to connect, is on the Agents page.

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, Output references, Tips and tricks

Inside a workspace, the entry point is the committed MAGUS.md: a generated routing index of the workspace's projects, targets, and the exact knowledge-graph queries that answer questions about them. Projects can carry their own (this repo commits one for gopherbuzz/ and docs/), scoped to that project. They are generated by magus describe graph -o markdown via the generate target; regenerate them, never hand-edit.

Contributing

For the full contributor reference, see the Development page: the Contributing guide, per-project target catalogs (run order and dependency graphs), and the config reference. The architecture diagram above tags each runtime component with the package it lives in, which is the quickest map of where code goes.

Building from source

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:

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 docs) and the playground.

Running the tests

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

magus run ci

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

[^playground]: Magusfiles are written in Buzz. You can run it in your browser, no install, at the Playground; the standard library modules are the API reference.

[^scip]: SCIP is Sourcegraph's code-index format. magus indexes on its own once a project uses the scip op, stores the index in the cache, and refreshes it in the background; the knowledge graph page covers the symbol layer and the @symbols shard.

[^app-dashboard]: What the tiles mean, and the metrics behind them: Telemetry and the daemon page.

[^app-graph]: The same graph the CLI queries, drawn. See magus graph for the verbs and knowledge graph for the schema.

[^app-logs]: A run's output is addressed by a short reference ID, which is what <ref> is above. See output references.

[^mcp]: Tool list, transport, and how to connect an agent: MCP.

[^app-activity]: The trail is the daemon's own record, kept in memory per workspace. See the daemon page.

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 BuildGlobalKnowledgeGraph(ctx context.Context, ws types.WorkspaceRepository, cfg config.Config, ...) (*knowledge.Graph, error)
• func BuildKnowledgeGraph(ctx context.Context, ws types.Describer, root string, cfg config.Config, ...) (*knowledge.Graph, 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 MergeWorkspaceSymbols(ctx context.Context, ws types.Describer, root string, cfg config.Config, ...) error
• func MergeWorkspaceSymbolsForRef(ctx context.Context, ws types.Describer, root string, cfg config.Config, ...) 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 Daemon
• 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) BeginInvocation(ctx context.Context, cmd journal.Command, magusVersion string, ...) (context.Context, func(error))
  • func (m *Magus) CacheDir() string
  • func (m *Magus) CacheDiskBytes() int64
  • func (m *Magus) CacheStats() cache.Stats
  • 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) DescribeCharms(defaults []string) types.CharmsOutput
  • func (m *Magus) DescribeEvaluatedProjects() types.EvaluatedProjectsOutput
  • func (m *Magus) DescribeFiles(paths []string) types.FilesOutput
  • 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) InvocationByID(inv string) (journal.Invocation, error)
  • func (m *Magus) KnowledgeGraph(ctx context.Context, refresh bool) (*knowledge.Graph, error)
  • func (m *Magus) KnowledgeGraphHealthy() (watching, valid bool)
  • func (m *Magus) KnowledgeGraphWithSymbols(ctx context.Context) (*knowledge.Graph, error)
  • func (m *Magus) KnowledgeGraphWithSymbolsForRef(ctx context.Context, ref string) (*knowledge.Graph, error)
  • func (m *Magus) LogCharms(charms string)
  • func (m *Magus) LogScope(label, source string)
  • func (m *Magus) MetricsCollector() (*otlp.Collector, bool)
  • func (m *Magus) MetricsSnapshot(ctx context.Context) ([]byte, error)
  • func (m *Magus) OutputByRef(ref string) ([]byte, cache.OutputDescriptor, error)
  • 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) ReindexSymbols(ctx context.Context) (int, 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) ServeDaemon(ctx context.Context) error
  • func (m *Magus) SetDaemon(d Daemon)
  • 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) SymbolIndexStatus(ctx context.Context) []types.SymbolIndexStatus
  • func (m *Magus) TailLog(projectPath, target string) (logPath string, err error)
  • func (m *Magus) Telemetry() observability.Provider
  • func (m *Magus) Trend(ctx context.Context, opts types.InsightOptions) (types.TrendOutput, error)
  • func (m *Magus) VCSOptions() types.VCSOptions
  • func (m *Magus) Volatility(ctx context.Context) (types.VolatilityReport, error)
  • func (m *Magus) WatchKnowledgeGraph(ctx context.Context) (func(), error)
  • func (m *Magus) WatchSymbolIndexing(ctx context.Context) (func(), error)
  • 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 WithMetricsCollection() Option
  • func WithProvider(p observability.Provider) 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 WithNoCache() RunOption
  • func WithNoVolatilityRetry() 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 RetryOnVolatile() 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 BuildGlobalKnowledgeGraph

func BuildGlobalKnowledgeGraph(ctx context.Context, ws types.WorkspaceRepository, cfg config.Config, refresh bool, log *slog.Logger) (*knowledge.Graph, error)

BuildGlobalKnowledgeGraph unions the current workspace with each registered one (cfg.Knowledge.Workspaces), namespacing node IDs by workspace so repos can't collide. A workspace that fails to open is skipped with a warning, not fatal: the query degrades to what it can reach.

func BuildKnowledgeGraph

func BuildKnowledgeGraph(ctx context.Context, ws types.Describer, root string, cfg config.Config, refresh bool, log *slog.Logger) (*knowledge.Graph, error)

BuildKnowledgeGraph assembles, persists, and returns the workspace knowledge graph. It is the single graph-loading path shared by the `magus graph` subcommands, the query/explain/path verbs, and the MCP tools: it gathers the describe outputs the graph is composed from, resolves the cache dir, and runs the cache-first build. ws is any workspace view that can describe itself (the read-only Inspect result or a full *Magus).

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 MergeWorkspaceSymbols

func MergeWorkspaceSymbols(ctx context.Context, ws types.Describer, root string, cfg config.Config, g *knowledge.Graph, log *slog.Logger) error

MergeWorkspaceSymbols pulls every persisted per-project @symbols shard into g, for a symbol-seeded query (the default graph excludes them for scale). Best-effort: no store or no symbol shards is a no-op.

func MergeWorkspaceSymbolsForRef

func MergeWorkspaceSymbolsForRef(ctx context.Context, ws types.Describer, root string, cfg config.Config, g *knowledge.Graph, ref string, log *slog.Logger) error

MergeWorkspaceSymbolsForRef merges symbols into g for `magus refs`, targeting only the shards that mention ref (via the xref routing index) when ref is an exact symbol ID - the scale-safe reverse lookup - or all symbol shards when ref is a fuzzy name whose exact ID is not yet known.

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 Daemon

type Daemon interface {
	Serve(ctx context.Context) error
}

Daemon is the long-running server this workspace hosts (the MCP HTTP endpoint plus the console API routes, and whatever else the daemon grows to serve). It is injected by the CLI in daemon mode ONLY - so ordinary command paths never construct one - and held as an interface so the root magus package need not import the daemon/handler packages (which depend on magus), breaking that cycle. The concrete *daemon.Daemon satisfies it.

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) BeginInvocation

func (m *Magus) BeginInvocation(ctx context.Context, cmd journal.Command, magusVersion string, extra ...slog.Handler) (context.Context, func(error))

BeginInvocation opens the structured journal for one `magus` command (launch to exit). It mints an invocation id, opens the union event log (<cacheDir>/runs/<inv>.jsonl) behind a capture *slog.Logger, threads that logger + the id onto ctx so every captured event (subprocess output + target results) streams into it, and emits the invocation's opening lifecycle event: a started event carrying the command lineage (subcommand/args/cwd/trigger) and magus version. Folding the identity into the stream this way means both the durable file and any live watcher learn which command produced the run from frame one - there is no separate metadata file. Extra handlers (e.g. a live SSE broadcaster) fan out from the same logger.

The returned cleanup takes the run's error: it emits the closing finished event (overall pass/fail outcome, final timing), then flushes and closes the log. Call it as `defer func() { end(runErr) }()` so the outcome reflects the final result.

It is best-effort: if the log cannot be opened, the id is still stamped on ctx and the lifecycle events still reach any extra handlers, so a run never fails on capture. The command/lineage is what the viewer surfaces; see magus.viewer.v1.Invocation.

func (*Magus) CacheDir

func (m *Magus) CacheDir() string

CacheDir returns the resolved workspace cache directory - the same location the journal run logs and per-ref output store live under. Callers that persist their own sidecar stores (e.g. the MCP audit log) hang them off this so everything shares one cache root and one retention regime.

func (*Magus) CacheDiskBytes

func (m *Magus) CacheDiskBytes() int64

CacheDiskBytes returns the approximate on-disk size of this workspace's cache in bytes (memoized; cheap to poll). Zero when no cache is attached.

func (*Magus) CacheStats

func (m *Magus) CacheStats() cache.Stats

CacheStats returns this workspace's live cache counters (hits/misses/errors) accumulated since the cache was opened. In daemon mode the cache is long-lived, so these grow across adopted runs - the source for the /dashboard cache-activity panel. Zero value when no cache is attached (an Inspect workspace).

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) DescribeCharms

func (m *Magus) DescribeCharms(defaults []string) types.CharmsOutput

DescribeCharms builds the inverse charm index: every charm name a target in the workspace declares, plus the reserved built-ins and any workspace default, and for each the project/target/spell declarations that give it a patch. defaults is the workspace default_charms set, so the report can mark which charms apply to every run without a :suffix. It is the transpose of DescribeTarget: one charm, every target that declares it, rather than one target and the charms it declares.

func (*Magus) DescribeEvaluatedProjects

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

DescribeEvaluatedProjects returns the fully-evaluated project inventory.

func (*Magus) DescribeFiles

func (m *Magus) DescribeFiles(paths []string) types.FilesOutput

DescribeFiles classifies workspace-relative paths against every project's declared source and output globs (the same workspace-rooted globs baseStep feeds the cache), plus directory containment for ownership. It is pure declaration lookup - no target evaluation, no VCS - so it is cheap enough to run over a whole dirty tree. An absolute path is re-rooted onto the workspace; a path outside it (or matching nothing) reports as unclaimed.

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) InvocationByID

func (m *Magus) InvocationByID(inv string) (journal.Invocation, error)

InvocationByID resolves an invocation id (OutputDescriptor.Inv) to its run header - the command lineage (subcommand/args/trigger), timing, and outcome - read from the union run log. It is the lineage source for `magus query output <ref> --meta` and the viewer. Returns fs.ErrNotExist when the run log has aged out.

func (*Magus) KnowledgeGraph

func (m *Magus) KnowledgeGraph(ctx context.Context, refresh bool) (*knowledge.Graph, error)

KnowledgeGraph returns the workspace knowledge graph. In the daemon, once WatchKnowledgeGraph is running, this answers from a warm in-memory graph without re-parsing magusfiles; otherwise (and on refresh) it rebuilds cache-first. It is always fresh: the warm graph is served only while a watcher can invalidate it.

func (*Magus) KnowledgeGraphHealthy

func (m *Magus) KnowledgeGraphHealthy() (watching, valid bool)

KnowledgeGraphHealthy reports the daemon's warm-knowledge-graph watcher state, for the /readyz readiness surface's "knowledge_graph" component. It goes through warmKnowledgeGraph (the same lazily-created holder KnowledgeGraph reads), so calling it before WatchKnowledgeGraph has ever run reports watching=false rather than panicking on a nil holder, and calling it after does not create a second holder (sync.Once).

func (*Magus) KnowledgeGraphWithSymbols

func (m *Magus) KnowledgeGraphWithSymbols(ctx context.Context) (*knowledge.Graph, error)

KnowledgeGraphWithSymbols returns a graph that INCLUDES the lazily-loaded @symbols shards, for a symbol-seeded MCP query (magus_query on symbols, magus_refs). It builds cache-first into a FRESH graph - not the shared warm graph - and merges symbols into it, so the warm graph the other MCP tools answer from is never polluted with a workspace's (potentially huge) symbol set.

func (*Magus) KnowledgeGraphWithSymbolsForRef

func (m *Magus) KnowledgeGraphWithSymbolsForRef(ctx context.Context, ref string) (*knowledge.Graph, error)

KnowledgeGraphWithSymbolsForRef is KnowledgeGraphWithSymbols for magus_refs: it merges only the symbol shards that mention ref (targeted reverse lookup) when ref is an exact symbol ID, or all of them for a fuzzy name. Also fresh-not-warm, so the shared warm graph stays symbol-free.

func (*Magus) LogCharms

func (m *Magus) LogCharms(charms string)

LogCharms emits the active-charm header through the cache logger. No-op 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) MetricsCollector

func (m *Magus) MetricsCollector() (*otlp.Collector, bool)

MetricsCollector returns a narrow accessor over this workspace's in-process metrics ManualReader for the daemon's derived-dashboard aggregation, or (nil, false) when metrics collection was not enabled at Open (the CLI default). Unlike Magus.MetricsSnapshot (OTLP bytes for external export), this reads raw metricdata - histogram buckets and counters - with no exporter hop and without exposing the generated dashboard proto here.

func (*Magus) MetricsSnapshot

func (m *Magus) MetricsSnapshot(ctx context.Context) ([]byte, error)

MetricsSnapshot returns this workspace's current metrics as standard OTLP protobuf (an ExportMetricsServiceRequest), or (nil, nil) when metrics collection was not enabled at Open (the CLI default). The daemon opens workspaces with WithMetricsCollection and relays this to the /dashboard. Reuses magus's existing OTel instruments; no bespoke metrics contract.

func (*Magus) OutputByRef

func (m *Magus) OutputByRef(ref string) ([]byte, cache.OutputDescriptor, error)

OutputByRef resolves a target-output reference id (or a unique prefix, git-style) to its reconstructed raw text and metadata. It reads the output store directly from the resolved cache dir, so it works on Inspect workspaces too (no live cache needed) - the retrieval path for `magus query output <ref>` (print). Returns fs.ErrNotExist when no ref matches, or *cache.AmbiguousRefError when a prefix matches several.

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) ReindexSymbols

func (m *Magus) ReindexSymbols(ctx context.Context) (int, error)

ReindexSymbols runs the scip op for every symbol-capable project, refreshing each project's cached SCIP index. A project whose indexer is missing or fails is reported with an actionable install hint but does not stop the rest. It returns how many projects were reindexed and the joined errors. This is the manual counterpart to the daemon's background auto-indexer, invoked by `magus graph build`.

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) ServeDaemon

func (m *Magus) ServeDaemon(ctx context.Context) error

ServeDaemon runs the injected daemon, blocking until ctx is cancelled or the server fails. It errors if no daemon was installed via SetDaemon.

func (*Magus) SetDaemon

func (m *Magus) SetDaemon(d Daemon)

SetDaemon installs the daemon that ServeDaemon delegates to. Called once, in daemon mode; other command paths leave it nil so no server is ever constructed.

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) SymbolIndexStatus

func (m *Magus) SymbolIndexStatus(ctx context.Context) []types.SymbolIndexStatus

SymbolIndexStatus reports, for each symbol-capable project, whether its cached SCIP index reflects current sources: fresh, out-of-date, or not-indexed. In the daemon it answers from a watcher-invalidated memo (a status push does not re-stat source trees); elsewhere it recomputes each call. Powers `magus status` and the dashboard.

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) Telemetry

func (m *Magus) Telemetry() observability.Provider

Telemetry returns this workspace's observability provider (nil on an Inspect workspace, which builds no cache and no provider). When several Magus instances were opened with a shared provider via WithProvider this returns that same instance, so metrics recorded through one are visible through another's Magus.MetricsCollector.

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) Volatility

func (m *Magus) Volatility(ctx context.Context) (types.VolatilityReport, error)

Volatility is the run-outcome lens: each (project, target) pair's recent pass/fail record scored by its Wilson lower bound, flagged volatile at or above the configured threshold. Unlike the git-history lenses it reads the shared runtime-history file (config.HistoryPath), not a commit scan - so it is workspace-wide and takes no InsightOptions window.

func (*Magus) WatchKnowledgeGraph

func (m *Magus) WatchKnowledgeGraph(ctx context.Context) (func(), error)

WatchKnowledgeGraph starts a file watcher that keeps the warm knowledge graph fresh, so daemon MCP calls answer from memory. It returns a stop function; the long-lived daemon calls it once at startup. A one-shot CLI never calls it and pays the cache-first rebuild per command (equally fresh, just not warm).

func (*Magus) WatchSymbolIndexing

func (m *Magus) WatchSymbolIndexing(ctx context.Context) (func(), error)

WatchSymbolIndexing starts the daemon's background symbol auto-indexer: a file watcher that re-runs each symbol-capable project's scip op when its sources change, throttled and idle-gated (see symbolIndexer). It returns a stop function; the long-lived daemon calls it once at startup, alongside WatchKnowledgeGraph. A no-op (never an error) when disabled by config or when no project is symbol-capable, so nothing is spun up need- lessly. A one-shot CLI never calls it and so never auto-indexes.

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 WithMetricsCollection

func WithMetricsCollection() Option

WithMetricsCollection builds an always-on in-process metrics collector for this workspace (OTel instruments record even with telemetry export off), so the daemon can serve OTLP snapshots to the /dashboard via Magus.MetricsSnapshot. The CLI leaves it off.

func WithProvider

func WithProvider(p observability.Provider) Option

WithProvider injects an already-constructed observability provider so several Magus instances (a daemon's bridge Magus plus each per-workspace registry Magus) share ONE set of OTel instruments and one metrics collector. The provider is owned by the daemon process, not any single workspace, so workspace eviction never discards accumulated metrics. It supersedes WithMetricsCollection: Open adopts the injected provider instead of constructing its own.

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 WithNoCache

func WithNoCache() RunOption

WithNoCache forces every selected target to run fresh even on a cache hit. Unlike a skip_cache target policy (which never snapshots), a --no-cache run still refreshes the cache entry on success, so a subsequent ordinary run replays the rebuilt result instead of the stale one.

func WithNoVolatilityRetry

func WithNoVolatilityRetry() RunOption

WithNoVolatilityRetry disables the volatility 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 RetryOnVolatile

func RetryOnVolatile() TargetOption

RetryOnVolatile enables volatility 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.