mhl-tools

mhl tools and integrations

Assumes the mhl-language skill. Exact signatures are in the mhl-language skill's references/stdlib.md.

The failure convention

Native ops fail in two different ways. Choose your handling per op:

An unchecked cmd.exec is the classic silent bug: the step passes while the command failed. Wrap it once and reuse the wrapper.

Declaring tools

A tool is a namespace of methods that gives steps, hooks and tests one reusable, testable API over native ops. Put logic here and keep steps thin.

tool Shell {
    // Fails the step on a non-zero exit, so callers need no check.
    must(argv: string[]): string {
        var result = cmd.exec(argv, timeout: 30s)
        if (result.exit_code != 0) fail(self.describe_failure(argv, result.stderr))
        return result.stdout.trim()
    }

    // internal: callable through self. and from this file's tests only.
    internal describe_failure(argv: string[], stderr: string): string ->
        "${argv.join(" ")} failed: ${stderr.trim()}"
}

test shell {
    describe returns_trimmed_stdout {
        are_equal(Shell.must(["echo", "hi"]), "hi")
    }

    describe nonzero_exit_fails {
        var message = ""
        try {
            Shell.must(["sh", "-c", "echo nope >&2; exit 3"])
        } catch (e) {
            message = "${e}"
        }
        is_true(message.contains("nope"))
    }

    describe internal_helpers_are_testable_here {
        are_equal(Shell.describe_failure(["ls"], "x\n"), "ls failed: x")
    }
}

• Annotate parameters and returns. Calls are checked by lint where it can see the types.
• Bind arguments by position, in declaration order. Names in a tool call are ignored.
• Use an expression body (name(x): T -> expr) or a block (name(x): T { ... }).
• Keep control-flow exits (goto, pause, complete, break) in steps. fail() belongs in tools freely.
• Share a value across methods with const or var in the tool body, and compose with self.other(...). Write durations as literals at the use site.