devops-whc 1.0.2-next → 1.0.3

package/README.md

@@ -1,377 +1,134 @@
-# devops-whc
-
-WHC cPanel automation CLI for deploy, verify, rollback, logs, backup, and health flows.
-
-Current workspace version: 1.0.2-next
-
-## 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 a stdio tool server and CLI that VS Code Copilot or other clients can launch. 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 --help
-```
-
-## Quick Start
-
-1. Copy `.env.example` to `.env`.
-2. Fill in the required WHC credentials and target paths.
-3. Run `npm run 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, point the server command to the published package or to the local `start-whc.cjs` helper.
-
-## NPM Scripts (Workspace Root)
-
-Run these from repository root (`devops-whc`):
-
-```powershell
-npm run help
-npm run serve
-npm run start
-npm run probe
-npm run check:generic
-npm run check:health
-```
-
-Quality and release scripts:
-
-```powershell
-npm run lint
-npm run typecheck
-npm test
-npm run build
-npm run pack:check
-npm run publish:prepare
-```
-
-When to use each:
-
-1. `npm run serve`: run directly from TypeScript source (best for local development).
-2. `npm run start`: run built output through `scripts/start-whc.cjs` (best for local runtime behavior similar to published package).
-3. `npm run prepare`: initialize local `.whc` state once.
-4. `npm run pack:check` / `npm run publish:npm`: publish pipeline scripts.
-
-## NPM Scripts (Publish Subpackage)
-
-If you work inside `packages/devops-whc`, available scripts are:
-
-```powershell
-npm --prefix packages/devops-whc run help
-npm --prefix packages/devops-whc run start
-npm --prefix packages/devops-whc run serve
-npm --prefix packages/devops-whc run probe
-npm --prefix packages/devops-whc run check:generic
-npm --prefix packages/devops-whc run check:health
-```
-
-These scripts automatically sync fresh artifacts from root via pre-hooks before execution.
-
-## VS Code Tool Server Config
-
-Published-package example:
-
-```jsonc
-{
-  "servers": {
-    "whc": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "devops-whc", "--serve"],
-      "env": {
-        "WHC_ENV_FILE": "${workspaceFolder}/.env",
-        "WHC_LOCAL_PROJECT_ROOT": "${workspaceFolder}",
-        "WHC_STATE_ROOT": ".whc",
-        "WHC_INSTANCE_NAME": "whc"
-      }
-    }
-  }
-}
-```
-
-Local-source example:
-
-```jsonc
-{
-  "servers": {
-    "whc": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["./scripts/start-whc.cjs"],
-      "cwd": "${workspaceFolder}",
-      "env": {
-        "WHC_ENV_FILE": "${workspaceFolder}/.env",
-        "WHC_LOCAL_PROJECT_ROOT": "${workspaceFolder}",
-        "WHC_STATE_ROOT": ".whc",
-        "WHC_INSTANCE_NAME": "whc"
-      }
-    }
-  }
-}
-```
-
-## CLI Commands
-
-```powershell
-whc --serve
-whc --probe
-whc --check-generic --project-root D:/Source/mytho/source/wordpress --workflow-mode ssh_scp_wpcli
-whc --check-health
-whc --help
-whc --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-generic --project-root D:/Source/mytho/source/wordpress --workflow-mode ssh_scp_wpcli
-npx -y devops-whc --check-health
-npx -y devops-whc --help
-npx -y devops-whc --version
-```
-
-## Local Run vs Script Run
-
-You can run the tool in both ways:
-
-1. Local development from this repo:
-  - Use npm scripts (`npm run serve`, `npm run probe`, `npm run check:generic`, ...).
-2. Installed package usage:
-  - Use `npx -y devops-whc ...` or global `whc ...`.
-
-You do not have to call custom script files manually in normal usage. The wrapper script (`start-whc.cjs`) is already wired behind `npm run start` and package start flow.
-
-## Required Environment Variables
-
-Base config:
-
-- `WHC_WORKFLOW_MODE`
-- `WHC_LOCAL_PROJECT_ROOT`
-
-For `git_deploy`:
-
-- `WHC_API_TOKEN`
-- `WHC_USER`
-- `WHC_HOST`
-- `WHC_PROD_PATH`
-
-For `ssh_scp_wpcli`:
-
-- `WHC_STAGING_SSH_HOST`
-- `WHC_STAGING_SSH_USERNAME`
-- one of:
-  - `WHC_STAGING_SSH_PRIVATE_KEY_PATH`
-  - `WHC_STAGING_SSH_PASSWORD`
-
-## Optional Environment Variables
-
-- `WHC_WORKFLOW_MODE`
-  - `git_deploy`: local source -> cPanel-managed Git repo -> deployment task
-  - `ssh_scp_wpcli`: source-driven workflow like `mytho/source` (doctor + SCP + WP-CLI + smoke)
-  - default if omitted: `ssh_scp_wpcli`
-- `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_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) Run deploy readiness check (single command)
-
-```powershell
-npx -y devops-whc --check-generic --project-root D:/Source/mytho/source/wordpress --workflow-mode ssh_scp_wpcli
-```
-
-Or from local clone:
-
-```powershell
-npm run check:generic -- D:/Source/mytho/source/wordpress
-```
-
-This command validates whether your local WordPress source shape is compatible with the WHC generic pipeline supported by this tool.
-
-`--project-root` is required. `--app-path` is optional.
-
-If `--app-path` is omitted, WHC treats `project-root` itself as the app root.
-If `--app-path` is provided but wrong, the command fails and does not initialize hidden files.
-
-Once the effective app root is valid, the command bootstraps hidden WHC state inside that app directory:
-
-1. `<app-path>/.whc/state/...`
-2. `<app-path>/.whc/logs/...`
-3. `<app-path>/.whc/env/whc.env`
-4. `<app-path>/.whc/env/whc.env.example`
-
-If credentials or SSH keys are still missing for that specific project, the check returns `status=blocked` with exact env keys to fill in the bootstrapped hidden env file.
-
-Current behavior by workflow mode:
-
-1. `git_deploy`: validates local source/layout compatibility for repository-driven cPanel deploy flows, including `.cpanel.yml` at repository root.
-2. `ssh_scp_wpcli`: validates the `mytho/source` style contract more directly:
-   - deployable plugin/theme entrypoints
-   - idempotent seed script
-   - local `ssh`/`scp`
-   - staging SSH/WP-CLI/path/domain probes
-   - `/wp-json/` HTTP readiness
-
-Important current boundary:
-
-1. `check:generic` is the main trustworthy gate for source compatibility and hidden-state bootstrap.
-2. `whc_setup_remote` is for wiring remote Git repository metadata on cPanel.
-3. `ssh_scp_wpcli` is the default workflow mode for `mytho/source`.
-4. `git_deploy` now triggers the cPanel deployment task for the requested `repository_root` and optional `branch`.
-5. `whc_deploy` is still not the end-to-end executor for the `mytho/source` SCP/WP-CLI pipeline.
-
-What you need from the result:
-
-1. `ready_for_deploy=true` and `status=ready`: ready to run deploy pipeline.
-2. `ready_for_deploy=false` and `status=blocked`: not ready yet.
-3. `next_actions`: exact steps to fix before rerun.
-
-You do not need to choose or manage internal source categories. The command applies internal checks and returns one deploy readiness decision plus actionable next steps.
-
-### 4) Start the tool server in VS Code
-
-Once the config is in place, Copilot can launch the server and call tools such as `whc_prepare`, `whc_deploy`, `whc_verify`, and `whc_rollback`.
-
-### 5) Prepare workspace state once
-
-```powershell
-npm run prepare
-```
-
-This initializes the hidden project state under `.whc` 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.
-
-## Release Prep
-
-Run these from repository root before publishing:
+# devops-whc
 
-```powershell
-npm run typecheck
-npm test
-npm run publish:prepare
-npm run pack:check
-```
+WHC cPanel automation CLI for deploy, verify, rollback, logs, backup, and health flows.
 
-What each step does:
+## Getting Started
 
-1. `npm run typecheck`: validates TypeScript before release.
-2. `npm test`: runs the test suite.
-3. `npm run publish:prepare`: syncs root docs/scripts/build output into `packages/devops-whc`.
-4. `npm run pack:check`: dry-runs the actual npm package from `packages/devops-whc`.
+Install globally:
+
+```powershell
+npm install -g devops-whc
+whc --help
+```
 
-Publish only after the dry-run looks correct:
+Or run directly with `npx`:
 
 ```powershell
