[pull] trunk from cli:trunk

.github/skills/writing-acceptance-tests/SKILL.md

@@ -11,6 +11,19 @@ creation and cloning without allowing concurrent scripts to interfere.
 Read `acceptance/README.md` and nearby scripts before editing. Test groups are
 discovered from `acceptance/testdata/<group>/`; do not register them manually.
 
+## Declare token capability
+
+Every `.txtar` script must start with exactly one capability declaration:
+
+```txtar
+# requires-user-capability: false
+```
+
+Set the declaration to `true` only when the script requires a user principal,
+such as account SSH/GPG keys, personal-account forks, or user membership APIs.
+Repository and organization operations supported by an installation token
+should use `false`.
+
 ## Choose one repository mode
 
 Every script must contain exactly one declaration:
@@ -120,7 +133,7 @@ Run metadata checks without live credentials:
 
 ```sh
 go test -tags=acceptance \
-  -run '^(TestSelectAcceptanceTestGroups|TestAcceptanceScriptsDeclareFixtureRepository|TestValidateFixtureRepositoryDeclaration|TestFixtureRepositoryManager)$' \
+  -run '^(TestSelectAcceptanceTestGroups|TestFilterAcceptanceScripts|TestTokenHasUserCapability|TestAcceptanceScriptsDeclareUserCapabilityRequirement|TestAcceptanceScriptsDeclareFixtureRepository|TestRequiresUserCapabilityForScript|TestValidateFixtureRepositoryDeclaration|TestFixtureRepositoryManager)$' \
   ./acceptance
 ```
 

acceptance/README.md

@@ -24,6 +24,8 @@ The token to use for authenticating with the `GH_ACCEPTANCE_HOST`. This must alr
 
 It's recommended to create and use a Legacy PAT for this; Fine-Grained PATs do not offer all the necessary privileges required. You can use an OAuth token provided via `gh auth login --web` and can provide it to the acceptance tests via `GH_ACCEPTANCE_TOKEN=$(gh auth token --hostname <host>)` but this can be a bit confusing and annoying if you `gh auth login` again without `-s` and lose the required scopes.
 
+The test harness infers whether a token authenticates a user from GitHub's documented token prefixes. OAuth (`gho_`), classic PAT (`ghp_`), fine-grained PAT (`github_pat_`), and GitHub App user (`ghu_`) tokens provide user capabilities. GitHub App installation (`ghs_`) tokens do not, so scripts marked `requires-user-capability: true` are omitted from unfiltered runs. Explicitly selecting an incompatible script with `GH_ACCEPTANCE_SCRIPT` fails with an error instead.
+
 Managed fixture repositories reduce repository creation by sharing state where
 tests can safely coexist.
 
@@ -76,7 +78,14 @@ The following custom environment variables are made available to the scripts:
 
 #### Script Metadata
 
