[VPEX] localenv: target a specific job task (--job-task <job-id>.<task-key>)

acceptance/localenv/help/output.txt

@@ -15,7 +15,7 @@ Flags:
       --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-id string               job ID to use as the compute target
+      --job-task string             job task to use as the compute target, as <job-id>.<task-key> (the task key is required)
       --serverless-version string   serverless version to use as the compute target (e.g. 5)
 
 Global Flags:

acceptance/localenv/job-classic-check/output.txt

@@ -1,5 +1,5 @@
 
->>> [CLI] environments setup-local --job-id 12345 --dry-run
+>>> [CLI] environments setup-local --job-task 12345.ingest --dry-run
 preflight  ok  check
 resolve    ok  source=job envKey=dbr/15.4.x-scala2.12
 fetch      ok  source=[DATABRICKS_URL]/dbr/15.4.x-scala2.12/pyproject.toml fromCache=false

acceptance/localenv/job-classic-check/script

@@ -1 +1 @@
-trace $CLI environments setup-local --job-id 12345 --dry-run
+trace $CLI environments setup-local --job-task 12345.ingest --dry-run

acceptance/localenv/job-classic-check/test.toml

@@ -3,7 +3,7 @@ EnvMatrix.DATABRICKS_BUNDLE_ENGINE = ["direct"]
 [Env]
 DATABRICKS_LOCALENV_CONSTRAINT_SOURCE = "$DATABRICKS_HOST"
 
-# A classic-compute job (a single job cluster, no serverless environments)
+# A classic task carries its own new_cluster, so --job-task <id>.<task-key>
 # resolves to that cluster's DBR-derived environment key.
 [[Server]]
 Pattern = "GET /api/2.2/jobs/get"
