Feature/v4.0

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -90,4 +90,4 @@ body:
       label: "Other"
       description: |
         Anything else relevant? eg: Logs, OS version, IDE, package manager, etc.
-        **Tip:** You can attach images, recordings or log files by clicking this area to highlight it and then dragging files in
+        **Tip:** You can attach images, recordings or log files by clicking this area to highlight it and then dragging files in

.github/ISSUE_TEMPLATE/community_ideas.yml

@@ -89,4 +89,4 @@ body:
         - Studio / DX
         - Documentation
         - Templates / Examples
-        - Not sure
+        - Not sure

.github/ISSUE_TEMPLATE/config.yml

@@ -8,4 +8,4 @@ contact_links:
     about: Ask questions with the expressots tag
   - name: Expressots Project Board
     url: https://github.com/orgs/expressots/projects/5
-    about: Track framework work across all ExpressoTS repositories
+    about: Track framework work across all ExpressoTS repositories

.github/ISSUE_TEMPLATE/documentation.yml

@@ -49,4 +49,4 @@ body:
   - type: textarea
     attributes:
       label: "Suggested improvement"
-      description: "Optional: how would you improve this documentation?"
+      description: "Optional: how would you improve this documentation?"

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -59,4 +59,4 @@ body:
         - Studio / DX
         - Documentation
         - Templates / Examples
-        - Not sure
+        - Not sure

.github/workflows/build.yaml

@@ -4,45 +4,48 @@ on:
   push:
     branches:
       - main
+      - feature/v4.0
   pull_request:
-    branches: ["main"]
+    branches: ["main", "feature/v4.0"]
   pull_request_target:
     types: [opened, synchronize, reopened]
 
+permissions:
+  contents: read
+
 jobs:
   build:
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Use Node.js
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: "18.11.0"
+          node-version: "20.19.0"
+          cache: "npm"
 
       - name: Install dependencies
-        run: npm install
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Build
+        run: npm run build
 
       - name: Unit Tests
-        working-directory: ./src
         run: npm run test
         env:
           CI: true
 
       - name: Run Code Coverage
-        working-directory: ./src
         run: npm run coverage
 
-      - name: Build
-        run: npm run build
-
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v4.0.1
         with:
           working-directory: .
           token: ${{ secrets.CODECOV_TOKEN }}
-
-      - name: Set up .npmrc
-        run: echo "//npm.pkg.github.com/:_authToken=${{ secrets.NPM_TOKEN }}" >> .npmrc

.github/workflows/codeql.yml

@@ -13,9 +13,9 @@ name: "CodeQL Advanced"
 
 on:
   push:
-    branches: [ "main" ]
+    branches: [ "main", "feature/v4.0" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "main", "feature/v4.0" ]
   schedule:
     - cron: '0 17 * * 4'
 

.github/workflows/publish-preview.yml

@@ -0,0 +1,55 @@
+name: Publish Preview to npm
+
+# Manual-dispatch only. Builds, tests, runs `release:prepare` to rewrite
+# any local file: deps to semver ranges, publishes under the chosen
+# dist-tag (default: `next`), then restores `package.json`.
+#
+# Usage from the GitHub UI: Actions -> Publish Preview to npm -> Run workflow.
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'npm dist-tag (default: next)'
+        required: false
+        default: 'next'
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.19.0
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Prepare publish (rewrite file: deps to ranges)
+        run: npm run release:prepare
+
+      - name: Publish to npm
+        run: npm publish --tag ${{ inputs.tag }} --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Restore package.json
+        if: always()
+        run: npm run release:restore

.gitignore

@@ -46,8 +46,9 @@ yarn.lock
 templates/opinionated/yarn.lock
 templates/opinionated/package-lock.json
 
-# ignore npm lock files
+# ignore npm lock files (keep root package-lock.json for CI npm ci)
 *-lock.json
+!package-lock.json
 
 # Ignore VSCODE configuration files
 .vscode

.husky/commit-msg

@@ -1 +1,26 @@
-npm run lint:fix && npm run format && npx --no -- commitlint --edit  
+
+# Ensure npx/node are on PATH when committing from GUI clients (Cursor, VS Code, ...)
+# that don't source the user's interactive shell rc files.
+if [ -z "$(command -v npx 2>/dev/null)" ]; then
+  export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+  for nvm_init in \
+    "$NVM_DIR/nvm.sh" \
+    "/usr/share/nvm/init-nvm.sh" \
+    "/usr/share/nvm/nvm.sh" \
+    "/usr/local/opt/nvm/nvm.sh" \
+    "/opt/homebrew/opt/nvm/nvm.sh"; do
+    if [ -s "$nvm_init" ]; then
+      # shellcheck disable=SC1090
+      . "$nvm_init"
+      break
+    fi
+  done
+fi
+
+if [ -z "$(command -v npx 2>/dev/null)" ]; then
+  echo "husky/commit-msg: npx not found in PATH. Skipping commitlint." >&2
+  echo "                 (Open a terminal where 'npx -v' works, or install nvm.)" >&2
+  exit 0
+fi
+
+npx --no -- commitlint --edit "$1"

.husky/pre-commit

@@ -0,0 +1,27 @@
+
+# Ensure node/npm/npx are on PATH when committing from GUI clients
+# (Cursor, VS Code, IntelliJ, ...) that don't source the user's
+# interactive shell rc files.
+if [ -z "$(command -v npx 2>/dev/null)" ]; then
+  export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+  for nvm_init in \
+    "$NVM_DIR/nvm.sh" \
+    "/usr/share/nvm/init-nvm.sh" \
+    "/usr/share/nvm/nvm.sh" \
+    "/usr/local/opt/nvm/nvm.sh" \
+    "/opt/homebrew/opt/nvm/nvm.sh"; do
+    if [ -s "$nvm_init" ]; then
+      # shellcheck disable=SC1090
+      . "$nvm_init"
+      break
+    fi
+  done
+fi
+
+if [ -z "$(command -v npx 2>/dev/null)" ]; then
+  echo "husky/pre-commit: npx not found in PATH. Skipping lint-staged." >&2
+  echo "                 (Open a terminal where 'npx -v' works, or install nvm.)" >&2
+  exit 0
+fi
+
+npx --no -- lint-staged

CHANGELOG.md

@@ -1,4 +1,24 @@
+## [4.0.0-preview.3](https://github.com/expressots/shared/compare/3.0.0...4.0.0-preview.3) (2026-05-25)
 
+Part of the ExpressoTS **v4.0.0 preview bundle**. See the [v4.0.0 release notes](https://expresso-ts.com/docs/4.0.0/prologue/release) and the [upgrade guide](https://expresso-ts.com/docs/4.0.0/prologue/upgrade_guide) for the full picture.
+
+### Features
+
+* extend `ExpressoConfig` with `scaffoldSchematics` covering all v4 schematics (`controller`, `usecase`, `dto`, `module`, `provider`, `entity`, `middleware`, `interceptor`, `event`, `handler`, `guard`, `config`).
+* add type-safe `Pattern` enum (regular `enum`, not `const enum`, so consumers compiling with `isolatedModules: true` such as Vite/Vitest/esbuild/SWC can import it).
+* expose shared content-negotiation primitives consumed by `@expressots/core` formatters.
+* add `Env.when(condition, value, fallback)` helper for environment-specific config resolution.
+* publish dual ESM + CJS builds with subpath exports for both module systems.
+* declare `engines.node: ">=20.18.0"`.
+
+### Bug Fixes
+
+* tighten the `IWebServer` / `IWebServerBuilder` typings so v4 adapters can declare their server contract without leaking Express types.
+* `configDotenv()` is now safe to call with no arguments — null-guard added on `options.encoding` / `options.debug` (previously threw `TypeError: Cannot read properties of undefined`).
+
+### Build System
+
+* bump dev toolchain to TypeScript 5.5, ESLint 8.57, Jest 29.7, Prettier 3.5.
 
 ## [3.0.0](https://github.com/expressots/shared/compare/3.0.0-beta.3...3.0.0) (2024-12-04)