dsh-plugin-local-infer 0.1.2 → 0.1.4

package/packages/core/lib/models.d.ts

@@ -14,6 +14,14 @@ export interface DefaultModel {
     url: string;
     file?: string;
 }
+/**
+ * ModelDownloadSource is the half of a DefaultModel the presence check, the
+ * hf CLI command, and the hub-cache lookup read: the Hugging Face repo URL
+ * and the optional artifact file. A full list entry satisfies it, and an
+ * adapter that only resolves the download pair composes just these fields
+ * instead of restating the entry's inert registry data.
+ */
+export type ModelDownloadSource = Pick<DefaultModel, 'url' | 'file'>;
 /**
  * repoIdFromUrl turns a Hugging Face repo URL into the `owner/name` repo id
  * the hf CLI takes. A URL with no owner/name pair reads as an empty id, which
@@ -27,18 +35,57 @@ export declare function repoIdFromUrl(url: string): string;
  */
 export declare function repoNameFromUrl(url: string): string;
 /**
- * modelArtifactPath is the path the presence check looks for in the model
- * directory: the entry's artifact file when it names one, else the repo-name
- * directory a whole-repo download leaves behind.
+ * hubCacheModelDirectory is the per-model directory the hf CLI creates in the
+ * hub cache for one repo id: `models--{namespace}--{name}`. A repo id without
+ * an owner/name pair reads as an empty directory name, which the callers
+ * handle as an absent model.
+ */
+export declare function hubCacheModelDirectory(repoId: string): string;
+/**
+ * isModelDirectoryOverridden reports whether a model directory field (the
+ * config's or a download request's) names a path (a non-blank string), the
+ * one rule every download route and view model shares to decide the layout:
+ * a named directory targets that directory flat (`--local-dir`), an unnamed
+ * one takes the hub-cache layout (no `--local-dir`, the
+ * `models--{ns}--{name}` directories the hf CLI writes into the hub cache).
+ * The predicate form lets callers narrow the field to a string without
+ * restating the blank check.
+ */
+export declare function isModelDirectoryOverridden(modelDirectory: unknown): modelDirectory is string;
+/**
+ * modelArtifactPath is the path a model download's artifact lands at in the
+ * model directory: the entry's artifact file when it names one, else the
+ * repo-name directory a whole-repo download leaves behind. With the hub-cache
+ * layout (`useHubCache`), it resolves into the per-model cache directory's
+ * `blobs` folder, the content-addressed store the hf CLI writes without
+ * `--local-dir`; the `directory` is then the hub cache root, not the per-model
+ * folder. Every presence decision (the card-facing checks and the engines'
+ * deploy re-fetch gates) resolves the deterministic snapshot instead
+ * (modelArtifactPresent); the hub-cache form here stays the blobs-store path.
  */
-export declare function modelArtifactPath(entry: DefaultModel, directory: string): string;
+export declare function modelArtifactPath(entry: ModelDownloadSource, directory: string, useHubCache?: boolean): string;
 /**
- * hfDownloadCommand renders the hf CLI download for one default model: the
- * repo, the artifact file when the entry names one, and the `--local-dir`
- * target. The string is the single source the download route runs and the
- * card shows beside its Download button.
+ * hfDownloadFileCommand renders the hf CLI download for one repo and file
+ * pair: the repo, the file (omitted when blank, a whole-repo download), the
+ * `--local-dir` target when the hub-cache layout does not apply, and the
+ * `--format human` flag. The flag overrides the non-TTY default (`auto` picks
+ * `agent`, which prints no progress) so the hf CLI prints tqdm progress
+ * lines to stderr, which the progress streaming tasks consume. The string is
+ * the single source every hf download command renders through: the model and
+ * chat-template builders below, and the Infernix extra-download commands the
+ * Get step streams.
  */
