install

package
v0.8.7 Latest Latest
Warning

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

 Go to latest Published: Feb 25, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// UpgradeRenameConfidenceHigh is emitted when rename detection is a unique exact content match.
	UpgradeRenameConfidenceHigh = "high"
	// UpgradeRenameDetectionUniqueExactHash identifies rename detection by unique exact normalized hash.
	UpgradeRenameDetectionUniqueExactHash = "unique_exact_normalized_hash"
	// UpgradePlanSchemaVersion is the JSON schema version for `al upgrade plan` output.
	UpgradePlanSchemaVersion = 1
)
View Source 
const (
	// DefaultDiffMaxLines is the default maximum number of diff lines shown per file.
	DefaultDiffMaxLines = 40
)

Variables

This section is empty.

Functions

func BuildUpgradePlanDiffPreviews added in v0.8.0 

func BuildUpgradePlanDiffPreviews(root string, plan UpgradePlan, opts UpgradePlanDiffPreviewOptions) (map[string]DiffPreview, error)

BuildUpgradePlanDiffPreviews builds line-level diff previews for upgrade-plan text rendering.

func EnsureGitignore added in v0.6.1 

func EnsureGitignore(sys GitignoreSystem, path string, block string) error

EnsureGitignore updates or creates a .gitignore file with the given block. It merges the block into existing content, replacing any previous agent-layer block. The block should contain only the template content (ignore patterns and comments); managed markers and headers are added automatically.

func RepairGitignoreBlock added in v0.8.0 

func RepairGitignoreBlock(root string, opts RepairGitignoreBlockOptions) error

RepairGitignoreBlock rewrites `.agent-layer/gitignore.block` from embedded templates and then reapplies the managed block to the repository root `.gitignore`.

func RollbackUpgradeSnapshot added in v0.8.0 

func RollbackUpgradeSnapshot(root string, snapshotID string, opts RollbackUpgradeSnapshotOptions) error

RollbackUpgradeSnapshot restores a previously captured managed-file snapshot by ID.

func Run 

func Run(root string, opts Options) error

Run initializes the repository with the required Agent Layer structure.

func ValidateGitignoreBlock added in v0.6.1 

func ValidateGitignoreBlock(block string, blockPath string) (string, error)

ValidateGitignoreBlock normalizes and validates a gitignore block template. It returns the normalized block or an error if managed markers or a template hash are present.

Types

type BaselineStateSource added in v0.8.0 

type BaselineStateSource string

BaselineStateSource identifies where baseline ownership evidence came from. 

const (
	// BaselineStateSourceWrittenByInit indicates baseline was captured by a successful init write flow.
	BaselineStateSourceWrittenByInit BaselineStateSource = "written_by_init"
	// BaselineStateSourceWrittenByUpgrade indicates baseline was captured by an upgrade write flow.
	BaselineStateSourceWrittenByUpgrade BaselineStateSource = "written_by_overwrite"
	// BaselineStateSourceWrittenByOverwrite is a legacy name for BaselineStateSourceWrittenByUpgrade.
	BaselineStateSourceWrittenByOverwrite BaselineStateSource = BaselineStateSourceWrittenByUpgrade
	// BaselineStateSourceInferredFromPinManifest indicates baseline was inferred from a pinned release manifest.
	BaselineStateSourceInferredFromPinManifest BaselineStateSource = "inferred_from_pin_manifest"
	// BaselineStateSourceMigratedFromLegacyDocsSnapshot indicates baseline was inferred from legacy docs snapshot files.
	BaselineStateSourceMigratedFromLegacyDocsSnapshot BaselineStateSource = "migrated_from_legacy_docs_snapshot"
)

type ConfigKeyMigration added in v0.8.0 

type ConfigKeyMigration struct {
	Key  string `json:"key"`
	From string `json:"from"`
	To   string `json:"to"`
}

ConfigKeyMigration is reserved for explicit config migrations.

type DiffPreview added in v0.8.0 

type DiffPreview struct {
	Path        string
	Ownership   OwnershipLabel
	UnifiedDiff string
	Truncated   bool
}

DiffPreview is a user-facing, per-file diff preview used by upgrade prompts and plans.

