@knpkv/jira-cli 0.3.0 → 1.1.0

package/src/JiraAuth.ts

@@ -35,18 +35,23 @@ import {
   revokeToken
 } from "@knpkv/atlassian-common/auth"
 import {
-  deleteToken,
+  type AuthProfile,
+  deleteActiveProfile,
+  deleteProfileBySelector,
   type FileSystemError,
   type HomeDirectoryError,
   HomeDirectoryLive,
   isTokenExpired,
+  loadActiveProfile,
+  loadActiveProfileToken,
   loadOAuthConfig,
-  loadToken,
+  loadProfiles,
   type OAuthConfig,
   type OAuthToken,
   type OAuthUser,
   saveOAuthConfig,
-  saveToken
+  saveProfileToken,
+  setActiveProfileBySelector
 } from "@knpkv/atlassian-common/config"
 import * as Console from "effect/Console"
 import * as Context from "effect/Context"
@@ -92,9 +97,16 @@ const TokenStorageLive = Layer.mergeAll(
 )
 
 // Wrap token storage operations with their required layers
-const loadTokenOp = () => loadToken(TOOL_NAME).pipe(Effect.provide(TokenStorageLive))
-const saveTokenOp = (token: OAuthToken) => saveToken(TOOL_NAME, token).pipe(Effect.provide(TokenStorageLive))
-const deleteTokenOp = () => deleteToken(TOOL_NAME).pipe(Effect.provide(TokenStorageLive))
+const loadTokenOp = () => loadActiveProfileToken(TOOL_NAME).pipe(Effect.provide(TokenStorageLive))
+const saveTokenOp = (token: OAuthToken) => saveProfileToken(TOOL_NAME, token).pipe(Effect.provide(TokenStorageLive))
+const deleteTokenOp = () => deleteActiveProfile(TOOL_NAME).pipe(Effect.provide(TokenStorageLive))
+const listProfilesOp = () =>
+  loadProfiles(TOOL_NAME).pipe(Effect.map((store) => store.profiles), Effect.provide(TokenStorageLive))
+const loadActiveProfileOp = () => loadActiveProfile(TOOL_NAME).pipe(Effect.provide(TokenStorageLive))
+const switchProfileOp = (selector: string) =>
+  setActiveProfileBySelector(TOOL_NAME, selector).pipe(Effect.provide(TokenStorageLive))
+const removeProfileOp = (selector: string) =>
+  deleteProfileBySelector(TOOL_NAME, selector).pipe(Effect.provide(TokenStorageLive))
 const loadOAuthConfigOp = () => loadOAuthConfig(TOOL_NAME).pipe(Effect.provide(TokenStorageLive))
 const saveOAuthConfigOp = (config: OAuthConfig) =>
   saveOAuthConfig(TOOL_NAME, config).pipe(Effect.provide(TokenStorageLive))
@@ -167,6 +179,24 @@ export interface JiraAuthService {
     OAuthUser | null,
     FileSystemError | HomeDirectoryError | PlatformError.PlatformError
   >
+  /** Get active auth profile */
+  readonly getActiveProfile: () => Effect.Effect<
+    AuthProfile | null,
+    FileSystemError | HomeDirectoryError | PlatformError.PlatformError
+  >
+  /** List stored auth profiles */
+  readonly listProfiles: () => Effect.Effect<
+    ReadonlyArray<AuthProfile>,
+    FileSystemError | HomeDirectoryError | PlatformError.PlatformError
+  >
+  /** Switch active profile by ID, name, site URL, cloud ID, or account ID */
+  readonly switchProfile: (
+    selector: string
+  ) => Effect.Effect<AuthProfile | null, FileSystemError | HomeDirectoryError | PlatformError.PlatformError>
+  /** Remove stored profile by ID, name, site URL, cloud ID, or account ID */
+  readonly removeProfile: (
+    selector: string
+  ) => Effect.Effect<AuthProfile | null, FileSystemError | HomeDirectoryError | PlatformError.PlatformError>
   /** Check if user is logged in */
   readonly isLoggedIn: () => Effect.Effect<boolean, FileSystemError | HomeDirectoryError | PlatformError.PlatformError>
 }
