@knpkv/atlassian-common 1.5.0 → 1.7.0

package/src/cli-auth/authCommand.ts

@@ -0,0 +1,227 @@
+/**
+ * The `auth` command group every Atlassian CLI exposes, built once over its {@link AtlassianCliAuth}.
+ *
+ * **Mental model**
+ *
+ * - **One descriptor, two readers.** The CLI passes the same {@link AtlassianCliDescriptor} it built
+ *   its auth from, so the setup instructions list exactly the scopes `auth login` requests. A second,
+ *   hand-written list is how a setup that cannot log in happens: Atlassian rejects an authorization
+ *   request naming a scope the app lacks.
+ * - **Only presentation is configured.** The heading the product's scopes sit under in the
+ *   developer console, and what to call a site in `--site`.
+ * - **A browser that does not open is an error.** The URL is printed first, so a headless or SSH
+ *   user can still finish by hand; the exit code just stops claiming it worked.
+ *
+ * @module
+ */
+import { Argument, Command, Flag, Prompt } from "effect/cli"
+import * as Console from "effect/Console"
+import type * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import type { AtlassianCliAuth, AtlassianCliDescriptor } from "./AtlassianCliAuth.js"
+import { openBrowser } from "./openBrowser.js"
+
+const CREATE_APP_URL = "https://developer.atlassian.com/console/myapps/create-3lo-app/"
+const CONSOLE_APPS_URL = "https://developer.atlassian.com/console/myapps/"
+const CALLBACK_URL = "http://localhost:8585/callback"
+
+/** The part of an Atlassian CLI's auth the `auth` commands drive. */
+export type AuthCommandService = Pick<
+  AtlassianCliAuth<never>,
+  | "configure"
+  | "login"
+  | "logout"
+  | "getActiveProfile"
+  | "listProfiles"
+  | "switchProfile"
+  | "removeProfile"
+>
+
+/** What only the product decides about how its `auth` commands read. */
+export interface AuthCommandOptions {
+  /** Developer-console heading the product's scopes live under, e.g. `"Jira API"`. */
+  readonly apiSection: string
+}
+
+/**
+ * The scopes to enable on the OAuth app, by console section. `read:me` is a User Identity scope;
+ * `offline_access` is requested at authorize time but is not an app permission, so it is omitted.
+ */
+export const scopeInstructions = (descriptor: AtlassianCliDescriptor, apiSection: string): string => {
+  const section = (heading: string, scopes: ReadonlyArray<string>): ReadonlyArray<string> =>
+    scopes.length === 0 ? [] : [`   - ${heading}:`, ...scopes.map((scope) => `       ${scope}`)]
+  const permissions = descriptor.scopes.filter((scope) => scope !== "offline_access")
+  return [
+    ...section(apiSection, permissions.filter((scope) => scope !== "read:me")),
+    ...section("User Identity API", permissions.filter((scope) => scope === "read:me"))
+  ].join("\n")
+}
+
+/** Print the URL, then try to open it; a browser that never opened fails the command. */
+const visit = (url: string) => Console.log(`Opening ${url}`).pipe(Effect.andThen(openBrowser(url)))
+
+/** Build `<cli> auth` with create, manage, configure, login, logout, status, profiles, use, remove. */
+export const makeAuthCommand = <I, S extends AuthCommandService>(
+  service: Context.Key<I, S>,
+  descriptor: AtlassianCliDescriptor,
+  options: AuthCommandOptions
+) => {
+  const withAuth = <A, Err, R>(f: (auth: S) => Effect.Effect<A, Err, R>) => Effect.flatMap(Effect.service(service), f)
+  const loginHint = `${descriptor.commandName} auth login`
+
+  const create = Command.make("create", {}, () =>
+    Effect.gen(function*() {
+      yield* Console.log(`
+Creating OAuth app in Atlassian Developer Console...
+
+1. Browser will open to create a new OAuth 2.0 (3LO) app
+2. Enter app name (e.g., "${descriptor.productName} CLI")
+3. After creation, go to "Permissions" and add:
+${scopeInstructions(descriptor, options.apiSection)}
+4. Go to "Authorization" and set callback URL:
+   ${CALLBACK_URL}
+5. Go to "Settings" and copy Client ID and Secret
+6. Run: ${descriptor.commandName} auth configure --client-id <ID> --client-secret <SECRET>
+`)
+      yield* visit(CREATE_APP_URL)
+    })).pipe(Command.withDescription("Create OAuth app in Atlassian Developer Console"))
+
+  // Opens the app list, not the app: the console addresses an app by an id that is not the OAuth
+  // client id, and the client id is the only app identifier the CLI stores.
+  const manage = Command.make("manage", {}, () =>
+    Effect.gen(function*() {
+      yield* Console.log(`
+Opening the Atlassian Developer Console app list...
+
+Select your OAuth app, then under "Permissions" make sure every scope below is
+enabled. \`${loginHint}\` requests all of them, and Atlassian rejects an
+authorization request naming a scope the app does not have — so a missing scope
+here fails the login itself, not just the command that needed it.
+
+${scopeInstructions(descriptor, options.apiSection)}
+
+Under "Authorization", the callback URL must be:
+   ${CALLBACK_URL}
+
+After adding scopes, run: ${loginHint}
+`)
+      yield* visit(CONSOLE_APPS_URL)
+    })).pipe(Command.withDescription("Open the Atlassian Developer Console to edit the OAuth app's scopes"))
+
+  const configure = Command.make(
+    "configure",
+    {
+      clientId: Flag.String("client-id").pipe(
+        Flag.withDescription("OAuth client ID from Atlassian Developer Console"),
+        Flag.optional
+      ),
+      clientSecret: Flag.String("client-secret").pipe(Flag.withDescription("OAuth client secret"), Flag.optional)
+    },
+    ({ clientId, clientSecret }) =>
+      withAuth((auth) =>
+        Effect.gen(function*() {
+          const id = Option.isSome(clientId)
+            ? clientId.value
+            : yield* Prompt.String({ message: "Enter OAuth client ID:" })
+          const secret = Option.isSome(clientSecret)
+            ? clientSecret.value
+            : yield* Prompt.String({ message: "Enter OAuth client secret:" })
+          yield* auth.configure({ clientId: id, clientSecret: secret })
+          yield* Console.log(`OAuth configured. Run '${loginHint}' to authenticate.`)
+        })
+      )
+  ).pipe(Command.withDescription("Configure OAuth client credentials"))
+
+  const login = Command.make(
+    "login",
+    {
+      site: Flag.String("site").pipe(
+        Flag.withDescription(`${descriptor.productName} site URL to use (for accounts with multiple sites)`),
+        Flag.optional
+      )
+    },
+    ({ site }) =>
+      withAuth((auth) =>
+        Effect.gen(function*() {
+          const sites = yield* auth.login(Option.isSome(site) ? { siteUrl: site.value } : undefined)
+          if (Array.isArray(sites) && sites.length > 0) {
+            yield* Console.log("\nRe-run with --site to select a specific site.")
+          }
+        })
+      )
+  ).pipe(Command.withDescription("Authenticate with Atlassian via OAuth"))
+
+  const logout = Command.make(
+    "logout",
+    {},
+    () => withAuth((auth) => auth.logout().pipe(Effect.andThen(Console.log("Logged out"))))
+  ).pipe(
+    Command.withDescription("Remove stored authentication")
+  )
+
+  const status = Command.make("status", {}, () =>
+    withAuth((auth) =>
+      Effect.gen(function*() {
+        const profile = yield* auth.getActiveProfile()
+        if (profile === null) {
+          return yield* Console.log(`Not logged in. Use '${loginHint}' to authenticate.`)
+        }
+        const user = profile.token.user
+        yield* Console.log(`Active profile: ${profile.name}`)
+        yield* Console.log(`Account: ${user !== undefined ? `${user.name} (${user.email})` : "unknown user"}`)
+        yield* Console.log(`Site: ${profile.token.site_url}`)
+        yield* Console.log(`Profile ID: ${profile.id}`)
+      })
+    )).pipe(Command.withDescription("Show authentication status"))
+
+  const profiles = Command.make("profiles", {}, () =>
+    withAuth((auth) =>
+      Effect.gen(function*() {
+        const [stored, active] = yield* Effect.all([auth.listProfiles(), auth.getActiveProfile()])
+        if (stored.length === 0) {
+          return yield* Console.log(`No auth profiles. Use '${loginHint}' to authenticate.`)
+        }
+        for (const profile of stored) {
+          yield* Console.log(`${active?.id === profile.id ? "*" : " "} ${profile.id}`)
+          yield* Console.log(`    ${profile.name}`)
+          yield* Console.log(`    ${profile.token.site_url}`)
+        }
+      })
+    )).pipe(Command.withDescription("List stored auth profiles"))
+
+  const profile = Argument.String("profile").pipe(
+    Argument.withDescription("Profile ID, name, site URL, cloud ID, or account ID")
+  )
+
+  const use = Command.make(
+    "use",
+    { profile },
+    ({ profile }) =>
+      withAuth((auth) =>
+        Effect.flatMap(
+          auth.switchProfile(profile),
+          (selected) =>
+            Console.log(selected === null ? `Profile not found: ${profile}` : `Active profile: ${selected.name}`)
+        )
+      )
+  ).pipe(Command.withDescription("Switch active auth profile"))
+
+  const remove = Command.make(
+    "remove",
+    { profile },
+    ({ profile }) =>
+      withAuth((auth) =>
+        Effect.flatMap(
+          auth.removeProfile(profile),
+          (removed) =>
+            Console.log(removed === null ? `Profile not found: ${profile}` : `Removed profile: ${removed.name}`)
+        )
+      )
+  ).pipe(Command.withDescription("Remove stored auth profile"))
+
+  return Command.make("auth").pipe(
+    Command.withDescription("Manage OAuth authentication"),
+    Command.withSubcommands([create, manage, configure, login, logout, status, profiles, use, remove])
+  )
+}

