staging

package
v0.14.4-dev.47 Latest Latest
Warning

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

Go to latest
Published: Nov 21, 2026 License: MIT Imports: 33 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AcquireLaunchShared

func AcquireLaunchShared(projectRoot, modeName string) (*flock.Flock, error)

AcquireLaunchShared holds a shared lock while a harness process uses staging.

func AcquirePublisher added in v0.7.3

func AcquirePublisher(ctx context.Context, projectRoot, modeName string) (*flock.Flock, error)

AcquirePublisher serializes builders, not the sessions using published files.

func ApplyDotAgentsPlan added in v0.9.0

func ApplyDotAgentsPlan(plan DotAgentsPlan, claudeBundle, codexHome string) error

func ApplyMCPPluginPlan added in v0.9.0

func ApplyMCPPluginPlan(plan MCPPluginPlan) error

func ApplyPackageTreePlan added in v0.9.0

func ApplyPackageTreePlan(plan PackageTreePlan, roots []HarnessRoot) error

ApplyPackageTreePlan verifies source integrity before writing the planned bytes.

func CollectGuidance

func CollectGuidance(projectRoot string, lock lockfile.PackLock, effective mode.Effective) (string, error)

func CollectLSP

func CollectLSP(lock lockfile.PackLock, effective *mode.Effective) (map[string]LSPEntry, error)

CollectLSP gathers the language servers that plugins declare, in Claude Code's format (name -> {command, args, extensionToLanguage, ...}): a .lsp.json at the plugin root, then each plugin.json's lspServers, as a path or inline. A later definition of the same server name wins, as for MCP.

func CollectMCP

func CollectMCP(projectRoot string, lock lockfile.PackLock, projectManifest *manifest.Manifest, effective *mode.Effective) (mcp.Entries, error)

CollectMCP applies the canonical precedence: plugins, manifest, then .agents.

func MarkProjectDirectories

func MarkProjectDirectories(projectRoot string)

MarkProjectDirectories records the project's path in the directories its staging lives in outside $AGENTPACK_HOME: the staging tree and the Codex homes. Every rebuild does this, so that the directories can be recognised as left over once the project is deleted.

func OmitProjectClaudeSkillDuplicates

func OmitProjectClaudeSkillDuplicates(projectRoot, bundle string) error

OmitProjectClaudeSkillDuplicates removes staged plugin skills whose names are already provided by project .claude/skills. Claude Code discovers both locations, and the project definition wins on a name collision. Full-tree hashes distinguish exact mirrored copies from same-name overrides while preserving different skill names even when their contents match.

func PlanLSPRoots added in v0.9.0

func PlanLSPRoots(projectRoot, modeName string, entries map[string]LSPEntry) (map[string]json.RawMessage, error)

PlanLSPRoots performs the path substitutions without copying files or creating data directories, so preflight can render the same target config.

func ProjectClaudeSkillNames

func ProjectClaudeSkillNames(projectRoot string) (map[string]struct{}, error)

ProjectClaudeSkillNames returns the case-insensitive names of skills Claude Code discovers directly from the project.

func ProjectSkillNames

func ProjectSkillNames(projectRoot, root string) (map[string]struct{}, error)

ProjectSkillNames returns the case-insensitive names of skills under a project-relative skill root such as .agents/skills.

func RemoveOrphanedProjectDirectories

func RemoveOrphanedProjectDirectories(projectRoot string)

RemoveOrphanedProjectDirectories removes what deleted projects left behind: /tmp/agentpack-<hash> staging trees and the Codex homes under /var/tmp/ap-c. Only a directory that agentpack marked, and whose project directory no longer exists, is removed; a Codex home that a running session still holds is left for a later run. Failures are ignored: tidying never fails a sync.

func ResolveCollisions added in v0.8.6

func ResolveCollisions(bundle, target string, userRoots []string) (map[string]struct{}, error)

ResolveCollisions removes duplicates only from this target's staged bundle. The returned native names also allow verification after a prior collision pass.

func SkillFolderName

func SkillFolderName(pkg lockfile.Package) string

func SkillIsShadowed

func SkillIsShadowed(skill lockfile.Package, plugins []lockfile.Package) bool

func StageDotAgents

func StageDotAgents(definitionRoot, workspaceRoot, modeName string, effective mode.Effective, codex string, target *harness.Target) error

func TryAcquireRebuildExclusive

func TryAcquireRebuildExclusive(projectRoot, modeName string) (*flock.Flock, error)

TryAcquireRebuildExclusive fails when a launch still holds the shared lock.

func UserSkillNames added in v0.8.6

func UserSkillNames(userRoots []string) (map[string]struct{}, error)

UserSkillNames lists skills in the supplied native user artifact roots.

Types

type ClaudeSkillsReport

type ClaudeSkillsReport struct {
	CopiedToClaude []string
	CopiedToAgents []string
	Updated        []ClaudeSkillsUpdate
	InSync         []string
}

