cli

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 7, 2026 License: MIT Imports: 34 Imported by: 0

Documentation

Overview

Package cli implements the iterion command-line interface.

Index

Constants

View Source 
const IterationLatest = -1

IterationLatest is the sentinel value of *InspectOptions.Iteration meaning "use the most recently started iteration of (branch, node)".

Variables

This section is empty.

Functions

func FormatDuration 

func FormatDuration(d time.Duration) string

FormatDuration formats a duration for human display.

func FormatTime 

func FormatTime(t time.Time) string

FormatTime formats a time for human display.

func IsTTY 

func IsTTY() bool

IsTTY reports whether stdin is connected to a terminal.

func ParseAnswerFlags 

func ParseAnswerFlags(flags []string) (map[string]string, error)

ParseAnswerFlags parses a slice of "key=value" strings into a map.

func ParseAnswersFile 

func ParseAnswersFile(path string) (map[string]interface{}, error)

ParseAnswersFile reads a JSON file containing answer key-value pairs.

func ParseVarFlags 

func ParseVarFlags(flags []string) (map[string]string, error)

ParseVarFlags parses a slice of "key=value" strings into a map.

func PrintError 

func PrintError(w io.Writer, err error)

StatusIcon returns a human-friendly icon for a run status. PrintError writes a structured error message to w. If the error is a RuntimeError it includes the error code, node, and hint.

func PromptHumanAnswers 

func PromptHumanAnswers(interaction *store.Interaction) (map[string]interface{}, error)

PromptHumanAnswers displays the interaction questions and prompts the user for answers interactively via stdin. Returns the answers as a map.

func RawCommit added in v0.4.0 

func RawCommit() string

RawCommit returns the bare commit string (short SHA, possibly empty).

func RawVersion added in v0.4.0 

func RawVersion() string

RawVersion returns the bare version string (e.g. "v1.2.3" or "dev"). Used by the desktop About panel and the auto-updater to compare semver against the latest manifest.

func RunDiagram 

func RunDiagram(opts DiagramOptions, p *Printer) error

RunDiagram compiles an .iter file and outputs its Mermaid diagram.

func RunEditor 

func RunEditor(ctx context.Context, opts EditorOptions, p *Printer) error

RunEditor starts the editor HTTP server.

Port semantics:

  • opts.Port == 0 : default to 4891 (legacy CLI behaviour — the `iterion editor` cobra command relies on this when --port is omitted).
  • opts.Port == -1 : let the OS pick a free port. The actual bind address is delivered via opts.OnReady. Used by the desktop host so multiple instances/projects never fight for 4891.
  • opts.Port > 0 : use that exact port.

func RunInit 

func RunInit(opts InitOptions, p *Printer) error

RunInit initializes a directory with an example workflow and environment config.

func RunInspect 

func RunInspect(opts InspectOptions, p *Printer) error

RunInspect loads and displays a run's state.

func RunReport 

func RunReport(opts ReportOptions, p *Printer) error

RunReport generates a detailed chronological report for a run.

func RunResumeWithFile 

func RunResumeWithFile(ctx context.Context, iterFile string, opts ResumeOptions, p *Printer) error

RunResumeWithFile resumes a paused run using a workflow file and answers.

func RunRun 

func RunRun(ctx context.Context, opts RunOptions, p *Printer) error

RunRun executes a workflow or recipe and reports the outcome.

func RunSandboxDoctor added in v0.4.0 

func RunSandboxDoctor(p *Printer) error

RunSandboxDoctor prints diagnostics about the sandbox subsystem. It is the implementation of `iterion sandbox doctor`.

The output covers:

  • the detected host kind (local / desktop / cloud) and how it was determined (env var vs heuristic);
  • which container runtime, if any, is on the user's PATH;
  • the registered sandbox drivers in preference order;
  • the driver the factory would pick for a run started from this environment, plus its advertised capabilities;
  • the global sandbox default (ITERION_SANDBOX_DEFAULT) — the lowest precedence layer that all workflows inherit from.

Output is human-readable by default; pass --json on the parent command to switch to JSON. Phase 0 prints stable string keys; Phase 1+ may extend the JSON shape — keys present today will not change.

