plans

type ConflictError ¶

type ConflictError struct {
	Name     string
	Expected int
	Current  int
}

ConflictError reports a mutation rejected because the caller's expected version no longer matches the plan's current one. Current carries the version the plan is actually at, so a frontend can offer "re-read and retry" or a deliberate force. Expected 0 identifies a failed create: the plan already exists.

func (e *ConflictError) Error() string

type CorruptError ¶

type CorruptError struct {
	Scope Scope
	Name  string
	Err   error
}

CorruptError reports a plan that exists but cannot be read or decoded, so a caller never mistakes a damaged plan for a missing one and recreates it.

func (e *CorruptError) Error() string

func (e *CorruptError) Unwrap() error

type CreateRequest ¶

type CreateRequest struct {
	Ref     Ref
	Content string
	Title   string
	Author  string
	Status  string
}

CreateRequest creates a new shared plan. Create is create-only: the write is guarded by expected version 0, so it fails with a *ConflictError instead of silently overwriting a plan that already exists.

type DeleteRequest ¶

type DeleteRequest struct {
	Ref             Ref
	ExpectedVersion *int
}

DeleteRequest removes a shared plan. ExpectedVersion follows the same rules as in UpdateRequest: nil deletes unconditionally.

type ExportRequest ¶

type ExportRequest struct {
	Ref   Ref
	Path  string
	Force bool
}

ExportRequest writes a plan's content to a file on disk.

Force replaces an existing regular file at Path. Without it, Export refuses any existing destination with a *ValidationError and leaves it untouched.

type ExportResult ¶

type ExportResult struct {
	Scope        Scope  `json:"scope"`
	Name         string `json:"name"`
	Path         string `json:"path"`
	Version      *int   `json:"version,omitempty"`
	BytesWritten int    `json:"bytes_written"`
}

ExportResult reports a completed export. Version is the exported plan's version.

type ListResult ¶

type ListResult struct {
	Plans    []Plan   `json:"plans"`
	Warnings []string `json:"warnings,omitempty"`
}

ListResult is the outcome of List. Warnings carries plans that exist but could not be read, so a caller can tell "no plans" apart from "some plans failed to load".

type NotFoundError ¶

type NotFoundError struct {
	Scope Scope
	Name  string
}

NotFoundError reports that the addressed plan does not exist in its scope.

func (e *NotFoundError) Error() string

type Plan ¶

type Plan struct {
	// Scope tells which plan system the plan lives in.
	Scope Scope `json:"scope"`
	// Name is the validated canonical plan name.
	Name string `json:"name"`
	// Title, Author, and Status are plan metadata. Status is a free-form
	// lifecycle label with no fixed vocabulary.
	Title  string `json:"title,omitempty"`
	Author string `json:"author,omitempty"`
	Status string `json:"status,omitempty"`
	// Content is the plan body. List returns metadata only, so Content is
	// empty there; Get populates it.
	Content string `json:"content,omitempty"`
	// Version is the optimistic-lock revision of the plan.
	Version *int `json:"version,omitempty"`
	// UpdatedAt is the stored time of the last write. Zero when unknown (and
	// then omitted from JSON via omitzero, which consults time.Time.IsZero;
	// omitempty would keep the zero struct).
	UpdatedAt time.Time `json:"updated_at,omitzero"`
}

Plan is the host-facing view of a plan.

The JSON tags are a stable, snake_case wire contract for host consumers (e.g. the plans CLI --json output). It is deliberately independent of the agent tool JSON of pkg/tools/builtin/plan, which keeps its historical camelCase fields (updatedAt, bytesWritten) for backward compatibility.

type Ref ¶

type Ref struct {
	Scope Scope
	Name  string
}

Ref addresses a plan by name within a scope.

func SharedRef(name string) Ref

type Scope ¶

type Scope string

Scope identifies which plan system a plan belongs to. It remains part of the wire contract for forward compatibility even though only one scope exists today.

const ScopeShared Scope = "shared"

type Service ¶

type Service interface {
	// List returns plan metadata (Content is left empty) for every shared
	// plan, sorted by name.
	List(ctx context.Context) (ListResult, error)
	// Get returns the full plan, including content. A missing plan is a
	// *NotFoundError.
	Get(ctx context.Context, ref Ref) (Plan, error)
	// Create adds a new shared plan; a name that already exists fails with a
	// *ConflictError carrying the current version.
	Create(ctx context.Context, req CreateRequest) (Plan, error)
	// Update replaces the content (and optionally metadata) of an existing
	// shared plan, honouring req.ExpectedVersion.
	Update(ctx context.Context, req UpdateRequest) (Plan, error)
	// SetStatus sets the free-form status of an existing shared plan,
	// honouring req.ExpectedVersion.
	SetStatus(ctx context.Context, req SetStatusRequest) (Plan, error)
	// Delete removes a shared plan, honouring req.ExpectedVersion. Deleting a
	// missing plan is a *NotFoundError.
	Delete(ctx context.Context, req DeleteRequest) error
	// Export writes a plan's content to req.Path, creating parent directories
	// as needed. An existing destination is refused with a *ValidationError
	// and preserved unless req.Force is set, which replaces an existing
	// regular file atomically; directories and non-regular files are always
	// refused.
	Export(ctx context.Context, req ExportRequest) (ExportResult, error)
}

Service is the host-facing contract for managing plans. Failures are reported as the typed errors of this package so frontends never classify by error text.

func NewService(storage plan.Storage) Service

type SetStatusRequest ¶

type SetStatusRequest struct {
	Ref             Ref
	Status          string
	ExpectedVersion *int
}

SetStatusRequest sets the free-form status of an existing shared plan without touching its body. ExpectedVersion follows the same rules as in UpdateRequest.

type StorageError ¶

type StorageError struct {
	Scope Scope
	Op    string
	Err   error
}

StorageError reports a backend failure (I/O, permissions, ...) that is neither a missing nor a corrupt plan.

func (e *StorageError) Error() string

func (e *StorageError) Unwrap() error

type UpdateRequest ¶

type UpdateRequest struct {
	Ref             Ref
	Content         string
	Title           *string
	Author          *string
	Status          *string
	ExpectedVersion *int
}

UpdateRequest replaces the content of an existing shared plan. Nil metadata pointers preserve the previous values; explicit values (including "") overwrite them.

ExpectedVersion is the version the caller last read: the write is rejected with a *ConflictError when it no longer matches. An explicit nil means unconditional replacement and must only be sent when the user deliberately chose to force.

type ValidationError ¶

type ValidationError struct {
	Message string
}

ValidationError reports invalid caller input: a malformed plan name, an unknown scope, empty or oversized content, or an empty status.

func (e *ValidationError) Error() string