@seleniumbox/sbox-mcp 1.0.0

package/dist/services/index.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectService = exports.diagnosticsService = exports.analyticsService = exports.uploadService = exports.sessionsPerProjectService = exports.userService = exports.deviceService = exports.browserService = exports.sessionService = exports.authService = void 0;
+const auth_adapter_1 = require("../adapters/auth.adapter");
+const session_adapter_1 = require("../adapters/session.adapter");
+const browser_adapter_1 = require("../adapters/browser.adapter");
+const device_adapter_1 = require("../adapters/device.adapter");
+const project_adapter_1 = require("../adapters/project.adapter");
+const upload_adapter_1 = require("../adapters/upload.adapter");
+const stats_adapter_1 = require("../adapters/stats.adapter");
+const diagnostics_adapter_1 = require("../adapters/diagnostics.adapter");
+const auth_service_1 = require("./auth.service");
+const session_service_1 = require("./session.service");
+const browser_service_1 = require("./browser.service");
+const device_service_1 = require("./device.service");
+const user_service_1 = require("./user.service");
+const sessions_per_project_service_1 = require("./sessions-per-project.service");
+const upload_service_1 = require("./upload.service");
+const analytics_service_1 = require("./analytics.service");
+const diagnostics_service_1 = require("./diagnostics.service");
+const project_service_1 = require("./project.service");
+exports.authService = (0, auth_service_1.createAuthService)(auth_adapter_1.authAdapter);
+exports.sessionService = (0, session_service_1.createSessionService)(session_adapter_1.sessionAdapter);
+exports.browserService = (0, browser_service_1.createBrowserService)(browser_adapter_1.browserAdapter);
+exports.deviceService = (0, device_service_1.createDeviceService)(device_adapter_1.deviceAdapter);
+exports.userService = (0, user_service_1.createUserService)(session_adapter_1.sessionAdapter);
+exports.sessionsPerProjectService = (0, sessions_per_project_service_1.createSessionsPerProjectService)(project_adapter_1.projectAdapter, session_adapter_1.sessionAdapter);
+exports.uploadService = (0, upload_service_1.createUploadService)(upload_adapter_1.uploadAdapter, project_adapter_1.projectAdapter);
+exports.analyticsService = (0, analytics_service_1.createAnalyticsService)(stats_adapter_1.statsAdapter);
+exports.diagnosticsService = (0, diagnostics_service_1.createDiagnosticsService)(diagnostics_adapter_1.diagnosticsAdapter);
+exports.projectService = (0, project_service_1.createProjectService)(project_adapter_1.projectAdapter);

package/dist/services/project.service.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Project service: list projects (all or "my projects" for the current user).
+ */
+import type { ProjectAdapter } from "../adapters/project.adapter";
+export interface ProjectDto {
+    id: number | string;
+    name: string;
+    description: string;
+    hasToken: boolean;
+    tokenPreview?: string;
+}
+export interface ProjectService {
+    listMyProjects(token: string): Promise<{
+        success: true;
+        data: ProjectDto[];
+    } | {
+        success: false;
+        status: number;
+        message: string;
+    }>;
+}
+export declare function createProjectService(adapter: ProjectAdapter): ProjectService;

package/dist/services/project.service.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Project service: list projects (all or "my projects" for the current user).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProjectService = createProjectService;
+function toProjectDto(raw) {
+    const id = raw.id ?? 0;
+    const name = raw.name ?? "";
+    const description = raw.description ?? "";
+    const tokenObj = raw.token;
+    const hasToken = Boolean(tokenObj?.token);
+    const tokenPreview = tokenObj?.token
+        ? tokenObj.token.length > 12
+            ? tokenObj.token.slice(0, 6) + "…" + tokenObj.token.slice(-6)
+            : "***"
+        : undefined;
+    return { id, name, description, hasToken, tokenPreview };
+}
+function createProjectService(adapter) {
+    return {
+        async listMyProjects(token) {
+            const res = await adapter.listMyProjects(token);
+            if (res.status !== 200) {
+                return { success: false, status: res.status, message: res.error ?? "Failed to list my projects" };
+            }
+            const data = res.projects.map(toProjectDto);
+            return { success: true, data };
+        },
+    };
+}