-npm run publish:npm
+npx -y devops-whc --help
 ```
 
-## NPM Auth
+## What This Package Is For
+
+Use `devops-whc` when you need a local CLI / stdio server for WHC cPanel workflows such as:
+
+1. deploy readiness checks
+2. health and connectivity checks
+3. repository-driven cPanel Git deployment
+4. source-driven WordPress delivery with SSH/SCP/WP-CLI
+
+## Two Workflow Modes
+
+### `ssh_scp_wpcli`
+
+Default mode. Use this for `mytho/source` style delivery:
+
+1. doctor
+2. backup
+3. SCP code sync
+4. WP-CLI bootstrap
+5. seed/bootstrap
+6. smoke gate
+
+### `git_deploy`
+
+Use this when your real deployment path is:
+
+1. local Git repository
+2. push to cPanel-managed repository
+3. trigger cPanel deployment task
+
+For this mode, `whc_deploy` uses:
 
-Authenticate npm on this machine before the real publish:
+1. `repository_root` as the remote cPanel-managed repository path
+2. optional `branch` if you want to deploy a specific branch
+
+## First Practical Step
+
+Run a readiness check against the actual project folder you want to manage:
 
 ```powershell
-npm whoami
-npm login
-npm whoami
+npx -y devops-whc --check-generic --project-root D:/Source/mytho/source/wordpress
 ```
 
-If your org uses browser-based auth, npm may open a web flow after `npm login`.
+What this does:
+
+1. validates the target project layout
+2. bootstraps hidden WHC state under that project
+3. tells you exactly which env values are still missing
+
+`--project-root` is required.
 
-Useful checks:
+`--app-path` is optional.
+If omitted, WHC treats `project-root` itself as the app root.
+
+## Commands You Will Actually Use
 
 ```powershell
