redmine-context 1.0.0

package/dist/extract/duration.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Sonda de DURAÇÃO de vídeo via `ffprobe` (M4-09, #65, ADR-002).
+ *
+ * Mede a duração de um vídeo ANTES de convertê-lo/transcrevê-lo, para que o
+ * pipeline ({@link extractVideoTranscript}) possa PULAR com aviso os vídeos que
+ * excedem o limite configurável (default 20 min, ADR-002) — sem gastar CPU na
+ * conversão/transcrição de mídia longa.
+ *
+ * Extraído de `video.ts` para manter cada módulo sob o limite de tamanho e com um
+ * propósito único (Rule #24): aqui vive SÓ a sondagem de duração; a orquestração
+ * (skip + preservação do keyframe) permanece em `video.ts`.
+ *
+ * DECISÕES DE SEGURANÇA/ROBUSTEZ (ADR-002), como no restante da milestone:
+ * - INVOCAÇÃO SEM SHELL: reusa {@link runWithWatchdog} (`execFile`), lista de args
+ *   explícita — o `inputPath` NUNCA é interpolado numa string de shell.
+ * - `-protocol_whitelist file`: o ffprobe só pode abrir o arquivo local dado, nunca
+ *   protocolos remotos embutidos em playlists/manifests hostis.
+ * - ENV SANITIZADO: só `PATH` — segredos do processo pai não vazam para o ffprobe.
+ * - TIMEOUT + KILL: watchdog `SIGTERM`→ graça →`SIGKILL`.
+ * - DEGRADAÇÃO GRACIOSA: ffprobe ausente, exit != 0, timeout ou saída não-parseável
+ *   NÃO lançam; devolvem `{ status: 'unavailable', reason }` — o chamador decide o
+ *   comportamento seguro (o pipeline PROSSEGUE, não bloqueia).
+ *
+ * Fronteira: módulo de core (pipeline de extração) — sem `console.*` (ADR-005).
+ */
+import type { Logger } from '../client/index.js';
+/** Invocação concreta do `ffprobe` passada ao {@link FfprobeRunner}. */
+export interface FfprobeInvocation {
+    /** Caminho absoluto do binário `ffprobe` já resolvido. */
+    readonly bin: string;
+    /** Argumentos do ffprobe (sem shell), incluindo `-protocol_whitelist file`. */
+    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;
+}
+/**
+ * Executor injetável do subprocesso ffprobe. Resolve com o `stdout` (a duração
+ * crua) no sucesso (exit 0); rejeita em falha — com um erro de nome
+ * `FfprobeTimeoutError` para sinalizar estouro de timeout.
+ */
+export type FfprobeRunner = (invocation: FfprobeInvocation) => Promise<string>;
+/** Sonda de duração bem-sucedida: duração do container em segundos. */
+export interface DurationProbeOk {
+    readonly status: 'ok';
+    /** Duração total do vídeo em segundos (float), como reportada pelo ffprobe. */
+    readonly seconds: number;
+}
+/**
+ * Sonda de duração INDISPONÍVEL (graciosa, ADR-002): o ffprobe está ausente, falhou,
+ * estourou o timeout ou devolveu uma duração não-parseável. O chamador decide o
+ * comportamento seguro — o pipeline PROSSEGUE sem bloquear (ver {@link extractVideoTranscript}).
+ */
+export interface DurationProbeUnavailable {
+    readonly status: 'unavailable';
+    /** Motivo canônico (`ffprobe-nao-instalado` | `duracao-indisponivel` | `erro-ffprobe` | `timeout`). */
+    readonly reason: string;
+    /** Mensagem de erro subjacente, quando houver. */
+    readonly error?: string;
+}
+/** Resultado tipado da sonda de duração via ffprobe. */
+export type DurationProbeResult = DurationProbeOk | DurationProbeUnavailable;
+/** Opções (todas injetáveis para testes herméticos) de {@link probeVideoDuration}. */
+export interface ProbeVideoDurationOptions {
+    /** Localizador do `ffprobe`; default {@link findFfprobe}. */
+    readonly findFfprobeBinary?: () => string | undefined;
+    /** Executor do subprocesso; default: watchdog real com `execFile`. */
+    readonly run?: FfprobeRunner;
+    /** Timeout antes do `SIGTERM` (ms); default {@link DEFAULT_PROBE_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+    /** Graça `SIGTERM` → `SIGKILL` (ms); default {@link PROBE_KILL_GRACE_MS}. */
+    readonly killGraceMs?: number;
+    /** Logger para o aviso de binário ausente; sem default de lib (ADR-003). */
+    readonly logger?: Logger;
+}
+/**
+ * Parseia a duração (segundos, float) da saída crua do `ffprobe`. Devolve
+ * `undefined` para saída vazia, `N/A`, não-numérica ou negativa — sinal de que a
+ * duração é INDISPONÍVEL (não presumimos zero nem crashamos).
+ *
+ * @param stdout - Saída crua do ffprobe (`format=duration`, uma linha).
+ * @returns A duração em segundos, ou `undefined` se não parseável.
+ * @example
+ * parseFfprobeDuration('123.45\n'); // 123.45
+ * parseFfprobeDuration('N/A');      // undefined
+ */
+export declare function parseFfprobeDuration(stdout: string): number | undefined;
+/**
+ * Mede a duração de um vídeo via `ffprobe` ANTES de convertê-lo/transcrevê-lo
+ * (M4-09, #65). REUSA o subprocesso seguro compartilhado (sem shell,
+ * `-protocol_whitelist file`, env sanitizado, watchdog `SIGTERM`→`SIGKILL`). NUNCA
+ * lança (degradação graciosa, ADR-002): ffprobe ausente, exit != 0, timeout ou
+ * saída não-parseável viram `{ status: 'unavailable', reason }` — cabe ao chamador
+ * decidir o comportamento seguro (o pipeline PROSSEGUE quando a duração é indisponível).
+ *
+ * @param inputPath - Caminho absoluto do vídeo já baixado no cache.
+ * @param options - Deps injetáveis + timeouts + logger — ver {@link ProbeVideoDurationOptions}.
+ * @returns `ok` com `seconds` no sucesso; `unavailable` com motivo caso contrário.
+ * @example
+ * const probe = await probeVideoDuration('/cache/att/clip.mp4');
+ * if (probe.status === 'ok' && probe.seconds > 1200) skipTranscription();
+ */
+export declare function probeVideoDuration(inputPath: string, options?: ProbeVideoDurationOptions): Promise<DurationProbeResult>;

package/dist/extract/duration.js

@@ -0,0 +1,148 @@
+/**
+ * Sonda de DURAÇÃO de vídeo via `ffprobe` (M4-09, #65, ADR-002).
+ *
+ * Mede a duração de um vídeo ANTES de convertê-lo/transcrevê-lo, para que o
+ * pipeline ({@link extractVideoTranscript}) possa PULAR com aviso os vídeos que
+ * excedem o limite configurável (default 20 min, ADR-002) — sem gastar CPU na
+ * conversão/transcrição de mídia longa.
+ *
+ * Extraído de `video.ts` para manter cada módulo sob o limite de tamanho e com um
+ * propósito único (Rule #24): aqui vive SÓ a sondagem de duração; a orquestração
+ * (skip + preservação do keyframe) permanece em `video.ts`.
+ *
+ * DECISÕES DE SEGURANÇA/ROBUSTEZ (ADR-002), como no restante da milestone:
+ * - INVOCAÇÃO SEM SHELL: reusa {@link runWithWatchdog} (`execFile`), lista de args
+ *   explícita — o `inputPath` NUNCA é interpolado numa string de shell.
+ * - `-protocol_whitelist file`: o ffprobe só pode abrir o arquivo local dado, nunca
+ *   protocolos remotos embutidos em playlists/manifests hostis.
+ * - ENV SANITIZADO: só `PATH` — segredos do processo pai não vazam para o ffprobe.
+ * - TIMEOUT + KILL: watchdog `SIGTERM`→ graça →`SIGKILL`.
+ * - DEGRADAÇÃO GRACIOSA: ffprobe ausente, exit != 0, timeout ou saída não-parseável
+ *   NÃO lançam; devolvem `{ status: 'unavailable', reason }` — o chamador decide o
+ *   comportamento seguro (o pipeline PROSSEGUE, não bloqueia).
+ *
+ * Fronteira: módulo de core (pipeline de extração) — sem `console.*` (ADR-005).
+ */
+import { findFfprobe } from './ffmpeg.js';
+import { runWithWatchdog, sanitizedEnv } from './subprocess.js';
+/** Timeout default da sonda `ffprobe` antes do `SIGTERM` (ms) — a leitura é rápida. */
+const DEFAULT_PROBE_TIMEOUT_MS = 15_000;
+/** Graça `SIGTERM` → `SIGKILL` da sonda `ffprobe` (ms). */
+const PROBE_KILL_GRACE_MS = 2_000;
+/** Teto do stdout/stderr do ffprobe (1 MiB) — a saída é uma única linha (a duração). */
+const PROBE_MAX_BUFFER_BYTES = 1024 * 1024;
+/** Erro interno: o watchdog matou o ffprobe por estourar o timeout. */
+class FfprobeTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`ffprobe excedeu o timeout de ${timeoutMs}ms e foi encerrado`);
+        this.timeoutMs = timeoutMs;
+        this.name = 'FfprobeTimeoutError';
+    }
+}
+/**
+ * Monta os argumentos do `ffprobe` para ler SÓ a duração do container em `inputPath`,
+ * como um número cru em segundos. `-protocol_whitelist file` precede o arquivo de
+ * entrada (ADR-002): o ffprobe só pode abrir o arquivo local dado, nunca protocolos
+ * remotos embutidos em playlists/manifests hostis. `-of default=nw=1:nk=1` imprime o
+ * valor sem chave nem cabeçalho de seção — só o número.
+ *
+ * @param inputPath - Caminho absoluto do vídeo de entrada.
+ * @returns Lista de argumentos, na ordem exigida pelo ffprobe.
+ */
+function buildFfprobeArgs(inputPath) {
+    return [
+        '-v',
+        'error', // silencioso, exceto erros
+        '-protocol_whitelist',
+        'file', // ADR-002: só o arquivo local dado, nada remoto
+        '-show_entries',
+        'format=duration', // só a duração do container
+        '-of',
+        'default=nw=1:nk=1', // saída crua: sem wrapper, sem chave
+        inputPath,
+    ];
+}
+/**
+ * Executor default da sonda: delega ao watchdog compartilhado
+ * ({@link runWithWatchdog}) — ffprobe SEM shell, env sanitizado e escalonamento
+ * `SIGTERM` → graça → `SIGKILL`. Diferente do ffmpeg, aqui o `stdout` IMPORTA (é a
+ * duração). O estouro de timeout é sinalizado com {@link FfprobeTimeoutError}.
+ *
+ * @param invocation - Ver {@link FfprobeInvocation}.
+ * @returns O `stdout` do ffprobe (a duração crua) no sucesso.
+ */
+function defaultProbeRun(invocation) {
+    const { bin, args, env, timeoutMs, killGraceMs } = invocation;
+    return runWithWatchdog({ bin, args, env, timeoutMs, killGraceMs, maxBuffer: PROBE_MAX_BUFFER_BYTES }, { makeTimeoutError: (ms) => new FfprobeTimeoutError(ms) });
+}
+/** `true` se o erro sinaliza estouro de timeout da sonda (por nome, robusto a DI). */
+function isProbeTimeout(error) {
+    return error instanceof Error && error.name === 'FfprobeTimeoutError';
+}
+/**
+ * Parseia a duração (segundos, float) da saída crua do `ffprobe`. Devolve
+ * `undefined` para saída vazia, `N/A`, não-numérica ou negativa — sinal de que a
+ * duração é INDISPONÍVEL (não presumimos zero nem crashamos).
+ *
+ * @param stdout - Saída crua do ffprobe (`format=duration`, uma linha).
+ * @returns A duração em segundos, ou `undefined` se não parseável.
+ * @example
+ * parseFfprobeDuration('123.45\n'); // 123.45
+ * parseFfprobeDuration('N/A');      // undefined
+ */
+export function parseFfprobeDuration(stdout) {
+    const trimmed = stdout.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    const seconds = Number.parseFloat(trimmed);
+    // Reason: `parseFloat('N/A')` → NaN; duração negativa é dado degenerado. Em ambos,
+    // tratamos como indisponível em vez de presumir um valor (degradação graciosa).
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return undefined;
+    return seconds;
+}
+/**
+ * Mede a duração de um vídeo via `ffprobe` ANTES de convertê-lo/transcrevê-lo
+ * (M4-09, #65). REUSA o subprocesso seguro compartilhado (sem shell,
+ * `-protocol_whitelist file`, env sanitizado, watchdog `SIGTERM`→`SIGKILL`). NUNCA
+ * lança (degradação graciosa, ADR-002): ffprobe ausente, exit != 0, timeout ou
+ * saída não-parseável viram `{ status: 'unavailable', reason }` — cabe ao chamador
+ * decidir o comportamento seguro (o pipeline PROSSEGUE quando a duração é indisponível).
+ *
+ * @param inputPath - Caminho absoluto do vídeo já baixado no cache.
+ * @param options - Deps injetáveis + timeouts + logger — ver {@link ProbeVideoDurationOptions}.
+ * @returns `ok` com `seconds` no sucesso; `unavailable` com motivo caso contrário.
+ * @example
+ * const probe = await probeVideoDuration('/cache/att/clip.mp4');
+ * if (probe.status === 'ok' && probe.seconds > 1200) skipTranscription();
+ */
+export async function probeVideoDuration(inputPath, options = {}) {
+    const findBinary = options.findFfprobeBinary ?? (() => findFfprobe()?.path);
+    const bin = findBinary();
+    if (bin === undefined) {
+        options.logger?.warn('ffprobe: binário não encontrado; a duração do vídeo não será medida ' +
+            '(a transcrição segue sem o limite de duração) — instale o ffmpeg/ffprobe (ver doctor)');
+        return { status: 'unavailable', reason: 'ffprobe-nao-instalado' };
+    }
+    const run = options.run ?? defaultProbeRun;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    const killGraceMs = options.killGraceMs ?? PROBE_KILL_GRACE_MS;
+    const args = buildFfprobeArgs(inputPath);
+    try {
+        const stdout = await run({ bin, args, env: sanitizedEnv(), timeoutMs, killGraceMs });
+        const seconds = parseFfprobeDuration(stdout);
+        if (seconds === undefined) {
+            return { status: 'unavailable', reason: 'duracao-indisponivel' };
+        }
+        return { status: 'ok', seconds };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            status: 'unavailable',
+            reason: isProbeTimeout(error) ? 'timeout' : 'erro-ffprobe',
+            error: message,
+        };
+    }
+}

