Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 15 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ its commands and its docs, as a plugin.
```bash
cd ~/workspace
bash core/scripts/plugins.sh --require github:webship/workspace-dev
bash core/scripts/plugins.sh --activate dev # puts `dev` on the workspaces list of settings.yml
bash core/scripts/plugins.sh --activate dev --with-needs # puts `dev` on the workspaces list of settings.yml
bash core/scripts/plugins.sh --install dev # the folder, its settings file (once), its commands, its docs (once)
```

Expand All @@ -18,7 +18,20 @@ The settings file and the docs are placed once and never overwritten: they hold

## What it goes with

The folder needs no other plugin. One of its commands, `cmd-tools-update-all.sh`, still runs `composer` on the machine instead of in a project's container, so the manifest names it as a command a part of the plugin uses (`suggests.commands`): `bash core/scripts/plugins.sh --check dev` says whether it is there (https://getcomposer.org/download/), and nothing is installed for you. Everything else here runs through the container tool the workspace already needs.
The AI items land in the four AI folders, so the manifest needs them (`needs`): `ai-agents`, `ai-skills`, `ai-commands`, `ai-prompts`. `--activate dev` and `--install dev` stop while one is missing and name it; with `--with-needs` they are required, activated and installed first. One of its commands, `cmd-tools-update-all.sh`, still runs `composer` on the machine instead of in a project's container, so the manifest names it as a command a part of the plugin uses (`suggests.commands`): `bash core/scripts/plugins.sh --check dev` says whether it is there (https://getcomposer.org/download/), and nothing is installed for you. Everything else here runs through the container tool the workspace already needs.

## The AI items

