@dreamlake/ml-dash 0.1.0

package/dist/local/storage.js

@@ -0,0 +1,447 @@
+/**
+ * The `.dash` directory on disk — the same tree the Python SDK writes.
+ *
+ *   .dash/{owner}/{project}/{folders…}/{experiment}/
+ *     experiment.json
+ *     parameters.json
+ *     logs/logs.jsonl          + .log_sequence
+ *     metrics/{name}/data.jsonl + metadata.json   ← current layout
+ *     metrics/{name}.jsonl                        ← legacy layout
+ *     files/{path}/{file_id}/{filename}
+ *     files/.files_metadata.json
+ *
+ * Both metric layouts are read. The Python SDK still writes the legacy flat
+ * form from `write_metric_data`, while its CLI's discovery only ever looked for
+ * the `metrics/<name>/data.jsonl` layout — so an experiment recorded through that path uploaded
+ * as "successful" with none of its metrics. Reading both is a deliberate
+ * divergence from the Python CLI, recorded in docs/PORTING.md.
+ */
+import { createHash } from "node:crypto";
+import { appendFileSync, createReadStream, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { copyFile } from "node:fs/promises";
+import path from "node:path";
+import { literal, resolveUnderRoot } from "./safe-path.js";
+export const FILES_METADATA_FILENAME = ".files_metadata.json";
+export const utcNowIso = () => new Date().toISOString().replace(/Z$/, "Z");
+/** Local-mode ID, matching the Python `(ms << 12) | rand12` shape. */
+export function generateSnowflakeId() {
+    const ms = BigInt(Date.now());
+    const rand = BigInt(Math.floor(Math.random() * 4096));
+    return ((ms << 12n) | rand).toString();
+}
+export function sha256File(filePath) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash("sha256");
+        createReadStream(filePath)
+            .on("error", reject)
+            .on("data", (c) => hash.update(c))
+            .on("end", () => resolve(hash.digest("hex")));
+    });
+}
+export class LocalStorage {
+    rootPath;
+    constructor(rootPath) {
+        const resolved = path.resolve(rootPath);
+        mkdirSync(resolved, { recursive: true });
+        // The root is the one path the user picked deliberately, so following its
+        // own links is what they asked for; everything below it is checked
+        // against this canonical form.
+        this.rootPath = realpathSync(resolved);
+    }
+    /**
+     * The single boundary: every path this class touches is built here, from
+     * the root down, with the server-supplied parts and the literal ones
+     * checked alike. A derived directory is never treated as a new root.
+     */
+    target(parts, mode = "write") {
+        return resolveUnderRoot(this.rootPath, parts, mode);
+    }
+    static prefixPart = (prefix) => ({
+        label: "experiment prefix",
+        value: prefix,
+        nested: true,
+    });
+    /**
+     * Experiment directory for a prefix of the form owner/project/folders…/name.
+     *
+     * Read mode: callers outside this class use it to look, and `upload` has to
+     * keep working on a tree where the user symlinked their own data. Every
+     * write below goes through `target(…, "write")` instead.
+     */
+    experimentDir(prefix) {
+        return this.target([LocalStorage.prefixPart(prefix)], "read");
+    }
+    /** Same directory, as a write target. */
+    experimentWriteDir(prefix) {
+        return this.target([LocalStorage.prefixPart(prefix)]);
+    }
+    // ── experiment metadata ────────────────────────────────────────────────────
+    /**
+     * Create or merge experiment.json. Existing files are merged, never
+     * clobbered, so a download into a populated tree does not discard fields the
+     * server did not return.
+     */
+    createExperiment(args) {
+        const prefixClean = args.prefix.replace(/\/+$/, "");
+        const dir = this.experimentWriteDir(prefixClean);
+        mkdirSync(dir, { recursive: true });
+        for (const sub of ["logs", "metrics", "files"]) {
+            mkdirSync(this.target([LocalStorage.prefixPart(prefixClean), literal(sub)]), { recursive: true });
+        }
+        const name = prefixClean.split("/").pop();
+        const file = this.target([LocalStorage.prefixPart(prefixClean), literal("experiment.json")]);
+        if (!existsSync(file)) {
+            writeFileSync(file, JSON.stringify({
+                name,
+                project: args.project,
+                description: args.description ?? null,
+                tags: args.tags ?? [],
+                bindrs: args.bindrs ?? [],
+                prefix: args.prefix,
+                metadata: args.metadata ?? null,
+                created_at: utcNowIso(),
+                write_protected: false,
+            }));
+            return dir;
+        }
+        let existing;
+        try {
+            existing = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            // Corrupt or truncated — rewrite rather than fail the whole download.
+            writeFileSync(file, JSON.stringify({
+                name,
+                project: args.project,
+                description: args.description ?? null,
+                tags: args.tags ?? [],
+                bindrs: args.bindrs ?? [],
+                prefix: args.prefix,
+                metadata: args.metadata ?? null,
+                created_at: utcNowIso(),
+                write_protected: false,
+            }));
+            return dir;
+        }
+        if (args.description != null)
+            existing.description = args.description;
+        if (args.tags != null)
+            existing.tags = args.tags;
+        if (args.bindrs != null)
+            existing.bindrs = args.bindrs;
+        if (args.prefix != null)
+            existing.prefix = args.prefix;
+        if (args.metadata != null)
+            existing.metadata = args.metadata;
+        existing.updated_at = utcNowIso();
+        writeFileSync(file, JSON.stringify(existing));
+        return dir;
+    }
+    readExperiment(prefix) {
+        const file = this.target([LocalStorage.prefixPart(prefix), literal("experiment.json")], "read");
+        if (!existsSync(file))
+            return null;
+        try {
+            return JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    // ── parameters ─────────────────────────────────────────────────────────────
+    /** Merge into parameters.json, bumping `version` the way the SDK does. */
+    writeParameters(prefix, data) {
+        mkdirSync(this.experimentWriteDir(prefix), { recursive: true });
+        const file = this.target([LocalStorage.prefixPart(prefix), literal("parameters.json")]);
+        let merged = {};
+        let version = 1;
+        if (existsSync(file)) {
+            try {
+                const doc = JSON.parse(readFileSync(file, "utf8"));
+                if (doc && typeof doc === "object") {
+                    merged = (doc.data && typeof doc.data === "object" ? doc.data : doc);
+                    version = typeof doc.version === "number" ? doc.version + 1 : 2;
+                }
+            }
+            catch {
+                merged = {};
+            }
+        }
+        writeFileSync(file, JSON.stringify({ version, data: { ...merged, ...data }, updatedAt: utcNowIso() }));
+    }
+    /** Read parameters, accepting both the versioned and the bare-dict shapes. */
+    readParameters(prefix) {
+        const file = this.target([LocalStorage.prefixPart(prefix), literal("parameters.json")], "read");
+        if (!existsSync(file))
+            return null;
+        try {
+            const doc = JSON.parse(readFileSync(file, "utf8"));
+            if (!doc || typeof doc !== "object" || Array.isArray(doc))
+                return null;
+            if ("data" in doc) {
+                return doc.data && typeof doc.data === "object" ? doc.data : null;
+            }
+            return doc;
+        }
+        catch {
+            return null;
+        }
+    }
+    // ── logs ───────────────────────────────────────────────────────────────────
+    /**
+     * Append log entries, continuing the `.log_sequence` counter so downloaded
+     * logs interleave correctly with anything already recorded locally.
+     */
+    appendLogs(prefix, entries) {
+        if (entries.length === 0)
+            return 0;
+        const logsDir = this.target([LocalStorage.prefixPart(prefix), literal("logs")]);
+        mkdirSync(logsDir, { recursive: true });
+        const logsFile = this.target([LocalStorage.prefixPart(prefix), literal("logs"), literal("logs.jsonl")]);
+        const seqFile = this.target([LocalStorage.prefixPart(prefix), literal("logs"), literal(".log_sequence")]);
+        let sequence = 0;
+        if (existsSync(seqFile)) {
+            const parsed = Number.parseInt(readFileSync(seqFile, "utf8").trim(), 10);
+            if (Number.isFinite(parsed))
+                sequence = parsed;
+        }
+        let out = "";
+        for (const e of entries) {
+            const record = {
+                sequenceNumber: sequence++,
+                timestamp: e.timestamp ?? "",
+                level: e.level ?? "info",
+                message: e.message,
+            };
+            if (e.metadata)
+                record.metadata = e.metadata;
+            out += JSON.stringify(record) + "\n";
+        }
+        appendFileSync(logsFile, out);
+        writeFileSync(seqFile, String(sequence));
+        return entries.length;
+    }
+    readLogs(prefix) {
+        const file = this.target([LocalStorage.prefixPart(prefix), literal("logs"), literal("logs.jsonl")], "read");
+        if (!existsSync(file))
+            return [];
+        const out = [];
+        for (const line of readFileSync(file, "utf8").split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                /* skipped, as the Python uploader skipped unparseable lines */
+            }
+        }
+        return out;
+    }
+    // ── metrics ────────────────────────────────────────────────────────────────
+    /**
+     * Every metric in the experiment, from both layouts.
+     *
+     * A name present in both is reported once, from the directory layout, which
+     * is the one the current SDK writes and the one that carries an index.
+     */
+    listMetrics(prefix) {
+        const metricsDir = this.target([LocalStorage.prefixPart(prefix), literal("metrics")], "read");
+        if (!existsSync(metricsDir))
+            return [];
+        const found = new Map();
+        for (const entry of readdirSync(metricsDir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                const dataFile = path.join(metricsDir, entry.name, "data.jsonl");
+                if (existsSync(dataFile)) {
+                    found.set(entry.name, { name: entry.name, layout: "directory", dataFile });
+                }
+            }
+        }
+        for (const entry of readdirSync(metricsDir, { withFileTypes: true })) {
+            if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+                const name = entry.name.slice(0, -".jsonl".length);
+                if (!found.has(name)) {
+                    found.set(name, { name, layout: "flat", dataFile: path.join(metricsDir, entry.name) });
+                }
+            }
+        }
+        return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    /**
+     * Read one metric's data points as the values the server wants.
+     *
+     * Both layouts store one JSON object per line with the point under `data`;
+     * the directory layout adds `index` and `createdAt`. Lines without `data`
+     * are skipped and counted, never uploaded as `undefined`.
+     */
+    readMetricPoints(metric) {
+        const points = [];
+        let skipped = 0;
+        let bytes = 0;
+        if (!existsSync(metric.dataFile))
+            return { points, skipped, bytes };
+        for (const line of readFileSync(metric.dataFile, "utf8").split("\n")) {
+            if (!line.trim())
+                continue;
+            bytes += Buffer.byteLength(line, "utf8");
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed === null || typeof parsed !== "object" || !("data" in parsed)) {
+                    skipped++;
+                    continue;
+                }
+                points.push(parsed.data);
+            }
+            catch {
+                skipped++;
+            }
+        }
+        return { points, skipped, bytes };
+    }
+    /** Append points in the directory layout, maintaining index and counts. */
+    appendBatchToMetric(prefix, metricName, dataPoints) {
+        const dirName = metricName === null ? "None" : String(metricName);
+        // A nested name ('train/loss') keeps nesting; '..' in one does not. Every
+        // part, including 'metrics' and the two filenames, is checked from the
+        // root — `metrics` being a link out of the tree is the case a check
+        // anchored at the metrics directory could not see.
+        const metricParts = [
+            LocalStorage.prefixPart(prefix),
+            literal("metrics"),
+            { label: "metric name", value: dirName, nested: true },
+        ];
+        const metricDir = this.target(metricParts);
+        mkdirSync(metricDir, { recursive: true });
+        const dataFile = this.target([...metricParts, literal("data.jsonl")]);
+        const metadataFile = this.target([...metricParts, literal("metadata.json")]);
+        let meta = {
+            metricId: `local-metric-${metricName}`,
+            name: metricName,
+            description: null,
+            tags: [],
+            metadata: null,
+            totalDataPoints: 0,
+            nextIndex: 0,
+            createdAt: utcNowIso(),
+        };
+        if (existsSync(metadataFile)) {
+            try {
+                meta = JSON.parse(readFileSync(metadataFile, "utf8"));
+            }
+            catch {
+                /* reinitialise from the default above */
+            }
+        }
+        const startIndex = meta.nextIndex ?? 0;
+        const batchTs = utcNowIso();
+        let out = "";
+        dataPoints.forEach((data, i) => {
+            out += JSON.stringify({ index: startIndex + i, data, createdAt: batchTs }) + "\n";
+        });
+        if (out)
+            appendFileSync(dataFile, out);
+        meta.nextIndex = startIndex + dataPoints.length;
+        meta.totalDataPoints = (meta.totalDataPoints ?? 0) + dataPoints.length;
+        meta.updatedAt = batchTs;
+        writeFileSync(metadataFile, JSON.stringify(meta));
+    }
+    // ── files ──────────────────────────────────────────────────────────────────
+    filesDir(prefix, mode = "write") {
+        return this.target([LocalStorage.prefixPart(prefix), literal("files")], mode);
+    }
+    /** The parts of a stored file's path, from the root down. */
+    fileParts(prefix, sub, ...rest) {
+        const parts = [LocalStorage.prefixPart(prefix), literal("files")];
+        // Python's storage lstrips a leading separator here; anything else in the
+        // path is checked rather than repaired.
+        const normalized = (sub ?? "").replace(/^\/+/, "");
+        if (normalized)
+            parts.push({ label: "file path", value: normalized, nested: true });
+        return [...parts, ...rest];
+    }
+    loadFilesMetadata(prefix) {
+        const file = this.target([LocalStorage.prefixPart(prefix), literal("files"), literal(FILES_METADATA_FILENAME)], "read");
+        if (!existsSync(file))
+            return { files: [] };
+        try {
+            const parsed = JSON.parse(readFileSync(file, "utf8"));
+            return Array.isArray(parsed?.files) ? parsed : { files: [] };
+        }
+        catch {
+            return { files: [] };
+        }
+    }
+    saveFilesMetadata(prefix, data) {
+        mkdirSync(this.filesDir(prefix), { recursive: true });
+        const file = this.target([LocalStorage.prefixPart(prefix), literal("files"), literal(FILES_METADATA_FILENAME)]);
+        // Write-then-rename: a crash mid-write would otherwise leave the manifest
+        // unparseable and orphan every file it listed. The temporary name is a
+        // target of its own, so a planted link cannot catch the write either.
+        const tmp = this.target([
+            LocalStorage.prefixPart(prefix),
+            literal("files"),
+            literal(`${FILES_METADATA_FILENAME}.tmp-${process.pid}`),
+        ]);
+        writeFileSync(tmp, JSON.stringify(data));
+        renameSync(tmp, file);
+    }
+    /** Non-deleted file records for an experiment. */
+    listFiles(prefix, pathPrefix, tags) {
+        let files = this.loadFilesMetadata(prefix).files.filter((f) => f.deletedAt === null);
+        if (pathPrefix)
+            files = files.filter((f) => (f.path ?? "").startsWith(pathPrefix));
+        if (tags?.length) {
+            const wanted = new Set(tags);
+            files = files.filter((f) => (f.tags ?? []).some((t) => wanted.has(t)));
+        }
+        return files;
+    }
+    /** Absolute on-disk path of a recorded file. */
+    filePath(prefix, record) {
+        return this.target(this.fileParts(prefix, record.path ?? "", { label: "file id", value: String(record.id) }, { label: "filename", value: record.filename }), "read");
+    }
+    /** Copy a file in and record it, replacing any record with the same path+filename. */
+    async writeFile(args) {
+        const fileId = generateSnowflakeId();
+        const idPart = { label: "file id", value: fileId };
+        const namePart = { label: "filename", value: args.filename };
+        const fileDir = this.target(this.fileParts(args.prefix, args.path ?? "", idPart));
+        const destination = this.target(this.fileParts(args.prefix, args.path ?? "", idPart, namePart));
+        const filename = args.filename;
+        mkdirSync(fileDir, { recursive: true });
+        await copyFile(args.sourcePath, destination);
+        const now = utcNowIso();
+        const record = {
+            id: fileId,
+            experimentId: `${args.project}/${args.prefix}`,
+            path: args.path ?? "",
+            filename,
+            description: args.description ?? null,
+            tags: args.tags ?? [],
+            bindrs: args.bindrs ?? [],
+            contentType: args.contentType ?? "",
+            sizeBytes: args.sizeBytes ?? statSync(destination).size,
+            checksum: args.checksum ?? "",
+            metadata: args.metadata ?? null,
+            uploadedAt: now,
+            updatedAt: now,
+            deletedAt: null,
+        };
+        const meta = this.loadFilesMetadata(args.prefix);
+        const existingIndex = meta.files.findIndex((f) => f.path === record.path && f.filename === record.filename && f.deletedAt === null);
+        if (existingIndex >= 0) {
+            const old = meta.files[existingIndex];
+            // Only the directory this manifest created for that record, and only
+            // if every component of it is a real directory under the root: never a
+            // link the record could point at something else through.
+            rmSync(this.target(this.fileParts(args.prefix, old.path ?? "", { label: "file id", value: String(old.id) })), { recursive: true, force: true });
+            meta.files[existingIndex] = record;
+        }
+        else {
+            meta.files.push(record);
+        }
+        this.saveFilesMetadata(args.prefix, meta);
+        return record;
+    }
+}

