devops-whc 1.0.1 → 1.0.2-next

package/README.md

@@ -1,8 +1,8 @@
 # devops-whc
 
-WHC cPanel MCP server for deploy, verify, rollback, logs, backup, and health flows.
+WHC cPanel automation CLI for deploy, verify, rollback, logs, backup, and health flows.
 
-Current release: 1.0.1
+Current workspace version: 1.0.2-next
 
 ## Publish Package Layout
 
@@ -14,7 +14,7 @@ The repository root is the development workspace. The publish package is prepare
 
 ## 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.
+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:
 
@@ -40,34 +40,80 @@ Or install globally:
 
 ```powershell
 npm install -g devops-whc
-whc-mcp --help
+whc --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.
+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 MCP, point the server command to the published package or to the local `start-mcp.cjs` helper.
+If you are using VS Code Copilot, point the server command to the published package or to the local `start-whc.cjs` helper.
 
-## VS Code MCP Config
+## 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-mcp": {
+    "whc": {
       "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"
+        "WHC_STATE_ROOT": ".whc",
+        "WHC_INSTANCE_NAME": "whc"
       }
     }
   }
@@ -79,16 +125,16 @@ Local-source example:
 ```jsonc
 {
   "servers": {
-    "whc-mcp": {
+    "whc": {
       "type": "stdio",
       "command": "node",
-      "args": ["./scripts/start-mcp.cjs"],
+      "args": ["./scripts/start-whc.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"
+        "WHC_STATE_ROOT": ".whc",
+        "WHC_INSTANCE_NAME": "whc"
       }
     }
   }
@@ -98,11 +144,12 @@ Local-source example:
 ## CLI Commands
 
 ```powershell
-whc-mcp --serve
-whc-mcp --probe
-whc-mcp --check-health
-whc-mcp --help
-whc-mcp --version
+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`:
@@ -110,25 +157,51 @@ 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
 ```
 
-## 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`
+## 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`
+- `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`
@@ -137,7 +210,7 @@ Set these in your local `.env` file:
 - `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`
@@ -174,17 +247,71 @@ npx -y devops-whc --check-health
 
 Use this to inspect disk, SSL, load, and capability state.
 
-### 3) Start the MCP server in VS Code
+### 3) Run deploy readiness check (single command)
 
-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`.
+```powershell
+npx -y devops-whc --check-generic --project-root D:/Source/mytho/source/wordpress --workflow-mode ssh_scp_wpcli
+```
 
-### 4) Prepare workspace state once
+Or from local clone:
 
 ```powershell
-npm run mcp:prepare
+npm run check:generic -- D:/Source/mytho/source/wordpress
 ```
 
-This initializes the hidden project state under `.mcp/whc-mcp` and ensures the workspace ignores local management files.
+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
 
@@ -193,16 +320,58 @@ This initializes the hidden project state under `.mcp/whc-mcp` and ensures the w
 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
+## Release Prep
+
+Run these from repository root before publishing:
+
+```powershell
+npm run typecheck
+npm test
+npm run publish:prepare
+npm run pack:check
+```
+
+What each step does:
+
+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`.
+
+Publish only after the dry-run looks correct:
+
+```powershell
+npm run publish:npm
+```
+
+## NPM Auth
+
+Authenticate npm on this machine before the real publish:
+
+```powershell
+npm whoami
+npm login
+npm whoami
+```
+
+If your org uses browser-based auth, npm may open a web flow after `npm login`.
+
+Useful checks:
+
+```powershell
+npm config get registry
+npm access ls-packages
+```
+
+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.
 
-1. `npm run test`
-2. `npm run pack:check`
-3. `npm --prefix packages/devops-whc publish`
+## License
 
-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.
+ISC
 
-## License
 
-ISC

package/{WHC_MCP_REQUIREMENTS.md → WHC_REQUIREMENTS.md}

@@ -1,7 +1,7 @@
-# WHC.ca (cPanel) MCP Server Requirements
+# WHC.ca (cPanel) tool 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.
+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.
@@ -72,14 +72,14 @@ 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:
+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:** MCP SDK (@modelcontextprotocol/sdk).
+- **Framework:** tool server SDK (@modelcontextprotocol/sdk).
 - **Communication:** 
     - **cPanel UAPI:** Over HTTPS (Port 2083) using API Tokens.
     - **SSH:** Using `ssh2` or system SSH (Port 27).
@@ -88,7 +88,7 @@ These steps are not auto-solvable by MCP and must be prepared by operator:
 ## 5. Implementation Roadmap
 
 ### Phase 1: Foundation & Auth
-- [ ] Initialize MCP project.
+- [ ] Initialize tool server project.
 - [ ] Implement secure `.env` loading for `WHC_API_TOKEN`, `WHC_USER`, and `WHC_HOST`.
 - [ ] Test connectivity to cPanel API and SSH.
 
@@ -103,10 +103,12 @@ These steps are not auto-solvable by MCP and must be prepared by operator:
 - [ ] Add health check dashboard.
 
 ### Phase 4: Gemini CLI Integration
-- [ ] Register the MCP server in `gemini-config.json`.
+- [ ] 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/dist/config/env.js

@@ -13,10 +13,10 @@ 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_API_TOKEN: zod_1.z.string().min(1).optional(),
+    WHC_USER: zod_1.z.string().min(1).optional(),
+    WHC_HOST: zod_1.z.string().min(1).optional(),
+    WHC_WORKFLOW_MODE: zod_1.z.enum(["git_deploy", "ssh_scp_wpcli"]).default("ssh_scp_wpcli"),
     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(),
@@ -34,14 +34,10 @@ const envSchema = zod_1.z.object({
         .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_HOST: zod_1.z.string().min(1).optional(),
     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_PROD_SSH_USERNAME: zod_1.z.string().min(1).optional(),
+    WHC_PROD_SSH_PRIVATE_KEY_PATH: zod_1.z.string().min(1).optional(),
     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(),
@@ -64,7 +60,8 @@ const envSchema = zod_1.z.object({
     WHC_FLOW_LOG_PATH: zod_1.z.string().min(1).optional(),
 });
 function loadConfig(env = process.env) {
-    const parsed = envSchema.safeParse(env);
+    const normalizedEnv = Object.fromEntries(Object.entries(env).map(([key, value]) => [key, value === "" ? undefined : value]));
+    const parsed = envSchema.safeParse(normalizedEnv);
     if (!parsed.success) {
         const issues = parsed.error.issues
             .map((issue) => issue.path.join("."))
@@ -72,17 +69,46 @@ function loadConfig(env = process.env) {
         throw new Error(`VALIDATION_ERROR: Missing or invalid env vars: ${issues.join(", ")}`);
     }
     const data = parsed.data;
-    const prodSshHost = data.WHC_PROD_SSH_HOST;
+    const workflowMode = data.WHC_WORKFLOW_MODE;
+    const missingFields = [];
+    if (workflowMode === "git_deploy") {
+        for (const key of [
+            "WHC_API_TOKEN",
+            "WHC_USER",
+            "WHC_HOST",
+        ]) {
+            if (!(data[key] ?? "").trim()) {
+                missingFields.push(key);
+            }
+        }
+    }
+    else {
+        for (const key of [
+            "WHC_STAGING_SSH_HOST",
+            "WHC_STAGING_SSH_USERNAME",
+        ]) {
+            if (!(data[key] ?? "").trim()) {
+                missingFields.push(key);
+            }
+        }
+        if (!(data.WHC_STAGING_SSH_PRIVATE_KEY_PATH ?? "").trim() && !(data.WHC_STAGING_SSH_PASSWORD ?? "").trim()) {
+            missingFields.push("WHC_STAGING_SSH_PRIVATE_KEY_PATH|WHC_STAGING_SSH_PASSWORD");
+        }
+    }
+    if (missingFields.length > 0) {
+        throw new Error(`VALIDATION_ERROR: Missing or invalid env vars: ${missingFields.join(", ")}`);
+    }
+    const prodSshHost = data.WHC_PROD_SSH_HOST ?? data.WHC_HOST ?? data.WHC_STAGING_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 prodSshUsername = data.WHC_PROD_SSH_USERNAME ?? data.WHC_USER ?? data.WHC_STAGING_SSH_USERNAME ?? "";
+    const prodSshPrivateKeyPath = data.WHC_PROD_SSH_PRIVATE_KEY_PATH ?? data.WHC_STAGING_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,
+        apiToken: data.WHC_API_TOKEN ?? "",
+        user: data.WHC_USER ?? "",
+        host: data.WHC_HOST ?? "",
+        apiBaseUrl: data.WHC_HOST ? `https://${data.WHC_HOST}:2083` : "",
+        workflowMode,
         domains: {
             primary: data.WHC_PRIMARY_DOMAIN,
             testing: data.WHC_TESTING_DOMAIN,
@@ -105,7 +131,6 @@ function loadConfig(env = process.env) {
             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: {

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

@@ -26,7 +26,6 @@ async function executeWhcDbBackup(config, request, deps = {}) {
     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(),