ClaudeSkillsReport summarizes a reconciliation between a project's .claude/skills and .agents/skills directories.

func ReconcileClaudeSkills

func ReconcileClaudeSkills(projectRoot string, dryRun bool) (ClaudeSkillsReport, error)

ReconcileClaudeSkills makes a project's .claude/skills and .agents/skills directories hold the same local skills. Claude Code only discovers project-local skills under .claude/skills, while the dot-agents convention shares project-local content across every harness under .agents/skills; a skill authored under either one is copied so both sides end up identical. When a skill exists on both sides with differing content, the copy with the newer file modification time wins. dryRun reports what would change without touching the filesystem.

type ClaudeSkillsUpdate

type ClaudeSkillsUpdate struct {
	Name   string
	Winner string // "claude" or "agents"
}

ClaudeSkillsUpdate records a local skill whose two copies had diverged and were reconciled to the newer side.

type ConvertedNames

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

ConvertedNames names the skills that a package's commands, agents and rules become on a target without those kinds. An item keeps its own name when it is free; otherwise it gets the name followed by its kind (review-command), then by a number. Items must be offered in staging order.

func NewConvertedNames

func NewConvertedNames(skills map[string]string) *ConvertedNames

NewConvertedNames takes the package's own skills, by storage name.

func (*ConvertedNames) For

func (names *ConvertedNames) For(artifact *artifacts.Markdown, target harness.Target) artifacts.Markdown

For returns the artifact as it is staged for target.

type DotAgentsArtifact added in v0.9.0

type DotAgentsArtifact struct {
	Target         harness.Target
	SourceRelative string
	Source         []byte
	Parsed         *artifacts.Markdown
	Kind           artifacts.Kind
	Name           string
	OutputPath     string
	Output         []byte
	NativeSource   string
	Omitted        bool
	Reason         string
}

type DotAgentsFile added in v0.9.0

type DotAgentsFile struct {
	Target         harness.Target
	SourcePath     string
	SourceRelative string
	RelativePath   string
	Contents       []byte
	HardLink       bool
}

type DotAgentsPlan added in v0.9.0

type DotAgentsPlan struct {
	SourceRoot   string
	SourceDigest string
	Files        []DotAgentsFile
	Artifacts    []DotAgentsArtifact
	Warnings     []string
}

func PlanDotAgents added in v0.9.0

func PlanDotAgents(dotRoot string, effective mode.Effective, target *harness.Target) (DotAgentsPlan, error)

PlanDotAgents computes every dot-agents overlay write in staging order. Codex skills are returned as native discoveries and never as staged files.

func (DotAgentsPlan) Validate added in v0.9.0

func (plan DotAgentsPlan) Validate() error

Validate ensures workspace inputs still match the plan before its staging generation is published.

type DriftError

type DriftError struct{ Changes []string }

DriftError lists staged files that differ from what the last sync wrote.

func (*DriftError) Details

func (err *DriftError) Details() string

func (*DriftError) Error

func (err *DriftError) Error() string

func (*DriftError) Summary

func (err *DriftError) Summary() string

type HarnessRoot

type HarnessRoot struct {
	Target harness.Target
	Path   string
}

type LSPCollectionPlan added in v0.9.0

type LSPCollectionPlan struct {
	Entries  map[string]LSPEntry
	Warnings []LSPCollectionWarning
}

func CollectLSPPlan added in v0.9.0

func CollectLSPPlan(lock lockfile.PackLock, effective *mode.Effective) (LSPCollectionPlan, error)

type LSPCollectionWarning added in v0.9.0

type LSPCollectionWarning struct{ Source, Message string }

type LSPEntry

type LSPEntry struct {
	Server   json.RawMessage
	Module   string
	CacheKey string
}

LSPEntry is one language server and the package that declares it.

type MCPCollectionPlan added in v0.9.0

type MCPCollectionPlan struct {
	Entries  mcp.Entries
	Warnings []MCPCollectionWarning
}

func CollectMCPPlan added in v0.9.0

func CollectMCPPlan(projectRoot string, lock lockfile.PackLock, projectManifest *manifest.Manifest, effective *mode.Effective) (MCPCollectionPlan, error)

type MCPCollectionWarning added in v0.9.0

type MCPCollectionWarning struct{ Source, Message string }

type MCPPluginPlan added in v0.9.0

type MCPPluginPlan struct {
	Entries     mcp.Entries
	Files       []PlannedMCPPluginFile
	Roots       []string
	DataDirs    []string
	Directories []string
	Sources     []MCPPluginSource
}

func PlanMCPPluginRoots added in v0.9.0

func PlanMCPPluginRoots(projectRoot, modeName string, effective mode.Effective, entries mcp.Entries) (MCPPluginPlan, error)

func (MCPPluginPlan) Validate added in v0.9.0

func (plan MCPPluginPlan) Validate() error

