@knpkv/atlassian-common 0.3.0 → 1.0.0

package/src/config/ProfileManager.ts

@@ -0,0 +1,268 @@
+/**
+ * Unified Atlassian profile management helpers shared by Atlassian CLIs.
+ *
+ * @module
+ */
+import * as Data from "effect/Data"
+import * as Effect from "effect/Effect"
+import * as FileSystem from "effect/FileSystem"
+import * as Path from "effect/Path"
+import type * as PlatformError from "effect/PlatformError"
+import * as Schema from "effect/Schema"
+import type { HttpClient } from "effect/unstable/http"
+import type { OAuthError } from "../auth/OAuthErrors.js"
+import { refreshToken } from "../auth/OAuthOperations.js"
+import { type AuthProfile, findProfile, loadProfiles, saveProfiles, saveProfileToken } from "./AuthProfiles.js"
+import { getProfilesPath, type HomeDirectoryError, HomeDirectoryTag } from "./ConfigPaths.js"
+import { type OAuthToken, OAuthTokenSchema } from "./OAuthSchemas.js"
+import { FileSystemError, isTokenExpired, loadOAuthConfig } from "./TokenStorage.js"
+
+export interface AtlassianToolDefinition {
+  readonly toolName: string
+  readonly authStoreName?: string
+  readonly legacyAuthPath?: ReadonlyArray<string>
+  readonly label: string
+  readonly loginHint: string
+  readonly requiredScopes: ReadonlyArray<string>
+}
+
+export const JIRA_REQUIRED_SCOPES = [
+  "read:jira-work",
+  "write:jira-work",
+  "manage:jira-project",
+  "read:jira-user",
+  "read:me",
+  "offline_access"
+] as const
+
+export const CONFLUENCE_REQUIRED_SCOPES = [
+  "read:page:confluence",
+  "write:page:confluence",
+  "delete:page:confluence",
+  "read:me",
+  "offline_access"
+] as const
+
+export const ATLASSIAN_TOOLS = [
+  {
+    toolName: "jira-cli",
+    label: "Jira CLI",
+    loginHint: "jira auth login",
+    requiredScopes: JIRA_REQUIRED_SCOPES
+  },
+  {
+    toolName: "confluence-to-markdown",
+    legacyAuthPath: [".confluence", "auth.json"],
+    label: "Confluence to Markdown",
+    loginHint: "confluence auth login",
+    requiredScopes: CONFLUENCE_REQUIRED_SCOPES
+  },
+  {
+    toolName: "jira-clockify",
+    authStoreName: "jira-cli",
+    label: "Jira Clockify",
+    loginHint: "jcf auth jira login",
+    requiredScopes: JIRA_REQUIRED_SCOPES
+  }
+] as const satisfies ReadonlyArray<AtlassianToolDefinition>
+
+export type ProfileTokenStatus = "valid" | "expired"
+
+export class ProfileNotFoundError extends Data.TaggedError("ProfileNotFoundError")<{
+  readonly selector: string
+}> {
+  override get message(): string {
+    return `Profile not found: ${this.selector}`
+  }
+}
+
+export class MissingOAuthConfigError extends Data.TaggedError("MissingOAuthConfigError")<{
+  readonly authStoreName: string
+  readonly profileId: string
+}> {
+  override get message(): string {
+    return `Cannot refresh expired profile ${this.profileId}: missing OAuth config for ${this.authStoreName}`
+  }
+}
+
+export interface ToolProfileStatus {
+  readonly tool: AtlassianToolDefinition
+  readonly authStoreName: string
+  readonly activeProfile: AuthProfile | null
+  readonly profiles: ReadonlyArray<AuthProfile>
+  readonly tokenStatus: ProfileTokenStatus | "missing"
+  readonly missingScopes: ReadonlyArray<string>
+  readonly oauthConfigured: boolean
+}
+
+const authStoreName = (tool: AtlassianToolDefinition): string => tool.authStoreName ?? tool.toolName
+
+const uniqueAuthTools = (tools: ReadonlyArray<AtlassianToolDefinition>): ReadonlyArray<AtlassianToolDefinition> =>
+  tools.filter((tool, index) =>
+    tools.findIndex((candidate) => authStoreName(candidate) === authStoreName(tool)) === index
+  )
+
+const loadLegacyToken = (
+  tool: AtlassianToolDefinition
+): Effect.Effect<
+  OAuthToken | null,
+  FileSystemError | HomeDirectoryError,
+  FileSystem.FileSystem | Path.Path | HomeDirectoryTag
+> =>
+  Effect.gen(function*() {
+    if (!tool.legacyAuthPath) return null
+    const fs = yield* FileSystem.FileSystem
+    const path = yield* Path.Path
+    const homeDirectory = yield* HomeDirectoryTag
+    const home = yield* homeDirectory.get()
+    const authPath = path.join(home, ...tool.legacyAuthPath)
+    const exists = yield* fs.exists(authPath).pipe(Effect.catch(() => Effect.succeed(false)))
+    if (!exists) return null
+    const content = yield* fs.readFileString(authPath).pipe(
+      Effect.mapError((cause) => new FileSystemError({ operation: "read", path: authPath, cause }))
+    )
+    const parsed = yield* Effect.try({
+      try: () => JSON.parse(content) as unknown,
+      catch: (cause) => cause
+    }).pipe(Effect.catch(() => Effect.succeed(null)))
+    if (parsed === null) return null
+    return yield* Schema.decodeUnknownEffect(OAuthTokenSchema)(parsed).pipe(
+      Effect.catch(() => Effect.succeed(null))
+    )
+  })
+
+export const tokenScopes = (token: OAuthToken): ReadonlySet<string> =>
+  new Set(token.scope.split(/\s+/).filter((scope: string) => scope.length > 0))
+
+export const missingScopes = (
+  token: OAuthToken,
+  requiredScopes: ReadonlyArray<string>
+): ReadonlyArray<string> => {
+  const granted = tokenScopes(token)
+  return requiredScopes.filter((scope) => !granted.has(scope))
+}
+
+export const inspectToolProfiles = (
+  tool: AtlassianToolDefinition
+): Effect.Effect<
+  ToolProfileStatus,
+  FileSystemError | HomeDirectoryError,
+  FileSystem.FileSystem | Path.Path | HomeDirectoryTag
+> =>
+  Effect.gen(function*() {
+    const storeName = authStoreName(tool)
+    const [store, config] = yield* Effect.all([loadProfiles(storeName), loadOAuthConfig(storeName)])
+    const activeProfile = store.profiles.find((profile) => profile.id === store.activeProfileId) ?? store.profiles[0] ??
+      null
+    return {
+      tool,
+      authStoreName: storeName,
+      activeProfile,
+      profiles: store.profiles,
+      tokenStatus: activeProfile === null ? "missing" : isTokenExpired(activeProfile.token, 0) ? "expired" : "valid",
+      missingScopes: activeProfile === null ? [] : missingScopes(activeProfile.token, tool.requiredScopes),
+      oauthConfigured: config !== null
+    }
+  })
+
+export const inspectAllToolProfiles = (
+  tools: ReadonlyArray<AtlassianToolDefinition> = ATLASSIAN_TOOLS
+) => Effect.forEach(tools, inspectToolProfiles)
+
+/**
+ * Switch matching existing profiles across auth stores.
+ *
+ * Fails when the selector is not present in any store so callers do not
+ * mistake an unchanged profile list for a successful switch.
+ */
+export const useProfileForAllTools = (
+  selector: string,
+  tools: ReadonlyArray<AtlassianToolDefinition> = ATLASSIAN_TOOLS
+): Effect.Effect<
+  ReadonlyArray<ToolProfileStatus>,
+  ProfileNotFoundError | FileSystemError | HomeDirectoryError | PlatformError.PlatformError,
+  FileSystem.FileSystem | Path.Path | HomeDirectoryTag
+> =>
+  Effect.gen(function*() {
+    const authTools = uniqueAuthTools(tools)
+    const stores = yield* Effect.forEach(authTools, (tool) =>
+      loadProfiles(authStoreName(tool)).pipe(Effect.map((store) => [tool, store] as const)))
+    const selected = stores.map(([, store]) =>
+      findProfile(store.profiles, selector)
+    ).find((profile): profile is AuthProfile =>
+      profile !== null
+    )
+    if (!selected) return yield* Effect.fail(new ProfileNotFoundError({ selector }))
+
+    yield* Effect.forEach(stores, ([tool, store]) => {
+      const matching = findProfile(store.profiles, selector) ?? findProfile(store.profiles, selected.id)
+      if (!matching) return Effect.void
+      return saveProfiles(authStoreName(tool), { ...store, activeProfileId: matching.id })
+    })
+    return yield* inspectAllToolProfiles(tools)
+  })
+
+/**
+ * Persist legacy single-token auth files into shared profile stores.
+ *
+ * Supports both XDG Atlassian auth files and tool-specific legacy paths such
+ * as Confluence's historical `~/.confluence/auth.json`.
+ */
+export const migrateLegacyProfiles = (
+  tools: ReadonlyArray<AtlassianToolDefinition> = ATLASSIAN_TOOLS
+): Effect.Effect<
+  ReadonlyArray<ToolProfileStatus>,
+  FileSystemError | HomeDirectoryError | PlatformError.PlatformError,
+  FileSystem.FileSystem | Path.Path | HomeDirectoryTag
+> =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    yield* Effect.forEach(uniqueAuthTools(tools), (tool) =>
+      Effect.gen(function*() {
+        const storeName = authStoreName(tool)
+        const profilesPath = yield* getProfilesPath(storeName)
+        const hasProfilesFile = yield* fs.exists(profilesPath).pipe(Effect.catch(() => Effect.succeed(false)))
+        if (hasProfilesFile) return
+        const store = yield* loadProfiles(storeName)
+        if (store.profiles.length > 0) {
+          yield* saveProfiles(storeName, store)
+          return
+        }
+        const legacyToken = yield* loadLegacyToken(tool)
+        if (legacyToken !== null) {
+          yield* saveProfileToken(storeName, legacyToken)
+        }
+      }))
+    return yield* inspectAllToolProfiles(tools)
+  })
+
+/**
+ * Refresh expired active profiles.
+ *
+ * Fails when an expired profile lacks OAuth client configuration so refresh
+ * callers cannot report success while leaving a token expired.
+ */
+export const refreshActiveProfiles = (
+  tools: ReadonlyArray<AtlassianToolDefinition> = ATLASSIAN_TOOLS
+): Effect.Effect<
+  ReadonlyArray<ToolProfileStatus>,
+  MissingOAuthConfigError | OAuthError | FileSystemError | HomeDirectoryError | PlatformError.PlatformError,
+  FileSystem.FileSystem | Path.Path | HomeDirectoryTag | HttpClient.HttpClient
+> =>
+  Effect.gen(function*() {
+    yield* Effect.forEach(uniqueAuthTools(tools), (tool) =>
+      Effect.gen(function*() {
+        const storeName = authStoreName(tool)
+        const store = yield* loadProfiles(storeName)
+        const active = store.profiles.find((profile) => profile.id === store.activeProfileId) ?? store.profiles[0] ??
+          null
+        if (!active || !isTokenExpired(active.token, 0)) return
+        const config = yield* loadOAuthConfig(storeName)
+        if (!config) {
+          return yield* Effect.fail(new MissingOAuthConfigError({ authStoreName: storeName, profileId: active.id }))
+        }
+        const refreshed = yield* refreshToken(active.token, config)
+        yield* saveProfileToken(storeName, refreshed)
+      }))
+    return yield* inspectAllToolProfiles(tools)
+  })

