@mainwp/control 1.0.0

package/dist/utils/audit-logger.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Audit Logger for mainwpcontrol
+ *
+ * Logs all destructive actions with preview, user decision, and execution result.
+ *
+ * Log location: ~/.config/mainwpcontrol/audit.log
+ * Format: Newline-delimited JSON (NDJSON)
+ * Rotation: When file exceeds 10MB, rotates to audit.log.1, audit.log.2, etc.
+ * Retention: Keeps last 5 rotated files
+ *
+ * Sensitive data (passwords, tokens, API keys) is automatically redacted.
+ */
+/**
+ * Audit entry structure
+ */
+export interface AuditEntry {
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Name of the ability executed */
+    abilityName: string;
+    /** Preview information (optional - not available in CLI executeDestructive path) */
+    preview?: {
+        summary: string;
+        affectedCount: number;
+    };
+    /** User's decision */
+    userDecision: 'approved' | 'declined';
+    /** Execution result (only present when approved) */
+    execution?: {
+        success: boolean;
+        error?: string;
+    };
+    /** Input parameters (redacted of sensitive data) */
+    input: Record<string, unknown>;
+}
+/**
+ * Input for logging a destructive action
+ */
+export interface LogDestructiveActionInput {
+    abilityName: string;
+    preview?: {
+        summary: string;
+        affectedCount: number;
+    };
+    userDecision: 'approved' | 'declined';
+    execution?: {
+        success: boolean;
+        error?: string;
+    };
+    input: Record<string, unknown>;
+}
+/**
+ * Get the audit log file path
+ */
+export declare function getAuditLogPath(): string;
+/**
+ * Audit Logger class
+ */
+export declare class AuditLogger {
+    private readonly inputSanitizer;
+    /**
+     * Log a destructive action
+     *
+     * SECURITY: Uses restricted permissions for audit logs.
+     *
+     * @param params - Action details to log
+     */
+    logDestructiveAction(params: LogDestructiveActionInput): Promise<void>;
+    /**
+     * Ensure log file exists with proper permissions
+     *
+     * SECURITY: Creates file with 0o600 (owner read/write only) if it doesn't exist.
+     */
+    private ensureLogFile;
+    /**
+     * Check if the log file should be rotated
+     */
+    private shouldRotate;
+    /**
+     * Rotate log files
+     *
+     * Rotation sequence: audit.log → audit.log.1 → audit.log.2 → ... → audit.log.5
+     * Oldest rotation (audit.log.5) is deleted
+     */
+    private rotateLogFile;
+}
+/**
+ * Get the audit logger singleton
+ */
+export declare function getAuditLogger(): AuditLogger;
+/**
+ * Fire-and-forget wrapper for logDestructiveAction.
+ * Swallows errors to prevent audit logging failures from
+ * interrupting the primary execution flow.
+ */
+export declare function logDestructiveActionSafe(params: LogDestructiveActionInput): Promise<void>;
+//# sourceMappingURL=audit-logger.d.ts.map

package/dist/utils/audit-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-logger.d.ts","sourceRoot":"","sources":["../../src/utils/audit-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAsBH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,OAAO,CAAC,EAAE;QACR,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,sBAAsB;IACtB,YAAY,EAAE,UAAU,GAAG,UAAU,CAAC;IACtC,oDAAoD;IACpD,SAAS,CAAC,EAAE;QACV,OAAO,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE;QACR,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,YAAY,EAAE,UAAU,GAAG,UAAU,CAAC;IACtC,SAAS,CAAC,EAAE;QACV,OAAO,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuB;IAEtD;;;;;;OAMG;IACG,oBAAoB,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyC5E;;;;OAIG;YACW,aAAa;IAU3B;;OAEG;YACW,YAAY;IAU1B;;;;;OAKG;YACW,aAAa;CA2B5B;AAOD;;GAEG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAK5C;AAGD;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/utils/audit-logger.js