type GitignoreSystem added in v0.6.1 

type GitignoreSystem interface {
	ReadFile(name string) ([]byte, error)
	WriteFileAtomic(filename string, data []byte, perm os.FileMode) error
}

GitignoreSystem is the minimal interface needed for gitignore operations.

type LabeledPath added in v0.8.0 

type LabeledPath struct {
	Path      string
	Ownership OwnershipLabel
}

LabeledPath is a path paired with an ownership label.

type MatchTemplateFunc added in v0.5.7 

type MatchTemplateFunc func(sys System, path string, templatePath string, info fs.FileInfo) (bool, error)

MatchTemplateFunc compares a destination file to a template.

type Options 

type Options struct {
	Overwrite    bool
	Prompter     Prompter
	WarnWriter   io.Writer
	PinVersion   string
	DiffMaxLines int
	System       System
}

Options controls installer behavior.

type OwnershipConfidence added in v0.8.0 

type OwnershipConfidence string

OwnershipConfidence is the certainty level for ownership classification evidence. 

const (
	// OwnershipConfidenceHigh indicates canonical baseline evidence.
	OwnershipConfidenceHigh OwnershipConfidence = "high"
	// OwnershipConfidenceMedium indicates inferred baseline evidence (for example pinned manifest).
	OwnershipConfidenceMedium OwnershipConfidence = "medium"
	// OwnershipConfidenceLow indicates legacy snapshot migration bridge evidence.
	OwnershipConfidenceLow OwnershipConfidence = "low"
)

type OwnershipLabel added in v0.8.0 

type OwnershipLabel string

OwnershipLabel classifies why a managed file differs from the embedded template. 

const (
	// OwnershipUpstreamTemplateDelta indicates a file differs because upstream template content changed.
	OwnershipUpstreamTemplateDelta OwnershipLabel = "upstream template delta"
	// OwnershipLocalCustomization indicates a file differs because local edits/customization are present.
	OwnershipLocalCustomization OwnershipLabel = "local customization"
	// OwnershipMixedUpstreamAndLocal indicates both upstream template changes and local customization are present.
	OwnershipMixedUpstreamAndLocal OwnershipLabel = "mixed upstream and local"
	// OwnershipUnknownNoBaseline indicates ownership cannot be classified due to missing baseline evidence.
	OwnershipUnknownNoBaseline OwnershipLabel = "unknown no baseline"
)

func (OwnershipLabel) Display added in v0.8.0 

func (o OwnershipLabel) Display() string

Display returns a stable user-facing ownership label string.

func (OwnershipLabel) State added in v0.8.0 

func (o OwnershipLabel) State() OwnershipState

State returns a stable machine-readable ownership enum for JSON output.

type OwnershipState added in v0.8.0 

type OwnershipState string

OwnershipState is the machine-readable ownership enum for upgrade-plan JSON. 

const (
	// OwnershipStateUpstreamTemplateDelta is used when a change is attributable to upstream template changes.
	OwnershipStateUpstreamTemplateDelta OwnershipState = "upstream_template_delta"
	// OwnershipStateLocalCustomization is used when a change is attributable to local customization.
	OwnershipStateLocalCustomization OwnershipState = "local_customization"
	// OwnershipStateMixedUpstreamAndLocal is used when both upstream and local changes are present.
	OwnershipStateMixedUpstreamAndLocal OwnershipState = "mixed_upstream_and_local"
	// OwnershipStateUnknownNoBaseline is used when ownership cannot be determined due to missing baseline.
	OwnershipStateUnknownNoBaseline OwnershipState = "unknown_no_baseline"
)

type PromptConfigSetDefaultFunc added in v0.8.2 

type PromptConfigSetDefaultFunc func(key string, manifestValue any, rationale string, field *config.FieldDef) (any, error)

PromptConfigSetDefaultFunc asks the user to confirm or customize a value for a missing required config key. It receives the key path, a default value from the migration manifest, a rationale string, and an optional field definition from the config catalog (nil when the key is not in the catalog). It returns the value to set (which may differ from the manifest value). When nil, the manifest value is used without prompting.

