Add command to open a resource in the browser (#1846)

## Changes

This builds on the functionality added in #1731 that produces a URL for
every resource.

Adds `bundle/resources` package to deal with resource lookups and
command completion. The new functionality is similar to the lookup and
command completion functionality located in `bundle/run`. It differs in
that it doesn't gracefully deal with ambiguous references to resources,
now that we explicitly validate this doesn't occur in the bundle
configuration. It still allows resources to be looked up with their
fully qualified key, `<plural type>.<key>`.

## Tests

* Added unit tests for resource lookup and completion
* Manually confirmed that `bundle open` prompts, accepts a key argument,
and opens a browser

bundle/resources/completion.go

@@ -0,0 +1,17 @@
+package resources
+
+import "github.com/databricks/cli/bundle"
+
+// Completions returns the same as [References] except
+// that every key maps directly to a single reference.
+func Completions(b *bundle.Bundle) map[string]Reference {
+	out := make(map[string]Reference)
+	keyOnlyRefs, _ := References(b)
+	for k, refs := range keyOnlyRefs {
+		if len(refs) != 1 {
+			continue
+		}
+		out[k] = refs[0]
+	}
+	return out
+}

bundle/resources/completion_test.go

@@ -0,0 +1,32 @@
+package resources
+
+import (
+	"testing"
+
+	"github.com/databricks/cli/bundle"
+	"github.com/databricks/cli/bundle/config"
+	"github.com/databricks/cli/bundle/config/resources"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestCompletions_SkipDuplicates(t *testing.T) {
+	b := &bundle.Bundle{
+		Config: config.Root{
+			Resources: config.Resources{
+				Jobs: map[string]*resources.Job{
+					"foo": {},
+					"bar": {},
+				},
+				Pipelines: map[string]*resources.Pipeline{
+					"foo": {},
+				},
+			},
+		},
+	}
+
+	// Test that this skips duplicates and only includes unambiguous completions.
+	out := Completions(b)
+	if assert.Len(t, out, 1) {
+		assert.Contains(t, out, "bar")
+	}
+}

bundle/resources/lookup.go

@@ -0,0 +1,69 @@
+package resources
+
+import (
+	"fmt"
+
+	"github.com/databricks/cli/bundle"
+	"github.com/databricks/cli/bundle/config"
+)
+
+// Reference is a reference to a resource.
+// It includes the resource type description, and a reference to the resource itself.
+type Reference struct {
+	Description config.ResourceDescription
+	Resource    config.ConfigResource
+}
+
+// Map is the core type for resource lookup and completion.
+type Map map[string][]Reference
+
+// References returns maps of resource keys to a slice of [Reference].
+//
+// The first map is indexed by the resource key only.
+// The second map is indexed by the resource type name and its key.
+//
+// While the return types allows for multiple resources to share the same key,
+// this is confirmed not to happen in the [validate.UniqueResourceKeys]	mutator.
+func References(b *bundle.Bundle) (Map, Map) {
+	keyOnly := make(Map)
+	keyWithType := make(Map)
+
+	// Collect map of resource references indexed by their keys.
+	for _, group := range b.Config.Resources.AllResources() {
+		for k, v := range group.Resources {
+			ref := Reference{
+				Description: group.Description,
+				Resource:    v,
+			}
+
+			kt := fmt.Sprintf("%s.%s", group.Description.PluralName, k)
+			keyOnly[k] = append(keyOnly[k], ref)
+			keyWithType[kt] = append(keyWithType[kt], ref)
+		}
+	}
+
+	return keyOnly, keyWithType
+}
+
+// Lookup returns the resource with the specified key.
+// If the key maps to more than one resource, an error is returned.
+// If the key does not map to any resource, an error is returned.
+func Lookup(b *bundle.Bundle, key string) (Reference, error) {
+	keyOnlyRefs, keyWithTypeRefs := References(b)
+	refs, ok := keyOnlyRefs[key]
+	if !ok {
+		refs, ok = keyWithTypeRefs[key]
+		if !ok {
+			return Reference{}, fmt.Errorf("resource with key %q not found", key)
+		}
+	}
+
+	switch {
+	case len(refs) == 1:
+		return refs[0], nil
+	case len(refs) > 1:
+		return Reference{}, fmt.Errorf("multiple resources with key %q found", key)
+	default:
+		panic("unreachable")
+	}
+}

bundle/resources/lookup_test.go

@@ -0,0 +1,88 @@
+package resources
+
+import (
+	"testing"
+
+	"github.com/databricks/cli/bundle"
+	"github.com/databricks/cli/bundle/config"
+	"github.com/databricks/cli/bundle/config/resources"
+	"github.com/databricks/databricks-sdk-go/service/jobs"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestLookup_EmptyBundle(t *testing.T) {
+	b := &bundle.Bundle{
+		Config: config.Root{
+			Resources: config.Resources{},
+		},
+	}
+
+	_, err := Lookup(b, "foo")
+	require.Error(t, err)
+	assert.ErrorContains(t, err, "resource with key \"foo\" not found")
+}
+
+func TestLookup_NotFound(t *testing.T) {
+	b := &bundle.Bundle{
+		Config: config.Root{
+			Resources: config.Resources{
+				Jobs: map[string]*resources.Job{
+					"foo": {},
+					"bar": {},
+				},
+			},
+		},
+	}
+
+	_, err := Lookup(b, "qux")
+	require.Error(t, err)
+	assert.ErrorContains(t, err, `resource with key "qux" not found`)
+}
+
+func TestLookup_MultipleFound(t *testing.T) {
+	b := &bundle.Bundle{
+		Config: config.Root{
+			Resources: config.Resources{
+				Jobs: map[string]*resources.Job{
+					"foo": {},
+				},
+				Pipelines: map[string]*resources.Pipeline{
+					"foo": {},
+				},
+			},
+		},
+	}
+
+	_, err := Lookup(b, "foo")
+	require.Error(t, err)
+	assert.ErrorContains(t, err, `multiple resources with key "foo" found`)
+}
+
+func TestLookup_Nominal(t *testing.T) {
+	b := &bundle.Bundle{
+		Config: config.Root{
+			Resources: config.Resources{
+				Jobs: map[string]*resources.Job{
+					"foo": {
+						JobSettings: &jobs.JobSettings{
+							Name: "Foo job",
+						},
+					},
+				},
+			},
+		},
+	}
+
+	// Lookup by key only.
+	out, err := Lookup(b, "foo")
+	if assert.NoError(t, err) {
+		assert.Equal(t, "Foo job", out.Resource.GetName())
+	}
+
+	// Lookup by type and key.
+	out, err = Lookup(b, "jobs.foo")
+	if assert.NoError(t, err) {
+		assert.Equal(t, "Foo job", out.Resource.GetName())
+	}
+}

cmd/bundle/bundle.go

@@ -27,5 +27,6 @@ func New() *cobra.Command {
 	cmd.AddCommand(newGenerateCommand())
 	cmd.AddCommand(newDebugCommand())
 	cmd.AddCommand(deployment.NewDeploymentCommand())
+	cmd.AddCommand(newOpenCommand())
 	return cmd
 }

cmd/bundle/open.go

@@ -0,0 +1,144 @@
+package bundle
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/databricks/cli/bundle"
+	"github.com/databricks/cli/bundle/config/mutator"
+	"github.com/databricks/cli/bundle/deploy/terraform"
+	"github.com/databricks/cli/bundle/phases"
+	"github.com/databricks/cli/bundle/resources"
+	"github.com/databricks/cli/cmd/bundle/utils"
+	"github.com/databricks/cli/cmd/root"
+	"github.com/databricks/cli/libs/cmdio"
+	"github.com/spf13/cobra"
+	"golang.org/x/exp/maps"
+
+	"github.com/pkg/browser"
+)
+
+func promptOpenArgument(ctx context.Context, b *bundle.Bundle) (string, error) {
+	// Compute map of "Human readable name of resource" -> "resource key".
+	inv := make(map[string]string)
+	for k, ref := range resources.Completions(b) {
+		title := fmt.Sprintf("%s: %s", ref.Description.SingularTitle, ref.Resource.GetName())
+		inv[title] = k
+	}
+
+	key, err := cmdio.Select(ctx, inv, "Resource to open")
+	if err != nil {
+		return "", err
+	}
+
+	return key, nil
+}
+
+func resolveOpenArgument(ctx context.Context, b *bundle.Bundle, args []string) (string, error) {
+	// If no arguments are specified, prompt the user to select the resource to open.
+	if len(args) == 0 && cmdio.IsPromptSupported(ctx) {
+		return promptOpenArgument(ctx, b)
+	}
+
+	if len(args) < 1 {
+		return "", fmt.Errorf("expected a KEY of the resource to open")
+	}
+
+	return args[0], nil
+}
+
+func newOpenCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "open",
+		Short: "Open a resource in the browser",
+		Args:  root.MaximumNArgs(1),
+	}
+
+	var forcePull bool
+	cmd.Flags().BoolVar(&forcePull, "force-pull", false, "Skip local cache and load the state from the remote workspace")
+
+	cmd.RunE = func(cmd *cobra.Command, args []string) error {
+		ctx := cmd.Context()
+		b, diags := utils.ConfigureBundleWithVariables(cmd)
+		if err := diags.Error(); err != nil {
+			return diags.Error()
+		}
+
+		diags = bundle.Apply(ctx, b, phases.Initialize())
+		if err := diags.Error(); err != nil {
+			return err
+		}
+
+		arg, err := resolveOpenArgument(ctx, b, args)
+		if err != nil {
+			return err
+		}
+
+		cacheDir, err := terraform.Dir(ctx, b)
+		if err != nil {
+			return err
+		}
+		_, stateFileErr := os.Stat(filepath.Join(cacheDir, terraform.TerraformStateFileName))
+		_, configFileErr := os.Stat(filepath.Join(cacheDir, terraform.TerraformConfigFileName))
+		noCache := errors.Is(stateFileErr, os.ErrNotExist) || errors.Is(configFileErr, os.ErrNotExist)
+
+		if forcePull || noCache {
+			diags = bundle.Apply(ctx, b, bundle.Seq(
+				terraform.StatePull(),
+				terraform.Interpolate(),
+				terraform.Write(),
+			))
+			if err := diags.Error(); err != nil {
+				return err
+			}
+		}
+
+		diags = bundle.Apply(ctx, b, bundle.Seq(
+			terraform.Load(),
+			mutator.InitializeURLs(),
+		))
+		if err := diags.Error(); err != nil {
+			return err
+		}
+
+		// Locate resource to open.
+		ref, err := resources.Lookup(b, arg)
+		if err != nil {
+			return err
+		}
+
+		// Confirm that the resource has a URL.
+		url := ref.Resource.GetURL()
+		if url == "" {
+			return fmt.Errorf("resource does not have a URL associated with it (has it been deployed?)")
+		}
+
+		return browser.OpenURL(url)
+	}
+
+	cmd.ValidArgsFunction = func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+		b, diags := root.MustConfigureBundle(cmd)
+		if err := diags.Error(); err != nil {
+			cobra.CompErrorln(err.Error())
+			return nil, cobra.ShellCompDirectiveError
+		}
+
+		// No completion in the context of a bundle.
+		// Source and destination paths are taken from bundle configuration.
+		if b == nil {
+			return nil, cobra.ShellCompDirectiveNoFileComp
+		}
+
+		if len(args) == 0 {
+			completions := resources.Completions(b)
+			return maps.Keys(completions), cobra.ShellCompDirectiveNoFileComp
+		} else {
+			return nil, cobra.ShellCompDirectiveNoFileComp
+		}
+	}
+
+	return cmd
+}