refactor: 🏗️ adding service connection sdk for easier integration of service connection commands

TESTING.md

@@ -80,6 +80,15 @@ Use this pattern as a seed and add more mocks only as the code under test demand
 
 Acceptance tests (`*_acc_test.go`) run against a live Azure DevOps organization using the harness under `internal/test`. They are opt-in and should only be used when unit tests and mocks cannot provide enough confidence.
 
+### Getting started (`AcceptanceTest`)
+
+`inttest.Test` executes a `TestCase` using a `TestContext` created by the harness. The `TestCase.AcceptanceTest` boolean controls which context is used:
+
+- `AcceptanceTest: true` (recommended for all `*_acc_test.go`): uses `inttest.NewAccTestContext(t)` which reads the required `AZDO_ACC_*` environment variables and creates real SDK clients for the configured organization.
+- `AcceptanceTest: false`: uses `inttest.NewTestContext(t)` which generates random placeholder values for `Org`, `PAT`, and `Project`. This is only useful for hermetic unit tests that want a lightweight `util.CmdContext` implementation; it is not suitable for live Azure DevOps operations.
+
+For acceptance tests, always set `AcceptanceTest: true`. Otherwise the harness will still be gated by `AZDO_ACC_TEST=1`, but the generated placeholder org/token values will typically cause confusing failures once your steps attempt real API calls.
+
 ### When to add an acceptance test
 
 - You need to verify a workflow/command (e.g., modifying security permissions) against real data.
@@ -92,20 +101,39 @@ Acceptance tests (`*_acc_test.go`) run against a live Azure DevOps organization
 | ------------------ | ------------------------------------------------------------------------------------------------------ |
 | `AZDO_ACC_TEST=1`  | Enables acceptance tests. Without it, `inttest.Test` skips all steps.                                  |
 | `AZDO_ACC_ORG`     | Organization name used for the session.                                                                |
-| `AZDO_ACC_ORG_URL` | Optional explicit organization URL; defaults to `https://dev.azure.com/<org>`.                         |
 | `AZDO_ACC_PAT`     | Personal Access Token with the scopes required by the test steps.                                      |
 | `AZDO_ACC_PROJECT` | Project name used by acceptance tests that operate on project-scoped resources.                        |
-| `AZDO_ACC_TIMEOUT` | Optional override for the default 60 s timeout. Accepts Go durations (`45s`, `2m`) or integer seconds. |
+| `AZDO_ACC_TIMEOUT` | Optional override for the default 240 s timeout. Accepts Go durations (`45s`, `2m`) or integer seconds. Use `-1` to disable timeouts. |
 
 ### Step-by-step skeleton
 
 1. Place the test in the command package with the `_acc_test.go` suffix.
-2. Wrap your steps in `inttest.Test(t, inttest.TestCase{ Steps: []inttest.Step{ ... } })`.
+2. Wrap your steps in `inttest.Test(t, inttest.TestCase{ AcceptanceTest: true, Steps: []inttest.Step{ ... } })`.
 3. **PreRun**: create or seed live resources (groups, repositories, permissions) using `ctx.ClientFactory()`.
 4. **Run**: construct the command options and call the command’s `run...` helper directly (e.g., `return runCommand(ctx, opts)`).
-5. **Verify**: use `inttest.Poll` to wait for eventual consistency and assert desired state.
+5. **Verify**: use `internal/util/poll.go` (`pollutil.Poll(ctx.Context(), ...)`) to wait for eventual consistency and assert desired state.
 6. **PostRun**: delete or revert all resources you created; aggregate cleanup errors with `errors.Join`.
 
+Minimal scaffold:
+
+```go
+inttest.Test(t, inttest.TestCase{
+	AcceptanceTest: true,
+	PreCheck: func() error {
+		// Validate required inputs (e.g., ensure AZDO_ACC_PROJECT is set when needed).
+		return nil
+	},
+	Steps: []inttest.Step{
+		{
+			PreRun:  func(ctx inttest.TestContext) error { return nil },
+			Run:     func(ctx inttest.TestContext) error { return nil },
+			Verify:  func(ctx inttest.TestContext) error { return nil },
+			PostRun: func(ctx inttest.TestContext) error { return nil },
+		},
+	},
+})
+```
+
 Example shell to execute a single acceptance test:
 ```bash
 AZDO_ACC_TEST=1 \
@@ -119,7 +147,7 @@ Acceptance tests are not run in CI; execute them manually before publishing feat
 
 - `inttest.TestContext` now exposes `Project()` alongside `Org`, `OrgUrl`, and `PAT`. Set `AZDO_ACC_PROJECT` when a test needs to target a specific project and fail fast in `PreRun` if it is missing.
 - Use `TestContext.SetValue(key, value)`/`Value(key)` to propagate data across `PreRun`, `Run`, `Verify`, and `PostRun` without relying on package-level variables. Keys can be simple strings or typed aliases; mimic `context.Context` usage.
-- The helper `inttest.WriteTestFile(path, contents)` creates or truncates files with `0600` permissions and ensures parent directories exist, which is useful for acceptance tests that need temporary credentials or certificates.
+- The helpers `inttest.WriteTestFile(t, contents)` and `inttest.WriteTestFileWithName(t, filename, contents)` create files with `0600` permissions under `t.TempDir()`, which is useful for acceptance tests that need temporary credentials or certificates.
 
 ### Updating Mocks
 

docs/azdo_help_reference.md

@@ -1089,7 +1089,10 @@ Create an Azure Resource Manager service connection
     --subscription-name string            Azure subscription name
 -t, --template string                     Format JSON output using a Go template; see "azdo help formatting"
     --tenant-id string                    Azure tenant ID (e.g., GUID)
--y, --yes                                 Skip confirmation prompts
+    --timeout duration                    Maximum time to wait when --wait or --validate-connection is enabled (default 2m0s)
+    --validate-connection                 Run TestConnection after creation (opt-in)
+    --validate-schema                     Validate auth scheme/params against endpoint type metadata (opt-in)
+    --wait                                Wait until the endpoint reports ready/failed
 ```
 
 Aliases
