@getfamiliar/shared 0.1.4 → 0.1.6

package/build/testing/FakeStorageProvider.js

@@ -0,0 +1,459 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { StorageError, } from "../Storage.js";
+/** Google-style native doc mime types and their export mapping. */
+export const FAKE_NATIVE_EXPORTS = {
+    "application/vnd.google-apps.document": {
+        mime: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        ext: ".docx",
+    },
+    "application/vnd.google-apps.spreadsheet": {
+        mime: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        ext: ".xlsx",
+    },
+    "application/vnd.google-apps.presentation": {
+        mime: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        ext: ".pptx",
+    },
+    "application/vnd.google-apps.drawing": { mime: "application/pdf", ext: ".pdf" },
+};
+/**
+ * In-memory {@link StorageProvider} for service, tool, CLI and contract
+ * tests. Imitates OneDrive (path addressing, unique names), Google
+ * Drive (id addressing, duplicate names, native docs) or Dropbox
+ * (path addressing, no content search). Content lives in memory;
+ * download / upload still go through real host files so the byte paths
+ * are exercised.
+ */
+export class FakeStorageProvider {
+    pluginId;
+    flavor;
+    drives = new Map();
+    options;
+    nextId = 1;
+    clock = Date.parse("2026-01-01T00:00:00Z");
+    /**
+     * @param options - Behaviour knobs; see {@link FakeStorageOptions}.
+     */
+    constructor(options = {}) {
+        this.options = options;
+        this.pluginId = options.pluginId ?? "fake";
+        this.flavor = options.flavor ?? "onedrive";
+        const accounts = options.accounts ?? { "a@x": [{ selector: null, name: "Primary" }] };
+        for (const [account, drives] of Object.entries(accounts)) {
+            for (const d of drives) {
+                const id = `drv-${account}-${d.selector ?? "primary"}`;
+                const rootId = this.newId();
+                const drive = {
+                    account,
+                    selector: d.selector,
+                    id,
+                    name: d.name,
+                    kind: d.selector === null ? "personal" : "team",
+                };
+                const nodes = new Map();
+                nodes.set(rootId, this.makeNode(rootId, null, "", "folder", null, null));
+                this.drives.set(driveKey(account, d.selector), { drive, rootId, nodes });
+            }
+        }
+    }
+    /** @returns The capabilities of the imitated provider. */
+    capabilities(_drive) {
+        const isGdrive = this.flavor === "gdrive";
+        return {
+            addressing: isGdrive ? "id" : "path",
+            uniqueNames: !isGdrive,
+            contentSearch: this.options.contentSearch ?? this.flavor !== "dropbox",
+            searchSnippets: false,
+            trash: this.options.trash ?? true,
+            nativeDocs: isGdrive,
+            serverSideCopy: true,
+        };
+    }
+    /** @returns All configured accounts. */
+    async listAccounts() {
+        return [...new Set([...this.drives.values()].map((d) => d.drive.account))];
+    }
+    /** @returns A fake login command. */
+    loginCommand(account) {
+        return `familiar ${this.pluginId} login ${account}`;
+    }
+    /** @returns The account's drives, filtered and capped. */
+    async listDrives(account, options) {
+        this.assertAccount(account);
+        if (this.options.brokenAccounts?.includes(account)) {
+            throw new StorageError("ProviderUnavailable", `fake outage for ${account}`);
+        }
+        const search = options.search?.toLowerCase();
+        return [...this.drives.values()]
+            .map((d) => d.drive)
+            .filter((d) => d.account === account)
+            .filter((d) => search === undefined || d.name.toLowerCase().includes(search))
+            .slice(0, options.limit);
+    }
+    /** @returns The drive for `selector`. */
+    async openDrive(account, selector) {
+        this.assertAccount(account);
+        const state = this.drives.get(driveKey(account, selector));
+        if (!state) {
+            throw new StorageError("NotFound", `no drive "${selector ?? "(primary)"}" for ${account}`);
+        }
+        return state.drive;
+    }
+    /** @returns The root folder id. */
+    async rootRealId(drive) {
+        return this.state(drive).rootId;
+    }
+    /** @returns The item or `null`. */
+    async stat(drive, realId) {
+        const node = this.state(drive).nodes.get(realId);
+        return node && !node.trashed ? this.toItem(drive, node) : null;
+    }
+    /** Native path resolution (only for path-addressed flavors). */
+    get resolvePath() {
+        if (this.flavor === "gdrive") {
+            return undefined;
+        }
+        return async (drive, path) => {
+            const state = this.state(drive);
+            const segments = path.split("/").filter((s) => s.length > 0);
+            let current = [state.nodes.get(state.rootId)];
+            for (const seg of segments) {
+                current = current.flatMap((parent) => this.children(state, parent.realId).filter((c) => c.name.toLowerCase() === seg.toLowerCase()));
+            }
+            return current.map((n) => this.toItem(drive, n));
+        };
+    }
+    /** @returns One page of children. */
+    async list(drive, folderRealId, options) {
+        const state = this.state(drive);
+        const folder = state.nodes.get(folderRealId);
+        if (!folder || folder.trashed) {
+            throw new StorageError("NotFound", `folder ${folderRealId} not found`);
+        }
+        const all = this.children(state, folderRealId).map((n) => this.toItem(drive, n));
+        return paginate(all, options);
+    }
+    /** @returns One page of name / content hits. */
+    async search(drive, query, options) {
+        if (this.options.searchDelayMs !== undefined) {
+            await delay(this.options.searchDelayMs, options.signal);
+        }
+        if (this.options.searchError) {
+            throw this.options.searchError;
+        }
+        this.assertAccount(drive.account);
+        const state = this.state(drive);
+        const needle = query.text.toLowerCase();
+        const contentSearch = this.capabilities(drive).contentSearch;
+        const hits = [];
+        for (const node of state.nodes.values()) {
+            if (node.trashed || node.realId === state.rootId) {
+                continue;
+            }
+            if (node.name.toLowerCase().includes(needle)) {
+                hits.push({ item: this.toItem(drive, node), matchedIn: "name" });
+                continue;
+            }
+            if (contentSearch && node.content?.toString("utf8").toLowerCase().includes(needle)) {
+                hits.push({ item: this.toItem(drive, node), matchedIn: "content" });
+            }
+        }
+        return paginate(hits, options);
+    }
+    /** Write the bytes (or the native export) to `destPath`. */
+    async download(drive, realId, destPath) {
+        const node = this.requireNode(drive, realId);
+        if (node.kind === "folder") {
+            throw new StorageError("Unsupported", `${node.name} is a folder`);
+        }
+        if (node.kind === "native") {
+            const mapping = node.mimeType ? FAKE_NATIVE_EXPORTS[node.mimeType] : undefined;
+            if (!mapping) {
+                throw new StorageError("Unsupported", `${this.pluginId}: native type ${node.mimeType} cannot be exported`);
+            }
+            const bytes = Buffer.from(`exported:${node.name}`);
+            await writeFile(destPath, bytes);
+            return {
+                bytes: bytes.length,
+                mimeType: mapping.mime,
+                fileName: node.name + mapping.ext,
+            };
+        }
+        const bytes = node.content ?? Buffer.alloc(0);
+        await writeFile(destPath, bytes);
+        return { bytes: bytes.length, mimeType: node.mimeType, fileName: node.name };
+    }
+    /** Upload from a host file with conflict / revision semantics. */
+    async upload(drive, parentRealId, name, source, options) {
+        const state = this.state(drive);
+        this.requireFolder(state, parentRealId);
+        const content = await readFile(source.path);
+        if (options.conflict === "replace") {
+            if (options.replaceRealId === undefined) {
+                throw new Error("fake: conflict=replace requires replaceRealId");
+            }
+            const existing = this.requireNode(drive, options.replaceRealId);
+            if (existing.kind !== "file") {
+                throw new StorageError("Unsupported", `${existing.name} is not a file`);
+            }
+            this.checkRevision(existing, options.ifRevision);
+            existing.content = content;
+            existing.revision += 1;
+            existing.modifiedUtc = this.tick();
+            if (source.mimeType) {
+                existing.mimeType = source.mimeType;
+            }
+            return this.toItem(drive, existing);
+        }
+        const clash = this.flavor === "gdrive" ? undefined : this.childNamed(state, parentRealId, name);
+        if (clash) {
+            if (options.conflict === "fail") {
+                throw new StorageError("NameConflict", `${name} already exists`);
+            }
+            name = this.freeName(state, parentRealId, name);
+        }
+        const node = this.makeNode(this.newId(), parentRealId, name, "file", source.mimeType ?? "application/octet-stream", content);
+        state.nodes.set(node.realId, node);
+        return this.toItem(drive, node);
+    }
+    /** Create a folder. */
+    async createFolder(drive, parentRealId, name, options) {
+        const state = this.state(drive);
+        this.requireFolder(state, parentRealId);
+        const existing = this.childNamed(state, parentRealId, name);
+        if (existing) {
+            if (options.conflict === "reuse" && existing.kind === "folder") {
+                return this.toItem(drive, existing);
+            }
+            if (options.conflict === "fail" || options.conflict === "reuse") {
+                throw new StorageError("NameConflict", `${name} already exists`);
+            }
+            name = this.freeName(state, parentRealId, name);
+        }
+        const node = this.makeNode(this.newId(), parentRealId, name, "folder", null, null);
+        state.nodes.set(node.realId, node);
+        return this.toItem(drive, node);
+    }
+    /** Move / rename. */
+    async move(drive, realId, target, options) {
+        const state = this.state(drive);
+        const node = this.requireNode(drive, realId);
+        this.checkRevision(node, options.ifRevision);
+        const parent = target.parentRealId ?? node.parentRealId ?? state.rootId;
+        this.requireFolder(state, parent);
+        const name = target.name ?? node.name;
+        const clash = this.childNamed(state, parent, name);
+        if (clash && clash.realId !== node.realId && this.flavor !== "gdrive") {
+            throw new StorageError("NameConflict", `${name} already exists`);
+        }
+        node.parentRealId = parent;
+        node.name = name;
+        node.revision += 1;
+        node.modifiedUtc = this.tick();
+        return this.toItem(drive, node);
+    }
+    /** Server-side copy (files only in the fake). */
+    async copy(drive, realId, target, options) {
+        const state = this.state(drive);
+        const node = this.requireNode(drive, realId);
+        this.requireFolder(state, target.parentRealId);
+        let name = target.name ?? node.name;
+        if (this.childNamed(state, target.parentRealId, name) && this.flavor !== "gdrive") {
+            if (options.conflict === "fail") {
+                throw new StorageError("NameConflict", `${name} already exists`);
+            }
+            name = this.freeName(state, target.parentRealId, name);
+        }
+        const copy = this.makeNode(this.newId(), target.parentRealId, name, node.kind, node.mimeType, node.content);
+        state.nodes.set(copy.realId, copy);
+        return this.toItem(drive, copy);
+    }
+    /** Soft delete (recursive). */
+    async trash(drive, realId, options) {
+        if (!this.capabilities(drive).trash) {
+            throw new StorageError("Unsupported", `${this.pluginId} has no trash`);
+        }
+        const state = this.state(drive);
+        const node = this.requireNode(drive, realId);
+        this.checkRevision(node, options.ifRevision);
+        const mark = (n) => {
+            n.trashed = true;
+            for (const child of this.children(state, n.realId)) {
+                mark(child);
+            }
+        };
+        mark(node);
+    }
+    // ---- test seeding -------------------------------------------------
+    /**
+     * Seed an item under `parentPath` (folders are created as needed).
+     * Duplicates are allowed for the gdrive flavor.
+     *
+     * @returns The seeded item's realId.
+     */
+    seed(account, selector, path, options = {}) {
+        const state = this.drives.get(driveKey(account, selector));
+        if (!state) {
+            throw new Error(`fake: no drive ${account}/${selector}`);
+        }
+        const segments = path.split("/").filter((s) => s.length > 0);
+        let parentId = state.rootId;
+        for (const seg of segments.slice(0, -1)) {
+            const existing = this.childNamed(state, parentId, seg);
+            if (existing) {
+                parentId = existing.realId;
+                continue;
+            }
+            const folder = this.makeNode(this.newId(), parentId, seg, "folder", null, null);
+            state.nodes.set(folder.realId, folder);
+            parentId = folder.realId;
+        }
+        const kind = options.kind ?? "file";
+        const leaf = segments[segments.length - 1] ?? "";
+        const node = this.makeNode(this.newId(), parentId, leaf, kind, kind === "folder" ? null : (options.mimeType ?? "text/plain"), kind === "file" ? Buffer.from(options.content ?? "") : null);
+        state.nodes.set(node.realId, node);
+        return node.realId;
+    }
+    /** Test helper: raw content of an item, or `null`. */
+    contentOf(account, selector, realId) {
+        return (this.drives
+            .get(driveKey(account, selector))
+            ?.nodes.get(realId)
+            ?.content?.toString("utf8") ?? null);
+    }
+    /** Test helper: whether an item is in the trash. */
+    isTrashed(account, selector, realId) {
+        return this.drives.get(driveKey(account, selector))?.nodes.get(realId)?.trashed === true;
+    }
+    // ---- internals ----------------------------------------------------
+    state(drive) {
+        this.assertAccount(drive.account);
+        const state = this.drives.get(driveKey(drive.account, drive.selector));
+        if (!state) {
+            throw new StorageError("NotFound", `unknown drive ${drive.id}`);
+        }
+        return state;
+    }
+    assertAccount(account) {
+        if (this.options.expiredAccounts?.includes(account)) {
+            throw new StorageError("AuthExpired", `login for ${account} expired`);
+        }
+        if (![...this.drives.values()].some((d) => d.drive.account === account)) {
+            throw new StorageError("AuthExpired", `no login for ${account}`);
+        }
+    }
+    requireNode(drive, realId) {
+        const node = this.state(drive).nodes.get(realId);
+        if (!node || node.trashed) {
+            throw new StorageError("NotFound", `item ${realId} not found`);
+        }
+        return node;
+    }
+    requireFolder(state, realId) {
+        const node = state.nodes.get(realId);
+        if (!node || node.trashed || node.kind !== "folder") {
+            throw new StorageError("NotFound", `folder ${realId} not found`);
+        }
+    }
+    checkRevision(node, ifRevision) {
+        if (ifRevision !== undefined && ifRevision !== String(node.revision)) {
+            throw new StorageError("RevisionMismatch", `${node.name} changed (rev ${node.revision})`);
+        }
+    }
+    children(state, parentId) {
+        return [...state.nodes.values()].filter((n) => n.parentRealId === parentId && !n.trashed);
+    }
+    childNamed(state, parentId, name) {
+        return this.children(state, parentId).find((n) => n.name.toLowerCase() === name.toLowerCase());
+    }
+    freeName(state, parentId, name) {
+        const dot = name.lastIndexOf(".");
+        const stem = dot > 0 ? name.slice(0, dot) : name;
+        const ext = dot > 0 ? name.slice(dot) : "";
+        for (let i = 1;; i++) {
+            const candidate = `${stem} ${i}${ext}`;
+            if (!this.childNamed(state, parentId, candidate)) {
+                return candidate;
+            }
+        }
+    }
+    pathOf(state, node) {
+        const parts = [];
+        let current = node;
+        while (current && current.realId !== state.rootId) {
+            parts.unshift(current.name);
+            current = current.parentRealId ? state.nodes.get(current.parentRealId) : undefined;
+            if (current === undefined) {
+                return null;
+            }
+        }
+        return `/${parts.join("/")}`;
+    }
+    toItem(drive, node) {
+        const state = this.state(drive);
+        return {
+            realId: node.realId,
+            parentRealId: node.parentRealId,
+            name: node.name,
+            // The gdrive flavor, like the real API, does not report paths.
+            path: this.flavor === "gdrive" ? null : this.pathOf(state, node),
+            kind: node.kind,
+            mimeType: node.mimeType,
+            size: node.kind === "file" ? (node.content?.length ?? 0) : null,
+            createdUtc: node.createdUtc,
+            modifiedUtc: node.modifiedUtc,
+            modifiedBy: "Fake User",
+            revision: String(node.revision),
+            contentHash: null,
+            webUrl: `https://fake.example/${node.realId}`,
+            isShared: false,
+        };
+    }
+    makeNode(realId, parentRealId, name, kind, mimeType, content) {
+        const now = this.tick();
+        return {
+            realId,
+            parentRealId,
+            name,
+            kind,
+            mimeType,
+            content,
+            createdUtc: now,
+            modifiedUtc: now,
+            revision: 1,
+            trashed: false,
+        };
+    }
+    newId() {
+        return `id${this.nextId++}`;
+    }
+    tick() {
+        this.clock += 60_000;
+        return new Date(this.clock).toISOString().replace(/\.\d{3}Z$/, "Z");
+    }
+}
+/** Map key of one drive. */
+function driveKey(account, selector) {
+    return `${account}\u0000${selector ?? ""}`;
+}
+/** Offset-cursor pagination over an in-memory array. */
+function paginate(all, options) {
+    const offset = options.cursor !== undefined ? Number.parseInt(options.cursor, 10) : 0;
+    const entries = all.slice(offset, offset + options.limit);
+    const next = offset + entries.length;
+    return { entries, nextCursor: next < all.length ? String(next) : null };
+}
+/**
+ * Sleep `ms`, rejecting early when `signal` aborts.
+ *
+ * @throws The signal's abort reason.
+ */
+function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        }, { once: true });
+    });
+}

