propr-cli 0.8.3

package/dist/api/agents.js

@@ -0,0 +1,201 @@
+/**
+ * Agents API
+ *
+ * Functions for interacting with the ProPR backend agent configuration endpoints.
+ * These functions provide a typed interface to list, add, and delete agents.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createApiClient } from "./index.js";
+export const AGENT_TYPES = ["claude", "codex", "antigravity", "opencode", "vibe"];
+// Keep in sync with packages/core/src/agents/version/types.ts AGENT_IMAGE_NAMES
+const AGENT_IMAGE_NAMES = {
+    claude: "propr/agent-claude",
+    codex: "propr/agent-codex",
+    antigravity: "propr/agent-antigravity",
+    opencode: "propr/agent-opencode",
+    vibe: "propr/agent-vibe",
+};
+/**
+ * Lists all configured agents.
+ *
+ * @param client - Optional ApiClient instance. If not provided, one will be created.
+ * @returns A promise resolving to the list of agent configurations.
+ *
+ * @example
+ * ```typescript
+ * // List all agents
+ * const result = await listAgents();
+ * console.log(`Found ${result.agents.length} agents`);
+ * ```
+ */
+export async function listAgents(client) {
+    const apiClient = client ?? (await createApiClient());
+    const response = await apiClient.get("/api/config/agents");
+    return response.data;
+}
+/**
+ * Adds a new agent configuration.
+ *
+ * This function first fetches the existing agents, adds the new one,
+ * and then saves the updated list.
+ *
+ * @param options - Options for the new agent.
+ * @param client - Optional ApiClient instance. If not provided, one will be created.
+ * @returns A promise resolving to the save response.
+ *
+ * @example
+ * ```typescript
+ * // Add a new Claude agent
+ * const result = await addAgent({
+ *   alias: 'claude-prod',
+ *   type: 'claude',
+ *   models: ['claude-sonnet-4-20250514', 'claude-opus-4-20250514']
+ * });
+ * ```
+ */
+export async function addAgent(options, client) {
+    const apiClient = client ?? (await createApiClient());
+    // Fetch existing agents
+    const existingResponse = await apiClient.get("/api/config/agents");
+    const existingAgents = existingResponse.data.agents || [];
+    // Check if alias already exists
+    const aliasExists = existingAgents.some((agent) => agent.alias.toLowerCase() === options.alias.toLowerCase());
+    if (aliasExists) {
+        throw new Error(`Agent with alias '${options.alias}' already exists`);
+    }
+    const configPath = options.configPath || resolveDefaultConfigPath(options.type, apiClient);
+    // Create new agent config
+    const newAgent = {
+        id: crypto.randomUUID(),
+        type: options.type,
+        alias: options.alias,
+        enabled: options.enabled !== undefined ? options.enabled : true,
+        dockerImage: options.dockerImage || getDefaultDockerImage(options.type),
+        configPath,
+        supportedModels: options.models,
+        defaultModel: options.defaultModel || options.models[0],
+    };
+    // Add new agent to the list
+    const updatedAgents = [...existingAgents, newAgent];
+    // Save the updated list
+    const response = await apiClient.post("/api/config/agents", {
+        body: { agents: updatedAgents },
+    });
+    return response.data;
+}
+/**
+ * Deletes an agent by alias.
+ *
+ * @param alias - The alias of the agent to delete.
+ * @param client - Optional ApiClient instance. If not provided, one will be created.
+ * @returns A promise resolving to the save response.
+ *
+ * @example
+ * ```typescript
+ * // Delete an agent
+ * await deleteAgent('claude-prod');
+ * ```
+ */
+export async function deleteAgent(alias, client) {
+    const apiClient = client ?? (await createApiClient());
+    // Fetch existing agents
+    const existingResponse = await apiClient.get("/api/config/agents");
+    const existingAgents = existingResponse.data.agents || [];
+    // Find the agent to delete
+    const agentIndex = existingAgents.findIndex((agent) => agent.alias.toLowerCase() === alias.toLowerCase());
+    if (agentIndex === -1) {
+        throw new Error(`Agent with alias '${alias}' not found`);
+    }
+    // Remove the agent
+    const updatedAgents = existingAgents.filter((_, index) => index !== agentIndex);
+    // Save the updated list
+    const response = await apiClient.post("/api/config/agents", {
+        body: { agents: updatedAgents },
+    });
+    return response.data;
+}
+/**
+ * Enables or disables an agent by alias.
+ *
+ * Fetches the full agents array, flips the `enabled` flag on the matching entry,
+ * and saves it back (full-array replace, matching the web UI). Requires the
+ * backend API to be reachable (i.e. the stack is running).
+ *
+ * @param alias - The alias of the agent to toggle.
+ * @param enabled - The desired enabled state.
+ * @param client - Optional ApiClient instance.
+ * @returns A promise resolving to the save response.
+ */
+export async function setAgentEnabled(alias, enabled, client) {
+    const apiClient = client ?? (await createApiClient());
+    const existingResponse = await apiClient.get("/api/config/agents");
+    const existingAgents = existingResponse.data.agents || [];
+    const target = existingAgents.find((agent) => agent.alias.toLowerCase() === alias.toLowerCase());
+    if (!target) {
+        throw new Error(`Agent with alias '${alias}' not found`);
+    }
+    const updatedAgents = existingAgents.map((agent) => agent === target ? { ...agent, enabled } : agent);
+    // Full-array replace can overwrite concurrent web/CLI edits until the API
+    // exposes a per-agent PATCH endpoint.
+    const response = await apiClient.post("/api/config/agents", {
+        body: { agents: updatedAgents },
+    });
+    return response.data;
+}
+/**
+ * Gets the default Docker image for an agent type.
+ *
+ * @param type - The agent type.
+ * @returns The default Docker image name.
+ */
+function getDefaultDockerImage(type) {
+    const name = AGENT_IMAGE_NAMES[type];
+    return name ? `${name}:latest` : `${type}-code-processor:latest`;
+}
+/**
+ * Gets the default config path for an agent type.
+ *
+ * Returns a path under the local user's home directory. This is correct for
+ * Docker-outside-Docker setups where the CLI and server share the same host,
+ * but will produce an incorrect path if the CLI talks to a remote ProPR
+ * server. In remote setups, always pass an explicit `configPath` instead.
+ *
+ * @param type - The agent type.
+ * @returns The default config path.
+ */
+function getDefaultConfigPath(type) {
+    const home = homedir();
+    switch (type) {
+        case "claude":
+            return join(home, ".claude");
+        case "codex":
+            return join(home, ".codex");
+        case "antigravity":
+            return join(home, ".gemini");
+        case "opencode":
+            return join(home, ".config", "opencode");
+        case "vibe":
+            return join(home, ".vibe");
+        default:
+            return join(home, `.${type}`);
+    }
+}
+function isRemoteApiUrl(baseUrl) {
+    try {
+        const hostname = new URL(baseUrl).hostname;
+        return hostname !== "localhost" && hostname !== "127.0.0.1" && hostname !== "::1";
+    }
+    catch {
+        return false;
+    }
+}
+function resolveDefaultConfigPath(type, client) {
+    const baseUrl = typeof client.getBaseUrl === "function" ? client.getBaseUrl() : "http://localhost";
+    if (isRemoteApiUrl(baseUrl)) {
+        throw new Error(`Cannot infer config path for a remote ProPR server (${baseUrl}). ` +
+            `Pass --config-path explicitly with the host path on the server ` +
+            `(e.g. --config-path /home/propr/.${type}).`);
+    }
+    return getDefaultConfigPath(type);
+}

