🚑 report failing url instead of crashing on download errors

[taras]

Motivation

The frontside.com deploy workflow fails at the Staticalize step with:

error: Uncaught (in promise) TypeError: Invalid gzip header
    let content = yield* until(response.text());
    at ...
    at file:///tmp/deno-compile-staticalize-linux/staticalize.ts:127:51

The message gives no indication of which URL was being downloaded, so it is impossible to tell which page on the site is misbehaving.

The download operation only routed non-2xx responses into the graceful, collected error path. Any thrown exception — a gzip/transport decode error, an HTML parse error, or a filesystem write error — escaped uncaught, killed the whole run, and printed a raw stack trace with no source/referrer context, even though both are in scope at the throw site.

Approach

• downloader.ts: wrap the download body in try/catch. On a thrown error (re-throwing if the run was aborted), return { ok: false, url, referrer, error } so it flows into the existing collected-error mechanism instead of crashing. The run keeps going, every page/asset that succeeds is still written, and it exits non-zero at the end. The non-2xx branch also now carries an error message for consistency.
• progress.ts / main.ts: thread the optional error through DownloadError and print it in the failed-downloads summary.
• staticalize.ts: attach the sitemap URL to read/parse failures of /sitemap.xml.
• test/staticalize.test.ts: new case serving a page that advertises Content-Encoding: gzip with a non-gzip body — asserts the run does not crash, healthy pages are still written, and the bad page is skipped. Verified this test reproduces the exact Invalid gzip header crash without the fix.

Example output now:

1 failed downloads:

  http://127.0.0.1:8005/bad
    referrer: http://127.0.0.1:8005/
    error: TypeError: Invalid gzip header

Bumps deno.json version 0.2.2 → 0.2.6 (stale field; latest release is v0.2.5) for the follow-up v0.2.6 release that frontside.com's deploy workflow will consume.

[taras]

Pushed 721287a addressing all review threads (Error + cause model, hierarchy print, dropped the abort guard).

Ran the recompiled binary against the live site (--site=http://localhost:8005) — it did exactly its job and pinpointed the deploy failure: 259 pages OK, 349 failures, every one TypeError: Invalid gzip header, all confined to the proxied doc sub-sites /effection/*, /interactors/*, /graphgen/*. So the fix on this side is working; the remaining gzip issue is on frontside.com's proxying of those sub-paths.

[cowboyd]

Sounds good, although should this be an option? Basically whether we fail fast or not?

[taras]

Good call — added in 73b8d04. There's now a --strict flag (threaded through useStaticalizer, so it's a library option too). Default stays keep-going (download everything, report all failures at the end, exit non-zero); --strict aborts on the first failure and prints that error's cause hierarchy.

Also rebased the branch onto main to pick up the new Verify CI workflow.

[taras]

Addressed the review in d82bf18 — I'd over-engineered the fail-fast path. Rundown:

• firstError capture / the skip / the iterator throw — all removed. --strict now just re-throws from the download (fail() throws when strict) and lets structured concurrency abort the run. No bookkeeping.
• Comments — dropped the code-narrating ones; the catch comment is trimmed to just the surprise (these underlying errors don't name the url).
• strict? on the types — removed the JSDoc; the description lives on the parser (config.ts).
• README vs --help — regenerated the block to match the actual output verbatim.
• main.ts comment / try-catch — gone; main.ts is back to its prior shape plus threading strict through.

One thing worth your call on the UX. Throwing from inside the download task can't be caught downstream to pretty-print it: the task buffer's scope.spawn makes each download a child of the resource scope, so a throw aborts that scope out of band (bypassing both the monitor's catch and the drain) — it lands on effection's default uncaught-error handler. So:

• library (useStaticalizer): strict surfaces as a normal rejected operation — clean, caller formats it.
• CLI: strict is a loud crash with effection's stack dump + Caused by:, rather than the collected-mode hierarchy. Exits 1 either way.

Making the CLI print the nice hierarchy in strict mode would mean reintroducing a result-based mechanism (roughly the thing you just told me to delete), so I left it as the clean crash. Happy to add the formatted variant if you'd rather have consistent output — your call.