Files
hyperframes/packages/cli/src/utils/download.ts
T
James RussoandClaude Opus 5.5 943b6512b4 feat(cli): add hyperframes/api entry with transcribe and removeBackground (#5453)
* feat(cli): add hyperframes/api entry with transcribe and removeBackground

HyperFrames Desktop runs the CLI as a child process, relaunching Electron
with ELECTRON_RUN_AS_NODE=1. A programmatic entry lets it import plain
functions and run them in a utilityProcess instead, so the RunAsNode fuse
can be turned off.

packages/cli/src/api.ts exports transcribe() and removeBackground(): typed
options in, typed result out, progress through callbacks, failures thrown
as TranscribeError / RemoveBackgroundError with a code and the original
error as cause. Neither prints, reads argv or exits.

The transcribe and remove-background commands now keep only flag
handling, printing and exit codes, and call these functions. Their
output, JSON and exit codes are unchanged.

The package gains an exports map with "./api" (built dist plus d.ts) and
"./package.json", generated from package-subpaths.json like the sibling
packages.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): trim api.ts comments under the package's comment share

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): trim trailing dots without a quadratic regex

CodeQL flags the trailing-dots regex on the Parakeet error now that it sits
behind a library entry. Same result, linear time.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): make the transcribe API's signal stop every stage

Review follow-ups on the api entry:

- parakeet-mlx now runs as an async child that the caller's signal can
  kill. Its failures keep the synchronous run's message, status and stderr.
- A pre-aborted signal throws before any setup. Whisper checks the signal
  before each setup stage, and the model download gets it.
- onEngine reports the model whisper runs (small for Spanish, not small.en).
  The resolver moved to whisper/modelForLanguage.ts so both share it.
- api/transcribe.ts imports everything at module scope. The command test
  hoists its whisper mock, since that module now loads during imports.
- whisper's internal TranscribeOptions/TranscribeResult types are renamed
  WhisperOptions/RunnerResult, so the API's public names are unique.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): let an AbortSignal stop whisper's install and audio prep

Review follow-ups on the api entry:

- whisper's runtime install (brew, git clone, cmake) and its ffmpeg audio
  prep run through a new stoppableExecFile when an API caller passes a
  signal. The child runs off the event loop, an abort ends it and every
  process it started, and the call rejects with a "cancelled"
  TranscribeError once they are gone. A failure throws the same error
  execFileSync throws (message, code, errno, status, signal, stdout,
  stderr), compared field by field in stoppableExecFile.test.ts.
  parakeet-mlx uses the same helper.
- Without a signal the helper is execFileSync, and the CLI passes none, so
  the CLI output stays byte for byte the same as hyperframes 0.8.146.
- TranscribeOptions.signal now says what it covers: a tool lookup that is
  already running (capped at 10 seconds) finishes first.
- New regressions in api.test.ts abort during a stand-in install step and
  during a stand-in ffmpeg convert. Both end in under 10 seconds with no
  process left, and both fail with the old synchronous calls.
- Tests load every module at the top of the file: namespace spies replace
  the importOriginal partial mocks, and node:fs and node:child_process are
  spied through their default exports and synced with
  syncBuiltinESMExports. remove-background --info imports its manager
  statically. The scanner in api.test.ts now reads every file this PR
  touches and catches importOriginal and vi.importActual.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-11 18:05:11 +00:00

173 lines
6.0 KiB
TypeScript