package/dist/util/ansi.js

@@ -0,0 +1,78 @@
+/**
+ * Minimal ANSI styling + table rendering.
+ *
+ * The Python CLI used `rich`. Porting `rich` wholesale would drag a rendering
+ * engine into a single-file binary for the sake of a handful of tables, so the
+ * subset that the CLI actually uses lives here instead: colours, a box table,
+ * and a panel. Colour is suppressed when stdout is not a TTY or NO_COLOR is
+ * set, so piping `ml-dash list` into a file yields plain text.
+ */
+const enabled = () => {
+    if (process.env.NO_COLOR !== undefined)
+        return false;
+    if (process.env.FORCE_COLOR !== undefined)
+        return true;
+    return process.stdout.isTTY === true;
+};
+const wrap = (code, close) => (s) => enabled() ? `\u001b[${code}m${s}\u001b[${close}m` : s;
+export const bold = wrap(1, 22);
+export const dim = wrap(2, 22);
+export const red = wrap(31, 39);
+export const green = wrap(32, 39);
+export const yellow = wrap(33, 39);
+export const blue = wrap(34, 39);
+export const cyan = wrap(36, 39);
+/** Visible width, ignoring the escape sequences the styles above insert. */
+export const visibleWidth = (s) => 
+// eslint-disable-next-line no-control-regex
+s.replace(/\u001b\[[0-9;]*m/g, "").length;
+const pad = (s, width, align) => {
+    const gap = Math.max(0, width - visibleWidth(s));
+    if (align === "right")
+        return " ".repeat(gap) + s;
+    if (align === "center") {
+        const l = Math.floor(gap / 2);
+        return " ".repeat(l) + s + " ".repeat(gap - l);
+    }
+    return s + " ".repeat(gap);
+};
+/** Rounded-box table, the same shape `rich.box.ROUNDED` produced. */
+export function renderTable(columns, rows, opts = {}) {
+    const widths = columns.map((c, i) => Math.max(visibleWidth(c.header), ...rows.map((r) => visibleWidth(r[i] ?? ""))));
+    const line = (l, m, r) => l + widths.map((w) => "─".repeat(w + 2)).join(m) + r;
+    const out = [];
+    if (opts.title)
+        out.push(bold(opts.title));
+    out.push(line("╭", "┬", "╮"));
+    out.push("│ " + columns.map((c, i) => pad(bold(c.header), widths[i], c.align ?? "left")).join(" │ ") + " │");
+    out.push(line("├", "┼", "┤"));
+    for (const row of rows) {
+        out.push("│ " + columns.map((c, i) => pad(row[i] ?? "", widths[i], c.align ?? "left")).join(" │ ") + " │");
+    }
+    out.push(line("╰", "┴", "╯"));
+    if (opts.caption)
+        out.push(dim(opts.caption));
+    return out.join("\n");
+}
+/** Bordered panel, the shape `rich.panel.Panel` produced. */
+export function renderPanel(body, opts = {}) {
+    const lines = body.split("\n");
+    const width = Math.max(...lines.map(visibleWidth), opts.title ? visibleWidth(opts.title) + 2 : 0);
+    const top = opts.title
+        ? "╭─ " + opts.title + " " + "─".repeat(Math.max(0, width - visibleWidth(opts.title) - 1)) + "╮"
+        : "╭" + "─".repeat(width + 2) + "╮";
+    const out = [top];
+    for (const l of lines)
+        out.push("│ " + pad(l, width, "left") + " │");
+    out.push("╰" + "─".repeat(width + 2) + "╯");
+    return out.join("\n");
+}
+export function formatBytes(n) {
+    let v = n;
+    for (const unit of ["B", "KB", "MB", "GB"]) {
+        if (v < 1024)
+            return `${v.toFixed(2)} ${unit}`;
+        v /= 1024;
+    }
+    return `${v.toFixed(2)} TB`;
+}

package/dist/util/glob.js

@@ -0,0 +1,47 @@
+/**
+ * fnmatch-compatible globbing.
+ *
+ * The Python CLI matched local experiment paths with `fnmatch.fnmatch` and let
+ * the server match remote ones. Both accept `*`, `?` and `[...]` classes, and
+ * — unlike shell globbing — `*` crosses `/`. A path-aware matcher would quietly
+ * change which experiments a pattern like `tom/<any>/exp<any>` selects, so this deliberately
+ * reproduces fnmatch's flat semantics.
+ */
+export function fnmatch(name, pattern) {
+    return fnmatchToRegExp(pattern).test(name);
+}
+export function fnmatchToRegExp(pattern) {
+    let out = "";
+    let i = 0;
+    while (i < pattern.length) {
+        const c = pattern[i++];
+        if (c === "*")
+            out += ".*";
+        else if (c === "?")
+            out += ".";
+        else if (c === "[") {
+            let j = i;
+            if (j < pattern.length && (pattern[j] === "!" || pattern[j] === "^"))
+                j++;
+            if (j < pattern.length && pattern[j] === "]")
+                j++;
+            while (j < pattern.length && pattern[j] !== "]")
+                j++;
+            if (j >= pattern.length) {
+                out += "\\[";
+            }
+            else {
+                let body = pattern.slice(i, j);
+                if (body.startsWith("!") || body.startsWith("^"))
+                    body = "^" + body.slice(1);
+                out += "[" + body.replace(/\\/g, "\\\\") + "]";
+                i = j + 1;
+            }
+        }
+        else {
+            out += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+        }
+    }
+    return new RegExp(`^${out}$`, "s");
+}
+export const hasWildcard = (s) => /[*?[]/.test(s);

package/dist/util/json.js

@@ -0,0 +1,70 @@
+/**
+ * JSON parsing that does not destroy Snowflake IDs.
+ *
+ * ml-dash node, experiment, project and file IDs are 64-bit Snowflakes. The
+ * server sends most of them as JSON strings, but not all — `upload_file`'s
+ * response and some GraphQL paths hand back bare numbers. `JSON.parse` turns
+ * those into IEEE-754 doubles, and a 19-digit Snowflake loses its last two or
+ * three digits in the process. Nothing throws: the ID simply comes back
+ * slightly wrong, and the 404 surfaces later at an unrelated call.
+ *
+ * So numbers that cannot survive a round trip are quoted before parsing, and
+ * every ID stays a string end to end.
+ */
+/** Rewrite unsafe integer literals as strings, leaving strings and floats alone. */
+export function preserveBigIntegers(text) {
+    let out = "";
+    let i = 0;
+    const n = text.length;
+    while (i < n) {
+        const c = text[i];
+        if (c === '"') {
+            // Copy the string literal verbatim — digits inside it are not numbers.
+            const start = i++;
+            while (i < n) {
+                if (text[i] === "\\")
+                    i += 2;
+                else if (text[i] === '"') {
+                    i++;
+                    break;
+                }
+                else
+                    i++;
+            }
+            out += text.slice(start, i);
+            continue;
+        }
+        if (c === "-" || (c >= "0" && c <= "9")) {
+            const start = i;
+            if (text[i] === "-")
+                i++;
+            while (i < n && text[i] >= "0" && text[i] <= "9")
+                i++;
+            const isInteger = !(i < n && (text[i] === "." || text[i] === "e" || text[i] === "E"));
+            while (i < n && /[0-9.eE+-]/.test(text[i]))
+                i++;
+            const literal = text.slice(start, i);
+            // Only integers, and only those outside the exactly-representable range.
+            out += isInteger && !Number.isSafeInteger(Number(literal)) ? `"${literal}"` : literal;
+            continue;
+        }
+        out += c;
+        i++;
+    }
+    return out;
+}
+export function parseJson(text) {
+    return JSON.parse(preserveBigIntegers(text));
+}
+/** Coerce whatever the server sent for an ID into a string, losslessly. */
+export function asId(v) {
+    if (v === null || v === undefined)
+        return undefined;
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "number")
+        return String(v);
+    if (typeof v === "bigint")
+        return v.toString();
+    return String(v);
+}

package/dist/util/pool.js

@@ -0,0 +1,30 @@
+/**
+ * A bounded-concurrency task runner.
+ *
+ * The Python CLI used `ThreadPoolExecutor(max_workers=N)` for metrics, chunks
+ * and files. Node has no threads to pool, but the limit still matters: it is
+ * what stops an experiment with 400 metrics from opening 400 sockets at once
+ * and having the server start refusing them. Results come back in submission
+ * order so a caller can pair them with its inputs; failures are returned, not
+ * thrown, because one bad metric must not abandon the rest of the batch.
+ */
+export async function runPool(items, limit, worker) {
+    const results = new Array(items.length);
+    const width = Math.max(1, Math.min(limit, items.length));
+    let cursor = 0;
+    const runners = Array.from({ length: width }, async () => {
+        for (;;) {
+            const index = cursor++;
+            if (index >= items.length)
+                return;
+            try {
+                results[index] = { value: await worker(items[index], index) };
+            }
+            catch (e) {
+                results[index] = { error: e instanceof Error ? e : new Error(String(e)) };
+            }
+        }
+    });
+    await Promise.all(runners);
+    return results;
+}

package/dist/version.js

@@ -0,0 +1,3 @@
+// Rewritten by scripts/build-release.ts at release time so a compiled binary
+// can never misreport itself. The npm channel reads the same constant.
+export const VERSION = "0.1.0";