@tapi-dev/sdk 0.1.7 → 0.1.9

package/dist/cli.js

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 import { createServer } from "node:http";
+import { createServer as createNetServer } from "node:net";
 import { createHash, randomUUID } from "node:crypto";
 import { createReadStream, createWriteStream, existsSync, readFileSync } from "node:fs";
 import { mkdir, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { performance } from "node:perf_hooks";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
 import { TapiClient } from "./index.js";
+import { loadWorkspace, normalizeProjectValue, writeWorkspaceConfig, } from "./workspace.js";
 const DEFAULT_DOWNLOADS_BASE_URL = "https://d4xaf52nfwiok.cloudfront.net";
 const DEFAULT_STUDIO_API_BASE_URL = "https://determined-motivation-production.up.railway.app";
 const DEFAULT_STUDIO_AUTH_HTML_URL = "https://rsarlong-1f92fd.gitlab.io/auth.html";
@@ -47,6 +49,27 @@ export async function runCli(argv = process.argv.slice(2)) {
         }
         return runDoctor(parseStudioOptions([subcommand, ...rest].filter(Boolean)));
     }
+    if (command === "init" || command === "link") {
+        if (hasHelpFlag([subcommand, ...rest])) {
+            printWorkspaceHelp(command);
+            return 0;
+        }
+        return writeWorkspace(command, [subcommand, ...rest].filter(Boolean));
+    }
+    if (command === "service") {
+        if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h" || hasHelpFlag(rest)) {
+            printServiceHelp();
+            return 0;
+        }
+        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();
@@ -55,6 +78,12 @@ export async function runCli(argv = process.argv.slice(2)) {
         if (subcommand === "describe") {
             return describeApiOperation(rest);
         }
+        if (subcommand === "sync") {
+            return syncApiCatalog(rest);
+        }
+        if (subcommand === "generate") {
+            return generateApiClient(rest);
+        }
         console.error(`Unknown apis command: ${subcommand}`);
         printApisHelp();
         return 1;
@@ -64,7 +93,10 @@ export async function runCli(argv = process.argv.slice(2)) {
         printHelp();
         return 1;
     }
-    if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+    if (!subcommand) {
+        return openStudio(parseStudioOptions([]));
+    }
+    if (subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
         printStudioHelp();
         return 0;
     }
@@ -88,6 +120,8 @@ export async function runCli(argv = process.argv.slice(2)) {
 }
 export function parseStudioOptions(args) {
     const raw = {};
+    let workspaceSearchRoot;
+    let skipWorkspace = false;
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg) {
@@ -121,6 +155,34 @@ export function parseStudioOptions(args) {
             raw.apiBaseUrl = arg.slice("--server=".length);
             continue;
         }
+        if (arg === "--workspace") {
+            workspaceSearchRoot = requireOptionValue(args, ++index, "--workspace");
+            continue;
+        }
+        if (arg.startsWith("--workspace=")) {
+            workspaceSearchRoot = arg.slice("--workspace=".length);
+            continue;
+        }
+        if (arg === "--no-workspace") {
+            skipWorkspace = true;
+            continue;
+        }
+        if (arg === "--project") {
+            raw.projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
+            continue;
+        }
+        if (arg.startsWith("--project=")) {
+            raw.projectId = normalizeProjectValue(arg.slice("--project=".length), "project");
+            continue;
+        }
+        if (arg === "--project-slug") {
+            raw.projectSlug = normalizeProjectValue(requireOptionValue(args, ++index, "--project-slug"), "projectSlug");
+            continue;
+        }
+        if (arg.startsWith("--project-slug=")) {
+            raw.projectSlug = normalizeProjectValue(arg.slice("--project-slug=".length), "projectSlug");
+            continue;
+        }
         if (arg === "--install-token") {
             raw.installToken = requireOptionValue(args, ++index, "--install-token");
             continue;
@@ -158,17 +220,21 @@ export function parseStudioOptions(args) {
         }
         throw new Error(`Unknown option: ${arg}`);
     }
+    const workspace = skipWorkspace ? undefined : loadWorkspace(workspaceSearchRoot ?? process.cwd());
     const channel = raw.channel ?? parseChannel(envString("TAPI_STUDIO_CHANNEL") ?? DEFAULT_CHANNEL);
     const apiBaseUrl = normalizeHttpUrl(raw.apiBaseUrl
         ?? envString("TAPI_STUDIO_API_BASE_URL")
         ?? envString("TAPI_BASE_URL")
         ?? envString("TAPI_STUDIO_SERVER_URL")
+        ?? workspace?.apiBaseUrl
         ?? DEFAULT_STUDIO_API_BASE_URL, "Studio API base URL");
     const downloadsBaseUrl = normalizeHttpUrl(envString("TAPI_DOWNLOADS_BASE_URL") ?? DEFAULT_DOWNLOADS_BASE_URL, "TAPI_DOWNLOADS_BASE_URL");
     const explicitManifestUrl = raw.manifestUrlOverride ?? envString("TAPI_STUDIO_MANIFEST_URL");
     const manifestUrl = explicitManifestUrl
         ? normalizeHttpUrl(explicitManifestUrl, "Studio manifest URL")
         : `${downloadsBaseUrl.replace(/\/+$/, "")}/studio/channels/${channel}/latest.json`;
+    const projectId = raw.projectId ?? envString("TAPI_PROJECT_ID") ?? workspace?.projectId;
+    const projectSlug = raw.projectSlug ?? envString("TAPI_PROJECT_SLUG") ?? workspace?.projectSlug;
     return {
         channel,
         apiBaseUrl,
@@ -179,13 +245,19 @@ export function parseStudioOptions(args) {
         silent: raw.silent ?? false,
         exePath: raw.exePath ?? envString("TAPI_STUDIO_EXE"),
         installToken: raw.installToken ?? envString("TAPI_STUDIO_INSTALL_TOKEN"),
+        workspace,
+        workspaceRoot: workspace?.root,
+        projectId,
+        projectSlug,
+        workspaceMode: Boolean(projectId || workspace),
     };
 }
 function parseApiOptions(args) {
     let operation = "";
-    let apiBaseUrl = envString("TAPI_BASE_URL") || DEFAULT_STUDIO_API_BASE_URL;
+    const workspace = loadWorkspace();
+    let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
     let apiKey = envString("TAPI_API_KEY") || "";
-    let appId = envString("TAPI_APP_ID");
+    let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg)
@@ -210,12 +282,12 @@ function parseApiOptions(args) {
             apiKey = arg.slice("--api-key=".length);
             continue;
         }
-        if (arg === "--app") {
-            appId = requireOptionValue(args, ++index, "--app");
+        if (arg === "--project") {
+            projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
             continue;
         }
-        if (arg.startsWith("--app=")) {
-            appId = arg.slice("--app=".length);
+        if (arg.startsWith("--project=")) {
+            projectId = normalizeProjectValue(arg.slice("--project=".length), "project");
             continue;
         }
         if (arg.startsWith("--")) {
@@ -233,12 +305,15 @@ function parseApiOptions(args) {
     if (!apiKey) {
         throw new Error("apis describe requires --api-key or TAPI_API_KEY.");
     }
+    if (!projectId) {
+        throw new Error("apis describe requires --project, TAPI_PROJECT_ID, or .tapi/project.json.");
+    }
     return {
         operation,
         options: {
             apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
             apiKey,
-            appId,
+            projectId,
         },
     };
 }
@@ -248,7 +323,7 @@ async function describeApiOperation(args) {
         const client = new TapiClient({
             baseUrl: options.apiBaseUrl,
             apiKey: options.apiKey,
-            appId: options.appId,
+            projectId: options.projectId,
         });
         const description = await client.websiteApis.describe(operation);
         console.log(JSON.stringify(description, null, 2));
@@ -259,6 +334,596 @@ async function describeApiOperation(args) {
         return 1;
     }
 }
+function parseApiWorkspaceOptions(args) {
+    const workspace = loadWorkspace();
+    let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
+    let apiKey = envString("TAPI_API_KEY") || "";
+    let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
+    let catalogPath = workspace?.config.generated?.catalog || ".tapi/generated/catalog.json";
+    let typescriptPath = workspace?.config.generated?.typescript || "src/tapi.generated.ts";
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg)
+            continue;
+        if (arg === "--api-base-url" || arg === "--server") {
+            apiBaseUrl = requireOptionValue(args, ++index, arg);
+            continue;
+        }
+        if (arg.startsWith("--api-base-url=")) {
+            apiBaseUrl = arg.slice("--api-base-url=".length);
+            continue;
+        }
+        if (arg.startsWith("--server=")) {
+            apiBaseUrl = arg.slice("--server=".length);
+            continue;
+        }
+        if (arg === "--api-key") {
+            apiKey = requireOptionValue(args, ++index, "--api-key");
+            continue;
+        }
+        if (arg.startsWith("--api-key=")) {
+            apiKey = arg.slice("--api-key=".length);
+            continue;
+        }
+        if (arg === "--project") {
+            projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
+            continue;
+        }
+        if (arg.startsWith("--project=")) {
+            projectId = normalizeProjectValue(arg.slice("--project=".length), "project");
+            continue;
+        }
+        if (arg === "--catalog") {
+            catalogPath = requireOptionValue(args, ++index, "--catalog");
+            continue;
+        }
+        if (arg.startsWith("--catalog=")) {
+            catalogPath = arg.slice("--catalog=".length);
+            continue;
+        }
+        if (arg === "--out") {
+            typescriptPath = requireOptionValue(args, ++index, "--out");
+            continue;
+        }
+        if (arg.startsWith("--out=")) {
+            typescriptPath = arg.slice("--out=".length);
+            continue;
+        }
+        throw new Error(`Unknown apis option: ${arg}`);
+    }
+    if (!apiKey) {
+        throw new Error("apis command requires --api-key or TAPI_API_KEY.");
+    }
+    if (!projectId) {
+        throw new Error("apis command requires --project, TAPI_PROJECT_ID, or .tapi/project.json.");
+    }
+    const root = workspace?.root || process.cwd();
+    return {
+        apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
+        apiKey,
+        projectId,
+        catalogPath: resolve(root, catalogPath),
+        typescriptPath: resolve(root, typescriptPath),
+    };
+}
+async function syncApiCatalog(args) {
+    try {
+        const options = parseApiWorkspaceOptions(args);
+        const catalog = await fetchApiCatalog(options);
+        await writeJsonFile(options.catalogPath, catalog);
+        console.log(`Synced Tapi API catalog: ${options.catalogPath}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+async function generateApiClient(args) {
+    try {
+        const options = parseApiWorkspaceOptions(args);
+        const catalog = await fetchApiCatalog(options);
+        await writeJsonFile(options.catalogPath, catalog);
+        await writeTextFile(options.typescriptPath, renderGeneratedApiClient(catalog));
+        console.log(`Generated Tapi API client: ${options.typescriptPath}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+async function fetchApiCatalog(options) {
+    const client = new TapiClient({
+        baseUrl: options.apiBaseUrl,
+        apiKey: options.apiKey,
+        projectId: options.projectId,
+    });
+    return client.catalog.get();
+}
+async function writeJsonFile(path, payload) {
+    await writeTextFile(path, `${JSON.stringify(payload, null, 2)}\n`);
+}
+async function writeTextFile(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, "utf8");
+}
+function renderGeneratedApiClient(catalog) {
+    const namespaces = new Map();
+    for (const api of catalog.apis || []) {
+        const namespace = safeIdentifier(api.name || "api");
+        for (const request of api.requests || []) {
+            const key = String(request.operation || request.sdkName || request.key || "").trim();
+            if (!key)
+                continue;
+            const operationName = safeIdentifier(key);
+            const operation = `${api.name}.${key}`;
+            const items = namespaces.get(namespace) ?? [];
+            items.push({ key: operation, operationName });
+            namespaces.set(namespace, items);
+        }
+    }
+    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 }),`);
+        return `  ${namespace}: {\n${lines.join("\n")}\n  },`;
+    });
+    return `/* Generated by Tapi. Do not edit by hand. */
+import { TapiClient, type TapiClientOptions, type RuntimeRunOptions } from "@tapi-dev/sdk";
+
+export interface GeneratedRunOptions {
+  runtime?: RuntimeRunOptions;
+  priority?: number;
+  runnerId?: string;
+  idempotencyKey?: string;
+  site?: string;
+}
+
+export function createTapiGeneratedClient(options: TapiClientOptions) {
+  const client = new TapiClient(options);
+  return {
+${namespaceBlocks.join("\n")}
+  };
+}
+`;
+}
+function safeIdentifier(value) {
+    const cleaned = String(value || "api")
+        .replace(/[^a-zA-Z0-9_$]+/g, "_")
+        .replace(/^([^a-zA-Z_$])/, "_$1");
+    return cleaned || "api";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseWorkspaceOptions(command, args) {
+    const raw = {
+        force: command === "link",
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg) {
+            continue;
+        }
+        if (arg === "--project") {
+            raw.projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
+            continue;
+        }
+        if (arg.startsWith("--project=")) {
+            raw.projectId = normalizeProjectValue(arg.slice("--project=".length), "project");
+            continue;
+        }
+        if (arg === "--project-slug") {
+            raw.projectSlug = normalizeProjectValue(requireOptionValue(args, ++index, "--project-slug"), "projectSlug");
+            continue;
+        }
+        if (arg.startsWith("--project-slug=")) {
+            raw.projectSlug = normalizeProjectValue(arg.slice("--project-slug=".length), "projectSlug");
+            continue;
+        }
+        if (arg === "--api-base-url" || arg === "--server") {
+            raw.apiBaseUrl = requireOptionValue(args, ++index, arg);
+            continue;
+        }
+        if (arg.startsWith("--api-base-url=")) {
+            raw.apiBaseUrl = arg.slice("--api-base-url=".length);
+            continue;
+        }
+        if (arg.startsWith("--server=")) {
+            raw.apiBaseUrl = arg.slice("--server=".length);
+            continue;
+        }
+        if (arg === "--root") {
+            raw.root = resolve(requireOptionValue(args, ++index, "--root"));
+            continue;
+        }
+        if (arg.startsWith("--root=")) {
+            raw.root = resolve(arg.slice("--root=".length));
+            continue;
+        }
+        if (arg === "--force") {
+            raw.force = true;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            throw new Error(`Unknown ${command} option: ${arg}`);
+        }
+        if (!raw.projectId) {
+            raw.projectId = normalizeProjectValue(arg, "project");
+            continue;
+        }
+        throw new Error(`Unexpected ${command} argument: ${arg}`);
+    }
+    if (!raw.projectId) {
+        throw new Error(`tapi ${command} requires --project <id>.`);
+    }
+    return {
+        force: raw.force ?? false,
+        projectId: raw.projectId,
+        projectSlug: raw.projectSlug,
+        apiBaseUrl: raw.apiBaseUrl ? normalizeHttpUrl(raw.apiBaseUrl, "Tapi API base URL") : undefined,
+        root: raw.root,
+    };
+}
+async function writeWorkspace(command, args) {
+    try {
+        const options = parseWorkspaceOptions(command, args);
+        const workspace = await writeWorkspaceConfig(options);
+        console.log(`Tapi workspace ${command === "init" ? "initialized" : "linked"}: ${workspace.configPath}`);
+        console.log(`Project: ${workspace.projectId}`);
+        if (workspace.apiBaseUrl) {
+            console.log(`API: ${workspace.apiBaseUrl}`);
+        }
+        return 0;
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+async function runServiceCommand(action, args = []) {
+    try {
+        ensureWindowsHost();
+        const normalized = action.toLowerCase();
+        if (!["status", "install", "start", "stop", "restart", "repair"].includes(normalized)) {
+            throw new Error(`Unknown service command: ${action}`);
+        }
+        if (normalized === "install") {
+            return installService(parseStudioOptions(args));
+        }
+        if (normalized === "repair" && args.length > 0) {
+            return repairService(parseStudioOptions(args));
+        }
+        if (args.length > 0) {
+            throw new Error(`tapi service ${normalized} does not accept options.`);
+        }
+        if (normalized === "repair") {
+            return repairService(parseStudioOptions([]));
+        }
+        const command = servicePowerShell(normalized);
+        const output = await runProcessCapture("powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", command]);
+        if (output.trim()) {
+            console.log(output.trim());
+        }
+        return 0;
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+async function repairService(options) {
+    const status = await getServiceStatus();
+    if (!status.installed) {
+        return installService(options);
+    }
+    return runServiceCommand("restart");
+}
+function servicePowerShell(action) {
+    const serviceName = "tapi-service";
+    const status = `$svc = Get-Service -Name '${serviceName}' -ErrorAction SilentlyContinue; if ($null -eq $svc) { [pscustomobject]@{ installed = $false; name = '${serviceName}'; status = 'not_installed' } | ConvertTo-Json -Compress; exit 0 }; [pscustomobject]@{ installed = $true; name = $svc.Name; status = $svc.Status.ToString() } | ConvertTo-Json -Compress`;
+    if (action === "status") {
+        return status;
+    }
+    if (action === "start") {
+        return `Start-Service -Name '${serviceName}' -ErrorAction Stop; ${status}`;
+    }
+    if (action === "stop") {
+        return `Stop-Service -Name '${serviceName}' -ErrorAction Stop; ${status}`;
+    }
+    if (action === "restart" || action === "repair") {
+        return `Restart-Service -Name '${serviceName}' -Force -ErrorAction Stop; ${status}`;
+    }
+    return status;
+}
+async function getServiceStatus() {
+    const output = await runProcessCapture("powershell.exe", [
+        "-NoProfile",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-Command",
+        servicePowerShell("status"),
+    ]);
+    try {
+        const payload = JSON.parse(output.trim());
+        return {
+            installed: Boolean(payload.installed),
+            name: typeof payload.name === "string" ? payload.name : "tapi-service",
+            status: typeof payload.status === "string" ? payload.status : "unknown",
+        };
+    }
+    catch {
+        return { installed: false, name: "tapi-service", status: "unknown" };
+    }
+}
+async function ensureServiceReadyForStudio(options) {
+    const status = await getServiceStatus();
+    if (!status.installed) {
+        console.log("Tapi Service is required and is not installed. Installing it now...");
+        const code = await installService(options);
+        if (code !== 0) {
+            throw new Error("Tapi Service install failed.");
+        }
+        return;
+    }
+    if (status.status !== "Running") {
+        console.log("Starting Tapi Service...");
+        const output = await runProcessCapture("powershell.exe", [
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-Command",
+            servicePowerShell("start"),
+        ]);
+        if (output.trim()) {
+            console.log(output.trim());
+        }
+    }
+}
+async function installService(options) {
+    const event = await createCliWideEvent("tapi_cli.service_install", {
+        sdk_version: sdkVersion,
+        options: installEventOptions(options),
+    });
+    try {
+        await event.phase("host.check", {
+            platform: process.platform,
+            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...`);
+        await event.phase("service_manifest.fetch.start", {
+            apiBaseUrl: options.apiBaseUrl,
+            channel: options.channel,
+        });
+        const manifest = await fetchProtectedServiceManifest(options.apiBaseUrl, options.channel, installToken);
+        await event.phase("service_manifest.fetch.success", {
+            manifest: serviceManifestEventSummary(manifest),
+        });
+        ensureCompatibleServiceManifest(manifest);
+        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 verified = await hasVerifiedCachedInstaller(zipPath, manifest.sha256);
+        if (verified) {
+            console.log(`Using cached Tapi Service artifact: ${zipPath}`);
+            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 event.phase("download.verified", {
+                zipPath,
+                expectedSha256: manifest.sha256,
+            });
+        }
+        if (options.downloadOnly) {
+            console.log(`Downloaded Tapi Service artifact: ${zipPath}`);
+            await event.finish(true, {
+                zipPath,
+                downloadOnly: true,
+            });
+            return 0;
+        }
+        const releaseDir = join(releasesDir, safePathSegment(manifest.version));
+        await extractZip(zipPath, releaseDir);
+        const installer = join(releaseDir, manifest.installer || "install_tapi_service.ps1");
+        const hostExe = join(releaseDir, manifest.serviceHostExecutable || "tapi-service-host.exe");
+        if (!existsSync(installer)) {
+            throw new Error(`Tapi Service installer was not found after extraction: ${installer}`);
+        }
+        if (!existsSync(hostExe)) {
+            throw new Error(`Tapi Service host executable was not found after extraction: ${hostExe}`);
+        }
+        console.log(`Installing Tapi Service ${manifest.version}...`);
+        await event.phase("service_installer.start", {
+            installer,
+            hostExe,
+            releaseDir,
+        });
+        await runProcess("powershell.exe", [
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-File",
+            installer,
+            "-ExecutablePath",
+            hostExe,
+            "-WorkingDirectory",
+            releaseDir,
+        ]);
+        await event.finish(true, {
+            releaseDir,
+            version: manifest.version,
+        });
+        console.log("Tapi Service is installed and running.");
+        return 0;
+    }
+    catch (error) {
+        await event.finish(false, {
+            error: errorDetails(error),
+        });
+        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.");
+        }
+        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";
+        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() {
     if (process.platform === "win32") {
         const localAppData = process.env.LOCALAPPDATA ??
@@ -267,6 +932,14 @@ export function getDefaultStudioCacheDir() {
     }
     return join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "tapi", "studio");
 }
+export function getDefaultServiceCacheDir() {
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA ??
+            (process.env.USERPROFILE ? join(process.env.USERPROFILE, "AppData", "Local") : join(homedir(), "AppData", "Local"));
+        return join(localAppData, "Tapi", "Service");
+    }
+    return join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "tapi", "service");
+}
 export class CliWideEvent {
     filePath;
     startedAt = performance.now();
@@ -432,12 +1105,46 @@ export function validateStudioManifest(input) {
         commitShort: optionalString(record, "commitShort"),
         ref: optionalString(record, "ref"),
         installerKind: optionalString(record, "installerKind"),
+        serverExecutable: optionalString(record, "serverExecutable"),
     };
     if (!/^[a-f0-9]{64}$/i.test(manifest.sha256)) {
         throw new Error("Studio manifest sha256 must be a 64-character hex digest.");
     }
     return manifest;
 }
