@tapi-dev/sdk 0.1.17 → 0.1.21

package/dist/cli.js

@@ -8,6 +8,7 @@ import { mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "n
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { performance } from "node:perf_hooks";
+import { emitKeypressEvents } from "node:readline";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -174,6 +175,23 @@ export async function runCli(argv = process.argv.slice(2)) {
         printTriggersHelp();
         return 1;
     }
+    if (command === "sessions") {
+        const sessionsCommand = subcommand && !subcommand.startsWith("-") ? subcommand : "list";
+        const sessionsArgs = subcommand && !subcommand.startsWith("-") ? rest : [subcommand, ...rest].filter(Boolean);
+        if (sessionsCommand === "help" || sessionsCommand === "--help" || sessionsCommand === "-h" || hasHelpFlag(sessionsArgs)) {
+            printSessionsHelp();
+            return 0;
+        }
+        if (sessionsCommand === "list") {
+            return listDevSessions(sessionsArgs);
+        }
+        if (sessionsCommand === "open") {
+            return openDevSession(sessionsArgs);
+        }
+        console.error(`Unknown sessions command: ${sessionsCommand}`);
+        printSessionsHelp();
+        return 1;
+    }
     if (command !== "studio") {
         console.error(`Unknown command: ${command}`);
         printHelp();
@@ -615,6 +633,350 @@ async function syncApiTriggers(args) {
         return 1;
     }
 }
+function parseSessionsOptions(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 site = "";
+    let sessionId = "";
+    let json = false;
+    let noInteractive = false;
+    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 === "--site") {
+            site = requireOptionValue(args, ++index, "--site").trim();
+            continue;
+        }
+        if (arg.startsWith("--site=")) {
+            site = arg.slice("--site=".length).trim();
+            continue;
+        }
+        if (arg === "--json") {
+            json = true;
+            noInteractive = true;
+            continue;
+        }
+        if (arg === "--no-interactive") {
+            noInteractive = true;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            throw new Error(`Unknown sessions option: ${arg}`);
+        }
+        if (!sessionId) {
+            sessionId = arg;
+            continue;
+        }
+        throw new Error(`Unexpected sessions argument: ${arg}`);
+    }
+    if (!apiKey) {
+        throw new Error("sessions command requires --api-key or TAPI_API_KEY.");
+    }
+    if (!projectId) {
+        throw new Error("sessions command requires --project, TAPI_PROJECT_ID, or .tapi/project.json.");
+    }
+    return {
+        sessionId,
+        options: {
+            apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
+            apiKey,
+            projectId,
+            site: site || undefined,
+            json,
+            noInteractive,
+        },
+    };
+}
+async function listDevSessions(args) {
+    try {
+        const { options } = parseSessionsOptions(args);
+        const sessions = await fetchDevSessions(options);
+        if (options.json) {
+            console.log(JSON.stringify(sessions, null, 2));
+            return 0;
+        }
+        const rows = flattenDevSessions(sessions);
+        if (rows.length === 0) {
+            console.log(`No Tapi dev sessions found for project ${sessions.projectId || options.projectId}.`);
+            return 0;
+        }
+        if (!options.noInteractive && process.stdin.isTTY && process.stdout.isTTY && rows.some((session) => session.openable)) {
+            return await runSessionsPicker(sessions, options);
+        }
+        console.log(renderDevSessions(sessions));
+        const openable = rows.find((session) => session.openable);
+        if (openable) {
+            console.log("\nOpen a takeover session with `tapi sessions open <session-id>`.");
+        }
+        return 0;
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+async function openDevSession(args) {
+    try {
+        const { sessionId, options } = parseSessionsOptions(args);
+        if (!sessionId) {
+            throw new Error("sessions open requires a session id.");
+        }
+        const sessions = await fetchDevSessions(options);
+        const session = findDevSession(sessions, sessionId);
+        if (!session) {
+            throw new Error(`Tapi session not found: ${sessionId}`);
+        }
+        return await openDevSessionInStudio(session, options);
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+async function fetchDevSessions(options) {
+    const client = new TapiClient({
+        baseUrl: options.apiBaseUrl,
+        apiKey: options.apiKey,
+        projectId: options.projectId,
+    });
+    return await withCliSpinner("Fetching Tapi dev sessions", () => client.sessions.list({ site: options.site }));
+}
+function flattenDevSessions(sessions) {
+    return (sessions.groups || []).flatMap((group) => group.sessions || []);
+}
+function findDevSession(sessions, sessionId) {
+    const normalized = sessionId.trim();
+    return flattenDevSessions(sessions).find((session) => session.id === normalized || session.id.startsWith(normalized));
+}
+async function runSessionsPicker(sessions, options) {
+    let currentSessions = sessions;
+    let rows = flattenDevSessions(currentSessions);
+    let openableIndexes = openableSessionIndexes(rows);
+    if (openableIndexes.length === 0) {
+        console.log(renderDevSessions(currentSessions));
+        return 0;
+    }
+    let selectedIndex = openableIndexes[0];
+    const input = process.stdin;
+    return await new Promise((resolvePromise) => {
+        let onKeypress;
+        const cleanup = () => {
+            input.off("keypress", onKeypress);
+            input.setRawMode?.(false);
+            input.pause();
+        };
+        const move = (direction) => {
+            if (openableIndexes.length === 0)
+                return;
+            const currentOpenableIndex = openableIndexes.indexOf(selectedIndex);
+            const nextOpenableIndex = (currentOpenableIndex + direction + openableIndexes.length) % openableIndexes.length;
+            selectedIndex = openableIndexes[nextOpenableIndex];
+            render();
+        };
+        const render = () => {
+            process.stdout.write("\x1Bc");
+            process.stdout.write(renderDevSessions(currentSessions, rows[selectedIndex]?.id));
+            process.stdout.write("\n\nUse Up/Down and Enter to open Studio. Press r to refresh, q to exit.\n");
+        };
+        const finish = (code) => {
+            cleanup();
+            resolvePromise(code);
+        };
+        onKeypress = (_input, key = {}) => {
+            if (key.ctrl && key.name === "c") {
+                finish(130);
+                return;
+            }
+            if (key.name === "q" || key.name === "escape") {
+                finish(0);
+                return;
+            }
+            if (key.name === "up") {
+                move(-1);
+                return;
+            }
+            if (key.name === "down") {
+                move(1);
+                return;
+            }
+            if (key.name === "r") {
+                fetchDevSessions(options)
+                    .then((nextSessions) => {
+                    currentSessions = nextSessions;
+                    rows = flattenDevSessions(currentSessions);
+                    openableIndexes = openableSessionIndexes(rows);
+                    if (!rows[selectedIndex]?.openable) {
+                        selectedIndex = openableIndexes[0] ?? 0;
+                    }
+                    render();
+                })
+                    .catch((error) => {
+                    process.stderr.write(`\n${formatError(error)}\n`);
+                    render();
+                });
+                return;
+            }
+            if (key.name === "return" || key.name === "enter") {
+                const session = rows[selectedIndex];
+                if (!session?.openable) {
+                    return;
+                }
+                cleanup();
+                openDevSessionInStudio(session, options)
+                    .then(resolvePromise)
+                    .catch((error) => {
+                    console.error(formatError(error));
+                    resolvePromise(1);
+                });
+            }
+        };
+        emitKeypressEvents(input);
+        input.setRawMode?.(true);
+        input.resume();
+        input.on("keypress", onKeypress);
+        render();
+    });
+}
+function openableSessionIndexes(rows) {
+    return rows
+        .map((session, index) => (session.openable ? index : -1))
+        .filter((index) => index >= 0);
+}
+async function openDevSessionInStudio(session, options) {
+    if (!session.openable) {
+        throw new Error(`Tapi session ${session.id} is not awaiting developer takeover.`);
+    }
+    const params = studioSessionLaunchParams(session);
+    const studioOptions = parseStudioOptions([
+        "--api-base-url",
+        options.apiBaseUrl,
+        "--project",
+        options.projectId,
+    ]);
+    studioOptions.launchUrlQuery = params.toString();
+    const selected = await trySelectDevSessionInOpenStudio(session, studioOptions);
+    if (selected.selected) {
+        console.log(`Selected Tapi Studio session in existing Studio: ${selected.baseUrl}`);
+        return 0;
+    }
+    return await openStudio(studioOptions);
+}
+function studioSessionLaunchParams(session) {
+    const params = new URLSearchParams();
+    params.set("runId", session.id);
+    params.set("apiRunId", session.id);
+    if (session.sitemap)
+        params.set("sitemap", session.sitemap);
+    if (session.runtimeSessionId)
+        params.set("runtimeSessionId", session.runtimeSessionId);
+    return params;
+}
+function studioSessionSelectIntent(session) {
+    return {
+        sessionId: session.id,
+        runId: session.id,
+        apiRunId: session.id,
+        ...(session.sitemap ? { sitemap: session.sitemap } : {}),
+        ...(session.runtimeSessionId ? { runtimeSessionId: session.runtimeSessionId } : {}),
+        source: "cli",
+        selectedAt: new Date().toISOString(),
+    };
+}
+export async function trySelectDevSessionInOpenStudio(session, options, fetchImpl = fetch) {
+    const record = await readStudioInstanceRecord(options);
+    if (!record) {
+        return { selected: false, reason: "instance_record_missing" };
+    }
+    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 { selected: false, reason: `identity_http_${identityResponse.status}` };
+        }
+        const identity = await readJsonBody(identityResponse);
+        if (!studioInstanceIdentityMatches(identity, options)) {
+            return { selected: false, reason: "identity_mismatch" };
+        }
+        const selectResponse = await fetchWithTimeout(`${record.baseUrl.replace(/\/+$/, "")}/api/studio/control/select-session`, {
+            method: "POST",
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(studioSessionSelectIntent(session)),
+        }, 1_500, fetchImpl);
+        if (!selectResponse.ok) {
+            return { selected: false, reason: `select_http_${selectResponse.status}` };
+        }
+        return { selected: true, baseUrl: record.baseUrl };
+    }
+    catch (error) {
+        return { selected: false, reason: formatError(error) };
+    }
+}
+function renderDevSessions(sessions, selectedId = "") {
+    const lines = [`Tapi sessions for project ${sessions.projectId || "unknown"}`];
+    for (const group of sessions.groups || []) {
+        lines.push("");
+        lines.push(`[${group.sitemap || "unknown"}]`);
+        if (!group.sessions || group.sessions.length === 0) {
+            lines.push("  No sessions.");
+            continue;
+        }
+        for (const session of group.sessions) {
+            const selected = selectedId && session.id === selectedId ? ">" : " ";
+            const openable = session.openable ? "*" : " ";
+            const id = truncateText(session.id || "", 18).padEnd(18, " ");
+            const status = truncateText(String(session.status || ""), 24).padEnd(24, " ");
+            const apiName = session.apiName && session.requestKey
+                ? `${session.apiName}.${session.requestKey}`
+                : session.apiName || session.requestKey || "unknown";
+            const state = session.stateLabel ? ` state=${session.stateLabel}` : "";
+            const url = session.currentUrl ? ` ${truncateText(session.currentUrl, 60)}` : "";
+            lines.push(`${selected}${openable} ${id} ${status} ${apiName}${state}${url}`);
+        }
+    }
+    lines.push("");
+    lines.push("* openable awaiting-takeover session");
+    return lines.join("\n");
+}
+function truncateText(value, maxLength) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, Math.max(0, maxLength - 3))}...`;
+}
 function defaultTriggerConfigPath(root) {
     for (const name of ["tapi.config.ts", "tapi.config.mjs", "tapi.config.js", "tapi.config.cjs", "tapi.config.json"]) {
         const path = join(root, name);
@@ -856,23 +1218,23 @@ function renderGeneratedApiClient(catalog) {
         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")}
-  };
-}
+    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) {
@@ -1889,7 +2251,7 @@ async function openStudio(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.");
+        console.error("Run `tapi studio install --channel pilot`, or set TAPI_STUDIO_EXE to the installed executable path.");
         return 1;
     }
     const child = spawn(exePath, [], {
@@ -2004,6 +2366,9 @@ 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;
+    let childPid = 0;
     await withCliSpinner("Starting Tapi Studio", async () => {
         const child = spawn(exePath, [], {
             detached: true,
@@ -2011,11 +2376,25 @@ async function launchPortableStudioServer(exePath, options, manifest) {
             stdio: "ignore",
             windowsHide: true,
         });
+        childPid = child.pid ?? 0;
         child.unref();
         await waitForHttpOk(`${url}/healthz`, PORTABLE_STUDIO_SERVER_READY_TIMEOUT_MS, PORTABLE_STUDIO_SERVER_READY_INTERVAL_MS);
     });
-    openBrowser(url);
-    console.log(`Opened Tapi Studio ${manifest.version}: ${url}`);
+    await writeStudioInstanceRecord(options, {
+        version: 1,
+        baseUrl: url,
+        host,
+        port,
+        pid: childPid || undefined,
+        apiBaseUrl: options.apiBaseUrl,
+        projectId: options.projectId,
+        workspaceRoot: options.workspaceRoot,
+        workspaceConfig: options.workspace?.configPath,
+        manifestVersion: manifest.version,
+        updatedAt: new Date().toISOString(),
+    });
+    openBrowser(launchUrl);
+    console.log(`Opened Tapi Studio ${manifest.version}: ${launchUrl}`);
 }
 export function findPortablePlaywrightBrowsersDir(exePath) {
     const exeDir = dirname(exePath);
@@ -2061,6 +2440,19 @@ export async function waitForHttpOk(url, timeoutMs = PORTABLE_STUDIO_SERVER_READ
     const suffix = lastError ? ` Last error: ${lastError}.` : "";
     throw new Error(`Tapi Studio server did not become ready at ${url} within ${Math.ceil(timeoutMs / 1000)}s.${suffix}`);
 }
+async function fetchWithTimeout(url, init, timeoutMs, fetchImpl = fetch) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), Math.max(1, timeoutMs));
+    try {
+        return await fetchImpl(url, {
+            ...init,
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
 function delay(ms) {
     return new Promise((resolvePromise) => {
         setTimeout(resolvePromise, Math.max(0, ms));
@@ -2184,7 +2576,7 @@ async function requestStudioInstallToken(apiBaseUrl, channel, firebaseIdToken, f
     if (!response.ok) {
         const detail = typeof responseBody?.detail === "string" ? responseBody.detail : "";
         if (detail === "pending_approval" || detail === "access_pending") {
-            throw new StudioInstallApprovalError("Access request submitted. Check your email for approval, then rerun `npx tapi studio install`.", detail, response.status);
+            throw new StudioInstallApprovalError("Access request submitted. Check your email for approval, then rerun `tapi studio install`.", detail, response.status);
         }
         if (detail === "access_rejected") {
             throw new StudioInstallApprovalError("Studio install access was rejected. Contact the Tapi admin if this is unexpected.", detail, response.status);
@@ -2371,6 +2763,81 @@ async function writeStudioAuthCache(credentials) {
 function getStudioAuthCachePath() {
     return join(getDefaultTapiDataDir(), "auth.json");
 }
+export function studioInstanceRecordPathForOptions(options) {
+    const key = createHash("sha256")
+        .update(JSON.stringify({
+        apiBaseUrl: comparableHttpUrl(options.apiBaseUrl),
+        projectId: options.projectId ?? "",
+        workspaceRoot: comparableFsPath(options.workspaceRoot ?? ""),
+    }))
+        .digest("hex")
+        .slice(0, 24);
+    return join(getDefaultTapiDataDir(), "Studio", "instances", `${key}.json`);
+}
+async function writeStudioInstanceRecord(options, record) {
+    await writeJsonFile(studioInstanceRecordPathForOptions(options), record);
+}
+async function readStudioInstanceRecord(options) {
+    try {
+        const parsed = JSON.parse(await readFile(studioInstanceRecordPathForOptions(options), "utf8"));
+        if (!isRecord(parsed)) {
+            return null;
+        }
+        const baseUrl = typeof parsed.baseUrl === "string" ? parsed.baseUrl.trim() : "";
+        const host = typeof parsed.host === "string" ? parsed.host.trim() : "";
+        const port = typeof parsed.port === "number" && Number.isFinite(parsed.port) ? parsed.port : 0;
+        if (!baseUrl || !host || port <= 0) {
+            return null;
+        }
+        return {
+            version: 1,
+            baseUrl,
+            host,
+            port,
+            pid: typeof parsed.pid === "number" && Number.isFinite(parsed.pid) ? parsed.pid : undefined,
+            apiBaseUrl: typeof parsed.apiBaseUrl === "string" ? parsed.apiBaseUrl : "",
+            projectId: typeof parsed.projectId === "string" ? parsed.projectId : undefined,
+            workspaceRoot: typeof parsed.workspaceRoot === "string" ? parsed.workspaceRoot : undefined,
+            workspaceConfig: typeof parsed.workspaceConfig === "string" ? parsed.workspaceConfig : undefined,
+            manifestVersion: typeof parsed.manifestVersion === "string" ? parsed.manifestVersion : undefined,
+            updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : "",
+        };
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return null;
+        }
+        return null;
+    }
+}
+function studioInstanceIdentityMatches(identity, options) {
+    if (!identity || identity.ok !== true) {
+        return false;
+    }
+    const expectedProject = (options.projectId ?? "").trim();
+    const actualProject = typeof identity.projectId === "string" ? identity.projectId.trim() : "";
+    if (expectedProject && actualProject && actualProject !== expectedProject) {
+        return false;
+    }
+    const expectedWorkspace = comparableFsPath(options.workspaceRoot ?? "");
+    const actualWorkspace = comparableFsPath(typeof identity.workspaceRoot === "string" ? identity.workspaceRoot : "");
+    if (expectedWorkspace && actualWorkspace && actualWorkspace !== expectedWorkspace) {
+        return false;
+    }
+    const expectedApiBaseUrl = comparableHttpUrl(options.apiBaseUrl);
+    const actualApiBaseUrl = comparableHttpUrl(typeof identity.apiBaseUrl === "string" ? identity.apiBaseUrl : "");
+    if (expectedApiBaseUrl && actualApiBaseUrl && actualApiBaseUrl !== expectedApiBaseUrl) {
+        return false;
+    }
+    return true;
+}
+function comparableHttpUrl(value) {
+    return String(value || "").trim().replace(/\/+$/, "").toLowerCase();
+}
+function comparableFsPath(value) {
+    const trimmed = String(value || "").trim();
+    return trimmed ? resolve(trimmed).toLowerCase() : "";
+}
 function getDefaultTapiDataDir() {
     if (process.platform === "win32") {
         const localAppData = process.env.LOCALAPPDATA
@@ -2831,146 +3298,166 @@ function readSdkVersion() {
 function printHelp() {
     console.log(`Tapi CLI
 