import { randomUUID } from "node:crypto";
import { createWriteStream, renameSync, unlinkSync } from "node:fs";
import { get as httpsGet } from "node:https";
import type { ClientRequest, IncomingMessage } from "node:http";
import { Transform } from "node:stream";
import { pipeline } from "node:stream/promises";
const DEFAULT_DOWNLOAD_TIMEOUT_MS = 30_000;
export interface DownloadOptions {
/** Abort after this many milliseconds without network activity. */
timeoutMs?: number;
/** Reject before writing more than this many response bytes. */
maxBytes?: number;
onProgress?: (receivedBytes: number, totalBytes: number | null) => void;
/** Aborting it destroys the request and removes the partial file. */
signal?: AbortSignal;
}
/** Every redirect a host may reasonably answer with, not just the two we saw first. */
export const REDIRECT_CODES = new Set([301, 302, 303, 307, 308]);
/**
* Where a redirect actually points.
*
* Split out because this is the part that was wrong, and it is the part that
* can be checked without a socket: hosts answer with relative locations
* (`/api/resolve-cache/...`) far more often than the original code assumed, and
* handing that string back as a request target fails.
*/
export function redirectTarget(location: string, from: string): string {
return new URL(location, from).toString();
}
/** Enough hops for a CDN handoff, few enough that a redirect loop still ends. */
const MAX_REDIRECTS = 10;
function removePartialFile(path: string): void {
try {
unlinkSync(path);
} catch {
// Missing/locked partial files are handled by the next atomic download.
}
}
function measureDownload(options: DownloadOptions, contentLength: string | undefined) {
const length = Number(contentLength);
const totalBytes = Number.isSafeInteger(length) && length >= 0 ? length : null;
let receivedBytes = 0;
let reportedAt = Date.now();
options.onProgress?.(0, totalBytes);
const stream = new Transform({
transform(chunk: Buffer, _encoding, callback) {
receivedBytes += chunk.byteLength;
if (options.maxBytes !== undefined && receivedBytes > options.maxBytes) {
callback(new Error(`Download exceeded ${options.maxBytes} bytes`));
return;
}
const now = Date.now();
if (now - reportedAt >= 100) {
options.onProgress?.(receivedBytes, totalBytes);
reportedAt = now;
}
callback(null, chunk);
},
});
return { stream, complete: () => options.onProgress?.(receivedBytes, totalBytes) };
}
function getUrl(
url: string,
signal: AbortSignal | undefined,
onResponse: (res: IncomingMessage) => void,
): ClientRequest {
return signal ? httpsGet(url, { signal }, onResponse) : httpsGet(url, onResponse);
}
/**
* Download a file from a URL, following redirects.
* Uses atomic write (download to .tmp, rename on success) to prevent
* corrupt partial files from persisting in the cache on interruption.
*
* Location headers are resolved against the URL that sent them, because they
* are frequently relative: a host answering 307 with `/api/resolve-cache/...`
* is normal, and passing that string back as a request target is not.
*
* The timeout is per request, so it re-arms on each hop of a redirect chain
* rather than budgeting the whole chain. A stalled socket is what it exists to
* catch, and without it the CLI waits forever.
*/
export function downloadFile(
url: string,
dest: string,
options: DownloadOptions = {},
): Promise<void> {
const tmp = `${dest}.${process.pid}.${randomUUID()}.tmp`;
const timeoutMs = options.timeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS;
return new Promise((resolve, reject) => {
const follow = (u: string, hops = 0) => {
let activeResponse: IncomingMessage | undefined;
let responseDiscarded = false;
let responsePipelineStarted = false;
let requestError: Error | undefined;
let request: ClientRequest;
try {
request = getUrl(u, options.signal, (res) => {
activeResponse = res;
if (res.statusCode && REDIRECT_CODES.has(res.statusCode)) {
const location = res.headers.location;
if (location) {
responseDiscarded = true;
res.destroy();
if (hops >= MAX_REDIRECTS) {
removePartialFile(tmp);
reject(
new Error(`Download failed: more than ${MAX_REDIRECTS} redirects from ${url}`),
);
return;
}
try {
follow(redirectTarget(location, u), hops + 1);
} catch (error) {
removePartialFile(tmp);
reject(error);
}
return;
}
}
if (res.statusCode !== 200) {
responseDiscarded = true;
res.destroy();
removePartialFile(tmp);
reject(new Error(`Download failed: HTTP ${res.statusCode}`));
return;
}
const meter = measureDownload(options, res.headers["content-length"]);
const file = createWriteStream(tmp);
responsePipelineStarted = true;
const transfer = pipeline(res, meter.stream, file);
transfer
.then(() => {
renameSync(tmp, dest);
meter.complete();
resolve();
})
.catch((err) => {
removePartialFile(tmp);
reject(requestError ?? err);
});
});
} catch (error) {
removePartialFile(tmp);
reject(error);
return;
}
request.setTimeout(timeoutMs, () => {
request.destroy(new Error(`Download timed out after ${timeoutMs}ms`));
});
request.on("error", (err) => {
if (responseDiscarded) return;
if (responsePipelineStarted) {
requestError = err;
activeResponse?.destroy(err);
return;
}
removePartialFile(tmp);
reject(err);
});
};
follow(url);
});
}