devops-whc 1.0.1

package/WHC_MCP_REQUIREMENTS.md

@@ -0,0 +1,112 @@
+# WHC.ca (cPanel) MCP Server Requirements
+
+## 1. Objective
+Build a specialized MCP (Model Context Protocol) Server to automate the management and deployment of web projects hosted on Web Hosting Canada (WHC.ca). The goal is to facilitate a seamless **Local -> Staging -> Production** workflow directly from the terminal/Gemini CLI.
+
+## 2. Core Features
+- **Git Automation:** Remote repository creation and branch-based synchronization.
+- **API Deployment:** Triggering cPanel's native deployment engine via UAPI.
+- **SSH Command Execution:** Remote server management (file manipulation, DB tasks) using WHC's specific port (27).
+- **Status Monitoring:** Real-time health checks, log retrieval, and SSL status.
+
+## 3. Tool Definitions (Current)
+
+| Tool Name | Mode | Safety | Description |
+| :--- | :--- | :--- | :--- |
+| `whc_prepare` | write | B | Initializes hidden state namespace and readiness checks. |
+| `whc_deploy` | write | C/D | Triggers deployment/sync flow with policy gating. |
+| `whc_verify` | read | A | Runs technical post-deploy verification and writes verify report. |
+| `whc_pipeline_status` | read | A | Reads latest pipeline state and artifact pointers. |
+| `whc_rollback` | write | D | Guarded rollback (dry-run + confirm + verify-chain PASS required). |
+| `whc_setup_remote` | write | C | Creates cPanel Git repo and returns SSH remote hints. |
+| `whc_ssh_exec` | write | C | Executes policy-controlled SSH commands. |
+| `whc_get_logs` | read | A | Fetches server logs. |
+| `whc_db_backup` | write | D | Creates remote SQL backup with audit trail. |
+| `whc_check_health` | read | A | Collects disk, SSL, load, and capability signals. |
+
+### 3.4 Rollback Contract (Current)
+`whc_rollback` is implemented as Level D.
+
+Policy requirements:
+1. `dry_run=true` is mandatory for preview phase.
+2. `confirmed=true` is mandatory for execution phase.
+3. Verify-chain must be present and PASS from `whc_verify` report.
+
+Execution modes:
+1. `git_branch` (UAPI deployment trigger with rollback branch)
+2. `db_backup` (SSH `wp db import`)
+3. `managed_sync_reverse` (manual action response with explicit warning)
+
+## 3.1 Deploy Contract (Current)
+`whc_deploy` now reports phase coverage explicitly to prevent false-positive "deploy pass" outcomes.
+
+Response fields in `data`:
+1. `pipeline_status`
+    - `full_pass` | `pass_partial`
+2. `phase_coverage`
+    - `code_state`: `included` | `excluded`
+    - `runtime_state`: `included` | `excluded`
+    - `data_state`: `included` | `excluded`
+    - `deployment_state`: `included` | `excluded`
+    - `notes`: explanatory list for what is in/out of scope
+
+Interpretation:
+1. `pass_partial` is expected when a run covers only transport/sync/deploy mechanics.
+2. `full_pass` must only be used when code/runtime/data/deployment states are all included and validated.
+
+## 3.2 Setup-Remote Contract (Current)
+`whc_setup_remote` is transport preparation, not code deployment.
+
+Response fields in `data`:
+1. `pipeline_status`
+    - expected default: `pass_partial`
+2. `phase_coverage`
+    - deployment state reflects repository wiring only
+3. `process_tracking`
+    - `stage`: `setup_remote`
+    - `status`: `completed` | `needs_manual_input`
+    - `next_step`: actionable follow-up
+    - `manual_actions`: explicit operator/agent to-do list
+
+Operational implication:
+1. A successful `whc_setup_remote` still requires local source push (`git push`) and subsequent `whc_deploy`.
+
+## 3.3 Manual Prerequisites (Must Be Explicit)
+These steps are not auto-solvable by MCP and must be prepared by operator:
+1. WHC API token creation and placement in env.
+2. SSH key provisioning to correct cPanel account.
+3. Credential scope alignment (target path ownership/account).
+
+## 4. Technical Stack
+- **Language:** TypeScript / Node.js.
+- **Framework:** MCP SDK (@modelcontextprotocol/sdk).
+- **Communication:** 
+    - **cPanel UAPI:** Over HTTPS (Port 2083) using API Tokens.
+    - **SSH:** Using `ssh2` or system SSH (Port 27).
+- **Configuration:** Global `.env` for sensitive credentials.
+
+## 5. Implementation Roadmap
+
+### Phase 1: Foundation & Auth
+- [ ] Initialize MCP project.
+- [ ] Implement secure `.env` loading for `WHC_API_TOKEN`, `WHC_USER`, and `WHC_HOST`.
+- [ ] Test connectivity to cPanel API and SSH.
+
+### Phase 2: Deployment & Git
+- [ ] Build `whc_setup_remote`: Automate the "Git Version Control" setup in cPanel.
+- [ ] Build `whc_deploy`: Connect to the `deployment` UAPI endpoint.
+- [ ] Create a standard `.cpanel.yml` template generator.
+
+### Phase 3: Monitoring & Utilities
+- [ ] Implement remote log tailing via SSH.
+- [ ] Implement database backup/restore helpers.
+- [ ] Add health check dashboard.
+
+### Phase 4: Gemini CLI Integration
+- [ ] Register the MCP server in `gemini-config.json`.
+- [ ] Create high-level commands/aliases (e.g., `whc-sync-staging`).
+
+## 6. Security Protocol
+- No API tokens or Private Keys are to be hardcoded.
+- All sensitive data must reside in a local `.env` file excluded from git.
+- API requests must use HTTPS with proper header authentication.

