first commit

plugins/library-navigator/skills/sp-storage-uri-plugin-bundle/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: sp-storage-uri-plugin-bundle
+description: Bundle URI plugin for @suaveplan/storage-uri — serves packed asset bundles over HTTP with range support, LRU cache, safe fetch shim, and OTel metrics.
+---
+
+# sp-storage-uri-plugin-bundle
+
+| Symbol | Kind | Responsibility |
+|---|---|---|
+| `bundleUriPlugin` | Function | Creates bundle:// URI plugin |
+| `validateOptions` | Function | Validates bundle plugin options |
+| `BundleStorageShim` | Class | Shim adapting bundle storage to URI plugin interface |
+| `safeFetch` | Function | Safe fetch with error handling |
+| `performExists` | Function | Checks if bundle entry exists |
+| `performGetMetadata` | Function | Reads bundle entry metadata |
+| `performRangeRead` | Function | Reads byte range from bundle |
+| `buildRangeHeader` | Function | Builds HTTP Range header |
+| `sliceForRange` | Function | Slices buffer for byte range |
+| `validateRange` | Function | Validates range request |
+| `parse` | Function | Parses bundle:// URI |
+| `build` | Function | Builds bundle:// URI |
+| `UriLruCache` | Class | LRU cache for bundle responses |
+| `toReadableStream` | Function | Converts response to readable stream |
+| `ensureNotAborted` | Function | Throws if operation aborted |
+| `recordCacheHit` | Function | OTel counter for cache hits |
+| `recordCacheMiss` | Function | OTel counter for cache misses |
+| `recordRangeFallback` | Function | OTel counter for range fallbacks |
+| `BUNDLE_URI_CODES` | Constant | Error codes via `defineCodes` |
+| `BundleUriError` | Class | Typed error with bundle URI codes |
+| `BundleUriPluginOptionsSchema` | Schema | Zod schema for plugin options |
+
+**File Structure:** `packages/persistence/storage/storage-uri-plugin-bundle/src/{factory,storage-shim,parse,range,cache,streaming,abort,otel,error-codes,types}/`
+
+**Sibling packages:**
+- `@suaveplan/storage-uri` — URI resolver framework
+- `@suaveplan/packer-browser` — asset bundling
+
+**Patterns:**
+
+*Quick Start:*
+```ts
+import { bundleUriPlugin } from "@suaveplan/storage-uri-plugin-bundle";
+const plugin = bundleUriPlugin({ baseUrl: "https://cdn.example.com/bundles" });
+```
+
+*Shim:*
+```ts
+import { BundleStorageShim } from "@suaveplan/storage-uri-plugin-bundle";
+const shim = new BundleStorageShim({ baseUrl });
+```
+
+*Range read:*
+```ts
+import { performRangeRead } from "@suaveplan/storage-uri-plugin-bundle";
+const data = await performRangeRead({ url, range: { start: 0, end: 1024 } });
+```
+
+**Constraints:**
+- Implements `UriPlugin` from `@suaveplan/storage-uri`
+- `bundle://` URIs reference packed asset bundles
+- `BundleStorageShim` fetches bundles over HTTP with retry
+- Range requests supported for partial asset loading
+- `UriLruCache` caches bundle metadata and small responses
+- `safeFetch` handles network errors with typed `BundleUriError`
+- OTel instruments: cache hit/miss, range fallback, operations
+- Error codes use `defineCodes` from `@suaveplan/error`
+
+**Checklist:**
+- [ ] `bundleUriPlugin` implements `UriPlugin` interface
+- [ ] `bundle://` URIs resolved to bundle assets
+- [ ] `BundleStorageShim` fetches over HTTP
+- [ ] Range requests return correct partial content
+- [ ] `UriLruCache` caches metadata and responses
+- [ ] `safeFetch` handles errors gracefully
+- [ ] OTel metrics track cache effectiveness
+- [ ] Error codes use `defineCodes` from `@suaveplan/error`