Help us shape the future of Go! Take the 2026 Go Developer Survey

formatters

package
v0.0.21 Latest Latest
Warning

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

 Go to latest Published: Oct 18, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package formatters — events.go

Output formatting for the new `pasture task events / timeline / contexts / agents` subcommands introduced by PROPOSAL-2 §7.9 (S6).

Each formatter supports two output modes per the project-wide convention:

  • OutputJSON: json.MarshalIndent with camelCase keys.
  • OutputText: human-readable multi-line summary.

Public API is symmetrical with formatters/task.go (FormatTask / FormatTasks):

  • FormatAuditEvent — single audit event.
  • FormatAuditEvents — list of audit events (events / timeline output).
  • FormatContextList — list of (Kind, ContextId) edges for one event.
  • FormatAgentEntry — single registered well-known agent + categories.
  • FormatAgentEntries — list of registered agents (agents list).

Package formatters provides output formatting functions for pasture CLI commands.

Each formatter supports two output modes:

  • OutputJSON: json.MarshalIndent with camelCase keys
  • OutputText: human-readable multi-line with labeled sections

The FormatError function always returns a string (never errors) and is safe to call in defer/cleanup paths.

Package formatters — status.go

Output formatting for `pasture status [--epoch <id>]`.

Two output shapes:

  • EpochStatusResult: full status view for a single epoch — phase, role, available transitions, slice progress, active sessions, and recent audit events (including any EpochCancelled event with its reason).
  • EpochSummaryList: the listing view when --epoch is omitted — one row per known epoch, showing its current phase and how many events it has.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FormatActiveSessions added in v0.0.5 

func FormatActiveSessions(sessions []protocol.RegisterSessionSignal, format types.OutputFormat) (string, error)

FormatActiveSessions renders the sessions registered with an epoch (the active_sessions query). JSON mode emits an array; text mode lists one session per line, or a "(none)" marker when empty.

func FormatAgentEntries 

func FormatAgentEntries(entries []AgentEntry, format types.OutputFormat) (string, error)

FormatAgentEntries renders a list of registered agents.

Used by `pasture task agents list`.

func FormatAgentEntry 

func FormatAgentEntry(a AgentEntry, format types.OutputFormat) (string, error)

FormatAgentEntry renders one agent + its categories.

Used by `pasture task agents show <id>`.

func FormatAuditEvent 

func FormatAuditEvent(e protocol.AuditEvent, format types.OutputFormat) (string, error)

FormatAuditEvent renders a single audit event in the requested format.

Used by `pasture task contexts <event-id>` (paired with the contexts list) and as a building block for FormatAuditEvents.

func FormatAuditEvents 

func FormatAuditEvents(events []protocol.AuditEvent, format types.OutputFormat) (string, error)

FormatAuditEvents renders a list of audit events. JSON mode is a top-level array; text mode is one line per event suitable for piping to grep/fzf.

Used by `pasture task events` and `pasture task timeline`.

func FormatComment 

func FormatComment(c provenance.Comment, format types.OutputFormat) (string, error)

FormatComment renders a single comment.

func FormatComments 

func FormatComments(cs []provenance.Comment, format types.OutputFormat) (string, error)

FormatComments renders all comments on a task in chronological order.

func FormatContextList 

func FormatContextList(contexts []protocol.Context, format types.OutputFormat) (string, error)

FormatContextList renders the context_edges attached to one event.

Used by `pasture task contexts <event-id>`.

func FormatDepTree 

func FormatDepTree(rootId string, edges []provenance.Edge, format types.OutputFormat) (string, error)

FormatDepTree renders the blocked-by edges reachable from rootId. JSON output preserves the DFS-ordered edge list so consumers can rebuild the tree. Text output renders an indented tree, deduplicating shared subtrees the same way DFS visits them.

func FormatEdge 

func FormatEdge(e provenance.Edge, format types.OutputFormat) (string, error)

FormatEdge renders a single edge in the requested output format. Used by `task dep add` to confirm the just-created edge.

func FormatEpochList added in v0.0.5 

func FormatEpochList(epochs []EpochSummary, format types.OutputFormat) (string, error)

FormatEpochList renders the epoch listing.

Text mode: one epoch per line with phase and event count; an actionable empty message when no epochs exist. JSON mode: an array of epoch summary objects.