@@ -1103,13 +1106,19 @@ cr, c, new, n, add, a
 Create a GitHub service endpoint
 
 ```
-    --configuration-id string   Configuration for connecting to the endpoint (use an OAuth/installation configuration). Mutually exclusive with --token.
--q, --jq expression             Filter JSON output using a jq expression
-    --json fields[=*]           Output JSON with the specified fields. Prefix a field with '-' to exclude it.
-    --name string               Name of the service endpoint
--t, --template string           Format JSON output using a Go template; see "azdo help formatting"
-    --token string              Visit https://github.com/settings/tokens to create personal access tokens. Recommended scopes: repo, user, admin:repo_hook. If omitted, you will be prompted for a token when interactive.
-    --url string                GitHub URL (defaults to https://github.com)
+    --configuration-id string             Configuration for connecting to the endpoint (use an OAuth/installation configuration). Mutually exclusive with --token.
+    --description string                  Description for the service endpoint
+    --grant-permission-to-all-pipelines   Grant access permission to all pipelines to use the service connection
+-q, --jq expression                       Filter JSON output using a jq expression
+    --json fields[=*]                     Output JSON with the specified fields. Prefix a field with '-' to exclude it.
+    --name string                         Name of the service endpoint
+-t, --template string                     Format JSON output using a Go template; see "azdo help formatting"
+    --timeout duration                    Maximum time to wait when --wait or --validate-connection is enabled (default 2m0s)
+    --token string                        Visit https://github.com/settings/tokens to create personal access tokens. Recommended scopes: repo, user, admin:repo_hook. If omitted, you will be prompted for a token when interactive.
+    --url string                          GitHub URL (defaults to https://github.com)
+    --validate-connection                 Run TestConnection after creation (opt-in)
+    --validate-schema                     Validate auth scheme/params against endpoint type metadata (opt-in)
+    --wait                                Wait until the endpoint reports ready/failed
 ```
 
 ### `azdo service-endpoint delete [ORGANIZATION/]PROJECT/ID_OR_NAME [flags]`

docs/azdo_service-endpoint_create_azurerm.md

@@ -83,9 +83,21 @@ This command is modeled after the Azure DevOps Terraform Provider's implementati
 
 	Azure tenant ID (e.g., GUID)
 
-* `-y`, `--yes`
+* `--timeout` `duration` (default `"2m0s"`)
 
-	Skip confirmation prompts
+	Maximum time to wait when --wait or --validate-connection is enabled
+
+* `--validate-connection`
+
+	Run TestConnection after creation (opt-in)
+
+* `--validate-schema`
+
+	Validate auth scheme/params against endpoint type metadata (opt-in)
+
+* `--wait`
+
+	Wait until the endpoint reports ready/failed
 
 
 ### ALIASES

docs/azdo_service-endpoint_create_github.md

@@ -14,6 +14,14 @@ Create a GitHub service endpoint using a personal access token (PAT) or an insta
 
 	Configuration for connecting to the endpoint (use an OAuth/installation configuration). Mutually exclusive with --token.
 
+* `--description` `string`
+
+	Description for the service endpoint
+
+* `--grant-permission-to-all-pipelines`
+
+	Grant access permission to all pipelines to use the service connection
+
 * `-q`, `--jq` `expression`
 
 	Filter JSON output using a jq expression
@@ -30,6 +38,10 @@ Create a GitHub service endpoint using a personal access token (PAT) or an insta
 
 	Format JSON output using a Go template; see "azdo help formatting"
 
+* `--timeout` `duration` (default `"2m0s"`)
+
+	Maximum time to wait when --wait or --validate-connection is enabled
+
 * `--token` `string`
 
 	Visit https://github.com/settings/tokens to create personal access tokens. Recommended scopes: repo, user, admin:repo_hook. If omitted, you will be prompted for a token when interactive.