+export function validateServiceReleaseManifest(input) {
+    if (!input || typeof input !== "object") {
+        throw new Error("Tapi Service manifest response was not a JSON object.");
+    }
+    const record = input;
+    const contents = Array.isArray(record.contents)
+        ? record.contents.filter((item) => typeof item === "string")
+        : undefined;
+    const manifest = {
+        product: optionalString(record, "product"),
+        version: requiredString(record, "version"),
+        channel: requiredString(record, "channel"),
+        platform: requiredString(record, "platform"),
+        artifactName: requiredString(record, "artifactName"),
+        url: normalizeHttpUrl(requiredString(record, "url"), "Tapi Service manifest url"),
+        sha256: requiredString(record, "sha256").toLowerCase(),
+        sizeBytes: optionalNumber(record, "sizeBytes"),
+        serviceHostExecutable: optionalString(record, "serviceHostExecutable"),
+        workerExecutable: optionalString(record, "workerExecutable"),
+        installer: optionalString(record, "installer"),
+        uninstaller: optionalString(record, "uninstaller"),
+        builtAt: optionalString(record, "builtAt"),
+        commit: optionalString(record, "commit"),
+        commitShort: optionalString(record, "commitShort"),
+        ref: optionalString(record, "ref"),
+        mobileChrome: isRecord(record.mobileChrome) ? record.mobileChrome : undefined,
+        contents,
+    };
+    if (!/^[a-f0-9]{64}$/i.test(manifest.sha256)) {
+        throw new Error("Tapi Service manifest sha256 must be a 64-character hex digest.");
+    }
+    return manifest;
+}
 export function compareVersions(left, right) {
     const leftParts = versionCore(left);
     const rightParts = versionCore(right);
@@ -503,6 +1210,15 @@ async function installStudio(options) {
             minSdkVersion: manifest.minSdkVersion,
             platform: manifest.platform,
         });
