redmine-context 1.0.0 → 1.2.0

package/dist/surfaces/mcp/server.d.ts

@@ -16,45 +16,9 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { type GetAttachmentTextArgs, type GetIssueContextArgs, type GetLastArgs, type SearchIssuesArgs } from './tools.js';
 import * as core from '../../index.js';
 import type { AttachmentTextResult, FetchAttachmentTextOptions, resolveApiKey } from '../../index.js';
-/** Formato aceito pela tool MCP (nomes amigáveis expostos ao cliente). */
-export type McpFormat = 'markdown' | 'json';
-/** Argumentos da tool `get_issue_context` já validados pelo schema zod. */
-export interface GetIssueContextArgs {
-    /** Identificador numérico da issue no Redmine. */
-    issue_id: number;
-    /** Formato de saída: `markdown` (padrão) ou `json`. */
-    format?: McpFormat | undefined;
-    /**
-     * Extrai o texto dos anexos de imagem (OCR) e o embute no bundle. Default:
-     * `false` — a extração adiciona latência (download + OCR por anexo). O M4 trará
-     * o modo cache-first/processing assíncrono; no M3 a extração é síncrona.
-     */
-    extract_attachments?: boolean | undefined;
-}
-/** Argumentos da tool `get_attachment_text` já validados pelo schema zod. */
-export interface GetAttachmentTextArgs {
-    /** Identificador numérico da issue que contém o anexo. */
-    issue_id: number;
-    /** Identificador numérico do anexo cujo texto será extraído. */
-    attachment_id: number;
-}
-/** Argumentos da tool `search_issues` já validados pelo schema zod. */
-export interface SearchIssuesArgs {
-    /** Termo full-text opcional (`/search.json`, best-effort). */
-    query?: string | undefined;
-    /** Filtro `project_id`. */
-    project_id?: number | undefined;
-    /** Filtro `status_id` (`'open'`, `'closed'`, `'*'` ou um id). */
-    status_id?: number | string | undefined;
-    /** Filtro `assigned_to_id` (um id ou `'me'`). */
-    assigned_to_id?: number | string | undefined;
-    /** Filtro `updated_on` no formato do Redmine (ex.: `>=2026-01-01`). */
-    updated_on?: string | undefined;
-    /** Máximo de resultados. Default: {@link SEARCH_DEFAULT_LIMIT}. */
-    limit?: number | undefined;
-}
 /**
  * Dependências injetáveis do server MCP — permitem testar o handler sem tocar o
  * processo real nem a rede. Os defaults (ver {@link defaultMcpDeps}) apontam para
@@ -65,6 +29,8 @@ export interface McpServerDeps {
     fetchIssueBundle: typeof core.fetchIssueBundle;
     /** Orquestração de busca (filtros + full-text best-effort) do core. */
     searchIssues: typeof core.fetchIssueSearch;
+    /** Orquestração das últimas issues (ordem + bundle completo) do core. */
+    fetchLastIssues: typeof core.fetchLastIssues;
     /**
      * Orquestração get → normalize → extração CACHE-FIRST de UM anexo (M4-11 #70):
      * devolve o texto já cacheado na hora e `processing` (sem bloquear) para mídia
@@ -95,14 +61,6 @@ export interface McpServerDeps {
     /** Sink de diagnóstico (progresso/erros) — SEMPRE stderr no stdio transport. */
     log?: (message: string) => void;
 }
-/** Nome canônico da tool de contexto de issue. */
-export declare const TOOL_NAME = "get_issue_context";
-/** Nome canônico da tool de busca de issues. */
-export declare const SEARCH_TOOL_NAME = "search_issues";
-/** Nome canônico da tool de texto de anexo. */
-export declare const ATTACHMENT_TOOL_NAME = "get_attachment_text";
-/** Limite default de resultados da tool `search_issues` (documentado no schema). */
-export declare const SEARCH_DEFAULT_LIMIT = 25;
 /**
  * Cria o handler da tool `get_issue_context`, testável isoladamente.
  *
@@ -132,6 +90,24 @@ export declare function createGetIssueContextHandler(deps: McpServerDeps): (args
  * const result = await handler({ query: 'timeout', project_id: 5 });
  */
 export declare function createSearchIssuesHandler(deps: McpServerDeps): (args: SearchIssuesArgs) => Promise<CallToolResult>;
