redmine-context 1.0.0

package/dist/surfaces/tui/job-registry.js

@@ -0,0 +1,123 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 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 { createContext, useCallback, useContext, useState } from 'react';
+/** Teto de jobs retidos: além disso, os CONCLUÍDOS mais antigos são descartados (GC). */
+const MAX_JOBS = 50;
+/** Estados terminais — não aceitam transição de volta (ver validação no updateJob). */
+const TERMINAL = ['done', 'failed'];
+const JobRegistryContext = createContext(undefined);
+/**
+ * Provider do registro de jobs — instanciado uma vez em `./app.tsx`,
+ * envolvendo toda a árvore de telas (ver o JSDoc do módulo).
+ */
+export function JobRegistryProvider({ children }) {
+    const [jobs, setJobs] = useState([]);
+    // Identidades ESTÁVEIS (useCallback sem deps, padrão do repo) — evita
+    // resubscrições desnecessárias em quem as usa como dependência de efeito
+    // (ex.: `./screens/export.tsx`).
+    const registerJob = useCallback((job) => {
+        setJobs((current) => {
+            const index = current.findIndex((existing) => existing.id === job.id);
+            let next;
+            if (index === -1) {
+                next = [...current, job];
+            }
+            else {
+                next = current.slice();
+                next[index] = job;
+            }
+            // GC: acima do teto, descarta os CONCLUÍDOS mais antigos (em andamento
+            // nunca são descartados) — sessões longas com muitas extrações (M3/M4)
+            // não acumulam sem bound.
+            if (next.length > MAX_JOBS) {
+                const overflow = next.length - MAX_JOBS;
+                let removed = 0;
+                next = next.filter((j) => {
+                    if (removed < overflow && TERMINAL.includes(j.status)) {
+                        removed += 1;
+                        return false;
+                    }
+                    return true;
+                });
+            }
+            return next;
+        });
+    }, []);
+    const updateJob = useCallback((id, patch) => {
+        setJobs((current) => current.map((job) => {
+            if (job.id !== id)
+                return job;
+            if (TERMINAL.includes(job.status) && patch.status !== undefined && patch.status !== job.status) {
+                // Estado terminal não regride — ignora a transição inválida inteira.
+                return job;
+            }
+            return { ...job, ...patch };
+        }));
+    }, []);
+    const updateJobStatus = useCallback((id, status) => {
+        updateJob(id, { status });
+    }, [updateJob]);
+    const value = { jobs, registerJob, updateJob, updateJobStatus };
+    return _jsx(JobRegistryContext.Provider, { value: value, children: children });
+}
+/**
+ * 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 function useJobRegistry() {
+    const value = useContext(JobRegistryContext);
+    if (value === undefined) {
+        throw new Error('useJobRegistry() usado fora de <JobRegistryProvider>.');
+    }
+    return value;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Mapeamento visual do status de job (#34/M2-11) — ícone (com fallback ASCII
+ * via `./symbols.ts`) e cor (token do tema) para cada {@link JobStatus},
+ * consumido por `./screens/jobs.tsx`. Mesmo padrão de `./attachment-status.ts`,
+ * extraído para um módulo à parte para poder ser testado sem montar a tela.
+ *
+ * `processing` não tem um ícone estático — o painel usa o `Spinner` já
+ * existente (`./components/spinner.tsx`) para esse estado, então
+ * {@link jobStatusIcon} devolve `undefined` para ele (ver a doc da função).
+ */
+import type { JobStatus } from './job-registry.js';
+import type { Theme } from './theme.js';
+/**
+ * Cor (token do tema) do ícone/rótulo de status — nunca uma cor literal
+ * (varredura anti-hardcode, `tests/surfaces/tui/no-hardcoded-colors.test.ts`).
+ *
+ * `pending` = `muted` (neutro, aguardando), `processing` = `primary`
+ * (operação ativa, mesma cor do `Spinner`), `done` = `success`, `failed` =
+ * `danger`.
+ *
+ * @param theme - Tema ativo (via `useTheme()` no chamador).
+ * @param status - Status do job.
+ * @returns O token de cor do tema mais adequado ao status.
+ */
+export declare function jobStatusColor(theme: Theme, status: JobStatus): string;
+/**
+ * Ícone estático do status, ou `undefined` para `processing` — nesse caso o
+ * painel (`./screens/jobs.tsx`) renderiza o `Spinner` animado existente em
+ * vez de um ícone parado.
+ *
+ * @param status - Status do job.
+ * @returns O símbolo (de `./symbols.ts`, com fallback ASCII automático) ou
+ *   `undefined`.
+ * @example
+ * jobStatusIcon('done')       // symbols.tick
+ * jobStatusIcon('processing') // undefined — usar <Spinner /> no lugar
+ */
+export declare function jobStatusIcon(status: JobStatus): string | undefined;
+/**
+ * Rótulo textual (pt-BR) do status, exibido ao lado do label do job.
+ *
+ * @param status - Status do job.
+ * @returns O rótulo a exibir (ex.: `[concluído]`).
+ */
+export declare function jobStatusLabel(status: JobStatus): string;