type PromptDeleteUnknownAllFunc added in v0.5.4 

type PromptDeleteUnknownAllFunc func(paths []string) (bool, error)

PromptDeleteUnknownAllFunc asks whether to delete all unknown paths.

type PromptDeleteUnknownFunc added in v0.5.4 

type PromptDeleteUnknownFunc func(path string) (bool, error)

PromptDeleteUnknownFunc asks whether to delete a specific unknown path.

type PromptFuncs added in v0.5.7 

type PromptFuncs struct {
	OverwriteAllPreviewFunc        PromptOverwriteAllPreviewFunc
	OverwriteAllMemoryPreviewFunc  PromptOverwriteAllPreviewFunc
	OverwriteAllUnifiedPreviewFunc PromptOverwriteAllUnifiedPreviewFunc
	OverwritePreviewFunc           PromptOverwritePreviewFunc
	DeleteUnknownAllFunc           PromptDeleteUnknownAllFunc
	DeleteUnknownFunc              PromptDeleteUnknownFunc
	ConfigSetDefaultFunc           PromptConfigSetDefaultFunc
}

PromptFuncs adapts optional prompt callbacks into a Prompter.

func (PromptFuncs) ConfigSetDefault added in v0.8.2 

func (p PromptFuncs) ConfigSetDefault(key string, manifestValue any, rationale string, field *config.FieldDef) (any, error)

ConfigSetDefault prompts the user to confirm or customize a default value for a missing config key. Returns the manifest value when no callback is set.

func (PromptFuncs) DeleteUnknown added in v0.5.7 

func (p PromptFuncs) DeleteUnknown(path string) (bool, error)

DeleteUnknown prompts the user to confirm deleting a single unknown path. Returns an error if no DeleteUnknownFunc is configured.

func (PromptFuncs) DeleteUnknownAll added in v0.5.7 

func (p PromptFuncs) DeleteUnknownAll(paths []string) (bool, error)

DeleteUnknownAll prompts the user to confirm deleting all unknown paths. Returns an error if no DeleteUnknownAllFunc is configured.

func (PromptFuncs) Overwrite added in v0.5.7 

func (p PromptFuncs) Overwrite(preview DiffPreview) (bool, error)

Overwrite prompts the user to confirm overwriting a single path. Returns an error if no Overwrite callback is configured.

func (PromptFuncs) OverwriteAll added in v0.5.7 

func (p PromptFuncs) OverwriteAll(previews []DiffPreview) (bool, error)

OverwriteAll prompts the user to confirm overwriting all given paths. Returns an error if no overwrite callback is configured.

func (PromptFuncs) OverwriteAllMemory added in v0.5.7 

func (p PromptFuncs) OverwriteAllMemory(previews []DiffPreview) (bool, error)

OverwriteAllMemory prompts the user to confirm overwriting all memory file paths. Returns an error if no OverwriteAll callback is configured.

func (PromptFuncs) OverwriteAllUnified added in v0.8.0 

func (p PromptFuncs) OverwriteAllUnified(managed []DiffPreview, memory []DiffPreview) (bool, bool, error)

OverwriteAllUnified prompts for managed and memory overwrite-all decisions in one pass. Returns an error if no unified callback is configured.

type PromptOverwriteAllPreviewFunc added in v0.8.0 

type PromptOverwriteAllPreviewFunc func(previews []DiffPreview) (bool, error)

PromptOverwriteAllPreviewFunc asks whether to overwrite all paths in a diff preview batch.

type PromptOverwriteAllUnifiedPreviewFunc added in v0.8.0 

type PromptOverwriteAllUnifiedPreviewFunc func(managed []DiffPreview, memory []DiffPreview) (bool, bool, error)

PromptOverwriteAllUnifiedPreviewFunc asks whether to apply managed and memory updates in one pass.

type PromptOverwriteFunc 

type PromptOverwriteFunc func(path string) (bool, error)

PromptOverwriteFunc asks whether to overwrite a given path.

type PromptOverwritePreviewFunc added in v0.8.0 

type PromptOverwritePreviewFunc func(preview DiffPreview) (bool, error)

