redmine-context 1.0.0

package/dist/config/doctor.js

@@ -0,0 +1,260 @@
+/**
+ * Diagnóstico dos binários de mídia (M3-11 #53, M4-01 #57, ADR-002).
+ *
+ * O núcleo do comando `doctor`: detecta a presença dos binários externos que a
+ * extração local de mídia precisa (`tesseract` do OCR, `ffmpeg` do vídeo,
+ * `whisper.cpp` da transcrição) e, quando ausentes, devolve uma instrução de
+ * instalação ADEQUADA AO SO. Também reporta o status do modelo GGUF do
+ * whisper.cpp no cache esperado.
+ *
+ * DECISÕES (todas exercitadas por testes):
+ * - PLATAFORMA INJETÁVEL: cada hint depende de `platform`, injetável para testar
+ *   os três SOs num único host — o default é `process.platform`.
+ * - REUSO DA DETECÇÃO DOS EXTRATORES: localização e leitura de versão
+ *   (`findTesseract`/`findFfmpeg`/`findWhisper` + `detect*Version`) vêm dos
+ *   módulos de extração (ADR-002) — não reimplementadas, e injetáveis para manter
+ *   os testes isolados do filesystem/binário reais.
+ * - DEGRADAÇÃO GRACIOSA: nunca lança; um binário ou modelo ausente é um estado
+ *   NORMAL (`found: false`) reportado com a dica — o `doctor` é justamente o que
+ *   orienta o usuário a instalar (ADR-002).
+ * - OPT-IN `--download-binaries` SÓ ONDE HÁ ARTEFATO OFICIAL: ffmpeg (BtbN) e
+ *   whisper.cpp (releases) mencionam o download automático futuro; tesseract
+ *   (sem artefato estático) só instrui a instalação por SO (ADR-002).
+ * - MODELO É UMA ENTRADA DO DIAGNÓSTICO: o status do GGUF entra na MESMA lista
+ *   de {@link BinaryDiagnosis} que as superfícies (CLI/TUI) já iteram — nova
+ *   entrada exibida SEM mudança de código nelas.
+ */
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { detectFfmpegVersion as defaultDetectFfmpegVersion, findFfmpeg as defaultFindFfmpeg, } from '../extract/ffmpeg.js';
+import { detectPdftotextVersion as defaultDetectPdftotextVersion, findPdftotext as defaultFindPdftotext, } from '../extract/pdf.js';
+import { detectTesseractVersion as defaultDetectTesseractVersion, findTesseract as defaultFindTesseract, } from '../extract/tesseract.js';
+import { findWhisper as defaultFindWhisper, whisperModelDir as defaultWhisperModelDir, } from '../extract/whisper.js';
+/** Path convencional do tesseract no Windows citado no hint (ADR-002). */
+const WINDOWS_CONVENTIONAL_PATH = 'C:\\Program Files\\Tesseract-OCR';
+/** Menção padronizada ao opt-in de download automático (ADR-002; o download é a #58+). */
+const DOWNLOAD_OPT_IN = 'ou, no futuro, o opt-in `--download-binaries`';
+/**
+ * Instrução de instalação do `tesseract` para um SO. Pura e injetável — cada
+ * plataforma gera uma dica testável isoladamente (ADR-002). SEM menção a
+ * `--download-binaries`: o tesseract não tem artefato estático oficial.
+ *
+ * @param platform - Plataforma alvo (`process.platform`).
+ * @returns Comando/instrução de instalação adequado ao SO.
+ * @example
+ * tesseractInstallHint('darwin'); // 'brew install tesseract tesseract-lang'
+ */
+export function tesseractInstallHint(platform) {
+    switch (platform) {
+        case 'darwin':
+            // tesseract-lang traz o traineddata de 'por' (o default do projeto é por+eng).
+            return 'brew install tesseract tesseract-lang';
+        case 'win32':
+            return `winget install UB-Mannheim.TesseractOCR (ou instale em ${WINDOWS_CONVENTIONAL_PATH})`;
+        default:
+            // Reason: Linux e demais UNIX — as duas famílias de gerenciador mais comuns.
+            return 'sudo apt install tesseract-ocr  (ou: sudo dnf install tesseract)';
+    }
+}
+/**
+ * Instrução de instalação do `pdftotext` (poppler) para um SO. Pura e injetável —
+ * cada plataforma gera uma dica testável isoladamente (ADR-002).
+ *
+ * @param platform - Plataforma alvo (`process.platform`).
+ * @returns Comando/instrução de instalação adequado ao SO.
+ * @example
+ * pdftotextInstallHint('darwin'); // 'brew install poppler'
+ */
+export function pdftotextInstallHint(platform) {
+    switch (platform) {
+        case 'darwin':
+            return 'brew install poppler';
+        case 'win32':
+            // Reason: os builds Windows do poppler vêm do repackage oschwartz10612 —
+            // disponível tanto no winget quanto no chocolatey.
+            return 'winget install oschwartz10612.Poppler (ou: choco install poppler)';
+        default:
+            // Reason: Linux e demais UNIX — as duas famílias de gerenciador mais comuns.
+            return 'sudo apt install poppler-utils  (ou: sudo dnf install poppler-utils)';
+    }
+}
+/**
+ * Instrução de instalação do `ffmpeg` por SO, COM menção ao opt-in
+ * `--download-binaries` e às builds estáticas BtbN (artefato oficial; ADR-002).
+ *
+ * @param platform - Plataforma alvo (`process.platform`).
+ * @returns Instrução de instalação/obtenção adequada ao SO.
+ * @example
+ * ffmpegInstallHint('darwin'); // 'brew install ffmpeg ...'
+ */
+export function ffmpegInstallHint(platform) {
+    const btbn = 'builds estáticos BtbN (github.com/BtbN/FFmpeg-Builds)';
+    switch (platform) {
+        case 'darwin':
+            return `brew install ffmpeg (${DOWNLOAD_OPT_IN}; ${btbn})`;
+        case 'win32':
+            return `winget install Gyan.FFmpeg (${DOWNLOAD_OPT_IN}; ${btbn})`;
+        default:
+            return `sudo apt install ffmpeg  (ou: sudo dnf install ffmpeg; ${DOWNLOAD_OPT_IN}; ${btbn})`;
+    }
+}
+/**
+ * Instrução de instalação do whisper.cpp por SO, COM menção ao opt-in
+ * `--download-binaries` e às releases do GitHub (artefato oficial; ADR-002).
+ *
+ * @param platform - Plataforma alvo (`process.platform`).
+ * @returns Instrução de instalação/obtenção adequada ao SO.
+ * @example
+ * whisperInstallHint('darwin'); // 'brew install whisper-cpp ...'
+ */
+export function whisperInstallHint(platform) {
+    const releases = 'releases em github.com/ggml-org/whisper.cpp/releases';
+    switch (platform) {
+        case 'darwin':
+            return `brew install whisper-cpp (${DOWNLOAD_OPT_IN}; ${releases})`;
+        case 'win32':
+            return `baixe as ${releases} (${DOWNLOAD_OPT_IN})`;
+        default:
+            return `brew install whisper-cpp ou compile o whisper.cpp (${DOWNLOAD_OPT_IN}; ${releases})`;
+    }
+}
+/** Extensão dos modelos do whisper.cpp no cache. */
+const GGUF_EXTENSION = '.gguf';
+/**
+ * Monta um {@link BinaryDiagnosis} sem injetar chaves `undefined` (respeita
+ * `exactOptionalPropertyTypes`): `path`/`version` só entram quando presentes.
+ *
+ * @param name - Nome do item diagnosticado.
+ * @param installHint - Instrução de instalação/obtenção.
+ * @param found - Caminho/versão quando encontrado; `undefined` = ausente.
+ * @returns O diagnóstico tipado.
+ */
+function makeDiagnosis(name, installHint, found) {
+    if (found === undefined) {
+        return { name, found: false, installHint };
+    }
+    const base = { name, found: true, path: found.path, installHint };
+    return found.version !== undefined ? { ...base, version: found.version } : base;
+}
+/**
+ * Diagnostica o `tesseract`: localiza-o, lê a versão quando presente e anexa a
+ * instrução de instalação do SO.
+ *
+ * @param platform - SO para o hint.
+ * @param find - Localizador do binário.
+ * @param detectVersion - Leitor de versão.
+ * @returns O diagnóstico do tesseract.
+ */
+async function diagnoseTesseract(platform, find, detectVersion) {
+    const installHint = tesseractInstallHint(platform);
+    const located = find();
+    if (located === undefined) {
+        return makeDiagnosis('tesseract', installHint, undefined);
+    }
+    const version = await detectVersion(located.path);
+    return makeDiagnosis('tesseract', installHint, { path: located.path, version });
+}
+/**
+ * Diagnostica o `ffmpeg`: localiza-o, lê a versão (1ª linha de `ffmpeg -version`)
+ * quando presente e anexa a instrução por SO (com opt-in/BtbN).
+ *
+ * @param platform - SO para o hint.
+ * @param find - Localizador do binário.
+ * @param detectVersion - Leitor de versão.
+ * @returns O diagnóstico do ffmpeg.
+ */
+async function diagnoseFfmpeg(platform, find, detectVersion) {
+    const installHint = ffmpegInstallHint(platform);
+    const located = find();
+    if (located === undefined) {
+        return makeDiagnosis('ffmpeg', installHint, undefined);
+    }
+    const version = await detectVersion(located.path);
+    return makeDiagnosis('ffmpeg', installHint, { path: located.path, version });
+}
+/** Diagnostica o `pdftotext` (poppler): localização, versão e hint por SO. */
+async function diagnosePdftotext(platform, locate, detectVersion) {
+    const hint = pdftotextInstallHint(platform);
+    const located = locate();
+    if (located === undefined) {
+        return { name: 'pdftotext', found: false, installHint: hint };
+    }
+    const version = await detectVersion(located.path);
+    const base = { name: 'pdftotext', found: true, path: located.path, installHint: hint };
+    return version !== undefined ? { ...base, version } : base;
+}
+/**
+ * Diagnostica o `whisper.cpp`: localiza QUALQUER binário conhecido (`whisper-cli`
+ * / `whisper-cpp` / `main`) e reporta o caminho encontrado (que revela qual).
+ * Sem versão: o whisper.cpp não tem `--version` estável — o path é a evidência.
+ *
+ * @param platform - SO para o hint.
+ * @param find - Localizador do binário.
+ * @returns O diagnóstico do whisper.cpp (sempre sem `version`).
+ */
+function diagnoseWhisper(platform, find) {
+    const installHint = whisperInstallHint(platform);
+    const located = find();
+    if (located === undefined) {
+        return makeDiagnosis('whisper.cpp', installHint, undefined);
+    }
+    // Reason: sem versão legível — o path (que inclui `whisper-cli`/`main`) é a
+    // evidência da presença e de QUAL binário está instalado (ADR-002).
+    return makeDiagnosis('whisper.cpp', installHint, { path: located.path });
+}
+/**
+ * Diagnostica o modelo GGUF do whisper.cpp: verifica se há ao menos um `.gguf`
+ * no diretório de cache canônico ({@link defaultWhisperModelDir}). Nunca lança:
+ * diretório inexistente/ilegível conta como ausente (degradação graciosa).
+ *
+ * @param modelDir - Diretório canônico dos modelos.
+ * @param listDir - Lista os arquivos do diretório.
+ * @returns O diagnóstico do modelo (path = arquivo GGUF quando presente).
+ */
+function diagnoseWhisperModel(modelDir, listDir) {
+    const hint = `baixe um modelo GGUF (ex.: ggml-base) para ${modelDir} (${DOWNLOAD_OPT_IN}, via #58)`;
+    let gguf;
+    try {
+        gguf = listDir(modelDir).find((file) => file.toLowerCase().endsWith(GGUF_EXTENSION));
+    }
+    catch {
+        // Reason: diretório ainda não criado (setup fresco) ou ilegível — ausente.
+        gguf = undefined;
+    }
+    if (gguf === undefined) {
+        return makeDiagnosis('modelo whisper (GGUF)', hint, undefined);
+    }
+    return makeDiagnosis('modelo whisper (GGUF)', hint, { path: join(modelDir, gguf) });
+}
+/**
+ * Diagnostica os binários e o modelo de mídia: `tesseract`, `ffmpeg`,
+ * `whisper.cpp` e o modelo GGUF. Cada um localizado (PATH + locais convencionais
+ * / cache), com versão quando legível, sempre com a instrução de instalação do
+ * SO. A ordem é estável (a mesma exibida por CLI/TUI).
+ *
+ * @param options - Deps injetáveis (plataforma, localizadores, versões, modelo).
+ *   Ver {@link DiagnoseBinariesOptions}.
+ * @returns A lista de {@link BinaryDiagnosis} na ordem
+ *   `[tesseract, pdftotext, ffmpeg, whisper.cpp, modelo]`.
+ * @example
+ * for (const item of await diagnoseBinaries()) {
+ *   if (!item.found) logger.warn(item.installHint);
+ * }
+ */
+export async function diagnoseBinaries(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const findTesseract = options.findTesseract ?? defaultFindTesseract;
+    const detectTesseractVersion = options.detectTesseractVersion ?? defaultDetectTesseractVersion;
+    const findFfmpeg = options.findFfmpeg ?? defaultFindFfmpeg;
+    const detectFfmpegVersion = options.detectFfmpegVersion ?? defaultDetectFfmpegVersion;
+    const findWhisper = options.findWhisper ?? defaultFindWhisper;
+    const modelDir = (options.whisperModelDir ?? defaultWhisperModelDir)();
+    const listDir = options.listDir ?? ((dir) => readdirSync(dir));
+    return [
+        await diagnoseTesseract(platform, findTesseract, detectTesseractVersion),
+        await diagnosePdftotext(platform, options.findPdftotext ?? defaultFindPdftotext, options.detectPdftotextVersion ?? defaultDetectPdftotextVersion),
+        await diagnoseFfmpeg(platform, findFfmpeg, detectFfmpegVersion),
+        diagnoseWhisper(platform, findWhisper),
+        diagnoseWhisperModel(modelDir, listDir),
+    ];
+}

