publish

package
v0.20.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package publish is `anfra publish`: a local repo's files published to its org, as PUBLISH.md (anfra-cloud) describes. The command wires it to the terminal (Env); its messages name the command's flags.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Confirm

func Confirm(ask Prompt, question string) (yes, ok bool)

Confirm asks a yes-or-no question, no the default.

func Run

func Run(ctx context.Context, dir string, o Options, env Env) (any, error)

Run publishes the repo at dir: PUBLISH.md's flow, from file selection to the server's answer. With o.Check it checks instead: a CheckResult; else a Result. Progress and questions go to env.ErrOut; warnings to env.Warn.

Types

type CheckResult added in v0.17.0

type CheckResult struct {
	Message string   `json:"message" doc:"the outcome, in a sentence"`
	Org     *OrgRef  `json:"org" doc:"where it would be published. Null when no org is configured."`
	Files   []string `json:"files" doc:"the files it would send" pretty:",tree"`
	Hints   []string `json:"hints,omitempty" doc:"what to do next, if any"`
}

CheckResult is `publish check`'s result: what would be published, and where (docs/designs/commands-and-api.md#cli-output).

type Env

type Env struct {
	// ErrOut is where progress and questions go, for a person at a terminal.
	ErrOut io.Writer
	// Warn says a problem that doesn't stop the publish, by its code; nil says
	// nothing.
	Warn func(code, message string)
	// OrgName is an org's name, as its login knows it; nil, or "": unknown.
	OrgName func(cloudapi.Org) string
	Ask     Prompt
	// Validate validates the repo here, before anything is sent: an error
	// refusing the publish, carrying what fails. Always, and again on the
	// server, whose verdict on exactly the published files is the one that
	// publishes (PUBLISH.md §Decisions).
	Validate func(context.Context) error
	// Credential checks the selected login before destination configuration is
	// saved, returning an authorizer that resolves credentials for every request.
	Credential func(context.Context, cloudapi.Org) (func(*http.Request) error, error)
	// SelectOrg explicitly selects a first destination; nil means no interactive terminal.
	SelectOrg func(context.Context) (cloudapi.Org, error)
	// RecoverOrg offers interactive recovery after credential loading fails.
	// It must return the original error when recovery does not apply, and confirm
	// any destination change before returning a different organization.
	RecoverOrg func(context.Context, cloudapi.Org, error) (cloudapi.Org, error)
	// UserAgent names the CLI and its version, for the server.
	UserAgent string
	// MotherDuck is the person's MotherDuck account, to copy a DuckDB data source
	// to; nil offers no copy.
	MotherDuck MotherDuck
	// Input asks for a line of text, as Ask asks a question; nil with no
	// terminal.
	Input Input
	// Logger is the repo's log, for what the publish absorbed that no one
	// sees, such as a retry; nil records nothing.
	Logger *slog.Logger
}

Env is what a publish needs from the command around it.

type FileChange added in v0.20.0

type FileChange struct {
	Path   string `json:"path" doc:"the file's path in the repo"`
	Change string `` /* 216-byte string literal not displayed */
}

FileChange is a file a pull changed, or one a pull or a publish would change.

type Input added in v0.13.0

type Input func(question string) (answer string, ok bool)

Input asks for a line of text, and returns it trimmed: "" when nothing was typed, or the question was interrupted; ok is false when nobody can answer it.

type MotherDuck added in v0.13.0

type MotherDuck interface {
	Find(ctx context.Context) (version string, ok bool)
	Status(ctx context.Context) (motherduck.Status, error)
	Login(ctx context.Context) error
	Session(ctx context.Context) (token string, databases []string, err error)
	DatabaseExists(ctx context.Context, name string) (bool, error)
	CreateDatabaseFrom(ctx context.Context, name, path string) error
	CreateReadToken(ctx context.Context, session, username, name, description string) (motherduck.Token, error)
	RevokeToken(ctx context.Context, session, username, id string) error
}

