@dreamlake/ml-dash 0.1.0

package/dist/client.js

@@ -0,0 +1,588 @@
+/**
+ * The ml-dash server client: REST under `{url}/api`, GraphQL at `{url}/graphql`,
+ * both bearing the same token.
+ *
+ * Everything moves through the server — there is no S3 direct upload, no
+ * presigned URL and no multipart chunking in this protocol. Files go up as one
+ * `multipart/form-data` POST to the unified node endpoint and come down from
+ * `/api/nodes/{id}/download`.
+ */
+import { createWriteStream } from "node:fs";
+import { open, stat } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { asId, parseJson } from "./util/json.js";
+export class AuthenticationError extends Error {
+}
+export class ConfigurationError extends Error {
+}
+export class NetworkError extends Error {
+}
+export class StorageError extends Error {
+}
+export class HttpError extends Error {
+    status;
+    url;
+    body;
+    constructor(status, url, body) {
+        super(`HTTP ${status} for ${url}: ${body.slice(0, 500)}`);
+        this.status = status;
+        this.url = url;
+        this.body = body;
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class RemoteClient {
+    graphqlBaseUrl;
+    baseUrl;
+    apiKey;
+    _namespace;
+    idCache = new Map();
+    constructor(baseUrl, namespace, apiKey) {
+        this.graphqlBaseUrl = baseUrl.replace(/\/+$/, "");
+        this.baseUrl = `${this.graphqlBaseUrl}/api`;
+        this._namespace = namespace;
+        this.apiKey = apiKey;
+    }
+    ensureAuthenticated() {
+        if (!this.apiKey) {
+            throw new AuthenticationError("Not authenticated. Run 'ml-dash login' to authenticate, or provide an explicit api key.");
+        }
+    }
+    /** The caller's namespace, asked of the server once and then remembered. */
+    async namespace() {
+        if (this._namespace)
+            return this._namespace;
+        const result = await this.graphqlQuery(`query GetMyNamespace { me { username } }`);
+        const username = result?.me?.username;
+        if (!username)
+            throw new NetworkError("Failed to fetch namespace from server");
+        this._namespace = username;
+        return username;
+    }
+    // ── transport ──────────────────────────────────────────────────────────────
+    async request(pathname, opts = {}) {
+        this.ensureAuthenticated();
+        const url = new URL(`${this.baseUrl}/${pathname.replace(/^\/+/, "")}`);
+        for (const [k, v] of Object.entries(opts.params ?? {})) {
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        }
+        const headers = { Authorization: `Bearer ${this.apiKey}` };
+        let body;
+        if (opts.json !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(opts.json);
+        }
+        else if (opts.form) {
+            body = opts.form; // fetch sets the multipart boundary itself
+        }
+        const res = await fetch(url, {
+            method: opts.method ?? "GET",
+            headers,
+            body,
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 30_000),
+        });
+        if (opts.raw)
+            return res;
+        if (!res.ok)
+            throw new HttpError(res.status, url.toString(), await res.text());
+        return res;
+    }
+    async requestJson(pathname, opts = {}) {
+        const res = await this.request(pathname, opts);
+        const text = await res.text();
+        return text ? parseJson(text) : {};
+    }
+    /**
+     * POST that retries a 409.
+     *
+     * Node upserts are a pre-check followed by a create, so two concurrent
+     * requests can both pass the check and one comes back 409. Retrying is safe:
+     * the second attempt finds the node the first one created.
+     */
+    async postWith409Retry(pathname, opts) {
+        const backoff = [100, 500, 2000];
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const res = await this.request(pathname, { ...opts, method: "POST", raw: true });
+            if (res.status !== 409) {
+                if (!res.ok)
+                    throw new HttpError(res.status, pathname, await res.text());
+                const text = await res.text();
+                return text ? parseJson(text) : {};
+            }
+            await res.text();
+            if (attempt < 2)
+                await sleep(backoff[attempt]);
+        }
+        throw new HttpError(409, pathname, "node creation still conflicting after 3 attempts");
+    }
+    async graphqlQuery(query, variables = {}) {
+        this.ensureAuthenticated();
+        const res = await fetch(`${this.graphqlBaseUrl}/graphql`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" },
+            body: JSON.stringify({ query, variables }),
+            signal: AbortSignal.timeout(30_000),
+        });
+        if (!res.ok)
+            throw new HttpError(res.status, `${this.graphqlBaseUrl}/graphql`, await res.text());
+        const result = parseJson(await res.text());
+        if (result.errors) {
+            throw new NetworkError(result.errors.map((e) => e.message ?? String(e)).join("; "));
+        }
+        return (result.data ?? {});
+    }
+    // ── identity ───────────────────────────────────────────────────────────────
+    async getCurrentUser() {
+        const result = await this.graphqlQuery(`
+      query GetCurrentUser {
+        me { id username email name given_name family_name picture }
+      }
+    `);
+        return result.me ?? null;
+    }
+    // ── projects ───────────────────────────────────────────────────────────────
+    /** Resolve a project slug to its ID. null means "not found" — the server will create it. */
+    async getProjectId(projectSlug) {
+        const ns = await this.namespace();
+        const cacheKey = `project:${ns}:${projectSlug}`;
+        const cached = this.idCache.get(cacheKey);
+        if (cached)
+            return cached;
+        const result = await this.graphqlQuery(`query GetProject($namespace: String!) {
+         namespace(slug: $namespace) { projects { id slug } }
+       }`, { namespace: ns });
+        const namespaceData = result.namespace;
+        if (namespaceData == null) {
+            throw new ConfigurationError(`Namespace '${ns}' not found. Please check the namespace exists on the server.`);
+        }
+        for (const p of namespaceData.projects ?? []) {
+            if (p.slug === projectSlug) {
+                const id = asId(p.id);
+                this.idCache.set(cacheKey, id);
+                return id;
+            }
+        }
+        return null;
+    }
+    async createProject(name, description) {
+        const ns = await this.namespace();
+        return this.requestJson(`namespaces/${ns}/nodes`, {
+            method: "POST",
+            json: { type: "PROJECT", name, slug: name, description: description ?? "" },
+        });
+    }
+    async deleteProject(projectSlug) {
+        const ns = await this.namespace();
+        const projectId = await this.getProjectId(projectSlug);
+        if (!projectId) {
+            throw new ConfigurationError(`Project '${projectSlug}' not found in namespace '${ns}'`);
+        }
+        return this.requestJson(`projects/${projectId}`, { method: "DELETE" });
+    }
+    // ── experiments ────────────────────────────────────────────────────────────
+    async createOrUpdateExperiment(args) {
+        const ns = await this.namespace();
+        let projectId = await this.getProjectId(args.project);
+        let parentId = "ROOT";
+        // A prefix of owner/project/folder…/name means the experiment hangs off a
+        // folder chain that has to exist first. Only the segments between the
+        // project and the experiment name are folders.
+        if (args.prefix) {
+            const parts = args.prefix.replace(/^\/+|\/+$/g, "").split("/");
+            const folderParts = parts.length > 3 ? parts.slice(2, -1) : [];
+            if (folderParts.length > 0) {
+                if (!projectId) {
+                    const created = await this.requestJson(`namespaces/${ns}/nodes`, {
+                        method: "POST",
+                        json: { type: "PROJECT", name: args.project, slug: args.project },
+                    });
+                    projectId = asId(created?.project?.id) ?? null;
+                }
+                if (projectId) {
+                    let current = "ROOT";
+                    for (const folderName of folderParts) {
+                        if (!folderName)
+                            continue;
+                        // No experimentId here: these are project-level folders, and
+                        // tagging them with one reparents them under the experiment.
+                        const folder = await this.postWith409Retry(`namespaces/${ns}/nodes`, {
+                            json: { type: "FOLDER", projectId, parentId: current, name: folderName },
+                        });
+                        current = asId(folder?.node?.id);
+                    }
+                    parentId = current;
+                }
+            }
+        }
+        const payload = { type: "EXPERIMENT", name: args.name, parentId };
+        if (projectId)
+            payload.projectId = projectId;
+        else
+            payload.projectSlug = args.project;
+        if (args.description != null)
+            payload.description = args.description;
+        if (args.tags != null)
+            payload.tags = args.tags;
+        if (args.bindrs != null)
+            payload.bindrs = args.bindrs;
+        if (args.writeProtected)
+            payload.writeProtected = true;
+        if (args.metadata != null)
+            payload.metadata = args.metadata;
+        const result = await this.postWith409Retry(`namespaces/${ns}/nodes`, { json: payload });
+        if (result?.experiment?.id && result?.node?.id) {
+            this.idCache.set(`exp_node:${asId(result.experiment.id)}`, asId(result.node.id));
+        }
+        return result;
+    }
+    async createLogEntries(experimentId, logs) {
+        return this.requestJson(`experiments/${experimentId}/logs`, { method: "POST", json: { logs } });
+    }
+    async setParameters(experimentId, data) {
+        return this.requestJson(`experiments/${experimentId}/parameters`, {
+            method: "POST",
+            json: { data },
+        });
+    }
+    async getParameters(experimentId) {
+        const result = await this.requestJson(`experiments/${experimentId}/parameters`);
+        return result.data ?? {};
+    }
+    async queryLogs(experimentId, opts = {}) {
+        return this.requestJson(`experiments/${experimentId}/logs`, {
+            params: {
+                limit: opts.limit,
+                offset: opts.offset,
+                orderBy: opts.orderBy,
+                order: opts.order,
+                level: opts.level?.join(","),
+                startTime: opts.startTime,
+                endTime: opts.endTime,
+                search: opts.search,
+            },
+        });
+    }
+    // ── metrics ────────────────────────────────────────────────────────────────
+    async appendBatchToMetric(experimentId, metricName, dataPoints) {
+        return this.requestJson(`experiments/${experimentId}/metrics/${encodeURIComponent(metricName)}/append-batch`, { method: "POST", json: { dataPoints } });
+    }
+    async getMetricData(experimentId, metricName, opts = {}) {
+        return this.requestJson(`experiments/${experimentId}/metrics/${encodeURIComponent(metricName)}/data`, {
+            params: {
+                startIndex: opts.startIndex,
+                limit: opts.limit,
+                bufferOnly: opts.bufferOnly ? "true" : undefined,
+            },
+        });
+    }
+    async getMetricStats(experimentId, metricName) {
+        return this.requestJson(`experiments/${experimentId}/metrics/${encodeURIComponent(metricName)}/stats`);
+    }
+    async downloadMetricChunk(experimentId, metricName, chunkNumber) {
+        return this.requestJson(`experiments/${experimentId}/metrics/${encodeURIComponent(metricName)}/chunks/${chunkNumber}`);
+    }
+    async listMetrics(experimentId) {
+        const result = await this.requestJson(`experiments/${experimentId}/metrics`);
+        return result.metrics ?? [];
+    }
+    // ── files ──────────────────────────────────────────────────────────────────
+    /**
+     * Upload one file, creating any folders its prefix names.
+     *
+     * The file is streamed off disk rather than read whole: the Python CLI did
+     * `f.read()` into memory, which puts a multi-GB checkpoint in the heap before
+     * a single byte leaves the machine.
+     */
+    async uploadFile(args) {
+        const ns = await this.namespace();
+        let projectId = args.projectId ?? null;
+        let parentId = args.parentId ?? "ROOT";
+        if (!projectId) {
+            const result = await this.graphqlQuery(`query GetExperimentProject($experimentId: ID!) {
+           experimentById(id: $experimentId) { projectId }
+         }`, { experimentId: args.experimentId });
+            projectId = asId(result?.experimentById?.projectId) ?? null;
+            if (!projectId) {
+                throw new ConfigurationError(`Could not resolve project ID for experiment ${args.experimentId}`);
+            }
+        }
+        // Files belong under the experiment node, not the project root.
+        let experimentNodeId = this.idCache.get(`exp_node:${args.experimentId}`);
+        if (!experimentNodeId) {
+            experimentNodeId = await this.getExperimentNodeId(args.experimentId);
+        }
+        if (experimentNodeId)
+            parentId = experimentNodeId;
+        let prefix = args.prefix ?? "";
+        if (prefix) {
+            for (const folderName of prefix.split("/")) {
+                if (!folderName)
+                    continue;
+                const folder = await this.postWith409Retry(`namespaces/${ns}/nodes`, {
+                    json: {
+                        type: "FOLDER",
+                        projectId,
+                        experimentId: args.experimentId,
+                        parentId,
+                        name: folderName,
+                    },
+                });
+                parentId = asId(folder?.node?.id);
+            }
+        }
+        const handle = await open(args.filePath, "r");
+        let result;
+        try {
+            const { size } = await handle.stat();
+            const form = new FormData();
+            // A Blob over the open handle keeps the bytes out of the JS heap.
+            const stream = handle.readableWebStream();
+            const blob = new Blob([await new Response(stream).arrayBuffer()], {
+                type: args.contentType || "application/octet-stream",
+            });
+            form.append("file", blob, args.filename);
+            form.append("type", "FILE");
+            form.append("projectId", String(projectId));
+            form.append("experimentId", String(args.experimentId));
+            form.append("parentId", String(parentId));
+            form.append("name", args.filename);
+            form.append("checksum", args.checksum);
+            if (args.description)
+                form.append("description", args.description);
+            if (args.tags?.length)
+                form.append("tags", args.tags.join(","));
+            if (args.metadata)
+                form.append("metadata", JSON.stringify(args.metadata));
+            result = await this.postWith409Retry(`namespaces/${ns}/nodes`, {
+                form,
+                timeoutMs: Math.max(30_000, Math.ceil(size / 1024) * 10),
+            });
+        }
+        finally {
+            await handle.close();
+        }
+        const node = result?.node ?? {};
+        const physical = result?.physicalFile ?? {};
+        return {
+            id: asId(node.id),
+            experimentId: asId(node.experimentId) ?? args.experimentId,
+            path: prefix,
+            filename: args.filename,
+            description: node.description,
+            tags: node.tags ?? [],
+            contentType: physical.contentType,
+            sizeBytes: physical.sizeBytes != null ? Number(physical.sizeBytes) : undefined,
+            checksum: physical.checksum,
+            metadata: node.metadata,
+            uploadedAt: node.createdAt,
+            updatedAt: node.updatedAt,
+            deletedAt: node.deletedAt,
+        };
+    }
+    async getExperimentNodeId(experimentId) {
+        const cacheKey = `exp_node:${experimentId}`;
+        const cached = this.idCache.get(cacheKey);
+        if (cached)
+            return cached;
+        const result = await this.graphqlQuery(`query GetExperimentNode($experimentId: ID!) {
+         experimentNode(experimentId: $experimentId) { id }
+       }`, { experimentId });
+        const id = asId(result?.experimentNode?.id);
+        if (!id)
+            throw new ConfigurationError(`No node found for experiment ID '${experimentId}'`);
+        this.idCache.set(cacheKey, id);
+        return id;
+    }
+    async getFile(fileId) {
+        return this.requestJson(`nodes/${fileId}`);
+    }
+    async listFiles(experimentId, limit = 500, offset = 0) {
+        const result = await this.graphqlQuery(`query ListExperimentFilesPaginated($experimentId: ID!, $limit: Int!, $offset: Int!) {
+         experimentById(id: $experimentId) {
+           filesPaginated(limit: $limit, offset: $offset) {
+             files {
+               id name description tags metadata createdAt pPath
+               physicalFile { id filename contentType sizeBytes checksum s3Url }
+             }
+             totalCount
+             hasMore
+           }
+         }
+       }`, { experimentId, limit, offset });
+        const page = result?.experimentById?.filesPaginated ?? {};
+        return { files: page.files ?? [], totalCount: page.totalCount ?? 0, hasMore: page.hasMore ?? false };
+    }
+    async searchFiles(pattern, experimentId, limit = 10, offset = 0) {
+        const result = await this.requestJson("search/files", {
+            params: { pattern, limit, offset, experimentId },
+        });
+        return result.files ?? [];
+    }
+    async deleteFile(fileId) {
+        return this.requestJson(`nodes/${fileId}`, { method: "DELETE" });
+    }
+    /**
+     * Stream a file to disk.
+     *
+     * Checksum verification belongs to the caller: `download` hashes into a
+     * scratch directory and only copies a file into the tree once it matches.
+     */
+    async downloadFileStreaming(fileId, destPath) {
+        const res = await this.request(`nodes/${fileId}/download`, { timeoutMs: 600_000, raw: true });
+        if (!res.ok)
+            throw new HttpError(res.status, `nodes/${fileId}/download`, await res.text());
+        if (!res.body)
+            throw new NetworkError(`Empty response body downloading file ${fileId}`);
+        await pipeline(Readable.fromWeb(res.body), createWriteStream(destPath));
+        await stat(destPath);
+        return destPath;
+    }
+    // ── GraphQL reads ──────────────────────────────────────────────────────────
+    async listProjectsGraphql(namespaceSlug, limit = 50, offset = 0) {
+        const result = await this.graphqlQuery(`query ProjectsPaginated($namespaceSlug: String, $limit: Int!, $offset: Int!) {
+         projectsPaginated(namespaceSlug: $namespaceSlug, limit: $limit, offset: $offset) {
+           projects { id name slug description tags experimentCount }
+           totalCount
+           hasMore
+         }
+       }`, { namespaceSlug: namespaceSlug ?? null, limit, offset });
+        const page = result?.projectsPaginated ?? {};
+        return { projects: page.projects ?? [], totalCount: page.totalCount ?? 0 };
+    }
+    async listExperimentsGraphql(projectSlug, opts = {}) {
+        const variables = {
+            namespaceSlug: opts.namespaceSlug ?? null,
+            projectSlug,
+            limit: opts.limit ?? 50,
+            offset: opts.offset ?? 0,
+        };
+        if (opts.status != null)
+            variables.status = opts.status;
+        const result = await this.graphqlQuery(`query ExperimentsPaginated($namespaceSlug: String, $projectSlug: String!, $status: ExperimentStatus, $limit: Int!, $offset: Int!) {
+         experimentsPaginated(namespaceSlug: $namespaceSlug, projectSlug: $projectSlug, status: $status, limit: $limit, offset: $offset) {
+           experiments {
+             id name description tags status startedAt endedAt metadata
+             project { slug namespace { slug } }
+             logMetadata { totalLogs }
+             metrics { name }
+             files { id }
+             trackCount
+             displayPath
+           }
+           totalCount
+           hasMore
+         }
+       }`, variables);
+        const page = result?.experimentsPaginated ?? {};
+        return { experiments: page.experiments ?? [], totalCount: page.totalCount ?? 0 };
+    }
+    async getExperimentGraphql(projectSlug, experimentName, namespaceSlug) {
+        const ns = namespaceSlug ?? (await this.namespace());
+        const result = await this.graphqlQuery(`query Experiment($namespaceSlug: String, $projectSlug: String!, $experimentName: String!) {
+         experiment(namespaceSlug: $namespaceSlug, projectSlug: $projectSlug, experimentName: $experimentName) {
+           id name description tags status metadata
+           project { slug namespace { slug } }
+           logMetadata { totalLogs }
+           metrics { name metricMetadata { totalDataPoints } }
+           files {
+             id name pPath description tags metadata
+             physicalFile { filename contentType sizeBytes checksum s3Url }
+           }
+           parameters { id data }
+         }
+       }`, { namespaceSlug: ns, projectSlug, experimentName });
+        return result?.experiment ?? null;
+    }
+    async searchExperimentsGraphql(pattern, limit = 50, offset = 0) {
+        const result = await this.graphqlQuery(`query SearchExperimentsPaginated($pattern: String!, $limit: Int!, $offset: Int!) {
+         searchExperimentsPaginated(pattern: $pattern, limit: $limit, offset: $offset) {
+           experiments {
+             id name description tags status startedAt endedAt metadata
+             project { id slug name namespace { id slug } }
+             logMetadata { totalLogs }
+             metrics { name metricMetadata { totalDataPoints } }
+             files { id name }
+             trackCount
+             displayPath
+           }
+           totalCount
+           hasMore
+         }
+       }`, { pattern, limit, offset });
+        const page = result?.searchExperimentsPaginated ?? {};
+        return { experiments: page.experiments ?? [], totalCount: page.totalCount ?? 0 };
+    }
+    /** Walk the project node tree to find an experiment nested under folders. */
+    async getExperimentByPathGraphql(projectSlug, experimentPath, namespaceSlug) {
+        const ns = namespaceSlug ?? (await this.namespace());
+        const result = await this.graphqlQuery(`query GetProjectHierarchy($namespaceSlug: String!, $projectSlug: String!) {
+         project(namespaceSlug: $namespaceSlug, projectSlug: $projectSlug) {
+           nodes(parentId: null, maxDepth: 20) {
+             ...NodeFields
+             children { ...NodeFields
+               children { ...NodeFields
+                 children { ...NodeFields
+                   children { ...NodeFields
+                     children { ...NodeFields
+                       children { ...NodeFields
+                         children { ...NodeFields
+                           children { ...NodeFields
+                             children { ...NodeFields } } } } } } } } }
+           }
+         }
+       }
+       fragment NodeFields on Node { id name type pPath experimentId }`, { namespaceSlug: ns, projectSlug });
+        const parts = experimentPath.replace(/^\/+|\/+$/g, "").split("/");
+        const find = async (nodes, remaining) => {
+            if (remaining.length === 0)
+                return null;
+            const [head, ...rest] = remaining;
+            for (const node of nodes ?? []) {
+                if (node?.name !== head)
+                    continue;
+                if (rest.length === 0 && node.type === "EXPERIMENT") {
+                    const experimentId = asId(node.experimentId);
+                    if (!experimentId)
+                        return null;
+                    const exp = await this.graphqlQuery(`query GetExperiment($id: ID!) {
+               experimentById(id: $id) {
+                 id name description tags status metadata
+                 project { slug namespace { slug } }
+               }
+             }`, { id: experimentId });
+                    return exp?.experimentById ?? null;
+                }
+                if (rest.length > 0 && node.children) {
+                    const found = await find(node.children, rest);
+                    if (found)
+                        return found;
+                }
+            }
+            return null;
+        };
+        return find(result?.project?.nodes ?? [], parts);
+    }
+    // ── tracks ─────────────────────────────────────────────────────────────────
+    async listTracks(experimentId, topicFilter) {
+        const result = await this.requestJson(`experiments/${experimentId}/tracks`, {
+            params: { topic: topicFilter },
+        });
+        return result.tracks ?? [];
+    }
+    async appendBatchToTrack(experimentId, topic, entries) {
+        // `append_batch`, with an underscore: the track routes spell it that way
+        // (`/experiments/:id/tracks/:topic/append_batch` in the server, and the
+        // same in the Python client), while the *metric* route next door is
+        // `append-batch`. The hyphen here 404'd every track upload.
+        return this.requestJson(`experiments/${experimentId}/tracks/${encodeURIComponent(topic)}/append_batch`, { method: "POST", json: { entries }, timeoutMs: 120_000 });
+    }
+    /** Track export. jsonl/parquet/mcap come back as bytes; json as a parsed object. */
+    async getTrackData(experimentId, topic, format) {
+        const res = await this.request(`experiments/${experimentId}/tracks/${encodeURIComponent(topic)}/data`, { params: { format }, timeoutMs: 600_000 });
+        if (format === "json")
+            return parseJson(await res.text());
+        return Buffer.from(await res.arrayBuffer());
+    }
+}

