devops-whc 1.0.1

package/AGENT_MCP_USAGE.md

@@ -0,0 +1,394 @@
+# WHC MCP Agent Usage Guide
+
+This guide is for AI agents and operators who need predictable, safe usage of the WHC MCP server.
+
+## 1. Goal
+
+Use WHC MCP to run a safe release flow:
+
+1. Initialize workspace state (`whc_prepare`).
+2. Validate connectivity and environment.
+3. Deploy to staging first.
+4. Run technical verify (`whc_verify`) and smoke gate.
+5. Promote to live only if staging passes.
+
+## 2. Runtime Model
+
+The server supports two workflow modes:
+
+1. `managed_clone_sync`
+2. `git_controlled`
+
+Most WHC managed WordPress flows use `managed_clone_sync`.
+
+If server env sets `WHC_WORKFLOW_MODE=managed_clone_sync`, treat staging as managed-only.
+Do not call `git_controlled` for staging in that mode.
+
+## 2.2 MCP Registration Standard
+
+Use one of these two registration patterns and keep them consistent with README.
+
+Published package (`npx`) recommended for most users:
+
+```jsonc
+{
+  "servers": {
+    "whc-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "devops-whc", "--serve"],
+      "env": {
+        "WHC_ENV_FILE": "${workspaceFolder}/.env",
+        "WHC_LOCAL_PROJECT_ROOT": "${workspaceFolder}",
+        "WHC_STATE_ROOT": ".mcp/whc-mcp",
+        "WHC_MCP_INSTANCE_NAME": "whc-mcp"
+      }
+    }
+  }
+}
+```
+
+Local clone (`start-mcp.cjs`) for contributors:
+
+```jsonc
+{
+  "servers": {
+    "whc-mcp": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["./scripts/start-mcp.cjs"],
+      "cwd": "${workspaceFolder}",
+      "env": {
+        "WHC_ENV_FILE": "${workspaceFolder}/.env",
+        "WHC_LOCAL_PROJECT_ROOT": "${workspaceFolder}",
+        "WHC_STATE_ROOT": ".mcp/whc-mcp",
+        "WHC_MCP_INSTANCE_NAME": "whc-mcp"
+      }
+    }
+  }
+}
+```
+
+Quick CLI checks:
+
+```powershell
+npx -y devops-whc --help
+npx -y devops-whc --version
+npx -y devops-whc --probe
+```
+
+## 2.3 Publish Package Boundary
+
+Release artifacts are published from `packages/devops-whc`, not from repository root.
+
+Release commands:
+
+```powershell
+npm run pack:check
+npm --prefix packages/devops-whc publish
+```
+
+`npm run pack:check` will run publish preparation and package dry-run against the subpackage.
+
+## 2.1 Why `whc_setup_remote` Exists
+
+`whc_setup_remote` does not deploy application code.
+
+It only prepares the remote Git endpoint on cPanel (repository root + SSH hint) so local source can be pushed.
+
+Think of it as wiring transport, not shipping release.
+
+After `whc_setup_remote`, a manual or automated `git push` from local source is still required, then `whc_deploy` triggers deployment tasks.
+
+## 3. Required Context Before Any Write
+
+Always collect these first:
+
+1. Active workflow mode.
+2. Target environment (`staging` or `live`).
+3. Direction (for managed clone/sync):
+   - `live_to_staging`
+   - `staging_to_live`
+4. Sync scope:
+   - `files`
+   - `database`
+   - `everything`
+5. Whether `dry_run` and `confirmed` are required by policy.
+6. For `git_controlled`, ensure `repository_root` belongs to current `WHC_USER` home path (`/home/<WHC_USER>/...`).
+
+## 3.1 Manual vs Agent Responsibilities
+
+User/operator must do manually (once per environment):
+1. Create/rotate WHC API token and place in env (`WHC_API_TOKEN`).
+2. Add SSH public key to correct cPanel account.
+3. Confirm host/path ownership and account scope.
+
+Agent can automate repeatedly:
+1. Validate context and run dry-run checks.
+2. Create/list repository via `whc_setup_remote`.
+3. Trigger deployment via `whc_deploy`.
+4. Execute safe runtime probes and logs/health collection.
+
+Hybrid step:
+1. `git push` may be run by agent from local terminal when keys/permissions are ready; otherwise operator performs push manually.
+
+## 4. Safety Rules
+
+1. Never promote live directly without staging verification.
+2. For `staging_to_live` with `database` or `everything`, provide backup reference unless emergency override is explicitly approved.
+3. Prefer `dry_run=true` before state-changing requests.
+4. Always set `confirmed=true` when the policy requires explicit confirmation.
+
+## 5. Tool Order (Recommended)
+
+1. `whc_prepare` to initialize hidden state and readiness checks.
+2. `whc_check_health` for target status and capability baseline.
+3. `whc_get_logs` for pre-deploy signal.
+4. `whc_deploy` with `dry_run=true`.
+5. `whc_deploy` real execution after dry-run passes.
+6. `whc_verify` to produce technical verify report.
+7. Run smoke checks outside or via allowed tool path.
+8. If staging passes, run promote flow for live with explicit direction and backup policy.
+
+## 6.4 Rollback (Level D) Contract
+
+Use rollback only when verify and policy conditions are satisfied.
+
+Mandatory gates:
+1. `dry_run=true` for preview.
+2. `confirmed=true` for execution.
+3. Verify-chain report from `whc_verify` with `final_status=PASS`.
+
+Example rollback preview payload:
+
+```json
+{
+  "dry_run": true,
+  "confirmed": true,
+  "payload": {
+    "target_environment": "live",
+    "rollback_mode": "git_branch",
+    "rollback_branch": "rollback/main",
+    "reason": "production incident mitigation",
+    "verify_release_id": "rel-2026-06-10-01"
+  }
+}
+```
+
+## 6. Canonical Payloads
+
+### 6.1 Staging dry-run (managed clone/sync refresh)
+
+```json
+{
+  "dry_run": true,
+  "confirmed": true,
+  "payload": {
+    "workflow_mode": "managed_clone_sync",
+    "target_environment": "staging",
+    "release_intent": "refresh",
+    "pipeline_id": "P3D",
+    "source_profile": {
+      "source_kind": "full_site",
+      "deploy_unit": "raw_source"
+    },
+    "direction": "live_to_staging",
+    "sync_scope": "files",
+    "verify_after_deploy": true,
+    "auto_rollback_on_verify_failure": false
+  }
+}
+```
+
+### 6.2 Staging real refresh sync (managed clone/sync)
+
+```json
+{
+  "confirmed": true,
+  "payload": {
+    "workflow_mode": "managed_clone_sync",
+    "target_environment": "staging",
+    "release_intent": "refresh",
+    "pipeline_id": "P3D",
+    "source_profile": {
+      "source_kind": "full_site",
+      "deploy_unit": "raw_source"
+    },
+    "direction": "live_to_staging",
+    "sync_scope": "files",
+    "verify_after_deploy": true,
+    "auto_rollback_on_verify_failure": false
+  }
+}
+```
+
+### 6.3 Live promote (higher risk)
+
+```json
+{
+  "confirmed": true,
+  "payload": {
+    "workflow_mode": "managed_clone_sync",
+    "target_environment": "live",
+    "release_intent": "promote",
+    "pipeline_id": "P3D",
+    "source_profile": {
+      "source_kind": "full_site",
+      "deploy_unit": "raw_source"
+    },
+    "direction": "staging_to_live",
+    "sync_scope": "files",
+    "verify_after_deploy": true,
+    "auto_rollback_on_verify_failure": true
+  }
+}
+```
+
+## 7. Smoke Gate Expectations
+
+Before live promote, ensure AC-critical smoke is green on staging.
+
+Suggested minimum:
+
+1. Account page reachable.
+2. Required API namespace/routes reachable.
+3. Pricing visibility behavior by auth state.
+4. Checkout fee messaging baseline.
+
+If preconditions fail (plugin/page/routes absent), gate must be `HOLD`.
+
+## 7.1 Pipeline Mindset Guard
+
+Treat these as two different operations:
+
+1. Environment refresh:
+  - `workflow_mode=managed_clone_sync`
+  - `direction=live_to_staging`
+  - `release_intent=refresh`
+2. Release deploy to staging:
+  - Use release candidate source (typically `git_controlled`), not live mirror sync.
+  - Use `repository_root` under `/home/<WHC_USER>/...`; cross-account paths are blocked by policy.
+
+Policy note:
+
+1. `managed_clone_sync + live_to_staging + release_intent=deploy` is blocked by policy because it causes release-testing ambiguity.
+
+## 8. Troubleshooting
+
+### 8.1 Startup auth errors with SSH key path
+
+Symptom:
+
+1. `AUTH_ERROR` or `ENOENT` for key file while path appears valid.
+
+Checks:
+
+1. Confirm `WHC_ENV_FILE` points to the intended env file.
+2. Confirm the MCP process has reloaded after env edits.
+3. Avoid malformed quoting in key path values.
+
+### 8.2 Deploy validation errors in managed mode
+
+If request fails with missing direction, ensure payload includes:
+
+1. `direction`
+2. `sync_scope`
+
+## 9. One-Line Operator Playbook
+
+1. Health check -> logs -> staging dry-run -> staging deploy -> smoke gate -> decide promote/hold.
+
+## 10. Flow Log Read Guide (For Agent Responses)
+
+### 10.1 Log path
+
+1. Default path: `.mcp/whc-mcp/logs/flow-events.jsonl`
+2. Custom path (optional): set `WHC_FLOW_LOG_PATH` in env
+
+### 10.2 Read latest entries (PowerShell)
+
+```powershell
+Get-Content .mcp/whc-mcp/logs/flow-events.jsonl -Tail 20
+```
+
+If custom path is configured:
+
+```powershell
+Get-Content $env:WHC_FLOW_LOG_PATH -Tail 20
+```
+
+Filter only deploy events:
+
+```powershell
+Get-Content .mcp/whc-mcp/logs/flow-events.jsonl -Tail 200 |
+  ForEach-Object { $_ | ConvertFrom-Json } |
+  Where-Object { $_.tool -eq 'whc_deploy' } |
+  Select-Object -Last 10
+```
+
+### 10.3 Response format requirement
+
+When responding after any write tool run, agent should include:
+
+1. `action_id`
+2. `tool`
+3. `status` (`success` or `failure`)
+4. `request_id` (if available)
+5. `pipeline_id`
+6. `target_environment`
+7. `release_intent`
+8. Log path used
+
+Minimal response snippet:
+
+```text
+Flow log:
+- path: .mcp/whc-mcp/logs/flow-events.jsonl
+- action_id: <value>
+- tool: whc_deploy
+- status: success|failure
+- request_id: <value>
+- pipeline_id: <value>
+- target_environment: staging|live
+- release_intent: deploy|refresh|promote|migrate|recover
+```
+
+## 10.4 First-Time Prepare (No Manual Template Filling)
+
+For local clone workflows, run once per workspace:
+
+```powershell
+npm run mcp:prepare
+```
+
+For npm-package workflows, call `whc_prepare` once from the MCP client after the server starts.
+
+This initializes hidden management paths automatically:
+1. `.mcp/whc-mcp/state/pipeline-status.json`
+2. `.mcp/whc-mcp/state/releases/`
+3. `.mcp/whc-mcp/state/reports/`
+4. `.mcp/whc-mcp/logs/`
+
+It also ensures `.mcp/` is ignored by git.
+
+## 10.5 Automatic State Tracking
+
+For every write tool run, MCP now auto-updates:
+1. `.mcp/whc-mcp/state/pipeline-status.json` (started/completed/status/next step/error)
+2. `.mcp/whc-mcp/state/releases/<request_id>.auto-manifest.json` (tool metadata + git changed files snapshot)
+
+No manual template authoring is required for normal DevOps runs.
+
+## 11. Pipeline Progress Tracking (What To Read)
+
+For `whc_deploy` and `whc_setup_remote`, read these response fields first:
+1. `data.pipeline_status`
+  - `full_pass` or `pass_partial`
+2. `data.phase_coverage`
+  - `code_state`, `runtime_state`, `data_state`, `deployment_state`
+3. `data.process_tracking` (setup_remote)
+  - `stage`, `status`, `next_step`, `manual_actions`
+
+Decision rule:
+1. If `pipeline_status=pass_partial`, do not claim end-to-end release completion.
+2. Follow `next_step` and unresolved `manual_actions` before moving to next gate.

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,208 @@
+# devops-whc
+
+WHC cPanel MCP server for deploy, verify, rollback, logs, backup, and health flows.
+
+Current release: 1.0.1
+
+## Publish Package Layout
+
+Npm release artifacts are now isolated in a dedicated package folder:
+
+- `packages/devops-whc`
+
+The repository root is the development workspace. The publish package is prepared by syncing built/runtime files into `packages/devops-whc` before packing or publishing.
+
+## What this is
+
+This package exposes an MCP server that VS Code Copilot or any MCP client can launch over stdio. It is designed for WHC cPanel projects and keeps the local workflow, target environment, and safety rules explicit.
+
+The server supports both usage patterns:
+
+1. Run from a local clone while developing.
+2. Install from npm and launch with `npx` or a global install.
+
+## Install
+
+### From a clone
+
+```powershell
+npm install
+npm run build
+```
+
+### From npm
+
+```powershell
+npx -y devops-whc --help
+```
+
+Or install globally:
+
+```powershell
+npm install -g devops-whc
+whc-mcp --help
+```
+
+## Quick Start
+
+1. Copy `.env.example` to `.env`.
+2. Fill in the required WHC credentials and target paths.
+3. Run `npm run mcp:prepare` once per workspace.
+4. Start the server with `npm run serve` for local development, or `npx -y devops-whc --serve` after npm install.
+
+If you are using VS Code Copilot MCP, point the server command to the published package or to the local `start-mcp.cjs` helper.
+
+## VS Code MCP Config
+
+Published-package example:
+
+```jsonc
+{
+  "servers": {
+    "whc-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "devops-whc", "--serve"],
+      "env": {
+        "WHC_ENV_FILE": "${workspaceFolder}/.env",
+        "WHC_LOCAL_PROJECT_ROOT": "${workspaceFolder}",
+        "WHC_STATE_ROOT": ".mcp/whc-mcp",
+        "WHC_MCP_INSTANCE_NAME": "whc-mcp"
+      }
+    }
+  }
+}
+```
+
+Local-source example:
+
+```jsonc
+{
+  "servers": {
+    "whc-mcp": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["./scripts/start-mcp.cjs"],
+      "cwd": "${workspaceFolder}",
+      "env": {
+        "WHC_ENV_FILE": "${workspaceFolder}/.env",
+        "WHC_LOCAL_PROJECT_ROOT": "${workspaceFolder}",
+        "WHC_STATE_ROOT": ".mcp/whc-mcp",
+        "WHC_MCP_INSTANCE_NAME": "whc-mcp"
+      }
+    }
+  }
+}
+```
+
+## CLI Commands
+
+```powershell
+whc-mcp --serve
+whc-mcp --probe
+whc-mcp --check-health
+whc-mcp --help
+whc-mcp --version
+```
+
+If you are using the npm package directly, the same commands work through `npx`:
+
+```powershell
+npx -y devops-whc --serve
+npx -y devops-whc --probe
+npx -y devops-whc --check-health
+npx -y devops-whc --help
+npx -y devops-whc --version
+```
+
+## Required Environment Variables
+
+Set these in your local `.env` file:
+
+- `WHC_API_TOKEN`
+- `WHC_USER`
+- `WHC_HOST`
+- `WHC_PROD_SSH_HOST`
+- `WHC_PROD_SSH_USERNAME`
+- `WHC_PROD_SSH_PRIVATE_KEY_PATH`
+
+## Optional Environment Variables
+
+- `WHC_WORKFLOW_MODE`
+- `WHC_PRIMARY_DOMAIN`
+- `WHC_TESTING_DOMAIN`
+- `WHC_STAGING_DOMAIN`
+- `WHC_PROD_PATH`
+- `WHC_STAGING_PATH`
+- `WHC_REQUIRE_STAGING_CONFIRM`
+- `WHC_WARN_DYNAMIC_DATA_SYNC`
+- `WHC_ENFORCE_STAGING_FIRST`
+- `WHC_ALLOW_STAGING_GIT_CONTROLLED`
+- `WHC_STAGING_SSH_HOST`
+- `WHC_STAGING_SSH_PORT`
+- `WHC_STAGING_SSH_USERNAME`
+- `WHC_STAGING_SSH_PRIVATE_KEY_PATH`
+- `WHC_STAGING_SSH_PASSWORD`
+- `WHC_STAGING_SSH_HOSTKEY`
+- `WHC_LOCAL_PROJECT_ROOT`
+- `WHC_LOCAL_APP_PATH`
+- `WHC_SOURCE_KIND`
+- `WHC_DEPLOY_UNIT`
+- `WHC_BUILD_COMMAND`
+- `WHC_BUILD_ARTIFACT_PATH`
+- `WHC_DEFAULT_RELEASE_INTENT`
+- `WHC_API_TIMEOUT_MS`
+- `WHC_SSH_TIMEOUT_MS`
+- `WHC_FLOW_LOG_PATH`
+- `WHC_STATE_ROOT`
+
+## Practical Examples
+
+### 1) Check connectivity before deploy
+
+```powershell
+npx -y devops-whc --probe
+```
+
+This checks the UAPI, SSH, and WP-CLI connectivity signals before a deploy run.
+
+### 2) Run a health check
+
+```powershell
+npx -y devops-whc --check-health
+```
+
+Use this to inspect disk, SSL, load, and capability state.
+
+### 3) Start the MCP server in VS Code
+
+Once the MCP config is in place, Copilot can launch the server and call tools such as `whc_prepare`, `whc_deploy`, `whc_verify`, and `whc_rollback`.
+
+### 4) Prepare workspace state once
+
+```powershell
+npm run mcp:prepare
+```
+
+This initializes the hidden project state under `.mcp/whc-mcp` and ensures the workspace ignores local management files.
+
+## Safety Notes
+
+1. Never commit `.env` or `.vscode/whc.env`.
+2. Keep secrets in your local workspace only.
+3. The npm tarball is limited to the published files list and does not include local env files.
+4. For staging-to-live or database-changing operations, follow the tool safety prompts and confirm the release intent.
+
+## Publish Checklist
+
+1. `npm run test`
+2. `npm run pack:check`
+3. `npm --prefix packages/devops-whc publish`
+
+Notes:
+1. `npm run pack:check` automatically runs publish preparation and packs from `packages/devops-whc`.
+2. Do not publish from the repository root package.
+
+## License
+
+ISC