@tapi-dev/sdk 0.1.12 → 0.1.15

package/dist/cli.d.ts

@@ -78,6 +78,13 @@ export declare function installedServiceVersionFromPathName(pathName: string): s
 export declare function serviceNeedsInstall(status: ServiceStatus, manifest: ServiceReleaseManifest): boolean;
 export declare function getDefaultStudioCacheDir(): string;
 export declare function getDefaultServiceCacheDir(): string;
+interface ServiceInstallLogPaths {
+    logPath: string;
+    resultPath: string;
+}
+export declare function getDefaultServiceInstallLogDir(): string;
+export declare function serviceInstallLogPaths(version: string, now?: Date): ServiceInstallLogPaths;
+export declare function formatServiceInstallFailure(error: unknown, paths: ServiceInstallLogPaths): Promise<string>;
 export declare class CliWideEvent {
     private readonly filePath;
     private readonly startedAt;
@@ -95,6 +102,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 findPortablePlaywrightBrowsersDir(exePath: string): string | undefined;
 export declare function waitForHttpOk(url: string, timeoutMs?: number, intervalMs?: number, fetchImpl?: FetchLike): Promise<void>;
 export declare function findPortableStudioServerExe(releaseDir: string, manifest: StudioReleaseManifest): string | undefined;
 export {};

package/dist/cli.js

@@ -3,8 +3,8 @@ import { spawn } from "node:child_process";
 import { createServer } from "node:http";
 import { createServer as createNetServer } from "node:net";
 import { createHash, randomUUID } from "node:crypto";
-import { createReadStream, createWriteStream, existsSync, readFileSync } from "node:fs";
-import { mkdir, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { createReadStream, createWriteStream, existsSync, readFileSync, readdirSync } from "node:fs";
+import { mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { performance } from "node:perf_hooks";
@@ -34,6 +34,75 @@ class StudioInstallApprovalError extends Error {
     }
 }
 const sdkVersion = readSdkVersion();
+const CLI_SPINNER_FRAMES = ["|", "/", "-", "\\"];
+function cliSpinnerEnabled() {
+    const noSpinner = (process.env.TAPI_NO_SPINNER || "").trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(noSpinner)) {
+        return false;
+    }
+    const spinner = (process.env.TAPI_CLI_SPINNER || "").trim().toLowerCase();
+    if (["0", "false", "no", "off"].includes(spinner)) {
+        return false;
+    }
+    return Boolean(process.stderr.isTTY);
+}
+class CliSpinner {
+    message;
+    frameIndex = 0;
+    lastLength = 0;
+    timer;
+    constructor(message) {
+        this.message = message;
+    }
+    start() {
+        if (this.timer) {
+            return;
+        }
+        this.render();
+        this.timer = setInterval(() => this.render(), 90);
+    }
+    succeed() {
+        this.stop("done");
+    }
+    fail() {
+        this.stop("failed");
+    }
+    render() {
+        const frame = CLI_SPINNER_FRAMES[this.frameIndex % CLI_SPINNER_FRAMES.length];
+        this.frameIndex += 1;
+        this.write(`${frame} ${this.message}`);
+    }
+    stop(status) {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        this.write(`${this.message} ${status}`);
+        process.stderr.write("\n");
+        this.lastLength = 0;
+    }
+    write(text) {
+        const padding = this.lastLength > text.length ? " ".repeat(this.lastLength - text.length) : "";
+        process.stderr.write(`\r${text}${padding}`);
+        this.lastLength = text.length;
+    }
+}
+async function withCliSpinner(message, work) {
+    if (!cliSpinnerEnabled()) {
+        return await work();
+    }
+    const spinner = new CliSpinner(message);
+    spinner.start();
+    try {
+        const result = await work();
+        spinner.succeed();
+        return result;
+    }
+    catch (error) {
+        spinner.fail();
+        throw error;
+    }
+}
 export async function runCli(argv = process.argv.slice(2)) {
     const [command, subcommand, ...rest] = argv;
     if (!command || command === "help" || command === "--help" || command === "-h") {
@@ -339,7 +408,7 @@ async function describeApiOperation(args) {
             apiKey: options.apiKey,
             projectId: options.projectId,
         });
-        const description = await client.websiteApis.describe(operation);
+        const description = await withCliSpinner(`Fetching Tapi API description for ${operation}`, () => client.websiteApis.describe(operation));
         console.log(JSON.stringify(description, null, 2));
         return 0;
     }
@@ -423,7 +492,7 @@ function parseApiWorkspaceOptions(args) {
 async function syncApiCatalog(args) {
     try {
         const options = parseApiWorkspaceOptions(args);
-        const catalog = await fetchApiCatalog(options);
+        const catalog = await withCliSpinner("Fetching Tapi API catalog", () => fetchApiCatalog(options));
         await writeJsonFile(options.catalogPath, catalog);
         console.log(`Synced Tapi API catalog: ${options.catalogPath}`);
         return 0;
@@ -436,7 +505,7 @@ async function syncApiCatalog(args) {
 async function generateApiClient(args) {
     try {
         const options = parseApiWorkspaceOptions(args);
-        const catalog = await fetchApiCatalog(options);
+        const catalog = await withCliSpinner("Fetching Tapi API catalog", () => fetchApiCatalog(options));
         await writeJsonFile(options.catalogPath, catalog);
         await writeTextFile(options.typescriptPath, renderGeneratedApiClient(catalog));
         console.log(`Generated Tapi API client: ${options.typescriptPath}`);
@@ -521,9 +590,11 @@ async function syncApiTriggers(args) {
             apiKey: options.apiKey,
             projectId: options.projectId,
         });
-        for (const trigger of triggers) {
-            await client.triggers.create(trigger);
-        }
+        await withCliSpinner(`Syncing ${triggers.length} Tapi API trigger(s)`, async () => {
+            for (const trigger of triggers) {
+                await client.triggers.create(trigger);
+            }
+        });
         console.log(`Synced ${triggers.length} Tapi API trigger(s) from ${options.configPath}.`);
         return 0;
     }
@@ -906,7 +977,7 @@ async function runServiceCommand(action, args = []) {
             return repairService(parseStudioOptions([]));
         }
         const command = servicePowerShell(normalized);
-        const output = await runProcessCapture("powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", command]);
+        const output = await withCliSpinner(`Running tapi-service ${normalized}`, () => runProcessCapture("powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", command]));
         if (output.trim()) {
             console.log(output.trim());
         }
@@ -918,7 +989,7 @@ async function runServiceCommand(action, args = []) {
     }
 }
 async function repairService(options) {
-    const status = await getServiceStatus();
+    const status = await withCliSpinner("Checking Tapi Service status", () => getServiceStatus());
     if (!status.installed) {
         return installService(options);
     }
@@ -964,7 +1035,7 @@ async function getServiceStatus() {
     }
 }
 async function ensureServiceReadyForStudio(options) {
-    const status = await getServiceStatus();
+    const status = await withCliSpinner("Checking Tapi Service status", () => getServiceStatus());
     if (!status.installed) {
         console.log("Tapi Service is required and is not installed. Installing it now...");
         const code = await installService(options);
@@ -985,13 +1056,13 @@ async function ensureServiceReadyForStudio(options) {
     }
     if (status.status !== "Running") {
         console.log("Starting Tapi Service...");
-        const output = await runProcessCapture("powershell.exe", [
+        const output = await withCliSpinner("Starting Tapi Service", () => runProcessCapture("powershell.exe", [
             "-NoProfile",
             "-ExecutionPolicy",
             "Bypass",
             "-Command",
             servicePowerShell("start"),
-        ]);
+        ]));
         if (output.trim()) {
             console.log(output.trim());
         }
@@ -1009,7 +1080,7 @@ async function fetchServiceManifestForEnsure(options) {
                 apiBaseUrl: options.apiBaseUrl,
                 channel: options.channel,
             });
-            installToken = await obtainStudioInstallToken(options, event);
+            installToken = await withCliSpinner("Checking Tapi Service install approval", () => obtainStudioInstallToken(options, event));
             await event.phase("auth.install_token.request.success", {
                 apiBaseUrl: options.apiBaseUrl,
                 channel: options.channel,
@@ -1019,7 +1090,7 @@ async function fetchServiceManifestForEnsure(options) {
             apiBaseUrl: options.apiBaseUrl,
             channel: options.channel,
         });
-        const manifest = await fetchProtectedServiceManifest(options.apiBaseUrl, options.channel, installToken);
+        const manifest = await withCliSpinner(`Fetching Tapi Service ${options.channel} manifest`, () => fetchProtectedServiceManifest(options.apiBaseUrl, options.channel, installToken));
         ensureCompatibleServiceManifest(manifest);
         await event.finish(true, {
             manifest: serviceManifestEventSummary(manifest),
@@ -1079,23 +1150,21 @@ async function installService(options) {
         ensureWindowsHost();
         let installToken = options.installToken?.trim();
         if (!installToken) {
-            console.log("Checking Tapi Service install approval...");
             await event.phase("auth.install_token.request.start", {
                 apiBaseUrl: options.apiBaseUrl,
                 channel: options.channel,
             });
-            installToken = await obtainStudioInstallToken(options, event);
+            installToken = await withCliSpinner("Checking Tapi Service install approval", () => obtainStudioInstallToken(options, event));
             await event.phase("auth.install_token.request.success", {
                 apiBaseUrl: options.apiBaseUrl,
                 channel: options.channel,
             });
         }
-        console.log(`Fetching Tapi Service ${options.channel} manifest...`);
         await event.phase("service_manifest.fetch.start", {
             apiBaseUrl: options.apiBaseUrl,
             channel: options.channel,
         });
-        const manifest = await fetchProtectedServiceManifest(options.apiBaseUrl, options.channel, installToken);
+        const manifest = await withCliSpinner(`Fetching Tapi Service ${options.channel} manifest`, () => fetchProtectedServiceManifest(options.apiBaseUrl, options.channel, installToken));
         await event.phase("service_manifest.fetch.success", {
             manifest: serviceManifestEventSummary(manifest),
         });
@@ -1112,13 +1181,12 @@ async function installService(options) {
             await event.phase("cache.hit", { zipPath });
         }
         else {
-            console.log(`Downloading Tapi Service ${manifest.version}...`);
             await event.phase("download.start", {
                 url: manifest.url,
                 destination: zipPath,
                 expectedSha256: manifest.sha256,
             });
-            await downloadAndVerify(manifest.url, zipPath, manifest.sha256, "Tapi Service artifact");
+            await withCliSpinner(`Downloading Tapi Service ${manifest.version}`, () => downloadAndVerify(manifest.url, zipPath, manifest.sha256, "Tapi Service artifact"));
             await event.phase("download.verified", {
                 zipPath,
                 expectedSha256: manifest.sha256,
@@ -1133,7 +1201,7 @@ async function installService(options) {
             return 0;
         }
         const releaseDir = join(releasesDir, safePathSegment(manifest.version));
-        await extractZip(zipPath, releaseDir);
+        await withCliSpinner(`Extracting Tapi Service ${manifest.version}`, () => extractZip(zipPath, releaseDir));
         const installer = join(releaseDir, manifest.installer || "install_tapi_service.ps1");
         const hostExe = join(releaseDir, manifest.serviceHostExecutable || "tapi-service-host.exe");
         if (!existsSync(installer)) {
@@ -1142,23 +1210,35 @@ async function installService(options) {
         if (!existsSync(hostExe)) {
             throw new Error(`Tapi Service host executable was not found after extraction: ${hostExe}`);
         }
-        console.log(`Installing Tapi Service ${manifest.version}...`);
+        const installLog = serviceInstallLogPaths(manifest.version);
+        await mkdir(dirname(installLog.logPath), { recursive: true });
         await event.phase("service_installer.start", {
             installer,
             hostExe,
             releaseDir,
+            logPath: installLog.logPath,
+            resultPath: installLog.resultPath,
         });
-        await runProcess("powershell.exe", [
-            "-NoProfile",
-            "-ExecutionPolicy",
-            "Bypass",
-            "-File",
-            installer,
-            "-ExecutablePath",
-            hostExe,
-            "-WorkingDirectory",
-            releaseDir,
-        ]);
+        try {
+            await withCliSpinner(`Installing Tapi Service ${manifest.version}`, () => runProcess("powershell.exe", [
+                "-NoProfile",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                installer,
+                "-ExecutablePath",
+                hostExe,
+                "-WorkingDirectory",
+                releaseDir,
+                "-LogPath",
+                installLog.logPath,
+                "-ResultPath",
+                installLog.resultPath,
+            ]));
+        }
+        catch (error) {
+            throw new Error(await formatServiceInstallFailure(error, installLog), { cause: error });
+        }
         await event.finish(true, {
             releaseDir,
             version: manifest.version,
@@ -1183,42 +1263,45 @@ async function publishLocalApis(args) {
         if (apis.length === 0) {
             throw new Error("No local generated APIs found under .tapi/apis.");
         }
-        let sitemapCount = 0;
-        for (const sitemap of sitemaps) {
-            const site = String(sitemap.site || "").trim();
-            if (!site || !isRecord(sitemap.siteMap)) {
-                continue;
-            }
-            await putJson(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/v1/sitemaps/${encodeURIComponent(site)}?project=${encodeURIComponent(options.projectId)}`, { site_map: sitemap.siteMap }, options.apiKey, options.projectId);
-            sitemapCount += 1;
-        }
-        let contracts = 0;
-        let requests = 0;
-        for (const api of apis) {
-            const apiId = String(api.id || api.name || "").trim();
-            if (!apiId) {
-                continue;
-            }
-            const site = String(api.site || "").trim();
-            await putJson(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/v1/generated-apis/contracts/${encodeURIComponent(apiId)}?project=${encodeURIComponent(options.projectId)}`, { generated_api: api }, options.apiKey, options.projectId);
-            contracts += 1;
-            const apiRequests = api.requests && typeof api.requests === "object" ? Object.values(api.requests) : [];
-            for (const request of apiRequests) {
-                if (!isRecord(request)) {
+        const { sitemapCount, contracts, requests, releaseVersion } = await withCliSpinner("Publishing local Tapi APIs", async () => {
+            let sitemapCount = 0;
+            for (const sitemap of sitemaps) {
+                const site = String(sitemap.site || "").trim();
+                if (!site || !isRecord(sitemap.siteMap)) {
                     continue;
                 }
-                const requestId = String(request.id || request.key || "").trim();
-                const status = String(request.status || "").trim();
-                if (!requestId || !["ready", "published"].includes(status)) {
+                await putJson(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/v1/sitemaps/${encodeURIComponent(site)}?project=${encodeURIComponent(options.projectId)}`, { site_map: sitemap.siteMap }, options.apiKey, options.projectId);
+                sitemapCount += 1;
+            }
+            let contracts = 0;
+            let requests = 0;
+            for (const api of apis) {
+                const apiId = String(api.id || api.name || "").trim();
+                if (!apiId) {
                     continue;
                 }
-                await postJson(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/v1/generated-apis/contracts/${encodeURIComponent(apiId)}/requests/${encodeURIComponent(requestId)}/publish?project=${encodeURIComponent(options.projectId)}`, { site }, options.apiKey, options.projectId);
-                requests += 1;
+                const site = String(api.site || "").trim();
+                await putJson(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/v1/generated-apis/contracts/${encodeURIComponent(apiId)}?project=${encodeURIComponent(options.projectId)}`, { generated_api: api }, options.apiKey, options.projectId);
+                contracts += 1;
+                const apiRequests = api.requests && typeof api.requests === "object" ? Object.values(api.requests) : [];
+                for (const request of apiRequests) {
+                    if (!isRecord(request)) {
+                        continue;
+                    }
+                    const requestId = String(request.id || request.key || "").trim();
+                    const status = String(request.status || "").trim();
+                    if (!requestId || !["ready", "published"].includes(status)) {
+                        continue;
+                    }
+                    await postJson(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/v1/generated-apis/contracts/${encodeURIComponent(apiId)}/requests/${encodeURIComponent(requestId)}/publish?project=${encodeURIComponent(options.projectId)}`, { site }, options.apiKey, options.projectId);
+                    requests += 1;
+                }
             }
-        }
-        const releaseResponse = await postJson(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/v1/generated-apis/releases?project=${encodeURIComponent(options.projectId)}`, { environment: "production" }, options.apiKey, options.projectId);
-        const release = isRecord(releaseResponse) && isRecord(releaseResponse.release) ? releaseResponse.release : {};
-        const releaseVersion = typeof release.version === "string" ? release.version : "unknown";
+            const releaseResponse = await postJson(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/v1/generated-apis/releases?project=${encodeURIComponent(options.projectId)}`, { environment: "production" }, options.apiKey, options.projectId);
+            const release = isRecord(releaseResponse) && isRecord(releaseResponse.release) ? releaseResponse.release : {};
+            const releaseVersion = typeof release.version === "string" ? release.version : "unknown";
+            return { sitemapCount, contracts, requests, releaseVersion };
+        });
         console.log(`Published ${requests} API request(s) from ${contracts} contract(s), synced ${sitemapCount} sitemap(s), activated release ${releaseVersion}.`);
         return 0;
     }
@@ -1327,6 +1410,76 @@ export function getDefaultServiceCacheDir() {
     }
     return join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "tapi", "service");
 }
+export function getDefaultServiceInstallLogDir() {
+    return join(getDefaultServiceCacheDir(), "logs");
+}
+export function serviceInstallLogPaths(version, now = new Date()) {
+    const stamp = now.toISOString().replace(/[:.]/g, "-");
+    const safeVersion = safePathSegment(version);
+    return {
+        logPath: join(getDefaultServiceInstallLogDir(), `install-${safeVersion}-${stamp}.log`),
+        resultPath: join(getDefaultServiceInstallLogDir(), `install-${safeVersion}-${stamp}.json`),
+    };
+}
+export async function formatServiceInstallFailure(error, paths) {
+    const lines = [
+        `Tapi Service installer failed: ${formatError(error)}`,
+        `Install log: ${paths.logPath}`,
+        `Install result: ${paths.resultPath}`,
+    ];
+    const result = await readServiceInstallResult(paths.resultPath);
+    if (result) {
+        const phase = installerStringField(result.phase);
+        const installError = installerStringField(result.error);
+        const exitCode = result.exitCode !== undefined ? String(result.exitCode) : "";
+        if (phase || exitCode) {
+            lines.push(`Installer result: phase=${phase || "unknown"} exitCode=${exitCode || "unknown"}`);
+        }
+        if (installError) {
+            lines.push(`Installer error: ${installError}`);
+        }
+        const resultLogPath = installerStringField(result.logPath);
+        if (resultLogPath && resultLogPath !== paths.logPath) {
+            lines.push(`Installer-reported log: ${resultLogPath}`);
+        }
+    }
+    const logText = await readTextFileIfExists(paths.logPath);
+    if (logText?.trim()) {
+        const tail = tailLines(logText, 30);
+        if (tail.length > 0) {
+            lines.push("Last installer log lines:");
+            lines.push(...tail.map((line) => `  ${line}`));
+        }
+    }
+    return lines.join("\n");
+}
+async function readServiceInstallResult(path) {
+    const text = await readTextFileIfExists(path);
+    if (!text) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readTextFileIfExists(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function installerStringField(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function tailLines(text, count) {
+    return text.split(/\r?\n/).filter((line) => line.trim()).slice(-count);
+}
 export class CliWideEvent {
     filePath;
     startedAt = performance.now();
@@ -1571,23 +1724,21 @@ async function installStudio(options) {
             });
         }
         else {
-            console.log("Checking Studio install approval...");
             await event.phase("auth.install_token.request.start", {
                 apiBaseUrl: options.apiBaseUrl,
                 channel: options.channel,
             });
-            installToken = await obtainStudioInstallToken(options, event);
+            installToken = await withCliSpinner("Checking Studio install approval", () => obtainStudioInstallToken(options, event));
             await event.phase("auth.install_token.request.success", {
                 apiBaseUrl: options.apiBaseUrl,
                 channel: options.channel,
             });
         }
-        console.log(`Fetching Tapi Studio ${options.channel} manifest...`);
         await event.phase("manifest.fetch.start", {
             apiBaseUrl: options.apiBaseUrl,
             channel: options.channel,
         });
-        const manifest = await fetchProtectedStudioManifest(options.apiBaseUrl, options.channel, installToken);
+        const manifest = await withCliSpinner(`Fetching Tapi Studio ${options.channel} manifest`, () => fetchProtectedStudioManifest(options.apiBaseUrl, options.channel, installToken));
         await event.phase("manifest.fetch.success", {
             manifest: manifestEventSummary(manifest),
         });
@@ -1619,13 +1770,12 @@ async function installStudio(options) {
         }
         else {
             await event.phase("cache.miss", { installerPath });
-            console.log(`Downloading Tapi Studio ${manifest.version}...`);
             await event.phase("download.start", {
                 url: manifest.url,
                 destination: installerPath,
                 expectedSha256: manifest.sha256,
             });
-            await downloadAndVerify(manifest.url, installerPath, manifest.sha256);
+            await withCliSpinner(`Downloading Tapi Studio ${manifest.version}`, () => downloadAndVerify(manifest.url, installerPath, manifest.sha256));
             await event.phase("download.verified", {
                 installerPath,
                 expectedSha256: manifest.sha256,
@@ -1640,12 +1790,11 @@ async function installStudio(options) {
             return 0;
         }
         const installerArgs = options.silent ? ["/S"] : [];
-        console.log(`Starting Tapi Studio installer: ${installerPath}`);
         await event.phase("installer.start", {
             installerPath,
             args: installerArgs,
         });
-        await runProcess(installerPath, installerArgs);
+        await withCliSpinner("Starting Tapi Studio installer", () => runProcess(installerPath, installerArgs));
         console.log("Tapi Studio installer finished.");
         await event.finish(true, {
             installerPath,
@@ -1712,7 +1861,7 @@ async function openStudio(options) {
     if (!options.exePath) {
         const portable = await ensurePortableStudioServer(options);
         if (portable) {
-            await launchPortableStudioServer(portable.exePath, options);
+            await launchPortableStudioServer(portable.exePath, options, portable.manifest);
             return 0;
         }
     }
@@ -1758,7 +1907,7 @@ async function ensurePortableStudioServer(options) {
                 apiBaseUrl: options.apiBaseUrl,
                 channel: options.channel,
             });
-            installToken = await obtainStudioInstallToken(options, event);
+            installToken = await withCliSpinner("Checking Studio install approval", () => obtainStudioInstallToken(options, event));
             await event.phase("auth.install_token.request.success", {
                 apiBaseUrl: options.apiBaseUrl,
                 channel: options.channel,
@@ -1768,7 +1917,7 @@ async function ensurePortableStudioServer(options) {
             apiBaseUrl: options.apiBaseUrl,
             channel: options.channel,
         });
-        const manifest = await fetchProtectedStudioManifest(options.apiBaseUrl, options.channel, installToken);
+        const manifest = await withCliSpinner(`Fetching Tapi Studio ${options.channel} manifest`, () => fetchProtectedStudioManifest(options.apiBaseUrl, options.channel, installToken));
         ensureCompatibleManifest(manifest);
         await event.phase("manifest.fetch.success", {
             manifest: manifestEventSummary(manifest),
@@ -1810,13 +1959,12 @@ async function installPortableStudioServer(options, manifest, event) {
         await event.phase("cache.hit", { artifactPath });
     }
     else {
-        console.log(`Downloading Tapi Studio server ${manifest.version}...`);
         await event.phase("download.start", {
             url: manifest.url,
             destination: artifactPath,
             expectedSha256: manifest.sha256,
         });
-        await downloadAndVerify(manifest.url, artifactPath, manifest.sha256, "Tapi Studio server artifact");
+        await withCliSpinner(`Downloading Tapi Studio server ${manifest.version}`, () => downloadAndVerify(manifest.url, artifactPath, manifest.sha256, "Tapi Studio server artifact"));
         await event.phase("download.verified", {
             artifactPath,
             expectedSha256: manifest.sha256,
@@ -1827,7 +1975,7 @@ async function installPortableStudioServer(options, manifest, event) {
         return artifactPath;
     }
     const releaseDir = portableStudioServerReleaseDir(manifest);
-    await extractZip(artifactPath, releaseDir);
+    await withCliSpinner(`Extracting Tapi Studio server ${manifest.version}`, () => extractZip(artifactPath, releaseDir));
     const exePath = findPortableStudioServerExe(releaseDir, manifest);
     if (!exePath) {
         throw new Error(`Tapi Studio server executable was not found after extraction: ${releaseDir}`);
@@ -1835,7 +1983,7 @@ async function installPortableStudioServer(options, manifest, event) {
     console.log(`Installed Tapi Studio server ${manifest.version}: ${releaseDir}`);
     return exePath;
 }
-async function launchPortableStudioServer(exePath, options) {
+async function launchPortableStudioServer(exePath, options, manifest) {
     const host = "127.0.0.1";
     const port = await chooseStudioPort();
     const env = buildStudioLaunchEnv(options);
@@ -1847,17 +1995,49 @@ async function launchPortableStudioServer(exePath, options) {
     env.TAPI_STUDIO_HOST = host;
     env.TAPI_STUDIO_PORT = String(port);
     env.TAPI_STUDIO_SERVER_PORT = String(port);
-    const child = spawn(exePath, [], {
-        detached: true,
-        env,
-        stdio: "ignore",
-        windowsHide: true,
-    });
-    child.unref();
+    env.TAPI_STUDIO_SERVER_VERSION = manifest.version;
+    env.TAPI_STUDIO_SERVER_COMMIT = manifest.commit || "";
+    env.TAPI_STUDIO_SERVER_COMMIT_SHORT = manifest.commitShort || manifest.version;
+    const playwrightBrowsersPath = findPortablePlaywrightBrowsersDir(exePath);
+    if (playwrightBrowsersPath) {
+        env.PLAYWRIGHT_BROWSERS_PATH = playwrightBrowsersPath;
+    }
     const url = `http://${host}:${port}`;
-    await waitForHttpOk(`${url}/healthz`, PORTABLE_STUDIO_SERVER_READY_TIMEOUT_MS, PORTABLE_STUDIO_SERVER_READY_INTERVAL_MS);
+    await withCliSpinner("Starting Tapi Studio", async () => {
+        const child = spawn(exePath, [], {
+            detached: true,
+            env,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        child.unref();
+        await waitForHttpOk(`${url}/healthz`, PORTABLE_STUDIO_SERVER_READY_TIMEOUT_MS, PORTABLE_STUDIO_SERVER_READY_INTERVAL_MS);
+    });
     openBrowser(url);
-    console.log(`Opened Tapi Studio: ${url}`);
+    console.log(`Opened Tapi Studio ${manifest.version}: ${url}`);
+}
+export function findPortablePlaywrightBrowsersDir(exePath) {
+    const exeDir = dirname(exePath);
+    const releaseDir = basename(exeDir).toLowerCase() === "tapi-studio-server"
+        ? dirname(exeDir)
+        : exeDir;
+    const candidates = [
+        join(releaseDir, "pw"),
+        join(releaseDir, "playwright-browsers"),
+        join(releaseDir, "sidecars", "pw"),
+        join(exeDir, "pw"),
+        join(exeDir, "playwright-browsers"),
+    ];
+    return candidates.find(isPlaywrightBrowsersDir);
+}
+function isPlaywrightBrowsersDir(path) {
+    try {
+        return existsSync(path)
+            && readdirSync(path, { withFileTypes: true }).some((entry) => entry.isDirectory() && entry.name.startsWith("chromium_headless_shell-"));
+    }
+    catch {
+        return false;
+    }
 }
 export async function waitForHttpOk(url, timeoutMs = PORTABLE_STUDIO_SERVER_READY_TIMEOUT_MS, intervalMs = PORTABLE_STUDIO_SERVER_READY_INTERVAL_MS, fetchImpl = fetch) {
     const startedAt = performance.now();
@@ -1915,7 +2095,7 @@ async function runDoctor(options) {
     const exePath = options.exePath ?? getStudioExecutableCandidates().find((candidate) => existsSync(candidate));
     console.log(`Studio executable: ${exePath && existsSync(exePath) ? exePath : "not found"}`);
     try {
-        const manifest = await fetchStudioManifest(options.manifestUrl);
+        const manifest = await withCliSpinner("Fetching latest Tapi Studio manifest", () => fetchStudioManifest(options.manifestUrl));
         ensureCompatibleManifest(manifest);
         console.log(`Latest Studio: ${manifest.version} (${manifest.platform})`);
     }

package/package.json

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