@hed-hog/core 0.0.399 → 0.0.400

package/src/file/filename-encoding.util.ts

@@ -0,0 +1,67 @@
+/**
+ * Nome de arquivo que chegou com o encoding trocado ("mojibake").
+ *
+ * O caso clássico é o byte a byte de UTF-8 lido como Latin-1: "Introdução" vira
+ * "Introdução". O multipart (busboy) entrega `originalname` assim, e a base
+ * ainda carrega nomes importados com o mesmo defeito — inclusive em duas camadas,
+ * quando o nome já quebrado passou pela conversão de novo ("IntroduÃ\u0083§Ã\u0083£o").
+ *
+ * A migration `20261103000000_core_fix_mojibake_filenames` reproduz esta mesma
+ * lógica em plpgsql para consertar o que já está gravado; mudanças aqui e lá
+ * andam juntas.
+ */
+
+/** Quantas camadas de conversão desfazer antes de desistir. */
+const MAX_DECODE_PASSES = 3;
+
+/**
+ * Marca de nome quebrado. `Ã`/`Â` seguidos de qualquer coisa é o rastro do byte
+ * de continuação lido como caractere; `â` seguido de um byte alto é o começo de
+ * um caractere de 3 bytes (travessão, aspas curvas) quebrado do mesmo jeito.
+ */
+const MOJIBAKE_PATTERN = /Ã.|Â.|â[\u0080-\u00BF]/;
+
+export function hasMojibake(value: string): boolean {
+  return MOJIBAKE_PATTERN.test(value);
+}
+
+/**
+ * Desfaz as camadas de mojibake de `value`, ou devolve o original quando não dá
+ * para desfazer com segurança.
+ *
+ * Só aceita o resultado de uma passada se ele for UTF-8 válido: é isso que
+ * protege o nome legítimo que casa o padrão por acaso. "MANUTENÇÃO.pdf" tem
+ * "ÃO", mas os bytes Latin-1 correspondentes (`C7 C3 4F`) não formam UTF-8, o
+ * `Buffer` devolve `U+FFFD` e o nome sai intacto.
+ */
+export function fixMojibake(value: string): string {
+  if (!value || !hasMojibake(value)) {
+    return value;
+  }
+
+  let current = value;
+
+  for (let pass = 0; pass < MAX_DECODE_PASSES; pass += 1) {
+    let decoded: string;
+    try {
+      decoded = Buffer.from(current, 'latin1').toString('utf8');
+    } catch {
+      break;
+    }
+
+    // `\uFFFD` é o que o decoder põe no lugar de byte inválido: o palpite estava
+    // errado e a passada anterior é o melhor que temos.
+    if (decoded === current || decoded.includes('\uFFFD')) {
+      break;
+    }
+
+    current = decoded;
+
+    if (!hasMojibake(current)) {
+      return current;
+    }
+  }
+
+  // Nenhuma passada chegou a um nome limpo: na dúvida, não estraga o que existe.
+  return hasMojibake(current) ? value : current;
+}

package/src/file/image-optimization.service.spec.ts

@@ -20,16 +20,25 @@ import { ImageOptimizationService } from './image-optimization.service';
 
 const mockSharp = sharp as unknown as jest.Mock & { __instance: any };
 