+/**
+ * Cria o handler da tool `get_last`, testável isoladamente.
+ *
+ * Resolve a instância/credencial da env (nunca de argumentos) e delega à
+ * orquestração `fetchLastIssues`: ordena por `updated`/`created`/`priority` e
+ * devolve o BUNDLE COMPLETO das mais recentes — o atalho de um passo para
+ * "me dá a última issue", sem exigir que o cliente descubra o id antes.
+ *
+ * Usa `cacheFirst: true` como as demais tools: responde na hora com o texto de
+ * anexo já cacheado e marca o restante como `processing`, sem bloquear no OCR.
+ *
+ * @param deps - Ver {@link McpServerDeps}.
+ * @returns Função assíncrona que recebe os argumentos e devolve um CallToolResult.
+ * @example
+ * const handler = createGetLastHandler(defaultMcpDeps());
+ * const result = await handler({ order: 'priority', count: 3 });
+ */
+export declare function createGetLastHandler(deps: McpServerDeps): (args: GetLastArgs) => Promise<CallToolResult>;
 /**
  * Cria o handler da tool `get_attachment_text`, testável isoladamente.
  *
@@ -169,3 +145,4 @@ export declare function defaultMcpDeps(): McpServerDeps;
  * @returns Promise que resolve quando o transporte encerra.
  */
 export declare function runStdioServer(overrides?: Partial<McpServerDeps>): Promise<void>;
+export { ATTACHMENT_TOOL_NAME, LAST_TOOL_NAME, SEARCH_DEFAULT_LIMIT, SEARCH_TOOL_NAME, TOOL_NAME, type GetAttachmentTextArgs, type GetIssueContextArgs, type GetLastArgs, type McpFormat, type SearchIssuesArgs, } from './tools.js';

package/dist/surfaces/mcp/server.js

@@ -16,7 +16,7 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { z } from 'zod';
+import { ATTACHMENT_INPUT_SCHEMA, ATTACHMENT_TOOL_NAME, INPUT_SCHEMA, LAST_INPUT_SCHEMA, LAST_TOOL_NAME, SEARCH_DEFAULT_LIMIT, SEARCH_INPUT_SCHEMA, SEARCH_TOOL_NAME, TOOL_NAME, } from './tools.js';
 import * as core from '../../index.js';
 import { fenceBlock } from '../../index.js';
 /** Interpreta `REDMINE_INSECURE` (`1`/`true`, case-insensitive) como boolean. */
@@ -24,61 +24,6 @@ function parseInsecure(env) {
     const raw = env.REDMINE_INSECURE;
     return raw !== undefined && /^(1|true)$/i.test(raw.trim());
 }
-/** Nome canônico da tool de contexto de issue. */
-export const TOOL_NAME = 'get_issue_context';
-/** Nome canônico da tool de busca de issues. */
-export const SEARCH_TOOL_NAME = 'search_issues';
-/** Nome canônico da tool de texto de anexo. */
-export const ATTACHMENT_TOOL_NAME = 'get_attachment_text';
-/** Limite default de resultados da tool `search_issues` (documentado no schema). */
-export const SEARCH_DEFAULT_LIMIT = 25;
-/** Teto de resultados aceito pela tool `search_issues`. */
-const SEARCH_MAX_LIMIT = 100;
-/** Schema zod dos argumentos da tool (sem URL/host: a instância vem da env). */
-const INPUT_SCHEMA = {
-    issue_id: z.number().int().positive().describe('Identificador numérico da issue no Redmine'),
-    format: z
-        .enum(['markdown', 'json'])
-        .optional()
-        .describe("Formato de saída: 'markdown' (padrão) ou 'json'"),
-    extract_attachments: z
-        .boolean()
-        .optional()
-        .describe('Extrai o texto (OCR) dos anexos de imagem e o embute no bundle. Default: false (adiciona latência de download+OCR). O M4 traz o modo cache-first/processing.'),
-};
-/** Schema zod da tool `get_attachment_text` (read-only, sem URL/host). */
-const ATTACHMENT_INPUT_SCHEMA = {
-    issue_id: z.number().int().positive().describe('Identificador numérico da issue que contém o anexo'),
-    attachment_id: z.number().int().positive().describe('Identificador numérico do anexo a extrair'),
-};
-/** Schema zod da tool `search_issues` (read-only, sem URL/host). */
-const SEARCH_INPUT_SCHEMA = {
-    query: z
-        .string()
-        .min(1)
-        .optional()
-        .describe('Termo full-text via /search.json (best-effort). Se a busca falhar, degrada para os filtros estruturados com aviso.'),
-    project_id: z.number().int().positive().optional().describe('Filtro estruturado project_id'),
-    status_id: z
-        .union([z.number().int(), z.string()])
-        .optional()
-        .describe("Filtro status_id: um id, 'open', 'closed' ou '*'"),
-    assigned_to_id: z
-        .union([z.number().int(), z.string()])
-        .optional()
-        .describe("Filtro assigned_to_id: um id ou 'me'"),
-    updated_on: z
-        .string()
-        .optional()
-        .describe('Filtro updated_on no formato do Redmine (ex.: >=2026-01-01, <=2026-12-31)'),
-    limit: z
-        .number()
-        .int()
-        .positive()
-        .max(SEARCH_MAX_LIMIT)
-        .optional()
-        .describe(`Máximo de resultados paginados (default ${SEARCH_DEFAULT_LIMIT}, teto ${SEARCH_MAX_LIMIT})`),
-};
 /** Extrai uma mensagem legível de um erro desconhecido. */
 function messageOf(error) {
     return error instanceof Error ? error.message : String(error);
@@ -276,6 +221,60 @@ export function createSearchIssuesHandler(deps) {
         }
     };
 }
