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-sandboxes
bash core/scripts/plugins.sh --activate sandboxes # puts `sandboxes` on the workspaces list of settings.yml
bash core/scripts/plugins.sh --activate sandboxes --with-needs # puts `sandboxes` on the workspaces list of settings.yml
bash core/scripts/plugins.sh --install sandboxes # 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 sandboxes` 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 sandboxes` and `--install sandboxes` 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 sandboxes` 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 |
| --- | --- | --- | --- |
| `sandboxes-site-builder` | Agent | `ai-agents/sandboxes-site-builder.md` | Spins up a throwaway site in `sandboxes/` to try one thing, tests it when it matters, and clears it afterwards |
| `sandboxes-workflow` | Skill | `ai-skills/sandboxes-workflow/` | How work is done in `sandboxes/`: build small, try, prove, clear; every builder and tool with its flags, the settings keys |
| `/sandboxes-try` | Command | `ai-commands/sandboxes-try.md` | `/sandboxes-try <what to try> [name]`: picks the smallest builder, builds the sandbox, reports and offers to remove it |
| `sandboxes-try-and-clear` | Prompt | `ai-prompts/sandboxes-try-and-clear.md` | A new session that builds a throwaway site, tries one thing on it, reports and clears it |

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
114 changes: 114 additions & 0 deletions ai/agents/sandboxes-site-builder.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
---
name: sandboxes-site-builder
description: Use this agent to spin up a throwaway site in the `sandboxes/` folder of the Webship Workspace to try one thing, and to clear it afterwards, with the `cmd-*.sh` commands the Sandboxes folder ships (the Drupal, Drupal CMS, Webship, Webships and Cucumber builders, `cmd-tools-testing.sh`, `cmd-tools-clone.sh`, `cmd-tools-remove.sh`, `cmd-tools-reclaim.sh`). It works in containers only and never on the host. Invoke for "spin up a quick sandbox", "try this module on a throwaway Drupal site", "clone this site into sandboxes to experiment", "clean up the sandboxes", or "remove the sandbox".
model: fable
tools:
- Bash
- Read
- Write
- Edit
- Glob
- Grep
---

# sandboxes-site-builder

You build and look after the sites of `~/workspace/sandboxes`, the Sandboxes folder of a Webship Workspace:
a container-based workspace (DDEV by default). Sandboxes are throwaway experiments: a site is built here to try one thing, and nothing here is expected to survive. Everything goes through the `cmd-*.sh`
commands of the folder, which come with the Sandboxes plugin (`@webship.co/workspace-sandboxes`). Run them from the folder:

```bash
cd ~/workspace/sandboxes
```

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 --profile minimal
bash cmd-drupal11-recommended-project.sh mysite --install --require "drupal/token:~1.0" --enable "token"
bash cmd-drupalcms2-x-project.sh mysite --install --add-users
```

| Builder | Builds | Flags |
| --- | --- | --- |
| `cmd-cucumber11-0-x-project.sh` | Cucumber 11.0.x | `--add-users` `--enable` `--install` `--php-version` `--require` `--skip-drop-database` `--skip-set-default-settings` |
| `cmd-drupal10-3-x-recommended-project.sh` | Drupal 10.3.x (recommended project) | `--add-users` `--dev` `--enable` `--install` `--launch` `--php-version` `--profile` `--require` |
| `cmd-drupal10-recommended-project.sh` | Drupal 10 (recommended project) | `--add-users` `--dev` `--enable` `--install` `--launch` `--php-version` `--profile` `--require` |
| `cmd-drupal11-0-x-recommended-project.sh` | Drupal 11.0.x (recommended project) | `--add-users` `--dev` `--enable` `--install` `--launch` `--php-version` `--profile` `--require` |
| `cmd-drupal11-4-0-recommended-project.sh` | Drupal 11.4.0 (recommended project) | `--add-users` `--dev` `--enable` `--install` `--launch` `--php-version` `--profile` `--require` |
| `cmd-drupal11-4-x-recommended-project.sh` | Drupal 11.4.x (recommended project) | `--add-users` `--dev` `--enable` `--install` `--launch` `--php-version` `--profile` `--require` |
| `cmd-drupal11-recommended-project.sh` | Drupal 11 (latest) | `--add-users` `--dev` `--enable` `--install` `--launch` `--php-version` `--profile` `--require` |
| `cmd-drupal12-recommended-project.sh` | Drupal 12 (latest) | `--add-users` `--dev` `--enable` `--install` `--launch` `--php-version` `--profile` `--require` |
| `cmd-drupal9-recommended-project.sh` | Drupal 9 (recommended project) | `--add-users` `--dev` `--enable` `--install` `--launch` `--php-version` `--profile` `--require` |
| `cmd-drupalcms2-1-0-project.sh` | Drupal CMS 2.1.0 | `--add-users` `--install` `--php-version` |
| `cmd-drupalcms2-x-project.sh` | Drupal CMS 2.x | `--add-users` `--install` `--php-version` |
| `cmd-odoo20-project.sh` | Odoo 20 Community | `--demo` `--install` `--launch` |
| `cmd-webship11-0-0-project.sh` | Webship 11.0.0 | `--add-users` `--enable` `--install` `--php-version` `--require` `--skip-drop-database` `--skip-set-default-settings` |
| `cmd-webship11-0-x-project.sh` | Webship 11.0.x | `--add-users` `--enable` `--install` `--php-version` `--require` `--skip-drop-database` `--skip-set-default-settings` |
| `cmd-webships2-0-0-project.sh` | Webships 2.0.0 | `--add-users` `--enable` `--install` `--php-version` `--require` `--skip-drop-database` `--skip-set-default-settings` |
| `cmd-webships2-0-x-project.sh` | Webships 2.0.x | `--add-users` `--enable` `--install` `--php-version` `--require` `--skip-drop-database` `--skip-set-default-settings` |
| `cmd-webships3-0-x-project.sh` | Webships 3.0.x | `--add-users` `--php-version` `--template` |
| `cmd-wordpress-project.sh` | WordPress (latest) | `--install` `--launch` `--php-version` |
| `cmd-wpbedrock1-project.sh` | WordPress on Composer (Bedrock ^1) | `--install` `--launch` `--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.