package/build/testing/StorageProviderContract.d.ts

@@ -0,0 +1,32 @@
+import { type StorageProvider } from "../Storage.js";
+/** Settings for one contract run. */
+export interface StorageContractOptions {
+    /** Account to test against; must be logged in. */
+    readonly account: string;
+    /** Drive selector (`null` = primary drive). */
+    readonly selector: string | null;
+    /**
+     * Existing folder path (absolute within the drive) the suite may write
+     * into. The suite creates and trashes a uniquely named sub-folder.
+     * Default: the drive root.
+     */
+    readonly basePath?: string;
+    /** Also upload a file of this many bytes (exercises resumable uploads). */
+    readonly largeFileBytes?: number;
+}
+/**
+ * Shared behavioural contract every {@link StorageProvider} must pass.
+ * Registered as a `node:test` suite; run it from a provider package's
+ * test file against the in-memory fake (always) and against a real
+ * account behind an env flag, e.g.:
+ *
+ * ```ts
+ * const upn = process.env.FAMILIAR_LIVE_MS365;
+ * if (upn) runStorageProviderContract("ms365 live", () => makeProvider(), { account: upn, selector: null });
+ * ```
+ *
+ * @param name - Suite name.
+ * @param makeProvider - Factory for the provider under test.
+ * @param options - Account, drive and scratch-folder settings.
+ */
+export declare function runStorageProviderContract(name: string, makeProvider: () => StorageProvider | Promise<StorageProvider>, options: StorageContractOptions): void;