+/**
+ * Cria o handler da tool `get_last`, testável isoladamente.
+ *
+ * Resolve a instância/credencial da env (nunca de argumentos) e delega à
+ * orquestração `fetchLastIssues`: ordena por `updated`/`created`/`priority` e
+ * devolve o BUNDLE COMPLETO das mais recentes — o atalho de um passo para
+ * "me dá a última issue", sem exigir que o cliente descubra o id antes.
+ *
+ * Usa `cacheFirst: true` como as demais tools: responde na hora com o texto de
+ * anexo já cacheado e marca o restante como `processing`, sem bloquear no OCR.
+ *
+ * @param deps - Ver {@link McpServerDeps}.
+ * @returns Função assíncrona que recebe os argumentos e devolve um CallToolResult.
+ * @example
+ * const handler = createGetLastHandler(defaultMcpDeps());
+ * const result = await handler({ order: 'priority', count: 3 });
+ */
+export function createGetLastHandler(deps) {
+    return async (args) => {
+        const resolved = await resolveInstance(deps);
+        if (!isResolved(resolved))
+            return resolved;
+        const { baseUrl, apiKey } = resolved;
+        const format = args.format === 'json' ? 'json' : 'md';
+        try {
+            let content;
+            for await (const event of deps.fetchLastIssues({
+                baseUrl,
+                apiKey,
+                format,
+                order: args.order,
+                count: args.count,
+                toolVersion: deps.toolVersion,
+                insecure: deps.insecure ?? false,
+                extractAttachments: args.extract_attachments ?? false,
+                cacheFirst: true,
+            })) {
+                if (event.kind === 'progress') {
+                    deps.log?.(event.message);
+                }
+                else {
+                    content = event.value.content;
+                }
+            }
+            if (content === undefined) {
+                return errorResult('A operação não produziu um bundle.');
+            }
+            return textResult(content);
+        }
+        catch (error) {
+            return errorResult(typedSearchErrorMessage(error));
+        }
+    };
+}
 /**
  * Traduz erros da extração de anexo em mensagens claras e tipadas.
  *
@@ -370,6 +369,7 @@ export function createMcpServer(deps) {
     const handler = createGetIssueContextHandler(deps);
     const searchHandler = createSearchIssuesHandler(deps);
     const attachmentHandler = createGetAttachmentTextHandler(deps);
+    const lastHandler = createGetLastHandler(deps);
     server.registerTool(TOOL_NAME, {
         title: 'Contexto de issue do Redmine',
         description: 'Busca uma issue na instância Redmine configurada (REDMINE_URL) e retorna seu contexto completo empacotado. Read-only.',
@@ -388,6 +388,12 @@ export function createMcpServer(deps) {
         inputSchema: ATTACHMENT_INPUT_SCHEMA,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, (args) => attachmentHandler(args));
+    server.registerTool(LAST_TOOL_NAME, {
+        title: 'Últimas issues do Redmine',
+        description: 'Retorna o contexto completo das issues mais recentes da instância configurada (REDMINE_URL), ordenadas por updated (padrão), created ou priority. Atalho de um passo quando o id ainda não é conhecido — considera apenas issues abertas; use search_issues para filtros (projeto, status, responsável). Read-only.',
+        inputSchema: LAST_INPUT_SCHEMA,
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, (args) => lastHandler(args));
     return server;
 }
 /** Constrói as dependências default apontando para o core e o processo reais. */