package/dist/services/session.service.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Session service: get session details, update status, delete session, start manual.
+ * Uses adapters and enrichment; never exposes internal IDs.
+ */
+import type { SessionAdapter } from "../adapters/session.adapter";
+import type { SessionDetailDto, SessionListResultDto, UpdateSessionStatusBodyDto, DeleteSessionResponseDto, StartManualSessionBodyDto } from "../dto/session.dto";
+export interface ListSessionsParams {
+    limit?: number;
+    offset?: number;
+    projectName?: string;
+    status?: string;
+    browser?: string;
+    build?: string;
+    sortBy?: string;
+    sortDirection?: string;
+}
+export interface SessionService {
+    getSessionDetail(ekey: string, token: string): Promise<{
+        success: true;
+        data: SessionDetailDto;
+    } | {
+        success: false;
+        status: number;
+        message: string;
+    }>;
+    listSessions(params: ListSessionsParams, token: string): Promise<{
+        success: true;
+        data: SessionListResultDto;
+    } | {
+        success: false;
+        status: number;
+        message: string;
+    }>;
+    /** Update a single session's result (passed/failed) via POST /e34/api/test-data?sessionId=&passed= */
+    updateSessionStatusBySessionId(sessionId: string, passed: boolean, token: string): Promise<{
+        success: boolean;
+        status: number;
+        message?: string;
+    }>;
+    updateSessionStatus(body: UpdateSessionStatusBodyDto, token: string): Promise<{
+        success: boolean;
+        status: number;
+        message?: string;
+    }>;
+    deleteSession(sessionId: string, token: string): Promise<{
+        success: true;
+        data: DeleteSessionResponseDto;
+    } | {
+        success: false;
+        status: number;
+        message: string;
+    }>;
+    startManualSession(body: StartManualSessionBodyDto, token: string): Promise<{
+        success: true;
+        data: SessionDetailDto;
+    } | {
+        success: false;
+        status: number;
+        message: string;
+    }>;
+}
+export declare function createSessionService(adapter: SessionAdapter): SessionService;

