packwise-skills 1.0.0

package/sub-skills/backend/java-spring.md

@@ -0,0 +1,241 @@
+# Java/Spring Boot Build Sub-Skill
+
+Build and package Java backend services using Spring Boot, Quarkus, or Micronaut.
+
+**Current version**: Java 21 LTS / 22 / Spring Boot 3.5.x / Quarkus 3.37.x / Micronaut 5.x (2025-2026)
+
+## When to Use
+
+- Enterprise backend services
+- REST APIs / GraphQL APIs
+- Microservices architecture
+- Team has Java/Kotlin experience
+- Need mature ecosystem (Spring ecosystem)
+
+## Spring Boot Build
+
+### Maven Build
+
+```bash
+# Clean + package
+mvn clean package -DskipTests
+# Output: target/myapp-1.0.0.jar
+
+# Run
+java -jar target/myapp-1.0.0.jar
+
+# Build with specific profile
+mvn clean package -Pproduction
+```
+
+### Gradle Build
+
+```bash
+./gradlew clean build -x test
+# Output: build/libs/myapp-1.0.0.jar
+
+# Run
+java -jar build/libs/myapp-1.0.0.jar
+```
+
+### Fat JAR vs Thin JAR
+
+| Type | Size | Startup | Best For |
+|------|------|---------|----------|
+| Fat JAR (default) | 50–200MB | Standard | Simple deployment, Docker |
+| Thin JAR | < 10MB | Faster (dependencies cached) | Multiple services sharing deps |
+| Native Image (GraalVM) | 30–80MB | Ultra fast (< 1s) | Serverless, CLI, microservices |
+
+### GraalVM Native Image
+
+```bash
+# Install GraalVM
+sdk install java 21.0.2-graal
+
+# Maven plugin (in pom.xml):
+# <plugin>
+#   <groupId>org.graalvm.buildtools</groupId>
+#   <artifactId>native-maven-plugin</artifactId>
+# </plugin>
+
+mvn -Pnative native:compile
+# Output: target/myapp (native binary, no JVM required)
+```
+
+## Docker
+
+```dockerfile
+FROM eclipse-temurin:21-jdk-jammy AS builder
+WORKDIR /app
+COPY pom.xml .
+COPY src/ src/
+RUN apt-get update && apt-get install -y maven && mvn clean package -DskipTests
+
+FROM eclipse-temurin:21-jre-jammy
+WORKDIR /app
+COPY --from=builder /app/target/*.jar app.jar
+RUN groupadd -r appuser && useradd -r -g appuser appuser && \
+    chown -R appuser:appuser /app
+USER appuser
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=3s CMD curl -f http://localhost:8080/actuator/health || exit 1
+ENTRYPOINT ["java", "-jar", "app.jar"]
+```
+
+```dockerfile
+# GraalVM native image Docker (smaller, faster)
+FROM ghcr.io/graalvm/native-image-community:21 AS builder
+WORKDIR /app
+COPY target/myapp .
+RUN native-image --static -o myapp-native myapp
+
+FROM debian:bookworm-slim
+COPY --from=builder /app/myapp-native /myapp
+RUN groupadd -r appuser && useradd -r -g appuser appuser
+USER appuser
+EXPOSE 8080
+CMD ["/myapp"]
+```
+
+## jpackage (Native Installers for Java Desktop/CLI Apps)
+
+`jpackage` is a JDK 14+ tool that creates native platform installers from JAR files — no JVM required on the target machine.
+
+```bash
+# Prerequisites: JDK 17+ with jpackage (included in JDK 14+)
+
+# 1. Build fat JAR first
+mvn clean package -DskipTests
+
+# 2. Create native installer
+# Windows (.exe / .msi)
+jpackage --type exe \
+  --input target/ \
+  --main-jar myapp-1.0.0.jar \
+  --main-class com.example.Main \
+  --name MyApp \
+  --app-version 1.0.0 \
+  --icon src/main/resources/icon.ico \
+  --win-shortcut \
+  --win-menu
+
+# macOS (.pkg / .dmg)
+jpackage --type dmg \
+  --input target/ \
+  --main-jar myapp-1.0.0.jar \
+  --main-class com.example.Main \
+  --name MyApp \
+  --app-version 1.0.0 \
+  --icon src/main/resources/icon.icns \
+  --mac-package-identifier com.example.myapp
+
+# Linux (.deb / .rpm)
+jpackage --type deb \
+  --input target/ \
+  --main-jar myapp-1.0.0.jar \
+  --main-class com.example.Main \
+  --name MyApp \
+  --app-version 1.0.0 \
+  --icon src/main/resources/icon.png \
+  --linux-shortcut
+```
+
+### jpackage vs Docker vs GraalVM Native Image
+
+| Approach | Output | JVM Required? | Size | Startup | Best For |
+|----------|--------|--------------|------|---------|----------|
+| jpackage | .exe/.msi/.dmg/.deb/.rpm | No (bundled JRE) | 40-100MB | 1-3s | Desktop/CLI distribution to non-technical users |
+| Docker | Container image | Yes (in container) | 100-300MB | 2-5s | Server deployment |
+| GraalVM Native | Native binary | No | 30-80MB | < 1s | Serverless, CLI, microservices |
+| Fat JAR | .jar file | Yes (user must install JDK) | 50-200MB | 2-8s | Developer tools, server deployment |
+
+### jpackage with Spring Boot (Special Handling)
+
+Spring Boot fat JARs have a nested JAR structure that `jpackage` doesn't handle well. Use the Spring Boot thin launcher or repack:
+
+```xml
+<!-- pom.xml — Use Spring Boot thin launcher -->
+<plugin>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-maven-plugin</artifactId>
+    <configuration>
+        <layout>ZIP</layout> <!-- Thin layout for jpackage compatibility -->
+    </configuration>
+</plugin>
+```
+
+```bash
+# Build thin JAR + dependencies
+mvn clean package -DskipTests
+
+# jpackage with classpath
+jpackage --type exe \
+  --input target/ \
+  --main-jar myapp-1.0.0.jar \
+  --main-class org.springframework.boot.loader.launch.JarLauncher \
+  --name MyApp \
+  --app-version 1.0.0
+```
+
+### Common Pitfalls (jpackage)
+
+| Issue | Fix |
+|-------|-----|
+| "jpackage not found" | Ensure JDK 17+ is installed (not JRE); `jpackage` is in `JAVA_HOME/bin` |
+| Spring Boot JAR fails to launch | Use `layout: ZIP` in spring-boot-maven-plugin; or repack with `maven-shade-plugin` |
+| Missing native libraries | Add `--java-options "-Djava.library.path=/app/libs"` |
+| macOS notarization fails | Sign the .pkg with `codesign` before notarizing; jpackage doesn't auto-sign |
+| Windows SmartScreen warning | Sign the .exe with EV/OV certificate after jpackage creates it |
+| Large installer size | Use `--jlink-options "--strip-debug --compress zip-6"` to reduce bundled JRE size |
+| Icon not showing | Ensure icon format is correct (.ico for Windows, .icns for macOS, .png for Linux) |
+
+## Quarkus Build
+
+```bash
+# Create project (replace 3.37 with latest Quarkus version)
+mvn io.quarkus.platform:quarkus-maven-plugin:3.37:create -DprojectGroupId=com.example -DprojectArtifactId=myapp
+
+# JVM mode
+mvn clean package
+java -jar target/quarkus-run.jar
+
+# Native mode (requires GraalVM)
+mvn clean package -Pnative
+./target/myapp
+```
+
+## Micronaut Build
+
+```bash
+# Create project
+mn create-app com.example.myapp
+
+# Build
+./gradlew clean build
+
+# Native image
+./gradlew nativeCompile
+# Output: build/native/nativeCompile/myapp
+```
+
+## Framework Comparison
+
+| Feature | Spring Boot | Quarkus | Micronaut |
+|---------|------------|---------|----------|
+| Maturity | Most mature | Growing fast | Growing |
+| Startup time | 2–8s (JVM), < 1s (native) | < 1s (native) | < 1s (native) |
+| Memory | 200–500MB (JVM) | 30–80MB (native) | 30–80MB (native) |
+| Native image | Supported (GraalVM) | First-class | First-class |
+| Ecosystem | Largest (Spring) | Good (Vert.x-based) | Good (Netty-based) |
+| Best for | Enterprise, large teams | Cloud-native, serverless | Microservices, serverless |
+
+## Common Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| JAR too large (> 200MB) | Exclude unused dependencies; use Spring Boot thin launcher |
+| GraalVM reflection errors | Add `reflect-config.json`; use `@RegisterForReflection` (Quarkus) |
+| Slow startup in containers | Use CDS (Class Data Sharing); consider native image |
+| Port conflict | Set `server.port` in `application.properties` or `SERVER_PORT` env |
+| Database connection pool exhausted | Configure HikariCP pool size; add connection timeout |
+| Actuator endpoints not exposed | Add `management.endpoints.web.exposure.include=health,info` |

