@knpkv/jira-cli 0.3.0 → 1.0.0

package/test/integration.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Read-only integration tests for Jira issue fetching and Markdown export.
+ *
+ * Requires:
+ * - JIRA_INTEGRATION=1
+ * - JIRA_EMAIL
+ * - JIRA_API_KEY
+ *
+ * Optional overrides:
+ * - JIRA_BASE_URL defaults to https://knpkv.atlassian.net
+ * - JIRA_ISSUE_KEY defaults to KAN-1
+ */
+import * as NodeServices from "@effect/platform-node/NodeServices"
+import { describe, expect, it } from "@effect/vitest"
+import { JiraApiClient, JiraApiConfig } from "@knpkv/jira-api-client"
+import { Config, Effect, Layer, Option } from "effect"
+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 { 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"
+
+interface IntegrationConfig {
+  readonly baseUrl: string
+  readonly issueKey: string
+  readonly email: string
+  readonly apiKey: Redacted.Redacted<string>
+}
+
+const envFlagEnabled = (value: string): boolean => ["1", "true", "yes"].includes(value.toLowerCase())
+
+const nonEmptyOrDefault = (value: Option.Option<string>, fallback: string): string =>
+  Option.match(value, {
+    onNone: () => fallback,
+    onSome: (some) => some.trim().length > 0 ? some : fallback
+  })
+
+const requireNonEmpty = (name: string, value: string): Effect.Effect<string, Error> =>
+  value.trim().length > 0 ? Effect.succeed(value) : Effect.fail(new Error(`${name} must be set`))
+
+const requireNonEmptyRedacted = (
+  name: string,
+  value: Redacted.Redacted<string>
+): Effect.Effect<Redacted.Redacted<string>, Error> =>
+  Redacted.value(value).trim().length > 0 ? Effect.succeed(value) : Effect.fail(new Error(`${name} must be set`))
+
+const SHOULD_RUN_INTEGRATION = Effect.runSync(
+  Config.option(Config.string("JIRA_INTEGRATION")).pipe(
+    Effect.map((enabled) => Option.isSome(enabled) && envFlagEnabled(enabled.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"))
+  const email = yield* Config.string("JIRA_EMAIL")
+  const apiKey = yield* Config.redacted("JIRA_API_KEY")
+
+  return {
+    baseUrl: nonEmptyOrDefault(baseUrl, DEFAULT_BASE_URL).replace(/\/+$/, ""),
+    issueKey: nonEmptyOrDefault(issueKey, DEFAULT_ISSUE_KEY),
+    email: yield* requireNonEmpty("JIRA_EMAIL", email),
+    apiKey: yield* requireNonEmptyRedacted("JIRA_API_KEY", apiKey)
+  } satisfies IntegrationConfig
+})
+
+const makeIntegrationLayer = (config: IntegrationConfig) => {
+  const configLayer = Layer.succeed(JiraApiConfig, {
+    baseUrl: config.baseUrl,
+    auth: {
+      type: "basic" as const,
+      email: config.email,
+      apiToken: config.apiKey
+    }
+  })
+
+  return MarkdownWriterLayer.pipe(
+    Layer.provideMerge(IssueServiceLayer),
+    Layer.provideMerge(Layer.succeed(SiteUrl, config.baseUrl)),
+    Layer.provideMerge(JiraApiClient.layer),
+    Layer.provideMerge(configLayer),
+    Layer.provideMerge(NodeServices.layer)
+  )
+}
+
+const makeTempRoot = Effect.gen(function*() {
+  const fs = yield* FileSystem.FileSystem
+  return yield* fs.makeTempDirectoryScoped()
+})
+
+const joinPath = (...parts: ReadonlyArray<string>) =>
+  Path.Path.pipe(
+    Effect.map((path) => path.join(...parts))
+  )
+
+const readText = (filePath: string) =>
+  FileSystem.FileSystem.pipe(
+    Effect.flatMap((fs) => fs.readFileString(filePath))
+  )
+
+const pathExists = (filePath: string) =>
+  FileSystem.FileSystem.pipe(
+    Effect.flatMap((fs) => fs.exists(filePath))
+  )
+
+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>
+    : {}
+}
+
+const getIssueAsMarkdown = (config: IntegrationConfig, testDir: string) =>
+  Effect.gen(function*() {
+    const issueService = yield* IssueService
+    const writer = yield* MarkdownWriter
+    const outputDir = yield* joinPath(testDir, "get-output")
+
+    const issue = yield* issueService.getByKey(config.issueKey)
+    yield* writer.writeMulti([issue], outputDir)
+
+    expect(issue.key).toBe(config.issueKey)
+    expect(issue.url).toBe(`${config.baseUrl}/browse/${config.issueKey}`)
+    expect(issue.summary.length).toBeGreaterThan(0)
+
+    const issueFile = yield* joinPath(outputDir, `${config.issueKey}.md`)
+    expect(yield* pathExists(issueFile)).toBe(true)
+
+    const markdown = yield* readText(issueFile)
+    const frontMatter = parseFrontMatter(markdown)
+
+    expect(frontMatter.key).toBe(config.issueKey)
+    expect(frontMatter.url).toBe(`${config.baseUrl}/browse/${config.issueKey}`)
+    expect(frontMatter.id).toBe(issue.id)
+    expect(frontMatter.summary).toBe(issue.summary)
+    expect(typeof frontMatter.status).toBe("string")
+    expect(markdown).toContain(`# ${config.issueKey}:`)
+
+    return { frontMatter, issue }
+  })
+
+const searchIssueAsSingleMarkdown = (config: IntegrationConfig, testDir: string) =>
+  Effect.gen(function*() {
+    const issueService = yield* IssueService
+    const writer = yield* MarkdownWriter
+    const outputDir = yield* joinPath(testDir, "search-output")
+    const jql = `issuekey = ${config.issueKey}`
+
+    const issues = yield* issueService.searchAll(jql, { maxResults: 1 })
+    expect(issues.map((issue) => issue.key)).toContain(config.issueKey)
+
+    yield* writer.writeSingle(issues, outputDir, jql)
+
+    const exportFile = yield* joinPath(outputDir, "jira-export.md")
+    expect(yield* pathExists(exportFile)).toBe(true)
+
+    const markdown = yield* readText(exportFile)
+    expect(markdown).toContain("# Jira Export")
+    expect(markdown).toContain(`Query: \`${jql}\``)
+    expect(markdown).toContain(`## ${config.issueKey}:`)
+  })
+
+describe("Jira integration", () => {
+  it.effect.skipIf(!SHOULD_RUN_INTEGRATION)(
+    "fetches KAN-1 with an API key and exports it as markdown",
+    () =>
+      Effect.gen(function*() {
+        const config = yield* readIntegrationConfig
+        return yield* Effect.gen(function*() {
+          const testDir = yield* makeTempRoot
+
+          const { frontMatter, issue } = yield* getIssueAsMarkdown(config, testDir)
+          yield* searchIssueAsSingleMarkdown(config, testDir)
+          expect(frontMatter.key).toBe(issue.key)
+        }).pipe(
+          Effect.provide(makeIntegrationLayer(config)),
+          Effect.scoped
+        )
+      }),
+    120000
+  )
+})

package/test/syncChanges.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "@effect/vitest"
+import { compareIssueFields } from "../src/internal/sync/changes.js"
+import type { SyncBaselineFields } from "../src/internal/sync/types.js"
+
+const fields = (overrides: Partial<SyncBaselineFields> = {}): SyncBaselineFields => ({
+  summary: "Baseline summary",
+  description: "Baseline description",
+  labels: ["a", "b"],
+  customFields: {
+    Risk: {
+      fieldId: "customfield_1",
+      displayName: "Risk",
+      shape: "singleSelect",
+      value: { id: "1", value: "Low" }
+    }
+  },
+  ...overrides
+})
+
+const compare = (
+  jira: SyncBaselineFields,
+  document: SyncBaselineFields,
+  baseline: SyncBaselineFields = fields()
+) =>
+  compareIssueFields({
+    issueId: "100123",
+    issueKey: "PROJ-123",
+    baseline,
+    jira,
+    document
+  })
+
+describe("compareIssueFields", () => {
+  it("returns no changes when Jira and document match the baseline", () => {
+    const result = compare(fields(), fields())
+    expect(result.changes).toEqual([])
+    expect(result.validationFailures).toEqual([])
+  })
+
+  it("classifies remote-only changes", () => {
+    const result = compare(fields({ summary: "Remote summary" }), fields())
+    expect(result.changes).toEqual([{
+      _tag: "RemoteOnly",
+      issueId: "100123",
+      issueKey: "PROJ-123",
+      field: "summary",
+      jiraValue: "Remote summary"
+    }])
+  })
+
+  it("classifies local-only changes", () => {
+    const result = compare(fields(), fields({ description: "Local description" }))
+    expect(result.changes).toEqual([{
+      _tag: "LocalOnly",
+      issueId: "100123",
+      issueKey: "PROJ-123",
+      field: "description",
+      documentValue: "Local description"
+    }])
+  })
+
+  it("classifies sync conflicts", () => {
+    const result = compare(fields({ summary: "Remote summary" }), fields({ summary: "Local summary" }))
+    expect(result.changes).toEqual([{
+      _tag: "Conflict",
+      issueId: "100123",
+      issueKey: "PROJ-123",
+      field: "summary",
+      baselineValue: "Baseline summary",
+      jiraValue: "Remote summary",
+      documentValue: "Local summary"
+    }])
+  })
+
+  it("compares custom fields", () => {
+    const result = compare(
+      fields(),
+      fields({
+        customFields: {
+          Risk: {
+            fieldId: "customfield_1",
+            displayName: "Risk",
+            shape: "singleSelect",
+            value: { id: "2", value: "High" }
+          }
+        }
+      })
+    )
+
+    expect(result.changes[0]).toMatchObject({
+      _tag: "LocalOnly",
+      field: "customFields.Risk",
+      documentValue: { id: "2", value: "High" }
+    })
+  })
+
+  it("reports missing custom fields as validation failures", () => {
+    const result = compare(fields(), fields({ customFields: {} }))
+    expect(result.validationFailures).toEqual([{
+      _tag: "ValidationFailure",
+      issueKey: "PROJ-123",
+      field: "customFields.Risk",
+      message: "Missing reconciled custom field \"Risk\""
+    }])
+  })
+})

package/test/syncConfig.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from "@effect/vitest"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import { parseSyncBaseline, serializeSyncBaseline } from "../src/internal/sync/baseline.js"
+import { parseWorkspaceConfig, serializeWorkspaceConfig } from "../src/internal/sync/config.js"
+import { makeEmptyManifest, parseSyncManifest, serializeSyncManifest } from "../src/internal/sync/manifest.js"
+import type { SyncBaseline } from "../src/internal/sync/types.js"
+
+const runExit = <A, E>(effect: Effect.Effect<A, E>): Promise<Exit.Exit<A, E>> => Effect.runPromiseExit(effect)
+
+describe("Jira Markdown Sync local data", () => {
+  describe("WorkspaceConfig", () => {
+    it("parses defaults and requested custom fields", async () => {
+      const result = await Effect.runPromise(parseWorkspaceConfig(
+        "config.yaml",
+        `
+siteUrl: https://example.atlassian.net
+customFields:
+  - displayName: Security & Compliance Impact
+    shape: singleSelect
+  - displayName: Reviewer
+    fieldId: customfield_12345
+    shape: user
+`
+      ))
+
+      expect(result.documentsDir).toBe("issues")
+      expect(result.customFields).toHaveLength(2)
+      expect(result.customFields[1]).toMatchObject({
+        displayName: "Reviewer",
+        fieldId: "customfield_12345",
+        shape: "user"
+      })
+    })
+
+    it("rejects unsupported field shapes", async () => {
+      const result = await runExit(parseWorkspaceConfig(
+        "config.yaml",
+        `
+siteUrl: https://example.atlassian.net
+customFields:
+  - displayName: Mystery
+    shape: unsupported
+`
+      ))
+
+      expect(Exit.isFailure(result)).toBe(true)
+    })
+
+    it("rejects duplicate display names without field ids", async () => {
+      const result = await runExit(parseWorkspaceConfig(
+        "config.yaml",
+        `
+siteUrl: https://example.atlassian.net
+customFields:
+  - displayName: Reviewer
+    shape: user
+  - displayName: Reviewer
+    shape: user
+`
+      ))
+
+      expect(Exit.isFailure(result)).toBe(true)
+    })
+
+    it("allows duplicate display names when field ids disambiguate", async () => {
+      const config = await Effect.runPromise(parseWorkspaceConfig(
+        "config.yaml",
+        `
+siteUrl: https://example.atlassian.net
+customFields:
+  - displayName: Reviewer
+    fieldId: customfield_1
+    shape: user
+  - displayName: Reviewer
+    fieldId: customfield_2
+    shape: user
+`
+      ))
+
+      expect(config.customFields).toHaveLength(2)
+    })
+
+    it("round-trips YAML serialization", async () => {
+      const config = await Effect.runPromise(parseWorkspaceConfig(
+        "config.yaml",
+        `
+siteUrl: https://example.atlassian.net
+documentsDir: issue-docs
+customFields: []
+`
+      ))
+
+      const parsed = await Effect.runPromise(parseWorkspaceConfig("config.yaml", serializeWorkspaceConfig(config)))
+      expect(parsed).toEqual(config)
+    })
+  })
+
+  describe("SyncManifest", () => {
+    it("round-trips an empty manifest", async () => {
+      const manifest = makeEmptyManifest("https://example.atlassian.net")
+      const parsed = await Effect.runPromise(parseSyncManifest("manifest.json", serializeSyncManifest(manifest)))
+      expect(parsed).toEqual(manifest)
+    })
+  })
+
+  describe("SyncBaseline", () => {
+    const baseline: SyncBaseline = {
+      version: 1,
+      issueId: "100123",
+      issueKey: "PROJ-123",
+      fields: {
+        summary: "Fix checkout copy",
+        description: "Editable description",
+        labels: ["checkout", "copy"],
+        customFields: {
+          "Security & Compliance Impact": {
+            fieldId: "customfield_10001",
+            displayName: "Security & Compliance Impact",
+            shape: "singleSelect",
+            value: { id: "10423", value: "Low" }
+          }
+        }
+      },
+      comments: [{ id: "20001" }]
+    }
+
+    it("round-trips baseline JSON", async () => {
+      const parsed = await Effect.runPromise(parseSyncBaseline("100123.json", serializeSyncBaseline(baseline)))
+      expect(parsed).toEqual(baseline)
+    })
+
+    it("rejects corrupt baseline JSON", async () => {
+      const result = await runExit(parseSyncBaseline("100123.json", "{nope"))
+      expect(Exit.isFailure(result)).toBe(true)
+    })
+  })
+})

package/test/syncDocument.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "@effect/vitest"
+import { parseIssueDocument, serializeIssueDocument } from "../src/internal/sync/document.js"
+import type { IssueDocument } from "../src/internal/sync/types.js"
+import { SyncValidationError } from "../src/JiraCliError.js"
+
+const document: IssueDocument = {
+  frontMatter: {
+    issueId: "100123",
+    issueKey: "PROJ-123",
+    summary: "Fix checkout copy",
+    status: "In Progress",
+    issueType: "Story",
+    priority: "Medium",
+    assignee: { accountId: "abc123", displayName: "Alice Example" },
+    reporter: null,
+    labels: ["checkout", "copy"],
+    customFields: {
+      "Security & Compliance Impact": { id: "10423", value: "Low" }
+    }
+  },
+  description: "Editable description markdown.",
+  multilineCustomFields: {
+    "Release Notes": "Multiline release notes."
+  },
+  commentDrafts: [{ draftId: "draft-1", body: "Please review this." }],
+  acceptedComments: [{
+    id: "20001",
+    author: "Alice Example",
+    created: "2026-06-27",
+    body: "Existing Jira comment."
+  }],
+  attachments: [{ filename: "evidence.png", url: "https://example.atlassian.net/evidence.png" }],
+  localNotes: "Private local note."
+}
+
+describe("Issue Document parsing", () => {
+  it("round-trips a representative issue document", () => {
+    const serialized = serializeIssueDocument(document)
+    const parsed = parseIssueDocument("PROJ-123.md", serialized)
+    expect(parsed).toEqual(document)
+  })
+
+  it("preserves local notes body text", () => {
+    const serialized = serializeIssueDocument({
+      ...document,
+      localNotes: "line one\n\n- private bullet"
+    })
+    const parsed = parseIssueDocument("PROJ-123.md", serialized)
+    expect(parsed.localNotes).toBe("line one\n\n- private bullet")
+  })
+
+  it("rejects missing description section", () => {
+    const serialized = serializeIssueDocument(document).replace(
+      /## Description[\s\S]*?## Release Notes/,
+      "## Release Notes"
+    )
+    expect(() => parseIssueDocument("PROJ-123.md", serialized)).toThrow(SyncValidationError)
+  })
+
+  it("rejects duplicate sections", () => {
+    const serialized = `${serializeIssueDocument(document)}\n## Description\n\nagain\n`
+    expect(() => parseIssueDocument("PROJ-123.md", serialized)).toThrow(SyncValidationError)
+  })
+
+  it("rejects malformed comment draft markers", () => {
+    const serialized = serializeIssueDocument(document).replace("<!-- draftId: draft-1 -->", "<!-- draft: draft-1 -->")
+    expect(() => parseIssueDocument("PROJ-123.md", serialized)).toThrow(SyncValidationError)
+  })
+})

package/test/syncFieldValues.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "@effect/vitest"
+import {
+  canonicalizeFieldValue,
+  cascadingFieldValue,
+  completeListValue,
+  explicitClear,
+  fieldValuesEqual,
+  isCascadingFieldValue,
+  isCompleteListValue,
+  isExplicitClear,
+  isOptionFieldValue,
+  isUserFieldValue,
+  optionFieldValue,
+  userFieldValue
+} from "../src/internal/sync/fieldValues.js"
+import type { SyncFieldValue } from "../src/internal/sync/types.js"
+
+describe("Jira Markdown Sync field value helpers", () => {
+  it("represents explicit clear as a deliberate null field value", () => {
+    const value: SyncFieldValue = explicitClear
+
+    expect(value).toBeNull()
+    expect(isExplicitClear(value)).toBe(true)
+    expect(isExplicitClear("")).toBe(false)
+  })
+
+  it("represents user field values with display name and stable account id", () => {
+    const value = userFieldValue("account-123", "Jane Doe")
+
+    expect(value).toEqual({ accountId: "account-123", displayName: "Jane Doe" })
+    expect(isUserFieldValue(value)).toBe(true)
+    expect(isUserFieldValue({ displayName: "Jane Doe" })).toBe(false)
+  })
+
+  it("represents option field values with readable value and optional Jira option id", () => {
+    expect(optionFieldValue("High")).toEqual({ value: "High" })
+    expect(optionFieldValue("High", "10001")).toEqual({ id: "10001", value: "High" })
+    expect(isOptionFieldValue(optionFieldValue("High", "10001"))).toBe(true)
+    expect(isOptionFieldValue({ id: "10001" })).toBe(false)
+  })
+
+  it("represents cascading field values as parent and optional child options", () => {
+    const parentOnly = cascadingFieldValue(optionFieldValue("Security"))
+    const parentAndChild = cascadingFieldValue(
+      optionFieldValue("Security", "10"),
+      optionFieldValue("Customer Data", "11")
+    )
+
+    expect(parentOnly).toEqual({ parent: { value: "Security" } })
+    expect(parentAndChild).toEqual({
+      parent: { id: "10", value: "Security" },
+      child: { id: "11", value: "Customer Data" }
+    })
+    expect(isCascadingFieldValue(parentAndChild)).toBe(true)
+    expect(isCascadingFieldValue({ parent: { id: "10" } })).toBe(false)
+  })
+
+  it("represents list values as complete field values, not patches", () => {
+    const values = completeListValue(["backend", "api", "backend"])
+
+    expect(values).toEqual(["api", "backend", "backend"])
+    expect(isCompleteListValue(values)).toBe(true)
+    expect(isCompleteListValue([{ parent: optionFieldValue("A") }])).toBe(false)
+  })
+
+  it("applies canonical field order to unordered list-like values", () => {
+    const first = completeListValue([
+      optionFieldValue("Beta", "2"),
+      userFieldValue("account-2", "Zoe"),
+      optionFieldValue("Alpha", "1"),
+      userFieldValue("account-1", "Amy")
+    ])
+
+    expect(first).toEqual([
+      optionFieldValue("Alpha", "1"),
+      optionFieldValue("Beta", "2"),
+      userFieldValue("account-1", "Amy"),
+      userFieldValue("account-2", "Zoe")
+    ])
+  })
+
+  it("can preserve configured field order for ordered list-like values", () => {
+    const value = completeListValue(["third", "first", "second"], { ordered: true })
+
+    expect(value).toEqual(["third", "first", "second"])
+    expect(canonicalizeFieldValue(value, { ordered: true })).toEqual(["third", "first", "second"])
+  })
+
+  it("compares unordered complete list values by canonical value", () => {
+    const left: SyncFieldValue = ["frontend", "backend"]
+    const right: SyncFieldValue = ["backend", "frontend"]
+
+    expect(fieldValuesEqual(left, right)).toBe(true)
+    expect(fieldValuesEqual(left, right, { ordered: true })).toBe(false)
+  })
+
+  it("compares explicit clears distinctly from empty complete list values", () => {
+    expect(fieldValuesEqual(explicitClear, [])).toBe(false)
+    expect(fieldValuesEqual([], [])).toBe(true)
+  })
+})

package/vitest.config.integration.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "vitest/config"
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      "@knpkv/jira-api-client": new URL("../jira-api-client/src/index.ts", import.meta.url).pathname
+    }
+  },
+  test: {
+    include: ["test/integration.test.ts"],
+    globals: true,
+    environment: "node",
+    testTimeout: 120000,
+    hookTimeout: 60000,
+    teardownTimeout: 60000
+  }
+})

package/vitest.config.ts

@@ -8,6 +8,7 @@ export default defineConfig({
   },
   test: {
     include: ["test/**/*.test.ts"],
+    exclude: ["test/integration.test.ts"],
     globals: true,
     environment: "node",
     testTimeout: 30000,