Merge branch 'release/5.26.0'

Author: tomgrv

.devcontainer/devcontainer.json

@@ -0,0 +1,195 @@
+<!-- @format -->
+
+# Devcontainer Features Repository
+
+This repository contains a collection of devcontainer features that enhance development environments. It provides Git utilities, hooks, version management, and other development tools that can be installed individually or as a complete development setup.
+
+**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
+
+## Critical Guidelines for Code Changes
+
+**MINIMAL CHANGES ONLY**: Make the smallest possible changes to address the specific request. Do NOT modify files that are not directly related to the task:
+
+- **Package files** (`package.json`, `package-lock.json`) should only be modified if explicitly required for the feature being worked on
+- **Build artifacts** and **symlinks** should not be committed unless they are the direct target of the request
+- **Repository setup** (symlinks, environment bootstrapping) should be done for development/testing only, not committed
+- **Infrastructure changes** should be avoided unless they are specifically requested
+
+When working on feature requests:
+1. Identify the **exact files** that need to be modified for the request
+2. Make changes **only** to those files
+3. Use temporary setup for development/testing but revert any unrelated changes before committing
+4. Focus on the **specific feature or fix** requested, not general repository improvements
+
+## Quick Reference for Copilot Agents
+
+**MINIMAL CHANGES ONLY**: Make the smallest possible changes to address the specific request. Do NOT modify files that are not directly related to the task:
+
+- **Package files** (`package.json`, `package-lock.json`) should only be modified if explicitly required for the feature being worked on
+- **Build artifacts** and **symlinks** should not be committed unless they are the direct target of the request
+- **Repository setup** (symlinks, environment bootstrapping) should be done for development/testing only, not committed
+- **Infrastructure changes** should be avoided unless they are specifically requested
+
+<<<<<<< HEAD
+When working on feature requests:
+=======
+## Essential Setup Commands (For Development/Testing Only - DO NOT COMMIT)
+
+**IMPORTANT**: These commands are for local development and testing only. Do NOT commit the resulting changes (symlinks, package modifications) unless they are specifically part of the requested feature.
+>>>>>>> eb404c6 (Add validate-pr.yml workflow to larasets feature stubs (#21))
+
+1. Identify the **exact files** that need to be modified for the request
+2. Make changes **only** to those files
+3. Use temporary setup for development/testing but revert any unrelated changes before committing
+4. Focus on the **specific feature or fix** requested, not general repository improvements
+
+<<<<<<< HEAD
+## Critical Guidelines for Commit Messages
+
+- Title and description must follow conventional commit format: start with a type followed by a colon and a brief summary starting with an imperative verb.
+- Type must follow configured types in root package.json or default to standard types.
+- Add a scope in parentheses if project structure warrants it (check for workspace, modules or package names)
+=======
+# 2. Fix known symlink issues (5 seconds) - FOR TESTING ONLY
+find src/common-utils/ -type f -name "_*.sh" -exec chmod +x {} \;
+find src/common-utils/ -type f -name "_*.sh" | while read file; do 
+  ln -sf $file src/common-utils/$(basename $file | sed 's/^_//;s/.sh$//'); 
+done
+
+# 3. Workaround for install script typo (1 second) - FOR TESTING ONLY
+ln -sf src/common-utils/_zz_log.sh src/common-utils/_zz_logs.sh
+```
+
+**Set timeouts to 5+ minutes for ALL commands to prevent premature cancellation.**
+
+## Core Development Commands
+
+| Command | Purpose | Duration | Notes |
+|---------|---------|----------|-------|
+| `npm run lint` | Lint staged files | 1-2s (empty), 15s (with files) | Uses lint-staged, only lints staged files |
+| `npm test` | Run tests | <1s | Currently only shows warning - no tests exist |
+| `./install.sh -s` | Install stubs only | 10-15s | Creates `.devcontainer/` and `.vscode/` configs |
+| `./install.sh -a` | Install all features | 15-20s | Full feature installation |
+| `./install.sh gitutils` | Install specific feature | 5-10s | Install individual feature by name |
+| `npx tomgrv/devcontainer-features -h` | NPX installation | 2s (cached) | Alternative installation method |
+
+**Validation Commands:**
+```bash
+# Quick feature test
+mkdir /tmp/test-features && cd /tmp/test-features
+git init
+/path/to/devcontainer-features/install.sh -s
+ls -la .devcontainer/ .vscode/  # Verify files created
+```
+
+## Repository Architecture
+
+### 7 Devcontainer Features (`src/` directory)
+
+| Feature | Purpose | Key Files |
+|---------|---------|-----------|
+| **gitutils** | Git aliases and workflow automation | Aliases for common git operations |
+| **githooks** | Development environment setup | commitlint, prettier, lint-staged, husky |
+| **gitversion** | Semantic versioning | GitVersion tool for automated versioning |
+| **act** | Local GitHub Actions | Nektos/act for running actions locally |
+| **pecl** | PHP Extensions | PECL installer for PHP development |
+| **larasets** | Laravel tools | Laravel-specific development utilities |
+| **common-utils** | Shared utilities | Scripts used by other features |
+
+### Key Configuration Files
+
+- `package.json` - Main configuration with npm scripts, dependencies, prettier, commitlint
+- `install.sh` - Installation script (**has typo bug** - see workaround above)
+- `.github/workflows/` - CI/CD: `validate.yml`, `release.yaml`
+- `stubs/` - Template files for `.devcontainer/` and `.vscode/` configs
+
+## Critical Issues & Workarounds
+
+### 🐛 Install Script Typo (Line 9)
+**Problem**: Script references `_zz_logs.sh` but file is `_zz_log.sh`  
+**Fix**: `ln -sf src/common-utils/_zz_log.sh src/common-utils/_zz_logs.sh`
+
+### 📦 Missing Prettier Plugin  
+**Problem**: Linting fails without `prettier-plugin-sh`  
+**Fix**: `npm install prettier-plugin-sh` (included in setup commands above)
+
+### 🔗 Broken Symlinks in common-utils
+**Problem**: Shell scripts not executable and symlinks missing  
+**Fix**: Run the chmod and symlink commands from setup section above
+
+### 🐳 Container vs Local Behavior
+- Features designed for **devcontainer environments**
+- Local installation shows "No writeable directory found" - **this is normal**
+- Some features require Docker/specific dependencies not available locally
+
+## Common Workflows for Copilot Agents
+
+### 🚀 First-time Repository Setup (Development/Testing Only)
+```bash
+# Run this exactly - all commands are required FOR TESTING ONLY
+# DO NOT COMMIT the resulting symlinks or package changes unless specifically requested
+cd /home/runner/work/devcontainer-features/devcontainer-features
+npm install
+npm install prettier-plugin-sh
+find src/common-utils/ -type f -name "_*.sh" -exec chmod +x {} \;
+find src/common-utils/ -type f -name "_*.sh" | while read file; do 
+  ln -sf $file src/common-utils/$(basename $file | sed 's/^_//;s/.sh$//'); 
+done
+ln -sf src/common-utils/_zz_log.sh src/common-utils/_zz_logs.sh
+```
+
+### 🧪 Testing Changes
+```bash
+# 1. Create test environment
+mkdir /tmp/feature-test && cd /tmp/feature-test
+git init
+
+# 2. Test installation
+/home/runner/work/devcontainer-features/devcontainer-features/install.sh -s
+
+# 3. Verify results
+ls -la .devcontainer/ .vscode/
+cat .devcontainer/devcontainer.json  # Should contain features array
+```
+
+### ✅ Pre-commit Validation
+```bash
+git add .                # Stage your changes
+npm run lint            # Lint staged files (1-15 seconds)
+# Fix any linting issues, then commit
+```
+
+### 📦 NPX Alternative Testing
+```bash
+# Test the NPX installation method
+mkdir /tmp/npx-test && cd /tmp/npx-test
+git init
+npx tomgrv/devcontainer-features -s
+# Should create same files as local installation
+```
+
+## Performance Expectations
+
+⚡ **Timing Reference** (all validated):
+
+| Operation | Expected Duration | Timeout Setting |
+|-----------|------------------|-----------------|
+| `npm install` | 3 seconds | 5+ minutes |
+| `npm install prettier-plugin-sh` | 1 second | 2+ minutes |
+| `npm run lint` (no files) | 1-2 seconds | 2+ minutes |
+| `npm run lint` (with files) | up to 15 seconds | 2+ minutes |
+| `./install.sh -s` | 10-15 seconds | 2+ minutes |
+| `./install.sh -a` | 15-20 seconds | 3+ minutes |
+| `./install.sh <feature>` | 5-10 seconds | 2+ minutes |
+| `npx tomgrv/devcontainer-features` | 2 seconds (cached) | 2+ minutes |
+
+⚠️ **CRITICAL**: Always set generous timeouts. Commands complete quickly but need buffer for system variations.
+
+## Troubleshooting Guide
+
+**❌ "No staged files found"** → Normal when running `npm run lint` with no staged changes  
+**❌ "No writeable directory found"** → Normal for local installation, features designed for containers  
+**❌ "_zz_logs.sh: No such file"** → Run the typo workaround: `ln -sf src/common-utils/_zz_log.sh src/common-utils/_zz_logs.sh`  
+**❌ "prettier-plugin-sh not found"** → Run: `npm install prettier-plugin-sh`  
+**❌ "Permission denied" on scripts** → Run: `find src/common-utils/ -type f -name "_*.sh" -exec chmod +x {} \;`
+>>>>>>> eb404c6 (Add validate-pr.yml workflow to larasets feature stubs (#21))

.github/copilot-instructions.md

@@ -0,0 +1,25 @@
+# @format
+
+name: Validate PR Title
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  alidate-pr-title:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install dependencies
+        run: npm ci && npm install -D $(jq -r '.commitlint.extends//""' 'package.json' | tr -d "'[]:,\"")
+
+      - name: Validate PR title
+        run: echo "${{ github.event.pull_request.title }}" | npx commitlint

.github/workflows/validate-pr-format.yml

@@ -12,6 +12,7 @@
 *.cache
 
 ## Misc
+VERSION
 .history
 .version.json
 .mono

.github/workflows/validate.yml

@@ -2,11 +2,96 @@
 
 # Changelog
 
-All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
+## v5.26.0 (2025-10-01)
+
+_Commits from: v5.25.0..HEAD_
+
+### 📂 Unscoped changes
+
+#### Features
+
+- ✨ add VERSION file update with gitversion semver on checkout (#11) ([1d08e6e](https://github.com/tomgrv/devcontainer-features/commit/1d08e6e4b1cb56bf106e9bab6aadc5610fc3b2fb))
+- ✨ update package.json to make them installable ([96e663e](https://github.com/tomgrv/devcontainer-features/commit/96e663e8c802db491bda593c76b90fbc2f09d686))
+
+#### Other changes
+
+- Add comprehensive GitHub Copilot instructions for devcontainer-features repository (#9) ([c3d40be](https://github.com/tomgrv/devcontainer-features/commit/c3d40be614546e9e27e37ec2ef83458fa120f9c5))
+- Add validate-pr.yml workflow to larasets feature stubs (#21) ([1c6ba09](https://github.com/tomgrv/devcontainer-features/commit/1c6ba0973262ac49b610b4f187e74ffdf023c00d))
+- Add validate-pr.yml workflow to larasets feature stubs (#21) ([bde381e](https://github.com/tomgrv/devcontainer-features/commit/bde381e7de5a0c3f3474cfd85fa7443385889dd4))
+- Correct filename reference from \_zz_logs.sh to \_zz_log.sh in install.sh (#17) ([594243b](https://github.com/tomgrv/devcontainer-features/commit/594243baef47d36eb35f59f7095f928b4eea73b2))
+- 📦️ ensure package.json are there ([ec38ffc](https://github.com/tomgrv/devcontainer-features/commit/ec38ffc234aaa48e0133a41025b26c51f9904dce))
+
+### 📦 common-utils changes
+
+#### Bug Fixes
+
+- 🐛 improve argument handling and usage output formatting ([3aa56d4](https://github.com/tomgrv/devcontainer-features/commit/3aa56d410c3d19c5ec41c0b55f2ff1975eafc1de))
+
+#### Features
+
+- ✨ add dispatcher utility script ([38dfce8](https://github.com/tomgrv/devcontainer-features/commit/38dfce894a5f2603f16ba17574fee1a8374bcc50))
+- ✨ add zz_input util ([3c2cc9c](https://github.com/tomgrv/devcontainer-features/commit/3c2cc9cb1700e0e8a604dc068f0b858eb3edc1e4))
+
+#### Other changes
+
+- ♻️ rename zz_utility to zz_dispatch ([4ceb267](https://github.com/tomgrv/devcontainer-features/commit/4ceb26734f3af4db1dbf57c561a4d73282d2a852))
+
+### 📦 githooks changes
+
+#### Features
+
+- ✨ add checkout version util ([d10c373](https://github.com/tomgrv/devcontainer-features/commit/d10c3737c5893362098b63ba37b4a78d584ee14e))
+- ✨ add sync-versions script and PR title validation workflow ([4e8a48d](https://github.com/tomgrv/devcontainer-features/commit/4e8a48de53ff643a8c159d4926b8572d1244777b))
+
+### 📦 gitutils changes
+
+#### Bug Fixes
+
+- 🐛 add bumped files commit ([d944af2](https://github.com/tomgrv/devcontainer-features/commit/d944af2ba50f50e3a26c0edfe48e5fee065a8afe))
+- 🐛 ensure lock file presence ([97ee738](https://github.com/tomgrv/devcontainer-features/commit/97ee7386c232724913cb4cde894f875e7f541374))
+
+#### Features
+
+- ✨ add auto rebase script and enhance commit deletion logic ([971090e](https://github.com/tomgrv/devcontainer-features/commit/971090e6c04ffed8e4f1770f3dfed493b5b01889))
+- ✨ add clear command ([f038e51](https://github.com/tomgrv/devcontainer-features/commit/f038e51f54b5eed6c820262d2e7b7dd0083de193))
+- ✨ add git pn alias for push --no-verify (#13) ([ceb1fbe](https://github.com/tomgrv/devcontainer-features/commit/ceb1fbe38e3f739f2b1812c433a3c023386ea649))
+- ✨ add scripts for squash merging and production releases ([e9b103a](https://github.com/tomgrv/devcontainer-features/commit/e9b103a7822a843f045cd4ea6a80b7891aa0711e))
+- ✨ add scripts for squash merging and production releases ([fa52dec](https://github.com/tomgrv/devcontainer-features/commit/fa52dec3de4dfabd28347869aef9dfc99e8cb416))
+- ✨ migrate to gitversion utils ([426b923](https://github.com/tomgrv/devcontainer-features/commit/426b9233a515e61c964532709485f4177745f021))
+
+#### Other changes
+
+- ♻️ ✨ add scripts to fix author and edit last commit ([8780a2b](https://github.com/tomgrv/devcontainer-features/commit/8780a2b8c5baf68e0f30f10ffdd334da883ffeb7))
+- ♻️ move to zz_log ([b0bf13b](https://github.com/tomgrv/devcontainer-features/commit/b0bf13bedc981b62bf1931a5624b648987fd4c51))
+
+### 📦 gitversion changes
+
+#### Bug Fixes
+
+- 🐛 improve version handling ([bdd74fc](https://github.com/tomgrv/devcontainer-features/commit/bdd74fc69e87a3a6d291a7d2184ce1821f9d6820))
+
+#### Features
+
+- ✨ add bump utilities ([8819028](https://github.com/tomgrv/devcontainer-features/commit/88190286546b1eefc42add9a8f0f73b0c7dbc49c))
+- ✨ enhance tag creation logic with force option handling ([193baf8](https://github.com/tomgrv/devcontainer-features/commit/193baf84f12e0daa0e99698501af0e817bea29b5))
+
+### 📦 larasets changes
+
+#### Bug Fixes
+
+- 🐛 refine vendor directory exclusions for modules and packages ([e814109](https://github.com/tomgrv/devcontainer-features/commit/e814109816a70b744dbe05ce6ec8eff0b9ee9298))
+
+#### Features
+
+- ✨ update task labels and commands ([9456163](https://github.com/tomgrv/devcontainer-features/commit/9456163b5662c6b3f3d9c7abd0ff3d51a5060e8a))
 
 ## 1.1.0 (2024-06-22)
 
 ### Features
 
--   ✨ add githook ([ab4c1fc](https://github.com/tomgrv/devcontainer-features/commit/ab4c1fc5eb4f712ed2009baf9a3cadb11097c7b5))
--   add features ([4b26d9d](https://github.com/tomgrv/devcontainer-features/commit/4b26d9d876caffb15078a6baaabf76d1a2707e6f))
+- ✨ add githook ([ab4c1fc](https://github.com/tomgrv/devcontainer-features/commit/ab4c1fc5eb4f712ed2009baf9a3cadb11097c7b5))
+- add features ([4b26d9d](https://github.com/tomgrv/devcontainer-features/commit/4b26d9d876caffb15078a6baaabf76d1a2707e6f))
+
+---
+
+_Generated on 2025-10-01 by [tomgrv/devcontainer-features](https://github.com/tomgrv/devcontainer-features)_

.gitignore

@@ -6,7 +6,7 @@ source=$(dirname $(readlink -f $0))
 # Source the common utils
 . $source/src/common-utils/_zz_colors.sh
 
-alias zz_log=$source/src/common-utils/_zz_logs.sh
+alias zz_log=$source/src/common-utils/_zz_log.sh
 
 # Prepare for local installation by creating a temporary directory and linking common utils
 find $source/src/common-utils/ -type f -name "_*.sh" -exec echo {} \; -exec chmod +x {} \; | while read file; do