Files
hyperframes/packages/cli/src/cloud/errors.ts
T

112 lines
4.4 KiB
TypeScript

import { failCommand } from "../utils/commandResult.js";
/**
* Shared API-error reporter for the cloud subverbs.
*
* Centralizes the three-branch `instanceof HyperframesApiError` → `Error`
* → `String` cascade so the curated `ERROR_CODE_HINTS` table is applied
* uniformly across `render`/`list`/`get`/`delete`. Without this, each
* subverb had to remember to consult the hint table (and most didn't,
* which is why review finding 10 was that `hyperframes_render_not_found`
* was unreachable from get/delete).
*/
import { errorBox } from "../ui/format.js";
import { HyperframesApiError } from "./_gen/client.js";
/**
* Hints surfaced when a HyperframesApiError carries a known machine-
* readable code. Keep entries actionable; if there's nothing useful to
* say, leave the code out and let the message stand on its own.
*/
const ERROR_CODE_HINTS: Record<string, string> = {
hyperframes_project_too_large:
"The zip exceeded the 200 MB limit. Run `hyperframes cloud render --dry-run` to see what stays in it, then add only verified-unneeded paths to `.hyperframesignore`.",
hyperframes_render_not_found:
"The render_id no longer exists — either soft-deleted or never created.",
invalid_parameter:
"Check the listed parameter against `hyperframes cloud render --help` for the accepted values.",
authentication_failed:
"Run `hyperframes auth status` to confirm your credential; `hyperframes auth login` to re-auth.",
rate_limit_exceeded: "Retry after the duration in the Retry-After header.",
};
// The asset upload API reports an over-limit file as invalid_parameter; only its message says why.
function hintCode(err: HyperframesApiError): string | undefined {
if (err.code === "invalid_parameter" && /^File too large\b/.test(err.message)) {
return "hyperframes_project_too_large";
}
return err.code;
}
/**
* Print an errorBox and `process.exit(1)` for any unknown error from
* the cloud subverbs. The `stage` is the human-readable name of the
* step that failed (e.g. "Upload failed", "Submit failed", "Could not
* list cloud renders"). Returns `never` so call sites can `throw` from
* the catch block without a separate exit.
*
* Options:
* - `notFound`: short-circuit on a 404 with this friendly message
* (the render-id, asset-id, etc. that wasn't found).
* - `extraHints`: per-code overrides merged on top of
* `ERROR_CODE_HINTS`.
* - `suggestion`: a fallback line shown when no code-specific hint
* matches. Use this for caller-context that's always actionable
* (e.g. "Resume with: hyperframes cloud get hfr_X" on poll
* errors) so the user can recover without having to remember the
* render_id.
*/
/** `code: ETIMEDOUT` for a failed fetch, whose own message is only "fetch failed"; the cause names why. */
function networkCode(err: Error): string | undefined {
const code = (err.cause as { code?: unknown } | undefined)?.code;
return typeof code === "string" && /^[A-Z][A-Z0-9_]{2,40}$/.test(code)
? `code: ${code}`
: undefined;
}
// fallow-ignore-next-line complexity
export function reportApiError(
stage: string,
err: unknown,
options: {
notFound?: string;
extraHints?: Record<string, string>;
suggestion?: string;
} = {},
): never {
const hints = { ...ERROR_CODE_HINTS, ...options.extraHints };
if (err instanceof HyperframesApiError) {
if (err.status === 404 && options.notFound) {
errorBox("Not found", options.notFound);
failCommand();
}
const code = hintCode(err);
const hint = code ? hints[code] : undefined;
const title = `${stage} (HTTP ${err.status})`;
const message =
err.param && !err.message.includes(err.param)
? `${err.message} (parameter: ${err.param})`
: err.message;
// Priority: code-specific hint > caller suggestion > bare code
// label > no third line. Code-specific hints win because they
// address the specific failure mode; the caller suggestion is a
// generic-context fallback.
if (hint) {
errorBox(title, message, hint);
} else if (options.suggestion) {
errorBox(title, message, options.suggestion);
} else if (err.code) {
errorBox(title, message, `code: ${err.code}`);
} else {
errorBox(title, message);
}
failCommand();
}
if (err instanceof Error) {
errorBox(stage, err.message, options.suggestion ?? networkCode(err));
failCommand();
}
errorBox(stage, String(err), options.suggestion);
failCommand();
}