feat(cli): add durable workflow and executor waiters

[dqn]

Summary

Add durable waiter commands and shared polling behavior for workflow executions and executor jobs so automation can wait through transient platform states with stable JSON diagnostics.

Main changes

• Add workflow wait <execution-id> and reuse the workflow waiter from workflow start --wait, workflow executions --wait, and workflow resume --wait.
• Add workflow wait targets, timeout handling, retryable polling, log support, and JSON diagnostics.
• Harden executor job waiting for executor trigger --wait and executor jobs ... --wait with timeout diagnostics and downstream execution tracking.
• Document shell automation commands and programmatic API examples for workflow and executor waiters.

Examples

Wait for a workflow execution captured from workflow start:

execution_id="$(
  tailor-sdk workflow start order-workflow --json | jq -r '.executionId'
)"

tailor-sdk workflow wait "$execution_id" \
  --until success \
  --timeout 10m \
  --interval 5s \
  --json

Wait for an executor job and downstream execution:

tailor-sdk executor trigger daily-workflow \
  --wait \
  --timeout 5m \
  --interval 5s \
  --json

Use the programmatic workflow waiter:

import { waitWorkflowExecution } from "@tailor-platform/sdk/cli";

const result = await waitWorkflowExecution({
  executionId,
  until: "success",
  timeout: 10 * 60 * 1000,
  interval: 5000,
});

Use the programmatic executor waiter:

import { triggerExecutor, watchExecutorJob } from "@tailor-platform/sdk/cli";
import dailyWorkflow from "../executors/dailyWorkflow";

const { jobId } = await triggerExecutor({
  executor: dailyWorkflow,
});

const result = await watchExecutorJob({
  executor: dailyWorkflow,
  jobId,
  timeout: 5 * 60 * 1000,
  interval: 5000,
});

[changeset-bot]

🦋 Changeset detected

Latest commit: 0b8ef93

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@tailor-platform/sdk	Minor
@tailor-platform/create-sdk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

pnpm add https://pkg.pr.new/@tailor-platform/create-sdk@0b8ef93

pnpm add https://pkg.pr.new/@tailor-platform/sdk@0b8ef93

commit: 0b8ef93

[toiroakr]

@dqn
Sorry for the late reply.
This looks good, so could you please resolve the conflicts and set it to ready?

[github-actions]

Code Metrics Report (packages/sdk)

	main (36f3d1d)	#1338 (a82147b)	+/-
Coverage	68.8%	69.5%	+0.7%
Code to Test Ratio	1:0.4	1:0.4	-0.1

Details

  |                    | main (36f3d1d) | #1338 (a82147b) |  +/-  |
  |--------------------|----------------|-----------------|-------|
+ | Coverage           |          68.8% |           69.5% | +0.7% |
  |   Files            |            420 |             422 |    +2 |
  |   Lines            |          14898 |           15078 |  +180 |
+ |   Covered          |          10250 |           10490 |  +240 |
- | Code to Test Ratio |          1:0.4 |           1:0.4 |  -0.1 |
  |   Code             |          99713 |          100903 | +1190 |
+ |   Test             |          44571 |           45065 |  +494 |

Code coverage of files in pull request scope (9.7% → 40.8%)

Files	Coverage	+/-	Status
packages/sdk/src/cli/commands/executor/jobs.ts	33.7%	+33.1%	modified
packages/sdk/src/cli/commands/executor/status.ts	47.7%	+18.3%	modified
packages/sdk/src/cli/commands/executor/trigger.ts	35.8%	+23.3%	modified
packages/sdk/src/cli/commands/workflow/args.ts	100.0%	0.0%	modified
packages/sdk/src/cli/commands/workflow/executions.ts	15.1%	+14.2%	modified
packages/sdk/src/cli/commands/workflow/index.ts	50.0%	0.0%	modified
packages/sdk/src/cli/commands/workflow/resume.ts	3.2%	-1.0%	modified
packages/sdk/src/cli/commands/workflow/start.ts	71.1%	+43.0%	modified
packages/sdk/src/cli/commands/workflow/status.ts	90.4%	+90.4%	modified
packages/sdk/src/cli/commands/workflow/transform.ts	26.0%	+26.0%	modified
packages/sdk/src/cli/commands/workflow/wait.ts	47.6%	+47.6%	added
packages/sdk/src/cli/commands/workflow/waiter.ts	72.9%	+72.9%	added