package/src/cli-auth/index.ts

@@ -0,0 +1,20 @@
+/**
+ * OAuth2 login and token refresh for Atlassian command-line tools.
+ *
+ * Separate from `./auth` because it carries a Node callback server and a
+ * browser launcher; `./auth` stays platform-neutral for server-side consumers.
+ *
+ * @module
+ */
+export {
+  type AccessibleSite,
+  type AtlassianCliAuth,
+  type AtlassianCliAuthOptions,
+  type AtlassianCliDescriptor,
+  type LoginOptions,
+  makeAtlassianCliAuth
+} from "./AtlassianCliAuth.js"
+export { type AuthCommandOptions, type AuthCommandService, makeAuthCommand, scopeInstructions } from "./authCommand.js"
+export { HttpServerFactoryLive, NodeCliAuthLive } from "./internal/NodeLayers.js"
+export { type HttpServerFactory, HttpServerFactoryTag, makeHttpServerFactory } from "./internal/oauthServer.js"
+export { BrowserOpenError, openBrowser } from "./openBrowser.js"

package/src/cli-auth/internal/NodeLayers.ts

@@ -0,0 +1,25 @@
+/**
+ * Node.js adapters for cli-auth: the OAuth callback server and token storage — the
+ * only cli-auth file importing `@effect/platform-node`.
+ *
+ * @internal
+ */
+import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem"
+import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer"
+import * as NodePath from "@effect/platform-node/NodePath"
+import * as Layer from "effect/Layer"
+import { createServer } from "node:http"
+import { HomeDirectoryLive } from "../../config/ConfigPaths.js"
+import { makeHttpServerFactory } from "./oauthServer.js"
+
+export const HttpServerFactoryLive = makeHttpServerFactory(
+  (options) => NodeHttpServer.layerServer(createServer, options)
+)
+
+/** Everything `makeAtlassianCliAuth` needs on Node besides HTTP client, spawner and Crypto. */
+export const NodeCliAuthLive = Layer.mergeAll(
+  HttpServerFactoryLive,
+  NodeFileSystem.layer,
+  NodePath.layer,
+  HomeDirectoryLive
+)

