feat!: add transactional package installation foundation

CONTRIBUTING.md

@@ -54,9 +54,9 @@ Then in another shell, run `dlv connect` and debug with dlv as you normally woul
 ```console
 $ dlv connect 127.0.0.1:2345
 Type 'help' for list of commands.
-(dlv) b install.go:58
+(dlv) b main.verifySignatureInStaging
 (dlv) c
-> [Breakpoint 1] main.verifySignature() /Users/user/src/columnar-tech/dbc/cmd/dbc/install.go:58 (hits goroutine(99):1 total:1) (PC: 0x105201f88)
+> [Breakpoint 1] main.verifySignatureInStaging() /Users/user/src/columnar-tech/dbc/cmd/dbc/install.go (hits goroutine(99):1 total:1) (PC: 0x105201f88)
 ```
 
 When you're done, exiting the client should cause the server to exit automatically.

client_methods.go

@@ -278,19 +278,17 @@ func (c *Client) Install(ctx context.Context, cfg config.Config, driverName stri
 	}
 	defer os.RemoveAll(filepath.Dir(f.Name()))
 
-	manifest, err := config.InstallDriver(cfg, driverName, f)
+	manifest, err := config.InstallPackage(ctx, cfg, driverName, f, config.InstallPackageOptions{})
 	if err != nil {
 		return nil, fmt.Errorf("failed to install driver %s: %w", driverName, err)
 	}
 
-	if err := config.CreateManifest(cfg, manifest.DriverInfo); err != nil {
-		return nil, fmt.Errorf("failed to create manifest for driver %s: %w", driverName, err)
-	}
-
 	return &manifest, nil
 }
 
