commandmate 0.49.2 → 0.50.0

package/dist/cli/utils/api-client.js

@@ -9,14 +9,10 @@
  * - ApiClient: HTTP get/post with base URL and auth headers
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DeadlineExceededError = exports.ApiError = exports.ApiClient = exports.FOREIGN_SESSION_ERROR_CODE = exports.MAX_STOP_PATTERN_LENGTH = void 0;
+exports.ApiClient = exports.MAX_STOP_PATTERN_LENGTH = exports.rethrowIfDeadlineExceeded = exports.isDeadlineExceeded = exports.DeadlineExceededError = exports.handleApiError = exports.foreignSessionMessage = exports.FOREIGN_SESSION_ERROR_CODE = exports.ApiError = void 0;
 exports.isValidWorktreeId = isValidWorktreeId;
 exports.isValidInstanceId = isValidInstanceId;
 exports.resolveAuthToken = resolveAuthToken;
-exports.foreignSessionMessage = foreignSessionMessage;
-exports.handleApiError = handleApiError;
-exports.isDeadlineExceeded = isDeadlineExceeded;
-exports.rethrowIfDeadlineExceeded = rethrowIfDeadlineExceeded;
 exports.assertResponseShape = assertResponseShape;
 exports.fetchDaemonVersion = fetchDaemonVersion;
 exports.warnIfVersionSkew = warnIfVersionSkew;
@@ -24,6 +20,17 @@ const types_1 = require("../types");
 const package_info_1 = require("./package-info");
 const uat_isolation_1 = require("../../config/uat-isolation");
 const server_url_1 = require("./server-url");
+const api_client_errors_1 = require("./api-client-errors");
+const api_client_deadline_1 = require("./api-client-deadline");
+var api_client_errors_2 = require("./api-client-errors");
+Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return api_client_errors_2.ApiError; } });
+Object.defineProperty(exports, "FOREIGN_SESSION_ERROR_CODE", { enumerable: true, get: function () { return api_client_errors_2.FOREIGN_SESSION_ERROR_CODE; } });
+Object.defineProperty(exports, "foreignSessionMessage", { enumerable: true, get: function () { return api_client_errors_2.foreignSessionMessage; } });
+Object.defineProperty(exports, "handleApiError", { enumerable: true, get: function () { return api_client_errors_2.handleApiError; } });
+var api_client_deadline_2 = require("./api-client-deadline");
+Object.defineProperty(exports, "DeadlineExceededError", { enumerable: true, get: function () { return api_client_deadline_2.DeadlineExceededError; } });
+Object.defineProperty(exports, "isDeadlineExceeded", { enumerable: true, get: function () { return api_client_deadline_2.isDeadlineExceeded; } });
+Object.defineProperty(exports, "rethrowIfDeadlineExceeded", { enumerable: true, get: function () { return api_client_deadline_2.rethrowIfDeadlineExceeded; } });
 /** Maximum stop-pattern length [SEC4-06] */
 exports.MAX_STOP_PATTERN_LENGTH = 500;
 /** Worktree ID validation pattern [SEC4-04] */
@@ -68,175 +75,6 @@ function resolveAuthToken(options) {
     }
     return process.env.CM_AUTH_TOKEN;
 }