func RunValidate 

func RunValidate(path string, p *Printer) error

RunValidate parses, compiles, and validates an .iter file.

func StatusIcon 

func StatusIcon(status string) string

func Version 

func Version() string

Version returns the human-readable version string (e.g. "v1.2.3 (abc1234)"). It is the public entry point for cmd/iterion (and cmd/iterion-desktop) to read version info without importing internal/appinfo directly — Go's internal-package rule forbids imports of pkg/internal/ from outside pkg/.

Types

type DiagramOptions 

type DiagramOptions struct {
	File string // .iter file path
	View string // "compact" (default), "detailed", or "full"
}

DiagramOptions holds options for the diagram command.

type DiagramResult 

type DiagramResult struct {
	File         string `json:"file"`
	WorkflowName string `json:"workflow_name"`
	View         string `json:"view"`
	Mermaid      string `json:"mermaid"`
}

DiagramResult holds the output of a diagram command.

type EditorOptions 

type EditorOptions struct {
	Port      int
	Bind      string // bind address (default "127.0.0.1"); use "0.0.0.0" to expose on LAN
	Dir       string // working directory (for examples)
	StoreDir  string // run store directory (default: nearest .iterion ancestor of Dir, or <Dir>/.iterion)
	NoBrowser bool   // skip opening browser

	// SessionToken, when non-empty, enables a session-cookie middleware on
	// the server. Used by the desktop host so other local processes can't
	// hit the editor's filesystem-write endpoints. Empty in CLI mode.
	SessionToken string

	// OnReady, when non-nil, is invoked once the HTTP listener is up and
	// the server has accepted its bind address. The argument is the actual
	// host:port the listener is bound to (useful when Port=0 / random).
	// Invoked from a goroutine; callers must be ready for it to fire
	// concurrently with their own Run loop.
	OnReady func(addr string)
}

EditorOptions holds options for the editor command.

type InitOptions 

type InitOptions struct {
	Dir string // target directory (default: ".")
}

InitOptions holds the configuration for the init command.

type InitResult 

type InitResult struct {
	Dir          string   `json:"dir"`
	FilesCreated []string `json:"files_created"`
	FilesSkipped []string `json:"files_skipped"`
}

InitResult holds the outcome for JSON output.

type InspectOptions 

type InspectOptions struct {
	RunID    string
	StoreDir string
	Events   bool // show event log
	Full     bool // show all details

	Node      string
	Branch    string
	Iteration *int // nil = unset; -1 = latest started
	// ExecutionID is the alternative single-string selector
	// ("exec:<branch>:<node>:<iter>"). Mutually exclusive with --node.
	ExecutionID string
	Section     InspectSection
	LogTail     int
	ListNodes   bool
}

InspectOptions holds the configuration for the inspect command.

type InspectSection 

type InspectSection string

InspectSection enumerates the per-node report buckets the caller can restrict to via --section. Empty value behaves as SectionAll. 

const (
	SectionAll          InspectSection = "all"
	SectionSummary      InspectSection = "summary"
	SectionEvents       InspectSection = "events"
	SectionTrace        InspectSection = "trace"
	SectionTools        InspectSection = "tools"
	SectionArtifacts    InspectSection = "artifacts"
	SectionInteractions InspectSection = "interactions"
	SectionLog          InspectSection = "log"
)

type OutputFormat 

type OutputFormat int

OutputFormat controls how results are rendered. 

const (
	OutputHuman OutputFormat = iota
	OutputJSON
)

type Printer 

type Printer struct {
	W      io.Writer
	Format OutputFormat
}

Printer writes structured output in the selected format.

func NewPrinter 

func NewPrinter(format OutputFormat) *Printer

NewPrinter creates a Printer writing to stdout.

func (*Printer) Blank 

func (p *Printer) Blank()

Blank prints an empty line.

func (*Printer) Header 

func (p *Printer) Header(title string)

Header prints a section header.

func (*Printer) JSON 

func (p *Printer) JSON(v interface{})

JSON emits v as indented JSON.

func (*Printer) KV 

func (p *Printer) KV(key, value string)

KV prints a key-value pair with aligned formatting.

