@webship.co/workspace-joomla 0.0.0-stage → 1.0.8

package/ai/skills/joomla-scenarios/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: joomla-scenarios
+description: Write and run webship-js scenarios for a Joomla site of the Webship Workspace with the Joomla step pack (`@webship-js/joomla-steps`) — the phrases of the pack by area (the administrator and its pages, lists and content, users and groups, the public site, the site login, search), the handles of the users registry, and the workspace command that runs them in the site's container. Use when asked to "write a scenario for this Joomla site", "test the manager account", "which step is there for an article", "add a feature for the search", or when a `.feature` file of a Joomla project is being written or fixed.
+argument-hint: '<site> [what to cover]'
+---
+
+# joomla-scenarios
+
+Scenarios for a Joomla site of a Webship Workspace (`~/workspace`, container-based, DDEV by
+default), written from the steps of [`@webship-js/joomla-steps`](https://github.com/webship/joomla-steps)
+and of [webship-js](https://github.com/webship/webship-js) itself, and run in the site's container
+by the workspace's own command. It comes with the Joomla plugin (`@webship.co/workspace-joomla`),
+like the builder (`cmd-joomla-project.sh`), the CLI tool (`cmd-tools-joomla-cli.sh`) and the
+agents `joomla-site-builder` and `joomla-tester`.
+
+## Where everything is
+
+| What | Where |
+| --- | --- |
+| The site | `~/workspace/<folder>/<site>`, at `https://<site>.ddev.site`, the administrator at `/administrator` (`<folder>` is a sites folder: `dev`, `test`, `sandboxes`, `demos`) |
+| The suite's configuration | `<site>/cucumber.js`: the step definitions it loads and the users registry (`worldParameters.users`) |
+| The features | `<site>/tests/features/*.feature` (`site.feature` is the first one the setup wrote) |
+| The pack's steps | `<site>/node_modules/@webship-js/joomla-steps/tests/step-definitions/*.steps.js` |
+| webship-js's steps | `<site>/node_modules/webship-js/tests/step-definitions/*.js` |
+| The reports | `<site>/tests/reports/` |
+
+## The order of work
+
+1. **Make sure the testing stack is there.** From the sites folder:
+   ```bash
+   cd ~/workspace/<folder>
+   bash cmd-tools-testing.sh <site>
+   ```
+   It adds webship-js, the step pack, the users registry and `tests/features/site.feature`, and
+   makes sure the default accounts are on the site. It is safe to run again: it adds what is
+   missing and keeps what was changed.
+2. **Read the installed steps before writing a phrase.** They are the source of truth: the pack
+   moves, and a phrase from memory is a guess.
+   ```bash
+   cd ~/workspace/<folder>/<site>
+   grep -hE "^(Given|When|Then)\(" node_modules/@webship-js/joomla-steps/tests/step-definitions/*.steps.js
+   ```
+   Every step carries a comment block with examples above it; open the file when a phrase is not
+   obvious.
+3. **Look at the page first** (the Playwright MCP browser, a tab of your own) when the scenario
+   is about a page you have not seen. A scenario written without having seen the page asserts
+   what you imagine.
+4. **Write the feature** in `<site>/tests/features/`, from phrases that exist (the lists below).
+5. **Match every step without a browser**, then run the feature, then the suite:
+   ```bash
+   cd ~/workspace/<folder>
+   bash cmd-tools-testing.sh <site> --dry-run --path tests/features/<name>.feature
+   bash cmd-tools-testing.sh <site> --run --path tests/features/<name>.feature
+   bash cmd-tools-testing.sh <site> --run --tags "@critical"
+   bash cmd-tools-testing.sh <site> --run
+   ```
+   A dry run says `Undefined` for a phrase no definition matches: fix the phrase, do not write a
+   step for it.
+
+## Accounts: a handle, never a password
+
+A scenario logs in by a handle of the users registry. The administrator and the site have a
+login each, and a step for each. The default accounts are on the site already
+(`bash cmd-tools-joomla-cli.sh <site> --add-users` adds them again if they were removed):
+
+| Handle | Account | User group | Logs in to |
+| --- | --- | --- | --- |
+| `admin` | `administrator` | Super Users | the administrator and the site |
+| `manager` | `manager` | Manager | the administrator and the site |
+| `editor` | `editor` | Editor | the site |
+| `member` | `member` | Registered | the site |
+
+```gherkin
+Given I am a logged in user with the "manager" user
+Then I should see the administrator dashboard
+Given I am logged in to the site with the "member" user
+Then I should be logged in to the site as "member"
+```
+
+## The phrases, by area
+
+Each line is a phrase the pack defines, and each one passed on a site built with
+`bash cmd-joomla-project.sh <site> --install --add-users --sample-data` (the names in quotes are
+that site's). Most `should` steps also take the negative: `should not see`, `should not be`,
+`should not exist`.
+
+### The administrator: session, pages, menu
+
+```gherkin
+Given I am on the administrator login page
+Given I am a logged in user with the "manager" user
+When I log out of the administrator panel
+Then I should be on the administrator login page
+Then I should see the administrator dashboard
+Then I should be logged in to the administrator panel as "Manager"
+Then I should see the administrator menu
+Then I should see the administrator menu item "Content"
+Then I should not see the administrator menu item "System"
+When I go to the administrator "Articles" page
+Then I should be on the administrator "Articles" page
+Then I should see the administrator page title "Articles"
+Then I should see the "New" toolbar button
+```
+
+### Lists and content
+
+```gherkin
+When I create an article titled "An article written by a scenario" with the text "Written by the suite."
+Then the article "An article written by a scenario" should exist
+Then the article "An article written by a scenario" should be published
+When I unpublish the article "An article written by a scenario"
+When I trash the article "An article written by a scenario"
+Then the article "An article written by a scenario" should be trashed
+When I delete the article "An article written by a scenario" permanently
+When I create a category titled "A category written by a scenario"
+When I trash the category "A category written by a scenario"
+When I delete the category "A category written by a scenario" permanently
+When I create a menu titled "A menu written by a scenario"
+Then the menu "A menu written by a scenario" should exist
+When I delete the menu "A menu written by a scenario"
+When I search the list for "no such article anywhere"
+Then I should see an empty list
+Then I should see a success message
+```
+
+### Users, groups and the system
+
+```gherkin
+Then the user "manager" should exist
+Then the user "manager" should be in the "Manager" group
+Then the access level "Special" should include the "Manager" group
+Then the group "Manager" should have 1 enabled user
+When I clear all caches
+Then there should not be checked out items
+```
+
+### The public site, its login and the search
+
+```gherkin
+Given I am on the login page
+Given I am on the password reset page
+Given I am on the username reminder page
+Given I am on the profile page
+Then I should see the login form
+Then I should see the password reset form
+Then I should see the username reminder form
+Given I am logged in to the site with the "member" user
+When I log out of the site
+Then I should be logged in to the site as "member"
+Then I should not be logged in to the site
+Then I should see the "Blog" menu item
+When I open the "Blog" menu item
+Then the breadcrumb should show "Home > Blog"
+Then I should see no system messages
+When I search the site for a word from the first article
+Then I should see that word in the search results
+Then I should see at least 1 search result
+When I search the site for "nosuchwordanywhere"
+Then I should see no search results
+```
+
+`I am an anonymous user`, `I am on the homepage`, `the page should have a title`,
+`I should see "<text>"` and `the response status code should be 200` are webship-js's own steps;
+its status codes, classes, landmarks and accessibility audits are used as they are and never
+redefined for this platform.
+
+## Traps found on a real site
+
+- **Two logins, two steps.** `I am a logged in user with the "<handle>" user` is the
+  administrator's login, `I am logged in to the site with the "<handle>" user` the site's.
+  `editor` and `member` have no administrator: use the site's step for them.
+- **The administrator shows the account's name, not its username.**
+  `I should be logged in to the administrator panel as "manager"` fails; the header says
+  `Manager`. The site's step (`logged in to the site as "member"`) takes the handle, and the user
+  steps (`the user "manager" should be in the "Manager" group`) take the username.
+- **A page a group may not open answers 403**: a manager on the administrator `"Users"` page.
+  Assert the status code; the administrator menu of a manager does not list `System` either.
+- **The breadcrumb is the whole trail**: `Home > Blog`, not `Blog`.
+- **The search step needs a page that lists articles first.**
+  `I search the site for a word from the first article` reads the word from the page on screen:
+  open the homepage before it.
+- **What the sample data brings is not on every site.** The `Blog` menu item, the articles and
+  the search index are there only when the site was built with `--sample-data`. A site built
+  without it has an empty front page: a scenario about them fails there.
+- **Trashing is not deleting.** A trashed article or category is still on the site:
+  `I delete the article "<title>" permanently` after the trash step, or the next run finds it.
+- **`I check in all items` fails when nothing is checked out.** Assert
+  `there should not be checked out items` instead, and check in only after a scenario left a
+  form open.
+- **Two phrases of the pack name the platform** (the version and the "running" check). They
+  break the rule below: leave them out of a suite, and read the version with
+  `bash cmd-tools-joomla-cli.sh <site>`.
+
+## Rules
+
+- **No account is created in a suite.** No `user:add` in a hook, no registration scenario that
+  leaves an account behind. A group the registry does not have is asked for, not made.
+- **Never the workspace account.** The site's own Super User is not in the registry; `admin` is
+  the `administrator` default account.
+- **No password in a feature file**, except where a wrong password is the subject.
+- **No platform name in a step phrase**: `I am on the administrator login page`, never a phrase
+  that names the platform. The same holds for a custom step.
+- **No selector and no address when a step says it**: `the administrator "Users" page`, not the
+  address of the page.
+- **What a scenario creates, it removes** in the same scenario, under a title nobody else uses.
+- **A custom step is the last resort**: look in the pack and in webship-js first, write it in
+  `<site>/tests/step-definitions/` with a comment block and examples, and say it may belong in
+  the pack.
+- **Everything runs in the container**, through `cmd-tools-testing.sh`. Never `npx cucumber-js`
+  or `npx playwright` on the host.
+- **A failing scenario is a result.** No `@wip`, no longer timeout, no looser assertion to turn a
+  run green: say what the site did.
+
+## Examples that run
+
+`examples/` holds three features that pass on a site built with
+`bash cmd-joomla-project.sh <site> --install --add-users --sample-data`. Copy one into the suite
+and run it:
+
+```bash
+cp ~/workspace/ai-skills/joomla-scenarios/examples/groups-and-pages.feature ~/workspace/<folder>/<site>/tests/features/
+cd ~/workspace/<folder>
+bash cmd-tools-testing.sh <site> --run --path tests/features/groups-and-pages.feature
+```
+
+| Feature | What it shows |
+| --- | --- |
+| `examples/groups-and-pages.feature` | Each default account logging in where its group may, the menu and the pages of a manager, the groups and access levels |
+| `examples/article-lifecycle.feature` | A manager writing, unpublishing, trashing and deleting an article; a category and a menu added and deleted |
+| `examples/site-and-search.feature` | The menu, the breadcrumb, the account pages and the search of the public site (needs `--sample-data`) |

package/ai/skills/joomla-scenarios/examples/article-lifecycle.feature

@@ -0,0 +1,36 @@
+Feature: A manager writes an article and removes it again
+  As a manager
+  I want to write, unpublish, trash and delete an article
+  So that the suite proves the content screens work and leaves the site as it found it
+
+  # Trashing is not deleting: the scenario deletes permanently, or the next run finds the item.
+
+  Scenario: The manager writes an article, takes it down and deletes it
+    Given I am a logged in user with the "manager" user
+    When I create an article titled "An article written by a scenario" with the text "This article is written and removed by the suite."
+    Then I should see a success message
+    And the article "An article written by a scenario" should be published
+    When I unpublish the article "An article written by a scenario"
+    Then the article "An article written by a scenario" should be unpublished
+    When I trash the article "An article written by a scenario"
+    Then the article "An article written by a scenario" should be trashed
+    When I delete the article "An article written by a scenario" permanently
+    Then the article "An article written by a scenario" should not exist
+
+  Scenario: An administrator adds a category and a menu and deletes them
+    Given I am a logged in user with the "admin" user
+    When I create a category titled "A category written by a scenario"
+    Then the category "A category written by a scenario" should exist
+    When I trash the category "A category written by a scenario"
+    And I delete the category "A category written by a scenario" permanently
+    Then the category "A category written by a scenario" should not exist
+    When I create a menu titled "A menu written by a scenario"
+    Then the menu "A menu written by a scenario" should exist
+    When I delete the menu "A menu written by a scenario"
+    Then the menu "A menu written by a scenario" should not exist
+
+  Scenario: A search of the list that finds nothing shows an empty list
+    Given I am a logged in user with the "manager" user
+    When I go to the administrator "Articles" page
+    And I search the list for "no such article anywhere"
+    Then I should see an empty list

package/ai/skills/joomla-scenarios/examples/groups-and-pages.feature

@@ -0,0 +1,41 @@
+Feature: Each account reaches what its user group may use
+  As the owner of the site
+  I want every default account to log in where its group may and to be refused the rest
+  So that a change of permissions is caught by the suite
+
+  # The accounts are the default ones; a scenario logs in by a handle of the users registry.
+  # The administrator and the site have a login each, and a step for each.
+
+  Scenario: A manager gets the administrator, with the menu of a manager
+    Given I am a logged in user with the "manager" user
+    Then I should see the administrator dashboard
+    And I should be logged in to the administrator panel as "Manager"
+    And I should see the administrator menu item "Content"
+    And I should not see the administrator menu item "System"
+
+  Scenario: A manager opens the articles and is refused the users
+    Given I am a logged in user with the "manager" user
+    When I go to the administrator "Articles" page
+    Then the response status code should be 200
+    And I should see the "New" toolbar button
+    When I go to the administrator "Users" page
+    Then the response status code should be 403
+
+  Scenario: An editor logs in to the site and has no administrator
+    Given I am logged in to the site with the "editor" user
+    Then I should be logged in to the site as "editor"
+    Given I am on the administrator login page
+    Then I should not see the administrator dashboard
+
+  Scenario: The groups and the access levels are the ones the accounts rely on
+    Given I am a logged in user with the "admin" user
+    Then the user "manager" should be in the "Manager" group
+    And the user "member" should not be in the "Manager" group
+    And the access level "Special" should include the "Manager" group
+    And the group "Manager" should have 1 enabled user
+
+  Scenario: A visitor is asked to log in before the profile
+    Given I am not logged in
+    And I am on the profile page
+    Then I should see the login form
+    And I should not be logged in to the site

package/ai/skills/joomla-scenarios/examples/site-and-search.feature

@@ -0,0 +1,33 @@
+Feature: A visitor finds their way around the site
+  As a visitor
+  I want the menu, the breadcrumb, the account pages and the search to work
+  So that a broken template or search index is caught by the suite
+
+  # For a site built with --sample-data: the "Blog" menu item, the articles and the search index
+  # come from the blog sample data. On a site built without it these scenarios fail.
+
+  Scenario: The menu leads to the blog, and the breadcrumb says where
+    Given I am an anonymous user
+    And I am on the homepage
+    Then the response status code should be 200
+    And I should see the "Blog" menu item
+    And I should see no system messages
+    When I open the "Blog" menu item
+    Then the breadcrumb should show "Home > Blog"
+
+  Scenario: The account pages are served with their forms
+    Given I am on the login page
+    Then I should see the login form
+    Given I am on the password reset page
+    Then I should see the password reset form
+    Given I am on the username reminder page
+    Then I should see the username reminder form
+
+  Scenario: The search finds a word of an article, and nothing for a word nobody wrote
+    Given I am an anonymous user
+    And I am on the homepage
+    When I search the site for a word from the first article
+    Then I should see that word in the search results
+    And I should see at least 1 search result
+    When I search the site for "nosuchwordanywhere"
+    Then I should see no search results

package/commands/cmd-joomla-project.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+
+# workspace-name: Joomla (latest)
+
+# Installed by the Joomla plugin (plugins.sh --install joomla); __WORKSPACE__ is the workspace it was installed into.
+#
+# Build a Joomla site in a container: the latest stable release, or the one --version names, at
+# https://<name>.ddev.site. With --install the site is installed with the workspace account as its
+# Super User; with --add-users it also gets the default accounts, one per user group.
+
+# Bootstrap.
+# Find the workspace tooling from this script, so a fresh clone needs no setup.
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
+source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
+
+# Load workspace settings.
+eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.__WORKSPACE__.settings.yml);
+
+# Set site version.
+site_version="latest";
+
+# Distribution.
+distribution_name="joomla";
+distribution_title="Joomla";
+distribution_webroot="public";
+
+ARGPARSE_DESCRIPTION="Build a ${distribution_title} project in __WORKSPACE__"
+# The args file comes with the plugin: core/scripts/plugins/joomla/ is where plugins.sh --install puts it.
+source ${WORKSPACE_SCRIPTS}/plugins/joomla/args/arg-joomla.sh || exit 1 ;
+
+shift $#;
+
+joomla_build ;

package/commands/cmd-tools-joomla-cli.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+# Installed by the Joomla plugin (plugins.sh --install joomla); __WORKSPACE__ is the workspace it was installed into.
+#
+# The Joomla CLI (cli/joomla.php) for one Joomla project of this workspace, in its container: say
+# what the site is, run a CLI command, update the core, look for updates, add or remove the default
+# accounts. Nothing here runs on the host.
+
+# Bootstrap.
+# Find the workspace tooling from this script, so a fresh clone needs no setup.
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
+source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
+
+# Load workspace settings.
+eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.__WORKSPACE__.settings.yml);
+
+# Distribution.
+distribution_name="joomla";
+
+ARGPARSE_DESCRIPTION="Run the Joomla CLI on a Joomla project of __WORKSPACE__: status, a command, updates, the default accounts"
+# The args file comes with the plugin: core/scripts/plugins/joomla/ is where plugins.sh --install puts it.
+source ${WORKSPACE_SCRIPTS}/plugins/joomla/args/arg-joomla-cli.sh || exit 1 ;
+
+shift $#;
+
+joomla_cli_tool ;

package/dist/src/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Joomla for Webship Workspace: a platform plugin.
+ *
+ * What the package carries is placed by the installer from the manifest: the builder and the
+ * Joomla CLI tool in the sites folders, their functions and argparse under core/scripts/plugins/joomla/,
+ * its AI items (ai/ in this package) in the folder of their kind:
+ * the agents in AI Agents, the skill in AI Skills, the command in AI Commands, the prompt in AI Prompts.
+ * The dashboard needs nothing drawn for it: the builder is in the
+ * Build list because it is a cmd-*-project.sh, the row menus are the core's, the AI items are listed
+ * like any other. What register() adds is what the assistant is told.
+ *
+ * Everything the dashboard is asked for goes through `api`; this package requires nothing from the
+ * dashboard's own files, so it can be installed from npm and removed without a trace.
+ */
+import type { PluginApi } from '@webship.co/workspace-plugin-api';
+/** The plugin's name, which its functions and its user list are named after. */
+export declare const PLATFORM = "joomla";
+/** The commands the installer places in every sites folder. */
+export declare const COMMANDS: string[];
+/** The agents the installer places in the AI Agents folder. */
+export declare const AGENTS: string[];
+/** The skill the installer places in the AI Skills folder (a folder each, with its SKILL.md). */
+export declare const SKILLS: string[];
+/** The slash command the installer places in the AI Commands folder. */
+export declare const AI_COMMANDS: string[];
+/** The prompt the installer places in the AI Prompts folder: each a whole launch command for a new session. */
+export declare const PROMPTS: string[];
+/** What the assistant is told about Joomla in this workspace. */
+export declare function assistantContext(): string;
+export declare function register(api: PluginApi): void;

package/dist/src/index.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Joomla for Webship Workspace: a platform plugin.
+ *
+ * What the package carries is placed by the installer from the manifest: the builder and the
+ * Joomla CLI tool in the sites folders, their functions and argparse under core/scripts/plugins/joomla/,
+ * its AI items (ai/ in this package) in the folder of their kind:
+ * the agents in AI Agents, the skill in AI Skills, the command in AI Commands, the prompt in AI Prompts.
+ * The dashboard needs nothing drawn for it: the builder is in the
+ * Build list because it is a cmd-*-project.sh, the row menus are the core's, the AI items are listed
+ * like any other. What register() adds is what the assistant is told.
+ *
+ * Everything the dashboard is asked for goes through `api`; this package requires nothing from the
+ * dashboard's own files, so it can be installed from npm and removed without a trace.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPTS = exports.AI_COMMANDS = exports.SKILLS = exports.AGENTS = exports.COMMANDS = exports.PLATFORM = void 0;
+exports.assistantContext = assistantContext;
+exports.register = register;
+/** The plugin's name, which its functions and its user list are named after. */
+exports.PLATFORM = 'joomla';
+/** The commands the installer places in every sites folder. */
+exports.COMMANDS = ['cmd-joomla-project.sh', 'cmd-tools-joomla-cli.sh'];
+/** The agents the installer places in the AI Agents folder. */
+exports.AGENTS = ['joomla-site-builder', 'joomla-tester'];
+/** The skill the installer places in the AI Skills folder (a folder each, with its SKILL.md). */
+exports.SKILLS = ['joomla-scenarios'];
+/** The slash command the installer places in the AI Commands folder. */
+exports.AI_COMMANDS = ['joomla-test'];
+/** The prompt the installer places in the AI Prompts folder: each a whole launch command for a new session. */
+exports.PROMPTS = ['joomla-build-and-test'];
+/** What the assistant is told about Joomla in this workspace. */
+function assistantContext() {
+    return [
+        'Joomla (a plugin, @webship.co/workspace-joomla): a Joomla site is built with',
+        '`bash cmd-joomla-project.sh <name> --install --add-users` from a sites folder (dev, test, sandboxes, demos),',
+        'in a container like every other project, at https://<name>.ddev.site (the administrator at /administrator).',
+        '`bash cmd-tools-joomla-cli.sh <name>` says what the site is; `--run "<command>"` runs the Joomla CLI (cli/joomla.php) in it,',
+        '`--update` updates the core, `--check` looks for updates, `--add-users` adds the default accounts (one per user group).',
+        '`bash cmd-tools-add-users.sh <name> joomla` adds the same accounts.',
+        '`bash cmd-tools-testing.sh <name>` sets up webship-js with the Joomla step pack; `--run` runs the suite.',
+        `For Joomla work, hand over to the agents ${exports.AGENTS.map((a) => `\`${a}\``).join(' and ')}.`,
+        `The plugin also places the skill ${exports.SKILLS.map((a) => `\`${a}\``).join(', ')} (the step pack's phrases, by area) in ai-skills/,`,
+        `the command ${exports.AI_COMMANDS.map((a) => `\`/${a} <site>\``).join(', ')} in ai-commands/ and the prompt ${exports.PROMPTS.map((a) => `\`${a}\``).join(' and ')} in ai-prompts/.`,
+        'Never run php, composer, npm or mysql on the host for a project.',
+    ].join(' ');
+}
+function register(api) {
+    api.addAssistantContext(assistantContext);
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAuBH,4CAcC;AAED,4BAEC;AArCD,gFAAgF;AACnE,QAAA,QAAQ,GAAG,QAAQ,CAAC;AAEjC,+DAA+D;AAClD,QAAA,QAAQ,GAAG,CAAC,uBAAuB,EAAE,yBAAyB,CAAC,CAAC;AAE7E,+DAA+D;AAClD,QAAA,MAAM,GAAG,CAAC,qBAAqB,EAAE,eAAe,CAAC,CAAC;AAE/D,iGAAiG;AACpF,QAAA,MAAM,GAAG,CAAC,kBAAkB,CAAC,CAAC;AAE3C,wEAAwE;AAC3D,QAAA,WAAW,GAAG,CAAC,aAAa,CAAC,CAAC;AAE3C,+GAA+G;AAClG,QAAA,OAAO,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAEjD,iEAAiE;AACjE,SAAgB,gBAAgB;IAC9B,OAAO;QACL,8EAA8E;QAC9E,8GAA8G;QAC9G,6GAA6G;QAC7G,8HAA8H;QAC9H,yHAAyH;QACzH,qEAAqE;QACrE,0GAA0G;QAC1G,4CAA4C,cAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG;QAC1F,oCAAoC,cAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,oDAAoD;QAChI,eAAe,mBAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,mCAAmC,eAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB;QACrK,kEAAkE;KACnE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAED,SAAgB,QAAQ,CAAC,GAAc;IACrC,GAAG,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;AAC5C,CAAC"}

package/docs/plugin-items-pattern.md

@@ -0,0 +1,150 @@
+# A plugin carries its own items
+
+Every `@webship.co/workspace-<name>` plugin manages what belongs to it: its `cmd-*.sh` commands and
+its AI items (agents, skills, commands, prompts). The package holds them, the manifest names them,
+and `plugins.sh --install <name>` lists each one in the workspace folder of its kind, when that
+folder is an active workspace folder. `--uninstall` takes them away again. The reference is
+[`@webship.co/workspace-wordpress`](https://github.com/webship/workspace-wordpress), and this plugin
+follows it; below, `<p>` is the plugin's name.
+
+## The layout
+
+```text
+commands/cmd-<p>-project.sh            cmd-*.sh scripts only: builders and tools, placed in workspace folders
+commands/cmd-tools-<p>-cli.sh
+ai/agents/<p>-<role>.md                one file per agent
+ai/skills/<p>-<topic>/SKILL.md         one folder per skill; every file in it is placed (examples/, references/)
+ai/commands/<p>-<verb>.md              one file per slash command
+ai/prompts/<p>-<task>.md               one file per prompt
+tests/items.test.ts                    the shape of every item, and that it names nothing that does not exist
+tests/fixtures/step-definitions.txt    the step definitions the items' phrases are checked against (a plugin with a step pack)
+```
+
+`commands/` is taken by the `cmd-*.sh` scripts, so the AI items live under `ai/`, one folder per
+kind, named like the manifest's `ai` keys. The installer places an item by the last part of its
+path, whatever folder the package keeps it in, so a plugin that kept its agents in `agents/` moves
+them with `git mv agents ai/agents` and changes two lines of its manifest.
+
+## The manifest
+
+```json
+"files": ["dist/src", "ai", "commands", "docs", "features", "scripts", "testing", "README.md"],
+"workspacePlugin": {
+  "name": "<p>",
+  "needs": [["dev", "test", "sandboxes", "demos"], "ai-agents", "ai-skills", "ai-commands", "ai-prompts"],
+  "commands": { "types": ["sites"], "workspaces": ["dev", "test", "sandboxes", "demos"],
+                "files": ["commands/cmd-<p>-project.sh", "commands/cmd-tools-<p>-cli.sh"] },
+  "ai": {
+    "agents":   ["ai/agents/<p>-site-builder.md", "ai/agents/<p>-tester.md"],
+    "skills":   ["ai/skills/<p>-scenarios"],
+    "commands": ["ai/commands/<p>-test.md"],
+    "prompts":  ["ai/prompts/<p>-build-and-test.md"]
+  }
+}
+```
+
+- `ai` is in `files`, or the items are not in the published package.
+- A skill is named by its folder, with no `/SKILL.md` and no trailing slash.
+- `needs` names the folder of every kind the plugin ships, after the folder its commands need. A
+  plugin with no `cmd-*.sh` for a sites folder leaves the first entry out; a kind it does not ship
+  is left out of `ai` and of `needs`.
+
+| Kind | Lands in | Claude Code reads it from |
+| --- | --- | --- |
+| `commands.files` | every active folder `commands.workspaces` names, else every active folder of `commands.types` | the folder itself: `bash cmd-….sh` |
+| `ai.agents` | `ai-agents/<name>.md` | `~/.claude/agents`, after Install |
+| `ai.skills` | `ai-skills/<name>/` | `~/.claude/skills`, after Install |
+| `ai.commands` | `ai-commands/<name>.md` | `~/.claude/commands`, after Install: `/<name>` |
+| `ai.prompts` | `ai-prompts/<name>.md` | nothing: the New screen form lists it as a template for a new session |
+
+## The shape of each kind
+
+| Kind | Shape |
+| --- | --- |
+| Agent | Frontmatter `name` (the file's name), `description` (when to use it, with the phrases a person says), `model: fable`, `tools`; then what it does, the commands it runs, its rules |
+| Skill | `SKILL.md` with frontmatter `name` (the folder's name) and `description` (what it does, then `Use when …`); files beside it for what is too long or is meant to be copied |
+| Command | Frontmatter `description` and `argument-hint`, no `name` (the file names it); the body reads what was typed from `$ARGUMENTS` |
+| Prompt | No frontmatter. One sentence that says what it is for, then a fenced block holding the whole launch command: `claude --permission-mode bypassPermissions """` … `"""`, with `<placeholders>` to fill in and a `#` line that says where it runs |
+
+Names start with the plugin's name (`<p>-…`): an item that is already in the folder under the same
+name is kept, so a name another plugin could also choose would never be placed. A command and a
+prompt never share a name: both end in `~/.claude/commands`.
+
+## What an item may say
+
+Nothing generic and nothing invented. An item is about what this plugin does in the workspace, and
+every command, flag, path and step phrase in it exists:
+
+- commands and flags: the plugin's own (`scripts/args/*.sh`) and the workspace's (`cmd-tools-testing.sh`
+  and its flags, `cmd-tools-remove.sh`, `cmd-tools-clone.sh --to`, `cmd-tools-ai-items.sh --install`);
+- step phrases: the plugin's step pack and webship-js, as installed in a real project;
+- the body is for any AI CLI, Claude Code being the default shape: plain Markdown ("run this
+  command", "read this file", "the AI assistant") that names no tool or feature of one CLI; the
+  frontmatter and a prompt's `claude …` launch line stay, with one line saying that the text between
+  the quotes can be given to another AI CLI as it is; a command keeps `$ARGUMENTS` and says in
+  words what the arguments are;
+- the workspace is container-based (DDEV by default); no platform name in a step phrase; no
+  account created by a scenario; no password, no personal path, addresses at `example.com`.
+
+Run every command an item tells its reader to run, and every scenario it shows, on a real site
+before it is pushed. Two of the three example features of the reference failed on their first real
+run, each on a phrase that exists and matched in a dry run.
+
+## The tests to copy
+
+`tests/items.test.ts` checks, with no site and no network:
+
+1. the manifest: one list per kind, each item under `ai/<kind>/`, in the package, named `<p>-…`,
+   `ai` in `files`, the folder of each kind in `needs`, no command and prompt of the same name;
+2. the shape of each kind (the table above; the two expressions the dashboard reads a prompt with);
+3. every `cmd-*.sh` an item names is the plugin's or the workspace's, with flags that exist;
+4. every step in a `gherkin` block or a `.feature` file matches a definition in
+   `tests/fixtures/step-definitions.txt`, names no platform and carries no password;
+5. the words: container-based, no personal value, the README lists every item.
+
+Refresh the fixture from a project whose testing stack is set up, whenever the pack's release
+line changes (`<pack>` is the plugin's step pack):
+
+```bash
+cd ~/workspace/<folder>/<site>
+{ echo "# <pack> <version> and webship-js <version>" ;
+  grep -hE "^(Given|When|Then)\(/" node_modules/<pack>/tests/step-definitions/*.steps.js node_modules/webship-js/tests/step-definitions/*.steps.js \
+    | sed -nE 's/^(Given|When|Then)\(\/(.*)\/, (\{[^}]*\}, )?(async )?function.*/\2/p' | sort -u ; } > step-definitions.txt
+```
+
+`tests/needs.test.ts` holds the exact `needs` list, and `tests/plugin.test.ts` that every file the
+manifest names ships.
+
+## Prove it on a fresh workspace
+
+Never in a workspace somebody works in. `webship-workspace init <folder>` makes an empty one.
+
+```bash
+npm pack                                                                 # in the plugin: the tarball of the branch
+cd <the fresh workspace>
+bash core/scripts/plugins.sh --require <path>/webship.co-workspace-<p>-<version>.tgz   # says what it needs
+bash core/scripts/plugins.sh --activate <p>                              # stops: lists what is not here, changes nothing
+bash core/scripts/plugins.sh --activate <p> --with-needs                 # adds the folders, then activates
+bash core/scripts/plugins.sh --install <p>                               # "placed …" once per file
+ls dev ai-agents ai-skills ai-commands ai-prompts                        # each item in its folder
+bash core/scripts/plugins.sh --list                                      # needs: … met by …
+bash core/scripts/plugins.sh --uninstall <p>                             # "removed …" once per file
+grep -c "<p>" core/config/plugins.installed.yml                          # 0: the record is gone
+```
+
+Then, installed again: build one site with the builder, run each command the items name, copy the
+skill's examples into the suite and run them, look at the four AI folders on the dashboard, and
+remove the site with `cmd-tools-remove.sh`.
+
+## What was found on the way
+
+- A phrase that matches in a dry run can still fail: a step may need another one before it
+  (`I should see the page title` needs `Given I am on a page`), or assert something the site does
+  not do as built. Only a real run tells.
+- Content a failed scenario created stays on the site. Name it so it is found, and remove it
+  through the CLI tool before the next run (an entry in the trash is not in a list of every status).
+- A folder that is not active gets nothing: the install says `skipped <n> <kind>` for it, and
+  places the items when the folder is added. With the folder in `needs`, `--activate` and
+  `--install` stop before that and offer to add it.
+- An item a person edited in its folder is kept by `--install` and by `--uninstall`: the record
+  holds the hash of what was placed.