@knpkv/jira-cli 0.1.1

package/src/commands/auth.ts

@@ -0,0 +1,124 @@
+/**
+ * Auth subcommands: create, configure, login, logout, status.
+ *
+ * **Mental model**
+ *
+ * - Each command is a standalone `Command.make` that yields into `JiraAuth` service methods.
+ * - `create` opens the Atlassian Developer Console; `configure` prompts for client ID/secret.
+ *
+ * @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 { JiraAuth } from "../JiraAuth.js"
+
+// === Auth create command ===
+const createCommand = Command.make("create", {}, () =>
+  Effect.gen(function*() {
+    yield* Console.log(`
+Creating OAuth app in Atlassian Developer Console...
+
+1. Browser will open to create a new OAuth 2.0 (3LO) app
+2. Enter app name (e.g., "Jira CLI")
+3. After creation, go to "Permissions" and add:
+
+   Jira API:
+   - read:jira-work    Search and read issues, comments, attachments
+   - read:jira-user    Read user info for assignee/reporter fields
+
+   User Identity API:
+   - read:me           Get your account ID and email for auth
+
+4. Go to "Authorization" and set callback URL:
+   http://localhost:8585/callback
+5. Go to "Settings" and copy Client ID and Secret
+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)
+    )
+  })).pipe(Command.withDescription("Create OAuth app in Atlassian Developer Console"))
+
+// === Auth configure command ===
+const clientIdOption = Options.text("client-id").pipe(
+  Options.withDescription("OAuth client ID from Atlassian Developer Console"),
+  Options.optional
+)
+const clientSecretOption = Options.text("client-secret").pipe(
+  Options.withDescription("OAuth client secret"),
+  Options.optional
+)
+
+const configureCommand = Command.make(
+  "configure",
+  { clientId: clientIdOption, clientSecret: clientSecretOption },
+  ({ clientId, clientSecret }) =>
+    Effect.gen(function*() {
+      const auth = yield* JiraAuth
+
+      const rawClientId = Option.isSome(clientId)
+        ? clientId.value
+        : yield* Prompt.text({ message: "Enter OAuth client ID:" })
+      const rawClientSecret = Option.isSome(clientSecret)
+        ? clientSecret.value
+        : yield* Prompt.text({ message: "Enter OAuth client secret:" })
+
+      yield* auth.configure({ clientId: rawClientId, clientSecret: rawClientSecret })
+      yield* Console.log("OAuth configured. Run 'jira auth login' to authenticate.")
+    })
+).pipe(Command.withDescription("Configure OAuth client credentials"))
+
+// === Auth login command ===
+const siteOption = Options.text("site").pipe(
+  Options.withDescription("Jira site URL to use (for accounts with multiple sites)"),
+  Options.optional
+)
+
+const loginCommand = Command.make("login", { site: siteOption }, ({ site }) =>
+  Effect.gen(function*() {
+    const auth = yield* JiraAuth
+    const result = yield* auth.login(Option.isSome(site) ? { siteUrl: site.value } : undefined)
+    if (Array.isArray(result) && result.length > 0) {
+      yield* Console.log("\nRe-run with --site to select a specific site.")
+    }
+  })).pipe(Command.withDescription("Authenticate with Atlassian via OAuth"))
+
+// === Auth logout command ===
+const logoutCommand = Command.make("logout", {}, () =>
+  Effect.gen(function*() {
+    const auth = yield* JiraAuth
+    yield* auth.logout()
+    yield* Console.log("Logged out")
+  })).pipe(Command.withDescription("Remove stored authentication"))
+
+// === Auth status command ===
+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})`)
+    } else {
+      yield* Console.log("Not logged in. Use 'jira auth login' to authenticate.")
+    }
+  })).pipe(Command.withDescription("Show authentication status"))
+
+// === Auth command group ===
+export const authCommand = Command.make("auth").pipe(
+  Command.withDescription("Manage OAuth authentication"),
+  Command.withSubcommands([
+    createCommand,
+    configureCommand,
+    loginCommand,
+    logoutCommand,
+    statusCommand
+  ])
+)

package/src/commands/errorHandler.ts

@@ -0,0 +1,14 @@
+/**
+ * Effect-idiomatic error handler — uses Cause.pretty for structured failure output.
+ *
+ * @internal
+ */
+import * as Cause from "effect/Cause"
+import * as Console from "effect/Console"
+import type * as Effect from "effect/Effect"
+
+/**
+ * Handle errors from CLI execution.
+ * Logs the pretty-printed cause to stderr via Console.error.
+ */
+export const handleError = <E>(cause: Cause.Cause<E>): Effect.Effect<void> => Console.error(Cause.pretty(cause))

