repos

package
v0.38.0 Latest Latest
Warning

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

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

Documentation

Overview

Package repos provides reusable per-repo installation logic for fullsend. It decouples the core install flow (scaffold commit, variable/secret writes) from CLI concerns (prompts, spinners, flag parsing) so that both the interactive CLI and future bulk-install commands can share the same logic.

Package repos implements parsing, validation, and resolution of the repos.yaml declarative manifest that drives multi-repo management (ADR 0057).

Index

Constants

View Source
const (
	ForgeGitHub = "github"
	ForgeGitLab = "gitlab"
)

Forge type constants used in the manifest's platform sections.

View Source
const (
	MintModePublic  = "public"
	MintModePrivate = "private"

	DefaultPublicMintURL = "https://mint.fullsend.sh"
)

Mint mode constants control the default mint URL for GitHub repos.

View Source
const (

	// DefaultScaffoldBranch is the branch name for fresh installations.
	DefaultScaffoldBranch = "fullsend/scaffold-install"

	// ScaffoldBumpBranchPrefix is the branch prefix for version upgrades.
	ScaffoldBumpBranchPrefix = "fullsend/bump-"
)
View Source
const DefaultGitHubURL = "https://github.com"

DefaultGitHubURL is the default forge URL for GitHub.com.

View Source
const NoneSentinel = "none"

NoneSentinel is the YAML value that explicitly clears an inherited field in the override cascade. Use "fullsend_ref: none" in YAML to stop the per-repo → platform-default → built-in-default chain.

Variables

View Source
var ValidDefaultKeys = []string{
	"defaults.allowed_remote_resources",
	"defaults.runtime",
	"github.url",
	"github.mint_url",
	"github.mint_mode",
	"github.fullsend_ref",
	"gitlab.url",
	"gitlab.fullsend_ref",
	"gitlab.runner_tags",
}

ValidDefaultKeys lists the manifest keys that can be set via `repos set-default`. Order matches the help text.

View Source
var WIFProviderPattern = regexp.MustCompile(
	`^projects/\d+/locations/global/workloadIdentityPools/[a-z][a-z0-9-]{2,30}[a-z0-9]/providers/[a-z][a-z0-9-]{2,30}[a-z0-9]$`,
)

WIFProviderPattern validates the full WIF provider resource name format required by google-github-actions/auth@v3. GCP pool/provider IDs: 4-32 chars, [a-z0-9-], start with letter, no trailing hyphen.

Functions

func AddToManifest added in v0.32.0

func AddToManifest(ctx context.Context, cfg ManifestEditConfig, forgeName string, entries []RepoEntry, clients ForgeClientFactory, progress ProgressFunc) (*ManifestAddResult, *Manifest, error)

AddToManifest appends repo entries to the appropriate platform section, skipping duplicates. The forgeName parameter determines which platform section receives the entries. When client is non-nil, each non-glob repo is probed for existing installation state and per-repo overrides are populated where the discovered values differ from platform defaults. Returns the result and the modified manifest. The manifest is written to disk only when ManifestPath is set and DryRun is false.

func AllMatch added in v0.37.0

func AllMatch(components []ComponentStatus) bool

AllMatch returns true when every ComponentStatus has Match == true.

func BuildScaffoldFiles

func BuildScaffoldFiles(cfg InstallConfig) ([]forge.TreeFile, error)

BuildScaffoldFiles generates the scaffold tree files for a per-repo install. Exported so the CLI dry-run path can display the file list without running the full install.

func DriftFieldName added in v0.37.0

func DriftFieldName(componentName string) string

DriftFieldName returns the component name without its category prefix, suitable for use as a Drift.Field value. "var:FULLSEND_MINT_URL" becomes "FULLSEND_MINT_URL"; "workflow" stays "workflow".

func ExpectedScaffoldContent added in v0.38.0

func ExpectedScaffoldContent(ctx context.Context, resolved ResolvedConfig, dcfg DriftConfig, refResolver *RefResolver) ([]forge.TreeFile, error)

ExpectedScaffoldContent renders the scaffold files that a fresh install would produce for the given resolved config. The status path uses this to compare against installed files for content drift detection — when the rendered template differs from the installed file, the repo's scaffold is stale even if the ref string matches.

When fullsend_ref pins a version that differs from the running binary, the refResolver fetches remote scaffold templates from the pinned ref so the baseline matches the pinned version, not the embedded templates. This mirrors the converge path's FetchRemoteScaffold logic. Both paths share driftInstallConfig as the underlying input builder and BuildScaffoldFiles as the renderer.

Returns (nil, nil) when FullsendRef is empty — there is no expected ref to compare against.

func FetchRemoteScaffold added in v0.37.0

func FetchRemoteScaffold(ctx context.Context, ghClient forge.Client,
	manifestRef, resolvedSHA, forgeName string,
	runnerTags []string,
) (scaffold.InstallFiles, error)

FetchRemoteScaffold fetches scaffold templates from fullsend-ai/fullsend at the given ref and renders them for the specified forge. This is used when fullsend_ref pins to a version that differs from the running binary, so embedded templates would be incorrect.

Template paths (scaffoldGitHubShimPath, scaffoldGitLabPaths) are pinned to the current binary's layout. If the remote ref reorganises these paths, the fetch fails gracefully and the caller falls back to embedded templates — cross-version compatibility is best-effort.

func HasFullsendEntries added in v0.38.0

func HasFullsendEntries(existing []byte) bool

