@knpkv/jira-cli 0.1.1

package/src/JiraAuth.ts

@@ -0,0 +1,476 @@
+/**
+ * OAuth2 authentication service for Jira CLI with token refresh and concurrency locking.
+ *
+ * **Mental model**
+ *
+ * - **Service pattern**: {@link JiraAuth} is a `Context.Tag` whose layer requires `HttpClient`
+ *   and `CommandExecutor`. All token storage operations are pre-bound to
+ *   `@knpkv/atlassian-common/config` with a `"jira-cli"` tool name.
+ * - **Refresh lock**: A `Ref<Option<Deferred>>` prevents concurrent token refreshes — the
+ *   first caller refreshes, others await the same Deferred.
+ * - **Browser-based login**: {@link JiraAuthService.login} starts a local callback server,
+ *   opens the browser, and awaits the OAuth code with a 5-minute timeout.
+ *
+ * **Common tasks**
+ *
+ * - Get a valid access token: `auth.getAccessToken()` (auto-refreshes if expired)
+ * - Full login flow: `auth.login()`
+ * - Check auth state: `auth.isLoggedIn()`
+ *
+ * @module
+ */
+import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem"
+import * as NodePath from "@effect/platform-node/NodePath"
+import * as Command from "@effect/platform/Command"
+import * as CommandExecutor from "@effect/platform/CommandExecutor"
+import type * as Error from "@effect/platform/Error"
+import * as HttpClient from "@effect/platform/HttpClient"
+import {
+  buildAuthUrl,
+  buildOAuthToken,
+  computeCodeChallenge,
+  exchangeCodeForTokens,
+  generateCodeVerifier,
+  generateUUID,
+  getAccessibleResources,
+  getUserInfo,
+  OAuthError,
+  refreshToken,
+  revokeToken
+} from "@knpkv/atlassian-common/auth"
+import {
+  deleteToken,
+  type FileSystemError,
+  type HomeDirectoryError,
+  HomeDirectoryLive,
+  isTokenExpired,
+  loadOAuthConfig,
+  loadToken,
+  type OAuthConfig,
+  type OAuthToken,
+  type OAuthUser,
+  saveOAuthConfig,
+  saveToken
+} from "@knpkv/atlassian-common/config"
+import * as Console from "effect/Console"
+import * as Context from "effect/Context"
+import * as Deferred from "effect/Deferred"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
+import * as Redacted from "effect/Redacted"
+import * as Ref from "effect/Ref"
+import { HttpServerFactoryLive } from "./internal/NodeLayers.js"
+import { startCallbackServer } from "./internal/oauthServer.js"
+import type { AuthMissingError } from "./JiraCliError.js"
+import { authMissing } from "./JiraCliError.js"
+
+/** Scopes for Jira CLI (includes write:jira-work for worklog) */
+const JIRA_CLI_SCOPES = [
+  "read:jira-work",
+  "write:jira-work",
+  "read:jira-user",
+  "read:me",
+  "offline_access"
+]
+
+const TOOL_NAME = "jira-cli"
+
+// Layer for token storage operations (FileSystem + Path + HomeDirectory)
+const TokenStorageLive = Layer.mergeAll(
+  NodeFileSystem.layer,
+  NodePath.layer,
+  HomeDirectoryLive
+)
+
+// 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 loadOAuthConfigOp = () => loadOAuthConfig(TOOL_NAME).pipe(Effect.provide(TokenStorageLive))
+const saveOAuthConfigOp = (config: OAuthConfig) =>
+  saveOAuthConfig(TOOL_NAME, config).pipe(Effect.provide(TokenStorageLive))
+
+/**
+ * Options for the login method.
+ *
+ * @category Types
+ */
+export interface LoginOptions {
+  /** Site URL to select (for accounts with multiple sites) */
+  readonly siteUrl?: string
+}
+
+/**
+ * Information about an accessible Jira site.
+ *
+ * @category Types
+ */
+export interface AccessibleSite {
+  readonly id: string
+  readonly name: string
+  readonly url: string
+}
+
+/**
+ * JiraAuth service interface.
+ *
+ * @category Services
+ */
+export interface JiraAuthService {
+  /** Configure OAuth client credentials */
+  readonly configure: (
+    config: OAuthConfig
+  ) => Effect.Effect<void, FileSystemError | HomeDirectoryError | Error.PlatformError>
+  /** Check if OAuth is configured */
+  readonly isConfigured: () => Effect.Effect<boolean, FileSystemError | HomeDirectoryError | Error.PlatformError>
+  /** Start OAuth login flow. Returns list of sites if multiple are available. */
+  readonly login: (
+    options?: LoginOptions
+  ) => Effect.Effect<
+    ReadonlyArray<AccessibleSite> | void,
+    OAuthError | FileSystemError | HomeDirectoryError | Error.PlatformError
+  >
+  /** Remove stored authentication */
+  readonly logout: () => Effect.Effect<void, OAuthError | FileSystemError | HomeDirectoryError | Error.PlatformError>
+  /** Get access token, refreshing if needed */
+  readonly getAccessToken: () => Effect.Effect<
+    Redacted.Redacted<string>,
+    AuthMissingError | OAuthError | FileSystemError | HomeDirectoryError | Error.PlatformError
+  >
+  /** Get cloud ID from stored token */
+  readonly getCloudId: () => Effect.Effect<
+    string,
+    AuthMissingError | FileSystemError | HomeDirectoryError | Error.PlatformError
+  >
+  /** Get site URL from stored token */
+  readonly getSiteUrl: () => Effect.Effect<
+    string,
+    AuthMissingError | FileSystemError | HomeDirectoryError | Error.PlatformError
+  >
+  /** Get current user info from stored token */
+  readonly getCurrentUser: () => Effect.Effect<
+    OAuthUser | null,
+    FileSystemError | HomeDirectoryError | Error.PlatformError
+  >
+  /** Check if user is logged in */
+  readonly isLoggedIn: () => Effect.Effect<boolean, FileSystemError | HomeDirectoryError | Error.PlatformError>
+}
+
+/**
+ * JiraAuth service tag.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect"
+ * import { JiraAuth } from "@knpkv/jira-cli/JiraAuth"
+ *
+ * Effect.gen(function* () {
+ *   const auth = yield* JiraAuth
+ *   const isLoggedIn = yield* auth.isLoggedIn()
+ *   if (!isLoggedIn) {
+ *     yield* auth.login()
+ *   }
+ * })
+ * ```
+ *
+ * @category Services
+ */
+export class JiraAuth extends Context.Tag("@knpkv/jira-cli/JiraAuth")<
+  JiraAuth,
+  JiraAuthService
+>() {}
+
+const make = Effect.gen(function*() {
+  const httpClient = yield* HttpClient.HttpClient
+  const commandExecutor = yield* CommandExecutor.CommandExecutor
+
+  // Ref to track ongoing refresh operation to prevent concurrent refreshes
+  const refreshLock = yield* Ref.make<
+    Option.Option<
+      Deferred.Deferred<OAuthToken, OAuthError | FileSystemError | HomeDirectoryError | Error.PlatformError>
+    >
+  >(
+    Option.none()
+  )
+
+  const openBrowserImpl = (url: string): Effect.Effect<void, OAuthError> =>
+    Command.make("open", url).pipe(
+      Command.exitCode,
+      Effect.catchAll(() => Command.make("xdg-open", url).pipe(Command.exitCode)),
+      Effect.catchAll(() => Command.make("cmd", "/c", "start", "", url).pipe(Command.exitCode)),
+      Effect.provide(Layer.succeed(CommandExecutor.CommandExecutor, commandExecutor)),
+      Effect.asVoid,
+      Effect.mapError((cause) => new OAuthError({ step: "authorize", cause }))
+    )
+
+  const getConfig = (): Effect.Effect<
+    OAuthConfig,
+    OAuthError | FileSystemError | HomeDirectoryError | Error.PlatformError
+  > =>
+    Effect.gen(function*() {
+      const config = yield* loadOAuthConfigOp()
+      if (config === null) {
+        return yield* Effect.fail(
+          new OAuthError({
+            step: "authorize",
+            cause: "OAuth not configured. Run 'jira auth configure' first."
+          })
+        )
+      }
+      return config
+    })
+
+  const refreshTokenImpl = (
+    token: OAuthToken,
+    config: OAuthConfig
+  ): Effect.Effect<OAuthToken, OAuthError | FileSystemError | HomeDirectoryError | Error.PlatformError> =>
+    Effect.gen(function*() {
+      const updated = yield* refreshToken(token, config).pipe(
+        Effect.provide(Layer.succeed(HttpClient.HttpClient, httpClient))
+      )
+      yield* saveTokenOp(updated)
+      return updated
+    })
+
+  const revokeTokenImpl = (
+    token: OAuthToken,
+    config: OAuthConfig
+  ): Effect.Effect<void, OAuthError> =>
+    revokeToken(token, config).pipe(
+      Effect.provide(Layer.succeed(HttpClient.HttpClient, httpClient))
+    )
+
+  const configure = (
+    config: OAuthConfig
+  ): Effect.Effect<void, FileSystemError | HomeDirectoryError | Error.PlatformError> => saveOAuthConfigOp(config)
+
+  const isConfigured = (): Effect.Effect<boolean, FileSystemError | HomeDirectoryError | Error.PlatformError> =>
+    Effect.gen(function*() {
+      const config = yield* loadOAuthConfigOp()
+      return config !== null
+    })
+
+  const login = (
+    options?: LoginOptions
+  ): Effect.Effect<
+    ReadonlyArray<AccessibleSite> | void,
+    OAuthError | FileSystemError | HomeDirectoryError | Error.PlatformError
+  > =>
+    Effect.gen(function*() {
+      const config = yield* getConfig()
+      const state = yield* generateUUID()
+      const codeVerifier = generateCodeVerifier()
+      const codeChallenge = yield* computeCodeChallenge(codeVerifier)
+
+      const { codePromise, port, shutdown } = yield* startCallbackServer(state).pipe(
+        Effect.provide(HttpServerFactoryLive)
+      )
+      const authUrl = buildAuthUrl({ clientId: config.clientId, state, port, scopes: JIRA_CLI_SCOPES, codeChallenge })
+
+      yield* Console.log(`Opening browser for Atlassian login (callback on port ${port})...`)
+      yield* Console.log(`If browser doesn't open, visit: ${authUrl}`)
+      yield* openBrowserImpl(authUrl)
+      yield* Console.log("Waiting for authorization (press Ctrl+C to cancel)...")
+
+      const code = yield* codePromise.pipe(
+        Effect.timeout("5 minutes"),
+        Effect.catchTag(
+          "TimeoutException",
+          () => Effect.fail(new OAuthError({ step: "authorize", cause: "Authorization timed out" }))
+        ),
+        Effect.ensuring(shutdown)
+      )
+
+      yield* Console.log("Exchanging code for tokens...")
+      const tokens = yield* exchangeCodeForTokens(code, config, { port, codeVerifier }).pipe(
+        Effect.provide(Layer.succeed(HttpClient.HttpClient, httpClient))
+      )
+
+      yield* Console.log("Fetching accessible sites...")
+      const sites = yield* getAccessibleResources(tokens.access_token).pipe(
+        Effect.provide(Layer.succeed(HttpClient.HttpClient, httpClient))
+      )
+
+      if (sites.length === 0) {
+        return yield* Effect.fail(
+          new OAuthError({
+            step: "authorize",
+            cause: "No Jira sites found for this account"
+          })
+        )
+      }
+
+      let site: (typeof sites)[number]
+
+      if (sites.length > 1) {
+        if (options?.siteUrl) {
+          const matched = sites.find((s) => s.url === options.siteUrl)
+          if (!matched) {
+            const available = sites.map((s) => `  - ${s.name}: ${s.url}`).join("\n")
+            return yield* Effect.fail(
+              new OAuthError({
+                step: "authorize",
+                cause: `Site '${options.siteUrl}' not found. Available sites:\n${available}`
+              })
+            )
+          }
+          site = matched
+        } else {
+          yield* Console.log("Multiple Jira sites found. Please select one:")
+          for (const s of sites) {
+            yield* Console.log(`  - ${s.name}: ${s.url}`)
+          }
+          yield* Console.log("\nRun 'jira auth login --site <url>' to select a site")
+          return sites.map((s) => ({ id: s.id, name: s.name, url: s.url }))
+        }
+      } else {
+        site = sites[0]!
+      }
+
+      yield* Console.log("Fetching user info...")
+      const user = yield* getUserInfo(tokens.access_token).pipe(
+        Effect.provide(Layer.succeed(HttpClient.HttpClient, httpClient))
+      )
+
+      const tokenData = buildOAuthToken(tokens, site, user)
+
+      yield* saveTokenOp(tokenData)
+      yield* Console.log(`Logged in as ${user.name} (${user.email})`)
+      return undefined
+    })
+
+  const logout = (): Effect.Effect<void, OAuthError | FileSystemError | HomeDirectoryError | Error.PlatformError> =>
+    Effect.gen(function*() {
+      const token = yield* loadTokenOp()
+      if (token === null) {
+        yield* Console.log("Not logged in")
+        return
+      }
+
+      const config = yield* loadOAuthConfigOp()
+      if (config !== null) {
+        yield* revokeTokenImpl(token, config).pipe(
+          Effect.tap(() => Effect.log("Token revoked with Atlassian")),
+          Effect.catchAll((error) => Effect.log(`Warning: Failed to revoke token: ${error.message}`))
+        )
+      }
+
+      yield* deleteTokenOp()
+    })
+
+  const getAccessToken = (): Effect.Effect<
+    Redacted.Redacted<string>,
+    AuthMissingError | OAuthError | FileSystemError | HomeDirectoryError | Error.PlatformError
+  > =>
+    Effect.gen(function*() {
+      const token = yield* loadTokenOp()
+      if (token === null) {
+        return yield* Effect.fail(authMissing())
+      }
+
+      if (!isTokenExpired(token)) {
+        return Redacted.make(token.access_token)
+      }
+
+      // Atomically check-then-set refresh lock to avoid TOCTOU race
+      const deferred = yield* Deferred.make<
+        OAuthToken,
+        OAuthError | FileSystemError | HomeDirectoryError | Error.PlatformError
+      >()
+      const existing = yield* Ref.modify(refreshLock, (current) =>
+        Option.isSome(current)
+          ? [current.value, current] as const
+          : [deferred, Option.some(deferred)] as const)
+
+      // Another fiber is already refreshing — just await its result
+      if (existing !== deferred) {
+        const refreshed = yield* Deferred.await(existing)
+        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())),
+        Effect.catchTag("OAuthError", (error) => {
+          if (error.step === "refresh") {
+            return Effect.gen(function*() {
+              yield* deleteTokenOp()
+              return yield* Effect.fail(
+                new OAuthError({
+                  step: "refresh",
+                  cause: "Refresh token expired. Please run 'jira auth login' to re-authenticate."
+                })
+              )
+            })
+          }
+          return Effect.fail(error)
+        })
+      )
+
+      return Redacted.make(result.access_token)
+    })
+
+  const getCloudId = (): Effect.Effect<
+    string,
+    AuthMissingError | FileSystemError | HomeDirectoryError | Error.PlatformError
+  > =>
+    Effect.gen(function*() {
+      const token = yield* loadTokenOp()
+      if (token === null) {
+        return yield* Effect.fail(authMissing())
+      }
+      return token.cloud_id
+    })
+
+  const getSiteUrl = (): Effect.Effect<
+    string,
+    AuthMissingError | FileSystemError | HomeDirectoryError | Error.PlatformError
+  > =>
+    Effect.gen(function*() {
+      const token = yield* loadTokenOp()
+      if (token === null) {
+        return yield* Effect.fail(authMissing())
+      }
+      return token.site_url
+    })
+
+  const getCurrentUser = (): Effect.Effect<
+    OAuthUser | null,
+    FileSystemError | HomeDirectoryError | Error.PlatformError
+  > =>
+    Effect.gen(function*() {
+      const token = yield* loadTokenOp()
+      return token?.user ?? null
+    })
+
+  const isLoggedIn = (): Effect.Effect<boolean, FileSystemError | HomeDirectoryError | Error.PlatformError> =>
+    Effect.gen(function*() {
+      const token = yield* loadTokenOp()
+      return token !== null
+    })
+
+  return JiraAuth.of({
+    configure,
+    isConfigured,
+    login,
+    logout,
+    getAccessToken,
+    getCloudId,
+    getSiteUrl,
+    getCurrentUser,
+    isLoggedIn
+  })
+})
+
+/**
+ * Layer for JiraAuth service.
+ *
+ * @category Layers
+ */
+export const layer = Layer.effect(JiraAuth, make)