package/src/commands/get.ts

@@ -0,0 +1,42 @@
+/**
+ * `jira 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 { IssueService } from "../IssueService.js"
+import { MarkdownWriter } from "../MarkdownWriter.js"
+
+const keyArg = Args.text({ name: "key" }).pipe(
+  Args.withDescription("Issue key (e.g., PROJ-123)")
+)
+
+const outputDirOption = Options.directory("output-dir").pipe(
+  Options.withAlias("o"),
+  Options.withDescription("Output directory for markdown file"),
+  Options.withDefault("./jira-tickets")
+)
+
+export const getCommand = Command.make(
+  "get",
+  {
+    key: keyArg,
+    outputDir: outputDirOption
+  },
+  ({ key, outputDir }) =>
+    Effect.gen(function*() {
+      const issueService = yield* IssueService
+      const writer = yield* MarkdownWriter
+
+      yield* Console.log(`Fetching ${key}...`)
+
+      const issue = yield* issueService.getByKey(key)
+
+      yield* Console.log(`Writing to ${outputDir}/${key}.md...`)
+      yield* writer.writeMulti([issue], outputDir)
+
+      yield* Console.log(`Done.`)
+    })
+).pipe(Command.withDescription("Get a single Jira issue by key"))

package/src/commands/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Barrel export for CLI commands and layer definitions.
+ *
+ * @module
+ */
+
+export { authCommand } from "./auth.js"
+export { handleError } from "./errorHandler.js"
+export { getCommand } from "./get.js"
+export { AppLayer, AuthOnlyLayer, getLayerType, MinimalLayer } from "./layers.js"
+export { searchCommand } from "./search.js"

package/src/commands/layers.ts

