resolve

package
v0.29.0 Latest Latest
Warning

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

Go to latest
Published: Jul 6, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source
const (
	DefaultMaxDepth     = 10
	DefaultMaxResources = 50
)

Variables

This section is empty.

Functions

func ResolveRelativeURL added in v0.15.0

func ResolveRelativeURL(parentURL, relRef string) (string, error)

ResolveRelativeURL resolves a relative reference against a parent URL using RFC 3986 semantics. Absolute URLs are returned unchanged. The caller must validate the resolved URL against allowed prefixes.

Types

type Dependency

type Dependency struct {
	Field     string
	URL       string
	LocalPath string
	SHA256    string
	FetchedAt time.Time
	CacheHit  bool
	Type      string // "file" or "directory"
	Warning   string // non-fatal warning about this dependency
}

Dependency records a single URL that was resolved to a local cache path.

func ResolveHarness

func ResolveHarness(ctx context.Context, h *harness.Harness, opts ResolveOpts) ([]Dependency, error)

ResolveHarness resolves URL-referenced declarative fields (Agent, Policy, Skills) in the harness to local cache paths. Local paths are left unchanged. The harness is modified in place: URL fields are replaced with cache paths, and h.Skills may grow to include transitively resolved skill dependencies. Returns the deduplicated list of resolved dependencies.

Skills are directories: when a skill field is a URL, the resolver uses git sparse checkout (via TreeFetcher / gitfetch.FetchTree) to fetch the directory tree and cache it locally. Only URLs pointing to supported forges (github.com) are accepted for skills. Agents and policies remain single files.

Skills with dependencies: frontmatter are recursively resolved up to MaxDepth levels. Diamond dependencies are deduplicated; cycles are rejected. Set MaxDepth to 0 to disable transitive resolution. Negative values use DefaultMaxDepth (10).

Trusting a skill means trusting its entire transitive dependency closure: a skill's frontmatter can declare relative references that resolve to different paths on the same allowed domain. All transitive deps are still validated against allowed_remote_resources and SHA256 integrity hashes.

The default limits (depth=10, resources=50) bound worst-case resolution. CI environments with untrusted harnesses should set tighter limits. See ADR-0038 for the security model and trust semantics.

type ResolveOpts

type ResolveOpts struct {
	WorkspaceRoot string
	FetchPolicy   fetch.FetchPolicy
	TraceID       string
	AuditLogPath  string

	// TreeFetcher fetches all files under a path in a remote repository.
	// When nil, defaults to gitfetch.FetchTree (git sparse checkout).
	TreeFetcher gitfetch.TreeFetchFunc

	// GitToken is an optional token for authenticating git fetches.
	// Empty means unauthenticated (sufficient for public repos).
	GitToken string

	// MaxDepth controls transitive dependency resolution depth.
	// 0 disables transitive resolution (Phase 1 behavior).
	// <0 uses DefaultMaxDepth (10).
	//
	// MaxResources uses different semantics: <=0 always uses
	// DefaultMaxResources (50). The asymmetry exists because MaxDepth=0
	// is a meaningful "disable" value, while MaxResources=0 ("allow zero
	// resources") would prevent even non-transitive URL resolution.
	MaxDepth     int
	MaxResources int
}

ResolveOpts controls how URL-referenced resources are resolved.

Jump to

Keyboard shortcuts

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