@knpkv/jira-cli 1.1.2 → 1.2.1

package/src/commands/search.ts

@@ -38,7 +38,7 @@ const outputDirOption = Options.directory("output-dir").pipe(
 const formatOption = Options.choice("format", ["multi", "single"]).pipe(
   Options.withAlias("f"),
   Options.withDescription("Output format: multi (one file per issue) or single (combined file)"),
-  Options.withDefault("multi" as const)
+  Options.withDefault("multi")
 )
 
 const maxResultsOption = Options.integer("max-results").pipe(

package/src/index.ts

@@ -4,6 +4,12 @@
  * @module
  */
 
+export {
+  AttachmentService,
+  type AttachmentServiceShape,
+  layer as AttachmentServiceLayer,
+  type UploadAttachmentInput
+} from "./AttachmentService.js"
 export {
   type Attachment,
   type Comment,

package/src/internal/attachmentInsertion.ts

@@ -0,0 +1,44 @@
+/**
+ * Local Attachment Insertion helpers for Jira Markdown files.
+ *
+ * @internal
+ */
+import { renderAttachmentMarkdown, replaceAttachmentPlaceholder } from "@knpkv/atlassian-common/attachments"
+import type { Attachment } from "../IssueService.js"
+
+export interface InsertAttachmentResult {
+  readonly content: string
+  readonly replacements: number
+}
+
+export const renderJiraAttachmentReference = (
+  attachment: Attachment,
+  options?: { readonly label?: string | null | undefined }
+): string =>
+  renderAttachmentMarkdown({
+    id: attachment.id,
+    filename: attachment.filename,
+    url: attachment.url,
+    mediaType: attachment.mediaType,
+    size: attachment.size
+  }, {
+    label: options?.label,
+    metadata: `<!-- jiraAttachment: ${
+      JSON.stringify({
+        jiraAttachmentId: attachment.id,
+        mediaType: attachment.mediaType,
+        size: attachment.size
+      })
+    } -->`
+  })
+
+export const insertJiraAttachmentReference = (
+  content: string,
+  placeholderPath: string,
+  attachment: Attachment
+): InsertAttachmentResult =>
+  replaceAttachmentPlaceholder(
+    content,
+    placeholderPath,
+    ({ label }) => renderJiraAttachmentReference(attachment, { label })
+  )

package/src/internal/frontmatter.ts

@@ -8,6 +8,7 @@
  *
  * @internal
  */
+import { isPreviewableAttachment } from "@knpkv/atlassian-common/attachments"
 import matter from "gray-matter"
 import * as yaml from "js-yaml"
 import type { Issue } from "../IssueService.js"
@@ -21,7 +22,10 @@ import type { Issue } from "../IssueService.js"
  * @internal
  */
 const yamlEngine = {
-  parse: (str: string): object => (yaml.load(str) as object) ?? {},
+  parse: (str: string): object => {
+    const parsed = yaml.load(str)
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}
+  },
   stringify: (data: object): string => yaml.dump(data)
 }
 
@@ -114,9 +118,19 @@ export const buildMarkdownContent = (issue: Issue): string => {
     parts.push("## Attachments")
     parts.push("")
     for (const attachment of issue.attachments) {
-      parts.push(`- [${attachment.filename}](${attachment.url})`)
+      const reference = isPreviewableAttachment(attachment)
+        ? `![${attachment.filename}](${attachment.url})`
+        : `[${attachment.filename}](${attachment.url})`
+      parts.push(`<!-- jiraAttachment: ${
+        JSON.stringify({
+          jiraAttachmentId: attachment.id,
+          mediaType: attachment.mediaType,
+          size: attachment.size
+        })
+      } -->`)
+      parts.push(reference)
+      parts.push("")
     }
-    parts.push("")
   }
 
   // Comments

package/src/internal/sync/baseline.ts

@@ -15,13 +15,13 @@ export const parseSyncBaseline = (
 ): Effect.Effect<SyncBaseline, SyncWorkspaceError | SyncValidationError> =>
   Effect.gen(function*() {
     const raw = yield* Effect.try({
-      try: () => JSON.parse(content) as unknown,
+      try: (): unknown => JSON.parse(content),
       catch: (cause) => new SyncWorkspaceError({ message: "Failed to parse Sync Baseline JSON", path, cause })
     })
-    return yield* Schema.decodeUnknownEffect(SyncBaselineSchema)(raw).pipe(
-      Effect.map((baseline) => baseline as SyncBaseline),
+    const baseline: SyncBaseline = yield* Schema.decodeUnknownEffect(SyncBaselineSchema)(raw).pipe(
       Effect.mapError((cause) => new SyncValidationError({ message: "Invalid Sync Baseline", path, cause }))
     )
+    return baseline
   })
 
 export const serializeSyncBaseline = (baseline: SyncBaseline): string => `${JSON.stringify(baseline, null, 2)}\n`

package/src/internal/sync/changes.ts

@@ -47,7 +47,7 @@ export const compareIssueFields = (input: CompareIssueFieldsInput): CompareIssue
   ])
 
   for (const name of customFieldNames) {
-    const field = `customFields.${name}` as const
+    const field: SyncFieldPath = `customFields.${name}`
     const baseline = input.baseline.customFields[name]?.value
     const jira = input.jira.customFields[name]?.value
     const document = input.document.customFields[name]?.value

package/src/internal/sync/config.ts

@@ -19,8 +19,7 @@ export const parseWorkspaceConfig = (
       try: () => yaml.load(content) ?? {},
       catch: (cause) => new SyncWorkspaceError({ message: "Failed to parse workspace config YAML", path, cause })
     })
-    const config = yield* Schema.decodeUnknownEffect(WorkspaceConfigSchema)(raw).pipe(
-      Effect.map((config) => config as WorkspaceConfig),
+    const config: WorkspaceConfig = yield* Schema.decodeUnknownEffect(WorkspaceConfigSchema)(raw).pipe(
       Effect.mapError((cause) =>
         new SyncValidationError({ message: "Invalid Jira Markdown Sync workspace config", path, cause })
       )

package/src/internal/sync/document.ts

@@ -3,6 +3,8 @@
  *
  * @internal
  */
+import { isPreviewableAttachment } from "@knpkv/atlassian-common/attachments"
+import * as Predicate from "effect/Predicate"
 import matter from "gray-matter"
 import * as yaml from "js-yaml"
 import { SyncValidationError } from "../../JiraCliError.js"
@@ -11,11 +13,22 @@ import type {
   AttachmentReference,
   CommentDraft,
   IssueDocument,
-  IssueDocumentFrontMatter
+  IssueDocumentFrontMatter,
+  UserFieldValue
 } from "./types.js"
 
+const isStringArray = (value: unknown): value is ReadonlyArray<string> =>
+  Array.isArray(value) && value.every((item) => typeof item === "string")
+
+const isFrontMatterCustomFields = (
+  value: unknown
+): value is IssueDocumentFrontMatter["customFields"] => Predicate.isReadonlyObject(value)
+
 const yamlEngine = {
-  parse: (str: string): object => (yaml.load(str) as object) ?? {},
+  parse: (str: string): object => {
+    const value = yaml.load(str)
+    return Predicate.isReadonlyObject(value) ? value : {}
+  },
   stringify: (data: object): string => yaml.dump(data)
 }
 
@@ -78,40 +91,41 @@ const section = (name: string, content: string): string => {
 const parseFrontMatter = (path: string, data: Record<string, unknown>): IssueDocumentFrontMatter => {
   const requiredString = (key: string): string => {
     const value = data[key]
-    if (typeof value !== "string") fail(path, `Missing or invalid front matter field "${key}"`)
-    return value as string
+    if (typeof value === "string") return value
+    return fail(path, `Missing or invalid front matter field "${key}"`)
   }
 
   const nullableString = (key: string): string | null => {
     const value = data[key]
     if (value === null || value === undefined) return null
-    if (typeof value !== "string") fail(path, `Invalid front matter field "${key}"`)
-    return value as string
+    if (typeof value === "string") return value
+    return fail(path, `Invalid front matter field "${key}"`)
   }
 
-  const userValue = (key: string) => {
+  const userValue = (key: string): UserFieldValue | null => {
     const value = data[key]
     if (value === null || value === undefined) return null
-    if (typeof value !== "object") fail(path, `Invalid user field "${key}"`)
-    const record = value as Record<string, unknown>
-    if (typeof record["accountId"] !== "string" || typeof record["displayName"] !== "string") {
-      fail(path, `Invalid user field "${key}"`)
-    }
-    return {
-      accountId: record["accountId"] as string,
-      displayName: record["displayName"] as string
+    const record = Predicate.isReadonlyObject(value) ? value : fail(path, `Invalid user field "${key}"`)
+    const accountId = record["accountId"]
+    const displayName = record["displayName"]
+    if (typeof accountId === "string" && typeof displayName === "string") {
+      return {
+        accountId,
+        displayName
+      }
     }
+    return fail(path, `Invalid user field "${key}"`)
   }
 
   const labels = data["labels"]
-  if (!Array.isArray(labels) || labels.some((label) => typeof label !== "string")) {
-    fail(path, `Missing or invalid front matter field "labels"`)
-  }
+  const parsedLabels = isStringArray(labels)
+    ? labels
+    : fail(path, `Missing or invalid front matter field "labels"`)
 
   const customFields = data["customFields"]
-  if (customFields === null || typeof customFields !== "object" || Array.isArray(customFields)) {
-    fail(path, `Missing or invalid front matter field "customFields"`)
-  }
+  const parsedCustomFields = isFrontMatterCustomFields(customFields)
+    ? customFields
+    : fail(path, `Missing or invalid front matter field "customFields"`)
 
   return {
     issueId: requiredString("issueId"),
@@ -122,8 +136,8 @@ const parseFrontMatter = (path: string, data: Record<string, unknown>): IssueDoc
     priority: nullableString("priority"),
     assignee: userValue("assignee"),
     reporter: userValue("reporter"),
-    labels: labels as ReadonlyArray<string>,
-    customFields: customFields as IssueDocumentFrontMatter["customFields"]
+    labels: parsedLabels,
+    customFields: parsedCustomFields
   }
 }
 
@@ -180,13 +194,68 @@ const parseAcceptedComments = (content: string): ReadonlyArray<AcceptedComment>
 }
 
 const serializeAttachments = (attachments: ReadonlyArray<AttachmentReference>): string =>
-  attachments.map((attachment) => `- [${attachment.filename}](${attachment.url})`).join("\n")
+  attachments.map((attachment) => {
+    const metadata = {
+      jiraAttachmentId: attachment.id,
+      mediaType: attachment.mediaType,
+      size: attachment.size
+    }
+    const reference = isPreviewableAttachment(attachment)
+      ? `![${attachment.filename}](${attachment.url})`
+      : `[${attachment.filename}](${attachment.url})`
+    return `<!-- jiraAttachment: ${JSON.stringify(metadata)} -->\n${reference}`
+  }).join("\n\n")
 
-const parseAttachments = (content: string): ReadonlyArray<AttachmentReference> =>
-  content.split(/\r?\n/).flatMap((line) => {
-    const match = /^- \[(.+)]\((.+)\)$/.exec(line.trim())
-    return match?.[1] && match[2] ? [{ filename: match[1], url: match[2] }] : []
-  })
+const parseAttachments = (content: string): ReadonlyArray<AttachmentReference> => {
+  const lines = content.split(/\r?\n/)
+  const attachments: Array<AttachmentReference> = []
+  let pendingMetadata: Partial<Pick<AttachmentReference, "id" | "mediaType" | "size">> = {}
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim()
+    if (line.length === 0) continue
+
+    const metadataMatch = /^<!--\s*jiraAttachment:\s*(\{.*})\s*-->$/.exec(line)
+    if (metadataMatch?.[1]) {
+      pendingMetadata = parseAttachmentMetadata(metadataMatch[1])
+      continue
+    }
+
+    const markdownMatch = /^(?:-\s*)?!?\[(.+)]\((.+)\)$/.exec(line)
+    if (markdownMatch?.[1] && markdownMatch[2]) {
+      attachments.push({
+        id: pendingMetadata.id ?? "",
+        filename: markdownMatch[1],
+        url: markdownMatch[2],
+        mediaType: pendingMetadata.mediaType ?? null,
+        size: pendingMetadata.size ?? null
+      })
+      pendingMetadata = {}
+    }
+  }
+
+  return attachments
+}
+
+const parseAttachmentMetadata = (
+  raw: string
+): Partial<Pick<AttachmentReference, "id" | "mediaType" | "size">> => {
+  try {
+    const parsed = JSON.parse(raw)
+    if (!Predicate.isReadonlyObject(parsed)) return {}
+    return {
+      id: typeof parsed["jiraAttachmentId"] === "string"
+        ? parsed["jiraAttachmentId"]
+        : typeof parsed["id"] === "string"
+        ? parsed["id"]
+        : "",
+      mediaType: typeof parsed["mediaType"] === "string" ? parsed["mediaType"] : null,
+      size: typeof parsed["size"] === "number" ? parsed["size"] : null
+    }
+  } catch {
+    return {}
+  }
+}
 
 const trimOuterBlankLines = (lines: ReadonlyArray<string>): ReadonlyArray<string> => {
   let start = 0

package/src/internal/sync/fieldValues.ts

@@ -3,6 +3,7 @@
  *
  * @internal
  */
+import * as Predicate from "effect/Predicate"
 import type { CascadingFieldValue, OptionFieldValue, SyncFieldValue, UserFieldValue } from "./types.js"
 
 export type CompleteListItem = string | number | boolean | UserFieldValue | OptionFieldValue
@@ -44,18 +45,18 @@ export const completeListValue = (
 export const makeCompleteListValue = completeListValue
 
 export const isUserFieldValue = (value: unknown): value is UserFieldValue => {
-  if (!isRecord(value)) return false
+  if (!Predicate.isReadonlyObject(value)) return false
   return typeof value["accountId"] === "string" && typeof value["displayName"] === "string"
 }
 
 export const isOptionFieldValue = (value: unknown): value is OptionFieldValue => {
-  if (!isRecord(value) || typeof value["value"] !== "string") return false
+  if (!Predicate.isReadonlyObject(value) || typeof value["value"] !== "string") return false
   const id = value["id"]
   return id === undefined || typeof id === "string"
 }
 
 export const isCascadingFieldValue = (value: unknown): value is CascadingFieldValue => {
-  if (!isRecord(value) || !isOptionFieldValue(value["parent"])) return false
+  if (!Predicate.isReadonlyObject(value) || !isOptionFieldValue(value["parent"])) return false
   const child = value["child"]
   return child === undefined || isOptionFieldValue(child)
 }
@@ -140,6 +141,3 @@ const isCompleteListItem = (value: unknown): value is CompleteListItem => {
       return false
   }
 }
-
-const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
-  value !== null && typeof value === "object" && !Array.isArray(value)

package/src/internal/sync/manifest.ts

@@ -21,7 +21,7 @@ export const parseSyncManifest = (
 ): Effect.Effect<SyncManifest, SyncWorkspaceError | SyncValidationError> =>
   Effect.gen(function*() {
     const raw = yield* Effect.try({
-      try: () => JSON.parse(content) as unknown,
+      try: (): unknown => JSON.parse(content),
       catch: (cause) => new SyncWorkspaceError({ message: "Failed to parse Sync Manifest JSON", path, cause })
     })
     return yield* Schema.decodeUnknownEffect(SyncManifestSchema)(raw).pipe(

package/src/internal/sync/schemas.ts

@@ -12,6 +12,7 @@ const SiteUrl = Schema.String.pipe(
 )
 
 const NonEmptyString = Schema.String.pipe(Schema.check(Schema.isMinLength(1)))
+const FilenameModes: readonly ["convention", "custom"] = ["convention", "custom"]
 
 export const FieldShapeSchema = Schema.Literals(FIELD_SHAPES)
 
@@ -23,7 +24,7 @@ export const RequestedCustomFieldSchema = Schema.Struct({
 })
 
 export const WorkspaceConfigSchema = Schema.Struct({
-  version: Schema.Literal(1).pipe(Schema.withDecodingDefaultTypeKey(Effect.succeed(1 as const))),
+  version: Schema.Literal(1).pipe(Schema.withDecodingDefaultTypeKey(Effect.succeed(1))),
   siteUrl: SiteUrl,
   documentsDir: NonEmptyString.pipe(Schema.withDecodingDefaultTypeKey(Effect.succeed("issues"))),
   customFields: Schema.Array(RequestedCustomFieldSchema).pipe(
@@ -35,7 +36,7 @@ export const ManifestIssueSchema = Schema.Struct({
   issueId: NonEmptyString,
   issueKey: NonEmptyString,
   documentPath: NonEmptyString,
-  filenameMode: Schema.Literals(["convention", "custom"] as const)
+  filenameMode: Schema.Literals(FilenameModes)
 })
 
 export const SyncManifestSchema = Schema.Struct({

package/src/internal/sync/types.ts

@@ -4,7 +4,18 @@
  * @internal
  */
 
-export const FIELD_SHAPES = [
+export type FieldShape =
+  | "text"
+  | "multilineText"
+  | "number"
+  | "boolean"
+  | "date"
+  | "singleSelect"
+  | "multiSelect"
+  | "user"
+  | "cascadingSelect"
+
+export const FIELD_SHAPES: ReadonlyArray<FieldShape> = [
   "text",
   "multilineText",
   "number",
@@ -14,9 +25,7 @@ export const FIELD_SHAPES = [
   "multiSelect",
   "user",
   "cascadingSelect"
-] as const
-
-export type FieldShape = typeof FIELD_SHAPES[number]
+]
 
 export interface RequestedCustomField {
   readonly displayName: string
@@ -123,8 +132,11 @@ export interface AcceptedComment {
 }
 
 export interface AttachmentReference {
+  readonly id: string
   readonly filename: string
   readonly url: string
+  readonly mediaType: string | null
+  readonly size: number | null
 }
 
 export interface IssueDocument {

package/test/IssueService.test.ts

@@ -0,0 +1,94 @@
+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 HttpClient from "effect/unstable/http/HttpClient"
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse"
+import { IssueService, layer as IssueServiceLayer, SiteUrl } from "../src/IssueService.js"
+
+const httpClient = HttpClient.make((request) =>
+  Effect.succeed(HttpClientResponse.fromWeb(
+    request,
+    new Response(
+      JSON.stringify(
+        request.url.includes("/rest/api/3/issue/")
+          ? {
+            id: "10000",
+            key: "PROJ-123",
+            fields: {
+              attachment: [{
+                id: "30001",
+                filename: "diagram.svg",
+                content: "https://example.atlassian.net/rest/api/3/attachment/content/30001",
+                mimeType: "image/svg+xml",
+                size: 448
+              }, {
+                id: "30002",
+                filename: "unknown.bin",
+                content: "https://example.atlassian.net/rest/api/3/attachment/content/30002",
+                size: 99
+              }],
+              components: [],
+              created: "2026-01-01T00:00:00.000Z",
+              description: "",
+              fixVersions: [],
+              issuetype: { name: "Task" },
+              labels: [],
+              status: { name: "Done" },
+              summary: "Sample issue",
+              updated: "2026-01-01T00:00:00.000Z"
+            },
+            renderedFields: {}
+          }
+          : {}
+      ),
+      {
+        status: request.url.includes("/rest/api/3/issue/") ? 200 : 404,
+        headers: { "content-type": "application/json" }
+      }
+    )
+  ))
+)
+
+const api = make(httpClient, {
+  baseUrl: "https://jira.test",
+  auth: { type: "basic", email: "test@example.com", apiToken: Redacted.make("token") }
+})
+
+const JiraClientLayer = Layer.succeed(
+  JiraApiClient,
+  JiraApiClient.of({
+    ...api,
+    uploadAttachment: () => Effect.die("unused Jira upload mock")
+  })
+)
+
+const TestLayer = IssueServiceLayer.pipe(
+  Layer.provide(JiraClientLayer),
+  Layer.provide(Layer.succeed(SiteUrl, "https://example.atlassian.net"))
+)
+
+describe("IssueService", () => {
+  it.effect("keeps mimeType as a backwards-compatible attachment alias", () =>
+    Effect.gen(function*() {
+      const service = yield* IssueService
+      const issue = yield* service.getByKey("PROJ-123")
+
+      expect(issue.attachments).toEqual([{
+        id: "30001",
+        filename: "diagram.svg",
+        url: "https://example.atlassian.net/rest/api/3/attachment/content/30001",
+        mediaType: "image/svg+xml",
+        mimeType: "image/svg+xml",
+        size: 448
+      }, {
+        id: "30002",
+        filename: "unknown.bin",
+        url: "https://example.atlassian.net/rest/api/3/attachment/content/30002",
+        mediaType: null,
+        mimeType: "",
+        size: 99
+      }])
+    }).pipe(Effect.provide(TestLayer)))
+})

package/test/VersionService.test.ts

@@ -1,7 +1,10 @@
 import { describe, expect, it } from "@effect/vitest"
-import { JiraApiClient } from "@knpkv/jira-api-client"
+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 HttpClient from "effect/unstable/http/HttpClient"
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse"
 import { stripEmails } from "../src/commands/version.js"
 import type { Version } from "../src/VersionService.js"
 import {
@@ -206,34 +209,45 @@ describe("stripEmails", () => {
 // ---------------------------------------------------------------------------
 
 const versionsFixture = [
-  { id: "1", name: "1.0.0", released: true, self: "https://x/version/1" },
+  {
+    id: "1",
+    name: "1.0.0",
+    released: true,
+    self: "https://x/version/1",
+    contributors: ["account-1", { accountId: "account-2", displayName: "Ada" }]
+  },
   { id: "2", name: "2.0.0", released: false, self: "https://x/version/2" },
   { id: "3", name: "3.0.0", released: true, self: "https://x/version/3" },
   { id: "4", name: "4.0.0", released: false, self: "https://x/version/4" }
 ]
 
 /**
- * Build a JiraApiClient mock whose `v3.client.GET` routes by path: the version
+ * Build a JiraApiClient mock whose HTTP transport routes by path: the version
  * list endpoint returns the fixture; the JQL search endpoint returns no issues
  * (so the contributor scan resolves to empty without further calls).
  */
-const makeJiraLayer = () =>
-  Layer.succeed(JiraApiClient, {
-    v3: {
-      client: {
-        GET: (path: string) =>
-          path === "/rest/api/3/project/{projectIdOrKey}/version"
-            ? Promise.resolve({
-              data: { values: versionsFixture, isLast: true },
-              response: { ok: true, status: 200 }
-            })
-            : Promise.resolve({
-              data: { issues: [], isLast: true },
-              response: { ok: true, status: 200 }
-            })
-      }
-    }
-  } as never)
+const makeJiraLayer = () => {
+  const httpClient = HttpClient.make((request) => {
+    const body = request.url.includes("/project/PROJ/version")
+      ? { values: versionsFixture, isLast: true }
+      : { issues: [], isLast: true }
+    return Effect.succeed(HttpClientResponse.fromWeb(
+      request,
+      new Response(JSON.stringify(body), { status: 200, headers: { "content-type": "application/json" } })
+    ))
+  })
+  const api = make(httpClient, {
+    baseUrl: "https://jira.test",
+    auth: { type: "basic", email: "test@example.com", apiToken: Redacted.make("token") }
+  })
+  return Layer.succeed(
+    JiraApiClient,
+    JiraApiClient.of({
+      ...api,
+      uploadAttachment: () => Effect.die("unused Jira upload mock")
+    })
+  )
+}
 
 describe("listProjectVersions filtering", () => {
   it.effect("returns all versions when neither flag is set", () =>
@@ -263,4 +277,11 @@ describe("listProjectVersions filtering", () => {
       const list = yield* service.listProjectVersions("PROJ", { maxResults: 2 })
       expect(list.map((v) => v.id)).toEqual(["1", "2"])
     }).pipe(Effect.provide(VersionServiceLayer), Effect.provide(makeJiraLayer())))
+
+  it.effect("preserves Jira Premium contributors decoded from the generated Version schema", () =>
+    Effect.gen(function*() {
+      const service = yield* VersionService
+      const list = yield* service.listProjectVersions("PROJ", { maxResults: 1 })
+      expect(list[0]?.contributors.map((person) => person.accountId)).toEqual(["account-1", "account-2"])
+    }).pipe(Effect.provide(VersionServiceLayer), Effect.provide(makeJiraLayer())))
 })

package/test/attachmentInsertion.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest"
+import { insertJiraAttachmentReference } from "../src/internal/attachmentInsertion.js"
+import type { Attachment } from "../src/IssueService.js"
+
+const attachment: Attachment = {
+  id: "30001",
+  filename: "diagram.svg",
+  url: "https://example.atlassian.net/rest/api/3/attachment/content/30001",
+  mediaType: "image/svg+xml",
+  mimeType: "image/svg+xml",
+  size: 448
+}
+
+describe("Jira attachment insertion", () => {
+  it("preserves the placeholder label as rendered alt text", () => {
+    const result = insertJiraAttachmentReference(
+      "before\n![Architecture diagram](./diagram.svg)\nafter",
+      "./diagram.svg",
+      attachment
+    )
+
+    expect(result.content).toContain("![Architecture diagram]")
+    expect(result.content).not.toContain("![diagram.svg]")
+  })
+})