@qodalis/cli-server-node 1.0.0-beta.1 → 1.0.0-beta.10

package/dist/src/services/cli-event-socket-manager.js

@@ -0,0 +1,246 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliEventSocketManager = void 0;
+const ws_1 = require("ws");
+const url_1 = require("url");
+const cli_shell_session_manager_1 = require("./cli-shell-session-manager");
+const logger_1 = require("../utils/logger");
+const cli_server_auth_1 = require("../auth/cli-server-auth");
+const ws_upgrade_auth_1 = require("../auth/ws-upgrade-auth");
+const session_bound_sockets_1 = require("./session-bound-sockets");
+const logger = (0, logger_1.createLogger)('EventSocket');
+/** Events delivered only to sockets authenticated as the event's user. */
+const USER_SCOPED_EVENTS = new Set(['session-kicked']);
+/**
+ * Manages WebSocket connections for server-push events and interactive shell sessions.
+ * Handles upgrades on `/ws/v1/qcli/events` and (when `enableShell` is set)
+ * `/ws/v1/qcli/shell`. With an auth provider that protects the server, event
+ * upgrades need a single-use `?ticket=`; `session-kicked` is delivered only to
+ * the affected user. Sockets authenticated with a stored session are bound to
+ * it: once it ends they are closed with 4401 `session ended` (after
+ * `session-kicked` for revocations; see {@link SessionBoundSockets}). Shell
+ * access (modes, limits, session binding) is decided by {@link CliShellSessionManager}.
+ */
+class CliEventSocketManager {
+    _wss = null;
+    _clients = new Set();
+    _clientMeta = new Map();
+    _shellManager;
+    _nextClientId = 1;
+    _auth;
+    _allowedOrigins;
+    _trustProxy;
+    _sessionBound = new session_bound_sockets_1.SessionBoundSockets({ awaitKick: true });
+    constructor(options = {}) {
+        this._shellManager = new cli_shell_session_manager_1.CliShellSessionManager({
+            enabled: options.enableShell ?? false,
+            shell: options.shell,
+            trustProxy: options.trustProxy,
+        });
+        this._allowedOrigins = options.allowedOrigins;
+        this._trustProxy = options.trustProxy ?? false;
+    }
+    /** Installs the auth provider (users plugin) used to authenticate upgrades with tickets. */
+    setAuth(auth) {
+        this._auth = auth;
+        this._shellManager.setAuth(auth);
+        this._sessionBound.setAuth(auth);
+    }
+    setAllowedOrigins(origins) {
+        this._allowedOrigins = origins;
+    }
+    setShellEnabled(enabled) {
+        this._shellManager.setEnabled(enabled);
+    }
+    get shellEnabled() {
+        return this._shellManager.enabled;
+    }
+    /** Shell access mode (`undefined` while the shell is disabled). */
+    get shellAuthMode() {
+        return this._shellManager.authMode;
+    }
+    /** The shell session manager (open sessions, limits, binding). */
+    get shellManager() {
+        return this._shellManager;
+    }
+    static EVENT_PATHS = new Set([
+        '/ws/v1/qcli/events',
+        '/ws/qcli/events',
+    ]);
+    static SHELL_PATHS = new Set([
+        '/ws/v1/qcli/shell',
+        '/ws/qcli/shell',
+    ]);
+    /**
+     * Attach to an HTTP server and listen for WebSocket upgrades on
+     * event and shell paths.
+     */
+    attach(server) {
+        this._wss = new ws_1.WebSocketServer({ noServer: true });
+        this._shellManager.logStartupState();
+        server.on('upgrade', (request, socket, head) => {
+            let parsed;
+            try {
+                parsed = new url_1.URL(request.url ?? '', 'http://localhost');
+            }
+            catch {
+                return; // malformed request target: not one of our paths
+            }
+            const pathname = parsed.pathname;
+            if (CliEventSocketManager.EVENT_PATHS.has(pathname)) {
+                (0, ws_upgrade_auth_1.authorizeWsUpgrade)(request, parsed, { auth: this._auth, allowedOrigins: this._allowedOrigins, trustProxy: this._trustProxy }).then((result) => {
+                    if (!result.ok) {
+                        (0, ws_upgrade_auth_1.rejectUpgrade)(socket, result.status);
+                        return;
+                    }
+                    this._wss.handleUpgrade(request, socket, head, (ws) => {
+                        this._wss.emit('connection', ws, request, result.ctx);
+                    });
+                }, () => (0, ws_upgrade_auth_1.rejectUpgrade)(socket, 401));
+                return;
+            }
+            if (CliEventSocketManager.SHELL_PATHS.has(pathname)) {
+                // Origin rejection stays an HTTP 403; every other refusal is
+                // "accept, then close" with a code the browser can read (C5).
+                (0, ws_upgrade_auth_1.authorizeWsUpgrade)(request, parsed, { allowedOrigins: this._allowedOrigins, trustProxy: this._trustProxy }).then((result) => {
+                    if (!result.ok) {
+                        (0, ws_upgrade_auth_1.rejectUpgrade)(socket, result.status);
+                        return;
+                    }
+                    this._wss.handleUpgrade(request, socket, head, (ws) => {
+                        this._shellManager.accept(ws, request, parsed).catch((err) => {
+                            logger.error('Shell session error: %s', err?.message ?? err);
+                            try {
+                                ws.close(1011, 'shell error');
+                            }
+                            catch {
+                                // ignore
+                            }
+                        });
+                    });
+                });
+                return;
+            }
+            // Unrecognized path; leave for other upgrade handlers
+        });
+        this._wss.on('connection', (ws, request, auth) => {
+            this._clients.add(ws);
+            const id = `evt-${this._nextClientId++}`;
+            this._clientMeta.set(ws, {
+                id,
+                connectedAt: new Date(),
+                remoteAddress: request.socket.remoteAddress ?? 'unknown',
+                auth,
+            });
+            this._sessionBound.bind(ws, auth);
+            logger.info('Client connected (id=%s)', id);
+            ws.send(JSON.stringify({ type: 'connected' }));
+            const disconnected = () => {
+                const meta = this._clientMeta.get(ws);
+                logger.info('Client disconnected (id=%s)', meta?.id ?? 'unknown');
+                this._sessionBound.unbind(ws);
+                this._clients.delete(ws);
+                this._clientMeta.delete(ws);
+            };
+            ws.on('close', disconnected);
+            ws.on('error', disconnected);
+        });
+    }
+    /**
+     * Broadcast an arbitrary message to all connected event clients.
+     */
+    broadcastMessage(message) {
+        const data = JSON.stringify(message);
+        const type = typeof message.type === 'string' ? message.type : '';
+        const payload = (message.data ?? {});
+        const toClose = [];
+        for (const ws of this._clients) {
+            if (ws.readyState !== ws_1.WebSocket.OPEN)
+                continue;
+            const auth = this._clientMeta.get(ws)?.auth;
+            if (USER_SCOPED_EVENTS.has(type)) {
+                // Only the affected user's sockets learn about it
+                if (!auth || auth.userId !== payload.userId)
+                    continue;
+                ws.send(data);
+                if (type === 'session-kicked' && auth.sessionId && auth.sessionId === payload.sessionId) {
+                    toClose.push(ws);
+                }
+                continue;
+            }
+            // A socket whose session ended only waits for its session-kicked
+            if (this._sessionBound.isEnding(ws))
+                continue;
+            if (this._auth?.protectServer) {
+                // Server-wide events need the matching read permission
+                const needed = type === 'log' || type.startsWith('log:')
+                    ? cli_server_auth_1.CliServerPermissions.LogsRead
+                    : type.startsWith('job:')
+                        ? cli_server_auth_1.CliServerPermissions.JobsRead
+                        : undefined;
+                if (needed && (!auth || !this._auth.hasPermission(auth, needed)))
+                    continue;
+            }
+            ws.send(data);
+        }
+        for (const ws of toClose) {
+            this._sessionBound.kicked(ws);
+        }
+    }
+    /**
+     * Broadcast a disconnect event to all connected clients and close sockets.
+     */
+    async broadcastDisconnect() {
+        logger.info('Broadcasting disconnect to %d clients', this._clients.size);
+        const message = JSON.stringify({ type: 'disconnect' });
+        const promises = [];
+        for (const ws of this._clients) {
+            if (ws.readyState === ws_1.WebSocket.OPEN) {
+                promises.push(new Promise((resolve) => {
+                    ws.send(message, () => {
+                        ws.close(1000, 'Server shutting down');
+                        resolve();
+                    });
+                }));
+            }
+        }
+        await Promise.all(promises);
+        this._shellManager.dispose();
+        this._sessionBound.dispose();
+        this._clients.clear();
+        this._clientMeta.clear();
+    }
+    /**
+     * Return information about all currently connected event clients.
+     */
+    getClients() {
+        const result = [];
+        for (const ws of this._clients) {
+            if (ws.readyState === ws_1.WebSocket.OPEN) {
+                const meta = this._clientMeta.get(ws);
+                if (meta) {
+                    result.push({
+                        id: meta.id,
+                        connectedAt: meta.connectedAt.toISOString(),
+                        remoteAddress: meta.remoteAddress,
+                        type: 'events',
+                    });
+                }
+            }
+        }
+        return result;
+    }
+    /** Terminates all connections and closes the WebSocket server. */
+    dispose() {
+        this._shellManager.dispose();
+        this._sessionBound.dispose();
+        for (const ws of this._clients) {
+            ws.terminate();
+        }
+        this._clients.clear();
+        this._clientMeta.clear();
+        this._wss?.close();
+    }
+}
+exports.CliEventSocketManager = CliEventSocketManager;
+//# sourceMappingURL=cli-event-socket-manager.js.map

