hobots 4.2.0 → 5.0.0

package/docs/runs.md

@@ -29,9 +29,11 @@ Dentro do handler — e em **qualquer módulo** chamado por ele — o objeto glo
 ```js
 // notas.js — não recebe ctx nenhum
 export async function baixar(nota) {
-  const step = hobots.transaction.startChild('http.client', `GET /notas/${nota}`);
-  const xml = await portal.baixar(nota);
-  step.setData('bytes', xml.length).finish();
+  const xml = await hobots.step(`GET /notas/${nota}`, async etapa => {
+    const xml = await portal.baixar(nota); // lançou? o SDK tenta de novo uma vez
+    etapa.data('bytes', xml.length);
+    return xml;
+  });
   hobots.items.succeeded({ numero_nota: nota }, { id: nota });
 }
 ```
@@ -43,7 +45,7 @@ Isso funciona com `concurrency > 1` porque cada execução roda no seu contexto
 | `hobots.log.<debug\|info\|warn\|error\|success>(msg, ...rest)` | Enviado incrementalmente (PATCHes com throttle) e ecoado no terminal (`[hobots] INFO …`). Nunca lança. `hobots.image(...)` no último argumento = print da linha. |
 | `hobots.items` | Ver [Itens](#itens-de-execução-hobotsitems) |
 | `hobots.progress` | Ver [Progresso](#progresso-hobotsprogress) |
-| `hobots.transaction` | Transaction da execução (`run`), já correlacionada e finalizada pelo SDK. `startChild(op, descrição)` = uma step no waterfall. |
+| `hobots.step(nome, fn, opts?)` | Ver [Etapas](#etapas-hobotsstep) |
 | `hobots.image(imagem, opts?)` | Ver [Imagens](#imagens-screenshots) |
 | `hobots.captureException(erro, hint?)` | Issue no módulo Issues; `hint.attachment` anexa um print à linha de log |
 | `hobots.retry(fn, opts?)` | Ver [Retry](#retry) |
@@ -52,6 +54,7 @@ Isso funciona com `concurrency > 1` porque cada execução roda no seu contexto
 
 - **Retorno** do handler: **ignorado** (resultados podem conter dados sensíveis). Reporte por logs e itens.
 - **Erro lançado**: nova tentativa (ver Retry) e, esgotadas, `failed` com tipo, mensagem (cap 10k) e stack (cap 20k), passando pelo scrub de segredos.
+- Para rodar o handler na sua máquina sem a Central, ver [Modo local](#modo-local-teste-sem-a-central).
 
 > **Dados sensíveis:** logs, itens, erros e prints são enviados ao servidor e ficam visíveis no app.
 
@@ -79,7 +82,7 @@ O contrato da plataforma — **todo item previsto termina com um desfecho regist
 const resultado = await hobots.items.each(
   contas,
   async (conta, item) => {
-    await login(conta);                       // lançou → item `failed` com a mensagem, step em erro, segue
+    await login(conta);                       // lançou → item `failed` com a mensagem, etapa em erro, segue
     const fatura = await baixar(conta);
     if (!fatura) return item.occurrence('sem fatura no mês');   // ocorrência de negócio
     item.succeeded({ fatura: fatura.numero, valor: fatura.valor }); // mescla com o payload base
@@ -90,8 +93,8 @@ const resultado = await hobots.items.each(
 // resultado = { total, succeeded, failed, occurrence }
 ```
 
-- Cada elemento vira uma **step** no waterfall (`op` 'item', descrição = `id`; `item.step.startChild(...)` mede sub-etapas) e um **item** com o `id` e o payload base.
-- **Exceção no handler** = item `failed` com a mensagem do erro, `step.setError(erro)`, linha de erro no log da run — e o loop **segue para o próximo**. Nada do que o handler já registrou (`item.failed/occurrence`) é sobrescrito.
+- Cada elemento vira uma **etapa** no waterfall (`op` 'item', descrição = `id`; `hobots.step(...)` dentro do handler vira sub-etapa dela, e `item.step` é o handle `warning`/`image`/`data`) e um **item** com o `id` e o payload base.
+- **Exceção no handler** = item `failed` com a mensagem do erro, etapa em `error`, linha de erro no log da run — e o loop **segue para o próximo**. Nada do que o handler já registrou (`item.failed/occurrence`) é sobrescrito. O `each` não repete o item: para tentar de novo um trecho, use `hobots.step` dentro do handler.
 - **Progresso automático**: declara o total pelo tamanho da lista (se o bot ainda não declarou um) e avança a cada elemento, inclusive nos que falharam. `progress: false` deixa o progresso por conta do bot.
 - Só **cancelamento, timeout e shutdown** interrompem o loop: o `RunCanceled` sobe, o item em curso não é registrado e o progresso não avança.
 - Aceita `Iterable` ou `AsyncIterable` (sem `length`, nenhum total é declarado).
@@ -112,11 +115,41 @@ hobots.register(handler, {
 - A declaração vai na presença da instância (`instance.items` no poll / abertura de run). No app, **Configurações → agente → itens da execução** pode personalizar as colunas (e restaurar as do código).
 - Sem declaração nem personalização, o app mostra as chaves encontradas nos próprios payloads.
 
+## Etapas (`hobots.step`)
+
+Uma **etapa** é um trecho da execução com nome de negócio, medido no waterfall da aba de performance. Uma chamada só: o SDK abre a etapa, roda a função, **tenta de novo** se ela lançar e fecha.
+
+```js
+// retries = 1 e retryDelayMs = 5_000 por padrão
+const pedido = await hobots.step('Buscar pedido', () => portal.buscar(numero));
+
+// etapa não idempotente (enviar, pagar, emitir): sem repetir
+await hobots.step(`Emitir nota ${numero}`, () => portal.emitir(numero), { retries: 0 });
+
+// mais tentativas, espera própria (número ou função da tentativa, 1-based)
+await hobots.step('Entrar no portal', login, { retries: 3, retryDelayMs: attempt => attempt * 2_000 });
+
+// a função recebe o handle `etapa` para o que o SDK não vê sozinho
+await hobots.step('Conferir anexos', async etapa => {
+  const anexos = await portal.anexos(numero);
+  etapa.data('total', anexos.length);
+  if (anexos.length === 0) etapa.warning('pedido sem anexos', { image: await page.screenshot() });
+});
+```
+
+- **Uma etapa só na Central**, cobrindo todas as tentativas: `data.attempts` quando houve mais de uma; status `warning` com o motivo (`data.message = "tentativa 1/2 falhou: Tipo: mensagem"`) quando a nova tentativa deu certo — a menos que a função já tenha marcado `warning`; `error` com `data.error = { type, message }` quando esgotou (a exceção original sobe); `cancelled` em cancelamento, timeout ou shutdown (nunca repetem).
+- Cada tentativa falhada vai para o **log da run**: `etapa "Buscar pedido": tentativa 1/2 falhou: Error: portal caiu — nova tentativa em 5000ms`. A espera é cancelável: uma execução cancelada no app não espera a próxima tentativa.
+- **Aninhamento automático**: `hobots.step` dentro da função vira sub-etapa da etapa corrente — inclusive dentro do handler de `items.each`, onde aninha na etapa do item.
+- O handle `etapa` (`StepHandle`): `warning(motivo, { image }?)` (uma etapa com erro não volta para aviso), `image(png)` (até 4 por etapa; vai em `data.attachments`), `data(chave, valor)` (`attachments` é reservada). Nada de abrir, fechar ou mudar status — isso é do SDK.
+- Abrir a etapa é um **ponto de parada** (`RunCanceled` se a execução foi cancelada). O nome é recortado em 2048 caracteres no cliente.
+- Fora de uma execução (aviso único), `hobots.step` roda a função com o mesmo retry, sem registrar nada. No [modo local](#modo-local-teste-sem-a-central) a etapa fica só na memória e o FINISH ecoa no terminal: `[hobots:step] FINISH Buscar pedido (812ms): tentativa 1/2 falhou: …`.
+- `hobots.retry(fn)` continua existindo para repetir **sem etapa**; `retries` de `register()`/`start()` repete o **trabalho inteiro**.
+
 ## Entregar enquanto processa (`hobots.flush()`)
 
 A transaction da execução só é enviada quando a run termina — num agente sempre ligado (`start()`) isso é nunca. `hobots.flush()` deixa o **bot** decidir quando entregar o que já fez:
 
-- cada step **raiz** já finalizada (com todas as filhas; as filhas ainda abertas são fechadas) vai numa transaction parcial da mesma run (`op` `hobots.run.flush`, `event_id` novo, até 200 steps cada) e sai da memória do SDK; steps raiz ainda abertas ficam para o próximo flush;
+- cada etapa **raiz** já finalizada (com todas as sub-etapas; as ainda abertas são fechadas) vai numa transaction parcial da mesma run (`op` `hobots.run.flush`, `event_id` novo, até 200 etapas cada) e sai da memória do SDK; etapas raiz ainda abertas ficam para o próximo flush;
 - itens, logs e progresso pendentes saem já, sem esperar o throttle;
 - aguarda a entrega com teto (`timeoutMs`, default 15 s) e **nunca lança** — pode ir num `finally`.
 
@@ -125,11 +158,11 @@ hobots.start(async () => {
   while (true) {
     const lote = await fila.pegar();
     if (lote.length) {
-      const rodada = hobots.transaction.startChild('rodada', `${lote.length} pedido(s)`);
       try {
-        for (const pedido of lote) await processar(pedido, rodada); // steps filhas + hobots.items.*
+        await hobots.step(`rodada: ${lote.length} pedido(s)`, async () => {
+          for (const pedido of lote) await processar(pedido); // sub-etapas (hobots.step) + hobots.items.*
+        }, { retries: 0 });
       } finally {
-        rodada.finish();
         await hobots.flush(); // waterfall e itens desta rodada já na Central
       }
     }
@@ -138,7 +171,7 @@ hobots.start(async () => {
 });
 ```
 
-Fila vazia → não abra step: cada step também vira duas linhas (START/FINISH) no log da execução, que guarda no máximo 1000.
+Fila vazia → não abra etapa: cada etapa também vira duas linhas (START/FINISH) no log da execução, que guarda no máximo 1000.
 
 ## Progresso (`hobots.progress`)
 
@@ -182,9 +215,54 @@ for (const ref of hobots.files.list()) hobots.log.info(ref.name, ref.size);
 
 `isFileRef(valor)` (export do pacote, também `hobots.isFileRef`) reconhece a forma de um `FileRef` — útil para percorrer params aninhados.
 
+## Modo local (teste sem a Central)
+
+Para testar o robô na sua máquina sem Client Secret, sem Central e sem rede, rode-o com a env **`HOBOTS_LOCAL_RUN=1`**. `register()` e `start()` se comportam igual neste modo: o handler roda **uma vez**, com `params = JSON.parse(HOBOTS_RUN_PARAMS || '{}')`, e o processo encerra. O código do bot não muda — `hobots.log`, `hobots.items`, `hobots.progress`, `hobots.files`, `items.each`, `hobots.step` (o FINISH de cada etapa ecoa como `[hobots:step] FINISH <nome> (123ms): <motivo>`), cancelamento e retry são os mesmos de produção; só o transporte é trocado por um que não fala com ninguém.
+
+```bash
+HOBOTS_LOCAL_RUN=1 HOBOTS_RUN_PARAMS='{"lote": 3}' node bot.js
+```
+
+- `HOBOTS_CLIENT_SECRET`, `HOBOTS_RUN_ID` e `HOBOTS_API_URL` são ignoradas. Nenhuma requisição sai: sem heartbeat, sem poll, sem issues (`hobots.captureException` devolve `undefined`).
+- `hobots.runId` é `'local'`; `HOBOTS_RUN_PARAMS` que não seja um objeto JSON válido imprime `[hobots] ERROR HOBOTS_RUN_PARAMS inválido: <motivo>` no stderr e encerra com código **2**.
+- **Exit code** pelo desfecho: **0** handler terminou; **1** lançou (depois dos retries configurados) — no stderr sai `[hobots] ERROR execução falhou — <Tipo>: <mensagem>` e a stack completa; **130** cancelado — `SIGINT`/`SIGTERM` disparam `hobots.signal` na execução em voo e esperam o handler parar por até 4 s (com `installExitHandlers: false`, ou com handler próprio do programa para o sinal, o SDK não intervém).
+
+O que sai no **stdout** (linhas estáveis, pensadas para quem lê a saída por script):
+
+| Linha | Quando |
+| --- | --- |
+| `[hobots] INFO modo local — execução sem a Central; params de HOBOTS_RUN_PARAMS` | primeira linha, ao entrar no modo |
+| `[hobots] INFO <mensagem>` (e `WARNING`/`ERROR` no stderr) | cada `hobots.log.*`, como sempre |
+| `[hobots:progress] <current>/<total>` | `hobots.progress` (também fora do modo local) |
+| `[hobots:item] <status>\t<id>\t<message>` | um item por linha, `status` = `succeeded` \| `occurrence` \| `failed`; tab e quebra de linha em id/mensagem viram espaço |
+| `[hobots:summary] total=<n> ok=<n> avisos=<n> falhas=<n> pulados=0` | no fim, contagem dos itens por status |
+| `[hobots] INFO execução local concluída (<succeeded\|failed\|canceled>) em <N>s` | última linha |
+
+Imagens e anexos (`hobots.image`, `{ image }` em itens e steps) são **descartados**, com um aviso único: `imagens e anexos não são enviados no modo local (descartados)`.
+
+**Arquivos.** `hobots.files` funciona com `storage: 'local'`; o formato `$HOBOTS_LOCAL_FILES_DIR/<id>/<nome>` continua valendo, e só no modo local o `FileRef` aceita a chave extra **`path`** (caminho absoluto ou relativo à pasta de trabalho): `download` copia de `path` **sem apagar a origem** (o teste roda quantas vezes quiser) e sem conferir `size`. `path` inexistente ou que não é arquivo regular: `arquivo "<nome>" não encontrado em <path>`. Um arquivo enviado pela Central (`storage: 's3'`) não existe aqui: `arquivo "<nome>" enviado pela Central não está disponível no modo local`. Fora do modo local a chave `path` é ignorada.
+
+### A CLI `hobots run`
+
+A CLI monta as envs e os params por você — e roda o entry com o **mesmo Node** (`process.execPath`), na mesma pasta de trabalho, herdando o terminal; o exit code do bot é o da CLI:
+
+```bash
+npx hobots run bot.js --params entrada.json --param lote=3 --param nome='"ACME"' --file planilha=./dados.xlsx -- --verbose
+```
+
+| Opção | Efeito |
+| --- | --- |
+| `--params <arquivo.json>` | objeto JSON base dos params |
+| `--param <chave>=<valor>` (repetível) | valor parseado como JSON quando for JSON válido (`3`, `true`, `"x"`, `[1]`), senão string crua; sobrescreve `--params` |
+| `--file <campo>=<caminho>` (repetível) | vira um `FileRef` `{ id: <uuid>, name, size, contentType, storage: 'local', path: <caminho absoluto> }`; o mesmo campo repetido vira uma lista; `contentType` pela extensão (`xlsx`, `xls`, `csv`, `ods`, `pdf`, `json`, `txt`, `xml`, `png`, `jpg`/`jpeg`, `zip`; demais `application/octet-stream`); caminho inexistente → `arquivo não encontrado: <caminho>`, exit 2 |
+| `--reset-ledger` | define `HOBOTS_LEDGER_RESET=1` no ambiente do bot (o ledger é do esqueleto do bot, não do SDK) |
+| `-- <args>` | tudo depois de `--` vai para o bot |
+
+`--help`/`-h` imprime a linha de uso no stdout (exit 0). Uso errado (sem entry, flag desconhecida, `--param` sem `=`): mensagem curta + linha de uso no stderr e exit **2**; entry inexistente → `arquivo não encontrado: <entry>`; `--params` com arquivo inexistente, JSON inválido ou que não é objeto → `--params: <motivo>` (exit 2). A CLI repassa `SIGINT`/`SIGTERM` ao bot e espera ele encerrar. O SDK Python tem a mesma CLI: `python -m hobots run bot.py …`.
+
 ## Imagens (screenshots)
 
-Um print vai **junto do evento** que ele ilustra — a linha de log, o item ou a step — para o
+Um print vai **junto do evento** que ele ilustra — a linha de log, o item ou a etapa — para o
 usuário ver o estado do robô no momento em que aquilo aconteceu (botão de imagem no app):
 
 ```js
@@ -199,16 +277,12 @@ await hobots.items.each(notas, async (nota, item) => {
   item.occurrence('sem fatura no mês', undefined, { image: await page.screenshot() });
 });
 
-// na step
-const step = hobots.transaction.startChild('emitir', numero);
-try {
+// na etapa
+await hobots.step(`emitir ${numero}`, async etapa => {
   await emitir(numero);
-} catch (erro) {
-  step.setError(erro, undefined, { image: await page.screenshot() });
-  throw erro;
-} finally {
-  step.finish();
-}
+  etapa.image(await page.screenshot()); // print do estado da tela
+  if (await page.isVisible('.aviso')) etapa.warning('portal demorou a responder', { image: await page.screenshot() });
+}, { retries: 0 });
 
 // numa issue (módulo Issues) — o print vai na linha de log que espelha o erro
 hobots.captureException(erro, { attachment: hobots.image(await page.screenshot(), { caption: 'tela no momento do erro' }) });
@@ -220,7 +294,7 @@ O SDK não tira o print: aceita bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou u
 
 Cancelar o trabalho no app **não mata** o handler: o SDK detecta (o PATCH periódico recebe 409), dispara `hobots.signal` e o próximo **ponto de parada** lança `RunCanceled`:
 
-- `hobots.items.*`, `hobots.progress.total/advance/set`, `hobots.transaction.startChild()`, `hobots.sleep()` e cada tentativa de `hobots.retry()`.
+- `hobots.items.*`, `hobots.progress.total/advance/set`, `hobots.step()`, `hobots.sleep()` e cada tentativa de `hobots.retry()`.
 - **Nunca `hobots.log.*`** — log em `finally` de limpeza não pode explodir.
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hobots",
-  "version": "4.2.0",
+  "version": "5.0.0",
   "description": "SDK JavaScript da Hobots — o agente é a própria tarefa: register() atende solicitações da plataforma (sob demanda), start() roda sempre ligado e reporta logs, itens e progresso. Credenciais por env, heartbeat sempre ligado, objeto global `hobots`.",
   "type": "module",
   "sideEffects": false,
@@ -12,6 +12,9 @@
     "dist",
     "docs"
   ],
+  "bin": {
+    "hobots": "./dist/cli.cjs"
+  },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",