@webship.co/workspace-digitalocean 0.0.0-stage → 1.0.0-beta1

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# @webship.co/workspace-digitalocean
 
-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.
+DigitalOcean for the [Webship Workspace](https://github.com/webship/workspace) dashboard: the **DIGITALOCEAN**
+menu on every site row, a live-site chip on the project card, "Link to DigitalOcean" when a new folder is
+made, and the `cmd-tools-digitalocean.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.
+
+An App Platform app has one environment (production) with one live URL, so the environments list is the app itself and its deployments. A deploy triggers a new deployment from the app's source; the logs are `doctl apps logs`; the database comes from a managed cluster you name once with `--database <cluster-id>` (`doctl databases connection` gives the details, `mysqldump`/`pg_dump` do the dump — your machine's IP must be in the cluster's trusted sources). There is no files mount: App Platform apps keep their files in Spaces, which is an S3 bucket, not something this plugin syncs.
+
+## Use it
+
+```bash
+cd ~/workspace
+bash core/scripts/plugins.sh --require github:webship/workspace-digitalocean
+bash core/scripts/plugins.sh --activate digitalocean
+bash core/scripts/plugins.sh --install digitalocean
+bash core/scripts/plugins.sh --configure digitalocean      # core/config/plugin.digitalocean.settings.yml
+```
+
+The same four steps are buttons on the dashboard's **Settings → Plugins** page.
+
+## The command
+
+```bash
+cd ~/workspace/dev
+bash cmd-tools-digitalocean.sh <project> [verb]
+```
+
+| Verb | What it does |
+| --- | --- |
+| `--link` <value> | Link the project to an App Platform app by its id. Find ids with: doctl apps list |
+| `--database` <value> | Remember the managed database cluster id --pull-db dumps from (doctl databases list). The app's own spec rarely says it. |
+| `--push` | Deploy: trigger a new deployment of the app from its source (doctl apps create-deployment --wait). |
+| `--environment` <value> | Environment for THIS run. An App Platform app has one: production. Kept for the family's shape. |
+| `--environments` | Show the app, its live URL, its active deployment and region. |
+| `--select` <value> | Remember which environment this project works against (production). Checked against the real list. |
+| `--pull-db` | Dump the linked managed database (mysqldump or pg_dump over its connection details) and import it into DDEV. REPLACES the local database — the current one is exported to backups/ first. Client data. |
+| `--logs` | Show the latest deploy log, then follow the run logs (doctl apps logs). |
+| `--activities` | List the last 10 deployments of the app. |
+| `--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 app. |
+
+The link lives in the project's `.digitalocean/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, digitaloceanProvider(api))` |
+| `src/lib/provider.ts` | The DigitalOcean 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-digitalocean.sh` | The per-workspace command |
+| `scripts/functions/fun-digitalocean.sh` | The provider's bash hooks (doctl) |
+| `scripts/functions/fun-digitalocean-tool.sh` | The family's dispatcher: link file, environment selection, safety export, status |
+| `scripts/args/arg-digitalocean.sh` | Its argparse |
+| `scripts/host-install.sh` | The host side: the CLI and the credential check |
+| `config/plugin.digitalocean.settings.yml` | The settings template |
+
+The `workspacePlugin` block in `package.json` is the manifest the installer reads.

package/commands/cmd-tools-digitalocean.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+# Installed by the DigitalOcean plugin (plugins.sh --install digitalocean); __WORKSPACE__ is the workspace it was installed into.
+#
+# The local ⇄ cloud bridge for one project on DigitalOcean: 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 DigitalOcean"
+# The args file comes with the plugin: core/scripts/plugins/digitalocean/ is where plugins.sh --install puts it.
+source ${WORKSPACE_SCRIPTS}/plugins/digitalocean/args/arg-digitalocean.sh || exit 1 ;
+
+shift $#;
+
+digitalocean_project_tool ;

package/config/plugin.digitalocean.settings.yml

@@ -0,0 +1,5 @@
+# DigitalOcean — core/config/plugin.digitalocean.settings.yml
+#
+# The doctl CLI inside the dashboard container. A personal access token from cloud.digitalocean.com → API → Tokens (read scope for the lists, write for deploys); injected only into DigitalOcean jobs, never printed.
+# A personal access token from cloud.digitalocean.com → API. Read by doctl as DIGITALOCEAN_ACCESS_TOKEN.
+access_token: CHANGE_ME

package/config/settings.labels.yml

@@ -0,0 +1,4 @@
+# Labels for core/config/plugin.digitalocean.settings.yml, merged into the Settings page.
+access_token:
+  label: DigitalOcean access token
+  info: 'A personal access token from cloud.digitalocean.com → API. Read by doctl as DIGITALOCEAN_ACCESS_TOKEN.'

package/ddev/docker-compose.digitalocean-cli.yaml

@@ -0,0 +1,9 @@
+# The doctl CLI and its session, shared FROM THE HOST: one login, token refreshes land on
+# the host, rebuilds keep it. The bin DIRECTORY is mounted, not the file, so an update on the host
+# is live in the container at once. A machine without the CLI mounts an empty dir and the actions
+# say so.
+services:
+  web:
+    volumes:
+      - "${HOME}/.local/bin:/host-local-bin:ro"
+      - "${HOME}/.config/doctl:/home/${USER}/.config/doctl:rw"

package/dist/src/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * DigitalOcean for Webship Workspace.
+ *
+ * The DIGITALOCEAN menu on every site row, a live-site chip, the New-folder link option and the
+ * `/digitalocean-site/<workspace>/<project>` jump: all of it is the hosting family's surface
+ * (@webship.co/workspace-hosting). This package is the DigitalOcean 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 { digitaloceanProvider } from './lib/provider';
+export { digitaloceanProvider };
+export { digitaloceanLinkOf } from './lib/link';
+export declare function register(api: PluginApi): void;

package/dist/src/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * DigitalOcean for Webship Workspace.
+ *
+ * The DIGITALOCEAN menu on every site row, a live-site chip, the New-folder link option and the
+ * `/digitalocean-site/<workspace>/<project>` jump: all of it is the hosting family's surface
+ * (@webship.co/workspace-hosting). This package is the DigitalOcean 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.digitaloceanLinkOf = exports.digitaloceanProvider = void 0;
+exports.register = register;
+const workspace_hosting_1 = require("@webship.co/workspace-hosting");
+const provider_1 = require("./lib/provider");
+Object.defineProperty(exports, "digitaloceanProvider", { enumerable: true, get: function () { return provider_1.digitaloceanProvider; } });
+var link_1 = require("./lib/link");
+Object.defineProperty(exports, "digitaloceanLinkOf", { enumerable: true, get: function () { return link_1.digitaloceanLinkOf; } });
+function register(api) {
+    (0, workspace_hosting_1.registerHosting)(api, (0, provider_1.digitaloceanProvider)(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,6CAAsD;AAE7C,qGAFA,+BAAoB,OAEA;AAC7B,mCAAgD;AAAvC,0GAAA,kBAAkB,OAAA;AAE3B,SAAgB,QAAQ,CAAC,GAAc;IACrC,IAAA,mCAAe,EAAC,GAAG,EAAE,IAAA,+BAAoB,EAAC,GAAG,CAAC,CAAC,CAAC;AAClD,CAAC"}

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

@@ -0,0 +1,11 @@
+/**
+ * Whether a project is linked to DigitalOcean, and to what: the `.digitalocean/workspace.yml` file that
+ * `cmd-tools-digitalocean.sh --link` writes (git-excluded), plus the branch the local code is on.
+ */
+import type { HostingLink } from '@webship.co/workspace-hosting';
+export interface DigitalOceanLink 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 digitaloceanLinkOf(projectDir: string): DigitalOceanLink | null;

package/dist/src/lib/link.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Whether a project is linked to DigitalOcean, and to what: the `.digitalocean/workspace.yml` file that
+ * `cmd-tools-digitalocean.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.digitaloceanLinkOf = digitaloceanLinkOf;
+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, '.digitalocean', '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 digitaloceanLinkOf(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,gDASC;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,eAAe,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC;IAAC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QAAC,OAAO,IAAI,CAAC;IAAC,CAAC;IAC3H,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,kBAAkB,CAAC,UAAkB;IACnD,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,11 @@
+/**
+ * DigitalOcean App Platform, as a hosting provider.
+ *
+ * The link is `.digitalocean/workspace.yml` (the app id, and the managed database cluster id when
+ * one was named); the app's live URL and deployments come from doctl with the access token from
+ * plugin.digitalocean.settings.yml injected per call; the deploy, the logs, the deployments list
+ * and the database pull go through cmd-tools-digitalocean.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 digitaloceanProvider(api: PluginApi): HostingProvider;

package/dist/src/lib/provider.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * DigitalOcean App Platform, as a hosting provider.
+ *
+ * The link is `.digitalocean/workspace.yml` (the app id, and the managed database cluster id when
+ * one was named); the app's live URL and deployments come from doctl with the access token from
+ * plugin.digitalocean.settings.yml injected per call; the deploy, the logs, the deployments list
+ * and the database pull go through cmd-tools-digitalocean.sh in a screen session.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.digitaloceanProvider = digitaloceanProvider;
+const workspace_hosting_1 = require("@webship.co/workspace-hosting");
+const link_1 = require("./link");
+function digitaloceanProvider(api) {
+    const settings = () => api.settings.read() || {};
+    const bin = () => (0, workspace_hosting_1.findCli)('doctl') || 'doctl';
+    const jobEnv = () => {
+        const t = (0, workspace_hosting_1.configured)(settings().access_token);
+        return t ? { ...process.env, DIGITALOCEAN_ACCESS_TOKEN: t } : null;
+    };
+    async function environments(link, lib, env) {
+        const id = link.id;
+        const out = await lib.run(bin(), ['apps', 'get', id, '-o', 'json'], process.env.HOME, { timeoutMs: 60 * 1000, env });
+        if (!out.ok)
+            return { id, rows: [], why: 'list failed' };
+        let apps = [];
+        try {
+            apps = JSON.parse(String(out.stdout));
+        }
+        catch (_) {
+            return { id, rows: [], why: 'list failed' };
+        }
+        const app = apps[0];
+        if (!app)
+            return { id, rows: [], why: 'no such app' };
+        const url = app.live_url || app.default_ingress;
+        const phase = (app.active_deployment && app.active_deployment.phase) || '';
+        // One environment per app: production. A deploying app is still live on its last deployment.
+        const status = url && /^active$/i.test(phase) ? 'active' : (app.in_progress_deployment ? 'deploying' : (phase || 'unknown').toLowerCase());
+        return { id, rows: [{ title: (app.spec && app.spec.name) || 'production', envId: 'production', status, url: url || undefined }] };
+    }
+    return {
+        id: 'digitalocean',
+        label: 'DIGITALOCEAN',
+        title: 'DigitalOcean',
+        cli: 'doctl',
+        script: 'cmd-tools-digitalocean.sh',
+        detect: (projectDir) => (0, link_1.digitaloceanLinkOf)(projectDir),
+        linkHint: (project) => `bash cmd-tools-digitalocean.sh ${project} --link <app-id>`,
+        consoleUrl: (link) => (link.id ? `https://cloud.digitalocean.com/apps/${encodeURIComponent(link.id)}` : null),
+        jobEnv,
+        tokenHint: 'access_token in core/config/plugin.digitalocean.settings.yml',
+        environments,
+        tools: {
+            status: { verb: 'digitalocean', label: 'Link and the app', icon: 'info', args: [] },
+            activities: { verb: 'digitalocean-activities', label: 'Last 10 deployments', icon: 'list', args: ['--activities'] },
+            logs: { verb: 'digitalocean-logs', label: 'Deploy and run logs', icon: 'file-text', args: ['--logs'] },
+            deploy: { verb: 'digitalocean-push', label: 'Deploy (new deployment from source)…', icon: 'push', args: ['--push'] },
+        },
+        pull: {
+            db: true, files: false,
+            dbArgs: (e) => ['--environment', e, '--pull-db'],
+            filesArgs: () => [],
+            noSafetyBackupArg: '--no-safety-backup',
+        },
+        errorHint: (msg) => (/401|unauthorized|unable to authenticate/i.test(msg)
+            ? `${msg}\n\nThe dashboard reaches DigitalOcean with access_token in core/config/plugin.digitalocean.settings.yml: a personal access token from cloud.digitalocean.com → API.`
+            : msg),
+        folder: {
+            idPattern: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+            idPlaceholder: 'b7e93f4a-1c2d-4e5f-8a9b-0c1d2e3f4a5b',
+            idHelp: 'A DigitalOcean app id is a UUID (doctl apps list, or the id in the app\'s console URL).',
+        },
+        menuNote: 'Linking and naming the database cluster stay on the command line; files live in Spaces and are not synced',
+    };
+}
+//# 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":"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"}

package/features/digitalocean.feature

@@ -0,0 +1,20 @@
+Feature: The DigitalOcean plugin on a project row
+  Once the plugin is activated and installed, every site row carries the DIGITALOCEAN menu, and the Plugins
+  page lists the plugin with its four steps.
+
+  Scenario: A site row offers the DIGITALOCEAN menu, captioned with its link state
+    Given I am on "/dev"
+     Then the element ".act-menu-digitalocean" should be displayed
+      And I should see "DIGITALOCEAN"
+      And the element ".act-menu-digitalocean + .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-digitalocean button"
+     Then ".uk-dropdown.uk-open" should be visible
+      And I should see "Not linked to DigitalOcean"
+
+  Scenario: The plugin is listed on the Plugins page
+    Given I am on "/settings/plugins"
+     Then I should see "DigitalOcean"
+      And I should see "@webship.co/workspace-digitalocean"

package/host-mounts.txt

@@ -0,0 +1,2 @@
+# Directories the dashboard container bind-mounts for this plugin; host-mounts.sh creates them as you first.
+~/.config/doctl

package/package.json

@@ -1,6 +1,88 @@
 {
   "name": "@webship.co/workspace-digitalocean",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-beta1",
+  "description": "DigitalOcean App Platform for Webship Workspace: the DIGITALOCEAN menu on every site row, the app's live URL and deployments, deploy, logs, a managed database pulled into DDEV. 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-digitalocean.git"
+  },
+  "files": [
+    "dist/src",
+    "commands",
+    "config",
+    "features",
+    "scripts",
+    "README.md",
+    "ddev",
+    "host-mounts.txt"
+  ],
+  "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": "digitalocean",
+    "label": "DigitalOcean",
+    "settingsFile": "plugin.digitalocean.settings.yml",
+    "settingsTemplate": "config/plugin.digitalocean.settings.yml",
+    "labels": "config/settings.labels.yml",
+    "legacySettingsKey": "digitalocean",
+    "typeActions": {
+      "digitalocean": [
+        "sites"
+      ]
+    },
+    "commands": {
+      "types": [
+        "sites"
+      ],
+      "workspaces": [
+        "dev",
+        "test",
+        "demos",
+        "sandboxes",
+        "projects"
+      ],
+      "files": [
+        "commands/cmd-tools-digitalocean.sh"
+      ]
+    },
+    "scripts": {
+      "functions": [
+        "scripts/functions/fun-digitalocean.sh",
+        "scripts/functions/fun-digitalocean-tool.sh"
+      ],
+      "args": [
+        "scripts/args/arg-digitalocean.sh"
+      ],
+      "hostInstall": "scripts/host-install.sh"
+    },
+    "features": [
+      "features/digitalocean.feature"
+    ],
+    "ddev": {
+      "compose": [
+        "ddev/docker-compose.digitalocean-cli.yaml"
+      ],
+      "hostMounts": [
+        "~/.config/doctl"
+      ]
+    }
+  },
+  "dependencies": {
+    "@webship.co/workspace-hosting": "^1.0.0-beta1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@webship.co/workspace-plugin-api": "^1.0.0-beta1",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/args/arg-digitalocean.sh

@@ -0,0 +1,46 @@
+#!/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 an App Platform app by its id. Find ids with: doctl apps list')
+parser.add_argument('-d', '--database',
+                    default="_none_",
+                    help='Remember the managed database cluster id --pull-db dumps from (doctl databases list). The app's own spec rarely says it.')
+parser.add_argument('-p', '--push',
+                    action='store_true',
+                    default=False,
+                    help='Deploy: trigger a new deployment of the app from its source (doctl apps create-deployment --wait).')
+parser.add_argument('-e', '--environment',
+                    default="_none_",
+                    help='Environment for THIS run. An App Platform app has one: production. Kept for the family's shape.')
+parser.add_argument('-E', '--environments',
+                    action='store_true',
+                    default=False,
+                    help='Show the app, its live URL, its active deployment and region.')
+parser.add_argument('-s', '--select',
+                    default="_none_",
+                    help='Remember which environment this project works against (production). Checked against the real list.')
+parser.add_argument('-D', '--pull-db',
+                    action='store_true',
+                    default=False,
+                    help='Dump the linked managed database (mysqldump or pg_dump over its connection details) and import it into DDEV. REPLACES the local database — the current one is exported to backups/ first. Client data.')
+parser.add_argument('-g', '--logs',
+                    action='store_true',
+                    default=False,
+                    help='Show the latest deploy log, then follow the run logs (doctl apps logs).')
+parser.add_argument('-a', '--activities',
+                    action='store_true',
+                    default=False,
+                    help='List the last 10 deployments of the app.')
+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 app.')
+ARGEOF

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

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+
+# The DigitalOcean tool's dispatcher: generated by the hosting family's scaffolder, the same for every
+# provider. The provider's own hooks live in fun-digitalocean.sh:
+#   ensure_digitalocean                              the CLI and credentials are usable, or say how
+#   digitalocean_do_link <project_path> <id>         link the project (writes the link file through digitalocean_link_set)
+#   digitalocean_list_environments <id>              one environment id per line (for --select's check)
+#   digitalocean_do_environments <id>                print the environments for a person
+#   digitalocean_pull_db <project_path> <id> <env>   dump the environment's database to stdout path given in $1… (see fun-digitalocean.sh)
+#   digitalocean_pull_files <project_path> <id> <env>
+#   digitalocean_do_push <project_path> <id> <env>   deploy
+#   digitalocean_do_logs <project_path> <id> <env>
+#   digitalocean_do_activities <project_path> <id>
+#   digitalocean_status <project_path> <id>          the closing status block
+
+DIGITALOCEAN_LINK_FILE=".digitalocean/workspace.yml";
+
+# One key of the link file, or nothing.
+function digitalocean_link_get() {
+  local project_path="$1" key="$2";
+  [ -f "${project_path}/${DIGITALOCEAN_LINK_FILE}" ] || return 0 ;
+  grep -E "^${key}:" "${project_path}/${DIGITALOCEAN_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 digitalocean_link_set() {
+  local project_path="$1" key="$2" value="$3" file;
+  file="${project_path}/${DIGITALOCEAN_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 "/.digitalocean/" "${project_path}/.git/info/exclude" 2>/dev/null ; then
+    mkdir -p "${project_path}/.git/info" && printf '/.digitalocean/\n' >> "${project_path}/.git/info/exclude" ;
+  fi
+}
+
+function digitalocean_linked_id() { digitalocean_link_get "$1" id ; }
+function digitalocean_selected_env() { digitalocean_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 digitalocean_target_env() {
+  if [ ! "${ENVIRONMENT:-_none_}" == '_none_' ] ; then printf '%s' "${ENVIRONMENT}"; return 0 ; fi
+  digitalocean_selected_env "$1";
+}
+
+# Where this project serves from: Drupal's two conventions, plus the flat case.
+function digitalocean_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 digitalocean_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 digitalocean_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 digitalocean_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="$(digitalocean_linked_id "${project_path}")" ;
+
+  if [ ! "${LINK:-_none_}" == '_none_' ] ; then
+    ensure_digitalocean || return 1 ;
+    if [ -n "${linked_id}" ] && [ ! "${linked_id}" == "${LINK}" ] && [ ! "${FORCE:-no}" == 'yes' ] ; then
+      echo "${doc_name}/${PROJECT_NAME} is already linked to DigitalOcean ${linked_id}." ;
+      echo "Re-run with --force to relink it to ${LINK}." ;
+      return 1 ;
+    fi
+    digitalocean_do_link "${project_path}" "${LINK}" || return 1 ;
+    linked_id="$(digitalocean_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 DigitalOcean — run with --link <id> first." ;
+      return 1 ;
+    fi
+    ensure_digitalocean || return 1 ;
+  fi
+
+  if [ "${ENVIRONMENTS:-no}" == 'yes' ] ; then
+    digitalocean_do_environments "${project_path}" "${linked_id}" || return 1 ;
+    echo "";
+    echo "  Select one:  bash cmd-tools-digitalocean.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 ! digitalocean_list_environments "${project_path}" "${linked_id}" 2>/dev/null | grep -qx "${SELECT}" ; then
+      echo "DigitalOcean ${linked_id} has no environment called '${SELECT}'." ;
+      echo "  List them: bash cmd-tools-digitalocean.sh ${PROJECT_NAME} --environments" ;
+      return 1 ;
+    fi
+    digitalocean_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="$(digitalocean_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-digitalocean.sh ${PROJECT_NAME} --environments" ;
+      echo "  bash cmd-tools-digitalocean.sh ${PROJECT_NAME} --select <environment>" ;
+      echo "  (or name it for this run: --environment <environment>)" ;
+      return 1 ;
+    fi
+    [ "${PULL_DB:-no}" == 'yes' ] && { digitalocean_pull_db "${project_path}" "${linked_id}" "${target_env}" || return 1 ; }
+    [ "${PULL_FILES:-no}" == 'yes' ] && { digitalocean_pull_files "${project_path}" "${linked_id}" "${target_env}" || return 1 ; }
+    [ "${PUSH:-no}" == 'yes' ] && { digitalocean_do_push "${project_path}" "${linked_id}" "${target_env}" || return 1 ; }
+  fi
+
+  if [ "${LOGS:-no}" == 'yes' ] ; then
+    digitalocean_do_logs "${project_path}" "${linked_id}" "$(digitalocean_target_env "${project_path}")" || true ;
+  fi
+  if [ "${ACTIVITIES:-no}" == 'yes' ] ; then
+    digitalocean_do_activities "${project_path}" "${linked_id}" || true ;
+  fi
+
+  # Default (and after any verb): status.
+  echo "";
+  echo "*---------------------------------------------------------------------*";
+  echo "  ${doc_name}/${PROJECT_NAME} on DigitalOcean";
+  if [ -z "${linked_id}" ]; then
+    echo "    not linked. Link it with:";
+    echo "      bash cmd-tools-digitalocean.sh ${PROJECT_NAME} --link <id>";
+    digitalocean_status "${project_path}" "" ;
+  else
+    echo "    linked:  ${linked_id}";
+    local selected;
+    selected="$(digitalocean_selected_env "${project_path}")";
+    echo "    env:     ${selected:-none selected — --environments then --select <name>}";
+    digitalocean_status "${project_path}" "${linked_id}" ;
+  fi
+  echo "*---------------------------------------------------------------------*";
+
+  cd "${WORKSPACE_ROOT}/${doc_name}";
+}

package/scripts/functions/fun-digitalocean.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+
+# DigitalOcean App Platform (https://cloud.digitalocean.com/apps) through doctl. The hooks the
+# hosting dispatcher (fun-digitalocean-tool.sh) calls for one project directory. Everything
+# defaults to read-only; --link, --push and --pull-db each demand their flag, and nothing here ever
+# creates or deletes an app or a database.
+
+function ensure_digitalocean() {
+  if command -v doctl > /dev/null 2>&1 ; then
+    if ! doctl account get > /dev/null 2>&1 ; then
+      echo "doctl is installed but has no usable token. On the host: doctl auth init (a personal access token from cloud.digitalocean.com → API)." ;
+      return 1 ;
+    fi
+    return 0 ;
+  fi
+  echo "doctl is not installed. Install it first:" ;
+  echo "  https://docs.digitalocean.com/reference/doctl/how-to/install/ (snap install doctl, or the release tarball into ~/.local/bin)" ;
+  echo "then authenticate with: doctl auth init" ;
+  return 1 ;
+}
+
+function digitalocean_do_link() {
+  local project_path="$1" app="$2";
+  doctl apps get "${app}" > /dev/null || { echo "No app ${app} on this account (doctl apps list)."; return 1; } ;
+  digitalocean_link_set "${project_path}" id "${app}" ;
+  if [ ! "${DATABASE:-_none_}" == '_none_' ] ; then
+    digitalocean_link_set "${project_path}" database "${DATABASE}" ;
+    echo "  --pull-db will dump managed database cluster ${DATABASE}." ;
+  fi
+  # One environment, always: production. Selected now so the pulls take no flag.
+  digitalocean_link_set "${project_path}" env production ;
+}
+
+function digitalocean_list_environments() { echo production ; }
+
+function digitalocean_do_environments() {
+  local app="$2";
+  doctl apps get "${app}" -o json | python3 -c 'import json,sys
+for a in json.load(sys.stdin):
+    s=a.get("spec",{}); d=a.get("active_deployment",{}) or {}
+    print("  %-12s %-28s %-10s %s" % ("production", (s.get("name") or "")[:28], (d.get("phase") or "").lower(), a.get("live_url") or a.get("default_ingress") or ""))
+    print("  region: %s   updated: %s" % (s.get("region",""), (a.get("updated_at") or "")[:19]))' \
+    || { echo "  (could not read the app — check doctl account get)"; return 1; } ;
+}
+
+function digitalocean_pull_db() {
+  local project_path="$1" app="$2" env="$3" stamp out dump safety cluster;
+  cluster="$(digitalocean_link_get "${project_path}" database)";
+  if [ -z "${cluster}" ] ; then
+    echo "No managed database cluster is linked. Name it once (doctl databases list):" ;
+    echo "  bash cmd-tools-digitalocean.sh ${PROJECT_NAME} --link ${app} --database <cluster-id> --force" ;
+    return 1 ;
+  fi
+  stamp="$(date +%Y-%m-%d-%H%M%S)";
+  out="${backups}/${doc_name}/${PROJECT_NAME}";
+  mkdir -p "${out}" ;
+  dump="${out}/${PROJECT_NAME}-digitalocean-${env}-${stamp}.sql.gz";
+  safety="${out}/${PROJECT_NAME}-before-digitalocean-pull-${stamp}.sql.gz";
+  echo "";
+  echo "Pulling database cluster ${cluster} of app ${app}.";
+  echo "  This is client data: it lands on this machine and in ${out}.";
+  echo "  Your IP must be among the cluster's trusted sources, or the connection is refused.";
+  echo "";
+  digitalocean_safety_export "${project_path}" "${safety}" ;
+  local conn; conn="$(doctl databases connection "${cluster}" -o json)" || return 1 ;
+  local engine; engine="$(doctl databases get "${cluster}" -o json | python3 -c 'import json,sys; print(json.load(sys.stdin)[0].get("engine",""))')";
+  local host port user pass db;
+  read -r host port user pass db <<< "$(printf '%s' "${conn}" | python3 -c 'import json,sys; c=json.load(sys.stdin); print(c["host"], c["port"], c["user"], c["password"], c["database"])')";
+  echo "Dumping ${db} (${engine}) from ${host}.";
+  case "${engine}" in
+    mysql)
+      MYSQL_PWD="${pass}" mysqldump --ssl --single-transaction --quick --no-tablespaces -h "${host}" -P "${port}" -u "${user}" "${db}" | gzip > "${dump}" || return 1 ;;
+    pg)
+      PGPASSWORD="${pass}" pg_dump --no-owner --no-acl -h "${host}" -p "${port}" -U "${user}" "${db}" | gzip > "${dump}" || return 1 ;;
+    *)
+      echo "Engine ${engine} is not one this tool dumps (mysql, pg)."; return 1 ;;
+  esac
+  digitalocean_import_dump "${project_path}" "${dump}" || return 1 ;
+  echo "";
+  echo "  Imported ${db} into ${doc_name}/${PROJECT_NAME}.";
+  echo "    pulled dump:   ${dump}";
+  echo "    local backup:  ${safety}";
+}
+
+function digitalocean_pull_files() {
+  echo "App Platform apps keep their files in Spaces (an S3 bucket): this tool does not sync them.";
+  echo "  s3cmd sync s3://<bucket>/<prefix>/ $(digitalocean_docroot "$1")/sites/default/files/   is the shape of it.";
+  return 1 ;
+}
+
+function digitalocean_do_push() {
+  local project_path="$1" app="$2";
+  echo "Creating a new deployment of app ${app} from its source (the branch or image the app spec names)…" ;
+  doctl apps create-deployment "${app}" --wait || return 1 ;
+}
+
+function digitalocean_do_logs() {
+  local app="$2";
+  echo "— the most recent deploy log —";
+  doctl apps logs "${app}" --type deploy 2>/dev/null | tail -80 ;
+  echo "— run logs (Ctrl-C stops following) —";
+  doctl apps logs "${app}" --type run --follow ;
+}
+
+function digitalocean_do_activities() {
+  doctl apps list-deployments "$2" -o json 2>/dev/null | python3 -c 'import json,sys
+for d in json.load(sys.stdin)[:10]:
+    print("  %-20s %-12s %s" % ((d.get("created_at") or "")[:19], (d.get("phase") or "").lower(), d.get("cause","")))' \
+    || echo "  (could not list the deployments)" ;
+}
+
+function digitalocean_status() {
+  local project_path="$1" app="$2";
+  if [ -z "${app}" ] ; then
+    echo "    (find the app id with: doctl apps list)";
+    return 0 ;
+  fi
+  echo "";
+  digitalocean_do_environments "${project_path}" "${app}" ;
+  local cluster; cluster="$(digitalocean_link_get "${project_path}" database)";
+  echo "    database: ${cluster:-none linked — --link ${app} --database <cluster-id> --force}";
+  echo "";
+  echo "  Console: https://cloud.digitalocean.com/apps/${app}";
+  echo "  Data: --pull-db brings the managed database down into DDEV; --push triggers a deployment.";
+}

package/scripts/host-install.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+## The host side of the DigitalOcean plugin: the CLI on this machine and the dashboard's credentials.
+## Run by core/scripts/plugins.sh --install digitalocean, 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)}";
+
+# The doctl CLI on this machine, mounted into the dashboard from ~/.local/bin or found on PATH.
+BIN='';
+for candidate in "$(command -v doctl 2>/dev/null)" "${HOME}/.local/bin/doctl" ; do
+  [ -n "${candidate}" ] && [ -x "${candidate}" ] && { BIN="${candidate}"; break; }
+done
+if [ -n "${BIN}" ] ; then
+  printf '  ✓ %-16s %s\n' "doctl" "${BIN}" ;
+else
+  printf '  ✗ %-16s %s\n' "doctl" "missing — the DIGITALOCEAN menu needs it (docs.digitalocean.com/reference/doctl/how-to/install — snap install doctl, or the GitHub release into ~/.local/bin)" ;
+fi
+
+STATE="$(grep -E '^access_token:' "${WORKSPACE_ROOT}/core/config/plugin.digitalocean.settings.yml" 2>/dev/null | head -1 | sed -E 's/^[a-z_]+:[[:space:]]*//')";
+case "${STATE}" in
+  ''|CHANGE_ME|"''"|'""') printf '  ✗ %-16s %s\n' "access_token" "not set in plugin.digitalocean.settings.yml — the dashboard cannot reach DigitalOcean" ;;
+  *)                       printf '  ✓ %-16s %s\n' "access_token" "set (plugin.digitalocean.settings.yml)" ;;
+esac
+