func FormatEpochQuery added in v0.0.5 

func FormatEpochQuery(result protocol.QueryStateResult, query protocol.QueryName, format types.OutputFormat) (string, error)

FormatEpochQuery renders the slice of a QueryStateResult selected by query.

full_state renders the complete view (via FormatEpochState); current_state renders only the phase + role; available_transitions renders only the reachable transitions. JSON keys stay camelCase and consistent with FormatEpochState so consumers parse one shape.

func FormatEpochState 

func FormatEpochState(result protocol.QueryStateResult, format types.OutputFormat) (string, error)

FormatEpochState formats a QueryStateResult for CLI output.

JSON mode: json.MarshalIndent with camelCase keys. Text mode: human-readable multi-line with labeled sections.

func FormatEpochStatus added in v0.0.5 

func FormatEpochStatus(r EpochStatusResult, format types.OutputFormat) (string, error)

FormatEpochStatus renders a single-epoch status view.

Text mode: a human-readable overview with labeled sections. JSON mode: a structured object with camelCase keys.

func FormatError 

func FormatError(err error, format types.OutputFormat) string

FormatError formats an error for CLI output.

If err is a *errors.StructuredError, the full diagnostic fields are included. For JSON format, returns a JSON object with category/what/why/impact/fix fields. For Text format, returns the multi-line Report() output. For unknown formats or plain errors, falls back to err.Error(). Always returns a non-empty string; never returns an error itself.

func FormatHookRecord added in v0.0.4 

func FormatHookRecord(eventType, sha string, eventID int64, message, author, branch, timestamp, repo string, remotes map[string]string, format types.OutputFormat) (string, error)

FormatHookRecord formats the result of `pasture hook record` for CLI output.

JSON mode: camelCase keys for all recorded fields; metadata fields (including repo and remotes) are omitted via omitempty when absent.

Text mode: "recorded <eventType> event for sha <sha> (event #N)" (unchanged).

func FormatLabels 

func FormatLabels(taskId string, labels []string, format types.OutputFormat) (string, error)

FormatLabels prints the label set for a task.

func FormatMigratePlan 

func FormatMigratePlan(plan MigratePlan, format types.OutputFormat) (string, error)

FormatMigratePlan renders the dry-run plan output for `pasture migrate`.

JSON mode is a structured object so CI scripts can parse it; text mode is a human-readable summary keyed by audit.stepDescription (Phase 11 R1-A uses plain-language, backfill-first phrasing — e.g. "v3->v4: backfill epoch IDs into the context-edge table, then drop the legacy epoch_id column").

func FormatMigrateResult 

func FormatMigrateResult(r MigrateResult, format types.OutputFormat) (string, error)

FormatMigrateResult renders the post-migration success line.

Text mode matches the §7.9 wording exactly: 

migrated <db-path> from v<from> to v<to>

func FormatQueueConcurrency added in v0.0.8 

func FormatQueueConcurrency(q QueueConcurrency, format types.OutputFormat) (string, error)

FormatQueueConcurrency renders one queue's concurrency setting.

func FormatSignalResult 

func FormatSignalResult(success bool, format types.OutputFormat) (string, error)

FormatSignalResult formats a signal delivery result for CLI output.

JSON mode: {"success": true/false} Text mode: "Signal delivered successfully" / "Signal delivery failed"

func FormatSliceProgressState added in v0.0.5 

func FormatSliceProgressState(events []protocol.SliceProgressSignal, format types.OutputFormat) (string, error)

FormatSliceProgressState renders the slice-progress events reported to an epoch (the slice_progress_state query). JSON mode emits an array; text mode lists one event per line, or a "(none)" marker when empty.

func FormatStartResult 

func FormatStartResult(workflowId string, format types.OutputFormat) (string, error)

FormatStartResult formats an epoch start result for CLI output.

JSON mode: {"workflowId": "..."} Text mode: "Started epoch: workflow_id=..."

func FormatTask 

func FormatTask(t provenance.Task, format types.OutputFormat) (string, error)

FormatTask renders a single task in the requested output format.

func FormatTasks 

func FormatTasks(ts []provenance.Task, format types.OutputFormat) (string, error)

FormatTasks renders a list of tasks in the requested output format. JSON output is a top-level array. Text output is a one-line-per-task summary suitable for piping to grep / fzf.

