--- name: version-bump description: Bump the package version across all versioned filenames, imports, READMEs, HTML files, and package.json exports in the Cahir project. --- # version-bump This skill handles version bumping across the Cahir project — a task that involves renaming ~19 versioned files, updating ~18 files with version strings in their content, rebuilding dist/, and syncing static/js/ copies. ## When to Use Use this skill when: - A **patch**, **minor**, or **major** version bump is needed - The user says something like "bump version", "update version to X.Y.Z", "prepare release" - A new version is being prepared for `npm publish` ## How It Works The project uses **version-stamped filenames** for better CDN UX (e.g., `simple-chat.0.0.10.es.js`). On each version bump, all these filenames and internal references must be updated consistently. A companion bash script handles this automatically: ``` scripts/version-bump.sh ``` ## Steps ### 1. Dry-run first (recommended) Always preview what will happen before making changes: ```bash bash scripts/version-bump.sh --dry-run ``` This walks through ALL phases showing exactly what would happen — backup targets, npm version changes, mini-diffs for every content change (line-by-line before→after), file renames, build, and static sync — without modifying anything. ### 2. Run the bump ```bash bash scripts/version-bump.sh ``` The script will: 1. Read the current version from `package.json` 2. Discover all versioned files dynamically (via `find` and `grep`) 3. Show a summary and ask for confirmation 4. **Phase 0:** Back up all affected files to `olderVersions/` (skip with `--no-backup`) 5. **Phase 0.5:** `npm version --no-git-tag-version` to update `package.json` version field + `package-lock.json` 6. **Phase 1:** `sed -i` replace old version → new version in file contents (export paths, imports, READMEs, etc.) + `git add`. `package-lock.json` is never touched by sed. 7. **Phase 2:** `git mv` all versioned filenames to new version (or `mv` + `git add` for untracked) 8. **Phase 3:** Run `npm run build` to regenerate `dist/` files (aborts on failure) 9. **Phase 4:** Copy fresh builds to `static/js/` + clean up old copies 10. **Phase 5:** Verify no stale old-version references remain ### 3. Review and commit ```bash git diff --staged git commit -m "chore: bump version to " git tag v # optional npm publish ``` ## What Gets Changed ### Files RENAMED (dynamically discovered — new components auto-included): **dist/** — 6 files (also regenerated by `npm run build`): - `cahir..evergreen.es.js` - `cahir..evergreen.es.min.js` - `cahir..evergreen.umd.cjs` - `cahir..evergreen.umd.js` - `cahir..evergreen.umd.min.cjs` - `cahir..evergreen.umd.min.js` **collections/DOM/** — 3 files: - `ch..cjs` - `ch..es.js` - `ch..js` **components/\*/** — 2 files per component (`.es.js` + `.js`): - `..es.js` - `..js` **static/js/** — 2 files (copies for GitHub Pages): - `cahir..evergreen.umd.js` - `ch..js` ### Files with CONTENT updates (dynamically discovered): - `package.json` — version field (via `npm version`) + exports paths (via `sed`) - `README.md` — CDN URLs and file references - `index.html` — script src tags - `components/examples/index.html` — script src tags - `components/*/README.md` — CDN URLs in each component's docs - `collections/DOM/ch.es.js` + `ch..es.js` — import paths - `components/*/*.es.js` + `*..es.js` — import paths ### Files that are NOT touched: - `.cjs` files — no version strings inside - Non-ES `.js` component files (e.g., `simple-chat.js`) — no version strings inside - `rollup.config.evergreen.js` — reads version from env dynamically - `CHANGELOG.md` — excluded from automated replacement (update manually) - `package-lock.json` — managed by `npm version`, never touched by `sed` - `src/` — source files rebuilt via `npm run build` using `npm_package_version` env var - `debug/` — not committed (in `.gitignore`) ## Adding New Components When a new component is added under `components/`: 1. Follow the existing naming convention: - `components//..es.js` - `components//..js` - `components//.es.js` (versionless copy) - `components//.js` (versionless copy) 2. The `.es.js` files should import from `../../collections/DOM/ch..es.js` 3. Add the component to `package.json` exports: ```json "./components/": { "browser": "./components//..js", "import": "./components//..es.js" } ``` 4. Add the component script tag to `components/examples/index.html` 5. **The bash script will automatically discover the new component** on the next version bump — no script changes needed, as it uses `find` and `grep` to dynamically locate versioned files. ## Flags | Flag | Description | |------|-------------| | `--dry-run` | Walk through all phases showing exactly what would change (mini-diffs, renames, etc.) without modifying anything | | `--yes` or `-y` | Skip confirmation prompt (for CI/automation) | | `--no-backup` | Skip the pre-change backup to `olderVersions/` | ## Safety - The script only operates within the git project root - Validates semver format before proceeding - Backs up all affected files to `olderVersions/backup-{VERSION}-{TIMESTAMP}/` before changes - Shows a full summary before making any changes - Uses `git mv` for better rename tracking (smaller diffs) - Stages all version-bumped files (`git add`) for commit - Aborts if `npm run build` fails - Verifies no stale references remain after completion - Excludes `CHANGELOG.md` from automated replacement and content discovery (update manually) - Excludes `src/`, `debug/`, `olderVersions/` from scanning - Auto-excludes gitignored paths via `git check-ignore` (second pass on top of manual exclusions) - All `grep` calls use `-F` (fixed-string mode) so dots in version strings are literal, not regex wildcards - `sed` escapes dots in version strings for regex safety (`0.0.10` → `0\.0\.10`) - Phase 5 verifies both file contents AND filenames for stale old-version references - Dry-run walks through every phase with full reporting (not just a summary) - Mini-diffs show every line that will change, before and after, with line numbers