redmine-context 1.0.0

package/dist/extract/which.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Localização de executáveis no PATH + locais convencionais por SO (M4-01, #57,
+ * ADR-002).
+ *
+ * Generaliza o padrão de {@link findTesseract} (busca `tesseract` no PATH e em
+ * `/opt/homebrew/bin` etc.) para os demais binários de mídia da milestone M4
+ * (`ffmpeg`, `whisper.cpp`), que aceitam MÚLTIPLOS nomes de binário — o
+ * whisper.cpp mudou de `main` (legado) para `whisper-cli` (atual) e o brew
+ * empacota como `whisper-cpp`. Decisões (exercitadas por testes):
+ *
+ * - PURO E INJETÁVEL: `platform`, `PATH` e o predicado de executabilidade são
+ *   injetáveis — os três SOs e os estados presente/ausente são testáveis num
+ *   único host, sem tocar filesystem/binário reais.
+ * - PRIORIDADE POR NOME: os nomes candidatos são tentados NA ORDEM dada (o loop
+ *   externo é o nome), e dentro de cada nome o `PATH` vem antes dos locais
+ *   convencionais — assim `whisper-cli` é preferido a `main` mesmo que ambos
+ *   existam, e reportamos QUAL foi encontrado ({@link ExecutableLocation.binaryName}).
+ * - SUFIXO `.exe` NO WINDOWS: aplicado a todos os candidatos automaticamente.
+ */
+/** Diretórios convencionais de um binário, separados por família de SO. */
+export interface ConventionalDirs {
+    /** Locais convencionais em UNIX (darwin/linux), consultados após o `PATH`. */
+    readonly unix: readonly string[];
+    /** Locais convencionais no Windows, consultados após o `PATH`. */
+    readonly windows: readonly string[];
+}
+/** Resultado de {@link findExecutable}: caminho absoluto + qual nome casou. */
+export interface ExecutableLocation {
+    /** Caminho absoluto do executável encontrado. */
+    readonly path: string;
+    /** Nome base do binário que casou (ex.: `whisper-cli`), sem sufixo `.exe`. */
+    readonly binaryName: string;
+}
+/** Dependências injetáveis de {@link findExecutable} — defaults de produção. */
+export interface FindExecutableDeps {
+    /** SO alvo; default `process.platform`. Decide `.exe` e os locais convencionais. */
+    readonly platform?: NodeJS.Platform;
+    /** Valor do `PATH`; default `process.env.PATH`. */
+    readonly pathValue?: string | undefined;
+    /** Predicado de executabilidade; default {@link isExecutable}. */
+    readonly isExecutable?: (candidate: string) => boolean;
+}
+/**
+ * Verifica se um caminho aponta para um arquivo executável (bit X), sem lançar.
+ *
+ * @param candidate - Caminho absoluto candidato ao binário.
+ * @returns `true` se o arquivo existe e é executável pelo processo atual.
+ */
+export declare function isExecutable(candidate: string): boolean;
+/**
+ * Localiza o PRIMEIRO executável de {@link baseNames} no `PATH` e nos locais
+ * convencionais do SO. Função pura e reutilizável pelo `doctor` (#57); não
+ * executa o binário. A ordem de {@link baseNames} é a prioridade (nome externo,
+ * PATH antes dos convencionais dentro de cada nome).
+ *
+ * @param baseNames - Nomes candidatos, em ordem de preferência (sem `.exe`).
+ * @param conventional - Locais convencionais por família de SO.
+ * @param deps - Deps injetáveis (plataforma, PATH, executabilidade).
+ * @returns A localização encontrada (path + nome que casou), ou `undefined`.
+ * @example
+ * findExecutable(['whisper-cli', 'main'], { unix: ['/opt/homebrew/bin'], windows: [] });
+ */
+export declare function findExecutable(baseNames: readonly string[], conventional: ConventionalDirs, deps?: FindExecutableDeps): ExecutableLocation | undefined;

package/dist/extract/which.js

