@b9g/platform 0.1.0

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "@b9g/platform",
+  "version": "0.1.0",
+  "description": "Base Platform interface and types for Shovel deployment adapters",
+  "keywords": [
+    "shovel",
+    "platform",
+    "deployment",
+    "adapter",
+    "interface"
+  ],
+  "dependencies": {
+    "@types/wicg-file-system-access": "^2023.10.7"
+  },
+  "devDependencies": {
+    "@b9g/libuild": "^0.1.10",
+    "bun-types": "latest"
+  },
+  "type": "module",
+  "types": "src/index.d.ts",
+  "module": "src/index.js",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./types": {
+      "types": "./src/types.d.ts",
+      "import": "./src/types.js"
+    },
+    "./types.js": {
+      "types": "./src/types.d.ts",
+      "import": "./src/types.js"
+    },
+    "./package.json": "./package.json",
+    "./adapter-registry": {
+      "types": "./src/adapter-registry.d.ts",
+      "import": "./src/adapter-registry.js"
+    },
+    "./adapter-registry.js": {
+      "types": "./src/adapter-registry.d.ts",
+      "import": "./src/adapter-registry.js"
+    },
+    "./base-platform": {
+      "types": "./src/base-platform.d.ts",
+      "import": "./src/base-platform.js"
+    },
+    "./base-platform.js": {
+      "types": "./src/base-platform.d.ts",
+      "import": "./src/base-platform.js"
+    },
+    "./filesystem": {
+      "types": "./src/filesystem.d.ts",
+      "import": "./src/filesystem.js"
+    },
+    "./filesystem.js": {
+      "types": "./src/filesystem.d.ts",
+      "import": "./src/filesystem.js"
+    },
+    "./index": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./index.js": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./registry": {
+      "types": "./src/registry.d.ts",
+      "import": "./src/registry.js"
+    },
+    "./registry.js": {
+      "types": "./src/registry.d.ts",
+      "import": "./src/registry.js"
+    },
+    "./service-worker": {
+      "types": "./src/service-worker.d.ts",
+      "import": "./src/service-worker.js"
+    },
+    "./service-worker.js": {
+      "types": "./src/service-worker.d.ts",
+      "import": "./src/service-worker.js"
+    },
+    "./utils": {
+      "types": "./src/utils.d.ts",
+      "import": "./src/utils.js"
+    },
+    "./utils.js": {
+      "types": "./src/utils.d.ts",
+      "import": "./src/utils.js"
+    },
+    "./detection": {
+      "types": "./src/detection.d.ts",
+      "import": "./src/detection.js"
+    },
+    "./detection.js": {
+      "types": "./src/detection.d.ts",
+      "import": "./src/detection.js"
+    },
+    "./directory-storage": {
+      "types": "./src/directory-storage.d.ts",
+      "import": "./src/directory-storage.js"
+    },
+    "./directory-storage.js": {
+      "types": "./src/directory-storage.d.ts",
+      "import": "./src/directory-storage.js"
+    }
+  }
+}

package/src/adapter-registry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Blessed alias registry for official Shovel adapters
+ * Maps short names to full package names for CLI convenience
+ */
+export interface AdapterModule {
+    createCache?: (config: any) => any;
+    createFileSystem?: (config: any) => any;
+}
+/**
+ * Official blessed aliases for cache adapters
+ */
+export declare const CACHE_ALIASES: {
+    readonly memory: "@b9g/cache";
+    readonly redis: "@b9g/cache-redis";
+    readonly kv: "@b9g/cache-kv";
+    readonly cloudflare: "@b9g/cache/cloudflare";
+};
+/**
+ * Official blessed aliases for filesystem adapters
+ */
+export declare const FILESYSTEM_ALIASES: {
+    readonly memory: "@b9g/filesystem";
+    readonly fs: "@b9g/filesystem/node";
+    readonly "bun-s3": "@b9g/filesystem/bun-s3";
+    readonly s3: "@b9g/filesystem-s3";
+    readonly r2: "@b9g/filesystem-r2";
+};
+/**
+ * Resolve a cache adapter name to a package name
+ * @param name - Blessed alias (memory, redis) or full package name (@custom/cache)
+ * @returns Full package name
+ */
+export declare function resolveCacheAdapter(name: string): string;
+/**
+ * Resolve a filesystem adapter name to a package name
+ * @param name - Blessed alias (memory, s3) or full package name (@custom/filesystem)
+ * @returns Full package name
+ */
+export declare function resolveFilesystemAdapter(name: string): string;
+/**
+ * Dynamically load a cache adapter
+ * @param name - Adapter name (blessed alias or package name)
+ * @param config - Adapter configuration
+ * @returns Cache instance
+ */
+export declare function loadCacheAdapter(name: string, config?: any): Promise<any>;
+/**
+ * Dynamically load a filesystem adapter
+ * @param name - Adapter name (blessed alias or package name)
+ * @param config - Adapter configuration
+ * @returns Filesystem adapter instance
+ */
+export declare function loadFilesystemAdapter(name: string, config?: any): Promise<any>;