-/**
- * The server's own explanation for a failure, when it sent one worth showing.
- *
- * Issue #1637: every 5xx used to be flattened into `Server error. Check server
- * logs for details.`, which is only useful to someone who has the server logs.
- * A cold-start `send` failed with an initialization timeout and told the
- * operator nothing but "go read the logs" — four orchestration runs in a row
- * then misdiagnosed it as a session-creation race and worked around it by
- * re-sending. Every route in this codebase already answers `{ error }`, so the
- * cause was always in the response body; nothing read it.
- *
- * Trimmed and length-capped because it is printed to a terminal, and an
- * unbounded server string is not something a CLI should paste verbatim.
- */
-const MAX_SERVER_ERROR_DETAIL = 2000;
-function serverErrorDetail(payload) {
-    const detail = typeof payload?.error === 'string' ? payload.error.trim() : '';
-    if (detail === '')
-        return undefined;
-    return detail.length > MAX_SERVER_ERROR_DETAIL
-        ? `${detail.slice(0, MAX_SERVER_ERROR_DETAIL)}…`
-        : detail;
-}
-/** Append `(server: <url>)` when the caller named one. */
-function withServerUrl(message, context) {
-    return context?.serverUrl ? `${message} (server: ${context.serverUrl})` : message;
-}
-/**
- * The `code` the server sends with the 409 for a tmux session another
- * CommandMate server created (Issue #2865). Spelled out rather than imported:
- * the server's constant lives next to the tmux gateway, which the CLI must not
- * load. `tests/unit/cli/utils/api-client-foreign-session-3334.test.ts` pins the
- * two to the same string.
- */
-exports.FOREIGN_SESSION_ERROR_CODE = 'session_owned_by_other_server';
-/**
- * Issue #3334: what the operator reads for that 409. It has to say three
- * things the status alone does not: the session is another CommandMate
- * server's, this command therefore did nothing to it, and where to go instead.
- */
-function foreignSessionMessage(payload) {
-    const name = typeof payload?.sessionName === 'string' && payload.sessionName !== ''
-        ? `"${payload.sessionName}" `
-        : '';
-    const where = typeof payload?.sessionPath === 'string' && payload.sessionPath !== ''
-        ? ` (it was started in ${payload.sessionPath})`
-        : '';
-    return (`The tmux session ${name}belongs to another CommandMate server${where}, ` +
-        'so nothing was sent to it, read from it or stopped. ' +
-        'Use the CommandMate server that started it, or stop that session there first.');
-}
-/**
- * Classify API errors into user-friendly messages and exit codes.
- * [IA3-09] Covers: ECONNREFUSED, 400, 401/403, 404, 429, 500, timeout
- *
- * @param error - Error object or unknown
- * @param status - HTTP status code if available
- * @param payload - Parsed error body, when the response carried one (Issue #1637).
- *   Used for 5xx, and for the foreign-session 409 (Issue #3334): the other 4xx
- *   messages below are already specific, and are pinned by tests as the CLI's
- *   own wording.
- * @param context - Which server answered, when the caller knows (Issue #2404).
- *   Read by the 404 branch only; the other messages do not send anyone looking
- *   in the wrong place.
- * @returns User-friendly error message and exit code
- */
-function handleApiError(error, status, payload, context) {
-    // HTTP status-based errors
-    if (status !== undefined) {
-        switch (status) {
-            case 400:
-                return {
-                    message: 'Bad request. Check your input parameters.',
-                    exitCode: types_1.ExitCode.CONFIG_ERROR,
-                };
-            case 401:
-            case 403:
-                // Issue #2489: the second sentence is the one that matters during a
-                // `commandmate remote` session. `remote` mints the token, hands its
-                // plaintext to the phone once through the pairing handoff and deletes
-                // it — so "set CM_AUTH_TOKEN" names a value the operator has no way to
-                // obtain, and following that advice is a dead end (#2489's report spent
-                // a session there). `--auth remote-only` is the exit: it leaves the
-                // loopback listener this client dials unauthenticated while the
-                // Provider's listener keeps demanding the token.
-                return {
-                    message: 'Authentication failed. Use --token <token> or set CM_AUTH_TOKEN environment variable. ' +
-                        'During a "commandmate remote" session the token is only ever shown to the paired phone — ' +
-                        'restart it with "commandmate remote --auth remote-only" to use the CLI from this machine without one.',
-                    exitCode: types_1.ExitCode.CONFIG_ERROR,
-                };
-            case 404:
-                // Issue #2404: the sentence stays, so everything matching on it keeps
-                // matching; the URL is appended because "check the worktree ID" is
-                // advice about the wrong thing whenever the id is fine and the SERVER
-                // is the one that is wrong.
-                return {
-                    message: withServerUrl('Resource not found. Check the worktree ID.', context),
-                    exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
-                };
-            case 409:
-                // Issue #3334: the one 409 every session route shares (#2865 / #3290).
-                // Without this it read "Unexpected HTTP status: 409", which does not say
-                // that nothing was done, nor why. Same exit code as that default branch,
-                // so a script branching on it sees no change. Every other 409 keeps the
-                // default wording below — the commands that own one (send's
-                // PROMPT_WAITING, verify's running run) already explain it themselves.
-                if (payload?.code === exports.FOREIGN_SESSION_ERROR_CODE) {
-                    return {
-                        message: foreignSessionMessage(payload),
-                        exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
-                    };
-                }
-                return {
-                    message: `Unexpected HTTP status: ${status}`,
-                    exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
-                };
-            case 429:
-                return {
-                    message: 'Rate limited. Please retry after a moment.',
-                    exitCode: types_1.ExitCode.DEPENDENCY_ERROR,
-                };
-            case 500:
-            default:
-                if (status >= 500) {
-                    // Issue #1637: pass the server's own reason through. The prefix is
-                    // kept so "this came from the server, not from the CLI" survives, and
-                    // so does the log pointer when the body said nothing.
-                    const detail = serverErrorDetail(payload);
-                    return {
-                        message: detail
-                            ? `Server error: ${detail}`
-                            : 'Server error. Check server logs for details.',
-                        exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
-                    };
-                }
-                return {
-                    message: `Unexpected HTTP status: ${status}`,
-                    exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
-                };
-        }
-    }
-    // Network/connection errors
-    if (error instanceof Error) {
-        const msg = error.message || '';
-        if (msg.includes('ECONNREFUSED') || msg.includes('fetch failed')) {
-            return {
-                message: 'Server is not running. Start it with: commandmate start',
-                exitCode: types_1.ExitCode.DEPENDENCY_ERROR,
-            };
-        }
-        if (error.name === 'AbortError' || msg.includes('timeout') || msg.includes('Timeout')) {
-            return {
-                message: 'Server did not respond in time. Check server status.',
-                exitCode: types_1.ExitCode.DEPENDENCY_ERROR,
-            };
-        }
-        if (error.name === 'TypeError') {
-            return {
-                message: 'Network error. Check your connection and server status.',
-                exitCode: types_1.ExitCode.DEPENDENCY_ERROR,
-            };
-        }
-    }
-    return {
-        message: 'An unexpected error occurred.',
-        exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
-    };
-}
 /**
  * Check if a URL points to a localhost address.
  */
