redmine-context 1.0.0

package/dist/fetch-attachment-text.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Orquestração get → normalize → extração de UM anexo (M3-13, ADR-002/ADR-005).
+ *
+ * Função fina do core que a superfície MCP (#55) reutiliza pela tool read-only
+ * `get_attachment_text`: recebe credenciais já resolvidas + `issueId`/`attachmentId`
+ * e devolve o {@link ExtractionResult} do anexo pedido, passando pelo MESMO
+ * pipeline com cache de {@link extractIssueAttachments} (`getOrCompute` garante o
+ * cache-hit quando o texto já foi extraído — a #55 não re-baixa nem re-roda o OCR).
+ *
+ * Só o anexo pedido entra no pipeline (a issue é filtrada a um único anexo), então
+ * o download/extração caro roda no máximo uma vez por chamada. Mantém a fronteira
+ * do ADR-005: encapsula `client`, `normalize`, `extract` e `cache`.
+ */
+import { type BackgroundExtractor } from './cache-first.js';
+import { type CacheStore } from './cache/index.js';
+import { type Logger } from './client/index.js';
+import type { ExtractionResult } from './contract.js';
+import { type ExtractorRegistry } from './extract/index.js';
+/**
+ * Erro tipado: o anexo pedido não existe na issue (após o fetch bem-sucedido da
+ * issue). Distinto de um 404 do Redmine (que é a issue inexistente) — as
+ * superfícies o mapeiam para uma mensagem clara, sem cache indevido.
+ */
+export declare class AttachmentNotFoundError extends Error {
+    /** Id da issue consultada. */
+    readonly issueId: number;
+    /** Id do anexo ausente. */
+    readonly attachmentId: number;
+    /**
+     * @param issueId - Id da issue consultada.
+     * @param attachmentId - Id do anexo que não foi encontrado.
+     */
+    constructor(issueId: number, attachmentId: number);
+}
+/** Opções de {@link fetchAttachmentText}: credenciais resolvidas + alvos. */
+export interface FetchAttachmentTextOptions {
+    /** URL base da instância Redmine (ex.: `https://redmine.example`). */
+    baseUrl: string;
+    /** api_key já resolvida pela cascata da superfície. */
+    apiKey: string;
+    /** Identificador da issue que contém o anexo. */
+    issueId: number;
+    /** Identificador do anexo cujo texto será extraído. */
+    attachmentId: number;
+    /** Permite `http://` (sem TLS) com aviso ruidoso. Default: `false`. */
+    insecure?: boolean;
+    /** Raiz do cache em disco para downloads/extrações. Default do {@link DiskCacheStore}. */
+    cacheDir?: string;
+}
+/** Resultado de {@link fetchAttachmentText}: o anexo + sua extração. */
+export interface AttachmentTextResult {
+    /** Id do anexo processado. */
+    attachmentId: number;
+    /** Resultado da extração (status + texto/metadata) — ver {@link ExtractionResult}. */
+    extraction: ExtractionResult;
+}
+/**
+ * Busca a issue, isola o anexo pedido e extrai seu texto pelo pipeline com cache.
+ *
+ * @param options - Ver {@link FetchAttachmentTextOptions}.
+ * @returns O {@link AttachmentTextResult} do anexo (texto quando `done`/`text`;
+ *   caso contrário `skipped`/`unsupported`/`failed` com motivo/dica).
+ * @throws {RedmineAuthError} Em 401 (propagado do client).
+ * @throws {RedmineForbiddenError} Em 403 — sem permissão para a issue.
+ * @throws {RedmineNotFoundError} Em 404 — issue inexistente.
+ * @throws {AttachmentNotFoundError} Quando o anexo não existe na issue.
+ * @example
+ * const { extraction } = await fetchAttachmentText({
+ *   baseUrl, apiKey, issueId: 42, attachmentId: 77,
+ * });
+ */
+export declare function fetchAttachmentText(options: FetchAttachmentTextOptions): Promise<AttachmentTextResult>;
+/**
+ * Opções de {@link fetchAttachmentTextCacheFirst}: as de {@link fetchAttachmentText}
+ * mais seams INJETÁVEIS (registry/store/background/logger) com defaults reais —
+ * usados pelos testes para simular a extração lenta de forma determinística, sem
+ * tocar a rede/disco/subprocesso reais.
+ */
+export interface FetchAttachmentTextCacheFirstOptions extends FetchAttachmentTextOptions {
+    /** Registry de extratores; default: {@link createDefaultRegistry}. */
+    registry?: ExtractorRegistry;
+    /** Store attachment-level; default: {@link DiskCacheStore} sobre `cacheDir`. */
+    store?: CacheStore<ExtractionResult>;
+    /**
+     * Dispatcher do job em background (#71); default: fila (`runQueue`) que roda a
+     * extração real detached. Injetável para provar o não-bloqueio (< 5s) sem esperar.
+     */
+    background?: BackgroundExtractor;
+    /** Logger para avisos; default no-op. Nunca `console.*`. */
+    logger?: Logger;
+}
+/**
+ * Variante CACHE-FIRST e NÃO-BLOQUEANTE de {@link fetchAttachmentText} (M4-11, #70).
+ *
+ * Busca a issue (rápido), isola o anexo pedido e LÊ o cache: se a extração já está
+ * pronta, devolve o texto IMEDIATAMENTE; se ainda não (anexo pesado), devolve
+ * `processing` na hora — SEM aguardar a extração — e dispara o job em segundo
+ * plano pela fila (fire-and-forget, forward-compatible com a continuação #71).
+ * Nenhuma chamada bloqueia aguardando mídia.
+ *
+ * @param options - Ver {@link FetchAttachmentTextCacheFirstOptions}.
+ * @returns O {@link AttachmentTextResult} do anexo (texto pronto, `processing` ou
+ *   `unsupported`), sempre sem bloquear na extração cara.
+ * @throws {RedmineAuthError} Em 401 (propagado do client).
+ * @throws {RedmineForbiddenError} Em 403 — sem permissão para a issue.
+ * @throws {RedmineNotFoundError} Em 404 — issue inexistente.
+ * @throws {AttachmentNotFoundError} Quando o anexo não existe na issue.
+ * @example
+ * const { extraction } = await fetchAttachmentTextCacheFirst({
+ *   baseUrl, apiKey, issueId: 42, attachmentId: 77,
+ * });
+ */
+export declare function fetchAttachmentTextCacheFirst(options: FetchAttachmentTextCacheFirstOptions): Promise<AttachmentTextResult>;

package/dist/fetch-attachment-text.js

@@ -0,0 +1,155 @@
+/**
+ * Orquestração get → normalize → extração de UM anexo (M3-13, ADR-002/ADR-005).
+ *
+ * Função fina do core que a superfície MCP (#55) reutiliza pela tool read-only
+ * `get_attachment_text`: recebe credenciais já resolvidas + `issueId`/`attachmentId`
+ * e devolve o {@link ExtractionResult} do anexo pedido, passando pelo MESMO
+ * pipeline com cache de {@link extractIssueAttachments} (`getOrCompute` garante o
+ * cache-hit quando o texto já foi extraído — a #55 não re-baixa nem re-roda o OCR).
+ *
+ * Só o anexo pedido entra no pipeline (a issue é filtrada a um único anexo), então
+ * o download/extração caro roda no máximo uma vez por chamada. Mantém a fronteira
+ * do ADR-005: encapsula `client`, `normalize`, `extract` e `cache`.
+ */
+import { extractIssueAttachmentsCacheFirst, makeQueueBackgroundExtractor, processingResult, } from './cache-first.js';
+import { DiskCacheStore } from './cache/index.js';
+import { createHttpClient, getIssue } from './client/index.js';
+import { extractIssueAttachments } from './extract-issue-attachments.js';
+import { createDefaultRegistry } from './extract/index.js';
+import { normalizeIssue } from './normalize/index.js';
+/**
+ * Erro tipado: o anexo pedido não existe na issue (após o fetch bem-sucedido da
+ * issue). Distinto de um 404 do Redmine (que é a issue inexistente) — as
+ * superfícies o mapeiam para uma mensagem clara, sem cache indevido.
+ */
+export class AttachmentNotFoundError extends Error {
+    /** Id da issue consultada. */
+    issueId;
+    /** Id do anexo ausente. */
+    attachmentId;
+    /**
+     * @param issueId - Id da issue consultada.
+     * @param attachmentId - Id do anexo que não foi encontrado.
+     */
+    constructor(issueId, attachmentId) {
+        super(`Anexo #${attachmentId} não encontrado na issue #${issueId}.`);
+        this.name = 'AttachmentNotFoundError';
+        this.issueId = issueId;
+        this.attachmentId = attachmentId;
+    }
+}
+/** Extração `unsupported` para anexo cujo MIME não tem extrator local registrado. */
+function unsupportedResult() {
+    return {
+        status: 'unsupported',
+        metadata: {
+            reason: 'sem-extrator-registrado',
+            hint: 'nenhum extrator local suporta o tipo deste anexo (o OCR cobre apenas imagens)',
+        },
+    };
+}
+/**
+ * Busca a issue, isola o anexo pedido e extrai seu texto pelo pipeline com cache.
+ *
+ * @param options - Ver {@link FetchAttachmentTextOptions}.
+ * @returns O {@link AttachmentTextResult} do anexo (texto quando `done`/`text`;
+ *   caso contrário `skipped`/`unsupported`/`failed` com motivo/dica).
+ * @throws {RedmineAuthError} Em 401 (propagado do client).
+ * @throws {RedmineForbiddenError} Em 403 — sem permissão para a issue.
+ * @throws {RedmineNotFoundError} Em 404 — issue inexistente.
+ * @throws {AttachmentNotFoundError} Quando o anexo não existe na issue.
+ * @example
+ * const { extraction } = await fetchAttachmentText({
+ *   baseUrl, apiKey, issueId: 42, attachmentId: 77,
+ * });
+ */
+export async function fetchAttachmentText(options) {
+    const { baseUrl, apiKey, issueId, attachmentId, insecure = false, cacheDir } = options;
+    const http = createHttpClient({ baseUrl, apiKey, insecure });
+    const payload = await getIssue(http, issueId);
+    const issue = normalizeIssue(payload);
+    const attachment = issue.attachments.find((a) => a.id === attachmentId);
+    if (attachment === undefined) {
+        throw new AttachmentNotFoundError(issueId, attachmentId);
+    }
+    const registry = await createDefaultRegistry();
+    const store = new DiskCacheStore(cacheDir !== undefined ? { cacheDir } : {});
+    // Filtra a issue a UM anexo: o pipeline pré-filtra por extrator e só baixa/roda
+    // o extrator caro do anexo pedido. `getOrCompute` serve do cache num re-hit.
+    const single = { ...issue, attachments: [attachment] };
+    const map = await extractIssueAttachments(http, single, {
+        instanceUrl: baseUrl,
+        registry,
+        store,
+        ...(cacheDir !== undefined ? { cacheDir } : {}),
+    });
+    // Ausente no mapa = nenhum extrator para o MIME provável → unsupported legível.
+    const extraction = map.get(attachmentId) ?? unsupportedResult();
+    return { attachmentId, extraction };
+}
+/**
+ * Variante CACHE-FIRST e NÃO-BLOQUEANTE de {@link fetchAttachmentText} (M4-11, #70).
+ *
+ * Busca a issue (rápido), isola o anexo pedido e LÊ o cache: se a extração já está
+ * pronta, devolve o texto IMEDIATAMENTE; se ainda não (anexo pesado), devolve
+ * `processing` na hora — SEM aguardar a extração — e dispara o job em segundo
+ * plano pela fila (fire-and-forget, forward-compatible com a continuação #71).
+ * Nenhuma chamada bloqueia aguardando mídia.
+ *
+ * @param options - Ver {@link FetchAttachmentTextCacheFirstOptions}.
+ * @returns O {@link AttachmentTextResult} do anexo (texto pronto, `processing` ou
+ *   `unsupported`), sempre sem bloquear na extração cara.
+ * @throws {RedmineAuthError} Em 401 (propagado do client).
+ * @throws {RedmineForbiddenError} Em 403 — sem permissão para a issue.
+ * @throws {RedmineNotFoundError} Em 404 — issue inexistente.
+ * @throws {AttachmentNotFoundError} Quando o anexo não existe na issue.
+ * @example
+ * const { extraction } = await fetchAttachmentTextCacheFirst({
+ *   baseUrl, apiKey, issueId: 42, attachmentId: 77,
+ * });
+ */
+export async function fetchAttachmentTextCacheFirst(options) {
+    const { baseUrl, apiKey, issueId, attachmentId, insecure = false, cacheDir, logger } = options;
+    const http = createHttpClient({ baseUrl, apiKey, insecure });
+    const payload = await getIssue(http, issueId);
+    const issue = normalizeIssue(payload);
+    const attachment = issue.attachments.find((a) => a.id === attachmentId);
+    if (attachment === undefined) {
+        throw new AttachmentNotFoundError(issueId, attachmentId);
+    }
+    const registry = options.registry ?? (await createDefaultRegistry());
+    const store = options.store ?? new DiskCacheStore(cacheDir !== undefined ? { cacheDir } : {});
+    const single = { ...issue, attachments: [attachment] };
+    // Default: a extração cara roda em background pela fila; o compute reusa o
+    // pipeline testado `extractIssueAttachments` (mesma chave/store → o resultado
+    // fica pronto para a 2ª chamada, #71). Injetável nos testes por determinismo.
+    const background = options.background ??
+        makeQueueBackgroundExtractor(async (_target, signal) => {
+            // Repassa o `signal` da fila (#69/#73) ao pipeline: quando a fila abortar, o
+            // abort chega ao `runWithWatchdog` e MATA o ffmpeg/whisper ponta a ponta. Só
+            // inclui quando dado (exactOptionalPropertyTypes).
+            const computed = await extractIssueAttachments(http, single, {
+                instanceUrl: baseUrl,
+                registry,
+                store,
+                ...(cacheDir !== undefined ? { cacheDir } : {}),
+                ...(signal !== undefined ? { signal } : {}),
+                ...(logger !== undefined ? { logger } : {}),
+            });
+            return computed.get(attachmentId) ?? processingResult();
+        }, 
+        // Passa o `store` para o dispatcher PERSISTIR o resultado de fechamento
+        // (done/failed) sob a mesma chave lida no cache-first (#71): a 2ª chamada
+        // acerta o cache e uma falha vira `failed` — nunca `processing` eterno.
+        { store, ...(logger !== undefined ? { logger } : {}) });
+    const map = await extractIssueAttachmentsCacheFirst(single, {
+        instanceUrl: baseUrl,
+        registry,
+        store,
+        background,
+        ...(logger !== undefined ? { logger } : {}),
+    });
+    // Ausente no mapa = nenhum extrator para o MIME provável → unsupported legível.
+    const extraction = map.get(attachmentId) ?? unsupportedResult();
+    return { attachmentId, extraction };
+}

package/dist/fetch-issue-bundle.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Orquestração get → normalize → bundle de uma issue (M1-11).
+ *
+ * Função fina do core que as superfícies (CLI #17, MCP #18) reutilizam: recebe
+ * as credenciais já resolvidas + o formato desejado e devolve uma
+ * `AsyncIterable<CoreEvent<IssueBundleResult>>` — emitindo progresso incremental
+ * e finalizando com um único {@link Result} contendo o bundle serializado.
+ *
+ * Mantém a fronteira do ADR-005: encapsula os módulos internos (`client`,
+ * `normalize`, `bundle`) para que a superfície permaneça fina e desacoplada.
+ */
+import { type BackgroundExtractor } from './cache-first.js';
+import type { CoreEvent } from './contract.js';
+/** Formato de saída do bundle: Markdown (default) ou JSON canônico. */
+export type BundleFormat = 'md' | 'json';
+/** Opções de {@link fetchIssueBundle}: credenciais já resolvidas + formato. */
+export interface FetchIssueBundleOptions {
+    /** URL base da instância Redmine (ex.: `https://redmine.example`). */
+    baseUrl: string;
+    /** api_key já resolvida pela cascata da superfície. */
+    apiKey: string;
+    /** Identificador da issue a empacotar. */
+    issueId: number;
+    /** Formato de saída. Default (na superfície): `md`. */
+    format: BundleFormat;
+    /** Versão da ferramenta gravada no bundle. */
+    toolVersion: string;
+    /** Permite `http://` (sem TLS) com aviso ruidoso. Default: `false`. */
+    insecure?: boolean;
+    /**
+     * Extrai o texto dos anexos de imagem e o embute no bundle (M3-10). Default:
+     * `false` no M3 — as superfícies (CLI/MCP) ligam a flag na #55. Requer o
+     * binário `tesseract`; ausente, o anexo apenas registra `failed` com a dica de
+     * instalação (o bundle sai mesmo assim — degradação graciosa, ADR-002).
+     */
+    extractAttachments?: boolean;
+    /**
+     * Raiz do cache em disco para downloads/extrações (M3-10). Default do
+     * {@link DiskCacheStore}. Só usado quando `extractAttachments` é `true`.
+     */
+    cacheDir?: string;
+    /**
+     * Modo CACHE-FIRST não-bloqueante (M4-11, #70). Quando `true` (e
+     * `extractAttachments` `true`), NÃO computa extração no caminho da resposta:
+     * embute o texto já cacheado e marca os anexos ainda não processados como
+     * `processing`, disparando a extração em background. Default: `false`
+     * (comportamento síncrono do M3, usado pela CLI de exportação em disco).
+     */
+    cacheFirst?: boolean;
+    /**
+     * Dispatcher do job em background do modo cache-first (seam de teste). Default:
+     * fila (`runQueue`) que roda a extração real detached. Injetável para provar o
+     * não-bloqueio de forma determinística. Só usado quando `cacheFirst` é `true`.
+     */
+    background?: BackgroundExtractor;
+}
+/** Resultado final: conteúdo serializado pronto para stdout/arquivo. */
+export interface IssueBundleResult {
+    /** Id da issue empacotada (compõe o nome do arquivo em `--out`). */
+    issueId: number;
+    /** Formato efetivo do conteúdo. */
+    format: BundleFormat;
+    /** Bundle serializado (Markdown ou JSON canônico). */
+    content: string;
+}
+/**
+ * Busca, normaliza e empacota uma issue, emitindo progresso incremental.
+ *
+ * @param options - Ver {@link FetchIssueBundleOptions}.
+ * @returns Sequência de {@link ProgressEvent} terminada por um {@link Result}
+ *   com o {@link IssueBundleResult}.
+ * @throws {RedmineAuthError} Em 401 (propagado do client).
+ * @throws {RedmineNotFoundError} Em 404 — issue inexistente.
+ * @throws {RedmineHttpError} Em outros status ≥ 400.
+ * @throws {Error} Em falha de rede/TLS/JSON inválido.
+ * @example
+ * for await (const event of fetchIssueBundle(opts)) {
+ *   if (event.kind === 'result') process.stdout.write(event.value.content);
+ * }
+ */
+export declare function fetchIssueBundle(options: FetchIssueBundleOptions): AsyncIterable<CoreEvent<IssueBundleResult>>;

package/dist/fetch-issue-bundle.js

@@ -0,0 +1,93 @@
+/**
+ * Orquestração get → normalize → bundle de uma issue (M1-11).
+ *
+ * Função fina do core que as superfícies (CLI #17, MCP #18) reutilizam: recebe
+ * as credenciais já resolvidas + o formato desejado e devolve uma
+ * `AsyncIterable<CoreEvent<IssueBundleResult>>` — emitindo progresso incremental
+ * e finalizando com um único {@link Result} contendo o bundle serializado.
+ *
+ * Mantém a fronteira do ADR-005: encapsula os módulos internos (`client`,
+ * `normalize`, `bundle`) para que a superfície permaneça fina e desacoplada.
+ */
+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 { extractIssueAttachments } from './extract-issue-attachments.js';
+import { createDefaultRegistry } from './extract/index.js';
+import { normalizeIssue } from './normalize/index.js';
+/** Helper: constrói um evento de progresso tipado. */
+function progress(stage, message) {
+    return { kind: 'progress', stage, message };
+}
+/**
+ * Busca, normaliza e empacota uma issue, emitindo progresso incremental.
+ *
+ * @param options - Ver {@link FetchIssueBundleOptions}.
+ * @returns Sequência de {@link ProgressEvent} terminada por um {@link Result}
+ *   com o {@link IssueBundleResult}.
+ * @throws {RedmineAuthError} Em 401 (propagado do client).
+ * @throws {RedmineNotFoundError} Em 404 — issue inexistente.
+ * @throws {RedmineHttpError} Em outros status ≥ 400.
+ * @throws {Error} Em falha de rede/TLS/JSON inválido.
+ * @example
+ * for await (const event of fetchIssueBundle(opts)) {
+ *   if (event.kind === 'result') process.stdout.write(event.value.content);
+ * }
+ */
+export async function* fetchIssueBundle(options) {
+    const { baseUrl, apiKey, issueId, format, toolVersion, insecure = false, extractAttachments = false } = options;
+    yield progress('connect', `Conectando a ${baseUrl}`);
+    const http = createHttpClient({ baseUrl, apiKey, insecure });
+    yield progress('fetch', `Buscando issue #${issueId}`);
+    const payload = await getIssue(http, issueId);
+    yield progress('normalize', 'Normalizando issue');
+    const issue = normalizeIssue(payload);
+    let extractions;
+    if (extractAttachments) {
+        yield progress('extract', 'Extraindo texto dos anexos');
+        const registry = await createDefaultRegistry();
+        const store = new DiskCacheStore(options.cacheDir !== undefined ? { cacheDir: options.cacheDir } : {});
+        if (options.cacheFirst === true) {
+            // Cache-first (#70): lê o que está pronto e marca o resto como `processing`,
+            // sem bloquear na extração cara; a computação real corre em background.
+            const background = options.background ??
+                makeQueueBackgroundExtractor(async (target, signal) => {
+                    const single = { ...issue, attachments: [target.attachment] };
+                    // Repassa o `signal` da fila (#69/#73): o abort chega ao `runWithWatchdog`
+                    // e MATA o ffmpeg/whisper ponta a ponta. Só inclui quando dado.
+                    const computed = await extractIssueAttachments(http, single, {
+                        instanceUrl: baseUrl,
+                        registry,
+                        store,
+                        ...(options.cacheDir !== undefined ? { cacheDir: options.cacheDir } : {}),
+                        ...(signal !== undefined ? { signal } : {}),
+                    });
+                    return computed.get(target.attachment.id) ?? processingResult();
+                }, { store });
+            extractions = await extractIssueAttachmentsCacheFirst(issue, {
+                instanceUrl: baseUrl,
+                registry,
+                store,
+                background,
+            });
+        }
+        else {
+            extractions = await extractIssueAttachments(http, issue, {
+                instanceUrl: baseUrl,
+                registry,
+                store,
+                ...(options.cacheDir !== undefined ? { cacheDir: options.cacheDir } : {}),
+            });
+        }
+    }
+    yield progress('bundle', `Empacotando bundle (${format})`);
+    const meta = { baseUrl, toolVersion, ...(extractions !== undefined ? { extractions } : {}) };
+    const content = format === 'json' ? buildJsonBundle(issue, meta).canonical : buildMarkdownBundle(issue, meta);
+    const result = {
+        kind: 'result',
+        value: { issueId, format, content },
+    };
+    yield result;
+}

package/dist/fetch-issue-search.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Orquestração de busca de issues para a tool `search_issues` (M1-13).
+ *
+ * Função fina do core reutilizável pela superfície MCP (#19): recebe credenciais
+ * já resolvidas + filtros estruturados + termo full-text opcional e devolve uma
+ * lista COMPACTA em Markdown (id, assunto fenced, status, responsável) — nunca o
+ * bundle completo por item.
+ *
+ * Estratégia (best-effort no full-text):
+ *  - Sem `query`: lista `/issues.json` só com os filtros estruturados.
+ *  - Com `query`: busca `/search.json` para obter os ids que casam com o texto e
+ *    então lista `/issues.json` restringindo por `issue_id` (interseção
+ *    texto ∩ filtros). Se `/search` falhar (404/erro), DEGRADA para os filtros
+ *    estruturados e adiciona um aviso ao payload — sem quebrar a tool.
+ *
+ * Mantém a fronteira do ADR-005: encapsula os módulos internos (`client`,
+ * `bundle`) para que a superfície permaneça fina e sem acesso a URL/host.
+ */
+/** Limite default de resultados quando a superfície não informa `limit`. */
+export declare const SEARCH_DEFAULT_LIMIT = 25;
+/**
+ * Filtros estruturados aceitos por `/issues.json`. Os valores seguem os formatos
+ * do Redmine (ex.: `status_id: 'open'`, `updated_on: '>=2026-01-01'`).
+ */
+export interface IssueSearchFilters {
+    /** Filtro `project_id`. */
+    project_id?: number | undefined;
+    /** Filtro `status_id` (`'open'`, `'closed'`, `'*'` ou um id). */
+    status_id?: number | string | undefined;
+    /** Filtro `assigned_to_id` (um id ou `'me'`). */
+    assigned_to_id?: number | string | undefined;
+    /** Filtro `updated_on` no formato do Redmine (ex.: `>=2026-01-01`). */
+    updated_on?: string | undefined;
+}
+/** Opções de {@link fetchIssueSearch}: credenciais + filtros + full-text. */
+export interface FetchIssueSearchOptions {
+    /** URL base da instância Redmine (ex.: `https://redmine.example`). */
+    baseUrl: string;
+    /** api_key já resolvida pela cascata da superfície. */
+    apiKey: string;
+    /** Filtros estruturados de `/issues.json` (ver {@link IssueSearchFilters}). */
+    filters: IssueSearchFilters;
+    /** Termo full-text opcional (`/search.json`, best-effort). */
+    query?: string | undefined;
+    /** Máximo de resultados. Default: {@link SEARCH_DEFAULT_LIMIT}. */
+    limit?: number | undefined;
+    /** Permite `http://` (sem TLS) com aviso ruidoso. Default: `false`. */
+    insecure?: boolean | undefined;
+}
+/** Resultado da busca: markdown compacto + metadados de degradação. */
+export interface IssueSearchResult {
+    /** Lista compacta em Markdown pronta para o CallToolResult. */
+    content: string;
+    /** Número de itens retornados. */
+    count: number;
+    /** Avisos de degradação (ex.: `/search` indisponível). Vazio no caminho feliz. */
+    warnings: string[];
+    /** `true` quando o full-text foi solicitado mas degradou para os filtros. */
+    degraded: boolean;
+}
+/**
+ * Busca issues combinando filtros estruturados e full-text best-effort.
+ *
+ * @param options - Ver {@link FetchIssueSearchOptions}.
+ * @returns Lista compacta em Markdown + metadados de degradação.
+ * @throws {RedmineAuthError} Em 401 (propagado do client).
+ * @throws {RedmineForbiddenError} Em 403.
+ * @throws {RedmineHttpError} Em outros status ≥ 400 de `/issues.json`.
+ * @example
+ * const res = await fetchIssueSearch({
+ *   baseUrl, apiKey, filters: { project_id: 5 }, query: 'timeout', limit: 25,
+ * });
+ */
+export declare function fetchIssueSearch(options: FetchIssueSearchOptions): Promise<IssueSearchResult>;

package/dist/fetch-issue-search.js

@@ -0,0 +1,120 @@
+/**
+ * Orquestração de busca de issues para a tool `search_issues` (M1-13).
+ *
+ * Função fina do core reutilizável pela superfície MCP (#19): recebe credenciais
+ * já resolvidas + filtros estruturados + termo full-text opcional e devolve uma
+ * lista COMPACTA em Markdown (id, assunto fenced, status, responsável) — nunca o
+ * bundle completo por item.
+ *
+ * Estratégia (best-effort no full-text):
+ *  - Sem `query`: lista `/issues.json` só com os filtros estruturados.
+ *  - Com `query`: busca `/search.json` para obter os ids que casam com o texto e
+ *    então lista `/issues.json` restringindo por `issue_id` (interseção
+ *    texto ∩ filtros). Se `/search` falhar (404/erro), DEGRADA para os filtros
+ *    estruturados e adiciona um aviso ao payload — sem quebrar a tool.
+ *
+ * Mantém a fronteira do ADR-005: encapsula os módulos internos (`client`,
+ * `bundle`) para que a superfície permaneça fina e sem acesso a URL/host.
+ */
+import { buildSearchListMarkdown } from './bundle/index.js';
+import { createHttpClient, listIssues, searchIssues } from './client/index.js';
+/** Limite default de resultados quando a superfície não informa `limit`. */
+export const SEARCH_DEFAULT_LIMIT = 25;
+/** Placeholder para responsável ausente (issue sem `assigned_to`). */
+const ABSENT_ASSIGNEE = '(nenhum)';
+/** Placeholder para ref degradada/desconhecida (nome ausente). */
+const UNKNOWN_REF = '(desconhecido)';
+/** Extrai uma mensagem legível de um erro desconhecido. */
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Converte um valor desconhecido em objeto simples para acesso seguro. */
+function asRecord(value) {
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+/** Nome legível de uma ref `{ id, name }` bruta; ausência → `undefined`. */
+function refName(value) {
+    const rec = asRecord(value);
+    if (rec === undefined)
+        return undefined;
+    return typeof rec.name === 'string' ? rec.name : UNKNOWN_REF;
+}
+/** Monta os params de `/issues.json` a partir dos filtros definidos. */
+function structuredParams(filters) {
+    const params = {};
+    if (filters.project_id !== undefined)
+        params.project_id = filters.project_id;
+    if (filters.status_id !== undefined)
+        params.status_id = filters.status_id;
+    if (filters.assigned_to_id !== undefined)
+        params.assigned_to_id = filters.assigned_to_id;
+    if (filters.updated_on !== undefined)
+        params.updated_on = filters.updated_on;
+    return params;
+}
+/** Extrai a linha compacta (assunto/status/responsável) de um payload bruto. */
+function toSearchListItem(payload) {
+    return {
+        id: payload.id,
+        subject: typeof payload.subject === 'string' ? payload.subject : null,
+        status: refName(payload.status) ?? UNKNOWN_REF,
+        assignee: refName(payload.assigned_to) ?? ABSENT_ASSIGNEE,
+    };
+}
+/**
+ * Busca issues combinando filtros estruturados e full-text best-effort.
+ *
+ * @param options - Ver {@link FetchIssueSearchOptions}.
+ * @returns Lista compacta em Markdown + metadados de degradação.
+ * @throws {RedmineAuthError} Em 401 (propagado do client).
+ * @throws {RedmineForbiddenError} Em 403.
+ * @throws {RedmineHttpError} Em outros status ≥ 400 de `/issues.json`.
+ * @example
+ * const res = await fetchIssueSearch({
+ *   baseUrl, apiKey, filters: { project_id: 5 }, query: 'timeout', limit: 25,
+ * });
+ */
+export async function fetchIssueSearch(options) {
+    const { baseUrl, apiKey, filters, insecure = false } = options;
+    const limit = options.limit ?? SEARCH_DEFAULT_LIMIT;
+    const query = options.query?.trim();
+    const http = createHttpClient({ baseUrl, apiKey, insecure });
+    const warnings = [];
+    let degraded = false;
+    let payloads;
+    if (query !== undefined && query.length > 0) {
+        let hitIds;
+        try {
+            const page = await searchIssues(http, { query, limit });
+            // Ids únicos preservando a ordem de relevância do /search.
+            hitIds = [...new Set(page.hits.map((hit) => hit.id))];
+        }
+        catch (error) {
+            // Degradação best-effort: /search indisponível não quebra a tool.
+            degraded = true;
+            warnings.push(`Busca full-text indisponível (${messageOf(error)}); exibindo apenas os filtros estruturados.`);
+        }
+        if (hitIds !== undefined) {
+            // Interseção texto ∩ filtros: restringe /issues.json pelos ids do /search.
+            payloads =
+                hitIds.length === 0
+                    ? []
+                    : await listIssues(http, {
+                        filters: { ...structuredParams(filters), issue_id: hitIds.join(',') },
+                        maxItems: limit,
+                    });
+        }
+        else {
+            payloads = await listIssues(http, { filters: structuredParams(filters), maxItems: limit });
+        }
+    }
+    else {
+        payloads = await listIssues(http, { filters: structuredParams(filters), maxItems: limit });
+    }
+    const items = payloads.slice(0, limit).map(toSearchListItem);
+    const content = buildSearchListMarkdown(items, { query, warnings });
+    return { content, count: items.length, warnings, degraded };
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export declare const TOOL_NAME = "redmine-context";
+export declare const TOOL_VERSION = "1.0.0";
+export * from './contract.js';
+export { fetchIssueBundle, type BundleFormat, type FetchIssueBundleOptions, type IssueBundleResult, } from './fetch-issue-bundle.js';
+export { extractIssueAttachments, type ExtractIssueAttachmentsOptions, } from './extract-issue-attachments.js';
+export { fetchAttachmentText, fetchAttachmentTextCacheFirst, AttachmentNotFoundError, type FetchAttachmentTextOptions, type FetchAttachmentTextCacheFirstOptions, type AttachmentTextResult, } from './fetch-attachment-text.js';
+export { extractIssueAttachmentsCacheFirst, makeQueueBackgroundExtractor, processingResult, type BackgroundExtractionTarget, type BackgroundExtractor, type BackgroundCompute, type CacheFirstExtractionOptions, type QueueBackgroundOptions, } from './cache-first.js';
+export { fetchIssueSearch, SEARCH_DEFAULT_LIMIT, type FetchIssueSearchOptions, type IssueSearchFilters, type IssueSearchResult, } from './fetch-issue-search.js';
+export { searchIssues, type SearchIssuesOptions, type SearchIssuesPage } from './client/index.js';
+export { createHttpClient, type HttpClient, type HttpClientOptions, type QueryParams, } from './client/index.js';
+export { listIssues, type ListIssuesOptions, type RedmineIssuePayload } from './client/index.js';
+export { getIssue } from './client/index.js';
+export { normalizeIssue } from './normalize/index.js';
+export { buildMarkdownBundle, buildJsonBundle, fenceBlock, type MarkdownBundleMeta, type JsonBundle, type JsonBundleEnvelope, type JsonBundleMeta, type JsonBundleSource, } from './bundle/index.js';
+export { RedmineHttpError, RedmineAuthError, RedmineForbiddenError, RedmineNotFoundError, } from './client/index.js';
+export { loginWithPassword, validateApiKey, RedmineLoginError, type LoginOptions, type LoginResult, type ValidateApiKeyOptions, } from './config/index.js';
+export { createCredentialCascade, resolveApiKey, describeCredentialSource, normalizeInstanceUrl, CredentialStoreError, type CredentialCascadeOptions, type CredentialSourceKind, } from './config/index.js';
+export { defaultSettingsStore, resolveInstanceUrl, type InstanceUrlOrigin, type ResolvedInstanceUrl, type SettingsStore, } from './config/index.js';
+export { diagnoseBinaries, tesseractInstallHint, pdftotextInstallHint, ffmpegInstallHint, whisperInstallHint, type BinaryDiagnosis, type DiagnoseBinariesOptions, } from './config/index.js';
+export { findFfmpeg, detectFfmpegVersion, findWhisper, whisperModelDir, type FfmpegLocation, type WhisperLocation, } from './extract/index.js';
+export { downloadGgufModel, GgufDownloadError, GGUF_MODEL_NAME, GGUF_MODEL_URL, GGUF_MODEL_SHA256, type DownloadGgufOptions, type GgufDownloadFailure, } from './extract/index.js';