@velum-labs/cursorkit 0.1.0 → 0.1.2

package/dist/src/ui/spinner.js

@@ -0,0 +1,102 @@
+import { isInteractive, uiStream } from "./runtime.js";
+import { SPINNER_FRAMES, cyan, dim, glyph, gray, green, red, yellow, } from "./theme.js";
+/**
+ * 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 class Spinner {
+    timer;
+    frame = 0;
+    text;
+    stream = uiStream();
+    interactive = isInteractive();
+    active = false;
+    constructor(text) {
+        this.text = text;
+    }
+    start() {
+        if (this.active)
+            return this;
+        this.active = true;
+        if (!this.interactive) {
+            this.stream.write(`${dim(glyph.arrow())} ${this.text}\n`);
+            return this;
+        }
+        this.hideCursor();
+        this.render();
+        this.timer = setInterval(() => {
+            this.frame = (this.frame + 1) % SPINNER_FRAMES.length;
+            this.render();
+        }, 80);
+        this.timer.unref();
+        return this;
+    }
+    update(text) {
+        this.text = text;
+        if (this.active && this.interactive)
+            this.render();
+        else if (this.active)
+            this.stream.write(`${dim(glyph.arrow())} ${this.text}\n`);
+        return this;
+    }
+    succeed(text) {
+        this.settle(green(glyph.tick()), text ?? this.text);
+    }
+    fail(text) {
+        this.settle(red(glyph.cross()), text ?? this.text);
+    }
+    warn(text) {
+        this.settle(yellow(glyph.warn()), text ?? this.text);
+    }
+    info(text) {
+        this.settle(cyan(glyph.bullet()), text ?? this.text);
+    }
+    stop() {
+        this.teardown();
+    }
+    settle(symbol, text) {
+        this.teardown();
+        this.stream.write(`${symbol} ${text}\n`);
+    }
+    render() {
+        const symbol = cyan(SPINNER_FRAMES[this.frame] ?? "-");
+        this.clearLine();
+        this.stream.write(`${symbol} ${this.text}`);
+    }
+    teardown() {
+        if (this.timer !== undefined) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        if (this.active && this.interactive) {
+            this.clearLine();
+            this.showCursor();
+        }
+        this.active = false;
+    }
+    clearLine() {
+        if (this.interactive)
+            this.stream.write("\r\u001b[2K");
+    }
+    hideCursor() {
+        if (this.interactive)
+            this.stream.write("\u001b[?25l");
+    }
+    showCursor() {
+        if (this.interactive)
+            this.stream.write("\u001b[?25h");
+    }
+}
+/** Run `work` under a spinner, settling to success/failure automatically. */
+export async function withSpinner(text, work, options = {}) {
+    const spinner = new Spinner(text).start();
+    try {
+        const value = await work();
+        spinner.succeed(options.success ? options.success(value) : text);
+        return value;
+    }
+    catch (error) {
+        spinner.fail(options.failure ? options.failure(error) : `${text} ${gray("(failed)")}`);
+        throw error;
+    }
+}

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

@@ -0,0 +1,38 @@
+export type StepStatus = "pending" | "active" | "done" | "failed" | "skipped";
+export type StepInput = {
+    id: string;
+    label: string;
+};
+/**
+ * A live checklist of stages. On a TTY it re-renders in place with per-stage
+ * spinners and elapsed time; otherwise it prints one line per state transition
+ * so non-interactive logs stay ordered and readable.
+ */
+export declare class StepList {
+    private readonly steps;
+    private readonly stream;
+    private readonly interactive;
+    private readonly title;
+    private timer;
+    private frame;
+    private renderedLines;
+    private started;
+    constructor(steps: readonly StepInput[], options?: {
+        title?: string;
+    });
+    start(): this;
+    setActive(id: string, detail?: string): void;
+    setDone(id: string, detail?: string): void;
+    setFailed(id: string, detail?: string): void;
+    setSkipped(id: string, detail?: string): void;
+    setDetail(id: string, detail: string): void;
+    /** Stop animation and leave the final frame in place. */
+    stop(): void;
+    private transition;
+    private printLine;
+    private render;
+    private clear;
+    private find;
+    private hideCursor;
+    private showCursor;
+}