package/sub-skills/backend/node-server.md

@@ -0,0 +1,164 @@
+# Node.js Backend Build Sub-Skill
+
+Build Node.js backend services (Express/NestJS/Fastify/Koa/Hono).
+
+**Current version**: Node.js 26 LTS / 22 LTS (2025-2026)
+
+> ⚠️ **Breaking changes since Node 22**: v23 enables `require(esm)` by default. v26 removes `http.writeHeader()` (use `writeHead()`), removes legacy `_stream_*` modules, enables Temporal API, upgrades V8 to 14.6 and Undici to 8.0. Native modules compiled for Node 22 need recompilation for Node 26.
+
+## When to Use
+
+- REST API / GraphQL API service
+- WebSocket service
+- Microservice / API gateway
+- Full-stack application backend
+- Serverless functions
+
+## Framework Quick Start
+
+### Express (Most Popular)
+
+```javascript
+const express = require('express');
+const app = express();
+app.use(express.json());
+app.get('/health', (req, res) => res.json({ status: 'ok' }));
+app.listen(3000);
+```
+
+### Fastify (High Performance)
+
+```javascript
+import Fastify from 'fastify';
+const app = Fastify({ logger: true });
+app.get('/health', async () => ({ status: 'ok' }));
+await app.listen({ port: 3000 });
+```
+
+### NestJS (Enterprise, TypeScript-first)
+
+```bash
+npm i -g @nestjs/cli
+nest new my-app
+npm run build    # outputs to dist/
+npm run start:prod
+```
+
+### Hono (Edge-first, ultra-lightweight)
+
+```javascript
+import { Hono } from 'hono';
+const app = new Hono();
+app.get('/health', (c) => c.json({ status: 'ok' }));
+export default app;
+```
+
+### Framework Comparison
+
+| Framework | Performance | TypeScript | Ecosystem | Best For |
+|-----------|------------|-----------|-----------|----------|
+| Express | Good | Optional | Largest | General purpose, tutorials |
+| Fastify | High | First-class | Large | Performance-critical APIs |
+| NestJS | Good | Required (default) | Large | Enterprise, complex architecture |
+| Koa | Good | Optional | Moderate | Minimalist Express alternative |
+| Hono | Highest | First-class | Growing | Edge runtime, serverless |
+
+## Build
+
+```bash
+# Express/Fastify/Koa/Hono: run directly (no build step for JS)
+node dist/server.js
+
+# TypeScript projects
+npx tsc                    # Compile TypeScript to JS
+# or esbuild (faster)
+npx esbuild src/index.ts --bundle --platform=node --format=cjs --outfile=dist/server.cjs
+# or tsx (run TypeScript directly, development)
+npx tsx src/index.ts
+
+# NestJS: requires compilation
+npm run build  # outputs to dist/
+
+# Bun runtime (alternative to Node.js, faster)
+bun run src/index.ts
+```
+
+## Docker
+
+```dockerfile
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:22-alpine
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./
+RUN apk add --no-cache tini && \
+    addgroup -S appgroup && adduser -S appuser -G appgroup && \
+    chown -R appuser:appgroup /app
+USER appuser
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
+ENTRYPOINT ["/sbin/tini", "--"]
+CMD ["node", "dist/server.js"]
+```
+
+## PM2 Process Manager
+
+```bash
+npm install -g pm2
+pm2 start dist/server.js --name myapp -i max   # Cluster mode (all CPU cores)
+pm2 start dist/server.js --name myapp -i 4     # 4 instances
+pm2 save && pm2 startup                         # Auto-start on reboot
+pm2 logs myapp                                  # View logs
+pm2 monit                                       # Monitoring dashboard
+pm2 reload myapp                                # Zero-downtime restart
+```
+
+## Environment Variables
+
+```javascript
+// Use dotenv for development
+require('dotenv').config();
+
+// Access: process.env.DATABASE_URL, process.env.PORT, etc.
+// NEVER commit .env files to git
+```
+
+```bash
+# Local: .env file (add to .gitignore)
+# Production: platform env vars or secrets manager
+# Type-safe env: use @t3-oss/env-nextjs or zod
+```
+
+## Cloud Platforms
+
+| Platform | Method | Cost | Best For |
+|----------|--------|------|---------|
+| Railway | Git push auto-deploy | Free/pay-as-you-go | Quick deploy |
+| Render | Git push auto-deploy | Free/pay-as-you-go | Quick deploy |
+| Fly.io | Docker deploy | Free/pay-as-you-go | Global edge |
+| Vercel | Serverless Functions | Free/pay-as-you-go | Next.js, API routes |
+| AWS EC2 | PM2/Docker | Per instance | Full control |
+| Aliyun ECS | PM2/Docker | Per instance | China access |
+| Deno Deploy | Git push | Free tier | Hono, edge functions |
+| Bun.sh | `bun run` | Free tier | Ultra-fast startup |
+
+## Common Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| Port in use | `lsof -i :3000` to check; use `kill -9 <PID>` |
+| Memory leak | PM2: `--max-memory-restart 500M`; check for event listener leaks |
+| Process crash loop | Check logs: `pm2 logs`; add error handling middleware |
+| CORS error | `app.use(cors())` with Express; configure allowed origins |
+| HTTPS in production | Nginx reverse proxy + Let's Encrypt (see cloud/docker.md) |
+| `MODULE_NOT_FOUND` | Check `node_modules`; run `npm ci` (not `npm install` in production) |
+| TypeScript path aliases not working | Use `tsc-alias` or `tsconfig-paths` after build |
+| Async error not caught | Use `express-async-errors` or wrap in try/catch |
+| Bun compatibility | Some npm packages don't support Bun; test thoroughly |

