@tmorin/plantuml-libs 18.1.4 → 18.2.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [18.2.0](https://github.com/tmorin/plantuml-libs/compare/v18.1.4...v18.2.0) (2026-08-01)
+
+
+### Features
+
+* **eip:** refresh the package ([b880bcb](https://github.com/tmorin/plantuml-libs/commit/b880bcb4898d485e54e2166e5772eb93c9278569))
+* **eip:** refresh the package ([f613242](https://github.com/tmorin/plantuml-libs/commit/f6132426064db47a86ff70b748fe111df82007ca))
+* **eip:** refresh the package ([2c75adf](https://github.com/tmorin/plantuml-libs/commit/2c75adfcb6045acb029f5db4b2025ea1c0a45774))
+
+
+### Bug Fixes
+
+* **generator:** resolve TypeScript errors surfaced by TS 6.0.3 ([a0085a2](https://github.com/tmorin/plantuml-libs/commit/a0085a23fcc164e49626f59482eb5575b0b0e331))
+* **test:** stabilize resolver tests ([5fc952b](https://github.com/tmorin/plantuml-libs/commit/5fc952b6e35a851d49d213612dbd80aaa11707b0))
+
 ### [18.1.4](https://github.com/tmorin/plantuml-libs/compare/v18.1.3...v18.1.4) (2026-04-11)
 
 

package/CLAUDE.md

@@ -0,0 +1,66 @@
+# CLAUDE.md
+
+Guidance for Claude Code when working in this repository.
+
+## Project
+
+`@tmorin/plantuml-libs` — generates PlantUML sprite/icon libraries (AWS, Azure, C4, EIP, Font Awesome, GCP, Material, Simple Icons, etc.) and their documentation website. Node.js CLI entry point: `bin/gdiag.js`.
+
+## Stack
+
+- TypeScript, run via `ts-node`, `moduleResolution: Node`. Source uses ESM `import` syntax but the package has no `"type": "module"` and `bin/gdiag.js` uses `require()` — this is CommonJS, not ESM, despite the import syntax.
+- Node.js >=24 <25 (see `engines` in package.json)
+- Mocha + `assert.strict` for tests
+- ESLint flat config (`eslint.config.mjs`) + Prettier (no semicolons, double quotes)
+
+Check `package.json` for exact dependency versions rather than assuming.
+
+## Architecture: Library vs Generator
+
+- `source/library/` — one factory per technology package (`source/library/packages/{name}/index.ts`), each producing raw PlantUML sprite/icon resources. Packages are independent but follow shared patterns.
+- `source/generator/workdir/` — orchestrates all library packages into a single `.workdir/library.yaml` manifest plus supporting assets. Run: `npm run generate:workdir`
+- `source/generator/website/` — ETL pipeline (Extract → Transform → Load) that turns `.workdir/library.yaml` into the documentation site and `distribution/` output. Each stage implements the generic `Stage<I, O>` interface (`source/generator/website/stage.ts`).
+- Full build: `scripts/generate-library.sh` chains workdir → website → distribution/. Requires Podman/Docker and the `plantuml-generator` image.
+- Single-package build: `scripts/generate-package.sh <package>` (invoked via `npm run generate:package -- -p <package>`) regenerates the workdir then builds just that one package through Podman.
+
+## Code Conventions
+
+- Classes: private constructor + static factory, e.g. `static create(...): X`
+- Import aliases for common modules: `import P from "path"`, `import Fe from "fs-extra"`, `import U from "util"`
+- Import order: stdlib → external packages → local modules, no blank lines between groups
+- `readonly` for immutable class properties; interfaces declared inline near their implementation
+- async/await throughout, no callbacks or `.then()` chains
+
+## Testing
+
+- Files: `test/*.spec.js` / `test/*.spec.mjs`, run with `npm test`
+- Run one file: `npm test -- test/gdiag.spec.js`
+- Run by pattern: `npm test -- --grep "gdiag"`
+- Test functions must be `async function` (not arrows) to access `this.timeout(...)`
+- AWS/Azure spec files make real network requests — expect them to be slow
+- Clean temp state in `beforeEach()`; use `.tmp/` for scratch output
+
+## Commands
+
+```bash
+npm run generate:workdir            # library packages -> .workdir/library.yaml
+npm run generate:website            # runs the website ETL stages
+npm run generate:package -- -p aws  # regenerate + build a single package (needs Podman)
+scripts/generate-library.sh         # full build: workdir -> website -> distribution/ (needs Podman/Docker)
+npm test                            # mocha
+npm run lint                        # eslint . (bin/**, test/**, .workdir/**, distribution/** ignored)
+```
+
+## Versioning & Commits
+
+- Semantic Versioning via `standard-version` (`npm run release`)
+- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/): `type(scope): description` — common types `feat`, `fix`, `refactor`, `chore`, `docs`, `test`
+- Pre-releases: `npm run alpha` (`--prerelease alpha`)
+
+## Package Upgrades
+
+Upgrading an icon/shape package (AWS, Azure, EIP, Font Awesome, GCP, Material, Simple Icons) or npm dependencies has a dedicated skill under `.claude/skills/` for each package (e.g. `aws-package-upgrading`, `npm-dependency-management`) — use those rather than improvising the process.
+
+## When in Doubt
+
+Match existing patterns in the surrounding file over generic best practices — this codebase has consistent, if unconventional, house style (no semicolons, aliased imports, factory-pattern classes).

package/bin/gdiag.js

@@ -3,12 +3,15 @@
 const P = require("path")
 const F = require("fs")
 const CP = require("child_process")
-const fetch = require("node-fetch")
+const fetchModule = require("node-fetch")
+const fetch = fetchModule.default ?? fetchModule
 const moment = require("moment")
 const glob = require("glob")
 
 function getArgs() {
-  return require("yargs")
+  const { hideBin } = require("yargs/helpers")
+  const yargs = require("yargs/yargs")
+  return yargs(hideBin(process.argv))
     .scriptName("gdiag")
     .env("GDIAG_")
     .option("work-directory", {

package/doc/howto.upgrade-eip-package.md

@@ -74,8 +74,10 @@ npm run generate:workdir -- -p eip
 
 Check the output:
 - `.workdir/library.yaml` should list the `eip` package with correct modules and examples
-- `.workdir/.cache/eip` should contain all expected shape modules
-- Verify the number of items against the previous version (changes indicate new/updated shapes)
+- Verify the total number of items: expected ~61 items across 7 modules
+  - `MessageConstruction`, `MessageRouting`, `MessageTransformation`
+  - `MessagingChannels`, `MessagingEndpoints`, `MessagingSystems`, `SystemManagement`
+- Changes in item count indicate new/updated shapes from the upstream repository
 
 ### 5. Commit and push the branch
 
@@ -99,26 +101,16 @@ git push -u origin feat/upgrade-eip-icons
 
 ### 6. Trigger the Package Builder pipeline
 
-**Primary (MCP)**: Use `github-mcp-server-create_dispatch_event` or similar to trigger the workflow
-```
-create_dispatch_event(owner="tmorin", repo="plantuml-libs", event_type="package-builder", 
-  client_payload={"pkgName": "eip", "pkgVersion": "latest", "branch": "feat/upgrade-eip-icons"})
-```
-
-Alternatively, use the MCP workflow trigger method (check your MCP server's available tools):
-```
-trigger_workflow(owner="tmorin", repo="plantuml-libs", workflow_id="package-builder.yaml",
-  inputs={"pkgName": "eip", "pkgVersion": "latest"}, ref="feat/upgrade-eip-icons")
-```
-
-**Fallback (CLI)**:
+**Primary (CLI)** (replace `<branch-name>` with your actual branch, e.g. `feat/upgrade-eip-icons`):
 ```bash
 gh workflow run package-builder.yaml \
   -f pkgName=eip \
-  -f pkgVersion=latest \
-  --ref feat/upgrade-eip-icons
+  --ref <branch-name>
 ```
 
+**Manual fallback** (if the CLI returns a 403 or permission error):
+Go to the [Package Builder workflow](https://github.com/tmorin/plantuml-libs/actions/workflows/package-builder.yaml) in the GitHub Actions tab, click **Run workflow**, select your branch, and set `pkgName` to `eip`.
+
 The pipeline will:
 1. Generate the work directory
 2. Render all PlantUML diagrams and examples
@@ -130,9 +122,6 @@ Processing typically takes several minutes. Monitor the run at the GitHub Action
 
 Once the pipeline completes, pull the generated files:
 
-**Primary (MCP)**: Use `github-mcp-server-get_commit` to verify changes and pull
-
-**Fallback (CLI)**:
 ```bash
 git pull origin feat/upgrade-eip-icons
 ```
@@ -146,9 +135,9 @@ ls -la distribution/eip/
 ```
 
 Verify:
-- `distribution/eip/Item/` - all shapes render correctly as PlantUML files
-- `distribution/eip/Group/` - all groups are properly styled
-- `distribution/eip/README.md` - auto-generated with updated shape counts
+- `distribution/eip/MessageConstruction/`, `distribution/eip/MessageRouting/`, etc. - all shapes render correctly as PlantUML files
+- Each item has `.puml`, `.Local.puml`, `.Remote.puml`, `.png`, `.Local.png`, `.md`, and Group variants
+- `distribution/eip/README.md` - auto-generated with updated shape counts and module list
 
 ### 9. Create a pull request
 
@@ -220,4 +209,24 @@ Then re-run the pipeline.
 
 ---
 
+## Lessons Learned
+
+### Workflow Trigger Permissions
+
+The Package Builder pipeline uses `workflow_dispatch` which requires the `workflows` scope on the GitHub token. The Copilot agent's token may not have this permission, causing `gh workflow run` to return a 403 error. In that case, the repository maintainer must trigger the pipeline manually via the GitHub Actions UI.
+
+### Workdir Validation is the Key Local Check
+
+Running `npm run generate:workdir -- -p eip` is the best local validation. It downloads the upstream shapes, applies the discovery logic, and writes `library.yaml`. Verifying the item counts (expected ~61 items across 7 modules) before pushing gives confidence that the source code is correct.
+
+### Additional Icons Override Upstream Shapes
+
+The `source/library/packages/eip/icons/` directory contains hand-crafted SVG files that complement the upstream shapes. The `unifyItems()` call merges additional icons (priority) with upstream shapes, so local icons take precedence when both have the same URN.
+
+### No `.workdir/.cache` Directory
+
+Unlike some packages, the EIP workdir does not create a `.cache` directory. Generated artifacts are stored in `.workdir/.tmp/eip/` during the run and only `library.yaml` and `source/` are persisted for the pipeline.
+
+---
+
 This guide keeps maintenance changes small, reviewable, and focused. Always validate locally before pushing to remote.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmorin/plantuml-libs",
-  "version": "18.1.4",
+  "version": "18.2.0",
   "description": "A set of resources for [PlantUML](https://plantuml.com) to define diagrams for AWS, Azure, EIP ...",
   "license": "MIT",
   "engines": {
@@ -53,39 +53,44 @@
     "test": "mocha"
   },
   "devDependencies": {
-    "@eslint/eslintrc": "^3.1.0",
-    "@types/extract-zip": "^2.0.1",
-    "@types/fs-extra": "^11.0.1",
-    "@types/html-minifier-terser": "^7.0.0",
-    "@types/lodash": "^4.14.176",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^10.0.1",
+    "@types/extract-zip": "^2.0.3",
+    "@types/fs-extra": "^11.0.4",
+    "@types/html-minifier-terser": "^7.0.2",
+    "@types/lodash": "^4.17.24",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^24.12.2",
+    "@types/node": "^25.9.1",
     "@types/node-fetch": "^2.6.13",
     "@types/yaml": "^1.9.7",
-    "@types/yargs": "^17.0.5",
-    "@typescript-eslint/eslint-plugin": "^8.7.0",
-    "@typescript-eslint/parser": "^8.7.0",
-    "cheerio": "^1.1.2",
-    "csv-parse": "^5.0.4",
-    "eslint": "^9.11.1",
+    "@types/yargs": "^17.0.35",
+    "@typescript-eslint/eslint-plugin": "^8.60.0",
+    "@typescript-eslint/parser": "^8.60.0",
+    "cheerio": "^1.2.0",
+    "csv-parse": "^6.2.1",
+    "eslint": "^10.4.1",
     "extract-zip": "^2.0.1",
-    "fs-extra": "^11.1.1",
-    "html-minifier-terser": "^7.0.0",
-    "lodash": "^4.17.21",
-    "marked": "^15.0.6",
-    "marked-gfm-heading-id": "^4.1.0",
-    "marked-mangle": "^1.0.1",
-    "mocha": "^11.7.5",
-    "node-fetch": "^2.7.0",
-    "prettier": "^3.0.3",
-    "standard-version": "^9.3.2",
-    "ts-node": "^10.4.0",
-    "typescript": "^5.0.3",
-    "yaml": "^2.1.1"
+    "fs-extra": "^11.3.5",
+    "html-minifier-terser": "^7.2.0",
+    "lodash": "^4.18.1",
+    "marked": "^18.0.4",
+    "marked-gfm-heading-id": "^4.1.4",
+    "marked-mangle": "^1.1.13",
+    "mocha": "^11.7.6",
+    "node-fetch": "^3.3.2",
+    "prettier": "^3.8.3",
+    "standard-version": "^9.5.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.3",
+    "yaml": "^2.9.0"
   },
   "dependencies": {
-    "glob": "^11.0.0",
-    "moment": "^2.29.1",
-    "yargs": "^17.2.1"
+    "glob": "^13.0.6",
+    "moment": "^2.30.1",
+    "yargs": "^18.0.0"
+  },
+  "overrides": {
+    "diff": "^8.0.3",
+    "serialize-javascript": "^7.0.5"
   }
 }