@assethub/cli 0.1.6 → 0.1.7

package/dist/runsUpload/controlEndpoints.js

@@ -0,0 +1,64 @@
+/**
+ * THE ONE PLACE the Production Control run-upload wire contract lives.
+ *
+ * The backend for these routes is being built in parallel. Everything the CLI
+ * knows about *where* to send bytes and *how big* they may be is in this file,
+ * so a late change on the server side is a one-line edit here rather than a
+ * sweep through the transport.
+ *
+ * Route shape mirrors the Cloudflare ag-registry Worker
+ * (assethub-ml research/artifact-graph/cloud/registry-worker/src/worker.js)
+ * because the payloads are the same `ag.registry.v1` documents. Only the prefix
+ * and the transport envelope differ: these live on AssetHub's public v2 API
+ * surface, behind `withExposedApi()` + API-key auth, so they speak AssetHub's
+ * `{success, data}` / `{success, error}` envelope rather than
+ * `ag.registry-error.v1`.
+ */
+/** Change this one line if the backend lands on a different prefix. */
+export const CONTROL_RUN_UPLOAD_API_PREFIX = '/api/v2/production/run-uploads';
+const trimTrailingSlash = (value) => value.replace(/\/+$/, '');
+export const controlRunUploadUrls = (baseUrl) => {
+    // Matches @assethub/api-client's own URL construction: trim the trailing
+    // slash and append, so a base URL carrying a path prefix keeps it.
+    const prefix = `${trimTrailingSlash(baseUrl)}${CONTROL_RUN_UPLOAD_API_PREFIX}`;
+    return {
+        graphs: `${prefix}/graphs`,
+        snapshot: graphId => `${prefix}/graphs/${encodeURIComponent(graphId)}/snapshot`,
+        blob: (graphId, blobKey) => `${prefix}/blobs/${encodeURIComponent(graphId)}/${encodeURIComponent(blobKey)}`,
+    };
+};
+/**
+ * Server-enforced ceilings, checked locally so a doomed run is rejected before
+ * the first byte leaves rather than after N blobs have already landed.
+ *
+ * The `ag.registry.v1` format allows far more (64 MiB graph arrays, 2 MiB
+ * manifest). These smaller numbers are the real ceiling: the routes run on
+ * Vercel Serverless, whose request-body limit bites first.
+ */
+export const CONTROL_MAX_BLOB_BYTES = 4 * 1024 * 1024;
+export const CONTROL_MAX_PUSH_BYTES = 4 * 1024 * 1024;
+/** Format-level ceilings from the registry contract, checked for completeness. */
+export const REGISTRY_MAX_MANIFEST_BYTES = 2 * 1024 * 1024;
+export const REGISTRY_MAX_GRAPH_ARRAY_BYTES = 64 * 1024 * 1024;
+export const REGISTRY_MAX_METADATA_BYTES = 256 * 1024;
+/**
+ * Error codes the routes answer with. Values follow AssetHub's public-API
+ * SCREAMING_SNAKE convention; the semantics follow the registry's.
+ */
+export const CONTROL_ERROR_CODES = {
+    /** 409 — the snapshot references bytes the pool does not hold yet. */
+    missingBlobs: 'MISSING_BLOBS',
+    /** 409 — same rev, different graphHash. A genuine divergence. */
+    snapshotConflict: 'SNAPSHOT_CONFLICT',
+    /** 409 — the server already holds a newer rev. Desired end state, not a failure. */
+    staleSnapshot: 'STALE_SNAPSHOT',
+    payloadTooLarge: 'PAYLOAD_TOO_LARGE',
+    /** 404 — the graph was never registered by this org. Distinct from "no access". */
+    notRegistered: 'NOT_REGISTERED',
+};
+/**
+ * These routes are internal-only. An API key whose owner is not an internal
+ * user, or whose org lacks the Production Control entitlement, gets 404 rather
+ * than 403 — the path's existence is itself not disclosed.
+ */
+export const CONTROL_NOT_ENTITLED_STATUS = 404;

