Documentation
¶
Overview ¶
Package spec handles specification file loading, status management, and listing.
Index ¶
- Variables
- func AutoBranchName(name string) string
- func NormalizeSpecFilename(ctx context.Context, name string, dirs ...string) (string, error)
- func RenumberSpecsAfterRemoval(ctx context.Context, dir string, removedNum int) error
- func ValidateBranchName(ctx context.Context, branch string) error
- type AutoCompleter
- type Frontmatter
- type Lister
- type PromptManager
- type SpecFile
- type SpecStatuses
- type Status
- type Summary
Constants ¶
This section is empty.
Variables ¶
var AvailableSpecStatuses = SpecStatuses{ StatusIdea, StatusDraft, StatusApproved, StatusGenerating, StatusPrompted, StatusVerifying, StatusCompleted, StatusRejected, }
AvailableSpecStatuses is the collection of all valid spec Status values.
Functions ¶
func AutoBranchName ¶ added in v0.39.0
AutoBranchName generates a canonical branch name from a spec file's basename (without .md extension). If the name has a numeric prefix, it returns "dark-factory/spec-NNN". Otherwise it returns "dark-factory/" + sanitized name.
func NormalizeSpecFilename ¶ added in v0.26.0
NormalizeSpecFilename assigns a sequential numeric prefix to name if it does not already have one. Scans all given dirs for .md files, finds the highest existing numeric prefix across all dirs, and returns fmt.Sprintf("%03d-%s", highest+1, name) for unnumbered names. If name already has a valid numeric prefix, it is returned unchanged.
func RenumberSpecsAfterRemoval ¶ added in v0.78.0
RenumberSpecsAfterRemoval renames all .md files in dir whose numeric prefix is greater than removedNum, decrementing each by 1 to close the gap left by the removed spec.
Types ¶
type AutoCompleter ¶
AutoCompleter checks if all linked prompts are completed and marks the spec as completed.
func NewAutoCompleter ¶
func NewAutoCompleter( queueDir, completedDir, specsInboxDir, specsInProgressDir, specsCompletedDir string, currentDateTimeGetter libtime.CurrentDateTimeGetter, projectName string, n notifier.Notifier, pm PromptManager, ) AutoCompleter
NewAutoCompleter creates a new AutoCompleter.
type Frontmatter ¶
type Frontmatter struct {
Status string `yaml:"status"`
Tags []string `yaml:"tags,omitempty"`
Approved string `yaml:"approved,omitempty"`
Generating string `yaml:"generating,omitempty"`
Prompted string `yaml:"prompted,omitempty"`
Verifying string `yaml:"verifying,omitempty"`
Completed string `yaml:"completed,omitempty"`
Rejected string `yaml:"rejected,omitempty"`
RejectedReason string `yaml:"rejected_reason,omitempty"`
Branch string `yaml:"branch,omitempty"`
Issue string `yaml:"issue,omitempty"`
}
Frontmatter represents the YAML frontmatter in a spec file.
type Lister ¶
type Lister interface {
List(ctx context.Context) ([]*SpecFile, error)
Summary(ctx context.Context) (*Summary, error)
}
Lister lists spec files from a directory.
type PromptManager ¶ added in v0.135.18
PromptManager is the subset of prompt.Manager that the spec package uses.
type SpecFile ¶
type SpecFile struct {
Path string
Frontmatter Frontmatter
Name string // filename without extension
Body []byte
// contains filtered or unexported fields
}
SpecFile represents a loaded spec file with frontmatter and body.
func Load ¶
func Load( ctx context.Context, path string, currentDateTimeGetter libtime.CurrentDateTimeGetter, ) (*SpecFile, error)
Load reads a spec file from disk, parsing frontmatter and body.
func (*SpecFile) MarkCompleted ¶
func (s *SpecFile) MarkCompleted()
MarkCompleted sets the spec status to completed.
func (*SpecFile) MarkVerifying ¶ added in v0.18.5
func (s *SpecFile) MarkVerifying()
MarkVerifying sets the spec status to verifying.
func (*SpecFile) SetBranchIfEmpty ¶ added in v0.39.0
SetBranchIfEmpty sets the branch in the frontmatter only if it is not already set.
func (*SpecFile) SetStatus ¶
SetStatus sets the status field in the frontmatter and stamps the matching timestamp once.
func (*SpecFile) SpecNumber ¶ added in v0.23.1
SpecNumber returns the numeric prefix of the spec file name. Returns -1 if the name has no numeric prefix.
func (*SpecFile) StampRejected ¶ added in v0.133.0
StampRejected sets the rejected timestamp and reason, then marks status as rejected.
type SpecStatuses ¶ added in v0.132.2
type SpecStatuses []Status
SpecStatuses is a slice of Status values.
func (SpecStatuses) Contains ¶ added in v0.132.2
func (s SpecStatuses) Contains(status Status) bool
Contains returns true if the given status is in the collection.
type Status ¶
type Status string
Status represents the lifecycle state of a spec.
const ( // StatusIdea indicates a rough concept that needs refinement before it can be reviewed. StatusIdea Status = "idea" // StatusDraft indicates the spec is complete and ready for human review and approval. StatusDraft Status = "draft" // StatusApproved indicates the spec has been reviewed and approved for prompt generation. StatusApproved Status = "approved" // StatusGenerating indicates the spec is currently being processed to generate prompts. StatusGenerating Status = "generating" // StatusPrompted indicates prompts have been generated from the spec. StatusPrompted Status = "prompted" // StatusVerifying indicates all linked prompts completed, awaiting human verification of acceptance criteria. StatusVerifying Status = "verifying" // StatusCompleted indicates human verified all acceptance criteria are met. StatusCompleted Status = "completed" // StatusRejected indicates the spec was deliberately abandoned before execution. // This is a terminal state — rejected specs are moved to specs/rejected/ and never processed again. StatusRejected Status = "rejected" )
func (Status) CanTransitionTo ¶ added in v0.132.2
CanTransitionTo returns nil if transitioning from s to target is valid, or an error naming both states if the transition is not in the table.
func (Status) IsActive ¶ added in v0.132.2
IsActive returns true if the spec is in active processing (neither pre-execution nor terminal).
func (Status) IsPreExecution ¶ added in v0.132.2
IsPreExecution returns true if the spec has not yet entered active processing.
func (Status) IsRejectable ¶ added in v0.133.0
IsRejectable returns true if the spec may be rejected from its current state. Rejection is allowed from all pre-execution states and from prompted (when all linked prompts are themselves rejectable — that additional check is performed by the command).
func (Status) IsTerminal ¶ added in v0.132.2
IsTerminal returns true if the spec has reached a final, non-actionable state.
type Summary ¶
type Summary struct {
Idea int
Draft int
Approved int
Prompted int
Verifying int
Completed int
Rejected int
Total int
LinkedPromptsCompleted int `json:"linked_prompts_completed,omitempty"`
LinkedPromptsTotal int `json:"linked_prompts_total,omitempty"`
}
Summary holds counts of specs grouped by status.
Source Files