@@ -0,0 +1,169 @@
+/**
+ * Audit Logger for mainwpcontrol
+ *
+ * Logs all destructive actions with preview, user decision, and execution result.
+ *
+ * Log location: ~/.config/mainwpcontrol/audit.log
+ * Format: Newline-delimited JSON (NDJSON)
+ * Rotation: When file exceeds 10MB, rotates to audit.log.1, audit.log.2, etc.
+ * Retention: Keeps last 5 rotated files
+ *
+ * Sensitive data (passwords, tokens, API keys) is automatically redacted.
+ */
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { getConfigDir } from '../config/settings.js';
+import { getInputSanitizer } from '../validation/input-sanitizer.js';
+/**
+ * Maximum log file size before rotation (10MB)
+ */
+const MAX_LOG_SIZE = 10 * 1024 * 1024;
+/**
+ * Maximum number of rotated log files to keep
+ */
+const MAX_ROTATIONS = 5;
+/**
+ * Audit log filename
+ */
+const AUDIT_LOG_FILENAME = 'audit.log';
+/**
+ * Get the audit log file path
+ */
+export function getAuditLogPath() {
+    return join(getConfigDir(), AUDIT_LOG_FILENAME);
+}
+/**
+ * Audit Logger class
+ */
+export class AuditLogger {
+    inputSanitizer = getInputSanitizer();
+    /**
+     * Log a destructive action
+     *
+     * SECURITY: Uses restricted permissions for audit logs.
+     *
+     * @param params - Action details to log
+     */
+    async logDestructiveAction(params) {
+        const logPath = getAuditLogPath();
+        // Create directory with restricted permissions (owner only)
+        const dir = getConfigDir();
+        await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+        // Check if rotation is needed
+        if (await this.shouldRotate(logPath)) {
+            await this.rotateLogFile(logPath);
+        }
+        // Redact sensitive data from input
+        const redactedInput = this.inputSanitizer.redactSensitive(params.input);
+        // Build audit entry
+        const entry = {
+            timestamp: new Date().toISOString(),
+            abilityName: params.abilityName,
+            userDecision: params.userDecision,
+            input: redactedInput,
+        };
+        // Add optional fields
+        if (params.preview) {
+            entry.preview = params.preview;
+        }
+        if (params.execution) {
+            entry.execution = params.execution;
+        }
+        // Format as NDJSON line
+        const line = JSON.stringify(entry) + '\n';
+        // Ensure file exists with proper permissions before appending
+        await this.ensureLogFile(logPath);
+        // Append to log file
+        await fs.appendFile(logPath, line, 'utf-8');
+    }
+    /**
+     * Ensure log file exists with proper permissions
+     *
+     * SECURITY: Creates file with 0o600 (owner read/write only) if it doesn't exist.
+     */
+    async ensureLogFile(logPath) {
+        try {
+            await fs.access(logPath);
+        }
+        catch {
+            // File doesn't exist, create with restricted permissions
+            const fd = await fs.open(logPath, 'w', 0o600);
+            await fd.close();
+        }
+    }
+    /**
+     * Check if the log file should be rotated
+     */
+    async shouldRotate(logPath) {
+        try {
+            const stats = await fs.stat(logPath);
+            return stats.size > MAX_LOG_SIZE;
+        }
+        catch {
+            // File doesn't exist yet
+            return false;
+        }
+    }
+    /**
+     * Rotate log files
+     *
+     * Rotation sequence: audit.log → audit.log.1 → audit.log.2 → ... → audit.log.5
+     * Oldest rotation (audit.log.5) is deleted
+     */
+    async rotateLogFile(logPath) {
+        // Delete oldest rotation
+        const oldestPath = `${logPath}.${MAX_ROTATIONS}`;
+        try {
+            await fs.unlink(oldestPath);
+        }
+        catch {
+            // Ignore if doesn't exist
+        }
+        // Rotate existing files (5 → delete, 4 → 5, 3 → 4, 2 → 3, 1 → 2)
+        for (let i = MAX_ROTATIONS - 1; i >= 1; i--) {
+            const from = `${logPath}.${i}`;
+            const to = `${logPath}.${i + 1}`;
+            try {
+                await fs.rename(from, to);
+            }
+            catch {
+                // Ignore if doesn't exist
+            }
+        }
+        // Rotate current log (audit.log → audit.log.1)
+        try {
+            await fs.rename(logPath, `${logPath}.1`);
+        }
+        catch {
+            // Ignore if doesn't exist
+        }
+    }
+}
+/**
+ * Singleton instance
+ */
+let instance = null;
+/**
+ * Get the audit logger singleton
+ */
+export function getAuditLogger() {
+    if (!instance) {
+        instance = new AuditLogger();
+    }
+    return instance;
+}
+/**
+ * Fire-and-forget wrapper for logDestructiveAction.
+ * Swallows errors to prevent audit logging failures from
+ * interrupting the primary execution flow.
+ */
+export async function logDestructiveActionSafe(params) {
+    try {
+        await getAuditLogger().logDestructiveAction(params);
+    }
+    catch (error) {
+        console.error(`CRITICAL: [AuditLogger] Failed to log destructive action: ${error instanceof Error ? error.message : String(error)}. ` +
+            `Audit log path: ${getAuditLogPath()}`);
+    }
+}
+//# sourceMappingURL=audit-logger.js.map