package/build/testing/StorageProviderContract.js

@@ -0,0 +1,168 @@
+import assert from "node:assert/strict";
+import { randomBytes } from "node:crypto";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { after, before, describe, it } from "node:test";
+import { StorageError, } from "../Storage.js";
+/**
+ * Shared behavioural contract every {@link StorageProvider} must pass.
+ * Registered as a `node:test` suite; run it from a provider package's
+ * test file against the in-memory fake (always) and against a real
+ * account behind an env flag, e.g.:
+ *
+ * ```ts
+ * const upn = process.env.FAMILIAR_LIVE_MS365;
+ * if (upn) runStorageProviderContract("ms365 live", () => makeProvider(), { account: upn, selector: null });
+ * ```
+ *
+ * @param name - Suite name.
+ * @param makeProvider - Factory for the provider under test.
+ * @param options - Account, drive and scratch-folder settings.
+ */
+export function runStorageProviderContract(name, makeProvider, options) {
+    describe(`StorageProvider contract: ${name}`, () => {
+        let provider;
+        let drive;
+        let base;
+        let localDir;
+        before(async () => {
+            provider = await makeProvider();
+            drive = await provider.openDrive(options.account, options.selector);
+            localDir = await mkdtemp(path.join(tmpdir(), "storage-contract-"));
+            const parentId = await resolveBase(provider, drive, options.basePath);
+            const suffix = randomBytes(4).toString("hex");
+            base = await provider.createFolder(drive, parentId, `familiar-contract-${suffix}`, {
+                conflict: "fail",
+            });
+        });
+        after(async () => {
+            if (base) {
+                await provider.trash(drive, base.realId, {}).catch(() => undefined);
+            }
+            if (localDir) {
+                await rm(localDir, { recursive: true, force: true });
+            }
+        });
+        it("lists the account and opens its drive", async () => {
+            const accounts = await provider.listAccounts();
+            assert.ok(accounts.includes(options.account), `accounts: ${accounts.join(", ")}`);
+            const drives = await provider.listDrives(options.account, { limit: 50 });
+            assert.ok(drives.some((d) => d.id === drive.id), "opened drive is listed");
+        });
+        it("rejects an unknown drive selector with NotFound", async () => {
+            await assert.rejects(provider.openDrive(options.account, "drives/definitely-not-a-drive"), isStorageError("NotFound"));
+        });
+        it("stats the root as a folder", async () => {
+            const root = await provider.stat(drive, await provider.rootRealId(drive));
+            assert.equal(root?.kind, "folder");
+        });
+        it("creates folders with fail / reuse semantics", async () => {
+            const folder = await provider.createFolder(drive, base.realId, "sub", {
+                conflict: "fail",
+            });
+            assert.equal(folder.kind, "folder");
+            const again = await provider.createFolder(drive, base.realId, "sub", {
+                conflict: "reuse",
+            });
+            assert.equal(again.realId, folder.realId);
+            if (provider.capabilities(drive).uniqueNames) {
+                await assert.rejects(provider.createFolder(drive, base.realId, "sub", { conflict: "fail" }), isStorageError("NameConflict"));
+            }
+        });
+        it("uploads, lists, stats and downloads a file byte-for-byte", async () => {
+            const src = path.join(localDir, "hello.txt");
+            await writeFile(src, "hello contract");
+            const item = await provider.upload(drive, base.realId, "hello.txt", { path: src, size: 14, mimeType: "text/plain" }, { conflict: "fail" });
+            assert.equal(item.kind, "file");
+            assert.equal(item.size, 14);
+            assert.ok(item.revision, "upload returns a revision");
+            const page = await provider.list(drive, base.realId, { limit: 50 });
+            assert.ok(page.entries.some((e) => e.realId === item.realId));
+            const stat = await provider.stat(drive, item.realId);
+            assert.equal(stat?.name, "hello.txt");
+            const dest = path.join(localDir, "hello.down");
+            const result = await provider.download(drive, item.realId, dest);
+            assert.equal(result.bytes, 14);
+            assert.equal(await readFile(dest, "utf8"), "hello contract");
+        });
+        it("honours conflict=fail and guarded replace", async () => {
+            const src = path.join(localDir, "rev.txt");
+            await writeFile(src, "v1");
+            const v1 = await provider.upload(drive, base.realId, "rev.txt", { path: src, size: 2 }, { conflict: "fail" });
+            if (provider.capabilities(drive).uniqueNames) {
+                await assert.rejects(provider.upload(drive, base.realId, "rev.txt", { path: src, size: 2 }, { conflict: "fail" }), isStorageError("NameConflict"));
+            }
+            await writeFile(src, "v2!");
+            const v2 = await provider.upload(drive, base.realId, "rev.txt", { path: src, size: 3 }, {
+                conflict: "replace",
+                replaceRealId: v1.realId,
+                ifRevision: v1.revision ?? undefined,
+            });
+            assert.equal(v2.realId, v1.realId);
+            assert.notEqual(v2.revision, v1.revision);
+            await assert.rejects(provider.upload(drive, base.realId, "rev.txt", { path: src, size: 3 }, {
+                conflict: "replace",
+                replaceRealId: v1.realId,
+                ifRevision: v1.revision ?? "stale",
+            }), isStorageError("RevisionMismatch"));
+        });
+        it("renames, moves, copies and trashes", async () => {
+            const src = path.join(localDir, "mv.txt");
+            await writeFile(src, "move me");
+            const file = await provider.upload(drive, base.realId, "mv.txt", { path: src, size: 7 }, { conflict: "fail" });
+            const dest = await provider.createFolder(drive, base.realId, "dest", {
+                conflict: "reuse",
+            });
+            const renamed = await provider.move(drive, file.realId, { name: "moved.txt" }, {});
+            assert.equal(renamed.name, "moved.txt");
+            const moved = await provider.move(drive, file.realId, { parentRealId: dest.realId }, {});
+            assert.equal(moved.parentRealId, dest.realId);
+            const copied = await provider.copy(drive, file.realId, { parentRealId: base.realId, name: "copy.txt" }, { conflict: "fail" });
+            assert.equal(copied.name, "copy.txt");
+            await provider.trash(drive, copied.realId, {});
+            assert.equal(await provider.stat(drive, copied.realId), null);
+        });
+        it("resolves paths natively when path-addressed", async () => {
+            if (provider.capabilities(drive).addressing !== "path" || !provider.resolvePath) {
+                return;
+            }
+            const basePath = (await provider.stat(drive, base.realId))?.path;
+            assert.ok(basePath, "path-addressed providers report paths");
+            const hits = await provider.resolvePath(drive, `${basePath}/sub`);
+            assert.equal(hits.length, 1);
+            assert.deepEqual(await provider.resolvePath(drive, `${basePath}/nope-${Date.now()}`), []);
+        });
+        it("uploads a large file", { skip: options.largeFileBytes === undefined }, async () => {
+            const size = options.largeFileBytes ?? 0;
+            const src = path.join(localDir, "large.bin");
+            await writeFile(src, randomBytes(size));
+            const item = await provider.upload(drive, base.realId, "large.bin", { path: src, size }, { conflict: "fail" });
+            assert.equal(item.size, size);
+        });
+    });
+}
+/**
+ * Resolve the base folder the suite writes into.
+ *
+ * @throws Error when `basePath` does not resolve to exactly one folder.
+ */
+async function resolveBase(provider, drive, basePath) {
+    const root = await provider.rootRealId(drive);
+    if (basePath === undefined || basePath === "/") {
+        return root;
+    }
+    if (!provider.resolvePath) {
+        throw new Error("basePath requires a path-addressed provider");
+    }
+    const hits = await provider.resolvePath(drive, basePath);
+    const folder = hits.length === 1 ? hits[0] : undefined;
+    if (folder?.kind !== "folder") {
+        throw new Error(`basePath ${basePath} is not a single folder`);
+    }
+    return folder.realId;
+}
+/** `assert.rejects` matcher for a {@link StorageError} with `code`. */
+function isStorageError(code) {
+    return (err) => err instanceof StorageError && err.code === code;
+}