@@ -0,0 +1,72 @@
+/**
+ * Localização de executáveis no PATH + locais convencionais por SO (M4-01, #57,
+ * ADR-002).
+ *
+ * Generaliza o padrão de {@link findTesseract} (busca `tesseract` no PATH e em
+ * `/opt/homebrew/bin` etc.) para os demais binários de mídia da milestone M4
+ * (`ffmpeg`, `whisper.cpp`), que aceitam MÚLTIPLOS nomes de binário — o
+ * whisper.cpp mudou de `main` (legado) para `whisper-cli` (atual) e o brew
+ * empacota como `whisper-cpp`. Decisões (exercitadas por testes):
+ *
+ * - PURO E INJETÁVEL: `platform`, `PATH` e o predicado de executabilidade são
+ *   injetáveis — os três SOs e os estados presente/ausente são testáveis num
+ *   único host, sem tocar filesystem/binário reais.
+ * - PRIORIDADE POR NOME: os nomes candidatos são tentados NA ORDEM dada (o loop
+ *   externo é o nome), e dentro de cada nome o `PATH` vem antes dos locais
+ *   convencionais — assim `whisper-cli` é preferido a `main` mesmo que ambos
+ *   existam, e reportamos QUAL foi encontrado ({@link ExecutableLocation.binaryName}).
+ * - SUFIXO `.exe` NO WINDOWS: aplicado a todos os candidatos automaticamente.
+ */
+import { accessSync, constants } from 'node:fs';
+import { posix, win32 } from 'node:path';
+/**
+ * Verifica se um caminho aponta para um arquivo executável (bit X), sem lançar.
+ *
+ * @param candidate - Caminho absoluto candidato ao binário.
+ * @returns `true` se o arquivo existe e é executável pelo processo atual.
+ */
+export function isExecutable(candidate) {
+    try {
+        accessSync(candidate, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Localiza o PRIMEIRO executável de {@link baseNames} no `PATH` e nos locais
+ * convencionais do SO. Função pura e reutilizável pelo `doctor` (#57); não
+ * executa o binário. A ordem de {@link baseNames} é a prioridade (nome externo,
+ * PATH antes dos convencionais dentro de cada nome).
+ *
+ * @param baseNames - Nomes candidatos, em ordem de preferência (sem `.exe`).
+ * @param conventional - Locais convencionais por família de SO.
+ * @param deps - Deps injetáveis (plataforma, PATH, executabilidade).
+ * @returns A localização encontrada (path + nome que casou), ou `undefined`.
+ * @example
+ * findExecutable(['whisper-cli', 'main'], { unix: ['/opt/homebrew/bin'], windows: [] });
+ */
+export function findExecutable(baseNames, conventional, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const isWindows = platform === 'win32';
+    const executable = deps.isExecutable ?? isExecutable;
+    const pathValue = deps.pathValue ?? process.env.PATH ?? '';
+    // Reason: `platform` é injetável (testar os 3 SOs num host só) — o join/split do
+    // PATH DEVE seguir o SO alvo, não o host, senão os separadores divergem.
+    const path = isWindows ? win32 : posix;
+    const pathDirs = pathValue.split(path.delimiter).filter((dir) => dir.length > 0);
+    const dirs = [...pathDirs, ...(isWindows ? conventional.windows : conventional.unix)];
+    const suffix = isWindows ? '.exe' : '';
+    // Reason: prioridade por NOME (loop externo) — um `whisper-cli` no PATH ganha
+    // de um `main` convencional, e é o nome reportado ao usuário.
+    for (const name of baseNames) {
+        for (const dir of dirs) {
+            const candidate = path.join(dir, `${name}${suffix}`);
+            if (executable(candidate)) {
+                return { path: candidate, binaryName: name };
+            }
+        }
+    }
+    return undefined;
+}

package/dist/extract/whisper-extract.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Extrator de transcrição de áudio via whisper.cpp (M4-05, #61, ADR-002).
+ *
+ * Recebe um WAV (o formato PCM 16 kHz mono produzido pela conversão da #60) e o
+ * transcreve para texto rodando o binário do whisper.cpp com o modelo GGUF do
+ * cache local. Espelha o estilo dos extratores já estabelecidos
+ * ({@link TesseractExtractor}, {@link convertAudioToWav}). Decisões de
+ * segurança/robustez (ADR-002), todas exercitadas por testes:
+ *
+ * - INVOCAÇÃO SEM SHELL: usa `execFile` (nunca `exec`/shell) com uma lista de
+ *   argumentos explícita — o caminho do WAV e do modelo NUNCA são interpolados
+ *   numa string de shell.
+ * - ENV SANITIZADO: o subprocesso recebe um env MÍNIMO (só `PATH`) — segredos do
+ *   processo pai (ex.: `REDMINE_API_KEY`) NUNCA vazam para o whisper.
+ * - MODELO GGUF DO CACHE: o modelo é passado via `-m <path>`, resolvido a partir
+ *   do diretório canônico de modelos ({@link whisperModelDir}) + {@link GGUF_MODEL_NAME}
+ *   — o binário e o modelo são artefatos independentes (ver `whisper.ts`).
+ * - IDIOMA AUTO-DETECT COM OVERRIDE (#62): sem `language`, nenhuma flag de idioma
+ *   é passada e o auto-detect (default do whisper.cpp, ADR-002) vale. Com
+ *   `language` (ex.: `'pt'`), o idioma é FORÇADO via `-l <lang>` — e o idioma entra
+ *   no `params` da chave attachment-level (ADR-004) e no `extraction.json`, de modo
+ *   que trocar modelo OU idioma gera chave distinta (reprocessa) e o mesmo par gera
+ *   a mesma chave (cache hit). O idioma é opcional (`exactOptionalPropertyTypes`:
+ *   nunca injetado como `undefined`).
+ * - TIMEOUT + KILL: um watchdog envia `SIGTERM` no timeout e, após a graça,
+ *   `SIGKILL` — um whisper travado não pendura a fila de jobs.
+ * - DEGRADAÇÃO GRACIOSA: binário ausente, modelo GGUF ausente, exit != 0 ou
+ *   timeout NÃO lançam; devolvem `{ status: 'failed', metadata.reason }` com dica.
+ *
+ * UNTRUSTED: a transcrição é conteúdo DERIVADO de um anexo (input hostil), logo é
+ * NÃO-CONFIÁVEL. Este extrator NÃO reembrulha o texto: expõe `text` cru, e a
+ * camada bundle (`src/bundle/json.ts` / `src/bundle/markdown.ts`) o isola em
+ * `{ untrusted: true }` / `<untrusted-content>` — o mesmo mecanismo do tesseract.
+ *
+ * CONFIDENCE: o stdout default do whisper.cpp (mesmo com timestamps) NÃO carrega
+ * um score de confiança agregado; obter probabilidades por token exigiria a saída
+ * JSON (`-oj`) + leitura de arquivo, fora do escopo XS desta issue. Por isso
+ * `confidence` é OMITIDO do resultado (respeitando `exactOptionalPropertyTypes`,
+ * nunca injetado como `undefined`) — "se disponível na saída, senão omita".
+ *
+ * TESTABILIDADE: o executor do subprocesso, o localizador do binário e o do modelo
+ * são INJETÁVEIS — os testes unitários são herméticos (sem whisper/modelo/FS reais)
+ * e asseguram os args passados ao executor.
+ */
+import type { ExtractorParams } from '../cache/contract.js';
+import type { ExtractorConfig } from '../cache/keys.js';
+import type { ExtractionResult } from '../contract.js';
+import type { ExtractOptions, Extractor } from './dispatcher.js';
+/**
+ * MIMEs de áudio roteados para a transcrição. O whisper.cpp consome o WAV; o
+ * pipeline real (áudio → WAV via #60 → whisper) é orquestrado por quem chama.
+ * Registrar estes MIMEs deixa o extrator pronto no registry default.
+ */
+export declare const WHISPER_MIMES: readonly string[];
+/**
+ * Parseia o stdout do whisper.cpp numa transcrição de linha única. Remove o
+ * prefixo de timestamp de cada linha (robustez, mesmo com `-nt` ativo), descarta
+ * linhas vazias e junta o texto com espaço, colapsando espaços em branco.
+ *
+ * @param stdout - Saída bruta do whisper.cpp.
+ * @returns O texto transcrito, ou string vazia se não houver conteúdo.
+ * @example
+ * parseWhisperOutput('[00:00:00.000 --> 00:00:02.000]  Olá\n'); // 'Olá'
+ */
+export declare function parseWhisperOutput(stdout: string): string;
+/** Invocação concreta do whisper passada ao {@link WhisperRunner}. */
+export interface WhisperInvocation {
+    /** Caminho absoluto do binário whisper.cpp já resolvido. */
+    readonly bin: string;
+    /** Argumentos (sem shell): `-m <modelo GGUF> -f <wav> -nt`. */
+    readonly args: readonly string[];
+    /** Env SANITIZADO do subprocesso (só `PATH`). */
+    readonly env: NodeJS.ProcessEnv;
+    /** Timeout antes do `SIGTERM` (ms). */
+    readonly timeoutMs: number;
+    /** Graça `SIGTERM` → `SIGKILL` (ms). */
+    readonly killGraceMs: number;
+    /**
+     * Sinal de CANCELAMENTO (#69/#73) repassado ao {@link runWithWatchdog}, que MATA
+     * o whisper (`SIGTERM`→`SIGKILL`) ao abortar. Opcional/aditivo (respeita
+     * `exactOptionalPropertyTypes` — nunca injetado como `undefined`).
+     */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Executor injetável do subprocesso whisper. Resolve com o `stdout` (a
+ * transcrição) no sucesso; rejeita em falha (exit != 0, binário não-executável em
+ * runtime) — rejeitando com um erro de nome `WhisperTimeoutError` no estouro de
+ * timeout.
+ */
+export type WhisperRunner = (invocation: WhisperInvocation) => Promise<string>;
+/** Opções de construção do {@link WhisperExtractor}. */
+export interface WhisperExtractorOptions {
+    /**
+     * Caminho absoluto do binário já resolvido. `undefined` = não instalado; nesse
+     * caso {@link WhisperExtractor.extract} degrada para `failed` (não lança).
+     */
+    readonly binaryPath?: string | undefined;
+    /**
+     * Caminho absoluto do modelo GGUF no cache. `undefined` = modelo ausente; nesse
+     * caso {@link WhisperExtractor.extract} degrada para `failed` (não lança).
+     */
+    readonly modelPath?: string | undefined;
+    /** Versão exposta na chave de cache (default de fábrica: {@link INTEGRATION_VERSION}). */
+    readonly version: string;
+    /**
+     * Idioma a FORÇAR (#62), ex.: `'pt'`. Ausente (`undefined`) = auto-detect (o
+     * default do whisper.cpp). Quando dado, entra nos args (`-l <lang>`), no `params`
+     * da chave de cache (ADR-004) e no `extraction.json`. Opcional — nunca injetado
+     * como `undefined` (respeita `exactOptionalPropertyTypes`).
+     */
+    readonly language?: string | undefined;
+    /** Executor do subprocesso; default: watchdog real com `execFile`. */
+    readonly run?: WhisperRunner;
+    /** Timeout antes do `SIGTERM` (ms); default {@link DEFAULT_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+    /** Graça `SIGTERM` → `SIGKILL` (ms); default {@link DEFAULT_KILL_GRACE_MS}. */
+    readonly killGraceMs?: number;
+}
+/**
+ * Extrator de transcrição baseado no binário whisper.cpp (ADR-002). Implementa
+ * {@link Extractor} e, além do contrato, expõe {@link extractorConfig} estável
+ * para {@link buildAttachmentKey}.
+ */
+export declare class WhisperExtractor implements Extractor {
+    readonly id = "whisper-transcribe";
+    readonly version: string;
+    readonly supportedMimes: readonly string[];
+    /**
+     * Modelo lógico (nome do GGUF) para a chave de cache (ADR-004). Derivado do
+     * `modelPath` (basename) quando dado, para que TROCAR o modelo gere chave
+     * attachment-level DISTINTA (#72); sem `modelPath`, cai no default pinado.
+     */
+    readonly model: string;
+    /**
+     * Parâmetros escalares da chave de cache (ADR-004). Vazio no auto-detect; com
+     * idioma forçado (#62), `{ language }` — trocar o idioma gera chave distinta.
+     */
+    readonly params: ExtractorParams;
+    private readonly binaryPath;
+    private readonly modelPath;
+    /** Idioma forçado (#62), ou `undefined` = auto-detect. */
+    private readonly language;
+    private readonly run;
+    private readonly timeoutMs;
+    private readonly killGraceMs;
+    /**
+     * @param options - Ver {@link WhisperExtractorOptions}.
+     */
+    constructor(options: WhisperExtractorOptions);
+    /**
+     * Configuração do extrator pronta para {@link buildAttachmentKey} (ADR-004).
+     * @returns `{ version, model, params }` estáveis desta instância.
+     */
+    get extractorConfig(): ExtractorConfig;
+    /**
+     * Transcreve o WAV em `filePath`. Nunca lança: falhas (binário ausente, modelo
+     * GGUF ausente, timeout, erro de execução) viram `{ status: 'failed',
+     * metadata.reason }` — degradação graciosa (ADR-002).
+     *
+     * @param filePath - Caminho absoluto do WAV (ou áudio) a transcrever.
+     * @param options - MIME real + logger — ver {@link ExtractOptions}.
+     * @returns `done` com `text` no sucesso; `failed` com motivo claro na falha.
+     */
+    extract(filePath: string, options: ExtractOptions): Promise<ExtractionResult>;
+    /**
+     * Monta um `ExtractionResult` `failed` com metadados de diagnóstico, sem injetar
+     * chaves `undefined` (respeita `exactOptionalPropertyTypes`).
+     *
+     * @param mime - MIME real detectado (do dispatcher).
+     * @param reason - Motivo canônico da falha.
+     * @param extra - Metadados adicionais (hint/erro).
+     * @returns Resultado `failed` tipado.
+     */
+    private failed;
+}
+/** Opções de composição do {@link createWhisperExtractor} (localizadores injetáveis). */
+export interface CreateWhisperExtractorOptions {
+    /**
+     * Localizador do binário whisper.cpp; retorna o caminho absoluto ou `undefined`
+     * (não instalado). Default: {@link findWhisper} no ambiente real.
+     */
+    readonly findBinary?: () => string | undefined;
+    /**
+     * Localizador do modelo GGUF no cache; retorna o caminho absoluto ou `undefined`
+     * (ausente). Default: {@link whisperModelDir} + {@link GGUF_MODEL_NAME} se existir.
+     */
+    readonly findModel?: () => string | undefined;
+    /**
+     * Idioma a FORÇAR (#62), ex.: `'pt'`. Ausente = auto-detect. Propagado ao
+     * {@link WhisperExtractor} (args `-l <lang>` + `params` da chave + extraction.json).
+     */
+    readonly language?: string | undefined;
+    /** Executor do subprocesso; default: watchdog real com `execFile`. */
+    readonly run?: WhisperRunner;
+    /** Timeout antes do `SIGTERM` (ms); default {@link DEFAULT_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+    /** Graça `SIGTERM` → `SIGKILL` (ms); default {@link DEFAULT_KILL_GRACE_MS}. */
+    readonly killGraceMs?: number;
+}
+/**
+ * Cria um {@link WhisperExtractor} resolvendo binário e modelo GGUF. Localiza o
+ * whisper.cpp ({@link findWhisper}) e o modelo no cache; ambos ausentes fazem o
+ * extrator degradar graciosamente em `extract` (ADR-002), sem lançar aqui.
+ *
+ * @param options - Localizadores/executor/timeouts injetáveis — ver {@link CreateWhisperExtractorOptions}.
+ * @returns O extrator pronto para registro no {@link ExtractorRegistry}.
+ * @example
+ * const extractor = await createWhisperExtractor();
+ */
+export declare function createWhisperExtractor(options?: CreateWhisperExtractorOptions): Promise<WhisperExtractor>;

package/dist/extract/whisper-extract.js

@@ -0,0 +1,323 @@
+/**
+ * Extrator de transcrição de áudio via whisper.cpp (M4-05, #61, ADR-002).
+ *
+ * Recebe um WAV (o formato PCM 16 kHz mono produzido pela conversão da #60) e o
+ * transcreve para texto rodando o binário do whisper.cpp com o modelo GGUF do
+ * cache local. Espelha o estilo dos extratores já estabelecidos
+ * ({@link TesseractExtractor}, {@link convertAudioToWav}). Decisões de
+ * segurança/robustez (ADR-002), todas exercitadas por testes:
+ *
+ * - INVOCAÇÃO SEM SHELL: usa `execFile` (nunca `exec`/shell) com uma lista de
+ *   argumentos explícita — o caminho do WAV e do modelo NUNCA são interpolados
+ *   numa string de shell.
+ * - ENV SANITIZADO: o subprocesso recebe um env MÍNIMO (só `PATH`) — segredos do
+ *   processo pai (ex.: `REDMINE_API_KEY`) NUNCA vazam para o whisper.
+ * - MODELO GGUF DO CACHE: o modelo é passado via `-m <path>`, resolvido a partir
+ *   do diretório canônico de modelos ({@link whisperModelDir}) + {@link GGUF_MODEL_NAME}
+ *   — o binário e o modelo são artefatos independentes (ver `whisper.ts`).
+ * - IDIOMA AUTO-DETECT COM OVERRIDE (#62): sem `language`, nenhuma flag de idioma
+ *   é passada e o auto-detect (default do whisper.cpp, ADR-002) vale. Com
+ *   `language` (ex.: `'pt'`), o idioma é FORÇADO via `-l <lang>` — e o idioma entra
+ *   no `params` da chave attachment-level (ADR-004) e no `extraction.json`, de modo
+ *   que trocar modelo OU idioma gera chave distinta (reprocessa) e o mesmo par gera
+ *   a mesma chave (cache hit). O idioma é opcional (`exactOptionalPropertyTypes`:
+ *   nunca injetado como `undefined`).
+ * - TIMEOUT + KILL: um watchdog envia `SIGTERM` no timeout e, após a graça,
+ *   `SIGKILL` — um whisper travado não pendura a fila de jobs.
+ * - DEGRADAÇÃO GRACIOSA: binário ausente, modelo GGUF ausente, exit != 0 ou
+ *   timeout NÃO lançam; devolvem `{ status: 'failed', metadata.reason }` com dica.
+ *
+ * UNTRUSTED: a transcrição é conteúdo DERIVADO de um anexo (input hostil), logo é
+ * NÃO-CONFIÁVEL. Este extrator NÃO reembrulha o texto: expõe `text` cru, e a
+ * camada bundle (`src/bundle/json.ts` / `src/bundle/markdown.ts`) o isola em
+ * `{ untrusted: true }` / `<untrusted-content>` — o mesmo mecanismo do tesseract.
+ *
+ * CONFIDENCE: o stdout default do whisper.cpp (mesmo com timestamps) NÃO carrega
+ * um score de confiança agregado; obter probabilidades por token exigiria a saída
+ * JSON (`-oj`) + leitura de arquivo, fora do escopo XS desta issue. Por isso
+ * `confidence` é OMITIDO do resultado (respeitando `exactOptionalPropertyTypes`,
+ * nunca injetado como `undefined`) — "se disponível na saída, senão omita".
+ *
+ * TESTABILIDADE: o executor do subprocesso, o localizador do binário e o do modelo
+ * são INJETÁVEIS — os testes unitários são herméticos (sem whisper/modelo/FS reais)
+ * e asseguram os args passados ao executor.
+ */
+import { existsSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { GGUF_MODEL_NAME } from './gguf.js';
+import { runWithWatchdog, sanitizedEnv } from './subprocess.js';
+import { findWhisper, whisperModelDir } from './whisper.js';
+/** Identificador estável do extrator (entra em metadados). */
+const EXTRACTOR_ID = 'whisper-transcribe';
+/**
+ * Modelo lógico para a chave de cache (ADR-004): o nome do arquivo GGUF. Trocar o
+ * modelo (ex.: `ggml-tiny` → `ggml-base`) muda a identidade e invalida o cache.
+ */
+const EXTRACTOR_MODEL = GGUF_MODEL_NAME;
+/**
+ * Versão da integração. Diferente de ffmpeg/tesseract, o whisper.cpp não tem um
+ * `--version` estável entre releases (ver `whisper.ts`), então usamos uma versão
+ * de integração fixa para a chave de cache (ADR-004).
+ */
+const INTEGRATION_VERSION = 'whisper-integration-1';
+/** Timeout default de uma transcrição antes do `SIGTERM` (ms) — áudio é lento. */
+const DEFAULT_TIMEOUT_MS = 120_000;
+/** Graça entre `SIGTERM` e `SIGKILL` (ms) — dá ao whisper chance de sair limpo. */
+const DEFAULT_KILL_GRACE_MS = 2_000;
+/** Teto do stdout capturado (16 MiB) — transcrições longas cabem com folga. */
+const MAX_BUFFER_BYTES = 16 * 1024 * 1024;
+/** Flag `-nt` (no timestamps): mantém o stdout como texto puro, fácil de parsear. */
+const NO_TIMESTAMPS_FLAG = '-nt';
+/**
+ * Flag de idioma do whisper-cli (whisper.cpp): `-l <lang>` (equiv. `--language`).
+ * Só é acrescentada quando o idioma é forçado (#62); ausente = auto-detect.
+ */
+const LANGUAGE_FLAG = '-l';
+/**
+ * MIMEs de áudio roteados para a transcrição. O whisper.cpp consome o WAV; o
+ * pipeline real (áudio → WAV via #60 → whisper) é orquestrado por quem chama.
+ * Registrar estes MIMEs deixa o extrator pronto no registry default.
+ */
+export const WHISPER_MIMES = [
+    'audio/wav',
+    'audio/x-wav',
+    'audio/mpeg',
+    'audio/mp4',
+    'audio/ogg',
+    'audio/webm',
+    'audio/flac',
+];
+/** Regex do prefixo de timestamp do whisper.cpp: `[00:00:00.000 --> 00:00:02.000]`. */
+const TIMESTAMP_PREFIX = /^\[[0-9:.]+\s*-->\s*[0-9:.]+\]\s*/;
+/** Colapsa qualquer sequência de espaços em branco num único espaço. */
+const WHITESPACE_RUN = /\s+/g;
+/**
+ * Parseia o stdout do whisper.cpp numa transcrição de linha única. Remove o
+ * prefixo de timestamp de cada linha (robustez, mesmo com `-nt` ativo), descarta
+ * linhas vazias e junta o texto com espaço, colapsando espaços em branco.
+ *
+ * @param stdout - Saída bruta do whisper.cpp.
+ * @returns O texto transcrito, ou string vazia se não houver conteúdo.
+ * @example
+ * parseWhisperOutput('[00:00:00.000 --> 00:00:02.000]  Olá\n'); // 'Olá'
+ */
+export function parseWhisperOutput(stdout) {
+    return stdout
+        .split('\n')
+        .map((line) => line.replace(TIMESTAMP_PREFIX, '').trim())
+        .filter((line) => line.length > 0)
+        .join(' ')
+        .replace(WHITESPACE_RUN, ' ')
+        .trim();
+}
+/** Erro interno: o watchdog matou o whisper por estourar o timeout. */
+class WhisperTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`whisper excedeu o timeout de ${timeoutMs}ms e foi encerrado`);
+        this.timeoutMs = timeoutMs;
+        this.name = 'WhisperTimeoutError';
+    }
+}
+/**
+ * Monta os argumentos do whisper.cpp: modelo GGUF via `-m`, entrada WAV via `-f` e
+ * `-nt` (sem timestamps, stdout limpo). Se `language` for dado (#62), acrescenta
+ * `-l <lang>` para FORÇAR o idioma; ausente, nenhuma flag de idioma é passada e o
+ * auto-detect (default do whisper.cpp, ADR-002) vale.
+ *
+ * @param modelPath - Caminho absoluto do modelo GGUF no cache.
+ * @param inputPath - Caminho absoluto do WAV a transcrever.
+ * @param language - Código do idioma a forçar (ex.: `'pt'`), ou `undefined` = auto.
+ * @returns Lista de argumentos, na ordem esperada pelo whisper.cpp.
+ */
+function buildWhisperArgs(modelPath, inputPath, language) {
+    const args = ['-m', modelPath, '-f', inputPath, NO_TIMESTAMPS_FLAG];
+    return language !== undefined ? [...args, LANGUAGE_FLAG, language] : args;
+}
+/** `true` se o erro sinaliza estouro de timeout do watchdog (por nome, robusto a DI). */
+function isTimeoutError(error) {
+    return error instanceof Error && error.name === 'WhisperTimeoutError';
+}
+/**
+ * Executor default: delega ao watchdog compartilhado ({@link runWithWatchdog}) —
+ * whisper.cpp SEM shell, env sanitizado e escalonamento `SIGTERM` → graça →
+ * `SIGKILL`. Resolve com o `stdout` (a transcrição) no exit 0; o estouro de
+ * timeout é sinalizado com {@link WhisperTimeoutError} para preservar a
+ * classificação de falha (`reason: 'timeout'`).
+ *
+ * @param invocation - Ver {@link WhisperInvocation}.
+ * @returns O stdout (transcrição) do whisper.
+ */
+function defaultRun(invocation) {
+    const { bin, args, env, timeoutMs, killGraceMs, signal } = invocation;
+    return runWithWatchdog({
+        bin,
+        args,
+        env,
+        timeoutMs,
+        killGraceMs,
+        maxBuffer: MAX_BUFFER_BYTES,
+        ...(signal !== undefined ? { signal } : {}),
+    }, { makeTimeoutError: (ms) => new WhisperTimeoutError(ms) });
+}
+/**
+ * Extrator de transcrição baseado no binário whisper.cpp (ADR-002). Implementa
+ * {@link Extractor} e, além do contrato, expõe {@link extractorConfig} estável
+ * para {@link buildAttachmentKey}.
+ */
+export class WhisperExtractor {
+    id = EXTRACTOR_ID;
+    version;
+    supportedMimes = WHISPER_MIMES;
+    /**
+     * Modelo lógico (nome do GGUF) para a chave de cache (ADR-004). Derivado do
+     * `modelPath` (basename) quando dado, para que TROCAR o modelo gere chave
+     * attachment-level DISTINTA (#72); sem `modelPath`, cai no default pinado.
+     */
+    model;
+    /**
+     * Parâmetros escalares da chave de cache (ADR-004). Vazio no auto-detect; com
+     * idioma forçado (#62), `{ language }` — trocar o idioma gera chave distinta.
+     */
+    params;
+    binaryPath;
+    modelPath;
+    /** Idioma forçado (#62), ou `undefined` = auto-detect. */
+    language;
+    run;
+    timeoutMs;
+    killGraceMs;
+    /**
+     * @param options - Ver {@link WhisperExtractorOptions}.
+     */
+    constructor(options) {
+        this.version = options.version;
+        this.binaryPath = options.binaryPath;
+        this.modelPath = options.modelPath;
+        // O `model` da chave reflete o GGUF REAL em uso (basename do modelPath); assim
+        // trocar de modelo invalida a chave attachment-level (ADR-004, #72). Sem
+        // modelPath (modelo ausente), usa o nome pinado como rótulo estável.
+        this.model = options.modelPath !== undefined ? basename(options.modelPath) : EXTRACTOR_MODEL;
+        this.language = options.language;
+        // Idioma forçado entra no params da chave; auto-detect mantém params vazio (sem
+        // injetar `undefined` — respeita `exactOptionalPropertyTypes`).
+        this.params = options.language !== undefined ? { language: options.language } : {};
+        this.run = options.run ?? defaultRun;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+    }
+    /**
+     * Configuração do extrator pronta para {@link buildAttachmentKey} (ADR-004).
+     * @returns `{ version, model, params }` estáveis desta instância.
+     */
+    get extractorConfig() {
+        return { version: this.version, model: this.model, params: this.params };
+    }
+    /**
+     * Transcreve o WAV em `filePath`. Nunca lança: falhas (binário ausente, modelo
+     * GGUF ausente, timeout, erro de execução) viram `{ status: 'failed',
+     * metadata.reason }` — degradação graciosa (ADR-002).
+     *
+     * @param filePath - Caminho absoluto do WAV (ou áudio) a transcrever.
+     * @param options - MIME real + logger — ver {@link ExtractOptions}.
+     * @returns `done` com `text` no sucesso; `failed` com motivo claro na falha.
+     */
+    async extract(filePath, options) {
+        const bin = this.binaryPath;
+        if (bin === undefined) {
+            options.logger?.warn('whisper: binário não encontrado no PATH nem em locais convencionais; ' +
+                'instale o whisper.cpp (ex.: `brew install whisper-cpp`) — veja o doctor');
+            return this.failed(options.mime, 'whisper-nao-instalado', {
+                hint: 'instale o whisper.cpp (whisper-cli/whisper-cpp); o doctor (#57) valida a instalação',
+            });
+        }
+        const model = this.modelPath;
+        if (model === undefined) {
+            options.logger?.warn('whisper: modelo GGUF não encontrado no cache; ' +
+                'baixe o modelo (ex.: `--download-binaries`) — veja o doctor');
+            return this.failed(options.mime, 'modelo-nao-encontrado', {
+                hint: 'o modelo GGUF do whisper.cpp não está no cache; o doctor (#57) orienta o download',
+            });
+        }
+        try {
+            const stdout = await this.run({
+                bin,
+                args: buildWhisperArgs(model, filePath, this.language),
+                env: sanitizedEnv(),
+                timeoutMs: this.timeoutMs,
+                killGraceMs: this.killGraceMs,
+                // Cancelamento (#69/#73): repassa o signal do dispatch até o watchdog, que
+                // MATA o whisper ao abortar. Só inclui quando dado (exactOptionalPropertyTypes).
+                ...(options.signal !== undefined ? { signal: options.signal } : {}),
+            });
+            return {
+                status: 'done',
+                text: parseWhisperOutput(stdout),
+                mime: options.mime,
+                // Reason (#62): model + params (incl. idioma) são persistidos no
+                // extraction.json — registram a identidade da extração produzida.
+                metadata: {
+                    extractorId: this.id,
+                    version: this.version,
+                    model: this.model,
+                    params: this.params,
+                },
+            };
+        }
+        catch (error) {
+            return this.failed(options.mime, isTimeoutError(error) ? 'timeout' : 'erro-transcricao', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * Monta um `ExtractionResult` `failed` com metadados de diagnóstico, sem injetar
+     * chaves `undefined` (respeita `exactOptionalPropertyTypes`).
+     *
+     * @param mime - MIME real detectado (do dispatcher).
+     * @param reason - Motivo canônico da falha.
+     * @param extra - Metadados adicionais (hint/erro).
+     * @returns Resultado `failed` tipado.
+     */
+    failed(mime, reason, extra) {
+        return {
+            status: 'failed',
+            mime,
+            metadata: { extractorId: this.id, version: this.version, reason, ...extra },
+        };
+    }
+}
+/**
+ * Resolve o caminho default do modelo GGUF no cache — {@link whisperModelDir} +
+ * {@link GGUF_MODEL_NAME} — retornando-o só se o arquivo existir.
+ *
+ * @returns O caminho absoluto do modelo, ou `undefined` se ausente do cache.
+ */
+function defaultFindModel() {
+    const modelPath = join(whisperModelDir(), GGUF_MODEL_NAME);
+    return existsSync(modelPath) ? modelPath : undefined;
+}
+/**
+ * Cria um {@link WhisperExtractor} resolvendo binário e modelo GGUF. Localiza o
+ * whisper.cpp ({@link findWhisper}) e o modelo no cache; ambos ausentes fazem o
+ * extrator degradar graciosamente em `extract` (ADR-002), sem lançar aqui.
+ *
+ * @param options - Localizadores/executor/timeouts injetáveis — ver {@link CreateWhisperExtractorOptions}.
+ * @returns O extrator pronto para registro no {@link ExtractorRegistry}.
+ * @example
+ * const extractor = await createWhisperExtractor();
+ */
+export function createWhisperExtractor(options = {}) {
+    const findBinary = options.findBinary ?? (() => findWhisper()?.path);
+    const findModel = options.findModel ?? defaultFindModel;
+    const extractor = new WhisperExtractor({
+        binaryPath: findBinary(),
+        modelPath: findModel(),
+        version: INTEGRATION_VERSION,
+        ...(options.language !== undefined ? { language: options.language } : {}),
+        ...(options.run !== undefined ? { run: options.run } : {}),
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(options.killGraceMs !== undefined ? { killGraceMs: options.killGraceMs } : {}),
+    });
+    return Promise.resolve(extractor);
+}