redmine-context 1.0.0 → 1.1.0

package/README.md

@@ -2,6 +2,13 @@
 
 Consumidor de Redmine que entrega contexto completo de issues — texto e mídia (áudio/vídeo/imagem) extraída **100% localmente** — para qualquer LLM, via MCP server, CLI e TUI.
 
+![Demo: um print anexado a uma issue vira contexto pesquisável, sem nada sair da máquina](demo/redmine-context.gif)
+
+O print de erro anexado na issue é opaco para qualquer ferramenta. Com `--extract`,
+o `tesseract` roda **na sua máquina** e o stack trace passa a fazer parte do
+contexto — o mesmo bundle que o MCP entrega ao seu LLM. Nada é enviado para
+lugar nenhum. O roteiro dessa gravação é reprodutível: [`demo/demo.tape`](demo/demo.tape).
+
 > Planejamento: `documentation/development/PLAN.md` · Backlog: `documentation/development/BACKLOG.md` · Decisões: `documentation/adr/`
 
 ## Requisitos
@@ -142,9 +149,14 @@ redmine-context issue 42            # usa a instância salva no login (ou --url/
 #    --extract liga o OCR dos anexos de imagem e embute o texto no bundle
 #    (requer tesseract; ver Extração de mídia abaixo).
 
+# 2b) last — quando você NÃO sabe o id: imprime o bundle da issue mais recente.
+#     --order updated (padrão) | created | priority   --count <n> (padrão 1, teto 5)
+redmine-context last
+redmine-context last --order priority --count 3
+
 # 3) mcp add — registra o MCP server no seu cliente (ex.: Claude) para expor as
-#    tools read-only get_issue_context, search_issues e get_attachment_text,
-#    usando a mesma credencial da cascata.
+#    tools read-only get_issue_context, search_issues, get_attachment_text e
+#    get_last, usando a mesma credencial da cascata.
 claude mcp add redmine-context \
   --env REDMINE_URL=https://redmine.example \
   -- npx -y redmine-context mcp
