@fitchmultz/pi-subagents 0.52.10 → 0.52.12

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## 0.52.12 - 2026-11-02
+
+<!-- npm-release:unreleased:start -->
+<!-- npm-release:unreleased:end -->
+
+- Merge pull request #326 from fitchmultz/chore/oxlint-v512-records ([e8ff5c5](https://github.com/fitchmultz/pi-subagents/commit/e8ff5c54a0efc481875949e98f96223c4d46ffc4))
+
+### What's Changed
+
+- Adopt the strict standard records and policy integrity keeper (5/5) by @fitchmultz in https://github.com/fitchmultz/pi-subagents/pull/326
+
+**Full Changelog**: https://github.com/fitchmultz/pi-subagents/compare/v0.52.11...v0.52.12
+
+## 0.52.11 - 2026-11-02
+
+<!-- npm-release:unreleased:start -->
+<!-- npm-release:unreleased:end -->
+
+- Merge pull request #325 from fitchmultz/chore/oxlint-v512-checkjs ([f55599c](https://github.com/fitchmultz/pi-subagents/commit/f55599cbf8c23c6ee1f9b5e55e7b963bc7140d58))
+
+### What's Changed
+
+- Enable checkJs and clear every strict-lint error in scripts and fixtures (4/5) by @fitchmultz in https://github.com/fitchmultz/pi-subagents/pull/325
+
+**Full Changelog**: https://github.com/fitchmultz/pi-subagents/compare/v0.52.10...v0.52.11
+
 ## 0.52.10 - 2026-11-02
 
 <!-- npm-release:unreleased:start -->

package/dist/build-info.js

@@ -1 +1 @@
-export const EXTENSION_BUILD = Object.freeze({"version":"0.52.10","sha256":"afeb6d4b7e13dfe796c199d39eddf3836e8f7ee7185f302254f4182659a0388c"});
+export const EXTENSION_BUILD = Object.freeze({"version":"0.52.12","sha256":"afeb6d4b7e13dfe796c199d39eddf3836e8f7ee7185f302254f4182659a0388c"});

package/docs/code-quality.md

@@ -39,3 +39,47 @@ substitutes the selected host graph. The retired workflow schema generator and
 its patching dependency are not part of the new runtime. `npm run check:size`
 still reports source and production line counts for visibility; no line count
 is mandated. The 1 MiB byte ceiling and all lint limits stay unchanged.
+
+## Adoption record
+
+Repository: `fitchmultz/pi-subagents`. Adopted standard: strict Oxlint/Oxfmt
+engineering standard v5.1.2, kept as the repository copy at
+`docs/strict-oxlint-oxfmt-standard.md`. Exception records live in
+[Quality exceptions](quality-exceptions.md) and follow the standard's Appendix B.
+
+Supported runtime and package manager: Node `>=24.21.0` with npm and the
+committed lockfile. Installed tool versions (devDependencies): oxlint 1.90.0,
+oxlint-tsgolint 7.0.2005, oxfmt 0.75.0, `@types/node` 24.19.2, typebox 1.4.3.
+
+Configuration and acceptance paths: lint `.oxlintrc.json`, formatting
+`.oxfmtrc.json`, compiler `tsconfig.json`. Local acceptance commands are
+`npm run lint`, `npm run format:check` and `npm run typecheck`; the aggregate
+acceptance command is hosted `npm run ci` (lint, formatting, TypeScript, byte
+ceiling, package/install smokes and the complete test suites, plus separate
+official-Pi and fork qualification jobs).
+
+Compiler projects and source profiles: one `tsc --noEmit` project covers all
+maintained TypeScript and checked-JavaScript (`src`, `scripts`, `test`,
+`.github`) with `strict`, `checkJs`, `noUncheckedIndexedAccess`,
+`exactOptionalPropertyTypes` and the full strict flag set. Lint profiles:
+production limits (complexity 10, depth 3, parameters 4, statements 40,
+function lines 80, file lines 500), test/fixture limits (complexity 15, depth
+4, parameters 6, no size limits) and declaration files with size limits off.
+
+Formatter and generator ownership: oxfmt formats all maintained source at
+width 100; npm owns lockfile formatting; build outputs keep their own bytes.
+
+Migration status: complete. The toolchain, baseline configuration, strict
+TypeScript compiler options, checked-JavaScript coverage and this records
+policy landed as PRs #319, #320, #321, #325 and the records PR; the policy
+integrity keeper `test/unit/strict-oxlint-policy.test.ts` pins the effective
+configuration, the four-entry overrides inventory and the directive rule-name
+inventory against drift.
+
+Integrated verification: hosted `npm run ci` on the merge of each part, with
+the single-agent-runtime, agent-receipts, pi-intercom-native-replay and
+retired-history-archive keepers exercising the native contracts. Locally
+verified state for the checked-JavaScript part is recorded in PR #325; the
+retired-history-archive suite requires passwordless `sudo` and
+`scripts/package-smoke.mjs` requires a short Unix socket directory, so hosted
+CI is the authoritative gate for both.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitchmultz/pi-subagents",
-  "version": "0.52.10",
+  "version": "0.52.12",
   "description": "Pi extension for subagent orchestration and local session coordination",
   "license": "MIT",
   "type": "module",

