@paradigma-inc/flywheel 0.1.115 → 0.1.134

package/src/runtime/vendor/flywheel-cli-dist/http/client.js

@@ -1,8 +1,9 @@
-import { randomUUID } from 'node:crypto';
-import { CliApprovalPendingError, } from '../errors.js';
-import { EXIT_AUTH, EXIT_TRANSPORT, } from '../exit-codes.js';
-import { maskForDebug, maskQueryString, redactExternalUrlForOutput, } from './debug.js';
-import { isRetryableNetworkError, isRetryableStatus, parseRetryAfterMs, withRetry, } from './retry.js';
+import { randomUUID } from "node:crypto";
+import { parseRepositoryJson } from "../local/domain/models/encoding.js";
+import { CliApprovalPendingError, } from "../errors.js";
+import { EXIT_AUTH, EXIT_TRANSPORT } from "../exit-codes.js";
+import { maskHeadersForDebug, maskQueryString } from "./debug.js";
+import { isRetryableNetworkError, isRetryableStatus, parseRetryAfterMs, withRetry, } from "./retry.js";
 export class CliHttpError extends Error {
     exitCode;
     status;
@@ -10,7 +11,7 @@ export class CliHttpError extends Error {
     request;
     constructor(message, exitCode, status, body, request) {
         super(message);
-        this.name = 'CliHttpError';
+        this.name = "CliHttpError";
         this.exitCode = exitCode;
         this.status = status;
         this.body = body;
@@ -21,18 +22,26 @@ class RetryableHttpError extends CliHttpError {
     retryAfterMs;
     constructor(message, status, retryAfterMs, body, request) {
         super(message, EXIT_TRANSPORT, status, body, request);
-        this.name = 'RetryableHttpError';
+        this.name = "RetryableHttpError";
         this.retryAfterMs = retryAfterMs;
     }
 }
-const API_VERSION_PREFIX = '/v1';
+class RetryableResponseBodyError extends Error {
+    original;
+    constructor(original) {
+        super(original instanceof Error ? original.message : String(original));
+        this.name = "RetryableResponseBodyError";
+        this.original = original;
+    }
+}
+const API_VERSION_PREFIX = "/v1";
 const ROOT_ONLY_PREFIXES = [
-    '/admin',
-    '/auth/accounts',
-    '/auth/github',
-    '/auth/integrations',
-    '/health',
-    '/repos',
+    "/admin",
+    "/auth/accounts",
+    "/auth/github",
+    "/auth/integrations",
+    "/health",
+    "/repos",
 ];
 function mapStatusToExitCode(status) {
     if (status === 401 || status === 403) {
@@ -41,35 +50,35 @@ function mapStatusToExitCode(status) {
     return EXIT_TRANSPORT;
 }
 function shouldBypassGenericRetryForProviderErrorBody(body) {
-    if (!body || typeof body !== 'object') {
+    if (!body || typeof body !== "object") {
         return false;
     }
     const detail = body.detail;
-    if (!detail || typeof detail !== 'object') {
+    if (!detail || typeof detail !== "object") {
         return false;
     }
     const providerError = detail.provider_error;
-    if (!providerError || typeof providerError !== 'object') {
+    if (!providerError || typeof providerError !== "object") {
         return false;
     }
     const typed = providerError;
-    return typed.retryable === false || typed.refresh_offers_before_retry === true;
+    return (typed.retryable === false || typed.refresh_offers_before_retry === true);
 }
 function maskUrlForDebug(target) {
     // Masks sensitive query parameters (tokens, credentials, signed-upload
     // params) before stringifying. Preserves origin + path + hash verbatim.
     try {
-        const url = typeof target === 'string' ? new URL(target) : target;
+        const url = typeof target === "string" ? new URL(target) : target;
         const maskedSearch = maskQueryString(url.search);
         return `${url.origin}${url.pathname}${maskedSearch}${url.hash}`;
     }
     catch {
-        return typeof target === 'string' ? target : target.toString();
+        return typeof target === "string" ? target : target.toString();
     }
 }
 function toQueryString(query) {
     if (!query) {
-        return '';
+        return "";
     }
     const params = new URLSearchParams();
     for (const [key, value] of Object.entries(query)) {
@@ -82,32 +91,34 @@ function toQueryString(query) {
         params.set(key, String(value));
     }
     const encoded = params.toString();
-    return encoded ? `?${encoded}` : '';
+    return encoded ? `?${encoded}` : "";
 }
 function normalizeInternalPath(path) {
-    return path.startsWith('/') ? path : `/${path}`;
+    return path.startsWith("/") ? path : `/${path}`;
 }
 function normalizeApiVersionPrefix(prefix) {
     const raw = prefix ?? API_VERSION_PREFIX;
     const normalized = raw.trim();
-    if (normalized === '' || normalized === '/') {
-        return '';
+    if (normalized === "" || normalized === "/") {
+        return "";
     }
-    return `/${normalized.replace(/^\/+|\/+$/g, '')}`;
+    return `/${normalized.replace(/^\/+|\/+$/g, "")}`;
 }
-function stripTrailingApiVersionPrefixFromBaseUrl(baseUrl, apiVersionPrefix) {
-    const normalizedBase = baseUrl.replace(/\/+$/, '');
-    if (apiVersionPrefix === '') {
+export function effectiveApiBaseUrl(baseUrl, apiVersionPrefix) {
+    apiVersionPrefix = normalizeApiVersionPrefix(apiVersionPrefix);
+    const normalizedBase = baseUrl.replace(/\/+$/, "");
+    if (apiVersionPrefix === "") {
         return normalizedBase;
     }
     try {
         const parsed = new URL(normalizedBase);
-        const cleanPath = parsed.pathname.replace(/\/+$/u, '');
-        if (cleanPath === apiVersionPrefix || cleanPath.endsWith(apiVersionPrefix)) {
-            parsed.pathname = cleanPath.slice(0, -apiVersionPrefix.length) || '/';
-            parsed.search = '';
-            parsed.hash = '';
-            return parsed.toString().replace(/\/+$/, '');
+        const cleanPath = parsed.pathname.replace(/\/+$/u, "");
+        if (cleanPath === apiVersionPrefix ||
+            cleanPath.endsWith(apiVersionPrefix)) {
+            parsed.pathname = cleanPath.slice(0, -apiVersionPrefix.length) || "/";
+            parsed.search = "";
+            parsed.hash = "";
+            return parsed.toString().replace(/\/+$/, "");
         }
     }
     catch {
@@ -120,7 +131,7 @@ function isRootOnlyPath(path) {
 }
 function versionedRequestPath(path, apiVersionPrefix) {
     const normalized = normalizeInternalPath(path);
-    if (apiVersionPrefix === '' || isRootOnlyPath(normalized)) {
+    if (apiVersionPrefix === "" || isRootOnlyPath(normalized)) {
         return normalized;
     }
     if (normalized === apiVersionPrefix ||
@@ -132,31 +143,34 @@ function versionedRequestPath(path, apiVersionPrefix) {
 function baseUrlLooksLikeOriginRoot(baseUrl) {
     try {
         const parsed = new URL(baseUrl);
-        const cleanPath = parsed.pathname.replace(/\/+$/, '');
-        return cleanPath === '' || cleanPath === '/';
+        const cleanPath = parsed.pathname.replace(/\/+$/, "");
+        return cleanPath === "" || cleanPath === "/";
     }
     catch {
         return false;
     }
 }
 function clampWaitTimeoutSeconds(value) {
-    const raw = typeof value === 'number' && Number.isFinite(value) ? value : 600;
+    const raw = typeof value === "number" && Number.isFinite(value) ? value : 600;
     return Math.min(3600, Math.max(10, Math.trunc(raw)));
 }
 function buildHttpErrorMessage(status, baseUrl) {
     const base = `request failed with status ${status}`;
-    if ((status === 401 || status === 404) && baseUrlLooksLikeOriginRoot(baseUrl)) {
-        return `${base} — base URL appears to be an origin root; try ${baseUrl.replace(/\/+$/, '')}/api`;
+    if ((status === 401 || status === 404) &&
+        baseUrlLooksLikeOriginRoot(baseUrl)) {
+        return `${base} — base URL appears to be an origin root; try ${baseUrl.replace(/\/+$/, "")}/api`;
     }
     return base;
 }
-async function readResponseBody(response) {
-    const contentType = response.headers.get('content-type') ?? '';
-    if (contentType.includes('application/json')) {
+async function readResponseBody(response, signal) {
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
         try {
             return await response.json();
         }
-        catch {
+        catch (error) {
+            if (signal?.aborted || isRetryableNetworkError(error))
+                throw error;
             return null;
         }
     }
@@ -172,10 +186,16 @@ async function readResponseBody(response) {
             return text;
         }
     }
-    catch {
+    catch (error) {
+        if (signal?.aborted || isRetryableNetworkError(error))
+            throw error;
         return null;
     }
 }
+async function readRepositoryJsonResponse(response) {
+    const text = await response.text();
+    return parseRepositoryJson(text);
+}
 function snapshotResponse(status, body) {
     return { status, body };
 }
@@ -186,78 +206,57 @@ function elapsedMsSince(startedAtMs) {
     return Math.max(0, Date.now() - startedAtMs);
 }
 function shouldIncludeRecoveryGuidance(failureKind) {
-    return (failureKind === 'timeout' ||
-        failureKind === 'transport' ||
-        failureKind === 'retryable_status');
+    return (failureKind === "timeout" ||
+        failureKind === "transport" ||
+        failureKind === "retryable_status" ||
+        failureKind === "response_body");
 }
 function pathWithoutApiVersion(path) {
-    return path.replace(/^\/v\d+(?=\/)/, '');
+    return path.replace(/^\/v\d+(?=\/)/, "");
 }
 function isReplayBackedWrite(method, path) {
     const normalizedPath = pathWithoutApiVersion(path);
-    return ((method === 'POST' && normalizedPath === '/nodes/commit-new') ||
-        (method === 'POST' &&
-            /^\/nodes\/[^/]+\/stage\/lease\/(?:acquire|heartbeat|release)$/.test(normalizedPath)) ||
-        (method === 'POST' &&
-            /^\/nodes\/[^/]+\/(?:commit|branch)$/.test(normalizedPath)) ||
-        (method === 'POST' &&
-            /^\/nodes\/[^/]+\/parents\/(?:add|remove)$/.test(normalizedPath)) ||
-        (method === 'DELETE' && /^\/nodes\/[^/]+$/.test(normalizedPath)) ||
-        (method === 'POST' && normalizedPath === '/nodes/bulk-delete') ||
-        (method === 'POST' && normalizedPath === '/nodes/merge') ||
-        (method === 'PUT' &&
+    return ((method === "POST" &&
+        /^\/nodes\/[^/]+\/stage\/lease\/(?:acquire|heartbeat|release)$/.test(normalizedPath)) ||
+        (method === "PUT" &&
             /^\/nodes\/[^/]+\/access-policy$/.test(normalizedPath)) ||
-        (method === 'POST' && normalizedPath === '/nodes/access-policy/bulk') ||
-        (method === 'POST' &&
-            /^\/nodes\/[^/]+\/artifacts\/uploads\/prepare$/.test(normalizedPath)) ||
-        (method === 'POST' &&
-            /^\/nodes\/[^/]+\/artifacts\/uploads\/finalize$/.test(normalizedPath)) ||
-        (method === 'POST' &&
-            /^\/nodes\/[^/]+\/artifacts\/bulk-delete$/.test(normalizedPath)) ||
-        (method === 'DELETE' &&
-            /^\/nodes\/[^/]+\/artifacts\/[^/]+$/.test(normalizedPath)) ||
-        (method === 'PATCH' &&
-            /^\/nodes\/[^/]+\/artifacts\/[^/]+\/note$/.test(normalizedPath)) ||
-        (method === 'POST' &&
+        (method === "POST" && normalizedPath === "/nodes/access-policy/bulk") ||
+        (method === "POST" &&
             /^\/nodes\/[^/]+\/executions$/.test(normalizedPath)) ||
-        (method === 'POST' &&
+        (method === "POST" &&
             /^\/nodes\/[^/]+\/executions\/[^/]+\/terminate$/.test(normalizedPath)) ||
-        (method === 'POST' &&
+        (method === "POST" &&
             /^\/nodes\/[^/]+\/compute\/acquire$/.test(normalizedPath)) ||
-        (method === 'POST' &&
+        (method === "POST" &&
             /^\/users\/me\/machines\/[^/]+\/release$/.test(normalizedPath)) ||
-        (method === 'POST' &&
-            normalizedPath === '/users/me/machines/release-all') ||
-        (method === 'POST' &&
-            normalizedPath === '/compute-grants/request-approval') ||
-        (method === 'POST' && normalizedPath === '/admin/test-users') ||
-        (method === 'DELETE' && /^\/admin\/test-users\/[^/]+$/.test(normalizedPath)) ||
-        (method === 'POST' &&
-            /^\/nodes\/[^/]+\/tags$/.test(normalizedPath)) ||
-        (method === 'PATCH' &&
-            /^\/nodes\/[^/]+\/tags\/[^/]+$/.test(normalizedPath)) ||
-        (method === 'DELETE' &&
-            /^\/nodes\/[^/]+\/tags\/[^/]+$/.test(normalizedPath)) ||
-        (method === 'PUT' && /^\/nodes\/[^/]+\/tags$/.test(normalizedPath)) ||
-        (method === 'POST' && normalizedPath === '/import'));
+        (method === "POST" &&
+            normalizedPath === "/users/me/machines/release-all") ||
+        (method === "POST" &&
+            normalizedPath === "/compute-grants/request-approval") ||
+        (method === "POST" && normalizedPath === "/admin/test-users") ||
+        (method === "DELETE" &&
+            /^\/admin\/test-users\/[^/]+$/.test(normalizedPath)) ||
+        (method === "POST" && normalizedPath === "/repositories") ||
+        (method === "POST" &&
+            /^\/repositories\/[^/]+\/(?:clone-sessions|pull-sessions|objects\/prepare|pushes|membership-removals|ownership-transfers|retirements|commits|purges)$/.test(normalizedPath)) ||
+        (method === "PUT" &&
+            /^\/repositories\/[^/]+\/(?:members\/[^/]+|objects\/sha256%3A[0-9a-f]{64})$/.test(normalizedPath)) ||
+        (method === "POST" && normalizedPath === "/import"));
 }
 function retrySafeForRequest(input) {
-    if (input.method === 'GET') {
+    if (input.method === "GET") {
         return true;
     }
     if (!input.idempotencyKey) {
         return false;
     }
-    if (input.wrapperStep === 'finalize') {
-        return false;
-    }
     return isReplayBackedWrite(input.method, input.path);
 }
 function buildRetryGuidance(input) {
     const feedbackHint = input.requestId
         ? ` If this keeps failing, run feedback:create and include request_id ${input.requestId}.`
-        : ' If this keeps failing, run feedback:create and include the request details.';
-    if (input.method === 'GET') {
+        : " If this keeps failing, run feedback:create and include the request details.";
+    if (input.method === "GET") {
         return `Retry the same read operation.${feedbackHint}`;
     }
     if (input.retrySafe && input.idempotencyKey) {
@@ -283,7 +282,7 @@ function buildFailureRequestContext(input) {
     if (input.idempotencyKey) {
         request.idempotencyKey = input.idempotencyKey;
     }
-    if (typeof input.retryAfterMs === 'number') {
+    if (typeof input.retryAfterMs === "number") {
         request.retryAfterMs = input.retryAfterMs;
     }
     if (input.wrapperStep) {
@@ -301,7 +300,6 @@ function buildFailureRequestContext(input) {
             method: input.method,
             path: input.path,
             idempotencyKey: input.idempotencyKey,
-            wrapperStep: input.wrapperStep,
         });
         request.retrySafe = retrySafe;
         request.retryGuidance = buildRetryGuidance({
@@ -315,25 +313,25 @@ function buildFailureRequestContext(input) {
 }
 function isApprovalRequiredBody(body) {
     return (body !== null &&
-        typeof body === 'object' &&
-        body.code === 'approval_required');
+        typeof body === "object" &&
+        body.code === "approval_required");
 }
 export function createHttpClient(options) {
     const transport = options.transport ?? fetch;
     const apiVersionPrefix = normalizeApiVersionPrefix(options.apiVersionPrefix);
-    const normalizedBase = stripTrailingApiVersionPrefixFromBaseUrl(options.baseUrl, apiVersionPrefix);
+    const normalizedBase = effectiveApiBaseUrl(options.baseUrl, options.apiVersionPrefix);
     const invocationId = options.invocationId ?? randomUUID();
     const retryMax = options.retryMax ?? 3;
     const warnedPaths = new Set();
     function emitDeprecationWarning(path, response, debugLog) {
-        const deprecation = response.headers.get('deprecation');
-        if (!deprecation || deprecation.toLowerCase() === 'false')
+        const deprecation = response.headers.get("deprecation");
+        if (!deprecation || deprecation.toLowerCase() === "false")
             return;
         if (warnedPaths.has(path))
             return;
         warnedPaths.add(path);
-        const sunset = response.headers.get('sunset');
-        const hint = sunset ? ` (sunset: ${sunset})` : '';
+        const sunset = response.headers.get("sunset");
+        const hint = sunset ? ` (sunset: ${sunset})` : "";
         const line = `deprecation warning: this endpoint is deprecated${hint}`;
         if (debugLog)
             debugLog(line);
@@ -344,44 +342,44 @@ export function createHttpClient(options) {
     const debug = options.debug ?? false;
     const debugLog = options.debugLog ?? ((line) => process.stderr.write(`${line}\n`));
     const timeoutMs = options.timeoutMs ?? 300_000;
-    async function doRequest(method, requestPath, requestOptions, idempotencyKey, requestId, startedAtMs, attempt, maxAttempts, requestIdempotencyKey) {
+    async function doRequest(method, requestPath, requestOptions, idempotencyKey, requestId, startedAtMs, attempt, maxAttempts, requestIdempotencyKey, responseMode, consumeResponse) {
         const url = new URL(`${normalizedBase}${requestPath}${toQueryString(requestOptions?.query)}`);
         const headers = {
-            Accept: 'application/json',
+            Accept: "application/json",
         };
         if (options.apiKey && !requestOptions?.skipAuth) {
             headers.Authorization = `Bearer ${options.apiKey}`;
         }
-        if (method !== 'GET' && !requestOptions?.skipIdempotency) {
-            headers['Idempotency-Key'] = idempotencyKey;
+        if (method !== "GET") {
+            headers["Idempotency-Key"] = idempotencyKey;
         }
         if (requestOptions?.body !== undefined && !requestOptions.rawBody) {
-            headers['Content-Type'] = 'application/json';
+            headers["Content-Type"] = "application/json";
         }
         if (options.cliVersion) {
-            headers['X-Flywheel-Cli-Version'] = options.cliVersion;
-            headers['User-Agent'] = `flywheel-cli/${options.cliVersion}`;
+            headers["X-Flywheel-Cli-Version"] = options.cliVersion;
+            headers["User-Agent"] = `flywheel-cli/${options.cliVersion}`;
         }
         if (options.commandName) {
-            headers['X-Flywheel-Cli-Command'] = options.commandName;
+            headers["X-Flywheel-Cli-Command"] = options.commandName;
         }
         if (options.flagNames && options.flagNames.length > 0) {
-            headers['X-Flywheel-Cli-Flags'] = options.flagNames.join(',');
+            headers["X-Flywheel-Cli-Flags"] = options.flagNames.join(",");
         }
-        headers['X-Flywheel-Cli-Invocation-Id'] = invocationId;
-        headers['X-Flywheel-Request-Id'] = requestId;
-        headers['X-Request-ID'] = requestId;
+        headers["X-Flywheel-Cli-Invocation-Id"] = invocationId;
+        headers["X-Flywheel-Request-Id"] = requestId;
+        headers["X-Request-ID"] = requestId;
         const wrapperStep = requestOptions?.wrapperStep ?? options.wrapperStep;
         if (wrapperStep) {
-            headers['X-Flywheel-Cli-Wrapper-Step'] = wrapperStep;
+            headers["X-Flywheel-Cli-Wrapper-Step"] = wrapperStep;
         }
         if (options.waitRequested === true) {
-            headers['X-Flywheel-Cli-Wait-Requested'] = 'true';
-            headers['X-Flywheel-Cli-Wait-Timeout-Seconds'] = String(clampWaitTimeoutSeconds(options.waitTimeoutS));
+            headers["X-Flywheel-Cli-Wait-Requested"] = "true";
+            headers["X-Flywheel-Cli-Wait-Timeout-Seconds"] = String(clampWaitTimeoutSeconds(options.waitTimeoutS));
         }
         const exitIntent = requestOptions?.exitIntent ?? options.exitIntent;
-        if (typeof exitIntent === 'number') {
-            headers['X-Flywheel-Cli-Exit-Intent'] = String(exitIntent);
+        if (typeof exitIntent === "number") {
+            headers["X-Flywheel-Cli-Exit-Intent"] = String(exitIntent);
         }
         if (requestOptions?.extraHeaders) {
             Object.assign(headers, requestOptions.extraHeaders);
@@ -393,18 +391,33 @@ export function createHttpClient(options) {
                 : undefined;
         if (debug) {
             debugLog(`DEBUG: ${method} ${maskUrlForDebug(url)} ${JSON.stringify({
-                headers: maskForDebug(headers),
-                body: maskForDebug(requestOptions?.body ?? null),
+                headers: maskHeadersForDebug(headers),
+                body: {
+                    present: requestOptions?.body !== undefined ||
+                        requestOptions?.rawBody !== undefined,
+                },
             })}`);
         }
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(new Error(`CLI HTTP timeout after ${timeoutMs}ms`)), timeoutMs);
         const progressInterval = process.stdout.isTTY
-            ? setInterval(() => process.stderr.write('.'), 10_000)
-            : null;
+            ? setInterval(() => process.stderr.write("."), 10_000)
+            : undefined;
         let response;
         try {
-            response = await transport(url, { method, headers, body, signal: controller.signal });
+            response = await transport(url, {
+                method,
+                headers,
+                body: body,
+                signal: controller.signal,
+                ...(responseMode === "repository_json" || responseMode === "repository_raw"
+                    ? { redirect: "error" }
+                    : {}),
+            });
+            if (debug) {
+                debugLog(`DEBUG: ${method} ${maskUrlForDebug(url)} -> ${response.status}`);
+            }
+            return await consumeResponse(response, controller.signal);
         }
         catch (error) {
             if (controller.signal.aborted) {
@@ -418,13 +431,37 @@ export function createHttpClient(options) {
                     attempt,
                     maxAttempts,
                     wrapperStep,
-                    failureKind: 'timeout',
+                    failureKind: "timeout",
                 }));
             }
             if (isRetryableNetworkError(error)) {
+                if (response === undefined) {
+                    throw error;
+                }
+                if (retrySafeForRequest({
+                    method,
+                    path: requestPath,
+                    idempotencyKey: requestIdempotencyKey,
+                })) {
+                    throw new RetryableResponseBodyError(error);
+                }
+                throw new CliHttpError("transport error", EXIT_TRANSPORT, undefined, undefined, buildFailureRequestContext({
+                    method,
+                    path: requestPath,
+                    requestId,
+                    idempotencyKey: requestIdempotencyKey,
+                    timeoutMs,
+                    startedAtMs,
+                    attempt,
+                    maxAttempts,
+                    wrapperStep,
+                    failureKind: "response_body",
+                }));
+            }
+            if (response !== undefined) {
                 throw error;
             }
-            throw new CliHttpError('transport error', EXIT_TRANSPORT, undefined, undefined, buildFailureRequestContext({
+            throw new CliHttpError("transport error", EXIT_TRANSPORT, undefined, undefined, buildFailureRequestContext({
                 method,
                 path: requestPath,
                 requestId,
@@ -434,75 +471,106 @@ export function createHttpClient(options) {
                 attempt,
                 maxAttempts,
                 wrapperStep,
-                failureKind: 'transport',
+                failureKind: "transport",
             }));
         }
         finally {
             clearTimeout(timer);
-            if (progressInterval)
-                clearInterval(progressInterval);
-        }
-        if (debug) {
-            debugLog(`DEBUG: ${method} ${maskUrlForDebug(url)} -> ${response.status}`);
+            clearInterval(progressInterval);
         }
-        return response;
     }
-    async function requestWithRetry(method, path, requestOptions) {
+    async function requestWithRetry(method, path, requestOptions, responseMode, consumeRepositoryResponse) {
         const requestPath = versionedRequestPath(path, apiVersionPrefix);
-        const idempotencyKey = options.idempotencyKey ?? randomUUID();
-        const requestIdempotencyKey = method !== 'GET' && requestOptions?.skipIdempotency !== true
-            ? idempotencyKey
-            : undefined;
+        const idempotencyKey = requestOptions?.idempotencyKey ?? options.idempotencyKey ?? randomUUID();
+        const requestIdempotencyKey = method !== "GET" ? idempotencyKey : undefined;
         const requestId = randomUUID();
-        const maxAttempts = normalizeMaxAttempts(retryEnabled ? retryMax : 1);
+        const maxAttempts = normalizeMaxAttempts(retryEnabled && requestOptions?.retryEnabled !== false ? retryMax : 1);
         const wrapperStep = requestOptions?.wrapperStep ?? options.wrapperStep;
         let attempt = 0;
         let lastAttemptStartedAtMs = Date.now();
         const fn = async () => {
             attempt += 1;
             lastAttemptStartedAtMs = Date.now();
-            let response;
-            try {
-                response = await doRequest(method, requestPath, requestOptions, idempotencyKey, requestId, lastAttemptStartedAtMs, attempt, maxAttempts, requestIdempotencyKey);
-            }
-            catch (error) {
-                // Network/transport layer errors propagate (retry layer decides).
-                if (isRetryableNetworkError(error)) {
-                    throw error;
-                }
-                throw error;
-            }
-            if (!response.ok) {
-                const body = await readResponseBody(response);
-                if (response.status === 422 && isApprovalRequiredBody(body)) {
-                    const approvalBody = body;
-                    throw new CliApprovalPendingError(typeof approvalBody.message === 'string'
-                        ? approvalBody.message
-                        : 'approval required', {
-                        approvalUrl: typeof approvalBody.approval_url === 'string'
-                            ? approvalBody.approval_url
-                            : undefined,
-                        approvalRequestId: typeof approvalBody.approval_request_id === 'string'
-                            ? approvalBody.approval_request_id
-                            : undefined,
-                        grantId: typeof approvalBody.grant_id === 'string'
-                            ? approvalBody.grant_id
-                            : undefined,
-                        requiredSignoffs: Array.isArray(approvalBody.required_signoffs)
-                            ? approvalBody.required_signoffs.filter((v) => typeof v === 'string')
-                            : undefined,
-                        serverResponse: snapshotResponse(response.status, body),
-                        request: {
+            return await doRequest(method, requestPath, requestOptions, idempotencyKey, requestId, lastAttemptStartedAtMs, attempt, maxAttempts, requestIdempotencyKey, responseMode, async (response, signal) => {
+                if (!response.ok) {
+                    const body = await readResponseBody(response, signal);
+                    if (response.status === 422 && isApprovalRequiredBody(body)) {
+                        const approvalBody = body;
+                        throw new CliApprovalPendingError(typeof approvalBody.message === "string"
+                            ? approvalBody.message
+                            : "approval required", {
+                            approvalUrl: typeof approvalBody.approval_url === "string"
+                                ? approvalBody.approval_url
+                                : undefined,
+                            approvalRequestId: typeof approvalBody.approval_request_id === "string"
+                                ? approvalBody.approval_request_id
+                                : undefined,
+                            grantId: typeof approvalBody.grant_id === "string"
+                                ? approvalBody.grant_id
+                                : undefined,
+                            requiredSignoffs: Array.isArray(approvalBody.required_signoffs)
+                                ? approvalBody.required_signoffs.filter((v) => typeof v === "string")
+                                : undefined,
+                            serverResponse: snapshotResponse(response.status, body),
+                            request: {
+                                method,
+                                path: requestPath,
+                                requestId,
+                            },
+                        });
+                    }
+                    if (isRetryableStatus(response.status)) {
+                        const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
+                        const suppressRetryGuidance = shouldBypassGenericRetryForProviderErrorBody(body);
+                        throw new RetryableHttpError(buildHttpErrorMessage(response.status, options.baseUrl), response.status, retryAfterMs, body, buildFailureRequestContext({
                             method,
                             path: requestPath,
                             requestId,
-                        },
-                    });
-                }
-                if (isRetryableStatus(response.status)) {
-                    const retryAfterMs = parseRetryAfterMs(response.headers.get('retry-after'));
-                    const suppressRetryGuidance = shouldBypassGenericRetryForProviderErrorBody(body);
-                    throw new RetryableHttpError(buildHttpErrorMessage(response.status, options.baseUrl), response.status, retryAfterMs, body, buildFailureRequestContext({
+                            idempotencyKey: requestIdempotencyKey,
+                            timeoutMs,
+                            startedAtMs: lastAttemptStartedAtMs,
+                            attempt,
+                            maxAttempts,
+                            retryAfterMs,
+                            wrapperStep,
+                            failureKind: "retryable_status",
+                            suppressRetryGuidance,
+                        }));
+                    }
+                    if (response.status === 426) {
+                        throw new CliHttpError("upgrade required: install the latest @paradigma-inc/flywheel package", EXIT_TRANSPORT, 426, body, buildFailureRequestContext({
+                            method,
+                            path: requestPath,
+                            requestId,
+                            idempotencyKey: requestIdempotencyKey,
+                            timeoutMs,
+                            startedAtMs: lastAttemptStartedAtMs,
+                            attempt,
+                            maxAttempts,
+                            wrapperStep,
+                            failureKind: "http_status",
+                        }));
+                    }
+                    if (response.status === 410) {
+                        const hint = body &&
+                            typeof body === "object" &&
+                            typeof body.replacement === "string"
+                            ? body.replacement
+                            : null;
+                        throw new CliHttpError(`resource gone${hint ? ` — use ${hint}` : ""}`, EXIT_TRANSPORT, 410, body, buildFailureRequestContext({
+                            method,
+                            path: requestPath,
+                            requestId,
+                            idempotencyKey: requestIdempotencyKey,
+                            timeoutMs,
+                            startedAtMs: lastAttemptStartedAtMs,
+                            attempt,
+                            maxAttempts,
+                            wrapperStep,
+                            failureKind: "http_status",
+                        }));
+                    }
+                    throw new CliHttpError(buildHttpErrorMessage(response.status, options.baseUrl), mapStatusToExitCode(response.status), response.status, body, buildFailureRequestContext({
                         method,
                         path: requestPath,
                         requestId,
@@ -511,31 +579,47 @@ export function createHttpClient(options) {
                         startedAtMs: lastAttemptStartedAtMs,
                         attempt,
                         maxAttempts,
-                        retryAfterMs,
                         wrapperStep,
-                        failureKind: 'retryable_status',
-                        suppressRetryGuidance,
+                        failureKind: "http_status",
                     }));
                 }
-                if (response.status === 426) {
-                    throw new CliHttpError('upgrade required: install the latest @paradigma-inc/flywheel package', EXIT_TRANSPORT, 426, body, buildFailureRequestContext({
-                        method,
-                        path: requestPath,
-                        requestId,
-                        idempotencyKey: requestIdempotencyKey,
-                        timeoutMs,
-                        startedAtMs: lastAttemptStartedAtMs,
-                        attempt,
-                        maxAttempts,
-                        wrapperStep,
-                        failureKind: 'http_status',
-                    }));
+                emitDeprecationWarning(requestPath, response, debugLog);
+                if (consumeRepositoryResponse) {
+                    return await consumeRepositoryResponse(response);
+                }
+                if (responseMode === "raw") {
+                    return response;
+                }
+                let body = null;
+                let responseError;
+                if (responseMode === "repository_json") {
+                    try {
+                        body = await readRepositoryJsonResponse(response);
+                    }
+                    catch (error) {
+                        if (signal.aborted || isRetryableNetworkError(error))
+                            throw error;
+                        body = undefined;
+                        responseError = "response body could not be read or parsed as JSON";
+                    }
                 }
-                if (response.status === 410) {
-                    const hint = body && typeof body === 'object' && typeof body.replacement === 'string'
-                        ? body.replacement
-                        : null;
-                    throw new CliHttpError(`resource gone${hint ? ` — use ${hint}` : ''}`, EXIT_TRANSPORT, 410, body, buildFailureRequestContext({
+                else {
+                    const contentType = response.headers.get("content-type") ?? "";
+                    if (contentType.includes("application/json")) {
+                        try {
+                            body = await response.json();
+                        }
+                        catch (error) {
+                            if (signal.aborted || isRetryableNetworkError(error))
+                                throw error;
+                            body = undefined;
+                            responseError = "response body could not be read or parsed as JSON";
+                        }
+                    }
+                }
+                responseError ??= requestOptions?.validateJson?.(body);
+                if (responseError !== undefined) {
+                    throw new CliHttpError(responseError, EXIT_TRANSPORT, response.status, body, buildFailureRequestContext({
                         method,
                         path: requestPath,
                         requestId,
@@ -545,24 +629,11 @@ export function createHttpClient(options) {
                         attempt,
                         maxAttempts,
                         wrapperStep,
-                        failureKind: 'http_status',
+                        failureKind: "response_body",
                     }));
                 }
-                throw new CliHttpError(buildHttpErrorMessage(response.status, options.baseUrl), mapStatusToExitCode(response.status), response.status, body, buildFailureRequestContext({
-                    method,
-                    path: requestPath,
-                    requestId,
-                    idempotencyKey: requestIdempotencyKey,
-                    timeoutMs,
-                    startedAtMs: lastAttemptStartedAtMs,
-                    attempt,
-                    maxAttempts,
-                    wrapperStep,
-                    failureKind: 'http_status',
-                }));
-            }
-            emitDeprecationWarning(requestPath, response, debugLog);
-            return response;
+                return body;
+            });
         };
         try {
             return await withRetry(fn, {
@@ -576,11 +647,14 @@ export function createHttpClient(options) {
                         if (shouldBypassGenericRetryForProviderErrorBody(error.body)) {
                             return { retry: false };
                         }
-                        if (typeof error.retryAfterMs === 'number') {
+                        if (typeof error.retryAfterMs === "number") {
                             return { retry: true, delayMs: error.retryAfterMs };
                         }
                         return { retry: true };
                     }
+                    if (error instanceof RetryableResponseBodyError) {
+                        return { retry: true };
+                    }
                     if (isRetryableNetworkError(error)) {
                         return { retry: true };
                     }
@@ -594,10 +668,30 @@ export function createHttpClient(options) {
             // out of withRetry after retries exhaust. Without this, runCli
             // would hit the generic Error path and lose the structured stderr
             // envelope, request metadata, and localhost-setup hint.
+            if (error instanceof RetryableResponseBodyError) {
+                const detail = error.original instanceof Error
+                    ? error.original.message
+                    : String(error.original);
+                throw new CliHttpError(`transport error: ${detail}`, EXIT_TRANSPORT, undefined, undefined, buildFailureRequestContext({
+                    method,
+                    path: requestPath,
+                    requestId,
+                    idempotencyKey: requestIdempotencyKey,
+                    timeoutMs,
+                    startedAtMs: lastAttemptStartedAtMs,
+                    attempt: Math.max(1, attempt),
+                    maxAttempts,
+                    wrapperStep,
+                    failureKind: "response_body",
+                }));
+            }
             if (error instanceof CliHttpError ||
                 error instanceof CliApprovalPendingError) {
                 throw error;
             }
+            if (responseMode === "repository_raw" && !isRetryableNetworkError(error)) {
+                throw error;
+            }
             const detail = error instanceof Error ? error.message : String(error);
             throw new CliHttpError(`transport error: ${detail}`, EXIT_TRANSPORT, undefined, undefined, buildFailureRequestContext({
                 method,
@@ -609,98 +703,22 @@ export function createHttpClient(options) {
                 attempt: Math.max(1, attempt),
                 maxAttempts,
                 wrapperStep,
-                failureKind: 'transport',
+                failureKind: "transport",
             }));
         }
     }
     return {
         async requestJson(method, path, requestOptions) {
-            const response = await requestWithRetry(method, path, requestOptions);
-            if (requestOptions?.rawResponse) {
-                return response;
-            }
-            const contentType = response.headers.get('content-type') ?? '';
-            if (!contentType.includes('application/json')) {
-                // 204/empty responses
-                return null;
-            }
-            return (await response.json());
+            return requestWithRetry(method, path, requestOptions, "json");
         },
-        async requestRaw(method, path, requestOptions) {
-            return requestWithRetry(method, path, requestOptions);
+        async requestRepositoryJson(method, path, requestOptions) {
+            return requestWithRetry(method, path, requestOptions, "repository_json");
         },
-        async requestRawExternal(method, absoluteUrl, rawOptions) {
-            if (typeof absoluteUrl !== 'string' ||
-                !(absoluteUrl.startsWith('http://') || absoluteUrl.startsWith('https://'))) {
-                throw new TypeError('requestRawExternal requires an absolute URL');
-            }
-            const headers = {};
-            if (rawOptions?.extraHeaders) {
-                Object.assign(headers, rawOptions.extraHeaders);
-            }
-            if (debug) {
-                debugLog(`DEBUG: ${method} ${redactExternalUrlForOutput(absoluteUrl)} (external) ${JSON.stringify({
-                    headers: maskForDebug(headers),
-                })}`);
-            }
-            // Apply the same timeout + abort semantics as internal requests so
-            // external uploads to stalled signed URLs can't hang the CLI past
-            // the configured --timeout / profile default_timeout_s.
-            const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort(new Error(`CLI HTTP timeout after ${timeoutMs}ms`)), timeoutMs);
-            const progressInterval = process.stdout.isTTY
-                ? setInterval(() => process.stderr.write('.'), 10_000)
-                : null;
-            const redactedPath = redactExternalUrlForOutput(absoluteUrl);
-            const startedAtMs = Date.now();
-            const wrapperStep = rawOptions?.wrapperStep ?? options.wrapperStep;
-            let response;
-            try {
-                response = await transport(new URL(absoluteUrl), {
-                    method,
-                    headers,
-                    body: rawOptions?.rawBody,
-                    signal: controller.signal,
-                });
-            }
-            catch (error) {
-                // Mirror internal-request semantics so callers always receive a
-                // structured CliHttpError envelope (with EXIT_TRANSPORT + the
-                // redacted external URL as `request.path`) instead of a raw network
-                // error bubbling out through the generic Error path in runCli.
-                void error;
-                if (controller.signal.aborted) {
-                    throw new CliHttpError(`request timed out after ${timeoutMs}ms`, EXIT_TRANSPORT, undefined, undefined, buildFailureRequestContext({
-                        method,
-                        path: redactedPath,
-                        timeoutMs,
-                        startedAtMs,
-                        attempt: 1,
-                        maxAttempts: 1,
-                        wrapperStep,
-                        failureKind: 'timeout',
-                    }));
-                }
-                throw new CliHttpError(`transport error while contacting ${redactedPath}`, EXIT_TRANSPORT, undefined, undefined, buildFailureRequestContext({
-                    method,
-                    path: redactedPath,
-                    timeoutMs,
-                    startedAtMs,
-                    attempt: 1,
-                    maxAttempts: 1,
-                    wrapperStep,
-                    failureKind: 'transport',
-                }));
-            }
-            finally {
-                clearTimeout(timer);
-                if (progressInterval)
-                    clearInterval(progressInterval);
-            }
-            if (debug) {
-                debugLog(`DEBUG: ${method} ${redactExternalUrlForOutput(absoluteUrl)} (external) -> ${response.status}`);
-            }
-            return response;
+        async requestRepositoryRaw(method, path, consumeResponse, requestOptions) {
+            return requestWithRetry(method, path, requestOptions, "repository_raw", consumeResponse);
+        },
+        async requestRaw(method, path, requestOptions) {
+            return requestWithRetry(method, path, requestOptions, "raw");
         },
     };
 }