-Every script must declare exactly one repository fixture mode:
+Every script must begin with a structured header comment declaring whether it
+needs a token that authenticates a user:
+
+```txtar
+# requires-user-capability: false
+```
+
+Every script must also declare exactly one repository fixture mode:
 
 ```txtar
 fixture-repo shared REPO

acceptance/acceptance_test.go

@@ -645,6 +645,8 @@ func validateAcceptanceScripts(t *testing.T, tsEnv testScriptEnv, groups []strin
 		require.NoError(t, err)
 		for _, file := range candidates {
 			require.NoError(t, validateFixtureRepositoryDeclaration(file))
+			_, err := requiresUserCapabilityForScript(file)
+			require.NoError(t, err)
 		}
 	}
 }
@@ -713,19 +715,128 @@ func TestSelectAcceptanceTestGroups(t *testing.T) {
 	}
 }
 
+type acceptanceScript struct {
+	file                   string
+	requiresUserCapability bool
+}
+
+func filterAcceptanceScripts(candidates []acceptanceScript, filtered, hasUserCapability bool) ([]string, string, error) {
+	if filtered && len(candidates) == 0 {
+		return nil, "no selected script belongs to this command directory", nil
+	}
+
+	files := make([]string, 0, len(candidates))
+	for _, candidate := range candidates {
+		if candidate.requiresUserCapability && !hasUserCapability {
+			if filtered {
+				return nil, "", fmt.Errorf("%s requires a token that authenticates a user", candidate.file)
+			}
+			continue
+		}
+		files = append(files, candidate.file)
+	}
+	if len(files) == 0 {
+		return nil, "all scripts require a token that authenticates a user", nil
+	}
+
+	return files, "", nil
+}
+
+func TestFilterAcceptanceScripts(t *testing.T) {
+	userOnly := acceptanceScript{file: "user.txtar", requiresUserCapability: true}
+	compatible := acceptanceScript{file: "installation.txtar"}
+
+	tests := []struct {
+		name              string
+		candidates        []acceptanceScript
+		filtered          bool
+		hasUserCapability bool
+		wantFiles         []string
+		wantSkip          string
+		wantErr           string
+	}{
+		{
+			name:              "user token keeps all scripts",
+			candidates:        []acceptanceScript{userOnly, compatible},
+			hasUserCapability: true,
+			wantFiles:         []string{"user.txtar", "installation.txtar"},
+		},
+		{
+			name:       "installation token omits user-only scripts",
+			candidates: []acceptanceScript{userOnly, compatible},
+			wantFiles:  []string{"installation.txtar"},
+		},
+		{
+			name:       "all incompatible scripts skip",
+			candidates: []acceptanceScript{userOnly},
+			wantSkip:   "all scripts require a token that authenticates a user",
+		},
+		{
+			name:     "empty explicit selection skips",
+			filtered: true,
+			wantSkip: "no selected script belongs to this command directory",
+		},
+		{
+			name:       "explicit compatible selection remains",
+			candidates: []acceptanceScript{compatible},
+			filtered:   true,
+			wantFiles:  []string{"installation.txtar"},
+		},
+		{
+			name:       "explicit incompatible selection errors",
+			candidates: []acceptanceScript{userOnly},
+			filtered:   true,
+			wantErr:    "user.txtar requires a token that authenticates a user",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			files, skipReason, err := filterAcceptanceScripts(tt.candidates, tt.filtered, tt.hasUserCapability)
+			if tt.wantErr != "" {
+				require.EqualError(t, err, tt.wantErr)
+				return
+			}
+			require.NoError(t, err)
+			assert.Equal(t, tt.wantFiles, files)
+			assert.Equal(t, tt.wantSkip, skipReason)
+		})
+	}
+}
+
 func testScriptParamsFor(t *testing.T, tsEnv testScriptEnv, fixtureRepositories *fixtureRepositoryManager, command string) testscript.Params {
 	t.Helper()
 
-	candidates, filtered, err := acceptanceScriptCandidates(tsEnv, command)
+	scriptFiles, filtered, err := acceptanceScriptCandidates(tsEnv, command)
 	if err != nil {
 		t.Fatal(err)
 	}
-	if filtered && len(candidates) == 0 {
-		t.Skipf("testdata/%s: no selected script belongs to this command directory", command)
+
+	candidates := make([]acceptanceScript, 0, len(scriptFiles))
+	for _, file := range scriptFiles {
+		requiresUserCapability, err := requiresUserCapabilityForScript(file)
+		if err != nil {
+			t.Fatal(err)
+		}
+		candidates = append(candidates, acceptanceScript{
+			file:                   file,
+			requiresUserCapability: requiresUserCapability,
+		})
+	}
+
+	files, skipReason, err := filterAcceptanceScripts(candidates, filtered, tsEnv.hasUserCapability)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if skipReason != "" {
+		if filtered {
+			t.Skipf("testdata/%s: %s", command, skipReason)
+		}
+		t.Skip(skipReason)
 	}
 
 	return testscript.Params{
-		Files:               candidates,
+		Files:               files,
 		Setup:               sharedSetup(tsEnv),
 		Cmds:                sharedCmds(tsEnv, fixtureRepositories),
 		RequireExplicitExec: true,
@@ -1174,10 +1285,11 @@ func (e missingEnvError) Error() string {
 }
 
 type testScriptEnv struct {
-	host  string
-	org   string
-	token string
-	user  string
+	host              string
+	org               string
+	token             string
+	user              string
+	hasUserCapability bool
 
 	// scripts optionally narrows a run to named scripts within the command
 	// directory being run. Empty means run every script in the directory.
@@ -1223,6 +1335,11 @@ func (e *testScriptEnv) fromEnv() error {
 	e.host = envMap["GH_ACCEPTANCE_HOST"]
 	e.org = envMap["GH_ACCEPTANCE_ORG"]
 	e.token = envMap["GH_ACCEPTANCE_TOKEN"]
+	var err error
+	e.hasUserCapability, err = tokenHasUserCapability(e.token)
+	if err != nil {
+		return err
+	}
 
 	e.scripts = parseScriptFilter(os.Getenv("GH_ACCEPTANCE_SCRIPT"))
 	e.preserveWorkDir = os.Getenv("GH_ACCEPTANCE_PRESERVE_WORK_DIR") == "true"

acceptance/testdata/api/basic-graphql.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 fixture-repo none
 

acceptance/testdata/api/basic-rest.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 fixture-repo none
 

acceptance/testdata/auth/auth-login-logout.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 fixture-repo none
 

acceptance/testdata/auth/auth-setup-git.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 fixture-repo none
 

acceptance/testdata/auth/auth-status.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 fixture-repo none
 

acceptance/testdata/auth/auth-token.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 fixture-repo none
 

acceptance/testdata/discussion/discussion-comment.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 # Create a repository with a file so it has a default branch
 fixture-repo shared REPO

acceptance/testdata/discussion/discussion-create.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 # Create a repository with a file so it has a default branch
 fixture-repo isolated REPO

acceptance/testdata/discussion/discussion-edit.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 # Create a repository with a file so it has a default branch
 fixture-repo shared REPO

acceptance/testdata/discussion/discussion-list.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 # Create a repository with a file so it has a default branch
 fixture-repo isolated REPO

acceptance/testdata/discussion/discussion-view.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 # Create a repository with a file so it has a default branch
 fixture-repo isolated REPO

acceptance/testdata/extension/extension-env.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 # Verify that gh tells an extension when it is being run as an extension
 
@@ -10,7 +11,8 @@ fixture-repo none
 env EXT_NAME=printenv-${RANDOM_STRING}
 env EXT_DIR=gh-${EXT_NAME}
 
-# Setup a local extension that reports the value of GH_EXTENSION
+# Setup a local extension that reports the extension environment and verifies
+# it can invoke the current gh executable without relying on PATH
 mkdir $EXT_DIR
 mv print-env.sh $EXT_DIR/$EXT_DIR
 chmod 777 $EXT_DIR/$EXT_DIR
@@ -23,19 +25,33 @@ defer gh extension remove $EXT_NAME
 # Verify GH_EXTENSION is set when the extension is run as gh <extension>
 exec gh $EXT_NAME
 stdout 'GH_EXTENSION=1'
+stdout 'GH_PATH was set correctly'
 
 # Verify GH_EXTENSION is set when the extension is run via gh extension exec
 exec gh extension exec $EXT_NAME
 stdout 'GH_EXTENSION=1'
+stdout 'GH_PATH was set correctly'
 
 # Verify GH_EXTENSION is absent when the extension is run standalone
 exec ./$EXT_DIR
 stdout 'GH_EXTENSION=0'
 
-# Verify GH_EXTENSION is documented
+# Verify GH_EXTENSION and GH_PATH are documented
 exec gh help environment
 stdout 'GH_EXTENSION`: set to `1` by gh when it invokes an extension'
