Add auth setup command and config-file token support

Author: pweiskircher

API.md

@@ -111,6 +111,45 @@ This keeps automation predictable while allowing full passthrough.
 
 ## MVP commands
 
+## `auth.setup`
+
+Store a token in `~/.config/buildkite-cli/auth.json` with strict permissions.
+
+- config directory mode: `0700`
+- auth file mode: `0600`
+
+If `--token` is not provided, `bkci` prompts interactively for a token.
+
+### Request
+
+```json
+{
+  "tokenProvided": false
+}
+```
+
+### Success response
+
+```json
+{
+  "ok": true,
+  "apiVersion": "v1",
+  "command": "auth.setup",
+  "request": {
+    "tokenProvided": false
+  },
+  "summary": {
+    "configured": true,
+    "source": "prompt"
+  },
+  "pagination": null,
+  "data": {
+    "path": "/Users/example/.config/buildkite-cli/auth.json"
+  },
+  "error": null
+}
+```
+
 ## `auth.status`
 
 Read the token details and report whether required scopes are present.
@@ -497,6 +536,7 @@ List build annotations.
 
 ## Mapping to Buildkite REST endpoints
 
+- `auth.setup` -> local filesystem write (`~/.config/buildkite-cli/auth.json`)
 - `auth.status` -> `GET /v2/access-token`
 - `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}`

README.md

@@ -48,9 +48,18 @@ Set one of these environment variables:
 - `BUILDKITE_API_TOKEN`
 - `BK_TOKEN`
 
+Or run interactive setup to store a token in:
+
+- `~/.config/buildkite-cli/auth.json`
+
+```bash
+bkci auth setup
+```
+
 ## Commands
 
 ```bash
+bkci auth setup [--token TOKEN]
 bkci auth status
 bkci builds list --org ORG [--pipeline PIPELINE] [--branch BRANCH] [--state STATE]
 bkci builds get --org ORG --pipeline PIPELINE --build BUILD_NUMBER

src/cli/execute-command.ts

@@ -551,26 +551,30 @@ export async function executeCommand(options: {
     };
   }
 
-  const response = await options.client.requestJson({
-    path: `/v2/organizations/${options.command.args.org}/pipelines/${options.command.args.pipeline}/builds/${options.command.args.buildNumber}/annotations`,
-  });
+  if (options.command.name === "annotations.list") {
+    const response = await options.client.requestJson({
+      path: `/v2/organizations/${options.command.args.org}/pipelines/${options.command.args.pipeline}/builds/${options.command.args.buildNumber}/annotations`,
+    });
 
-  if (options.command.global.raw) {
+    if (options.command.global.raw) {
+      return {
+        request,
+        summary: {},
+        pagination: null,
+        data: response.data,
+      };
+    }
+
+    const annotations = asArray(response.data).map((entry) => mapAnnotation(entry));
     return {
       request,
-      summary: {},
+      summary: {
+        count: annotations.length,
+      },
       pagination: null,
-      data: response.data,
+      data: annotations,
     };
   }
 
-  const annotations = asArray(response.data).map((entry) => mapAnnotation(entry));
-  return {
-    request,
-    summary: {
-      count: annotations.length,
-    },
-    pagination: null,
-    data: annotations,
-  };
+  throw new Error(`unsupported command for executeCommand: ${options.command.name}`);
 }

src/cli/parse-args.test.ts

@@ -3,6 +3,16 @@ import test from "node:test";
 
 import { parseCliArgs } from "./parse-args.js";
 
+test("parseCliArgs parses auth setup with token", () => {
+  const parsed = parseCliArgs(["auth", "setup", "--token", "abc123"]);
+
+  assert.equal(parsed.name, "auth.setup");
+  assert.equal(parsed.global.raw, false);
+  assert.deepEqual(parsed.args, {
+    token: "abc123",
+  });
+});
+
 test("parseCliArgs parses auth status", () => {
   const parsed = parseCliArgs(["auth", "status"]);
 

src/cli/parse-args.ts

@@ -2,6 +2,7 @@ import type {
   AnnotationsListArgs,
   ArtifactsDownloadArgs,
   ArtifactsListArgs,
+  AuthSetupArgs,
   AuthStatusArgs,
   BuildsGetArgs,
   BuildsListArgs,
@@ -60,6 +61,25 @@ function parseGlobalOptions(tokens: Array<string>): { readonly global: ParsedGlo
   };
 }
 
+function parseAuthSetup(tokens: Array<string>): AuthSetupArgs {
+  let token: string | null = null;
+  let index = 0;
+
+  while (index < tokens.length) {
+    const current = tokens[index] ?? "";
+    if (current === "--token") {
+      const next = readOptionValue(tokens, index, current);
+      token = normalizeValue(next.value);
+      index = next.nextIndex;
+      continue;
+    }
+
+    throw new Error(`unknown argument for auth setup: ${current}`);
+  }
+
+  return { token };
+}
+
 function parseAuthStatus(tokens: Array<string>): AuthStatusArgs {
   if (tokens.length > 0) {
     throw new Error(`unknown argument for auth status: ${tokens[0] ?? ""}`);
@@ -413,6 +433,14 @@ export function parseCliArgs(argv: Array<string>): ParsedCommand {
 
   const [group, action, ...rest] = tokens;
 
+  if (group === "auth" && action === "setup") {
+    return {
+      name: "auth.setup",
+      global: globalParsed.global,
+      args: parseAuthSetup(rest),
+    };
+  }
+
   if (group === "auth" && action === "status") {
     return {
       name: "auth.status",
@@ -476,6 +504,7 @@ export function parseCliArgs(argv: Array<string>): ParsedCommand {
 }
 
 export const USAGE_TEXT = `Usage:
