Documentation
¶
Index ¶
- Constants
- func CommitFilesViaPR(ctx context.Context, client forge.Client, printer *ui.Printer, ...) (bool, error)
- func CommitScaffoldFiles(ctx context.Context, client forge.Client, printer *ui.Printer, ...) (bool, error)
- func DeleteVendoredPaths(ctx context.Context, client forge.Client, owner, repo string, paths []string) (int, error)
- func RemoveStaleBinaryCommitMessage(destPath string) string
- func RemoveStaleContentCommitMessage(path string) string
- func RemoveStaleVendoredAssets(ctx context.Context, client forge.Client, printer *ui.Printer, ...) error
- func RemoveStaleVendoredAssetsCommitMessage(paths []string) string
- func VendorBinary(ctx context.Context, client forge.Client, ...) error
- func VendorCommitMessage(source binary.Source, version, destPath string, sizeBytes int64) string
- func VendorContentCommitMessage(version, pathPrefix string, fileCount int) string
- type AgentCredentials
- type Layer
- type LayerReport
- type LayerStatus
- type Operation
- type PreflightResult
- type SkipReason
- type Stack
- func (s *Stack) AnalyzeAll(ctx context.Context) ([]*LayerReport, error)
- func (s *Stack) CollectRequiredScopes(op Operation) []string
- func (s *Stack) InstallAll(ctx context.Context) error
- func (s *Stack) Layers() []Layer
- func (s *Stack) Preflight(ctx context.Context, op Operation, client forge.Client) (*PreflightResult, error)
- func (s *Stack) UninstallAll(ctx context.Context) []error
Constants ¶
const (
// VendoredBinaryPathPerRepo is the upload path inside a per-repo target repo.
VendoredBinaryPathPerRepo = ".fullsend/bin/fullsend"
)
Variables ¶
This section is empty.
Functions ¶
func CommitFilesViaPR ¶ added in v0.24.0
func CommitFilesViaPR(ctx context.Context, client forge.Client, printer *ui.Printer, owner, repo, defaultBranch, branch, commitMsg, prTitle, prBody string, files []forge.TreeFile) (bool, error)
CommitFilesViaPR delivers files via a pull request on the given branch. Uses a fixed branch name so re-runs update the same PR.
func CommitScaffoldFiles ¶ added in v0.18.0
func CommitScaffoldFiles(ctx context.Context, client forge.Client, printer *ui.Printer, owner, repo, defaultBranch string, meta repos.ScaffoldPRMetadata, files []forge.TreeFile, direct bool, in io.Reader) (bool, error)
CommitScaffoldFiles delivers scaffold files to a repository. When direct is false (the default), files are committed to a feature branch and delivered via PR. When direct is true, files are pushed directly to the default branch, falling back to a PR if branch protection blocks the push.
The meta parameter supplies the commit message, PR title/body, and branch name. Pass an empty Branch to use the default ("fullsend/scaffold-install").
The in parameter enables interactive prompts (e.g., fork-vs-upstream choice). Pass os.Stdin for interactive CLI callers; pass nil for non-interactive callers (sync-scaffold), which default to forking without prompting. GitHub App installation tokens never fork: they deliver the PR from a branch in the target repository.
The returned bool is true when files were committed directly to the default branch (false for PR-based delivery, idempotent no-ops, or unchanged content).
func DeleteVendoredPaths ¶ added in v0.19.0
func DeleteVendoredPaths(ctx context.Context, client forge.Client, owner, repo string, paths []string) (int, error)
DeleteVendoredPaths removes stale vendored paths in a single commit when possible.
func RemoveStaleBinaryCommitMessage ¶ added in v0.17.0
RemoveStaleBinaryCommitMessage returns title + body for stale binary deletion.
func RemoveStaleContentCommitMessage ¶ added in v0.19.0
RemoveStaleContentCommitMessage returns title + body for stale content deletion.
func RemoveStaleVendoredAssets ¶ added in v0.19.0
func RemoveStaleVendoredAssets(ctx context.Context, client forge.Client, printer *ui.Printer, owner, repo, workflowPrefix, binaryPath string) error
RemoveStaleVendoredAssets deletes vendored assets when --vendor is not set. It skips work when neither the vendor manifest nor vendored binary exists.
func RemoveStaleVendoredAssetsCommitMessage ¶ added in v0.19.0
RemoveStaleVendoredAssetsCommitMessage returns title + body for batch stale deletion.
func VendorBinary ¶ added in v0.0.4
func VendorBinary(ctx context.Context, client forge.Client, owner, repo, destPath, binaryPath, commitMsg string) error
VendorBinary uploads a pre-built fullsend binary to the given destPath. CI workflows detect this file and use it instead of downloading from GitHub releases, enabling development iteration without cutting a release.
func VendorCommitMessage ¶ added in v0.17.0
VendorCommitMessage returns a GitHub commit message (title + body) for upload.
func VendorContentCommitMessage ¶ added in v0.19.0
VendorContentCommitMessage returns a commit message for vendored content upload.
Types ¶
type AgentCredentials ¶
type AgentCredentials struct {
Role string
Name string
Slug string
PEM string
ClientID string
AppID int
}
AgentCredentials holds agent identity (role, name, slug) and app credentials for layer operations.
type Layer ¶
type Layer interface {
// Name returns a human-readable name for this layer.
Name() string
// RequiredScopes returns the OAuth scopes this layer needs for the
// given operation. Scopes are GitHub-flavored strings like "repo",
// "delete_repo", "workflow". Used by Preflight to fail early when
// the token is missing required scopes.
RequiredScopes(op Operation) []string
// Install creates or configures this layer's concern.
Install(ctx context.Context) error
// Uninstall tears down this layer's concern.
Uninstall(ctx context.Context) error
// Analyze assesses the current state and reports what would change.
Analyze(ctx context.Context) (*LayerReport, error)
}
Layer is the interface each installation concern implements. Layers are processed in order for install, reverse order for uninstall.
type LayerReport ¶
type LayerReport struct {
Name string
Status LayerStatus
Details []string // human-readable detail lines
WouldInstall []string // what install would create
WouldFix []string // what install would fix (for degraded state)
}
LayerReport is the result of analyzing a single layer.
type LayerStatus ¶
type LayerStatus int
LayerStatus represents the current state of a layer.
const ( StatusNotInstalled LayerStatus = iota StatusInstalled StatusDegraded // partially installed or misconfigured StatusUnknown // cannot determine )
func (LayerStatus) String ¶
func (s LayerStatus) String() string
String returns a human-readable description of the status.
type Operation ¶
type Operation int
Operation identifies which action is being performed on a layer.
type PreflightResult ¶
type PreflightResult struct {
// Required is the set of scopes the operation needs.
Required []string
// Granted is the set of scopes the token actually has.
Granted []string
// Missing is the set of scopes needed but not granted.
Missing []string
// Skipped is true when scope introspection was unavailable
// (e.g., fine-grained tokens that don't report scopes).
Skipped bool
// SkippedReason indicates why the preflight was skipped.
SkippedReason SkipReason
}
PreflightResult describes what a preflight check found.
func (*PreflightResult) Error ¶
func (r *PreflightResult) Error() string
Error returns a human-readable error describing missing scopes and how to fix the problem.
func (*PreflightResult) OK ¶
func (r *PreflightResult) OK() bool
OK returns true if no scopes are missing.
func (*PreflightResult) SkipGuidance ¶ added in v0.30.0
func (r *PreflightResult) SkipGuidance() string
SkipGuidance returns a human-readable message listing the scopes that could not be verified and their fine-grained equivalents.
type SkipReason ¶ added in v0.30.0
type SkipReason string
SkipReason describes why a preflight check was skipped.
const ( // SkipNone means the preflight was not skipped. SkipNone SkipReason = "" // SkipInstallationToken means the token is a GitHub App installation token. SkipInstallationToken SkipReason = "installation" // SkipFineGrained means the token is a fine-grained PAT whose // permissions cannot be introspected. SkipFineGrained SkipReason = "fine-grained" )
type Stack ¶
type Stack struct {
// contains filtered or unexported fields
}
Stack is an ordered collection of layers.
func (*Stack) AnalyzeAll ¶
func (s *Stack) AnalyzeAll(ctx context.Context) ([]*LayerReport, error)
AnalyzeAll runs Analyze on each layer and returns reports.
func (*Stack) CollectRequiredScopes ¶
CollectRequiredScopes returns the deduplicated set of scopes needed by all layers for the given operation.
func (*Stack) InstallAll ¶
InstallAll runs Install on each layer in order. Stops on first error, returning the error and the name of the failed layer.
func (*Stack) Preflight ¶
func (s *Stack) Preflight(ctx context.Context, op Operation, client forge.Client) (*PreflightResult, error)
Preflight checks that the forge client's token has all the scopes required by the stack's layers for the given operation. It returns a PreflightResult describing what was found.
If the token is a GitHub App installation token, or scope introspection is unavailable (e.g., fine-grained PATs), Preflight returns a result with OK() == true and Skipped set. OAuth scope preflight does not apply to installation tokens; for tokens we cannot introspect we let the operation proceed and fail at the point of use if permissions are actually missing.