[roland-d]

This adds a collection for the HTTP Client of PhpStorm and other JetBrains IDEs, generated from src/joomla-ws-api.json. main has the generator, not the generated files: the collection is a release file and is in a phpstorm branch that follows main.

What's included

• scripts/generate-phpstorm.mjs: generates a request for each of the 235 operations in the spec (6.2.0), with one .http file per tag (48 files, for instance banners-categories.http). Request names are the spec summaries, and request bodies are the spec's examples. npm run phpstorm writes the collection to dist/phpstorm/, which git ignores.
• scripts/phpstorm/: the README and environment files of the collection. The generator copies them into the output.
• Release file: npm run build runs the generator and adds joomla-ws-api-<version>-phpstorm.zip to dist/ and to the .sha256. The zip is written in Node with fixed dates, so the same spec always gives the same zip. The release workflow now uploads dist/joomla-ws-api-*, because dist/ also has the phpstorm folder.
• phpstorm branch: the new phpstorm.yml workflow runs on every push to main (and manually from main). It commits the collection to the root of the phpstorm branch when it changed, with a message like "Generated from 6.2.0 (main 9bd9ea4)". The first run creates the branch. It only runs in joomla-projects/API-Endpoints.
• CI: npm run build in CI also runs the generator, so every spec change is checked with it. There are no .http files and no phpstorm:check in main.
• Environments:
  • base_url goes in http-client.env.json, for example https://example.com/api/index.php.
  • The tokens go in http-client.private.env.json, which is git-ignored. An .example file is included.
  • Requests send X-Joomla-Token: {{api_key}}. The Joomla Update operations send X-JUpdate-Token: {{update_token}}, as the spec's security says.
• Path variables are defined at the top of each file. When the spec describes a parameter, that description becomes a comment. For example, content-history DELETE and keep take the ID of the version, not the ID of the item.
• Query parameters (paging and filters) are listed in a comment above each list request.
• Docs: the collection README covers setup and usage. The root README has a "PhpStorm collection" section that points to the release file (since 6.2.1) and the branch.

CHANGELOG.md is unchanged: the spec itself doesn't change.

Verification

• npm run check and npm run build pass locally. The zip is valid and has the same files as dist/phpstorm/.
• The routes in the .http files match the spec's operations one for one (235/235, method and path).
• All request bodies are valid JSON, and every variable used in a file is defined in that file.
• The commit step of the branch workflow was tested against a local repository: the first run created the branch, a run with nothing changed made no commit, and a spec change gave a one-file commit.
• The requests have not been run against a live Joomla site yet.

Compared to the Bruno collection

This collection also covers the routes that the bruno branch doesn't have yet: Joomla Update, Newsfeeds Categories, contact mail fields, several field-group collections, and content history of contacts and articles. Like the spec, it leaves out Guided Tours and DELETE privacy/consents/{id}, which aren't routes of the core web services plugins.

🤖 Generated with Claude Code

[HermanPeeren]

Thanks @roland-d, a generated collection is a good idea: 235 requests that are always in line with the spec.

I'd like to keep main for the spec itself, so that a contributor can improve the spec in GitHub's web editor,
without Node.js. With the generated files in main, every spec change must also contain the regenerated
collection, and each patch release changes all 48 files (the version is in their header).

So my proposal: generate the collection at release time instead of committing it to main.

1. The generator stays in main: scripts/generate-phpstorm.mjs and npm run phpstorm, writing to
   dist/phpstorm/ (git-ignored) instead of phpstorm/. No phpstorm/*.http files in main, and no
   phpstorm:check. npm run build also runs the generator, so CI still checks that it works with every
   change of the spec.
2. Release file: the release workflow zips the collection into joomla-ws-api-<version>-phpstorm.zip and
   adds it to the release, next to the other files (and to the .sha256). It is then always in sync with that
   release and findable with the GitHub API, like the spec.
3. A phpstorm branch, filled by the release workflow: for the latest release it commits the generated
   collection (the .http files, the environment files and phpstorm/README.md) to that branch. People can
   browse or clone it there, and nobody has to keep it up to date by hand.
4. Small points:
   • file names without spaces, for instance banners-categories.http;
   • the root README gets a short section that points to the release file and the phpstorm branch.

Would you like to change your PR in this direction? If you prefer, I can do the release workflow part (2 and 3)
after your change of the generator is merged.

[HermanPeeren]

One change to point 3 of my proposal: the phpstorm branch can follow main instead of the latest release.

• On every push to main, a workflow regenerates the collection and commits it to the phpstorm branch, but only
  when the collection actually changed. The commit message names the spec version and the main commit it was
  generated from, for instance "Generated from 6.2.0 (main 9bd9ea4)".
• The release file joomla-ws-api-<version>-phpstorm.zip stays the fixed collection of each release.

So it works like the spec itself: the release has the released version, and the branch always has the newest one,
also with small improvements that are not released yet. The workflow can create the branch on its first run.

[roland-d]

Thanks @HermanPeeren, good proposal. I've changed the PR this way, including your change that the phpstorm branch follows main:

1. Generator in main: npm run phpstorm writes to dist/phpstorm/, which git ignores. There are no .http files and no phpstorm:check in main anymore. The README and environment files of the collection are now in scripts/phpstorm/, and the generator copies them into the output. npm run build also runs the generator, so CI still checks that it works with every change of the spec.
2. Release file: the build adds joomla-ws-api-<version>-phpstorm.zip to dist/ and to the .sha256. It's zipped in Node with fixed dates, so it needs no zip binary and the same spec always gives the same zip. Because dist/ now also contains the phpstorm folder, the release workflow uploads dist/joomla-ws-api-* instead of dist/*.
3. phpstorm branch: a new phpstorm.yml workflow runs on every push to main and commits the collection to the root of the phpstorm branch, but only when it changed. The commit message looks like "Generated from 6.2.0 (main 9bd9ea4)". The first run creates the branch. The job only runs in joomla-projects/API-Endpoints, because in a fork phpstorm can be the branch of a pull request, like this one.
4. Small points: file names are now like banners-categories.http. The root README has a section that points to the release file and the branch. The collection README uses absolute links, because it ends up in the zip and at the root of the branch.

I tested the branch workflow's commit step against a local repository. The first run created the branch, a run with nothing changed made no commit, and a change to the spec gave a one-file commit. The generated requests are the same as before; only the file names changed.

The 6.2.0 release came out before this change, so it has no zip. The first release with the collection will be the next one.

[HermanPeeren]

Thanks @roland-d, this is what we discussed. A few details:

1. Please update the PR title and description to the new setup (no .http files or phpstorm:check in main).
2. phpstorm.yml: add && github.ref == 'refs/heads/main' to the job's if:, so a manual run from another branch doesn't push to phpstorm.
3. After the merge, I'll release 6.2.1 with the collection. Both READMEs can then say "since 6.2.1" instead of "since the release after 6.2.0".
4. zip() in build.mjs only handles a flat folder: please skip subfolders or fail with a clear message.
5. Collection README: use single backticks for inline code instead of triple ones.

[HermanPeeren]

Thanks @roland-d! The collection is out in release 6.2.1 as joomla-ws-api-6.2.1-phpstorm.zip, and the phpstorm branch now updates on every change of main.