redmine-context 1.0.0

package/dist/index.js

@@ -0,0 +1,67 @@
+export const TOOL_NAME = 'redmine-context';
+// Manter em sincronia com package.json (validado por tests/packaging/smoke-pack.test.ts).
+export const TOOL_VERSION = '1.0.0';
+// Superfície pública do core: contrato de tipos + padrão de progresso (ADR-005).
+// As superfícies devem consumir o core somente por aqui / por ./contract.js.
+export * from './contract.js';
+// Orquestração get → normalize → bundle reutilizável por CLI (#17) e MCP (#18).
+export { fetchIssueBundle, } from './fetch-issue-bundle.js';
+// Orquestração de extração de anexos (M3-10): baixa → dispatcher → extrator →
+// cache → Map<attachmentId, ExtractionResult>, embutida nos bundles pela flag
+// `extractAttachments` de `fetchIssueBundle`. CLI/MCP ligam a flag na #55.
+export { extractIssueAttachments, } from './extract-issue-attachments.js';
+// Orquestração get → normalize → extração de UM anexo (M3-13): reutiliza o
+// pipeline com cache de `extractIssueAttachments` para a tool MCP read-only
+// `get_attachment_text` (#55). Devolve o ExtractionResult do anexo pedido.
+export { fetchAttachmentText, fetchAttachmentTextCacheFirst, AttachmentNotFoundError, } from './fetch-attachment-text.js';
+// Leitura cache-first não-bloqueante das extrações (M4-11 #70): lê o que está
+// pronto e sinaliza `processing` para o resto, disparando a extração cara em
+// background pela fila — a superfície MCP responde na hora (< 5s), sem bloquear.
+export { extractIssueAttachmentsCacheFirst, makeQueueBackgroundExtractor, processingResult, } from './cache-first.js';
+// Orquestração de busca (filtros + full-text best-effort) para a tool MCP (#19).
+export { fetchIssueSearch, SEARCH_DEFAULT_LIMIT, } from './fetch-issue-search.js';
+// Primitiva full-text `/search.json` (usada pela orquestração acima).
+export { searchIssues } from './client/index.js';
+// Client HTTP base (auth por api_key + retry) — usado por telas que precisam
+// montar suas próprias chamadas ao core sem uma orquestração pronta (ex.: a
+// home da TUI, #29, que lista "minhas issues" via `listIssues` abaixo).
+export { createHttpClient, } from './client/index.js';
+// Listagem paginada de issues (`GET /issues.json`), payload bruto sem
+// normalização — usada pela home da TUI (#29) com o filtro `assigned_to_id=me`.
+export { listIssues } from './client/index.js';
+// Detalhe completo de uma issue (`GET /issues/{id}.json`), payload bruto sem
+// normalização — usado pela tela de detalhe da TUI (#31), que normaliza com
+// `normalizeIssue` abaixo para render o modelo estável `Issue` (sem passar
+// pelo bundle Markdown/JSON, que é o formato de saída da CLI/MCP, não do
+// modelo em memória que a TUI precisa para paginar/rolar o conteúdo).
+export { getIssue } from './client/index.js';
+// Normalização do payload bruto de issue no modelo estável `Issue` do
+// contrato — usada por `fetchIssueBundle` (CLI/MCP) e, desde a #31, também
+// diretamente pela tela de detalhe da TUI (`getIssue` + `normalizeIssue`,
+// sem serializar para Markdown/JSON).
+export { normalizeIssue } from './normalize/index.js';
+// Empacotamento Markdown/JSON direto (M1-09/M1-10) — usado por
+// `fetchIssueBundle` internamente e, desde a #33, também diretamente pela
+// tela de exportação da TUI: a issue já está normalizada em memória (`./use-issue-detail.js`,
+// #31), então gravar o bundle não precisa refazer a busca+normalização via
+// `fetchIssueBundle` — só empacotar o que já foi carregado.
+export { buildMarkdownBundle, buildJsonBundle, fenceBlock, } from './bundle/index.js';
+// Erros HTTP tipados — usados pelas superfícies para mapear exit codes (ADR-005).
+export { RedmineHttpError, RedmineAuthError, RedmineForbiddenError, RedmineNotFoundError, } from './client/index.js';
+// Login por senha (M1-07) e cascata de credenciais (M1-08) para as superfícies.
+export { loginWithPassword, validateApiKey, RedmineLoginError, } from './config/index.js';
+export { createCredentialCascade, resolveApiKey, describeCredentialSource, normalizeInstanceUrl, CredentialStoreError, } from './config/index.js';
+// Persistência da URL da instância (#187) — fallback além de REDMINE_URL/--url.
+export { defaultSettingsStore, resolveInstanceUrl, } from './config/index.js';
+// Diagnóstico de binários de mídia (M3-11 #53, M4-01 #57) — núcleo do comando
+// `doctor` (CLI) e da seção "Binários de mídia" da TUI. Detecção de tesseract,
+// ffmpeg e whisper.cpp + status do modelo GGUF, com hint de instalação por SO
+// (ADR-002).
+export { diagnoseBinaries, tesseractInstallHint, pdftotextInstallHint, ffmpegInstallHint, whisperInstallHint, } from './config/index.js';
+// Localização de binários de mídia e path canônico do modelo GGUF (M4-01, #57).
+// `whisperModelDir` é o ponto único de verdade do cache de modelos, consumido
+// pelo `doctor` e pelo download do modelo (#58) (ADR-002).
+export { findFfmpeg, detectFfmpegVersion, findWhisper, whisperModelDir, } from './extract/index.js';
+// Download do modelo GGUF com SHA-256 pinado e guard headless (M4-02, #58).
+// Opt-in interativo (ADR-002): recusa em MCP/headless; consome `whisperModelDir`.
+export { downloadGgufModel, GgufDownloadError, GGUF_MODEL_NAME, GGUF_MODEL_URL, GGUF_MODEL_SHA256, } from './extract/index.js';

