@webship.co/workspace-gatsby 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}/gatsby-site-builder.md +8 -0
- package/{agents → ai/agents}/gatsby-tester.md +12 -2
- package/ai/commands/gatsby-test.md +92 -0
- package/ai/prompts/gatsby-build-and-test.md +26 -0
- package/ai/skills/gatsby-scenarios/SKILL.md +182 -0
- package/ai/skills/gatsby-scenarios/examples/built-pages.feature +32 -0
- package/ai/skills/gatsby-scenarios/examples/images-and-manifest.feature +19 -0
- package/ai/skills/gatsby-scenarios/examples/routing.feature +17 -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/gatsby.feature +15 -2
- package/package.json +27 -5
package/README.md
CHANGED
|
@@ -4,7 +4,8 @@ Gatsby for the [Webship Workspace](https://github.com/webship/workspace) dashboa
|
|
|
4
4
|
makes a real Gatsby site from a starter in a container, builds it to a production build and serves
|
|
5
5
|
it, a Gatsby CLI tool for the sites it built, the
|
|
6
6
|
[Gatsby step pack](https://github.com/webship/gatsby-steps) wired into the workspace's testing
|
|
7
|
-
setup, and
|
|
7
|
+
setup, and its AI items — two agents, a skill, a
|
|
8
|
+
command and a prompt — each listed in the workspace folder of its kind.
|
|
8
9
|
|
|
9
10
|
The workspace is container-based (DDEV by default): a Gatsby project is a row like any other, so
|
|
10
11
|
the row menus the core draws (start, stop, launch, backup, clone, remove, tests) work on it; what
|
|
@@ -20,20 +21,47 @@ The plugin is made from the reference platform plugin,
|
|
|
20
21
|
cd ~/workspace
|
|
21
22
|
bash core/scripts/plugins.sh --require github:webship/workspace-gatsby # npm install into the dashboard
|
|
22
23
|
bash core/scripts/plugins.sh --activate gatsby # plugins.gatsby in settings.yml
|
|
23
|
-
bash core/scripts/plugins.sh --install gatsby # commands, functions, args,
|
|
24
|
+
bash core/scripts/plugins.sh --install gatsby # commands, functions, args, AI items
|
|
24
25
|
bash core/scripts/plugins.sh --configure gatsby # nothing to configure: it has no settings file
|
|
25
26
|
```
|
|
26
27
|
|
|
27
28
|
The same four steps are buttons on the dashboard's **Settings → Plugins** page. `--install` is
|
|
28
|
-
idempotent. `--uninstall` removes what it placed; an
|
|
29
|
+
idempotent. `--uninstall` removes what it placed; an AI item you edited stays.
|
|
29
30
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
31
|
+
Everything the plugin carries lands in the folder it belongs to, when that folder is an active
|
|
32
|
+
workspace folder:
|
|
33
|
+
|
|
34
|
+
| What | Lands in |
|
|
35
|
+
| --- | --- |
|
|
36
|
+
| `cmd-gatsby-project.sh`, `cmd-tools-gatsby-cli.sh` | every active sites folder: `dev/`, `test/`, `sandboxes/`, `demos/` |
|
|
37
|
+
| The agents `gatsby-site-builder`, `gatsby-tester` | `ai-agents/` |
|
|
38
|
+
| The skill `gatsby-scenarios` | `ai-skills/` |
|
|
39
|
+
| The command `/gatsby-test` | `ai-commands/` |
|
|
40
|
+
| The prompt `gatsby-build-and-test` | `ai-prompts/` |
|
|
41
|
+
|
|
42
|
+
There they are listed like any other item of the folder, and installed into Claude Code from there.
|
|
33
43
|
|
|
34
44
|
The agents, the builder's flags in the Build form and the step pack in the testing setup need a
|
|
35
45
|
Webship Workspace after 1.0.6.
|
|
36
46
|
|
|
47
|
+
## What it needs
|
|
48
|
+
|
|
49
|
+
A workspace starts empty, so the manifest says what else this plugin needs (`needs`):
|
|
50
|
+
|
|
51
|
+
- 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.
|
|
52
|
+
- `ai-agents`, `ai-skills`, `ai-commands` and `ai-prompts`: the AI folders its agents, its skill, its command and its prompt are placed in.
|
|
53
|
+
|
|
54
|
+
`--require` says so, `--activate` and `--install` stop until the workspace has them, and `--with-needs` adds what is missing first:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
bash core/scripts/plugins.sh --activate gatsby --with-needs # dev and the four AI folders are required, activated and installed first
|
|
58
|
+
bash core/scripts/plugins.sh --install gatsby
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
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.
|
|
62
|
+
|
|
63
|
+
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 gatsby` again. A kind whose folder is not there is skipped, and the install says so.
|
|
64
|
+
|
|
37
65
|
## What the package holds
|
|
38
66
|
|
|
39
67
|
| Path | What it is |
|
|
@@ -43,10 +71,14 @@ Webship Workspace after 1.0.6.
|
|
|
43
71
|
| `scripts/functions/fun-gatsby.sh` | The bash functions behind both, sourced by bootstrap once installed; the names the core's tools look for (`set_gatsby_users`, `add_gatsby_users`, `cancel_gatsby_users`, `testing_configure_gatsby`) |
|
|
44
72
|
| `scripts/args/arg-gatsby.sh`, `arg-gatsby-cli.sh` | Their argparse; the Build form draws the builder's flags from the first |
|
|
45
73
|
| `testing/site.feature` | The first feature a Gatsby project gets when testing is set up |
|
|
46
|
-
| `agents/gatsby-site-builder.md` | The agent that builds and maintains Gatsby sites with these commands |
|
|
47
|
-
| `agents/gatsby-tester.md` | The agent that writes and runs scenarios with the Gatsby step pack |
|
|
74
|
+
| `ai/agents/gatsby-site-builder.md` | The agent that builds and maintains Gatsby sites with these commands |
|
|
75
|
+
| `ai/agents/gatsby-tester.md` | The agent that writes and runs scenarios with the Gatsby step pack |
|
|
76
|
+
| `ai/skills/gatsby-scenarios/` | The skill: the step pack's phrases by area, the traps found on a real site, three example features |
|
|
77
|
+
| `ai/commands/gatsby-test.md` | The slash command `/gatsby-test <site>`: set up, match every step, run, report |
|
|
78
|
+
| `ai/prompts/gatsby-build-and-test.md` | A prompt: the whole launch command for a new session |
|
|
48
79
|
| `src/index.ts` | `register(api)`: what the assistant is told about Gatsby here |
|
|
49
80
|
| `features/gatsby.feature` | Scenarios for the dashboard's own browser suite |
|
|
81
|
+
| `docs/plugin-items-pattern.md` | How a plugin carries its own commands and AI items, and how to prove it |
|
|
50
82
|
|
|
51
83
|
The `workspacePlugin` block in `package.json` is the manifest the installer reads.
|
|
52
84
|
|
|
@@ -124,25 +156,41 @@ webship-js's own, and places `tests/features/site.feature` when the project has
|
|
|
124
156
|
page as a production build, rendered and hydrated, its page data and its 404 page. There is no
|
|
125
157
|
users registry. Run it again and it adds what is missing and keeps what you changed.
|
|
126
158
|
|
|
127
|
-
## The
|
|
159
|
+
## The AI items
|
|
128
160
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
| `gatsby-site-builder` | Make a site from a starter, build it again, update, maintain or remove it with the commands above, in containers only |
|
|
132
|
-
| `gatsby-tester` | Set the testing stack up, look at the built 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 |
|
|
161
|
+
`ai/` in the package holds one folder per kind, the manifest's `ai` block names each item, and
|
|
162
|
+
`--install` places it in the workspace folder of that kind.
|
|
133
163
|
|
|
134
|
-
|
|
135
|
-
|
|
164
|
+
| Kind | Item | Use it to |
|
|
165
|
+
| --- | --- | --- |
|
|
166
|
+
| Agent | `gatsby-site-builder` | Make a site from a starter, build it again, update, maintain or remove it with the commands above, in containers only |
|
|
167
|
+
| Agent | `gatsby-tester` | Set the testing stack up, look at the built 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 |
|
|
168
|
+
| Skill | `gatsby-scenarios` | Write a scenario from phrases that exist: the pack's steps by area (the build and hydration, page data and the 404 page, client-side routing, images, the manifest), the traps found on a real site, and three features that pass on a site from the default starter |
|
|
169
|
+
| Command | `/gatsby-test <site> [feature or @tag]` | Run the suite of a site from inside a session: set up when missing, match every step, run against the production build, report what failed and why |
|
|
170
|
+
| Prompt | `gatsby-build-and-test` | Start a session that makes a site from a starter, builds and serves it, sets the testing stack up and runs the first feature |
|
|
171
|
+
|
|
172
|
+
After `--install` each is in its folder on the dashboard. **Install** there puts an agent, a skill
|
|
173
|
+
or a command into Claude Code (`~/.claude/agents`, `~/.claude/skills`, `~/.claude/commands`), or
|
|
174
|
+
from the command line:
|
|
136
175
|
|
|
137
176
|
```bash
|
|
138
|
-
cd ~/workspace/ai-agents
|
|
139
|
-
bash cmd-tools-ai-items.sh gatsby-
|
|
177
|
+
cd ~/workspace/ai-agents && bash cmd-tools-ai-items.sh gatsby-tester --install
|
|
178
|
+
cd ~/workspace/ai-skills && bash cmd-tools-ai-items.sh gatsby-scenarios --install
|
|
179
|
+
cd ~/workspace/ai-commands && bash cmd-tools-ai-items.sh gatsby-test --install
|
|
140
180
|
```
|
|
141
181
|
|
|
182
|
+
A prompt is not installed: it is the whole `claude …` launch command of a new session, and the
|
|
183
|
+
dashboard's **New screen** form lists it as a template. By hand, fill the placeholders in and run
|
|
184
|
+
the command of the file from the folder it names.
|
|
185
|
+
|
|
186
|
+
Every step phrase the items show is checked against the definitions of the step pack and of
|
|
187
|
+
webship-js (`tests/fixtures/step-definitions.txt`), and every command and flag against the
|
|
188
|
+
plugin's own.
|
|
189
|
+
|
|
142
190
|
## Develop it
|
|
143
191
|
|
|
144
192
|
```bash
|
|
145
193
|
npm install # builds dist/ (TypeScript)
|
|
146
194
|
npm run lint
|
|
147
|
-
npm test # the manifest, the commands, the
|
|
195
|
+
npm test # the manifest, the commands, the AI items, the functions against a scaffolded project
|
|
148
196
|
```
|
|
@@ -108,3 +108,11 @@ folder; the database export it also tries has nothing to export and says so),
|
|
|
108
108
|
| A 502 or 404 from the router | No production build yet (`--build`), or the server stopped (`--restart`). |
|
|
109
109
|
| The old page after a change | The address serves the build: `--build`. |
|
|
110
110
|
| `is not a Gatsby project` from the CLI tool | The project has no `.ddev/config.gatsby.yaml`: it was not built by this builder. |
|
|
111
|
+
|
|
112
|
+
## What comes with you
|
|
113
|
+
|
|
114
|
+
The Gatsby plugin places these beside you, each in the workspace folder of its kind: the agent
|
|
115
|
+
`gatsby-tester` (`ai-agents/`), the skill `gatsby-scenarios` (`ai-skills/`), the command
|
|
116
|
+
`/gatsby-test <site>` (`ai-commands/`) and the prompt `gatsby-build-and-test` (`ai-prompts/`),
|
|
117
|
+
which is this agent's whole first job as a launch command: make the site from a starter, build
|
|
118
|
+
and serve it, set the testing stack up, run the first feature.
|
|
@@ -20,8 +20,8 @@ tools:
|
|
|
20
20
|
|
|
21
21
|
# gatsby-tester
|
|
22
22
|
|
|
23
|
-
You test Gatsby sites in a Webship Workspace (`~/workspace`)
|
|
24
|
-
[webship-js](https://github.com/webship/webship-js) (Playwright and Cucumber) and its Gatsby step
|
|
23
|
+
You test Gatsby sites in a Webship Workspace (`~/workspace`), a container-based workspace (DDEV
|
|
24
|
+
by default), with [webship-js](https://github.com/webship/webship-js) (Playwright and Cucumber) and its Gatsby step
|
|
25
25
|
pack, [`@webship-js/gatsby-steps`](https://github.com/webship/gatsby-steps). The suite lives in
|
|
26
26
|
the project (`cucumber.js`, `tests/features/`, `tests/step-definitions/`), next to the site's
|
|
27
27
|
`site/` folder and not in it, and runs in the project's container against the production build
|
|
@@ -114,3 +114,13 @@ Feature: The home page
|
|
|
114
114
|
|
|
115
115
|
Check every phrase against the installed definitions before you run it: the pack moves, and a phrase
|
|
116
116
|
from memory is a guess.
|
|
117
|
+
|
|
118
|
+
## What comes with you
|
|
119
|
+
|
|
120
|
+
The Gatsby plugin places these beside you, each in the workspace folder of its kind:
|
|
121
|
+
|
|
122
|
+
| Item | Where | What it is for |
|
|
123
|
+
| --- | --- | --- |
|
|
124
|
+
| `gatsby-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 site from the default starter |
|
|
125
|
+
| `/gatsby-test <site>` (command) | `ai-commands/` | The run itself: set up when missing, check the build, match every step, run, report |
|
|
126
|
+
| `gatsby-build-and-test` (prompt) | `ai-prompts/` | A new session that makes a site with `gatsby-site-builder`'s commands and runs its first feature |
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Test a Gatsby site of the Webship Workspace with webship-js and the Gatsby step pack — set the testing stack up when it is missing, check which production build is served, 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
|
+
# /gatsby-test
|
|
7
|
+
|
|
8
|
+
Test the Gatsby 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.gatsby.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
|
+
`gatsby`, `node` or `npm` on the host for a site.
|
|
19
|
+
|
|
20
|
+
## 1. Find the site
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
ls ~/workspace/*/<site>/.ddev/config.gatsby.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-gatsby-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 build is served and the testing stack is there
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
cd ~/workspace/<folder>
|
|
35
|
+
bash cmd-tools-gatsby-cli.sh <site>
|
|
36
|
+
grep -c "@webship-js/gatsby-steps" <site>/cucumber.js
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
The first prints the version, the production build with the time it was made, and whether the
|
|
40
|
+
server runs. The suite tests that build, not the source. If the server is not running,
|
|
41
|
+
`bash cmd-tools-gatsby-cli.sh <site> --restart` starts it again. Do not build unasked: if the
|
|
42
|
+
source is newer than the build, say so in the report, with the command that builds
|
|
43
|
+
(`bash cmd-tools-gatsby-cli.sh <site> --build`).
|
|
44
|
+
|
|
45
|
+
If `cucumber.js` is missing or does not name the step pack, set the stack up (it adds what is
|
|
46
|
+
missing and keeps what was changed):
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
bash cmd-tools-testing.sh <site>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## 3. Match every step, without a browser
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
bash cmd-tools-testing.sh <site> --dry-run # the whole suite
|
|
56
|
+
bash cmd-tools-testing.sh <site> --dry-run --path tests/features/<name>.feature # one feature
|
|
57
|
+
bash cmd-tools-testing.sh <site> --dry-run --tags "@critical" # one tag
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Use the form that matches what was asked. An `Undefined` or `Ambiguous` step is a finding: name
|
|
61
|
+
the feature, the line and the phrase, show the closest phrase the pack defines
|
|
62
|
+
(`grep -hE "^(Given|When|Then)\(" <site>/node_modules/@webship-js/gatsby-steps/tests/step-definitions/*.steps.js`),
|
|
63
|
+
and stop before the real run.
|
|
64
|
+
|
|
65
|
+
## 4. Run
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
bash cmd-tools-testing.sh <site> --run # the whole suite
|
|
69
|
+
bash cmd-tools-testing.sh <site> --run --path tests/features/<name>.feature # one feature
|
|
70
|
+
bash cmd-tools-testing.sh <site> --run --tags "@critical" # one tag
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Run it once. Do not add `--retry`, do not tag a scenario `@wip` and do not change a feature to
|
|
74
|
+
make the run pass.
|
|
75
|
+
|
|
76
|
+
## 5. Report
|
|
77
|
+
|
|
78
|
+
Say, in this order:
|
|
79
|
+
|
|
80
|
+
1. The site, its address (`https://<site>.ddev.site`), the build that was tested (when it was
|
|
81
|
+
made) and what was run (suite, feature or tag).
|
|
82
|
+
2. The totals the run printed: scenarios and steps, passed and failed, and the time.
|
|
83
|
+
3. For each failed scenario: the feature and line, the step that failed, the message, and what
|
|
84
|
+
it means for the site — a defect of the site, a scenario that asserts something the site never
|
|
85
|
+
did (a page of another starter, a link to another site), or the environment (the server was
|
|
86
|
+
stopped, the build is older than the source).
|
|
87
|
+
4. Where the report is: `~/workspace/<folder>/<site>/tests/reports/`.
|
|
88
|
+
|
|
89
|
+
A failing suite is a result: report it as it is. The site has no accounts: never add one for a
|
|
90
|
+
scenario, and never write a platform name into a step phrase. For writing or fixing scenarios,
|
|
91
|
+
use the `gatsby-scenarios` skill or hand over to the `gatsby-tester` agent; for changing or building
|
|
92
|
+
the site, to `gatsby-site-builder`.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
Make a Gatsby site from a starter in a sites folder, serve its production build 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 Gatsby 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 gatsby, node, npm or npx outside the site's container
|
|
11
|
+
# a static site: no database and no accounts, and none is added to make a tool happy
|
|
12
|
+
|
|
13
|
+
1. bash cmd-gatsby-project.sh <name> --install
|
|
14
|
+
(add --starter <url> for a starter other than the default one, and --ref <x> for a commit, a branch or a tag of it)
|
|
15
|
+
2. bash cmd-tools-gatsby-cli.sh <name>
|
|
16
|
+
tell me the version, the address, how many pages the production build has and whether the server runs
|
|
17
|
+
3. bash cmd-tools-testing.sh <name>
|
|
18
|
+
webship-js, the step pack and tests/features/site.feature
|
|
19
|
+
4. bash cmd-tools-testing.sh <name> --dry-run --path tests/features/site.feature
|
|
20
|
+
5. bash cmd-tools-testing.sh <name> --run --path tests/features/site.feature
|
|
21
|
+
|
|
22
|
+
If a command fails, show the line that failed and stop. Do not retry with other flags.
|
|
23
|
+
When the feature is green: the address, the version, how many scenarios and steps passed.
|
|
24
|
+
Then ask me whether to keep the site or remove it with: bash cmd-tools-remove.sh <name>
|
|
25
|
+
"""
|
|
26
|
+
```
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gatsby-scenarios
|
|
3
|
+
description: Write and run webship-js scenarios for a Gatsby site of the Webship Workspace with the Gatsby step pack (`@webship-js/gatsby-steps`) — the phrases of the pack by area (the production build and hydration, page data and the 404 page, client-side routing and the route announcer, images, the web app manifest), what a site from the default starter does, and the workspace command that runs them in the site's container against the build. Use when asked to "write a scenario for this Gatsby site", "test the links of the site", "which step is there for the 404 page", "check that the page is hydrated", or when a `.feature` file of a Gatsby project is being written or fixed.
|
|
4
|
+
argument-hint: '<site> [what to cover]'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# gatsby-scenarios
|
|
8
|
+
|
|
9
|
+
Scenarios for a Gatsby site of a Webship Workspace (`~/workspace`, container-based, DDEV by
|
|
10
|
+
default), written from the steps of [`@webship-js/gatsby-steps`](https://github.com/webship/gatsby-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 Gatsby plugin (`@webship.co/workspace-gatsby`),
|
|
13
|
+
like the builder (`cmd-gatsby-project.sh`), the Gatsby CLI tool (`cmd-tools-gatsby-cli.sh`) and the
|
|
14
|
+
agents `gatsby-site-builder` and `gatsby-tester`.
|
|
15
|
+
|
|
16
|
+
## Where everything is
|
|
17
|
+
|
|
18
|
+
| What | Where |
|
|
19
|
+
| --- | --- |
|
|
20
|
+
| The site | `~/workspace/<folder>/<site>`, at `https://<site>.ddev.site` (`<folder>` is a sites folder: `dev`, `test`, `sandboxes`, `demos`) |
|
|
21
|
+
| The source of the site | `<site>/site/` (its own `package.json`, `gatsby-config.js`, `src/`) |
|
|
22
|
+
| What the address serves | The production build, `<site>/site/public` |
|
|
23
|
+
| The suite's configuration | `<site>/cucumber.js`: the step definitions it loads. There is no users registry: the site has no accounts |
|
|
24
|
+
| The features | `<site>/tests/features/*.feature` (`site.feature` is the first one the setup wrote) |
|
|
25
|
+
| The pack's steps | `<site>/node_modules/@webship-js/gatsby-steps/tests/step-definitions/*.steps.js` |
|
|
26
|
+
| webship-js's steps | `<site>/node_modules/webship-js/tests/step-definitions/*.js` |
|
|
27
|
+
| The reports | `<site>/tests/reports/` |
|
|
28
|
+
|
|
29
|
+
## The order of work
|
|
30
|
+
|
|
31
|
+
1. **Make sure the testing stack is there.** From the sites folder:
|
|
32
|
+
```bash
|
|
33
|
+
cd ~/workspace/<folder>
|
|
34
|
+
bash cmd-tools-testing.sh <site>
|
|
35
|
+
```
|
|
36
|
+
It adds webship-js, the step pack and `tests/features/site.feature`. It is safe to run again:
|
|
37
|
+
it adds what is missing and keeps what was changed.
|
|
38
|
+
2. **Make sure the build is the one you mean to test.** The suite tests the build, not the
|
|
39
|
+
source:
|
|
40
|
+
```bash
|
|
41
|
+
bash cmd-tools-gatsby-cli.sh <site> # the version, the build and when it was made, the server
|
|
42
|
+
bash cmd-tools-gatsby-cli.sh <site> --build # after a change to the source
|
|
43
|
+
```
|
|
44
|
+
3. **Read the installed steps before writing a phrase.** They are the source of truth: the pack
|
|
45
|
+
moves, and a phrase from memory is a guess.
|
|
46
|
+
```bash
|
|
47
|
+
cd ~/workspace/<folder>/<site>
|
|
48
|
+
grep -hE "^(Given|When|Then)\(" node_modules/@webship-js/gatsby-steps/tests/step-definitions/*.steps.js
|
|
49
|
+
```
|
|
50
|
+
Every step carries a comment block with five examples above it; open the file when a phrase
|
|
51
|
+
is not obvious.
|
|
52
|
+
4. **Look at the page first** (the Playwright MCP browser, a tab of your own): the titles, the
|
|
53
|
+
link texts and the addresses are the site's own.
|
|
54
|
+
5. **Write the feature** in `<site>/tests/features/`, from phrases that exist (the lists below).
|
|
55
|
+
6. **Match every step without a browser**, then run the feature, then the suite:
|
|
56
|
+
```bash
|
|
57
|
+
cd ~/workspace/<folder>
|
|
58
|
+
bash cmd-tools-testing.sh <site> --dry-run --path tests/features/<name>.feature
|
|
59
|
+
bash cmd-tools-testing.sh <site> --run --path tests/features/<name>.feature
|
|
60
|
+
bash cmd-tools-testing.sh <site> --run --tags "@critical"
|
|
61
|
+
bash cmd-tools-testing.sh <site> --run
|
|
62
|
+
```
|
|
63
|
+
A dry run says `Undefined` for a phrase no definition matches: fix the phrase, do not write a
|
|
64
|
+
step for it.
|
|
65
|
+
|
|
66
|
+
## No accounts
|
|
67
|
+
|
|
68
|
+
An Gatsby site is static: nobody logs in, and a scenario starts as a visitor
|
|
69
|
+
(`Given I am an anonymous user`, or straight at a page).
|
|
70
|
+
|
|
71
|
+
## The phrases, by area
|
|
72
|
+
|
|
73
|
+
Each line is a phrase the pack defines, and each one passed on a site built with
|
|
74
|
+
`bash cmd-gatsby-project.sh <site> --install` (the default starter; the titles and the addresses
|
|
75
|
+
in quotes are that starter's). Most `should` steps also take the negative.
|
|
76
|
+
|
|
77
|
+
### The build and hydration
|
|
78
|
+
|
|
79
|
+
```gherkin
|
|
80
|
+
Given I am on the homepage
|
|
81
|
+
Then the site should be a production build
|
|
82
|
+
Then the page should be from the current build
|
|
83
|
+
Then I should see a hydrated page
|
|
84
|
+
Then there should be no hydration errors
|
|
85
|
+
Then the page title should be "Home | Gatsby Default Starter"
|
|
86
|
+
Then the page head should be set by the Head API
|
|
87
|
+
Then I should see "Welcome to" without JavaScript
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### Page data and the 404 page
|
|
91
|
+
|
|
92
|
+
```gherkin
|
|
93
|
+
Then the page-data for "/" should be available
|
|
94
|
+
Then the page-data for "/no-such-page/" should not be available
|
|
95
|
+
Then the 404 page should be available
|
|
96
|
+
Then I should not be on a 404 page
|
|
97
|
+
When I go to "/this-page-does-not-exist/"
|
|
98
|
+
Then I should be on a 404 page
|
|
99
|
+
Then I should be on the default 404 page
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Client-side routing
|
|
103
|
+
|
|
104
|
+
```gherkin
|
|
105
|
+
When I click the link "Page 2" without a full page reload
|
|
106
|
+
Then the page should have a route announcer
|
|
107
|
+
Then the route announcer should announce "Hi from the second page"
|
|
108
|
+
When I go back without a full page reload
|
|
109
|
+
Then the page "/page-2/" should be prefetched
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### Images and the manifest
|
|
113
|
+
|
|
114
|
+
```gherkin
|
|
115
|
+
Then I should see an optimized image
|
|
116
|
+
Then the optimized image should be loaded
|
|
117
|
+
Then the optimized image should offer the "webp" format
|
|
118
|
+
Then the optimized image should have a placeholder
|
|
119
|
+
Then the manifest should be valid
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`I am an anonymous user`, `I am on the homepage`, `I go to "/page-2/"`, `I should see "<text>"`
|
|
123
|
+
and `the response status code should be 200` are webship-js's own steps; its status codes, links,
|
|
124
|
+
landmarks and accessibility audits are used as they are and never redefined for this platform.
|
|
125
|
+
|
|
126
|
+
## Traps found on a real site
|
|
127
|
+
|
|
128
|
+
- **The route announcer step adds the first words itself.** The announcer of the site says
|
|
129
|
+
`Navigated to Hi from the second page`; the step is written with what follows `Navigated to`,
|
|
130
|
+
and that is the first heading of the page, not its title:
|
|
131
|
+
`Then the route announcer should announce "Hi from the second page"`. Written with the whole
|
|
132
|
+
sentence, or with the title `Page two`, it fails.
|
|
133
|
+
- **The 404 page of the default starter is the default 404 page.** `Then I should not be on the
|
|
134
|
+
default 404 page` fails until the site has a 404 page of its own; `Then I should be on a 404
|
|
135
|
+
page` is the step for both.
|
|
136
|
+
- **A title is the page's and the site's**: `Home | Gatsby Default Starter`,
|
|
137
|
+
`Page two | Gatsby Default Starter`. The step compares the whole title.
|
|
138
|
+
- **`Then the scroll position should be restored` was not proven on the default starter.** After
|
|
139
|
+
`When I scroll down 300`, a click on the link `Page 2` and a step back, the step said the page
|
|
140
|
+
was not scrolled when the link was clicked. Run it on a page whose link is further down before
|
|
141
|
+
relying on it.
|
|
142
|
+
- **A stale build passes or fails for the wrong reason.** After a change to `site/src`, nothing
|
|
143
|
+
changes at the address until `bash cmd-tools-gatsby-cli.sh <site> --build`.
|
|
144
|
+
- **The front page links to other sites.** The suite depends on this site only: assert the links
|
|
145
|
+
of the site (`Page 2`), and follow none that leaves it.
|
|
146
|
+
|
|
147
|
+
## Rules
|
|
148
|
+
|
|
149
|
+
- **No platform name in a step phrase.** A step says what a person does or sees: `the site should
|
|
150
|
+
be a production build`, `I should see a hydrated page`. The pack also has steps that name the
|
|
151
|
+
generator of the page; a feature of this workspace leaves them out, and a custom step never
|
|
152
|
+
names the product.
|
|
153
|
+
- **No account, no password, no secret in a feature file.** The site has no accounts, and a
|
|
154
|
+
service it talks to is tested with its own pack on its own project.
|
|
155
|
+
- **No selector when a step says it**: `I should see an optimized image`, not a selector of the
|
|
156
|
+
image.
|
|
157
|
+
- **The suite depends on this site only**, and changes nothing: a scenario reads the build, never
|
|
158
|
+
writes into `site/`, and never builds.
|
|
159
|
+
- **A custom step is the last resort**: look in the pack and in webship-js first, write it in
|
|
160
|
+
`<site>/tests/step-definitions/` with a comment block and examples, and say it may belong in
|
|
161
|
+
the pack.
|
|
162
|
+
- **Everything runs in the container**, through `cmd-tools-testing.sh`. Never `npx cucumber-js`
|
|
163
|
+
or `npx playwright` on the host.
|
|
164
|
+
- **A failing scenario is a result.** No `@wip`, no longer timeout, no looser assertion to turn a
|
|
165
|
+
run green: say what the site did.
|
|
166
|
+
|
|
167
|
+
## Examples that run
|
|
168
|
+
|
|
169
|
+
`examples/` holds three features that pass on a site built with
|
|
170
|
+
`bash cmd-gatsby-project.sh <site> --install`. Copy one into the suite and run it:
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
cp ~/workspace/ai-skills/gatsby-scenarios/examples/built-pages.feature ~/workspace/<folder>/<site>/tests/features/
|
|
174
|
+
cd ~/workspace/<folder>
|
|
175
|
+
bash cmd-tools-testing.sh <site> --run --path tests/features/built-pages.feature
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
| Feature | What it shows |
|
|
179
|
+
| --- | --- |
|
|
180
|
+
| `examples/built-pages.feature` | The front page as a hydrated page of the current build, the page data the build wrote, an address with no page |
|
|
181
|
+
| `examples/routing.feature` | A link that changes the page without a full page reload, the route announcer, a prefetched page |
|
|
182
|
+
| `examples/images-and-manifest.feature` | The optimized image of the front page, the web app manifest, the text of the page without scripts |
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
Feature: The pages of the production build
|
|
2
|
+
As the owner of the site
|
|
3
|
+
I want every page to be served from the production build, rendered and hydrated
|
|
4
|
+
So that a build that came out broken is caught by the suite
|
|
5
|
+
|
|
6
|
+
# The titles and the addresses are the ones of the starter the builder uses by default:
|
|
7
|
+
# change them to the pages of the site.
|
|
8
|
+
|
|
9
|
+
Scenario: The front page is a hydrated page of the current build
|
|
10
|
+
Given I am an anonymous user
|
|
11
|
+
And I am on the homepage
|
|
12
|
+
Then the response status code should be 200
|
|
13
|
+
And the site should be a production build
|
|
14
|
+
And the page should be from the current build
|
|
15
|
+
And I should see a hydrated page
|
|
16
|
+
And there should be no hydration errors
|
|
17
|
+
And the page title should be "Home | Gatsby Default Starter"
|
|
18
|
+
And the page head should be set by the Head API
|
|
19
|
+
|
|
20
|
+
Scenario: The build wrote the data of each page
|
|
21
|
+
Given I am on the homepage
|
|
22
|
+
Then the page-data for "/" should be available
|
|
23
|
+
And the page-data for "/page-2/" should be available
|
|
24
|
+
And the page-data for "/no-such-page/" should not be available
|
|
25
|
+
|
|
26
|
+
Scenario: An address with no page answers 404 with the 404 page of the site
|
|
27
|
+
Given I am on the homepage
|
|
28
|
+
Then the 404 page should be available
|
|
29
|
+
And I should not be on a 404 page
|
|
30
|
+
When I go to "/this-page-does-not-exist/"
|
|
31
|
+
Then I should be on a 404 page
|
|
32
|
+
And the response status code should be 404
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
Feature: The images, the manifest and the page without scripts
|
|
2
|
+
As the owner of the site
|
|
3
|
+
I want the images to be optimized, the manifest to be valid and the text to be in the page itself
|
|
4
|
+
So that the site loads well and reads without scripts
|
|
5
|
+
|
|
6
|
+
Scenario: The front page shows an optimized image
|
|
7
|
+
Given I am on the homepage
|
|
8
|
+
Then I should see an optimized image
|
|
9
|
+
And the optimized image should be loaded
|
|
10
|
+
And the optimized image should offer the "webp" format
|
|
11
|
+
And the optimized image should have a placeholder
|
|
12
|
+
|
|
13
|
+
Scenario: The site has a valid web app manifest
|
|
14
|
+
Given I am on the homepage
|
|
15
|
+
Then the manifest should be valid
|
|
16
|
+
|
|
17
|
+
Scenario: The text of the front page is in the page before any script runs
|
|
18
|
+
Given I am on the homepage
|
|
19
|
+
Then I should see "Welcome to" without JavaScript
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
Feature: A visitor moves between the pages without a full page reload
|
|
2
|
+
As the owner of the site
|
|
3
|
+
I want the links of the site to change the page on the client, and to say so to a screen reader
|
|
4
|
+
So that a link that started to reload the whole page is caught by the suite
|
|
5
|
+
|
|
6
|
+
Scenario: A link changes the page on the client and the page is announced
|
|
7
|
+
Given I am on the homepage
|
|
8
|
+
When I click the link "Page 2" without a full page reload
|
|
9
|
+
Then the page title should be "Page two | Gatsby Default Starter"
|
|
10
|
+
And the page should have a route announcer
|
|
11
|
+
And the route announcer should announce "Hi from the second page"
|
|
12
|
+
When I go back without a full page reload
|
|
13
|
+
Then the page title should be "Home | Gatsby Default Starter"
|
|
14
|
+
|
|
15
|
+
Scenario: The front page prefetches the page its link leads to
|
|
16
|
+
Given I am on the homepage
|
|
17
|
+
Then the page "/page-2/" should be prefetched
|
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
|
* Gatsby CLI tool in the sites folders, their functions and argparse under
|
|
6
|
-
* core/scripts/plugins/gatsby/,
|
|
6
|
+
* core/scripts/plugins/gatsby/, 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 = "gatsby";
|
|
|
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 Gatsby 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
|
* Gatsby CLI tool in the sites folders, their functions and argparse under
|
|
7
|
-
* core/scripts/plugins/gatsby/,
|
|
7
|
+
* core/scripts/plugins/gatsby/, 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 = 'gatsby';
|
|
|
22
22
|
exports.COMMANDS = ['cmd-gatsby-project.sh', 'cmd-tools-gatsby-cli.sh'];
|
|
23
23
|
/** The agents the installer places in the AI Agents folder. */
|
|
24
24
|
exports.AGENTS = ['gatsby-site-builder', 'gatsby-tester'];
|
|
25
|
+
/** The skill the installer places in the AI Skills folder (a folder each, with its SKILL.md). */
|
|
26
|
+
exports.SKILLS = ['gatsby-scenarios'];
|
|
27
|
+
/** The slash command the installer places in the AI Commands folder. */
|
|
28
|
+
exports.AI_COMMANDS = ['gatsby-test'];
|
|
29
|
+
/** The prompt the installer places in the AI Prompts folder: a whole launch command for a new session. */
|
|
30
|
+
exports.PROMPTS = ['gatsby-build-and-test'];
|
|
25
31
|
/** What the assistant is told about Gatsby in this workspace. */
|
|
26
32
|
function assistantContext() {
|
|
27
33
|
return [
|
|
@@ -33,6 +39,8 @@ function assistantContext() {
|
|
|
33
39
|
'`--build` builds and serves it again after a change, `--update` updates its packages, `--restart` starts its server again.',
|
|
34
40
|
'`bash cmd-tools-testing.sh <name>` sets up webship-js with the Gatsby step pack; `--run` runs the suite against the build.',
|
|
35
41
|
`For Gatsby work, hand over to the agents ${exports.AGENTS.map((a) => `\`${a}\``).join(' and ')}.`,
|
|
42
|
+
`The plugin also places the skill ${exports.SKILLS.map((a) => `\`${a}\``).join(', ')} (the step pack's phrases, by area) in ai-skills/,`,
|
|
43
|
+
`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/.`,
|
|
36
44
|
'Never run gatsby, node or npm on the host for a project.',
|
|
37
45
|
].join(' ');
|
|
38
46
|
}
|
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,QAAQ,CAAC;AAEjC,+DAA+D;AAClD,QAAA,QAAQ,GAAG,CAAC,uBAAuB,EAAE,yBAAyB,CAAC,CAAC;AAE7E,+DAA+D;AAClD,QAAA,MAAM,GAAG,CAAC,qBAAqB,EAAE,eAAe,CAAC,CAAC;AAE/D,iGAAiG;AACpF,QAAA,MAAM,GAAG,CAAC,kBAAkB,CAAC,CAAC;AAE3C,wEAAwE;AAC3D,QAAA,WAAW,GAAG,CAAC,aAAa,CAAC,CAAC;AAE3C,0GAA0G;AAC7F,QAAA,OAAO,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAEjD,iEAAiE;AACjE,SAAgB,gBAAgB;IAC9B,OAAO;QACL,4FAA4F;QAC5F,kGAAkG;QAClG,sHAAsH;QACtH,uGAAuG;QACvG,oHAAoH;QACpH,4HAA4H;QAC5H,4HAA4H;QAC5H,4CAA4C,cAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG;QAC1F,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,0DAA0D;KAC3D,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/gatsby.feature
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
Feature: The Gatsby plugin on the dashboard
|
|
2
|
-
Once the plugin is activated and installed, the sites folders offer the Gatsby builder,
|
|
3
|
-
AI
|
|
2
|
+
Once the plugin is activated and installed, the sites folders offer the Gatsby 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 Gatsby plugin on the dashboard
|
|
|
15
16
|
Given I am on "/ai-agents"
|
|
16
17
|
Then I should see "gatsby-site-builder"
|
|
17
18
|
And I should see "gatsby-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 "gatsby-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 "gatsby-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 "gatsby-build-and-test"
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@webship.co/workspace-gatsby",
|
|
3
|
-
"version": "1.0.
|
|
4
|
-
"description": "Gatsby for Webship Workspace: the builder (`cmd-gatsby-project.sh`) and the Gatsby CLI tool in every sites folder, a starter built to a production build and served in a container, the Gatsby step pack wired into the testing setup, and
|
|
3
|
+
"version": "1.0.8",
|
|
4
|
+
"description": "Gatsby for Webship Workspace: the builder (`cmd-gatsby-project.sh`) and the Gatsby CLI tool in every sites folder, a starter built to a production build and served in a container, the Gatsby 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": "gatsby",
|
|
29
30
|
"label": "Gatsby",
|
|
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"
|
|
@@ -56,8 +69,17 @@
|
|
|
56
69
|
},
|
|
57
70
|
"ai": {
|
|
58
71
|
"agents": [
|
|
59
|
-
"agents/gatsby-site-builder.md",
|
|
60
|
-
"agents/gatsby-tester.md"
|
|
72
|
+
"ai/agents/gatsby-site-builder.md",
|
|
73
|
+
"ai/agents/gatsby-tester.md"
|
|
74
|
+
],
|
|
75
|
+
"skills": [
|
|
76
|
+
"ai/skills/gatsby-scenarios"
|
|
77
|
+
],
|
|
78
|
+
"commands": [
|
|
79
|
+
"ai/commands/gatsby-test.md"
|
|
80
|
+
],
|
|
81
|
+
"prompts": [
|
|
82
|
+
"ai/prompts/gatsby-build-and-test.md"
|
|
61
83
|
]
|
|
62
84
|
},
|
|
63
85
|
"features": [
|