devops-whc 1.0.1

package/dist/config/env.js

@@ -0,0 +1,132 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+const dotenv_1 = __importDefault(require("dotenv"));
+const zod_1 = require("zod");
+if (process.env.WHC_ENV_FILE && process.env.WHC_ENV_FILE.trim().length > 0) {
+    dotenv_1.default.config({ path: process.env.WHC_ENV_FILE });
+}
+else {
+    dotenv_1.default.config();
+}
+const envSchema = zod_1.z.object({
+    WHC_API_TOKEN: zod_1.z.string().min(1),
+    WHC_USER: zod_1.z.string().min(1),
+    WHC_HOST: zod_1.z.string().min(1),
+    WHC_WORKFLOW_MODE: zod_1.z.enum(["managed_clone_sync", "git_controlled"]).default("managed_clone_sync"),
+    WHC_PRIMARY_DOMAIN: zod_1.z.string().min(1).optional(),
+    WHC_TESTING_DOMAIN: zod_1.z.string().min(1).optional(),
+    WHC_STAGING_DOMAIN: zod_1.z.string().min(1).optional(),
+    WHC_PROD_PATH: zod_1.z.string().min(1).default("/public_html"),
+    WHC_STAGING_PATH: zod_1.z.string().min(1).optional(),
+    WHC_REQUIRE_STAGING_CONFIRM: zod_1.z
+        .enum(["true", "false"])
+        .default("true")
+        .transform((value) => value === "true"),
+    WHC_WARN_DYNAMIC_DATA_SYNC: zod_1.z
+        .enum(["true", "false"])
+        .default("true")
+        .transform((value) => value === "true"),
+    WHC_ENFORCE_STAGING_FIRST: zod_1.z
+        .enum(["true", "false"])
+        .default("true")
+        .transform((value) => value === "true"),
+    WHC_ALLOW_STAGING_GIT_CONTROLLED: zod_1.z
+        .enum(["true", "false"])
+        .default("false")
+        .transform((value) => value === "true"),
+    WHC_PROD_SSH_HOST: zod_1.z.string().min(1),
+    WHC_PROD_SSH_PORT: zod_1.z.coerce.number().int().positive().default(27),
+    WHC_PROD_SSH_USERNAME: zod_1.z.string().min(1),
+    WHC_PROD_SSH_PRIVATE_KEY_PATH: zod_1.z.string().min(1),
+    WHC_STAGING_SSH_HOST: zod_1.z.string().min(1).optional(),
+    WHC_STAGING_SSH_PORT: zod_1.z.coerce.number().int().positive().optional(),
+    WHC_STAGING_SSH_USERNAME: zod_1.z.string().min(1).optional(),
+    WHC_STAGING_SSH_PRIVATE_KEY_PATH: zod_1.z.string().min(1).optional(),
+    WHC_STAGING_SSH_PASSWORD: zod_1.z.string().min(1).optional(),
+    WHC_STAGING_SSH_HOSTKEY: zod_1.z.string().min(1).optional(),
+    WHC_LOCAL_PROJECT_ROOT: zod_1.z.string().min(1).optional(),
+    WHC_LOCAL_APP_PATH: zod_1.z.string().min(1).optional(),
+    WHC_SOURCE_KIND: zod_1.z
+        .enum(["full_site", "partial_content", "package_only", "artifact_first", "monorepo_slice"])
+        .default("full_site"),
+    WHC_DEPLOY_UNIT: zod_1.z.enum(["raw_source", "build_artifact", "package_bundle"]).default("raw_source"),
+    WHC_BUILD_COMMAND: zod_1.z.string().min(1).optional(),
+    WHC_BUILD_ARTIFACT_PATH: zod_1.z.string().min(1).optional(),
+    WHC_DEFAULT_RELEASE_INTENT: zod_1.z
+        .enum(["refresh", "deploy", "promote", "migrate", "recover"])
+        .default("deploy"),
+    WHC_API_TIMEOUT_MS: zod_1.z.coerce.number().int().positive().default(15000),
+    WHC_SSH_TIMEOUT_MS: zod_1.z.coerce.number().int().positive().default(10000),
+    WHC_FLOW_LOG_PATH: zod_1.z.string().min(1).optional(),
+});
+function loadConfig(env = process.env) {
+    const parsed = envSchema.safeParse(env);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((issue) => issue.path.join("."))
+            .filter((field) => field.length > 0);
+        throw new Error(`VALIDATION_ERROR: Missing or invalid env vars: ${issues.join(", ")}`);
+    }
+    const data = parsed.data;
+    const prodSshHost = data.WHC_PROD_SSH_HOST;
+    const prodSshPort = data.WHC_PROD_SSH_PORT;
+    const prodSshUsername = data.WHC_PROD_SSH_USERNAME;
+    const prodSshPrivateKeyPath = data.WHC_PROD_SSH_PRIVATE_KEY_PATH;
+    const hasStagingSsh = !!data.WHC_STAGING_SSH_HOST || !!data.WHC_STAGING_SSH_USERNAME || !!data.WHC_STAGING_SSH_PRIVATE_KEY_PATH;
+    return {
+        apiToken: data.WHC_API_TOKEN,
+        user: data.WHC_USER,
+        host: data.WHC_HOST,
+        apiBaseUrl: `https://${data.WHC_HOST}:2083`,
+        workflowMode: data.WHC_WORKFLOW_MODE,
+        domains: {
+            primary: data.WHC_PRIMARY_DOMAIN,
+            testing: data.WHC_TESTING_DOMAIN,
+            staging: data.WHC_STAGING_DOMAIN,
+        },
+        paths: {
+            prod: data.WHC_PROD_PATH,
+            staging: data.WHC_STAGING_PATH,
+        },
+        sourceProfile: {
+            localProjectRoot: data.WHC_LOCAL_PROJECT_ROOT,
+            localAppPath: data.WHC_LOCAL_APP_PATH,
+            sourceKind: data.WHC_SOURCE_KIND,
+            deployUnit: data.WHC_DEPLOY_UNIT,
+            buildCommand: data.WHC_BUILD_COMMAND,
+            buildArtifactPath: data.WHC_BUILD_ARTIFACT_PATH,
+            defaultReleaseIntent: data.WHC_DEFAULT_RELEASE_INTENT,
+        },
+        safety: {
+            requireStagingConfirm: data.WHC_REQUIRE_STAGING_CONFIRM,
+            warnDynamicDataSync: data.WHC_WARN_DYNAMIC_DATA_SYNC,
+            enforceStagingFirst: data.WHC_ENFORCE_STAGING_FIRST,
+            allowStagingGitControlled: data.WHC_ALLOW_STAGING_GIT_CONTROLLED,
+        },
+        sshTargets: {
+            prod: {
+                host: prodSshHost,
+                port: prodSshPort,
+                username: prodSshUsername,
+                privateKeyPath: prodSshPrivateKeyPath,
+            },
+            staging: hasStagingSsh
+                ? {
+                    host: data.WHC_STAGING_SSH_HOST ?? prodSshHost,
+                    port: data.WHC_STAGING_SSH_PORT ?? prodSshPort,
+                    username: data.WHC_STAGING_SSH_USERNAME ?? prodSshUsername,
+                    privateKeyPath: data.WHC_STAGING_SSH_PRIVATE_KEY_PATH,
+                    password: data.WHC_STAGING_SSH_PASSWORD,
+                    hostKey: data.WHC_STAGING_SSH_HOSTKEY,
+                }
+                : undefined,
+        },
+        apiTimeoutMs: data.WHC_API_TIMEOUT_MS,
+        sshTimeoutMs: data.WHC_SSH_TIMEOUT_MS,
+        flowLogPath: data.WHC_FLOW_LOG_PATH,
+    };
+}