package/dist/audit/audit-logger.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompositeAuditLogger = exports.FileAuditLogger = exports.ConsoleAuditLogger = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+class ConsoleAuditLogger {
+    log(entry) {
+        const safeEntry = toSafeEntry(entry);
+        // Console logging is temporary; production sink can be added later.
+        console.log("[AUDIT]", JSON.stringify(safeEntry));
+    }
+}
+exports.ConsoleAuditLogger = ConsoleAuditLogger;
+class FileAuditLogger {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    log(entry) {
+        const safeEntry = toSafeEntry(entry);
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(this.filePath), { recursive: true });
+        (0, node_fs_1.appendFileSync)(this.filePath, JSON.stringify(safeEntry) + "\n", { encoding: "utf8" });
+    }
+}
+exports.FileAuditLogger = FileAuditLogger;
+class CompositeAuditLogger {
+    sinks;
+    constructor(sinks) {
+        this.sinks = sinks;
+    }
+    log(entry) {
+        for (const sink of this.sinks) {
+            sink.log(entry);
+        }
+    }
+}
+exports.CompositeAuditLogger = CompositeAuditLogger;
+function toSafeEntry(entry) {
+    return {
+        ...entry,
+        details: redactSecrets(entry.details),
+    };
+}
+function redactSecrets(details) {
+    if (!details) {
+        return undefined;
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(details)) {
+        if (/token|secret|password|key/i.test(key)) {
+            result[key] = "[REDACTED]";
+            continue;
+        }
+        result[key] = value;
+    }
+    return result;
+}

