@webship.co/workspace-joomla 0.0.0-stage → 1.0.7

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# @webship.co/workspace-joomla
 
-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.
+Joomla for the [Webship Workspace](https://github.com/webship/workspace) dashboard: a builder
+that makes a real Joomla site in a container, a Joomla CLI tool for the sites it built, the default
+accounts, the [Joomla step pack](https://github.com/webship/joomla-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 Joomla 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).
+
+## Use it
+
+```bash
+cd ~/workspace
+bash core/scripts/plugins.sh --require github:webship/workspace-joomla   # npm install into the dashboard
+bash core/scripts/plugins.sh --activate joomla                            # plugins.joomla in settings.yml
+bash core/scripts/plugins.sh --install joomla                             # commands, functions, args, agents
+bash core/scripts/plugins.sh --configure joomla                           # 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-joomla-project.sh` | The builder, in the Build list as **Joomla (latest)**, installed into every sites folder |
+| `commands/cmd-tools-joomla-cli.sh` | The Joomla CLI for one project: what the site is, a command, updates, the default accounts |
+| `scripts/functions/fun-joomla.sh` | The bash functions behind both, sourced by bootstrap once installed; the names the core's tools look for (`set_joomla_users`, `add_joomla_users`, `cancel_joomla_users`, `testing_configure_joomla`) |
+| `scripts/args/arg-joomla.sh`, `arg-joomla-cli.sh` | Their argparse; the Build form draws the builder's flags from the first |
+| `testing/site.feature` | The first feature a Joomla project gets when testing is set up |
+| `agents/joomla-site-builder.md` | The agent that builds and maintains Joomla sites with these commands |
+| `agents/joomla-tester.md` | The agent that writes and runs scenarios with the Joomla step pack |
+| `src/index.ts` | `register(api)`: what the assistant is told about Joomla here |
+| `features/joomla.feature` | Scenarios for the dashboard's own browser suite |
+
+The `workspacePlugin` block in `package.json` is the manifest the installer reads.
+
+## The commands
+
+Run them from a sites folder. `--help` is safe on both.
+
+### Build a site
+
+```bash
+cd ~/workspace/dev
+bash cmd-joomla-project.sh mysite --install --add-users
+```
+
+| Flag | What it does |
+| --- | --- |
+| `--version <x>` | The release to download: `latest` (the default: the latest stable release), or a number such as `6.2.0` |
+| `--install` | Install the site, with the workspace account as its Super User |
+| `--add-users` | With `--install`: add the default accounts, one per user group |
+| `--sample-data` | With `--install`: add the blog sample data of Joomla, and build the Smart Search index over it |
+| `--php-version <x>` | The PHP of the project container (`8.3`) |
+| `--launch` | Open the site when it is ready |
+
+The site answers at `https://mysite.ddev.site`, the administrator at `/administrator`. The container
+tool has no project type for Joomla, so the build runs `ddev config --project-type=php` with the
+docroot `public` and the Node.js of the workspace (24), downloads the full package of the release
+and unpacks it in the container, and installs with Joomla's own command-line installer. The
+installer is given the container's database values (`db` / `db` / `db`), the same in every project,
+and nothing personal. A project of the same name is deleted first.
+
+Joomla refuses a password shorter than 12 characters: `--install` stops before it starts when the
+workspace account's is shorter.
+
+### Work on a site
+
+```bash
+bash cmd-tools-joomla-cli.sh mysite                                    # version, address, accounts
+bash cmd-tools-joomla-cli.sh mysite --run "extension:list --type=plugin"
+bash cmd-tools-joomla-cli.sh mysite --run "list"                       # every command of the Joomla CLI
+bash cmd-tools-joomla-cli.sh mysite --check                            # look for updates of the core and the extensions
+bash cmd-tools-joomla-cli.sh mysite --update                           # update the core, clean the cache
+bash cmd-tools-joomla-cli.sh mysite --add-users                        # the default accounts
+bash cmd-tools-joomla-cli.sh mysite --cancel-users                     # delete them
+```
+
+### The default accounts
+
+| Account | User group | Handle in the tests | Logs in to |
+| --- | --- | --- | --- |
+| `administrator` | Super Users | `admin` | the administrator and the site |
+| `manager` | Manager | `manager` | the administrator and the site |
+| `editor` | Editor | `editor` | the site |
+| `member` | Registered | `member` | the site |
+
+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 Super User is the workspace
+account and is never written into a test. `bash cmd-tools-add-users.sh mysite joomla` and
+`bash cmd-tools-cancel-users.sh mysite joomla` add and remove the same list.
+
+The **Users** menu of a project row does not add them: the dashboard reads the user list of a row
+from the DDEV project type, and a Joomla project is a `php` project, because the container tool has
+no type for Joomla. Use the CLI tool or the two commands above.
+
+### Test a site
+
+```bash
+bash cmd-tools-testing.sh mysite                 # webship-js, the step pack, 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 Joomla project it also adds
+`@webship-js/joomla-steps` to `package.json`, lists its step definitions in `cucumber.js` after
+webship-js's own, writes the users registry (the handles above, overridable with
+`JOOMLA_<HANDLE>_USER` and `JOOMLA_<HANDLE>_PASSWORD`), 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.
+
+## The agents
+
+| Agent | Use it to |
+| --- | --- |
+| `joomla-site-builder` | Build, update, maintain or remove a Joomla site with the commands above, in containers only |
+| `joomla-tester` | Set the testing stack up, look at the site in the Playwright MCP browser first, write scenarios from the pack's 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 joomla-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/joomla-site-builder.md

@@ -0,0 +1,105 @@
+---
+name: joomla-site-builder
+description: Use this agent to build, maintain, update or remove a Joomla site in the Webship Workspace — a new site from `cmd-joomla-project.sh`, Joomla CLI work through `cmd-tools-joomla-cli.sh` (extensions, configuration, cache, updates, 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 Joomla site", "install this extension on <site>", "update Joomla on <site>", "add the test accounts", or "remove the Joomla sandbox". For writing and running test scenarios, hand over to `joomla-tester`.
+model: fable
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+# joomla-site-builder
+
+You build and look after Joomla 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 Joomla plugin (`@webship.co/workspace-joomla`); if a folder has no
+`cmd-joomla-project.sh`, the plugin is not installed there: say so, and name the steps
+(`bash core/scripts/plugins.sh --require @webship.co/workspace-joomla`, `--activate joomla`,
+`--install joomla`) 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-joomla-project.sh mysite --install --add-users
+```
+
+| Flag | What it does |
+| --- | --- |
+| `--version <x>` | The release to download: `latest` (the default: the latest stable release), or a number such as `6.2.0`. |
+| `--install` | Installs the site, with the workspace account (`account:` in `core/config/settings.yml`) as its Super User. Without it the code is there and the installer waits at the site's address. |
+| `--add-users` | With `--install`: the default accounts, one per user group (`administrator`, `manager`, `editor`, `member`). |
+| `--sample-data` | With `--install`: the blog sample data of Joomla (articles, a menu, modules), and the Smart Search index built over it. |
+| `--php-version <x>` | The PHP of the project container (`8.3` by default; Joomla 6 needs 8.3 or later). |
+| `--launch` | Opens the site when it is ready. |
+
+The site answers at `https://<name>.ddev.site`, the administrator at `/administrator`. The code is
+in the `public/` folder of the project. 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.
+
+Joomla refuses a password shorter than 12 characters. When the workspace account's is shorter the
+builder says so before it starts: do not invent another password, ask for the setting to be changed.
+
+## Work on a site
+
+```bash
+bash cmd-tools-joomla-cli.sh mysite                                  # what it is: version, address, accounts
+bash cmd-tools-joomla-cli.sh mysite --run "extension:list --type=plugin"
+bash cmd-tools-joomla-cli.sh mysite --run "config:get sitename"
+bash cmd-tools-joomla-cli.sh mysite --run "cache:clean"
+bash cmd-tools-joomla-cli.sh mysite --check                          # look for updates, change nothing
+bash cmd-tools-joomla-cli.sh mysite --update                         # the core, to the latest release of its line
+bash cmd-tools-joomla-cli.sh mysite --add-users                      # the default accounts
+bash cmd-tools-joomla-cli.sh mysite --cancel-users                   # and away again
+```
+
+`--run "list"` prints every command the site's Joomla CLI has. Inside the project folder,
+`ddev exec php public/cli/joomla.php <command>` is the same CLI, 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-add-users.sh <name> joomla`, `bash cmd-tools-testing.sh <name>` (the testing
+stack, with the Joomla step pack).
+
+## Rules
+
+- **Containers only.** Never `php`, `composer`, `npm` or `mysql` on the host for a project.
+- **The database values are the container's.** The installer is given `db` / `db` / `db` on the
+  host `db`, the same in every project. Do not put another host, account or password into
+  `configuration.php`, and do not copy that file between projects.
+- **The Super User 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.
+- **Open-source only.** Extensions come from the Joomla Extensions Directory or a public
+  repository, as a package the CLI installs (`extension:install --url=…`). No paid extension, no
+  trial, no licence key, and no sign-in to any vendor account.
+- **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 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 |
+| --- | --- |
+| `The Joomla <x> package could not be downloaded or unpacked` | No network in the container, or a version that does not exist: `--version latest` proves which. |
+| `Joomla asks for a password of 12 characters or more` | The workspace account's password is too short for Joomla: it is changed in `core/config/settings.yml`, by its owner. |
+| The installer page instead of the site | The build ran without `--install`: finish it in the browser, or build again with `--install`. |
+| `Error displaying the error page` or a database error | The project is stopped (`ddev start -y`), or `configuration.php` was replaced: its database values are `db` / `db` / `db` on the host `db`. |
+| The site search finds nothing | The Smart Search index is empty: `--run "finder:index"`. |
+| **Add the test users** in the row's Users menu adds no Joomla account | The menu reads the DDEV project type, and a Joomla project is a `php` project. Use `bash cmd-tools-joomla-cli.sh <name> --add-users` or `bash cmd-tools-add-users.sh <name> joomla`. |
+| `is not a Joomla project` from the CLI tool | The project's docroot has no `cli/joomla.php`: it was not built by this builder. |

package/agents/joomla-tester.md

@@ -0,0 +1,126 @@
+---
+name: joomla-tester
+description: Use this agent to test a Joomla site of the Webship Workspace with webship-js and the Joomla step pack (`@webship-js/joomla-steps`) — set the testing stack up with `cmd-tools-testing.sh`, explore the site in the Playwright MCP browser first, write Gherkin scenarios from the pack's own steps, 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 Joomla site", "write scenarios for the manager group", "why does this scenario fail", or "run the suite on <site>". For building or changing the site itself, hand over to `joomla-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
+---
+
+# joomla-tester
+
+You test Joomla sites in a Webship Workspace (`~/workspace`) with
+[webship-js](https://github.com/webship/webship-js) (Playwright and Cucumber) and its Joomla step
+pack, [`@webship-js/joomla-steps`](https://github.com/webship/joomla-steps). 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 pack, the users registry, a first feature
+```
+
+For a Joomla project the setup adds the pack to `package.json`, lists its step definitions in
+`cucumber.js` after webship-js's own, writes the users registry 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/joomla-steps/tests/step-definitions/
+   grep -n "^\(Given\|When\|Then\)" node_modules/@webship-js/joomla-steps/tests/step-definitions/joomla.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`).
+The site and the administrator have a login each, and a step for each:
+
+```gherkin
+Given I am a logged in user with the "manager" user        # the administrator
+Given I am logged in to the site with the "member" user    # the site
+```
+
+| Handle | Account | User group | Logs in to |
+| --- | --- | --- | --- |
+| `admin` | `administrator` | Super Users | the administrator and the site |
+| `manager` | `manager` | Manager | the administrator and the site |
+| `editor` | `editor` | Editor | the site |
+| `member` | `member` | Registered | the site |
+
+These are the default accounts (`bash cmd-tools-joomla-cli.sh mysite --add-users`). Override one
+for another environment with `JOOMLA_<HANDLE>_USER` and `JOOMLA_<HANDLE>_PASSWORD`. A step that
+names an account on a list (`the user "manager" should be in the "Manager" group`) takes the
+account's username, not the handle.
+
+## Rules
+
+- **Never create an account in a suite.** No `user:add` in a hook, no registration scenario
+  that leaves an account behind, no step that adds one. Accounts are configuration: they are on the
+  site before the suite runs. If a scenario needs a group 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 Super User (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 login
+  page`, `I should see the administrator dashboard`, `I go to the administrator "Users" page`. Never
+  a phrase with the platform's name in it. The same holds for a custom step you write.
+- **No CSS selector and no address in a scenario when a step of the pack says it.** `the
+  administrator "Users" page`, not `/administrator/index.php?option=com_users`.
+- **A custom step is the last resort.** Look in the pack and in webship-js first. If one is really
+  missing, write it in `tests/step-definitions/`, with a JSDoc block and examples like the pack's,
+  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
+  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 manager looks after the articles
+
+  Scenario: The manager opens the list of articles
+    Given I am a logged in user with the "manager" user
+    When I go to the administrator "Articles" page
+    Then the response status code should be 200
+    And I should see the administrator menu
+```
+
+Check every phrase against the installed definitions before you run it: the pack moves, and a phrase
+from memory is a guess.

package/commands/cmd-joomla-project.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+
+# workspace-name: Joomla (latest)
+
+# Installed by the Joomla plugin (plugins.sh --install joomla); __WORKSPACE__ is the workspace it was installed into.
+#
+# Build a Joomla site in a container: the latest stable release, or the one --version names, at
+# https://<name>.ddev.site. With --install the site is installed with the workspace account as its
+# Super User; with --add-users it also gets the default accounts, one per user group.
+
+# 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.
+site_version="latest";
+
+# Distribution.
+distribution_name="joomla";
+distribution_title="Joomla";
+distribution_webroot="public";
+
+ARGPARSE_DESCRIPTION="Build a ${distribution_title} project in __WORKSPACE__"
+# The args file comes with the plugin: core/scripts/plugins/joomla/ is where plugins.sh --install puts it.
+source ${WORKSPACE_SCRIPTS}/plugins/joomla/args/arg-joomla.sh || exit 1 ;
+
+shift $#;
+
+joomla_build ;

package/commands/cmd-tools-joomla-cli.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+# Installed by the Joomla plugin (plugins.sh --install joomla); __WORKSPACE__ is the workspace it was installed into.
+#
+# The Joomla CLI (cli/joomla.php) for one Joomla project of this workspace, in its container: say
+# what the site is, run a CLI command, update the core, look for updates, 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="joomla";
+
+ARGPARSE_DESCRIPTION="Run the Joomla CLI on a Joomla project of __WORKSPACE__: status, a command, updates, the default accounts"
+# The args file comes with the plugin: core/scripts/plugins/joomla/ is where plugins.sh --install puts it.
+source ${WORKSPACE_SCRIPTS}/plugins/joomla/args/arg-joomla-cli.sh || exit 1 ;
+
+shift $#;
+
+joomla_cli_tool ;

package/dist/src/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Joomla for Webship Workspace: a platform plugin.
+ *
+ * What the package carries is placed by the installer from the manifest: the builder and the
+ * Joomla CLI tool in the sites folders, their functions and argparse under core/scripts/plugins/joomla/,
+ * 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, which its functions and its user list are named after. */
+export declare const PLATFORM = "joomla";
+/** 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 Joomla in this workspace. */
+export declare function assistantContext(): string;
+export declare function register(api: PluginApi): void;

package/dist/src/index.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Joomla for Webship Workspace: a platform plugin.
+ *
+ * What the package carries is placed by the installer from the manifest: the builder and the
+ * Joomla CLI tool in the sites folders, their functions and argparse under core/scripts/plugins/joomla/,
+ * 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.PLATFORM = void 0;
+exports.assistantContext = assistantContext;
+exports.register = register;
+/** The plugin's name, which its functions and its user list are named after. */
+exports.PLATFORM = 'joomla';
+/** The commands the installer places in every sites folder. */
+exports.COMMANDS = ['cmd-joomla-project.sh', 'cmd-tools-joomla-cli.sh'];
+/** The agents the installer places in the AI Agents folder. */
+exports.AGENTS = ['joomla-site-builder', 'joomla-tester'];
+/** What the assistant is told about Joomla in this workspace. */
+function assistantContext() {
+    return [
+        'Joomla (a plugin, @webship.co/workspace-joomla): a Joomla site is built with',
+        '`bash cmd-joomla-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 (the administrator at /administrator).',
+        '`bash cmd-tools-joomla-cli.sh <name>` says what the site is; `--run "<command>"` runs the Joomla CLI (cli/joomla.php) in it,',
+        '`--update` updates the core, `--check` looks for updates, `--add-users` adds the default accounts (one per user group).',
+        '`bash cmd-tools-add-users.sh <name> joomla` adds the same accounts.',
+        '`bash cmd-tools-testing.sh <name>` sets up webship-js with the Joomla step pack; `--run` runs the suite.',
+        `For Joomla work, hand over to the agents ${exports.AGENTS.map((a) => `\`${a}\``).join(' and ')}.`,
+        'Never run php, composer, npm or mysql on the host for a project.',
+    ].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;;;AAcH,4CAYC;AAED,4BAEC;AA1BD,gFAAgF;AACnE,QAAA,QAAQ,GAAG,QAAQ,CAAC;AAEjC,+DAA+D;AAClD,QAAA,QAAQ,GAAG,CAAC,uBAAuB,EAAE,yBAAyB,CAAC,CAAC;AAE7E,+DAA+D;AAClD,QAAA,MAAM,GAAG,CAAC,qBAAqB,EAAE,eAAe,CAAC,CAAC;AAE/D,iEAAiE;AACjE,SAAgB,gBAAgB;IAC9B,OAAO;QACL,8EAA8E;QAC9E,8GAA8G;QAC9G,6GAA6G;QAC7G,8HAA8H;QAC9H,yHAAyH;QACzH,qEAAqE;QACrE,0GAA0G;QAC1G,4CAA4C,cAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG;QAC1F,kEAAkE;KACnE,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/joomla.feature

@@ -0,0 +1,17 @@
+Feature: The Joomla plugin on the dashboard
+  Once the plugin is activated and installed, the sites folders offer the Joomla builder, the
+  AI Agents folder lists the Joomla 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 "Joomla"
+      And I should see "@webship.co/workspace-joomla"
+
+  Scenario: A sites folder offers the Joomla builder
+    Given I am on "/dev"
+     Then "option[value='cmd-joomla-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 "joomla-site-builder"
+      And I should see "joomla-tester"

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@webship.co/workspace-joomla",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.7",
+  "description": "Joomla for Webship Workspace: the builder (`cmd-joomla-project.sh`) and the Joomla CLI tool in every sites folder, the default accounts, the Joomla step pack wired into the testing setup, and two AI agents in the AI Agents folder.",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/webship/workspace-joomla.git"
+  },
+  "files": [
+    "dist/src",
+    "agents",
+    "commands",
+    "features",
+    "scripts",
+    "testing",
+    "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": "joomla",
+    "label": "Joomla",
+    "commands": {
+      "types": [
+        "sites"
+      ],
+      "workspaces": [
+        "dev",
+        "test",
+        "sandboxes",
+        "demos"
+      ],
+      "files": [
+        "commands/cmd-joomla-project.sh",
+        "commands/cmd-tools-joomla-cli.sh"
+      ]
+    },
+    "scripts": {
+      "functions": [
+        "scripts/functions/fun-joomla.sh"
+      ],
+      "args": [
+        "scripts/args/arg-joomla.sh",
+        "scripts/args/arg-joomla-cli.sh"
+      ],
+      "machine": [
+        "testing/site.feature"
+      ]
+    },
+    "ai": {
+      "agents": [
+        "agents/joomla-site-builder.md",
+        "agents/joomla-tester.md"
+      ]
+    },
+    "features": [
+      "features/joomla.feature"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@webship.co/workspace-plugin-api": "^1.0.7",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/args/arg-joomla-cli.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+parser.add_argument('PROJECT_NAME',
+                    help='The Joomla project in this workspace.')
+parser.add_argument('-r', '--run',
+                    default="_none_",
+                    help='A Joomla CLI command to run in the project, without the leading php cli/joomla.php. Example: --run "extension:list --type=plugin"')
+parser.add_argument('-u', '--update',
+                    action='store_true',
+                    default=False,
+                    help='Update Joomla itself to the latest release of its line, and clean the cache.')
+parser.add_argument('-k', '--check',
+                    action='store_true',
+                    default=False,
+                    help='Look for updates of Joomla and of its extensions, and change nothing.')
+parser.add_argument('-a', '--add-users',
+                    action='store_true',
+                    default=False,
+                    help='Add the default accounts, one per user group. An account that is already there is left as it is.')
+parser.add_argument('-c', '--cancel-users',
+                    action='store_true',
+                    default=False,
+                    help='Delete the default accounts.')
+ARGEOF

package/scripts/args/arg-joomla.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+parser.add_argument('PROJECT_NAME',
+                    help='The name of the project: its folder, its DDEV project and its host name.')
+parser.add_argument('-v', '--version',
+                    default="${site_version}",
+                    help='The Joomla release to download: latest, or a version number. Example: --version 6.2.0 [default %(default)s]')
+parser.add_argument('-i', '--install',
+                    action='store_true',
+                    default=False,
+                    help='Install Joomla, with the workspace account as the Super User.')
+parser.add_argument('-a', '--add-users',
+                    action='store_true',
+                    default=False,
+                    help='With --install, add the default accounts: one per user group, the ones the test scenarios log in as.')
+parser.add_argument('-s', '--sample-data',
+                    action='store_true',
+                    default=False,
+                    help='With --install, add the blog sample data of Joomla: articles, a menu and modules.')
+parser.add_argument('-l', '--launch',
+                    action='store_true',
+                    default=False,
+                    help='Open the site in a browser when it is ready.')
+parser.add_argument('--php-version',
+                    default="8.3",
+                    choices=['8.5', '8.4', '8.3'],
+                    help='PHP version for the project container. Example: --php-version 8.4 [default %(default)s]')
+ARGEOF

package/scripts/functions/fun-joomla.sh

@@ -0,0 +1,387 @@
+#!/usr/bin/env bash
+
+# Joomla for the Webship Workspace: build a site, run the Joomla CLI on it, add its default
+# accounts, and wire its step pack into the testing setup.
+#
+# Placed by `plugins.sh --install joomla` in core/scripts/plugins/joomla/functions/, where
+# bootstrap sources it after the core's own functions. Everything runs in the project's container
+# (DDEV by default: `ddev exec php <docroot>/cli/joomla.php …`), never on the host.
+#
+# The container tool has no project type for Joomla, so a Joomla project is a `php` project that
+# carries the Joomla CLI in its docroot; that file is how the functions here recognise one. The
+# installer is given the container's own database values (db / db / db) and nothing personal.
+#
+# Four names are the ones the core's tools look for:
+#   set_joomla_users        the default accounts          (cmd-tools-add-users.sh <project> joomla)
+#   add_joomla_users        create them with the Joomla CLI (the same tool, and --add-users of the builder)
+#   cancel_joomla_users     delete them                   (cmd-tools-cancel-users.sh <project> joomla)
+#   testing_configure_joomla  the step pack in the testing stack (cmd-tools-testing.sh <project>)
+
+# The step pack a Joomla project is tested with, and the release line it is required at.
+readonly JOOMLA_STEPS_PACKAGE='@webship-js/joomla-steps';
+readonly JOOMLA_STEPS_VERSION='^2.1.0';
+
+# The release a build falls back on when the latest one cannot be read: the one this plugin was proven on.
+readonly JOOMLA_PROVEN_VERSION='6.2.0';
+
+# Joomla refuses a password shorter than this.
+readonly JOOMLA_PASSWORD_LENGTH=12;
+
+# The default accounts: one per user group a scenario logs in as. Accounts are configuration,
+# created once on the site; a test suite never creates or deletes one. The role is the Joomla
+# user group, by its title.
+function set_joomla_users() {
+  users=(administrator manager editor member);
+  local groups=('Super Users' 'Manager' 'Editor' 'Registered') i user ;
+  for i in "${!users[@]}" ; do
+    user="${users[$i]}" ;
+    printf -v "user_${user}_name" '%s' "${user}" ;
+    printf -v "user_${user}_mail" '%s' "${user}@example.com" ;
+    printf -v "user_${user}_password" '%s' 'dD.123123ddd' ;
+    printf -v "user_${user}_role" '%s' "${groups[$i]}" ;
+  done
+}
+
+# The docroot of a project, from its own container configuration.
+function joomla_docroot() {
+  local project_path="$1" docroot ;
+  docroot="$(grep -E '^docroot:' "${project_path}/.ddev/config.yaml" 2>/dev/null | head -1 | sed -E 's/^docroot:[[:space:]]*//; s/^"(.*)"$/\1/; s/[[:space:]]*$//')" ;
+  printf '%s' "${docroot}" ;
+}
+
+# Where the Joomla CLI is, from the project root: <docroot>/cli/joomla.php.
+function joomla_cli_path() {
+  local docroot ; docroot="$(joomla_docroot "$1")" ;
+  printf '%s' "${docroot:+${docroot}/}cli/joomla.php" ;
+}
+
+# Is this folder a Joomla project? The Joomla CLI and the administrator in its docroot say so.
+function joomla_is_project() {
+  local project_path="$1" docroot ;
+  [ -f "${project_path}/.ddev/config.yaml" ] || return 1 ;
+  docroot="$(joomla_docroot "${project_path}")" ;
+  [ -f "${project_path}/${docroot:+${docroot}/}cli/joomla.php" ] && [ -d "${project_path}/${docroot:+${docroot}/}administrator" ] ;
+}
+
+# Is the site installed? The installer writes configuration.php, and nothing else does.
+function joomla_is_installed() {
+  local project_path="$1" docroot ;
+  docroot="$(joomla_docroot "${project_path}")" ;
+  [ -f "${project_path}/${docroot:+${docroot}/}configuration.php" ] ;
+}
+
+# Go to the project a tool was asked about, or say why not.
+function joomla_enter_project() {
+  local project_path="${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME}";
+  if [ ! -d "${project_path}" ] ; then
+    echo "No project ${PROJECT_NAME} in ${WORKSPACE_ROOT}/${doc_name}." ;
+    return 1 ;
+  fi
+  if ! joomla_is_project "${project_path}" ; then
+    echo "${doc_name}/${PROJECT_NAME} is not a Joomla project (its docroot has no cli/joomla.php)." ;
+    return 1 ;
+  fi
+  cd "${project_path}" || return 1 ;
+}
+
+# Run the Joomla CLI in the container of the project the shell is in. Every argument is quoted
+# for the container's shell, so a name with a space ("Super Users") arrives as one argument.
+function joomla_cli() {
+  local line arg ;
+  line="php $(joomla_cli_path "$(pwd)")" ;
+  for arg in "$@" ; do
+    line="${line} $(printf '%q' "${arg}")" ;
+  done
+  ddev exec "${line}" ;
+}
+
+# Is there an account of this username on the site?
+function joomla_user_exists() {
+  # A row of the list: the number of the account, then its username.
+  joomla_cli user:list --no-interaction 2>/dev/null | grep -qE "^[[:space:]]*[0-9]+[[:space:]]+$1[[:space:]]" ;
+}
+
+# The number of the latest stable release, read in the container from where the releases are
+# published; the proven release when it cannot be read.
+function joomla_latest_version() {
+  local version ;
+  version="$(ddev exec "curl -fsSI https://github.com/joomla/joomla-cms/releases/latest" 2>/dev/null \
+    | tr -d '\r' | sed -nE 's#^[Ll]ocation:.*/tag/([0-9][0-9A-Za-z.-]*)$#\1#p' | head -1)" ;
+  printf '%s' "${version:-${JOOMLA_PROVEN_VERSION}}" ;
+}
+
+# Build a Joomla site from nothing: the container, the code, and with --install the site itself.
+function joomla_build() {
+  trim_project_name ;
+  local base_url="https://${PROJECT_NAME}.ddev.site" ;
+  local version="${VERSION:-${site_version:-latest}}" ;
+  local php_version="${PHP_VERSION:-${site_php_version:-8.3}}" ;
+  local docroot="${distribution_webroot}" ;
+  local web="${docroot:+${docroot}/}" ;
+
+  if [ "${INSTALL}" == 'yes' ] && [ "${#account_pass}" -lt "${JOOMLA_PASSWORD_LENGTH}" ] ; then
+    echo "Joomla asks for a password of ${JOOMLA_PASSWORD_LENGTH} characters or more, and the workspace account's is shorter." ;
+    echo "Change account: pass in core/config/settings.yml, or build without --install." ;
+    exit 1 ;
+  fi
+
+  cd ${WORKSPACE_ROOT}/${doc_name} || exit 1 ;
+
+  drop_database ;
+  rm -rf "${PROJECT_NAME}" ;
+  mkdir -p "${PROJECT_NAME}/${docroot}" ;
+  cd ${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME} || exit 1 ;
+
+  ddev config --project-type=php --docroot="${docroot}" --project-name=${PROJECT_NAME} \
+    --php-version=${php_version} --webserver-type=nginx-fpm --nodejs-version=$(ddev_nodejs_version) || exit 1 ;
+  ddev_up start -y || exit 1 ;
+
+  [ "${version}" == 'latest' ] && version="$(joomla_latest_version)" ;
+  local package="https://github.com/joomla/joomla-cms/releases/download/${version}/Joomla_${version}-Stable-Full_Package.zip" ;
+  echo "Downloading Joomla ${version}." ;
+  ddev exec "curl -fsSL -o /tmp/joomla.zip '${package}' && unzip -q -o /tmp/joomla.zip -d '/var/www/html/${docroot}' && rm -f /tmp/joomla.zip" \
+    || { echo "The Joomla ${version} package could not be downloaded or unpacked." ; exit 1 ; } ;
+
+  if [ "${INSTALL}" == 'yes' ] ; then
+    # The container's own database values, the same in every project: nothing personal is written.
+    ddev exec "php ${web}installation/joomla.php install --no-interaction \
+      --site-name=$(printf '%q' "${doc_name} ${PROJECT_NAME}") \
+      --admin-user=$(printf '%q' "${account_name}") --admin-username=$(printf '%q' "${account_name}") \
+      --admin-password=$(printf '%q' "${account_pass}") --admin-email=$(printf '%q' "${account_mail}") \
+      --db-type=mysqli --db-host=db --db-user=db --db-pass=db --db-name=db --db-prefix=jos_" \
+      || { echo "The Joomla installer failed." ; exit 1 ; } ;
+
+    # The administrator asks every new site to share anonymous statistics, with a notice on each
+    # page. A local site answers "never" once.
+    ddev mysql -e "UPDATE jos_extensions SET params='{\"mode\":3}' WHERE element='stats' AND folder='system'" ;
+
+    if [ "${SAMPLE_DATA}" == 'yes' ] ; then
+      joomla_sample_data ;
+    fi
+
+    if [ "${ADD_USERS}" == 'yes' ] ; then
+      set_joomla_users ;
+      add_joomla_users ;
+      cd ${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME} || exit 1 ;
+    fi
+
+    echo "${doc_name} ${PROJECT_NAME} has been installed: Joomla ${version}.";
+    echo "Go to ${base_url}/administrator and log in as ${account_name}";
+  else
+    [ "${ADD_USERS}" == 'yes' ] && echo "--add-users needs --install: there is no site to add accounts to yet." ;
+    [ "${SAMPLE_DATA}" == 'yes' ] && echo "--sample-data needs --install: there is no site to add content to yet." ;
+    echo "${doc_name} ${PROJECT_NAME} is ready to install.";
+    echo "Go to ${base_url}";
+  fi
+
+  if [ "${LAUNCH}" == 'yes' ] ; then
+    ddev launch ;
+  fi
+
+  cd ${WORKSPACE_ROOT}/${doc_name};
+}
+
+# The "blog" sample data of Joomla: articles, a menu and the modules that show them. Joomla
+# offers it through the administrator only, so the container logs in as the workspace account,
+# the way a browser would, and asks for each of its four steps in order; then the Smart Search
+# index is built, which the sample data leaves empty. The password travels in the container's
+# environment for that one command and is written nowhere.
+function joomla_sample_data() {
+  echo "Adding the blog sample data." ;
+  ddev exec "JOOMLA_USER=$(printf '%q' "${account_name}") JOOMLA_PASSWORD=$(printf '%q' "${account_pass}") bash -s" <<'SAMPLEEOF' || { echo "  The sample data could not be added; the site itself is installed." ; return 1 ; } ;
+set -e
+site="${DDEV_PRIMARY_URL%/}"
+jar="$(mktemp)"
+trap 'rm -f "${jar}"' EXIT
+admin="${site}/administrator/index.php"
+login_token="$(curl -ksL -c "${jar}" "${admin}" | grep -oP '(?<=name=")[a-f0-9]{32}(?=" value="1")' | head -1)"
+curl -ksL -o /dev/null -b "${jar}" -c "${jar}" "${admin}" \
+  --data-urlencode "username=${JOOMLA_USER}" --data-urlencode "passwd=${JOOMLA_PASSWORD}" \
+  --data-urlencode "option=com_login" --data-urlencode "task=login" \
+  --data-urlencode "return=aW5kZXgucGhw" --data-urlencode "${login_token}=1"
+# A token of the session that is now open: the one of the login form is stale by now.
+token="$(curl -ksL -b "${jar}" -c "${jar}" "${admin}" | grep -oP '(?<=csrf.token":")[a-f0-9]{32}' | head -1)"
+[ -n "${token}" ] || { echo "  The administrator did not open a session." ; exit 1 ; }
+# In order: the second step makes the menu the third one attaches the modules to.
+for step in 1 2 3 4 ; do
+  curl -ksL -b "${jar}" -c "${jar}" -o /dev/null \
+    "${admin}?option=com_ajax&group=sampledata&type=blog&plugin=SampledataApplyStep${step}&format=json&${token}=1"
+done
+SAMPLEEOF
+  joomla_cli finder:index --no-interaction ;
+}
+
+# Create the default accounts with the Joomla CLI. An account that is already there is left as it is.
+# The list is loaded by the caller (set_joomla_users): the core's add_users, the builder, the CLI tool.
+function add_joomla_users() {
+  joomla_enter_project || return 1 ;
+  local user user_name user_mail user_password user_role ;
+  for user in "${users[@]}" ; do
+    user_name="user_${user}_name"; user_mail="user_${user}_mail";
+    user_password="user_${user}_password"; user_role="user_${user}_role";
+
+    echo " ---------------------------------------------------------------- ";
+    echo "      User name: ${!user_name}";
+    echo "      User mail: ${!user_mail}";
+    echo "  User password: ${!user_password}";
+    echo "      User role: ${!user_role}";
+    echo " ================================================================= ";
+
+    if joomla_user_exists "${!user_name}" ; then
+      echo "   ${!user_name} is already there." ;
+    else
+      joomla_cli user:add --no-interaction --username="${!user_name}" --name="${!user_name^}" \
+        --password="${!user_password}" --email="${!user_mail}" --usergroup="${!user_role}" ;
+    fi
+  done
+  cd ${WORKSPACE_ROOT}/${doc_name};
+}
+
+# Delete the default accounts.
+function cancel_joomla_users() {
+  joomla_enter_project || return 1 ;
+  local user user_name ;
+  for user in "${users[@]}" ; do
+    user_name="user_${user}_name";
+    echo " ---------------------------------------------------------------- ";
+    echo "      User name: ${!user_name}";
+    echo " ================================================================= ";
+    if joomla_user_exists "${!user_name}" ; then
+      joomla_cli user:delete --no-interaction --username="${!user_name}" ;
+    else
+      echo "   ${!user_name} is not there." ;
+    fi
+  done
+  cd ${WORKSPACE_ROOT}/${doc_name};
+}
+
+# What cmd-tools-joomla-cli.sh does: the first of --run, --update, --check, --add-users,
+# --cancel-users that was asked for; with none of them, what the site is.
+function joomla_cli_tool() {
+  trim_project_name ;
+  joomla_enter_project || exit 1 ;
+
+  if ! ddev describe -j 2>/dev/null | grep -q '"status":"running"' ; then
+    ddev start -y || exit 1 ;
+  fi
+
+  if [ ! "${RUN}" == '_none_' ] ; then
+    # One string on purpose: --run "extension:list --type=plugin" is a command and its arguments.
+    ddev exec "php $(joomla_cli_path "$(pwd)") ${RUN}" ;
+    exit $? ;
+  fi
+
+  if [ "${UPDATE}" == 'yes' ] ; then
+    joomla_cli core:update --no-interaction && joomla_cli cache:clean --no-interaction ;
+  elif [ "${CHECK}" == 'yes' ] ; then
+    joomla_cli core:check-updates --no-interaction ;
+    joomla_cli update:extensions:check --no-interaction ;
+  elif [ "${ADD_USERS}" == 'yes' ] ; then
+    set_joomla_users ;
+    add_joomla_users ;
+  elif [ "${CANCEL_USERS}" == 'yes' ] ; then
+    set_joomla_users ;
+    cancel_joomla_users ;
+  else
+    echo "${doc_name}/${PROJECT_NAME}: $(joomla_cli --version 2>/dev/null | head -1) at https://${PROJECT_NAME}.ddev.site" ;
+    if joomla_is_installed "$(pwd)" ; then
+      echo "" ; echo "Accounts:" ; joomla_cli user:list --no-interaction ;
+    else
+      echo "The site is not installed yet: open its address, or build it again with --install." ;
+    fi
+  fi
+  cd ${WORKSPACE_ROOT}/${doc_name};
+}
+
+# The step pack in the testing stack of a Joomla project. The core's testing_configure calls
+# this in the project folder once webship-js is scaffolded and before the dependencies are
+# installed; for a project that is not Joomla it changes nothing.
+#
+# It adds the pack to package.json, lists its step definitions in cucumber.js after webship-js's
+# own, gives cucumber.js the users registry of the default accounts (a handle a scenario reads,
+# mapped to an account; never the workspace account), and writes a first feature when the project
+# has none of its own. Every part is skipped when it is already there, so a second run adds what
+# the first missed and never resets a suite.
+function testing_configure_joomla() {
+  local project_path="$1";
+  joomla_is_project "${project_path}" || return 0 ;
+  if [ ! -f "${project_path}/cucumber.js" ] || [ ! -f "${project_path}/package.json" ] ; then
+    echo "  Joomla: cucumber.js is not here yet — run the testing setup again once webship-js is scaffolded." ;
+    return 1 ;
+  fi
+
+  echo "Adding the Joomla step pack (${JOOMLA_STEPS_PACKAGE} ${JOOMLA_STEPS_VERSION}).";
+  set_joomla_users ;
+  local registry="" user user_name user_password handle ;
+  for user in "${users[@]}" ; do
+    user_name="user_${user}_name"; user_password="user_${user}_password";
+    # The pack's features call the Super User "admin".
+    handle="${user}" ; [ "${user}" == 'administrator' ] && handle="admin" ;
+    registry="${registry}${handle}|${!user_name}|${!user_password}"$'\n' ;
+  done
+
+  python3 - "${project_path}" "${JOOMLA_STEPS_PACKAGE}" "${JOOMLA_STEPS_VERSION}" 'JOOMLA' "${registry}" <<'PYEOF' || return 1
+import json, re, sys
+
+project, pack, version, prefix, registry = sys.argv[1:6]
+
+# package.json: the pack as a dev dependency, at the release line this plugin was proven on.
+pkg_file = project + '/package.json'
+pkg = json.load(open(pkg_file))
+if pack not in pkg.get('dependencies', {}) and pack not in pkg.get('devDependencies', {}):
+    pkg.setdefault('devDependencies', {})[pack] = version
+    open(pkg_file, 'w').write(json.dumps(pkg, indent=2) + '\n')
+    print('  package.json: %s %s' % (pack, version))
+
+# cucumber.js: the pack's step definitions after webship-js's own, and the users registry.
+cucumber_file = project + '/cucumber.js'
+src = open(cucumber_file).read()
+before = src
+
+if ('node_modules/%s/' % pack) not in src:
+    line = "'node_modules/%s/tests/step-definitions/**/*.js'," % pack
+    core = re.search(r"^([ \t]*)'node_modules/webship-js/tests/step-definitions/[^']*',.*$", src, re.M)
+    opening = re.search(r"^([ \t]*)require:[ \t]*\[[ \t]*$", src, re.M)
+    if core:
+        src = src[:core.end()] + '\n' + core.group(1) + line + src[core.end():]
+    elif opening:
+        src = src[:opening.end()] + '\n' + opening.group(1) + '  ' + line + src[opening.end():]
+    else:
+        sys.exit("  cucumber.js has no require list this can add to. Add this line to it:\n    " + line)
+    print('  cucumber.js: the step definitions of %s' % pack)
+
+if not re.search(r"^[ \t]*users:[ \t]*\{", src, re.M):
+    world = re.search(r"^([ \t]*)worldParameters:[ \t]*\{[ \t]*$", src, re.M)
+    if not world:
+        sys.exit("  cucumber.js has no worldParameters block to add the users registry to.")
+    pad = world.group(1) + '  '
+    rows = [r.split('|') for r in registry.splitlines() if r.strip()]
+    block = [
+        pad + "// The users registry: a handle a scenario reads, mapped to an account of this site (the default",
+        pad + "// accounts: cmd-tools-add-users.sh). Override one with %s_<HANDLE>_USER and %s_<HANDLE>_PASSWORD." % (prefix, prefix),
+        pad + "users: {",
+    ]
+    for handle, name, password in rows:
+        env = '%s_%s' % (prefix, handle.upper())
+        block.append(pad + "  %s: { username: process.env.%s_USER || '%s', password: process.env.%s_PASSWORD || '%s' }," % (handle, env, name, env, password))
+    block.append(pad + "},")
+    src = src[:world.end()] + '\n' + '\n'.join(block) + src[world.end():]
+    print('  cucumber.js: the users registry (%s)' % ', '.join(r[0] for r in rows))
+
+if src != before:
+    open(cucumber_file, 'w').write(src)
+PYEOF
+
+  # A first feature, when the project has none for the site yet: the front page, the login page,
+  # each default account in its group.
+  local feature="${WORKSPACE_SCRIPTS}/plugins/joomla/site.feature" ;
+  if [ -f "${feature}" ] && [ ! -f "${project_path}/tests/features/site.feature" ] ; then
+    mkdir -p "${project_path}/tests/features" && cp "${feature}" "${project_path}/tests/features/site.feature" \
+      && echo "  tests/features/site.feature: a first feature for the site" ;
+  fi
+
+  # The scenarios log in as the default accounts: make sure an installed site has them.
+  if joomla_is_installed "${project_path}" ; then
+    ( add_joomla_users > /dev/null ) && echo "  the default accounts are on the site (${users[*]})" ;
+  fi
+}

package/testing/site.feature

@@ -0,0 +1,64 @@
+Feature: The site answers and its accounts work
+  As the owner of the site
+  I want the front page, the login page and each default account to work
+  So that a build that came out broken is caught before anything else is tested
+
+  # Placed by the workspace's testing setup as a starting point: it is yours to change.
+  # The accounts are the default ones (cmd-tools-add-users.sh); a scenario logs in by a handle of
+  # the users registry in cucumber.js, so no password is written here.
+
+  @critical
+  Scenario: The front page is served
+    Given I am an anonymous user
+    And I am on the homepage
+    Then the response status code should be 200
+    And the page should have a title
+
+  @critical
+  Scenario: The login page is served with its form
+    Given I am on the login page
+    Then the response status code should be 200
+    And I should see the login form
+
+  Scenario Outline: Each default account is on the site, in the group of its role
+    Given I am a logged in user with the "admin" user
+    Then the user "<account>" should exist
+    And the user "<account>" should be enabled
+    And the user "<account>" should be in the "<group>" group
+
+    Examples:
+      | account       | group       |
+      | administrator | Super Users |
+      | manager       | Manager     |
+      | editor        | Editor      |
+      | member        | Registered  |
+
+  Scenario Outline: An account of the administrator logs in to it
+    Given I am a logged in user with the "<handle>" user
+    Then I should see the administrator dashboard
+    And I should see the administrator menu
+
+    Examples:
+      | handle  |
+      | admin   |
+      | manager |
+
+  Scenario Outline: An account of the site logs in to it
+    Given I am logged in to the site with the "<handle>" user
+    Then I should be logged in to the site as "<handle>"
+
+    Examples:
+      | handle |
+      | editor |
+      | member |
+
+  Scenario: An account is refused a page its group may not open
+    Given I am a logged in user with the "manager" user
+    When I go to the administrator "Users" page
+    Then the response status code should be 403
+
+  Scenario: An anonymous visitor has no session
+    Given I am not logged in
+    When I am on the profile page
+    Then I should see the login form
+    And I should not be logged in to the site