MotherDuck is a person's MotherDuck account, as copying a DuckDB file there needs it (motherduck.Account). Nil offers no copy: without a terminal, nobody is there to sign in.

type Options

type Options struct {
	// Message is what the publish is, for the org's history of the repo; "" is
	// HEAD's commit, in a git repo.
	Message string
	// SetOrg is an org's address to record as the repo's, and publish to.
	SetOrg string
	// Check is publish check: the preflight, which goes as far as a publish
	// would before its first change, then says what it would do. Today, the
	// part done here, offline, without authentication or config writes: the
	// files, and where they'd go.
	Check bool
	// Pull merges what the org has that this folder hasn't seen before
	// publishing, instead of refusing; it stops on conflicts.
	Pull bool
	// Yes did nothing since publish stopped asking before replacing a
	// version; kept for a release, with a warning.
	Yes bool
	// CreateDataSources adds the data sources the repo uses and the org lacks
	// without asking.
	CreateDataSources bool
}

Options are a publish's choices: the command's flags.

type OrgRef added in v0.17.0

type OrgRef struct {
	URL  string `json:"url" doc:"the org's address"`
	Name string `json:"name,omitempty" doc:"the org's name, from its saved login. Absent when it isn't known."`
}

OrgRef is an org a publish goes to: its address, and its name when the login knows it.

type Prompt

type Prompt func(question string, choices ...string) (choice int, ok bool)

Prompt asks a question with choices, the last one the default (the safe answer), and returns the choice's index; ok is false when nobody can answer it (not a terminal).

type PullConflict added in v0.20.0

type PullConflict struct {
	Paths   []string `` /* 161-byte string literal not displayed */
	Message string   `json:"message" doc:"what happened, naming its files"`
}

PullConflict is one conflict: the paths it covers, and what happened.

type PullOptions added in v0.20.0

type PullOptions struct {
	// SetOrg is an org's address to record as the repo's, and pull from.
	SetOrg string
	// Take is "org" or "local": resolve the conflicts on Paths by keeping that
	// side's version of the whole files.
	Take  string
	Paths []string
	// Abort undoes the last pull while it isn't finished.
	Abort bool
}

PullOptions are a pull's choices: the command's flags. At most one of Take and Abort.

type PullResult added in v0.20.0

type PullResult struct {
	Message      string                    `json:"message" doc:"the outcome, in a sentence"`
	Org          *OrgRef                   `json:"org,omitempty" doc:"the org pulled from"`
	Revision     string                    `json:"revision,omitempty" doc:"the org's revision this pull merged into the folder"`
	PublishedBy  string                    `json:"published_by,omitempty" doc:"who published that revision. Absent for the org's starting files."`
	PublishedAt  *time.Time                `json:"published_at,omitempty" doc:"when that revision was published" pretty:",moment"`
	Base         string                    `json:"base,omitempty" doc:"the org's revision this folder matched before the pull. Absent when anfra had no record of one."`
	Changes      []FileChange              `json:"changes,omitempty" doc:"the files the pull wrote or deleted, other than those with conflicts"`
	Conflicts    map[string][]PullConflict `` /* 192-byte string literal not displayed */
	HowToResolve map[string]string         `json:"how_to_resolve,omitempty" doc:"how to resolve each kind of conflict left, by kind"`
	Taken        []TakenSide               `json:"taken,omitempty" doc:"with --take: the conflicts resolved, and the side kept"`
	Restored     []string                  `json:"restored,omitempty" doc:"with --abort: the files put back as they were before the pull"`
	Hints        []string                  `json:"hints,omitempty" doc:"what to do next, if any"`
}

PullResult is a pull's result: what it merged into the folder, and what's left to resolve. --take and --abort answer it too, with what they did.

func Pull added in v0.20.0

func Pull(ctx context.Context, dir string, o PullOptions, env Env) (PullResult, error)

Pull merges the org's published files into the folder at dir, or, with o.Take or o.Abort, resolves or undoes the last pull (docs/designs/publish.md).

type Pulled added in v0.20.0

