@webpieces/dev-config 0.0.0-dev

package/README.md

@@ -0,0 +1,306 @@
+# @webpieces/dev-config
+
+Development configuration, scripts, and patterns for WebPieces projects.
+
+## Overview
+
+This package provides shareable development tools for projects using the WebPieces framework:
+
+- **Executable scripts** for common development tasks
+- **ESLint configuration** with WebPieces patterns and best practices
+- **Jest preset** for testing TypeScript projects
+- **Base TypeScript configuration** with decorator support
+- **Claude Code patterns** for AI-assisted development
+
+## Installation
+
+```bash
+npm install --save-dev @webpieces/dev-config
+```
+
+## Features
+
+### 1. Executable Scripts
+
+All scripts are available as npm bin commands after installation.
+
+#### Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `wp-start` | Start the WebPieces development server |
+| `wp-stop` | Stop the running server |
+| `wp-set-version` | Update package versions across the monorepo |
+| `wp-use-local` | Switch to local WebPieces packages for development |
+| `wp-use-published` | Switch back to published npm packages |
+| `wp-setup-patterns` | Create symlinks for Claude Code pattern files |
+
+#### Usage in package.json
+
+```json
+{
+  "scripts": {
+    "start": "wp-start 8080",
+    "stop": "wp-stop",
+    "dev:local": "wp-use-local",
+    "postinstall": "wp-setup-patterns"
+  }
+}
+```
+
+#### Local Development with wp-use-local
+
+To develop against a local copy of webpieces-ts:
+
+1. Set the `WEBPIECES_ROOT` environment variable:
+   ```bash
+   export WEBPIECES_ROOT=/path/to/webpieces-ts
+   ```
+
+2. Build webpieces-ts:
+   ```bash
+   cd $WEBPIECES_ROOT
+   npm run build
+   ```
+
+3. Switch to local packages:
+   ```bash
+   wp-use-local
+   ```
+
+4. To switch back to published packages:
+   ```bash
+   wp-use-published
+   ```
+
+### 2. ESLint Configuration
+
+Import the base configuration in your `eslint.config.mjs`:
+
+```javascript
+import webpiecesConfig from '@webpieces/dev-config/eslint';
+import nx from '@nx/eslint-plugin';
+
+export default [
+  ...webpiecesConfig,  // WebPieces base rules
+  ...nx.configs['flat/typescript'],
+  {
+    // Project-specific overrides
+    files: ['**/*.ts'],
+    rules: {
+      // Your custom rules
+    }
+  }
+];
+```
+
+The base configuration includes:
+
+- TypeScript-specific rules aligned with WebPieces patterns
+- Relaxed rules for test files
+- Consistent code quality standards
+- Support for decorators and metadata
+
+### 3. Jest Preset
+
+Use the Jest preset in your `jest.config.js`:
+
+```javascript
+module.exports = {
+  preset: '@webpieces/dev-config/jest',
+  // Project-specific overrides
+  roots: ['<rootDir>/src'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.spec.ts',
+  ],
+};
+```
+
+The preset includes:
+
+- `ts-jest` for TypeScript support
+- Decorator and metadata support enabled
+- Sensible test file patterns (`*.spec.ts`, `*.test.ts`)
+- Coverage configuration
+
+### 4. TypeScript Configuration
+
+Extend the base TypeScript config in your `tsconfig.json`:
+
+```json
+{
+  "extends": "@webpieces/dev-config/tsconfig",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      // Project-specific path mappings
+    }
+  },
+  "include": ["src/**/*"]
+}
+```
+
+The base configuration includes:
+
+- Decorator support (`experimentalDecorators`, `emitDecoratorMetadata`)
+- Strict type checking
+- ES2021 target with CommonJS modules
+- Source maps enabled
+
+### 5. Claude Code Patterns
+
+The package includes WebPieces coding patterns and guidelines for Claude Code.
+
+#### Setup
+
+Run the setup command to create symlinks in your `.claude` directory:
+
+```bash
+wp-setup-patterns
+```
+
+This creates:
+- `.claude/CLAUDE.md` - Claude Code guidelines
+- `.claude/claude.patterns.md` - Detailed coding patterns
+
+These files will auto-update when you upgrade `@webpieces/dev-config`.
+
+#### Adding to postinstall
+
+Add to your `package.json` to automatically set up patterns after install:
+
+```json
+{
+  "scripts": {
+    "postinstall": "wp-setup-patterns"
+  }
+}
+```
+
+## Auto-Sync Behavior
+
+When you upgrade `@webpieces/dev-config`, all configurations automatically update:
+
+```bash
+npm update @webpieces/dev-config
+```
+
+Your ESLint, Jest, and TypeScript configurations will use the latest version without manual intervention, as they reference files from `node_modules/@webpieces/dev-config`.
+
+## Version Management
+
+The package follows semantic versioning:
+
+- **Major versions** (2.0.0): Breaking changes to configuration or script behavior
+- **Minor versions** (1.1.0): New features, additional scripts, or non-breaking config changes
+- **Patch versions** (1.0.1): Bug fixes and documentation updates
+
+## Examples
+
+### Full Project Setup
+
+```bash
+# Install the package
+npm install --save-dev @webpieces/dev-config
+
+# Set up Claude patterns
+npx wp-setup-patterns
+
+# Create eslint.config.mjs
+cat > eslint.config.mjs << 'EOF'
+import webpiecesConfig from '@webpieces/dev-config/eslint';
+export default [...webpiecesConfig];
+EOF
+
+# Create jest.config.js
+cat > jest.config.js << 'EOF'
+module.exports = {
+  preset: '@webpieces/dev-config/jest',
+};
+EOF
+
+# Create tsconfig.json
+cat > tsconfig.json << 'EOF'
+{
+  "extends": "@webpieces/dev-config/tsconfig",
+  "include": ["src/**/*"]
+}
+EOF
+
+# Add scripts to package.json
+npm pkg set scripts.start="wp-start 8080"
+npm pkg set scripts.stop="wp-stop"
+npm pkg set scripts.postinstall="wp-setup-patterns"
+```
+
+### Using in webpieces-ts itself
+
+The webpieces-ts monorepo uses its own dev-config package via workspace protocol:
+
+```json
+{
+  "devDependencies": {
+    "@webpieces/dev-config": "workspace:*"
+  }
+}
+```
+
+This ensures webpieces-ts uses the same tools as consuming projects (dogfooding).
+
+## Troubleshooting
+
+### Scripts not found
+
+If bin commands like `wp-start` are not found:
+
+1. Ensure the package is installed: `npm list @webpieces/dev-config`
+2. Check that npm created symlinks: `ls -la node_modules/.bin/wp-*`
+3. Try reinstalling: `npm install`
+
+### Claude patterns not showing
+
+If `.claude/CLAUDE.md` doesn't exist:
+
+```bash
+# Run the setup command manually
+npx wp-setup-patterns
+
+# Or check if the files exist in node_modules
+ls -la node_modules/@webpieces/dev-config/patterns/
+```
+
+### Local development not working
+
+If `wp-use-local` fails:
+
+1. Ensure `WEBPIECES_ROOT` is set: `echo $WEBPIECES_ROOT`
+2. Build webpieces-ts: `cd $WEBPIECES_ROOT && npm run build`
+3. Check that dist exists: `ls $WEBPIECES_ROOT/dist/packages/`
+
+## Contributing
+
+This package is part of the [webpieces-ts](https://github.com/deanhiller/webpieces-ts) monorepo.
+
+To modify scripts or configurations:
+
+1. Edit files in `packages/tooling/dev-config/`
+2. Build: `npx nx build dev-config`
+3. Test in webpieces-ts itself (dogfooding)
+4. Submit a pull request
+
+## License
+
+Apache-2.0
+
+## Related Packages
+
+- [@webpieces/core-context](https://www.npmjs.com/package/@webpieces/core-context) - Context management
+- [@webpieces/http-server](https://www.npmjs.com/package/@webpieces/http-server) - HTTP server
+- [@webpieces/http-routing](https://www.npmjs.com/package/@webpieces/http-routing) - Routing and controllers
+- [@webpieces/http-filters](https://www.npmjs.com/package/@webpieces/http-filters) - Filter chain
+
+## Support
+
+- GitHub Issues: https://github.com/deanhiller/webpieces-ts/issues
+- Documentation: https://github.com/deanhiller/webpieces-ts#readme

package/bin/set-version.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+set -e
+
+# Set version script for webpieces packages
+# Path-agnostic version that works from both workspace and node_modules
+
+# Detect project root
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if [[ "$SCRIPT_DIR" == *"node_modules/@webpieces/dev-config"* ]]; then
+  # Running in consumer project
+  PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+else
+  # Running in webpieces-ts workspace
+  PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+fi
+
+cd "$PROJECT_ROOT" || exit 1
+
+# Read base version from VERSION file
+BASE_VERSION=$(cat VERSION | tr -d '[:space:]')
+
+# Get build number from environment or default to 'dev'
+BUILD_NUMBER=${BUILD_NUMBER:-dev}
+
+# Construct full version
+if [ "$BUILD_NUMBER" = "dev" ]; then
+  FULL_VERSION="0.0.0-dev"
+else
+  FULL_VERSION="${BASE_VERSION}.${BUILD_NUMBER}"
+fi
+
+echo "📦 Setting version to: $FULL_VERSION"
+echo "   Base version: $BASE_VERSION"
+echo "   Build number: $BUILD_NUMBER"
+
+# Update all package.json files in packages/
+update_package() {
+  local pkg_file=$1
+  echo "   Updating: $pkg_file"
+
+  # Create temp file
+  local tmp_file=$(mktemp)
+
+  # Update version
+  jq --arg ver "$FULL_VERSION" '.version=$ver' "$pkg_file" > "$tmp_file"
+
+  # Update @webpieces/* dependencies to match
+  jq --arg ver "$FULL_VERSION" '
+    if .dependencies then
+      .dependencies |= with_entries(
+        if .key | startswith("@webpieces/") then
+          .value = $ver
+        else
+          .
+        end
+      )
+    else
+      .
+    end
+  ' "$tmp_file" > "$tmp_file.2"
+
+  # Move back
+  mv "$tmp_file.2" "$pkg_file"
+  rm -f "$tmp_file"
+}
+
+# Update source package.json files
+echo "📝 Updating source package.json files..."
+for pkg in packages/core/*/package.json packages/http/*/package.json packages/tooling/*/package.json; do
+  if [ -f "$pkg" ]; then
+    update_package "$pkg"
+  fi
+done
+
+# Update dist package.json files if they exist
+if [ -d "dist/packages" ]; then
+  echo "📝 Updating dist package.json files..."
+  for pkg in dist/packages/core/*/package.json dist/packages/http/*/package.json dist/packages/tooling/*/package.json; do
+    if [ -f "$pkg" ]; then
+      update_package "$pkg"
+    fi
+  done
+fi
+
+echo "✅ Version set to $FULL_VERSION for all packages"

package/bin/setup-claude-patterns.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+set -e
+
+# Setup Claude pattern files by creating symlinks
+# This script runs as postinstall to make Claude documentation available
+
+# Detect project root
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if [[ "$SCRIPT_DIR" == *"node_modules/@webpieces/dev-config"* ]]; then
+  # Running in consumer project (from node_modules)
+  PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+  PATTERNS_DIR="$SCRIPT_DIR/../patterns"
+else
+  # Running in webpieces-ts workspace
+  PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+  PATTERNS_DIR="$PROJECT_ROOT/packages/tooling/dev-config/patterns"
+fi
+
+cd "$PROJECT_ROOT" || exit 1
+
+echo "🔗 Setting up Claude pattern files..."
+
+# Create .claude directory if it doesn't exist
+mkdir -p .claude
+
+# Check if patterns exist
+if [ ! -f "$PATTERNS_DIR/CLAUDE.md" ]; then
+  echo "⚠️  Warning: CLAUDE.md not found in patterns directory"
+  echo "   Expected: $PATTERNS_DIR/CLAUDE.md"
+else
+  # Create relative symlink to CLAUDE.md
+  echo "   Creating symlink for CLAUDE.md..."
+  ln -sf "$PATTERNS_DIR/CLAUDE.md" .claude/CLAUDE.md
+  echo "   ✅ .claude/CLAUDE.md"
+fi
+
+if [ ! -f "$PATTERNS_DIR/claude.patterns.md" ]; then
+  echo "⚠️  Warning: claude.patterns.md not found in patterns directory"
+  echo "   Expected: $PATTERNS_DIR/claude.patterns.md"
+else
+  # Create relative symlink to claude.patterns.md
+  echo "   Creating symlink for claude.patterns.md..."
+  ln -sf "$PATTERNS_DIR/claude.patterns.md" .claude/claude.patterns.md
+  echo "   ✅ .claude/claude.patterns.md"
+fi
+
+echo ""
+echo "✅ Claude pattern files are available in .claude/"
+echo "   These files are symlinked from @webpieces/dev-config"
+echo "   They will auto-update when you upgrade the package"

package/bin/start.sh

@@ -0,0 +1,107 @@
+#!/bin/bash
+
+# Start script for webpieces-ts server
+# Path-agnostic version that works from both workspace and node_modules
+
+PORT=${1:-8080}
+LOG_FILE="tmp/server.log"
+PID_FILE="/tmp/webpieces-ts-server.pid"
+
+echo "Starting webpieces-ts server on port $PORT..."
+echo "Logs: $LOG_FILE"
+
+# Check if already running
+if [ -f "$PID_FILE" ]; then
+    if kill -0 $(cat "$PID_FILE") 2>/dev/null; then
+        echo "❌ Server is already running (PID: $(cat $PID_FILE))"
+        exit 1
+    else
+        echo "⚠️ Removing stale PID file"
+        rm -f "$PID_FILE"
+    fi
+fi
+
+if lsof -Pi :$PORT -sTCP:LISTEN -t >/dev/null ; then
+    echo "❌ Port $PORT is already in use"
+    exit 1
+fi
+
+# Detect project root based on where script is running from
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if [[ "$SCRIPT_DIR" == *"node_modules/@webpieces/dev-config"* ]]; then
+  # Running in consumer project (from node_modules)
+  PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+else
+  # Running in webpieces-ts workspace
+  PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+fi
+
+echo "Project root: $PROJECT_ROOT"
+cd "$PROJECT_ROOT" || exit 1
+
+# Build the server
+echo "Building server..."
+npx nx build example-app
+
+if [ $? -ne 0 ]; then
+    echo "❌ Build failed"
+    exit 1
+fi
+
+echo "✅ Build completed successfully"
+
+# Create symlinks for @webpieces libraries (required for production build)
+echo "Creating @webpieces library symlinks..."
+rm -rf node_modules/@webpieces/*
+mkdir -p node_modules/@webpieces
+
+# Create symlinks to dist packages
+ln -sf "$(pwd)/dist/packages/core/core-context" node_modules/@webpieces/core-context
+ln -sf "$(pwd)/dist/packages/core/core-meta" node_modules/@webpieces/core-meta
+ln -sf "$(pwd)/dist/packages/http/http-routing" node_modules/@webpieces/http-routing
+ln -sf "$(pwd)/dist/packages/http/http-filters" node_modules/@webpieces/http-filters
+ln -sf "$(pwd)/dist/packages/http/http-server" node_modules/@webpieces/http-server
+
+echo "✅ Symlinks created successfully"
+
+# Create tmp directory for logs
+mkdir -p tmp
+
+# Run the production build (with reflect-metadata loaded first)
+echo "Starting server..."
+NODE_ENV=development PORT=$PORT node -r reflect-metadata dist/apps/example-app/src/server.js > $LOG_FILE 2>&1 &
+SERVER_PID=$!
+
+# Save PID
+echo $SERVER_PID > $PID_FILE
+
+echo "Started server with PID: $SERVER_PID"
+echo "Waiting for server to be ready..."
+
+# Monitor log for ready message
+for i in {1..60}; do
+    if grep -q "listening on" $LOG_FILE 2>/dev/null; then
+        echo "✅ Server is ready on port $PORT"
+        echo "✅ Process PID: $SERVER_PID"
+        echo "✅ Tail logs with: tail -f $LOG_FILE"
+        exit 0
+    fi
+
+    # Check if process is still alive
+    if ! kill -0 $SERVER_PID 2>/dev/null; then
+        echo "❌ Server process died unexpectedly!"
+        echo "Last 20 lines of log:"
+        tail -n 20 $LOG_FILE
+        exit 1
+    fi
+
+    sleep 1
+done
+
+echo "⚠️  Server started but ready message not seen"
+echo "Last 20 lines of log:"
+tail -n 20 $LOG_FILE
+echo ""
+echo "Server may still be starting. Check logs with: tail -f $LOG_FILE"
+exit 0

package/bin/stop.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+
+# Stop script for webpieces-ts server
+# Path-agnostic version that works from both workspace and node_modules
+
+PID_FILE="/tmp/webpieces-ts-server.pid"
+
+echo "Stopping webpieces-ts server..."
+
+# Check if PID file exists
+if [ ! -f "$PID_FILE" ]; then
+    echo "⚠️  No PID file found. Server may not be running."
+    echo "Checking for any running server processes..."
+
+    # Try to find and kill any running server processes
+    pkill -f "node -r reflect-metadata dist/apps/example-app/src/server.js"
+
+    if [ $? -eq 0 ]; then
+        echo "✅ Killed running server process(es)"
+    else
+        echo "❌ No running server found"
+    fi
+
+    exit 0
+fi
+
+# Read PID
+SERVER_PID=$(cat "$PID_FILE")
+
+# Check if process is running
+if ! kill -0 "$SERVER_PID" 2>/dev/null; then
+    echo "⚠️  Process $SERVER_PID is not running (stale PID file)"
+    rm -f "$PID_FILE"
+    exit 0
+fi
+
+# Try graceful shutdown first (SIGTERM)
+echo "Sending SIGTERM to process $SERVER_PID..."
+kill "$SERVER_PID"
+
+# Wait up to 10 seconds for graceful shutdown
+for i in {1..10}; do
+    if ! kill -0 "$SERVER_PID" 2>/dev/null; then
+        echo "✅ Server stopped gracefully"
+        rm -f "$PID_FILE"
+        exit 0
+    fi
+    sleep 1
+done
+
+# If still running, force kill (SIGKILL)
+echo "⚠️  Server didn't stop gracefully, forcing shutdown..."
+kill -9 "$SERVER_PID" 2>/dev/null
+
+# Wait a bit more
+sleep 1
+
+if ! kill -0 "$SERVER_PID" 2>/dev/null; then
+    echo "✅ Server stopped (forced)"
+    rm -f "$PID_FILE"
+    exit 0
+else
+    echo "❌ Failed to stop server"
+    exit 1
+fi

package/bin/use-local-webpieces.sh

@@ -0,0 +1,89 @@
+#!/bin/bash
+set -e
+
+# Switch to local webpieces packages for development
+# This script links to local dist/ packages instead of published npm packages
+
+# Detect project root
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if [[ "$SCRIPT_DIR" == *"node_modules/@webpieces/dev-config"* ]]; then
+  # Running in consumer project
+  PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+else
+  # Running in webpieces-ts workspace
+  PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+fi
+
+cd "$PROJECT_ROOT" || exit 1
+
+echo "🔗 Switching to local @webpieces packages..."
+
+# Check if WEBPIECES_ROOT environment variable is set
+if [ -z "$WEBPIECES_ROOT" ]; then
+  echo "❌ WEBPIECES_ROOT environment variable not set"
+  echo "   Please set it to your webpieces-ts directory:"
+  echo "   export WEBPIECES_ROOT=/path/to/webpieces-ts"
+  exit 1
+fi
+
+if [ ! -d "$WEBPIECES_ROOT/dist/packages" ]; then
+  echo "❌ webpieces-ts dist/ directory not found at: $WEBPIECES_ROOT/dist/packages"
+  echo "   Have you built webpieces-ts? Run: npm run build"
+  exit 1
+fi
+
+# Remove existing @webpieces packages
+echo "   Removing published @webpieces packages..."
+rm -rf node_modules/@webpieces/*
+mkdir -p node_modules/@webpieces
+
+# Create symlinks to local dist packages
+echo "   Creating symlinks to local packages..."
+
+# Core packages
+if [ -d "$WEBPIECES_ROOT/dist/packages/core/core-context" ]; then
+  ln -sf "$WEBPIECES_ROOT/dist/packages/core/core-context" node_modules/@webpieces/core-context
+  echo "   ✅ core-context"
+fi
+
+if [ -d "$WEBPIECES_ROOT/dist/packages/core/core-meta" ]; then
+  ln -sf "$WEBPIECES_ROOT/dist/packages/core/core-meta" node_modules/@webpieces/core-meta
+  echo "   ✅ core-meta"
+fi
+
+# HTTP packages
+if [ -d "$WEBPIECES_ROOT/dist/packages/http/http-routing" ]; then
+  ln -sf "$WEBPIECES_ROOT/dist/packages/http/http-routing" node_modules/@webpieces/http-routing
+  echo "   ✅ http-routing"
+fi
+
+if [ -d "$WEBPIECES_ROOT/dist/packages/http/http-filters" ]; then
+  ln -sf "$WEBPIECES_ROOT/dist/packages/http/http-filters" node_modules/@webpieces/http-filters
+  echo "   ✅ http-filters"
+fi
+
+if [ -d "$WEBPIECES_ROOT/dist/packages/http/http-server" ]; then
+  ln -sf "$WEBPIECES_ROOT/dist/packages/http/http-server" node_modules/@webpieces/http-server
+  echo "   ✅ http-server"
+fi
+
+if [ -d "$WEBPIECES_ROOT/dist/packages/http/http-client" ]; then
+  ln -sf "$WEBPIECES_ROOT/dist/packages/http/http-client" node_modules/@webpieces/http-client
+  echo "   ✅ http-client"
+fi
+
+if [ -d "$WEBPIECES_ROOT/dist/packages/http/http-api" ]; then
+  ln -sf "$WEBPIECES_ROOT/dist/packages/http/http-api" node_modules/@webpieces/http-api
+  echo "   ✅ http-api"
+fi
+
+# Tooling packages
+if [ -d "$WEBPIECES_ROOT/dist/packages/tooling/dev-config" ]; then
+  ln -sf "$WEBPIECES_ROOT/dist/packages/tooling/dev-config" node_modules/@webpieces/dev-config
+  echo "   ✅ dev-config"
+fi
+
+echo ""
+echo "✅ Successfully switched to local @webpieces packages from: $WEBPIECES_ROOT"
+echo "   To switch back to published packages, run: wp-use-published"