Deprecate setup-local --constraints-only in favour of --no-dbconnect

.nextchanges/cli/setup-local-deprecate-constraints-only.md

@@ -0,0 +1 @@
+Deprecated the `databricks environments setup-local --constraints-only` flag in favour of the orthogonal `--no-dbconnect`. The flag still works (it remains a hidden alias with identical behaviour) but is hidden from `--help` and now prints a one-line deprecation notice; it will be removed in a later release.

acceptance/localenv/constraints-only-existing/output.txt

@@ -1,5 +1,6 @@
 
 >>> [CLI] environments setup-local --serverless-version 4 --constraints-only --dry-run --output json
+Flag --constraints-only has been deprecated, use --no-dbconnect instead
 {
   "schemaVersion": 1,
   "command": "environments setup-local",

acceptance/localenv/constraints-only/output.txt

@@ -1,5 +1,6 @@
 
 >>> [CLI] environments setup-local --serverless-version 4 --constraints-only --dry-run --output json
+Flag --constraints-only has been deprecated, use --no-dbconnect instead
 {
   "schemaVersion": 1,
   "command": "environments setup-local",

acceptance/localenv/help/output.txt

@@ -18,7 +18,6 @@ Examples:
 Flags:
       --cluster-id string           cluster ID to use as the compute target
       --cluster-name string         cluster name to use as the compute target (resolved to an ID via the Clusters API)
-      --constraints-only            apply the Python version and constraints without adding the databricks-connect dependency
       --dry-run                     compute the plan without writing files or provisioning
   -h, --help                        help for setup-local
       --job-task string             job task to use as the compute target, as <job-id>.<task-key> (the task key is required)

cmd/environments/sync.go

@@ -60,6 +60,11 @@ func addComputeFlags(cmd *cobra.Command) {
 	cmd.Flags().String("serverless-version", "", "serverless version to use as the compute target (e.g. 5)")
 	cmd.Flags().String("job-task", "", "job task to use as the compute target, as <job-id>.<task-key> (the task key is required)")
 	cmd.Flags().Bool("constraints-only", false, "apply the Python version and constraints without adding the databricks-connect dependency")
+	// --constraints-only is superseded by the orthogonal --no-dbconnect (identical
+	// behaviour). Keep it defined so existing scripts and CI keep working, but hide
+	// it from --help and emit a one-line deprecation notice on stderr when it is
+	// used. MarkDeprecated does both; removal is a separate, later step.
+	cmd.Flags().MarkDeprecated("constraints-only", "use --no-dbconnect instead")
 	// The negative flags (--no-constraints, --no-dbconnect, --no-provision) are
 	// orthogonal and compose. --no-dbconnect and the older --constraints-only are
 	// equivalent (both skip the databricks-connect dependency).

cmd/environments/sync_test.go

@@ -0,0 +1,21 @@
+package environments
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestSetupLocalConstraintsOnlyDeprecated pins --constraints-only as a hidden,
+// deprecated alias for --no-dbconnect: the flag is kept defined so scripts and CI
+// that already pass it keep working, but it is hidden from --help and pflag prints
+// a one-line deprecation notice pointing at --no-dbconnect when it is used.
+func TestSetupLocalConstraintsOnlyDeprecated(t *testing.T) {
+	cmd := newSetupLocalCommand()
+
+	f := cmd.Flags().Lookup("constraints-only")
+	require.NotNil(t, f, "--constraints-only must remain defined for backward compatibility")
+	assert.True(t, f.Hidden, "--constraints-only should be hidden from --help")
+	assert.Equal(t, "use --no-dbconnect instead", f.Deprecated, "--constraints-only should carry the deprecation notice")
+}