magus v0.4.2 is out. See what's new
¶ View generated markdown
5 min read

Magusfile Module Reference

These are the runtime utility modules. Import each under its bare name (import "fs", then fs.glob(...)) with camelCase methods. magus layers these host methods onto Buzz's own stdlib, so a single import "fs" (or os, crypto) carries both surfaces, and the magus forms are sandbox-aware where Buzz's bare stdlib is not. Methods that are also in Buzz's own standard library are marked with an asterisk (*) and a footnote on their page; either form works.

Files and paths

Module Description
fs Filesystem and path primitives.
path Pure path-string math: abs, rel, clean, is_abs, expand_user, and glob matching.
archive Archive creation and extraction with automatic format detection. Supports tar, zip, tar.gz, tar.bz2, tar.xz, and tar.zst. Symlinks and non-regular entries are skipped.

Process and environment

Module Description
os The machine and this process: platform triple, CPU count, hostname, the running magus binary, and the two members that shadow Buzz's own (exit, sleep). Running OTHER processes lives in the proc module.
env Process environment variable access.
platform Normalize OS/architecture identifiers across naming conventions (aarch64<->arm64, Darwin<->darwin).

Text and formatting

Module Description
strings String helpers Buzz's builtins lack: case conversion, comparison, affix trimming, padding, and splitting into lines or fields.
fmt String formatting (printf-style).
markdown GitHub-Flavored Markdown to semantic HTML.

Serialization and encoding

Module Description
json JSON encode/decode.
yaml YAML parse and stringify (YAML 1.2 via gopkg.in/yaml.v3).

Cryptography

Module Description
crypto Content digests (SHA-256/512; SHA-1 and MD5 for legacy-checksum interop) and Ed25519 signing.

Networking

Module Description
http HTTP client. Requests run ONCE unless given a retry policy.

Time

Module Description
time Timestamp formatting/parsing and duration parsing (Go time, UTC).

Versioning and version control

Module Description
semver Semantic version parsing and comparison (SemVer 2.0.0).
vcs Version-control queries for the current working tree.

Magus internals

Module Description
magus Magus core primitives.

Three provider namespaces are wired by the runtime rather than declared here, so they do not appear in the method list below: magus\cache.remote(<spell>) selects a remote cache provider, magus\ci.provider(<spell>) a CI provider, and magus\secret.provider(<spell>) / magus\secret.read(<ref>) a secret provider and the credentials read through it. Each takes an imported spell handle. magus\secret.endpoint(<grant>) serves the case read cannot: it returns a loopback base URL a CHILD PROCESS is pointed at instead of the real API, so magus attaches the credential on the way upstream and the child never holds it. It takes an object with ref/host/header/prefix fields, declared in your own magusfile. For your own code, read is the ordinary choice. See Secrets, Remote cache and CI integration.

import "magus" resolves in a magus buzz script as well as in a magusfile, and a script run inside a workspace reads that workspace: projects, affected, projectGraph, where and insight all answer in-process, and so does magus\ledger (list, put, register, clear): the lease ledger an orchestrating agent declares about work it handed out (see types.Lease). There is deliberately no magus ledger CLI subcommand, so this namespace and the magus_ledger MCP tool are the only doors onto it. Only the members that DECLARE into the workspace being loaded (magus\project, the provider selections above) raise MGS1022 in a script - there is nothing for them to declare into. Run a script outside any workspace and the reading members raise it too, since there is no workspace to read. The nested-command methods (cmd, run, describe, doctor) work there either way and discover the workspace themselves. | | charm | Constructors for charm values: RFC 6902 JSON Patches over a target's argv (see docs/charms.md). |

Other

