magus v0.3.0 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
1 min read

Wards

A ward is a guardrail magus runs against a resolved op - after a target's operation is fully assembled but before it executes. The ward inspects the op's argv and rejects it when the command contradicts the op's declared kind, so a misconfigured op fails immediately with a coded, actionable diagnostic instead of misbehaving at run time.

Wards share the MGSxxxx diagnostic rail with the rest of magus's diagnostics and error codes: each ward raises a typed error with a stable code, a plain-language explanation, and a suggested fix.

Kind coherence

magus ops carry a kind - a service op is a long-running process magus supervises in the foreground; a command op runs to completion. A ward fires when the argv lies about that kind:

  • A service op that detaches (MGS5002) - docker run -d, a --detach flag, and friends fork the process away from magus, so foreground supervision, readiness, and stop all stop working. Drop the detach flag, or make it a command op if detaching is what you want.
  • A command op that never exits (MGS5003) - a watcher like tsc --watch in a run-to-completion op hangs the run. Make it a service op, or drop the watch flag.

Both are mirror images of the same bug: the argv and the kind disagree. Catching it at resolution time turns a confusing hang or a lost log into a one-line fix.

See Services for the full rationale, and Operations for how op kinds fit the work hierarchy.

Where wards fit

Wards are one family in magus's diagnostics. The complete catalog, grouped by area, lives under the diagnostic codes:

  • magusfile - authoring and configuration problems.
  • race - concurrency and ordering hazards.
  • sandbox - filesystem and exec isolation violations.
  • services - service-op problems, including the kind-coherence wards above.
ConceptsPages in this section. SpellsA spell is a library of tool-native ops (go-build, cargo-clippy, eslint) plus cache metadata that your magusfile composes into runnable targets. magus DocumentationThe magus documentation hub covering install, targets, spells, charms, operations, engines, remote caching, MCP, telemetry, and the interactive playground. ChangelogEvery released change to magus, newest first, in Keep a Changelog format. Generated from releases/*.yaml.
wardsdiagnosticsoperationsserviceskindMGSxxxxguardrails
Last updated (b022d75e)
Glossary

Magusfile

The magusfile.buzz that declares a project's targets (as export funs) and binds its spells. See targets.

Target

A named operation (build, test, ...) you invoke with magus run <target>; it may compose a spell's tool-native operations and depend on other targets. See targets.

Operation

A single tool-native command a target composes; the middle of the work hierarchy (Spell to Operation to Target). See operations.

Ward

A coded diagnostic that inspects a resolved op and nudges or blocks an anti-pattern before it runs. See wards.

Sandbox

The restricted filesystem and environment a target runs in, so builds stay reproducible and side-effect-free. See sandbox.

Service

A long-running or shared process magus manages across runs, distinct from a one-shot target. See services.

Concurrency

How many targets run at once. It is bounded by the pool's capacity and set with --concurrency, MAGUS_CONCURRENCY, or the concurrency config key. See daemon.

Diagnostic code

A stable MGSxxxx identifier attached to a magus warning or error, so it can be referenced and looked up; some are guardrails (see wards), others hard errors.

Conventions

This page uses none of the site's convention markers. The full set is on the conventions page.