Documentation
¶
Overview ¶
Package driver runs a project's tracker driver: an executable at .f10/driver satisfying the verb contract in docs/driver-contract.md.
f10 specifies that contract and implements none of it. What a driver talks to - Notion, Jira, a wiki, a spreadsheet - is the project's business, and so is the language it is written in. The one thing f10 fixes is the shape of the conversation: a verb, an argument, data on stdout, and a reserved exit code for a verb the driver does not offer.
Read verbs return data and change nothing; write verbs change the tracker and only the tracker. Neither acts on the local machine: f10 opens every url and creates every branch, which is what lets `open` mean the same thing for a task as for a pull request, where no driver is involved.
Index ¶
Constants ¶
const ( VerbRead = "read" // stdout: the task as markdown VerbURL = "url" // stdout: one url VerbSearch = "search" // stdout: JSON rows, one task each VerbBranch = "branch" // stdout: one branch name, never created VerbChildren = "children" // stdout: JSON rows, one subtask each VerbIndex = "index" // stdout: one url, the task list; no argument VerbList = "list" // stdout: JSON rows, the first page of open tasks; no argument // VerbCreate is the first write verb: stdin is the task as markdown, // `# <title>` first; stdout is the new task's id. VerbCreate = "create" )
Verbs a driver may implement. All but create are read verbs.
const ExitUnsupported = 3
ExitUnsupported is the contract's reserved exit code: the driver ran and understood the call, but does not implement that verb. It is a normal answer, not a failure, so a driver can offer `read` without `search`.
Variables ¶
var ErrUnsupported = errors.New("driver does not implement this verb")
ErrUnsupported reports the reserved exit code back to the caller, which then falls back or explains, rather than failing the command.
var Priorities = []string{"urgent", "high", "medium", "low"}
Priorities is the contract's ordered priority vocabulary, most urgent first. A search or list row may carry one as its `priority`; a driver maps its tracker's own values onto these, and a row without one has no priority.
Functions ¶
func PriorityRank ¶ added in v0.38.0
PriorityRank places a row's priority value in Priorities, case and surrounding space ignored: its index and true, or -1 and false for a value outside the vocabulary.
Types ¶
type Driver ¶
A Driver is one project's executable.
func Find ¶
Find returns the driver for a storage root, or nil when the project has none - the ordinary case, which callers answer by falling back to the host's issues.
func (*Driver) Run ¶
Run invokes one verb and returns its stdout. The reserved code becomes ErrUnsupported; any other non-zero exit is a failure carrying the driver's own stderr verbatim, because the driver knows why it failed and f10 does not.
func (*Driver) RunInput ¶ added in v0.41.0
func (d *Driver) RunInput(ctx context.Context, input, verb string, args ...string) (string, string, error)
RunInput invokes a write verb with input on its stdin and returns its stdout and, on success, its stderr: a warning about a property the tracker has no field for. It is never retried, because a failed write may still have changed the tracker.
Source Files