layers

package
v0.1.0-rc4 Latest Latest
Warning

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

Go to latest
Published: Apr 23, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func VendorBinary added in v0.0.4

func VendorBinary(ctx context.Context, client forge.Client, org, binaryPath string) error

VendorBinary uploads a pre-built fullsend binary to .fullsend/bin/fullsend. CI workflows detect this file and use it instead of downloading from GitHub releases, enabling development iteration without cutting a release.

Types

type AgentCredentials

type AgentCredentials struct {
	config.AgentEntry
	PEM      string
	ClientID string
}

AgentCredentials extends AgentEntry with app credentials.

type ConfigRepoLayer

type ConfigRepoLayer struct {
	// contains filtered or unexported fields
}

ConfigRepoLayer manages the .fullsend configuration repository. This is the foundational layer — it must be installed before any other layers that depend on the config repo existing.

func NewConfigRepoLayer

func NewConfigRepoLayer(org string, client forge.Client, cfg *config.OrgConfig, printer *ui.Printer, hasPrivate bool) *ConfigRepoLayer

NewConfigRepoLayer creates a new ConfigRepoLayer. Set hasPrivate to true if the org has any private repos — the config repo will be created as private to match the org's existing pattern. For orgs with only public repos (e.g., open source orgs), it is created as public to avoid surprises. This matters because the .fullsend repo may contain workflow files referenced by public repos.

func (*ConfigRepoLayer) Analyze

func (l *ConfigRepoLayer) Analyze(ctx context.Context) (*LayerReport, error)

Analyze checks whether the .fullsend repo and config.yaml exist and are valid.

func (*ConfigRepoLayer) Install

func (l *ConfigRepoLayer) Install(ctx context.Context) error