package/dist/api/client.js

@@ -0,0 +1,284 @@
+/**
+ * CLI API Client
+ *
+ * A configured HTTP client for communicating with the ProPR backend REST API.
+ * Automatically reads the base URL and authorization headers from ConfigManager
+ * and provides standardized error handling.
+ */
+import { createConfigManager } from "../config/index.js";
+import { ApiError, createApiError, NetworkError, TimeoutError, } from "./errors.js";
+/**
+ * Default base URL for the ProPR backend API.
+ */
+const DEFAULT_BASE_URL = "http://localhost:4000";
+/**
+ * Default request timeout in milliseconds (30 seconds).
+ */
+const DEFAULT_TIMEOUT = 30000;
+/**
+ * API Client for making HTTP requests to the ProPR backend.
+ *
+ * Features:
+ * - Automatic authorization header injection from ConfigManager
+ * - Base URL configuration with default fallback
+ * - Standardized error handling for common HTTP errors
+ * - Request timeout support
+ * - JSON request/response handling
+ *
+ * @example
+ * ```typescript
+ * const client = await createApiClient();
+ *
+ * // Make a GET request
+ * const response = await client.get<{ repos: string[] }>('/api/repos');
+ * console.log(response.data.repos);
+ *
+ * // Make a POST request
+ * const result = await client.post<{ jobId: string }>('/api/jobs', {
+ *   body: { repo: 'owner/repo' }
+ * });
+ * console.log(result.data.jobId);
+ * ```
+ */
+export class ApiClient {
+    configManager;
+    baseUrl;
+    token;
+    defaultTimeout;
+    /**
+     * Creates a new ApiClient instance.
+     *
+     * @param configManager - The ConfigManager instance for reading configuration.
+     * @param options - Optional configuration overrides.
+     */
+    constructor(configManager, options = {}) {
+        this.configManager = configManager;
+        this.baseUrl = options.baseUrl ?? this.configManager.getRemoteUrl() ?? DEFAULT_BASE_URL;
+        this.token = options.token ?? this.configManager.getGithubToken();
+        this.defaultTimeout = options.defaultTimeout ?? DEFAULT_TIMEOUT;
+    }
+    /**
+     * Gets the current base URL.
+     *
+     * @returns The base URL being used for API requests.
+     */
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    /**
+     * Gets whether a token is configured.
+     *
+     * @returns True if a token is available for authentication.
+     */
+    hasToken() {
+        return this.token !== undefined && this.token.length > 0;
+    }
+    /**
+     * Makes an HTTP request to the API.
+     *
+     * @param endpoint - The API endpoint path (will be prepended with base URL).
+     * @param options - Request options.
+     * @returns A promise resolving to the API response.
+     * @throws {UnauthorizedError} When the server returns 401.
+     * @throws {ForbiddenError} When the server returns 403.
+     * @throws {NotFoundError} When the server returns 404.
+     * @throws {BadRequestError} When the server returns 400.
+     * @throws {InternalServerError} When the server returns 500+.
+     * @throws {NetworkError} When a network error occurs.
+     * @throws {TimeoutError} When the request times out.
+     */
+    async request(endpoint, options = {}) {
+        const { method = "GET", body, headers: customHeaders = {}, params, timeout = this.defaultTimeout, } = options;
+        // Build the full URL
+        const url = this.buildUrl(endpoint, params);
+        // Build headers
+        const headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            ...customHeaders,
+        };
+        // Add authorization header if token is available
+        if (this.token) {
+            headers["Authorization"] = `Bearer ${this.token}`;
+        }
+        // Build fetch options
+        const fetchOptions = {
+            method,
+            headers,
+        };
+        // Add body for non-GET requests
+        if (body !== undefined && method !== "GET") {
+            fetchOptions.body = JSON.stringify(body);
+        }
+        // Create abort controller for timeout
+        const controller = new AbortController();
+        fetchOptions.signal = controller.signal;
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const response = await fetch(url, fetchOptions);
+            clearTimeout(timeoutId);
+            // Handle error responses
+            if (!response.ok) {
+                let errorResponse;
+                try {
+                    errorResponse = await response.json();
+                }
+                catch {
+                    // Response body is not JSON or empty
+                }
+                throw createApiError(response.status, errorResponse);
+            }
+            // Parse successful response
+            let data;
+            const contentType = response.headers.get("content-type");
+            if (contentType?.includes("application/json")) {
+                data = await response.json();
+            }
+            else {
+                // Handle non-JSON responses
+                data = await response.text();
+            }
+            return {
+                data,
+                status: response.status,
+                headers: response.headers,
+            };
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            // Re-throw API errors as-is
+            if (error instanceof ApiError) {
+                throw error;
+            }
+            // Handle abort errors (timeout)
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new TimeoutError("Request timed out.", timeout);
+            }
+            // Handle network errors
+            if (error instanceof TypeError) {
+                throw new NetworkError(`Network error: ${error.message}`, error);
+            }
+            // Handle other errors
+            throw new NetworkError(`Unexpected error: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Makes a GET request.
+     *
+     * @param endpoint - The API endpoint path.
+     * @param options - Request options (method will be ignored).
+     * @returns A promise resolving to the API response.
+     */
+    async get(endpoint, options = {}) {
+        return this.request(endpoint, { ...options, method: "GET" });
+    }
+    /**
+     * Makes a POST request.
+     *
+     * @param endpoint - The API endpoint path.
+     * @param options - Request options (method will be ignored).
+     * @returns A promise resolving to the API response.
+     */
+    async post(endpoint, options = {}) {
+        return this.request(endpoint, { ...options, method: "POST" });
+    }
+    /**
+     * Makes a PUT request.
+     *
+     * @param endpoint - The API endpoint path.
+     * @param options - Request options (method will be ignored).
+     * @returns A promise resolving to the API response.
+     */
+    async put(endpoint, options = {}) {
+        return this.request(endpoint, { ...options, method: "PUT" });
+    }
+    /**
+     * Makes a PATCH request.
+     *
+     * @param endpoint - The API endpoint path.
+     * @param options - Request options (method will be ignored).
+     * @returns A promise resolving to the API response.
+     */
+    async patch(endpoint, options = {}) {
+        return this.request(endpoint, { ...options, method: "PATCH" });
+    }
+    /**
+     * Makes a DELETE request.
+     *
+     * @param endpoint - The API endpoint path.
+     * @param options - Request options (method will be ignored).
+     * @returns A promise resolving to the API response.
+     */
+    async delete(endpoint, options = {}) {
+        return this.request(endpoint, { ...options, method: "DELETE" });
+    }
+    /**
+     * Builds the full URL for a request.
+     *
+     * @param endpoint - The API endpoint path.
+     * @param params - Optional query parameters.
+     * @returns The full URL string.
+     */
+    buildUrl(endpoint, params) {
+        // Ensure endpoint starts with /
+        const normalizedEndpoint = endpoint.startsWith("/") ? endpoint : `/${endpoint}`;
+        // Build URL
+        const url = new URL(normalizedEndpoint, this.baseUrl);
+        // Add query parameters
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                if (value !== undefined) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        return url.toString();
+    }
+    /**
+     * Refreshes the client configuration from ConfigManager.
+     * Useful when the configuration may have changed after initialization.
+     */
+    refreshConfig() {
+        const newBaseUrl = this.configManager.getRemoteUrl();
+        const newToken = this.configManager.getGithubToken();
+        if (newBaseUrl !== undefined) {
+            this.baseUrl = newBaseUrl;
+        }
+        if (newToken !== undefined) {
+            this.token = newToken;
+        }
+    }
+}
+/**
+ * Creates and initializes an ApiClient instance.
+ *
+ * This convenience function creates a ConfigManager, initializes it,
+ * and returns a configured ApiClient.
+ *
+ * @param options - Optional configuration overrides.
+ * @returns A promise resolving to an initialized ApiClient.
+ *
+ * @example
+ * ```typescript
+ * const client = await createApiClient();
+ * const response = await client.get<{ status: string }>('/api/status');
+ * console.log(response.data.status);
+ * ```
+ */
+export async function createApiClient(options = {}) {
+    const configManager = await createConfigManager();
+    return new ApiClient(configManager, options);
+}
+/**
+ * Creates an ApiClient using an existing ConfigManager instance.
+ *
+ * Use this when you already have a ConfigManager initialized and want
+ * to avoid creating a duplicate instance.
+ *
+ * @param configManager - An existing ConfigManager instance.
+ * @param options - Optional configuration overrides.
+ * @returns An ApiClient instance.
+ */
+export function createApiClientWithConfig(configManager, options = {}) {
+    return new ApiClient(configManager, options);
+}

package/dist/api/errors.js

@@ -0,0 +1,145 @@
+/**
+ * API Error Classes
+ *
+ * Custom error classes for API client error handling.
+ */
+/**
+ * Base error class for API-related errors.
+ */
+export class ApiError extends Error {
+    code;
+    status;
+    response;
+    constructor(message, code, status, response) {
+        super(message);
+        this.name = "ApiError";
+        this.code = code;
+        this.status = status;
+        this.response = response;
+    }
+}
+/**
+ * Error thrown when authentication fails (401 Unauthorized).
+ */
+export class UnauthorizedError extends ApiError {
+    constructor(message = "Authentication required. Please check your GitHub token.", response) {
+        super(message, "UNAUTHORIZED", 401, response);
+        this.name = "UnauthorizedError";
+    }
+}
+/**
+ * Error thrown when access is forbidden (403 Forbidden).
+ */
+export class ForbiddenError extends ApiError {
+    constructor(message = "Access denied. You do not have permission to perform this action.", response) {
+        super(message, "FORBIDDEN", 403, response);
+        this.name = "ForbiddenError";
+    }
+}
+/**
+ * Error thrown when a resource is not found (404 Not Found).
+ */
+export class NotFoundError extends ApiError {
+    constructor(message = "The requested resource was not found.", response) {
+        super(message, "NOT_FOUND", 404, response);
+        this.name = "NotFoundError";
+    }
+}
+/**
+ * Error thrown when the request is invalid (400 Bad Request).
+ */
+export class BadRequestError extends ApiError {
+    constructor(message = "Invalid request.", response) {
+        super(message, "BAD_REQUEST", 400, response);
+        this.name = "BadRequestError";
+    }
+}
+/**
+ * Error thrown when the server encounters an error (500+ Internal Server Error).
+ */
+export class InternalServerError extends ApiError {
+    constructor(message = "The server encountered an error.", status = 500, response) {
+        super(message, "INTERNAL_ERROR", status, response);
+        this.name = "InternalServerError";
+    }
+}
+/**
+ * Error thrown when a network error occurs (connection refused, DNS failure, etc).
+ */
+export class NetworkError extends ApiError {
+    constructor(message = "Network error. Please check your connection.", originalError) {
+        super(message, "NETWORK_ERROR", 0);
+        this.name = "NetworkError";
+        if (originalError) {
+            this.cause = originalError;
+        }
+    }
+}
+/**
+ * Error thrown when a request times out.
+ */
+export class TimeoutError extends ApiError {
+    constructor(message = "Request timed out.", timeoutMs) {
+        const fullMessage = timeoutMs
+            ? `${message} (timeout: ${timeoutMs}ms)`
+            : message;
+        super(fullMessage, "TIMEOUT", 0);
+        this.name = "TimeoutError";
+    }
+}
+/**
+ * Creates an appropriate ApiError subclass based on the HTTP status code.
+ *
+ * @param status - The HTTP status code.
+ * @param response - The error response body.
+ * @returns An ApiError subclass instance.
+ */
+export function createApiError(status, response) {
+    const message = response?.error ?? getDefaultErrorMessage(status);
+    switch (status) {
+        case 400:
+            return new BadRequestError(message, response);
+        case 401:
+            return new UnauthorizedError(message, response);
+        case 403:
+            return new ForbiddenError(message, response);
+        case 404:
+            return new NotFoundError(message, response);
+        default:
+            if (status >= 500) {
+                return new InternalServerError(message, status, response);
+            }
+            return new ApiError(message, "UNKNOWN", status, response);
+    }
+}
+/**
+ * Gets a default error message for a given HTTP status code.
+ *
+ * @param status - The HTTP status code.
+ * @returns A default error message.
+ */
+function getDefaultErrorMessage(status) {
+    switch (status) {
+        case 400:
+            return "Invalid request.";
+        case 401:
+            return "Authentication required. Please check your GitHub token.";
+        case 403:
+            return "Access denied. You do not have permission to perform this action.";
+        case 404:
+            return "The requested resource was not found.";
+        case 500:
+            return "The server encountered an error.";
+        case 502:
+            return "Bad gateway. The server is temporarily unavailable.";
+        case 503:
+            return "Service unavailable. Please try again later.";
+        case 504:
+            return "Gateway timeout. The server took too long to respond.";
+        default:
+            if (status >= 500) {
+                return "The server encountered an error.";
+            }
+            return `Request failed with status ${status}.`;
+    }
+}