@tapi-dev/sdk 0.1.21 → 0.1.25

package/README.md

@@ -63,19 +63,18 @@ tapi sessions
 tapi publish
 ```
 
-Local authoring files live in the app repo:
-
-```text
-.tapi/project.json
-.tapi/sitemaps/<site>.json
-.tapi/apis/<site>/<api>.json
-.tapi/generated/catalog.json
-src/tapi.generated.ts
-```
-
-Drafts are local. `tapi publish` uploads local sitemaps and API contracts, marks
-ready requests as published, and activates one immutable server release. Runtime
-SDK calls read the active release catalog, not mutable Studio drafts.
+Local project identity lives in the app repo:
+
+```text
+.tapi/project.json
+.tapi/generated/catalog.json
+src/tapi.generated.ts
+```
+
+Sitemaps and API contracts are saved in the bound Tapi server project. Run
+`tapi publish` to mark ready server-side requests as published and activate one
+immutable server release. Runtime SDK calls read the active release catalog, not
+mutable Studio drafts.
 
 ```bash
 TAPI_API_KEY=tapi_project_key tapi publish

package/dist/cli.d.ts

@@ -75,6 +75,8 @@ export interface ServiceStatus {
     installedVersion?: string;
 }
 export type FetchLike = typeof fetch;
