@knpkv/jira-cli 1.2.3 → 1.4.0

package/src/AttachmentService.ts

@@ -20,7 +20,7 @@ export interface UploadAttachmentInput {
   readonly mediaType?: string | undefined
 }
 
-export interface AttachmentServiceShape {
+export interface AttachmentServiceContract {
   readonly uploadToIssue: (
     issueIdOrKey: string,
     input: UploadAttachmentInput
@@ -29,7 +29,7 @@ export interface AttachmentServiceShape {
 
 export class AttachmentService extends Context.Service<
   AttachmentService,
-  AttachmentServiceShape
+  AttachmentServiceContract
 >()("@knpkv/jira-cli/AttachmentService") {}
 
 const UploadedAttachmentSchema = Schema.Struct({
@@ -41,7 +41,7 @@ const UploadedAttachmentSchema = Schema.Struct({
   size: Schema.optional(Schema.NullOr(Schema.Number))
 })
 
-const decodeUploadedAttachment = (raw: unknown): Effect.Effect<Attachment, JiraApiError> =>
+const decodeUploadedAttachment = <UnparsedInput>(raw: UnparsedInput): Effect.Effect<Attachment, JiraApiError> =>
   Schema.decodeUnknownEffect(UploadedAttachmentSchema)(raw).pipe(
     Effect.mapError((cause) => new JiraApiError({ message: "Jira returned an invalid attachment response", cause })),
     Effect.flatMap((record) => {
@@ -62,7 +62,7 @@ const decodeUploadedAttachment = (raw: unknown): Effect.Effect<Attachment, JiraA
     })
   )
 
-const decodeFirstUploadedAttachment = (raw: unknown): Effect.Effect<Attachment, JiraApiError> => {
+const decodeFirstUploadedAttachment = <UnparsedInput>(raw: UnparsedInput): Effect.Effect<Attachment, JiraApiError> => {
   if (!Array.isArray(raw)) {
     return Effect.fail(new JiraApiError({ message: "Jira did not return an attachment array" }))
   }
@@ -78,7 +78,7 @@ const make = Effect.gen(function*() {
   const fs = yield* FileSystem.FileSystem
   const path = yield* Path.Path
 
-  const uploadToIssue: AttachmentServiceShape["uploadToIssue"] = (issueIdOrKey, input) =>
+  const uploadToIssue: AttachmentServiceContract["uploadToIssue"] = (issueIdOrKey, input) =>
     Effect.gen(function*() {
       const bytes = yield* fs.readFile(input.filePath).pipe(
         Effect.mapError((cause) =>
@@ -89,7 +89,7 @@ const make = Effect.gen(function*() {
       const result = yield* client.uploadAttachment(issueIdOrKey, {
         bytes,
         filename,
-        ...(input.mediaType === undefined ? {} : { mediaType: input.mediaType })
+        ...(!(input.mediaType === undefined) && { mediaType: input.mediaType })
       }).pipe(
         Effect.mapError((cause) =>
           new JiraApiError({ message: `Failed to upload attachment to ${issueIdOrKey}`, cause })

package/src/IssueService.ts

@@ -8,7 +8,7 @@
  *   like `extractDisplayName` and `extractNameArray`.
  * - **Rendered fields**: Requests include `expand: "renderedFields"` to get HTML-rendered
  *   descriptions and comments, falling back to plain text.
- * - **Pagination guard**: {@link IssueServiceShape.searchAll} iterates pages using
+ * - **Pagination guard**: {@link IssueServiceContract.searchAll} iterates pages using
  *   `nextPageToken` with a MAX_PAGES (1000) safety limit.
  *
  * **Common tasks**
@@ -24,6 +24,7 @@ import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
 import * as Predicate from "effect/Predicate"
+import * as Schema from "effect/Schema"
 import { JiraApiError } from "./JiraCliError.js"
 
 /**
@@ -114,19 +115,174 @@ interface SearchJqlResponse {
   readonly nextPageToken?: string
 }
 
-const recordOrEmpty = (value: unknown): Readonly<Record<PropertyKey, unknown>> =>
-  Predicate.isReadonlyObject(value) ? value : {}
+const JsonObject = Schema.Record(Schema.String, Schema.Json)
+const isJsonObject = Schema.is(JsonObject)
 
-const recordArray = (value: unknown): ReadonlyArray<Readonly<Record<PropertyKey, unknown>>> =>
-  Array.isArray(value) ? value.filter(Predicate.isReadonlyObject) : []
+const recordOrEmpty = <UnparsedInput>(value: UnparsedInput): Readonly<Record<string, Schema.Json>> =>
+  isJsonObject(value) ? value : {}
 
-const parseSearchJqlResponse = (value: unknown): SearchJqlResponse => {
+const recordArray = <UnparsedInput>(value: UnparsedInput): ReadonlyArray<Readonly<Record<string, Schema.Json>>> =>
+  Array.isArray(value) ? value.filter(isJsonObject) : []
+
+const parseSearchJqlResponse = <UnparsedInput>(value: UnparsedInput): SearchJqlResponse => {
   const record = recordOrEmpty(value)
-  const nextPageToken = typeof record.nextPageToken === "string" ? record.nextPageToken : undefined
+  const nextPageToken = Predicate.isString(record.nextPageToken) ? record.nextPageToken : undefined
   return {
     issues: Array.isArray(record.issues) ? record.issues : [],
-    isLast: typeof record.isLast === "boolean" ? record.isLast : nextPageToken === undefined,
-    ...(nextPageToken !== undefined ? { nextPageToken } : {})
+    isLast: Predicate.isBoolean(record.isLast) ? record.isLast : nextPageToken === undefined,
+    ...((nextPageToken !== undefined) && { nextPageToken })
+  }
+}
+
+/**
+ * Edits to apply to an issue's list-valued fields.
+ *
+ * `add`/`remove` are incremental and `set` replaces. Prefer the incremental pair:
+ * `fixVersions` and `labels` are **sets**, so a `set` that forgets an existing
+ * value silently drops it — the failure mode when scripting a release scope.
+ *
+ * An empty array reads as "not supplied", not as "clear the field". The CLI's
+ * repeatable flags use `Options.atLeast(0)`, which reports an absent flag as
+ * `[]`, so treating `[]` as a replacement would turn every unpassed flag into a
+ * destructive clear. The consequence is that clearing a field outright is not
+ * currently expressible; it needs an explicit `--clear-*` flag (or a
+ * presence-aware option type) rather than a reinterpretation of `[]`.
+ *
+ * @category Types
+ */
+export interface EditIssueInput {
+  readonly addFixVersions?: ReadonlyArray<string>
+  readonly removeFixVersions?: ReadonlyArray<string>
+  readonly setFixVersions?: ReadonlyArray<string>
+  readonly addLabels?: ReadonlyArray<string>
+  readonly removeLabels?: ReadonlyArray<string>
+  readonly setLabels?: ReadonlyArray<string>
+}
+
+/** Any JSON value, matching what the generated client accepts for field values. */
+type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | ReadonlyArray<JsonValue>
+  | { readonly [key: string]: JsonValue }
+
+/** One entry in Jira's `update` map. */
+interface FieldOperation {
+  readonly add?: JsonValue
+  readonly remove?: JsonValue
+}
+
+/** A `PUT /issue/{key}` body: `fields` replaces, `update` applies operations. */
+interface EditIssuePayload {
+  readonly fields?: { readonly [field: string]: JsonValue }
+  readonly update?: { readonly [field: string]: ReadonlyArray<FieldOperation> }
+}
+
+/**
+ * One list-valued field's edits, plus how to render a value for it — Jira wants
+ * `{ name }` objects for fixVersions but bare strings for labels.
+ */
+interface FieldEditSpec {
+  readonly field: string
+  /** Flag stem, so an error can quote the flag the caller actually typed. */
+  readonly flag: string
+  readonly set: ReadonlyArray<string> | undefined
+  readonly add: ReadonlyArray<string> | undefined
+  readonly remove: ReadonlyArray<string> | undefined
+  readonly wrap: (value: string) => JsonValue
+}
+
+/**
+ * Outcome of {@link buildEditIssuePayload}: either a body to send, or the
+ * reason the requested edit is not expressible as one.
+ *
+ * Tagged rather than discriminated by property presence, so a caller matches on
+ * `_tag` and a future third outcome cannot narrow silently.
+ *
+ * @category Types
+ */
+export type EditIssuePayloadResult =
+  | { readonly _tag: "Payload"; readonly payload: EditIssuePayload }
+  | { readonly _tag: "Invalid"; readonly reason: string }
+
+/**
+ * Build the `PUT /issue/{key}` body for an {@link EditIssueInput}.
+ *
+ * Incremental edits go through Jira's `update` verb rather than a
+ * read-modify-write on `fields`: the server applies them atomically, so a
+ * concurrent edit cannot be clobbered and no extra GET is needed.
+ *
+ * Jira rejects a field that appears in both `fields` and `update`, and the error
+ * it returns does not name the field — so that combination is caught here with a
+ * message that does.
+ *
+ * Pure so the payload shape can be tested without the API.
+ *
+ * @category Utilities
+ */
+export const buildEditIssuePayload = (
+  input: EditIssueInput
+): EditIssuePayloadResult => {
+  const fields: Record<string, JsonValue> = {}
+  const update: Record<string, ReadonlyArray<FieldOperation>> = {}
+
+  const specs: ReadonlyArray<FieldEditSpec> = [
+    {
+      field: "fixVersions",
+      flag: "fix-version",
+      set: input.setFixVersions,
+      add: input.addFixVersions,
+      remove: input.removeFixVersions,
+      // fixVersions entries are objects keyed by name.
+      wrap: (name) => ({ name })
+    },
+    {
+      field: "labels",
+      flag: "label",
+      set: input.setLabels,
+      add: input.addLabels,
+      remove: input.removeLabels,
+      // Labels are bare strings.
+      wrap: (label) => label
+    }
+  ]
+
+  for (const spec of specs) {
+    // An empty repeatable flag arrives as `[]`, which means "not passed" rather
+    // than "replace with nothing" — treating it as a set would clear the field.
+    const set = spec.set !== undefined && spec.set.length > 0 ? spec.set : undefined
+    const increments = [
+      ...(spec.add ?? []).map((value) => ({ add: spec.wrap(value) })),
+      ...(spec.remove ?? []).map((value) => ({ remove: spec.wrap(value) }))
+    ]
+    if (set !== undefined && increments.length > 0) {
+      return {
+        _tag: "Invalid",
+        reason: `--${spec.flag} cannot be combined with --add-${spec.flag}/--remove-${spec.flag}; ` +
+          `--${spec.flag} replaces the whole list.`
+      }
+    }
+    if (set !== undefined) fields[spec.field] = set.map(spec.wrap)
+    else if (increments.length > 0) update[spec.field] = increments
+  }
+
+  const hasFields = Object.keys(fields).length > 0
+  const hasUpdate = Object.keys(update).length > 0
+  if (!hasFields && !hasUpdate) {
+    return {
+      _tag: "Invalid",
+      reason:
+        "Nothing to edit. Pass at least one of --add-fix-version, --remove-fix-version, --fix-version, --add-label, --remove-label or --label."
+    }
+  }
+  return {
+    _tag: "Payload",
+    payload: {
+      ...(hasFields && { fields }),
+      ...(hasUpdate && { update })
+    }
   }
 }
 
@@ -135,7 +291,7 @@ const parseSearchJqlResponse = (value: unknown): SearchJqlResponse => {
  *
  * @category Services
  */
-export interface IssueServiceShape {
+export interface IssueServiceContract {
   /** Get a single issue by key */
   readonly getByKey: (key: string) => Effect.Effect<Issue, JiraApiError>
   /** Search issues by JQL query */
@@ -145,6 +301,11 @@ export interface IssueServiceShape {
     jql: string,
     options?: { readonly maxResults?: number }
   ) => Effect.Effect<ReadonlyArray<Issue>, JiraApiError>
+  /**
+   * Edit an issue's list-valued fields (fixVersions, labels) and return the
+   * issue as it stands afterwards. Needs `write:jira-work`.
+   */
+  readonly edit: (key: string, input: EditIssueInput) => Effect.Effect<Issue, JiraApiError>
 }
 
 /**
@@ -166,7 +327,7 @@ export interface IssueServiceShape {
  */
 export class IssueService extends Context.Service<
   IssueService,
-  IssueServiceShape
+  IssueServiceContract
 >()("@knpkv/jira-cli/IssueService") {}
 
 const FIELDS = [
@@ -189,12 +350,12 @@ const FIELDS = [
 /**
  * Extract string from a field that may be an object with displayName/name.
  */
-const extractDisplayName = (field: unknown): string | null => {
+const extractDisplayName = <UnparsedInput>(field: UnparsedInput): string | null => {
   if (field === null || field === undefined) return null
-  if (typeof field === "string") return field
+  if (Predicate.isString(field)) return field
   if (Predicate.isReadonlyObject(field)) {
-    if (typeof field.displayName === "string") return field.displayName
-    if (typeof field.name === "string") return field.name
+    if (Predicate.isString(field.displayName)) return field.displayName
+    if (Predicate.isString(field.name)) return field.name
   }
   return null
 }
@@ -202,13 +363,13 @@ const extractDisplayName = (field: unknown): string | null => {
 /**
  * Extract array of strings from a field that may be array of objects with name.
  */
-const extractNameArray = (field: unknown): ReadonlyArray<string> => {
+const extractNameArray = <UnparsedInput>(field: UnparsedInput): ReadonlyArray<string> => {
   if (!Array.isArray(field)) return []
   return field
     .map((item) => {
-      if (typeof item === "string") return item
+      if (Predicate.isString(item)) return item
       if (Predicate.isReadonlyObject(item)) {
-        if (typeof item.name === "string") return item.name
+        if (Predicate.isString(item.name)) return item.name
       }
       return null
     })
@@ -218,7 +379,7 @@ const extractNameArray = (field: unknown): ReadonlyArray<string> => {
 /**
  * Parse date from unknown value, returning epoch date if invalid.
  */
-const parseDate = (val: unknown): Date => {
+const parseDate = <UnparsedInput>(val: UnparsedInput): Date => {
   const str = String(val ?? "")
   if (!str) return new Date(0)
   const date = new Date(str)
@@ -228,7 +389,7 @@ const parseDate = (val: unknown): Date => {
 /**
  * Map IssueBean from API to our Issue type.
  */
-const mapIssue = (bean: Readonly<Record<PropertyKey, unknown>>, baseUrl: string): Issue => {
+const mapIssue = (bean: Readonly<Record<string, Schema.Json>>, baseUrl: string): Issue => {
   const fields = recordOrEmpty(bean.fields)
   const renderedFields = recordOrEmpty(bean.renderedFields)
   const key = String(bean["key"] ?? "")
@@ -240,7 +401,7 @@ const mapIssue = (bean: Readonly<Record<PropertyKey, unknown>>, baseUrl: string)
     ? recordArray(attachmentField).map((att) => {
       const mediaType = normalizeAttachmentMediaType(
         undefined,
-        typeof att["mimeType"] === "string" ? att["mimeType"] : null
+        Predicate.isString(att["mimeType"]) ? att["mimeType"] : null
       )
       return {
         id: String(att["id"] ?? ""),
@@ -259,7 +420,7 @@ const mapIssue = (bean: Readonly<Record<PropertyKey, unknown>>, baseUrl: string)
   const renderedComments = recordArray(recordOrEmpty(renderedFields.comment).comments)
 
   // Build map of rendered comments by ID for accurate matching
-  const renderedMap = new Map<string, Record<string, unknown>>()
+  const renderedMap = new Map<string, Record<string, Schema.Json>>()
   for (const r of renderedComments) {
     const rId = String(r["id"] ?? "")
     if (rId) renderedMap.set(rId, r)
@@ -273,14 +434,14 @@ const mapIssue = (bean: Readonly<Record<PropertyKey, unknown>>, baseUrl: string)
     return {
       id: commentId,
       author: extractDisplayName(author) ?? "Unknown",
-      body: typeof renderedBody === "string" ? renderedBody : String(c["body"] ?? ""),
+      body: Predicate.isString(renderedBody) ? renderedBody : String(c["body"] ?? ""),
       created: parseDate(c["created"]),
       updated: parseDate(c["updated"])
     }
   })
 
   // Use rendered description (HTML) if available
-  const description = typeof renderedFields["description"] === "string"
+  const description = Predicate.isString(renderedFields["description"])
     ? renderedFields["description"]
     : String(fields["description"] ?? "")
 
@@ -305,7 +466,8 @@ const mapIssue = (bean: Readonly<Record<PropertyKey, unknown>>, baseUrl: string)
   }
 }
 
-const mapIssueUnknown = (bean: unknown, baseUrl: string): Issue => mapIssue(recordOrEmpty(bean), baseUrl)
+const mapIssueUnknown = <UnparsedInput>(bean: UnparsedInput, baseUrl: string): Issue =>
+  mapIssue(recordOrEmpty(bean), baseUrl)
 
 const make = Effect.gen(function*() {
   const client = yield* JiraApiClient
@@ -331,7 +493,7 @@ const make = Effect.gen(function*() {
       params: {
         jql,
         maxResults,
-        ...(nextPageToken ? { nextPageToken } : {}),
+        ...(nextPageToken && { nextPageToken }),
         fields: FIELDS,
         expand: "renderedFields"
       }
@@ -393,7 +555,32 @@ const make = Effect.gen(function*() {
       return allIssues
     })
 
-  return IssueService.of({ getByKey, search, searchAll })
+  const edit = (key: string, input: EditIssueInput): Effect.Effect<Issue, JiraApiError> =>
+    Effect.gen(function*() {
+      const built = buildEditIssuePayload(input)
+      if (built._tag === "Invalid") return yield* Effect.fail(new JiraApiError({ message: built.reason }))
+      yield* client.editIssue(key, { payload: built.payload }).pipe(
+        Effect.mapError((cause) => new JiraApiError({ message: `Failed to edit issue ${key}`, cause }))
+      )
+      // The 204 carries no body, so re-read to report the resulting state.
+      //
+      // Past this point the edit is already committed, so a failed read-back must
+      // not be reported as a failed edit: a caller told "edit failed" may redo a
+      // change that already landed. `returnIssue` would close the window, but the
+      // endpoint takes no `fields`, so the returned issue can silently omit what
+      // `getByKey` asks for — quietly wrong data in place of a loud error.
+      return yield* getByKey(key).pipe(
+        Effect.mapError((cause) =>
+          new JiraApiError({
+            message: `Edited issue ${key}, but reading it back failed, so the result below is unverified. ` +
+              `The edit was applied — do not repeat it.`,
+            cause
+          })
+        )
+      )
+    })
+
+  return IssueService.of({ getByKey, search, searchAll, edit })
 })
 
 /**

package/src/JiraAuth.ts

@@ -59,15 +59,15 @@ import * as Context from "effect/Context"
 import * as Crypto from "effect/Crypto"
 import * as Deferred from "effect/Deferred"
 import * as Effect from "effect/Effect"
+import * as HttpClient from "effect/http/HttpClient"
 import * as Layer from "effect/Layer"
 import * as Option from "effect/Option"
 import type * as PlatformError from "effect/PlatformError"
+import { ChildProcessSpawner } from "effect/process"
 import * as Redacted from "effect/Redacted"
 import * as Ref from "effect/Ref"
-import * as HttpClient from "effect/unstable/http/HttpClient"
-import { ChildProcessSpawner } from "effect/unstable/process"
 import { HttpServerFactoryLive } from "./internal/NodeLayers.js"
-import { startCallbackServer } from "./internal/oauthServer.js"
+import { callbackUrl, startCallbackServer } from "./internal/oauthServer.js"
 import { openBrowser } from "./internal/openBrowser.js"
 import type { AuthMissingError } from "./JiraCliError.js"
 import { authMissing } from "./JiraCliError.js"
@@ -78,8 +78,9 @@ const JIRA_CLI_SCOPES = [
   "read:jira-work",
   // Edit issues and write worklogs.
   "write:jira-work",
-  // Edit a version (e.g. its description) via `PUT /rest/api/3/version/{id}` and
-  // manage version "Related work" links (`/rest/api/3/version/{id}/relatedwork`).
+  // Create a version (`POST /rest/api/3/version`), edit one (e.g. its
+  // description) via `PUT /rest/api/3/version/{id}`, and manage version
+  // "Related work" links (`/rest/api/3/version/{id}/relatedwork`).
   "manage:jira-project",
   // Resolve account IDs to display names for Driver/Contributors/Approvers.
   "read:jira-user",
@@ -253,27 +254,58 @@ const make = Effect.gen(function*() {
     Effect.gen(function*() {
       const config = yield* loadOAuthConfigOp()
       if (config === null) {
-        return yield* Effect.fail(
-          new OAuthError({
-            step: "authorize",
-            cause: "OAuth not configured. Run 'jira auth configure' first."
-          })
-        )
+        return yield* new OAuthError({
+          step: "authorize",
+          cause: "OAuth not configured. Run 'jira auth configure' first."
+        })
       }
       return config
     })
 
+  // Atlassian rotates refresh tokens: the response carries a replacement and
+  // the one we sent is consumed server-side. Interrupting between the
+  // round-trip and `saveTokenOp` therefore destroys the credential — the next
+  // refresh fails and `getAccessToken` below reacts by deleting the token file,
+  // so the user is silently logged out and has to run `jira auth login` again.
+  //
+  // Interruption is routine here, not hypothetical: this runs during layer
+  // construction on every CLI invocation, and jcf's nvim statusline kills the
+  // process on `VimLeave`. So the grant and the persist are atomic.
+  //
+  // The region carries its own deadline rather than relying on a caller's.
+  // `Effect.timeout` is a race, and racing an uninterruptible loser means
+  // waiting for it — an outer bound would go inert and, worse, an
+  // uninterruptible region with no deadline of its own absorbs SIGINT/SIGTERM
+  // entirely (`NodeRuntime.runMain`'s signal handlers only interrupt the main
+  // fiber), leaving a process that ignores Ctrl-C. The deadline forked inside
+  // the region is itself interruptible, so it does bound this.
+  //
+  // Abandoning the round-trip cannot prove the grant did not land: Atlassian
+  // may consume the refresh token and rotate it after we have stopped
+  // listening, and no client-side deadline changes that. So the deadline is
+  // paired with the rule in `getAccessToken` below — a refresh that fails
+  // without a 4xx never deletes the stored token. The credential survives to be
+  // retried, and only a real rejection ends the session.
+  const REFRESH_TIMEOUT = "30 seconds"
+
   const refreshTokenImpl = (
     token: OAuthToken,
     config: OAuthConfig
   ): Effect.Effect<OAuthToken, OAuthError | FileSystemError | HomeDirectoryError | PlatformError.PlatformError> =>
-    Effect.gen(function*() {
-      const updated = yield* refreshToken(token, config).pipe(
-        Effect.provide(Layer.succeed(HttpClient.HttpClient, httpClient))
-      )
-      yield* saveTokenOp(updated)
-      return updated
-    })
+    Effect.uninterruptible(
+      Effect.gen(function*() {
+        const updated = yield* refreshToken(token, config).pipe(
+          Effect.provide(Layer.succeed(HttpClient.HttpClient, httpClient)),
+          Effect.timeout(REFRESH_TIMEOUT),
+          Effect.catchTag(
+            "TimeoutError",
+            () => Effect.fail(new OAuthError({ step: "refresh", cause: `no response within ${REFRESH_TIMEOUT}` }))
+          )
+        )
+        yield* saveTokenOp(updated)
+        return updated
+      })
+    )
 
   const revokeTokenImpl = (
     token: OAuthToken,
@@ -317,6 +349,7 @@ const make = Effect.gen(function*() {
             clientId: config.clientId,
             state,
             port,
+            redirectUri: callbackUrl(port),
             scopes: JIRA_CLI_SCOPES,
             codeChallenge
           })
@@ -338,7 +371,11 @@ const make = Effect.gen(function*() {
       )
 
       yield* Console.log("Exchanging code for tokens...")
-      const tokens = yield* exchangeCodeForTokens(code, config, { port, codeVerifier }).pipe(
+      const tokens = yield* exchangeCodeForTokens(code, config, {
+        port,
+        redirectUri: callbackUrl(port),
+        codeVerifier
+      }).pipe(
         Effect.provide(Layer.succeed(HttpClient.HttpClient, httpClient))
       )
 
@@ -348,12 +385,10 @@ const make = Effect.gen(function*() {
       )
 
       if (sites.length === 0) {
-        return yield* Effect.fail(
-          new OAuthError({
-            step: "authorize",
-            cause: "No Jira sites found for this account"
-          })
-        )
+        return yield* new OAuthError({
+          step: "authorize",
+          cause: "No Jira sites found for this account"
+        })
       }
 
       let site: (typeof sites)[number]
@@ -363,12 +398,10 @@ const make = Effect.gen(function*() {
           const matched = sites.find((s) => s.url === options.siteUrl)
           if (!matched) {
             const available = sites.map((s) => `  - ${s.name}: ${s.url}`).join("\n")
-            return yield* Effect.fail(
-              new OAuthError({
-                step: "authorize",
-                cause: `Site '${options.siteUrl}' not found. Available sites:\n${available}`
-              })
-            )
+            return yield* new OAuthError({
+              step: "authorize",
+              cause: `Site '${options.siteUrl}' not found. Available sites:\n${available}`
+            })
           }
           site = matched
         } else {
@@ -425,7 +458,7 @@ const make = Effect.gen(function*() {
     Effect.gen(function*() {
       const token = yield* loadTokenOp()
       if (token === null) {
-        return yield* Effect.fail(authMissing())
+        return yield* authMissing()
       }
 
       const nowMs = yield* Clock.currentTimeMillis
@@ -448,19 +481,50 @@ const make = Effect.gen(function*() {
 
       const refresh = Effect.gen(function*() {
         const config = yield* getConfig()
-        yield* Console.log("Token expired, refreshing...")
+        // stderr, not stdout: this fires from inside layer construction, so it
+        // lands ahead of whatever the command prints. On `--json` that used to
+        // put a line of prose in front of the document, and the release
+        // automation parsing it failed *after* the remote writes had happened.
+        yield* Console.error("Token expired, refreshing...")
         return yield* refreshTokenImpl(token, config)
       }).pipe(
         Effect.catchTag("OAuthError", (error) => {
-          if (error.step === "refresh") {
+          // Discard the stored credential only when Atlassian actually rejected
+          // it. A refresh can fail without saying anything about the token —
+          // transport error, timeout, interruption — and in those cases the
+          // grant may even have been consumed server-side, so the one thing we
+          // must not do is delete the replacement's only trail. Deleting on any
+          // `step === "refresh"` failure turned a flaky network into a silent
+          // logout, which is worse than retrying and is unrecoverable. On a 4xx
+          // the token is genuinely dead and re-login is the only way forward.
+          // Not every failure is a verdict on the token, and not even every
+          // 4xx is. `429` is the one this most needs to survive — several
+          // `jira`/`jcf` processes on an expired token hit the endpoint
+          // together, one wins the rotation and the rest are rate-limited —
+          // while `408`/`425` restate the timeout case and `407` and other
+          // middlebox replies never came from Atlassian at all.
+          //
+          // Status alone is still too coarse. `refreshToken` sends the client
+          // credentials in the body, so a wrong or rotated `clientSecret` comes
+          // back as `400 invalid_client`; deleting the token there destroys a
+          // working credential over a config problem, and the re-login it forces
+          // would fail the same way until `jira auth configure` is run. Only
+          // `invalid_grant` means the stored token itself is spent, and that is
+          // the only thing that ends the session — on a `403` too, since a bare
+          // 403 is just as likely to come from a proxy or WAF as from Atlassian
+          // revoking anything. An unparseable body leaves `errorCode` absent and
+          // the token in place.
+          const { errorCode, status } = error
+          const rejected = errorCode === "invalid_grant" && (status === 400 || status === 403)
+          if (error.step === "refresh" && rejected) {
             return Effect.gen(function*() {
               yield* deleteTokenOp()
-              return yield* Effect.fail(
-                new OAuthError({
-                  step: "refresh",
-                  cause: "Refresh token expired. Please run 'jira auth login' to re-authenticate."
-                })
-              )
+              return yield* new OAuthError({
+                step: "refresh",
+                cause: "Refresh token expired. Please run 'jira auth login' to re-authenticate.",
+                status,
+                errorCode
+              })
             })
           }
           return Effect.fail(error)
@@ -486,7 +550,7 @@ const make = Effect.gen(function*() {
     Effect.gen(function*() {
       const token = yield* loadTokenOp()
       if (token === null) {
-        return yield* Effect.fail(authMissing())
+        return yield* authMissing()
       }
       return token.cloud_id
     })
@@ -498,7 +562,7 @@ const make = Effect.gen(function*() {
     Effect.gen(function*() {
       const token = yield* loadTokenOp()
       if (token === null) {
-        return yield* Effect.fail(authMissing())
+        return yield* authMissing()
       }
       return token.site_url
     })