-export declare function hfDownloadCommand(entry: DefaultModel, directory: string): string;
+export declare function hfDownloadFileCommand(repo: string, file: string, directory: string, useHubCache?: boolean): string;
+/**
+ * hfDownloadCommand renders the hf CLI download for one model download
+ * source: the repo, the artifact file when the entry names one, and the
+ * `--local-dir` target. With the hub-cache layout (`useHubCache`), the `--local-dir` is
+ * dropped so the hf CLI writes into the hub cache's `models--{ns}--{name}`
+ * directory (the content-addressed `blobs/` plus the `snapshots/`). The
+ * string is the single source the download route runs and the card shows
+ * beside its Download button, rendered through hfDownloadFileCommand.
+ */
+export declare function hfDownloadCommand(entry: ModelDownloadSource, directory: string, useHubCache?: boolean): string;
 /**
  * The chat template file the hf CLI pulls into the model directory. The
  * NInfer deploy step and the template download route both target this name, so
@@ -48,11 +95,50 @@ export declare const CHAT_TEMPLATE_FILE = "chat_template.jinja";
 /**
  * hfChatTemplateCommand renders the hf CLI download for one chat template repo
  * reference into the model directory: the repo, the template file, and the
- * `--local-dir` target. The string is the single source the template download
- * route runs and the card shows beside its Download button and in the System
- * dependencies box when the auto-download is unavailable.
+ * `--local-dir` target. With the hub-cache layout (`useHubCache`), the
+ * `--local-dir` is dropped so the template lands in the hub cache's
+ * `models--{ns}--{name}` directory. The string is the single source the
+ * template download route runs and the card shows beside its Download button
+ * and in the System dependencies box when the auto-download is unavailable,
+ * rendered through hfDownloadFileCommand.
  */
-export declare function hfChatTemplateCommand(repo: string, directory: string): string;
+export declare function hfChatTemplateCommand(repo: string, directory: string, useHubCache?: boolean): string;
+/**
+ * chatTemplateArtifactPath is the path the flat-layout chat-template presence
+ * check looks for: the template file joined onto the model directory. The
+ * hub-cache layout resolves through chatTemplatePresent instead (the
+ * deterministic snapshot pick), not through this join.
+ */
+export declare function chatTemplateArtifactPath(directory: string): string;
+/**
+ * modelArtifactPresent reports whether a model download source's artifact is
+ * on disk. With the hub-cache layout it resolves the deterministic hub-cache
+ * snapshot holding the file (the same pick the model-directory display uses),
+ * so a `blobs` folder left by any download never reads as present on its
+ * own; a blank `file` (a whole-repo download) reads the repo's snapshot
+ * directories. With the flat layout it checks the artifact path joined onto
+ * the base directory. `baseDir` is the hub cache root under the cache layout,
+ * the flat override otherwise.
+ */
+export declare function modelArtifactPresent(entry: ModelDownloadSource, baseDir: string, useHubCache?: boolean): boolean;
+/**
+ * chatTemplatePresent reports whether a chat template repo's template file is
+ * on disk: the deterministic hub-cache snapshot pick under the hub-cache
+ * layout (a per-repo `snapshots` folder alone never reads as present), the
+ * flat file join otherwise. `baseDir` follows the modelArtifactPresent rule.
+ */
+export declare function chatTemplatePresent(repo: string, baseDir: string, useHubCache?: boolean): boolean;
+/**
+ * hubCacheSnapshotFilePath resolves the concrete file path of one file in the
+ * hub cache's snapshots, matching what the hf CLI treats as the active
+ * revision: the commit recorded in `refs/main` wins when its directory under
+ * `models--{ns}--{name}/snapshots/` holds the file; otherwise the snapshot
+ * with the newest mtime wins, covering a repo with no ref and a ref naming a
+ * commit that lacks the file. Ties break on readdir order. Returns null when
+ * no snapshot holds the file (the file is not downloaded), which the caller
+ * reads as absent. The `hubCache` is the hub cache root.
+ */
+export declare function hubCacheSnapshotFilePath(hubCache: string, repoId: string, file: string): string | null;
 /**
  * ModelDirectoryEntry is one top-level entry of a model directory listing:
  * the entry name, whether it is a directory, and for directories whether the
@@ -74,4 +160,24 @@ export interface ModelDirectoryEntry {
  * sorted, so the dropdown order is stable across summary fetches.
  */
 export declare function modelEntriesForEngine(entries: readonly ModelDirectoryEntry[], engineId: string): string[];
