scaffold

package
v0.53.0 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source
const (
	RunnerImageLatestTag = "latest"
	RunnerImageDevTag    = "dev"
)

Runner image tags that are not release versions. RunnerImageLatestTag is published only for non-prerelease release tags, so it tracks releases. RunnerImageDevTag moves on every main push that changes the runner image and is not supported for production.

View Source
const (
	// PerRepoVendorPrefix is the in-repo directory that holds vendored
	// assets in a per-repo install.
	PerRepoVendorPrefix = ".fullsend/"

	// PerRepoVendoredBinaryPath is the vendored binary path inside a
	// per-repo target repo.
	PerRepoVendoredBinaryPath = ".fullsend/bin/fullsend"
)
View Source
const DefaultGitLabIDTokenAudience = "fullsend"

DefaultGitLabIDTokenAudience is the audience the shipped GitLab agent job requests for FULLSEND_ID_TOKEN. Installs whose WIF provider is the guide's own gitlab-oidc provider keep it.

View Source
const GitLabAgentTemplatePath = ".gitlab/ci/fullsend-agent.yml"

GitLabAgentTemplatePath is the GitLab agent job template whose id_tokens block requests the token used for Vertex workload identity federation.

View Source
const RunnerImageRepository = "ghcr.io/fullsend-ai/fullsend-runner"

RunnerImageRepository is the image the GitLab CI templates run their poll, dispatcher, and agent jobs in. Only Fullsend's runner-image workflow publishes to it.

Variables

This section is empty.

Functions

func ComparePathPresence added in v0.19.0

func ComparePathPresence(ctx context.Context, client forge.Client, owner, repo string, expected []string) (missing []string, err error)

ComparePathPresence checks which expected paths exist in the repo's default branch. It uses forge.Client.ListRepositoryFiles to fetch all file paths in a single call, then checks membership locally. This replaces O(N) GetFileContent calls with O(1) API calls.

func FileMode added in v0.6.0

func FileMode(path string) string

FileMode returns the Git tree mode for a scaffold file.

func FormatRunnerTags added in v0.37.0

func FormatRunnerTags(tags []string) string

formatRunnerTags formats runner tags as a YAML inline list.

func FormatVersionMarker added in v0.37.0

func FormatVersionMarker(upstreamRef, upstreamTag string) string

formatVersionMarker returns a YAML comment line containing the version for drift detection. The comment uses "fullsend-ref:" which is matched by glWorkflowRefPattern (\bref:) because the hyphen before "ref" creates a word boundary. Returns "" when no version is available.

When both upstreamRef (a commit SHA) and upstreamTag (a human-readable version) are set and differ, the marker includes a parenthesized annotation: "# fullsend-ref: <sha> (<tag>)".

func FullsendRepoFile

func FullsendRepoFile(path string) ([]byte, error)

FullsendRepoFile returns the content of a file from the fullsend-repo scaffold. The path is relative to the fullsend-repo root (e.g., ".github/workflows/prioritize.yml").

func GitLabPerRepoFile added in v0.33.0

func GitLabPerRepoFile(path string) ([]byte, error)

GitLabPerRepoFile returns the content of a file from the GitLab per-repo scaffold. The path is relative to the fullsend-repo-gitlab root (e.g., ".gitlab-ci.yml").

func HarnessBaseURL added in v0.18.0

func HarnessBaseURL(harnessName, commitSHA string) (string, error)

HarnessBaseURL returns the raw.githubusercontent.com URL for a scaffold harness template at a specific commit SHA.

func HarnessContent added in v0.30.0

func HarnessContent(harnessName string) ([]byte, error)

HarnessContent returns the raw YAML bytes of an embedded scaffold harness template. This is the same content served by raw.githubusercontent.com for the release commit the CLI was built from.

func InsertAfterDocStart added in v0.37.0

func InsertAfterDocStart(content, line string) string

insertAfterDocStart inserts a line after the YAML document start marker (---\n). If no document start marker is present, the line is prepended.

func IsLayeredPath added in v0.19.0

func IsLayeredPath(path string) bool

IsLayeredPath reports whether path is in a layered content directory.

func IsRunnerImageTag added in v0.52.0

func IsRunnerImageTag(tag string) bool

IsRunnerImageTag reports whether tag is one ResolveRunnerImageTag can return: a release version (X.Y.Z, optionally a prerelease), "latest", or "dev".

func IsUpstreamOnlyPath added in v0.19.0

func IsUpstreamOnlyPath(path string) bool

IsUpstreamOnlyPath reports whether path is upstream-only infrastructure.

