@knpkv/atlassian-common 1.3.0 → 1.5.0

package/src/auth/OAuthOperations.ts

@@ -20,8 +20,8 @@
  */
 import * as Clock from "effect/Clock"
 import * as Effect from "effect/Effect"
+import { HttpClient, HttpClientRequest } from "effect/http"
 import * as Schema from "effect/Schema"
-import { HttpClient, HttpClientRequest } from "effect/unstable/http"
 import { type OAuthConfig, type OAuthToken } from "../config/OAuthSchemas.js"
 import { unsafeCurrentTimeMillis } from "../internal/legacyWallClock.js"
 import { ME_URL, RESOURCES_URL, REVOKE_URL, TOKEN_URL } from "./OAuthEndpoints.js"
@@ -29,6 +29,7 @@ import { OAuthError } from "./OAuthErrors.js"
 import {
   type AccessibleResource,
   AccessibleResourceSchema,
+  TokenErrorSchema,
   type TokenResponse,
   TokenResponseSchema,
   type UserInfo,
@@ -49,6 +50,15 @@ export interface ExchangeCodeOptions {
   readonly codeVerifier?: string | undefined
 }
 
+interface AuthorizationCodeTokenBody {
+  readonly grant_type: string
+  readonly client_id: string
+  readonly client_secret: string
+  readonly code: string
+  readonly redirect_uri: string
+  code_verifier?: string
+}
+
 /**
  * Exchange authorization code for tokens.
  *
@@ -58,10 +68,10 @@ export const exchangeCodeForTokens = (
   code: string,
   config: OAuthConfig,
   options: ExchangeCodeOptions
-): Effect.Effect<TokenResponse, OAuthError, HttpClient.HttpClient> =>
+) =>
   Effect.gen(function*() {
     const httpClient = yield* HttpClient.HttpClient
-    const tokenBody: Record<string, string> = {
+    const tokenBody: AuthorizationCodeTokenBody = {
       grant_type: "authorization_code",
       client_id: config.clientId,
       client_secret: config.clientSecret,
@@ -79,9 +89,7 @@ export const exchangeCodeForTokens = (
     if (response.status >= 400) {
       const text = yield* response.text
       yield* Effect.logDebug(`Token exchange failed (${response.status}): ${text}`)
-      return yield* Effect.fail(
-        new OAuthError({ step: "token", cause: `HTTP ${response.status}` })
-      )
+      return yield* new OAuthError({ step: "token", cause: `HTTP ${response.status}` })
     }
 
     const body = yield* response.json
@@ -113,9 +121,7 @@ export const getAccessibleResources = (
     if (response.status >= 400) {
       const text = yield* response.text
       yield* Effect.logDebug(`Accessible resources failed (${response.status}): ${text}`)
-      return yield* Effect.fail(
-        new OAuthError({ step: "resources", cause: `HTTP ${response.status}` })
-      )
+      return yield* new OAuthError({ step: "resources", cause: `HTTP ${response.status}` })
     }
 
     const body = yield* response.json
@@ -147,9 +153,7 @@ export const getUserInfo = (
     if (response.status >= 400) {
       const text = yield* response.text
       yield* Effect.logDebug(`User info failed (${response.status}): ${text}`)
-      return yield* Effect.fail(
-        new OAuthError({ step: "user-info", cause: `HTTP ${response.status}` })
-      )
+      return yield* new OAuthError({ step: "user-info", cause: `HTTP ${response.status}` })
     }
 
     const body = yield* response.json
@@ -192,9 +196,20 @@ export const refreshToken = (
       const text = yield* response.text.pipe(
         Effect.mapError((cause) => new OAuthError({ step: "refresh", cause }))
       )
-      return yield* Effect.fail(
-        new OAuthError({ step: "refresh", cause: `HTTP ${response.status}: ${text}` })
+      // The OAuth `error` code is what distinguishes "this grant is spent" from
+      // "your request was malformed", and callers key credential deletion off
+      // it. A body that is not JSON, or not shaped like an OAuth error, simply
+      // leaves it absent — which callers read as "no verdict", not "rejected".
+      const errorCode = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(TokenErrorSchema))(text).pipe(
+        Effect.map((decoded) => decoded.error),
+        Effect.catch(() => Effect.succeed(undefined))
       )
+      return yield* new OAuthError({
+        step: "refresh",
+        cause: `HTTP ${response.status}: ${text}`,
+        status: response.status,
+        ...(!(errorCode === undefined) && { errorCode })
+      })
     }
 
     const body = yield* response.json.pipe(
@@ -243,12 +258,10 @@ export const revokeToken = (
     )
 
     if (response.status >= 400) {
-      return yield* Effect.fail(
-        new OAuthError({
-          step: "revoke",
-          cause: `Token revocation failed with status ${response.status}`
-        })
-      )
+      return yield* new OAuthError({
+        step: "revoke",
+        cause: `Token revocation failed with status ${response.status}`
+      })
     }
   })
 

package/src/auth/OAuthResponseSchemas.ts

@@ -11,6 +11,18 @@
  */
 import * as Schema from "effect/Schema"
 
+/**
+ * OAuth 2.0 error response body (RFC 6749 §5.2).
+ *
+ * Only `error` is required; providers vary on the rest, so nothing else is
+ * modelled — the code is the part callers act on.
+ *
+ * @category Schema
+ */
+export const TokenErrorSchema = Schema.Struct({
+  error: Schema.String
+})
+
 /**
  * Schema for OAuth2 token response from Atlassian.
  *

package/src/auth/index.ts

@@ -12,6 +12,7 @@ export {
   buildAuthUrl,
   type BuildAuthUrlOptions,
   computeCodeChallenge,
+  CONFLUENCE_FOLDER_SCOPES,
   CONFLUENCE_SCOPES,
   generateCodeVerifier,
   JIRA_PROPOSAL_SCOPES,

package/src/bin.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { NodeHttpClient, NodeRuntime, NodeServices } from "@effect/platform-node"
+import { Argument as Args, Command } from "effect/cli"
 import * as Console from "effect/Console"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
 import * as Stdio from "effect/Stdio"
-import { Argument as Args, Command } from "effect/unstable/cli"
 import pkg from "../package.json" with { type: "json" }
 import {
   HomeDirectoryLive,
@@ -15,7 +15,7 @@ import {
   useProfileForAllTools
 } from "./config/index.js"
 
-const profileArg = Args.string("profile").pipe(
+const profileArg = Args.String("profile").pipe(
   Args.withDescription("Profile ID, name, site URL, cloud ID, or account ID")
 )
 
@@ -106,7 +106,9 @@ const program = Effect.gen(function*() {
       HomeDirectoryLive
     )
   ),
-  Effect.catch((error: unknown) => Console.error(String(error)).pipe(Effect.andThen(Effect.fail(error))))
+  Effect.catch(<UnparsedInput>(error: UnparsedInput) =>
+    Console.error(String(error)).pipe(Effect.andThen(Effect.fail(error)))
+  )
 )
 
 NodeRuntime.runMain(program, { disableErrorReporting: true })

package/src/config/AuthProfiles.ts

@@ -71,9 +71,11 @@ export type AuthProfilesFile = Schema.Schema.Type<typeof AuthProfilesFileSchema>
 
 const emptyProfiles = (): AuthProfilesFile => ({ profiles: [] })
 
-const parseJsonOrNull = (content: string): unknown | null => {
+const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Json))
+
+const parseJsonOrNull = (content: string): Schema.Json | null => {
   try {
-    return JSON.parse(content)
+    return decodeJson(content)
   } catch {
     return null
   }

package/src/config/ConfigPaths.ts

@@ -61,8 +61,8 @@ export class HomeDirectoryTag extends Context.Service<
   HomeDirectory
 >()("@knpkv/atlassian-common/HomeDirectory") {}
 
-const HomeConfig = Config.option(Config.string("HOME")).pipe(
-  Config.orElse(() => Config.option(Config.string("USERPROFILE")))
+const HomeConfig = Config.option(Config.String("HOME")).pipe(
+  Config.orElse(() => Config.option(Config.String("USERPROFILE")))
 )
 
 /**
@@ -84,7 +84,7 @@ export const HomeDirectoryLive: Layer.Layer<HomeDirectoryTag> = Layer.succeed(
   }
 )
 
-const XdgConfigHome = Config.option(Config.string("XDG_CONFIG_HOME"))
+const XdgConfigHome = Config.option(Config.String("XDG_CONFIG_HOME"))
 
 /**
  * XDG config directory for Atlassian tools.

package/src/config/ProfileManager.ts

@@ -7,11 +7,11 @@ import * as Clock from "effect/Clock"
 import * as Data from "effect/Data"
 import * as Effect from "effect/Effect"
 import * as FileSystem from "effect/FileSystem"
+import type { HttpClient } from "effect/http"
 import * as Path from "effect/Path"
 import type * as PlatformError from "effect/PlatformError"
 import * as Schema from "effect/Schema"
-import type { HttpClient } from "effect/unstable/http"
-import type { OAuthError } from "../auth/OAuthErrors.js"
+import { OAuthError } from "../auth/OAuthErrors.js"
 import { refreshToken } from "../auth/OAuthOperations.js"
 import {
   type AuthProfile,
@@ -51,6 +51,17 @@ export const JIRA_PROPOSAL_REQUIRED_SCOPES: ReadonlyArray<string> = [
   "offline_access"
 ]
 
+/**
+ * Scopes a Confluence profile must hold to be considered valid.
+ *
+ * Deliberately page-only. The CLI also requests the folder and CQL-search scopes
+ * (`CONFLUENCE_FOLDER_SCOPES`), but they are not listed here: this constant also
+ * gates control-center's per-site scope check, and a profile that can read and
+ * write pages is legitimately valid for everything except `folder`/`search`.
+ * The cost is that `atlassian profiles doctor` reports a pre-folder profile as
+ * valid and those two commands then fail with 401/403 until the OAuth app is
+ * updated and the user logs in again — see the confluence-to-markdown README.
+ */
 export const CONFLUENCE_REQUIRED_SCOPES: ReadonlyArray<string> = [
   "read:page:confluence",
   "write:page:confluence",
@@ -216,7 +227,7 @@ export const useProfileForAllTools = (
     ).find((profile): profile is AuthProfile =>
       profile !== null
     )
-    if (!selected) return yield* Effect.fail(new ProfileNotFoundError({ selector }))
+    if (selected === undefined) return yield* new ProfileNotFoundError({ selector })
 
     yield* Effect.forEach(stores, ([tool, store]) => {
       const matching = findProfile(store.profiles, selector) ?? findProfile(store.profiles, selected.id)
@@ -260,6 +271,9 @@ export const migrateLegacyProfiles = (
     return yield* inspectAllToolProfiles(tools)
   })
 
+/** Matches `JiraAuth`'s refresh deadline; see the rotation comment below. */
+const REFRESH_TIMEOUT = "30 seconds"
+
 /**
  * Refresh expired active profiles.
  *
@@ -284,10 +298,32 @@ export const refreshActiveProfiles = (
         if (!active || !isTokenExpiredAt(active.token, nowMs, 0)) return
         const config = yield* loadOAuthConfig(storeName)
         if (!config) {
-          return yield* Effect.fail(new MissingOAuthConfigError({ authStoreName: storeName, profileId: active.id }))
+          return yield* new MissingOAuthConfigError({ authStoreName: storeName, profileId: active.id })
         }
-        const refreshed = yield* refreshToken(active.token, config)
-        yield* saveProfileToken(storeName, refreshed)
+        // Rotating refresh tokens: the grant consumes the stored token
+        // server-side and the response carries its replacement, so an interrupt
+        // between the two spends the credential without persisting what
+        // replaced it — the next refresh 4xxs and the user is silently logged
+        // out. Keep the grant and the persist atomic, as `JiraAuth` does.
+        // The deadline is inside the region on purpose: an uninterruptible
+        // region with no bound of its own absorbs SIGINT/SIGTERM entirely
+        // (`runMain`'s handlers only interrupt the main fiber), so `atlassian
+        // auth refresh` would stop answering Ctrl-C against a stalled token
+        // endpoint. A deadline forked inside the region is still interruptible,
+        // so it does bound this. Failing here leaves the stored token in place
+        // — a refresh that never answered says nothing about its validity.
+        yield* Effect.uninterruptible(
+          Effect.gen(function*() {
+            const refreshed = yield* refreshToken(active.token, config).pipe(
+              Effect.timeout(REFRESH_TIMEOUT),
+              Effect.catchTag(
+                "TimeoutError",
+                () => Effect.fail(new OAuthError({ step: "refresh", cause: `no response within ${REFRESH_TIMEOUT}` }))
+              )
+            )
+            yield* saveProfileToken(storeName, refreshed)
+          })
+        )
       }))
     return yield* inspectAllToolProfiles(tools)
   })

package/src/config/TokenStorage.ts

@@ -28,9 +28,11 @@ import { type HomeDirectoryError, type HomeDirectoryTag } from "./ConfigPaths.js
 import { ensureConfigDir, getAuthPath, getOAuthConfigPath, writeSecureFile } from "./ConfigPaths.js"
 import { type OAuthConfig, OAuthConfigSchema, type OAuthToken, OAuthTokenSchema } from "./OAuthSchemas.js"
 
-const parseJsonOrNull = (content: string): unknown | null => {
+const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Json))
+
+const parseJsonOrNull = (content: string): Schema.Json | null => {
   try {
-    return JSON.parse(content)
+    return decodeJson(content)
   } catch {
     return null
   }

package/test/ApiUpdateWorkflows.test.ts

@@ -0,0 +1,356 @@
+import * as NodeServices from "@effect/platform-node/NodeServices"
+import { expect, layer } from "@effect/vitest"
+import * as Array from "effect/Array"
+import * as Effect from "effect/Effect"
+import * as FileSystem from "effect/FileSystem"
+import * as Path from "effect/Path"
+import * as Predicate from "effect/Predicate"
+import * as Schema from "effect/Schema"
+import { parse } from "yaml"
+
+const isRecord = <UnparsedInput>(value: UnparsedInput): value is UnparsedInput & Record<string, Schema.Json> =>
+  Predicate.isObjectOrArray(value) && value !== null && !Array.isArray(value)
+
+const buildCommands = (source: string): ReadonlyArray<string> => {
+  const workflow: unknown = parse(source)
+  if (!isRecord(workflow) || !isRecord(workflow.jobs)) return []
+
+  return Object.values(workflow.jobs).flatMap((job) => {
+    if (!isRecord(job) || !Array.isArray(job.steps)) return []
+    return job.steps.flatMap((step) => {
+      if (!isRecord(step) || !Predicate.isString(step.name) || !step.name.startsWith("Build ")) return []
+      return Predicate.isString(step.run) ? [step.run] : []
+    })
+  })
+}
+
+const dependencyClosureDiagnostics = (
+  source: string,
+  expectedConsumers: ReadonlyArray<string>
+): ReadonlyArray<string> => {
+  const commands = buildCommands(source)
+  return expectedConsumers.flatMap((consumer) => {
+    const dependencyClosedFilter = `--filter ${consumer}...`
+    return commands.some((command) => command.includes(dependencyClosedFilter) && /\bbuild\b/u.test(command))
+      ? []
+      : [`API update workflow must build ${consumer} with its workspace dependency closure`]
+  })
+}
+
+const PackageManifest = Schema.Struct({
+  name: Schema.String,
+  private: Schema.optional(Schema.Boolean),
+  exports: Schema.optional(Schema.Json)
+})
+
+// Public generated subpaths or generated export targets declare the contract;
+// package names and consumer dependencies do not.
+const exposesGeneratedContract = (exports: Schema.Json): boolean => {
+  if (Predicate.isString(exports)) return /(?:^|\/)generated(?:\/|$)/u.test(exports)
+  if (Array.isArray(exports)) return exports.some(exposesGeneratedContract)
+  if (!isRecord(exports)) return false
+  return Object.entries(exports).some(([name, target]) =>
+    /^\.\/generated(?:\/|$)/u.test(name) || exposesGeneratedContract(target)
+  )
+}
+
+const patchGuidanceDiagnostics = (
+  source: string,
+  generatedClientNames: ReadonlySet<string>
+): ReadonlyArray<string> => {
+  const workflow: unknown = parse(source)
+  if (!isRecord(workflow) || !isRecord(workflow.jobs)) return []
+
+  return Object.values(workflow.jobs).flatMap((job) => {
+    if (!isRecord(job) || !Array.isArray(job.steps)) return []
+    const steps = job.steps.filter(isRecord)
+    const bodies = steps.flatMap((step) =>
+      isRecord(step.with) && Predicate.isString(step.with.body) ? [step.with.body.replace(/\s+/gu, " ")] : []
+    )
+    const hasUnchangedContractGuidance = bodies.some((body) => /\bpublic contract is unchanged\b/iu.test(body))
+    const guidanceDiagnostics = bodies.flatMap((body) =>
+      body.split(/[.!?]/u).flatMap((sentence) =>
+        /\bpatch (?:is appropriate|(?:only )?when)\b/iu.test(sentence)
+          && !/\bpublic contract is unchanged\b/iu.test(sentence)
+          ? ["Patch release guidance must require an unchanged public contract"]
+          : []
+      )
+    )
+    const defaultDiagnostics = steps.flatMap((step) => {
+      if (!Predicate.isString(step.run) || !/cat\s+>\s+\.changeset\//u.test(step.run)) return []
+      const heredocs = [...step.run.matchAll(
+        /cat\s+>\s+\.changeset\/[^\s]+\.md\s+<<['"]?(\w+)['"]?\s*\n([\s\S]*?)\n\1(?:\n|$)/gu
+      )]
+      if (heredocs.length === 0) return ["Generated changeset heredoc could not be inspected"]
+      return heredocs.flatMap((heredoc) => {
+        const frontmatter = heredoc[2]?.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u)?.[1]
+        if (frontmatter === undefined) return ["Generated changeset must contain release frontmatter"]
+        const releases: unknown = parse(frontmatter)
+        if (!isRecord(releases)) return ["Generated changeset must contain release frontmatter"]
+        return Object.entries(releases).flatMap(([name, release]) =>
+          generatedClientNames.has(name) && release === "patch" && !hasUnchangedContractGuidance
+            ? [`Generated client ${name} defaults to patch without unchanged-contract guidance`]
+            : []
+        )
+      })
+    })
+    return [...guidanceDiagnostics, ...defaultDiagnostics]
+  })
+}
+
+// Generated changesets must not reuse a fixed path: the workflow regenerates the PR branch
+// from the base, so a fixed name overwrites a still-pending changeset from an earlier update.
+const changesetPathDiagnostics = (source: string): ReadonlyArray<string> =>
+  [...source.matchAll(/cat\s+>\s+(\.changeset\/[^\s]+\.md)/gu)].flatMap(([, changesetPath]) =>
+    changesetPath !== undefined && changesetPath.includes("${GITHUB_RUN_ID}")
+      ? []
+      : [`Generated changeset ${changesetPath ?? ""} must be unique per workflow run`]
+  )
+
+const releaseWorkflow = (name: string, release: string, guidance = "Review the generated API.") => `
+jobs:
+  update:
+    steps:
+      - name: Create changeset
+        run: |
+          cat > .changeset/api-update.md <<'CHANGESET'
+          ---
+          "${name}": ${release}
+          ---
+          Update generated API schemas.
+          CHANGESET
+      - name: Create pull request
+        with:
+          body: ${guidance}
+`
+
+const inspectApiUpdateWorkflows = Effect.fn("ApiUpdateWorkflows.inspectApiUpdateWorkflows")(function*(root: string) {
+  const fileSystem = yield* FileSystem.FileSystem
+  const path = yield* Path.Path
+  const packagesRoot = path.join(root, "packages")
+  const generatedClientNames = new Set<string>()
+  for (const directory of yield* fileSystem.readDirectory(packagesRoot)) {
+    if (["vendor", "generated", "node_modules"].includes(directory)) continue
+    const packageRoot = path.join(packagesRoot, directory)
+    if ((yield* fileSystem.stat(packageRoot)).type !== "Directory") continue
+    const manifestPath = path.join(packageRoot, "package.json")
+    if (!(yield* fileSystem.exists(manifestPath))) continue
+    const manifest = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(PackageManifest))(
+      yield* fileSystem.readFileString(manifestPath)
+    )
+    if (manifest.private !== true && manifest.exports !== undefined && exposesGeneratedContract(manifest.exports)) {
+      generatedClientNames.add(manifest.name)
+    }
+  }
+  const workflowRoot = path.join(root, ".github/workflows")
+  const diagnostics: Array<string> = []
+  for (const name of (yield* fileSystem.readDirectory(workflowRoot)).toSorted()) {
+    if (!/-api-update\.ya?ml$/u.test(name)) continue
+    const source = yield* fileSystem.readFileString(path.join(workflowRoot, name))
+    for (const diagnostic of patchGuidanceDiagnostics(source, generatedClientNames)) {
+      diagnostics.push(`${name}: ${diagnostic}`)
+    }
+  }
+  return diagnostics
+})
+
+const loadWorkflow = Effect.fn("ApiUpdateWorkflows.loadWorkflow")(function*(name: string) {
+  const fileSystem = yield* FileSystem.FileSystem
+  const path = yield* Path.Path
+  const workflowPath = yield* path.fromFileUrl(new URL(`../../../.github/workflows/${name}`, import.meta.url))
+  return yield* fileSystem.readFileString(workflowPath)
+})
+
+layer(NodeServices.layer)("API update workflow build closure", (it) => {
+  const fixtureClients = new Set(["@knpkv/jira-api-client"])
+
+  it.effect("discovers a fourth API workflow and its exported generated contract", () =>
+    Effect.gen(function*() {
+      const fileSystem = yield* FileSystem.FileSystem
+      const path = yield* Path.Path
+      const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "api-update-discovery-" })
+      const workflowRoot = path.join(root, ".github/workflows")
+      yield* fileSystem.makeDirectory(workflowRoot, { recursive: true })
+      for (const name of ["clockify", "jira", "confluence", "tempo"]) {
+        const packageRoot = path.join(root, "packages", name)
+        yield* fileSystem.makeDirectory(packageRoot, { recursive: true })
+        yield* fileSystem.writeFileString(
+          path.join(packageRoot, "package.json"),
+          JSON.stringify({
+            name: `@fixture/${name}`,
+            exports: { "./api": { types: "./dist/generated/Api.d.ts", import: "./dist/generated/Api.js" } }
+          })
+        )
+        yield* fileSystem.writeFileString(
+          path.join(workflowRoot, `${name}-api-update.yml`),
+          releaseWorkflow(`@fixture/${name}`, name === "tempo" ? "patch" : "minor")
+        )
+      }
+      for (
+        const [directory, manifest] of [
+          ["private-client", {
+            name: "@fixture/private-client",
+            private: true,
+            exports: { "./generated": "./dist/Api.js" }
+          }],
+          ["vendor", { name: "@fixture/vendor-client", exports: { "./generated": "./dist/Api.js" } }],
+          ["generated", { name: "@fixture/generated-package", exports: { "./generated": "./dist/Api.js" } }],
+          ["consumer", {
+            name: "@fixture/consumer",
+            exports: { ".": "./dist/index.js" },
+            dependencies: { "@fixture/tempo": "workspace:*" }
+          }]
+        ] satisfies ReadonlyArray<readonly [string, Schema.Json]>
+      ) {
+        const packageRoot = path.join(root, "packages", directory)
+        yield* fileSystem.makeDirectory(packageRoot, { recursive: true })
+        yield* fileSystem.writeFileString(path.join(packageRoot, "package.json"), JSON.stringify(manifest))
+        const decoded = yield* Schema.decodeUnknownEffect(PackageManifest)(manifest)
+        yield* fileSystem.writeFileString(
+          path.join(workflowRoot, `${directory}-api-update.yml`),
+          releaseWorkflow(decoded.name, "patch")
+        )
+      }
+      expect(yield* inspectApiUpdateWorkflows(root)).toEqual([
+        "tempo-api-update.yml: Generated client @fixture/tempo defaults to patch without unchanged-contract guidance"
+      ])
+      yield* fileSystem.writeFileString(
+        path.join(workflowRoot, "tempo-api-update.yml"),
+        releaseWorkflow("@fixture/tempo", "minor")
+      )
+      expect(yield* inspectApiUpdateWorkflows(root)).toEqual([])
+    }))
+
+  it("recognizes generated export subpaths and conditional targets without guessing package names", () => {
+    expect(exposesGeneratedContract({ "./generated/v1": "./dist/Api.js" })).toBe(true)
+    expect(exposesGeneratedContract({ ".": { import: [null, "./dist/generated/Api.js"] } })).toBe(true)
+    expect(exposesGeneratedContract({ ".": "./dist/generated-client.js" })).toBe(false)
+    expect(exposesGeneratedContract({ ".": "./dist/index.js" })).toBe(false)
+  })
+
+  it("rejects compatible-only patch guidance and accepts unchanged-contract guidance", () => {
+    const workflow = (guidance: string) => `
+jobs:
+  update:
+    steps:
+      - name: Create pull request
+        with:
+          body: ${guidance}
+`
+    expect(patchGuidanceDiagnostics(
+      workflow(
+        "Patch is appropriate only after confirming every public contract remains compatible."
+      ),
+      fixtureClients
+    )).toEqual(["Patch release guidance must require an unchanged public contract"])
+    expect(patchGuidanceDiagnostics(
+      workflow(
+        "Patch is appropriate only when the generated public contract is unchanged."
+      ),
+      fixtureClients
+    )).toEqual([])
+  })
+
+  it("rejects an unqualified generated-client patch default", () => {
+    expect(
+      patchGuidanceDiagnostics(
+        releaseWorkflow("@knpkv/jira-api-client", "patch", "Review the generated API."),
+        fixtureClients
+      )
+    )
+      .toEqual(["Generated client @knpkv/jira-api-client defaults to patch without unchanged-contract guidance"])
+    expect(
+      patchGuidanceDiagnostics(
+        releaseWorkflow("@knpkv/jira-api-client", "minor", "Review the generated API."),
+        fixtureClients
+      )
+    )
+      .toEqual([])
+    expect(patchGuidanceDiagnostics(
+      releaseWorkflow(
+        "@knpkv/jira-api-client",
+        "patch",
+        "Patch is appropriate only when the generated public contract is unchanged."
+      ),
+      fixtureClients
+    )).toEqual([])
+    expect(
+      patchGuidanceDiagnostics(
+        releaseWorkflow("@fixture/private-client", "patch", "Apply the JSON patch."),
+        fixtureClients
+      )
+    )
+      .toEqual([])
+    expect(
+      patchGuidanceDiagnostics(
+        releaseWorkflow("@knpkv/jira-clockify", "patch", "Consumer dependency update."),
+        fixtureClients
+      )
+    )
+      .toEqual([])
+  })
+
+  it.effect("checks every discovered API-update workflow in the repository", () =>
+    Effect.gen(function*() {
+      const fileSystem = yield* FileSystem.FileSystem
+      const path = yield* Path.Path
+      const root = yield* path.fromFileUrl(new URL("../../../", import.meta.url))
+      expect(yield* fileSystem.readDirectory(path.join(root, ".github/workflows"))).toEqual(expect.arrayContaining([
+        "clockify-api-update.yml",
+        "jira-api-update.yml",
+        "confluence-api-update.yml"
+      ]))
+      expect(yield* inspectApiUpdateWorkflows(root)).toEqual([])
+    }))
+
+  it("rejects a fixed generated changeset path and accepts a per-run path", () => {
+    expect(changesetPathDiagnostics("run: cat > .changeset/clockify-api-spec-update.md <<'CHANGESET'")).toEqual([
+      "Generated changeset .changeset/clockify-api-spec-update.md must be unique per workflow run"
+    ])
+    expect(
+      changesetPathDiagnostics("run: cat > .changeset/clockify-api-spec-update-${GITHUB_RUN_ID}.md <<'CHANGESET'")
+    ).toEqual([])
+  })
+
+  it.effect("writes every generated changeset to a per-run path", () =>
+    Effect.gen(function*() {
+      for (const name of ["clockify-api-update.yml", "jira-api-update.yml", "confluence-api-update.yml"]) {
+        const source = yield* loadWorkflow(name)
+        expect(source).toMatch(/cat\s+>\s+\.changeset\//u)
+        expect(changesetPathDiagnostics(source)).toEqual([])
+      }
+    }))
+
+  it("rejects a bare consumer build and accepts a dependency-closed build", () => {
+    const invalid = `
+jobs:
+  update:
+    steps:
+      - name: Build generated client and consumer
+        run: pnpm --filter @knpkv/confluence-to-markdown build
+`
+    const valid = `
+jobs:
+  update:
+    steps:
+      - name: Build generated client and consumer
+        run: pnpm --filter @knpkv/confluence-to-markdown... build
+`
+
+    expect(dependencyClosureDiagnostics(invalid, ["@knpkv/confluence-to-markdown"])).toEqual([
+      "API update workflow must build @knpkv/confluence-to-markdown with its workspace dependency closure"
+    ])
+    expect(dependencyClosureDiagnostics(valid, ["@knpkv/confluence-to-markdown"])).toEqual([])
+  })
+
+  it.effect("builds every API consumer with its workspace dependencies", () =>
+    Effect.gen(function*() {
+      const confluence = yield* loadWorkflow("confluence-api-update.yml")
+      const jira = yield* loadWorkflow("jira-api-update.yml")
+      const clockify = yield* loadWorkflow("clockify-api-update.yml")
+
+      expect(dependencyClosureDiagnostics(confluence, ["@knpkv/confluence-to-markdown"])).toEqual([])
+      expect(dependencyClosureDiagnostics(jira, ["@knpkv/jira-cli", "@knpkv/jira-clockify"])).toEqual([])
+      expect(dependencyClosureDiagnostics(clockify, ["@knpkv/jira-clockify"])).toEqual([])
+    }))
+})