HasFullsendEntries reports whether existing .gitlab-ci.yml content already contains all fullsend CI entries. It performs semantic drift detection by checking:

  1. include: contains the fullsend-pipeline.yml entry
  2. If stages: exists, it contains dispatch, poll, agent (if no stages: key, the included pipeline provides them)
  3. If workflow: exists, it must have a rules: sequence containing fullsend's three if: conditions. If workflow: exists without rules:, that is drift — MergeGitLabCI would add them. (if no workflow: block at all, fullsend's jobs self-filter)

Used by the installer to skip unnecessary .gitlab-ci.yml writes when all entries are already present, avoiding YAML formatting churn.

func IsNumeric added in v0.34.0

func IsNumeric(s string) bool

IsNumeric reports whether s contains only ASCII digits.

func IsValidForge added in v0.33.0

func IsValidForge(name string) bool

IsValidForge reports whether the given forge name is supported.

func IsValidGCPProjectID added in v0.34.0

func IsValidGCPProjectID(s string) bool

IsValidGCPProjectID checks that s matches the GCP project ID format: 6-30 characters, lowercase letters, digits, and hyphens, starting with a letter.

func IsValidGCPRegion added in v0.34.0

func IsValidGCPRegion(s string) bool

IsValidGCPRegion checks that s looks like a GCP region: lowercase letters, digits, and hyphens (e.g. "us-central1", "europe-west4").

func IsValidRef added in v0.32.0

func IsValidRef(ref string) bool

IsValidRef reports whether ref contains only characters safe for use in GitHub Actions workflow uses: lines.

func MarshalWithHeader added in v0.31.0

func MarshalWithHeader(m *Manifest) ([]byte, error)

MarshalWithHeader serializes the manifest with a descriptive header comment.

func MatchManifestRepos added in v0.32.0

func MatchManifestRepos(manifest *Manifest, patterns []string) ([]string, error)

MatchManifestRepos returns the list of repo names from the manifest that match any of the given patterns. Used by CLI commands to resolve positional args (which may contain globs) against manifest entries.

func MergeGitLabCI added in v0.38.0

func MergeGitLabCI(existing []byte) ([]byte, error)

MergeGitLabCI merges fullsend's CI configuration into an existing .gitlab-ci.yml. It uses yaml.v3's Node API to preserve comments and formatting in the existing file.

The merge performs up to three operations:

  1. Appends an include entry for .gitlab/ci/fullsend-pipeline.yml (skipped if already present)
  2. Appends fullsend's stages (dispatch, poll, agent) to the existing stages: array, deduplicating if already present. Skipped when no stages: key exists.
  3. When a workflow: block already exists, merges workflow:rules entries (deduplicates by if: condition) and sets auto_cancel.on_new_commit: none if not present. When no workflow: block exists, it is left absent so the repo's push-triggered pipelines are not disrupted.

When existing is nil or empty, returns a minimal .gitlab-ci.yml with just the fullsend include and workflow block.

func RemoveFromManifest added in v0.32.0

func RemoveFromManifest(cfg ManifestEditConfig, repos []string, progress ProgressFunc) (*ManifestRemoveResult, *Manifest, error)