package/dist/commands/api.js

@@ -0,0 +1,89 @@
+/**
+ * `ml-dash api` — raw GraphQL against the server.
+ *
+ * Two conveniences from the Python CLI are load-bearing and reproduced exactly:
+ * a bare selection set is wrapped in `{ … }` (or `mutation { … }`), and single
+ * quotes are rewritten to double quotes so a query survives shell quoting.
+ */
+import { makeClient, notAuthenticatedMessage, resolveContext } from "../cli/context.js";
+import { red } from "../util/ansi.js";
+export const spec = {
+    name: "api",
+    help: "Send GraphQL queries to ml-dash server",
+    description: `Send GraphQL queries to the ml-dash server.
+
+Examples:
+  ml-dash api --query "me { username name email }"
+  ml-dash api --query "user(title: 'hello') { id title }"
+  ml-dash api --query "me { username }" --jq ".me.username"
+  ml-dash api --mutation "updateUser(username: 'newname') { username }"
+
+Notes:
+  - Single quotes are auto-converted to double quotes for GraphQL
+  - Use --jq for dot-path extraction (built-in, no deps)`,
+    options: [
+        { flags: ["--query", "-q"], dest: "query", metavar: "QUERY", help: "GraphQL query string" },
+        { flags: ["--mutation", "-m"], dest: "mutation", metavar: "MUTATION", help: "GraphQL mutation string" },
+        { flags: ["--jq"], dest: "jq", metavar: "PATH", help: "Extract value using dot-path (e.g., .me.username)" },
+        { flags: ["--dash-url", "--api-url"], dest: "dash_url", metavar: "URL", help: "ML-Dash server URL (default: https://api.dash.ml)" },
+    ],
+    mutuallyExclusive: [{ dests: ["query", "mutation"], required: true }],
+};
+/** GraphQL wants double quotes; shells want single. Trade one for the other. */
+export const fixQuotes = (q) => q.replace(/'/g, '"');
+export function buildQuery(query, isMutation) {
+    const q = fixQuotes(query.trim());
+    if (q.startsWith("{") || q.startsWith("mutation") || q.startsWith("query"))
+        return q;
+    return isMutation ? `mutation { ${q} }` : `{ ${q} }`;
+}
+/** Dot-path lookup. A numeric segment indexes into an array, as in the Python CLI. */
+export function extractPath(data, path) {
+    let cur = data;
+    for (const key of path.replace(/^\.+/, "").split(".")) {
+        if (!key)
+            continue;
+        if (Array.isArray(cur)) {
+            const idx = Number(key);
+            if (!Number.isInteger(idx))
+                throw new Error(`Cannot index array with '${key}'`);
+            cur = cur[idx];
+        }
+        else if (cur !== null && typeof cur === "object") {
+            if (!(key in cur))
+                throw new Error(`Key '${key}' not found`);
+            cur = cur[key];
+        }
+        else {
+            throw new Error(`Cannot access '${key}' on ${cur === null ? "null" : typeof cur}`);
+        }
+    }
+    return cur;
+}
+export async function run(args) {
+    const ctx = resolveContext(args);
+    if (!ctx.apiKey) {
+        console.error(`${red("Error:")} ${notAuthenticatedMessage(ctx)}`);
+        return 1;
+    }
+    try {
+        const isMutation = typeof args.mutation === "string";
+        const query = buildQuery(String(isMutation ? args.mutation : args.query), isMutation);
+        let result = await makeClient(ctx).graphqlQuery(query);
+        if (typeof args.jq === "string") {
+            try {
+                result = extractPath(result, args.jq);
+            }
+            catch (e) {
+                console.error(red(`Error extracting path '${args.jq}': ${e.message}`));
+                return 1;
+            }
+        }
+        console.log(JSON.stringify(result, null, 2));
+        return 0;
+    }
+    catch (e) {
+        console.error(red(`Error: ${e.message}`));
+        return 1;
+    }
+}