package/src/adapter-registry.js

@@ -0,0 +1,71 @@
+/// <reference types="./adapter-registry.d.ts" />
+// src/adapter-registry.ts
+var CACHE_ALIASES = {
+  memory: "@b9g/cache",
+  redis: "@b9g/cache-redis",
+  kv: "@b9g/cache-kv",
+  cloudflare: "@b9g/cache/cloudflare"
+};
+var FILESYSTEM_ALIASES = {
+  memory: "@b9g/filesystem",
+  fs: "@b9g/filesystem/node",
+  "bun-s3": "@b9g/filesystem/bun-s3",
+  s3: "@b9g/filesystem-s3",
+  r2: "@b9g/filesystem-r2"
+};
+function resolveCacheAdapter(name) {
+  if (name.startsWith("@")) {
+    return name;
+  }
+  if (name in CACHE_ALIASES) {
+    return CACHE_ALIASES[name];
+  }
+  throw new Error(`Unknown cache adapter: ${name}. Available aliases: ${Object.keys(CACHE_ALIASES).join(", ")} or use full package name like @custom/cache`);
+}
+function resolveFilesystemAdapter(name) {
+  if (name.startsWith("@")) {
+    return name;
+  }
+  if (name in FILESYSTEM_ALIASES) {
+    return FILESYSTEM_ALIASES[name];
+  }
+  throw new Error(`Unknown filesystem adapter: ${name}. Available aliases: ${Object.keys(FILESYSTEM_ALIASES).join(", ")} or use full package name like @custom/filesystem`);
+}
+async function loadCacheAdapter(name, config = {}) {
+  const packageName = resolveCacheAdapter(name);
+  try {
+    const module = await import(packageName);
+    if (!module.createCache) {
+      throw new Error(`Package ${packageName} does not export a createCache function`);
+    }
+    return module.createCache(config);
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("Cannot resolve module")) {
+      throw new Error(`Cache adapter '${name}' requires: npm install ${packageName}`);
+    }
+    throw error;
+  }
+}
+async function loadFilesystemAdapter(name, config = {}) {
+  const packageName = resolveFilesystemAdapter(name);
+  try {
+    const module = await import(packageName);
+    if (!module.createFileSystem) {
+      throw new Error(`Package ${packageName} does not export a createFileSystem function`);
+    }
+    return module.createFileSystem(config);
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("Cannot resolve module")) {
+      throw new Error(`Filesystem adapter '${name}' requires: npm install ${packageName}`);
+    }
+    throw error;
+  }
+}
+export {
+  CACHE_ALIASES,
+  FILESYSTEM_ALIASES,
+  loadCacheAdapter,
+  loadFilesystemAdapter,
+  resolveCacheAdapter,
+  resolveFilesystemAdapter
+};

