@knpkv/jira-cli 0.1.1

package/src/internal/jqlBuilder.ts

@@ -0,0 +1,49 @@
+/**
+ * JQL query construction with proper value escaping.
+ *
+ * **Mental model**
+ *
+ * - {@link buildByVersionJql} generates `fixVersion = "X"` queries with optional project filter.
+ * - {@link escapeJqlValue} handles backslashes, quotes, newlines, carriage returns.
+ *
+ * @internal
+ */
+
+/**
+ * Build JQL query to find issues by fix version.
+ *
+ * @param version - The fix version to search for
+ * @param project - Optional project key to filter by
+ * @returns JQL query string
+ *
+ * @example
+ * ```typescript
+ * buildByVersionJql("1.0.0")
+ * // => 'fixVersion = "1.0.0" ORDER BY key ASC'
+ *
+ * buildByVersionJql("1.0.0", "PROJ")
+ * // => 'project = "PROJ" AND fixVersion = "1.0.0" ORDER BY key ASC'
+ * ```
+ *
+ * @category JQL Builders
+ */
+export const buildByVersionJql = (version: string, project?: string): string => {
+  const escapedVersion = escapeJqlValue(version)
+  const projectClause = project !== undefined ? `project = "${escapeJqlValue(project)}" AND ` : ""
+  return `${projectClause}fixVersion = "${escapedVersion}" ORDER BY key ASC`
+}
+
+/**
+ * Escape a value for use in JQL queries.
+ *
+ * @param value - The value to escape
+ * @returns Escaped value safe for JQL
+ *
+ * @category Utilities
+ */
+export const escapeJqlValue = (value: string): string =>
+  value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, "\\\"")
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r")

package/src/internal/oauthServer.ts

@@ -0,0 +1,203 @@
+/**
+ * Local HTTP callback server for OAuth2 authorization code capture.
+ *
+ * **Mental model**
+ *
+ * - **Deferred-coordinated lifecycle**: {@link startCallbackServer} returns a `codePromise`
+ *   (Deferred) and a `shutdown` effect. The server validates the CSRF `state` parameter
+ *   and resolves the Deferred with the authorization code.
+ * - **Port auto-discovery**: Tries default port 8585, increments on conflict.
+ *
+ * @internal
+ */
+import * as HttpRouter from "@effect/platform/HttpRouter"
+import * as HttpServer from "@effect/platform/HttpServer"
+import type { ServeError } from "@effect/platform/HttpServerError"
+import * as HttpServerRequest from "@effect/platform/HttpServerRequest"
+import * as HttpServerResponse from "@effect/platform/HttpServerResponse"
+import { OAuthError } from "@knpkv/atlassian-common/auth"
+import * as Context from "effect/Context"
+import * as Deferred from "effect/Deferred"
+import * as Effect from "effect/Effect"
+import * as Fiber from "effect/Fiber"
+import * as Layer from "effect/Layer"
+
+const DEFAULT_PORT = 8585
+const MAX_PORT_ATTEMPTS = 10
+
+/**
+ * Factory service for creating HTTP servers.
+ * This allows mocking the server creation in tests.
+ *
+ * @category Services
+ */
+export interface HttpServerFactory {
+  readonly createServerLayer: (port: number) => Layer.Layer<
+    HttpServer.HttpServer,
+    ServeError,
+    never
+  >
+}
+
+/**
+ * Tag for the HttpServerFactory service.
+ *
+ * @category Services
+ */
+export class HttpServerFactoryTag extends Context.Tag("@knpkv/jira-cli/HttpServerFactory")<
+  HttpServerFactoryTag,
+  HttpServerFactory
+>() {}
+
+/**
+ * Create a HttpServerFactory layer from a layer factory function.
+ * This allows injecting platform-specific implementations.
+ *
+ * @param createLayerFn - Function that creates HttpServer layer for a given port
+ * @returns Layer providing HttpServerFactory
+ *
+ * @category Layers
+ */
+export const makeHttpServerFactory = (
+  createLayerFn: (port: number) => Layer.Layer<HttpServer.HttpServer, ServeError, never>
+): Layer.Layer<HttpServerFactoryTag> =>
+  Layer.succeed(HttpServerFactoryTag, {
+    createServerLayer: createLayerFn
+  })
+
+/**
+ * Check if a port is available by attempting to start a server.
+ */
+const isPortAvailable = (port: number): Effect.Effect<boolean, never, HttpServerFactoryTag> =>
+  Effect.gen(function*() {
+    const factory = yield* HttpServerFactoryTag
+    const serverLayer = factory.createServerLayer(port)
+
+    const result = yield* Layer.build(serverLayer).pipe(
+      Effect.scoped,
+      Effect.as(true),
+      Effect.catchAll(() => Effect.succeed(false))
+    )
+    return result
+  })
+
+/**
+ * Find an available port starting from the default.
+ */
+const findAvailablePort = (): Effect.Effect<number, OAuthError, HttpServerFactoryTag> =>
+  Effect.gen(function*() {
+    for (let attempt = 0; attempt < MAX_PORT_ATTEMPTS; attempt++) {
+      const port = DEFAULT_PORT + attempt
+      const available = yield* isPortAvailable(port)
+      if (available) {
+        return port
+      }
+    }
+    return yield* Effect.fail(
+      new OAuthError({
+        step: "authorize",
+        cause: `Could not find available port (tried ${DEFAULT_PORT}-${
+          DEFAULT_PORT + MAX_PORT_ATTEMPTS - 1
+        }). Close other applications using these ports.`
+      })
+    )
+  })
+
+/**
+ * Result from the OAuth callback server.
+ */
+export interface CallbackServerResult {
+  /** Promise that resolves with the authorization code */
+  readonly codePromise: Effect.Effect<string, OAuthError>
+  /** Shutdown the callback server */
+  readonly shutdown: Effect.Effect<void, never>
+  /** The port the server is listening on */
+  readonly port: number
+}
+
+/**
+ * Start a local HTTP server to receive OAuth callback.
+ *
+ * @param expectedState - The state parameter to verify against CSRF
+ * @returns Server control interface with code promise, shutdown, and port
+ *
+ * @category OAuth
+ */
+export const startCallbackServer = (
+  expectedState: string
+): Effect.Effect<CallbackServerResult, OAuthError, HttpServerFactoryTag> =>
+  Effect.gen(function*() {
+    const factory = yield* HttpServerFactoryTag
+    const port = yield* findAvailablePort()
+    const deferred = yield* Deferred.make<string, OAuthError>()
+    const readyDeferred = yield* Deferred.make<void, OAuthError>()
+
+    const app = HttpRouter.empty.pipe(
+      HttpRouter.get(
+        "/callback",
+        Effect.gen(function*() {
+          const req = yield* HttpServerRequest.HttpServerRequest
+          const url = new URL(req.url, `http://localhost:${port}`)
+          const code = url.searchParams.get("code")
+          const state = url.searchParams.get("state")
+          const error = url.searchParams.get("error")
+          const errorDescription = url.searchParams.get("error_description")
+
+          if (error) {
+            yield* Deferred.fail(
+              deferred,
+              new OAuthError({ step: "authorize", cause: errorDescription ?? error })
+            )
+            return HttpServerResponse.html(
+              "<html><body><h1>Authorization Failed</h1><p>You can close this window.</p></body></html>"
+            )
+          }
+
+          if (state !== expectedState) {
+            yield* Deferred.fail(
+              deferred,
+              new OAuthError({ step: "authorize", cause: "State mismatch - possible CSRF attack" })
+            )
+            return HttpServerResponse.html(
+              "<html><body><h1>Security Error</h1><p>State verification failed.</p></body></html>"
+            )
+          }
+
+          if (!code) {
+            yield* Deferred.fail(
+              deferred,
+              new OAuthError({ step: "authorize", cause: "No authorization code received" })
+            )
+            return HttpServerResponse.html(
+              "<html><body><h1>Error</h1><p>No authorization code received.</p></body></html>"
+            )
+          }
+
+          yield* Deferred.succeed(deferred, code)
+          return HttpServerResponse.html(
+            "<html><body><h1>Success!</h1><p>You can close this window and return to the terminal.</p></body></html>"
+          )
+        })
+      )
+    )
+
+    const serverLayer = factory.createServerLayer(port)
+
+    const serverFiber = yield* HttpServer.serve(app).pipe(
+      Layer.provide(serverLayer),
+      Layer.build,
+      Effect.tap(() => Deferred.succeed(readyDeferred, undefined)),
+      Effect.tapError((err) => Deferred.fail(readyDeferred, new OAuthError({ step: "authorize", cause: err }))),
+      Effect.flatMap(() => Effect.never),
+      Effect.scoped,
+      Effect.fork
+    )
+
+    yield* Deferred.await(readyDeferred)
+
+    return {
+      codePromise: Deferred.await(deferred),
+      shutdown: Fiber.interrupt(serverFiber).pipe(Effect.asVoid),
+      port
+    }
+  })

