feat(extension): add acceptance tests and fix env override + error handling

- acceptance/extension_test.go: acceptance tests for extension dispatch,
  CIRCLE_TOKEN injection, unknown-command fallthrough, and exit code propagation
- buildEnv: replace duplicate env keys in-place instead of appending, so
  the injected token wins over any pre-existing CIRCLE_TOKEN in the shell env
- Run: use clierrors.New instead of fmt.Errorf for structured error output
- rootUnknownCommand: accept rootName param so binary renames (e.g. cci) work
- main.go: format CLIError from extension via the normal error formatter

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: webster

acceptance/extension_test.go

@@ -0,0 +1,173 @@
+// Copyright (c) 2026 Circle Internet Services, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+//
+// SPDX-License-Identifier: MIT
+
+package acceptance_test
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"gotest.tools/v3/assert"
+	"gotest.tools/v3/assert/cmp"
+	"gotest.tools/v3/skip"
+
+	"github.com/CircleCI-Public/circleci-cli-v2/internal/testing/binary"
+	testenv "github.com/CircleCI-Public/circleci-cli-v2/internal/testing/env"
+)
+
+// buildExtension writes a shell script as a fake circleci-<name> extension
+// into extDir and returns the full path. The script prints its positional args
+// and the CIRCLE_TOKEN / CIRCLE_URL env vars, then exits 0.
+func buildExtension(t *testing.T, extDir, name string) string {
+	t.Helper()
+	skip.If(t, runtime.GOOS == "windows", "shell-script extensions are not supported on Windows")
+
+	path := filepath.Join(extDir, "circleci-"+name)
+	script := "#!/bin/sh\nprintf 'args:%s\\n' \"$*\"\nprintf 'token:%s\\n' \"$CIRCLE_TOKEN\"\nprintf 'url:%s\\n' \"$CIRCLE_URL\"\n"
+	err := os.WriteFile(path, []byte(script), 0o755)
+	assert.NilError(t, err)
+	return path
+}
+
+// withExtDir prepends extDir to PATH in the given environ slice.
+func withExtDir(environ []string, extDir string) []string {
+	out := make([]string, 0, len(environ)+1)
+	out = append(out, environ...)
+	for i, v := range out {
+		if strings.HasPrefix(v, "PATH=") {
+			out[i] = "PATH=" + extDir + string(os.PathListSeparator) + v[len("PATH="):]
+			return out
+		}
+	}
+	return append(out, "PATH="+extDir)
+}
+
+// TestExtensionDispatch verifies that an unknown command is transparently
+// dispatched to circleci-<name> when the binary exists in PATH.
+func TestExtensionDispatch(t *testing.T) {
+	extDir := t.TempDir()
+	buildExtension(t, extDir, "hello")
+
+	env := testenv.New(t)
+	env.Token = testToken
+
+	result := binary.RunCLI(t, binary.RunOpts{
+		Binary:  binaryPath,
+		Args:    []string{"hello", "arg1", "arg2"},
+		Env:     withExtDir(env.Environ(), extDir),
+		WorkDir: t.TempDir(),
+	})
+
+	assert.Equal(t, result.ExitCode, 0, "stderr: %s", result.Stderr)
+	assert.Check(t, cmp.Contains(result.Stdout, "args:arg1 arg2"),
+		"extension did not receive correct args; stdout: %q", result.Stdout)
+}
+
+// TestExtensionEnvInjection verifies that CIRCLE_TOKEN and CIRCLE_URL are
+// injected into the extension's environment from the CLI's resolved config.
+func TestExtensionEnvInjection(t *testing.T) {
+	extDir := t.TempDir()
+	buildExtension(t, extDir, "hello")
+
+	env := testenv.New(t)
+	env.Token = testToken
+
+	result := binary.RunCLI(t, binary.RunOpts{
+		Binary:  binaryPath,
+		Args:    []string{"hello"},
+		Env:     withExtDir(env.Environ(), extDir),
+		WorkDir: t.TempDir(),
+	})
+
+	assert.Equal(t, result.ExitCode, 0, "stderr: %s", result.Stderr)
+	assert.Check(t, cmp.Contains(result.Stdout, "token:"+testToken),
+		"CIRCLE_TOKEN not injected; stdout: %q", result.Stdout)
+}
+
+// TestExtensionExitCodePropagated verifies that the extension's exit code is
+// propagated back to the caller unchanged.
+func TestExtensionExitCodePropagated(t *testing.T) {
+	skip.If(t, runtime.GOOS == "windows", "shell-script extensions are not supported on Windows")
+
+	extDir := t.TempDir()
+	path := filepath.Join(extDir, "circleci-fail")
+	err := os.WriteFile(path, []byte("#!/bin/sh\nexit 42\n"), 0o755)
+	assert.NilError(t, err)
+
+	env := testenv.New(t)
+
+	result := binary.RunCLI(t, binary.RunOpts{
+		Binary:  binaryPath,
+		Args:    []string{"fail"},
+		Env:     withExtDir(env.Environ(), extDir),
+		WorkDir: t.TempDir(),
+	})
+
+	assert.Equal(t, result.ExitCode, 42, "expected exit code 42 from extension")
+}
+
+// TestExtensionNotFoundShowsOriginalError verifies that when no matching
+// extension exists, the original "unknown command" error from Cobra is shown.
+func TestExtensionNotFoundShowsOriginalError(t *testing.T) {
+	env := testenv.New(t)
+
+	result := binary.RunCLI(t, binary.RunOpts{
+		Binary:  binaryPath,
+		Args:    []string{"no-such-command-xyz"},
+		Env:     env.Environ(),
+		WorkDir: t.TempDir(),
+	})
+
+	assert.Check(t, result.ExitCode != 0, "expected non-zero exit for unknown command")
+	assert.Check(t, cmp.Contains(result.Stderr, "unknown command"),
+		"expected 'unknown command' in stderr; got: %q", result.Stderr)
+}
+
+// TestExtensionNestedUnknownNotIntercepted verifies that unknown subcommands
+// within a known group (e.g. "circleci pipeline foo") are not dispatched to
+// any extension — only top-level unknown commands are intercepted.
+func TestExtensionNestedUnknownNotIntercepted(t *testing.T) {
+	skip.If(t, runtime.GOOS == "windows", "shell-script extensions are not supported on Windows")
+
+	// Put a circleci-foo extension on PATH to confirm it is NOT invoked.
+	extDir := t.TempDir()
+	buildExtension(t, extDir, "foo")
+
+	env := testenv.New(t)
+	env.Token = testToken
+
+	result := binary.RunCLI(t, binary.RunOpts{
+		Binary:  binaryPath,
+		Args:    []string{"pipeline", "foo"},
+		Env:     withExtDir(env.Environ(), extDir),
+		WorkDir: t.TempDir(),
+	})
+
+	// The key assertion: the extension script prints "args:" — if that appears,
+	// the extension was wrongly invoked. Whether the group shows help or an error
+	// is pre-existing behavior outside this feature's scope.
+	assert.Check(t, !strings.Contains(result.Stdout, "args:"),
+		"extension should NOT have been invoked for a nested unknown command; stdout: %q", result.Stdout)
+}

