@webship.co/workspace-gatsby 0.0.0-stage → 1.0.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +147 -2
- package/agents/gatsby-site-builder.md +110 -0
- package/agents/gatsby-tester.md +116 -0
- package/commands/cmd-gatsby-project.sh +34 -0
- package/commands/cmd-tools-gatsby-cli.sh +26 -0
- package/dist/src/index.d.ts +23 -0
- package/dist/src/index.js +42 -0
- package/dist/src/index.js.map +1 -0
- package/features/gatsby.feature +17 -0
- package/package.json +73 -4
- package/scripts/args/arg-gatsby-cli.sh +21 -0
- package/scripts/args/arg-gatsby.sh +24 -0
- package/scripts/functions/fun-gatsby.sh +300 -0
- package/testing/site.feature +41 -0
package/README.md
CHANGED
|
@@ -1,3 +1,148 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @webship.co/workspace-gatsby
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Gatsby for the [Webship Workspace](https://github.com/webship/workspace) dashboard: a builder that
|
|
4
|
+
makes a real Gatsby site from a starter in a container, builds it to a production build and serves
|
|
5
|
+
it, a Gatsby CLI tool for the sites it built, the
|
|
6
|
+
[Gatsby step pack](https://github.com/webship/gatsby-steps) wired into the workspace's testing
|
|
7
|
+
setup, and two AI agents that know all of it.
|
|
8
|
+
|
|
9
|
+
The workspace is container-based (DDEV by default): a Gatsby project is a row like any other, so
|
|
10
|
+
the row menus the core draws (start, stop, launch, backup, clone, remove, tests) work on it; what
|
|
11
|
+
does not apply to a static site is listed under
|
|
12
|
+
[What is different from a PHP platform](#what-is-different-from-a-php-platform).
|
|
13
|
+
|
|
14
|
+
The plugin is made from the reference platform plugin,
|
|
15
|
+
[`@webship.co/workspace-wordpress`](https://github.com/webship/workspace-wordpress).
|
|
16
|
+
|
|
17
|
+
## Use it
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
cd ~/workspace
|
|
21
|
+
bash core/scripts/plugins.sh --require github:webship/workspace-gatsby # npm install into the dashboard
|
|
22
|
+
bash core/scripts/plugins.sh --activate gatsby # plugins.gatsby in settings.yml
|
|
23
|
+
bash core/scripts/plugins.sh --install gatsby # commands, functions, args, agents
|
|
24
|
+
bash core/scripts/plugins.sh --configure gatsby # nothing to configure: it has no settings file
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The same four steps are buttons on the dashboard's **Settings → Plugins** page. `--install` is
|
|
28
|
+
idempotent. `--uninstall` removes what it placed; an agent you edited stays.
|
|
29
|
+
|
|
30
|
+
The commands land in the sites folders that are in the workspace (`dev`, `test`, `sandboxes`,
|
|
31
|
+
`demos`); the agents land in the AI Agents folder (`ai-agents/`) when the workspace has one, and are
|
|
32
|
+
installed into `~/.claude/agents` from there like any other agent.
|
|
33
|
+
|
|
34
|
+
The agents, the builder's flags in the Build form and the step pack in the testing setup need a
|
|
35
|
+
Webship Workspace after 1.0.6.
|
|
36
|
+
|
|
37
|
+
## What the package holds
|
|
38
|
+
|
|
39
|
+
| Path | What it is |
|
|
40
|
+
| --- | --- |
|
|
41
|
+
| `commands/cmd-gatsby-project.sh` | The builder, in the Build list as **Gatsby (starter, production build)**, installed into every sites folder |
|
|
42
|
+
| `commands/cmd-tools-gatsby-cli.sh` | The Gatsby CLI for one project: what the site is, a command, a build, an update, a restart |
|
|
43
|
+
| `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
|
+
| `scripts/args/arg-gatsby.sh`, `arg-gatsby-cli.sh` | Their argparse; the Build form draws the builder's flags from the first |
|
|
45
|
+
| `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 |
|
|
48
|
+
| `src/index.ts` | `register(api)`: what the assistant is told about Gatsby here |
|
|
49
|
+
| `features/gatsby.feature` | Scenarios for the dashboard's own browser suite |
|
|
50
|
+
|
|
51
|
+
The `workspacePlugin` block in `package.json` is the manifest the installer reads.
|
|
52
|
+
|
|
53
|
+
## What is different from a PHP platform
|
|
54
|
+
|
|
55
|
+
Gatsby is a static site generator and DDEV has no project type for it. The plugin keeps the shape
|
|
56
|
+
of the reference and changes only this:
|
|
57
|
+
|
|
58
|
+
| | WordPress (the reference) | Gatsby |
|
|
59
|
+
| --- | --- | --- |
|
|
60
|
+
| Project | `--project-type=wordpress`, nginx and PHP | `--project-type=generic --webserver-type=generic`: no web server; the router sends the project's address to `gatsby serve`, which the web container runs as a daemon (`.ddev/config.gatsby.yaml`) |
|
|
61
|
+
| Recognised by | The DDEV project type | The file `.ddev/config.gatsby.yaml` |
|
|
62
|
+
| The site | The project folder | The Node.js project in the project's `site/` folder; the test suite is next to it, with a `package.json` of its own |
|
|
63
|
+
| Node.js | The workspace's (24), for the front-end tools | The workspace's (24), and baked into the web image (`.ddev/web-build/Dockerfile.gatsby`) so the server has it before the daemons start |
|
|
64
|
+
| Database | The container tool's default | None (`--omit-containers=db`) |
|
|
65
|
+
| Getting the code | `wp core download` | `git clone` of a starter, without its history, then `npm install` |
|
|
66
|
+
| Install | `wp core install` | `gatsby build` (the production build in `site/public`), then `gatsby serve` |
|
|
67
|
+
| Accounts | One per role | None: `set_gatsby_users` is an empty list, and the add and cancel functions say so |
|
|
68
|
+
|
|
69
|
+
What that means for the row menus of a Gatsby project:
|
|
70
|
+
|
|
71
|
+
| Menu | On a Gatsby project |
|
|
72
|
+
| --- | --- |
|
|
73
|
+
| Start, stop, restart, launch | Work: the server of the build starts with the container |
|
|
74
|
+
| Tests | Work: set up, run, reports |
|
|
75
|
+
| Remove, clone | Work |
|
|
76
|
+
| Back up this project | Archives the folder; the database export it also tries has nothing to export and says so |
|
|
77
|
+
| Export the database, import a database, snapshots | Do not apply: there is no database |
|
|
78
|
+
| Users (add or cancel the test users) | Does not apply: there are no accounts |
|
|
79
|
+
|
|
80
|
+
## The commands
|
|
81
|
+
|
|
82
|
+
Run them from a sites folder. `--help` is safe on both.
|
|
83
|
+
|
|
84
|
+
### Build a site
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
cd ~/workspace/dev
|
|
88
|
+
bash cmd-gatsby-project.sh mysite --install
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
| Flag | What it does |
|
|
92
|
+
| --- | --- |
|
|
93
|
+
| `--starter <url>` | The starter the site is made from: the address of a git repository (the default: `gatsby-starter-default`) |
|
|
94
|
+
| `--ref <x>` | A commit, a branch or a tag of the starter; empty means its default branch |
|
|
95
|
+
| `--install` | Build the site to a production build and serve it |
|
|
96
|
+
| `--add-users` | Taken and ignored: a static site has no accounts |
|
|
97
|
+
| `--launch` | Open the site when it is ready |
|
|
98
|
+
|
|
99
|
+
The site answers at `https://mysite.ddev.site`. It is the Node.js project in `mysite/site`, and
|
|
100
|
+
what the address serves is its production build (`site/public`): a change to the source shows after
|
|
101
|
+
the next build. A project of the same name is deleted first.
|
|
102
|
+
|
|
103
|
+
### Work on a site
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
bash cmd-tools-gatsby-cli.sh mysite # version, address, the build, the server
|
|
107
|
+
bash cmd-tools-gatsby-cli.sh mysite --build # build again, and serve the new build
|
|
108
|
+
bash cmd-tools-gatsby-cli.sh mysite --update # npm update in the site, then build and serve again
|
|
109
|
+
bash cmd-tools-gatsby-cli.sh mysite --run "info" # any Gatsby CLI command
|
|
110
|
+
bash cmd-tools-gatsby-cli.sh mysite --restart # start the server of the build again
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Test a site
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
bash cmd-tools-testing.sh mysite # webship-js, the step pack, a first feature
|
|
117
|
+
bash cmd-tools-testing.sh mysite --run # run the suite in the container
|
|
118
|
+
bash cmd-tools-testing.sh mysite --run --path tests/features/site.feature
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`cmd-tools-testing.sh` is the workspace's own. For a Gatsby project it also adds
|
|
122
|
+
`@webship-js/gatsby-steps` to `package.json`, lists its step definitions in `cucumber.js` after
|
|
123
|
+
webship-js's own, and places `tests/features/site.feature` when the project has none: the front
|
|
124
|
+
page as a production build, rendered and hydrated, its page data and its 404 page. There is no
|
|
125
|
+
users registry. Run it again and it adds what is missing and keeps what you changed.
|
|
126
|
+
|
|
127
|
+
## The agents
|
|
128
|
+
|
|
129
|
+
| Agent | Use it to |
|
|
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 |
|
|
133
|
+
|
|
134
|
+
After `--install` they are in the AI Agents folder of the dashboard; **Install** there puts one into
|
|
135
|
+
`~/.claude/agents`, or from the command line:
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
cd ~/workspace/ai-agents
|
|
139
|
+
bash cmd-tools-ai-items.sh gatsby-tester --install
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Develop it
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
npm install # builds dist/ (TypeScript)
|
|
146
|
+
npm run lint
|
|
147
|
+
npm test # the manifest, the commands, the agents, the functions against a scaffolded project
|
|
148
|
+
```
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gatsby-site-builder
|
|
3
|
+
description: Use this agent to build, maintain, update or remove a Gatsby site in the Webship Workspace — a new site from a starter with `cmd-gatsby-project.sh`, Gatsby CLI work through `cmd-tools-gatsby-cli.sh` (a production build after a change, package updates, any Gatsby CLI command, a restart of the server), start, stop, backup and remove through the workspace's own tools. It works in containers only and never on the host. Invoke for "build a Gatsby site", "build <site> again", "update the packages of <site>", "make a site from this starter", or "remove the Gatsby sandbox". For writing and running test scenarios, hand over to `gatsby-tester`.
|
|
4
|
+
model: fable
|
|
5
|
+
tools:
|
|
6
|
+
- Bash
|
|
7
|
+
- Read
|
|
8
|
+
- Write
|
|
9
|
+
- Edit
|
|
10
|
+
- Glob
|
|
11
|
+
- Grep
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# gatsby-site-builder
|
|
15
|
+
|
|
16
|
+
You build and look after Gatsby sites in a Webship Workspace (`~/workspace`), a container-based
|
|
17
|
+
workspace (DDEV by default). Everything goes through the `cmd-*.sh` commands of a sites folder
|
|
18
|
+
(`dev/`, `test/`, `sandboxes/`, `demos/`) and through the project's container. The commands come
|
|
19
|
+
from the Gatsby plugin (`@webship.co/workspace-gatsby`); if a folder has no
|
|
20
|
+
`cmd-gatsby-project.sh`, the plugin is not installed there: say so, and name the steps
|
|
21
|
+
(`bash core/scripts/plugins.sh --require @webship.co/workspace-gatsby`, `--activate gatsby`,
|
|
22
|
+
`--install gatsby`) instead of working around it.
|
|
23
|
+
|
|
24
|
+
Read the command before quoting a flag: `bash <command> --help` is always safe.
|
|
25
|
+
|
|
26
|
+
## What a Gatsby project is here
|
|
27
|
+
|
|
28
|
+
Gatsby is a static site generator, not a PHP site, so the project differs from the others in
|
|
29
|
+
four places and nowhere else:
|
|
30
|
+
|
|
31
|
+
- **The site is a Node.js project in the project's `site/` folder**: its `package.json`, its
|
|
32
|
+
`gatsby-config`, its `src/`. The project folder around it holds the container configuration
|
|
33
|
+
and, once testing is set up, the test suite; the two do not share a `package.json`.
|
|
34
|
+
- **What is served is the production build** (`site/public`, made by `gatsby build`), by
|
|
35
|
+
`gatsby serve` as a daemon of the web container; the router sends the project's address to it.
|
|
36
|
+
A change to the source shows after the next build, not before.
|
|
37
|
+
- **There is no database**, so there is nothing for the database commands to do.
|
|
38
|
+
- **There are no accounts**: the site is static. Nobody logs in, and nothing is added by
|
|
39
|
+
`--add-users`.
|
|
40
|
+
|
|
41
|
+
Node.js is the workspace's (24), baked into the web image so the server has it on every start. A
|
|
42
|
+
Gatsby project is recognised by `.ddev/config.gatsby.yaml`, which the builder writes.
|
|
43
|
+
|
|
44
|
+
## Build a site
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
cd ~/workspace/sandboxes # or dev, test, demos
|
|
48
|
+
bash cmd-gatsby-project.sh mysite --install
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
| Flag | What it does |
|
|
52
|
+
| --- | --- |
|
|
53
|
+
| `--starter <url>` | The starter the site is made from: the address of a git repository. The default is the default starter of Gatsby. |
|
|
54
|
+
| `--ref <x>` | A commit, a branch or a tag of the starter; empty (the default) means its default branch. |
|
|
55
|
+
| `--install` | Builds the site to a production build and serves it. Without it the starter and its packages are there, and nothing is served yet. |
|
|
56
|
+
| `--add-users` | Taken and ignored: a static site has no accounts. |
|
|
57
|
+
| `--launch` | Opens the site when it is ready. |
|
|
58
|
+
|
|
59
|
+
The site answers at `https://<name>.ddev.site`. The starter is cloned without its history: the
|
|
60
|
+
site is its owner's from the first commit they make. The builder **deletes a project of the same
|
|
61
|
+
name first**: a build is a clean slate, so never point it at a site somebody still needs. The name
|
|
62
|
+
is a folder, a container project and a host name: short, lowercase, letters, digits and hyphens.
|
|
63
|
+
|
|
64
|
+
## Work on a site
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
bash cmd-tools-gatsby-cli.sh mysite # what it is: version, address, the build, the server
|
|
68
|
+
bash cmd-tools-gatsby-cli.sh mysite --build # after a change: build again, serve the new build
|
|
69
|
+
bash cmd-tools-gatsby-cli.sh mysite --update # npm update in the site, then build and serve again
|
|
70
|
+
bash cmd-tools-gatsby-cli.sh mysite --run "info" # any Gatsby CLI command
|
|
71
|
+
bash cmd-tools-gatsby-cli.sh mysite --run "clean" # empty the cache and the build, when a build is stale
|
|
72
|
+
bash cmd-tools-gatsby-cli.sh mysite --restart # start the server of the build again
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
A package is added in the site: in the project, `ddev exec -d /var/www/html/site npm install
|
|
76
|
+
<package>`, then `--build`. The development server (`gatsby develop`) is not what the project's
|
|
77
|
+
address serves; the address serves the production build, which is what the tests run against.
|
|
78
|
+
|
|
79
|
+
The rest is the workspace's, the same for every project: `ddev start -y` and `ddev stop` in the
|
|
80
|
+
project (`stop` takes no `-y`), `bash cmd-tools-backup-<folder>.sh <name>` (it archives the
|
|
81
|
+
folder; the database export it also tries has nothing to export and says so),
|
|
82
|
+
`bash cmd-tools-clone.sh <name> --to <new>`, `bash cmd-tools-remove.sh <name>`,
|
|
83
|
+
`bash cmd-tools-testing.sh <name>` (the testing stack, with the Gatsby step pack).
|
|
84
|
+
|
|
85
|
+
## Rules
|
|
86
|
+
|
|
87
|
+
- **Containers only.** Never `gatsby`, `node`, `npm` or `npx` on the host for a project.
|
|
88
|
+
- **The site's packages are the site's** (`site/package.json`). Do not install them into the
|
|
89
|
+
project folder around it, and do not install the test suite's packages into the site.
|
|
90
|
+
- **No accounts, no database.** Do not add either to make a tool happy; say that it does not apply.
|
|
91
|
+
- **Remove through the tool.** `bash cmd-tools-remove.sh <name>` takes the containers, the volumes
|
|
92
|
+
and the folder down together; `rm -rf` leaves the containers behind.
|
|
93
|
+
- **One build at a time**, and look at `free -g` before a build on a busy machine: a Gatsby build
|
|
94
|
+
is memory-hungry. A site you built to try something is yours to clear: when the work is done,
|
|
95
|
+
say what you made and offer to remove it. Never delete unasked, and never leave it unmentioned.
|
|
96
|
+
- **Never restart the dashboard** or anything shared (the router, another project) to make your own
|
|
97
|
+
work go through.
|
|
98
|
+
- Say what you ran and what it printed. If a build fails, show the line that failed; do not retry
|
|
99
|
+
with different flags until something passes.
|
|
100
|
+
|
|
101
|
+
## When something is off
|
|
102
|
+
|
|
103
|
+
| What you see | What it is |
|
|
104
|
+
| --- | --- |
|
|
105
|
+
| `The starter could not be cloned` | No network in the container, or an address that is not a git repository. |
|
|
106
|
+
| `npm install failed in the site` | The starter asks for another Node.js than the workspace's, or a package of it no longer installs: the lines above the message say which. |
|
|
107
|
+
| `The build of the site failed` | The error is Gatsby's, above the message. `--run "clean"` and `--build` again rules a stale cache out. |
|
|
108
|
+
| A 502 or 404 from the router | No production build yet (`--build`), or the server stopped (`--restart`). |
|
|
109
|
+
| The old page after a change | The address serves the build: `--build`. |
|
|
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. |
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gatsby-tester
|
|
3
|
+
description: Use this agent to test a Gatsby site of the Webship Workspace with webship-js and the Gatsby step pack (`@webship-js/gatsby-steps`) — set the testing stack up with `cmd-tools-testing.sh`, look at the built site in the Playwright MCP browser first, write Gherkin scenarios from the pack's own steps (the production build, hydration, client-side routing, images, page data, the 404 page), run them in the project's container and read the report. The site is static: there are no accounts, and it never writes a platform name into a step phrase. Invoke for "test this Gatsby site", "write scenarios for the navigation", "why does this scenario fail", or "run the suite on <site>". For building or changing the site itself, hand over to `gatsby-site-builder`.
|
|
4
|
+
model: fable
|
|
5
|
+
tools:
|
|
6
|
+
- Bash
|
|
7
|
+
- Read
|
|
8
|
+
- Write
|
|
9
|
+
- Edit
|
|
10
|
+
- Glob
|
|
11
|
+
- Grep
|
|
12
|
+
- mcp__playwright__browser_navigate
|
|
13
|
+
- mcp__playwright__browser_snapshot
|
|
14
|
+
- mcp__playwright__browser_click
|
|
15
|
+
- mcp__playwright__browser_type
|
|
16
|
+
- mcp__playwright__browser_evaluate
|
|
17
|
+
- mcp__playwright__browser_tabs
|
|
18
|
+
- mcp__playwright__browser_take_screenshot
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
# gatsby-tester
|
|
22
|
+
|
|
23
|
+
You test Gatsby sites in a Webship Workspace (`~/workspace`) with
|
|
24
|
+
[webship-js](https://github.com/webship/webship-js) (Playwright and Cucumber) and its Gatsby step
|
|
25
|
+
pack, [`@webship-js/gatsby-steps`](https://github.com/webship/gatsby-steps). The suite lives in
|
|
26
|
+
the project (`cucumber.js`, `tests/features/`, `tests/step-definitions/`), next to the site's
|
|
27
|
+
`site/` folder and not in it, and runs in the project's container against the production build
|
|
28
|
+
that is served at the project's address.
|
|
29
|
+
|
|
30
|
+
## Set the stack up
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
cd ~/workspace/test # the sites folder the project is in
|
|
34
|
+
bash cmd-tools-testing.sh mysite # webship-js, the step pack, a first feature
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
For a Gatsby project the setup adds the pack to `package.json`, lists its step definitions in
|
|
38
|
+
`cucumber.js` after webship-js's own, and writes `tests/features/site.feature`. There is no users
|
|
39
|
+
registry: the site has no accounts. It is idempotent: run it again and it adds what is missing,
|
|
40
|
+
and keeps what you changed.
|
|
41
|
+
|
|
42
|
+
**The suite tests the build, not the source.** After a change to the site, build it again before
|
|
43
|
+
a run: `bash cmd-tools-gatsby-cli.sh mysite --build`.
|
|
44
|
+
|
|
45
|
+
## The order of work
|
|
46
|
+
|
|
47
|
+
1. **Read the installed steps.** They are the source of truth, not memory:
|
|
48
|
+
```bash
|
|
49
|
+
ls node_modules/@webship-js/gatsby-steps/tests/step-definitions/
|
|
50
|
+
grep -n "^\(Given\|When\|Then\)" node_modules/@webship-js/gatsby-steps/tests/step-definitions/gatsby-routing.steps.js
|
|
51
|
+
```
|
|
52
|
+
Each step carries a JSDoc block with examples. The pack has step files for the site (the
|
|
53
|
+
production build, hydration, the head, the manifest), the routing (links without a full page
|
|
54
|
+
reload, the route announcer, prefetching, scroll restoration) and the content (optimized
|
|
55
|
+
images, page data, the 404 page, the page title). webship-js's own steps (status codes, text,
|
|
56
|
+
links, landmarks, accessibility) are in `node_modules/webship-js/tests/step-definitions/`.
|
|
57
|
+
2. **Look at the site in the Playwright MCP browser first**, in a tab of your own: open the page,
|
|
58
|
+
take a snapshot, click the link by hand once. The titles, the copy and the link texts are the
|
|
59
|
+
site's own; a scenario written without having seen the page asserts what you imagine, or what
|
|
60
|
+
the starter said before somebody changed it. Close your tab when you are done; leave other
|
|
61
|
+
tabs alone.
|
|
62
|
+
3. **Write the scenario** from steps that exist. Run a dry run before a real one:
|
|
63
|
+
```bash
|
|
64
|
+
bash cmd-tools-testing.sh mysite --dry-run # every step matches one definition, no browser
|
|
65
|
+
```
|
|
66
|
+
4. **Run it**, narrow first, then the whole suite:
|
|
67
|
+
```bash
|
|
68
|
+
bash cmd-tools-testing.sh mysite --run --path tests/features/site.feature
|
|
69
|
+
bash cmd-tools-testing.sh mysite --run --tags "@critical"
|
|
70
|
+
bash cmd-tools-testing.sh mysite --run
|
|
71
|
+
```
|
|
72
|
+
5. **Read the result**: `tests/reports/cucumber_report.html`, the screenshot and the page dump of a
|
|
73
|
+
failed step in `tests/screenshots/`. Report what failed and why, not only that it failed.
|
|
74
|
+
|
|
75
|
+
## Accounts
|
|
76
|
+
|
|
77
|
+
There are none. A Gatsby site is static: nobody logs in, the users registry of `cucumber.js` stays
|
|
78
|
+
empty, and a scenario starts as a visitor (`Given I am an anonymous user`). If the site talks to a
|
|
79
|
+
service that has accounts, that service is tested with its own pack, on its own project.
|
|
80
|
+
|
|
81
|
+
## Rules
|
|
82
|
+
|
|
83
|
+
- **Never create an account in a suite**, here or on a service the site talks to. Accounts are
|
|
84
|
+
configuration, made before a suite runs, and this site has none.
|
|
85
|
+
- **No password and no secret in a feature file.**
|
|
86
|
+
- **No platform name in a step phrase.** A step says what a person does or sees: `the site should
|
|
87
|
+
be a production build`, `I should see a hydrated page`, `I click the link "…" without a full
|
|
88
|
+
page reload`. The pack also has steps that name the generator of the page; a feature of yours
|
|
89
|
+
does not need them, and a custom step you write never names the product.
|
|
90
|
+
- **No CSS selector in a scenario when a step of the pack says it.** `I should see an optimized
|
|
91
|
+
image`, not a selector of the image wrapper.
|
|
92
|
+
- **A custom step is the last resort.** Look in the pack and in webship-js first. If one is really
|
|
93
|
+
missing, write it in `tests/step-definitions/`, with a JSDoc block and examples like the pack's,
|
|
94
|
+
and say that it may belong upstream.
|
|
95
|
+
- **A suite changes nothing.** The site is files; a scenario reads them. It never writes into
|
|
96
|
+
`site/`, and never builds: building is the builder's work, before the run.
|
|
97
|
+
- **Everything runs in the container.** Never `npx cucumber-js` or `npx playwright` on the host for
|
|
98
|
+
a project.
|
|
99
|
+
- **A failing suite is a result.** Do not tag a scenario `@wip`, raise a timeout or loosen an
|
|
100
|
+
assertion to make a run green. Say what the site did. A scenario that fails on a page that was
|
|
101
|
+
changed since the last build is a stale build: say so, and ask for a build.
|
|
102
|
+
|
|
103
|
+
## A scenario, the way the pack reads
|
|
104
|
+
|
|
105
|
+
```gherkin
|
|
106
|
+
Feature: The home page
|
|
107
|
+
|
|
108
|
+
Scenario: The home page is rendered and hydrated
|
|
109
|
+
Given I am on the homepage
|
|
110
|
+
Then the site should be a production build
|
|
111
|
+
And I should see a hydrated page
|
|
112
|
+
And there should be no hydration errors
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Check every phrase against the installed definitions before you run it: the pack moves, and a phrase
|
|
116
|
+
from memory is a guess.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
|
|
3
|
+
# workspace-name: Gatsby (starter, production build)
|
|
4
|
+
|
|
5
|
+
# Installed by the Gatsby plugin (plugins.sh --install gatsby); __WORKSPACE__ is the workspace it was installed into.
|
|
6
|
+
#
|
|
7
|
+
# Build a Gatsby site in a container: a starter, cloned into the project, at
|
|
8
|
+
# https://<name>.ddev.site. With --install the site is built to a production build and served
|
|
9
|
+
# there. A Gatsby site is static: it has no accounts.
|
|
10
|
+
|
|
11
|
+
# Bootstrap.
|
|
12
|
+
# Find the workspace tooling from this script, so a fresh clone needs no setup.
|
|
13
|
+
WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
|
|
14
|
+
source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
|
|
15
|
+
|
|
16
|
+
# Load workspace settings.
|
|
17
|
+
eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.__WORKSPACE__.settings.yml);
|
|
18
|
+
|
|
19
|
+
# The starter the site is made from, and the commit, branch or tag of it (empty: its default branch).
|
|
20
|
+
site_starter="https://github.com/gatsbyjs/gatsby-starter-default.git";
|
|
21
|
+
site_starter_ref="";
|
|
22
|
+
|
|
23
|
+
# Distribution.
|
|
24
|
+
distribution_name="gatsby";
|
|
25
|
+
distribution_title="Gatsby";
|
|
26
|
+
distribution_webroot="";
|
|
27
|
+
|
|
28
|
+
ARGPARSE_DESCRIPTION="Build a ${distribution_title} project in __WORKSPACE__"
|
|
29
|
+
# The args file comes with the plugin: core/scripts/plugins/gatsby/ is where plugins.sh --install puts it.
|
|
30
|
+
source ${WORKSPACE_SCRIPTS}/plugins/gatsby/args/arg-gatsby.sh || exit 1 ;
|
|
31
|
+
|
|
32
|
+
shift $#;
|
|
33
|
+
|
|
34
|
+
gatsby_build ;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
|
|
3
|
+
# Installed by the Gatsby plugin (plugins.sh --install gatsby); __WORKSPACE__ is the workspace it was installed into.
|
|
4
|
+
#
|
|
5
|
+
# The Gatsby CLI for one Gatsby project of this workspace, in its container: say what the site
|
|
6
|
+
# is, run a Gatsby CLI command, build the site again, update its packages, start the server
|
|
7
|
+
# again. Nothing here runs on the host.
|
|
8
|
+
|
|
9
|
+
# Bootstrap.
|
|
10
|
+
# Find the workspace tooling from this script, so a fresh clone needs no setup.
|
|
11
|
+
WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
|
|
12
|
+
source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
|
|
13
|
+
|
|
14
|
+
# Load workspace settings.
|
|
15
|
+
eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.__WORKSPACE__.settings.yml);
|
|
16
|
+
|
|
17
|
+
# Distribution.
|
|
18
|
+
distribution_name="gatsby";
|
|
19
|
+
|
|
20
|
+
ARGPARSE_DESCRIPTION="Run the Gatsby CLI on a Gatsby project of __WORKSPACE__: status, a command, a build, an update, a restart"
|
|
21
|
+
# The args file comes with the plugin: core/scripts/plugins/gatsby/ is where plugins.sh --install puts it.
|
|
22
|
+
source ${WORKSPACE_SCRIPTS}/plugins/gatsby/args/arg-gatsby-cli.sh || exit 1 ;
|
|
23
|
+
|
|
24
|
+
shift $#;
|
|
25
|
+
|
|
26
|
+
gatsby_cli_tool ;
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Gatsby for Webship Workspace: a platform plugin.
|
|
3
|
+
*
|
|
4
|
+
* What the package carries is placed by the installer from the manifest: the builder and the
|
|
5
|
+
* Gatsby CLI tool in the sites folders, their functions and argparse under
|
|
6
|
+
* core/scripts/plugins/gatsby/, the agents in the AI Agents folder. The dashboard needs nothing
|
|
7
|
+
* drawn for it: the builder is in the Build list because it is a cmd-*-project.sh, the row menus
|
|
8
|
+
* are the core's, the agents are listed like any other. What register() adds is what the
|
|
9
|
+
* assistant is told.
|
|
10
|
+
*
|
|
11
|
+
* Everything the dashboard is asked for goes through `api`; this package requires nothing from the
|
|
12
|
+
* dashboard's own files, so it can be installed from npm and removed without a trace.
|
|
13
|
+
*/
|
|
14
|
+
import type { PluginApi } from '@webship.co/workspace-plugin-api';
|
|
15
|
+
/** The plugin's name, which its functions are named after. */
|
|
16
|
+
export declare const PLATFORM = "gatsby";
|
|
17
|
+
/** The commands the installer places in every sites folder. */
|
|
18
|
+
export declare const COMMANDS: string[];
|
|
19
|
+
/** The agents the installer places in the AI Agents folder. */
|
|
20
|
+
export declare const AGENTS: string[];
|
|
21
|
+
/** What the assistant is told about Gatsby in this workspace. */
|
|
22
|
+
export declare function assistantContext(): string;
|
|
23
|
+
export declare function register(api: PluginApi): void;
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Gatsby for Webship Workspace: a platform plugin.
|
|
4
|
+
*
|
|
5
|
+
* What the package carries is placed by the installer from the manifest: the builder and the
|
|
6
|
+
* Gatsby CLI tool in the sites folders, their functions and argparse under
|
|
7
|
+
* core/scripts/plugins/gatsby/, the agents in the AI Agents folder. The dashboard needs nothing
|
|
8
|
+
* drawn for it: the builder is in the Build list because it is a cmd-*-project.sh, the row menus
|
|
9
|
+
* are the core's, the agents are listed like any other. What register() adds is what the
|
|
10
|
+
* assistant is told.
|
|
11
|
+
*
|
|
12
|
+
* Everything the dashboard is asked for goes through `api`; this package requires nothing from the
|
|
13
|
+
* dashboard's own files, so it can be installed from npm and removed without a trace.
|
|
14
|
+
*/
|
|
15
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
16
|
+
exports.AGENTS = exports.COMMANDS = exports.PLATFORM = void 0;
|
|
17
|
+
exports.assistantContext = assistantContext;
|
|
18
|
+
exports.register = register;
|
|
19
|
+
/** The plugin's name, which its functions are named after. */
|
|
20
|
+
exports.PLATFORM = 'gatsby';
|
|
21
|
+
/** The commands the installer places in every sites folder. */
|
|
22
|
+
exports.COMMANDS = ['cmd-gatsby-project.sh', 'cmd-tools-gatsby-cli.sh'];
|
|
23
|
+
/** The agents the installer places in the AI Agents folder. */
|
|
24
|
+
exports.AGENTS = ['gatsby-site-builder', 'gatsby-tester'];
|
|
25
|
+
/** What the assistant is told about Gatsby in this workspace. */
|
|
26
|
+
function assistantContext() {
|
|
27
|
+
return [
|
|
28
|
+
'Gatsby (a plugin, @webship.co/workspace-gatsby): a Gatsby site is made from a starter with',
|
|
29
|
+
'`bash cmd-gatsby-project.sh <name> --install` from a sites folder (dev, test, sandboxes, demos),',
|
|
30
|
+
'in a container like every other project: the site is the Node.js project in <name>/site, built to a production build',
|
|
31
|
+
'and served at https://<name>.ddev.site. It is static: there is no database and there are no accounts.',
|
|
32
|
+
'`bash cmd-tools-gatsby-cli.sh <name>` says what the site is; `--run "<gatsby command>"` runs the Gatsby CLI in it,',
|
|
33
|
+
'`--build` builds and serves it again after a change, `--update` updates its packages, `--restart` starts its server again.',
|
|
34
|
+
'`bash cmd-tools-testing.sh <name>` sets up webship-js with the Gatsby step pack; `--run` runs the suite against the build.',
|
|
35
|
+
`For Gatsby work, hand over to the agents ${exports.AGENTS.map((a) => `\`${a}\``).join(' and ')}.`,
|
|
36
|
+
'Never run gatsby, node or npm on the host for a project.',
|
|
37
|
+
].join(' ');
|
|
38
|
+
}
|
|
39
|
+
function register(api) {
|
|
40
|
+
api.addAssistantContext(assistantContext);
|
|
41
|
+
}
|
|
42
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAcH,4CAYC;AAED,4BAEC;AA1BD,8DAA8D;AACjD,QAAA,QAAQ,GAAG,QAAQ,CAAC;AAEjC,+DAA+D;AAClD,QAAA,QAAQ,GAAG,CAAC,uBAAuB,EAAE,yBAAyB,CAAC,CAAC;AAE7E,+DAA+D;AAClD,QAAA,MAAM,GAAG,CAAC,qBAAqB,EAAE,eAAe,CAAC,CAAC;AAE/D,iEAAiE;AACjE,SAAgB,gBAAgB;IAC9B,OAAO;QACL,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,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,17 @@
|
|
|
1
|
+
Feature: The Gatsby plugin on the dashboard
|
|
2
|
+
Once the plugin is activated and installed, the sites folders offer the Gatsby builder, the
|
|
3
|
+
AI Agents folder lists the Gatsby agents, and the Plugins page lists the plugin with its steps.
|
|
4
|
+
|
|
5
|
+
Scenario: The plugin is listed on the Plugins page
|
|
6
|
+
Given I am on "/settings/plugins"
|
|
7
|
+
Then I should see "Gatsby"
|
|
8
|
+
And I should see "@webship.co/workspace-gatsby"
|
|
9
|
+
|
|
10
|
+
Scenario: A sites folder offers the Gatsby builder
|
|
11
|
+
Given I am on "/dev"
|
|
12
|
+
Then "option[value='cmd-gatsby-project.sh']" should be attached
|
|
13
|
+
|
|
14
|
+
Scenario: The AI Agents folder lists the agents the plugin ships
|
|
15
|
+
Given I am on "/ai-agents"
|
|
16
|
+
Then I should see "gatsby-site-builder"
|
|
17
|
+
And I should see "gatsby-tester"
|
package/package.json
CHANGED
|
@@ -1,6 +1,75 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@webship.co/workspace-gatsby",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.0.7",
|
|
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 two AI agents in the AI Agents folder.",
|
|
5
|
+
"main": "dist/src/index.js",
|
|
6
|
+
"types": "dist/src/index.d.ts",
|
|
7
|
+
"license": "ISC",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "https://github.com/webship/workspace-gatsby.git"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"dist/src",
|
|
14
|
+
"agents",
|
|
15
|
+
"commands",
|
|
16
|
+
"features",
|
|
17
|
+
"scripts",
|
|
18
|
+
"testing",
|
|
19
|
+
"README.md"
|
|
20
|
+
],
|
|
21
|
+
"scripts": {
|
|
22
|
+
"build": "tsc -p tsconfig.json",
|
|
23
|
+
"prepare": "npm run build",
|
|
24
|
+
"test": "npm run build && node --test dist/tests/*.test.js",
|
|
25
|
+
"lint": "tsc -p tsconfig.json --noEmit"
|
|
26
|
+
},
|
|
27
|
+
"workspacePlugin": {
|
|
28
|
+
"name": "gatsby",
|
|
29
|
+
"label": "Gatsby",
|
|
30
|
+
"commands": {
|
|
31
|
+
"types": [
|
|
32
|
+
"sites"
|
|
33
|
+
],
|
|
34
|
+
"workspaces": [
|
|
35
|
+
"dev",
|
|
36
|
+
"test",
|
|
37
|
+
"sandboxes",
|
|
38
|
+
"demos"
|
|
39
|
+
],
|
|
40
|
+
"files": [
|
|
41
|
+
"commands/cmd-gatsby-project.sh",
|
|
42
|
+
"commands/cmd-tools-gatsby-cli.sh"
|
|
43
|
+
]
|
|
44
|
+
},
|
|
45
|
+
"scripts": {
|
|
46
|
+
"functions": [
|
|
47
|
+
"scripts/functions/fun-gatsby.sh"
|
|
48
|
+
],
|
|
49
|
+
"args": [
|
|
50
|
+
"scripts/args/arg-gatsby.sh",
|
|
51
|
+
"scripts/args/arg-gatsby-cli.sh"
|
|
52
|
+
],
|
|
53
|
+
"machine": [
|
|
54
|
+
"testing/site.feature"
|
|
55
|
+
]
|
|
56
|
+
},
|
|
57
|
+
"ai": {
|
|
58
|
+
"agents": [
|
|
59
|
+
"agents/gatsby-site-builder.md",
|
|
60
|
+
"agents/gatsby-tester.md"
|
|
61
|
+
]
|
|
62
|
+
},
|
|
63
|
+
"features": [
|
|
64
|
+
"features/gatsby.feature"
|
|
65
|
+
]
|
|
66
|
+
},
|
|
67
|
+
"devDependencies": {
|
|
68
|
+
"@types/node": "^24.0.0",
|
|
69
|
+
"@webship.co/workspace-plugin-api": "^1.0.7",
|
|
70
|
+
"typescript": "^5.9.0"
|
|
71
|
+
},
|
|
72
|
+
"publishConfig": {
|
|
73
|
+
"access": "public"
|
|
74
|
+
}
|
|
75
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
|
|
3
|
+
argparse "$@" <<ARGEOF || exit 1
|
|
4
|
+
parser.add_argument('PROJECT_NAME',
|
|
5
|
+
help='The Gatsby project in this workspace.')
|
|
6
|
+
parser.add_argument('-r', '--run',
|
|
7
|
+
default="_none_",
|
|
8
|
+
help='A Gatsby CLI command to run in the site, without the leading gatsby. Example: --run "info"')
|
|
9
|
+
parser.add_argument('-b', '--build',
|
|
10
|
+
action='store_true',
|
|
11
|
+
default=False,
|
|
12
|
+
help='Build the site to a production build again, and serve the new build.')
|
|
13
|
+
parser.add_argument('-u', '--update',
|
|
14
|
+
action='store_true',
|
|
15
|
+
default=False,
|
|
16
|
+
help='Update the packages of the site within the ranges its package.json allows, then build and serve it again.')
|
|
17
|
+
parser.add_argument('-s', '--restart',
|
|
18
|
+
action='store_true',
|
|
19
|
+
default=False,
|
|
20
|
+
help='Start the server of the built site again, and wait until it answers.')
|
|
21
|
+
ARGEOF
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
|
|
3
|
+
argparse "$@" <<ARGEOF || exit 1
|
|
4
|
+
parser.add_argument('PROJECT_NAME',
|
|
5
|
+
help='The name of the project: its folder, its DDEV project and its host name.')
|
|
6
|
+
parser.add_argument('-s', '--starter',
|
|
7
|
+
default="${site_starter}",
|
|
8
|
+
help='The starter the site is made from: the address of a git repository. [default %(default)s]')
|
|
9
|
+
parser.add_argument('-r', '--ref',
|
|
10
|
+
default="${site_starter_ref}",
|
|
11
|
+
help='A commit, a branch or a tag of the starter; empty means its default branch. Example: --ref e75499f')
|
|
12
|
+
parser.add_argument('-i', '--install',
|
|
13
|
+
action='store_true',
|
|
14
|
+
default=False,
|
|
15
|
+
help='Build the site to a production build and serve it at the address of the project.')
|
|
16
|
+
parser.add_argument('-a', '--add-users',
|
|
17
|
+
action='store_true',
|
|
18
|
+
default=False,
|
|
19
|
+
help='Taken so that every builder accepts the same flags: a static site has no accounts, and nothing is added.')
|
|
20
|
+
parser.add_argument('-l', '--launch',
|
|
21
|
+
action='store_true',
|
|
22
|
+
default=False,
|
|
23
|
+
help='Open the site in a browser when it is ready.')
|
|
24
|
+
ARGEOF
|
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
|
|
3
|
+
# Gatsby for the Webship Workspace: make a site from a starter, build it to a production build,
|
|
4
|
+
# serve it, run the Gatsby CLI on it, and wire its step pack into the testing setup.
|
|
5
|
+
#
|
|
6
|
+
# Placed by `plugins.sh --install gatsby` in core/scripts/plugins/gatsby/functions/, where
|
|
7
|
+
# bootstrap sources it after the core's own functions. Everything runs in the project's container
|
|
8
|
+
# (DDEV by default), never on the host: the site is a Node.js project in the project's site/
|
|
9
|
+
# folder, the web container builds it and serves the build as a daemon (`gatsby serve`), and the
|
|
10
|
+
# router serves that at the project's address. There is no database.
|
|
11
|
+
#
|
|
12
|
+
# A Gatsby site is static: it has no accounts. Gatsby is not a PHP platform and DDEV has no
|
|
13
|
+
# project type for it, so a Gatsby project is recognised by a file (.ddev/config.gatsby.yaml,
|
|
14
|
+
# written by the builder), and four names are the ones the core's tools look for:
|
|
15
|
+
# set_gatsby_users an empty list: there are no accounts (cmd-tools-add-users.sh <project> gatsby)
|
|
16
|
+
# add_gatsby_users says so, and adds nothing (the same tool)
|
|
17
|
+
# cancel_gatsby_users says so, and removes nothing (cmd-tools-cancel-users.sh <project> gatsby)
|
|
18
|
+
# testing_configure_gatsby the step pack in the testing stack (cmd-tools-testing.sh <project>)
|
|
19
|
+
|
|
20
|
+
# The step pack a Gatsby project is tested with, and the release line it is required at.
|
|
21
|
+
readonly GATSBY_STEPS_PACKAGE='@webship-js/gatsby-steps';
|
|
22
|
+
readonly GATSBY_STEPS_VERSION='^2.0.2';
|
|
23
|
+
|
|
24
|
+
# Where the site lives in the web container, and the port its server listens on.
|
|
25
|
+
readonly GATSBY_SITE='/var/www/html/site';
|
|
26
|
+
readonly GATSBY_PORT='8000';
|
|
27
|
+
|
|
28
|
+
# A static site has no accounts: the list is empty.
|
|
29
|
+
function set_gatsby_users() {
|
|
30
|
+
users=();
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
# Is this folder a Gatsby project? The builder leaves .ddev/config.gatsby.yaml in it.
|
|
34
|
+
function gatsby_is_project() {
|
|
35
|
+
local project_path="$1";
|
|
36
|
+
[ -f "${project_path}/.ddev/config.gatsby.yaml" ] ;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
# Go to the project a tool was asked about, or say why not.
|
|
40
|
+
function gatsby_enter_project() {
|
|
41
|
+
local project_path="${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME}";
|
|
42
|
+
if [ ! -d "${project_path}" ] ; then
|
|
43
|
+
echo "No project ${PROJECT_NAME} in ${WORKSPACE_ROOT}/${doc_name}." ;
|
|
44
|
+
return 1 ;
|
|
45
|
+
fi
|
|
46
|
+
if ! gatsby_is_project "${project_path}" ; then
|
|
47
|
+
echo "${doc_name}/${PROJECT_NAME} is not a Gatsby project (it has no .ddev/config.gatsby.yaml)." ;
|
|
48
|
+
return 1 ;
|
|
49
|
+
fi
|
|
50
|
+
cd "${project_path}" || return 1 ;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
# What the container tool is told about the site: the router sends the project's address to the
|
|
54
|
+
# server of the built site, which the web container runs as a daemon once there is a build, and
|
|
55
|
+
# Node.js is in the web image itself. The container tool installs the Node.js of the project when
|
|
56
|
+
# the container starts, after the daemons have started and within a short time limit: baked into
|
|
57
|
+
# the image, the Node.js the site was built with is there before anything starts, on every
|
|
58
|
+
# restart, on a slow connection and offline.
|
|
59
|
+
function gatsby_write_ddev_config() {
|
|
60
|
+
local project_path="$1" nodejs_version="$2";
|
|
61
|
+
mkdir -p "${project_path}/.ddev/web-build" || return 1 ;
|
|
62
|
+
cat > "${project_path}/.ddev/config.gatsby.yaml" <<YAMLEOF
|
|
63
|
+
# Gatsby in this project. Written by the Gatsby builder of the workspace; build again rather than
|
|
64
|
+
# editing by hand. The web container serves no files of its own: the router sends ports 80 and
|
|
65
|
+
# 443 of the project's address to the server of the built site (gatsby serve), which the web
|
|
66
|
+
# container runs as a daemon once the site has a production build (site/public).
|
|
67
|
+
web_environment:
|
|
68
|
+
- GATSBY_TELEMETRY_DISABLED=1
|
|
69
|
+
web_extra_exposed_ports:
|
|
70
|
+
- name: gatsby
|
|
71
|
+
container_port: ${GATSBY_PORT}
|
|
72
|
+
http_port: 80
|
|
73
|
+
https_port: 443
|
|
74
|
+
web_extra_daemons:
|
|
75
|
+
- name: gatsby
|
|
76
|
+
command: "bash -c 'while [ ! -f ${GATSBY_SITE}/public/index.html ]; do sleep 2; done; cd ${GATSBY_SITE} && exec npx gatsby serve -p ${GATSBY_PORT} -H 0.0.0.0'"
|
|
77
|
+
directory: /var/www/html
|
|
78
|
+
YAMLEOF
|
|
79
|
+
cat > "${project_path}/.ddev/web-build/Dockerfile.gatsby" <<DOCKEREOF
|
|
80
|
+
# Node.js ${nodejs_version} in the web image, so the site's server has it before the container's
|
|
81
|
+
# daemons start. Written by the Gatsby builder of the workspace.
|
|
82
|
+
RUN N_PREFIX=/usr/local n install ${nodejs_version} && node --version
|
|
83
|
+
DOCKEREOF
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
# npm and the Gatsby CLI in the container, in the folder of the site.
|
|
87
|
+
function gatsby_npm() {
|
|
88
|
+
ddev exec -d "${GATSBY_SITE}" "npm $*" ;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
function gatsby_cli() {
|
|
92
|
+
ddev exec -d "${GATSBY_SITE}" "npx gatsby $*" ;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
# The release of Gatsby the site has installed.
|
|
96
|
+
function gatsby_version() {
|
|
97
|
+
ddev exec "node -p \"require('${GATSBY_SITE}/node_modules/gatsby/package.json').version\"" 2>/dev/null | tr -d '\r' ;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
# Wait until the server of the built site answers on its own port.
|
|
101
|
+
function gatsby_wait() {
|
|
102
|
+
local attempt ;
|
|
103
|
+
for attempt in $(seq 1 60) ; do
|
|
104
|
+
if ddev exec "curl -fsS -o /dev/null http://127.0.0.1:${GATSBY_PORT}/" > /dev/null 2>&1 ; then
|
|
105
|
+
return 0 ;
|
|
106
|
+
fi
|
|
107
|
+
sleep 2 ;
|
|
108
|
+
done
|
|
109
|
+
echo "The server of the built site did not start; what it said:" ;
|
|
110
|
+
ddev exec "supervisorctl tail webextradaemons:gatsby stderr" 2>/dev/null ;
|
|
111
|
+
return 1 ;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
# Start the server of the built site again (the daemon of the web container), and wait for it.
|
|
115
|
+
function gatsby_restart() {
|
|
116
|
+
if [ ! -f site/public/index.html ] ; then
|
|
117
|
+
echo "The site has no production build yet (site/public): build it with --build." ;
|
|
118
|
+
return 1 ;
|
|
119
|
+
fi
|
|
120
|
+
ddev exec "supervisorctl restart webextradaemons:gatsby" || return 1 ;
|
|
121
|
+
gatsby_wait ;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
# Build the site to a production build, and serve the new build.
|
|
125
|
+
function gatsby_production_build() {
|
|
126
|
+
echo "Building the site to a production build (gatsby build)." ;
|
|
127
|
+
gatsby_npm run build || { echo "The build of the site failed." ; return 1 ; } ;
|
|
128
|
+
gatsby_restart ;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
# Build a Gatsby site from nothing: the container, the starter, its packages, and with --install
|
|
132
|
+
# the production build, served.
|
|
133
|
+
function gatsby_build() {
|
|
134
|
+
trim_project_name ;
|
|
135
|
+
local base_url="https://${PROJECT_NAME}.ddev.site" ;
|
|
136
|
+
local starter="${STARTER:-${site_starter}}" ;
|
|
137
|
+
local ref="${REF:-${site_starter_ref:-}}" ;
|
|
138
|
+
local project_path="${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME}" ;
|
|
139
|
+
|
|
140
|
+
cd ${WORKSPACE_ROOT}/${doc_name} || exit 1 ;
|
|
141
|
+
|
|
142
|
+
drop_database ;
|
|
143
|
+
rm -rf "${PROJECT_NAME}" ;
|
|
144
|
+
mkdir -p "${PROJECT_NAME}" ;
|
|
145
|
+
cd "${project_path}" || exit 1 ;
|
|
146
|
+
|
|
147
|
+
# A generic web server and no database: the site is files, built once and served.
|
|
148
|
+
ddev config --project-type=generic --webserver-type=generic --docroot="" --project-name=${PROJECT_NAME} \
|
|
149
|
+
--omit-containers=db --nodejs-version=$(ddev_nodejs_version) || exit 1 ;
|
|
150
|
+
gatsby_write_ddev_config "${project_path}" "$(ddev_nodejs_version)" || exit 1 ;
|
|
151
|
+
ddev_up start -y || exit 1 ;
|
|
152
|
+
|
|
153
|
+
echo "Getting the starter: ${starter}${ref:+ at ${ref}}" ;
|
|
154
|
+
ddev exec "git clone --quiet '${starter}' site" || { echo "The starter could not be cloned." ; exit 1 ; } ;
|
|
155
|
+
if [ -n "${ref}" ] ; then
|
|
156
|
+
ddev exec -d "${GATSBY_SITE}" "git checkout --quiet '${ref}'" || { echo "The starter has no ${ref}." ; exit 1 ; } ;
|
|
157
|
+
fi
|
|
158
|
+
# The site is yours from here: it starts without the history of the starter.
|
|
159
|
+
rm -rf "${project_path}/site/.git" ;
|
|
160
|
+
|
|
161
|
+
echo "Installing the packages of the site. This takes a few minutes." ;
|
|
162
|
+
gatsby_npm install --no-audit --no-fund || { echo "npm install failed in the site." ; exit 1 ; } ;
|
|
163
|
+
|
|
164
|
+
[ "${ADD_USERS}" == 'yes' ] && echo "--add-users: a Gatsby site is static and has no accounts; nothing is added." ;
|
|
165
|
+
|
|
166
|
+
if [ "${INSTALL}" == 'yes' ] ; then
|
|
167
|
+
gatsby_production_build || exit 1 ;
|
|
168
|
+
echo "${doc_name} ${PROJECT_NAME} has been built and is served: Gatsby $(gatsby_version).";
|
|
169
|
+
echo "Go to ${base_url}";
|
|
170
|
+
else
|
|
171
|
+
echo "${doc_name} ${PROJECT_NAME} is ready to build: Gatsby $(gatsby_version).";
|
|
172
|
+
echo "Build and serve it with: bash cmd-tools-gatsby-cli.sh ${PROJECT_NAME} --build (or build with --install)";
|
|
173
|
+
fi
|
|
174
|
+
|
|
175
|
+
if [ "${LAUNCH}" == 'yes' ] ; then
|
|
176
|
+
ddev launch ;
|
|
177
|
+
fi
|
|
178
|
+
|
|
179
|
+
cd ${WORKSPACE_ROOT}/${doc_name};
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
# A static site has no accounts: there is nothing to add, and nothing to remove.
|
|
183
|
+
function add_gatsby_users() {
|
|
184
|
+
echo "A Gatsby site is static: it has no accounts, so there are none to add." ;
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
function cancel_gatsby_users() {
|
|
188
|
+
echo "A Gatsby site is static: it has no accounts, so there are none to remove." ;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
# What cmd-tools-gatsby-cli.sh does: the first of --run, --build, --update, --restart that was
|
|
192
|
+
# asked for; with none of them, what the site is.
|
|
193
|
+
function gatsby_cli_tool() {
|
|
194
|
+
trim_project_name ;
|
|
195
|
+
gatsby_enter_project || exit 1 ;
|
|
196
|
+
|
|
197
|
+
if ! ddev describe -j 2>/dev/null | grep -q '"status":"running"' ; then
|
|
198
|
+
ddev start -y || exit 1 ;
|
|
199
|
+
fi
|
|
200
|
+
|
|
201
|
+
if [ ! "${RUN}" == '_none_' ] ; then
|
|
202
|
+
# Unquoted on purpose: --run "info --clipboard" is a command and its arguments.
|
|
203
|
+
gatsby_cli ${RUN} ;
|
|
204
|
+
exit $? ;
|
|
205
|
+
fi
|
|
206
|
+
|
|
207
|
+
if [ "${BUILD}" == 'yes' ] ; then
|
|
208
|
+
gatsby_production_build || exit 1 ;
|
|
209
|
+
echo "Gatsby $(gatsby_version): the new build is served at https://${PROJECT_NAME}.ddev.site" ;
|
|
210
|
+
elif [ "${UPDATE}" == 'yes' ] ; then
|
|
211
|
+
echo "Gatsby $(gatsby_version) is installed." ;
|
|
212
|
+
gatsby_npm update --no-audit --no-fund || exit 1 ;
|
|
213
|
+
gatsby_production_build || exit 1 ;
|
|
214
|
+
echo "Gatsby $(gatsby_version): the new build is served at https://${PROJECT_NAME}.ddev.site" ;
|
|
215
|
+
elif [ "${RESTART}" == 'yes' ] ; then
|
|
216
|
+
gatsby_restart || exit 1 ;
|
|
217
|
+
echo "Gatsby $(gatsby_version): the build is served at https://${PROJECT_NAME}.ddev.site" ;
|
|
218
|
+
else
|
|
219
|
+
echo "${doc_name}/${PROJECT_NAME}: Gatsby $(gatsby_version) at https://${PROJECT_NAME}.ddev.site" ;
|
|
220
|
+
echo "" ;
|
|
221
|
+
if [ -f site/public/index.html ] ; then
|
|
222
|
+
echo "Production build: site/public, $(find site/public -name '*.html' | wc -l) pages, built $(date -r site/public/index.html '+%Y-%m-%d %H:%M')" ;
|
|
223
|
+
if ddev exec "curl -fsS -o /dev/null http://127.0.0.1:${GATSBY_PORT}/" > /dev/null 2>&1 ; then
|
|
224
|
+
echo "Server: running (gatsby serve)" ;
|
|
225
|
+
else
|
|
226
|
+
echo "Server: not answering; start it again with --restart" ;
|
|
227
|
+
fi
|
|
228
|
+
else
|
|
229
|
+
echo "Production build: none yet; build it with --build" ;
|
|
230
|
+
fi
|
|
231
|
+
echo "Accounts: none (a static site)" ;
|
|
232
|
+
fi
|
|
233
|
+
cd ${WORKSPACE_ROOT}/${doc_name};
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
# The step pack in the testing stack of a Gatsby project. The core's testing_configure calls this
|
|
237
|
+
# in the project folder once webship-js is scaffolded and before the dependencies are installed;
|
|
238
|
+
# for a project that is not Gatsby it changes nothing.
|
|
239
|
+
#
|
|
240
|
+
# It adds the pack to package.json, lists its step definitions in cucumber.js after webship-js's
|
|
241
|
+
# own, and writes a first feature when the project has none of its own. There is no users
|
|
242
|
+
# registry: the site has no accounts. Every part is skipped when it is already there, so a second
|
|
243
|
+
# run adds what the first missed and never resets a suite. The suite is the project's (its
|
|
244
|
+
# package.json, cucumber.js and tests/ are next to site/, not in it).
|
|
245
|
+
function testing_configure_gatsby() {
|
|
246
|
+
local project_path="$1";
|
|
247
|
+
gatsby_is_project "${project_path}" || return 0 ;
|
|
248
|
+
if [ ! -f "${project_path}/cucumber.js" ] || [ ! -f "${project_path}/package.json" ] ; then
|
|
249
|
+
echo " Gatsby: cucumber.js is not here yet — run the testing setup again once webship-js is scaffolded." ;
|
|
250
|
+
return 1 ;
|
|
251
|
+
fi
|
|
252
|
+
|
|
253
|
+
echo "Adding the Gatsby step pack (${GATSBY_STEPS_PACKAGE} ${GATSBY_STEPS_VERSION}).";
|
|
254
|
+
|
|
255
|
+
python3 - "${project_path}" "${GATSBY_STEPS_PACKAGE}" "${GATSBY_STEPS_VERSION}" <<'PYEOF' || return 1
|
|
256
|
+
import json, re, sys
|
|
257
|
+
|
|
258
|
+
project, pack, version = sys.argv[1:4]
|
|
259
|
+
|
|
260
|
+
# package.json: the pack as a dev dependency, at the release line this plugin was proven on.
|
|
261
|
+
pkg_file = project + '/package.json'
|
|
262
|
+
pkg = json.load(open(pkg_file))
|
|
263
|
+
if pack not in pkg.get('dependencies', {}) and pack not in pkg.get('devDependencies', {}):
|
|
264
|
+
pkg.setdefault('devDependencies', {})[pack] = version
|
|
265
|
+
open(pkg_file, 'w').write(json.dumps(pkg, indent=2) + '\n')
|
|
266
|
+
print(' package.json: %s %s' % (pack, version))
|
|
267
|
+
|
|
268
|
+
# cucumber.js: the pack's step definitions after webship-js's own.
|
|
269
|
+
cucumber_file = project + '/cucumber.js'
|
|
270
|
+
src = open(cucumber_file).read()
|
|
271
|
+
before = src
|
|
272
|
+
|
|
273
|
+
if ('node_modules/%s/' % pack) not in src:
|
|
274
|
+
line = "'node_modules/%s/tests/step-definitions/**/*.js'," % pack
|
|
275
|
+
core = re.search(r"^([ \t]*)'node_modules/webship-js/tests/step-definitions/[^']*',.*$", src, re.M)
|
|
276
|
+
opening = re.search(r"^([ \t]*)require:[ \t]*\[[ \t]*$", src, re.M)
|
|
277
|
+
if core:
|
|
278
|
+
src = src[:core.end()] + '\n' + core.group(1) + line + src[core.end():]
|
|
279
|
+
elif opening:
|
|
280
|
+
src = src[:opening.end()] + '\n' + opening.group(1) + ' ' + line + src[opening.end():]
|
|
281
|
+
else:
|
|
282
|
+
sys.exit(" cucumber.js has no require list this can add to. Add this line to it:\n " + line)
|
|
283
|
+
print(' cucumber.js: the step definitions of %s' % pack)
|
|
284
|
+
|
|
285
|
+
if src != before:
|
|
286
|
+
open(cucumber_file, 'w').write(src)
|
|
287
|
+
PYEOF
|
|
288
|
+
|
|
289
|
+
# A first feature, when the project has none for the site yet: the front page as a production
|
|
290
|
+
# build, rendered and hydrated, its page data and its 404 page.
|
|
291
|
+
local feature="${WORKSPACE_SCRIPTS}/plugins/gatsby/site.feature" ;
|
|
292
|
+
if [ -f "${feature}" ] && [ ! -f "${project_path}/tests/features/site.feature" ] ; then
|
|
293
|
+
mkdir -p "${project_path}/tests/features" && cp "${feature}" "${project_path}/tests/features/site.feature" \
|
|
294
|
+
&& echo " tests/features/site.feature: a first feature for the site" ;
|
|
295
|
+
fi
|
|
296
|
+
|
|
297
|
+
if [ ! -f "${project_path}/site/public/index.html" ] ; then
|
|
298
|
+
echo " the site has no production build yet: build it (cmd-tools-gatsby-cli.sh ${PROJECT_NAME} --build) before the suite runs" ;
|
|
299
|
+
fi
|
|
300
|
+
}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
Feature: The built site answers
|
|
2
|
+
As the owner of the site
|
|
3
|
+
I want the production build to be served, rendered and complete
|
|
4
|
+
So that a build that came out broken is caught before anything else is tested
|
|
5
|
+
|
|
6
|
+
# Placed by the workspace's testing setup as a starting point: it is yours to change.
|
|
7
|
+
# The site is static: it has no accounts, so no scenario logs in. The suite runs against the
|
|
8
|
+
# production build that is served at the address of the project; build again after a change
|
|
9
|
+
# (cmd-tools-gatsby-cli.sh <project> --build).
|
|
10
|
+
|
|
11
|
+
@critical
|
|
12
|
+
Scenario: The front page is served from the production build
|
|
13
|
+
Given I am an anonymous user
|
|
14
|
+
And I am on the homepage
|
|
15
|
+
Then the response status code should be 200
|
|
16
|
+
And the site should be a production build
|
|
17
|
+
And the page should be from the current build
|
|
18
|
+
|
|
19
|
+
@critical
|
|
20
|
+
Scenario: The front page is rendered and hydrated
|
|
21
|
+
Given I am on the homepage
|
|
22
|
+
Then I should see a hydrated page
|
|
23
|
+
And there should be no hydration errors
|
|
24
|
+
|
|
25
|
+
Scenario: The build wrote the data of the front page
|
|
26
|
+
Given I am on the homepage
|
|
27
|
+
Then the page-data for "/" should be available
|
|
28
|
+
And the page-data for "/no-such-page/" should not be available
|
|
29
|
+
|
|
30
|
+
Scenario: The build wrote a 404 page
|
|
31
|
+
Given I am on the homepage
|
|
32
|
+
Then the 404 page should be available
|
|
33
|
+
|
|
34
|
+
Scenario: An address with no page answers 404 with the 404 page of the site
|
|
35
|
+
When I go to "/this-page-does-not-exist/"
|
|
36
|
+
Then I should be on a 404 page
|
|
37
|
+
And the response status code should be 404
|
|
38
|
+
|
|
39
|
+
Scenario: A page that exists is not a 404 page
|
|
40
|
+
Given I am on the homepage
|
|
41
|
+
Then I should not be on a 404 page
|