shade-sdk 0.1.0__py3-none-any.whl

shade_sdk/__init__.py

@@ -0,0 +1,5 @@
+"""shade-sdk: o runtime dos robôs da ShadeOne (ADR 019)."""
+
+#: Semver próprio do SDK (ADR 019, D10), desacoplado da versão da plataforma. Subir aqui pede
+#: regenerar a wheel e o lock da imagem: `uv run python scripts/gerar_lock_do_sandbox.py`.
+__version__ = "0.1.0"

shade_sdk/runtime/__init__.py

@@ -0,0 +1,33 @@
+"""O que roda dentro do robô: ledger, recuperação, relatório, configuração e saída.
+
+Os nomes que o robô gerado usa ficam reexportados aqui (``from shade_sdk.runtime import
+Settings``), mas o import de cada módulo é preguiçoso: ``config`` carrega o ``.env`` do
+diretório corrente e ``ledger`` liga o canal do registro quando ``SHADE_REGISTRO_DIR`` existe,
+e quem só precisa do número do protocolo (o executor da plataforma) não deve disparar nada
+disso.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+#: nome reexportado → o módulo de ``shade_sdk.runtime`` que o define.
+_REEXPORTADOS = {
+    "_CanalDoRegistro": "ledger",
+    "_RegistroAntesDeEfetivar": "ledger",
+    "RecoveryStopError": "recovery",
+    "append_historico": "report",
+    "generate_report": "report",
+    "Settings": "config",
+    "RUNTIME_PROTOCOL": "protocolo",
+}
+
+__all__ = sorted(_REEXPORTADOS)
+
+
+def __getattr__(nome: str) -> Any:
+    modulo = _REEXPORTADOS.get(nome)
+    if modulo is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {nome!r}")
+    return getattr(importlib.import_module(f"{__name__}.{modulo}"), nome)

shade_sdk/runtime/config.py

@@ -0,0 +1,76 @@
+"""Configurações do robô: ``Settings`` e a carga do ``.env`` para o ambiente do processo.
+
+Era ``runtime_templates/config_runtime.py`` no backend, copiado como ``src/config.py`` do
+projeto gerado; desde a HU-29.1 o ``src/config.py`` gerado reexporta daqui. Importar este
+módulo carrega o ``.env`` do diretório corrente (``_load_env_file``), como antes: é o que leva
+credenciais, ``TELEMETRY_*`` e ``RECOVERY_*`` para o ``os.getenv`` do robô.
+"""
+
+import os
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+
+def _load_env_file(path: str = ".env") -> None:
+    """Carrega o .env para o ambiente do processo.
+
+    O Settings abaixo já lê o .env — mas SÓ para os campos declarados nele.
+    Todo o resto que o bot lê com os.getenv (credenciais, TELEMETRY_*, SMTP_* /
+    NOTIFY_EMAIL_TO, RECOVERY_*, SMOKE_TARGET_URL) chegava VAZIO quando
+    configurado no .env, que é exatamente o que o .env.example e o README mandam
+    preencher: nada neste projeto levava o arquivo para o ambiente.
+
+    Precedência: variável já presente no ambiente VENCE o arquivo — quem exporta
+    no shell ou no agendador manda mais que o .env commitado ao lado do bot.
+    """
+    env_path = Path(path)
+    if not env_path.exists():
+        return
+    for raw_line in env_path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        if key and key not in os.environ:
+            os.environ[key] = value.strip().strip('"').strip("'")
+
+
+# Roda no import de src.config — antes de qualquer Settings() ou os.getenv do bot.
+_load_env_file()
+
+
+class Settings(BaseSettings):
+    """Configurações carregadas de variáveis de ambiente / .env"""
+
+    # Execução
+    environment: str = Field(default="development", alias="ENVIRONMENT")
+    log_level: str = Field(default="INFO", alias="LOG_LEVEL")
+    default_timeout_ms: int = Field(default=30_000, alias="DEFAULT_TIMEOUT_MS")
+    dry_run: bool = Field(default=False, alias="DRY_RUN")
+
+    # Browser
+    headless: bool = Field(default=False, alias="HEADLESS")
+    base_url: str = Field(default="", alias="BASE_URL")
+
+    # Credenciais (preencher no .env — nunca hardcoded)
+    # username: str = Field(default="", alias="SHADE_USERNAME")
+    # password: str = Field(default="", alias="SHADE_PASSWORD")
+
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+        case_sensitive = False
+        # O .env carrega MAIS do que estes campos — credenciais lidas via
+        # os.getenv (APP_PASSWORD...), TELEMETRY_*, DB_PATH, NOTIFY_EMAIL_TO,
+        # tokens de API. O default do pydantic-settings é "forbid", e um .env
+        # com qualquer uma dessas chaves derrubava o bot em Settings(), na
+        # primeira linha de run_automation. Extra ignorado: quem lê essas
+        # variáveis é o código que as declara.
+        extra = "ignore"
+
+    @property
+    def is_production(self) -> bool:
+        return self.environment.lower() == "production"

shade_sdk/runtime/ledger.py

@@ -0,0 +1,505 @@
+"""Idempotência do bot gerado — identidade do item por CHAVE DE NEGÓCIO.
+
+**O problema.** A retomada de lote (``BATCH_RESUME``) guardava o **índice** da
+linha em ``data/checkpoint.json``. Índice é âncora **posicional**: basta a fila
+ganhar uma linha no topo — comportamento normal de uma fila de pedidos — para o
+índice N passar a apontar para outra transação. O bot então **pula a nova e
+recadastra a já feita**. É a mesma armadilha que a validação ao vivo corrigiu nos
+seletores (linha de grade ancorada por CONTEÚDO, não por posição — #700).
+
+**A correção.** A identidade do item passa a ser derivada do que ele É:
+
+1. as **colunas-chave** que a pessoa escolheu na Revisão (nº do pedido,
+   documento…), quando escolhidas; ou
+2. o **conteúdo inteiro** do item (todos os campos), quando não há escolha.
+
+Ambas sobrevivem a reordenação e a inserção. O índice **não** é usado em nenhum
+dos dois caminhos — nem como fallback: cair na posição no meio de um lote
+reordenado é justamente o defeito.
+
+**Ordinal entre itens idênticos.** Duas linhas rigorosamente iguais são dois
+pedidos, não um. A chave carrega o ordinal do item entre os idênticos do mesmo
+lote (``identidade#2``), o que é estável sob reordenação (um multiconjunto não
+tem ordem) e evita engolir a segunda ocorrência.
+
+**PII.** A chave pode ser um documento (CPF/CNPJ). No ledger vai só o
+``sha256`` — ``checkpoint.json`` é um arquivo de diagnóstico, costuma ser aberto
+e enviado em suporte, e não deve carregar o dado. Não é anonimização forte (quem
+tem a planilha recomputa o hash); é a mesma disciplina de não deixar o dado
+viajar para onde ele não precisa estar. O rastro **legível** fica no arquivo de
+controle ao lado da entrada, que já vive na mesma zona de confiança da planilha.
+
+**Versionamento.** O ledger v2 é um objeto ``{version, key_fields, done}``. O
+formato v1 (lista crua de índices) é **migrado**, não descartado: o índice N vira
+a chave da linha N do lote atual — exatamente o que a v1 teria pulado.
+
+
+---
+
+Era ``runtime_templates/idempotency_runtime.py`` no backend, colado por marcador dentro do
+``main.py`` gerado; desde a HU-29.1 o robô o importa daqui. O ``main.py`` gerado configura os
+campos-chave com ``_configurar_ledger`` (a escolha da Revisão) e importa os nomes que usa.
+"""
+
+from __future__ import annotations
+
+import json
+
+from loguru import logger
+
+from shade_sdk.runtime.protocolo import (
+    CAMPOS,
+    DIGITOS_DA_SEQUENCIA,
+    OP_DESFAZER,
+    OP_FEITO,
+    OP_INCERTO,
+    PEDIDOS,
+    POLLING_DA_RESPOSTA_SECONDS,
+    RESPOSTAS,
+    VARIAVEL_DA_PASTA,
+    VIVO,
+)
+
+_CHECKPOINT_PATH = "data/checkpoint.json"
+_CHECKPOINT_VERSION = 3
+# Campos que identificam um item (escolha da pessoa na Revisão). Vazio → a
+# identidade é o conteúdo inteiro do item. Quem muda é ``_configurar_ledger``.
+_KEY_FIELDS: tuple = ()
+
+
+def _configurar_ledger(*, key_fields: tuple = ()) -> None:
+    """Os campos-chave do item, antes do primeiro uso do ledger.
+
+    O ``main.py`` gerado chama no import, com a coluna-chave escolhida na Revisão. Trocar a
+    chave depois de gravar o ledger o invalida inteiro (``_load_checkpoint`` para).
+    """
+    global _KEY_FIELDS
+    _KEY_FIELDS = tuple(key_fields)
+
+
+def _item_identity(row: dict) -> str:
+    """Identidade de NEGÓCIO do item — nunca a posição na fila.
+
+    Com colunas-chave escolhidas, a identidade são os valores delas. Sem escolha,
+    é o conteúdo inteiro do item: também sobrevive a reordenação e a inserção de
+    linhas, ao contrário do índice. Campos internos (``_item_index``,
+    ``_status``…) ficam de fora — ``_item_index`` É a posição, e deixá-lo entrar
+    reintroduziria o defeito pela porta dos fundos.
+
+    String vazia = não dá para identificar este item (o chamador avisa e NÃO pula).
+    """
+    if _KEY_FIELDS:
+        parts = [str(row.get(f, "") or "").strip() for f in _KEY_FIELDS]
+        if any(parts):
+            return "\x1f".join(parts)
+    return "\x1f".join(
+        f"{k}={row[k]}" for k in sorted(row) if not str(k).startswith("_") and str(row[k]).strip()
+    )
+
+
+def _item_digest(identity: str, occurrences: dict) -> str:
+    """Chave do item no ledger: identidade + ordinal entre itens IDÊNTICOS do lote.
+
+    Duas linhas rigorosamente iguais são dois pedidos, não um. O ordinal é estável
+    sob reordenação (itens idênticos não têm ordem entre si).
+
+    PII: só o sha256 vai para o ledger — ``checkpoint.json`` costuma ser aberto e
+    enviado num diagnóstico, e a chave pode ser um documento.
+    """
+    if not identity:
+        return ""
+    import hashlib
+
+    occurrences[identity] = occurrences.get(identity, 0) + 1
+    return hashlib.sha256(f"{identity}#{occurrences[identity]}".encode()).hexdigest()
+
+
+def _ledger_ilegivel(path: str, motivo: str):
+    """O ledger existe mas não dá para confiar nele. PARA, com saída acionável.
+
+    Devolver "nenhum item foi feito" seria fail-OPEN: o lote inteiro voltaria ao
+    sistema do cliente. E a hora em que isso aconteceria é exatamente a hora em que
+    a retomada mais importa — um ledger truncado vem de um processo morto no meio
+    (Ctrl+C, queda de energia, agendador matando o job). Transformar "fui
+    interrompido" em "recadastrei tudo" é o defeito que esta camada existe para
+    matar; a mesma escolha fail-closed da troca de chave vale aqui.
+    """
+    return RuntimeError(
+        f"Nao da para confiar no controle de itens ja feitos em {path}: {motivo}. "
+        f"Rodar assim recadastraria itens que ja foram processados. Guarde o arquivo "
+        f"para diagnostico e: apague-o + rode com --reprocessar-tudo se aceita refazer "
+        f"o lote inteiro, ou restaure uma copia boa do arquivo."
+    )
+
+
+def _load_checkpoint(path: str, rows: list):
+    """Lê o ledger. Devolve ``(feitos, incertos)``. Ausente → vazios; ilegível → para.
+
+    ``incertos`` são itens cuja EFETIVAÇÃO rodou sem que o resultado tenha sido
+    confirmado. Não são "por fazer" (refazer duplica) nem "feitos" (dar por feito
+    perde trabalho em silêncio) — ficam retidos até uma pessoa conferir.
+    """
+    try:
+        with open(path, encoding="utf-8") as _cf:
+            data = json.load(_cf)
+    except FileNotFoundError:
+        return set(), set()
+    except Exception as _exc:  # noqa: BLE001
+        raise _ledger_ilegivel(path, f"nao foi possivel ler o arquivo ({_exc})") from None
+    if isinstance(data, list):
+        # v1: lista de ÍNDICES. Migra para chave de negócio pela posição no lote
+        # atual — exatamente o que a v1 teria pulado. Índice sem linha some.
+        _occ: dict = {}
+        _by_index = {
+            _i: _item_digest(_item_identity(_r), _occ) for _i, _r in enumerate(rows or [], start=1)
+        }
+        done = {_by_index[_i] for _i in data if isinstance(_i, int) and _by_index.get(_i)}
+        logger.warning(
+            f"Checkpoint no formato antigo (por posicao) convertido para chave de negocio: "
+            f"{len(done)} de {len(data)} item(ns) preservado(s). A partir daqui a retomada "
+            f"sobrevive a reordenacao da fila."
+        )
+        return done, set()
+    # Daqui para baixo, toda forma inesperada é ledger ilegível — não "vazio".
+    # Cada `isinstance` abaixo já mordeu na auditoria: `done` como número derrubava
+    # o bot com TypeError cru, e `key_fields` como número idem.
+    if not isinstance(data, dict):
+        raise _ledger_ilegivel(path, "o conteudo nao e um registro de controle")
+    _versao = data.get("version")
+    if _versao == 2:
+        # v2 não tinha a lista de incertos. Aceita e sobe para v3 na próxima
+        # gravação: o que existe lá é "feito", que continua valendo.
+        data = dict(data, incerto=[])
+    elif _versao != _CHECKPOINT_VERSION:
+        raise _ledger_ilegivel(path, f"versao desconhecida ({_versao!r})")
+    _raw_fields = data.get("key_fields")
+    _raw_done = data.get("done")
+    _raw_incerto = data.get("incerto", [])
+    if (
+        not isinstance(_raw_fields, list)
+        or not isinstance(_raw_done, list)
+        or not isinstance(_raw_incerto, list)
+    ):
+        raise _ledger_ilegivel(path, "os campos de controle estao com o formato errado")
+    _stored = [str(f) for f in _raw_fields]
+    if _stored != [str(f) for f in _KEY_FIELDS]:
+        # Trocar a chave invalida o ledger inteiro: os hashes gravados não têm como
+        # casar. Parar é a escolha segura — seguir em silêncio recadastraria tudo.
+        raise _ledger_ilegivel(
+            path,
+            f"ele foi gravado com outra chave de identificacao "
+            f"({_stored or 'conteudo da linha'} != {list(_KEY_FIELDS) or 'conteudo da linha'})",
+        )
+    return (
+        {str(k) for k in _raw_done if str(k)},
+        {str(k) for k in _raw_incerto if str(k)},
+    )
+
+
+def _save_checkpoint(path: str, done: set, incerto: set = frozenset()) -> bool:
+    """Persiste o ledger de forma idempotente (reescrita completa, ordenada).
+
+    ESCRITA ATÔMICA (arquivo temporário + ``os.replace``). A reescrita direta roda
+    a cada item concluído, então a janela em que o arquivo fica truncado é
+    percorrida dezenas de vezes num lote — e morrer dentro dela deixava um JSON
+    pela metade, justamente na interrupção que a retomada existe para cobrir.
+    ``os.replace`` é atômico em POSIX e Windows: ou o ledger antigo, ou o novo.
+
+    DURÁVEL: o conteúdo vai ao disco (``fsync`` do temporário) antes da troca,
+    e a troca também (``_fsync_do_diretorio``). O registro feito ANTES de
+    efetivar (``_RegistroAntesDeEfetivar``) precisa sobreviver até a uma queda
+    de energia na máquina de quem roda o robô.
+
+    Devolve se gravou: quem registra antes de efetivar não efetiva sem o registro.
+    """
+    try:
+        import os as _os
+
+        _os.makedirs(_os.path.dirname(path) or ".", exist_ok=True)
+        _tmp = path + ".tmp"
+        with open(_tmp, "w", encoding="utf-8") as _cf:
+            json.dump(
+                {
+                    "version": _CHECKPOINT_VERSION,
+                    "key_fields": [str(f) for f in _KEY_FIELDS],
+                    "done": sorted(done),
+                    "incerto": sorted(incerto),
+                },
+                _cf,
+            )
+            _cf.flush()
+            _os.fsync(_cf.fileno())
+        _os.replace(_tmp, path)
+    except Exception as _exc:  # noqa: BLE001
+        # ERRO, não aviso: o ledger ficou para trás do que aconteceu. Se isto se
+        # repetir (disco cheio, permissao), a proxima execucao nao sabe o que ja
+        # passou por aqui.
+        logger.error(
+            f"Falha ao gravar o controle de itens ja feitos em {path}: {_exc}. "
+            f"Os itens a partir daqui PODEM ser refeitos ou ficar retidos para "
+            f"conferencia na proxima execucao — resolva antes de rodar de novo."
+        )
+        return False
+    _fsync_do_diretorio(path)
+    return True
+
+
+def _fsync_do_diretorio(path: str) -> None:
+    """``fsync`` do diretório do ledger, depois do ``os.replace``.
+
+    Sem ele, uma queda de energia logo depois da troca pode deixar o diretório
+    apontando para o ledger ANTIGO, sem o registro feito antes de efetivar, e a
+    retomada refaria o item. É melhor esforço: o Windows não abre diretório, e há
+    filesystem que recusa o ``fsync`` dele (alguns FUSE, o bind mount do Docker
+    Desktop). Aí fica o que o sistema já garante: a troca continua atômica, e
+    contra o processo morto (SIGKILL) o cache do kernel já basta.
+
+    Nunca levanta, nem no ``close``: ``_save_checkpoint`` não levanta, e quem o
+    chama no ``except`` do guard ou depois do "Criado" conta com isso.
+    """
+    import os as _os
+
+    try:
+        _fd = _os.open(_os.path.dirname(path) or ".", _os.O_RDONLY)
+    except OSError:
+        return
+    try:
+        _os.fsync(_fd)
+    except OSError:
+        pass
+    try:
+        _os.close(_fd)
+    except OSError:
+        pass
+
+
+class _RegistroAntesDeEfetivar:
+    """Registra o item como INCERTO no ledger ANTES de despachar a efetivação
+    (write-ahead), para a morte do processo depois do efeito não fazer a
+    retomada refazê-lo.
+
+    Até aqui o ``incerto`` só chegava ao ledger no ``except`` do guard do item,
+    com o processo vivo. Um SIGKILL entre o clique de salvar e o registro de
+    ``feito`` (parada por perda de posse, OOM, estouro de tempo, queda do
+    runner) deixava o ledger sem o item, e a retomada o refazia: pedido
+    duplicado no sistema do cliente. Com o registro antes, a retomada o RETÉM
+    para conferência, o mesmo destino da efetivação que não confirmou.
+
+    - Chamar (o gancho ``antes_de_efetivar`` do método de página, depois das
+      esperas e imediatamente antes do despacho) registra e grava. Sem gravar,
+      LEVANTA: efetivar sem o registro reabriria a janela.
+    - ``desfazer()`` é do processo VIVO que viu a chamada de efetivação levantar
+      antes de retornar: o caso comum é o Playwright recusar a acionabilidade
+      antes de despachar, e o item volta para a fila. Tira só o que ESTA
+      instância marcou: num item com dois passos de efetivação, a falha do
+      segundo não apaga a marca do primeiro.
+    - Item sem chave (digest vazio) não tem o que registrar, como no resto do
+      ledger.
+    """
+
+    def __init__(self, path: str, done: set, incerto: set, digest: str) -> None:
+        self.path = path
+        self.done = done
+        self.incerto = incerto
+        self.digest = digest
+        self.marcou = False
+
+    def __call__(self) -> None:
+        if not self.digest or self.digest in self.incerto:
+            return
+        if _CANAL_DO_REGISTRO is not None:
+            # Na plataforma (HU-17.7), o servidor decide ANTES do registro local: gravar o
+            # incerto aqui primeiro deixaria no arquivo uma duvida que nunca efetivou a cada
+            # oscilacao da API.
+            _resposta = _CANAL_DO_REGISTRO.pedir(self.digest)
+            if _resposta == "feita":
+                self.done.add(self.digest)
+                _save_checkpoint(self.path, self.done, self.incerto)
+                raise _JaFeitoNoServidor(self.digest)
+            if _resposta == "retida":
+                self.incerto.add(self.digest)
+                _save_checkpoint(self.path, self.done, self.incerto)
+                raise _RetidoNoServidor(self.digest)
+            if _resposta not in ("registrada", "seguir"):
+                raise _RegistroIndisponivel(_resposta)
+        self.incerto.add(self.digest)
+        if not _save_checkpoint(self.path, self.done, self.incerto):
+            self.incerto.discard(self.digest)
+            if _CANAL_DO_REGISTRO is not None:
+                _CANAL_DO_REGISTRO.enfileirar(OP_DESFAZER, self.digest)
+            raise RuntimeError(
+                f"Nao foi possivel registrar o item em {self.path} antes de efetivar: "
+                f"sem esse registro, uma interrupcao agora faria o item ser refeito na "
+                f"retomada. O item NAO foi efetivado."
+            )
+        self.marcou = True
+
+    def desfazer(self) -> None:
+        if not self.marcou:
+            return
+        self.marcou = False
+        self.incerto.discard(self.digest)
+        _save_checkpoint(self.path, self.done, self.incerto)
+        if _CANAL_DO_REGISTRO is not None:
+            _CANAL_DO_REGISTRO.enfileirar(OP_DESFAZER, self.digest)
+
+
+# ── Registro no servidor (HU-17.7, ADR 012) ──────────────────────────────────
+# Na plataforma, o executor injeta SHADE_REGISTRO_DIR e o robo pede o registro de
+# cada item ANTES de efetivar, por arquivos nessa pasta (o sandbox nao tem rede para
+# a plataforma). Sem a variavel (o robo rodando na maquina de quem o baixou, o
+# ensaio, o smoke), nada disto liga: so o ledger local, como sempre.
+
+#: Quanto o robo espera a resposta de um registro: o executor atende em serie, e um
+#: feito ainda subindo (ate 40 s) vem antes do incerto (outros 40 s). Abaixo da posse
+#: do run (120 s) menos a margem com que o executor para o container (30 s).
+_PRAZO_DO_REGISTRO = 85.0
+#: Sem o executor dar sinal de vida por este tempo, o robo se encerra: um executor
+#: morto nao renova a posse, e outro pode estar rodando o run.
+_SEM_VIDA_DO_EXECUTOR = 30.0
+_REGISTRO_PAROU = []
+
+
+class _JaFeitoNoServidor(BaseException):
+    """O servidor ja tem o item como feito: pular, sem efetivar.
+
+    BaseException, e nao Exception: a re-tentativa por passo e a recuperacao do item
+    capturam Exception, e uma delas faria o item seguir (ou ser dado por feito)."""
+
+
+class _RetidoNoServidor(BaseException):
+    """Uma execucao anterior comecou a efetivar o item e nao confirmou: fica retido
+    para conferencia, sem efetivar."""
+
+
+class _RegistroIndisponivel(BaseException):
+    """O registro nao respondeu (ou recusou): o robo para sem efetivar. Sem o
+    registro, uma interrupcao agora faria o item ser refeito."""
+
+    def __init__(self, motivo: str) -> None:
+        super().__init__(motivo)
+        _REGISTRO_PAROU.append(motivo)
+
+
+class _CanalDoRegistro:
+    """Os pedidos ao executor, um arquivo por pedido, numerados em ordem."""
+
+    def __init__(self, pasta: str) -> None:
+        import os as _os
+        import threading as _th
+
+        self.pasta = pasta
+        self.pedidos = _os.path.join(pasta, PEDIDOS)
+        self.respostas = _os.path.join(pasta, RESPOSTAS)
+        self.seq = 0
+        self.campos_gravados = False
+        self._trava = _th.Lock()
+
+    def _escrever(self, op: str, chave: str) -> int:
+        import os as _os
+
+        with self._trava:
+            if not self.campos_gravados:
+                _tmp = _os.path.join(self.pasta, ".campos.tmp")
+                with open(_tmp, "w", encoding="utf-8") as _f:
+                    json.dump([str(f) for f in _KEY_FIELDS], _f)
+                _os.replace(_tmp, _os.path.join(self.pasta, CAMPOS))
+                self.campos_gravados = True
+            # O numero so avanca depois de o pedido existir: um pedido que nao gravou nao
+            # deixa buraco na sequencia (o executor recusaria o registro esperando por ele).
+            _seq = self.seq + 1
+            _nome = f"{_seq:0{DIGITOS_DA_SEQUENCIA}d}.json"
+            _tmp = _os.path.join(self.pedidos, "." + _nome + ".tmp")
+            with open(_tmp, "w", encoding="utf-8") as _f:
+                json.dump({"op": op, "key": chave}, _f)
+            _os.replace(_tmp, _os.path.join(self.pedidos, _nome))
+            self.seq = _seq
+            return _seq
+
+    def pedir(self, chave: str) -> str:
+        """Pede o registro do item como incerto e espera a resposta."""
+        import os as _os
+        import time as _t
+
+        try:
+            _seq = self._escrever(OP_INCERTO, chave)
+        except Exception as _exc:  # noqa: BLE001
+            return f"pedido nao gravou ({_exc})"
+        _arquivo = _os.path.join(self.respostas, f"{_seq:0{DIGITOS_DA_SEQUENCIA}d}.json")
+        _limite = _t.monotonic() + _PRAZO_DO_REGISTRO
+        while _t.monotonic() < _limite:
+            try:
+                with open(_arquivo, encoding="utf-8") as _f:
+                    _resposta = str(json.load(_f).get("r", ""))
+            except FileNotFoundError:
+                _t.sleep(POLLING_DA_RESPOSTA_SECONDS)
+                continue
+            except Exception:  # noqa: BLE001
+                _resposta = "resposta ilegivel"
+            try:
+                _os.remove(_arquivo)
+            except OSError:
+                pass
+            return _resposta
+        return "sem resposta"
+
+    def enfileirar(self, op: str, chave: str) -> None:
+        """O feito e o desfazer: sem esperar, e sem nunca levantar (o item ja esta
+        decidido; a falha so deixa a duvida no servidor, do lado seguro)."""
+        try:
+            self._escrever(op, chave)
+        except Exception as _exc:  # noqa: BLE001
+            logger.warning(f"Registro de {op} do item nao gravou: {_exc}")
+
+
+def _vigiar_o_executor(pasta: str) -> None:
+    """Encerra o robo se o executor parar de dar sinal de vida (o arquivo `vivo`
+    deixa de mudar): sem executor, ninguem segura a posse do run."""
+    import os as _os
+    import time as _t
+
+    _arquivo = _os.path.join(pasta, VIVO)
+    _visto = None
+    _desde = _t.monotonic()
+    while True:
+        try:
+            with open(_arquivo, encoding="ascii") as _f:
+                _valor = _f.read()
+        except Exception:  # noqa: BLE001
+            _valor = None
+        if _valor != _visto:
+            _visto, _desde = _valor, _t.monotonic()
+        elif _t.monotonic() - _desde > _SEM_VIDA_DO_EXECUTOR:
+            logger.error(
+                "O executor deixou de dar sinal de vida: o robo para aqui, sem efetivar "
+                "mais nada (outro executor pode retomar a execucao)."
+            )
+            _os._exit(75)
+        _t.sleep(1)
+
+
+def _iniciar_o_registro():
+    import os as _os
+
+    _pasta = _os.environ.get(VARIAVEL_DA_PASTA)
+    if not _pasta:
+        return None
+    import threading as _th
+
+    _th.Thread(target=_vigiar_o_executor, args=(_pasta,), daemon=True).start()
+    return _CanalDoRegistro(_pasta)
+
+
+_CANAL_DO_REGISTRO = _iniciar_o_registro()
+
+
+def _concluir_item(path: str, done: set, incerto: set, digest: str) -> None:
+    """O item foi feito (ou dado por feito): sai da duvida, entra no ledger local e,
+    na plataforma, o feito vai para o servidor."""
+    if not digest:
+        return
+    done.add(digest)
+    incerto.discard(digest)
+    _save_checkpoint(path, done, incerto)
+    if _CANAL_DO_REGISTRO is not None:
+        _CANAL_DO_REGISTRO.enfileirar(OP_FEITO, digest)

shade_sdk/runtime/output.py

@@ -0,0 +1,136 @@
+"""A planilha de saída do robô: ``data/output.xlsx`` (ou ``.csv`` sem ``openpyxl``).
+
+Duas variantes, como no gerador: ``_write_output`` grava como veio; ``_write_output_com_pii``
+aplica a decisão de PII por coluna (Fronteira 3, LGPD): ``drop_cols`` não são gravadas e
+``mask_cols`` passam por ``_mask_pii``. O mascaramento acontece na fronteira de gravação, e o
+valor em memória segue real. O ``main.py`` gerado importa uma das duas com o nome
+``_write_output``.
+
+Coluna ``_status`` → cabeçalho "Status"; a ordem é: colunas de entrada | Status | capturadas.
+
+Era ``runtime_templates/output_writer_runtime.py`` e ``output_writer_pii_runtime.py`` no
+backend, colados dentro do ``main.py`` gerado; desde a HU-29.1 o robô os importa daqui.
+"""
+
+from __future__ import annotations
+
+import csv
+import os
+
+from loguru import logger
+
+
+def _csv_celula_segura(v):
+    """Escape pelo formato: o Excel calcula célula de CSV iniciada por = + - @ (ou
+    tab/CR). Prefixa com apóstrofo; número puro ("-5") segue intacto."""
+    if isinstance(v, str) and v[:1] in ("=", "+", "-", "@", "\t", "\r"):
+        try:
+            float(v)
+        except ValueError:
+            return "'" + v
+    return v
+
+
+def _write_output(results: list[dict], path: str = "data/output.xlsx") -> None:
+    """Grava planilha de saída: colunas de entrada + Status + valores capturados."""
+    if not results:
+        return
+    fields: list[str] = []
+    for r in results:
+        for k in r:
+            if k not in fields:
+                fields.append(k)
+    header = ["Status" if f == "_status" else f for f in fields]
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    try:
+        import openpyxl as _xl
+
+        wb = _xl.Workbook()
+        ws = wb.active
+        ws.append(header)
+        for r in results:
+            ws.append([r.get(f, "") for f in fields])
+        # Escape pelo formato: o openpyxl grava como FÓRMULA todo texto iniciado por
+        # "=" (dado do sistema-alvo); o Excel do cliente a calcularia ao abrir.
+        for _linha in ws.iter_rows():
+            for _c in _linha:
+                if _c.data_type == "f":
+                    _c.data_type = "s"
+        wb.save(path)
+    except ImportError:
+        path = path.replace(".xlsx", ".csv")
+        with open(path, "w", newline="", encoding="utf-8-sig") as f:
+            writer = csv.writer(f)
+            writer.writerow([_csv_celula_segura(h) for h in header])
+            for r in results:
+                writer.writerow([_csv_celula_segura(r.get(f, "")) for f in fields])
+    logger.success(f"Saída gravada em {path} ({len(results)} linha(s)).")
+
+
+def _mask_pii(value) -> str:
+    """Mascara parcialmente um valor de saída marcado como dado pessoal (LGPD).
+
+    Preserva o mínimo de utilidade (formato reconhecível) sem expor o dado cru:
+    e-mail mantém a inicial + domínio; documento/telefone mantêm os 2 últimos
+    dígitos; demais valores mantêm a inicial. Valor vazio permanece vazio."""
+    s = str(value or "")
+    if not s:
+        return s
+    if "@" in s and "." in s.split("@")[-1]:
+        local, _, domain = s.partition("@")
+        return (local[:1] or "*") + "***@" + domain
+    digits = "".join(ch for ch in s if ch.isdigit())
+    if len(digits) >= 4:
+        return "***" + s[-2:]
+    return s[:1] + "***"
+
+
+def _write_output_com_pii(
+    results: list[dict],
+    path: str = "data/output.xlsx",
+    mask_cols: tuple = (),
+    drop_cols: tuple = (),
+) -> None:
+    """Grava a planilha de saída aplicando a política de PII por coluna (LGPD):
+    ``drop_cols`` são omitidas; ``mask_cols`` são mascaradas via ``_mask_pii``."""
+    if not results:
+        return
+    mask_set = set(mask_cols)
+    drop_set = set(drop_cols)
+    fields: list[str] = []
+    for r in results:
+        for k in r:
+            if k in drop_set:
+                continue
+            if k not in fields:
+                fields.append(k)
+    header = ["Status" if f == "_status" else f for f in fields]
+
+    def _cell(r: dict, f: str):
+        v = r.get(f, "")
+        return _mask_pii(v) if f in mask_set else v
+
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    try:
+        import openpyxl as _xl
+
+        wb = _xl.Workbook()
+        ws = wb.active
+        ws.append(header)
+        for r in results:
+            ws.append([_cell(r, f) for f in fields])
+        # Escape pelo formato: o openpyxl grava como FÓRMULA todo texto iniciado por
+        # "=" (dado do sistema-alvo); o Excel do cliente a calcularia ao abrir.
+        for _linha in ws.iter_rows():
+            for _c in _linha:
+                if _c.data_type == "f":
+                    _c.data_type = "s"
+        wb.save(path)
+    except ImportError:
+        path = path.replace(".xlsx", ".csv")
+        with open(path, "w", newline="", encoding="utf-8-sig") as f:
+            writer = csv.writer(f)
+            writer.writerow([_csv_celula_segura(h) for h in header])
+            for r in results:
+                writer.writerow([_csv_celula_segura(_cell(r, f)) for f in fields])
+    logger.success(f"Saída gravada em {path} ({len(results)} linha(s)).")

shade_sdk/runtime/protocolo.py

@@ -0,0 +1,47 @@
+"""O protocolo do runtime: o contrato entre o robô e o executor da plataforma (ADR 019, D10).
+
+Na plataforma, o executor injeta ``SHADE_REGISTRO_DIR`` e o robô pede o registro de cada item
+antes de efetivar por arquivos nessa pasta (HU-17.7, ADR 012): o sandbox não tem rede para a
+plataforma. O formato da pasta é contrato público, e este módulo é a fonte dele dos dois lados
+(o ledger do robô e ``workers/registro_do_item.py`` no executor)::
+
+    $SHADE_REGISTRO_DIR/
+        campos.json                   ["pedido"]  os campos-chave do robô, gravado uma vez
+        pedidos/NNNNNNNNNNNN.json     {"op": "incerto" | "feito" | "desfazer", "key": "<sha256>"}
+        respostas/NNNNNNNNNNNN.json   {"r": "registrada" | "seguir" | "feita" | "retida" | ...}
+        vivo                          um contador que o executor troca enquanto a posse vale
+
+- Cada arquivo nasce num temporário e entra por ``os.replace`` (atômico): quem lê nunca vê
+  um JSON pela metade.
+- A sequência ``NNNNNNNNNNNN`` (12 dígitos) começa em 1 e não tem buraco: o número só avança
+  depois de o pedido existir.
+- Só o ``incerto`` tem resposta, e o robô a espera por polling de 10 ms até o prazo do
+  registro; ``feito`` e ``desfazer`` vão sem esperar.
+- O robô se encerra se o ``vivo`` parar de mudar (o executor morto não renova a posse).
+
+**Mudar qualquer coisa deste formato sobe ``RUNTIME_PROTOCOL``.** O número vai no manifesto da
+release (``runtime_protocol``), e o executor recusa, antes de subir o container, o artefato
+com um número que ele não fala.
+"""
+
+from __future__ import annotations
+
+#: A versão do contrato acima. O executor aceita um conjunto de números (ver
+#: ``workers/registro_do_item.py``); o robô fala exatamente um.
+RUNTIME_PROTOCOL = 1
+
+#: A variável que liga o modo plataforma no robô (o caminho da pasta).
+VARIAVEL_DA_PASTA = "SHADE_REGISTRO_DIR"
+PEDIDOS = "pedidos"
+RESPOSTAS = "respostas"
+CAMPOS = "campos.json"
+VIVO = "vivo"
+
+OP_INCERTO = "incerto"
+OP_FEITO = "feito"
+OP_DESFAZER = "desfazer"
+
+#: Quantos dígitos tem o número do pedido e da resposta no nome do arquivo.
+DIGITOS_DA_SEQUENCIA = 12
+#: O intervalo com que o robô procura a resposta de um ``incerto``.
+POLLING_DA_RESPOSTA_SECONDS = 0.01

shade_sdk/runtime/recovery.py

@@ -0,0 +1,136 @@
+"""Recuperação do robô: classificação da falha, sessão perdida (S3) e modal inesperado (S2).
+
+Era ``runtime_templates/recovery_runtime.py`` no backend, colado em três trechos dentro do
+``main.py`` gerado; desde a HU-29.1 o robô o importa daqui. A política (``_RECOVERY_POLICY``)
+é do processo e segue no ``main.py``.
+
+As constantes ajustáveis por ambiente são lidas no import deste módulo: o ``main.py`` gerado
+o importa depois de ``src.config``, que leva o ``.env`` para o ambiente antes.
+"""
+
+from __future__ import annotations
+
+import os
+
+_RECOVERY_MAX_ATTEMPTS = int(os.getenv("RECOVERY_MAX_ATTEMPTS", "3"))
+_RECOVERY_BACKOFF_S = float(os.getenv("RECOVERY_BACKOFF_S", "1.0"))
+_RECOVERY_PAUSE_S = int(os.getenv("RECOVERY_PAUSE_S", "60"))  # alert_pause: segundos de espera HITL
+
+
+class RecoveryStopError(RuntimeError):
+    """Política stop: sinaliza que o lote deve ser encerrado imediatamente."""
+
+
+def _classify_recovery_state(exc: Exception) -> str:
+    """Classifica a exceção num estado de recuperação.
+
+    - "transient": timeout / erro de navegação do Playwright → re-tentar o
+      BLOCO do item com backoff (D3; seguro só porque o item é idempotente).
+    - "modal": clique interceptado por overlay/dialog → dispensar o modal e
+      re-tentar a ação (D3; S2). Sinal conservador: só a frase de intercepção
+      de ponteiro do Playwright identifica isso com segurança.
+    - "unknown": qualquer outra exceção → saída honesta (S4).
+    """
+    try:
+        from playwright.sync_api import Error as _PwError
+        from playwright.sync_api import TimeoutError as _PwTimeout
+    except Exception:  # playwright ausente — degrada para desconhecido
+        return "unknown"
+    if isinstance(exc, _PwTimeout):
+        return "transient"
+    _msg = str(exc).lower()
+    if isinstance(exc, _PwError) and "intercepts pointer events" in _msg:
+        return "modal"
+    _transient_hints = ("timeout", "navigation", "net::", "err_", "connection reset")
+    if isinstance(exc, _PwError) and any(_h in _msg for _h in _transient_hints):
+        return "transient"
+    return "unknown"
+
+
+def _sessao_perdida(page, marcador_de_login=None) -> bool:
+    """Sessão perdida = o elemento de login reaparece ou a URL
+    volta para /login (sinais determinísticos do S3 — sessão expirada).
+
+    ``marcador_de_login`` devolve o locator do campo de senha do login (o ``main.py`` gerado
+    passa um ``lambda`` com o seletor gravado); é chamado aqui dentro, no mesmo ``try``."""
+    try:
+        if marcador_de_login is not None and marcador_de_login().is_visible():
+            return True
+    except Exception:
+        pass
+    try:
+        return "/login" in (page.url or "").lower()
+    except Exception:
+        return False
+
+
+_MODAL_SELECTORS = [
+    "[role=dialog]",
+    "[aria-modal=true]",
+    ".modal",
+    ".overlay",
+    ".popup",
+]
+_MODAL_CLOSE_SELECTORS = [
+    "[role=dialog] button[aria-label*=fechar i]",
+    "[role=dialog] button[aria-label*=close i]",
+    "[role=dialog] button[class*=close]",
+    "[role=dialog] button[class*=fechar]",
+    ".modal button[class*=close]",
+    ".overlay button[class*=close]",
+]
+_MODAL_OK_TEXTS = ["OK", "Fechar", "Aceitar", "Continuar", "Close"]
+
+
+def _is_modal_present(page) -> bool:
+    """S2: verifica se há um modal/overlay visível na página.
+    Conservador: só sinais claros de dialog/overlay (role, aria-modal, classes comuns)."""
+    for _sel in _MODAL_SELECTORS:
+        try:
+            if page.locator(_sel).first.is_visible(timeout=500):
+                return True
+        except Exception:
+            pass
+    return False
+
+
+def _dismiss_modal(page) -> None:
+    """S2: tenta dispensar um modal/overlay inesperado.
+
+    Estratégia conservadora (ordem de preferência):
+    1. Botão de fechar canônico (aria-label close/fechar ou class close/fechar).
+    2. Botão com texto OK/Fechar/Aceitar/Continuar/Close dentro do dialog.
+    3. Tecla Esc (último recurso — pode fechar dialogs nativos).
+    Levanta exceção se nenhuma estratégia funcionar (chamador decide).
+    """
+    # 1. Botão de fechar por seletor canônico
+    for _cs in _MODAL_CLOSE_SELECTORS:
+        try:
+            _btn = page.locator(_cs).first
+            if _btn.is_visible(timeout=500):
+                _btn.click(timeout=2000)
+                return
+        except Exception:
+            pass
+    # 2. Botão por texto dentro do dialog
+    for _txt in _MODAL_OK_TEXTS:
+        try:
+            _btn = (
+                page.locator("[role=dialog] button, .modal button")
+                .get_by_text(_txt, exact=True)
+                .first
+            )
+            if _btn.is_visible(timeout=500):
+                _btn.click(timeout=2000)
+                return
+        except Exception:
+            pass
+    # 3. Esc como último recurso
+    try:
+        page.keyboard.press("Escape")
+        page.wait_for_timeout(300)
+        if not _is_modal_present(page):
+            return
+    except Exception:
+        pass
+    raise RuntimeError("Não foi possível dispensar o modal")

shade_sdk/runtime/report.py

@@ -0,0 +1,304 @@
+"""Relatório HTML da execução (``relatorio.html``) e o histórico (``data/historico.csv``).
+
+Chamado ao fim de cada run do ``main.py``. Era ``runtime_templates/report_runtime.py`` no
+backend, copiado como ``src/report.py`` do projeto gerado; desde a HU-29.1 o ``src/report.py``
+gerado reexporta daqui.
+"""
+
+from __future__ import annotations
+
+import base64
+import csv as _csv
+import html as _html
+import os as _os
+from datetime import datetime
+from pathlib import Path
+
+# ── API pública ───────────────────────────────────────────────────────────────
+
+
+def generate_report(
+    process_name: str,
+    step_descriptions: list[str],
+    steps_executed: int,
+    success: bool,
+    duration_s: float,
+    screenshot_paths: list[str] | None = None,
+    output_path: str = "relatorio.html",
+    failed_step: str = "",
+) -> None:
+    """Gera relatorio.html e apensa ao historico.csv; erros sao silenciados."""
+    try:
+        if not failed_step and not success and steps_executed < len(step_descriptions):
+            failed_step = step_descriptions[steps_executed]
+        append_historico(
+            success=success,
+            duration_s=duration_s,
+            failed_step=failed_step,
+            steps_executed=steps_executed,
+        )
+        _write_report(
+            process_name=process_name,
+            step_descriptions=step_descriptions,
+            steps_executed=steps_executed,
+            success=success,
+            duration_s=duration_s,
+            screenshot_paths=screenshot_paths or [],
+            output_path=output_path,
+        )
+    except Exception:
+        pass
+
+
+# ── Internals ─────────────────────────────────────────────────────────────────
+
+
+def _embed_image(path: str) -> str | None:
+    """Retorna data-URI base64 da imagem ou None se não disponível."""
+    try:
+        data = Path(path).read_bytes()
+        ext = Path(path).suffix.lstrip(".").lower() or "png"
+        mime = {"jpg": "jpeg", "jpeg": "jpeg"}.get(ext, ext)
+        return f"data:image/{mime};base64,{base64.b64encode(data).decode()}"
+    except Exception:
+        return None
+
+
+def append_historico(
+    success: bool,
+    duration_s: float,
+    failed_step: str,
+    steps_executed: int,
+    csv_path: str = "data/historico.csv",
+) -> dict:
+    """Apende uma linha em data/historico.csv; cria com header se nao existir."""
+    _HEADER = ["timestamp", "status", "duracao_s", "passo_falhou", "passos_executados"]
+    _os.makedirs(_os.path.dirname(csv_path) or ".", exist_ok=True)
+    ts = datetime.now().isoformat(timespec="seconds")
+    status = "sucesso" if success else "falha"
+    row = [ts, status, f"{duration_s:.2f}", failed_step, str(steps_executed)]
+    needs_header = not _os.path.exists(csv_path)
+    with open(csv_path, "a", newline="", encoding="utf-8") as _f:
+        writer = _csv.writer(_f)
+        if needs_header:
+            writer.writerow(_HEADER)
+        writer.writerow(row)
+    try:
+        with open(csv_path, newline="", encoding="utf-8") as _f:
+            _rows = list(_csv.DictReader(_f))
+        total = len(_rows)
+        successes = sum(1 for r in _rows if r.get("status") == "sucesso")
+        rate = round(100 * successes / total) if total else 0
+        return {"total": total, "successes": successes, "failures": total - successes, "rate": rate}
+    except Exception:
+        return {
+            "total": 1,
+            "successes": int(success),
+            "failures": int(not success),
+            "rate": 100 * int(success),
+        }
+
+
+def _read_historico(csv_path: str = "data/historico.csv") -> tuple[list[dict], dict]:
+    """Le historico.csv; retorna (ultimas 20 linhas, stats agregados)."""
+    try:
+        with open(csv_path, newline="", encoding="utf-8") as _f:
+            rows = list(_csv.DictReader(_f))
+    except FileNotFoundError:
+        return [], {"total": 0, "successes": 0, "failures": 0, "rate": 0}
+    total = len(rows)
+    successes = sum(1 for r in rows if r.get("status") == "sucesso")
+    rate = round(100 * successes / total) if total else 0
+    return rows[-20:], {
+        "total": total,
+        "successes": successes,
+        "failures": total - successes,
+        "rate": rate,
+    }
+
+
+def _history_section(csv_path: str = "data/historico.csv") -> str:
+    """Gera secao HTML com historico de execucoes (ultimas 20 + agregados)."""
+    rows, stats = _read_historico(csv_path)
+    if not rows:
+        return (
+            "<h2>Historico de execucoes</h2>"
+            "<p style='color:#64748b;font-size:13px;margin-bottom:28px'>"
+            "Primeira execucao &mdash; sem historico anterior.</p>"
+        )
+    total = stats["total"]
+    rate = stats["rate"]
+    durs = [float(r.get("duracao_s") or 0) for r in rows]
+    avg_dur = sum(durs) / len(durs) if durs else 0.0
+    rate_cls = "ok-val" if rate >= 80 else ("teal-val" if rate >= 50 else "err-val")
+    cards = (
+        f"<div class='card'><div class='lbl'>Total de execucoes</div>"
+        f"<div class='val teal-val'>{total}</div></div>"
+        f"<div class='card'><div class='lbl'>Taxa de sucesso</div>"
+        f"<div class='val {rate_cls}'>{rate}%</div></div>"
+        f"<div class='card'><div class='lbl'>Duracao media</div>"
+        f"<div class='val teal-val'>{avg_dur:.1f}s</div></div>"
+    )
+    table_rows_html = []
+    for r in reversed(rows):
+        ts = _html.escape(r.get("timestamp", ""))
+        st = r.get("status", "")
+        badge = (
+            '<span class="badge ok">sucesso</span>'
+            if st == "sucesso"
+            else '<span class="badge err">falha</span>'
+        )
+        dur = _html.escape(str(r.get("duracao_s") or ""))
+        fp = _html.escape(r.get("passo_falhou") or "—")
+        pe = _html.escape(str(r.get("passos_executados") or ""))
+        table_rows_html.append(
+            f"<tr><td>{ts}</td><td>{badge}</td><td>{dur}s</td><td>{fp}</td><td>{pe}</td></tr>"
+        )
+    return (
+        "<h2>Historico de execucoes</h2>"
+        f"<div class='summary'>{cards}</div>"
+        "<table><thead><tr>"
+        "<th>Timestamp</th><th>Status</th><th>Duracao</th>"
+        "<th>Passo que falhou</th><th>Passos executados</th>"
+        "</tr></thead><tbody>" + "\n".join(table_rows_html) + "</tbody></table>"
+    )
+
+
+def _step_rows(step_descriptions: list[str], steps_executed: int, success: bool) -> str:
+    rows = []
+    for i, desc in enumerate(step_descriptions, start=1):
+        e = _html.escape(desc)
+        if i <= steps_executed:
+            badge = '<span class="badge ok">OK</span>'
+        elif not success and i == steps_executed + 1:
+            badge = '<span class="badge err">ERRO</span>'
+        else:
+            badge = '<span class="badge pend">Pendente</span>'
+        rows.append(f"<tr><td class='num'>{i}</td><td>{e}</td><td>{badge}</td></tr>")
+    return "\n".join(rows)
+
+
+def _screenshots_section(screenshot_paths: list[str]) -> str:
+    items = []
+    for p in screenshot_paths:
+        uri = _embed_image(p)
+        if not uri:
+            continue
+        name = _html.escape(Path(p).name)
+        items.append(
+            f'<div class="shot"><img src="{uri}" alt="{name}" loading="lazy">'
+            f'<div class="caption">{name}</div></div>'
+        )
+    if not items:
+        return ""
+    return '<h2>Evidências</h2><div class="shots">' + "".join(items) + "</div>"
+
+
+_CSS = """\
+*{box-sizing:border-box;margin:0;padding:0}
+body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;font-size:14px;
+     color:#1a1a1a;background:#fff;line-height:1.5}
+.wrap{max-width:920px;margin:0 auto;padding:40px 24px}
+.hdr{border-bottom:2px solid #0d9488;padding-bottom:18px;margin-bottom:28px}
+.hdr h1{font-size:22px;font-weight:700;color:#0d9488}
+.hdr .meta{color:#555;font-size:13px;margin-top:5px}
+.summary{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));
+          gap:14px;margin-bottom:28px}
+.card{border:1px solid #e2e8f0;border-radius:6px;padding:14px;text-align:center}
+.card .lbl{font-size:11px;text-transform:uppercase;letter-spacing:.05em;color:#64748b}
+.card .val{font-size:26px;font-weight:700;margin-top:4px}
+.ok-val{color:#16a34a} .err-val{color:#dc2626} .teal-val{color:#0d9488}
+h2{font-size:15px;font-weight:600;margin-bottom:10px;color:#334155}
+table{width:100%;border-collapse:collapse;margin-bottom:28px}
+th{text-align:left;padding:8px 12px;font-size:11px;text-transform:uppercase;
+   letter-spacing:.05em;color:#64748b;border-bottom:2px solid #e2e8f0}
+td{padding:9px 12px;border-bottom:1px solid #f1f5f9;font-size:13px}
+td.num{width:40px;color:#94a3b8;text-align:right;padding-right:16px}
+tr:last-child td{border-bottom:none}
+.badge{display:inline-block;padding:2px 7px;border-radius:4px;
+       font-size:11px;font-weight:600;text-transform:uppercase}
+.badge.ok{background:#dcfce7;color:#16a34a}
+.badge.err{background:#fee2e2;color:#dc2626}
+.badge.pend{background:#f1f5f9;color:#94a3b8}
+.shots{display:grid;grid-template-columns:repeat(auto-fill,minmax(260px,1fr));
+       gap:14px;margin-bottom:28px}
+.shot img{width:100%;border-radius:5px;border:1px solid #e2e8f0;display:block}
+.caption{font-size:11px;color:#64748b;margin-top:4px}
+.footer{color:#94a3b8;font-size:12px;text-align:center;margin-top:36px;
+        padding-top:16px;border-top:1px solid #e2e8f0}
+.sched{background:#f0fdfa;border:1px solid #99f6e4;border-radius:6px;
+       padding:14px 18px;margin-bottom:28px;font-size:13px}
+.sched h3{font-size:13px;font-weight:600;margin-bottom:8px;color:#0f766e}
+.sched ul{margin:6px 0 6px 18px}
+.sched li{margin-bottom:3px}
+.sched code{background:#e0f2fe;padding:1px 5px;border-radius:3px;
+            font-family:monospace;font-size:12px}
+"""
+
+
+_SCHEDULE_HTML = (
+    "<div class='sched'>"
+    "<h3>&#x23F0; Agendar execucao recorrente</h3>"
+    "<p>Para executar esta automacao automaticamente, use os scripts incluidos:</p>"
+    "<ul>"
+    "<li><strong>macOS / Linux:</strong> <code>bash agendar.sh</code></li>"
+    "<li><strong>Windows:</strong> execute <code>agendar.bat</code></li>"
+    "</ul>"
+    "<p>Escolha diario, semanal ou horario. Logs em: <code>logs/agendamento.log</code></p>"
+    "<p><strong>Para remover:</strong> "
+    "macOS/Linux: <code>crontab -e</code> (apague a linha com rodar.sh) &nbsp;|&nbsp; "
+    "Windows: <code>schtasks /delete /tn RPA_AUTOMACAO_DIARIO /f</code> "
+    "ou <code>taskschd.msc</code></p>"
+    "</div>"
+)
+
+
+def _write_report(
+    process_name: str,
+    step_descriptions: list[str],
+    steps_executed: int,
+    success: bool,
+    duration_s: float,
+    screenshot_paths: list[str],
+    output_path: str,
+) -> None:
+    now = datetime.now().strftime("%d/%m/%Y %H:%M:%S")
+    n = len(step_descriptions)
+    steps_ok = steps_executed if success else steps_executed
+    status_label = "Concluido" if success else "Com falha"
+    status_cls = "ok-val" if success else "err-val"
+    dur = f"{duration_s:.1f}s"
+    e_name = _html.escape(process_name)
+
+    rows_html = _step_rows(step_descriptions, steps_executed, success)
+    shots_html = _screenshots_section(screenshot_paths)
+    history_html = _history_section()
+
+    page = (
+        "<!DOCTYPE html>"
+        f'<html lang="pt-BR"><head><meta charset="UTF-8">'
+        f'<meta name="viewport" content="width=device-width,initial-scale=1">'
+        f"<title>Relatorio — {e_name}</title>"
+        f"<style>{_CSS}</style>"
+        "</head><body><div class='wrap'>"
+        f"<div class='hdr'><h1>{e_name}</h1>"
+        f"<div class='meta'>Relatorio de Execucao &middot; {_html.escape(now)}</div></div>"
+        "<div class='summary'>"
+        f"<div class='card'><div class='lbl'>Status</div>"
+        f"<div class='val {status_cls}'>{_html.escape(status_label)}</div></div>"
+        f"<div class='card'><div class='lbl'>Passos</div>"
+        f"<div class='val teal-val'>{steps_ok}/{n}</div></div>"
+        f"<div class='card'><div class='lbl'>Duracao</div>"
+        f"<div class='val teal-val'>{_html.escape(dur)}</div></div>"
+        "</div>"
+        "<h2>Passos executados</h2>"
+        "<table><thead><tr><th>#</th><th>Descricao</th><th>Status</th></tr></thead>"
+        f"<tbody>{rows_html}</tbody></table>"
+        f"{shots_html}"
+        f"{history_html}"
+        f"{_SCHEDULE_HTML}"
+        "<div class='footer'>Gerado pelo Shade One</div>"
+        "</div></body></html>"
+    )
+
+    Path(output_path).write_text(page, encoding="utf-8")

shade_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: shade-sdk
+Version: 0.1.0
+Summary: O runtime dos robôs da ShadeOne: ledger por chave de negócio, recuperação, relatório e o protocolo com o executor.
+Author: ShadeOne
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# shade-sdk
+
+O runtime dos robôs da ShadeOne. O robô gerado pela plataforma importa este pacote, na versão
+fixada pelo `requirements.lock` da imagem do sandbox, e o robô escrito à mão vai importar o
+mesmo pacote (ADR 019, D1).
+
+- `shade_sdk.runtime.ledger`: identidade do item por chave de negócio, o `incerto` gravado
+  antes de efetivar e o canal do registro com o executor.
+- `shade_sdk.runtime.recovery`: classificação da falha, sessão perdida e modal inesperado.
+- `shade_sdk.runtime.report`: relatório HTML da execução e o histórico.
+- `shade_sdk.runtime.config`: `Settings` e a carga do `.env`.
+- `shade_sdk.runtime.output`: a planilha de saída, com ou sem mascaramento de PII.
+- `shade_sdk.runtime.protocolo`: o número e o formato do contrato robô ↔ executor.
+
+Licença: Apache-2.0.

shade_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+shade_sdk/__init__.py,sha256=RXYux3ySNU2_Mx-rjzKi7s0j3e6VZuU6ldouSkbk0j8,271
+shade_sdk/runtime/__init__.py,sha256=Q3XSeds7ABj4G_kNzSv8vs_kY-EkoejMcDa2D57QyWk,1170
+shade_sdk/runtime/config.py,sha256=lV-jg4s7WJkaLZbQ-KLNiwX5pd_3YtmXhDWqHCiGwus,3148
+shade_sdk/runtime/ledger.py,sha256=mAxbQCT7qF3zlEVd1PYOV4xoxEh7bu_TsuAzxMpOnRI,21658
+shade_sdk/runtime/output.py,sha256=NFMZQwmh3hm5mjxud7n4gLz0nvY_BKVvYuabtewc6c8,5120
+shade_sdk/runtime/protocolo.py,sha256=vHvdxrqRKByfoAV_aMmYThODt8j6DPlolOplkW8-NSo,2243
+shade_sdk/runtime/recovery.py,sha256=I620_zkBQhkNVNVaBo164p-PHFRiz_JtihhaYCFokfQ,5065
+shade_sdk/runtime/report.py,sha256=MspZLSEf2iG262_cQBpigy4ok0YV-4eQPtld-yIHNK0,12582
+shade_sdk-0.1.0.dist-info/METADATA,sha256=Il8N2aoJZgxOQO1TZoyDs6YRBVz6XPn6bwDQCODoUaI,1205
+shade_sdk-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+shade_sdk-0.1.0.dist-info/RECORD,,

shade_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any