diff --git a/CLAUDE.md b/CLAUDE.md index adccc31..c9571b7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -124,6 +124,11 @@ Releases are automated via GitHub Actions on push to main (`.github/workflows/re - **Preview locally:** `devflow release` shows what the next release would be - **Manual bump:** `devflow version-bump ` updates all version files locally +**Release pipeline gotchas (fixed in v0.2.0 — do not reintroduce):** +- `bump-version.sh` runs under `set -o pipefail`. `check_version_consistency` (lib/watch.sh) greps each command file for a `[devflow v]` badge; that grep pipeline MUST be guarded with `|| true` — no command carries the badge, so an unguarded grep returns 1 and `set -e` aborts the whole release silently (right after "All version files updated", before `make release`). +- release.yml must create an **annotated** tag (`git tag -a "v$X" -m ...`). `git push --follow-tags` does NOT push lightweight tags, which leaves `gh release create` failing with "tag exists locally but has not been pushed". +- To release an already-merged commit that used `[skip release]`: `gh workflow run release.yml -f bump_override=` (the dispatch override bypasses the skip / "none" detection). + ### Auto-Reinstall When `devflow watch setup` is run in the devflow source repo, it offers an auto-reinstall opt-in: diff --git a/devflow-plugin/commands/render-diagram.md b/devflow-plugin/commands/render-diagram.md index e8f7a54..c4aefc7 100644 --- a/devflow-plugin/commands/render-diagram.md +++ b/devflow-plugin/commands/render-diagram.md @@ -71,4 +71,12 @@ When the diagram belongs in a doc (spec, ADR, walkthrough, README): Never embed the raw `.excalidraw` JSON in prose, and never rely on a markdown embed for in-session display — that is what Step 4's Read is for. +## Maintenance notes (export pipeline) + +`devflow visualizations render` → `lib/excalidraw-export.cjs` depends on three GLOBAL npm packages: `canvas`, `excalidraw-to-svg`, `@resvg/resvg-js`. If you touch this path: +- **node ≥ 25 requires `canvas@3+`** — `canvas@2` has no node-25 prebuilt (source build fails); `canvas@3.2.3+` ships a prebuilt binary. +- **`excalidraw-to-svg` reads `@excalidraw/utils` via a CWD-relative path** (`./node_modules/@excalidraw/utils/dist/excalidraw-utils.min.js`); with globally-installed deps the CLI passes `EXCAL_NODE_MODULES=$(npm root -g)` and the script `chdir`s to the dir whose `node_modules` holds it. +- **Global deps resolve via `NODE_PATH` — CommonJS `require` only, NOT ESM `import`** (this is why the script is `.cjs`). +- Don't suppress the `getContext` error — it signals a missing/misconfigured `canvas` (a real failure), unlike the cosmetic "Could not load img" jsdom warnings which are filtered. + $ARGUMENTS diff --git a/devflow-plugin/skills/render-diagram/SKILL.md b/devflow-plugin/skills/render-diagram/SKILL.md index add1c74..4b9b316 100644 --- a/devflow-plugin/skills/render-diagram/SKILL.md +++ b/devflow-plugin/skills/render-diagram/SKILL.md @@ -72,4 +72,12 @@ When the diagram belongs in a doc (spec, ADR, walkthrough, README): Never embed the raw `.excalidraw` JSON in prose, and never rely on a markdown embed for in-session display — that is what Step 4's Read is for. +## Maintenance notes (export pipeline) + +`devflow visualizations render` → `lib/excalidraw-export.cjs` depends on three GLOBAL npm packages: `canvas`, `excalidraw-to-svg`, `@resvg/resvg-js`. If you touch this path: +- **node ≥ 25 requires `canvas@3+`** — `canvas@2` has no node-25 prebuilt (source build fails); `canvas@3.2.3+` ships a prebuilt binary. +- **`excalidraw-to-svg` reads `@excalidraw/utils` via a CWD-relative path** (`./node_modules/@excalidraw/utils/dist/excalidraw-utils.min.js`); with globally-installed deps the CLI passes `EXCAL_NODE_MODULES=$(npm root -g)` and the script `chdir`s to the dir whose `node_modules` holds it. +- **Global deps resolve via `NODE_PATH` — CommonJS `require` only, NOT ESM `import`** (this is why the script is `.cjs`). +- Don't suppress the `getContext` error — it signals a missing/misconfigured `canvas` (a real failure), unlike the cosmetic "Could not load img" jsdom warnings which are filtered. + $ARGUMENTS diff --git a/skills/render-diagram/SKILL.md b/skills/render-diagram/SKILL.md index add1c74..4b9b316 100644 --- a/skills/render-diagram/SKILL.md +++ b/skills/render-diagram/SKILL.md @@ -72,4 +72,12 @@ When the diagram belongs in a doc (spec, ADR, walkthrough, README): Never embed the raw `.excalidraw` JSON in prose, and never rely on a markdown embed for in-session display — that is what Step 4's Read is for. +## Maintenance notes (export pipeline) + +`devflow visualizations render` → `lib/excalidraw-export.cjs` depends on three GLOBAL npm packages: `canvas`, `excalidraw-to-svg`, `@resvg/resvg-js`. If you touch this path: +- **node ≥ 25 requires `canvas@3+`** — `canvas@2` has no node-25 prebuilt (source build fails); `canvas@3.2.3+` ships a prebuilt binary. +- **`excalidraw-to-svg` reads `@excalidraw/utils` via a CWD-relative path** (`./node_modules/@excalidraw/utils/dist/excalidraw-utils.min.js`); with globally-installed deps the CLI passes `EXCAL_NODE_MODULES=$(npm root -g)` and the script `chdir`s to the dir whose `node_modules` holds it. +- **Global deps resolve via `NODE_PATH` — CommonJS `require` only, NOT ESM `import`** (this is why the script is `.cjs`). +- Don't suppress the `getContext` error — it signals a missing/misconfigured `canvas` (a real failure), unlike the cosmetic "Could not load img" jsdom warnings which are filtered. + $ARGUMENTS