-//# sourceMappingURL=models.d.ts.map
+/**
+ * ModelCacheEntry is one `models--*` directory in the hub cache: the repo id
+ * the directory names (the `{namespace}/{name}` decoded from the
+ * `models--{ns}--{name}` form) and the artifact file names the snapshots hold
+ * (the union across every commit), the data the per-engine cache scan filters.
+ */
+export interface ModelCacheEntry {
+    repoId: string;
+    files: string[];
+}
+/**
+ * modelCacheEntriesForEngine filters the hub cache's `models--*` directories
+ * down to the models the engine's Model dropdown offers, by the artifact types
+ * each engine serves: Basalt `.basalt`, NInfer `.ninfer`, Infernix
+ * `.ninfer`/`.infernix`, llama.cpp `.gguf`, Hyper-Qwen a repo holding a
+ * `.safetensors` weight file, and Strata `.gguf`/`.safetensors`. An engine with
+ * no matching cached model lists none. The result is the repo ids the
+ * dropdown shows, sorted for a stable order across summary fetches.
+ */
+export declare function modelCacheEntriesForEngine(entries: readonly ModelCacheEntry[], engineId: string): string[];
+//# sourceMappingURL=models.d.ts.map

package/packages/core/lib/models.js

@@ -1,3 +1,4 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 /**
  * repoIdFromUrl turns a Hugging Face repo URL into the `owner/name` repo id
@@ -21,26 +22,81 @@ export function repoNameFromUrl(url) {
     return slash >= 0 ? repo.slice(slash + 1) : repo;
 }
 /**
- * modelArtifactPath is the path the presence check looks for in the model
- * directory: the entry's artifact file when it names one, else the repo-name
- * directory a whole-repo download leaves behind.
+ * hubCacheModelDirectory is the per-model directory the hf CLI creates in the
+ * hub cache for one repo id: `models--{namespace}--{name}`. A repo id without
+ * an owner/name pair reads as an empty directory name, which the callers
+ * handle as an absent model.
  */
