fix(cli): make the API tolerate null options and context arguments

[josephfarina]

Summary

Guards every exported API function against null in its optional arguments —
the largest robustness gap the chaos test found. Stacked on #4637;
review/merge that first.

The bug

Every API function used options = {} (and, on two-argument commands,
{cwd = …} = {}) as a default parameter. JavaScript defaults only fire for
undefined — passing an explicit null bypassed them and threw a raw
TypeError: Cannot read properties of null (reading 'cwd') (with no error code
and no AstryxError) instead of a graceful error. This affected the whole
public API surface: 17 functions on the options argument, plus the trailing
context argument on init, upgrade, and themeBuild.

These are all shielded behind the CLI (Commander always passes a real object,
so no end user ever hit them) — but the programmatic API contract is "never a
raw crash for any input," which scripts and integrations rely on.

The fix

• Coalesce the options argument (options = options ?? {}) as the first
  statement in every affected function.
• Do the same for the trailing context argument on init, upgrade, and
  themeBuild (an earlier pass fixed only the options slot and left the
  context slot crashing).
• Add a regression suite that calls every exported command with null in both
  the options and context positions and asserts none throw a bare TypeError.
  It also fails if a new export ships without a case, so this can't silently
  come back. The suite runs from a throwaway temp directory so it never touches
  the repo.

Stack

1. fix(cli): confine user paths, close DoS vectors, and repair broken paths #4637 — security + DoS + broken paths
2. fix(cli): make the API tolerate null options and context arguments #4638 (this PR) — API robustness against null arguments
3. fix(cli): flag collision, stale bundled themes, and codemod edge cases #4639 — flag collision, stale bundled themes, codemod edge cases

Test plan

• New regression suite — 21 cases, all green
• init / upgrade / theme suites green (no regression from the
  context-argument change)
• eslint clean on all touched files

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview	Aug 1, 2026 6:55pm

[josephfarina]

Closing — this change is unnecessary.

The guards defended against callers passing an explicit null for an optional
options/context argument. But a TypeScript consumer can't do that: the
generated types are options?: {...} (i.e. {...} | undefined), so null is a
compile error (TS2345: Argument of type 'null' is not assignable). Verified by
type-checking a consumer that passes null against the emitted .d.mts — every
null call errors, undefined/omitted/real-object calls pass.

The plain options = {} parameter default (already in place) is the idiomatic
JS way to make the argument optional and is sufficient — it handles the only
input a real or typed caller can produce (omitted → undefined). The extra
options = options ?? {} layer only converts a TypeError into an
AstryxError for a contract violation the type system already prevents; the
"crashes" came from a fuzzer poking null into every argument, not a real
caller. Not worth touching ~20 functions for.

The other chaos-test fixes continue in #4639, now rebased directly onto #4637.