@oren-sh/sdk

SDK para escrever workers do Oren em Node.

Um worker do Oren é uma imagem OCI que lê /oren/input.json e escreve /oren/output.json. O protocolo é simples de propósito — este pacote existe para você não reimplementar leitura de caminho, tratamento de erro e código de saída em cada worker.

Uso

import { task } from '@oren-sh/sdk';

type Inputs = { defaultChange: 'major' | 'minor' | 'patch' | 'none' };
type Outputs = { change: string; commitCount: number };

await task<Inputs, Outputs>(async ({ inputs, path, log }) => {
  const source = path('source');        // onde a dependência foi montada
  log('analisando', source);            // stdout e stderr são log livre

  return { change: inputs.defaultChange, commitCount: 3 };
});

O que a função devolver vira a saída da task, validada pela CLI contra o contrato. Lançar aborta o step com código de saída 1.

API

task<I, O>(handler) — ponto de entrada do worker. O handler recebe:

| | | | --- | --- | | inputs | entradas já validadas contra o contrato, com defaults aplicados | | execution | metadados: pipeline, step, task, dependências montadas | | path(nome) | caminho onde uma dependência foi montada, pelo nome do contrato | | log(...) | escreve em stderr |

TaskError — erro cuja mensagem é destinada a quem escreveu o pipeline. É exibida sem stack trace, ao contrário de qualquer outra exceção.

Dockerfile

FROM node:22-alpine
WORKDIR /worker
COPY package.json ./
RUN npm install --omit=dev
COPY index.js ./
ENTRYPOINT ["node", "/worker/index.js"]

Ou deixe o oren init --template node gerar tudo.

Não é obrigatório

O protocolo é ler um arquivo e escrever outro; um worker em shell de três linhas é igualmente válido, e nada no Oren privilegia Node. Este pacote é conveniência, não requisito.

Variáveis do protocolo

O SDK lê estas, com os valores padrão como fallback:

| Variável | Padrão | | --- | --- | | OREN_INPUT_PATH | /oren/input.json | | OREN_OUTPUT_PATH | /oren/output.json | | OREN_CONTEXT_PATH | /oren/context.json |

Estado

Rascunho, versão 0.x. O protocolo v1 está estável; a API deste pacote ainda pode mudar.