@@ -270,7 +108,7 @@ class ApiClient {
         // Issue #3360: in UAT isolation the default port 3000 is the user's production server,
         // so a client that was not told where to go must not go anywhere.
         if (!options?.baseUrl && (0, uat_isolation_1.isUatIsolationEnabled)() && !process.env.CM_PORT) {
-            throw new ApiError(`${uat_isolation_1.UAT_ISOLATION_ENV_VAR}=${process.env[uat_isolation_1.UAT_ISOLATION_ENV_VAR]} requires CM_PORT: refusing to fall back to the default port 3000.`, types_1.ExitCode.CONFIG_ERROR);
+            throw new api_client_errors_1.ApiError(`${uat_isolation_1.UAT_ISOLATION_ENV_VAR}=${process.env[uat_isolation_1.UAT_ISOLATION_ENV_VAR]} requires CM_PORT: refusing to fall back to the default port 3000.`, types_1.ExitCode.CONFIG_ERROR);
         }
         this.baseUrl = options?.baseUrl || (0, server_url_1.resolveServerEndpoint)((0, server_url_1.loadClientEnv)()).url;
         this.token = resolveAuthToken(options);
@@ -409,21 +247,21 @@ class ApiClient {
                 // Issue #1637: read the body first — handleApiError needs it to surface
                 // the server's reason for a 5xx instead of "check the logs".
                 const payload = await bounded(deadline, readErrorPayload(response));
-                const errResult = handleApiError(null, response.status, payload, { serverUrl: this.baseUrl });
-                throw new ApiError(errResult.message, errResult.exitCode, response.status, payload);
+                const errResult = (0, api_client_errors_1.handleApiError)(null, response.status, payload, { serverUrl: this.baseUrl });
+                throw new api_client_errors_1.ApiError(errResult.message, errResult.exitCode, response.status, payload);
             }
             return (await bounded(deadline, response.json()));
         }
         catch (error) {
             if (deadline) {
                 const classified = deadline.classify(error);
-                if (classified instanceof DeadlineExceededError)
+                if (classified instanceof api_client_deadline_1.DeadlineExceededError)
                     throw classified;
             }
-            if (error instanceof ApiError)
+            if (error instanceof api_client_errors_1.ApiError)
                 throw error;
-            const errResult = handleApiError(error);
-            throw new ApiError(errResult.message, errResult.exitCode);
+            const errResult = (0, api_client_errors_1.handleApiError)(error);
+            throw new api_client_errors_1.ApiError(errResult.message, errResult.exitCode);
         }
         finally {
             deadline?.release();
@@ -444,9 +282,21 @@ class ApiClient {
     async patch(path, body) {
         return sendWithBody(this.baseUrl, 'PATCH', this.getHeaders(), path, body, this.startDeadline());
     }
+    /**
+     * HTTP PUT request (Issue #4116: the role settings routes).
+     *
+     * @param headers - Added to this request: a condition, not part of the body (Issue #4132)
+     */
+    async put(path, body, headers) {
+        return sendWithBody(this.baseUrl, 'PUT', { ...this.getHeaders(), ...headers }, path, body, this.startDeadline());
+    }
+    /** HTTP DELETE request (Issue #4116: `roles rm`). */
+    async delete(path) {
+        return sendWithBody(this.baseUrl, 'DELETE', this.getHeaders(), path, undefined, this.startDeadline());
+    }
 }
 exports.ApiClient = ApiClient;
-/** POST / PATCH share everything but the method; an empty body (204) is `undefined`. */
+/** POST / PATCH / PUT / DELETE share everything but the method; an empty body (204) is `undefined`. */
 async function sendWithBody(baseUrl, method, headers, path, body, deadline) {
     try {
         const response = await bounded(deadline, fetch(`${baseUrl}${path}`, {
@@ -459,8 +309,8 @@ async function sendWithBody(baseUrl, method, headers, path, body, deadline) {
             // Issue #1637: read the body first — handleApiError needs it to surface
             // the server's reason for a 5xx instead of "check the logs".
             const payload = await bounded(deadline, readErrorPayload(response));
-            const errResult = handleApiError(null, response.status, payload, { serverUrl: baseUrl });
-            throw new ApiError(errResult.message, errResult.exitCode, response.status, payload);
+            const errResult = (0, api_client_errors_1.handleApiError)(null, response.status, payload, { serverUrl: baseUrl });
+            throw new api_client_errors_1.ApiError(errResult.message, errResult.exitCode, response.status, payload);
         }
         // Handle 204 No Content
         const text = await bounded(deadline, response.text());
@@ -471,13 +321,13 @@ async function sendWithBody(baseUrl, method, headers, path, body, deadline) {
     catch (error) {
         if (deadline) {
             const classified = deadline.classify(error);
-            if (classified instanceof DeadlineExceededError)
+            if (classified instanceof api_client_deadline_1.DeadlineExceededError)
                 throw classified;
         }
-        if (error instanceof ApiError)
+        if (error instanceof api_client_errors_1.ApiError)
             throw error;
-        const errResult = handleApiError(error);
-        throw new ApiError(errResult.message, errResult.exitCode, undefined, undefined, error);
+        const errResult = (0, api_client_errors_1.handleApiError)(error);
+        throw new api_client_errors_1.ApiError(errResult.message, errResult.exitCode, undefined, undefined, error);
     }
     finally {
         deadline?.release();
@@ -509,76 +359,11 @@ async function readErrorPayload(response) {
         return undefined;
     }
 }
-/**
- * API Error with exit code for CLI process.exit()
- */
-class ApiError extends Error {
-    exitCode;
-    statusCode;
-    payload;
-    transportError;
-    constructor(message, exitCode, statusCode, 
-    /** Typed error body, when the server sent one (Issue #1237). */
-    payload, 
-    /**
-     * The error `fetch` threw, when no HTTP response came back (Issue #3756):
-     * the strict `respond` tells "never connected" (nothing can have been sent)
-     * from "the connection broke" by its `cause.code`.
-     */
-    transportError) {
-        super(message);
-        this.exitCode = exitCode;
-        this.statusCode = statusCode;
-        this.payload = payload;
-        this.transportError = transportError;
-        this.name = 'ApiError';
-    }
-    /** Stable machine code the server assigned to this failure, if any. */
-    get apiCode() {
-        return this.payload?.code;
-    }
-}
-exports.ApiError = ApiError;
 // =============================================================================
 // Command deadline (Issue #3983)
 // =============================================================================
 /** The longest delay `setTimeout` honours (2^31-1 ms, ~24.8 days). */
 const MAX_TIMER_MS = 2 ** 31 - 1;
-/**
- * A request ended by the deadline of a client from {@link ApiClient.withDeadline}
- * (Issue #3983).
- *
- * An `ApiError` with exit 124 so that the commands' own error handling reports
- * it as the timeout it is, and a class of its own so that a catch which turns
- * failures into a degraded result ("verification resolves its own task", "use
- * the selector as an instance id") can tell it apart and rethrow it — see
- * {@link isDeadlineExceeded}. Wrapped into another `ApiError`, it travels as
- * that error's `transportError`.
- */
-class DeadlineExceededError extends ApiError {
-    constructor(serverUrl) {
-        super(withServerUrl('--timeout reached before the server answered', { serverUrl }), types_1.WaitExitCode.TIMEOUT);
-        this.name = 'DeadlineExceededError';
-    }
-}
-exports.DeadlineExceededError = DeadlineExceededError;
-/**
- * Whether `error` is — or wraps — a request ended by a command deadline
- * (Issue #3983). The catches that degrade on failure ask this first and
- * rethrow: a deadline is the command's answer, not a reason to carry on.
- */
-function isDeadlineExceeded(error) {
-    if (error instanceof DeadlineExceededError)
-        return true;
-    if (error instanceof ApiError && error.transportError instanceof DeadlineExceededError)
-        return true;
-    return error instanceof Error && error.cause instanceof DeadlineExceededError;
-}
-/** Rethrow `error` when it is a command deadline; otherwise return (Issue #3983). */
-function rethrowIfDeadlineExceeded(error) {
-    if (isDeadlineExceeded(error))
-        throw error;
-}
 /**
  * Arm the deadline of one request. Its signal goes to `fetch` (which then also
  * aborts the body stream), and every await of the request is raced against it
@@ -592,7 +377,7 @@ function startRequestDeadline(deadlineAt, serverUrl, callerSignal) {
     const controller = new AbortController();
     const fire = () => {
         if (!controller.signal.aborted)
-            controller.abort(new DeadlineExceededError(serverUrl));
+            controller.abort(new api_client_deadline_1.DeadlineExceededError(serverUrl));
     };
     const remaining = deadlineAt - Date.now();
     let timer;
@@ -605,9 +390,9 @@ function startRequestDeadline(deadlineAt, serverUrl, callerSignal) {
         timer.unref?.();
     }
     const signal = callerSignal ? AbortSignal.any([controller.signal, callerSignal]) : controller.signal;
-    const deadlineError = () => controller.signal.reason instanceof DeadlineExceededError
+    const deadlineError = () => controller.signal.reason instanceof api_client_deadline_1.DeadlineExceededError
         ? controller.signal.reason
-        : new DeadlineExceededError(serverUrl);
+        : new api_client_deadline_1.DeadlineExceededError(serverUrl);
     return {
         signal,
         run(promise) {
@@ -686,12 +471,12 @@ function versionSkewMessage(detail) {
  */
 function assertResponseShape(value, fields, context) {
     if (value === null || typeof value !== 'object') {
-        throw new ApiError(versionSkewMessage(`${context}: expected an object from the server`), types_1.ExitCode.UNEXPECTED_ERROR);
+        throw new api_client_errors_1.ApiError(versionSkewMessage(`${context}: expected an object from the server`), types_1.ExitCode.UNEXPECTED_ERROR);
     }
     const record = value;
     for (const field of fields) {
         if (!(field in record)) {
-            throw new ApiError(versionSkewMessage(`${context}: the server response is missing the "${field}" field`), types_1.ExitCode.UNEXPECTED_ERROR);
+            throw new api_client_errors_1.ApiError(versionSkewMessage(`${context}: the server response is missing the "${field}" field`), types_1.ExitCode.UNEXPECTED_ERROR);
         }
     }
     return value;

package/dist/cli/utils/role-failure.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The role API's refusals as an exit code (Issue #4116). On its own, free of the file
+ * system and of catches, because `message-dispatch.ts` reads it and that is on the
+ * paths `wait` / `ask` / `verify` hold to their deadline.
+ */
+import { ApiError, type ApiErrorPayload } from './api-client';
+/**
+ * A role command's failure, with the code `--json` reports. An {@link ApiError}, so
+ * `handleCommandError` prints it and exits with its code in a command that has no
+ * `--json` of its own.
+ */
+export declare class RoleCliError extends ApiError {
+    readonly code: string;
+    /** Extra keys of the `--json` failure, such as `candidates` or `references`. */
+    readonly details: Record<string, unknown>;
+    constructor(code: string, message: string, exitCode: number, 
+    /** Extra keys of the `--json` failure, such as `candidates` or `references`. */
+    details?: Record<string, unknown>, statusCode?: number, payload?: ApiErrorPayload);
+}
+/** Said on every refusal after a save, so nobody takes the old setting to be still there. */
+export declare const ROLE_STAYED_SAVED = "The role setting stayed saved, so after a restart the message can be sent again without --role.";
+/** Whether a send's refusal says its role was saved before it. */
+export declare function roleSettingSavedBy(error: unknown): boolean;
+/**
+ * The role failure an API error is, or null when it is not one. The management
+ * routes put their code in `error` and their sentence in `message`; the send and
+ * task routes put the code in `code` and the sentence in `error`.
+ */
+export declare function roleFailureFromApi(error: unknown): RoleCliError | null;
+export declare function usageError(message: string): RoleCliError;
+//# sourceMappingURL=role-failure.d.ts.map

package/dist/cli/utils/role-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-failure.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/role-failure.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAE9D;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,QAAQ;aAEtB,IAAI,EAAE,MAAM;IAG5B,gFAAgF;aAChE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAJhC,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM;IAChB,gFAAgF;IAChE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACrD,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,eAAe;CAK5B;AAED,6FAA6F;AAC7F,eAAO,MAAM,iBAAiB,oGACqE,CAAC;AAEpG,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAkBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI,CAqBtE;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAExD"}

package/dist/cli/utils/role-failure.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * The role API's refusals as an exit code (Issue #4116). On its own, free of the file
+ * system and of catches, because `message-dispatch.ts` reads it and that is on the
+ * paths `wait` / `ask` / `verify` hold to their deadline.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLE_STAYED_SAVED = exports.RoleCliError = void 0;
+exports.roleSettingSavedBy = roleSettingSavedBy;
+exports.roleFailureFromApi = roleFailureFromApi;
+exports.usageError = usageError;
+const types_1 = require("../types");
+const api_client_1 = require("./api-client");
+/**
+ * A role command's failure, with the code `--json` reports. An {@link ApiError}, so
+ * `handleCommandError` prints it and exits with its code in a command that has no
+ * `--json` of its own.
+ */
+class RoleCliError extends api_client_1.ApiError {
+    code;
+    details;
+    constructor(code, message, exitCode, 
+    /** Extra keys of the `--json` failure, such as `candidates` or `references`. */
+    details = {}, statusCode, payload) {
+        super(message, exitCode, statusCode, payload);
+        this.code = code;
+        this.details = details;
+        this.name = 'RoleCliError';
+    }
+}
+exports.RoleCliError = RoleCliError;
+/** Said on every refusal after a save, so nobody takes the old setting to be still there. */
+exports.ROLE_STAYED_SAVED = 'The role setting stayed saved, so after a restart the message can be sent again without --role.';
+/** Whether a send's refusal says its role was saved before it. */
+function roleSettingSavedBy(error) {
+    return error instanceof api_client_1.ApiError && error.payload?.roleSettings?.saved === true;
+}
+const ROLE_ROUTE_EXITS = {
+    invalid_request: types_1.ExitCode.CONFIG_ERROR,
+    not_found: types_1.ExitCode.CONFIG_ERROR,
+    tool_not_supported: types_1.ExitCode.CONFIG_ERROR,
+    name_conflict: types_1.RoleExitCode.CONFLICT,
+    version_conflict: types_1.RoleExitCode.CONFLICT,
+    name_changed: types_1.RoleExitCode.CONFLICT,
+    role_in_use: types_1.RoleExitCode.CONFLICT,
+    instance_exists: types_1.RoleExitCode.CONFLICT,
+    roster_changed: types_1.RoleExitCode.CONFLICT,
+    // Mirror ROLE_CONDITION_UNMET_CODE and its neighbours in `lib/agent-roles/launch-errors`.
+    ROLE_CONDITION_UNMET: types_1.RoleExitCode.NOT_SENT,
+    ROLE_LAUNCH_REFUSED: types_1.RoleExitCode.NOT_SENT,
+    SESSION_LAUNCH_ROLE_MISMATCH: types_1.RoleExitCode.NOT_SENT,
+};
+/**
+ * The role failure an API error is, or null when it is not one. The management
+ * routes put their code in `error` and their sentence in `message`; the send and
+ * task routes put the code in `code` and the sentence in `error`.
+ */
+function roleFailureFromApi(error) {
+    if (!(error instanceof api_client_1.ApiError) || !error.payload)
+        return null;
+    const { payload } = error;
+    const managementShape = payload.success === false && typeof payload.message === 'string';
+    const code = managementShape ? payload.error : payload.code;
+    const sentence = managementShape ? payload.message : payload.error;
+    if (typeof code !== 'string' || typeof sentence !== 'string')
+        return null;
+    // A `not_found` from `/send` is the role's only when it says what became of the setting.
+    if (!managementShape && !payload.roleSettings && !code.startsWith('ROLE_') && !code.startsWith('SESSION_LAUNCH_ROLE')) {
+        return null;
+    }
+    const exitCode = ROLE_ROUTE_EXITS[code];
+    if (exitCode === undefined)
+        return null;
+    const details = {};
+    if (payload.references !== undefined)
+        details.references = payload.references;
+    if (payload.currentBodyVersion !== undefined)
+        details.currentBodyVersion = payload.currentBodyVersion;
+    if (payload.roleRefusal !== undefined)
+        details.roleRefusal = payload.roleRefusal;
+    if (payload.roleSettings !== undefined)
+        details.roleSettings = payload.roleSettings;
+    if (payload.sendOutcome !== undefined)
+        details.sendOutcome = payload.sendOutcome;
+    const saved = payload.roleSettings?.saved === true ? ` ${exports.ROLE_STAYED_SAVED}` : '';
+    return new RoleCliError(code, `${sentence}${saved}`, exitCode, details, error.statusCode, payload);
+}
+function usageError(message) {
+    return new RoleCliError('invalid_request', message, types_1.ExitCode.CONFIG_ERROR);
+}

package/dist/cli/utils/role-input.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What a role command reads from this machine rather than the server (Issue #4116):
+ * a role's body, and how a path looks here. It makes no request, so nothing here can
+ * sit on a `--timeout`.
+ */
+export declare function canonicalPath(value: string): string;
+export declare function isDirectory(value: string): boolean;
+/**
+ * The body named by `--file` / `--stdin`, or undefined when neither was given.
+ * A terminal on stdin is refused rather than waited on: this is never interactive.
+ */
+export declare function readRoleBodyOption(options: {
+    file?: string;
+    stdin?: boolean;
+}): Promise<string | undefined>;
+//# sourceMappingURL=role-input.d.ts.map

package/dist/cli/utils/role-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-input.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/role-input.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAMlD;AAuBD;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAgBjH"}

package/dist/cli/utils/role-input.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * What a role command reads from this machine rather than the server (Issue #4116):
+ * a role's body, and how a path looks here. It makes no request, so nothing here can
+ * sit on a `--timeout`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalPath = canonicalPath;
+exports.isDirectory = isDirectory;
+exports.readRoleBodyOption = readRoleBodyOption;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const agent_roles_1 = require("../../types/agent-roles");
+const role_failure_1 = require("./role-failure");
+function canonicalPath(value) {
+    const resolved = node_path_1.default.resolve(value);
+    try {
+        return node_fs_1.default.realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+function isDirectory(value) {
+    try {
+        return node_fs_1.default.statSync(value).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Keeps every byte, a BOM included: the body reaches the model as written. */
+function decodeRoleBody(bytes, source) {
+    if (bytes.byteLength > agent_roles_1.MAX_ROLE_BODY_BYTES) {
+        throw (0, role_failure_1.usageError)(`The body from ${source} is ${bytes.byteLength} bytes; a role holds at most ${agent_roles_1.MAX_ROLE_BODY_BYTES}.`);
+    }
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw (0, role_failure_1.usageError)(`The body from ${source} is not valid UTF-8.`);
+    }
+}
+async function readAll(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        // Kept as bytes until the end: a character can be split across two chunks.
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk);
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * The body named by `--file` / `--stdin`, or undefined when neither was given.
+ * A terminal on stdin is refused rather than waited on: this is never interactive.
+ */
+async function readRoleBodyOption(options) {
+    if (options.file !== undefined && options.stdin)
+        throw (0, role_failure_1.usageError)('Give the body with --file or --stdin, not both.');
+    if (options.file !== undefined) {
+        let bytes;
+        try {
+            bytes = node_fs_1.default.readFileSync(options.file);
+        }
+        catch (error) {
+            throw (0, role_failure_1.usageError)(`Could not read ${options.file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return decodeRoleBody(bytes, options.file);
+    }
+    if (!options.stdin)
+        return undefined;
+    if (process.stdin.isTTY) {
+        throw (0, role_failure_1.usageError)('--stdin needs the body piped in; a terminal is not read. Use --file, or pipe it.');
+    }
+    return decodeRoleBody(await readAll(process.stdin), 'stdin');
+}

package/dist/cli/utils/security-logger.d.ts

@@ -16,6 +16,23 @@ export interface SecurityEvent {
     /** Additional details */
     details?: string;
 }
+/**
+ * Get security log file path
+ *
+ * Issue #4210: `CM_LOG_DIR` is judged the way `getLogDir()`
+ * (`config/log-config.ts`) judges it for every other log writer. A value inside
+ * `/proc`, `/sys` or `/dev` — literally, through a symlink, or as the absolute
+ * form of a relative value — is refused and the default file is used. A
+ * relative value is otherwise kept as given and so resolved against this
+ * process's cwd, which is also what `getLogDir()` does: the file is only ever
+ * opened by the process that resolved it, so nothing else has to agree on it.
+ *
+ * The default stays `~/.commandmate-security.log` rather than `getLogDir()`'s
+ * `<cwd>/data/logs`: a CLI run from an arbitrary directory has no `data/logs`.
+ *
+ * @returns The file security events are appended to
+ */
+export declare function getSecurityLogPath(): string;
 /**
  * Log a security event
  * Silently fails if file operations fail (non-critical)

package/dist/cli/utils/security-logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"security-logger.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/security-logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC1C,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAaD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAU3D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAY/E"}
+{"version":3,"file":"security-logger.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/security-logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC1C,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAO3C;AAqBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAU3D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAY/E"}