feat(process-instance): add suspend and resume commands

[kristinkomschow]

Summary

• Add c8ctl suspend process-instance <key> and c8ctl resume process-instance <key>
• Wired through COMMAND_REGISTRY / COMMAND_DISPATCH, calling the SDK's suspendProcessInstance / resumeProcessInstance (POST /process-instances/{key}/suspension and /resumption)
• README.md and docs/command-reference.md regenerated from the registry (single source of truth)

Version note: this REST endpoint only exists starting with Camunda 8.10 — 8.8/8.9 gateways 404 on it. Documented in .github/SDK_GAPS.md, called out in the command help text ("Camunda 8.10+"), and the live integration tests below are version-gated accordingly.

Closes camunda/camunda#57996

Test plan

• npm run typecheck
• npx biome check --fix (clean)
• npm run check:layering
• npm run build
• npm run test:unit (2339/2339 pass)
• npm test (integration watch.test.ts failures are pre-existing, require a live local cluster, unrelated to this change)
• Behavioural unit tests for suspend/resume dry-run and missing-key cases
• Live CLI integration tests (deploy a user-task process, suspend pi, poll get pi --fields state for SUSPENDED, resume pi, poll back to ACTIVE) — verified locally against Camunda 8.10 and 8.9 (confirms the 404 on 8.9), gated to 8.10+ in CI

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

Live integration coverage is needed because the current tests never execute either new SDK operation.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 2

Open (2)

• Add live CLI integration test for process instance suspension · New
• Add live CLI integration test for process instance resumption · New

What changed in this PR

Adds process-instance suspension and resumption commands through the existing command framework.

Changes:

• Registers and dispatches suspend and resume.
• Calls the corresponding SDK operations with dry-run support.
• Updates generated documentation and behavioural tests.

File	Description
src/​commands/​process-instances.ts	Implements both handlers.
src/​command-dispatch.ts	Wires handlers into dispatch.
src/​framework/​command-registry.ts	Declares command metadata.
tests/​unit/​process-instances-behaviour.test.ts	Tests dry-run and missing-key paths.
tests/​unit/​command-registry.test.ts	Updates registry expectations.
README.md	Lists the new verbs.
docs/​command-reference.md	Documents command usage.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Compatibility documentation and required help/completion and CLI-only integration-test coverage need correction.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

• Use CLI-only fixture setup and state polling in integration test · New

Resolved since last review (2)

• Add live CLI integration test for process instance resumption
• Add live CLI integration test for process instance suspension

Previously missed (2)

In code that hasn't changed since last review

Document Camunda 8.10 requirement in help and command references

.github/​SDK_GAPS.md:21

The Camunda 8.10 floor is only recorded in this contributor-facing file. The generated CLI help and public command reference advertise both commands without a version qualifier even though 8.8/8.9 remain supported targets, so users on those versions will encounter an unexplained 404. Add the requirement to both registry descriptions/help texts and regenerate README/docs.

Add suspend and resume to help and completion test coverage

tests/​unit/​command-registry.test.ts:45

These additions cover registry membership only. The existing help and completion tests explicitly enumerate exposed verbs but still omit suspend and resume, leaving the new generated help/completion entries without regression coverage. Add both verbs to those assertions, including detailed help and the process-instance (pi) <key> shape.

[Copilot]

Copilot review overview

🟡 Changes recommended

Public help omits the 8.10 compatibility floor, and the integration helper introduces a prohibited unchecked assertion.

Review effort: Balanced
Findings: 1

Open (1)

• Replace unchecked type assertion with runtime narrowing · New

Resolved since last review (1)

• Use CLI-only fixture setup and state polling in integration test

Previously missed (2)

In code that hasn't changed since last review

Mark command as available only in Camunda 8.10+

src/​framework/​command-registry.ts:1142

The repository supports Camunda 8.8/8.9, but this command is guaranteed to return 404 there, while the generated public help currently presents it without a version constraint. The internal SDK_GAPS.md entry is not user-facing. Add “(Camunda 8.10+)” to this help description, matching the existing Business ID annotations, and regenerate the command reference.

Mark resume command as available only in Camunda 8.10+

src/​framework/​command-registry.ts:1157

The generated public help also needs to identify resume as Camunda 8.10+; otherwise users of the supported 8.8/8.9 versions are told this command is available even though it always fails with 404. Annotate this help description and regenerate the command reference.

[Copilot]

Copilot review overview

🔵 Needs a closer look

User-facing help must disclose that both commands require Camunda 8.10 or newer.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Replace unchecked type assertion with runtime narrowing

Previously missed (1)

In code that hasn't changed since last review

Add Camunda 8.10+ requirement to command help and documentation

src/​framework/​command-registry.ts:1142

This command is unavailable on the supported Camunda 8.8/8.9 clusters, but neither its top-level nor detailed help says so; users discover the limitation only through a gateway 404. Include “Camunda 8.10+” in both descriptions and regenerate README/command-reference, following the existing version annotations in this registry (for example, lines 265 and 315).

This issue also appears on line 1156 of the same file.

[kristinkomschow]

Addressed the "Previously missed" finding from the latest Copilot review overview (Add Camunda 8.10+ requirement to command help and documentation, src/framework/command-registry.ts:1142/1156): both suspend/resume helpDescriptions now say "(Camunda 8.10+)", following the existing "(Camunda 8.9+)" convention used for the businessId flags. docs/command-reference.md regenerated. Pushed in c7cc180.

[Copilot]

Copilot review overview

🟢 Approval recommended

The implementation is correctly wired, documented, version-gated, and covered by behavioral and integration tests.

Review effort: Balanced
Findings: None

[kristinkomschow]

@jwulf I'm unsure who to request review from for this. I see that c8ctl ownership was moved to clients-sdks-ai-first-tooling (?) but I don't seem to be able to add that group as reviewer.