@knpkv/jira-cli 1.2.3 → 1.3.1

package/test/oauthServer.test.ts

@@ -1,15 +1,25 @@
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient"
 import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer"
 import { describe, expect, it } from "@effect/vitest"
 import * as Effect from "effect/Effect"
+import * as Fiber from "effect/Fiber"
 import * as Layer from "effect/Layer"
 import * as Ref from "effect/Ref"
-import { HttpServer, HttpServerError } from "effect/unstable/http"
+import { HttpClient, HttpClientRequest, HttpServer, HttpServerError } from "effect/unstable/http"
 import { createServer } from "node:http"
-import { makeHttpServerFactory, startCallbackServer } from "../src/internal/oauthServer.js"
+import { HttpServerFactoryLive } from "../src/internal/NodeLayers.js"
+import {
+  callbackServerListenOptions,
+  callbackUrl,
+  HttpServerFactoryTag,
+  makeHttpServerFactory,
+  startCallbackServer
+} from "../src/internal/oauthServer.js"
 
 const EphemeralHttpServerFactoryLive = makeHttpServerFactory(
   () => NodeHttpServer.layerServer(createServer, { port: 0 })
 )
+const HttpClientLive = NodeHttpClient.layerUndici
 const fakeHttpServer = (port: number): HttpServer.HttpServer["Service"] =>
   HttpServer.make({
     address: { _tag: "TcpAddress", hostname: "127.0.0.1", port },
@@ -17,6 +27,23 @@ const fakeHttpServer = (port: number): HttpServer.HttpServer["Service"] =>
   })
 
 describe("oauth callback server lifecycle", () => {
+  it.effect("binds the same localhost name advertised by the callback URL", () =>
+    Effect.scoped(
+      Effect.gen(function*() {
+        const listenOptions = callbackServerListenOptions(0)
+        const factory = yield* HttpServerFactoryTag
+        const server = yield* HttpServer.HttpServer.pipe(
+          Effect.provide(factory.createServerLayer(listenOptions))
+        )
+        const advertisedUrl = new URL(callbackUrl(8585))
+        const ipv6OnlyLocalhost = (hostname: string) => (hostname === "localhost" ? "::1" : undefined)
+        expect(server.address._tag).toBe("TcpAddress")
+        expect(listenOptions.host).toBe(advertisedUrl.hostname)
+        expect(ipv6OnlyLocalhost(listenOptions.host)).toBe("::1")
+        expect(ipv6OnlyLocalhost(advertisedUrl.hostname)).toBe("::1")
+      }).pipe(Effect.provide(HttpServerFactoryLive))
+    ))
+
   it.effect("releases the port when authorization exits before receiving a code", () =>
     Effect.gen(function*() {
       yield* Effect.scoped(
@@ -51,7 +78,7 @@ describe("oauth callback server lifecycle", () => {
 
   it.effect("retries occupied fixed-range ports with the injected factory", () => {
     const attempts = Ref.makeUnsafe<ReadonlyArray<number>>([])
-    const occupiedFactory = makeHttpServerFactory((port) =>
+    const occupiedFactory = makeHttpServerFactory(({ port }) =>
       Layer.effect(
         HttpServer.HttpServer,
         Ref.update(attempts, (ports) => [...ports, port]).pipe(
@@ -96,4 +123,49 @@ describe("oauth callback server lifecycle", () => {
       )
     )
   })
+
+  it.effect("ignores a forged error callback before accepting the legitimate state", () =>
+    Effect.scoped(
+      Effect.gen(function*() {
+        const expectedState = "expected-state"
+        const { codePromise, port } = yield* startCallbackServer(expectedState)
+        const codeReceiver = yield* Effect.forkChild(codePromise)
+        const client = yield* HttpClient.HttpClient
+
+        const forgedResponse = yield* client.execute(
+          HttpClientRequest.get(`http://127.0.0.1:${port}/callback`).pipe(
+            HttpClientRequest.setUrlParam("error", "access_denied")
+          )
+        )
+        expect(forgedResponse.status).toBe(403)
+        yield* client.execute(
+          HttpClientRequest.get(`http://127.0.0.1:${port}/callback`).pipe(
+            HttpClientRequest.setUrlParam("code", "legitimate-code"),
+            HttpClientRequest.setUrlParam("state", expectedState)
+          )
+        )
+
+        expect(yield* Fiber.join(codeReceiver)).toBe("legitimate-code")
+      }).pipe(Effect.provide(Layer.mergeAll(EphemeralHttpServerFactoryLive, HttpClientLive)))
+    ))
+
+  it.effect("accepts a provider error only after validating state", () =>
+    Effect.scoped(
+      Effect.gen(function*() {
+        const expectedState = "expected-state"
+        const { codePromise, port } = yield* startCallbackServer(expectedState)
+        const codeReceiver = yield* Effect.forkChild(codePromise)
+        const client = yield* HttpClient.HttpClient
+
+        yield* client.execute(
+          HttpClientRequest.get(`http://127.0.0.1:${port}/callback`).pipe(
+            HttpClientRequest.setUrlParam("error", "access_denied"),
+            HttpClientRequest.setUrlParam("state", expectedState)
+          )
+        )
+
+        const error = yield* Fiber.join(codeReceiver).pipe(Effect.flip)
+        expect(String(error.cause)).toContain("access_denied")
+      }).pipe(Effect.provide(Layer.mergeAll(EphemeralHttpServerFactoryLive, HttpClientLive)))
+    ))
 })

package/test/publicApi.test.ts

@@ -0,0 +1,34 @@
+/**
+ * The root barrel is the published surface.
+ *
+ * The changeset advertises `planRelatedWorkSync` as the reusable planning step,
+ * but nothing re-exported it and `package.json` exposed no `VersionService`
+ * subpath, so both `import { planRelatedWorkSync } from "@knpkv/jira-cli"` and
+ * the natural subpath import would have failed after publication.
+ */
+import { describe, expect, it } from "@effect/vitest"
+import * as Predicate from "effect/Predicate"
+import { readFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import * as api from "../src/index.js"
+
+const manifestExports = (): ReadonlyArray<string> => {
+  const parsed: unknown = JSON.parse(
+    readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8")
+  )
+  if (!Predicate.isObject(parsed)) return []
+  const exports = parsed["exports"]
+  return Predicate.isObject(exports) ? Object.keys(exports) : []
+}
+
+describe("@knpkv/jira-cli public API", () => {
+  it("exports the related-work planner the changeset advertises", () => {
+    expect(Predicate.isFunction(api.planRelatedWorkSync)).toBe(true)
+    expect(api.VersionService).toBeDefined()
+    expect(api.VersionServiceLayer).toBeDefined()
+  })
+
+  it("declares a VersionService subpath alongside the other services", () => {
+    expect(manifestExports()).toContain("./VersionService")
+  })
+})

package/test/relatedWorkSync.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, it } from "@effect/vitest"
+import type { RelatedWork } from "../src/VersionService.js"
+import { planRelatedWorkSync } from "../src/VersionService.js"
+
+const link = (
+  title: string,
+  url: string,
+  category = "Communication",
+  relatedWorkId: string | null = `id-${title}`
+): RelatedWork => ({ relatedWorkId, title, category, url })
+
+const notes = { title: "Release Notes - REL 96", url: "https://example.atlassian.net/wiki/pages/1" }
+const vra = { title: "Verbal Risk Assessment - REL 96", url: "https://example.atlassian.net/wiki/pages/2" }
+const report = { title: "Test Report - REL 96", url: "https://example.atlassian.net/wiki/pages/3" }
+
+const options = { category: "Communication", prune: false }
+
+describe("planRelatedWorkSync", () => {
+  it("adds every link when the version has none", () => {
+    const plan = planRelatedWorkSync([], [notes, vra, report], options)
+
+    expect(plan.toAdd).toEqual([notes, vra, report])
+    expect(plan.kept).toEqual([])
+    expect(plan.toRemove).toEqual([])
+  })
+
+  // The whole point: scaffolding a release twice must not double the links.
+  it("is a no-op on a second run", () => {
+    const desired = [notes, vra, report]
+    const existing = desired.map((d) => link(d.title, d.url))
+
+    const plan = planRelatedWorkSync(existing, desired, options)
+
+    expect(plan.toAdd).toEqual([])
+    expect(plan.kept).toEqual([notes.url, vra.url, report.url])
+    expect(plan.toRemove).toEqual([])
+  })
+
+  it("adds only what is missing", () => {
+    const plan = planRelatedWorkSync([link(notes.title, notes.url)], [notes, vra], options)
+
+    expect(plan.toAdd).toEqual([vra])
+    expect(plan.kept).toEqual([notes.url])
+  })
+
+  // A link retitled in the Jira UI is still the same link; matching on URL
+  // keeps the user's edit instead of adding a duplicate under our title.
+  it("matches on URL, not title", () => {
+    const existing = [link("Renamed by hand", notes.url)]
+
+    const plan = planRelatedWorkSync(existing, [notes], options)
+
+    expect(plan.toAdd).toEqual([])
+    expect(plan.kept).toEqual([notes.url])
+  })
+
+  it("ignores links in other categories", () => {
+    const existing = [link(notes.title, notes.url, "Testing")]
+
+    const plan = planRelatedWorkSync(existing, [notes], options)
+
+    expect(plan.toAdd).toEqual([notes])
+  })
+
+  it("leaves extras alone without --prune", () => {
+    const existing = [link(notes.title, notes.url), link("Stale", "https://example.atlassian.net/wiki/pages/99")]
+
+    const plan = planRelatedWorkSync(existing, [notes], options)
+
+    expect(plan.toRemove).toEqual([])
+  })
+
+  it("removes extras in the category with --prune", () => {
+    const existing = [link(notes.title, notes.url), link("Stale", "https://example.atlassian.net/wiki/pages/99")]
+
+    const plan = planRelatedWorkSync(existing, [notes], { category: "Communication", prune: true })
+
+    expect(plan.toRemove).toEqual([
+      { relatedWorkId: "id-Stale", url: "https://example.atlassian.net/wiki/pages/99" }
+    ])
+  })
+
+  it("never prunes across categories", () => {
+    const existing = [link("Other team's link", "https://example.atlassian.net/wiki/pages/99", "Testing")]
+
+    const plan = planRelatedWorkSync(existing, [notes], { category: "Communication", prune: true })
+
+    expect(plan.toRemove).toEqual([])
+    expect(plan.toAdd).toEqual([notes])
+  })
+
+  it("skips prune candidates Jira gave no id for", () => {
+    const existing = [link("No id", "https://example.atlassian.net/wiki/pages/99", "Communication", null)]
+
+    const plan = planRelatedWorkSync(existing, [notes], { category: "Communication", prune: true })
+
+    expect(plan.toRemove).toEqual([])
+  })
+
+  // The pile-up the reconcile exists to clean up: repeated `related-work add`
+  // leaves several links to the same page, all of them wanted URLs.
+  it("prunes surplus copies of a desired URL, keeping the first", () => {
+    const existing = [
+      link("Release Notes", notes.url, "Communication", "id-first"),
+      link("Release Notes", notes.url, "Communication", "id-second"),
+      link("Release Notes", notes.url, "Communication", "id-third")
+    ]
+
+    const plan = planRelatedWorkSync(existing, [notes], { category: "Communication", prune: true })
+
+    expect(plan.toAdd).toEqual([])
+    expect(plan.kept).toEqual([notes.url])
+    expect(plan.toRemove).toEqual([
+      { relatedWorkId: "id-second", url: notes.url },
+      { relatedWorkId: "id-third", url: notes.url }
+    ])
+  })
+
+  it("leaves duplicate copies alone without --prune", () => {
+    const existing = [
+      link("Release Notes", notes.url, "Communication", "id-first"),
+      link("Release Notes", notes.url, "Communication", "id-second")
+    ]
+
+    const plan = planRelatedWorkSync(existing, [notes], options)
+
+    expect(plan.toRemove).toEqual([])
+  })
+
+  // Two --link flags for one page are one link: URL is the identity on the
+  // desired side too, or the reconcile would itself create the duplicates.
+  it("collapses repeated desired entries to a single add", () => {
+    const plan = planRelatedWorkSync([], [notes, { title: "Same page, other title", url: notes.url }], options)
+
+    expect(plan.toAdd).toEqual([notes])
+  })
+
+  // Every desired link carries a URL, so a url-less entry can never be one of
+  // them. Skipping it left the category unreconciled while --prune reported
+  // success.
+  it("prunes a url-less entry that Jira gave an id", () => {
+    const existing = [
+      link("Release Notes", notes.url),
+      { relatedWorkId: "id-orphan", title: "Legacy attachment", category: "Communication", url: null }
+    ]
+
+    const plan = planRelatedWorkSync(existing, [notes], { category: "Communication", prune: true })
+
+    expect(plan.toRemove).toEqual([{ relatedWorkId: "id-orphan", url: null }])
+  })
+
+  // Jira can hand back a desired URL twice with only the second copy
+  // deletable. Skipping the undeletable one before designating a keeper let the
+  // deletable duplicate claim that role, so both survived a reconcile that
+  // reported success.
+  it("prunes the deletable duplicate when the keeper has no id", () => {
+    const existing = [
+      { relatedWorkId: null, title: "Release Notes", category: "Communication", url: notes.url },
+      link("Release Notes", notes.url, "Communication", "id-second")
+    ]
+
+    const plan = planRelatedWorkSync(existing, [notes], { category: "Communication", prune: true })
+
+    expect(plan.toRemove).toEqual([{ relatedWorkId: "id-second", url: notes.url }])
+  })
+
+  // The nearby valid fixture: with no id there is nothing to delete with, so
+  // it stays skipped however it is pruned.
+  it("leaves a url-less entry alone when Jira gave no id either", () => {
+    const existing = [
+      link("Release Notes", notes.url),
+      { relatedWorkId: null, title: "Legacy attachment", category: "Communication", url: null }
+    ]
+
+    const plan = planRelatedWorkSync(existing, [notes], { category: "Communication", prune: true })
+
+    expect(plan.toRemove).toEqual([])
+  })
+})

package/test/remoteWrites.test.ts

@@ -0,0 +1,220 @@
+import { describe, expect, it } from "@effect/vitest"
+import { JiraApiClient, make } from "@knpkv/jira-api-client"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Redacted from "effect/Redacted"
+import * as Schema from "effect/Schema"
+import * as HttpClient from "effect/unstable/http/HttpClient"
+import type * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse"
+import { IssueService, layer as IssueServiceLayer, SiteUrl } from "../src/IssueService.js"
+import { layer as VersionServiceLayer, VersionService } from "../src/VersionService.js"
+
+/** One recorded outbound call, so a test can assert what actually went to Jira. */
+interface RecordedRequest {
+  readonly method: string
+  readonly url: string
+  readonly body: Schema.Json | undefined
+}
+
+const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Json))
+
+const bodyJson = (request: HttpClientRequest.HttpClientRequest): Schema.Json | undefined => {
+  if (request.body._tag !== "Uint8Array") return undefined
+  return decodeJson(new TextDecoder().decode(request.body.body))
+}
+
+const issueFields = {
+  attachment: [],
+  components: [],
+  created: "2026-01-01T00:00:00.000Z",
+  description: "",
+  issuetype: { name: "Task" },
+  status: { name: "Done" },
+  summary: "Sample issue",
+  updated: "2026-01-01T00:00:00.000Z"
+}
+
+/**
+ * Route by method+path and record every call.
+ *
+ * `respond` returns the web `Response` for a request; anything it does not
+ * recognise 404s, so an unexpected extra call fails loudly rather than being
+ * absorbed by a permissive catch-all.
+ */
+const makeRecordingLayer = (respond: (request: HttpClientRequest.HttpClientRequest) => Response) => {
+  const calls: Array<RecordedRequest> = []
+  const httpClient = HttpClient.make((request) => {
+    calls.push({ method: request.method, url: request.url, body: bodyJson(request) })
+    return Effect.succeed(HttpClientResponse.fromWeb(request, respond(request)))
+  })
+  const api = make(httpClient, {
+    baseUrl: "https://jira.test",
+    auth: { type: "basic", email: "test@example.com", apiToken: Redacted.make("token") }
+  })
+  const layer = Layer.succeed(
+    JiraApiClient,
+    JiraApiClient.of({ ...api, uploadAttachment: () => Effect.die("unused Jira upload mock") })
+  )
+  return { calls, layer }
+}
+
+const json = <UnparsedInput>(body: UnparsedInput, status = 200) =>
+  new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } })
+
+describe("IssueService.edit", () => {
+  /**
+   * The payload builder is unit-tested separately; what this covers is that the
+   * body it builds actually reaches `PUT /issue/{key}` unaltered, rather than
+   * being reshaped or dropped on the way through the generated client.
+   */
+  it.effect("sends the built payload to PUT /issue/{key} and re-reads the issue", () => {
+    const { calls, layer } = makeRecordingLayer((request) =>
+      request.method === "PUT"
+        // Jira answers a default edit with 204 No Content.
+        ? new Response(null, { status: 204 })
+        : json({
+          id: "10000",
+          key: "PROJ-123",
+          fields: { ...issueFields, fixVersions: [{ name: "OOB 100" }], labels: ["domain:oob"] },
+          renderedFields: {}
+        })
+    )
+
+    return Effect.gen(function*() {
+      const service = yield* IssueService
+      const issue = yield* service.edit("PROJ-123", {
+        addFixVersions: ["OOB 100"],
+        addLabels: ["domain:oob"]
+      })
+
+      const put = calls.find((call) => call.method === "PUT")
+      expect(put?.url).toContain("/rest/api/3/issue/PROJ-123")
+      expect(put?.body).toEqual({
+        update: {
+          fixVersions: [{ add: { name: "OOB 100" } }],
+          labels: [{ add: "domain:oob" }]
+        }
+      })
+
+      // The 204 carries no body, so the reported state has to come from a re-read.
+      expect(calls.filter((call) => call.method === "GET")).toHaveLength(1)
+      expect(issue.fixVersions).toEqual(["OOB 100"])
+      expect(issue.labels).toEqual(["domain:oob"])
+    }).pipe(
+      Effect.provide(IssueServiceLayer),
+      Effect.provide(layer),
+      Effect.provide(Layer.succeed(SiteUrl, "https://example.atlassian.net"))
+    )
+  })
+
+  /**
+   * Once the PUT lands the edit is committed. Reporting the read-back failure as
+   * a failed edit invites the caller to repeat a change that already happened.
+   */
+  it.effect("reports a failed read-back as committed-but-unverified, not as a failed edit", () => {
+    const { calls, layer } = makeRecordingLayer((request) =>
+      request.method === "PUT"
+        ? new Response(null, { status: 204 })
+        : json({ errorMessages: ["Internal server error"] }, 500)
+    )
+
+    return Effect.gen(function*() {
+      const service = yield* IssueService
+      const error = yield* Effect.flip(service.edit("PROJ-123", { addFixVersions: ["OOB 100"] }))
+
+      expect(error.message).toContain("do not repeat it")
+      expect(error.message).not.toContain("Failed to edit")
+      // The write really did go out — that is why the wording matters.
+      expect(calls.filter((call) => call.method === "PUT")).toHaveLength(1)
+    }).pipe(
+      Effect.provide(IssueServiceLayer),
+      Effect.provide(layer),
+      Effect.provide(Layer.succeed(SiteUrl, "https://example.atlassian.net"))
+    )
+  })
+
+  /** A refused combination must never reach the network. */
+  it.effect("fails before calling Jira when the flags contradict each other", () => {
+    const { calls, layer } = makeRecordingLayer(() => new Response(null, { status: 204 }))
+
+    return Effect.gen(function*() {
+      const service = yield* IssueService
+      const result = yield* Effect.flip(
+        service.edit("PROJ-123", { setFixVersions: ["OOB 100"], addFixVersions: ["OOB 99"] })
+      )
+
+      expect(result.message).toContain("--fix-version cannot be combined")
+      expect(calls).toHaveLength(0)
+    }).pipe(
+      Effect.provide(IssueServiceLayer),
+      Effect.provide(layer),
+      Effect.provide(Layer.succeed(SiteUrl, "https://example.atlassian.net"))
+    )
+  })
+})
+
+describe("VersionService.createVersion", () => {
+  /**
+   * The create endpoint wants a numeric `projectId`, but `/project/{key}`
+   * serialises the id as a string — so the coercion is the whole reason the
+   * project lookup exists, and sending the string form is a 400 from Jira.
+   */
+  it.effect("resolves the project key to a numeric projectId", () => {
+    const { calls, layer } = makeRecordingLayer((request) =>
+      request.url.includes("/rest/api/3/project/")
+        ? json({ id: "10001", key: "PROJ" })
+        : json({ id: "10042", name: "OOB 100", released: false, archived: false }, 201)
+    )
+
+    return Effect.gen(function*() {
+      const service = yield* VersionService
+      const version = yield* service.createVersion({
+        projectKey: "PROJ",
+        name: "OOB 100",
+        description: "Q3 release"
+      })
+
+      const post = calls.find((call) => call.method === "POST")
+      expect(post?.url).toContain("/rest/api/3/version")
+      expect(post?.body).toEqual({ name: "OOB 100", projectId: 10001, description: "Q3 release" })
+      expect(version.id).toBe("10042")
+      expect(version.released).toBe(false)
+    }).pipe(Effect.provide(VersionServiceLayer), Effect.provide(layer))
+  })
+
+  /** Omitted optional fields must be absent, not sent as `undefined`/null. */
+  it.effect("omits the optional date and description fields when not given", () => {
+    const { calls, layer } = makeRecordingLayer((request) =>
+      request.url.includes("/rest/api/3/project/")
+        ? json({ id: "10001", key: "PROJ" })
+        : json({ id: "10042", name: "OOB 100", released: false, archived: false }, 201)
+    )
+
+    return Effect.gen(function*() {
+      const service = yield* VersionService
+      yield* service.createVersion({ projectKey: "PROJ", name: "OOB 100" })
+
+      expect(calls.find((call) => call.method === "POST")?.body).toEqual({
+        name: "OOB 100",
+        projectId: 10001
+      })
+    }).pipe(Effect.provide(VersionServiceLayer), Effect.provide(layer))
+  })
+
+  /**
+   * Without a usable id there is nothing to create the version against, and
+   * Jira's own error for a missing projectId does not say so.
+   */
+  it.effect("fails with a named error when the project returns no numeric id", () => {
+    const { calls, layer } = makeRecordingLayer(() => json({ key: "PROJ" }))
+
+    return Effect.gen(function*() {
+      const service = yield* VersionService
+      const error = yield* Effect.flip(service.createVersion({ projectKey: "PROJ", name: "OOB 100" }))
+
+      expect(error.message).toContain("no usable numeric id")
+      expect(calls.filter((call) => call.method === "POST")).toHaveLength(0)
+    }).pipe(Effect.provide(VersionServiceLayer), Effect.provide(layer))
+  })
+})

package/test/syncChanges.test.ts

@@ -10,7 +10,7 @@ const fields = (overrides: Partial<SyncBaselineFields> = {}): SyncBaselineFields
     Risk: {
       fieldId: "customfield_1",
       displayName: "Risk",
-      shape: "singleSelect",
+      form: "singleSelect",
       value: { id: "1", value: "Low" }
     }
   },
@@ -80,7 +80,7 @@ describe("compareIssueFields", () => {
           Risk: {
             fieldId: "customfield_1",
             displayName: "Risk",
-            shape: "singleSelect",
+            form: "singleSelect",
             value: { id: "2", value: "High" }
           }
         }

package/test/syncConfig.test.ts

@@ -29,7 +29,7 @@ customFields:
       expect(result.customFields[1]).toMatchObject({
         displayName: "Reviewer",
         fieldId: "customfield_12345",
-        shape: "user"
+        form: "user"
       })
     })
 
@@ -117,7 +117,7 @@ customFields: []
           "Security & Compliance Impact": {
             fieldId: "customfield_10001",
             displayName: "Security & Compliance Impact",
-            shape: "singleSelect",
+            form: "singleSelect",
             value: { id: "10423", value: "Low" }
           }
         }