@@ -395,6 +401,7 @@ export function defaultMcpDeps() {
     return {
         fetchIssueBundle: core.fetchIssueBundle,
         searchIssues: core.fetchIssueSearch,
+        fetchLastIssues: core.fetchLastIssues,
         fetchAttachmentText: core.fetchAttachmentTextCacheFirst,
         resolveApiKey: core.resolveApiKey,
         env: process.env,
@@ -425,3 +432,7 @@ export async function runStdioServer(overrides = {}) {
     });
 }
 /* c8 ignore stop */
+// Contrato de entrada das tools (nomes, tipos e schemas) — vive em `./tools.ts`
+// desde a extração da RULES #24. Reexportado aqui para que os consumidores
+// (CLI, testes) continuem tendo `./server.js` como porta única da superfície MCP.
+export { ATTACHMENT_TOOL_NAME, LAST_TOOL_NAME, SEARCH_DEFAULT_LIMIT, SEARCH_TOOL_NAME, TOOL_NAME, } from './tools.js';

package/dist/surfaces/mcp/tools.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Contrato de ENTRADA das tools MCP: nomes canônicos, tipos de argumentos e
+ * schemas zod.
+ *
+ * Extraído de `./server.ts` (RULES #24 — arquivo não-teste perto de 700 linhas):
+ * o server passa a conter apenas o comportamento (resolução de instância,
+ * handlers e registro), enquanto a superfície declarativa — o que cada tool
+ * aceita — vive aqui. Um só motivo para mudar cada arquivo.
+ *
+ * Segurança: nenhum schema aceita URL/host — a instância vem sempre da config do
+ * processo (ver `resolveInstance` em `./server.ts`).
+ */
+import { z } from 'zod';
+import * as core from '../../index.js';
+/** Formato aceito pelas tools MCP (nomes amigáveis expostos ao cliente). */
+export type McpFormat = 'markdown' | 'json';
+/** Nome canônico da tool de contexto de issue. */
+export declare const TOOL_NAME = "get_issue_context";
+/** Nome canônico da tool de busca de issues. */
+export declare const SEARCH_TOOL_NAME = "search_issues";
+/** Nome canônico da tool de texto de anexo. */
+export declare const ATTACHMENT_TOOL_NAME = "get_attachment_text";
+/** Nome canônico da tool das últimas issues. */
+export declare const LAST_TOOL_NAME = "get_last";
+/** Limite default de resultados da tool `search_issues` (documentado no schema). */
+export declare const SEARCH_DEFAULT_LIMIT = 25;
+/** Argumentos da tool `get_issue_context` já validados pelo schema zod. */
+export interface GetIssueContextArgs {
+    /** Identificador numérico da issue no Redmine. */
+    issue_id: number;
+    /** Formato de saída: `markdown` (padrão) ou `json`. */
+    format?: McpFormat | undefined;
+    /**
+     * Extrai o texto dos anexos de imagem (OCR) e o embute no bundle. Default:
+     * `false` — a extração adiciona latência (download + OCR por anexo). O M4 trará
+     * o modo cache-first/processing assíncrono; no M3 a extração é síncrona.
+     */
+    extract_attachments?: boolean | undefined;
+}
+/** Argumentos da tool `get_attachment_text` já validados pelo schema zod. */
+export interface GetAttachmentTextArgs {
+    /** Identificador numérico da issue que contém o anexo. */
+    issue_id: number;
+    /** Identificador numérico do anexo cujo texto será extraído. */
+    attachment_id: number;
+}
+/** Argumentos da tool `search_issues` já validados pelo schema zod. */
+export interface SearchIssuesArgs {
+    /** Termo full-text opcional (`/search.json`, best-effort). */
+    query?: string | undefined;
+    /** Filtro `project_id`. */
+    project_id?: number | undefined;
+    /** Filtro `status_id` (`'open'`, `'closed'`, `'*'` ou um id). */
+    status_id?: number | string | undefined;
+    /** Filtro `assigned_to_id` (um id ou `'me'`). */
+    assigned_to_id?: number | string | undefined;
+    /** Filtro `updated_on` no formato do Redmine (ex.: `>=2026-01-01`). */
+    updated_on?: string | undefined;
+    /** Máximo de resultados. Default: {@link SEARCH_DEFAULT_LIMIT}. */
+    limit?: number | undefined;
+}
+/** Argumentos da tool `get_last` já validados pelo schema zod. */
+export interface GetLastArgs {
+    /** Critério de ordenação. Default: `updated`. */
+    order?: core.LastIssuesOrder | undefined;
+    /** Quantas issues empacotar. Default: 1; teto {@link core.LAST_MAX_COUNT}. */
+    count?: number | undefined;
+    /** Formato de saída: `markdown` (padrão) ou `json`. */
+    format?: McpFormat | undefined;
+    /** Extrai o texto (OCR) dos anexos e o embute nos bundles. Default: `false`. */
+    extract_attachments?: boolean | undefined;
+}
+/** Schema zod da tool `get_issue_context` (sem URL/host: a instância vem da env). */
+export declare const INPUT_SCHEMA: {
+    readonly issue_id: z.ZodNumber;
+    readonly format: z.ZodOptional<z.ZodEnum<{
+        json: "json";
+        markdown: "markdown";
+    }>>;
+    readonly extract_attachments: z.ZodOptional<z.ZodBoolean>;
+};
+/** Schema zod da tool `get_attachment_text` (read-only, sem URL/host). */
+export declare const ATTACHMENT_INPUT_SCHEMA: {
+    readonly issue_id: z.ZodNumber;
+    readonly attachment_id: z.ZodNumber;
+};
+/** Schema zod da tool `search_issues` (read-only, sem URL/host). */
+export declare const SEARCH_INPUT_SCHEMA: {
+    readonly query: z.ZodOptional<z.ZodString>;
+    readonly project_id: z.ZodOptional<z.ZodNumber>;
+    readonly status_id: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    readonly assigned_to_id: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    readonly updated_on: z.ZodOptional<z.ZodString>;
+    readonly limit: z.ZodOptional<z.ZodNumber>;
+};
+/** Schema zod da tool `get_last` (read-only, sem URL/host). */
+export declare const LAST_INPUT_SCHEMA: {
+    readonly order: z.ZodOptional<z.ZodEnum<{
+        priority: "priority";
+        updated: "updated";
+        created: "created";
+    }>>;
+    readonly count: z.ZodOptional<z.ZodNumber>;
+    readonly format: z.ZodOptional<z.ZodEnum<{
+        json: "json";
+        markdown: "markdown";
+    }>>;
+    readonly extract_attachments: z.ZodOptional<z.ZodBoolean>;
+};

package/dist/surfaces/mcp/tools.js

@@ -0,0 +1,93 @@
+/**
+ * Contrato de ENTRADA das tools MCP: nomes canônicos, tipos de argumentos e
+ * schemas zod.
+ *
+ * Extraído de `./server.ts` (RULES #24 — arquivo não-teste perto de 700 linhas):
+ * o server passa a conter apenas o comportamento (resolução de instância,
+ * handlers e registro), enquanto a superfície declarativa — o que cada tool
+ * aceita — vive aqui. Um só motivo para mudar cada arquivo.
+ *
+ * Segurança: nenhum schema aceita URL/host — a instância vem sempre da config do
+ * processo (ver `resolveInstance` em `./server.ts`).
+ */
+import { z } from 'zod';
+import * as core from '../../index.js';
+/** Nome canônico da tool de contexto de issue. */
+export const TOOL_NAME = 'get_issue_context';
+/** Nome canônico da tool de busca de issues. */
+export const SEARCH_TOOL_NAME = 'search_issues';
+/** Nome canônico da tool de texto de anexo. */
+export const ATTACHMENT_TOOL_NAME = 'get_attachment_text';
+/** Nome canônico da tool das últimas issues. */
+export const LAST_TOOL_NAME = 'get_last';
+/** Limite default de resultados da tool `search_issues` (documentado no schema). */
+export const SEARCH_DEFAULT_LIMIT = 25;
+/** Teto de resultados aceito pela tool `search_issues`. */
+const SEARCH_MAX_LIMIT = 100;
+/** Schema zod da tool `get_issue_context` (sem URL/host: a instância vem da env). */
+export const INPUT_SCHEMA = {
+    issue_id: z.number().int().positive().describe('Identificador numérico da issue no Redmine'),
+    format: z
+        .enum(['markdown', 'json'])
+        .optional()
+        .describe("Formato de saída: 'markdown' (padrão) ou 'json'"),
+    extract_attachments: z
+        .boolean()
+        .optional()
+        .describe('Extrai o texto (OCR) dos anexos de imagem e o embute no bundle. Default: false (adiciona latência de download+OCR). O M4 traz o modo cache-first/processing.'),
+};
+/** Schema zod da tool `get_attachment_text` (read-only, sem URL/host). */
+export const ATTACHMENT_INPUT_SCHEMA = {
+    issue_id: z.number().int().positive().describe('Identificador numérico da issue que contém o anexo'),
+    attachment_id: z.number().int().positive().describe('Identificador numérico do anexo a extrair'),
+};
+/** Schema zod da tool `search_issues` (read-only, sem URL/host). */
+export const SEARCH_INPUT_SCHEMA = {
+    query: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Termo full-text via /search.json (best-effort). Se a busca falhar, degrada para os filtros estruturados com aviso.'),
+    project_id: z.number().int().positive().optional().describe('Filtro estruturado project_id'),
+    status_id: z
+        .union([z.number().int(), z.string()])
+        .optional()
+        .describe("Filtro status_id: um id, 'open', 'closed' ou '*'"),
+    assigned_to_id: z
+        .union([z.number().int(), z.string()])
+        .optional()
+        .describe("Filtro assigned_to_id: um id ou 'me'"),
+    updated_on: z
+        .string()
+        .optional()
+        .describe('Filtro updated_on no formato do Redmine (ex.: >=2026-01-01, <=2026-12-31)'),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(SEARCH_MAX_LIMIT)
+        .optional()
+        .describe(`Máximo de resultados paginados (default ${SEARCH_DEFAULT_LIMIT}, teto ${SEARCH_MAX_LIMIT})`),
+};
+/** Schema zod da tool `get_last` (read-only, sem URL/host). */
+export const LAST_INPUT_SCHEMA = {
+    order: z
+        .enum(['updated', 'created', 'priority'])
+        .optional()
+        .describe(`Critério de ordenação: 'updated' (padrão — mexida mais recente), 'created' (entrada mais recente) ou 'priority' (mais urgente, desempatando pela mais recente)`),
+    count: z
+        .number()
+        .int()
+        .positive()
+        .max(core.LAST_MAX_COUNT)
+        .optional()
+        .describe(`Quantas issues empacotar (default ${core.LAST_DEFAULT_COUNT}, teto ${core.LAST_MAX_COUNT}). Cada item é um bundle COMPLETO — prefira search_issues para visões amplas.`),
+    format: z
+        .enum(['markdown', 'json'])
+        .optional()
+        .describe("Formato de saída: 'markdown' (padrão) ou 'json' (sempre um array)"),
+    extract_attachments: z
+        .boolean()
+        .optional()
+        .describe('Extrai o texto (OCR) dos anexos de imagem e o embute nos bundles. Default: false (adiciona latência de download+OCR).'),
+};

package/dist/surfaces/tui/app.d.ts

@@ -9,6 +9,20 @@ import { type Theme, type ThemeController } from './theme.js';
  * Ink nem depender de uma tela de dados real (#29+) para chegar no estado de
  * re-auth ativo.
  */
+/**
+ * Estilo da moldura da aplicação conforme o suporte a Unicode.
+ *
+ * `round` desenha com box-drawing (`╭ ─ │ ╯`); no terminal legado do Windows
+ * isso vira mojibake, do mesmo jeito que os frames braille do spinner (M5-09,
+ * #84). `classic` é o fallback ASCII do próprio Ink (`+ - |`).
+ *
+ * Função pura (em vez de só a constante) para o fallback ser testável sem
+ * depender do ambiente real — mesmo padrão de `./glyphs.ts`.
+ *
+ * @param unicode - `true` quando o terminal renderiza box-drawing.
+ * @returns O `borderStyle` a passar ao `Box` do Ink.
+ */
+export declare function borderStyleFor(unicode: boolean): 'round' | 'classic';
 export type EscapeAction = {
     kind: 'abort-reauth';
     origin: ScreenName;

package/dist/surfaces/tui/app.js

@@ -34,12 +34,14 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { Box, Text, useApp, useInput, useStdout } from 'ink';
 import { Breadcrumb } from './components/breadcrumb.js';
-import { TerminalSizeProvider, useTerminalHeight } from './hooks/use-terminal-width.js';
+import { isUnicodeSupported } from './glyphs.js';
+import { TerminalHeightProvider, TerminalSizeProvider, useTerminalHeight, } from './hooks/use-terminal-width.js';
 import { applyTerminalColors } from './terminal-colors.js';
 import { ReAuthAbortedError } from './hooks/use-auth-guard.js';
 import { consumeEscapeInterceptor } from './hooks/use-escape-interceptor.js';
 import { useExitGuard } from './hooks/use-exit-guard.js';
 import { useOnboardingCallbacks } from './hooks/use-onboarding-callbacks.js';
+import { isTyping } from './hooks/use-typing-guard.js';
 import { JobRegistryProvider } from './job-registry.js';
 import { NavigationProvider, useNavigation, useNavigationStack } from './navigation.js';
 import { HomeSelectionProvider } from './screens/home-selection.js';
@@ -49,6 +51,33 @@ import { DEFAULT_PALETTE_ID, resolvePalette } from './palettes.js';
 import { INITIAL_SCREEN, SCREENS } from './screen.js';
 import { symbols } from './symbols.js';
 import { DEFAULT_THEME, ThemeControllerProvider, ThemeProvider, useTheme, } from './theme.js';
+/**
+ * O que `Esc` deve fazer dado o estado atual — extraída como função pura
+ * (fix do review #119) para poder ser testada isoladamente
+ * (`tests/surfaces/tui/app.test.tsx`) sem precisar montar toda a árvore do
+ * Ink nem depender de uma tela de dados real (#29+) para chegar no estado de
+ * re-auth ativo.
+ */
+/**
+ * Estilo da moldura da aplicação conforme o suporte a Unicode.
+ *
+ * `round` desenha com box-drawing (`╭ ─ │ ╯`); no terminal legado do Windows
+ * isso vira mojibake, do mesmo jeito que os frames braille do spinner (M5-09,
+ * #84). `classic` é o fallback ASCII do próprio Ink (`+ - |`).
+ *
+ * Função pura (em vez de só a constante) para o fallback ser testável sem
+ * depender do ambiente real — mesmo padrão de `./glyphs.ts`.
+ *
+ * @param unicode - `true` quando o terminal renderiza box-drawing.
+ * @returns O `borderStyle` a passar ao `Box` do Ink.
+ */
+export function borderStyleFor(unicode) {
+    return unicode ? 'round' : 'classic';
+}
+/** Estilo resolvido para o ambiente atual — decidido uma vez, no import. */
+const BORDER_STYLE = borderStyleFor(isUnicodeSupported());
+/** Linhas consumidas pela moldura (topo + base). */
+const BORDER_ROWS = 2;
 /**
  * Decide a ação de `Esc`: abandono do re-auth (fix do review #119) quando a
  * tela atual é do fluxo de onboarding (`onboarding-*`) E há um `reAuth` em
@@ -139,7 +168,10 @@ function AppShell() {
     const abortReAuthRef = useRef(abortReAuth);
     abortReAuthRef.current = abortReAuth;
     const handleGlobalInput = useCallback((input, key) => {
-        if (input === 'q') {
+        // `q` só sai FORA de campo de texto: o Ink entrega a tecla a todos os
+        // handlers, então sem esta guarda digitar uma URL com "q" (ou uma senha)
+        // fecharia a TUI no meio do onboarding (ver ./hooks/use-typing-guard.ts).
+        if (input === 'q' && !isTyping()) {
             exitRef.current();
             return;
         }
@@ -176,5 +208,10 @@ function AppShell() {
     // + este container com a ALTURA do terminal (`minHeight`). O breadcrumb fica no
     // topo e a tela ocupa o resto (`flexGrow`); cada tela ancora seus atalhos no
     // rodapé com um espaçador `flexGrow` (estilo nano/nvim/tmux).
-    return (_jsxs(Box, { flexDirection: "column", minHeight: rows, children: [_jsx(Breadcrumb, { stack: stack }), armed ? (_jsx(Box, { paddingX: 1, marginBottom: 1, children: _jsxs(Text, { color: theme.warning, children: [symbols.warning, " Pressione Ctrl+C de novo para sair."] }) })) : null, _jsx(Box, { flexGrow: 1, flexDirection: "column", children: _jsx(Screen, {}) })] }));
+    return (
+    // Moldura única da aplicação (#190 — pacote estético): a borda vive AQUI e
+    // não nas telas, então nenhuma tela precisa saber que existe uma. As duas
+    // linhas da borda saem do minHeight para o conteúdo não estourar a altura do
+    // terminal (o que empurraria o topo para fora no modo full-screen).
+    _jsxs(Box, { flexDirection: "column", minHeight: Math.max(1, rows - BORDER_ROWS), borderStyle: BORDER_STYLE, borderColor: theme.border, children: [_jsx(Breadcrumb, { stack: stack }), armed ? (_jsx(Box, { paddingX: 1, marginBottom: 1, children: _jsxs(Text, { color: theme.warning, children: [symbols.warning, " Pressione Ctrl+C de novo para sair."] }) })) : null, _jsx(Box, { flexGrow: 1, flexDirection: "column", children: _jsx(TerminalHeightProvider, { height: Math.max(1, rows - BORDER_ROWS), children: _jsx(Screen, {}) }) })] }));
 }

package/dist/surfaces/tui/banner.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Arte ASCII do banner da tela de abertura (#190 — pacote estético).
+ *
+ * As três variantes são CONSTANTES, não geradas em runtime: o texto é sempre
+ * `redmine-context`, então trazer uma dependência de fontes (figlet/cfonts) para
+ * recalcular a mesma string a cada boot não se paga — custaria peso no pacote e
+ * tempo de start. Para regenerar (fonte `ANSI Shadow` / `Small` do figlet):
+ *
+ *   npx figlet -f "ANSI Shadow" redmine-context
+ *   npx figlet -f "ANSI Shadow" redmine ; npx figlet -f "ANSI Shadow" context
+ *   npx figlet -f Small redmine-context
+ *
+ * A seleção é PURA ({@link selectBanner}) e depende de dois sinais que a TUI já
+ * possui: a largura do terminal (`../hooks/use-terminal-width.js`) e o suporte a
+ * Unicode (`../glyphs.js`) — o mesmo sinal que degrada os frames braille do
+ * spinner no terminal legado do Windows (M5-09, #84). Sem essa degradação, os
+ * blocos `█`/`╗` do ANSI Shadow virariam mojibake.
+ */
+/** Variante escolhida por {@link selectBanner}. */
+export type BannerVariant = 'wide' | 'stacked' | 'ascii' | 'plain';
+/**
+ * Escolhe a variante do banner para o terminal atual.
+ *
+ * Ordem de preferência, sempre respeitando a largura disponível:
+ * `wide` (uma linha, Unicode) → `stacked` (duas linhas, Unicode) → `ascii`
+ * (ASCII puro) → `plain` (sem arte; a tela cai no nome em texto).
+ *
+ * @param width - Colunas disponíveis (ver `useTerminalWidth`).
+ * @param unicode - `true` quando o terminal renderiza os blocos do ANSI Shadow.
+ * @returns A variante a renderizar.
+ * @example
+ * selectBanner(140, true) // 'wide'
+ * selectBanner(80, true)  // 'stacked' (não cabe a wide)
+ * selectBanner(80, false) // 'ascii'  (sem Unicode)
+ */
+export declare function selectBanner(width: number, unicode: boolean): BannerVariant;
+/**
+ * Linhas da variante escolhida.
+ *
+ * @param variant - Variante de {@link selectBanner}.
+ * @returns As linhas da arte; vazio para `plain`.
+ */
+export declare function bannerLines(variant: BannerVariant): readonly string[];