@@ -403,14 +433,11 @@ const make = Effect.gen(function*() {
         return Redacted.make(refreshed.access_token)
       }
 
-      // This fiber owns the refresh
-      const config = yield* getConfig()
-      yield* Console.log("Token expired, refreshing...")
-
-      const result = yield* refreshTokenImpl(token, config).pipe(
-        Effect.tap((refreshed) => Deferred.succeed(deferred, refreshed)),
-        Effect.tapError((error) => Deferred.fail(deferred, error)),
-        Effect.ensuring(Ref.set(refreshLock, Option.none())),
+      const refresh = Effect.gen(function*() {
+        const config = yield* getConfig()
+        yield* Console.log("Token expired, refreshing...")
+        return yield* refreshTokenImpl(token, config)
+      }).pipe(
         Effect.catchTag("OAuthError", (error) => {
           if (error.step === "refresh") {
             return Effect.gen(function*() {
@@ -427,6 +454,15 @@ const make = Effect.gen(function*() {
         })
       )
 
+      // This fiber owns the refresh. Complete the shared Deferred with the final
+      // transformed exit so waiters observe the same success or failure.
+      const exit = yield* refresh.pipe(
+        Effect.exit,
+        Effect.ensuring(Ref.set(refreshLock, Option.none()))
+      )
+      yield* Deferred.done(deferred, exit)
+      const result = yield* Deferred.await(deferred)
+
       return Redacted.make(result.access_token)
     })
 
@@ -463,6 +499,26 @@ const make = Effect.gen(function*() {
       return token?.user ?? null
     })
 
+  const getActiveProfile = (): Effect.Effect<
+    AuthProfile | null,
+    FileSystemError | HomeDirectoryError | PlatformError.PlatformError
+  > => loadActiveProfileOp()
+
+  const listProfiles = (): Effect.Effect<
+    ReadonlyArray<AuthProfile>,
+    FileSystemError | HomeDirectoryError | PlatformError.PlatformError
+  > => listProfilesOp()
+
+  const switchProfile = (
+    selector: string
+  ): Effect.Effect<AuthProfile | null, FileSystemError | HomeDirectoryError | PlatformError.PlatformError> =>
+    switchProfileOp(selector)
+
+  const removeProfile = (
+    selector: string
+  ): Effect.Effect<AuthProfile | null, FileSystemError | HomeDirectoryError | PlatformError.PlatformError> =>
+    removeProfileOp(selector)
+
   const isLoggedIn = (): Effect.Effect<boolean, FileSystemError | HomeDirectoryError | PlatformError.PlatformError> =>
     Effect.gen(function*() {
       const token = yield* loadTokenOp()
@@ -478,6 +534,10 @@ const make = Effect.gen(function*() {
     getCloudId,
     getSiteUrl,
     getCurrentUser,
+    getActiveProfile,
+    listProfiles,
+    switchProfile,
+    removeProfile,
     isLoggedIn
   })
 })

package/src/JiraCliError.ts

@@ -42,3 +42,27 @@ export class WriteError extends Data.TaggedError("WriteError")<{
   readonly message: string
   readonly cause?: unknown
 }> {}
+
+/**
+ * Error when reading or writing Jira Markdown Sync workspace state.
+ *
+ * @category Errors
+ */
+export class SyncWorkspaceError extends Data.TaggedError("SyncWorkspaceError")<{
+  readonly message: string
+  readonly path?: string | undefined
+  readonly cause?: unknown
+}> {}
+
+/**
+ * Error when local Jira Markdown Sync configuration or data fails validation.
+ *
+ * @category Errors
+ */
+export class SyncValidationError extends Data.TaggedError("SyncValidationError")<{
+  readonly message: string
+  readonly issueKey?: string | undefined
+  readonly field?: string | undefined
+  readonly path?: string | undefined
+  readonly cause?: unknown
+}> {}

package/src/SyncWorkspace.ts

@@ -0,0 +1,185 @@
+/**
+ * Local workspace I/O for Jira Markdown Sync.
+ *
+ * @module
+ */
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as FileSystem from "effect/FileSystem"
+import * as Layer from "effect/Layer"
+import * as Path from "effect/Path"
+import { parseSyncBaseline, serializeSyncBaseline } from "./internal/sync/baseline.js"
+import { makeDefaultWorkspaceConfig, parseWorkspaceConfig, serializeWorkspaceConfig } from "./internal/sync/config.js"
+import { makeEmptyManifest, parseSyncManifest, serializeSyncManifest } from "./internal/sync/manifest.js"
+import {
+  baselineFilePath,
+  conventionDocumentPath,
+  resolveWorkspacePaths,
+  type SyncWorkspacePaths
+} from "./internal/sync/paths.js"
+import type { SyncBaseline, SyncManifest, WorkspaceConfig } from "./internal/sync/types.js"
+import { SyncWorkspaceError } from "./JiraCliError.js"
+
+export interface InitWorkspaceInput {
+  readonly root: string
+  readonly siteUrl: string
+}
+
+export interface SyncWorkspaceShape {
+  readonly init: (input: InitWorkspaceInput) => Effect.Effect<SyncWorkspacePaths, SyncWorkspaceError>
+  readonly paths: (root: string, config?: Pick<WorkspaceConfig, "documentsDir">) => Effect.Effect<SyncWorkspacePaths>
+  readonly readConfig: (root: string) => Effect.Effect<WorkspaceConfig, SyncWorkspaceError>
+  readonly writeConfig: (root: string, config: WorkspaceConfig) => Effect.Effect<void, SyncWorkspaceError>
+  readonly readManifest: (root: string) => Effect.Effect<SyncManifest, SyncWorkspaceError>
+  readonly writeManifest: (root: string, manifest: SyncManifest) => Effect.Effect<void, SyncWorkspaceError>
+  readonly readBaseline: (root: string, issueId: string) => Effect.Effect<SyncBaseline, SyncWorkspaceError>
+  readonly writeBaseline: (
+    root: string,
+    baseline: SyncBaseline
+  ) => Effect.Effect<void, SyncWorkspaceError>
+  readonly conventionDocumentPath: (root: string, issueKey: string) => Effect.Effect<string, SyncWorkspaceError>
+}
+
+export class SyncWorkspace extends Context.Service<
+  SyncWorkspace,
+  SyncWorkspaceShape
+>()("@knpkv/jira-cli/SyncWorkspace") {}
+
+const mapWorkspaceError = (message: string, path?: string | undefined) => (cause: unknown) =>
+  new SyncWorkspaceError({ message, path, cause })
+
+const make = Effect.gen(function*() {
+  const fs = yield* FileSystem.FileSystem
+  const path = yield* Path.Path
+
+  const paths: SyncWorkspaceShape["paths"] = (root, config) => Effect.succeed(resolveWorkspacePaths(path, root, config))
+
+  const ensureDir = (dir: string): Effect.Effect<void, SyncWorkspaceError> =>
+    fs.makeDirectory(dir, { recursive: true }).pipe(
+      Effect.mapError(mapWorkspaceError("Failed to create sync workspace directory", dir)),
+      Effect.asVoid
+    )
+
+  const writeFile = (filePath: string, content: string): Effect.Effect<void, SyncWorkspaceError> =>
+    Effect.gen(function*() {
+      const dir = path.dirname(filePath)
+      yield* ensureDir(dir)
+      const tempPath = `${filePath}.tmp.${Date.now()}`
+      yield* fs.writeFileString(tempPath, content).pipe(
+        Effect.mapError(mapWorkspaceError("Failed to write sync workspace file", filePath))
+      )
+      yield* fs.rename(tempPath, filePath).pipe(
+        Effect.mapError(mapWorkspaceError("Failed to replace sync workspace file", filePath))
+      )
+    })
+
+  const readFile = (filePath: string): Effect.Effect<string, SyncWorkspaceError> =>
+    fs.readFileString(filePath).pipe(
+      Effect.mapError(mapWorkspaceError("Failed to read sync workspace file", filePath))
+    )
+
+  const init: SyncWorkspaceShape["init"] = ({ root, siteUrl }) =>
+    Effect.gen(function*() {
+      const config = makeDefaultWorkspaceConfig(siteUrl)
+      const workspacePaths = resolveWorkspacePaths(path, root, config)
+      yield* ensureDir(workspacePaths.documentsDir)
+      yield* ensureDir(workspacePaths.metadataDir)
+      yield* ensureDir(workspacePaths.baselinesDir)
+      yield* ensureDir(workspacePaths.historyDir)
+      yield* writeFile(workspacePaths.configFile, serializeWorkspaceConfig(config))
+      yield* writeFile(workspacePaths.manifestFile, serializeSyncManifest(makeEmptyManifest(siteUrl)))
+      return workspacePaths
+    })
+
+  const readConfig: SyncWorkspaceShape["readConfig"] = (root) =>
+    Effect.gen(function*() {
+      const workspacePaths = resolveWorkspacePaths(path, root)
+      const content = yield* readFile(workspacePaths.configFile)
+      return yield* parseWorkspaceConfig(workspacePaths.configFile, content).pipe(
+        Effect.mapError((cause) =>
+          new SyncWorkspaceError({
+            message: cause.message,
+            path: "path" in cause ? cause.path : workspacePaths.configFile,
+            cause
+          })
+        )
+      )
+    })
+
+  const writeConfig: SyncWorkspaceShape["writeConfig"] = (root, config) =>
+    Effect.gen(function*() {
+      const workspacePaths = resolveWorkspacePaths(path, root, config)
+      yield* ensureDir(workspacePaths.metadataDir)
+      yield* writeFile(workspacePaths.configFile, serializeWorkspaceConfig(config))
+    })
+
+  const readManifest: SyncWorkspaceShape["readManifest"] = (root) =>
+    Effect.gen(function*() {
+      const workspacePaths = resolveWorkspacePaths(path, root)
+      const content = yield* readFile(workspacePaths.manifestFile)
+      return yield* parseSyncManifest(workspacePaths.manifestFile, content).pipe(
+        Effect.mapError((cause) =>
+          new SyncWorkspaceError({
+            message: cause.message,
+            path: "path" in cause ? cause.path : workspacePaths.manifestFile,
+            cause
+          })
+        )
+      )
+    })
+
+  const writeManifest: SyncWorkspaceShape["writeManifest"] = (root, manifest) =>
+    Effect.gen(function*() {
+      const workspacePaths = resolveWorkspacePaths(path, root)
+      yield* ensureDir(workspacePaths.metadataDir)
+      yield* writeFile(workspacePaths.manifestFile, serializeSyncManifest(manifest))
+    })
+
+  const readBaseline: SyncWorkspaceShape["readBaseline"] = (root, issueId) =>
+    Effect.gen(function*() {
+      const workspacePaths = resolveWorkspacePaths(path, root)
+      const filePath = baselineFilePath(path, workspacePaths, issueId)
+      const content = yield* readFile(filePath)
+      return yield* parseSyncBaseline(filePath, content).pipe(
+        Effect.mapError((cause) =>
+          new SyncWorkspaceError({
+            message: cause.message,
+            path: "path" in cause ? cause.path : filePath,
+            cause
+          })
+        )
+      )
+    })
+
+  const writeBaseline: SyncWorkspaceShape["writeBaseline"] = (root, baseline) =>
+    Effect.gen(function*() {
+      const workspacePaths = resolveWorkspacePaths(path, root)
+      const filePath = baselineFilePath(path, workspacePaths, baseline.issueId)
+      yield* ensureDir(workspacePaths.baselinesDir)
+      yield* writeFile(filePath, serializeSyncBaseline(baseline))
+    })
+
+  const getConventionDocumentPath: SyncWorkspaceShape["conventionDocumentPath"] = (root, issueKey) =>
+    Effect.gen(function*() {
+      const config = yield* readConfig(root)
+      const workspacePaths = resolveWorkspacePaths(path, root, config)
+      return conventionDocumentPath(path, workspacePaths, issueKey)
+    })
+
+  return SyncWorkspace.of({
+    init,
+    paths,
+    readConfig,
+    writeConfig,
+    readManifest,
+    writeManifest,
+    readBaseline,
+    writeBaseline,
+    conventionDocumentPath: getConventionDocumentPath
+  })
+})
+
+export const layer: Layer.Layer<SyncWorkspace, never, FileSystem.FileSystem | Path.Path> = Layer.effect(
+  SyncWorkspace,
+  make
+)

package/src/bin.ts

@@ -17,11 +17,10 @@ import {
   AppLayer,
   authCommand,
   AuthOnlyLayer,
-  getCommand,
   getLayerType,
   handleError,
+  issueCommand,
   MinimalLayer,
-  searchCommand,
   versionCommand
 } from "./commands/index.js"
 
@@ -32,17 +31,16 @@ const skillsInstall = makeInstallCommand({
 })
 
 const skillsCommand = Command.make("skills", {}, () => Console.log("Usage: jira skills install")).pipe(
-  Command.withDescription("Agent skill commands"),
+  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
   ])

package/src/commands/auth.ts

@@ -11,7 +11,7 @@
 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 { Argument as Args, Command, Flag as Options, Prompt } from "effect/unstable/cli"
 import { openBrowser } from "../internal/openBrowser.js"
 import { JiraAuth } from "../JiraAuth.js"
 
@@ -97,14 +97,65 @@ const logoutCommand = Command.make("logout", {}, () =>
 const statusCommand = Command.make("status", {}, () =>
   Effect.gen(function*() {
     const auth = yield* JiraAuth
-    const user = yield* auth.getCurrentUser()
-    if (user) {
-      yield* Console.log(`Logged in as: ${user.name} (${user.email})`)
+    const profile = yield* auth.getActiveProfile()
+    if (profile) {
+      const user = profile.token.user
+      const account = user ? `${user.name} (${user.email})` : "unknown user"
+      yield* Console.log(`Active profile: ${profile.name}`)
+      yield* Console.log(`Account: ${account}`)
+      yield* Console.log(`Site: ${profile.token.site_url}`)
+      yield* Console.log(`Profile ID: ${profile.id}`)
     } else {
       yield* Console.log("Not logged in. Use 'jira auth login' to authenticate.")
     }
   })).pipe(Command.withDescription("Show authentication status"))
 
+// === Auth profiles command ===
+const profilesCommand = Command.make("profiles", {}, () =>
+  Effect.gen(function*() {
+    const auth = yield* JiraAuth
+    const [profiles, active] = yield* Effect.all([auth.listProfiles(), auth.getActiveProfile()])
+    if (profiles.length === 0) {
+      yield* Console.log("No auth profiles. Use 'jira auth login' to authenticate.")
+      return
+    }
+
+    for (const profile of profiles) {
+      const marker = active?.id === profile.id ? "*" : " "
+      yield* Console.log(`${marker} ${profile.id}`)
+      yield* Console.log(`    ${profile.name}`)
+      yield* Console.log(`    ${profile.token.site_url}`)
+    }
+  })).pipe(Command.withDescription("List stored auth profiles"))
+
+const profileArg = Args.string("profile").pipe(
+  Args.withDescription("Profile ID, name, site URL, cloud ID, or account ID")
+)
+
+// === Auth use command ===
+const useCommand = Command.make("use", { profile: profileArg }, ({ profile }) =>
+  Effect.gen(function*() {
+    const auth = yield* JiraAuth
+    const selected = yield* auth.switchProfile(profile)
+    if (!selected) {
+      yield* Console.log(`Profile not found: ${profile}`)
+      return
+    }
+    yield* Console.log(`Active profile: ${selected.name}`)
+  })).pipe(Command.withDescription("Switch active auth profile"))
+
+// === Auth remove command ===
+const removeCommand = Command.make("remove", { profile: profileArg }, ({ profile }) =>
+  Effect.gen(function*() {
+    const auth = yield* JiraAuth
+    const removed = yield* auth.removeProfile(profile)
+    if (!removed) {
+      yield* Console.log(`Profile not found: ${profile}`)
+      return
+    }
+    yield* Console.log(`Removed profile: ${removed.name}`)
+  })).pipe(Command.withDescription("Remove stored auth profile"))
+
 // === Auth command group ===
 export const authCommand = Command.make("auth").pipe(
   Command.withDescription("Manage OAuth authentication"),
@@ -113,6 +164,9 @@ export const authCommand = Command.make("auth").pipe(
     configureCommand,
     loginCommand,
     logoutCommand,
-    statusCommand
+    statusCommand,
+    profilesCommand,
+    useCommand,
+    removeCommand
   ])
 )

package/src/commands/get.ts

@@ -1,5 +1,5 @@
 /**
- * `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
  */
@@ -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,7 +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

@@ -5,7 +5,7 @@
  *
  * - **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).
+ *   `"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.
  *
@@ -61,6 +61,10 @@ const DummyJiraAuthLayer = Layer.succeed(
     getCloudId: () => Effect.die(new Error("Not configured")),
     getSiteUrl: () => Effect.die(new Error("Not configured")),
     getCurrentUser: () => Effect.succeed(null),
+    getActiveProfile: () => Effect.succeed(null),
+    listProfiles: () => Effect.succeed([]),
+    switchProfile: () => Effect.succeed(null),
+    removeProfile: () => Effect.succeed(null),
     isLoggedIn: () => Effect.succeed(false)
   })
 )
@@ -147,6 +151,9 @@ export const MinimalLayer = DummyIssueServiceLayer.pipe(
  */
 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"
   }

package/src/commands/search.ts

@@ -1,5 +1,5 @@
 /**
- * `jira search` command — JQL search with multi/single Markdown output.
+ * `jira issue search` command — JQL search with multi/single Markdown output.
  *
  * @internal
  */
@@ -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

@@ -1,5 +1,5 @@
 /**
- * `jira version` command — list / view Jira project versions (releases) with
+ * `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).
@@ -126,13 +126,13 @@ const listCommand = Command.make("list", {
         v.approvers.map((a) => `${a.person.displayName}:${a.status}`).join("|") || "-"
       ].join(sep))
     }
-  })).pipe(Command.withDescription("List versions for a Jira project"))
+  })).pipe(Command.withDescription("Read-only: list versions for a Jira project"))
 
