@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/auth/signin.ts

@@ -0,0 +1,494 @@
+import { spawn, spawnSync } from "node:child_process"
+
+import { azCliAuth, resetAzCliAuth } from "../cases/ado.ts"
+import { basic, http } from "../cases/http.ts"
+import type { AppConfig } from "../config.ts"
+import type { AskQuestion } from "../mcp/tools.ts"
+import { withoutTelemetry } from "../privacy.ts"
+import { forgetSystem, fromSaved, readIndex, savedSecrets, saveSystem, storeName, type Via } from "./store.ts"
+
+/** How a sign-in talks to the user: the terminal (`forgeqe auth`) or the shell's dialogs (/auth). */
+export type AuthIO = {
+  say(text: string, kind?: "info" | "ok" | "err"): void
+  /** A line of text; `secret` hides what is typed. null when the user cancels. */
+  input(q: { label: string; secret?: boolean; initial?: string }): Promise<string | null>
+  choose(q: AskQuestion): Promise<string | null>
+  openUrl(url: string): void
+  /** az and gh can take over the terminal (`forgeqe auth`); in the shell their output is read and shown instead. */
+  attached?: boolean
+  signal?: AbortSignal
+}
+
+export type SystemId = "azure_devops" | "github" | "jira" | "confluence" | "testrail" | "zephyr" | "qtest" | "xray"
+
+export const SYSTEMS: { id: SystemId; label: string; aliases: string[] }[] = [
+  { id: "azure_devops", label: "Azure DevOps", aliases: ["ado", "azure", "devops", "azdo", "azure-devops"] },
+  { id: "github", label: "GitHub", aliases: ["gh"] },
+  { id: "jira", label: "Jira", aliases: ["atlassian"] },
+  { id: "confluence", label: "Confluence", aliases: ["wiki"] },
+  { id: "testrail", label: "TestRail", aliases: [] },
+  { id: "zephyr", label: "Zephyr Scale", aliases: ["zephyr-scale"] },
+  { id: "qtest", label: "qTest", aliases: [] },
+  { id: "xray", label: "Xray Cloud", aliases: [] },
+]
+
+/** A system id from what the user typed ("ado", "Azure DevOps", "jira"); null when it names none. */
+export function findSystem(name: string): SystemId | null {
+  const n = name.trim().toLowerCase().replace(/\s+/g, "_")
+  if (!n) return null
+  const s = SYSTEMS.find((x) => x.id === n || x.label.toLowerCase().replace(/\s+/g, "_") === n || x.aliases.includes(n.replace(/_/g, "-")) || x.aliases.includes(n))
+  return s?.id || null
+}
+
+export type SignInResult = { ok: boolean; system: string; message: string; account?: string }
+
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/** The environment variable names the config reads for each system (forgeqe.yaml can rename them). */
+export function envNames(cfg?: AppConfig) {
+  const s = cfg?.sources
+  return {
+    ado: { url: "ADO_ORG_URL", token: s?.ado?.tokenEnv || "ADO_PAT" },
+    jira: { url: "JIRA_URL", email: s?.jira?.emailEnv || "JIRA_EMAIL", token: s?.jira?.tokenEnv || "JIRA_API_TOKEN" },
+    confluence: { url: "CONFLUENCE_URL", email: s?.confluence?.emailEnv || "CONFLUENCE_EMAIL", token: s?.confluence?.tokenEnv || "CONFLUENCE_TOKEN" },
+    testrail: { url: "TESTRAIL_URL", email: s?.testrail?.emailEnv || "TESTRAIL_EMAIL", token: s?.testrail?.tokenEnv || "TESTRAIL_API_KEY" },
+    zephyr: { url: "ZEPHYR_URL", token: s?.zephyr?.tokenEnv || "ZEPHYR_API_TOKEN" },
+    qtest: { url: "QTEST_URL", project: "QTEST_PROJECT_ID", token: s?.qtest?.tokenEnv || "QTEST_TOKEN" },
+    xray: { url: "XRAY_URL", id: s?.xray.clientIdEnv || "XRAY_CLIENT_ID", secret: s?.xray.clientSecretEnv || "XRAY_CLIENT_SECRET" },
+  }
+}
+
+/** Open a page in the default browser. */
+export function openInBrowser(url: string): void {
+  const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]]
+  try {
+    spawn(cmd as string, args as string[], { stdio: "ignore", detached: true }).unref()
+  } catch {}
+}
+
+// ---- Small helpers ----
+
+const httpsUrl = (raw: string) => {
+  const t = raw.trim().replace(/\/+$/, "")
+  return /^https?:\/\//i.test(t) ? t : `https://${t}`
+}
+
+/** "acme", "dev.azure.com/acme/Shop", or a visualstudio.com URL → the organization URL. */
+export function adoOrgUrl(raw: string): string {
+  const t = raw.trim()
+  if (/^[A-Za-z0-9][A-Za-z0-9-]*$/.test(t)) return `https://dev.azure.com/${t}`
+  const u = new URL(httpsUrl(t))
+  if (u.hostname === "dev.azure.com") return `${u.origin}/${u.pathname.split("/").filter(Boolean)[0] || ""}`.replace(/\/+$/, "")
+  if (u.hostname.endsWith(".visualstudio.com")) return u.origin
+  return `${u.origin}${u.pathname}`.replace(/\/+$/, "")
+}
+
+/** An Atlassian Cloud site's root (https://acme.atlassian.net) from any page on it. */
+const siteRoot = (raw: string) => {
+  const u = new URL(httpsUrl(raw))
+  return u.hostname.endsWith(".atlassian.net") ? u.origin : `${u.origin}${u.pathname}`.replace(/\/+$/, "")
+}
+
+const isCloud = (url: string) => new URL(url).hostname.endsWith(".atlassian.net")
+
+function gitEmail(): string | undefined {
+  const r = spawnSync("git", ["config", "user.email"], { encoding: "utf8" })
+  return r.status === 0 ? r.stdout.trim() || undefined : undefined
+}
+
+async function ask(io: AuthIO, label: string, opts: { secret?: boolean; initial?: string } = {}): Promise<string> {
+  const v = await io.input({ label, ...opts })
+  if (v === null || !v.trim()) throw new Cancelled()
+  return v.trim()
+}
+
+class Cancelled extends Error {
+  constructor() {
+    super("Cancelled.")
+  }
+}
+
+/** A value the config already has: from forgeqe.yaml, the environment, or an earlier sign-in. */
+const known = (name: string, fromConfig?: string) => fromConfig || process.env[name] || undefined
+
+/**
+ * Run az or gh. With `attached` it takes over the terminal; otherwise its output is read line by line and shown, and
+ * `onLine` can answer it on stdin (gh's "Press Enter"). Resolves with the exit code; null when stopped or timed out.
+ */
+function runTool(io: AuthIO, cmd: string, args: string[], opts: { env?: Record<string, string>; stdin?: string; onLine?: (line: string, write: (s: string) => void) => void; timeoutMs?: number } = {}): Promise<number | null> {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, {
+      env: { ...withoutTelemetry(process.env), ...opts.env },
+      stdio: io.attached && opts.stdin === undefined ? "inherit" : ["pipe", "pipe", "pipe"],
+      shell: process.platform === "win32",
+    })
+    const write = (s: string) => child.stdin?.write(s)
+    if (opts.stdin !== undefined) child.stdin?.end(opts.stdin)
+    let buf = ""
+    const onData = (chunk: Buffer) => {
+      buf += chunk.toString("utf8")
+      const parts = buf.split(/\r?\n/)
+      buf = parts.pop() || ""
+      for (const line of parts) {
+        if (!line.trim()) continue
+        if (opts.onLine) opts.onLine(line, write)
+        else io.say(line)
+      }
+    }
+    child.stdout?.on("data", onData)
+    child.stderr?.on("data", onData)
+    const timer = setTimeout(() => child.kill(), opts.timeoutMs ?? 10 * 60_000)
+    const stop = () => child.kill()
+    io.signal?.addEventListener("abort", stop, { once: true })
+    child.on("error", () => resolve(null))
+    child.on("close", (code) => {
+      clearTimeout(timer)
+      io.signal?.removeEventListener("abort", stop)
+      resolve(io.signal?.aborted ? null : code)
+    })
+  })
+}
+
+/** Save, put the values into this process too, and say so; a value exported in the terminal still wins next time. */
+async function finish(io: AuthIO, id: SystemId, rec: { via: Via; env: Record<string, string>; secrets: Record<string, string>; account?: string }, what: string): Promise<SignInResult> {
+  const shadowed = Object.keys({ ...rec.env, ...rec.secrets }).filter((n) => process.env[n] !== undefined && !fromSaved.has(n) && process.env[n] !== ({ ...rec.env, ...rec.secrets })[n])
+  const where = await saveSystem(id, rec)
+  for (const [n, v] of Object.entries({ ...rec.env, ...rec.secrets })) {
+    process.env[n] = v
+    fromSaved.add(n)
+  }
+  for (const n of Object.keys(rec.secrets)) savedSecrets.add(n)
+  const label = SYSTEMS.find((s) => s.id === id)!.label
+  const lines = [`Signed in to ${label}${rec.account ? ` as ${rec.account}` : ""} (${what}).`]
+  if (Object.keys(rec.secrets).length) lines.push(`Saved in ${where}.`)
+  if (shadowed.length) lines.push(`${shadowed.join(", ")} ${shadowed.length === 1 ? "is" : "are"} also set in this terminal or a .env file: a value exported in the terminal is used instead of this sign-in.`)
+  io.say(lines.join(" "), "ok")
+  return { ok: true, system: id, message: lines.join(" "), account: rec.account }
+}
+
+const describeError = (err: unknown) => (err as Error).message.replace(/\s+/g, " ").slice(0, 400)
+
+// ---- The systems ----
+
+async function signInAdo(io: AuthIO, cfg?: AppConfig): Promise<SignInResult> {
+  const names = envNames(cfg).ado
+  const org = adoOrgUrl(known(names.url, cfg?.sources.ado?.orgUrl) || (await ask(io, "Azure DevOps organization (a name like acme, or its URL)")))
+  const hasAz = Boolean(Bun.which("az"))
+  const cloud = /dev\.azure\.com|visualstudio\.com/.test(org)
+  let method = "pat"
+  if (hasAz && cloud) {
+    method =
+      (await io.choose({
+        title: `Sign in to Azure DevOps (${org})`,
+        detail: "Signing in with Microsoft uses the Azure CLI (az login) in your browser; nothing is saved by ForgeQE, and az renews the sign-in itself.",
+        options: [
+          { id: "az", label: "Sign in with Microsoft in the browser" },
+          { id: "pat", label: "Paste a personal access token" },
+          { id: "cancel", label: "Cancel" },
+        ],
+      })) || "cancel"
+    if (method === "cancel") throw new Cancelled()
+  }
+  const who = async (auth: string) => {
+    const { data } = await http<{ authenticatedUser?: { providerDisplayName?: string; properties?: { Account?: { $value?: string } } } }>(`${org}/_apis/connectionData`, { auth })
+    const u = data?.authenticatedUser
+    if (!u || /anonymous/i.test(u.providerDisplayName || "")) throw new Error("Azure DevOps did not accept the sign-in for this organization.")
+    return u.properties?.Account?.$value || u.providerDisplayName || undefined
+  }
+
+  if (method === "az") {
+    resetAzCliAuth()
+    let auth = azCliAuth()
+    if (!auth) {
+      io.say("Opening the Microsoft sign-in in your browser (az login)…")
+      const code = await runTool(io, "az", ["login", "--only-show-errors", "--output", "none"], { env: { AZURE_CORE_LOGIN_EXPERIENCE_V2: "off" } })
+      if (code !== 0) throw new Error("az login did not finish.")
+      resetAzCliAuth()
+      auth = azCliAuth()
+      if (!auth) throw new Error("az login finished, but the Azure CLI gave no token for Azure DevOps.")
+    }
+    let account: string | undefined
+    try {
+      account = await who(auth)
+    } catch (err) {
+      const tenant = await io.input({ label: `Azure DevOps did not accept the Azure CLI's account (${describeError(err)}). The organization may be in another Microsoft tenant: its domain or id (empty to stop)` })
+      if (!tenant?.trim()) throw new Error("The Azure CLI's account has no access to this organization. Try a personal access token instead.")
+      const code = await runTool(io, "az", ["login", "--tenant", tenant.trim(), "--only-show-errors", "--output", "none"], { env: { AZURE_CORE_LOGIN_EXPERIENCE_V2: "off" } })
+      resetAzCliAuth()
+      auth = code === 0 ? azCliAuth() : null
+      if (!auth) throw new Error("az login did not finish.")
+      account = await who(auth)
+    }
+    // Without a token, Azure DevOps calls and its MCP server use the Azure CLI's sign-in.
+    return finish(io, "azure_devops", { via: "azcli", env: { [names.url]: org }, secrets: {}, account }, "Azure CLI sign-in")
+  }
+
+  io.openUrl(`${org}/_usersSettings/tokens`)
+  io.say(
+    `Your browser shows ${org}/_usersSettings/tokens. Choose New Token, pick an expiry, and give it these scopes: Work Items (Read & write), Test Management (Read & write), Code (Read & write, for pull request reviews), Wiki (Read & write), Project and Team (Read), Build (Read). Then copy the token.`,
+  )
+  const token = await ask(io, "Paste the personal access token", { secret: true })
+  const account = await who(basic("", token))
+  return finish(io, "azure_devops", { via: "token", env: { [names.url]: org }, secrets: { [names.token]: token }, account }, "personal access token")
+}
+
+function ghSignedIn(): string | null {
+  const r = spawnSync("gh", ["api", "user", "--jq", ".login"], { encoding: "utf8", env: { ...withoutTelemetry(process.env), GH_PROMPT_DISABLED: "1" }, shell: process.platform === "win32" })
+  return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : null
+}
+
+async function signInGithub(io: AuthIO): Promise<SignInResult> {
+  if (!Bun.which("gh")) {
+    io.openUrl("https://cli.github.com/")
+    throw new Error("GitHub sign-in uses the GitHub CLI (gh), which is not installed. Install it (brew install gh, winget install GitHub.cli, or cli.github.com) and try again.")
+  }
+  const current = ghSignedIn()
+  if (current) {
+    const again = await io.choose({
+      title: `GitHub: signed in as ${current}`,
+      detail: "The GitHub CLI already has a sign-in, which ForgeQE uses for pull requests and CI secrets.",
+      options: [
+        { id: "keep", label: `Keep ${current}` },
+        { id: "again", label: "Sign in again" },
+      ],
+    })
+    if (again !== "again") return finish(io, "github", { via: "gh", env: {}, secrets: {}, account: current }, "GitHub CLI")
+  }
+  const method =
+    (await io.choose({
+      title: "Sign in to GitHub",
+      detail: "ForgeQE works through the GitHub CLI (gh), which keeps the sign-in in your system's credential store.",
+      options: [
+        { id: "web", label: "Sign in with GitHub in the browser" },
+        { id: "token", label: "Paste a personal access token" },
+        { id: "cancel", label: "Cancel" },
+      ],
+    })) || "cancel"
+  if (method === "cancel") throw new Cancelled()
+  let code: number | null
+  if (method === "web") {
+    let shown = false
+    code = await runTool(io, "gh", ["auth", "login", "--hostname", "github.com", "--git-protocol", "https", "--web", "--scopes", "repo,workflow,read:org"], {
+      onLine: (line, write) => {
+        const otp = /one-time code:\s*([A-Z0-9]{4}-[A-Z0-9]{4})/i.exec(line)?.[1]
+        if (otp && !shown) {
+          shown = true
+          io.say(`Your one-time code is ${otp}. Enter it on the GitHub page that opens in your browser.`)
+          io.openUrl("https://github.com/login/device")
+          write("\n")
+        } else if (!/Press Enter|Open this URL|github\.com\/login\/device/i.test(line)) io.say(line.replace(/^[!✓-]\s*/, ""))
+      },
+    })
+  } else {
+    io.openUrl("https://github.com/settings/tokens/new?scopes=repo,workflow,read:org&description=ForgeQE")
+    io.say("Your browser shows GitHub's new token page with the scopes ForgeQE needs (repo, workflow, read:org). Generate the token and copy it.")
+    const token = await ask(io, "Paste the GitHub token", { secret: true })
+    code = await runTool({ ...io, attached: false }, "gh", ["auth", "login", "--hostname", "github.com", "--git-protocol", "https", "--with-token"], { stdin: `${token}\n` })
+  }
+  const account = ghSignedIn()
+  if (code !== 0 || !account) throw new Error("The GitHub CLI did not finish signing in.")
+  return finish(io, "github", { via: "gh", env: {}, secrets: {}, account }, "GitHub CLI")
+}
+
+async function signInAtlassian(io: AuthIO, cfg: AppConfig | undefined, which: "jira" | "confluence"): Promise<SignInResult> {
+  const names = envNames(cfg)[which]
+  const label = which === "jira" ? "Jira" : "Confluence"
+  const configured = which === "jira" ? cfg?.sources.jira?.url : cfg?.sources.confluence?.url
+  const example = which === "jira" ? "https://acme.atlassian.net" : "https://acme.atlassian.net/wiki"
+  let url = siteRoot(known(names.url, configured) || (await ask(io, `${label} site URL (e.g. ${example})`)))
+  const cloud = isCloud(url)
+  if (which === "confluence" && cloud && !url.endsWith("/wiki")) url = `${url}/wiki`
+  const me = which === "jira" ? `${url}/rest/api/${cloud ? 3 : 2}/myself` : `${url}/rest/api/user/current`
+  const who = async (auth: string) => {
+    const { data } = await http<{ displayName?: string; emailAddress?: string; type?: string }>(me, { auth })
+    if (!data?.displayName || data.type === "anonymous") throw new Error(`${label} did not accept the token.`)
+    return data.displayName
+  }
+
+  // Confluence on the Jira Cloud site: the Jira account works, and the config reuses its variables.
+  const jira = envNames(cfg).jira
+  const jiraUrl = cfg?.sources.jira?.url || process.env[jira.url]
+  if (which === "confluence" && cloud && jiraUrl && new URL(jiraUrl).host === new URL(url).host && process.env[jira.email] && process.env[jira.token]) {
+    const account = await who(basic(process.env[jira.email]!, process.env[jira.token]!))
+    return finish(io, "confluence", { via: "token", env: { [names.url]: url }, secrets: {}, account }, "the Jira sign-in for this site")
+  }
+
+  if (cloud) {
+    const email = await ask(io, "Atlassian account email", { initial: process.env[names.email] || gitEmail() })
+    io.openUrl("https://id.atlassian.com/manage-profile/security/api-tokens")
+    io.say("Your browser shows your Atlassian API tokens. Choose Create API token, name it (for example ForgeQE), and copy it.")
+    const token = await ask(io, "Paste the API token", { secret: true })
+    const account = await who(basic(email, token))
+    return finish(io, which, { via: "token", env: { [names.url]: url, [names.email]: email }, secrets: { [names.token]: token }, account }, "API token")
+  }
+  io.openUrl(which === "jira" ? `${url}/secure/ViewProfile.jspa?selectedTab=com.atlassian.pats.pats-plugin:jira-user-personal-access-tokens` : `${url}/plugins/personalaccesstokens/usertokens.action`)
+  io.say(`Your browser shows your ${label} personal access tokens. Create a token and copy it.`)
+  const token = await ask(io, "Paste the personal access token", { secret: true })
+  const account = await who(`Bearer ${token}`)
+  return finish(io, which, { via: "token", env: { [names.url]: url }, secrets: { [names.token]: token }, account }, "personal access token")
+}
+
+async function signInTestrail(io: AuthIO, cfg?: AppConfig): Promise<SignInResult> {
+  const names = envNames(cfg).testrail
+  const url = httpsUrl(known(names.url, cfg?.sources.testrail?.url) || (await ask(io, "TestRail URL (e.g. https://acme.testrail.io)")))
+  const email = await ask(io, "TestRail email", { initial: process.env[names.email] || gitEmail() })
+  io.openUrl(`${url}/index.php?/mysettings`)
+  io.say("Your browser shows your TestRail settings. On the API Keys tab, add a key, save the settings, and copy the key.")
+  const key = await ask(io, "Paste the API key", { secret: true })
+  const { data } = await http<{ name?: string }>(`${url}/index.php?/api/v2/get_user_by_email&email=${encodeURIComponent(email)}`, { auth: basic(email, key) })
+  return finish(io, "testrail", { via: "token", env: { [names.url]: url, [names.email]: email }, secrets: { [names.token]: key }, account: data?.name || email }, "API key")
+}
+
+async function signInZephyr(io: AuthIO, cfg?: AppConfig): Promise<SignInResult> {
+  const names = envNames(cfg).zephyr
+  const url = (cfg?.sources.zephyr?.url || process.env[names.url] || "https://api.zephyrscale.smartbear.com/v2").replace(/\/+$/, "")
+  const jira = cfg?.sources.jira?.url || process.env.JIRA_URL
+  if (jira) io.openUrl(jira)
+  io.say("In Jira, open your profile picture menu, choose Zephyr API keys (Zephyr Scale Cloud), and generate a key. Then copy it.")
+  const token = await ask(io, "Paste the Zephyr Scale API key", { secret: true })
+  await http(`${url}/projects?maxResults=1`, { auth: `Bearer ${token}` })
+  const env = url === "https://api.zephyrscale.smartbear.com/v2" ? {} : { [names.url]: url }
+  return finish(io, "zephyr", { via: "token", env, secrets: { [names.token]: token } }, "API key")
+}
+
+async function signInQtest(io: AuthIO, cfg?: AppConfig): Promise<SignInResult> {
+  const names = envNames(cfg).qtest
+  const url = httpsUrl(known(names.url, cfg?.sources.qtest?.url) || (await ask(io, "qTest Manager URL (e.g. https://acme.qtestnet.com)")))
+  const project = String(cfg?.sources.qtest?.projectId || process.env[names.project] || (await ask(io, "qTest project id (the number in the project's URL)")))
+  io.openUrl(url)
+  io.say("In qTest Manager, open Resources, then API & SDK, and copy your API access token.")
+  const raw = await ask(io, "Paste the access token", { secret: true })
+  const token = raw.replace(/^bearer\s+/i, "")
+  const { data } = await http<{ name?: string }>(`${url}/api/v3/projects/${encodeURIComponent(project)}`, { auth: `Bearer ${token}` })
+  return finish(io, "qtest", { via: "token", env: { [names.url]: url, [names.project]: project }, secrets: { [names.token]: token }, account: data?.name ? `project ${data.name}` : undefined }, "access token")
+}
+
+async function signInXray(io: AuthIO, cfg?: AppConfig): Promise<SignInResult> {
+  const names = envNames(cfg).xray
+  const url = (cfg?.sources.xray.url || process.env[names.url] || "https://xray.cloud.getxray.app").replace(/\/+$/, "")
+  const jira = cfg?.sources.jira?.url || process.env.JIRA_URL
+  if (jira && !isCloud(jira)) throw new Error("Xray Server/Data Center uses the Jira sign-in: run the Jira sign-in instead.")
+  if (jira) io.openUrl(`${jira}/plugins/servlet/ac/com.xpandit.plugins.xray/xray-configuration-page`)
+  io.say("In Jira, open Apps, then Xray, Settings, API Keys, and create a key (it needs a Jira administrator). Copy the client id and the client secret.")
+  const id = await ask(io, "Paste the client id", { secret: true })
+  const secret = await ask(io, "Paste the client secret", { secret: true })
+  await http(`${url}/api/v2/authenticate`, { auth: "", body: { client_id: id, client_secret: secret } })
+  return finish(io, "xray", { via: "token", env: {}, secrets: { [names.id]: id, [names.secret]: secret } }, "API key")
+}
+
+/** Save one secret by its environment variable name: an LLM API key, a webhook URL, an SMTP or login password. */
+export async function saveNamedSecret(io: AuthIO, name: string): Promise<SignInResult> {
+  if (!ENV_NAME.test(name)) return { ok: false, system: name, message: `"${name}" is not an environment variable name.` }
+  try {
+    const value = await ask(io, `Paste the value for ${name}`, { secret: true })
+    const where = await saveSystem(`env:${name}`, { via: "token", env: {}, secrets: { [name]: value } })
+    process.env[name] = value
+    fromSaved.add(name)
+    savedSecrets.add(name)
+    const message = `${name} saved in ${where}.`
+    io.say(message, "ok")
+    return { ok: true, system: name, message }
+  } catch (err) {
+    const message = err instanceof Cancelled ? "Cancelled." : describeError(err)
+    io.say(message, err instanceof Cancelled ? "info" : "err")
+    return { ok: false, system: name, message }
+  }
+}
+
+/** Sign in to one system, asking which when `system` is empty. */
+export async function signIn(io: AuthIO, system: string | undefined, cfg?: AppConfig): Promise<SignInResult> {
+  let id = system ? findSystem(system) : null
+  if (system && !id) {
+    if (ENV_NAME.test(system) && system === system.toUpperCase()) return saveNamedSecret(io, system)
+    const message = `No system called "${system}". Choose one of: ${SYSTEMS.map((s) => s.id).join(", ")}, or give an environment variable name (like OPENAI_API_KEY) to save that secret.`
+    io.say(message, "err")
+    return { ok: false, system, message }
+  }
+  if (!id) {
+    const pick = await io.choose({
+      title: "Sign in to which system?",
+      options: [...SYSTEMS.map((s) => ({ id: s.id, label: s.label })), { id: "cancel", label: "Cancel" }],
+    })
+    if (!pick || pick === "cancel") return { ok: false, system: "", message: "Cancelled." }
+    id = pick as SystemId
+  }
+  try {
+    switch (id) {
+      case "azure_devops":
+        return await signInAdo(io, cfg)
+      case "github":
+        return await signInGithub(io)
+      case "jira":
+      case "confluence":
+        return await signInAtlassian(io, cfg, id)
+      case "testrail":
+        return await signInTestrail(io, cfg)
+      case "zephyr":
+        return await signInZephyr(io, cfg)
+      case "qtest":
+        return await signInQtest(io, cfg)
+      case "xray":
+        return await signInXray(io, cfg)
+    }
+    return { ok: false, system: id, message: "Unknown system." }
+  } catch (err) {
+    const message = err instanceof Cancelled || io.signal?.aborted ? "Cancelled." : `Sign-in failed: ${describeError(err)}`
+    io.say(message, err instanceof Cancelled ? "info" : "err")
+    return { ok: false, system: id, message }
+  }
+}
+
+/** Forget a saved sign-in; az and gh keep their own. */
+export async function signOut(system: string): Promise<string> {
+  const id = findSystem(system) || (ENV_NAME.test(system) ? `env:${system}` : null)
+  if (!id) return `No system called "${system}".`
+  const rec = readIndex().systems[id]
+  if (!(await forgetSystem(id))) return `Nothing is saved for ${system}.`
+  for (const n of [...Object.keys(rec?.env || {}), ...(rec?.secrets || [])]) {
+    if (fromSaved.has(n)) {
+      delete process.env[n]
+      fromSaved.delete(n)
+    }
+  }
+  const label = SYSTEMS.find((s) => s.id === id)?.label || system
+  if (rec?.via === "azcli") return `Forgot the ${label} sign-in. The Azure CLI is still signed in; run az logout to sign it out too.`
+  if (rec?.via === "gh") return `Forgot the ${label} sign-in. The GitHub CLI is still signed in; run gh auth logout to sign it out too.`
+  return `Forgot the ${label} sign-in and removed its secrets from ${storeName()}.`
+}
+
+/** One line per system: signed in how and as whom, set in the environment, or not set up. */
+export function authStatus(cfg?: AppConfig): string[] {
+  const n = envNames(cfg)
+  const saved = readIndex().systems
+  const source = (names: string[]) => {
+    const missing = names.filter((x) => !process.env[x])
+    if (missing.length) return null
+    return names.some((x) => fromSaved.has(x)) ? "saved sign-in" : "environment"
+  }
+  const row = (id: string, label: string, how: string | null) => {
+    const s = saved[id]
+    const who = s?.account ? ` as ${s.account}` : ""
+    return `${label.padEnd(14)}${how ? `${how}${who}` : "not signed in"}`
+  }
+  const adoUrl = cfg?.sources.ado?.orgUrl || process.env[n.ado.url]
+  const ado = adoUrl ? source([n.ado.token]) || (saved.azure_devops?.via === "azcli" && azCliAuth() ? "Azure CLI sign-in" : null) : null
+  const ghUser = Bun.which("gh") ? ghSignedIn() : null
+  const jiraUrl = cfg?.sources.jira?.url || process.env[n.jira.url]
+  const jira = jiraUrl ? source(isCloud(jiraUrl) ? [n.jira.email, n.jira.token] : [n.jira.token]) : null
+  const conf = cfg?.sources.confluence
+  const confHow = conf ? source(conf.cloud ? [conf.emailEnv, conf.tokenEnv] : [conf.tokenEnv]) : null
+  const lines = [
+    row("azure_devops", "Azure DevOps", ado && `${ado}, ${adoUrl}`),
+    `${"GitHub".padEnd(14)}${ghUser ? `GitHub CLI as ${ghUser}` : Bun.which("gh") ? "not signed in" : "GitHub CLI (gh) not installed"}`,
+    row("jira", "Jira", jira && `${jira}, ${jiraUrl}`),
+    row("confluence", "Confluence", confHow && `${confHow}, ${conf!.url}`),
+    row("testrail", "TestRail", cfg?.sources.testrail || process.env[n.testrail.url] ? source([n.testrail.email, n.testrail.token]) : null),
+    row("zephyr", "Zephyr Scale", source([n.zephyr.token])),
+    row("qtest", "qTest", cfg?.sources.qtest || process.env[n.qtest.url] ? source([n.qtest.token]) : null),
+    row("xray", "Xray Cloud", source([n.xray.id, n.xray.secret])),
+  ]
+  const extra = Object.keys(saved).filter((k) => k.startsWith("env:")).map((k) => k.slice(4))
+  if (extra.length) lines.push(`${"Other secrets".padEnd(14)}${extra.join(", ")}`)
+  lines.push("", `Secrets are kept in ${storeName()}. A variable exported in the terminal is used before a saved sign-in, and a saved sign-in before a .env file.`)
+  return lines
+}