@@ -38,6 +50,18 @@ Create a GitHub service endpoint using a personal access token (PAT) or an insta
 
 	GitHub URL (defaults to https://github.com)
 
+* `--validate-connection`
+
+	Run TestConnection after creation (opt-in)
+
+* `--validate-schema`
+
+	Validate auth scheme/params against endpoint type metadata (opt-in)
+
+* `--wait`
+
+	Wait until the endpoint reports ready/failed
+
 
 ### JSON Fields
 

internal/cmd/security/permission/delete/delete_acc_test.go

@@ -13,6 +13,7 @@ import (
 	"github.com/tmeckel/azdo-cli/internal/cmd/security/permission/shared"
 	inttest "github.com/tmeckel/azdo-cli/internal/test"
 	"github.com/tmeckel/azdo-cli/internal/types"
+	pollutil "github.com/tmeckel/azdo-cli/internal/util"
 )
 
 type aceContainer struct {
@@ -31,6 +32,7 @@ func TestAccDeletePermission(t *testing.T) {
 	var groupIdentity string
 
 	inttest.Test(t, inttest.TestCase{
+		AcceptanceTest: true,
 		Steps: []inttest.Step{
 			{
 				PreRun: func(ctx inttest.TestContext) error {
@@ -103,7 +105,7 @@ func TestAccDeletePermission(t *testing.T) {
 					if err != nil {
 						return err
 					}
-					return inttest.Poll(func() error {
+					return pollutil.Poll(ctx.Context(), func() error {
 						ace, err := shared.FindAccessControlEntry(ctx.Context(), secClient, nsUUID, token, groupIdentity)
 						if err != nil {
 							return err
@@ -117,7 +119,7 @@ func TestAccDeletePermission(t *testing.T) {
 							return nil
 						}
 						return fmt.Errorf("expected ACE to be removed; allow=%d deny=%d", allow, deny)
-					}, inttest.PollOptions{
+					}, pollutil.PollOptions{
 						Tries:   10,
 						Timeout: 30 * time.Second,
 					})

internal/cmd/security/permission/reset/reset_acc_test.go

@@ -13,6 +13,7 @@ import (
 	"github.com/tmeckel/azdo-cli/internal/cmd/security/permission/shared"
 	inttest "github.com/tmeckel/azdo-cli/internal/test"
 	"github.com/tmeckel/azdo-cli/internal/types"
+	pollutil "github.com/tmeckel/azdo-cli/internal/util"
 )
 
 type aceContainer struct {
@@ -44,6 +45,7 @@ func TestAccResetPermission(t *testing.T) {
 	)
 
 	inttest.Test(t, inttest.TestCase{
+		AcceptanceTest: true,
 		Steps: []inttest.Step{
 			{
 				PreRun: func(ctx inttest.TestContext) error {
@@ -119,7 +121,7 @@ func TestAccResetPermission(t *testing.T) {
 						return err
 					}
 
-					return inttest.Poll(func() error {
+					return pollutil.Poll(ctx.Context(), func() error {
 						ace, err := shared.FindAccessControlEntry(ctx.Context(), secClient, nsUUID, token, groupIdentity)
 						if err != nil {
 							return err
@@ -135,7 +137,7 @@ func TestAccResetPermission(t *testing.T) {
 							return fmt.Errorf("unexpected permission state allow=0x%X deny=0x%X", allow, deny)
 						}
 						return nil
-					}, inttest.PollOptions{
+					}, pollutil.PollOptions{
 						Tries:   10,
 						Timeout: 30 * time.Second,
 					})

internal/cmd/security/permission/update/update_acc_test.go

@@ -12,6 +12,7 @@ import (
 
 	"github.com/tmeckel/azdo-cli/internal/cmd/security/permission/shared"
 	inttest "github.com/tmeckel/azdo-cli/internal/test"
+	pollutil "github.com/tmeckel/azdo-cli/internal/util"
 )
 
 func TestAccUpdatePermission(t *testing.T) {
@@ -26,6 +27,7 @@ func TestAccUpdatePermission(t *testing.T) {
 	groupName := fmt.Sprintf("azdo-cli-test-group-%s", uuid.New().String())
 
 	inttest.Test(t, inttest.TestCase{
+		AcceptanceTest: true,
 		Steps: []inttest.Step{
 			{
 				PreRun: func(ctx inttest.TestContext) error {
@@ -72,7 +74,7 @@ func TestAccUpdatePermission(t *testing.T) {
 					if err != nil {
 						return err
 					}
-					return inttest.Poll(func() error {
+					return pollutil.Poll(ctx.Context(), func() error {
 						ace, err := shared.FindAccessControlEntry(ctx.Context(), sec, nsUUID, token, groupIdentity)
 						if err != nil {
 							return err
@@ -87,7 +89,7 @@ func TestAccUpdatePermission(t *testing.T) {
 							return fmt.Errorf("allow mask %d does not contain expected bit 0x2", *ace.Allow)
 						}
 						return nil
-					}, inttest.PollOptions{
+					}, pollutil.PollOptions{
 						Tries:   10,
 						Timeout: 30 * time.Second,
 					})