@struktoai/mirage-node 0.0.5-alpha.1 → 0.0.6

package/dist/core/hf_hub/repo.d.ts

@@ -0,0 +1,40 @@
+import type { HfHubAccessor } from '../../accessor/hf_hub.ts';
+/** The repository's branches, tags and conversion refs. */
+export declare function fetchRefs(accessor: HfHubAccessor): Promise<Record<string, unknown>>;
+/**
+ * The commit the mount's revision currently points at.
+ *
+ * Read from the repo object rather than from /refs because the repo object
+ * answers it for a tag and a commit-pinned mount too, where /refs only
+ * enumerates branches.
+ *
+ * Asked of the revision endpoint, not the bare one: the bare object's `sha`
+ * is the default branch's whatever revision was requested, and the cache is
+ * keyed by this sha. Reading the wrong one files a `--revision dev` download
+ * under main's snapshot and points refs/dev at it, so a later main download
+ * finds the snapshot already there and serves dev's bytes.
+ */
+export declare function headCommit(accessor: HfHubAccessor): Promise<string>;
+/** What the Hub says is missing when a listing came back empty. */
+export declare enum Absence {
+    PRESENT = "present",
+    REPO = "repo",
+    REVISION = "revision"
+}
+/** The endpoint whose url upstream names in its not-found messages. */
+export declare function revisionUrl(accessor: HfHubAccessor): string;
+/**
+ * Why a listing came back empty, asked of the Hub directly.
+ *
+ * `fetchTree` folds 401/403/404 into an empty listing on purpose: a mount's
+ * readdir over a repository it cannot see has to render an empty directory
+ * rather than raise. A CLI verb wants the opposite, so it asks this on the
+ * failure path only, which costs one request and only when something already
+ * went wrong.
+ *
+ * The status cannot answer it. A missing repository, a missing revision and a
+ * missing file are all 404, and only the Hub's `X-Error-Code` header tells
+ * them apart; probed against the live Hub, not inferred.
+ */
+export declare function classifyAbsence(accessor: HfHubAccessor): Promise<Absence>;
+//# sourceMappingURL=repo.d.ts.map

package/dist/core/hf_hub/repo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../../src/core/hf_hub/repo.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAG7D,2DAA2D;AAC3D,wBAAsB,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAIzF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAKzE;AAED,mEAAmE;AACnE,oBAAY,OAAO;IACjB,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,QAAQ,aAAa;CACtB;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAO3D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAW/E"}

package/dist/core/hf_hub/repo.js

@@ -0,0 +1,80 @@
+// ========= 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 { apiUrl, HfHubError, hubGet, revSegment } from "./client.js";
+/** The repository's branches, tags and conversion refs. */
+export async function fetchRefs(accessor) {
+    const url = apiUrl(accessor.endpoint, accessor.repoType, accessor.repoId, '/refs');
+    const data = await hubGet(accessor.token, url);
+    return typeof data === 'object' && data !== null ? data : {};
+}
+/**
+ * The commit the mount's revision currently points at.
+ *
+ * Read from the repo object rather than from /refs because the repo object
+ * answers it for a tag and a commit-pinned mount too, where /refs only
+ * enumerates branches.
+ *
+ * Asked of the revision endpoint, not the bare one: the bare object's `sha`
+ * is the default branch's whatever revision was requested, and the cache is
+ * keyed by this sha. Reading the wrong one files a `--revision dev` download
+ * under main's snapshot and points refs/dev at it, so a later main download
+ * finds the snapshot already there and serves dev's bytes.
+ */
+export async function headCommit(accessor) {
+    const data = await hubGet(accessor.token, revisionUrl(accessor));
+    if (data === null || typeof data !== 'object' || Array.isArray(data))
+        return '';
+    const sha = data.sha;
+    return typeof sha === 'string' ? sha : '';
+}
+/** What the Hub says is missing when a listing came back empty. */
+export var Absence;
+(function (Absence) {
+    Absence["PRESENT"] = "present";
+    Absence["REPO"] = "repo";
+    Absence["REVISION"] = "revision";
+})(Absence || (Absence = {}));
+/** The endpoint whose url upstream names in its not-found messages. */
+export function revisionUrl(accessor) {
+    return apiUrl(accessor.endpoint, accessor.repoType, accessor.repoId, `/revision/${revSegment(accessor.revision)}`);
+}
+/**
+ * Why a listing came back empty, asked of the Hub directly.
+ *
+ * `fetchTree` folds 401/403/404 into an empty listing on purpose: a mount's
+ * readdir over a repository it cannot see has to render an empty directory
+ * rather than raise. A CLI verb wants the opposite, so it asks this on the
+ * failure path only, which costs one request and only when something already
+ * went wrong.
+ *
+ * The status cannot answer it. A missing repository, a missing revision and a
+ * missing file are all 404, and only the Hub's `X-Error-Code` header tells
+ * them apart; probed against the live Hub, not inferred.
+ */
+export async function classifyAbsence(accessor) {
+    try {
+        await hubGet(accessor.token, revisionUrl(accessor));
+    }
+    catch (err) {
+        if (err instanceof HfHubError) {
+            if (err.errorCode === 'RepoNotFound')
+                return Absence.REPO;
+            if (err.errorCode === 'RevisionNotFound')
+                return Absence.REVISION;
+        }
+        throw err;
+    }
+    return Absence.PRESENT;
+}
+//# sourceMappingURL=repo.js.map

