@b9g/shovel 0.2.0-beta.2 → 0.2.0-beta.21

package/CHANGELOG.md

@@ -1,198 +1,210 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [0.2.0-beta] - 2025-11-05
-
-### Added
-
-#### 🚀 Directly Executable Production Builds
-- **Self-contained deployment**: `shovel build` now creates directly executable production builds that don't require `shovel serve`
-- **2-file output**: Production builds generate only `server.js` (executable) and `package.json` (dependencies)
-- **Platform bootstrapping**: Automatic platform detection and ServiceWorker environment setup
-- **Zero-config deployment**: Run `chmod +x server.js && ./server.js` after `npm install` in the dist directory
-
-#### 🌐 Complete ServiceWorker API Implementation
-- **Full ServiceWorker globals**: Implemented `self`, `addEventListener`, `removeEventListener`, `dispatchEvent`
-- **ServiceWorker lifecycle**: Proper `install` and `activate` event handling
-- **ServiceWorker APIs**: Implemented `self.skipWaiting()` and `self.clients` with environment-aware behavior
-- **Web standards compliance**: All APIs follow web platform standards, not runtime-specific implementations
-
-#### 🏗️ New Bucket Architecture
-- **`self.buckets` API**: Replaced `self.dirs` with standardized bucket interface for filesystem access
-- **Factory pattern**: Dynamic adapter loading for different storage backends (memory, local, S3, R2)
-- **Unified interface**: All storage adapters implement the same `Bucket` interface
-- **`getDirectoryHandle(name)` API**: Standardized directory access following File System Access API patterns
-
-#### 📦 Asset Import Improvements
-- **`assetBase` import attribute**: New syntax for asset imports with base path resolution
-- **Automatic asset processing**: Assets are automatically copied and processed during build
-- **Import transformation**: `import './style.css' with { assetBase: true }` generates proper asset URLs
-- **Manifest generation**: Asset manifests track all processed assets with metadata
-
-#### 🧪 Enhanced Cache System
-- **Redis cache adapter**: Full Redis support with connection pooling and error handling
-- **Multi-threaded coordination**: PostMessage-based cache coordination for worker environments
-- **Platform-agnostic types**: Separated web standard types from platform-specific implementations
-- **Factory pattern**: Dynamic cache adapter loading matching filesystem patterns
-
-#### 🔧 Type System Improvements
-- **Separated type imports**: Platform-specific types only in platform packages, web standard types in shared packages
-- **TypeScript configuration**: Fixed Headers iteration and other compatibility issues with proper lib configuration
-- **Comprehensive type checking**: All packages now pass strict TypeScript compilation
-- **Web standard prioritization**: Chose webworker types over runtime-specific types for compatibility
-
-#### ⚡ Performance & Production Features
-- **TechEmpower Framework Benchmarks**: Official implementation and testing completed
-- **Production scaling**: Multi-worker support with proper resource coordination
-- **Docker deployment**: Complete containerization support with optimized builds
-- **Cloudflare Workers**: Enhanced support with proper ES module bundling
-
-### Changed
-
-#### 💥 Breaking Changes
-- **BREAKING**: Replaced `self.dirs` with `self.buckets` API
-- **BREAKING**: Changed `getBucket()` to `getDirectoryHandle(name: string)` for standardization
-- **BREAKING**: Asset imports now require explicit `assetBase` attribute for base path resolution
-- **BREAKING**: Updated all filesystem adapters to implement new `Bucket` interface
-
-#### 🏗️ Build System Overhaul
-- **Simplified output**: Moved from complex templating to clean esbuild banner approach
-- **Self-contained bundling**: Framework dependencies bundled, app dependencies preserved
-- **Platform detection**: Automatic runtime detection and appropriate adapter loading
-- **Production runtime**: Uses proven development patterns for production consistency
-
-#### 📁 Architecture Improvements
-- **Clean separation**: Platform-specific code isolated from shared/core packages
-- **Consistent interfaces**: All adapters follow same patterns (cache, filesystem, platform)
-- **Dynamic loading**: Runtime adapter detection and loading
-- **Environment awareness**: Proper detection of worker vs main thread contexts
-
-### Fixed
-
-- **TypeScript compilation**: Resolved Headers.entries() iteration issues with DOM.Iterable configuration
-- **Cache exports**: Fixed missing factory functions in multi-threaded cache coordination
-- **Platform contamination**: Removed Node.js-specific imports from platform-agnostic packages
-- **Build loops**: Fixed infinite loading where worker.js was trying to load itself
-- **Worker globals**: Proper ServiceWorker environment setup in all execution contexts
-- **Dependency resolution**: Fixed workspace dependency resolution and external bundling
-
-### Technical Details
-
-#### ServiceWorker Implementation
-The ServiceWorker implementation provides full web platform compatibility:
+All notable changes to Shovel will be documented in this file.
 