Install creates the .fullsend config repo (if it doesn't exist) and writes config.yaml into it.

Timing note: after CreateRepo with auto_init, the default branch may not be fully materialized yet. The Contents API call to write config.yaml can get transient 404s. The GitHub client's retry-with-backoff in do() handles this, but callers should be aware that the first file write to a newly created repo may take several seconds to succeed.

func (*ConfigRepoLayer) Name

func (l *ConfigRepoLayer) Name() string

func (*ConfigRepoLayer) RequiredScopes

func (l *ConfigRepoLayer) RequiredScopes(op Operation) []string

RequiredScopes returns the scopes needed for the given operation.

func (*ConfigRepoLayer) Uninstall

func (l *ConfigRepoLayer) Uninstall(ctx context.Context) error

Uninstall deletes the .fullsend config repo. Idempotent: if the repo is already gone, this is a no-op.

type DispatchTokenLayer

type DispatchTokenLayer struct {
	// contains filtered or unexported fields
}

DispatchTokenLayer manages the org-level dispatch token that enrolled repos use to trigger workflow_dispatch events on the .fullsend repo.

The dispatch token is a fine-grained PAT scoped to the .fullsend repo with actions:write and contents:read permissions. It is stored as an org-level Actions secret with visibility "selected", scoped to enrolled repos only. This way, enrolled repos can trigger dispatches but never access the App private keys (which are repo-level secrets on .fullsend).

func NewDispatchTokenLayer

func NewDispatchTokenLayer(org string, client forge.Client, token string, repoIDs []int64, printer *ui.Printer, promptFn PromptTokenFunc) *DispatchTokenLayer

NewDispatchTokenLayer creates a new DispatchTokenLayer. If promptFn is non-nil, it will be called during Install to obtain a dispatch token interactively when none was provided and the org secret doesn't already exist.

func (*DispatchTokenLayer) Analyze

func (l *DispatchTokenLayer) Analyze(ctx context.Context) (*LayerReport, error)

Analyze checks whether the dispatch token org secret exists.

func (*DispatchTokenLayer) Install

func (l *DispatchTokenLayer) Install(ctx context.Context) error

Install creates or updates the org-level dispatch token secret. If dispatchToken is non-empty, the secret is created with that value. If dispatchToken is empty, the method checks whether the secret already exists. If it does, the repo access list is updated. If it doesn't and promptFn is set, promptFn is called to obtain a token interactively. If it doesn't exist and promptFn is nil, an error is returned.

func (*DispatchTokenLayer) Name

func (l *DispatchTokenLayer) Name() string

Name returns the layer name.

func (*DispatchTokenLayer) RequiredScopes

func (l *DispatchTokenLayer) RequiredScopes(op Operation) []string

RequiredScopes returns the scopes needed for the given operation.

func (*DispatchTokenLayer) Uninstall

func (l *DispatchTokenLayer) Uninstall(ctx context.Context) error

Uninstall removes the org-level dispatch token secret if it exists.

type EnrollmentLayer

type EnrollmentLayer struct {
	// contains filtered or unexported fields
}

EnrollmentLayer monitors workflow-driven enrollment of target repos. Enrollment is performed by the repo-maintenance workflow in .fullsend, which creates PRs with shim workflows in response to config.yaml changes. This layer dispatches that workflow and reports the results.

func NewEnrollmentLayer

func NewEnrollmentLayer(org string, client forge.Client, enabledRepos, disabledRepos []string, printer *ui.Printer) *EnrollmentLayer

NewEnrollmentLayer creates a new EnrollmentLayer.

func (*EnrollmentLayer) Analyze

func (l *EnrollmentLayer) Analyze(ctx context.Context) (*LayerReport, error)

Analyze checks which enabled repos have the shim workflow installed and which disabled repos still have it.

func (*EnrollmentLayer) Install

func (l *EnrollmentLayer) Install(ctx context.Context) error

Install dispatches the repo-maintenance workflow to handle enrollment, waits for it to complete, and reports any enrollment PRs created.

func (*EnrollmentLayer) Name

func (l *EnrollmentLayer) Name() string

func (*EnrollmentLayer) RequiredScopes

func (l *EnrollmentLayer) RequiredScopes(op Operation) []string

RequiredScopes returns the scopes needed for the given operation.

func (*EnrollmentLayer) Uninstall

func (l *EnrollmentLayer) Uninstall(_ context.Context) error

Uninstall is a no-op. Individual repo cleanup is not automated — repos keep their shim workflows.

type InferenceLayer added in v0.0.3

type InferenceLayer struct {
	// contains filtered or unexported fields
}

InferenceLayer manages inference provider credentials in the .fullsend repo.

func NewInferenceLayer added in v0.0.3

func NewInferenceLayer(org string, client forge.Client, provider inference.Provider, printer *ui.Printer) *InferenceLayer

NewInferenceLayer creates a new InferenceLayer.

func (*InferenceLayer) Analyze added in v0.0.3

func (l *InferenceLayer) Analyze(ctx context.Context) (*LayerReport, error)

Analyze checks whether inference credentials exist in the .fullsend repo.

func (*InferenceLayer) Install added in v0.0.3

func (l *InferenceLayer) Install(ctx context.Context) error

Install provisions inference credentials and stores them as repo secrets. If all expected secrets already exist, provisioning is skipped to maintain idempotency (avoids accumulating SA keys against GCP's 10-key limit).

func (*InferenceLayer) Name added in v0.0.3

func (l *InferenceLayer) Name() string

Name returns the layer name.

func (*InferenceLayer) RequiredScopes added in v0.0.3

func (l *InferenceLayer) RequiredScopes(op Operation) []string

RequiredScopes returns the scopes needed for the given operation.

func (*InferenceLayer) Uninstall added in v0.0.3

func (l *InferenceLayer) Uninstall(_ context.Context) error

Uninstall is a no-op. Secrets are removed when the .fullsend repo is deleted.

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.

const (
	OpInstall Operation = iota
	OpUninstall
	OpAnalyze
)

func (Operation) String

func (o Operation) String() string

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
}

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.

type PromptTokenFunc added in v0.1.0

type PromptTokenFunc func(ctx context.Context) (string, error)

PromptTokenFunc is a callback that prompts the user for a dispatch token interactively. It is called during Install when no token was provided at construction time and the org secret doesn't already exist.

type SecretsLayer

type SecretsLayer struct {
	// contains filtered or unexported fields
}

SecretsLayer manages agent app secrets and variables in the .fullsend repo.

func NewSecretsLayer

func NewSecretsLayer(org string, client forge.Client, agents []AgentCredentials, printer *ui.Printer) *SecretsLayer

NewSecretsLayer creates a new SecretsLayer.

func (*SecretsLayer) Analyze

func (s *SecretsLayer) Analyze(ctx context.Context) (*LayerReport, error)

Analyze checks whether all expected agent secrets and variables exist in the .fullsend repo.

func (*SecretsLayer) Install

func (s *SecretsLayer) Install(ctx context.Context) error

Install stores agent app private keys as repo secrets and client IDs as repo variables in the .fullsend config repo.

func (*SecretsLayer) Name

func (s *SecretsLayer) Name() string

Name returns the layer name.

func (*SecretsLayer) RequiredScopes

func (s *SecretsLayer) RequiredScopes(op Operation) []string

RequiredScopes returns the scopes needed for the given operation.

func (*SecretsLayer) Uninstall

func (s *SecretsLayer) Uninstall(_ context.Context) error

Uninstall is a no-op. Secrets are removed when the .fullsend repo is deleted.

type Stack

type Stack struct {
	// contains filtered or unexported fields
}

Stack is an ordered collection of layers.

func NewStack

func NewStack(layers ...Layer) *Stack

NewStack creates a new Stack with the given layers in order.

func (*Stack) AnalyzeAll

func (s *Stack) AnalyzeAll(ctx context.Context) ([]*LayerReport, error)

AnalyzeAll runs Analyze on each layer and returns reports.

func (*Stack) CollectRequiredScopes

func (s *Stack) CollectRequiredScopes(op Operation) []string

CollectRequiredScopes returns the deduplicated set of scopes needed by all layers for the given operation.

func (*Stack) InstallAll

func (s *Stack) InstallAll(ctx context.Context) error

InstallAll runs Install on each layer in order. Stops on first error, returning the error and the name of the failed layer.

func (*Stack) Layers

func (s *Stack) Layers() []Layer

Layers returns the layers in order.

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 forge doesn't support scope introspection (e.g., fine-grained tokens, GitHub App tokens), Preflight returns a result with OK() == true and logs that scope checking was skipped. We can't validate what we can't see, so we let the operation proceed and fail at the point of use if scopes are actually missing.

func (*Stack) UninstallAll

func (s *Stack) UninstallAll(ctx context.Context) []error

UninstallAll runs Uninstall on each layer in reverse order. Collects all errors rather than stopping on first.

type VendorBinaryLayer added in v0.1.0

type VendorBinaryLayer struct {
	// contains filtered or unexported fields
}

VendorBinaryLayer manages the vendored development binary in .fullsend/bin/.

When enabled (--vendor-fullsend-binary flag), it calls a VendorFunc callback to cross-compile and upload the binary. When disabled (the default), it checks whether a vendored binary exists and deletes it to prevent a stale binary from shadowing released versions.

func NewVendorBinaryLayer added in v0.1.0

func NewVendorBinaryLayer(org string, client forge.Client, printer *ui.Printer, enabled bool, vendorFn VendorFunc) *VendorBinaryLayer

NewVendorBinaryLayer creates a new VendorBinaryLayer.

func (*VendorBinaryLayer) Analyze added in v0.1.0

func (l *VendorBinaryLayer) Analyze(ctx context.Context) (*LayerReport, error)

Analyze assesses the current state of the vendored binary.

func (*VendorBinaryLayer) Install added in v0.1.0

func (l *VendorBinaryLayer) Install(ctx context.Context) error

Install either vendors the binary (when enabled) or removes a stale one (when disabled).

func (*VendorBinaryLayer) Name added in v0.1.0

func (l *VendorBinaryLayer) Name() string

func (*VendorBinaryLayer) RequiredScopes added in v0.1.0

func (l *VendorBinaryLayer) RequiredScopes(op Operation) []string

RequiredScopes returns the scopes needed for the given operation.

func (*VendorBinaryLayer) Uninstall added in v0.1.0

func (l *VendorBinaryLayer) Uninstall(_ context.Context) error

Uninstall is a no-op. The vendored binary is removed when the config repo is deleted by the ConfigRepoLayer.

type VendorFunc added in v0.1.0

type VendorFunc func(ctx context.Context, client forge.Client, printer *ui.Printer, org string) error

VendorFunc is a callback that cross-compiles and uploads a vendored binary.

type WorkflowsLayer

type WorkflowsLayer struct {
	// contains filtered or unexported fields
}

WorkflowsLayer manages workflow files and CODEOWNERS in the .fullsend config repo. It writes the reusable agent dispatch workflow, the repo onboarding workflow, and a CODEOWNERS file that grants the installing user ownership of all config-repo contents.

func NewWorkflowsLayer

func NewWorkflowsLayer(org string, client forge.Client, printer *ui.Printer, user string) *WorkflowsLayer

NewWorkflowsLayer creates a new WorkflowsLayer. user is the authenticated user who will own CODEOWNERS entries.

func (*WorkflowsLayer) Analyze

func (l *WorkflowsLayer) Analyze(ctx context.Context) (*LayerReport, error)

Analyze checks which managed files exist in the config repo.

func (*WorkflowsLayer) Install

func (l *WorkflowsLayer) Install(ctx context.Context) error

Install writes the workflow files and CODEOWNERS to the .fullsend repo. CODEOWNERS failure is treated as a warning, not a fatal error.

Note: writing multiple files sequentially via the Contents API can cause transient 404s because each file write creates a new commit and the branch ref is updated asynchronously. The GitHub client's retry logic handles this. CODEOWNERS is written last and its failure is non-fatal because some orgs restrict CODEOWNERS writes to specific teams.

func (*WorkflowsLayer) Name

func (l *WorkflowsLayer) Name() string

func (*WorkflowsLayer) RequiredScopes

func (l *WorkflowsLayer) RequiredScopes(op Operation) []string

RequiredScopes returns the scopes needed for the given operation.

func (*WorkflowsLayer) Uninstall

func (l *WorkflowsLayer) Uninstall(_ context.Context) error

Uninstall is a no-op. Workflow files are removed when the config repo is deleted by the ConfigRepoLayer.

Jump to

Keyboard shortcuts

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