Module Description
base64 Base64 text codec (standard and URL-safe, both padded).
csv Delimiter-separated tabular text (CSV, TSV) parsing and rendering.
diff Unified line diffs, for reporting what drifted rather than only that something did.
hex Hex text codec.
ini INI/properties config parsing and rendering (.npmrc, .gitconfig, .editorconfig).
lcov LCOV coverage reports: the percentage a badge or a floor gate shows, and the line-level merge that keeps it true across multiple test processes.
log Emit a message at a level through magus's own logger, so it honors -q/-v/-vv, renders in the run's format, is redacted, and is captured in the run log. Unlike std\print, which is an uncontrolled bare line.
math Rounding to a decimal place, clamping, and aggregation over a list of numbers.
net TCP readiness and port allocation: wait for a service to accept connections, and find a free port.
proc Run other processes. proc.exec is the one verb that runs anything: it streams output live, captures it, honors the sandbox, and raises on failure instead of handing back a code to check. Needing a shell is not a second verb - proc.shell builds the {bin, args} to hand it, so which shell ran stays visible at the call site instead of hidden inside it. Distinct from Buzz's own os.execute, which returns an exit code and stays silent when you do not read it.
sort Ordering for string lists: lexicographic, natural (digit-aware), and semver.
template Logic-less Mustache templating (Mustache spec, via github.com/cbroglie/mustache).
term Terminal interaction: capability probes, an interactive picker, and styled output. Renders to stderr; pick raises rather than hanging when there is no terminal.
toml TOML parse and stringify (TOML 1.0 via pelletier/go-toml/v2).
url URL percent-encoding, parsing, and building.
uuid Unique identifiers and random tokens (v4 random, v7 time-ordered, plus raw random hex/tokens).
xml Build, serialize, and parse XML/SVG.

See also

  • Targets: the runnable units whose magusfiles call these modules.
  • Spells: language and toolchain adapters that compose these modules into ops.
  • Charms: the execution modifiers the charm module constructs.
  • Playground: exercise these modules live in the browser.
generatedstd/**/*.gostdlibmodulesmagusfilereferencefsoshttpjson
Last updated (4f8cc295)
Earlier changes on this page (7)

Full history ↗ · Blame source ↗

Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. See workspace.

Project

A directory magus recognizes as a unit of work (it has a magusfile); the unit of caching, scheduling, and dependency tracking. See workspace.

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.

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). See operations.

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. See spells.

Charm

An execution modifier attached with : (lint:rw) that changes how a target runs, not which one; the built-in rw flips a check-only target to mutate in place, and ci always strips it. See charms.

Module

A magus stdlib namespace a magusfile imports for host capabilities: filesystem, exec, vcs, and more. See the module reference.

Buzz

The language magusfiles are written in (the .buzz engine). See engines.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. See cache.

Affected

The set of projects touched by a change; magus affected <target> runs a target only over them. See affected.

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.

CI

An ordinary magusfile-defined target you compose yourself with magus\needs - magus does not hardcode its stages. Magus.RunCI treats it specially only in that it strips the rw charm, it is the anchor magus affected ci keys off, and a selected scope with no project declaring it is a load error rather than a silent no-op. See targets.

Remote cache

A CI-only backend that shares content-addressed artifacts across runners: a cold machine replays a build another runner already did instead of rebuilding. Every remote artifact must be signed by a trusted key. See remote.

MAGUS.md

The committed routing index at a workspace root, regenerated from the knowledge graph: it lists every node and points at the exact query for a given question, so it is the entry point an agent reads first. See knowledge.

Insight

The reports magus derives over the graph and history (hotspots, affinity, ownership, trend, volatility, unreferenced). See insight.

Lease

One row of the lease ledger: a piece of work an orchestrating agent handed out, with its goal, the checkpoint it was cut against, and the paths it owns or must not touch. The ledger records; the agent guard is what reads those facts back when grading a write. See doctrine.

Conventions

Placeholders

Angle brackets mark a value you replace with your own - never type the brackets:

magus run <target>
magus completion <shell>    # e.g. bash, zsh, fish

<target>, <path>, <shell>, <name> and the like are stand-ins, not literal text.