package/dist/clients/ssh-client.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WhcSshClient = void 0;
+const node_fs_1 = require("node:fs");
+const ssh2_1 = require("ssh2");
+class WhcSshClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async probe() {
+        return this.probeTarget(this.config.sshTargets.prod);
+    }
+    async probeTarget(target) {
+        const startedAt = Date.now();
+        const privateKey = (0, node_fs_1.readFileSync)(target.privateKeyPath);
+        return new Promise((resolve) => {
+            const client = new ssh2_1.Client();
+            const timeoutId = setTimeout(() => {
+                client.end();
+                resolve({
+                    ok: false,
+                    latencyMs: Date.now() - startedAt,
+                    message: "SSH probe timed out",
+                });
+            }, this.config.sshTimeoutMs);
+            client
+                .on("ready", () => {
+                clearTimeout(timeoutId);
+                client.end();
+                resolve({
+                    ok: true,
+                    latencyMs: Date.now() - startedAt,
+                    message: "SSH connectivity probe succeeded",
+                });
+            })
+                .on("error", (error) => {
+                clearTimeout(timeoutId);
+                client.end();
+                resolve({
+                    ok: false,
+                    latencyMs: Date.now() - startedAt,
+                    message: error.message,
+                });
+            })
+                .connect({
+                host: target.host,
+                port: target.port,
+                username: target.username,
+                privateKey,
+                readyTimeout: this.config.sshTimeoutMs,
+            });
+        });
+    }
+    async execWithKey(target, command) {
+        const startedAt = Date.now();
+        const privateKey = (0, node_fs_1.readFileSync)(target.privateKeyPath);
+        return new Promise((resolve) => {
+            const client = new ssh2_1.Client();
+            const timeoutId = setTimeout(() => {
+                client.end();
+                resolve({
+                    ok: false,
+                    latencyMs: Date.now() - startedAt,
+                    stdout: "",
+                    stderr: "",
+                    message: "SSH command timed out",
+                });
+            }, this.config.sshTimeoutMs);
+            client
+                .on("ready", () => {
+                client.exec(command, (err, stream) => {
+                    if (err) {
+                        clearTimeout(timeoutId);
+                        client.end();
+                        resolve({
+                            ok: false,
+                            latencyMs: Date.now() - startedAt,
+                            stdout: "",
+                            stderr: "",
+                            message: err.message,
+                        });
+                        return;
+                    }
+                    let stdout = "";
+                    let stderr = "";
+                    stream
+                        .on("close", (code) => {
+                        clearTimeout(timeoutId);
+                        client.end();
+                        resolve({
+                            ok: code === 0,
+                            latencyMs: Date.now() - startedAt,
+                            stdout: stdout.trim(),
+                            stderr: stderr.trim(),
+                            message: code === 0 ? "SSH command succeeded" : `SSH command failed with exit code ${code ?? -1}`,
+                        });
+                    })
+                        .on("data", (data) => {
+                        stdout += data.toString("utf8");
+                    });
+                    stream.stderr.on("data", (data) => {
+                        stderr += data.toString("utf8");
+                    });
+                });
+            })
+                .on("error", (error) => {
+                clearTimeout(timeoutId);
+                client.end();
+                resolve({
+                    ok: false,
+                    latencyMs: Date.now() - startedAt,
+                    stdout: "",
+                    stderr: "",
+                    message: error.message,
+                });
+            })
+                .connect({
+                host: target.host,
+                port: target.port,
+                username: target.username,
+                privateKey,
+                readyTimeout: this.config.sshTimeoutMs,
+            });
+        });
+    }
+    async execWithPassword(target, command) {
+        const startedAt = Date.now();
+        return new Promise((resolve) => {
+            const client = new ssh2_1.Client();
+            const timeoutId = setTimeout(() => {
+                client.end();
+                resolve({
+                    ok: false,
+                    latencyMs: Date.now() - startedAt,
+                    stdout: "",
+                    stderr: "",
+                    message: "SSH command timed out",
+                });
+            }, this.config.sshTimeoutMs);
+            client
+                .on("ready", () => {
+                client.exec(command, (err, stream) => {
+                    if (err) {
+                        clearTimeout(timeoutId);
+                        client.end();
+                        resolve({
+                            ok: false,
+                            latencyMs: Date.now() - startedAt,
+                            stdout: "",
+                            stderr: "",
+                            message: err.message,
+                        });
+                        return;
+                    }
+                    let stdout = "";
+                    let stderr = "";
+                    stream
+                        .on("close", (code) => {
+                        clearTimeout(timeoutId);
+                        client.end();
+                        resolve({
+                            ok: code === 0,
+                            latencyMs: Date.now() - startedAt,
+                            stdout: stdout.trim(),
+                            stderr: stderr.trim(),
+                            message: code === 0 ? "SSH command succeeded" : `SSH command failed with exit code ${code ?? -1}`,
+                        });
+                    })
+                        .on("data", (data) => {
+                        stdout += data.toString("utf8");
+                    });
+                    stream.stderr.on("data", (data) => {
+                        stderr += data.toString("utf8");
+                    });
+                });
+            })
+                .on("error", (error) => {
+                clearTimeout(timeoutId);
+                client.end();
+                resolve({
+                    ok: false,
+                    latencyMs: Date.now() - startedAt,
+                    stdout: "",
+                    stderr: "",
+                    message: error.message,
+                });
+            })
+                .connect({
+                host: target.host,
+                port: target.port,
+                username: target.username,
+                password: target.password,
+                readyTimeout: this.config.sshTimeoutMs,
+            });
+        });
+    }
+}
+exports.WhcSshClient = WhcSshClient;

