redmine-context 1.0.0

package/dist/bundle/json.js

@@ -0,0 +1,266 @@
+/**
+ * Bundle JSON determinístico de uma issue normalizada (issue #15, ADR-005).
+ *
+ * Converte uma {@link Issue} do contrato num corpo canônico byte-idêntico entre
+ * execuções do mesmo estado, próprio para consumo por LLMs. Três invariantes:
+ *
+ * 1. Determinismo: coleções recebem ordenação estável DECLARADA (journals por
+ *    `(created_on, id)`; attachments/relations/custom_fields/children por `id`) e
+ *    as chaves de objeto são ordenadas pelo serializador ({@link stableStringify}).
+ * 2. `generated_at` FORA do corpo canônico: vive no envelope separado, para que
+ *    dois bundles do mesmo estado sejam idênticos. O chamador (CLI, #17) decide
+ *    como unir corpo e envelope.
+ * 3. Anti prompt-injection: conteúdo textual derivado do Redmine (descrição, notas
+ *    de journal, valores de custom field) é marcado `untrusted: true` (ADR-005).
+ *
+ * Follow-up da review da #11: refs degradadas — o `NULL_REF` congelado do
+ * normalize, com `id === 0` — NÃO são renderizadas como valores válidos; emitem
+ * `null` explícito, evitando que um placeholder vaze como referência real.
+ */
+import { stableStringify } from './stable-stringify.js';
+/** Versão do schema do bundle — congelada em "1.0" para esta major. */
+const SCHEMA_VERSION = '1.0';
+/** Envolve um conteúdo não-confiável do Redmine com a marca `untrusted: true`. */
+function untrusted(value) {
+    return { untrusted: true, value };
+}
+/**
+ * Renderiza uma ref obrigatória do contrato.
+ *
+ * Refs degradadas (`id === 0`, o `NULL_REF` do normalize) viram `null` — nunca
+ * são emitidas como `{ id: 0, name: '' }`, que aparentaria uma referência válida.
+ *
+ * @param ref - Ref do contrato (possivelmente o placeholder degradado).
+ * @returns `{ id, name }` para refs reais; `null` para o placeholder.
+ */
+function renderRef(ref) {
+    if (ref.id === 0)
+        return null;
+    return { id: ref.id, name: ref.name };
+}
+/** Renderiza uma ref opcional; ausência vira `null` (mesmo canal que degradação). */
+function renderOptionalRef(ref) {
+    return ref === undefined ? null : renderRef(ref);
+}
+/** Detalhe bruto de journal — histórico estruturado, repassado sem interpretação. */
+function renderDetail(detail) {
+    const out = {
+        property: detail.property,
+        // `name` fica estrutural: vocabulário fixo em property=attr e id em
+        // property=cf — é chave programática do status history.
+        name: detail.name,
+    };
+    // old/new_value carregam texto derivado (ex.: descrição inteira em
+    // details de "description") — mesma categoria de confiança de notes.
+    if ('old_value' in detail) {
+        out.old_value = detail.old_value === null || detail.old_value === undefined ? null : untrusted(detail.old_value);
+    }
+    if ('new_value' in detail) {
+        out.new_value = detail.new_value === null || detail.new_value === undefined ? null : untrusted(detail.new_value);
+    }
+    return out;
+}
+/** Renderiza um journal; a nota livre (se houver) é marcada `untrusted`. */
+function renderJournal(journal) {
+    const out = {
+        id: journal.id,
+        created_on: journal.created_on,
+        user: renderOptionalRef(journal.user),
+        details: journal.details.map(renderDetail),
+    };
+    if (journal.notes !== undefined)
+        out.notes = untrusted(journal.notes);
+    return out;
+}
+/** Renderiza um custom field; o `value` (texto do Redmine) é marcado `untrusted`. */
+function renderCustomField(field) {
+    const out = {
+        id: field.id,
+        name: field.name,
+        value: untrusted(field.value),
+        raw_value: field.raw_value,
+    };
+    if (field.field_format !== undefined)
+        out.field_format = field.field_format;
+    return out;
+}
+/**
+ * Renderiza um artefato derivado da extração (M4-08) — ex.: o keyframe de vídeo.
+ * Emite APENAS a REFERÊNCIA (tipo + caminho no cache + mime); o binário NUNCA é
+ * embutido (ADR-002: o MCP é read-only e textual). O `path`/`kind`/`mime` são dados
+ * NOSSOS (não derivados do Redmine), logo sem marcação `untrusted`.
+ *
+ * @param artifact - Artefato produzido pela extração.
+ * @returns Objeto JSON `{ kind, path, mime? }`.
+ */
+function renderArtifact(artifact) {
+    const out = { kind: artifact.kind, path: artifact.path };
+    if (artifact.mime !== undefined)
+        out.mime = artifact.mime;
+    return out;
+}
+/**
+ * Renderiza o resultado da extração de um anexo (M3-10). `status` sempre presente;
+ * `text` só quando há texto, marcado `untrusted` (conteúdo derivado do anexo);
+ * `reason` só quando o resultado (skip/falha/unsupported) o carrega em metadata;
+ * `artifacts` (M4-08) referencia derivados no cache (ex.: keyframe), sem embutir.
+ *
+ * @param result - Resultado de uma extração de anexo.
+ * @returns Objeto JSON `{ status, text?, reason?, hint?, artifacts? }`.
+ */
+function renderExtraction(result) {
+    const out = { status: result.status };
+    if (typeof result.text === 'string' && result.text !== '') {
+        out.text = untrusted(result.text);
+    }
+    const reason = result.metadata?.['reason'];
+    if (typeof reason === 'string')
+        out.reason = reason;
+    // Paridade com o MD (review #141): o hint (texto NOSSO, ex.: instrução de
+    // instalação) é a parte acionável para o consumidor do JSON (MCP/LLM).
+    const hint = result.metadata?.['hint'];
+    if (typeof hint === 'string')
+        out.hint = hint;
+    if (result.artifacts !== undefined && result.artifacts.length > 0) {
+        out.artifacts = result.artifacts.map(renderArtifact);
+    }
+    return out;
+}
+/** Renderiza um anexo (metadados; conteúdo binário é extraído fora do bundle). */
+function renderAttachment(att, extractions) {
+    const out = {
+        id: att.id,
+        filename: att.filename,
+        filesize: att.filesize,
+        created_on: att.created_on,
+        content_url: att.content_url,
+    };
+    if (att.content_type !== undefined)
+        out.content_type = att.content_type;
+    if (att.description !== undefined)
+        out.description = untrusted(att.description);
+    if (att.author !== undefined)
+        out.author = renderOptionalRef(att.author);
+    if (att.digest !== undefined)
+        out.digest = att.digest;
+    const extraction = extractions?.get(att.id);
+    if (extraction !== undefined)
+        out.extraction = renderExtraction(extraction);
+    return out;
+}
+/** Renderiza uma relação entre issues. */
+function renderRelation(rel) {
+    return {
+        id: rel.id,
+        issue_id: rel.issue_id,
+        issue_to_id: rel.issue_to_id,
+        relation_type: rel.relation_type,
+        delay: rel.delay ?? null,
+    };
+}
+/** Renderiza uma issue-filha. */
+function renderChild(child) {
+    const out = { id: child.id };
+    if (child.tracker !== undefined)
+        out.tracker = renderOptionalRef(child.tracker);
+    if (child.subject !== undefined)
+        out.subject = untrusted(child.subject);
+    return out;
+}
+/**
+ * Comparador estável de journals: `created_on` e, em empate, `id`.
+ *
+ * Exportado para que o bundle Markdown (#16) reutilize EXATAMENTE a mesma
+ * ordenação cronológica do JSON, sem duplicar a regra de desempate.
+ */
+export function compareJournals(a, b) {
+    if (a.created_on < b.created_on)
+        return -1;
+    if (a.created_on > b.created_on)
+        return 1;
+    return a.id - b.id;
+}
+/**
+ * Ordena por `id` sem mutar o array de entrada.
+ *
+ * Exportado para reuso pelo bundle Markdown (#16): attachments, relations,
+ * custom_fields e children compartilham a MESMA ordenação estável do JSON.
+ */
+export function byId(items) {
+    return [...items].sort((a, b) => a.id - b.id);
+}
+/**
+ * Monta o corpo da issue já ordenado e com marcações `untrusted`.
+ *
+ * @param issue - Issue normalizada do contrato.
+ * @param extractions - Extrações por anexo (M3-10); `undefined` = sem extração.
+ * @returns Objeto JSON pronto para serialização estável.
+ */
+function renderIssue(issue, extractions) {
+    const out = {
+        id: issue.id,
+        subject: untrusted(issue.subject),
+        description: issue.description === undefined ? null : untrusted(issue.description),
+        project: renderRef(issue.project),
+        tracker: renderRef(issue.tracker),
+        status: renderRef(issue.status),
+        priority: renderRef(issue.priority),
+        author: renderRef(issue.author),
+        created_on: issue.created_on,
+        updated_on: issue.updated_on,
+        custom_fields: byId(issue.custom_fields).map(renderCustomField),
+        journals: [...issue.journals].sort(compareJournals).map(renderJournal),
+        attachments: byId(issue.attachments).map((att) => renderAttachment(att, extractions)),
+        relations: byId(issue.relations).map(renderRelation),
+        children: byId(issue.children).map(renderChild),
+    };
+    if (issue.assigned_to !== undefined)
+        out.assigned_to = renderOptionalRef(issue.assigned_to);
+    if (issue.done_ratio !== undefined)
+        out.done_ratio = issue.done_ratio;
+    if (issue.start_date !== undefined)
+        out.start_date = issue.start_date;
+    if (issue.due_date !== undefined)
+        out.due_date = issue.due_date;
+    if (issue.parent !== undefined)
+        out.parent = { id: issue.parent.id };
+    if (issue.watchers !== undefined)
+        out.watchers = byId(issue.watchers).map(renderRef);
+    return out;
+}
+/**
+ * Empacota uma issue normalizada num bundle JSON determinístico.
+ *
+ * O corpo canônico é byte-idêntico entre execuções do mesmo estado (ordenação
+ * estável + serializador de chaves ordenadas). `generated_at` fica no envelope,
+ * fora do corpo, preservando essa propriedade.
+ *
+ * @param issue - Issue normalizada (ver `src/normalize`).
+ * @param meta - Metadados do empacotamento (base URL, versão, timestamp opcional).
+ * @returns Corpo canônico serializado e envelope com `generated_at` + `source`.
+ * @example
+ * const { canonical, envelope } = buildJsonBundle(issue, {
+ *   baseUrl: 'https://redmine.example',
+ *   toolVersion: TOOL_VERSION,
+ * });
+ */
+export function buildJsonBundle(issue, meta) {
+    const source = {
+        base_url: meta.baseUrl,
+        issue_id: issue.id,
+        issue_updated_on: issue.updated_on,
+    };
+    const body = {
+        schema_version: SCHEMA_VERSION,
+        tool_version: meta.toolVersion,
+        source: { ...source },
+        issue: renderIssue(issue, meta.extractions),
+    };
+    return {
+        canonical: stableStringify(body),
+        envelope: {
+            generated_at: meta.generatedAt ?? new Date().toISOString(),
+            source,
+        },
+    };
+}

