@struktoai/mirage-node 0.0.7-alpha.2 → 0.0.7-alpha.3

package/dist/vfs/gridfs/gridfs.js

@@ -0,0 +1,144 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { BaseVFS } from '@struktoai/mirage-core/vfs/base';
+import { normalizeKeyPrefix } from '@struktoai/mirage-core/vfs/s3/config';
+import { VFSName } from '@struktoai/mirage-core/types';
+import { GridFSAccessor } from "../../accessor/gridfs.js";
+import { redactConfig } from "./config.js";
+import { PROMPT } from "./prompt.js";
+import { appendByStreamedRewrite } from '@struktoai/mirage-core/core/generic/rewrite';
+import { readdir as gridfsReaddir } from "../../core/gridfs/readdir.js";
+import { read as gridfsRead } from "../../core/gridfs/read.js";
+import { stat as gridfsStat } from "../../core/gridfs/stat.js";
+import { readStream as gridfsStream } from "../../core/gridfs/stream.js";
+import { exists as gridfsExists } from "../../core/gridfs/exists.js";
+import { write as gridfsWrite, writeStream as gridfsWriteStream } from "../../core/gridfs/write.js";
+import { create as gridfsCreate } from "../../core/gridfs/create.js";
+import { mkdir as gridfsMkdir } from "../../core/gridfs/mkdir.js";
+import { unlink as gridfsUnlink } from "../../core/gridfs/unlink.js";
+import { rmdir as gridfsRmdir } from "../../core/gridfs/rmdir.js";
+import { rmR as gridfsRmR } from "../../core/gridfs/rm.js";
+import { rename as gridfsRename } from "../../core/gridfs/rename.js";
+import { copy as gridfsCopy } from "../../core/gridfs/copy.js";
+import { truncate as gridfsTruncate } from "../../core/gridfs/truncate.js";
+import { SCOPE_ERROR } from "../../core/gridfs/constants.js";
+import { tree as gridfsTree } from "../../core/gridfs/readdir.js";
+import { stripSlash } from '@struktoai/mirage-core/utils/slash';
+export class GridFSVFS extends BaseVFS {
+    name = VFSName.GRIDFS;
+    cachesReads = true;
+    supportsSnapshot = true;
+    // byte store: stat() sizes every file from metadata
+    sizesAlwaysKnown = true;
+    // stat and read both stamp str(file_id), so the gate compares like
+    // with like.
+    readRevalidatable = true;
+    prompt = PROMPT;
+    config;
+    accessor;
+    constructor(config) {
+        super();
+        const normalized = normalizeKeyPrefix(config.keyPrefix);
+        const cfg = { ...config };
+        if (normalized !== undefined) {
+            cfg.keyPrefix = normalized;
+        }
+        else {
+            delete cfg.keyPrefix;
+        }
+        this.config = cfg;
+        this.accessor = new GridFSAccessor(this.config);
+    }
+    async close() {
+        await this.accessor.close();
+        await super.close();
+    }
+    readsRanges = true;
+    maxGlobMatches = SCOPE_ERROR;
+    readTree(path) {
+        return gridfsTree(this.accessor, path);
+    }
+    readdir(path) {
+        return gridfsReaddir(this.accessor, path);
+    }
+    read(path, _handed, offset = 0, size = null) {
+        if (offset === 0 && size === null)
+            return gridfsRead(this.accessor, path);
+        return gridfsRead(this.accessor, path, size === null ? { offset } : { offset, size });
+    }
+    stat(path) {
+        return gridfsStat(this.accessor, path);
+    }
+    readStream(path) {
+        return gridfsStream(this.accessor, path);
+    }
+    exists(path) {
+        return gridfsExists(this.accessor, path);
+    }
+    write(path, data) {
+        return gridfsWrite(this.accessor, path, data);
+    }
+    writeStream(path, data, signal) {
+        return gridfsWriteStream(this.accessor, path, data, signal);
+    }
+    append(path, data) {
+        return this.appendStream(path, data);
+    }
+    appendStream(path, data) {
+        return appendByStreamedRewrite((p, remember) => gridfsStream(this.accessor, p, remember), (p, d) => this.writeStream(p, d), (p) => this.stat(p), path, data);
+    }
+    create(path) {
+        return gridfsCreate(this.accessor, path);
+    }
+    mkdir(path, parents = false) {
+        return gridfsMkdir(this.accessor, path, parents);
+    }
+    unlink(path) {
+        return gridfsUnlink(this.accessor, path);
+    }
+    rmdir(path) {
+        return gridfsRmdir(this.accessor, path);
+    }
+    rmR(path) {
+        return gridfsRmR(this.accessor, path);
+    }
+    rename(src, dst) {
+        return gridfsRename(this.accessor, src, dst);
+    }
+    copy(src, dst) {
+        return gridfsCopy(this.accessor, src, dst);
+    }
+    truncate(path, length, noCreate = false) {
+        return gridfsTruncate(this.accessor, path, length, noCreate);
+    }
+    storageLocation() {
+        // The hosts, the database, the bucket and the key prefix pin the files
+        // two mounts would share. The URI's credentials are left out: they name
+        // a login, not a store.
+        const cfg = this.config;
+        const scheme = cfg.uri.indexOf('://');
+        const rest = scheme === -1 ? cfg.uri : cfg.uri.slice(scheme + 3);
+        const hosts = (rest.slice(rest.lastIndexOf('@') + 1).split('/')[0] ?? '').split('?')[0] ?? '';
+        const prefix = stripSlash(cfg.keyPrefix ?? '');
+        const base = `${this.name}:${hosts}/${cfg.database}/${cfg.bucket ?? 'fs'}`;
+        return prefix === '' ? base : `${base}/${prefix}`;
+    }
+    getState() {
+        return Promise.resolve({
+            type: this.name,
+            config: redactConfig(this.config),
+        });
+    }
+}
+//# sourceMappingURL=gridfs.js.map