package/src/cli-auth/internal/oauthServer.ts

@@ -0,0 +1,168 @@
+/**
+ * Local HTTP callback server for OAuth2 authorization code capture.
+ *
+ * **Mental model**
+ *
+ * - **Scope-owned lifecycle**: {@link startCallbackServer} returns a `codePromise`
+ *   (Deferred). The server validates the CSRF `state` parameter, resolves the
+ *   Deferred with the authorization code, and stops when its enclosing scope closes.
+ * - **Port auto-discovery**: Tries default port 8585, increments on conflict up to 8594.
+ * - **Ready before return**: the handler is installed before the port is handed back,
+ *   so the caller never advertises a callback URL nothing answers.
+ *
+ * @internal
+ */
+import * as Context from "effect/Context"
+import * as Deferred from "effect/Deferred"
+import * as Effect from "effect/Effect"
+import { HttpRouter, HttpServer, HttpServerRequest, HttpServerResponse } from "effect/http"
+import type * as HttpServerError from "effect/http/HttpServerError"
+import * as Layer from "effect/Layer"
+import { NetAddress } from "effect/net"
+import * as Schema from "effect/Schema"
+import * as Scope from "effect/Scope"
+import { OAuthError } from "../../auth/OAuthErrors.js"
+
+const DEFAULT_PORT = 8585
+const MAX_PORT = 8594
+type HttpServerInstance = Effect.Success<typeof HttpServer.HttpServer>
+
+/**
+ * Creates the platform HTTP server for one listen attempt. The Node adapter is
+ * {@link HttpServerFactoryLive}; tests substitute ephemeral or failing servers.
+ */
+export interface HttpServerFactory {
+  readonly createServerLayer: (options: CallbackServerListenOptions) => Layer.Layer<
+    HttpServer.HttpServer,
+    HttpServerError.ServeError,
+    never
+  >
+}
+
+export interface CallbackServerListenOptions {
+  readonly host: "localhost"
+  readonly port: number
+}
+
+export const callbackServerListenOptions = (port: number): CallbackServerListenOptions => ({
+  host: "localhost",
+  port
+})
+
+export const callbackUrl = (port: number): string => `http://localhost:${port}/callback`
+
+export class HttpServerFactoryTag extends Context.Service<
+  HttpServerFactoryTag,
+  HttpServerFactory
+>()("@knpkv/atlassian-common/cli-auth/HttpServerFactory") {}
+
+/** Builds a {@link HttpServerFactoryTag} layer from a per-attempt server layer. */
+export const makeHttpServerFactory = (
+  createLayerFn: (
+    options: CallbackServerListenOptions
+  ) => Layer.Layer<HttpServer.HttpServer, HttpServerError.ServeError, never>
+): Layer.Layer<HttpServerFactoryTag> =>
+  Layer.succeed(HttpServerFactoryTag, {
+    createServerLayer: createLayerFn
+  })
+
+export interface CallbackServerResult {
+  /** Resolves with the authorization code, or fails with the provider's error. */
+  readonly codePromise: Effect.Effect<string, OAuthError>
+  /** The port the server is listening on */
+  readonly port: number
+}
+
+const AddressInUseCause = Schema.Struct({
+  code: Schema.Literal("EADDRINUSE")
+})
+
+const isAddressInUse = (error: HttpServerError.ServeError): boolean => Schema.is(AddressInUseCause)(error.cause)
+
+const page = (heading: string, body: string) =>
+  HttpServerResponse.html(`<html><body><h1>${heading}</h1><p>${body}</p></body></html>`)
+
+/**
+ * Start a local HTTP server to receive the OAuth callback for `expectedState`.
+ *
+ * Fails with one `OAuthError` (step `authorize`) when no port in range can be
+ * bound; the server stops when the enclosing scope closes.
+ */
+export const startCallbackServer = (
+  expectedState: string
+): Effect.Effect<CallbackServerResult, OAuthError, HttpServerFactoryTag | Scope.Scope> =>
+  Effect.gen(function*() {
+    const factory = yield* HttpServerFactoryTag
+    const deferred = yield* Deferred.make<string, OAuthError>()
+    const scope = yield* Effect.scope
+
+    // Map to OAuthError once, outside the retry, so a run of occupied ports
+    // does not nest one OAuthError inside another.
+    const buildServer = (port: number): Effect.Effect<HttpServerInstance, HttpServerError.ServeError> =>
+      Layer.build(factory.createServerLayer(callbackServerListenOptions(port))).pipe(
+        Scope.provide(scope),
+        Effect.map((context) => Context.get(context, HttpServer.HttpServer)),
+        Effect.catchIf(
+          (error) => isAddressInUse(error) && port < MAX_PORT,
+          () => buildServer(port + 1)
+        )
+      )
+
+    const server = yield* buildServer(DEFAULT_PORT).pipe(
+      Effect.mapError((cause) => new OAuthError({ step: "authorize", cause }))
+    )
+
+    if (!NetAddress.isInetAddress(server.address)) {
+      return yield* new OAuthError({ step: "authorize", cause: "OAuth callback server must listen on a TCP port" })
+    }
+    const port = server.address.port
+
+    const router = yield* HttpRouter.make
+    yield* router.add(
+      "GET",
+      "/callback",
+      Effect.gen(function*() {
+        const req = yield* HttpServerRequest.HttpServerRequest
+        const url = new URL(req.url, callbackUrl(port))
+        const code = url.searchParams.get("code")
+        const state = url.searchParams.get("state")
+        const error = url.searchParams.get("error")
+        const errorDescription = url.searchParams.get("error_description")
+
+        if (state !== expectedState) {
+          return page("Security Error", "State verification failed.").pipe(HttpServerResponse.setStatus(403))
+        }
+
+        if (error !== null && error !== "") {
+          // An empty description is no description: report the error code instead.
+          yield* Deferred.fail(
+            deferred,
+            new OAuthError({
+              step: "authorize",
+              cause: errorDescription === null || errorDescription === "" ? error : errorDescription
+            })
+          )
+          return page("Authorization Failed", "You can close this window.")
+        }
+
+        if (code === null || code === "") {
+          yield* Deferred.fail(deferred, new OAuthError({ step: "authorize", cause: "No authorization code received" }))
+          return page("Error", "No authorization code received.")
+        }
+
+        yield* Deferred.succeed(deferred, code)
+        return page("Success!", "You can close this window and return to the terminal.")
+      })
+    )
+
+    // Installs the handler in this scope and returns; a failure to install
+    // surfaces here rather than leaving the caller waiting on a dead server.
+    yield* HttpServer.serveEffect(router.asHttpEffect()).pipe(
+      Effect.provideService(HttpServer.HttpServer, server)
+    )
+
+    return {
+      codePromise: Deferred.await(deferred),
+      port
+    }
+  })