package/dist/utils/audit-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-logger.js","sourceRoot":"","sources":["../../src/utils/audit-logger.ts"],"names":[],"mappings":"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"}

package/dist/utils/colors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared color utilities for mainwpcontrol
+ *
+ * Respects NO_COLOR env var and non-TTY detection.
+ * All terminal coloring should go through these functions.
+ */
+/**
+ * ANSI color codes
+ */
+export declare const colors: {
+    reset: string;
+    bold: string;
+    dim: string;
+    red: string;
+    green: string;
+    yellow: string;
+    blue: string;
+    cyan: string;
+    gray: string;
+};
+/**
+ * Check if we should use colored output
+ */
+export declare function useColors(): boolean;
+/**
+ * Apply color if colors are enabled
+ */
+export declare function color(text: string, ...codes: string[]): string;
+//# sourceMappingURL=colors.d.ts.map

package/dist/utils/colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../../src/utils/colors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;CAUlB,CAAC;AAEF;;GAEG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAK9D"}

package/dist/utils/colors.js

@@ -0,0 +1,36 @@
+/**
+ * Shared color utilities for mainwpcontrol
+ *
+ * Respects NO_COLOR env var and non-TTY detection.
+ * All terminal coloring should go through these functions.
+ */
+/**
+ * ANSI color codes
+ */
+export const colors = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+};
+/**
+ * Check if we should use colored output
+ */
+export function useColors() {
+    return process.stdout.isTTY === true && !('NO_COLOR' in process.env);
+}
+/**
+ * Apply color if colors are enabled
+ */
+export function color(text, ...codes) {
+    if (!useColors()) {
+        return text;
+    }
+    return codes.join('') + text + colors.reset;
+}
+//# sourceMappingURL=colors.js.map

package/dist/utils/colors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.js","sourceRoot":"","sources":["../../src/utils/colors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,KAAK,EAAE,SAAS;IAChB,IAAI,EAAE,SAAS;IACf,GAAG,EAAE,SAAS;IACd,GAAG,EAAE,UAAU;IACf,KAAK,EAAE,UAAU;IACjB,MAAM,EAAE,UAAU;IAClB,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,UAAU;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,SAAS;IACvB,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC;AACvE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,GAAG,KAAe;IACpD,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC;AAC9C,CAAC"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Error classes for mainwpcontrol
+ *
+ * Each error class maps to a specific exit code.
+ */
+import { type ExitCodeValue } from './exit-codes.js';
+/**
+ * Base error class for mainwpcontrol errors
+ */
+export declare abstract class MainWPCTLError extends Error {
+    readonly details?: unknown | undefined;
+    readonly hint?: string | undefined;
+    abstract readonly exitCode: ExitCodeValue;
+    abstract readonly code: string;
+    constructor(message: string, details?: unknown | undefined, hint?: string | undefined);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Input validation error (exit code 1)
+ */
+export declare class InputError extends MainWPCTLError {
+    readonly exitCode: 1;
+    readonly code = "INPUT_ERROR";
+    constructor(message: string, details?: unknown, hint?: string);
+}
+/**
+ * Schema validation error (exit code 1)
+ */
+export declare class SchemaValidationError extends MainWPCTLError {
+    readonly validationErrors: unknown[];
+    readonly exitCode: 1;
+    readonly code = "SCHEMA_VALIDATION_ERROR";
+    constructor(message: string, validationErrors: unknown[], hint?: string);
+}
+/**
+ * Authentication error (exit code 2)
+ */
+export declare class AuthError extends MainWPCTLError {
+    readonly exitCode: 2;
+    readonly code = "AUTH_ERROR";
+    constructor(message: string, details?: unknown, hint?: string);
+}
+/**
+ * Configuration error (exit code 2)
+ */
+export declare class ConfigError extends MainWPCTLError {
+    readonly exitCode: 2;
+    readonly code = "CONFIG_ERROR";
+    constructor(message: string, details?: unknown, hint?: string);
+}
+/**
+ * Network error (exit code 3)
+ */
+export declare class NetworkError extends MainWPCTLError {
+    readonly cause?: Error | undefined;
+    readonly exitCode: 3;
+    readonly code = "NETWORK_ERROR";
+    constructor(message: string, cause?: Error | undefined, hint?: string);
+}
+/**
+ * TLS/SSL error (exit code 3)
+ */
+export declare class TLSError extends MainWPCTLError {
+    readonly exitCode: 3;
+    readonly code = "TLS_ERROR";
+    constructor(message: string, details?: unknown, hint?: string);
+}
+/**
+ * API error (exit code 4)
+ */
+export declare class APIError extends MainWPCTLError {
+    readonly statusCode?: number | undefined;
+    readonly exitCode: 4;
+    readonly code: string;
+    constructor(code: string, message: string, statusCode?: number | undefined, details?: unknown, hint?: string);
+}
+/**
+ * Confirmation required error (exit code 4)
+ */
+export declare class ConfirmationRequiredError extends MainWPCTLError {
+    readonly preview?: unknown | undefined;
+    readonly exitCode: 4;
+    readonly code = "CONFIRMATION_REQUIRED";
+    constructor(message: string, preview?: unknown | undefined, hint?: string);
+}
+/**
+ * Mutual exclusion error (exit code 1)
+ */
+export declare class MutualExclusionError extends MainWPCTLError {
+    readonly exitCode: 1;
+    readonly code = "MUTUAL_EXCLUSION_ERROR";
+    constructor(message?: string, hint?: string);
+}
+/**
+ * Internal error (exit code 5)
+ */
+export declare class InternalError extends MainWPCTLError {
+    readonly cause?: Error | undefined;
+    readonly exitCode: 5;
+    readonly code = "INTERNAL_ERROR";
+    constructor(message: string, cause?: Error | undefined, hint?: string);
+}
+/**
+ * Check if an error is a MainWPCTLError
+ */
+export declare function isMainWPCTLError(error: unknown): error is MainWPCTLError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"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"}