-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 triggers sync
-  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
-  triggers sync   Upsert API-call triggers from tapi.config
-  publish         Upload local .tapi API drafts and publish ready requests
-  service         Inspect or control the local Tapi Windows service
-  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 triggers sync
+  tapi sessions
+  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
+  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
+`);
+}
+function printSessionsHelp() {
+    console.log(`Tapi dev session commands
+
+Usage:
+  tapi sessions [--api-base-url URL] [--api-key KEY] [--project PROJECT]
+  tapi sessions list [--json] [--site SITE]
+  tapi sessions open <session-id> [--api-base-url URL] [--api-key KEY] [--project PROJECT]
+
+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
+  --site <name>          Limit sessions to one sitemap/site
+  --json                 Print raw grouped session JSON
+  --no-interactive       Print the grouped list without the arrow-key picker
 `);
 }
 function printApisHelp() {
-    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
+    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 printTriggersHelp() {
-    console.log(`Tapi API trigger commands
-
-Usage:
-  tapi triggers sync [--config FILE] [--api-base-url URL] [--api-key KEY] [--project PROJECT]
-
-Options:
-  --config <path>        Trigger config path; defaults to tapi.config.ts/js/json in the workspace root
-  --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
-
-Config:
-  export default {
-    triggers: {
-      nightlyBalance: {
-        apiRequest: "schwab.get_balance",
-        interval: "1h",
-        inputs: { accountId: "main" },
-        runtime: { profileRef: "perm_default" },
-      },
-    },
-  };
+    console.log(`Tapi API trigger commands
+
+Usage:
+  tapi triggers sync [--config FILE] [--api-base-url URL] [--api-key KEY] [--project PROJECT]
+
+Options:
+  --config <path>        Trigger config path; defaults to tapi.config.ts/js/json in the workspace root
+  --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
+
+Config:
+  export default {
+    triggers: {
+      nightlyBalance: {
+        apiRequest: "schwab.get_balance",
+        interval: "1h",
+        inputs: { accountId: "main" },
+        runtime: { profileRef: "perm_default" },
+      },
+    },
+  };
 `);
 }
 function printStudioHelp() {
-    console.log(`Tapi Studio commands
-
-Usage:
-  tapi studio [options]
-  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 install authorization and protected downloads
-  --server <url>         Alias for --api-base-url
-  --workspace <path>     Search this directory for .tapi/project.json
-  --no-workspace         Do not load .tapi/project.json
-  --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
-  --install-dir <path>   Portable Studio server release directory
-  --download-only        Download and verify without running the installer
-  --silent               Run the NSIS installer with /S
-  --exe <path>           Tapi Studio executable path for open/doctor
+  --api-base-url <url>   Tapi API base URL for install authorization and protected downloads
+  --server <url>         Alias for --api-base-url
+  --workspace <path>     Search this directory for .tapi/project.json
+  --no-workspace         Do not load .tapi/project.json
+  --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
+  --install-dir <path>   Portable Studio server release directory
+  --download-only        Download and verify without running the installer
+  --silent               Run the NSIS installer with /S
+  --exe <path>           Tapi Studio executable path for open/doctor
 `);
 }
 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
+    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
+    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.
+    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) {