@@ -12,8 +12,8 @@ Response.Body = '''
   "job_id": 12345,
   "settings": {
     "name": "classic-job",
-    "job_clusters": [
-      {"job_cluster_key": "main", "new_cluster": {"spark_version": "15.4.x-scala2.12", "num_workers": 1}}
+    "tasks": [
+      {"task_key": "ingest", "new_cluster": {"spark_version": "15.4.x-scala2.12", "num_workers": 1}}
     ]
   }
 }

acceptance/localenv/job-serverless-check/output.txt

@@ -1,5 +1,5 @@
 
->>> [CLI] environments setup-local --job-id 12345 --dry-run
+>>> [CLI] environments setup-local --job-task 12345.transform --dry-run
 preflight  ok  check
 resolve    ok  source=job envKey=serverless/serverless-v3
 fetch      ok  source=[DATABRICKS_URL]/serverless/serverless-v3/pyproject.toml fromCache=false

acceptance/localenv/job-serverless-check/script

@@ -1 +1 @@
-trace $CLI environments setup-local --job-id 12345 --dry-run
+trace $CLI environments setup-local --job-task 12345.transform --dry-run

acceptance/localenv/job-serverless-check/test.toml

@@ -3,15 +3,19 @@ EnvMatrix.DATABRICKS_BUNDLE_ENGINE = ["direct"]
 [Env]
 DATABRICKS_LOCALENV_CONSTRAINT_SOURCE = "$DATABRICKS_HOST"
 
-# A serverless job pins its environment_version on the environment spec, so the
-# target resolves to that serverless-vN (here v3) rather than defaulting to v5.
+# A serverless task binds an environment_key to one of the job's environments;
+# that environment pins the version, so --job-task <id>.<task-key> resolves to
+# the matching serverless-vN (here v3) directly — no default fallback.
 [[Server]]
 Pattern = "GET /api/2.2/jobs/get"
 Response.Body = '''
 {
   "job_id": 12345,
   "settings": {
     "name": "serverless-job",
+    "tasks": [
+      {"task_key": "transform", "environment_key": "default"}
+    ],
     "environments": [
       {"environment_key": "default", "spec": {"environment_version": "3"}}
     ]

acceptance/localenv/serverless-default-check/output.txt → acceptance/localenv/job-task-foreach/output.txt

@@ -1,8 +1,8 @@
 
->>> [CLI] environments setup-local --job-id 12345 --dry-run
+>>> [CLI] environments setup-local --job-task 12345.fanout --dry-run
 preflight  ok  check
-resolve    ok  source=job envKey=serverless/serverless-v5
-fetch      ok  source=[DATABRICKS_URL]/serverless/serverless-v5/pyproject.toml fromCache=false
+resolve    ok  source=job envKey=serverless/serverless-v3
+fetch      ok  source=[DATABRICKS_URL]/serverless/serverless-v3/pyproject.toml fromCache=false
 merge      ok
 provision  ok
 validate   ok

acceptance/localenv/job-task-foreach/script

@@ -0,0 +1 @@
+trace $CLI environments setup-local --job-task 12345.fanout --dry-run

acceptance/localenv/job-task-foreach/test.toml

@@ -0,0 +1,47 @@
+EnvMatrix.DATABRICKS_BUNDLE_ENGINE = ["direct"]
+
+[Env]
+DATABRICKS_LOCALENV_CONSTRAINT_SOURCE = "$DATABRICKS_HOST"
+
+# A for_each_task wraps the real per-iteration task; its compute lives on the
+# nested task. --job-task resolves against that nested task (here a serverless
+# environment binding), not the empty outer wrapper.
+[[Server]]
+Pattern = "GET /api/2.2/jobs/get"
+Response.Body = '''
+{
+  "job_id": 12345,
+  "settings": {
+    "name": "foreach-job",
+    "tasks": [
+      {
+        "task_key": "fanout",
+        "for_each_task": {
+          "inputs": "[1,2,3]",
+          "task": {"task_key": "inner", "environment_key": "default"}
+        }
+      }
+    ],
+    "environments": [
+      {"environment_key": "default", "spec": {"environment_version": "3"}}
+    ]
+  }
+}
+'''
+
+[[Server]]
+Pattern = "GET /serverless/serverless-v3/pyproject.toml"
+Response.Body = '''
+[project]
+requires-python = ">=3.11"
+
+[dependency-groups]
+dev = ["databricks-connect~=15.4.0"]
+
+[tool.uv]
+constraint-dependencies = ["pyarrow<19"]
+'''
+
+[[Repls]]
+Old = 'uv uv \S+(?: \([^)]+\))?'
+New = 'uv [UV_VERSION]'

acceptance/localenv/job-task-jobcluster/output.txt

@@ -0,0 +1,13 @@
+
+>>> [CLI] environments setup-local --job-task 12345.ingest --dry-run
+preflight  ok  check
+resolve    ok  source=job envKey=dbr/15.4.x-scala2.12
+fetch      ok  source=[DATABRICKS_URL]/dbr/15.4.x-scala2.12/pyproject.toml fromCache=false
+merge      ok
+provision  ok
+validate   ok
+Plan: [TEST_TMP_DIR]/pyproject.toml
+  changed region: requires-python
+  changed region: tool.uv.constraint-dependencies
+  changed region: databricks-connect
+Check complete. No files were modified.

acceptance/localenv/job-task-jobcluster/script

@@ -0,0 +1 @@
+trace $CLI environments setup-local --job-task 12345.ingest --dry-run

acceptance/localenv/job-task-jobcluster/test.toml

@@ -0,0 +1,41 @@
+EnvMatrix.DATABRICKS_BUNDLE_ENGINE = ["direct"]
+
+[Env]
+DATABRICKS_LOCALENV_CONSTRAINT_SOURCE = "$DATABRICKS_HOST"
+
+# A classic task references a shared job cluster by job_cluster_key (rather than
+# an inline new_cluster), so --job-task resolves the version from the job's
+# job_clusters entry.
+[[Server]]
+Pattern = "GET /api/2.2/jobs/get"
+Response.Body = '''
+{
+  "job_id": 12345,
+  "settings": {
+    "name": "jobcluster-job",
+    "tasks": [
+      {"task_key": "ingest", "job_cluster_key": "shared"}
+    ],
+    "job_clusters": [
+      {"job_cluster_key": "shared", "new_cluster": {"spark_version": "15.4.x-scala2.12", "num_workers": 1}}
+    ]
+  }
+}
+'''
+
+[[Server]]
+Pattern = "GET /dbr/15.4.x-scala2.12/pyproject.toml"
+Response.Body = '''
+[project]
+requires-python = ">=3.11"
+
+[dependency-groups]
+dev = ["databricks-connect~=15.4.0"]
+
+[tool.uv]
+constraint-dependencies = ["pyarrow<19"]
+'''
+
+[[Repls]]
+Old = 'uv uv \S+(?: \([^)]+\))?'
+New = 'uv [UV_VERSION]'

acceptance/localenv/job-serverless-version-mismatch/output.txt → acceptance/localenv/job-task-missing-key/output.txt

@@ -1,5 +1,5 @@
 preflight  ok  check
-resolve    error  resolving job 12345: job 12345 has serverless environments with differing versions; pass --serverless-version explicitly to disambiguate
+resolve    error  specify a job task: job 12345 has multiple tasks; specify one: --job-task 12345.<task-key> (available: ingest, transform)
 fetch      pending
 merge      pending
 provision  pending

acceptance/localenv/job-task-missing-key/script

@@ -0,0 +1 @@
+musterr $CLI environments setup-local --job-task 12345 --dry-run

acceptance/localenv/job-task-missing-key/test.toml

@@ -0,0 +1,26 @@
+EnvMatrix.DATABRICKS_BUNDLE_ENGINE = ["direct"]
+
+[Env]
+DATABRICKS_LOCALENV_CONSTRAINT_SOURCE = "$DATABRICKS_HOST"
+
+# A bare --job-task <job-id> (no .<task-key>) is a usage error: a job can bind
+# tasks to different environment versions, so the CLI will not guess which one.
+# The error lists the job's task keys. Reported as E_USAGE at the resolve phase.
+[[Server]]
+Pattern = "GET /api/2.2/jobs/get"
+Response.Body = '''
+{
+  "job_id": 12345,
+  "settings": {
+    "name": "multi-task-job",
+    "tasks": [
+      {"task_key": "ingest", "environment_key": "e1"},
+      {"task_key": "transform", "environment_key": "e2"}
+    ],
+    "environments": [
+      {"environment_key": "e1", "spec": {"environment_version": "3"}},
+      {"environment_key": "e2", "spec": {"environment_version": "4"}}
+    ]
+  }
+}
+'''

acceptance/localenv/job-multicluster-mismatch/output.txt → acceptance/localenv/job-task-unknown/output.txt

@@ -1,5 +1,5 @@
 preflight  ok  check
-resolve    error  resolving job 12345: job 12345 has job clusters with differing spark_version; pass --cluster-id or --serverless-version explicitly to disambiguate
+resolve    error  resolving job task 12345.nope: job 12345 has no task "nope" (available: ingest)
 fetch      pending
 merge      pending
 provision  pending

acceptance/localenv/job-task-unknown/script

@@ -0,0 +1 @@
+musterr $CLI environments setup-local --job-task 12345.nope --dry-run

acceptance/localenv/job-task-unknown/test.toml

@@ -0,0 +1,23 @@
+EnvMatrix.DATABRICKS_BUNDLE_ENGINE = ["direct"]
+
+[Env]
+DATABRICKS_LOCALENV_CONSTRAINT_SOURCE = "$DATABRICKS_HOST"
+
+# A --job-task naming a task key that the job does not define fails at resolve
+# (E_RESOLVE); the message lists the job's actual task keys.
+[[Server]]
+Pattern = "GET /api/2.2/jobs/get"
+Response.Body = '''
+{
+  "job_id": 12345,
+  "settings": {
+    "name": "job-with-tasks",
+    "tasks": [
+      {"task_key": "ingest", "environment_key": "default"}
+    ],
+    "environments": [
+      {"environment_key": "default", "spec": {"environment_version": "3"}}
+    ]
+  }
+}
+'''

acceptance/localenv/job-ambiguous-compute/output.txt → acceptance/localenv/job-task-unpinned/output.txt

@@ -1,5 +1,5 @@
 preflight  ok  check
-resolve    error  resolving job 12345: job 12345 has both serverless environments and job clusters; pass --cluster-id or --serverless-version explicitly to disambiguate
+resolve    error  resolving job task 12345.transform: task "transform" of job 12345 binds environment "default", which records no environment version
 fetch      pending
 merge      pending
 provision  pending

acceptance/localenv/job-task-unpinned/script

@@ -0,0 +1 @@
+musterr $CLI environments setup-local --job-task 12345.transform --dry-run

acceptance/localenv/job-task-unpinned/test.toml

@@ -0,0 +1,25 @@
+EnvMatrix.DATABRICKS_BUNDLE_ENGINE = ["direct"]
+
+[Env]
+DATABRICKS_LOCALENV_CONSTRAINT_SOURCE = "$DATABRICKS_HOST"
+
+# A task whose bound serverless environment records no version cannot be resolved:
+# the job-task path reads the version directly and never falls back to a default
+# (the serverless-vN fallback applies only to the bundle-target path). Fails at
+# resolve (E_RESOLVE); nothing is fetched.
+[[Server]]
+Pattern = "GET /api/2.2/jobs/get"
+Response.Body = '''
+{
+  "job_id": 12345,
+  "settings": {
+    "name": "serverless-job-unpinned",
+    "tasks": [
+      {"task_key": "transform", "environment_key": "default"}
+    ],
+    "environments": [
+      {"environment_key": "default", "spec": {}}
+    ]
+  }
+}
+'''

acceptance/localenv/json-error/output.txt

@@ -35,7 +35,7 @@
   "error": {
     "code": "E_NO_TARGET",
     "failurePhase": "resolve",
-    "message": "No compute target is selected. Select a cluster or serverless target, or pass --cluster-id / --cluster-name / --serverless-version / --job-id",
+    "message": "No compute target is selected. Select a cluster or serverless target, or pass --cluster-id / --cluster-name / --serverless-version / --job-task",
     "diskMutated": false
   },
   "durationMs": 0

acceptance/localenv/no-target/output.txt

@@ -1,5 +1,5 @@
 preflight  ok  uv [UV_VERSION]
-resolve    error  No compute target is selected. Select a cluster or serverless target, or pass --cluster-id / --cluster-name / --serverless-version / --job-id
+resolve    error  No compute target is selected. Select a cluster or serverless target, or pass --cluster-id / --cluster-name / --serverless-version / --job-task
 fetch      pending
 merge      pending
 provision  pending