PromptOverwritePreviewFunc asks whether to overwrite a single diff preview path.

type Prompter added in v0.5.7 

type Prompter interface {
	OverwriteAll(previews []DiffPreview) (bool, error)
	OverwriteAllMemory(previews []DiffPreview) (bool, error)
	Overwrite(preview DiffPreview) (bool, error)
	DeleteUnknownAll(paths []string) (bool, error)
	DeleteUnknown(path string) (bool, error)
}

Prompter provides user prompts for overwrite and delete decisions.

type RealSystem added in v0.5.7 

type RealSystem struct{}

RealSystem implements System using the OS filesystem.

func (RealSystem) LookupEnv added in v0.8.0 

func (RealSystem) LookupEnv(key string) (string, bool)

LookupEnv returns the value and presence of an environment variable.

func (RealSystem) Lstat added in v0.8.7 

func (RealSystem) Lstat(name string) (os.FileInfo, error)

Lstat returns a FileInfo describing the named file without following symlinks.

func (RealSystem) MkdirAll added in v0.5.7 

func (RealSystem) MkdirAll(path string, perm os.FileMode) error

MkdirAll creates a directory named path, along with any necessary parents.

func (RealSystem) ReadFile added in v0.5.7 

func (RealSystem) ReadFile(name string) ([]byte, error)

ReadFile reads the named file and returns the contents. 

func (RealSystem) Readlink(name string) (string, error)

Readlink returns the destination of a symbolic link.

func (RealSystem) RemoveAll added in v0.5.7 

func (RealSystem) RemoveAll(path string) error

RemoveAll removes path and any children it contains.

func (RealSystem) Rename added in v0.8.0 

func (RealSystem) Rename(oldpath string, newpath string) error

Rename renames (moves) oldpath to newpath.

func (RealSystem) Stat added in v0.5.7 

func (RealSystem) Stat(name string) (os.FileInfo, error)

Stat returns a FileInfo describing the named file. 

func (RealSystem) Symlink(oldname string, newname string) error

Symlink creates newname as a symbolic link to oldname.

func (RealSystem) WalkDir added in v0.5.7 

func (RealSystem) WalkDir(root string, fn fs.WalkDirFunc) error

WalkDir walks the file tree rooted at root.

func (RealSystem) WriteFileAtomic added in v0.5.7 

func (RealSystem) WriteFileAtomic(filename string, data []byte, perm os.FileMode) error

WriteFileAtomic writes data to a file atomically by writing to a temp file and renaming.

type RepairGitignoreBlockOptions added in v0.8.0 

type RepairGitignoreBlockOptions struct {
	System System
}

RepairGitignoreBlockOptions controls gitignore-block repair behavior.

type RollbackUpgradeSnapshotOptions added in v0.8.0 

type RollbackUpgradeSnapshotOptions struct {
	System System
}

RollbackUpgradeSnapshotOptions controls manual rollback behavior.

type System added in v0.5.7 

type System interface {
	Lstat(name string) (os.FileInfo, error)
	Stat(name string) (os.FileInfo, error)
	ReadFile(name string) ([]byte, error)
	Readlink(name string) (string, error)
	LookupEnv(key string) (string, bool)
	MkdirAll(path string, perm os.FileMode) error
	RemoveAll(path string) error
	Rename(oldpath string, newpath string) error
	Symlink(oldname string, newname string) error
	WalkDir(root string, fn fs.WalkDirFunc) error
	WriteFileAtomic(filename string, data []byte, perm os.FileMode) error
}

System abstracts filesystem operations needed by the installer. This interface is intentionally package-local per Decision edefea6 to enable parallel-safe unit tests without shared global state. Other packages (dispatch, sync) define their own System interfaces with operations specific to their needs.

type UpgradeChange added in v0.8.0 

type UpgradeChange struct {
	Path                    string               `json:"path"`
	Ownership               OwnershipLabel       `json:"ownership"`
	OwnershipState          OwnershipState       `json:"ownership_state"`
	OwnershipConfidence     *OwnershipConfidence `json:"ownership_confidence,omitempty"`
	OwnershipBaselineSource *BaselineStateSource `json:"ownership_baseline_source,omitempty"`
	OwnershipReasonCodes    []string             `json:"ownership_reason_codes,omitempty"`
}