func FormatTypedTree added in v0.0.14 

func FormatTypedTree(rootId string, edges []provenance.Edge, kinds []provenance.EdgeKind, format types.OutputFormat) (string, error)

FormatTypedTree renders a typed relation tree for a non-legacy selection: a single non-blocked_by kind, or every kind. The legacy blocked_by-only mode keeps its own path (FormatDepTree) so its bytes never change.

The input edges must already be in the traversal order produced by the handler walk (kind-major, then target ID ascending, DFS pre-order, repeats included). Text and JSON consume the same marked list, so edge order and repeat markers always agree.

func HookLifecycle added in v0.0.5 

func HookLifecycle(w io.Writer, page model.LifecyclePage, format string) error

Types

type AgentEntry 

type AgentEntry struct {
	AgentId       string
	Kind          string
	Name          string
	WellKnownName string // empty when no row exists in pasture_well_known_agents
	AutomatonRole protocol.AutomatonRole
	PastureRole   protocol.PastureRole
}

AgentEntry is the tuple presented by `pasture task agents list / show`. It pairs a Provenance AgentId (wire string) with its registered well-known name (if any), and the AutomatonRole / PastureRole stored in pasture_agent_categories. Lives in the formatters package because it is the view-model for one CLI subcommand and has no business existing inside the tracker (which deals in raw rows).

type EpochStatusResult added in v0.0.5 

type EpochStatusResult struct {
	// EpochId is the epoch being described.
	EpochId string
	// CurrentPhase is the epoch's current phase.
	CurrentPhase protocol.PhaseId
	// CurrentRole is the agent role expected to act at the current phase.
	CurrentRole protocol.RoleId
	// AvailableTransitions lists the phases the epoch can advance to from its
	// current state (computed from the FSM — not a value frozen at write time).
	AvailableTransitions []protocol.PhaseId
	// TransitionHistory is the ordered list of phase transitions made so far.
	TransitionHistory []protocol.TransitionRecord
	// SliceProgress is the slice-completion events reported to this epoch.
	SliceProgress []protocol.SliceProgressSignal
	// ActiveSessions is the set of sessions currently registered with this epoch.
	ActiveSessions []protocol.RegisterSessionSignal
	// RecentEvents is the N most-recent audit events for quick history review.
	// Events are in ascending (oldest-first) order so the most recent is last.
	RecentEvents []protocol.AuditEvent
	// CancelReason is non-nil when an EpochCancelled event appears in the audit
	// trail, carrying the operator reason (which may be an empty string if no
	// reason was provided).
	CancelReason *string
}

EpochStatusResult is the data model for `pasture status --epoch <id>`. It combines the projected EpochState snapshot with recent audit events so the CLI can present a single-screen overview without querying multiple commands.

type EpochSummary added in v0.0.5 

type EpochSummary struct {
	EpochId      string
	CurrentPhase protocol.PhaseId
	EventCount   int
}

EpochSummary is one row in the epoch listing when --epoch is omitted.

type MigratePlan 

type MigratePlan struct {
	DBPath         string
	CurrentVersion int
	TargetVersion  int
	Steps          []MigratePlanStep
	DryRun         bool
}

MigratePlan is the data the `pasture migrate --dry-run` handler hands to the formatter: each entry describes one forward step the migrator WOULD apply. FromVersion is the currently-recorded on-disk version; ToVersion is the version after applying this step. The CurrentVersion / TargetVersion fields describe the overall plan span.

type MigratePlanStep 

type MigratePlanStep struct {
	FromVersion int
	ToVersion   int
	Description string
}

MigratePlanStep is one row in a migration plan.

type MigrateResult 

type MigrateResult struct {
	DBPath      string
	FromVersion int
	ToVersion   int
}

MigrateResult is the data the `pasture migrate` handler hands the formatter after a successful (non-dry-run) migration.

type QueueConcurrency added in v0.0.8 

type QueueConcurrency struct {
	Queue             string
	WorkerConcurrency *int
}

QueueConcurrency is one queue's per-process limit on concurrent jobs, as it is stored in the pasture database.

WorkerConcurrency is a pointer because "no limit" and "a limit of zero" are different states in storage and must not be rendered the same way. nil means the queue runs as many jobs at once as it can dequeue.

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.