-export function modelArtifactPath(entry, directory) {
+export function hubCacheModelDirectory(repoId) {
+    const slash = repoId.lastIndexOf('/');
+    if (slash <= 0)
+        return '';
+    return `models--${repoId.slice(0, slash)}--${repoId.slice(slash + 1)}`;
+}
+/**
+ * isModelDirectoryOverridden reports whether a model directory field (the
+ * config's or a download request's) names a path (a non-blank string), the
+ * one rule every download route and view model shares to decide the layout:
+ * a named directory targets that directory flat (`--local-dir`), an unnamed
+ * one takes the hub-cache layout (no `--local-dir`, the
+ * `models--{ns}--{name}` directories the hf CLI writes into the hub cache).
+ * The predicate form lets callers narrow the field to a string without
+ * restating the blank check.
+ */
+export function isModelDirectoryOverridden(modelDirectory) {
+    return typeof modelDirectory === 'string' && modelDirectory.trim() !== '';
+}
+/**
+ * modelArtifactPath is the path a model download's artifact lands at in the
+ * model directory: the entry's artifact file when it names one, else the
+ * repo-name directory a whole-repo download leaves behind. With the hub-cache
+ * layout (`useHubCache`), it resolves into the per-model cache directory's
+ * `blobs` folder, the content-addressed store the hf CLI writes without
+ * `--local-dir`; the `directory` is then the hub cache root, not the per-model
+ * folder. Every presence decision (the card-facing checks and the engines'
+ * deploy re-fetch gates) resolves the deterministic snapshot instead
+ * (modelArtifactPresent); the hub-cache form here stays the blobs-store path.
+ */
+export function modelArtifactPath(entry, directory, useHubCache = false) {
+    if (useHubCache) {
+        const modelDir = hubCacheModelDirectory(repoIdFromUrl(entry.url));
+        if (modelDir !== '')
+            return join(directory, modelDir, 'blobs');
+    }
     if (entry.file !== undefined && entry.file !== '') {
         return join(directory, entry.file);
     }
     return join(directory, repoNameFromUrl(entry.url));
 }
 /**
- * hfDownloadCommand renders the hf CLI download for one default model: the
- * repo, the artifact file when the entry names one, and the `--local-dir`
- * target. The string is the single source the download route runs and the
- * card shows beside its Download button.
+ * hfDownloadFileCommand renders the hf CLI download for one repo and file
+ * pair: the repo, the file (omitted when blank, a whole-repo download), the
+ * `--local-dir` target when the hub-cache layout does not apply, and the
+ * `--format human` flag. The flag overrides the non-TTY default (`auto` picks
+ * `agent`, which prints no progress) so the hf CLI prints tqdm progress
+ * lines to stderr, which the progress streaming tasks consume. The string is
+ * the single source every hf download command renders through: the model and
+ * chat-template builders below, and the Infernix extra-download commands the
+ * Get step streams.
+ */
+export function hfDownloadFileCommand(repo, file, directory, useHubCache = false) {
+    const filePart = file !== '' ? ` ${file}` : '';
+    const localDir = useHubCache ? '' : ` --local-dir ${directory}`;
+    return `hf download ${repo}${filePart}${localDir} --format human`;
+}
+/**
+ * hfDownloadCommand renders the hf CLI download for one model download
+ * source: the repo, the artifact file when the entry names one, and the
+ * `--local-dir` target. With the hub-cache layout (`useHubCache`), the `--local-dir` is
+ * dropped so the hf CLI writes into the hub cache's `models--{ns}--{name}`
+ * directory (the content-addressed `blobs/` plus the `snapshots/`). The
+ * string is the single source the download route runs and the card shows
+ * beside its Download button, rendered through hfDownloadFileCommand.
  */
-export function hfDownloadCommand(entry, directory) {
+export function hfDownloadCommand(entry, directory, useHubCache = false) {
     const repo = repoIdFromUrl(entry.url);
-    const file = entry.file !== undefined && entry.file !== '' ? ` ${entry.file}` : '';
-    return `hf download ${repo}${file} --local-dir ${directory}`;
+    const file = entry.file !== undefined && entry.file !== '' ? entry.file : '';
+    return hfDownloadFileCommand(repo, file, directory, useHubCache);
 }
 /**
  * The chat template file the hf CLI pulls into the model directory. The
@@ -51,12 +107,115 @@ export const CHAT_TEMPLATE_FILE = 'chat_template.jinja';
 /**
  * hfChatTemplateCommand renders the hf CLI download for one chat template repo
  * reference into the model directory: the repo, the template file, and the
- * `--local-dir` target. The string is the single source the template download
- * route runs and the card shows beside its Download button and in the System
- * dependencies box when the auto-download is unavailable.
+ * `--local-dir` target. With the hub-cache layout (`useHubCache`), the
+ * `--local-dir` is dropped so the template lands in the hub cache's
+ * `models--{ns}--{name}` directory. The string is the single source the
+ * template download route runs and the card shows beside its Download button
+ * and in the System dependencies box when the auto-download is unavailable,
+ * rendered through hfDownloadFileCommand.
+ */
+export function hfChatTemplateCommand(repo, directory, useHubCache = false) {
+    return hfDownloadFileCommand(repo, CHAT_TEMPLATE_FILE, directory, useHubCache);
+}
+/**
+ * chatTemplateArtifactPath is the path the flat-layout chat-template presence
+ * check looks for: the template file joined onto the model directory. The
+ * hub-cache layout resolves through chatTemplatePresent instead (the
+ * deterministic snapshot pick), not through this join.
+ */
+export function chatTemplateArtifactPath(directory) {
+    return join(directory, CHAT_TEMPLATE_FILE);
+}
+/**
+ * modelArtifactPresent reports whether a model download source's artifact is
+ * on disk. With the hub-cache layout it resolves the deterministic hub-cache
+ * snapshot holding the file (the same pick the model-directory display uses),
+ * so a `blobs` folder left by any download never reads as present on its
+ * own; a blank `file` (a whole-repo download) reads the repo's snapshot
+ * directories. With the flat layout it checks the artifact path joined onto
+ * the base directory. `baseDir` is the hub cache root under the cache layout,
+ * the flat override otherwise.
+ */
+export function modelArtifactPresent(entry, baseDir, useHubCache = false) {
+    if (useHubCache) {
+        return hubCacheSnapshotFilePath(baseDir, repoIdFromUrl(entry.url), entry.file ?? '') !== null;
+    }
+    return existsSync(modelArtifactPath(entry, baseDir));
+}
+/**
+ * chatTemplatePresent reports whether a chat template repo's template file is
+ * on disk: the deterministic hub-cache snapshot pick under the hub-cache
+ * layout (a per-repo `snapshots` folder alone never reads as present), the
+ * flat file join otherwise. `baseDir` follows the modelArtifactPresent rule.
  */
-export function hfChatTemplateCommand(repo, directory) {
-    return `hf download ${repo} ${CHAT_TEMPLATE_FILE} --local-dir ${directory}`;
+export function chatTemplatePresent(repo, baseDir, useHubCache = false) {
+    if (useHubCache) {
+        return hubCacheSnapshotFilePath(baseDir, repo, CHAT_TEMPLATE_FILE) !== null;
+    }
+    return existsSync(chatTemplateArtifactPath(baseDir));
+}
+/**
+ * hubCacheSnapshotFilePath resolves the concrete file path of one file in the
+ * hub cache's snapshots, matching what the hf CLI treats as the active
+ * revision: the commit recorded in `refs/main` wins when its directory under
+ * `models--{ns}--{name}/snapshots/` holds the file; otherwise the snapshot
+ * with the newest mtime wins, covering a repo with no ref and a ref naming a
+ * commit that lacks the file. Ties break on readdir order. Returns null when
+ * no snapshot holds the file (the file is not downloaded), which the caller
+ * reads as absent. The `hubCache` is the hub cache root.
+ */
+export function hubCacheSnapshotFilePath(hubCache, repoId, file) {
+    const modelDir = hubCacheModelDirectory(repoId);
+    if (modelDir === '')
+        return null;
+    const modelRoot = join(hubCache, modelDir);
+    const snapshots = join(modelRoot, 'snapshots');
+    // The hf CLI writes the revision it last downloaded into refs/main; that
+    // commit is the cache's active one, so it outranks mtime.
+    const active = readHubCacheRef(join(modelRoot, 'refs', 'main'));
+    if (active !== '') {
+        const activePath = join(snapshots, active, file);
+        if (existsSync(activePath))
+            return activePath;
+    }
+    let commits;
+    try {
+        commits = readdirSync(snapshots);
+    }
+    catch {
+        return null;
+    }
+    let newestPath = null;
+    let newestMtime = -Infinity;
+    for (const commit of commits) {
+        const path = join(snapshots, commit, file);
+        if (!existsSync(path))
+            continue;
+        const snapshotDir = join(snapshots, commit);
+        let mtime;
+        try {
+            mtime = statSync(snapshotDir).mtimeMs;
+        }
+        catch {
+            // A directory that cannot be stat'ed mid-scan cannot win the pick.
+            continue;
+        }
+        if (mtime > newestMtime) {
+            newestMtime = mtime;
+            newestPath = path;
+        }
+    }
+    return newestPath;
+}
+// readHubCacheRef returns the commit the hf CLI ref file names, or '' when
+// the ref is absent or unreadable (a cache written by an older CLI).
+function readHubCacheRef(refPath) {
+    try {
+        return readFileSync(refPath, 'utf8').trim();
+    }
+    catch {
+        return '';
+    }
 }
 /**
  * modelEntriesForEngine filters a model directory listing down to the model
@@ -98,4 +257,37 @@ export function modelEntriesForEngine(entries, engineId) {
     }
     return names.sort();
 }
-//# sourceMappingURL=models.js.map
+/**
+ * modelCacheEntriesForEngine filters the hub cache's `models--*` directories
+ * down to the models the engine's Model dropdown offers, by the artifact types
+ * each engine serves: Basalt `.basalt`, NInfer `.ninfer`, Infernix
+ * `.ninfer`/`.infernix`, llama.cpp `.gguf`, Hyper-Qwen a repo holding a
+ * `.safetensors` weight file, and Strata `.gguf`/`.safetensors`. An engine with
+ * no matching cached model lists none. The result is the repo ids the
+ * dropdown shows, sorted for a stable order across summary fetches.
+ */
+export function modelCacheEntriesForEngine(entries, engineId) {
+    const serves = (files) => {
+        switch (engineId) {
+            case 'basalt':
+                return files.some((file) => file.endsWith('.basalt'));
+            case 'ninfer':
+                return files.some((file) => file.endsWith('.ninfer'));
+            case 'infernix':
+                return files.some((file) => file.endsWith('.ninfer') || file.endsWith('.infernix'));
+            case 'llamacpp':
+                return files.some((file) => file.endsWith('.gguf'));
+            case 'hyperqwen':
+                return files.some((file) => file.endsWith('.safetensors'));
+            case 'strata':
+                return files.some((file) => file.endsWith('.gguf') || file.endsWith('.safetensors'));
+            default:
+                return false;
+        }
+    };
+    return entries
+        .filter((entry) => serves(entry.files))
+        .map((entry) => entry.repoId)
+        .sort();
+}
+//# sourceMappingURL=models.js.map

package/packages/core/lib/parameter.d.ts

@@ -68,6 +68,29 @@ export type ParameterForm = {
     kind: 'combo';
     options: ComboOption[];
 };
+/**
+ * ParameterDeploy declares where a parameter's value lands at deploy time:
+ * on the command line, in the process environment, or in a config file the
+ * deploy step writes. A `config` target names the file format and the
+ * nesting path: `block` is the top-level key, `key` the leaf. The config-file
+ * renderer nests `toConfig(value)` (or the raw value) under that path. A
+ * `block` ending in `[]` (e.g. `models[]`) is the array-entry convention: the
+ * key lands inside the single object of a one-element array named by the
+ * prefix, and specs sharing that block merge into that one entry. A spec
+ * declares one target, or a list of targets when the value lands in more than
+ * one place (a Strata shared spec lands on the CLI in the binary mode and in
+ * the env in the docker mode).
+ */
+export type ParameterDeploy = {
+    target: 'cli';
+} | {
+    target: 'env';
+} | {
+    target: 'config';
+    format: 'json' | 'yaml' | 'env';
+    block?: string;
+    key?: string;
+};
 /**
  * ParameterSpec is the unit of parameter management: a declarative description
  * of one engine parameter. It is the object that makes the parameter-to-
@@ -77,8 +100,11 @@ export type ParameterForm = {
  * of adding these specs, never rewiring the core.
  *
  * `description` is behavior-first: it says what the parameter does to the run,
- * not what it is. `toArgv` and `toEnv` are the engine-specific spellings that
- * turn a value into a CLI flag or an environment variable.
+ * not what it is. `toArgv`, `toEnv`, and `toConfig` are the engine-specific
+ * spellings that turn a value into a CLI flag, an environment variable, or a
+ * config-file entry. `deploy` declares which spelling the deploy step uses;
+ * a list declares several, so one spec can serve more than one build mode
+ * (the flags in the binary mode and the env vars in the docker mode).
  */
 export interface ParameterSpec {
     key: string;
@@ -92,5 +118,7 @@ export interface ParameterSpec {
     requires?: (config: Config) => string | null;
     toArgv?: (value: unknown) => string[];
     toEnv?: (value: unknown) => [string, string];
+    toConfig?: (value: unknown) => unknown;
+    deploy?: ParameterDeploy | readonly ParameterDeploy[];
 }
-//# sourceMappingURL=parameter.d.ts.map
+//# sourceMappingURL=parameter.d.ts.map

package/packages/core/lib/parameter.js

@@ -1,2 +1,2 @@
 export {};
-//# sourceMappingURL=parameter.js.map
+//# sourceMappingURL=parameter.js.map

package/packages/core/lib/progress.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The pure hf (huggingface_hub) tqdm progress parser the get and launch routes
+ * share: it turns the raw tqdm stderr lines into a structured HfProgress
+ * state, so a route's onChunk sink (the download runner's streamed stderr)
+ * feeds the card's progress events without a node import. The parser
+ * recognizes the two tqdm bar shapes the hf CLI emits with `--format human`:
+ * the file-count bar (`Fetching 102 files: 42%|...| 43/102 [00:01<00:02,
+ * 20.5it/s]`, where the done/total fields carry file counts, not bytes) and
+ * the byte bar (`Downloading x.safetensors: 12% | 5.2G/43.5G [01:23<10:11,
+ * 72.3MB/s]`, where the done/total fields carry human byte sizes). It
+ * converts the human byte sizes to bytes and the `[elapsed<remaining, rate]`
+ * tail to remaining seconds, and marks the unit the done/total amounts carry
+ * (`'files'` for the file-count bar, `'bytes'` for the byte bar), so a
+ * readout renders the amounts in the unit the bar measured. The client
+ * package mirrors this parser in
+ * `packages/client/src/store/progress.ts` (the TASK-006 browser-side copy):
+ * the core package is not browser-safe, so the client bundle keeps its own
+ * copy and the two shapes (`HfProgress` and the client's `HfProgressShape`)
+ * must stay in sync when a tqdm bar shape changes.
+ * @module dsh-plugin-local-infer/core/progress
+ */
+/**
+ * HfProgress is the structured state one tqdm bar update folds to: the step
+ * label the bar names (the file, or the file-count fetch), the percent
+ * complete, the done and total amounts (bytes for the byte bar, file counts
+ * for the file-count bar), the remaining time in seconds (0 when the bar
+ * carries no tail), and the unit the done/total amounts carry ('bytes' for
+ * the byte bar, 'files' for the file-count bar), so a readout renders the
+ * amounts in the unit the bar measured.
+ */
+export interface HfProgress {
+    step: string;
+    percent: number;
+    doneBytes: number;
+    totalBytes: number;
+    etaSeconds: number;
+    unit: 'bytes' | 'files';
+}
+/**
+ * parseHfProgressLine parses one tqdm bar line into an HfProgress state, or
+ * undefined when the line is not a bar update (a plain log line, a command
+ * echo). It recognizes the file-count and byte shapes above.
+ */
+export declare function parseHfProgressLine(line: string): HfProgress | undefined;
+/**
+ * foldHfProgressChunk folds a raw stderr chunk into the latest HfProgress
+ * state it carries: the chunk splits on the line separators tqdm writes
+ * (carriage returns between bar redraws, newlines between steps), each line
+ * parses through parseHfProgressLine, and the last parseable line wins. A
+ * chunk with no bar update returns the prior state, so a caller threads the
+ * fold across chunks and always holds the newest state.
+ */
+export declare function foldHfProgressChunk(chunk: string, prior: HfProgress | undefined): HfProgress | undefined;
+//# sourceMappingURL=progress.d.ts.map

package/packages/core/lib/progress.js

@@ -0,0 +1,120 @@
+/**
+ * The pure hf (huggingface_hub) tqdm progress parser the get and launch routes
+ * share: it turns the raw tqdm stderr lines into a structured HfProgress
+ * state, so a route's onChunk sink (the download runner's streamed stderr)
+ * feeds the card's progress events without a node import. The parser
+ * recognizes the two tqdm bar shapes the hf CLI emits with `--format human`:
+ * the file-count bar (`Fetching 102 files: 42%|...| 43/102 [00:01<00:02,
+ * 20.5it/s]`, where the done/total fields carry file counts, not bytes) and
+ * the byte bar (`Downloading x.safetensors: 12% | 5.2G/43.5G [01:23<10:11,
+ * 72.3MB/s]`, where the done/total fields carry human byte sizes). It
+ * converts the human byte sizes to bytes and the `[elapsed<remaining, rate]`
+ * tail to remaining seconds, and marks the unit the done/total amounts carry
+ * (`'files'` for the file-count bar, `'bytes'` for the byte bar), so a
+ * readout renders the amounts in the unit the bar measured. The client
+ * package mirrors this parser in
+ * `packages/client/src/store/progress.ts` (the TASK-006 browser-side copy):
+ * the core package is not browser-safe, so the client bundle keeps its own
+ * copy and the two shapes (`HfProgress` and the client's `HfProgressShape`)
+ * must stay in sync when a tqdm bar shape changes.
+ * @module dsh-plugin-local-infer/core/progress
+ */
+// The file-count bar: `Fetching 102 files: 42%|...| 43/102 [00:01<00:02, ...]`.
+// The bar glyph run between the pipes is skipped, and the counts are plain
+// integers.
+const FILES_LINE = /^Fetching (\d+) files:\s*(\d+(?:\.\d+)?)%\|[^|]*\|\s*(\d+)\s*\/\s*(\d+)(?:\s*\[([^\]]*)\])?/;
+// The byte bar: `Downloading x.safetensors: 12% | 5.2G/43.5G [01:23<10:11, ...]`.
+// The sizes carry an optional K/M/G/T/P unit (decimal, or binary with an
+// `i`), and the tail is optional (a finished bar drops it).
+const BYTES_LINE = /^(?:Downloading|Fetching)\s+([^:]+):\s*(\d+(?:\.\d+)?)%\s*\|\s*(\d+(?:\.\d+)?[KMGTP]?i?B?)\s*\/\s*(\d+(?:\.\d+)?[KMGTP]?i?B?)\s*(?:\[([^\]]*)\])?/;
+// The unit exponents for the decimal (1000-based) sizes the hf CLI's tqdm
+// renders; a binary `i` suffix (Gi, Mi, ...) switches the base to 1024.
+const UNIT_EXPONENTS = { K: 1, M: 2, G: 3, T: 4, P: 5 };
+// parseHumanSize converts one human byte size (`5.2G`) to bytes: the decimal
+// base the hf CLI's tqdm uses, with a 1024 base when the unit carries the
+// binary `i` suffix. A size with no unit is a plain byte count.
+function parseHumanSize(text) {
+    const match = /^(\d+(?:\.\d+)?)([KMGTP]?)i?B?$/.exec(text);
+    if (match === null)
+        return 0;
+    const exponent = UNIT_EXPONENTS[match[2]] ?? 0;
+    const base = text.includes('i') ? 1024 : 1000;
+    return Number(match[1]) * base ** exponent;
+}
+// durationSeconds converts a `MM:SS`, `H:MM:SS`, or `D:H:MM:SS` clock string
+// to seconds, the tqdm tail's remaining-time format.
+function durationSeconds(text) {
+    let seconds = 0;
+    for (const part of text.split(':')) {
+        seconds = seconds * 60 + Number(part);
+    }
+    return seconds;
+}
+// etaSecondsFromTail reads the remaining time out of a tqdm tail
+// (`01:23<10:11, 72.3MB/s`): the clock string after the `<`, 0 when the tail
+// is absent or carries no remaining time.
+function etaSecondsFromTail(tail) {
+    if (tail === undefined)
+        return 0;
+    const match = /<\s*(\d+(?::\d+)+)/.exec(tail);
+    if (match === null)
+        return 0;
+    return durationSeconds(match[1]);
+}
+/**
+ * parseHfProgressLine parses one tqdm bar line into an HfProgress state, or
+ * undefined when the line is not a bar update (a plain log line, a command
+ * echo). It recognizes the file-count and byte shapes above.
+ */
+export function parseHfProgressLine(line) {
+    const trimmed = line.trim();
+    if (trimmed === '')
+        return undefined;
+    const files = FILES_LINE.exec(trimmed);
+    if (files !== null) {
+        // The file-count bar carries counts, not bytes: the done/total fields
+        // hold the file numbers, the step label names the fetch, and the unit
+        // marks the amounts as file counts, so a readout renders them as files.
+        return {
+            step: `Fetching ${files[1]} files`,
+            percent: Number(files[2]),
+            doneBytes: Number(files[3]),
+            totalBytes: Number(files[4]),
+            etaSeconds: etaSecondsFromTail(files[5]),
+            unit: 'files',
+        };
+    }
+    const bytes = BYTES_LINE.exec(trimmed);
+    if (bytes !== null) {
+        const verb = trimmed.startsWith('Fetching') ? 'Fetching' : 'Downloading';
+        // The byte bar carries human byte sizes: the done/total fields hold the
+        // parsed byte counts, and the unit marks the amounts as bytes.
+        return {
+            step: `${verb} ${bytes[1].trim()}`,
+            percent: Number(bytes[2]),
+            doneBytes: parseHumanSize(bytes[3]),
+            totalBytes: parseHumanSize(bytes[4]),
+            etaSeconds: etaSecondsFromTail(bytes[5]),
+            unit: 'bytes',
+        };
+    }
+    return undefined;
+}
+/**
+ * foldHfProgressChunk folds a raw stderr chunk into the latest HfProgress
+ * state it carries: the chunk splits on the line separators tqdm writes
+ * (carriage returns between bar redraws, newlines between steps), each line
+ * parses through parseHfProgressLine, and the last parseable line wins. A
+ * chunk with no bar update returns the prior state, so a caller threads the
+ * fold across chunks and always holds the newest state.
+ */
+export function foldHfProgressChunk(chunk, prior) {
+    let folded = prior;
+    for (const line of chunk.split(/\r\n|\r|\n/)) {
+        const parsed = parseHfProgressLine(line);
+        if (parsed !== undefined)
+            folded = parsed;
+    }
+    return folded;
+}
+//# sourceMappingURL=progress.js.map