package/dist/services/session.service.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Session service: get session details, update status, delete session, start manual.
+ * Uses adapters and enrichment; never exposes internal IDs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSessionService = createSessionService;
+const enrichment_service_1 = require("./enrichment.service");
+function createSessionService(adapter) {
+    return {
+        async getSessionDetail(ekey, token) {
+            const res = await adapter.getByEkey(ekey, token);
+            if (res.status !== 200 || !res.data) {
+                return { success: false, status: res.status, message: res.error ?? "Session not found" };
+            }
+            const videoUrl = (0, enrichment_service_1.buildVideoUrl)(res.data.ekey ?? ekey);
+            const dto = (0, enrichment_service_1.enrichSessionDetail)(res.data, videoUrl);
+            return { success: true, data: dto };
+        },
+        async listSessions(params, token) {
+            const size = Math.min(Math.max(params.limit ?? 25, 1), 100);
+            const offset = Math.max(params.offset ?? 0, 0);
+            const res = await adapter.listPaginated({
+                projectId: params.projectName,
+                size,
+                offset,
+                status: params.status,
+                browser: params.browser,
+                build: params.build,
+                sortBy: params.sortBy ?? "arrival",
+                sortDirection: params.sortDirection ?? "desc",
+            }, token);
+            if (res.status !== 200) {
+                return { success: false, status: res.status, message: res.error ?? "List sessions failed" };
+            }
+            const content = res.content.map((raw) => {
+                const videoUrl = raw.ekey ? (0, enrichment_service_1.buildVideoUrl)(raw.ekey) : null;
+                return (0, enrichment_service_1.enrichSessionDetail)(raw, videoUrl);
+            });
+            return { success: true, data: { content, totalElements: res.totalElements } };
+        },
+        async updateSessionStatusBySessionId(sessionId, passed, token) {
+            const res = await adapter.updateSessionStatus(sessionId, passed, token);
+            if (res.status >= 200 && res.status < 300) {
+                return { success: true, status: res.status };
+            }
+            return { success: false, status: res.status, message: res.error };
+        },
+        async updateSessionStatus(body, token) {
+            const res = await adapter.updateStatusByBuild({ buildName: body.buildName, projectId: body.projectName, status: body.status }, token);
+            if (res.status >= 200 && res.status < 300) {
+                return { success: true, status: res.status };
+            }
+            return { success: false, status: res.status, message: res.error };
+        },
+        async deleteSession(sessionId, token) {
+            const res = await adapter.deleteManualSession(sessionId, token);
+            if (res.status >= 200 && res.status < 300) {
+                return { success: true, data: { success: true, message: "Session deleted" } };
+            }
+            return { success: false, status: res.status, message: res.error ?? "Delete failed" };
+        },
+        async startManualSession(body, token) {
+            const cap = {
+                "e34:projectId": body.projectName,
+                ...(body.browserName && { browserName: body.browserName }),
+                ...(body.browserVersion && { version: body.browserVersion }),
+                ...(body.url && { url: body.url }),
+            };
+            Object.keys(body).forEach((k) => {
+                if (!["projectName", "browserName", "browserVersion", "url"].includes(k))
+                    cap[k] = body[k];
+            });
+            const res = await adapter.startManualSession(cap, token);
+            if (res.status !== 200 || !res.sessionId) {
+                return { success: false, status: res.status, message: res.error ?? "Start manual session failed" };
+            }
+            const getRes = await adapter.getByEkey(res.sessionId, token);
+            const raw = getRes.data;
+            const videoUrl = (0, enrichment_service_1.buildVideoUrl)(res.sessionId);
+            const dto = raw ? (0, enrichment_service_1.enrichSessionDetail)(raw, videoUrl) : {
+                sessionId: res.sessionId,
+                projectName: body.projectName,
+                browserName: body.browserName ?? "",
+                browserVersion: body.browserVersion ?? "",
+                deviceName: "",
+                userName: "",
+                status: "running",
+                framework: "selenium",
+                startTime: new Date().toISOString(),
+                endTime: null,
+                durationMs: null,
+                videoUrl,
+                capabilities: {
+                    browser: body.browserName,
+                    version: body.browserVersion,
+                    "e34:projectId": body.projectName,
+                    ...(body.url && { url: body.url }),
+                },
+            };
+            return { success: true, data: dto };
+        },
+    };
+}

package/dist/services/sessions-per-project.service.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Sessions per project (last X days): totalSessions, passed, failed, running, avgDuration.
+ * Uses project and session adapters; aggregates in MCP (backend has no single endpoint).
+ */
+import type { ProjectAdapter } from "../adapters/project.adapter";
+import type { SessionAdapter } from "../adapters/session.adapter";
+import type { SessionsPerProjectDto } from "../dto/project-stats.dto";
+export interface SessionsPerProjectService {
+    getSessionsPerProject(token: string, days: number): Promise<{
+        success: true;
+        data: SessionsPerProjectDto[];
+    } | {
+        success: false;
+        status: number;
+        message: string;
+    }>;
+}
+export declare function createSessionsPerProjectService(projectAdapter: ProjectAdapter, sessionAdapter: SessionAdapter): SessionsPerProjectService;

package/dist/services/sessions-per-project.service.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Sessions per project (last X days): totalSessions, passed, failed, running, avgDuration.
+ * Uses project and session adapters; aggregates in MCP (backend has no single endpoint).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSessionsPerProjectService = createSessionsPerProjectService;
+const PAGE_SIZE = 500;
+function createSessionsPerProjectService(projectAdapter, sessionAdapter) {
+    return {
+        async getSessionsPerProject(token, days) {
+            const countRes = await projectAdapter.getCountPerProject(days, token);
+            if (countRes.status !== 200) {
+                return { success: false, status: countRes.status, message: countRes.error ?? "Failed to get project counts" };
+            }
+            const projects = countRes.items.map((p) => p.project).filter(Boolean);
+            const results = [];
+            const maxAgeDays = Math.max(0, days);
+            for (const projectName of projects) {
+                const listRes = await sessionAdapter.listPaginated({ projectId: projectName, size: PAGE_SIZE, offset: 0, maxAgeDays }, token);
+                if (listRes.status !== 200)
+                    continue;
+                const content = listRes.content;
+                let passed = 0;
+                let failed = 0;
+                let running = 0;
+                let totalDuration = 0;
+                let countWithDuration = 0;
+                for (const s of content) {
+                    const r = (s.result ?? "").toLowerCase();
+                    if (r === "passed")
+                        passed++;
+                    else if (r === "failed" || r === "timeout")
+                        failed++;
+                    else
+                        running++;
+                    const d = s.duration ?? s.duration;
+                    if (typeof d === "number" && d >= 0) {
+                        totalDuration += d;
+                        countWithDuration++;
+                    }
+                }
+                const totalSessions = content.length;
+                const avgDuration = countWithDuration > 0 ? Math.round(totalDuration / countWithDuration) : 0;
+                results.push({
+                    projectName,
+                    totalSessions,
+                    passed,
+                    failed,
+                    running,
+                    avgDuration,
+                });
+            }
+            return { success: true, data: results };
+        },
+    };
+}