package/dist/src/services/cli-event-socket-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-event-socket-manager.js","sourceRoot":"","sources":["../../../src/services/cli-event-socket-manager.ts"],"names":[],"mappings":"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"}

package/dist/src/services/cli-log-socket-manager.d.ts

@@ -0,0 +1,67 @@
+import type { Server } from 'http';
+import { ICliServerAuth } from '../auth/cli-server-auth';
+/** Information about a connected WebSocket log-streaming client. */
+export interface CliLogWebSocketClientInfo {
+    id: string;
+    connectedAt: string;
+    remoteAddress: string;
+    levelFilter: string | null;
+    type: 'logs';
+}
+/**
+ * Manages WebSocket connections for streaming log messages to clients.
+ *
+ * Parity with CliLogSocketManager in the .NET and Python servers.
+ * Handles `/ws/v1/qcli/logs` and `/ws/qcli/logs` upgrade paths. Sockets
+ * authenticated with a stored session are bound to it: once it ends they are
+ * closed with 4401 `session ended` (see {@link SessionBoundSockets}).
+ */
+export declare class CliLogSocketManager {
+    private _wss;
+    private readonly _clients;
+    private _nextClientId;
+    private _auth?;
+    private _allowedOrigins?;
+    private readonly _trustProxy;
+    private readonly _sessionBound;
+    constructor(options?: {
+        allowedOrigins?: string[];
+        trustProxy?: boolean | number;
+    });
+    /** Installs the auth provider; when it protects the server, upgrades need a ticket and `logs:read`. */
+    setAuth(auth: ICliServerAuth | undefined): void;
+    setAllowedOrigins(origins: string[] | undefined): void;
+    private static readonly LOG_PATHS;
+    /**
+     * Check whether a log at `logLevel` passes the `filterLevel` gate.
+     */
+    static shouldSendLog(filterLevel: string | null, logLevel: string): boolean;
+    /**
+     * Format a log message as a JSON string matching the cross-server schema.
+     */
+    static formatLogMessage(level: string, message: string, category?: string | null): string;
+    /**
+     * Attach to an HTTP server and handle WebSocket upgrades on log paths.
+     *
+     * If you already have a `CliEventSocketManager` attached, call this
+     * method on the same `server` — Node's `upgrade` event supports
+     * multiple listeners, and each manager only handles its own paths.
+     */
+    attach(server: Server): void;
+    /**
+     * Broadcast a log message to all connected clients whose filter allows it.
+     */
+    broadcastLog(level: string, message: string, category?: string | null): void;
+    /**
+     * Send a disconnect message to all clients and close connections.
+     */
+    broadcastDisconnect(): Promise<void>;
+    /**
+     * Return information about all currently connected log clients.
+     */
+    getClients(): CliLogWebSocketClientInfo[];
+    /** Terminates all connections and closes the WebSocket server. */
+    dispose(): void;
+    private _handleConnection;
+}
+//# sourceMappingURL=cli-log-socket-manager.d.ts.map