package/dist/normalize/collections.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Normalização das coleções aninhadas de uma issue (issue #12).
+ *
+ * Cobre o que a issue #11 deixou como coleções vazias: custom_fields, relations,
+ * parent/children e watchers. Mesmo contrato de robustez de {@link normalizeIssue}
+ * (`src/normalize/issue.ts`): reutiliza os helpers defensivos de `./helpers.js` e
+ * NUNCA lança — itens malformados são descartados e campos ausentes degradam para
+ * defaults estáveis do contrato (ADR-005).
+ */
+import type { CustomField, IssueChild, IssueRelation, RedmineRef } from '../contract.js';
+/**
+ * Normaliza a coleção de custom fields de uma issue.
+ *
+ * @param value - Valor bruto de `issue.custom_fields`.
+ * @param fieldFormats - Mapa opcional `id → field_format` fornecido externamente.
+ * @returns Array de custom fields válidos (itens malformados descartados).
+ */
+export declare function normalizeCustomFields(value: unknown, fieldFormats?: Map<number, string>): CustomField[];
+/**
+ * Normaliza a coleção de relations de uma issue.
+ *
+ * @param value - Valor bruto de `issue.relations`.
+ * @returns Array de relations válidas (itens malformados descartados).
+ */
+export declare function normalizeRelations(value: unknown): IssueRelation[];
+/**
+ * Normaliza a coleção de children (nível de topo) de uma issue.
+ *
+ * @param value - Valor bruto de `issue.children`.
+ * @returns Array de children válidos (itens malformados descartados).
+ */
+export declare function normalizeChildren(value: unknown): IssueChild[];
+/**
+ * Extrai a referência de parent (`{ id }`) do payload.
+ *
+ * @param value - Valor bruto de `issue.parent`.
+ * @returns `{ id }` quando há `id` numérico; senão `undefined`.
+ */
+export declare function normalizeParent(value: unknown): {
+    id: number;
+} | undefined;
+/**
+ * Normaliza a lista de watchers (refs `{ id, name }`).
+ *
+ * Só deve ser chamada quando a chave `watchers` está presente no payload — a
+ * ausência da chave (include não pedido ou 403) é degradação e o campo do
+ * contrato fica omitido pelo chamador.
+ *
+ * @param value - Valor bruto de `issue.watchers`.
+ * @returns Array de refs válidas (itens malformados descartados).
+ */
+export declare function normalizeWatchers(value: unknown): RedmineRef[];

package/dist/normalize/collections.js

@@ -0,0 +1,170 @@
+/**
+ * Normalização das coleções aninhadas de uma issue (issue #12).
+ *
+ * Cobre o que a issue #11 deixou como coleções vazias: custom_fields, relations,
+ * parent/children e watchers. Mesmo contrato de robustez de {@link normalizeIssue}
+ * (`src/normalize/issue.ts`): reutiliza os helpers defensivos de `./helpers.js` e
+ * NUNCA lança — itens malformados são descartados e campos ausentes degradam para
+ * defaults estáveis do contrato (ADR-005).
+ */
+import { asArray, asNumber, asRecord, asString, isDefined, normalizeRef } from './helpers.js';
+/**
+ * Extrai o `raw_value` de um custom field preservando o bruto da API.
+ *
+ * Mantém `string`, `""` e arrays (filtrando itens não-textuais) exatamente como
+ * vieram; `null`, ausência e tipos inesperados colapsam para `null`.
+ *
+ * @param value - Valor bruto de `custom_field.value`.
+ * @returns O bruto preservado no formato do contrato.
+ */
+function rawCustomFieldValue(value) {
+    if (Array.isArray(value))
+        return value.filter((item) => typeof item === 'string');
+    return asString(value) ?? null;
+}
+/**
+ * Normaliza APENAS a ausência de um custom field (`""`/`null` → `null`).
+ *
+ * Não há coerção de tipo (ADR-005): qualquer valor presente e não-vazio é
+ * repassado intacto — inclusive arrays.
+ *
+ * @param raw - O `raw_value` já extraído.
+ * @returns `null` para ausência (`""`/`null`); senão o próprio bruto.
+ */
+function normalizedCustomFieldValue(raw) {
+    if (raw === null || raw === '')
+        return null;
+    return raw;
+}
+/**
+ * Normaliza um custom field para o contrato {@link CustomField}.
+ *
+ * `field_format` não vem na API de issue: só é anotado quando o chamador fornece
+ * o formato via `fieldFormats` (ex.: de `/custom_fields.json`).
+ *
+ * @param value - Item bruto de `issue.custom_fields[]`.
+ * @param fieldFormats - Mapa opcional `id → field_format` fornecido externamente.
+ * @returns O custom field normalizado, ou `undefined` se não tiver `id` numérico.
+ */
+function normalizeCustomField(value, fieldFormats) {
+    const record = asRecord(value);
+    if (record === undefined)
+        return undefined;
+    const id = asNumber(record.id);
+    if (id === undefined)
+        return undefined;
+    const raw = rawCustomFieldValue(record.value);
+    const field = {
+        id,
+        name: asString(record.name) ?? '',
+        value: normalizedCustomFieldValue(raw),
+        raw_value: raw,
+    };
+    const format = fieldFormats?.get(id);
+    if (format !== undefined)
+        field.field_format = format;
+    return field;
+}
+/**
+ * Normaliza a coleção de custom fields de uma issue.
+ *
+ * @param value - Valor bruto de `issue.custom_fields`.
+ * @param fieldFormats - Mapa opcional `id → field_format` fornecido externamente.
+ * @returns Array de custom fields válidos (itens malformados descartados).
+ */
+export function normalizeCustomFields(value, fieldFormats) {
+    return asArray(value)
+        .map((item) => normalizeCustomField(item, fieldFormats))
+        .filter(isDefined);
+}
+/**
+ * Normaliza uma relação entre issues para o contrato {@link IssueRelation}.
+ *
+ * @param value - Item bruto de `issue.relations[]`.
+ * @returns A relação normalizada, ou `undefined` se não tiver `id` numérico.
+ *   `delay` ausente vira `null`; demais campos numéricos/textuais degradam.
+ */
+function normalizeRelation(value) {
+    const record = asRecord(value);
+    if (record === undefined)
+        return undefined;
+    const id = asNumber(record.id);
+    if (id === undefined)
+        return undefined;
+    return {
+        id,
+        issue_id: asNumber(record.issue_id) ?? 0,
+        issue_to_id: asNumber(record.issue_to_id) ?? 0,
+        relation_type: asString(record.relation_type) ?? '',
+        delay: asNumber(record.delay) ?? null,
+    };
+}
+/**
+ * Normaliza a coleção de relations de uma issue.
+ *
+ * @param value - Valor bruto de `issue.relations`.
+ * @returns Array de relations válidas (itens malformados descartados).
+ */
+export function normalizeRelations(value) {
+    return asArray(value).map(normalizeRelation).filter(isDefined);
+}
+/**
+ * Normaliza uma issue-filha para o contrato {@link IssueChild}.
+ *
+ * O contrato é plano (`{id, tracker?, subject?}`): eventuais `children` aninhados
+ * do payload são ignorados aqui — cada nível é uma issue por si.
+ *
+ * @param value - Item bruto de `issue.children[]`.
+ * @returns A filha normalizada, ou `undefined` se não tiver `id` numérico.
+ */
+function normalizeChild(value) {
+    const record = asRecord(value);
+    if (record === undefined)
+        return undefined;
+    const id = asNumber(record.id);
+    if (id === undefined)
+        return undefined;
+    const child = { id };
+    const tracker = normalizeRef(record.tracker);
+    if (tracker !== undefined)
+        child.tracker = tracker;
+    const subject = asString(record.subject);
+    if (subject !== undefined)
+        child.subject = subject;
+    return child;
+}
+/**
+ * Normaliza a coleção de children (nível de topo) de uma issue.
+ *
+ * @param value - Valor bruto de `issue.children`.
+ * @returns Array de children válidos (itens malformados descartados).
+ */
+export function normalizeChildren(value) {
+    return asArray(value).map(normalizeChild).filter(isDefined);
+}
+/**
+ * Extrai a referência de parent (`{ id }`) do payload.
+ *
+ * @param value - Valor bruto de `issue.parent`.
+ * @returns `{ id }` quando há `id` numérico; senão `undefined`.
+ */
+export function normalizeParent(value) {
+    const record = asRecord(value);
+    if (record === undefined)
+        return undefined;
+    const id = asNumber(record.id);
+    return id === undefined ? undefined : { id };
+}
+/**
+ * Normaliza a lista de watchers (refs `{ id, name }`).
+ *
+ * Só deve ser chamada quando a chave `watchers` está presente no payload — a
+ * ausência da chave (include não pedido ou 403) é degradação e o campo do
+ * contrato fica omitido pelo chamador.
+ *
+ * @param value - Valor bruto de `issue.watchers`.
+ * @returns Array de refs válidas (itens malformados descartados).
+ */
+export function normalizeWatchers(value) {
+    return asArray(value).map(normalizeRef).filter(isDefined);
+}

package/dist/normalize/helpers.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Helpers de parsing defensivo compartilhados pela normalização (issues #11/#12).
+ *
+ * Núcleo do estilo "nunca lança" de `src/normalize/*`: cada função converte um
+ * valor `unknown` em um tipo estável ou num `undefined`/default previsível,
+ * permitindo que payloads parciais ou malformados degradem campo a campo sem
+ * crashar. Reutilizados por {@link normalizeIssue} e pelos normalizadores de
+ * coleções (custom_fields, relations, children, watchers).
+ */
+import type { RedmineRef } from '../contract.js';
+/**
+ * Converte um valor desconhecido em `Record<string, unknown>` para acesso seguro.
+ *
+ * @param value - Valor a inspecionar.
+ * @returns O objeto tipado, ou `undefined` se não for um objeto simples.
+ */
+export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+/** Devolve o array bruto, ou `[]` quando o valor não é um array. */
+export declare function asArray(value: unknown): unknown[];
+/** `string` quando o valor é textual, senão `undefined`. */
+export declare function asString(value: unknown): string | undefined;
+/** `number` quando o valor é numérico, senão `undefined`. */
+export declare function asNumber(value: unknown): number | undefined;
+/** Preserva `string`/`null` de valores brutos; tipos inesperados viram `null`. */
+export declare function asStringOrNull(value: unknown): string | null;
+/** Type guard para remover `undefined` após um `map` defensivo. */
+export declare function isDefined<T>(value: T | undefined): value is T;
+/**
+ * Normaliza uma ref nomeada do Redmine (`{ id, name }`).
+ *
+ * @param value - Valor bruto (objeto esperado).
+ * @returns A ref quando há `id` numérico; senão `undefined`. `name` não-string
+ *   degrada para `""`.
+ */
+export declare function normalizeRef(value: unknown): RedmineRef | undefined;

package/dist/normalize/helpers.js

@@ -0,0 +1,59 @@
+/**
+ * Helpers de parsing defensivo compartilhados pela normalização (issues #11/#12).
+ *
+ * Núcleo do estilo "nunca lança" de `src/normalize/*`: cada função converte um
+ * valor `unknown` em um tipo estável ou num `undefined`/default previsível,
+ * permitindo que payloads parciais ou malformados degradem campo a campo sem
+ * crashar. Reutilizados por {@link normalizeIssue} e pelos normalizadores de
+ * coleções (custom_fields, relations, children, watchers).
+ */
+/**
+ * Converte um valor desconhecido em `Record<string, unknown>` para acesso seguro.
+ *
+ * @param value - Valor a inspecionar.
+ * @returns O objeto tipado, ou `undefined` se não for um objeto simples.
+ */
+export function asRecord(value) {
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+/** Devolve o array bruto, ou `[]` quando o valor não é um array. */
+export function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+/** `string` quando o valor é textual, senão `undefined`. */
+export function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+/** `number` quando o valor é numérico, senão `undefined`. */
+export function asNumber(value) {
+    return typeof value === 'number' ? value : undefined;
+}
+/** Preserva `string`/`null` de valores brutos; tipos inesperados viram `null`. */
+export function asStringOrNull(value) {
+    if (value === null)
+        return null;
+    return typeof value === 'string' ? value : null;
+}
+/** Type guard para remover `undefined` após um `map` defensivo. */
+export function isDefined(value) {
+    return value !== undefined;
+}
+/**
+ * Normaliza uma ref nomeada do Redmine (`{ id, name }`).
+ *
+ * @param value - Valor bruto (objeto esperado).
+ * @returns A ref quando há `id` numérico; senão `undefined`. `name` não-string
+ *   degrada para `""`.
+ */
+export function normalizeRef(value) {
+    const record = asRecord(value);
+    if (record === undefined)
+        return undefined;
+    const id = asNumber(record.id);
+    if (id === undefined)
+        return undefined;
+    return { id, name: asString(record.name) ?? '' };
+}

package/dist/normalize/index.d.ts

@@ -0,0 +1,2 @@
+export declare const MODULE_NAME: "normalize";
+export { normalizeIssue } from './issue.js';

package/dist/normalize/index.js

@@ -0,0 +1,2 @@
+export const MODULE_NAME = 'normalize';
+export { normalizeIssue } from './issue.js';

package/dist/normalize/issue.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Normalização do payload bruto de issue (issues #11/#12).
+ *
+ * Converte o {@link RedmineIssuePayload} devolvido por `getIssue`
+ * (`/issues/{id}.json?include=journals,attachments,relations,children`) no modelo
+ * estável {@link Issue} do contrato. Cobre o núcleo (#11) — id, subject,
+ * description, refs, datas, journals e attachments — e as coleções aninhadas
+ * (#12) delegadas a `./collections.js`: custom_fields, relations, parent/children
+ * e watchers.
+ *
+ * Parsing 100% defensivo (estilo `src/client/issues.ts`): payload parcial ou
+ * malformado NUNCA lança — cada campo degrada para um default estável.
+ */
+import type { RedmineIssuePayload } from '../client/issues.js';
+import type { Issue } from '../contract.js';
+/**
+ * Normaliza o payload bruto de uma issue no modelo {@link Issue} do contrato.
+ *
+ * Núcleo (#11): id, subject, description, refs, datas, journals e attachments.
+ * Coleções (#12): custom_fields, relations, parent/children e watchers. Nunca
+ * lança: payload parcial/malformado degrada campo a campo para defaults estáveis.
+ *
+ * `watchers` só aparece quando a chave está presente no payload; a ausência
+ * (include não pedido ou 403) omite o campo como degradação. A API de issue não
+ * devolve `field_format` dos custom fields — o chamador pode anotá-lo via
+ * `fieldFormats` (ex.: a partir de `/custom_fields.json`).
+ *
+ * @param payload - Payload bruto de `getIssue`.
+ * @param fieldFormats - Mapa opcional `custom_field_id → field_format`.
+ * @returns A issue normalizada, sempre válida perante o contrato.
+ * @example
+ * const issue = normalizeIssue(await getIssue(http, 100));
+ */
+export declare function normalizeIssue(payload: RedmineIssuePayload, fieldFormats?: Map<number, string>): Issue;

package/dist/normalize/issue.js

@@ -0,0 +1,154 @@
+/**
+ * Normalização do payload bruto de issue (issues #11/#12).
+ *
+ * Converte o {@link RedmineIssuePayload} devolvido por `getIssue`
+ * (`/issues/{id}.json?include=journals,attachments,relations,children`) no modelo
+ * estável {@link Issue} do contrato. Cobre o núcleo (#11) — id, subject,
+ * description, refs, datas, journals e attachments — e as coleções aninhadas
+ * (#12) delegadas a `./collections.js`: custom_fields, relations, parent/children
+ * e watchers.
+ *
+ * Parsing 100% defensivo (estilo `src/client/issues.ts`): payload parcial ou
+ * malformado NUNCA lança — cada campo degrada para um default estável.
+ */
+import { normalizeChildren, normalizeCustomFields, normalizeParent, normalizeRelations, normalizeWatchers, } from './collections.js';
+import { asArray, asNumber, asRecord, asString, asStringOrNull, isDefined, normalizeRef, } from './helpers.js';
+/** Ref placeholder para campos obrigatórios do contrato ausentes no payload. */
+// Congelado: instância compartilhada entre todas as issues degradadas — mutação
+// acidental corromperia o placeholder globalmente (modo strict lança).
+const NULL_REF = Object.freeze({ id: 0, name: '' });
+/** Ref obrigatória do contrato: cai para {@link NULL_REF} se ausente/inválida. */
+function requireRef(value) {
+    return normalizeRef(value) ?? NULL_REF;
+}
+/**
+ * Normaliza um detalhe bruto de journal, preservando o histórico sem interpretar.
+ *
+ * @param value - Item bruto de `journal.details[]`.
+ * @returns O detalhe normalizado, ou `undefined` se não for um objeto.
+ */
+function normalizeJournalDetail(value) {
+    const record = asRecord(value);
+    if (record === undefined)
+        return undefined;
+    const detail = {
+        property: asString(record.property) ?? '',
+        name: asString(record.name) ?? '',
+    };
+    if ('old_value' in record)
+        detail.old_value = asStringOrNull(record.old_value);
+    if ('new_value' in record)
+        detail.new_value = asStringOrNull(record.new_value);
+    return detail;
+}
+/**
+ * Normaliza uma entrada de journal (nota opcional + `details[]` brutos).
+ *
+ * @param value - Item bruto de `issue.journals[]`.
+ * @returns O journal normalizado, ou `undefined` se não tiver `id` numérico.
+ */
+function normalizeJournal(value) {
+    const record = asRecord(value);
+    if (record === undefined)
+        return undefined;
+    const id = asNumber(record.id);
+    if (id === undefined)
+        return undefined;
+    const journal = {
+        id,
+        created_on: asString(record.created_on) ?? '',
+        details: asArray(record.details).map(normalizeJournalDetail).filter(isDefined),
+    };
+    // notes só é significativa quando não-vazia (Redmine devolve "" em journal de detalhe).
+    const notes = asString(record.notes);
+    if (notes !== undefined && notes !== '')
+        journal.notes = notes;
+    const user = normalizeRef(record.user);
+    if (user !== undefined)
+        journal.user = user;
+    return journal;
+}
+/**
+ * Normaliza um anexo, mantendo `content_type`/`digest` quando presentes.
+ *
+ * @param value - Item bruto de `issue.attachments[]`.
+ * @returns O anexo normalizado, ou `undefined` se não tiver `id` numérico.
+ */
+function normalizeAttachment(value) {
+    const record = asRecord(value);
+    if (record === undefined)
+        return undefined;
+    const id = asNumber(record.id);
+    if (id === undefined)
+        return undefined;
+    const attachment = {
+        id,
+        filename: asString(record.filename) ?? '',
+        filesize: asNumber(record.filesize) ?? 0,
+        created_on: asString(record.created_on) ?? '',
+        content_url: asString(record.content_url) ?? '',
+    };
+    const contentType = asString(record.content_type);
+    if (contentType !== undefined)
+        attachment.content_type = contentType;
+    const description = asString(record.description);
+    if (description !== undefined && description !== '')
+        attachment.description = description;
+    const author = normalizeRef(record.author);
+    if (author !== undefined)
+        attachment.author = author;
+    const digest = asString(record.digest);
+    if (digest !== undefined)
+        attachment.digest = digest;
+    return attachment;
+}
+/**
+ * Normaliza o payload bruto de uma issue no modelo {@link Issue} do contrato.
+ *
+ * Núcleo (#11): id, subject, description, refs, datas, journals e attachments.
+ * Coleções (#12): custom_fields, relations, parent/children e watchers. Nunca
+ * lança: payload parcial/malformado degrada campo a campo para defaults estáveis.
+ *
+ * `watchers` só aparece quando a chave está presente no payload; a ausência
+ * (include não pedido ou 403) omite o campo como degradação. A API de issue não
+ * devolve `field_format` dos custom fields — o chamador pode anotá-lo via
+ * `fieldFormats` (ex.: a partir de `/custom_fields.json`).
+ *
+ * @param payload - Payload bruto de `getIssue`.
+ * @param fieldFormats - Mapa opcional `custom_field_id → field_format`.
+ * @returns A issue normalizada, sempre válida perante o contrato.
+ * @example
+ * const issue = normalizeIssue(await getIssue(http, 100));
+ */
+export function normalizeIssue(payload, fieldFormats) {
+    const record = asRecord(payload) ?? {};
+    const issue = {
+        id: asNumber(record.id) ?? 0,
+        subject: asString(record.subject) ?? '',
+        project: requireRef(record.project),
+        tracker: requireRef(record.tracker),
+        status: requireRef(record.status),
+        priority: requireRef(record.priority),
+        author: requireRef(record.author),
+        created_on: asString(record.created_on) ?? '',
+        updated_on: asString(record.updated_on) ?? '',
+        journals: asArray(record.journals).map(normalizeJournal).filter(isDefined),
+        attachments: asArray(record.attachments).map(normalizeAttachment).filter(isDefined),
+        custom_fields: normalizeCustomFields(record.custom_fields, fieldFormats),
+        relations: normalizeRelations(record.relations),
+        children: normalizeChildren(record.children),
+    };
+    const description = asString(record.description);
+    if (description !== undefined && description !== '')
+        issue.description = description;
+    const assignedTo = normalizeRef(record.assigned_to);
+    if (assignedTo !== undefined)
+        issue.assigned_to = assignedTo;
+    const parent = normalizeParent(record.parent);
+    if (parent !== undefined)
+        issue.parent = parent;
+    // Ausência da chave `watchers` = degradação (403/include ausente): campo omitido.
+    if ('watchers' in record)
+        issue.watchers = normalizeWatchers(record.watchers);
+    return issue;
+}

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

@@ -0,0 +1,61 @@
+/**
+ * Handlers dos comandos do CLI (M1-11): `issue` e `login`.
+ *
+ * Consomem EXCLUSIVAMENTE a superfície pública do core (`../../index.js`,
+ * fronteira do ADR-005) — a orquestração `fetchIssueBundle`, o `loginWithPassword`
+ * e a cascata de credenciais. Cada handler devolve o exit code do processo; o
+ * mapeamento status→código vive em {@link exitCodeForError} e é documentado no
+ * `--help`.
+ */
+import type { ParsedArgs, RunDeps } from './types.js';
+/** Exit codes do CLI (documentados no `--help`). */
+export declare const EXIT: {
+    /** Erro genérico ou uso inválido. */
+    readonly GENERIC: 1;
+    /** Falha de autenticação ou credencial ausente. */
+    readonly AUTH: 2;
+    /** Erro de rede ou HTTP. */
+    readonly NETWORK: 3;
+    /** Issue inexistente. */
+    readonly NOT_FOUND: 4;
+};
+/**
+ * Mapeia um erro para o exit code do CLI.
+ *
+ * Ordem importa: os erros específicos (404, 401) estendem `RedmineHttpError` e
+ * precisam ser testados antes do genérico HTTP. Erros de rede (sem status) são
+ * detectados pela mensagem do client e também caem em {@link EXIT.NETWORK}.
+ *
+ * @param error - Erro capturado durante a operação.
+ * @returns O exit code correspondente.
+ */
+export declare function exitCodeForError(error: unknown): number;
+/**
+ * Comando `issue <id>`: resolve credencial pela cascata, empacota e emite o
+ * bundle (stdout ou `--out <dir>`), com progresso em stderr.
+ *
+ * @param parsed - Argumentos parseados (posicional `<id>` + flags).
+ * @param deps - Dependências injetáveis (I/O, env).
+ * @returns Exit code do processo.
+ */
+export declare function runIssue(parsed: ParsedArgs, deps: RunDeps): Promise<number>;
+/**
+ * Comando `doctor`: diagnostica os binários de mídia (hoje o `tesseract`) e
+ * imprime um relatório em TEXTO PURO no stdout. Degrada naturalmente em
+ * `NO_COLOR`/não-TTY (não emite cor/ANSI). Exit 0 se todos presentes, 1 se
+ * faltar algum — o exit code deixa o resultado programável em scripts.
+ *
+ * @param _parsed - Argumentos parseados (o comando não usa flags hoje).
+ * @param deps - Dependências injetáveis (I/O).
+ * @returns Exit code do processo (0 = tudo ok, 1 = binário faltando).
+ */
+export declare function runDoctor(_parsed: ParsedArgs, deps: RunDeps): Promise<number>;
+/**
+ * Comando `login`: autentica (senha ou `--api-key`) e salva a api_key na
+ * cascata para a instância informada.
+ *
+ * @param parsed - Argumentos parseados (flags `--url`, `--api-key`, `--insecure`).
+ * @param deps - Dependências injetáveis (prompts, I/O, env).
+ * @returns Exit code do processo.
+ */
+export declare function runLogin(parsed: ParsedArgs, deps: RunDeps): Promise<number>;