UpgradeChange describes a single template delta entry.

type UpgradeMigrationEntry added in v0.8.0 

type UpgradeMigrationEntry struct {
	ID             string                 `json:"id"`
	Kind           string                 `json:"kind"`
	Rationale      string                 `json:"rationale"`
	SourceAgnostic bool                   `json:"source_agnostic"`
	Status         UpgradeMigrationStatus `json:"status"`
	SkipReason     string                 `json:"skip_reason,omitempty"`
	From           string                 `json:"from,omitempty"`
	To             string                 `json:"to,omitempty"`
	Path           string                 `json:"path,omitempty"`
	Key            string                 `json:"key,omitempty"`
	Value          json.RawMessage        `json:"value,omitempty"`
}

UpgradeMigrationEntry is a deterministic migration-plan/apply record.

type UpgradeMigrationReport added in v0.8.0 

type UpgradeMigrationReport struct {
	TargetVersion         string                       `json:"target_version,omitempty"`
	MinPriorVersion       string                       `json:"min_prior_version,omitempty"`
	ManifestPath          string                       `json:"manifest_path,omitempty"`
	SourceVersion         string                       `json:"source_version"`
	SourceVersionOrigin   UpgradeMigrationSourceOrigin `json:"source_version_origin"`
	SourceResolutionNotes []string                     `json:"source_resolution_notes,omitempty"`
	Entries               []UpgradeMigrationEntry      `json:"entries"`
}

UpgradeMigrationReport contains deterministic migration planning/execution data for upgrade output.

type UpgradeMigrationSourceOrigin added in v0.8.0 

type UpgradeMigrationSourceOrigin string

UpgradeMigrationSourceOrigin identifies where migration source-version evidence came from. 

const (
	// UpgradeMigrationSourceUnknown means source version could not be determined.
	UpgradeMigrationSourceUnknown UpgradeMigrationSourceOrigin = "unknown"
	// UpgradeMigrationSourcePin means source version came from .agent-layer/al.version.
	UpgradeMigrationSourcePin UpgradeMigrationSourceOrigin = "pin_file"
	// UpgradeMigrationSourceBaseline means source version came from managed baseline state.
	UpgradeMigrationSourceBaseline UpgradeMigrationSourceOrigin = "managed_baseline"
	// UpgradeMigrationSourceSnapshot means source version came from latest upgrade snapshot pin entry.
	UpgradeMigrationSourceSnapshot UpgradeMigrationSourceOrigin = "upgrade_snapshot"
	// UpgradeMigrationSourceManifestMatch means source version was inferred from embedded manifest fingerprint matching.
	UpgradeMigrationSourceManifestMatch UpgradeMigrationSourceOrigin = "manifest_match"
)

type UpgradeMigrationStatus added in v0.8.0 

type UpgradeMigrationStatus string

UpgradeMigrationStatus describes migration execution/planning status. 

const (
	// UpgradeMigrationStatusPlanned means migration is eligible to run.
	UpgradeMigrationStatusPlanned UpgradeMigrationStatus = "planned"
	// UpgradeMigrationStatusApplied means migration mutated repository state during apply.
	UpgradeMigrationStatusApplied UpgradeMigrationStatus = "applied"
	// UpgradeMigrationStatusNoop means migration ran but made no changes (already migrated/idempotent).
	UpgradeMigrationStatusNoop UpgradeMigrationStatus = "no_op"
	// UpgradeMigrationStatusSkippedUnknownSource means migration requires a known source version but source is unknown.
	UpgradeMigrationStatusSkippedUnknownSource UpgradeMigrationStatus = "skipped_unknown_source"
	// UpgradeMigrationStatusSkippedSourceTooOld means migration requires a newer prior version than the resolved source.
	UpgradeMigrationStatusSkippedSourceTooOld UpgradeMigrationStatus = "skipped_source_too_old"
)

type UpgradePinAction added in v0.8.0 

type UpgradePinAction string

UpgradePinAction identifies the pin transition kind in an upgrade plan. 