package/dist/surfaces/tui/job-status.js

@@ -0,0 +1,81 @@
+import { symbols } from './symbols.js';
+/**
+ * Cor (token do tema) do ícone/rótulo de status — nunca uma cor literal
+ * (varredura anti-hardcode, `tests/surfaces/tui/no-hardcoded-colors.test.ts`).
+ *
+ * `pending` = `muted` (neutro, aguardando), `processing` = `primary`
+ * (operação ativa, mesma cor do `Spinner`), `done` = `success`, `failed` =
+ * `danger`.
+ *
+ * @param theme - Tema ativo (via `useTheme()` no chamador).
+ * @param status - Status do job.
+ * @returns O token de cor do tema mais adequado ao status.
+ */
+export function jobStatusColor(theme, status) {
+    switch (status) {
+        case 'pending':
+            return theme.muted;
+        case 'processing':
+            return theme.primary;
+        case 'done':
+            return theme.success;
+        case 'failed':
+            return theme.danger;
+        default: {
+            // Exaustividade: se a união ganhar um novo membro sem atualizar este
+            // switch, o typecheck falha aqui (nunca em runtime).
+            const exhaustiveCheck = status;
+            return exhaustiveCheck;
+        }
+    }
+}
+/**
+ * Ícone estático do status, ou `undefined` para `processing` — nesse caso o
+ * painel (`./screens/jobs.tsx`) renderiza o `Spinner` animado existente em
+ * vez de um ícone parado.
+ *
+ * @param status - Status do job.
+ * @returns O símbolo (de `./symbols.ts`, com fallback ASCII automático) ou
+ *   `undefined`.
+ * @example
+ * jobStatusIcon('done')       // symbols.tick
+ * jobStatusIcon('processing') // undefined — usar <Spinner /> no lugar
+ */
+export function jobStatusIcon(status) {
+    switch (status) {
+        case 'pending':
+            return symbols.circle;
+        case 'processing':
+            return undefined;
+        case 'done':
+            return symbols.tick;
+        case 'failed':
+            return symbols.cross;
+        default: {
+            const exhaustiveCheck = status;
+            return exhaustiveCheck;
+        }
+    }
+}
+/**
+ * Rótulo textual (pt-BR) do status, exibido ao lado do label do job.
+ *
+ * @param status - Status do job.
+ * @returns O rótulo a exibir (ex.: `[concluído]`).
+ */
+export function jobStatusLabel(status) {
+    switch (status) {
+        case 'pending':
+            return 'pendente';
+        case 'processing':
+            return 'processando';
+        case 'done':
+            return 'concluído';
+        case 'failed':
+            return 'falhou';
+        default: {
+            const exhaustiveCheck = status;
+            return exhaustiveCheck;
+        }
+    }
+}

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