package/src/base-platform.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Base platform implementation with dynamic adapter loading
+ * Provides common functionality for all platform implementations
+ */
+import type { Platform, PlatformConfig, CacheConfig, CacheBackendConfig, FilesystemConfig } from "./types.js";
+import type { CacheStorage } from "@b9g/cache/cache-storage";
+/**
+ * Base platform class with shared adapter loading logic
+ * Platform implementations extend this and provide platform-specific methods
+ */
+export declare abstract class BasePlatform implements Platform {
+    protected config: PlatformConfig;
+    constructor(config?: PlatformConfig);
+    abstract readonly name: string;
+    abstract readonly distDir: FileSystemDirectoryHandle;
+    abstract loadServiceWorker(entrypoint: string, options?: any): Promise<any>;
+    abstract createServer(handler: any, options?: any): any;
+    abstract getFileSystemRoot(bucketName: string): Promise<FileSystemDirectoryHandle>;
+    /**
+     * Create cache storage with dynamic adapter loading
+     * Uses platform defaults when specific cache types aren't configured
+     */
+    createCaches(config?: CacheConfig): Promise<CacheStorage>;
+    /**
+     * Get platform-specific default cache configuration
+     * Subclasses override this to provide optimal defaults for their runtime
+     */
+    protected getDefaultCacheConfig(): CacheConfig;
+    /**
+     * Merge user config with platform defaults
+     */
+    protected mergeCacheConfig(userConfig?: CacheConfig): CacheConfig;
+    /**
+     * Build CacheStorage instance with dynamic adapter loading
+     */
+    protected buildCacheStorage(config: CacheConfig): Promise<CacheStorage>;
+    /**
+     * Load a single cache instance using dynamic import
+     */
+    protected loadCacheInstance(config: CacheBackendConfig): Promise<any>;
+    /**
+     * Load filesystem adapter using dynamic import
+     */
+    protected loadFilesystemAdapter(config?: FilesystemConfig): Promise<any>;
+    /**
+     * Get platform-specific default filesystem configuration
+     * Subclasses override this to provide optimal defaults for their runtime
+     */
+    protected getDefaultFilesystemConfig(): FilesystemConfig;
+}

package/src/base-platform.js