type Pulled struct {
	Revision    string       `json:"revision" doc:"the org's revision pulled"`
	PublishedBy string       `json:"published_by,omitempty" doc:"who published it. Absent for the org's starting files."`
	PublishedAt *time.Time   `json:"published_at,omitempty" doc:"when it was published" pretty:",moment"`
	Changes     []FileChange `json:"changes" doc:"the files the pull wrote or deleted"`
}

Pulled is what publish --pull merged into the folder before publishing.

type Result added in v0.17.0

type Result struct {
	Message            string             `json:"message" doc:"the outcome, in a sentence"`
	Org                OrgRef             `json:"org" doc:"where it was published"`
	Revision           string             `json:"revision" doc:"the revision published"`
	Changed            bool               `json:"changed" doc:"false when these files were what the org had published"`
	Replaced           *cloudapi.Replaced `json:"replaced,omitempty" doc:"the revision it replaced"`
	Files              int                `json:"files" doc:"how many files it published"`
	DataSourcesCreated []string           `json:"data_sources_created" doc:"the data sources it added to the org"`
	Pulled             *Pulled            `` /* 126-byte string literal not displayed */
	Hints              []string           `json:"hints,omitempty" doc:"what to do next, if any"`
}

Result is a publish's result: the revision it published, and what came of it.

type StatusResult added in v0.20.0

type StatusResult struct {
	Message     string       `json:"message" doc:"the outcome, in a sentence"`
	Org         *OrgRef      `json:"org,omitempty" doc:"the repo's org. Absent when none is configured."`
	Revision    string       `json:"revision,omitempty" doc:"the org's published revision"`
	PublishedBy string       `json:"published_by,omitempty" doc:"who published that revision. Absent for the org's starting files."`
	PublishedAt *time.Time   `json:"published_at,omitempty" doc:"when that revision was published" pretty:",moment"`
	Base        string       `json:"base,omitempty" doc:"the org's revision this folder last pulled or published. Absent when anfra has no record of one."`
	Incoming    []FileChange `json:"incoming,omitempty" doc:"what the org changed since the base: what a pull would change in this folder"`
	Unpublished []FileChange `` /* 128-byte string literal not displayed */
	// PullInterrupted is a pull stopped partway through writing files: the
	// folder is half pulled, so it isn't compared.
	PullInterrupted bool                      `` /* 146-byte string literal not displayed */
	Conflicts       map[string][]PullConflict `json:"conflicts,omitempty" doc:"the last pull's conflicts not resolved yet, by kind"`
	HowToResolve    map[string]string         `json:"how_to_resolve,omitempty" doc:"how to resolve each kind of conflict left, by kind"`
	Hints           []string                  `json:"hints,omitempty" doc:"what to do next, if any"`
}

StatusResult is `publish status`'s result: how this folder stands against what its org has published.

func Status added in v0.20.0

func Status(ctx context.Context, dir string, env Env) (StatusResult, error)

Status says how the folder at dir stands against its org's published revision: what a pull would bring in, what a publish would send, and the last pull's conflicts. It changes nothing, here or on the org.

type TakenSide added in v0.20.0

type TakenSide struct {
	Paths []string `json:"paths" doc:"the files the conflict covers"`
	Kept  string   `json:"kept" doc:"whose version was kept. \"org\" or \"local\"."`
}

TakenSide is a conflict resolved by keeping one side's version.

Directories

Path Synopsis
Package syncstate keeps a repo folder's sync state with its orgs: the org revision its files last matched (the base), and a pull that isn't finished (the pending record).
Package syncstate keeps a repo folder's sync state with its orgs: the org revision its files last matched (the base), and a pull that isn't finished (the pending record).
Package workdir is a repo folder as publish and pull see it: the files a publish carries, hashed into a tree, and the safe writing of a merge into them, with a backup to undo it.
Package workdir is a repo folder as publish and pull see it: the files a publish carries, hashed into a tree, and the safe writing of a merge into them, with a backup to undo it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL