@knpkv/jira-cli 1.2.3 → 1.4.0

package/src/commands/edit.ts

@@ -0,0 +1,88 @@
+/**
+ * `jira issue edit <key>` command — edit an issue's list-valued fields
+ * (fixVersions, labels).
+ *
+ * Incremental flags (`--add-*`, `--remove-*`) are the ones to reach for: both
+ * fields are sets, so the replacing form silently drops anything not listed.
+ *
+ * @internal
+ */
+import { Argument as Args, Command, Flag as Options } from "effect/cli"
+import * as Console from "effect/Console"
+import * as Effect from "effect/Effect"
+import { IssueService } from "../IssueService.js"
+
+const keyArg = Args.String("key").pipe(
+  Args.withDescription("Issue key (e.g., PROJ-123)")
+)
+
+const addFixVersionOption = Options.String("add-fix-version").pipe(
+  Options.withDescription("Add a fix version by name, keeping existing ones (repeatable)"),
+  Options.atLeast(0)
+)
+const removeFixVersionOption = Options.String("remove-fix-version").pipe(
+  Options.withDescription("Remove a fix version by name (repeatable)"),
+  Options.atLeast(0)
+)
+const fixVersionOption = Options.String("fix-version").pipe(
+  Options.withDescription(
+    "Replace the fix versions with exactly these names (repeatable). Drops any not listed — prefer --add-fix-version"
+  ),
+  Options.atLeast(0)
+)
+const addLabelOption = Options.String("add-label").pipe(
+  Options.withDescription("Add a label, keeping existing ones (repeatable)"),
+  Options.atLeast(0)
+)
+const removeLabelOption = Options.String("remove-label").pipe(
+  Options.withDescription("Remove a label (repeatable)"),
+  Options.atLeast(0)
+)
+const labelOption = Options.String("label").pipe(
+  Options.withDescription(
+    "Replace the labels with exactly these (repeatable). Drops any not listed — prefer --add-label"
+  ),
+  Options.atLeast(0)
+)
+const jsonOption = Options.Boolean("json").pipe(
+  Options.withDescription("Output as JSON"),
+  Options.withDefault(false)
+)
+
+export const editCommand = Command.make(
+  "edit",
+  {
+    key: keyArg,
+    addFixVersion: addFixVersionOption,
+    removeFixVersion: removeFixVersionOption,
+    fixVersion: fixVersionOption,
+    addLabel: addLabelOption,
+    removeLabel: removeLabelOption,
+    label: labelOption,
+    json: jsonOption
+  },
+  ({ addFixVersion, addLabel, fixVersion, json, key, label, removeFixVersion, removeLabel }) =>
+    Effect.gen(function*() {
+      const issueService = yield* IssueService
+      const issue = yield* issueService.edit(key, {
+        addFixVersions: addFixVersion,
+        removeFixVersions: removeFixVersion,
+        setFixVersions: fixVersion,
+        addLabels: addLabel,
+        removeLabels: removeLabel,
+        setLabels: label
+      })
+
+      if (json) {
+        yield* Console.log(JSON.stringify(issue, null, 2))
+        return
+      }
+      yield* Console.log(`Updated ${issue.key}`)
+      yield* Console.log(`fixVersions: ${issue.fixVersions.join(", ") || "-"}`)
+      yield* Console.log(`labels: ${issue.labels.join(", ") || "-"}`)
+    })
+).pipe(
+  Command.withDescription(
+    "Remote write: edit an issue's fix versions and labels (requires write:jira-work scope)"
+  )
+)

package/src/commands/get.ts

@@ -3,17 +3,17 @@
  *
  * @internal
  */
+import { Argument as Args, Command, Flag as Options } from "effect/cli"
 import * as Console from "effect/Console"
 import * as Effect from "effect/Effect"
-import { Argument as Args, Command, Flag as Options } from "effect/unstable/cli"
 import { IssueService } from "../IssueService.js"
 import { MarkdownWriter } from "../MarkdownWriter.js"
 
-const keyArg = Args.string("key").pipe(
+const keyArg = Args.String("key").pipe(
   Args.withDescription("Issue key (e.g., PROJ-123)")
 )
 
-const outputDirOption = Options.directory("output-dir").pipe(
+const outputDirOption = Options.Directory("output-dir").pipe(
   Options.withAlias("o"),
   Options.withDescription("Output directory for markdown file"),
   Options.withDefault("./jira-tickets")

package/src/commands/issue.ts

@@ -3,12 +3,13 @@
  *
  * @internal
  */
-import { Command } from "effect/unstable/cli"
+import { Command } from "effect/cli"
+import { editCommand } from "./edit.js"
 import { getCommand } from "./get.js"
 import { attachmentCommand } from "./issueAttachment.js"
 import { searchCommand } from "./search.js"
 
 export const issueCommand = Command.make("issue").pipe(
   Command.withDescription("Jira issue resource commands"),
-  Command.withSubcommands([attachmentCommand, getCommand, searchCommand])
+  Command.withSubcommands([attachmentCommand, getCommand, searchCommand, editCommand])
 )

package/src/commands/issueAttachment.ts

@@ -4,39 +4,42 @@
  * @internal
  */
 import { renderAttachmentMarkdown } from "@knpkv/atlassian-common/attachments"
+import { Argument as Args, Command, Flag as Options } from "effect/cli"
 import * as Console from "effect/Console"
 import * as Effect from "effect/Effect"
 import * as FileSystem from "effect/FileSystem"
 import * as Option from "effect/Option"
-import { Argument as Args, Command, Flag as Options } from "effect/unstable/cli"
 import { AttachmentService } from "../AttachmentService.js"
 import { insertJiraAttachmentReference } from "../internal/attachmentInsertion.js"
 import { JiraApiError, WriteError } from "../JiraCliError.js"
 
-const issueArg = Args.string("issue").pipe(
+const issueArg = Args.String("issue").pipe(
   Args.withDescription("Issue key or id, for example PROJ-123")
 )
 
-const fileArg = Args.string("file").pipe(
+const fileArg = Args.String("file").pipe(
   Args.withDescription("Local file to upload")
 )
 
-const documentOption = Options.file("document").pipe(
+const documentOption = Options.File("document").pipe(
   Options.withDescription("Local Jira Markdown document containing the attachment placeholder"),
   Options.optional
 )
 
-const noInsertOption = Options.boolean("no-insert").pipe(
-  Options.withDescription("Only upload and print the Attachment Reference")
+const noInsertOption = Options.Boolean("no-insert").pipe(
+  Options.withDescription("Only upload and print the Attachment Reference"),
+  Options.withDefault(false)
 )
 
-const dryRunOption = Options.boolean("dry-run").pipe(
+const dryRunOption = Options.Boolean("dry-run").pipe(
   Options.withAlias("n"),
-  Options.withDescription("Validate local insertion input without uploading")
+  Options.withDescription("Validate local insertion input without uploading"),
+  Options.withDefault(false)
 )
 
-const jsonOption = Options.boolean("json").pipe(
-  Options.withDescription("Write exactly one JSON value to stdout")
+const jsonOption = Options.Boolean("json").pipe(
+  Options.withDescription("Write exactly one JSON value to stdout"),
+  Options.withDefault(false)
 )
 
 const readDocument = (documentPath: string) =>
@@ -88,16 +91,16 @@ const uploadCommand = Command.make(
       if (documentInput !== null) {
         const matches = countPlaceholderMatches(documentInput.content, file)
         if (matches !== 1) {
-          return yield* Effect.fail(
-            new JiraApiError({ message: `Expected exactly one attachment placeholder for ${file}, found ${matches}` })
-          )
+          return yield* new JiraApiError({
+            message: `Expected exactly one attachment placeholder for ${file}, found ${matches}`
+          })
         }
       }
 
       if (dryRun) {
         const exists = yield* fileExists(file)
         if (!exists) {
-          return yield* Effect.fail(new JiraApiError({ message: `Attachment file does not exist: ${file}` }))
+          return yield* new JiraApiError({ message: `Attachment file does not exist: ${file}` })
         }
         const result = { dryRun: true, issue, file, insert: shouldInsert }
         yield* Console.log(json ? JSON.stringify(result) : `Dry run: ${file} can be uploaded to ${issue}`)
@@ -111,12 +114,10 @@ const uploadCommand = Command.make(
       if (documentInput !== null) {
         const result = insertJiraAttachmentReference(documentInput.content, file, attachment)
         if (result.replacements !== 1) {
-          return yield* Effect.fail(
-            new JiraApiError({
-              message:
-                `Uploaded attachment ${attachment.id}, but expected exactly one local placeholder for ${file}; found ${result.replacements}`
-            })
-          )
+          return yield* new JiraApiError({
+            message:
+              `Uploaded attachment ${attachment.id}, but expected exactly one local placeholder for ${file}; found ${result.replacements}`
+          })
         }
         yield* writeDocument(documentInput.path, result.content)
         inserted = true

package/src/commands/layers.ts

@@ -28,7 +28,8 @@ const DummyIssueServiceLayer = Layer.succeed(
   IssueService.of({
     getByKey: () => Effect.die(new Error("Not configured - run 'jira auth login' first")),
     search: () => Effect.die(new Error("Not configured - run 'jira auth login' first")),
-    searchAll: () => Effect.die(new Error("Not configured - run 'jira auth login' first"))
+    searchAll: () => Effect.die(new Error("Not configured - run 'jira auth login' first")),
+    edit: () => Effect.die(new Error("Not configured - run 'jira auth login' first"))
   })
 )
 
@@ -52,9 +53,11 @@ const DummyVersionServiceLayer = Layer.succeed(
   VersionService.of({
     listProjectVersions: () => Effect.die(new Error("Not configured - run 'jira auth login' first")),
     getVersion: () => Effect.die(new Error("Not configured - run 'jira auth login' first")),
+    createVersion: () => Effect.die(new Error("Not configured - run 'jira auth login' first")),
     updateVersion: () => Effect.die(new Error("Not configured - run 'jira auth login' first")),
     listRelatedWork: () => Effect.die(new Error("Not configured - run 'jira auth login' first")),
-    addRelatedWork: () => Effect.die(new Error("Not configured - run 'jira auth login' first"))
+    addRelatedWork: () => Effect.die(new Error("Not configured - run 'jira auth login' first")),
+    deleteRelatedWork: () => Effect.die(new Error("Not configured - run 'jira auth login' first"))
   })
 )
 

package/src/commands/search.ts

@@ -3,45 +3,45 @@
  *
  * @internal
  */
+import { Argument as Args, Command, Flag as Options } from "effect/cli"
 import * as Console from "effect/Console"
 import * as Effect from "effect/Effect"
 import * as Option from "effect/Option"
-import { Argument as Args, Command, Flag as Options } from "effect/unstable/cli"
 import { buildByVersionJql } from "../internal/jqlBuilder.js"
 import { IssueService } from "../IssueService.js"
 import { MarkdownWriter } from "../MarkdownWriter.js"
 
 // === Options ===
-const jqlArg = Args.string("jql").pipe(
+const jqlArg = Args.String("jql").pipe(
   Args.withDescription("JQL query to search for issues"),
   Args.optional
 )
 
-const byVersionOption = Options.string("by-version").pipe(
+const byVersionOption = Options.String("by-version").pipe(
   Options.withAlias("v"),
   Options.withDescription("Search by fix version (pre-defined query)"),
   Options.optional
 )
 
-const projectOption = Options.string("project").pipe(
+const projectOption = Options.String("project").pipe(
   Options.withAlias("p"),
   Options.withDescription("Filter by project key"),
   Options.optional
 )
 
-const outputDirOption = Options.directory("output-dir").pipe(
+const outputDirOption = Options.Directory("output-dir").pipe(
   Options.withAlias("o"),
   Options.withDescription("Output directory for markdown files"),
   Options.withDefault("./jira-tickets")
 )
 
-const formatOption = Options.choice("format", ["multi", "single"]).pipe(
+const formatOption = Options.Literals("format", ["multi", "single"]).pipe(
   Options.withAlias("f"),
   Options.withDescription("Output format: multi (one file per issue) or single (combined file)"),
   Options.withDefault("multi")
 )
 
-const maxResultsOption = Options.integer("max-results").pipe(
+const maxResultsOption = Options.Int("max-results").pipe(
   Options.withAlias("m"),
   Options.withDescription("Maximum number of results to fetch"),
   Options.withDefault(100)

package/src/commands/version.ts

@@ -6,13 +6,13 @@
  *
  * @internal
  */
+import { Argument as Args, Command, Flag as Options } from "effect/cli"
 import * as Console from "effect/Console"
 import * as Effect from "effect/Effect"
 import * as Option from "effect/Option"
-import { Argument as Args, Command, Flag as Options } from "effect/unstable/cli"
 import { JiraApiError } from "../JiraCliError.js"
 import type { Person, Version } from "../VersionService.js"
-import { VersionService } from "../VersionService.js"
+import { planRelatedWorkSync, VersionService } from "../VersionService.js"
 
 /**
  * Return a copy of `version` with every resolved {@link Person.emailAddress}
@@ -48,27 +48,27 @@ const ensureNumericId = (id: string): Effect.Effect<void, JiraApiError> =>
       })
     )
 
-const projectOption = Options.string("project").pipe(
+const projectOption = Options.String("project").pipe(
   Options.withAlias("p"),
   Options.withDescription("Jira project key (e.g. RPS)")
 )
-const releasedOption = Options.boolean("released").pipe(
+const releasedOption = Options.Boolean("released").pipe(
   Options.withDescription("Only list released versions"),
   Options.withDefault(false)
 )
-const unreleasedOption = Options.boolean("unreleased").pipe(
+const unreleasedOption = Options.Boolean("unreleased").pipe(
   Options.withDescription("Only list unreleased versions"),
   Options.withDefault(false)
 )
-const jsonOption = Options.boolean("json").pipe(
+const jsonOption = Options.Boolean("json").pipe(
   Options.withDescription("Output as JSON"),
   Options.withDefault(false)
 )
-const emailsOption = Options.boolean("emails").pipe(
+const emailsOption = Options.Boolean("emails").pipe(
   Options.withDescription("Include resolved user email addresses in --json output"),
   Options.withDefault(false)
 )
-const customFieldOption = Options.string("custom-field").pipe(
+const customFieldOption = Options.String("custom-field").pipe(
   Options.withDescription(
     "Custom field display name to include on each ticket (repeatable, e.g. " +
       "--custom-field \"Security & Compliance Impact\"). Values are exposed in " +
@@ -76,13 +76,13 @@ const customFieldOption = Options.string("custom-field").pipe(
   ),
   Options.atLeast(0)
 )
-const maxOption = Options.integer("max").pipe(
+const maxOption = Options.Int("max").pipe(
   Options.withAlias("m"),
   Options.withDescription("Maximum number of versions to fetch (default: all)"),
   Options.optional
 )
 
-const idArg = Args.string("id").pipe(Args.withDescription("Version id (numeric)"))
+const idArg = Args.String("id").pipe(Args.withDescription("Version id (numeric)"))
 
 const listCommand = Command.make("list", {
   project: projectOption,
@@ -95,17 +95,15 @@ const listCommand = Command.make("list", {
 }, ({ customFields, emails, json, max, project, released, unreleased }) =>
   Effect.gen(function*() {
     if (released && unreleased) {
-      return yield* Effect.fail(
-        new JiraApiError({
-          message: "--released and --unreleased are mutually exclusive; pass at most one (omit both to list all)."
-        })
-      )
+      return yield* new JiraApiError({
+        message: "--released and --unreleased are mutually exclusive; pass at most one (omit both to list all)."
+      })
     }
     const service = yield* VersionService
     const versions = yield* service.listProjectVersions(project, {
       released,
       unreleased,
-      ...(Option.isSome(max) ? { maxResults: max.value } : {}),
+      ...((Option.isSome(max)) && { maxResults: max.value }),
       customFieldNames: customFields
     })
     if (json) {
@@ -169,11 +167,85 @@ const formatTicketKeys = (tickets: Version["tickets"]): string => {
   return remaining > 0 ? `${shown} (+${remaining} more)` : shown
 }
 
-const descriptionOption = Options.string("description").pipe(
+const descriptionOption = Options.String("description").pipe(
   Options.withAlias("d"),
   Options.withDescription("New version description")
 )
 
+// === create ===
+
+/**
+ * Jira accepts version dates only as ISO 8601 `yyyy-mm-dd`. Anything else — a
+ * locale format, a timestamp — comes back as a generic 400 that does not name the
+ * offending field, so reject it locally where the message can.
+ */
+export const isIsoDate = (value: string): boolean => {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false
+  // Reject real-looking but non-existent dates (2026-02-30): round-tripping
+  // through Date is the cheapest calendar check.
+  const parsed = new Date(`${value}T00:00:00Z`)
+  return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value
+}
+
+const ensureIsoDate = (flag: string, value: string): Effect.Effect<void, JiraApiError> =>
+  isIsoDate(value) ? Effect.void : Effect.fail(
+    new JiraApiError({ message: `Invalid --${flag} "${value}". Expected an ISO 8601 date (yyyy-mm-dd).` })
+  )
+
+// No `-n` alias: it means `--dry-run` everywhere else in these CLIs, and both
+// `getLayerType` implementations route on `argv.includes("-n")`. Reusing it for
+// a value on a remote-write command is the wrong default.
+const nameOption = Options.String("name").pipe(
+  Options.withDescription("Version name (e.g. \"OOB 100\")")
+)
+const optionalDescriptionOption = Options.String("description").pipe(
+  Options.withAlias("d"),
+  Options.withDescription("Version description"),
+  Options.optional
+)
+const startDateOption = Options.String("start-date").pipe(
+  Options.withDescription("Start date, ISO 8601 (yyyy-mm-dd)"),
+  Options.optional
+)
+const releaseDateOption = Options.String("release-date").pipe(
+  Options.withDescription("Release date, ISO 8601 (yyyy-mm-dd)"),
+  Options.optional
+)
+
+const createCommand = Command.make("create", {
+  project: projectOption,
+  name: nameOption,
+  description: optionalDescriptionOption,
+  startDate: startDateOption,
+  releaseDate: releaseDateOption,
+  json: jsonOption
+}, ({ description, json, name, project, releaseDate, startDate }) =>
+  Effect.gen(function*() {
+    if (Option.isSome(startDate)) yield* ensureIsoDate("start-date", startDate.value)
+    if (Option.isSome(releaseDate)) yield* ensureIsoDate("release-date", releaseDate.value)
+
+    const service = yield* VersionService
+    const version = yield* service.createVersion({
+      projectKey: project,
+      name,
+      ...((Option.isSome(description)) && { description: description.value }),
+      ...((Option.isSome(startDate)) && { startDate: startDate.value }),
+      ...((Option.isSome(releaseDate)) && { releaseDate: releaseDate.value })
+    })
+    if (json) {
+      yield* Console.log(JSON.stringify(version, null, 2))
+      return
+    }
+    yield* Console.log(`Created version ${version.name} (${version.id}) on ${project}`)
+    yield* Console.log(`startDate: ${version.startDate ?? "-"}`)
+    yield* Console.log(`releaseDate: ${version.releaseDate ?? "-"}`)
+    yield* Console.log(`description: ${version.description ?? "-"}`)
+  })).pipe(
+    Command.withDescription(
+      "Remote write: create a new unreleased version on a project (requires manage:jira-project scope)"
+    )
+  )
+
 const updateCommand = Command.make("update", { id: idArg, description: descriptionOption, json: jsonOption }, ({
   description,
   id,
@@ -195,15 +267,15 @@ const updateCommand = Command.make("update", { id: idArg, description: descripti
 
 // === related-work ===
 
-const titleOption = Options.string("title").pipe(
+const titleOption = Options.String("title").pipe(
   Options.withAlias("t"),
   Options.withDescription("Related-work link title (e.g. \"Release notes\")")
 )
-const urlOption = Options.string("url").pipe(
+const urlOption = Options.String("url").pipe(
   Options.withAlias("u"),
   Options.withDescription("Related-work link URL (e.g. a Confluence page)")
 )
-const categoryOption = Options.string("category").pipe(
+const categoryOption = Options.String("category").pipe(
   Options.withAlias("c"),
   Options.withDescription("Related-work category (Jira groups by this; e.g. Communication, Testing, Design)"),
   Options.withDefault("Communication")
@@ -256,12 +328,93 @@ const relatedWorkAddCommand = Command.make("add", {
     )
   )
 
+const linkOption = Options.String("link").pipe(
+  Options.withAlias("l"),
+  Options.withDescription("Desired link as `title=url` (repeatable). Category comes from --category."),
+  Options.atLeast(0)
+)
+
+const pruneOption = Options.Boolean("prune").pipe(
+  Options.withDescription("Also remove links in the category that are not in the desired set"),
+  Options.withDefault(false)
+)
+
+/**
+ * Reconcile a version's related-work links against a desired set.
+ *
+ * Re-running a release scaffold should not pile up duplicate "Release notes"
+ * links, which is what repeated `add` calls produce. Matching is by URL, the
+ * only stable identity a link has — Jira assigns the id and the title is
+ * editable.
+ */
+const relatedWorkSyncCommand = Command.make("sync", {
+  id: idArg,
+  link: linkOption,
+  category: categoryOption,
+  prune: pruneOption,
+  json: jsonOption
+}, ({ category, id, json, link, prune }) =>
+  Effect.gen(function*() {
+    yield* ensureNumericId(id)
+
+    const desired: Array<{ readonly title: string; readonly url: string }> = []
+    for (const raw of link) {
+      const separator = raw.indexOf("=")
+      // Check the trimmed halves, not the separator position: `" =url"` and
+      // `"title= "` both put a non-empty span either side of the `=` and would
+      // otherwise reach Jira as a link with an empty title or url.
+      const title = separator < 0 ? "" : raw.slice(0, separator).trim()
+      const url = separator < 0 ? "" : raw.slice(separator + 1).trim()
+      if (separator < 0 || title.length === 0 || url.length === 0) {
+        return yield* new JiraApiError({ message: `Invalid --link ${JSON.stringify(raw)}. Expected title=url.` })
+      }
+      desired.push({ title, url })
+    }
+    if (desired.length === 0) {
+      return yield* new JiraApiError({ message: "Pass at least one --link title=url." })
+    }
+
+    const service = yield* VersionService
+    const existing = yield* service.listRelatedWork(id)
+    const plan = planRelatedWorkSync(existing, desired, { category, prune })
+
+    for (const item of plan.toAdd) {
+      yield* service.addRelatedWork(id, { title: item.title, category, url: item.url })
+    }
+    for (const item of plan.toRemove) {
+      yield* service.deleteRelatedWork(id, item.relatedWorkId)
+    }
+
+    const added = plan.toAdd.map((d) => d.url)
+    const removed = plan.toRemove.map((d) => d.url)
+    if (json) {
+      yield* Console.log(JSON.stringify({ added, kept: plan.kept, removed }, null, 2))
+      return
+    }
+    yield* Console.log(
+      `Version ${id} (${category}): ${added.length} added, ${plan.kept.length} unchanged, ${removed.length} removed`
+    )
+    for (const url of added) yield* Console.log(`  + ${url}`)
+    for (const url of removed) yield* Console.log(`  - ${url}`)
+  })).pipe(
+    // The help text is what a user reads before a remote write, so it has to
+    // say that pruning is opt-in: without --prune nothing is ever removed, and
+    // "reconcile to exactly the given set" reads as a promise that stale links
+    // were cleaned up.
+    Command.withDescription(
+      "Remote write: add any missing related-work links in a category, matched by URL (idempotent); " +
+        "pass --prune to also remove links that are not in the given set"
+    )
+  )
+
 const relatedWorkCommand = Command.make("related-work").pipe(
-  Command.withDescription("List or attach version related-work links (Confluence pages on the release report)"),
-  Command.withSubcommands([relatedWorkListCommand, relatedWorkAddCommand])
+  Command.withDescription(
+    "List, attach or reconcile version related-work links (Confluence pages on the release report)"
+  ),
+  Command.withSubcommands([relatedWorkListCommand, relatedWorkAddCommand, relatedWorkSyncCommand])
 )
 
 export const versionCommand = Command.make("version").pipe(
   Command.withDescription("Jira version commands"),
-  Command.withSubcommands([listCommand, getCommand, updateCommand, relatedWorkCommand])
+  Command.withSubcommands([listCommand, getCommand, createCommand, updateCommand, relatedWorkCommand])
 )

package/src/index.ts

@@ -6,7 +6,7 @@
 
 export {
   AttachmentService,
-  type AttachmentServiceShape,
+  type AttachmentServiceContract,
   layer as AttachmentServiceLayer,
   type UploadAttachmentInput
 } from "./AttachmentService.js"
@@ -15,7 +15,7 @@ export {
   type Comment,
   type Issue,
   IssueService,
-  type IssueServiceShape,
+  type IssueServiceContract,
   layer as IssueServiceLayer,
   type SearchOptions,
   type SearchResult,
@@ -29,4 +29,14 @@ export {
   type LoginOptions
 } from "./JiraAuth.js"
 export * from "./JiraCliError.js"
-export { layer as MarkdownWriterLayer, MarkdownWriter, type MarkdownWriterShape } from "./MarkdownWriter.js"
+export { layer as MarkdownWriterLayer, MarkdownWriter, type MarkdownWriterContract } from "./MarkdownWriter.js"
+export {
+  type DesiredRelatedWork,
+  layer as VersionServiceLayer,
+  planRelatedWorkSync,
+  type RelatedWork,
+  type RelatedWorkSyncPlan,
+  type Version,
+  VersionService,
+  type VersionServiceContract
+} from "./VersionService.js"

package/src/internal/NodeLayers.ts

@@ -13,5 +13,5 @@ import { makeHttpServerFactory } from "./oauthServer.js"
  * @category Layers
  */
 export const HttpServerFactoryLive = makeHttpServerFactory(
-  (port) => NodeHttpServer.layerServer(createServer, { port })
+  (options) => NodeHttpServer.layerServer(createServer, options)
 )

package/src/internal/frontmatter.ts

@@ -9,6 +9,7 @@
  * @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 type { Issue } from "../IssueService.js"
@@ -24,9 +25,9 @@ import type { Issue } from "../IssueService.js"
 const yamlEngine = {
   parse: (str: string): object => {
     const parsed = yaml.load(str)
-    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}
+    return parsed !== null && Predicate.isObjectOrArray(parsed) && !Array.isArray(parsed) ? parsed : {}
   },
-  stringify: (data: object): string => yaml.dump(data)
+  stringify: <Data extends object>(data: Data): string => yaml.dump(data)
 }
 
 /**