@@ -0,0 +1,114 @@
+/// <reference types="./base-platform.d.ts" />
+// src/base-platform.ts
+import { loadCacheAdapter, loadFilesystemAdapter } from "./adapter-registry.js";
+var BasePlatform = class {
+  config;
+  constructor(config = {}) {
+    this.config = config;
+  }
+  /**
+   * Create cache storage with dynamic adapter loading
+   * Uses platform defaults when specific cache types aren't configured
+   */
+  async createCaches(config) {
+    const mergedConfig = this.mergeCacheConfig(config);
+    return this.buildCacheStorage(mergedConfig);
+  }
+  /**
+   * Get platform-specific default cache configuration
+   * Subclasses override this to provide optimal defaults for their runtime
+   */
+  getDefaultCacheConfig() {
+    return {
+      pages: { type: "memory" },
+      api: { type: "memory" },
+      static: { type: "memory" }
+    };
+  }
+  /**
+   * Merge user config with platform defaults
+   */
+  mergeCacheConfig(userConfig) {
+    const defaults = this.getDefaultCacheConfig();
+    const platformConfig = this.config.caches || {};
+    return {
+      ...defaults,
+      ...platformConfig,
+      ...userConfig
+    };
+  }
+  /**
+   * Build CacheStorage instance with dynamic adapter loading
+   */
+  async buildCacheStorage(config) {
+    const caches = /* @__PURE__ */ new Map();
+    for (const [name, cacheConfig] of Object.entries(config)) {
+      if (cacheConfig && typeof cacheConfig === "object" && "type" in cacheConfig) {
+        const cache = await this.loadCacheInstance(cacheConfig);
+        caches.set(name, cache);
+      }
+    }
+    return {
+      async open(name) {
+        const cache = caches.get(name);
+        if (!cache) {
+          throw new Error(`Cache '${name}' not configured`);
+        }
+        return cache;
+      },
+      async delete(name) {
+        const deleted = caches.delete(name);
+        return deleted;
+      },
+      async has(name) {
+        return caches.has(name);
+      },
+      async keys() {
+        return Array.from(caches.keys());
+      }
+    };
+  }
+  /**
+   * Load a single cache instance using dynamic import
+   */
+  async loadCacheInstance(config) {
+    if (!config.type) {
+      throw new Error("Cache configuration must specify a type");
+    }
+    try {
+      return await loadCacheAdapter(config.type, config);
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`Failed to load cache adapter: ${error.message}`);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Load filesystem adapter using dynamic import
+   */
+  async loadFilesystemAdapter(config) {
+    const fsConfig = config || this.config.filesystem || this.getDefaultFilesystemConfig();
+    if (!fsConfig.type) {
+      throw new Error("Filesystem configuration must specify a type");
+    }
+    try {
+      return await loadFilesystemAdapter(fsConfig.type, fsConfig);
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`Failed to load filesystem adapter: ${error.message}`);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Get platform-specific default filesystem configuration
+   * Subclasses override this to provide optimal defaults for their runtime
+   */
+  getDefaultFilesystemConfig() {
+    return { type: "memory" };
+  }
+};
+export {
+  BasePlatform
+};

package/src/detection.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Platform detection utilities
+ * Centralized logic for detecting JavaScript runtime and deployment platforms
+ */
+import type { PlatformDetection } from "./types.js";
+/**
+ * Detect the current JavaScript runtime
+ */
+export declare function detectRuntime(): "bun" | "deno" | "node";
+/**
+ * Detect platform for development (uses current runtime)
+ */
+export declare function detectDevelopmentPlatform(): string;
+/**
+ * Comprehensive platform detection with confidence scoring
+ */
+export declare function detectPlatforms(): PlatformDetection[];
+/**
+ * Get the best platform detection
+ */
+export declare function getBestPlatformDetection(): PlatformDetection;
+/**
+ * Resolve platform name from options or auto-detect
+ */
+export declare function resolvePlatform(options: {
+    platform?: string;
+    target?: string;
+}): string;
+/**
+ * Create platform instance based on name
+ */
+export declare function createPlatform(platformName: string, options?: any): Promise<any>;
+/**
+ * Display platform information (for CLI info command)
+ */
+export declare function displayPlatformInfo(platformName: string): void;

package/src/detection.js

@@ -0,0 +1,126 @@
+/// <reference types="./detection.d.ts" />
+// src/detection.ts
+function detectRuntime() {
+  if (typeof Bun !== "undefined" || process.versions?.bun) {
+    return "bun";
+  }
+  if (typeof Deno !== "undefined") {
+    return "deno";
+  }
+  return "node";
+}
+function detectDevelopmentPlatform() {
+  const runtime = detectRuntime();
+  switch (runtime) {
+    case "bun":
+      return "bun";
+    case "deno":
+      return "node";
+    case "node":
+    default:
+      return "node";
+  }
+}
+function detectPlatforms() {
+  const detections = [];
+  if (typeof Bun !== "undefined") {
+    detections.push({
+      platform: "bun",
+      confidence: 0.9,
+      reasons: ["Bun global detected"]
+    });
+  }
+  if (typeof EdgeRuntime !== "undefined") {
+    detections.push({
+      platform: "vercel",
+      confidence: 0.9,
+      reasons: ["Vercel EdgeRuntime detected"]
+    });
+  }
+  if (typeof Deno !== "undefined") {
+    detections.push({
+      platform: "deno",
+      confidence: 0.9,
+      reasons: ["Deno global detected"]
+    });
+  }
+  if (typeof caches !== "undefined" && typeof Response !== "undefined" && typeof crypto !== "undefined") {
+    if (typeof addEventListener !== "undefined" && typeof fetch !== "undefined") {
+      detections.push({
+        platform: "cloudflare-workers",
+        confidence: 0.8,
+        reasons: ["Worker-like environment detected", "Web APIs available"]
+      });
+    }
+  }
+  if (typeof process !== "undefined" && process.versions && process.versions.node) {
+    detections.push({
+      platform: "node",
+      confidence: 0.7,
+      reasons: ["Node.js process detected"]
+    });
+  }
+  if (detections.length === 0) {
+    detections.push({
+      platform: "unknown",
+      confidence: 0,
+      reasons: ["No platform detected"]
+    });
+  }
+  return detections.sort((a, b) => b.confidence - a.confidence);
+}
+function getBestPlatformDetection() {
+  const detections = detectPlatforms();
+  return detections[0];
+}
+function resolvePlatform(options) {
+  if (options.platform) {
+    return options.platform;
+  }
+  if (options.target) {
+    return options.target;
+  }
+  return detectDevelopmentPlatform();
+}
+async function createPlatform(platformName, options = {}) {
+  switch (platformName) {
+    case "node": {
+      const modulePath = import.meta.resolve("@b9g/platform-node");
+      const { createNodePlatform } = await import(modulePath);
+      return createNodePlatform(options);
+    }
+    case "bun": {
+      const modulePath = import.meta.resolve("@b9g/platform-bun");
+      const { createBunPlatform } = await import(modulePath);
+      return createBunPlatform(options);
+    }
+    case "cloudflare":
+    case "cloudflare-workers":
+    case "cf": {
+      const modulePath = import.meta.resolve("@b9g/platform-cloudflare");
+      const { createCloudflarePlatform } = await import(modulePath);
+      return createCloudflarePlatform(options);
+    }
+    default:
+      throw new Error(
+        `Unknown platform: ${platformName}. Available platforms: node, bun, cloudflare`
+      );
+  }
+}
+function displayPlatformInfo(platformName) {
+  const runtime = detectRuntime();
+  const detection = getBestPlatformDetection();
+  console.info(`\u{1F680} Platform: ${platformName}`);
+  console.info(`\u2699\uFE0F  Runtime: ${runtime}`);
+  console.info(`\u{1F50D} Auto-detected: ${detection.platform} (confidence: ${detection.confidence})`);
+  console.info(`\u{1F4A1} Reasons: ${detection.reasons.join(", ")}`);
+}
+export {
+  createPlatform,
+  detectDevelopmentPlatform,
+  detectPlatforms,
+  detectRuntime,
+  displayPlatformInfo,
+  getBestPlatformDetection,
+  resolvePlatform
+};

package/src/directory-storage.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Directory Storage implementation for ServiceWorker self.dirs API
+ *
+ * This implements the proposed web standard interface that parallels CacheStorage
+ * for structured filesystem access in ServiceWorkers.
+ */
+import type { DirectoryStorage } from "./service-worker.js";
+/**
+ * Platform-agnostic directory storage implementation
+ * Uses a single root directory with well-known subdirectories
+ */
+export declare class PlatformDirectoryStorage implements DirectoryStorage {
+    private rootDir;
+    private cache;
+    constructor(rootDir: FileSystemDirectoryHandle);
+    /**
+     * Open a named directory - creates if it doesn't exist
+     * Well-known names: 'assets', 'static', 'server', 'client'
+     */
+    open(name: string): Promise<FileSystemDirectoryHandle>;
+    /**
+     * Check if a named directory exists
+     */
+    has(name: string): Promise<boolean>;
+    /**
+     * Delete a named directory and all its contents
+     */
+    delete(name: string): Promise<boolean>;
+    /**
+     * List all available directory names
+     */
+    keys(): Promise<string[]>;
+    /**
+     * Clear the cache (useful for hot reloading)
+     */
+    clearCache(): void;
+}
+/**
+ * Create a DirectoryStorage instance from a root directory
+ */
+export declare function createDirectoryStorage(rootDir: FileSystemDirectoryHandle): DirectoryStorage;

package/src/directory-storage.js

@@ -0,0 +1,78 @@
+/// <reference types="./directory-storage.d.ts" />
+// src/directory-storage.ts
+var PlatformDirectoryStorage = class {
+  rootDir;
+  cache = /* @__PURE__ */ new Map();
+  constructor(rootDir) {
+    this.rootDir = rootDir;
+  }
+  /**
+   * Open a named directory - creates if it doesn't exist
+   * Well-known names: 'assets', 'static', 'server', 'client'
+   */
+  async open(name) {
+    if (this.cache.has(name)) {
+      return this.cache.get(name);
+    }
+    try {
+      const dirHandle = await this.rootDir.getDirectoryHandle(name);
+      this.cache.set(name, dirHandle);
+      return dirHandle;
+    } catch (error) {
+      const dirHandle = await this.rootDir.getDirectoryHandle(name, { create: true });
+      this.cache.set(name, dirHandle);
+      return dirHandle;
+    }
+  }
+  /**
+   * Check if a named directory exists
+   */
+  async has(name) {
+    try {
+      await this.rootDir.getDirectoryHandle(name);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Delete a named directory and all its contents
+   */
+  async delete(name) {
+    try {
+      await this.rootDir.removeEntry(name, { recursive: true });
+      this.cache.delete(name);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * List all available directory names
+   */
+  async keys() {
+    const keys = [];
+    try {
+      for await (const [name, handle] of this.rootDir.entries()) {
+        if (handle.kind === "directory") {
+          keys.push(name);
+        }
+      }
+    } catch {
+    }
+    return keys.sort();
+  }
+  /**
+   * Clear the cache (useful for hot reloading)
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+};
+function createDirectoryStorage(rootDir) {
+  return new PlatformDirectoryStorage(rootDir);
+}
+export {
+  PlatformDirectoryStorage,
+  createDirectoryStorage
+};

package/src/filesystem.d.ts

@@ -0,0 +1,8 @@
+/**
+ * File System Access API implementation
+ */
+/**
+ * Get the file system root handle for the specified name
+ * Auto-registers Node.js platform if no platform is detected
+ */
+export declare function getFileSystemRoot(name?: string): Promise<FileSystemDirectoryHandle>;