func LegacyFlatVendoredPaths added in v0.19.0

func LegacyFlatVendoredPaths(workflowPrefix string) ([]string, error)

LegacyFlatVendoredPaths lists pre-.defaults flat layout paths for legacy cleanup.

func LocalReusableWorkflowTargets added in v0.48.0

func LocalReusableWorkflowTargets(paths []string) []string

LocalReusableWorkflowTargets returns the `uses:` targets (./.github/workflows/<name>) of the reusable workflows among paths, the form a vendored caller uses to reach them.

func ManagedHeader added in v0.18.0

func ManagedHeader(path string) string

ManagedHeader returns the managed-by header to prepend to a scaffold file at install time, or an empty string if the file should not have one. Files that support # comments (YAML, shell) get a header pointing to the upstream source. Markdown, JSON, and .gitkeep files are skipped.

func ManagedVendoredContentPaths added in v0.19.0

func ManagedVendoredContentPaths(workflowPrefix string) ([]string, error)

ManagedVendoredContentPaths returns embed-derived paths for the current vendor layout.

func PathsFromInstallFiles added in v0.19.0

func PathsFromInstallFiles(files InstallFiles) []string

PathsFromInstallFiles extracts relative paths from install files.

func PerRepoShimTemplate added in v0.8.0

func PerRepoShimTemplate() ([]byte, error)

PerRepoShimTemplate returns the content of the per-repo shim workflow template.

func PerRepoThinCallerPaths added in v0.37.0

func PerRepoThinCallerPaths() []string

PerRepoThinCallerPaths returns the workflow paths installed as thin callers during per-repo installation. Used by uninstall and remote scaffold to keep lifecycle operations in sync with install.

func PrependManagedHeader added in v0.18.0

func PrependManagedHeader(path string, content []byte) []byte