package/src/cli-auth/openBrowser.ts

@@ -0,0 +1,47 @@
+/**
+ * Cross-platform browser launcher backed by Effect child process services.
+ *
+ * Tries `open`, then `xdg-open`, then `rundll32.exe`, stopping at the first that
+ * exits 0. A launcher that is missing or exits non-zero falls through to the next;
+ * when none succeeds the last failure is reported, typed, so the caller decides
+ * whether a browser that never opened is fatal.
+ *
+ * @module
+ */
+import * as Data from "effect/Data"
+import * as Effect from "effect/Effect"
+import type * as PlatformError from "effect/PlatformError"
+import { ChildProcess, ChildProcessSpawner } from "effect/process"
+
+/** A launcher ran but reported failure (for example `xdg-open` with no browser on a headless host). */
+export class BrowserOpenError extends Data.TaggedError("BrowserOpenError")<{
+  readonly command: string
+  readonly exitCode: number
+}> {}
+
+const run = (
+  command: string,
+  args: ReadonlyArray<string>
+): Effect.Effect<void, BrowserOpenError | PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner> =>
+  Effect.gen(function*() {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
+    const exitCode = yield* spawner.exitCode(
+      ChildProcess.make(command, args, {
+        stdin: "ignore",
+        stdout: "ignore",
+        stderr: "ignore"
+      })
+    )
+    if (exitCode !== 0) {
+      return yield* new BrowserOpenError({ command, exitCode })
+    }
+  })
+
+/** Open `url` in the user's browser. */
+export const openBrowser = (
+  url: string
+): Effect.Effect<void, BrowserOpenError | PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner> =>
+  run("open", [url]).pipe(
+    Effect.catch(() => run("xdg-open", [url])),
+    Effect.catch(() => run("rundll32.exe", ["url.dll,FileProtocolHandler", url]))
+  )

