@knpkv/atlassian-common 1.4.1 → 1.6.0

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/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,10 +7,10 @@ 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 { OAuthError } from "../auth/OAuthErrors.js"
 import { refreshToken } from "../auth/OAuthOperations.js"
 import {
@@ -227,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)
@@ -298,7 +298,7 @@ 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 })
         }
         // Rotating refresh tokens: the grant consumes the stored token
         // server-side and the response carries its replacement, so an interrupt

package/test/ApiUpdateWorkflows.test.ts

@@ -1,10 +1,11 @@
 import * as NodeServices from "@effect/platform-node/NodeServices"
-import { describe, expect, it } from "@effect/vitest"
+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 type * as Schema from "effect/Schema"
+import * as Schema from "effect/Schema"
 import { parse } from "yaml"
 
 const isRecord = <UnparsedInput>(value: UnparsedInput): value is UnparsedInput & Record<string, Schema.Json> =>
@@ -36,15 +37,290 @@ const dependencyClosureDiagnostics = (
   })
 }
 
-const loadWorkflow = (name: string) =>
-  Effect.gen(function*() {
-    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)
-  }).pipe(Effect.provide(NodeServices.layer))
+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([])
+      }
+    }))
 
-describe("API update workflow build closure", () => {
   it("rejects a bare consumer build and accepts a dependency-closed build", () => {
     const invalid = `
 jobs:

package/test/OAuthOperations.test.ts

@@ -1,9 +1,9 @@
 import { describe, it } from "@effect/vitest"
 import * as Effect from "effect/Effect"
+import type { HttpClientRequest } from "effect/http"
+import { HttpClient, HttpClientResponse } from "effect/http"
 import * as Layer from "effect/Layer"
 import { TestClock } from "effect/testing"
-import type { HttpClientRequest } from "effect/unstable/http"
-import { HttpClient, HttpClientResponse } from "effect/unstable/http"
 import { expect } from "vitest"
 import { OAuthError } from "../src/auth/OAuthErrors.js"
 import {

package/test/ProfileManager.test.ts

@@ -4,9 +4,9 @@ import * as Clock from "effect/Clock"
 import * as Deferred from "effect/Deferred"
 import * as Fiber from "effect/Fiber"
 import * as FileSystem from "effect/FileSystem"
+import { HttpClient, HttpClientResponse } from "effect/http"
 import * as Path from "effect/Path"
 import { SystemError } from "effect/PlatformError"
-import { HttpClient, HttpClientResponse } from "effect/unstable/http"
 import {
   type AtlassianToolDefinition,
   HomeDirectoryLive,