package/dist/src/ui/steps.js

@@ -0,0 +1,154 @@
+import { isInteractive, uiStream } from "./runtime.js";
+import { SPINNER_FRAMES, cyan, dim, glyph, gray, green, red, yellow, } from "./theme.js";
+function elapsedLabel(step) {
+    if (step.startedAt === undefined)
+        return "";
+    const end = step.endedAt ?? Date.now();
+    const seconds = (end - step.startedAt) / 1000;
+    if (seconds < 0.05)
+        return "";
+    return gray(` ${seconds.toFixed(1)}s`);
+}
+function symbolFor(step, frame) {
+    switch (step.status) {
+        case "pending":
+            return gray(glyph.pending());
+        case "active":
+            return cyan(SPINNER_FRAMES[frame] ?? "-");
+        case "done":
+            return green(glyph.tick());
+        case "failed":
+            return red(glyph.cross());
+        case "skipped":
+            return yellow(glyph.bullet());
+        default: {
+            const exhaustive = step.status;
+            throw new Error(`unknown step status: ${String(exhaustive)}`);
+        }
+    }
+}
+/**
+ * A live checklist of stages. On a TTY it re-renders in place with per-stage
+ * spinners and elapsed time; otherwise it prints one line per state transition
+ * so non-interactive logs stay ordered and readable.
+ */
+export class StepList {
+    steps;
+    stream = uiStream();
+    interactive = isInteractive();
+    title;
+    timer;
+    frame = 0;
+    renderedLines = 0;
+    started = false;
+    constructor(steps, options = {}) {
+        this.steps = steps.map((step) => ({
+            id: step.id,
+            label: step.label,
+            status: "pending",
+        }));
+        this.title = options.title;
+    }
+    start() {
+        if (this.started)
+            return this;
+        this.started = true;
+        if (this.interactive) {
+            this.hideCursor();
+            this.render();
+            this.timer = setInterval(() => {
+                this.frame = (this.frame + 1) % SPINNER_FRAMES.length;
+                this.render();
+            }, 80);
+            this.timer.unref();
+        }
+        else if (this.title !== undefined) {
+            this.stream.write(`${this.title}\n`);
+        }
+        return this;
+    }
+    setActive(id, detail) {
+        this.transition(id, "active", detail);
+    }
+    setDone(id, detail) {
+        this.transition(id, "done", detail);
+    }
+    setFailed(id, detail) {
+        this.transition(id, "failed", detail);
+    }
+    setSkipped(id, detail) {
+        this.transition(id, "skipped", detail);
+    }
+    setDetail(id, detail) {
+        const step = this.find(id);
+        step.detail = detail;
+        if (this.interactive)
+            this.render();
+    }
+    /** Stop animation and leave the final frame in place. */
+    stop() {
+        if (this.timer !== undefined) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        if (this.interactive && this.started) {
+            this.render();
+            this.showCursor();
+        }
+        this.started = false;
+    }
+    transition(id, status, detail) {
+        const step = this.find(id);
+        if (status === "active" && step.startedAt === undefined)
+            step.startedAt = Date.now();
+        if ((status === "done" || status === "failed" || status === "skipped") &&
+            step.endedAt === undefined) {
+            step.endedAt = Date.now();
+            if (step.startedAt === undefined)
+                step.startedAt = step.endedAt;
+        }
+        step.status = status;
+        if (detail !== undefined)
+            step.detail = detail;
+        if (this.interactive)
+            this.render();
+        else
+            this.printLine(step);
+    }
+    printLine(step) {
+        const detail = step.detail !== undefined ? ` ${dim(step.detail)}` : "";
+        this.stream.write(`${symbolFor(step, 0)} ${step.label}${detail}\n`);
+    }
+    render() {
+        const lines = [];
+        if (this.title !== undefined)
+            lines.push(this.title);
+        for (const step of this.steps) {
+            const detail = step.detail !== undefined ? ` ${dim(step.detail)}` : "";
+            lines.push(`${symbolFor(step, this.frame)} ${step.label}${detail}${elapsedLabel(step)}`);
+        }
+        this.clear();
+        this.stream.write(lines.join("\n") + "\n");
+        this.renderedLines = lines.length;
+    }
+    clear() {
+        if (!this.interactive || this.renderedLines === 0)
+            return;
+        this.stream.write(`\u001b[${this.renderedLines}A`);
+        this.stream.write("\u001b[0J");
+    }
+    find(id) {
+        const step = this.steps.find((candidate) => candidate.id === id);
+        if (step === undefined)
+            throw new Error(`unknown step id: ${id}`);
+        return step;
+    }
+    hideCursor() {
+        if (this.interactive)
+            this.stream.write("\u001b[?25l");
+    }
+    showCursor() {
+        if (this.interactive)
+            this.stream.write("\u001b[?25h");
+    }
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Zero-dependency terminal theming. All color/format helpers no-op when color
+ * is not supported (not a TTY, `NO_COLOR` set, or a dumb terminal), so output
+ * stays clean when piped or captured. UI is written to stderr by convention so
+ * the bridge server's stdout (JSON logs) stays pristine.
+ */
+/** True when ANSI styling should be emitted to the given stream. */
+export declare function supportsColor(stream?: NodeJS.WriteStream): boolean;
+type Style = (text: string) => string;
+export declare const bold: Style;
+export declare const dim: Style;
+export declare const italic: Style;
+export declare const underline: Style;
+export declare const red: Style;
+export declare const green: Style;
+export declare const yellow: Style;
+export declare const blue: Style;
+export declare const magenta: Style;
+export declare const cyan: Style;
+export declare const gray: Style;
+/** Status glyphs, with ASCII fallbacks when color (≈ unicode-friendly TTY) is off. */
+export declare const glyph: {
+    tick: () => "✔" | "[ok]";
+    cross: () => "✖" | "[x]";
+    bullet: () => "•" | "*";
+    arrow: () => "›" | ">";
+    pointer: () => ">" | "❯";
+    warn: () => "⚠" | "[!]";
+    pending: () => "○" | "( )";
+};
+/** Frames for the in-place spinner (braille dots when color is on). */
+export declare const SPINNER_FRAMES: readonly string[];
+/** The product banner shown atop interactive surfaces. */
+export declare function brandHeader(subtitle?: string): string;
+export {};

package/dist/src/ui/theme.js

@@ -0,0 +1,63 @@
+/**
+ * Zero-dependency terminal theming. All color/format helpers no-op when color
+ * is not supported (not a TTY, `NO_COLOR` set, or a dumb terminal), so output
+ * stays clean when piped or captured. UI is written to stderr by convention so
+ * the bridge server's stdout (JSON logs) stays pristine.
+ */
+/** True when ANSI styling should be emitted to the given stream. */
+export function supportsColor(stream = process.stderr) {
+    if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "")
+        return false;
+    if (process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== "0")
+        return true;
+    if (process.env.TERM === "dumb")
+        return false;
+    return Boolean(stream.isTTY);
+}
+function wrap(open, close) {
+    return (text) => supportsColor() ? `\u001b[${open}m${text}\u001b[${close}m` : text;
+}
+export const bold = wrap(1, 22);
+export const dim = wrap(2, 22);
+export const italic = wrap(3, 23);
+export const underline = wrap(4, 24);
+export const red = wrap(31, 39);
+export const green = wrap(32, 39);
+export const yellow = wrap(33, 39);
+export const blue = wrap(34, 39);
+export const magenta = wrap(35, 39);
+export const cyan = wrap(36, 39);
+export const gray = wrap(90, 39);
+/** Status glyphs, with ASCII fallbacks when color (≈ unicode-friendly TTY) is off. */
+export const glyph = {
+    tick: () => (supportsColor() ? "\u2714" : "[ok]"),
+    cross: () => (supportsColor() ? "\u2716" : "[x]"),
+    bullet: () => (supportsColor() ? "\u2022" : "*"),
+    arrow: () => (supportsColor() ? "\u203a" : ">"),
+    pointer: () => (supportsColor() ? "\u276f" : ">"),
+    warn: () => (supportsColor() ? "\u26a0" : "[!]"),
+    pending: () => (supportsColor() ? "\u25cb" : "( )"),
+};
+/** Frames for the in-place spinner (braille dots when color is on). */
+export const SPINNER_FRAMES = supportsColorFrames();
+function supportsColorFrames() {
+    return [
+        "\u280b",
+        "\u2819",
+        "\u2839",
+        "\u2838",
+        "\u283c",
+        "\u2834",
+        "\u2826",
+        "\u2827",
+        "\u2807",
+        "\u280f",
+    ];
+}
+/** The product banner shown atop interactive surfaces. */
+export function brandHeader(subtitle) {
+    const title = bold(cyan("cursorkit"));
+    const tag = dim("local model bridge for Cursor");
+    const head = `${title}  ${tag}`;
+    return subtitle === undefined ? head : `${head}\n${dim(subtitle)}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velum-labs/cursorkit",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "description": "Unofficial research bridge for experimenting with Cursor's ConnectRPC protocol against a self-hosted OpenAI-compatible model.",
@@ -39,7 +39,6 @@
     }
   },
   "bin": {
-    "ck": "./dist/src/ck.js",
     "cursorkit": "./dist/src/cli.js"
   },
   "files": [
@@ -53,6 +52,7 @@
     "@bufbuild/protobuf": "^2.12.0",
     "@connectrpc/connect": "^2.1.2",
     "@connectrpc/connect-node": "^2.1.2",
+    "commander": "14.0.3",
     "protobufjs": "8.6.3",
     "selfsigned": "5.5.0",
     "undici": "8.5.0"
@@ -62,6 +62,7 @@
     "@bufbuild/protoc-gen-es": "^2.12.0",
     "@types/node": "24.10.1",
     "@velum-labs/model-fusion-protocol": "0.1.1",
+    "@vitest/coverage-v8": "4.1.8",
     "prettier": "3.8.4",
     "tsx": "4.22.4",
     "typescript": "6.0.3",
@@ -78,6 +79,7 @@
     "baseline:generate": "tsx src/tools/baselineInventory.ts",
     "baseline:check": "tsx src/tools/baselineInventory.ts --check",
     "test": "vitest run tests",
+    "test:coverage": "vitest run --coverage",
     "e2e:cursor-agent": "python3 tests/e2e/cursor-agent-smoke.py",
     "model-fusion:protocol:check": "tsx src/tools/checkModelFusionProtocol.ts",
     "release:publish:check": "tsx src/tools/checkReleasePublishConfig.ts",
@@ -87,7 +89,7 @@
     "release:check": "tsx src/tools/releaseCheck.ts",
     "serve": "node dist/src/cli.js serve",
     "dev": "tsx src/cli.ts serve",
-    "ck": "node dist/src/ck.js",
+    "ck": "node dist/src/cli.js ck",
     "test:harness": "node dist/src/testing/cli.js"
   }
 }

package/dist/src/ck.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/dist/src/ck.js

@@ -1,6 +0,0 @@
-#!/usr/bin/env node
-import { runCk } from "./ckLauncher.js";
-runCk().catch((error) => {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 1;
-});