project/package_cache_instance.go

// Copyright 2026 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package project

import (
	"path"
)

// PackageCacheInstance represents an immutable, content-addressed CIPD package
// stored in the central package cache.
//
// Each instance corresponds to an exact package payload identified by its CIPD
// instance ID (hash). Instances are globally unique and shared across all
// worktrees and workspace destinations. They reside at
// `.jiri_root/packages/instances/<instance_id>` and are never modified once downloaded.
type PackageCacheInstance struct {
	// Name is the CIPD package path, e.g. "gn/gn/linux-amd64".
	Name string `json:"package"`
	// Version is the resolved version tag or ref, e.g. "git_revision:...".
	Version string `json:"version"`
	// InstanceID is the content-addressable SHA256 hex string from CIPD.
	InstanceID string `json:"instance_id"`
}

// Subdir returns the relative path inside the cache root where CIPD installs this instance.
func (p PackageCacheInstance) Subdir() string {
	return path.Join("instances", p.InstanceID)
}

// ExistsIn checks whether this instance is downloaded and present in the specified cache.
func (p PackageCacheInstance) ExistsIn(cache *PackageCache) bool {
	return cache.InstanceExists(p)
}