package/src/JiraCliError.ts

@@ -0,0 +1,44 @@
+/**
+ * Tagged error types for Jira CLI operations.
+ *
+ * **Mental model**
+ *
+ * - **Three error tags**: {@link AuthMissingError} (not logged in),
+ *   {@link JiraApiError} (API call failed), {@link WriteError} (file I/O failed).
+ * - **Factory helper**: {@link authMissing} creates `AuthMissingError` with the default message.
+ *
+ * @module
+ */
+import * as Data from "effect/Data"
+
+/**
+ * Error when user is not authenticated.
+ *
+ * @category Errors
+ */
+export class AuthMissingError extends Data.TaggedError("AuthMissingError")<{
+  readonly message: string
+}> {}
+
+export const authMissing = () => new AuthMissingError({ message: "Not logged in. Run 'jira auth login' first." })
+
+/**
+ * Error during Jira API operations.
+ *
+ * @category Errors
+ */
+export class JiraApiError extends Data.TaggedError("JiraApiError")<{
+  readonly message: string
+  readonly cause?: unknown
+}> {}
+
+/**
+ * Error when writing files.
+ *
+ * @category Errors
+ */
+export class WriteError extends Data.TaggedError("WriteError")<{
+  readonly path: string
+  readonly message: string
+  readonly cause?: unknown
+}> {}

