Documentation
¶
Overview ¶
Package cli wires the command-line surface: Runefile resolution, the parse → analyze → run pipeline, task dispatch, and exit-code mapping.
Failure-hook capture for the MCP surface (spec 022 US1): hook stdout is collected in a dedicated masked buffer and delivered to agents as the fix-suggestion section of the tool result. Masking happens at the writer as bytes arrive, so it always precedes the size cap (FR-007).
Index ¶
- Constants
- func Analyze(opts Options, path string, jsonOut bool) error
- func BannerLine(th style.Theme, msg string) string
- func BannerMessage(err error) string
- func CodeFor(err error) int
- func LSP(opts Options, lspOpts LSPOptions) error
- func Run(opts Options, args []string) error
- func ServeMCP(opts Options, useHTTP bool, addr, tokenFile string) error
- func VersionCheck(opts Options, asJSON bool) error
- type CompatibilityResult
- type Interrupted
- type LSPOptions
- type Options
- type TaskCandidate
- type TaskFailure
- type UsageError
- type ValidationError
Constants ¶
const ( ExitSuccess = 0 // all requested tasks succeeded ExitTaskFail = 1 // a task body failed ExitUsage = 2 // usage error / no Runefile / unknown task / bad args ExitValidation = 3 // static parse/analyze error — nothing executed ExitInterrupt = 130 // interrupted (SIGINT) )
Exit codes (contracts/cli.md, FR-021).
Variables ¶
This section is empty.
Functions ¶
func Analyze ¶ added in v0.3.0
Analyze statically analyzes the Runefile at path (or the discovered Runefile when path is empty) together with its transitive imports, printing diagnostics and running nothing (spec FR-023). It uses the shared analysis service, so its diagnostics are identical to what the language server publishes (FR-002).
Exit codes follow Rune's house scheme: 0 when there are no error-severity diagnostics, 3 (ValidationError) when there are, and 2 (UsageError) for a missing/unreadable Runefile or other discovery/IO failure.
func BannerLine ¶ added in v0.4.0
BannerLine formats one of Rune's "rune: <msg>" failure banners, emphasizing the prefix with the shared error role so failures are scannable by color in a long transcript (spec 014 C1). Only the prefix is styled: the message stays plain (and pre-masked where it embeds task output), so stripping ANSI recovers the exact plain bytes. It is the single definition of the banner shape, shared by the cycle/watch banners here and the top-level banner in cmd/rune.
func BannerMessage ¶ added in v0.4.0
BannerMessage returns the banner text for err, or "" when err must not produce a top-level banner: a ValidationError's diagnostics are already rendered by the pipeline, and a silent TaskFailure ([no-exit-message]) intentionally stays quiet. It is the single source of the suppression rule shared by the top-level (cmd/rune) and watch-loop banner paths.
func LSP ¶ added in v0.3.0
func LSP(opts Options, lspOpts LSPOptions) error
LSP starts the Rune language server over stdio (spec FR-011). stdout carries only JSON-RPC protocol messages; logs go to stderr or --log-file (FR-012). It executes nothing (FR-028).
func Run ¶
Run executes one CLI invocation. args is everything after the global flags: VAR=VALUE overrides interleaved with task names and their arguments.
The full pipeline (lex → parse → analyze → schedule → execute) is wired in run.go; this function resolves the Runefile and delegates.
func VersionCheck ¶ added in v0.3.0
VersionCheck implements `rune version --check [--json]`: it resolves the applicable Runefile, reads its minimum_version, and reports compatibility of the installed binary. It runs no task. When no Runefile or no requirement is present it reports "no requirement declared" (exit 0). An installed version that does not satisfy a valid requirement exits non-zero (ExitValidation).
Types ¶
type CompatibilityResult ¶ added in v0.3.0
type CompatibilityResult struct {
Installed string `json:"installed"`
Required string `json:"required"` // empty when no requirement is declared
Compatible bool `json:"compatible"`
// Development is true when the installed version is not a recognized semantic
// version (a local "dev" build): the requirement is waved through rather than
// enforced, so a machine consumer can tell this apart from a genuine match.
Development bool `json:"development"`
Runefile string `json:"runefile"` // resolved path, empty when none found
}
CompatibilityResult is the machine-readable result of `rune version --check`.
type Interrupted ¶
type Interrupted struct{ Err error }
Interrupted marks a SIGINT (exit 130).
func (*Interrupted) Error ¶
func (e *Interrupted) Error() string
func (*Interrupted) Unwrap ¶
func (e *Interrupted) Unwrap() error
type LSPOptions ¶ added in v0.3.0
type LSPOptions struct {
LogFile string // path to write logs to; empty means stderr
LogLevel string // error|warn|info|debug (coarse for the MVP)
}
LSPOptions configures the language server started by LSP.
type Options ¶
type Options struct {
File string // -f/--file
List bool // --list
DryRun bool // --dry-run
Summary bool // --summary
Dump bool // --dump
DumpFormat string // --format (with --dump)
Set []string
Watch bool
Choose bool
Yes bool
Quiet bool
Fmt bool
ClearCache bool
// IgnoreVersion bypasses the Runefile's minimum_version gate for this run
// (the CLI-only --ignore-version flag). It is never settable from a Runefile.
IgnoreVersion bool
// MCPAllowIgnoreVersion lets the MCP/agent server run despite an unmet
// minimum_version. It is an operator-only opt (a `rune serve` flag), disabled
// by default, and never settable from a Runefile.
MCPAllowIgnoreVersion bool
// Resolved per-stream color decisions (see cmd/rune): ColorStdout gates
// --list and --help (which write to stdout); ColorStderr gates Rune's own
// messages — status/echo/cache lines and diagnostics — on stderr.
ColorStdout bool
ColorStderr bool
Version string
Cwd string
Ctx context.Context // cancelled on SIGINT (nil => Background)
Stdin io.Reader
Stdout io.Writer
Stderr io.Writer
// Commands are the reserved subcommand names (and aliases). They are used
// only to enrich the "unknown task" error with a did-you-mean suggestion.
Commands []string
}
Options carries the resolved global CLI flags and I/O streams for one invocation. main.go populates it from cobra and passes it to Run.
type TaskCandidate ¶
TaskCandidate is a completable task: its name plus the first line of its doc comment, used as the shell-completion description.
func TaskCandidates ¶
func TaskCandidates(opts Options) []TaskCandidate
TaskCandidates returns the non-private, OS-matching tasks of the resolved Runefile, each with its first doc line, for dynamic shell completion. It is deliberately tolerant: any failure (no Runefile, read error, parse/compose error) yields nil so completion degrades gracefully and never disrupts the shell session. The analyzer is intentionally skipped — task names should still complete when the Runefile has semantic (not syntactic) errors.
type TaskFailure ¶
TaskFailure marks a task body failure (exit 1). Silent suppresses the trailing error banner (the [no-exit-message] attribute) without changing the exit code.
func (*TaskFailure) Error ¶
func (e *TaskFailure) Error() string
func (*TaskFailure) Unwrap ¶
func (e *TaskFailure) Unwrap() error
type UsageError ¶
type UsageError struct{ Err error }
UsageError marks an error as a usage/discovery problem (exit 2).
func (*UsageError) Error ¶
func (e *UsageError) Error() string
func (*UsageError) Unwrap ¶
func (e *UsageError) Unwrap() error
type ValidationError ¶
type ValidationError struct{ Err error }
ValidationError marks a static parse/analyze failure (exit 3). The diagnostics have already been rendered to stderr by the caller; this type only carries the exit code intent.
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string
func (*ValidationError) Unwrap ¶
func (e *ValidationError) Unwrap() error
Source Files