Spell contract

A spell answers magus through exported mgs_ functions. magus calls each one once, with no arguments, when it loads the spell, before any target runs. Each function must declare exactly the return type below; a different one, > any, or an mgs_ name this page does not list is MGS1051.

Only mgs_getName is required. Leaving any other function out declares nothing for it.

mgs_getName

export fun mgs_getName() > str

Required. The spell's name, the one a magusfile imports it by.

mgs_listRequiredGlobs

export fun mgs_listRequiredGlobs() > [Path]

The files every op of the spell reads. They key its cache and pull its project into the affected set.

mgs_listProvidedGlobs

export fun mgs_listProvidedGlobs() > [Path]

The files the spell's ops write.

mgs_listIgnoreDirs

export fun mgs_listIgnoreDirs() > [Path]

Directories the spell's ecosystem generates (vendor, node_modules, target), which the input-hashing walk prunes. Each Path sets isDir = true.

mgs_listManifests

export fun mgs_listManifests() > [Manifest]

The candidate manifests of the spell's ecosystem, in order: the first one present in a project directory is its manifest. Each names the lockfiles it may carry.

mgs_listScriptRunners

export fun mgs_listScriptRunners() > [Command]

The argv prefixes that run a script a manifest defines, which doctor reports as MGS1049.

mgs_getTools

export fun mgs_getTools() > {str: Tool}

Every binary the spell's ops run, keyed by the bin name a Command names, each with the probe that reads its version into the cache key.

mgs_getLanguage

export fun mgs_getLanguage() > Language

The source language the spell adapts: its name, its file extensions and, when the spell can declare it honestly, its comment and string syntax.

mgs_getSymbolIndexer

export fun mgs_getSymbolIndexer() > SymbolIndexer

The command that writes the spell's SCIP symbol index. magus runs it as the reserved index op.

mgs_getSandbox

export fun mgs_getSandbox() > Sandbox

What the spell's tools need from the host beyond the sandbox's own grants.

mgs_isOpaque

export fun mgs_isOpaque() > bool

Whether the spell delegates to a foreign process that manages its own dependency graph, so magus treats the project as a black box.

mgs_getModeArgs

export fun mgs_getModeArgs() > {str: [str]}

The args that tell an op apart from other uses of a program with no subcommand, keyed by op name: node runs scripts too, and only --test is node-test.

mgs_listTargets

export fun mgs_listTargets() > {str: fun(Target) Command}

The spell's ops, keyed by op name. magus calls each handler once at load, with a null Target, to read the Command it declares, so a handler must not read its Target.

mgs_listServices

export fun mgs_listServices() > {str: fun(Target) Service}

The spell's long-running ops, keyed by op name, each read the way a target handler is.