redmine-context 1.0.0

package/dist/surfaces/tui/hooks/use-onboarding-callbacks.js

@@ -0,0 +1,104 @@
+/**
+ * Callbacks REAIS do onboarding (#28) — fecha o wiring entre as telas de
+ * onboarding (`../screens/onboarding/`) e o core: login por senha
+ * (`loginWithPassword`), validação de api_key colada (`validateApiKey`, o
+ * fallback de 2FA do ADR-003) e persistência via a cascata de credenciais M2
+ * (`createCredentialCascade` — keychain preferido, com migração automática).
+ *
+ * Único ponto de import do core para o fluxo de onboarding (ADR-005): as
+ * telas em si (`../screens/onboarding/*.tsx`) só recebem os callbacks
+ * injetados via `<OnboardingProvider callbacks={...}>` (`../app.tsx`) — nunca
+ * importam `../../../index.js` diretamente.
+ *
+ * Mantém uma cópia local da URL (via o callback `onUrlSubmit`, atualizado a
+ * cada submissão da tela de URL) porque o `OnboardingContext` só existe
+ * DEPOIS deste hook rodar (`<OnboardingProvider callbacks={...}>` recebe os
+ * callbacks como prop) — não há como este hook consumir `useOnboarding()`
+ * sem um ciclo de dependência.
+ */
+import { useRef } from 'react';
+import { createCredentialCascade, defaultSettingsStore, loginWithPassword, validateApiKey, RedmineAuthError, } from '../../../index.js';
+/**
+ * Interpreta `REDMINE_INSECURE` (`1`/`true`, case-insensitive) — mesma
+ * convenção usada por `../screens/onboarding/url.tsx` e pelo MCP
+ * (`../../mcp/server.ts`).
+ */
+function isInsecureEnvSet(env) {
+    const raw = env.REDMINE_INSECURE;
+    return raw !== undefined && /^(1|true)$/i.test(raw.trim());
+}
+/** Extrai uma mensagem segura de uma falha desconhecida — o core já redige segredos antes de lançar. */
+function messageOf(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+ * Persiste a instância autenticada (#187) — simétrico ao `login` da CLL. Falha ao
+ * salvar a URL NÃO invalida o onboarding (a credencial já foi salva): swallow.
+ */
+async function persistInstance(settings, url) {
+    try {
+        await settings.setInstanceUrl(url);
+    }
+    catch {
+        // Sem persistência a TUI ainda funciona nesta sessão (REDMINE_URL/prompt).
+    }
+}
+/**
+ * Monta os callbacks reais de onboarding — injetados em
+ * `<OnboardingProvider callbacks={...}>` por `../app.tsx`.
+ *
+ * @example
+ * const callbacks = useOnboardingCallbacks();
+ * return <OnboardingProvider callbacks={callbacks}>...</OnboardingProvider>;
+ */
+export function useOnboardingCallbacks(settings = defaultSettingsStore()) {
+    // Ref (não state): a URL só é lida dentro dos callbacks de login/api_key,
+    // nunca precisa disparar um re-render por si só.
+    const urlRef = useRef('');
+    const onUrlSubmit = (url) => {
+        urlRef.current = url;
+    };
+    const onModeSelect = () => {
+        // Reason: o modo escolhido só direciona a NAVEGAÇÃO entre telas
+        // (`../screens/onboarding/mode.tsx`) — nenhuma chamada ao core depende
+        // dele, então não há estado a guardar aqui.
+    };
+    const onLoginSubmit = async (credentials) => {
+        try {
+            const result = await loginWithPassword({
+                baseUrl: urlRef.current,
+                username: credentials.username,
+                password: credentials.password,
+                insecure: isInsecureEnvSet(process.env),
+            });
+            await createCredentialCascade().set(urlRef.current, result.apiKey);
+            await persistInstance(settings, urlRef.current);
+            return { kind: 'success', user: result.user };
+        }
+        catch (cause) {
+            if (cause instanceof RedmineAuthError) {
+                return { kind: 'auth-error', message: cause.message };
+            }
+            return { kind: 'network-error', message: messageOf(cause) };
+        }
+    };
+    const onApiKeySubmit = async (apiKey) => {
+        try {
+            const result = await validateApiKey({
+                baseUrl: urlRef.current,
+                apiKey,
+                insecure: isInsecureEnvSet(process.env),
+            });
+            await createCredentialCascade().set(urlRef.current, result.apiKey);
+            await persistInstance(settings, urlRef.current);
+            return { kind: 'success', user: result.user };
+        }
+        catch (cause) {
+            if (cause instanceof RedmineAuthError) {
+                return { kind: 'auth-error', message: cause.message };
+            }
+            return { kind: 'network-error', message: messageOf(cause) };
+        }
+    };
+    return { onUrlSubmit, onModeSelect, onLoginSubmit, onApiKeySubmit };
+}

package/dist/surfaces/tui/hooks/use-terminal-width.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Hook de largura do terminal (M2-16, #39): lê `process.stdout.columns` com
+ * fallback, escuta o evento `resize` do stdout REAL para atualizar em
+ * runtime (redimensionamento da janela do terminal), e é injetável via
+ * {@link TerminalWidthProvider} para testes.
+ *
+ * A injeção via contexto existe porque `ink-testing-library` FIXA
+ * `stdout.columns` em `100` (não expõe opção de configurar — ver
+ * `node_modules/ink-testing-library/build/index.js`), então nenhum teste
+ * usando o `render()` daquela lib consegue simular 80/60 colunas só ajustando
+ * `process.stdout.columns`. Testes de layout responsivo usam
+ * `tests/surfaces/tui/render-at-width.tsx`, que injeta a largura por este
+ * provider (e mocka o `stdout` passado ao Ink real com o mesmo valor, para
+ * que o PRÓPRIO wrap do Ink também reflita a largura simulada).
+ */
+import { type ReactNode } from 'react';
+/** Largura assumida quando `process.stdout.columns` está indisponível (ex.: saída não-TTY). */
+export declare const DEFAULT_TERMINAL_WIDTH = 80;
+/** Altura assumida quando `process.stdout.rows` está indisponível. */
+export declare const DEFAULT_TERMINAL_HEIGHT = 24;
+/**
+ * Provider de largura FIXA — usado pelos testes (injeta 80/60 sem depender do
+ * `process.stdout` real). Fora de testes, a árvore da TUI (`../app.tsx`) usa o
+ * {@link TerminalSizeProvider} (uma única assinatura de `resize`).
+ */
+export declare function TerminalWidthProvider({ width, children }: {
+    width: number;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Provider de TAMANHO do terminal (largura + altura) com UMA ÚNICA assinatura do
+ * evento `resize` do stdout (#190 fix). Montado no topo da TUI (`../app.tsx`) para
+ * que `useTerminalWidth`/`useTerminalHeight` leiam do contexto em vez de cada
+ * consumidor (ex.: cada linha da lista) assinar o próprio `resize` — o que
+ * estourava o limite de 10 listeners do EventEmitter (MaxListenersExceededWarning).
+ */
+export declare function TerminalSizeProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Largura atual do terminal, em colunas.
+ *
+ * Usa o provider mais próximo se houver ({@link TerminalSizeProvider} em produção
+ * ou {@link TerminalWidthProvider} nos testes); senão (sem provider) lê o stdout
+ * real e assina o `resize` — caminho de fallback para uso isolado.
+ */
+export declare function useTerminalWidth(): number;
+/**
+ * Altura atual do terminal, em linhas. Lê do {@link TerminalSizeProvider}; sem ele
+ * (uso isolado/testes) cai no fallback {@link DEFAULT_TERMINAL_HEIGHT}.
+ */
+export declare function useTerminalHeight(): number;

package/dist/surfaces/tui/hooks/use-terminal-width.js

@@ -0,0 +1,90 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Hook de largura do terminal (M2-16, #39): lê `process.stdout.columns` com
+ * fallback, escuta o evento `resize` do stdout REAL para atualizar em
+ * runtime (redimensionamento da janela do terminal), e é injetável via
+ * {@link TerminalWidthProvider} para testes.
+ *
+ * A injeção via contexto existe porque `ink-testing-library` FIXA
+ * `stdout.columns` em `100` (não expõe opção de configurar — ver
+ * `node_modules/ink-testing-library/build/index.js`), então nenhum teste
+ * usando o `render()` daquela lib consegue simular 80/60 colunas só ajustando
+ * `process.stdout.columns`. Testes de layout responsivo usam
+ * `tests/surfaces/tui/render-at-width.tsx`, que injeta a largura por este
+ * provider (e mocka o `stdout` passado ao Ink real com o mesmo valor, para
+ * que o PRÓPRIO wrap do Ink também reflita a largura simulada).
+ */
+import { createContext, useContext, useEffect, useState } from 'react';
+/** Largura assumida quando `process.stdout.columns` está indisponível (ex.: saída não-TTY). */
+export const DEFAULT_TERMINAL_WIDTH = 80;
+/** Altura assumida quando `process.stdout.rows` está indisponível. */
+export const DEFAULT_TERMINAL_HEIGHT = 24;
+const TerminalWidthContext = createContext(undefined);
+/** Altura atual (linhas), provida pelo {@link TerminalSizeProvider}; `undefined` fora dele. */
+const TerminalHeightContext = createContext(undefined);
+/** Lê a largura atual do stdout do processo, com fallback para {@link DEFAULT_TERMINAL_WIDTH}. */
+function readProcessColumns() {
+    const columns = process.stdout.columns;
+    return typeof columns === 'number' && columns > 0 ? columns : DEFAULT_TERMINAL_WIDTH;
+}
+/** Lê a altura atual do stdout do processo, com fallback para {@link DEFAULT_TERMINAL_HEIGHT}. */
+function readProcessRows() {
+    const rows = process.stdout.rows;
+    return typeof rows === 'number' && rows > 0 ? rows : DEFAULT_TERMINAL_HEIGHT;
+}
+/**
+ * Provider de largura FIXA — usado pelos testes (injeta 80/60 sem depender do
+ * `process.stdout` real). Fora de testes, a árvore da TUI (`../app.tsx`) usa o
+ * {@link TerminalSizeProvider} (uma única assinatura de `resize`).
+ */
+export function TerminalWidthProvider({ width, children }) {
+    return _jsx(TerminalWidthContext.Provider, { value: width, children: children });
+}
+/**
+ * Provider de TAMANHO do terminal (largura + altura) com UMA ÚNICA assinatura do
+ * evento `resize` do stdout (#190 fix). Montado no topo da TUI (`../app.tsx`) para
+ * que `useTerminalWidth`/`useTerminalHeight` leiam do contexto em vez de cada
+ * consumidor (ex.: cada linha da lista) assinar o próprio `resize` — o que
+ * estourava o limite de 10 listeners do EventEmitter (MaxListenersExceededWarning).
+ */
+export function TerminalSizeProvider({ children }) {
+    const [size, setSize] = useState(() => ({ width: readProcessColumns(), height: readProcessRows() }));
+    useEffect(() => {
+        const onResize = () => setSize({ width: readProcessColumns(), height: readProcessRows() });
+        process.stdout.on('resize', onResize);
+        return () => {
+            process.stdout.off('resize', onResize);
+        };
+    }, []);
+    return (_jsx(TerminalWidthContext.Provider, { value: size.width, children: _jsx(TerminalHeightContext.Provider, { value: size.height, children: children }) }));
+}
+/**
+ * Largura atual do terminal, em colunas.
+ *
+ * Usa o provider mais próximo se houver ({@link TerminalSizeProvider} em produção
+ * ou {@link TerminalWidthProvider} nos testes); senão (sem provider) lê o stdout
+ * real e assina o `resize` — caminho de fallback para uso isolado.
+ */
+export function useTerminalWidth() {
+    const injected = useContext(TerminalWidthContext);
+    const [width, setWidth] = useState(readProcessColumns);
+    useEffect(() => {
+        // Com um provider (produção via TerminalSizeProvider, ou testes), a largura é
+        // a fonte da verdade — não assina o stdout real por consumidor.
+        if (injected !== undefined)
+            return;
+        const handleResize = () => setWidth(readProcessColumns());
+        process.stdout.on('resize', handleResize);
+        return () => {
+            process.stdout.off('resize', handleResize);
+        };
+    }, [injected]);
+    return injected ?? width;
+}
+/**
+ * Altura atual do terminal, em linhas. Lê do {@link TerminalSizeProvider}; sem ele
+ * (uso isolado/testes) cai no fallback {@link DEFAULT_TERMINAL_HEIGHT}.
+ */
+export function useTerminalHeight() {
+    return useContext(TerminalHeightContext) ?? DEFAULT_TERMINAL_HEIGHT;
+}

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

@@ -0,0 +1,50 @@
+import { type SettingsStore } from '../../index.js';
+import { type InstanceInfo } from './instance.js';
+import type { Theme } from './theme.js';
+/** Dependências injetáveis do `runTui` (default: processo real). */
+export interface RunTuiDeps {
+    /** Ambiente (para `REDMINE_URL`); default `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Store da URL persistida + paleta; default {@link defaultSettingsStore}. */
+    settings?: SettingsStore;
+    /** Stream de saída (para o alt-screen); default `process.stdout`. Injetável em testes. */
+    stdout?: NodeJS.WriteStream;
+    /** `process` para os handlers de sinal do alt-screen; default `process`. Injetável em testes. */
+    proc?: AltScreenProc;
+}
+/**
+ * Resolve a instância da TUI no boot (#187) e POPULA `env.REDMINE_URL` para os
+ * hooks de dados (que leem o ambiente) — `REDMINE_URL` vence; sem ela, usa a URL
+ * persistida no `login`. Extraída para teste (o `runTui` bloqueia em `waitUntilExit`).
+ *
+ * @param env - Ambiente a consultar/popular (o `runTui` passa `process.env`).
+ * @param settings - Store da URL persistida.
+ * @returns Metadados da instância + ação de limpar a persistida, para o contexto.
+ */
+export declare function resolveTuiInstance(env: NodeJS.ProcessEnv, settings: SettingsStore): Promise<InstanceInfo>;
+/**
+ * Sobe a TUI e aguarda o app sair.
+ *
+ * @param deps - Ver {@link RunTuiDeps} (env/settings/stdout); default: processo real.
+ * @returns Exit code `0` (sair da TUI é sempre encerramento normal).
+ */
+export declare function runTui(deps?: RunTuiDeps): Promise<number>;
+/** Subconjunto do `process` que `installAltScreen` usa (injetável em testes). */
+export interface AltScreenProc {
+    on(event: string, listener: (...args: unknown[]) => void): unknown;
+    off(event: string, listener: (...args: unknown[]) => void): unknown;
+    exit(code?: number): never;
+}
+/**
+ * Entra no alt-screen e instala a restauração à prova de saída não cooperativa
+ * (#190, B1). Restaura em: saída normal (via o `dispose` retornado, chamado no
+ * `finally`), `process.exit`/fim natural (`'exit'`) e sinais de término
+ * (SIGINT/SIGTERM/SIGHUP) — nesses, restaura SÍNCRONO e então encerra com o código
+ * convencional. A restauração é IDEMPOTENTE (só escreve a sequência de saída uma vez).
+ *
+ * @param out - Stream do terminal.
+ * @param proc - `process` (ou um fake em testes).
+ * @param theme - Paleta ativa no boot (aplica fundo/texto default via OSC).
+ * @returns `dispose()` — restaura + remove os listeners (saída normal).
+ */
+export declare function installAltScreen(out: NodeJS.WriteStream, proc: AltScreenProc, theme?: Theme): () => void;

package/dist/surfaces/tui/index.js

@@ -0,0 +1,158 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Ponto de entrada da TUI (M2-01).
+ *
+ * Renderiza o roteador (`app.tsx`) via Ink e resolve quando o usuário sai
+ * (`q`, ver `app.tsx`). Consumido pelo CLI quando `redmine-context` roda sem
+ * argumentos e o stdout é um TTY (`../cli/main.ts`).
+ *
+ * `exitOnCtrlC: false` (M2-04): o app implementa seu próprio padrão de saída
+ * (duplo Ctrl+C, ver `hooks/use-exit-guard.ts`) — sem essa flag, o Ink sai do
+ * processo na primeira pressão de Ctrl+C antes do handler global rodar.
+ *
+ * Full-screen + paletas (#190): entra no buffer de tela alternativo (alt-screen)
+ * em TTY e passa a paleta persistida + o flag full-screen ao `App`.
+ */
+import { render } from 'ink';
+import { defaultSettingsStore } from '../../index.js';
+import { App } from './app.js';
+import { InstanceProvider } from './instance.js';
+import { DEFAULT_PALETTE_ID, resolvePalette } from './palettes.js';
+import { applyTerminalColors, resetTerminalColors } from './terminal-colors.js';
+/**
+ * Resolve a instância da TUI no boot (#187) e POPULA `env.REDMINE_URL` para os
+ * hooks de dados (que leem o ambiente) — `REDMINE_URL` vence; sem ela, usa a URL
+ * persistida no `login`. Extraída para teste (o `runTui` bloqueia em `waitUntilExit`).
+ *
+ * @param env - Ambiente a consultar/popular (o `runTui` passa `process.env`).
+ * @param settings - Store da URL persistida.
+ * @returns Metadados da instância + ação de limpar a persistida, para o contexto.
+ */
+export async function resolveTuiInstance(env, settings) {
+    let url = nonEmpty(env.REDMINE_URL);
+    let origin = url !== undefined ? 'env' : 'none';
+    if (url === undefined) {
+        const persisted = await settings.getInstanceUrl().catch(() => undefined);
+        if (persisted !== undefined && persisted.length > 0) {
+            env.REDMINE_URL = persisted;
+            url = persisted;
+            origin = 'config';
+        }
+    }
+    return {
+        ...(url !== undefined ? { url } : {}),
+        origin,
+        clearPersisted: async () => {
+            await settings.clearInstanceUrl();
+            // Se a instância desta sessão veio da persistida, ela foi escrita em
+            // `env.REDMINE_URL` no boot — limpa também, senão os hooks de dados
+            // continuariam vendo a instância "logada" após o logout (só um restart
+            // corrigiria). Não toca `env` quando a origem foi a própria env real.
+            if (origin === 'config') {
+                delete env.REDMINE_URL;
+            }
+        },
+    };
+}
+/**
+ * Sobe a TUI e aguarda o app sair.
+ *
+ * @param deps - Ver {@link RunTuiDeps} (env/settings/stdout); default: processo real.
+ * @returns Exit code `0` (sair da TUI é sempre encerramento normal).
+ */
+export async function runTui(deps = {}) {
+    const env = deps.env ?? process.env;
+    const settings = deps.settings ?? defaultSettingsStore();
+    const instance = await resolveTuiInstance(env, settings);
+    // Paleta persistida (#190) — default (Catppuccin Mocha) se nenhuma escolhida.
+    const paletteId = (await settings.getPaletteId().catch(() => undefined)) ?? DEFAULT_PALETTE_ID;
+    // Full-screen (#190): alt-screen buffer (como vim/htop) só em TTY real — a TUI
+    // ocupa a tela toda e o conteúdo anterior do terminal é restaurado ao sair.
+    // Fora de TTY o `shouldRenderTui` (M2-03) já nem chega aqui.
+    const out = deps.stdout ?? process.stdout;
+    const fullScreen = out.isTTY === true;
+    // `dispose` restaura o terminal na saída NORMAL (finally). Os handlers de sinal
+    // instalados por `installAltScreen` cobrem a saída NÃO cooperativa (SIGTERM/
+    // SIGHUP/SIGINT externos, fechar a aba) — sem eles o `finally` de uma Promise
+    // não roda e o terminal fica preso no alt-screen (achado B1 da review).
+    const bootTheme = resolvePalette(paletteId).theme;
+    const dispose = fullScreen ? installAltScreen(out, deps.proc ?? process, bootTheme) : () => undefined;
+    try {
+        const { waitUntilExit } = render(_jsx(InstanceProvider, { value: instance, children: _jsx(App, { initialPaletteId: paletteId, settings: settings }) }), { exitOnCtrlC: false });
+        await waitUntilExit();
+    }
+    finally {
+        dispose();
+    }
+    return 0;
+}
+/**
+ * Entra no alt-screen, aplica as cores da paleta como default do terminal (OSC,
+ * ANTES do clear — a tela é limpa já com o fundo temático), limpa e esconde o cursor.
+ */
+function enterAltScreen(out, theme) {
+    out.write('\x1b[?1049h');
+    if (theme !== undefined)
+        applyTerminalColors(out, theme);
+    out.write('\x1b[H\x1b[2J\x1b[?25l');
+}
+/** Restaura cursor + cores default do terminal + buffer principal (ao sair). */
+function leaveAltScreen(out, theme) {
+    out.write('\x1b[?25h');
+    if (theme !== undefined)
+        resetTerminalColors(out);
+    out.write('\x1b[?1049l');
+}
+/** Sinais que terminam o processo e para os quais restauramos o terminal. */
+const RESTORE_SIGNALS = [
+    ['SIGINT', 130],
+    ['SIGTERM', 143],
+    ['SIGHUP', 129],
+];
+/**
+ * Entra no alt-screen e instala a restauração à prova de saída não cooperativa
+ * (#190, B1). Restaura em: saída normal (via o `dispose` retornado, chamado no
+ * `finally`), `process.exit`/fim natural (`'exit'`) e sinais de término
+ * (SIGINT/SIGTERM/SIGHUP) — nesses, restaura SÍNCRONO e então encerra com o código
+ * convencional. A restauração é IDEMPOTENTE (só escreve a sequência de saída uma vez).
+ *
+ * @param out - Stream do terminal.
+ * @param proc - `process` (ou um fake em testes).
+ * @param theme - Paleta ativa no boot (aplica fundo/texto default via OSC).
+ * @returns `dispose()` — restaura + remove os listeners (saída normal).
+ */
+export function installAltScreen(out, proc, theme) {
+    enterAltScreen(out, theme);
+    let restored = false;
+    const restore = () => {
+        if (restored)
+            return;
+        restored = true;
+        leaveAltScreen(out, theme);
+    };
+    const onExit = () => restore();
+    const signalHandlers = RESTORE_SIGNALS.map(([signal, code]) => {
+        const handler = () => {
+            restore();
+            cleanup();
+            proc.exit(code);
+        };
+        proc.on(signal, handler);
+        return [signal, handler];
+    });
+    proc.on('exit', onExit);
+    function cleanup() {
+        proc.off('exit', onExit);
+        for (const [signal, handler] of signalHandlers)
+            proc.off(signal, handler);
+    }
+    return () => {
+        restore();
+        cleanup();
+    };
+}
+/** Retorna a string aparada se não-vazia, senão `undefined`. */
+function nonEmpty(value) {
+    const trimmed = value?.trim();
+    return trimmed !== undefined && trimmed.length > 0 ? trimmed : undefined;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Contexto da INSTÂNCIA resolvida da TUI (#187).
+ *
+ * O `runTui` resolve a instância uma vez no boot — `REDMINE_URL` (env) tem
+ * precedência; sem ela, usa a URL persistida no `login` — e a expõe aqui para as
+ * telas que precisam saber a ORIGEM (`config`/`doctor`) e para o `logout` também
+ * limpar a URL persistida. Os hooks de dados continuam lendo `process.env`
+ * (populado no boot), então este contexto carrega só metadados + a ação de limpar.
+ */
+import { type ReactNode } from 'react';
+/** Origem da instância em uso na TUI. */
+export type InstanceOrigin = 'env' | 'config' | 'none';
+/** Metadados da instância resolvida + ação para limpar a URL persistida. */
+export interface InstanceInfo {
+    /** URL da instância em uso, ou `undefined` se nenhuma. */
+    readonly url?: string;
+    /** De onde veio: `env` (REDMINE_URL), `config` (persistida) ou `none`. */
+    readonly origin: InstanceOrigin;
+    /** Remove a URL persistida (usado no logout); no-op se não houver store. */
+    readonly clearPersisted: () => Promise<void>;
+}
+/** Provider da instância resolvida (montado pelo `runTui`). */
+export declare function InstanceProvider({ value, children, }: {
+    value: InstanceInfo;
+    children: ReactNode;
+}): ReactNode;
+/** Lê a instância resolvida no contexto (default seguro fora do provider). */
+export declare function useInstance(): InstanceInfo;
+/**
+ * `true` se a credencial de AMBIENTE (`REDMINE_API_KEY`) pode ser usada nesta
+ * sessão. SEGURANÇA (#187): quando a instância veio de fonte MUTÁVEL (`settings.json`
+ * persistido, origem `config`), retorna `false` — a env-key é instance-agnóstica e
+ * não pode ser enviada a uma URL controlável por arquivo. Espelha o `allowEnvFallback`
+ * já aplicado na CLI (`issue`) e no MCP; deve ser passado no `CredentialCascadeOptions`
+ * de TODA resolução de credencial da TUI.
+ */
+export declare function useEnvFallbackAllowed(): boolean;

package/dist/surfaces/tui/instance.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Contexto da INSTÂNCIA resolvida da TUI (#187).
+ *
+ * O `runTui` resolve a instância uma vez no boot — `REDMINE_URL` (env) tem
+ * precedência; sem ela, usa a URL persistida no `login` — e a expõe aqui para as
+ * telas que precisam saber a ORIGEM (`config`/`doctor`) e para o `logout` também
+ * limpar a URL persistida. Os hooks de dados continuam lendo `process.env`
+ * (populado no boot), então este contexto carrega só metadados + a ação de limpar.
+ */
+import { createContext, useContext } from 'react';
+/** Default seguro: sem instância e limpeza no-op (usado fora do provider, ex.: testes). */
+const DEFAULT = {
+    origin: 'none',
+    clearPersisted: async () => undefined,
+};
+const InstanceContext = createContext(DEFAULT);
+/** Provider da instância resolvida (montado pelo `runTui`). */
+export function InstanceProvider({ value, children, }) {
+    return _jsx(InstanceContext.Provider, { value: value, children: children });
+}
+/** Lê a instância resolvida no contexto (default seguro fora do provider). */
+export function useInstance() {
+    return useContext(InstanceContext);
+}
+/**
+ * `true` se a credencial de AMBIENTE (`REDMINE_API_KEY`) pode ser usada nesta
+ * sessão. SEGURANÇA (#187): quando a instância veio de fonte MUTÁVEL (`settings.json`
+ * persistido, origem `config`), retorna `false` — a env-key é instance-agnóstica e
+ * não pode ser enviada a uma URL controlável por arquivo. Espelha o `allowEnvFallback`
+ * já aplicado na CLI (`issue`) e no MCP; deve ser passado no `CredentialCascadeOptions`
+ * de TODA resolução de credencial da TUI.
+ */
+export function useEnvFallbackAllowed() {
+    return useInstance().origin !== 'config';
+}

package/dist/surfaces/tui/job-registry.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Registro leve de jobs da sessão (#34/M2-11) — fonte de dados do painel de
+ * jobs (`./screens/jobs.tsx`, tecla `t` na home/detalhe).
+ *
+ * Mesmo padrão de `./screens/home-selection.tsx`/`./screens/loaded-issue-context.tsx`
+ * (ver o JSDoc de qualquer um dos dois para as alternativas descartadas —
+ * singleton de módulo vazaria estado entre testes; guardar isto dentro de
+ * `NavigationValue` acoplaria o roteador a um detalhe de produtores
+ * específicos): instanciado uma vez em `./app.tsx`, ACIMA da pilha de
+ * navegação, para que jobs sobrevivam ao push/pop de telas — iniciar uma
+ * exportação (`./screens/export.tsx`), navegar para outra tela e voltar ainda
+ * deve mostrar o job (em andamento ou já concluído) no painel.
+ *
+ * ## Contrato para produtores futuros (M3/M4 — extração de anexos)
+ *
+ * Qualquer operação assíncrona da sessão que o usuário deva acompanhar
+ * (exportação hoje; extração de imagem/PDF no M3, áudio/vídeo no M4) é um
+ * "produtor": chama {@link JobRegistryValue.registerJob} uma vez ao iniciar
+ * e {@link JobRegistryValue.updateJobStatus} a cada transição de estado.
+ * Regras do contrato:
+ *
+ * 1. `id` é escolhido pelo PRODUTOR, não pelo registro — deve ser único por
+ *    EXECUÇÃO (ex.: `extract-${attachmentId}-${Date.now()}`), permitindo que
+ *    tentativas repetidas do mesmo tipo de job apareçam como entradas
+ *    distintas no painel (histórico da sessão, não um contador único por
+ *    recurso). `registerJob` faz upsert por `id`: registrar de novo com um
+ *    `id` já existente substitui a entrada em vez de duplicá-la.
+ * 2. Transições de `status` esperadas: `pending` (enfileirado, ainda não
+ *    iniciado) → `processing` (em execução) → `done` | `failed` (estado
+ *    terminal). Produtores sem fase de fila (ex.: exportação, #33 — dispara
+ *    e já começa a gravar) podem registrar direto em `processing`.
+ * 3. `startedAt` (epoch ms, `Date.now()`) é OPCIONAL — quando presente, é o
+ *    instante em que o job entrou em `processing` (não o momento do
+ *    registro em si, que pode ser antes se o job nasceu `pending`). Hoje o
+ *    painel (`./screens/jobs.tsx`) não renderiza duração a partir disso —
+ *    campo já capturado para uma UI futura sem exigir novo campo no
+ *    contrato.
+ * 4. `cancelable`/`onCancel`: só produtores que sabem interromper a
+ *    operação de fato devem marcar `cancelable: true` E fornecer
+ *    `onCancel` (chamado pelo painel ao usuário pressionar Ctrl+C com o job
+ *    selecionado). Exportação (#33) NÃO é cancelável — nada a abortar no
+ *    meio de um `writeFile` — o painel mostra "(não cancelável)" para ela.
+ *    A infraestrutura de cancelamento REAL (abortar uma extração em
+ *    andamento) é do M4; até lá, nenhum produtor real marca `cancelable`.
+ * 5. Jobs terminais (`done`/`failed`) permanecem no registro até o fim da
+ *    sessão (histórico "concluídas da sessão" da AC) — nenhuma limpeza
+ *    automática hoje.
+ */
+import { type ReactNode } from 'react';
+/** Estados possíveis de um job (ver a regra 2 do contrato no JSDoc do módulo). */
+export type JobStatus = 'pending' | 'processing' | 'done' | 'failed';
+/**
+ * Um job da sessão, exibido no painel (`./screens/jobs.tsx`). Ver o JSDoc do
+ * módulo para o contrato completo consumido por produtores futuros (M3/M4).
+ */
+export interface Job {
+    /** Identificador único da EXECUÇÃO (não do recurso) — escolhido pelo produtor, ver regra 1. */
+    id: string;
+    /** Rótulo legível exibido no painel (ex.: `Exportar #88 (md)`). */
+    label: string;
+    /** Estado atual — ver as transições esperadas na regra 2. */
+    status: JobStatus;
+    /** Instante (epoch ms) em que o job entrou em `processing` — ver regra 3. Opcional. */
+    startedAt?: number;
+    /** `true` só quando o produtor também fornece {@link onCancel} — ver regra 4. Default `false`. */
+    cancelable?: boolean;
+    /** Chamado pelo painel ao usuário pressionar Ctrl+C com este job selecionado, quando `cancelable` é `true`. */
+    onCancel?: () => void;
+    /** Progresso incremental 0–100 (extrações M3/M4). Omitido: indeterminado. */
+    progress?: number;
+    /** Detalhe curto da fase atual ou mensagem de erro (ex.: "transcrevendo áudio"). */
+    detail?: string;
+}
+/** Campos atualizáveis de um job em andamento — ver {@link JobRegistryValue.updateJob}. */
+export interface JobPatch {
+    status?: JobStatus;
+    progress?: number;
+    detail?: string;
+    label?: string;
+}
+/** Valor exposto pelo contexto do registro de jobs. */
+export interface JobRegistryValue {
+    /** Jobs da sessão, na ordem de registro (mais antigo primeiro). */
+    jobs: readonly Job[];
+    /**
+     * Registra um job novo, ou substitui (upsert por `id`) um já existente —
+     * ver regra 1 do contrato.
+     */
+    registerJob: (job: Job) => void;
+    /**
+     * Atualiza campos do job (`status`/`progress`/`detail`/`label`). Sem efeito
+     * se `id` não existir. Transições a partir de estado TERMINAL (`done`/
+     * `failed`) são ignoradas — bug de produtor não regride o painel.
+     */
+    updateJob: (id: string, patch: JobPatch) => void;
+    /** Atalho de compatibilidade: `updateJob(id, { status })`. */
+    updateJobStatus: (id: string, status: JobStatus) => void;
+}
+/**
+ * Provider do registro de jobs — instanciado uma vez em `./app.tsx`,
+ * envolvendo toda a árvore de telas (ver o JSDoc do módulo).
+ */
+export declare function JobRegistryProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Hook do registro de jobs, consumido tanto por produtores (`./screens/export.tsx`,
+ * futuramente extração no M3/M4) quanto pelo painel (`./screens/jobs.tsx`).
+ *
+ * @throws {Error} Se chamado fora de um `<JobRegistryProvider>` — indica erro
+ *   de composição (tela renderizada sem passar pelo roteador).
+ */
+export declare function useJobRegistry(): JobRegistryValue;