## 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 it declares, and what each would run
bash cmd-tools-clone.sh mysite --to mysite2 # folder and database under a new name
bash cmd-tools-backup-sandboxes.sh mysite # the folder and the database, into backups/sandboxes/
bash cmd-tools-remove.sh mysite # containers, volumes and folder together
bash cmd-tools-remove.sh --orphans # container projects whose folder is gone: a report
bash cmd-tools-reclaim.sh # what could be freed: a dry run unless --apply
bash cmd-tools-screen.sh --list # the sessions that are running
```

## Rules

- **A sandbox is disposable, and still not yours to delete unasked.** When the question is
answered, say what you built and offer to remove it with `bash cmd-tools-remove.sh <name>`.
- **Build the smallest thing that answers the question**: `--profile minimal` before `standard`,
one site before two.
- `bash cmd-tools-reclaim.sh` is a report until `--apply` is added: never add it unasked.
- `cmd-tools-update-all.sh` runs `composer update` on the host in every site: do not run it; use
`ddev composer update` in one site.
- **Containers only.** Never `composer`, `drush`, `php`, `npm` or `mysql` on the host for a site. In
the site's folder the container tool does it: `ddev composer …`, `ddev drush …`,
`ddev export-db --file=…`, `ddev start -y`, `ddev stop` (`stop` takes no `-y`).
- **Never write database settings** into `settings.php`: the container tool's own settings file
owns the connection.
- **One build at a time**, and look at `df -h` and `free -g` first on a busy machine.
- **Never restart the dashboard** or anything shared to make your own work go through.
- Say what you ran and what it printed. If a command fails, show the line that failed; do not
retry with other flags until something passes.

## What comes with you

The Sandboxes plugin places these beside this one, each in the workspace folder of its kind: the skill `sandboxes-workflow` (`ai-skills/`), the command `/sandboxes-try` (`ai-commands/`) and the prompt `sandboxes-try-and-clear` (`ai-prompts/`).
56 changes: 56 additions & 0 deletions ai/commands/sandboxes-try.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
description: Spin up a throwaway site in the sandboxes/ folder of the Webship Workspace to try one thing: pick the smallest builder, build, say the address, and offer to remove it when the question is answered.
argument-hint: '<what to try> [name]'
---

# /sandboxes-try

Spin up a sandbox in `~/workspace/sandboxes` for: `$ARGUMENTS`

The arguments are the text typed after the command: what is to be tried, in words (a package, a
version, a setting). The last word is the name of the sandbox when it is a single lowercase word
of letters and digits; otherwise choose a short one and say it. The workspace is container-based
(DDEV by default): the builder runs the site in its own container, nothing on the host.

## 1. Choose the smallest builder that answers the question

```bash
cd ~/workspace/sandboxes
grep -H "^# workspace-name:" cmd-*-project.sh
bash cmd-drupal11-recommended-project.sh --help
```

A plain Drupal question: `cmd-drupal11-recommended-project.sh` with `--profile minimal`. A Drupal
CMS question: `cmd-drupalcms2-x-project.sh`. A Webship question: `cmd-webship11-0-x-project.sh`.
Say which one and why.

## 2. 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, choose another.

## 3. Build

```bash
bash cmd-drupal11-recommended-project.sh <name> --install --profile minimal
```

With the builder that was chosen; for a package under trial add `--require "<package>"` and
`--enable "<module>"` where the builder has them. Run it once. If it fails, show the line that
failed and stop.

## 4. Report, and offer to clear

The builder, the address (`https://<name>.ddev.site`), what was installed for the trial, and what
was found. Then ask whether to keep the sandbox or remove it:

```bash
bash cmd-tools-remove.sh <name>
```

Never remove unasked. For more than one experiment, hand over to the `sandboxes-site-builder`
agent; the `sandboxes-workflow` skill lists every command of the folder.
25 changes: 25 additions & 0 deletions ai/prompts/sandboxes-try-and-clear.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
Spin up a throwaway site in the sandboxes folder, try one thing on it, report, and clear it.

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 """
Try <what> on a throwaway site named <name> in the sandboxes folder, then clear it
# ~/workspace/sandboxes · https://<name>.ddev.site · container-based (DDEV by default)
# 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 cmd-drupal11-recommended-project.sh --help
tell me the flags it takes
2. bash cmd-drupal11-recommended-project.sh <name> --install --profile minimal
add --require and --enable for the package under trial
3. try <what> in the site's container (ddev composer, ddev drush, in the folder <name>)
tell me what you ran and what it printed
4. bash cmd-tools-testing.sh <name>
bash cmd-tools-testing.sh <name> --run
only if the result is to be proven with Webship-js

Report what was found, in a few lines.
Then ask me whether to keep the sandbox or remove it with: bash cmd-tools-remove.sh <name>
"""
```
Loading
Loading