description

Documentation

Overview

Package description holds the domain logic for keeping a repository's description in sync across forges and for pushing the canonical description to any configured backup destinations. This logic used to live in internal/cli/description_sync.go, which reached directly into codeberg.NewForgejoClient, os.WriteFile, and exec.Command("ssh", ...) from the CLI layer - a Separation of Concerns violation (task w01). Moving it here keeps internal/cli as a thin flag-parsing -> function-call layer: the composition root (internal/cli/description_sync.go) builds the concrete forge/file/ssh writers and injects them, following the same pattern task t01 established for forge.PublicRepoEnsurer (SetForgejoBackupClientFactory) and task u01 established for ForgeClientResolver.

Index

• func SyncRepoDescriptions(cfg *config.Config, dryRun bool, backupActive func(*config.Organization) bool, ...)
• type BackupDescriptionWriter
• type FileBackupDescriptionWriter
  • func (FileBackupDescriptionWriter) WriteBackupDescription(org *config.Organization, repoName, description string, dryRun bool) (bool, error)
• type ForgeClientResolver
• type ForgejoBackupDescriptionWriter
  • func (w ForgejoBackupDescriptionWriter) WriteBackupDescription(org *config.Organization, repoName, description string, dryRun bool) (bool, error)
• type ForgejoClientFactory
• type ForgejoDescriptionClient
• type SSHBackupDescriptionWriter
  • func (SSHBackupDescriptionWriter) WriteBackupDescription(org *config.Organization, repoName, description string, dryRun bool) (bool, error)

Functions

func SyncRepoDescriptions

func SyncRepoDescriptions(cfg *config.Config, dryRun bool, backupActive func(*config.Organization) bool, disableBackup func(*config.Organization, error), repoName, knownCBDesc, knownGHDesc string, cache map[string]string, resolver ForgeClientResolver, writers []BackupDescriptionWriter)

SyncRepoDescriptions ensures both platforms have the canonical description and pushes it to any active backup destinations. Precedence: Codeberg > GitHub; if Codeberg empty and GitHub has one, use GitHub. knownCBDesc and knownGHDesc can be empty; the function fetches as needed. writers is tried in order for each active backup organization (see writeBackupDescription); internal/cli constructs and injects the concrete list (Forgejo/file/SSH) at its composition root.

Types

type BackupDescriptionWriter

type BackupDescriptionWriter interface {
	WriteBackupDescription(org *config.Organization, repoName, description string, dryRun bool) (supported bool, err error)
}

BackupDescriptionWriter writes a repository description to one backup mechanism (Forgejo API, local bare-repo file, or SSH-reachable bare-repo file). description_sync.go previously supported exactly these three mechanisms via an if/else cascade over org fields (org.IsForgejo(), a "file://" host prefix, or org.DescriptionSyncHost/Root); each mechanism is now its own implementation of this interface instead of a branch in one function.

supported reports whether org is configured for this writer's mechanism at all, independent of whether the write itself succeeded - callers use it to fall through to the next writer in the list (see SyncRepoDescriptions), matching the original cascade's behavior where an org matching no known mechanism was silently skipped.

type FileBackupDescriptionWriter

type FileBackupDescriptionWriter struct{}

FileBackupDescriptionWriter writes the canonical description to a local bare repository's "description" file. It applies to organizations whose Host is a "file://" URL - i.e. a local-filesystem backup location.

func (FileBackupDescriptionWriter) WriteBackupDescription

func (FileBackupDescriptionWriter) WriteBackupDescription(org *config.Organization, repoName, description string, dryRun bool) (bool, error)

WriteBackupDescription implements BackupDescriptionWriter.

type ForgeClientResolver

type ForgeClientResolver interface {
	ClientFor(org *config.Organization) (forge.RepoDescriptionClient, bool)
}

ForgeClientResolver builds the forge.RepoDescriptionClient used to read and update a repository's canonical description on GitHub/Codeberg/Forgejo. internal/cli's ForgeClientResolver (the composition root's single client construction point, see forge_client.go) satisfies this structurally, so this package never imports the concrete github/codeberg packages.

type ForgejoBackupDescriptionWriter

type ForgejoBackupDescriptionWriter struct {
	NewClient ForgejoClientFactory
}

ForgejoBackupDescriptionWriter writes the canonical description to a Forgejo/Gitea instance's repository-description API. It only applies to organizations configured as Forgejo backup targets (org.IsForgejo()).

func (ForgejoBackupDescriptionWriter) WriteBackupDescription

func (w ForgejoBackupDescriptionWriter) WriteBackupDescription(org *config.Organization, repoName, description string, dryRun bool) (bool, error)

WriteBackupDescription implements BackupDescriptionWriter.

type ForgejoClientFactory

type ForgejoClientFactory func(org *config.Organization) ForgejoDescriptionClient

ForgejoClientFactory builds a ForgejoDescriptionClient for a Forgejo backup organization. internal/cli (the composition root) injects a factory built from codeberg.NewForgejoClient; this package depends only on the factory signature and the ForgejoDescriptionClient interface it returns, matching the abstraction boundary forge.PublicRepoEnsurer already established for internal/sync's own Forgejo backup bootstrapping (SetForgejoBackupClientFactory).

type ForgejoDescriptionClient

type ForgejoDescriptionClient interface {
	HasToken() bool
	UpdateRepoDescription(repoName, description string) error
}

ForgejoDescriptionClient is the narrow capability ForgejoBackupDescriptionWriter needs from a forge client: checking whether a token is configured and updating a repository's description over the Forgejo/Gitea API. codeberg.Client (constructed via codeberg.NewForgejoClient) satisfies this structurally, but this package never imports the codeberg package itself - see ForgejoClientFactory.

type SSHBackupDescriptionWriter

type SSHBackupDescriptionWriter struct{}

SSHBackupDescriptionWriter writes the canonical description to a bare repository's "description" file on a remote host reachable over SSH. It applies to organizations that configure both DescriptionSyncHost (the SSH host with shell access) and DescriptionSyncRoot (the filesystem path on that host where bare repos live).

func (SSHBackupDescriptionWriter) WriteBackupDescription

func (SSHBackupDescriptionWriter) WriteBackupDescription(org *config.Organization, repoName, description string, dryRun bool) (bool, error)

WriteBackupDescription implements BackupDescriptionWriter.