@veryfront/ext-content-mdx 0.1.1186 → 0.1.1189

package/esm/src/platform/adapters/file-system-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-system-capabilities.d.ts","sourceRoot":"","sources":["../../../../src/src/platform/adapters/file-system-capabilities.ts"],"names":[],"mappings":"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"}

package/esm/src/platform/adapters/file-system-capabilities.js

@@ -0,0 +1,508 @@
+import { isProxyWithoutHooks } from "../compat/error-introspection.js";
+const apply = Reflect.apply;
+const getOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;
+const getPrototypeOf = Object.getPrototypeOf;
+const objectHasOwnProperty = Object.prototype.hasOwnProperty;
+const createObject = Object.create;
+const freezeObject = Object.freeze;
+const isArray = Array.isArray;
+const numberIsSafeInteger = Number.isSafeInteger;
+const universalObjectPrototype = Object.prototype;
+const NativeUint8Array = Uint8Array;
+const typedArrayPrototype = getPrototypeOf(NativeUint8Array.prototype);
+const typedArrayBufferGetter = requireIntrinsicGetter(typedArrayPrototype, "buffer", "Uint8Array buffer");
+const typedArrayByteLengthGetter = requireIntrinsicGetter(typedArrayPrototype, "byteLength", "Uint8Array byteLength");
+const typedArrayByteOffsetGetter = requireIntrinsicGetter(typedArrayPrototype, "byteOffset", "Uint8Array byte offset");
+const typedArrayNameGetter = requireIntrinsicGetter(typedArrayPrototype, Symbol.toStringTag, "Uint8Array name");
+const arrayBufferByteLengthGetter = requireIntrinsicGetter(ArrayBuffer.prototype, "byteLength", "ArrayBuffer byteLength");
+const arrayBufferResizableGetter = getOwnPropertyDescriptor(ArrayBuffer.prototype, "resizable")?.get;
+const setBytes = NativeUint8Array.prototype.set;
+const ABSENT_CAPABILITY = Symbol("absent filesystem capability");
+const INVALID_CAPABILITY = Symbol("invalid filesystem capability");
+const LEGACY_CAPABILITY_KEYS = [
+    "readFileBytes",
+    "readFileBytesBounded",
+    "readFileBytesWithinLimit",
+    "writeFileBytes",
+    "maxWholeFileReadBytes",
+];
+const BOUNDED_TEXT_CAPABILITY_KEYS = [
+    "readFileBytes",
+    "readFileBytesWithinLimit",
+    "maxWholeFileReadBytes",
+];
+const BYTE_READ_CAPABILITY_KEYS = [
+    "readFileBytes",
+    "readFileBytesBounded",
+    "readFileBytesWithinLimit",
+    "maxWholeFileReadBytes",
+];
+const SNAPSHOT_CAPABILITY_KEYS = ["readFileSnapshotWithinLimit"];
+const EXCLUSIVE_CREATE_CAPABILITY_KEYS = ["createFileBytesExclusive"];
+const GENERATION_CAPABILITY_KEYS = ["getSourceSnapshotVersion"];
+const VIRTUAL_READ_CAPABILITY_KEYS = [
+    "readFileBytes",
+    "readFileBytesWithinLimit",
+    "maxWholeFileReadBytes",
+];
+function hasOwn(value, key) {
+    return apply(objectHasOwnProperty, value, [key]);
+}
+function requireIntrinsicGetter(target, property, name) {
+    const descriptor = getOwnPropertyDescriptor(target, property);
+    const getter = descriptor !== undefined && hasOwn(descriptor, "get") ? descriptor.get : undefined;
+    if (typeof getter !== "function") {
+        throw new TypeError(`Required ${name} intrinsic is unavailable`);
+    }
+    return getter;
+}
+function invalidCapability(label, detail, cause) {
+    return cause === undefined
+        ? new TypeError(`${label} ${detail}`)
+        : new TypeError(`${label} ${detail}`, { cause });
+}
+function requireCapabilityObject(value, label) {
+    if (typeof value !== "object" ||
+        value === null ||
+        isProxyWithoutHooks(value) ||
+        isArray(value)) {
+        throw invalidCapability(label, "must be a non-array, non-Proxy object");
+    }
+}
+function captureDataProperties(value, label, keys, invalidFieldPolicy = "reject") {
+    const properties = createObject(null);
+    const resolved = createObject(null);
+    let remaining = keys.length;
+    let owner = value;
+    const seen = new Set();
+    for (let depth = 0; owner !== null && depth < 64; depth++) {
+        if (owner === universalObjectPrototype) {
+            owner = null;
+            break;
+        }
+        if (isProxyWithoutHooks(owner)) {
+            throw invalidCapability(label, "capabilities must not use a Proxy");
+        }
+        if (seen.has(owner)) {
+            throw invalidCapability(label, "capabilities have an invalid prototype chain");
+        }
+        seen.add(owner);
+        let parent;
+        try {
+            parent = getPrototypeOf(owner);
+        }
+        catch (cause) {
+            throw invalidCapability(label, "capabilities could not be inspected safely", cause);
+        }
+        // A foreign realm's Object.prototype is identified by its terminal
+        // position rather than by local identity and is never adapter authority.
+        if (owner !== value && parent === null) {
+            owner = null;
+            break;
+        }
+        for (let index = 0; index < keys.length; index++) {
+            const key = keys[index];
+            if (resolved[key])
+                continue;
+            let descriptor;
+            try {
+                descriptor = getOwnPropertyDescriptor(owner, key);
+            }
+            catch (cause) {
+                throw invalidCapability(label, "capabilities could not be inspected safely", cause);
+            }
+            if (descriptor === undefined)
+                continue;
+            resolved[key] = true;
+            remaining--;
+            if (!hasOwn(descriptor, "value")) {
+                if (invalidFieldPolicy === "reject") {
+                    throw invalidCapability(label, key === "maxWholeFileReadBytes"
+                        ? `${key} must be a data property`
+                        : `${key} must be a data-property method`);
+                }
+                properties[key] = INVALID_CAPABILITY;
+                continue;
+            }
+            properties[key] = descriptor.value;
+        }
+        if (remaining === 0) {
+            owner = null;
+            break;
+        }
+        owner = parent;
+    }
+    if (owner !== null && remaining > 0) {
+        throw invalidCapability(label, "capability prototype chain is too deep");
+    }
+    for (let index = 0; index < keys.length; index++) {
+        const key = keys[index];
+        if (!resolved[key])
+            properties[key] = ABSENT_CAPABILITY;
+    }
+    return freezeObject(properties);
+}
+function requireOptionalMethod(candidate, label, key, allowExplicitUndefined = true) {
+    if (candidate === ABSENT_CAPABILITY ||
+        (allowExplicitUndefined && candidate === undefined))
+        return undefined;
+    if (typeof candidate !== "function" || isProxyWithoutHooks(candidate)) {
+        throw invalidCapability(label, `${key} must be a non-Proxy function`);
+    }
+    return candidate;
+}
+function getUint8ArrayByteLength(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    try {
+        if (apply(typedArrayNameGetter, value, []) !== "Uint8Array")
+            return undefined;
+        const byteLength = apply(typedArrayByteLengthGetter, value, []);
+        return typeof byteLength === "number" && numberIsSafeInteger(byteLength) && byteLength >= 0
+            ? byteLength
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Admit an untrusted byte result before copying it into an immutable-size,
+ * tightly allocated ArrayBuffer. The maximum is checked from the intrinsic
+ * Uint8Array byte length before allocating the defensive copy.
+ */
+export function copyFixedUint8ArrayWithinLimit(value, maximumBytes, label) {
+    if (!numberIsSafeInteger(maximumBytes) || maximumBytes <= 0) {
+        throw new RangeError(`${label} maximum must be a positive safe integer`);
+    }
+    const byteLength = getUint8ArrayByteLength(value);
+    if (byteLength === undefined) {
+        throw new TypeError(`${label} reader returned invalid bytes`);
+    }
+    // Size overflow is a RangeError across the bounded-read surface; a malformed
+    // or dishonest result type stays a TypeError. Boundaries that present a
+    // different class to their own callers normalize this cause themselves.
+    if (byteLength > maximumBytes) {
+        throw new RangeError(`${label} exceeds ${maximumBytes} bytes`);
+    }
+    let buffer;
+    let resizable = false;
+    try {
+        buffer = apply(typedArrayBufferGetter, value, []);
+        apply(arrayBufferByteLengthGetter, buffer, []);
+        resizable = arrayBufferResizableGetter !== undefined &&
+            apply(arrayBufferResizableGetter, buffer, []) === true;
+    }
+    catch (cause) {
+        throw new TypeError(`${label} reader must return bytes backed by a fixed ArrayBuffer`, {
+            cause,
+        });
+    }
+    if (resizable) {
+        throw new TypeError(`${label} reader must return bytes backed by a fixed ArrayBuffer`);
+    }
+    const copy = new NativeUint8Array(byteLength);
+    try {
+        apply(setBytes, copy, [value]);
+    }
+    catch (cause) {
+        throw new TypeError(`${label} reader returned invalid bytes`, { cause });
+    }
+    let copyByteLength;
+    let copyByteOffset;
+    let copyBuffer;
+    let copyBufferByteLength;
+    try {
+        copyByteLength = apply(typedArrayByteLengthGetter, copy, []);
+        copyByteOffset = apply(typedArrayByteOffsetGetter, copy, []);
+        copyBuffer = apply(typedArrayBufferGetter, copy, []);
+        copyBufferByteLength = apply(arrayBufferByteLengthGetter, copyBuffer, []);
+    }
+    catch (cause) {
+        throw new TypeError(`${label} could not allocate a fixed byte copy`, { cause });
+    }
+    if (copyByteLength !== byteLength ||
+        copyByteOffset !== 0 ||
+        copyBufferByteLength !== byteLength) {
+        throw new TypeError(`${label} could not allocate a tight fixed byte copy`);
+    }
+    return copy;
+}
+/**
+ * Extract the ArrayBuffer from an admitted tight fixed Uint8Array without
+ * consulting mutable global constructors or configurable typed-array getters.
+ */
+export function getFixedUint8ArrayBuffer(value, label) {
+    const byteLength = getUint8ArrayByteLength(value);
+    if (byteLength === undefined) {
+        throw new TypeError(`${label} must be a Uint8Array`);
+    }
+    let byteOffset;
+    let buffer;
+    let bufferByteLength;
+    let resizable = false;
+    try {
+        byteOffset = apply(typedArrayByteOffsetGetter, value, []);
+        buffer = apply(typedArrayBufferGetter, value, []);
+        bufferByteLength = apply(arrayBufferByteLengthGetter, buffer, []);
+        resizable = arrayBufferResizableGetter !== undefined &&
+            apply(arrayBufferResizableGetter, buffer, []) === true;
+    }
+    catch (cause) {
+        throw new TypeError(`${label} must use a tight fixed ArrayBuffer`, { cause });
+    }
+    if (byteOffset !== 0 || bufferByteLength !== byteLength || resizable) {
+        throw new TypeError(`${label} must use a tight fixed ArrayBuffer`);
+    }
+    return buffer;
+}
+/** Read the intrinsic byte length only after verifying a tight fixed buffer. */
+export function getFixedUint8ArrayByteLength(value, label) {
+    const byteLength = getUint8ArrayByteLength(value);
+    if (byteLength === undefined) {
+        throw new TypeError(`${label} must be a Uint8Array`);
+    }
+    getFixedUint8ArrayBuffer(value, label);
+    return byteLength;
+}
+function copyExclusiveCreateBytes(content, label) {
+    const byteLength = getUint8ArrayByteLength(content);
+    if (byteLength === undefined) {
+        throw invalidCapability(label, "create content must be a Uint8Array");
+    }
+    return copyFixedUint8ArrayWithinLimit(content, byteLength === 0 ? 1 : byteLength, `${label} create content`);
+}
+function requirePositiveByteLimit(value, label) {
+    if (!numberIsSafeInteger(value) || value <= 0) {
+        throw new RangeError(`${label} must be a positive safe integer`);
+    }
+    return value;
+}
+function requireGeneration(value, label) {
+    if (!numberIsSafeInteger(value) || value < 0) {
+        throw invalidCapability(label, "generation must be a non-negative safe integer");
+    }
+    return value;
+}
+function captureWholeFileReader(value, properties, label, defensiveResults, allowExplicitUndefined) {
+    const rawReadFileBytes = requireOptionalMethod(properties.readFileBytes, label, "readFileBytes", allowExplicitUndefined);
+    const ceilingCandidate = properties.maxWholeFileReadBytes;
+    const ceiling = ceilingCandidate === ABSENT_CAPABILITY ||
+        (allowExplicitUndefined && ceilingCandidate === undefined)
+        ? undefined
+        : ceilingCandidate;
+    if (ceiling !== undefined && (!numberIsSafeInteger(ceiling) || ceiling <= 0)) {
+        throw invalidCapability(label, "maxWholeFileReadBytes must be a positive safe integer");
+    }
+    if (ceiling !== undefined && rawReadFileBytes === undefined) {
+        throw invalidCapability(label, "maxWholeFileReadBytes requires readFileBytes");
+    }
+    if (ceiling === undefined || rawReadFileBytes === undefined)
+        return undefined;
+    const maximumBytes = ceiling;
+    const read = defensiveResults
+        ? async (path) => {
+            const result = await apply(rawReadFileBytes, value, [path]);
+            return copyFixedUint8ArrayWithinLimit(result, maximumBytes, `${label} whole-file`);
+        }
+        : (path) => apply(rawReadFileBytes, value, [path]);
+    const captured = createObject(null);
+    captured.maximumBytes = maximumBytes;
+    captured.read = read;
+    return freezeObject(captured);
+}
+/**
+ * Preserve the broad legacy capture temporarily for its scheduled consumers.
+ * Bounded text passes the narrow purpose so writer and prefix fields are never
+ * inspected.
+ */
+export function captureFileSystemCapabilities(value, label = "Filesystem", purpose = "legacy") {
+    requireCapabilityObject(value, label);
+    const keys = purpose === "bounded-text"
+        ? BOUNDED_TEXT_CAPABILITY_KEYS
+        : purpose === "byte-read"
+            ? BYTE_READ_CAPABILITY_KEYS
+            : LEGACY_CAPABILITY_KEYS;
+    const properties = captureDataProperties(value, label, keys);
+    const rawReadFileBytes = requireOptionalMethod(properties.readFileBytes, label, "readFileBytes");
+    const rawBoundedReader = purpose === "bounded-text"
+        ? undefined
+        : requireOptionalMethod(properties.readFileBytesBounded, label, "readFileBytesBounded");
+    const rawExactReader = requireOptionalMethod(properties.readFileBytesWithinLimit, label, "readFileBytesWithinLimit");
+    const rawWriter = purpose !== "legacy" ? undefined : requireOptionalMethod(properties.writeFileBytes, label, "writeFileBytes");
+    const readFileBytes = rawReadFileBytes === undefined
+        ? undefined
+        : (path) => apply(rawReadFileBytes, value, [path]);
+    const readFileBytesBounded = rawBoundedReader === undefined
+        ? undefined
+        : (path, byteLimit) => apply(rawBoundedReader, value, [path, byteLimit]);
+    const readFileBytesWithinLimit = rawExactReader === undefined
+        ? undefined
+        : (path, byteLimit) => apply(rawExactReader, value, [path, byteLimit]);
+    const writeFileBytes = rawWriter === undefined
+        ? undefined
+        : (path, content) => apply(rawWriter, value, [path, content]);
+    const wholeFileReader = captureWholeFileReader(value, properties, label, false, true);
+    const captured = createObject(null);
+    if (readFileBytes !== undefined)
+        captured.readFileBytes = readFileBytes;
+    if (readFileBytesBounded !== undefined)
+        captured.readFileBytesBounded = readFileBytesBounded;
+    if (readFileBytesWithinLimit !== undefined) {
+        captured.readFileBytesWithinLimit = readFileBytesWithinLimit;
+    }
+    if (writeFileBytes !== undefined)
+        captured.writeFileBytes = writeFileBytes;
+    if (wholeFileReader !== undefined)
+        captured.wholeFileReader = wholeFileReader;
+    return freezeObject(captured);
+}
+/**
+ * Capture the established byte-reader surface while defensively admitting
+ * every result. New purpose-specific code should prefer the narrower capture
+ * functions above.
+ */
+export function captureByteReadCapabilities(value, label = "Filesystem") {
+    const capabilities = captureFileSystemCapabilities(value, label, "byte-read");
+    const captured = createObject(null);
+    if (capabilities.readFileBytes !== undefined) {
+        captured.unbounded = async (path) => copyFixedUint8ArrayWithinLimit(await capabilities.readFileBytes(path), Number.MAX_SAFE_INTEGER, `${label} whole-file`);
+    }
+    if (capabilities.wholeFileReader !== undefined) {
+        const rawWhole = capabilities.wholeFileReader;
+        const whole = createObject(null);
+        whole.maximumBytes = rawWhole.maximumBytes;
+        whole.read = async (path) => copyFixedUint8ArrayWithinLimit(await rawWhole.read(path), rawWhole.maximumBytes, `${label} whole-file`);
+        captured.whole = freezeObject(whole);
+    }
+    if (capabilities.readFileBytesBounded !== undefined) {
+        captured.prefix = async (path, byteLimit) => {
+            const limit = requirePositiveByteLimit(byteLimit, `${label} prefix byte limit`);
+            return copyFixedUint8ArrayWithinLimit(await capabilities.readFileBytesBounded(path, limit), limit, `${label} prefix`);
+        };
+    }
+    if (capabilities.readFileBytesWithinLimit !== undefined) {
+        captured.exact = async (path, byteLimit) => {
+            const limit = requirePositiveByteLimit(byteLimit, `${label} exact byte limit`);
+            return copyFixedUint8ArrayWithinLimit(await capabilities.readFileBytesWithinLimit(path, limit), limit, `${label} exact`);
+        };
+    }
+    return freezeObject(captured);
+}
+function admitQuarantinedMethod(candidate) {
+    if (candidate === ABSENT_CAPABILITY ||
+        candidate === INVALID_CAPABILITY ||
+        candidate === undefined ||
+        typeof candidate !== "function" ||
+        isProxyWithoutHooks(candidate)) {
+        return undefined;
+    }
+    return candidate;
+}
+/**
+ * Capture legacy byte capabilities after genuine snapshot authority has been
+ * proven independently. Malformed optional fields are omitted one at a time;
+ * unsafe object or prototype provenance still rejects the adapter.
+ */
+export function captureLegacyFileSystemCapabilitiesForSnapshot(value, label = "Filesystem") {
+    requireCapabilityObject(value, label);
+    const properties = captureDataProperties(value, label, LEGACY_CAPABILITY_KEYS, "quarantine");
+    const rawReadFileBytes = admitQuarantinedMethod(properties.readFileBytes);
+    const rawBoundedReader = admitQuarantinedMethod(properties.readFileBytesBounded);
+    const rawExactReader = admitQuarantinedMethod(properties.readFileBytesWithinLimit);
+    const rawWriter = admitQuarantinedMethod(properties.writeFileBytes);
+    const ceilingCandidate = properties.maxWholeFileReadBytes;
+    const maximumBytes = numberIsSafeInteger(ceilingCandidate) &&
+        ceilingCandidate > 0
+        ? ceilingCandidate
+        : undefined;
+    const captured = createObject(null);
+    if (rawReadFileBytes !== undefined) {
+        const readFileBytes = (path) => apply(rawReadFileBytes, value, [path]);
+        captured.readFileBytes = readFileBytes;
+        if (maximumBytes !== undefined) {
+            const wholeFileReader = createObject(null);
+            wholeFileReader.maximumBytes = maximumBytes;
+            wholeFileReader.read = readFileBytes;
+            captured.wholeFileReader = freezeObject(wholeFileReader);
+        }
+    }
+    if (rawBoundedReader !== undefined) {
+        captured.readFileBytesBounded = (path, byteLimit) => apply(rawBoundedReader, value, [path, byteLimit]);
+    }
+    if (rawExactReader !== undefined) {
+        captured.readFileBytesWithinLimit = (path, byteLimit) => apply(rawExactReader, value, [path, byteLimit]);
+    }
+    if (rawWriter !== undefined) {
+        captured.writeFileBytes = (path, content) => apply(rawWriter, value, [path, content]);
+    }
+    return freezeObject(captured);
+}
+export function captureSnapshotReadCapability(value, label = "Filesystem", allowExplicitUndefined = false) {
+    requireCapabilityObject(value, label);
+    const properties = captureDataProperties(value, label, SNAPSHOT_CAPABILITY_KEYS);
+    const rawReader = requireOptionalMethod(properties.readFileSnapshotWithinLimit, label, "readFileSnapshotWithinLimit", allowExplicitUndefined);
+    if (rawReader === undefined)
+        return undefined;
+    const captured = createObject(null);
+    captured.read = async (path, containmentRoot, byteLimit) => {
+        requirePositiveByteLimit(byteLimit, `${label} snapshot byte limit`);
+        const result = await apply(rawReader, value, [path, containmentRoot, byteLimit]);
+        return copyFixedUint8ArrayWithinLimit(result, byteLimit, `${label} snapshot`);
+    };
+    return freezeObject(captured);
+}
+export function captureExclusiveCreateCapability(value, label = "Filesystem") {
+    requireCapabilityObject(value, label);
+    const properties = captureDataProperties(value, label, EXCLUSIVE_CREATE_CAPABILITY_KEYS);
+    const rawCreator = requireOptionalMethod(properties.createFileBytesExclusive, label, "createFileBytesExclusive", false);
+    if (rawCreator === undefined)
+        return undefined;
+    const captured = createObject(null);
+    captured.create = (path, content) => {
+        const fixedContent = copyExclusiveCreateBytes(content, label);
+        return apply(rawCreator, value, [path, fixedContent]);
+    };
+    return freezeObject(captured);
+}
+export function captureStaticReadCapabilities(value, label = "Filesystem") {
+    requireCapabilityObject(value, label);
+    const snapshot = captureSnapshotReadCapability(value, label);
+    const captured = createObject(null);
+    if (snapshot !== undefined)
+        captured.snapshot = snapshot;
+    // Virtual readers are authority only behind an explicit own data marker.
+    // An absent, inherited, or accessor marker leaves unrelated fields unobserved.
+    const semantics = getOwnPropertyDescriptor(value, "symlinkSemantics");
+    if (semantics === undefined ||
+        !hasOwn(semantics, "value") ||
+        semantics.value !== "none") {
+        return freezeObject(captured);
+    }
+    const generationProperties = captureDataProperties(value, label, GENERATION_CAPABILITY_KEYS);
+    const rawGeneration = requireOptionalMethod(generationProperties.getSourceSnapshotVersion, label, "getSourceSnapshotVersion", false);
+    if (rawGeneration === undefined)
+        return freezeObject(captured);
+    const readerProperties = captureDataProperties(value, label, VIRTUAL_READ_CAPABILITY_KEYS);
+    const rawExactReader = requireOptionalMethod(readerProperties.readFileBytesWithinLimit, label, "readFileBytesWithinLimit", false);
+    const whole = captureWholeFileReader(value, readerProperties, label, true, false);
+    const virtual = createObject(null);
+    virtual.generation = async () => {
+        const result = await apply(rawGeneration, value, []);
+        return requireGeneration(result, label);
+    };
+    if (rawExactReader !== undefined) {
+        virtual.exact = async (path, byteLimit) => {
+            requirePositiveByteLimit(byteLimit, `${label} exact byte limit`);
+            const result = await apply(rawExactReader, value, [path, byteLimit]);
+            return copyFixedUint8ArrayWithinLimit(result, byteLimit, `${label} exact`);
+        };
+    }
+    if (whole !== undefined)
+        virtual.whole = whole;
+    if (virtual.exact === undefined && virtual.whole === undefined) {
+        return freezeObject(captured);
+    }
+    captured.virtual = freezeObject(virtual);
+    return freezeObject(captured);
+}

package/esm/src/platform/adapters/native-file-system-provenance.d.ts

@@ -0,0 +1,6 @@
+import type { FileSystemAdapter } from "./base.js";
+/** Register a directly constructed built-in adapter backed by the host filesystem. */
+export declare function markNativeFileSystemAdapter(adapter: FileSystemAdapter): void;
+/** Return true only for the exact built-in adapter object registered at construction. */
+export declare function isNativeFileSystemAdapter(adapter: FileSystemAdapter): boolean;
+//# sourceMappingURL=native-file-system-provenance.d.ts.map

package/esm/src/platform/adapters/native-file-system-provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-file-system-provenance.d.ts","sourceRoot":"","sources":["../../../../src/src/platform/adapters/native-file-system-provenance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAWnD,sFAAsF;AACtF,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAE5E;AAED,yFAAyF;AACzF,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAMT"}

package/esm/src/platform/adapters/native-file-system-provenance.js

@@ -0,0 +1,15 @@
+const IntrinsicWeakSet = WeakSet;
+const ReflectApply = Reflect.apply;
+const WeakSetPrototypeAdd = IntrinsicWeakSet.prototype.add;
+const WeakSetPrototypeHas = IntrinsicWeakSet.prototype.has;
+// Exact-object provenance only. Wrappers and proxies must not inherit this
+// classification because they may translate paths into a non-native namespace.
+const nativeFileSystemAdapters = new IntrinsicWeakSet();
+/** Register a directly constructed built-in adapter backed by the host filesystem. */
+export function markNativeFileSystemAdapter(adapter) {
+    ReflectApply(WeakSetPrototypeAdd, nativeFileSystemAdapters, [adapter]);
+}
+/** Return true only for the exact built-in adapter object registered at construction. */
+export function isNativeFileSystemAdapter(adapter) {
+    return ReflectApply(WeakSetPrototypeHas, nativeFileSystemAdapters, [adapter]);
+}

package/esm/src/platform/adapters/runtime/deno/filesystem-adapter.d.ts

@@ -0,0 +1,45 @@
+import type { DirEntry, FileInfo, FileSystemAdapter, FileWatcher, WatchOptions } from "../../base.js";
+import { type NodeFileSystemCapabilityOptions } from "../shared/node-filesystem-adapter.js";
+interface DenoCreateFile {
+    write(content: Uint8Array): Promise<number>;
+    close(): void;
+}
+interface DenoCreateRuntime {
+    open(path: string, options: {
+        write: true;
+        createNew: true;
+    }): Promise<DenoCreateFile>;
+}
+interface DenoFileSystemCapabilityOptions extends NodeFileSystemCapabilityOptions {
+    /** Test seam for Deno createNew availability and partial write failures. */
+    readonly denoCreateRuntime?: DenoCreateRuntime | null;
+}
+export declare class DenoFileSystemAdapter implements FileSystemAdapter {
+    constructor(options?: DenoFileSystemCapabilityOptions);
+    readFile(path: string): Promise<string>;
+    readFileBytes(path: string): Promise<Uint8Array>;
+    readFileBytesBounded(path: string, byteLimit: number): Promise<Uint8Array>;
+    readFileBytesWithinLimit(path: string, byteLimit: number): Promise<Uint8Array>;
+    writeFile(path: string, content: string): Promise<void>;
+    writeFileBytes(path: string, content: Uint8Array): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    readDir(path: string): AsyncIterable<DirEntry>;
+    stat(path: string): Promise<FileInfo>;
+    lstat(path: string): Promise<FileInfo>;
+    realPath(path: string): Promise<string>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    remove(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    makeTempDir(prefix: string): Promise<string>;
+    watch(paths: string | string[], options?: WatchOptions): FileWatcher;
+}
+export interface DenoFileSystemAdapter {
+    readFileSnapshotWithinLimit?(path: string, containmentRoot: string, byteLimit: number): Promise<Uint8Array>;
+    createFileBytesExclusive?(path: string, content: Uint8Array): Promise<void>;
+}
+export {};
+//# sourceMappingURL=filesystem-adapter.d.ts.map

package/esm/src/platform/adapters/runtime/deno/filesystem-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-adapter.d.ts","sourceRoot":"","sources":["../../../../../../src/src/platform/adapters/runtime/deno/filesystem-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,QAAQ,EAGR,QAAQ,EACR,iBAAiB,EACjB,WAAW,EACX,YAAY,EACb,MAAM,eAAe,CAAC;AAWvB,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,sCAAsC,CAAC;AAE9C,UAAU,cAAc;IACtB,KAAK,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,KAAK,IAAI,IAAI,CAAC;CACf;AAED,UAAU,iBAAiB;IACzB,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,SAAS,EAAE,IAAI,CAAA;KAAE,GACxC,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5B;AAED,UAAU,+BAAgC,SAAQ,+BAA+B;IAC/E,4EAA4E;IAC5E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACvD;AAoGD,qBAAa,qBAAsB,YAAW,iBAAiB;gBACjD,OAAO,GAAE,+BAAoC;IAuBnD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKvC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAKhD,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAW1E,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAW9E,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvD,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWrC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC;IAY/C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAKrC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAKtC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKvC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtE,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKlD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,WAAW;CAoGrE;AAED,MAAM,WAAW,qBAAqB;IACpC,2BAA2B,CAAC,CAC1B,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CAAC;IACvB,wBAAwB,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7E"}