Enable global strict typechecking with real JSDoc types

AGENTS.md

@@ -41,7 +41,10 @@ indentation, double quotes, semicolons, and small named functions. Prefer
 dependency injection for testable command behavior, as seen in
 `runDeployCommand` and `runSecretCommand`. Use kebab-case CLI flags
 (`--control-url`) and uppercase environment variables (`ADMIN_TOKEN`,
-`CONTROL_URL`, `WDL_NS`).
+`CONTROL_URL`, `WDL_NS`). Types are JSDoc, checked by `npm run typecheck`
+(`tsc --noEmit`) under `strict`: annotate new parameters and returns with real
+types rather than `any`, and use `unknown` plus narrowing for values validated
+at runtime.
 
 Markdown wrapping is bilingual by design, normalized with Prettier
 (`--embedded-language-formatting=off`; code blocks are hand-formatted) and kept

CONTRIBUTING.md

@@ -22,7 +22,8 @@ resolution) is exercisable offline. To try commands end to end, point
 ## Architecture
 
 The CLI is plain ESM JavaScript — no build step; `tsc --noEmit` typechecks the
-JSDoc types.
+JSDoc types under `strict`, so new code needs real JSDoc annotations on
+parameters and returns (no implicit `any`).
 
 | Path                                    | Role                                                                                                                                                                                                        |
 | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

bin/wdl.js

@@ -28,6 +28,7 @@ const REGISTRY = [initCmd, deployCmd, secretCmd, workersCmd, deleteCmd, d1Cmd, r
 // Alias -> canonical command name.
 const ALIASES = { secrets: "secret" };
 
+/** @type {Record<string, CommandModule>} */
 const COMMANDS = Object.fromEntries(REGISTRY.map((c) => [c.meta.name, c]));
 for (const [alias, target] of Object.entries(ALIASES)) COMMANDS[alias] = COMMANDS[target];
 
@@ -38,6 +39,19 @@ for (const c of REGISTRY) {
   if (!c.meta.parseOptions) throw new Error(`command "${c.meta.name}" is missing meta.parseOptions`);
 }
 
+/**
+ * One entry of {@link REGISTRY}: a command module exposing its run entrypoint
+ * and the metadata the dispatcher reads.
+ * @typedef {{
+ *   main: (argv?: string[]) => Promise<void>,
+ *   meta: { name: string, summary: string, autoloadEnv: boolean, parseOptions: import("node:util").ParseArgsOptionsConfig },
+ * }} CommandModule
+ */
+
+/**
+ * @param {string[]} [argv]
+ * @param {{ env?: NodeJS.ProcessEnv, loadEnv?: NonNullable<Parameters<typeof import("../lib/credentials.js").loadCliControlEnv>[1]>["loadEnv"] | null }} [deps]
+ */
 export async function main(argv = process.argv.slice(2), deps = {}) {
   const [command, ...rest] = argv;
 
@@ -60,7 +74,8 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
   const scanned = scanCommandArgs(commandModule, rest);
   // Tests pass loadEnv: null to disable autoload; an injected loader (or the
   // real default when undefined) flows straight into loadCliControlEnv.
-  const loadEnvOverride = Object.hasOwn(deps, "loadEnv") ? deps.loadEnv : undefined;
+  /** @type {NonNullable<Parameters<typeof loadCliControlEnv>[1]>["loadEnv"]} */
+  const loadEnvOverride = (Object.hasOwn(deps, "loadEnv") ? deps.loadEnv : undefined) ?? undefined;
   const skipAutoload = Object.hasOwn(deps, "loadEnv") && !deps.loadEnv;
   // Help never needs credentials, so a malformed .env must not block it.
   if (!skipAutoload && commandModule.meta.autoloadEnv && !scanned.help) {
@@ -86,6 +101,10 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
 // positional alias `wdl <command> [flags] help` — are recognized with the
 // framework's own isHelpAlias. strict:false never throws on argv input; only
 // a broken option schema can throw, and that should surface loudly.
+/**
+ * @param {CommandModule} commandModule
+ * @param {string[]} args
+ */
 function scanCommandArgs(commandModule, args) {
   const { values, positionals } = parseArgs({
     args,
@@ -108,8 +127,10 @@ function scanCommandArgs(commandModule, args) {
   };
 }
 
+/** @param {number} exitCode */
 function usage(exitCode) {
   // Aliases grouped by the command they point at, for the "(alias: …)" note.
+  /** @type {Record<string, string[]>} */
   const aliasesByTarget = {};
   for (const [alias, target] of Object.entries(ALIASES)) {
     (aliasesByTarget[target] ??= []).push(alias);

commands/config.js

@@ -18,7 +18,7 @@ export const main = command.main;
 export const runConfigCommand = command.run;
 export const meta = command.meta;
 
-/** @param {{ values: Record<string, any>, positionals: string[], context: import("../lib/command.js").CommandContext }} arg */
+/** @param {{ values: { json?: boolean }, positionals: string[], context: import("../lib/command.js").CommandContext }} arg */
 async function runConfig({ values, positionals, context }) {
   const [subcommand, extra] = positionals;
   if (subcommand !== "explain" || extra) throw new CliError(usageText());
@@ -29,10 +29,22 @@ async function runConfig({ values, positionals, context }) {
     controlUrl: publicEntry(state.controlUrl),
     token: publicEntry(state.token),
   };
-  writeResult(values.json, body, () => formatConfigExplain(body), context.stdout);
+  writeResult(values.json === true, body, () => formatConfigExplain(body), context.stdout);
 }
 
+/**
+ * @typedef {object} PublicConfigEntry
+ * @property {string} value
+ * @property {string} source
+ * @property {string} [error]
+ */
+
+/**
+ * @param {import("../lib/config-state.js").ConfigEntry} entry
+ * @returns {PublicConfigEntry}
+ */
 function publicEntry(entry) {
+  /** @type {PublicConfigEntry} */
   const out = {
     value: entry.display,
     source: entry.source,
@@ -41,6 +53,9 @@ function publicEntry(entry) {
   return out;
 }
 
+/**
+ * @param {{ namespace: PublicConfigEntry, controlUrl: PublicConfigEntry, token: PublicConfigEntry }} body
+ */
 function formatConfigExplain(body) {
   return [
     ...formatBlock("namespace", body.namespace),
@@ -51,6 +66,10 @@ function formatConfigExplain(body) {
   ];
 }
 
+/**
+ * @param {string} name
+ * @param {PublicConfigEntry} entry
+ */
 function formatBlock(name, entry) {
   const lines = [
     `${name}:`,