@knpkv/jira-cli 1.1.2 → 1.2.0

package/test/IssueService.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "@effect/vitest"
+import { JiraApiClient } from "@knpkv/jira-api-client"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import { IssueService, layer as IssueServiceLayer, SiteUrl } from "../src/IssueService.js"
+
+const JiraClientLayer = Layer.succeed(
+  JiraApiClient,
+  JiraApiClient.of({
+    v3: {
+      client: {
+        GET: (path: string) =>
+          path === "/rest/api/3/issue/{issueIdOrKey}"
+            ? Promise.resolve({
+              data: {
+                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: {}
+              },
+              response: { ok: true, status: 200 }
+            })
+            : Promise.resolve({ data: {}, response: { ok: false, status: 404 } })
+      }
+    }
+  })
+)
+
+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,9 @@
 import { describe, expect, it } from "@effect/vitest"
-import { JiraApiClient } from "@knpkv/jira-api-client"
+import { JiraApiClient, type JiraApiClientShape } from "@knpkv/jira-api-client"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
+import type { paths as V3Paths } from "../../jira-api-client/src/generated/v3/schema.js"
+import { makeOpenApiFetchClient } from "../../jira-api-client/src/OpenApiFetchClient.js"
 import { stripEmails } from "../src/commands/version.js"
 import type { Version } from "../src/VersionService.js"
 import {
@@ -218,22 +220,25 @@ const versionsFixture = [
  * (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 }
-            })
+  Layer.succeed(
+    JiraApiClient,
+    {
+      v3: {
+        client: Object.assign(makeOpenApiFetchClient<V3Paths>("https://jira.test", {}).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)
+    } satisfies JiraApiClientShape
+  )
 
 describe("listProjectVersions filtering", () => {
   it.effect("returns all versions when neither flag is set", () =>

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]")
+  })
+})

package/test/commandTree.test.ts

@@ -4,6 +4,7 @@ import * as Layer from "effect/Layer"
 import * as Ref from "effect/Ref"
 import * as Terminal from "effect/Terminal"
 import { Command } from "effect/unstable/cli"
+import { AttachmentService } from "../src/AttachmentService.js"
 import { issueCommand } from "../src/commands/issue.js"
 import { versionCommand } from "../src/commands/version.js"
 import { type Issue, IssueService } from "../src/IssueService.js"