-```typescript
-// Environment-aware skipWaiting implementation
-const skipWaiting = async (): Promise<void> => {
-  if (options.isDevelopment && options.hotReload) {
-    console.info('[ServiceWorker] skipWaiting() - triggering hot reload');
-    await options.hotReload();
-  } else if (!options.isDevelopment) {
-    console.info('[ServiceWorker] skipWaiting() - production graceful restart not implemented');
-  }
-};
-```
+## [0.2.0-beta.12] - 2026-01-14
 
-#### Build System Architecture
-The new build system uses esbuild banners for clean, self-contained executables:
-
-```javascript
-// Production bootstrap injected via esbuild banner
-buildConfig.banner = {
-  js: `#!/usr/bin/env node
-import { ServiceWorkerRuntime, createServiceWorkerGlobals, createBucketStorage } from '@b9g/platform';
-
-if (import.meta.url === \`file://\${process.argv[1]}\`) {
-  const runtime = new ServiceWorkerRuntime();
-  const buckets = createBucketStorage(process.cwd());
-  
-  createServiceWorkerGlobals(runtime, { buckets });
-  // ... HTTP server setup using proven patterns
-}
-// User's ServiceWorker code follows...`
-};
-```
+### Breaking Changes
 
-#### Type Architecture
-Clean separation ensures web standard compatibility:
+- **`shovel activate` command removed** - Use `shovel build --lifecycle` instead
+- **`loadServiceWorker()` removed** - Use `platform.serviceWorker.register()` instead
+- **`getEntryWrapper()` removed** - Use `getProductionEntryPoints()` instead
 
-```typescript
-// Platform-agnostic cache using web standards
-interface WorkerLike {
-  postMessage(value: any): void;
-  on(event: string, listener: (data: any) => void): void;
-}
+### Build System Unification
 
-// Web standard encoding instead of Node.js Buffer
-body: btoa(String.fromCharCode(...new Uint8Array(body))),
-totalSize += new TextEncoder().encode(value).length;
-```
+Major refactor of the build system to be platform-driven and unified across all commands.
 
-### Migration Guide
+- **New `ServerBundler` class** - Unified bundler replacing separate build/watch logic
+- **Platform-driven entry points** - Platforms define their output structure via `getProductionEntryPoints()`:
+  - Node/Bun: `{ index: "<supervisor>", worker: "<worker>" }` - two files
+  - Cloudflare: `{ worker: "<code>" }` - single file
+- **Deleted `activate` command** - Replaced with `shovel build --lifecycle` flag
+  - `--lifecycle` - runs activate stage (default)
+  - `--lifecycle install` - runs install stage only
 
-#### From `self.dirs` to `self.buckets`
-```typescript
-// Before
-const distDir = await self.dirs.getBucket();
+### API Changes
 
-// After  
-const distBucket = await self.buckets.getDirectoryHandle('dist');
-```
+- **New `platform.serviceWorker.register()` API** - Mirrors browser's `navigator.serviceWorker.register()`
+- **Deleted `loadServiceWorker()`** - Use `serviceWorker.register()` instead
+- **New `platform.listen()` / `close()`** - Server lifecycle management
+- **New `runLifecycle()` and `dispatchRequest()`** - Public runtime utilities
 
-#### Asset Imports
-```typescript
-// Before
-import './style.css' with { url: true };
+### Code Quality
 
