redmine-context 1.0.0

package/dist/surfaces/tui/format-file-size.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Formatação humanizada de tamanho de arquivo (#32) — usada pela seção de
+ * anexos do detalhe da issue para exibir `Attachment.filesize` (bytes,
+ * inteiro bruto do Redmine) em um texto curto (B/KB/MB/GB), sem depender de
+ * biblioteca externa para uma conta tão simples.
+ */
+/**
+ * Formata `bytes` como texto humanizado (ex.: `999B`, `1.5KB`, `2MB`).
+ *
+ * Escala para a maior unidade em que o valor fica `>= 1` (mas `< 1024`),
+ * arredondando para 1 casa decimal — sem casa decimal supérflua quando o
+ * valor é inteiro (`1KB`, não `1.0KB`).
+ *
+ * @param bytes - Tamanho em bytes (`Attachment.filesize`). Valores negativos
+ *   nunca deveriam ocorrer (o core normaliza para `>= 0`), mas são tratados
+ *   defensivamente como `0` em vez de lançar — consistente com o resto da
+ *   normalização (ADR-005: nunca crashar por payload inesperado).
+ * @returns O texto humanizado.
+ * @example
+ * humanizeFileSize(999)  // "999B"
+ * humanizeFileSize(1536) // "1.5KB"
+ * humanizeFileSize(2 * 1024 * 1024) // "2MB"
+ */
+export declare function humanizeFileSize(bytes: number): string;

package/dist/surfaces/tui/format-file-size.js

@@ -0,0 +1,43 @@
+/**
+ * Formatação humanizada de tamanho de arquivo (#32) — usada pela seção de
+ * anexos do detalhe da issue para exibir `Attachment.filesize` (bytes,
+ * inteiro bruto do Redmine) em um texto curto (B/KB/MB/GB), sem depender de
+ * biblioteca externa para uma conta tão simples.
+ */
+/** Unidades usadas na escalada progressiva (índice 0 = bytes, sem sufixo de escala). */
+const UNITS = ['B', 'KB', 'MB', 'GB', 'TB'];
+/**
+ * Formata `bytes` como texto humanizado (ex.: `999B`, `1.5KB`, `2MB`).
+ *
+ * Escala para a maior unidade em que o valor fica `>= 1` (mas `< 1024`),
+ * arredondando para 1 casa decimal — sem casa decimal supérflua quando o
+ * valor é inteiro (`1KB`, não `1.0KB`).
+ *
+ * @param bytes - Tamanho em bytes (`Attachment.filesize`). Valores negativos
+ *   nunca deveriam ocorrer (o core normaliza para `>= 0`), mas são tratados
+ *   defensivamente como `0` em vez de lançar — consistente com o resto da
+ *   normalização (ADR-005: nunca crashar por payload inesperado).
+ * @returns O texto humanizado.
+ * @example
+ * humanizeFileSize(999)  // "999B"
+ * humanizeFileSize(1536) // "1.5KB"
+ * humanizeFileSize(2 * 1024 * 1024) // "2MB"
+ */
+export function humanizeFileSize(bytes) {
+    const safeBytes = bytes > 0 ? bytes : 0;
+    let value = safeBytes;
+    let unitIndex = 0;
+    while (value >= 1024 && unitIndex < UNITS.length - 1) {
+        value /= 1024;
+        unitIndex += 1;
+    }
+    let rounded = Math.round(value * 10) / 10;
+    // O arredondamento pode "estourar" a unidade (1048575 bytes → 1024KB):
+    // nesse caso, escala mais um degrau para exibir 1MB, não 1024KB.
+    if (rounded >= 1024 && unitIndex < UNITS.length - 1) {
+        rounded = Math.round((rounded / 1024) * 10) / 10;
+        unitIndex += 1;
+    }
+    const formatted = Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
+    return `${formatted}${UNITS[unitIndex]}`;
+}

package/dist/surfaces/tui/glyphs.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Espelha a heurística de `is-unicode-supported@2` (a mesma que `figures`
+ * consome) como função pura e injetável.
+ *
+ * Reason: `figures` decide o fallback UMA vez, no import, a partir do ambiente
+ * real — para orçarmos os glyphs "common" pelo MESMO critério (e testá-lo com
+ * ambientes simulados) precisamos da decisão exposta como função. Manter a
+ * lógica idêntica à da lib garante que os dois caminhos concordem.
+ *
+ * @param env - Ambiente do processo (ou um subconjunto controlado em testes).
+ * @param platform - Plataforma (`process.platform`); injetável para testes.
+ * @returns `true` quando o terminal deve renderizar glyphs Unicode.
+ * @example
+ * isUnicodeSupported({ WT_SESSION: '1' }, 'win32'); // true (Windows Terminal)
+ * isUnicodeSupported({}, 'win32'); // false (cmd.exe/PowerShell legado)
+ */
+export declare function isUnicodeSupported(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/** Conjunto de glyphs "common" que a TUI usa fora de `figures`. */
+export interface Glyphs {
+    /** Marcador de corte do truncamento (`../truncate.ts`). */
+    readonly ellipsis: string;
+    /** Separador entre campos de uma linha (ex.: `tamanho · tipo`). */
+    readonly middleDot: string;
+    /** Placeholder para campos ausentes (assignee, datas, old/new value). */
+    readonly emptyPlaceholder: string;
+    /** Seta "para cima" das dicas de navegação. */
+    readonly arrowUp: string;
+    /** Seta "para baixo" das dicas de navegação. */
+    readonly arrowDown: string;
+    /** Caractere da máscara de senha/api_key (`components/text-input.tsx`). */
+    readonly maskBullet: string;
+    /** Frames do spinner (`components/spinner.tsx`). */
+    readonly spinnerFrames: readonly string[];
+}
+/** Glyphs Unicode — terminais modernos (Windows Terminal, iTerm, etc.). */
+export declare const UNICODE_GLYPHS: Glyphs;
+/** Fallback ASCII puro — terminal legado do Windows (sem mojibake). */
+export declare const ASCII_GLYPHS: Glyphs;
+/**
+ * Escolhe o conjunto de glyphs conforme o suporte a Unicode.
+ *
+ * @param unicode - `true` para glyphs Unicode, `false` para o fallback ASCII.
+ * @returns O conjunto de glyphs correspondente.
+ */
+export declare function resolveGlyphs(unicode: boolean): Glyphs;
+/** Glyphs resolvidos para o ambiente atual — importado pelas telas/utilitários. */
+export declare const glyphs: Glyphs;

package/dist/surfaces/tui/glyphs.js

@@ -0,0 +1,84 @@
+/**
+ * Glyphs NÃO cobertos por `figures` — hardening do terminal LEGADO do Windows
+ * (M5-09, #84): cmd.exe / PowerShell antigo, sem suporte a Unicode.
+ *
+ * `figures` (ver `./symbols.ts`) só degrada para ASCII os seus símbolos
+ * ESPECIAIS (tick/cross/pointer/info/warning). Os glyphs da categoria "common"
+ * dele — reticências `…`, setas `↑`/`↓`, `bullet`, etc. — permanecem Unicode
+ * MESMO no conjunto `fallbackSymbols` (confira `node_modules/figures/index.js`:
+ * `common` é espalhado tanto em `mainSymbols` quanto em `fallbackSymbols`).
+ *
+ * A TUI usa alguns desses glyphs "common" hardcoded fora do sistema de
+ * `figures` (reticências de truncamento, setas de navegação, o separador `·`,
+ * a máscara de senha `•` e os frames braille do spinner). Em um terminal
+ * legado do Windows eles apareceriam como mojibake. Este módulo centraliza
+ * ESSES glyphs com um fallback ASCII, decidido pelo MESMO sinal que `figures`
+ * usa por baixo (`is-unicode-supported`), replicado aqui como função pura e
+ * injetável (`env`/`platform`) — seguindo o padrão de `../cli/tty.ts`
+ * (`shouldRenderTui`), que também mantém a decisão de degradação testável sem
+ * ler `process` direto.
+ */
+import process from 'node:process';
+/**
+ * Espelha a heurística de `is-unicode-supported@2` (a mesma que `figures`
+ * consome) como função pura e injetável.
+ *
+ * Reason: `figures` decide o fallback UMA vez, no import, a partir do ambiente
+ * real — para orçarmos os glyphs "common" pelo MESMO critério (e testá-lo com
+ * ambientes simulados) precisamos da decisão exposta como função. Manter a
+ * lógica idêntica à da lib garante que os dois caminhos concordem.
+ *
+ * @param env - Ambiente do processo (ou um subconjunto controlado em testes).
+ * @param platform - Plataforma (`process.platform`); injetável para testes.
+ * @returns `true` quando o terminal deve renderizar glyphs Unicode.
+ * @example
+ * isUnicodeSupported({ WT_SESSION: '1' }, 'win32'); // true (Windows Terminal)
+ * isUnicodeSupported({}, 'win32'); // false (cmd.exe/PowerShell legado)
+ */
+export function isUnicodeSupported(env = process.env, platform = process.platform) {
+    const { TERM, TERM_PROGRAM } = env;
+    if (platform !== 'win32') {
+        return TERM !== 'linux'; // console do kernel Linux não renderiza Unicode
+    }
+    return (Boolean(env.WT_SESSION) || // Windows Terminal
+        Boolean(env.TERMINUS_SUBLIME) || // Terminus (<0.2.27)
+        env.ConEmuTask === '{cmd::Cmder}' || // ConEmu e cmder
+        TERM_PROGRAM === 'Terminus-Sublime' ||
+        TERM_PROGRAM === 'vscode' ||
+        TERM === 'xterm-256color' ||
+        TERM === 'alacritty' ||
+        TERM === 'rxvt-unicode' ||
+        TERM === 'rxvt-unicode-256color' ||
+        env.TERMINAL_EMULATOR === 'JetBrains-JediTerm');
+}
+/** Glyphs Unicode — terminais modernos (Windows Terminal, iTerm, etc.). */
+export const UNICODE_GLYPHS = {
+    ellipsis: '…',
+    middleDot: '·',
+    emptyPlaceholder: '—',
+    arrowUp: '↑',
+    arrowDown: '↓',
+    maskBullet: '•',
+    spinnerFrames: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
+};
+/** Fallback ASCII puro — terminal legado do Windows (sem mojibake). */
+export const ASCII_GLYPHS = {
+    ellipsis: '...',
+    middleDot: '|',
+    emptyPlaceholder: '-',
+    arrowUp: '^',
+    arrowDown: 'v',
+    maskBullet: '*',
+    spinnerFrames: ['|', '/', '-', '\\'],
+};
+/**
+ * Escolhe o conjunto de glyphs conforme o suporte a Unicode.
+ *
+ * @param unicode - `true` para glyphs Unicode, `false` para o fallback ASCII.
+ * @returns O conjunto de glyphs correspondente.
+ */
+export function resolveGlyphs(unicode) {
+    return unicode ? UNICODE_GLYPHS : ASCII_GLYPHS;
+}
+/** Glyphs resolvidos para o ambiente atual — importado pelas telas/utilitários. */
+export const glyphs = resolveGlyphs(isUnicodeSupported());

package/dist/surfaces/tui/hooks/use-auth-guard.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Erro de rejeição de `guard()` quando o re-login em andamento é ABANDONADO
+ * (Esc na tela de onboarding, ver `../app.tsx`) em vez de concluído — fix do
+ * review do PR #119.
+ *
+ * @remarks Telas de dados que chamam `guard()` devem tratar esta rejeição
+ *   como uma operação CANCELADA pelo usuário (volte a um estado neutro —
+ *   ex.: `status: 'idle'` — igual a antes da chamada), e não como uma falha
+ *   inesperada (nada de mensagem de erro em vermelho ou crash): o usuário
+ *   escolheu conscientemente não reautenticar.
+ */
+export declare class ReAuthAbortedError extends Error {
+    constructor(message?: string);
+}
+/** Valor retornado por {@link useAuthGuard}. */
+export interface UseAuthGuardResult {
+    /**
+     * Envolve uma operação autenticada do core.
+     *
+     * Devolve o mesmo resultado (ou rejeição) da operação em condições normais.
+     * Em caso de `RedmineAuthError`, dispara o fluxo de re-auth descrito no
+     * módulo e só resolve depois que o usuário loga de novo e a operação é
+     * reexecutada — chamadoras que precisam de um `AbortController`/cleanup
+     * (ex.: `useEffect`) continuam funcionando normalmente: a promise
+     * devolvida é só ignorada se o componente desmontar antes dela resolver.
+     *
+     * Se o re-login for abandonado (Esc, ver `../app.tsx`), a `Promise`
+     * rejeita com {@link ReAuthAbortedError} — trate como cancelamento, não
+     * como erro (ver o remark da classe).
+     *
+     * @param operation - A chamada ao core a proteger (ex.: `fetchIssueBundle`).
+     */
+    guard<T>(operation: () => Promise<T>): Promise<T>;
+}
+/**
+ * Hook público de re-autenticação — ver o JSDoc do módulo para o contrato
+ * completo.
+ */
+export declare function useAuthGuard(): UseAuthGuardResult;

package/dist/surfaces/tui/hooks/use-auth-guard.js

@@ -0,0 +1,135 @@
+/**
+ * Guarda central de re-autenticação (M2-13, issue #36).
+ *
+ * QUALQUER tela de dados (#29+) que chame o core autenticado deve envolver
+ * essa chamada com `guard()`. Se a operação rejeitar com `RedmineAuthError`
+ * (401 — a api_key expirou ou foi revogada no servidor), o guard:
+ *
+ * 1. guarda a tela ATUAL (`useNavigation().current`) como origem e a própria
+ *    chamada como callback de retry;
+ * 2. empurra `onboarding-login` em modo re-auth
+ *    (`OnboardingContext.beginReAuth`, `../screens/onboarding/onboarding-context.tsx`),
+ *    reaproveitando o fluxo de onboarding já existente para o usuário logar
+ *    de novo — sem repetir `onboarding-url`/`onboarding-mode`, já que a
+ *    instância já é conhecida;
+ * 3. quando o re-login resolve com sucesso, `validating.tsx`/`api-key.tsx`
+ *    (`../screens/onboarding/`) chamam `OnboardingContext.resolveReAuth()`,
+ *    que dispara o `retry` guardado aqui — SÓ NESSE MOMENTO a `Promise`
+ *    devolvida por `guard()` resolve, com o resultado da nova tentativa — e a
+ *    navegação volta à tela de origem (`useNavigation().popTo`, chamado pelas
+ *    mesmas telas antes de `resolveReAuth()`).
+ *
+ * Se o re-login falhar (senha errada, rede fora do ar), a tela de login
+ * segue seu fluxo normal (mensagem de erro, tentar de novo) — o `reAuth`
+ * guardado no contexto permanece intacto (a origem não se perde) até uma
+ * tentativa ter sucesso.
+ *
+ * A credencial antiga é sobrescrita normalmente pela cascata de persistência
+ * (`createCredentialCascade().set()`, já chamada por
+ * `./use-onboarding-callbacks.ts` em todo login bem-sucedido, re-auth ou não)
+ * — nenhum tratamento especial é necessário aqui.
+ *
+ * Fix do review do PR #119 — dois problemas cobertos aqui:
+ *
+ * 1. Abandono do re-login (Esc): antes, a `Promise` de `guard()` ficava
+ *    pendurada para sempre se o usuário apertasse Esc na tela de login em
+ *    vez de completar o re-auth. Agora o atalho global de Esc
+ *    (`../../app.tsx`), ao detectar que está numa tela `onboarding-*` com um
+ *    `reAuth` ativo, chama `OnboardingContext.abortReAuth()` — que rejeita
+ *    a `Promise` com {@link ReAuthAbortedError}. Chamadoras de `guard()`
+ *    (telas de dados) devem tratar essa rejeição como uma operação
+ *    CANCELADA (estado neutro — "usuário desistiu de logar de novo"), não
+ *    como uma falha a ser exibida como erro/crash.
+ * 2. 401 concorrentes: antes, um segundo `guard()` falhando com 401 enquanto
+ *    o primeiro já tinha iniciado o re-auth SOBRESCREVIA o `reAuth` no
+ *    contexto — o primeiro retry/reject ficava órfão. Agora
+ *    `OnboardingContext.beginReAuth()` acumula uma lista de pendências; uma
+ *    única passagem de login bem-sucedida (`resolveReAuth()`) resolve TODOS
+ *    os `guard()` pendentes.
+ *
+ * @example
+ * // Tela de dados futura (#29+, ex.: `screens/home.tsx`):
+ * import { useAuthGuard } from '../hooks/use-auth-guard.js';
+ *
+ * function HomeScreen() {
+ *   const { guard } = useAuthGuard();
+ *   const [bundle, setBundle] = useState<IssueBundleResult>();
+ *
+ *   useEffect(() => {
+ *     let cancelled = false;
+ *     guard(() => fetchIssueBundleViaCore(issueId)).then((result) => {
+ *       if (!cancelled) setBundle(result);
+ *     });
+ *     return () => {
+ *       cancelled = true;
+ *     };
+ *   }, [issueId]);
+ *   // ...
+ * }
+ */
+import { useCallback, useRef } from 'react';
+import { RedmineAuthError } from '../../../index.js';
+import { useNavigation } from '../navigation.js';
+import { useOnboarding } from '../screens/onboarding/onboarding-context.js';
+/**
+ * Erro de rejeição de `guard()` quando o re-login em andamento é ABANDONADO
+ * (Esc na tela de onboarding, ver `../app.tsx`) em vez de concluído — fix do
+ * review do PR #119.
+ *
+ * @remarks Telas de dados que chamam `guard()` devem tratar esta rejeição
+ *   como uma operação CANCELADA pelo usuário (volte a um estado neutro —
+ *   ex.: `status: 'idle'` — igual a antes da chamada), e não como uma falha
+ *   inesperada (nada de mensagem de erro em vermelho ou crash): o usuário
+ *   escolheu conscientemente não reautenticar.
+ */
+export class ReAuthAbortedError extends Error {
+    constructor(message = 'Re-autenticação cancelada pelo usuário (Esc).') {
+        super(message);
+        this.name = 'ReAuthAbortedError';
+    }
+}
+/**
+ * Hook público de re-autenticação — ver o JSDoc do módulo para o contrato
+ * completo.
+ */
+export function useAuthGuard() {
+    const { current, push } = useNavigation();
+    const { beginReAuth } = useOnboarding();
+    // Refs (não deps do useCallback): `guard` precisa ficar com identidade
+    // ESTÁVEL (padrão do repo) mesmo com `current`/`push`/`beginReAuth` mudando
+    // entre renders — o valor lido é sempre o mais recente via ref.
+    const currentRef = useRef(current);
+    currentRef.current = current;
+    const pushRef = useRef(push);
+    pushRef.current = push;
+    const beginReAuthRef = useRef(beginReAuth);
+    beginReAuthRef.current = beginReAuth;
+    const guard = useCallback(function guardOperation(operation, 
+    // A origem é capturada UMA VEZ, na primeira falha — e reaproveitada em
+    // retries subsequentes (`falha do re-login não perde a origem`, DoD
+    // #36), mesmo que a navegação já tenha mudado quando o retry acontece.
+    origin = currentRef.current) {
+        return operation().catch((cause) => {
+            if (!(cause instanceof RedmineAuthError)) {
+                throw cause;
+            }
+            return new Promise((resolve, reject) => {
+                // Fix do review #119: `beginReAuth` devolve `true` só na PRIMEIRA
+                // vez que este ciclo de re-auth é ativado — 401 concorrentes
+                // (segunda chamada enquanto a primeira já empilhou o login) só
+                // adicionam a pendência à lista existente, sem empilhar
+                // `onboarding-login` de novo nem perder o retry/reject anterior.
+                const activated = beginReAuthRef.current(origin, {
+                    retry: () => {
+                        guardOperation(operation, origin).then(resolve, reject);
+                    },
+                    reject,
+                });
+                if (activated) {
+                    pushRef.current('onboarding-login');
+                }
+            });
+        });
+    }, []);
+    return { guard };
+}

package/dist/surfaces/tui/hooks/use-doctor-status.d.ts

@@ -0,0 +1,64 @@
+import { describeCredentialSource, type CredentialSourceKind } from '../../../index.js';
+/** Resultado do teste leve de conectividade. */
+export type ConnectivityStatus = 'checking' | 'ok' | 'error' | 'skipped';
+/** Snapshot completo do painel de diagnóstico exibido por `doctor.tsx`. */
+export interface DoctorStatus {
+    /** Versão do runtime Node (`process.version`, ou injetada em teste). */
+    nodeVersion: string;
+    /** Nome do produto (via core). */
+    toolName: string;
+    /** Versão do produto (via core). */
+    toolVersion: string;
+    /** Instância configurada (`REDMINE_URL`), ou `undefined` se ausente. */
+    instanceUrl: string | undefined;
+    /**
+     * Fonte da credencial em uso na cascata — NUNCA a api_key em si.
+     * `'checking'` enquanto a consulta assíncrona ainda não resolveu.
+     */
+    credentialMethod: CredentialSourceKind | 'checking';
+    /** Resultado do teste leve de conectividade (ver {@link ConnectivityStatus}). */
+    connectivity: ConnectivityStatus;
+    /** Detalhe do erro de conectividade, se houver — sempre seguro (sem segredos). */
+    connectivityDetail: string | undefined;
+}
+/** Resultado devolvido por um {@link ConnectivityChecker}. */
+export interface ConnectivityCheckResult {
+    /** `true` se a instância respondeu com sucesso dentro do timeout. */
+    ok: boolean;
+    /** Detalhe legível da falha (status HTTP ou motivo da exceção). Ausente quando `ok`. */
+    detail?: string;
+}
+/**
+ * Executa a checagem de conectividade — injetável para testes (o default de
+ * produção usa `fetch` global com timeout via `AbortController`).
+ */
+export type ConnectivityChecker = (instanceUrl: string, timeoutMs: number) => Promise<ConnectivityCheckResult>;
+/** Dependências injetáveis do hook — todas opcionais, com defaults de produção. */
+export interface UseDoctorStatusOptions {
+    /** Ambiente consultado para `REDMINE_URL`; default `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Versão do Node exibida; default `process.version`. */
+    nodeVersion?: string;
+    /** Resolve a fonte da credencial; default `describeCredentialSource` do core. */
+    describeCredentialSource?: typeof describeCredentialSource;
+    /** Executa a checagem de conectividade; default via `fetch` global. */
+    checkConnectivity?: ConnectivityChecker;
+    /** Timeout (ms) da checagem de conectividade; default {@link DEFAULT_CONNECTIVITY_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/** Timeout default do teste de conectividade — curto o bastante para não travar a tela. */
+export declare const DEFAULT_CONNECTIVITY_TIMEOUT_MS = 3000;
+/**
+ * Reúne o status do doctor: node/tool/instância (síncronos, disponíveis já no
+ * primeiro render) + credencial e conectividade (assíncronos, resolvidos via
+ * `useEffect` quando há uma instância configurada).
+ *
+ * @param options - Dependências injetáveis. Ver {@link UseDoctorStatusOptions}.
+ * @returns O {@link DoctorStatus} atual — `credentialMethod`/`connectivity`
+ *   começam em `'checking'`/`'skipped'` e são atualizados quando a checagem
+ *   assíncrona resolve (ou `'skipped'` direto, se não há instância configurada).
+ *
+ * @example
+ * const status = useDoctorStatus(); // deps de produção (process.env, fetch real)
+ */
+export declare function useDoctorStatus(options?: UseDoctorStatusOptions): DoctorStatus;

package/dist/surfaces/tui/hooks/use-doctor-status.js

@@ -0,0 +1,123 @@
+/**
+ * Lógica de status do painel `doctor` (M2-12, #35): reúne versão do Node, da
+ * ferramenta, instância configurada, método de credencial em uso e status de
+ * conectividade. Extraída para um hook porque a credencial e a conectividade
+ * são assíncronas (cascata de credenciais, rede) e precisam ser testáveis com
+ * dependências injetadas — nenhum teste deste arquivo toca keychain ou rede
+ * reais.
+ *
+ * Fronteira do core (ADR-005): a única coisa importada daqui é
+ * `describeCredentialSource` + `TOOL_NAME`/`TOOL_VERSION` via `../../../index.js`
+ * — a checagem de conectividade usa `fetch` global diretamente (mesmo padrão
+ * de baixo nível de `client/http.ts`/`config/login.ts`), porque o doctor testa
+ * apenas ALCANÇABILIDADE (GET leve, sem autenticação) — não uma chamada de
+ * API do core, então não há nada do core a reexportar para isso.
+ *
+ * Sem vazamento de segredos: a api_key nunca entra neste módulo — a fonte da
+ * credencial é relatada pelo NOME (`'keyring' | 'file' | 'env' | 'none'`), e a
+ * checagem de conectividade é uma requisição não autenticada.
+ */
+import { useEffect, useState } from 'react';
+import { describeCredentialSource, TOOL_NAME, TOOL_VERSION } from '../../../index.js';
+/** Timeout default do teste de conectividade — curto o bastante para não travar a tela. */
+export const DEFAULT_CONNECTIVITY_TIMEOUT_MS = 3000;
+/**
+ * Checagem default de conectividade: GET leve (sem autenticação) à instância,
+ * com timeout via `AbortController`. Não autenticado de propósito — o doctor
+ * testa alcançabilidade de rede, não valida a credencial (isso já é reportado
+ * separadamente por `credentialMethod`), então a api_key nunca participa
+ * desta requisição.
+ */
+const defaultCheckConnectivity = async (instanceUrl, timeoutMs) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(instanceUrl, { method: 'GET', signal: controller.signal });
+        if (!response.ok) {
+            return { ok: false, detail: `HTTP ${response.status}` };
+        }
+        return { ok: true };
+    }
+    catch (cause) {
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        return { ok: false, detail: reason };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+/** Lê `REDMINE_URL` do ambiente, tratando string vazia como ausente. */
+function instanceFromEnv(env) {
+    const value = env.REDMINE_URL;
+    return value !== undefined && value.length > 0 ? value : undefined;
+}
+/**
+ * Reúne o status do doctor: node/tool/instância (síncronos, disponíveis já no
+ * primeiro render) + credencial e conectividade (assíncronos, resolvidos via
+ * `useEffect` quando há uma instância configurada).
+ *
+ * @param options - Dependências injetáveis. Ver {@link UseDoctorStatusOptions}.
+ * @returns O {@link DoctorStatus} atual — `credentialMethod`/`connectivity`
+ *   começam em `'checking'`/`'skipped'` e são atualizados quando a checagem
+ *   assíncrona resolve (ou `'skipped'` direto, se não há instância configurada).
+ *
+ * @example
+ * const status = useDoctorStatus(); // deps de produção (process.env, fetch real)
+ */
+export function useDoctorStatus(options = {}) {
+    const env = options.env ?? process.env;
+    const nodeVersion = options.nodeVersion ?? process.version;
+    const resolveSource = options.describeCredentialSource ?? describeCredentialSource;
+    const checkConnectivity = options.checkConnectivity ?? defaultCheckConnectivity;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_CONNECTIVITY_TIMEOUT_MS;
+    const instanceUrl = instanceFromEnv(env);
+    const [credentialMethod, setCredentialMethod] = useState(instanceUrl === undefined ? 'none' : 'checking');
+    const [connectivity, setConnectivity] = useState(instanceUrl === undefined ? 'skipped' : 'checking');
+    const [connectivityDetail, setConnectivityDetail] = useState(undefined);
+    useEffect(() => {
+        if (instanceUrl === undefined) {
+            setCredentialMethod('none');
+            setConnectivity('skipped');
+            setConnectivityDetail(undefined);
+            return;
+        }
+        let cancelled = false;
+        setCredentialMethod('checking');
+        setConnectivity('checking');
+        setConnectivityDetail(undefined);
+        resolveSource(instanceUrl, { env }).then((source) => {
+            if (!cancelled)
+                setCredentialMethod(source);
+        }, () => {
+            if (!cancelled)
+                setCredentialMethod('none');
+        });
+        checkConnectivity(instanceUrl, timeoutMs).then((result) => {
+            if (cancelled)
+                return;
+            setConnectivity(result.ok ? 'ok' : 'error');
+            setConnectivityDetail(result.detail);
+        }, (cause) => {
+            if (cancelled)
+                return;
+            setConnectivity('error');
+            setConnectivityDetail(cause instanceof Error ? cause.message : String(cause));
+        });
+        return () => {
+            cancelled = true;
+        };
+        // Reason: `env`/`resolveSource`/`checkConnectivity` são estáveis entre
+        // renders quando as deps de produção são usadas (defaults do módulo, ou
+        // `process.env`) — o efeito só precisa refazer a consulta quando a
+        // instância configurada muda.
+    }, [instanceUrl]);
+    return {
+        nodeVersion,
+        toolName: TOOL_NAME,
+        toolVersion: TOOL_VERSION,
+        instanceUrl,
+        credentialMethod,
+        connectivity,
+        connectivityDetail,
+    };
+}

package/dist/surfaces/tui/hooks/use-escape-interceptor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Consome o interceptor ativo, se houver — chamado pelo roteador (`../app.tsx`)
+ * ANTES de aplicar o `pop()` padrão do Esc global.
+ *
+ * @returns `true` se um interceptor tratou o Esc (o chamador não deve fazer
+ *   `pop()` nesse caso); `false` se nenhum interceptor está registrado (o
+ *   chamador segue com o comportamento padrão).
+ */
+export declare function consumeEscapeInterceptor(): boolean;
+/** Somente para testes: garante um estado limpo entre casos de teste. */
+export declare function resetEscapeInterceptor(): void;
+/**
+ * Registra `onEscape` como o interceptor ativo enquanto `active` for `true`;
+ * desregistra automaticamente quando `active` vira `false` ou o componente
+ * desmonta (limpeza do `useEffect`).
+ *
+ * @param active - Só registra o interceptor enquanto `true` (ex.: campo de
+ *   busca da home aberto).
+ * @param onEscape - Chamado quando `Esc` é pressionado e este interceptor
+ *   está ativo. Identidade pode mudar entre renders (lido via `ref`).
+ *
+ * @example
+ * useEscapeInterceptor(isSearching, closeSearch);
+ */
+export declare function useEscapeInterceptor(active: boolean, onEscape: () => void): void;

package/dist/surfaces/tui/hooks/use-escape-interceptor.js

@@ -0,0 +1,65 @@
+/**
+ * Interceptação pontual do Esc global (M2-07, issue #30).
+ *
+ * O roteador (`../app.tsx`) trata `Esc` globalmente como `pop()` da pilha de
+ * navegação (volta para a tela anterior). A busca inline da home
+ * (`../screens/home.tsx`) precisa que `Esc`, enquanto o campo de busca está
+ * ativo, feche a busca e restaure a lista original — em vez de desempilhar a
+ * home e voltar para a tela de onde ela veio. Sem esse desvio, o usuário
+ * sairia da home sem querer só por tentar limpar o texto da busca.
+ *
+ * Implementado como uma única referência mutável em nível de módulo, não um
+ * Context/Provider: a TUI só sustenta UMA tela ativa por vez (arquitetura de
+ * pilha, `../navigation.tsx`), então nunca há mais de um interceptor
+ * concorrente de fato — um Provider/Context inteiro seria complexidade sem
+ * benefício para esse caso. O mecanismo é genérico o bastante para qualquer
+ * tela futura que precise do mesmo desvio pontual do Esc global.
+ */
+import { useEffect, useRef } from 'react';
+/** Interceptor ativo no momento, ou `undefined` se nenhuma tela registrou um. */
+let activeInterceptor;
+/**
+ * Consome o interceptor ativo, se houver — chamado pelo roteador (`../app.tsx`)
+ * ANTES de aplicar o `pop()` padrão do Esc global.
+ *
+ * @returns `true` se um interceptor tratou o Esc (o chamador não deve fazer
+ *   `pop()` nesse caso); `false` se nenhum interceptor está registrado (o
+ *   chamador segue com o comportamento padrão).
+ */
+export function consumeEscapeInterceptor() {
+    if (activeInterceptor === undefined) {
+        return false;
+    }
+    activeInterceptor();
+    return true;
+}
+/** Somente para testes: garante um estado limpo entre casos de teste. */
+export function resetEscapeInterceptor() {
+    activeInterceptor = undefined;
+}
+/**
+ * Registra `onEscape` como o interceptor ativo enquanto `active` for `true`;
+ * desregistra automaticamente quando `active` vira `false` ou o componente
+ * desmonta (limpeza do `useEffect`).
+ *
+ * @param active - Só registra o interceptor enquanto `true` (ex.: campo de
+ *   busca da home aberto).
+ * @param onEscape - Chamado quando `Esc` é pressionado e este interceptor
+ *   está ativo. Identidade pode mudar entre renders (lido via `ref`).
+ *
+ * @example
+ * useEscapeInterceptor(isSearching, closeSearch);
+ */
+export function useEscapeInterceptor(active, onEscape) {
+    const onEscapeRef = useRef(onEscape);
+    onEscapeRef.current = onEscape;
+    useEffect(() => {
+        if (!active) {
+            return;
+        }
+        activeInterceptor = () => onEscapeRef.current();
+        return () => {
+            activeInterceptor = undefined;
+        };
+    }, [active]);
+}