package/dist/src/services/cli-log-socket-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-log-socket-manager.d.ts","sourceRoot":"","sources":["../../../src/services/cli-log-socket-manager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAmB,MAAM,MAAM,CAAC;AAGpD,OAAO,EAA8C,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAMrG,oEAAoE;AACpE,MAAM,WAAW,yBAAyB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;CAChB;AAsCD;;;;;;;GAOG;AACH,qBAAa,mBAAmB;IAC5B,OAAO,CAAC,IAAI,CAAgC;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,KAAK,CAAC,CAAiB;IAC/B,OAAO,CAAC,eAAe,CAAC,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;IAC/C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;gBAE/C,OAAO,GAAE;QAAE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;KAAO;IAKtF,uGAAuG;IACvG,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI;IAK/C,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI;IAItD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAG9B;IAEH;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAY3E;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM;IAUzF;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAmC5B;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAsB5E;;OAEG;IACG,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB1C;;OAEG;IACH,UAAU,IAAI,yBAAyB,EAAE;IAgBzC,kEAAkE;IAClE,OAAO,IAAI,IAAI;IASf,OAAO,CAAC,iBAAiB;CAwB5B"}

package/dist/src/services/cli-log-socket-manager.js

@@ -0,0 +1,225 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliLogSocketManager = void 0;
+const ws_1 = require("ws");
+const url_1 = require("url");
+const logger_1 = require("../utils/logger");
+const cli_server_auth_1 = require("../auth/cli-server-auth");
+const ws_upgrade_auth_1 = require("../auth/ws-upgrade-auth");
+const session_bound_sockets_1 = require("./session-bound-sockets");
+const logger = (0, logger_1.createLogger)('LogSocket');
+/**
+ * Level ordering from lowest to highest severity.
+ * Matches the Python/C# implementations.
+ */
+const LEVEL_ORDER = {
+    verbose: 0,
+    debug: 1,
+    information: 2,
+    warning: 3,
+    error: 4,
+    fatal: 5,
+};
+/**
+ * Maps short/uppercase log levels (used by LogRingBuffer) to the
+ * standard level names used across all three servers.
+ */
+const LEVEL_ALIASES = {
+    info: 'information',
+    warn: 'warning',
+    err: 'error',
+};
+function normalizeLevel(level) {
+    const lower = level.toLowerCase();
+    return LEVEL_ALIASES[lower] ?? lower;
+}
+/**
+ * Manages WebSocket connections for streaming log messages to clients.
+ *
+ * Parity with CliLogSocketManager in the .NET and Python servers.
+ * Handles `/ws/v1/qcli/logs` and `/ws/qcli/logs` upgrade paths. Sockets
+ * authenticated with a stored session are bound to it: once it ends they are
+ * closed with 4401 `session ended` (see {@link SessionBoundSockets}).
+ */
+class CliLogSocketManager {
+    _wss = null;
+    _clients = new Map();
+    _nextClientId = 1;
+    _auth;
+    _allowedOrigins;
+    _trustProxy;
+    _sessionBound = new session_bound_sockets_1.SessionBoundSockets();
+    constructor(options = {}) {
+        this._allowedOrigins = options.allowedOrigins;
+        this._trustProxy = options.trustProxy ?? false;
+    }
+    /** Installs the auth provider; when it protects the server, upgrades need a ticket and `logs:read`. */
+    setAuth(auth) {
+        this._auth = auth;
+        this._sessionBound.setAuth(auth);
+    }
+    setAllowedOrigins(origins) {
+        this._allowedOrigins = origins;
+    }
+    static LOG_PATHS = new Set([
+        '/ws/v1/qcli/logs',
+        '/ws/qcli/logs',
+    ]);
+    /**
+     * Check whether a log at `logLevel` passes the `filterLevel` gate.
+     */
+    static shouldSendLog(filterLevel, logLevel) {
+        if (!filterLevel)
+            return true;
+        const filterOrd = LEVEL_ORDER[normalizeLevel(filterLevel)];
+        const logOrd = LEVEL_ORDER[normalizeLevel(logLevel)];
+        // Unknown levels always pass
+        if (filterOrd === undefined || logOrd === undefined)
+            return true;
+        return logOrd >= filterOrd;
+    }
+    /**
+     * Format a log message as a JSON string matching the cross-server schema.
+     */
+    static formatLogMessage(level, message, category) {
+        return JSON.stringify({
+            type: 'log',
+            timestamp: new Date().toISOString(),
+            level: normalizeLevel(level),
+            message,
+            category: category ?? null,
+        });
+    }
+    /**
+     * Attach to an HTTP server and handle WebSocket upgrades on log paths.
+     *
+     * If you already have a `CliEventSocketManager` attached, call this
+     * method on the same `server` — Node's `upgrade` event supports
+     * multiple listeners, and each manager only handles its own paths.
+     */
+    attach(server) {
+        this._wss = new ws_1.WebSocketServer({ noServer: true });
+        server.on('upgrade', (request, socket, head) => {
+            let parsed;
+            try {
+                parsed = new url_1.URL(request.url ?? '', 'http://localhost');
+            }
+            catch {
+                return; // malformed request target: not one of our paths
+            }
+            const pathname = parsed.pathname;
+            if (!CliLogSocketManager.LOG_PATHS.has(pathname))
+                return;
+            (0, ws_upgrade_auth_1.authorizeWsUpgrade)(request, parsed, {
+                auth: this._auth,
+                allowedOrigins: this._allowedOrigins,
+                trustProxy: this._trustProxy,
+                permission: cli_server_auth_1.CliServerPermissions.LogsRead,
+            }).then((result) => {
+                if (!result.ok) {
+                    (0, ws_upgrade_auth_1.rejectUpgrade)(socket, result.status);
+                    return;
+                }
+                this._wss.handleUpgrade(request, socket, head, (ws) => {
+                    const levelFilter = parsed.searchParams.get('level') || null;
+                    this._handleConnection(ws, request, levelFilter, result.ctx);
+                });
+            }, () => (0, ws_upgrade_auth_1.rejectUpgrade)(socket, 401));
+        });
+    }
+    /**
+     * Broadcast a log message to all connected clients whose filter allows it.
+     */
+    broadcastLog(level, message, category) {
+        if (this._clients.size === 0)
+            return;
+        let formatted = null;
+        for (const entry of this._clients.values()) {
+            if (entry.ws.readyState !== ws_1.WebSocket.OPEN)
+                continue;
+            if (!CliLogSocketManager.shouldSendLog(entry.levelFilter, level))
+                continue;
+            // Lazy-format only when there's at least one recipient
+            if (!formatted) {
+                formatted = CliLogSocketManager.formatLogMessage(level, message, category);
+            }
+            try {
+                entry.ws.send(formatted);
+            }
+            catch {
+                // ignore send errors; cleanup happens on close/error events
+            }
+        }
+    }
+    /**
+     * Send a disconnect message to all clients and close connections.
+     */
+    async broadcastDisconnect() {
+        logger.info('Broadcasting disconnect to %d log clients', this._clients.size);
+        const disconnectMsg = JSON.stringify({ type: 'disconnect' });
+        const promises = [];
+        for (const entry of this._clients.values()) {
+            if (entry.ws.readyState === ws_1.WebSocket.OPEN) {
+                promises.push(new Promise((resolve) => {
+                    entry.ws.send(disconnectMsg, () => {
+                        entry.ws.close(1000, 'Server shutting down');
+                        resolve();
+                    });
+                }));
+            }
+        }
+        await Promise.all(promises);
+        this._sessionBound.dispose();
+        this._clients.clear();
+    }
+    /**
+     * Return information about all currently connected log clients.
+     */
+    getClients() {
+        const result = [];
+        for (const entry of this._clients.values()) {
+            if (entry.ws.readyState === ws_1.WebSocket.OPEN) {
+                result.push({
+                    id: entry.id,
+                    connectedAt: entry.connectedAt.toISOString(),
+                    remoteAddress: entry.remoteAddress,
+                    levelFilter: entry.levelFilter,
+                    type: 'logs',
+                });
+            }
+        }
+        return result;
+    }
+    /** Terminates all connections and closes the WebSocket server. */
+    dispose() {
+        this._sessionBound.dispose();
+        for (const entry of this._clients.values()) {
+            entry.ws.terminate();
+        }
+        this._clients.clear();
+        this._wss?.close();
+    }
+    _handleConnection(ws, request, levelFilter, auth) {
+        const id = `log-${this._nextClientId++}`;
+        const entry = {
+            id,
+            ws,
+            connectedAt: new Date(),
+            remoteAddress: request.socket.remoteAddress ?? 'unknown',
+            levelFilter,
+        };
+        this._clients.set(id, entry);
+        this._sessionBound.bind(ws, auth);
+        ws.send(JSON.stringify({ type: 'connected' }));
+        logger.info('Log client connected (id=%s, level=%s)', id, levelFilter ?? 'all');
+        const disconnected = () => {
+            logger.info('Log client disconnected (id=%s)', id);
+            this._sessionBound.unbind(ws);
+            this._clients.delete(id);
+        };
+        ws.on('close', disconnected);
+        ws.on('error', disconnected);
+    }
+}
+exports.CliLogSocketManager = CliLogSocketManager;
+//# sourceMappingURL=cli-log-socket-manager.js.map

