redmine-context 1.0.0

package/dist/surfaces/mcp/server.js

@@ -0,0 +1,427 @@
+/**
+ * Superfície MCP (stdio) do `redmine-context` (M1-12).
+ *
+ * Expõe a tool read-only `get_issue_context(issue_id, format?)`, que reutiliza a
+ * orquestração `fetchIssueBundle` do core. Segue a mesma fronteira da CLI
+ * (ADR-005): importa o core EXCLUSIVAMENTE por `../../index.js`; nenhum módulo
+ * interno é acessado diretamente (regra eslint `no-restricted-imports`).
+ *
+ * Segurança: NENHUMA tool aceita URL/host arbitrário — a instância vem sempre da
+ * config/env do processo (`REDMINE_URL`; sem ela, a URL persistida no `login`,
+ * #187) + cascata de credencial. Quando a URL vem da persistida (fonte mutável),
+ * a credencial de AMBIENTE (`REDMINE_API_KEY`, instance-agnóstica) é DESABILITADA
+ * — só credencial pinada à instância (keychain/arquivo) é aceita, impedindo que um
+ * `settings.json` adulterado exfiltre a chave (ver `resolveInstance`). No transporte
+ * stdio o protocolo ocupa o stdout, portanto todo diagnóstico vai para stderr.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import * as core from '../../index.js';
+import { fenceBlock } from '../../index.js';
+/** Interpreta `REDMINE_INSECURE` (`1`/`true`, case-insensitive) como boolean. */
+function parseInsecure(env) {
+    const raw = env.REDMINE_INSECURE;
+    return raw !== undefined && /^(1|true)$/i.test(raw.trim());
+}
+/** Nome canônico da tool de contexto de issue. */
+export const TOOL_NAME = 'get_issue_context';
+/** Nome canônico da tool de busca de issues. */
+export const SEARCH_TOOL_NAME = 'search_issues';
+/** Nome canônico da tool de texto de anexo. */
+export const ATTACHMENT_TOOL_NAME = 'get_attachment_text';
+/** Limite default de resultados da tool `search_issues` (documentado no schema). */
+export const SEARCH_DEFAULT_LIMIT = 25;
+/** Teto de resultados aceito pela tool `search_issues`. */
+const SEARCH_MAX_LIMIT = 100;
+/** Schema zod dos argumentos da tool (sem URL/host: a instância vem da env). */
+const INPUT_SCHEMA = {
+    issue_id: z.number().int().positive().describe('Identificador numérico da issue no Redmine'),
+    format: z
+        .enum(['markdown', 'json'])
+        .optional()
+        .describe("Formato de saída: 'markdown' (padrão) ou 'json'"),
+    extract_attachments: z
+        .boolean()
+        .optional()
+        .describe('Extrai o texto (OCR) dos anexos de imagem e o embute no bundle. Default: false (adiciona latência de download+OCR). O M4 traz o modo cache-first/processing.'),
+};
+/** Schema zod da tool `get_attachment_text` (read-only, sem URL/host). */
+const ATTACHMENT_INPUT_SCHEMA = {
+    issue_id: z.number().int().positive().describe('Identificador numérico da issue que contém o anexo'),
+    attachment_id: z.number().int().positive().describe('Identificador numérico do anexo a extrair'),
+};
+/** Schema zod da tool `search_issues` (read-only, sem URL/host). */
+const SEARCH_INPUT_SCHEMA = {
+    query: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Termo full-text via /search.json (best-effort). Se a busca falhar, degrada para os filtros estruturados com aviso.'),
+    project_id: z.number().int().positive().optional().describe('Filtro estruturado project_id'),
+    status_id: z
+        .union([z.number().int(), z.string()])
+        .optional()
+        .describe("Filtro status_id: um id, 'open', 'closed' ou '*'"),
+    assigned_to_id: z
+        .union([z.number().int(), z.string()])
+        .optional()
+        .describe("Filtro assigned_to_id: um id ou 'me'"),
+    updated_on: z
+        .string()
+        .optional()
+        .describe('Filtro updated_on no formato do Redmine (ex.: >=2026-01-01, <=2026-12-31)'),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(SEARCH_MAX_LIMIT)
+        .optional()
+        .describe(`Máximo de resultados paginados (default ${SEARCH_DEFAULT_LIMIT}, teto ${SEARCH_MAX_LIMIT})`),
+};
+/** Extrai uma mensagem legível de um erro desconhecido. */
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Monta um `CallToolResult` de erro (isError) com uma única mensagem de texto. */
+function errorResult(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+/** Monta um `CallToolResult` de sucesso com o bundle serializado. */
+function textResult(content) {
+    return { content: [{ type: 'text', text: content }] };
+}
+/**
+ * Traduz um erro da operação em uma mensagem MCP clara e tipada.
+ *
+ * 403/404/401 recebem texto orientado; os demais propagam a mensagem original.
+ * Nenhum resultado é cacheado aqui — o erro é sempre recomputado por chamada.
+ *
+ * @param error - Erro capturado durante o fetch/bundle.
+ * @param issueId - Id da issue para compor a mensagem.
+ * @returns A mensagem a ser exibida no `isError`.
+ */
+function typedErrorMessage(error, issueId) {
+    if (error instanceof core.RedmineNotFoundError) {
+        return `Issue #${issueId} não encontrada (404). Verifique o id na instância configurada.`;
+    }
+    if (error instanceof core.RedmineForbiddenError) {
+        return `Acesso negado à issue #${issueId} (403). A credencial não tem permissão para vê-la.`;
+    }
+    if (error instanceof core.RedmineAuthError) {
+        return 'Falha de autenticação (401). Verifique a credencial em REDMINE_API_KEY.';
+    }
+    return messageOf(error);
+}
+/**
+ * Resolve `REDMINE_URL` + credencial da env (nunca de argumentos das tools).
+ *
+ * Fonte única da política "sem URL/host nos argumentos": ambas as tools passam
+ * por aqui. Em falha devolve um {@link CallToolResult} de erro orientado; em
+ * sucesso, a instância pronta para uso.
+ *
+ * @param deps - Ver {@link McpServerDeps}.
+ * @returns A instância resolvida, ou um CallToolResult de erro (`isError`).
+ */
+async function resolveInstance(deps) {
+    // REDMINE_URL tem precedência; sem ela, cai na URL persistida no login (#187),
+    // via o resolvedor único (trata string vazia como ausente). Continua UMA
+    // instância configurada (env/persistida) — nunca de argumento de tool.
+    const persistedUrl = deps.settings ? await deps.settings.getInstanceUrl() : undefined;
+    const resolved = core.resolveInstanceUrl({ envUrl: deps.env.REDMINE_URL, persistedUrl });
+    if (resolved === undefined) {
+        return errorResult('Instância não configurada. Defina REDMINE_URL no ambiente do processo ou rode `redmine-context login`.');
+    }
+    const { url: baseUrl, origin } = resolved;
+    // Auditabilidade (#187): quando a instância NÃO veio da env (fallback persistido),
+    // registra a URL em uso no diagnóstico (o stdout é do protocolo → vai ao stderr).
+    if (origin !== 'env') {
+        deps.log?.(`instância resolvida via ${origin}: ${baseUrl}`);
+    }
+    let apiKey;
+    try {
+        apiKey = await deps.resolveApiKey(baseUrl, {
+            env: deps.env,
+            // SEGURANÇA (#187): URL de fonte MUTÁVEL (settings.json persistido, origem
+            // `config`) NÃO pode usar a REDMINE_API_KEY instance-agnóstica — só credencial
+            // PINADA à instância (keychain/arquivo). Impede que um settings.json adulterado
+            // redirecione a chave real para um host arbitrário (fail-closed).
+            allowEnvFallback: origin !== 'config',
+            // Aviso de migração/keychain vai para o diagnóstico (stdout é do protocolo).
+            logger: { warn: (message) => deps.log?.(message) },
+        });
+    }
+    catch (error) {
+        return errorResult(messageOf(error));
+    }
+    if (apiKey === undefined || apiKey.length === 0) {
+        return errorResult(`Nenhuma credencial encontrada para ${baseUrl}. Configure REDMINE_API_KEY (ou o arquivo de credenciais via 'redmine-context login').`);
+    }
+    return { baseUrl, apiKey };
+}
+/** Type guard: distingue a instância resolvida de um CallToolResult de erro. */
+function isResolved(value) {
+    return 'baseUrl' in value;
+}
+/**
+ * Cria o handler da tool `get_issue_context`, testável isoladamente.
+ *
+ * Resolve a instância/credencial a partir da env (nunca de argumentos), invoca
+ * `fetchIssueBundle` e devolve o bundle. Erros viram `isError` com mensagem
+ * tipada; a ausência de `REDMINE_URL`/credencial orienta a configuração.
+ *
+ * @param deps - Ver {@link McpServerDeps}.
+ * @returns Função assíncrona que recebe os argumentos e devolve um CallToolResult.
+ * @example
+ * const handler = createGetIssueContextHandler(defaultMcpDeps());
+ * const result = await handler({ issue_id: 42, format: 'json' });
+ */
+export function createGetIssueContextHandler(deps) {
+    return async (args) => {
+        const resolved = await resolveInstance(deps);
+        if (!isResolved(resolved))
+            return resolved;
+        const { baseUrl, apiKey } = resolved;
+        const format = args.format === 'json' ? 'json' : 'md';
+        try {
+            let content;
+            for await (const event of deps.fetchIssueBundle({
+                baseUrl,
+                apiKey,
+                issueId: args.issue_id,
+                format,
+                toolVersion: deps.toolVersion,
+                insecure: deps.insecure ?? false,
+                extractAttachments: args.extract_attachments ?? false,
+                // Cache-first (#70): embute o texto já pronto e marca o restante como
+                // `processing` sem bloquear na extração cara (a computação corre em background).
+                cacheFirst: true,
+            })) {
+                if (event.kind === 'progress') {
+                    deps.log?.(event.message);
+                }
+                else {
+                    content = event.value.content;
+                }
+            }
+            if (content === undefined) {
+                return errorResult('A operação não produziu um bundle.');
+            }
+            return textResult(content);
+        }
+        catch (error) {
+            return errorResult(typedErrorMessage(error, args.issue_id));
+        }
+    };
+}
+/**
+ * Traduz erros da busca em mensagens claras (sem `issue_id`, que não se aplica).
+ *
+ * @param error - Erro capturado durante a busca.
+ * @returns Mensagem a exibir no `isError`.
+ */
+function typedSearchErrorMessage(error) {
+    if (error instanceof core.RedmineAuthError) {
+        return 'Falha de autenticação (401). Verifique a credencial em REDMINE_API_KEY.';
+    }
+    if (error instanceof core.RedmineForbiddenError) {
+        return 'Acesso negado (403). A credencial não tem permissão para esta busca.';
+    }
+    return messageOf(error);
+}
+/** Monta os filtros estruturados a partir dos argumentos definidos da tool. */
+function searchFiltersOf(args) {
+    return {
+        project_id: args.project_id,
+        status_id: args.status_id,
+        assigned_to_id: args.assigned_to_id,
+        updated_on: args.updated_on,
+    };
+}
+/**
+ * Cria o handler da tool `search_issues`, testável isoladamente.
+ *
+ * Resolve a instância/credencial da env (nunca de argumentos), delega à
+ * orquestração `fetchIssueSearch` (filtros + full-text best-effort) e devolve a
+ * lista compacta em Markdown. A degradação da busca full-text NÃO é erro: o
+ * aviso já vem embutido no payload retornado pelo core.
+ *
+ * @param deps - Ver {@link McpServerDeps}.
+ * @returns Função assíncrona que recebe os argumentos e devolve um CallToolResult.
+ * @example
+ * const handler = createSearchIssuesHandler(defaultMcpDeps());
+ * const result = await handler({ query: 'timeout', project_id: 5 });
+ */
+export function createSearchIssuesHandler(deps) {
+    return async (args) => {
+        const resolved = await resolveInstance(deps);
+        if (!isResolved(resolved))
+            return resolved;
+        const { baseUrl, apiKey } = resolved;
+        try {
+            const result = await deps.searchIssues({
+                baseUrl,
+                apiKey,
+                filters: searchFiltersOf(args),
+                query: args.query,
+                limit: args.limit ?? SEARCH_DEFAULT_LIMIT,
+            });
+            // Degradação vira aviso no corpo (não isError); logamos para diagnóstico.
+            if (result.degraded)
+                deps.log?.(result.warnings.join(' '));
+            return textResult(result.content);
+        }
+        catch (error) {
+            return errorResult(typedSearchErrorMessage(error));
+        }
+    };
+}
+/**
+ * Traduz erros da extração de anexo em mensagens claras e tipadas.
+ *
+ * 404/403/401 do Redmine e o {@link core.AttachmentNotFoundError} recebem texto
+ * orientado; os demais propagam a mensagem original. Nenhum resultado é cacheado
+ * aqui — o erro é sempre recomputado por chamada (sem cache indevido).
+ *
+ * @param error - Erro capturado durante o fetch/extração.
+ * @param issueId - Id da issue para compor a mensagem.
+ * @param attachmentId - Id do anexo para compor a mensagem.
+ * @returns A mensagem a ser exibida no `isError`.
+ */
+function typedAttachmentErrorMessage(error, issueId, attachmentId) {
+    if (error instanceof core.AttachmentNotFoundError) {
+        return `Anexo #${attachmentId} não encontrado na issue #${issueId}. Verifique o id do anexo.`;
+    }
+    return typedErrorMessage(error, issueId);
+}
+/**
+ * Renderiza o {@link AttachmentTextResult} como conteúdo MCP de sucesso.
+ *
+ * Com texto (`done`/`text`): devolve-o dentro da fence `<untrusted-content>` — é
+ * conteúdo DERIVADO do anexo, logo não confiável (padrão do repo). Sem texto
+ * (`pending`/`processing`/`skipped`/`unsupported`/`failed`): devolve `status` +
+ * `reason`/`hint` legíveis — NUNCA um erro genérico; o `hint` é texto nosso
+ * (ex.: como instalar o tesseract), fora da fence por ser confiável.
+ *
+ * @param result - Resultado da extração do anexo.
+ * @returns CallToolResult de sucesso (não `isError`).
+ */
+function renderAttachmentText(result) {
+    const { extraction } = result;
+    if (typeof extraction.text === 'string' && extraction.text.trim() !== '') {
+        return textResult(fenceBlock(extraction.text));
+    }
+    const lines = [`Anexo #${result.attachmentId}: extração ${extraction.status} (sem texto disponível).`];
+    const reason = extraction.metadata?.['reason'];
+    const hint = extraction.metadata?.['hint'];
+    if (typeof reason === 'string')
+        lines.push(`Motivo: ${reason}`);
+    if (typeof hint === 'string')
+        lines.push(hint);
+    return textResult(lines.join('\n'));
+}
+/**
+ * Cria o handler da tool `get_attachment_text`, testável isoladamente.
+ *
+ * Resolve a instância/credencial da env (nunca de argumentos), delega à
+ * orquestração cache-first `fetchAttachmentText` (texto já cacheado volta na
+ * hora; mídia pesada ainda não processada volta como `processing` SEM bloquear —
+ * M4-11 #70) e devolve o texto extraído dentro da fence untrusted. Anexo não
+ * processável / `processing` vira status legível (não `isError`); 403/404 do
+ * Redmine e anexo inexistente viram `isError` tipado.
+ *
+ * @param deps - Ver {@link McpServerDeps}.
+ * @returns Função assíncrona que recebe os argumentos e devolve um CallToolResult.
+ * @example
+ * const handler = createGetAttachmentTextHandler(defaultMcpDeps());
+ * const result = await handler({ issue_id: 42, attachment_id: 77 });
+ */
+export function createGetAttachmentTextHandler(deps) {
+    return async (args) => {
+        const resolved = await resolveInstance(deps);
+        if (!isResolved(resolved))
+            return resolved;
+        const { baseUrl, apiKey } = resolved;
+        try {
+            const result = await deps.fetchAttachmentText({
+                baseUrl,
+                apiKey,
+                issueId: args.issue_id,
+                attachmentId: args.attachment_id,
+                insecure: deps.insecure ?? false,
+            });
+            return renderAttachmentText(result);
+        }
+        catch (error) {
+            return errorResult(typedAttachmentErrorMessage(error, args.issue_id, args.attachment_id));
+        }
+    };
+}
+/**
+ * Constrói um {@link McpServer} com a tool `get_issue_context` registrada.
+ *
+ * A tool é read-only e não expõe URL/host — a instância vem sempre da env.
+ *
+ * @param deps - Ver {@link McpServerDeps}.
+ * @returns O server pronto para `connect(transport)`.
+ */
+export function createMcpServer(deps) {
+    const server = new McpServer({ name: core.TOOL_NAME, version: deps.toolVersion });
+    const handler = createGetIssueContextHandler(deps);
+    const searchHandler = createSearchIssuesHandler(deps);
+    const attachmentHandler = createGetAttachmentTextHandler(deps);
+    server.registerTool(TOOL_NAME, {
+        title: 'Contexto de issue do Redmine',
+        description: 'Busca uma issue na instância Redmine configurada (REDMINE_URL) e retorna seu contexto completo empacotado. Read-only.',
+        inputSchema: INPUT_SCHEMA,
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, (args) => handler(args));
+    server.registerTool(SEARCH_TOOL_NAME, {
+        title: 'Buscar issues no Redmine',
+        description: 'Busca issues na instância configurada (REDMINE_URL) por filtros estruturados (project_id, status_id, assigned_to_id, updated_on) e, opcionalmente, texto livre (query, best-effort via /search). Retorna uma lista compacta paginada. Read-only.',
+        inputSchema: SEARCH_INPUT_SCHEMA,
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, (args) => searchHandler(args));
+    server.registerTool(ATTACHMENT_TOOL_NAME, {
+        title: 'Texto extraído de um anexo do Redmine',
+        description: 'Extrai (com cache) o texto de um anexo de uma issue na instância configurada (REDMINE_URL) e o retorna dentro de uma fence de conteúdo não confiável. Anexo não processável retorna o status/motivo legível (skipped/unsupported/failed), não um erro. Read-only.',
+        inputSchema: ATTACHMENT_INPUT_SCHEMA,
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, (args) => attachmentHandler(args));
+    return server;
+}
+/** Constrói as dependências default apontando para o core e o processo reais. */
+export function defaultMcpDeps() {
+    return {
+        fetchIssueBundle: core.fetchIssueBundle,
+        searchIssues: core.fetchIssueSearch,
+        fetchAttachmentText: core.fetchAttachmentTextCacheFirst,
+        resolveApiKey: core.resolveApiKey,
+        env: process.env,
+        settings: core.defaultSettingsStore(),
+        toolVersion: core.TOOL_VERSION,
+        insecure: parseInsecure(process.env),
+        // Diagnóstico SEMPRE em stderr: o stdout pertence ao protocolo stdio.
+        log: (message) => void process.stderr.write(`${message}\n`),
+    };
+}
+/* c8 ignore start -- wire de I/O (stdio transport); coberto pelo teste E2E real (#20). */
+/**
+ * Sobe o server MCP no transporte stdio e resolve quando a conexão fecha.
+ *
+ * O stdout é reservado ao protocolo; qualquer log vai para stderr.
+ *
+ * @param overrides - Dependências injetáveis (defaults via {@link defaultMcpDeps}).
+ * @returns Promise que resolve quando o transporte encerra.
+ */
+export async function runStdioServer(overrides = {}) {
+    const deps = { ...defaultMcpDeps(), ...overrides };
+    const server = createMcpServer(deps);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    deps.log?.('redmine-context MCP server pronto (stdio).');
+    await new Promise((resolve) => {
+        transport.onclose = () => resolve();
+    });
+}
+/* c8 ignore stop */

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

@@ -0,0 +1,55 @@
+import type { SettingsStore } from '../../index.js';
+import { type OnboardingReAuth } from './screens/onboarding/onboarding-context.js';
+import { type ScreenName } from './screen.js';
+import { type Theme, type ThemeController } from './theme.js';
+/**
+ * O que `Esc` deve fazer dado o estado atual — extraída como função pura
+ * (fix do review #119) para poder ser testada isoladamente
+ * (`tests/surfaces/tui/app.test.tsx`) sem precisar montar toda a árvore do
+ * Ink nem depender de uma tela de dados real (#29+) para chegar no estado de
+ * re-auth ativo.
+ */
+export type EscapeAction = {
+    kind: 'abort-reauth';
+    origin: ScreenName;
+} | {
+    kind: 'pop';
+};
+/**
+ * Decide a ação de `Esc`: abandono do re-auth (fix do review #119) quando a
+ * tela atual é do fluxo de onboarding (`onboarding-*`) E há um `reAuth` em
+ * andamento; `pop()` simples em qualquer outro caso (comportamento original,
+ * M2-04).
+ */
+export declare function resolveEscapeAction(current: ScreenName, reAuth: OnboardingReAuth | undefined): EscapeAction;
+/**
+ * App raiz da TUI: só monta os providers (tema, pilha de navegação,
+ * onboarding — M2-05.1). `OnboardingProvider` recebe os callbacks REAIS de
+ * `useOnboardingCallbacks` (#28) — o wiring com o core (`loginWithPassword`,
+ * `validateApiKey`, credential cascade) vive só ali, nunca nas telas em si
+ * (ADR-005).
+ */
+/** Props do {@link App} — todas opcionais para não quebrar `render(<App/>)` nos testes. */
+export interface AppProps {
+    /**
+     * Id da paleta inicial (#190). Ausente ⇒ {@link DEFAULT_THEME} (comportamento
+     * atual, usado pelos testes); o `runTui` passa a paleta resolvida do settings.
+     */
+    initialPaletteId?: string;
+    /** Store para PERSISTIR a paleta escolhida (#190). Ausente ⇒ persistência é no-op. */
+    settings?: Pick<SettingsStore, 'setPaletteId'>;
+}
+/**
+ * Estado do tema/paleta (#190) — extraído para teste determinístico (sem depender
+ * do teclado): mantém a paleta ativa, resolve o {@link Theme} e expõe o
+ * {@link ThemeController} (preview troca ao vivo; select troca + persiste best-effort).
+ *
+ * @param initialPaletteId - Paleta inicial; `undefined` ⇒ {@link DEFAULT_THEME} (testes).
+ * @param settings - Store para persistir a paleta no `select` (opcional).
+ * @returns O `theme` resolvido + o `controller`.
+ */
+export declare function useThemeControllerState(initialPaletteId?: string, settings?: Pick<SettingsStore, 'setPaletteId'>): {
+    theme: Theme;
+    controller: ThemeController;
+};
+export declare function App(props?: AppProps): import("react").JSX.Element;

package/dist/surfaces/tui/app.js

@@ -0,0 +1,180 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Roteador de telas da TUI (M2-01, evoluído em M2-04 para pilha + casca
+ * visual global).
+ *
+ * `App` só instancia os providers (tema, pilha de navegação) — quem de fato
+ * consome o contexto e renderiza a casca visual (breadcrumb fixo, aviso de
+ * saída, tela atual) é `AppShell`, um componente à parte porque precisa
+ * estar DENTRO dos providers para poder chamar `useTheme()`/`useNavigation()`.
+ *
+ * Atalhos globais (qualquer tela): `q` sai, `Esc` volta (`pop()` da pilha,
+ * ver `navigation.tsx`), `Ctrl+C` segue o padrão de duas pressões (ver
+ * `hooks/use-exit-guard.ts`). `/` era reservado (no-op) para a busca antes
+ * da M2-07 existir; a semântica real agora vive na home (`screens/home.tsx`,
+ * que registra seu PRÓPRIO `useInput` para `/`) — o handler global permanece
+ * no-op aqui, o que automaticamente CONTINUA bloqueando `/` em qualquer tela
+ * que não seja a home (nenhuma outra tela trata essa tecla).
+ *
+ * Fix do review do PR #119: `Esc` numa tela `onboarding-*` enquanto um
+ * re-auth (M2-13, #36) está em andamento (`OnboardingContext.reAuth`) passa
+ * a significar ABANDONO explícito do re-login, em vez do `pop()` simples de
+ * sempre — sem isso, a `Promise` do `guard()` original
+ * (`hooks/use-auth-guard.ts`) ficaria pendurada para sempre. Nesse caso:
+ * `abortReAuth()` rejeita as pendências com `ReAuthAbortedError` e a
+ * navegação volta direto para a tela de ORIGEM do 401 (`popTo`,
+ * `navigation.tsx`) em vez de só desempilhar uma tela por vez.
+ *
+ * M2-07 (#30): `Esc` no campo de busca da home precisa fechar a busca em vez
+ * de desempilhar a home inteira — `consumeEscapeInterceptor()`
+ * (`hooks/use-escape-interceptor.ts`) é consultado ANTES do `pop()` padrão;
+ * se a home registrou um interceptor (busca aberta), ele é quem trata o Esc
+ * e o `pop()`/abandono de re-auth abaixo é pulado nesse ciclo.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Box, Text, useApp, useInput, useStdout } from 'ink';
+import { Breadcrumb } from './components/breadcrumb.js';
+import { TerminalSizeProvider, useTerminalHeight } from './hooks/use-terminal-width.js';
+import { applyTerminalColors } from './terminal-colors.js';
+import { ReAuthAbortedError } from './hooks/use-auth-guard.js';
+import { consumeEscapeInterceptor } from './hooks/use-escape-interceptor.js';
+import { useExitGuard } from './hooks/use-exit-guard.js';
+import { useOnboardingCallbacks } from './hooks/use-onboarding-callbacks.js';
+import { JobRegistryProvider } from './job-registry.js';
+import { NavigationProvider, useNavigation, useNavigationStack } from './navigation.js';
+import { HomeSelectionProvider } from './screens/home-selection.js';
+import { LoadedIssueProvider } from './screens/loaded-issue-context.js';
+import { OnboardingProvider, useOnboarding, } from './screens/onboarding/onboarding-context.js';
+import { DEFAULT_PALETTE_ID, resolvePalette } from './palettes.js';
+import { INITIAL_SCREEN, SCREENS } from './screen.js';
+import { symbols } from './symbols.js';
+import { DEFAULT_THEME, ThemeControllerProvider, ThemeProvider, useTheme, } from './theme.js';
+/**
+ * Decide a ação de `Esc`: abandono do re-auth (fix do review #119) quando a
+ * tela atual é do fluxo de onboarding (`onboarding-*`) E há um `reAuth` em
+ * andamento; `pop()` simples em qualquer outro caso (comportamento original,
+ * M2-04).
+ */
+export function resolveEscapeAction(current, reAuth) {
+    if (reAuth !== undefined && current.startsWith('onboarding-')) {
+        return { kind: 'abort-reauth', origin: reAuth.origin };
+    }
+    return { kind: 'pop' };
+}
+/**
+ * Estado do tema/paleta (#190) — extraído para teste determinístico (sem depender
+ * do teclado): mantém a paleta ativa, resolve o {@link Theme} e expõe o
+ * {@link ThemeController} (preview troca ao vivo; select troca + persiste best-effort).
+ *
+ * @param initialPaletteId - Paleta inicial; `undefined` ⇒ {@link DEFAULT_THEME} (testes).
+ * @param settings - Store para persistir a paleta no `select` (opcional).
+ * @returns O `theme` resolvido + o `controller`.
+ */
+export function useThemeControllerState(initialPaletteId, settings) {
+    const [paletteId, setPaletteId] = useState(initialPaletteId);
+    const theme = paletteId !== undefined ? resolvePalette(paletteId).theme : DEFAULT_THEME;
+    const controller = useMemo(() => ({
+        paletteId: paletteId ?? DEFAULT_PALETTE_ID,
+        preview: (id) => setPaletteId(id),
+        select: async (id) => {
+            setPaletteId(id);
+            // Persistência best-effort: uma falha ao salvar não deve quebrar a TUI.
+            try {
+                await settings?.setPaletteId(id);
+            }
+            catch {
+                /* segue com a paleta aplicada nesta sessão */
+            }
+        },
+    }), [paletteId, settings]);
+    return { theme, controller };
+}
+export function App(props = {}) {
+    const { initialPaletteId, settings } = props;
+    const navigation = useNavigationStack(INITIAL_SCREEN);
+    const onboardingCallbacks = useOnboardingCallbacks();
+    // Paleta ativa (#190) — ver {@link useThemeControllerState}.
+    const { theme, controller } = useThemeControllerState(initialPaletteId, settings);
+    // Aplica as cores da paleta como default do terminal (OSC) sempre que ela muda
+    // (troca ao vivo na tela Aparência) — o fundo cobre a tela e todo texto sem cor
+    // explícita fica legível. Só em TTY real; nos testes (`ink-testing-library`) o
+    // stdout não é TTY, então não escreve nada.
+    const { stdout } = useStdout();
+    useEffect(() => {
+        if (stdout?.isTTY === true)
+            applyTerminalColors(stdout, theme);
+    }, [theme, stdout]);
+    return (_jsx(TerminalSizeProvider, { children: _jsx(ThemeProvider, { theme: theme, children: _jsx(ThemeControllerProvider, { value: controller, children: _jsx(NavigationProvider, { value: navigation, children: _jsx(OnboardingProvider, { callbacks: onboardingCallbacks, children: _jsx(HomeSelectionProvider, { children: _jsx(LoadedIssueProvider, { children: _jsx(JobRegistryProvider, { children: _jsx(AppShell, {}) }) }) }) }) }) }) }) }));
+}
+/**
+ * Casca visual do app: breadcrumb fixo + aviso de saída (quando armado) +
+ * tela atual. Só existe dentro dos providers de `App` — depende de
+ * `useTheme()`/`useNavigation()`.
+ */
+function AppShell() {
+    const { exit } = useApp();
+    const { current, pop, popTo, stack } = useNavigation();
+    const { reAuth, abortReAuth } = useOnboarding();
+    const theme = useTheme();
+    const { armed } = useExitGuard(exit);
+    // Full-screen (#190): o app ocupa a altura TODA do terminal. `minHeight` (não
+    // `height` fixo) evita a amostragem do Yoga em listas longas (achado B2). As
+    // telas usam um espaçador (`flexGrow`) antes dos atalhos para ancorá-los no
+    // rodapé, estilo nano/nvim/tmux.
+    const rows = useTerminalHeight();
+    // Handler ESTÁVEL (refs + useCallback): identidade nova a cada render faz o
+    // useInput des/re-subscrever no efeito pós-commit, abrindo janelas em que
+    // teclas rápidas (Esc em sequência) se perdem — mesma classe de bug
+    // corrigida no TextInput.
+    const exitRef = useRef(exit);
+    exitRef.current = exit;
+    const popRef = useRef(pop);
+    popRef.current = pop;
+    const popToRef = useRef(popTo);
+    popToRef.current = popTo;
+    const currentRef = useRef(current);
+    currentRef.current = current;
+    const reAuthRef = useRef(reAuth);
+    reAuthRef.current = reAuth;
+    const abortReAuthRef = useRef(abortReAuth);
+    abortReAuthRef.current = abortReAuth;
+    const handleGlobalInput = useCallback((input, key) => {
+        if (input === 'q') {
+            exitRef.current();
+            return;
+        }
+        if (key.escape) {
+            // M2-07 (#30): a busca da home intercepta Esc para fechar o campo em
+            // vez de desempilhar a tela — consultado ANTES de qualquer outra
+            // semântica de Esc (pop/abandono de re-auth).
+            if (consumeEscapeInterceptor()) {
+                return;
+            }
+            // Fix do review #119: Esc numa tela de onboarding com um re-auth ativo
+            // é ABANDONO explícito — aborta as pendências (rejeita o(s) `guard()`
+            // original(is) com `ReAuthAbortedError`) e volta direto à tela de
+            // origem do 401, em vez do `pop()` simples de sempre.
+            const action = resolveEscapeAction(currentRef.current, reAuthRef.current);
+            if (action.kind === 'abort-reauth') {
+                abortReAuthRef.current(new ReAuthAbortedError());
+                popToRef.current(action.origin);
+                return;
+            }
+            popRef.current();
+            return;
+        }
+        if (input === '/') {
+            // Reason: reservado para a busca (M2-07, ainda sem tela) — no-op
+            // proposital para já travar a tecla e evitar que outra tela reaproveite
+            // "/" para algo diferente antes da tela de busca existir.
+            return;
+        }
+    }, []);
+    useInput(handleGlobalInput);
+    const Screen = SCREENS[current].component;
+    // Full-screen = alt-screen (runTui) + fundo/texto via OSC (cobrem a tela toda)
+    // + este container com a ALTURA do terminal (`minHeight`). O breadcrumb fica no
+    // topo e a tela ocupa o resto (`flexGrow`); cada tela ancora seus atalhos no
+    // rodapé com um espaçador `flexGrow` (estilo nano/nvim/tmux).
+    return (_jsxs(Box, { flexDirection: "column", minHeight: rows, children: [_jsx(Breadcrumb, { stack: stack }), armed ? (_jsx(Box, { paddingX: 1, marginBottom: 1, children: _jsxs(Text, { color: theme.warning, children: [symbols.warning, " Pressione Ctrl+C de novo para sair."] }) })) : null, _jsx(Box, { flexGrow: 1, flexDirection: "column", children: _jsx(Screen, {}) })] }));
+}