package/dist/services/upload.service.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Upload service: upload mobile apps (APK/IPA) to SBOX. Resolves project name to id; no business logic beyond delegation.
+ */
+import type { UploadAdapter } from "../adapters/upload.adapter";
+import type { ProjectAdapter } from "../adapters/project.adapter";
+export interface UploadResultDto {
+    uploadedAppIdentifier: string;
+    projectName: string;
+}
+export interface UploadService {
+    uploadMobileApp(projectName: string, fileBuffer: Buffer, filename: string, token: string): Promise<{
+        success: true;
+        data: UploadResultDto;
+    } | {
+        success: false;
+        status: number;
+        message: string;
+    }>;
+}
+export declare function createUploadService(uploadAdapter: UploadAdapter, projectAdapter: ProjectAdapter): UploadService;

package/dist/services/upload.service.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Upload service: upload mobile apps (APK/IPA) to SBOX. Resolves project name to id; no business logic beyond delegation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUploadService = createUploadService;
+function createUploadService(uploadAdapter, projectAdapter) {
+    return {
+        async uploadMobileApp(projectName, fileBuffer, filename, token) {
+            const listRes = await projectAdapter.listProjects(token);
+            if (listRes.status !== 200) {
+                return { success: false, status: listRes.status, message: listRes.error ?? "Failed to list projects" };
+            }
+            const project = listRes.projects.find((p) => (p.name ?? "").toLowerCase() === projectName.toLowerCase());
+            if (!project || project.id == null) {
+                return { success: false, status: 404, message: `Project not found: ${projectName}` };
+            }
+            const projectId = String(project.id);
+            const res = await uploadAdapter.uploadMobileApp(projectId, fileBuffer, filename, token);
+            if (res.status !== 200 || !res.uploadedAppIdentifier) {
+                return { success: false, status: res.status, message: res.error ?? "Upload failed" };
+            }
+            return {
+                success: true,
+                data: { uploadedAppIdentifier: res.uploadedAppIdentifier, projectName: project.name ?? projectName },
+            };
+        },
+    };
+}

package/dist/services/user.service.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Active users (top N) with session counts and project names.
+ * Uses user adapter and session list; returns business-friendly DTOs.
+ */
+import type { SessionAdapter } from "../adapters/session.adapter";
+import type { ActiveUserDto } from "../dto/user.dto";
+export interface UserService {
+    getActiveUsersTopN(token: string, limit: number): Promise<{
+        success: true;
+        data: ActiveUserDto[];
+    } | {
+        success: false;
+        status: number;
+        message: string;
+    }>;
+}
+export declare function createUserService(sessionAdapter: SessionAdapter): UserService;