@@ -0,0 +1,142 @@
+/**
+ * Layer composition for CLI commands with three tiers: full, auth-only, minimal.
+ *
+ * **Mental model**
+ *
+ * - **Lazy layer selection**: {@link getLayerType} inspects `process.argv[2]` 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
+ *   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 { 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"
+
+// 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")
+  })
+)
+
+const DummyMarkdownWriterLayer = Layer.succeed(
+  MarkdownWriter,
+  MarkdownWriter.of({
+    writeMulti: () => Effect.dieMessage("Not configured"),
+    writeSingle: () => Effect.dieMessage("Not configured")
+  })
+)
+
+const DummyJiraAuthLayer = Layer.succeed(
+  JiraAuth,
+  JiraAuth.of({
+    configure: () => Effect.dieMessage("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"),
+    getCurrentUser: () => Effect.succeed(null),
+    isLoggedIn: () => Effect.succeed(false)
+  })
+)
+
+// Auth layer with HTTP client
+const AuthLive = JiraAuthLayer.pipe(Layer.provide(NodeHttpClient.layer))
+
+// Build Jira API config layer dynamically based on auth
+const JiraConfigLive = Layer.unwrapEffect(
+  Effect.gen(function*() {
+    const auth = yield* JiraAuth
+    const accessToken = yield* auth.getAccessToken()
+    const cloudId = yield* auth.getCloudId()
+
+    return Layer.succeed(JiraApiConfig, {
+      baseUrl: "",
+      auth: {
+        type: "oauth2" as const,
+        accessToken,
+        cloudId
+      }
+    })
+  })
+)
+
+// Build Jira API client layer with config (no HttpClient needed — uses openapi-fetch)
+const JiraClientLive = JiraApiClient.layer.pipe(
+  Layer.provide(JiraConfigLive)
+)
+
+// Build SiteUrl layer from auth
+const SiteUrlLive = Layer.unwrapEffect(
+  Effect.gen(function*() {
+    const auth = yield* JiraAuth
+    const siteUrl = yield* auth.getSiteUrl()
+    return Layer.succeed(SiteUrl, siteUrl)
+  })
+)
+
+/**
+ * Full app layer with all services for search commands.
+ *
+ * @category Layers
+ */
+export const AppLayer = MarkdownWriterLayer.pipe(
+  Layer.provideMerge(IssueServiceLayer),
+  Layer.provideMerge(SiteUrlLive),
+  Layer.provideMerge(JiraClientLive),
+  Layer.provideMerge(AuthLive),
+  Layer.provideMerge(NodeHttpClient.layer),
+  Layer.provideMerge(NodeContext.layer)
+)
+
+/**
+ * Auth-only layer for auth commands.
+ *
+ * @category Layers
+ */
+export const AuthOnlyLayer = DummyIssueServiceLayer.pipe(
+  Layer.provideMerge(DummyMarkdownWriterLayer),
+  Layer.provideMerge(AuthLive),
+  Layer.provideMerge(NodeHttpClient.layer),
+  Layer.provideMerge(NodeContext.layer)
+)
+
+/**
+ * Minimal layer for help/version commands.
+ *
+ * @category Layers
+ */
+export const MinimalLayer = DummyIssueServiceLayer.pipe(
+  Layer.provideMerge(DummyMarkdownWriterLayer),
+  Layer.provideMerge(DummyJiraAuthLayer),
+  Layer.provideMerge(NodeContext.layer)
+)
+
+/**
+ * Determine which layer to use based on command.
+ *
+ * @category Utilities
+ */
+export const getLayerType = (argv: ReadonlyArray<string>): "full" | "auth" | "minimal" => {
+  const cmd = argv[2]
+  if (cmd === "auth") {
+    return "auth"
+  }
+  if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "--version") {
+    return "minimal"
+  }
+  return "full"
+}

package/src/commands/search.ts