func (*Printer) Line 

func (p *Printer) Line(format string, args ...interface{})

Line prints a formatted line.

func (*Printer) Table 

func (p *Printer) Table(headers []string, rows [][]string)

Table prints rows with column headers.

type ReportOptions 

type ReportOptions struct {
	RunID    string
	StoreDir string
	Output   string // output file path (empty = stdout)
}

ReportOptions holds the configuration for the report command.

type ResumeOptions 

type ResumeOptions struct {
	RunID       string
	StoreDir    string
	AnswersFile string            // path to JSON answers file
	Answers     map[string]string // --answer key=value overrides
	LogLevel    string            // log level (default: "info", env: ITERION_LOG_LEVEL)
	Force       bool              // allow resume despite workflow hash change
	Executor    runtime.NodeExecutor
	// Background marks this invocation as a managed-runner subprocess
	// spawned by the editor server. The CLI writes a .pid file so the
	// server can detect liveness across its own restart.
	Background bool
}

ResumeOptions holds the configuration for the resume command.

type RunOptions 

type RunOptions struct {
	File          string               // .iter file path
	Recipe        string               // recipe JSON file path (alternative to File)
	Vars          map[string]string    // --var key=value overrides
	RunID         string               // explicit run ID (auto-generated if empty)
	StoreDir      string               // store directory (default: nearest .iterion ancestor of the .iter file, or alongside it)
	Timeout       time.Duration        // maximum run duration (0 = no limit)
	LogLevel      string               // log level (default: "info", env: ITERION_LOG_LEVEL)
	NoInteractive bool                 // disable interactive TTY prompting on human pause
	Executor      runtime.NodeExecutor // pluggable executor (nil = stub)
	// Background marks this invocation as a managed-runner subprocess
	// spawned by the editor server. The CLI writes a .pid file so the
	// server can detect liveness across its own restart, and forces
	// NoInteractive (no TTY in the spawned process).
	Background bool
	// MergeInto controls the worktree-finalization fast-forward target
	// for `worktree: auto` runs. "" or "current" → FF the user's
	// currently-checked-out branch (default); "none" → skip FF;
	// <branch-name> → FF that branch (must match currently-checked-out).
	MergeInto string
	// BranchName overrides the default storage branch
	// `iterion/run/<friendly>` created on the worktree's HEAD. The
	// branch is always created (GC guard); on collision a numeric
	// suffix is appended.
	BranchName string
	// MergeStrategy selects how the run's commits are landed on the
	// merge target when AutoMerge is on: "squash" (default) collapses
	// into one commit; "merge" fast-forwards (preserves history).
	MergeStrategy string
	// AutoMerge toggles whether the engine performs the merge at end
	// of run. CLI default is true (preserves prior behaviour); the
	// editor sets false by default to defer merge to a UI action.
	AutoMerge bool
	// Sandbox is the run-level override for the sandbox activation
	// mode ("", "none", "auto"). "" inherits the project default
	// (ITERION_SANDBOX_DEFAULT) which itself defaults to "" (no
	// sandbox). The workflow's own `sandbox:` block is the next layer
	// of precedence; per-node overrides win above all. See pkg/sandbox.
	Sandbox string
	// SandboxDefaultImage overrides the image ref used by `sandbox: auto`
	// when no .devcontainer/devcontainer.json is found in the workspace.
	// Empty inherits ITERION_SANDBOX_DEFAULT_IMAGE then the built-in
	// default (`ghcr.io/socialgouv/iterion-sandbox-slim:<iterion-version>`).
	SandboxDefaultImage string
}

RunOptions holds the configuration for the run command.

type ValidateResult 

type ValidateResult struct {
	File               string   `json:"file"`
	Valid              bool     `json:"valid"`
	WorkflowName       string   `json:"workflow_name,omitempty"`
	NodeCount          int      `json:"node_count,omitempty"`
	EdgeCount          int      `json:"edge_count,omitempty"`
	ParseDiagnostics   []string `json:"parse_diagnostics,omitempty"`
	CompileDiagnostics []string `json:"compile_diagnostics,omitempty"`
}

ValidateResult holds the outcome of a validate command.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.