package/scripts/archive-retired-history.mjs

@@ -389,6 +389,21 @@ function prepare(values, uid) {
   syncDirectory(path.dirname(archive));
   return inspect(record, uid);
 }
+function ownerUid(/** @type {{ "owner-uid"?: string }} */ values) {
+  assert.match(values["owner-uid"] ?? "", /^(?:0|[1-9][0-9]*)$/, "E_OWNER_UID");
+  const uid = Number(values["owner-uid"]);
+  assert.ok(Number.isSafeInteger(uid) && uid <= 4_294_967_294, "E_OWNER_UID");
+  return uid;
+}
+
+function requireLinuxCapability() {
+  const capability = /^CapEff:\s*([a-f0-9]+)$/im.exec(fs.readFileSync("/proc/self/status", "utf8"));
+  assert.ok(capability !== null, "E_PROCESS_VISIBILITY");
+  const capEff = capability[1];
+  assert.ok(capEff !== undefined, "E_PROCESS_VISIBILITY");
+  assert.ok((BigInt(`0x${capEff}`) & (1n << 19n)) !== 0n, "E_PROCESS_VISIBILITY");
+}
+
 function main() {
   const { values, positionals } = parseArgs({
     options: {
@@ -408,23 +423,15 @@ function main() {
     return;
   }
   assert.ok(positionals.length === 1, "E_ACTION");
-  const action = positionals[0];
+  const action = positionals[0] ?? "";
   assert.ok(["prepare", "inspect", "archive"].includes(action), "E_ACTION");
   assert.ok(["linux", "darwin"].includes(process.platform), "E_PLATFORM");
   assert.ok(process.geteuid !== undefined, "E_PLATFORM");
   assert.ok(process.geteuid() === 0, "E_PRIVILEGE");
   if (process.platform === "linux") {
-    const capability = /^CapEff:\s*([a-f0-9]+)$/im.exec(
-      fs.readFileSync("/proc/self/status", "utf8"),
-    );
-    assert.ok(capability !== null, "E_PROCESS_VISIBILITY");
-    const capEff = capability[1];
-    assert.ok(capEff !== undefined, "E_PROCESS_VISIBILITY");
-    assert.ok((BigInt(`0x${capEff}`) & (1n << 19n)) !== 0n, "E_PROCESS_VISIBILITY");
+    requireLinuxCapability();
   }
-  assert.match(values["owner-uid"] ?? "", /^(?:0|[1-9][0-9]*)$/, "E_OWNER_UID");
-  const uid = Number(values["owner-uid"]);
-  assert.ok(Number.isSafeInteger(uid) && uid <= 4_294_967_294, "E_OWNER_UID");
+  const uid = ownerUid(values);
   if (action !== "inspect") {
     assert.ok(values.quiesced === true, "E_QUIESCENCE_ACK");
   }
@@ -454,7 +461,7 @@ try {
 } catch (error) {
   let code = "E_INSPECTION_FAILED";
   if (error instanceof assert.AssertionError && !error.generatedMessage) {
-    const firstLine = error.message.split("\n")[0];
+    const firstLine = error.message.split("\n")[0] ?? "";
     if (/^E_[A-Z_]+$/.test(firstLine)) {
       code = firstLine;
     }

package/scripts/build.mjs

@@ -20,8 +20,14 @@ import { setTimeout as delay } from "node:timers/promises";
 import { promisify } from "node:util";
 import { compilerInvocation } from "./typescript.mjs";
 
+/** @type {(file: string, args: readonly string[], options: import("node:child_process").ExecFileOptions) => Promise<{ stdout: string, stderr: string }>} */
+// oxlint-disable-next-line typescript/strict-void-return
 const execFile = promisify(execFileCallback);
 const RM_OPTIONS = { force: true, maxRetries: 5, recursive: true, retryDelay: 100 };
+
+function isErrno(/** @type {unknown} */ error, /** @type {string} */ code) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
 const RENAME_RETRY_LIMIT = 50;
 const RENAME_RETRY_MS = 50;
 
@@ -32,26 +38,28 @@ if (process.argv.includes("--help") || process.argv.includes("-h")) {
   process.exit(0);
 }
 
-async function discardStaging(path) {
+async function discardStaging(/** @type {string} */ path) {
   try {
     await rm(path, RM_OPTIONS);
   } catch (error) {
     // Cleanup is always best-effort: it must not turn a successful race loss
     // into failure or replace the compiler/publish error that matters.
-    console.warn(`could not remove staging ${path}: ${error?.message ?? error}`);
+    console.warn(
+      `could not remove staging ${path}: ${error instanceof Error ? error.message : JSON.stringify(error)}`,
+    );
   }
 }
 
-function isOwnerGone(pid) {
+function isOwnerGone(/** @type {number} */ pid) {
   try {
     process.kill(pid, 0);
     return false;
   } catch (error) {
-    return error?.code === "ESRCH";
+    return isErrno(error, "ESRCH");
   }
 }
 
-async function hasPublishedDist(path) {
+async function hasPublishedDist(/** @type {string} */ path) {
   try {
     return (await readdir(path)).length > 0;
   } catch {
@@ -59,7 +67,7 @@ async function hasPublishedDist(path) {
   }
 }
 
-async function reapStrandedStaging(cwd) {
+async function reapStrandedStaging(/** @type {string} */ cwd) {
   // Signal 0 proves only that the owner was gone at probe time. Pid reuse
   // between this probe and removal is inherent to pid-based reaping.
   for (const entry of await readdir(cwd, { withFileTypes: true })) {
@@ -77,38 +85,49 @@ async function reapStrandedStaging(cwd) {
   }
 }
 
-async function compileProject(cwd, stagingDir, compiler, project) {
+async function compileProject(
+  /** @type {string} */ cwd,
+  /** @type {string} */ stagingDir,
+  /** @type {{ command: string, args: string[] }} */ compiler,
+  /** @type {string} */ project,
+) {
   const { stderr, stdout } = await execFile(
     compiler.command,
     [...compiler.args, "-p", project, "--outDir", stagingDir],
     { cwd, maxBuffer: 10 * 1024 * 1024 },
   );
-  if (stdout) {
+  if (stdout !== "") {
     process.stdout.write(stdout);
   }
-  if (stderr) {
+  if (stderr !== "") {
     process.stderr.write(stderr);
   }
 }
 
-async function compileToStaging(cwd, stagingDir, compiler) {
+async function compileToStaging(
+  /** @type {string} */ cwd,
+  /** @type {string} */ stagingDir,
+  /** @type {{ command: string, args: string[] }} */ compiler,
+) {
   try {
     await compileProject(cwd, stagingDir, compiler, "tsconfig.build.json");
     await compileProject(cwd, stagingDir, compiler, "tsconfig.client.json");
     await stampBuild(cwd, stagingDir);
   } catch (error) {
-    if (error?.stdout) {
-      process.stdout.write(error.stdout);
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- exec rejections carry partial output
+    const output = /** @type {{ stdout?: string, stderr?: string }} */ (error);
+    if (output.stdout !== undefined && output.stdout !== "") {
+      process.stdout.write(output.stdout);
     }
-    if (error?.stderr) {
-      process.stderr.write(error.stderr);
+    if (output.stderr !== undefined && output.stderr !== "") {
+      process.stderr.write(output.stderr);
     }
     await discardStaging(stagingDir);
     throw error;
   }
 }
 
-async function stampBuild(cwd, stagingDir) {
+async function stampBuild(/** @type {string} */ cwd, /** @type {string} */ stagingDir) {
   const stamp = "build-info.js";
   const hash = createHash("sha256");
   const files = (await readdir(stagingDir, { recursive: true }))
@@ -120,14 +139,21 @@ async function stampBuild(cwd, stagingDir) {
     const content = await readFile(join(stagingDir, file));
     hash.update(file).update("\0").update(content).update("\0");
   }
-  const { version } = JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
+  /** @type {{ version: string }} */
+  // oxlint-disable-next-line typescript/no-unsafe-assignment
+  const pkg = JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
+  const { version } = pkg;
   await writeFile(
     join(stagingDir, stamp),
     `export const EXTENSION_BUILD = Object.freeze(${JSON.stringify({ version, sha256: hash.digest("hex") })});\n`,
   );
 }
 
-async function tryPublish(stagingDir, distDir, retry) {
+async function tryPublish(
+  /** @type {string} */ stagingDir,
+  /** @type {string} */ distDir,
+  /** @type {number} */ retry,
+) {
   try {
     await rename(stagingDir, distDir);
     return true;
@@ -147,12 +173,12 @@ async function tryPublish(stagingDir, distDir, retry) {
   }
 }
 
-async function publishStaging(stagingDir, distDir) {
+async function publishStaging(/** @type {string} */ stagingDir, /** @type {string} */ distDir) {
   const previousDir = `${stagingDir}.previous`;
   try {
     // Retire dist exactly once, outside the retry loop, so retries never retire a concurrent winner.
-    await rename(distDir, previousDir).catch((error) => {
-      if (error?.code !== "ENOENT") {
+    await rename(distDir, previousDir).catch((/** @type {unknown} */ error) => {
+      if (!isErrno(error, "ENOENT")) {
         throw error;
       }
     });
@@ -166,12 +192,13 @@ async function publishStaging(stagingDir, distDir) {
     await discardStaging(previousDir);
   } catch (error) {
     // ENOENT: nothing was retired. Otherwise a concurrent winner may already own dist.
-    await rename(previousDir, distDir).catch((restoreError) => {
-      if (restoreError?.code !== "ENOENT") {
-        console.warn(
-          `could not restore ${previousDir} to dist: ${restoreError?.message ?? restoreError}`,
-        );
+    await rename(previousDir, distDir).catch((/** @type {unknown} */ restoreError) => {
+      if (isErrno(restoreError, "ENOENT")) {
+        return;
       }
+      const message =
+        restoreError instanceof Error ? restoreError.message : JSON.stringify(restoreError);
+      console.warn(`could not restore ${previousDir} to dist: ${message}`);
     });
     throw error;
   } finally {
@@ -192,7 +219,7 @@ async function main() {
   await publishStaging(stagingDir, join(cwd, "dist"));
 }
 
-main().catch((error) => {
-  console.error(error instanceof Error ? error.message : String(error));
+main().catch((/** @type {unknown} */ error) => {
+  console.error(error instanceof Error ? error.message : JSON.stringify(error));
   process.exitCode = 1;
 });

package/scripts/check-compat.mjs

@@ -13,7 +13,11 @@ if (process.argv.includes("--help") || process.argv.includes("-h")) {
 }
 assert.equal(process.argv.length, 2, "Expected no arguments; use --help");
 await import("./compat-host.mjs");
-const run = (command, args, options = {}) => {
+const run = (
+  /** @type {string} */ command,
+  /** @type {string[]} */ args,
+  /** @type {import("node:child_process").SpawnSyncOptions} */ options = {},
+) => {
   // Outlasts the 1_200_000 ms integration watchdog in scripts/run-tests.mjs.
   const result = spawnSync(command, args, { stdio: "inherit", timeout: 1_500_000, ...options });
   if (result.error) {
@@ -22,18 +26,19 @@ const run = (command, args, options = {}) => {
   assert.equal(
     result.status,
     0,
-    `${command} ${args.join(" ")} failed (${result.status ?? result.signal})`,
+    `${command} ${args.join(" ")} failed (${result.status ?? result.signal ?? "unknown"})`,
   );
-  return result.stdout?.trim();
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- spawnSync stdout shape depends on caller options
+  return /** @type {string | undefined} */ (/** @type {unknown} */ (result.stdout))?.trim();
 };
-const git = (cwd, args) =>
+const git = (/** @type {string} */ cwd, /** @type {string[]} */ args) =>
   run("git", args, { cwd, stdio: ["ignore", "pipe", "inherit"], encoding: "utf8" });
 const root = mkdtempSync(join(tmpdir(), "ps-editor-"));
 const editor = join(root, "source");
 try {
   const supplied = process.env.PI_EDITOR_RECEIPT_TEST_ROOT;
   let expectedRef;
-  if (supplied) {
+  if (supplied !== undefined) {
     const source = resolve(supplied);
     expectedRef = git(source, ["rev-parse", "HEAD"]);
     assert.equal(
@@ -42,7 +47,7 @@ try {
       "Supplied editor source must be clean",
     );
     run("git", ["clone", "--no-hardlinks", "--quiet", source, editor]);
-    git(editor, ["checkout", "--quiet", "--detach", expectedRef]);
+    git(editor, ["checkout", "--quiet", "--detach", expectedRef ?? ""]);
   } else {
     run("git", [
       "clone",
@@ -57,8 +62,8 @@ try {
     ]);
   }
   const ref = git(editor, ["rev-parse", "HEAD"]);
-  assert.match(ref, /^[a-f0-9]{40}$/);
-  if (expectedRef) {
+  assert.match(ref ?? "", /^[a-f0-9]{40}$/);
+  if (expectedRef !== undefined) {
     assert.equal(ref, expectedRef);
   }
   assert.ok(
@@ -74,7 +79,11 @@ try {
   git(editor, ["diff", "--exit-code"]);
   console.log(
     JSON.stringify({
-      nativeEditor: { ref, source: editor, supplied: supplied ? resolve(supplied) : null },
+      nativeEditor: {
+        ref,
+        source: editor,
+        supplied: supplied !== undefined ? resolve(supplied) : null,
+      },
     }),
   );
   const env = { ...process.env, PI_EDITOR_RECEIPT_TEST_ROOT: editor };

package/scripts/compat-host.mjs

@@ -6,33 +6,45 @@ import { findPackageJSON } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-export const hostRoot = realpathSync(
-  dirname(findPackageJSON("@earendil-works/pi-coding-agent", import.meta.url)),
-);
+const hostPackageJson = findPackageJSON("@earendil-works/pi-coding-agent", import.meta.url);
+if (hostPackageJson === undefined) {
+  throw new Error("Could not locate the installed pi-coding-agent package");
+}
+export const hostRoot = realpathSync(dirname(hostPackageJson));
 export const hostIndex = join(hostRoot, "dist/index.js");
+/** @type {{ version: string, bin: { pi: string } }} */
+// oxlint-disable-next-line typescript/no-unsafe-assignment
 const manifest = JSON.parse(readFileSync(join(hostRoot, "package.json"), "utf8"));
 export const hostCli = realpathSync(join(hostRoot, manifest.bin.pi));
-for (const [name, actual] of [
+/** @type {[string, string][]} */
+const expectedHostPaths = [
   ["PI_COMPAT_EXPECTED_PACKAGE_DIR", hostRoot],
   ["PI_HOST_INDEX", hostIndex],
   ["PI_HOST_CLI", hostCli],
-]) {
-  if (process.env[name]) {
+];
+for (const [name, actual] of expectedHostPaths) {
+  const expected = process.env[name];
+  if (expected !== undefined) {
     assert.equal(
-      realpathSync(process.env[name]),
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- assert generic inference already matches
+      realpathSync(expected),
       realpathSync(actual),
       `${name} must select the installed graph`,
     );
   }
 }
-if (process.env.PI_COMPAT_EXPECTED_VERSION) {
-  assert.equal(manifest.version, process.env.PI_COMPAT_EXPECTED_VERSION);
+const expectedVersion = process.env.PI_COMPAT_EXPECTED_VERSION;
+if (expectedVersion !== undefined) {
+  // oxlint-disable-next-line typescript/no-unnecessary-condition -- assert generic inference already matches
+  assert.equal(manifest.version, expectedVersion);
 }
 assert.equal(
+  // oxlint-disable-next-line typescript/no-unnecessary-condition -- assert generic inference already matches
   realpathSync(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))),
   realpathSync(hostIndex),
 );
-const hash = (path) => createHash("sha256").update(readFileSync(path)).digest("hex");
+const hash = (/** @type {string} */ path) =>
+  createHash("sha256").update(readFileSync(path)).digest("hex");
 console.log(
   JSON.stringify({
     host: process.env.PI_COMPAT_HOST ?? "local",

package/scripts/intercom-bridge-credentials.mjs

@@ -13,12 +13,34 @@ import {
 import { resolve, join } from "node:path";
 import { parseArgs } from "node:util";
 
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function errorMessage(error) {
-  return error instanceof Error ? error.message : String(error);
+/**
+ * @param {string | undefined} value
+ * @returns {value is string}
+ */
+function hasValue(value) {
+  return value !== undefined && value !== "";
+}
+
+/** @param {(string | undefined)[]} values */
+function firstValue(values) {
+  for (const value of values) {
+    if (hasValue(value)) {
+      return value;
+    }
+  }
+  return;
+}
+
+function errorMessage(/** @type {unknown} */ error) {
+  return error instanceof Error ? error.message : JSON.stringify(error);
 }
 
 function help() {
@@ -50,19 +72,21 @@ Exit: 0 success, 1 filesystem/OpenSSL failure, 2 invalid arguments.
 Never transfer ca.key or server.key to the remote host.`);
 }
 
-function privatePath(path, directory = false) {
+function privatePath(/** @type {string} */ path, /** @type {boolean} */ directory = false) {
   const st = lstatSync(path);
+  const uid = process.getuid?.();
   if (
+    uid === undefined ||
     st.isSymbolicLink() ||
     !(directory ? st.isDirectory() : st.isFile()) ||
-    st.uid !== process.getuid() ||
-    st.mode & 0o077
+    st.uid !== uid ||
+    (st.mode & 0o077) !== 0
   ) {
     throw new Error(`Expected an owned, private ${directory ? "directory" : "file"}: ${path}`);
   }
 }
 
-function atomicConfig(path, config) {
+function atomicConfig(/** @type {string} */ path, /** @type {unknown} */ config) {
   const temp = `${path}.${randomBytes(8).toString("hex")}.tmp`;
   try {
     writeFileSync(temp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600, flag: "wx" });
@@ -72,19 +96,26 @@ function atomicConfig(path, config) {
   }
 }
 
+/** @param {string[]} args */
 function openssl(...args) {
-  execFileSync(process.env.OPENSSL || "openssl", args, {
+  const opensslBin = process.env.OPENSSL;
+  execFileSync(opensslBin !== undefined && opensslBin !== "" ? opensslBin : "openssl", args, {
     stdio: ["ignore", "pipe", "pipe"],
     timeout: 30000,
   });
 }
 
-function key(path) {
+function key(/** @type {string} */ path) {
   openssl("ecparam", "-name", "prime256v1", "-genkey", "-noout", "-out", path);
   privatePath(path);
 }
 
-function issueCertificate(dir, stem, name, { server = false, days = 7 } = {}) {
+function issueCertificate(
+  /** @type {string} */ dir,
+  /** @type {string} */ stem,
+  /** @type {string} */ name,
+  /** @type {{ server?: boolean, days?: number }} */ { server = false, days = 7 } = {},
+) {
   const keyPath = join(dir, `${stem}.key`);
   const certPath = join(dir, `${stem}.crt`);
   const csrPath = join(dir, `${stem}.csr`);
@@ -129,7 +160,9 @@ function issueCertificate(dir, stem, name, { server = false, days = 7 } = {}) {
   };
 }
 
-function readConfig(path) {
+function readConfig(/** @type {string} */ path) {
+  /** @type {{ ca?: string, clients?: unknown[], cert?: string, key?: string }} */
+  // oxlint-disable-next-line typescript/no-unsafe-assignment
   const config = JSON.parse(readFileSync(path, "utf8"));
   if (!isRecord(config) || !Array.isArray(config.clients) || typeof config.ca !== "string") {
     throw new Error("Invalid clients allowlist.");
@@ -161,22 +194,24 @@ try {
       days: { type: "string" },
     },
   });
-  if (args.values.help) {
+  if (args.values.help === true) {
     help();
     process.exit(0);
   }
-  const [action, dir, name] = args.positionals;
+  const [action = "", dir = "", name] = args.positionals;
+  const cwdArg = args.values.cwd;
+  const daysArg = args.values.days;
   port = args.values.port === undefined ? 9443 : Number(args.values.port);
   const defaultDays = action === "renew-server" ? 365 : 7;
   certificateDays = args.values.days === undefined ? defaultDays : Number(args.values.days);
   if (
     !["init", "issue", "revoke", "renew-server"].includes(action) ||
-    !dir ||
+    dir === "" ||
     args.positionals.length > 3 ||
-    (["issue", "revoke"].includes(action) && !name) ||
-    (action === "renew-server" && (name || args.values.cwd)) ||
-    (name && !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name)) ||
-    (action === "revoke" && (args.values.cwd || args.values.days)) ||
+    (["issue", "revoke"].includes(action) && !hasValue(name)) ||
+    (action === "renew-server" && (hasValue(name) || hasValue(cwdArg))) ||
+    (hasValue(name) && !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name)) ||
+    (action === "revoke" && (hasValue(cwdArg) || hasValue(daysArg))) ||
     (action !== "init" && args.values.port !== undefined) ||
     !Number.isInteger(port) ||
     port < 0 ||
@@ -192,12 +227,15 @@ try {
   process.exit(2);
 }
 
-let lock;
+/** @type {string | undefined} */ let lock;
 try {
   process.umask(0o077);
   const [action, rawDir, suppliedName] = args.positionals;
+  if (rawDir === undefined) {
+    throw new Error("A directory argument is required.");
+  }
   const dir = resolve(rawDir);
-  const name = suppliedName || "grok-bot";
+  const name = hasValue(suppliedName) ? suppliedName : "grok-bot";
   const configPath = join(dir, "config.json");
   let config;
   if (action === "init") {
@@ -253,10 +291,12 @@ try {
     config = readConfig(configPath);
   }
   if (action === "revoke") {
-    if (!config.clients.some((client) => client.name === name)) {
+    if (!config.clients.some((/** @type {{ name: string }} */ client) => client.name === name)) {
       throw new Error(`No authorized client named ${name}.`);
     }
-    config.clients = config.clients.filter((client) => client.name !== name);
+    config.clients = config.clients.filter(
+      (/** @type {{ name: string }} */ client) => client.name !== name,
+    );
     atomicConfig(configPath, config);
     console.log(
       JSON.stringify({ revoked: name, config: configPath, next: "Send SIGHUP to the helper PID." }),
@@ -284,13 +324,17 @@ try {
     const credential = issueCertificate(dir, `${name}-${randomBytes(8).toString("hex")}`, name, {
       days: certificateDays,
     });
-    const previous = config.clients.find((client) => client.name === name);
-    config.clients = config.clients.filter((client) => client.name !== name);
+    const previous = config.clients.find(
+      (/** @type {{ name: string }} */ client) => client.name === name,
+    );
+    config.clients = config.clients.filter(
+      (/** @type {{ name: string }} */ client) => client.name !== name,
+    );
     config.clients.push({
       ...previous,
       fingerprint256: credential.fingerprint256,
       name,
-      cwd: resolve(args.values.cwd || previous?.cwd || process.cwd()),
+      cwd: resolve(firstValue([args.values.cwd, previous?.cwd]) ?? process.cwd()),
     });
     atomicConfig(configPath, config);
     console.log(
@@ -307,7 +351,7 @@ try {
   console.error(errorMessage(error));
   process.exitCode = 1;
 } finally {
-  if (lock) {
+  if (lock !== undefined) {
     rmSync(join(lock, "owner"), { force: true });
     rmdirSync(lock);
   }