+type StudioPortAvailable = (port: number) => Promise<boolean>;
+type StudioPortReaper = (preferred: number, count: number) => Promise<number>;
 export declare function runCli(argv?: string[]): Promise<number>;
 export declare function parseStudioOptions(args: string[]): StudioCliOptions;
 export declare function trySelectDevSessionInOpenStudio(session: TapiDevSession, options: StudioCliOptions, fetchImpl?: FetchLike): Promise<{
@@ -86,6 +88,7 @@ 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;
+export declare function getDefaultMachineServiceReleasesDir(): string | undefined;
 interface ServiceInstallLogPaths {
     logPath: string;
     resultPath: string;
@@ -111,13 +114,26 @@ export declare function validateStudioManifest(input: unknown): StudioReleaseMan
 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 tryOpenExistingPortableStudioServer(options: StudioCliOptions, manifest: StudioReleaseManifest, fetchImpl?: FetchLike, openBrowserImpl?: (url: string) => void): Promise<{
+    opened: boolean;
+    baseUrl?: string;
+    reason?: 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 chooseStudioPort(preferred?: number, options?: {
+    count?: number;
+    portAvailable?: StudioPortAvailable;
+    reapBlockedPorts?: StudioPortReaper;
+}): Promise<number>;
 export declare function studioInstanceRecordPathForOptions(options: StudioCliOptions): string;
 export declare function findPortableStudioServerExe(releaseDir: string, manifest: StudioReleaseManifest): string | undefined;
+export declare function estimateRequiredExtractionBytes(zipBytes: number): number;
+export declare function formatInsufficientExtractionSpace(zipPath: string, destination: string, availableBytes: number, requiredBytes: number): string;
 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 pruneTapiReleaseDirs(directory: string, keepPaths: string[], isManagedDirName: (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

@@ -4,7 +4,7 @@ import { createServer } from "node:http";
 import { createServer as createNetServer } from "node:net";
 import { createHash, randomUUID } from "node:crypto";
 import { createReadStream, createWriteStream, existsSync, readFileSync, readdirSync } from "node:fs";
-import { mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, rm, stat, statfs, 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";
@@ -27,6 +27,8 @@ 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";
+const MIN_EXTRACTION_REQUIRED_BYTES = 1024 * 1024 * 1024;
+const EXTRACTION_REQUIRED_MULTIPLIER = 3;
 class StudioInstallApprovalError extends Error {
     code;
     status;
@@ -138,13 +140,6 @@ export async function runCli(argv = process.argv.slice(2)) {
         }
         return runServiceCommand(subcommand, rest);
     }
-    if (command === "publish") {
-        if (hasHelpFlag([subcommand, ...rest])) {
-            printPublishHelp();
-            return 0;
-        }
-        return publishLocalApis([subcommand, ...rest].filter(Boolean));
-    }
     if (command === "apis") {
         if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h" || hasHelpFlag(rest)) {
             printApisHelp();
@@ -438,7 +433,7 @@ async function describeApiOperation(args) {
             apiKey: options.apiKey,
             projectId: options.projectId,
         });
-        const description = await withCliSpinner(`Fetching Tapi API description for ${operation}`, () => client.websiteApis.describe(operation));
+        const description = await withCliSpinner(`Fetching Tapi API description for ${operation}`, () => client.services.describe(operation));
         console.log(JSON.stringify(description, null, 2));
         return 0;
     }
@@ -1215,7 +1210,7 @@ function renderGeneratedApiClient(catalog) {
         }
     }
     const namespaceBlocks = [...namespaces.entries()].map(([namespace, operations]) => {
-        const lines = operations.map(({ key, operationName }) => `    ${operationName}: (inputs: Record<string, unknown> = {}, options: GeneratedRunOptions = {}) => client.websiteApis.run(${JSON.stringify(key)}, { ...options, inputs }),`);
+        const lines = operations.map(({ key, operationName }) => `    ${operationName}: (inputs: Record<string, unknown> = {}, options: GeneratedRunOptions = {}) => client.services.run(${JSON.stringify(key)}, { ...options, inputs }),`);
         return `  ${namespace}: {\n${lines.join("\n")}\n  },`;
     });
     return `/* Generated by Tapi. Do not edit by hand. */
@@ -1521,12 +1516,26 @@ async function installService(options) {
             manifest: serviceManifestEventSummary(manifest),
         });
         ensureCompatibleServiceManifest(manifest);
+        const serviceStatus = await getServiceStatus().catch(() => ({
+            installed: false,
+            name: "tapi-service",
+            status: "unknown",
+        }));
         const serviceCacheDir = getDefaultServiceCacheDir();
         const downloadsDir = join(serviceCacheDir, "downloads");
         const releasesDir = join(serviceCacheDir, "releases");
         await mkdir(downloadsDir, { recursive: true });
         await mkdir(releasesDir, { recursive: true });
         const zipPath = join(downloadsDir, cachedServiceArtifactName(manifest));
+        const releaseDir = join(releasesDir, safePathSegment(manifest.version));
+        await pruneServiceInstallStorageBeforeDownload({
+            downloadsDir,
+            zipPath,
+            releasesDir,
+            releaseDir,
+            manifestVersion: manifest.version,
+            installedVersion: serviceStatus.installedVersion,
+        });
         const verified = await hasVerifiedCachedInstaller(zipPath, manifest.sha256);
         if (verified) {
             console.log(`Using cached Tapi Service artifact: ${zipPath}`);
@@ -1552,7 +1561,8 @@ async function installService(options) {
             });
             return 0;
         }
-        const releaseDir = join(releasesDir, safePathSegment(manifest.version));
+        await pruneManagedFiles(downloadsDir, [zipPath], isTapiServiceDownloadArtifact, MAX_NONCURRENT_MANAGED_DOWNLOADS, "old Tapi Service download");
+        await pruneTapiReleaseDirs(releasesDir, [releaseDir], isSafeManagedReleaseDirName, MAX_NONCURRENT_MANAGED_RELEASES, "old Tapi Service release");
         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");
@@ -1597,7 +1607,7 @@ async function installService(options) {
             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");
+        await pruneTapiReleaseDirs(releasesDir, [releaseDir], isSafeManagedReleaseDirName, MAX_NONCURRENT_MANAGED_RELEASES, "old Tapi Service release");
         console.log("Tapi Service is installed and running.");
         return 0;
     }
@@ -1608,147 +1618,6 @@ async function installService(options) {
         throw error;
     }
 }
-async function publishLocalApis(args) {
-    try {
-        const options = parseApiWorkspaceOptions(args);
-        const workspace = loadWorkspace();
-        const root = workspace?.root || process.cwd();
-        const sitemaps = await readLocalSitemaps(join(root, ".tapi", "sitemaps"));
-        const apis = await readLocalGeneratedApis(join(root, ".tapi", "apis"));
-        if (apis.length === 0) {
-            throw new Error("No local generated APIs found under .tapi/apis.");
-        }
-        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;
-                }
-                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)) {
-                        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";
-            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;
-    }
-    catch (error) {
-        console.error(formatError(error));
-        return 1;
-    }
-}
-async function readLocalSitemaps(root) {
-    const sitemaps = [];
-    if (!existsSync(root)) {
-        return sitemaps;
-    }
-    const entries = await readdir(root, { withFileTypes: true });
-    for (const entry of entries) {
-        if (!entry.isFile() || !entry.name.endsWith(".json")) {
-            continue;
-        }
-        const path = join(root, entry.name);
-        try {
-            const payload = JSON.parse(readFileSync(path, "utf8"));
-            if (!isRecord(payload) || !isRecord(payload.siteMap)) {
-                continue;
-            }
-            const site = String(payload.site || payload.siteMap.site || "").trim();
-            if (site) {
-                sitemaps.push({ site, siteMap: payload.siteMap });
-            }
-        }
-        catch {
-            continue;
-        }
-    }
-    return sitemaps;
-}
-async function readLocalGeneratedApis(root) {
-    const apis = [];
-    if (!existsSync(root)) {
-        return apis;
-    }
-    const entries = await readdir(root, { withFileTypes: true });
-    for (const entry of entries) {
-        const path = join(root, entry.name);
-        if (entry.isDirectory()) {
-            apis.push(...await readLocalGeneratedApis(path));
-            continue;
-        }
-        if (!entry.isFile() || !entry.name.endsWith(".json")) {
-            continue;
-        }
-        try {
-            const payload = JSON.parse(readFileSync(path, "utf8"));
-            if (isRecord(payload) && isRecord(payload.api)) {
-                apis.push(payload.api);
-            }
-        }
-        catch {
-            continue;
-        }
-    }
-    return apis;
-}
-async function putJson(url, body, apiKey, projectId) {
-    return requestJson("PUT", url, body, apiKey, projectId);
-}
-async function postJson(url, body, apiKey, projectId) {
-    return requestJson("POST", url, body, apiKey, projectId);
-}
-async function requestJson(method, url, body, apiKey, projectId) {
-    const response = await fetch(url, {
-        method,
-        headers: {
-            Authorization: `Bearer ${apiKey}`,
-            "Content-Type": "application/json",
-            "X-Tapi-Project": projectId,
-        },
-        body: JSON.stringify(body),
-    });
-    const text = await response.text();
-    if (!response.ok) {
-        throw new Error(`Tapi publish request failed: HTTP ${response.status} ${text}`);
-    }
-    if (!text.trim()) {
-        return {};
-    }
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return {};
-    }
-}
 export function getDefaultStudioCacheDir() {
     const homeOverride = envString("TAPI_STUDIO_HOME");
     if (homeOverride) {
@@ -1769,6 +1638,27 @@ export function getDefaultServiceCacheDir() {
     }
     return join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "tapi", "service");
 }
+export function getDefaultMachineServiceReleasesDir() {
+    if (process.platform !== "win32") {
+        return undefined;
+    }
+    const programData = process.env.PROGRAMDATA?.trim() || "C:\\ProgramData";
+    return join(programData, "Tapi", "Service", "releases");
+}
+async function pruneServiceInstallStorageBeforeDownload(options) {
+    await pruneManagedFiles(options.downloadsDir, [options.zipPath], isTapiServiceDownloadArtifact, MAX_NONCURRENT_MANAGED_DOWNLOADS, "old Tapi Service download");
+    await rm(options.releaseDir, { recursive: true, force: true }).catch(() => undefined);
+    await pruneTapiReleaseDirs(options.releasesDir, [options.releaseDir], isSafeManagedReleaseDirName, MAX_NONCURRENT_MANAGED_RELEASES, "old Tapi Service release");
+    const machineReleasesDir = getDefaultMachineServiceReleasesDir();
+    if (!machineReleasesDir) {
+        return;
+    }
+    const keepPaths = [join(machineReleasesDir, safePathSegment(options.manifestVersion))];
+    if (options.installedVersion) {
+        keepPaths.push(join(machineReleasesDir, safePathSegment(options.installedVersion)));
+    }
+    await pruneTapiReleaseDirs(machineReleasesDir, keepPaths, isSafeManagedReleaseDirName, MAX_NONCURRENT_MANAGED_RELEASES, "old machine-scope Tapi Service release");
+}
 export function getDefaultServiceInstallLogDir() {
     return join(getDefaultServiceCacheDir(), "logs");
 }
@@ -2236,6 +2126,10 @@ async function openStudio(options) {
     if (!options.exePath) {
         const portable = await ensurePortableStudioServer(options);
         if (portable) {
+            const existing = await tryOpenExistingPortableStudioServer(options, portable.manifest);
+            if (existing.opened) {
+                return 0;
+            }
             await launchPortableStudioServer(portable.exePath, options, portable.manifest);
             return 0;
         }
@@ -2270,6 +2164,34 @@ function findStudioExecutable(options) {
     }
     return getStudioExecutableCandidates().find((candidate) => existsSync(candidate));
 }
+export async function tryOpenExistingPortableStudioServer(options, manifest, fetchImpl = fetch, openBrowserImpl = openBrowser) {
+    const record = await readStudioInstanceRecord(options);
+    if (!record) {
+        return { opened: false, reason: "instance_record_missing" };
+    }
+    if ((record.manifestVersion || "") !== manifest.version) {
+        return { opened: false, reason: "manifest_version_mismatch" };
+    }
+    try {
+        const identityResponse = await fetchWithTimeout(`${record.baseUrl.replace(/\/+$/, "")}/api/studio/control/identity`, { headers: { Accept: "application/json" } }, 1_000, fetchImpl);
+        if (!identityResponse.ok) {
+            await unlinkIfExists(studioInstanceRecordPathForOptions(options));
+            return { opened: false, reason: `identity_http_${identityResponse.status}` };
+        }
+        const identity = await readJsonBody(identityResponse);
+        if (!studioInstanceIdentityMatches(identity, options)) {
+            return { opened: false, reason: "identity_mismatch" };
+        }
+        const launchUrl = studioLaunchUrl(record.baseUrl, options);
+        openBrowserImpl(launchUrl);
+        console.log(`Opened existing Tapi Studio ${record.manifestVersion || manifest.version}: ${launchUrl}`);
+        return { opened: true, baseUrl: record.baseUrl };
+    }
+    catch (error) {
+        await unlinkIfExists(studioInstanceRecordPathForOptions(options));
+        return { opened: false, reason: formatError(error) };
+    }
+}
 async function ensurePortableStudioServer(options) {
     const event = await createCliWideEvent("tapi_cli.studio_server_ensure", {
         sdk_version: sdkVersion,
@@ -2340,9 +2262,11 @@ async function installPortableStudioServer(options, manifest, event) {
         return artifactPath;
     }
     const releaseDir = portableStudioServerReleaseDir(manifest, options.installDir);
+    await pruneManagedFiles(options.cacheDir, [artifactPath], isTapiStudioDownloadArtifact, MAX_NONCURRENT_MANAGED_DOWNLOADS, "old Tapi Studio download");
+    await pruneTapiReleaseDirs(dirname(releaseDir), [releaseDir], isSafeManagedReleaseDirName, MAX_NONCURRENT_MANAGED_RELEASES, "old Tapi Studio server release");
     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");
+    await pruneTapiReleaseDirs(dirname(releaseDir), [releaseDir], isSafeManagedReleaseDirName, MAX_NONCURRENT_MANAGED_RELEASES, "old Tapi Studio server release");
     console.log(`Installed Tapi Studio server ${manifest.version}: ${releaseDir}`);
     return exePath;
 }
@@ -2354,6 +2278,7 @@ async function launchPortableStudioServer(exePath, options, manifest) {
     env.TAPI_RUNTIME_NAMESPACE = "installed";
     env.TAPI_RUNTIME_CONTROL_PORT = env.TAPI_RUNTIME_CONTROL_PORT || "8765";
     env.TAPI_PROCESS_ROLE = "studio_server";
+    env.TAPI_STUDIO_EXIT_ON_IDLE = "1";
     env.TAPI_STUDIO_OPEN_BROWSER = "0";
     env.TAPI_STUDIO_HOST = host;
     env.TAPI_STUDIO_PORT = String(port);
@@ -2366,8 +2291,7 @@ async function launchPortableStudioServer(exePath, options, manifest) {
         env.PLAYWRIGHT_BROWSERS_PATH = playwrightBrowsersPath;
     }
     const url = `http://${host}:${port}`;
-    const launchQuery = options.launchUrlQuery ? options.launchUrlQuery.replace(/^\?+/, "") : "";
-    const launchUrl = launchQuery ? `${url}/?${launchQuery}` : url;
+    const launchUrl = studioLaunchUrl(url, options);
     let childPid = 0;
     await withCliSpinner("Starting Tapi Studio", async () => {
         const child = spawn(exePath, [], {
@@ -2396,6 +2320,11 @@ async function launchPortableStudioServer(exePath, options, manifest) {
     openBrowser(launchUrl);
     console.log(`Opened Tapi Studio ${manifest.version}: ${launchUrl}`);
 }
+function studioLaunchUrl(baseUrl, options) {
+    const normalizedBaseUrl = baseUrl.replace(/\/+$/, "");
+    const launchQuery = options.launchUrlQuery ? options.launchUrlQuery.replace(/^\?+/, "") : "";
+    return launchQuery ? `${normalizedBaseUrl}/?${launchQuery}` : normalizedBaseUrl;
+}
 export function findPortablePlaywrightBrowsersDir(exePath) {
     const exeDir = dirname(exePath);
     const releaseDir = basename(exeDir).toLowerCase() === "tapi-studio-server"
@@ -2458,12 +2387,28 @@ function delay(ms) {
         setTimeout(resolvePromise, Math.max(0, ms));
     });
 }
-async function chooseStudioPort(preferred = 18766) {
-    for (let port = preferred; port < preferred + 25; port += 1) {
-        if (await isPortAvailable(port)) {
+export async function chooseStudioPort(preferred = 18766, options = {}) {
+    const count = options.count ?? 25;
+    const portAvailable = options.portAvailable ?? isPortAvailable;
+    const reapBlockedPorts = options.reapBlockedPorts ?? reapPortableStudioServersBlockingPorts;
+    const initiallyReaped = await reapBlockedPorts(preferred, count);
+    if (initiallyReaped > 0) {
+        await delay(250);
+    }
+    for (let port = preferred; port < preferred + count; port += 1) {
+        if (await portAvailable(port)) {
             return port;
         }
     }
+    const reaped = await reapBlockedPorts(preferred, count);
+    if (reaped > 0) {
+        await delay(250);
+        for (let port = preferred; port < preferred + count; port += 1) {
+            if (await portAvailable(port)) {
+                return port;
+            }
+        }
+    }
     throw new Error(`No available local Studio port found starting at ${preferred}.`);
 }
 async function isPortAvailable(port) {
@@ -2475,6 +2420,56 @@ async function isPortAvailable(port) {
         });
     });
 }
+async function reapPortableStudioServersBlockingPorts(preferred, count) {
+    if (process.platform !== "win32") {
+        return 0;
+    }
+    const start = Math.max(1, Math.min(65535, Math.trunc(preferred)));
+    const end = Math.max(start, Math.min(65535, start + Math.max(1, Math.trunc(count)) - 1));
+    const script = `
+$ErrorActionPreference = 'SilentlyContinue'
+$ports = ${start}..${end}
+$connections = @(Get-NetTCPConnection -State Listen | Where-Object { $ports -contains $_.LocalPort })
+$owners = @{}
+foreach ($conn in $connections) {
+  $pidValue = [int]$conn.OwningProcess
+  if ($pidValue -le 0 -or $owners.ContainsKey($pidValue)) { continue }
+  $proc = Get-CimInstance Win32_Process -Filter "ProcessId=$pidValue"
+  if ($null -eq $proc) { continue }
+  $path = [string]$proc.ExecutablePath
+  $cmd = [string]$proc.CommandLine
+  $isPortableStudio = (
+    $path -match '\\\\Tapi\\\\Studio\\\\server\\\\releases\\\\' -or
+    $cmd -match 'tapi-studio-server'
+  )
+  if ($isPortableStudio) {
+    $owners[$pidValue] = $true
+  }
+}
+$stopped = 0
+foreach ($pidValue in $owners.Keys) {
+  try {
+    Stop-Process -Id $pidValue -Force -ErrorAction Stop
+    $stopped += 1
+  } catch {}
+}
+[pscustomobject]@{ stopped = $stopped } | ConvertTo-Json -Compress
+`;
+    try {
+        const output = await runProcessCapture("powershell.exe", [
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-Command",
+            script,
+        ]);
+        const payload = JSON.parse(output.trim() || "{}");
+        return typeof payload.stopped === "number" ? payload.stopped : 0;
+    }
+    catch {
+        return 0;
+    }
+}
 async function runDoctor(options) {
     console.log(`Tapi SDK: ${sdkVersion}`);
     console.log(`Node: ${process.version}`);
@@ -3026,6 +3021,7 @@ function cachedServiceArtifactName(manifest) {
 async function extractZip(zipPath, destination) {
     await rm(destination, { recursive: true, force: true });
     await mkdir(destination, { recursive: true });
+    await ensureEnoughDiskSpaceForExtraction(zipPath, destination);
     try {
         await runProcessCapture("powershell.exe", [
             "-NoProfile",
@@ -3039,6 +3035,60 @@ async function extractZip(zipPath, destination) {
         throw new Error(formatZipExtractionFailure(zipPath, destination, error), { cause: error });
     }
 }
+async function ensureEnoughDiskSpaceForExtraction(zipPath, destination) {
+    const zipInfo = await stat(zipPath).catch(() => undefined);
+    if (!zipInfo?.isFile()) {
+        return;
+    }
+    const requiredBytes = estimateRequiredExtractionBytes(zipInfo.size);
+    const availableBytes = await availableBytesForPath(destination);
+    if (availableBytes === undefined || availableBytes >= requiredBytes) {
+        return;
+    }
+    throw new Error(formatInsufficientExtractionSpace(zipPath, destination, availableBytes, requiredBytes));
+}
+export function estimateRequiredExtractionBytes(zipBytes) {
+    const scaled = Math.ceil(Math.max(0, zipBytes) * EXTRACTION_REQUIRED_MULTIPLIER);
+    return Math.max(MIN_EXTRACTION_REQUIRED_BYTES, scaled);
+}
+async function availableBytesForPath(targetPath) {
+    let probe = resolve(targetPath);
+    for (;;) {
+        if (existsSync(probe)) {
+            try {
+                const info = await statfs(probe);
+                return Number(info.bavail) * Number(info.bsize);
+            }
+            catch {
+                return undefined;
+            }
+        }
+        const parent = dirname(probe);
+        if (!parent || parent === probe) {
+            return undefined;
+        }
+        probe = parent;
+    }
+}
+export function formatInsufficientExtractionSpace(zipPath, destination, availableBytes, requiredBytes) {
+    return [
+        `Not enough free disk space to extract ${zipPath}.`,
+        `Destination: ${destination}.`,
+        `Available: ${formatBytes(availableBytes)}; estimated required before extraction: ${formatBytes(requiredBytes)}.`,
+        "Tapi prunes old managed downloads and releases before extraction, but this drive is still too full.",
+        "Free space under %LOCALAPPDATA%\\Tapi or move Studio downloads/releases with TAPI_STUDIO_HOME / --cache-dir / --install-dir.",
+    ].join(" ");
+}
+function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0) {
+        return "unknown";
+    }
+    const gib = bytes / (1024 * 1024 * 1024);
+    if (gib >= 1) {
+        return `${gib.toFixed(2)} GB`;
+    }
+    return `${(bytes / (1024 * 1024)).toFixed(0)} MB`;
+}
 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 }`;
 }
@@ -3090,7 +3140,7 @@ export async function pruneManagedFiles(directory, keepPaths, isManagedFileName,
     }
     return removed;
 }
-async function pruneManagedDirs(directory, keepPaths, isManagedDirName, maxNoncurrentEntries = 0, label = "old Tapi release") {
+export async function pruneTapiReleaseDirs(directory, keepPaths, isManagedDirName, maxNoncurrentEntries = 0, label = "old Tapi release") {
     const keep = normalizedKeepPathSet(keepPaths);
     let entries;
     try {
@@ -3108,7 +3158,7 @@ async function pruneManagedDirs(directory, keepPaths, isManagedDirName, maxNoncu
         if (keep.has(normalizeFilesystemPath(candidate))) {
             continue;
         }
-        if (!existsSync(join(candidate, MANAGED_RELEASE_MARKER))) {
+        if (!(await isTapiManagedReleaseDir(candidate))) {
             continue;
         }
         const info = await stat(candidate).catch(() => undefined);
@@ -3134,6 +3184,34 @@ async function pruneManagedDirs(directory, keepPaths, isManagedDirName, maxNoncu
     }
     return removed;
 }
+async function isTapiManagedReleaseDir(directory) {
+    if (existsSync(join(directory, MANAGED_RELEASE_MARKER))) {
+        return true;
+    }
+    if (looksLikeTapiServiceReleaseDir(directory) || looksLikeTapiStudioReleaseDir(directory)) {
+        return true;
+    }
+    const entries = await readdir(directory).catch(() => undefined);
+    return Array.isArray(entries) && entries.length === 0;
+}
+function looksLikeTapiServiceReleaseDir(directory) {
+    return (existsSync(join(directory, "tapi-service-host.exe"))
+        && existsSync(join(directory, "install_tapi_service.ps1"))
+        && (existsSync(join(directory, "tapi-service-worker.exe"))
+            || existsSync(join(directory, "tapi-service-worker", "tapi-service-worker.exe"))));
+}
+function looksLikeTapiStudioReleaseDir(directory) {
+    return Boolean(findPortableStudioServerExe(directory, {
+        version: "",
+        channel: "",
+        platform: SUPPORTED_STUDIO_PLATFORM,
+        artifactName: "tapi-studio-server.zip",
+        url: "",
+        sha256: "",
+        installerKind: "portable-server",
+        serverExecutable: "tapi-studio-server.exe",
+    }));
+}
 export function isTapiStudioDownloadArtifact(fileName) {
     const normalized = fileName.toLowerCase();
     return (normalized.endsWith(".zip")
@@ -3310,7 +3388,6 @@ Usage:
   tapi apis generate
   tapi triggers sync
   tapi sessions
-  tapi publish
   tapi service status
   tapi doctor
 
@@ -3326,7 +3403,6 @@ Commands:
   apis generate   Generate a TypeScript runtime wrapper from the catalog
   triggers sync   Upsert API-call triggers from tapi.config
   sessions        List dev-mode API sessions and open takeover sessions
-  publish         Upload local .tapi API drafts and publish ready requests
   service         Inspect or control the local Tapi Windows service
   doctor          Alias for studio doctor
 `);
@@ -3451,15 +3527,6 @@ Commands:
   repair    Restart tapi-service using the current installed service
 `);
 }
-function printPublishHelp() {
-    console.log(`Tapi publish
-
-Usage:
-  tapi publish [--api-base-url URL] [--api-key KEY] [--project PROJECT]
-
-Publishes ready generated API requests from local .tapi/apis files.
-`);
-}
 function formatError(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/index.d.ts

@@ -4,9 +4,9 @@ import { RunnersResource } from "./runners.js";
 import { RunsResource } from "./runs.js";
 import { RuntimeResource } from "./runtime.js";
 import { SessionsResource } from "./sessions.js";
+import { ServicesResource } from "./services.js";
 import { TriggersResource } from "./triggers.js";
 import type { TapiClientOptions } from "./types.js";
-import { WebsiteApisResource } from "./website-apis.js";
 export declare class TapiClient {
     readonly catalog: CatalogResource;
     readonly cloudRuns: CloudRunsResource;
@@ -14,8 +14,8 @@ export declare class TapiClient {
     readonly runs: RunsResource;
     readonly runtime: RuntimeResource;
     readonly sessions: SessionsResource;
+    readonly services: ServicesResource;
     readonly triggers: TriggersResource;
-    readonly websiteApis: WebsiteApisResource;
     constructor(options: TapiClientOptions);
 }
 export * from "./errors.js";

package/dist/index.js

@@ -5,8 +5,8 @@ import { RunnersResource } from "./runners.js";
 import { RunsResource } from "./runs.js";
 import { RuntimeResource } from "./runtime.js";
 import { SessionsResource } from "./sessions.js";
+import { ServicesResource } from "./services.js";
 import { TriggersResource } from "./triggers.js";
-import { WebsiteApisResource } from "./website-apis.js";
 export class TapiClient {
     catalog;
     cloudRuns;
@@ -14,8 +14,8 @@ export class TapiClient {
     runs;
     runtime;
     sessions;
+    services;
     triggers;
-    websiteApis;
     constructor(options) {
         const http = new HttpClient(options);
         this.catalog = new CatalogResource(http);
@@ -24,8 +24,8 @@ export class TapiClient {
         this.runs = new RunsResource(http);
         this.runtime = new RuntimeResource(http, options);
         this.sessions = new SessionsResource(http);
+        this.services = new ServicesResource(http, options);
         this.triggers = new TriggersResource(http);
-        this.websiteApis = new WebsiteApisResource(http, options);
     }
 }
 export * from "./errors.js";

package/dist/services.d.ts

@@ -0,0 +1,17 @@
+import type { HttpClient } from "./client.js";
+import type { CloudBatchRun, CloudRunQuote, ServiceCloudBatchRequest, ServiceCloudQuoteRequest, ServiceOperation, ServiceRunRequest, TapiRun } from "./types.js";
+import type { TapiClientOptions } from "./types.js";
+export declare class ServicesResource {
+    private readonly http;
+    private readonly dev;
+    constructor(http: HttpClient, options: TapiClientOptions);
+    run(serviceRequest: string, request?: ServiceRunRequest): Promise<TapiRun>;
+    quoteCloud(serviceRequest: string, request?: ServiceCloudQuoteRequest): Promise<CloudRunQuote>;
+    runCloud(serviceRequest: string, request?: ServiceRunRequest & {
+        cloud?: ServiceCloudBatchRequest["cloud"];
+        user?: ServiceCloudBatchRequest["user"];
+        payment?: ServiceCloudBatchRequest["payment"];
+    }): Promise<CloudBatchRun>;
+    runCloudBatch(serviceRequest: string, request: ServiceCloudBatchRequest): Promise<CloudBatchRun>;
+    describe(serviceRequest: string): Promise<ServiceOperation>;
+}

package/dist/{website-apis.js → services.js}

@@ -1,32 +1,32 @@
 import { TapiError } from "./errors.js";
 import { attachLateInputs, serializeInputs } from "./late-input.js";
-export class WebsiteApisResource {
+export class ServicesResource {
     http;
     dev;
     constructor(http, options) {
         this.http = http;
         this.dev = options.dev === true;
     }
-    async run(apiRequest, request = {}) {
-        const { apiName, requestKey } = splitApiRequest(apiRequest);
+    async run(serviceRequest, request = {}) {
+        const { serviceName, requestKey } = splitServiceRequest(serviceRequest);
         const { bodyInputs, lateInputs } = serializeInputs(request.inputs);
         const body = {
             ...request,
             ...(bodyInputs === undefined ? {} : { inputs: bodyInputs }),
             ...(this.dev ? { dev: true } : {}),
         };
-        const run = await this.http.post(`/api/sdk/v1/website-apis/${encodeURIComponent(apiName)}/requests/${encodeURIComponent(requestKey)}/runs`, body);
+        const run = await this.http.post(`/api/sdk/v1/services/${encodeURIComponent(serviceName)}/requests/${encodeURIComponent(requestKey)}/runs`, body);
         if (run.id && lateInputs.length > 0) {
             attachLateInputs(lateInputs, run.id, (runId, inputKey, value) => this.http.post(`/api/sdk/v1/runs/${encodeURIComponent(runId)}/inputs/${encodeURIComponent(inputKey)}`, { value }));
         }
         return run;
     }
-    quoteCloud(apiRequest, request = {}) {
-        const { apiName, requestKey } = splitApiRequest(apiRequest);
-        return this.http.post(`/api/sdk/v1/website-apis/${encodeURIComponent(apiName)}/requests/${encodeURIComponent(requestKey)}/cloud/quote`, request);
+    quoteCloud(serviceRequest, request = {}) {
+        const { serviceName, requestKey } = splitServiceRequest(serviceRequest);
+        return this.http.post(`/api/sdk/v1/services/${encodeURIComponent(serviceName)}/requests/${encodeURIComponent(requestKey)}/cloud/quote`, request);
     }
-    runCloud(apiRequest, request = {}) {
-        return this.runCloudBatch(apiRequest, {
+    runCloud(serviceRequest, request = {}) {
+        return this.runCloudBatch(serviceRequest, {
             inputs: [request.inputs ?? {}],
             cloud: request.cloud,
             user: request.user,
@@ -35,10 +35,10 @@ export class WebsiteApisResource {
             idempotencyKey: request.idempotencyKey,
         });
     }
-    async runCloudBatch(apiRequest, request) {
-        const { apiName, requestKey } = splitApiRequest(apiRequest);
+    async runCloudBatch(serviceRequest, request) {
+        const { serviceName, requestKey } = splitServiceRequest(serviceRequest);
         try {
-            return await this.http.post(`/api/sdk/v1/website-apis/${encodeURIComponent(apiName)}/requests/${encodeURIComponent(requestKey)}/cloud/batch`, request);
+            return await this.http.post(`/api/sdk/v1/services/${encodeURIComponent(serviceName)}/requests/${encodeURIComponent(requestKey)}/cloud/batch`, request);
         }
         catch (error) {
             if (error instanceof TapiError && error.status === 402 && isRecord(error.details)) {
@@ -47,19 +47,19 @@ export class WebsiteApisResource {
             throw error;
         }
     }
-    describe(apiRequest) {
-        const { apiName, requestKey } = splitApiRequest(apiRequest);
-        return this.http.get(`/api/sdk/v1/website-apis/${encodeURIComponent(apiName)}/requests/${encodeURIComponent(requestKey)}`);
+    describe(serviceRequest) {
+        const { serviceName, requestKey } = splitServiceRequest(serviceRequest);
+        return this.http.get(`/api/sdk/v1/services/${encodeURIComponent(serviceName)}/requests/${encodeURIComponent(requestKey)}`);
     }
 }
-function splitApiRequest(value) {
+function splitServiceRequest(value) {
     const text = value.trim();
     const index = text.lastIndexOf(".");
     if (index <= 0 || index === text.length - 1) {
-        throw new Error("api request must be formatted as '<apiName>.<requestKey>'");
+        throw new Error("service request must be formatted as '<serviceName>.<requestKey>'");
     }
     return {
-        apiName: text.slice(0, index),
+        serviceName: text.slice(0, index),
         requestKey: text.slice(index + 1),
     };
 }

package/dist/triggers.js

@@ -4,16 +4,16 @@ export class TriggersResource {
         this.http = http;
     }
     list() {
-        return this.http.get("/api/sdk/v1/website-api-triggers");
+        return this.http.get("/api/sdk/v1/service-triggers");
     }
     create(request) {
-        return this.http.post("/api/sdk/v1/website-api-triggers", request);
+        return this.http.post("/api/sdk/v1/service-triggers", request);
     }
     get(triggerId) {
-        return this.http.get(`/api/sdk/v1/website-api-triggers/${encodeURIComponent(triggerId)}`);
+        return this.http.get(`/api/sdk/v1/service-triggers/${encodeURIComponent(triggerId)}`);
     }
     update(triggerId, request) {
-        return this.http.patch(`/api/sdk/v1/website-api-triggers/${encodeURIComponent(triggerId)}`, request);
+        return this.http.patch(`/api/sdk/v1/service-triggers/${encodeURIComponent(triggerId)}`, request);
     }
     enable(triggerId) {
         return this.update(triggerId, { enabled: true });
@@ -22,9 +22,9 @@ export class TriggersResource {
         return this.update(triggerId, { enabled: false });
     }
     delete(triggerId) {
-        return this.http.delete(`/api/sdk/v1/website-api-triggers/${encodeURIComponent(triggerId)}`);
+        return this.http.delete(`/api/sdk/v1/service-triggers/${encodeURIComponent(triggerId)}`);
     }
     fire(triggerId) {
-        return this.http.post(`/api/sdk/v1/website-api-triggers/${encodeURIComponent(triggerId)}/run`);
+        return this.http.post(`/api/sdk/v1/service-triggers/${encodeURIComponent(triggerId)}/run`);
     }
 }

package/dist/types.d.ts

@@ -16,6 +16,7 @@ export interface WebsiteApiRunRequest {
     runnerId?: string;
     idempotencyKey?: string;
     site?: string;
+    sitemapId?: string;
 }
 export interface CloudRunOptions {
     windows?: boolean;
@@ -46,6 +47,9 @@ export interface WebsiteApiCloudBatchRequest {
     site?: string;
     idempotencyKey?: string;
 }
+export type ServiceRunRequest = WebsiteApiRunRequest;
+export type ServiceCloudQuoteRequest = WebsiteApiCloudQuoteRequest;
+export type ServiceCloudBatchRequest = WebsiteApiCloudBatchRequest;
 export interface CloudRunQuote {
     inputCount: number;
     windows: boolean;
@@ -155,10 +159,11 @@ export interface WebsiteApiOperation {
     namespace: string;
     operation: string;
     site?: string;
+    sitemapId?: string;
     version?: string;
     status?: string;
     publishedAt?: string | null;
-    variant?: "desktop" | "mobile" | string;
+    deviceMode?: "desktop" | "mobile" | string;
     runtime?: RuntimeRunOptions | Record<string, unknown>;
     inputs: WebsiteApiInputContract[];
     outputs?: WebsiteApiOutputContract[];
@@ -181,6 +186,7 @@ export interface WebsiteApiTriggerCreateRequest {
     runnerId?: string;
     priority?: number;
     site?: string;
+    sitemapId?: string;
 }
 export interface WebsiteApiTriggerUpdateRequest {
     enabled: boolean;
@@ -228,6 +234,9 @@ export interface TapiRun {
     updatedAt?: string;
     [key: string]: unknown;
 }
+export type ServiceInputContract = WebsiteApiInputContract;
+export type ServiceOutputContract = WebsiteApiOutputContract;
+export type ServiceOperation = WebsiteApiOperation;
 export type TapiDevSessionStatus = "queued" | "running" | "waiting_for_input" | "awaiting_takeover" | "needs_developer_attention" | "completed" | "failed" | "cancelled" | string;
 export interface TapiDevSession {
     id: string;
@@ -367,7 +376,8 @@ export interface SdkCatalogRequest {
     status: string;
     operation?: string;
     sdkName?: string;
-    variant?: "desktop" | "mobile" | string;
+    sitemapId?: string;
+    deviceMode?: "desktop" | "mobile" | string;
     runtime?: RuntimeRunOptions | Record<string, unknown>;
     inputs?: WebsiteApiInputContract[];
     inputSchema?: Record<string, unknown>;
@@ -379,6 +389,7 @@ export interface SdkCatalogApi {
     name: string;
     version: string;
     site?: string;
+    sitemapId?: string;
     requests: SdkCatalogRequest[];
     [key: string]: unknown;
 }

package/package.json

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

package/dist/website-apis.d.ts

@@ -1,17 +0,0 @@
-import type { HttpClient } from "./client.js";
-import type { CloudBatchRun, CloudRunQuote, TapiRun, WebsiteApiCloudBatchRequest, WebsiteApiCloudQuoteRequest, WebsiteApiOperation, WebsiteApiRunRequest } from "./types.js";
-import type { TapiClientOptions } from "./types.js";
-export declare class WebsiteApisResource {
-    private readonly http;
-    private readonly dev;
-    constructor(http: HttpClient, options: TapiClientOptions);
-    run(apiRequest: string, request?: WebsiteApiRunRequest): Promise<TapiRun>;
-    quoteCloud(apiRequest: string, request?: WebsiteApiCloudQuoteRequest): Promise<CloudRunQuote>;
-    runCloud(apiRequest: string, request?: WebsiteApiRunRequest & {
-        cloud?: WebsiteApiCloudBatchRequest["cloud"];
-        user?: WebsiteApiCloudBatchRequest["user"];
-        payment?: WebsiteApiCloudBatchRequest["payment"];
-    }): Promise<CloudBatchRun>;
-    runCloudBatch(apiRequest: string, request: WebsiteApiCloudBatchRequest): Promise<CloudBatchRun>;
-    describe(apiRequest: string): Promise<WebsiteApiOperation>;
-}