Add jobs retry command with optional scope diagnostics

Author: pweiskircher

API.md

@@ -160,6 +160,10 @@ Required scopes for this CLI:
 - `read_build_logs`
 - `read_artifacts`
 
+Optional capability scopes:
+
+- `write_builds` (needed for `jobs.retry`)
+
 ### Success response
 
 ```json
@@ -176,7 +180,8 @@ Required scopes for this CLI:
     ],
     "grantedScopes": 3,
     "missingScopes": [],
-    "ready": true
+    "ready": true,
+    "warnings": []
   },
   "pagination": null,
   "data": {
@@ -199,7 +204,16 @@ Required scopes for this CLI:
       "read_build_logs",
       "read_artifacts"
     ],
-    "missingScopes": []
+    "missingScopes": [],
+    "capabilities": {
+      "jobsRetry": {
+        "requiredScopes": [
+          "write_builds"
+        ],
+        "missingScopes": [],
+        "ready": true
+      }
+    }
   },
   "error": null
 }
@@ -384,6 +398,57 @@ Use `--raw` to keep exact Buildkite payloads.
 }
 ```
 
+## `jobs.retry`
+
+Retry a failed/timed-out job.
+
+Requires `write_builds` scope.
+
+### Request
+
+```json
+{
+  "org": "acme",
+  "pipeline": "web",
+  "buildNumber": 942,
+  "jobId": "0197abcd"
+}
+```
+
+### Success response
+
+```json
+{
+  "ok": true,
+  "apiVersion": "v1",
+  "command": "jobs.retry",
+  "request": {
+    "org": "acme",
+    "pipeline": "web",
+    "buildNumber": 942,
+    "jobId": "0197abcd"
+  },
+  "summary": {
+    "retried": true,
+    "jobId": "0197efgh",
+    "state": "scheduled"
+  },
+  "pagination": null,
+  "data": {
+    "job": {
+      "id": "0197efgh",
+      "type": "script",
+      "name": "Playwright tests",
+      "stepKey": "e2e",
+      "state": "scheduled",
+      "exitStatus": null,
+      "webUrl": "https://buildkite.com/acme/web/builds/942#job-0197efgh"
+    }
+  },
+  "error": null
+}
+```
+
 ## `artifacts.list`
 
 List artifacts for a build, optionally filtered by job.
@@ -541,6 +606,7 @@ List build annotations.
 - `builds.list` -> `GET /v2/builds` or `GET /v2/organizations/{org}/builds` or `GET /v2/organizations/{org}/pipelines/{pipeline}/builds`
 - `builds.get` -> `GET /v2/organizations/{org}/pipelines/{pipeline}/builds/{number}`
 - `jobs.log.get` -> `GET /v2/organizations/{org}/pipelines/{pipeline}/builds/{number}/jobs/{job.id}/log`
+- `jobs.retry` -> `PUT /v2/organizations/{org}/pipelines/{pipeline}/builds/{number}/jobs/{job.id}/retry`
 - `artifacts.list` -> `GET /v2/organizations/{org}/pipelines/{pipeline}/builds/{number}/artifacts` or `GET /v2/organizations/{org}/pipelines/{pipeline}/builds/{number}/jobs/{job.id}/artifacts`
 - `artifacts.download` -> `GET /v2/organizations/{org}/pipelines/{pipeline}/builds/{number}/jobs/{job.id}/artifacts/{id}/download`
 - `annotations.list` -> `GET /v2/organizations/{org}/pipelines/{pipeline}/builds/{number}/annotations`
@@ -552,7 +618,6 @@ These are strong candidates for the next version:
 - `builds.create`
 - `builds.rebuild`
 - `builds.cancel`
-- `jobs.retry`
 - `jobs.unblock`
 - `jobs.env.get`
 - `pipelines.list`

README.md

@@ -7,6 +7,7 @@ A local CLI that queries Buildkite REST APIs and returns LLM-friendly JSON envel
 - List builds.
 - Get one build with job summary.
 - Fetch job logs.
+- Retry failed/timed-out jobs.
 - List artifacts.
 - Download artifacts.
 - List annotations.
@@ -70,21 +71,50 @@ bkci auth status
 bkci builds list --org ORG [--pipeline PIPELINE] [--branch BRANCH] [--state STATE]
 bkci builds get --org ORG --pipeline PIPELINE --build BUILD_NUMBER
 bkci jobs log get --org ORG --pipeline PIPELINE --build BUILD_NUMBER --job JOB_ID