package/dist/services/user.service.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Active users (top N) with session counts and project names.
+ * Uses user adapter and session list; returns business-friendly DTOs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUserService = createUserService;
+function createUserService(sessionAdapter) {
+    return {
+        async getActiveUsersTopN(token, limit) {
+            const sessionsRes = await sessionAdapter.listPaginated({ size: 500, offset: 0, sortBy: "arrival", sortDirection: "desc" }, token);
+            if (sessionsRes.status !== 200) {
+                return { success: false, status: sessionsRes.status, message: sessionsRes.error ?? "Failed to list sessions" };
+            }
+            const byUser = new Map();
+            for (const s of sessionsRes.content) {
+                const uid = (s.extras ?? {})["e34:userId"];
+                const project = (s.extras ?? {})["e34:projectId"];
+                const userKey = uid ?? "unknown";
+                if (!byUser.has(userKey))
+                    byUser.set(userKey, { count: 0, projects: new Set() });
+                const entry = byUser.get(userKey);
+                entry.count += 1;
+                if (project)
+                    entry.projects.add(project);
+            }
+            const sorted = [...byUser.entries()]
+                .sort((a, b) => b[1].count - a[1].count)
+                .slice(0, limit);
+            const dtos = sorted.map(([userName, { count, projects }]) => ({
+                userName,
+                email: null,
+                activeSessionCount: count,
+                projectNames: [...projects],
+            }));
+            return { success: true, data: dtos };
+        },
+    };
+}

package/dist/token-cache.d.ts

@@ -0,0 +1,13 @@
+/**
+ * In-memory and file-backed cache for the SBOX session token. Set on successful sbox_open_login,
+ * used by other tools when token is not passed. Cleared on 401/invalid token.
+ * File persistence ensures the token survives MCP process restarts (e.g. new process per IDE prompt).
+ * lastPollId is set when we return device-flow (browser didn't open) so sbox_complete_login can use it.
+ */
+export declare function getCachedToken(): string | null;
+export declare function setCachedToken(token: string): void;
+export declare function clearCachedToken(): void;
+export declare function setLastPollId(pollId: string): void;
+export declare function getLastPollId(): string | null;
+/** Resolve token: prefer provided token, else cached. Returns null if neither. */
+export declare function resolveToken(provided: string | undefined | null): string | null;

