@chrismessina/raycast-downloader 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Messina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# @chrismessina/raycast-downloader
+
+Downloads for Raycast extensions that survive the window closing.
+
+## The problem
+
+Raycast unloads a command when the user presses Escape or pops back to root search. From the [lifecycle docs](https://developers.raycast.com/information/lifecycle):
+
+> Any async work you kick off should not be relied on to keep running.
+
+An in-flight stream to disk is torn down mid-write, leaving a truncated file. `no-view` mode does not help — it runs until its promise resolves, and the promise *is* the thing doing the downloading.
+
+So the transfer runs in a **detached child process** that outlives the command, reporting through a status file on disk rather than through memory.
+
+```ts
+import { startDownload, watchStatus } from "@chrismessina/raycast-downloader";
+
+const ticket = await startDownload({
+  url: signedUrl,
+  outputPath: "/Users/me/Downloads/recording.mp4",
+  expectedBytes: 383713905,
+});
+
+// The user can dismiss Raycast here. The download continues.
+
+watchStatus(ticket.id, {
+  onChange: (s) => console.log(s.bytesDownloaded, "/", s.totalBytes),
+  onSettled: (s) => console.log(s.state),
+});
+```
+
+## Scope of the guarantee
+
+**Survives:** Raycast dismissal, the command being unloaded, the parent process exiting.
+
+**Does not survive** (without user action): machine sleep, power loss, unattended network drops. Partial files are always retained, so an interrupted transfer resumes via HTTP Range instead of starting over.
+
+This is stated narrowly on purpose. Detached spawn solves parent-process-exit — the problem Raycast creates. It is not a download supervisor.
+
+## Platforms
+
+macOS and Windows. `curl` is used for the transfer and ships with both (Windows 10+ includes it at `System32\curl.exe`).
+
+The supervision around the transfer differs, because the two platforms have genuinely different process models:
+
+| | macOS / POSIX | Windows |
+|---|---|---|
+| Detach | `detached: true` + `unref()` | `unref()` only — `detached` there means "new console window" |
+| Cancel | `process.kill(-pid)` on the process group | `taskkill /PID <pid> /T` walks the tree |
+| Identity | `ps -o lstart` | PowerShell `Get-Process().StartTime`, falling back to `wmic` on older builds |
+| Who records the outcome | the runner's SIGTERM handler | `killDownload`, since nothing catchable is delivered |
+
+### When identity can't be established
+
+Some environments can't resolve a process's start time at all. Two different questions then get two different answers, deliberately:
+
+**"Is this download still running?"** → falls back to the runner's heartbeat. A process that hasn't written a status in 30 seconds (60 missed beats) is treated as dead. Biasing unconditionally toward "alive" would be worse than it sounds: a dead runner would never be reconciled, its partial never reaped, and a watcher would poll a stuck status forever.
+
+**"Should I signal this pid?"** → refuses. Guessing wrong about liveness costs a mislabelled status; guessing wrong about identity kills an unrelated process tree. `killDownload` returns `false` and records a terminal status rather than signalling on an unproven pid.
+
+`canVerifyProcessIdentity()` exposes which regime you're in.
+
+## Two layers
+
+**Layer A — transport** (`status`, `detach`, `curl`): for extensions downloading from a URL.
+
+**Layer B — everything else** (`paths`, `errors`, `progress`, `history`): useful to any extension that puts a file on disk, however it got the bytes.
+
+The split is deliberate. A tool that owns its own transport — a vendor CLI, say, which never exposes a URL, picks its own output path, and emits no progress — can consume Layer B without being forced through a URL-shaped API that does not fit it.
+
+## Design notes
+
+Each of these exists because the obvious implementation is wrong in a way that only shows up in production.
+
+**Process identity is `(pid, startTime)`, never a bare pid.** macOS `kern.maxproc` is 16000, so pids get recycled. A liveness check of `kill(pid, 0)` alone answers "does *some* process have this pid" — and cancelling on that basis can `kill(-pid)` an unrelated process group.
+
+**Credentials never touch argv.** `ps` is world-readable. Measured: a URL passed as a curl argument is visible to any process on the machine; written to a `0600` config file and passed by path as `curl -K <file>`, it is not. The config is unlinked as soon as curl's first output byte proves it has been read. Signed URLs are bearer credentials, so the config-file channel is a requirement rather than a preference.
+
+**Timeouts are throughput-based, not wall-clock.** `--max-time` counts machine sleep against the budget, so a laptop closed for ten minutes guarantees a spurious failure on a healthy transfer. `--speed-limit`/`--speed-time` measure actual throughput and are sleep-tolerant.
+
+**`.part` file plus atomic rename.** Cancelling a naive download leaves a truncated file that looks exactly like a successful one. Bytes land in `<outputPath>.part` and are renamed only after the size is verified.
+
+**Status writes are atomic and polled, not watched.** `writeFileSync(tmp)` + `renameSync` means a reader never sees half-written JSON — but the rename replaces the inode, so an `fs.watch` bound to the original file silently stops firing. Hence polling.
+
+**Liveness and throughput are separate signals.** `heartbeatAt` advances while the process lives; `lastByteAt` advances only when bytes move. Conflated, a hung-but-alive transfer reads as healthy forever.
+
+**`finalizing` is a real state.** The runner writes `finalizing` → renames → writes `completed`. A crash between the rename and the completion write leaves a correct file on disk; reconciliation recognizes that rather than reporting a failure and prompting a needless re-download of hundreds of megabytes.
+
+**curl's default meter, not `--progress-bar`.** The progress-bar mode emits only a percentage. The default meter carries real bytes, total, speed and ETA — verified against captured output, not assumed.
+
+## Known limitations
+
+Stated plainly so a consumer doesn't discover them the hard way.
+
+**Leases are per-instance, not distributed.** `acquireLease` serializes adoption well enough for two windows of the same extension, but it is a read-then-write on a file, not a true compare-and-swap. Two processes racing within the same millisecond can both believe they won. The realistic case — a user opening a second window seconds later — is covered.
+
+**Reusing an `id` while its download is still running starts a competing writer.** Despite "reuse it to resume", there is no active-status check. Reuse an id only after the previous transfer reached a terminal state.
+
+**Schema evolution has no in-flight migration.** Readers reject a status whose `schema` they don't recognize. If a future version bumps it while a download from the old version is mid-flight, that transfer becomes invisible to watch/cancel/prune — it still completes, but nothing tracks it.
+
+**Bundling.** `startDownload` resolves `runner.js` from `__dirname`. If a consumer inlines `detach.js` into a single bundle without copying `dist/runner.js` alongside, it throws "runner not found" — loudly, not silently. Keep the package external, or copy the runner into the bundle directory.
+
+**`npm test` runs against the built `dist`** — the script builds first, so it is never stale, but invoking `node --test` directly is. The integration suite hits the real network; set `SKIP_INTEGRATION=1` to skip it.
+
+## API
+
+```
+paths     expandHome · isContained · resolveDirectory · uniquePath · sanitizeFilename
+errors    DownloadError · DownloadErrorCode · classifyHttpStatus · isDownloadError
+progress  formatBytes · formatSpeed · formatEta · formatProgressLine · createThrottle
+history   createDownloadHistory
+status    writeStatus · readStatus · listStatuses · watchStatus · pruneStatuses
+          isAlive · isStalled · isTerminal · acquireLease · releaseLease
+detach    startDownload · killDownload · reconcile · runnerPath
+curl      buildCurlConfig · parseCurlMeter · parseWriteOut · classifyCurlFailure
+```
+
+Import from the root or from a subpath (`@chrismessina/raycast-downloader/paths`).
+
+## Notes for consumers
+
+**Never put a signed URL in `meta`.** It is persisted to the status file. Store an identifier you can re-resolve from instead.
+
+**Retry policy is yours.** Consumers differ too much to share one: `DownloadError.retryable` gives you the signal, the loop stays in your code.
+
+**`uniquePath` numbering starts where you say.** Existing extensions differ (`(1)` vs `(2)`); `startAt` preserves that, because unifying it silently renames files users already have.
+
+## Development
+
+```bash
+npm run build      # tsc
+npm test           # node --test, includes live network integration tests
+SKIP_INTEGRATION=1 npm test   # unit tests only
+```
+
+Zero runtime dependencies. `@raycast/api` is a peer, and is loaded lazily so the runner and the tests work outside a Raycast host.
+
+## License
+
+MIT

package/dist/curl.d.ts

@@ -0,0 +1,106 @@
+/**
+ * curl transport: config construction, progress parsing, exit classification.
+ *
+ * Why curl rather than Node's own `fetch`: the transfer has to outlive the
+ * Raycast command that started it. A detached Node process could do it, but
+ * curl already handles Range resume, redirects, retries and connection timeouts,
+ * and it is present on every macOS install.
+ *
+ * Two decisions here are load-bearing, both verified empirically:
+ *
+ *  1. The URL is passed in a 0600 CONFIG FILE, never on the command line.
+ *     Signed URLs are bearer credentials; argv is world-readable via `ps`.
+ *     Measured: with the URL as an argument it is visible in `ps`; via `-K` it
+ *     is not.
+ *  2. Timeouts are THROUGHPUT-based (`--speed-limit`/`--speed-time`), not
+ *     wall-clock (`--max-time`). `--max-time` counts machine sleep against the
+ *     budget, so a laptop closed for ten minutes guarantees a spurious failure
+ *     on an otherwise healthy transfer.
+ */
+import { DownloadError, type SignalName } from "./errors";
+export declare function hasCurl(): boolean;
+/** Bytes/sec below which a transfer is considered dead, sustained for `stallSeconds`. */
+export declare const DEFAULT_SPEED_LIMIT_BYTES = 1024;
+export declare const DEFAULT_STALL_SECONDS = 120;
+export interface CurlConfigOptions {
+    url: string;
+    /** Destination. Callers should pass the `.part` path, not the final one. */
+    outputPath: string;
+    headers?: Record<string, string>;
+    followRedirects?: boolean;
+    /** Continue a partial transfer via HTTP Range. */
+    resume?: boolean;
+    /**
+     * Stall THRESHOLD, not a rate limit: if throughput stays below this for
+     * `stallSeconds`, curl aborts. Lowering it makes stall detection more
+     * forgiving; it does not slow the transfer down.
+     */
+    speedLimitBytes?: number;
+    stallSeconds?: number;
+    connectTimeoutSeconds?: number;
+    /**
+     * Cap the transfer rate in bytes/sec (curl `--limit-rate`). Genuinely slows
+     * the download — useful for tests and for not saturating a connection.
+     */
+    limitRateBytes?: number;
+    /**
+     * Absolute wall-clock cap. Deliberately optional and unset by default —
+     * see the note above about sleep.
+     */
+    maxTimeSeconds?: number;
+}
+/**
+ * Build the contents of a curl config file (`curl -K <file>`).
+ *
+ * Everything sensitive lives in this file, which the caller must create 0600 and
+ * delete once curl has started.
+ */
+export declare function buildCurlConfig(options: CurlConfigOptions): string;
+export interface CurlProgress {
+    bytesDownloaded: number;
+    totalBytes?: number;
+    speedBytesPerSec?: number;
+    etaSeconds?: number;
+}
+/**
+ * Parse curl's default progress meter.
+ *
+ * Deliberately NOT `--progress-bar`: that mode emits only a percentage, which is
+ * why the existing Fetch extension's speed and ETA fields are hardcoded to zero
+ * and its speed UI has never rendered. The default meter carries real numbers:
+ *
+ *   % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+ *                                  Dload  Upload   Total   Spent    Left  Speed
+ *  13  365M   13 48.7M    0     0  8058k      0  0:00:46  0:00:06  0:00:40 8501k
+ *
+ * Returns the most recent complete sample, or null if none is present yet.
+ */
+export declare function parseCurlMeter(buffer: string): CurlProgress | null;
+/** Parse curl's abbreviated sizes: `1234`, `48.7M`, `365M`, `8058k`. */
+export declare function parseCurlSize(field: string | undefined): number | undefined;
+/** Parse `H:MM:SS`. curl prints `--:--:--` when it has no estimate. */
+export declare function parseCurlDuration(field: string | undefined): number | undefined;
+export interface CurlWriteOut {
+    sizeDownload?: number;
+    speedDownload?: number;
+    httpCode?: number;
+}
+/** Parse the trailing `write-out` block (size, speed, http_code — one per line). */
+export declare function parseWriteOut(stdout: string): CurlWriteOut;
+export interface ClassifyCurlInput {
+    exitCode: number | null;
+    signal?: SignalName | null;
+    httpCode?: number;
+    stderrTail?: string;
+    /** True when the local process deliberately terminated curl. */
+    cancelled?: boolean;
+}
+/**
+ * Turn a finished curl invocation into a typed error.
+ *
+ * HTTP status is consulted before the exit code: curl exits 22 for every 4xx/5xx
+ * under `fail-with-body`, and "403 Forbidden" is far more actionable than
+ * "curl exited 22".
+ */
+export declare function classifyCurlFailure(input: ClassifyCurlInput): DownloadError;
+//# sourceMappingURL=curl.d.ts.map

package/dist/curl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"curl.d.ts","sourceRoot":"","sources":["../src/curl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,aAAa,EAA0B,KAAK,UAAU,EAAsB,MAAM,UAAU,CAAC;AAetG,wBAAgB,OAAO,IAAI,OAAO,CAWjC;AAED,yFAAyF;AACzF,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAC9C,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kDAAkD;IAClD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CA+ClE;AAuBD,MAAM,WAAW,YAAY;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA0BlE;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAW3E;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAQ/E;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAU1D;AAwBD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,iBAAiB,GAAG,aAAa,CAwB3E"}

package/dist/curl.js

@@ -0,0 +1,264 @@
+"use strict";
+/**
+ * curl transport: config construction, progress parsing, exit classification.
+ *
+ * Why curl rather than Node's own `fetch`: the transfer has to outlive the
+ * Raycast command that started it. A detached Node process could do it, but
+ * curl already handles Range resume, redirects, retries and connection timeouts,
+ * and it is present on every macOS install.
+ *
+ * Two decisions here are load-bearing, both verified empirically:
+ *
+ *  1. The URL is passed in a 0600 CONFIG FILE, never on the command line.
+ *     Signed URLs are bearer credentials; argv is world-readable via `ps`.
+ *     Measured: with the URL as an argument it is visible in `ps`; via `-K` it
+ *     is not.
+ *  2. Timeouts are THROUGHPUT-based (`--speed-limit`/`--speed-time`), not
+ *     wall-clock (`--max-time`). `--max-time` counts machine sleep against the
+ *     budget, so a laptop closed for ten minutes guarantees a spurious failure
+ *     on an otherwise healthy transfer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STALL_SECONDS = exports.DEFAULT_SPEED_LIMIT_BYTES = void 0;
+exports.hasCurl = hasCurl;
+exports.buildCurlConfig = buildCurlConfig;
+exports.parseCurlMeter = parseCurlMeter;
+exports.parseCurlSize = parseCurlSize;
+exports.parseCurlDuration = parseCurlDuration;
+exports.parseWriteOut = parseWriteOut;
+exports.classifyCurlFailure = classifyCurlFailure;
+const errors_1 = require("./errors");
+/**
+ * Is `curl` available on this system?
+ *
+ * Called before spawning so a missing binary is reported as a prerequisite the
+ * user can act on, rather than as a generic transport failure surfacing minutes
+ * after `startDownload` already reported success.
+ *
+ * Present by default on macOS and on Windows 10+ (`System32\curl.exe`), so this
+ * is a guard against unusual environments rather than a common path. Cached —
+ * the answer cannot change within a process's lifetime in any way that matters.
+ */
+let curlAvailable;
+function hasCurl() {
+    if (curlAvailable !== undefined)
+        return curlAvailable;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { execFileSync } = require("node:child_process");
+        execFileSync("curl", ["--version"], { stdio: "ignore", timeout: 5000 });
+        curlAvailable = true;
+    }
+    catch {
+        curlAvailable = false;
+    }
+    return curlAvailable;
+}
+/** Bytes/sec below which a transfer is considered dead, sustained for `stallSeconds`. */
+exports.DEFAULT_SPEED_LIMIT_BYTES = 1024;
+exports.DEFAULT_STALL_SECONDS = 120;
+/**
+ * Build the contents of a curl config file (`curl -K <file>`).
+ *
+ * Everything sensitive lives in this file, which the caller must create 0600 and
+ * delete once curl has started.
+ */
+function buildCurlConfig(options) {
+    const { url, outputPath, headers = {}, followRedirects = true, resume = false, speedLimitBytes = exports.DEFAULT_SPEED_LIMIT_BYTES, stallSeconds = exports.DEFAULT_STALL_SECONDS, connectTimeoutSeconds = 30, limitRateBytes, maxTimeSeconds, } = options;
+    const lines = [
+        `url = "${escapeConfigValue(url)}"`,
+        `output = "${escapeConfigValue(outputPath)}"`,
+        // `fail` (not `fail-with-body`): on a 4xx/5xx, curl must write NOTHING to
+        // the output file.
+        //
+        // With `fail-with-body`, an error response body lands in the `.part` file —
+        // measured: a 404 wrote 21 bytes of `{"error":"Not found"}`. Because the
+        // partial is deliberately retained for resume, the next attempt's
+        // `continue-at = -` would start AFTER those bytes, splicing an error
+        // document into the middle of the media. The file would then pass a
+        // size check and be published as complete. Silent corruption is far worse
+        // than losing an error body we never surface to the user anyway.
+        "fail",
+        `connect-timeout = ${connectTimeoutSeconds}`,
+        // Throughput-based stall detection: survives sleep, catches a dead socket.
+        `speed-limit = ${speedLimitBytes}`,
+        `speed-time = ${stallSeconds}`,
+        // Authoritative final numbers, parsed from stdout on exit.
+        'write-out = "\\n%{size_download}\\n%{speed_download}\\n%{http_code}\\n"',
+    ];
+    if (followRedirects)
+        lines.push("location");
+    // `-C -` asks curl to work out the offset from the existing file.
+    if (resume)
+        lines.push("continue-at = -");
+    if (limitRateBytes !== undefined)
+        lines.push(`limit-rate = ${limitRateBytes}`);
+    if (maxTimeSeconds !== undefined)
+        lines.push(`max-time = ${maxTimeSeconds}`);
+    for (const [name, value] of Object.entries(headers)) {
+        lines.push(`header = "${escapeConfigValue(`${name}: ${value}`)}"`);
+    }
+    return lines.join("\n") + "\n";
+}
+/**
+ * Escape a value for curl's config quoting.
+ *
+ * Escaping quotes and backslashes is not sufficient on its own: curl's config
+ * format is line-oriented, so a raw newline inside a value ends the line and
+ * whatever follows is parsed as a fresh directive. Measured behavior is that
+ * curl rejects the resulting malformed URL rather than honoring the smuggled
+ * directive — but that is curl's parser saving us, not our own correctness.
+ *
+ * So control characters are rejected outright rather than escaped. A URL or
+ * header value containing a newline is malformed anyway; refusing it makes
+ * config injection structurally impossible instead of contingent on curl.
+ */
+function escapeConfigValue(value) {
+    // eslint-disable-next-line no-control-regex
+    if (/[\x00-\x1f\x7f]/.test(value)) {
+        throw new errors_1.DownloadError("validation", "Refusing a value containing control characters.");
+    }
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+/**
+ * Parse curl's default progress meter.
+ *
+ * Deliberately NOT `--progress-bar`: that mode emits only a percentage, which is
+ * why the existing Fetch extension's speed and ETA fields are hardcoded to zero
+ * and its speed UI has never rendered. The default meter carries real numbers:
+ *
+ *   % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+ *                                  Dload  Upload   Total   Spent    Left  Speed
+ *  13  365M   13 48.7M    0     0  8058k      0  0:00:46  0:00:06  0:00:40 8501k
+ *
+ * Returns the most recent complete sample, or null if none is present yet.
+ */
+function parseCurlMeter(buffer) {
+    // Meter updates are separated by \r; take complete lines only.
+    const lines = buffer.split(/[\r\n]+/).filter((line) => line.trim().length > 0);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const fields = lines[i].trim().split(/\s+/);
+        // 12 columns; the first is a percentage, so require a leading integer.
+        if (fields.length < 12)
+            continue;
+        if (!/^\d+$/.test(fields[0]))
+            continue;
+        const totalBytes = parseCurlSize(fields[1]);
+        const bytesDownloaded = parseCurlSize(fields[3]);
+        if (bytesDownloaded === undefined)
+            continue;
+        const speedBytesPerSec = parseCurlSize(fields[6]);
+        const etaSeconds = parseCurlDuration(fields[10]);
+        return {
+            bytesDownloaded,
+            totalBytes: totalBytes && totalBytes > 0 ? totalBytes : undefined,
+            speedBytesPerSec,
+            etaSeconds,
+        };
+    }
+    return null;
+}
+/** Parse curl's abbreviated sizes: `1234`, `48.7M`, `365M`, `8058k`. */
+function parseCurlSize(field) {
+    if (!field)
+        return undefined;
+    const match = /^(\d+(?:\.\d+)?)([kKmMgGtT])?$/.exec(field.trim());
+    if (!match)
+        return undefined;
+    const value = parseFloat(match[1]);
+    if (!Number.isFinite(value))
+        return undefined;
+    const multipliers = { k: 1024, m: 1024 ** 2, g: 1024 ** 3, t: 1024 ** 4 };
+    const suffix = match[2]?.toLowerCase();
+    return suffix ? Math.round(value * multipliers[suffix]) : value;
+}
+/** Parse `H:MM:SS`. curl prints `--:--:--` when it has no estimate. */
+function parseCurlDuration(field) {
+    if (!field || field.includes("-"))
+        return undefined;
+    const parts = field.trim().split(":");
+    if (parts.length !== 3)
+        return undefined;
+    const [h, m, s] = parts.map((p) => parseInt(p, 10));
+    if ([h, m, s].some((n) => Number.isNaN(n)))
+        return undefined;
+    return h * 3600 + m * 60 + s;
+}
+/** Parse the trailing `write-out` block (size, speed, http_code — one per line). */
+function parseWriteOut(stdout) {
+    const lines = stdout.trim().split("\n").filter(Boolean);
+    if (lines.length < 3)
+        return {};
+    const [size, speed, code] = lines.slice(-3).map((line) => Number(line.trim()));
+    return {
+        sizeDownload: Number.isFinite(size) ? size : undefined,
+        speedDownload: Number.isFinite(speed) ? speed : undefined,
+        httpCode: Number.isFinite(code) ? code : undefined,
+    };
+}
+/**
+ * curl exit codes worth distinguishing.
+ * https://curl.se/libcurl/c/libcurl-errors.html
+ */
+const EXIT_CODES = {
+    6: { code: "dns", message: "Could not resolve host." },
+    7: { code: "network", message: "Failed to connect to the server." },
+    18: { code: "network", message: "Transfer ended early." },
+    22: { code: "http_client", message: "The server returned an error." },
+    23: { code: "disk_full", message: "Could not write the file — the disk may be full." },
+    26: { code: "permission", message: "Could not read from the local file." },
+    28: { code: "timeout", message: "The transfer timed out." },
+    33: { code: "network", message: "The server does not support resuming; restart the download." },
+    35: { code: "tls", message: "Could not establish a secure connection." },
+    36: { code: "integrity", message: "Could not resume — the partial file is unusable." },
+    47: { code: "network", message: "Too many redirects." },
+    52: { code: "network", message: "The server returned nothing." },
+    55: { code: "network", message: "Failed to send data to the server." },
+    56: { code: "network", message: "Connection lost during transfer." },
+    63: { code: "http_client", message: "The response exceeded the maximum allowed size." },
+};
+/**
+ * Turn a finished curl invocation into a typed error.
+ *
+ * HTTP status is consulted before the exit code: curl exits 22 for every 4xx/5xx
+ * under `fail-with-body`, and "403 Forbidden" is far more actionable than
+ * "curl exited 22".
+ */
+function classifyCurlFailure(input) {
+    const { exitCode, signal, httpCode, stderrTail, cancelled } = input;
+    if (cancelled || signal === "SIGTERM" || signal === "SIGINT") {
+        return new errors_1.DownloadError("cancelled", "Download cancelled.", { exitCode, signal });
+    }
+    if (httpCode !== undefined && httpCode >= 400) {
+        const code = (0, errors_1.classifyHttpStatus)(httpCode);
+        return new errors_1.DownloadError(code, httpErrorMessage(httpCode), { httpStatus: httpCode, exitCode, signal });
+    }
+    if (exitCode !== null && EXIT_CODES[exitCode]) {
+        const { code, message } = EXIT_CODES[exitCode];
+        return new errors_1.DownloadError(code, message, { exitCode, signal, httpStatus: httpCode });
+    }
+    // Last resort: curl's own words are more useful than a bare number.
+    const detail = stderrTail?.trim().split("\n").pop()?.trim();
+    return new errors_1.DownloadError("unknown", detail ? `Download failed: ${detail}` : `Download failed (curl exit ${exitCode ?? "unknown"}).`, { exitCode, signal, httpStatus: httpCode });
+}
+function httpErrorMessage(status) {
+    switch (status) {
+        case 401:
+            return "Not authorized — the credentials were rejected.";
+        case 403:
+            return "Access denied. The link may have expired, or you may not have permission to download this.";
+        case 404:
+            return "The file was not found on the server.";
+        case 410:
+            return "The download link has expired.";
+        case 416:
+            return "Could not resume from the existing partial file.";
+        case 429:
+            return "Rate limited by the server. Try again shortly.";
+        default:
+            return status >= 500
+                ? `The server is temporarily unavailable (HTTP ${status}).`
+                : `The server rejected the request (HTTP ${status}).`;
+    }
+}
+//# sourceMappingURL=curl.js.map

package/dist/curl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"curl.js","sourceRoot":"","sources":["../src/curl.ts"],"names":[],"mappings":"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"}