redmine-context 1.0.0

package/dist/extract/whisper.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Localização do binário whisper.cpp e diretório canônico do modelo GGUF
+ * (M4-01, #57, ADR-002).
+ *
+ * A milestone M4 transcreve áudio localmente com whisper.cpp (ADR-002). O binário
+ * teve VÁRIOS nomes ao longo do tempo — hoje é `whisper-cli`; o brew empacota como
+ * `whisper-cpp`; o legado era simplesmente `main`. O `doctor` (#57) detecta
+ * QUALQUER um e reporta o caminho encontrado (que revela qual binário é).
+ *
+ * DECISÕES (exercitadas por testes):
+ * - SEM FLAG DE VERSÃO ESTÁVEL: diferente de ffmpeg/tesseract, o whisper.cpp não
+ *   tem um `--version` estável entre releases — o PATH resolvido é a evidência de
+ *   presença; o `doctor` não reporta versão para ele (documentado no diagnóstico).
+ * - MODELO SEPARADO DO BINÁRIO: o binário e o modelo `.gguf` são artefatos
+ *   independentes; {@link whisperModelDir} define AGORA o path canônico do cache
+ *   de modelos (`env-paths` cache + `/models`) que a #58 (download do modelo)
+ *   consumirá — um único ponto de verdade para ambas as issues.
+ */
+import { findExecutable } from './which.js';
+/** Resultado de {@link findWhisper}: caminho + qual binário casou. */
+export interface WhisperLocation {
+    /** Caminho absoluto do executável encontrado. */
+    readonly path: string;
+    /** Nome do binário que casou (`whisper-cli` | `whisper-cpp` | `main`). */
+    readonly binaryName: string;
+}
+/**
+ * Localiza o binário do whisper.cpp no `PATH` e em locais convencionais,
+ * preferindo `whisper-cli` a `whisper-cpp` a `main`. Puro e reutilizável pelo
+ * `doctor` (#57). Não executa o binário.
+ *
+ * @param deps - Deps injetáveis (plataforma/PATH/executabilidade) — ver
+ *   {@link findExecutable}. Default: ambiente real.
+ * @returns A localização encontrada (path + nome), ou `undefined` se ausente.
+ * @example
+ * const found = findWhisper();
+ * if (found !== undefined) logger.info(`whisper.cpp: ${found.binaryName}`);
+ */
+export declare function findWhisper(deps?: Parameters<typeof findExecutable>[2]): WhisperLocation | undefined;
+/**
+ * Diretório canônico do cache de modelos GGUF do whisper.cpp — `env-paths` cache
+ * do usuário (por SO) + `/models`. PONTO ÚNICO DE VERDADE compartilhado entre o
+ * `doctor` (#57, status do modelo) e o download do modelo (#58).
+ *
+ * @returns Caminho absoluto do diretório de modelos (ex.:
+ *   `~/Library/Caches/redmine-context/models` no macOS).
+ * @example
+ * const dir = whisperModelDir();
+ */
+export declare function whisperModelDir(): string;

package/dist/extract/whisper.js

@@ -0,0 +1,67 @@
+/**
+ * Localização do binário whisper.cpp e diretório canônico do modelo GGUF
+ * (M4-01, #57, ADR-002).
+ *
+ * A milestone M4 transcreve áudio localmente com whisper.cpp (ADR-002). O binário
+ * teve VÁRIOS nomes ao longo do tempo — hoje é `whisper-cli`; o brew empacota como
+ * `whisper-cpp`; o legado era simplesmente `main`. O `doctor` (#57) detecta
+ * QUALQUER um e reporta o caminho encontrado (que revela qual binário é).
+ *
+ * DECISÕES (exercitadas por testes):
+ * - SEM FLAG DE VERSÃO ESTÁVEL: diferente de ffmpeg/tesseract, o whisper.cpp não
+ *   tem um `--version` estável entre releases — o PATH resolvido é a evidência de
+ *   presença; o `doctor` não reporta versão para ele (documentado no diagnóstico).
+ * - MODELO SEPARADO DO BINÁRIO: o binário e o modelo `.gguf` são artefatos
+ *   independentes; {@link whisperModelDir} define AGORA o path canônico do cache
+ *   de modelos (`env-paths` cache + `/models`) que a #58 (download do modelo)
+ *   consumirá — um único ponto de verdade para ambas as issues.
+ */
+import { join } from 'node:path';
+import envPaths from 'env-paths';
+import { findExecutable } from './which.js';
+/** Nome da aplicação para `env-paths` — em sincronia com o cache de anexos (ADR-004). */
+const APP_NAME = 'redmine-context';
+/** Subdiretório do cache que guarda os modelos GGUF do whisper.cpp. */
+const MODELS_SUBDIR = 'models';
+/**
+ * Nomes candidatos do binário whisper.cpp, EM ORDEM DE PREFERÊNCIA: o atual
+ * (`whisper-cli`), o empacotado pelo brew (`whisper-cpp`) e o legado (`main`).
+ *
+ * `main` é um nome genérico e é o ÚLTIMO da lista de propósito — só casa um
+ * executável exatamente chamado `main` no PATH/locais convencionais, e apenas
+ * quando nenhum nome mais específico existe (ADR-002; caveat de supply chain).
+ */
+const WHISPER_BINARIES = ['whisper-cli', 'whisper-cpp', 'main'];
+/** Locais convencionais do whisper.cpp por família de SO, após o `PATH`. */
+const CONVENTIONAL = {
+    unix: ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin'],
+    windows: ['C:\\whisper\\bin', 'C:\\Program Files\\whisper\\bin'],
+};
+/**
+ * Localiza o binário do whisper.cpp no `PATH` e em locais convencionais,
+ * preferindo `whisper-cli` a `whisper-cpp` a `main`. Puro e reutilizável pelo
+ * `doctor` (#57). Não executa o binário.
+ *
+ * @param deps - Deps injetáveis (plataforma/PATH/executabilidade) — ver
+ *   {@link findExecutable}. Default: ambiente real.
+ * @returns A localização encontrada (path + nome), ou `undefined` se ausente.
+ * @example
+ * const found = findWhisper();
+ * if (found !== undefined) logger.info(`whisper.cpp: ${found.binaryName}`);
+ */
+export function findWhisper(deps) {
+    return findExecutable(WHISPER_BINARIES, CONVENTIONAL, deps);
+}
+/**
+ * Diretório canônico do cache de modelos GGUF do whisper.cpp — `env-paths` cache
+ * do usuário (por SO) + `/models`. PONTO ÚNICO DE VERDADE compartilhado entre o
+ * `doctor` (#57, status do modelo) e o download do modelo (#58).
+ *
+ * @returns Caminho absoluto do diretório de modelos (ex.:
+ *   `~/Library/Caches/redmine-context/models` no macOS).
+ * @example
+ * const dir = whisperModelDir();
+ */
+export function whisperModelDir() {
+    return join(envPaths(APP_NAME).cache, MODELS_SUBDIR);
+}

package/dist/extract/zip.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Leitor de ZIP MÍNIMO e ZERO-DEPENDÊNCIA (#184) — só o necessário para ler
+ * entradas de contêineres OOXML (docx/pptx/xlsx). Fiel ao estilo do projeto
+ * ("sem dependência nova", como o `magic.ts`): usa apenas `node:zlib`.
+ *
+ * Lê o End Of Central Directory (EOCD) do fim do buffer, percorre o Central
+ * Directory (a fonte AUTORITATIVA dos tamanhos/offsets — funciona mesmo com data
+ * descriptors) e extrai cada entrada sob demanda: método STORED (0) devolve os
+ * bytes crus; DEFLATE (8) infla via `inflateRawSync`. Entradas de diretório
+ * (nome terminando em `/`) são ignoradas.
+ *
+ * SEGURANÇA (anti-zip-bomb): a inflação é limitada por `maxOutputLength`
+ * ({@link MAX_ENTRY_BYTES}); uma entrada que estoure o teto lança em vez de
+ * alocar memória sem limite. Não suporta ZIP64 (contêineres Office reais cabem
+ * folgadamente abaixo dos limites de 32 bits) — arquivos ZIP64 lançam, e o
+ * chamador degrada graciosamente.
+ */
+/** Metadados de uma entrada do ZIP, lidos do Central Directory. */
+export interface ZipEntry {
+    /** Nome (caminho) da entrada dentro do zip. */
+    readonly name: string;
+    /** Método de compressão (0 = stored, 8 = deflate). */
+    readonly method: number;
+    /** Tamanho comprimido em bytes. */
+    readonly compressedSize: number;
+    /** Tamanho descomprimido em bytes. */
+    readonly uncompressedSize: number;
+    /** Offset do Local file header desta entrada no buffer. */
+    readonly localHeaderOffset: number;
+}
+/** Arquivo ZIP parseado: consulta e leitura de entradas por nome. */
+export interface ZipArchive {
+    /** Nomes de todas as entradas de arquivo (exclui diretórios). */
+    names(): string[];
+    /** `true` se existe uma entrada de arquivo com esse nome exato. */
+    has(name: string): boolean;
+    /** Lê e descomprime uma entrada; `undefined` se não existir. */
+    read(name: string): Buffer | undefined;
+}
+/**
+ * Parseia um buffer ZIP e devolve um {@link ZipArchive} para leitura sob demanda.
+ *
+ * @param buffer - Conteúdo completo do arquivo zip.
+ * @returns O arquivo parseado (índice de entradas + leitura preguiçosa).
+ * @throws {Error} Se o buffer não for um zip válido ou for ZIP64 (não suportado).
+ * @example
+ * const zip = parseZip(await readFile('a.docx'));
+ * const xml = zip.read('word/document.xml')?.toString('utf8');
+ */
+export declare function parseZip(buffer: Buffer): ZipArchive;

package/dist/extract/zip.js

@@ -0,0 +1,165 @@
+/**
+ * Leitor de ZIP MÍNIMO e ZERO-DEPENDÊNCIA (#184) — só o necessário para ler
+ * entradas de contêineres OOXML (docx/pptx/xlsx). Fiel ao estilo do projeto
+ * ("sem dependência nova", como o `magic.ts`): usa apenas `node:zlib`.
+ *
+ * Lê o End Of Central Directory (EOCD) do fim do buffer, percorre o Central
+ * Directory (a fonte AUTORITATIVA dos tamanhos/offsets — funciona mesmo com data
+ * descriptors) e extrai cada entrada sob demanda: método STORED (0) devolve os
+ * bytes crus; DEFLATE (8) infla via `inflateRawSync`. Entradas de diretório
+ * (nome terminando em `/`) são ignoradas.
+ *
+ * SEGURANÇA (anti-zip-bomb): a inflação é limitada por `maxOutputLength`
+ * ({@link MAX_ENTRY_BYTES}); uma entrada que estoure o teto lança em vez de
+ * alocar memória sem limite. Não suporta ZIP64 (contêineres Office reais cabem
+ * folgadamente abaixo dos limites de 32 bits) — arquivos ZIP64 lançam, e o
+ * chamador degrada graciosamente.
+ */
+import { inflateRawSync } from 'node:zlib';
+/** Assinatura do End Of Central Directory record (`PK\x05\x06`). */
+const EOCD_SIG = 0x06054b50;
+/** Assinatura de um Central Directory file header (`PK\x01\x02`). */
+const CDH_SIG = 0x02014b50;
+/** Assinatura de um Local file header (`PK\x03\x04`). */
+const LFH_SIG = 0x04034b50;
+/** Método de compressão: armazenado sem compressão. */
+const METHOD_STORED = 0;
+/** Método de compressão: DEFLATE. */
+const METHOD_DEFLATE = 8;
+/** Teto de bytes descomprimidos por entrada (anti-zip-bomb): 64 MiB. */
+const MAX_ENTRY_BYTES = 64 * 1024 * 1024;
+/** Tamanho fixo do EOCD record (sem comentário). */
+const EOCD_MIN = 22;
+/** Tamanho fixo do Central Directory file header (sem nome/extra/comentário). */
+const CDH_FIXED = 46;
+/** Tamanho fixo do Local file header (sem nome/extra). */
+const LFH_FIXED = 30;
+/** Comprimento máximo do comentário do EOCD (campo uint16). */
+const MAX_COMMENT = 0xffff;
+/**
+ * Localiza o offset do EOCD varrendo do fim do buffer para trás (o comentário
+ * final tem até 64 KiB). Retorna o offset do PRIMEIRO EOCD encontrado a partir do
+ * fim.
+ *
+ * @param buf - Buffer do arquivo zip inteiro.
+ * @returns Offset do EOCD.
+ * @throws {Error} Se o buffer for menor que o EOCD mínimo ou não tiver a assinatura.
+ */
+function findEocd(buf) {
+    if (buf.length < EOCD_MIN) {
+        throw new Error('zip inválido: buffer menor que o EOCD mínimo');
+    }
+    const floor = Math.max(0, buf.length - EOCD_MIN - MAX_COMMENT);
+    for (let i = buf.length - EOCD_MIN; i >= floor; i -= 1) {
+        if (buf.readUInt32LE(i) === EOCD_SIG) {
+            // Anti-spoofing (dados anexados após o zip): um EOCD REAL termina EXATAMENTE
+            // no fim do arquivo (offset + 22 + tamanho-do-comentário === buf.length). Sem
+            // essa checagem, uma segunda assinatura `PK\x05\x06` forjada e anexada ao fim
+            // seria aceita, permitindo apontar o central directory para conteúdo diferente
+            // do que o Word abriria. Um Office real tem comentário vazio e EOCD no EOF.
+            const commentLen = buf.readUInt16LE(i + 20);
+            if (i + EOCD_MIN + commentLen === buf.length) {
+                return i;
+            }
+        }
+    }
+    throw new Error('zip inválido: EOCD ausente ou inconsistente (dados anexados?)');
+}
+/** Implementação de {@link ZipArchive} sobre um buffer + índice de entradas. */
+class BufferZipArchive {
+    buf;
+    entries;
+    constructor(buf, entries) {
+        this.buf = buf;
+        this.entries = entries;
+    }
+    names() {
+        return [...this.entries.keys()];
+    }
+    has(name) {
+        return this.entries.has(name);
+    }
+    read(name) {
+        const entry = this.entries.get(name);
+        if (entry === undefined) {
+            return undefined;
+        }
+        return this.readEntry(entry);
+    }
+    /**
+     * Lê e descomprime uma entrada usando o Local file header (para o offset dos
+     * dados) e o `compressedSize` do Central Directory (autoritativo).
+     *
+     * @param entry - Entrada a ler.
+     * @returns Bytes descomprimidos.
+     * @throws {Error} Se o header local for inválido, os dados truncados, o método
+     *   não suportado, ou a inflação estourar {@link MAX_ENTRY_BYTES}.
+     */
+    readEntry(entry) {
+        const buf = this.buf;
+        const off = entry.localHeaderOffset;
+        if (off + LFH_FIXED > buf.length || buf.readUInt32LE(off) !== LFH_SIG) {
+            throw new Error(`zip inválido: local header ausente para "${entry.name}"`);
+        }
+        const nameLen = buf.readUInt16LE(off + 26);
+        const extraLen = buf.readUInt16LE(off + 28);
+        const dataStart = off + LFH_FIXED + nameLen + extraLen;
+        const dataEnd = dataStart + entry.compressedSize;
+        if (dataEnd > buf.length) {
+            throw new Error(`zip inválido: dados truncados para "${entry.name}"`);
+        }
+        const raw = buf.subarray(dataStart, dataEnd);
+        if (entry.method === METHOD_STORED) {
+            if (raw.length > MAX_ENTRY_BYTES) {
+                throw new Error(`entrada "${entry.name}" excede o teto de ${MAX_ENTRY_BYTES} bytes`);
+            }
+            return Buffer.from(raw);
+        }
+        if (entry.method === METHOD_DEFLATE) {
+            return inflateRawSync(raw, { maxOutputLength: MAX_ENTRY_BYTES });
+        }
+        throw new Error(`método de compressão não suportado (${entry.method}) em "${entry.name}"`);
+    }
+}
+/**
+ * Parseia um buffer ZIP e devolve um {@link ZipArchive} para leitura sob demanda.
+ *
+ * @param buffer - Conteúdo completo do arquivo zip.
+ * @returns O arquivo parseado (índice de entradas + leitura preguiçosa).
+ * @throws {Error} Se o buffer não for um zip válido ou for ZIP64 (não suportado).
+ * @example
+ * const zip = parseZip(await readFile('a.docx'));
+ * const xml = zip.read('word/document.xml')?.toString('utf8');
+ */
+export function parseZip(buffer) {
+    const eocd = findEocd(buffer);
+    const totalEntries = buffer.readUInt16LE(eocd + 10);
+    const cdOffset = buffer.readUInt32LE(eocd + 16);
+    if (totalEntries === 0xffff || cdOffset === 0xffffffff) {
+        throw new Error('zip64 não suportado');
+    }
+    const entries = new Map();
+    let p = cdOffset;
+    for (let i = 0; i < totalEntries; i += 1) {
+        if (p + CDH_FIXED > buffer.length || buffer.readUInt32LE(p) !== CDH_SIG) {
+            throw new Error('zip inválido: central directory corrompido');
+        }
+        const method = buffer.readUInt16LE(p + 10);
+        const compressedSize = buffer.readUInt32LE(p + 20);
+        const uncompressedSize = buffer.readUInt32LE(p + 24);
+        const nameLen = buffer.readUInt16LE(p + 28);
+        const extraLen = buffer.readUInt16LE(p + 30);
+        const commentLen = buffer.readUInt16LE(p + 32);
+        const localHeaderOffset = buffer.readUInt32LE(p + 42);
+        const name = buffer.toString('utf8', p + CDH_FIXED, p + CDH_FIXED + nameLen);
+        // Entradas de diretório (nome terminando em `/`) não têm conteúdo útil.
+        // Nomes DUPLICADOS: last-write-wins (o `Map` sobrescreve). Decisão consciente —
+        // não há escrita em disco (sem path traversal), apenas round-trip de texto; a
+        // última entrada com aquele nome é a lida, como na maioria dos leitores de zip.
+        if (!name.endsWith('/')) {
+            entries.set(name, { name, method, compressedSize, uncompressedSize, localHeaderOffset });
+        }
+        p += CDH_FIXED + nameLen + extraLen + commentLen;
+    }
+    return new BufferZipArchive(buffer, entries);
+}

package/dist/extract-issue-attachments.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Orquestração core da extração de anexos de uma issue (M3-10, ADR-002/ADR-005).
+ *
+ * É a AMARRAÇÃO do M3: liga download → dispatcher → extrator → cache → bundle.
+ * Para cada anexo de IMAGEM da issue, resolve o extrator no registry, calcula a
+ * chave attachment-level ({@link buildAttachmentKey}) e, sob {@link getOrCompute}
+ * (cache de 2 camadas), baixa o binário (respeitando limite/skip do ADR-002) e o
+ * roteia para o extrator via {@link dispatchExtraction} (magic byte vence). O
+ * resultado é um `Map<attachmentId, ExtractionResult>` consumido pelos bundles.
+ *
+ * DEGRADAÇÃO GRACIOSA (ADR-002), toda exercitada por testes:
+ * - tesseract AUSENTE não impede o bundle: o extrator devolve `failed` com motivo
+ *   de instalação; o anexo apenas carrega esse status.
+ * - a falha de UM anexo (rede, IO) NÃO derruba os demais: cada anexo roda numa
+ *   Promise com `catch` individual que a converte em `failed`.
+ * - cache-hit não re-extrai: `getOrCompute` serve do store sem baixar nem rodar o
+ *   extrator caro de novo.
+ *
+ * Só anexos cujo MIME provável (extensão/`content_type`) tem extrator registrado
+ * são processados — os demais nem entram no mapa (não há trabalho a fazer). A
+ * ROTEAMENTO real dentro do `compute` ainda é decidido por magic bytes.
+ */
+import { type CacheStore, type ExtractorConfig } from './cache/index.js';
+import type { HttpClient, Logger } from './client/index.js';
+import type { Attachment, ExtractionResult, Issue } from './contract.js';
+import { type Extractor, type ExtractorRegistry } from './extract/index.js';
+/** Opções de {@link extractIssueAttachments}. */
+export interface ExtractIssueAttachmentsOptions {
+    /** URL base da instância Redmine — vira o `instance_hash` da chave e do path. */
+    instanceUrl: string;
+    /** Registry consultado para achar o extrator do MIME real de cada anexo. */
+    registry: ExtractorRegistry;
+    /** Store de cache attachment-level (memória ou disco) — ver {@link CacheStore}. */
+    store: CacheStore<ExtractionResult>;
+    /** Raiz do cache em disco p/ os downloads. Default: {@link defaultCacheDir}. */
+    cacheDir?: string;
+    /** Limite (bytes) por anexo; acima disso o download é pulado. Default do downloader. */
+    maxBytes?: number;
+    /**
+     * Sinal de CANCELAMENTO (#69/#73) fiado ao `dispatchExtraction` de cada anexo e,
+     * dali, ao `runWithWatchdog` dos extratores de mídia — ao abortar, o subprocesso
+     * (ffmpeg/whisper) é MORTO. Repassado pela fila de background do MCP via
+     * {@link JobContext.signal}. Opcional/aditivo (respeita `exactOptionalPropertyTypes`).
+     */
+    signal?: AbortSignal;
+    /** Logger para avisos (falha de anexo, mismatch); default no-op. Nunca `console.*`. */
+    logger?: Logger;
+}
+/**
+ * MIME provável de um anexo, para PRÉ-FILTRO e seleção do extrator da chave de
+ * cache: a extensão declarada e, em falta, o `content_type`. NÃO é a fonte de
+ * verdade do roteamento (isso é magic byte, dentro do `compute`).
+ *
+ * @param attachment - Anexo do contrato.
+ * @returns MIME provável, ou `undefined` se indeterminável.
+ */
+export declare function probableMime(attachment: Attachment): string | undefined;
+/**
+ * Deriva a {@link ExtractorConfig} da chave de cache a partir de um extrator,
+ * usando defaults estáveis quando `model`/`params` não são declarados.
+ *
+ * @param extractor - Extrator resolvido pelo registry.
+ * @returns Config `(version, model, params)` para {@link buildAttachmentKey}.
+ */
+export declare function toExtractorConfig(extractor: Extractor): ExtractorConfig;
+/**
+ * Extrai o texto de TODOS os anexos de imagem de uma issue, em paralelo e com
+ * degradação graciosa por anexo (ADR-002).
+ *
+ * @param http - Client HTTP autenticado da instância — ver {@link HttpClient}.
+ * @param issue - Issue normalizada cujos anexos serão processados.
+ * @param options - Ver {@link ExtractIssueAttachmentsOptions}.
+ * @returns `Map<attachmentId, ExtractionResult>` — só com anexos de imagem
+ *   (extrator registrado). Um anexo que falhe entra como `failed`, nunca ausente.
+ * @example
+ * const registry = await createDefaultRegistry();
+ * const store = new DiskCacheStore<ExtractionResult>({ cacheDir });
+ * const map = await extractIssueAttachments(http, issue, {
+ *   instanceUrl: 'https://redmine.example', cacheDir, store, registry,
+ * });
+ */
+export declare function extractIssueAttachments(http: HttpClient, issue: Issue, options: ExtractIssueAttachmentsOptions): Promise<Map<number, ExtractionResult>>;

package/dist/extract-issue-attachments.js

@@ -0,0 +1,156 @@
+/**
+ * Orquestração core da extração de anexos de uma issue (M3-10, ADR-002/ADR-005).
+ *
+ * É a AMARRAÇÃO do M3: liga download → dispatcher → extrator → cache → bundle.
+ * Para cada anexo de IMAGEM da issue, resolve o extrator no registry, calcula a
+ * chave attachment-level ({@link buildAttachmentKey}) e, sob {@link getOrCompute}
+ * (cache de 2 camadas), baixa o binário (respeitando limite/skip do ADR-002) e o
+ * roteia para o extrator via {@link dispatchExtraction} (magic byte vence). O
+ * resultado é um `Map<attachmentId, ExtractionResult>` consumido pelos bundles.
+ *
+ * DEGRADAÇÃO GRACIOSA (ADR-002), toda exercitada por testes:
+ * - tesseract AUSENTE não impede o bundle: o extrator devolve `failed` com motivo
+ *   de instalação; o anexo apenas carrega esse status.
+ * - a falha de UM anexo (rede, IO) NÃO derruba os demais: cada anexo roda numa
+ *   Promise com `catch` individual que a converte em `failed`.
+ * - cache-hit não re-extrai: `getOrCompute` serve do store sem baixar nem rodar o
+ *   extrator caro de novo.
+ *
+ * Só anexos cujo MIME provável (extensão/`content_type`) tem extrator registrado
+ * são processados — os demais nem entram no mapa (não há trabalho a fazer). A
+ * ROTEAMENTO real dentro do `compute` ainda é decidido por magic bytes.
+ */
+import { buildAttachmentKey, defaultCacheDir, getOrCompute, } from './cache/index.js';
+import { RedmineAuthError } from './client/index.js';
+import { dispatchExtraction, downloadAttachment, isSkipped, mimeForExtension, } from './extract/index.js';
+/**
+ * MIME provável de um anexo, para PRÉ-FILTRO e seleção do extrator da chave de
+ * cache: a extensão declarada e, em falta, o `content_type`. NÃO é a fonte de
+ * verdade do roteamento (isso é magic byte, dentro do `compute`).
+ *
+ * @param attachment - Anexo do contrato.
+ * @returns MIME provável, ou `undefined` se indeterminável.
+ */
+export function probableMime(attachment) {
+    return mimeForExtension(attachment.filename) ?? attachment.content_type;
+}
+/**
+ * Deriva a {@link ExtractorConfig} da chave de cache a partir de um extrator,
+ * usando defaults estáveis quando `model`/`params` não são declarados.
+ *
+ * @param extractor - Extrator resolvido pelo registry.
+ * @returns Config `(version, model, params)` para {@link buildAttachmentKey}.
+ */
+export function toExtractorConfig(extractor) {
+    return {
+        version: extractor.version,
+        model: extractor.model ?? extractor.id,
+        params: extractor.params ?? {},
+    };
+}
+/** Monta um `ExtractionResult` `failed` a partir de um erro do pipeline. */
+function failedFromError(error) {
+    return {
+        status: 'failed',
+        metadata: {
+            reason: 'erro-pipeline',
+            error: error instanceof Error ? error.message : String(error),
+        },
+    };
+}
+/**
+ * Extrai UM anexo sob cache: `getOrCompute(store, key, () => baixa + roteia)`.
+ * A chave attachment-level é imutável por conteúdo+extrator, então um cache-hit
+ * dispensa baixar e re-extrair.
+ *
+ * @param ctx - Contexto resolvido — ver {@link ExtractOneContext}.
+ * @returns O {@link ExtractionResult} (cacheado ou recém-computado).
+ */
+function extractOne(ctx) {
+    const { http, attachment, extractor, instanceUrl, cacheDir, store, registry, maxBytes, signal, logger } = ctx;
+    const key = buildAttachmentKey({ instanceUrl, attachment, extractor: toExtractorConfig(extractor) });
+    return getOrCompute(store, key, async () => {
+        const download = await downloadAttachment(http, attachment, {
+            cacheDir,
+            instanceUrl,
+            ...(maxBytes !== undefined ? { maxBytes } : {}),
+        });
+        if (isSkipped(download)) {
+            return { status: 'skipped', metadata: { reason: download.reason } };
+        }
+        return dispatchExtraction(download, {
+            registry,
+            filename: attachment.filename,
+            ...(logger !== undefined ? { logger } : {}),
+            ...(signal !== undefined ? { signal } : {}),
+        });
+    });
+}
+/**
+ * Extrai o texto de TODOS os anexos de imagem de uma issue, em paralelo e com
+ * degradação graciosa por anexo (ADR-002).
+ *
+ * @param http - Client HTTP autenticado da instância — ver {@link HttpClient}.
+ * @param issue - Issue normalizada cujos anexos serão processados.
+ * @param options - Ver {@link ExtractIssueAttachmentsOptions}.
+ * @returns `Map<attachmentId, ExtractionResult>` — só com anexos de imagem
+ *   (extrator registrado). Um anexo que falhe entra como `failed`, nunca ausente.
+ * @example
+ * const registry = await createDefaultRegistry();
+ * const store = new DiskCacheStore<ExtractionResult>({ cacheDir });
+ * const map = await extractIssueAttachments(http, issue, {
+ *   instanceUrl: 'https://redmine.example', cacheDir, store, registry,
+ * });
+ */
+export async function extractIssueAttachments(http, issue, options) {
+    const { instanceUrl, registry, store, maxBytes, signal, logger } = options;
+    const cacheDir = options.cacheDir ?? defaultCacheDir();
+    // Pré-filtro: só anexos cujo MIME provável tem extrator registrado. Os demais
+    // (PDFs, textos, tipos sem extrator) não geram trabalho nem entram no mapa.
+    //
+    // INVARIANTE DE CACHE (NIT-1 do BLOCKER-1, ADR-004): a chave attachment-level é
+    // consistente entre o caminho síncrono (aqui) e o de background porque áudio e
+    // vídeo DELEGAM `version`/`model`/`params` ao MESMO {@link WhisperExtractor}
+    // compartilhado (ver `createDefaultRegistry`). Se um dia áudio/vídeo passarem a
+    // ter model/params PRÓPRIOS (divergindo do transcritor), a chave deixaria de
+    // bater e o cache-first re-dispararia em loop — manter a delegação é o que evita
+    // essa regressão.
+    const targets = [];
+    for (const attachment of issue.attachments) {
+        const mime = probableMime(attachment);
+        const extractor = mime !== undefined ? registry.find(mime) : undefined;
+        if (extractor !== undefined) {
+            targets.push({ attachment, extractor });
+        }
+    }
+    const entries = await Promise.all(targets.map(async ({ attachment, extractor }) => {
+        try {
+            const result = await extractOne({
+                http,
+                attachment,
+                extractor,
+                instanceUrl,
+                cacheDir,
+                store,
+                registry,
+                maxBytes,
+                signal,
+                logger,
+            });
+            return [attachment.id, result];
+        }
+        catch (error) {
+            // Erro de AUTENTICAÇÃO não é falha de UM anexo: a credencial do
+            // processo expirou e nenhum download vai funcionar — propaga para o
+            // chamador acionar o re-login (review #141). O resto (rede/IO/
+            // subprocesso) degrada por anexo, como manda o ADR-002.
+            if (error instanceof RedmineAuthError) {
+                throw error;
+            }
+            logger?.warn(`extract: falha ao processar o anexo #${attachment.id} (${attachment.filename}); ` +
+                `seguindo sem ele: ${error instanceof Error ? error.message : String(error)}`);
+            return [attachment.id, failedFromError(error)];
+        }
+    }));
+    return new Map(entries);
+}