@webship.co/workspace-cpanel 0.0.0-stage → 1.0.0-alpha1

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# @webship.co/workspace-cpanel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+cPanel for the [Webship Workspace](https://github.com/webship/workspace) dashboard: the **CPANEL**
+menu on every site row, a live-site chip on the project card, "Link to cPanel" when a new folder is
+made, and the `cmd-tools-cpanel.sh` command in every site workspace. A provider of
+[`@webship.co/workspace-hosting`](https://github.com/webship/workspace-hosting), which draws the menu,
+the environments modal, the get-database-and-files flow and the New-folder section for every host.
+
+cPanel has no CLI of its own, so the dashboard talks to the UAPI over HTTPS (port 2083) with an API token per account, and the pulls, the deploy and the log go over SSH (`ssh`, `rsync`, `drush sql:dump` in the remote docroot). The link is `user@host:/home/user/public_html`; the environments are the account's domains, each a live site.
+
+## Use it
+
+```bash
+cd ~/workspace
+bash core/scripts/plugins.sh --require github:webship/workspace-cpanel
+bash core/scripts/plugins.sh --activate cpanel
+bash core/scripts/plugins.sh --install cpanel
+bash core/scripts/plugins.sh --configure cpanel      # core/config/plugin.cpanel.settings.yml
+```
+
+The same four steps are buttons on the dashboard's **Settings → Plugins** page.
+
+## The command
+
+```bash
+cd ~/workspace/dev
+bash cmd-tools-cpanel.sh <project> [verb]
+```
+
+| Verb | What it does |
+| --- | --- |
+| `--link` <value> | Link the project to a cPanel account and site: user@host:/remote/docroot (the account user, the server host, the site's document root on it). |
+| `--push` | Deploy: rsync the local docroot to the remote document root (excludes sites/default/files, settings.php, .git, .ddev; deletes what is gone locally). Outward-facing: asks before syncing. |
+| `--environment` <value> | The domain for THIS run (an account can serve several). Default: the one remembered by --select. |
+| `--environments` | List the account's domains (UAPI DomainInfo::list_domains) and disk usage. |
+| `--select` <value> | Remember which domain this project works against (in .cpanel/workspace.yml, git-excluded). Checked against the account's domains. |
+| `--pull-db` | Dump the site's database over SSH (drush sql:dump in the remote docroot) and import it into DDEV. REPLACES the local database — the current one is exported to backups/ first. Client data. |
+| `--pull-files` | rsync the remote sites/default/files into the local docroot (adds and overwrites, never deletes). Client data. |
+| `--logs` | Show the last 50 lines of the site's error_log over SSH. |
+| `--no-safety-backup` | Skip exporting the local database before --pull-db replaces it. |
+| `--force` | Allow --link to relink a project that already points at a different account. |
+
+The link lives in the project's `.cpanel/workspace.yml` (git-excluded); the dashboard reads it to know
+the project is linked and which environment it works against.
+
+## What the package holds
+
+| Path | What it is |
+| --- | --- |
+| `src/index.ts` | `register(api)`: `registerHosting(api, cpanelProvider(api))` |
+| `src/lib/provider.ts` | The cPanel provider: the credentials, the environments and their URLs, the verbs, the pulls, the console |
+| `src/lib/link.ts` | The link file reader |
+| `commands/cmd-tools-cpanel.sh` | The per-workspace command |
+| `scripts/functions/fun-cpanel.sh` | The provider's bash hooks (its API) |
+| `scripts/functions/fun-cpanel-tool.sh` | The family's dispatcher: link file, environment selection, safety export, status |
+| `scripts/args/arg-cpanel.sh` | Its argparse |
+| `scripts/host-install.sh` | The host side: the CLI and the credential check |
+| `config/plugin.cpanel.settings.yml` | The settings template |
+
+The `workspacePlugin` block in `package.json` is the manifest the installer reads.

package/commands/cmd-tools-cpanel.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+# Installed by the cPanel plugin (plugins.sh --install cpanel); __WORKSPACE__ is the workspace it was installed into.
+#
+# The local ⇄ cloud bridge for one project on cPanel: show its link and environments, link it,
+# bring a database and files down into DDEV, deploy, read logs.
+
+# Bootstrap.
+# Find the workspace tooling from this script, so a fresh clone needs no setup.
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
+source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
+
+# Load workspace settings and extra lists.
+eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.__WORKSPACE__.settings.yml);
+
+ARGPARSE_DESCRIPTION="Show, link, pull from or deploy a __WORKSPACE__ project on cPanel"
+# The args file comes with the plugin: core/scripts/plugins/cpanel/ is where plugins.sh --install puts it.
+source ${WORKSPACE_SCRIPTS}/plugins/cpanel/args/arg-cpanel.sh || exit 1 ;
+
+shift $#;
+
+cpanel_project_tool ;

package/config/plugin.cpanel.settings.yml

@@ -0,0 +1,9 @@
+# cPanel — core/config/plugin.cpanel.settings.yml
+#
+# How the dashboard reaches cPanel accounts: the UAPI over HTTPS with an API token (cPanel → Security → Manage API Tokens), one token per account. Which account a project belongs to is in its link (host and user); the token for that account is looked up here by user.
+# A map of cPanel user → API token (cPanel → Security → Manage API Tokens), one per account the dashboard lists domains for. Example: {webshipco: XXXX}. Injected only into cPanel jobs, never printed.
+api_tokens:
+  # webshipco: CHANGE_ME
+  CHANGE_ME_USER: CHANGE_ME
+# The private key the pulls and deploys use to reach the accounts over SSH (authorized in cPanel → Security → SSH Access). Default: ~/.ssh/id_ed25519.
+ssh_key: ~/.ssh/id_ed25519

package/config/settings.labels.yml

@@ -0,0 +1,7 @@
+# Labels for core/config/plugin.cpanel.settings.yml, merged into the Settings page.
+api_tokens:
+  label: cPanel API tokens by user
+  info: 'A map of cPanel user → API token (cPanel → Security → Manage API Tokens), one per account the dashboard lists domains for. Example: a nested map, one user per line. Injected only into cPanel jobs, never printed.'
+ssh_key:
+  label: SSH key for the pulls
+  info: 'The private key the pulls and deploys use to reach the accounts over SSH (authorized in cPanel → Security → SSH Access). Default: ~/.ssh/id_ed25519.'

package/dist/src/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * cPanel for Webship Workspace.
+ *
+ * The CPANEL menu on every site row, a live-site chip, the New-folder link option and the
+ * `/cpanel-site/<workspace>/<project>` jump: all of it is the hosting family's surface
+ * (@webship.co/workspace-hosting). This package is the cPanel provider plus what the installer places
+ * (the per-workspace command, its bash functions, the settings template, the host install).
+ *
+ * Everything the dashboard is asked for goes through `api`; this package requires nothing from
+ * the dashboard's own files.
+ */
+import type { PluginApi } from '@webship.co/workspace-plugin-api';
+import { cpanelProvider } from './lib/provider';
+export { cpanelProvider };
+export { cpanelLinkOf } from './lib/link';
+export declare function register(api: PluginApi): void;

package/dist/src/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * cPanel for Webship Workspace.
+ *
+ * The CPANEL menu on every site row, a live-site chip, the New-folder link option and the
+ * `/cpanel-site/<workspace>/<project>` jump: all of it is the hosting family's surface
+ * (@webship.co/workspace-hosting). This package is the cPanel provider plus what the installer places
+ * (the per-workspace command, its bash functions, the settings template, the host install).
+ *
+ * Everything the dashboard is asked for goes through `api`; this package requires nothing from
+ * the dashboard's own files.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cpanelLinkOf = exports.cpanelProvider = void 0;
+exports.register = register;
+const workspace_hosting_1 = require("@webship.co/workspace-hosting");
+const provider_1 = require("./lib/provider");
+Object.defineProperty(exports, "cpanelProvider", { enumerable: true, get: function () { return provider_1.cpanelProvider; } });
+var link_1 = require("./lib/link");
+Object.defineProperty(exports, "cpanelLinkOf", { enumerable: true, get: function () { return link_1.cpanelLinkOf; } });
+function register(api) {
+    (0, workspace_hosting_1.registerHosting)(api, (0, provider_1.cpanelProvider)(api));
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAUH,4BAEC;AATD,qEAAgE;AAEhE,6CAAgD;AAEvC,+FAFA,yBAAc,OAEA;AACvB,mCAA0C;AAAjC,oGAAA,YAAY,OAAA;AAErB,SAAgB,QAAQ,CAAC,GAAc;IACrC,IAAA,mCAAe,EAAC,GAAG,EAAE,IAAA,yBAAc,EAAC,GAAG,CAAC,CAAC,CAAC;AAC5C,CAAC"}

package/dist/src/lib/link.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether a project is linked to cPanel, and to what: the `.cpanel/workspace.yml` file that
+ * `cmd-tools-cpanel.sh --link` writes (git-excluded), plus the branch the local code is on.
+ */
+import type { HostingLink } from '@webship.co/workspace-hosting';
+export interface cPanelLink extends HostingLink {
+    /** Every key of the link file, for the provider's own needs (region, resource group, host…). */
+    fields: Record<string, string>;
+}
+export declare function readLinkFile(projectDir: string): Record<string, string> | null;
+export declare function cpanelLinkOf(projectDir: string): cPanelLink | null;

package/dist/src/lib/link.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Whether a project is linked to cPanel, and to what: the `.cpanel/workspace.yml` file that
+ * `cmd-tools-cpanel.sh --link` writes (git-excluded), plus the branch the local code is on.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readLinkFile = readLinkFile;
+exports.cpanelLinkOf = cpanelLinkOf;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function readLinkFile(projectDir) {
+    let text;
+    try {
+        text = fs_1.default.readFileSync(path_1.default.join(projectDir, '.cpanel', 'workspace.yml'), 'utf8');
+    }
+    catch (_) {
+        return null;
+    }
+    const fields = {};
+    for (const line of text.split('\n')) {
+        const m = line.match(/^([a-z_]+):\s*(.*?)\s*$/);
+        if (m)
+            fields[m[1]] = m[2].replace(/^["']|["']$/g, '');
+    }
+    return fields;
+}
+function cpanelLinkOf(projectDir) {
+    const fields = readLinkFile(projectDir);
+    if (!fields || !fields.id)
+        return null;
+    let branch = null;
+    try {
+        const head = fs_1.default.readFileSync(path_1.default.join(projectDir, '.git', 'HEAD'), 'utf8').trim();
+        branch = (head.match(/^ref: refs\/heads\/(.+)$/) || [])[1] || null;
+    }
+    catch (_) { /* not a git clone */ }
+    return { id: fields.id, env: fields.env || null, branch, fields };
+}
+//# sourceMappingURL=link.js.map

package/dist/src/lib/link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.js","sourceRoot":"","sources":["../../../src/lib/link.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;AAWH,oCASC;AAED,oCASC;AA7BD,4CAAoB;AACpB,gDAAwB;AAQxB,SAAgB,YAAY,CAAC,UAAkB;IAC7C,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QAAC,IAAI,GAAG,YAAE,CAAC,YAAY,CAAC,cAAI,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC;IAAC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QAAC,OAAO,IAAI,CAAC;IAAC,CAAC;IACrH,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAChD,IAAI,CAAC;YAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAgB,YAAY,CAAC,UAAkB;IAC7C,MAAM,MAAM,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAE,CAAC,YAAY,CAAC,cAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QACnF,MAAM,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,0BAA0B,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IACrE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,CAAC,qBAAqB,CAAC,CAAC;IACrC,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AACpE,CAAC"}

package/dist/src/lib/provider.d.ts

@@ -0,0 +1,10 @@
+/**
+ * cPanel, as a hosting provider.
+ *
+ * The link is `.cpanel/workspace.yml` (user, host, remote docroot); the account's domains come from
+ * the UAPI over HTTPS with the account's API token from plugin.cpanel.settings.yml; the pulls, the
+ * deploy and the log go over SSH through cmd-tools-cpanel.sh in a screen session.
+ */
+import type { PluginApi } from '@webship.co/workspace-plugin-api';
+import type { HostingProvider } from '@webship.co/workspace-hosting';
+export declare function cpanelProvider(api: PluginApi): HostingProvider;

package/dist/src/lib/provider.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * cPanel, as a hosting provider.
+ *
+ * The link is `.cpanel/workspace.yml` (user, host, remote docroot); the account's domains come from
+ * the UAPI over HTTPS with the account's API token from plugin.cpanel.settings.yml; the pulls, the
+ * deploy and the log go over SSH through cmd-tools-cpanel.sh in a screen session.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cpanelProvider = cpanelProvider;
+const workspace_hosting_1 = require("@webship.co/workspace-hosting");
+const link_1 = require("./link");
+function cpanelProvider(api) {
+    const settings = () => api.settings.read() || {};
+    /** The token of one account: `api_tokens` is a map by user. */
+    const tokenFor = (user) => {
+        const map = settings().api_tokens;
+        if (map && typeof map === 'object')
+            return (0, workspace_hosting_1.configured)(map[user]);
+        return null;
+    };
+    const jobEnv = () => {
+        const map = settings().api_tokens;
+        const any = map && typeof map === 'object' && Object.values(map).some((v) => (0, workspace_hosting_1.configured)(v));
+        return any ? { ...process.env, CPANEL_API_TOKENS: JSON.stringify(map), CPANEL_SSH_KEY: String(settings().ssh_key || '~/.ssh/id_ed25519') } : null;
+    };
+    async function environments(link, lib, env) {
+        const fields = link.fields || {};
+        const user = fields.user;
+        const host = fields.host;
+        const id = link.id;
+        const token = user ? tokenFor(user) : null;
+        if (!token)
+            return { id, rows: [], why: `no token for ${user || 'the account'}` };
+        const out = await lib.run('curl', ['-sS', '-k', '-m', '30', '-H', `Authorization: cpanel ${user}:${token}`, `https://${host}:2083/execute/DomainInfo/list_domains`], process.env.HOME, { timeoutMs: 40 * 1000, env });
+        if (!out.ok)
+            return { id, rows: [], why: 'list failed' };
+        let data;
+        try {
+            data = JSON.parse(String(out.stdout)).data || {};
+        }
+        catch (_) {
+            return { id, rows: [], why: 'list failed' };
+        }
+        const rows = [];
+        if (data.main_domain)
+            rows.push({ title: `${data.main_domain} (main)`, envId: data.main_domain, status: 'active', url: `https://${data.main_domain}` });
+        for (const d of [...(data.addon_domains || []), ...(data.sub_domains || [])])
+            rows.push({ title: d, envId: d, status: 'active', url: `https://${d}` });
+        for (const d of data.parked_domains || [])
+            rows.push({ title: `${d} (alias)`, envId: d, status: 'alias' });
+        return { id, rows };
+    }
+    return {
+        id: 'cpanel',
+        label: 'CPANEL',
+        title: 'cPanel',
+        script: 'cmd-tools-cpanel.sh',
+        detect: (projectDir) => (0, link_1.cpanelLinkOf)(projectDir),
+        linkHint: (project) => `bash cmd-tools-cpanel.sh ${project} --link user@host:/home/user/public_html`,
+        consoleUrl: (link) => { const h = link.fields && link.fields.host; return h ? `https://${h}:2083/` : null; },
+        jobEnv,
+        tokenHint: 'api_tokens (by cPanel user) in core/config/plugin.cpanel.settings.yml',
+        environments,
+        tools: {
+            status: { verb: 'cpanel', label: 'Link and domains', icon: 'info', args: [] },
+            logs: { verb: 'cpanel-logs', label: 'Last 50 lines of error_log', icon: 'file-text', args: ['--logs'] },
+            deploy: { verb: 'cpanel-push', label: 'Deploy with rsync…', icon: 'push', args: ['--push'] },
+        },
+        pull: {
+            db: true, files: true,
+            dbArgs: (e) => ['--environment', e, '--pull-db'],
+            filesArgs: (e) => ['--environment', e, '--pull-files'],
+            noSafetyBackupArg: '--no-safety-backup',
+        },
+        folder: {
+            idPattern: /^[a-z0-9_.-]+@[a-z0-9.-]+:\/.+$/i,
+            idPlaceholder: 'webshipco@server.example.com:/home/webshipco/public_html',
+            idHelp: 'A cPanel link is user@host:/remote/docroot — the account user, the server, and the site\'s document root on it.',
+        },
+        menuNote: 'The pulls, the deploy and the log go over SSH with the key in the settings; the API token only lists domains',
+    };
+}
+//# sourceMappingURL=provider.js.map

package/dist/src/lib/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../../src/lib/provider.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAQH,wCA+DC;AApED,qEAA2D;AAG3D,iCAAsC;AAEtC,SAAgB,cAAc,CAAC,GAAc;IAC3C,MAAM,QAAQ,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;IAEjD,+DAA+D;IAC/D,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAiB,EAAE;QAC/C,MAAM,GAAG,GAAG,QAAQ,EAAE,CAAC,UAAU,CAAC;QAClC,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,IAAA,8BAAU,EAAE,GAA+B,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9F,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,MAAM,MAAM,GAAG,GAA6B,EAAE;QAC5C,MAAM,GAAG,GAAG,QAAQ,EAAE,CAAC,UAAU,CAAC;QAClC,MAAM,GAAG,GAAG,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,GAA8B,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAA,8BAAU,EAAC,CAAC,CAAC,CAAC,CAAC;QACvH,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,iBAAiB,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,OAAO,IAAI,mBAAmB,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACpJ,CAAC,CAAC;IAEF,KAAK,UAAU,YAAY,CAAC,IAAiB,EAAE,GAAc,EAAE,GAAsB;QACnF,MAAM,MAAM,GAAI,IAAY,CAAC,MAAM,IAAI,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QAAC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACnD,MAAM,EAAE,GAAG,IAAI,CAAC,EAAY,CAAC;QAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC3C,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,gBAAgB,IAAI,IAAI,aAAa,EAAE,EAAE,CAAC;QAClF,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,yBAAyB,IAAI,IAAI,KAAK,EAAE,EAAE,WAAW,IAAI,uCAAuC,CAAC,EACjK,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;QACnD,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC;QACzD,IAAI,IAAS,CAAC;QACd,IAAI,CAAC;YAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;QAAC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YAAC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC;QAAC,CAAC;QACpH,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,IAAI,IAAI,CAAC,WAAW;YAAE,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,WAAW,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QACxJ,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC,CAAC;QACvJ,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,cAAc,IAAI,EAAE;YAAE,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;QAC3G,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IAED,OAAO;QACL,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,QAAQ;QACf,KAAK,EAAE,QAAQ;QACf,MAAM,EAAE,qBAAqB;QAC7B,MAAM,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,IAAA,mBAAY,EAAC,UAAU,CAAC;QAChD,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,4BAA4B,OAAO,0CAA0C;QACpG,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,GAAG,MAAM,CAAC,GAAI,IAAY,CAAC,MAAM,IAAK,IAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9H,MAAM;QACN,SAAS,EAAE,uEAAuE;QAClF,YAAY;QACZ,KAAK,EAAE;YACL,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE;YAC7E,IAAI,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,4BAA4B,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,QAAQ,CAAC,EAAE;YACvG,MAAM,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,QAAQ,CAAC,EAAE;SAC7F;QACD,IAAI,EAAE;YACJ,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI;YACrB,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,eAAe,EAAE,CAAC,EAAE,WAAW,CAAC;YAChD,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,eAAe,EAAE,CAAC,EAAE,cAAc,CAAC;YACtD,iBAAiB,EAAE,oBAAoB;SACxC;QACD,MAAM,EAAE;YACN,SAAS,EAAE,kCAAkC;YAC7C,aAAa,EAAE,0DAA0D;YACzE,MAAM,EAAE,iHAAiH;SAC1H;QACD,QAAQ,EAAE,8GAA8G;KACzH,CAAC;AACJ,CAAC"}

package/features/cpanel.feature

@@ -0,0 +1,20 @@
+Feature: The cPanel plugin on a project row
+  Once the plugin is activated and installed, every site row carries the CPANEL menu, and the Plugins
+  page lists the plugin with its four steps.
+
+  Scenario: A site row offers the CPANEL menu, captioned with its link state
+    Given I am on "/dev"
+     Then the element ".act-menu-cpanel" should be displayed
+      And I should see "CPANEL"
+      And the element ".act-menu-cpanel + .act-status" should be displayed
+
+  Scenario: An unlinked project's menu opens and says how to link it
+    Given I am on "/dev"
+      And I click on the element ".project-row .act-menu-cpanel button"
+     Then ".uk-dropdown.uk-open" should be visible
+      And I should see "Not linked to cPanel"
+
+  Scenario: The plugin is listed on the Plugins page
+    Given I am on "/settings/plugins"
+     Then I should see "cPanel"
+      And I should see "@webship.co/workspace-cpanel"

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@webship.co/workspace-cpanel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-alpha1",
+  "description": "cPanel hosting for Webship Workspace: the CPANEL menu on every site row, the account's domains as live sites, get database and files over SSH, deploy with rsync, the error log, the cPanel console. A provider of @webship.co/workspace-hosting.",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/webship/workspace-cpanel.git"
+  },
+  "files": [
+    "dist/src",
+    "commands",
+    "config",
+    "features",
+    "scripts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "test": "npm run build && node --test dist/tests/*.test.js",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  },
+  "workspacePlugin": {
+    "name": "cpanel",
+    "label": "cPanel",
+    "settingsFile": "plugin.cpanel.settings.yml",
+    "settingsTemplate": "config/plugin.cpanel.settings.yml",
+    "labels": "config/settings.labels.yml",
+    "legacySettingsKey": "cpanel",
+    "typeActions": {
+      "cpanel": [
+        "sites"
+      ]
+    },
+    "commands": {
+      "types": [
+        "sites"
+      ],
+      "workspaces": [
+        "dev",
+        "test",
+        "demos",
+        "sandboxes",
+        "projects"
+      ],
+      "files": [
+        "commands/cmd-tools-cpanel.sh"
+      ]
+    },
+    "scripts": {
+      "functions": [
+        "scripts/functions/fun-cpanel.sh",
+        "scripts/functions/fun-cpanel-tool.sh"
+      ],
+      "args": [
+        "scripts/args/arg-cpanel.sh"
+      ],
+      "hostInstall": "scripts/host-install.sh"
+    },
+    "features": [
+      "features/cpanel.feature"
+    ]
+  },
+  "dependencies": {
+    "@webship.co/workspace-hosting": "^1.0.0-alpha1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@webship.co/workspace-plugin-api": "^1.0.0-alpha1",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/args/arg-cpanel.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+parser.add_argument('PROJECT_NAME',
+                    help='The project directory in this workspace.')
+parser.add_argument('-l', '--link',
+                    default="_none_",
+                    help='Link the project to a cPanel account and site: user@host:/remote/docroot (the account user, the server host, the site's document root on it).')
+parser.add_argument('-p', '--push',
+                    action='store_true',
+                    default=False,
+                    help='Deploy: rsync the local docroot to the remote document root (excludes sites/default/files, settings.php, .git, .ddev; deletes what is gone locally). Outward-facing: asks before syncing.')
+parser.add_argument('-e', '--environment',
+                    default="_none_",
+                    help='The domain for THIS run (an account can serve several). Default: the one remembered by --select.')
+parser.add_argument('-E', '--environments',
+                    action='store_true',
+                    default=False,
+                    help='List the account's domains (UAPI DomainInfo::list_domains) and disk usage.')
+parser.add_argument('-s', '--select',
+                    default="_none_",
+                    help='Remember which domain this project works against (in .cpanel/workspace.yml, git-excluded). Checked against the account's domains.')
+parser.add_argument('-D', '--pull-db',
+                    action='store_true',
+                    default=False,
+                    help='Dump the site's database over SSH (drush sql:dump in the remote docroot) and import it into DDEV. REPLACES the local database — the current one is exported to backups/ first. Client data.')
+parser.add_argument('-F', '--pull-files',
+                    action='store_true',
+                    default=False,
+                    help='rsync the remote sites/default/files into the local docroot (adds and overwrites, never deletes). Client data.')
+parser.add_argument('-g', '--logs',
+                    action='store_true',
+                    default=False,
+                    help='Show the last 50 lines of the site's error_log over SSH.')
+parser.add_argument('-B', '--no-safety-backup',
+                    action='store_true',
+                    default=False,
+                    help='Skip exporting the local database before --pull-db replaces it.')
+parser.add_argument('-f', '--force',
+                    action='store_true',
+                    default=False,
+                    help='Allow --link to relink a project that already points at a different account.')
+ARGEOF

package/scripts/functions/fun-cpanel-tool.sh

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+
+# The cPanel tool's dispatcher: generated by the hosting family's scaffolder, the same for every
+# provider. The provider's own hooks live in fun-cpanel.sh:
+#   ensure_cpanel                              the CLI and credentials are usable, or say how
+#   cpanel_do_link <project_path> <id>         link the project (writes the link file through cpanel_link_set)
+#   cpanel_list_environments <id>              one environment id per line (for --select's check)
+#   cpanel_do_environments <id>                print the environments for a person
+#   cpanel_pull_db <project_path> <id> <env>   dump the environment's database to stdout path given in $1… (see fun-cpanel.sh)
+#   cpanel_pull_files <project_path> <id> <env>
+#   cpanel_do_push <project_path> <id> <env>   deploy
+#   cpanel_do_logs <project_path> <id> <env>
+#   cpanel_do_activities <project_path> <id>
+#   cpanel_status <project_path> <id>          the closing status block
+
+CPANEL_LINK_FILE=".cpanel/workspace.yml";
+
+# One key of the link file, or nothing.
+function cpanel_link_get() {
+  local project_path="$1" key="$2";
+  [ -f "${project_path}/${CPANEL_LINK_FILE}" ] || return 0 ;
+  grep -E "^${key}:" "${project_path}/${CPANEL_LINK_FILE}" | head -1 | sed -E 's/^[a-z_]+:[[:space:]]*//; s/^"//; s/"$//' ;
+}
+
+# Set one key of the link file, creating it (git-excluded: it is this machine's, not the repo's).
+function cpanel_link_set() {
+  local project_path="$1" key="$2" value="$3" file;
+  file="${project_path}/${CPANEL_LINK_FILE}";
+  mkdir -p "$(dirname "${file}")" ;
+  touch "${file}" ;
+  if grep -qE "^${key}:" "${file}" ; then
+    sed -i -E "s|^${key}:.*|${key}: ${value}|" "${file}" ;
+  else
+    printf '%s: %s\n' "${key}" "${value}" >> "${file}" ;
+  fi
+  if [ -d "${project_path}/.git" ] && ! grep -qx "/.cpanel/" "${project_path}/.git/info/exclude" 2>/dev/null ; then
+    mkdir -p "${project_path}/.git/info" && printf '/.cpanel/\n' >> "${project_path}/.git/info/exclude" ;
+  fi
+}
+
+function cpanel_linked_id() { cpanel_link_get "$1" id ; }
+function cpanel_selected_env() { cpanel_link_get "$1" env ; }
+
+# Which environment a run acts on: --environment for this run, else the remembered selection, else
+# nothing. Deliberately NOT defaulting to production: pulling live data because nobody said
+# otherwise is exactly the accident worth preventing.
+function cpanel_target_env() {
+  if [ ! "${ENVIRONMENT:-_none_}" == '_none_' ] ; then printf '%s' "${ENVIRONMENT}"; return 0 ; fi
+  cpanel_selected_env "$1";
+}
+
+# Where this project serves from: Drupal's two conventions, plus the flat case.
+function cpanel_docroot() {
+  for candidate in web docroot ; do
+    [ -d "$1/${candidate}" ] && { printf '%s' "${candidate}"; return 0 ; }
+  done
+  printf '%s' "";
+}
+
+# The local database is replaced by a pull, so it is exported first unless --no-safety-backup.
+function cpanel_safety_export() {
+  local project_path="$1" safety="$2";
+  if [ "${NO_SAFETY_BACKUP:-no}" == 'yes' ] ; then
+    echo "Skipping the local database export, as asked. The current local data will be lost.";
+  else
+    echo "Exporting the current local database first.";
+    (cd "${project_path}" && ddev export-db --file="${safety}") \
+      || echo "  (no local database to export yet — continuing)";
+  fi
+}
+
+function cpanel_import_dump() {
+  local project_path="$1" dump="$2";
+  echo "Importing it into DDEV.";
+  (cd "${project_path}" && ddev start -y > /dev/null && ddev import-db --file="${dump}") || return 1 ;
+  echo "  Drupal sites usually need: ddev drush updb -y && ddev drush cr";
+}
+
+function cpanel_project_tool() {
+  local project_path="${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME}";
+  local linked_id="";
+
+  if [ ! -d "${project_path}" ]; then
+    echo "No such project: ${project_path}";
+    return 1 ;
+  fi
+  cd "${project_path}" ;
+  linked_id="$(cpanel_linked_id "${project_path}")" ;
+
+  if [ ! "${LINK:-_none_}" == '_none_' ] ; then
+    ensure_cpanel || return 1 ;
+    if [ -n "${linked_id}" ] && [ ! "${linked_id}" == "${LINK}" ] && [ ! "${FORCE:-no}" == 'yes' ] ; then
+      echo "${doc_name}/${PROJECT_NAME} is already linked to cPanel ${linked_id}." ;
+      echo "Re-run with --force to relink it to ${LINK}." ;
+      return 1 ;
+    fi
+    cpanel_do_link "${project_path}" "${LINK}" || return 1 ;
+    linked_id="$(cpanel_linked_id "${project_path}")" ;
+    echo "Linked ${doc_name}/${PROJECT_NAME} → ${linked_id}." ;
+  fi
+
+  local needs_link="";
+  for flag in "${ENVIRONMENTS:-no}" "${PULL_DB:-no}" "${PULL_FILES:-no}" "${PUSH:-no}" "${LOGS:-no}" "${ACTIVITIES:-no}" ; do
+    [ "${flag}" == 'yes' ] && needs_link=yes ;
+  done
+  [ ! "${SELECT:-_none_}" == '_none_' ] && needs_link=yes ;
+  if [ -n "${needs_link}" ] ; then
+    if [ -z "${linked_id}" ] ; then
+      echo "Not linked to cPanel — run with --link <id> first." ;
+      return 1 ;
+    fi
+    ensure_cpanel || return 1 ;
+  fi
+
+  if [ "${ENVIRONMENTS:-no}" == 'yes' ] ; then
+    cpanel_do_environments "${project_path}" "${linked_id}" || return 1 ;
+    echo "";
+    echo "  Select one:  bash cmd-tools-cpanel.sh ${PROJECT_NAME} --select <environment>";
+  fi
+
+  if [ ! "${SELECT:-_none_}" == '_none_' ] ; then
+    # Checked against the real list rather than taken on trust: a typo would otherwise be
+    # discovered by a pull that dumps the wrong environment, or none.
+    if ! cpanel_list_environments "${project_path}" "${linked_id}" 2>/dev/null | grep -qx "${SELECT}" ; then
+      echo "cPanel ${linked_id} has no environment called '${SELECT}'." ;
+      echo "  List them: bash cmd-tools-cpanel.sh ${PROJECT_NAME} --environments" ;
+      return 1 ;
+    fi
+    cpanel_link_set "${project_path}" env "${SELECT}" ;
+    echo "${doc_name}/${PROJECT_NAME} now works against the ${SELECT} environment." ;
+  fi
+
+  if [ "${PULL_DB:-no}" == 'yes' ] || [ "${PULL_FILES:-no}" == 'yes' ] || [ "${PUSH:-no}" == 'yes' ] ; then
+    local target_env;
+    target_env="$(cpanel_target_env "${project_path}")";
+    if [ -z "${target_env}" ] ; then
+      echo "No environment selected. Pick one first — a pull or a deploy must never guess which environment it targets:" ;
+      echo "  bash cmd-tools-cpanel.sh ${PROJECT_NAME} --environments" ;
+      echo "  bash cmd-tools-cpanel.sh ${PROJECT_NAME} --select <environment>" ;
+      echo "  (or name it for this run: --environment <environment>)" ;
+      return 1 ;
+    fi
+    [ "${PULL_DB:-no}" == 'yes' ] && { cpanel_pull_db "${project_path}" "${linked_id}" "${target_env}" || return 1 ; }
+    [ "${PULL_FILES:-no}" == 'yes' ] && { cpanel_pull_files "${project_path}" "${linked_id}" "${target_env}" || return 1 ; }
+    [ "${PUSH:-no}" == 'yes' ] && { cpanel_do_push "${project_path}" "${linked_id}" "${target_env}" || return 1 ; }
+  fi
+
+  if [ "${LOGS:-no}" == 'yes' ] ; then
+    cpanel_do_logs "${project_path}" "${linked_id}" "$(cpanel_target_env "${project_path}")" || true ;
+  fi
+  if [ "${ACTIVITIES:-no}" == 'yes' ] ; then
+    cpanel_do_activities "${project_path}" "${linked_id}" || true ;
+  fi
+
+  # Default (and after any verb): status.
+  echo "";
+  echo "*---------------------------------------------------------------------*";
+  echo "  ${doc_name}/${PROJECT_NAME} on cPanel";
+  if [ -z "${linked_id}" ]; then
+    echo "    not linked. Link it with:";
+    echo "      bash cmd-tools-cpanel.sh ${PROJECT_NAME} --link <id>";
+    cpanel_status "${project_path}" "" ;
+  else
+    echo "    linked:  ${linked_id}";
+    local selected;
+    selected="$(cpanel_selected_env "${project_path}")";
+    echo "    env:     ${selected:-none selected — --environments then --select <name>}";
+    cpanel_status "${project_path}" "${linked_id}" ;
+  fi
+  echo "*---------------------------------------------------------------------*";
+
+  cd "${WORKSPACE_ROOT}/${doc_name}";
+}

package/scripts/functions/fun-cpanel.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+
+# cPanel accounts: the UAPI over HTTPS (port 2083, an API token per account) for the domains, and
+# SSH for everything that touches the site (the database dump, the files, the deploy, the log). The
+# hooks the hosting dispatcher (fun-cpanel-tool.sh) calls for one project directory. Everything
+# defaults to read-only; --link, --push, --pull-db and --pull-files each demand their flag.
+
+# The dashboard passes the tokens map as CPANEL_API_TOKENS (JSON by user) and the key as
+# CPANEL_SSH_KEY; on the host they come from core/config/plugin.cpanel.settings.yml.
+function cpanel_token_for() {
+  local user="$1";
+  if [ -n "${CPANEL_API_TOKENS:-}" ] ; then
+    printf '%s' "${CPANEL_API_TOKENS}" | python3 -c 'import json,sys; print(json.load(sys.stdin).get(sys.argv[1],""))' "${user}" 2>/dev/null ;
+  else
+    # Either `api_tokens: {user: token}` on one line or a nested map under `api_tokens:`.
+    python3 - "${WORKSPACE_CONFIG}/plugin.cpanel.settings.yml" "${user}" <<'PY' 2>/dev/null
+import re,sys,io
+s=io.open(sys.argv[1],encoding='utf-8').read()
+want=sys.argv[2]
+m=re.search(r'^api_tokens:[ \t]*(\{.*\})[ \t]*$', s, re.M)
+if m:
+    for pair in m.group(1).strip('{}').split(','):
+        if ':' in pair:
+            k,v=pair.split(':',1)
+            if k.strip().strip('"\'')==want: print(v.strip().strip('"\'')); break
+else:
+    on=False
+    for line in s.split('\n'):
+        if re.match(r'^api_tokens:\s*$', line): on=True; continue
+        if on:
+            if line and not line.startswith(' '): break
+            mm=re.match(r'^\s+([^#\s:]+):\s*(.*?)\s*$', line)
+            if mm and mm.group(1)==want: print(mm.group(2).strip('"\'')); break
+PY
+  fi
+}
+
+function cpanel_ssh_key() {
+  local k="${CPANEL_SSH_KEY:-${ssh_key:-~/.ssh/id_ed25519}}";
+  printf '%s' "${k/#\~/${HOME}}";
+}
+
+function ensure_cpanel() {
+  for tool in ssh rsync curl python3 ; do
+    command -v "${tool}" > /dev/null 2>&1 || { echo "${tool} is not installed, and the cPanel tool needs it."; return 1; } ;
+  done
+  return 0 ;
+}
+
+# The link is user@host:/remote/docroot, kept as three keys; the id the dashboard shows is user@host.
+function cpanel_do_link() {
+  local project_path="$1" spec="$2" user host remote;
+  [[ "${spec}" =~ ^([^@]+)@([^:]+):(/.+)$ ]] || { echo "A cPanel link is user@host:/remote/docroot, got: ${spec}"; return 1; } ;
+  user="${BASH_REMATCH[1]}"; host="${BASH_REMATCH[2]}"; remote="${BASH_REMATCH[3]}";
+  cpanel_link_set "${project_path}" id "${user}@${host}" ;
+  cpanel_link_set "${project_path}" user "${user}" ;
+  cpanel_link_set "${project_path}" host "${host}" ;
+  cpanel_link_set "${project_path}" remote "${remote}" ;
+  if ssh -i "$(cpanel_ssh_key)" -o BatchMode=yes -o ConnectTimeout=10 "${user}@${host}" "test -d '${remote}'" 2>/dev/null ; then
+    echo "  SSH reaches ${user}@${host} and ${remote} exists." ;
+  else
+    echo "  SSH could not reach ${user}@${host} with $(cpanel_ssh_key) (or ${remote} is missing): authorize the key in cPanel → Security → SSH Access." ;
+  fi
+}
+
+function cpanel_uapi() {
+  local project_path="$1" call="$2" user host token;
+  user="$(cpanel_link_get "${project_path}" user)"; host="$(cpanel_link_get "${project_path}" host)";
+  token="$(cpanel_token_for "${user}")";
+  [ -z "${token}" ] && { echo "No API token for cPanel user ${user} in plugin.cpanel.settings.yml (api_tokens)." >&2; return 1; } ;
+  curl -sS -k -m 30 -H "Authorization: cpanel ${user}:${token}" "https://${host}:2083/execute/${call}" ;
+}
+
+function cpanel_list_environments() {
+  cpanel_uapi "$1" DomainInfo/list_domains | python3 -c 'import json,sys
+d=json.load(sys.stdin).get("data",{})
+for x in [d.get("main_domain")]+d.get("addon_domains",[])+d.get("sub_domains",[]):
+    if x: print(x)' 2>/dev/null ;
+}
+
+function cpanel_do_environments() {
+  local project_path="$1";
+  cpanel_uapi "${project_path}" DomainInfo/list_domains | python3 -c 'import json,sys
+d=json.load(sys.stdin).get("data",{})
+print("  %-40s %s" % (d.get("main_domain",""), "main   https://"+d.get("main_domain","")))
+for x in d.get("addon_domains",[]): print("  %-40s %s" % (x, "addon  https://"+x))
+for x in d.get("sub_domains",[]): print("  %-40s %s" % (x, "sub    https://"+x))
+for x in d.get("parked_domains",[]): print("  %-40s %s" % (x, "alias"))' || return 1 ;
+  cpanel_uapi "${project_path}" Quota/get_quota_info 2>/dev/null | python3 -c 'import json,sys
+d=json.load(sys.stdin).get("data",{})
+print("  disk: %s MB of %s MB" % (d.get("megabytes_used","?"), d.get("megabyte_limit","?")))' 2>/dev/null ;
+}
+
+function cpanel_ssh() {
+  local project_path="$1"; shift;
+  ssh -i "$(cpanel_ssh_key)" -o BatchMode=yes -o ConnectTimeout=15 "$(cpanel_link_get "${project_path}" id)" "$@" ;
+}
+
+function cpanel_pull_db() {
+  local project_path="$1" acct="$2" env="$3" stamp out dump safety remote;
+  remote="$(cpanel_link_get "${project_path}" remote)";
+  stamp="$(date +%Y-%m-%d-%H%M%S)";
+  out="${backups}/${doc_name}/${PROJECT_NAME}";
+  mkdir -p "${out}" ;
+  dump="${out}/${PROJECT_NAME}-cpanel-${env}-${stamp}.sql.gz";
+  safety="${out}/${PROJECT_NAME}-before-cpanel-pull-${stamp}.sql.gz";
+  echo "";
+  echo "Pulling the database of ${env} on ${acct} (drush sql:dump in ${remote}).";
+  echo "  This is client data: it lands on this machine and in ${out}.";
+  echo "";
+  cpanel_safety_export "${project_path}" "${safety}" ;
+  echo "Dumping over SSH.";
+  cpanel_ssh "${project_path}" "cd '${remote}' && (command -v drush >/dev/null 2>&1 && drush sql:dump --gzip || ../vendor/bin/drush sql:dump --gzip)" > "${dump}" || return 1 ;
+  [ -s "${dump}" ] || { echo "The dump is empty — is drush on the server (vendor/bin/drush beside the docroot)?"; return 1; } ;
+  cpanel_import_dump "${project_path}" "${dump}" || return 1 ;
+  echo "";
+  echo "  Imported ${env} into ${doc_name}/${PROJECT_NAME}.";
+  echo "    pulled dump:   ${dump}";
+  echo "    local backup:  ${safety}";
+}
+
+function cpanel_pull_files() {
+  local project_path="$1" acct="$2" env="$3" docroot remote;
+  remote="$(cpanel_link_get "${project_path}" remote)";
+  docroot="$(cpanel_docroot "${project_path}")";
+  [ -z "${docroot}" ] && { echo "No web/ or docroot/ in ${doc_name}/${PROJECT_NAME} — nothing to pull files into."; return 1; } ;
+  echo "";
+  echo "rsync ${acct}:${remote}/sites/default/files → ${docroot}/sites/default/files (adds and overwrites, never deletes).";
+  mkdir -p "${project_path}/${docroot}/sites/default/files" ;
+  rsync -az --info=progress2 -e "ssh -i $(cpanel_ssh_key) -o BatchMode=yes" "${acct}:${remote}/sites/default/files/" "${project_path}/${docroot}/sites/default/files/" || return 1 ;
+  echo "  If Drupal still shows broken images: ddev drush cr";
+}
+
+function cpanel_do_push() {
+  local project_path="$1" acct="$2" env="$3" docroot remote a;
+  remote="$(cpanel_link_get "${project_path}" remote)";
+  docroot="$(cpanel_docroot "${project_path}")";
+  [ -z "${docroot}" ] && { echo "No web/ or docroot/ in ${doc_name}/${PROJECT_NAME} — nothing to deploy."; return 1; } ;
+  echo "Deploy ${docroot}/ of ${doc_name}/${PROJECT_NAME} → ${acct}:${remote}/ (${env})";
+  echo "  rsync --delete, excluding sites/default/files, sites/*/settings*.php, .git, .ddev. The live site changes.";
+  read -r -p "  Continue? [y/N] " a < /dev/tty || return 1 ;
+  [[ "${a}" =~ ^[Yy] ]] || { echo "Not deployed."; return 1; } ;
+  rsync -az --delete --info=progress2 -e "ssh -i $(cpanel_ssh_key) -o BatchMode=yes" \
+    --exclude 'sites/default/files' --exclude 'sites/*/settings*.php' --exclude '.git' --exclude '.ddev' \
+    "${project_path}/${docroot}/" "${acct}:${remote}/" || return 1 ;
+  if [ -d "${project_path}/vendor" ] ; then
+    echo "  vendor/ is beside the docroot locally: syncing it to $(dirname "${remote}")/vendor/ too.";
+    rsync -az --delete -e "ssh -i $(cpanel_ssh_key) -o BatchMode=yes" "${project_path}/vendor/" "${acct}:$(dirname "${remote}")/vendor/" || return 1 ;
+  fi
+  echo "  Deployed. Clear caches on the server: ssh ${acct} 'cd ${remote} && drush cr'";
+}
+
+function cpanel_do_logs() {
+  local project_path="$1" remote;
+  remote="$(cpanel_link_get "${project_path}" remote)";
+  cpanel_ssh "${project_path}" "for f in '${remote}/error_log' \"\$HOME/logs/\"*error_log; do [ -f \"\$f\" ] && { echo \"— \$f —\"; tail -50 \"\$f\"; }; done" ;
+}
+
+function cpanel_status() {
+  local project_path="$1" acct="$2";
+  if [ -z "${acct}" ] ; then
+    echo "    (the link is user@host:/remote/docroot)";
+    return 0 ;
+  fi
+  echo "    remote:  $(cpanel_link_get "${project_path}" remote)";
+  echo "";
+  cpanel_do_environments "${project_path}" ;
+  echo "";
+  echo "  Console: https://$(cpanel_link_get "${project_path}" host):2083/";
+  echo "  Data: --pull-db and --pull-files bring the site down into DDEV over SSH; --push deploys with rsync.";
+}

package/scripts/host-install.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+## The host side of the cPanel plugin: the CLI on this machine and the dashboard's credentials.
+## Run by core/scripts/plugins.sh --install cpanel, and by core/scripts/install.sh for every installed
+## plugin that ships one. Idempotent: whatever is already there is reported, not redone. Offered,
+## never automatic: a hosting CLI carries cloud credentials for real environments.
+set -u
+WORKSPACE_ROOT="${WORKSPACE_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../../.." && pwd)}";
+
+STATE="$(grep -E '^api_tokens:' "${WORKSPACE_ROOT}/core/config/plugin.cpanel.settings.yml" 2>/dev/null | head -1 | sed -E 's/^[a-z_]+:[[:space:]]*//')";
+case "${STATE}" in
+  ''|CHANGE_ME|"''"|'""') printf '  ✗ %-16s %s\n' "api_tokens" "not set in plugin.cpanel.settings.yml — the dashboard cannot reach cPanel" ;;
+  *)                       printf '  ✓ %-16s %s\n' "api_tokens" "set (plugin.cpanel.settings.yml)" ;;
+esac
+