# mooncram CLI behavior specification [中文版本](CLI_SPEC_CN.md) This document describes the CLI behavior of the current `0.0.4` module. It covers the command line, Markdown input format, process execution, matching, reporting, and updates. It is a description of the current implementation, not a proposal for additional features. The English and Chinese versions have the same section structure and should be maintained together. Examples containing `mooncram` fences are enclosed in larger Markdown example fences so that this specification does not itself introduce executable cases. Paths such as `./hello.mbtx` in those examples are illustrative. ## 1. Invocation and command-line parsing ```text mooncram [global-options] check [paths...] [global-options] mooncram [global-options] test [paths...] [global-options] mooncram [global-options] update [paths...] [global-options] [--dry-run] mooncram (-h | --help) mooncram (-V | --version) mooncram help [check|test|update] mooncram check (-h | --help) mooncram test (-h | --help) mooncram update (-h | --help) ``` From the repository checkout, the executable can be launched with: ```text moon run . -- check README.md moon run . -- test README.md moon run . -- update examples --dry-run ``` The `--` in these examples separates `moon` arguments from mooncram arguments. A later `--` can terminate mooncram's own option parsing. | Command | Behavior | | --- | --- | | `check` | Validate documents and resolve local targets without building or executing cases. | | `test` | Execute cases and compare routed output and exit status with the expectations. | | `update` | Execute cases, then update and normalize their expectations from observed results, including passing cases. | | `update --dry-run` | Execute cases and print proposed document changes without writing them. | | `help`, `-h`, `--help` | Print the relevant help to stdout and exit with `0`, without discovering or executing cases. | | `-V`, `--version` | At the top level, print the executable's version string followed by a newline to stdout and exit with `0`. | A subcommand is required unless a help or version request is handled. An empty command line is an argument error, not an implicit `test`. Version flags are not available after `check`, `test`, or `update`; for example, `mooncram test --version` is an argument error. ### 1.1 Options and defaults | Option | Scope | Default | Accepted values and effect | | --- | --- | --- | --- | | `--target VALUE` | Global, `test`/`update` only | `wasm` | Exactly `wasm` or `native`; default backend for local package cases. | | `--timeout-ms N` | Global, `test`/`update` only | `60000` | Positive signed 32-bit integer in milliseconds; one deadline for each case's build and execution. | | `--color VALUE` | Global | `auto` | Exactly `auto`, `always`, or `never`; controls mooncram's report coloring. | | `--dry-run` | `update` only | Off | Print proposed document diffs instead of replacing documents. Takes no value. | Global options can appear before the subcommand, before paths, between paths, or after paths. Both `--target native` and `--target=native` forms are accepted; the other value options also accept `--name=value`. These options have no short aliases. Each global value option may be supplied only once, including across both sides of the subcommand; repeated occurrences are errors rather than overrides. Repeating `--dry-run` keeps it enabled. `--dry-run` must occur after `update`. It is invalid at the top level and for `check` or `test`. `check` also rejects explicit `--target` and `--timeout-ms`, even when they equal the defaults or appear before the subcommand. All three commands accept `--color`. Unknown commands/options, missing option values, and invalid values produce exit status `2`. For `--timeout-ms`, only ASCII decimal digits are accepted, with value in `1..2147483647`. Leading zeroes are allowed. Signs, spaces, fractions, zero, and overflow are rejected. Validation after argument parsing checks target, then timeout, then color. `paths` accepts zero or more values. With no paths, it becomes `.`. After the subcommand, `--` makes all remaining arguments paths, including names starting with `-`: ```text mooncram --target native test docs README.md --color never mooncram update docs --timeout-ms=120000 --dry-run mooncram test -- -example.md ``` Mooncram does not expand path globs itself. Expansion by the shell launching mooncram happens before the CLI receives its arguments. A fence can declare its module; target and timeout are controlled by the CLI options. ### 1.2 Check without execution `check` shares file discovery, Markdown parsing, command and expectation validation, and document-level module/directory validation with `test` and `update`. Configuration-only fences are validated too. It then resolves each pipeline segment against the current filesystem, checking script existence, executable package selection, module boundaries, and import alias conflicts. It reads the parent environment, local files and configuration without building, downloading dependencies, starting subprocesses, or modifying Markdown. A document parse or declaration-validation failure counts as one error and prevents checking its cases. A target-resolution failure counts as one error for that case, skips its remaining segments, and continues with later cases and files. Ambiguity warnings follow the usual reporting rules and do not count as errors. The summary is `N cases, E errors`; a run with no cases and no other errors uses the existing no-cases error instead. Variable expansion uses the current parent environment and platform variable-name rules, document exports, and temporary assignments. Results therefore depend on the environment and current filesystem. A target generated by an earlier case may be reported missing by `check`; `test` and `update` resolve targets at execution time and support this pattern. `check` does not verify source compilation, backend build support, remote-coordinate existence, or program assertions. It has no per-case execution timeout. ## 2. File discovery and ordering Discovery completes before any document is read or any case is executed. 1. Resolve each supplied path against mooncram's invocation directory. 2. Recurse into actual directories. During enumeration, skip entries beginning with `.`, entries hidden according to the filesystem API, and entries named exactly `_build` or `target`. This includes Windows hidden attributes. 3. Select regular files whose encountered path ends in the case-sensitive suffix `.md`. A directly supplied regular file with another suffix is ignored. 4. For a file symlink with an encountered `.md` suffix, include its target if it is a regular file. Do not traverse directory symlinks. 5. Resolve selected files to canonical absolute paths, deduplicate those paths, and sort them lexicographically. The skip rules apply to directory entries during traversal. An explicitly supplied hidden file, hidden directory, `_build`, or `target` is not rejected just because of its name; its contents still follow the normal discovery rules. Deduplication uses canonical paths, not file contents or inode identity. The suffix test is on the encountered path, so an `alias.md` symlink can select a regular target whose own name has another suffix. A missing input or a filesystem error during discovery aborts the entire run with status `2`; already discovered files are not executed. Symlinks ending in `.md` whose targets cannot be inspected can also produce discovery errors. Documents run in sorted canonical-path order, independently of argument order. Cases run serially in document order. Segments of the same pipeline run concurrently. Filesystem side effects from earlier cases remain visible to later cases. Each process starts in the block's working directory (the canonical document's parent by default) and inherits mooncram's environment, overridden by the exports in effect for that case and then by the segment's temporary assignments. A document without cases is allowed when other documents contain cases. If there are no attempted cases (checked or executed) and no recorded errors, the CLI reports `ERROR no mooncram cases found` and exits with `2` without a summary. ## 3. Markdown recognition and case boundaries Documents are read as UTF-8; decoding failures are document errors. Markdown is parsed structurally with `cmark`, with source locations and layout retained. Fenced code blocks with a backtick opening fence and the exact, case-sensitive language `mooncram` contain tests; `mooncram-import` declares file tool imports. The info string accepts optional whitespace and a single module name, such as `mooncram user/foo`. The declaration is scoped to that fence; ordinary fences have no module name. Multiple words, JSON settings, or invalid module names are document parsing errors at the opening line. Module/package names use nonempty slash-separated components with ASCII letters, digits, `_`, `-`, or `.`; `.` and `..` components are prohibited. Valid longer backtick fences work as well as triple backticks. Other languages, indented code blocks, tilde fences, and apparent fences inside larger code examples are silently ignored. Cases inside block quotes and lists are supported; the Markdown container prefix is not part of the command or output. Normal Markdown indentation rules apply before parsing lines. An eligible fence must have a closing fence and at least one command (an export or a working directory declaration also satisfies this requirement). An unclosed or empty eligible fence is a document parsing error. Ignored fences do not produce mooncram parsing errors. ````markdown ```mooncram user/foo $ ./hello.mbtx "Moon Bit" Hello, Moon Bit! $ cmd/main --version my-cli * (glob) ``` ```` Within the parsed code block: - A line beginning exactly with `$ ` starts a command; an export sets the environment, `set-current-working-directory` configures the block, and every other command starts a case. A line consisting only of `$` is also treated as a command start, then rejected as an empty command. - Before the first command, only completely empty lines are ignored. Any other line is an error. `$` followed only by a tab is not the `$ ` command prefix. - Every following line up to the next command or closing fence is an expectation line, except completely empty lines at the end of that span. - Trailing empty lines are separators and are excluded from expectations. Empty lines inside the remaining expectation span are real output lines; whitespace-only lines are not empty separators. - Commands occupy one source line. There is no multiline command continuation, comment syntax, or separate setup/teardown syntax inside a test block. A line of output that would look like a command must use a JSON string with `(escaped)`. The whole document, including all commands and expectations, is parsed before executing any case in that document. A parsing error prevents every case in that document from running, even cases before the error. Later documents are still processed. Reported source line numbers are one-based positions in the original Markdown document. ### 3.1 File tool imports A document permits zero or one `mooncram-import` fence, with no settings after its language name. Recognition follows the same backtick/container rules as `mooncram`, including longer fences, lists and quotes. Tilde fences and fences inside larger examples are ignored. An eligible import fence must close and contain at least one declaration; blank or whitespace-only lines are allowed. Imports never count as cases, and an import-only document is legal subject to the overall no-cases rule. Each nonblank line must be `alias : user/module[/package]@version`. Whitespace around the colon and declaration is allowed. Aliases are case-sensitive `[A-Za-z_][A-Za-z0-9_-]*`; `export` and `set-current-working-directory` are reserved. Coordinates require at least two path components, following the module/package name rules above. Versions must be exact SemVer `MAJOR.MINOR.PATCH`, optionally followed by `-prerelease` and `+build`. Core numbers and numeric prerelease identifiers have no leading zeros; build identifiers may have them. Identifiers contain ASCII letters, digits and hyphens, separated by dots, with no empty identifiers. Omitted versions, `latest`, ranges, wildcards, default arguments and variable expansion are rejected. All imports are collected and validated before commands and exports are parsed in their original order. `Document.imports : Map[String, ToolImport]` stores each alias's `name`, `coordinate` and one-based source `line`. Bindings apply to every case in that document regardless of declaration position, and never cross files. A duplicate alias reports both declaration lines; a second import fence is a document parsing error reporting both opening positions. Other malformed input is located at the offending line or opening fence. ````markdown ```mooncram-import moongrep : moonbit-community/moongrep@0.3.5 ``` ```mooncram $ moongrep --version * (glob) ``` ```` ## 4. Command tokenization and executable selection The text after the leading `$` is tokenized directly into an array of pipeline segments, a single export assignment, or a working directory configuration. It is not passed to a shell. The command parser returns `Command::Pipeline(Array[PipelineSegment])`, `Command::Export(name~ : String, value~ : String)`, or `Command::SetCurrentWorkingDirectory(directory~ : String)`, with `Debug` and `Eq`. Its optional `lookup` callback resolves variables; without it references are undefined. Optional `case_insensitive : Bool = false` normalizes temporary assignment names and reference lookup keys to ASCII uppercase when enabled; the document parser enables it on Windows. Returned arguments, assignment values and directory names have already been expanded. `PipelineSegment` has `argv : Array[String]`, `extra_env : Map[String, String]`, `stderr_to_stdout : Bool`, and `stdout_to_null : Bool`, with `Debug` and `Eq`. Both flags default to `false` when their markers are absent; `Case.pipeline` stores these segments. Segment `extra_env` contains only temporary assignments, while `Case.extra_env` retains the document export snapshot. The executor copies that snapshot and overlays each segment's temporary values for both its build and run. | Syntax | Meaning | | --- | --- | | Unquoted, unescaped `\|` | Separate pipeline segments, even without surrounding spaces. | | Unquoted space or tab | Separate arguments; consecutive separators are ignored. | | `'text'` | Literal text until the next single quote; backslashes are literal. | | `"text"` | Text until the next unescaped double quote. | | Backslash outside single quotes | Quote exactly the next character, including inside double quotes. | | `''` or `""` | An empty argument, which is preserved. | | Adjacent quoted/unquoted fragments | Concatenated into the same argument; `a"b"c` becomes `abc`. | | `${NAME}` outside single quotes, with an unescaped `$` | Expand one environment variable; never split or recursively expand the result. | Backslash does not interpret C/JSON escape sequences: `\n` contributes `n`, not a newline, unless the backslash is inside single quotes. A trailing backslash or an unclosed quote is a parsing error. The underlying command parser rejects NUL, CR and LF. Raw NUL characters in Markdown are first replaced by cmark with `U+FFFD` (`�`), so they do not trigger the NUL check. Empty pipeline segments, including leading/trailing `|` and `||`, are parsing errors. Quoted or escaped `|` is an ordinary argument character. For example: ```text $ ./producer.mbtx|cmd/filter|./consumer.mbtx ``` Except for the exact trailing redirection markers below, unquoted `&`, `;`, `<`, `>`, backticks, `(`, and `)` are rejected wherever they occur in a word. Quoting or escaping them passes them literally. There is no wildcard or tilde expansion or command substitution. For example, `'$HOME'`, `*`, and `~` are literal arguments; `'$(cmd)'` is literal, while unquoted `$(cmd)` is rejected because of its parentheses. Only nonfinal segments accept these trailing markers. The final segment, including a single command, rejects either marker or their combination with "redirection is not allowed in the final pipeline segment". Its stdout and stderr are always captured separately. | Markers | Original stdout | Original stderr | | --- | --- | --- | | None | Next segment | Diagnostic stderr | | `2>&1` | Next segment | Same output pipe | | `1>/dev/null` | Discarded | Diagnostic stderr | | Both, in either order | Discarded | Next segment | Markers contain no spaces or tabs and require at least one space or tab between the marker and the preceding command, argument or marker. The following `|` needs no whitespace. Each kind may occur at most once, and no ordinary argument may follow a marker in the same segment. Missing commands, duplicate markers, internal whitespace, other redirection forms, and redirection on `export` are parsing errors, retaining the document filename and command line number. Classification uses exact raw tokens during tokenization, before variable expansion. Fully quoted or correctly escaped markers and marker text produced by expansion remain ordinary arguments. Literal `2>&1` requires quoting or `2\>\&1`, escaping both `>` and `&`; literal `1>/dev/null` can use `1\>/dev/null`. The old `>/dev/null`, `stdout>/null` and `stderr>/stdout` syntax is rejected. Expanded argv is never checked for redirection syntax. For example: ```text $ ./producer.mbtx 1>/dev/null 2>&1|cmd/filter ``` `$ set-current-working-directory ` declares one working directory for the current fence. It requires exactly one nonempty expanded argument, reusing normal quoting, escaping and variable lookup. Each block permits at most one declaration, before its first actual test command; exports may precede it. Duplicates, late declarations, pipes, redirection, expected output and exit codes are parsing errors with source locations. Blank separators are allowed. This directive is not a case; configuration-only fences are legal, with the usual no-cases rule for a whole run. The parser does not inspect the filesystem. It stores the argument as expanded at declaration time using earlier document exports or the parent environment; later assignments cannot change it. `WorkingDirectoryDeclaration` contains `directory : String` and its one-based `line : Int`. `Case.working_directory` is optional; `Document.working_directory_declarations` retains every declaration, including those in fences without cases. Configuration resets at each fence; document exports continue across fences. After parsing and module validation, before any case or build in that document, `validate_document_working_directories` checks every declaration. Relative paths resolve against the canonical Markdown file's parent, never another block's cwd; absolute paths are accepted. Targets must already be directories, including symlink targets, and are resolved to real absolute paths. Earlier cases cannot create these directories. The returned `Map[Int, String]` maps declaration lines to validated directories. The CLI selects each case's directory from that map, using the document directory when no declaration applies. Validation failures are one document error, located at the directive and showing the resolved path: zero cases execute and no update occurs in that document, while later documents continue. A directory removed after validation follows the normal execution-error rules. This changes no filesystem side-effect or dry-run rules. Local modules still resolve from startup cwd and package builds retain `moon -C `; their subprocess cwd is the configured block directory. `$ export NAME=value` sets exactly one variable. The assignment is split at the first literal `=`; the name must match `[A-Za-z_][A-Za-z0-9_]*` and cannot contain variable references. Empty values and additional `=` characters are allowed. The value follows the argument quoting and expansion rules. Missing assignments, invalid names, extra arguments, and an `export` segment in any pipeline are parsing errors. An export accepts no expected output or exit code; any following nonempty expectation span is a parsing error. Blank separator lines are allowed. Exports do not count as cases, and export-only fences are valid. The existing no-cases error still applies when the entire run contains no actual cases. Exports take effect in source order across eligible blocks in one document and reset at the next document. Lookup first checks earlier document exports, then the parent process environment. An exported empty string is a defined value and overrides the parent. Self-reference reads the value before the assignment. Each actual case receives an independent `extra_env : Map[String, String]` snapshot. The original command text is retained for reports, update and dry-run. On Windows, export assignment, reference lookup and subsequent replacement are case-insensitive. Export names and lookup keys are normalized to ASCII uppercase, so differently cased assignments replace the same snapshot entry and child processes receive only one exported entry per variable. Linux and macOS retain case-sensitive names. These rules also apply to self-reference and empty values. Only `${NAME}` references expand; `$NAME` is literal. Unquoted and double-quoted references expand, while single quotes and escaped dollar signs protect them. Expansion occurs once and never retokenizes: whitespace, quotes, `|` and even another `${NAME}` in the result remain inside the same argument. Empty results remain arguments; `prefix${NAME}suffix` concatenates into one argument. Undefined variables and invalid or unclosed references are document parsing errors, with file and source line numbers. The whole document must parse before any case runs. `$ NAME=value OTHER="${NAME}" command` sets temporary variables for one pipeline segment and its build. Only consecutive assignments before the executable are recognized, with an unquoted, unescaped name and `=`; names use the same `[A-Za-z_][A-Za-z0-9_]*` rule as exports. Values follow the existing quoting, escaping and expansion rules, including empty values and additional `=`. Assignments after the executable are ordinary arguments. Words with invalid variable names, such as `9A=x` and `A-B=x`, are not recognized as temporary assignments. They are ordinary words and can select the executable when they are the first word after any temporary assignments. Temporary values override document exports and the parent environment. Assignments expand from left to right, then arguments expand using the resulting environment: `A=new B="${A}" command "${B}"` passes `new`. Self-reference reads the value before that assignment; repeated names keep the last value. Each pipeline segment has its own temporary environment, and later commands retain the document environment. Windows names remain case-insensitive; Linux and macOS names remain case-sensitive. Assignments without a command, or temporary prefixes on `export` or `set-current-working-directory`, are parsing errors. After any temporary assignments, the first word selects the segment's executable and cannot contain an expandable `${NAME}`. This is a parsing error even if the variable is defined. Single-quoted or escaped references may appear literally in executable paths. File paths passed as ordinary arguments follow the normal expansion rules. The first argument of each segment must be nonempty. A case in an ordinary `mooncram` fence can execute a file import alias or a regular `.mbtx` file. Script paths are resolved against the block's working directory; absolute script paths are accepted. Scripts are also allowed in fences with a module declaration. Before executing any case in a document, all declarations must exactly match `name` in the `moon.mod` located directly in mooncram's startup cwd. This includes configuration-only fences. Missing/invalid configuration or a mismatched declaration is a document error reported at the declaring fence's opening line. No parent search or registry module loading occurs. `Case.module_name` stores the optional name; `Document.module_declarations` stores names and opening line numbers. The execution context stores the module name, startup root, and source root. Declared fences additionally accept executable package names relative to the module's `source` directory. Missing, empty, or null `source` means the module root; otherwise it must resolve to a subdirectory inside the module root. For `user/foo`, `cmd/boo` refers to `user/foo/cmd/boo`. The short name `foo` first considers root package `user/foo`, then same-name subpackage `user/foo/foo`. A package is callable if its configuration declares `pkgtype(kind: "executable")` or `options("is-main": true)`. If only the subpackage is callable it is selected; if both are callable the root wins. If neither is callable the case errors. A selected package's compilation or backend failure errors without fallback. Each ambiguous pipeline segment emits one independent `WARNING` on mooncram's stderr with document position, both full names, and the chosen package. Warnings never enter captured program output, mismatch diagnostics, updated expectations, or error counts. Package names cannot be absolute directory paths, use `./` or `../`, contain traversal, or cross another `moon.mod` boundary, including through symlinks. `moon.pkg` is parsed with `moonbitlang/moon_config@0.4.2`. Invalid configurations are errors. Arbitrary binaries, shell commands and `.mbt` files are not case targets. Remote packages can only be accessed through declared aliases. User targets are never searched through `PATH`. Remaining arguments are forwarded to the tested program, so its `--version` or `--target` is not interpreted as a mooncram option. Each pipeline segment independently checks its first argument against `Document.imports`. An alias becomes `moonx --target wasm -- `; `Case.command` and the parsed pipeline are retained unchanged. Imported tools inherit the case cwd, environment snapshot and output routes. CLI `--target` continues to control local packages; imports always use Wasm. In a declared fence, probe the same local candidates used by local resolution (including root short-name and same-name subpackage candidates). If any is executable, fail before pipeline startup and require a different import alias. Local configuration read/parse failures propagate normally; they must not be treated as missing packages. Non-alias segments retain their existing resolution behavior. ## 5. Build, execution, capture, and timeout Mooncram uses external MoonBit tools. `moon` must be available to build cases; scripts and imports also require `moonx`, Wasm packages require `moonrun`, and native package builds require the corresponding native toolchain. The backend used to run mooncram itself is separate from the backend selected for a test case. The following argument vectors use resolved absolute paths. Angle-bracket items are placeholders, not shell syntax: | Case kind | Build preflight | Program invocation | | --- | --- | --- | | `.mbtx` script | `moon run --build-only --target wasm