@tapi-dev/sdk 0.1.13 → 0.1.17

package/README.md

@@ -30,6 +30,23 @@ Studio executable is installed yet, `tapi studio` runs the installer first, then
 opens Studio. The normal developer path is the portable server launched by the
 CLI.
 
+By default, Studio downloads and extracted portable server releases live under
+the user's local app data directory. On Windows that is usually
+`%LOCALAPPDATA%\Tapi\Studio`. To keep the whole Studio install on another drive,
+set `TAPI_STUDIO_HOME` before launching:
+
+```powershell
+$env:TAPI_STUDIO_HOME="F:\Tapi\Studio"
+npx tapi studio
+```
+
+For separate paths, use `--cache-dir` for downloaded zip artifacts and
+`--install-dir` for extracted portable Studio server releases.
+
+After a successful install, the CLI prunes older Tapi-managed download artifacts
+from the cache and older SDK-marked release folders from the install directory.
+The current artifact and current release are kept.
+
 Useful commands:
 
 ```bash

package/dist/cli.d.ts

@@ -54,6 +54,7 @@ interface StudioCliOptions {
     manifestUrl: string;
     manifestUrlOverride?: string;
     cacheDir: string;
+    installDir: string;
     downloadOnly: boolean;
     silent: boolean;
     exePath?: string;
@@ -102,6 +103,13 @@ 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 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 declare function buildExpandArchiveCommand(zipPath: string, destination: string): string;
+export declare function formatZipExtractionFailure(zipPath: string, destination: string, error: unknown): string;
+export declare function pruneManagedFiles(directory: string, keepPaths: string[], isManagedFileName: (name: string) => boolean, maxNoncurrentEntries?: number, label?: string): Promise<number>;
+export declare function isTapiStudioDownloadArtifact(fileName: string): boolean;
+export declare function isTapiServiceDownloadArtifact(fileName: string): boolean;
 export {};

package/dist/cli.js

@@ -3,7 +3,7 @@ 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 { 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";
@@ -23,6 +23,9 @@ 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 MAX_WIDE_EVENT_PROCESS_ROOTS = 5;
+const MAX_NONCURRENT_MANAGED_DOWNLOADS = 0;
+const MAX_NONCURRENT_MANAGED_RELEASES = 0;
+const MANAGED_RELEASE_MARKER = ".tapi-managed-release";
 class StudioInstallApprovalError extends Error {
     code;
     status;
@@ -34,6 +37,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") {
@@ -213,6 +285,14 @@ export function parseStudioOptions(args) {
             raw.cacheDir = resolve(arg.slice("--cache-dir=".length));
             continue;
         }
+        if (arg === "--install-dir") {
+            raw.installDir = resolve(requireOptionValue(args, ++index, "--install-dir"));
+            continue;
+        }
+        if (arg.startsWith("--install-dir=")) {
+            raw.installDir = resolve(arg.slice("--install-dir=".length));
+            continue;
+        }
         if (arg === "--exe") {
             raw.exePath = resolve(requireOptionValue(args, ++index, "--exe"));
             continue;
@@ -255,6 +335,7 @@ export function parseStudioOptions(args) {
         manifestUrl,
         manifestUrlOverride: explicitManifestUrl ? normalizeHttpUrl(explicitManifestUrl, "Studio manifest URL") : undefined,
         cacheDir: raw.cacheDir ?? getDefaultStudioCacheDir(),
+        installDir: raw.installDir ?? resolve(envString("TAPI_STUDIO_INSTALL_DIR") ?? getDefaultPortableStudioServerReleasesDir()),
         downloadOnly: raw.downloadOnly ?? false,
         silent: raw.silent ?? false,
         exePath: raw.exePath ?? envString("TAPI_STUDIO_EXE"),
@@ -339,7 +420,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 +504,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 +517,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 +602,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 +989,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 +1001,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 +1047,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 +1068,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());
         }
@@ -1003,23 +1086,12 @@ async function fetchServiceManifestForEnsure(options) {
         options: installEventOptions(options),
     });
     try {
-        let installToken = options.installToken?.trim();
-        if (!installToken) {
-            await event.phase("auth.install_token.request.start", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-            installToken = await obtainStudioInstallToken(options, event);
-            await event.phase("auth.install_token.request.success", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-        }
+        const installToken = await ensureStudioInstallTokenForRun(options, event, "Checking Tapi Service install authorization");
         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));
         ensureCompatibleServiceManifest(manifest);
         await event.finish(true, {
             manifest: serviceManifestEventSummary(manifest),
@@ -1077,25 +1149,12 @@ async function installService(options) {
             arch: process.arch,
         });
         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);
-            await event.phase("auth.install_token.request.success", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-        }
-        console.log(`Fetching Tapi Service ${options.channel} manifest...`);
+        const installToken = await ensureStudioInstallTokenForRun(options, event, "Checking Tapi Service install authorization");
         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 +1171,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 +1191,8 @@ 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));
+        await markManagedReleaseDir(releaseDir, manifest.version);
         const installer = join(releaseDir, manifest.installer || "install_tapi_service.ps1");
         const hostExe = join(releaseDir, manifest.serviceHostExecutable || "tapi-service-host.exe");
         if (!existsSync(installer)) {
@@ -1144,7 +1203,6 @@ async function installService(options) {
         }
         const installLog = serviceInstallLogPaths(manifest.version);
         await mkdir(dirname(installLog.logPath), { recursive: true });
-        console.log(`Installing Tapi Service ${manifest.version}...`);
         await event.phase("service_installer.start", {
             installer,
             hostExe,
@@ -1153,7 +1211,7 @@ async function installService(options) {
             resultPath: installLog.resultPath,
         });
         try {
-            await runProcess("powershell.exe", [
+            await withCliSpinner(`Installing Tapi Service ${manifest.version}`, () => runProcess("powershell.exe", [
                 "-NoProfile",
                 "-ExecutionPolicy",
                 "Bypass",
@@ -1167,7 +1225,7 @@ async function installService(options) {
                 installLog.logPath,
                 "-ResultPath",
                 installLog.resultPath,
-            ]);
+            ]));
         }
         catch (error) {
             throw new Error(await formatServiceInstallFailure(error, installLog), { cause: error });
@@ -1176,6 +1234,8 @@ async function installService(options) {
             releaseDir,
             version: manifest.version,
         });
+        await pruneManagedFiles(downloadsDir, [zipPath], isTapiServiceDownloadArtifact, MAX_NONCURRENT_MANAGED_DOWNLOADS, "old Tapi Service download");
+        await pruneManagedDirs(releasesDir, [releaseDir], isSafeManagedReleaseDirName, MAX_NONCURRENT_MANAGED_RELEASES, "old Tapi Service release");
         console.log("Tapi Service is installed and running.");
         return 0;
     }
@@ -1196,42 +1256,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;
     }
@@ -1325,6 +1388,10 @@ async function requestJson(method, url, body, apiKey, projectId) {
     }
 }
 export function getDefaultStudioCacheDir() {
+    const homeOverride = envString("TAPI_STUDIO_HOME");
+    if (homeOverride) {
+        return join(resolve(homeOverride), "downloads");
+    }
     if (process.platform === "win32") {
         const localAppData = process.env.LOCALAPPDATA ??
             (process.env.USERPROFILE ? join(process.env.USERPROFILE, "AppData", "Local") : join(homedir(), "AppData", "Local"));
@@ -1646,31 +1713,12 @@ 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.");
         }
-        let installToken = options.installToken?.trim();
-        if (installToken) {
-            await event.phase("auth.install_token.provided", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-        }
-        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);
-            await event.phase("auth.install_token.request.success", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-        }
-        console.log(`Fetching Tapi Studio ${options.channel} manifest...`);
+        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 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),
         });
@@ -1702,13 +1750,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,
@@ -1723,12 +1770,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,
@@ -1786,6 +1832,39 @@ async function obtainStudioInstallToken(options, event) {
     const issued = await requestStudioInstallToken(options.apiBaseUrl, options.channel, firebaseCreds.idToken);
     return issued.installToken;
 }
+export function memoizeStudioInstallToken(options, installToken) {
+    const existing = options.installToken?.trim();
+    if (existing) {
+        options.installToken = existing;
+        return existing;
+    }
+    const normalized = installToken?.trim() ?? "";
+    if (normalized) {
+        options.installToken = normalized;
+    }
+    return normalized;
+}
+async function ensureStudioInstallTokenForRun(options, event, message) {
+    const existing = memoizeStudioInstallToken(options);
+    if (existing) {
+        await event.phase("auth.install_token.reused", {
+            apiBaseUrl: options.apiBaseUrl,
+            channel: options.channel,
+        });
+        return existing;
+    }
+    await event.phase("auth.install_token.request.start", {
+        apiBaseUrl: options.apiBaseUrl,
+        channel: options.channel,
+    });
+    const installToken = memoizeStudioInstallToken(options, await withCliSpinner(message, () => obtainStudioInstallToken(options, event)));
+    await event.phase("auth.install_token.request.success", {
+        apiBaseUrl: options.apiBaseUrl,
+        channel: options.channel,
+        cachedForRun: true,
+    });
+    return installToken;
+}
 async function openStudio(options) {
     ensureWindowsHost();
     if (options.downloadOnly) {
@@ -1795,7 +1874,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;
         }
     }
@@ -1835,23 +1914,12 @@ async function ensurePortableStudioServer(options) {
         options: installEventOptions(options),
     });
     try {
-        let installToken = options.installToken?.trim();
-        if (!installToken) {
-            await event.phase("auth.install_token.request.start", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-            installToken = await obtainStudioInstallToken(options, event);
-            await event.phase("auth.install_token.request.success", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-        }
+        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 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),
@@ -1862,7 +1930,7 @@ async function ensurePortableStudioServer(options) {
             });
             return null;
         }
-        const existing = findPortableStudioServerExe(portableStudioServerReleaseDir(manifest), manifest);
+        const existing = findPortableStudioServerExe(portableStudioServerReleaseDir(manifest, options.installDir), manifest);
         if (existing) {
             await event.finish(true, {
                 serverExe: existing,
@@ -1893,13 +1961,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,
@@ -1907,18 +1974,17 @@ async function installPortableStudioServer(options, manifest, event) {
     }
     if (options.downloadOnly) {
         console.log(`Downloaded Tapi Studio server artifact: ${artifactPath}`);
+        await pruneManagedFiles(options.cacheDir, [artifactPath], isTapiStudioDownloadArtifact, MAX_NONCURRENT_MANAGED_DOWNLOADS, "old Tapi Studio download");
         return artifactPath;
     }
-    const releaseDir = portableStudioServerReleaseDir(manifest);
-    await extractZip(artifactPath, releaseDir);
-    const exePath = findPortableStudioServerExe(releaseDir, manifest);
-    if (!exePath) {
-        throw new Error(`Tapi Studio server executable was not found after extraction: ${releaseDir}`);
-    }
+    const releaseDir = portableStudioServerReleaseDir(manifest, options.installDir);
+    const exePath = await withCliSpinner(`Extracting Tapi Studio server ${manifest.version}`, () => extractPortableStudioServerZip(artifactPath, releaseDir, manifest));
+    await pruneManagedFiles(options.cacheDir, [artifactPath], isTapiStudioDownloadArtifact, MAX_NONCURRENT_MANAGED_DOWNLOADS, "old Tapi Studio download");
+    await pruneManagedDirs(dirname(releaseDir), [releaseDir], isSafeManagedReleaseDirName, MAX_NONCURRENT_MANAGED_RELEASES, "old Tapi Studio server release");
     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);
@@ -1930,17 +1996,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();
@@ -1998,7 +2096,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})`);
     }