package/src/auth/store.ts

@@ -0,0 +1,170 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { forgeqeHome } from "../tools.ts"
+
+/**
+ * Credentials saved by `forgeqe auth login`. Secrets (tokens, API keys, passwords) go to the operating system's
+ * credential store (Keychain, Credential Manager, Secret Service) under the service "forgeqe", one entry per
+ * environment variable name. Where there is no store (a headless Linux box without Secret Service), or with
+ * FORGEQE_SECRET_STORE=file, they go to ~/.forgeqe/credentials.json, readable only by the user.
+ * ~/.forgeqe/auth.json says what is saved: per system, the non-secret values (URLs, emails) and the secret names.
+ */
+
+const SERVICE = "forgeqe"
+/** The service before ForgeQE was renamed from WebPilot: sign-ins saved under it are still read. */
+const LEGACY_SERVICE = "webpilot"
+
+export type Via = "token" | "azcli" | "gh"
+
+export type SavedSystem = {
+  via: Via
+  /** Non-secret values by environment variable name (site URLs, emails, project ids). */
+  env: Record<string, string>
+  /** Environment variable names whose values are in the secret store. */
+  secrets: string[]
+  /** Who the credentials belong to, as the system reported it when they were checked. */
+  account?: string
+  savedAt: string
+}
+
+export type AuthIndex = { systems: Record<string, SavedSystem> }
+
+const indexFile = () => path.join(forgeqeHome(), "auth.json")
+const fileStore = () => path.join(forgeqeHome(), "credentials.json")
+
+export function readIndex(): AuthIndex {
+  try {
+    const data = JSON.parse(readFileSync(indexFile(), "utf8")) as AuthIndex
+    return { systems: data?.systems && typeof data.systems === "object" ? data.systems : {} }
+  } catch {
+    return { systems: {} }
+  }
+}
+
+function writePrivate(file: string, data: unknown) {
+  mkdirSync(path.dirname(file), { recursive: true })
+  writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 })
+  try {
+    chmodSync(file, 0o600)
+  } catch {}
+}
+
+function writeIndex(index: AuthIndex) {
+  writePrivate(indexFile(), index)
+}
+
+function readFileSecrets(): Record<string, string> {
+  try {
+    return JSON.parse(readFileSync(fileStore(), "utf8")) as Record<string, string>
+  } catch {
+    return {}
+  }
+}
+
+const useFile = () => /^file$/i.test(process.env.FORGEQE_SECRET_STORE || "") || typeof Bun.secrets?.get !== "function"
+
+/** Where secrets are kept on this machine, for status lines. */
+export function storeName(): string {
+  if (useFile()) return fileStore()
+  return process.platform === "darwin" ? "the macOS Keychain" : process.platform === "win32" ? "Windows Credential Manager" : "the Secret Service keyring"
+}
+
+export async function getSecret(name: string): Promise<string | null> {
+  if (!useFile()) {
+    try {
+      const value = (await Bun.secrets.get({ service: SERVICE, name })) || (await Bun.secrets.get({ service: LEGACY_SERVICE, name }))
+      if (value) return value
+    } catch {
+      // No usable OS store: fall through to the file.
+    }
+  }
+  return readFileSecrets()[name] ?? null
+}
+
+/** Saves to the OS store, or to the private file when there is none. Returns where it went. */
+export async function setSecret(name: string, value: string): Promise<string> {
+  if (!useFile()) {
+    try {
+      await Bun.secrets.set({ service: SERVICE, name, value })
+      return storeName()
+    } catch {
+      // No usable OS store: use the file.
+    }
+  }
+  writePrivate(fileStore(), { ...readFileSecrets(), [name]: value })
+  return fileStore()
+}
+
+export async function deleteSecret(name: string): Promise<void> {
+  if (!useFile()) {
+    for (const service of [SERVICE, LEGACY_SERVICE]) {
+      try {
+        await Bun.secrets.delete({ service, name })
+      } catch {}
+    }
+  }
+  const all = readFileSecrets()
+  if (name in all) {
+    delete all[name]
+    writePrivate(fileStore(), all)
+  }
+}
+
+/** Record a system's credentials: secrets to the store, the rest to auth.json. Replaces what was saved for it. */
+export async function saveSystem(id: string, rec: { via: Via; env: Record<string, string>; secrets: Record<string, string>; account?: string }): Promise<string> {
+  const index = readIndex()
+  const old = index.systems[id]
+  for (const name of old?.secrets || []) if (!(name in rec.secrets)) await deleteSecret(name)
+  let where = storeName()
+  for (const [name, value] of Object.entries(rec.secrets)) where = await setSecret(name, value)
+  index.systems[id] = { via: rec.via, env: rec.env, secrets: Object.keys(rec.secrets), ...(rec.account ? { account: rec.account } : {}), savedAt: new Date().toISOString() }
+  writeIndex(index)
+  return where
+}
+
+/** Forget a system: its secrets and its entry. Secrets another system still uses (Jira and Confluence) stay. */
+export async function forgetSystem(id: string): Promise<boolean> {
+  const index = readIndex()
+  const old = index.systems[id]
+  if (!old) return false
+  delete index.systems[id]
+  const kept = new Set(Object.values(index.systems).flatMap((s) => s.secrets))
+  for (const name of old.secrets) if (!kept.has(name)) await deleteSecret(name)
+  writeIndex(index)
+  return true
+}
+
+/** Names whose values came from saved credentials in this process, for status. */
+export const fromSaved = new Set<string>()
+/** The secret ones among them: hidden from the shell commands agents run. */
+export const savedSecrets = new Set<string>()
+
+/**
+ * Put saved credentials into process.env, under the names the config reads, for every name the environment does not
+ * set already. Runs before .env files are read, so the order is: this terminal's environment, then saved sign-ins,
+ * then .env files.
+ */
+export async function applySavedCredentials(env: NodeJS.ProcessEnv = process.env): Promise<string[]> {
+  if (/^(0|off|false|no)$/i.test(env.FORGEQE_SAVED_AUTH || "") || !existsSync(indexFile())) return []
+  const applied: string[] = []
+  for (const sys of Object.values(readIndex().systems)) {
+    for (const [name, value] of Object.entries(sys.env || {})) {
+      if (env[name] === undefined && value) {
+        env[name] = value
+        applied.push(name)
+      }
+    }
+    for (const name of sys.secrets || []) {
+      if (env[name] !== undefined) continue
+      const value = await getSecret(name)
+      if (value) {
+        env[name] = value
+        applied.push(name)
+        savedSecrets.add(name)
+      }
+    }
+  }
+  for (const n of applied) fromSaved.add(n)
+  return applied
+}