package/dist/core/hf_hub/repo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo.js","sourceRoot":"","sources":["../../../src/core/hf_hub/repo.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;AAGvE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAEpE,2DAA2D;AAC3D,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,QAAuB;IACrD,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClF,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;IAC9C,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,CAAE,IAAgC,CAAC,CAAC,CAAC,EAAE,CAAA;AAC3F,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAuB;IACtD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAA;IAChE,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAA;IAC/E,MAAM,GAAG,GAAI,IAAgC,CAAC,GAAG,CAAA;IACjD,OAAO,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;AAC3C,CAAC;AAED,mEAAmE;AACnE,MAAM,CAAN,IAAY,OAIX;AAJD,WAAY,OAAO;IACjB,8BAAmB,CAAA;IACnB,wBAAa,CAAA;IACb,gCAAqB,CAAA;AACvB,CAAC,EAJW,OAAO,KAAP,OAAO,QAIlB;AAED,uEAAuE;AACvE,MAAM,UAAU,WAAW,CAAC,QAAuB;IACjD,OAAO,MAAM,CACX,QAAQ,CAAC,QAAQ,EACjB,QAAQ,CAAC,QAAQ,EACjB,QAAQ,CAAC,MAAM,EACf,aAAa,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAC7C,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAuB;IAC3D,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAA;IACrD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,UAAU,EAAE,CAAC;YAC9B,IAAI,GAAG,CAAC,SAAS,KAAK,cAAc;gBAAE,OAAO,OAAO,CAAC,IAAI,CAAA;YACzD,IAAI,GAAG,CAAC,SAAS,KAAK,kBAAkB;gBAAE,OAAO,OAAO,CAAC,QAAQ,CAAA;QACnE,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAA;AACxB,CAAC"}

package/dist/core/hf_hub/stat.d.ts

@@ -0,0 +1,6 @@
+import type { IndexCacheStore } from '@struktoai/mirage-core/cache/index/store';
+import { FileStat } from '@struktoai/mirage-core/types';
+import type { PathSpec } from '@struktoai/mirage-core/types';
+import type { HfHubAccessor } from '../../accessor/hf_hub.ts';
+export declare function stat(accessor: HfHubAccessor, pathSpec: PathSpec, index?: IndexCacheStore): Promise<FileStat>;
+//# sourceMappingURL=stat.d.ts.map

package/dist/core/hf_hub/stat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stat.d.ts","sourceRoot":"","sources":["../../../src/core/hf_hub/stat.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAA;AAC/E,OAAO,EAAE,QAAQ,EAAY,MAAM,8BAA8B,CAAA;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAI5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAoC7D,wBAAsB,IAAI,CACxB,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,QAAQ,EAClB,KAAK,CAAC,EAAE,eAAe,GACtB,OAAO,CAAC,QAAQ,CAAC,CAWnB"}

package/dist/core/hf_hub/stat.js