-// Uninstall uninstalls a driver with the given name from the specified configuration.
+// Uninstall removes a driver's runtime registration from the specified
+// configuration. For external registrations, the shared library remains in
+// place because dbc does not own it.
 func (c *Client) Uninstall(cfg config.Config, driverName string) error {
 	di, err := config.GetDriver(cfg, driverName)
 	if err != nil {

client_methods_test.go

@@ -25,6 +25,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/Masterminds/semver/v3"
 	"github.com/columnar-tech/dbc"
 	"github.com/columnar-tech/dbc/config"
 	"github.com/stretchr/testify/assert"
@@ -168,6 +169,26 @@ func TestClientUninstall(t *testing.T) {
 		assert.Error(t, err)
 		assert.Contains(t, err.Error(), "not-installed-driver")
 	})
+
+	t.Run("removes external registration and preserves shared library", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		cfg := config.Config{Level: config.ConfigEnv, Location: tmpDir}
+		shared := filepath.Join(tmpDir, "managed-elsewhere", "driver.so")
+		require.NoError(t, os.MkdirAll(filepath.Dir(shared), 0o700))
+		require.NoError(t, os.WriteFile(shared, []byte("external library"), 0o600))
+		info := config.DriverInfo{
+			ID: "external-driver", FilePath: tmpDir, Name: "External Driver",
+			Version: semver.MustParse("1.0.0"), Source: "external",
+		}
+		info.Driver.Shared.Set(config.PlatformTuple(), shared)
+		require.NoError(t, config.CreateManifest(cfg, info))
+
+		require.NoError(t, c.Uninstall(cfg, info.ID))
+		assert.NoFileExists(t, filepath.Join(tmpDir, "external-driver.toml"))
+		data, err := os.ReadFile(shared)
+		require.NoError(t, err)
+		assert.Equal(t, "external library", string(data))
+	})
 }
 
 func TestClientDownload(t *testing.T) {

cmd/dbc/install.go

@@ -15,6 +15,7 @@
 package main
 
 import (
+	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -32,6 +33,7 @@ import (
 	"github.com/Masterminds/semver/v3"
 	"github.com/columnar-tech/dbc"
 	"github.com/columnar-tech/dbc/config"
+	"github.com/columnar-tech/dbc/internal/hostpath"
 	"github.com/columnar-tech/dbc/internal/jsonschema"
 )
 
@@ -111,13 +113,14 @@ func (c InstallCmd) GetModel() tea.Model {
 	return c.GetModelCustom(defaultBaseModel())
 }
 
-func verifySignature(m config.Manifest, noVerify bool) error {
-	if m.Files.Driver == "" || noVerify {
+func verifySignatureInStaging(path string, m config.Manifest, noVerify bool) error {
+	if m.Files.Driver == "" {
+		return fmt.Errorf("package manifest does not specify Files.driver")
+	}
+	if noVerify {
 		return nil
 	}
 
-	path := filepath.Dir(m.Driver.Shared.Get(config.PlatformTuple()))
-
 	lib, err := os.Open(filepath.Join(path, m.Files.Driver))
 	if err != nil {
 		return fmt.Errorf("could not open driver file: %w", err)
@@ -145,10 +148,12 @@ func verifySignature(m config.Manifest, noVerify bool) error {
 	return nil
 }
 
-type writeDriverManifestMsg struct {
-	DriverInfo config.DriverInfo
+type packageInstallResultMsg struct {
+	Manifest config.Manifest
 }
 
+type installVerificationStartedMsg struct{}
+
 type localInstallMsg struct{}
 
 // alreadyInstalledChecksumMsg carries the checksum computed for an already-installed driver.
@@ -241,6 +246,8 @@ type progressiveInstallModel struct {
 	alreadyInstalledChecksum string
 	jsonOut                  io.Writer
 	jsonErrorOutput          string // JSON error envelope to emit via FinalOutput
+	verificationStarted      bool
+	verifyStagedPackage      func(string, config.Manifest, bool) error
 }
 
 type driversWithRegistryError struct {
@@ -257,8 +264,8 @@ func (m progressiveInstallModel) Init() tea.Cmd {
 
 	return tea.Batch(m.spinner.Tick, func() tea.Msg {
 		installDir := "."
-		if locs := filepath.SplitList(m.cfg.Location); len(locs) > 0 && locs[0] != "" {
-			installDir = locs[0]
+		if root := m.cfg.PrimaryLocation(); root != "" {
+			installDir = root
 		}
 		lockDir := installDir
 		for {
@@ -313,7 +320,7 @@ func (m progressiveInstallModel) FinalOutput() string {
 				Status:   "already installed",
 				Driver:   m.conflictingInfo.ID,
 				Version:  m.conflictingInfo.Version.String(),
-				Location: filepath.SplitList(m.cfg.Location)[0],
+				Location: m.cfg.PrimaryLocation(),
 			}
 			if m.alreadyInstalledChecksum != "" {
 				payload.Checksum = m.alreadyInstalledChecksum
@@ -334,7 +341,7 @@ func (m progressiveInstallModel) FinalOutput() string {
 			return string(jsonOutput)
 		}
 		return fmt.Sprintf("\nDriver %s %s already installed at %s",
-			m.conflictingInfo.ID, m.conflictingInfo.Version, filepath.SplitList(m.cfg.Location)[0])
+			m.conflictingInfo.ID, m.conflictingInfo.Version, m.cfg.PrimaryLocation())
 	}
 
 	var b strings.Builder
@@ -343,7 +350,7 @@ func (m progressiveInstallModel) FinalOutput() string {
 			Status:   "installed",
 			Driver:   m.Driver,
 			Version:  m.DriverPackage.Version.String(),
-			Location: filepath.SplitList(m.cfg.Location)[0],
+			Location: m.cfg.PrimaryLocation(),
 		}
 		if m.hasConflict() {
 			installStatus.Conflict = fmt.Sprintf("%s (version: %s)", m.conflictingInfo.ID, m.conflictingInfo.Version)
@@ -383,7 +390,11 @@ func (m progressiveInstallModel) FinalOutput() string {
 		}
 
 		if installStatus.Conflict != "" {
-			fmt.Fprintf(&b, "\nRemoved conflicting driver: %s", installStatus.Conflict)
+			label := "Shadowed active driver"
+			if conflictIsInInstallRoot(m.conflictingInfo, m.cfg.PrimaryLocation(), m.cfg.Level) {
+				label = "Replaced active driver"
+			}
+			fmt.Fprintf(&b, "\n%s: %s", label, installStatus.Conflict)
 		}
 
 		fmt.Fprintf(&b, "\nInstalled %s %s to %s",
@@ -396,6 +407,45 @@ func (m progressiveInstallModel) FinalOutput() string {
 	return b.String()
 }
 
+// TODO: The install-root path identity check below duplicates logic in config;
+// consider reusing it from, or moving it to, the config package.
+func conflictIsInInstallRoot(conflict config.DriverInfo, installRoot string, level config.ConfigLevel) bool {
+	if conflict.FilePath == "" || installRoot == "" {
+		return false
+	}
+
+	// Registry registrations identify their hive rather than a filesystem root.
+	// They are replaced when this install targets the same registry level.
+	switch strings.ToUpper(conflict.FilePath) {
+	case `HKCU\SOFTWARE\ADBC\DRIVERS`:
+		return level == config.ConfigUser
+	case `HKLM\SOFTWARE\ADBC\DRIVERS`:
+		return level == config.ConfigSystem
+	}
+
+	return sameInstallRoot(conflict.FilePath, installRoot)
+}
+
+func sameInstallRoot(a, b string) bool {
+	if aInfo, err := os.Stat(a); err == nil {
+		if bInfo, err := os.Stat(b); err == nil && os.SameFile(aInfo, bInfo) {
+			return true
+		}
+	}
+	canonicalize := func(path string) string {
+		absolute, err := hostpath.Abs(path)
+		if err != nil {
+			absolute = hostpath.Clean(path)
+		}
+		if resolved, err := hostpath.EvalSymlinks(absolute); err == nil {
+			absolute = resolved
+		}
+		return hostpath.Clean(absolute)
+	}
+
+	return hostpath.Equal(canonicalize(a), canonicalize(b))
+}
+
 func (m progressiveInstallModel) searchForDriver(list []dbc.Driver) (tea.Model, tea.Cmd) {
 	driverName, vers, err := parseDriverConstraint(m.Driver)
 	if err != nil {
@@ -478,18 +528,24 @@ func (m progressiveInstallModel) startInstalling(downloaded *os.File) (tea.Model
 		}
 	}
 
+	program := prog
+	verifier := m.verifyStagedPackage
+	if verifier == nil {
+		verifier = verifySignatureInStaging
+	}
 	return m, func() tea.Msg {
-		if m.conflictingInfo.ID != "" {
-			if err := config.UninstallDriver(m.cfg, m.conflictingInfo); err != nil {
-				return err
-			}
-		}
-
-		manifest, err := config.InstallDriver(m.cfg, m.Driver, downloaded)
+		manifest, err := config.InstallPackage(context.Background(), m.cfg, m.Driver, downloaded, config.InstallPackageOptions{
+			Verifier: func(stagingDir string, stagedManifest config.Manifest) error {
+				if program != nil {
+					program.Send(installVerificationStartedMsg{})
+				}
+				return verifier(stagingDir, stagedManifest, m.NoVerify)
+			},
+		})
 		if err != nil {
 			return err
 		}
-		return manifest
+		return packageInstallResultMsg{Manifest: manifest}
 	}
 }
 
@@ -547,31 +603,27 @@ func (m progressiveInstallModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		m = m.addEvent("download.complete")
 		m = m.addEvent("extract.start")
 		return m.startInstalling(msg)
-	case config.Manifest:
-		if m.DriverPackage.Version == nil {
-			m.DriverPackage = manifestToPackageInfo(msg)
+	case installVerificationStartedMsg:
+		if m.state >= stDone || m.status != 0 || m.verificationStarted {
+			return m, nil
 		}
-
-		m.state = stVerifying
-		m.postInstallMessage = strings.Join(msg.PostInstall.Messages, "\n")
+		m.verificationStarted = true
 		m = m.addEvent("extract.complete")
 		m = m.addEvent("verify.start")
-		return m, func() tea.Msg {
-			if err := verifySignature(msg, m.NoVerify); err != nil {
-				path := filepath.Dir(msg.Driver.Shared.Get(config.PlatformTuple()))
-				_ = os.RemoveAll(path)
-				return err
-			}
-			return writeDriverManifestMsg{DriverInfo: msg.DriverInfo}
+		if !m.NoVerify {
+			m.state = stVerifying
 		}
-	case writeDriverManifestMsg:
-		m.state = stDone
-		m.installedDriverInfo = msg.DriverInfo
+		return m, nil
+	case packageInstallResultMsg:
+		if m.DriverPackage.Version == nil {
+			m.DriverPackage = manifestToPackageInfo(msg.Manifest)
+		}
+		m.postInstallMessage = strings.Join(msg.Manifest.PostInstall.Messages, "\n")
+		m.installedDriverInfo = msg.Manifest.DriverInfo
 		m = m.addEvent("verify.complete")
 		m = m.addEvent("manifest.create")
-		return m, tea.Sequence(func() tea.Msg {
-			return config.CreateManifest(m.cfg, msg.DriverInfo)
-		}, tea.Quit)
+		m.state = stDone
+		return m, tea.Quit
 	case error:
 		m.status = 1
 		m.err = msg