-npm config get registry
-npm access ls-packages
+whc --help
+whc --probe
+whc --check-health
+whc --check-generic --project-root D:/Source/mytho/source/wordpress
+whc --serve
+```
+
+The same commands also work with `npx -y devops-whc ...`.
+
+## VS Code / Copilot Example
+
+```jsonc
+{
+  "servers": {
+    "whc": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "devops-whc", "--serve"],
+      "env": {
+        "WHC_ENV_FILE": "${workspaceFolder}/.env",
+        "WHC_LOCAL_PROJECT_ROOT": "${workspaceFolder}",
+        "WHC_STATE_ROOT": ".whc",
+        "WHC_INSTANCE_NAME": "whc"
+      }
+    }
+  }
+}
 ```
 
-Release notes:
-
-1. `npm run publish:npm` publishes from `packages/devops-whc`, not from repository root.
-2. For prerelease versions like `1.0.2-next`, the publish script automatically uses dist-tag `next`.
-3. Do not run `npm publish` directly from the repository root package.
-4. Be explicit in release notes that `ssh_scp_wpcli` is the default mode for `mytho/source`, while `git_deploy` is the repository-driven cPanel deployment path.
-
-## License
-
-ISC
-
-
+## Minimum Config Mindset
+
+For `git_deploy`, think:
+
+1. `WHC_API_TOKEN`
+2. `WHC_USER`
+3. `WHC_HOST`
+4. `WHC_PROD_PATH`
+5. `repository_root`
+
+For `ssh_scp_wpcli`, think:
+
+1. local WordPress app root
+2. staging SSH host/user
+3. SSH key or password
+4. remote staging path
+5. smoke-ready WordPress runtime
+
+## Current Boundary
+
+1. `check:generic` is the main trustworthy readiness/bootstrap gate.
+2. `whc_setup_remote` prepares remote Git repository wiring on cPanel.
+3. `git_deploy` triggers the cPanel deployment task for the requested `repository_root` and optional `branch`.
+4. `ssh_scp_wpcli` is still the correct default mindset for `mytho/source`.
+5. `whc_deploy` does not yet execute the full `ssh_scp_wpcli` runtime pipeline end to end; keep that in project-local scripts.
+
+## License
+
+ISC

package/dist/config/env.js

@@ -7,10 +7,10 @@ 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 });
+    dotenv_1.default.config({ path: process.env.WHC_ENV_FILE, quiet: true });
 }
 else {
-    dotenv_1.default.config();
+    dotenv_1.default.config({ quiet: true });
 }
 const envSchema = zod_1.z.object({
     WHC_API_TOKEN: zod_1.z.string().min(1).optional(),

package/dist/index.js

@@ -23,34 +23,34 @@ const APP_VERSION = process.env.npm_package_version ?? "0.0.0";
 const HELP_TEXT = [
     `WHC CLI Help v${APP_VERSION}`,
     "",
+    "Getting started:",
+    "  1) Create a project-local .env with your WHC values",
+    "  2) Run check-generic against the real project folder you want to manage",
+    "  3) Fix any blocked env/path issues reported by the check",
+    "  4) Run serve when you want Copilot/clients to call the tool server",
+    "",
+    "Most-used commands:",
+    "  whc --help",
+    "  whc --probe",
+    "  whc --check-health",
+    "  whc --check-generic --project-root D:/Source/mytho/source/wordpress",
+    "  whc --serve",
+    "",
+    "npx equivalents:",
+    "  npx -y devops-whc --help",
+    "  npx -y devops-whc --probe",
+    "  npx -y devops-whc --check-health",
+    "  npx -y devops-whc --check-generic --project-root D:/Source/mytho/source/wordpress",
+    "  npx -y devops-whc --serve",
+    "",
     "Modes:",
-    "  --serve         Start stdio tool server (registers all tools)",
+    "  --serve         Start stdio tool server",
     "  --probe         Run connectivity probe (UAPI, SSH, WP-CLI)",
     "  --check-generic Run one-shot deploy readiness check for a specific project folder",
     "  --check-health  Execute whc_check_health once and print JSON",
     "  --version       Print CLI version",
     "  --help          Show this help",
     "",
-    "Quick start:",
-    "  1) npm install",
-    "  2) copy .env.example to .env and fill secrets",
-    "  3) npm run prepare",
-    "  4) npm run serve",
-    "",
-    "Published package use:",
-    "  npx -y devops-whc --serve",
-    "  npx -y devops-whc --probe",
-    "  npx -y devops-whc --check-generic --project-root D:/Source/mytho/source/wordpress --workflow-mode ssh_scp_wpcli",
-    "  npx -y devops-whc --check-health",
-    "",
-    "Safe release flow:",
-    "  1) check-health",
-    "  2) pre-deploy logs",
-    "  3) staging deploy dry-run (confirmed=true if policy requires)",
-    "  4) staging deploy real",
-    "  5) smoke gate",
-    "  6) promote live only when smoke is green",
-    "",
     "Git deploy payload reminders:",
     "  - repository_root is required",
     "  - branch is optional; omitted means deploy current configured HEAD",
@@ -68,8 +68,8 @@ const HELP_TEXT = [
     "  - do not commit .env or .vscode/whc.env",
     "  - npm tarball excludes local env files by design",
     "",
-    "Reference:",
-    "  - AGENT_USAGE.md",
+    "Contributor note:",
+    "  - if you are developing from the git repo, use README.md in the repository root",
 ].join("\n");
 async function main() {
     if (process.argv.includes("--help")) {

package/dist/server.js

@@ -50,7 +50,7 @@ async function createWhcToolServer() {
     const ToolServerClass = sdkModule["M" + "cpServer"];
     const server = new ToolServerClass({
         name: instanceName,
-        version: "1.0.2-next",
+        version: "1.0.3",
     });
     // ── whc_prepare ───────────────────────────────────────────────────────────
     server.registerTool("whc_prepare", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devops-whc",
-  "version": "1.0.2-next",
+  "version": "1.0.3",
   "description": "WHC cPanel automation CLI for deploy, verify, and rollback flows",
   "main": "dist/index.js",
   "bin": {
@@ -12,27 +12,15 @@
   "files": [
     "dist",
     "scripts/start-whc.cjs",
-    "scripts/prepare-first-time.cjs",
     "README.md",
-    "AGENT_USAGE.md",
-    "WHC_REQUIREMENTS.md",
     "LICENSE"
   ],
   "scripts": {
-    "prepack": "node ../../scripts/prepare-publish-package.cjs",
-    "publish:release": "npm publish",
-    "pack:check": "npm pack --dry-run",
-    "prehelp": "node ../../scripts/prepare-publish-package.cjs",
     "help": "node dist/index.js --help",
-    "prestart": "node ../../scripts/prepare-publish-package.cjs",
     "start": "node scripts/start-whc.cjs",
-    "preserve": "node ../../scripts/prepare-publish-package.cjs",
     "serve": "node dist/index.js --serve",
-    "preprobe": "node ../../scripts/prepare-publish-package.cjs",
     "probe": "node dist/index.js --probe",
-    "precheck:generic": "node ../../scripts/prepare-publish-package.cjs",
     "check:generic": "node dist/index.js --check-generic",
-    "precheck:health": "node ../../scripts/prepare-publish-package.cjs",
     "check:health": "node dist/index.js --check-health"
   },
   "keywords": [

package/AGENT_USAGE.md

@@ -1,375 +0,0 @@
-# WHC CLI Agent Usage Guide
-
-This guide is for AI agents and operators who need predictable, safe usage of the WHC tool server.
-
-## 1. Goal
-
-Use WHC CLI 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. `git_deploy`
-2. `ssh_scp_wpcli`
-
-`git_deploy` means local source is pushed to a cPanel-managed Git repository and deployment is triggered from that repository.
-`ssh_scp_wpcli` means source-first delivery over SSH/SCP with runtime bootstrap via WP-CLI and smoke gating.
-If `WHC_WORKFLOW_MODE` is omitted, default to `ssh_scp_wpcli`.
-
-## 2.2 Tool Server 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": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "devops-whc", "--serve"],
-      "env": {
-        "WHC_ENV_FILE": "${workspaceFolder}/.env",
-        "WHC_LOCAL_PROJECT_ROOT": "${workspaceFolder}",
-        "WHC_STATE_ROOT": ".whc",
-        "WHC_INSTANCE_NAME": "whc"
-      }
-    }
-  }
-}
-```
-
-Local clone (`start-whc.cjs`) for contributors:
-
-```jsonc
-{
-  "servers": {
-    "whc": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["./scripts/start-whc.cjs"],
-      "cwd": "${workspaceFolder}",
-      "env": {
-        "WHC_ENV_FILE": "${workspaceFolder}/.env",
-        "WHC_LOCAL_PROJECT_ROOT": "${workspaceFolder}",
-        "WHC_STATE_ROOT": ".whc",
-        "WHC_INSTANCE_NAME": "whc"
-      }
-    }
-  }
-}
-```
-
-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 run publish:npm
-```
-
-`npm run pack:check` will run publish preparation and package dry-run against the subpackage.
-`npm run publish:npm` runs `npm publish` from the publish subpackage.
-For prerelease versions, `npm run publish:npm` automatically adds `--tag next` unless an explicit tag is provided.
-
-## 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.
-
-Current boundary:
-
-1. `whc_setup_remote` is ready for remote Git repository setup.
-2. `check:generic` is the main trustworthy readiness gate for both workflow modes.
-3. `whc_deploy` for `git_deploy` triggers the real cPanel deployment task for a given `repository_root` and optional `branch`.
-4. `whc_deploy` does not yet execute the full `ssh_scp_wpcli` runtime pipeline; keep that in project-local scripts for now.
-
-## 3. Required Context Before Any Write
-
-Always collect these first:
-
-1. Active workflow mode.
-2. Target environment (`staging` or `live`).
-3. For `git_deploy`, identify the remote repository root and branch that should be deployed.
-4. For `ssh_scp_wpcli`, identify the local app root, staging SSH target, and runtime bootstrap path.
-5. Whether `dry_run` and `confirmed` are required by policy.
-
-## 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. Push local source to the cPanel-managed Git repository when credentials are available.
-4. Trigger deployment via `whc_deploy` for the intended `repository_root` and optional `branch`.
-5. Execute safe runtime probes and logs/health collection.
-6. Run source-compatibility checks and hidden-state bootstrap for a specific project root.
-
-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 claim a deploy was executed unless the handler actually changed remote state.
-2. Never promote live directly without staging verification.
-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. For `git_deploy`, run remote repository setup and local `git push`.
-5. For `ssh_scp_wpcli`, run the project-local doctor/SCP/WP-CLI pipeline.
-6. `whc_verify` to produce technical verify report.
-7. Run smoke checks outside or via allowed tool path.
-8. If staging passes, decide whether live release should proceed.
-
-For `ssh_scp_wpcli` projects, replace steps 4-7 with the project-local source pipeline:
-1. doctor
-2. backup
-3. SCP code sync
-4. WP-CLI runtime bootstrap
-5. seed/bootstrap
-6. smoke gate
-
-## 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 Usage Patterns
-
-### 6.1 `git_deploy`
-
-Use this mode when the real delivery path is:
-
-1. local Git repository
-2. push to cPanel-managed repository
-3. cPanel deployment task runs `.cpanel.yml`
-
-Agent expectations today:
-
-1. validate readiness with `check:generic`
-2. ensure remote repo exists with `whc_setup_remote`
-3. push with local Git
-4. trigger the cPanel deployment task with `whc_deploy`
-5. do not overstate this as WordPress runtime bootstrap; that still belongs to separate checks/scripts
-
-### 6.2 `ssh_scp_wpcli`
-
-Use this mode for `mytho/source` style delivery:
-
-1. doctor
-2. backup
-3. SCP code sync
-4. WP-CLI bootstrap
-5. seed/bootstrap
-6. smoke gate
-
-## 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 foundations:
-
-1. `git_deploy`
-   - repository-driven
-   - local `git push`
-   - cPanel deployment task
-   - `.cpanel.yml` at repo root
-2. `ssh_scp_wpcli`
-   - source-driven
-   - SCP file transfer
-   - remote WP-CLI runtime/bootstrap
-   - project-specific smoke gate
-
-Policy note:
-
-1. `ssh_scp_wpcli` is the correct default mindset for `mytho/source`.
-2. `git_deploy` should not be described as staging/live native sync.
-3. If a release note or operator guide mentions `managed_clone_sync`, treat that as stale wording and replace it.
-
-## 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 tool server process has reloaded after env edits.
-3. Avoid malformed quoting in key path values.
-
-### 8.2 Deploy contract confusion
-
-If users are mixing repository deploy with environment-sync wording:
-
-1. for `git_deploy`, think `repository_root`, `branch`, `.cpanel.yml`, and cPanel deployment task
-2. for `ssh_scp_wpcli`, think WordPress app root, `scp`, `wp`, and smoke checks
-3. do not describe either mode as native WHC staging/live clone sync
-
-## 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: `.whc/logs/flow-events.jsonl`
-2. Custom path (optional): set `WHC_FLOW_LOG_PATH` in env
-
-### 10.2 Read latest entries (PowerShell)
-
-```powershell
-Get-Content .whc/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 .whc/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: .whc/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 prepare
-```
-
-For npm-package workflows, call `whc_prepare` once from The tool server client after the server starts.
-
-This initializes hidden management paths automatically:
-1. `.whc/state/pipeline-status.json`
-2. `.whc/state/releases/`
-3. `.whc/state/reports/`
-4. `.whc/logs/`
-
-It also ensures `.whc/` is ignored by git.
-
-## 10.5 Automatic State Tracking
-
-For every write tool run, tool server now auto-updates:
-1. `.whc/state/pipeline-status.json` (started/completed/status/next step/error)
-2. `.whc/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/WHC_REQUIREMENTS.md