package/dist/vfs/gridfs/gridfs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gridfs.js","sourceRoot":"","sources":["../../../src/vfs/gridfs/gridfs.ts"],"names":[],"mappings":"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"}

package/dist/vfs/gridfs/prompt.d.ts

@@ -0,0 +1,2 @@
+export declare const PROMPT = "{prefix}\n  Remote MongoDB GridFS bucket. Maps GridFS filenames to virtual paths.\n  IMPORTANT: This is a remote mount. Prefer targeted reads (grep, head) over full scans. Avoid cat on large files without piping to head/tail.\n  find -type f pushes -name/-size filters into the fs.files query server-side, so it is cheap even on large buckets.\n  Supports: ls, cat, head, tail, grep, rg, wc, find, tree, jq, stat.";
+//# sourceMappingURL=prompt.d.ts.map

package/dist/vfs/gridfs/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../../src/vfs/gridfs/prompt.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,MAAM,kaAIkD,CAAA"}

package/dist/vfs/gridfs/prompt.js

@@ -0,0 +1,19 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+export const PROMPT = `{prefix}
+  Remote MongoDB GridFS bucket. Maps GridFS filenames to virtual paths.
+  IMPORTANT: This is a remote mount. Prefer targeted reads (grep, head) over full scans. Avoid cat on large files without piping to head/tail.
+  find -type f pushes -name/-size filters into the fs.files query server-side, so it is cheap even on large buckets.
+  Supports: ls, cat, head, tail, grep, rg, wc, find, tree, jq, stat.`;
+//# sourceMappingURL=prompt.js.map

package/dist/vfs/gridfs/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../../src/vfs/gridfs/prompt.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,uEAAuE;AAEvE,MAAM,CAAC,MAAM,MAAM,GAAG;;;;qEAI+C,CAAA"}

package/dist/vfs/hf_buckets/config.d.ts