type MCPPluginSource added in v0.9.0

type MCPPluginSource struct{ Root, Digest, Module string }

type PackageFile

type PackageFile struct {
	Path    string
	Virtual string
	Real    string
}

PackageFile is one file of a cached package as staging sees it. Virtual is where the file sits in the package's canonical layout (skills/<name>/…, commands/…); Real is its actual path in the cache entry, which mode selectors are written against. The two differ for a file reached through a symbolic link or through a component path a plugin manifest declares.

func PackageFiles

func PackageFiles(sourceRoot, module string, plugin bool) ([]PackageFile, error)

PackageFiles lists the files of a cache entry. A plugin gets its tree as it is, the symbolic links under its component directories followed, and the component paths its manifests declare; a bare skill gets its whole tree with links followed. A link or a declared path that leaves the package is skipped with a warning that names it.

type PackageTreePlan added in v0.9.0

type PackageTreePlan struct {
	SourceRoot   string
	SourceDigest string
	Artifacts    []PlannedArtifact
	Files        []PlannedPackageFile
	Warnings     []string
}

PackageTreePlan is the parsed package view consumed by staging and preflight. Files contain the exact bytes to publish, so planning never rereads a source after reporting its generated output.

func PlanPackageTree added in v0.9.0

func PlanPackageTree(sourceRoot, module, bareSkillName string, effective mode.Effective, roots []HarnessRoot, plugin bool) (PackageTreePlan, error)

PlanPackageTree reads a package once, applies mode filtering and target rendering, and returns the files that staging would publish. Plugin support files are included when plugin is true.

func StagePackOverlay

func StagePackOverlay(lock lockfile.PackLock, roots []HarnessRoot, effective mode.Effective) ([]PackageTreePlan, error)

func (PackageTreePlan) Validate added in v0.9.0

func (plan PackageTreePlan) Validate() error

Validate also detects newly added files and changed package manifests or links.

type Pipeline

type Pipeline struct {
	// ProjectRoot is the definition root (manifest, lock, staging identity).
	ProjectRoot string
	// WorkspaceRoot is the checkout for .agents inputs; empty means ProjectRoot.
	WorkspaceRoot string
	Lock          lockfile.PackLock
	Manifest      *manifest.Manifest
	Mode          mode.Effective
	Target        *base.Target
	// StrictExternal refuses workspace overlay materialization.
	StrictExternal bool
	// Info receives lines that report what staging did and need no action,
	// such as how each hook was rendered. Nil drops them.
	Info func(message string)
}

func (Pipeline) HookDiagnostics

func (pipeline Pipeline) HookDiagnostics() ([]hooks.Diagnostic, hooks.RenderSummary, error)

HookDiagnostics returns renderer findings without writing hook files.

func (Pipeline) Rebuild

func (pipeline Pipeline) Rebuild() (_ []string, rebuildErr error)

func (Pipeline) RebuildPending

func (pipeline Pipeline) RebuildPending() (bool, error)

RebuildPending tells launchers to restore before using staging after an interruption.

func (Pipeline) RecordStaged

func (pipeline Pipeline) RecordStaged() error

RecordStaged saves the manifest of the staged content as it is now.

func (Pipeline) StagedDrift

func (pipeline Pipeline) StagedDrift(full bool) (changes []string, recorded bool, err error)

StagedDrift compares the staged content with the manifest of the last sync and describes every file that was modified, added or removed since, by its path. recorded is false when no sync has left a manifest yet.

With full set it hashes every staged file and also reports a harness root that is gone; that is the check behind `sync --verify-only`. Without it, it compares kind, size and modification time only and skips roots that no longer exist: enough for a sync to say what it is about to replace, since the rebuild that follows does not depend on the answer.

func (Pipeline) Verify

func (pipeline Pipeline) Verify() error

type PlannedArtifact added in v0.9.0

type PlannedArtifact struct {
	Target            harness.Target
	SourceRelative    string
	VirtualPath       string
	Source            []byte
	Parsed            *artifacts.Markdown
	Name              string
	Kind              artifacts.Kind
	OutputPath        string
	Output            []byte
	AdditionalOutputs []string
	Omitted           bool
	Reason            string
	Warnings          []string
}

PlannedArtifact is one parsed markdown item and its target-specific output.

type PlannedMCPPluginFile added in v0.9.0

type PlannedMCPPluginFile struct {
	Path       string
	Contents   []byte
	Mode       os.FileMode
	LinkTarget string
	Module     string
}

type PlannedPackageFile added in v0.9.0

type PlannedPackageFile struct {
	Target         harness.Target
	SourceRelative string
	RelativePath   string
	Contents       []byte
	ExecuteBits    os.FileMode
	// Verbatim marks a byte-for-byte copy of a package file, the same for every harness.
	Verbatim bool
}

PlannedPackageFile is one generated artifact or copied plugin support file.

Jump to

Keyboard shortcuts

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