Audit fixes: qualify() helper, docs onboarding, CI hardening, testing coverage

[btravers]

Summary

Fixes from a full project audit (code health, security, DX):

New API — qualify() (worker, minor)

• qualify(type, options?) builds the fromPromise qualifier, replacing the ~8-line ApplicationFailure.create boilerplate repeated in every activity. Error rejections keep their message and are preserved as cause; nonRetryable / details / fallback message supported. Always wraps so the declared type is guaranteed for retry policies. Dogfooded in the order-processing example.

Packages

• @temporal-contract/testing: @temporalio/client and @temporalio/worker moved to peer dependencies — their types leak through the public it fixture (breaking, see changeset; edit .changeset/audit-fixes.md down to minor if you consider it non-breaking in practice). Phantom config entry dropped from files, keywords added.
• All packages: sideEffects: false; worker's last explicit any replaced with ChildWorkflowHandle<Workflow>; JSDoc examples fixed to ESM-correct imports.
• Example workflow rethrows cancellation (isCancellation) instead of swallowing it in the notification catch.

Tests

• Testing package had zero tests; extension.ts and global-setup.ts now covered (mocked testcontainers/Temporal). New spec for contract/src/format.ts.

CI

• All actions pinned to commit SHAs; test job matrix adds Node 22.19.0 (the declared engines floor); timeout-minutes everywhere; release no longer builds twice.

Docs

• Getting-started now compiles as written (qualify, createWorker + workflowsPathFromURL instead of require.resolve); .js extensions on all ~45 relative snippet imports; 12 require.resolve sites replaced.
• Installation prerequisites corrected (Node 22.19+, TS 6.0); testing package requirements (Vitest 4, ESM-only, Docker) stated.
• New Testing guide; README gets full peer install block and a Stability & Versioning section; migration guides demoted to a collapsed sidebar group; stale claims fixed; stray docs/package-lock.json removed.

Test plan

• pnpm lint / pnpm format / pnpm knip clean
• pnpm typecheck — 12/12 tasks
• pnpm test — 9/9 tasks (incl. 6 new testing-package tests, 12 new format tests, 6 new qualify tests)
• pnpm test:integration — 8/8 tasks against a real Temporal server (Docker)
• pnpm build + typedoc regen + VitePress docs build (validates dead links, incl. the new /guide/testing)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR applies a broad “audit fixes” pass across temporal-contract, focusing on reducing activity boilerplate via a new qualify() helper, aligning docs/snippets with the repo’s ESM + .js import requirements, strengthening CI, and adding missing test coverage.

Changes:

• Added qualify(type, options?) to @temporal-contract/worker/activity and updated examples/docs to use it.
• Hardened workflows/docs for ESM correctness (.js extensions, workflowsPathFromURL(...) vs require.resolve), and improved onboarding docs.
• Expanded coverage (new unit specs for worker qualify + contract formatters; introduced a Vitest setup + tests for @temporal-contract/testing) and tightened CI (timeouts, matrix, pinned actions).

Reviewed changes

Copilot reviewed 37 out of 39 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
README.md	Updates public-facing examples/install instructions to use qualify and peer-dep install guidance.
pnpm-lock.yaml	Lockfile updates reflecting dependency/peer-dep reshuffles (notably testing package).
packages/worker/src/workflow.ts	Fixes JSDoc snippet imports to be ESM-correct (.js).
packages/worker/src/worker.ts	Updates JSDoc to use workflowsPathFromURL and ESM imports.
packages/worker/src/child-workflow.ts	Removes internal any in child workflow handle typing.
packages/worker/src/activity.ts	Introduces qualify() helper and updates docs/examples within the module.
packages/worker/src/activity.spec.ts	Adds test coverage for qualify() behavior.
packages/worker/package.json	Declares sideEffects: false for better tree-shaking.
packages/testing/vitest.config.ts	Adds Vitest config with coverage + injected testcontainers address.
packages/testing/src/global-setup.spec.ts	Adds unit coverage for Vitest globalSetup via mocked testcontainers.
packages/testing/src/extension.spec.ts	Adds unit coverage for it fixture extension (mocked Temporal connections).
packages/testing/package.json	Adds keywords, sideEffects: false, Vitest scripts, and moves Temporal SDK deps to peers.
packages/contract/src/format.spec.ts	Adds tests for formatIssue / summarizeIssues rendering.
packages/contract/package.json	Declares sideEffects: false.
packages/client/package.json	Declares sideEffects: false.
examples/order-processing-worker/src/application/workflows.ts	Ensures workflow cancellation propagates (isCancellation).
examples/order-processing-worker/src/application/activities.ts	Dogfoods qualify() to remove repeated ApplicationFailure.create boilerplate.
docs/package-lock.json	Removes stray lockfile from docs.
docs/guide/worker-usage.md	Updates snippets for ESM .js imports and workflowsPathFromURL.
docs/guide/worker-implementation.md	Updates snippets for ESM .js imports.
docs/guide/troubleshooting.md	Updates snippets to workflowsPathFromURL and qualify.
docs/guide/testing.md	Adds a new testing guide for @temporal-contract/testing.
docs/guide/result-pattern.md	Updates imports in snippets to ESM .js.
docs/guide/nexus-integration.md	Updates snippets to ESM .js and workflowsPathFromURL.
docs/guide/installation.md	Updates prerequisites and adds warnings about testing package requirements.
docs/guide/getting-started.md	Updates onboarding snippets to use qualify and ESM-safe workflow path resolution.
docs/guide/entry-points.md	Updates workflow path examples to workflowsPathFromURL and .js exports.
docs/guide/client-usage.md	Updates snippet imports to ESM .js.
docs/guide/activity-handlers.md	Adds qualify guidance and converts examples to use it + ESM .js imports.
docs/.vitepress/config.ts	Adds Testing guide nav entry; moves migration guides into a collapsed group.
CONTRIBUTING.md	Aligns prerequisites with supported Node/pnpm versions.
.github/workflows/release.yml	Adds timeout, pins actions to SHAs, removes redundant build step.
.github/workflows/deploy-docs.yml	Adds timeouts and pins actions to SHAs.
.github/workflows/ci.yml	Adds timeouts, pins actions, expands test matrix (Node floor), renames artifacts.
.github/actions/setup/action.yml	Adds node-version override input; pins setup/cache actions to SHAs.
.changeset/qualify-helper.md	Changeset documenting new qualify() helper release.
.changeset/audit-fixes.md	Changeset summarizing audit fixes and the testing package breaking change.
.agents/rules/handlers.md	Updates handler guidance to mention qualify().
.agents/rules/dependencies.md	Updates peer-dependency policy table and security override guidance.

Files not reviewed (2)

• docs/package-lock.json: Generated file
• pnpm-lock.yaml: Generated file