@webship.co/workspace-ghost 1.0.7 → 1.0.8
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 +66 -18
- package/{agents → ai/agents}/ghost-site-builder.md +8 -0
- package/{agents → ai/agents}/ghost-tester.md +12 -2
- package/ai/commands/ghost-test.md +87 -0
- package/ai/prompts/ghost-build-and-test.md +27 -0
- package/ai/skills/ghost-scenarios/SKILL.md +288 -0
- package/ai/skills/ghost-scenarios/examples/front-end.feature +32 -0
- package/ai/skills/ghost-scenarios/examples/post-lifecycle.feature +24 -0
- package/ai/skills/ghost-scenarios/examples/roles-and-screens.feature +31 -0
- package/dist/src/index.d.ts +8 -2
- package/dist/src/index.js +11 -3
- package/dist/src/index.js.map +1 -1
- package/docs/plugin-items-pattern.md +145 -0
- package/features/ghost.feature +15 -2
- package/package.json +27 -5
package/README.md
CHANGED
|
@@ -3,7 +3,8 @@
|
|
|
3
3
|
Ghost for the [Webship Workspace](https://github.com/webship/workspace) dashboard: a builder that
|
|
4
4
|
makes a real, self-hosted Ghost site in a container, a Ghost-CLI tool for the sites it built, the
|
|
5
5
|
default staff accounts, the [Ghost step pack](https://github.com/webship/ghost-steps) wired into
|
|
6
|
-
the workspace's testing setup, and
|
|
6
|
+
the workspace's testing setup, and its AI items — two agents, a skill, a
|
|
7
|
+
command and a prompt — each listed in the workspace folder of its kind.
|
|
7
8
|
|
|
8
9
|
The workspace is container-based (DDEV by default): a Ghost project is a row like any other, so the
|
|
9
10
|
row menus the core draws (start, stop, launch, backup, clone, remove, tests) work on it unchanged.
|
|
@@ -21,20 +22,47 @@ what Ghost needs, see [What is different from a PHP platform](#what-is-different
|
|
|
21
22
|
cd ~/workspace
|
|
22
23
|
bash core/scripts/plugins.sh --require github:webship/workspace-ghost # npm install into the dashboard
|
|
23
24
|
bash core/scripts/plugins.sh --activate ghost # plugins.ghost in settings.yml
|
|
24
|
-
bash core/scripts/plugins.sh --install ghost # commands, functions, args,
|
|
25
|
+
bash core/scripts/plugins.sh --install ghost # commands, functions, args, AI items
|
|
25
26
|
bash core/scripts/plugins.sh --configure ghost # nothing to configure: it has no settings file
|
|
26
27
|
```
|
|
27
28
|
|
|
28
29
|
The same four steps are buttons on the dashboard's **Settings → Plugins** page. `--install` is
|
|
29
|
-
idempotent. `--uninstall` removes what it placed; an
|
|
30
|
+
idempotent. `--uninstall` removes what it placed; an AI item you edited stays.
|
|
30
31
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
32
|
+
Everything the plugin carries lands in the folder it belongs to, when that folder is an active
|
|
33
|
+
workspace folder:
|
|
34
|
+
|
|
35
|
+
| What | Lands in |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| `cmd-ghost-project.sh`, `cmd-tools-ghost-cli.sh` | every active sites folder: `dev/`, `test/`, `sandboxes/`, `demos/` |
|
|
38
|
+
| The agents `ghost-site-builder`, `ghost-tester` | `ai-agents/` |
|
|
39
|
+
| The skill `ghost-scenarios` | `ai-skills/` |
|
|
40
|
+
| The command `/ghost-test` | `ai-commands/` |
|
|
41
|
+
| The prompt `ghost-build-and-test` | `ai-prompts/` |
|
|
42
|
+
|
|
43
|
+
There they are listed like any other item of the folder, and installed into Claude Code from there.
|
|
34
44
|
|
|
35
45
|
The agents, the builder's flags in the Build form and the step pack in the testing setup need a
|
|
36
46
|
Webship Workspace after 1.0.6.
|
|
37
47
|
|
|
48
|
+
## What it needs
|
|
49
|
+
|
|
50
|
+
A workspace starts empty, so the manifest says what else this plugin needs (`needs`):
|
|
51
|
+
|
|
52
|
+
- one sites folder, for the builder and the tool: `dev`, `test`, `sandboxes`, `demos` (`dev` is the one added when none is there). The folder also carries `cmd-tools-testing.sh` and the Users tools this plugin's hooks answer to.
|
|
53
|
+
- `ai-agents`, `ai-skills`, `ai-commands` and `ai-prompts`: the AI folders its agents, its skill, its command and its prompt are placed in.
|
|
54
|
+
|
|
55
|
+
`--require` says so, `--activate` and `--install` stop until the workspace has them, and `--with-needs` adds what is missing first:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
bash core/scripts/plugins.sh --activate ghost --with-needs # dev and the four AI folders are required, activated and installed first
|
|
59
|
+
bash core/scripts/plugins.sh --install ghost
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Everything the builder runs for a site runs in the site's own container, through the container tool the workspace already needs; the plugin asks for no command of its own on the machine.
|
|
63
|
+
|
|
64
|
+
A workspace that knows none of this (Webship Workspace 1.0.8 and older) ignores the keys: add a sites folder and the AI folders yourself, then `--install ghost` again. A kind whose folder is not there is skipped, and the install says so.
|
|
65
|
+
|
|
38
66
|
## What the package holds
|
|
39
67
|
|
|
40
68
|
| Path | What it is |
|
|
@@ -45,10 +73,14 @@ Webship Workspace after 1.0.6.
|
|
|
45
73
|
| `scripts/args/arg-ghost.sh`, `arg-ghost-cli.sh` | Their argparse; the Build form draws the builder's flags from the first |
|
|
46
74
|
| `scripts/ghost-accounts.js` | The setup and the staff accounts through the Admin API, run with Node.js in the project's container |
|
|
47
75
|
| `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 |
|
|
76
|
+
| `ai/agents/ghost-site-builder.md` | The agent that builds and maintains Ghost sites with these commands |
|
|
77
|
+
| `ai/agents/ghost-tester.md` | The agent that writes and runs scenarios with the Ghost step pack |
|
|
78
|
+
| `ai/skills/ghost-scenarios/` | The skill: the step pack's phrases by area, the traps found on a real site, three example features |
|
|
79
|
+
| `ai/commands/ghost-test.md` | The slash command `/ghost-test <site>`: set up, match every step, run, report |
|
|
80
|
+
| `ai/prompts/ghost-build-and-test.md` | A prompt: the whole launch command for a new session |
|
|
50
81
|
| `src/index.ts` | `register(api)`: what the assistant is told about Ghost here |
|
|
51
82
|
| `features/ghost.feature` | Scenarios for the dashboard's own browser suite |
|
|
83
|
+
| `docs/plugin-items-pattern.md` | How a plugin carries its own commands and AI items, and how to prove it |
|
|
52
84
|
|
|
53
85
|
The `workspacePlugin` block in `package.json` is the manifest the installer reads.
|
|
54
86
|
|
|
@@ -137,25 +169,41 @@ webship-js's own, writes the users registry (the handles above, overridable with
|
|
|
137
169
|
places `tests/features/site.feature` when the project has none, and makes sure the default accounts
|
|
138
170
|
are on the site. Run it again and it adds what is missing and keeps what you changed.
|
|
139
171
|
|
|
140
|
-
## The
|
|
172
|
+
## The AI items
|
|
141
173
|
|
|
142
|
-
|
|
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 |
|
|
174
|
+
`ai/` in the package holds one folder per kind, the manifest's `ai` block names each item, and
|
|
175
|
+
`--install` places it in the workspace folder of that kind.
|
|
146
176
|
|
|
147
|
-
|
|
148
|
-
|
|
177
|
+
| Kind | Item | Use it to |
|
|
178
|
+
| --- | --- | --- |
|
|
179
|
+
| Agent | `ghost-site-builder` | Build, update, restart, maintain or remove a Ghost site with the commands above, in containers only |
|
|
180
|
+
| Agent | `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 |
|
|
181
|
+
| Skill | `ghost-scenarios` | Write a scenario from phrases that exist: the pack's steps by area, the handles of the users registry, the traps found on a real site, and three features that pass on a fresh site |
|
|
182
|
+
| Command | `/ghost-test <site> [feature or @tag]` | Run the suite of a site from inside a session: set up when missing, match every step, run, report what failed and why |
|
|
183
|
+
| Prompt | `ghost-build-and-test` | Start a session that builds a site, says what it is, sets the testing stack up and runs the first feature |
|
|
184
|
+
|
|
185
|
+
After `--install` each is in its folder on the dashboard. **Install** there puts an agent, a skill
|
|
186
|
+
or a command into Claude Code (`~/.claude/agents`, `~/.claude/skills`, `~/.claude/commands`), or
|
|
187
|
+
from the command line:
|
|
149
188
|
|
|
150
189
|
```bash
|
|
151
|
-
cd ~/workspace/ai-agents
|
|
152
|
-
bash cmd-tools-ai-items.sh ghost-
|
|
190
|
+
cd ~/workspace/ai-agents && bash cmd-tools-ai-items.sh ghost-tester --install
|
|
191
|
+
cd ~/workspace/ai-skills && bash cmd-tools-ai-items.sh ghost-scenarios --install
|
|
192
|
+
cd ~/workspace/ai-commands && bash cmd-tools-ai-items.sh ghost-test --install
|
|
153
193
|
```
|
|
154
194
|
|
|
195
|
+
A prompt is not installed: it is the whole `claude …` launch command of a new session, and the
|
|
196
|
+
dashboard's **New screen** form lists it as a template. By hand, fill the placeholders in and run
|
|
197
|
+
the command of the file from the folder it names.
|
|
198
|
+
|
|
199
|
+
Every step phrase the items show is checked against the definitions of the step pack and of
|
|
200
|
+
webship-js (`tests/fixtures/step-definitions.txt`), and every command and flag against the
|
|
201
|
+
plugin's own.
|
|
202
|
+
|
|
155
203
|
## Develop it
|
|
156
204
|
|
|
157
205
|
```bash
|
|
158
206
|
npm install # builds dist/ (TypeScript)
|
|
159
207
|
npm run lint
|
|
160
|
-
npm test # the manifest, the commands, the
|
|
208
|
+
npm test # the manifest, the commands, the AI items, the functions against a scaffolded project
|
|
161
209
|
```
|
|
@@ -121,3 +121,11 @@ project (`stop` takes no `-y`), `bash cmd-tools-backup-<folder>.sh <name>`,
|
|
|
121
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
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
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. |
|
|
124
|
+
|
|
125
|
+
## What comes with you
|
|
126
|
+
|
|
127
|
+
The Ghost plugin places these beside you, each in the workspace folder of its kind: the agent
|
|
128
|
+
`ghost-tester` (`ai-agents/`), the skill `ghost-scenarios` (`ai-skills/`), the command
|
|
129
|
+
`/ghost-test <site>` (`ai-commands/`) and the prompt `ghost-build-and-test` (`ai-prompts/`), which
|
|
130
|
+
is this agent's whole first job as a launch command: build, say what the site is, set the testing
|
|
131
|
+
stack up, run the first feature.
|
|
@@ -20,8 +20,8 @@ tools:
|
|
|
20
20
|
|
|
21
21
|
# ghost-tester
|
|
22
22
|
|
|
23
|
-
You test self-hosted Ghost sites in a Webship Workspace (`~/workspace`)
|
|
24
|
-
[webship-js](https://github.com/webship/webship-js) (Playwright and Cucumber) and its Ghost step
|
|
23
|
+
You test self-hosted Ghost sites in a Webship Workspace (`~/workspace`), a container-based
|
|
24
|
+
workspace (DDEV by default), with [webship-js](https://github.com/webship/webship-js) (Playwright and Cucumber) and its Ghost step
|
|
25
25
|
pack, [`@webship-js/ghost-steps`](https://github.com/webship/ghost-steps). The suite lives in the
|
|
26
26
|
project (`cucumber.js`, `tests/features/`, `tests/step-definitions/`) and runs in the project's
|
|
27
27
|
container.
|
|
@@ -132,3 +132,13 @@ Feature: An editor sees every post
|
|
|
132
132
|
|
|
133
133
|
Check every phrase against the installed definitions before you run it: the pack moves, and a phrase
|
|
134
134
|
from memory is a guess.
|
|
135
|
+
|
|
136
|
+
## What comes with you
|
|
137
|
+
|
|
138
|
+
The Ghost plugin places these beside you, each in the workspace folder of its kind:
|
|
139
|
+
|
|
140
|
+
| Item | Where | What it is for |
|
|
141
|
+
| --- | --- | --- |
|
|
142
|
+
| `ghost-scenarios` (skill) | `ai-skills/` | The pack's phrases by area, the traps found on a real site, and three example features that pass on a fresh site |
|
|
143
|
+
| `/ghost-test <site>` (command) | `ai-commands/` | The run itself: set up when missing, match every step, run, report |
|
|
144
|
+
| `ghost-build-and-test` (prompt) | `ai-prompts/` | A new session that builds a site with `ghost-site-builder`'s commands and runs its first feature |
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Test a self-hosted Ghost site of the Webship Workspace with webship-js and the Ghost step pack — set the testing stack up when it is missing, match every step, run the suite (or one feature, or one tag) in the site's container, and report what failed and why.
|
|
3
|
+
argument-hint: '<site> [tests/features/<name>.feature | @tag]'
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# /ghost-test
|
|
7
|
+
|
|
8
|
+
Test the Ghost site named in: `$ARGUMENTS`
|
|
9
|
+
|
|
10
|
+
The first word is the site (its folder name in a sites folder of the workspace). What follows, if
|
|
11
|
+
anything, narrows the run: a path that starts with `tests/features/` is one feature (or one
|
|
12
|
+
folder of features), a word that starts with `@` is a tag expression. With nothing after the site,
|
|
13
|
+
the whole suite runs. With no site at all, stop and ask for one: list the candidates with
|
|
14
|
+
`ls -d ~/workspace/*/*/.ddev/config.ghost.yaml`.
|
|
15
|
+
|
|
16
|
+
The workspace is container-based (DDEV by default) and everything below runs in the site's
|
|
17
|
+
container through the workspace's own command. Never run `npx cucumber-js`, `npx playwright`,
|
|
18
|
+
`ghost`, `node` or `npm` on the host for a site.
|
|
19
|
+
|
|
20
|
+
## 1. Find the site
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
ls ~/workspace/*/<site>/.ddev/config.ghost.yaml
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
`<folder>` is the sites folder the site is in (`dev`, `test`, `sandboxes`, `demos`). If the file is
|
|
27
|
+
not there, stop: this command is for a site built with `cmd-ghost-project.sh`, which writes it. If
|
|
28
|
+
`<folder>` has no `cmd-tools-testing.sh`, stop and say that the folder is not a sites folder of
|
|
29
|
+
this workspace.
|
|
30
|
+
|
|
31
|
+
## 2. Make sure the site answers and the testing stack is there
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
cd ~/workspace/<folder>
|
|
35
|
+
bash cmd-tools-ghost-cli.sh <site>
|
|
36
|
+
grep -c "@webship-js/ghost-steps" <site>/cucumber.js
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
The first prints the version, the address and the staff accounts; if the site does not answer,
|
|
40
|
+
`bash cmd-tools-ghost-cli.sh <site> --restart` starts it again and waits for it. If `cucumber.js`
|
|
41
|
+
is missing or does not name the step pack, set the stack up (it adds what is missing and keeps
|
|
42
|
+
what was changed):
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
bash cmd-tools-testing.sh <site>
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## 3. Match every step, without a browser
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
bash cmd-tools-testing.sh <site> --dry-run # the whole suite
|
|
52
|
+
bash cmd-tools-testing.sh <site> --dry-run --path tests/features/<name>.feature # one feature
|
|
53
|
+
bash cmd-tools-testing.sh <site> --dry-run --tags "@critical" # one tag
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Use the form that matches what was asked. An `Undefined` or `Ambiguous` step is a finding: name
|
|
57
|
+
the feature, the line and the phrase, show the closest phrase the pack defines
|
|
58
|
+
(`grep -hE "^(Given|When|Then)\(" <site>/node_modules/@webship-js/ghost-steps/tests/step-definitions/*.steps.js`),
|
|
59
|
+
and stop before the real run.
|
|
60
|
+
|
|
61
|
+
## 4. Run
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
bash cmd-tools-testing.sh <site> --run # the whole suite
|
|
65
|
+
bash cmd-tools-testing.sh <site> --run --path tests/features/<name>.feature # one feature
|
|
66
|
+
bash cmd-tools-testing.sh <site> --run --tags "@critical" # one tag
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Run it once. Do not add `--retry`, do not tag a scenario `@wip` and do not change a feature to
|
|
70
|
+
make the run pass.
|
|
71
|
+
|
|
72
|
+
## 5. Report
|
|
73
|
+
|
|
74
|
+
Say, in this order:
|
|
75
|
+
|
|
76
|
+
1. The site, its address (`https://<site>.ddev.site`) and what was run (suite, feature or tag).
|
|
77
|
+
2. The totals the run printed: scenarios and steps, passed and failed, and the time.
|
|
78
|
+
3. For each failed scenario: the feature and line, the step that failed, the message, and what
|
|
79
|
+
it means for the site — a defect of the site, a scenario that asserts something the site never
|
|
80
|
+
did, or the environment (the site was stopped, a staff account is missing:
|
|
81
|
+
`bash cmd-tools-ghost-cli.sh <site> --add-users` adds the default ones).
|
|
82
|
+
4. Where the report is: `~/workspace/<folder>/<site>/tests/reports/`.
|
|
83
|
+
|
|
84
|
+
A failing suite is a result: report it as it is. Never create a staff account for a scenario,
|
|
85
|
+
never write a password into a feature file, and never write a platform name into a step phrase.
|
|
86
|
+
For writing or fixing scenarios, use the `ghost-scenarios` skill or hand over to the `ghost-tester`
|
|
87
|
+
agent; for changing the site, to `ghost-site-builder`.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
Build a self-hosted Ghost site in a sites folder and prove it with its first webship-js feature.
|
|
2
|
+
|
|
3
|
+
`claude` is the default launcher; the text between the triple quotes is plain and can be given to another AI CLI as it is.
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
claude --permission-mode bypassPermissions """
|
|
7
|
+
Build a Ghost site named <name> in this sites folder and test it with webship-js
|
|
8
|
+
# ~/workspace/<dev|test|sandboxes|demos> · https://<name>.ddev.site · container-based (DDEV by default)
|
|
9
|
+
# the builder deletes a project of the same name first: stop if <name> is a site somebody still needs
|
|
10
|
+
# nothing on the host: no ghost, node, npm or mysql outside the site's container
|
|
11
|
+
# open source and self-hosted: no hosted service, no payment provider, no vendor account
|
|
12
|
+
|
|
13
|
+
1. bash cmd-ghost-project.sh <name> --install --add-users
|
|
14
|
+
(add --version <x> for a release other than the latest)
|
|
15
|
+
if it says the setup waits at /ghost, the workspace account's password is under 10 characters: stop and tell me
|
|
16
|
+
2. bash cmd-tools-ghost-cli.sh <name>
|
|
17
|
+
tell me the version, the address and the staff accounts it lists
|
|
18
|
+
3. bash cmd-tools-testing.sh <name>
|
|
19
|
+
webship-js, the step pack, the users registry, the mailbox and tests/features/site.feature
|
|
20
|
+
4. bash cmd-tools-testing.sh <name> --dry-run --path tests/features/site.feature
|
|
21
|
+
5. bash cmd-tools-testing.sh <name> --run --path tests/features/site.feature
|
|
22
|
+
|
|
23
|
+
If a command fails, show the line that failed and stop. Do not retry with other flags.
|
|
24
|
+
When the feature is green: the address, the version, how many scenarios and steps passed.
|
|
25
|
+
Then ask me whether to keep the site or remove it with: bash cmd-tools-remove.sh <name>
|
|
26
|
+
"""
|
|
27
|
+
```
|
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ghost-scenarios
|
|
3
|
+
description: Write and run webship-js scenarios for a self-hosted Ghost site of the Webship Workspace with the Ghost step pack (`@webship-js/ghost-steps`) — the phrases of the pack by area (the session and the staff roles, the admin screens and lists, the editor and publishing, tags, the settings, the front end, the membership form), the handles of the users registry, and the workspace command that runs them in the site's container. Use when asked to "write a scenario for this Ghost site", "test the editor role", "which step is there for the admin menu", "add a feature for publishing a post", or when a `.feature` file of a Ghost project is being written or fixed.
|
|
4
|
+
argument-hint: '<site> [what to cover]'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# ghost-scenarios
|
|
8
|
+
|
|
9
|
+
Scenarios for a self-hosted Ghost site of a Webship Workspace (`~/workspace`, container-based, DDEV
|
|
10
|
+
by default), written from the steps of [`@webship-js/ghost-steps`](https://github.com/webship/ghost-steps)
|
|
11
|
+
and of [webship-js](https://github.com/webship/webship-js) itself, and run in the site's container
|
|
12
|
+
by the workspace's own command. It comes with the Ghost plugin (`@webship.co/workspace-ghost`),
|
|
13
|
+
like the builder (`cmd-ghost-project.sh`), the Ghost-CLI tool (`cmd-tools-ghost-cli.sh`) and the
|
|
14
|
+
agents `ghost-site-builder` and `ghost-tester`.
|
|
15
|
+
|
|
16
|
+
## Where everything is
|
|
17
|
+
|
|
18
|
+
| What | Where |
|
|
19
|
+
| --- | --- |
|
|
20
|
+
| The site | `~/workspace/<folder>/<site>`, at `https://<site>.ddev.site`, the admin at `/ghost` (`<folder>` is a sites folder: `dev`, `test`, `sandboxes`, `demos`) |
|
|
21
|
+
| The suite's configuration | `<site>/cucumber.js`: the step definitions it loads, the users registry (`worldParameters.users`) and the mailbox of the site (`mailUrl`) |
|
|
22
|
+
| The features | `<site>/tests/features/*.feature` (`site.feature` is the first one the setup wrote) |
|
|
23
|
+
| The pack's steps | `<site>/node_modules/@webship-js/ghost-steps/tests/step-definitions/*.steps.js` |
|
|
24
|
+
| webship-js's steps | `<site>/node_modules/webship-js/tests/step-definitions/*.js` |
|
|
25
|
+
| The reports | `<site>/tests/reports/` |
|
|
26
|
+
|
|
27
|
+
## The order of work
|
|
28
|
+
|
|
29
|
+
1. **Make sure the testing stack is there.** From the sites folder:
|
|
30
|
+
```bash
|
|
31
|
+
cd ~/workspace/<folder>
|
|
32
|
+
bash cmd-tools-testing.sh <site>
|
|
33
|
+
```
|
|
34
|
+
It adds webship-js, the step pack, the users registry, the address of the mailbox and
|
|
35
|
+
`tests/features/site.feature`, and makes sure the default staff accounts are on the site. It is
|
|
36
|
+
safe to run again: it adds what is missing and keeps what was changed.
|
|
37
|
+
2. **Read the installed steps before writing a phrase.** They are the source of truth: the pack
|
|
38
|
+
moves, and a phrase from memory is a guess.
|
|
39
|
+
```bash
|
|
40
|
+
cd ~/workspace/<folder>/<site>
|
|
41
|
+
grep -hE "^(Given|When|Then)\(" node_modules/@webship-js/ghost-steps/tests/step-definitions/*.steps.js
|
|
42
|
+
```
|
|
43
|
+
Every step carries a comment block with five examples above it; open the file when a phrase
|
|
44
|
+
is not obvious.
|
|
45
|
+
3. **Look at the screen first** (the Playwright MCP browser, a tab of your own) when the scenario
|
|
46
|
+
is about a screen you have not seen. The admin is a single-page application: what a screen
|
|
47
|
+
shows, and to which role, is only known once it has rendered.
|
|
48
|
+
4. **Write the feature** in `<site>/tests/features/`, from phrases that exist (the lists below).
|
|
49
|
+
5. **Match every step without a browser**, then run the feature, then the suite:
|
|
50
|
+
```bash
|
|
51
|
+
cd ~/workspace/<folder>
|
|
52
|
+
bash cmd-tools-testing.sh <site> --dry-run --path tests/features/<name>.feature
|
|
53
|
+
bash cmd-tools-testing.sh <site> --run --path tests/features/<name>.feature
|
|
54
|
+
bash cmd-tools-testing.sh <site> --run --tags "@critical"
|
|
55
|
+
bash cmd-tools-testing.sh <site> --run
|
|
56
|
+
```
|
|
57
|
+
A dry run says `Undefined` for a phrase no definition matches: fix the phrase, do not write a
|
|
58
|
+
step for it.
|
|
59
|
+
|
|
60
|
+
## Accounts: a handle, never a password
|
|
61
|
+
|
|
62
|
+
A scenario signs in by a handle of the users registry. The default staff accounts are on the site
|
|
63
|
+
already (`bash cmd-tools-ghost-cli.sh <site> --add-users` adds them again if they were removed):
|
|
64
|
+
|
|
65
|
+
| Handle | Account | Role |
|
|
66
|
+
| --- | --- | --- |
|
|
67
|
+
| `administrator` | `administrator@example.com` | Administrator |
|
|
68
|
+
| `editor` | `editor@example.com` | Editor |
|
|
69
|
+
| `author` | `author@example.com` | Author |
|
|
70
|
+
| `contributor` | `contributor@example.com` | Contributor |
|
|
71
|
+
|
|
72
|
+
```gherkin
|
|
73
|
+
Given I am logged in to the admin as "editor"
|
|
74
|
+
Then I should be logged in to the admin as "editor"
|
|
75
|
+
And the user menu should show "editor@example.com"
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
The pack's own features also sign in as `owner`. Here the owner of the site is the workspace
|
|
79
|
+
account, which is not in the registry: write the scenario for `administrator`.
|
|
80
|
+
|
|
81
|
+
## The phrases, by area
|
|
82
|
+
|
|
83
|
+
Each line is a phrase the pack defines, and each one passed on a site built with
|
|
84
|
+
`bash cmd-ghost-project.sh <site> --install --add-users` (the names in quotes are that site's: its
|
|
85
|
+
first post, its first page, its tag). Most `should` steps also take the negative: `should not
|
|
86
|
+
see`, `should not be`, `should not offer`.
|
|
87
|
+
|
|
88
|
+
### The session
|
|
89
|
+
|
|
90
|
+
```gherkin
|
|
91
|
+
Given I am an anonymous user
|
|
92
|
+
Given I am logged in to the admin as "editor"
|
|
93
|
+
When I log out of the admin
|
|
94
|
+
Then I should be logged in to the admin as "editor"
|
|
95
|
+
Then I should not be logged in to the admin
|
|
96
|
+
Then the user menu should show "editor@example.com"
|
|
97
|
+
When I try to log in to the admin with the email "editor@example.com" and the password "not-the-password"
|
|
98
|
+
Then I should see the sign in error "Your password is incorrect."
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### Admin screens, by the name on the menu
|
|
102
|
+
|
|
103
|
+
```gherkin
|
|
104
|
+
When I go to the admin screen "Posts"
|
|
105
|
+
Then I should be on the admin screen "Posts"
|
|
106
|
+
Then the admin screen "Settings" should not be available
|
|
107
|
+
Then I should be on the admin screen "sign in"
|
|
108
|
+
Then I should see "Tags" in the admin menu
|
|
109
|
+
Then I should not see "Members" in the admin menu
|
|
110
|
+
When I click "Pages" in the admin menu
|
|
111
|
+
When I search the admin for "Coming soon"
|
|
112
|
+
Then I should see the admin search result "Coming soon"
|
|
113
|
+
When I open the admin search result "Coming soon"
|
|
114
|
+
Then I should see the notification "Post reverted to a draft."
|
|
115
|
+
Then I should see the dialog "Invite a new staff user"
|
|
116
|
+
When I answer the dialog with "Close"
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
The screens that have a name: `Analytics`, `Posts`, `Drafts`, `Scheduled`, `Published`, `Pages`,
|
|
120
|
+
`Tags`, `New tag`, `Members`, `New member`, `Comments`, `Settings`, `Staff`, `New post`,
|
|
121
|
+
`New page`, `sign in`.
|
|
122
|
+
|
|
123
|
+
### The lists, the tags and the staff
|
|
124
|
+
|
|
125
|
+
```gherkin
|
|
126
|
+
Then I should see the page "About this site" in the list
|
|
127
|
+
Then the page "About this site" should have the status "Published" in the list
|
|
128
|
+
Then I should not see the post "A post from the suite" in the list
|
|
129
|
+
Then I should see the tag "News" in the list
|
|
130
|
+
Then the tag "News" should have 1 post
|
|
131
|
+
When I set the tag name to "A tag from the suite"
|
|
132
|
+
Then the tag slug should be "a-tag-from-the-suite"
|
|
133
|
+
When I set the tag description to "Made by the suite."
|
|
134
|
+
When I save the tag
|
|
135
|
+
When I open the tag "A tag from the suite" from the list
|
|
136
|
+
When I delete the tag
|
|
137
|
+
Then I should see the staff user "editor" with the role "Editor"
|
|
138
|
+
When I open the staff user "author"
|
|
139
|
+
Then the staff user email should be "author@example.com"
|
|
140
|
+
Then the staff user role should be "Author"
|
|
141
|
+
When I close the staff user
|
|
142
|
+
Then the staff invitation should offer the role "Contributor"
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
A tag is made on the screen `New tag`. The staff steps open the Staff settings themselves, and
|
|
146
|
+
`the staff invitation should offer the role` opens the invitation dialog and sends nothing: close
|
|
147
|
+
it with `When I answer the dialog with "Close"`.
|
|
148
|
+
|
|
149
|
+
### The editor and publishing
|
|
150
|
+
|
|
151
|
+
```gherkin
|
|
152
|
+
Given there is no post titled "A post from the suite"
|
|
153
|
+
When I start a new post
|
|
154
|
+
When I set the editor title to "A post from the suite"
|
|
155
|
+
When I write "Published by the suite." in the editor
|
|
156
|
+
When I wait for the editor to save
|
|
157
|
+
When I add the tag "News" to the post
|
|
158
|
+
Then the post should have the tag "News"
|
|
159
|
+
When I set the excerpt to "An excerpt."
|
|
160
|
+
Then the excerpt should be "An excerpt."
|
|
161
|
+
Then the post URL should be "a-post-from-the-suite"
|
|
162
|
+
When I preview the post
|
|
163
|
+
Then the preview should show "Published by the suite."
|
|
164
|
+
When I close the preview
|
|
165
|
+
When I open the publish dialog
|
|
166
|
+
Then the publish dialog should say "Ready, set, publish."
|
|
167
|
+
When I publish the post
|
|
168
|
+
Then the publish confirmation should say "A post from the suite"
|
|
169
|
+
When I close the publish confirmation
|
|
170
|
+
When I open the editor of the post "A post from the suite"
|
|
171
|
+
Then the editor title should be "Coming soon"
|
|
172
|
+
Then the editor status should be "Published"
|
|
173
|
+
Then the editor should offer "Update"
|
|
174
|
+
Then the post settings should offer "Excerpt"
|
|
175
|
+
When I unpublish the post
|
|
176
|
+
When I delete the post from the editor
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
`post` and `page` are interchangeable in every one of these. A contributor writes drafts and has
|
|
180
|
+
no Publish button:
|
|
181
|
+
|
|
182
|
+
```gherkin
|
|
183
|
+
Then the editor status should be "Draft"
|
|
184
|
+
Then the editor should not offer "Publish"
|
|
185
|
+
Then the editor should offer "Preview"
|
|
186
|
+
Then the post settings should not offer "Tags"
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### The settings
|
|
190
|
+
|
|
191
|
+
```gherkin
|
|
192
|
+
When I go to the settings section "Title & description"
|
|
193
|
+
Then the settings section "Title & description" should show "dev mysite"
|
|
194
|
+
When I open the navigation settings
|
|
195
|
+
Then the navigation settings should list the link "Home"
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
### The front end
|
|
199
|
+
|
|
200
|
+
```gherkin
|
|
201
|
+
When I go to the homepage
|
|
202
|
+
Then the page should be the home page
|
|
203
|
+
Then the page should be a post
|
|
204
|
+
Then the page should be a page
|
|
205
|
+
Then the page should be the tag archive of "news"
|
|
206
|
+
Then the page generator should start with "Ghost 6"
|
|
207
|
+
Then I should see the post "Coming soon" in the post feed
|
|
208
|
+
Then the post feed should have 1 post
|
|
209
|
+
Then I should see "About" in the site navigation
|
|
210
|
+
Then the archive should be on page 1
|
|
211
|
+
Then the archive should not have a next page
|
|
212
|
+
Then the post should not be restricted to members
|
|
213
|
+
Then I should see a subscribe button
|
|
214
|
+
When I open the site search
|
|
215
|
+
When I search the site for "Coming"
|
|
216
|
+
Then I should see the site search result "Coming soon"
|
|
217
|
+
When I close the site search
|
|
218
|
+
When I open the membership sign up form
|
|
219
|
+
Then the membership form should show "Sign up"
|
|
220
|
+
When I close the membership form
|
|
221
|
+
Then I should not be signed in as a member
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
`I am an anonymous user`, `I go to the homepage`, `I go to "/about/"`, `I should see "<text>"`,
|
|
225
|
+
`I press the key "Escape"` and `the response status code should be 200` are webship-js's own
|
|
226
|
+
steps; its status codes, classes, landmarks and accessibility audits are used as they are and
|
|
227
|
+
never redefined for this platform.
|
|
228
|
+
|
|
229
|
+
## Traps found on a real site
|
|
230
|
+
|
|
231
|
+
- `the user menu should show "…"` opens the user menu and leaves it open, and
|
|
232
|
+
`When I log out of the admin` then cannot click it. Close it first:
|
|
233
|
+
```gherkin
|
|
234
|
+
Then the user menu should show "editor@example.com"
|
|
235
|
+
When I press the key "Escape"
|
|
236
|
+
And I log out of the admin
|
|
237
|
+
```
|
|
238
|
+
- An Editor has `Settings` in the admin menu and has no `Members`: the menu of an Editor is
|
|
239
|
+
`Posts` (with `Drafts`, `Scheduled`, `Published`), `Pages`, `Tags`, `Settings` and `Help`.
|
|
240
|
+
Assert the menu of a role from what the screen showed, not from what the role's name suggests.
|
|
241
|
+
- A site as built has one post (`Coming soon`), one page (`About this site`, at `/about/`), one
|
|
242
|
+
tag (`News`) and the navigation `Home` and `About`. The pack's own features
|
|
243
|
+
(`node_modules/@webship-js/ghost-steps/tests/features/`) are written for the pack's seeded test
|
|
244
|
+
site (`Travel diary 8`, the tag `Guides`): copy the shape, replace every title.
|
|
245
|
+
- A site title is `<folder> <site>` after a build (`dev mysite`), until somebody changes it.
|
|
246
|
+
- A scenario that failed half way leaves its post behind. Open it with
|
|
247
|
+
`Given there is no post titled "<title>"` (and `there is no tag named "<name>"`), so the next
|
|
248
|
+
run starts clean.
|
|
249
|
+
|
|
250
|
+
## Rules
|
|
251
|
+
|
|
252
|
+
- **No staff account is created in a suite.** No invitation that is sent, no call to the Admin API
|
|
253
|
+
in a hook that adds a user. A role the registry does not have is asked for, not made. A member
|
|
254
|
+
is content, not staff: a membership scenario may create one, and removes it again
|
|
255
|
+
(`Given there is no member with the email "<address>"`).
|
|
256
|
+
- **Never the workspace account.** The owner of the site is not in the registry.
|
|
257
|
+
- **No password in a feature file**, except where a wrong password is the subject.
|
|
258
|
+
- **No platform name in a step phrase**: `I am logged in to the admin as "editor"`, never a phrase
|
|
259
|
+
that names the product. The same holds for a custom step.
|
|
260
|
+
- **No selector and no route when a step says it**: `the admin screen "Staff"`, not the route of
|
|
261
|
+
the screen.
|
|
262
|
+
- **What a scenario creates, it removes** in the same scenario, under a title nobody else uses.
|
|
263
|
+
- **Nothing is e-mailed outside and nothing is paid for.** The mail of the site goes to the
|
|
264
|
+
mailbox of the container; no hosted service and no payment provider is connected.
|
|
265
|
+
- **A custom step is the last resort**: look in the pack and in webship-js first, write it in
|
|
266
|
+
`<site>/tests/step-definitions/` with a comment block and examples, and say it may belong in
|
|
267
|
+
the pack.
|
|
268
|
+
- **Everything runs in the container**, through `cmd-tools-testing.sh`. Never `npx cucumber-js`
|
|
269
|
+
or `npx playwright` on the host.
|
|
270
|
+
- **A failing scenario is a result.** No `@wip`, no longer timeout, no looser assertion to turn a
|
|
271
|
+
run green: say what the site did.
|
|
272
|
+
|
|
273
|
+
## Examples that run
|
|
274
|
+
|
|
275
|
+
`examples/` holds three features that pass on a site built with
|
|
276
|
+
`bash cmd-ghost-project.sh <site> --install --add-users`. Copy one into the suite and run it:
|
|
277
|
+
|
|
278
|
+
```bash
|
|
279
|
+
cp ~/workspace/ai-skills/ghost-scenarios/examples/roles-and-screens.feature ~/workspace/<folder>/<site>/tests/features/
|
|
280
|
+
cd ~/workspace/<folder>
|
|
281
|
+
bash cmd-tools-testing.sh <site> --run --path tests/features/roles-and-screens.feature
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
| Feature | What it shows |
|
|
285
|
+
| --- | --- |
|
|
286
|
+
| `examples/roles-and-screens.feature` | Each staff role reaching, or being refused, an admin screen; the admin menu of a role; the staff list |
|
|
287
|
+
| `examples/post-lifecycle.feature` | An editor writing, publishing, viewing, unpublishing and deleting a post: content a scenario creates and removes |
|
|
288
|
+
| `examples/front-end.feature` | A visitor on the home page, a page, a tag archive and the search of the site, with no session |
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
Feature: A visitor reads the site
|
|
2
|
+
As the owner of the site
|
|
3
|
+
I want the home page, the first post, the first page and the tag archive to be served
|
|
4
|
+
So that a theme or a setting that breaks the front end is caught by the suite
|
|
5
|
+
|
|
6
|
+
# The titles are the ones a site has right after it is built: change them to the content of the site.
|
|
7
|
+
|
|
8
|
+
Scenario: The home page lists the posts and the navigation
|
|
9
|
+
Given I am an anonymous user
|
|
10
|
+
When I go to the homepage
|
|
11
|
+
Then the page should be the home page
|
|
12
|
+
And I should see the post "Coming soon" in the post feed
|
|
13
|
+
And I should see "Home" in the site navigation
|
|
14
|
+
And I should see "About" in the site navigation
|
|
15
|
+
And I should see a subscribe button
|
|
16
|
+
And the archive should be on page 1
|
|
17
|
+
|
|
18
|
+
Scenario: A page and a tag archive have their own kind of page
|
|
19
|
+
Given I am an anonymous user
|
|
20
|
+
When I go to "/about/"
|
|
21
|
+
Then the page should be a page
|
|
22
|
+
And the page should not be a post
|
|
23
|
+
When I go to "/tag/news/"
|
|
24
|
+
Then the page should be the tag archive of "news"
|
|
25
|
+
And I should see the post "Coming soon" in the post feed
|
|
26
|
+
|
|
27
|
+
Scenario: The search of the site finds a post
|
|
28
|
+
Given I am an anonymous user
|
|
29
|
+
When I go to the homepage
|
|
30
|
+
And I open the site search
|
|
31
|
+
And I search the site for "Coming"
|
|
32
|
+
Then I should see the site search result "Coming soon"
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
Feature: An editor writes a post and removes it again
|
|
2
|
+
As an editor
|
|
3
|
+
I want to write, publish, unpublish and delete a post
|
|
4
|
+
So that the suite proves the editor works and leaves the site as it found it
|
|
5
|
+
|
|
6
|
+
Scenario: The editor publishes a post, sees it on the site and deletes it
|
|
7
|
+
Given I am logged in to the admin as "editor"
|
|
8
|
+
And there is no post titled "A post written by a scenario"
|
|
9
|
+
When I start a new post
|
|
10
|
+
And I set the editor title to "A post written by a scenario"
|
|
11
|
+
And I write "This post is written and removed by the suite." in the editor
|
|
12
|
+
And I publish the post
|
|
13
|
+
Then the publish confirmation should say "A post written by a scenario"
|
|
14
|
+
When I close the publish confirmation
|
|
15
|
+
Then the post "A post written by a scenario" should have the status "Published" in the list
|
|
16
|
+
When I go to "/a-post-written-by-a-scenario/"
|
|
17
|
+
Then the response status code should be 200
|
|
18
|
+
And the page should be a post
|
|
19
|
+
And I should see "This post is written and removed by the suite."
|
|
20
|
+
When I open the editor of the post "A post written by a scenario"
|
|
21
|
+
And I unpublish the post
|
|
22
|
+
Then the editor status should be "Draft"
|
|
23
|
+
When I delete the post from the editor
|
|
24
|
+
Then I should not see the post "A post written by a scenario" in the list
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
Feature: Each staff role reaches the screens it may use
|
|
2
|
+
As the owner of the site
|
|
3
|
+
I want every staff role to open its own screens and to be refused the others
|
|
4
|
+
So that a change of what a role may do is caught by the suite
|
|
5
|
+
|
|
6
|
+
# The accounts are the default ones; a scenario signs in by a handle of the users registry.
|
|
7
|
+
|
|
8
|
+
Scenario: An editor opens the posts and the tags, and has no Members screen
|
|
9
|
+
Given I am logged in to the admin as "editor"
|
|
10
|
+
When I go to the admin screen "Posts"
|
|
11
|
+
Then I should be on the admin screen "Posts"
|
|
12
|
+
And I should see "Tags" in the admin menu
|
|
13
|
+
And I should not see "Members" in the admin menu
|
|
14
|
+
And the admin screen "Members" should not be available
|
|
15
|
+
|
|
16
|
+
Scenario: An author has the posts and nothing that manages the site
|
|
17
|
+
Given I am logged in to the admin as "author"
|
|
18
|
+
Then I should see "Posts" in the admin menu
|
|
19
|
+
And I should not see "Tags" in the admin menu
|
|
20
|
+
And the admin screen "Tags" should not be available
|
|
21
|
+
And the admin screen "Staff" should not be available
|
|
22
|
+
|
|
23
|
+
Scenario: A contributor is refused the settings
|
|
24
|
+
Given I am logged in to the admin as "contributor"
|
|
25
|
+
Then the admin screen "Settings" should not be available
|
|
26
|
+
|
|
27
|
+
Scenario: An administrator sees each staff account with its role
|
|
28
|
+
Given I am logged in to the admin as "administrator"
|
|
29
|
+
Then I should see the staff user "editor" with the role "Editor"
|
|
30
|
+
And I should see the staff user "author" with the role "Author"
|
|
31
|
+
And I should see the staff user "contributor" with the role "Contributor"
|
package/dist/src/index.d.ts
CHANGED
|
@@ -3,9 +3,9 @@
|
|
|
3
3
|
*
|
|
4
4
|
* What the package carries is placed by the installer from the manifest: the builder and the
|
|
5
5
|
* Ghost-CLI tool in the sites folders, their functions, argparse and the accounts script under
|
|
6
|
-
* core/scripts/plugins/ghost/,
|
|
6
|
+
* core/scripts/plugins/ghost/, its AI items (ai/) in the AI folders. The dashboard needs nothing
|
|
7
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
|
|
8
|
+
* are the core's, the AI items are listed like any other. What register() adds is what the
|
|
9
9
|
* assistant is told.
|
|
10
10
|
*
|
|
11
11
|
* Everything the dashboard is asked for goes through `api`; this package requires nothing from the
|
|
@@ -18,6 +18,12 @@ export declare const PLATFORM = "ghost";
|
|
|
18
18
|
export declare const COMMANDS: string[];
|
|
19
19
|
/** The agents the installer places in the AI Agents folder. */
|
|
20
20
|
export declare const AGENTS: string[];
|
|
21
|
+
/** The skill the installer places in the AI Skills folder (a folder each, with its SKILL.md). */
|
|
22
|
+
export declare const SKILLS: string[];
|
|
23
|
+
/** The slash command the installer places in the AI Commands folder. */
|
|
24
|
+
export declare const AI_COMMANDS: string[];
|
|
25
|
+
/** The prompt the installer places in the AI Prompts folder: a whole launch command for a new session. */
|
|
26
|
+
export declare const PROMPTS: string[];
|
|
21
27
|
/** What the assistant is told about Ghost in this workspace. */
|
|
22
28
|
export declare function assistantContext(): string;
|
|
23
29
|
export declare function register(api: PluginApi): void;
|
package/dist/src/index.js
CHANGED
|
@@ -4,16 +4,16 @@
|
|
|
4
4
|
*
|
|
5
5
|
* What the package carries is placed by the installer from the manifest: the builder and the
|
|
6
6
|
* Ghost-CLI tool in the sites folders, their functions, argparse and the accounts script under
|
|
7
|
-
* core/scripts/plugins/ghost/,
|
|
7
|
+
* core/scripts/plugins/ghost/, its AI items (ai/) in the AI folders. The dashboard needs nothing
|
|
8
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
|
|
9
|
+
* are the core's, the AI items are listed like any other. What register() adds is what the
|
|
10
10
|
* assistant is told.
|
|
11
11
|
*
|
|
12
12
|
* Everything the dashboard is asked for goes through `api`; this package requires nothing from the
|
|
13
13
|
* dashboard's own files, so it can be installed from npm and removed without a trace.
|
|
14
14
|
*/
|
|
15
15
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
16
|
-
exports.AGENTS = exports.COMMANDS = exports.PLATFORM = void 0;
|
|
16
|
+
exports.PROMPTS = exports.AI_COMMANDS = exports.SKILLS = exports.AGENTS = exports.COMMANDS = exports.PLATFORM = void 0;
|
|
17
17
|
exports.assistantContext = assistantContext;
|
|
18
18
|
exports.register = register;
|
|
19
19
|
/** The plugin's name, which its functions are named after. */
|
|
@@ -22,6 +22,12 @@ exports.PLATFORM = 'ghost';
|
|
|
22
22
|
exports.COMMANDS = ['cmd-ghost-project.sh', 'cmd-tools-ghost-cli.sh'];
|
|
23
23
|
/** The agents the installer places in the AI Agents folder. */
|
|
24
24
|
exports.AGENTS = ['ghost-site-builder', 'ghost-tester'];
|
|
25
|
+
/** The skill the installer places in the AI Skills folder (a folder each, with its SKILL.md). */
|
|
26
|
+
exports.SKILLS = ['ghost-scenarios'];
|
|
27
|
+
/** The slash command the installer places in the AI Commands folder. */
|
|
28
|
+
exports.AI_COMMANDS = ['ghost-test'];
|
|
29
|
+
/** The prompt the installer places in the AI Prompts folder: a whole launch command for a new session. */
|
|
30
|
+
exports.PROMPTS = ['ghost-build-and-test'];
|
|
25
31
|
/** What the assistant is told about Ghost in this workspace. */
|
|
26
32
|
function assistantContext() {
|
|
27
33
|
return [
|
|
@@ -32,6 +38,8 @@ function assistantContext() {
|
|
|
32
38
|
'`--update` updates Ghost, `--restart` starts it again, `--add-users` adds the default staff accounts (one per role).',
|
|
33
39
|
'`bash cmd-tools-testing.sh <name>` sets up webship-js with the Ghost step pack; `--run` runs the suite.',
|
|
34
40
|
`For Ghost work, hand over to the agents ${exports.AGENTS.map((a) => `\`${a}\``).join(' and ')}.`,
|
|
41
|
+
`The plugin also places the skill ${exports.SKILLS.map((a) => `\`${a}\``).join(', ')} (the step pack's phrases, by area) in ai-skills/,`,
|
|
42
|
+
`the command ${exports.AI_COMMANDS.map((a) => `\`/${a} <site>\``).join(', ')} in ai-commands/ and the prompt ${exports.PROMPTS.map((a) => `\`${a}\``).join(' and ')} in ai-prompts/.`,
|
|
35
43
|
'Never run ghost, node, npm or mysql on the host for a project; the owner of a site is the workspace account,',
|
|
36
44
|
'and no hosted service or payment provider is connected.',
|
|
37
45
|
].join(' ');
|
package/dist/src/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAuBH,4CAcC;AAED,4BAEC;AArCD,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,iGAAiG;AACpF,QAAA,MAAM,GAAG,CAAC,iBAAiB,CAAC,CAAC;AAE1C,wEAAwE;AAC3D,QAAA,WAAW,GAAG,CAAC,YAAY,CAAC,CAAC;AAE1C,0GAA0G;AAC7F,QAAA,OAAO,GAAG,CAAC,sBAAsB,CAAC,CAAC;AAEhD,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,oCAAoC,cAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,oDAAoD;QAChI,eAAe,mBAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,mCAAmC,eAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB;QACrK,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,145 @@
|
|
|
1
|
+
# A plugin carries its own items
|
|
2
|
+
|
|
3
|
+
Every `@webship.co/workspace-<name>` plugin manages what belongs to it: its `cmd-*.sh` commands and
|
|
4
|
+
its AI items (agents, skills, commands, prompts). The package holds them, the manifest names them,
|
|
5
|
+
and `plugins.sh --install <name>` lists each one in the workspace folder of its kind, when that
|
|
6
|
+
folder is an active workspace folder. `--uninstall` takes them away again. The reference is
|
|
7
|
+
[`@webship.co/workspace-wordpress`](https://github.com/webship/workspace-wordpress), and this plugin
|
|
8
|
+
follows it; below, `<p>` is the plugin's name.
|
|
9
|
+
|
|
10
|
+
## The layout
|
|
11
|
+
|
|
12
|
+
```text
|
|
13
|
+
commands/cmd-<p>-project.sh cmd-*.sh scripts only: builders and tools, placed in workspace folders
|
|
14
|
+
commands/cmd-tools-<p>-cli.sh
|
|
15
|
+
ai/agents/<p>-<role>.md one file per agent
|
|
16
|
+
ai/skills/<p>-<topic>/SKILL.md one folder per skill; every file in it is placed (examples/, references/)
|
|
17
|
+
ai/commands/<p>-<verb>.md one file per slash command
|
|
18
|
+
ai/prompts/<p>-<task>.md one file per prompt
|
|
19
|
+
tests/items.test.ts the shape of every item, and that it names nothing that does not exist
|
|
20
|
+
tests/fixtures/step-definitions.txt the step definitions the items' phrases are checked against (a plugin with a step pack)
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
`commands/` is taken by the `cmd-*.sh` scripts, so the AI items live under `ai/`, one folder per
|
|
24
|
+
kind, named like the manifest's `ai` keys. The installer places an item by the last part of its
|
|
25
|
+
path, whatever folder the package keeps it in, so a plugin that kept its agents in `agents/` moves
|
|
26
|
+
them with `git mv agents ai/agents` and changes two lines of its manifest.
|
|
27
|
+
|
|
28
|
+
## The manifest
|
|
29
|
+
|
|
30
|
+
```json
|
|
31
|
+
"files": ["dist/src", "ai", "commands", "docs", "features", "scripts", "testing", "README.md"],
|
|
32
|
+
"workspacePlugin": {
|
|
33
|
+
"name": "<p>",
|
|
34
|
+
"needs": [["dev", "test", "sandboxes", "demos"], "ai-agents", "ai-skills", "ai-commands", "ai-prompts"],
|
|
35
|
+
"commands": { "types": ["sites"], "workspaces": ["dev", "test", "sandboxes", "demos"],
|
|
36
|
+
"files": ["commands/cmd-<p>-project.sh", "commands/cmd-tools-<p>-cli.sh"] },
|
|
37
|
+
"ai": {
|
|
38
|
+
"agents": ["ai/agents/<p>-site-builder.md", "ai/agents/<p>-tester.md"],
|
|
39
|
+
"skills": ["ai/skills/<p>-scenarios"],
|
|
40
|
+
"commands": ["ai/commands/<p>-test.md"],
|
|
41
|
+
"prompts": ["ai/prompts/<p>-build-and-test.md"]
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
- `ai` is in `files`, or the items are not in the published package.
|
|
47
|
+
- A skill is named by its folder, with no `/SKILL.md` and no trailing slash.
|
|
48
|
+
- `needs` names the folder of every kind the plugin ships, after the folder its commands need. A
|
|
49
|
+
plugin with no `cmd-*.sh` for a sites folder leaves the first entry out; a kind it does not ship
|
|
50
|
+
is left out of `ai` and of `needs`.
|
|
51
|
+
|
|
52
|
+
| Kind | Lands in | Claude Code reads it from |
|
|
53
|
+
| --- | --- | --- |
|
|
54
|
+
| `commands.files` | every active folder `commands.workspaces` names, else every active folder of `commands.types` | the folder itself: `bash cmd-….sh` |
|
|
55
|
+
| `ai.agents` | `ai-agents/<name>.md` | `~/.claude/agents`, after Install |
|
|
56
|
+
| `ai.skills` | `ai-skills/<name>/` | `~/.claude/skills`, after Install |
|
|
57
|
+
| `ai.commands` | `ai-commands/<name>.md` | `~/.claude/commands`, after Install: `/<name>` |
|
|
58
|
+
| `ai.prompts` | `ai-prompts/<name>.md` | nothing: the New screen form lists it as a template for a new session |
|
|
59
|
+
|
|
60
|
+
## The shape of each kind
|
|
61
|
+
|
|
62
|
+
| Kind | Shape |
|
|
63
|
+
| --- | --- |
|
|
64
|
+
| Agent | Frontmatter `name` (the file's name), `description` (when to use it, with the phrases a person says), `model: fable`, `tools`; then what it does, the commands it runs, its rules |
|
|
65
|
+
| Skill | `SKILL.md` with frontmatter `name` (the folder's name) and `description` (what it does, then `Use when …`); files beside it for what is too long or is meant to be copied |
|
|
66
|
+
| Command | Frontmatter `description` and `argument-hint`, no `name` (the file names it); the body reads what was typed from `$ARGUMENTS` |
|
|
67
|
+
| Prompt | No frontmatter. One sentence that says what it is for, then a fenced block holding the whole launch command: `claude --permission-mode bypassPermissions """` … `"""`, with `<placeholders>` to fill in and a `#` line that says where it runs |
|
|
68
|
+
|
|
69
|
+
Names start with the plugin's name (`<p>-…`): an item that is already in the folder under the same
|
|
70
|
+
name is kept, so a name another plugin could also choose would never be placed. A command and a
|
|
71
|
+
prompt never share a name: both end in `~/.claude/commands`.
|
|
72
|
+
|
|
73
|
+
## What an item may say
|
|
74
|
+
|
|
75
|
+
Nothing generic and nothing invented. An item is about what this plugin does in the workspace, and
|
|
76
|
+
every command, flag, path and step phrase in it exists:
|
|
77
|
+
|
|
78
|
+
- commands and flags: the plugin's own (`scripts/args/*.sh`) and the workspace's (`cmd-tools-testing.sh`
|
|
79
|
+
and its flags, `cmd-tools-remove.sh`, `cmd-tools-clone.sh --to`, `cmd-tools-ai-items.sh --install`);
|
|
80
|
+
- step phrases: the plugin's step pack and webship-js, as installed in a real project;
|
|
81
|
+
- the workspace is container-based (DDEV by default); no platform name in a step phrase; no
|
|
82
|
+
account created by a scenario; no password, no personal path, addresses at `example.com`.
|
|
83
|
+
|
|
84
|
+
Run every command an item tells its reader to run, and every scenario it shows, on a real site
|
|
85
|
+
before it is pushed. Two of the three example features of the reference failed on their first real
|
|
86
|
+
run, each on a phrase that exists and matched in a dry run.
|
|
87
|
+
|
|
88
|
+
## The tests to copy
|
|
89
|
+
|
|
90
|
+
`tests/items.test.ts` checks, with no site and no network:
|
|
91
|
+
|
|
92
|
+
1. the manifest: one list per kind, each item under `ai/<kind>/`, in the package, named `<p>-…`,
|
|
93
|
+
`ai` in `files`, the folder of each kind in `needs`, no command and prompt of the same name;
|
|
94
|
+
2. the shape of each kind (the table above; the two expressions the dashboard reads a prompt with);
|
|
95
|
+
3. every `cmd-*.sh` an item names is the plugin's or the workspace's, with flags that exist;
|
|
96
|
+
4. every step in a `gherkin` block or a `.feature` file matches a definition in
|
|
97
|
+
`tests/fixtures/step-definitions.txt`, names no platform and carries no password;
|
|
98
|
+
5. the words: container-based, no personal value, the README lists every item.
|
|
99
|
+
|
|
100
|
+
Refresh the fixture from a project whose testing stack is set up, whenever the pack's release
|
|
101
|
+
line changes (`<pack>` is the plugin's step pack):
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
cd ~/workspace/<folder>/<site>
|
|
105
|
+
{ echo "# <pack> <version> and webship-js <version>" ;
|
|
106
|
+
grep -hE "^(Given|When|Then)\(/" node_modules/<pack>/tests/step-definitions/*.steps.js node_modules/webship-js/tests/step-definitions/*.steps.js \
|
|
107
|
+
| sed -nE 's/^(Given|When|Then)\(\/(.*)\/, (async )?function.*/\2/p' | sort -u ; } > step-definitions.txt
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
`tests/needs.test.ts` holds the exact `needs` list, and `tests/plugin.test.ts` that every file the
|
|
111
|
+
manifest names ships.
|
|
112
|
+
|
|
113
|
+
## Prove it on a fresh workspace
|
|
114
|
+
|
|
115
|
+
Never in a workspace somebody works in. `webship-workspace init <folder>` makes an empty one.
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
npm pack # in the plugin: the tarball of the branch
|
|
119
|
+
cd <the fresh workspace>
|
|
120
|
+
bash core/scripts/plugins.sh --require <path>/webship.co-workspace-<p>-<version>.tgz # says what it needs
|
|
121
|
+
bash core/scripts/plugins.sh --activate <p> # stops: lists what is not here, changes nothing
|
|
122
|
+
bash core/scripts/plugins.sh --activate <p> --with-needs # adds the folders, then activates
|
|
123
|
+
bash core/scripts/plugins.sh --install <p> # "placed …" once per file
|
|
124
|
+
ls dev ai-agents ai-skills ai-commands ai-prompts # each item in its folder
|
|
125
|
+
bash core/scripts/plugins.sh --list # needs: … met by …
|
|
126
|
+
bash core/scripts/plugins.sh --uninstall <p> # "removed …" once per file
|
|
127
|
+
grep -c "<p>" core/config/plugins.installed.yml # 0: the record is gone
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Then, installed again: build one site with the builder, run each command the items name, copy the
|
|
131
|
+
skill's examples into the suite and run them, look at the four AI folders on the dashboard, and
|
|
132
|
+
remove the site with `cmd-tools-remove.sh`.
|
|
133
|
+
|
|
134
|
+
## What was found on the way
|
|
135
|
+
|
|
136
|
+
- A phrase that matches in a dry run can still fail: a step may need another one before it
|
|
137
|
+
(`I should see the page title` needs `Given I am on a page`), or assert something the site does
|
|
138
|
+
not do as built. Only a real run tells.
|
|
139
|
+
- Content a failed scenario created stays on the site. Name it so it is found, and remove it
|
|
140
|
+
through the CLI tool before the next run (an entry in the trash is not in a list of every status).
|
|
141
|
+
- A folder that is not active gets nothing: the install says `skipped <n> <kind>` for it, and
|
|
142
|
+
places the items when the folder is added. With the folder in `needs`, `--activate` and
|
|
143
|
+
`--install` stop before that and offer to add it.
|
|
144
|
+
- An item a person edited in its folder is kept by `--install` and by `--uninstall`: the record
|
|
145
|
+
holds the hash of what was placed.
|
package/features/ghost.feature
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
Feature: The Ghost plugin on the dashboard
|
|
2
|
-
Once the plugin is activated and installed, the sites folders offer the Ghost builder,
|
|
3
|
-
AI
|
|
2
|
+
Once the plugin is activated and installed, the sites folders offer the Ghost builder, each
|
|
3
|
+
AI folder lists the items of its kind the plugin ships, and the Plugins page lists the plugin
|
|
4
|
+
with its steps.
|
|
4
5
|
|
|
5
6
|
Scenario: The plugin is listed on the Plugins page
|
|
6
7
|
Given I am on "/settings/plugins"
|
|
@@ -15,3 +16,15 @@ Feature: The Ghost plugin on the dashboard
|
|
|
15
16
|
Given I am on "/ai-agents"
|
|
16
17
|
Then I should see "ghost-site-builder"
|
|
17
18
|
And I should see "ghost-tester"
|
|
19
|
+
|
|
20
|
+
Scenario: The AI Skills folder lists the skill the plugin ships
|
|
21
|
+
Given I am on "/ai-skills"
|
|
22
|
+
Then I should see "ghost-scenarios"
|
|
23
|
+
|
|
24
|
+
Scenario: The AI Commands folder lists the command the plugin ships
|
|
25
|
+
Given I am on "/ai-commands"
|
|
26
|
+
Then I should see "ghost-test"
|
|
27
|
+
|
|
28
|
+
Scenario: The AI Prompts folder lists the prompt the plugin ships
|
|
29
|
+
Given I am on "/ai-prompts"
|
|
30
|
+
Then I should see "ghost-build-and-test"
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@webship.co/workspace-ghost",
|
|
3
|
-
"version": "1.0.
|
|
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
|
|
3
|
+
"version": "1.0.8",
|
|
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 its AI items in their folders: two agents, a skill, a command and a prompt.",
|
|
5
5
|
"main": "dist/src/index.js",
|
|
6
6
|
"types": "dist/src/index.d.ts",
|
|
7
7
|
"license": "ISC",
|
|
@@ -11,8 +11,9 @@
|
|
|
11
11
|
},
|
|
12
12
|
"files": [
|
|
13
13
|
"dist/src",
|
|
14
|
-
"
|
|
14
|
+
"ai",
|
|
15
15
|
"commands",
|
|
16
|
+
"docs",
|
|
16
17
|
"features",
|
|
17
18
|
"scripts",
|
|
18
19
|
"testing",
|
|
@@ -27,6 +28,18 @@
|
|
|
27
28
|
"workspacePlugin": {
|
|
28
29
|
"name": "ghost",
|
|
29
30
|
"label": "Ghost",
|
|
31
|
+
"needs": [
|
|
32
|
+
[
|
|
33
|
+
"dev",
|
|
34
|
+
"test",
|
|
35
|
+
"sandboxes",
|
|
36
|
+
"demos"
|
|
37
|
+
],
|
|
38
|
+
"ai-agents",
|
|
39
|
+
"ai-skills",
|
|
40
|
+
"ai-commands",
|
|
41
|
+
"ai-prompts"
|
|
42
|
+
],
|
|
30
43
|
"commands": {
|
|
31
44
|
"types": [
|
|
32
45
|
"sites"
|
|
@@ -57,8 +70,17 @@
|
|
|
57
70
|
},
|
|
58
71
|
"ai": {
|
|
59
72
|
"agents": [
|
|
60
|
-
"agents/ghost-site-builder.md",
|
|
61
|
-
"agents/ghost-tester.md"
|
|
73
|
+
"ai/agents/ghost-site-builder.md",
|
|
74
|
+
"ai/agents/ghost-tester.md"
|
|
75
|
+
],
|
|
76
|
+
"skills": [
|
|
77
|
+
"ai/skills/ghost-scenarios"
|
|
78
|
+
],
|
|
79
|
+
"commands": [
|
|
80
|
+
"ai/commands/ghost-test.md"
|
|
81
|
+
],
|
|
82
|
+
"prompts": [
|
|
83
|
+
"ai/prompts/ghost-build-and-test.md"
|
|
62
84
|
]
|
|
63
85
|
},
|
|
64
86
|
"features": [
|