package/dist/bundle/markdown.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Bundle Markdown determinístico de uma issue normalizada (issue #16, ADR-005).
+ *
+ * Renderiza uma {@link Issue} num documento Markdown legível por humanos e por
+ * LLMs, mantendo as MESMAS invariantes do bundle JSON (#15):
+ *
+ * 1. Determinismo: coleções recebem a ordenação estável DECLARADA — reutilizada
+ *    de `./json.ts` ({@link compareJournals}, {@link byId}) sem duplicar a regra.
+ *    Dois bundles do mesmo estado são byte-idênticos; não há `generated_at` no
+ *    corpo (o timestamp vive apenas no envelope do JSON, #15).
+ * 2. Anti prompt-injection: TODO conteúdo textual derivado do Redmine (subject,
+ *    descrição, notas de journal, valores de custom field, nomes e descrições de
+ *    anexo, subjects de filhos) é isolado dentro de fences
+ *    `<untrusted-content>...</untrusted-content>`. Este é EXATAMENTE o conjunto
+ *    marcado `untrusted: true` no JSON, acrescido do nome do anexo (M1-10).
+ *    Metadados estruturais (ids, datas, nomes de campos padrão, URLs) ficam fora.
+ * 3. Refs degradadas: o `NULL_REF` do normalize (`id === 0`) é renderizado como
+ *    "(desconhecido)" — nunca como um nome vazio silencioso.
+ *
+ * No M1 os anexos são texto-only: referenciados pela URL de download do Redmine,
+ * sem baixar o binário.
+ */
+import type { Issue } from '../contract.js';
+import { type ExtractionMap } from './json.js';
+/** Metadados de empacotamento do bundle Markdown (sem timestamp — determinismo). */
+export interface MarkdownBundleMeta {
+    /** Base URL do Redmine de origem — compõe as URLs de download dos anexos. */
+    baseUrl: string;
+    /** Versão da ferramenta (`TOOL_VERSION`), registrada no rodapé de proveniência. */
+    toolVersion: string;
+    /**
+     * Extrações de anexos (M3-10). Quando presente, cada anexo com resultado ganha
+     * a seção "Texto extraído" — o texto de OCR dentro de `<untrusted-content>`.
+     */
+    extractions?: ExtractionMap;
+}
+/**
+ * Isola conteúdo não confiável num bloco `<untrusted-content>` de várias linhas.
+ *
+ * Exportada para reutilização por outras superfícies do core (ex.: a tool MCP
+ * `get_attachment_text`, M3-13) que devolvem texto multi-linha derivado do
+ * Redmine e precisam da MESMA marcação anti prompt-injection, sem duplicá-la.
+ *
+ * @param text - Conteúdo derivado do Redmine.
+ * @returns Bloco fence pronto para inserção como seção.
+ */
+export declare function fenceBlock(text: string): string;
+/**
+ * Isola conteúdo não confiável numa fence inline (uma linha).
+ *
+ * Exportada para ser reutilizada por outros renderizadores do bundle (ex.: a
+ * lista compacta de resultados de busca, M1-13) sem duplicar a marcação
+ * anti prompt-injection.
+ *
+ * @param text - Conteúdo derivado do Redmine.
+ * @returns Fence inline `<untrusted-content>...</untrusted-content>`.
+ */
+export declare function fenceInline(text: string): string;
+/**
+ * Empacota uma issue normalizada num documento Markdown determinístico.
+ *
+ * O corpo é byte-idêntico entre execuções do mesmo estado (ordenação estável
+ * reutilizada do JSON + ausência de `generated_at`). Todo conteúdo textual
+ * derivado do Redmine é isolado em fences `<untrusted-content>`.
+ *
+ * @param issue - Issue normalizada (ver `src/normalize`).
+ * @param meta - Base URL do Redmine e versão da ferramenta.
+ * @returns Documento Markdown completo, terminado por uma quebra de linha.
+ * @example
+ * const md = buildMarkdownBundle(issue, {
+ *   baseUrl: 'https://redmine.example',
+ *   toolVersion: TOOL_VERSION,
+ * });
+ */
+export declare function buildMarkdownBundle(issue: Issue, meta: MarkdownBundleMeta): string;

package/dist/bundle/markdown.js

@@ -0,0 +1,294 @@
+/**
+ * Bundle Markdown determinístico de uma issue normalizada (issue #16, ADR-005).
+ *
+ * Renderiza uma {@link Issue} num documento Markdown legível por humanos e por
+ * LLMs, mantendo as MESMAS invariantes do bundle JSON (#15):
+ *
+ * 1. Determinismo: coleções recebem a ordenação estável DECLARADA — reutilizada
+ *    de `./json.ts` ({@link compareJournals}, {@link byId}) sem duplicar a regra.
+ *    Dois bundles do mesmo estado são byte-idênticos; não há `generated_at` no
+ *    corpo (o timestamp vive apenas no envelope do JSON, #15).
+ * 2. Anti prompt-injection: TODO conteúdo textual derivado do Redmine (subject,
+ *    descrição, notas de journal, valores de custom field, nomes e descrições de
+ *    anexo, subjects de filhos) é isolado dentro de fences
+ *    `<untrusted-content>...</untrusted-content>`. Este é EXATAMENTE o conjunto
+ *    marcado `untrusted: true` no JSON, acrescido do nome do anexo (M1-10).
+ *    Metadados estruturais (ids, datas, nomes de campos padrão, URLs) ficam fora.
+ * 3. Refs degradadas: o `NULL_REF` do normalize (`id === 0`) é renderizado como
+ *    "(desconhecido)" — nunca como um nome vazio silencioso.
+ *
+ * No M1 os anexos são texto-only: referenciados pela URL de download do Redmine,
+ * sem baixar o binário.
+ */
+import { byId, compareJournals } from './json.js';
+/** Placeholder para ref degradada (id 0) — nunca um nome vazio silencioso. */
+const UNKNOWN_REF = '(desconhecido)';
+/** Placeholder para ref opcional ausente (distinto de degradada). */
+const ABSENT_REF = '(nenhum)';
+/**
+ * Neutraliza tentativas de fuga da fence embutidas no conteúdo não confiável.
+ *
+ * Reason: um valor do Redmine pode conter literalmente `</untrusted-content>`
+ * para "fechar" a fence e injetar instruções fora dela. Inserimos um espaço de
+ * largura zero após o `<` de qualquer tag de fence, preservando o texto visível
+ * mas quebrando o token — de forma determinística.
+ *
+ * @param text - Conteúdo bruto derivado do Redmine.
+ * @returns Texto com tokens de fence defangados.
+ */
+function neutralizeFence(text) {
+    // Tolerante a espaços internos: "< /untrusted-content >" também fecharia o
+    // fence aos olhos de um LLM — normaliza qualquer variante.
+    return text.replace(/<\s*(\/?)\s*untrusted-content\s*>/gi, '<​$1untrusted-content>');
+}
+/**
+ * Isola conteúdo não confiável num bloco `<untrusted-content>` de várias linhas.
+ *
+ * Exportada para reutilização por outras superfícies do core (ex.: a tool MCP
+ * `get_attachment_text`, M3-13) que devolvem texto multi-linha derivado do
+ * Redmine e precisam da MESMA marcação anti prompt-injection, sem duplicá-la.
+ *
+ * @param text - Conteúdo derivado do Redmine.
+ * @returns Bloco fence pronto para inserção como seção.
+ */
+export function fenceBlock(text) {
+    return `<untrusted-content>\n${neutralizeFence(text)}\n</untrusted-content>`;
+}
+/**
+ * Isola conteúdo não confiável numa fence inline (uma linha).
+ *
+ * Exportada para ser reutilizada por outros renderizadores do bundle (ex.: a
+ * lista compacta de resultados de busca, M1-13) sem duplicar a marcação
+ * anti prompt-injection.
+ *
+ * @param text - Conteúdo derivado do Redmine.
+ * @returns Fence inline `<untrusted-content>...</untrusted-content>`.
+ */
+export function fenceInline(text) {
+    return `<untrusted-content>${neutralizeFence(text)}</untrusted-content>`;
+}
+/**
+ * Nome legível de uma ref obrigatória, tratando degradação.
+ *
+ * @param ref - Ref do contrato (possivelmente o placeholder `id === 0`).
+ * @returns Nome real ou "(desconhecido)" para o placeholder degradado.
+ */
+function refName(ref) {
+    return ref.id === 0 ? UNKNOWN_REF : ref.name;
+}
+/** Nome de uma ref opcional; ausência → "(nenhum)", degradada → "(desconhecido)". */
+function optionalRefName(ref) {
+    return ref === undefined ? ABSENT_REF : refName(ref);
+}
+/** Achata o valor de um custom field (multi-valor → lista separada por vírgula). */
+function customFieldText(value) {
+    if (value === null)
+        return null;
+    return Array.isArray(value) ? value.join(', ') : value;
+}
+/** Cabeçalho + assunto (fenced) + metadados estruturais da issue. */
+function renderHeader(issue) {
+    const lines = [`# Issue #${issue.id}`, '', '## Assunto', '', fenceBlock(issue.subject), ''];
+    lines.push('## Metadados', '');
+    lines.push(`- **Projeto:** ${refName(issue.project)}`);
+    lines.push(`- **Tracker:** ${refName(issue.tracker)}`);
+    lines.push(`- **Status:** ${refName(issue.status)}`);
+    lines.push(`- **Prioridade:** ${refName(issue.priority)}`);
+    lines.push(`- **Autor:** ${refName(issue.author)}`);
+    lines.push(`- **Responsável:** ${optionalRefName(issue.assigned_to)}`);
+    lines.push(`- **Criada em:** ${issue.created_on}`);
+    lines.push(`- **Atualizada em:** ${issue.updated_on}`);
+    if (issue.done_ratio !== undefined)
+        lines.push(`- **Progresso:** ${issue.done_ratio}%`);
+    if (issue.start_date !== undefined)
+        lines.push(`- **Início:** ${issue.start_date}`);
+    if (issue.due_date !== undefined)
+        lines.push(`- **Prazo:** ${issue.due_date}`);
+    return lines.join('\n');
+}
+/** Seção de descrição (fenced) — placeholder estrutural quando ausente. */
+function renderDescription(issue) {
+    const body = issue.description === undefined ? '_(sem descrição)_' : fenceBlock(issue.description);
+    return `## Descrição\n\n${body}`;
+}
+/** Seção de custom fields — nome do campo (metadado) + valor (fenced). */
+function renderCustomFields(issue) {
+    if (issue.custom_fields.length === 0)
+        return '## Custom Fields\n\n_(nenhum)_';
+    const rows = byId(issue.custom_fields).map((field) => {
+        const text = customFieldText(field.value);
+        const value = text === null ? '_(vazio)_' : fenceInline(text);
+        // O nome do custom field é definido pelo admin da instância — derivado.
+        return `- **${fenceInline(field.name)}:** ${value}`;
+    });
+    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.
+ */
+function renderJournalDetails(journal) {
+    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}`;
+    });
+}
+/** Renderiza uma entrada de journal: cabeçalho estrutural + nota (fenced). */
+function renderJournal(journal) {
+    const lines = [`### Journal #${journal.id} — ${journal.created_on} — ${optionalRefName(journal.user)}`, ''];
+    const details = renderJournalDetails(journal);
+    if (details.length > 0)
+        lines.push('Alterações:', ...details, '');
+    if (journal.notes !== undefined)
+        lines.push('Nota:', fenceBlock(journal.notes), '');
+    if (details.length === 0 && journal.notes === undefined)
+        lines.push('_(sem alterações ou notas)_', '');
+    return lines.join('\n').trimEnd();
+}
+/** Seção de histórico — journals em ordem cronológica estável (created_on, id). */
+function renderJournals(issue) {
+    if (issue.journals.length === 0)
+        return '## Histórico\n\n_(nenhum)_';
+    const ordered = [...issue.journals].sort(compareJournals).map(renderJournal);
+    return ['## Histórico', ...ordered].join('\n\n');
+}
+/** Seção de relações — tipo + issue alvo (tudo estrutural). */
+function renderRelations(issue) {
+    if (issue.relations.length === 0)
+        return '## Relações\n\n_(nenhuma)_';
+    const rows = byId(issue.relations).map((rel) => {
+        const delay = rel.delay === undefined || rel.delay === null ? '' : ` (atraso: ${rel.delay}d)`;
+        return `- **${rel.relation_type}** → issue #${rel.issue_to_id}${delay}`;
+    });
+    return ['## Relações', '', ...rows].join('\n');
+}
+/** Seção do pai — referência estrutural por número de issue. */
+function renderParent(issue) {
+    const body = issue.parent === undefined ? '_(nenhuma)_' : `- issue #${issue.parent.id}`;
+    return `## Issue Pai\n\n${body}`;
+}
+/** Renderiza uma issue-filha: id/tracker estruturais + subject (fenced). */
+function renderChild(child) {
+    const tracker = child.tracker === undefined ? '' : ` [${refName(child.tracker)}]`;
+    const subject = child.subject === undefined ? '' : ` ${fenceInline(child.subject)}`;
+    return `- issue #${child.id}${tracker}${subject}`;
+}
+/** Seção de sub-issues — filhos ordenados por id. */
+function renderChildren(issue) {
+    if (issue.children.length === 0)
+        return '## Sub-issues\n\n_(nenhuma)_';
+    const rows = byId(issue.children).map(renderChild);
+    return ['## Sub-issues', '', ...rows].join('\n');
+}
+/**
+ * Renderiza as linhas de "Artefatos" de uma extração (M4-08) — ex.: o keyframe de
+ * vídeo. Emite só a REFERÊNCIA (tipo + caminho no cache local); o binário NUNCA é
+ * embutido (ADR-002). O caminho é dado NOSSO (deriva de id/digest hex do anexo),
+ * portanto fora de `<untrusted-content>`. A URL do Redmine do anexo já consta no
+ * bloco do anexo (linha "URL"), completando a referência path-de-cache + URL.
+ *
+ * @param artifacts - Artefatos derivados da extração.
+ * @returns Linhas Markdown a concatenar ao bloco do anexo (vazio se não houver).
+ */
+function renderArtifacts(artifacts) {
+    if (artifacts === undefined || artifacts.length === 0)
+        return [];
+    const lines = ['  - Artefatos:'];
+    for (const art of artifacts) {
+        const mime = art.mime === undefined ? '' : ` (${art.mime})`;
+        lines.push(`    - ${art.kind}: ${art.path}${mime}`);
+    }
+    return lines;
+}
+/**
+ * Renderiza a seção "Texto extraído" de um anexo (M3-10). O texto de OCR é
+ * conteúdo DERIVADO do anexo, logo isolado dentro de `<untrusted-content>`. Quando
+ * não há texto (skip/falha/unsupported), mostra `status` + `reason`/`hint` — assim
+ * o bundle continua saindo e, no caso de tesseract ausente, DIZ como instalar.
+ * Artefatos derivados (keyframe, M4-08) são REFERENCIADOS ao final, sem embutir.
+ *
+ * @param result - Resultado da extração do anexo.
+ * @returns Linhas Markdown da seção (para concatenar ao bloco do anexo).
+ */
+function renderExtraction(result) {
+    const artifacts = renderArtifacts(result.artifacts);
+    if (typeof result.text === 'string' && result.text.trim() !== '') {
+        return [`  - Texto extraído (${result.status}):`, fenceBlock(result.text), ...artifacts];
+    }
+    const lines = [`  - Texto extraído (${result.status}):`];
+    const reason = result.metadata?.['reason'];
+    const hint = result.metadata?.['hint'];
+    if (typeof reason === 'string')
+        lines.push(`    - Motivo: ${reason}`);
+    // `hint` é texto NOSSO (não do Redmine) — ex.: instruções de instalação; fica
+    // fora da fence untrusted por ser confiável.
+    if (typeof hint === 'string')
+        lines.push(`    - ${hint}`);
+    if (typeof reason !== 'string' && typeof hint !== 'string' && artifacts.length === 0) {
+        lines.push('    - _(sem texto)_');
+    }
+    return [...lines, ...artifacts];
+}
+/**
+ * Renderiza um anexo: metadados estruturais + URL de download do Redmine.
+ *
+ * O nome e a descrição (conteúdo derivado) vão em fence; a URL usa o filename
+ * percent-encoded como componente de caminho, mantendo-a válida e imune a fuga.
+ * Quando há extração (M3-10), acrescenta a seção "Texto extraído".
+ *
+ * @param att - Anexo normalizado.
+ * @param baseUrl - Base URL do Redmine.
+ * @param extractions - Extrações por anexo; `undefined` = sem extração.
+ * @returns Bloco Markdown do anexo.
+ */
+function renderAttachment(att, baseUrl, extractions) {
+    const url = `${baseUrl}/attachments/download/${att.id}/${encodeURIComponent(att.filename)}`;
+    const lines = [`- **Anexo #${att.id}** — ${att.filesize} bytes`];
+    lines.push(`  - Nome: ${fenceInline(att.filename)}`);
+    lines.push(`  - URL: ${url}`);
+    if (att.description !== undefined)
+        lines.push(`  - Descrição: ${fenceInline(att.description)}`);
+    const extraction = extractions?.get(att.id);
+    if (extraction !== undefined)
+        lines.push(...renderExtraction(extraction));
+    return lines.join('\n');
+}
+/** Seção de anexos — referenciados por URL do Redmine, ordenados por id. */
+function renderAttachments(issue, baseUrl, extractions) {
+    if (issue.attachments.length === 0)
+        return '## Anexos\n\n_(nenhum)_';
+    const rows = byId(issue.attachments).map((att) => renderAttachment(att, baseUrl, extractions));
+    return ['## Anexos', '', ...rows].join('\n');
+}
+/**
+ * Empacota uma issue normalizada num documento Markdown determinístico.
+ *
+ * O corpo é byte-idêntico entre execuções do mesmo estado (ordenação estável
+ * reutilizada do JSON + ausência de `generated_at`). Todo conteúdo textual
+ * derivado do Redmine é isolado em fences `<untrusted-content>`.
+ *
+ * @param issue - Issue normalizada (ver `src/normalize`).
+ * @param meta - Base URL do Redmine e versão da ferramenta.
+ * @returns Documento Markdown completo, terminado por uma quebra de linha.
+ * @example
+ * const md = buildMarkdownBundle(issue, {
+ *   baseUrl: 'https://redmine.example',
+ *   toolVersion: TOOL_VERSION,
+ * });
+ */
+export function buildMarkdownBundle(issue, meta) {
+    const sections = [
+        renderHeader(issue),
+        renderDescription(issue),
+        renderCustomFields(issue),
+        renderJournals(issue),
+        renderRelations(issue),
+        renderParent(issue),
+        renderChildren(issue),
+        renderAttachments(issue, meta.baseUrl, meta.extractions),
+        `---\n\n_Empacotado por redmine-context v${meta.toolVersion}._`,
+    ];
+    return `${sections.join('\n\n')}\n`;
+}

package/dist/bundle/search-list.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Lista compacta em Markdown dos resultados da tool `search_issues` (M1-13).
+ *
+ * Diferente do bundle completo de uma issue (#16), aqui cada item é UMA linha:
+ * id + status + responsável (metadados estruturais, fora da fence) e o assunto
+ * isolado numa fence `<untrusted-content>` — reutilizando {@link fenceInline}
+ * para manter a MESMA marcação anti prompt-injection do bundle.
+ *
+ * Determinístico: nenhum timestamp; a ordem é a recebida do chamador (que já
+ * reflete a ordenação do Redmine). Avisos de degradação (ex.: `/search`
+ * indisponível) são renderizados no corpo, atendendo ao "aviso no payload".
+ */
+/** Item compacto de um resultado de busca (status/responsável já resolvidos). */
+export interface SearchListItem {
+    /** Id da issue. */
+    id: number;
+    /** Assunto derivado do Redmine — renderizado dentro da fence untrusted. */
+    subject: string | null;
+    /** Nome do status (metadado estrutural). */
+    status: string;
+    /** Nome do responsável, ou placeholder de ausência (metadado estrutural). */
+    assignee: string;
+}
+/** Metadados de renderização da lista: consulta e avisos de degradação. */
+export interface SearchListMeta {
+    /** Termo full-text usado (renderizado em fence por ser entrada arbitrária). */
+    query?: string | undefined;
+    /** Avisos a exibir no corpo (ex.: degradação da busca full-text). */
+    warnings?: string[] | undefined;
+}
+/**
+ * Renderiza a lista compacta de resultados de busca em Markdown.
+ *
+ * @param items - Itens já resolvidos (status/responsável em nomes legíveis).
+ * @param meta - Consulta e avisos de degradação (ver {@link SearchListMeta}).
+ * @returns Documento Markdown terminado por uma quebra de linha.
+ * @example
+ * const md = buildSearchListMarkdown(
+ *   [{ id: 1, subject: 'x', status: 'New', assignee: '(nenhum)' }],
+ *   { query: 'x' },
+ * );
+ */
+export declare function buildSearchListMarkdown(items: SearchListItem[], meta?: SearchListMeta): string;