@velum-labs/cursorkit 0.1.0 → 0.1.2

package/dist/src/cursorDesktopState.js

@@ -0,0 +1,204 @@
+/**
+ * Builders that shape the Cursor desktop `applicationUser` state and local
+ * model catalog entries. Extracted from `ckLauncher` so the (large) launcher
+ * module is not also responsible for the desktop state-seed schema. These are
+ * pure data transforms over plain JSON-shaped records.
+ */
+export function mergeLocalAgentBackendUrlsIntoApplicationUser(applicationUser, agentOrigin) {
+    const cursorCreds = ensureRecord(applicationUser, "cursorCreds");
+    const urls = { default: agentOrigin };
+    cursorCreds.agentBackendUrlPrivacy = urls;
+    cursorCreds.agentBackendUrlNonPrivacy = urls;
+}
+export function mergeLocalDesktopModelsIntoApplicationUser(applicationUser, models) {
+    const localModelIds = new Set(models.map((model) => model.id));
+    const current = Array.isArray(applicationUser.availableDefaultModels2)
+        ? applicationUser.availableDefaultModels2.filter((item) => {
+            if (!isPlainRecord(item) || typeof item.name !== "string") {
+                return true;
+            }
+            return !localModelIds.has(item.name);
+        })
+        : [];
+    applicationUser.availableDefaultModels2 = current;
+    const aiSettings = ensureRecord(applicationUser, "aiSettings");
+    for (const model of models) {
+        appendUnique(ensureStringArray(aiSettings, "userAddedModels"), model.id);
+        appendUnique(ensureStringArray(aiSettings, "modelOverrideEnabled"), model.id);
+        removeValue(ensureStringArray(aiSettings, "modelOverrideDisabled"), model.id);
+    }
+    const preferences = ensureRecord(aiSettings, "modelParameterPreferences");
+    const updatedAt = new Date().toISOString();
+    for (const model of models) {
+        preferences[model.id] = {
+            modelId: model.id,
+            parameters: localDesktopParameterValues(true),
+            updatedAt,
+        };
+    }
+    const firstModel = models[0];
+    if (firstModel !== undefined) {
+        applicationUser.useOpenAIKey = true;
+        applicationUser.openAIBaseUrl = firstModel.baseUrl;
+        applicationUser.openAIKey = firstModel.apiKey;
+        const modelConfig = ensureRecord(aiSettings, "modelConfig");
+        const selectedModel = {
+            modelId: firstModel.id,
+            parameters: localDesktopParameterValues(true),
+        };
+        for (const key of ["composer", "background-composer"]) {
+            modelConfig[key] = {
+                modelName: firstModel.id,
+                maxMode: true,
+                selectedModels: [selectedModel],
+            };
+        }
+    }
+    const featureModelConfigs = ensureRecord(applicationUser, "featureModelConfigs");
+    for (const value of Object.values(featureModelConfigs)) {
+        if (!isPlainRecord(value)) {
+            continue;
+        }
+        const fallbackModels = ensureStringArray(value, "fallbackModels");
+        for (const model of models) {
+            appendUnique(fallbackModels, model.id);
+        }
+    }
+}
+export function buildLocalDesktopModelEntry(model) {
+    const tooltipData = {
+        primaryText: "",
+        secondaryText: "",
+        secondaryWarningText: false,
+        icon: "",
+        tertiaryText: "",
+        tertiaryTextUrl: "",
+        markdownContent: `**${model.displayName}**<br />Local OpenAI-compatible model served by cursorkit.<br /><br />${model.contextTokenLimit.toLocaleString()} token context window`,
+    };
+    return {
+        name: model.id,
+        serverModelName: model.id,
+        clientDisplayName: model.displayName,
+        inputboxShortModelName: model.displayName,
+        vendorName: "local",
+        vendor: { displayName: "Local" },
+        supportsAgent: true,
+        supportsCmdK: false,
+        supportsImages: false,
+        supportsMaxMode: true,
+        supportsNonMaxMode: true,
+        supportsPlanMode: true,
+        supportsSandboxing: false,
+        supportsThinking: false,
+        cloudAgentEffortModes: [],
+        defaultOn: true,
+        degradationStatus: 0,
+        isRecommendedForBackgroundComposer: false,
+        legacySlugs: [model.id],
+        idAliases: [model.id, model.displayName],
+        parameterDefinitions: localDesktopParameterDefinitions(),
+        namedModelSectionIndex: 10_000,
+        visibleInRoutedModelView: true,
+        tooltipData,
+        tooltipDataForMaxMode: tooltipData,
+        variants: [
+            localDesktopVariantConfig(model, tooltipData, false),
+            localDesktopVariantConfig(model, tooltipData, true),
+        ],
+    };
+}
+function localDesktopVariantConfig(model, tooltipData, isMaxMode) {
+    return {
+        parameterValues: localDesktopParameterValues(isMaxMode),
+        displayName: model.displayName,
+        isMaxMode,
+        isDefaultMaxConfig: isMaxMode,
+        isDefaultNonMaxConfig: !isMaxMode,
+        tooltipData,
+        displayNameOutsidePicker: model.displayName,
+        variantStringRepresentation: localDesktopVariantString(model.id, isMaxMode),
+        legacySlug: model.id,
+    };
+}
+function localDesktopVariantString(modelId, isMaxMode) {
+    const context = isMaxMode ? "1m" : "272k";
+    return `${modelId}[context=${context},reasoning=medium,fast=false]`;
+}
+function localDesktopParameterValues(isMaxMode) {
+    return [
+        { id: "context", value: isMaxMode ? "1m" : "272k" },
+        { id: "reasoning", value: "medium" },
+        { id: "fast", value: "false" },
+    ];
+}
+function localDesktopParameterDefinitions() {
+    return [
+        {
+            id: "context",
+            name: "Context",
+            markdownTooltip: "Context size the model has available.",
+            parameterType: {
+                enumParameter: {
+                    values: [
+                        { value: "272k", displayName: "272K" },
+                        { value: "1m", displayName: "1M" },
+                    ],
+                },
+            },
+        },
+        {
+            id: "reasoning",
+            name: "Reasoning",
+            markdownTooltip: "Reasoning effort the model uses to generate its response.",
+            parameterType: {
+                enumParameter: {
+                    values: [
+                        { value: "none", displayName: "None" },
+                        { value: "low", displayName: "Low" },
+                        { value: "medium", displayName: "Medium" },
+                        { value: "high", displayName: "High" },
+                        { value: "extra-high", displayName: "Extra High" },
+                    ],
+                },
+            },
+            isCycleableByHotkey: true,
+        },
+        {
+            id: "fast",
+            name: "Fast",
+            markdownTooltip: "Use the provider's fast lane when supported.",
+            parameterType: {
+                booleanParameter: {
+                    values: [{ value: "false" }, { value: "true", displayName: "Fast" }],
+                },
+            },
+        },
+    ];
+}
+function ensureRecord(target, key) {
+    if (!isPlainRecord(target[key])) {
+        target[key] = {};
+    }
+    return target[key];
+}
+function ensureStringArray(target, key) {
+    const values = Array.isArray(target[key])
+        ? target[key].filter((value) => typeof value === "string")
+        : [];
+    target[key] = values;
+    return values;
+}
+function appendUnique(values, value) {
+    if (!values.includes(value)) {
+        values.push(value);
+    }
+}
+function removeValue(values, value) {
+    const index = values.indexOf(value);
+    if (index !== -1) {
+        values.splice(index, 1);
+    }
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/src/desktopConnectProxy.d.ts

@@ -5,9 +5,19 @@ export interface DesktopConnectProxyOptions {
     bridgeHost: string;
     bridgePort: number;
     logPath?: string;
+    /**
+     * When true, CONNECT requests to non-Cursor hosts are tunneled through to
+     * their destination, turning this into an open forwarder. Defaults to false
+     * so only Cursor backends (cursorHostnames) are reachable.
+     */
     passthrough?: boolean;
     cursorHostnames?: readonly string[];
     headerTimeoutMs?: number;
+    /**
+     * Allow binding to a non-loopback host. Off by default to avoid exposing the
+     * proxy beyond the local machine.
+     */
+    allowExternalHost?: boolean;
 }
 export interface DesktopConnectProxy {
     server: net.Server;

package/dist/src/desktopConnectProxy.js

@@ -5,8 +5,11 @@ const CONNECT_LINE_PATTERN = /^CONNECT\s+([^\s]+)\s+HTTP\/\d(?:\.\d)?$/i;
 const DEFAULT_HEADER_TIMEOUT_MS = 5_000;
 const MAX_CONNECT_HEADER_BYTES = 32 * 1024;
 export async function startDesktopConnectProxy(options) {
+    if (options.allowExternalHost !== true && !isLoopbackHost(options.host)) {
+        throw new Error(`Refusing to bind CONNECT proxy to non-loopback host ${options.host}. Set allowExternalHost: true to override.`);
+    }
     const cursorHostnames = new Set(options.cursorHostnames ?? DESKTOP_HOSTNAMES);
-    const passthrough = options.passthrough ?? true;
+    const passthrough = options.passthrough ?? false;
     const activeSockets = new Set();
     const server = net.createServer((client) => {
         activeSockets.add(client);
@@ -155,6 +158,9 @@ function handleClient(client, options, cursorHostnames, passthrough, activeSocke
         });
     });
 }
+function isLoopbackHost(host) {
+    return host === "127.0.0.1" || host === "::1" || host === "localhost";
+}
 function parseConnectDestination(value) {
     if (value.startsWith("[")) {
         const closeBracket = value.indexOf("]");

package/dist/src/server.js

@@ -1,3 +1,4 @@
+import { timingSafeEqual } from "node:crypto";
 import http from "node:http";
 import http2 from "node:http2";
 import https from "node:https";
@@ -101,7 +102,9 @@ export async function createBridgeRuntime(config, logger) {
 }
 export async function startServer(runtime) {
     const listener = (request, response) => {
-        void handleRequest(runtime, request, response);
+        handleRequest(runtime, request, response).catch((error) => {
+            handleRequestFailure(runtime, response, error);
+        });
     };
     const server = runtime.config.useTls
         ? runtime.config.desktopMode
@@ -252,6 +255,35 @@ async function handleRequest(runtime, request, response) {
     }
     proxyRequest(request, response, runtime.config, runtime.logger);
 }
+function handleRequestFailure(runtime, response, error) {
+    runtime.logger.error("request handler crashed", {
+        error: error instanceof Error ? error.message : String(error),
+    });
+    try {
+        if (response.headersSent) {
+            response.destroy();
+            return;
+        }
+        response.writeHead(500, { "content-type": "application/json" });
+        response.end(JSON.stringify({ error: "internal bridge error" }));
+    }
+    catch {
+        response.destroy();
+    }
+}
+/**
+ * Length-independent constant-time comparison so bridge-token checks do not leak
+ * the secret via early-mismatch timing. A missing header never matches.
+ */
+function constantTimeEquals(value, expected) {
+    if (value === undefined)
+        return false;
+    const valueBuf = Buffer.from(value);
+    const expectedBuf = Buffer.from(expected);
+    if (valueBuf.length !== expectedBuf.length)
+        return false;
+    return timingSafeEqual(valueBuf, expectedBuf);
+}
 function authorizeRequest(runtime, request, response) {
     const token = runtime.config.authToken;
     if (token === undefined) {
@@ -259,7 +291,8 @@ function authorizeRequest(runtime, request, response) {
     }
     const authorization = headerValue(request.headers.authorization);
     const bridgeToken = headerValue(request.headers["x-cursor-rpc-auth"]);
-    const authorized = authorization === `Bearer ${token}` || bridgeToken === token;
+    const authorized = constantTimeEquals(authorization, `Bearer ${token}`) ||
+        constantTimeEquals(bridgeToken, token);
     if (authorized) {
         return true;
     }

package/dist/src/tools/releaseCheck.d.ts

@@ -20,7 +20,7 @@ export interface ReleaseCategoryStatus {
     optionalSuiteIds: string[];
     summary: string;
 }
-export declare const REQUIRED_PACKAGE_ENTRIES: readonly ["package/package.json", "package/README.md", "package/DISCLAIMER.md", "package/dist/src/cli.js", "package/dist/src/cli.d.ts", "package/dist/src/ck.js", "package/dist/src/ck.d.ts", "package/proto/agent/v1/agent.proto", "package/proto/aiserver/v1/aiserver.proto", "package/docs/protocol.md", "package/docs/release-gates.md", "package/docs/testing-harness.md", "package/docs/test-manifest.json", "package/docs/route-contract-manifest.json", "package/docs/release-summary.json"];
+export declare const REQUIRED_PACKAGE_ENTRIES: readonly ["package/package.json", "package/README.md", "package/DISCLAIMER.md", "package/dist/src/cli.js", "package/dist/src/cli.d.ts", "package/proto/agent/v1/agent.proto", "package/proto/aiserver/v1/aiserver.proto", "package/docs/protocol.md", "package/docs/release-gates.md", "package/docs/testing-harness.md", "package/docs/test-manifest.json", "package/docs/route-contract-manifest.json", "package/docs/release-summary.json"];
 export declare const EXCLUDED_PACKAGE_ENTRY_PREFIXES: readonly ["package/examples/"];
 export declare function runReleaseCheck(repoRoot?: string): number;
 export declare function buildReleaseCategoryStatuses(results: ReleaseGateStatusInput[], optionalSuites?: OptionalLiveSuite[]): ReleaseCategoryStatus[];

package/dist/src/tools/releaseCheck.js

@@ -10,8 +10,6 @@ export const REQUIRED_PACKAGE_ENTRIES = [
     "package/DISCLAIMER.md",
     "package/dist/src/cli.js",
     "package/dist/src/cli.d.ts",
-    "package/dist/src/ck.js",
-    "package/dist/src/ck.d.ts",
     "package/proto/agent/v1/agent.proto",
     "package/proto/aiserver/v1/aiserver.proto",
     "package/docs/protocol.md",
@@ -273,10 +271,7 @@ function runPackageSmoke(repoRoot) {
     }
     const packedPackageJsonPath = path.join(extractDir, "package", "package.json");
     const packedPackageJson = JSON.parse(fs.readFileSync(packedPackageJsonPath, "utf8"));
-    const expectedBins = new Map([
-        ["cursorkit", "./dist/src/cli.js"],
-        ["ck", "./dist/src/ck.js"],
-    ]);
+    const expectedBins = new Map([["cursorkit", "./dist/src/cli.js"]]);
     const invalidBins = Array.from(expectedBins).filter(([name, target]) => packedPackageJson.bin?.[name] !== target);
     if (invalidBins.length > 0) {
         details.error =

package/dist/src/ui/index.d.ts

@@ -0,0 +1,8 @@
+/** The cursorkit CLI's zero-dependency terminal UI layer. */
+export * from "./theme.js";
+export * from "./runtime.js";
+export { Spinner, withSpinner } from "./spinner.js";
+export { StepList } from "./steps.js";
+export type { StepInput, StepStatus } from "./steps.js";
+export { select, confirm, text, done, note } from "./prompt.js";
+export type { SelectOption } from "./prompt.js";

package/dist/src/ui/index.js

@@ -0,0 +1,6 @@
+/** The cursorkit CLI's zero-dependency terminal UI layer. */
+export * from "./theme.js";
+export * from "./runtime.js";
+export { Spinner, withSpinner } from "./spinner.js";
+export { StepList } from "./steps.js";
+export { select, confirm, text, done, note } from "./prompt.js";

package/dist/src/ui/prompt.d.ts

@@ -0,0 +1,30 @@
+export type SelectOption<T> = {
+    value: T;
+    label: string;
+    hint?: string;
+};
+/**
+ * Single-choice selection. On a raw-capable TTY this is arrow-key driven with a
+ * live highlighted cursor; otherwise it falls back to a numbered prompt read
+ * from stdin (so piped input and non-raw terminals still work). Returns the
+ * default when input is empty or unparseable.
+ */
+export declare function select<T>(input: {
+    message: string;
+    options: ReadonlyArray<SelectOption<T>>;
+    defaultIndex?: number;
+}): Promise<T>;
+/** Yes/no confirmation. Returns `defaultValue` on empty input. */
+export declare function confirm(input: {
+    message: string;
+    defaultValue?: boolean;
+}): Promise<boolean>;
+/** Free-text prompt. Returns `defaultValue` (or "") on empty input. */
+export declare function text(input: {
+    message: string;
+    defaultValue?: string;
+}): Promise<string>;
+/** A success line for the end of a wizard. */
+export declare function done(message: string): void;
+/** A neutral note line. */
+export declare function note(message: string): void;

package/dist/src/ui/prompt.js

@@ -0,0 +1,182 @@
+import { createInterface, emitKeypressEvents } from "node:readline";
+import { canPromptInteractively, uiStream } from "./runtime.js";
+import { bold, cyan, dim, glyph, gray, green } from "./theme.js";
+const out = uiStream();
+// For non-interactive input (piped/redirected/empty stdin) we read all of stdin
+// exactly once and serve answers line by line. This supports scripted input
+// (`printf "2\n3\n" | ck ...`) and falls back to "" (the prompt default) once
+// exhausted — without the fragile behavior of attaching multiple readline
+// interfaces to an already-ended stdin.
+let bufferedLines;
+let bufferedRead = false;
+async function ensureBufferedStdin() {
+    if (bufferedRead)
+        return;
+    bufferedRead = true;
+    if (process.stdin.isTTY || process.stdin.readableEnded) {
+        bufferedLines = [];
+        return;
+    }
+    const chunks = [];
+    await new Promise((resolve) => {
+        process.stdin.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+        process.stdin.once("end", () => resolve());
+        process.stdin.once("error", () => resolve());
+    });
+    bufferedLines = Buffer.concat(chunks).toString("utf8").split("\n");
+}
+/**
+ * Read a single line from stdin, prompting on stderr. On a TTY this reads live;
+ * otherwise it draws from buffered stdin and resolves to "" when there is no
+ * more input, so callers fall back to their default instead of hanging.
+ */
+async function readLine(promptText) {
+    if (!process.stdin.isTTY) {
+        out.write(promptText);
+        await ensureBufferedStdin();
+        const next = bufferedLines?.shift();
+        out.write("\n");
+        return (next ?? "").trim();
+    }
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: out });
+        let answered = false;
+        rl.question(promptText, (answer) => {
+            answered = true;
+            rl.close();
+            resolve(answer.trim());
+        });
+        rl.on("close", () => {
+            if (!answered)
+                resolve("");
+        });
+    });
+}
+/**
+ * Single-choice selection. On a raw-capable TTY this is arrow-key driven with a
+ * live highlighted cursor; otherwise it falls back to a numbered prompt read
+ * from stdin (so piped input and non-raw terminals still work). Returns the
+ * default when input is empty or unparseable.
+ */
+export async function select(input) {
+    const { options } = input;
+    if (options.length === 0)
+        throw new Error("select requires at least one option");
+    const fallbackIndex = Math.min(Math.max(input.defaultIndex ?? 0, 0), options.length - 1);
+    if (!canPromptInteractively()) {
+        return selectNumbered(input.message, options, fallbackIndex);
+    }
+    return selectInteractive(input.message, options, fallbackIndex);
+}
+function optionAt(options, index) {
+    const option = options[index];
+    if (option === undefined)
+        throw new Error(`option index out of range: ${index}`);
+    return option;
+}
+async function selectNumbered(message, options, fallbackIndex) {
+    out.write(`${bold(message)}\n`);
+    options.forEach((option, index) => {
+        const marker = index === fallbackIndex ? cyan(`${index + 1}`) : `${index + 1}`;
+        const hint = option.hint !== undefined ? dim(` — ${option.hint}`) : "";
+        out.write(`  ${marker}) ${option.label}${hint}\n`);
+    });
+    const answer = await readLine(`Choose [1-${options.length}] (${fallbackIndex + 1}): `);
+    if (answer.length === 0)
+        return optionAt(options, fallbackIndex).value;
+    const byNumber = Number.parseInt(answer, 10);
+    if (Number.isInteger(byNumber) &&
+        byNumber >= 1 &&
+        byNumber <= options.length) {
+        return optionAt(options, byNumber - 1).value;
+    }
+    const byLabel = options.findIndex((option) => option.label.toLowerCase() === answer.toLowerCase());
+    if (byLabel >= 0)
+        return optionAt(options, byLabel).value;
+    return optionAt(options, fallbackIndex).value;
+}
+function selectInteractive(message, options, fallbackIndex) {
+    return new Promise((resolve) => {
+        let cursor = fallbackIndex;
+        let rendered = 0;
+        const stdin = process.stdin;
+        emitKeypressEvents(stdin);
+        const wasRaw = stdin.isRaw === true;
+        if (stdin.setRawMode)
+            stdin.setRawMode(true);
+        stdin.resume();
+        out.write("\u001b[?25l");
+        const render = () => {
+            if (rendered > 0) {
+                out.write(`\u001b[${rendered}A`);
+                out.write("\u001b[0J");
+            }
+            const lines = [bold(message)];
+            options.forEach((option, index) => {
+                const active = index === cursor;
+                const pointer = active ? cyan(glyph.pointer()) : " ";
+                const label = active ? cyan(option.label) : option.label;
+                const hint = option.hint !== undefined ? dim(` — ${option.hint}`) : "";
+                lines.push(`${pointer} ${label}${hint}`);
+            });
+            lines.push(dim("  (arrows to move, enter to select)"));
+            out.write(lines.join("\n") + "\n");
+            rendered = lines.length;
+        };
+        const cleanup = () => {
+            stdin.removeListener("keypress", onKey);
+            if (stdin.setRawMode)
+                stdin.setRawMode(wasRaw);
+            stdin.pause();
+            out.write("\u001b[?25h");
+        };
+        const onKey = (_str, key) => {
+            if (key.sequence === "\u0003") {
+                cleanup();
+                out.write("\n");
+                process.exit(130);
+            }
+            if (key.name === "up" || key.name === "k") {
+                cursor = (cursor - 1 + options.length) % options.length;
+                render();
+            }
+            else if (key.name === "down" || key.name === "j") {
+                cursor = (cursor + 1) % options.length;
+                render();
+            }
+            else if (key.name === "return" || key.name === "enter") {
+                cleanup();
+                resolve(optionAt(options, cursor).value);
+            }
+        };
+        stdin.on("keypress", onKey);
+        render();
+    });
+}
+/** Yes/no confirmation. Returns `defaultValue` on empty input. */
+export async function confirm(input) {
+    const def = input.defaultValue ?? false;
+    const hint = def ? "[Y/n]" : "[y/N]";
+    const answer = (await readLine(`${bold(input.message)} ${dim(hint)} `)).toLowerCase();
+    if (answer.length === 0)
+        return def;
+    return answer === "y" || answer === "yes";
+}
+/** Free-text prompt. Returns `defaultValue` (or "") on empty input. */
+export async function text(input) {
+    const suffix = input.defaultValue !== undefined && input.defaultValue.length > 0
+        ? dim(` (${input.defaultValue})`)
+        : "";
+    const answer = await readLine(`${bold(input.message)}${suffix} `);
+    if (answer.length === 0)
+        return input.defaultValue ?? "";
+    return answer;
+}
+/** A success line for the end of a wizard. */
+export function done(message) {
+    out.write(`${green(glyph.tick())} ${message}\n`);
+}
+/** A neutral note line. */
+export function note(message) {
+    out.write(`${gray(glyph.arrow())} ${message}\n`);
+}

package/dist/src/ui/runtime.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Interaction-mode detection. The CLI's rich surfaces (spinners, live step
+ * lists, prompts) only render when we are attached to an interactive terminal
+ * and not running under CI; otherwise everything degrades to plain line logs so
+ * pipes, captures, and tests stay deterministic.
+ */
+/** True under a recognized CI environment. */
+export declare function isCI(): boolean;
+/** The stream all UI is written to (stderr; stdout is reserved for tool output). */
+export declare function uiStream(): NodeJS.WriteStream;
+/** True when we should render rich, animated UI to `stream`. */
+export declare function isInteractive(stream?: NodeJS.WriteStream): boolean;
+/** True when we can read interactive keypresses (raw mode) from stdin. */
+export declare function canPromptInteractively(): boolean;

package/dist/src/ui/runtime.js

@@ -0,0 +1,35 @@
+/**
+ * Interaction-mode detection. The CLI's rich surfaces (spinners, live step
+ * lists, prompts) only render when we are attached to an interactive terminal
+ * and not running under CI; otherwise everything degrades to plain line logs so
+ * pipes, captures, and tests stay deterministic.
+ */
+/** True under a recognized CI environment. */
+export function isCI() {
+    const env = process.env;
+    return Boolean(env.CI === "true" ||
+        env.CI === "1" ||
+        env.CONTINUOUS_INTEGRATION ||
+        env.GITHUB_ACTIONS ||
+        env.GITLAB_CI ||
+        env.BUILDKITE ||
+        env.CIRCLECI);
+}
+/** The stream all UI is written to (stderr; stdout is reserved for tool output). */
+export function uiStream() {
+    return process.stderr;
+}
+/** True when we should render rich, animated UI to `stream`. */
+export function isInteractive(stream = uiStream()) {
+    if (process.env.CURSORKIT_NO_TUI === "1")
+        return false;
+    if (isCI())
+        return false;
+    return Boolean(stream.isTTY);
+}
+/** True when we can read interactive keypresses (raw mode) from stdin. */
+export function canPromptInteractively() {
+    return (Boolean(process.stdin.isTTY) &&
+        !isCI() &&
+        process.env.CURSORKIT_NO_TUI !== "1");
+}

package/dist/src/ui/spinner.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A single-line spinner. On an interactive TTY it animates in place; otherwise
+ * it prints one line per state transition so logs stay readable and ordered.
+ */
+export declare class Spinner {
+    private timer;
+    private frame;
+    private text;
+    private readonly stream;
+    private readonly interactive;
+    private active;
+    constructor(text: string);
+    start(): this;
+    update(text: string): this;
+    succeed(text?: string): void;
+    fail(text?: string): void;
+    warn(text?: string): void;
+    info(text?: string): void;
+    stop(): void;
+    private settle;
+    private render;
+    private teardown;
+    private clearLine;
+    private hideCursor;
+    private showCursor;
+}
+/** Run `work` under a spinner, settling to success/failure automatically. */
+export declare function withSpinner<T>(text: string, work: () => Promise<T>, options?: {
+    success?: (value: T) => string;
+    failure?: (error: unknown) => string;
+}): Promise<T>;