package/dist/clients/whc-uapi-client.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WhcUapiClient = void 0;
+class WhcUapiClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    authHeader() {
+        return `cpanel ${this.config.user}:${this.config.apiToken}`;
+    }
+    async probe() {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.apiTimeoutMs);
+        const startedAt = Date.now();
+        try {
+            const response = await fetch(`${this.config.apiBaseUrl}/execute/VersionControl/list_repositories`, {
+                method: "GET",
+                headers: {
+                    Authorization: this.authHeader(),
+                    Accept: "application/json",
+                },
+                signal: controller.signal,
+            });
+            const latencyMs = Date.now() - startedAt;
+            if (!response.ok) {
+                return {
+                    ok: false,
+                    status: response.status,
+                    latencyMs,
+                    message: `UAPI probe failed with status ${response.status}`,
+                };
+            }
+            return {
+                ok: true,
+                status: response.status,
+                latencyMs,
+                message: "UAPI connectivity probe succeeded",
+            };
+        }
+        catch (error) {
+            const latencyMs = Date.now() - startedAt;
+            const message = error instanceof Error ? error.message : "Unknown UAPI probe error";
+            return {
+                ok: false,
+                latencyMs,
+                message,
+            };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async listRepositories() {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.apiTimeoutMs);
+        const startedAt = Date.now();
+        try {
+            const response = await fetch(`${this.config.apiBaseUrl}/execute/VersionControl/list_repositories`, {
+                method: "GET",
+                headers: { Authorization: this.authHeader(), Accept: "application/json" },
+                signal: controller.signal,
+            });
+            const latencyMs = Date.now() - startedAt;
+            if (!response.ok) {
+                return { ok: false, latencyMs, repositories: [], message: `HTTP ${response.status}` };
+            }
+            const body = (await response.json());
+            if (!body.result || body.result.status !== 1) {
+                const err = (body.result?.errors ?? []).join("; ") || "UAPI list_repositories failed";
+                return { ok: false, latencyMs, repositories: [], message: err };
+            }
+            return {
+                ok: true,
+                latencyMs,
+                repositories: body.result.data ?? [],
+                message: "list_repositories succeeded",
+            };
+        }
+        catch (error) {
+            const latencyMs = Date.now() - startedAt;
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return { ok: false, latencyMs, repositories: [], message };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async createRepository(repositoryRoot, originUrl) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.apiTimeoutMs);
+        const startedAt = Date.now();
+        const params = new URLSearchParams({ repository_root: repositoryRoot, type: "git" });
+        if (originUrl) {
+            params.set("origin_url", originUrl);
+        }
+        try {
+            const response = await fetch(`${this.config.apiBaseUrl}/execute/VersionControl/create`, {
+                method: "POST",
+                headers: {
+                    Authorization: this.authHeader(),
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    Accept: "application/json",
+                },
+                body: params.toString(),
+                signal: controller.signal,
+            });
+            const latencyMs = Date.now() - startedAt;
+            if (!response.ok) {
+                return { ok: false, latencyMs, message: `HTTP ${response.status}` };
+            }
+            const body = (await response.json());
+            if (!body.result || body.result.status !== 1) {
+                const err = (body.result?.errors ?? []).join("; ") || "UAPI create failed";
+                return { ok: false, latencyMs, message: err };
+            }
+            return {
+                ok: true,
+                latencyMs,
+                repository_root: body.result.data?.repository_root ?? repositoryRoot,
+                message: "Repository created successfully",
+            };
+        }
+        catch (error) {
+            const latencyMs = Date.now() - startedAt;
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return { ok: false, latencyMs, message };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async triggerDeployment(repositoryRoot, branch) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.apiTimeoutMs);
+        const startedAt = Date.now();
+        const params = new URLSearchParams({ repository_root: repositoryRoot });
+        if (branch) {
+            params.set("branch", branch);
+        }
+        try {
+            const response = await fetch(`${this.config.apiBaseUrl}/execute/VersionControl/deployment`, {
+                method: "POST",
+                headers: {
+                    Authorization: this.authHeader(),
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    Accept: "application/json",
+                },
+                body: params.toString(),
+                signal: controller.signal,
+            });
+            const latencyMs = Date.now() - startedAt;
+            if (!response.ok) {
+                return { ok: false, latencyMs, message: `HTTP ${response.status}` };
+            }
+            const body = (await response.json());
+            if (!body.result || body.result.status !== 1) {
+                const err = (body.result?.errors ?? []).join("; ") || "UAPI deployment trigger failed";
+                return { ok: false, latencyMs, message: err };
+            }
+            return {
+                ok: true,
+                latencyMs,
+                deployment_id: body.result.data?.deployment_id,
+                message: "Deployment triggered successfully",
+            };
+        }
+        catch (error) {
+            const latencyMs = Date.now() - startedAt;
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return { ok: false, latencyMs, message };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+exports.WhcUapiClient = WhcUapiClient;

package/dist/clients/wpcli-client.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WpCliClient = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+const WPCLI_CHECK_COMMAND = 'if command -v wp >/dev/null 2>&1; then wp --info | head -n 1; else echo __WPCLI_NOT_FOUND__; fi';
+class WpCliClient {
+    config;
+    sshClient;
+    constructor(config, sshClient) {
+        this.config = config;
+        this.sshClient = sshClient;
+    }
+    async probe() {
+        const prod = await this.probeWithKey(this.config.sshTargets.prod, "production");
+        const staging = await this.probeStaging();
+        return { prod, staging };
+    }
+    async probeWithKey(target, envLabel) {
+        const result = await this.sshClient.execWithKey(target, WPCLI_CHECK_COMMAND);
+        if (!result.ok && result.stdout.length === 0) {
+            return {
+                reachable: false,
+                available: false,
+                latencyMs: result.latencyMs,
+                message: `${envLabel} SSH command failed: ${result.message}`,
+            };
+        }
+        if (result.stdout.includes("__WPCLI_NOT_FOUND__")) {
+            return {
+                reachable: true,
+                available: false,
+                latencyMs: result.latencyMs,
+                message: `${envLabel} reachable but WP-CLI is not installed or not in PATH`,
+            };
+        }
+        return {
+            reachable: true,
+            available: true,
+            latencyMs: result.latencyMs,
+            message: `${envLabel} WP-CLI available`,
+            versionLine: result.stdout.split("\n")[0],
+        };
+    }
+    async probeStaging() {
+        const stagingTarget = this.config.sshTargets.staging;
+        if (!stagingTarget) {
+            return {
+                reachable: false,
+                available: false,
+                latencyMs: 0,
+                message: "staging SSH target is not configured",
+            };
+        }
+        if (stagingTarget.privateKeyPath) {
+            return this.probeWithKey({
+                host: stagingTarget.host,
+                port: stagingTarget.port,
+                username: stagingTarget.username,
+                privateKeyPath: stagingTarget.privateKeyPath,
+            }, "staging");
+        }
+        if (!stagingTarget.password) {
+            return {
+                reachable: false,
+                available: false,
+                latencyMs: 0,
+                message: "staging key not set and staging password not configured",
+            };
+        }
+        const startedAt = Date.now();
+        const args = [
+            "-ssh",
+            "-batch",
+            "-P",
+            String(stagingTarget.port),
+            "-l",
+            stagingTarget.username,
+            "-pw",
+            stagingTarget.password,
+        ];
+        if (stagingTarget.hostKey) {
+            args.push("-hostkey", stagingTarget.hostKey);
+        }
+        args.push(stagingTarget.host, WPCLI_CHECK_COMMAND);
+        try {
+            const { stdout } = await execFileAsync("plink", args, {
+                timeout: this.config.sshTimeoutMs,
+                windowsHide: true,
+            });
+            const latencyMs = Date.now() - startedAt;
+            const output = stdout.trim();
+            if (output.includes("__WPCLI_NOT_FOUND__")) {
+                return {
+                    reachable: true,
+                    available: false,
+                    latencyMs,
+                    message: "staging reachable but WP-CLI is not installed or not in PATH",
+                };
+            }
+            return {
+                reachable: true,
+                available: output.length > 0,
+                latencyMs,
+                message: output.length > 0 ? "staging WP-CLI available" : "staging reachable but WP-CLI check returned empty output",
+                versionLine: output.split("\n")[0] || undefined,
+            };
+        }
+        catch (error) {
+            const latencyMs = Date.now() - startedAt;
+            const message = error instanceof Error ? error.message : "unknown staging WP-CLI probe error";
+            const hostKeyHint = stagingTarget.hostKey
+                ? ""
+                : " (tip: set WHC_STAGING_SSH_HOSTKEY to avoid first-time hostkey trust blocks)";
+            return {
+                reachable: false,
+                available: false,
+                latencyMs,
+                message: `staging WP-CLI probe failed: ${message}${hostKeyHint}`,
+            };
+        }
+    }
+}
+exports.WpCliClient = WpCliClient;