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

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# @webship.co/workspace-typo3
 
-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.
+TYPO3 for the [Webship Workspace](https://github.com/webship/workspace) dashboard: a builder
+that makes a real TYPO3 site in a container, a typo3 console tool for the sites it built, the default
+accounts, the [TYPO3 step pack](https://github.com/webship/typo3-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 TYPO3 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-typo3   # npm install into the dashboard
+bash core/scripts/plugins.sh --activate typo3                            # plugins.typo3 in settings.yml
+bash core/scripts/plugins.sh --install typo3                             # commands, functions, args, agents
+bash core/scripts/plugins.sh --configure typo3                           # 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-typo3-project.sh` | The builder, in the Build list as **TYPO3 (13.4 LTS)**, installed into every sites folder |
+| `commands/cmd-tools-typo3-cli.sh` | The typo3 console for one project: what the site is, a command, updates, caches, the default accounts |
+| `scripts/functions/fun-typo3.sh` | The bash functions behind both, sourced by bootstrap once installed; the names the core's tools look for (`set_typo3_users`, `add_typo3_users`, `cancel_typo3_users`, `testing_configure_typo3`) |
+| `scripts/args/arg-typo3.sh`, `arg-typo3-cli.sh` | Their argparse; the Build form draws the builder's flags from the first |
+| `testing/site.feature` | The first feature a TYPO3 project gets when testing is set up |
+| `agents/typo3-site-builder.md` | The agent that builds and maintains TYPO3 sites with these commands |
+| `agents/typo3-tester.md` | The agent that writes and runs scenarios with the TYPO3 step pack |
+| `src/index.ts` | `register(api)`: what the assistant is told about TYPO3 here |
+| `features/typo3.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-typo3-project.sh mysite --install --add-users
+```
+
+| Flag | What it does |
+| --- | --- |
+| `--version <x>` | The release to create the project from, as a Composer constraint of `typo3/cms-base-distribution`: `^13.4` (the default, TYPO3 13.4 LTS), or a number such as `13.4.20` |
+| `--install` | Set the site up, with the workspace account as its administrator, and add the official Introduction package: a site with pages, content and a search |
+| `--add-users` | With `--install`: add the default accounts, an administrator and an editor |
+| `--bare` | With `--install`: leave the Introduction package out (a backend, and no site or page yet) |
+| `--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 backend at `/typo3`. The build runs
+`ddev config --project-type=typo3` with the docroot `public` and the Node.js of the workspace (24),
+creates the project with Composer in the container (`typo3/cms-base-distribution`), and sets it up
+with TYPO3's own `setup` command. The setup 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.
+
+The Introduction package (`typo3/cms-introduction`, on the Bootstrap Package theme) is the site the
+step pack is written for; with it the build also runs the upgrade wizard its search content needs
+and points the search results at the templates of Indexed Search.
+
+TYPO3 asks for an administrator password of 8 characters or more, with an upper and a lower case
+letter, a digit and a sign: the setup stops when the workspace account's does not pass.
+
+### Work on a site
+
+```bash
+bash cmd-tools-typo3-cli.sh mysite                                    # version, address, sites, backend accounts
+bash cmd-tools-typo3-cli.sh mysite --run "extension:list --active"
+bash cmd-tools-typo3-cli.sh mysite --run "list"                       # every command of the console
+bash cmd-tools-typo3-cli.sh mysite --flush                            # flush every cache
+bash cmd-tools-typo3-cli.sh mysite --update                           # Composer packages, extension setup, caches
+bash cmd-tools-typo3-cli.sh mysite --add-users                        # the default accounts
+bash cmd-tools-typo3-cli.sh mysite --cancel-users                     # delete them
+```
+
+### The default accounts
+
+| Account | Role | Handle in the tests |
+| --- | --- | --- |
+| `administrator` | administrator (not a system maintainer: the Extensions module and the Admin Tools stay with the workspace account) | `admin` |
+| `editor` | the backend group "Advanced editors" (from the Introduction package) | `editor` |
+
+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. The row's Users menu (**Add the test users**),
+`bash cmd-tools-add-users.sh mysite typo3` and `bash cmd-tools-cancel-users.sh mysite typo3` add
+and remove the same list. On a site without the Introduction package the editor is created without
+a group.
+
+### 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 TYPO3 project it also adds
+`@webship-js/typo3-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
+`TYPO3_<HANDLE>_USER` and `TYPO3_<HANDLE>_PASS`), 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 |
+| --- | --- |
+| `typo3-site-builder` | Build, update, maintain or remove a TYPO3 site with the commands above, in containers only |
+| `typo3-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 typo3-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/typo3-site-builder.md

@@ -0,0 +1,106 @@
+---
+name: typo3-site-builder
+description: Use this agent to build, maintain, update or remove a TYPO3 site in the Webship Workspace — a new site from `cmd-typo3-project.sh`, typo3 console work through `cmd-tools-typo3-cli.sh` (extensions, caches, upgrade wizards, 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 TYPO3 site", "add this extension to <site>", "update TYPO3 on <site>", "add the test accounts", or "remove the TYPO3 sandbox". For writing and running test scenarios, hand over to `typo3-tester`.
+model: fable
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+# typo3-site-builder
+
+You build and look after TYPO3 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 TYPO3 plugin (`@webship.co/workspace-typo3`); if a folder has no
+`cmd-typo3-project.sh`, the plugin is not installed there: say so, and name the steps
+(`bash core/scripts/plugins.sh --require @webship.co/workspace-typo3`, `--activate typo3`,
+`--install typo3`) 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-typo3-project.sh mysite --install --add-users
+```
+
+| Flag | What it does |
+| --- | --- |
+| `--version <x>` | The release to create the project from, as a Composer constraint of `typo3/cms-base-distribution`: `^13.4` (the default, TYPO3 13.4 LTS), or a number such as `13.4.20`. |
+| `--install` | Sets TYPO3 up, with the workspace account (`account:` in `core/config/settings.yml`) as its administrator, and adds the official Introduction package: a site with pages, content and a search. Without it the code is there and the installer waits at `/typo3/install.php`. |
+| `--add-users` | With `--install`: the default accounts, `administrator` (an administrator) and `editor` (in the backend group "Advanced editors"). |
+| `--bare` | With `--install`: leaves the Introduction package out. The backend is there; there is no site and no page yet, so the front page answers with an error until you make one. |
+| `--php-version <x>` | The PHP of the project container (`8.3` by default). |
+| `--launch` | Opens the site when it is ready. |
+
+The site answers at `https://<name>.ddev.site`, the backend at `/typo3`. It is a Composer project:
+the docroot is `public/`, the configuration is in `config/`. 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.
+
+TYPO3 asks for an administrator password of 8 characters or more, with an upper and a lower case
+letter, a digit and a sign. When the workspace account's does not pass, the setup says so and the
+build stops: do not invent another password, ask for the setting to be changed.
+
+## Work on a site
+
+```bash
+bash cmd-tools-typo3-cli.sh mysite                                  # what it is: version, address, sites, backend accounts
+bash cmd-tools-typo3-cli.sh mysite --run "extension:list --active"
+bash cmd-tools-typo3-cli.sh mysite --run "upgrade:list"
+bash cmd-tools-typo3-cli.sh mysite --flush                          # every cache
+bash cmd-tools-typo3-cli.sh mysite --update                         # the Composer packages, the extension setup, the caches
+bash cmd-tools-typo3-cli.sh mysite --add-users                      # the default accounts
+bash cmd-tools-typo3-cli.sh mysite --cancel-users                   # and away again
+```
+
+`--run "list"` prints every command of the site's console. Inside the project folder,
+`ddev exec vendor/bin/typo3 <command>` is the same console; an extension is a Composer package
+(`ddev composer require <vendor>/<package>`, then `--run "extension:setup"`), and
+`ddev export-db --file=…`, `ddev import-db --file=…` are the tools for the database.
+
+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> typo3`, `bash cmd-tools-testing.sh <name>` (the testing
+stack, with the TYPO3 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 setup is given `db` / `db` / `db` on the host
+  `db`, the same in every project, and the container tool writes its own `config/system/additional.php`.
+  Do not put another host, account or password into the configuration.
+- **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.
+- **Open-source only.** Extensions come from Packagist or the TYPO3 Extension Repository, as
+  Composer packages. 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 |
+| --- | --- |
+| `composer create-project … failed` | No network in the container, or a constraint no release matches: the default `^13.4` proves which. |
+| `typo3 setup failed` | Most often the workspace account's password does not pass TYPO3's rules (8 characters, both cases, a digit, a sign): it is changed in `core/config/settings.yml`, by its owner. |
+| The installer instead of the backend | The build ran without `--install`: finish it at `/typo3/install.php`, or build again with `--install`. |
+| An error page on the front page, the backend works | The site was built with `--bare`: it has no site configuration and no page yet. |
+| A page shows old content | The caches: `bash cmd-tools-typo3-cli.sh <name> --flush`. |
+| `The site has no backend group "Advanced editors"` | The accounts were added to a site without the Introduction package: `editor` exists, with no rights until you give it a group. |
+| `is not a TYPO3 project` from the CLI tool | The project's `.ddev/config.yaml` does not say `type: typo3`: it was not built by this builder. |

package/agents/typo3-tester.md

@@ -0,0 +1,125 @@
+---
+name: typo3-tester
+description: Use this agent to test a TYPO3 site of the Webship Workspace with webship-js and the TYPO3 step pack (`@webship-js/typo3-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 TYPO3 site", "write scenarios for the editor", "why does this scenario fail", or "run the suite on <site>". For building or changing the site itself, hand over to `typo3-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
+---
+
+# typo3-tester
+
+You test TYPO3 sites in a Webship Workspace (`~/workspace`) with
+[webship-js](https://github.com/webship/webship-js) (Playwright and Cucumber) and its TYPO3 step
+pack, [`@webship-js/typo3-steps`](https://github.com/webship/typo3-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 TYPO3 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/typo3-steps/tests/step-definitions/
+   grep -n "^\(Given\|When\|Then\)" node_modules/@webship-js/typo3-steps/tests/step-definitions/typo3-backend.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 to the backend by a **handle** of the users registry (`worldParameters.users` in
+`cucumber.js`):
+
+```gherkin
+Given I am a logged in user with the "editor" user
+Then I should be logged in as "editor"
+```
+
+| Handle | Account | Role |
+| --- | --- | --- |
+| `admin` | `administrator` | administrator (not a system maintainer: no Extensions module, no Admin Tools) |
+| `editor` | `editor` | the backend group "Advanced editors" of the Introduction package |
+
+These are the default accounts (`bash cmd-tools-typo3-cli.sh mysite --add-users`). Override one
+for another environment with `TYPO3_<HANDLE>_USER` and `TYPO3_<HANDLE>_PASS`.
+
+## Rules
+
+- **Never create an account in a suite.** No `backend:user:create` in a hook, no 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 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 a logged in
+  user with the "editor" user`, `I open the "Page" module`, `I select the "Home" page in the page
+  tree`. 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 "List"
+  module`, not `/typo3/module/web/list`.
+- **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.
+
+The pack's own features are written for the Introduction package (its pages, menus and copy). A
+site built with `--bare`, or one with other content, needs its own page names in the scenarios.
+
+## A scenario, the way the pack reads
+
+```gherkin
+Feature: An editor works in the page module
+
+  Scenario: The editor opens the page module
+    Given I am a logged in user with the "editor" user
+    When I open the "Page" module
+    Then the "Page" module should be active
+    And I should not see the "Extensions" module
+```
+
+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-tools-typo3-cli.sh

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

package/commands/cmd-typo3-project.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+# workspace-name: TYPO3 (13.4 LTS)
+
+# Installed by the TYPO3 plugin (plugins.sh --install typo3); __WORKSPACE__ is the workspace it was installed into.
+#
+# Build a TYPO3 site in a container: TYPO3 13.4 LTS, or the release --version names, at
+# https://<name>.ddev.site. With --install the site is set up with the workspace account as its
+# administrator and gets the official Introduction package (a site with pages and content); with
+# --add-users it also gets the default accounts, an administrator and an editor.
+
+# 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="^13.4";
+
+# Distribution.
+distribution_name="typo3";
+distribution_title="TYPO3";
+distribution_webroot="public";
+project_template="typo3/cms-base-distribution";
+
+ARGPARSE_DESCRIPTION="Build a ${distribution_title} project in __WORKSPACE__"
+# The args file comes with the plugin: core/scripts/plugins/typo3/ is where plugins.sh --install puts it.
+source ${WORKSPACE_SCRIPTS}/plugins/typo3/args/arg-typo3.sh || exit 1 ;
+
+shift $#;
+
+typo3_build ;

package/dist/src/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * TYPO3 for Webship Workspace: a platform plugin.
+ *
+ * What the package carries is placed by the installer from the manifest: the builder and the
+ * typo3 console tool in the sites folders, their functions and argparse under core/scripts/plugins/typo3/,
+ * 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 is also the DDEV project type its functions are named after. */
+export declare const PLATFORM = "typo3";
+/** 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 TYPO3 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";
+/**
+ * TYPO3 for Webship Workspace: a platform plugin.
+ *
+ * What the package carries is placed by the installer from the manifest: the builder and the
+ * typo3 console tool in the sites folders, their functions and argparse under core/scripts/plugins/typo3/,
+ * 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 is also the DDEV project type its functions are named after. */
+exports.PLATFORM = 'typo3';
+/** The commands the installer places in every sites folder. */
+exports.COMMANDS = ['cmd-typo3-project.sh', 'cmd-tools-typo3-cli.sh'];
+/** The agents the installer places in the AI Agents folder. */
+exports.AGENTS = ['typo3-site-builder', 'typo3-tester'];
+/** What the assistant is told about TYPO3 in this workspace. */
+function assistantContext() {
+    return [
+        'TYPO3 (a plugin, @webship.co/workspace-typo3): a TYPO3 site is built with',
+        '`bash cmd-typo3-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 backend at /typo3); --install sets TYPO3 13.4 LTS up',
+        'with the Introduction package (a site with pages and content), --bare leaves that package out.',
+        '`bash cmd-tools-typo3-cli.sh <name>` says what the site is; `--run "<command>"` runs the typo3 console (vendor/bin/typo3) in it,',
+        '`--update` updates the Composer packages, `--flush` flushes the caches, `--add-users` adds the default accounts (an administrator and an editor).',
+        '`bash cmd-tools-testing.sh <name>` sets up webship-js with the TYPO3 step pack; `--run` runs the suite.',
+        `For TYPO3 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,4FAA4F;AAC/E,QAAA,QAAQ,GAAG,OAAO,CAAC;AAEhC,+DAA+D;AAClD,QAAA,QAAQ,GAAG,CAAC,sBAAsB,EAAE,wBAAwB,CAAC,CAAC;AAE3E,+DAA+D;AAClD,QAAA,MAAM,GAAG,CAAC,oBAAoB,EAAE,cAAc,CAAC,CAAC;AAE7D,gEAAgE;AAChE,SAAgB,gBAAgB;IAC9B,OAAO;QACL,2EAA2E;QAC3E,6GAA6G;QAC7G,gIAAgI;QAChI,gGAAgG;QAChG,kIAAkI;QAClI,mJAAmJ;QACnJ,yGAAyG;QACzG,2CAA2C,cAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG;QACzF,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/typo3.feature

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

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@webship.co/workspace-typo3",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.7",
+  "description": "TYPO3 for Webship Workspace: the builder (`cmd-typo3-project.sh`) and the typo3 console tool in every sites folder, the default accounts, the TYPO3 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-typo3.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": "typo3",
+    "label": "TYPO3",
+    "commands": {
+      "types": [
+        "sites"
+      ],
+      "workspaces": [
+        "dev",
+        "test",
+        "sandboxes",
+        "demos"
+      ],
+      "files": [
+        "commands/cmd-typo3-project.sh",
+        "commands/cmd-tools-typo3-cli.sh"
+      ]
+    },
+    "scripts": {
+      "functions": [
+        "scripts/functions/fun-typo3.sh"
+      ],
+      "args": [
+        "scripts/args/arg-typo3.sh",
+        "scripts/args/arg-typo3-cli.sh"
+      ],
+      "machine": [
+        "testing/site.feature"
+      ]
+    },
+    "ai": {
+      "agents": [
+        "agents/typo3-site-builder.md",
+        "agents/typo3-tester.md"
+      ]
+    },
+    "features": [
+      "features/typo3.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-typo3-cli.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+parser.add_argument('PROJECT_NAME',
+                    help='The TYPO3 project in this workspace.')
+parser.add_argument('-r', '--run',
+                    default="_none_",
+                    help='A typo3 console command to run in the project, without the leading typo3. Example: --run "extension:list --active"')
+parser.add_argument('-u', '--update',
+                    action='store_true',
+                    default=False,
+                    help='Update the Composer packages of the project (TYPO3 and its extensions) within their constraints, set the extensions up and flush the caches.')
+parser.add_argument('-f', '--flush',
+                    action='store_true',
+                    default=False,
+                    help='Flush every cache, and nothing else.')
+parser.add_argument('-a', '--add-users',
+                    action='store_true',
+                    default=False,
+                    help='Add the default accounts, an administrator and an editor. 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-typo3.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 TYPO3 release to create the project from, as a Composer constraint of typo3/cms-base-distribution. Example: --version 13.4.20 [default %(default)s]')
+parser.add_argument('-i', '--install',
+                    action='store_true',
+                    default=False,
+                    help='Set TYPO3 up, with the workspace account as the administrator, and add the Introduction package: a site with pages and content.')
+parser.add_argument('-a', '--add-users',
+                    action='store_true',
+                    default=False,
+                    help='With --install, add the default accounts: an administrator and an editor, the ones the test scenarios log in as.')
+parser.add_argument('-b', '--bare',
+                    action='store_true',
+                    default=False,
+                    help='With --install, leave the Introduction package out: an installation with a backend, and no site or page yet.')
+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.4', '8.3', '8.2'],
+                    help='PHP version for the project container. Example: --php-version 8.4 [default %(default)s]')
+ARGEOF

package/scripts/functions/fun-typo3.sh

@@ -0,0 +1,358 @@
+#!/usr/bin/env bash
+
+# TYPO3 for the Webship Workspace: build a site, run the typo3 console on it, add its default
+# accounts, and wire its step pack into the testing setup.
+#
+# Placed by `plugins.sh --install typo3` in core/scripts/plugins/typo3/functions/, where
+# bootstrap sources it after the core's own functions. Everything runs in the project's container
+# (DDEV by default: `ddev composer …`, `ddev exec vendor/bin/typo3 …`), never on the host. The
+# setup command 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, under the DDEV project type `typo3`:
+#   set_typo3_users        the default accounts            (cmd-tools-add-users.sh <project> typo3)
+#   add_typo3_users        create them with the console    (the same tool, and --add-users of the builder)
+#   cancel_typo3_users     delete them                     (cmd-tools-cancel-users.sh <project> typo3)
+#   testing_configure_typo3  the step pack in the testing stack (cmd-tools-testing.sh <project>)
+
+# The step pack a TYPO3 project is tested with, and the release line it is required at.
+readonly TYPO3_STEPS_PACKAGE='@webship-js/typo3-steps';
+readonly TYPO3_STEPS_VERSION='^2.1.0';
+
+# The backend group the editor account joins: the one the Introduction package brings.
+readonly TYPO3_EDITOR_GROUP='Advanced editors';
+
+# The default accounts: an administrator and an editor, the ones a scenario logs in as. Accounts
+# are configuration, created once on the site; a test suite never creates or deletes one. The
+# role is `admin` for an administrator, or the title of a backend group.
+function set_typo3_users() {
+  users=(administrator editor);
+  local roles=('admin' "${TYPO3_EDITOR_GROUP}") 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' "${roles[$i]}" ;
+  done
+}
+
+# Is this folder a TYPO3 project? Its DDEV project type says so.
+function typo3_is_project() {
+  local project_path="$1";
+  grep -qE '^type:[[:space:]]*"?typo3"?[[:space:]]*$' "${project_path}/.ddev/config.yaml" 2>/dev/null ;
+}
+
+# Is the site set up? The setup command writes config/system/settings.php, and nothing else does.
+function typo3_is_installed() {
+  [ -f "$1/config/system/settings.php" ] ;
+}
+
+# Go to the project a tool was asked about, or say why not.
+function typo3_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 ! typo3_is_project "${project_path}" ; then
+    echo "${doc_name}/${PROJECT_NAME} is not a TYPO3 project (its .ddev/config.yaml does not say type: typo3)." ;
+    return 1 ;
+  fi
+  cd "${project_path}" || return 1 ;
+}
+
+# Run the typo3 console in the container of the project the shell is in. Every argument is
+# quoted for the container's shell, so a password with a sign in it arrives as one argument.
+function typo3_cli() {
+  local line="vendor/bin/typo3" arg ;
+  for arg in "$@" ; do
+    line="${line} $(printf '%q' "${arg}")" ;
+  done
+  ddev exec "${line}" ;
+}
+
+# One value from the project's database, read in its container.
+function typo3_query() {
+  ddev mysql -N -B -e "$1" 2>/dev/null | tr -d '\r' | head -1 ;
+}
+
+# Is there a backend account of this username on the site?
+function typo3_user_exists() {
+  [ "$(typo3_query "SELECT COUNT(*) FROM be_users WHERE username = '$1' AND deleted = 0")" == '1' ] ;
+}
+
+# Build a TYPO3 site from nothing: the container, the code, and with --install the site itself.
+function typo3_build() {
+  trim_project_name ;
+  local base_url="https://${PROJECT_NAME}.ddev.site" ;
+  local version="${VERSION:-${site_version:-^13.4}}" ;
+  local php_version="${PHP_VERSION:-${site_php_version:-8.3}}" ;
+
+  cd ${WORKSPACE_ROOT}/${doc_name} || exit 1 ;
+
+  drop_database ;
+  rm -rf "${PROJECT_NAME}" ;
+  mkdir -p "${PROJECT_NAME}" ;
+  cd ${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME} || exit 1 ;
+
+  ddev config --project-type=typo3 --docroot="${distribution_webroot}" --project-name=${PROJECT_NAME} \
+    --php-version=${php_version} --nodejs-version=$(ddev_nodejs_version) --auto || exit 1 ;
+  ddev_up start -y || exit 1 ;
+
+  ddev composer create-project "${project_template}:${version}" . --no-interaction \
+    || { echo "composer create-project ${project_template}:${version} failed." ; exit 1 ; } ;
+
+  if [ "${INSTALL}" == 'yes' ] ; then
+    # The container's own database values, the same in every project: nothing personal is written.
+    typo3_cli setup --no-interaction --force --server-type=other \
+      --driver=mysqli --host=db --port=3306 --dbname=db --username=db --password=db \
+      --admin-username="${account_name}" --admin-user-password="${account_pass}" --admin-email="${account_mail}" \
+      --project-name="${doc_name} ${PROJECT_NAME}" \
+      || { echo "typo3 setup failed. TYPO3 asks for an administrator password of 8 characters or more, with an upper and a lower case letter, a digit and a sign: see account: pass in core/config/settings.yml." ; exit 1 ; } ;
+
+    if [ "${BARE}" == 'yes' ] ; then
+      echo "No Introduction package: the installation has no site and no page yet." ;
+    else
+      typo3_introduction || exit 1 ;
+    fi
+
+    if [ "${ADD_USERS}" == 'yes' ] ; then
+      set_typo3_users ;
+      add_typo3_users ;
+      cd ${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME} || exit 1 ;
+    fi
+
+    typo3_cli cache:flush ;
+
+    echo "${doc_name} ${PROJECT_NAME} has been installed: $(typo3_cli --version 2>/dev/null | head -1).";
+    echo "Go to ${base_url}/typo3 and log in as ${account_name}";
+  else
+    [ "${ADD_USERS}" == 'yes' ] && echo "--add-users needs --install: there is no site to add accounts to yet." ;
+    echo "${doc_name} ${PROJECT_NAME} is ready to install.";
+    echo "Go to ${base_url}/typo3/install.php";
+  fi
+
+  if [ "${LAUNCH}" == 'yes' ] ; then
+    ddev launch ;
+  fi
+
+  cd ${WORKSPACE_ROOT}/${doc_name};
+}
+
+# The official Introduction package (typo3/cms-introduction, on the Bootstrap Package theme): a
+# site with pages, content, a search and the backend groups the editor account joins. It is the
+# site the step pack is written for.
+function typo3_introduction() {
+  echo "Adding the Introduction package." ;
+  ddev composer require typo3/cms-introduction --no-interaction \
+    || { echo "composer require typo3/cms-introduction failed." ; return 1 ; } ;
+
+  # Activates the package and imports its content and its site configuration.
+  typo3_cli extension:setup || return 1 ;
+
+  # The content stores the search as a plugin of the old kind, and the setup marks every upgrade
+  # wizard as done before the content is imported: run the one that turns it into a content element.
+  typo3_cli upgrade:mark:undone indexedSearchCTypeMigration ;
+  typo3_cli upgrade:run indexedSearchCTypeMigration --no-interaction ;
+
+  # The search result templates of the theme call a ViewHelper TYPO3 13.4 no longer ships, which
+  # breaks the result list: use the templates of Indexed Search itself.
+  ddev mysql -e "UPDATE sys_template SET config = CONCAT(IFNULL(config, ''), '
+plugin.tx_indexedsearch.view.templateRootPaths.20 >
+plugin.tx_indexedsearch.view.templateRootPaths.21 >
+plugin.tx_indexedsearch.view.partialRootPaths.20 >
+plugin.tx_indexedsearch.view.partialRootPaths.21 >
+plugin.tx_indexedsearch.view.layoutRootPaths.20 >
+plugin.tx_indexedsearch.view.layoutRootPaths.21 >
+') WHERE root = 1 AND (config IS NULL OR config NOT LIKE '%plugin.tx_indexedsearch.view.templateRootPaths.20 >%')" ;
+}
+
+# Create the default accounts with the typo3 console. An account that is already there is left as it is.
+# The list is loaded by the caller (set_typo3_users): the core's add_users, the builder, the CLI tool.
+function add_typo3_users() {
+  typo3_enter_project || return 1 ;
+  local user user_name user_mail user_password user_role group ;
+  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 typo3_user_exists "${!user_name}" ; then
+      echo "   ${!user_name} is already there." ;
+    elif [ "${!user_role}" == 'admin' ] ; then
+      typo3_cli backend:user:create --no-interaction --username="${!user_name}" \
+        --password="${!user_password}" --email="${!user_mail}" --admin && echo "   ${!user_name} is created." ;
+    else
+      # A backend group is named by its number: look it up by its title.
+      group="$(typo3_query "SELECT uid FROM be_groups WHERE title = '${!user_role}' AND deleted = 0 LIMIT 1")" ;
+      if [ -z "${group}" ] ; then
+        echo "   The site has no backend group \"${!user_role}\" (the Introduction package brings it): ${!user_name} is created without a group." ;
+        typo3_cli backend:user:create --no-interaction --username="${!user_name}" \
+          --password="${!user_password}" --email="${!user_mail}" && echo "   ${!user_name} is created." ;
+      else
+        typo3_cli backend:user:create --no-interaction --username="${!user_name}" \
+          --password="${!user_password}" --email="${!user_mail}" --groups="${group}" && echo "   ${!user_name} is created." ;
+      fi
+    fi
+  done
+  cd ${WORKSPACE_ROOT}/${doc_name};
+}
+
+# Delete the default accounts. The console has no command for it, so the records are removed
+# from the project's database, in its container.
+function cancel_typo3_users() {
+  typo3_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 typo3_user_exists "${!user_name}" ; then
+      ddev mysql -e "DELETE FROM be_users WHERE username = '${!user_name}'" && echo "   ${!user_name} is deleted." ;
+    else
+      echo "   ${!user_name} is not there." ;
+    fi
+  done
+  cd ${WORKSPACE_ROOT}/${doc_name};
+}
+
+# What cmd-tools-typo3-cli.sh does: the first of --run, --update, --flush, --add-users,
+# --cancel-users that was asked for; with none of them, what the site is.
+function typo3_cli_tool() {
+  trim_project_name ;
+  typo3_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 --active" is a command and its arguments.
+    ddev exec "vendor/bin/typo3 ${RUN}" ;
+    exit $? ;
+  fi
+
+  if [ "${UPDATE}" == 'yes' ] ; then
+    ddev composer update --with-all-dependencies --no-interaction \
+      && typo3_cli extension:setup && typo3_cli cache:flush ;
+  elif [ "${FLUSH}" == 'yes' ] ; then
+    typo3_cli cache:flush && echo "The caches are flushed." ;
+  elif [ "${ADD_USERS}" == 'yes' ] ; then
+    set_typo3_users ;
+    add_typo3_users ;
+  elif [ "${CANCEL_USERS}" == 'yes' ] ; then
+    set_typo3_users ;
+    cancel_typo3_users ;
+  else
+    echo "${doc_name}/${PROJECT_NAME}: $(typo3_cli --version 2>/dev/null | head -1) at https://${PROJECT_NAME}.ddev.site" ;
+    if typo3_is_installed "$(pwd)" ; then
+      echo "" ; echo "Sites:" ; typo3_cli site:list ;
+      echo "" ; echo "Backend accounts:" ;
+      ddev mysql -t -e "SELECT username, email, IF(admin = 1, 'admin', usergroup) AS role FROM be_users WHERE deleted = 0 AND username <> '_cli_' ORDER BY uid" ;
+    else
+      echo "The site is not set up yet: open its address at /typo3/install.php, or build it again with --install." ;
+    fi
+  fi
+  cd ${WORKSPACE_ROOT}/${doc_name};
+}
+
+# The step pack in the testing stack of a TYPO3 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 TYPO3 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_typo3() {
+  local project_path="$1";
+  typo3_is_project "${project_path}" || return 0 ;
+  if [ ! -f "${project_path}/cucumber.js" ] || [ ! -f "${project_path}/package.json" ] ; then
+    echo "  TYPO3: cucumber.js is not here yet — run the testing setup again once webship-js is scaffolded." ;
+    return 1 ;
+  fi
+
+  echo "Adding the TYPO3 step pack (${TYPO3_STEPS_PACKAGE} ${TYPO3_STEPS_VERSION}).";
+  set_typo3_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 administrator "admin".
+    handle="${user}" ; [ "${user}" == 'administrator' ] && handle="admin" ;
+    registry="${registry}${handle}|${!user_name}|${!user_password}"$'\n' ;
+  done
+
+  # The pack reads TYPO3_<HANDLE>_USER and TYPO3_<HANDLE>_PASS: the registry keeps its names.
+  python3 - "${project_path}" "${TYPO3_STEPS_PACKAGE}" "${TYPO3_STEPS_VERSION}" 'TYPO3' 'PASS' "${registry}" <<'PYEOF' || return 1
+import json, re, sys
+
+project, pack, version, prefix, secret, registry = sys.argv[1:7]
+
+# 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>_%s." % (prefix, prefix, secret),
+        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_%s || '%s' }," % (handle, env, name, env, secret, 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 form,
+  # each default account in its role.
+  local feature="${WORKSPACE_SCRIPTS}/plugins/typo3/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 a site that is set up has them.
+  if typo3_is_installed "${project_path}" ; then
+    ( add_typo3_users > /dev/null ) && echo "  the default accounts are on the site (${users[*]})" ;
+  fi
+}

package/testing/site.feature

@@ -0,0 +1,53 @@
+Feature: The site answers and its accounts work
+  As the owner of the site
+  I want the front page, the login form 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. The module names are those
+  # of a backend in English.
+
+  @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 form is served to a visitor
+    Given I am not logged in
+    Then I should not be logged in
+    And I should see "Username"
+    And I should see "Password"
+
+  Scenario Outline: Each default account logs in
+    Given I am a logged in user with the "<handle>" user
+    Then I should be logged in as "<handle>"
+
+    Examples:
+      | handle |
+      | admin  |
+      | editor |
+
+  # The administrator account is an administrator, not a system maintainer: the modules of a
+  # system maintainer (Extensions, the Admin Tools) stay with the account that set the site up.
+  Scenario: The administrator has the administration modules
+    Given I am a logged in user with the "admin" user
+    Then I should see the "Page" module
+    And I should see the "Backend Users" module
+    And I should see the "Log" module
+
+  Scenario: The editor has the content modules, and no administration module
+    Given I am a logged in user with the "editor" user
+    Then I should see the "Page" module
+    And I should see the "List" module
+    And I should not see the "Backend Users" module
+    And I should not see the "Log" module
+
+  Scenario: Logging out ends the session
+    Given I am a logged in user with the "editor" user
+    When I log out
+    Then I should not be logged in
+    And I should not see a login error