redmine-context 1.0.0

package/dist/config/login.js

@@ -0,0 +1,189 @@
+/**
+ * Login por senha (Basic auth) para descobrir a api_key do usuário (M1-07).
+ *
+ * Fluxo: `GET {baseUrl}/users/current.json` com `Authorization: Basic
+ * base64(user:pass)`. A senha nunca é logada nem persistida; qualquer texto
+ * que possa vazar (mensagens de rede/parse) é redigido antes de compor um erro.
+ *
+ * A política de TLS (https obrigatório; `insecure` apenas com aviso ruidoso) é
+ * reutilizada de `client/http.ts` via {@link validateBaseUrl} — não duplicada.
+ * O fallback de 2FA (copiar a api_key em `/my/account`) segue o ADR-003.
+ */
+import { Buffer } from 'node:buffer';
+import { RedmineAuthError, redactSecret, validateBaseUrl } from '../client/index.js';
+const noopLogger = { warn: () => undefined };
+/**
+ * Erro de login por senha que não se enquadra num status HTTP tipado do client
+ * (entrada inválida, REST desabilitada, corpo inesperado, falha de rede/parse).
+ * Sempre construído com a mensagem já redigida — nunca carrega a senha.
+ */
+export class RedmineLoginError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** Remove barras finais da baseUrl preservando o subpath. */
+function trimTrailingSlash(baseUrl) {
+    return baseUrl.replace(/\/+$/, '');
+}
+/** Estreita `unknown` para um objeto indexável, ou `undefined` se não for. */
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : undefined;
+}
+/** Retorna a string se o campo for uma string não vazia, senão `undefined`. */
+function stringField(record, key) {
+    const value = record[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/**
+ * Autentica por senha e descobre a api_key do usuário.
+ *
+ * @param options - Ver {@link LoginOptions}.
+ * @returns {@link LoginResult} com a api_key e a identidade do usuário.
+ * @throws {RedmineLoginError} Entrada inválida, corpo sem usuário/api_key,
+ *   REST desabilitada, falha de rede ou JSON inválido (senha sempre redigida).
+ * @throws {RedmineAuthError} Em 401 — com instrução de fallback 2FA (ADR-003).
+ * @throws {Error} Se a política de TLS for violada (via `validateBaseUrl`).
+ * @example
+ * const { apiKey, user } = await loginWithPassword({
+ *   baseUrl: 'https://redmine.example',
+ *   username: 'alice',
+ *   password: '****',
+ * });
+ */
+export async function loginWithPassword(options) {
+    const { baseUrl, username, password, insecure = false } = options;
+    const logger = options.logger ?? noopLogger;
+    if (username.length === 0) {
+        throw new RedmineLoginError('username é obrigatório e não pode ser vazio.');
+    }
+    if (password.length === 0) {
+        throw new RedmineLoginError('password é obrigatório e não pode ser vazio.');
+    }
+    // Reusa a política de TLS do client (ADR-003) — pode lançar antes de qualquer fetch.
+    validateBaseUrl(baseUrl, insecure, logger);
+    // Redige a senha de qualquer texto de baixo nível antes de compor uma mensagem.
+    const redact = (text) => redactSecret(text, password);
+    const origin = trimTrailingSlash(baseUrl);
+    const url = `${origin}/users/current.json`;
+    const accountUrl = `${origin}/my/account`;
+    const token = Buffer.from(`${username}:${password}`, 'utf8').toString('base64');
+    const headers = {
+        Accept: 'application/json',
+        Authorization: `Basic ${token}`,
+    };
+    let response;
+    try {
+        response = await fetch(url, { method: 'GET', headers });
+    }
+    catch (cause) {
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        throw new RedmineLoginError(redact(`Falha de rede ao acessar ${url}: ${reason}`));
+    }
+    if (response.status === 401) {
+        throw new RedmineAuthError(`Autenticação falhou (401): usuário ou senha inválidos. ` +
+            `Se a conta usa autenticação de dois fatores (2FA), o login por senha não funciona — ` +
+            `copie sua api_key em ${accountUrl} e informe-a diretamente.`, 401, url);
+    }
+    if (!response.ok) {
+        throw new RedmineLoginError(redact(`GET ${url} respondeu ${response.status} ${response.statusText}.`));
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (cause) {
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        throw new RedmineLoginError(redact(`Resposta de ${url} não é JSON válido: ${reason}`));
+    }
+    const rawUser = asRecord(asRecord(body)?.user);
+    const id = rawUser?.id;
+    const login = rawUser ? stringField(rawUser, 'login') : undefined;
+    if (rawUser === undefined || typeof id !== 'number' || login === undefined) {
+        throw new RedmineLoginError(`Resposta de ${url} não contém um usuário válido (campos id/login ausentes).`);
+    }
+    const apiKey = stringField(rawUser, 'api_key');
+    if (apiKey === undefined) {
+        throw new RedmineLoginError(`A resposta não contém api_key: a REST API pode estar desabilitada ou a conta não ter permissão. ` +
+            `Habilite a REST API e copie sua api_key em ${accountUrl}.`);
+    }
+    const firstname = stringField(rawUser, 'firstname');
+    const lastname = stringField(rawUser, 'lastname');
+    const name = [firstname, lastname].filter((part) => part !== undefined).join(' ') || login;
+    return { apiKey, user: { id, login, name } };
+}
+/**
+ * Valida uma api_key colada diretamente pelo usuário (fallback de 2FA do
+ * ADR-003, quando `loginWithPassword` falha com 401) contra `GET
+ * {baseUrl}/users/current.json`, autenticando com o header
+ * `X-Redmine-API-Key` em vez de Basic auth. A key nunca é logada; qualquer
+ * texto que possa vazar é redigido antes de compor um erro — mesma política
+ * de {@link loginWithPassword}.
+ *
+ * @param options - Ver {@link ValidateApiKeyOptions}.
+ * @returns {@link LoginResult} com a própria api_key (ecoada de volta, para
+ *   simetria com {@link loginWithPassword}) e a identidade do usuário.
+ * @throws {RedmineLoginError} Entrada inválida, corpo sem usuário, REST
+ *   desabilitada, falha de rede ou JSON inválido (key sempre redigida).
+ * @throws {RedmineAuthError} Em 401 — api_key inválida ou expirada.
+ * @throws {Error} Se a política de TLS for violada (via `validateBaseUrl`).
+ * @example
+ * const { apiKey, user } = await validateApiKey({
+ *   baseUrl: 'https://redmine.example',
+ *   apiKey: pastedKey,
+ * });
+ */
+export async function validateApiKey(options) {
+    const { baseUrl, apiKey, insecure = false } = options;
+    const logger = options.logger ?? noopLogger;
+    if (apiKey.length === 0) {
+        throw new RedmineLoginError('api_key é obrigatória e não pode ser vazia.');
+    }
+    // Reusa a política de TLS do client (ADR-003) — pode lançar antes de qualquer fetch.
+    validateBaseUrl(baseUrl, insecure, logger);
+    // Redige a key de qualquer texto de baixo nível antes de compor uma mensagem.
+    const redact = (text) => redactSecret(text, apiKey);
+    const origin = trimTrailingSlash(baseUrl);
+    const url = `${origin}/users/current.json`;
+    const headers = {
+        Accept: 'application/json',
+        'X-Redmine-API-Key': apiKey,
+    };
+    let response;
+    try {
+        response = await fetch(url, { method: 'GET', headers });
+    }
+    catch (cause) {
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        throw new RedmineLoginError(redact(`Falha de rede ao acessar ${url}: ${reason}`));
+    }
+    if (response.status === 401) {
+        throw new RedmineAuthError(`Autenticação falhou (401): api_key inválida ou expirada. Copie a api_key atual em ${accountUrlFor(origin)}.`, 401, url);
+    }
+    if (!response.ok) {
+        throw new RedmineLoginError(redact(`GET ${url} respondeu ${response.status} ${response.statusText}.`));
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (cause) {
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        throw new RedmineLoginError(redact(`Resposta de ${url} não é JSON válido: ${reason}`));
+    }
+    const rawUser = asRecord(asRecord(body)?.user);
+    const id = rawUser?.id;
+    const login = rawUser ? stringField(rawUser, 'login') : undefined;
+    if (rawUser === undefined || typeof id !== 'number' || login === undefined) {
+        throw new RedmineLoginError(`Resposta de ${url} não contém um usuário válido (campos id/login ausentes).`);
+    }
+    const firstname = stringField(rawUser, 'firstname');
+    const lastname = stringField(rawUser, 'lastname');
+    const name = [firstname, lastname].filter((part) => part !== undefined).join(' ') || login;
+    return { apiKey, user: { id, login, name } };
+}
+/** Monta a URL de `/my/account` a partir da origem já sem barra final. */
+function accountUrlFor(origin) {
+    return `${origin}/my/account`;
+}

package/dist/config/settings.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Store de CONFIGURAÇÕES NÃO SECRETAS do usuário (#187).
+ *
+ * Hoje guarda apenas a **URL da instância** "default/última usada", para que a
+ * TUI/CLI/MCP não dependam EXCLUSIVAMENTE de `REDMINE_URL` no ambiente: o `login`
+ * persiste a instância autenticada e as superfícies a usam como fallback.
+ *
+ * Diferente do credential store (ADR-003), aqui NÃO há segredo — a URL não é
+ * sensível — então o arquivo usa permissões default (sem `0600`). Fica em
+ * `env-paths('redmine-context').config/settings.json`. Parse defensivo: JSON
+ * inválido/ausente NUNCA quebra o boot (degrada para "sem configuração"), pois,
+ * ao contrário da api_key, nada aqui é irrecuperável.
+ *
+ * RESOLUÇÃO DA INSTÂNCIA ({@link resolveInstanceUrl}, pura): a ordem de precedência
+ * é `--url` (flag) → `REDMINE_URL` (env) → URL persistida. Isso preserva a
+ * retrocompatibilidade (flag/env sempre vencem) e a convenção env-first do MCP
+ * headless, adicionando a persistência só como último recurso.
+ */
+/** Formato persistido (evolutivo). */
+export interface Settings {
+    /** URL base da instância "default/última usada" (normalizada ao gravar). */
+    instanceUrl?: string;
+    /** Id da paleta de cores da TUI escolhida (#190). */
+    palette?: string;
+}
+/** Store de settings não-secretas: URL da instância + paleta da TUI. */
+export interface SettingsStore {
+    /** URL da instância persistida, ou `undefined` se nenhuma. */
+    getInstanceUrl(): Promise<string | undefined>;
+    /** Persiste (normalizada) a URL da instância. */
+    setInstanceUrl(url: string): Promise<void>;
+    /** Remove a URL da instância persistida; no-op se não existir. */
+    clearInstanceUrl(): Promise<void>;
+    /** Id da paleta de cores da TUI persistida, ou `undefined` se nenhuma (#190). */
+    getPaletteId(): Promise<string | undefined>;
+    /** Persiste o id da paleta de cores da TUI (#190). */
+    setPaletteId(id: string): Promise<void>;
+}
+/** Caminho padrão do arquivo de settings (diretório de config do usuário). */
+export declare function defaultSettingsPath(): string;
+/** Opções do {@link FileSettingsStore}. */
+export interface FileSettingsStoreOptions {
+    /** Caminho do arquivo; default via `env-paths`. Útil para testes. */
+    filePath?: string;
+}
+/**
+ * {@link SettingsStore} baseado num arquivo JSON não-secreto. Leitura defensiva
+ * (ENOENT/JSON inválido → sem configuração); escrita cria o diretório sob demanda.
+ */
+export declare class FileSettingsStore implements SettingsStore {
+    private readonly filePath;
+    constructor(options?: FileSettingsStoreOptions);
+    /**
+     * Lê o objeto BRUTO do arquivo (preservando chaves desconhecidas para
+     * forward-compat); qualquer problema degrada para `{}` (nunca lança).
+     */
+    private readRaw;
+    /**
+     * Escreve o objeto ATOMICAMENTE (arquivo temp + `rename`), criando o diretório
+     * sob demanda. O `rename` no mesmo diretório é atômico nos SOs suportados —
+     * evita deixar um `settings.json` truncado se o processo morrer no meio da escrita.
+     */
+    private write;
+    getInstanceUrl(): Promise<string | undefined>;
+    setInstanceUrl(url: string): Promise<void>;
+    clearInstanceUrl(): Promise<void>;
+    getPaletteId(): Promise<string | undefined>;
+    setPaletteId(id: string): Promise<void>;
+}
+/** {@link SettingsStore} padrão (arquivo em `env-paths().config`). */
+export declare function defaultSettingsStore(): SettingsStore;
+/** Origem de onde a URL da instância foi resolvida (para diagnóstico/UX). */
+export type InstanceUrlOrigin = 'flag' | 'env' | 'config';
+/** URL da instância resolvida + de onde veio. */
+export interface ResolvedInstanceUrl {
+    /** URL base da instância. */
+    url: string;
+    /** Origem: `flag` (--url), `env` (REDMINE_URL) ou `config` (persistida). */
+    origin: InstanceUrlOrigin;
+}
+/**
+ * Resolve a URL da instância por precedência: `--url` → `REDMINE_URL` → persistida.
+ * Função PURA — o chamador carrega a URL persistida (assíncrona) e a injeta aqui.
+ *
+ * @param opts - `flagUrl` (--url), `envUrl` (REDMINE_URL) e `persistedUrl` (settings).
+ * @returns A URL resolvida + origem, ou `undefined` se nenhuma fonte tiver valor.
+ * @example
+ * resolveInstanceUrl({ envUrl: 'https://r.example' }); // { url: 'https://r.example', origin: 'env' }
+ */
+export declare function resolveInstanceUrl(opts: {
+    flagUrl?: string | undefined;
+    envUrl?: string | undefined;
+    persistedUrl?: string | undefined;
+}): ResolvedInstanceUrl | undefined;

package/dist/config/settings.js

@@ -0,0 +1,140 @@
+/**
+ * Store de CONFIGURAÇÕES NÃO SECRETAS do usuário (#187).
+ *
+ * Hoje guarda apenas a **URL da instância** "default/última usada", para que a
+ * TUI/CLI/MCP não dependam EXCLUSIVAMENTE de `REDMINE_URL` no ambiente: o `login`
+ * persiste a instância autenticada e as superfícies a usam como fallback.
+ *
+ * Diferente do credential store (ADR-003), aqui NÃO há segredo — a URL não é
+ * sensível — então o arquivo usa permissões default (sem `0600`). Fica em
+ * `env-paths('redmine-context').config/settings.json`. Parse defensivo: JSON
+ * inválido/ausente NUNCA quebra o boot (degrada para "sem configuração"), pois,
+ * ao contrário da api_key, nada aqui é irrecuperável.
+ *
+ * RESOLUÇÃO DA INSTÂNCIA ({@link resolveInstanceUrl}, pura): a ordem de precedência
+ * é `--url` (flag) → `REDMINE_URL` (env) → URL persistida. Isso preserva a
+ * retrocompatibilidade (flag/env sempre vencem) e a convenção env-first do MCP
+ * headless, adicionando a persistência só como último recurso.
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import envPaths from 'env-paths';
+import { normalizeInstanceUrl } from './credentials.js';
+/** Nome do arquivo de settings no diretório de config do usuário. */
+const SETTINGS_FILENAME = 'settings.json';
+/** Caminho padrão do arquivo de settings (diretório de config do usuário). */
+export function defaultSettingsPath() {
+    return join(envPaths('redmine-context').config, SETTINGS_FILENAME);
+}
+/** Verifica se um erro do fs é "arquivo não encontrado" (ENOENT). */
+function isNotFound(cause) {
+    return (typeof cause === 'object' &&
+        cause !== null &&
+        cause.code === 'ENOENT');
+}
+/**
+ * {@link SettingsStore} baseado num arquivo JSON não-secreto. Leitura defensiva
+ * (ENOENT/JSON inválido → sem configuração); escrita cria o diretório sob demanda.
+ */
+export class FileSettingsStore {
+    filePath;
+    constructor(options = {}) {
+        this.filePath = options.filePath ?? defaultSettingsPath();
+    }
+    /**
+     * Lê o objeto BRUTO do arquivo (preservando chaves desconhecidas para
+     * forward-compat); qualquer problema degrada para `{}` (nunca lança).
+     */
+    async readRaw() {
+        let raw;
+        try {
+            raw = await readFile(this.filePath, 'utf8');
+        }
+        catch (cause) {
+            if (isNotFound(cause))
+                return {};
+            throw cause;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            // Config não-secreta: JSON corrompido degrada para "sem config" (a URL é
+            // re-obtida no próximo login), em vez de travar o boot como no credential store.
+            return {};
+        }
+        return typeof parsed === 'object' && parsed !== null ? parsed : {};
+    }
+    /**
+     * Escreve o objeto ATOMICAMENTE (arquivo temp + `rename`), criando o diretório
+     * sob demanda. O `rename` no mesmo diretório é atômico nos SOs suportados —
+     * evita deixar um `settings.json` truncado se o processo morrer no meio da escrita.
+     */
+    async write(data) {
+        await mkdir(dirname(this.filePath), { recursive: true });
+        const tmp = `${this.filePath}.${process.pid}.tmp`;
+        await writeFile(tmp, `${JSON.stringify(data, null, 2)}\n`);
+        await rename(tmp, this.filePath);
+    }
+    async getInstanceUrl() {
+        const url = (await this.readRaw()).instanceUrl;
+        // Rejeita string vazia OU só-whitespace (ex.: settings.json editado à mão) —
+        // mesma semântica do `nonEmpty()` do resolvedor, evitando um baseUrl de espaços.
+        const trimmed = typeof url === 'string' ? url.trim() : '';
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    async setInstanceUrl(url) {
+        const normalized = normalizeInstanceUrl(url);
+        const data = await this.readRaw();
+        data.instanceUrl = normalized;
+        await this.write(data);
+    }
+    async clearInstanceUrl() {
+        const data = await this.readRaw();
+        if (!('instanceUrl' in data))
+            return;
+        delete data.instanceUrl;
+        await this.write(data);
+    }
+    async getPaletteId() {
+        const id = (await this.readRaw()).palette;
+        const trimmed = typeof id === 'string' ? id.trim() : '';
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    async setPaletteId(id) {
+        const data = await this.readRaw();
+        data.palette = id;
+        await this.write(data);
+    }
+}
+/** {@link SettingsStore} padrão (arquivo em `env-paths().config`). */
+export function defaultSettingsStore() {
+    return new FileSettingsStore();
+}
+/** Retorna a string aparada se não-vazia, senão `undefined`. */
+function nonEmpty(value) {
+    const trimmed = value?.trim();
+    return trimmed !== undefined && trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * Resolve a URL da instância por precedência: `--url` → `REDMINE_URL` → persistida.
+ * Função PURA — o chamador carrega a URL persistida (assíncrona) e a injeta aqui.
+ *
+ * @param opts - `flagUrl` (--url), `envUrl` (REDMINE_URL) e `persistedUrl` (settings).
+ * @returns A URL resolvida + origem, ou `undefined` se nenhuma fonte tiver valor.
+ * @example
+ * resolveInstanceUrl({ envUrl: 'https://r.example' }); // { url: 'https://r.example', origin: 'env' }
+ */
+export function resolveInstanceUrl(opts) {
+    const flag = nonEmpty(opts.flagUrl);
+    if (flag !== undefined)
+        return { url: flag, origin: 'flag' };
+    const env = nonEmpty(opts.envUrl);
+    if (env !== undefined)
+        return { url: env, origin: 'env' };
+    const persisted = nonEmpty(opts.persistedUrl);
+    if (persisted !== undefined)
+        return { url: persisted, origin: 'config' };
+    return undefined;
+}

package/dist/contract.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Contrato público do core (ADR-005).
+ *
+ * FRONTEIRA (boundary): este é o ÚNICO módulo que as superfícies (TUI, CLI, MCP)
+ * devem importar para consumir o core. Nenhuma superfície acessa os módulos
+ * internos (`src/client`, `src/normalize`, `src/extract`, `src/bundle`,
+ * `src/config`, `src/cache`) diretamente — o acoplamento se dá exclusivamente
+ * por estes tipos e pelo padrão `AsyncIterable<ProgressEvent | Result>`.
+ * A regra eslint `no-restricted-imports` (escopo `src/surfaces/**`) reforça isso.
+ */
+/** Referência nomeada do Redmine (`{ id, name }`) — projeto, tracker, status, usuário, etc. */
+export interface RedmineRef {
+    id: number;
+    name: string;
+}
+/**
+ * Custom field normalizado — SEM coerção de tipo (ADR-005).
+ * `raw_value` preserva o valor bruto exatamente como a API devolveu (incl. `null`
+ * ou `""` em campo vazio); em campos "multiple" é `string[]`.
+ * `value` normaliza apenas ausência: `""`/`null`/ausente → `null`. Nada além disso.
+ */
+export interface CustomField {
+    id: number;
+    name: string;
+    value: string | string[] | null;
+    raw_value: string | string[] | null;
+    field_format?: string;
+}
+/** Detalhe bruto de um journal (histórico de status/atributos), sem interpretação. */
+export interface JournalDetail {
+    property: string;
+    name: string;
+    old_value?: string | null;
+    new_value?: string | null;
+}
+/** Entrada de journal: nota opcional + `details[]` brutos. */
+export interface Journal {
+    id: number;
+    notes?: string;
+    created_on: string;
+    user?: RedmineRef;
+    details: JournalDetail[];
+}
+/** Anexo normalizado; `digest` é opcional (nem sempre presente na API). */
+export interface Attachment {
+    id: number;
+    filename: string;
+    filesize: number;
+    content_type?: string;
+    description?: string;
+    author?: RedmineRef;
+    created_on: string;
+    content_url: string;
+    digest?: string;
+}
+/** Relação entre issues: `relation_type` + `delay` (ADR-005). */
+export interface IssueRelation {
+    id: number;
+    issue_id: number;
+    issue_to_id: number;
+    relation_type: string;
+    delay?: number | null;
+}
+/** Referência a uma issue-filha (parent/children). */
+export interface IssueChild {
+    id: number;
+    tracker?: RedmineRef;
+    subject?: string;
+}
+/** Issue normalizada — modelo estável consumido pelas superfícies. */
+export interface Issue {
+    id: number;
+    subject: string;
+    description?: string;
+    project: RedmineRef;
+    tracker: RedmineRef;
+    status: RedmineRef;
+    priority: RedmineRef;
+    author: RedmineRef;
+    assigned_to?: RedmineRef;
+    created_on: string;
+    updated_on: string;
+    done_ratio?: number;
+    start_date?: string;
+    due_date?: string;
+    custom_fields: CustomField[];
+    journals: Journal[];
+    attachments: Attachment[];
+    relations: IssueRelation[];
+    parent?: {
+        id: number;
+    };
+    children: IssueChild[];
+    /** Opcional: pode faltar por degradação em 403 (ADR-005). */
+    watchers?: RedmineRef[];
+}
+/**
+ * Status de uma extração de anexo (ADR-005 — pipeline de extração, M3/M4).
+ *
+ * Vocabulário único e canônico do core; as superfícies (TUI/CLI/MCP) apenas o
+ * consomem. Ver a migração documentada em `src/surfaces/tui/attachment-status.ts`.
+ *
+ * - `text` — anexo textual (o conteúdo já É o texto, sem OCR/ASR).
+ * - `pending` — enfileirado/aguardando, ainda não processado.
+ * - `processing` — extração em andamento (job assíncrono).
+ * - `done` — extração concluída; `text` (e/ou `artifacts`) disponível(is).
+ * - `failed` — extração tentada e falhou (ver `metadata.reason`).
+ * - `cancelled` — extração cancelada via `AbortSignal` (o subprocesso foi morto
+ *   ou o job pendente não chegou a iniciar) (#69, ADR-005).
+ * - `unsupported` — não há extrator registrado para o MIME REAL do arquivo.
+ * - `skipped` — pulado deliberadamente (ex.: excede o limite de tamanho, ADR-002).
+ */
+export type ExtractionStatus = 'text' | 'pending' | 'processing' | 'done' | 'failed' | 'cancelled' | 'unsupported' | 'skipped';
+/**
+ * Artefato derivado de uma extração (arquivo produzido e cacheado ao lado do
+ * `original` do anexo, ADR-004) — ex.: transcrição, texto de página, thumbnail.
+ */
+export interface ExtractionArtifact {
+    /** Tipo do artefato (ex.: `transcript`, `page-text`, `thumbnail`). */
+    kind: string;
+    /** Caminho absoluto do artefato no cache local. */
+    path: string;
+    /** MIME do artefato, quando conhecido. */
+    mime?: string;
+}
+/**
+ * Resultado de uma extração de anexo (ADR-005).
+ *
+ * `status` é sempre presente; `text`/`confidence`/`artifacts` são preenchidos
+ * conforme o extrator e o status (ex.: `done` traz `text`; `unsupported`/
+ * `skipped` trazem apenas `status` + `metadata`). `mime` carrega o MIME REAL
+ * detectado por magic bytes (NUNCA por extensão/Content-Type).
+ */
+export interface ExtractionResult {
+    /** Estado final/atual da extração. */
+    status: ExtractionStatus;
+    /** Texto extraído (quando `status === 'text'` ou `'done'`). */
+    text?: string;
+    /** Confiança da extração em [0, 1] (ex.: score de OCR/ASR). */
+    confidence?: number;
+    /** Artefatos derivados produzidos pela extração. */
+    artifacts?: ExtractionArtifact[];
+    /** MIME REAL detectado por magic bytes do arquivo baixado. */
+    mime?: string;
+    /** Metadados livres (ex.: `extractorId`, `version`, `reason`, `declaredMime`). */
+    metadata?: Record<string, unknown>;
+}
+/** Evento de progresso incremental emitido durante uma operação longa. */
+export interface ProgressEvent {
+    kind: 'progress';
+    stage: string;
+    message: string;
+}
+/** Resultado final de uma operação. Sempre o último item do iterable. */
+export interface Result<T> {
+    kind: 'result';
+    value: T;
+}
+/** União discriminada consumida pelas superfícies. */
+export type CoreEvent<T> = ProgressEvent | Result<T>;
+/**
+ * Operação de exemplo que fixa o padrão de consumo do core.
+ *
+ * Não implementa nenhum client real — apenas demonstra o contrato:
+ * emite progresso incremental e finaliza com um único `Result`.
+ *
+ * @returns Sequência assíncrona de progresso terminada por um Result.
+ * @example
+ * for await (const event of demoOperation()) {
+ *   if (event.kind === 'result') console.log(event.value);
+ * }
+ */
+export declare function demoOperation(): AsyncIterable<ProgressEvent | Result<string>>;

package/dist/contract.js

@@ -0,0 +1,27 @@
+/**
+ * Contrato público do core (ADR-005).
+ *
+ * FRONTEIRA (boundary): este é o ÚNICO módulo que as superfícies (TUI, CLI, MCP)
+ * devem importar para consumir o core. Nenhuma superfície acessa os módulos
+ * internos (`src/client`, `src/normalize`, `src/extract`, `src/bundle`,
+ * `src/config`, `src/cache`) diretamente — o acoplamento se dá exclusivamente
+ * por estes tipos e pelo padrão `AsyncIterable<ProgressEvent | Result>`.
+ * A regra eslint `no-restricted-imports` (escopo `src/surfaces/**`) reforça isso.
+ */
+/**
+ * Operação de exemplo que fixa o padrão de consumo do core.
+ *
+ * Não implementa nenhum client real — apenas demonstra o contrato:
+ * emite progresso incremental e finaliza com um único `Result`.
+ *
+ * @returns Sequência assíncrona de progresso terminada por um Result.
+ * @example
+ * for await (const event of demoOperation()) {
+ *   if (event.kind === 'result') console.log(event.value);
+ * }
+ */
+export async function* demoOperation() {
+    yield { kind: 'progress', stage: 'start', message: 'iniciando operação' };
+    yield { kind: 'progress', stage: 'work', message: 'processando' };
+    yield { kind: 'result', value: 'done' };
+}

package/dist/core.d.ts

@@ -0,0 +1 @@
+export declare const CORE_MODULES: readonly ["client", "normalize", "extract", "bundle", "config", "cache"];

package/dist/core.js

@@ -0,0 +1,8 @@
+import { MODULE_NAME as bundle } from './bundle/index.js';
+import { MODULE_NAME as cache } from './cache/index.js';
+import { MODULE_NAME as client } from './client/index.js';
+import { MODULE_NAME as config } from './config/index.js';
+import { MODULE_NAME as extract } from './extract/index.js';
+import { MODULE_NAME as normalize } from './normalize/index.js';
+// Os 6 módulos do core, na ordem das camadas do ADR-005.
+export const CORE_MODULES = [client, normalize, extract, bundle, config, cache];