package/dist/extract/ffmpeg.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Localização e versão do binário `ffmpeg` (M4-01, #57, ADR-002).
+ *
+ * O `doctor` (#57) usa estas funções para reportar a presença do ffmpeg — que a
+ * milestone M4 usará para extrair a faixa de áudio + 1 keyframe de vídeos (ADR-002)
+ * — sem reimplementar a detecção em cada superfície. Segue o padrão de
+ * {@link findTesseract}: PATH + locais convencionais (incl. `/opt/homebrew/bin`),
+ * puro e injetável, degradando graciosamente quando ausente.
+ */
+import { findExecutable } from './which.js';
+/** Resultado de {@link findFfmpeg}: caminho absoluto do binário localizado. */
+export interface FfmpegLocation {
+    /** Caminho absoluto do executável `ffmpeg` encontrado. */
+    readonly path: string;
+}
+/**
+ * Localiza o binário `ffmpeg` no `PATH` e em locais convencionais por plataforma.
+ * Função pura 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, ou `undefined` se não instalado.
+ * @example
+ * const found = findFfmpeg();
+ * if (found === undefined) logger.warn('ffmpeg não instalado');
+ */
+export declare function findFfmpeg(deps?: Parameters<typeof findExecutable>[2]): FfmpegLocation | undefined;
+/** Resultado de {@link findFfprobe}: caminho absoluto do binário localizado. */
+export interface FfprobeLocation {
+    /** Caminho absoluto do executável `ffprobe` encontrado. */
+    readonly path: string;
+}
+/**
+ * Localiza o binário `ffprobe` no `PATH` e em locais convencionais por plataforma
+ * (os mesmos do ffmpeg — o ffprobe vem no MESMO pacote). Função pura e injetável;
+ * não executa o binário. Degrada para `undefined` quando ausente (ADR-002): sem
+ * ffprobe, a #65 não bloqueia — apenas não mede a duração.
+ *
+ * @param deps - Deps injetáveis (plataforma/PATH/executabilidade) — ver
+ *   {@link findExecutable}. Default: ambiente real.
+ * @returns A localização encontrada, ou `undefined` se não instalado.
+ * @example
+ * const probe = findFfprobe();
+ * if (probe === undefined) logger.warn('ffprobe não instalado; duração não medida');
+ */
+export declare function findFfprobe(deps?: Parameters<typeof findExecutable>[2]): FfprobeLocation | undefined;
+/**
+ * Lê a versão do binário via `ffmpeg -version` (primeira linha:
+ * `ffmpeg version X.Y.Z ...` — em builds distro pode vir `n6.1.1` ou hash git;
+ * capturamos o primeiro token após `version`). Não lança: retorna `undefined`
+ * se o binário falhar ou a saída for inesperada.
+ *
+ * @param bin - Caminho absoluto do binário.
+ * @returns A versão detectada (ex.: `6.1.1`), ou `undefined`.
+ */
+export declare function detectFfmpegVersion(bin: string): Promise<string | undefined>;

package/dist/extract/ffmpeg.js

@@ -0,0 +1,95 @@
+/**
+ * Localização e versão do binário `ffmpeg` (M4-01, #57, ADR-002).
+ *
+ * O `doctor` (#57) usa estas funções para reportar a presença do ffmpeg — que a
+ * milestone M4 usará para extrair a faixa de áudio + 1 keyframe de vídeos (ADR-002)
+ * — sem reimplementar a detecção em cada superfície. Segue o padrão de
+ * {@link findTesseract}: PATH + locais convencionais (incl. `/opt/homebrew/bin`),
+ * puro e injetável, degradando graciosamente quando ausente.
+ */
+import { execFile } from 'node:child_process';
+import { findExecutable } from './which.js';
+/** Nome base do binário do ffmpeg. */
+const FFMPEG_BINARY = 'ffmpeg';
+/**
+ * Nome base do binário do `ffprobe` — a ferramenta de SONDA do pacote ffmpeg. É
+ * distribuída junto do ffmpeg (mesmo diretório/pacote em brew/apt/BtbN), por isso
+ * reusa os MESMOS locais convencionais ({@link CONVENTIONAL}). Usada pela #65 para
+ * medir a duração de um vídeo ANTES de transcrevê-lo (limite configurável, ADR-002).
+ */
+const FFPROBE_BINARY = 'ffprobe';
+/**
+ * Locais convencionais do `ffmpeg` por família de SO, consultados após o `PATH`.
+ * No Windows não há caminho canônico (builds estáticos BtbN são descompactados
+ * em qualquer lugar) — cobrimos os destinos mais comuns como best-effort.
+ */
+const CONVENTIONAL = {
+    unix: ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin'],
+    windows: ['C:\\ffmpeg\\bin', 'C:\\Program Files\\ffmpeg\\bin'],
+};
+/** Graça de timeout ao ler a versão do ffmpeg (ms) — a chamada é instantânea. */
+const VERSION_TIMEOUT_MS = 2_000;
+/**
+ * Localiza o binário `ffmpeg` no `PATH` e em locais convencionais por plataforma.
+ * Função pura 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, ou `undefined` se não instalado.
+ * @example
+ * const found = findFfmpeg();
+ * if (found === undefined) logger.warn('ffmpeg não instalado');
+ */
+export function findFfmpeg(deps) {
+    const located = findExecutable([FFMPEG_BINARY], CONVENTIONAL, deps);
+    return located !== undefined ? { path: located.path } : undefined;
+}
+/**
+ * Localiza o binário `ffprobe` no `PATH` e em locais convencionais por plataforma
+ * (os mesmos do ffmpeg — o ffprobe vem no MESMO pacote). Função pura e injetável;
+ * não executa o binário. Degrada para `undefined` quando ausente (ADR-002): sem
+ * ffprobe, a #65 não bloqueia — apenas não mede a duração.
+ *
+ * @param deps - Deps injetáveis (plataforma/PATH/executabilidade) — ver
+ *   {@link findExecutable}. Default: ambiente real.
+ * @returns A localização encontrada, ou `undefined` se não instalado.
+ * @example
+ * const probe = findFfprobe();
+ * if (probe === undefined) logger.warn('ffprobe não instalado; duração não medida');
+ */
+export function findFfprobe(deps) {
+    const located = findExecutable([FFPROBE_BINARY], CONVENTIONAL, deps);
+    return located !== undefined ? { path: located.path } : undefined;
+}
+/**
+ * Monta o env MÍNIMO do subprocesso: só `PATH`. Nenhum segredo do pai (ex.:
+ * `REDMINE_API_KEY`) vaza para o ffmpeg (ADR-002).
+ *
+ * @returns Env sanitizado para o subprocesso.
+ */
+function sanitizedEnv() {
+    return { PATH: process.env.PATH ?? '/usr/bin:/bin' };
+}
+/**
+ * Lê a versão do binário via `ffmpeg -version` (primeira linha:
+ * `ffmpeg version X.Y.Z ...` — em builds distro pode vir `n6.1.1` ou hash git;
+ * capturamos o primeiro token após `version`). Não lança: retorna `undefined`
+ * se o binário falhar ou a saída for inesperada.
+ *
+ * @param bin - Caminho absoluto do binário.
+ * @returns A versão detectada (ex.: `6.1.1`), ou `undefined`.
+ */
+export function detectFfmpegVersion(bin) {
+    return new Promise((resolve) => {
+        execFile(bin, ['-version'], { env: sanitizedEnv(), encoding: 'utf8', windowsHide: true, timeout: VERSION_TIMEOUT_MS }, (error, stdout) => {
+            if (error !== null) {
+                resolve(undefined);
+                return;
+            }
+            // Reason: 1ª linha "ffmpeg version <token> ..."; o token pode ser semver
+            // puro, prefixado (`n6.1`) ou um hash — reportamos o token cru como veio.
+            const match = /ffmpeg version (\S+)/i.exec(stdout);
+            resolve(match?.[1]);
+        });
+    });
+}

package/dist/extract/gguf.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare const GGUF_MODEL_NAME: "ggml-tiny.bin";
+/** URL HTTPS oficial e fixa do {@link GGUF_MODEL_NAME} (Hugging Face resolve). */
+export declare 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 declare const GGUF_MODEL_SHA256: "be07e048e1e599ad46341c8d2a135645097a538221678b7acdd1b1919c6e1b21";
+/** Categorias de falha do download — discriminante acionável do {@link GgufDownloadError}. */
+export type GgufDownloadFailure = 'headless' | 'insecure-url' | 'http-error' | 'checksum-mismatch';
+/**
+ * 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 declare class GgufDownloadError extends Error {
+    /** Categoria da falha — ver {@link GgufDownloadFailure}. */
+    readonly code: GgufDownloadFailure;
+    constructor(code: GgufDownloadFailure, message: string);
+}
+/** Opções de rede repassadas ao `fetch` — hoje apenas cabeçalhos (ex.: `Range`). */
+export interface GgufFetchInit {
+    /** Cabeçalhos HTTP a enviar (ex.: `{ Range: 'bytes=1024-' }`). */
+    readonly headers?: Record<string, string>;
+}
+/**
+ * Dependências injetáveis de efeito colateral (rede + filesystem). O default
+ * ({@link defaultGgufDeps}) usa `fetch` global e `node:fs/promises`; os testes
+ * injetam spies para permanecerem herméticos.
+ */
+export interface GgufDeps {
+    /**
+     * Busca a URL (com cabeçalhos opcionais, ex.: `Range`) e devolve a resposta —
+     * wrapper fino sobre o `fetch` global.
+     */
+    readonly fetch: (url: string, init?: GgufFetchInit) => Promise<Response>;
+    /** Cria o diretório de destino recursivamente (idempotente). */
+    readonly mkdir: (dir: string) => Promise<void>;
+    /** Grava (truncando) os bytes baixados num caminho (o `.part`) — download novo. */
+    readonly writeFile: (path: string, data: Uint8Array) => Promise<void>;
+    /** ANEXA bytes ao fim do `.part` existente — usado na retomada via Range. */
+    readonly appendFile: (path: string, data: Uint8Array) => Promise<void>;
+    /** Lê o conteúdo atual do `.part` (para compor o checksum do arquivo completo). */
+    readonly readPart: (path: string) => Promise<Uint8Array>;
+    /**
+     * Tamanho, em bytes, de um `.part` já existente; `undefined` se ele não existe —
+     * é o ponto de retomada (`Range: bytes=<tamanho>-`).
+     */
+    readonly statPart: (path: string) => Promise<number | undefined>;
+    /** Renomeia o `.part` verificado para o destino final. */
+    readonly rename: (from: string, to: string) => Promise<void>;
+    /** Remove um caminho (o `.part` descartado), sem lançar se ausente. */
+    readonly rm: (path: string) => Promise<void>;
+}
+/** Opções de {@link downloadGgufModel}. Tudo tem default seguro para produção. */
+export interface DownloadGgufOptions {
+    /** Diretório de destino do modelo. Default: {@link whisperModelDir}. */
+    readonly destDir?: string;
+    /**
+     * Indica ambiente MCP/headless. Quando `true`, o download é RECUSADO (opt-in
+     * interativo, ADR-002). Default: `false`.
+     */
+    readonly headless?: boolean;
+    /** URL de origem (HTTPS). Default: {@link GGUF_MODEL_URL}. */
+    readonly url?: string;
+    /** SHA-256 hex esperado. Default: {@link GGUF_MODEL_SHA256}. */
+    readonly sha256?: string;
+    /** Dependências injetáveis (fetch/fs). Default: {@link defaultGgufDeps}. */
+    readonly deps?: GgufDeps;
+}
+/**
+ * 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 declare function defaultGgufDeps(): GgufDeps;
+/**
+ * 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 declare function downloadGgufModel(options?: DownloadGgufOptions): Promise<string>;