redmine-context 1.0.0

package/dist/extract/gguf.js

@@ -0,0 +1,215 @@
+/**
+ * Download do modelo GGUF do whisper.cpp com verificação de integridade
+ * (M4-02, #58, ADR-002).
+ *
+ * A transcrição local (ADR-002) exige um modelo `.gguf`, artefato independente do
+ * binário `whisper-cli` ({@link findWhisper}). Este módulo baixa esse modelo de
+ * forma AUDITÁVEL e SEGURA, respeitando a política híbrida de binários do ADR-002:
+ *
+ * - CONSTANTES PINADAS: URL HTTPS oficial ({@link GGUF_MODEL_URL}) e SHA-256
+ *   esperado ({@link GGUF_MODEL_SHA256}) ficam no código, não em config remota — a
+ *   integridade não depende de o servidor "dizer" qual é o hash certo.
+ * - SÓ HTTPS: qualquer URL `http://` é RECUSADA antes de tocar a rede (defesa
+ *   contra downgrade/MITM em ambiente corporativo).
+ * - CHECKSUM OBRIGATÓRIO: o conteúdo é gravado num `.part`, seu SHA-256 é comparado
+ *   ao pinado e só então renomeado para o destino; divergência → o `.part` é
+ *   DESCARTADO e um erro claro (esperado vs. obtido) é lançado.
+ * - RETOMADA VIA HTTP RANGE (M4-03, #59): se um `.part` de N bytes já existe, o
+ *   request pede `Range: bytes=N-` e ANEXA os bytes recebidos (`206 Partial Content`),
+ *   evitando rebaixar do zero. O checksum é sempre do arquivo COMPLETO. Fallbacks
+ *   graciosos: servidor que IGNORA o Range (`200 OK` com o corpo inteiro) recomeça
+ *   do zero sem corromper; `.part` inservível (`416`) é descartado e o download
+ *   reinicia limpo.
+ * - NUNCA EM MCP HEADLESS: o download é OPT-IN INTERATIVO (`--download-binaries`,
+ *   ADR-002). Quando a chamada sinaliza ambiente MCP/headless ({@link DownloadGgufOptions.headless}),
+ *   a função RECUSA antes de qualquer IO, com erro acionável — download silencioso
+ *   de executáveis/modelos é vetor de supply chain.
+ *
+ * Todas as dependências de efeito colateral (fetch/fs) são INJETÁVEIS
+ * ({@link GgufDeps}) para tornar os testes herméticos — sem rede nem FS real.
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { whisperModelDir } from './whisper.js';
+/**
+ * Modelo GGUF default: `ggml-tiny` (multilíngue, ~78 MB) do repositório oficial
+ * `ggerganov/whisper.cpp` no Hugging Face. Escolhido por ser o MENOR modelo
+ * multilíngue oficial — mantém o auto-detect de idioma do ADR-002 com o menor
+ * custo de download para o primeiro contato. Modelos maiores (base/small) são
+ * evolução futura configurável; a MECÂNICA de download+verificação é idêntica.
+ */
+export const GGUF_MODEL_NAME = 'ggml-tiny.bin';
+/** URL HTTPS oficial e fixa do {@link GGUF_MODEL_NAME} (Hugging Face resolve). */
+export const GGUF_MODEL_URL = 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.bin';
+/**
+ * SHA-256 hex esperado do {@link GGUF_MODEL_NAME}. É a ÂNCORA de integridade:
+ * o arquivo baixado só é aceito se seu hash bater exatamente com esta constante.
+ */
+export const GGUF_MODEL_SHA256 = 'be07e048e1e599ad46341c8d2a135645097a538221678b7acdd1b1919c6e1b21';
+/** Sufixo do arquivo parcial durante a escrita, antes do rename para o destino. */
+const PART_SUFFIX = '.part';
+/**
+ * Erro tipado de qualquer recusa/falha do download do modelo GGUF. O campo
+ * {@link GgufDownloadError.code} permite ao chamador (CLI/doctor) reagir de forma
+ * específica sem casar strings de mensagem.
+ */
+export class GgufDownloadError extends Error {
+    /** Categoria da falha — ver {@link GgufDownloadFailure}. */
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+    }
+}
+/**
+ * Constrói as dependências reais de produção: `fetch` global e `node:fs/promises`
+ * (`mkdir` recursivo, `rm` com `force`). Isolado para manter {@link downloadGgufModel}
+ * testável sem tocar rede/FS.
+ *
+ * @returns Deps ligadas ao ambiente real.
+ */
+export function defaultGgufDeps() {
+    return {
+        fetch: (url, init) => fetch(url, init),
+        mkdir: async (dir) => {
+            await mkdir(dir, { recursive: true });
+        },
+        writeFile: (path, data) => writeFile(path, data),
+        // flag 'a': cria o arquivo se ausente e sempre anexa ao fim (retomada).
+        appendFile: (path, data) => writeFile(path, data, { flag: 'a' }),
+        readPart: async (path) => new Uint8Array(await readFile(path)),
+        // stat inexistente (ENOENT) ⇒ sem `.part` ⇒ download novo (undefined).
+        statPart: async (path) => {
+            try {
+                return (await stat(path)).size;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        rename: (from, to) => rename(from, to),
+        rm: (path) => rm(path, { force: true }),
+    };
+}
+/**
+ * Baixa o modelo GGUF do whisper.cpp e o grava no cache local, verificando o
+ * SHA-256 pinado antes de considerá-lo válido (ADR-002, M4-02).
+ *
+ * Ordem dos portões (todos exercitados por testes): (1) guard headless — recusa
+ * antes de qualquer IO; (2) só HTTPS — recusa `http://` sem tocar a rede; (3)
+ * RETOMADA — se um `.part` de N bytes já existe, pede `Range: bytes=N-` e ANEXA o
+ * `206`; se o servidor ignora o Range (`200`) recomeça do zero, e um `.part`
+ * inservível (`416`) é descartado antes de reiniciar limpo; (4) compara o SHA-256
+ * do arquivo COMPLETO ao esperado — se bater, renomeia atomicamente para o destino
+ * e devolve o caminho; se não, DESCARTA o `.part` e lança {@link GgufDownloadError}
+ * com esperado vs. obtido.
+ *
+ * @param options - Destino, flag headless, origem/checksum e deps — ver {@link DownloadGgufOptions}.
+ * @returns Caminho absoluto do modelo `.gguf`/`.bin` gravado e verificado.
+ * @throws {GgufDownloadError} `headless` (ambiente MCP), `insecure-url` (não-HTTPS),
+ *   `http-error` (resposta não-2xx) ou `checksum-mismatch` (integridade divergente).
+ * @example
+ * const modelPath = await downloadGgufModel({ headless: false });
+ * logger.info(`modelo pronto em ${modelPath}`);
+ */
+export async function downloadGgufModel(options = {}) {
+    const headless = options.headless ?? false;
+    const url = options.url ?? GGUF_MODEL_URL;
+    const expected = (options.sha256 ?? GGUF_MODEL_SHA256).toLowerCase();
+    const destDir = options.destDir ?? whisperModelDir();
+    const deps = options.deps ?? defaultGgufDeps();
+    // Portão 1: opt-in interativo (ADR-002). Nunca baixa em MCP/headless.
+    if (headless) {
+        throw new GgufDownloadError('headless', 'Download do modelo GGUF é opt-in interativo (--download-binaries) e não pode ' +
+            'rodar em ambiente MCP/headless (ADR-002). Execute a CLI interativamente para baixá-lo.');
+    }
+    // Portão 2: só HTTPS — bloqueia downgrade/MITM antes de qualquer rede. Uma URL
+    // malformada é tratada como insegura (não escapa como TypeError cru).
+    let protocol;
+    try {
+        protocol = new URL(url).protocol;
+    }
+    catch {
+        throw new GgufDownloadError('insecure-url', `Download recusado: URL do modelo GGUF inválida ('${url}'). Apenas HTTPS é permitido.`);
+    }
+    if (protocol !== 'https:') {
+        throw new GgufDownloadError('insecure-url', `Download recusado: apenas HTTPS é permitido para o modelo GGUF (protocolo recebido: '${protocol}').`);
+    }
+    const finalPath = join(destDir, GGUF_MODEL_NAME);
+    const partPath = `${finalPath}${PART_SUFFIX}`;
+    // Portão 3: retomada. Um `.part` de N>0 bytes vira o ponto de partida do Range;
+    // ausente/vazio ⇒ download novo (sem cabeçalho Range).
+    const existingSize = await deps.statPart(partPath);
+    let rangeStart = existingSize !== undefined && existingSize > 0 ? existingSize : 0;
+    let response = await requestModel(deps, url, rangeStart);
+    // `.part` inservível para o servidor (ex.: já completo/maior): 416. Descarta o
+    // parcial e reinicia limpo UMA vez, para não travar num parcial envenenado.
+    if (response.status === 416 && rangeStart > 0) {
+        await deps.rm(partPath).catch(() => undefined);
+        rangeStart = 0;
+        response = await requestModel(deps, url, 0);
+    }
+    if (!response.ok) {
+        throw new GgufDownloadError('http-error', `Falha ao baixar o modelo GGUF: resposta HTTP ${response.status}.`);
+    }
+    const body = new Uint8Array(await response.arrayBuffer());
+    await deps.mkdir(destDir);
+    try {
+        // Só é retomada de verdade se pedimos Range E o servidor honrou com 206. Caso
+        // contrário (200 com o corpo inteiro), o `.part` é sobrescrito do zero — nunca
+        // anexamos a um corpo completo, o que corromperia o arquivo.
+        let complete;
+        if (rangeStart > 0 && response.status === 206) {
+            const previous = await deps.readPart(partPath);
+            await deps.appendFile(partPath, body);
+            complete = concatBytes(previous, body);
+        }
+        else {
+            await deps.writeFile(partPath, body);
+            complete = body;
+        }
+        // Portão 4: integridade do arquivo COMPLETO. Só o hash pinado valida o
+        // conteúdo — nunca o servidor.
+        const actual = createHash('sha256').update(complete).digest('hex');
+        if (actual !== expected) {
+            throw new GgufDownloadError('checksum-mismatch', `Integridade do modelo GGUF divergente: esperado ${expected}, obtido ${actual}. Arquivo descartado.`);
+        }
+        await deps.rename(partPath, finalPath);
+    }
+    catch (error) {
+        // Descarta o `.part` em QUALQUER falha (escrita parcial, checksum ou rename) —
+        // nunca deixa lixo nem um destino final corrompido. `rm` é force, idempotente.
+        await deps.rm(partPath).catch(() => undefined);
+        throw error;
+    }
+    return finalPath;
+}
+/**
+ * Faz o request do modelo, anexando `Range: bytes=<from>-` quando `from > 0` para
+ * retomar de um `.part` parcial. Isolado para manter {@link downloadGgufModel}
+ * legível e testar o cabeçalho de retomada de forma direta.
+ *
+ * @param deps - Dependências injetáveis (usa apenas `fetch`).
+ * @param url - URL HTTPS já validada do modelo.
+ * @param from - Offset de retomada em bytes; `0` faz um GET normal (sem Range).
+ * @returns A resposta HTTP (200 no download novo/fallback; 206 na retomada honrada).
+ */
+function requestModel(deps, url, from) {
+    return from > 0 ? deps.fetch(url, { headers: { Range: `bytes=${from}-` } }) : deps.fetch(url);
+}
+/**
+ * Concatena `previous` (bytes já no `.part`) com `appended` (bytes do `206`) para
+ * compor o arquivo COMPLETO sobre o qual o SHA-256 é verificado.
+ *
+ * @param previous - Bytes já presentes no `.part` antes da retomada.
+ * @param appended - Bytes recebidos no corpo do `206 Partial Content`.
+ * @returns Buffer com o conteúdo completo (`previous` seguido de `appended`).
+ */
+function concatBytes(previous, appended) {
+    const out = new Uint8Array(previous.length + appended.length);
+    out.set(previous);
+    out.set(appended, previous.length);
+    return out;
+}

package/dist/extract/index.d.ts

@@ -0,0 +1,19 @@
+export declare const MODULE_NAME: "extract";
+export { downloadAttachment, isSkipped, safeExtension, type DownloadAttachmentOptions, type DownloadResult, type SkippedDownload, } from './download.js';
+export { detectMime, detectMimeFromFile, mimeForExtension, MAGIC_SAMPLE_SIZE, } from './magic.js';
+export { dispatchExtraction, ExtractorRegistry, type DispatchOptions, type ExtractOptions, type Extractor, } from './dispatcher.js';
+export { defaultConcurrency, runQueue, type JobContext, type QueueEvent, type QueueJob, type QueueJobStatus, type RunQueueOptions, } from './queue.js';
+export { createDefaultRegistry, createTesseractExtractor, detectTesseractVersion, findTesseract, TesseractExtractor, TESSERACT_MIMES, type TesseractExtractorOptions, type TesseractLocation, } from './tesseract.js';
+export { createPdfExtractor, detectPdftotextVersion, findPdftotext, PdfExtractor, PDF_MIMES, type PdfExtractorOptions, type PdftotextLocation, } from './pdf.js';
+export { findExecutable, isExecutable, type ConventionalDirs, type ExecutableLocation, type FindExecutableDeps, } from './which.js';
+export { runWithWatchdog, sanitizedEnv, SubprocessTimeoutError, type ExecFileLike, type SanitizedEnvOptions, type WatchdogChild, type WatchdogDeps, type WatchdogInvocation, } from './subprocess.js';
+export { detectFfmpegVersion, findFfmpeg, findFfprobe, type FfmpegLocation, type FfprobeLocation, } from './ffmpeg.js';
+export { audioTempDir, convertAudioToWav, type ConvertAudioToWavOptions, type FfmpegInvocation, type FfmpegRunner, type WavConversionFailure, type WavConversionResult, type WavConversionSuccess, } from './audio.js';
+export { findWhisper, whisperModelDir, type WhisperLocation } from './whisper.js';
+export { createWhisperExtractor, parseWhisperOutput, WhisperExtractor, WHISPER_MIMES, type CreateWhisperExtractorOptions, type WhisperExtractorOptions, type WhisperInvocation, type WhisperRunner, } from './whisper-extract.js';
+export { AudioExtractor, AUDIO_MIMES, createAudioExtractor, type AudioExtractorOptions, } from './audio-extractor.js';
+export { createVideoExtractor, VideoExtractor, type VideoExtractorOptions, type VideoPipelineOverrides, } from './video-extractor.js';
+export { createOoxmlExtractor, OoxmlExtractor, OOXML_MIMES } from './ooxml.js';
+export { parseZip, type ZipArchive, type ZipEntry } from './zip.js';
+export { convertVideoToWav, extractVideoKeyframe, extractVideoTranscript, parseFfprobeDuration, probeVideoDuration, VIDEO_MIMES, type DurationProbeOk, type DurationProbeResult, type DurationProbeUnavailable, type ExtractKeyframeOptions, type ExtractVideoTranscriptOptions, type FfprobeInvocation, type FfprobeRunner, type KeyframeFailure, type KeyframeResult, type KeyframeSuccess, type ProbeVideoDurationOptions, } from './video.js';
+export { downloadGgufModel, defaultGgufDeps, GgufDownloadError, GGUF_MODEL_NAME, GGUF_MODEL_URL, GGUF_MODEL_SHA256, type DownloadGgufOptions, type GgufDeps, type GgufFetchInit, type GgufDownloadFailure, } from './gguf.js';

package/dist/extract/index.js

@@ -0,0 +1,19 @@
+export const MODULE_NAME = 'extract';
+export { downloadAttachment, isSkipped, safeExtension, } from './download.js';
+export { detectMime, detectMimeFromFile, mimeForExtension, MAGIC_SAMPLE_SIZE, } from './magic.js';
+export { dispatchExtraction, ExtractorRegistry, } from './dispatcher.js';
+export { defaultConcurrency, runQueue, } from './queue.js';
+export { createDefaultRegistry, createTesseractExtractor, detectTesseractVersion, findTesseract, TesseractExtractor, TESSERACT_MIMES, } from './tesseract.js';
+export { createPdfExtractor, detectPdftotextVersion, findPdftotext, PdfExtractor, PDF_MIMES, } from './pdf.js';
+export { findExecutable, isExecutable, } from './which.js';
+export { runWithWatchdog, sanitizedEnv, SubprocessTimeoutError, } from './subprocess.js';
+export { detectFfmpegVersion, findFfmpeg, findFfprobe, } from './ffmpeg.js';
+export { audioTempDir, convertAudioToWav, } from './audio.js';
+export { findWhisper, whisperModelDir } from './whisper.js';
+export { createWhisperExtractor, parseWhisperOutput, WhisperExtractor, WHISPER_MIMES, } from './whisper-extract.js';
+export { AudioExtractor, AUDIO_MIMES, createAudioExtractor, } from './audio-extractor.js';
+export { createVideoExtractor, VideoExtractor, } from './video-extractor.js';
+export { createOoxmlExtractor, OoxmlExtractor, OOXML_MIMES } from './ooxml.js';
+export { parseZip } from './zip.js';
+export { convertVideoToWav, extractVideoKeyframe, extractVideoTranscript, parseFfprobeDuration, probeVideoDuration, VIDEO_MIMES, } from './video.js';
+export { downloadGgufModel, defaultGgufDeps, GgufDownloadError, GGUF_MODEL_NAME, GGUF_MODEL_URL, GGUF_MODEL_SHA256, } from './gguf.js';

package/dist/extract/magic.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Detecção de MIME REAL por magic bytes (M3-08, ADR-005).
+ *
+ * SEGURANÇA: o tipo do anexo é decidido SEMPRE pelos primeiros bytes do arquivo
+ * baixado — NUNCA pela extensão do filename nem pelo `Content-Type` reportado
+ * pelo Redmine (ambos são atacáveis/mentíveis). Um `.png` que na verdade é um
+ * executável, ou um `Content-Type: image/png` sobre um zip, são detectados pelo
+ * conteúdo. Sem dependência nova: assinaturas mínimas próprias, tabeladas abaixo.
+ *
+ * Tabela de assinaturas (offset em bytes → sequência hex):
+ *
+ *   MIME                | offset | bytes (hex)                    | origem
+ *   --------------------|--------|--------------------------------|------------------
+ *   image/png           | 0      | 89 50 4E 47 0D 0A 1A 0A         | PNG signature
+ *   image/jpeg          | 0      | FF D8 FF                        | JFIF/EXIF SOI
+ *   image/gif           | 0      | 47 49 46 38 (GIF8)              | GIF87a/GIF89a
+ *   image/webp          | 0 + 8  | 52 49 46 46 (RIFF) + 57 45 42 50| RIFF container
+ *   application/pdf     | 0      | 25 50 44 46 (%PDF)              | PDF header
+ *   application/zip     | 0      | 50 4B 03 04 (PK\x03\x04)        | ZIP local header (docx/xlsx/pptx)
+ *   audio/wav           | 0 + 8  | 52 49 46 46 (RIFF) + 57 41 56 45| RIFF/WAVE container
+ *   video/x-msvideo     | 0 + 8  | 52 49 46 46 (RIFF) + 41 56 49 20| RIFF/AVI container
+ *   audio/ogg           | 0      | 4F 67 67 53 (OggS)              | Ogg container
+ *   video/webm          | 0      | 1A 45 DF A3 (EBML)             | Matroska/WebM (EBML)
+ *   audio/mpeg          | 0      | 49 44 33 (ID3) ou FF Ex sync    | MP3 (tag ID3 ou frame sync)
+ *
+ * CONTÊINERES ISO-BMFF (MP4/MOV/M4A, M4-14/#73): a box `ftyp` fica no offset 4
+ * (bytes 4-8 == 'ftyp'); a MARCA (brand, bytes 8-12) decide áudio vs vídeo. Brands
+ * de áudio (`M4A `, `M4B `) → `audio/mp4`; qualquer outra (`isom`, `mp42`, `qt  `,
+ * `avc1`, …) → `video/mp4`. Isso roteia o mesmo container para o extrator certo
+ * (whisper direto para áudio; pipeline de vídeo → áudio → whisper para vídeo).
+ *
+ * Fallback: se nenhuma assinatura casar e a amostra for "texto plausível"
+ * (sem byte NUL e maioria de bytes imprimíveis), classifica como `text/plain`.
+ * Caso contrário, retorna `undefined` (desconhecido/binário sem extrator).
+ *
+ * DOCX/XLSX/PPTX são contêineres ZIP: a detecção por magic bytes os reporta como
+ * `application/zip` — a diferenciação fina (inspecionar `[Content_Types].xml`)
+ * fica para o extrator específico, fora do escopo do dispatcher.
+ */
+/**
+ * Tamanho da amostra lida do início do arquivo. Cobre a maior assinatura
+ * (webp precisa de 12 bytes) com folga e dá base estatística ao teste de texto.
+ */
+export declare const MAGIC_SAMPLE_SIZE = 512;
+/**
+ * Detecta o MIME REAL de uma amostra de bytes via a tabela de assinaturas, com
+ * fallback para `text/plain` quando a amostra é texto plausível.
+ *
+ * @param bytes - Amostra do início do arquivo (idealmente {@link MAGIC_SAMPLE_SIZE}).
+ * @returns O MIME detectado, ou `undefined` se desconhecido/binário sem assinatura.
+ * @example
+ * detectMime(new Uint8Array([0x25, 0x50, 0x44, 0x46])); // 'application/pdf'
+ * detectMime(new Uint8Array([])); // undefined
+ */
+export declare function detectMime(bytes: Uint8Array): string | undefined;
+/**
+ * Lê o prefixo de um arquivo e detecta seu MIME REAL por magic bytes.
+ *
+ * Lê no máximo {@link MAGIC_SAMPLE_SIZE} bytes (não carrega o arquivo inteiro),
+ * então fecha o descritor. Arquivos vazios ou muito curtos resultam em
+ * `undefined` — o dispatcher os trata como `unsupported`, sem erro fatal.
+ *
+ * @param filePath - Caminho absoluto do arquivo baixado.
+ * @returns O MIME detectado, ou `undefined` se desconhecido.
+ * @throws {Error} Se o arquivo não puder ser aberto/lido (ex.: não existe).
+ */
+export declare function detectMimeFromFile(filePath: string): Promise<string | undefined>;
+/**
+ * Deriva o MIME que a EXTENSÃO de um filename declara — usado somente para o
+ * aviso de mismatch (o magic byte é a fonte de verdade). Retorna `undefined`
+ * para extensões ausentes ou não mapeadas (nesse caso não há mismatch a avisar).
+ *
+ * @param filename - Nome de arquivo reportado pelo Redmine (não confiável).
+ * @returns O MIME declarado pela extensão, ou `undefined`.
+ * @example
+ * mimeForExtension('photo.PNG'); // 'image/png'
+ * mimeForExtension('report.pdf'); // 'application/pdf'
+ * mimeForExtension('noext'); // undefined
+ */
+export declare function mimeForExtension(filename: string): string | undefined;

package/dist/extract/magic.js

@@ -0,0 +1,282 @@
+/**
+ * Detecção de MIME REAL por magic bytes (M3-08, ADR-005).
+ *
+ * SEGURANÇA: o tipo do anexo é decidido SEMPRE pelos primeiros bytes do arquivo
+ * baixado — NUNCA pela extensão do filename nem pelo `Content-Type` reportado
+ * pelo Redmine (ambos são atacáveis/mentíveis). Um `.png` que na verdade é um
+ * executável, ou um `Content-Type: image/png` sobre um zip, são detectados pelo
+ * conteúdo. Sem dependência nova: assinaturas mínimas próprias, tabeladas abaixo.
+ *
+ * Tabela de assinaturas (offset em bytes → sequência hex):
+ *
+ *   MIME                | offset | bytes (hex)                    | origem
+ *   --------------------|--------|--------------------------------|------------------
+ *   image/png           | 0      | 89 50 4E 47 0D 0A 1A 0A         | PNG signature
+ *   image/jpeg          | 0      | FF D8 FF                        | JFIF/EXIF SOI
+ *   image/gif           | 0      | 47 49 46 38 (GIF8)              | GIF87a/GIF89a
+ *   image/webp          | 0 + 8  | 52 49 46 46 (RIFF) + 57 45 42 50| RIFF container
+ *   application/pdf     | 0      | 25 50 44 46 (%PDF)              | PDF header
+ *   application/zip     | 0      | 50 4B 03 04 (PK\x03\x04)        | ZIP local header (docx/xlsx/pptx)
+ *   audio/wav           | 0 + 8  | 52 49 46 46 (RIFF) + 57 41 56 45| RIFF/WAVE container
+ *   video/x-msvideo     | 0 + 8  | 52 49 46 46 (RIFF) + 41 56 49 20| RIFF/AVI container
+ *   audio/ogg           | 0      | 4F 67 67 53 (OggS)              | Ogg container
+ *   video/webm          | 0      | 1A 45 DF A3 (EBML)             | Matroska/WebM (EBML)
+ *   audio/mpeg          | 0      | 49 44 33 (ID3) ou FF Ex sync    | MP3 (tag ID3 ou frame sync)
+ *
+ * CONTÊINERES ISO-BMFF (MP4/MOV/M4A, M4-14/#73): a box `ftyp` fica no offset 4
+ * (bytes 4-8 == 'ftyp'); a MARCA (brand, bytes 8-12) decide áudio vs vídeo. Brands
+ * de áudio (`M4A `, `M4B `) → `audio/mp4`; qualquer outra (`isom`, `mp42`, `qt  `,
+ * `avc1`, …) → `video/mp4`. Isso roteia o mesmo container para o extrator certo
+ * (whisper direto para áudio; pipeline de vídeo → áudio → whisper para vídeo).
+ *
+ * Fallback: se nenhuma assinatura casar e a amostra for "texto plausível"
+ * (sem byte NUL e maioria de bytes imprimíveis), classifica como `text/plain`.
+ * Caso contrário, retorna `undefined` (desconhecido/binário sem extrator).
+ *
+ * DOCX/XLSX/PPTX são contêineres ZIP: a detecção por magic bytes os reporta como
+ * `application/zip` — a diferenciação fina (inspecionar `[Content_Types].xml`)
+ * fica para o extrator específico, fora do escopo do dispatcher.
+ */
+import { open } from 'node:fs/promises';
+/**
+ * Tamanho da amostra lida do início do arquivo. Cobre a maior assinatura
+ * (webp precisa de 12 bytes) com folga e dá base estatística ao teste de texto.
+ */
+export const MAGIC_SAMPLE_SIZE = 512;
+/** Razão mínima de bytes imprimíveis para classificar a amostra como texto. */
+const TEXT_PRINTABLE_RATIO = 0.95;
+/** Byte NUL — sua presença descarta imediatamente a hipótese de texto. */
+const NUL_BYTE = 0x00;
+/**
+ * Tabela de assinaturas, avaliada em ordem. A primeira que casar vence — as
+ * assinaturas são disjuntas (prefixos distintos), então a ordem não é ambígua.
+ */
+const SIGNATURES = [
+    { mime: 'image/png', segments: [{ offset: 0, bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] }] },
+    { mime: 'image/jpeg', segments: [{ offset: 0, bytes: [0xff, 0xd8, 0xff] }] },
+    { mime: 'image/gif', segments: [{ offset: 0, bytes: [0x47, 0x49, 0x46, 0x38] }] },
+    {
+        mime: 'image/webp',
+        segments: [
+            { offset: 0, bytes: [0x52, 0x49, 0x46, 0x46] },
+            { offset: 8, bytes: [0x57, 0x45, 0x42, 0x50] },
+        ],
+    },
+    { mime: 'application/pdf', segments: [{ offset: 0, bytes: [0x25, 0x50, 0x44, 0x46] }] },
+    { mime: 'application/zip', segments: [{ offset: 0, bytes: [0x50, 0x4b, 0x03, 0x04] }] },
+    // RIFF/WAVE (áudio) e RIFF/AVI (vídeo): mesmo prefixo RIFF do webp, distinguidos
+    // pelo subtipo no offset 8 (segmento dupla-checado, como o webp).
+    {
+        mime: 'audio/wav',
+        segments: [
+            { offset: 0, bytes: [0x52, 0x49, 0x46, 0x46] },
+            { offset: 8, bytes: [0x57, 0x41, 0x56, 0x45] },
+        ],
+    },
+    {
+        mime: 'video/x-msvideo',
+        segments: [
+            { offset: 0, bytes: [0x52, 0x49, 0x46, 0x46] },
+            { offset: 8, bytes: [0x41, 0x56, 0x49, 0x20] },
+        ],
+    },
+    // Ogg (áudio) — o whisper transcreve a faixa; classificamos como áudio (ADR-005).
+    { mime: 'audio/ogg', segments: [{ offset: 0, bytes: [0x4f, 0x67, 0x67, 0x53] }] },
+    // EBML (Matroska/WebM): compartilham a assinatura; roteamos ao pipeline de vídeo,
+    // que extrai a faixa de áudio (webm/mkv só-áudio ainda transcreve; keyframe degrada).
+    { mime: 'video/webm', segments: [{ offset: 0, bytes: [0x1a, 0x45, 0xdf, 0xa3] }] },
+    // MP3 com tag ID3v2 no início (o frame sync puro é tratado à parte, ver detectMime).
+    { mime: 'audio/mpeg', segments: [{ offset: 0, bytes: [0x49, 0x44, 0x33] }] },
+];
+/** Segmento da box `ftyp` de um contêiner ISO-BMFF (MP4/MOV/M4A): offset 4. */
+const FTYP_SEGMENT = { offset: 4, bytes: [0x66, 0x74, 0x79, 0x70] };
+/**
+ * Brands (marca no offset 8-12) de ISO-BMFF que classificam o container como
+ * ÁUDIO: `M4A ` e `M4B `. Qualquer outra brand é tratada como vídeo (`video/mp4`).
+ */
+const AUDIO_FTYP_BRANDS = [
+    [0x4d, 0x34, 0x41, 0x20], // 'M4A '
+    [0x4d, 0x34, 0x42, 0x20], // 'M4B '
+];
+/**
+ * Detecta o MIME de um contêiner ISO-BMFF (MP4/MOV/M4A) pela box `ftyp` (offset 4)
+ * e sua brand (offset 8). Brands de áudio → `audio/mp4`; demais → `video/mp4`.
+ *
+ * @param bytes - Amostra do início do arquivo.
+ * @returns `audio/mp4` | `video/mp4` se for ISO-BMFF; `undefined` caso contrário.
+ */
+function detectFtypMime(bytes) {
+    if (!matchesSegment(bytes, FTYP_SEGMENT)) {
+        return undefined;
+    }
+    const isAudio = AUDIO_FTYP_BRANDS.some((brand) => matchesSegment(bytes, { offset: 8, bytes: brand }));
+    return isAudio ? 'audio/mp4' : 'video/mp4';
+}
+/**
+ * `true` se a amostra começa com um MPEG audio frame sync (MP3 sem tag ID3): o
+ * primeiro byte é `0xFF` e os 3 bits mais altos do segundo byte são `1` (máscara
+ * `0xE0`). Distingue-se do JPEG (`FF D8`), cujo `0xD8 & 0xE0 = 0xC0`, e do ftyp.
+ *
+ * @param bytes - Amostra do início do arquivo.
+ * @returns `true` se casar o frame sync de MP3.
+ */
+function isMp3FrameSync(bytes) {
+    const b0 = bytes[0];
+    const b1 = bytes[1];
+    if (b0 === undefined || b1 === undefined) {
+        return false;
+    }
+    return b0 === 0xff && (b1 & 0xe0) === 0xe0;
+}
+/**
+ * Mapa extensão → MIME esperado. USADO APENAS para detectar mismatch entre a
+ * extensão declarada e o magic byte real (o magic byte sempre vence, ver
+ * dispatcher). NUNCA é fonte de verdade para roteamento.
+ */
+const EXTENSION_MIME = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    pdf: 'application/pdf',
+    zip: 'application/zip',
+    docx: 'application/zip',
+    xlsx: 'application/zip',
+    pptx: 'application/zip',
+    txt: 'text/plain',
+    md: 'text/plain',
+    log: 'text/plain',
+    csv: 'text/plain',
+    // Contêineres de áudio/vídeo (M4-14/#73): mapeados para o MIME que o `detectMime`
+    // produz para o mesmo conteúdo, minimizando avisos de mismatch espúrios. O `mov`
+    // é declarado como `video/mp4` porque a brand `qt  ` é classificada como vídeo.
+    mp4: 'video/mp4',
+    m4v: 'video/mp4',
+    mov: 'video/mp4',
+    webm: 'video/webm',
+    mkv: 'video/webm',
+    avi: 'video/x-msvideo',
+    m4a: 'audio/mp4',
+    m4b: 'audio/mp4',
+    mp3: 'audio/mpeg',
+    wav: 'audio/wav',
+    ogg: 'audio/ogg',
+    oga: 'audio/ogg',
+};
+/**
+ * Verifica se um único segmento de assinatura casa com a amostra.
+ *
+ * @param bytes - Amostra lida do início do arquivo.
+ * @param segment - Segmento (offset + bytes esperados).
+ * @returns `true` se todos os bytes do segmento casam na amostra.
+ */
+function matchesSegment(bytes, segment) {
+    if (segment.offset + segment.bytes.length > bytes.length) {
+        return false;
+    }
+    for (let i = 0; i < segment.bytes.length; i += 1) {
+        if (bytes[segment.offset + i] !== segment.bytes[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Heurística de "texto plausível": sem byte NUL e com ao menos
+ * {@link TEXT_PRINTABLE_RATIO} de bytes imprimíveis (ASCII visível, espaços em
+ * branco comuns ou bytes ≥ 0x80, que cobrem sequências UTF-8). Uma amostra
+ * vazia NÃO é texto (retorna `false`).
+ *
+ * @param bytes - Amostra lida do início do arquivo.
+ * @returns `true` se a amostra parece texto legível.
+ */
+function isPlausibleText(bytes) {
+    if (bytes.length === 0) {
+        return false;
+    }
+    let printable = 0;
+    for (const byte of bytes) {
+        if (byte === NUL_BYTE) {
+            return false;
+        }
+        // Reason: tab/LF/CR + ASCII visível (0x20–0x7E) + alto (≥0x80 UTF-8) contam
+        // como imprimíveis; demais bytes de controle derrubam a razão.
+        const isWhitespace = byte === 0x09 || byte === 0x0a || byte === 0x0d;
+        const isVisibleAscii = byte >= 0x20 && byte <= 0x7e;
+        const isHighByte = byte >= 0x80;
+        if (isWhitespace || isVisibleAscii || isHighByte) {
+            printable += 1;
+        }
+    }
+    return printable / bytes.length >= TEXT_PRINTABLE_RATIO;
+}
+/**
+ * Detecta o MIME REAL de uma amostra de bytes via a tabela de assinaturas, com
+ * fallback para `text/plain` quando a amostra é texto plausível.
+ *
+ * @param bytes - Amostra do início do arquivo (idealmente {@link MAGIC_SAMPLE_SIZE}).
+ * @returns O MIME detectado, ou `undefined` se desconhecido/binário sem assinatura.
+ * @example
+ * detectMime(new Uint8Array([0x25, 0x50, 0x44, 0x46])); // 'application/pdf'
+ * detectMime(new Uint8Array([])); // undefined
+ */
+export function detectMime(bytes) {
+    for (const signature of SIGNATURES) {
+        if (signature.segments.every((segment) => matchesSegment(bytes, segment))) {
+            return signature.mime;
+        }
+    }
+    // Contêineres que exigem lógica além de casar bytes fixos: ISO-BMFF (a brand
+    // decide áudio vs vídeo) e MP3 sem tag ID3 (frame sync com máscara de bits).
+    const ftyp = detectFtypMime(bytes);
+    if (ftyp !== undefined) {
+        return ftyp;
+    }
+    if (isMp3FrameSync(bytes)) {
+        return 'audio/mpeg';
+    }
+    return isPlausibleText(bytes) ? 'text/plain' : undefined;
+}
+/**
+ * Lê o prefixo de um arquivo e detecta seu MIME REAL por magic bytes.
+ *
+ * Lê no máximo {@link MAGIC_SAMPLE_SIZE} bytes (não carrega o arquivo inteiro),
+ * então fecha o descritor. Arquivos vazios ou muito curtos resultam em
+ * `undefined` — o dispatcher os trata como `unsupported`, sem erro fatal.
+ *
+ * @param filePath - Caminho absoluto do arquivo baixado.
+ * @returns O MIME detectado, ou `undefined` se desconhecido.
+ * @throws {Error} Se o arquivo não puder ser aberto/lido (ex.: não existe).
+ */
+export async function detectMimeFromFile(filePath) {
+    const handle = await open(filePath, 'r');
+    try {
+        const buffer = Buffer.alloc(MAGIC_SAMPLE_SIZE);
+        const { bytesRead } = await handle.read(buffer, 0, MAGIC_SAMPLE_SIZE, 0);
+        return detectMime(buffer.subarray(0, bytesRead));
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Deriva o MIME que a EXTENSÃO de um filename declara — usado somente para o
+ * aviso de mismatch (o magic byte é a fonte de verdade). Retorna `undefined`
+ * para extensões ausentes ou não mapeadas (nesse caso não há mismatch a avisar).
+ *
+ * @param filename - Nome de arquivo reportado pelo Redmine (não confiável).
+ * @returns O MIME declarado pela extensão, ou `undefined`.
+ * @example
+ * mimeForExtension('photo.PNG'); // 'image/png'
+ * mimeForExtension('report.pdf'); // 'application/pdf'
+ * mimeForExtension('noext'); // undefined
+ */
+export function mimeForExtension(filename) {
+    const dot = filename.lastIndexOf('.');
+    if (dot < 0 || dot === filename.length - 1) {
+        return undefined;
+    }
+    const ext = filename.slice(dot + 1).toLowerCase();
+    return EXTENSION_MIME[ext];
+}