package/src/config/index.ts

@@ -10,6 +10,7 @@ export {
   getAuthPath,
   getConfigDir,
   getOAuthConfigPath,
+  getProfilesPath,
   type HomeDirectory,
   HomeDirectoryError,
   HomeDirectoryLive,
@@ -41,3 +42,44 @@ export {
   saveOAuthConfig,
   saveToken
 } from "./TokenStorage.js"
+
+// Auth profiles
+export {
+  type AuthProfile,
+  AuthProfileSchema,
+  type AuthProfilesFile,
+  AuthProfilesFileSchema,
+  deleteActiveProfile,
+  deleteProfile,
+  deleteProfileBySelector,
+  findProfile,
+  loadActiveProfile,
+  loadActiveProfileToken,
+  loadProfiles,
+  profileFromToken,
+  profileIdFromToken,
+  profileNameFromToken,
+  saveProfiles,
+  saveProfileToken,
+  setActiveProfile,
+  setActiveProfileBySelector
+} from "./AuthProfiles.js"
+
+// Unified profile manager
+export {
+  ATLASSIAN_TOOLS,
+  type AtlassianToolDefinition,
+  CONFLUENCE_REQUIRED_SCOPES,
+  inspectAllToolProfiles,
+  inspectToolProfiles,
+  JIRA_REQUIRED_SCOPES,
+  migrateLegacyProfiles,
+  MissingOAuthConfigError,
+  missingScopes,
+  ProfileNotFoundError,
+  type ProfileTokenStatus,
+  refreshActiveProfiles,
+  tokenScopes,
+  type ToolProfileStatus,
+  useProfileForAllTools
+} from "./ProfileManager.js"

package/test/AuthProfiles.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from "@effect/vitest"
+import { ConfigProvider, Effect, Layer } from "effect"
+import * as FileSystem from "effect/FileSystem"
+import * as Path from "effect/Path"
+import { SystemError } from "effect/PlatformError"
+import {
+  deleteProfileBySelector,
+  HomeDirectoryLive,
+  loadActiveProfileToken,
+  loadProfiles,
+  type OAuthToken,
+  saveProfileToken,
+  setActiveProfileBySelector
+} from "../src/config/index.js"
+
+const TEST_HOME = "/tmp/atlassian-common-profile-test"
+const TOOL_NAME = "test-tool"
+const basePath = `${TEST_HOME}/.config/atlassian/${TOOL_NAME}`
+const authPath = `${basePath}/auth.json`
+const profilesPath = `${basePath}/profiles.json`
+
+const fsError = (method: string) =>
+  Effect.fail(
+    new SystemError({ _tag: "NotFound", module: "FileSystem", method, description: "mock not found" })
+  )
+
+const makeToken = (n: number): OAuthToken => ({
+  access_token: `access-${n}`,
+  refresh_token: `refresh-${n}`,
+  expires_at: Date.now() + 60_000,
+  scope: "read:me offline_access",
+  cloud_id: `cloud-${n}`,
+  site_url: `https://site-${n}.atlassian.net`,
+  user: {
+    account_id: `account-${n}`,
+    name: `User ${n}`,
+    email: `user-${n}@example.com`
+  }
+})
+
+const makeMockFS = (files: Record<string, string> = {}) => {
+  const store = { ...files }
+  const partial: Partial<FileSystem.FileSystem> = {
+    exists: (path) => Effect.succeed(path in store),
+    readFileString: (path) => path in store ? Effect.succeed(store[path]!) : fsError("readFileString"),
+    writeFileString: (path: string, content: string) => {
+      store[path] = content
+      return Effect.void
+    },
+    makeDirectory: () => Effect.void,
+    chmod: () => Effect.void,
+    remove: (path: string) => {
+      delete store[path]
+      return Effect.void
+    }
+  }
+
+  return {
+    store,
+    layer: Layer.succeed(FileSystem.FileSystem, FileSystem.FileSystem.of(partial as FileSystem.FileSystem))
+  }
+}
+
+const ConfigProviderLive = ConfigProvider.layer(
+  ConfigProvider.fromEnv({ env: { HOME: TEST_HOME } })
+)
+
+const run = <A>(
+  effect: Effect.Effect<A, unknown, FileSystem.FileSystem | Path.Path>,
+  files?: Record<string, string>
+) => {
+  const mock = makeMockFS(files)
+  const layer = Layer.mergeAll(mock.layer, Path.layer, HomeDirectoryLive, ConfigProviderLive)
+  return Effect.runPromise(effect.pipe(Effect.provide(layer))).then((result) => ({ result, store: mock.store }))
+}
+
+describe("AuthProfiles", () => {
+  it("upserts profiles and mirrors the active profile to auth.json", async () => {
+    const first = makeToken(1)
+    const second = makeToken(2)
+
+    const { result: profiles, store } = await run(
+      Effect.gen(function*() {
+        yield* saveProfileToken(TOOL_NAME, first)
+        yield* saveProfileToken(TOOL_NAME, second)
+        return yield* loadProfiles(TOOL_NAME)
+      })
+    )
+
+    expect(profiles.profiles.map((profile) => profile.id)).toEqual(["account-2@cloud-2", "account-1@cloud-1"])
+    expect(profiles.activeProfileId).toBe("account-2@cloud-2")
+    expect(JSON.parse(store[authPath]!)["access_token"]).toBe("access-2")
+    expect(JSON.parse(store[profilesPath]!)["profiles"]).toHaveLength(2)
+  })
+
+  it("switches and removes profiles by flexible selector", async () => {
+    const first = makeToken(1)
+    const second = makeToken(2)
+
+    const { result, store } = await run(
+      Effect.gen(function*() {
+        yield* saveProfileToken(TOOL_NAME, first)
+        yield* saveProfileToken(TOOL_NAME, second)
+        const selected = yield* setActiveProfileBySelector(TOOL_NAME, first.site_url)
+        const activeAfterSwitch = yield* loadActiveProfileToken(TOOL_NAME)
+        const removed = yield* deleteProfileBySelector(TOOL_NAME, first.user!.account_id)
+        const activeAfterRemove = yield* loadActiveProfileToken(TOOL_NAME)
+        return { selected, activeAfterSwitch, removed, activeAfterRemove }
+      })
+    )
+
+    expect(result.selected?.id).toBe("account-1@cloud-1")
+    expect(result.activeAfterSwitch?.access_token).toBe("access-1")
+    expect(result.removed?.id).toBe("account-1@cloud-1")
+    expect(result.activeAfterRemove?.access_token).toBe("access-2")
+    expect(JSON.parse(store[authPath]!)["access_token"]).toBe("access-2")
+  })
+
+  it("loads a legacy auth.json token as a single active profile", async () => {
+    const token = makeToken(1)
+
+    const { result } = await run(
+      loadProfiles(TOOL_NAME),
+      { [authPath]: JSON.stringify(token, null, 2) }
+    )
+
+    expect(result.activeProfileId).toBe("account-1@cloud-1")
+    expect(result.profiles).toHaveLength(1)
+    expect(result.profiles[0]?.token.access_token).toBe("access-1")
+  })
+})

package/test/OAuthEndpoints.test.ts

@@ -1,25 +1,30 @@
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
 import { it as effectIt } from "@effect/vitest"
 import * as Effect from "effect/Effect"
 import { describe, expect, it } from "vitest"
 import { AUTH_URL, buildAuthUrl, computeCodeChallenge, generateCodeVerifier } from "../src/auth/OAuthEndpoints.js"
 
+const withCrypto = <A, E, R>(effect: Effect.Effect<A, E, R>) => effect.pipe(Effect.provide(NodeCrypto.layer))
+
 describe("OAuthEndpoints", () => {
   // ---- PKCE ----
 
   describe("generateCodeVerifier", () => {
     // 32 random bytes base64url-encoded = 43 chars; verifies output shape for RFC 7636 compliance
-    it("returns a base64url string of 43 characters (32 random bytes)", () => {
-      const verifier = generateCodeVerifier()
-      expect(verifier).toHaveLength(43)
-      expect(verifier).toMatch(/^[A-Za-z0-9_-]+$/)
-    })
+    effectIt.effect("returns a base64url string of 43 characters (32 random bytes)", () =>
+      Effect.gen(function*() {
+        const verifier = yield* generateCodeVerifier()
+        expect(verifier).toHaveLength(43)
+        expect(verifier).toMatch(/^[A-Za-z0-9_-]+$/)
+      }).pipe(withCrypto))
 
     // PKCE verifiers must be unique per auth request — reuse enables replay attacks
-    it("produces unique values", () => {
-      const a = generateCodeVerifier()
-      const b = generateCodeVerifier()
-      expect(a).not.toBe(b)
-    })
+    effectIt.effect("produces unique values", () =>
+      Effect.gen(function*() {
+        const a = yield* generateCodeVerifier()
+        const b = yield* generateCodeVerifier()
+        expect(a).not.toBe(b)
+      }).pipe(withCrypto))
   })
 
   describe("computeCodeChallenge", () => {
@@ -30,23 +35,23 @@ describe("OAuthEndpoints", () => {
         const expected = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
         const challenge = yield* computeCodeChallenge(verifier)
         expect(challenge).toBe(expected)
-      }))
+      }).pipe(withCrypto))
 
     // Same verifier must always produce same challenge — server verifies this on token exchange
     effectIt.effect("is deterministic", () =>
       Effect.gen(function*() {
-        const v = generateCodeVerifier()
+        const v = yield* generateCodeVerifier()
         const a = yield* computeCodeChallenge(v)
         const b = yield* computeCodeChallenge(v)
         expect(a).toBe(b)
-      }))
+      }).pipe(withCrypto))
 
     // base64url must not contain +, /, = — these break URL query params
     effectIt.effect("produces base64url output (no +, /, =)", () =>
       Effect.gen(function*() {
         const challenge = yield* computeCodeChallenge("test-verifier-string")
         expect(challenge).toMatch(/^[A-Za-z0-9_-]+$/)
-      }))
+      }).pipe(withCrypto))
   })
 
   // ---- buildAuthUrl ----