const (
	// UpgradePinActionNone means the current pin already matches the target pin.
	UpgradePinActionNone UpgradePinAction = "none"
	// UpgradePinActionSet means the repo currently has no pin and the plan sets one.
	UpgradePinActionSet UpgradePinAction = "set"
	// UpgradePinActionUpdate means the repo pin changes from one value to another.
	UpgradePinActionUpdate UpgradePinAction = "update"
	// UpgradePinActionRemove means the repo pin is removed for the target.
	UpgradePinActionRemove UpgradePinAction = "remove"
)

type UpgradePinVersionDiff added in v0.8.0 

type UpgradePinVersionDiff struct {
	Current string           `json:"current"`
	Target  string           `json:"target"`
	Action  UpgradePinAction `json:"action"`
}

UpgradePinVersionDiff captures current->target pin movement for upgrade planning.

type UpgradePlan added in v0.8.0 

type UpgradePlan struct {
	SchemaVersion             int                     `json:"schema_version"`
	DryRun                    bool                    `json:"dry_run"`
	TemplateAdditions         []UpgradeChange         `json:"template_additions"`
	TemplateUpdates           []UpgradeChange         `json:"template_updates"`
	SectionAwareUpdates       []UpgradeChange         `json:"section_aware_updates"`
	TemplateRenames           []UpgradeRename         `json:"template_renames"`
	TemplateRemovalsOrOrphans []UpgradeChange         `json:"template_removals_or_orphans"`
	ConfigKeyMigrations       []ConfigKeyMigration    `json:"config_key_migrations"`
	MigrationReport           UpgradeMigrationReport  `json:"migration_report"`
	PinVersionChange          UpgradePinVersionDiff   `json:"pin_version_change"`
	ReadinessChecks           []UpgradeReadinessCheck `json:"readiness_checks"`
}

UpgradePlan is the machine-readable output of `al upgrade plan`.

func BuildUpgradePlan added in v0.8.0 

func BuildUpgradePlan(root string, opts UpgradePlanOptions) (UpgradePlan, error)

BuildUpgradePlan computes a dry-run upgrade plan against the running binary's embedded templates.

type UpgradePlanDiffPreviewOptions added in v0.8.0 

type UpgradePlanDiffPreviewOptions struct {
	System       System
	MaxDiffLines int
}

UpgradePlanDiffPreviewOptions controls diff preview generation for upgrade plan rendering.

type UpgradePlanOptions added in v0.8.0 

type UpgradePlanOptions struct {
	TargetPinVersion string
	System           System
}

UpgradePlanOptions controls dry-run plan generation.

type UpgradeReadinessCheck added in v0.8.0 

type UpgradeReadinessCheck struct {
	ID      string   `json:"id"`
	Summary string   `json:"summary"`
	Details []string `json:"details"`
}

UpgradeReadinessCheck captures a non-fatal pre-upgrade readiness finding for text output.

type UpgradeRename added in v0.8.0 

type UpgradeRename struct {
	From                    string               `json:"from"`
	To                      string               `json:"to"`
	Ownership               OwnershipLabel       `json:"ownership"`
	OwnershipState          OwnershipState       `json:"ownership_state"`
	OwnershipConfidence     *OwnershipConfidence `json:"ownership_confidence,omitempty"`
	OwnershipBaselineSource *BaselineStateSource `json:"ownership_baseline_source,omitempty"`
	OwnershipReasonCodes    []string             `json:"ownership_reason_codes,omitempty"`
	Confidence              string               `json:"confidence"`
	Detection               string               `json:"detection"`
}

UpgradeRename describes a rename detected by the dry-run planner.

type UpgradeSnapshotMetadata added in v0.8.5 

type UpgradeSnapshotMetadata struct {
	ID           string
	CreatedAtUTC string
	Status       string
}

UpgradeSnapshotMetadata provides lightweight snapshot listing fields.

func ListUpgradeSnapshots added in v0.8.5 

func ListUpgradeSnapshots(root string, sys System) ([]UpgradeSnapshotMetadata, error)

ListUpgradeSnapshots returns metadata for all available upgrade snapshots, sorted by creation time (newest first).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.