Documentation
¶
Overview ¶
Package board handles board discovery, scaffolding, and config.
The board is a "north/" directory inside the user's project repo, anchored by "north/config.yml". It is found by walking up from the current directory, the same way git finds ".git". Tasks live in one of three state folders: drafts/, tasks/, archive/.
lock.go — advisory file lock serialising board mutations.
The lock is a "north/.lock" file created with O_CREATE|O_EXCL and removed on release. It guards the read-allocate-write window of mutating operations (notably the NextID scan), so it is held only for the duration of one mutation. A lock file older than staleAfter is presumed abandoned by a crashed process and is stolen. Stdlib only — no flock, so it behaves the same on every platform git works on.
Index ¶
- Constants
- Variables
- func EnsureUserConfig(dir string) error
- func InitBoard(root string) (string, error)
- func LocateBoard(start string) (string, error)
- func Lock(boardDir string) (func(), error)
- func NextID(board string) (string, error)
- func Root(board string) string
- func Slug(title string) string
- func StateDir(board string, state models.TaskState) string
- func TaskFilename(taskID, title string) string
- func TaskFiles(board string, states ...models.TaskState) ([]string, error)
- func UserConfigDir() (string, error)
- func WriteConfig(board string, cfg Config) (string, error)
- func WriteGitattributes(board string) error
- type Config
- type DepsEnforcement
- type UserConfig
Constants ¶
const ( BoardDirname = "north" ConfigName = "config.yml" // TemplateName is the editable body scaffold used by bodyless creates. TemplateName = "task-template.md" // GitattributesName guards board files against CRLF drift on any clone. GitattributesName = ".gitattributes" // FormatVersion is the board format this binary reads and writes. Boards // stamped with a newer version are refused on load. FormatVersion = 1 )
const DefaultTaskTemplate = `## Summary
## Acceptance Criteria
## Notes
## Changes
## Comments
`
DefaultTaskTemplate is what init scaffolds into north/task-template.md. It is a suggestion, never a schema: North writes it once and never parses it back, and a missing or empty template means new tasks get a blank body — this constant is not a runtime fallback.
const LockName = ".lock"
LockName is the lock file's name inside the board dir.
Variables ¶
var DepsEnforcements = []DepsEnforcement{DepsHint, DepsValidated, DepsStrict}
DepsEnforcements lists the levels, loosest first.
Functions ¶
func EnsureUserConfig ¶ added in v0.7.0
EnsureUserConfig creates dir and scaffolds dir/config.yml with the commented template if the file does not exist. An existing file is left untouched.
func InitBoard ¶
InitBoard scaffolds a board under root (default cwd): config + state folders. Idempotent — existing files/folders are left untouched. Returns the board dir.
func LocateBoard ¶
LocateBoard walks up from start (default cwd) to find the "north/" board dir (the one containing config.yml). Returns NotFound with a hint if none exists.
func Lock ¶ added in v0.7.0
Lock takes the advisory board lock and returns a release func. It retries briefly while another process holds the lock, steals locks older than staleAfter, and returns Conflict when the board stays locked past the wait budget.
func NextID ¶
NextID returns the next free task id — a bare number, max across all folders + 1 (as a string; ids are never reused).
func TaskFilename ¶
TaskFilename is the on-disk filename for a task: "12-add-login.md".
func TaskFiles ¶
TaskFiles returns the task Markdown files in the given state folders (all states if none are given), sorted within each folder.
func UserConfigDir ¶ added in v0.7.0
UserConfigDir returns the user-level config directory, "~/.north".
func WriteConfig ¶
WriteConfig writes config.yml, stamping the current format version when the config carries none. Returns the path.
func WriteGitattributes ¶ added in v0.7.0
WriteGitattributes writes the board's .gitattributes ("* text eol=lf"), overwriting. Used by init and `doctor --fix`.
Types ¶
type Config ¶
type Config struct {
Version int `yaml:"version"`
AutoCommit bool `yaml:"auto_commit"`
DepsEnforcement DepsEnforcement `yaml:"deps_enforcement"`
}
Config holds per-board settings from "north/config.yml".
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns the defaults (current format version, auto_commit false, deps validated).
func LoadConfig ¶
LoadConfig reads "north/config.yml" into a Config. A missing file and extra keys are tolerated; malformed YAML is a hard error (a silently ignored typo would silently change behaviour, e.g. turning auto_commit off).
type DepsEnforcement ¶ added in v0.7.0
type DepsEnforcement string
DepsEnforcement grades how strictly depends_on is enforced on writes. Enforcement never touches stored data, so levels switch freely.
const ( // DepsHint never refuses a dependency-related action; it only warns // (dangling/forward references, self-refs, cycles, out-of-order moves). DepsHint DepsEnforcement = "hint" // DepsValidated keeps the graph well-formed — dangling ids, self-refs, // and cycles are refused on write, delete heals dependents — while // workflow order (finishing with unmet deps) only warns. The default. DepsValidated DepsEnforcement = "validated" // DepsStrict is validated plus workflow enforcement: moving to done or // in_progress with unmet dependencies is refused. DepsStrict DepsEnforcement = "strict" )
func ParseDepsEnforcement ¶ added in v0.7.0
func ParseDepsEnforcement(value string) (DepsEnforcement, error)
ParseDepsEnforcement coerces a string to a DepsEnforcement level.
type UserConfig ¶ added in v0.7.0
type UserConfig struct {
TUI struct {
Theme string `yaml:"theme"`
} `yaml:"tui"`
}
UserConfig holds user-level (per-user, not per-board) settings read from "~/.north/config.yml". Unlike Config, it is personal preference and never committed to the shared repo.
func DefaultUserConfig ¶ added in v0.7.0
func DefaultUserConfig() UserConfig
DefaultUserConfig returns the defaults (theme "default").
func LoadUserConfig ¶ added in v0.7.0
func LoadUserConfig(dir string) (UserConfig, error)
LoadUserConfig reads dir/config.yml into a UserConfig. A missing file and unknown keys are tolerated; a read error or malformed YAML returns the defaults alongside the error so callers can fall back and warn — they never block on this file.
Source Files