package/test/ApiUpdateWorkflows.test.ts

@@ -107,6 +107,40 @@ const changesetPathDiagnostics = (source: string): ReadonlyArray<string> =>
       : [`Generated changeset ${changesetPath ?? ""} must be unique per workflow run`]
   )
 
+// A regenerated-client-only diff is generator churn, not an upstream change: the
+// detection step must compare only the workflow's own client `specsDir`, and the
+// pull request must be gated on it.
+const specOnlyGuardDiagnostics = (source: string, specsDir: string): ReadonlyArray<string> => {
+  const workflow: unknown = parse(source)
+  if (!isRecord(workflow) || !isRecord(workflow.jobs)) return ["API update workflow could not be inspected"]
+
+  return Object.values(workflow.jobs).flatMap((job) => {
+    if (!isRecord(job) || !Array.isArray(job.steps)) return []
+    const steps = job.steps.filter(isRecord)
+    const detection = steps.find((step) => Predicate.isString(step.run) && step.run.includes("updated=true"))
+    if (detection === undefined || !Predicate.isString(detection.id) || !Predicate.isString(detection.run)) {
+      return ["API update workflow must detect upstream spec changes"]
+    }
+    const pathspecs = detection.run.replace(/\\\n\s*/gu, " ").match(/git diff --quiet -- ([^;\n]+)/u)?.[1]
+      ?.trim().split(/\s+/u) ?? []
+    const pathspecDiagnostics = pathspecs.length === 0
+      ? ["API update workflow must compare spec paths with git diff --quiet"]
+      : pathspecs.flatMap((pathspec) =>
+        pathspec === specsDir || pathspec.startsWith(`${specsDir}/`)
+          ? []
+          : [`API update workflow must open a pull request only for spec changes, not ${pathspec}`]
+      )
+    const gate = `steps.${detection.id}.outputs.updated == 'true'`
+    const pullRequestDiagnostics = steps.flatMap((step) =>
+      Predicate.isString(step.uses) && step.uses.startsWith("peter-evans/create-pull-request@")
+        && !(Predicate.isString(step.if) && step.if.includes(gate))
+        ? ["API update pull request must be gated on the spec-change detection step"]
+        : []
+    )
+    return [...pathspecDiagnostics, ...pullRequestDiagnostics]
+  })
+}
+
 const releaseWorkflow = (name: string, release: string, guidance = "Review the generated API.") => `
 jobs:
   update:
@@ -321,6 +355,50 @@ jobs:
       }
     }))
 
+  it("rejects generated-code detection and accepts a spec-only gate", () => {
+    const workflow = (pathspecs: string, gate: string) => `
+jobs:
+  update:
+    steps:
+      - name: Detect spec changes
+        id: check
+        run: |
+          if git diff --quiet -- \\
+            ${pathspecs}; then
+            echo "updated=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "updated=true" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Create pull request
+        if: ${gate}
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1
+`
+    const gate = "steps.check.outputs.updated == 'true'"
+    const specs = "packages/x/.specs"
+    expect(specOnlyGuardDiagnostics(workflow("packages/x/.specs packages/x/src/generated", gate), specs)).toEqual([
+      "API update workflow must open a pull request only for spec changes, not packages/x/src/generated"
+    ])
+    expect(specOnlyGuardDiagnostics(workflow("packages/y/.specs", gate), specs)).toEqual([
+      "API update workflow must open a pull request only for spec changes, not packages/y/.specs"
+    ])
+    expect(specOnlyGuardDiagnostics(workflow("packages/x/.specs-old", gate), specs)).toEqual([
+      "API update workflow must open a pull request only for spec changes, not packages/x/.specs-old"
+    ])
+    expect(specOnlyGuardDiagnostics(workflow("packages/x/.specs", "always()"), specs)).toEqual([
+      "API update pull request must be gated on the spec-change detection step"
+    ])
+    expect(specOnlyGuardDiagnostics(workflow("packages/x/.specs/x-v1.json", gate), specs)).toEqual([])
+    expect(specOnlyGuardDiagnostics(workflow("packages/x/.specs", gate), specs)).toEqual([])
+  })
+
+  it.effect("opens API update pull requests only for spec changes", () =>
+    Effect.gen(function*() {
+      for (const client of ["clockify", "jira", "confluence"]) {
+        const source = yield* loadWorkflow(`${client}-api-update.yml`)
+        expect(specOnlyGuardDiagnostics(source, `packages/${client}-api-client/.specs`)).toEqual([])
+      }
+    }))
+
   it("rejects a bare consumer build and accepts a dependency-closed build", () => {
     const invalid = `
 jobs: