@knpkv/jira-cli 0.1.1 → 1.0.0

package/src/bin.ts

@@ -2,61 +2,71 @@
 /**
  * CLI entry point — assembles commands, selects layer by subcommand, runs via `NodeRuntime`.
  *
- * `process.argv` is read once at the edge and passed to Effect — no globals in effectful code.
+ * Arguments are read from Effect's `Stdio` service at the runtime edge.
  *
  * @module
  */
-import { Command } from "@effect/cli"
-import { NodeRuntime } from "@effect/platform-node"
+import { NodeRuntime, NodeStdio } from "@effect/platform-node"
+import { makeInstallCommand } from "@knpkv/agent-skills"
+import * as Console from "effect/Console"
 import * as Effect from "effect/Effect"
-import * as Logger from "effect/Logger"
-import * as LogLevel from "effect/LogLevel"
+import * as Stdio from "effect/Stdio"
+import { Command } from "effect/unstable/cli"
 import pkg from "../package.json" with { type: "json" }
 import {
   AppLayer,
   authCommand,
   AuthOnlyLayer,
-  getCommand,
   getLayerType,
   handleError,
+  issueCommand,
   MinimalLayer,
-  searchCommand
+  versionCommand
 } from "./commands/index.js"
 
+const skillsInstall = makeInstallCommand({
+  description: "Install the Jira agent skill",
+  name: "install",
+  skills: ["jira"]
+})
+
+const skillsCommand = Command.make("skills", {}, () => Console.log("Usage: jira skills install")).pipe(
+  Command.withDescription("Local write agent skill commands"),
+  Command.withSubcommands([skillsInstall])
+)
+
 // === Main command ===
 const jira = Command.make("jira").pipe(
-  Command.withDescription("Fetch Jira tickets and export to markdown"),
+  Command.withDescription("Jira CLI commands"),
   Command.withSubcommands([
     authCommand,
-    getCommand,
-    searchCommand
+    issueCommand,
+    skillsCommand,
+    versionCommand
   ])
 )
 
 // === Run CLI ===
-const cli = Command.run(jira, {
-  name: pkg.name,
+const cli = Command.runWith(jira, {
   version: pkg.version
 })
 
-// Read argv once at the edge
-const argv = globalThis.process.argv
-
-const layerType = getLayerType(argv)
-const layer = layerType === "full"
-  ? AppLayer
-  : layerType === "auth"
-  ? AuthOnlyLayer
-  : MinimalLayer
-
-// Suppress verbose Effect logs
-const SilentLogger = Logger.replace(Logger.defaultLogger, Logger.none)
+const program = Effect.gen(function*() {
+  const stdio = yield* Stdio.Stdio
+  const args = yield* stdio.args
+  const layerType = getLayerType(args)
+  const layer = layerType === "full"
+    ? AppLayer
+    : layerType === "auth"
+    ? AuthOnlyLayer
+    : MinimalLayer
 
-const program = cli(argv).pipe(
-  Effect.provide(layer),
-  Effect.provide(SilentLogger),
-  Logger.withMinimumLogLevel(LogLevel.None),
-  Effect.catchAllCause((cause) => handleError(cause))
+  return yield* cli(args).pipe(
+    Effect.provide(layer)
+  )
+}).pipe(
+  Effect.provide(NodeStdio.layer),
+  Effect.catchCause((cause) => handleError(cause))
 )
 
 NodeRuntime.runMain(program)

package/src/commands/auth.ts

@@ -8,11 +8,11 @@
  *
  * @internal
  */
-import { Command, Options, Prompt } from "@effect/cli"
-import * as PlatformCommand from "@effect/platform/Command"
 import * as Console from "effect/Console"
 import * as Effect from "effect/Effect"
 import * as Option from "effect/Option"
+import { Command, Flag as Options, Prompt } from "effect/unstable/cli"
+import { openBrowser } from "../internal/openBrowser.js"
 import { JiraAuth } from "../JiraAuth.js"
 
 // === Auth create command ===
@@ -38,21 +38,15 @@ Creating OAuth app in Atlassian Developer Console...
 6. Run: jira auth configure --client-id <ID> --client-secret <SECRET>
 `)
     const url = "https://developer.atlassian.com/console/myapps/create-3lo-app/"
-    yield* PlatformCommand.make("open", url).pipe(
-      PlatformCommand.exitCode,
-      Effect.catchAll(() => PlatformCommand.make("xdg-open", url).pipe(PlatformCommand.exitCode)),
-      Effect.catchAll(() => PlatformCommand.make("cmd", "/c", "start", "", url).pipe(PlatformCommand.exitCode)),
-      Effect.asVoid,
-      Effect.catchAll(() => Effect.void)
-    )
+    yield* openBrowser(url).pipe(Effect.catch(() => Effect.void))
   })).pipe(Command.withDescription("Create OAuth app in Atlassian Developer Console"))
 
 // === Auth configure command ===
-const clientIdOption = Options.text("client-id").pipe(
+const clientIdOption = Options.string("client-id").pipe(
   Options.withDescription("OAuth client ID from Atlassian Developer Console"),
   Options.optional
 )
-const clientSecretOption = Options.text("client-secret").pipe(
+const clientSecretOption = Options.string("client-secret").pipe(
   Options.withDescription("OAuth client secret"),
   Options.optional
 )
@@ -77,7 +71,7 @@ const configureCommand = Command.make(
 ).pipe(Command.withDescription("Configure OAuth client credentials"))
 
 // === Auth login command ===
-const siteOption = Options.text("site").pipe(
+const siteOption = Options.string("site").pipe(
   Options.withDescription("Jira site URL to use (for accounts with multiple sites)"),
   Options.optional
 )

package/src/commands/get.ts

@@ -1,15 +1,15 @@
 /**
- * `jira get <key>` command — fetches a single issue and writes to Markdown.
+ * `jira issue get <key>` command — fetches a single issue and writes to Markdown.
  *
  * @internal
  */
-import { Args, Command, 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.text({ name: "key" }).pipe(
+const keyArg = Args.string("key").pipe(
   Args.withDescription("Issue key (e.g., PROJ-123)")
 )
 
@@ -39,4 +39,4 @@ export const getCommand = Command.make(
 
       yield* Console.log(`Done.`)
     })
-).pipe(Command.withDescription("Get a single Jira issue by key"))
+).pipe(Command.withDescription("Read-only: get a single Jira issue by key"))

package/src/commands/index.ts

@@ -6,6 +6,6 @@
 
 export { authCommand } from "./auth.js"
 export { handleError } from "./errorHandler.js"
-export { getCommand } from "./get.js"
+export { issueCommand } from "./issue.js"
 export { AppLayer, AuthOnlyLayer, getLayerType, MinimalLayer } from "./layers.js"
-export { searchCommand } from "./search.js"
+export { versionCommand } from "./version.js"

package/src/commands/issue.ts

@@ -0,0 +1,13 @@
+/**
+ * `jira issue` command namespace.
+ *
+ * @internal
+ */
+import { Command } from "effect/unstable/cli"
+import { getCommand } from "./get.js"
+import { searchCommand } from "./search.js"
+
+export const issueCommand = Command.make("issue").pipe(
+  Command.withDescription("Read-only Jira issue commands"),
+  Command.withSubcommands([getCommand, searchCommand])
+)

package/src/commands/layers.ts

@@ -3,61 +3,73 @@
  *
  * **Mental model**
  *
- * - **Lazy layer selection**: {@link getLayerType} inspects `process.argv[2]` to pick
+ * - **Lazy layer selection**: {@link getLayerType} inspects CLI arguments from `Stdio` to pick
  *   the smallest layer needed — `"minimal"` for help/version, `"auth"` for auth commands,
- *   `"full"` for search/get (which needs API client + issue service).
- * - **Dummy services**: Auth-only and minimal layers provide `Effect.dieMessage` stubs
+ *   `"full"` for issue/version reads and writes.
+ * - **Dummy services**: Auth-only and minimal layers provide dying stubs
  *   for unused services to satisfy the type system without initialization cost.
  *
  * @internal
  */
-import * as NodeContext from "@effect/platform-node/NodeContext"
 import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient"
+import * as NodeServices from "@effect/platform-node/NodeServices"
 import { JiraApiClient, JiraApiConfig } from "@knpkv/jira-api-client"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
 import { IssueService, layer as IssueServiceLayer, SiteUrl } from "../IssueService.js"
 import { JiraAuth, layer as JiraAuthLayer } from "../JiraAuth.js"
 import { layer as MarkdownWriterLayer, MarkdownWriter } from "../MarkdownWriter.js"
+import { layer as VersionServiceLayer, VersionService } from "../VersionService.js"
 
 // Dummy services for auth-only commands
 const DummyIssueServiceLayer = Layer.succeed(
   IssueService,
   IssueService.of({
-    getByKey: () => Effect.dieMessage("Not configured - run 'jira auth login' first"),
-    search: () => Effect.dieMessage("Not configured - run 'jira auth login' first"),
-    searchAll: () => Effect.dieMessage("Not configured - run 'jira auth login' first")
+    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"))
   })
 )
 
 const DummyMarkdownWriterLayer = Layer.succeed(
   MarkdownWriter,
   MarkdownWriter.of({
-    writeMulti: () => Effect.dieMessage("Not configured"),
-    writeSingle: () => Effect.dieMessage("Not configured")
+    writeMulti: () => Effect.die(new Error("Not configured")),
+    writeSingle: () => Effect.die(new Error("Not configured"))
+  })
+)
+
+const DummyVersionServiceLayer = Layer.succeed(
+  VersionService,
+  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")),
+    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"))
   })
 )
 
 const DummyJiraAuthLayer = Layer.succeed(
   JiraAuth,
   JiraAuth.of({
-    configure: () => Effect.dieMessage("Not configured"),
+    configure: () => Effect.die(new Error("Not configured")),
     isConfigured: () => Effect.succeed(false),
-    login: () => Effect.dieMessage("Not configured"),
-    logout: () => Effect.dieMessage("Not configured"),
-    getAccessToken: () => Effect.dieMessage("Not configured"),
-    getCloudId: () => Effect.dieMessage("Not configured"),
-    getSiteUrl: () => Effect.dieMessage("Not configured"),
+    login: () => Effect.die(new Error("Not configured")),
+    logout: () => Effect.die(new Error("Not configured")),
+    getAccessToken: () => Effect.die(new Error("Not configured")),
+    getCloudId: () => Effect.die(new Error("Not configured")),
+    getSiteUrl: () => Effect.die(new Error("Not configured")),
     getCurrentUser: () => Effect.succeed(null),
     isLoggedIn: () => Effect.succeed(false)
   })
 )
 
 // Auth layer with HTTP client
-const AuthLive = JiraAuthLayer.pipe(Layer.provide(NodeHttpClient.layer))
+const AuthLive = JiraAuthLayer.pipe(Layer.provide(Layer.mergeAll(NodeHttpClient.layerUndici, NodeServices.layer)))
 
 // Build Jira API config layer dynamically based on auth
-const JiraConfigLive = Layer.unwrapEffect(
+const JiraConfigLive = Layer.unwrap(
   Effect.gen(function*() {
     const auth = yield* JiraAuth
     const accessToken = yield* auth.getAccessToken()
@@ -80,7 +92,7 @@ const JiraClientLive = JiraApiClient.layer.pipe(
 )
 
 // Build SiteUrl layer from auth
-const SiteUrlLive = Layer.unwrapEffect(
+const SiteUrlLive = Layer.unwrap(
   Effect.gen(function*() {
     const auth = yield* JiraAuth
     const siteUrl = yield* auth.getSiteUrl()
@@ -95,11 +107,12 @@ const SiteUrlLive = Layer.unwrapEffect(
  */
 export const AppLayer = MarkdownWriterLayer.pipe(
   Layer.provideMerge(IssueServiceLayer),
+  Layer.provideMerge(VersionServiceLayer),
   Layer.provideMerge(SiteUrlLive),
   Layer.provideMerge(JiraClientLive),
   Layer.provideMerge(AuthLive),
-  Layer.provideMerge(NodeHttpClient.layer),
-  Layer.provideMerge(NodeContext.layer)
+  Layer.provideMerge(NodeHttpClient.layerUndici),
+  Layer.provideMerge(NodeServices.layer)
 )
 
 /**
@@ -109,9 +122,10 @@ export const AppLayer = MarkdownWriterLayer.pipe(
  */
 export const AuthOnlyLayer = DummyIssueServiceLayer.pipe(
   Layer.provideMerge(DummyMarkdownWriterLayer),
+  Layer.provideMerge(DummyVersionServiceLayer),
   Layer.provideMerge(AuthLive),
-  Layer.provideMerge(NodeHttpClient.layer),
-  Layer.provideMerge(NodeContext.layer)
+  Layer.provideMerge(NodeHttpClient.layerUndici),
+  Layer.provideMerge(NodeServices.layer)
 )
 
 /**
@@ -121,8 +135,9 @@ export const AuthOnlyLayer = DummyIssueServiceLayer.pipe(
  */
 export const MinimalLayer = DummyIssueServiceLayer.pipe(
   Layer.provideMerge(DummyMarkdownWriterLayer),
+  Layer.provideMerge(DummyVersionServiceLayer),
   Layer.provideMerge(DummyJiraAuthLayer),
-  Layer.provideMerge(NodeContext.layer)
+  Layer.provideMerge(NodeServices.layer)
 )
 
 /**
@@ -130,12 +145,15 @@ export const MinimalLayer = DummyIssueServiceLayer.pipe(
  *
  * @category Utilities
  */
-export const getLayerType = (argv: ReadonlyArray<string>): "full" | "auth" | "minimal" => {
-  const cmd = argv[2]
+export const getLayerType = (args: ReadonlyArray<string>): "full" | "auth" | "minimal" => {
+  const cmd = args[0]
+  if (args.includes("--help") || args.includes("-h")) {
+    return "minimal"
+  }
   if (cmd === "auth") {
     return "auth"
   }
-  if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "--version") {
+  if (!cmd || cmd === "skills" || cmd === "--help" || cmd === "-h" || cmd === "--version") {
     return "minimal"
   }
   return "full"

package/src/commands/search.ts

@@ -1,29 +1,29 @@
 /**
- * `jira search` command — JQL search with multi/single Markdown output.
+ * `jira issue search` command — JQL search with multi/single Markdown output.
  *
  * @internal
  */
-import { Args, Command, 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.text({ name: "jql" }).pipe(
+const jqlArg = Args.string("jql").pipe(
   Args.withDescription("JQL query to search for issues"),
   Args.optional
 )
 
-const byVersionOption = Options.text("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.text("project").pipe(
+const projectOption = Options.string("project").pipe(
   Options.withAlias("p"),
   Options.withDescription("Filter by project key"),
   Options.optional
@@ -74,8 +74,8 @@ export const searchCommand = Command.make(
         query = jql.value
       } else {
         yield* Console.log("Error: Either a JQL query or --by-version must be provided.")
-        yield* Console.log("Usage: jira search <jql>")
-        yield* Console.log("       jira search --by-version <version>")
+        yield* Console.log("Usage: jira issue search <jql>")
+        yield* Console.log("       jira issue search --by-version <version>")
         return
       }
 
@@ -99,4 +99,4 @@ export const searchCommand = Command.make(
         yield* Console.log(`Exported ${issues.length} file(s) to ${outputDir}/`)
       }
     })
-).pipe(Command.withDescription("Search Jira issues and export to markdown"))
+).pipe(Command.withDescription("Read-only: search Jira issues and export to markdown"))

package/src/commands/version.ts

@@ -0,0 +1,267 @@
+/**
+ * `jira version` command — list / get Jira project versions (releases) with
+ * Driver, Contributors and Approver fields resolved to display names, plus
+ * mutations: edit the description and manage "Related work" links (the
+ * Confluence pages surfaced on a release report).
+ *
+ * @internal
+ */
+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"
+
+/**
+ * Return a copy of `version` with every resolved {@link Person.emailAddress}
+ * (PII) set to null — covering driver, contributors, approvers[].person and
+ * tickets[].assignee. Used to keep emails out of `--json` output unless the
+ * caller opts in with `--emails`.
+ */
+export const stripEmails = (version: Version): Version => {
+  const stripPerson = <P extends Person>(person: P): P => ({ ...person, emailAddress: null })
+  return {
+    ...version,
+    driver: version.driver ? stripPerson(version.driver) : null,
+    contributors: version.contributors.map(stripPerson),
+    approvers: version.approvers.map((a) => ({ ...a, person: stripPerson(a.person) })),
+    tickets: version.tickets.map((t) => ({
+      ...t,
+      assignee: t.assignee ? stripPerson(t.assignee) : null
+    }))
+  }
+}
+
+/**
+ * Jira version ids are numeric (e.g. `10042`). Passing a name/key 404s with an
+ * opaque error, so validate early and emit a hint pointing at `version list`.
+ */
+const ensureNumericId = (id: string): Effect.Effect<void, JiraApiError> =>
+  /^\d+$/.test(id)
+    ? Effect.void
+    : Effect.fail(
+      new JiraApiError({
+        message: `Invalid version id "${id}". The version id is numeric (e.g. 10042); ` +
+          `use 'jira version list --project <KEY>' to find it.`
+      })
+    )
+
+const projectOption = Options.string("project").pipe(
+  Options.withAlias("p"),
+  Options.withDescription("Jira project key (e.g. RPS)")
+)
+const releasedOption = Options.boolean("released").pipe(
+  Options.withDescription("Only list released versions"),
+  Options.withDefault(false)
+)
+const unreleasedOption = Options.boolean("unreleased").pipe(
+  Options.withDescription("Only list unreleased versions"),
+  Options.withDefault(false)
+)
+const jsonOption = Options.boolean("json").pipe(
+  Options.withDescription("Output as JSON"),
+  Options.withDefault(false)
+)
+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(
+  Options.withDescription(
+    "Custom field display name to include on each ticket (repeatable, e.g. " +
+      "--custom-field \"Security & Compliance Impact\"). Values are exposed in " +
+      "ticket.customFields[<name>]."
+  ),
+  Options.atLeast(0)
+)
+const maxOption = Options.integer("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 listCommand = Command.make("list", {
+  project: projectOption,
+  released: releasedOption,
+  unreleased: unreleasedOption,
+  customFields: customFieldOption,
+  max: maxOption,
+  json: jsonOption,
+  emails: emailsOption
+}, ({ 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)."
+        })
+      )
+    }
+    const service = yield* VersionService
+    const versions = yield* service.listProjectVersions(project, {
+      released,
+      unreleased,
+      ...(Option.isSome(max) ? { maxResults: max.value } : {}),
+      customFieldNames: customFields
+    })
+    if (json) {
+      const output = emails ? versions : versions.map(stripEmails)
+      yield* Console.log(JSON.stringify(output, null, 2))
+      return
+    }
+    const sep = "  "
+    yield* Console.log(["id", "name", "released", "releaseDate", "driver", "contributors", "approvers"].join(sep))
+    for (const v of versions) {
+      yield* Console.log([
+        v.id,
+        v.name,
+        String(v.released),
+        v.releaseDate ?? "-",
+        v.driver?.displayName ?? "-",
+        v.contributors.map((c) => c.displayName).join("|") || "-",
+        v.approvers.map((a) => `${a.person.displayName}:${a.status}`).join("|") || "-"
+      ].join(sep))
+    }
+  })).pipe(Command.withDescription("Read-only: list versions for a Jira project"))
+
+/** Cap on the number of ticket keys listed in the human `get` output. */
+const TICKET_KEYS_LIMIT = 20
+
+const getCommand = Command.make(
+  "get",
+  { id: idArg, json: jsonOption, emails: emailsOption },
+  ({ emails, id, json }) =>
+    Effect.gen(function*() {
+      yield* ensureNumericId(id)
+      const service = yield* VersionService
+      const version = yield* service.getVersion(id)
+      if (json) {
+        const output = emails ? version : stripEmails(version)
+        yield* Console.log(JSON.stringify(output, null, 2))
+        return
+      }
+      yield* Console.log(`# ${version.name} (${version.id})`)
+      yield* Console.log(`released: ${version.released}`)
+      yield* Console.log(`releaseDate: ${version.releaseDate ?? "-"}`)
+      yield* Console.log(`driver: ${version.driver?.displayName ?? "-"}`)
+      yield* Console.log(`contributors: ${version.contributors.map((c) => c.displayName).join(", ") || "-"}`)
+      yield* Console.log(
+        `approvers: ${version.approvers.map((a) => `${a.person.displayName}:${a.status}`).join(", ") || "-"}`
+      )
+      yield* Console.log(`tickets (${version.tickets.length}): ${formatTicketKeys(version.tickets)}`)
+    })
+).pipe(Command.withDescription("Read-only: get a single Jira version"))
+
+/**
+ * Render a version's ticket keys for the human `get`: the first
+ * {@link TICKET_KEYS_LIMIT} keys, with a `(+M more)` suffix when truncated, or
+ * `-` when there are none.
+ */
+const formatTicketKeys = (tickets: Version["tickets"]): string => {
+  if (tickets.length === 0) return "-"
+  const keys = tickets.map((t) => t.key)
+  const shown = keys.slice(0, TICKET_KEYS_LIMIT).join(", ")
+  const remaining = keys.length - TICKET_KEYS_LIMIT
+  return remaining > 0 ? `${shown} (+${remaining} more)` : shown
+}
+
+const descriptionOption = Options.string("description").pipe(
+  Options.withAlias("d"),
+  Options.withDescription("New version description")
+)
+
+const updateCommand = Command.make("update", { id: idArg, description: descriptionOption, json: jsonOption }, ({
+  description,
+  id,
+  json
+}) =>
+  Effect.gen(function*() {
+    yield* ensureNumericId(id)
+    const service = yield* VersionService
+    const version = yield* service.updateVersion(id, { description })
+    if (json) {
+      yield* Console.log(JSON.stringify(version, null, 2))
+      return
+    }
+    yield* Console.log(`Updated version ${version.name} (${version.id})`)
+    yield* Console.log(`description: ${version.description ?? "-"}`)
+  })).pipe(
+    Command.withDescription("Remote write: update a version's description (requires manage:jira-project scope)")
+  )
+
+// === related-work ===
+
+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(
+  Options.withAlias("u"),
+  Options.withDescription("Related-work link URL (e.g. a Confluence page)")
+)
+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")
+)
+
+const relatedWorkListCommand = Command.make(
+  "list",
+  { id: idArg, json: jsonOption },
+  ({ id, json }) =>
+    Effect.gen(function*() {
+      yield* ensureNumericId(id)
+      const service = yield* VersionService
+      const items = yield* service.listRelatedWork(id)
+      if (json) {
+        yield* Console.log(JSON.stringify(items, null, 2))
+        return
+      }
+      if (items.length === 0) {
+        yield* Console.log("(no related work)")
+        return
+      }
+      const sep = "  "
+      yield* Console.log(["category", "title", "url"].join(sep))
+      for (const w of items) {
+        yield* Console.log([w.category || "-", w.title ?? "-", w.url ?? "-"].join(sep))
+      }
+    })
+).pipe(Command.withDescription("Read-only: list a version's related-work links"))
+
+const relatedWorkAddCommand = Command.make("add", {
+  id: idArg,
+  title: titleOption,
+  url: urlOption,
+  category: categoryOption,
+  json: jsonOption
+}, ({ category, id, json, title, url }) =>
+  Effect.gen(function*() {
+    yield* ensureNumericId(id)
+    const service = yield* VersionService
+    const created = yield* service.addRelatedWork(id, { title, category, url })
+    if (json) {
+      yield* Console.log(JSON.stringify(created, null, 2))
+      return
+    }
+    yield* Console.log(`Attached "${created.title ?? title}" (${created.category}) to version ${id}`)
+    yield* Console.log(`url: ${created.url ?? url}`)
+  })).pipe(
+    Command.withDescription(
+      "Remote write: attach a related-work link (e.g. a Confluence page) to a version (requires manage:jira-project scope)"
+    )
+  )
+
+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])
+)
+
+export const versionCommand = Command.make("version").pipe(
+  Command.withDescription("Jira version commands"),
+  Command.withSubcommands([listCommand, getCommand, updateCommand, relatedWorkCommand])
+)