+bkci jobs retry --org ORG --pipeline PIPELINE --build BUILD_NUMBER --job JOB_ID
 bkci artifacts list --org ORG --pipeline PIPELINE --build BUILD_NUMBER [--job JOB_ID]
 bkci artifacts download --org ORG --pipeline PIPELINE --build BUILD_NUMBER [--job JOB_ID] [--artifact-id ID ...] [--glob GLOB] [--out DIR]
 bkci annotations list --org ORG --pipeline PIPELINE --build BUILD_NUMBER
 ```
 
 ## Required token scopes
 
+Baseline scopes:
+
 - `read_builds`
 - `read_build_logs`
 - `read_artifacts`
 
+Additional scope for retrying jobs:
+
+- `write_builds`
+
+## Retry jobs examples
+
+Retry a job:
+
+```bash
+bkci jobs retry --org acme --pipeline web --build 942 --job 0197abcd
+```
+
+If your token is missing `write_builds`, `bkci` returns a clear error envelope (and does not retry):
+
+```json
+{
+  "ok": false,
+  "command": "jobs.retry",
+  "error": {
+    "type": "permission_error",
+    "message": "failed to retry job: token missing required scope(s): write_builds",
+    "code": "missing_scope"
+  }
+}
+```
+
 ## Notes
 
 - Use `--raw` on any command to return raw Buildkite payloads inside the envelope.
-- `bkci auth status` checks token scopes and reports missing required scopes.
+- `bkci auth status` checks token scopes, reports missing required scopes, and warns when optional capability scopes (for example `jobs.retry`) are missing.
 - `jobs log get` strips ANSI/control sequences in normalized mode for cleaner LLM output.
 - Pagination metadata is parsed from Buildkite `Link` headers for list endpoints.
 

src/cli/execute-command.test.ts

@@ -12,6 +12,8 @@ type MockClient = {
   readonly requestJson: (options: {
     readonly path: string;
     readonly query?: Record<string, string | number | null>;
+    readonly method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    readonly body?: unknown;
   }) => Promise<BuildkiteJsonResponse>;
   readonly requestBinary: (options: {
     readonly path: string;
@@ -30,15 +32,16 @@ function createMockClient(options: {
 
   return {
     requestJson: async (request) => {
-      seenPaths.push(request.path);
+      const method = request.method ?? "GET";
+      seenPaths.push(`${method} ${request.path}`);
       const next = jsonQueue.shift() ?? null;
       if (next === null) {
         throw new Error("unexpected json request");
       }
       return next;
     },
     requestBinary: async (request) => {
-      seenPaths.push(request.path);
+      seenPaths.push(`GET ${request.path}`);
       const bytes = binaryByPath[request.path] ?? null;
       if (bytes === null) {
         throw new Error(`unexpected binary request: ${request.path}`);
@@ -78,10 +81,18 @@ test("executeCommand auth.status returns required scope diagnostics", async () =
     grantedScopes: 2,
     missingScopes: ["read_artifacts"],
     ready: false,
+    warnings: ["jobs.retry requires token scope: write_builds"],
   });
 
   const data = result.data as Record<string, unknown>;
   assert.deepEqual(data.missingScopes, ["read_artifacts"]);
+  assert.deepEqual(data.capabilities, {
+    jobsRetry: {
+      requiredScopes: ["write_builds"],
+      missingScopes: ["write_builds"],
+      ready: false,
+    },
+  });
 });
 
 test("executeCommand builds.list normalizes data and pagination", async () => {
@@ -188,6 +199,105 @@ test("executeCommand builds.get computes failed job ids", async () => {
   assert.deepEqual(summary.failedJobIds, ["job-1"]);
 });
 
+test("executeCommand jobs.retry retries job when write_builds scope is present", async () => {
+  const command = parseCliArgs([
+    "jobs",
+    "retry",
+    "--org",
+    "acme",
+    "--pipeline",
+    "web",
+    "--build",
+    "77",
+    "--job",
+    "job-1",
+  ]);
+
+  const seenPaths: Array<string> = [];
+  const client = createMockClient({
+    seenPaths,
+    jsonResponses: [
+      {
+        status: 200,
+        headers: new Headers(),
+        requestId: "req-auth",
+        data: {
+          scopes: ["read_builds", "read_build_logs", "read_artifacts", "write_builds"],
+        },
+      },
+      {
+        status: 200,
+        headers: new Headers(),
+        requestId: "req-retry",
+        data: {
+          id: "job-2",
+          state: "scheduled",
+          name: "tests",
+          type: "script",
+        },
+      },
+    ],
+  });
+
+  const result = await executeCommand({ command, client });
+
+  assert.deepEqual(seenPaths, [
+    "GET /v2/access-token",
+    "PUT /v2/organizations/acme/pipelines/web/builds/77/jobs/job-1/retry",
+  ]);
+
+  assert.deepEqual(result.summary, {
+    retried: true,
+    jobId: "job-2",
+    state: "scheduled",
+  });
+
+  assert.deepEqual(result.data, {
+    job: {
+      id: "job-2",
+      type: "script",
+      name: "tests",
+      stepKey: null,
+      state: "scheduled",
+      exitStatus: null,
+      webUrl: null,
+    },
+  });
+});
+
+test("executeCommand jobs.retry returns permission error when scope is missing", async () => {
+  const command = parseCliArgs([
+    "jobs",
+    "retry",
+    "--org",
+    "acme",
+    "--pipeline",
+    "web",
+    "--build",
+    "77",
+    "--job",
+    "job-1",
+  ]);
+
+  const client = createMockClient({
+    jsonResponses: [
+      {
+        status: 200,
+        headers: new Headers(),
+        requestId: "req-auth",
+        data: {
+          scopes: ["read_builds", "read_build_logs", "read_artifacts"],
+        },
+      },
+    ],
+  });
+
+  await assert.rejects(
+    () => executeCommand({ command, client }),
+    /token missing required scope\(s\): write_builds/
+  );
+});
+
 test("executeCommand artifacts.download fetches and writes files", async () => {
   const outputDir = await mkdtemp(path.join(os.tmpdir(), "bkci-test-"));