package/src/MarkdownWriter.ts

@@ -0,0 +1,112 @@
+/**
+ * File I/O service for writing Jira issues as Markdown with YAML frontmatter.
+ *
+ * **Mental model**
+ *
+ * - **Two output modes**: {@link MarkdownWriterShape.writeMulti} creates one `.md` per issue;
+ *   {@link MarkdownWriterShape.writeSingle} combines all into `jira-export.md`.
+ * - **Effect service**: Requires `FileSystem` and `Path` from `@effect/platform`.
+ *
+ * @module
+ */
+import * as FileSystem from "@effect/platform/FileSystem"
+import * as Path from "@effect/platform/Path"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import { buildCombinedMarkdown, serializeIssue } from "./internal/frontmatter.js"
+import type { Issue } from "./IssueService.js"
+import { WriteError } from "./JiraCliError.js"
+
+/**
+ * MarkdownWriter service interface.
+ *
+ * @category Services
+ */
+export interface MarkdownWriterShape {
+  /** Write each issue to a separate markdown file */
+  readonly writeMulti: (
+    issues: ReadonlyArray<Issue>,
+    outputDir: string
+  ) => Effect.Effect<void, WriteError>
+  /** Write all issues to a single markdown file */
+  readonly writeSingle: (
+    issues: ReadonlyArray<Issue>,
+    outputDir: string,
+    jql: string
+  ) => Effect.Effect<void, WriteError>
+}
+
+/**
+ * MarkdownWriter service tag.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect"
+ * import { MarkdownWriter } from "@knpkv/jira-cli/MarkdownWriter"
+ *
+ * Effect.gen(function* () {
+ *   const writer = yield* MarkdownWriter
+ *   yield* writer.writeMulti(issues, "./output")
+ * })
+ * ```
+ *
+ * @category Services
+ */
+export class MarkdownWriter extends Context.Tag("@knpkv/jira-cli/MarkdownWriter")<
+  MarkdownWriter,
+  MarkdownWriterShape
+>() {}
+
+const make = Effect.gen(function*() {
+  const fs = yield* FileSystem.FileSystem
+  const path = yield* Path.Path
+
+  const ensureDir = (dir: string): Effect.Effect<void, WriteError> =>
+    fs.makeDirectory(dir, { recursive: true }).pipe(
+      Effect.catchAll((cause) =>
+        Effect.fail(new WriteError({ path: dir, message: "Failed to create directory", cause }))
+      )
+    )
+
+  const writeFile = (filePath: string, content: string): Effect.Effect<void, WriteError> =>
+    fs.writeFileString(filePath, content).pipe(
+      Effect.catchAll((cause) =>
+        Effect.fail(new WriteError({ path: filePath, message: "Failed to write file", cause }))
+      )
+    )
+
+  const writeMulti: MarkdownWriterShape["writeMulti"] = (issues, outputDir) =>
+    Effect.gen(function*() {
+      yield* ensureDir(outputDir)
+
+      for (const issue of issues) {
+        const filename = `${issue.key}.md`
+        const filePath = path.join(outputDir, filename)
+        const content = serializeIssue(issue)
+        yield* writeFile(filePath, content)
+      }
+    })
+
+  const writeSingle: MarkdownWriterShape["writeSingle"] = (issues, outputDir, jql) =>
+    Effect.gen(function*() {
+      yield* ensureDir(outputDir)
+
+      const filename = "jira-export.md"
+      const filePath = path.join(outputDir, filename)
+      const content = buildCombinedMarkdown(issues, jql)
+      yield* writeFile(filePath, content)
+    })
+
+  return MarkdownWriter.of({ writeMulti, writeSingle })
+})
+
+/**
+ * Layer for MarkdownWriter service.
+ *
+ * @category Layers
+ */
+export const layer: Layer.Layer<MarkdownWriter, never, FileSystem.FileSystem | Path.Path> = Layer.effect(
+  MarkdownWriter,
+  make
+)

package/src/bin.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * 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.
+ *
+ * @module
+ */
+import { Command } from "@effect/cli"
+import { NodeRuntime } from "@effect/platform-node"
+import * as Effect from "effect/Effect"
+import * as Logger from "effect/Logger"
+import * as LogLevel from "effect/LogLevel"
+import pkg from "../package.json" with { type: "json" }
+import {
+  AppLayer,
+  authCommand,
+  AuthOnlyLayer,
+  getCommand,
+  getLayerType,
+  handleError,
+  MinimalLayer,
+  searchCommand
+} from "./commands/index.js"
+
+// === Main command ===
+const jira = Command.make("jira").pipe(
+  Command.withDescription("Fetch Jira tickets and export to markdown"),
+  Command.withSubcommands([
+    authCommand,
+    getCommand,
+    searchCommand
+  ])
+)
+
+// === Run CLI ===
+const cli = Command.run(jira, {
+  name: pkg.name,
+  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 = cli(argv).pipe(
+  Effect.provide(layer),
+  Effect.provide(SilentLogger),
+  Logger.withMinimumLogLevel(LogLevel.None),
+  Effect.catchAllCause((cause) => handleError(cause))
+)
+
+NodeRuntime.runMain(program)