@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 CHANGED
@@ -1,3 +1,148 @@
1
- # Temporary Holding Version
1
+ # @webship.co/workspace-gatsby
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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