skilldoc

Documentation

Overview

Package skilldoc derives a structured description of the flashduty CLI's command tree (the "dump") and uses it to generate and validate the command-cards that document the CLI for an LLM operator.

The dump is the single source of truth: it is built in-process from the live cobra tree (see Build), so it can never drift from the binary it describes. The generator turns a dump into per-domain factual fences; the validator checks every documented `fduty …` example against the same dump.

Index

• func FenceEnd(group string) string
• func FenceStart(group string) string
• func GenerateFence(d Dump, group string) string
• func HasPlaceholder(tok string) bool
• type Command
• type Doc
• type Dump
  • func Build(root *cobra.Command) Dump
• type Example
  • func HarvestExamples(md string) []Example
• type Flag
• type Issue
  • func CheckFences(d Dump, docs []Doc) []Issue
  • func Validate(d Dump, docs []Doc) []Issue

Functions

func FenceEnd

func FenceEnd(group string) string

func FenceStart

func FenceStart(group string) string

FenceStart / FenceEnd return the literal markers for a group, used by the freshness check to locate fences in docs.

func GenerateFence

func GenerateFence(d Dump, group string) string

GenerateFence renders the factual fenced block for one command group: a section per leaf verb with its short description and a flag table (name, type, required, usage + enum), plus a body-only (--data) note when the command has nested JSON-only fields. Required-ness and enums are sourced from the authoritative "Request fields:" text in each command's Long; the flag list falls back to the dump's Flags when no such block exists (read-only verbs). Output is deterministic.

func HasPlaceholder

func HasPlaceholder(tok string) bool

HasPlaceholder reports whether tok is a documentation placeholder rather than a literal argument: angle-bracket tokens (<id>), shell vars ($VAR), the ellipsis (...), or `ou_xxx`-style stand-ins. The validator skips the value of any flag whose token is a placeholder.

Types

type Command

type Command struct {
	Path  string `json:"path"`  // space-joined name chain below root, e.g. "status-page change-create"
	Group string `json:"group"` // first path segment, e.g. "status-page"
	Short string `json:"short"`
	// Use is cobra's raw Use string, e.g. "change-create <page-id>". cligen folds
	// a required *_id field into a positional argument and records it here as a
	// <placeholder>; that field is then supplied positionally, NOT via its
	// same-named --flag (passing the flag alone fails the Args check). Capturing
	// Use is what lets the generator render the correct positional invocation —
	// the bare Path alone (which strips the placeholder) cannot.
	Use     string `json:"use"`
	Long    string `json:"long"` // cligen's Request/Response field text (authoritative for enums + nested --data)
	Example string `json:"example"`
	Flags   []Flag `json:"flags"`
}

Command is one runnable leaf of the CLI tree.

type Doc

type Doc struct {
	Path string
	Body string
}

Doc is a documentation file fed to the validator: its display Path (for issue reporting) and raw markdown Body.

type Dump

type Dump struct {
	Commands []Command `json:"commands"`
}

Dump is the structured snapshot of the CLI's command tree. It is the JSON contract shared between the dump oracle, the validator, and the generator.

func Build

func Build(root *cobra.Command) Dump

Build walks the cobra tree rooted at root and returns a structured dump of every runnable, non-hidden leaf command. Group containers (non-runnable parents like "status-page") are descended into but not emitted themselves.

Path is the space-joined chain of cobra command names below the root, using c.Name() so a positional placeholder in Use (e.g. "change-create <page-id>") is stripped to the bare verb. Required flags are detected via cobra's one-required-flag annotation. Enums and nested --data fields are NOT re-derived here; they live verbatim in Long, which cligen authored.

type Example

type Example struct {
	Line   int
	Tokens []string
}

Example is one harvested CLI invocation from a markdown document. Tokens are the whitespace-separated arguments AFTER the `fduty`/`flashduty` binary word (so Tokens[0] is the command group). Line is the 1-based line where the invocation began.

func HarvestExamples

func HarvestExamples(md string) []Example

HarvestExamples pulls every `fduty`/`flashduty` invocation out of markdown: fenced code blocks (```…```) and inline backtick spans alike. A candidate is any line whose first shell word is the binary; trailing-backslash continuations are joined into one example. Prose lines (no binary word) are ignored.

type Flag

type Flag struct {
	Name     string `json:"name"`
	Type     string `json:"type"`
	Default  string `json:"default"`
	Usage    string `json:"usage"`
	Required bool   `json:"required"`
}

Flag is one flag of a command, as exposed by pflag.

type Issue

type Issue struct {
	Doc    string
	Line   int
	Kind   string // "unknown-command" | "unknown-flag" | "positional-as-flag" | "stale-fence"
	Detail string
}

Issue is one validation finding against the command oracle.

func CheckFences

func CheckFences(d Dump, docs []Doc) []Issue

CheckFences asserts every GENERATED:<group> fence embedded in docs matches a fresh render from the dump. A fence whose inner content has drifted, or a start marker with no matching end marker, yields a stale-fence issue. Docs with no generated fence for a group are silently fine.

func Validate

func Validate(d Dump, docs []Doc) []Issue

Validate checks every harvested `fduty …` example in docs against the dump: an example whose leading words resolve to no command path yields an unknown-command issue; an example flag absent from its command's flag set (and not a global flag) yields an unknown-flag issue. Placeholder tokens are skipped so documentation stand-ins (<id>, $VAR) never trip the validator.