@@ -0,0 +1,102 @@
+/**
+ * `jira 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 { buildByVersionJql } from "../internal/jqlBuilder.js"
+import { IssueService } from "../IssueService.js"
+import { MarkdownWriter } from "../MarkdownWriter.js"
+
+// === Options ===
+const jqlArg = Args.text({ name: "jql" }).pipe(
+  Args.withDescription("JQL query to search for issues"),
+  Args.optional
+)
+
+const byVersionOption = Options.text("by-version").pipe(
+  Options.withAlias("v"),
+  Options.withDescription("Search by fix version (pre-defined query)"),
+  Options.optional
+)
+
+const projectOption = Options.text("project").pipe(
+  Options.withAlias("p"),
+  Options.withDescription("Filter by project key"),
+  Options.optional
+)
+
+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(
+  Options.withAlias("f"),
+  Options.withDescription("Output format: multi (one file per issue) or single (combined file)"),
+  Options.withDefault("multi" as const)
+)
+
+const maxResultsOption = Options.integer("max-results").pipe(
+  Options.withAlias("m"),
+  Options.withDescription("Maximum number of results to fetch"),
+  Options.withDefault(100)
+)
+
+// === Search command ===
+export const searchCommand = Command.make(
+  "search",
+  {
+    jql: jqlArg,
+    byVersion: byVersionOption,
+    project: projectOption,
+    outputDir: outputDirOption,
+    format: formatOption,
+    maxResults: maxResultsOption
+  },
+  ({ byVersion, format, jql, maxResults, outputDir, project }) =>
+    Effect.gen(function*() {
+      const issueService = yield* IssueService
+      const writer = yield* MarkdownWriter
+
+      // Build JQL query
+      let query: string
+
+      if (Option.isSome(byVersion)) {
+        const projectKey = Option.isSome(project) ? project.value : undefined
+        query = buildByVersionJql(byVersion.value, projectKey)
+        yield* Console.log(`Searching by fix version: ${byVersion.value}`)
+      } else if (Option.isSome(jql)) {
+        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>")
+        return
+      }
+
+      yield* Console.log(`Query: ${query}`)
+      yield* Console.log("Fetching issues...")
+
+      const issues = yield* issueService.searchAll(query, { maxResults })
+
+      if (issues.length === 0) {
+        yield* Console.log("No issues found.")
+        return
+      }
+
+      yield* Console.log(`Found ${issues.length} issue(s). Writing to ${outputDir}...`)
+
+      if (format === "single") {
+        yield* writer.writeSingle(issues, outputDir, query)
+        yield* Console.log(`Exported to ${outputDir}/jira-export.md`)
+      } else {
+        yield* writer.writeMulti(issues, outputDir)
+        yield* Console.log(`Exported ${issues.length} file(s) to ${outputDir}/`)
+      }
+    })
+).pipe(Command.withDescription("Search Jira issues and export to markdown"))

package/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Root barrel export for `@knpkv/jira-cli`.
+ *
+ * @module
+ */
+
+export {
+  type Attachment,
+  type Comment,
+  type Issue,
+  IssueService,
+  type IssueServiceShape,
+  layer as IssueServiceLayer,
+  type SearchOptions,
+  type SearchResult,
+  SiteUrl
+} from "./IssueService.js"
+export {
+  type AccessibleSite,
+  JiraAuth,
+  type JiraAuthService,
+  layer as JiraAuthLayer,
+  type LoginOptions
+} from "./JiraAuth.js"
+export * from "./JiraCliError.js"
+export { layer as MarkdownWriterLayer, MarkdownWriter, type MarkdownWriterShape } from "./MarkdownWriter.js"

package/src/internal/NodeLayers.ts

@@ -0,0 +1,17 @@
+/**
+ * Node.js-specific HTTP server factory — the only file importing `@effect/platform-node` server.
+ *
+ * @internal
+ */
+import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer"
+import { createServer } from "node:http"
+import { makeHttpServerFactory } from "./oauthServer.js"
+
+/**
+ * HTTP Server factory layer using Node.js http module.
+ *
+ * @category Layers
+ */
+export const HttpServerFactoryLive = makeHttpServerFactory(
+  (port) => NodeHttpServer.layerServer(createServer, { port })
+)

package/src/internal/frontmatter.ts