package/dist/src/services/cli-log-socket-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-log-socket-manager.js","sourceRoot":"","sources":["../../../src/services/cli-log-socket-manager.ts"],"names":[],"mappings":"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"}

package/dist/{services → src/services}/cli-response-builder.d.ts

@@ -1,13 +1,22 @@
 import { CliServerResponse } from '../models';
+/** Fluent interface for building a structured CLI server response with typed output blocks. */
 export interface ICliResponseBuilder {
+    /** Appends a text output block with an optional style. */
     writeText(text: string, style?: 'success' | 'error' | 'info' | 'warning'): void;
+    /** Appends a table output block. */
     writeTable(headers: string[], rows: string[][]): void;
+    /** Appends a list output block. */
     writeList(items: string[], ordered?: boolean): void;
+    /** Appends a JSON output block. */
     writeJson(value: any): void;
+    /** Appends a key-value pairs output block. */
     writeKeyValue(entries: Record<string, string>): void;
+    /** Sets the exit code for the response. */
     setExitCode(code: number): void;
+    /** Builds and returns the final structured response. */
     build(): CliServerResponse;
 }
+/** Default implementation of {@link ICliResponseBuilder} that accumulates output blocks. */
 export declare class CliResponseBuilder implements ICliResponseBuilder {
     private _exitCode;
     private _outputs;

package/dist/src/services/cli-response-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-response-builder.d.ts","sourceRoot":"","sources":["../../../src/services/cli-response-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,+FAA+F;AAC/F,MAAM,WAAW,mBAAmB;IAChC,0DAA0D;IAC1D,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IAChF,oCAAoC;IACpC,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC;IACtD,mCAAmC;IACnC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACpD,mCAAmC;IACnC,SAAS,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,CAAC;IAC5B,8CAA8C;IAC9C,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACrD,2CAA2C;IAC3C,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,wDAAwD;IACxD,KAAK,IAAI,iBAAiB,CAAC;CAC9B;AAED,4FAA4F;AAC5F,qBAAa,kBAAmB,YAAW,mBAAmB;IAC1D,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,QAAQ,CAAyB;IAEzC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI;IAI/E,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI;IAIrD,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,UAAQ,GAAG,IAAI;IAIjD,SAAS,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI;IAI3B,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAOpD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI/B,KAAK,IAAI,iBAAiB;CAM7B"}

package/dist/{services → src/services}/cli-response-builder.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CliResponseBuilder = void 0;
+/** Default implementation of {@link ICliResponseBuilder} that accumulates output blocks. */
 class CliResponseBuilder {
     _exitCode = 0;
     _outputs = [];

package/dist/src/services/cli-response-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-response-builder.js","sourceRoot":"","sources":["../../../src/services/cli-response-builder.ts"],"names":[],"mappings":";;;AAqBA,4FAA4F;AAC5F,MAAa,kBAAkB;IACnB,SAAS,GAAG,CAAC,CAAC;IACd,QAAQ,GAAsB,EAAE,CAAC;IAEzC,SAAS,CAAC,IAAY,EAAE,KAAgD;QACpE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACnF,CAAC;IAED,UAAU,CAAC,OAAiB,EAAE,IAAgB;QAC1C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,SAAS,CAAC,KAAe,EAAE,OAAO,GAAG,KAAK;QACtC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,SAAS,CAAC,KAAU;QAChB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,aAAa,CAAC,OAA+B;QACzC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;SAC3E,CAAC,CAAC;IACP,CAAC;IAED,WAAW,CAAC,IAAY;QACpB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IAC1B,CAAC;IAED,KAAK;QACD,OAAO;YACH,QAAQ,EAAE,IAAI,CAAC,SAAS;YACxB,OAAO,EAAE,IAAI,CAAC,QAAQ;SACzB,CAAC;IACN,CAAC;CACJ;AArCD,gDAqCC"}