@bendyline/gezel-catalog 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bendyline
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @bendyline/gezel-catalog
+
+Catalog loader for [gezel](https://github.com/bendyline/gezel) — resolves the
+chat, image and video model catalogs, toolsets, connector types, project types,
+gezel role templates and craftbooks that the daemon serves.
+
+```bash
+npm install @bendyline/gezel-catalog
+```
+
+## Content lives elsewhere
+
+This package is the **loader**, not the content. The catalog data ships as
+[`@bendyline/gilde`](https://www.npmjs.com/package/@bendyline/gilde), an
+exact-pinned dependency resolved at runtime through `gildeDataDir()`.
+
+```ts
+import { CatalogService } from '@bendyline/gezel-catalog';
+
+const catalog = new CatalogService();
+const models = await catalog.list('chat-model');
+```
+
+Override the content root with `GEZEL_GILDE_DATA_DIR` for tests, evals or
+operator-supplied catalogs.
+
+Gilde takes open-source contributions — new models, toolsets and craftbooks are
+proposed there, not here.
+
+## Stability
+
+Public API under semver. The catalog *schemas* are defined in
+[`@bendyline/gezel`](https://www.npmjs.com/package/@bendyline/gezel) and follow
+its versioning.
+
+MIT © Bendyline

package/dist/index.d.ts

@@ -0,0 +1,555 @@
+import { CatalogKind, CatalogItemSummary, CatalogItemDetail, CatalogItemVersionInfo, CraftbookTestSpec, ToolsetCategory, ToolsetManifest } from '@bendyline/gezel';
+
+/**
+ * ─ CatalogSource ───────────────────────────────────────────────────
+ *
+ * Abstracts where catalog items live. Two implementations today:
+ *
+ *   - BundledSource:  reads the on-disk `data/` directory shipped with
+ *                     this package. Always available, zero network.
+ *   - RemoteSource:   (TODO) fetches a static index.json + per-item
+ *                     manifests from an HTTP(S) URL. Stubbed until we
+ *                     publish a public catalog repo.
+ *
+ * The CatalogService (see service.ts) composes multiple sources.
+ *
+ * On-disk layout under `data/`:
+ *
+ *   {kind-plural}/{shard}/{id}/manifest.json     ← identity layer
+ *   {kind-plural}/{shard}/{id}/versions/{semver}/manifest.json  ← per-version
+ *   {kind-plural}/{shard}/{id}/versions/{semver}/about.md       ← (templates) prompt
+ *
+ * Craftbook templates (V2) replace the per-version manifest + about.md +
+ * scripts/ with ONE `versions/{semver}/craftbook.json` (a CraftbookDoc:
+ * prose inlined as `description`, scripts inlined as the `scripts` map).
+ * The legacy layout is still read as a fallback — user/community roots
+ * may carry it.
+ */
+interface CatalogSource {
+    readonly id: string;
+    readonly label: string;
+    listKinds(): Promise<CatalogKind[]>;
+    list(kind: CatalogKind): Promise<CatalogItemSummary[]>;
+    /** When `version` is omitted, returns the auto-resolved latest. */
+    get(kind: CatalogKind, id: string, version?: string): Promise<CatalogItemDetail | null>;
+    /** All versions of an item, newest first. Empty when item is missing. */
+    listVersions(kind: CatalogKind, id: string): Promise<CatalogItemVersionInfo[]>;
+    /**
+     * Read a file relative to an item's folder. When `version` is set, the
+     * version subfolder is checked first; misses fall through to the item
+     * root so shared assets (`logo.svg`) don't have to be duplicated per
+     * version.
+     */
+    readItemFile(kind: CatalogKind, id: string, relPath: string, version?: string): Promise<Buffer | null>;
+    /**
+     * Optional: every file under an item's folder as item-relative paths. Only
+     * on-disk sources implement it (used by the `.gzl` exporter); synthetic
+     * sources (builtin toolsets) omit it.
+     */
+    listItemFiles?(kind: CatalogKind, id: string): Promise<string[]>;
+    /**
+     * Optional: a craftbook's eval descriptor (`versions/<v>/test.json`),
+     * tolerant-parsed. Null when the book, version, or sidecar is missing
+     * or unparseable. Only on-disk craftbook sources implement it.
+     */
+    getCraftbookTestSpec?(id: string, version?: string): Promise<{
+        version: string;
+        spec: CraftbookTestSpec;
+    } | null>;
+}
+interface BundledSourceOptions {
+    /**
+     * Override the on-disk root. Defaults to `data/` next to this package.
+     * A function is re-read on every disk access — the live gilde update
+     * mechanism uses this to flip the content root without reconstructing
+     * the source (CatalogService is built once at boot and held by many
+     * subsystems). A string keeps the historical freeze-at-construct
+     * behavior.
+     */
+    dataDir?: string | (() => string);
+    /** Source id surfaced via `CatalogService.listSources()`. */
+    id?: string;
+    /** Human-readable label. */
+    label?: string;
+    /**
+     * When true, skip the per-kind `index.json` fast-path and always walk
+     * the per-item folders. Used by the index builder itself (see
+     * gilde `tools/build-index.mjs`) to avoid feeding a stale or absent index
+     * back into itself, and by tests that want deterministic disk reads.
+     */
+    noIndex?: boolean;
+    /**
+     * The running app's version, compared against content `minGezelVersion`
+     * floors. Defaults to `GEZEL_VERSION`; injectable so tests can exercise
+     * gating against a stamped version (`GEZEL_VERSION` is `0.0.0` in dev
+     * checkouts, which bypasses all filtering).
+     */
+    gezelVersion?: string;
+}
+declare class BundledSource implements CatalogSource {
+    readonly id: string;
+    readonly label: string;
+    private readonly rootProvider;
+    private readonly useIndex;
+    private readonly gezelVersion;
+    constructor(options?: BundledSourceOptions | string);
+    private get root();
+    /** True when this build satisfies a content `minGezelVersion` floor. */
+    private floorSatisfied;
+    listKinds(): Promise<CatalogKind[]>;
+    list(kind: CatalogKind): Promise<CatalogItemSummary[]>;
+    /**
+     * Fast-path: when `{kindDir}/index.json` is present, load every
+     * summary from that one file instead of walking ~3,800 per-item
+     * folders. The index is generated by gilde `tools/build-index.mjs` and
+     * embeds the same `CatalogItemManifest` shape this source produces
+     * via the slow walk, plus a derived `category` for toolsets.
+     *
+     * Returns null when the index is missing or unreadable; callers fall
+     * back to `listFromDisk()`. Per-entry parse failures are skipped.
+     */
+    private listFromIndex;
+    private listFromDisk;
+    get(kind: CatalogKind, id: string, version?: string): Promise<CatalogItemDetail | null>;
+    listVersions(kind: CatalogKind, id: string): Promise<CatalogItemVersionInfo[]>;
+    readItemFile(kind: CatalogKind, id: string, relPath: string, version?: string): Promise<Buffer | null>;
+    /**
+     * Every file under an item's folder, as item-relative paths (e.g.
+     * `manifest.json`, `versions/1.0.0/pages/gallery/index.html`), sorted. Used
+     * by the `.gzl` exporter to pack an item verbatim — pages, seeds, and all
+     * assets, not just the ones the manifest names. Read each back with
+     * `readItemFile(kind, id, relPath)` (no version → item-relative). Empty when
+     * the item folder is missing.
+     */
+    listItemFiles(kind: CatalogKind, id: string): Promise<string[]>;
+    /** Parse a version folder's `craftbook.json`, or null when absent/invalid. */
+    private readCraftbookDoc;
+    /**
+     * A craftbook's eval descriptor (`versions/<v>/test.json`), tolerant-
+     * parsed so a spec written by a newer author still loads. Resolution
+     * mirrors `get`: no `version` → the latest non-yanked semver. Null on
+     * missing book/version/sidecar or an unparseable spec (CI's strict
+     * guard is where invalid specs get surfaced loudly — runtime readers
+     * degrade quietly).
+     */
+    getCraftbookTestSpec(id: string, version?: string): Promise<{
+        version: string;
+        spec: CraftbookTestSpec;
+    } | null>;
+    private itemDir;
+    /** Read + validate the identity (root) manifest for an item. */
+    private loadIdentity;
+    /** Enumerate `versions/{semver}/manifest.json` entries. Unsorted. */
+    private discoverVersionFolders;
+    /**
+     * Pick a target version. When `requested` is set, validate it exists —
+     * an explicit pin deliberately bypasses the yank / `minSupportedVersion`
+     * / `minGezelVersion` filters so installed content keeps resolving.
+     * Otherwise resolve the highest non-yanked semver above
+     * `minSupportedVersion` whose `minGezelVersion` floor this build
+     * satisfies. Returns null when nothing satisfies.
+     */
+    private pickVersion;
+    /**
+     * Compose identity + version into the resolved (flat) manifest shape
+     * that consumers expect. Returns null when identity is missing,
+     * version is missing, or validation fails.
+     */
+    private loadResolvedManifest;
+    private readOptional;
+    private logoUrlFor;
+}
+
+/**
+ * Composes one or more `CatalogSource`s behind a single API. Order is
+ * priority order — earlier sources shadow later ones on id collision:
+ *
+ *   1. BuiltinToolsetsSource — synthetic groups for our in-process MCP
+ *      server. Tools we ship and own.
+ *   2. BundledSource — pre-reviewed third-party catalog shipped with
+ *      the app (`data/`). Hand-curated.
+ *   3. CommunitySource — auto-imported entries from the upstream MCP
+ *      registry (`data/community/`). Permissively-licensed only;
+ *      treated as a second tier that the UI can label distinctly.
+ *
+ * UI + HTTP both go through this service.
+ */
+declare class CatalogService {
+    private readonly sources;
+    private readonly contentRootProvider;
+    /**
+     * @param sources explicit source list (replaces the defaults entirely).
+     * @param opts.localRoot a GEZEL_HOME to read user-installed / `.gzl`-imported
+     *   catalog items from (project types + gezel roles). Appended just ahead of
+     *   the bundled tier so a user's imported item shadows a same-id bundled one.
+     * @param opts.contentRoot dynamic gilde content root for the default
+     *   bundled + community tiers, re-read on every disk access. The live
+     *   gilde update mechanism flips it without reconstructing this service
+     *   (which is built once at boot and held by many subsystems).
+     * @param opts.gezelVersion the running app's version, compared against
+     *   content `minGezelVersion` floors. Defaults to `GEZEL_VERSION`
+     *   inside each source; injectable so tests can exercise gating (dev
+     *   checkouts report `0.0.0`, which bypasses all filtering).
+     */
+    constructor(sources?: CatalogSource[], opts?: {
+        localRoot?: string;
+        contentRoot?: () => string;
+        gezelVersion?: string;
+    });
+    /**
+     * The effective gilde content root, or null when constructed without a
+     * provider (tests, CLI one-shots). Cheap and synchronous — ChatManager
+     * snapshots it per session to detect a live content flip and rebuild
+     * cached model profiles/tuning on the next turn.
+     */
+    contentRoot(): string | null;
+    /** All active sources in priority order (higher trust first). */
+    listSources(): Array<{
+        id: string;
+        label: string;
+    }>;
+    /**
+     * Merged listing across sources. Items from earlier sources (bundled)
+     * shadow later sources (remote) on id collision.
+     */
+    list(kind: CatalogKind): Promise<CatalogItemSummary[]>;
+    get(kind: CatalogKind, id: string, sourceId?: string, version?: string): Promise<CatalogItemDetail | null>;
+    listVersions(kind: CatalogKind, id: string, sourceId?: string): Promise<CatalogItemVersionInfo[]>;
+    readItemFile(kind: CatalogKind, id: string, relPath: string, sourceId?: string, version?: string): Promise<Buffer | null>;
+    /** Every file under an item's folder (item-relative paths). For the exporter. */
+    listItemFiles(kind: CatalogKind, id: string, sourceId?: string): Promise<string[]>;
+    /**
+     * A craftbook's eval descriptor (`test.json` sidecar), from the first
+     * source that carries one. Null when no source ships it.
+     */
+    getCraftbookTestSpec(id: string, version?: string): Promise<{
+        version: string;
+        spec: CraftbookTestSpec;
+    } | null>;
+}
+
+/**
+ * Root of the installed (or link:ed) @bendyline/gilde package — the
+ * external content repo that replaced the old in-package `data/` tree.
+ *
+ * Resolved via the package's `./package.json` export; if gilde ever
+ * ships an `exports` map without that subpath, this throws and the
+ * service boots with an empty catalog (see the AGENTS.md gotcha and
+ * the guard test in gilde-data.test.ts).
+ */
+declare function gildePackageRoot(): string;
+/**
+ * The catalog content root (kind dirs + community/). Honors
+ * GEZEL_GILDE_DATA_DIR (absolute path to a data dir, e.g. a raw
+ * ../gilde/data checkout) so tests, evals, and operators can bypass
+ * node resolution entirely. Not cached — the override must stay
+ * flippable within a process (tests rely on it).
+ */
+declare function gildeDataDir(): string;
+
+/**
+ * The community catalog tier — entries auto-imported from the upstream
+ * MCP registry (registry.modelcontextprotocol.io). Same on-disk layout
+ * as the bundled catalog, just rooted at `data/community/` so the
+ * hand-curated bundled tier stays small and visually distinct.
+ *
+ * Layout under the community root mirrors `BundledSource`'s expected
+ * shape:
+ *
+ *   data/community/toolsets/{shard}/{id}/manifest.json
+ *   data/community/toolsets/{shard}/{id}/versions/{semver}/manifest.json
+ *
+ * Only the `toolsets` kind is populated today; other kinds can land
+ * here later without further plumbing.
+ *
+ * Identity collisions are resolved by `CatalogService` priority:
+ * BundledSource is registered ahead of CommunitySource, so a community
+ * entry with the same id as a bundled one is shadowed.
+ */
+declare class CommunitySource extends BundledSource {
+    constructor(dataDir?: string | (() => string), gezelVersion?: string);
+}
+
+declare class LocalCatalogSource extends BundledSource {
+    constructor(home: string, gezelVersion?: string);
+    listKinds(): Promise<CatalogKind[]>;
+    list(kind: CatalogKind): Promise<CatalogItemSummary[]>;
+    get(kind: CatalogKind, id: string, version?: string): Promise<CatalogItemDetail | null>;
+    listVersions(kind: CatalogKind, id: string): Promise<CatalogItemVersionInfo[]>;
+    readItemFile(kind: CatalogKind, id: string, relPath: string, version?: string): Promise<Buffer | null>;
+    listItemFiles(kind: CatalogKind, id: string): Promise<string[]>;
+}
+
+/**
+ * Categorize a toolset by its identity-manifest fields. The order of
+ * checks matches the priority order of `RULES` above.
+ *
+ * Inputs are lowercased and concatenated into a single haystack —
+ * tokenized matching isn't worth the complexity for ~10% better
+ * placement of niche entries.
+ */
+declare function categorizeToolset(input: {
+    id: string;
+    name: string;
+    description: string;
+    tags: readonly string[];
+    maintainerName?: string;
+}): ToolsetCategory;
+
+/**
+ * ─ Built-in toolsets ────────────────────────────────────────────────
+ *
+ * The main MCP server (`@bendyline/gezel-mcp`) registers 90+ tools.
+ * Sending all of them on every chat turn fills 10K+ input tokens of
+ * tool schemas before the user's message is even read — enough to
+ * trip OpenAI Tier-1 TPM caps on a fresh "hello?" turn. The fix is
+ * to bucket those tools into named groups and only expose the groups
+ * a given gezel actually needs.
+ *
+ * Each group surfaces in the catalog as a synthetic toolset manifest
+ * with `runtime.kind === 'builtin'`. A gezel's toolsets can install /
+ * uninstall these groups exactly like third-party MCP toolsets;
+ * `ChatManager` reads the per-gezel toolsets, expands the groups to a
+ * tool-name allowlist, and hands it to `McpBridgePool` which strips
+ * everything else before serializing for the model.
+ *
+ * Membership is the single source of truth for role defaults
+ * (`role-tool-filter.ts` references group ids, not tool names) and
+ * for the picker UI. New tools added to the MCP server should be
+ * dropped into a relevant group here so they reach gezels at all.
+ *
+ * Catalog id format: `builtin.<group-id>` (e.g. `builtin.workspace-fs-read`).
+ * The prefix keeps us out of the third-party id namespace.
+ */
+interface BuiltinToolsetGroup {
+    id: string;
+    name: string;
+    description: string;
+    tools: string[];
+}
+declare const BUILTIN_TOOLSETS: BuiltinToolsetGroup[];
+/** Resolve a group by its `id` (e.g. `'workspace-fs-read'`). */
+declare function getBuiltinToolset(id: string): BuiltinToolsetGroup | undefined;
+/**
+ * Inverse map: tool name → group it belongs to. Built once at module
+ * load (~60 entries). Used by the auto-injected `## Tools available
+ * this turn` block in the system prompt to bucket tool names into
+ * named groups so the model sees a structured listing rather than a
+ * flat alphabet soup. Tools not in any group (third-party MCP servers
+ * the user installed) get classified as "other" by the consumer.
+ *
+ * If two groups ever name the same tool, the FIRST group in
+ * `BUILTIN_TOOLSETS` wins (matches the Map insertion-order iteration).
+ * Deliberate subset groups such as `tasks-readonly` may duplicate a
+ * strict slice of their base group; other duplication is a manifest bug
+ * worth surfacing rather than silently resolving here.
+ */
+declare const BUILTIN_TOOL_TO_GROUP: Map<string, BuiltinToolsetGroup>;
+/** Catalog id format: `builtin.<group-id>`. */
+declare function builtinCatalogId(groupId: string): string;
+/**
+ * Catalog source that exposes the BUILTIN_TOOLSETS as installable
+ * toolsets. Composed alongside `BundledSource` in `CatalogService`.
+ */
+declare class BuiltinToolsetsSource implements CatalogSource {
+    readonly id = "builtin";
+    readonly label = "Built-in";
+    listKinds(): Promise<CatalogKind[]>;
+    list(kind: CatalogKind): Promise<CatalogItemSummary[]>;
+    get(kind: CatalogKind, id: string, version?: string): Promise<CatalogItemDetail | null>;
+    listVersions(kind: CatalogKind, id: string): Promise<CatalogItemVersionInfo[]>;
+    readItemFile(kind: CatalogKind, id: string, relPath: string, _version?: string): Promise<Buffer | null>;
+}
+
+interface NpmInstallOptions {
+    manifest: ToolsetManifest & {
+        runtime: {
+            kind: 'npm-package';
+        };
+    };
+    installRoot: string;
+    /** Test/private-registry override. Redirects remain pinned to this exact origin. */
+    registry?: string;
+}
+interface NpmInstallResult {
+    installPath: string;
+    tarballSha256: string;
+}
+declare function installNpmPackageToolset(opts: NpmInstallOptions): Promise<NpmInstallResult>;
+/** SHA-256 of a tarball on disk without buffering the archive in memory. */
+declare function verifyTarballSha256(tarballPath: string): Promise<string>;
+declare function extractNpmPackageTarball(opts: {
+    tarballPath: string;
+    destination: string;
+    expectedName: string;
+    expectedVersion: string;
+}): Promise<string>;
+declare function validateNpmArchiveEntry(path: string, type: string): void;
+declare function publishStagedNpmInstall(staging: string, target: string, backup: string): Promise<void>;
+declare function recoverInterruptedNpmInstall(target: string, backup: string): Promise<void>;
+
+/**
+ * Registry interaction for live gilde content updates. Pure fetch/stage
+ * helpers — the stateful orchestration (opt-in gate, scheduler, activation,
+ * pruning) lives in the service's GildeUpdateManager. The trust anchor here
+ * is registry TLS plus the registry-reported integrity hash, the same trust
+ * a build-time `pnpm install` of the pin extends.
+ */
+declare const GILDE_PACKAGE_NAME = "@bendyline/gilde";
+interface GildeReleaseInfo {
+    version: string;
+    tarballUrl: string;
+    /** SRI string from the registry (`sha512-<base64>`), when present. */
+    integrity?: string;
+    /** Legacy sha1 hex from the registry, when present. */
+    shasum?: string;
+}
+/**
+ * Every plain `major.minor.patch` release of `@bendyline/gilde` the registry
+ * knows, unsorted. Prerelease versions and releases whose tarball points off
+ * the registry origin are dropped.
+ */
+declare function fetchGildeReleases(opts?: {
+    registry?: string;
+}): Promise<GildeReleaseInfo[]>;
+/**
+ * Same-minor-line update policy: the newest release on the bundled pin's
+ * `major.minor` line that is strictly newer than both the pin and the
+ * currently-active live version. Null when the install is already current.
+ * Line bumps deliberately ride app releases — they may carry schema changes
+ * this build's loader cannot represent.
+ */
+declare function pickGildePatchUpdate(releases: GildeReleaseInfo[], bundledPin: string, currentLive?: string): GildeReleaseInfo | null;
+/** Numeric compare for plain `major.minor.patch` strings. */
+declare function compareRelease(a: string, b: string): number;
+/** `true` for the plain `major.minor.patch` form gilde releases use. */
+declare function isGildeReleaseVersion(v: string): boolean;
+/**
+ * Download + verify + extract one gilde release into `stagingDir`. Returns
+ * the extracted `package/` directory (content root is `<packageDir>/data`).
+ * Refuses when the registry metadata carries no usable integrity hash. The
+ * tarball is removed either way; the caller owns `stagingDir` cleanup on
+ * error.
+ */
+declare function stageGildeVersion(opts: {
+    release: GildeReleaseInfo;
+    stagingDir: string;
+    registry?: string;
+}): Promise<{
+    packageDir: string;
+}>;
+
+/**
+ * The empirical no-regression gate for live gilde activation. The loader in
+ * this build parses content with this build's Zod schemas, and an
+ * unparseable item silently vanishes from the catalog — acceptable for a
+ * brand-new item authored against newer schemas, catastrophic for one the
+ * install already relies on (an installed model would lose its tuning, a
+ * scheduled craftbook would stop resolving). So before activating a
+ * candidate content root, every item resolvable from the current root must
+ * still resolve from the candidate; anything less refuses the update.
+ */
+interface GildeContentRegression {
+    kind: CatalogKind;
+    id: string;
+}
+type GildeContentValidation = {
+    ok: true;
+    checked: number;
+} | {
+    ok: false;
+    regressions: GildeContentRegression[];
+};
+declare function validateGildeContentUpgrade(opts: {
+    currentDataDir: string;
+    candidateDataDir: string;
+    /**
+     * App version for `minGezelVersion` gating — defaults to `GEZEL_VERSION`
+     * inside the sources. Both sides run on the same build, so gating is
+     * symmetric: a candidate that retro-gates a currently-resolvable item
+     * fails this gate (correctly — that item would vanish for this install),
+     * while a brand-new gated item passes (it never resolved here before).
+     * Injectable for tests; dev builds (`0.0.0`) never gate.
+     */
+    gezelVersion?: string;
+}): Promise<GildeContentValidation>;
+
+/**
+ * Tiny Hugging Face Hub API client used by catalog tooling.
+ *
+ * Scope: enough to list the files in a model repo and extract their
+ * sha256 + size for manifest generation. Not a general-purpose HF SDK —
+ * we don't need authentication, dataset endpoints, model cards, or
+ * downloads (the install path has its own streaming downloader).
+ *
+ * The Hub publishes file metadata at `/api/models/<repo>/tree/<rev>`.
+ * Each entry looks like:
+ *
+ *   {
+ *     "type": "file",
+ *     "path": "model-00001-of-00003.safetensors",
+ *     "size": 5343268752,
+ *     "oid": "0b9b0515...",                    // git blob sha
+ *     "lfs": { "oid": "2689680915...", ... }, // sha256 of the LFS payload
+ *   }
+ *
+ * The `lfs.oid` is the sha256 we want for integrity checks. Plain
+ * non-LFS files (small JSONs, tokenizer configs) don't carry an
+ * `lfs` block — we fall back to the git blob's `oid`, which the HF
+ * client tools also accept for verification.
+ */
+interface HfFileEntry {
+    /** Path within the repo (e.g. `model.safetensors`, `config.json`). */
+    path: string;
+    /** Size in bytes (LFS-aware — points at the resolved payload, not the pointer file). */
+    sizeBytes: number;
+    /**
+     * SHA-256 hex string we use for integrity checks. For LFS-stored
+     * files this is `lfs.oid` (HF stores the sha256 there). For small
+     * non-LFS files, falls back to the git blob `oid` — not a sha256
+     * but stable, and the HF client tools accept it.
+     */
+    sha256: string;
+    /** True when the sha came from `lfs.oid` (a real sha256). */
+    lfsBacked: boolean;
+}
+interface FetchTreeOptions {
+    /** Branch / tag / commit. Defaults to `main`. */
+    rev?: string;
+    /** Test seam — defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * List every file in a Hugging Face model repo at the given rev.
+ * Recurses into subdirectories so deeply-nested files (rare, but
+ * happens for some quants) are returned flattened with their full
+ * path.
+ */
+declare function fetchHuggingfaceTree(repo: string, opts?: FetchTreeOptions): Promise<HfFileEntry[]>;
+/**
+ * Resolve a Hugging Face repo + revision to its concrete commit SHA.
+ *
+ * `/api/models/<repo>/revision/<rev>` returns the repo metadata for that
+ * ref, including `sha` — the 40-char commit the ref currently points at.
+ * Catalog tooling calls this with `rev = 'main'` to capture the commit
+ * to pin in a manifest, so downloads become content-frozen against an
+ * immutable snapshot rather than the moving branch tip.
+ */
+declare function fetchHuggingfaceCommit(repo: string, opts?: {
+    rev?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<string>;
+/**
+ * Total bytes across every file in a repo's tree. Used to populate
+ * `approxSizeBytes` on a chat-model manifest.
+ */
+declare function totalSize(files: ReadonlyArray<HfFileEntry>): number;
+/**
+ * Filter the tree down to the files an MLX install actually needs:
+ * weight shards (`*.safetensors`), the safetensors index, configs,
+ * and tokenizer files. Drops `.gitattributes`, `README.md`, sample
+ * images, and other repo metadata that MLX doesn't read at run time.
+ */
+declare function selectMlxInstallFiles(files: ReadonlyArray<HfFileEntry>): HfFileEntry[];
+
+export { BUILTIN_TOOLSETS, BUILTIN_TOOL_TO_GROUP, type BuiltinToolsetGroup, BuiltinToolsetsSource, BundledSource, type BundledSourceOptions, CatalogService, type CatalogSource, CommunitySource, type FetchTreeOptions, GILDE_PACKAGE_NAME, type GildeContentRegression, type GildeContentValidation, type GildeReleaseInfo, type HfFileEntry, LocalCatalogSource, builtinCatalogId, categorizeToolset, compareRelease, extractNpmPackageTarball, fetchGildeReleases, fetchHuggingfaceCommit, fetchHuggingfaceTree, getBuiltinToolset, gildeDataDir, gildePackageRoot, installNpmPackageToolset, isGildeReleaseVersion, pickGildePatchUpdate, publishStagedNpmInstall, recoverInterruptedNpmInstall, selectMlxInstallFiles, stageGildeVersion, totalSize, validateGildeContentUpgrade, validateNpmArchiveEntry, verifyTarballSha256 };