Enable global strict typechecking with real JSDoc types

[cnluzhang]

Summary

Flip the CLI to TypeScript strict globally (tsconfig.json → "strict": true) and annotate the whole tree — bin/, commands/, lib/, and the test suite — with real JSDoc types. No .ts conversion, no build step: it stays plain ESM JS checked by tsc --noEmit, matching the repo's existing approach.

npm run typecheck (already run in CI on every PR) now enforces strict, so no workflow change is needed.

What changed

• Foundational lib typed first, introducing the shared typedefs the rest reference: ControlResponse (+ looser ControlResponseStatus/ControlJsonResponse for test fakes), TokenStore, plus a shared hasErrorCode guard.
• wrangler, formatters, commands, bin typed against those shapes (WranglerConfig, D1Database, R2Object, WhoamiBody, SseEvent, DoctorCheck, …); parsers that re-validate their input take unknown and narrow.
• Test suite typed (mock deps/fakes, recorder arrays, catch (err) narrowing); the shared ControlCall shape lives once in tests/unit/helpers.js.
• tsconfig.json: only strict flips false → true; every other option/include/exclude is unchanged.

No any escape hatches

The conversion uses real types throughout — zero any (including Record<string, any> and (...args: any[])) and zero @ts-ignore/@ts-expect-error/@ts-nocheck. Notable choices:

• Self-guarding validators and wire-parsed JSON take unknown and narrow.
• EventEmitter surfaces use a generic <A extends unknown[]> listener instead of any[].
• defineCommand's run uses method syntax (bivariant) so each command types its own values shape without an any in the framework contract.

Behavior changes

Aside from these, the change is types-only. Typing the parsers surfaced several places where malformed wrangler config was silently dropped or produced a cryptic low-level error rather than the "map or loudly reject — silent drops are bugs" contract the rest of the parsers follow. Each is now a clear, fail-fast error, and each is covered by a new unit test:

1. parseServicesFromCfg now requires binding and service to be non-empty strings, matching the d1/r2 parsers — previously a non-string truthy service flowed into the deploy manifest and a non-string binding (e.g. ["AB"]) was String()-coerced past the binding-name regex.
2. ensureControlContextFromConfigState fails closed with "No control URL configured" when the URL is unresolved, instead of returning null typed as string.
3. collectRoutes throws when routes is present but not an array, instead of silently ignoring it and deploying a worker with no routes. (Added in review.)
4. resolveAssetsDir / assets.directory rejects a present-but-empty or non-string directory with a clear error, instead of silently skipping "" or hitting path.resolve as a TypeError. (Added in review.)

All four are intentional hardenings that only reject input that was never valid; no previously-valid config is rejected.

Docs

CONTRIBUTING.md and AGENTS.md now note that tsc runs under strict and new code needs real JSDoc types. CHANGELOG.md is intentionally untouched (this repo curates it at release time, not per-PR).

Checks

npm run lint, npm run typecheck (strict), and npm test all pass — 377/377 unit tests green, eslint clean. The diff is types-only apart from the four tested config-validation hardenings above.

The branch went through two review passes (incremental, then a full 8-angle pass over the whole diff) plus the inline PR review; cleanups and fixes from all of them are folded in.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This pull request enables TypeScript strict checking across the CLI’s existing ESM JavaScript codebase by adding comprehensive, “real” JSDoc types (no .ts conversion / no emit), while also incorporating two small runtime hardening fixes discovered during typing work.

Changes:

• Turn on tsc strict mode (tsconfig.json) and annotate the CLI implementation + tests with concrete JSDoc types/guards.
• Introduce/propagate shared typed shapes for control-plane IO, Wrangler config parsing, command context, and test fakes.
• Apply and test two behavior fixes: stricter [[services]] parsing and failing closed when the control URL is unresolved.

Reviewed changes