+stdout 'GH_PATH`: set the path to the gh executable, useful for when gh can not properly determine'
 
 -- print-env.sh --
 #!/usr/bin/env bash
+set -e
+
 echo "GH_EXTENSION=${GH_EXTENSION:-0}"
+
+if [[ "${GH_EXTENSION:-0}" == "1" ]]; then
+  expected_token=$GH_TOKEN
+  mkdir -p empty-path
+  PATH=$PWD/empty-path
+  actual_token=$("$GH_PATH" auth token --hostname "$GH_HOST")
+  [[ "$actual_token" == "$expected_token" ]]
+  echo "GH_PATH was set correctly"
+fi

acceptance/testdata/extension/extension.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 # Skip if Bash is not available given script extension
 [!exec:bash] skip

acceptance/testdata/gist/gist-create-view-delete.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: true
 
 fixture-repo none
 

acceptance/testdata/gist/gist-edit-rename-list.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: true
 
 fixture-repo none
 

acceptance/testdata/gpg-key/gpg-key.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: true
 
 skip 'it modifies the user''s personal GitHub account GPG keys'
 

acceptance/testdata/issue/issue-comment-edit-last-with-comments.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 # Setup environment variables used for testscript
 

acceptance/testdata/issue/issue-comment-edit-last-without-comments-creates.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 # Setup environment variables used for testscript
 

acceptance/testdata/issue/issue-comment-edit-last-without-comments-errors.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 # Setup environment variables used for testscript
 

acceptance/testdata/issue/issue-comment-new.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 # Setup environment variables used for testscript
 

acceptance/testdata/issue/issue-create-basic.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 # Create a repository with a file so it has a default branch
 fixture-repo shared REPO

acceptance/testdata/issue/issue-create-edit-with-project.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 # Create a repository with a file so it has a default branch
 fixture-repo shared REPO

acceptance/testdata/issue/issue-create-with-metadata.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: true
 
 # Create a repository with a file so it has a default branch
 fixture-repo shared REPO

acceptance/testdata/issue/issue-develop-worktree-cross-repo.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 fixture-repo none
 

acceptance/testdata/issue/issue-develop-worktree.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 # Develop an issue in a fresh worktree, reuse that worktree, and add another
 # worktree after the local branch exists.

acceptance/testdata/issue/issue-list.txtar

@@ -1,3 +1,4 @@
+# requires-user-capability: false
 
 # Create a repository with a file so it has a default branch
 fixture-repo shared REPO