package/dist/contracts/deployment.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/envelope.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/dispatcher/tool-dispatcher.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatch = dispatch;
+const node_crypto_1 = require("node:crypto");
+const node_crypto_2 = require("node:crypto");
+const policy_engine_1 = require("../policy/policy-engine");
+const workspace_state_1 = require("../state/workspace-state");
+async function dispatch(options) {
+    const { config, toolDef, rawInput, validate, execute, idempotencyStore, auditLogger, actionIdFactory = node_crypto_2.randomUUID, } = options;
+    const startedAt = Date.now();
+    const startedAtIso = new Date(startedAt).toISOString();
+    // Step 1: Validate input schema
+    let request;
+    try {
+        request = validate(rawInput);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown validation error";
+        return buildErrorEnvelope(toolDef.name, actionIdFactory(), startedAt, toolDef.safetyLevel, {
+            code: "VALIDATION_ERROR",
+            message,
+            retryable: false,
+        });
+    }
+    // Step 2: Policy evaluation
+    const policy = (0, policy_engine_1.evaluatePolicy)({
+        toolName: toolDef.name,
+        mode: toolDef.mode,
+        safetyLevel: toolDef.safetyLevel,
+        dryRun: request.dry_run,
+        confirmed: request.confirmed,
+    });
+    if (!policy.allowed) {
+        return buildErrorEnvelope(toolDef.name, actionIdFactory(), startedAt, toolDef.safetyLevel, {
+            code: "BUSINESS_POLICY_BLOCKED",
+            message: policy.reason ?? "Operation blocked by safety policy",
+            retryable: false,
+        });
+    }
+    // Step 3: Idempotency check (write operations only)
+    let idempotencyKey;
+    let payloadHash;
+    if (toolDef.mode === "write" && request.idempotency_key) {
+        idempotencyKey = request.idempotency_key;
+        payloadHash = hashPayload(request.payload);
+        const existing = idempotencyStore.get(idempotencyKey);
+        if (existing && existing.payloadHash === payloadHash) {
+            return existing.response;
+        }
+    }
+    // Step 4: Execute handler
+    let response;
+    if (toolDef.mode === "write" && process.env.NODE_ENV !== "test") {
+        (0, workspace_state_1.writePipelineStartState)({
+            rootDir: process.cwd(),
+            toolName: toolDef.name,
+            requestId: request.request_id,
+            targetEnvironment: extractStringField(request.payload, "target_environment"),
+            pipelineId: extractStringField(request.payload, "pipeline_id"),
+            releaseIntent: extractStringField(request.payload, "release_intent"),
+            startedAtIso,
+        });
+    }
+    try {
+        response = await execute(config, request);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown execution error";
+        response = buildErrorEnvelope(toolDef.name, actionIdFactory(), startedAt, toolDef.safetyLevel, {
+            code: "UNKNOWN_UPSTREAM_ERROR",
+            message,
+            retryable: true,
+        });
+    }
+    if (toolDef.mode === "write" && process.env.NODE_ENV !== "test") {
+        const data = (response.data ?? null);
+        const processTracking = data && typeof data === "object" ? data["process_tracking"] : undefined;
+        const nextStep = processTracking && typeof processTracking["next_step"] === "string" ? processTracking["next_step"] : undefined;
+        (0, workspace_state_1.writePipelineEndState)({
+            rootDir: process.cwd(),
+            toolName: toolDef.name,
+            requestId: request.request_id,
+            targetEnvironment: extractStringField(request.payload, "target_environment"),
+            pipelineId: extractStringField(request.payload, "pipeline_id"),
+            releaseIntent: extractStringField(request.payload, "release_intent"),
+            startedAtIso,
+        }, {
+            ok: response.ok,
+            actionId: response.action_id,
+            nextStep,
+            errorCode: response.error?.code,
+            errorMessage: response.error?.message,
+        });
+    }
+    // Step 5: Audit write operations
+    if (toolDef.mode === "write") {
+        auditLogger.log({
+            actionId: response.action_id,
+            tool: toolDef.name,
+            status: response.ok ? "success" : "failure",
+            timestamp: new Date().toISOString(),
+            details: {
+                dry_run: request.dry_run ?? false,
+                ok: response.ok,
+                idempotency_key: idempotencyKey ?? "",
+                request_id: request.request_id,
+                target_environment: extractStringField(request.payload, "target_environment"),
+                pipeline_id: extractStringField(request.payload, "pipeline_id"),
+                release_intent: extractStringField(request.payload, "release_intent"),
+            },
+        });
+    }
+    // Step 6: Store idempotency record for successful writes
+    if (toolDef.mode === "write" && idempotencyKey && payloadHash && response.ok) {
+        idempotencyStore.set(idempotencyKey, {
+            actionId: response.action_id,
+            payloadHash,
+            response,
+        });
+    }
+    return response;
+}
+function buildErrorEnvelope(tool, actionId, startedAt, safetyLevel, error) {
+    return {
+        ok: false,
+        action_id: actionId,
+        tool,
+        data: null,
+        error,
+        meta: {
+            latency_ms: Date.now() - startedAt,
+            safety_level: safetyLevel,
+        },
+    };
+}
+function hashPayload(payload) {
+    return (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+function extractStringField(payload, key) {
+    if (!payload || typeof payload !== "object") {
+        return "";
+    }
+    const value = payload[key];
+    return typeof value === "string" ? value : "";
+}

package/dist/handlers/whc-check-health.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeWhcCheckHealth = executeWhcCheckHealth;
+exports.handleWhcCheckHealth = handleWhcCheckHealth;
+exports.buildDefaultWhcCheckHealthRequest = buildDefaultWhcCheckHealthRequest;
+const node_crypto_1 = require("node:crypto");
+const connectivity_1 = require("../probes/connectivity");
+const whc_check_health_1 = require("../schemas/whc-check-health");
+/**
+ * Pure executor: assumes request is already validated.
+ * Used by the dispatcher (validate → policy → idempotency → execute → audit).
+ */
+async function executeWhcCheckHealth(config, request, deps = {}) {
+    const startedAt = Date.now();
+    const actionIdFactory = deps.actionIdFactory ?? node_crypto_1.randomUUID;
+    const probeRunner = deps.probeRunner ?? connectivity_1.runConnectivityProbe;
+    try {
+        const report = await probeRunner(config);
+        const readiness = computeReadiness(report);
+        const warnings = buildWarnings(report);
+        return {
+            ok: true,
+            action_id: actionIdFactory(),
+            tool: "whc_check_health",
+            data: {
+                readiness,
+                capabilities: report,
+                paths: {
+                    prod: config.paths.prod,
+                    staging: config.paths.staging,
+                },
+                warnings,
+            },
+            error: null,
+            meta: {
+                latency_ms: Date.now() - startedAt,
+                safety_level: "A",
+                workflow_mode: config.workflowMode,
+                pipeline_id: request.payload.pipeline_id,
+                release_intent: request.payload.release_intent,
+                source_profile: request.payload.source_profile,
+                delivery_mechanism: "read_probe",
+            },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown health-check error";
+        return {
+            ok: false,
+            action_id: actionIdFactory(),
+            tool: "whc_check_health",
+            data: null,
+            error: {
+                code: "UNKNOWN_UPSTREAM_ERROR",
+                message,
+                retryable: true,
+            },
+            meta: {
+                latency_ms: Date.now() - startedAt,
+                safety_level: "A",
+                workflow_mode: config.workflowMode,
+                pipeline_id: request.payload.pipeline_id,
+                release_intent: request.payload.release_intent,
+                source_profile: request.payload.source_profile,
+                delivery_mechanism: "read_probe",
+            },
+        };
+    }
+}
+/**
+ * Standalone convenience wrapper: validates input then executes.
+ * Used for direct CLI invocation without the dispatcher.
+ */
+async function handleWhcCheckHealth(config, input, deps = {}) {
+    const startedAt = Date.now();
+    const actionIdFactory = deps.actionIdFactory ?? node_crypto_1.randomUUID;
+    let request;
+    try {
+        request = (0, whc_check_health_1.validateWhcCheckHealthRequest)(input);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown validation error";
+        return {
+            ok: false,
+            action_id: actionIdFactory(),
+            tool: "whc_check_health",
+            data: null,
+            error: { code: "VALIDATION_ERROR", message, retryable: false },
+            meta: { latency_ms: Date.now() - startedAt, safety_level: "A" },
+        };
+    }
+    return executeWhcCheckHealth(config, request, deps);
+}
+function buildDefaultWhcCheckHealthRequest(config) {
+    return {
+        request_id: (0, node_crypto_1.randomUUID)(),
+        actor: {
+            kind: "copilot",
+            user_hint: "local-cli",
+        },
+        payload: (0, whc_check_health_1.buildDefaultWhcCheckHealthPayload)(config),
+    };
+}
+function computeReadiness(report) {
+    if (report.uapi.ok && report.ssh.ok) {
+        return "ready";
+    }
+    if (!report.uapi.ok || !report.ssh.ok) {
+        return "needs_fix";
+    }
+    return "unknown";
+}
+function buildWarnings(report) {
+    const warnings = [];
+    if (!report.uapi.ok) {
+        warnings.push(`UAPI connectivity issue: ${report.uapi.message}`);
+    }
+    if (!report.ssh.ok) {
+        warnings.push(`Production SSH issue: ${report.ssh.message}`);
+    }
+    if (!report.sshEnvironments.staging.ok) {
+        warnings.push(`Staging SSH issue: ${report.sshEnvironments.staging.message}`);
+    }
+    if (!report.wpcli.prod.available) {
+        warnings.push(`WP-CLI unavailable on production: ${report.wpcli.prod.message}`);
+    }
+    if (!report.wpcli.staging.available) {
+        warnings.push(`WP-CLI unavailable on staging: ${report.wpcli.staging.message}`);
+    }
+    return warnings;
+}

package/dist/handlers/whc-db-backup.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeWhcDbBackup = executeWhcDbBackup;
+const node_crypto_1 = require("node:crypto");
+const ssh_client_1 = require("../clients/ssh-client");
+function buildDumpPath(outputPath, env, compress) {
+    if (outputPath)
+        return outputPath;
+    const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const ext = compress ? ".sql.gz" : ".sql";
+    return `~/db-backups/${env}-${ts}${ext}`;
+}
+function buildWpCliCommand(dumpPath, compress, tables) {
+    const tableFlag = tables && tables.length > 0 ? ` --tables=${tables.join(",")}` : "";
+    const compressFlag = compress ? " | gzip" : "";
+    if (compress) {
+        return `wp db export -${tableFlag} 2>/dev/null${compressFlag} > ${dumpPath}`;
+    }
+    return `wp db export ${dumpPath}${tableFlag}`;
+}
+async function executeWhcDbBackup(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, output_path, compress, tables } = request.payload;
+    const dumpPath = buildDumpPath(output_path, target_environment, compress);
+    // Dry run: preview command without executing
+    if (request.dry_run) {
+        const previewCmd = buildWpCliCommand(dumpPath, compress, tables);
+        return {
+            ok: true,
+            action_id: actionIdFactory(),
+            tool: "whc_db_backup",
+            data: {
+                target_environment,
+                dump_path: dumpPath,
+                compressed: compress,
+                tables,
+            },
+            error: null,
+            meta: {
+                latency_ms: Date.now() - startedAt,
+                safety_level: "D",
+                delivery_mechanism: "ssh_exec",
+            },
+        };
+    }
+    // Resolve SSH target
+    let execResult;
+    const ensureDirCmd = `mkdir -p $(dirname ${dumpPath})`;
+    const backupCmd = buildWpCliCommand(dumpPath, compress, tables);
+    const sizeCmd = `du -sh ${dumpPath} 2>/dev/null | cut -f1 || echo 'unknown'`;
+    // Ensure backup dir exists, then run wp db export, then get size
+    const fullCommand = `${ensureDirCmd} && ${backupCmd} && ${sizeCmd}`;
+    try {
+        if (target_environment === "staging") {
+            const stagingTarget = config.sshTargets.staging;
+            if (!stagingTarget) {
+                return buildErrorResponse(actionIdFactory(), startedAt, "BUSINESS_POLICY_BLOCKED", "Staging SSH target is not configured.");
+            }
+            if (!stagingTarget.privateKeyPath) {
+                return buildErrorResponse(actionIdFactory(), startedAt, "BUSINESS_POLICY_BLOCKED", "whc_db_backup requires key-based SSH auth on staging.");
+            }
+            execResult = await sshClient.execWithKey({
+                host: stagingTarget.host,
+                port: stagingTarget.port,
+                username: stagingTarget.username,
+                privateKeyPath: stagingTarget.privateKeyPath,
+            }, fullCommand);
+        }
+        else {
+            execResult = await sshClient.execWithKey(config.sshTargets.prod, fullCommand);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "SSH exec failed";
+        return buildErrorResponse(actionIdFactory(), startedAt, "AUTH_ERROR", message);
+    }
+    if (!execResult.ok) {
+        return buildErrorResponse(actionIdFactory(), startedAt, "TEMPORARY_UPSTREAM_ERROR", execResult.message || execResult.stderr || "wp db export failed");
+    }
+    const sizeHint = execResult.stdout.split("\n").filter((l) => l.trim().length > 0).pop()?.trim();
+    return {
+        ok: true,
+        action_id: actionIdFactory(),
+        tool: "whc_db_backup",
+        data: {
+            target_environment,
+            dump_path: dumpPath,
+            compressed: compress,
+            tables,
+            size_hint: sizeHint,
+        },
+        error: null,
+        meta: {
+            latency_ms: Date.now() - startedAt,
+            safety_level: "D",
+            delivery_mechanism: "ssh_exec",
+        },
+    };
+}
+function buildErrorResponse(actionId, startedAt, code, message) {
+    return {
+        ok: false,
+        action_id: actionId,
+        tool: "whc_db_backup",
+        data: null,
+        error: { code, message, retryable: code === "TEMPORARY_UPSTREAM_ERROR" },
+        meta: { latency_ms: Date.now() - startedAt, safety_level: "D" },
+    };
+}