Copilot reviewed 55 out of 57 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tsconfig.json	Enables global strict typechecking.
tests/unit/helpers.js	Adds shared ControlCall typedef + typed test deps helpers.
tests/unit/cli-token.test.js	Tightens test typings (stdin fakes, caught error narrowing, controlFetch fakes).
tests/unit/cli-token-store.test.js	Adds JSDoc typing for temp-dir and permission tests.
tests/unit/cli-stdin.test.js	Types TTY/raw-mode fakes and stderr capture arrays.
tests/unit/cli-output.test.js	Types stdout capture and callback parameters.
tests/unit/cli-init.test.js	Types exit-capture wiring and console overrides for strict mode.
tests/unit/cli-deploy.test.js	Adds typed recorded-call shapes and narrows JSON parsing in assertions.
tests/unit/cli-d1.test.js	Adds typed request-body parsing helpers and recorded-call typing.
tests/unit/cli-credentials.test.js	Adds typed env/warnings collections and loader signatures.
tests/unit/cli-control-fetch.test.js	Types fake transport/streams for strict mode streaming tests.
tests/unit/cli-config-doctor.test.js	Expands strict typings + adds coverage for fail-closed control URL context.
tests/unit/cli-command.test.js	Types command-spec test scaffolding and runtime-invalid spec casts.
lib/wrangler/utils.js	Adds typed helpers (manifestMap, hasOwn, asRecord).
lib/wrangler/modules.js	Types module collection return shape.
lib/wrangler/config.js	Types Wrangler config shapes and improves error message extraction.
lib/wrangler/command.js	Adds typed exec failure shaping + narrows formatter inputs.
lib/wrangler/bindings.js	Adds typed binding parsers; hardens [[services]] string validation.
lib/wrangler/assets.js	Adds typed signatures to assets dir resolution and ignore matcher helpers.
lib/wrangler-pack.js	Adds manifest typedefs + tighter typing around Wrangler config/assets parsing.
lib/workflows-format.js	Adds typed workflow formatter input shapes.
lib/workers-format.js	Adds typed worker formatter input shapes.
lib/whoami.js	Adds whoami response typedefs + fail-closed config-state→control-context helper.
lib/token-store.js	Adds TokenStore typedef and uses hasErrorCode for fs error narrowing.
lib/stdin.js	Refines StdinLike typing and narrows callbacks in stdin readers.
lib/r2-format.js	Adds typed shapes for R2 list/head formatters.
lib/package-info.js	Adds return-type annotations for package.json helpers.
lib/output.js	Adds typed signatures for output helpers and warning formatting.
lib/ns-pattern.js	Adds predicate return types for identifier/ns validators.
lib/dotenv.js	Adds typed signatures for dotenv parsing/quoting helpers.
lib/delete-format.js	Adds typed delete-format body shapes; narrows numeric checks.
lib/d1-format.js	Adds typed shapes for D1 formatter inputs.
lib/d1-files.js	Hardens --file validation and adds typed migration-file filtering.
lib/credentials.js	Adds typed signatures for env resolution and uses hasErrorCode for ENOENT.
lib/control-fetch.js	Adds typed ControlResponse/init/transport surfaces and improves stream typing.
lib/config-state.js	Introduces ConfigEntry typedef and tightens config resolution typing.
lib/common.js	Adds option/typedef structure and introduces hasErrorCode guard.
lib/command.js	Tightens CommandContext typing and stabilizes fetch helper signatures.
lib/bundle-modules.js	Adds typed signatures for module wire encoding helpers.
CONTRIBUTING.md	Documents strict tsc expectations and “real JSDoc” requirement.
commands/workflows.js	Types workflow command flag values and narrows formatter inputs.
commands/workers.js	Types workers list response shape passed to formatter.
commands/whoami.js	Types whoami command flag values and output mode selection.
commands/token.js	Introduces typed TokenValues and token list row typedefs.
commands/tail.js	Adds typed SSE/tail payload shapes and strict typing across stream/render logic.
commands/secret.js	Adds typed secret response/warning shapes and narrows worker scope checks.
commands/r2.js	Adds typed R2Context, header handling, and streaming body typing.
commands/init.js	Adds typed CLI arg parsing and filesystem error narrowing.
commands/doctor.js	Adds typed doctor context/check shapes and strict typing for config/whoami checks.
commands/deploy.js	Adds deploy warning typedefs + typed pack options and control responses.
commands/delete.js	Types delete command flag values and formatter inputs.
commands/d1.js	Introduces D1Flags and tightens request/response shapes and param parsing.
commands/config.js	Types config command flag values + public config entry shape.
bin/wdl.js	Adds dispatcher module typedefs and tighter typing around loadEnv overrides.
AGENTS.md	Documents strict tsc + JSDoc typing expectations for contributors/agents.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 55 out of 57 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 55 out of 57 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 55 out of 57 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 55 out of 57 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 55 out of 57 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 55 out of 57 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 55 out of 57 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 55 out of 57 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

tests/unit/cli-stdin.test.js:93

• The PR description says there are zero any uses, but this branch still has /** @type {any} */ casts (e.g. confirmAction({ stdin: /** @type {any} */ ({ isTTY: false }), … }) later in this file). Please replace these with unknown/structural types (or update the PR description if keeping them is intentional).

[Copilot]

Pull request overview

Copilot reviewed 55 out of 57 changed files in this pull request and generated no new comments.