devops-whc 1.0.1

package/dist/handlers/whc-prepare.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeWhcPrepare = executeWhcPrepare;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const workspace_state_1 = require("../state/workspace-state");
+async function executeWhcPrepare(_config, request) {
+    const startedAt = Date.now();
+    const rootDir = request.payload.workspace_root ?? process.cwd();
+    const relativeStateRoot = (process.env.WHC_STATE_ROOT ?? workspace_state_1.DEFAULT_STATE_ROOT).trim() || workspace_state_1.DEFAULT_STATE_ROOT;
+    const stateRootAbs = (0, workspace_state_1.resolveStateRoot)(rootDir);
+    const pipelineStatusFile = (0, workspace_state_1.getPipelineStatusFile)(rootDir);
+    const trackedPaths = [
+        relativeStateRoot,
+        `${relativeStateRoot}/state`,
+        `${relativeStateRoot}/state/releases`,
+        `${relativeStateRoot}/state/reports`,
+        `${relativeStateRoot}/logs`,
+        `${relativeStateRoot}/env`,
+    ];
+    const existingBefore = new Set(trackedPaths.filter((relativePath) => (0, node_fs_1.existsSync)((0, node_path_1.join)(rootDir, ...relativePath.split("/").filter(Boolean)))));
+    const hadStatusBefore = (0, node_fs_1.existsSync)(pipelineStatusFile);
+    if (request.dry_run) {
+        const checks = buildChecks();
+        const manualActions = checks.filter((item) => item.status === "fail").map((item) => item.details);
+        return {
+            ok: true,
+            action_id: (0, node_crypto_1.randomUUID)(),
+            tool: "whc_prepare",
+            data: {
+                state_root: relativeStateRoot,
+                created_paths: trackedPaths.filter((item) => !existingBefore.has(item)),
+                gitignore_updated: false,
+                already_initialized: hadStatusBefore,
+                ready: manualActions.length === 0,
+                manual_actions: manualActions,
+                checks,
+                pipeline_status_file: pipelineStatusFile,
+                next_step: "Set dry_run=false to materialize state files and continue to whc_deploy.",
+            },
+            error: null,
+            meta: {
+                latency_ms: Date.now() - startedAt,
+                safety_level: "B",
+                delivery_mechanism: "file_transfer",
+            },
+        };
+    }
+    (0, workspace_state_1.ensureWorkspaceState)(rootDir);
+    const gitignoreUpdated = request.payload.ensure_gitignore_rule !== false
+        ? ensureGitignoreRule(rootDir, ".mcp/")
+        : false;
+    if (!(0, node_fs_1.existsSync)(pipelineStatusFile) || request.payload.force_reinitialize) {
+        const payload = {
+            started: false,
+            completed: false,
+            status: "idle",
+            next_step: "Run whc_deploy after whc_prepare completes.",
+        };
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(stateRootAbs, "state"), { recursive: true });
+        (0, node_fs_1.writeFileSync)(pipelineStatusFile, JSON.stringify(payload, null, 2) + "\n", "utf8");
+    }
+    const checks = buildChecks();
+    const manualActions = checks.filter((item) => item.status === "fail").map((item) => item.details);
+    const createdPaths = trackedPaths.filter((item) => !existingBefore.has(item));
+    return {
+        ok: true,
+        action_id: (0, node_crypto_1.randomUUID)(),
+        tool: "whc_prepare",
+        data: {
+            state_root: relativeStateRoot,
+            created_paths: createdPaths,
+            gitignore_updated: gitignoreUpdated,
+            already_initialized: hadStatusBefore,
+            ready: manualActions.length === 0,
+            manual_actions: manualActions,
+            checks,
+            pipeline_status_file: pipelineStatusFile,
+            next_step: manualActions.length > 0
+                ? "Complete manual_actions before running whc_deploy."
+                : "Run whc_deploy (dry_run first) then whc_verify.",
+        },
+        error: null,
+        meta: {
+            latency_ms: Date.now() - startedAt,
+            safety_level: "B",
+            delivery_mechanism: "file_transfer",
+        },
+    };
+}
+function buildChecks() {
+    const requiredEnv = [
+        "WHC_API_TOKEN",
+        "WHC_USER",
+        "WHC_HOST",
+        "WHC_PROD_SSH_HOST",
+        "WHC_PROD_SSH_USERNAME",
+        "WHC_PROD_SSH_PRIVATE_KEY_PATH",
+    ];
+    return requiredEnv.map((key) => {
+        const value = (process.env[key] ?? "").trim();
+        if (value.length > 0) {
+            return { name: key, status: "pass", details: `${key} is configured.` };
+        }
+        return {
+            name: key,
+            status: "fail",
+            details: `Set ${key} in your .env before deploy.`,
+        };
+    });
+}
+function ensureGitignoreRule(rootDir, rule) {
+    const gitignorePath = (0, node_path_1.join)(rootDir, ".gitignore");
+    if (!(0, node_fs_1.existsSync)(gitignorePath)) {
+        (0, node_fs_1.writeFileSync)(gitignorePath, `${rule}\n`, "utf8");
+        return true;
+    }
+    const content = (0, node_fs_1.readFileSync)(gitignorePath, "utf8");
+    const hasRule = content.split(/\r?\n/).some((line) => line.trim() === rule);
+    if (hasRule) {
+        return false;
+    }
+    const next = content.endsWith("\n") ? `${content}${rule}\n` : `${content}\n${rule}\n`;
+    (0, node_fs_1.writeFileSync)(gitignorePath, next, "utf8");
+    return true;
+}

package/dist/handlers/whc-rollback.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeWhcRollback = executeWhcRollback;
+const node_crypto_1 = require("node:crypto");
+const whc_uapi_client_1 = require("../clients/whc-uapi-client");
+const ssh_client_1 = require("../clients/ssh-client");
+const workspace_state_1 = require("../state/workspace-state");
+async function executeWhcRollback(config, request, deps = {}) {
+    const startedAt = Date.now();
+    const actionIdFactory = deps.actionIdFactory ?? node_crypto_1.randomUUID;
+    const uapiClient = deps.uapiClient ?? new whc_uapi_client_1.WhcUapiClient(config);
+    const sshClient = deps.sshClient ?? new ssh_client_1.WhcSshClient(config);
+    const chain = resolveVerifyChain(request);
+    if (!chain.accepted) {
+        return buildError(actionIdFactory(), startedAt, "BUSINESS_POLICY_BLOCKED", "Rollback requires a PASS verify-chain from whc_verify. Provide verify_release_id/verify_report_path with final_status=PASS.");
+    }
+    const actions = [];
+    const warnings = [];
+    if (request.dry_run) {
+        if (request.payload.rollback_mode === "git_branch") {
+            const repositoryRoot = request.payload.repository_root ?? config.paths.prod;
+            actions.push(`Would trigger UAPI deployment on ${repositoryRoot} with branch ${request.payload.rollback_branch}.`);
+        }
+        if (request.payload.rollback_mode === "db_backup") {
+            actions.push(`Would import DB backup reference ${request.payload.backup_reference} on ${request.payload.target_environment}.`);
+            warnings.push("DB restore can overwrite runtime data and is irreversible without additional backups.");
+        }
+        if (request.payload.rollback_mode === "managed_sync_reverse") {
+            actions.push(`Would perform managed reverse sync direction ${request.payload.direction}.`);
+            warnings.push("Managed reverse sync can overwrite files/data on destination environment.");
+        }
+        return {
+            ok: true,
+            action_id: actionIdFactory(),
+            tool: "whc_rollback",
+            data: {
+                rollback_mode: request.payload.rollback_mode,
+                rollback_status: "preview",
+                actions,
+                warnings,
+                verify_required: true,
+                verify_chain: chain,
+                next_step: "Re-run with dry_run=false and confirmed=true to execute rollback.",
+            },
+            error: null,
+            meta: {
+                latency_ms: Date.now() - startedAt,
+                safety_level: "D",
+                delivery_mechanism: "git_deploy",
+            },
+        };
+    }
+    if (request.payload.rollback_mode === "git_branch") {
+        const repositoryRoot = request.payload.repository_root ?? config.paths.prod;
+        const result = await uapiClient.triggerDeployment(repositoryRoot, request.payload.rollback_branch);
+        if (!result.ok) {
+            return buildError(actionIdFactory(), startedAt, "TEMPORARY_UPSTREAM_ERROR", `Rollback deployment failed: ${result.message}`);
+        }
+        actions.push(`Triggered rollback deployment on ${repositoryRoot} with branch ${request.payload.rollback_branch}.`);
+    }
+    if (request.payload.rollback_mode === "db_backup") {
+        const target = request.payload.target_environment === "staging" ? config.sshTargets.staging : config.sshTargets.prod;
+        if (!target || !target.privateKeyPath) {
+            return buildError(actionIdFactory(), startedAt, "BUSINESS_POLICY_BLOCKED", "DB rollback requires key-based SSH target configuration.");
+        }
+        const dumpPath = request.payload.backup_reference;
+        const wpPath = request.payload.target_environment === "staging" ? config.paths.staging ?? config.paths.prod : config.paths.prod;
+        const cmd = `cd '${wpPath.replace(/'/g, `"'"`)}' && wp db import '${dumpPath.replace(/'/g, `"'"`)}'`;
+        const sshResult = await sshClient.execWithKey({
+            host: target.host,
+            port: target.port,
+            username: target.username,
+            privateKeyPath: target.privateKeyPath,
+        }, cmd);
+        if (!sshResult.ok) {
+            return buildError(actionIdFactory(), startedAt, "TEMPORARY_UPSTREAM_ERROR", `DB rollback failed: ${sshResult.message}`);
+        }
+        actions.push(`Imported DB backup ${dumpPath} on ${request.payload.target_environment}.`);
+        warnings.push("DB rollback executed. Run whc_verify immediately.");
+    }
+    if (request.payload.rollback_mode === "managed_sync_reverse") {
+        warnings.push("managed_sync_reverse execution is not automated yet; manual WHC action required.");
+        actions.push(`Manual action required: execute reverse sync ${request.payload.direction} from WHC panel.`);
+    }
+    return {
+        ok: true,
+        action_id: actionIdFactory(),
+        tool: "whc_rollback",
+        data: {
+            rollback_mode: request.payload.rollback_mode,
+            rollback_status: "executed",
+            actions,
+            warnings,
+            verify_required: true,
+            verify_chain: chain,
+            next_step: "Run whc_verify to confirm rollback integrity.",
+        },
+        error: null,
+        meta: {
+            latency_ms: Date.now() - startedAt,
+            safety_level: "D",
+            delivery_mechanism: request.payload.rollback_mode === "git_branch" ? "git_deploy" : "ssh_exec",
+        },
+    };
+}
+function resolveVerifyChain(request) {
+    const reportPath = request.payload.verify_report_path ?? (0, workspace_state_1.findLatestVerifyReportFile)(process.cwd());
+    if (!reportPath) {
+        return { source: "missing", final_status: "missing", accepted: false };
+    }
+    const report = (0, workspace_state_1.readJsonFile)(reportPath);
+    if (!report) {
+        return { source: reportPath, final_status: "invalid", accepted: false };
+    }
+    if (request.payload.verify_release_id && report.release_id !== request.payload.verify_release_id) {
+        return { source: reportPath, final_status: String(report.final_status ?? "unknown"), accepted: false };
+    }
+    const finalStatus = String(report.final_status ?? "unknown");
+    return {
+        source: reportPath,
+        final_status: finalStatus,
+        accepted: finalStatus === "PASS",
+    };
+}
+function buildError(actionId, startedAt, code, message) {
+    return {
+        ok: false,
+        action_id: actionId,
+        tool: "whc_rollback",
+        data: null,
+        error: {
+            code,
+            message,
+            retryable: code === "TEMPORARY_UPSTREAM_ERROR",
+        },
+        meta: {
+            latency_ms: Date.now() - startedAt,
+            safety_level: "D",
+        },
+    };
+}