@@ -1,114 +0,0 @@
-# WHC.ca (cPanel) tool server Requirements
-
-## 1. Objective
-Build a specialized WHC tool server (stdio + CLI) 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 tool server 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:** tool server 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 tool server 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 tool 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/scripts/prepare-first-time.cjs

@@ -1,75 +0,0 @@
-const fs = require("node:fs");
-const path = require("node:path");
-
-function ensureDir(p) {
-  fs.mkdirSync(p, { recursive: true });
-}
-
-function ensureGitignoreRule(rootDir, rule) {
-  const gitignorePath = path.join(rootDir, ".gitignore");
-  if (!fs.existsSync(gitignorePath)) {
-    fs.writeFileSync(gitignorePath, `${rule}\n`, "utf8");
-    return;
-  }
-
-  const content = fs.readFileSync(gitignorePath, "utf8");
-  const hasRule = content.split(/\r?\n/).some((line) => line.trim() === rule);
-  if (hasRule) {
-    return;
-  }
-
-  const next = content.endsWith("\n") ? `${content}${rule}\n` : `${content}\n${rule}\n`;
-  fs.writeFileSync(gitignorePath, next, "utf8");
-}
-
-function ensureFileIfMissing(filePath, data) {
-  if (!fs.existsSync(filePath)) {
-    fs.writeFileSync(filePath, data, "utf8");
-  }
-}
-
-function resolveStateRoot(rootDir) {
-  const configured = (process.env.WHC_STATE_ROOT || "").trim();
-  const relative = configured.length > 0 ? configured : ".whc";
-  const segments = relative.split(/[\\/]+/).filter(Boolean);
-  return path.join(rootDir, ...segments);
-}
-
-function main() {
-  const rootDir = path.resolve(__dirname, "..");
-  const stateRoot = resolveStateRoot(rootDir);
-  const stateDir = path.join(stateRoot, "state");
-  const releasesDir = path.join(stateDir, "releases");
-  const reportsDir = path.join(stateDir, "reports");
-  const logsDir = path.join(stateRoot, "logs");
-  const envDir = path.join(stateRoot, "env");
-
-  ensureDir(stateRoot);
-  ensureDir(stateDir);
-  ensureDir(releasesDir);
-  ensureDir(reportsDir);
-  ensureDir(logsDir);
-  ensureDir(envDir);
-
-  ensureGitignoreRule(rootDir, ".whc/");
-
-  const statusFile = path.join(stateDir, "pipeline-status.json");
-  ensureFileIfMissing(
-    statusFile,
-    JSON.stringify(
-      {
-        started: false,
-        completed: false,
-        status: "idle",
-        next_step: "Run a write tool (deploy/setup/backup/ssh) to start tracking.",
-      },
-      null,
-      2,
-    ) + "\n",
-  );
-
-  console.log("[prepare-first-time] Initialized .whc hidden state and ensured .gitignore contains .whc/");
-  console.log(`[prepare-first-time] State file: ${statusFile}`);
-}
-
-main();