+        if (isPortableStudioServerManifest(manifest)) {
+            const serverExe = await installPortableStudioServer(options, manifest, event);
+            await event.finish(true, {
+                serverExe,
+                downloadOnly: options.downloadOnly,
+                installerKind: manifest.installerKind,
+            });
+            return 0;
+        }
         await mkdir(options.cacheDir, { recursive: true });
         const installerPath = join(options.cacheDir, cachedInstallerName(manifest));
         await event.phase("cache.check.start", {
@@ -602,7 +1318,26 @@ async function obtainStudioInstallToken(options, event) {
 }
 async function openStudio(options) {
     ensureWindowsHost();
-    const exePath = options.exePath ?? getStudioExecutableCandidates().find((candidate) => existsSync(candidate));
+    if (options.downloadOnly) {
+        throw new Error("--download-only is only supported with `tapi studio install`.");
+    }
+    await ensureServiceReadyForStudio(options);
+    if (!options.exePath) {
+        const portable = await ensurePortableStudioServer(options);
+        if (portable) {
+            await launchPortableStudioServer(portable.exePath, options);
+            return 0;
+        }
+    }
+    let exePath = findStudioExecutable(options);
+    if (!exePath && !options.exePath) {
+        console.log("Tapi Studio executable was not found. Installing Tapi Studio now...");
+        const installCode = await installStudio(options);
+        if (installCode !== 0) {
+            return installCode;
+        }
+        exePath = findStudioExecutable(options);
+    }
     if (!exePath || !existsSync(exePath)) {
         console.error("Tapi Studio executable was not found.");
         console.error("Run `npx tapi studio install --channel pilot`, or set TAPI_STUDIO_EXE to the installed executable path.");
@@ -610,6 +1345,7 @@ async function openStudio(options) {
     }
     const child = spawn(exePath, [], {
         detached: true,
+        env: buildStudioLaunchEnv(options),
         stdio: "ignore",
         windowsHide: false,
     });
@@ -617,6 +1353,141 @@ async function openStudio(options) {
     console.log(`Opened Tapi Studio: ${exePath}`);
     return 0;
 }
+function findStudioExecutable(options) {
+    if (options.exePath) {
+        return existsSync(options.exePath) ? options.exePath : undefined;
+    }
+    return getStudioExecutableCandidates().find((candidate) => existsSync(candidate));
+}
+async function ensurePortableStudioServer(options) {
+    const event = await createCliWideEvent("tapi_cli.studio_server_ensure", {
+        sdk_version: sdkVersion,
+        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,
+            });
+        }
+        await event.phase("manifest.fetch.start", {
+            apiBaseUrl: options.apiBaseUrl,
+            channel: options.channel,
+        });
+        const manifest = await fetchProtectedStudioManifest(options.apiBaseUrl, options.channel, installToken);
+        ensureCompatibleManifest(manifest);
+        await event.phase("manifest.fetch.success", {
+            manifest: manifestEventSummary(manifest),
+        });
+        if (!isPortableStudioServerManifest(manifest)) {
+            await event.finish(true, {
+                installerKind: manifest.installerKind || "legacy",
+            });
+            return null;
+        }
+        const existing = findPortableStudioServerExe(portableStudioServerReleaseDir(manifest), manifest);
+        if (existing) {
+            await event.finish(true, {
+                serverExe: existing,
+                cacheHit: true,
+            });
+            return { exePath: existing, manifest };
+        }
+        const exePath = await installPortableStudioServer(options, manifest, event);
+        await event.finish(true, {
+            serverExe: exePath,
+            cacheHit: false,
+        });
+        return { exePath, manifest };
+    }
+    catch (error) {
+        await event.finish(false, {
+            error: errorDetails(error),
+        });
+        throw error;
+    }
+}
+async function installPortableStudioServer(options, manifest, event) {
+    await mkdir(options.cacheDir, { recursive: true });
+    const artifactPath = join(options.cacheDir, cachedInstallerName(manifest));
+    const verified = await hasVerifiedCachedInstaller(artifactPath, manifest.sha256);
+    if (verified) {
+        console.log(`Using cached Tapi Studio server artifact: ${artifactPath}`);
+        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 event.phase("download.verified", {
+            artifactPath,
+            expectedSha256: manifest.sha256,
+        });
+    }
+    if (options.downloadOnly) {
+        console.log(`Downloaded Tapi Studio server artifact: ${artifactPath}`);
+        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}`);
+    }
+    console.log(`Installed Tapi Studio server ${manifest.version}: ${releaseDir}`);
+    return exePath;
+}
+async function launchPortableStudioServer(exePath, options) {
+    const host = "127.0.0.1";
+    const port = await chooseStudioPort();
+    const env = buildStudioLaunchEnv(options);
+    env.TAPI_RUNTIME_MODE = "installed";
+    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_OPEN_BROWSER = "0";
+    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();
+    const url = `http://${host}:${port}`;
+    openBrowser(url);
+    console.log(`Opened Tapi Studio: ${url}`);
+}
+async function chooseStudioPort(preferred = 18766) {
+    for (let port = preferred; port < preferred + 25; port += 1) {
+        if (await isPortAvailable(port)) {
+            return port;
+        }
+    }
+    throw new Error(`No available local Studio port found starting at ${preferred}.`);
+}
+async function isPortAvailable(port) {
+    return await new Promise((resolvePromise) => {
+        const server = createNetServer();
+        server.once("error", () => resolvePromise(false));
+        server.listen(port, "127.0.0.1", () => {
+            server.close(() => resolvePromise(true));
+        });
+    });
+}
 async function runDoctor(options) {
     console.log(`Tapi SDK: ${sdkVersion}`);
     console.log(`Node: ${process.version}`);
@@ -625,6 +1496,8 @@ async function runDoctor(options) {
     console.log(`Studio channel: ${options.channel}`);
     console.log(`Studio manifest: ${options.manifestUrl}`);
     console.log(`Studio cache: ${options.cacheDir}`);
+    console.log(`Workspace: ${options.workspaceRoot ?? "not found"}`);
+    console.log(`Project: ${options.projectId ?? "not set"}`);
     const exePath = options.exePath ?? getStudioExecutableCandidates().find((candidate) => existsSync(candidate));
     console.log(`Studio executable: ${exePath && existsSync(exePath) ? exePath : "not found"}`);
     try {
@@ -638,6 +1511,27 @@ async function runDoctor(options) {
     }
     return 0;
 }
+function buildStudioLaunchEnv(options) {
+    const env = { ...process.env };
+    env.TAPI_STUDIO_API_BASE_URL = options.apiBaseUrl;
+    env.TAPI_BASE_URL = env.TAPI_BASE_URL || options.apiBaseUrl;
+    if (options.workspaceRoot) {
+        env.TAPI_WORKSPACE_ROOT = options.workspaceRoot;
+    }
+    if (options.workspace?.configPath) {
+        env.TAPI_WORKSPACE_CONFIG = options.workspace.configPath;
+    }
+    if (options.projectId) {
+        env.TAPI_PROJECT_ID = options.projectId;
+    }
+    if (options.projectSlug) {
+        env.TAPI_PROJECT_SLUG = options.projectSlug;
+    }
+    if (options.workspaceMode) {
+        env.TAPI_STUDIO_WORKSPACE_MODE = "1";
+    }
+    return env;
+}
 async function fetchProtectedStudioManifest(apiBaseUrl, channel, installToken, fetchImpl = fetch) {
     const response = await fetchImpl(`${apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/studio/releases/${channel}`, {
         headers: {
@@ -654,6 +1548,22 @@ async function fetchProtectedStudioManifest(apiBaseUrl, channel, installToken, f
     }
     return validateStudioManifest(responseBody);
 }
+async function fetchProtectedServiceManifest(apiBaseUrl, channel, installToken, fetchImpl = fetch) {
+    const response = await fetchImpl(`${apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/service/releases/${channel}`, {
+        headers: {
+            Accept: "application/json",
+            Authorization: `Bearer ${installToken}`,
+        },
+    });
+    const responseBody = await readJsonBody(response);
+    if (!response.ok) {
+        const detail = typeof responseBody?.detail === "string" ? responseBody.detail : "";
+        throw new Error(detail
+            ? `Failed to fetch protected Tapi Service manifest: HTTP ${response.status} (${detail})`
+            : `Failed to fetch protected Tapi Service manifest: HTTP ${response.status}`);
+    }
+    return validateServiceReleaseManifest(responseBody);
+}
 async function fetchStudioManifest(manifestUrl, fetchImpl = fetch) {
     const response = await fetchImpl(manifestUrl, {
         headers: {
@@ -696,24 +1606,24 @@ async function requestStudioInstallToken(apiBaseUrl, channel, firebaseIdToken, f
         expiresAt: typeof payload?.expiresAt === "string" ? payload.expiresAt : undefined,
     };
 }
-async function downloadAndVerify(url, destination, expectedSha256) {
+async function downloadAndVerify(url, destination, expectedSha256, label = "Studio installer") {
     const partialPath = `${destination}.partial`;
-    await downloadFile(url, partialPath);
+    await downloadFile(url, partialPath, label);
     const actualSha256 = await sha256File(partialPath);
     if (actualSha256 !== expectedSha256.toLowerCase()) {
         await unlinkIfExists(partialPath);
-        throw new Error(`Studio installer checksum mismatch. Expected ${expectedSha256}, got ${actualSha256}.`);
+        throw new Error(`${label} checksum mismatch. Expected ${expectedSha256}, got ${actualSha256}.`);
     }
     await rename(partialPath, destination);
     console.log(`Verified SHA256: ${actualSha256}`);
 }
-async function downloadFile(url, destination) {
+async function downloadFile(url, destination, label = "download") {
     const response = await fetch(url);
     if (!response.ok) {
-        throw new Error(`Failed to download Studio installer: HTTP ${response.status}`);
+        throw new Error(`Failed to download ${label}: HTTP ${response.status}`);
     }
     if (!response.body) {
-        throw new Error("Studio installer response did not include a body.");
+        throw new Error(`${label} response did not include a body.`);
     }
     await pipeline(Readable.fromWeb(response.body), createWriteStream(destination));
 }
@@ -937,6 +1847,32 @@ async function runProcess(command, args) {
         });
     });
 }
+async function runProcessCapture(command, args) {
+    return await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(command, args, {
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
+        child.once("error", rejectPromise);
+        child.once("exit", (code) => {
+            const err = stderr.trim();
+            if (code === 0) {
+                resolvePromise(stdout);
+            }
+            else {
+                rejectPromise(new Error(err || `Process exited with code ${code ?? "unknown"}.`));
+            }
+        });
+    });
+}
 function ensureWindowsHost() {
     if (process.platform !== "win32" || process.arch !== "x64") {
         throw new Error("Tapi Studio desktop installer is currently published for Windows x64 only.");
@@ -950,10 +1886,58 @@ function ensureCompatibleManifest(manifest) {
         throw new Error(`Tapi Studio ${manifest.version} requires @tapi-dev/sdk >= ${manifest.minSdkVersion}; installed SDK is ${sdkVersion}.`);
     }
 }
+function ensureCompatibleServiceManifest(manifest) {
+    if (manifest.platform !== SUPPORTED_STUDIO_PLATFORM) {
+        throw new Error(`This SDK expected ${SUPPORTED_STUDIO_PLATFORM}, but the Tapi Service manifest points to ${manifest.platform}.`);
+    }
+}
 function cachedInstallerName(manifest) {
     const rawName = manifest.artifactName || basename(new URL(manifest.url).pathname) || `TapiStudioSetup-${manifest.version}.exe`;
     return rawName.replace(/[^A-Za-z0-9._-]/g, "_");
 }
+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 getDefaultPortableStudioServerReleasesDir() {
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA ??
+            (process.env.USERPROFILE ? join(process.env.USERPROFILE, "AppData", "Local") : join(homedir(), "AppData", "Local"));
+        return join(localAppData, "Tapi", "Studio", "server", "releases");
+    }
+    return join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "tapi", "studio", "server", "releases");
+}
+function findPortableStudioServerExe(releaseDir, manifest) {
+    const executable = manifest.serverExecutable || "tapi-studio-server.exe";
+    const baseName = executable.toLowerCase().endsWith(".exe")
+        ? executable.slice(0, -4)
+        : executable;
+    const candidates = [
+        join(releaseDir, executable),
+        join(releaseDir, baseName, `${baseName}.exe`),
+        join(releaseDir, "tapi-studio-server.exe"),
+        join(releaseDir, "tapi-studio-server", "tapi-studio-server.exe"),
+    ];
+    return candidates.find((candidate) => existsSync(candidate));
+}
+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, "_");
+}
+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`,
+    ]);
+}
 function installEventOptions(options) {
     return {
         channel: options.channel,
@@ -967,6 +1951,22 @@ function installEventOptions(options) {
         installTokenProvided: Boolean(options.installToken),
     };
 }
+function serviceManifestEventSummary(manifest) {
+    return {
+        product: manifest.product,
+        version: manifest.version,
+        channel: manifest.channel,
+        platform: manifest.platform,
+        artifactName: manifest.artifactName,
+        url: manifest.url,
+        sha256: manifest.sha256,
+        sizeBytes: manifest.sizeBytes,
+        serviceHostExecutable: manifest.serviceHostExecutable,
+        workerExecutable: manifest.workerExecutable,
+        installer: manifest.installer,
+        commitShort: manifest.commitShort,
+    };
+}
 function manifestEventSummary(manifest) {
     return {
         product: manifest.product,
@@ -982,6 +1982,12 @@ function manifestEventSummary(manifest) {
         bundledService: manifest.bundledService,
     };
 }
+function safePathSegment(value) {
+    return String(value || "release").replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^_+|_+$/g, "") || "release";
+}
+function powerShellSingleQuoted(value) {
+    return `'${String(value).replace(/'/g, "''")}'`;
+}
 function parseChannel(value) {
     if (value === "pilot" || value === "stable" || value === "nightly") {
         return value;
@@ -1067,52 +2073,117 @@ function readSdkVersion() {
 function printHelp() {
     console.log(`Tapi CLI
 
-Usage:
-  tapi studio install [--channel pilot] [--api-base-url URL]
-  tapi studio open
-  tapi studio doctor
-  tapi apis describe <namespace.operation>
-  tapi doctor
-
-Commands:
-  studio install  Download, verify, and run the Tapi Studio installer
-  studio open     Open an installed Tapi Studio desktop app
-  studio doctor   Check local SDK and Studio release configuration
-  apis describe   Print a generated website API input/output contract
-  doctor          Alias for studio doctor
+Usage:
+  tapi init --project PROJECT
+  tapi link --project PROJECT
+  tapi studio install [--channel pilot] [--api-base-url URL]
+  tapi studio
+  tapi studio open
+  tapi studio doctor
+  tapi apis describe <namespace.operation>
+  tapi apis sync
+  tapi apis generate
+  tapi publish
+  tapi service status
+  tapi doctor
+
+Commands:
+  init            Create .tapi/project.json for this repo
+  link            Rebind this repo to an existing Tapi project
+  studio install  Download, verify, and run the Tapi Studio installer
+  studio          Open Tapi Studio for this repo
+  studio open     Open Tapi Studio for this repo
+  studio doctor   Check local SDK and Studio release configuration
+  apis describe   Print a generated website API input/output contract
+  apis sync       Save the published API catalog to .tapi/generated
+  apis generate   Generate a TypeScript runtime wrapper from the catalog
+  publish         Upload local .tapi API drafts and publish ready requests
+  service         Inspect or control the local Tapi Windows service
+  doctor          Alias for studio doctor
 `);
 }
 function printApisHelp() {
-    console.log(`Tapi generated website API commands
-
-Usage:
-  tapi apis describe <namespace.operation> [--api-base-url URL] [--api-key KEY] [--app APP]
-
-Options:
-  --api-base-url <url>   Tapi API base URL
-  --server <url>         Alias for --api-base-url
-  --api-key <key>        Tapi API key; defaults to TAPI_API_KEY
-  --app <id>             SDK app/project id; defaults to TAPI_APP_ID
+    console.log(`Tapi generated website API commands
+
+Usage:
+  tapi apis describe <namespace.operation> [--api-base-url URL] [--api-key KEY] [--project PROJECT]
+  tapi apis sync [--api-base-url URL] [--api-key KEY] [--project PROJECT]
+  tapi apis generate [--api-base-url URL] [--api-key KEY] [--project PROJECT] [--out FILE]
+
+Options:
+  --api-base-url <url>   Tapi API base URL
+  --server <url>         Alias for --api-base-url
+  --api-key <key>        Tapi API key; defaults to TAPI_API_KEY
+  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
+  --catalog <path>       Catalog JSON output path
+  --out <path>           Generated TypeScript output path
 `);
 }
 function printStudioHelp() {
-    console.log(`Tapi Studio commands
-
-Usage:
-  tapi studio install [options]
-  tapi studio open [options]
-  tapi studio doctor [options]
-
-Options:
+    console.log(`Tapi Studio commands
+
+Usage:
+  tapi studio [options]
+  tapi studio install [options]
+  tapi studio open [options]
+  tapi studio doctor [options]
+
+Options:
   --channel <name>       Release channel: pilot, stable, or nightly
   --api-base-url <url>   Tapi API base URL for approval and protected downloads
-  --server <url>         Alias for --api-base-url
-  --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
-  --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
+  --server <url>         Alias for --api-base-url
+  --workspace <path>     Search this directory for .tapi/project.json
+  --no-workspace         Do not load .tapi/project.json
+  --project <id>         Tapi project id for workspace-bound Studio
+  --project-slug <slug>  Optional display slug for the bound project
+  --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
+  --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
+`);
+}
+function printWorkspaceHelp(command) {
+    console.log(`Tapi workspace ${command}
+
+Usage:
+  tapi ${command} --project PROJECT [--api-base-url URL] [--root PATH] [--force]
+
+Options:
+  --project <id>         Tapi project id/name to bind this repo to
+  --project-slug <slug>  Optional display slug
+  --api-base-url <url>   Tapi API base URL stored in .tapi/project.json
+  --server <url>         Alias for --api-base-url
+  --root <path>          Directory where .tapi/project.json should be written
+  --force                Overwrite an existing workspace config
+`);
+}
+function printServiceHelp() {
+    console.log(`Tapi service commands
+
+Usage:
+  tapi service status
+  tapi service start
+  tapi service stop
+  tapi service restart
+  tapi service repair
+
+Commands:
+  status    Print installed/running status for tapi-service
+  start     Start tapi-service
+  stop      Stop tapi-service
+  restart   Restart tapi-service
+  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) {