package/dist/token-cache.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * In-memory and file-backed cache for the SBOX session token. Set on successful sbox_open_login,
+ * used by other tools when token is not passed. Cleared on 401/invalid token.
+ * File persistence ensures the token survives MCP process restarts (e.g. new process per IDE prompt).
+ * lastPollId is set when we return device-flow (browser didn't open) so sbox_complete_login can use it.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCachedToken = getCachedToken;
+exports.setCachedToken = setCachedToken;
+exports.clearCachedToken = clearCachedToken;
+exports.setLastPollId = setLastPollId;
+exports.getLastPollId = getLastPollId;
+exports.resolveToken = resolveToken;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+let cachedToken = null;
+let lastPollId = null;
+let memoryLoadedFromFile = false;
+function getTokenFilePath() {
+    if (process.env.SBOX_MCP_TOKEN_FILE)
+        return process.env.SBOX_MCP_TOKEN_FILE;
+    const dir = path_1.default.join(os_1.default.homedir(), ".sbox-mcp");
+    return path_1.default.join(dir, "token");
+}
+function loadTokenFromFile() {
+    if (memoryLoadedFromFile)
+        return;
+    memoryLoadedFromFile = true;
+    try {
+        const filePath = getTokenFilePath();
+        if (fs_1.default.existsSync(filePath)) {
+            const raw = fs_1.default.readFileSync(filePath, "utf-8").trim();
+            if (raw)
+                cachedToken = raw;
+        }
+    }
+    catch {
+        // ignore read errors (e.g. no file, permissions)
+    }
+}
+function saveTokenToFile(token) {
+    try {
+        const filePath = getTokenFilePath();
+        if (token) {
+            const dir = path_1.default.dirname(filePath);
+            if (!fs_1.default.existsSync(dir))
+                fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+            fs_1.default.writeFileSync(filePath, token, { mode: 0o600, encoding: "utf-8" });
+        }
+        else if (fs_1.default.existsSync(filePath)) {
+            fs_1.default.unlinkSync(filePath);
+        }
+    }
+    catch {
+        // ignore write errors
+    }
+}
+function getCachedToken() {
+    loadTokenFromFile();
+    return cachedToken;
+}
+function setCachedToken(token) {
+    cachedToken = token;
+    saveTokenToFile(token);
+}
+function clearCachedToken() {
+    cachedToken = null;
+    saveTokenToFile(null);
+}
+const LAST_POLL_ID_FILE = "last_poll_id";
+function getCacheDir() {
+    if (process.env.SBOX_MCP_TOKEN_FILE)
+        return path_1.default.dirname(process.env.SBOX_MCP_TOKEN_FILE);
+    return path_1.default.join(os_1.default.homedir(), ".sbox-mcp");
+}
+function setLastPollId(pollId) {
+    lastPollId = pollId;
+    try {
+        const dir = getCacheDir();
+        if (!fs_1.default.existsSync(dir))
+            fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        fs_1.default.writeFileSync(path_1.default.join(dir, LAST_POLL_ID_FILE), pollId, { mode: 0o600, encoding: "utf-8" });
+    }
+    catch {
+        // ignore
+    }
+}
+function getLastPollId() {
+    if (lastPollId)
+        return lastPollId;
+    try {
+        const filePath = path_1.default.join(getCacheDir(), LAST_POLL_ID_FILE);
+        if (fs_1.default.existsSync(filePath)) {
+            lastPollId = fs_1.default.readFileSync(filePath, "utf-8").trim() || null;
+            return lastPollId;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return null;
+}
+/** Resolve token: prefer provided token, else cached. Returns null if neither. */
+function resolveToken(provided) {
+    const t = (provided ?? "").trim();
+    if (t)
+        return t;
+    return getCachedToken();
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Simple logger for MCP module. All output goes to stderr so that when running over
+ * stdio (MCP transport), stdout is reserved for JSON-RPC and is not corrupted by logs.
+ */
+export interface Logger {
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+    debug(msg: string, meta?: Record<string, unknown>): void;
+}
+export declare const logger: Logger;

package/dist/utils/logger.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Simple logger for MCP module. All output goes to stderr so that when running over
+ * stdio (MCP transport), stdout is reserved for JSON-RPC and is not corrupted by logs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+const isProd = process.env.NODE_ENV === "production";
+function format(level, msg, meta) {
+    const ts = new Date().toISOString();
+    const m = meta && Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : "";
+    return `${ts} [${level}] ${msg}${m}\n`;
+}
+function writeStderr(line) {
+    process.stderr.write(line);
+}
+exports.logger = {
+    info(msg, meta) {
+        writeStderr(format("INFO", msg, meta));
+    },
+    warn(msg, meta) {
+        writeStderr(format("WARN", msg, meta));
+    },
+    error(msg, meta) {
+        writeStderr(format("ERROR", msg, meta));
+    },
+    debug(msg, meta) {
+        if (!isProd)
+            writeStderr(format("DEBUG", msg, meta));
+    },
+};

package/dist/utils/open-browser.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Open a URL in the system default browser. Cross-platform via spawn (no shell).
+ * Returns true if open succeeded, false otherwise (e.g. headless environment).
+ * Never throws; callers can continue (e.g. return auth_url for IDE to open).
+ */
+export declare function openUrlInBrowser(url: string): Promise<boolean>;

package/dist/utils/open-browser.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Open a URL in the system default browser. Cross-platform via spawn (no shell).
+ * Returns true if open succeeded, false otherwise (e.g. headless environment).
+ * Never throws; callers can continue (e.g. return auth_url for IDE to open).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openUrlInBrowser = openUrlInBrowser;
+const child_process_1 = require("child_process");
+const os_1 = require("os");
+function openUrlInBrowser(url) {
+    return new Promise((resolve) => {
+        const plat = (0, os_1.platform)();
+        const [cmd, args] = plat === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : plat === "darwin"
+                ? ["open", [url]]
+                : ["xdg-open", [url]];
+        const child = (0, child_process_1.spawn)(cmd, args, { stdio: "ignore" });
+        child.on("error", () => resolve(false));
+        child.on("close", (code) => resolve(code === 0));
+    });
+}

package/dist/utils/time-range.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Builds query string for SBOX time-range params. Backend accepts either days or unit+value.
+ */
+export type TimeRange = {
+    days: number;
+} | {
+    unit: "hour" | "minute" | "day";
+    value: number;
+};
+export declare function buildTimeQuery(timeRange: TimeRange): string;
+export declare function parseTimeToRange(value: number, unit: "hour" | "minute" | "day"): TimeRange;