package/dist/handlers/whc-setup-remote.js

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeWhcSetupRemote = executeWhcSetupRemote;
+const node_crypto_1 = require("node:crypto");
+const whc_uapi_client_1 = require("../clients/whc-uapi-client");
+async function executeWhcSetupRemote(config, request, deps = {}) {
+    const startedAt = Date.now();
+    const actionIdFactory = deps.actionIdFactory ?? node_crypto_1.randomUUID;
+    const uapiClient = deps.uapiClient ?? new whc_uapi_client_1.WhcUapiClient(config);
+    const { deploy_target_path, clone_url, source_profile, release_intent, pipeline_id } = request.payload;
+    const pathOwner = extractHomeOwner(deploy_target_path);
+    if (pathOwner && pathOwner !== config.user) {
+        const isStaging = request.payload.target_environment === "staging";
+        const lines = [
+            `Path owner mismatch: deploy_target_path belongs to '${pathOwner}' but WHC_USER is '${config.user}'.`,
+        ];
+        if (isStaging) {
+            lines.push("WHC managed staging uses a separate cPanel account; git repo setup via this user's UAPI cannot target it.", "Use managed_clone_sync mode to sync staging from live, or configure dedicated staging credentials.");
+        }
+        else {
+            const suggestedPayload = buildSuggestedSetupRemotePayload(request, config.user);
+            lines.push(`Use a repository path under /home/${config.user}/... or switch credentials/workflow mode.`, "Copy-ready payload using current WHC_USER:", JSON.stringify(suggestedPayload, null, 2));
+        }
+        return {
+            ok: false,
+            action_id: actionIdFactory(),
+            tool: "whc_setup_remote",
+            data: null,
+            error: {
+                code: "BUSINESS_POLICY_BLOCKED",
+                message: lines.join("\n"),
+                retryable: false,
+            },
+            meta: {
+                latency_ms: Date.now() - startedAt,
+                safety_level: "C",
+                workflow_mode: config.workflowMode,
+                pipeline_id,
+                release_intent,
+                source_profile,
+                delivery_mechanism: "git_deploy",
+            },
+        };
+    }
+    // Dry run: return preview without making changes
+    if (request.dry_run) {
+        const sshRemoteHint = buildSshRemoteHint(config, deploy_target_path);
+        return {
+            ok: true,
+            action_id: actionIdFactory(),
+            tool: "whc_setup_remote",
+            data: {
+                repository_root: deploy_target_path,
+                ssh_remote_hint: sshRemoteHint,
+                was_existing: false,
+                baseline_kind: "unknown",
+                migration_guidance: "dry_run: no changes made. Run without dry_run to create repository.",
+                pipeline_status: "pass_partial",
+                phase_coverage: buildSetupRemotePhaseCoverage(true),
+                process_tracking: {
+                    started: true,
+                    completed: true,
+                    stage: "setup_remote",
+                    status: "needs_manual_input",
+                    next_step: "Run whc_setup_remote without dry_run to create repository, then push local source to the returned SSH remote.",
+                    manual_actions: [
+                        "Ensure cPanel API token is available in WHC_API_TOKEN.",
+                        "Ensure SSH key is authorized on target cPanel account.",
+                        "Run local git remote add/set-url and git push to the ssh_remote_hint.",
+                    ],
+                },
+                warnings: [],
+            },
+            error: null,
+            meta: {
+                latency_ms: Date.now() - startedAt,
+                safety_level: "C",
+                workflow_mode: config.workflowMode,
+                pipeline_id,
+                release_intent,
+                source_profile,
+                delivery_mechanism: "git_deploy",
+            },
+        };
+    }
+    // Check for existing repository at target path
+    let listResult;
+    try {
+        listResult = await uapiClient.listRepositories();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Failed to list repositories";
+        return buildUapiErrorResponse(actionIdFactory(), startedAt, request, "AUTH_ERROR", message);
+    }
+    if (!listResult.ok) {
+        return buildUapiErrorResponse(actionIdFactory(), startedAt, request, "TEMPORARY_UPSTREAM_ERROR", listResult.message);
+    }
+    const existing = listResult.repositories.find((r) => r.repository_root === deploy_target_path);
+    if (existing) {
+        const sshRemoteHint = buildSshRemoteHint(config, deploy_target_path);
+        const baseline = inferBaselineKind(source_profile.source_kind);
+        return {
+            ok: true,
+            action_id: actionIdFactory(),
+            tool: "whc_setup_remote",
+            data: {
+                repository_root: deploy_target_path,
+                ssh_remote_hint: sshRemoteHint,
+                was_existing: true,
+                baseline_kind: baseline,
+                migration_guidance: buildMigrationGuidance(baseline, true),
+                pipeline_status: "pass_partial",
+                phase_coverage: buildSetupRemotePhaseCoverage(false),
+                process_tracking: {
+                    started: true,
+                    completed: true,
+                    stage: "setup_remote",
+                    status: "needs_manual_input",
+                    next_step: "Push/update local source to this existing repository root, then run whc_deploy for the target environment.",
+                    manual_actions: [
+                        "Verify local git remote points to ssh_remote_hint.",
+                        "Push target branch from local workspace.",
+                    ],
+                },
+                warnings: [],
+            },
+            error: null,
+            meta: {
+                latency_ms: Date.now() - startedAt,
+                safety_level: "C",
+                workflow_mode: config.workflowMode,
+                pipeline_id,
+                release_intent,
+                source_profile,
+                delivery_mechanism: "git_deploy",
+            },
+        };
+    }
+    // Create repository
+    const createResult = await uapiClient.createRepository(deploy_target_path, clone_url);
+    if (!createResult.ok) {
+        return buildUapiErrorResponse(actionIdFactory(), startedAt, request, "TEMPORARY_UPSTREAM_ERROR", createResult.message);
+    }
+    const sshRemoteHint = buildSshRemoteHint(config, deploy_target_path);
+    const baseline = inferBaselineKind(source_profile.source_kind);
+    const warnings = buildWarnings(source_profile.source_kind, release_intent);
+    return {
+        ok: true,
+        action_id: actionIdFactory(),
+        tool: "whc_setup_remote",
+        data: {
+            repository_root: createResult.repository_root ?? deploy_target_path,
+            ssh_remote_hint: sshRemoteHint,
+            was_existing: false,
+            baseline_kind: baseline,
+            migration_guidance: buildMigrationGuidance(baseline, false),
+            pipeline_status: "pass_partial",
+            phase_coverage: buildSetupRemotePhaseCoverage(false),
+            process_tracking: {
+                started: true,
+                completed: true,
+                stage: "setup_remote",
+                status: "needs_manual_input",
+                next_step: "Set local git remote to ssh_remote_hint, push source branch, then execute whc_deploy.",
+                manual_actions: [
+                    "Run: git remote add whc <ssh_remote_hint> (or git remote set-url whc <ssh_remote_hint>).",
+                    "Run: git push whc <branch>.",
+                    "Run whc_deploy with matching repository_root and branch.",
+                ],
+            },
+            warnings,
+        },
+        error: null,
+        meta: {
+            latency_ms: Date.now() - startedAt,
+            safety_level: "C",
+            workflow_mode: config.workflowMode,
+            pipeline_id,
+            release_intent,
+            source_profile,
+            delivery_mechanism: "git_deploy",
+        },
+    };
+}
+function buildSshRemoteHint(config, deployTargetPath) {
+    const { username, host } = config.sshTargets.prod;
+    return `${username}@${host}:${deployTargetPath}`;
+}
+function inferBaselineKind(sourceKind) {
+    if (sourceKind === "full_site")
+        return "custom_app";
+    if (sourceKind === "partial_content" || sourceKind === "package_only")
+        return "custom_app";
+    return "unknown";
+}
+function buildMigrationGuidance(baseline, wasExisting) {
+    if (wasExisting) {
+        return "Repository already exists at target path. Verify remote URL in your local repo with `git remote -v`.";
+    }
+    if (baseline === "unknown") {
+        return "Repository created. Inspect target path baseline before first deploy: confirm whether default WP or custom app is present, then reconcile runtime state.";
+    }
+    return undefined;
+}
+function buildWarnings(sourceKind, releaseIntent) {
+    const warnings = [];
+    if (releaseIntent === "migrate") {
+        warnings.push("Release intent is migrate: confirm uploads and content dependencies before promoting to live.");
+    }
+    if (sourceKind === "full_site" && releaseIntent === "deploy") {
+        warnings.push("Full-site source: confirm deploy target path matches the intended webroot, not a subdirectory.");
+    }
+    return warnings;
+}
+function buildSetupRemotePhaseCoverage(dryRun) {
+    return {
+        code_state: "excluded",
+        runtime_state: "excluded",
+        data_state: "excluded",
+        deployment_state: dryRun ? "excluded" : "included",
+        notes: [
+            "whc_setup_remote prepares Git repository wiring only; it does not sync code or bootstrap WordPress runtime/data.",
+            "Manual local git push is required after setup to move source code.",
+            dryRun ? "dry_run preview only; repository not created yet." : "Repository setup completed; continue with git push and deploy.",
+        ],
+    };
+}
+function extractHomeOwner(pathValue) {
+    const match = pathValue.match(/^\/home\/([^\/]+)\//);
+    return match?.[1];
+}
+function buildSuggestedSetupRemotePayload(request, currentUser) {
+    return {
+        request_id: request.request_id,
+        actor: request.actor,
+        dry_run: request.dry_run,
+        confirmed: request.confirmed,
+        idempotency_key: request.idempotency_key,
+        payload: {
+            ...request.payload,
+            deploy_target_path: `/home/${currentUser}/public_html`,
+        },
+    };
+}
+function buildUapiErrorResponse(actionId, startedAt, request, code, message) {
+    return {
+        ok: false,
+        action_id: actionId,
+        tool: "whc_setup_remote",
+        data: null,
+        error: { code, message, retryable: code === "TEMPORARY_UPSTREAM_ERROR" },
+        meta: {
+            latency_ms: Date.now() - startedAt,
+            safety_level: "C",
+            workflow_mode: undefined,
+            pipeline_id: request.payload.pipeline_id,
+            release_intent: request.payload.release_intent,
+            source_profile: request.payload.source_profile,
+            delivery_mechanism: "git_deploy",
+        },
+    };
+}

package/dist/handlers/whc-ssh-exec.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeWhcSshExec = executeWhcSshExec;
+const node_crypto_1 = require("node:crypto");
+const whc_ssh_exec_1 = require("../schemas/whc-ssh-exec");
+const ssh_client_1 = require("../clients/ssh-client");
+async function executeWhcSshExec(config, request, deps = {}) {
+    const startedAt = Date.now();
+    const actionIdFactory = deps.actionIdFactory ?? node_crypto_1.randomUUID;
+    const sshClient = deps.sshClient ?? new ssh_client_1.WhcSshClient(config);
+    const { target_environment, raw_command, working_dir } = request.payload;
+    // Check allowlist/denylist before any SSH attempt
+    const allowed = (0, whc_ssh_exec_1.isCommandAllowed)(raw_command);
+    if (!allowed.allowed) {
+        return {
+            ok: false,
+            action_id: actionIdFactory(),
+            tool: "whc_ssh_exec",
+            data: null,
+            error: {
+                code: "BUSINESS_POLICY_BLOCKED",
+                message: allowed.reason ?? "Command blocked by policy",
+                retryable: false,
+            },
+            meta: { latency_ms: Date.now() - startedAt, safety_level: "C" },
+        };
+    }
+    // Dry run: return preview without executing
+    if (request.dry_run) {
+        return {
+            ok: true,
+            action_id: actionIdFactory(),
+            tool: "whc_ssh_exec",
+            data: {
+                target_environment,
+                command: raw_command,
+                stdout: "",
+                stderr: "",
+                exit_ok: true,
+            },
+            error: null,
+            meta: {
+                latency_ms: Date.now() - startedAt,
+                safety_level: "C",
+                delivery_mechanism: "ssh_exec",
+            },
+        };
+    }
+    const finalCommand = working_dir ? `cd ${working_dir} && ${raw_command}` : raw_command;
+    let execResult;
+    try {
+        if (target_environment === "staging") {
+            const stagingTarget = config.sshTargets.staging;
+            if (!stagingTarget) {
+                return {
+                    ok: false,
+                    action_id: actionIdFactory(),
+                    tool: "whc_ssh_exec",
+                    data: null,
+                    error: {
+                        code: "BUSINESS_POLICY_BLOCKED",
+                        message: "Staging SSH target is not configured.",
+                        retryable: false,
+                    },
+                    meta: { latency_ms: Date.now() - startedAt, safety_level: "C" },
+                };
+            }
+            if (!stagingTarget.privateKeyPath) {
+                if (!stagingTarget.password) {
+                    return {
+                        ok: false,
+                        action_id: actionIdFactory(),
+                        tool: "whc_ssh_exec",
+                        data: null,
+                        error: {
+                            code: "BUSINESS_POLICY_BLOCKED",
+                            message: "whc_ssh_exec requires staging SSH credentials. Configure either WHC_STAGING_SSH_PRIVATE_KEY_PATH or WHC_STAGING_SSH_PASSWORD.",
+                            retryable: false,
+                        },
+                        meta: { latency_ms: Date.now() - startedAt, safety_level: "C" },
+                    };
+                }
+                execResult = await sshClient.execWithPassword({
+                    host: stagingTarget.host,
+                    port: stagingTarget.port,
+                    username: stagingTarget.username,
+                    password: stagingTarget.password,
+                }, finalCommand);
+            }
+            else {
+                execResult = await sshClient.execWithKey({
+                    host: stagingTarget.host,
+                    port: stagingTarget.port,
+                    username: stagingTarget.username,
+                    privateKeyPath: stagingTarget.privateKeyPath,
+                }, finalCommand);
+            }
+        }
+        else {
+            execResult = await sshClient.execWithKey(config.sshTargets.prod, finalCommand);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "SSH exec failed";
+        return {
+            ok: false,
+            action_id: actionIdFactory(),
+            tool: "whc_ssh_exec",
+            data: null,
+            error: { code: "AUTH_ERROR", message, retryable: false },
+            meta: { latency_ms: Date.now() - startedAt, safety_level: "C" },
+        };
+    }
+    return {
+        ok: execResult.ok,
+        action_id: actionIdFactory(),
+        tool: "whc_ssh_exec",
+        data: {
+            target_environment,
+            command: raw_command,
+            stdout: execResult.stdout,
+            stderr: execResult.stderr,
+            exit_ok: execResult.ok,
+        },
+        error: execResult.ok
+            ? null
+            : {
+                code: "UNKNOWN_UPSTREAM_ERROR",
+                message: execResult.message || "Command exited with non-zero status",
+                retryable: false,
+            },
+        meta: {
+            latency_ms: Date.now() - startedAt,
+            safety_level: "C",
+            delivery_mechanism: "ssh_exec",
+        },
+    };
+}