+  bkci auth setup [--token TOKEN]
   bkci auth status [--raw]
   bkci builds list --org ORG [--pipeline PIPELINE] [--branch BRANCH] [--state STATE] [--page N] [--per-page N] [--raw]
   bkci builds get --org ORG --pipeline PIPELINE --build BUILD_NUMBER [--raw]

src/cli/types.ts

@@ -2,6 +2,10 @@ export type ParsedGlobalOptions = {
   readonly raw: boolean;
 };
 
+export type AuthSetupArgs = {
+  readonly token: string | null;
+};
+
 export type AuthStatusArgs = Record<string, never>;
 
 export type BuildsListArgs = {
@@ -52,6 +56,7 @@ export type AnnotationsListArgs = {
 };
 
 export type ParsedCommand =
+  | { readonly name: "auth.setup"; readonly global: ParsedGlobalOptions; readonly args: AuthSetupArgs }
   | { readonly name: "auth.status"; readonly global: ParsedGlobalOptions; readonly args: AuthStatusArgs }
   | { readonly name: "builds.list"; readonly global: ParsedGlobalOptions; readonly args: BuildsListArgs }
   | { readonly name: "builds.get"; readonly global: ParsedGlobalOptions; readonly args: BuildsGetArgs }

src/core/types.ts

@@ -1,4 +1,5 @@
 export type CommandName =
+  | "auth.setup"
   | "auth.status"
   | "builds.list"
   | "builds.get"

src/index.ts

@@ -2,10 +2,12 @@
 
 import { executeCommand } from "./cli/execute-command.js";
 import { parseCliArgs, USAGE_TEXT } from "./cli/parse-args.js";
+import type { ParsedCommand } from "./cli/types.js";
 import { failureEnvelope, successEnvelope } from "./core/envelope.js";
 import { toApiError } from "./core/errors.js";
 import { createBuildkiteClient } from "./shell/buildkite-client.js";
 import { getBuildkiteTokenFromEnv } from "./shell/env.js";
+import { setupAuthConfig } from "./shell/auth-config.js";
 
 function printJson(value: unknown): void {
   process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
@@ -15,13 +17,23 @@ function shouldShowHelp(argv: Array<string>): boolean {
   return argv.includes("--help") || argv.includes("-h");
 }
 
+function getSafeRequest(command: ParsedCommand): Record<string, unknown> {
+  if (command.name === "auth.setup") {
+    return {
+      tokenProvided: command.args.token !== null,
+    };
+  }
+
+  return { ...command.args };
+}
+
 async function main(argv: Array<string>): Promise<number> {
   if (argv.length === 0 || shouldShowHelp(argv)) {
     process.stdout.write(`${USAGE_TEXT}\n`);
     return 0;
   }
 
-  let parsed;
+  let parsed: ParsedCommand;
   try {
     parsed = parseCliArgs(argv);
   } catch (error) {
@@ -30,6 +42,37 @@ async function main(argv: Array<string>): Promise<number> {
     return 1;
   }
 
+  if (parsed.name === "auth.setup") {
+    try {
+      const result = await setupAuthConfig({
+        token: parsed.args.token,
+      });
+
+      const output = successEnvelope({
+        command: parsed.name,
+        request: getSafeRequest(parsed),
+        summary: {
+          configured: true,
+          source: result.source,
+        },
+        pagination: null,
+        data: {
+          path: result.path,
+        },
+      });
+      printJson(output);
+      return 0;
+    } catch (error) {
+      const output = failureEnvelope({
+        command: parsed.name,
+        request: getSafeRequest(parsed),
+        error: toApiError(error),
+      });
+      printJson(output);
+      return 1;
+    }
+  }
+
   try {
     const token = getBuildkiteTokenFromEnv();
     const client = createBuildkiteClient(token);
@@ -51,7 +94,7 @@ async function main(argv: Array<string>): Promise<number> {
   } catch (error) {
     const output = failureEnvelope({
       command: parsed.name,
-      request: { ...parsed.args },
+      request: getSafeRequest(parsed),
       error: toApiError(error),
     });
     printJson(output);

src/shell/auth-config.test.ts

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { getAuthConfigPath, readTokenFromConfig, setupAuthConfig } from "./auth-config.js";
+
+test("setupAuthConfig writes auth.json with strict permissions", async () => {
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), "bkci-auth-"));
+  const authPath = path.join(tempDir, "config", "buildkite-cli", "auth.json");
+  const previousPath = process.env.BKCI_AUTH_PATH;
+
+  try {
+    process.env.BKCI_AUTH_PATH = authPath;
+
+    const setupResult = await setupAuthConfig({ token: "token-123" });
+    assert.equal(setupResult.path, authPath);
+    assert.equal(setupResult.source, "argument");
+
+    const content = await readFile(authPath, "utf8");
+    const parsed = JSON.parse(content) as { token?: string };
+    assert.equal(parsed.token, "token-123");
+    assert.equal(readTokenFromConfig(), "token-123");
+    assert.equal(getAuthConfigPath(), authPath);
+
+    const fileInfo = await stat(authPath);
+    const fileMode = fileInfo.mode & 0o777;
+    assert.equal(fileMode, 0o600);
+
+    const directoryInfo = await stat(path.dirname(authPath));
+    const directoryMode = directoryInfo.mode & 0o777;
+    assert.equal(directoryMode, 0o700);
+  } finally {
+    if (previousPath === undefined) {
+      delete process.env.BKCI_AUTH_PATH;
+    } else {
+      process.env.BKCI_AUTH_PATH = previousPath;
+    }
+    await rm(tempDir, { recursive: true, force: true });
+  }
+});