package/dist/utils/errors.js

@@ -0,0 +1,149 @@
+/**
+ * Error classes for mainwpcontrol
+ *
+ * Each error class maps to a specific exit code.
+ */
+import { ExitCode } from './exit-codes.js';
+/**
+ * Base error class for mainwpcontrol errors
+ */
+export class MainWPCTLError extends Error {
+    details;
+    hint;
+    constructor(message, details, hint) {
+        super(message);
+        this.details = details;
+        this.hint = hint;
+        this.name = this.constructor.name;
+        Error.captureStackTrace(this, this.constructor);
+    }
+    toJSON() {
+        const result = {
+            code: this.code,
+            message: this.message,
+            details: this.details,
+        };
+        if (this.hint) {
+            result.hint = this.hint;
+        }
+        return result;
+    }
+}
+/**
+ * Input validation error (exit code 1)
+ */
+export class InputError extends MainWPCTLError {
+    exitCode = ExitCode.INPUT_ERROR;
+    code = 'INPUT_ERROR';
+    constructor(message, details, hint) {
+        super(message, details, hint);
+    }
+}
+/**
+ * Schema validation error (exit code 1)
+ */
+export class SchemaValidationError extends MainWPCTLError {
+    validationErrors;
+    exitCode = ExitCode.INPUT_ERROR;
+    code = 'SCHEMA_VALIDATION_ERROR';
+    constructor(message, validationErrors, hint) {
+        super(message, { validationErrors }, hint);
+        this.validationErrors = validationErrors;
+    }
+}
+/**
+ * Authentication error (exit code 2)
+ */
+export class AuthError extends MainWPCTLError {
+    exitCode = ExitCode.AUTH_ERROR;
+    code = 'AUTH_ERROR';
+    constructor(message, details, hint) {
+        super(message, details, hint);
+    }
+}
+/**
+ * Configuration error (exit code 2)
+ */
+export class ConfigError extends MainWPCTLError {
+    exitCode = ExitCode.AUTH_ERROR;
+    code = 'CONFIG_ERROR';
+    constructor(message, details, hint) {
+        super(message, details, hint);
+    }
+}
+/**
+ * Network error (exit code 3)
+ */
+export class NetworkError extends MainWPCTLError {
+    cause;
+    exitCode = ExitCode.NETWORK_ERROR;
+    code = 'NETWORK_ERROR';
+    constructor(message, cause, hint) {
+        super(message, cause ? { cause: cause.message } : undefined, hint);
+        this.cause = cause;
+    }
+}
+/**
+ * TLS/SSL error (exit code 3)
+ */
+export class TLSError extends MainWPCTLError {
+    exitCode = ExitCode.NETWORK_ERROR;
+    code = 'TLS_ERROR';
+    constructor(message, details, hint) {
+        super(message, details, hint);
+    }
+}
+/**
+ * API error (exit code 4)
+ */
+export class APIError extends MainWPCTLError {
+    statusCode;
+    exitCode = ExitCode.API_ERROR;
+    code;
+    constructor(code, message, statusCode, details, hint) {
+        super(message, details, hint);
+        this.statusCode = statusCode;
+        this.code = code;
+    }
+}
+/**
+ * Confirmation required error (exit code 4)
+ */
+export class ConfirmationRequiredError extends MainWPCTLError {
+    preview;
+    exitCode = ExitCode.API_ERROR;
+    code = 'CONFIRMATION_REQUIRED';
+    constructor(message, preview, hint) {
+        super(message, { preview }, hint);
+        this.preview = preview;
+    }
+}
+/**
+ * Mutual exclusion error (exit code 1)
+ */
+export class MutualExclusionError extends MainWPCTLError {
+    exitCode = ExitCode.INPUT_ERROR;
+    code = 'MUTUAL_EXCLUSION_ERROR';
+    constructor(message = 'dry_run and confirm are mutually exclusive', hint) {
+        super(message, undefined, hint);
+    }
+}
+/**
+ * Internal error (exit code 5)
+ */
+export class InternalError extends MainWPCTLError {
+    cause;
+    exitCode = ExitCode.INTERNAL_ERROR;
+    code = 'INTERNAL_ERROR';
+    constructor(message, cause, hint) {
+        super(message, cause ? { cause: cause.message } : undefined, hint);
+        this.cause = cause;
+    }
+}
+/**
+ * Check if an error is a MainWPCTLError
+ */
+export function isMainWPCTLError(error) {
+    return error instanceof MainWPCTLError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

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

package/dist/utils/exit-codes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Exit codes for mainwpcontrol
+ *
+ * These codes are stable and documented. Do not change without updating docs.
+ */
+export declare const ExitCode: {
+    /** Operation completed successfully */
+    readonly SUCCESS: 0;
+    /** User, schema, or input error */
+    readonly INPUT_ERROR: 1;
+    /** Authentication or configuration error */
+    readonly AUTH_ERROR: 2;
+    /** Network or TLS error */
+    readonly NETWORK_ERROR: 3;
+    /** API or ability execution error */
+    readonly API_ERROR: 4;
+    /** Internal error (stack trace only with --debug) */
+    readonly INTERNAL_ERROR: 5;
+};
+export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];
+//# sourceMappingURL=exit-codes.d.ts.map