@@ -0,0 +1,59 @@
+import { z } from '@struktoai/mirage-core/vfs/secrets';
+import type { ConfigOf, RedactedConfig } from '@struktoai/mirage-core/vfs/secrets';
+export declare const HF_ENDPOINT = "https://huggingface.co";
+export declare const HF_TIMEOUT_MS = 30000;
+export declare function assertHfRepoId(value: string, field: string): string;
+/**
+ * Either spelling the Hub itself accepts for a repository.
+ *
+ * A repo id is `namespace/name` or a bare `name`, and the second resolves
+ * against whoever the token belongs to. That is not a convenience:
+ * `hf repo create widget` followed by `hf download widget` is what the real
+ * CLI produces, and refusing the bare form made mirage reject an id the Hub
+ * had just minted. What is refused is a shape the Hub has no reading for: an
+ * empty segment, or more than one slash.
+ *
+ * A BUCKET keeps the stricter rule (`assertHfRepoId`): the Buckets API has no
+ * namespace-from-token step, so a bare bucket name addresses nothing.
+ */
+export declare function assertHfRepoRef(value: string, field: string): string;
+export interface HfBucketsConfig {
+    bucket: string;
+    token?: string;
+    endpoint?: string;
+    timeoutMs?: number;
+    keyPrefix?: string;
+}
+declare const HfBucketsConfigSchema: z.ZodObject<{
+    bucket: z.ZodString;
+    token: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    keyPrefix: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type HfBucketsConfigRedacted = RedactedConfig<ConfigOf<typeof HfBucketsConfigSchema>, 'token'>;
+export declare function redactHfBucketsConfig(config: HfBucketsConfig): HfBucketsConfigRedacted;
+export declare function normalizeHfBucketsConfig(input: Record<string, unknown>): HfBucketsConfig;
+export interface HfRepoConfig {
+    repoId: string;
+    token?: string;
+    endpoint?: string;
+    timeoutMs?: number;
+    keyPrefix?: string;
+    revision?: string;
+    expandCommits?: boolean;
+}
+declare const HfRepoConfigSchema: z.ZodObject<{
+    repoId: z.ZodString;
+    token: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    keyPrefix: z.ZodOptional<z.ZodString>;
+    revision: z.ZodOptional<z.ZodString>;
+    expandCommits: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type HfRepoConfigRedacted = RedactedConfig<ConfigOf<typeof HfRepoConfigSchema>, 'token'>;
+export declare function redactHfRepoConfig(config: HfRepoConfig): HfRepoConfigRedacted;
+export declare function normalizeHfRepoConfig(input: Record<string, unknown>): HfRepoConfig;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/vfs/hf_buckets/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/vfs/hf_buckets/config.ts"],"names":[],"mappings":"AAcA,OAAO,EAIL,CAAC,EACF,MAAM,oCAAoC,CAAA;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAA;AAGlF,eAAO,MAAM,WAAW,2BAA2B,CAAA;AAGnD,eAAO,MAAM,aAAa,QAAS,CAAA;AAEnC,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMnE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMpE;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAUD,QAAA,MAAM,qBAAqB;;;;;;iBAMzB,CAAA;AAIF,MAAM,MAAM,uBAAuB,GAAG,cAAc,CAClD,QAAQ,CAAC,OAAO,qBAAqB,CAAC,EACtC,OAAO,CACR,CAAA;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,uBAAuB,CAKtF;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,CAIxF;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IASjB,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,QAAA,MAAM,kBAAkB;;;;;;;;iBAQtB,CAAA;AAIF,MAAM,MAAM,oBAAoB,GAAG,cAAc,CAAC,QAAQ,CAAC,OAAO,kBAAkB,CAAC,EAAE,OAAO,CAAC,CAAA;AAE/F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,oBAAoB,CAK7E;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,CAIlF"}

package/dist/vfs/hf_buckets/config.js

@@ -0,0 +1,91 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { parseConfigWithSchema, redactConfigWithSchema, secretStr, z, } from '@struktoai/mirage-core/vfs/secrets';
+import { secondsToMs } from '@struktoai/mirage-core/utils/normalize';
+export const HF_ENDPOINT = 'https://huggingface.co';
+// python's `timeout: int = 30`, in the milliseconds this side stores.
+export const HF_TIMEOUT_MS = 30_000;
+export function assertHfRepoId(value, field) {
+    const parts = value.split('/');
+    if (parts.length !== 2 || parts[0] === '' || parts[1] === '') {
+        throw new Error(`${field} must be in 'namespace/name' form; got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+/**
+ * Either spelling the Hub itself accepts for a repository.
+ *
+ * A repo id is `namespace/name` or a bare `name`, and the second resolves
+ * against whoever the token belongs to. That is not a convenience:
+ * `hf repo create widget` followed by `hf download widget` is what the real
+ * CLI produces, and refusing the bare form made mirage reject an id the Hub
+ * had just minted. What is refused is a shape the Hub has no reading for: an
+ * empty segment, or more than one slash.
+ *
+ * A BUCKET keeps the stricter rule (`assertHfRepoId`): the Buckets API has no
+ * namespace-from-token step, so a bare bucket name addresses nothing.
+ */
+export function assertHfRepoRef(value, field) {
+    const parts = value.split('/');
+    if (parts.length > 2 || parts.some((p) => p === '')) {
+        throw new Error(`${field} must be 'name' or 'namespace/name'; got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+// Python states the timeout in seconds; the redactor fills `endpoint`
+// from HF_ENDPOINT, so it is optional on the wire exactly as python's
+// default makes it.
+const HF_NORMALIZER = {
+    rename: { timeout: 'timeoutMs' },
+    transform: { timeout: secondsToMs },
+};
+const HfBucketsConfigSchema = z.object({
+    bucket: z.string(),
+    token: secretStr().optional(),
+    endpoint: z.string().optional(),
+    timeoutMs: z.number().optional(),
+    keyPrefix: z.string().optional(),
+});
+export function redactHfBucketsConfig(config) {
+    return redactConfigWithSchema(HfBucketsConfigSchema, {
+        ...config,
+        endpoint: config.endpoint ?? HF_ENDPOINT,
+    });
+}
+export function normalizeHfBucketsConfig(input) {
+    const config = parseConfigWithSchema(HfBucketsConfigSchema, input, HF_NORMALIZER);
+    assertHfRepoId(config.bucket, 'bucket');
+    return config;
+}
+const HfRepoConfigSchema = z.object({
+    repoId: z.string(),
+    token: secretStr().optional(),
+    endpoint: z.string().optional(),
+    timeoutMs: z.number().optional(),
+    keyPrefix: z.string().optional(),
+    revision: z.string().optional(),
+    expandCommits: z.boolean().optional(),
+});
+export function redactHfRepoConfig(config) {
+    return redactConfigWithSchema(HfRepoConfigSchema, {
+        ...config,
+        endpoint: config.endpoint ?? HF_ENDPOINT,
+    });
+}
+export function normalizeHfRepoConfig(input) {
+    const config = parseConfigWithSchema(HfRepoConfigSchema, input, HF_NORMALIZER);
+    assertHfRepoRef(config.repoId, 'repo_id');
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/vfs/hf_buckets/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/vfs/hf_buckets/config.ts"],"names":[],"mappings":"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"}

package/dist/vfs/hf_buckets/hf_buckets.d.ts

@@ -0,0 +1,36 @@
+import { BaseVFS } from '@struktoai/mirage-core/vfs/base';
+import { HfBucketsAccessor } from '../../accessor/hf_buckets.ts';
+import { type HfBucketsConfig, type HfBucketsConfigRedacted } from './config.ts';
+import type { PathSpec, FileStat } from '@struktoai/mirage-core/types';
+import type { Handed } from '@struktoai/mirage-core/vfs/types';
+export interface HfBucketsVFSState {
+    type: string;
+    config: HfBucketsConfigRedacted;
+}
+export declare class HfBucketsVFS extends BaseVFS {
+    readonly name: string;
+    readonly prompt: string;
+    readonly cachesReads: boolean;
+    readonly sizesAlwaysKnown: boolean;
+    readonly supportsSnapshot: boolean;
+    readonly readRevalidatable: boolean;
+    readonly config: HfBucketsConfig;
+    readonly accessor: HfBucketsAccessor;
+    constructor(config: HfBucketsConfig);
+    readonly readsRanges: boolean;
+    readonly maxGlobMatches: number;
+    readTree(path: PathSpec): Promise<Map<string, FileStat> | null>;
+    readdir(path: PathSpec): Promise<FileStat[]>;
+    read(path: PathSpec, _handed?: Handed, offset?: number, size?: number | null): Promise<Uint8Array>;
+    stat(path: PathSpec): Promise<FileStat>;
+    readStream(path: PathSpec): AsyncIterable<Uint8Array>;
+    exists(path: PathSpec): Promise<boolean>;
+    write(path: PathSpec, data: Uint8Array): Promise<FileStat | null>;
+    create(path: PathSpec): Promise<FileStat | null>;
+    mkdir(path: PathSpec, parents?: boolean): Promise<void>;
+    unlink(path: PathSpec): Promise<void>;
+    rmR(path: PathSpec): Promise<void>;
+    storageLocation(): string;
+    getState(): Promise<HfBucketsVFSState>;
+}
+//# sourceMappingURL=hf_buckets.d.ts.map

package/dist/vfs/hf_buckets/hf_buckets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hf_buckets.d.ts","sourceRoot":"","sources":["../../../src/vfs/hf_buckets/hf_buckets.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAA;AAGzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAE7B,MAAM,aAAa,CAAA;AAEpB,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AACtE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAA;AAe9D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,uBAAuB,CAAA;CAChC;AAED,qBAAa,YAAa,SAAQ,OAAO;IACvC,SAAkB,IAAI,EAAE,MAAM,CAAqB;IACnD,SAAkB,MAAM,EAAE,MAAM,CAAS;IACzC,SAAkB,WAAW,EAAE,OAAO,CAAO;IAI7C,SAAkB,gBAAgB,EAAE,OAAO,CAAO;IAClD,SAAkB,gBAAgB,EAAE,OAAO,CAAO;IAIlD,SAAkB,iBAAiB,EAAE,OAAO,CAAO;IACnD,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;IAChC,SAAkB,QAAQ,EAAE,iBAAiB,CAAA;gBAEjC,MAAM,EAAE,eAAe;IAcnC,SAAkB,WAAW,EAAE,OAAO,CAAO;IAE7C,SAAkB,cAAc,EAAE,MAAM,CAAc;IAE7C,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,IAAI,CAAC;IAI/D,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAI5C,IAAI,CACX,IAAI,EAAE,QAAQ,EACd,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,SAAI,EACV,IAAI,GAAE,MAAM,GAAG,IAAW,GACzB,OAAO,CAAC,UAAU,CAAC;IAKb,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAIvC,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,aAAa,CAAC,UAAU,CAAC;IAIrD,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxC,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAIjE,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAIhD,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,eAAe,IAAI,MAAM;IASzB,QAAQ,IAAI,OAAO,CAAC,iBAAiB,CAAC;CAMhD"}

package/dist/vfs/hf_buckets/hf_buckets.js

@@ -0,0 +1,114 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { BaseVFS } from '@struktoai/mirage-core/vfs/base';
+import { normalizeKeyPrefix } from '@struktoai/mirage-core/vfs/s3/config';
+import { VFSName } from '@struktoai/mirage-core/types';
+import { HfBucketsAccessor } from "../../accessor/hf_buckets.js";
+import { assertHfRepoId, HF_ENDPOINT, redactHfBucketsConfig, } from "./config.js";
+import { PROMPT } from "./prompt.js";
+import { readdir as hfReaddir } from "../../core/hf_buckets/readdir.js";
+import { read as hfRead } from "../../core/hf_buckets/read.js";
+import { stat as hfStat } from "../../core/hf_buckets/stat.js";
+import { readStream as hfStream } from "../../core/hf_buckets/stream.js";
+import { exists as hfExists } from "../../core/hf_buckets/exists.js";
+import { write as hfWrite } from "../../core/hf_buckets/write.js";
+import { create as hfCreate } from "../../core/hf_buckets/create.js";
+import { mkdir as hfMkdir } from "../../core/hf_buckets/mkdir.js";
+import { unlink as hfUnlink } from "../../core/hf_buckets/unlink.js";
+import { rmR as hfRmR } from "../../core/hf_buckets/rm.js";
+import { SCOPE_ERROR } from "../../core/hf_buckets/constants.js";
+import { tree as hfTree } from "../../core/hf_buckets/readdir.js";
+import { rstripSlash, stripSlash } from '@struktoai/mirage-core/utils/slash';
+export class HfBucketsVFS extends BaseVFS {
+    name = VFSName.HF_BUCKETS;
+    prompt = PROMPT;
+    cachesReads = true;
+    // The Hub tree API reports each file's exact byte size (the LFS
+    // object size for LFS files); readdir backfills any lister-omitted
+    // size with one stat.
+    sizesAlwaysKnown = true;
+    supportsSnapshot = true;
+    // stat stamps the paths-info xet hash and a read stamps its download's
+    // strong ETag, which is that same hash, so a `fresh` probe compares like
+    // with like.
+    readRevalidatable = true;
+    config;
+    accessor;
+    constructor(config) {
+        super();
+        assertHfRepoId(config.bucket, 'bucket');
+        const normalized = normalizeKeyPrefix(config.keyPrefix);
+        const cfg = { ...config };
+        if (normalized !== undefined) {
+            cfg.keyPrefix = normalized;
+        }
+        else {
+            delete cfg.keyPrefix;
+        }
+        this.config = cfg;
+        this.accessor = new HfBucketsAccessor(this.config);
+    }
+    readsRanges = true;
+    maxGlobMatches = SCOPE_ERROR;
+    readTree(path) {
+        return hfTree(this.accessor, path);
+    }
+    readdir(path) {
+        return hfReaddir(this.accessor, path);
+    }
+    read(path, _handed, offset = 0, size = null) {
+        if (offset === 0 && size === null)
+            return hfRead(this.accessor, path);
+        return hfRead(this.accessor, path, size === null ? { offset } : { offset, size });
+    }
+    stat(path) {
+        return hfStat(this.accessor, path);
+    }
+    readStream(path) {
+        return hfStream(this.accessor, path);
+    }
+    exists(path) {
+        return hfExists(this.accessor, path);
+    }
+    write(path, data) {
+        return hfWrite(this.accessor, path, data);
+    }
+    create(path) {
+        return hfCreate(this.accessor, path);
+    }
+    mkdir(path, parents = false) {
+        return hfMkdir(this.accessor, path, parents);
+    }
+    unlink(path) {
+        return hfUnlink(this.accessor, path);
+    }
+    rmR(path) {
+        return hfRmR(this.accessor, path);
+    }
+    storageLocation() {
+        // The endpoint, the bucket and the key prefix pin the objects two mounts
+        // would share.
+        const cfg = this.config;
+        const prefix = stripSlash(cfg.keyPrefix ?? '');
+        const base = `${this.name}:${rstripSlash(cfg.endpoint ?? HF_ENDPOINT)}:${cfg.bucket}`;
+        return prefix === '' ? base : `${base}/${prefix}`;
+    }
+    getState() {
+        return Promise.resolve({
+            type: this.name,
+            config: redactHfBucketsConfig(this.config),
+        });
+    }
+}
+//# sourceMappingURL=hf_buckets.js.map

package/dist/vfs/hf_buckets/hf_buckets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hf_buckets.js","sourceRoot":"","sources":["../../../src/vfs/hf_buckets/hf_buckets.ts"],"names":[],"mappings":"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"}

package/dist/vfs/hf_buckets/prompt.d.ts

@@ -0,0 +1,2 @@
+export declare const PROMPT = "{prefix}\n  Remote Hugging Face Bucket (read-only). Maps bucket object keys to virtual paths.\n  IMPORTANT: This is a remote mount. Prefer targeted reads (grep, head) over full scans.\n  Supports: ls, cat, head, tail, grep, rg, wc, find, tree, jq, stat.";
+//# sourceMappingURL=prompt.d.ts.map

package/dist/vfs/hf_buckets/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../../src/vfs/hf_buckets/prompt.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,MAAM,kQAGkD,CAAA"}

package/dist/vfs/hf_buckets/prompt.js

@@ -0,0 +1,18 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+export const PROMPT = `{prefix}
+  Remote Hugging Face Bucket (read-only). Maps bucket object keys to virtual paths.
+  IMPORTANT: This is a remote mount. Prefer targeted reads (grep, head) over full scans.
+  Supports: ls, cat, head, tail, grep, rg, wc, find, tree, jq, stat.`;
+//# sourceMappingURL=prompt.js.map

package/dist/vfs/hf_buckets/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../../src/vfs/hf_buckets/prompt.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,uEAAuE;AAEvE,MAAM,CAAC,MAAM,MAAM,GAAG;;;qEAG+C,CAAA"}

package/dist/vfs/hf_datasets/config.d.ts

@@ -0,0 +1,6 @@
+import { type HfRepoConfig, type HfRepoConfigRedacted, normalizeHfRepoConfig, redactHfRepoConfig } from '../hf_buckets/config.ts';
+export type HfDatasetsConfig = HfRepoConfig;
+export type HfDatasetsConfigRedacted = HfRepoConfigRedacted;
+export declare const normalizeHfDatasetsConfig: typeof normalizeHfRepoConfig;
+export declare const redactHfDatasetsConfig: typeof redactHfRepoConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/vfs/hf_datasets/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/vfs/hf_datasets/config.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,qBAAqB,EACrB,kBAAkB,EACnB,MAAM,yBAAyB,CAAA;AAEhC,MAAM,MAAM,gBAAgB,GAAG,YAAY,CAAA;AAC3C,MAAM,MAAM,wBAAwB,GAAG,oBAAoB,CAAA;AAE3D,eAAO,MAAM,yBAAyB,8BAAwB,CAAA;AAC9D,eAAO,MAAM,sBAAsB,2BAAqB,CAAA"}

package/dist/vfs/hf_datasets/config.js

@@ -0,0 +1,17 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { normalizeHfRepoConfig, redactHfRepoConfig, } from "../hf_buckets/config.js";
+export const normalizeHfDatasetsConfig = normalizeHfRepoConfig;
+export const redactHfDatasetsConfig = redactHfRepoConfig;
+//# sourceMappingURL=config.js.map

package/dist/vfs/hf_datasets/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/vfs/hf_datasets/config.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,uEAAuE;AAEvE,OAAO,EAGL,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,yBAAyB,CAAA;AAKhC,MAAM,CAAC,MAAM,yBAAyB,GAAG,qBAAqB,CAAA;AAC9D,MAAM,CAAC,MAAM,sBAAsB,GAAG,kBAAkB,CAAA"}

package/dist/vfs/hf_datasets/hf_datasets.d.ts

@@ -0,0 +1,16 @@
+import { HfDatasetsAccessor } from '../../accessor/hf_hub.ts';
+import { HfHubVFS } from '../hf_hub/base.ts';
+import { type HfDatasetsConfig, type HfDatasetsConfigRedacted } from './config.ts';
+export interface HfDatasetsVFSState {
+    type: string;
+    config: HfDatasetsConfigRedacted;
+}
+export declare class HfDatasetsVFS extends HfHubVFS {
+    readonly name: string;
+    readonly prompt: string;
+    readonly config: HfDatasetsConfig;
+    readonly accessor: HfDatasetsAccessor;
+    constructor(config: HfDatasetsConfig);
+    getState(): Promise<HfDatasetsVFSState>;
+}
+//# sourceMappingURL=hf_datasets.d.ts.map

package/dist/vfs/hf_datasets/hf_datasets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hf_datasets.d.ts","sourceRoot":"","sources":["../../../src/vfs/hf_datasets/hf_datasets.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAa,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAExE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAE9B,MAAM,aAAa,CAAA;AAGpB,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,wBAAwB,CAAA;CACjC;AAED,qBAAa,aAAc,SAAQ,QAAQ;IACzC,SAAkB,IAAI,EAAE,MAAM,CAAsB;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAS;IAChC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAA;gBAEzB,MAAM,EAAE,gBAAgB;IAcpC,QAAQ,IAAI,OAAO,CAAC,kBAAkB,CAAC;CAMxC"}