Skip to content

Progress events ​

Follow a relizy run without parsing text - the typed events of the onProgress option and of RELIZY_REPORTER=json, one JSON object per line.

A program running relizy (an app, a script, a CI wrapper) gets what happens as typed events: a step started, done, failed or skipped, what it does now, the links it created, the logs, the end of the run. The events are the same from the API and from the CLI.

From Node.js ​

Every command takes an onProgress option, called with each event of the run:

ts
import type { RelizyEvent } from 'relizy'
import { release } from 'relizy'

const report = await release({
  yes: true,
  profile: 'beta',
  onProgress(event: RelizyEvent) {
    switch (event.type) {
      case 'step:start':
        console.log(`> ${event.label}`)
        break
      case 'step:done':
        console.log(`  ${event.message} (${event.durationMs} ms)`)
        break
      case 'step:failed':
        console.error(`  ${event.label} failed: ${event.message}`)
        break
      case 'link':
        console.log(`  ${event.label}: ${event.url}`)
        break
    }
  },
})

The commands a command runs (bump inside release) share its listener, and their steps are the progress of the step of the parent: one release gives one command:start. A listener can be async (void | Promise<void>): it is not awaited, and a listener that throws or rejects does not stop the run (never an unhandled rejection). Several runs can follow each other at the same time (several projects of an application): each run gets its own events, and what its steps did never mixes with another run. The API leaves the logs to the logger: there is no log event out of the CLI renderers.

From the CLI ​

RELIZY_REPORTER=json writes one JSON event per line on stdout, and nothing else (the logs of relizy before the run starts go to stderr). A parent process reads the lines as they come:

bash
RELIZY_REPORTER=json relizy release --profile beta --yes
text
{"type":"command:start","command":"release","title":"relizy release","dryRun":false,"time":1794595334759}
{"type":"step:start","step":"bump","label":"Computing the versions","time":1794595334801}
{"type":"step:done","step":"bump","label":"Computing the versions","message":"relizy 1.4.0  →  1.5.0","durationMs":412,"details":[],"time":1794595335213}
{"type":"release:finish","report":{"status":"released","released":true,"version":"1.5.0"},"time":1794595340120}

A prompt cannot be answered (it would write on stdout): release and bump without --yes fail at once with what to do, as without a terminal, and any other prompt (a one-time password: pass --otp) fails the same way. The exit code is the one of the command (0, or 1 on an error: the command:error event comes before).

Events ​

Every event has type and time (milliseconds since the epoch).

typeWhenFields
command:startThe command startscommand (release, bump...), title, dryRun
step:startA step startsstep, label (what it does)
step:doneA step succeededstep, label, message (what it did), durationMs, details, data (what it did, see Step data)
step:failedA step failedstep, label, message, durationMs, fatal (false when the release goes on: a post, a provider release), cancelled, data (what it did before failing, when known)
step:skippedA step is left outstep, label, reason: the flag of the run (--no-publish), canary, or the option of the config (release.social: false)
step:itemA thing of the running step starts or ends: a package, a platformstep (publish, social), item: name, status (running, done, failed, skipped), detail, url
progressWhat the running step does nowmessage, ai (done by AI)
noteWhat a step did, shown under its resultmessage, ai
linkWhat a step created: a release, an npm page, a post, the PR commentstep (publish, provider-release, social, sync, pr-comment), label, url
previewWhat a dry run generated (changelog, release notes, post)title, meta, content
logA log of relizy (the CLI renderers only, not the debug ones)level, message
release:finishrelease is overreport: the report of the release
command:completeAnother command is overmessage, nothing, failed, warnings, links, durationMs
command:errorThe command failed, or its prompt was refusedmessage, failedStep, cancelled, report (a release that failed)

step is the name of the step as the hooks name it: checks, bump, changelog, publish, commit-and-tag, push, provider-release, social, sync, pr-comment, and merge-preview for the steps of mergePreview(). It is missing for a step that has no hook. The steps of the other commands (relizy publish alone: publish) use the same names.

A name can come with several step:start/step:done pairs: relizy publish alone gives three publish pairs (checking the packages, building them with publish.buildCmd, publishing them, only the last one with data), and mergePreview() one merge-preview pair per part of the preview (the merge, the release, the checks, the comment, the commit status). Within release, publish is one pair.

The types are exported: RelizyEvent (the union), RelizyEventListener, one type per event (StepDoneEvent, StepItemEvent...), and the data of each step (StepDataMap, PublishStepData...).

Step data ​

step:done (and step:failed when the step knows what it did before failing) carries data, what the step did as data, typed by step: an interface renders each step without parsing its message.

stepdata
checkschecks: { name, status, message? } per safety check (provider-release, publish, social, branch, push, and sync when branches are synced), status passed, failed or skipped
bumppackages: { name, oldVersion, newVersion, group? }
changelogfiles: { file, packageName, content }, the file relative to the project and the entry added (previewed in dry-run)
publishregistry, tag (the dist-tag), dryRun, packages: { name, version, status, url?, reason? } in publish order, status published, skipped (already on the registry) or failed
commit-and-tagcommit: { hash?, message } (no hash in dry-run), tags
pushremote, branch, tags (the tags were pushed)
provider-releaseprovider, releases: { tag, name?, url? }
socialdryRun, posts: { platform, status, url?, reason? }, status posted, skipped or failed
syncmode, source, dryRun, branches: { branch, status, commit?, pullRequest?, conflicts?, reason? }, status merged, fast-forward, up-to-date, pull-request, conflict or failed
pr-commentposted, number?, url?

With dryRun: true (the run is a simulation), published and posted mean what the run would do: nothing was published nor posted, and the packages have no url.

ts
import { release } from 'relizy'

await release({
  onProgress(event) {
    if (event.type === 'step:item') {
      console.log(event.step, event.item.name, event.item.status)
    }

    if (event.type === 'step:done' && event.step === 'publish') {
      for (const pkg of event.data?.packages ?? []) {
        console.log(pkg.name, pkg.version, pkg.status, pkg.url)
      }
    }
  },
})

Answering from the application ​

The prompts of the terminal have their option, for an application asking in its own interface:

  • onConfirm(plan) (release(), bump()) validates the computed versions before anything is written; false cancels the run as a refused prompt. An error it throws fails the run (cancelled: false, nothing written): throw a RelizyCancelError to cancel instead. It is not called when the versions are confirmed in advance: yes, or bump.yes: true in the config or the profile. Without onConfirm nor yes, the terminal asks
  • onOtp({ registry, packageName }) (release(), publish()) gives the one-time password the registry asks for, as a string or a promise. An empty password (or none) cancels the publish as a refused prompt (a RelizyCancelError, cancelled: true); the packages published before stay published
ts
import { release } from 'relizy'

await release({
  // Asked once the versions are computed, nothing written yet
  onConfirm: plan => showPlanInTheApp(plan.packages),
  onOtp: ({ registry }) => askTheOtpInTheApp(registry),
  onProgress: event => renderInTheApp(event),
})

See Also ​