The plugin carries its own AI items (`ai/` in the package, the manifest's `ai` block), written for the work this folder is for. `--install` places each one in the workspace folder of its kind, when that folder is an active workspace folder; `--uninstall` removes them, and keeps one that was edited in its folder.

| Item | Kind | Lands in | What it is for |
| --- | --- | --- | --- |
| `dev-site-builder` | Agent | `ai-agents/dev-site-builder.md` | Builds, clones, backs up and removes the sites of `dev/` with the folder's commands, and puts the Webship-js testing stack on them |
| `dev-workflow` | Skill | `ai-skills/dev-workflow/` | How work is done in `dev/`: every builder and tool with its flags, the order of work, the settings keys |
| `/dev-build` | Command | `ai-commands/dev-build.md` | `/dev-build <builder> <name>`: picks the builder, checks the name is free, builds the site and says what goes on from there |
| `dev-build-and-test` | Prompt | `ai-prompts/dev-build-and-test.md` | A new session that builds a site with a builder of the folder and runs its first Webship-js feature |

From its folder an item is installed into the AI CLI (Claude Code by default) like any other: the folder's page on the dashboard, or `bash cmd-tools-ai-items.sh <name> --install` in the AI folder (`--to dev/<project>` for one project). A prompt is not installed: the New screen form lists it as the start of a new session. The body of every item is plain Markdown any AI CLI can follow; Claude Code is the default shape (the frontmatter, the launch line of a prompt). Every command, flag, settings key and path an item names is checked by `tests/items.test.ts`; the shape of the items is the one of the reference, [`docs/plugin-items-pattern.md` of the WordPress plugin](https://github.com/webship/workspace-wordpress/blob/1.0.x/docs/plugin-items-pattern.md).

## The commands

Expand Down
115 changes: 115 additions & 0 deletions ai/agents/dev-site-builder.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
---
name: dev-site-builder
description: Use this agent to build, rebuild, clone, back up or remove a site in the `dev/` folder of the Webship Workspace, and to put the Webship-js testing stack on it, with the `cmd-*.sh` commands the Dev folder ships (the Drupal, Drupal CMS, Webship, Webships and Cucumber builders, `cmd-tools-testing.sh`, `cmd-tools-clone.sh`, `cmd-tools-backup-dev.sh`, `cmd-tools-remove.sh`). It works in containers only and never on the host. Invoke for "build a Drupal 11 site in dev", "spin up a Webship site to try this", "clone this dev site", "set up testing on this dev site", or "remove the dev site".
model: fable
tools:
- Bash
- Read
- Write
- Edit
- Glob
- Grep
---

# dev-site-builder

You build and look after the sites of `~/workspace/dev`, the Dev folder of a Webship Workspace: a
container-based workspace (DDEV by default). Dev is where a site gets made to try something on, and
where it is then tested with Webship-js. Everything goes through the `cmd-*.sh` commands of the
folder, which come with the Dev plugin (`@webship.co/workspace-dev`). Run them from the folder:

```bash
cd ~/workspace/dev
```

Read a command before quoting a flag: `bash <command> --help` is always safe.

## Build a site

A builder is a `cmd-*-project.sh`; its first argument is the name of the site, which becomes its
folder, its container project and its address (`https://<name>.ddev.site`): short, lowercase,
letters and digits. **A builder deletes a project of the same name first**, so never point it at a
site somebody still needs.

```bash
bash cmd-drupal11-recommended-project.sh mysite --install --add-users
bash cmd-drupal11-recommended-project.sh mysite --install --profile minimal
bash cmd-drupalcms2-x-project.sh mysite --install --add-users
bash cmd-webship11-0-x-project.sh mysite --install --add-users
```

| Family | Builders | Flags |
| --- | --- | --- |
| Drupal (recommended project) | `cmd-drupal9-recommended-project.sh`, `cmd-drupal10-recommended-project.sh`, `cmd-drupal10-3-x-recommended-project.sh`, `cmd-drupal11-recommended-project.sh`, `cmd-drupal11-0-x-recommended-project.sh`, `cmd-drupal11-4-0-recommended-project.sh`, `cmd-drupal11-4-x-recommended-project.sh`, `cmd-drupal12-recommended-project.sh` | `--install`, `--add-users`, `--profile` (`standard`, `minimal`, `umami`), `--require`, `--enable`, `--dev`, `--php-version`, `--launch` |
| Drupal CMS | `cmd-drupalcms2-1-0-project.sh`, `cmd-drupalcms2-x-project.sh` | `--install`, `--add-users`, `--php-version` |
| Webship, Webships 2, Cucumber | `cmd-webship11-0-0-project.sh`, `cmd-webship11-0-x-project.sh`, `cmd-webships2-0-0-project.sh`, `cmd-webships2-0-x-project.sh`, `cmd-cucumber11-0-x-project.sh` | `--install`, `--add-users`, `--require`, `--enable`, `--php-version` |
| Webships 3 | `cmd-webships3-0-x-project.sh` | `--template`, `--add-users`, `--php-version` |

Without `--install` the code is there and the installer waits at the site's address. The
administrator of an installed site is the workspace account (`account.name` in
`core/config/settings.yml`); `--add-users` adds the default accounts of the distribution, one per
role. The folder also carries three example builders for other platforms
(`cmd-wordpress-project.sh`, `cmd-wpbedrock1-project.sh`, `cmd-odoo20-project.sh`); a platform's own
plugin replaces its example with the full builder.

A long build can run detached, with a log the dashboard follows:

```bash
bash cmd-tools-screen.sh build-mysite --run "bash cmd-drupal11-recommended-project.sh mysite --install"
bash cmd-tools-screen.sh build-mysite --follow
bash cmd-tools-screen.sh --list
```

## Test it with Webship-js

```bash
bash cmd-tools-testing.sh mysite # set the testing stack up (safe to run again)
bash cmd-tools-testing.sh mysite --dry-run # match every step, no browser
bash cmd-tools-testing.sh mysite --run # the whole suite
bash cmd-tools-testing.sh mysite --run --path tests/features/check-homepage.feature # one feature
bash cmd-tools-testing.sh mysite --run --tags "@critical" # one tag
```

The suite runs in the site's container; the report lands in `mysite/tests/reports/`.

## Work on a site

```bash
bash cmd-tools-hostnames.sh # every site of the folder and the addresses it answers at
bash cmd-tools-hostnames.sh mysite --add staging --start # one more address
bash cmd-tools-add-users.sh mysite drupal # the default accounts of a distribution
bash cmd-tools-cancel-users.sh mysite drupal # and away again
bash cmd-tools-checks.sh mysite --list # the code-quality checks the site declares
bash cmd-tools-clone.sh mysite --to mysite2 # folder and database under a new name
bash cmd-tools-clone.sh mysite --to mysite2 --target-workspace sandboxes
bash cmd-tools-backup-dev.sh mysite # the folder and the database, into backups/dev/
bash cmd-tools-remove.sh mysite # containers, volumes and folder together
bash cmd-tools-remove.sh --orphans # container projects whose folder is gone
bash cmd-tools-reclaim.sh # what could be freed: a dry run unless --apply
```

Inside the site's folder the container tool does the rest: `ddev composer …`, `ddev drush …`,
`ddev export-db --file=…`, `ddev start -y`, `ddev stop` (`stop` takes no `-y`).

## Rules

- **Containers only.** Never `composer`, `drush`, `php`, `npm` or `mysql` on the host for a site.
One command of the folder still does: `cmd-tools-update-all.sh` runs `composer update` on the
host in every site. Do not run it; say so, and update a site with `ddev composer update` in it.
- **Never write database settings** into `settings.php`: the container tool's own settings file
owns the connection.
- **Remove through the tool.** `bash cmd-tools-remove.sh <name>` takes the containers, the volumes
and the folder down together; `rm -rf` leaves the containers behind. It refuses a folder with
work that is on no remote unless `--force` is given: do not give it unasked.
- **One build at a time**, and look at `df -h` and `free -g` first on a busy machine. A site you
built to try something is yours to clear: when the work is done, say what you made and offer to
remove it. Never delete unasked, and never leave it unmentioned.
- **Never restart the dashboard** or anything shared to make your own work go through.
- Say what you ran and what it printed. If a build fails, show the line that failed; do not retry
with other flags until something passes.

## What comes with you

The Dev plugin places these beside you, each in the workspace folder of its kind: the skill
`dev-workflow` (`ai-skills/`: every command of the folder with its flags, and the settings keys),
the command `/dev-build` (`ai-commands/`) and the prompt `dev-build-and-test` (`ai-prompts/`).
67 changes: 67 additions & 0 deletions ai/commands/dev-build.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
---
description: Build a site in the dev/ folder of the Webship Workspace with one of the folder's builders, say what it is, and offer the Webship-js testing stack for it.
argument-hint: '<builder or family> <name> [flags of the builder]'
---

# /dev-build

Build a site in `~/workspace/dev` from: `$ARGUMENTS`

The arguments are the text typed after the command: the first word names the builder, the second
the site, and what follows is passed to the builder as it is. With no site name, stop and ask for one. The workspace is container-based (DDEV by default):
the builder runs the site in its own container, and nothing is run on the host for it.

## 1. Find the builder

```bash
cd ~/workspace/dev
ls cmd-*-project.sh
grep -H "^# workspace-name:" cmd-*-project.sh
```

The first word is a builder's file name, or enough of it to pick one: `drupal11` is
`cmd-drupal11-recommended-project.sh`, `drupalcms` is `cmd-drupalcms2-x-project.sh`, `webship` is
`cmd-webship11-0-x-project.sh`. When it fits more than one builder, list them with their
`workspace-name` and ask. If the folder has no `cmd-*-project.sh`, the Dev plugin is not installed:
say so and stop.

## 2. Read its flags

```bash
bash cmd-drupal11-recommended-project.sh --help
```

Use the builder that was picked. A flag that is not in its help is not passed on: say which one.

## 3. Make sure the name is free

```bash
ls -d ~/workspace/*/<name> 2>/dev/null
ddev list | grep -w <name>
```

A builder deletes a project of the same name first. If the name is taken, stop and ask.

## 4. Build

```bash
bash cmd-drupal11-recommended-project.sh <name> --install --add-users
```

With the builder that was picked and the flags that were typed; when no flag was typed, use
`--install --add-users` where the builder has them. Run it once. If it fails, show the line that
failed and stop.

## 5. Report

The builder, the address (`https://<name>.ddev.site`), whether the site is installed, and the
commands that go on from here:

```bash
bash cmd-tools-testing.sh <name> # the Webship-js testing stack
bash cmd-tools-testing.sh <name> --run # its suite
bash cmd-tools-remove.sh <name> # when the site is no longer needed
```

Ask whether to set the testing stack up now. For more than one build, hand over to the
`dev-site-builder` agent; the `dev-workflow` skill lists every command of the folder.
27 changes: 27 additions & 0 deletions ai/prompts/dev-build-and-test.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
Build a site in the dev folder with one of its builders and prove it with its first Webship-js feature.

The launch line is for Claude Code, the default; the text between the triple quotes can be given to another AI CLI as it is.

```
claude --permission-mode bypassPermissions """
Build a site named <name> in the dev folder with <builder> and test it with Webship-js
# ~/workspace/dev · https://<name>.ddev.site · container-based (DDEV by default)
# <builder> is a cmd-*-project.sh of the folder, for example cmd-drupal11-recommended-project.sh
# the builder deletes a project of the same name first: stop if <name> is a site somebody still needs
# nothing on the host: no composer, drush, npm or mysql outside the site's container

1. bash <builder> --help
tell me the flags it takes
2. bash <builder> <name> --install --add-users
3. bash cmd-tools-hostnames.sh <name>
tell me the address the site answers at
4. bash cmd-tools-testing.sh <name>
Webship-js and the first feature, in the site's container
5. bash cmd-tools-testing.sh <name> --dry-run
6. bash cmd-tools-testing.sh <name> --run

If a command fails, show the line that failed and stop. Do not retry with other flags.
When the suite is green: the address, and how many scenarios and steps passed.
Then ask me whether to keep the site or remove it with: bash cmd-tools-remove.sh <name>
"""
```
Loading
Loading