-/** Cap on the number of ticket keys listed in the human `view` output. */
+/** Cap on the number of ticket keys listed in the human `get` output. */
 const TICKET_KEYS_LIMIT = 20
 
-const viewCommand = Command.make(
-  "view",
+const getCommand = Command.make(
+  "get",
   { id: idArg, json: jsonOption, emails: emailsOption },
   ({ emails, id, json }) =>
     Effect.gen(function*() {
@@ -154,10 +154,10 @@ const viewCommand = Command.make(
       )
       yield* Console.log(`tickets (${version.tickets.length}): ${formatTicketKeys(version.tickets)}`)
     })
-).pipe(Command.withDescription("Show a single Jira version"))
+).pipe(Command.withDescription("Read-only: get a single Jira version"))
 
 /**
- * Render a version's ticket keys for the human `view`: the first
+ * 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.
  */
@@ -174,7 +174,7 @@ const descriptionOption = Options.string("description").pipe(
   Options.withDescription("New version description")
 )
 
-const setCommand = Command.make("set", { id: idArg, description: descriptionOption, json: jsonOption }, ({
+const updateCommand = Command.make("update", { id: idArg, description: descriptionOption, json: jsonOption }, ({
   description,
   id,
   json
@@ -190,10 +190,10 @@ const setCommand = Command.make("set", { id: idArg, description: descriptionOpti
     yield* Console.log(`Updated version ${version.name} (${version.id})`)
     yield* Console.log(`description: ${version.description ?? "-"}`)
   })).pipe(
-    Command.withDescription("Update a version's description (requires manage:jira-project scope)")
+    Command.withDescription("Remote write: update a version's description (requires manage:jira-project scope)")
   )
 
-// === relatedwork ===
+// === related-work ===
 
 const titleOption = Options.string("title").pipe(
   Options.withAlias("t"),
@@ -231,7 +231,7 @@ const relatedWorkListCommand = Command.make(
         yield* Console.log([w.category || "-", w.title ?? "-", w.url ?? "-"].join(sep))
       }
     })
-).pipe(Command.withDescription("List a version's related-work links"))
+).pipe(Command.withDescription("Read-only: list a version's related-work links"))
 
 const relatedWorkAddCommand = Command.make("add", {
   id: idArg,
@@ -252,16 +252,16 @@ const relatedWorkAddCommand = Command.make("add", {
     yield* Console.log(`url: ${created.url ?? url}`)
   })).pipe(
     Command.withDescription(
-      "Attach a related-work link (e.g. a Confluence page) to a version (requires manage:jira-project scope)"
+      "Remote write: attach a related-work link (e.g. a Confluence page) to a version (requires manage:jira-project scope)"
     )
   )
 
-const relatedWorkCommand = Command.make("relatedwork").pipe(
+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("List, view, or edit Jira project versions (releases)"),
-  Command.withSubcommands([listCommand, viewCommand, setCommand, relatedWorkCommand])
+  Command.withDescription("Jira version commands"),
+  Command.withSubcommands([listCommand, getCommand, updateCommand, relatedWorkCommand])
 )