package/dist/runsUpload/graphFolder.d.ts

@@ -0,0 +1,25 @@
+import { type ArtifactGraph, type ArtifactNode } from './artifactGraphModel.js';
+export declare const GRAPH_FOLDER_SCHEMA_VERSION = "ag.graph-folder.v1";
+export declare const MANIFEST_FILE_NAME = "manifest.json";
+export declare const NODES_FILE_NAME = "nodes.jsonl";
+export declare const EDGES_FILE_NAME = "edges.jsonl";
+export type GraphFolder = {
+    /** Absolute-or-as-given folder path, used verbatim in error messages. */
+    path: string;
+    /** The folder's own name, the default source for a graphId. */
+    name: string;
+    manifest: Record<string, unknown>;
+    /** Normalized + canonically ordered, ready to hash. */
+    graph: ArtifactGraph;
+    /** blobKey -> the file inside the folder that holds its bytes. */
+    blobFiles: Map<string, string>;
+};
+/** Port of format.py `manifest_flows`: metadata.flow.id ∪ `flow:*` tag suffixes. */
+export declare const deriveFlows: (graph: ArtifactGraph) => string[];
+/** Port of format.py `node_state`. */
+export declare const nodeState: (node: ArtifactNode) => string;
+/** Port of format.py `manifest_states`: `state:*` tag counts, key-sorted. */
+export declare const deriveStates: (graph: ArtifactGraph) => Record<string, number>;
+/** Port of `read_graph_folder`. */
+export declare const readGraphFolder: (path: string) => Promise<GraphFolder>;
+//# sourceMappingURL=graphFolder.d.ts.map

package/dist/runsUpload/graphFolder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphFolder.d.ts","sourceRoot":"","sources":["../../src/runsUpload/graphFolder.ts"],"names":[],"mappings":"AAgBA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,yBAAyB,CAAA;AAIhC,eAAO,MAAM,2BAA2B,uBAAuB,CAAA;AAC/D,eAAO,MAAM,kBAAkB,kBAAkB,CAAA;AACjD,eAAO,MAAM,eAAe,gBAAgB,CAAA;AAC5C,eAAO,MAAM,eAAe,gBAAgB,CAAA;AAE5C,MAAM,MAAM,WAAW,GAAG;IACxB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAA;IACZ,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,uDAAuD;IACvD,KAAK,EAAE,aAAa,CAAA;IACpB,kEAAkE;IAClE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B,CAAA;AAED,oFAAoF;AACpF,eAAO,MAAM,WAAW,GAAI,OAAO,aAAa,KAAG,MAAM,EAYxD,CAAA;AAED,sCAAsC;AACtC,eAAO,MAAM,SAAS,GAAI,MAAM,YAAY,KAAG,MAK9C,CAAA;AAED,6EAA6E;AAC7E,eAAO,MAAM,YAAY,GAAI,OAAO,aAAa,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAOxE,CAAA;AAED,mCAAmC;AACnC,eAAO,MAAM,eAAe,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,WAAW,CAevE,CAAA"}

package/dist/runsUpload/graphFolder.js