package/dist/config/index.d.ts

@@ -0,0 +1,6 @@
+export declare const MODULE_NAME: "config";
+export { loginWithPassword, validateApiKey, RedmineLoginError, type LoginOptions, type LoginResult, type ValidateApiKeyOptions, } from './login.js';
+export { CascadingCredentialStore, CredentialStoreError, EnvCredentialStore, FileCredentialStore, MigratingCredentialCascade, createCredentialCascade, defaultCredentialsPath, describeCredentialSource, normalizeInstanceUrl, resolveApiKey, type CredentialCascadeOptions, type CredentialSourceKind, type CredentialStore, type EnvCredentialStoreOptions, type FileCredentialStoreOptions, } from './credentials.js';
+export { KeyringCredentialStore, type KeyringCredentialStoreOptions, type KeyringEntry, type KeyringModule, type KeyringModuleLoader, } from './keyring.js';
+export { FileSettingsStore, defaultSettingsPath, defaultSettingsStore, resolveInstanceUrl, type FileSettingsStoreOptions, type InstanceUrlOrigin, type ResolvedInstanceUrl, type Settings, type SettingsStore, } from './settings.js';
+export { diagnoseBinaries, tesseractInstallHint, pdftotextInstallHint, ffmpegInstallHint, whisperInstallHint, type BinaryDiagnosis, type DiagnoseBinariesOptions, } from './doctor.js';

