@webship.co/workspace-ghost 0.0.0-stage → 1.0.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +160 -2
- package/agents/ghost-site-builder.md +123 -0
- package/agents/ghost-tester.md +134 -0
- package/commands/cmd-ghost-project.sh +33 -0
- package/commands/cmd-tools-ghost-cli.sh +26 -0
- package/dist/src/index.d.ts +23 -0
- package/dist/src/index.js +42 -0
- package/dist/src/index.js.map +1 -0
- package/features/ghost.feature +17 -0
- package/package.json +74 -4
- package/scripts/args/arg-ghost-cli.sh +25 -0
- package/scripts/args/arg-ghost.sh +21 -0
- package/scripts/functions/fun-ghost.sh +464 -0
- package/scripts/ghost-accounts.js +175 -0
- package/testing/site.feature +47 -0
package/README.md
CHANGED
|
@@ -1,3 +1,161 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @webship.co/workspace-ghost
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Ghost for the [Webship Workspace](https://github.com/webship/workspace) dashboard: a builder that
|
|
4
|
+
makes a real, self-hosted Ghost site in a container, a Ghost-CLI tool for the sites it built, the
|
|
5
|
+
default staff accounts, the [Ghost step pack](https://github.com/webship/ghost-steps) wired into
|
|
6
|
+
the workspace's testing setup, and two AI agents that know all of it.
|
|
7
|
+
|
|
8
|
+
The workspace is container-based (DDEV by default): a Ghost project is a row like any other, so the
|
|
9
|
+
row menus the core draws (start, stop, launch, backup, clone, remove, tests) work on it unchanged.
|
|
10
|
+
|
|
11
|
+
It is the open-source Ghost, self-hosted: no hosted service, no payment provider and no vendor
|
|
12
|
+
account is connected, and the mail of the site never leaves the container.
|
|
13
|
+
|
|
14
|
+
The plugin is made from the reference platform plugin,
|
|
15
|
+
[`@webship.co/workspace-wordpress`](https://github.com/webship/workspace-wordpress); what differs is
|
|
16
|
+
what Ghost needs, see [What is different from a PHP platform](#what-is-different-from-a-php-platform).
|
|
17
|
+
|
|
18
|
+
## Use it
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
cd ~/workspace
|
|
22
|
+
bash core/scripts/plugins.sh --require github:webship/workspace-ghost # npm install into the dashboard
|
|
23
|
+
bash core/scripts/plugins.sh --activate ghost # plugins.ghost in settings.yml
|
|
24
|
+
bash core/scripts/plugins.sh --install ghost # commands, functions, args, agents
|
|
25
|
+
bash core/scripts/plugins.sh --configure ghost # nothing to configure: it has no settings file
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
The same four steps are buttons on the dashboard's **Settings → Plugins** page. `--install` is
|
|
29
|
+
idempotent. `--uninstall` removes what it placed; an agent you edited stays.
|
|
30
|
+
|
|
31
|
+
The commands land in the sites folders that are in the workspace (`dev`, `test`, `sandboxes`,
|
|
32
|
+
`demos`); the agents land in the AI Agents folder (`ai-agents/`) when the workspace has one, and are
|
|
33
|
+
installed into `~/.claude/agents` from there like any other agent.
|
|
34
|
+
|
|
35
|
+
The agents, the builder's flags in the Build form and the step pack in the testing setup need a
|
|
36
|
+
Webship Workspace after 1.0.6.
|
|
37
|
+
|
|
38
|
+
## What the package holds
|
|
39
|
+
|
|
40
|
+
| Path | What it is |
|
|
41
|
+
| --- | --- |
|
|
42
|
+
| `commands/cmd-ghost-project.sh` | The builder, in the Build list as **Ghost (latest)**, installed into every sites folder |
|
|
43
|
+
| `commands/cmd-tools-ghost-cli.sh` | Ghost-CLI for one project: what the site is, a command, an update, a restart, the default accounts |
|
|
44
|
+
| `scripts/functions/fun-ghost.sh` | The bash functions behind both, sourced by bootstrap once installed; the names the core's tools look for (`set_ghost_users`, `add_ghost_users`, `cancel_ghost_users`, `testing_configure_ghost`) |
|
|
45
|
+
| `scripts/args/arg-ghost.sh`, `arg-ghost-cli.sh` | Their argparse; the Build form draws the builder's flags from the first |
|
|
46
|
+
| `scripts/ghost-accounts.js` | The setup and the staff accounts through the Admin API, run with Node.js in the project's container |
|
|
47
|
+
| `testing/site.feature` | The first feature a Ghost project gets when testing is set up |
|
|
48
|
+
| `agents/ghost-site-builder.md` | The agent that builds and maintains Ghost sites with these commands |
|
|
49
|
+
| `agents/ghost-tester.md` | The agent that writes and runs scenarios with the Ghost step pack |
|
|
50
|
+
| `src/index.ts` | `register(api)`: what the assistant is told about Ghost here |
|
|
51
|
+
| `features/ghost.feature` | Scenarios for the dashboard's own browser suite |
|
|
52
|
+
|
|
53
|
+
The `workspacePlugin` block in `package.json` is the manifest the installer reads.
|
|
54
|
+
|
|
55
|
+
## What is different from a PHP platform
|
|
56
|
+
|
|
57
|
+
Ghost is a Node.js application and DDEV has no project type for it. The plugin keeps the shape of
|
|
58
|
+
the reference and changes only this:
|
|
59
|
+
|
|
60
|
+
| | WordPress (the reference) | Ghost |
|
|
61
|
+
| --- | --- | --- |
|
|
62
|
+
| Project | `--project-type=wordpress`, nginx and PHP | `--project-type=generic --webserver-type=generic`: no web server; the router sends the project's address to Ghost's port, and the web container runs Ghost as a daemon (`.ddev/config.ghost.yaml`) |
|
|
63
|
+
| Recognised by | The DDEV project type | The file `.ddev/config.ghost.yaml` |
|
|
64
|
+
| Node.js | The workspace's (24), for the front-end tools | The workspace's (24), and baked into the web image (`.ddev/web-build/Dockerfile.ghost`) so Ghost has it before the daemons start |
|
|
65
|
+
| Database | The container tool's default, settings written by the tool | MySQL 8 from the container tool; `config.production.json` carries the container's own `db` / `db` / `db` |
|
|
66
|
+
| Getting the code | `wp core download` | Ghost-CLI (`ghost install`), with `npx` in the container |
|
|
67
|
+
| Install | `wp core install` | The setup through the Admin API, with the workspace account as the owner |
|
|
68
|
+
| Accounts | WP-CLI | The Admin API: an invitation per account, accepted from the mailbox of the container |
|
|
69
|
+
| Users menu of the row | Reads the project type | Does not apply (no project type): `cmd-tools-ghost-cli.sh --add-users`, or `cmd-tools-add-users.sh <name> ghost` |
|
|
70
|
+
|
|
71
|
+
## The commands
|
|
72
|
+
|
|
73
|
+
Run them from a sites folder. `--help` is safe on both.
|
|
74
|
+
|
|
75
|
+
### Build a site
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
cd ~/workspace/dev
|
|
79
|
+
bash cmd-ghost-project.sh mysite --install --add-users
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
| Flag | What it does |
|
|
83
|
+
| --- | --- |
|
|
84
|
+
| `--version <x>` | The release to install: `latest` (the default), or a number such as `6.77.0` |
|
|
85
|
+
| `--install` | Set the site up, with the workspace account as its owner |
|
|
86
|
+
| `--add-users` | With `--install`: add the default staff accounts, one per role |
|
|
87
|
+
| `--launch` | Open the site when it is ready |
|
|
88
|
+
|
|
89
|
+
The site answers at `https://mysite.ddev.site`, the admin at `/ghost`. The code is in the project's
|
|
90
|
+
`ghost/` folder. The mail of the site goes to the mailbox of the container (`ddev mailpit`); the
|
|
91
|
+
update check and the other calls to outside services are switched off. A project of the same name
|
|
92
|
+
is deleted first.
|
|
93
|
+
|
|
94
|
+
Ghost asks for a password of 10 characters or more: if the workspace account's is shorter, the
|
|
95
|
+
site is built and the builder says that the setup waits at `/ghost`.
|
|
96
|
+
|
|
97
|
+
### Work on a site
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
bash cmd-tools-ghost-cli.sh mysite # version, address, staff accounts
|
|
101
|
+
bash cmd-tools-ghost-cli.sh mysite --run "doctor" # any Ghost-CLI command
|
|
102
|
+
bash cmd-tools-ghost-cli.sh mysite --update # the latest release, then Ghost is started again
|
|
103
|
+
bash cmd-tools-ghost-cli.sh mysite --restart # start Ghost again and wait for it
|
|
104
|
+
bash cmd-tools-ghost-cli.sh mysite --add-users # the default staff accounts
|
|
105
|
+
bash cmd-tools-ghost-cli.sh mysite --cancel-users # delete them, and what they wrote
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The process belongs to the web container, so `ghost start`, `ghost stop` and `ghost restart` do not
|
|
109
|
+
apply: `--restart` is the way.
|
|
110
|
+
|
|
111
|
+
### The default accounts
|
|
112
|
+
|
|
113
|
+
| Account | Role | Handle in the tests |
|
|
114
|
+
| --- | --- | --- |
|
|
115
|
+
| `administrator@example.com` | Administrator | `administrator` |
|
|
116
|
+
| `editor@example.com` | Editor | `editor` |
|
|
117
|
+
| `author@example.com` | Author | `author` |
|
|
118
|
+
| `contributor@example.com` | Contributor | `contributor` |
|
|
119
|
+
|
|
120
|
+
Each has the password of the workspace's other default lists. They are for local sites and for
|
|
121
|
+
tests; the owner of the site is the workspace account and is never written into a test.
|
|
122
|
+
`bash cmd-tools-add-users.sh mysite ghost` and `bash cmd-tools-cancel-users.sh mysite ghost` add
|
|
123
|
+
and remove the same list.
|
|
124
|
+
|
|
125
|
+
### Test a site
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
bash cmd-tools-testing.sh mysite # webship-js, the step pack, the users registry, a first feature
|
|
129
|
+
bash cmd-tools-testing.sh mysite --run # run the suite in the container
|
|
130
|
+
bash cmd-tools-testing.sh mysite --run --path tests/features/site.feature
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
`cmd-tools-testing.sh` is the workspace's own. For a Ghost project it also adds
|
|
134
|
+
`@webship-js/ghost-steps` to `package.json`, lists its step definitions in `cucumber.js` after
|
|
135
|
+
webship-js's own, writes the users registry (the handles above, overridable with
|
|
136
|
+
`SITE_<HANDLE>_EMAIL` and `SITE_<HANDLE>_PASSWORD`) and the address of the mailbox (`mailUrl`),
|
|
137
|
+
places `tests/features/site.feature` when the project has none, and makes sure the default accounts
|
|
138
|
+
are on the site. Run it again and it adds what is missing and keeps what you changed.
|
|
139
|
+
|
|
140
|
+
## The agents
|
|
141
|
+
|
|
142
|
+
| Agent | Use it to |
|
|
143
|
+
| --- | --- |
|
|
144
|
+
| `ghost-site-builder` | Build, update, restart, maintain or remove a Ghost site with the commands above, in containers only |
|
|
145
|
+
| `ghost-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 |
|
|
146
|
+
|
|
147
|
+
After `--install` they are in the AI Agents folder of the dashboard; **Install** there puts one into
|
|
148
|
+
`~/.claude/agents`, or from the command line:
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
cd ~/workspace/ai-agents
|
|
152
|
+
bash cmd-tools-ai-items.sh ghost-tester --install
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## Develop it
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
npm install # builds dist/ (TypeScript)
|
|
159
|
+
npm run lint
|
|
160
|
+
npm test # the manifest, the commands, the agents, the functions against a scaffolded project
|
|
161
|
+
```
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ghost-site-builder
|
|
3
|
+
description: Use this agent to build, maintain, update or remove a self-hosted Ghost site in the Webship Workspace — a new site from `cmd-ghost-project.sh`, Ghost-CLI work through `cmd-tools-ghost-cli.sh` (version, doctor, logs, configuration, updates, a restart, the default staff accounts), start, stop, backup and remove through the workspace's own tools. It works in containers only and never on the host, and connects no hosted service and no payment provider. Invoke for "build a Ghost site", "update Ghost on <site>", "restart Ghost on <site>", "add the test accounts", or "remove the Ghost sandbox". For writing and running test scenarios, hand over to `ghost-tester`.
|
|
4
|
+
model: fable
|
|
5
|
+
tools:
|
|
6
|
+
- Bash
|
|
7
|
+
- Read
|
|
8
|
+
- Write
|
|
9
|
+
- Edit
|
|
10
|
+
- Glob
|
|
11
|
+
- Grep
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# ghost-site-builder
|
|
15
|
+
|
|
16
|
+
You build and look after self-hosted Ghost sites in a Webship Workspace (`~/workspace`), a
|
|
17
|
+
container-based workspace (DDEV by default). Everything goes through the `cmd-*.sh` commands of a
|
|
18
|
+
sites folder (`dev/`, `test/`, `sandboxes/`, `demos/`) and through the project's container. The
|
|
19
|
+
commands come from the Ghost plugin (`@webship.co/workspace-ghost`); if a folder has no
|
|
20
|
+
`cmd-ghost-project.sh`, the plugin is not installed there: say so, and name the steps
|
|
21
|
+
(`bash core/scripts/plugins.sh --require @webship.co/workspace-ghost`, `--activate ghost`,
|
|
22
|
+
`--install ghost`) instead of working around it.
|
|
23
|
+
|
|
24
|
+
Read the command before quoting a flag: `bash <command> --help` is always safe.
|
|
25
|
+
|
|
26
|
+
## What a Ghost project is here
|
|
27
|
+
|
|
28
|
+
Ghost is a Node.js application, not a PHP site, so the project differs from the others in three
|
|
29
|
+
places and nowhere else:
|
|
30
|
+
|
|
31
|
+
- The web container runs no web server of its own. It runs **Ghost as a daemon** (Node.js, baked
|
|
32
|
+
into the web image), and the router sends the project's address to Ghost's port (2368).
|
|
33
|
+
- The database is **MySQL 8**, the container tool's own database service (`db` / `db` / `db`).
|
|
34
|
+
- The mail of the site goes to the **mailbox of the container** (Mailpit, `ddev mailpit`). No
|
|
35
|
+
e-mail leaves the machine; staff invitations and member sign in links are read there.
|
|
36
|
+
|
|
37
|
+
The code of Ghost is in the project's `ghost/` folder (`ghost/current` is the installed release,
|
|
38
|
+
`ghost/content` the themes, images and logs, `ghost/config.production.json` the configuration). A
|
|
39
|
+
Ghost project is recognised by `.ddev/config.ghost.yaml`, which the builder writes.
|
|
40
|
+
|
|
41
|
+
This is the open-source Ghost, self-hosted. Never connect it to a hosted service, a payment
|
|
42
|
+
provider or a paid tier, and never sign in to a vendor account for it.
|
|
43
|
+
|
|
44
|
+
## Build a site
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
cd ~/workspace/sandboxes # or dev, test, demos
|
|
48
|
+
bash cmd-ghost-project.sh mysite --install --add-users
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
| Flag | What it does |
|
|
52
|
+
| --- | --- |
|
|
53
|
+
| `--version <x>` | The release to install: `latest` (the default), or a number such as `6.77.0`. |
|
|
54
|
+
| `--install` | Sets the site up, with the workspace account (`account:` in `core/config/settings.yml`) as its owner. Without it the site waits for its setup at `/ghost`. |
|
|
55
|
+
| `--add-users` | With `--install`: the default staff accounts, one per role (`administrator`, `editor`, `author`, `contributor`). |
|
|
56
|
+
| `--launch` | Opens the site when it is ready. |
|
|
57
|
+
|
|
58
|
+
The site answers at `https://<name>.ddev.site`, the admin at `/ghost`. The builder **deletes a
|
|
59
|
+
project of the same name first**: a build is a clean slate, so never point it at a site somebody
|
|
60
|
+
still needs. The name is a folder, a container project and a host name: short, lowercase, letters,
|
|
61
|
+
digits and hyphens.
|
|
62
|
+
|
|
63
|
+
Ghost refuses a password under 10 characters. The owner is the workspace account, so if its
|
|
64
|
+
password is shorter the builder stops after the site is built and says so: the fix is the
|
|
65
|
+
workspace account, never a made-up owner.
|
|
66
|
+
|
|
67
|
+
## Work on a site
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
bash cmd-tools-ghost-cli.sh mysite # what it is: version, address, staff accounts
|
|
71
|
+
bash cmd-tools-ghost-cli.sh mysite --run "version"
|
|
72
|
+
bash cmd-tools-ghost-cli.sh mysite --run "doctor"
|
|
73
|
+
bash cmd-tools-ghost-cli.sh mysite --run "config get url"
|
|
74
|
+
bash cmd-tools-ghost-cli.sh mysite --update # the latest release, then Ghost is started again
|
|
75
|
+
bash cmd-tools-ghost-cli.sh mysite --restart # after a change to config.production.json or a theme
|
|
76
|
+
bash cmd-tools-ghost-cli.sh mysite --add-users # the default staff accounts
|
|
77
|
+
bash cmd-tools-ghost-cli.sh mysite --cancel-users # and away again, with what they wrote
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
The process is the web container's, not Ghost-CLI's: `ghost start`, `ghost stop` and
|
|
81
|
+
`ghost restart` do not apply here. Use `--restart`, or inside the project
|
|
82
|
+
`ddev exec supervisorctl restart webextradaemons:ghost`. The log is
|
|
83
|
+
`ghost/content/logs/` and `ddev logs`.
|
|
84
|
+
|
|
85
|
+
Ghost has no command line for accounts: the staff accounts are created through the Admin API
|
|
86
|
+
(an invitation, accepted from the mailbox of the container), which is what `--add-users` does.
|
|
87
|
+
|
|
88
|
+
The rest is the workspace's, the same for every project: `ddev start -y` and `ddev stop` in the
|
|
89
|
+
project (`stop` takes no `-y`), `bash cmd-tools-backup-<folder>.sh <name>`,
|
|
90
|
+
`bash cmd-tools-clone.sh <name> --to <new>`, `bash cmd-tools-remove.sh <name>`,
|
|
91
|
+
`bash cmd-tools-testing.sh <name>` (the testing stack, with the Ghost step pack).
|
|
92
|
+
`ddev export-db --file=…` and `ddev import-db --file=…` work on the MySQL database as on any other.
|
|
93
|
+
|
|
94
|
+
## Rules
|
|
95
|
+
|
|
96
|
+
- **Containers only.** Never `ghost`, `node`, `npm`, `pnpm` or `mysql` on the host for a project.
|
|
97
|
+
- **The database settings are the container's own** (`db` / `db` / `db` in
|
|
98
|
+
`config.production.json`, written by the builder). Never write another host, user or password
|
|
99
|
+
there, and nothing personal.
|
|
100
|
+
- **The owner is the workspace account**, never a made-up one. Do not print its password, do not
|
|
101
|
+
write it into a file of the project, and do not put it in a test: the default accounts exist for
|
|
102
|
+
that.
|
|
103
|
+
- **Open source only.** No hosted service, no payment provider, no paid tier, no vendor account.
|
|
104
|
+
- **Remove through the tool.** `bash cmd-tools-remove.sh <name>` takes the containers, the volumes
|
|
105
|
+
and the folder down together; `rm -rf` leaves the containers behind.
|
|
106
|
+
- **One build at a time**, and look at `free -g` before a build on a busy machine. A site you built
|
|
107
|
+
to try something is yours to clear: when the work is done, say what you made and offer to remove
|
|
108
|
+
it. Never delete unasked, and never leave it unmentioned.
|
|
109
|
+
- **Never restart the dashboard** or anything shared (the router, another project) to make your own
|
|
110
|
+
work go through.
|
|
111
|
+
- Say what you ran and what it printed. If a build fails, show the line that failed; do not retry
|
|
112
|
+
with different flags until something passes.
|
|
113
|
+
|
|
114
|
+
## When something is off
|
|
115
|
+
|
|
116
|
+
| What you see | What it is |
|
|
117
|
+
| --- | --- |
|
|
118
|
+
| `ghost install failed` | No network in the container, or a version that does not exist: `--version latest` proves which. A line about the Node.js version means the web image was not rebuilt: `ddev restart` in the project. |
|
|
119
|
+
| A 502 or 503 from the router | Ghost is still starting (the first start creates the tables), or it stopped: `bash cmd-tools-ghost-cli.sh <name> --restart` waits for it and prints the end of the log when it does not come up. |
|
|
120
|
+
| The setup screen instead of the admin | The build ran without `--install`. Build again with `--install`, or finish the setup by hand at `/ghost`. |
|
|
121
|
+
| `Could not sign in as the owner` | The owner's address or password was changed on the site, so it is no longer the workspace account. The accounts cannot be managed from the tool until it is. |
|
|
122
|
+
| `No invitation … reached the mailbox` | The mail of the site no longer goes to the container's mailbox: look at `"mail"` in `ghost/config.production.json`. |
|
|
123
|
+
| `is not a Ghost project` from the CLI tool | The project has no `.ddev/config.ghost.yaml`: it was not built by this builder. |
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ghost-tester
|
|
3
|
+
description: Use this agent to test a self-hosted Ghost site of the Webship Workspace with webship-js and the Ghost step pack (`@webship-js/ghost-steps`) — set the testing stack up with `cmd-tools-testing.sh`, explore the site and its admin 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 signs in by the handles of the users registry, never creates a staff account in a suite, and never writes a platform name into a step phrase. Invoke for "test this Ghost site", "write scenarios for the editor role", "why does this scenario fail", or "run the suite on <site>". For building or changing the site itself, hand over to `ghost-site-builder`.
|
|
4
|
+
model: fable
|
|
5
|
+
tools:
|
|
6
|
+
- Bash
|
|
7
|
+
- Read
|
|
8
|
+
- Write
|
|
9
|
+
- Edit
|
|
10
|
+
- Glob
|
|
11
|
+
- Grep
|
|
12
|
+
- mcp__playwright__browser_navigate
|
|
13
|
+
- mcp__playwright__browser_snapshot
|
|
14
|
+
- mcp__playwright__browser_click
|
|
15
|
+
- mcp__playwright__browser_type
|
|
16
|
+
- mcp__playwright__browser_evaluate
|
|
17
|
+
- mcp__playwright__browser_tabs
|
|
18
|
+
- mcp__playwright__browser_take_screenshot
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
# ghost-tester
|
|
22
|
+
|
|
23
|
+
You test self-hosted Ghost sites in a Webship Workspace (`~/workspace`) with
|
|
24
|
+
[webship-js](https://github.com/webship/webship-js) (Playwright and Cucumber) and its Ghost step
|
|
25
|
+
pack, [`@webship-js/ghost-steps`](https://github.com/webship/ghost-steps). The suite lives in the
|
|
26
|
+
project (`cucumber.js`, `tests/features/`, `tests/step-definitions/`) and runs in the project's
|
|
27
|
+
container.
|
|
28
|
+
|
|
29
|
+
## Set the stack up
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
cd ~/workspace/test # the sites folder the project is in
|
|
33
|
+
bash cmd-tools-testing.sh mysite # webship-js, the step pack, the users registry, a first feature
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
For a Ghost project the setup adds the pack to `package.json`, lists its step definitions in
|
|
37
|
+
`cucumber.js` after webship-js's own, writes the users registry, the address of the mailbox
|
|
38
|
+
(`mailUrl`) and `tests/features/site.feature`, and makes sure the default staff accounts are on the
|
|
39
|
+
site. It is idempotent: run it again and it adds what is missing, and keeps what you changed.
|
|
40
|
+
|
|
41
|
+
## The order of work
|
|
42
|
+
|
|
43
|
+
1. **Read the installed steps.** They are the source of truth, not memory:
|
|
44
|
+
```bash
|
|
45
|
+
ls node_modules/@webship-js/ghost-steps/tests/step-definitions/
|
|
46
|
+
grep -n "^\(Given\|When\|Then\)" node_modules/@webship-js/ghost-steps/tests/step-definitions/ghost.steps.js
|
|
47
|
+
```
|
|
48
|
+
Each step carries a JSDoc block with examples. The pack has four step files: the session and
|
|
49
|
+
the admin menu, the admin lists and settings, the editor, and the front end with the membership
|
|
50
|
+
forms. webship-js's own steps (status codes, classes, landmarks, accessibility) are in
|
|
51
|
+
`node_modules/webship-js/tests/step-definitions/`.
|
|
52
|
+
2. **Look at the site in the Playwright MCP browser first**, in a tab of your own: open the page,
|
|
53
|
+
take a snapshot, do the thing by hand once. The admin is a single-page application, so what a
|
|
54
|
+
screen shows is only known once it has rendered. A scenario written without having seen the
|
|
55
|
+
page asserts what you imagine. Close your tab when you are done; leave other tabs alone.
|
|
56
|
+
3. **Write the scenario** from steps that exist. Run a dry run before a real one:
|
|
57
|
+
```bash
|
|
58
|
+
bash cmd-tools-testing.sh mysite --dry-run # every step matches one definition, no browser
|
|
59
|
+
```
|
|
60
|
+
4. **Run it**, narrow first, then the whole suite:
|
|
61
|
+
```bash
|
|
62
|
+
bash cmd-tools-testing.sh mysite --run --path tests/features/site.feature
|
|
63
|
+
bash cmd-tools-testing.sh mysite --run --tags "@critical"
|
|
64
|
+
bash cmd-tools-testing.sh mysite --run
|
|
65
|
+
```
|
|
66
|
+
5. **Read the result**: `tests/reports/cucumber_report.html`, the screenshot and the page dump of a
|
|
67
|
+
failed step in `tests/screenshots/`. Report what failed and why, not only that it failed.
|
|
68
|
+
|
|
69
|
+
## Accounts
|
|
70
|
+
|
|
71
|
+
A scenario signs in by a **handle** of the users registry (`worldParameters.users` in `cucumber.js`):
|
|
72
|
+
|
|
73
|
+
```gherkin
|
|
74
|
+
Given I am logged in to the admin as "editor"
|
|
75
|
+
Then I should be logged in to the admin as "editor"
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
| Handle | Account | Role |
|
|
79
|
+
| --- | --- | --- |
|
|
80
|
+
| `administrator` | `administrator@example.com` | Administrator |
|
|
81
|
+
| `editor` | `editor@example.com` | Editor |
|
|
82
|
+
| `author` | `author@example.com` | Author |
|
|
83
|
+
| `contributor` | `contributor@example.com` | Contributor |
|
|
84
|
+
|
|
85
|
+
These are the default staff accounts (`bash cmd-tools-ghost-cli.sh mysite --add-users`). Override
|
|
86
|
+
one for another environment with `SITE_<HANDLE>_EMAIL` and `SITE_<HANDLE>_PASSWORD`.
|
|
87
|
+
|
|
88
|
+
The pack's own features also sign in as `owner`. Here the owner of the site is the workspace
|
|
89
|
+
account, which is not in the registry: write the scenario for `administrator`, who may do the same
|
|
90
|
+
in the admin except hand the site over.
|
|
91
|
+
|
|
92
|
+
## Rules
|
|
93
|
+
|
|
94
|
+
- **Never create an account in a suite.** No staff invitation that is sent, no call to the Admin
|
|
95
|
+
API in a hook that adds a user, no step that adds one. Accounts are configuration: they are on
|
|
96
|
+
the site before the suite runs. If a scenario needs a role the registry does not have, say so and
|
|
97
|
+
ask for the account to be added to the site and to the registry.
|
|
98
|
+
- **Never the workspace account.** The owner of the site (the workspace account) is not in the
|
|
99
|
+
registry and its password goes in no file.
|
|
100
|
+
- **No password in a feature file**, except where a wrong password is the subject of the scenario.
|
|
101
|
+
- **No platform name in a step phrase.** A step says what a person does or sees: `I am logged in to
|
|
102
|
+
the admin as "editor"`, `I go to the admin screen "Posts"`, `I should see the post "…" in the post
|
|
103
|
+
feed`. Never a phrase that names the product. The same holds for a custom step you write.
|
|
104
|
+
- **No CSS selector and no route in a scenario when a step of the pack says it.** `the admin
|
|
105
|
+
screen "Staff"`, not `/ghost/#/settings/staff`.
|
|
106
|
+
- **A custom step is the last resort.** Look in the pack and in webship-js first. If one is really
|
|
107
|
+
missing, write it in `tests/step-definitions/`, with a JSDoc block and examples like the pack's,
|
|
108
|
+
and say that it may belong upstream.
|
|
109
|
+
- **Content a scenario creates, it removes**, or it names it so a later run finds and clears it
|
|
110
|
+
(`Given there is no post titled "…"`, `Given there is no tag named "…"`). Members and their
|
|
111
|
+
sign in e-mails are content, not staff: a membership scenario may create a member, reads the
|
|
112
|
+
link from the mailbox of the container, and removes the member again. A suite leaves the site as
|
|
113
|
+
it found it.
|
|
114
|
+
- **Nothing is e-mailed outside and nothing is paid for.** The mail of the site goes to the
|
|
115
|
+
container's mailbox; never point a scenario at a hosted service or a payment provider.
|
|
116
|
+
- **Everything runs in the container.** Never `npx cucumber-js` or `npx playwright` on the host for
|
|
117
|
+
a project.
|
|
118
|
+
- **A failing suite is a result.** Do not tag a scenario `@wip`, raise a timeout or loosen an
|
|
119
|
+
assertion to make a run green. Say what the site did.
|
|
120
|
+
|
|
121
|
+
## A scenario, the way the pack reads
|
|
122
|
+
|
|
123
|
+
```gherkin
|
|
124
|
+
Feature: An editor sees every post
|
|
125
|
+
|
|
126
|
+
Scenario: The editor opens the posts and may publish
|
|
127
|
+
Given I am logged in to the admin as "editor"
|
|
128
|
+
When I go to the admin screen "Posts"
|
|
129
|
+
Then I should be on the admin screen "Posts"
|
|
130
|
+
And I should see "Tags" in the admin menu
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Check every phrase against the installed definitions before you run it: the pack moves, and a phrase
|
|
134
|
+
from memory is a guess.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
|
|
3
|
+
# workspace-name: Ghost (latest)
|
|
4
|
+
|
|
5
|
+
# Installed by the Ghost plugin (plugins.sh --install ghost); __WORKSPACE__ is the workspace it was installed into.
|
|
6
|
+
#
|
|
7
|
+
# Build a self-hosted Ghost site in a container: the latest release, or the one --version names, at
|
|
8
|
+
# https://<name>.ddev.site. With --install the site is set up with the workspace account as its
|
|
9
|
+
# owner; with --add-users it also gets the default staff accounts, one per role.
|
|
10
|
+
|
|
11
|
+
# Bootstrap.
|
|
12
|
+
# Find the workspace tooling from this script, so a fresh clone needs no setup.
|
|
13
|
+
WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
|
|
14
|
+
source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
|
|
15
|
+
|
|
16
|
+
# Load workspace settings.
|
|
17
|
+
eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.__WORKSPACE__.settings.yml);
|
|
18
|
+
|
|
19
|
+
# Set site version.
|
|
20
|
+
site_version="latest";
|
|
21
|
+
|
|
22
|
+
# Distribution.
|
|
23
|
+
distribution_name="ghost";
|
|
24
|
+
distribution_title="Ghost";
|
|
25
|
+
distribution_webroot="";
|
|
26
|
+
|
|
27
|
+
ARGPARSE_DESCRIPTION="Build a ${distribution_title} project in __WORKSPACE__"
|
|
28
|
+
# The args file comes with the plugin: core/scripts/plugins/ghost/ is where plugins.sh --install puts it.
|
|
29
|
+
source ${WORKSPACE_SCRIPTS}/plugins/ghost/args/arg-ghost.sh || exit 1 ;
|
|
30
|
+
|
|
31
|
+
shift $#;
|
|
32
|
+
|
|
33
|
+
ghost_build ;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
|
|
3
|
+
# Installed by the Ghost plugin (plugins.sh --install ghost); __WORKSPACE__ is the workspace it was installed into.
|
|
4
|
+
#
|
|
5
|
+
# Ghost-CLI for one Ghost project of this workspace, in its container: say what the site is,
|
|
6
|
+
# run a Ghost-CLI command, update Ghost, restart it, add or remove the default staff accounts.
|
|
7
|
+
# Nothing here runs on the host.
|
|
8
|
+
|
|
9
|
+
# Bootstrap.
|
|
10
|
+
# Find the workspace tooling from this script, so a fresh clone needs no setup.
|
|
11
|
+
WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
|
|
12
|
+
source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
|
|
13
|
+
|
|
14
|
+
# Load workspace settings.
|
|
15
|
+
eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.__WORKSPACE__.settings.yml);
|
|
16
|
+
|
|
17
|
+
# Distribution.
|
|
18
|
+
distribution_name="ghost";
|
|
19
|
+
|
|
20
|
+
ARGPARSE_DESCRIPTION="Run Ghost-CLI on a Ghost project of __WORKSPACE__: status, a command, an update, a restart, the default accounts"
|
|
21
|
+
# The args file comes with the plugin: core/scripts/plugins/ghost/ is where plugins.sh --install puts it.
|
|
22
|
+
source ${WORKSPACE_SCRIPTS}/plugins/ghost/args/arg-ghost-cli.sh || exit 1 ;
|
|
23
|
+
|
|
24
|
+
shift $#;
|
|
25
|
+
|
|
26
|
+
ghost_cli_tool ;
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Ghost for Webship Workspace: a platform plugin.
|
|
3
|
+
*
|
|
4
|
+
* What the package carries is placed by the installer from the manifest: the builder and the
|
|
5
|
+
* Ghost-CLI tool in the sites folders, their functions, argparse and the accounts script under
|
|
6
|
+
* core/scripts/plugins/ghost/, the agents in the AI Agents folder. The dashboard needs nothing
|
|
7
|
+
* drawn for it: the builder is in the Build list because it is a cmd-*-project.sh, the row menus
|
|
8
|
+
* are the core's, the agents are listed like any other. What register() adds is what the
|
|
9
|
+
* assistant is told.
|
|
10
|
+
*
|
|
11
|
+
* Everything the dashboard is asked for goes through `api`; this package requires nothing from the
|
|
12
|
+
* dashboard's own files, so it can be installed from npm and removed without a trace.
|
|
13
|
+
*/
|
|
14
|
+
import type { PluginApi } from '@webship.co/workspace-plugin-api';
|
|
15
|
+
/** The plugin's name, which its functions are named after. */
|
|
16
|
+
export declare const PLATFORM = "ghost";
|
|
17
|
+
/** The commands the installer places in every sites folder. */
|
|
18
|
+
export declare const COMMANDS: string[];
|
|
19
|
+
/** The agents the installer places in the AI Agents folder. */
|
|
20
|
+
export declare const AGENTS: string[];
|
|
21
|
+
/** What the assistant is told about Ghost in this workspace. */
|
|
22
|
+
export declare function assistantContext(): string;
|
|
23
|
+
export declare function register(api: PluginApi): void;
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Ghost for Webship Workspace: a platform plugin.
|
|
4
|
+
*
|
|
5
|
+
* What the package carries is placed by the installer from the manifest: the builder and the
|
|
6
|
+
* Ghost-CLI tool in the sites folders, their functions, argparse and the accounts script under
|
|
7
|
+
* core/scripts/plugins/ghost/, the agents in the AI Agents folder. The dashboard needs nothing
|
|
8
|
+
* drawn for it: the builder is in the Build list because it is a cmd-*-project.sh, the row menus
|
|
9
|
+
* are the core's, the agents are listed like any other. What register() adds is what the
|
|
10
|
+
* assistant is told.
|
|
11
|
+
*
|
|
12
|
+
* Everything the dashboard is asked for goes through `api`; this package requires nothing from the
|
|
13
|
+
* dashboard's own files, so it can be installed from npm and removed without a trace.
|
|
14
|
+
*/
|
|
15
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
16
|
+
exports.AGENTS = exports.COMMANDS = exports.PLATFORM = void 0;
|
|
17
|
+
exports.assistantContext = assistantContext;
|
|
18
|
+
exports.register = register;
|
|
19
|
+
/** The plugin's name, which its functions are named after. */
|
|
20
|
+
exports.PLATFORM = 'ghost';
|
|
21
|
+
/** The commands the installer places in every sites folder. */
|
|
22
|
+
exports.COMMANDS = ['cmd-ghost-project.sh', 'cmd-tools-ghost-cli.sh'];
|
|
23
|
+
/** The agents the installer places in the AI Agents folder. */
|
|
24
|
+
exports.AGENTS = ['ghost-site-builder', 'ghost-tester'];
|
|
25
|
+
/** What the assistant is told about Ghost in this workspace. */
|
|
26
|
+
function assistantContext() {
|
|
27
|
+
return [
|
|
28
|
+
'Ghost (a plugin, @webship.co/workspace-ghost): a self-hosted Ghost site is built with',
|
|
29
|
+
'`bash cmd-ghost-project.sh <name> --install --add-users` from a sites folder (dev, test, sandboxes, demos),',
|
|
30
|
+
'in a container like every other project, at https://<name>.ddev.site (the admin at /ghost).',
|
|
31
|
+
'`bash cmd-tools-ghost-cli.sh <name>` says what the site is; `--run "<ghost-cli command>"` runs Ghost-CLI in it,',
|
|
32
|
+
'`--update` updates Ghost, `--restart` starts it again, `--add-users` adds the default staff accounts (one per role).',
|
|
33
|
+
'`bash cmd-tools-testing.sh <name>` sets up webship-js with the Ghost step pack; `--run` runs the suite.',
|
|
34
|
+
`For Ghost work, hand over to the agents ${exports.AGENTS.map((a) => `\`${a}\``).join(' and ')}.`,
|
|
35
|
+
'Never run ghost, node, npm or mysql on the host for a project; the owner of a site is the workspace account,',
|
|
36
|
+
'and no hosted service or payment provider is connected.',
|
|
37
|
+
].join(' ');
|
|
38
|
+
}
|
|
39
|
+
function register(api) {
|
|
40
|
+
api.addAssistantContext(assistantContext);
|
|
41
|
+
}
|
|
42
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAcH,4CAYC;AAED,4BAEC;AA1BD,8DAA8D;AACjD,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,uFAAuF;QACvF,6GAA6G;QAC7G,6FAA6F;QAC7F,iHAAiH;QACjH,sHAAsH;QACtH,yGAAyG;QACzG,2CAA2C,cAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG;QACzF,8GAA8G;QAC9G,yDAAyD;KAC1D,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAED,SAAgB,QAAQ,CAAC,GAAc;IACrC,GAAG,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;AAC5C,CAAC"}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
Feature: The Ghost plugin on the dashboard
|
|
2
|
+
Once the plugin is activated and installed, the sites folders offer the Ghost builder, the
|
|
3
|
+
AI Agents folder lists the Ghost agents, and the Plugins page lists the plugin with its steps.
|
|
4
|
+
|
|
5
|
+
Scenario: The plugin is listed on the Plugins page
|
|
6
|
+
Given I am on "/settings/plugins"
|
|
7
|
+
Then I should see "Ghost"
|
|
8
|
+
And I should see "@webship.co/workspace-ghost"
|
|
9
|
+
|
|
10
|
+
Scenario: A sites folder offers the Ghost builder
|
|
11
|
+
Given I am on "/dev"
|
|
12
|
+
Then "option[value='cmd-ghost-project.sh']" should be attached
|
|
13
|
+
|
|
14
|
+
Scenario: The AI Agents folder lists the agents the plugin ships
|
|
15
|
+
Given I am on "/ai-agents"
|
|
16
|
+
Then I should see "ghost-site-builder"
|
|
17
|
+
And I should see "ghost-tester"
|
package/package.json
CHANGED
|
@@ -1,6 +1,76 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@webship.co/workspace-ghost",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.0.7",
|
|
4
|
+
"description": "Ghost for Webship Workspace: the builder (`cmd-ghost-project.sh`) and the Ghost-CLI tool in every sites folder, the default staff accounts, the Ghost step pack wired into the testing setup, and two AI agents in the AI Agents folder.",
|
|
5
|
+
"main": "dist/src/index.js",
|
|
6
|
+
"types": "dist/src/index.d.ts",
|
|
7
|
+
"license": "ISC",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "https://github.com/webship/workspace-ghost.git"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"dist/src",
|
|
14
|
+
"agents",
|
|
15
|
+
"commands",
|
|
16
|
+
"features",
|
|
17
|
+
"scripts",
|
|
18
|
+
"testing",
|
|
19
|
+
"README.md"
|
|
20
|
+
],
|
|
21
|
+
"scripts": {
|
|
22
|
+
"build": "tsc -p tsconfig.json",
|
|
23
|
+
"prepare": "npm run build",
|
|
24
|
+
"test": "npm run build && node --test dist/tests/*.test.js",
|
|
25
|
+
"lint": "tsc -p tsconfig.json --noEmit"
|
|
26
|
+
},
|
|
27
|
+
"workspacePlugin": {
|
|
28
|
+
"name": "ghost",
|
|
29
|
+
"label": "Ghost",
|
|
30
|
+
"commands": {
|
|
31
|
+
"types": [
|
|
32
|
+
"sites"
|
|
33
|
+
],
|
|
34
|
+
"workspaces": [
|
|
35
|
+
"dev",
|
|
36
|
+
"test",
|
|
37
|
+
"sandboxes",
|
|
38
|
+
"demos"
|
|
39
|
+
],
|
|
40
|
+
"files": [
|
|
41
|
+
"commands/cmd-ghost-project.sh",
|
|
42
|
+
"commands/cmd-tools-ghost-cli.sh"
|
|
43
|
+
]
|
|
44
|
+
},
|
|
45
|
+
"scripts": {
|
|
46
|
+
"functions": [
|
|
47
|
+
"scripts/functions/fun-ghost.sh"
|
|
48
|
+
],
|
|
49
|
+
"args": [
|
|
50
|
+
"scripts/args/arg-ghost.sh",
|
|
51
|
+
"scripts/args/arg-ghost-cli.sh"
|
|
52
|
+
],
|
|
53
|
+
"machine": [
|
|
54
|
+
"scripts/ghost-accounts.js",
|
|
55
|
+
"testing/site.feature"
|
|
56
|
+
]
|
|
57
|
+
},
|
|
58
|
+
"ai": {
|
|
59
|
+
"agents": [
|
|
60
|
+
"agents/ghost-site-builder.md",
|
|
61
|
+
"agents/ghost-tester.md"
|
|
62
|
+
]
|
|
63
|
+
},
|
|
64
|
+
"features": [
|
|
65
|
+
"features/ghost.feature"
|
|
66
|
+
]
|
|
67
|
+
},
|
|
68
|
+
"devDependencies": {
|
|
69
|
+
"@types/node": "^24.0.0",
|
|
70
|
+
"@webship.co/workspace-plugin-api": "^1.0.7",
|
|
71
|
+
"typescript": "^5.9.0"
|
|
72
|
+
},
|
|
73
|
+
"publishConfig": {
|
|
74
|
+
"access": "public"
|
|
75
|
+
}
|
|
76
|
+
}
|