poe-code 12.0.6 → 12.0.8

package/packages/package-lint/dist/bundle-policy.js

@@ -1,11 +1,94 @@
 import { isBuiltin } from "node:module";
 import path from "node:path";
+export const canonicalFsRoutes = [
+    {
+        workspace: "@poe-code/safe-fs",
+        specifier: "poe-code/safe-fs",
+        key: "./safe-fs",
+        source: { node: "packages/safe-fs/src/index.ts", browser: "packages/safe-fs/src/core.ts" },
+        runtime: {
+            node: "packages/safe-js/dist/safe-fs.js",
+            browser: "packages/safe-js/dist/browser/safe-fs.js"
+        },
+        types: { node: "packages/safe-fs/dist/index.d.ts", browser: "packages/safe-fs/dist/core.d.ts" }
+    },
+    {
+        workspace: "@poe-code/safe-fs/core",
+        specifier: "poe-code/safe-fs/core",
+        key: "./safe-fs/core",
+        source: { node: "packages/safe-fs/src/core.ts", browser: "packages/safe-fs/src/core.ts" },
+        runtime: {
+            node: "packages/safe-js/dist/safe-fs-core.js",
+            browser: "packages/safe-js/dist/browser/safe-fs-core.js"
+        },
+        types: { node: "packages/safe-fs/dist/core.d.ts", browser: "packages/safe-fs/dist/core.d.ts" }
+    },
+    {
+        workspace: "@poe-code/safe-fs/node",
+        specifier: "poe-code/safe-fs/node",
+        key: "./safe-fs/node",
+        source: { node: "packages/safe-fs/src/node-host.ts", browser: null },
+        runtime: { node: "packages/safe-js/dist/safe-fs-node.js", browser: null },
+        types: {
+            node: "packages/safe-fs/dist/node-host.d.ts",
+            browser: "packages/safe-fs/dist/node-unavailable.d.ts"
+        }
+    }
+];
+export const canonicalFsProfiles = {
+    node: {
+        outdir: "packages/safe-js/dist",
+        policy: "packages/safe-fs/src/platform/node.ts",
+        types: "packages/safe-fs/dist/platform/node.d.ts"
+    },
+    browser: {
+        outdir: "packages/safe-js/dist/browser",
+        policy: "packages/safe-fs/src/platform/browser.ts",
+        types: "packages/safe-fs/dist/platform/browser.d.ts"
+    }
+};
+export const canonicalFsExports = Object.fromEntries(canonicalFsRoutes.map((route) => [
+    route.key,
+    {
+        types: { browser: `./${route.types.browser}`, default: `./${route.types.node}` },
+        browser: route.runtime.browser === null ? null : `./${route.runtime.browser}`,
+        import: `./${route.runtime.node}`
+    }
+]));
+const nodeOnlySafeJsExports = Object.fromEntries([
+    ["./safe-js", "index"],
+    ["./safe-js/core", "core"],
+    ["./safe-js/cli", "cli"],
+    ["./safejs", "index"],
+    ["./safejs/core", "core"],
+    ["./safejs/cli", "cli"]
+].map(([route, entry]) => [
+    route,
+    {
+        types: {
+            browser: "./packages/safe-fs/dist/node-unavailable.d.ts",
+            default: `./packages/safe-js/dist/${entry}.d.ts`
+        },
+        browser: null,
+        import: `./packages/safe-js/dist/${entry}.js`
+    }
+]));
+export const canonicalFsTypeImports = {
+    "#safe-fs-platform": {
+        types: {
+            browser: `./${canonicalFsProfiles.browser.types}`,
+            default: `./${canonicalFsProfiles.node.types}`
+        },
+        default: null
+    }
+};
 export const canonicalFs = {
     workspace: "@poe-code/safe-fs",
     specifier: "poe-code/safe-fs",
     source: "packages/safe-fs/src/index.ts",
-    runtime: "packages/safejs/dist/safe-fs.js",
-    types: "packages/safe-fs/dist/index.d.ts"
+    runtime: "packages/safe-js/dist/safe-fs.js",
+    types: "packages/safe-fs/dist/index.d.ts",
+    routes: canonicalFsRoutes
 };
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
@@ -31,7 +114,8 @@ function packageName(specifier) {
 }
 export function findBundleIssues(manifest, workspaceNames, metafile, packedFiles) {
     const issues = [];
-    const exported = record(record(manifest.exports)["./safe-fs"]);
+    const exported = record(manifest.exports);
+    const routes = new Set(canonicalFsRoutes.map((route) => route.specifier));
     const imports = new Set(Object.values(metafile.outputs ?? {}).flatMap((output) => (output.imports ?? [])
         .filter((dependency) => dependency.external)
         .map((dependency) => dependency.path ?? "")));
@@ -42,7 +126,7 @@ export function findBundleIssues(manifest, workspaceNames, metafile, packedFiles
     for (const specifier of [...imports].sort()) {
         if (isBuiltin(specifier))
             continue;
-        if (specifier === canonicalFs.specifier && manifest.name === "poe-code")
+        if (routes.has(specifier) && manifest.name === "poe-code")
             continue;
         const dependency = packageName(specifier);
         const reason = !dependency
@@ -55,79 +139,227 @@ export function findBundleIssues(manifest, workspaceNames, metafile, packedFiles
         if (reason)
             issues.push({ external: specifier, reason });
     }
+    const exportKeys = Object.keys(exported).filter((key) => key === "./safe-fs" || key.startsWith("./safe-fs/"));
     if (!metafile.canonicalBundle &&
-        !imports.has(canonicalFs.specifier) &&
-        !Object.keys(exported).length)
+        !metafile.browserCanonicalBundle &&
+        !exportKeys.length &&
+        ![...imports].some((specifier) => routes.has(specifier)))
         return issues;
-    const fail = (reason) => issues.push({ external: canonicalFs.specifier, reason });
-    if (manifest.name !== "poe-code" ||
-        exported.import !== `./${canonicalFs.runtime}` ||
-        exported.types !== `./${canonicalFs.types}` ||
-        Object.keys(exported).some((condition) => condition !== "import" && condition !== "types")) {
+    const fail = (reason, external = canonicalFs.specifier) => {
+        if (!issues.some((issue) => issue.external === external && issue.reason === reason))
+            issues.push({ external, reason });
+    };
+    for (const route of canonicalFsRoutes) {
+        if (manifest.name !== "poe-code" ||
+            JSON.stringify(exported[route.key]) !== JSON.stringify(canonicalFsExports[route.key]))
+            fail("invalid-canonical-export", route.specifier);
+    }
+    if (exportKeys.some((key) => !canonicalFsRoutes.some((route) => route.key === key)))
         fail("invalid-canonical-export");
+    for (const [key, expected] of Object.entries(nodeOnlySafeJsExports)) {
+        if (JSON.stringify(exported[key]) !== JSON.stringify(expected))
+            fail("invalid-node-only-safejs-export", `poe-code${key.slice(1)}`);
+    }
+    if (JSON.stringify(record(manifest.imports)["#safe-fs-platform"]) !==
+        JSON.stringify(canonicalFsTypeImports["#safe-fs-platform"]))
+        fail("invalid-canonical-type-import");
+    const canonicalPaths = canonicalFsRoutes
+        .flatMap((route) => [...Object.values(route.runtime), ...Object.values(route.types)])
+        .filter((filename) => filename !== null);
+    for (const filename of canonicalPaths) {
+        let directory = path.posix.dirname(filename);
+        while (directory !== ".") {
+            if (packedFiles.has(`${directory}/package.json`))
+                fail("nested-canonical-package-scope");
+            directory = path.posix.dirname(directory);
+        }
     }
-    if (!packedFiles.has(canonicalFs.types))
-        fail("unpacked-canonical-types");
     if ([...packedFiles].some((filename) => filename.startsWith("packages/safe-fs/dist/") &&
         [".js", ".mjs", ".cjs"].some((extension) => filename.endsWith(extension))))
         fail("duplicate-packed-runtime");
-    if (Object.keys(metafile.inputs ?? {}).some((input) => input.startsWith("packages/safe-fs/src/"))) {
+    if (Object.keys(metafile.inputs ?? {}).some((input) => input.startsWith("packages/safe-fs/src/")))
         fail("duplicate-canonical-runtime");
-    }
-    const canonical = metafile.canonicalBundle;
-    if (!canonical ||
-        !Array.isArray(canonical.entryPoints) ||
-        !canonical.entryPoints.includes(canonicalFs.source)) {
-        fail("missing-canonical-root");
-        return issues;
-    }
-    const outputs = canonical.metafile.outputs ?? {};
-    if (!Object.hasOwn(canonical.metafile.inputs ?? {}, canonicalFs.source))
-        fail("missing-canonical-source");
-    if (outputs[canonicalFs.runtime]?.entryPoint !== canonicalFs.source)
-        fail("invalid-canonical-root");
-    for (const entry of canonical.entryPoints) {
-        if (!Object.values(outputs).some((output) => output.entryPoint === entry))
-            fail("missing-declared-root");
-    }
-    const pending = [canonicalFs.runtime];
-    const visited = new Set();
-    while (pending.length) {
-        const filename = pending.pop();
-        if (visited.has(filename))
-            continue;
-        visited.add(filename);
-        if (!filename.startsWith("packages/safejs/dist/") ||
-            path.posix.normalize(filename) !== filename) {
-            fail("invalid-canonical-path");
+    const emptyTypes = "packages/safe-fs/dist/node-unavailable.d.ts";
+    if (!metafile.canonicalEmptyTypes?.includes(emptyTypes))
+        fail("nonempty-browser-node-types", "poe-code/safe-fs/node");
+    for (const profile of ["node", "browser"]) {
+        const settings = canonicalFsProfiles[profile];
+        const canonical = profile === "node" ? metafile.canonicalBundle : metafile.browserCanonicalBundle;
+        if (!canonical || !Array.isArray(canonical.entryPoints)) {
+            fail("missing-canonical-root");
             continue;
         }
-        const output = outputs[filename];
-        if (!output) {
-            fail("missing-canonical-output");
-            continue;
+        const inputs = canonical.metafile.inputs ?? {};
+        if (!Object.hasOwn(inputs, settings.policy) ||
+            Object.hasOwn(inputs, canonicalFsProfiles[profile === "node" ? "browser" : "node"].policy))
+            fail("wrong-canonical-policy");
+        const outputs = canonical.metafile.outputs ?? {};
+        for (const singleton of [
+            "contracts/errors.ts",
+            "bridge/filesystem.ts",
+            "fs/memory/index.ts",
+            "fs/mount/comparison.ts",
+            "fs/s3/registry.ts",
+            "fs/s3/authority.ts",
+            `platform/${profile}.ts`
+        ]) {
+            const source = `packages/safe-fs/src/${singleton}`;
+            if (!Object.hasOwn(inputs, source))
+                continue;
+            const copies = Object.entries(outputs).filter(([filename, output]) => packedFiles.has(filename) && Object.hasOwn(output.inputs ?? {}, source));
+            if (copies.length > 1)
+                fail("duplicate-canonical-singleton");
+        }
+        const pending = [];
+        for (const route of canonicalFsRoutes) {
+            const source = route.source[profile];
+            const runtime = route.runtime[profile];
+            if (source === null || runtime === null)
+                continue;
+            if (!canonical.entryPoints.includes(source))
+                fail("missing-canonical-root", route.specifier);
+            if (!Object.hasOwn(inputs, source))
+                fail("missing-canonical-source", route.specifier);
+            if (outputs[runtime]?.entryPoint !== source)
+                fail("invalid-canonical-root", route.specifier);
+            pending.push(runtime);
+        }
+        for (const entry of canonical.entryPoints) {
+            if (!Object.values(outputs).some((output) => output.entryPoint === entry))
+                fail("missing-declared-root");
         }
-        if (!packedFiles.has(filename))
-            fail("unpacked-canonical-output");
-        if (filename.endsWith(".js"))
-            pending.push(`${filename}.map`);
-        if (Object.keys(output.inputs ?? {}).some((input) => !input.startsWith("packages/safe-fs/src/")))
-            fail("foreign-canonical-input");
-        if (output.cssBundle)
-            pending.push(output.cssBundle);
-        for (const dependency of output.imports ?? []) {
-            if (dependency.external) {
-                if (!dependency.path || !isBuiltin(dependency.path))
-                    fail("external-canonical-dependency");
+        const rootedOutputs = new Set();
+        const rootedPending = Object.entries(outputs)
+            .filter(([, output]) => output.entryPoint && canonical.entryPoints.includes(output.entryPoint))
+            .map(([filename]) => filename);
+        while (rootedPending.length) {
+            const filename = rootedPending.pop();
+            if (rootedOutputs.has(filename))
+                continue;
+            rootedOutputs.add(filename);
+            for (const dependency of outputs[filename]?.imports ?? []) {
+                if (!dependency.external && dependency.path)
+                    rootedPending.push(dependency.path);
+            }
+        }
+        for (const [filename, output] of Object.entries(outputs)) {
+            if (output.entryPoint && !rootedOutputs.has(filename) && packedFiles.has(filename))
+                fail("undeclared-canonical-root");
+        }
+        const visited = new Set();
+        while (pending.length) {
+            const filename = pending.pop();
+            if (visited.has(filename))
+                continue;
+            visited.add(filename);
+            if (!filename.startsWith(`${settings.outdir}/`) ||
+                path.posix.normalize(filename) !== filename ||
+                (profile === "node" && filename.startsWith(`${canonicalFsProfiles.browser.outdir}/`))) {
+                fail("invalid-canonical-path");
+                continue;
+            }
+            const output = outputs[filename];
+            if (!output) {
+                fail("missing-canonical-output");
+                continue;
+            }
+            if (!packedFiles.has(filename))
+                fail("unpacked-canonical-output");
+            if (filename.endsWith(".js"))
+                pending.push(`${filename}.map`);
+            if (Object.keys(output.inputs ?? {}).some((input) => !input.startsWith("packages/safe-fs/src/")))
+                fail("foreign-canonical-input");
+            if (output.cssBundle)
+                pending.push(output.cssBundle);
+            for (const dependency of output.imports ?? []) {
+                if (dependency.external) {
+                    if (profile === "browser" || !dependency.path || !isBuiltin(dependency.path))
+                        fail("external-canonical-dependency");
+                }
+                else if (dependency.path)
+                    pending.push(dependency.path);
+                else
+                    fail("missing-canonical-edge");
+            }
+        }
+        const typeQueue = canonicalFsRoutes.map((route) => route.types[profile]);
+        typeQueue.push(settings.types);
+        const seenTypes = new Set();
+        while (typeQueue.length) {
+            const filename = typeQueue.pop();
+            if (seenTypes.has(filename))
+                continue;
+            seenTypes.add(filename);
+            if (!filename.startsWith("packages/safe-fs/dist/") ||
+                path.posix.normalize(filename) !== filename ||
+                !filename.endsWith(".d.ts")) {
+                fail("invalid-canonical-types-path");
+                continue;
+            }
+            if (!packedFiles.has(filename))
+                fail("unpacked-canonical-types");
+            const edges = metafile.canonicalTypes?.[filename];
+            if (!Array.isArray(edges)) {
+                fail("missing-canonical-types");
+                continue;
+            }
+            for (const edge of edges) {
+                if (edge === "#safe-fs-platform")
+                    typeQueue.push(settings.types);
+                else if (isBuiltin(edge)) {
+                    if (profile === "browser")
+                        fail("external-canonical-types");
+                }
+                else if (edge.startsWith(".") &&
+                    !["?", "#", "%", "\\", ":"].some((character) => edge.includes(character)) &&
+                    (edge.endsWith(".js") || edge.endsWith(".d.ts"))) {
+                    const target = edge.endsWith(".js") ? `${edge.slice(0, -3)}.d.ts` : edge;
+                    typeQueue.push(path.posix.normalize(path.posix.join(path.posix.dirname(filename), target)));
+                }
+                else
+                    fail("external-canonical-types");
             }
-            else if (dependency.path)
-                pending.push(dependency.path);
-            else
-                fail("missing-canonical-edge");
         }
     }
     return issues;
 }
+export async function collectCanonicalDeclarations(rootDir, files) {
+    const { default: ts } = await import("typescript");
+    const declarations = await collectPackageFiles(rootDir, ["packages/safe-fs/dist/**/*.d.ts"], files);
+    const canonicalTypes = {};
+    const canonicalEmptyTypes = [];
+    for (const filename of declarations) {
+        const source = ts.createSourceFile(filename, await files.readFile(path.join(rootDir, filename)), ts.ScriptTarget.Latest, true);
+        const imports = new Set(source.referencedFiles.map((reference) => reference.fileName));
+        const visit = (node) => {
+            if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+                node.moduleSpecifier &&
+                ts.isStringLiteral(node.moduleSpecifier))
+                imports.add(node.moduleSpecifier.text);
+            if (ts.isImportTypeNode(node) &&
+                ts.isLiteralTypeNode(node.argument) &&
+                ts.isStringLiteral(node.argument.literal))
+                imports.add(node.argument.literal.text);
+            if (ts.isExternalModuleReference(node) &&
+                node.expression &&
+                ts.isStringLiteral(node.expression))
+                imports.add(node.expression.text);
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+        for (const reference of source.typeReferenceDirectives)
+            imports.add(`types:${reference.fileName}`);
+        canonicalTypes[filename] = [...imports];
+        if (source.statements.length === 1 &&
+            source.statements.every((statement) => ts.isExportDeclaration(statement) &&
+                !statement.moduleSpecifier &&
+                statement.exportClause &&
+                ts.isNamedExports(statement.exportClause) &&
+                statement.exportClause.elements.length === 0))
+            canonicalEmptyTypes.push(filename);
+    }
+    return { canonicalTypes, canonicalEmptyTypes };
+}
 export async function collectPackageFiles(rootDir, entries, files) {
     const packed = new Set();
     async function visit(filename, declarationsOnly) {

package/packages/package-lint/dist/model.d.ts

@@ -1,4 +1,4 @@
-import type { BundleMetafile } from "./bundle-policy.js";
+import { type BundleMetafile } from "./bundle-policy.js";
 import { type PackageFileView, type PacklistProvider } from "./packlist.js";
 import { type RuntimeAssetDeclaration, type RuntimeFileAssetView } from "./runtime-files.js";
 import { type SourceImportView } from "./source-imports.js";
@@ -40,6 +40,7 @@ export interface PackageInfo {
     ecosystem: Ecosystem;
     main: string | undefined;
     exports: unknown;
+    imports?: unknown;
     bin: Record<string, string>;
     files: string[];
     scripts: Record<string, string>;

package/packages/package-lint/dist/model.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { collectCanonicalDeclarations } from "./bundle-policy.js";
 import { parse as parseYaml } from "yaml";
 import { createNpmPacklistProvider, loadPackageFileView } from "./packlist.js";
 import { scanRuntimeFileAssets } from "./runtime-files.js";
@@ -107,6 +108,7 @@ async function loadPackage(fs, rootDir, relDir, isRoot) {
         ecosystem,
         main: typeof pkg.main === "string" ? pkg.main : undefined,
         exports: pkg.exports,
+        imports: pkg.imports,
         bin: toBinRecord(pkg.bin, typeof pkg.name === "string" ? pkg.name : relDir),
         files: Array.isArray(pkg.files)
             ? pkg.files.filter((f) => typeof f === "string")
@@ -448,12 +450,17 @@ export async function loadBuildView(fs, rootDir) {
     catch {
         return undefined;
     }
+    let metafile;
     try {
-        return parseMetafile(JSON.parse(raw));
+        metafile = JSON.parse(raw);
     }
     catch {
         return undefined;
     }
+    if (metafile.canonicalBundle || metafile.browserCanonicalBundle) {
+        Object.assign(metafile, await collectCanonicalDeclarations(rootDir, fs));
+    }
+    return parseMetafile(metafile);
 }
 /** All workspace packages plus the root package. */
 export function allPackages(model) {

package/packages/safe-fs/dist/bridge/filesystem.d.ts

@@ -0,0 +1,88 @@
+import type { FileSystem } from "../contracts/filesystem.js";
+import type { BridgePrimitives, BufferEncodingOption, FsBridgeDirent, FsBridgeEncoding, FsBridgeStats, MakeDirectoryOptions, Mode, ObjectEncodingOptions, StatOptions } from "./types.js";
+type Encoding = FsBridgeEncoding | "buffer";
+type ReadOptions = ObjectEncodingOptions & {
+    flag?: string | number | undefined;
+    signal?: AbortSignal | undefined;
+};
+type DirectoryOptions = {
+    encoding?: Encoding | null | undefined;
+    recursive?: boolean | undefined;
+    withFileTypes?: boolean | undefined;
+};
+export declare class FileSystemBridge<Binary extends Uint8Array> {
+    #private;
+    constructor(fs: FileSystem, options: {
+        readonly cwd?: string;
+        readonly signal?: AbortSignal;
+    }, primitives: BridgePrimitives<Binary>);
+    readFile(path: unknown, options?: {
+        encoding?: null | undefined;
+        flag?: string | number | undefined;
+        signal?: AbortSignal | undefined;
+    } | null): Promise<Binary>;
+    readFile(path: unknown, options: FsBridgeEncoding | (ReadOptions & {
+        encoding: FsBridgeEncoding;
+    })): Promise<string>;
+    readFile(path: unknown, options?: ReadOptions | FsBridgeEncoding | null): Promise<string | Binary>;
+    writeFile(path: unknown, data: unknown, options?: unknown): Promise<void>;
+    appendFile(path: unknown, data: unknown, options?: unknown): Promise<void>;
+    stat(path: unknown, options?: StatOptions & {
+        bigint?: false | undefined;
+    }): Promise<FsBridgeStats>;
+    stat(path: unknown, options: StatOptions & {
+        bigint: true;
+    }): Promise<never>;
+    stat(path: unknown, options?: StatOptions): Promise<FsBridgeStats>;
+    lstat(path: unknown, options?: StatOptions & {
+        bigint?: false | undefined;
+    }): Promise<FsBridgeStats>;
+    lstat(path: unknown, options: StatOptions & {
+        bigint: true;
+    }): Promise<never>;
+    lstat(path: unknown, options?: StatOptions): Promise<FsBridgeStats>;
+    readdir(path: unknown, options?: FsBridgeEncoding | (ObjectEncodingOptions & {
+        withFileTypes?: false | undefined;
+        recursive?: boolean | undefined;
+    }) | null): Promise<string[]>;
+    readdir(path: unknown, options: "buffer" | (DirectoryOptions & {
+        encoding: "buffer";
+        withFileTypes?: false | undefined;
+    })): Promise<Binary[]>;
+    readdir(path: unknown, options: ObjectEncodingOptions & {
+        withFileTypes: true;
+        recursive?: boolean | undefined;
+    }): Promise<FsBridgeDirent[]>;
+    readdir(path: unknown, options: DirectoryOptions & {
+        encoding: "buffer";
+        withFileTypes: true;
+    }): Promise<FsBridgeDirent<Binary>[]>;
+    mkdir(path: unknown, options: MakeDirectoryOptions & {
+        recursive: true;
+    }): Promise<string | undefined>;
+    mkdir(path: unknown, options?: Mode | (MakeDirectoryOptions & {
+        recursive?: false | undefined;
+    }) | null): Promise<void>;
+    mkdir(path: unknown, options?: Mode | MakeDirectoryOptions | null): Promise<string | undefined>;
+    access(path: unknown, mode?: number): Promise<void>;
+    rm(path: unknown, value?: unknown): Promise<void>;
+    rmdir(path: unknown, value?: unknown): Promise<void>;
+    rename(source: unknown, destination: unknown): Promise<void>;
+    copyFile(source: unknown, destination: unknown, mode?: number): Promise<void>;
+    cp(source: unknown, destination: unknown, value?: unknown): Promise<void>;
+    readlink(path: unknown, options?: ObjectEncodingOptions | FsBridgeEncoding | null): Promise<string>;
+    readlink(path: unknown, options: BufferEncodingOption): Promise<Binary>;
+    readlink(path: unknown, options?: ObjectEncodingOptions | BufferEncodingOption | string | null): Promise<string | Binary>;
+    realpath(path: unknown, options?: ObjectEncodingOptions | FsBridgeEncoding | null): Promise<string>;
+    realpath(path: unknown, options: BufferEncodingOption): Promise<Binary>;
+    realpath(path: unknown, options?: ObjectEncodingOptions | BufferEncodingOption | string | null): Promise<string | Binary>;
+    mkdtemp(prefix: string, options?: ObjectEncodingOptions | FsBridgeEncoding | null): Promise<string>;
+    mkdtemp(prefix: string, options: BufferEncodingOption): Promise<Binary>;
+    mkdtemp(prefix: string, options?: ObjectEncodingOptions | BufferEncodingOption | string | null): Promise<string | Binary>;
+    symlink(target: unknown, path: unknown, type?: unknown): Promise<void>;
+    link(existing: unknown, path: unknown): Promise<void>;
+    chmod(path: unknown, value: unknown): Promise<void>;
+    utimes(path: unknown, atime: unknown, mtime: unknown): Promise<void>;
+    truncate(path: unknown, length?: number): Promise<void>;
+}
+export {};

package/packages/safe-fs/dist/bridge/index.d.ts

@@ -0,0 +1,6 @@
+import type { FileSystem } from "../contracts/filesystem.js";
+import { FileSystemBridge } from "./filesystem.js";
+import type { FsBridgeOptions } from "./types.js";
+export type { FsBridgeCodec, FsBridgeDirent, FsBridgeEncoding, FsBridgeFileSystem, FsBridgeOptions, FsBridgeStats } from "./types.js";
+export type FsBridge = FileSystemBridge<Uint8Array<ArrayBuffer>>;
+export declare function createFsBridge(fs: FileSystem, options: FsBridgeOptions): FsBridge;

package/packages/safe-fs/dist/bridge/stats.d.ts

@@ -0,0 +1,4 @@
+import type { FsBridgeDirent, FsBridgeStats } from "./types.js";
+import type { FileStat, FileType } from "../contracts/filesystem.js";
+export declare function bridgeStats(stat: FileStat): FsBridgeStats;
+export declare function bridgeDirent<Name extends string | Uint8Array>(name: Name, parentPath: string, type: FileType): FsBridgeDirent<Name>;

package/packages/safe-fs/dist/bridge/types.d.ts

@@ -0,0 +1,75 @@
+import type { FileSystem, FsOptions } from "../contracts/filesystem.js";
+export interface FsBridgeCodec {
+    isEncoding(encoding: string): boolean;
+    encode(text: string, encoding: string): Uint8Array;
+    decode(bytes: Uint8Array, encoding: string): string;
+}
+export interface FsBridgeOptions {
+    readonly codec: FsBridgeCodec;
+    readonly cwd?: string;
+    readonly signal?: AbortSignal;
+}
+export interface FsBridgeFileSystem extends FileSystem {
+    rmdir?(path: string, options?: FsOptions): Promise<void>;
+}
+export type FsBridgeEncoding = "ascii" | "utf8" | "utf-8" | "utf16le" | "utf-16le" | "ucs2" | "ucs-2" | "base64" | "base64url" | "latin1" | "binary" | "hex";
+export interface ObjectEncodingOptions {
+    encoding?: FsBridgeEncoding | null | undefined;
+}
+export type BufferEncodingOption = "buffer" | {
+    encoding: "buffer";
+};
+export type Mode = number | string;
+export interface MakeDirectoryOptions {
+    recursive?: boolean | undefined;
+    mode?: Mode | undefined;
+}
+export interface StatOptions {
+    bigint?: boolean | undefined;
+}
+export interface FsBridgePredicates {
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+    isBlockDevice(): boolean;
+    isCharacterDevice(): boolean;
+    isFIFO(): boolean;
+    isSocket(): boolean;
+}
+export interface FsBridgeStats extends FsBridgePredicates {
+    dev: number;
+    ino: number;
+    mode: number;
+    nlink: number;
+    uid: number;
+    gid: number;
+    rdev: number;
+    size: number;
+    blksize: number;
+    blocks: number;
+    atimeMs: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    birthtimeMs: number;
+    atime: Date;
+    mtime: Date;
+    ctime: Date;
+    birthtime: Date;
+}
+export interface FsBridgeDirent<Name extends string | Uint8Array = string> extends FsBridgePredicates {
+    name: Name;
+    parentPath: string;
+    path: string;
+}
+export interface BridgePrimitives<Binary extends Uint8Array> {
+    readonly codec: FsBridgeCodec;
+    copyBytes(bytes: Uint8Array): Binary;
+    pathValue?(value: unknown): unknown;
+    randomSuffix(): string;
+    readonly paths: {
+        isAbsolute(path: string): boolean;
+        dirname(path: string): string;
+        relative(from: string, to: string): string;
+        resolve(cwd: string, ...paths: string[]): string;
+    };
+}

package/packages/safe-fs/dist/bridge/values.d.ts

@@ -0,0 +1,6 @@
+export declare function record(value: unknown, name: string): Record<string, unknown>;
+export declare function onlyKeys(value: Record<string, unknown>, allowed: readonly string[]): void;
+export declare function booleanValue(value: unknown, fallback?: boolean): boolean;
+export declare function abortError(): Error;
+export declare function checkSignal(signal: AbortSignal | undefined): void;
+export declare function withSignal<Value>(signal: AbortSignal | undefined, operation: () => Promise<Value>): Promise<Value>;

package/packages/safe-fs/dist/contracts/errors.d.ts

@@ -1,3 +1,5 @@
+import type { PlatformErrno } from "#safe-fs-platform";
+export type { PlatformErrno } from "#safe-fs-platform";
 declare const descriptions: {
     readonly EACCES: "permission denied";
     readonly EAGAIN: "resource temporarily unavailable";
@@ -37,7 +39,7 @@ export interface FsErrorOptions extends ErrorOptions {
 }
 export declare class FsError extends Error {
     readonly code: ErrnoCode;
-    readonly errno: number;
+    readonly errno: PlatformErrno;
     readonly syscall?: string;
     readonly path?: string;
     readonly dest?: string;
@@ -46,4 +48,3 @@ export declare class FsError extends Error {
 export declare function isErrnoCode(code: unknown): code is ErrnoCode;
 export declare function isFsError(error: unknown, code?: ErrnoCode): error is FsError;
 export declare function toFsError(error: unknown, options?: FsErrorOptions): FsError;
-export {};