@b9g/shovel 0.1.10 → 0.2.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,198 @@
+# 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:
+
+```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');
+  }
+};
+```
+
+#### 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...`
+};
+```
+
+#### Type Architecture
+Clean separation ensures web standard compatibility:
+
+```typescript
+// Platform-agnostic cache using web standards
+interface WorkerLike {
+  postMessage(value: any): void;
+  on(event: string, listener: (data: any) => void): void;
+}
+
+// Web standard encoding instead of Node.js Buffer
+body: btoa(String.fromCharCode(...new Uint8Array(body))),
+totalSize += new TextEncoder().encode(value).length;
+```
+
+### Migration Guide
+
+#### From `self.dirs` to `self.buckets`
+```typescript
+// Before
+const distDir = await self.dirs.getBucket();
+
+// After  
+const distBucket = await self.buckets.getDirectoryHandle('dist');
+```
+
+#### Asset Imports
+```typescript
+// Before
+import './style.css' with { url: true };
+
+// After
+import './style.css' with { assetBase: true };
+```
+
+#### Deployment
+```bash
+# Before
+shovel build
+shovel serve dist/
+
+# After
+shovel build
+cd dist && npm install
+chmod +x server.js && ./server.js
+```
+
+### Performance
+
+- **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
+
+### 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.1.10] - Previous Release
+
+### Added
+- Initial CLI implementation
+- Basic platform abstraction
+- Development server functionality
+- Asset processing pipeline
+
+### Fixed
+- Various development workflow issues
+- Build system stability
+- Type definitions
+
+---
+
+For detailed technical documentation, see the [README.md](README.md) and individual package documentation.

package/README.md

@@ -1,12 +1,144 @@
 # Shovel
 
-Shovel is a CLI for building web applications.
+**The ServiceWorker platform for server-side JavaScript.**
 
-## Commands
+Same code. Any runtime. Node.js, Bun, Cloudflare Workers.
 
-- `shovel develop`
+```javascript
+// app.js
+self.addEventListener("fetch", (event) => {
+  event.respondWith(new Response("Hello World"));
+});
+```
 
-- `shovel build`
+```bash
+npx @b9g/shovel develop app.js
+```
 
-- `shovel static`
-  Build a static website.
+## Why Shovel?
+
+Browsers have ServiceWorker. Cloudflare has Workers. Node.js and Bun have... Express?
+
+Shovel brings the ServiceWorker programming model to server-side JavaScript. Write your app once using web standards, deploy it anywhere.
+
+## Web Standards
+
+Shovel implements web platform APIs that server-side JavaScript is missing:
+
+| API | Standard | What it does |
+|-----|----------|--------------|
+| `fetch` event | [Service Workers](https://w3c.github.io/ServiceWorker/) | Request handling |
+| `self.caches` | [Cache API](https://w3c.github.io/ServiceWorker/#cache-interface) | Response caching |
+| `self.buckets` | [FileSystemDirectoryHandle](https://fs.spec.whatwg.org/#api-filesystemdirectoryhandle) | Storage (local, S3, R2) |
+| `self.cookieStore` | [Cookie Store API](https://wicg.github.io/cookie-store/) | Cookie management |
+| `URLPattern` | [URLPattern](https://urlpattern.spec.whatwg.org/) | Route matching (100% WPT) |
+| `AsyncContext.Variable` | [TC39 Stage 2](https://github.com/tc39/proposal-async-context) | Request-scoped state |
+
+Your code uses standards. Shovel makes them work everywhere.
+
+## True Portability
+
+Shovel is a complete meta-framework. Same code, any runtime, any rendering strategy:
+
+- **Server runtimes**: Node.js, Bun, Cloudflare Workers for development and production
+- **Browser ServiceWorkers**: The same app can run as a PWA service worker
+- **Universal rendering**: Dynamic, static, or client-side - link and deploy assets automatically
+
+## Quick Start
+
+```javascript
+// app.js
+import {Router} from "@b9g/router";
+
+const router = new Router();
+
+router.route("/").get(() => new Response("Hello World"));
+
+router.route("/users/:id").get((request, {params}) => {
+  return Response.json({id: params.id});
+});
+
+self.addEventListener("fetch", (event) => {
+  event.respondWith(router.handler(event.request));
+});
+```
+
+```bash
+# Create a new project
+npm create @b9g/shovel my-app
+
+# Development with hot reload
+npx @b9g/shovel develop app.js
+
+# Build for production
+npx @b9g/shovel build app.js --platform=node
+npx @b9g/shovel build app.js --platform=bun
+npx @b9g/shovel build app.js --platform=cloudflare
+```
+
+## Platform APIs
+
+```javascript
+// Cache API - response caching
+const cache = await self.caches.open("my-cache");
+await cache.put(request, response.clone());
+const cached = await cache.match(request);
+
+// File System Access - storage buckets (local, S3, R2)
+const bucket = await self.buckets.open("uploads");
+const file = await bucket.getFileHandle("image.png");
+const contents = await (await file.getFile()).arrayBuffer();
+
+// Cookie Store - cookie management
+const session = await self.cookieStore.get("session");
+await self.cookieStore.set("theme", "dark");
+
+// AsyncContext - request-scoped state without prop drilling
+const requestId = new AsyncContext.Variable();
+requestId.run(crypto.randomUUID(), async () => {
+  console.log(requestId.get()); // Works anywhere in the call stack
+});
+```
+
+## Asset Pipeline
+
+Import any file and get its production URL with content hashing:
+
+```javascript
+import styles from "./styles.css" with { assetBase: "/assets" };
+import logo from "./logo.png" with { assetBase: "/assets" };
+
+// styles = "/assets/styles-a1b2c3d4.css"
+// logo = "/assets/logo-e5f6g7h8.png"
+```
+
+At build time, Shovel:
+- Copies assets to the output directory with content hashes
+- Generates a manifest mapping original paths to hashed URLs
+- Transforms imports to return the final URLs
+
+Assets are served via the platform's best option:
+- **Cloudflare**: Workers Assets (edge-cached, zero config)
+- **Node/Bun**: Static file middleware or bucket storage
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| `@b9g/shovel` | CLI for development and deployment |
+| `@b9g/platform` | Core runtime and platform APIs |
+| `@b9g/platform-node` | Node.js adapter |
+| `@b9g/platform-bun` | Bun adapter |
+| `@b9g/platform-cloudflare` | Cloudflare Workers adapter |
+| `@b9g/router` | URLPattern-based routing with middleware |
+| `@b9g/cache` | Cache API implementation |
+| `@b9g/filesystem` | File System Access implementation |
+| `@b9g/match-pattern` | URLPattern with extensions (100% WPT) |
+| `@b9g/async-context` | AsyncContext.Variable implementation |
+| `@b9g/http-errors` | Standard HTTP error classes |
+| `@b9g/auth` | OAuth2/PKCE and CORS middleware |
+| `@b9g/assets` | Static asset handling |
+
+## License
+
+MIT

package/bin/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+export {};