@@ -0,0 +1,66 @@
+// ========= 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 { FileStat, FileType } from '@struktoai/mirage-core/types';
+import { enoent } from '@struktoai/mirage-core/utils/errors';
+import { contentTypeForPath } from '@struktoai/mirage-core/utils/filetype';
+import { mountPrefixOf } from '@struktoai/mirage-core/utils/key_prefix';
+import { dirStatEntry, keyOf, lookup } from "./lookup.js";
+/**
+ * Render one tree row as a FileStat.
+ *
+ * Size is the row's, which is the Hub's *content* length even for an LFS
+ * file; the 135-byte pointer never reaches here. Reporting the pointer would
+ * make `wc -c` and `ls -l` lie and risk truncated copies over FUSE.
+ *
+ * `modified` is null unless the mount asked for commit expansion: a Hub file's
+ * only mtime is the commit that last touched it, and stamping the
+ * repository's own lastModified onto every file would be a confident lie about
+ * files that commit never touched.
+ */
+function statOf(entry) {
+    const modified = entry.remoteTime === '' ? null : entry.remoteTime;
+    if (entry.resourceType === 'folder') {
+        return new FileStat({ name: entry.name, type: FileType.DIRECTORY, modified });
+    }
+    return new FileStat({
+        name: entry.name,
+        size: entry.size ?? null,
+        modified,
+        // A file's FileType *is* its content type here; there is no FILE member,
+        // so the extension decides, exactly as every other backend spells it.
+        type: FileType.FILE,
+        content: contentTypeForPath(entry.name),
+        // git is content-addressed, so the object id is the strongest fingerprint
+        // any backend here has: identical bytes carry an identical oid, and a
+        // rewrite that changed nothing correctly reports nothing.
+        fingerprint: entry.id,
+        extra: { ...entry.extra },
+    });
+}
+export async function stat(accessor, pathSpec, index) {
+    const prefix = mountPrefixOf(pathSpec.virtual, pathSpec.resourcePath);
+    const rel = pathSpec.mountPath.replace(/^\/+|\/+$/g, '');
+    if (rel === '')
+        return new FileStat({ name: '/', type: FileType.DIRECTORY });
+    const key = keyOf(prefix, rel);
+    const found = await lookup(accessor, index, prefix, key);
+    if (found.entry !== null)
+        return statOf(found.entry);
+    // A directory the tree implies but has no row of its own for still exists,
+    // which is what a listing at the key proves.
+    if (found.children !== null)
+        return statOf(dirStatEntry(key));
+    throw enoent(pathSpec.virtual);
+}
+//# sourceMappingURL=stat.js.map

package/dist/core/hf_hub/stat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stat.js","sourceRoot":"","sources":["../../../src/core/hf_hub/stat.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;AAIvE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAEjE,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAA;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAA;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAA;AAEvE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzD;;;;;;;;;;;GAWG;AACH,SAAS,MAAM,CAAC,KAAiB;IAC/B,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAA;IAClE,IAAI,KAAK,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,IAAI,QAAQ,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAA;IAC/E,CAAC;IACD,OAAO,IAAI,QAAQ,CAAC;QAClB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI;QACxB,QAAQ;QACR,yEAAyE;QACzE,sEAAsE;QACtE,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,OAAO,EAAE,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC;QACvC,0EAA0E;QAC1E,sEAAsE;QACtE,0DAA0D;QAC1D,WAAW,EAAE,KAAK,CAAC,EAAE;QACrB,KAAK,EAAE,EAAE,GAAG,KAAK,CAAC,KAAK,EAAE;KAC1B,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,QAAuB,EACvB,QAAkB,EAClB,KAAuB;IAEvB,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAA;IACrE,MAAM,GAAG,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAA;IACxD,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,IAAI,QAAQ,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAA;IAC5E,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC9B,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,CAAA;IACxD,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IACpD,2EAA2E;IAC3E,6CAA6C;IAC7C,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAA;IAC7D,MAAM,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;AAChC,CAAC"}

package/dist/core/hf_hub/stream.d.ts

@@ -0,0 +1,7 @@
+import type { IndexCacheStore } from '@struktoai/mirage-core/cache/index/store';
+import type { PathSpec } from '@struktoai/mirage-core/types';
+import type { HfHubAccessor } from '../../accessor/hf_hub.ts';
+/** Read a byte range, in the resource API's end-exclusive spelling. */
+export declare function rangeRead(accessor: HfHubAccessor, path: PathSpec, start: number, end: number): Promise<Uint8Array>;
+export declare function stream(accessor: HfHubAccessor, path: PathSpec, index?: IndexCacheStore): AsyncIterable<Uint8Array>;
+//# sourceMappingURL=stream.d.ts.map