package/dist/config/index.js

@@ -0,0 +1,6 @@
+export const MODULE_NAME = 'config';
+export { loginWithPassword, validateApiKey, RedmineLoginError, } from './login.js';
+export { CascadingCredentialStore, CredentialStoreError, EnvCredentialStore, FileCredentialStore, MigratingCredentialCascade, createCredentialCascade, defaultCredentialsPath, describeCredentialSource, normalizeInstanceUrl, resolveApiKey, } from './credentials.js';
+export { KeyringCredentialStore, } from './keyring.js';
+export { FileSettingsStore, defaultSettingsPath, defaultSettingsStore, resolveInstanceUrl, } from './settings.js';
+export { diagnoseBinaries, tesseractInstallHint, pdftotextInstallHint, ffmpegInstallHint, whisperInstallHint, } from './doctor.js';

package/dist/config/keyring.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Credential store da api_key no keychain nativo do SO (M2-14).
+ *
+ * Implementa a mesma interface {@link CredentialStore} do M1 sobre o keychain do
+ * sistema operacional via `@napi-rs/keyring` (macOS Keychain, Windows Credential
+ * Manager, libsecret no Linux). O pacote distribui binários pré-compilados pelas
+ * próprias `optionalDependencies` por plataforma, então `node-gyp` nunca é
+ * acionado numa instalação limpa.
+ *
+ * O módulo nativo é carregado sob demanda por import dinâmico com `try/catch`: se
+ * não houver prebuild para a plataforma (ex.: uma variante `musl` sem binário), o
+ * carregamento falha de forma controlada — o store fica indisponível (`get`
+ * devolve `undefined`; `set`/`delete` viram no-op) e um único aviso é emitido via
+ * logger, permitindo que a cascata siga para o arquivo. Erros do keychain em
+ * runtime (ler/gravar/remover) também degradam sem derrubar o processo.
+ *
+ * O service usado é `redmine-context` e o account é a instância normalizada por
+ * {@link normalizeInstanceUrl}, mantendo a mesma chave estável do store de
+ * arquivo. A api_key nunca é logada nem incluída em mensagens de aviso.
+ *
+ * Esta issue apenas introduz o store e suas exportações; a ordem da cascata
+ * (keychain → arquivo → env) e a migração ficam para o M2-15 (#38).
+ */
+import type { Logger } from '../client/index.js';
+import { type CredentialStore } from './credentials.js';
+/**
+ * Superfície mínima da `Entry` de `@napi-rs/keyring` usada por este store.
+ * Declarada localmente para permitir mock nos testes e desacoplar do tipo nativo.
+ */
+export interface KeyringEntry {
+    /** Recupera o segredo; `null` (ou erro `NoEntry`) quando não existe. */
+    getPassword(): string | null;
+    /** Persiste (ou substitui) o segredo desta entrada. */
+    setPassword(password: string): void;
+    /** Remove a credencial; `false` quando não havia o que remover. */
+    deleteCredential(): boolean;
+}
+/** Superfície mínima do módulo `@napi-rs/keyring`: apenas o construtor `Entry`. */
+export interface KeyringModule {
+    /** Construtor de uma entrada para `(service, account)`. */
+    Entry: new (service: string, account: string) => KeyringEntry;
+}
+/**
+ * Carregador do módulo nativo. Injetável para testes; o padrão faz o import
+ * dinâmico de `@napi-rs/keyring`.
+ */
+export type KeyringModuleLoader = () => Promise<KeyringModule>;
+/** Opções do {@link KeyringCredentialStore}. */
+export interface KeyringCredentialStoreOptions {
+    /** Service registrado no keychain; default `redmine-context`. */
+    service?: string;
+    /** Logger para o aviso único de indisponibilidade/degradação; default no-op. */
+    logger?: Logger;
+    /** Carregador do módulo nativo; default import dinâmico (injetável em testes). */
+    loader?: KeyringModuleLoader;
+}
+/**
+ * Implementação de {@link CredentialStore} sobre o keychain nativo do SO.
+ *
+ * Todas as operações degradam de forma segura: indisponibilidade do módulo ou
+ * erros de runtime do keychain nunca derrubam o processo — `get` devolve
+ * `undefined` e `set`/`delete` viram no-op, com aviso via logger.
+ */
+export declare class KeyringCredentialStore implements CredentialStore {
+    private readonly service;
+    private readonly logger;
+    private readonly loader;
+    /** Import memoizado: resolve para o módulo ou `undefined` se indisponível. */
+    private modulePromise;
+    /** Garante que o aviso de indisponibilidade seja emitido uma única vez. */
+    private unavailableWarned;
+    /** @param options - Ver {@link KeyringCredentialStoreOptions}. */
+    constructor(options?: KeyringCredentialStoreOptions);
+    /**
+     * Indica se o keychain nativo está disponível nesta plataforma (há prebuild e
+     * o módulo carrega). Usado pela cascata M2 para decidir a migração e o destino
+     * das escritas. O carregamento é memoizado, então o custo é pago uma só vez.
+     *
+     * @returns `true` se o módulo nativo carregou; `false` se indisponível.
+     */
+    isAvailable(): Promise<boolean>;
+    /** @inheritdoc */
+    get(instance: string): Promise<string | undefined>;
+    /** @inheritdoc */
+    set(instance: string, apiKey: string): Promise<void>;
+    /** @inheritdoc */
+    delete(instance: string): Promise<void>;
+    /** Constrói a `Entry` para a instância, ou `undefined` se indisponível. */
+    private entryFor;
+    /** Carrega (uma vez) o módulo nativo; `undefined` se não houver prebuild. */
+    private load;
+    /** Emite (uma única vez) o aviso de módulo indisponível. */
+    private warnUnavailable;
+    /** Emite um aviso de degradação de runtime — sem nunca expor a api_key. */
+    private warnRuntime;
+}

package/dist/config/keyring.js

@@ -0,0 +1,158 @@
+/**
+ * Credential store da api_key no keychain nativo do SO (M2-14).
+ *
+ * Implementa a mesma interface {@link CredentialStore} do M1 sobre o keychain do
+ * sistema operacional via `@napi-rs/keyring` (macOS Keychain, Windows Credential
+ * Manager, libsecret no Linux). O pacote distribui binários pré-compilados pelas
+ * próprias `optionalDependencies` por plataforma, então `node-gyp` nunca é
+ * acionado numa instalação limpa.
+ *
+ * O módulo nativo é carregado sob demanda por import dinâmico com `try/catch`: se
+ * não houver prebuild para a plataforma (ex.: uma variante `musl` sem binário), o
+ * carregamento falha de forma controlada — o store fica indisponível (`get`
+ * devolve `undefined`; `set`/`delete` viram no-op) e um único aviso é emitido via
+ * logger, permitindo que a cascata siga para o arquivo. Erros do keychain em
+ * runtime (ler/gravar/remover) também degradam sem derrubar o processo.
+ *
+ * O service usado é `redmine-context` e o account é a instância normalizada por
+ * {@link normalizeInstanceUrl}, mantendo a mesma chave estável do store de
+ * arquivo. A api_key nunca é logada nem incluída em mensagens de aviso.
+ *
+ * Esta issue apenas introduz o store e suas exportações; a ordem da cascata
+ * (keychain → arquivo → env) e a migração ficam para o M2-15 (#38).
+ */
+import { normalizeInstanceUrl } from './credentials.js';
+/** Especificador do módulo nativo carregado dinamicamente. */
+const KEYRING_MODULE = '@napi-rs/keyring';
+/** Service padrão registrado no keychain do SO. */
+const DEFAULT_SERVICE = 'redmine-context';
+/** Logger no-op: usado quando nenhum logger é injetado. */
+const noopLogger = { warn: () => undefined };
+/** Loader padrão: import dinâmico do binding nativo. */
+const defaultLoader = async () => {
+    const mod = await import(KEYRING_MODULE);
+    return mod;
+};
+/** Verifica se um erro do keyring é "entrada não encontrada" (NoEntry). */
+function isNoEntry(cause) {
+    const message = cause instanceof Error ? cause.message.toLowerCase() : String(cause).toLowerCase();
+    return message.includes('no matching entry') || message.includes('noentry');
+}
+/**
+ * Implementação de {@link CredentialStore} sobre o keychain nativo do SO.
+ *
+ * Todas as operações degradam de forma segura: indisponibilidade do módulo ou
+ * erros de runtime do keychain nunca derrubam o processo — `get` devolve
+ * `undefined` e `set`/`delete` viram no-op, com aviso via logger.
+ */
+export class KeyringCredentialStore {
+    service;
+    logger;
+    loader;
+    /** Import memoizado: resolve para o módulo ou `undefined` se indisponível. */
+    modulePromise;
+    /** Garante que o aviso de indisponibilidade seja emitido uma única vez. */
+    unavailableWarned = false;
+    /** @param options - Ver {@link KeyringCredentialStoreOptions}. */
+    constructor(options = {}) {
+        this.service = options.service ?? DEFAULT_SERVICE;
+        this.logger = options.logger ?? noopLogger;
+        this.loader = options.loader ?? defaultLoader;
+    }
+    /**
+     * Indica se o keychain nativo está disponível nesta plataforma (há prebuild e
+     * o módulo carrega). Usado pela cascata M2 para decidir a migração e o destino
+     * das escritas. O carregamento é memoizado, então o custo é pago uma só vez.
+     *
+     * @returns `true` se o módulo nativo carregou; `false` se indisponível.
+     */
+    async isAvailable() {
+        return (await this.load()) !== undefined;
+    }
+    /** @inheritdoc */
+    async get(instance) {
+        const entry = await this.entryFor(instance);
+        if (entry === undefined) {
+            return undefined;
+        }
+        try {
+            const value = entry.getPassword();
+            return value !== null && value.length > 0 ? value : undefined;
+        }
+        catch (cause) {
+            if (isNoEntry(cause)) {
+                return undefined;
+            }
+            this.warnRuntime('ler', cause);
+            return undefined;
+        }
+    }
+    /** @inheritdoc */
+    async set(instance, apiKey) {
+        const entry = await this.entryFor(instance);
+        if (entry === undefined) {
+            return;
+        }
+        try {
+            entry.setPassword(apiKey);
+        }
+        catch (cause) {
+            this.warnRuntime('gravar', cause);
+        }
+    }
+    /** @inheritdoc */
+    async delete(instance) {
+        const entry = await this.entryFor(instance);
+        if (entry === undefined) {
+            return;
+        }
+        try {
+            entry.deleteCredential();
+        }
+        catch (cause) {
+            // Remover uma entrada ausente é um no-op esperado, não um erro.
+            if (isNoEntry(cause)) {
+                return;
+            }
+            this.warnRuntime('remover', cause);
+        }
+    }
+    /** Constrói a `Entry` para a instância, ou `undefined` se indisponível. */
+    async entryFor(instance) {
+        const mod = await this.load();
+        if (mod === undefined) {
+            return undefined;
+        }
+        const account = normalizeInstanceUrl(instance);
+        try {
+            return new mod.Entry(this.service, account);
+        }
+        catch (cause) {
+            this.warnRuntime('inicializar', cause);
+            return undefined;
+        }
+    }
+    /** Carrega (uma vez) o módulo nativo; `undefined` se não houver prebuild. */
+    async load() {
+        this.modulePromise ??= this.loader().then((mod) => mod, (cause) => {
+            this.warnUnavailable(cause);
+            return undefined;
+        });
+        return this.modulePromise;
+    }
+    /** Emite (uma única vez) o aviso de módulo indisponível. */
+    warnUnavailable(cause) {
+        if (this.unavailableWarned) {
+            return;
+        }
+        this.unavailableWarned = true;
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        this.logger.warn(`Keychain nativo indisponível (${reason}); as credenciais seguirão pelo arquivo. ` +
+            'Instale o prebuild de @napi-rs/keyring para esta plataforma para usar o keychain do SO.');
+    }
+    /** Emite um aviso de degradação de runtime — sem nunca expor a api_key. */
+    warnRuntime(action, cause) {
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        this.logger.warn(`Falha ao ${action} a credencial no keychain do SO: ${reason}.`);
+    }
+}

package/dist/config/login.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Login por senha (Basic auth) para descobrir a api_key do usuário (M1-07).
+ *
+ * Fluxo: `GET {baseUrl}/users/current.json` com `Authorization: Basic
+ * base64(user:pass)`. A senha nunca é logada nem persistida; qualquer texto
+ * que possa vazar (mensagens de rede/parse) é redigido antes de compor um erro.
+ *
+ * A política de TLS (https obrigatório; `insecure` apenas com aviso ruidoso) é
+ * reutilizada de `client/http.ts` via {@link validateBaseUrl} — não duplicada.
+ * O fallback de 2FA (copiar a api_key em `/my/account`) segue o ADR-003.
+ */
+import { type Logger } from '../client/index.js';
+/** Opções do login por senha. */
+export interface LoginOptions {
+    /** URL base da instância Redmine (ex.: `https://redmine.example`). */
+    baseUrl: string;
+    /** Login/identificador do usuário no Redmine. */
+    username: string;
+    /** Senha em texto puro — usada só para o header Basic, nunca logada. */
+    password: string;
+    /** Permite `http://` (sem TLS) com aviso ruidoso. Default: `false`. */
+    insecure?: boolean;
+    /** Logger para o aviso de conexão insegura; default no-op. */
+    logger?: Logger;
+}
+/** Resultado do login: api_key descoberta e identidade mínima do usuário. */
+export interface LoginResult {
+    /** api_key do usuário, extraída de `/users/current.json`. */
+    apiKey: string;
+    /** Identidade mínima do usuário autenticado. */
+    user: {
+        /** Id numérico do usuário no Redmine. */
+        id: number;
+        /** Login do usuário. */
+        login: string;
+        /** Nome de exibição (`firstname lastname`, ou `login` se ausentes). */
+        name: string;
+    };
+}
+/**
+ * Erro de login por senha que não se enquadra num status HTTP tipado do client
+ * (entrada inválida, REST desabilitada, corpo inesperado, falha de rede/parse).
+ * Sempre construído com a mensagem já redigida — nunca carrega a senha.
+ */
+export declare class RedmineLoginError extends Error {
+    constructor(message: string);
+}
+/**
+ * Autentica por senha e descobre a api_key do usuário.
+ *
+ * @param options - Ver {@link LoginOptions}.
+ * @returns {@link LoginResult} com a api_key e a identidade do usuário.
+ * @throws {RedmineLoginError} Entrada inválida, corpo sem usuário/api_key,
+ *   REST desabilitada, falha de rede ou JSON inválido (senha sempre redigida).
+ * @throws {RedmineAuthError} Em 401 — com instrução de fallback 2FA (ADR-003).
+ * @throws {Error} Se a política de TLS for violada (via `validateBaseUrl`).
+ * @example
+ * const { apiKey, user } = await loginWithPassword({
+ *   baseUrl: 'https://redmine.example',
+ *   username: 'alice',
+ *   password: '****',
+ * });
+ */
+export declare function loginWithPassword(options: LoginOptions): Promise<LoginResult>;
+/** Opções da validação de uma api_key colada diretamente (fallback de 2FA). */
+export interface ValidateApiKeyOptions {
+    /** URL base da instância Redmine (ex.: `https://redmine.example`). */
+    baseUrl: string;
+    /** api_key colada pelo usuário — usada só para o header, nunca logada. */
+    apiKey: string;
+    /** Permite `http://` (sem TLS) com aviso ruidoso. Default: `false`. */
+    insecure?: boolean;
+    /** Logger para o aviso de conexão insegura; default no-op. */
+    logger?: Logger;
+}
+/**
+ * Valida uma api_key colada diretamente pelo usuário (fallback de 2FA do
+ * ADR-003, quando `loginWithPassword` falha com 401) contra `GET
+ * {baseUrl}/users/current.json`, autenticando com o header
+ * `X-Redmine-API-Key` em vez de Basic auth. A key nunca é logada; qualquer
+ * texto que possa vazar é redigido antes de compor um erro — mesma política
+ * de {@link loginWithPassword}.
+ *
+ * @param options - Ver {@link ValidateApiKeyOptions}.
+ * @returns {@link LoginResult} com a própria api_key (ecoada de volta, para
+ *   simetria com {@link loginWithPassword}) e a identidade do usuário.
+ * @throws {RedmineLoginError} Entrada inválida, corpo sem usuário, REST
+ *   desabilitada, falha de rede ou JSON inválido (key sempre redigida).
+ * @throws {RedmineAuthError} Em 401 — api_key inválida ou expirada.
+ * @throws {Error} Se a política de TLS for violada (via `validateBaseUrl`).
+ * @example
+ * const { apiKey, user } = await validateApiKey({
+ *   baseUrl: 'https://redmine.example',
+ *   apiKey: pastedKey,
+ * });
+ */
+export declare function validateApiKey(options: ValidateApiKeyOptions): Promise<LoginResult>;