@@ -2396,10 +2494,14 @@ function isPortableStudioServerManifest(manifest) {
     const kind = String(manifest.installerKind || "").toLowerCase();
     return kind === "portable-server" || manifest.artifactName.toLowerCase().endsWith(".zip");
 }
-function portableStudioServerReleaseDir(manifest) {
-    return join(getDefaultPortableStudioServerReleasesDir(), safePathSegment(manifest.version));
+function portableStudioServerReleaseDir(manifest, releasesDir = getDefaultPortableStudioServerReleasesDir()) {
+    return join(releasesDir, safePathSegment(manifest.version));
 }
 function getDefaultPortableStudioServerReleasesDir() {
+    const homeOverride = envString("TAPI_STUDIO_HOME");
+    if (homeOverride) {
+        return join(resolve(homeOverride), "server", "releases");
+    }
     if (process.platform === "win32") {
         const localAppData = process.env.LOCALAPPDATA ??
             (process.env.USERPROFILE ? join(process.env.USERPROFILE, "AppData", "Local") : join(homedir(), "AppData", "Local"));
@@ -2422,6 +2524,34 @@ export function findPortableStudioServerExe(releaseDir, manifest) {
     ];
     return candidates.find((candidate) => existsSync(candidate));
 }
+async function extractPortableStudioServerZip(zipPath, releaseDir, manifest) {
+    const stagingDir = `${releaseDir}.extracting-${process.pid}-${Date.now()}`;
+    const existingExe = findPortableStudioServerExe(releaseDir, manifest);
+    if (!existingExe) {
+        await rm(releaseDir, { recursive: true, force: true });
+    }
+    await rm(stagingDir, { recursive: true, force: true });
+    try {
+        await extractZip(zipPath, stagingDir);
+        const stagedExe = findPortableStudioServerExe(stagingDir, manifest);
+        if (!stagedExe) {
+            throw new Error(`Tapi Studio server executable was not found after extraction. Expected ${manifest.serverExecutable || "tapi-studio-server.exe"} under ${stagingDir}.`);
+        }
+        await rm(releaseDir, { recursive: true, force: true });
+        await mkdir(dirname(releaseDir), { recursive: true });
+        await rename(stagingDir, releaseDir);
+        await markManagedReleaseDir(releaseDir, manifest.version);
+        const finalExe = findPortableStudioServerExe(releaseDir, manifest);
+        if (!finalExe) {
+            throw new Error(`Tapi Studio server executable disappeared while finalizing extraction: ${releaseDir}`);
+        }
+        return finalExe;
+    }
+    catch (error) {
+        await rm(stagingDir, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+}
 function cachedServiceArtifactName(manifest) {
     const rawName = manifest.artifactName || basename(new URL(manifest.url).pathname) || `TapiService-${manifest.version}.zip`;
     return rawName.replace(/[^A-Za-z0-9._-]/g, "_");
@@ -2429,13 +2559,141 @@ function cachedServiceArtifactName(manifest) {
 async function extractZip(zipPath, destination) {
     await rm(destination, { recursive: true, force: true });
     await mkdir(destination, { recursive: true });
-    await runProcessCapture("powershell.exe", [
-        "-NoProfile",
-        "-ExecutionPolicy",
-        "Bypass",
-        "-Command",
-        `Expand-Archive -LiteralPath ${powerShellSingleQuoted(zipPath)} -DestinationPath ${powerShellSingleQuoted(destination)} -Force`,
-    ]);
+    try {
+        await runProcessCapture("powershell.exe", [
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-Command",
+            buildExpandArchiveCommand(zipPath, destination),
+        ]);
+    }
+    catch (error) {
+        throw new Error(formatZipExtractionFailure(zipPath, destination, error), { cause: error });
+    }
+}
+export function buildExpandArchiveCommand(zipPath, destination) {
+    return `$ErrorActionPreference = 'Stop'; try { Expand-Archive -LiteralPath ${powerShellSingleQuoted(zipPath)} -DestinationPath ${powerShellSingleQuoted(destination)} -Force -ErrorAction Stop } catch { Write-Error $_; exit 1 }`;
+}
+export function formatZipExtractionFailure(zipPath, destination, error) {
+    const detail = formatError(error);
+    const diskHint = /not enough space|no space left|disk full/i.test(detail)
+        ? " Free disk space on that drive, or set TAPI_STUDIO_HOME / --cache-dir / --install-dir to paths on a drive with more room."
+        : "";
+    return `Failed to extract archive ${zipPath} to ${destination}: ${detail}${diskHint}`;
+}
+export async function pruneManagedFiles(directory, keepPaths, isManagedFileName, maxNoncurrentEntries = 0, label = "old Tapi download") {
+    const keep = normalizedKeepPathSet(keepPaths);
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    const candidates = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !isManagedFileName(entry.name)) {
+            continue;
+        }
+        const candidate = join(directory, entry.name);
+        if (keep.has(normalizeFilesystemPath(candidate))) {
+            continue;
+        }
+        const info = await stat(candidate).catch(() => undefined);
+        if (!info?.isFile()) {
+            continue;
+        }
+        candidates.push({ path: candidate, mtimeMs: info.mtimeMs });
+    }
+    candidates.sort((left, right) => right.mtimeMs - left.mtimeMs);
+    const removable = candidates.slice(Math.max(0, maxNoncurrentEntries));
+    let removed = 0;
+    for (const candidate of removable) {
+        try {
+            await rm(candidate.path, { force: true });
+            removed += 1;
+        }
+        catch {
+            // Cache pruning is best effort; install success should not depend on cleanup.
+        }
+    }
+    if (removed > 0) {
+        console.log(`Pruned ${removed} ${label}${removed === 1 ? "" : "s"}.`);
+    }
+    return removed;
+}
+async function pruneManagedDirs(directory, keepPaths, isManagedDirName, maxNoncurrentEntries = 0, label = "old Tapi release") {
+    const keep = normalizedKeepPathSet(keepPaths);
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    const candidates = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !isManagedDirName(entry.name)) {
+            continue;
+        }
+        const candidate = join(directory, entry.name);
+        if (keep.has(normalizeFilesystemPath(candidate))) {
+            continue;
+        }
+        if (!existsSync(join(candidate, MANAGED_RELEASE_MARKER))) {
+            continue;
+        }
+        const info = await stat(candidate).catch(() => undefined);
+        if (!info?.isDirectory()) {
+            continue;
+        }
+        candidates.push({ path: candidate, mtimeMs: info.mtimeMs });
+    }
+    candidates.sort((left, right) => right.mtimeMs - left.mtimeMs);
+    const removable = candidates.slice(Math.max(0, maxNoncurrentEntries));
+    let removed = 0;
+    for (const candidate of removable) {
+        try {
+            await rm(candidate.path, { recursive: true, force: true });
+            removed += 1;
+        }
+        catch {
+            // Cache pruning is best effort; install success should not depend on cleanup.
+        }
+    }
+    if (removed > 0) {
+        console.log(`Pruned ${removed} ${label}${removed === 1 ? "" : "s"}.`);
+    }
+    return removed;
+}
+export function isTapiStudioDownloadArtifact(fileName) {
+    const normalized = fileName.toLowerCase();
+    return (normalized.endsWith(".zip")
+        && (normalized.startsWith("tapi-studio")
+            || normalized.startsWith("tapistudio")
+            || normalized.includes("tapi_studio")));
+}
+export function isTapiServiceDownloadArtifact(fileName) {
+    const normalized = fileName.toLowerCase();
+    return normalized.endsWith(".zip") && (normalized.startsWith("tapiservice-") || normalized.startsWith("tapi-service"));
+}
+function isSafeManagedReleaseDirName(name) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name);
+}
+async function markManagedReleaseDir(directory, version) {
+    const payload = JSON.stringify({
+        product: "tapi",
+        version,
+        managedBy: "@tapi-dev/sdk",
+    });
+    await writeFile(join(directory, MANAGED_RELEASE_MARKER), `${payload}\n`).catch(() => undefined);
+}
+function normalizedKeepPathSet(paths) {
+    return new Set(paths.map((path) => normalizeFilesystemPath(path)));
+}
+function normalizeFilesystemPath(path) {
+    return resolve(path).replace(/\\/g, "/").toLowerCase();
 }
 function installEventOptions(options) {
     return {
@@ -2444,6 +2702,7 @@ function installEventOptions(options) {
         manifestUrl: options.manifestUrl,
         manifestUrlOverride: options.manifestUrlOverride,
         cacheDir: options.cacheDir,
+        installDir: options.installDir,
         downloadOnly: options.downloadOnly,
         silent: options.silent,
         exePath: options.exePath,
@@ -2657,7 +2916,7 @@ Usage:
 
 Options:
   --channel <name>       Release channel: pilot, stable, or nightly
-  --api-base-url <url>   Tapi API base URL for approval and protected downloads
+  --api-base-url <url>   Tapi API base URL for install authorization and protected downloads
   --server <url>         Alias for --api-base-url
   --workspace <path>     Search this directory for .tapi/project.json
   --no-workspace         Do not load .tapi/project.json
@@ -2666,6 +2925,7 @@ Options:
   --install-token <tok>  Preissued Studio install token (skips browser sign-in)
   --manifest <url>       Exact release manifest URL for doctor only
   --cache-dir <path>     Installer download cache directory
+  --install-dir <path>   Portable Studio server release directory
   --download-only        Download and verify without running the installer
   --silent               Run the NSIS installer with /S
   --exe <path>           Tapi Studio executable path for open/doctor

package/package.json

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