redmine-context 1.0.0

package/dist/surfaces/tui/hooks/use-issue-search.js

@@ -0,0 +1,168 @@
+/**
+ * Lógica de dados da busca inline da home (M2-07, issue #30): busca textual
+ * + filtro rápido de status via `fetchIssueSearch` do core — orquestração
+ * que já combina filtros estruturados (`assigned_to_id=me` + `status_id`)
+ * com full-text best-effort (`/search.json`, com degradação sinalizada no
+ * payload quando indisponível). Extraído para um hook próprio (em vez de
+ * estender `use-my-issues.ts`) porque o gatilho é bem diferente: `useMyIssues`
+ * busca uma vez ao montar, enquanto esta busca é retriggada a cada mudança de
+ * `query`/`statusFilter` — mas reaproveita deliberadamente o MESMO formato de
+ * `MyIssuesState` (`loading`/`error-network`/`error-forbidden`/`auth-aborted`
+ * + um estado "carregado") para a tela (`../screens/home.tsx`) tratar os dois
+ * hooks de forma consistente.
+ *
+ * Fronteira do core (ADR-005): a única coisa importada daqui é
+ * `../../../index.js` (`fetchIssueSearch`/`resolveApiKey`) — a tela só
+ * formata os estados, nunca chama o core diretamente.
+ *
+ * Debounce de digitação: `query` normalmente muda a cada tecla (controlado
+ * pelo `TextInput` da home); disparar `fetchIssueSearch` a cada tecla geraria
+ * uma chamada de rede por caractere digitado. Este hook espera
+ * `debounceMs` (300ms em produção, {@link DEFAULT_DEBOUNCE_MS}) de silêncio
+ * antes de efetivamente buscar — implementado com um `setTimeout` reagendado
+ * a cada mudança de `query` (cancelado no cleanup do efeito).
+ *
+ * 401 via `useAuthGuard` (M2-13, #36, mandatório para qualquer chamada
+ * autenticada ao core): a busca é envolvida por `guard()`, mesmo padrão de
+ * `use-my-issues.ts` — em 401, o estado permanece `loading` durante o
+ * re-auth e a busca é refeita automaticamente após o re-login. Abandono do
+ * re-login (Esc) vira o estado `auth-aborted`.
+ */
+import { useEffect, useRef, useState } from 'react';
+import { fetchIssueSearch, resolveApiKey, RedmineForbiddenError, } from '../../../index.js';
+import { useEnvFallbackAllowed } from '../instance.js';
+import { ReAuthAbortedError, useAuthGuard } from './use-auth-guard.js';
+/** Debounce (ms) default aplicado a `query` antes de disparar a busca. */
+export const DEFAULT_DEBOUNCE_MS = 300;
+/** Mapeia o filtro rápido de status para o `status_id` de `/issues.json` (`*` = todas). */
+function statusIdFor(filter) {
+    if (filter === 'open')
+        return 'open';
+    if (filter === 'closed')
+        return 'closed';
+    return '*';
+}
+/** Lê `REDMINE_URL` do ambiente, tratando string vazia como ausente (mesma convenção do doctor/home). */
+function instanceFromEnv(env) {
+    const value = env.REDMINE_URL;
+    return value !== undefined && value.length > 0 ? value : undefined;
+}
+/**
+ * Busca issues (filtros + full-text best-effort) via o core, com debounce de
+ * digitação e o filtro rápido de status.
+ *
+ * @param query - Termo full-text bruto (não debounced) — tipicamente o
+ *   `value` do `TextInput` da busca da home.
+ * @param statusFilter - Filtro rápido de status (ver {@link SearchStatusFilter}).
+ * @param options - Dependências injetáveis. Ver {@link UseIssueSearchOptions}.
+ * @returns O {@link UseIssueSearchResult} atual.
+ *
+ * @example
+ * const { state, clear } = useIssueSearch(query, statusFilter); // deps de produção
+ */
+export function useIssueSearch(query, statusFilter, options = {}) {
+    const env = options.env ?? process.env;
+    const resolve = options.resolveApiKey ?? resolveApiKey;
+    const runSearch = options.fetchIssueSearch ?? fetchIssueSearch;
+    const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    // Fix do padrão #120 (use-my-issues.ts): qualquer chamada autenticada ao
+    // core passa por `guard()` — 401 dispara o re-login e retoma a busca.
+    const { guard } = useAuthGuard();
+    // SEGURANÇA (#187): origem config (URL persistida) → sem env-key instance-agnóstica.
+    const allowEnvFallback = useEnvFallbackAllowed();
+    const [state, setState] = useState({ status: 'idle' });
+    const [debouncedQuery, setDebouncedQuery] = useState(query);
+    // Debounce: só propaga `query` para `debouncedQuery` depois de `debounceMs`
+    // de silêncio — reagendado a cada tecla (cleanup cancela o timer anterior).
+    useEffect(() => {
+        const timer = setTimeout(() => {
+            setDebouncedQuery(query);
+        }, debounceMs);
+        return () => {
+            clearTimeout(timer);
+        };
+    }, [query, debounceMs]);
+    useEffect(() => {
+        let cancelled = false;
+        const trimmed = debouncedQuery.trim();
+        // Nada para buscar: sem texto E sem filtro de status ativo. `idle` evita
+        // uma chamada de rede assim que o campo de busca abre vazio.
+        if (trimmed.length === 0 && statusFilter === 'all') {
+            setState({ status: 'idle' });
+            return;
+        }
+        setState({ status: 'loading' });
+        const instanceUrl = instanceFromEnv(env);
+        if (instanceUrl === undefined) {
+            setState({
+                status: 'error-network',
+                message: 'Instância não configurada (defina REDMINE_URL).',
+            });
+            return;
+        }
+        const cascadeOptions = { env, allowEnvFallback };
+        void (async () => {
+            try {
+                const apiKey = await resolve(instanceUrl, cascadeOptions);
+                if (apiKey === undefined) {
+                    if (!cancelled) {
+                        setState({
+                            status: 'error-network',
+                            message: `Nenhuma credencial encontrada para ${instanceUrl}.`,
+                        });
+                    }
+                    return;
+                }
+                const result = await guard(() => runSearch({
+                    baseUrl: instanceUrl,
+                    apiKey,
+                    filters: { assigned_to_id: 'me', status_id: statusIdFor(statusFilter) },
+                    query: trimmed.length > 0 ? trimmed : undefined,
+                }));
+                if (cancelled)
+                    return;
+                setState({
+                    status: 'loaded',
+                    content: result.content,
+                    count: result.count,
+                    degraded: result.degraded,
+                    warnings: result.warnings,
+                });
+            }
+            catch (cause) {
+                if (cancelled)
+                    return;
+                if (cause instanceof RedmineForbiddenError) {
+                    setState({
+                        status: 'error-forbidden',
+                        message: 'Sem permissão para buscar issues nesta instância (403).',
+                    });
+                    return;
+                }
+                if (cause instanceof ReAuthAbortedError) {
+                    setState({
+                        status: 'auth-aborted',
+                        message: 'login cancelado — pressione f/digite de novo para tentar',
+                    });
+                    return;
+                }
+                const message = cause instanceof Error ? cause.message : String(cause);
+                setState({ status: 'error-network', message });
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+        // Reason: `env`/`resolve`/`runSearch`/`guard` são estáveis entre renders
+        // com as deps de produção (defaults do módulo, ou `process.env`, ou a
+        // identidade estável de `useAuthGuard().guard`) — o efeito só precisa
+        // refazer a busca quando `debouncedQuery`/`statusFilter` mudam.
+    }, [debouncedQuery, statusFilter, env, allowEnvFallback, resolve, runSearch, guard]);
+    // Handler ESTÁVEL (useCallback via ref indireta não é necessário aqui: sem
+    // dependências externas mutáveis, `clear` já é estável por construção).
+    const clear = useRef(() => {
+        setDebouncedQuery('');
+        setState({ status: 'idle' });
+    }).current;
+    return { state, clear };
+}

package/dist/surfaces/tui/hooks/use-list-navigation.d.ts

@@ -0,0 +1,44 @@
+import { type Dispatch, type SetStateAction } from 'react';
+/** Opções do hook — todas opcionais. */
+export interface UseListNavigationOptions {
+    /**
+     * Chamado com o índice atual quando o usuário confirma a seleção (Enter).
+     * Opcional: uma lista somente de exibição pode omitir e ler apenas
+     * `selectedIndex`.
+     */
+    onSelect?: (index: number) => void;
+    /**
+     * Desliga a captura de teclado deste hook quando `false` (mesmo padrão de
+     * `isActive` do `../components/text-input.tsx`) — necessário quando outro
+     * campo da mesma tela está temporariamente "dono" do teclado (ex.: a busca
+     * inline da home, M2-07/#30). Default: `true`.
+     */
+    isActive?: boolean;
+    /**
+     * Cursor inicial — default `0`. Aplicado assim que `itemCount` deixa de
+     * ser `0` pela primeira vez (clampado); mudanças subsequentes NÃO
+     * reposicionam o cursor (preservação de seleção entre remounts — #31).
+     */
+    initialIndex?: number;
+}
+/** Valor retornado pelo hook. */
+export interface UseListNavigationResult {
+    /** Índice selecionado (0-based), sempre dentro de `[0, itemCount - 1]`. */
+    selectedIndex: number;
+    /** Setter direto — útil para resetar a seleção quando a lista troca de conteúdo (ex.: novo filtro). */
+    setSelectedIndex: Dispatch<SetStateAction<number>>;
+}
+/**
+ * Hook de navegação em lista: setas/`j`/`k` movem `selectedIndex` com wrap,
+ * Enter confirma via `onSelect`.
+ *
+ * @param itemCount Total de itens navegáveis. `0` desativa a navegação (sem
+ *   quebrar — apenas nada acontece, a lista está vazia).
+ * @param options Ver {@link UseListNavigationOptions}.
+ *
+ * @example
+ * const { selectedIndex } = useListNavigation(issues.length, {
+ *   onSelect: (index) => push('issue-detail'),
+ * });
+ */
+export declare function useListNavigation(itemCount: number, options?: UseListNavigationOptions): UseListNavigationResult;

package/dist/surfaces/tui/hooks/use-list-navigation.js

@@ -0,0 +1,82 @@
+/**
+ * Padrão reutilizável de navegação em listas da TUI (M2-04).
+ *
+ * Encapsula o `useInput()` comum a toda lista selecionável: setas ↑/↓ (ou
+ * `j`/`k`, atalhos vim-like opcionais) movem `selectedIndex` com wrap nas
+ * pontas; Enter confirma via `onSelect`. Cada tela de lista (M2-06 é a
+ * primeira a consumir isso) só precisa chamar o hook com o total de itens —
+ * nenhuma tela reimplementa esse teclado do zero.
+ *
+ * Esc (voltar) e Ctrl+C (sair) NÃO são tratados aqui — são atalhos globais
+ * do roteador (`../app.tsx`, `use-exit-guard.ts`), fora do escopo de uma
+ * lista específica.
+ */
+import { useInput } from 'ink';
+import { useEffect, useRef, useState } from 'react';
+/**
+ * Hook de navegação em lista: setas/`j`/`k` movem `selectedIndex` com wrap,
+ * Enter confirma via `onSelect`.
+ *
+ * @param itemCount Total de itens navegáveis. `0` desativa a navegação (sem
+ *   quebrar — apenas nada acontece, a lista está vazia).
+ * @param options Ver {@link UseListNavigationOptions}.
+ *
+ * @example
+ * const { selectedIndex } = useListNavigation(issues.length, {
+ *   onSelect: (index) => push('issue-detail'),
+ * });
+ */
+export function useListNavigation(itemCount, options = {}) {
+    const { onSelect, isActive = true, initialIndex } = options;
+    // Ref (não dep de efeito): a aplicação do `initialIndex` deve acontecer uma
+    // única vez, na primeira vez que a lista deixa de estar vazia — mesmo que
+    // `initialIndex` mude entre renders (ex.: o contexto de origem re-renderiza
+    // por outro motivo).
+    const appliedInitialRef = useRef(false);
+    const [selectedIndex, setSelectedIndex] = useState(() => {
+        if (itemCount <= 0) {
+            // Nada para clampar ainda — o efeito abaixo aplica `initialIndex` assim
+            // que `itemCount` deixar de ser 0 (ex.: lista ainda carregando).
+            return 0;
+        }
+        appliedInitialRef.current = true;
+        return Math.min(Math.max(initialIndex ?? 0, 0), itemCount - 1);
+    });
+    useInput((input, key) => {
+        if (itemCount <= 0) {
+            return;
+        }
+        if (key.upArrow || input === 'k') {
+            setSelectedIndex((current) => (current - 1 + itemCount) % itemCount);
+            return;
+        }
+        if (key.downArrow || input === 'j') {
+            setSelectedIndex((current) => (current + 1) % itemCount);
+            return;
+        }
+        if (key.return) {
+            onSelect?.(selectedIndex);
+        }
+    }, { isActive });
+    // Reason: mantém `selectedIndex` dentro dos limites quando `itemCount`
+    // encolhe (ex.: um filtro reduz a lista) — evita um índice "fantasma" que
+    // aponta para fora do array de itens da tela. Também é o gatilho de
+    // aplicação do `initialIndex` (#31): na primeira vez que `itemCount` deixa
+    // de ser 0, usa `initialIndex` (se informado) como base em vez do cursor
+    // atual — cobre tanto o caso síncrono (lista já não-vazia no primeiro
+    // render) quanto o assíncrono (lista carrega depois, ex.: `home.tsx`).
+    useEffect(() => {
+        setSelectedIndex((current) => {
+            if (itemCount <= 0) {
+                return 0;
+            }
+            const base = !appliedInitialRef.current && initialIndex !== undefined ? initialIndex : current;
+            appliedInitialRef.current = true;
+            return Math.min(Math.max(base, 0), itemCount - 1);
+        });
+        // Reason: `initialIndex` é intencionalmente OMITIDO das deps — é lido só
+        // na aplicação única controlada por `appliedInitialRef`, nunca deve
+        // reexecutar este efeito por si só (ver o JSDoc da opção).
+    }, [itemCount]);
+    return { selectedIndex, setSelectedIndex };
+}

package/dist/surfaces/tui/hooks/use-media-binaries.d.ts

@@ -0,0 +1,24 @@
+import { diagnoseBinaries, type BinaryDiagnosis } from '../../../index.js';
+/** Estado da seção "Binários de mídia": carregando + o resultado do diagnóstico. */
+export interface MediaBinariesState {
+    /** `true` enquanto o diagnóstico assíncrono ainda não resolveu. */
+    loading: boolean;
+    /** Binários diagnosticados (vazio até resolver, ou se o diagnóstico falhar). */
+    binaries: BinaryDiagnosis[];
+}
+/** Dependências injetáveis do hook — todas opcionais, com defaults de produção. */
+export interface UseMediaBinariesOptions {
+    /** Executa o diagnóstico; default `diagnoseBinaries` do core. */
+    diagnose?: typeof diagnoseBinaries;
+}
+/**
+ * Diagnostica os binários de mídia uma vez, no mount. Nunca lança: se o
+ * diagnóstico rejeitar, sai do loading com uma lista vazia (a tela apenas não
+ * exibe binários — degradação graciosa).
+ *
+ * @param options - Deps injetáveis. Ver {@link UseMediaBinariesOptions}.
+ * @returns O {@link MediaBinariesState} atual — começa em `loading: true`.
+ * @example
+ * const { loading, binaries } = useMediaBinaries();
+ */
+export declare function useMediaBinaries(options?: UseMediaBinariesOptions): MediaBinariesState;

package/dist/surfaces/tui/hooks/use-media-binaries.js

@@ -0,0 +1,44 @@
+/**
+ * Lógica assíncrona da seção "Binários de mídia" da tela doctor (M3-11, #53).
+ *
+ * Extraída para um hook porque o diagnóstico (`diagnoseBinaries`) é assíncrono
+ * (localiza binários no filesystem e lê versão via subprocesso) e precisa ser
+ * testável com a dependência injetada — nenhum teste deste arquivo consulta um
+ * binário real.
+ *
+ * Fronteira do core (ADR-005): a única coisa importada daqui é `diagnoseBinaries`
+ * via `../../../index.js` — a mesma superfície pública que a CLI consome para o
+ * comando `doctor`. Sem reimplementar detecção na TUI.
+ */
+import { useEffect, useState } from 'react';
+import { diagnoseBinaries } from '../../../index.js';
+/**
+ * Diagnostica os binários de mídia uma vez, no mount. Nunca lança: se o
+ * diagnóstico rejeitar, sai do loading com uma lista vazia (a tela apenas não
+ * exibe binários — degradação graciosa).
+ *
+ * @param options - Deps injetáveis. Ver {@link UseMediaBinariesOptions}.
+ * @returns O {@link MediaBinariesState} atual — começa em `loading: true`.
+ * @example
+ * const { loading, binaries } = useMediaBinaries();
+ */
+export function useMediaBinaries(options = {}) {
+    const diagnose = options.diagnose ?? diagnoseBinaries;
+    const [state, setState] = useState({ loading: true, binaries: [] });
+    useEffect(() => {
+        let cancelled = false;
+        diagnose().then((binaries) => {
+            if (!cancelled)
+                setState({ loading: false, binaries });
+        }, () => {
+            if (!cancelled)
+                setState({ loading: false, binaries: [] });
+        });
+        return () => {
+            cancelled = true;
+        };
+        // Reason: `diagnose` é estável entre renders (default do módulo, ou uma dep
+        // injetada estável no teste) — o diagnóstico só precisa rodar uma vez.
+    }, [diagnose]);
+    return state;
+}

package/dist/surfaces/tui/hooks/use-my-issues.d.ts

@@ -0,0 +1,66 @@
+import { createHttpClient, listIssues, resolveApiKey } from '../../../index.js';
+/** Issue resumida exibida numa linha da lista da home — só os campos usados por `IssueRow`. */
+export interface MyIssue {
+    /** Id numérico da issue (`#id` na linha). */
+    id: number;
+    /** Assunto da issue (truncado na exibição, nunca aqui). */
+    subject: string;
+    /** Nome do status (badge colorido por tema). */
+    statusName: string;
+}
+/**
+ * Estado da busca de "minhas issues", consumido por `../screens/home.tsx`.
+ * `loading`/`empty`/`error-network`/`error-forbidden` são os 4 estados
+ * visuais distintos exigidos pela AC da #29; `loaded` é o estado "normal"
+ * com a lista preenchida. `auth-aborted` (fix do review #120) é um 5º
+ * estado leve, distinto de `error-network`: o usuário viu o prompt de
+ * re-login (401 tratado por `useAuthGuard`) e escolheu conscientemente (Esc)
+ * não reautenticar — não é uma falha inesperada, então não usa o vocabulário
+ * de erro; `retry` (tecla `r`) segue disponível para tentar de novo.
+ */
+export type MyIssuesState = {
+    status: 'loading';
+} | {
+    status: 'empty';
+} | {
+    status: 'loaded';
+    issues: MyIssue[];
+} | {
+    status: 'error-network';
+    message: string;
+} | {
+    status: 'error-forbidden';
+    message: string;
+} | {
+    status: 'auth-aborted';
+    message: string;
+};
+/** Dependências injetáveis do hook — todas opcionais, com defaults de produção via o core. */
+export interface UseMyIssuesOptions {
+    /** Ambiente consultado para `REDMINE_URL`; default `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Resolve a api_key pela cascata M2; default `resolveApiKey` do core. */
+    resolveApiKey?: typeof resolveApiKey;
+    /** Constrói o client HTTP autenticado; default `createHttpClient` do core. */
+    createHttpClient?: typeof createHttpClient;
+    /** Lista issues paginando `/issues.json`; default `listIssues` do core. */
+    listIssues?: typeof listIssues;
+}
+/** Valor retornado pelo hook. */
+export interface UseMyIssuesResult {
+    /** Estado atual da busca (ver {@link MyIssuesState}). */
+    state: MyIssuesState;
+    /** Reexecuta a busca do zero (`status` volta a `loading`) — usado pelo retry (tecla `r`) dos estados de erro. */
+    retry: () => void;
+}
+/**
+ * Lista "minhas issues" (`assigned_to_id=me`) via o core.
+ *
+ * @param options - Dependências injetáveis. Ver {@link UseMyIssuesOptions}.
+ * @returns O {@link UseMyIssuesResult} atual — `state.status` começa em
+ *   `'loading'` e é atualizado quando a busca assíncrona resolve.
+ *
+ * @example
+ * const { state, retry } = useMyIssues(); // deps de produção (process.env, core real)
+ */
+export declare function useMyIssues(options?: UseMyIssuesOptions): UseMyIssuesResult;

package/dist/surfaces/tui/hooks/use-my-issues.js

@@ -0,0 +1,151 @@
+/**
+ * Lógica de dados da tela home (M2-06, #29): lista "minhas issues"
+ * (`assigned_to_id=me`) via o core — resolve a credencial pela cascata
+ * (`resolveApiKey`), monta um client HTTP autenticado (`createHttpClient`) e
+ * pagina `/issues.json` (`listIssues`). Extraída para um hook porque toda a
+ * busca é assíncrona e precisa ser testável com dependências injetadas —
+ * nenhum teste deste arquivo toca keychain ou rede reais.
+ *
+ * Fronteira do core (ADR-005): a única coisa importada daqui é
+ * `../../../index.js` — a tela (`../screens/home.tsx`) só formata os 5
+ * estados visuais (`loading`/`empty`/`error-network`/`error-forbidden`/
+ * `auth-aborted`) mais o estado "com itens" (`loaded`), nunca chama o core
+ * diretamente.
+ *
+ * A instância vem de `REDMINE_URL` (mesma convenção do doctor/CLI/MCP —
+ * ver `use-doctor-status.ts`), lida do `env` injetado (default `process.env`).
+ *
+ * Fix do review do PR #120: esta era a primeira tela de dados (#29+) a
+ * chamar o core autenticado SEM passar pelo `useAuthGuard` (M2-13, #36,
+ * mandatório para qualquer chamada assim, ver `./use-auth-guard.ts`) — um 401
+ * (api_key expirada/revogada) virava um `error-network` cru em vez de
+ * disparar o re-login e retomar a busca automaticamente. A busca (`listIssues`)
+ * agora é envolvida por `guard()`: em 401, o estado permanece `loading`
+ * durante o re-auth (a `Promise` de `guard()` só resolve/rejeita depois que o
+ * usuário loga de novo, ver `use-auth-guard.ts`) e a lista carrega assim que o
+ * re-login tem sucesso, sem ação extra do usuário. Se o re-login for
+ * abandonado (Esc), `guard()` rejeita com `ReAuthAbortedError` — tratado aqui
+ * como o estado próprio `auth-aborted` (não um erro cru), com `retry` (tecla
+ * `r`, já existente) disponível para tentar de novo.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { createHttpClient, listIssues, resolveApiKey, RedmineForbiddenError, } from '../../../index.js';
+import { useEnvFallbackAllowed } from '../instance.js';
+import { ReAuthAbortedError, useAuthGuard } from './use-auth-guard.js';
+/** Estreita `unknown` para um objeto indexável, ou `undefined` se não for. */
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : undefined;
+}
+/**
+ * Converte um payload bruto de issue em {@link MyIssue}; `undefined` se
+ * `subject`/`status.name` faltarem ou tiverem um shape inesperado — a linha
+ * é simplesmente omitida da lista em vez de quebrar a tela inteira.
+ */
+function toMyIssue(raw) {
+    const subject = raw.subject;
+    const statusName = asRecord(raw.status)?.name;
+    if (typeof subject !== 'string' || typeof statusName !== 'string') {
+        return undefined;
+    }
+    return { id: raw.id, subject, statusName };
+}
+/** Lê `REDMINE_URL` do ambiente, tratando string vazia como ausente (mesma convenção do doctor). */
+function instanceFromEnv(env) {
+    const value = env.REDMINE_URL;
+    return value !== undefined && value.length > 0 ? value : undefined;
+}
+/**
+ * Lista "minhas issues" (`assigned_to_id=me`) via o core.
+ *
+ * @param options - Dependências injetáveis. Ver {@link UseMyIssuesOptions}.
+ * @returns O {@link UseMyIssuesResult} atual — `state.status` começa em
+ *   `'loading'` e é atualizado quando a busca assíncrona resolve.
+ *
+ * @example
+ * const { state, retry } = useMyIssues(); // deps de produção (process.env, core real)
+ */
+export function useMyIssues(options = {}) {
+    const env = options.env ?? process.env;
+    const resolve = options.resolveApiKey ?? resolveApiKey;
+    const buildClient = options.createHttpClient ?? createHttpClient;
+    const fetchIssues = options.listIssues ?? listIssues;
+    // Fix do review #120: a busca é uma chamada autenticada ao core — `guard`
+    // (identidade estável, `useCallback` sem deps em `use-auth-guard.ts`) trata
+    // 401 disparando o re-login e retomando a operação automaticamente.
+    const { guard } = useAuthGuard();
+    // SEGURANÇA (#187): se a instância veio da persistida (origem config), a
+    // REDMINE_API_KEY instance-agnóstica NÃO pode ser usada (só credencial pinada).
+    const allowEnvFallback = useEnvFallbackAllowed();
+    const [state, setState] = useState({ status: 'loading' });
+    const [reloadToken, setReloadToken] = useState(0);
+    const retry = useCallback(() => {
+        setReloadToken((current) => current + 1);
+    }, []);
+    useEffect(() => {
+        let cancelled = false;
+        setState({ status: 'loading' });
+        const instanceUrl = instanceFromEnv(env);
+        if (instanceUrl === undefined) {
+            setState({
+                status: 'error-network',
+                message: 'Instância não configurada (defina REDMINE_URL).',
+            });
+            return;
+        }
+        const cascadeOptions = { env, allowEnvFallback };
+        void (async () => {
+            try {
+                const apiKey = await resolve(instanceUrl, cascadeOptions);
+                if (apiKey === undefined) {
+                    if (!cancelled) {
+                        setState({
+                            status: 'error-network',
+                            message: `Nenhuma credencial encontrada para ${instanceUrl}.`,
+                        });
+                    }
+                    return;
+                }
+                const http = buildClient({ baseUrl: instanceUrl, apiKey });
+                // Fix do review #120: envolvida por `guard()` — em 401, a Promise só
+                // resolve após o re-login ter sucesso e a busca ser refeita
+                // automaticamente; o estado do hook permanece `loading` enquanto isso.
+                const raw = await guard(() => fetchIssues(http, { filters: { assigned_to_id: 'me' } }));
+                if (cancelled)
+                    return;
+                const issues = raw.map(toMyIssue).filter((issue) => issue !== undefined);
+                setState(issues.length === 0 ? { status: 'empty' } : { status: 'loaded', issues });
+            }
+            catch (cause) {
+                if (cancelled)
+                    return;
+                if (cause instanceof RedmineForbiddenError) {
+                    setState({
+                        status: 'error-forbidden',
+                        message: 'Sem permissão para listar suas issues nesta instância (403).',
+                    });
+                    return;
+                }
+                if (cause instanceof ReAuthAbortedError) {
+                    // Fix do review #120: abandono consciente do re-login (Esc) — estado
+                    // neutro dedicado, não um erro cru. `retry` (tecla `r`, já existente
+                    // na tela) refaz a busca do zero.
+                    setState({
+                        status: 'auth-aborted',
+                        message: 'login cancelado — pressione r para tentar de novo',
+                    });
+                    return;
+                }
+                const message = cause instanceof Error ? cause.message : String(cause);
+                setState({ status: 'error-network', message });
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+        // Reason: `env`/`resolve`/`buildClient`/`fetchIssues`/`guard` são estáveis
+        // entre renders com as deps de produção (defaults do módulo, ou
+        // `process.env`, ou a identidade estável de `useAuthGuard().guard`) — o
+        // efeito só precisa refazer a busca quando `reloadToken` muda (retry).
+    }, [env, allowEnvFallback, resolve, buildClient, fetchIssues, guard, reloadToken]);
+    return { state, retry };
+}

package/dist/surfaces/tui/hooks/use-onboarding-callbacks.d.ts

@@ -0,0 +1,11 @@
+import { type SettingsStore } from '../../../index.js';
+import type { OnboardingCallbacks } from '../screens/onboarding/onboarding-context.js';
+/**
+ * Monta os callbacks reais de onboarding — injetados em
+ * `<OnboardingProvider callbacks={...}>` por `../app.tsx`.
+ *
+ * @example
+ * const callbacks = useOnboardingCallbacks();
+ * return <OnboardingProvider callbacks={callbacks}>...</OnboardingProvider>;
+ */
+export declare function useOnboardingCallbacks(settings?: SettingsStore): OnboardingCallbacks;