package/dist/utils/exit-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.d.ts","sourceRoot":"","sources":["../../src/utils/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,QAAQ;IACnB,uCAAuC;;IAGvC,mCAAmC;;IAGnC,4CAA4C;;IAG5C,2BAA2B;;IAG3B,qCAAqC;;IAGrC,qDAAqD;;CAE7C,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC"}

package/dist/utils/exit-codes.js

@@ -0,0 +1,20 @@
+/**
+ * Exit codes for mainwpcontrol
+ *
+ * These codes are stable and documented. Do not change without updating docs.
+ */
+export const ExitCode = {
+    /** Operation completed successfully */
+    SUCCESS: 0,
+    /** User, schema, or input error */
+    INPUT_ERROR: 1,
+    /** Authentication or configuration error */
+    AUTH_ERROR: 2,
+    /** Network or TLS error */
+    NETWORK_ERROR: 3,
+    /** API or ability execution error */
+    API_ERROR: 4,
+    /** Internal error (stack trace only with --debug) */
+    INTERNAL_ERROR: 5,
+};
+//# sourceMappingURL=exit-codes.js.map

package/dist/utils/exit-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.js","sourceRoot":"","sources":["../../src/utils/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,uCAAuC;IACvC,OAAO,EAAE,CAAC;IAEV,mCAAmC;IACnC,WAAW,EAAE,CAAC;IAEd,4CAA4C;IAC5C,UAAU,EAAE,CAAC;IAEb,2BAA2B;IAC3B,aAAa,EAAE,CAAC;IAEhB,qCAAqC;IACrC,SAAS,EAAE,CAAC;IAEZ,qDAAqD;IACrD,cAAc,EAAE,CAAC;CACT,CAAC"}