@@ -13,6 +14,7 @@ import { type RelatedWork, type Version, VersionService } from "../src/VersionSe
 interface CommandCalls {
   readonly issueGet: number
   readonly issueSearch: number
+  readonly issueAttachmentUpload: number
   readonly versionList: number
   readonly versionGet: number
   readonly versionUpdate: number
@@ -23,6 +25,7 @@ interface CommandCalls {
 
 const emptyCalls: CommandCalls = {
   issueGet: 0,
+  issueAttachmentUpload: 0,
   issueSearch: 0,
   relatedWorkAdd: 0,
   relatedWorkList: 0,
@@ -52,6 +55,15 @@ const sampleIssue: Issue = {
   url: "https://example.atlassian.net/browse/PROJ-123"
 }
 
+const sampleAttachment = {
+  id: "30001",
+  filename: "evidence.png",
+  url: "https://example.atlassian.net/rest/api/3/attachment/content/30001",
+  mediaType: "image/png",
+  mimeType: "image/png",
+  size: 123
+}
+
 const sampleVersion: Version = {
   approvers: [],
   archived: false,
@@ -88,6 +100,16 @@ const CaptureTerminalLayer = (stdout: Ref.Ref<string>) =>
 
 const CommandServicesLayer = (calls: Ref.Ref<CommandCalls>) =>
   Layer.mergeAll(
+    Layer.succeed(
+      AttachmentService,
+      AttachmentService.of({
+        uploadToIssue: () =>
+          Ref.update(calls, (state) => ({
+            ...state,
+            issueAttachmentUpload: state.issueAttachmentUpload + 1
+          })).pipe(Effect.as(sampleAttachment))
+      })
+    ),
     Layer.succeed(
       IssueService,
       IssueService.of({
@@ -158,24 +180,40 @@ describe("Jira command tree", () => {
       const calls = yield* Ref.make(emptyCalls)
       const getOutput = yield* Ref.make("")
       const searchOutput = yield* Ref.make("")
+      const uploadOutput = yield* Ref.make("")
       const legacyGetOutput = yield* Ref.make("")
       const legacySearchOutput = yield* Ref.make("")
 
       const getExit = yield* runJiraCommand(["issue", "get", "PROJ-123"], calls, getOutput)
       const searchExit = yield* runJiraCommand(["issue", "search", "project = PROJ"], calls, searchOutput)
+      const uploadExit = yield* runJiraCommand(
+        [
+          "issue",
+          "attachment",
+          "upload",
+          "PROJ-123",
+          "./evidence.png",
+          "--no-insert"
+        ],
+        calls,
+        uploadOutput
+      )
       const legacyGetExit = yield* runJiraCommand(["get", "PROJ-123"], calls, legacyGetOutput)
       const legacySearchExit = yield* runJiraCommand(["search", "project = PROJ"], calls, legacySearchOutput)
 
       expect(getExit._tag).toBe("Success")
       expect(searchExit._tag).toBe("Success")
+      expect(uploadExit._tag).toBe("Success")
       expect(legacyGetExit._tag).toBe("Failure")
       expect(legacySearchExit._tag).toBe("Failure")
 
       expect(yield* Ref.get(calls)).toMatchObject({
         issueGet: 1,
+        issueAttachmentUpload: 1,
         issueSearch: 1,
         writeMulti: 2
       })
+      expect(sampleAttachment.mimeType).toBe(sampleAttachment.mediaType)
     }))
 
   it.effect("exposes canonical version commands and rejects legacy names", () =>

package/test/frontmatter.test.ts

@@ -10,7 +10,10 @@ import type { Issue } from "../src/IssueService.js"
  */
 const parseFrontMatter = (output: string): Record<string, unknown> => {
   const match = output.match(/^---\n([\s\S]*?)\n---/)
-  return match ? (yaml.load(match[1]) as Record<string, unknown>) : {}
+  const parsed = match ? yaml.load(match[1]) : {}
+  return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+    ? Object.fromEntries(Object.entries(parsed))
+    : {}
 }
 
 const makeIssue = (overrides: Partial<Issue> = {}): Issue => ({
@@ -57,6 +60,22 @@ describe("frontmatter", () => {
       expect(data.priority).toBeNull()
       expect(data.assignee).toBeNull()
     })
+
+    it("renders image and SVG attachments as inline previews with identity metadata", () => {
+      const output = serializeIssue(makeIssue({
+        attachments: [{
+          id: "10001",
+          filename: "diagram.svg",
+          url: "https://example.atlassian.net/rest/api/3/attachment/content/10001",
+          mediaType: "application/octet-stream",
+          size: 42
+        }]
+      }))
+      expect(output).toContain(
+        "<!-- jiraAttachment: {\"jiraAttachmentId\":\"10001\",\"mediaType\":\"application/octet-stream\",\"size\":42} -->"
+      )
+      expect(output).toContain("![diagram.svg](https://example.atlassian.net/rest/api/3/attachment/content/10001)")
+    })
   })
 
   describe("extractFrontMatter", () => {

package/test/integration.test.ts

@@ -18,11 +18,14 @@ import * as FileSystem from "effect/FileSystem"
 import * as Path from "effect/Path"
 import * as Redacted from "effect/Redacted"
 import * as yaml from "js-yaml"
+import { AttachmentService, layer as AttachmentServiceLayer } from "../src/AttachmentService.js"
+import { insertJiraAttachmentReference } from "../src/internal/attachmentInsertion.js"
 import { IssueService, layer as IssueServiceLayer, SiteUrl } from "../src/IssueService.js"
 import { layer as MarkdownWriterLayer, MarkdownWriter } from "../src/MarkdownWriter.js"
 
 const DEFAULT_BASE_URL = "https://knpkv.atlassian.net"
 const DEFAULT_ISSUE_KEY = "KAN-1"
+const INTEGRATION_ATTACHMENT_FILENAME = "inline-attachment.svg"
 
 interface IntegrationConfig {
   readonly baseUrl: string
@@ -54,6 +57,20 @@ const SHOULD_RUN_INTEGRATION = Effect.runSync(
   )
 )
 
+const SHOULD_RUN_ATTACHMENT_INTEGRATION = Effect.runSync(
+  Effect.all([
+    Config.option(Config.string("JIRA_INTEGRATION")),
+    Config.option(Config.string("JIRA_ATTACHMENT_INTEGRATION"))
+  ]).pipe(
+    Effect.map(([integration, attachment]) =>
+      Option.isSome(integration) &&
+      envFlagEnabled(integration.value) &&
+      Option.isSome(attachment) &&
+      envFlagEnabled(attachment.value)
+    )
+  )
+)
+
 const readIntegrationConfig = Effect.gen(function*() {
   const baseUrl = yield* Config.option(Config.string("JIRA_BASE_URL"))
   const issueKey = yield* Config.option(Config.string("JIRA_ISSUE_KEY"))
@@ -72,13 +89,14 @@ const makeIntegrationLayer = (config: IntegrationConfig) => {
   const configLayer = Layer.succeed(JiraApiConfig, {
     baseUrl: config.baseUrl,
     auth: {
-      type: "basic" as const,
+      type: "basic",
       email: config.email,
       apiToken: config.apiKey
-    }
+    } satisfies { readonly type: "basic"; readonly email: string; readonly apiToken: typeof config.apiKey }
   })
 
   return MarkdownWriterLayer.pipe(
+    Layer.provideMerge(AttachmentServiceLayer),
     Layer.provideMerge(IssueServiceLayer),
     Layer.provideMerge(Layer.succeed(SiteUrl, config.baseUrl)),
     Layer.provideMerge(JiraApiClient.layer),
@@ -102,16 +120,49 @@ const readText = (filePath: string) =>
     Effect.flatMap((fs) => fs.readFileString(filePath))
   )
 
+const writeText = (filePath: string, content: string) =>
+  FileSystem.FileSystem.pipe(
+    Effect.flatMap((fs) => fs.writeFileString(filePath, content))
+  )
+
 const pathExists = (filePath: string) =>
   FileSystem.FileSystem.pipe(
     Effect.flatMap((fs) => fs.exists(filePath))
   )
 
+const integrationAttachmentFixturePath = Path.Path.pipe(
+  Effect.flatMap((path) =>
+    path.fromFileUrl(new URL("../../atlassian-common/test/fixtures/attachments/inline-attachment.svg", import.meta.url))
+  )
+)
+
+const copyIntegrationAttachmentAsset = (testDir: string) =>
+  Effect.gen(function*() {
+    const source = yield* integrationAttachmentFixturePath
+    const target = yield* joinPath(testDir, INTEGRATION_ATTACHMENT_FILENAME)
+    yield* writeText(target, yield* readText(source))
+    return target
+  })
+
+const expectCanonicalIssueIncludesAttachmentMedia = (
+  config: IntegrationConfig,
+  issue: { readonly attachments: ReadonlyArray<{ readonly filename: string }> },
+  markdown: string
+) => {
+  if (config.issueKey !== DEFAULT_ISSUE_KEY) return
+
+  expect(issue.attachments.some((attachment) => attachment.filename === INTEGRATION_ATTACHMENT_FILENAME)).toBe(true)
+  expect(markdown).toContain("## Attachments")
+  expect(markdown).toContain(`![${INTEGRATION_ATTACHMENT_FILENAME}](`)
+  expect(markdown).toContain("jiraAttachmentId")
+  expect(markdown).toContain("image/svg+xml")
+}
+
 const parseFrontMatter = (markdown: string): Record<string, unknown> => {
   const match = /^---\n([\s\S]*?)\n---/.exec(markdown)
   const parsed = match?.[1] ? yaml.load(match[1]) : {}
   return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
-    ? parsed as Record<string, unknown>
+    ? Object.fromEntries(Object.entries(parsed))
     : {}
 }
 
@@ -140,6 +191,7 @@ const getIssueAsMarkdown = (config: IntegrationConfig, testDir: string) =>
     expect(frontMatter.summary).toBe(issue.summary)
     expect(typeof frontMatter.status).toBe("string")
     expect(markdown).toContain(`# ${config.issueKey}:`)
+    expectCanonicalIssueIncludesAttachmentMedia(config, issue, markdown)
 
     return { frontMatter, issue }
   })
@@ -184,4 +236,41 @@ describe("Jira integration", () => {
       }),
     120000
   )
+
+  it.effect.skipIf(!SHOULD_RUN_ATTACHMENT_INTEGRATION)(
+    "uploads an SVG attachment and inserts a Markdown attachment reference",
+    () =>
+      Effect.gen(function*() {
+        const config = yield* readIntegrationConfig
+        return yield* Effect.gen(function*() {
+          const testDir = yield* makeTempRoot
+          const assetPath = yield* copyIntegrationAttachmentAsset(testDir)
+          const documentPath = yield* joinPath(testDir, `${config.issueKey}.md`)
+          yield* writeText(documentPath, `# ${config.issueKey}\n\n![Attachment proof](${assetPath})\n`)
+
+          const attachmentService = yield* AttachmentService
+          const issueService = yield* IssueService
+          const attachment = yield* attachmentService.uploadToIssue(config.issueKey, { filePath: assetPath })
+          expect(attachment.id).toBeTruthy()
+          expect(attachment.filename).toBe(INTEGRATION_ATTACHMENT_FILENAME)
+          expect(attachment.mediaType === null || attachment.mediaType.includes("svg")).toBe(true)
+
+          const issue = yield* issueService.getByKey(config.issueKey)
+          expect(issue.attachments.some((candidate) => candidate.id === attachment.id)).toBe(true)
+
+          const insertion = insertJiraAttachmentReference(yield* readText(documentPath), assetPath, attachment)
+          expect(insertion.replacements).toBe(1)
+          yield* writeText(documentPath, insertion.content)
+
+          const updated = yield* readText(documentPath)
+          expect(updated).toContain(`"jiraAttachmentId":"${attachment.id}"`)
+          expect(updated).toContain(`![${INTEGRATION_ATTACHMENT_FILENAME}](`)
+          expect(updated).not.toContain(`![Attachment proof](${assetPath})`)
+        }).pipe(
+          Effect.provide(makeIntegrationLayer(config)),
+          Effect.scoped
+        )
+      }),
+    120000
+  )
 })

package/test/layers.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "@effect/vitest"
+import { getLayerType } from "../src/commands/layers.js"
+
+describe("getLayerType", () => {
+  it("routes attachment upload dry-runs to the config-free minimal layer", () => {
+    expect(getLayerType(["issue", "attachment", "upload", "PROJ-1", "./evidence.png", "--dry-run"])).toBe(
+      "minimal"
+    )
+    expect(getLayerType(["issue", "attachment", "upload", "PROJ-1", "./evidence.png", "-n"])).toBe("minimal")
+    expect(getLayerType(["issue", "attachment", "upload", "PROJ-1", "./evidence.png"])).toBe("full")
+  })
+})

package/test/syncDocument.test.ts

@@ -29,7 +29,13 @@ const document: IssueDocument = {
     created: "2026-06-27",
     body: "Existing Jira comment."
   }],
-  attachments: [{ filename: "evidence.png", url: "https://example.atlassian.net/evidence.png" }],
+  attachments: [{
+    id: "30001",
+    filename: "evidence.png",
+    url: "https://example.atlassian.net/evidence.png",
+    mediaType: "image/png",
+    size: 1234
+  }],
   localNotes: "Private local note."
 }
 
@@ -66,4 +72,27 @@ describe("Issue Document parsing", () => {
     const serialized = serializeIssueDocument(document).replace("<!-- draftId: draft-1 -->", "<!-- draft: draft-1 -->")
     expect(() => parseIssueDocument("PROJ-123.md", serialized)).toThrow(SyncValidationError)
   })
+
+  it("renders image attachments inline with hidden identity metadata", () => {
+    const serialized = serializeIssueDocument(document)
+    expect(serialized).toContain(
+      "<!-- jiraAttachment: {\"jiraAttachmentId\":\"30001\",\"mediaType\":\"image/png\",\"size\":1234} -->"
+    )
+    expect(serialized).toContain("![evidence.png](https://example.atlassian.net/evidence.png)")
+  })
+
+  it("keeps parsing legacy attachment link lines", () => {
+    const serialized = serializeIssueDocument(document).replace(
+      /<!-- jiraAttachment:[\s\S]*?\n!\[evidence\.png]\(https:\/\/example\.atlassian\.net\/evidence\.png\)/,
+      "- [evidence.png](https://example.atlassian.net/evidence.png)"
+    )
+    const parsed = parseIssueDocument("PROJ-123.md", serialized)
+    expect(parsed.attachments).toEqual([{
+      id: "",
+      filename: "evidence.png",
+      url: "https://example.atlassian.net/evidence.png",
+      mediaType: null,
+      size: null
+    }])
+  })
 })

package/vitest.config.integration.ts

@@ -3,6 +3,10 @@ import { defineConfig } from "vitest/config"
 export default defineConfig({
   resolve: {
     alias: {
+      "@knpkv/atlassian-common/attachments": new URL("../atlassian-common/src/attachments.ts", import.meta.url).pathname,
+      "@knpkv/atlassian-common/auth": new URL("../atlassian-common/src/auth/index.ts", import.meta.url).pathname,
+      "@knpkv/atlassian-common/config": new URL("../atlassian-common/src/config/index.ts", import.meta.url).pathname,
+      "@knpkv/agent-skills": new URL("../agent-skills/src/index.ts", import.meta.url).pathname,
       "@knpkv/jira-api-client": new URL("../jira-api-client/src/index.ts", import.meta.url).pathname
     }
   },

package/vitest.config.ts

@@ -3,6 +3,10 @@ import { defineConfig } from "vitest/config"
 export default defineConfig({
   resolve: {
     alias: {
+      "@knpkv/atlassian-common/attachments": new URL("../atlassian-common/src/attachments.ts", import.meta.url).pathname,
+      "@knpkv/atlassian-common/auth": new URL("../atlassian-common/src/auth/index.ts", import.meta.url).pathname,
+      "@knpkv/atlassian-common/config": new URL("../atlassian-common/src/config/index.ts", import.meta.url).pathname,
+      "@knpkv/agent-skills": new URL("../agent-skills/src/index.ts", import.meta.url).pathname,
       "@knpkv/jira-api-client": new URL("../jira-api-client/src/index.ts", import.meta.url).pathname
     }
   },