@tapi-dev/sdk 0.1.29 → 0.1.31

package/dist/cli.d.ts

@@ -60,6 +60,7 @@ export interface StudioCliOptions {
     silent: boolean;
     exePath?: string;
     installToken?: string;
+    installTokenSource?: "option" | "env" | "minted";
     workspace?: TapiWorkspace;
     workspaceRoot?: string;
     projectId?: string;
@@ -113,7 +114,7 @@ export declare function getStudioExecutableCandidates(): string[];
 export declare function validateStudioManifest(input: unknown): StudioReleaseManifest;
 export declare function validateServiceReleaseManifest(input: unknown): ServiceReleaseManifest;
 export declare function compareVersions(left: string, right: string): number;
-export declare function memoizeStudioInstallToken(options: StudioCliOptions, installToken?: string): string;
+export declare function memoizeStudioInstallToken(options: StudioCliOptions, installToken?: string, source?: StudioCliOptions["installTokenSource"]): string;
 export declare function closeExistingPortableStudioServersForFreshLaunch(stopProcesses?: () => Promise<number>): Promise<{
     stopped: number;
     recordsRemoved: number;
@@ -125,7 +126,9 @@ export declare function chooseStudioPort(preferred?: number, options?: {
     portAvailable?: StudioPortAvailable;
     reapBlockedPorts?: StudioPortReaper;
 }): Promise<number>;
-export declare function downloadAndVerify(url: string, destination: string, expectedSha256: string, label?: string): Promise<void>;
+export declare function downloadAndVerify(url: string, destination: string, expectedSha256: string, label?: string, options?: {
+    stallTimeoutMs?: number;
+}): Promise<void>;
 export declare function studioInstanceRecordPathForOptions(options: StudioCliOptions): string;
 export declare function findPortableStudioServerExe(releaseDir: string, manifest: StudioReleaseManifest): string | undefined;
 export declare function estimateRequiredExtractionBytes(zipBytes: number): number;

package/dist/cli.js

@@ -9,7 +9,7 @@ import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { performance } from "node:perf_hooks";
 import { emitKeypressEvents } from "node:readline";
-import { Readable } from "node:stream";
+import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { TapiClient } from "./index.js";
@@ -23,6 +23,8 @@ const SUPPORTED_STUDIO_PLATFORM = "windows-x86_64";
 const DEFAULT_INSTALL_AUTH_TIMEOUT_MS = 120_000;
 const PORTABLE_STUDIO_SERVER_READY_TIMEOUT_MS = 30_000;
 const PORTABLE_STUDIO_SERVER_READY_INTERVAL_MS = 250;
+const DOWNLOAD_STALL_TIMEOUT_MS = 30_000;
+const DOWNLOAD_PROGRESS_LOG_BYTES = 50 * 1024 * 1024;
 const MAX_WIDE_EVENT_PROCESS_ROOTS = 5;
 const MAX_NONCURRENT_MANAGED_DOWNLOADS = 0;
 const MAX_NONCURRENT_MANAGED_RELEASES = 0;
@@ -342,6 +344,8 @@ export function parseStudioOptions(args) {
         : `${downloadsBaseUrl.replace(/\/+$/, "")}/studio/channels/${channel}/latest.json`;
     const projectId = raw.projectId ?? envString("TAPI_PROJECT_ID") ?? workspace?.projectId;
     const projectSlug = raw.projectSlug ?? envString("TAPI_PROJECT_SLUG") ?? workspace?.projectSlug;
+    const envInstallToken = envString("TAPI_STUDIO_INSTALL_TOKEN");
+    const installToken = raw.installToken ?? envInstallToken;
     return {
         channel,
         apiBaseUrl,
@@ -352,7 +356,8 @@ export function parseStudioOptions(args) {
         downloadOnly: raw.downloadOnly ?? false,
         silent: raw.silent ?? false,
         exePath: raw.exePath ?? envString("TAPI_STUDIO_EXE"),
-        installToken: raw.installToken ?? envString("TAPI_STUDIO_INSTALL_TOKEN"),
+        installToken,
+        installTokenSource: raw.installToken ? "option" : installToken ? "env" : undefined,
         workspace,
         workspaceRoot: workspace?.root,
         projectId,
@@ -1965,12 +1970,7 @@ async function installStudio(options) {
             throw new Error("Direct Studio manifest overrides are no longer supported for install. "
                 + "Use --channel with the protected install flow instead.");
         }
-        const installToken = await ensureStudioInstallTokenForRun(options, event, "Checking Studio install authorization");
-        await event.phase("manifest.fetch.start", {
-            apiBaseUrl: options.apiBaseUrl,
-            channel: options.channel,
-        });
-        const manifest = await withCliSpinner(`Fetching Tapi Studio ${options.channel} manifest`, () => fetchProtectedStudioManifest(options.apiBaseUrl, options.channel, installToken));
+        const manifest = await fetchStudioManifestForRun(options, event, "Checking Studio install authorization");
         await event.phase("manifest.fetch.success", {
             manifest: manifestEventSummary(manifest),
         });
@@ -2084,7 +2084,7 @@ async function obtainStudioInstallToken(options, event) {
     const issued = await requestStudioInstallToken(options.apiBaseUrl, options.channel, firebaseCreds.idToken);
     return issued.installToken;
 }
-export function memoizeStudioInstallToken(options, installToken) {
+export function memoizeStudioInstallToken(options, installToken, source = "minted") {
     const existing = options.installToken?.trim();
     if (existing) {
         options.installToken = existing;
@@ -2093,9 +2093,14 @@ export function memoizeStudioInstallToken(options, installToken) {
     const normalized = installToken?.trim() ?? "";
     if (normalized) {
         options.installToken = normalized;
+        options.installTokenSource = source;
     }
     return normalized;
 }
+function clearStudioInstallTokenForRun(options) {
+    options.installToken = undefined;
+    options.installTokenSource = undefined;
+}
 async function ensureStudioInstallTokenForRun(options, event, message) {
     const existing = memoizeStudioInstallToken(options);
     if (existing) {
@@ -2109,7 +2114,7 @@ async function ensureStudioInstallTokenForRun(options, event, message) {
         apiBaseUrl: options.apiBaseUrl,
         channel: options.channel,
     });
-    const installToken = memoizeStudioInstallToken(options, await withCliSpinner(message, () => obtainStudioInstallToken(options, event)));
+    const installToken = memoizeStudioInstallToken(options, await withCliSpinner(message, () => obtainStudioInstallToken(options, event)), "minted");
     await event.phase("auth.install_token.request.success", {
         apiBaseUrl: options.apiBaseUrl,
         channel: options.channel,
@@ -2117,6 +2122,39 @@ async function ensureStudioInstallTokenForRun(options, event, message) {
     });
     return installToken;
 }
+async function fetchStudioManifestForRun(options, event, authMessage) {
+    const installToken = await ensureStudioInstallTokenForRun(options, event, authMessage);
+    await event.phase("manifest.fetch.start", {
+        apiBaseUrl: options.apiBaseUrl,
+        channel: options.channel,
+    });
+    try {
+        return await withCliSpinner(`Fetching Tapi Studio ${options.channel} manifest`, () => fetchProtectedStudioManifest(options.apiBaseUrl, options.channel, installToken));
+    }
+    catch (error) {
+        if (!isExpiredStudioInstallTokenError(error) || options.installTokenSource === "option") {
+            throw error;
+        }
+        await event.phase("auth.install_token.expired", {
+            apiBaseUrl: options.apiBaseUrl,
+            channel: options.channel,
+            tokenSource: options.installTokenSource ?? "unknown",
+            error: errorDetails(error),
+        });
+        clearStudioInstallTokenForRun(options);
+        const refreshedToken = await ensureStudioInstallTokenForRun(options, event, "Refreshing Studio install authorization");
+        await event.phase("manifest.fetch.retry.start", {
+            apiBaseUrl: options.apiBaseUrl,
+            channel: options.channel,
+        });
+        return await withCliSpinner(`Retrying Tapi Studio ${options.channel} manifest`, () => fetchProtectedStudioManifest(options.apiBaseUrl, options.channel, refreshedToken));
+    }
+}
+function isExpiredStudioInstallTokenError(error) {
+    const message = formatError(error);
+    return (message.includes("Failed to fetch protected Studio manifest: HTTP 401")
+        && message.includes("Studio install token has expired"));
+}
 async function openStudio(options) {
     ensureWindowsHost();
     if (options.downloadOnly) {
@@ -2178,12 +2216,7 @@ async function ensurePortableStudioServer(options) {
         options: installEventOptions(options),
     });
     try {
-        const installToken = await ensureStudioInstallTokenForRun(options, event, "Checking Studio install authorization");
-        await event.phase("manifest.fetch.start", {
-            apiBaseUrl: options.apiBaseUrl,
-            channel: options.channel,
-        });
-        const manifest = await withCliSpinner(`Fetching Tapi Studio ${options.channel} manifest`, () => fetchProtectedStudioManifest(options.apiBaseUrl, options.channel, installToken));
+        const manifest = await fetchStudioManifestForRun(options, event, "Checking Studio install authorization");
         ensureCompatibleManifest(manifest);
         await event.phase("manifest.fetch.success", {
             manifest: manifestEventSummary(manifest),
@@ -2617,11 +2650,11 @@ async function requestStudioInstallToken(apiBaseUrl, channel, firebaseIdToken, f
         expiresAt: typeof payload?.expiresAt === "string" ? payload.expiresAt : undefined,
     };
 }
-export async function downloadAndVerify(url, destination, expectedSha256, label = "Studio installer") {
+export async function downloadAndVerify(url, destination, expectedSha256, label = "Studio installer", options = {}) {
     const partialPath = `${destination}.partial`;
     await unlinkIfExists(partialPath);
     try {
-        await downloadFile(url, partialPath, label);
+        await downloadFile(url, partialPath, label, options);
         const actualSha256 = await sha256File(partialPath);
         if (actualSha256 !== expectedSha256.toLowerCase()) {
             throw new Error(`${label} checksum mismatch. Expected ${expectedSha256}, got ${actualSha256}.`);
@@ -2634,15 +2667,97 @@ export async function downloadAndVerify(url, destination, expectedSha256, label
         throw error;
     }
 }
-async function downloadFile(url, destination, label = "download") {
-    const response = await fetch(url);
-    if (!response.ok) {
-        throw new Error(`Failed to download ${label}: HTTP ${response.status}`);
+async function downloadFile(url, destination, label = "download", options = {}) {
+    const stallTimeoutMs = normalizeDownloadTimeout(options.stallTimeoutMs);
+    const controller = new AbortController();
+    let stallTimer;
+    let stallError;
+    let source;
+    let progressStream;
+    let destinationStream;
+    let receivedBytes = 0;
+    let nextProgressLogBytes = DOWNLOAD_PROGRESS_LOG_BYTES;
+    const failIfStalled = (phase) => {
+        if (stallTimer) {
+            clearTimeout(stallTimer);
+        }
+        stallTimer = setTimeout(() => {
+            stallError = formatDownloadStallError(label, stallTimeoutMs, phase, receivedBytes);
+            controller.abort(stallError);
+            source?.destroy(stallError);
+            progressStream?.destroy(stallError);
+            destinationStream?.destroy(stallError);
+        }, stallTimeoutMs);
+    };
+    try {
+        console.log(`Downloading ${label}...`);
+        failIfStalled("connecting");
+        const response = await fetch(url, { signal: controller.signal });
+        if (!response.ok) {
+            throw new Error(`Failed to download ${label}: HTTP ${response.status}`);
+        }
+        if (!response.body) {
+            throw new Error(`${label} response did not include a body.`);
+        }
+        failIfStalled("receiving data");
+        source = Readable.fromWeb(response.body);
+        progressStream = new Transform({
+            transform(chunk, _encoding, callback) {
+                receivedBytes += downloadChunkByteLength(chunk);
+                failIfStalled("receiving data");
+                if (receivedBytes >= nextProgressLogBytes) {
+                    console.log(`Downloaded ${label}: ${formatBytes(receivedBytes)}...`);
+                    while (receivedBytes >= nextProgressLogBytes) {
+                        nextProgressLogBytes += DOWNLOAD_PROGRESS_LOG_BYTES;
+                    }
+                }
+                callback(null, chunk);
+            },
+        });
+        destinationStream = createWriteStream(destination);
+        await pipeline(source, progressStream, destinationStream);
+        console.log(`Downloaded ${label}: ${formatBytes(receivedBytes)}.`);
+    }
+    catch (error) {
+        if (stallError) {
+            throw stallError;
+        }
+        throw error;
     }
-    if (!response.body) {
-        throw new Error(`${label} response did not include a body.`);
+    finally {
+        if (stallTimer) {
+            clearTimeout(stallTimer);
+        }
+    }
+}
+function downloadChunkByteLength(chunk) {
+    if (typeof chunk === "string") {
+        return Buffer.byteLength(chunk);
+    }
+    if (Buffer.isBuffer(chunk)) {
+        return chunk.length;
+    }
+    if (chunk instanceof Uint8Array) {
+        return chunk.byteLength;
+    }
+    return 0;
+}
+function normalizeDownloadTimeout(timeoutMs) {
+    if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs)) {
+        return DOWNLOAD_STALL_TIMEOUT_MS;
+    }
+    return Math.max(1, Math.floor(timeoutMs));
+}
+function formatDownloadStallError(label, timeoutMs, phase, receivedBytes) {
+    const progress = receivedBytes > 0 ? ` after ${formatBytes(receivedBytes)}` : "";
+    return new Error(`${label} download stalled${progress}: no data received for ${formatDuration(timeoutMs)} while ${phase}. ` +
+        "Check your network connection, VPN, or install authorization and retry.");
+}
+function formatDuration(ms) {
+    if (ms < 1000) {
+        return `${ms}ms`;
     }
-    await pipeline(Readable.fromWeb(response.body), createWriteStream(destination));
+    return `${Math.ceil(ms / 1000)}s`;
 }
 async function browserGoogleSignIn(timeoutMs = DEFAULT_INSTALL_AUTH_TIMEOUT_MS) {
     ensureWindowsHost();
@@ -3332,6 +3447,7 @@ function installEventOptions(options) {
         silent: options.silent,
         exePath: options.exePath,
         installTokenProvided: Boolean(options.installToken),
+        installTokenSource: options.installTokenSource,
     };
 }
 function serviceManifestEventSummary(manifest) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tapi-dev/sdk",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",