-// After
-import './style.css' with { assetBase: true };
-```
+- Extracted `mergeConfigWithDefaults()` helper to reduce duplication
+- Added JSDoc to platform `create*` methods documenting defaults
+- Standardized import organization (node builtins → external → @b9g/* → relative)
+- Renamed `isDynamicCode` → `containsRuntimeExpressions` for clarity
 
-#### Deployment
-```bash
-# Before
-shovel build
-shovel serve dist/
+### Package Updates
 
-# After
-shovel build
-cd dist && npm install
-chmod +x server.js && ./server.js
-```
+- `@b9g/platform` → 0.1.14-beta.0
+- `@b9g/platform-node` → 0.1.14-beta.0
+- `@b9g/platform-bun` → 0.1.12-beta.0
+- `@b9g/platform-cloudflare` → 0.1.12-beta.0
 
-### Performance
+### Deleted Files
 
-- **TechEmpower Benchmarks**: Competitive performance in official framework benchmarks
-- **Production scaling**: Multi-worker coordination with proper resource management
-- **Build optimization**: Faster builds with simplified bundling strategy
-- **Runtime efficiency**: Direct execution without CLI overhead
+- `src/commands/activate.ts` - Replaced by `build --lifecycle`
+- `src/utils/watcher.ts` - Merged into `ServerBundler`
+- `src/plugins/shovel.ts` - Split into `config.ts` + `entry.ts`
+- `packages/platform/test/single-threaded.test.ts`
+- `SingleThreadedRuntime` class - All platforms now use `ServiceWorkerPool`
 
-### Developer Experience
+---
 
-- **Zero-config deployment**: No configuration required for basic deployment
-- **Proven patterns**: Production builds use same patterns as development
-- **Better error messages**: Improved error handling and diagnostics
-- **Type safety**: Comprehensive TypeScript support across all packages
+## [0.2.0-beta.11] - 2026-01-10
+
+### Changes since beta.10
+- **ESBuild configuration support (#18)** - Custom esbuild options in shovel.json
+- **Config expression syntax** - `$PORT || 3000`, `$DATABASE_URL ?? null`
+- **Null fallback fix** - Allow intentional null fallbacks in config expressions
+- **DatabaseStorage API redesign** - New open/get pattern with IndexedDB-style migrations
+- **Migrated from Drizzle to @b9g/zen** - Simpler, more portable database layer
+- **Logging DX improvements** - Better defaults, consolidated categories
+- **`impl` key unification** - Simplified resource configuration
+- **CI/lint enforcement** - ESLint and Prettier standardized
+- **Documentation** - Comprehensive docs for all APIs
+
+### Package Updates
+- `@b9g/router` → 0.2.0-beta.1 (CORS middleware, trailingSlash moved)
+- `@b9g/node-webworker` → 0.2.0-beta.1 (CloseEvent, onclose, env option)
+- `@b9g/cache-redis` → 0.2.0-beta.1 (logger category fix)
+- `@b9g/assets` → 0.2.0-beta.0
+- `@b9g/async-context` → 0.2.0-beta.0
+- `@b9g/cache` → 0.2.0-beta.0
+- `@b9g/http-errors` → 0.2.0-beta.0
+- `@b9g/match-pattern` → 0.2.0-beta.0
 
 ---
 
-## [0.1.10] - Previous Release
+## [0.2.0-beta.10] - Previous Beta
+
+This is a major release that establishes Shovel as a complete ServiceWorker-based meta-framework. The 0.2.0 beta introduces locked-down APIs for core packages, a unified configuration system, and comprehensive platform support.
+
+### Breaking Changes
+
+- **`self.buckets` renamed to `self.directories`** - The file system API now uses `directories` to align with web standards terminology
+- **`@b9g/router` middleware moved** - `trailingSlash` middleware moved from main export to `@b9g/router/middleware`
+- **`self.loggers.get()` signature changed** - Now takes an array: `self.loggers.get(["app", "db"])` instead of dot notation
+- **Config `module`/`export` unified to `impl`** - Resource configurations now use a single `impl` key for reified implementations
 
-### Added
-- Initial CLI implementation
-- Basic platform abstraction
-- Development server functionality
-- Asset processing pipeline
+### New Features
 
-### Fixed
-- Various development workflow issues
-- Build system stability
-- Type definitions
+#### Consistent Worker Execution Model (#17)
+ServiceWorker code now ALWAYS runs in a worker thread, never the main thread. This ensures:
+- Same globals/environment in dev and prod (eliminates mode-only bugs)
+- Worker isolation preserved
+- Simplified mental model
+
+#### ESBuild Configuration Support (#18)
+Custom ESBuild options can now be specified in `shovel.json`:
+```json
+{
+  "esbuild": {
+    "external": ["lightningcss"],
+    "define": { "DEBUG": "true" }
+  }
+}
+```
+
+#### Config Expression Syntax
+Environment variables and expressions in `shovel.json`:
+```json
+{
+  "port": "$PORT || 3000",
+  "databases": {
+    "main": {
+      "url": "$DATABASE_URL"
+    }
+  }
+}
+```
+
+#### Comprehensive Logging System
+- Built-in LogTape integration with console sink by default
+- Configurable sinks (file, OpenTelemetry, Sentry, etc.)
+- Category-based log levels
+- `shovel` category logs at `info` level by default
+
+#### Database Storage API
+New `self.databases` API with IndexedDB-style migrations:
+```typescript
+self.addEventListener("activate", (event) => {
+  event.waitUntil(
+    databases.open("main", 2, (e) => {
+      e.waitUntil(e.db.exec`CREATE TABLE users (...)`);
+    })
+  );
+});
+
+// In fetch handlers
+const db = databases.get("main");
+const users = await db.all`SELECT * FROM users`;
+```
+
+#### CORS Middleware
+New CORS middleware in `@b9g/router/middleware`:
+```typescript
+import { cors } from "@b9g/router/middleware";
+router.use(cors({ origin: "https://example.com" }));
+```
+
+### Package Updates
+
+#### Locked at 0.2.0-beta.0 (API stable)
+- `@b9g/async-context` - AsyncContext polyfill
+- `@b9g/match-pattern` - URLPattern implementation
+- `@b9g/assets` - Static asset pipeline with content hashing
+- `@b9g/cache` - Cache API implementation (memory, postmessage)
+- `@b9g/http-errors` - HTTP error classes
+
+#### Updated to 0.2.0-beta.1
+- `@b9g/router` - Added CORS middleware, moved trailingSlash to /middleware
+- `@b9g/node-webworker` - Added CloseEvent, onclose handler, env option
+- `@b9g/cache-redis` - Logger category updates
+
+#### Still Evolving (0.1.x)
+- `@b9g/platform` - Core runtime and platform abstraction
+- `@b9g/platform-bun` - Bun platform adapter
+- `@b9g/platform-node` - Node.js platform adapter
+- `@b9g/platform-cloudflare` - Cloudflare Workers adapter
+- `@b9g/filesystem` - File System Access API implementation
+- `@b9g/filesystem-s3` - S3 filesystem adapter
+
+### CLI Changes
+
+- `shovel develop` - Development server with hot reload (note: `dev` alias removed)
+- `shovel build` - Production build (use `--lifecycle` flag to run lifecycle events)
+- Removed `--verbose` flags (use logging config instead)
+
+### Infrastructure
+
+- Migrated from Drizzle ORM to `@b9g/zen` for database operations
+- Added GitHub Actions CI with parallel test execution
+- ESLint and Prettier configuration standardized
+- Comprehensive test suites with `bun:test`
+
+### Documentation
+
+New documentation pages:
+- Getting Started guide
+- CLI reference
+- Configuration (shovel.json) reference
+- Deployment guide
+- ServiceWorker lifecycle
+- Routing and middleware
+- Storage APIs (databases, caches, directories)
+- Cookies and AsyncContext
 
 ---
 
-For detailed technical documentation, see the [README.md](README.md) and individual package documentation.
+## [0.1.x] - Previous Releases
+
+Initial development releases establishing core architecture:
+- ServiceWorker-based request handling
+- Platform abstraction layer
+- Router with generator-based middleware
+- Cache API implementations
+- File System Access API
+- Hot reload in development