package/sub-skills/backend/php-laravel.md

@@ -0,0 +1,175 @@
+# PHP Backend Build Sub-Skill
+
+Build and package PHP backend services (Laravel / Symfony / Slim).
+
+**Current version**: PHP 8.3 / 8.4 / Laravel 11.x / Symfony 7.x (2025-2026)
+
+## When to Use
+
+- Content management systems (WordPress plugins, custom CMS)
+- REST APIs / GraphQL APIs
+- Web applications with server-side rendering
+- Team has PHP experience
+- Shared hosting deployment
+
+## Laravel Build
+
+### Build & Package
+
+```bash
+# Install dependencies
+composer install --no-dev --optimize-autoloader
+
+# Cache configuration (production)
+php artisan config:cache
+php artisan route:cache
+php artisan view:cache
+php artisan event:cache
+
+# Build frontend assets
+npm ci && npm run build
+
+# Create distributable archive
+tar -czf myapp.tar.gz \
+    --exclude='.env' \
+    --exclude='node_modules' \
+    --exclude='tests' \
+    --exclude='.git' \
+    .
+```
+
+### Docker
+
+```dockerfile
+FROM php:8.3-fpm AS builder
+WORKDIR /app
+COPY composer.json composer.lock ./
+RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer && \
+    composer install --no-dev --optimize-autoloader --no-scripts
+COPY . .
+RUN php artisan config:cache && php artisan route:cache && php artisan view:cache
+
+FROM php:8.3-fpm
+WORKDIR /app
+COPY --from=builder /app /app
+RUN groupadd -r appuser && useradd -r -g appuser appuser && \
+    chown -R appuser:appuser /app/storage /app/bootstrap/cache
+USER appuser
+EXPOSE 9000
+HEALTHCHECK --interval=30s --timeout=3s CMD php artisan --version || exit 1
+CMD ["php-fpm"]
+```
+
+### Nginx + PHP-FPM
+
+```nginx
+server {
+    listen 80;
+    server_name example.com;
+    root /app/public;
+    index index.php;
+
+    location / {
+        try_files $uri $uri/ /index.php?$query_string;
+    }
+
+    location ~ \.php$ {
+        fastcgi_pass app:9000;
+        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
+        include fastcgi_params;
+    }
+}
+```
+
+### Shared Hosting Deployment
+
+```bash
+# 1. Run `composer install --no-dev` locally
+# 2. Upload via FTP/SFTP:
+#    - All files EXCEPT: .env.example, .git, node_modules, tests
+# 3. Set document root to `public/` directory
+# 4. Copy .env.example → .env and configure
+# 5. Run: php artisan key:generate
+# 6. Set permissions: chmod -R 775 storage bootstrap/cache
+```
+
+### Laravel Forge / Vapor / Ploi
+
+| Platform | Type | Best For |
+|----------|------|---------|
+| Laravel Forge | VPS management | Full control, traditional hosting |
+| Laravel Vapor | Serverless (AWS Lambda) | Auto-scaling, pay-per-request |
+| Ploi | VPS management | Alternative to Forge |
+
+## Symfony Build
+
+```bash
+# Install dependencies
+composer install --no-dev --optimize-autoloader
+
+# Warm up cache
+php bin/console cache:warmup --env=prod
+
+# Build frontend (if using Encore)
+npm ci && npm run build
+
+# Docker
+docker build -t myapp .
+```
+
+```dockerfile
+FROM php:8.3-fpm AS builder
+WORKDIR /app
+COPY composer.json composer.lock ./
+RUN composer install --no-dev --optimize-autoloader
+COPY . .
+RUN php bin/console cache:warmup --env=prod
+
+FROM php:8.3-fpm
+WORKDIR /app
+COPY --from=builder /app /app
+USER www-data
+EXPOSE 9000
+```
+
+## Slim / Lumen (Micro-frameworks)
+
+```php
+// Slim 4 — minimal API
+use Slim\Factory\AppFactory;
+
+$app = AppFactory::create();
+$app->get('/health', function ($request, $response) {
+    $response->getBody()->write('OK');
+    return $response;
+});
+$app->run();
+```
+
+```bash
+# Build
+composer install --no-dev
+php -S 0.0.0.0:8080 -t public public/index.php
+```
+
+## PHP Distribution Channels
+
+| Channel | Method | Best For |
+|---------|--------|---------|
+| Composer Packagist | `composer publish` | Libraries / packages |
+| Docker Hub | `docker push` | Containerized apps |
+| Shared hosting | FTP/SFTP upload | WordPress, small sites |
+| VPS | `git pull` + `composer install` | Full control |
+| Serverless (Bref) | `vendor/bin/bref deploy` | AWS Lambda |
+
+## Common Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| `composer install` fails in prod | Use `--no-dev`; check PHP version compatibility |
+| 500 error after deploy | Check `.env` config; run `php artisan config:clear` |
+| Storage permissions | `chmod -R 775 storage bootstrap/cache`; set correct owner |
+| OPcache not working | Enable `opcache.enable=1` in php.ini; restart PHP-FPM |
+| Memory limit exceeded | Increase `memory_limit` in php.ini (default 128M, use 256M+) |
+| Asset mix not compiling | Run `npm ci && npm run build`; check `webpack.mix.js` / `vite.config.js` |
+| Shared hosting: `artisan` not available | Use `php artisan` with full path; some hosts restrict CLI |