format

Documentation

Overview

Package format provides shared rendering helpers for slash command reply text (IM-friendly plain-text payloads).

Both /close's per-entry table and /new's per-entry table render a header line + a sorted list of result rows. They share the byte cap (Feishu's 4 KB single-message limit), the "...and N more" tail, the typed-priority sort, and the row shape. This package centralizes those so neither close nor newcmd needs to import the other for rendering.

Specific commands still own the wording of their headers and row-render functions — format only knows about the byte cap, sort, and tail helpers, plus the RenderedRow output struct that the row-render callback returns.

Lives under internal/command/ as a sibling of close / newcmd / stop — the helpers are shared across command packages, not specific to any one command.

Index

• Constants
• func FormatTable[T any](rows []T, render Render[T], headerBuilder HeaderBuilder) string
• func HumanAction(action string) string
• func JoinCounts(parts []string) string
• type HeaderBuilder
• type Render
• type RenderedRow
• type RowBucket

Constants

const ReplyByteCap = 4096

ReplyByteCap is the Feishu single-message payload limit. Both /close and /new format strings cap here to keep the channel side from rejecting the message outright.

const TailFmt = "  ... and %d more"

TailFmt is the "...and N more" suffix appended when the output would otherwise exceed the byte cap.

Functions

func FormatTable

func FormatTable[T any](rows []T, render Render[T], headerBuilder HeaderBuilder) string

FormatTable renders rows as an IM-friendly table:

• Calls render on each row to produce text + bucket
• Sorts by (bucket asc, agent, cwd) — typed-priority order
• Builds the header via headerBuilder
• Truncates to ReplyByteCap with TailFmt suffix

Returns the empty string when rows is empty. Callers provide their own empty-state reply (e.g. "No active agents to close." for /close; /new handles empty differently).

func HumanAction

func HumanAction(action string) string

HumanAction returns a short human-readable verb for an Action string (used in error messages). Exported so callers can build consistent error-row text.

func JoinCounts

func JoinCounts(parts []string) string

JoinCounts joins the count summary fragment used in mixed- result headers. Kept here so /close and /new use the same comma-space separator.

Types

type HeaderBuilder

type HeaderBuilder func(success, skipped, failed int) string

HeaderBuilder builds the top-of-reply line from the (success, skipped, failed) counts. Specific commands own the wording.

type Render

type Render[T any] func(T) RenderedRow

Render is the per-row callback callers provide. It maps one of their result types to a formatted row + sort bucket.

T is intentionally unconstrained (any) — callers' result types don't need to implement any interface; the callback just constructs a RenderedRow from whatever data the type carries. This keeps the call-site boilerplate to "one function" per command.

type RenderedRow

type RenderedRow struct {
	Text   string
	Bucket RowBucket
	Agent  string
	Cwd    string
}

RenderedRow is one formatted line + the structured fields the sorter needs. Produced by the row-render callback passed to FormatTable.

type RowBucket

type RowBucket int

RowBucket is the typed priority bucket for a formatter row. Lower values sort first. success < failure < skipped so the user sees ✓ first, then ✗, then • (previous alphabetical sort on the rendered strings placed `•` (U+2022) before `✓` (U+2713) before `✗` (U+2717), inverting the spec).

const (
	BucketSuccess RowBucket = iota
	BucketFailure
	BucketSkipped
)