feat(oci): support digest-pinned imports

Accept sha256 manifest references in import and diff, prefer a digest when both tag and digest are supplied, and persist the resolved OCI identity on imported workspaces.

Pin the CLI extraction pass to the manifest resolved during its initial check so a concurrent tag move cannot change the imported bundle.

Author: Keerthirajan58

cmd/nebi/bundle_api_e2e_test.go

@@ -165,7 +165,8 @@ func TestE2E_BundlePublishImportViaAPI_LocalMode(t *testing.T) {
 	writeFile("notebook.ipynb", notebookBody)
 
 	reg := oci.Registry{Host: ociHost, Namespace: ociNS, PlainHTTP: true}
-	if _, err := oci.Publish(ctx, srcDir, reg, repoName, bundleTag); err != nil {
+	published, err := oci.Publish(ctx, srcDir, reg, repoName, bundleTag)
+	if err != nil {
 		t.Fatalf("seed oci.Publish: %v", err)
 	}
 
@@ -178,11 +179,15 @@ func TestE2E_BundlePublishImportViaAPI_LocalMode(t *testing.T) {
 	})
 
 	// ---- Import via POST /registries/:id/import ----
-	wsID := importViaAPI(t, serverURL, token, registryID, map[string]interface{}{
+	imported := importViaAPI(t, serverURL, token, registryID, map[string]interface{}{
 		"repository_path": ociNS + "/" + repoName,
-		"tag":             bundleTag,
+		"digest":          published.Digest,
 		"name":            "notebook-imported",
 	})
+	if imported.ImportRepository != published.Repository || imported.ImportTag != "" || imported.ImportDigest != published.Digest {
+		t.Fatalf("unexpected import metadata: repository=%q tag=%q digest=%q", imported.ImportRepository, imported.ImportTag, imported.ImportDigest)
+	}
+	wsID := imported.ID
 
 	// ---- Poll workspace until ready (or fail after 30s) ----
 	pollWorkspaceReady(t, serverURL, token, wsID, 30*time.Second)
@@ -337,8 +342,15 @@ func createRegistryViaAPI(t *testing.T, serverURL, token string, body map[string
 	return result.ID
 }
 
-// importViaAPI POSTs to /registries/:id/import and returns the created workspace ID.
-func importViaAPI(t *testing.T, serverURL, token, registryID string, body map[string]interface{}) string {
+type importedWorkspace struct {
+	ID               string `json:"id"`
+	ImportRepository string `json:"import_repository"`
+	ImportTag        string `json:"import_tag"`
+	ImportDigest     string `json:"import_digest"`
+}
+
+// importViaAPI POSTs to /registries/:id/import and returns the created workspace.
+func importViaAPI(t *testing.T, serverURL, token, registryID string, body map[string]interface{}) importedWorkspace {
 	t.Helper()
 	b, _ := json.Marshal(body)
 	url := fmt.Sprintf("%s/api/v1/registries/%s/import", serverURL, registryID)
@@ -354,16 +366,14 @@ func importViaAPI(t *testing.T, serverURL, token, registryID string, body map[st
 	if resp.StatusCode != http.StatusCreated {
 		t.Fatalf("POST /registries/%s/import: status %d, body: %s", registryID, resp.StatusCode, raw)
 	}
-	var result struct {
-		ID string `json:"id"`
-	}
+	var result importedWorkspace
 	if err := json.Unmarshal(raw, &result); err != nil {
 		t.Fatalf("decode import response: %v (body: %s)", err, raw)
 	}
 	if result.ID == "" {
 		t.Fatalf("import response missing id: %s", raw)
 	}
-	return result.ID
+	return result
 }
 
 // pollWorkspaceReady polls GET /workspaces/:id until status == "ready" or times out.

cmd/nebi/bundle_e2e_test.go

@@ -12,6 +12,8 @@ import (
 	"testing"
 
 	"github.com/google/go-containerregistry/pkg/registry"
+	"github.com/nebari-dev/nebi/internal/oci"
+	"github.com/nebari-dev/nebi/internal/store"
 )
 
 // startE2ERegistry spins up an in-memory OCI Distribution server. The
@@ -27,9 +29,9 @@ func startE2ERegistry(t *testing.T) string {
 	return u.Host
 }
 
-// publishedRefRE extracts the "<host>/<ns>/<repo>:<tag>" fragment from
+// publishedRefRE extracts the tag reference and resolved manifest digest from
 // publish stderr lines that look like `Published <ref> (digest: sha256:...)`.
-var publishedRefRE = regexp.MustCompile(`Published (\S+) \(digest:`)
+var publishedRefRE = regexp.MustCompile(`Published (\S+) \(digest: (sha256:[a-f0-9]{64})\)`)
 
 // TestE2E_LocalBundlePublishImport runs a full publish --local → import
 // round trip against an in-memory OCI registry. Verifies that pixi.toml,
@@ -146,6 +148,84 @@ func TestE2E_LocalBundlePublishImport(t *testing.T) {
 	if !strings.Contains(string(gotLock), "version: 6") {
 		t.Fatalf("imported pixi.lock missing expected content:\n%s", gotLock)
 	}
+
+	artifact, err := oci.ParseArtifactReference(ref)
+	if err != nil {
+		t.Fatalf("parse published reference: %v", err)
+	}
+	s, err := store.Open(dataDir)
+	if err != nil {
+		t.Fatalf("open local store: %v", err)
+	}
+	defer s.Close()
+	ws, err := s.FindWorkspaceByPath(outDir)
+	if err != nil {
+		t.Fatalf("find imported workspace: %v", err)
+	}
+	if ws == nil {
+		t.Fatal("imported workspace was not tracked")
+	}
+	if ws.ImportRepository != artifact.Repository || ws.ImportTag != artifact.Tag || ws.ImportDigest != m[2] {
+		t.Fatalf("unexpected tag import metadata: repository=%q tag=%q digest=%q", ws.ImportRepository, ws.ImportTag, ws.ImportDigest)
+	}
+}
+
+func TestE2E_LocalBundleImportAndDiffByDigest(t *testing.T) {
+	dataDir := t.TempDir()
+	t.Setenv("NEBI_DATA_DIR", dataDir)
+
+	regHost := startE2ERegistry(t)
+	srcDir := t.TempDir()
+	writePixiFiles(t, srcDir,
+		"[project]\nname = \"digest-e2e\"\nchannels = [\"conda-forge\"]\nplatforms = [\"linux-64\"]\n",
+		"version: 6\n",
+	)
+	published, err := oci.Publish(
+		t.Context(),
+		srcDir,
+		oci.Registry{Host: regHost, Namespace: "demo", PlainHTTP: true},
+		"digest-e2e",
+		"reviewed",
+	)
+	if err != nil {
+		t.Fatalf("publish bundle: %v", err)
+	}
+
+	digestRef := "http://" + published.Repository + "@" + published.Digest
+	outParent := t.TempDir()
+	outDir := filepath.Join(outParent, "restored")
+	res := runCLI(t, outParent, "import", digestRef, "--output", outDir)
+	if res.ExitCode != 0 {
+		t.Fatalf("digest import failed:\nstdout: %s\nstderr: %s", res.Stdout, res.Stderr)
+	}
+
+	s, err := store.Open(dataDir)
+	if err != nil {
+		t.Fatalf("open local store: %v", err)
+	}
+	defer s.Close()
+	ws, err := s.FindWorkspaceByPath(outDir)
+	if err != nil {
+		t.Fatalf("find imported workspace: %v", err)
+	}
+	if ws == nil {
+		t.Fatal("imported workspace was not tracked")
+	}
+	if ws.ImportRepository != published.Repository || ws.ImportTag != "" || ws.ImportDigest != published.Digest {
+		t.Fatalf("unexpected import metadata: repository=%q tag=%q digest=%q", ws.ImportRepository, ws.ImportTag, ws.ImportDigest)
+	}
+
+	modifiedToml := "[project]\nname = \"digest-e2e\"\nchannels = [\"conda-forge\"]\nplatforms = [\"linux-64\"]\n\n[dependencies]\nrequests = \"*\"\n"
+	if err := os.WriteFile(filepath.Join(outDir, "pixi.toml"), []byte(modifiedToml), 0o644); err != nil {
+		t.Fatalf("modify imported pixi.toml: %v", err)
+	}
+	res = runCLI(t, outDir, "diff", digestRef)
+	if res.ExitCode != 0 {
+		t.Fatalf("digest diff failed:\nstdout: %s\nstderr: %s", res.Stdout, res.Stderr)
+	}
+	if !strings.Contains(res.Stdout, digestRef) || !strings.Contains(res.Stdout, "requests") {
+		t.Fatalf("digest diff did not compare against the OCI artifact: stdout=%q stderr=%q", res.Stdout, res.Stderr)
+	}
 }
 
 // TestE2E_LocalBundleRejectsNonEmptyDest verifies that importing a bundle

cmd/nebi/client.go

@@ -224,6 +224,34 @@ func saveOrigin(remoteID, name, tag, action, tomlContent, lockContent string) er
 	return s.SaveWorkspace(ws)
 }
 
+// saveImportMetadata records the immutable OCI identity that seeded a local
+// workspace. The workspace must already have been registered by ensureInit.
+func saveImportMetadata(dir, repository, tag, manifestDigest string) error {
+	absDir, err := filepath.Abs(dir)
+	if err != nil {
+		return fmt.Errorf("resolving import directory: %w", err)
+	}
+
+	s, err := store.New()
+	if err != nil {
+		return err
+	}
+	defer s.Close()
+
+	ws, err := s.FindWorkspaceByPath(absDir)
+	if err != nil {
+		return err
+	}
+	if ws == nil {
+		return fmt.Errorf("imported workspace at %s is not tracked", absDir)
+	}
+
+	ws.ImportRepository = repository
+	ws.ImportTag = tag
+	ws.ImportDigest = manifestDigest
+	return s.SaveWorkspace(ws)
+}
+
 // parseWsRef parses a reference in the format workspace:tag.
 // Returns (workspace, tag) where tag may be empty if not specified.
 func parseWsRef(ref string) (string, string) {

cmd/nebi/diff.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/nebari-dev/nebi/internal/cliclient"
 	"github.com/nebari-dev/nebi/internal/diff"
+	"github.com/nebari-dev/nebi/internal/oci"
 	"github.com/nebari-dev/nebi/internal/store"
 	"github.com/spf13/cobra"
 )
@@ -23,6 +24,7 @@ Each reference can be:
   - A path (contains a slash): ./dir, /tmp/project, foo/bar
   - A tracked workspace name (bare word): data-science
   - A server ref (contains a colon): myworkspace:v1
+  - An OCI ref: quay.io/nebari/my-env:v1 or quay.io/nebari/my-env@sha256:<digest>
 
 If no refs are given, compares the current directory against the last
 pushed/pulled origin.
@@ -37,6 +39,7 @@ Examples:
   nebi diff myworkspace:v1                     # server version vs cwd
   nebi diff myworkspace:v1 myworkspace:v2      # two server versions
   nebi diff myworkspace:v1 ./local-dir         # server vs local dir
+  nebi diff quay.io/nebari/my-env@sha256:<digest>
 
 Use --lock to also compare pixi.lock files.`,
 	Args:              cobra.RangeArgs(0, 2),
@@ -140,12 +143,36 @@ func runDiff(cmd *cobra.Command, args []string) error {
 
 // resolveSource resolves a ref (directory, workspace name, or workspace:tag) into a diffSource.
 func resolveSource(ref, defaultLabel string) (*diffSource, error) {
-	// 1. Local directory path (must contain a slash, e.g. ./foo, /tmp/foo, foo/bar)
+	// 1. Explicit local directory path.
+	if isExplicitLocalPath(ref) {
+		return resolveLocalSource(ref, defaultLabel)
+	}
+
+	// Preserve the existing path semantics when a registry-looking relative
+	// path exists on disk. Prefix a non-existent path with ./ to force it to
+	// remain local.
+	if isPath(ref) {
+		if _, err := os.Stat(ref); err == nil || !os.IsNotExist(err) {
+			return resolveLocalSource(ref, defaultLabel)
+		}
+	}
+
+	// 2. Fully-qualified OCI reference. Registry-like tag references and all
+	// digest references are unambiguous; simple foo/bar remains a local path.
+	if looksLikeOCIReference(ref) {
+		artifact, err := oci.ParseArtifactReference(ref)
+		if err != nil {
+			return nil, err
+		}
+		return resolveOCISource(ref, artifact)
+	}
+
+	// 3. Local directory path (must contain a slash, e.g. foo/bar).
 	if isPath(ref) {
 		return resolveLocalSource(ref, defaultLabel)
 	}
 
-	// 2. Local workspace name (check store before assuming server ref)
+	// 4. Local workspace name (check store before assuming server ref)
 	if !strings.Contains(ref, ":") {
 		s, err := store.New()
 		if err == nil {
@@ -166,10 +193,49 @@ func resolveSource(ref, defaultLabel string) (*diffSource, error) {
 		}
 	}
 
-	// 3. Server ref (workspace:tag)
+	// 5. Server ref (workspace:tag)
 	return resolveServerSource(ref)
 }
 
+func isExplicitLocalPath(ref string) bool {
+	return ref == "." ||
+		ref == ".." ||
+		filepath.IsAbs(ref) ||
+		strings.HasPrefix(ref, "./") ||
+		strings.HasPrefix(ref, "../")
+}
+
+func looksLikeOCIReference(ref string) bool {
+	if strings.HasPrefix(ref, "http://") || strings.HasPrefix(ref, "https://") || strings.Contains(ref, "@") {
+		return true
+	}
+
+	slash := strings.IndexByte(ref, '/')
+	if slash <= 0 {
+		return false
+	}
+	registryHost := ref[:slash]
+	return registryHost == "localhost" || strings.ContainsAny(registryHost, ".:")
+}
+
+func resolveOCISource(label string, artifact oci.ArtifactReference) (*diffSource, error) {
+	result, err := oci.PullBundle(context.Background(), artifact.Repository, artifact.Selector(), oci.PullOptions{
+		PlainHTTP: artifact.PlainHTTP,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("pulling OCI bundle: %w", err)
+	}
+	if err := oci.VerifyManifestDigest(result.Digest, artifact.Digest); err != nil {
+		return nil, err
+	}
+
+	return &diffSource{
+		label: label,
+		toml:  result.PixiToml,
+		lock:  result.PixiLock,
+	}, nil
+}
+
 func resolveLocalSource(dir, defaultLabel string) (*diffSource, error) {
 	absDir, err := filepath.Abs(dir)
 	if err != nil {