package/test/jqlBuilder.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "@effect/vitest"
+import { buildByVersionJql, escapeJqlValue } from "../src/internal/jqlBuilder.js"
+
+describe("jqlBuilder", () => {
+  describe("buildByVersionJql", () => {
+    it("builds JQL for version only", () => {
+      const result = buildByVersionJql("1.0.0")
+      expect(result).toBe("fixVersion = \"1.0.0\" ORDER BY key ASC")
+    })
+
+    it("builds JQL with project filter", () => {
+      const result = buildByVersionJql("1.0.0", "PROJ")
+      expect(result).toBe("project = \"PROJ\" AND fixVersion = \"1.0.0\" ORDER BY key ASC")
+    })
+
+    it("handles version with special characters", () => {
+      const result = buildByVersionJql("1.0.0-beta.1")
+      expect(result).toBe("fixVersion = \"1.0.0-beta.1\" ORDER BY key ASC")
+    })
+
+    it("escapes quotes in version name", () => {
+      const result = buildByVersionJql("OOB 42 \"Nimble Needlefish\"")
+      expect(result).toBe("fixVersion = \"OOB 42 \\\"Nimble Needlefish\\\"\" ORDER BY key ASC")
+    })
+  })
+
+  describe("escapeJqlValue", () => {
+    it("escapes backslashes", () => {
+      expect(escapeJqlValue("path\\to\\file")).toBe("path\\\\to\\\\file")
+    })
+
+    it("escapes double quotes", () => {
+      expect(escapeJqlValue("say \"hello\"")).toBe("say \\\"hello\\\"")
+    })
+
+    it("leaves normal strings unchanged", () => {
+      expect(escapeJqlValue("normal string")).toBe("normal string")
+    })
+
+    it("escapes newlines and carriage returns", () => {
+      expect(escapeJqlValue("line1\nline2")).toBe("line1\\nline2")
+      expect(escapeJqlValue("line1\r\nline2")).toBe("line1\\r\\nline2")
+    })
+  })
+})

package/tsconfig.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "allowUnusedLabels": false,
+    "allowUnreachableCode": false,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "bundler",
+    "module": "ESNext",
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}

package/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "vitest/config"
+
+export default defineConfig({
+  test: {
+    include: ["test/**/*.test.ts"],
+    globals: true,
+    environment: "node",
+    testTimeout: 30000,
+    hookTimeout: 30000,
+    teardownTimeout: 30000
+  }
+})