@@ -0,0 +1,147 @@
+// Reading an `ag.graph-folder.v1` folder off local disk.
+//
+// Port of assethub-ml research/artifact-graph/artifact-graph-py/
+// artifact_graph/graph_folder/ (`format.py` parse_manifest / parse_jsonl /
+// manifest_flows / manifest_states / node_state, `load.py` read_graph_folder).
+//
+// A folder written by `save_graph_folder` is already byte-canonical: its
+// nodes.jsonl / edges.jsonl lines are the `normalize_graph_state` output, one
+// canonical JSON line each, in canonical order. Re-normalizing them here is
+// therefore a no-op for a healthy folder and a repair for a hand-edited one —
+// and because the manifest's graphHash was taken over that same output,
+// re-hashing is what proves the folder still describes itself.
+import { readFile, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { codePointCompare, normalizeArtifactGraph, } from './artifactGraphModel.js';
+import { isPlainObject } from './canonicalJson.js';
+import { RunUploadError } from './runUploadError.js';
+export const GRAPH_FOLDER_SCHEMA_VERSION = 'ag.graph-folder.v1';
+export const MANIFEST_FILE_NAME = 'manifest.json';
+export const NODES_FILE_NAME = 'nodes.jsonl';
+export const EDGES_FILE_NAME = 'edges.jsonl';
+/** Port of format.py `manifest_flows`: metadata.flow.id ∪ `flow:*` tag suffixes. */
+export const deriveFlows = (graph) => {
+    const flows = new Set();
+    for (const node of graph.nodes ?? []) {
+        const metadata = isPlainObject(node.metadata) ? node.metadata : {};
+        const flow = isPlainObject(metadata.flow) ? metadata.flow : {};
+        const flowId = String(flow.id ?? '').trim();
+        if (flowId)
+            flows.add(flowId);
+        for (const tag of Array.isArray(node.tags) ? node.tags : []) {
+            if (String(tag).startsWith('flow:'))
+                flows.add(String(tag).slice('flow:'.length));
+        }
+    }
+    return [...flows].sort(codePointCompare);
+};
+/** Port of format.py `node_state`. */
+export const nodeState = (node) => {
+    for (const tag of Array.isArray(node.tags) ? node.tags : []) {
+        if (String(tag).startsWith('state:'))
+            return String(tag).slice('state:'.length);
+    }
+    return '';
+};
+/** Port of format.py `manifest_states`: `state:*` tag counts, key-sorted. */
+export const deriveStates = (graph) => {
+    const states = {};
+    for (const node of graph.nodes ?? []) {
+        const state = nodeState(node);
+        if (state)
+            states[state] = (states[state] ?? 0) + 1;
+    }
+    return Object.fromEntries(Object.entries(states).sort(([a], [b]) => codePointCompare(a, b)));
+};
+/** Port of `read_graph_folder`. */
+export const readGraphFolder = async (path) => {
+    const manifest = await parseManifest(join(path, MANIFEST_FILE_NAME), path);
+    const nodes = await parseJsonl(join(path, NODES_FILE_NAME), NODES_FILE_NAME);
+    const edges = await parseJsonl(join(path, EDGES_FILE_NAME), EDGES_FILE_NAME);
+    const graph = normalizeArtifactGraph({ nodes, edges });
+    const blobFiles = new Map();
+    for (const entry of Array.isArray(manifest.blobs) ? manifest.blobs : []) {
+        if (!isPlainObject(entry))
+            continue;
+        const key = typeof entry.key === 'string' ? entry.key : '';
+        const file = typeof entry.file === 'string' ? entry.file : '';
+        if (key && file)
+            blobFiles.set(key, join(path, file));
+    }
+    return { path, name: basename(path), manifest, graph, blobFiles };
+};
+const parseManifest = async (file, folderPath) => {
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (isNotFound(error)) {
+            const exists = await pathExists(folderPath);
+            throw new RunUploadError('folder_not_a_graph_folder', exists
+                ? `${folderPath} is not an artifact graph run folder: ${MANIFEST_FILE_NAME} is missing. ` +
+                    `Point the command at the folder that holds ${MANIFEST_FILE_NAME}, ${NODES_FILE_NAME} and ${EDGES_FILE_NAME}.`
+                : `No such run folder: ${folderPath}. Expected a folder containing ${MANIFEST_FILE_NAME}.`, { cause: error });
+        }
+        throw new RunUploadError('folder_unreadable', `Could not read ${MANIFEST_FILE_NAME} in ${folderPath}: ${messageOf(error)}`, { cause: error });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new RunUploadError('manifest_invalid_json', `${file} is not valid JSON: ${messageOf(error)}`, { cause: error });
+    }
+    if (!isPlainObject(parsed)) {
+        throw new RunUploadError('manifest_invalid_json', `${file} must contain a JSON object.`);
+    }
+    if (parsed.schemaVersion !== GRAPH_FOLDER_SCHEMA_VERSION) {
+        throw new RunUploadError('manifest_unsupported_schema', `Unsupported run folder schemaVersion ${JSON.stringify(parsed.schemaVersion ?? null)} in ${file}; ` +
+            `this CLI uploads ${GRAPH_FOLDER_SCHEMA_VERSION} folders. Re-export the run with a current artifact-graph build.`);
+    }
+    return parsed;
+};
+const parseJsonl = async (file, label) => {
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (isNotFound(error)) {
+            throw new RunUploadError('folder_not_a_graph_folder', `Run folder is missing ${label}: ${file}.`, { cause: error });
+        }
+        throw new RunUploadError('folder_unreadable', `Could not read ${file}: ${messageOf(error)}`, {
+            cause: error,
+        });
+    }
+    const items = [];
+    const lines = raw.split('\n');
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index].trim();
+        if (!line)
+            continue;
+        let item;
+        try {
+            item = JSON.parse(line);
+        }
+        catch (error) {
+            throw new RunUploadError('jsonl_invalid', `Invalid JSONL in ${label} line ${index + 1}: ${messageOf(error)}`, { cause: error });
+        }
+        if (!isPlainObject(item)) {
+            throw new RunUploadError('jsonl_invalid', `Invalid JSONL in ${label} line ${index + 1}: expected an object.`);
+        }
+        items.push(item);
+    }
+    return items;
+};
+const pathExists = async (path) => {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const isNotFound = (error) => error != null && typeof error === 'object' && 'code' in error && error.code === 'ENOENT';
+const messageOf = (error) => error instanceof Error ? error.message : String(error);

package/dist/runsUpload/runUploadError.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Every failure the run-upload path reports.
+ *
+ * `message` is what the operator reads on stderr, so it always answers both
+ * questions: what happened, and what to do next. `code` stays stable for tests
+ * and for anyone scripting around the command.
+ *
+ * Nothing here ever carries the API key. Request URLs are safe to print (the
+ * key rides in the Authorization header, never in a query string) but response
+ * bodies and header dumps are not echoed wholesale — only the server's own
+ * `error.code` / `error.message` / `error.details.blobKeys`.
+ */
+export declare class RunUploadError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, message: string, options?: {
+        status?: number;
+        details?: Record<string, unknown>;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=runUploadError.d.ts.map

package/dist/runsUpload/runUploadError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runUploadError.d.ts","sourceRoot":"","sources":["../../src/runsUpload/runUploadError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;gBAGxC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAM;CAQtF"}

package/dist/runsUpload/runUploadError.js

@@ -0,0 +1,24 @@
+/**
+ * Every failure the run-upload path reports.
+ *
+ * `message` is what the operator reads on stderr, so it always answers both
+ * questions: what happened, and what to do next. `code` stays stable for tests
+ * and for anyone scripting around the command.
+ *
+ * Nothing here ever carries the API key. Request URLs are safe to print (the
+ * key rides in the Authorization header, never in a query string) but response
+ * bodies and header dumps are not echoed wholesale — only the server's own
+ * `error.code` / `error.message` / `error.details.blobKeys`.
+ */
+export class RunUploadError extends Error {
+    code;
+    status;
+    details;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'RunUploadError';
+        this.code = code;
+        this.status = options.status;
+        this.details = options.details;
+    }
+}

package/dist/runsUpload/uploadRun.d.ts

@@ -0,0 +1,43 @@
+import { type PlannedBlob, type RunUploadPlan } from './buildRunUpload.js';
+export type RunUploadProgressEvent = {
+    kind: 'register';
+    graphId: string;
+} | {
+    kind: 'blob';
+    index: number;
+    total: number;
+    blob: PlannedBlob;
+    status: 'uploaded' | 'skipped';
+} | {
+    kind: 'push';
+    graphId: string;
+    rev: number;
+};
+export type RunUploadResult = {
+    graphId: string;
+    streamId: string;
+    rev: number;
+    graphHash: string;
+    registered: boolean;
+    blobsUploaded: number;
+    blobsSkipped: number;
+    bytesUploaded: number;
+    /**
+     * `published` — the snapshot became the graph's current revision.
+     * `unchanged` — an exact re-push of what the server already holds.
+     * `stale`     — the server already holds a NEWER revision, so this upload is
+     *               a no-op rather than a failure.
+     */
+    status: 'published' | 'unchanged' | 'stale';
+    data: unknown;
+};
+export type UploadRunInput = {
+    plan: RunUploadPlan;
+    baseUrl: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+    skipRegister?: boolean;
+    onProgress?: (event: RunUploadProgressEvent) => void;
+};
+export declare const uploadRun: ({ plan, baseUrl, apiKey, fetchImpl, skipRegister, onProgress, }: UploadRunInput) => Promise<RunUploadResult>;
+//# sourceMappingURL=uploadRun.d.ts.map

package/dist/runsUpload/uploadRun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploadRun.d.ts","sourceRoot":"","sources":["../../src/runsUpload/uploadRun.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAc,KAAK,WAAW,EAAE,KAAK,aAAa,EAAC,MAAM,qBAAqB,CAAA;AAGrF,MAAM,MAAM,sBAAsB,GAC9B;IAAC,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GACnC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;CAAC,GAC/F;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,CAAA;AAEhD,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,OAAO,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,MAAM,EAAE,WAAW,GAAG,WAAW,GAAG,OAAO,CAAA;IAC3C,IAAI,EAAE,OAAO,CAAA;CACd,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,aAAa,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAA;CACrD,CAAA;AAED,eAAO,MAAM,SAAS,GAAU,iEAO7B,cAAc,KAAG,OAAO,CAAC,eAAe,CA0F1C,CAAA"}

package/dist/runsUpload/uploadRun.js

@@ -0,0 +1,217 @@
+// Sending a planned run to Production Control.
+//
+// Order is the registry's: register -> blobs -> snapshot. The snapshot is
+// rejected while any blob it references is absent from the pool, so the bytes
+// have to land first.
+//
+// Resumability is the reason blobs go one at a time behind a HEAD. Content
+// addressing makes an upload idempotent — the same key always holds the same
+// bytes — so a run that dies at blob 150 of 300 is finished by re-running the
+// exact same command: the first 150 HEAD as present and are skipped. Nothing
+// records progress locally, because the server already knows it.
+//
+// Memory: exactly one blob is resident at a time, and `buildRunUploadPlan` has
+// already refused any blob over the per-request ceiling by stat'ing it, so an
+// oversized file is never read at all.
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { CONTROL_ERROR_CODES, CONTROL_NOT_ENTITLED_STATUS, controlRunUploadUrls, } from './controlEndpoints.js';
+import { RunUploadError } from './runUploadError.js';
+export const uploadRun = async ({ plan, baseUrl, apiKey, fetchImpl = globalThis.fetch.bind(globalThis), skipRegister = false, onProgress = () => { }, }) => {
+    const urls = controlRunUploadUrls(baseUrl);
+    // Built once, never logged, never placed in a URL or a query string.
+    const authHeaders = { authorization: `Bearer ${apiKey}` };
+    let registered = false;
+    if (!skipRegister) {
+        onProgress({ kind: 'register', graphId: plan.graphId });
+        await request(fetchImpl, urls.graphs, {
+            method: 'POST',
+            headers: { ...authHeaders, 'content-type': 'application/json' },
+            body: JSON.stringify(plan.registration),
+        });
+        registered = true;
+    }
+    let blobsUploaded = 0;
+    let blobsSkipped = 0;
+    let bytesUploaded = 0;
+    for (let index = 0; index < plan.blobs.length; index += 1) {
+        const blob = plan.blobs[index];
+        const url = urls.blob(plan.graphId, blob.blobKey);
+        if (await blobExists(fetchImpl, url, authHeaders)) {
+            blobsSkipped += 1;
+            onProgress({ kind: 'blob', index, total: plan.blobs.length, blob, status: 'skipped' });
+            continue;
+        }
+        const bytes = await readVerifiedBlob(blob);
+        await request(fetchImpl, url, {
+            method: 'PUT',
+            headers: {
+                ...authHeaders,
+                'content-type': blob.mime,
+                'x-artifact-blob-name': encodeURIComponent(blob.name),
+                'x-artifact-blob-sha256': blob.sha256,
+                'x-artifact-blob-size': String(blob.size),
+            },
+            body: bytes,
+        });
+        blobsUploaded += 1;
+        bytesUploaded += blob.size;
+        onProgress({ kind: 'blob', index, total: plan.blobs.length, blob, status: 'uploaded' });
+    }
+    onProgress({ kind: 'push', graphId: plan.graphId, rev: plan.rev });
+    let payload;
+    try {
+        payload = await request(fetchImpl, urls.snapshot(plan.graphId), {
+            method: 'PUT',
+            headers: { ...authHeaders, 'content-type': 'application/json' },
+            body: plan.pushBody,
+        });
+    }
+    catch (error) {
+        // The server already holds a newer revision. That is the end state the
+        // caller wanted, so it is reported, not thrown.
+        if (error instanceof RunUploadError && error.code === CONTROL_ERROR_CODES.staleSnapshot) {
+            return {
+                graphId: plan.graphId,
+                streamId: plan.streamId,
+                rev: plan.rev,
+                graphHash: plan.graphHash,
+                registered,
+                blobsUploaded,
+                blobsSkipped,
+                bytesUploaded,
+                status: 'stale',
+                data: error.details ?? null,
+            };
+        }
+        throw error;
+    }
+    const data = payload.data ?? null;
+    const serverStatus = data != null && typeof data === 'object' && 'status' in data
+        ? String(data.status)
+        : '';
+    return {
+        graphId: plan.graphId,
+        streamId: plan.streamId,
+        rev: plan.rev,
+        graphHash: plan.graphHash,
+        registered,
+        blobsUploaded,
+        blobsSkipped,
+        bytesUploaded,
+        status: serverStatus === 'unchanged' ? 'unchanged' : 'published',
+        data,
+    };
+};
+const blobExists = async (fetchImpl, url, authHeaders) => {
+    const response = await send(fetchImpl, url, { method: 'HEAD', headers: authHeaders });
+    if (response.ok)
+        return true;
+    if (response.status === 404)
+        return false;
+    throw await errorFrom(response, url, 'HEAD');
+};
+const readVerifiedBlob = async (blob) => {
+    const bytes = await readFile(blob.file);
+    const digest = createHash('sha256').update(bytes).digest('hex');
+    // The server recomputes this and rejects a mismatch; catching it here names
+    // the local file instead of surfacing an opaque 400.
+    if (digest !== blob.sha256) {
+        throw new RunUploadError('blob_digest_mismatch', `${blob.file} hashes to sha256:${digest} but the run folder declares ${blob.blobKey}. ` +
+            'The file changed since the folder was exported. Nothing further was sent; re-export the run.', { details: { blobKey: blob.blobKey, file: blob.file } });
+    }
+    if (bytes.byteLength !== blob.size) {
+        throw new RunUploadError('blob_size_mismatch', `${blob.file} is ${bytes.byteLength} bytes but the run folder declares ${blob.size}. ` +
+            'The file changed since the folder was exported. Nothing further was sent; re-export the run.', { details: { blobKey: blob.blobKey, file: blob.file } });
+    }
+    return bytes;
+};
+const request = async (fetchImpl, url, init) => {
+    const method = String(init.method ?? 'GET');
+    const response = await send(fetchImpl, url, init);
+    const payload = await readJson(response);
+    if (!response.ok || payload?.success !== true) {
+        throw await errorFrom(response, url, method, payload);
+    }
+    return payload;
+};
+const send = async (fetchImpl, url, init) => {
+    try {
+        return await fetchImpl(url, init);
+    }
+    catch (error) {
+        // Nothing here echoes the request headers, so the API key cannot leak into
+        // a transport error.
+        throw new RunUploadError('network_unreachable', `Could not reach Production Control at ${originOf(url)}: ${causeText(error)}. ` +
+            'Check your network and --base-url (or ASSETHUB_API_BASE_URL), then run the same command again — ' +
+            'blobs that already landed are detected and skipped, so the upload continues where it stopped.', { cause: error });
+    }
+};
+const readJson = async (response) => {
+    try {
+        return (await response.json());
+    }
+    catch {
+        // HEAD, 204, or a proxy's HTML error page.
+        return null;
+    }
+};
+const errorFrom = async (response, url, method, parsed) => {
+    const payload = parsed === undefined ? await readJson(response) : parsed;
+    const code = payload?.error?.code ?? `HTTP_${response.status}`;
+    const message = payload?.error?.message ?? `${method} ${originOf(url)} failed with ${response.status}`;
+    const details = payload?.error?.details;
+    return new RunUploadError(code, `${message}${hintFor(code, response.status, details)}`, {
+        status: response.status,
+        details,
+    });
+};
+/** The "what do I do now" half of every server-side failure. */
+const hintFor = (code, status, details) => {
+    if (code === CONTROL_ERROR_CODES.missingBlobs) {
+        const keys = Array.isArray(details?.blobKeys) ? details.blobKeys.map(String) : [];
+        return (`\nProduction Control is missing ${keys.length || 'some'} of this run's blobs` +
+            (keys.length > 0 ? `: ${keys.slice(0, 5).join(', ')}${keys.length > 5 ? ', …' : ''}` : '') +
+            '.\nRun the same command again — it re-checks every blob and sends only the absent ones.');
+    }
+    if (code === CONTROL_ERROR_CODES.snapshotConflict) {
+        return ('\nProduction Control already holds a different snapshot at this revision.' +
+            '\nUpload as a new revision with --rev <n> higher than the stored one, or --graph-id to publish it as a separate run.');
+    }
+    if (code === CONTROL_ERROR_CODES.payloadTooLarge || status === 413) {
+        return '\nThe request exceeded the size Production Control accepts. Re-export the run with smaller assets, or split it.';
+    }
+    // Both of these are 404, so the code is what separates them. Reading a
+    // NOT_REGISTERED as "you have no access" would send someone chasing an
+    // entitlement they already have.
+    if (code === CONTROL_ERROR_CODES.notRegistered) {
+        return ('\nThat graph is not registered for your org, so there is nothing to upload into.' +
+            '\nDrop --skip-register (registration is part of the normal upload), or pass the --graph-id of a run you have already registered.');
+    }
+    if (status === CONTROL_NOT_ENTITLED_STATUS) {
+        return ('\nThis API key cannot upload runs to Production Control. That needs an internal account whose org has the Production Control entitlement.' +
+            '\nCheck `assethub auth status` is using the key you meant, then ask for access.');
+    }
+    if (status === 401 || status === 403) {
+        return '\nThe API key was rejected. Re-run `assethub auth login --api-key-stdin`, or pass --api-key.';
+    }
+    if (status >= 500) {
+        return '\nThat is a server-side failure. Run the same command again — already-uploaded blobs are skipped, so a retry is cheap.';
+    }
+    return '';
+};
+const originOf = (url) => {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return url;
+    }
+};
+const causeText = (error) => {
+    if (!(error instanceof Error))
+        return String(error);
+    const cause = error.cause;
+    const causeMessage = cause instanceof Error ? cause.message : '';
+    return causeMessage ? `${error.message} (${causeMessage})` : error.message;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assethub/cli",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Command line interface for AssetHub.",
   "type": "module",
   "bin": {
@@ -20,19 +20,22 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
-    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit"
-  },
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@assethub/api-client": "^0.1.1"
+    "@assethub/api-client": "^0.1.2"
   },
   "devDependencies": {
     "@types/node": "24.10.1",
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "vitest": "^4.1.5",
+    "@assethub/autopilot-core": "0.0.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit"
   }
-}
+}