magus v0.3.0 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
3 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.
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 Process execution. os.exec runs a command directly (no shell); os.exec_sh runs a line through the shell. Both stream output live and return a result {stdout, stderr, code, ok}.
env Process environment variable access.
platform Normalize OS/architecture identifiers across naming conventions (aarch64↔arm64, Darwin↔darwin).

Text and formatting

Module Description
strings Case conversion and word helpers (camel/snake/kebab/Pascal, capitalize, words, ellipsis).
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).
encoding Base64/hex/URL text codecs.

Cryptography

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

Networking

Module Description
http HTTP client with automatic retry on transient errors.

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 backend, magus\ci.provider(<spell>) a CI provider, and magus\secret.provider(<spell>) / magus\secret.read(<ref>) a secret backend and the credentials read through it. Each takes an imported spell handle. See Secrets, Remote cache and CI integration.

import "magus" resolves in a magus buzz script as well as in a magusfile. The members that declare into the workspace magus is loading (magus\project, the provider selections above) and the ones served in-process from a loaded workspace (ls, targets, affected, graph, where) raise MGS1022 in a script; the nested-command methods (cmd, run, describe, insight, doctor) work there 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
template Logic-less Mustache templating (Mustache spec, via github.com/cbroglie/mustache).
toml TOML parse and stringify (TOML 1.0 via pelletier/go-toml/v2).
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 operations.
  • Charms: the execution modifiers the charm module constructs.
  • Playground: exercise these modules live in the browser.
auto-generatedstdlibmodulesmagusfilereferencefsoshttpjson
Last updated (843581cb)
Earlier changes on this page (2)

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.

Operation

A single tool-native command a target composes; the middle of the work hierarchy (Spell to Operation 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.

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-cache.

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). See insight.

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.