redmine-context 1.0.0

package/dist/client/issues.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Operações de leitura de issues sobre o {@link HttpClient} do M1.
+ *
+ * Escopo (issue #9): apenas `getIssue` e `listIssues`. Sem retry/backoff
+ * (issue #10) e SEM normalização (issue #11) — o payload é devolvido bruto,
+ * tipado de forma rasa. A normalização para o modelo {@link Issue} do contrato
+ * acontece em outra camada.
+ */
+import type { HttpClient, QueryParams } from './http.js';
+/**
+ * Payload bruto de uma issue, exatamente como a API do Redmine devolve.
+ * Tipo raso e intencionalmente permissivo: só garante `id`; os demais campos
+ * (subject, journals, attachments, custom_fields, ...) ficam sob a assinatura
+ * de índice e serão interpretados na normalização (issue #11).
+ */
+export interface RedmineIssuePayload {
+    id: number;
+    [key: string]: unknown;
+}
+/** Opções de {@link listIssues}: filtros de query + controle de paginação. */
+export interface ListIssuesOptions {
+    /**
+     * Filtros repassados ao endpoint `/issues.json` (ex.: `{ project_id: 5,
+     * status_id: 'open' }`). São enviados junto de `offset`/`limit` em cada página.
+     */
+    filters?: QueryParams;
+    /**
+     * Itens por página (parâmetro `limit`). Default e teto: {@link REDMINE_MAX_LIMIT}.
+     * Valores acima do teto são reduzidos silenciosamente para 100.
+     */
+    pageSize?: number;
+    /**
+     * Máximo de itens a acumular no total. Ausente = esgota toda a coleção
+     * (respeitando `total_count`). Também reduz o `limit` da última página para
+     * não buscar além do necessário.
+     */
+    maxItems?: number;
+}
+/**
+ * Busca o detalhe completo de uma issue com todas as coleções aninhadas.
+ *
+ * Usa `include=journals,attachments,relations,children` e devolve o payload
+ * BRUTO (sem normalizar). A resposta do Redmine tem o formato `{ issue: {...} }`;
+ * o objeto interno é retornado tipado como {@link RedmineIssuePayload}.
+ *
+ * @param http - Client HTTP autenticado (ver {@link HttpClient}).
+ * @param id - Identificador da issue.
+ * @returns O payload bruto da issue.
+ * @throws {Error} Se a resposta não contiver a chave `issue`.
+ * @throws {RedmineHttpError} Propagado pelo client em respostas ≥ 400.
+ * @example
+ * const issue = await getIssue(http, 100);
+ */
+export declare function getIssue(http: HttpClient, id: number): Promise<RedmineIssuePayload>;
+/**
+ * Lista issues paginando `/issues.json` via `offset`/`limit` até esgotar a
+ * coleção (respeitando `total_count`) ou atingir `maxItems`.
+ *
+ * Cada página respeita o teto de {@link REDMINE_MAX_LIMIT} do Redmine. Quando
+ * `maxItems` está definido, o `limit` da última página é reduzido para não
+ * buscar itens além do necessário. Sem retry (issue #10).
+ *
+ * @param http - Client HTTP autenticado (ver {@link HttpClient}).
+ * @param options - Filtros e controle de paginação (ver {@link ListIssuesOptions}).
+ * @returns Array acumulado com os payloads brutos das issues.
+ * @throws {Error} Se alguma página não trouxer o array `issues`.
+ * @throws {RedmineHttpError} Propagado pelo client em respostas ≥ 400.
+ * @example
+ * const all = await listIssues(http, { filters: { project_id: 5 }, maxItems: 500 });
+ */
+export declare function listIssues(http: HttpClient, options?: ListIssuesOptions): Promise<RedmineIssuePayload[]>;

package/dist/client/issues.js

@@ -0,0 +1,100 @@
+/**
+ * Operações de leitura de issues sobre o {@link HttpClient} do M1.
+ *
+ * Escopo (issue #9): apenas `getIssue` e `listIssues`. Sem retry/backoff
+ * (issue #10) e SEM normalização (issue #11) — o payload é devolvido bruto,
+ * tipado de forma rasa. A normalização para o modelo {@link Issue} do contrato
+ * acontece em outra camada.
+ */
+/** Include padrão do detalhe de issue (ADR-005): histórico e coleções aninhadas. */
+const ISSUE_INCLUDE = 'journals,attachments,relations,children';
+/** Teto de itens por página imposto pelo Redmine ao parâmetro `limit`. */
+const REDMINE_MAX_LIMIT = 100;
+/**
+ * Converte um valor desconhecido em `Record<string, unknown>` para acesso seguro.
+ *
+ * @param value - Valor a inspecionar.
+ * @returns O objeto tipado, ou `undefined` se não for um objeto simples.
+ */
+function asRecord(value) {
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+/**
+ * Busca o detalhe completo de uma issue com todas as coleções aninhadas.
+ *
+ * Usa `include=journals,attachments,relations,children` e devolve o payload
+ * BRUTO (sem normalizar). A resposta do Redmine tem o formato `{ issue: {...} }`;
+ * o objeto interno é retornado tipado como {@link RedmineIssuePayload}.
+ *
+ * @param http - Client HTTP autenticado (ver {@link HttpClient}).
+ * @param id - Identificador da issue.
+ * @returns O payload bruto da issue.
+ * @throws {Error} Se a resposta não contiver a chave `issue`.
+ * @throws {RedmineHttpError} Propagado pelo client em respostas ≥ 400.
+ * @example
+ * const issue = await getIssue(http, 100);
+ */
+export async function getIssue(http, id) {
+    const raw = await http.get(`/issues/${id}.json`, { include: ISSUE_INCLUDE });
+    const body = asRecord(raw);
+    const issue = body === undefined ? undefined : asRecord(body.issue);
+    if (issue === undefined) {
+        throw new Error(`Resposta de /issues/${id}.json não contém a chave "issue".`);
+    }
+    return issue;
+}
+/** Extrai `issues[]` e `total_count` de uma página de `/issues.json`. */
+function parsePage(raw) {
+    const body = asRecord(raw);
+    const issues = body?.issues;
+    if (!Array.isArray(issues)) {
+        throw new Error('Resposta de /issues.json não contém o array "issues".');
+    }
+    // total_count pode faltar em respostas inesperadas: assume o tamanho da página.
+    const totalCount = typeof body?.total_count === 'number' ? body.total_count : issues.length;
+    return { issues: issues, totalCount };
+}
+/**
+ * Lista issues paginando `/issues.json` via `offset`/`limit` até esgotar a
+ * coleção (respeitando `total_count`) ou atingir `maxItems`.
+ *
+ * Cada página respeita o teto de {@link REDMINE_MAX_LIMIT} do Redmine. Quando
+ * `maxItems` está definido, o `limit` da última página é reduzido para não
+ * buscar itens além do necessário. Sem retry (issue #10).
+ *
+ * @param http - Client HTTP autenticado (ver {@link HttpClient}).
+ * @param options - Filtros e controle de paginação (ver {@link ListIssuesOptions}).
+ * @returns Array acumulado com os payloads brutos das issues.
+ * @throws {Error} Se alguma página não trouxer o array `issues`.
+ * @throws {RedmineHttpError} Propagado pelo client em respostas ≥ 400.
+ * @example
+ * const all = await listIssues(http, { filters: { project_id: 5 }, maxItems: 500 });
+ */
+export async function listIssues(http, options = {}) {
+    const { filters = {}, maxItems } = options;
+    const pageSize = Math.min(options.pageSize ?? REDMINE_MAX_LIMIT, REDMINE_MAX_LIMIT);
+    const acc = [];
+    let offset = 0;
+    for (;;) {
+        // Reduz o limit da última página quando maxItems se aproxima do total.
+        const remaining = maxItems === undefined ? pageSize : Math.min(pageSize, maxItems - acc.length);
+        if (remaining <= 0) {
+            break;
+        }
+        const params = { ...filters, offset, limit: remaining };
+        const { issues, totalCount } = parsePage(await http.get('/issues.json', params));
+        acc.push(...issues);
+        offset += issues.length;
+        // Para em página vazia (guarda contra loop infinito) ou ao esgotar a coleção.
+        if (issues.length === 0 || offset >= totalCount) {
+            break;
+        }
+        if (maxItems !== undefined && acc.length >= maxItems) {
+            break;
+        }
+    }
+    return acc;
+}

package/dist/client/search.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Busca full-text de issues via `/search.json` (M1-13).
+ *
+ * Camada baixa sobre o {@link HttpClient} do M1: dispara `GET /search.json` com o
+ * termo `q` restrito a issues (`issues=1`) e devolve os acertos de forma rasa
+ * (id/título/tipo/url), SEM normalizar. É best-effort por natureza — um Redmine
+ * sem o módulo de busca responde 404; o orquestrador ({@link fetchIssueSearch})
+ * captura a falha e degrada para os filtros estruturados.
+ *
+ * Nunca recebe URL/host: o {@link HttpClient} já carrega a instância/credencial.
+ */
+import type { HttpClient } from './http.js';
+/** Opções da busca full-text sobre `/search.json`. */
+export interface SearchIssuesOptions {
+    /** Termo de busca (`q`). Deve ser não vazio (validado na superfície). */
+    query: string;
+    /** Deslocamento de paginação (`offset`). Default: `0`. */
+    offset?: number;
+    /** Itens por página (`limit`). Default e teto: {@link SEARCH_MAX_LIMIT}. */
+    limit?: number;
+}
+/** Acerto raso de `/search.json` já filtrado para o tipo `issue`. */
+export interface RedmineSearchHit {
+    /** Id da issue correspondente ao acerto. */
+    id: number;
+    /** Título do acerto como a API devolve (ex.: `Bug #12: assunto`). */
+    title: string;
+    /** Tipo do acerto (`issue`, `issue-closed`, ...). */
+    type: string;
+    /** URL do acerto na instância Redmine. */
+    url: string;
+}
+/** Página de resultados de `/search.json`: acertos + total reportado. */
+export interface SearchIssuesPage {
+    /** Acertos do tipo issue, na ordem devolvida pela API. */
+    hits: RedmineSearchHit[];
+    /** `total_count` reportado (ou o tamanho da página se ausente). */
+    totalCount: number;
+}
+/** Teto de itens por página imposto ao parâmetro `limit` de `/search.json`. */
+export declare const SEARCH_MAX_LIMIT = 100;
+/**
+ * Busca issues por texto livre em `/search.json`, restrito a issues.
+ *
+ * Devolve apenas os acertos do tipo issue (ids reutilizáveis como filtro
+ * `issue_id` em `/issues.json`). Não retenta e não normaliza — propaga os erros
+ * tipados do {@link HttpClient} (ex.: 404 quando a busca está indisponível) para
+ * o chamador decidir a degradação.
+ *
+ * @param http - Client HTTP autenticado (ver {@link HttpClient}).
+ * @param options - Termo e paginação (ver {@link SearchIssuesOptions}).
+ * @returns Página com os acertos de issue e o `total_count` reportado.
+ * @throws {Error} Se a resposta não contiver o array `results`.
+ * @throws {RedmineHttpError} Propagado pelo client em respostas ≥ 400.
+ * @example
+ * const page = await searchIssues(http, { query: 'timeout', limit: 25 });
+ */
+export declare function searchIssues(http: HttpClient, options: SearchIssuesOptions): Promise<SearchIssuesPage>;

package/dist/client/search.js

@@ -0,0 +1,81 @@
+/**
+ * Busca full-text de issues via `/search.json` (M1-13).
+ *
+ * Camada baixa sobre o {@link HttpClient} do M1: dispara `GET /search.json` com o
+ * termo `q` restrito a issues (`issues=1`) e devolve os acertos de forma rasa
+ * (id/título/tipo/url), SEM normalizar. É best-effort por natureza — um Redmine
+ * sem o módulo de busca responde 404; o orquestrador ({@link fetchIssueSearch})
+ * captura a falha e degrada para os filtros estruturados.
+ *
+ * Nunca recebe URL/host: o {@link HttpClient} já carrega a instância/credencial.
+ */
+/** Teto de itens por página imposto ao parâmetro `limit` de `/search.json`. */
+export const SEARCH_MAX_LIMIT = 100;
+/**
+ * Converte um valor desconhecido em `Record<string, unknown>` para acesso seguro.
+ *
+ * @param value - Valor a inspecionar.
+ * @returns O objeto tipado, ou `undefined` se não for um objeto simples.
+ */
+function asRecord(value) {
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+/** Extrai um acerto do array `results`, aceitando apenas os do tipo `issue*`. */
+function parseHit(entry) {
+    const rec = asRecord(entry);
+    if (rec === undefined)
+        return undefined;
+    const { id, type } = rec;
+    // Reason: o /search.json mistura tipos (issue, wiki-page, ...); só issues nos
+    // interessam. Redmine varia entre `issue` e `issue-closed` — casamos o prefixo.
+    if (typeof id !== 'number' || typeof type !== 'string' || !type.startsWith('issue')) {
+        return undefined;
+    }
+    return {
+        id,
+        type,
+        title: typeof rec.title === 'string' ? rec.title : '',
+        url: typeof rec.url === 'string' ? rec.url : '',
+    };
+}
+/**
+ * Busca issues por texto livre em `/search.json`, restrito a issues.
+ *
+ * Devolve apenas os acertos do tipo issue (ids reutilizáveis como filtro
+ * `issue_id` em `/issues.json`). Não retenta e não normaliza — propaga os erros
+ * tipados do {@link HttpClient} (ex.: 404 quando a busca está indisponível) para
+ * o chamador decidir a degradação.
+ *
+ * @param http - Client HTTP autenticado (ver {@link HttpClient}).
+ * @param options - Termo e paginação (ver {@link SearchIssuesOptions}).
+ * @returns Página com os acertos de issue e o `total_count` reportado.
+ * @throws {Error} Se a resposta não contiver o array `results`.
+ * @throws {RedmineHttpError} Propagado pelo client em respostas ≥ 400.
+ * @example
+ * const page = await searchIssues(http, { query: 'timeout', limit: 25 });
+ */
+export async function searchIssues(http, options) {
+    const limit = Math.min(options.limit ?? SEARCH_MAX_LIMIT, SEARCH_MAX_LIMIT);
+    const params = {
+        q: options.query,
+        issues: 1,
+        limit,
+        offset: options.offset ?? 0,
+    };
+    const body = asRecord(await http.get('/search.json', params));
+    const results = body?.results;
+    if (!Array.isArray(results)) {
+        throw new Error('Resposta de /search.json não contém o array "results".');
+    }
+    const hits = [];
+    for (const entry of results) {
+        const hit = parseHit(entry);
+        if (hit !== undefined)
+            hits.push(hit);
+    }
+    const totalCount = typeof body?.total_count === 'number' ? body.total_count : hits.length;
+    return { hits, totalCount };
+}

package/dist/config/credentials.d.ts

@@ -0,0 +1,247 @@
+/**
+ * Credential store da api_key por instância (M1-08).
+ *
+ * Persiste a api_key em um arquivo JSON `{ "<instance>": { "apiKey": "..." } }`
+ * com permissão `0600` dentro de um diretório `0700` — uma entrada por URL base
+ * normalizada, suportando múltiplas instâncias Redmine. O caminho padrão vem de
+ * `env-paths` (diretório de config do usuário).
+ *
+ * A resolução segue a cascata do ADR-003: keychain → arquivo → variável de
+ * ambiente `REDMINE_API_KEY` (o env é sempre aceito, para CI/MCP headless). A
+ * interface {@link CredentialStore} (get/set/delete) é comum a todas as
+ * implementações; a {@link MigratingCredentialCascade} as consulta em ordem e,
+ * quando o keychain está disponível, migra a chave do arquivo para ele.
+ *
+ * A api_key nunca é logada e nunca aparece em mensagens de erro — os erros de
+ * permissão carregam apenas caminhos e o comando `chmod` a ser executado. A
+ * verificação de permissão POSIX fica atrás de `process.platform !== 'win32'`
+ * porque o Windows não tem o mesmo modelo de bits `0600` (o hardening real do
+ * Windows é o M5-08).
+ */
+import type { Logger } from '../client/index.js';
+import { KeyringCredentialStore, type KeyringModuleLoader } from './keyring.js';
+/**
+ * Contrato de armazenamento de api_key por instância. A implementação de
+ * arquivo (M1) e a de keychain (M2) satisfazem esta interface, o que permite à
+ * cascata tratá-las de forma uniforme.
+ */
+export interface CredentialStore {
+    /**
+     * Recupera a api_key da instância, ou `undefined` se não houver.
+     * @param instance - URL base da instância (será normalizada).
+     */
+    get(instance: string): Promise<string | undefined>;
+    /**
+     * Persiste (ou substitui) a api_key da instância.
+     * @param instance - URL base da instância (será normalizada).
+     * @param apiKey - api_key a armazenar.
+     */
+    set(instance: string, apiKey: string): Promise<void>;
+    /**
+     * Remove a api_key da instância; no-op se não existir.
+     * @param instance - URL base da instância (será normalizada).
+     */
+    delete(instance: string): Promise<void>;
+}
+/** Erro do credential store — sempre construído sem expor a api_key. */
+export declare class CredentialStoreError extends Error {
+    constructor(message: string);
+}
+/**
+ * Normaliza a URL base de uma instância para uma chave estável.
+ *
+ * Aplica minúsculas (protocolo e host), remove a porta padrão (443 p/ https, 80
+ * p/ http), remove a barra final e preserva o subpath. Mantém a mesma ideia do
+ * futuro `instance_hash`: formas equivalentes colapsam na mesma chave.
+ *
+ * @param instance - URL base da instância (ex.: `https://Redmine.Example/`).
+ * @returns A URL normalizada (ex.: `https://redmine.example`).
+ * @throws {TypeError} Se `instance` não for uma URL válida.
+ * @example
+ * normalizeInstanceUrl('HTTPS://Redmine.Example:443/'); // 'https://redmine.example'
+ */
+export declare function normalizeInstanceUrl(instance: string): string;
+/** Caminho padrão do arquivo de credenciais (diretório de config do usuário). */
+export declare function defaultCredentialsPath(): string;
+/** Opções do {@link FileCredentialStore}. */
+export interface FileCredentialStoreOptions {
+    /** Caminho do arquivo; default via `env-paths`. Útil para testes. */
+    filePath?: string;
+}
+/**
+ * Implementação de {@link CredentialStore} baseada em arquivo `0600` num
+ * diretório `0700`. Verifica as permissões ao ler (boot) e as reaplica ao
+ * escrever, independentemente do umask.
+ */
+export declare class FileCredentialStore implements CredentialStore {
+    private readonly filePath;
+    /** @param options - Ver {@link FileCredentialStoreOptions}. */
+    constructor(options?: FileCredentialStoreOptions);
+    /** @inheritdoc */
+    get(instance: string): Promise<string | undefined>;
+    /** @inheritdoc */
+    set(instance: string, apiKey: string): Promise<void>;
+    /** @inheritdoc */
+    delete(instance: string): Promise<void>;
+    /** Lê e valida o arquivo; `undefined` se ainda não existir. */
+    private read;
+    /** Escreve o arquivo garantindo dir `0700` e arquivo `0600`. */
+    private write;
+    /** Falha com erro acionável se as permissões do arquivo estiverem erradas. */
+    private assertSecureMode;
+}
+/** Opções do {@link EnvCredentialStore}. */
+export interface EnvCredentialStoreOptions {
+    /** Nome da variável de ambiente; default `REDMINE_API_KEY`. */
+    varName?: string;
+    /** Ambiente a consultar; default `process.env` (injetável em testes). */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Implementação de {@link CredentialStore} somente-leitura sobre uma variável
+ * de ambiente. É o fallback headless (CI/MCP) da cascata: `get` devolve a chave
+ * do env para qualquer instância; `set`/`delete` lançam.
+ */
+export declare class EnvCredentialStore implements CredentialStore {
+    private readonly varName;
+    private readonly env;
+    /** @param options - Ver {@link EnvCredentialStoreOptions}. */
+    constructor(options?: EnvCredentialStoreOptions);
+    /** @inheritdoc */
+    get(): Promise<string | undefined>;
+    /** Somente leitura: sempre lança. */
+    set(): Promise<void>;
+    /** Somente leitura: sempre lança. */
+    delete(): Promise<void>;
+}
+/**
+ * Cascata de {@link CredentialStore}: `get` consulta os stores em ordem e
+ * devolve o primeiro valor encontrado; escritas vão para o primeiro store (o
+ * gravável). A ordem M1 é arquivo → env.
+ */
+export declare class CascadingCredentialStore implements CredentialStore {
+    private readonly stores;
+    /**
+     * @param stores - Stores em ordem de prioridade (o primeiro é o gravável).
+     * @throws {CredentialStoreError} Se a lista estiver vazia.
+     */
+    constructor(stores: readonly CredentialStore[]);
+    /** @inheritdoc */
+    get(instance: string): Promise<string | undefined>;
+    /** @inheritdoc */
+    set(instance: string, apiKey: string): Promise<void>;
+    /** @inheritdoc */
+    delete(instance: string): Promise<void>;
+    /** O primeiro store da cascata — destino das escritas. */
+    private writableStore;
+}
+/**
+ * Cascata de credenciais M2 com migração para o keychain (ADR-003).
+ *
+ * A resolução (`get`) segue a ordem keychain → arquivo `0600` → env; o primeiro
+ * valor encontrado vence. Quando a chave vem do ARQUIVO e o keychain está
+ * DISPONÍVEL, a chave é migrada — gravada no keychain e só então removida do
+ * arquivo (a remoção é condicionada à confirmação da gravação, evitando perda da
+ * credencial se o keychain degradar) — com um único aviso informativo por
+ * cascata. As escritas (`set`) preferem o keychain quando disponível, com
+ * fallback para o arquivo; o env é somente leitura. A api_key nunca é logada.
+ */
+export declare class MigratingCredentialCascade implements CredentialStore {
+    private readonly keyring;
+    private readonly file;
+    private readonly env;
+    private readonly logger;
+    /** Garante que o aviso de migração seja emitido uma única vez por cascata. */
+    private migrationWarned;
+    /**
+     * @param keyring - Store do keychain nativo (fonte prioritária e destino da migração).
+     * @param file - Store de arquivo `0600` (fallback e origem da migração).
+     * @param env - Store de ambiente somente leitura (fallback headless).
+     * @param logger - Logger do aviso único de migração; default no-op.
+     */
+    constructor(keyring: KeyringCredentialStore, file: CredentialStore, env: CredentialStore, logger?: Logger);
+    /** @inheritdoc */
+    get(instance: string): Promise<string | undefined>;
+    /** @inheritdoc */
+    set(instance: string, apiKey: string): Promise<void>;
+    /** @inheritdoc */
+    delete(instance: string): Promise<void>;
+    /**
+     * Identifica QUAL fonte resolveria a credencial da instância (keychain →
+     * arquivo → env), sem expor a api_key e SEM disparar a migração
+     * arquivo→keychain feita por {@link get} — diagnóstico somente-leitura
+     * usado pela tela `doctor` da TUI (#35), que só precisa mostrar o método em
+     * uso, nunca o segredo.
+     *
+     * @param instance - URL base da instância (será normalizada pelos stores).
+     * @returns A fonte em uso, ou `'none'` se nenhuma tiver a credencial.
+     */
+    describeSource(instance: string): Promise<CredentialSourceKind>;
+    /**
+     * Migra a chave do arquivo para o keychain quando este está disponível. A
+     * remoção do arquivo só ocorre após confirmar a gravação no keychain, evitando
+     * perda da credencial se a escrita degradar. Emite um único aviso, sem expor a
+     * api_key.
+     *
+     * @param instance - URL base da instância (será normalizada pelos stores).
+     * @param apiKey - Chave lida do arquivo a ser migrada.
+     */
+    private migrateFromFile;
+}
+/**
+ * Fonte que resolveria a credencial de uma instância na cascata M2, sem
+ * expor a api_key em si (consumido pela tela `doctor` da TUI, #35).
+ * `'none'` quando nenhuma das três fontes tem a credencial.
+ */
+export type CredentialSourceKind = 'keyring' | 'file' | 'env' | 'none';
+/** Opções de {@link createCredentialCascade} / {@link resolveApiKey}. */
+export interface CredentialCascadeOptions {
+    /** Caminho do arquivo de credenciais; default via `env-paths`. */
+    filePath?: string;
+    /** Nome da variável de ambiente; default `REDMINE_API_KEY`. */
+    envVarName?: string;
+    /** Ambiente a consultar; default `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Logger para o aviso único de migração; default no-op. */
+    logger?: Logger;
+    /** Service do keychain; default `redmine-context`. */
+    keyringService?: string;
+    /** Carregador do módulo nativo do keychain; injetável em testes. */
+    keyringLoader?: KeyringModuleLoader;
+    /**
+     * Permite a credencial de AMBIENTE (`REDMINE_API_KEY`) como fallback. Default
+     * `true` (retrocompatível). SEGURANÇA (#187): a env-key é INSTANCE-AGNÓSTICA
+     * (o `EnvCredentialStore` a devolve para QUALQUER URL). Quando a URL da
+     * instância vem de uma fonte MUTÁVEL/menos confiável (ex.: `settings.json`
+     * persistido, origem `config`), passe `false` — assim uma URL adulterada não
+     * pode fazer a chave real ser enviada a um host arbitrário; só credencial
+     * PINADA à instância (keychain/arquivo) é aceita (fail-closed).
+     */
+    allowEnvFallback?: boolean;
+}
+export declare function createCredentialCascade(options?: CredentialCascadeOptions): MigratingCredentialCascade;
+/**
+ * Resolve a api_key de uma instância pela cascata M2 (keychain → arquivo → env),
+ * migrando do arquivo para o keychain quando este estiver disponível.
+ *
+ * @param instance - URL base da instância (será normalizada).
+ * @param options - Ver {@link CredentialCascadeOptions}.
+ * @returns A api_key resolvida, ou `undefined` se nenhuma fonte a tiver.
+ * @example
+ * const apiKey = await resolveApiKey('https://redmine.example');
+ */
+export declare function resolveApiKey(instance: string, options?: CredentialCascadeOptions): Promise<string | undefined>;
+/**
+ * Identifica a fonte que resolveria a credencial de uma instância na cascata
+ * M2 (keychain → arquivo → env), SEM expor a api_key e sem migrar do arquivo
+ * para o keychain — ver {@link MigratingCredentialCascade.describeSource}.
+ * Usada pela tela `doctor` da TUI (#35) para relatar o método de credencial
+ * em uso.
+ *
+ * @param instance - URL base da instância (será normalizada).
+ * @param options - Ver {@link CredentialCascadeOptions}.
+ * @returns A fonte em uso ('keyring' | 'file' | 'env'), ou 'none'.
+ * @example
+ * const source = await describeCredentialSource('https://redmine.example');
+ */
+export declare function describeCredentialSource(instance: string, options?: CredentialCascadeOptions): Promise<CredentialSourceKind>;