package/dist/core/hf_hub/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../../src/core/hf_hub/stream.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAA;AAE/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAI7D,uEAAuE;AACvE,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,UAAU,CAAC,CAErB;AAED,wBAAuB,MAAM,CAC3B,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,QAAQ,EACd,KAAK,CAAC,EAAE,eAAe,GACtB,aAAa,CAAC,UAAU,CAAC,CAe3B"}

package/dist/core/hf_hub/stream.js

@@ -0,0 +1,32 @@
+// ========= 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 { recordStream } from '@struktoai/mirage-core/observe/context';
+import { hubStream, resolveUrl } from "./client.js";
+import { read, resolveEntry } from "./read.js";
+/** Read a byte range, in the resource API's end-exclusive spelling. */
+export async function rangeRead(accessor, path, start, end) {
+    return read(accessor, path, undefined, { offset: start, size: end - start });
+}
+export async function* stream(accessor, path, index) {
+    await resolveEntry(accessor, path, index);
+    const raw = path.mountPath;
+    const url = resolveUrl(accessor.endpoint, accessor.repoType, accessor.repoId, accessor.revision, accessor.repoPath(raw));
+    const rec = recordStream('read', raw, accessor.resourceName);
+    for await (const chunk of hubStream(accessor.token, url)) {
+        if (rec !== null)
+            rec.bytes += chunk.length;
+        yield chunk;
+    }
+}
+//# sourceMappingURL=stream.js.map

package/dist/core/hf_hub/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../../src/core/hf_hub/stream.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;AAGvE,OAAO,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAA;AAGrE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAE9C,uEAAuE;AACvE,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAuB,EACvB,IAAc,EACd,KAAa,EACb,GAAW;IAEX,OAAO,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,GAAG,KAAK,EAAE,CAAC,CAAA;AAC9E,CAAC;AAED,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,MAAM,CAC3B,QAAuB,EACvB,IAAc,EACd,KAAuB;IAEvB,MAAM,YAAY,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAA;IAC1B,MAAM,GAAG,GAAG,UAAU,CACpB,QAAQ,CAAC,QAAQ,EACjB,QAAQ,CAAC,QAAQ,EACjB,QAAQ,CAAC,MAAM,EACf,QAAQ,CAAC,QAAQ,EACjB,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CACvB,CAAA;IACD,MAAM,GAAG,GAAG,YAAY,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAA;IAC5D,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC;QACzD,IAAI,GAAG,KAAK,IAAI;YAAE,GAAG,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,CAAA;QAC3C,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC"}

package/dist/core/hf_hub/tree.d.ts

