shared

Cross-tool helpers for the [name] toolbox. Every tool inside the toolbox can pull these in with require(".shared"). Holds the small set of helpers that more than one tool needs — typically the ok(value, formatted?) / fail(message, exitCode?) constructors that produce the canonical [name]ToolResult shape, plus any toolbox-wide parsers, validators, or shared state. Per-tool implementation stays inside each <x>.tool/init.luau; this module is not a place to forward logic from.

Exports

• M.ok(value: any?, formatted: string?) -> [name]ToolResult — success envelope (exitCode = 0, ok = true).
• M.fail(message: string, exitCode: number?) -> [name]ToolResult — failure envelope (exitCode defaults to 1, ok = false).

Types:

• [name]ToolResult = { stdout: string, stderr: string, exitCode: number, ok: boolean, value: any? }
  • stdout — human-readable formatted output; empty when the op produces no text.
  • stderr — error message on failure; empty on success.
  • exitCode — POSIX-style exit code: 0 success, 1 generic failure, 2 bad arguments.
  • ok — true iff exitCode == 0.
  • value — structured return from the underlying op; nil for void ops.

Usage

local shared = require(".shared")

function M.someTool(args)
    if not args.id then
        return shared.fail("missing id", 2)
    end
    return shared.ok({ id = args.id }, "created " .. args.id)
end

Notes

• Pure constructors — no engine calls, no state. Safe to call from any context.
• Tools that opt into this shape get a stable envelope every other tool in the toolbox can rely on. Tools that do something custom can return whatever shape they want — [name]ToolResult is opt-in.
• Per-tool implementations still own their own --!desc / --!arg / --!return / --!example annotations even when their result is constructed through these helpers.