PrependManagedHeader prepends the managed-by header to file content. If the file starts with a shebang (#!), the header is inserted after the first line. Returns content unchanged if no header applies.

func RenderGitLabAgentAudience added in v0.51.0

func RenderGitLabAgentAudience(content []byte, audience string) ([]byte, error)

RenderGitLabAgentAudience returns the agent template content with its FULLSEND_ID_TOKEN audience set to audience. An empty audience, or the default one, returns content unchanged. The caller validates audience (a single printable line); it is written as a double-quoted YAML scalar. The template must contain the shipped audience line exactly once, so a template that has drifted from it fails instead of silently keeping the default audience.

func RenderRunnerImageTag added in v0.52.0

func RenderRunnerImageTag(content, tag string) string

RenderRunnerImageTag renders tag into the runner image references of a GitLab CI template. Besides the placeholder, it rewrites the legacy hardcoded ":dev" reference so templates fetched from an older pinned ref also run the image matching that ref instead of tracking main.

func RenderTemplate added in v0.19.0

func RenderTemplate(path string, content []byte, opts RenderOptions) ([]byte, error)

RenderTemplate applies vendoring-aware substitutions to scaffold templates. Substitutions are fixed string replacements (not text/template), so only compile-time constants are injected into workflow YAML.

func ResolveFullsendVersion added in v0.37.0

func ResolveFullsendVersion(upstreamRef, upstreamTag string) string

ResolveFullsendVersion returns the version string for the __FULLSEND_VERSION__ placeholder in GitLab CI templates. The shared install-fullsend-cli.sh script uses this to install the CLI at runtime: version tags (v0.42.0) trigger a pre-built binary download from GitHub Releases; commit SHAs trigger a clone-and-build from source. Dev builds (both inputs empty) return "latest" so the before_script resolves the newest release — the before_script always installs the pinned version, overwriting any default binary in the runner image.

func ResolveRunnerImageTag added in v0.52.0

func ResolveRunnerImageTag(upstreamRef, upstreamTag string) string

ResolveRunnerImageTag returns the fullsend-runner image tag the GitLab CI templates run, derived from the same inputs as ResolveFullsendVersion so the image follows the pinned CLI:

  • a release ref or tag (vX.Y.Z) selects the release image X.Y.Z;
  • no ref at all (a dev build with no fullsend_ref, which installs the latest release CLI) selects "latest", which tracks releases;
  • any other ref (a branch such as main, or an untagged commit SHA) selects "dev". The runner image is built only for main commits that touch its inputs, so such a ref cannot map to an image of its own; pinning one is the explicit opt-in to main's image.

func ResolveVendoredCleanupPaths added in v0.19.0

func ResolveVendoredCleanupPaths(ctx context.Context, client forge.Client, owner, repo, workflowPrefix, binaryPath string) ([]string, error)

ResolveVendoredCleanupPaths returns paths to delete when disabling --vendor. Prefers the committed manifest; falls back to embed enumeration for legacy installs. binaryPath is included when no manifest is present.

func SanitizeDisplayText added in v0.48.0

func SanitizeDisplayText(s string) string

SanitizeDisplayText replaces control and other non-printable characters so text derived from repository content is safe to print in CLI and workflow output.

func StaleVendoredPaths added in v0.38.0

func StaleVendoredPaths(manifest *VendorManifest, current []string) []string

StaleVendoredPaths returns manifest-recorded content paths that are not part of the new vendored set, so a re-vendor can delete them in the same commit instead of leaving untracked orphans in consumer repos (e.g. a script removed from the vendoredDefaultsScripts allowlist). Only safe vendored repo paths are returned; the binary and the manifest itself are tracked separately and never appear in manifest.Paths.

func VendorManifestPath added in v0.19.0

func VendorManifestPath(workflowPrefix string) string

VendorManifestPath returns the manifest path for the install mode.

func VendoredMarkerPath added in v0.19.0

func VendoredMarkerPath() string

VendoredMarkerPath returns the path used to detect a vendored install.

func WalkFullsendRepo

func WalkFullsendRepo(fn func(path string, content []byte) error) error

WalkFullsendRepo calls fn for each file in the fullsend-repo scaffold that should be installed into a .fullsend repo. Files in layered directories (agents/, skills/, etc.) and upstream-only directories (.github/actions/, .github/scripts/) are skipped — they are provided at runtime by reusable workflows. See ADR 0035.

func WalkFullsendRepoAll added in v0.8.0

func WalkFullsendRepoAll(fn func(path string, content []byte) error) error

WalkFullsendRepoAll calls fn for every file in the fullsend-repo scaffold, including layered and upstream-only files. Used by tests that validate embedded content.

func WalkGitLabPerRepo added in v0.33.0

func WalkGitLabPerRepo(fn func(path string, content []byte) error) error

WalkGitLabPerRepo calls fn for each file in the GitLab per-repo scaffold. Unlike WalkFullsendRepo, this does not filter layered directories because the GitLab scaffold contains only CI pipeline YAML, helper scripts, and .fullsend/config.yaml — it has no layered content (harness, agents, policies) to filter. Harness resolution at runtime is handled by fullsend run's config-driven lookup.

func WalkLayeredContent added in v0.19.0

func WalkLayeredContent(fn func(path string, content []byte) error) error

WalkLayeredContent calls fn for layered directories and .github/scripts from fullsend-repo.

func WalkUpstream added in v0.19.0

func WalkUpstream(fn func(path string, content []byte) error) error

WalkUpstream calls fn for upstream assets from the current module checkout. Used by tests; install-time vendoring reads from ResolveVendorRoot instead.

Types

type InstallFile added in v0.19.0

type InstallFile struct {
	Path    string
	Content []byte
	Mode    string
}

InstallFile is a file to commit during install.

type InstallFiles added in v0.19.0

type InstallFiles []InstallFile

InstallFiles is the slice type returned by install collectors.

func CollectGitLabPerRepoInstallFiles added in v0.34.0

func CollectGitLabPerRepoInstallFiles(agentRunnerTags, controlRunnerTags []string, upstreamRef, upstreamTag string) (InstallFiles, error)

CollectGitLabPerRepoInstallFiles gathers CI template files for GitLab per-repo installation.

The embedded .fullsend/config.yaml is excluded — callers generate a config with roles and forge field instead.

The embedded root .gitignore is also excluded: installing it would overwrite a consumer's existing ignore file with a one-line fragment. The embed still ships for docs/tests; adopters (and the guide) add output/ themselves. When --output-dir sits inside --target-repo (GitLab layout), fullsend run omits that top-level directory from the sandbox tarball and .git/info/exclude via outputDirExcludeRel.

The root .gitlab-ci.yml is also excluded: the install flow merges fullsend's include directive and workflow rules into the consumer's existing file (or creates a minimal one) instead of overwriting it. See MergeGitLabCI in internal/repos/gitlabci.go.

agentRunnerTags and controlRunnerTags specify GitLab runner tags to inject into agent (data-plane) and control-plane CI job definitions. upstreamRef and upstreamTag control the version marker embedded in the pipeline wrapper for upgrade/status drift detection.

func CollectPerRepoInstallFiles added in v0.19.0

func CollectPerRepoInstallFiles(vendored bool, upstreamRef, upstreamTag string) (InstallFiles, error)

CollectPerRepoInstallFiles gathers files for per-repo installation.

func CollectVendoredAssets added in v0.19.0

func CollectVendoredAssets(root, workflowPrefix string) (InstallFiles, error)

CollectVendoredAssets gathers files for --vendor installs. Upstream mirror content lives under .defaults/ (same layout as runtime sparse checkout). Reusable workflows are always written under .github/workflows/ because GitHub Actions requires local reusable workflow references (./path) to live there. Other vendored assets use workflowPrefix (.fullsend/ for repository installs).

type RenderOptions added in v0.19.0

type RenderOptions struct {
	Vendored    bool
	UpstreamRef string // commit SHA to pin workflow refs to; empty = use DefaultUpstreamRef
	UpstreamTag string // version tag for traceability comment (e.g. "v0.19.0")
	RunnerImage string // GitHub Actions runner image; empty = use DefaultGHRunner
}

RenderOptions controls install-time substitution for shim and thin-caller templates.

func RenderOptionsForInstall added in v0.19.0

func RenderOptionsForInstall(vendored bool, upstreamRef, upstreamTag string) RenderOptions

RenderOptionsForInstall builds render options from the --vendor flag.

type StaleVendoredAssets added in v0.48.0

type StaleVendoredAssets struct {
	// Paths lists the stale vendored files that exist on the default
	// branch and whose Fullsend ownership is established, sorted.
	Paths []string
	// Ignored counts vendor-manifest entries kept because the path is not
	// one a vendored install owns (for example .fullsend/config.yaml or a
	// custom action). Their names are not reported: they come from
	// repository content.
	Ignored int
	// RepoFiles is the default-branch file listing the decision used.
	RepoFiles []string
}

StaleVendoredAssets describes the Fullsend-owned assets an earlier vendored install left in a repository whose vendoring is now disabled. It is computed from read-only forge calls, so install, dry run and status can share one answer about what is safe to delete.

func FindStaleVendoredAssets added in v0.48.0

func FindStaleVendoredAssets(ctx context.Context, client forge.Client, owner, repo string) (*StaleVendoredAssets, error)

FindStaleVendoredAssets returns the Fullsend-owned vendored assets present in a repository. Repository content is treated as untrusted evidence of ownership:

  • Nothing is reported unless the vendor manifest or the vendored binary is present.
  • With a vendor manifest, only its entries that are files Fullsend is known to have shipped (the current embedded .defaults/ layout, explicit historical paths, the known reusable workflow files, the vendored binary and the manifest itself) are reported. Any other entry, including a user-created file under .defaults/ or .fullsend/.defaults/ and entries such as .fullsend/config.yaml or custom actions, is counted in Ignored and kept.
  • With only the binary, the embed-derived .defaults/ layout and the known reusable workflow files are reported. A root action.yml and .github/actions/ or .github/scripts/ files are never claimed.

A malformed manifest or a failed read returns an error, so callers make no changes. Returned paths never contain control characters.

type VendorManifest added in v0.19.0

type VendorManifest struct {
	Version    string   `yaml:"version"`
	CLIVersion string   `yaml:"cli_version,omitempty"`
	SourceRef  string   `yaml:"source_ref,omitempty"`
	BinaryPath string   `yaml:"binary_path"`
	Paths      []string `yaml:"paths"`
}

VendorManifest records paths written by a --vendor install for cleanup and analyze.

func NewVendorManifest added in v0.19.0

func NewVendorManifest(cliVersion, sourceRef, binaryPath string, contentPaths []string) *VendorManifest

NewVendorManifest builds a manifest from install outputs.

func ParseVendorManifest added in v0.19.0

func ParseVendorManifest(data []byte) (*VendorManifest, error)

ParseVendorManifest parses manifest YAML from a repository.

func ReadVendorManifest added in v0.19.0

func ReadVendorManifest(ctx context.Context, client forge.Client, owner, repo, workflowPrefix string) (*VendorManifest, bool, error)

ReadVendorManifest loads the manifest from a repo when present.

func (*VendorManifest) CleanupPaths added in v0.19.0

func (m *VendorManifest) CleanupPaths(workflowPrefix string) []string

CleanupPaths returns all repo paths to delete, including the manifest file.

func (*VendorManifest) MarshalYAML added in v0.19.0

func (m *VendorManifest) MarshalYAML() ([]byte, error)

MarshalYAML serializes the manifest.

Jump to

Keyboard shortcuts

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