@@ -0,0 +1,105 @@
+import { IndexEntry } from '@struktoai/mirage-core/cache/index/config';
+import type { IndexCacheStore } from '@struktoai/mirage-core/cache/index/store';
+import type { HfHubAccessor, RowTables } from '../../accessor/hf_hub.ts';
+import { HfHubError } from './client.ts';
+import type { TreeEntry } from './tree_entry.ts';
+/** Turn one tree row into a TreeEntry. */
+export declare function parseEntry(item: Record<string, unknown>): TreeEntry;
+/**
+ * The next page's URL, read out of the Link header.
+ *
+ * The Hub pages the tree with an opaque cursor rather than a page number, so
+ * the only way to ask for page two is to follow the URL it handed back.
+ */
+export declare function nextCursor(headers: Record<string, string>): string;
+/** Query for one tree page. */
+export declare function pageParams(expand: boolean): Record<string, string>;
+/** The tree endpoint for the mount's revision and key prefix. */
+export declare function treeUrl(accessor: HfHubAccessor): string;
+/** Fold one page of tree rows into the mount's listing. */
+export declare function collect(rows: unknown, prefix: string, into: Map<string, TreeEntry>): void;
+/** Follow the cursor from one page to the last, folding as it goes. */
+/**
+ * The refusal for a listing the page ceiling cut short.
+ *
+ * Thrown rather than returned because this listing is not a cache in front
+ * of the Hub, it is seeded as the mount's whole index: a partial one reads
+ * as a complete one, so every file past the ceiling becomes a confident
+ * false absence and `hf download` silently omits it. An error the caller
+ * can see is the lesser failure.
+ */
+export declare function truncated(repoId: string): HfHubError;
+export declare function walkPages(accessor: HfHubAccessor, url: string, params: Record<string, string> | undefined, into: Map<string, TreeEntry>, limit?: number): Promise<string>;
+/**
+ * Every path under the mount's subtree, in one paged walk.
+ *
+ * `recursive=true` returns the whole subtree. Size, oid and the LFS and Xet
+ * hashes all ride the bare row, so the only thing `expand=true` adds is the
+ * commit that last touched each path -- a Hub file's only mtime -- and it
+ * costs a twentyfold drop in page size (1000 rows to 50, with any explicit
+ * limit above 100 refused).
+ *
+ * Which one is used is the mount's call, and its default is neither: ask for
+ * one expanded page, and if the whole repository fit in it, that page is the
+ * answer and the mtimes came free. Only a repository too big for one page
+ * falls back to the bare walk, and pays one wasted request for the attempt.
+ */
+export declare function fetchTree(accessor: HfHubAccessor): Promise<Map<string, TreeEntry>>;
+/**
+ * Bucket a Hub tree by parent directory.
+ *
+ * Keyed by mount-absolute path, the way every other backend keys its index,
+ * so the shared cache machinery can spell an eviction without knowing which
+ * backend it is talking to. The tree itself stays mount-relative; `prefix` is
+ * what lifts it. This is the one shape both storage paths are built from, so
+ * the seeded index and the derived tables cannot disagree.
+ */
+export declare function indexDirs(tree: Map<string, TreeEntry>, prefix: string): Map<string, [string, IndexEntry][]>;
+/** The entry and children tables a no-index mount reads, from the buckets. */
+export declare function indexRows(tree: Map<string, TreeEntry>, prefix: string): RowTables;
+/**
+ * Write the accessor's tree into `index` under `prefix`.
+ *
+ * One `setDir` per directory, the way the shared store spells a whole
+ * listing; the year-long expiry is what makes the index the listing rather
+ * than a cache in front of one.
+ */
+export declare function seedIndex(accessor: HfHubAccessor, index: IndexCacheStore, prefix: string): Promise<void>;
+/**
+ * Refetch the tree and re-seed the index from it.
+ *
+ * The mount fetches the whole tree once and seeds the index with it, so the
+ * index *is* the listing rather than a cache in front of one. That makes a
+ * cleared or expired index indistinguishable from an empty repository, which
+ * is why dropping the index has to mean "refetch".
+ */
+export declare function refillIndex(accessor: HfHubAccessor, index: IndexCacheStore, prefix: string): Promise<boolean>;
+/**
+ * Refetch when the index holds no listing at all.
+ *
+ * Every reader treats a missing listing as a real absence, which is right
+ * against a *live* index and wrong against one that was never filled or has
+ * been dropped. The root listing is what tells the two apart, in one lookup
+ * and no request: the tree is written whole, so while the index is live the
+ * mount root always has a row.
+ */
+export declare function ensureLiveIndex(accessor: HfHubAccessor, index: IndexCacheStore, prefix: string): Promise<boolean>;
+/**
+ * Fetch the tree if this mount has not got one yet.
+ *
+ * Hydration is tracked by `treeLoaded`, never by whether the tree holds
+ * anything: an empty repository hydrates to an empty map, and reading that as
+ * "not hydrated" refetches it on every call forever.
+ */
+export declare function ensureTree(accessor: HfHubAccessor, index?: IndexCacheStore, prefix?: string): Promise<void>;
+/**
+ * The index tables built straight from the accessor's tree.
+ *
+ * What a mount with no index wired reads instead. Every reader has an index
+ * inside a workspace, but a backend constructed on its own has NULL_INDEX,
+ * whose every lookup is a miss -- so without this, readdir answered ENOENT for
+ * a repository it could list perfectly well. Built by the same `indexRows` the
+ * seeded path uses, so the two cannot disagree.
+ */
+export declare function localRows(accessor: HfHubAccessor, prefix: string): Promise<RowTables>;
+//# sourceMappingURL=tree.d.ts.map

package/dist/core/hf_hub/tree.d.ts.map

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