Documentation
¶
Overview ¶
Package list implements the `aiwf list` verb (per-verb subpackage of M-0116; cmd/aiwf/main.go newRootCmd wires it via NewCmd).
Index ¶
- Constants
- func ComputeTitleBudget(rows []ListSummary, renderedStatuses []string, termWidth int) int
- func IsKnownKind(s string) bool
- func NewCmd() *cobra.Command
- func RenderListCountsText(w io.Writer, counts ListCounts)
- func RenderListRowsText(w io.Writer, rows []ListSummary, titleBudget int, colorEnabled bool)
- func Run(root, kind, status, parent string, archived bool, format string, ...) int
- func UnionAllStatuses() []string
- type ListCounts
- type ListSummary
Constants ¶
const MinTitleColumnRunes = 10
MinTitleColumnRunes is the floor below which the title column is no longer worth truncating — at 10 runes most titles collapse to a few initial words plus "…", which is more annoying than useful. When the terminal is narrower than what's needed to leave this much room, we give up on truncation and let the terminal wrap as it always has.
Variables ¶
This section is empty.
Functions ¶
func ComputeTitleBudget ¶
func ComputeTitleBudget(rows []ListSummary, renderedStatuses []string, termWidth int) int
ComputeTitleBudget returns the per-row rune cap for the title column, or 0 to disable truncation. termWidth=0 means "no TTY / no-trunc / width unknown" — pass through as 0 and the caller skips truncation. renderedStatuses is the per-row status string as it will be written (glyph + space + status when the row matches the G-0080 palette); measured here so the budget reflects the actual column width.
The math: tabwriter renders id|status|title|parent with 2-char padding between columns. Natural row width is id_w + 2 + status_w + 2 + title_w + 2 + parent_w. Set title_w = termWidth - (id_w + status_w + parent_w + 6) and floor at MinTitleColumnRunes — if the remainder would be below the floor, truncation buys so little (and looks so ugly) that we return 0 and let the terminal wrap. The header row contributes its own width (ID/STATUS/TITLE/PARENT, all narrower than typical content) so we don't measure it.
func IsKnownKind ¶
IsKnownKind validates --kind input against the closed kind set before the verb walks the tree. Cheap usage-error check.
func NewCmd ¶
NewCmd builds `aiwf list`: the AI-first read primitive over the planning tree. Read-only; no commit. Default semantic is "non- terminal entities" (forward-compat with ADR-0004); --archived widens to include terminal-status entities.
func RenderListCountsText ¶
func RenderListCountsText(w io.Writer, counts ListCounts)
RenderListCountsText emits the per-kind summary line in the order dictated by entity.AllKinds. Format:
5 epics · 47 milestones · 12 ADRs · 14 gaps · 3 decisions · 1 contract
func RenderListRowsText ¶
func RenderListRowsText(w io.Writer, rows []ListSummary, titleBudget int, colorEnabled bool)
RenderListRowsText emits one row per entity with aligned columns:
ID STATUS TITLE PARENT M-001 ○ draft M one E-01 M-002 → in_progress M two E-01
Empty-result is the empty string (no header) — keeps the verb cheap to consume in shell pipelines and grep-friendly. The status column carries a 1-rune glyph + space prefix when the status maps to the G-0080 palette (every kernel status does); the glyph is content, not style, and appears in piped output the same as in a TTY.
titleBudget caps the title column's rune width when stdout is a TTY narrower than a row's natural width — closes G-0080's tabwriter-wrap bug where long titles wrap into the id-column gutter. A non-positive budget disables truncation (piped output, --no-trunc, or a TTY wide enough to fit the row as-is). The cap is applied per-row before the tabwriter sees the input, so tabwriter's column alignment stays intact.
colorEnabled toggles the ANSI-bold styling on the header row. It is the only place ANSI escapes enter this verb's output; row content stays escape-free so downstream tooling (grep, awk) sees plain text.
func UnionAllStatuses ¶
func UnionAllStatuses() []string
UnionAllStatuses returns every status string any kind allows, sorted and de-duplicated. Used as the --status completion fallback when --kind has not been set yet.
Types ¶
type ListCounts ¶
ListCounts is the per-kind count payload for the no-args invocation. Keys are kind names; the renderer iterates entity.AllKinds() so the order is canonical and a future kind picks up automatically.
func BuildListCounts ¶
func BuildListCounts(tr *tree.Tree) ListCounts
BuildListCounts returns the per-kind count of non-terminal entities for the no-args invocation. Iteration order follows entity.AllKinds.
type ListSummary ¶
type ListSummary struct {
ID string `json:"id"`
Kind string `json:"kind"`
Status string `json:"status"`
Title string `json:"title"`
Parent string `json:"parent,omitempty"`
Path string `json:"path,omitempty"`
}
ListSummary is the per-entity row emitted by `aiwf list`. The shape is the JSON envelope's `result` element verbatim and is the contract downstream tooling depends on; keep it stable across V1 evolutions.
func BuildListRows ¶
func BuildListRows(tr *tree.Tree, kind, status, parent string, archived bool) []ListSummary
BuildListRows applies the V1 filter axes to tr and returns the matched entities as summary rows in id-ascending order. Default semantic excludes terminal-status entities; archived=true widens.
The kind+status filter routes through tree.FilterByKindStatuses so `aiwf list --kind gap --status open` and `aiwf status`'s Open gaps section share one source of truth (M-072 AC-6).
Source Files