@@ -0,0 +1,170 @@
+/**
+ * YAML frontmatter serialization for Jira issues using `gray-matter`.
+ *
+ * **Mental model**
+ *
+ * - {@link serializeIssue} produces `---\nyaml\n---\nmarkdown` for a single issue.
+ * - {@link buildCombinedMarkdown} concatenates all issues with a JQL header for single-file export.
+ *
+ * @internal
+ */
+import matter from "gray-matter"
+import type { Issue } from "../IssueService.js"
+
+/**
+ * Front-matter data for a Jira issue.
+ *
+ * @category Types
+ */
+export interface IssueFrontMatter {
+  readonly key: string
+  readonly id: string
+  readonly summary: string
+  readonly status: string
+  readonly type: string
+  readonly priority: string | null
+  readonly assignee: string | null
+  readonly reporter: string | null
+  readonly created: string
+  readonly updated: string
+  readonly fixVersions: ReadonlyArray<string>
+  readonly labels: ReadonlyArray<string>
+  readonly components: ReadonlyArray<string>
+  readonly url: string
+}
+
+/**
+ * Extract front-matter data from an issue.
+ *
+ * @param issue - The issue to extract from
+ * @returns Front-matter object
+ *
+ * @category Utilities
+ */
+export const extractFrontMatter = (issue: Issue): IssueFrontMatter => ({
+  key: issue.key,
+  id: issue.id,
+  summary: issue.summary,
+  status: issue.status,
+  type: issue.type,
+  priority: issue.priority,
+  assignee: issue.assignee,
+  reporter: issue.reporter,
+  created: issue.created.toISOString(),
+  updated: issue.updated.toISOString(),
+  fixVersions: issue.fixVersions,
+  labels: issue.labels,
+  components: issue.components,
+  url: issue.url
+})
+
+/**
+ * Serialize an issue to markdown with front-matter.
+ *
+ * @param issue - The issue to serialize
+ * @returns Markdown string with YAML front-matter
+ *
+ * @category Serialization
+ */
+export const serializeIssue = (issue: Issue): string => {
+  const frontMatter = extractFrontMatter(issue)
+  const content = buildMarkdownContent(issue)
+  return matter.stringify(content, frontMatter)
+}
+
+/**
+ * Build markdown content for an issue (without front-matter).
+ *
+ * @param issue - The issue to build content for
+ * @returns Markdown content string
+ *
+ * @category Serialization
+ */
+export const buildMarkdownContent = (issue: Issue): string => {
+  const parts: Array<string> = []
+
+  // Title
+  parts.push(`# ${issue.key}: ${issue.summary}`)
+  parts.push("")
+
+  // Description
+  if (issue.description) {
+    parts.push("## Description")
+    parts.push("")
+    parts.push(issue.description)
+    parts.push("")
+  }
+
+  // Attachments
+  if (issue.attachments.length > 0) {
+    parts.push("## Attachments")
+    parts.push("")
+    for (const attachment of issue.attachments) {
+      parts.push(`- [${attachment.filename}](${attachment.url})`)
+    }
+    parts.push("")
+  }
+
+  // Comments
+  if (issue.comments.length > 0) {
+    parts.push("## Comments")
+    parts.push("")
+    for (const comment of issue.comments) {
+      const date = comment.created.toISOString().split("T")[0]
+      parts.push(`### ${comment.author} (${date})`)
+      parts.push("")
+      parts.push(comment.body)
+      parts.push("")
+    }
+  }
+
+  return parts.join("\n")
+}
+
+/**
+ * Build a combined markdown file for multiple issues.
+ *
+ * @param issues - The issues to include
+ * @param jql - The JQL query used (for header)
+ * @returns Combined markdown string
+ *
+ * @category Serialization
+ */
+export const buildCombinedMarkdown = (issues: ReadonlyArray<Issue>, jql: string): string => {
+  const parts: Array<string> = []
+
+  // Header
+  parts.push("# Jira Export")
+  parts.push("")
+  parts.push(`Query: \`${jql}\``)
+  parts.push(`Exported: ${new Date().toISOString()}`)
+  parts.push(`Total: ${issues.length} tickets`)
+  parts.push("")
+  parts.push("---")
+  parts.push("")
+
+  // Issues
+  for (const issue of issues) {
+    parts.push(`## ${issue.key}: ${issue.summary}`)
+    parts.push("")
+    parts.push(
+      `**Status:** ${issue.status} | **Type:** ${issue.type}${
+        issue.priority ? ` | **Priority:** ${issue.priority}` : ""
+      }`
+    )
+    if (issue.assignee) {
+      parts.push(`**Assignee:** ${issue.assignee}`)
+    }
+    parts.push("")
+
+    if (issue.description) {
+      parts.push(issue.description)
+      parts.push("")
+    }
+
+    parts.push("---")
+    parts.push("")
+  }
+
+  return parts.join("\n")
+}