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-msg 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.
Index ¶
- func FormatAgentEntries(entries []AgentEntry, format types.OutputFormat) (string, error)
- func FormatAgentEntry(a AgentEntry, format types.OutputFormat) (string, error)
- func FormatAuditEvent(e protocol.AuditEvent, format types.OutputFormat) (string, error)
- func FormatAuditEvents(events []protocol.AuditEvent, format types.OutputFormat) (string, error)
- func FormatComment(c provenance.Comment, format types.OutputFormat) (string, error)
- func FormatComments(cs []provenance.Comment, format types.OutputFormat) (string, error)
- func FormatContextList(contexts []protocol.Context, format types.OutputFormat) (string, error)
- func FormatDepTree(rootId string, edges []provenance.Edge, format types.OutputFormat) (string, error)
- func FormatEdge(e provenance.Edge, format types.OutputFormat) (string, error)
- func FormatEpochState(result types.QueryStateResult, format types.OutputFormat) (string, error)
- func FormatError(err error, format types.OutputFormat) string
- func FormatHookRecord(eventType, sha string, eventID int64, ...) (string, error)
- func FormatLabels(taskId string, labels []string, format types.OutputFormat) (string, error)
- func FormatMigratePlan(plan MigratePlan, format types.OutputFormat) (string, error)
- func FormatMigrateResult(r MigrateResult, format types.OutputFormat) (string, error)
- func FormatSignalResult(success bool, format types.OutputFormat) (string, error)
- func FormatStartResult(workflowId, runId string, format types.OutputFormat) (string, error)
- func FormatTask(t provenance.Task, format types.OutputFormat) (string, error)
- func FormatTasks(ts []provenance.Task, format types.OutputFormat) (string, error)
- type AgentEntry
- type MigratePlan
- type MigratePlanStep
- type MigrateResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 ¶
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 FormatEpochState ¶
func FormatEpochState(result types.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 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 ¶
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 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 FormatStartResult ¶
func FormatStartResult(workflowId, runId string, format types.OutputFormat) (string, error)
FormatStartResult formats an epoch start result for CLI output.
JSON mode: {"workflowId": "...", "runId": "..."} Text mode: "Started epoch: workflow_id=..., run_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.
Types ¶
type AgentEntry ¶
type AgentEntry struct {
AgentId 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 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 ¶
MigratePlanStep is one row in a migration plan.
type MigrateResult ¶
MigrateResult is the data the `pasture migrate` handler hands the formatter after a successful (non-dry-run) migration.
Source Files