SDK Configure Bundle Size

	main (36f3d1d)	#1338 (a82147b)	+/-
configure-index-size	20.09KB	20.09KB	0KB
dependency-chunks-size	0KB	0KB	0KB
total-bundle-size	20.09KB	20.09KB	0KB

Runtime Performance

	main (36f3d1d)	#1338 (a82147b)	+/-
Generate Median	3,002ms	2,992ms	-10ms
Generate Max	3,101ms	3,063ms	-38ms
Apply Build Median	3,044ms	3,071ms	27ms
Apply Build Max	3,057ms	3,091ms	34ms

Type Performance (instantiations)

	main (36f3d1d)	#1338 (a82147b)	+/-
tailordb-basic	36,212	36,212	0
tailordb-optional	3,841	3,841	0
tailordb-relation	6,012	6,012	0
tailordb-validate	2,566	2,566	0
tailordb-hooks	5,777	5,777	0
tailordb-object	12,136	12,136	0
tailordb-enum	2,462	2,462	0
resolver-basic	9,438	9,438	0
resolver-nested	26,125	26,125	0
resolver-array	18,201	18,201	0
executor-schedule	4,268	4,268	0
executor-webhook	907	907	0
executor-record	6,788	6,788	0
executor-resolver	4,417	4,417	0
executor-operation-function	899	899	0
executor-operation-gql	903	903	0
executor-operation-webhook	918	918	0
executor-operation-workflow	1,747	1,747	0

---

Reported by octocov

[dqn]

Resolved the merge conflict.

[github-actions]

📖 Docs Quality & Consistency Check

✅ Docs are consistent with the implementation and contain no user-facing internal-detail leaks.

Checked areas:

• packages/sdk/docs/cli-reference.md - verified new workflow wait command entry matches implementation
• packages/sdk/docs/cli/workflow.md - verified all command options (defaults, aliases, descriptions) match command definitions in packages/sdk/src/cli/commands/workflow/wait.ts and args.ts
• packages/sdk/docs/cli/executor.md - verified timeout option additions and shell automation examples match implementation
• Shell automation examples - verified all examples use correct command syntax and options
• Programmatic API examples - verified waitWorkflowExecution and watchExecutorJob function signatures match exported functions from packages/sdk/src/cli/lib.ts
• JSDoc comments on exported functions - verified they describe user-facing behavior without leaking internal implementation details

Implementation consistency verified:

• CLI command options (interval, timeout, until, logs) match their definitions in packages/sdk/src/cli/commands/workflow/args.ts
• Default values documented correctly: interval: "3s", timeout: "10m" (workflow), timeout: "5m" (executor), until: "terminal"
• Wait targets (success, suspended, terminal) match the WorkflowWaitUntil type definition
• Return types documented correctly: WorkflowWaitResult includes statusClass, elapsedMs, attempts, timedOut, lastError
• Executor wait result includes targetType, job, workflowExecutionId, functionExecutionId fields as implemented

Reader perspective verified:

• Documentation uses only user-facing terminology (execution, job, workflow, executor, wait target)
• No protobuf/gRPC terminology exposed
• No internal module structure (parser, configure, cli) mentioned
• No internal class/method names revealed
• Examples import only from public API: @​tailor-platform/sdk/cli
• Describes observable behavior, not internal mechanics (e.g., "wait for completion" not "poll platform RPC until terminal state")

Re-run this check by adding the docs-check label to the PR.

---