-const DEFAULT_SETTINGS: Record<string, string | undefined> = {
-  'image-compression-enabled': 'false',
+// O `SettingService` real converte o valor pelo `type` da setting antes de devolver:
+// `boolean` vira boolean, `array` vira array JS. O mock precisa refletir isso, senão o
+// spec valida um contrato que não existe — foi exatamente assim que a leitura por
+// string passou despercebida e deixou compressão e WebP desligados em produção.
+const DEFAULT_SETTINGS: Record<string, unknown> = {
+  'image-compression-enabled': false,
   'image-compression-quality': undefined,
   'image-compression-types': undefined,
-  'image-webp-conversion-enabled': 'false',
+  'image-webp-conversion-enabled': false,
   'image-webp-convert-types': undefined,
   'image-max-dimension': undefined,
 };
 
-const makeService = (settings: Record<string, string | undefined> = {}) => {
+// Entrada grande o bastante para que qualquer saída simulada conte como ganho: o
+// serviço recusa um resultado que não ficou menor, então um buffer de 3 bytes como
+// entrada faria todo teste cair no fallback para o original.
+const INPUT = Buffer.alloc(4096, 1);
+
+const makeService = (settings: Record<string, unknown> = {}) => {
   const merged = { ...DEFAULT_SETTINGS, ...settings };
   const settingService = {
     getSettingValues: jest.fn(async () => merged),
@@ -135,12 +144,64 @@ describe('ImageOptimizationService', () => {
 
     it('retorna o original quando não há resize, compressão nem conversão', async () => {
       const { service } = makeService();
-      const buffer = Buffer.from('img');
+      const buffer = INPUT;
       const result = await service.optimizeBuffer(buffer, 'image/jpeg', 'a.jpg');
       expect(result).toEqual({ buffer, mimetype: 'image/jpeg', originalname: 'a.jpg' });
       expect(mockSharp).not.toHaveBeenCalled();
     });
 
+    // Regressão: o SettingService devolve boolean e array já convertidos pelo `type` da
+    // setting. Ler isso como string desligava compressão e WebP mesmo com os toggles
+    // ligados na tela, e era o motivo de PNGs de vários MB serem gravados intactos.
+    it('converte para webp com as settings tipadas, como o SettingService entrega', async () => {
+      const { service } = makeService({
+        'image-webp-conversion-enabled': true,
+        'image-webp-convert-types': ['image/jpeg', 'image/png'],
+        'image-compression-quality': 80,
+      });
+      const out = Buffer.from('webp-bytes');
+      mockSharp.__instance.toBuffer.mockResolvedValue(out);
+
+      const result = await service.optimizeBuffer(INPUT, 'image/png', 'skill.png');
+
+      expect(result).toEqual({
+        buffer: out,
+        mimetype: 'image/webp',
+        originalname: 'skill.webp',
+      });
+      expect(mockSharp.__instance.webp).toHaveBeenCalledWith({ quality: 80 });
+    });
+
+    it('comprime com as settings tipadas quando a conversão para webp está desligada', async () => {
+      const { service } = makeService({
+        'image-compression-enabled': true,
+        'image-compression-types': ['image/jpeg'],
+        'image-compression-quality': 60,
+      });
+      const out = Buffer.from('jpeg-small');
+      mockSharp.__instance.toBuffer.mockResolvedValue(out);
+
+      const result = await service.optimizeBuffer(INPUT, 'image/jpeg', 'a.jpg');
+
+      expect(result).toEqual({ buffer: out, mimetype: 'image/jpeg', originalname: 'a.jpg' });
+      expect(mockSharp.__instance.jpeg).toHaveBeenCalledWith({ quality: 60 });
+    });
+
+    it('mantém o original quando o tipo tipado não está em nenhuma das listas', async () => {
+      const { service } = makeService({
+        'image-compression-enabled': true,
+        'image-compression-types': ['image/jpeg'],
+        'image-webp-conversion-enabled': true,
+        'image-webp-convert-types': ['image/jpeg'],
+      });
+      const buffer = Buffer.from('png-bytes');
+
+      const result = await service.optimizeBuffer(buffer, 'image/png', 'a.png');
+
+      expect(result).toEqual({ buffer, mimetype: 'image/png', originalname: 'a.png' });
+      expect(mockSharp).not.toHaveBeenCalled();
+    });
+
     it('converte para webp quando habilitado e o tipo está na lista', async () => {
       const { service } = makeService({
         'image-webp-conversion-enabled': 'true',
@@ -150,7 +211,7 @@ describe('ImageOptimizationService', () => {
       const out = Buffer.from('webp-bytes');
       mockSharp.__instance.toBuffer.mockResolvedValue(out);
 
-      const result = await service.optimizeBuffer(Buffer.from('img'), 'image/jpeg', 'photo.jpg');
+      const result = await service.optimizeBuffer(INPUT, 'image/jpeg', 'photo.jpg');
 
       expect(result).toEqual({
         buffer: out,
@@ -169,7 +230,7 @@ describe('ImageOptimizationService', () => {
       const out = Buffer.from('jpeg-small');
       mockSharp.__instance.toBuffer.mockResolvedValue(out);
 
-      const result = await service.optimizeBuffer(Buffer.from('img'), 'image/jpeg', 'a.jpg');
+      const result = await service.optimizeBuffer(INPUT, 'image/jpeg', 'a.jpg');
 
       expect(result).toEqual({ buffer: out, mimetype: 'image/jpeg', originalname: 'a.jpg' });
       expect(mockSharp.__instance.jpeg).toHaveBeenCalledWith({ quality: 60 });
@@ -184,7 +245,7 @@ describe('ImageOptimizationService', () => {
       const out = Buffer.from('png-small');
       mockSharp.__instance.toBuffer.mockResolvedValue(out);
 
-      const result = await service.optimizeBuffer(Buffer.from('img'), 'image/png', 'a.png');
+      const result = await service.optimizeBuffer(INPUT, 'image/png', 'a.png');
 
       expect(result.mimetype).toBe('image/png');
       // quality 80 -> compressionLevel 2
@@ -199,7 +260,7 @@ describe('ImageOptimizationService', () => {
       const out = Buffer.from('png-from-tiff');
       mockSharp.__instance.toBuffer.mockResolvedValue(out);
 
-      const result = await service.optimizeBuffer(Buffer.from('img'), 'image/tiff', 'scan.tiff');
+      const result = await service.optimizeBuffer(INPUT, 'image/tiff', 'scan.tiff');
 
       expect(result).toEqual({
         buffer: out,
@@ -213,7 +274,7 @@ describe('ImageOptimizationService', () => {
       const out = Buffer.from('resized');
       mockSharp.__instance.toBuffer.mockResolvedValue(out);
 
-      const result = await service.optimizeBuffer(Buffer.from('img'), 'image/jpeg', 'a.jpg');
+      const result = await service.optimizeBuffer(INPUT, 'image/jpeg', 'a.jpg');
 
       expect(mockSharp.__instance.resize).toHaveBeenCalledWith({
         width: 1024,
@@ -228,7 +289,7 @@ describe('ImageOptimizationService', () => {
       const { service } = makeService({ 'image-max-dimension': '1024' });
       mockSharp.__instance.toBuffer.mockResolvedValue(Buffer.from('cropped'));
 
-      await service.optimizeBuffer(Buffer.from('img'), 'image/jpeg', 'a.jpg', {
+      await service.optimizeBuffer(INPUT, 'image/jpeg', 'a.jpg', {
         maxWidth: 200,
         maxHeight: 100,
       });
@@ -245,13 +306,89 @@ describe('ImageOptimizationService', () => {
       const out = Buffer.from('reencoded');
       mockSharp.__instance.toBuffer.mockResolvedValue(out);
 
-      const result = await service.optimizeBuffer(Buffer.from('img'), 'image/gif', 'a.gif');
+      const result = await service.optimizeBuffer(INPUT, 'image/heic', 'a.heic');
 
-      expect(result).toEqual({ buffer: out, mimetype: 'image/gif', originalname: 'a.gif' });
+      expect(result).toEqual({ buffer: out, mimetype: 'image/heic', originalname: 'a.heic' });
       expect(mockSharp.__instance.jpeg).not.toHaveBeenCalled();
       expect(mockSharp.__instance.png).not.toHaveBeenCalled();
     });
 
+    it('não toca em SVG mesmo com max-dimension configurado (sharp não tem encoder de SVG)', async () => {
+      const { service } = makeService({ 'image-max-dimension': '500' });
+      const buffer = Buffer.from('<svg></svg>');
+
+      const result = await service.optimizeBuffer(buffer, 'image/svg+xml', 'logo.svg');
+
+      expect(result).toEqual({ buffer, mimetype: 'image/svg+xml', originalname: 'logo.svg' });
+      expect(mockSharp).not.toHaveBeenCalled();
+    });
+
+    it('não toca em GIF mesmo com max-dimension configurado (preserva a animação)', async () => {
+      const { service } = makeService({ 'image-max-dimension': '500' });
+      const buffer = Buffer.from('gif-bytes');
+
+      const result = await service.optimizeBuffer(buffer, 'image/gif', 'a.gif');
+
+      expect(result).toEqual({ buffer, mimetype: 'image/gif', originalname: 'a.gif' });
+      expect(mockSharp).not.toHaveBeenCalled();
+    });
+
+    // Recomprimir nem sempre encolhe: ilustração chapada e captura de tela com poucas
+    // cores costumam sair maiores em WebP com perda do que no PNG original. Gravar esse
+    // resultado inflaria justamente os arquivos que a feature deveria aliviar.
+    it('mantém o original quando o webp fica maior que a entrada', async () => {
+      const { service } = makeService({
+        'image-webp-conversion-enabled': true,
+        'image-webp-convert-types': ['image/png'],
+      });
+      const small = Buffer.alloc(64, 1);
+      mockSharp.__instance.toBuffer.mockResolvedValue(Buffer.alloc(4096, 2));
+
+      const result = await service.optimizeBuffer(small, 'image/png', 'flat-art.png');
+
+      expect(result).toEqual({
+        buffer: small,
+        mimetype: 'image/png',
+        originalname: 'flat-art.png',
+      });
+    });
+
+    it('mantém o original quando a recompressão no mesmo formato fica maior', async () => {
+      const { service } = makeService({
+        'image-compression-enabled': true,
+        'image-compression-types': ['image/jpeg'],
+      });
+      const small = Buffer.alloc(64, 1);
+      mockSharp.__instance.toBuffer.mockResolvedValue(Buffer.alloc(4096, 2));
+
+      const result = await service.optimizeBuffer(small, 'image/jpeg', 'a.jpg');
+
+      expect(result).toEqual({ buffer: small, mimetype: 'image/jpeg', originalname: 'a.jpg' });
+    });
+
+    // O recorte com dimensões exatas é a razão da chamada (capa de curso), não uma
+    // tentativa de encolher: devolver o original ali entregaria a proporção errada.
+    it('aceita resultado maior quando o alvo exato foi pedido (crop)', async () => {
+      const { service } = makeService({
+        'image-webp-conversion-enabled': true,
+        'image-webp-convert-types': ['image/png'],
+      });
+      const small = Buffer.alloc(64, 1);
+      const bigger = Buffer.alloc(4096, 2);
+      mockSharp.__instance.toBuffer.mockResolvedValue(bigger);
+
+      const result = await service.optimizeBuffer(small, 'image/png', 'banner.png', {
+        maxWidth: 1200,
+        maxHeight: 630,
+      });
+
+      expect(result).toEqual({
+        buffer: bigger,
+        mimetype: 'image/webp',
+        originalname: 'banner.webp',
+      });
+    });
+
     it('faz fallback para o original quando o sharp lança', async () => {
       const { service } = makeService({
         'image-compression-enabled': 'true',
@@ -261,7 +398,7 @@ describe('ImageOptimizationService', () => {
       const warnSpy = jest
         .spyOn((service as any).logger, 'warn')
         .mockImplementation(() => undefined);
-      const buffer = Buffer.from('img');
+      const buffer = INPUT;
 
       const result = await service.optimizeBuffer(buffer, 'image/jpeg', 'a.jpg');
 
@@ -277,7 +414,7 @@ describe('ImageOptimizationService', () => {
       });
       mockSharp.__instance.toBuffer.mockResolvedValue(Buffer.from('x'));
 
-      await service.optimizeBuffer(Buffer.from('img'), 'image/jpeg', 'a.jpg');
+      await service.optimizeBuffer(INPUT, 'image/jpeg', 'a.jpg');
 
       expect(mockSharp.__instance.jpeg).toHaveBeenCalledWith({ quality: 80 });
     });
@@ -289,7 +426,7 @@ describe('ImageOptimizationService', () => {
       mockSharp.__instance.webp.mockReturnValue(mockSharp.__instance);
       mockSharp.__instance.toBuffer.mockResolvedValue(Buffer.from('out'));
 
-      const result = await service.resizeBuffer(Buffer.from('img'), 'image/jpeg', {
+      const result = await service.resizeBuffer(INPUT, 'image/jpeg', {
         width: 640,
         format: 'webp',
         quality: 82,
@@ -312,7 +449,7 @@ describe('ImageOptimizationService', () => {
       const { service } = makeService();
       mockSharp.__instance.toBuffer.mockResolvedValue(Buffer.from('out'));
 
-      const result = await service.resizeBuffer(Buffer.from('img'), 'image/png', {
+      const result = await service.resizeBuffer(INPUT, 'image/png', {
         width: 320,
       });
 
@@ -352,7 +489,7 @@ describe('ImageOptimizationService', () => {
         .mockImplementation(() => undefined);
       mockSharp.__instance.toBuffer.mockRejectedValue(new Error('sharp boom'));
 
-      const result = await service.resizeBuffer(Buffer.from('img'), 'image/jpeg', {
+      const result = await service.resizeBuffer(INPUT, 'image/jpeg', {
         width: 640,
       });
 
@@ -364,7 +501,7 @@ describe('ImageOptimizationService', () => {
       const { service } = makeService();
       mockSharp.__instance.toBuffer.mockResolvedValue(Buffer.from('out'));
 
-      await service.resizeBuffer(Buffer.from('img'), 'image/jpeg', {
+      await service.resizeBuffer(INPUT, 'image/jpeg', {
         width: 640,
         quality: 0,
       });

package/src/file/image-optimization.service.ts

@@ -43,16 +43,36 @@ export class ImageOptimizationService {
     private readonly settingService: SettingService,
   ) {}
 
-  private parseArraySetting(raw: string | undefined): string[] {
-    if (!raw) return [];
+  /**
+   * `SettingService.getSettingValues` já converte o valor pelo `type` da setting: uma
+   * de tipo `array` chega aqui como array JS, não como a string do banco. Ler só a
+   * string fazia `JSON.parse` receber o array coagido para `"image/jpeg,image/png"`,
+   * lançar, e o catch devolver `[]` — o que desligava compressão e WebP em silêncio,
+   * por mais que os tipos estivessem marcados na tela. Aceitar as duas formas mantém
+   * o serviço utilizável por quem monta as settings à mão (specs, chamadores diretos).
+   */
+  private parseArraySetting(raw: unknown): string[] {
+    if (Array.isArray(raw)) {
+      return raw.map((item) => String(item));
+    }
+    if (typeof raw !== 'string' || !raw) return [];
     try {
       const parsed = JSON.parse(raw);
-      return Array.isArray(parsed) ? parsed : [];
+      return Array.isArray(parsed) ? parsed.map((item) => String(item)) : [];
     } catch {
       return [];
     }
   }
 
+  /**
+   * Mesmo motivo do `parseArraySetting`: uma setting `boolean` chega como `true`, e
+   * comparar com a string `'true'` dava sempre `false`. É a mesma leitura tolerante
+   * que o `OAuthService` já faz.
+   */
+  private parseBooleanSetting(raw: unknown): boolean {
+    return raw === true || raw === 'true';
+  }
+
   private replaceExtension(filename: string, newExt: string): string {
     const base = basename(filename, extname(filename));
     return `${base}.${newExt}`;
@@ -88,6 +108,29 @@ export class ImageOptimizationService {
     }
   }
 
+  /**
+   * Recusa um resultado que não ficou menor que a entrada.
+   *
+   * Recomprimir nem sempre encolhe: ilustração chapada e captura de tela com poucas
+   * cores são casos em que o PNG original já é menor do que qualquer WebP com perda, e
+   * gravar o resultado maior contraria o próprio motivo de a feature existir. Pior, o
+   * `reoptimizeFile` autoriza a troca só pela mudança de mimetype — sem esta guarda, a
+   * varredura do acervo poderia inflar justamente os arquivos que ela deveria aliviar.
+   *
+   * Não vale quando o chamador pediu dimensões exatas (`maxWidth` + `maxHeight`): ali o
+   * recorte é a razão da chamada, e devolver o original entregaria a proporção errada.
+   */
+  private keepSmaller(
+    original: OptimizedImage,
+    optimized: OptimizedImage,
+    isExactCrop: boolean,
+  ): OptimizedImage {
+    if (isExactCrop || optimized.buffer.length < original.buffer.length) {
+      return optimized;
+    }
+    return original;
+  }
+
   /**
    * Applies optional resize, compression and/or WebP conversion to the given
    * buffer based on the current settings. Returns the original data unchanged
@@ -104,6 +147,17 @@ export class ImageOptimizationService {
       return { buffer, mimetype, originalname };
     }
 
+    // Vectors must stay vectors, and resizing an animated GIF would flatten it to a
+    // single frame — same reasoning as resizeBuffer() below. Sharp also has no SVG
+    // encoder: falling through to the generic "unknown format" branch re-encodes the
+    // rasterized result as PNG bytes while this function kept reporting the original
+    // `image/svg+xml` mimetype, so the stored file ended up with a Content-Type that
+    // didn't match its actual bytes and every consumer (the settings preview, the
+    // dynamic favicon, <img> tags) rendered a broken image.
+    if (mimetype === 'image/svg+xml' || mimetype === 'image/gif') {
+      return { buffer, mimetype, originalname };
+    }
+
     const settings = await this.settingService.getSettingValues([
       'image-compression-enabled',
       'image-compression-quality',
@@ -113,8 +167,12 @@ export class ImageOptimizationService {
       'image-max-dimension',
     ]);
 
-    const compressionEnabled = settings['image-compression-enabled'] === 'true';
-    const webpEnabled = settings['image-webp-conversion-enabled'] === 'true';
+    const compressionEnabled = this.parseBooleanSetting(
+      settings['image-compression-enabled'],
+    );
+    const webpEnabled = this.parseBooleanSetting(
+      settings['image-webp-conversion-enabled'],
+    );
 
     const quality = Math.min(
       100,
@@ -149,6 +207,9 @@ export class ImageOptimizationService {
       return { buffer, mimetype, originalname };
     }
 
+    const original: OptimizedImage = { buffer, mimetype, originalname };
+    const isExactCrop = targetWidth > 0 && targetHeight > 0;
+
     try {
       let instance = sharp(buffer);
       if (resize) {
@@ -158,50 +219,74 @@ export class ImageOptimizationService {
       // WebP conversion has priority over plain compression.
       if (willConvertWebp) {
         const optimized = await instance.webp({ quality }).toBuffer();
-        return {
-          buffer: optimized,
-          mimetype: 'image/webp',
-          originalname: this.replaceExtension(originalname, 'webp'),
-        };
+        return this.keepSmaller(
+          original,
+          {
+            buffer: optimized,
+            mimetype: 'image/webp',
+            originalname: this.replaceExtension(originalname, 'webp'),
+          },
+          isExactCrop,
+        );
       }
 
       // Re-encode keeping the original format. Reached when compressing, or when
       // only resizing (a resize always requires re-encoding the buffer).
       if (mimetype === 'image/jpeg') {
         const optimized = await instance.jpeg({ quality }).toBuffer();
-        return { buffer: optimized, mimetype, originalname };
+        return this.keepSmaller(
+          original,
+          { buffer: optimized, mimetype, originalname },
+          isExactCrop,
+        );
       } else if (mimetype === 'image/png') {
         const optimized = await instance
           .png({ compressionLevel: this.pngCompressionLevel(quality) })
           .toBuffer();
-        return { buffer: optimized, mimetype, originalname };
+        return this.keepSmaller(
+          original,
+          { buffer: optimized, mimetype, originalname },
+          isExactCrop,
+        );
       } else if (mimetype === 'image/webp') {
         const optimized = await instance.webp({ quality }).toBuffer();
-        return { buffer: optimized, mimetype, originalname };
+        return this.keepSmaller(
+          original,
+          { buffer: optimized, mimetype, originalname },
+          isExactCrop,
+        );
       } else if (mimetype === 'image/bmp' || mimetype === 'image/tiff') {
         // Convert to PNG as a compressed lossless alternative.
         const optimized = await instance
           .png({ compressionLevel: this.pngCompressionLevel(quality) })
           .toBuffer();
-        return {
-          buffer: optimized,
-          mimetype: 'image/png',
-          originalname: this.replaceExtension(originalname, 'png'),
-        };
+        return this.keepSmaller(
+          original,
+          {
+            buffer: optimized,
+            mimetype: 'image/png',
+            originalname: this.replaceExtension(originalname, 'png'),
+          },
+          isExactCrop,
+        );
       }
 
       // Unknown image format: only re-encode if a resize was requested,
       // otherwise leave it untouched.
       if (resize) {
         const optimized = await instance.toBuffer();
-        return { buffer: optimized, mimetype, originalname };
+        return this.keepSmaller(
+          original,
+          { buffer: optimized, mimetype, originalname },
+          isExactCrop,
+        );
       }
-      return { buffer, mimetype, originalname };
+      return original;
     } catch (err) {
       this.logger.warn(
         `Image optimization failed for "${originalname}" (${mimetype}): ${err instanceof Error ? err.message : String(err)}. Falling back to original.`,
       );
-      return { buffer, mimetype, originalname };
+      return original;
     }
   }
 

package/src/file/mcp-file-source.schema.ts

@@ -0,0 +1,83 @@
+/**
+ * Fragmento de schema e texto de descrição que toda tool MCP que recebe arquivo espalha
+ * no seu `inputSchema`.
+ *
+ * Fica num lugar só porque é ele que o modelo lê para decidir o caminho: se cada tool
+ * descrevesse as modalidades com palavras próprias, o agente escolheria diferente em cada
+ * uma, e a mais barata (`fileId`) perderia para a mais cara (`fileBase64`) por acidente
+ * de redação.
+ */
+
+/** As quatro origens, em ordem de preferência. */
+export const FILE_SOURCE_FIELDS = [
+  'fileId',
+  'uploadId',
+  'fileUrl',
+  'fileBase64',
+] as const;
+
+export type FileSourceModality = (typeof FILE_SOURCE_FIELDS)[number];
+
+/**
+ * Propriedades para espalhar no `inputSchema` da tool.
+ *
+ * Nenhuma delas entra em `required`: a exigência é "exatamente uma", que JSON Schema
+ * expressaria com `oneOf` mas que nem todo cliente MCP avalia — a checagem de verdade
+ * está em `McpFileSourceService.detectModality`, e a descrição abaixo é o que faz o
+ * modelo acertar antes de chamar.
+ */
+export const FILE_SOURCE_SCHEMA_PROPERTIES: Record<string, any> = {
+  fileId: {
+    type: 'number',
+    description:
+      'Preferred. ID of a file already in storage (from core.files.list, an attachments list, or core.files.upload.complete). Must have been uploaded by the caller, unless the caller is an administrator.',
+  },
+  uploadId: {
+    type: 'number',
+    description:
+      'ID returned by core.files.create-upload-url or core.files.upload.init, after the binary has been uploaded. Use this to send a file that is on disk without putting its bytes in the conversation.',
+  },
+  fileUrl: {
+    type: 'string',
+    description:
+      'Public http(s) URL the server downloads by itself. Private, loopback, link-local and cloud metadata addresses are rejected, redirects are limited, and the content type is checked against the actual bytes.',
+  },
+  fileBase64: {
+    type: 'string',
+    description:
+      'Base64-encoded content, sent inline. Only for small files (about 256kb): base64 of anything larger overflows the model output limit. Requires fileName and mimeType.',
+  },
+  fileName: {
+    type: 'string',
+    description: 'Original file name. Required with fileBase64; optional with fileUrl.',
+  },
+  mimeType: {
+    type: 'string',
+    description:
+      'MIME type, e.g. application/pdf. Required with fileBase64; optional with fileUrl. Must be allowed by the storage-accept-mimetype setting, and is verified against the real content.',
+  },
+  sha256: {
+    type: 'string',
+    description:
+      'Optional hex sha256 of the file. When present, content that does not hash to it is rejected.',
+  },
+};
+
+/**
+ * Bloco anexado à descrição de cada tool.
+ *
+ * Diz o teto real — `storage-max-size`, 10 MB por padrão. A descrição antiga de
+ * `finance.titles.attachments.add` anunciava ~37 MB, número derivado do
+ * `api-body-size-limit`; ele nunca valeu, porque quem barra primeiro é o
+ * `storage-max-size`, e é ele que aparece na mensagem de erro.
+ */
+export const FILE_SOURCE_DESCRIPTION = [
+  'Exactly one file source is required: fileId, uploadId, fileUrl or fileBase64.',
+  'Prefer fileId; use fileBase64 only for files of a few hundred kilobytes, since the encoded content has to fit in a single tool call.',
+  'To send a local file without putting it in the conversation, call core.files.create-upload-url, PUT the binary to the URL it returns, call core.files.upload.complete, and pass the resulting fileId here.',
+  'Every path enforces the storage-accept-mimetype and storage-max-size settings (10mb by default).',
+].join(' ');
+
+/** Junta a descrição própria da tool com o bloco comum. */
+export const withFileSourceDescription = (description: string): string =>
+  `${description.trim()} ${FILE_SOURCE_DESCRIPTION}`;