RemoveFromManifest removes matching repo entries from all platform sections in the manifest. Patterns containing glob characters (*, ?, [) are matched against manifest entries using filepath.Match. Returns the result and the modified manifest.

func RuntimeSection added in v0.38.0

func RuntimeSection(runtime string) string

RuntimeSection renders the "Runtime" section appended to the scaffold PR body so the reviewer of a setup PR sees which agent runtime the repo will use and how to change it. An empty runtime means the default.

func ScaffoldPathsForForge added in v0.34.0

func ScaffoldPathsForForge(forgeName string) []string

ScaffoldPathsForForge returns the scaffold file paths to delete for the given forge during uninstall.

func SetDefault added in v0.34.0

func SetDefault(manifestPath, key, value string) error

SetDefault sets or removes a platform-level default in the manifest. An empty value removes the key. The file is created with version: 1 if it does not exist.

func UninstallSecretsForForge added in v0.34.0

func UninstallSecretsForForge(forgeName string) []string

UninstallSecretsForForge returns the CI/CD secret names to delete for the given forge during uninstall.

func UninstallVarsForForge added in v0.34.0

func UninstallVarsForForge(forgeName string) []string

UninstallVarsForForge returns the CI/CD variable names to delete for the given forge during uninstall.

func UnmergeGitLabCI added in v0.38.0

func UnmergeGitLabCI(existing []byte) ([]byte, error)

UnmergeGitLabCI removes fullsend's CI configuration from a .gitlab-ci.yml. It removes the fullsend pipeline include entry and the fullsend workflow:rules entries. Returns the cleaned YAML, or nil if the file has no remaining meaningful content.

Types

type ComponentAction added in v0.38.0

type ComponentAction struct {
	Component string // e.g., "workflow", "thin-caller:<path>", "var:MINT_URL", "ref"
	Action    string // "none", "add", "update", "upgrade", "orphan", "error"
	Detail    string // human-readable detail
}

ComponentAction describes an action taken (or planned) on a single installation component during convergence.

type ComponentStatus added in v0.37.0

type ComponentStatus struct {
	// Name identifies the component, prefixed by category:
	//   "workflow", "thin-caller:<path>", "var:<name>", "secret:<name>"
	Name string

	// Present is true when the component exists on the forge.
	Present bool

	// Expected is the manifest's desired value. Empty when value
	// checking does not apply (e.g., secrets whose values cannot be
	// read back, or when no expected value was provided).
	Expected string

	// Actual is the component's current value on the forge. Empty
	// when the component is not present or its value is opaque.
	Actual string

	// Match is true when the component is present and either no value
	// check applies or the actual value equals the expected value.
	Match bool
}

ComponentStatus describes the state of a single installation component as probed from the forge. Both install and status use this to answer "what's wrong with this repo?" — install acts on the answer, status reports it.

func ProbeComponents added in v0.37.0

func ProbeComponents(ctx context.Context, client forge.Client, owner, repo, forgeName string, fc ForgeConfig, expectedVarValues map[string]string) ([]ComponentStatus, error)

ProbeComponents checks all per-repo installation components and returns their status.

Components checked:

  • Shim workflow file (presence)
  • Per-repo thin callers (presence, GitHub only)
  • Required variables (presence; values compared when expectedVarValues contains a non-empty entry for the variable name)
  • Required secrets (presence only — values cannot be read back)

expectedVarValues maps variable names to their expected values for value-level drift detection. Pass nil for presence-only checking.

type ContentDriftFile added in v0.38.0

type ContentDriftFile struct {
	// Path is the expected path from the template. Use InstalledPath
	// when reporting drift to show the actual location on the forge.
	Path string

	// InstalledPath is the actual path of the file on the forge. For
	// workflow files this may differ from Path due to extension
	// differences (.yml vs .yaml).
	InstalledPath string

	// Expected is the rendered template content for this file.
	Expected []byte
}

ContentDriftFile describes a scaffold file whose installed content differs from the expected template output after ref normalization.

func CheckFileContentDrift added in v0.38.0

func CheckFileContentDrift(ctx context.Context, client forge.Client,
	owner, repo string, fc ForgeConfig, forgeName string,
	expectedFiles []forge.TreeFile) ([]ContentDriftFile, error)

CheckFileContentDrift compares expected scaffold files against installed files on the forge, returning files whose content has drifted. Refs are normalized with replaceShimRef before comparison so that ref-format differences (tag vs SHA, annotation presence) do not produce false positives — ref drift is detected separately.

Both the status and converge paths use this function so they share the same comparison logic and cannot diverge.

Files that are not found on the forge are skipped — presence drift is detected separately by ProbeComponents.

type ConvergeBatchResult added in v0.38.0

type ConvergeBatchResult struct {
	Results []ConvergeResult
}

ConvergeBatchResult holds the aggregate outcome of a batch convergence.

func Converge added in v0.38.0

func Converge(ctx context.Context, cfg ConvergeConfig,
	clients ForgeClientFactory,
	commitScaffold ScaffoldCommitFunc,
	progress ProgressFunc) (*ConvergeBatchResult, error)

Converge processes every repo in the manifest through a single convergence pipeline: probe → diff → apply. For each repo it determines what components exist and what actions are needed, then applies only the necessary changes.

This replaces the former two-phase architecture where BatchInstall handled new repos and a separate Upgrade + Sync pass handled already-installed repos.

func (*ConvergeBatchResult) AlreadyCurrent added in v0.38.0

func (r *ConvergeBatchResult) AlreadyCurrent() []ConvergeResult

AlreadyCurrent returns results where no action was needed.

func (*ConvergeBatchResult) Converged added in v0.38.0

func (r *ConvergeBatchResult) Converged() []ConvergeResult

Converged returns results where repos had drifted components repaired.

func (*ConvergeBatchResult) Failed added in v0.38.0

func (r *ConvergeBatchResult) Failed() []ConvergeResult

Failed returns results that errored.

func (*ConvergeBatchResult) Installed added in v0.38.0

func (r *ConvergeBatchResult) Installed() []ConvergeResult

Installed returns results where repos were newly installed.

type ConvergeConfig added in v0.38.0

type ConvergeConfig struct {
	Manifest       *Manifest
	DryRun         bool
	RepoFilter     []string
	MaxConcurrency int

	// Roles is the list of agent roles to install (e.g., "triage", "coder").
	Roles []string

	// UpstreamRef is the git ref (SHA) used to pin scaffold workflow refs.
	UpstreamRef string
	// UpstreamTag is the version tag corresponding to UpstreamRef.
	UpstreamTag string

	// Direct controls scaffold delivery: true pushes directly to the
	// default branch; false creates a PR.
	Direct bool

	// Force allows downgrades when upgrading refs.
	Force bool

	// InferenceProject is the GCP project ID for inference.
	InferenceProject string
	// InferenceProjectNumber is the numeric GCP project number.
	InferenceProjectNumber string
	// InferenceRegion is the GCP region for inference.
	InferenceRegion string

	// ReviewAppClientID is the OAuth client ID of the review agent's
	// GitHub App.
	ReviewAppClientID string
}

ConvergeConfig holds all inputs for a convergence operation that processes every repo through a single pipeline: probe → diff → apply. It replaces the former two-phase architecture where BatchInstall handled new repos and Upgrade + Sync handled already-installed repos.

type ConvergeResult added in v0.38.0

type ConvergeResult struct {
	Owner   string
	Repo    string
	Actions []ComponentAction

	// Installed is true when the repo was not previously installed and
	// received a full install.
	Installed bool

	// Converged is true when the repo had drifted components that were
	// repaired (variables, refs, or missing scaffold files).
	Converged bool

	// AlreadyCurrent is true when all components matched and no action
	// was needed.
	AlreadyCurrent bool

	Error error

	// WIFProvider is the WIF provider resource name used during install.
	WIFProvider string
}

ConvergeResult holds the outcome of converging a single repo.

type DefaultsConfig

type DefaultsConfig struct {
	AllowedRemoteResources []string `yaml:"allowed_remote_resources,omitempty"`
	// Runtime is the default agent runtime for every repo (claude, pi).
	Runtime string `yaml:"runtime,omitempty"`
}

DefaultsConfig holds default field values applied to every repo across all platforms.

type DiscoveredRepo added in v0.31.0

type DiscoveredRepo struct {
	Owner           string
	Repo            string
	Source          string // "per-repo", "per-org", or "new"
	MintURL         string
	InferenceRegion string
	FullsendRef     string
}

DiscoveredRepo holds the result of discovering a single repo's fullsend installation status.

type Drift added in v0.31.0

type Drift struct {
	Field    string `json:"field"`
	Expected string `json:"expected"`
	Actual   string `json:"actual"`
}

Drift describes a single field that differs between the manifest's desired state and the repo's actual state.

type DriftConfig added in v0.38.0

type DriftConfig struct {
	// InferenceRegion is the GCP region for inference. Only available
	// from CLI flags on repos install; empty on the status path.
	InferenceRegion string

	// ReviewAppClientID is the OAuth client ID of the review agent's
	// GitHub App. Only available from CLI flags on repos install.
	ReviewAppClientID string

	// RunnerTags is a list of GitLab CI runner tags from the manifest's
	// GitLab platform section.
	RunnerTags []string
}

DriftConfig holds additional fields beyond ResolvedConfig that are needed to build a complete InstallConfig for drift detection. These fields come from the manifest or CLI flags and are not part of the per-repo resolved config.

type ForgeClientFactory added in v0.33.0

type ForgeClientFactory interface {
	// ConfigFor returns a ForgeConfig with a live Client for the named forge.
	// The factory lazily creates and caches clients, so a GitLab token is
	// only required if the manifest actually contains GitLab entries.
	ConfigFor(forgeName string) (ForgeConfig, error)
}

ForgeClientFactory creates ForgeConfig instances with a live Client. The CLI layer implements this with lazy client creation and caching.

type ForgeConfig added in v0.33.0

type ForgeConfig struct {
	// Client is the API client for this forge. Set by ForgeClientFactory;
	// nil when ForgeConfig is constructed by ForgeConfigFor (pattern-only).
	Client forge.Client

	// WorkflowPaths lists the shim workflow file paths to try, in order.
	WorkflowPaths []string

	// WorkflowRefPattern extracts the @ref from a fullsend shim workflow.
	WorkflowRefPattern *regexp.Regexp

	// ShimRefPattern matches all @ref occurrences in fullsend uses: lines
	// within a workflow file, used by upgrade to rewrite refs.
	ShimRefPattern *regexp.Regexp
}

ForgeConfig holds forge-specific CI paths and regex patterns used by status and upgrade operations. Each forge has different workflow file conventions and ref syntax. When populated by a ForgeClientFactory, the Client field carries a live API client for the forge.

func ForgeConfigFor added in v0.33.0

func ForgeConfigFor(forgeName string) ForgeConfig

ForgeConfigFor returns the ForgeConfig for the given forge name. Unknown values (including empty string) default to GitHub. This is intentional: callers in legacy code paths may pass an empty forge, and Validate() catches invalid forge names before they reach here.

func GitHubForgeConfig added in v0.33.0

func GitHubForgeConfig() ForgeConfig

GitHubForgeConfig returns the ForgeConfig for GitHub repositories. GitHub Actions workflow files live under .github/workflows/ and use the "uses: owner/repo/.github/workflows/file@ref" syntax.

func GitLabForgeConfig added in v0.33.0

func GitLabForgeConfig() ForgeConfig

GitLabForgeConfig returns the ForgeConfig for GitLab repositories. GitLab CI files live under .gitlab/ci/ and use include: directives with ref: fields. Patterns here are placeholders for the GitLab CI dispatch template structure (see ADR 0067). The ShimRefPattern matches any ref: line in the file — the dispatch file must contain only the fullsend include (single-include constraint).

type InferenceProvisioner added in v0.34.0

type InferenceProvisioner interface {
	// Status checks if WIF infrastructure is already provisioned for a repo.
	// Returns the WIF provider resource name if provisioned, empty string
	// if not.
	Status(ctx context.Context, owner, repo string) (wifProvider string, err error)

	// Provision creates WIF infrastructure for a repo and returns the WIF
	// provider resource name.
	Provision(ctx context.Context, owner, repo string) (wifProvider string, err error)
}

InferenceProvisioner abstracts GCP WIF infrastructure operations. CLI implementations call real GCP APIs; tests provide stubs.

type InstallConfig

type InstallConfig struct {
	Owner string
	Repo  string
	Forge string

	// Roles is the list of agent roles to install (e.g., "triage", "code").
	Roles []string

	MintURL string

	InferenceProject string
	InferenceRegion  string

	// UpstreamRef is the git ref (SHA) used to pin scaffold workflow refs.
	// Empty for dev builds (falls back to config.DefaultUpstreamRef).
	UpstreamRef string
	// UpstreamTag is the version tag corresponding to UpstreamRef (e.g., "v0.42.0").
	UpstreamTag string

	// Skip flags control which install steps are executed. Set by callers
	// that handle specific steps externally (e.g., admin.go handles mint
	// setup before calling Install).
	SkipAppSetup bool

	// SkipScaffoldAndConfig skips scaffold file delivery and variable/secret
	// writes. The caller handles these steps externally (e.g., vendor mode
	// commits scaffold and vendor files together atomically).
	SkipScaffoldAndConfig bool

	// WIFProvider is the pre-computed WIF provider resource name. The caller
	// is responsible for computing or provisioning this value before calling
	// Install. Required unless SkipScaffoldAndConfig is true.
	WIFProvider string

	// PerRepoConfig, when set, overrides the default per-repo config
	// generated by NewPerRepoConfig. Used during migration to carry
	// over org config fields into the per-repo config.
	PerRepoConfig config.PerRepoConfigWriter

	// Runtime, when set, is written as the per-repo `runtime:` of the
	// generated config (`fullsend admin install <owner>/<repo> --runtime`).
	// Empty keeps the code default; ignored when PerRepoConfig is set.
	Runtime string

	VendorBinary bool

	// ReviewAppClientID is the OAuth client ID of the review agent's
	// GitHub App. When set, it is written as the FULLSEND_REVIEW_CLIENT_ID
	// repo variable so that pre-fetch-prior-review.sh can validate
	// provenance of prior review comments.
	ReviewAppClientID string

	// RunnerTags is a list of GitLab CI runner tags to embed in scaffold
	// pipeline YAML so that agent jobs are routed to specific runners.
	RunnerTags []string

	// Direct controls scaffold delivery: true pushes directly to the default
	// branch; false creates a PR.
	Direct bool

	// ReuseSecrets indicates that GCP secrets (FULLSEND_GCP_PROJECT_ID and
	// FULLSEND_GCP_WIF_PROVIDER) already exist on the repo and should not
	// be overwritten. When true, InferenceProject and WIFProvider may be
	// empty and secret writes are skipped.
	ReuseSecrets bool

	// PrebuiltScaffoldFiles, when non-nil, replaces the embedded scaffold
	// template collection. Used when fullsend_ref pins to a version that
	// differs from the running binary, so templates are fetched from the
	// fullsend-ai/fullsend repo at the pinned ref.
	PrebuiltScaffoldFiles scaffold.InstallFiles
}

InstallConfig is a pure data struct holding all inputs needed for a per-repo installation. CLI flags, environment variables, and interactive prompts are resolved by the caller before constructing this struct.

type InstallResult

type InstallResult struct {
	Owner string
	Repo  string

	Success bool
	Error   error

	// WIFProvider is the WIF provider resource name, either pre-existing
	// (from InstallConfig) or newly provisioned.
	WIFProvider string
}

InstallResult holds the outcome of a per-repo installation.

func Install

func Install(ctx context.Context, cfg InstallConfig,
	client forge.Client,
	commitScaffold ScaffoldCommitFunc,
	progress ProgressFunc) (*InstallResult, error)

Install performs a per-repo fullsend installation. It generates and commits scaffold files, and writes repository variables and secrets. The caller is responsible for computing the WIF provider resource name (via InstallConfig.WIFProvider) before calling this function — GCP provisioning is handled separately by `inference provision` and `mint enroll`.

type ManagedVar added in v0.38.0

type ManagedVar struct {
	Name    string
	Value   string
	Dynamic bool // true = presence-only (value mutated at runtime)
}

ManagedVar describes a repository variable with its expected value and whether it is dynamic (mutated at runtime). Static variables are value-checked during drift detection; dynamic variables are presence-checked only.

type Manifest

type Manifest struct {
	Version  int             `yaml:"version"`
	Defaults DefaultsConfig  `yaml:"defaults,omitempty"`
	GitHub   *PlatformConfig `yaml:"github,omitempty"`
	GitLab   *PlatformConfig `yaml:"gitlab,omitempty"`
}

Manifest is the top-level structure of a repos.yaml file. Platform sections (github, gitlab) replace the former nested forge section. Each platform section contains infrastructure config AND its repos list.

func LoadManifest

func LoadManifest(ctx context.Context, pathOrURL string) (*Manifest, error)

LoadManifest reads and parses a repos.yaml manifest from a local file path or an HTTPS URL. Remote fetches enforce a 30-second timeout and a 1 MB response size limit.

func (*Manifest) AllRepos added in v0.37.0

func (m *Manifest) AllRepos() []RepoEntry

AllRepos returns a flat list of all repo entries across all platform sections. The order is GitHub repos first, then GitLab repos, preserving the order within each section.

func (*Manifest) DistinctForges added in v0.33.0

func (m *Manifest) DistinctForges() []string

DistinctForges returns the deduplicated set of forge names actually used by entries in the manifest. Only forges with a non-nil platform section containing repos are included. The order is deterministic (github before gitlab).

func (*Manifest) EnsurePlatform added in v0.37.0

func (m *Manifest) EnsurePlatform(forgeName string) *PlatformConfig

EnsurePlatform returns the PlatformConfig for the given forge name, creating it if it does not exist.

func (*Manifest) ExpandGlobs

func (m *Manifest) ExpandGlobs(ctx context.Context, clients ForgeClientFactory) ([]ResolvedRepo, error)

ExpandGlobs resolves wildcard repo entries by listing org repos via the forge API (requires network access). Explicit entries always win over glob-matched entries. The returned list is deduplicated and sorted.

ListOrgRepos is called with includePrivate=true because repos.yaml manifests are used in per-repo mode, where agents run on the target repo itself. Archived and forked repos remain excluded.

The clients factory provides per-forge API clients so glob entries targeting different forges resolve against the correct API.

func (*Manifest) HasForge added in v0.33.0

func (m *Manifest) HasForge(name string) bool

HasForge reports whether any repo in the manifest resolves to the given forge name.

func (*Manifest) Marshal

func (m *Manifest) Marshal() ([]byte, error)

Marshal serializes the manifest back to YAML.

func (*Manifest) PlatformFor added in v0.37.0

func (m *Manifest) PlatformFor(forgeName string) *PlatformConfig

PlatformFor returns the PlatformConfig for the given forge name, or nil if that platform section is not present in the manifest.

func (*Manifest) ResolveConfig

func (m *Manifest) ResolveConfig(owner, repo string) (ResolvedConfig, bool)

ResolveConfig computes the fully merged configuration for the given owner/repo by looking up the entry in the manifest's platform sections. The resolution order is:

  1. Per-repo override (from RepoEntry)
  2. Platform-level default (from PlatformConfig)
  3. Built-in defaults (empty strings)

The sentinel value "none" at any level stops the fallback chain, returning "". The second return value indicates whether the repo was found in the manifest's repo list. When false, the returned config is empty.

For repos matched via glob expansion, use ResolveConfigForEntry instead — this method only finds exact matches in the manifest's repo list and will not match glob patterns.

func (*Manifest) ResolveConfigForEntry

func (m *Manifest) ResolveConfigForEntry(owner, repo, forgeName string, entry RepoEntry) ResolvedConfig

ResolveConfigForEntry computes the fully merged configuration for the given owner/repo using the provided RepoEntry and forge name. Use this with entries returned by ExpandGlobs, which carry per-glob overrides that ResolveConfig cannot find by exact match.

func (*Manifest) ResolveConfigWithGlobs added in v0.33.0

func (m *Manifest) ResolveConfigWithGlobs(owner, repo string) (ResolvedConfig, bool)

ResolveConfigWithGlobs resolves config for a repo, falling back to glob-pattern matching when the exact entry lookup fails.

func (*Manifest) TotalRepoCount added in v0.37.0

func (m *Manifest) TotalRepoCount() int

TotalRepoCount returns the total number of repo entries across all platform sections.

func (*Manifest) Validate

func (m *Manifest) Validate() error

Validate checks the manifest for structural correctness:

  • version must be 1
  • github.url defaults to https://github.com when unset; mint_url defaults to DefaultPublicMintURL in public mode, and is required in private mode
  • gitlab.url is required when a gitlab section is present with repos
  • platform-specific fields are rejected on the wrong platform
  • each repo entry must have a valid owner/repo or owner/glob format
  • glob characters are only allowed in the repo name, not the owner
  • no duplicate repo entries (before glob expansion)
  • glob patterns must be valid filepath.Match patterns
  • forge URLs must be valid HTTPS URLs with no path component

type ManifestAddResult added in v0.32.0

type ManifestAddResult struct {
	Added   []string
	Skipped []string
}

ManifestAddResult holds the outcome of adding repos to a manifest.

type ManifestEditConfig added in v0.32.0

type ManifestEditConfig struct {
	Manifest     *Manifest
	ManifestPath string
	DryRun       bool
}

ManifestEditConfig holds inputs for manifest add/remove operations.

type ManifestRemoveResult added in v0.32.0

type ManifestRemoveResult struct {
	Removed []string
	Skipped []string
}

ManifestRemoveResult holds the outcome of removing repos from a manifest.

type MigrateConfig added in v0.34.0

type MigrateConfig struct {
	// Org is the GitHub organization to migrate.
	Org string
	// Project is the GCP project ID for inference (required).
	Project string
	// RepoFilter limits migration to specific repos (supports globs).
	RepoFilter []string
	// DryRun previews changes without applying.
	DryRun bool
	// Direct pushes scaffold directly to the default branch instead of
	// creating a PR.
	Direct bool
	// MaxConcurrency is the parallel limit for per-repo operations.
	MaxConcurrency int
	// ManifestPath is the output path for the generated repos.yaml.
	ManifestPath string
	// Roles is the list of agent roles to install.
	Roles []string
	// UpstreamRef is the git ref (SHA) used to pin scaffold workflow refs.
	UpstreamRef string
	// UpstreamTag is the version tag corresponding to UpstreamRef.
	UpstreamTag string
	// CLIVersion is the current CLI version, used for manifest ref defaults.
	CLIVersion string

	// ReviewAppClientID is the OAuth client ID of the review agent's
	// GitHub App. When set, it is written as FULLSEND_REVIEW_CLIENT_ID
	// on each migrated repo.
	ReviewAppClientID string
}

MigrateConfig holds configuration for the repos migrate command.

type MigrateRepoResult added in v0.34.0

type MigrateRepoResult struct {
	Owner       string
	Repo        string
	Status      string // "migrated", "skipped", "failed"
	WIFProvider string
	Error       error
	StatusError error
}

MigrateRepoResult holds the outcome of migrating a single repo.

type MigrateResult added in v0.34.0

type MigrateResult struct {
	Migrated      []MigrateRepoResult
	Skipped       []MigrateRepoResult
	Failed        []MigrateRepoResult
	Manifest      *Manifest
	Unenrolled    int
	UnenrollError error
}

MigrateResult holds the overall outcome of a migration.

func Migrate added in v0.34.0

func Migrate(ctx context.Context, cfg MigrateConfig, clients ForgeClientFactory,
	provisioner InferenceProvisioner,
	commitScaffold ScaffoldCommitFunc,
	progress ProgressFunc) (*MigrateResult, error)

Migrate orchestrates the full migration of an org from per-org to per-repo install. For each enrolled repo it:

  1. Checks if already per-repo installed (skips if so)
  2. Checks/provisions inference WIF infrastructure
  3. Installs per-repo (scaffold, variables, secrets)
  4. Unenrolls from per-org config

At the end, it generates a repos.yaml manifest from the discovered state. Individual repo failures do not abort the batch.

type OrphanFile added in v0.38.0

type OrphanFile struct {
	Path string
}

OrphanFile describes a file that exists on the forge at a managed scaffold path but is no longer produced by the current template.

func CheckOrphanFiles added in v0.38.0

func CheckOrphanFiles(ctx context.Context, client forge.Client,
	owner, repo string, fc ForgeConfig, forgeName string,
	expectedFiles []forge.TreeFile) ([]OrphanFile, error)

CheckOrphanFiles compares the set of managed scaffold paths against the expected template output, checking which managed paths exist on the forge but are absent from the expected files. These are orphan files — leftover from a previous template version.

type OrphanVar added in v0.38.0

type OrphanVar struct {
	Name string
}

OrphanVar describes a repository variable with the FULLSEND_ prefix that exists on the forge but is not in the current managed variable set.

func CheckOrphanVars added in v0.38.0

func CheckOrphanVars(ctx context.Context, client forge.Client,
	owner, repo string, cfg InstallConfig, mintURL string) ([]OrphanVar, error)

CheckOrphanVars lists all repository variables on the forge and returns those with the FULLSEND_ prefix that are not in the managed variable set for the given forge. These are orphan variables — leftover from a previous installation or a removed feature.

The managed set is computed using the FULL superset of possible managed variables — conditional fields (InferenceRegion, ReviewAppClientID) are populated with placeholders so that variables like FULLSEND_GCP_REGION are never flagged as orphans just because the caller doesn't know their expected value.

type PlatformConfig added in v0.37.0

type PlatformConfig struct {
	URL         string      `yaml:"url,omitempty"`
	MintURL     string      `yaml:"mint_url,omitempty"`
	MintMode    string      `yaml:"mint_mode,omitempty"`
	FullsendRef string      `yaml:"fullsend_ref,omitempty"`
	RunnerTags  []string    `yaml:"runner_tags,omitempty"`
	Repos       []RepoEntry `yaml:"repos"`
}

PlatformConfig holds per-platform infrastructure settings and the list of repos managed under that platform. A single struct serves both GitHub and GitLab; validation rejects platform-specific fields on the wrong platform (e.g. mint_url under gitlab).

type ProgressFunc

type ProgressFunc func(repo, phase, message string)

ProgressFunc is a callback for reporting installation progress. The caller maps this to spinner output, structured logs, or whatever UI is appropriate.

Parameters:

  • repo: the "owner/repo" being installed
  • phase: a machine-readable phase name (e.g., "scaffold", "vars", "secrets")
  • message: a human-readable status message

type RefResolver added in v0.37.0

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

RefResolver resolves symbolic fullsend_ref values (tags, branches) to commit SHAs on the fullsend-ai/fullsend repository. Results are cached so repeated calls for the same ref avoid redundant API calls.

func NewRefResolver added in v0.37.0

func NewRefResolver(client forge.Client) *RefResolver

NewRefResolver creates a resolver that uses the given GitHub client. The client must target GitHub's API since fullsend-ai/fullsend is always a GitHub repository.

func (*RefResolver) IsAncestor added in v0.37.0

func (r *RefResolver) IsAncestor(ctx context.Context, potentialAncestor, descendant string) (bool, error)

IsAncestor reports whether potentialAncestor is an ancestor of (or identical to) descendant in the fullsend-ai/fullsend repository. Both arguments must be commit SHAs. Returns false with a nil error when the relationship cannot be determined (e.g., diverged commits).

func (*RefResolver) Resolve added in v0.37.0

func (r *RefResolver) Resolve(ctx context.Context, ref string) string

Resolve resolves ref to a commit SHA on fullsend-ai/fullsend. If ref is already a SHA it is returned unchanged. Tags are tried first, then branches. If resolution fails, ref is returned as-is (graceful degradation to string comparison).

type RepoEntry

type RepoEntry struct {
	Name                   string   `yaml:"name"`
	FullsendRef            string   `yaml:"fullsend_ref,omitempty"`
	MintURL                string   `yaml:"mint_url,omitempty"`
	MintMode               string   `yaml:"mint_mode,omitempty"`
	AllowedRemoteResources []string `yaml:"allowed_remote_resources,omitempty"`
	// Runtime is the agent runtime written as the repo's `runtime:` at
	// install time (claude, pi); empty inherits defaults.runtime, and an
	// empty resolved value keeps the code default (claude).
	Runtime string `yaml:"runtime,omitempty"`
}

RepoEntry represents a single repo or glob pattern in a platform's repos list. Always uses object form with name as the required field. Override fields use plain strings; the sentinel value "none" stops the inheritance chain.

type RepoState added in v0.32.0

type RepoState struct {
	Installed       bool
	MintURL         string
	InferenceRegion string
	FullsendRef     string
}

RepoState holds the installation state of a single repo as read from forge variables and workflow files.

func ProbeRepoState added in v0.32.0

func ProbeRepoState(ctx context.Context, client forge.Client, owner, repo, forgeName string, fc ForgeConfig) (RepoState, error)

ProbeRepoState reads a repo's current per-repo installation state by probing all installation components (workflow files, variables, secrets). A repo is considered per-repo installed when at least one required variable is present — a workflow file alone may come from per-org enrollment. Returns a zero RepoState when no required variables are found.

type RepoStatus added in v0.31.0

type RepoStatus struct {
	Owner           string  `json:"owner"`
	Repo            string  `json:"repo"`
	Installed       bool    `json:"installed"`
	CurrentRef      string  `json:"current_ref,omitempty"`
	ExpectedRef     string  `json:"expected_ref,omitempty"`
	MintURL         string  `json:"mint_url,omitempty"`
	ExpectedMintURL string  `json:"expected_mint_url,omitempty"`
	Region          string  `json:"region,omitempty"`
	Drifts          []Drift `json:"drifts,omitempty"`
	Error           string  `json:"error,omitempty"`
}

RepoStatus holds the status of a single repo as compared against the manifest's desired state.

type ResolvedConfig

type ResolvedConfig struct {
	Owner                  string
	Repo                   string
	Forge                  string
	ForgeConfig            ForgeConfig
	MintURL                string
	MintMode               string
	FullsendRef            string
	AllowedRemoteResources []string
	// Runtime is the resolved agent runtime (entry, then defaults); empty
	// means the code default.
	Runtime string
}

ResolvedConfig is the fully resolved configuration for a single repository after merging manifest defaults and platform-level settings. The ForgeConfig field carries per-forge patterns and (when populated by ForgeClientFactory.ConfigFor) a live API client.

type ResolvedRepo

type ResolvedRepo struct {
	Owner string
	Repo  string
	Forge string
	Entry RepoEntry
}

ResolvedRepo pairs an owner/repo with the manifest entry that matched it (either an explicit entry or a glob-generated one).

type ScaffoldCommitFunc

type ScaffoldCommitFunc func(ctx context.Context, owner, repo string,
	files []forge.TreeFile, direct bool, installed bool) error

ScaffoldCommitFunc delivers scaffold files to a repository and returns any error encountered.

The installed parameter indicates whether this repo already had fullsend components before this operation (true = upgrade, false = fresh install). CLI implementations use this to select the appropriate commit message and PR title without making extra API calls.

The CLI layer provides an implementation wrapping layers.CommitScaffoldFiles, which adds retry on non-fast-forward errors, branch-protection fallback to PR delivery, and fork-based PR support for non-owner users.

type ScaffoldMetadataOpts added in v0.36.0

type ScaffoldMetadataOpts struct {
	// GuardInstalled indicates whether the repo already has fullsend
	// installed (true = upgrade path, false = fresh install). When nil,
	// the function defaults to fresh-install metadata.
	GuardInstalled *bool

	// OldVersion, when non-empty, overrides the existing-version detection
	// from the workflow file. Only meaningful on the upgrade path.
	OldVersion string
}

ScaffoldMetadataOpts holds pre-fetched values for BuildScaffoldPRMetadata.

type ScaffoldPRMetadata added in v0.36.0

type ScaffoldPRMetadata struct {
	CommitMsg string
	PRTitle   string
	PRBody    string
	Branch    string
}

ScaffoldPRMetadata holds commit/PR metadata for scaffold file delivery. Values differ based on whether this is a fresh install or a version upgrade.

func BuildScaffoldPRMetadata added in v0.36.0

func BuildScaffoldPRMetadata(ctx context.Context, client forge.Client,
	owner, repo, upstreamTag string, opts ...ScaffoldMetadataOpts) ScaffoldPRMetadata

BuildScaffoldPRMetadata returns PR metadata appropriate for the operation type: fresh install vs. version upgrade. Callers must indicate whether the repo is already installed via opts.GuardInstalled; when nil the function defaults to fresh-install metadata.

type StatusResult added in v0.31.0

type StatusResult struct {
	Repos    []RepoStatus  `json:"repos"`
	Summary  StatusSummary `json:"summary"`
	Warnings []string      `json:"warnings,omitempty"`
}

StatusResult holds the full output of a status check.

func Status added in v0.31.0

func Status(ctx context.Context, manifest *Manifest, clients ForgeClientFactory, maxConcurrency int, repoFilter []string) (*StatusResult, error)

Status compares the manifest's desired state against the actual forge state for each repo. It returns a StatusResult with per-repo status and aggregate counts. API calls are parallelised up to maxConcurrency.

type StatusSummary added in v0.31.0

type StatusSummary struct {
	Total        int `json:"total"`
	Installed    int `json:"installed"`
	NotInstalled int `json:"not_installed"`
	Drifted      int `json:"drifted"`
	Errored      int `json:"errored"`
}

StatusSummary provides aggregate counts across all repos. Counts are not mutually exclusive: a repo can be both Installed and Errored (e.g. variables present but workflow read fails), so Installed + NotInstalled + Errored may exceed Total.

type UninstallConfig added in v0.32.0

type UninstallConfig struct {
	Manifest       *Manifest
	Repos          []string
	DryRun         bool
	MaxConcurrency int
}

UninstallConfig holds all inputs for a multi-repo uninstall operation.

type UninstallResult added in v0.32.0

type UninstallResult struct {
	Owner           string
	Repo            string
	Success         bool
	Error           error
	WorkflowDeleted bool
	VarsDeleted     int
	SecretsDeleted  int
}

UninstallResult holds the outcome of uninstalling fullsend from a single repo.

func Uninstall added in v0.32.0

func Uninstall(ctx context.Context, cfg UninstallConfig,
	clients ForgeClientFactory,
	progress ProgressFunc) ([]UninstallResult, error)

Uninstall tears down fullsend from the specified repos.

It runs in a single phase: parallel per-repo cleanup (bounded by MaxConcurrency) deletes the workflow file, then deletes variables and secrets.

GCP WIF cleanup is handled separately via `inference deprovision`.

Does NOT modify repos.yaml — use RemoveFromManifest for that.

Jump to

Keyboard shortcuts

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