@@ -103,7 +108,7 @@ describe("OAuthEndpoints", () => {
           const parsed = new URL(url)
           expect(parsed.searchParams.get("code_challenge")).toBe(challenge)
           expect(parsed.searchParams.get("code_challenge_method")).toBe("S256")
-        })
+        }).pipe(withCrypto)
     )
   })
 })

package/test/OAuthOperations.test.ts

@@ -1,6 +1,7 @@
 import { describe, it } from "@effect/vitest"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
+import { TestClock } from "effect/testing"
 import type { HttpClientRequest } from "effect/unstable/http"
 import { HttpClient, HttpClientResponse } from "effect/unstable/http"
 import { expect } from "vitest"
@@ -58,6 +59,8 @@ const oauthConfig: OAuthConfig = {
   clientSecret: "csecret"
 }
 
+const TEST_NOW = Date.parse("2026-01-01T00:00:00.000Z")
+
 const oauthToken: OAuthToken = {
   access_token: "old-access",
   refresh_token: "old-refresh",
@@ -221,6 +224,7 @@ describe("OAuthOperations", () => {
     // Verifies grant_type=refresh_token is sent and returned token preserves cloud_id/site_url from original
     it.effect("sends refresh_token and returns updated OAuthToken", () =>
       Effect.gen(function*() {
+        yield* TestClock.setTime(TEST_NOW)
         const { capturedRequests, mockClient } = createMockHttpClient([
           { status: 200, body: { ...validTokenBody, access_token: "new-access", refresh_token: "new-refresh" } }
         ])
@@ -232,7 +236,7 @@ describe("OAuthOperations", () => {
         // preserves existing fields
         expect(result.cloud_id).toBe("cloud-1")
         expect(result.site_url).toBe("https://site.atlassian.net")
-        expect(result.expires_at).toBeGreaterThan(Date.now())
+        expect(result.expires_at).toBe(TEST_NOW + validTokenBody.expires_in * 1000)
 
         const req = capturedRequests[0]!
         const body = yield* req.body._tag === "Uint8Array"