redmine-context 1.0.0

package/dist/surfaces/cli/prompts.js

@@ -0,0 +1,147 @@
+/**
+ * Prompts interativos do CLI (M1-11) — leitura de linha e senha mascarada.
+ *
+ * Implementação mínima sobre o `readline` nativo (sem dependência de terceiros):
+ * `prompt` lê uma linha com echo normal; `promptPassword` desliga o echo dos
+ * caracteres digitados (sem eco — a senha nunca aparece no terminal nem em logs).
+ * Os streams de entrada/saída são injetáveis para permitir testes determinísticos.
+ */
+import { createInterface } from 'node:readline';
+/** I/O default apontando para o processo atual. */
+function defaultIo() {
+    return { input: process.stdin, output: process.stdout };
+}
+/**
+ * Cria uma {@link PromptSession} sobre os streams informados.
+ *
+ * @param io - Streams de I/O (ver {@link PromptIo}). Default: stdin/stdout.
+ * @returns Sessão com `prompt`/`promptPassword`/`close`.
+ * @example
+ * const session = createPromptSession();
+ * const user = await session.prompt('Usuário: ');
+ * const pass = await session.promptPassword('Senha: ');
+ * session.close();
+ */
+export function createPromptSession(io = defaultIo()) {
+    let rl;
+    let muted = false;
+    // Fila própria: o readline EMITE 'line' assim que a entrada chega (pipes e
+    // colagens entregam várias linhas de uma vez) e eventos sem ouvinte com
+    // pergunta pendente se perderiam — segunda metade do bug #106.
+    const pending = [];
+    const waiters = [];
+    const ensure = () => {
+        if (rl === undefined) {
+            const created = createInterface({ input: io.input, output: io.output });
+            const writer = created;
+            writer._writeToOutput = (text) => {
+                if (!muted) {
+                    io.output.write(text);
+                }
+                // muted: engole o echo dos caracteres sensíveis.
+            };
+            created.on('line', (line) => {
+                const waiter = waiters.shift();
+                if (waiter) {
+                    waiter(line);
+                }
+                else {
+                    pending.push(line);
+                }
+            });
+            // EOF (Ctrl+D / pipe encerrado) com prompt pendente: resolve vazio para o
+            // fluxo falhar com mensagem clara em vez de o processo morrer em silêncio.
+            created.on('close', () => {
+                while (waiters.length > 0) {
+                    waiters.shift()?.('');
+                }
+            });
+            rl = created;
+        }
+        return rl;
+    };
+    const nextLine = () => {
+        const queued = pending.shift();
+        if (queued !== undefined) {
+            return Promise.resolve(queued);
+        }
+        return new Promise((resolve) => {
+            waiters.push(resolve);
+        });
+    };
+    const ask = async (question, mute) => {
+        ensure();
+        io.output.write(question);
+        muted = mute;
+        try {
+            return await nextLine();
+        }
+        finally {
+            muted = false;
+            if (mute) {
+                io.output.write('\n');
+            }
+        }
+    };
+    return {
+        prompt: (question) => ask(question, false),
+        promptPassword: (question) => ask(question, true),
+        close: () => {
+            rl?.close();
+            rl = undefined;
+        },
+    };
+}
+/**
+ * Lê uma linha do usuário com echo normal.
+ *
+ * @param question - Texto exibido antes da entrada (ex.: `'Usuário: '`).
+ * @param io - Streams de I/O (ver {@link PromptIo}). Default: stdin/stdout.
+ * @returns A linha digitada (sem o `\n` final).
+ * @example
+ * const user = await prompt('Usuário: ');
+ */
+export function prompt(question, io = defaultIo()) {
+    const rl = createInterface({ input: io.input, output: io.output });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+/**
+ * Lê uma linha sensível (senha, api_key) SEM ecoar os caracteres digitados.
+ *
+ * A pergunta é escrita normalmente; a partir daí o writer interno do readline é
+ * silenciado, de modo que nenhum caractere da entrada aparece no terminal.
+ *
+ * @param question - Texto exibido antes da entrada (ex.: `'Senha: '`).
+ * @param io - Streams de I/O (ver {@link PromptIo}). Default: stdin/stdout.
+ * @returns O valor digitado (sem o `\n` final), nunca ecoado.
+ * @example
+ * const password = await promptPassword('Senha: ');
+ */
+export function promptPassword(question, io = defaultIo()) {
+    const { input, output } = io;
+    const rl = createInterface({ input, output, terminal: true });
+    // O readline expõe `_writeToOutput` como ponto de extensão do echo.
+    const writer = rl;
+    let muted = false;
+    writer._writeToOutput = (text) => {
+        if (!muted) {
+            output.write(text);
+        }
+        // muted: engole o echo dos caracteres da senha (sem eco).
+    };
+    output.write(question);
+    muted = true;
+    return new Promise((resolve) => {
+        rl.question('', (answer) => {
+            muted = false;
+            rl.close();
+            output.write('\n');
+            resolve(answer);
+        });
+    });
+}

package/dist/surfaces/cli/tty.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Decisão de degradação da TUI Ink (M2-03).
+ *
+ * Centraliza em uma função pura quando o `redmine-context` sem argumentos
+ * pode abrir a TUI Ink vs. quando deve cair para o caminho de texto puro da
+ * CLI (help). Sinais de degradação (qualquer um basta):
+ *
+ * - `NO_COLOR` definida (qualquer valor, inclusive string vazia — convenção
+ *   de https://no-color.org: a mera presença da variável já sinaliza a
+ *   preferência do usuário/ambiente por saída sem formatação);
+ * - `CI=true` ou `CI=1` (ambientes de integração contínua não têm um terminal real);
+ * - stdout não é um TTY (pipe, redirecionamento para arquivo, etc.).
+ *
+ * Pura e testável isoladamente: recebe `env` e `isTTY` em vez de ler
+ * `process.env`/`process.stdout` diretamente, seguindo o padrão de
+ * dependências injetáveis do CLI (`RunDeps`, ver `./types.ts`).
+ */
+/**
+ * Decide se a TUI Ink pode ser aberta.
+ *
+ * @param env - Ambiente do processo (ou um subconjunto controlado em testes).
+ * @param isTTY - `true` quando o stdout real é um TTY.
+ * @returns `true` somente quando não há nenhum sinal de degradação.
+ * @example
+ * shouldRenderTui(process.env, process.stdout.isTTY === true);
+ */
+export declare function shouldRenderTui(env: NodeJS.ProcessEnv, isTTY: boolean): boolean;

package/dist/surfaces/cli/tty.js

@@ -0,0 +1,35 @@
+/**
+ * Decisão de degradação da TUI Ink (M2-03).
+ *
+ * Centraliza em uma função pura quando o `redmine-context` sem argumentos
+ * pode abrir a TUI Ink vs. quando deve cair para o caminho de texto puro da
+ * CLI (help). Sinais de degradação (qualquer um basta):
+ *
+ * - `NO_COLOR` definida (qualquer valor, inclusive string vazia — convenção
+ *   de https://no-color.org: a mera presença da variável já sinaliza a
+ *   preferência do usuário/ambiente por saída sem formatação);
+ * - `CI=true` ou `CI=1` (ambientes de integração contínua não têm um terminal real);
+ * - stdout não é um TTY (pipe, redirecionamento para arquivo, etc.).
+ *
+ * Pura e testável isoladamente: recebe `env` e `isTTY` em vez de ler
+ * `process.env`/`process.stdout` diretamente, seguindo o padrão de
+ * dependências injetáveis do CLI (`RunDeps`, ver `./types.ts`).
+ */
+/**
+ * Decide se a TUI Ink pode ser aberta.
+ *
+ * @param env - Ambiente do processo (ou um subconjunto controlado em testes).
+ * @param isTTY - `true` quando o stdout real é um TTY.
+ * @returns `true` somente quando não há nenhum sinal de degradação.
+ * @example
+ * shouldRenderTui(process.env, process.stdout.isTTY === true);
+ */
+export function shouldRenderTui(env, isTTY) {
+    if (!isTTY)
+        return false;
+    if (env.NO_COLOR !== undefined)
+        return false;
+    if (env.CI === 'true' || env.CI === '1')
+        return false;
+    return true;
+}

package/dist/surfaces/cli/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Tipos compartilhados da superfície CLI (M1-11).
+ *
+ * Isolados neste módulo para evitar ciclos entre `main.ts` (parse/dispatch) e
+ * `commands.ts` (handlers) e manter cada arquivo com um propósito único.
+ */
+import type { SettingsStore } from '../../index.js';
+/** Dependências injetáveis do CLI — permitem testar I/O e prompts sem tocar o processo real. */
+export interface RunDeps {
+    /** Escreve no canal de saída (stdout) — recebe o bundle. */
+    stdout(text: string): void;
+    /** Escreve no canal de diagnóstico (stderr) — recebe progresso e mensagens. */
+    stderr(text: string): void;
+    /** Ambiente consultado para `REDMINE_URL` e pela cascata de credenciais. */
+    env: NodeJS.ProcessEnv;
+    /** Lê uma linha do usuário (ex.: URL, usuário). */
+    prompt(question: string): Promise<string>;
+    /** Lê um valor sensível sem echo (senha, api_key). */
+    promptPassword(question: string): Promise<string>;
+    /**
+     * `true` quando o stdout real é um TTY — decide se `redmine-context` sem
+     * argumentos abre a TUI (M2-01) ou degrada para o help (padrão atual).
+     * Opcional: nos testes, ausência equivale a `false` (não-TTY).
+     */
+    isTTY?: boolean;
+    /**
+     * Store da URL da instância persistida (#187): o `login` a grava e `issue`/`login`
+     * a usam como fallback além de `--url`/`REDMINE_URL`. Opcional: ausente nos testes
+     * (sem persistência), presente na execução real (`defaultSettingsStore`).
+     */
+    settings?: SettingsStore;
+}
+/** Resultado do parse manual de `argv`: posicionais + flags. */
+export interface ParsedArgs {
+    /** Argumentos posicionais na ordem (ex.: `['issue', '42']`). */
+    positionals: string[];
+    /** Flags parseadas: `true` para booleanas, string para as com valor. */
+    flags: Map<string, string | boolean>;
+}

package/dist/surfaces/cli/types.js

@@ -0,0 +1,7 @@
+/**
+ * Tipos compartilhados da superfície CLI (M1-11).
+ *
+ * Isolados neste módulo para evitar ciclos entre `main.ts` (parse/dispatch) e
+ * `commands.ts` (handlers) e manter cada arquivo com um propósito único.
+ */
+export {};

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

@@ -0,0 +1,171 @@
+/**
+ * Superfície MCP (stdio) do `redmine-context` (M1-12).
+ *
+ * Expõe a tool read-only `get_issue_context(issue_id, format?)`, que reutiliza a
+ * orquestração `fetchIssueBundle` do core. Segue a mesma fronteira da CLI
+ * (ADR-005): importa o core EXCLUSIVAMENTE por `../../index.js`; nenhum módulo
+ * interno é acessado diretamente (regra eslint `no-restricted-imports`).
+ *
+ * Segurança: NENHUMA tool aceita URL/host arbitrário — a instância vem sempre da
+ * config/env do processo (`REDMINE_URL`; sem ela, a URL persistida no `login`,
+ * #187) + cascata de credencial. Quando a URL vem da persistida (fonte mutável),
+ * a credencial de AMBIENTE (`REDMINE_API_KEY`, instance-agnóstica) é DESABILITADA
+ * — só credencial pinada à instância (keychain/arquivo) é aceita, impedindo que um
+ * `settings.json` adulterado exfiltre a chave (ver `resolveInstance`). No transporte
+ * stdio o protocolo ocupa o stdout, portanto todo diagnóstico vai para stderr.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.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
+ * o core e o `process.env` reais.
+ */
+export interface McpServerDeps {
+    /** Orquestração get → normalize → bundle do core. */
+    fetchIssueBundle: typeof core.fetchIssueBundle;
+    /** Orquestração de busca (filtros + full-text best-effort) do core. */
+    searchIssues: typeof core.fetchIssueSearch;
+    /**
+     * 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
+     * ainda não processada. Default: {@link core.fetchAttachmentTextCacheFirst}.
+     * Tipada pela assinatura base para aceitar tanto a variante cache-first quanto
+     * a síncrona (M3) nos testes.
+     */
+    fetchAttachmentText: (options: FetchAttachmentTextOptions) => Promise<AttachmentTextResult>;
+    /** Resolução de credencial pela cascata (arquivo → env). */
+    resolveApiKey: typeof resolveApiKey;
+    /** Ambiente consultado para `REDMINE_URL` e pela cascata de credencial. */
+    env: NodeJS.ProcessEnv;
+    /**
+     * Store da URL da instância persistida (#187): fallback quando `REDMINE_URL`
+     * não está no ambiente do processo (ex.: registro MCP sem a env, mas com
+     * `login` já feito). Continua uma ÚNICA instância configurada — nunca vem dos
+     * argumentos das tools. Opcional (ausente nos testes que fixam a env).
+     */
+    settings?: core.SettingsStore;
+    /** Versão da ferramenta gravada no bundle. */
+    toolVersion: string;
+    /**
+     * Permite `http://` (sem TLS) com aviso ruidoso. Derivado de `REDMINE_INSECURE`
+     * no ambiente do processo. Default: `false` (só `https://`). Espelha a flag
+     * `--insecure` da CLI para os ambientes de teste/CI que usam http local.
+     */
+    insecure?: boolean;
+    /** 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.
+ *
+ * Resolve a instância/credencial a partir da env (nunca de argumentos), invoca
+ * `fetchIssueBundle` e devolve o bundle. Erros viram `isError` com mensagem
+ * tipada; a ausência de `REDMINE_URL`/credencial orienta a configuração.
+ *
+ * @param deps - Ver {@link McpServerDeps}.
+ * @returns Função assíncrona que recebe os argumentos e devolve um CallToolResult.
+ * @example
+ * const handler = createGetIssueContextHandler(defaultMcpDeps());
+ * const result = await handler({ issue_id: 42, format: 'json' });
+ */
+export declare function createGetIssueContextHandler(deps: McpServerDeps): (args: GetIssueContextArgs) => Promise<CallToolResult>;
+/**
+ * Cria o handler da tool `search_issues`, testável isoladamente.
+ *
+ * Resolve a instância/credencial da env (nunca de argumentos), delega à
+ * orquestração `fetchIssueSearch` (filtros + full-text best-effort) e devolve a
+ * lista compacta em Markdown. A degradação da busca full-text NÃO é erro: o
+ * aviso já vem embutido no payload retornado pelo core.
+ *
+ * @param deps - Ver {@link McpServerDeps}.
+ * @returns Função assíncrona que recebe os argumentos e devolve um CallToolResult.
+ * @example
+ * const handler = createSearchIssuesHandler(defaultMcpDeps());
+ * 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_attachment_text`, testável isoladamente.
+ *
+ * Resolve a instância/credencial da env (nunca de argumentos), delega à
+ * orquestração cache-first `fetchAttachmentText` (texto já cacheado volta na
+ * hora; mídia pesada ainda não processada volta como `processing` SEM bloquear —
+ * M4-11 #70) e devolve o texto extraído dentro da fence untrusted. Anexo não
+ * processável / `processing` vira status legível (não `isError`); 403/404 do
+ * Redmine e anexo inexistente viram `isError` tipado.
+ *
+ * @param deps - Ver {@link McpServerDeps}.
+ * @returns Função assíncrona que recebe os argumentos e devolve um CallToolResult.
+ * @example
+ * const handler = createGetAttachmentTextHandler(defaultMcpDeps());
+ * const result = await handler({ issue_id: 42, attachment_id: 77 });
+ */
+export declare function createGetAttachmentTextHandler(deps: McpServerDeps): (args: GetAttachmentTextArgs) => Promise<CallToolResult>;
+/**
+ * Constrói um {@link McpServer} com a tool `get_issue_context` registrada.
+ *
+ * A tool é read-only e não expõe URL/host — a instância vem sempre da env.
+ *
+ * @param deps - Ver {@link McpServerDeps}.
+ * @returns O server pronto para `connect(transport)`.
+ */
+export declare function createMcpServer(deps: McpServerDeps): McpServer;
+/** Constrói as dependências default apontando para o core e o processo reais. */
+export declare function defaultMcpDeps(): McpServerDeps;
+/**
+ * Sobe o server MCP no transporte stdio e resolve quando a conexão fecha.
+ *
+ * O stdout é reservado ao protocolo; qualquer log vai para stderr.
+ *
+ * @param overrides - Dependências injetáveis (defaults via {@link defaultMcpDeps}).
+ * @returns Promise que resolve quando o transporte encerra.
+ */
+export declare function runStdioServer(overrides?: Partial<McpServerDeps>): Promise<void>;