@wordup-md/unstorage-drivers 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ManUtopiK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,177 @@
-# Temporary Holding Version
+# @wordup-md/unstorage-drivers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Isomorphic [unstorage](https://unstorage.unjs.io) drivers, part of the WordUp ecosystem.
+
+Every driver is its own subpath export: an app only loads the drivers it imports. Drivers rely on web
+standards (`fetch`, `TextDecoder`, `URLSearchParams`, the File System API), never on Node modules.
+
+## Install
+
+```bash
+pnpm add @wordup-md/unstorage-drivers unstorage
+```
+
+## Drivers
+
+| Driver    | Import                                 | Access     | Runs in               |
+| --------- | -------------------------------------- | ---------- | --------------------- |
+| `forgejo` | `@wordup-md/unstorage-drivers/forgejo` | Read-only  | Anywhere with `fetch` |
+| `gitlab`  | `@wordup-md/unstorage-drivers/gitlab`  | Read-only  | Anywhere with `fetch` |
+| `overlay` | `@wordup-md/unstorage-drivers/overlay` | Read-write | Anywhere              |
+| `opfs`    | `@wordup-md/unstorage-drivers/opfs`    | Read-write | Browser               |
+| `ipfs`    | `@wordup-md/unstorage-drivers/ipfs`    | Read-write | Anywhere with Helia   |
+| `git-fs`  | `@wordup-md/unstorage-drivers/git-fs`  | Read-write | Anywhere (adapter)    |
+
+### `forgejo` and `gitlab`
+
+Map the files of a Forgejo (or Gitea) or GitLab repository, the counterparts of `unstorage/drivers/github`.
+The git tree is listed once and kept for `ttl` seconds; file bodies are fetched on demand, pinned to `branch`.
+
+```ts
+import { createStorage } from "unstorage";
+import forgejoDriver from "@wordup-md/unstorage-drivers/forgejo";
+import gitlabDriver from "@wordup-md/unstorage-drivers/gitlab";
+
+const docs = createStorage({
+  driver: forgejoDriver({ apiURL: "https://codeberg.org", repo: "owner/name", dir: "content" }),
+});
+const site = createStorage({
+  driver: gitlabDriver({
+    repo: "group/name",
+    getHeaders: async () => ({ Authorization: `Bearer ${await getToken()}` }),
+  }),
+});
+
+await docs.getKeys(); // ["index.md", "docs:guide.md", ...]
+await docs.getItem("index.md");
+await docs.getKeys("", { force: true }); // refetch the tree now
+```
+
+| Option       | Type                | Default                                                           | Description                                                            |
+| ------------ | ------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `repo`       | `string`            | required                                                          | `owner/name` of the repository (GitLab: project path or ID).           |
+| `branch`     | `string`            | Forgejo: `"main"`, GitLab: the project's default branch           | Branch, tag or commit SHA to read.                                     |
+| `dir`        | `string`            | `""`                                                              | Directory of the repository used as the driver root.                   |
+| `ttl`        | `number`            | `600`                                                             | Seconds the file list is reused. `Infinity` for a pinned commit.       |
+| `token`      | `string`            |                                                                   | Access token, needed for private repositories.                         |
+| `getHeaders` | `() => HeadersInit` |                                                                   | Headers resolved before every request (OAuth bearer, refreshed token). |
+| `apiURL`     | `string`            | Forgejo: `"https://codeberg.org"`, GitLab: `"https://gitlab.com"` | Base URL of the instance.                                              |
+
+`getMeta(key)` returns the blob `sha` and `mode` (and `size` on Forgejo).
+
+### `overlay`
+
+Stacks layers over a base, to edit a read-only source locally: `layers[0]` is the writable top layer,
+the last layer is the base. The top layer only ever holds the changes: a value set back to the base one
+is dropped, a removed base file leaves a marker.
+
+```ts
+import indexedDbDriver from "unstorage/drivers/indexedb";
+import overlayDriver from "@wordup-md/unstorage-drivers/overlay";
+
+const overlay = overlayDriver({
+  layers: [indexedDbDriver({ dbName: "changes" }), gitlabDriver({ repo: "group/name" })],
+});
+const storage = createStorage({ driver: overlay });
+
+await storage.setItem("docs:intro.md", "# Intro", { previousPath: "docs/guide.md" }); // a rename
+await storage.getItem("docs:intro.md", { original: true }); // the base value
+// Once the changes are committed to the base:
+await overlay.mergeItem("docs:intro.md");
+```
+
+### `opfs`
+
+Files in the Origin Private File System of the browser, or in any `FileSystemDirectoryHandle`
+(e.g. a folder picked with `showDirectoryPicker()`).
+
+| Option   | Type                        | Default                            | Description                                          |
+| -------- | --------------------------- | ---------------------------------- | ---------------------------------------------------- |
+| `fs`     | `FileSystemDirectoryHandle` | `navigator.storage.getDirectory()` | Directory used as the filesystem root.               |
+| `base`   | `string`                    | `""`                               | Directory under the root used as the driver root.    |
+| `ignore` | `(path) => boolean`         |                                    | Skips the files and directories it returns true for. |
+
+`getMeta(key)` returns the `mtime`, `size` and `type` of the file.
+
+### `ipfs`
+
+A UnixFS directory on IPFS, with [Helia](https://helia.io). The whole storage is one directory DAG,
+so its state is a single root CID: every write builds a new root, from the changed file up, and hands it
+to `onRootChange()` to persist or publish. Pass it back as `root` to reopen the same storage.
+
+```ts
+import { createHelia } from "helia";
+import { unixfs } from "@helia/unixfs";
+import { CID } from "multiformats/cid";
+import ipfsDriver from "@wordup-md/unstorage-drivers/ipfs";
+
+const helia = await createHelia();
+const saved = localStorage.getItem("root");
+const driver = ipfsDriver({
+  fs: unixfs(helia),
+  root: saved ? CID.parse(saved) : undefined,
+  onRootChange: (root) => localStorage.setItem("root", root.toString()),
+});
+const storage = createStorage({ driver });
+
+await storage.setItem("docs:guide.md", "# Guide");
+await driver.getRoot(); // the CID of the whole storage
+```
+
+| Option         | Type                  | Default               | Description                                 |
+| -------------- | --------------------- | --------------------- | ------------------------------------------- |
+| `fs`           | `UnixFS`              | required              | The UnixFS instance, e.g. `unixfs(helia)`.  |
+| `root`         | `CID`                 | a new empty directory | CID of the directory to open.               |
+| `onRootChange` | `(root: CID) => void` |                       | Called with the new root after every write. |
+
+Writes run one at a time; a failed write keeps the previous root. Removing a file prunes the
+directories it leaves empty, so the same files always make the same root. `getMeta(key)` returns the
+file `cid`, `size`, `mode` and `mtime`. `@helia/unixfs` and `multiformats` are optional peer
+dependencies: the driver only imports their types.
+
+### `git-fs`
+
+Not a driver but the other way around: a filesystem over any unstorage instance, for
+[isomorphic-git](https://isomorphic-git.org). Files are storage items (path `a/b.md` is key `a:b.md`),
+directories are implicit, and reads and writes go raw so git objects stay byte-exact on any driver.
+A file written with `storage.setItem()` is a file git sees.
+
+```ts
+import git from "isomorphic-git";
+import http from "isomorphic-git/http/web";
+import { createStorage, prefixStorage } from "unstorage";
+import createGitFs from "@wordup-md/unstorage-drivers/git-fs";
+import opfsDriver from "@wordup-md/unstorage-drivers/opfs";
+
+const storage = createStorage({ driver: opfsDriver() });
+const fs = createGitFs(prefixStorage(storage, "repos:site"));
+
+await git.clone({
+  fs,
+  http,
+  dir: "/",
+  url: "https://example.com/site.git",
+  corsProxy: "https://cors.isomorphic-git.org",
+});
+await storage.setItem("repos:site:index.md", "# Edited");
+await git.status({ fs, dir: "/", filepath: "index.md" }); // "*modified"
+```
+
+Without a native `mtime` in the driver meta, the file stats carry a hash of the content, so git only
+rehashes the files that changed.
+
+## Development
+
+```bash
+vp install   # install dependencies
+vp test      # run the tests
+vp check     # format, lint and type check
+vp pack      # build the library
+```
+
+A new driver goes in `src/<name>.ts` with an entry in the `pack` block of `vite.config.ts`;
+the `package.json` exports are generated on build.
+
+## License
+
+MIT

package/dist/_utils-B_aavWpW.mjs

@@ -0,0 +1,43 @@
+//#region src/_utils.ts
+/**
+* Helpers shared by the drivers. Bundled into each driver that imports them, never exported.
+*/
+function createError(driver, message, options) {
+	return new Error(`[unstorage] [${driver}] ${message}`, options);
+}
+/** The headers of a forge request: the `token` header, then the ones from `getHeaders()`. */
+async function forgeHeaders(options, tokenHeader) {
+	const headers = new Headers(options.token ? tokenHeader(options.token) : void 0);
+	if (options.getHeaders) for (const [name, value] of new Headers(await options.getHeaders())) headers.set(name, value);
+	return headers;
+}
+/**
+* A file listing fetched at most once per `ttl` seconds. Concurrent reads share one fetch,
+* a failed fetch is dropped so the next read retries, and `force` refetches right away.
+*/
+function createListingCache(fetchListing, ttl) {
+	let files = {};
+	let lastCheck;
+	let pending;
+	return async function getFiles(force = false) {
+		if (!force && lastCheck !== void 0 && lastCheck + ttl * 1e3 > Date.now()) return files;
+		pending ??= fetchListing().finally(() => {
+			pending = void 0;
+		});
+		files = await pending;
+		lastCheck = Date.now();
+		return files;
+	};
+}
+/** Drop the options set to `undefined`, so they keep their default. */
+function withDefaults(defaults, options) {
+	return {
+		...defaults,
+		...Object.fromEntries(Object.entries(options).filter(([, value]) => value !== void 0))
+	};
+}
+function trimSlashes(path) {
+	return path.replace(/^\/+|\/+$/g, "");
+}
+//#endregion
+export { withDefaults as a, trimSlashes as i, createListingCache as n, forgeHeaders as r, createError as t };

package/dist/_utils-fCOHgF0_.d.mts

@@ -0,0 +1,13 @@
+//#region src/_utils.d.ts
+/** Options common to the drivers reading a git forge through its REST API. */
+interface ForgeAuthOptions {
+  /** Access token, needed for private repositories. */
+  token?: string;
+  /**
+   * Request headers, resolved before every request: for an OAuth `Authorization: Bearer …` header,
+   * or a token that may be refreshed. Merged over the `token` header.
+   */
+  getHeaders?: () => HeadersInit | Promise<HeadersInit>;
+}
+//#endregion
+export { ForgeAuthOptions as t };

package/dist/forgejo.d.mts

@@ -0,0 +1,30 @@
+import { t as ForgeAuthOptions } from "./_utils-fCOHgF0_.mjs";
+import { Driver } from "unstorage";
+//#region src/forgejo.d.ts
+export interface ForgejoDriverOptions extends ForgeAuthOptions {
+  /** `owner/name` of the repository. Required. */
+  repo: string;
+  /**
+   * Branch, tag or commit SHA to read.
+   * @default "main"
+   */
+  branch?: string;
+  /**
+   * Directory of the repository to use as the driver root.
+   * @default ""
+   */
+  dir?: string;
+  /**
+   * Seconds the file list is reused before the tree is fetched again.
+   * `getKeys(base, { force: true })` refetches it right away.
+   * @default 600
+   */
+  ttl?: number;
+  /**
+   * Base URL of the Forgejo instance.
+   * @default "https://codeberg.org"
+   */
+  apiURL?: string;
+}
+export default function forgejoDriver(_opts: ForgejoDriverOptions): Driver;
+//#endregion

package/dist/forgejo.mjs

@@ -0,0 +1,82 @@
+import { a as withDefaults, i as trimSlashes, n as createListingCache, r as forgeHeaders, t as createError } from "./_utils-B_aavWpW.mjs";
+//#region src/forgejo.ts
+const DRIVER_NAME = "forgejo";
+/** Forgejo caps the page size of a tree at 1000 entries by default. */
+const TREE_PAGE_SIZE = 1e3;
+const defaultOptions = {
+	branch: "main",
+	dir: "",
+	ttl: 600,
+	apiURL: "https://codeberg.org"
+};
+function forgejoDriver(_opts) {
+	const opts = withDefaults(defaultOptions, _opts);
+	if (!opts.repo) throw createError(DRIVER_NAME, "Missing required option `repo`.");
+	const dir = trimSlashes(opts.dir);
+	const prefix = dir ? `${dir}/` : "";
+	const getFiles = createListingCache(fetchFiles, opts.ttl);
+	async function fetchFiles() {
+		const found = {};
+		let seen = 0;
+		try {
+			for (let page = 1;; page++) {
+				const query = new URLSearchParams({
+					recursive: "true",
+					per_page: String(TREE_PAGE_SIZE),
+					page: String(page)
+				});
+				const { tree, truncated, total_count } = await (await request(`git/trees/${encodeURIComponent(opts.branch)}?${query.toString()}`)).json();
+				for (const node of tree ?? []) {
+					if (node.type !== "blob" || !node.path.startsWith(prefix)) continue;
+					const key = node.path.slice(prefix.length).replace(/\//g, ":");
+					found[key] = {
+						sha: node.sha,
+						mode: node.mode,
+						size: node.size
+					};
+				}
+				seen += tree?.length ?? 0;
+				if (!truncated || !tree?.length || total_count !== void 0 && seen >= total_count) return found;
+			}
+		} catch (error) {
+			throw createError(DRIVER_NAME, "Failed to fetch git tree", { cause: error });
+		}
+	}
+	async function fetchRaw(key) {
+		if (!(key in await getFiles())) return null;
+		const path = `${prefix}${key.replace(/:/g, "/")}`.split("/").map(encodeURIComponent).join("/");
+		try {
+			const res = await request(`raw/${path}?ref=${encodeURIComponent(opts.branch)}`);
+			return new Uint8Array(await res.arrayBuffer());
+		} catch (error) {
+			throw createError(DRIVER_NAME, `Failed to fetch \`${JSON.stringify(key)}\``, { cause: error });
+		}
+	}
+	async function request(endpoint) {
+		const url = `${opts.apiURL.replace(/\/+$/, "")}/api/v1/repos/${opts.repo}/${endpoint}`;
+		const headers = await forgeHeaders(opts, (token) => ({ Authorization: `token ${token}` }));
+		const res = await fetch(url, { headers });
+		if (!res.ok) throw Object.assign(/* @__PURE__ */ new Error(`Forgejo ${res.status} on ${url}`), { statusCode: res.status });
+		return res;
+	}
+	return {
+		name: DRIVER_NAME,
+		options: opts,
+		async getKeys(_base, tOpts) {
+			return Object.keys(await getFiles(Boolean(tOpts?.force)));
+		},
+		async hasItem(key) {
+			return key in await getFiles();
+		},
+		async getItem(key) {
+			const body = await fetchRaw(key);
+			return body && new TextDecoder().decode(body);
+		},
+		getItemRaw: fetchRaw,
+		async getMeta(key) {
+			return (await getFiles())[key] ?? null;
+		}
+	};
+}
+//#endregion
+export { forgejoDriver as default };

package/dist/git-fs.d.mts

@@ -0,0 +1,41 @@
+import { Storage } from "unstorage";
+//#region src/git-fs.d.ts
+type Encoding = "utf8" | "utf-8";
+type EncodingOption = Encoding | {
+  encoding?: Encoding;
+} | undefined;
+export interface GitFsStats {
+  type: "file" | "dir";
+  mode: number;
+  size: number;
+  ino: number;
+  mtimeMs: number;
+  ctimeMs: number;
+  uid: number;
+  gid: number;
+  dev: number;
+  isFile(): boolean;
+  isDirectory(): boolean;
+  isSymbolicLink(): boolean;
+}
+/** The `PromiseFsClient` shape isomorphic-git expects, without depending on it. */
+export interface GitFs {
+  promises: {
+    readFile(path: string, options?: EncodingOption): Promise<Uint8Array | string>;
+    writeFile(path: string, data: Uint8Array | string, options?: EncodingOption | {
+      mode?: number;
+    }): Promise<void>;
+    unlink(path: string): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    mkdir(path: string, mode?: number): Promise<void>;
+    rmdir(path: string): Promise<void>;
+    stat(path: string): Promise<GitFsStats>;
+    lstat(path: string): Promise<GitFsStats>;
+    readlink(path: string): Promise<string>;
+    symlink(target: string, path: string): Promise<void>;
+    chmod(path: string, mode: number): Promise<void>;
+  };
+}
+export default function createGitFs(storage: Storage): GitFs;
+//#endregion
+export {};

package/dist/git-fs.mjs

@@ -0,0 +1,121 @@
+import { normalizeKey } from "unstorage";
+//#region src/git-fs.ts
+/**
+* A filesystem over an unstorage instance, for isomorphic-git: `git.clone({ fs: createGitFs(storage), dir: "/" })`.
+* Files are storage items (path `a/b.md` is key `a:b.md`), directories are implicit in the keys,
+* and every read and write goes raw, so git objects stay byte-exact on any driver.
+* Mount it on a sub-path with `prefixStorage(storage, "repo")`.
+*
+* Not a driver but the other way around: any driver (memory, IndexedDB, OPFS, overlay…) becomes
+* a git working tree, and `storage.setItem()` writes a file git sees.
+*/
+const encoder = /* @__PURE__ */ new TextEncoder();
+const decoder = /* @__PURE__ */ new TextDecoder();
+function createGitFs(storage) {
+	/** The keys of every file under the directory `key` (the root when empty). */
+	const keysUnder = async (key) => key ? (await storage.getKeys(key)).filter((k) => k.startsWith(`${key}:`)) : storage.getKeys();
+	async function readBytes(path, syscall) {
+		const key = toKey(path);
+		const value = key ? await storage.getItemRaw(key) : null;
+		if (value === null || value === void 0) throw fsError("ENOENT", syscall, path);
+		return toBytes(value);
+	}
+	async function stat(path) {
+		const key = toKey(path);
+		if (key && await storage.hasItem(key)) {
+			const meta = await storage.getMeta(key);
+			if (meta.mtime instanceof Date && typeof meta.size === "number") return createStats("file", meta.size, meta.mtime.getTime());
+			const bytes = await readBytes(path, "stat");
+			return createStats("file", bytes.length, 0, fnv1a(bytes));
+		}
+		if (!key || (await keysUnder(key)).length) return createStats("dir", 0);
+		throw fsError("ENOENT", "stat", path);
+	}
+	return { promises: {
+		async readFile(path, options) {
+			const bytes = await readBytes(path, "open");
+			return encodingOf(options) ? decoder.decode(bytes) : bytes;
+		},
+		async writeFile(path, data) {
+			const key = toKey(path);
+			if (!key) throw fsError("EISDIR", "open", path);
+			await storage.setItemRaw(key, typeof data === "string" ? encoder.encode(data) : data);
+		},
+		async unlink(path) {
+			const key = toKey(path);
+			if (!key || !await storage.hasItem(key)) throw fsError("ENOENT", "unlink", path);
+			await storage.removeItem(key);
+		},
+		async readdir(path) {
+			const key = toKey(path);
+			if (key && await storage.hasItem(key)) throw fsError("ENOTDIR", "scandir", path);
+			const keys = await keysUnder(key);
+			if (key && !keys.length) throw fsError("ENOENT", "scandir", path);
+			const offset = key ? key.length + 1 : 0;
+			return [...new Set(keys.map((k) => k.slice(offset).split(":")[0]))].sort();
+		},
+		async mkdir(path) {
+			const key = toKey(path);
+			if (!key || await storage.hasItem(key) || (await keysUnder(key)).length) throw fsError("EEXIST", "mkdir", path);
+		},
+		async rmdir(path) {
+			const key = toKey(path);
+			if (key && await storage.hasItem(key)) throw fsError("ENOTDIR", "rmdir", path);
+			if ((await keysUnder(key)).length) throw fsError("ENOTEMPTY", "rmdir", path);
+		},
+		stat,
+		lstat: stat,
+		async readlink(path) {
+			throw fsError("ENOSYS", "readlink", path);
+		},
+		async symlink(_target, path) {
+			throw fsError("ENOSYS", "symlink", path);
+		},
+		async chmod() {}
+	} };
+}
+/** The storage key of a path: `/a/./b.md` is `a:b.md`, the root is `""`. */
+function toKey(path) {
+	const segments = path.split(/[/\\]+/).filter((segment) => segment && segment !== ".");
+	if (segments.includes("..")) throw fsError("EINVAL", "open", path);
+	return normalizeKey(segments.join(":"));
+}
+function toBytes(value) {
+	if (value instanceof Uint8Array) return value;
+	if (value instanceof ArrayBuffer) return new Uint8Array(value);
+	return encoder.encode(typeof value === "string" ? value : JSON.stringify(value));
+}
+function encodingOf(options) {
+	return typeof options === "string" ? options : options?.encoding;
+}
+function createStats(type, size, mtimeMs = 0, ino = 0) {
+	return {
+		type,
+		mode: type === "dir" ? 16877 : 33188,
+		size,
+		ino,
+		mtimeMs,
+		ctimeMs: mtimeMs,
+		uid: 1,
+		gid: 1,
+		dev: 1,
+		isFile: () => type === "file",
+		isDirectory: () => type === "dir",
+		isSymbolicLink: () => false
+	};
+}
+/** 32-bit FNV-1a hash. */
+function fnv1a(bytes) {
+	let hash = 2166136261;
+	for (const byte of bytes) hash = Math.imul(hash ^ byte, 16777619);
+	return hash >>> 0;
+}
+function fsError(code, syscall, path) {
+	return Object.assign(/* @__PURE__ */ new Error(`${code}: ${syscall} '${path}'`), {
+		code,
+		syscall,
+		path
+	});
+}
+//#endregion
+export { createGitFs as default };

package/dist/gitlab.d.mts

@@ -0,0 +1,27 @@
+import { t as ForgeAuthOptions } from "./_utils-fCOHgF0_.mjs";
+import { Driver } from "unstorage";
+//#region src/gitlab.d.ts
+export interface GitlabDriverOptions extends ForgeAuthOptions {
+  /** Path (`group/name`) or numeric ID of the project. Required. */
+  repo: string;
+  /** Branch, tag or commit SHA to read. Defaults to the default branch of the project. */
+  branch?: string;
+  /**
+   * Directory of the repository to use as the driver root.
+   * @default ""
+   */
+  dir?: string;
+  /**
+   * Seconds the file list is reused before the tree is fetched again.
+   * `getKeys(base, { force: true })` refetches it right away.
+   * @default 600
+   */
+  ttl?: number;
+  /**
+   * Base URL of the GitLab instance.
+   * @default "https://gitlab.com"
+   */
+  apiURL?: string;
+}
+export default function gitlabDriver(_opts: GitlabDriverOptions): Driver;
+//#endregion

package/dist/gitlab.mjs

@@ -0,0 +1,84 @@
+import { a as withDefaults, i as trimSlashes, n as createListingCache, r as forgeHeaders, t as createError } from "./_utils-B_aavWpW.mjs";
+//#region src/gitlab.ts
+const DRIVER_NAME = "gitlab";
+/** The largest page size GitLab accepts. */
+const TREE_PAGE_SIZE = 100;
+const defaultOptions = {
+	branch: "",
+	dir: "",
+	ttl: 600,
+	apiURL: "https://gitlab.com"
+};
+function gitlabDriver(_opts) {
+	const opts = withDefaults(defaultOptions, _opts);
+	if (!opts.repo) throw createError(DRIVER_NAME, "Missing required option `repo`.");
+	const dir = trimSlashes(opts.dir);
+	const prefix = dir ? `${dir}/` : "";
+	const getFiles = createListingCache(fetchFiles, opts.ttl);
+	async function fetchFiles() {
+		const found = {};
+		try {
+			for (let page = "1"; page;) {
+				const query = new URLSearchParams({
+					recursive: "true",
+					per_page: String(TREE_PAGE_SIZE),
+					page
+				});
+				if (opts.branch) query.set("ref", opts.branch);
+				if (dir) query.set("path", dir);
+				const res = await request(`repository/tree?${query.toString()}`);
+				for (const node of await res.json()) {
+					if (node.type !== "blob" || !node.path.startsWith(prefix)) continue;
+					const key = node.path.slice(prefix.length).replace(/\//g, ":");
+					found[key] = {
+						sha: node.id,
+						mode: node.mode
+					};
+				}
+				page = res.headers.get("x-next-page");
+			}
+			return found;
+		} catch (error) {
+			throw createError(DRIVER_NAME, "Failed to fetch git tree", { cause: error });
+		}
+	}
+	async function fetchRaw(key) {
+		if (!(key in await getFiles())) return null;
+		const path = encodeURIComponent(`${prefix}${key.replace(/:/g, "/")}`);
+		const query = opts.branch ? `?ref=${encodeURIComponent(opts.branch)}` : "";
+		try {
+			const res = await request(`repository/files/${path}/raw${query}`);
+			return new Uint8Array(await res.arrayBuffer());
+		} catch (error) {
+			throw createError(DRIVER_NAME, `Failed to fetch \`${JSON.stringify(key)}\``, { cause: error });
+		}
+	}
+	async function request(endpoint) {
+		const project = encodeURIComponent(opts.repo);
+		const url = `${opts.apiURL.replace(/\/+$/, "")}/api/v4/projects/${project}/${endpoint}`;
+		const headers = await forgeHeaders(opts, (token) => ({ "PRIVATE-TOKEN": token }));
+		const res = await fetch(url, { headers });
+		if (!res.ok) throw Object.assign(/* @__PURE__ */ new Error(`GitLab ${res.status} on ${url}`), { statusCode: res.status });
+		return res;
+	}
+	return {
+		name: DRIVER_NAME,
+		options: opts,
+		async getKeys(_base, tOpts) {
+			return Object.keys(await getFiles(Boolean(tOpts?.force)));
+		},
+		async hasItem(key) {
+			return key in await getFiles();
+		},
+		async getItem(key) {
+			const body = await fetchRaw(key);
+			return body && new TextDecoder().decode(body);
+		},
+		getItemRaw: fetchRaw,
+		async getMeta(key) {
+			return (await getFiles())[key] ?? null;
+		}
+	};
+}
+//#endregion
+export { gitlabDriver as default };

package/dist/ipfs.d.mts

@@ -0,0 +1,21 @@
+import { Driver } from "unstorage";
+import { UnixFS } from "@helia/unixfs";
+import { CID } from "multiformats/cid";
+//#region src/ipfs.d.ts
+export interface IpfsDriverOptions {
+  /** The UnixFS instance to read and write with, e.g. `unixfs(helia)`. Required. */
+  fs: UnixFS;
+  /**
+   * CID of the directory to open.
+   * @default a new empty directory
+   */
+  root?: CID;
+  /** Called with the new root CID after every write, in order. */
+  onRootChange?: (root: CID) => void | Promise<void>;
+}
+export interface IpfsDriver extends Driver {
+  /** The current root CID, once the pending writes are done. */
+  getRoot(): Promise<CID>;
+}
+export default function ipfsDriver(opts: IpfsDriverOptions): IpfsDriver;
+//#endregion

package/dist/ipfs.mjs

@@ -0,0 +1,133 @@
+import { t as createError } from "./_utils-B_aavWpW.mjs";
+//#region src/ipfs.ts
+const DRIVER_NAME = "ipfs";
+/** Multicodec of a raw block, always a file. */
+const RAW_CODEC = 85;
+const encoder = /* @__PURE__ */ new TextEncoder();
+function ipfsDriver(opts) {
+	const { fs } = opts;
+	if (!fs) throw createError(DRIVER_NAME, "Missing required option `fs`.");
+	let rootPromise = opts.root ? Promise.resolve(opts.root) : fs.addDirectory();
+	/** Apply a change to the root, one at a time; a failed change leaves the root as it was. */
+	async function update(change) {
+		const previous = rootPromise;
+		const next = previous.then(change);
+		rootPromise = next.catch(() => previous);
+		const root = await next;
+		if (!root.equals(await previous)) await opts.onRootChange?.(root);
+	}
+	async function statOf(root, path) {
+		return fs.stat(root, { path }).catch(ignoreNotFound);
+	}
+	async function readFile(key) {
+		const root = await rootPromise;
+		const path = toPath(key);
+		const stats = await statOf(root, path);
+		if (!stats || stats.type === "directory") return null;
+		const chunks = [];
+		for await (const chunk of fs.cat(root, { path })) chunks.push(chunk);
+		return concat(chunks);
+	}
+	/** The directory `dir` with `entry` at `segments` (or removed, when `entry` is null). */
+	async function setAt(dir, segments, entry) {
+		const [name, ...rest] = segments;
+		const child = await statOf(dir, name);
+		if (!rest.length) {
+			if (entry) return fs.cp(entry, dir, name, { force: true });
+			return child ? fs.rm(dir, name) : dir;
+		}
+		if (child && child.type !== "directory") throw createError(DRIVER_NAME, `\`${name}\` is a file, not a directory.`);
+		if (!child && !entry) return dir;
+		const updated = await setAt(child?.cid ?? await fs.addDirectory(), rest, entry);
+		if (!entry && await isEmpty(updated)) return fs.rm(dir, name);
+		return fs.cp(updated, dir, name, { force: true });
+	}
+	async function isEmpty(dir) {
+		for await (const _entry of fs.ls(dir)) return false;
+		return true;
+	}
+	async function listFiles(dir, prefix) {
+		const keys = [];
+		for await (const entry of fs.ls(dir)) {
+			const key = prefix ? `${prefix}:${entry.name}` : entry.name;
+			if (await isDirectory(entry.cid)) keys.push(...await listFiles(entry.cid, key));
+			else keys.push(key);
+		}
+		return keys;
+	}
+	/** Entries don't tell their type: a raw block is a file, a dag-pb node needs a stat. */
+	async function isDirectory(cid) {
+		return cid.code !== RAW_CODEC && (await fs.stat(cid)).type === "directory";
+	}
+	const write = (key, bytes) => update(async (root) => setAt(root, toSegments(key), await fs.addBytes(bytes)));
+	return {
+		name: DRIVER_NAME,
+		options: opts,
+		getRoot: () => rootPromise,
+		async hasItem(key) {
+			const stats = await statOf(await rootPromise, toPath(key));
+			return !!stats && stats.type !== "directory";
+		},
+		async getItem(key) {
+			const bytes = await readFile(key);
+			return bytes && new TextDecoder().decode(bytes);
+		},
+		getItemRaw: readFile,
+		async getMeta(key) {
+			const stats = await statOf(await rootPromise, toPath(key));
+			if (!stats || stats.type === "directory") return null;
+			return {
+				cid: stats.cid.toString(),
+				size: Number(stats.size),
+				mode: stats.mode,
+				...stats.mtime && { mtime: /* @__PURE__ */ new Date(Number(stats.mtime.secs) * 1e3) }
+			};
+		},
+		async setItem(key, value) {
+			await write(key, encoder.encode(value));
+		},
+		async setItemRaw(key, value) {
+			await write(key, toBytes(value));
+		},
+		async removeItem(key) {
+			await update((root) => setAt(root, toSegments(key), null));
+		},
+		async getKeys() {
+			return listFiles(await rootPromise, "");
+		},
+		async clear(prefix) {
+			await update((root) => prefix ? setAt(root, toSegments(prefix), null) : fs.addDirectory());
+		}
+	};
+}
+function toSegments(key) {
+	const segments = key.split(/[:/]/).filter(Boolean);
+	if (!segments.length || segments.some((segment) => segment === "." || segment === "..")) throw createError(DRIVER_NAME, `Invalid key: ${JSON.stringify(key)}.`);
+	return segments;
+}
+function toPath(key) {
+	return toSegments(key).join("/");
+}
+function toBytes(value) {
+	if (value instanceof Uint8Array) return value;
+	if (value instanceof ArrayBuffer) return new Uint8Array(value);
+	return encoder.encode(typeof value === "string" ? value : JSON.stringify(value));
+}
+function concat(chunks) {
+	if (chunks.length === 1) return chunks[0];
+	const bytes = new Uint8Array(chunks.reduce((size, chunk) => size + chunk.length, 0));
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.length;
+	}
+	return bytes;
+}
+/** Resolve a missing path to nothing; any other failure stays an error. */
+function ignoreNotFound(error) {
+	const { name, code } = error ?? {};
+	if (name === "DoesNotExistError" || name === "NotFoundError" || code === "ERR_NOT_FOUND") return null;
+	throw error;
+}
+//#endregion
+export { ipfsDriver as default };

package/dist/opfs.d.mts

@@ -0,0 +1,20 @@
+import { Driver } from "unstorage";
+//#region src/opfs.d.ts
+export interface OpfsDriverOptions {
+  /**
+   * The directory to use as the filesystem root.
+   * @default navigator.storage.getDirectory()
+   */
+  fs?: FileSystemDirectoryHandle | Promise<FileSystemDirectoryHandle>;
+  /**
+   * Directory under the root to use as the driver root.
+   * @default ""
+   */
+  base?: string;
+  /** Skip the files and directories whose path (relative to `base`) it returns true for. */
+  ignore?: (path: string) => boolean;
+}
+export default function opfsDriver(opts?: OpfsDriverOptions): Driver;
+/** Collapse `/`, `:` and `.` segments, refusing `..` ones. */
+export declare function normalizePath(path: string): string;
+//#endregion

package/dist/opfs.mjs

@@ -0,0 +1,115 @@
+import { t as createError } from "./_utils-B_aavWpW.mjs";
+//#region src/opfs.ts
+const DRIVER_NAME = "opfs";
+let defaultRoot;
+function getDefaultRoot() {
+	if (typeof globalThis.navigator?.storage?.getDirectory !== "function") throw createError(DRIVER_NAME, "No `fs` given and the Origin Private File System is unavailable.");
+	return defaultRoot ??= navigator.storage.getDirectory();
+}
+function opfsDriver(opts = {}) {
+	const base = normalizePath(opts.base ?? "");
+	const getRoot = async () => await opts.fs ?? getDefaultRoot();
+	const resolve = (key) => normalizePath(`${base}/${key}`);
+	async function readFile(key) {
+		const handle = await getFileHandle(await getRoot(), resolve(key));
+		return handle ? handle.getFile() : null;
+	}
+	async function writeFile(key, data) {
+		const path = resolve(key);
+		const writable = await (await (await getDirectoryHandle(await getRoot(), dirname(path), true)).getFileHandle(basename(path), { create: true })).createWritable();
+		await writable.write(data);
+		await writable.close();
+	}
+	return {
+		name: DRIVER_NAME,
+		options: opts,
+		async hasItem(key) {
+			return await getFileHandle(await getRoot(), resolve(key)) !== null;
+		},
+		async getItem(key) {
+			const file = await readFile(key);
+			return file && file.text();
+		},
+		async getItemRaw(key) {
+			const file = await readFile(key);
+			return file && new Uint8Array(await file.arrayBuffer());
+		},
+		async getMeta(key) {
+			const file = await readFile(key);
+			return file && {
+				mtime: new Date(file.lastModified),
+				size: file.size,
+				type: file.type
+			};
+		},
+		async setItem(key, value) {
+			await writeFile(key, value);
+		},
+		async setItemRaw(key, value) {
+			await writeFile(key, value);
+		},
+		async removeItem(key) {
+			const path = resolve(key);
+			if (!path) throw createError(DRIVER_NAME, "Cannot remove the root directory.");
+			await (await getDirectoryHandle(await getRoot(), dirname(path)))?.removeEntry(basename(path)).catch(ignoreNotFound);
+		},
+		async getKeys() {
+			const dir = await getDirectoryHandle(await getRoot(), base);
+			return dir ? listFiles(dir, "", opts.ignore) : [];
+		},
+		async clear(prefix) {
+			const path = resolve(prefix ?? "");
+			const dir = await getDirectoryHandle(await getRoot(), path);
+			if (!dir) return;
+			const names = [];
+			for await (const name of dir.keys()) names.push(name);
+			await Promise.all(names.map((name) => dir.removeEntry(name, { recursive: true })));
+		}
+	};
+}
+/** Collapse `/`, `:` and `.` segments, refusing `..` ones. */
+function normalizePath(path) {
+	const wrapped = `/${path}/`.replace(/[/:]+(\.[/:]+)*[/:]*/g, "/");
+	if (wrapped.includes("/../")) throw createError(DRIVER_NAME, `Invalid key: ${JSON.stringify(path)}. It must not contain .. segments`);
+	return wrapped.slice(1, -1);
+}
+function dirname(path) {
+	return path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "";
+}
+function basename(path) {
+	return path.slice(path.lastIndexOf("/") + 1);
+}
+/** The directory at `path`, or nothing when it doesn't exist and `create` is not set. */
+async function getDirectoryHandle(root, path, create = false) {
+	let dir = root;
+	for (const segment of path ? path.split("/") : []) {
+		const child = await dir.getDirectoryHandle(segment, { create }).catch(ignoreNotFound);
+		if (!child) return null;
+		dir = child;
+	}
+	return dir;
+}
+/** The file at `path`, or nothing when it doesn't exist or is a directory. */
+async function getFileHandle(root, path) {
+	if (!path) return null;
+	const dir = await getDirectoryHandle(root, dirname(path));
+	return dir ? dir.getFileHandle(basename(path)).catch(ignoreNotFound) : null;
+}
+async function listFiles(dir, path, ignore) {
+	const files = [];
+	for await (const [name, handle] of dir.entries()) {
+		const entryPath = path ? `${path}/${name}` : name;
+		if (ignore?.(entryPath)) continue;
+		if (handle.kind === "file") files.push(entryPath);
+		else files.push(...await listFiles(handle, entryPath, ignore));
+	}
+	return files;
+}
+/** Resolve a missing entry to nothing; any other failure stays an error. */
+function ignoreNotFound(error) {
+	const name = error?.name;
+	if (name === "NotFoundError" || name === "TypeMismatchError") return null;
+	throw error;
+}
+//#endregion
+export { opfsDriver as default, normalizePath };

package/dist/overlay.d.mts

@@ -0,0 +1,17 @@
+import { Driver } from "unstorage";
+//#region src/overlay.d.ts
+export interface OverlayDriverOptions {
+  /** The writable top layer first, the base last. */
+  layers: Driver[];
+}
+export interface OverlayDriver extends Driver {
+  /** Drop the change of `key` from the top layer, once it is committed to the base. */
+  mergeItem(key: string): Promise<void>;
+  /**
+   * Hook for once changes are committed to the base. The file list of the base is not refetched:
+   * it refreshes on the `ttl` of the base driver.
+   */
+  merge(): Promise<void>;
+}
+export default function overlayDriver(options: OverlayDriverOptions): OverlayDriver;
+//#endregion

package/dist/overlay.mjs

@@ -0,0 +1,75 @@
+import { normalizeKey } from "unstorage";
+//#region src/overlay.ts
+/**
+* Unstorage driver stacking layers over a base, to edit a read-only source locally.
+* `layers[0]` is the writable top layer (e.g. IndexedDB) and the last layer is the base
+* (e.g. a git forge). Reads go top-down. Writes only touch the top layer, which then holds
+* nothing but the changes: a value set back to the base one is dropped, a removed base file
+* leaves a marker. Once the changes are committed to the base, `mergeItem()` drops them.
+*
+* A superset of `unstorage/drivers/overlay`, which neither compares with the base nor merges.
+*/
+/** Same marker as `unstorage/drivers/overlay`. */
+const OVERLAY_REMOVED = "__OVERLAY_REMOVED__";
+/** Suffix of the key holding the meta of an item, as unstorage's `setMeta()` does. */
+const META_SUFFIX = "$";
+const DRIVER_NAME = "overlay";
+function overlayDriver(options) {
+	const { layers } = options;
+	const top = layers[0];
+	const base = layers.at(-1);
+	const isRemoved = async (key) => await top?.getItem(key) === OVERLAY_REMOVED;
+	async function read(opts, get) {
+		if (opts?.original) return base ? await get(base) ?? null : null;
+		for (const layer of layers) {
+			const value = await get(layer);
+			if (value === OVERLAY_REMOVED) return null;
+			if (value !== null && value !== void 0) return value;
+		}
+		return null;
+	}
+	async function dropChange(key, opts = {}) {
+		await top?.removeItem?.(key, opts);
+		await top?.removeItem?.(key + META_SUFFIX, opts);
+	}
+	return {
+		name: DRIVER_NAME,
+		options,
+		async hasItem(key, opts) {
+			for (const layer of layers) if (await layer.hasItem(key, opts)) return layer !== top || !await isRemoved(key);
+			return false;
+		},
+		async getItem(key, opts) {
+			return await read(opts, (layer) => layer.getItem(key, opts));
+		},
+		async getItemRaw(key, opts) {
+			return read(opts, (layer) => layer.getItemRaw ? layer.getItemRaw(key, opts) : layer.getItem(key, opts));
+		},
+		async setItem(key, value, opts) {
+			if (value === await base?.getItem(key, opts)) return dropChange(key, opts);
+			await top?.setItem?.(key, value, opts);
+			if (opts?.previousPath) {
+				const previousPath = String(opts.previousPath).replaceAll("/", ":");
+				await top?.setItem?.(key + META_SUFFIX, JSON.stringify({ previousPath }), opts);
+			}
+		},
+		async removeItem(key, opts) {
+			if (opts?.force || !await base?.hasItem(key, opts)) return dropChange(key, opts);
+			await top?.setItem?.(key, OVERLAY_REMOVED, opts);
+		},
+		async getKeys(prefix, opts) {
+			const keysByLayer = await Promise.all(layers.map(async (layer) => (await layer.getKeys(prefix, opts)).map(normalizeKey)));
+			const removed = new Set((await Promise.all((keysByLayer[0] ?? []).map(async (key) => await isRemoved(key) ? key : null))).filter((key) => key !== null));
+			return [...new Set(keysByLayer.flat())].filter((key) => !removed.has(key));
+		},
+		async mergeItem(key) {
+			await dropChange(key);
+		},
+		async merge() {},
+		async dispose() {
+			await Promise.all(layers.map(async (layer) => layer.dispose?.()));
+		}
+	};
+}
+//#endregion
+export { overlayDriver as default };

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@wordup-md/unstorage-drivers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "Isomorphic unstorage drivers for git forges and beyond, loaded one by one through subpath exports.",
+  "keywords": [
+    "forgejo",
+    "gitea",
+    "gitlab",
+    "ipfs",
+    "isomorphic",
+    "isomorphic-git",
+    "opfs",
+    "unstorage",
+    "unstorage-driver"
+  ],
+  "homepage": "https://github.com/wordup-md/unstorage-drivers#readme",
+  "bugs": {
+    "url": "https://github.com/wordup-md/unstorage-drivers/issues"
+  },
+  "license": "MIT",
+  "author": "ManUtopiK <emmanuel.salomon@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wordup-md/unstorage-drivers.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./forgejo": "./dist/forgejo.mjs",
+    "./git-fs": "./dist/git-fs.mjs",
+    "./gitlab": "./dist/gitlab.mjs",
+    "./ipfs": "./dist/ipfs.mjs",
+    "./opfs": "./dist/opfs.mjs",
+    "./overlay": "./dist/overlay.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@helia/unixfs": "^8.0.9",
+    "@types/node": "^26.6.5",
+    "blockstore-core": "^7.0.1",
+    "bumpp": "^12.3.0",
+    "isomorphic-git": "^1.44.2",
+    "multiformats": "^14.0.5",
+    "typescript": "^7.0.2",
+    "unstorage": "^1.17.6",
+    "vite-plus": "1.3.0"
+  },
+  "peerDependencies": {
+    "@helia/unixfs": ">=8",
+    "multiformats": ">=13",
+    "unstorage": "^1.17.0"
+  },
+  "peerDependenciesMeta": {
+    "@helia/unixfs": {
+      "optional": true
+    },
+    "multiformats": {
+      "optional": true
+    }
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "12.14.0",
+      "onFail": "download"
+    }
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "release": "bumpp"
+  }
 }