@tapi-dev/sdk 0.1.15 → 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,7 +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

@@ -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;
@@ -282,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;
@@ -324,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"),
@@ -1074,18 +1086,7 @@ 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 withCliSpinner("Checking Tapi Service install approval", () => 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,
@@ -1148,18 +1149,7 @@ async function installService(options) {
             arch: process.arch,
         });
         ensureWindowsHost();
-        let installToken = options.installToken?.trim();
-        if (!installToken) {
-            await event.phase("auth.install_token.request.start", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-            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,
-            });
-        }
+        const installToken = await ensureStudioInstallTokenForRun(options, event, "Checking Tapi Service install authorization");
         await event.phase("service_manifest.fetch.start", {
             apiBaseUrl: options.apiBaseUrl,
             channel: options.channel,
@@ -1202,6 +1192,7 @@ async function installService(options) {
         }
         const releaseDir = join(releasesDir, safePathSegment(manifest.version));
         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)) {
@@ -1243,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;
     }
@@ -1395,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"));
@@ -1716,24 +1713,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.");
         }
-        let installToken = options.installToken?.trim();
-        if (installToken) {
-            await event.phase("auth.install_token.provided", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-        }
-        else {
-            await event.phase("auth.install_token.request.start", {
-                apiBaseUrl: options.apiBaseUrl,
-                channel: options.channel,
-            });
-            installToken = await withCliSpinner("Checking Studio install approval", () => 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,
@@ -1852,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) {
@@ -1901,18 +1914,7 @@ 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 withCliSpinner("Checking Studio install approval", () => 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,
@@ -1928,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,
@@ -1972,14 +1974,13 @@ 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 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}`);
-    }
+    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;
 }
@@ -2493,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"));
@@ -2519,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, "_");
@@ -2526,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 {
@@ -2541,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,
@@ -2754,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
@@ -2763,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.15",
+  "version": "0.1.17",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",