@webship.co/workspace-drupal-cms 0.0.0-stage → 1.0.7

package/README.md

@@ -1,3 +1,223 @@
-# Temporary Holding Version
+# @webship.co/workspace-drupal-cms
 
-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.
+Drupal CMS for the [Webship Workspace](https://github.com/webship/workspace) dashboard: one builder
+that makes a real Drupal CMS site in a container (a release, a site template, add-on recipes), a
+Drush tool for the sites it built, the default accounts, the
+[Drupal CMS step pack](https://github.com/webship/drupal-cms-steps) wired into the workspace's
+testing setup, and two AI agents that know all of it.
+
+The workspace is container-based (DDEV by default): a Drupal CMS project is a row like any other, so
+the row menus the core draws (start, stop, launch, backup, clone, remove, tests) work on it unchanged.
+
+It is made from the reference platform plugin,
+[`@webship.co/workspace-wordpress`](https://github.com/webship/workspace-wordpress), and it is the
+whole of the platform: the build, the accounts and the testing hook are the plugin's own functions.
+
+## Use it
+
+```bash
+cd ~/workspace
+bash core/scripts/plugins.sh --require github:webship/workspace-drupal-cms   # npm install into the dashboard
+bash core/scripts/plugins.sh --activate drupal-cms                            # plugins.drupal-cms in settings.yml
+bash core/scripts/plugins.sh --install drupal-cms                             # commands, functions, args, agents
+bash core/scripts/plugins.sh --configure drupal-cms                           # nothing to configure: it has no settings file
+```
+
+The same four steps are buttons on the dashboard's **Settings → Plugins** page. `--install` is
+idempotent. `--uninstall` removes what it placed; an agent you edited stays.
+
+The commands land in the sites folders that are in the workspace (`dev`, `test`, `sandboxes`,
+`demos`); the agents land in the AI Agents folder (`ai-agents/`) when the workspace has one, and are
+installed into `~/.claude/agents` from there like any other agent.
+
+It needs a Webship Workspace 1.0.7 or later.
+
+## What the package holds
+
+| Path | What it is |
+| --- | --- |
+| `commands/cmd-drupal-cms-project.sh` | The builder, in the Build list as **Drupal CMS (a site template and recipes)**, installed into every sites folder |
+| `commands/cmd-tools-drupal-cms-cli.sh` | Drush for one project: what the site is, a command, an add-on recipe, updates, the cache, a one-time login link, the default accounts |
+| `scripts/functions/fun-drupal-cms.sh` | The bash functions behind both, sourced by bootstrap once installed; the names the core's tools look for (`set_drupal_cms_users`, `add_drupal_cms_users`, `cancel_drupal_cms_users`, `testing_configure_drupal_cms`) |
+| `scripts/args/arg-drupal-cms.sh`, `arg-drupal-cms-cli.sh` | Their argparse; the Build form draws the builder's flags from the first |
+| `testing/site.feature` | The first feature a Drupal CMS project gets when testing is set up |
+| `agents/drupal-cms-site-builder.md` | The agent that builds and maintains Drupal CMS sites with these commands |
+| `agents/drupal-cms-tester.md` | The agent that writes and runs scenarios with the Drupal CMS step pack |
+| `src/index.ts` | `register(api)`: what the assistant is told about Drupal CMS here |
+| `features/drupal-cms.feature` | Scenarios for the dashboard's own browser suite |
+
+The `workspacePlugin` block in `package.json` is the manifest the installer reads. The plugin is
+`drupal-cms`; its functions and its user list are called `drupal_cms`, because a bash function name
+takes no hyphen.
+
+## How this relates to the folder builders
+
+The sites folders (`dev`, `test`, `sandboxes`, `demos`) are plugins too, and they place builders of
+their own: `cmd-drupalcms2-x-project.sh` and `cmd-drupalcms2-1-0-project.sh`, one file per release.
+Those builders call build functions that the workspace base still carries, and they install the
+Starter template only. This plugin does not move, replace or change any of them, and a workspace
+that never installs it works as before.
+
+This plugin sits beside them as the platform's own package:
+
+- **One builder, with arguments.** `cmd-drupal-cms-project.sh <name> --version … --template …
+  --recipes …` is one file for every release, site template and set of add-on recipes. Its name
+  collides with no file a folder places, so both sets are in the Build list of a folder at the same
+  time and `--uninstall` leaves the folder's files as they were.
+- **Its own functions.** The build (`drupal_cms_build`), the accounts and the testing hook are in
+  `fun-drupal-cms.sh`. They call only the workspace's general helpers (the project name, the clean
+  slate of a rebuild, the start of the container, the Node.js of the workspace) and none of the
+  Drupal functions of the base, so the base can drop its own later without touching this plugin.
+- **One shared name, on purpose.** The core's account tools look for `add_<name>_users` and
+  `cancel_<name>_users`. With this plugin installed, `cmd-tools-add-users.sh <project> drupal_cms`
+  and `--add-users` of a folder builder for Drupal CMS add **this plugin's accounts** (below) in
+  place of the base's older list. Uninstall the plugin and the older list is back.
+- **The testing setup.** The base adds no step pack to a Drupal project. With this plugin,
+  `cmd-tools-testing.sh <project>` adds the Drupal CMS step pack to a Drupal CMS site, whichever
+  builder made it.
+
+### And the Drupal plugin
+
+[`@webship.co/workspace-drupal`](https://github.com/webship/workspace-drupal) is the plugin for a
+Drupal core site. The two are independent: either works without the other, and neither calls a
+function of the other.
+
+- **Each has its Drush tool.** `cmd-tools-drupal-cms-cli.sh` is this plugin's, so the platform is
+  complete with this plugin alone; it also applies add-on recipes (`--recipe`), which the Drupal
+  plugin's tool does not. With both installed, `cmd-tools-drupal-cli.sh` works on a Drupal CMS site
+  too, since it works on any Drupal project.
+- **Each tests its own sites.** The Drupal plugin's testing hook leaves a Drupal CMS site alone, and
+  this one leaves a Drupal core site alone. The Drupal CMS step pack loads the Drupal core pack by
+  itself, so `cucumber.js` lists the Drupal CMS pack only; both packs are in `package.json`.
+
+## The commands
+
+Run them from a sites folder. `--help` is safe on both.
+
+### Build a site
+
+```bash
+cd ~/workspace/dev
+bash cmd-drupal-cms-project.sh mysite --install --add-users
+bash cmd-drupal-cms-project.sh mysite --recipes forms,search --install --add-users
+bash cmd-drupal-cms-project.sh mysite --template blank --install
+bash cmd-drupal-cms-project.sh mysite --version 2.2.9 --dry-run        # what would be built, and nothing built
+```
+
+| Flag | What it does |
+| --- | --- |
+| `--version <x>` | A release line for its latest release (`2.x`, the default), a release (`2.2.9`) or a development branch (`2.x-dev`) |
+| `--template <name>` | The site template the installer applies: `starter` (the default, `drupal_cms_starter`), `blank` (`drupal_cms_blank`), or the recipe name of another template |
+| `--template-package <package>` | The composer package of a template that is not `drupal/<its recipe name>` |
+| `--recipes <names>` | With `--install`: add-on recipes applied after the install, separated by commas; `forms` stands for `drupal_cms_forms` |
+| `--install` | Install the site, with the workspace account as its administrator |
+| `--add-users` | With `--install`: add the default accounts |
+| `--php-version <x>` | The PHP of the project container; empty is the one the project template names |
+| `--dry-run` | Say the code, the container, the site template and the recipes, and build nothing |
+| `--launch` | Open the site when it is ready |
+
+The site answers at `https://mysite.ddev.site`, the login at `/user/login`, the dashboard at
+`/admin/dashboard`. The build runs `ddev config` with the Node.js of the workspace (24), creates the
+code from `drupal/cms` with composer in the container, and installs with Drush through the
+platform's own installer, which applies the site template. The database settings are the container
+tool's (`settings.ddev.php`): the build writes none and hands the installer no database address.
+A project of the same name is deleted first. The platform's installer names the first account and
+sets its password by itself on some releases; the build sets the name, the password and the
+address of the workspace account again once the site is installed.
+
+The project template ships a container configuration of its own. After the code is there, the
+build puts the project's name back, keeps the database the container started with, and starts
+again. When the template asks for a newer container tool than the machine has, the build takes
+that line out, says so, and goes on.
+
+The project template brings the installer and no site template, so the build requires the
+template's package with composer before the install: `drupal/<its recipe name>` (the Starter
+template is `drupal/drupal_cms_starter`), or the package `--template-package` names. Only what
+composer can require without an account anywhere: no marketplace, no key.
+
+A site built here is a local one: the build keeps it out of the install statistics the platform
+reports (`DRUPAL_CMS_TELEMETRY=0` in the project's container). It also keeps the site template and
+the recipes of the build there (`DRUPAL_SITE_TEMPLATE`, `DRUPAL_CMS_RECIPES`), which is where the
+test suite reads them.
+
+### Work on a site
+
+```bash
+bash cmd-tools-drupal-cms-cli.sh mysite                                    # version, template, recipes, accounts, pending updates
+bash cmd-tools-drupal-cms-cli.sh mysite --recipe forms,search              # apply add-on recipes
+bash cmd-tools-drupal-cms-cli.sh mysite --run "pm:list --status=enabled"
+bash cmd-tools-drupal-cms-cli.sh mysite --update                           # composer update, the database updates, the cache
+bash cmd-tools-drupal-cms-cli.sh mysite --cache-rebuild
+bash cmd-tools-drupal-cms-cli.sh mysite --login                            # a one-time login link
+bash cmd-tools-drupal-cms-cli.sh mysite --add-users                        # the default accounts
+bash cmd-tools-drupal-cms-cli.sh mysite --cancel-users                     # delete them, and what they wrote
+```
+
+The tool works on any Drupal CMS project of the folder, whichever builder made it.
+
+### The default accounts
+
+| Account | Role | Handle in the tests |
+| --- | --- | --- |
+| `administrator` | administrator | `admin` |
+| `content_editor` | content_editor | `content editor` |
+| `authenticated` | none | `authenticated` |
+
+Each has the address `<account>@example.com` and the password of the workspace's other default
+lists. They are for local sites and for tests; the site's own administrator is the workspace
+account and is never written into a test. `bash cmd-tools-add-users.sh mysite drupal_cms` and
+`bash cmd-tools-cancel-users.sh mysite drupal_cms` add and remove the same list. The row's Users menu
+names this list for a Drupal CMS site once the workspace carries
+[webship/workspace#178](https://github.com/webship/workspace/issues/178); a Workspace 1.0.7 names
+another one there, so use the commands.
+
+### Test a site
+
+```bash
+bash cmd-tools-testing.sh mysite                 # webship-js, the step packs, the users registry, a first feature
+bash cmd-tools-testing.sh mysite --run           # run the suite in the container
+bash cmd-tools-testing.sh mysite --run --path tests/features/site.feature
+```
+
+`cmd-tools-testing.sh` is the workspace's own. For a Drupal CMS project it also adds
+`@webship-js/drupal-cms-steps` and the `@webship-js/drupal-core-steps` it depends on to
+`package.json`, lists the Drupal CMS pack's step definitions in `cucumber.js` after webship-js's
+own, writes what the pack reads (the users registry with the handles above, overridable with
+`DRUPAL_<NAME>_USER`, `DRUPAL_<NAME>_PASS` and `DRUPAL_<NAME>_MAIL` for `ADMIN`, `EDITOR` and
+`AUTHENTICATED`; the site template and the recipes; the cookie consent accepted before every
+scenario), places `tests/features/site.feature` when the project has none, and makes sure the
+default accounts are on the site. Run it again and it adds what is missing and keeps what you
+changed.
+
+**What was proven.** A site was built, installed and tested with this builder (Drupal CMS 2.2.9 on
+Drupal 11.4.12, the Starter template with the Forms and Search recipes, PHP 8.3, DDEV 1.24.7): the
+site answers, the accounts log in, the first feature is green. The Blank template and a template
+of another package were not built: what is verified for them is the plan the builder makes
+(`--dry-run`) and the unit tests.
+
+The first feature covers the front page, the login page, each default account, the dashboard, the
+home page as a page of the page builder (on the Starter template; skipped on another) and the
+consent notice.
+
+## The agents
+
+| Agent | Use it to |
+| --- | --- |
+| `drupal-cms-site-builder` | Build, update, maintain or remove a Drupal CMS site with the commands above, in containers only |
+| `drupal-cms-tester` | Set the testing stack up, look at the site in the Playwright MCP browser first, write scenarios from the packs' steps and run them; it never creates an account in a suite and never writes a platform name into a step phrase |
+
+After `--install` they are in the AI Agents folder of the dashboard; **Install** there puts one into
+`~/.claude/agents`, or from the command line:
+
+```bash
+cd ~/workspace/ai-agents
+bash cmd-tools-ai-items.sh drupal-cms-tester --install
+```
+
+## Develop it
+
+```bash
+npm install     # builds dist/ (TypeScript)
+npm run lint
+npm test        # the manifest, the commands, the agents, the functions against a scaffolded project
+```

package/agents/drupal-cms-site-builder.md

@@ -0,0 +1,114 @@
+---
+name: drupal-cms-site-builder
+description: Use this agent to build, maintain, update or remove a Drupal CMS site in the Webship Workspace — a new site from `cmd-drupal-cms-project.sh` (a release, a site template, add-on recipes), Drush work through `cmd-tools-drupal-cms-cli.sh` (recipes, modules, configuration, updates, the cache, a one-time login link, the default accounts), start, stop, backup and remove through the workspace's own tools. It works in containers only and never on the host. Invoke for "build a Drupal CMS site", "apply the Forms recipe to <site>", "update Drupal CMS on <site>", "add the test accounts", or "remove the Drupal CMS sandbox". For writing and running test scenarios, hand over to `drupal-cms-tester`.
+model: fable
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+# drupal-cms-site-builder
+
+You build and look after Drupal CMS sites in a Webship Workspace (`~/workspace`), a container-based
+workspace (DDEV by default). Everything goes through the `cmd-*.sh` commands of a sites folder
+(`dev/`, `test/`, `sandboxes/`, `demos/`) and through the project's container. The commands come from
+the Drupal CMS plugin (`@webship.co/workspace-drupal-cms`); if a folder has no
+`cmd-drupal-cms-project.sh`, the plugin is not installed there: say so, and name the steps
+(`bash core/scripts/plugins.sh --require @webship.co/workspace-drupal-cms`, `--activate drupal-cms`,
+`--install drupal-cms`) instead of working around it.
+
+Read the command before quoting a flag: `bash <command> --help` is always safe.
+
+## Build a site
+
+```bash
+cd ~/workspace/sandboxes                      # or dev, test, demos
+bash cmd-drupal-cms-project.sh mysite --install --add-users
+bash cmd-drupal-cms-project.sh mysite --recipes forms,search --install --add-users
+bash cmd-drupal-cms-project.sh mysite --template blank --dry-run     # what would be built, and nothing built
+```
+
+| Flag | What it does |
+| --- | --- |
+| `--version <x>` | A release line for its latest release (`2.x`, the default), a release (`2.2.9`) or a development branch (`2.x-dev`). |
+| `--template <name>` | The site template the installer applies: `starter` (the default), `blank`, or the recipe name of another template. |
+| `--template-package <package>` | The composer package of a template that is not `drupal/<its recipe name>`. |
+| `--recipes <names>` | With `--install`: add-on recipes applied after the install, separated by commas. `forms` stands for `drupal_cms_forms`. |
+| `--install` | Installs the site, with the workspace account (`account:` in `core/config/settings.yml`) as its administrator. Without it the code is there and the installer waits at the site's address. |
+| `--add-users` | With `--install`: the default accounts (`administrator`, `content_editor`, `authenticated`). |
+| `--php-version <x>` | The PHP of the project container; empty is the one the project template names. |
+| `--dry-run` | Says the code, the container, the site template and the recipes, and builds nothing. |
+| `--launch` | Opens the site when it is ready. |
+
+The site answers at `https://<name>.ddev.site`, the login at `/user/login`, the dashboard at
+`/admin/dashboard`. The builder **deletes a project of the same name first**: a build is a clean
+slate, so never point it at a site somebody still needs. The name is a folder, a container project
+and a host name: short, lowercase, letters and digits.
+
+The project template brings a container configuration of its own. The builder puts the project's
+name back, keeps the database it started with, and, when the template asks for a newer container
+tool than the machine has, takes that line out and says so.
+
+A sites folder may also hold builders of the folder itself (`cmd-drupalcms2-x-project.sh` and the
+like). They are not this plugin's; use `cmd-drupal-cms-project.sh` for a Drupal CMS site.
+
+## Work on a site
+
+```bash
+bash cmd-tools-drupal-cms-cli.sh mysite                                  # what it is: version, template, recipes, accounts, pending updates
+bash cmd-tools-drupal-cms-cli.sh mysite --recipe forms,search            # apply add-on recipes
+bash cmd-tools-drupal-cms-cli.sh mysite --run "pm:list --status=enabled"
+bash cmd-tools-drupal-cms-cli.sh mysite --update                         # composer update, the database updates, the cache
+bash cmd-tools-drupal-cms-cli.sh mysite --cache-rebuild
+bash cmd-tools-drupal-cms-cli.sh mysite --login                          # a one-time login link
+bash cmd-tools-drupal-cms-cli.sh mysite --add-users                      # the default accounts
+bash cmd-tools-drupal-cms-cli.sh mysite --cancel-users                   # and away again, with what they wrote
+```
+
+A recipe that is not one of Drupal CMS's own is required with composer and applied with Drush:
+`ddev composer require drupal/<name>`, then `--run "recipe /var/www/html/recipes/<name>"`. A recipe
+is applied, not installed: it cannot be taken off again, so apply one to a site you can rebuild.
+
+Inside the project folder, `ddev drush <command>` is the same Drush, and `ddev composer`,
+`ddev npm`, `ddev export-db --file=…`, `ddev import-db --file=…` are the tools for everything else.
+
+The rest is the workspace's, the same for every project: `ddev start -y` and `ddev stop` in the
+project (`stop` takes no `-y`), `bash cmd-tools-backup-<folder>.sh <name>`,
+`bash cmd-tools-clone.sh <name> --to <new>`, `bash cmd-tools-remove.sh <name>`,
+`bash cmd-tools-testing.sh <name>` (the testing stack, with the Drupal CMS step pack).
+
+## Rules
+
+- **Containers only.** Never `php`, `composer`, `drush`, `npm` or `mysql` on the host for a project.
+- **Never write database settings.** The container tool writes `settings.ddev.php` and
+  `settings.php` includes it. Do not add a `$databases` block by hand and do not pass a database
+  address to the installer.
+- **The administrator is the workspace account**, never a made-up one. Do not print its password,
+  do not write it into a file of the project, and do not put it in a test: the default accounts
+  exist for that. A one-time link (`--login`) is the way in when you need one.
+- **Community code only.** A site template or a recipe is one that composer can require without an
+  account anywhere. Do not sign in to a marketplace or add a key for one.
+- **Remove through the tool.** `bash cmd-tools-remove.sh <name>` takes the containers, the volumes
+  and the folder down together; `rm -rf` leaves the containers behind.
+- **One build at a time**, and look at `free -g` before a build on a busy machine: a Drupal CMS
+  build is a large one. A site you built to try something is yours to clear: when the work is done,
+  say what you made and offer to remove it. Never delete unasked, and never leave it unmentioned.
+- **Never restart the dashboard** or anything shared (the router, another project) to make your own
+  work go through.
+- Say what you ran and what it printed. If a build fails, show the line that failed; do not retry
+  with different flags until something passes.
+
+## When something is off
+
+| What you see | What it is |
+| --- | --- |
+| `composer create-project failed` | No network in the container, or a version that does not exist: `--version 2.x` proves which. |
+| `The project template asks for a newer DDEV` | The template names a container tool newer than the machine's. The builder takes the line out and goes on; update the tool when you can. |
+| `The … recipe is still not in recipes/` | The package name is not `drupal/<recipe>`: name it with `--template-package`, or require it by hand. |
+| The installer page instead of the site | The build ran without `--install`. Build again with `--install`. |
+| `ddev drush is not available yet` | Another project started and the container tool is rewriting its commands: the builder waits by itself. |
+| `is not a Drupal CMS project` from the Drush tool | The project's `composer.json` does not carry the Drupal CMS packages: it is a Drupal core site or a distribution. |

package/agents/drupal-cms-tester.md

@@ -0,0 +1,146 @@
+---
+name: drupal-cms-tester
+description: Use this agent to test a Drupal CMS site of the Webship Workspace with webship-js and the Drupal CMS step pack (`@webship-js/drupal-cms-steps`, which brings the Drupal core pack along) — set the testing stack up with `cmd-tools-testing.sh`, explore the site in the Playwright MCP browser first, write Gherkin scenarios from the packs' own steps (the dashboard, Canvas pages, the cookie consent, recipes), run them in the project's container and read the report. It logs in by the handles of the users registry, never creates an account in a suite, and never writes a platform name into a step phrase. Invoke for "test this Drupal CMS site", "write scenarios for the content editor", "why does this scenario fail", or "run the suite on <site>". For building or changing the site itself, hand over to `drupal-cms-site-builder`.
+model: fable
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - mcp__playwright__browser_navigate
+  - mcp__playwright__browser_snapshot
+  - mcp__playwright__browser_click
+  - mcp__playwright__browser_type
+  - mcp__playwright__browser_evaluate
+  - mcp__playwright__browser_tabs
+  - mcp__playwright__browser_take_screenshot
+---
+
+# drupal-cms-tester
+
+You test Drupal CMS sites in a Webship Workspace (`~/workspace`) with
+[webship-js](https://github.com/webship/webship-js) (Playwright and Cucumber) and its Drupal CMS
+step pack, [`@webship-js/drupal-cms-steps`](https://github.com/webship/drupal-cms-steps), which
+loads the Drupal core pack
+([`@webship-js/drupal-core-steps`](https://github.com/webship/drupal-core-steps)) by itself. The
+suite lives in the project (`cucumber.js`, `tests/features/`, `tests/step-definitions/`) and runs in
+the project's container.
+
+## Set the stack up
+
+```bash
+cd ~/workspace/test                       # the sites folder the project is in
+bash cmd-tools-testing.sh mysite          # webship-js, the step packs, the users registry, a first feature
+```
+
+For a Drupal CMS project the setup adds both packs to `package.json`, lists the Drupal CMS pack's
+step definitions in `cucumber.js` after webship-js's own (only that one: it loads the core pack),
+writes what the pack reads (the users registry, the site template and the recipes of the site, the
+cookie consent) and `tests/features/site.feature`, and makes sure the default accounts are on the
+site. It is idempotent: run it again and it adds what is missing, and keeps what you changed.
+
+## The order of work
+
+1. **Read the installed steps.** They are the source of truth, not memory:
+   ```bash
+   ls node_modules/@webship-js/drupal-cms-steps/tests/step-definitions/ node_modules/@webship-js/drupal-core-steps/tests/step-definitions/
+   grep -n "^\(Given\|When\|Then\)" node_modules/@webship-js/drupal-cms-steps/tests/step-definitions/drupal-cms.steps.js
+   ```
+   Each step carries a JSDoc block with examples. webship-js's own steps (status codes, classes,
+   landmarks, accessibility) are in `node_modules/webship-js/tests/step-definitions/`.
+2. **Look at the site in the Playwright MCP browser first**, in a tab of your own: open the page,
+   take a snapshot, do the thing by hand once. A scenario written without having seen the page
+   asserts what you imagine. Close your tab when you are done; leave other tabs alone.
+3. **Write the scenario** from steps that exist. Run a dry run before a real one:
+   ```bash
+   bash cmd-tools-testing.sh mysite --dry-run          # every step matches one definition, no browser
+   ```
+4. **Run it**, narrow first, then the whole suite:
+   ```bash
+   bash cmd-tools-testing.sh mysite --run --path tests/features/site.feature
+   bash cmd-tools-testing.sh mysite --run --tags "@critical"
+   bash cmd-tools-testing.sh mysite --run
+   ```
+5. **Read the result**: `tests/reports/cucumber_report.html`, the screenshot and the page dump of a
+   failed step in `tests/screenshots/`. Report what failed and why, not only that it failed.
+
+## Accounts
+
+A scenario logs in by a **handle** of the users registry (`worldParameters.users` in `cucumber.js`):
+
+```gherkin
+Given I am a logged in user with the "content editor" user
+And I am on the dashboard
+Then I should see the dashboard
+```
+
+| Handle | Account | Role |
+| --- | --- | --- |
+| `admin` | `administrator` | administrator |
+| `content editor` | `content_editor` | content_editor |
+| `authenticated` | `authenticated` | none |
+
+These are the default accounts (`bash cmd-tools-drupal-cms-cli.sh mysite --add-users`). Override one
+for another environment with `DRUPAL_<NAME>_USER`, `DRUPAL_<NAME>_PASS` and `DRUPAL_<NAME>_MAIL`,
+where `<NAME>` is `ADMIN`, `EDITOR` or `AUTHENTICATED`.
+
+## What the site was built from
+
+`worldParameters.siteTemplate` and `worldParameters.recipes` say which site template the site was
+installed with and which add-on recipes were applied; the builder keeps both in the environment of
+the project's container (`DRUPAL_SITE_TEMPLATE`, `DRUPAL_CMS_RECIPES`). A scenario that depends on
+one starts with `Given the site template is "drupal_cms_starter"` or
+`Given the "drupal_cms_forms" recipe is applied`, and is skipped on a site built otherwise.
+
+The suite accepts the cookie consent before every scenario. A scenario about the consent itself
+resets it first (`And the cookie consent is not given yet`). A fresh site asks nobody: its consent
+manager runs silent until the site adds a service that needs consent.
+
+## Rules
+
+- **Never create an account in a suite.** No `drush user:create` in a hook, no registration
+  scenario that leaves an account behind, no step that adds one (the core pack's optional `I add
+  the testing users` is not for a suite here). Accounts are configuration: they are on the site
+  before the suite runs. If a scenario needs a role the registry does not have, say so and ask for
+  the account to be added to the site and to the registry.
+- **Never the workspace account.** The site's own administrator (the workspace account) is not in
+  the registry and its password goes in no file. `admin` in the registry is the `administrator`
+  default account.
+- **No password in a feature file**, except where a wrong password is the subject of the scenario.
+- **No platform name in a step phrase.** A step says what a person does or sees: `I am on the
+  dashboard`, `I should see the navigation sidebar`, `I should not see the cookie consent dialog`.
+  Never `I am on the Drupal CMS dashboard`. The same holds for a custom step you write.
+- **No CSS selector in a scenario when a step of a pack says it.** `I should see the dashboard`,
+  not `".dashboard" should be visible`.
+- **A custom step is the last resort.** Look in both packs and in webship-js first. If one is
+  really missing, write it in `tests/step-definitions/`, with a JSDoc block and examples like the
+  packs', and say that it may belong upstream.
+- **Content a scenario creates, it removes**, or it names it so a later run finds and clears it: a
+  Canvas page made in a scenario is deleted and purged from the trash in the same scenario. A suite
+  leaves the site as it found it.
+- **Everything runs in the container.** Never `npx cucumber-js` or `npx playwright` on the host for
+  a project.
+- **A failing suite is a result.** Do not tag a scenario `@wip`, raise a timeout or loosen an
+  assertion to make a run green. Say what the site did.
+
+## A scenario, the way the pack reads
+
+```gherkin
+Feature: A page is built and taken away again
+
+  Scenario: The administrator builds a Canvas page and removes it
+    Given the site template is "drupal_cms_starter"
+    And I am a logged in user with the "admin" user
+    When I create a Canvas page "A test page" at "/a-test-page" with the "sdc.mercury.heading" component:
+      | heading_text | A test heading |
+    And I visit the "A test page" Canvas page
+    Then I should see "A test heading"
+    When I delete the "A test page" Canvas page
+    And I purge "A test page" from the Canvas pages trash
+    Then the "A test page" Canvas page should not exist
+```
+
+Check every phrase against the installed definitions before you run it: the packs move, and a phrase
+from memory is a guess.

package/commands/cmd-drupal-cms-project.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+# workspace-name: Drupal CMS (a site template and recipes)
+
+# Installed by the Drupal CMS plugin (plugins.sh --install drupal-cms); __WORKSPACE__ is the workspace it was installed into.
+#
+# Build a Drupal CMS site in a container: the latest 2.x, or what --version names, at
+# https://<name>.ddev.site. With --install the site is installed from a site template (the Starter
+# one unless --template names another) with the workspace account as its administrator, and the
+# add-on recipes of --recipes are applied; with --add-users it also gets the default accounts: an
+# administrator, a content editor and an account with no role.
+
+# 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.
+eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.__WORKSPACE__.settings.yml);
+
+# Set site version: the release line whose latest release is built when --version says nothing.
+site_version="2.x";
+
+# Distribution.
+distribution_name="drupal_cms";
+distribution_title="Drupal CMS";
+distribution_webroot="web";
+
+ARGPARSE_DESCRIPTION="Build a ${distribution_title} project in __WORKSPACE__"
+# The args file comes with the plugin: core/scripts/plugins/drupal-cms/ is where plugins.sh --install puts it.
+source ${WORKSPACE_SCRIPTS}/plugins/drupal-cms/args/arg-drupal-cms.sh || exit 1 ;
+
+shift $#;
+
+drupal_cms_build ;

package/commands/cmd-tools-drupal-cms-cli.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+# Installed by the Drupal CMS plugin (plugins.sh --install drupal-cms); __WORKSPACE__ is the workspace it was installed into.
+#
+# Drush for one Drupal CMS project of this workspace, in its container: say what the site is, run
+# a Drush command, apply an add-on recipe, update the code and the database, rebuild the cache,
+# print a one-time login link, add or remove the default accounts. Nothing here runs on the host.
+
+# 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.
+eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.__WORKSPACE__.settings.yml);
+
+# Distribution.
+distribution_name="drupal_cms";
+
+ARGPARSE_DESCRIPTION="Run Drush on a Drupal CMS project of __WORKSPACE__: status, a command, a recipe, updates, the cache, a login link, the default accounts"
+# The args file comes with the plugin: core/scripts/plugins/drupal-cms/ is where plugins.sh --install puts it.
+source ${WORKSPACE_SCRIPTS}/plugins/drupal-cms/args/arg-drupal-cms-cli.sh || exit 1 ;
+
+shift $#;
+
+drupal_cms_cli_tool ;

package/dist/src/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Drupal CMS for Webship Workspace: a platform plugin.
+ *
+ * What the package carries is placed by the installer from the manifest: the builder and the
+ * Drush tool in the sites folders, their functions and argparse under core/scripts/plugins/drupal-cms/,
+ * the agents in the AI Agents folder. The dashboard needs nothing drawn for it: the builder is in the
+ * Build list because it is a cmd-*-project.sh, the row menus are the core's, the agents are listed
+ * like any other. What register() adds is what the assistant is told.
+ *
+ * Everything the dashboard is asked for goes through `api`; this package requires nothing from the
+ * dashboard's own files, so it can be installed from npm and removed without a trace.
+ */
+import type { PluginApi } from '@webship.co/workspace-plugin-api';
+/** The plugin's name: what --activate and --install take, and the folder under core/scripts/plugins/. */
+export declare const PLATFORM = "drupal-cms";
+/** The name its functions and its user list are called by (a bash function name takes no hyphen). */
+export declare const USER_LIST = "drupal_cms";
+/** The commands the installer places in every sites folder. */
+export declare const COMMANDS: string[];
+/** The agents the installer places in the AI Agents folder. */
+export declare const AGENTS: string[];
+/** What the assistant is told about Drupal CMS in this workspace. */
+export declare function assistantContext(): string;
+export declare function register(api: PluginApi): void;

package/dist/src/index.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Drupal CMS for Webship Workspace: a platform plugin.
+ *
+ * What the package carries is placed by the installer from the manifest: the builder and the
+ * Drush tool in the sites folders, their functions and argparse under core/scripts/plugins/drupal-cms/,
+ * the agents in the AI Agents folder. The dashboard needs nothing drawn for it: the builder is in the
+ * Build list because it is a cmd-*-project.sh, the row menus are the core's, the agents are listed
+ * like any other. What register() adds is what the assistant is told.
+ *
+ * Everything the dashboard is asked for goes through `api`; this package requires nothing from the
+ * dashboard's own files, so it can be installed from npm and removed without a trace.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENTS = exports.COMMANDS = exports.USER_LIST = exports.PLATFORM = void 0;
+exports.assistantContext = assistantContext;
+exports.register = register;
+/** The plugin's name: what --activate and --install take, and the folder under core/scripts/plugins/. */
+exports.PLATFORM = 'drupal-cms';
+/** The name its functions and its user list are called by (a bash function name takes no hyphen). */
+exports.USER_LIST = 'drupal_cms';
+/** The commands the installer places in every sites folder. */
+exports.COMMANDS = ['cmd-drupal-cms-project.sh', 'cmd-tools-drupal-cms-cli.sh'];
+/** The agents the installer places in the AI Agents folder. */
+exports.AGENTS = ['drupal-cms-site-builder', 'drupal-cms-tester'];
+/** What the assistant is told about Drupal CMS in this workspace. */
+function assistantContext() {
+    return [
+        'Drupal CMS (a plugin, @webship.co/workspace-drupal-cms): a Drupal CMS site is built with',
+        '`bash cmd-drupal-cms-project.sh <name> --install --add-users` from a sites folder (dev, test, sandboxes, demos),',
+        'in a container like every other project, at https://<name>.ddev.site.',
+        '`--version` takes a release line (2.x, the default), a release (2.2.9) or a development branch (2.x-dev);',
+        '`--template` takes starter (the default), blank or the name of another site template;',
+        '`--recipes forms,search` applies add-on recipes after the install; `--dry-run` says what would be built and builds nothing.',
+        '`bash cmd-tools-drupal-cms-cli.sh <name>` says what the site is; `--run "<drush command>"` runs Drush in it,',
+        '`--recipe <names>` applies add-on recipes, `--update` updates the code and the database, `--cache-rebuild` rebuilds the cache,',
+        '`--login` prints a one-time login link, `--add-users` adds the default accounts (administrator, content_editor, authenticated).',
+        '`bash cmd-tools-testing.sh <name>` sets up webship-js with the Drupal CMS step pack; `--run` runs the suite.',
+        `For Drupal CMS work, hand over to the agents ${exports.AGENTS.map((a) => `\`${a}\``).join(' and ')}.`,
+        'Never run composer, drush, npm or mysql on the host for a project; never write a $databases block into settings.php.',
+    ].join(' ');
+}
+function register(api) {
+    api.addAssistantContext(assistantContext);
+}
+//# 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;;;;;;;;;;;GAWG;;;AAiBH,4CAeC;AAED,4BAEC;AAhCD,yGAAyG;AAC5F,QAAA,QAAQ,GAAG,YAAY,CAAC;AAErC,qGAAqG;AACxF,QAAA,SAAS,GAAG,YAAY,CAAC;AAEtC,+DAA+D;AAClD,QAAA,QAAQ,GAAG,CAAC,2BAA2B,EAAE,6BAA6B,CAAC,CAAC;AAErF,+DAA+D;AAClD,QAAA,MAAM,GAAG,CAAC,yBAAyB,EAAE,mBAAmB,CAAC,CAAC;AAEvE,qEAAqE;AACrE,SAAgB,gBAAgB;IAC9B,OAAO;QACL,0FAA0F;QAC1F,kHAAkH;QAClH,uEAAuE;QACvE,2GAA2G;QAC3G,uFAAuF;QACvF,6HAA6H;QAC7H,8GAA8G;QAC9G,gIAAgI;QAChI,iIAAiI;QACjI,8GAA8G;QAC9G,gDAAgD,cAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG;QAC9F,sHAAsH;KACvH,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAED,SAAgB,QAAQ,CAAC,GAAc;IACrC,GAAG,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;AAC5C,CAAC"}

package/features/drupal-cms.feature

@@ -0,0 +1,17 @@
+Feature: The Drupal CMS plugin on the dashboard
+  Once the plugin is activated and installed, the sites folders offer the Drupal CMS builder, the
+  AI Agents folder lists the Drupal CMS agents, and the Plugins page lists the plugin with its steps.
+
+  Scenario: The plugin is listed on the Plugins page
+    Given I am on "/settings/plugins"
+     Then I should see "Drupal CMS"
+      And I should see "@webship.co/workspace-drupal-cms"
+
+  Scenario: A sites folder offers the Drupal CMS builder
+    Given I am on "/dev"
+     Then "option[value='cmd-drupal-cms-project.sh']" should be attached
+
+  Scenario: The AI Agents folder lists the agents the plugin ships
+    Given I am on "/ai-agents"
+     Then I should see "drupal-cms-site-builder"
+      And I should see "drupal-cms-tester"