internal/extension/extension.go

@@ -37,6 +37,7 @@ import (
 	"strings"
 
 	"github.com/CircleCI-Public/circleci-cli-v2/internal/config"
+	clierrors "github.com/CircleCI-Public/circleci-cli-v2/internal/errors"
 	"github.com/CircleCI-Public/circleci-cli-v2/internal/gitremote"
 )
 
@@ -77,7 +78,11 @@ func Run(ctx context.Context, name string, args []string, configPath string) err
 			// Exit with the extension's exit code, not our own error message.
 			os.Exit(cmd.ProcessState.ExitCode())
 		}
-		return fmt.Errorf("extension %q failed: %w", binary, err)
+		return clierrors.New(
+			"extension.exec_failed",
+			"Extension failed",
+			fmt.Sprintf("extension %q could not be executed: %s", binary, err),
+		)
 	}
 	return nil
 }
@@ -110,8 +115,20 @@ func buildEnv(ctx context.Context, configPath string) []string {
 	}
 
 	for k, v := range overlays {
-		if v != "" {
-			env = append(env, k+"="+v)
+		if v == "" {
+			continue
+		}
+		prefix := k + "="
+		replaced := false
+		for i, e := range env {
+			if strings.HasPrefix(e, prefix) {
+				env[i] = prefix + v
+				replaced = true
+				break
+			}
+		}
+		if !replaced {
+			env = append(env, prefix+v)
 		}
 	}
 	return env

main.go

@@ -56,15 +56,24 @@ func run() int {
 		// Before reporting "unknown command", try the implicit extension mechanism:
 		// any executable named "circleci-<name>" in PATH is a valid extension.
 		// Only intercept top-level unknown commands (error ends with `for "circleci"`).
-		if name, ok := rootUnknownCommand(err); ok {
+		if name, ok := rootUnknownCommand(err, rootCmd.Name()); ok {
 			configPath, _ := rootCmd.Flags().GetString("config")
 			extArgs := extensionArgs(name)
 			extErr := extension.Run(ctx, name, extArgs, configPath)
 			if extErr == nil {
 				return clierrors.ExitSuccess
 			}
 			// Extension not found — fall through and show the original cobra error.
-			if !errors.As(extErr, new(*extension.ErrNotFound)) {
+			var notFound *extension.ErrNotFound
+			if !errors.As(extErr, &notFound) {
+				if cliErr, ok := errors.AsType[*clierrors.CLIError](extErr); ok {
+					if jsonFlagPresent() {
+						_, _ = fmt.Fprint(os.Stderr, cliErr.FormatJSON())
+					} else {
+						_, _ = fmt.Fprint(os.Stderr, cliErr.Format())
+					}
+					return cliErr.ExitCode
+				}
 				_, _ = fmt.Fprintln(os.Stderr, extErr)
 				return clierrors.ExitGeneralError
 			}
@@ -87,15 +96,19 @@ func run() int {
 // rootUnknownCommand reports whether err is Cobra's "unknown command" error
 // for the root command specifically (not a nested group). Returns the command
 // name that was not found.
-func rootUnknownCommand(err error) (string, bool) {
+//
+// Note: this relies on Cobra's internal error string format. The suffix uses
+// rootName so binary renames (e.g. "cci") are handled correctly.
+func rootUnknownCommand(err error, rootName string) (string, bool) {
 	msg := err.Error()
 	// Cobra formats this as: unknown command "foo" for "circleci"
 	const prefix = `unknown command "`
 	if !strings.HasPrefix(msg, prefix) {
 		return "", false
 	}
 	// Must be for the root, not a subgroup like "circleci pipeline".
-	if !strings.HasSuffix(msg, `for "circleci"`) {
+	suffix := fmt.Sprintf(` for %q`, rootName)
+	if !strings.HasSuffix(msg, suffix) {
 		return "", false
 	}
 	name, _, ok := strings.Cut(msg[len(prefix):], `"`)
@@ -105,14 +118,42 @@ func rootUnknownCommand(err error) (string, bool) {
 	return name, true
 }
 
+// globalFlagsWithValues is the set of root-level persistent flags that consume
+// the following token as their value (i.e. not boolean flags). We skip over
+// these and their values when scanning os.Args for the extension command name,
+// so that a flag value that happens to equal the extension name is not mistaken
+// for the positional command argument.
+var globalFlagsWithValues = map[string]bool{
+	"--config": true,
+	"-c":       true,
+	"--theme":  true,
+}
+
 // extensionArgs returns the arguments to pass to the extension binary.
-// It scans os.Args for the first non-flag positional argument matching name
-// and returns everything after it.
+// It scans os.Args, skipping global flags and their values, and returns
+// everything after the first positional argument matching name.
 func extensionArgs(name string) []string {
-	for i, arg := range os.Args[1:] {
-		if !strings.HasPrefix(arg, "-") && arg == name {
-			return os.Args[i+2:]
+	args := os.Args[1:]
+	i := 0
+	for i < len(args) {
+		arg := args[i]
+		if strings.HasPrefix(arg, "-") {
+			if strings.Contains(arg, "=") {
+				// --flag=value form: single token, no separate value token
+				i++
+				continue
+			}
+			if globalFlagsWithValues[arg] {
+				i += 2 // skip flag and its value token
+				continue
+			}
+			i++ // boolean flag
+			continue
+		}
+		if arg == name {
+			return args[i+1:]
 		}
+		i++
 	}
 	return nil
 }