@@ -0,0 +1,74 @@
+/**
+ * Contexto de navegação da TUI (M2-01, evoluído em M2-04 para uma PILHA de
+ * telas).
+ *
+ * Expõe a pilha de telas navegadas — a base (índice 0) é sempre a tela
+ * inicial, o topo (`stack.at(-1)`) é a tela renderizada — e as operações que
+ * a manipulam: `push` (avança, empilha), `pop` (volta, usado pelo Esc
+ * global em `app.tsx`) e `replace` (troca o topo sem aumentar a
+ * profundidade). O breadcrumb fixo (`components/breadcrumb.tsx`) lê `stack`
+ * direto para renderizar o caminho "Início › Atalhos".
+ *
+ * `navigate()` é mantido como alias de `push()` — nome original da API do
+ * M2-01 — para que as telas existentes (`screens/welcome.tsx`) não
+ * precisassem ser reescritas junto desta evolução.
+ *
+ * O roteador (`app.tsx`) é o único lugar que instancia o `Provider`; o
+ * estado real da pilha vive em {@link useNavigationStack}, extraído para cá
+ * (em vez de inline no roteador) para poder ser testado isoladamente, sem
+ * depender de handlers de teclado.
+ */
+import { type ReactNode } from 'react';
+import type { ScreenName } from './screen.js';
+/** Valor exposto pelo contexto de navegação. */
+export interface NavigationValue {
+    /** Pilha de telas navegadas — a base (índice 0) é sempre a tela inicial. */
+    stack: readonly ScreenName[];
+    /** Tela atualmente roteada — sempre o topo da pilha (`stack.at(-1)`). */
+    current: ScreenName;
+    /** Empilha uma nova tela (navegação "para frente"). */
+    push(next: ScreenName): void;
+    /** Alias de {@link push} — nome original da API do M2-01, mantido por compat. */
+    navigate(next: ScreenName): void;
+    /** Desempilha a tela atual, voltando à anterior. Nada faz na raiz (pilha com 1 item). */
+    pop(): void;
+    /** Substitui o topo da pilha por outra tela, sem alterar a profundidade. */
+    replace(next: ScreenName): void;
+    /** Zera a pilha para uma única tela (fim de fluxo multi-tela). */
+    resetTo(next: ScreenName): void;
+    /**
+     * Desempilha repetidamente até `target` ficar no topo — usado para
+     * retomar a navegação após um fluxo empilhado por cima de uma tela de
+     * origem (ex.: re-autenticação, M2-13/#36: `onboarding-login` é
+     * empilhado sobre a tela de dados que recebeu um 401; ao logar de novo,
+     * `popTo(origin)` desfaz esse empilhamento de uma vez, mesmo que o login
+     * tenha passado por telas intermediárias como `onboarding-api-key`).
+     *
+     * Fix do review #119: se `target` não estiver na pilha (ex.: abandono do
+     * re-auth via Esc, `../app.tsx`, numa sessão onde a origem já não é mais
+     * alcançável), cai em {@link resetTo} — zera a pilha para `target` — em
+     * vez de silenciosamente não fazer nada (o que deixaria o usuário preso
+     * numa tela de onboarding sem saída visível).
+     */
+    popTo(target: ScreenName): void;
+}
+/** Provider do contexto de navegação — usado apenas pelo roteador (`app.tsx`). */
+export declare function NavigationProvider({ value, children, }: {
+    value: NavigationValue;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Hook de navegação consumido pelas telas.
+ *
+ * @throws {Error} Se chamado fora de um `<NavigationProvider>` — indica erro
+ *   de composição (tela renderizada sem passar pelo roteador).
+ */
+export declare function useNavigation(): NavigationValue;
+/**
+ * Estado real da pilha de navegação — hook interno usado apenas pelo
+ * roteador (`app.tsx`), que instancia o `NavigationProvider` com o valor
+ * retornado aqui.
+ *
+ * @param initial Tela na base da pilha (única tela quando o app abre).
+ */
+export declare function useNavigationStack(initial: ScreenName): NavigationValue;

package/dist/surfaces/tui/navigation.js

@@ -0,0 +1,87 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Contexto de navegação da TUI (M2-01, evoluído em M2-04 para uma PILHA de
+ * telas).
+ *
+ * Expõe a pilha de telas navegadas — a base (índice 0) é sempre a tela
+ * inicial, o topo (`stack.at(-1)`) é a tela renderizada — e as operações que
+ * a manipulam: `push` (avança, empilha), `pop` (volta, usado pelo Esc
+ * global em `app.tsx`) e `replace` (troca o topo sem aumentar a
+ * profundidade). O breadcrumb fixo (`components/breadcrumb.tsx`) lê `stack`
+ * direto para renderizar o caminho "Início › Atalhos".
+ *
+ * `navigate()` é mantido como alias de `push()` — nome original da API do
+ * M2-01 — para que as telas existentes (`screens/welcome.tsx`) não
+ * precisassem ser reescritas junto desta evolução.
+ *
+ * O roteador (`app.tsx`) é o único lugar que instancia o `Provider`; o
+ * estado real da pilha vive em {@link useNavigationStack}, extraído para cá
+ * (em vez de inline no roteador) para poder ser testado isoladamente, sem
+ * depender de handlers de teclado.
+ */
+import { createContext, useCallback, useContext, useState } from 'react';
+const NavigationContext = createContext(undefined);
+/** Provider do contexto de navegação — usado apenas pelo roteador (`app.tsx`). */
+export function NavigationProvider({ value, children, }) {
+    return _jsx(NavigationContext.Provider, { value: value, children: children });
+}
+/**
+ * Hook de navegação consumido pelas telas.
+ *
+ * @throws {Error} Se chamado fora de um `<NavigationProvider>` — indica erro
+ *   de composição (tela renderizada sem passar pelo roteador).
+ */
+export function useNavigation() {
+    const value = useContext(NavigationContext);
+    if (value === undefined) {
+        throw new Error('useNavigation() usado fora de <NavigationProvider>.');
+    }
+    return value;
+}
+/**
+ * Estado real da pilha de navegação — hook interno usado apenas pelo
+ * roteador (`app.tsx`), que instancia o `NavigationProvider` com o valor
+ * retornado aqui.
+ *
+ * @param initial Tela na base da pilha (única tela quando o app abre).
+ */
+export function useNavigationStack(initial) {
+    const [stack, setStack] = useState([initial]);
+    const push = useCallback((next) => {
+        setStack((current) => [...current, next]);
+    }, []);
+    const pop = useCallback(() => {
+        setStack((current) => (current.length > 1 ? current.slice(0, -1) : current));
+    }, []);
+    const replace = useCallback((next) => {
+        setStack((current) => [...current.slice(0, -1), next]);
+    }, []);
+    // Zera a pilha para uma única tela — fim de fluxos multi-tela (ex.: splash
+    // do onboarding, logout): sem isso, Esc "voltaria" para telas do fluxo
+    // encerrado que continuam empilhadas por baixo.
+    const resetTo = useCallback((next) => {
+        setStack(() => [next]);
+    }, []);
+    // Corta a pilha logo após a última ocorrência de `target` — equivalente a
+    // chamar `pop()` repetidamente até `target` virar o topo, mas em uma única
+    // atualização de estado (evita re-renders intermediários).
+    //
+    // Fix do review #119: quando `target` NÃO está na pilha, o comportamento
+    // passa a ser o mesmo de `resetTo(target)` (zera a pilha para uma única
+    // tela) em vez de um no-op silencioso — evita deixar o usuário preso numa
+    // tela sem rota de volta visível (ex.: abandono do re-auth, `../app.tsx`).
+    const popTo = useCallback((target) => {
+        setStack((current) => {
+            const index = current.lastIndexOf(target);
+            if (index === -1) {
+                return [target];
+            }
+            return current.slice(0, index + 1);
+        });
+    }, []);
+    // Reason: a pilha sempre tem ao menos 1 item (inicializada com `initial`,
+    // `pop()` nunca a esvazia) — o fallback só existe para satisfazer
+    // `noUncheckedIndexedAccess` do TypeScript, nunca é de fato alcançado.
+    const current = stack[stack.length - 1] ?? initial;
+    return { stack, current, push, navigate: push, pop, replace, resetTo, popTo };
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Kits de PALETAS de cores da TUI (#190).
+ *
+ * Cada paleta é um {@link Theme} COMPLETO em truecolor (hex), curado a partir de
+ * esquemas de cor consagrados. Trocar de paleta é escolher um `id` aqui — o
+ * `ThemeProvider` (`./theme.tsx`) recebe o `Theme` resolvido. Este arquivo é a
+ * ÚNICA fonte de literais hex (junto de `theme.tsx`); as telas nunca declaram cor
+ * literal (varredura `no-hardcoded-colors.test.ts`), sempre via `useTheme()`.
+ *
+ * Os valores hex são bem conhecidos dos respectivos projetos de tema. A
+ * degradação para texto puro (NO_COLOR/CI/não-TTY) é decidida ANTES de a TUI
+ * subir (`shouldRenderTui`), então aqui só existem terminais com cor.
+ */
+import type { Theme } from './theme.js';
+/** Uma paleta nomeada: metadados + o {@link Theme} completo. */
+export interface Palette {
+    /** Identificador estável (persistido em settings.json). */
+    readonly id: string;
+    /** Rótulo legível exibido no seletor. */
+    readonly label: string;
+    /** Tema completo (truecolor) desta paleta. */
+    readonly theme: Theme;
+}
+/**
+ * Lista ORDENADA de paletas (a ordem é a do seletor). A primeira é o default
+ * quando não há escolha persistida ({@link DEFAULT_PALETTE_ID}).
+ */
+export declare const PALETTES: readonly Palette[];
+/** Id da paleta default (a primeira da lista) — usada sem escolha persistida. */
+export declare const DEFAULT_PALETTE_ID: string;
+/**
+ * Resolve uma paleta por `id`, com fallback para a default se o `id` for
+ * desconhecido (ex.: settings.json com uma paleta removida numa versão futura).
+ *
+ * @param id - Id persistido (ou `undefined`).
+ * @returns A paleta correspondente, ou a default.
+ */
+export declare function resolvePalette(id: string | undefined): Palette;