package/build/testing/index.d.ts

@@ -1,4 +1,6 @@
+export { FAKE_NATIVE_EXPORTS, type FakeStorageFlavor, type FakeStorageOptions, FakeStorageProvider, } from "./FakeStorageProvider.js";
 export { MockAgentRunBus, type MockAgentRunBusListener } from "./MockAgentRunBus.js";
 export { MockBusStore } from "./MockBusStore.js";
 export { MockEventBus } from "./MockEventBus.js";
 export { type MockLogEntry, MockLogger } from "./MockLogger.js";
+export { runStorageProviderContract, type StorageContractOptions, } from "./StorageProviderContract.js";

package/build/testing/index.js

@@ -1,4 +1,6 @@
+export { FAKE_NATIVE_EXPORTS, FakeStorageProvider, } from "./FakeStorageProvider.js";
 export { MockAgentRunBus } from "./MockAgentRunBus.js";
 export { MockBusStore } from "./MockBusStore.js";
 export { MockEventBus } from "./MockEventBus.js";
 export { MockLogger } from "./MockLogger.js";
+export { runStorageProviderContract, } from "./StorageProviderContract.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@getfamiliar/shared",
   "type": "module",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Familiar — shared types and bus-state client between host and container.",
   "publishConfig": {
     "access": "public"