feat(DT-4385): add a CLI to demo an in-progress feature

[rossnelson]

Based on decode-binary-protobuf-payloads, because the demo it ships is a demo
of that branch. Review this after DT-4385, or with it.

The goal

A reviewer of an in-progress feature needs a Temporal server that has the
feature, the dynamic configuration it wants, a worker, the workflows that show
it, and a list of what to check. One command supplies all of it:

pnpm demo start system-nexus-signal-with-start

The command runs the stages, prints the summary, and exits. The run continues.
pnpm demo stop ends it, and --once ends it before the command returns.

This tool is for in-progress features. The system Nexus SignalWithStart
operation is in server 1.32.0, and the newest CLI release has server 1.31.2, thus
a release cannot show it and the tool compiles a server checkout instead.

How a scenario is put together

Everything is in utilities/demo. A scenario is a directory, the way a Catalog
example is, and its files are TypeScript:

utilities/demo/scenarios/system-nexus-signal-with-start/
  definition.ts         what to run and what to check
  scenario.ts           behaviour that names of examples cannot give
  caller-workflow.ts    the workflow that sends the operation
  payload-converter.ts  binary/protobuf for the two messages

A definition is a module, not JSON, because the shape has a meaning at runtime
only and the compiler checks a module at no cost. Therefore the options that a
definition sends to its scenario are checked, and the editor shows them:

error TS2561: Object literal may only specify known properties, but
'signalNaem' does not exist in type '{ ... signalName?: string ... }'.
Did you mean to write 'signalName'?

A scenario says what to run in one of two ways, and it can use both. examples
names Catalog examples. A scenario.ts gives behaviour that names of examples
cannot give.

Stages

Four stages run in sequence, and each one is optional. Use "enabled": false in
the definition, or --skip and --only.

Stage	What it does
server	Supplies a Temporal dev server and applies the dynamic config
worker	Starts the Catalog worker against that server
ui	Starts the ui-server API and the UI dev server
scenarios	Runs the workflows that show the feature

A start stops a recorded run of the same scenario first, and it says so. Anything
on a port that no record mentions belongs to somebody else, and a stage reuses
it. A stop kills the recorded pids and then sweeps the ports that the run owns.

The server stage

The stage selects the least costly server that has the feature. A definition
gives the commit that added it:

"requires": { "serverCommit": "01aa279c462fd9e7efc8e0ba6bbc4554b51557dd" }

The stage finds the release line of that commit from its tags, then it tries a
CLI on disk, then a release, then a build of your server checkout. It gives the
reason:

Commit 01aa279c4 is on main and first tagged 1.32.0-157.0, so any Server
1.32.0-157.0 or later has it.
The latest CLI release bundles Server 1.31.2, which is too old. Compiling the
server checkout instead.

When a release has the operation, the same definition uses that release, with no
change and no Go tools.

The build uses a Go workspace in .feature-demo, thus it changes no repository:
it adds no replace directive and it writes no go.work in a checkout. A
definition gives no path to a checkout, because a path belongs to a machine. Set
TEMPORAL_SERVER_REPO and TEMPORAL_CLI_REPO, or copy
.env.feature-demo.local.example. The paths are read only if a build is
necessary.

The Catalog does the work

The workflows are Catalog examples and the worker is the Catalog worker, thus a
demo shows the same code that the Catalog page runs. A definition gives an
example id only, and the workflow type, the task queue, and the input schema come
from the Catalog. An input that disagrees with the schema of an example stops the
run before anything starts.

The caller of the operation is an ordinary workflow, because the reserved
__temporal_ prefix is refused by the Go SDK only. TypeScript has no encoder for
the payloads of the operation, which are binary/protobuf workflowservice
messages, thus payload-converter.ts supplies one and the caller runs on a
worker of its own. That converter is scaffolding: two tests fail when the SDK
makes it unnecessary, and each one says what to delete. The scenario also reads
the request that the server recorded and stops the run if a field that the UI
needs is absent.

Also here

pnpm catalog list shows the Catalog examples and their ids, which a person
needs to write a definition. It is a separate commit, and it can become a
separate PR if the Catalog owners prefer.

The system Nexus skill documents that the Go SDK alone refuses the reserved
prefix, and that the true limit for TypeScript is the encoding of the payloads.

To review

1. pnpm demo list, then pnpm demo start system-nexus-signal-with-start.
2. Follow the steps that the summary gives. They check the display that DT-4385
   adds.
3. pnpm demo stop.

pnpm lint:ci, pnpm check, pnpm catalog verify, and pnpm test -- --run all
pass. 44 tests cover the dispatcher, the selection of a server, and the reasons
this scenario ships a caller of its own.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
holocene	Ready	Preview	Aug 20, 2026 4:36pm