@@ -188,11 +200,12 @@ Detalhes e passos manuais (adicionar `NPM_TOKEN`, tornar o repo público, dispar
 
 ## MCP server (stdio)
 
-O subcomando `redmine-context mcp` sobe um servidor [MCP](https://modelcontextprotocol.io) sobre stdio, expondo três tools read-only:
+O subcomando `redmine-context mcp` sobe um servidor [MCP](https://modelcontextprotocol.io) sobre stdio, expondo quatro tools read-only:
 
 - `get_issue_context(issue_id: number, format?: 'markdown' | 'json', extract_attachments?: boolean)` — busca a issue na instância configurada, normaliza e retorna o bundle (Markdown por padrão). Com `extract_attachments: true`, embute o texto (OCR) dos anexos de imagem no bundle (default `false`, pois adiciona latência de download+OCR).
 - `search_issues(query?, project_id?, status_id?, assigned_to_id?, updated_on?, limit?)` — busca issues por filtros estruturados e, opcionalmente, texto livre (`query`, best-effort via `/search`); retorna uma lista compacta paginada.
 - `get_attachment_text(issue_id: number, attachment_id: number)` — retorna o texto extraído (OCR, com cache) de um anexo, 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`), nunca um erro genérico.
+- `get_last(order?, count?, format?, extract_attachments?)` — retorna o **bundle completo** das issues mais recentes, sem exigir o id. `order` é `updated` (padrão, mexida mais recente), `created` (entrada mais recente) ou `priority` (mais urgente, desempatando pela mais recente); `count` vai até 5 (padrão 1). Considera apenas issues **abertas** — para filtrar por projeto/status/responsável, use `search_issues`. Em `format: 'json'` a saída é **sempre um array**, pois a tool devolve uma coleção.
 
 A instância vem sempre da configuração do processo (`REDMINE_URL` + cascata de credencial, `REDMINE_API_KEY` no modo headless): **nenhuma tool aceita URL/host arbitrário**. Erros 403/404 e credencial ausente retornam um erro MCP claro (`isError`). O stdout é reservado ao protocolo; logs vão para stderr.
 
@@ -213,8 +226,8 @@ Passe a instância via `--env` (aplicado ao ambiente do servidor), por exemplo
 `claude mcp add redmine-context --env REDMINE_URL=https://redmine.example -- npx -y redmine-context mcp`.
 Configure o ambiente do servidor com `REDMINE_URL` e `REDMINE_API_KEY` (ou rode
 `redmine-context login` para gravar a credencial na cascata). Com a integração
-ativa, o cliente ganha as tools read-only `get_issue_context`, `search_issues` e
-`get_attachment_text` (detalhadas acima).
+ativa, o cliente ganha as tools read-only `get_issue_context`, `search_issues`,
+`get_attachment_text` e `get_last` (detalhadas acima).
 
 ## Extração de mídia (OCR)
 
@@ -254,6 +267,8 @@ redmine-context doctor    # exit 0 se tudo presente, 1 se faltar algum
 
 ## TUI interativa
 
+![A TUI: banner com o gradiente da paleta ativa e a tela de Aparência trocando entre as 12 paletas](demo/tui.gif)
+
 `redmine-context` **sem argumentos** (num terminal interativo) abre a interface
 de texto completa — mesma credencial e mesmo core da CLI/MCP:
 

package/dist/bundle/journal-detail.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Semântica dos `journal.details` do Redmine — rótulos legíveis e ids resolvidos.
+ *
+ * A API grava o nome CRU da coluna (`status_id`, `done_ratio`) e os valores como
+ * ids, então `status_id: 12 → 7` não informa nada a quem lê — nem humano nem LLM.
+ * Este módulo traduz isso UMA vez, para TODAS as superfícies: o bundle Markdown
+ * (`./markdown.ts`) e a tela de detalhe da TUI consumiam a mesma informação e
+ * divergiam, com a TUI mostrando os ids crus.
+ *
+ * Cada parte devolvida diz se é texto NOSSO (`trusted`) ou conteúdo derivado do
+ * Redmine (`trusted: false`). Quem renderiza decide a política: o bundle envolve
+ * o não confiável em `<untrusted-content>` (anti prompt-injection), a TUI apenas
+ * exibe. A distinção é o motivo de este módulo devolver partes em vez de strings
+ * já formatadas.
+ *
+ * Nada sai como valor CRU sem ser um id inteiro (ver `idToken`): `detail.name` e
+ * `old/new_value` são strings livres da API, e um valor forjado escaparia da
+ * fence do bundle.
+ */
+import type { Issue, JournalDetail } from '../contract.js';
+/**
+ * Dicionários `id → nome` para resolver os ids HISTÓRICOS de um journal.
+ *
+ * Sem eles só o valor que coincide com o estado atual da issue ganha nome, e o
+ * outro lado da alteração fica como `#id` — ilegível ("não sei o que é status
+ * 12"). Todos os campos são opcionais: o que faltar degrada para `#id`.
+ */
+export interface DetailLookups {
+    /** `id → nome` de status (`/issue_statuses.json`). */
+    readonly status?: ReadonlyMap<number, string> | undefined;
+    /** `id → nome` de trackers (`/trackers.json`). */
+    readonly tracker?: ReadonlyMap<number, string> | undefined;
+    /** `id → nome` de prioridades (`/enumerations/issue_priorities.json`). */
+    readonly priority?: ReadonlyMap<number, string> | undefined;
+    /** `id → nome` de usuários (ver {@link collectUsers}). */
+    readonly user?: ReadonlyMap<number, string> | undefined;
+}
+/**
+ * Monta o dicionário de usuários a partir da PRÓPRIA issue — sem rede.
+ *
+ * `/users.json` exige admin na maioria das instâncias, mas os nomes já circulam
+ * no payload: autor, responsável, autor de cada journal, autor de cada anexo e
+ * watchers. Isso costuma cobrir os ids que aparecem no histórico, já que quem
+ * mexeu na issue quase sempre deixou um journal.
+ *
+ * @param issue - Issue normalizada.
+ * @returns Mapa `id → nome` com todos os usuários citados no payload.
+ */
+export declare function collectUsers(issue: Issue): ReadonlyMap<number, string>;
+/**
+ * Um pedaço de texto pronto para exibir, com a marca de confiança.
+ */
+export interface DetailPart {
+    /** Texto a exibir. */
+    text: string;
+    /**
+     * `true` quando o texto é NOSSO (rótulo traduzido, `#id`, `40%`) e dispensa
+     * marcação de conteúdo não confiável; `false` quando vem do Redmine.
+     */
+    trusted: boolean;
+}
+/**
+ * Rótulo de um detail de journal.
+ *
+ * @param detail - Detalhe do journal.
+ * @param issue - Issue normalizada (resolve nomes de custom field).
+ * @returns O rótulo e sua marca de confiança.
+ * @example
+ * journalDetailLabel({ property: 'attr', name: 'status_id' }, issue)
+ * // { text: 'Status', trusted: true }
+ */
+export declare function journalDetailLabel(detail: JournalDetail, issue: Issue): DetailPart;
+/**
+ * Um lado (antes/depois) de uma alteração.
+ *
+ * Ids de referência recebem `#` para nunca parecerem número solto. O nome vem,
+ * em ordem: do dicionário da instância (`lookups`, que resolve qualquer id,
+ * inclusive os históricos) ou do estado ATUAL da issue, quando o id coincide. A comparação é segura:
+ * só o último journal que alterou um campo tem `new_value` igual ao valor
+ * corrente, então nenhum valor histórico é nomeado incorretamente.
+ *
+ * @param detail - Detalhe do journal (define como o valor é interpretado).
+ * @param raw - Valor bruto (`old_value` ou `new_value`).
+ * @param issue - Issue normalizada (resolve refs pelo estado atual).
+ * @param lookups - Dicionários da instância; ausentes ⇒ degrada para `#id`.
+ * @returns A parte a exibir, ou `undefined` para ausência (cada superfície usa
+ *   seu próprio placeholder).
+ */
+export declare function journalDetailValue(detail: JournalDetail, raw: string | null | undefined, issue: Issue, lookups?: DetailLookups): DetailPart | undefined;

package/dist/bundle/journal-detail.js

@@ -0,0 +1,240 @@
+/**
+ * Semântica dos `journal.details` do Redmine — rótulos legíveis e ids resolvidos.
+ *
+ * A API grava o nome CRU da coluna (`status_id`, `done_ratio`) e os valores como
+ * ids, então `status_id: 12 → 7` não informa nada a quem lê — nem humano nem LLM.
+ * Este módulo traduz isso UMA vez, para TODAS as superfícies: o bundle Markdown
+ * (`./markdown.ts`) e a tela de detalhe da TUI consumiam a mesma informação e
+ * divergiam, com a TUI mostrando os ids crus.
+ *
+ * Cada parte devolvida diz se é texto NOSSO (`trusted`) ou conteúdo derivado do
+ * Redmine (`trusted: false`). Quem renderiza decide a política: o bundle envolve
+ * o não confiável em `<untrusted-content>` (anti prompt-injection), a TUI apenas
+ * exibe. A distinção é o motivo de este módulo devolver partes em vez de strings
+ * já formatadas.
+ *
+ * Nada sai como valor CRU sem ser um id inteiro (ver `idToken`): `detail.name` e
+ * `old/new_value` são strings livres da API, e um valor forjado escaparia da
+ * fence do bundle.
+ */
+/**
+ * Monta o dicionário de usuários a partir da PRÓPRIA issue — sem rede.
+ *
+ * `/users.json` exige admin na maioria das instâncias, mas os nomes já circulam
+ * no payload: autor, responsável, autor de cada journal, autor de cada anexo e
+ * watchers. Isso costuma cobrir os ids que aparecem no histórico, já que quem
+ * mexeu na issue quase sempre deixou um journal.
+ *
+ * @param issue - Issue normalizada.
+ * @returns Mapa `id → nome` com todos os usuários citados no payload.
+ */
+export function collectUsers(issue) {
+    const users = new Map();
+    const add = (ref) => {
+        if (ref !== undefined && ref.id !== 0 && ref.name.length > 0)
+            users.set(ref.id, ref.name);
+    };
+    add(issue.author);
+    add(issue.assigned_to);
+    for (const journal of issue.journals)
+        add(journal.user);
+    for (const attachment of issue.attachments)
+        add(attachment.author);
+    for (const watcher of issue.watchers ?? [])
+        add(watcher);
+    return users;
+}
+/** Dicionário da enumeração correspondente a um atributo. */
+function lookupFor(attr, lookups) {
+    if (lookups === undefined)
+        return undefined;
+    switch (attr) {
+        case 'status_id':
+            return lookups.status;
+        case 'tracker_id':
+            return lookups.tracker;
+        case 'priority_id':
+            return lookups.priority;
+        case 'assigned_to_id':
+        case 'author_id':
+            return lookups.user;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Rótulos legíveis dos atributos padrão do Redmine.
+ *
+ * Vocabulário fixo da ferramenta (não conteúdo da instância), portanto texto
+ * confiável.
+ */
+const ATTR_LABELS = {
+    subject: 'Assunto',
+    description: 'Descrição',
+    project_id: 'Projeto',
+    tracker_id: 'Tracker',
+    status_id: 'Status',
+    priority_id: 'Prioridade',
+    author_id: 'Autor',
+    assigned_to_id: 'Responsável',
+    category_id: 'Categoria',
+    fixed_version_id: 'Versão',
+    parent_id: 'Issue pai',
+    child_id: 'Sub-issue',
+    done_ratio: 'Progresso',
+    start_date: 'Início',
+    due_date: 'Prazo',
+    estimated_hours: 'Estimativa',
+    is_private: 'Privada',
+};
+/** Atributos cujo valor é o número de OUTRA issue (não um id de enumeração). */
+const ISSUE_REF_ATTRS = new Set(['parent_id', 'child_id']);
+/**
+ * Tipos de relação do Redmine — vocabulário FECHADO, portanto confiável. Um
+ * valor fora desta lista é tratado como conteúdo derivado.
+ */
+const RELATION_TYPES = new Set([
+    'relates',
+    'duplicates',
+    'duplicated',
+    'blocks',
+    'blocked',
+    'precedes',
+    'follows',
+    'copied_to',
+    'copied_from',
+]);
+/**
+ * Porteiro dos valores exibidos sem marcação.
+ *
+ * @param raw - Valor bruto do detail.
+ * @returns O próprio valor se for um inteiro não negativo; senão `undefined`.
+ */
+function idToken(raw) {
+    return /^\d+$/.test(raw) ? raw : undefined;
+}
+/**
+ * Ref ATUAL da issue correspondente a um atributo, quando o contrato a carrega.
+ *
+ * Usada só para NOMEAR um id que coincide com o estado corrente; nunca para
+ * inferir estado histórico.
+ *
+ * @param issue - Issue normalizada.
+ * @param attr - Nome cru do atributo (ex.: `status_id`).
+ * @returns A ref atual, ou `undefined` se o atributo não tiver uma no contrato.
+ */
+function currentRefFor(issue, attr) {
+    switch (attr) {
+        case 'project_id':
+            return issue.project;
+        case 'tracker_id':
+            return issue.tracker;
+        case 'status_id':
+            return issue.status;
+        case 'priority_id':
+            return issue.priority;
+        case 'author_id':
+            return issue.author;
+        case 'assigned_to_id':
+            return issue.assigned_to;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Nome do custom field a partir do id: num detail `cf`, o `name` é o ID do campo
+ * (não o rótulo), e sai como número solto sem esta resolução.
+ *
+ * @param issue - Issue normalizada (fonte dos `custom_fields`).
+ * @param rawId - `detail.name` de um detail `cf`.
+ * @returns O nome do campo, ou `undefined` se o id não constar na issue.
+ */
+function customFieldName(issue, rawId) {
+    const id = Number(rawId);
+    if (!Number.isInteger(id))
+        return undefined;
+    return issue.custom_fields.find((field) => field.id === id)?.name;
+}
+/**
+ * Rótulo de um detail de journal.
+ *
+ * @param detail - Detalhe do journal.
+ * @param issue - Issue normalizada (resolve nomes de custom field).
+ * @returns O rótulo e sua marca de confiança.
+ * @example
+ * journalDetailLabel({ property: 'attr', name: 'status_id' }, issue)
+ * // { text: 'Status', trusted: true }
+ */
+export function journalDetailLabel(detail, issue) {
+    if (detail.property === 'cf') {
+        const name = customFieldName(issue, detail.name);
+        // Nome definido pelo admin da instância: conteúdo derivado.
+        if (name !== undefined)
+            return { text: name, trusted: false };
+        return { text: `campo #${detail.name}`, trusted: idToken(detail.name) !== undefined };
+    }
+    if (detail.property === 'attachment') {
+        const id = idToken(detail.name);
+        return id === undefined
+            ? { text: `Anexo ${detail.name}`, trusted: false }
+            : { text: `Anexo #${id}`, trusted: true };
+    }
+    if (detail.property === 'relation') {
+        return RELATION_TYPES.has(detail.name)
+            ? { text: `Relação (${detail.name})`, trusted: true }
+            : { text: detail.name, trusted: false };
+    }
+    const label = ATTR_LABELS[detail.name];
+    return label === undefined ? { text: detail.name, trusted: false } : { text: label, trusted: true };
+}
+/**
+ * Um lado (antes/depois) de uma alteração.
+ *
+ * Ids de referência recebem `#` para nunca parecerem número solto. O nome vem,
+ * em ordem: do dicionário da instância (`lookups`, que resolve qualquer id,
+ * inclusive os históricos) ou do estado ATUAL da issue, quando o id coincide. A comparação é segura:
+ * só o último journal que alterou um campo tem `new_value` igual ao valor
+ * corrente, então nenhum valor histórico é nomeado incorretamente.
+ *
+ * @param detail - Detalhe do journal (define como o valor é interpretado).
+ * @param raw - Valor bruto (`old_value` ou `new_value`).
+ * @param issue - Issue normalizada (resolve refs pelo estado atual).
+ * @param lookups - Dicionários da instância; ausentes ⇒ degrada para `#id`.
+ * @returns A parte a exibir, ou `undefined` para ausência (cada superfície usa
+ *   seu próprio placeholder).
+ */
+export function journalDetailValue(detail, raw, issue, lookups) {
+    if (raw === null || raw === undefined || raw === '')
+        return undefined;
+    const id = idToken(raw);
+    // Um detail `relation` registra a issue do outro lado da relação.
+    if (detail.property === 'relation') {
+        return id === undefined ? { text: raw, trusted: false } : { text: `issue #${id}`, trusted: true };
+    }
+    if (detail.property !== 'attr')
+        return { text: raw, trusted: false };
+    if (detail.name === 'done_ratio') {
+        return id === undefined ? { text: raw, trusted: false } : { text: `${id}%`, trusted: true };
+    }
+    if (ISSUE_REF_ATTRS.has(detail.name)) {
+        return id === undefined ? { text: raw, trusted: false } : { text: `issue #${id}`, trusted: true };
+    }
+    // Dicionário da instância primeiro: resolve QUALQUER id, inclusive o valor
+    // histórico que não corresponde mais ao estado atual.
+    if (id !== undefined) {
+        const named = lookupFor(detail.name, lookups)?.get(Number(id));
+        if (named !== undefined)
+            return { text: `${named} (#${id})`, trusted: true };
+    }
+    const ref = currentRefFor(issue, detail.name);
+    if (id !== undefined && ref !== undefined && ref.id !== 0 && String(ref.id) === id) {
+        // O NOME vem do Redmine, mas é a mesma categoria dos metadados estruturais
+        // (status/prioridade/responsável) já exibidos sem marcação nas duas
+        // superfícies — mantém a política existente em vez de criar uma nova.
+        return { text: `${ref.name} (#${id})`, trusted: true };
+    }
+    if (id !== undefined && ATTR_LABELS[detail.name] !== undefined && detail.name.endsWith('_id')) {
+        return { text: `#${id}`, trusted: true };
+    }
+    return { text: raw, trusted: false };
+}

package/dist/bundle/markdown.d.ts

@@ -21,6 +21,7 @@
  * sem baixar o binário.
  */
 import type { Issue } from '../contract.js';
+import { type DetailLookups } from './journal-detail.js';
 import { type ExtractionMap } from './json.js';
 /** Metadados de empacotamento do bundle Markdown (sem timestamp — determinismo). */
 export interface MarkdownBundleMeta {
@@ -33,6 +34,12 @@ export interface MarkdownBundleMeta {
      * a seção "Texto extraído" — o texto de OCR dentro de `<untrusted-content>`.
      */
     extractions?: ExtractionMap;
+    /**
+     * Dicionários `id → nome` da instância (status/tracker/prioridade/usuários).
+     * Sem eles, os ids HISTÓRICOS do journal saem como `#id` — legível, mas sem
+     * significado ("não sei o que é status 12").
+     */
+    lookups?: DetailLookups;
 }
 /**
  * Isola conteúdo não confiável num bloco `<untrusted-content>` de várias linhas.

package/dist/bundle/markdown.js

@@ -20,7 +20,10 @@
  * No M1 os anexos são texto-only: referenciados pela URL de download do Redmine,
  * sem baixar o binário.
  */
+import { journalDetailLabel, journalDetailValue, } from './journal-detail.js';
 import { byId, compareJournals } from './json.js';
+/** Placeholder de valor ausente numa alteração de journal. */
+const ABSENT_VALUE = '∅';
 /** Placeholder para ref degradada (id 0) — nunca um nome vazio silencioso. */
 const UNKNOWN_REF = '(desconhecido)';
 /** Placeholder para ref opcional ausente (distinto de degradada). */
@@ -124,21 +127,25 @@ function renderCustomFields(issue) {
     return ['## Custom Fields', '', ...rows].join('\n');
 }
 /**
- * Renderiza os `details` de um journal. `name` e old/new_value são derivados
- * (em details de "description"/"subject" os values carregam o texto completo
- * do campo) — todos passam pelo fence inline.
+ * Renderiza os `details` de um journal.
+ *
+ * A SEMÂNTICA (rótulos, ids resolvidos) vem de `./journal-detail.js`, compartilhada
+ * com a TUI; aqui só se aplica a política deste formato: o que a semântica marcar
+ * como não confiável entra na fence anti prompt-injection.
  */
-function renderJournalDetails(journal) {
+function renderJournalDetails(journal, issue, lookups) {
+    const fence = (part) => part === undefined ? ABSENT_VALUE : part.trusted ? part.text : fenceInline(part.text);
     return journal.details.map((detail) => {
-        const from = detail.old_value === null || detail.old_value === undefined ? '∅' : fenceInline(detail.old_value);
-        const to = detail.new_value === null || detail.new_value === undefined ? '∅' : fenceInline(detail.new_value);
-        return `  - ${fenceInline(detail.name)}: ${from} → ${to}`;
+        const label = fence(journalDetailLabel(detail, issue));
+        const from = fence(journalDetailValue(detail, detail.old_value, issue, lookups));
+        const to = fence(journalDetailValue(detail, detail.new_value, issue, lookups));
+        return `  - ${label}: ${from} → ${to}`;
     });
 }
 /** Renderiza uma entrada de journal: cabeçalho estrutural + nota (fenced). */
-function renderJournal(journal) {
+function renderJournal(journal, issue, lookups) {
     const lines = [`### Journal #${journal.id} — ${journal.created_on} — ${optionalRefName(journal.user)}`, ''];
-    const details = renderJournalDetails(journal);
+    const details = renderJournalDetails(journal, issue, lookups);
     if (details.length > 0)
         lines.push('Alterações:', ...details, '');
     if (journal.notes !== undefined)
@@ -148,10 +155,12 @@ function renderJournal(journal) {
     return lines.join('\n').trimEnd();
 }
 /** Seção de histórico — journals em ordem cronológica estável (created_on, id). */
-function renderJournals(issue) {
+function renderJournals(issue, lookups) {
     if (issue.journals.length === 0)
         return '## Histórico\n\n_(nenhum)_';
-    const ordered = [...issue.journals].sort(compareJournals).map(renderJournal);
+    const ordered = [...issue.journals]
+        .sort(compareJournals)
+        .map((journal) => renderJournal(journal, issue, lookups));
     return ['## Histórico', ...ordered].join('\n\n');
 }
 /** Seção de relações — tipo + issue alvo (tudo estrutural). */
@@ -283,7 +292,7 @@ export function buildMarkdownBundle(issue, meta) {
         renderHeader(issue),
         renderDescription(issue),
         renderCustomFields(issue),
-        renderJournals(issue),
+        renderJournals(issue, meta.lookups),
         renderRelations(issue),
         renderParent(issue),
         renderChildren(issue),

package/dist/client/enumerations.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Enumerações da instância (status, trackers, prioridades) — `id → nome`.
+ *
+ * O histórico de uma issue guarda apenas ids (`status_id: 12 → 7`), e a issue
+ * carrega o nome SÓ do estado atual. Sem estas listas, metade de cada alteração
+ * fica ilegível: "não sei o que é status 12".
+ *
+ * São coleções pequenas, estáveis e legíveis por qualquer usuário autenticado
+ * (não exigem admin, ao contrário de `/users.json`). O resultado é memoizado por
+ * instância no processo — a TUI e o servidor MCP são processos longos e não
+ * devem repetir estes GETs a cada issue.
+ *
+ * DEGRADAÇÃO (ADR-005): cada endpoint falha de forma independente e silenciosa.
+ * Uma instância que restrinja `/trackers.json` continua resolvendo status e
+ * prioridade; sem nenhum deles, o chamador volta a exibir `#id` — nunca um erro.
+ */
+import type { HttpClient } from './http.js';
+/** Mapas `id → nome` das enumerações usadas na leitura do histórico. */
+export interface RedmineEnumerations {
+    /** `/issue_statuses.json` */
+    readonly status: ReadonlyMap<number, string>;
+    /** `/trackers.json` */
+    readonly tracker: ReadonlyMap<number, string>;
+    /** `/enumerations/issue_priorities.json` */
+    readonly priority: ReadonlyMap<number, string>;
+}
+/**
+ * Busca (e memoiza) as enumerações da instância.
+ *
+ * @param http - Client autenticado da instância.
+ * @param instanceKey - Chave de memoização (a URL base da instância).
+ * @returns Os mapas `id → nome`; vazios nos endpoints que falharem.
+ * @example
+ * const enums = await fetchEnumerations(http, baseUrl);
+ * enums.status.get(12); // 'Estimativa'
+ */
+export declare function fetchEnumerations(http: HttpClient, instanceKey: string): Promise<RedmineEnumerations>;
+/** Limpa a memoização (testes e troca de instância). */
+export declare function clearEnumerationsCache(): void;

package/dist/client/enumerations.js

@@ -0,0 +1,76 @@
+/**
+ * Enumerações da instância (status, trackers, prioridades) — `id → nome`.
+ *
+ * O histórico de uma issue guarda apenas ids (`status_id: 12 → 7`), e a issue
+ * carrega o nome SÓ do estado atual. Sem estas listas, metade de cada alteração
+ * fica ilegível: "não sei o que é status 12".
+ *
+ * São coleções pequenas, estáveis e legíveis por qualquer usuário autenticado
+ * (não exigem admin, ao contrário de `/users.json`). O resultado é memoizado por
+ * instância no processo — a TUI e o servidor MCP são processos longos e não
+ * devem repetir estes GETs a cada issue.
+ *
+ * DEGRADAÇÃO (ADR-005): cada endpoint falha de forma independente e silenciosa.
+ * Uma instância que restrinja `/trackers.json` continua resolvendo status e
+ * prioridade; sem nenhum deles, o chamador volta a exibir `#id` — nunca um erro.
+ */
+/** Enumerações vazias — usado quando tudo falha (degradação total). */
+const EMPTY = {
+    status: new Map(),
+    tracker: new Map(),
+    priority: new Map(),
+};
+/** Entradas memoizadas por instância. */
+const memo = new Map();
+/** Converte `{ chave: [{id, name}] }` em `Map<id, name>`; erro ⇒ mapa vazio. */
+async function fetchMap(http, path, key) {
+    const out = new Map();
+    try {
+        const body = (await http.get(path, {}));
+        const rows = body[key];
+        if (!Array.isArray(rows))
+            return out;
+        for (const row of rows) {
+            if (typeof row !== 'object' || row === null)
+                continue;
+            const { id, name } = row;
+            if (typeof id === 'number' && typeof name === 'string' && name.length > 0)
+                out.set(id, name);
+        }
+    }
+    catch {
+        // Endpoint indisponível/sem permissão: degrada para mapa vazio (o chamador
+        // volta a exibir `#id`). Nunca propaga — isto é enriquecimento, não dado
+        // essencial do bundle.
+    }
+    return out;
+}
+/**
+ * Busca (e memoiza) as enumerações da instância.
+ *
+ * @param http - Client autenticado da instância.
+ * @param instanceKey - Chave de memoização (a URL base da instância).
+ * @returns Os mapas `id → nome`; vazios nos endpoints que falharem.
+ * @example
+ * const enums = await fetchEnumerations(http, baseUrl);
+ * enums.status.get(12); // 'Estimativa'
+ */
+export function fetchEnumerations(http, instanceKey) {
+    const cached = memo.get(instanceKey);
+    if (cached !== undefined)
+        return cached;
+    const pending = (async () => {
+        const [status, tracker, priority] = await Promise.all([
+            fetchMap(http, '/issue_statuses.json', 'issue_statuses'),
+            fetchMap(http, '/trackers.json', 'trackers'),
+            fetchMap(http, '/enumerations/issue_priorities.json', 'issue_priorities'),
+        ]);
+        return { status, tracker, priority };
+    })().catch(() => EMPTY);
+    memo.set(instanceKey, pending);
+    return pending;
+}
+/** Limpa a memoização (testes e troca de instância). */
+export function clearEnumerationsCache() {
+    memo.clear();
+}

package/dist/client/index.d.ts

@@ -3,3 +3,4 @@ export { createHttpClient, redactSecret, validateBaseUrl, type HttpClient, type
 export { RedmineHttpError, RedmineAuthError, RedmineForbiddenError, RedmineNotFoundError, httpErrorFor, } from './errors.js';
 export { getIssue, listIssues, type RedmineIssuePayload, type ListIssuesOptions, } from './issues.js';
 export { searchIssues, SEARCH_MAX_LIMIT, type SearchIssuesOptions, type SearchIssuesPage, type RedmineSearchHit, } from './search.js';
+export { fetchEnumerations, clearEnumerationsCache, type RedmineEnumerations, } from './enumerations.js';

package/dist/client/index.js

@@ -3,3 +3,4 @@ export { createHttpClient, redactSecret, validateBaseUrl, } from './http.js';
 export { RedmineHttpError, RedmineAuthError, RedmineForbiddenError, RedmineNotFoundError, httpErrorFor, } from './errors.js';
 export { getIssue, listIssues, } from './issues.js';
 export { searchIssues, SEARCH_MAX_LIMIT, } from './search.js';
+export { fetchEnumerations, clearEnumerationsCache, } from './enumerations.js';

package/dist/fetch-issue-bundle.js

@@ -13,7 +13,8 @@ import { buildJsonBundle } from './bundle/index.js';
 import { buildMarkdownBundle } from './bundle/index.js';
 import { extractIssueAttachmentsCacheFirst, makeQueueBackgroundExtractor, processingResult, } from './cache-first.js';
 import { DiskCacheStore } from './cache/index.js';
-import { createHttpClient, getIssue } from './client/index.js';
+import { collectUsers } from './bundle/journal-detail.js';
+import { createHttpClient, fetchEnumerations, getIssue } from './client/index.js';
 import { extractIssueAttachments } from './extract-issue-attachments.js';
 import { createDefaultRegistry } from './extract/index.js';
 import { normalizeIssue } from './normalize/index.js';
@@ -82,8 +83,22 @@ export async function* fetchIssueBundle(options) {
             });
         }
     }
+    // Dicionários da instância: sem eles os ids HISTÓRICOS do journal saem como
+    // `#id`. `fetchEnumerations` é memoizado por instância e degrada em silêncio,
+    // então o custo é uma vez por processo e a falha nunca derruba o bundle. Só
+    // vale a busca quando existe histórico para traduzir.
+    let lookups;
+    if (issue.journals.length > 0) {
+        const enums = await fetchEnumerations(http, baseUrl);
+        lookups = { ...enums, user: collectUsers(issue) };
+    }
     yield progress('bundle', `Empacotando bundle (${format})`);
-    const meta = { baseUrl, toolVersion, ...(extractions !== undefined ? { extractions } : {}) };
+    const meta = {
+        baseUrl,
+        toolVersion,
+        ...(extractions !== undefined ? { extractions } : {}),
+        ...(lookups !== undefined ? { lookups } : {}),
+    };
     const content = format === 'json' ? buildJsonBundle(issue, meta).canonical : buildMarkdownBundle(issue, meta);
     const result = {
         kind: 'result',