rubrkit 0.1.1 → 0.4.0

package/src/sdk.js

@@ -1,443 +1,556 @@
-// @ts-check
-
-import { DEFAULT_API_URL, normalizeApiUrl } from './config.js';
-
-const TERMINAL_JOB_STATES = new Set(['succeeded', 'failed', 'cancelled', 'paused']);
-
-/**
- * @typedef {{
- *   apiKey?: string | null,
- *   apiUrl?: string,
- *   fetchImpl?: typeof fetch,
- *   userAgent?: string,
- *   retryReads?: number
- * }} RubrkitOptions
- *
- * @typedef {{
- *   intervalMs?: number,
- *   timeoutMs?: number,
- *   signal?: AbortSignal,
- *   onProgress?: (job: Record<string, any>) => void
- * }} JobWaitOptions
- */
-
-export class RubrkitError extends Error {
-    /**
-     * @param {string} message
-     * @param {{ code?: string, details?: unknown }} [options]
-     */
-    constructor(message, { code = 'rubrkit_error', details = undefined } = {}) {
-        super(message);
-        this.name = 'RubrkitError';
-        this.code = code;
-        this.details = details;
-    }
-}
-
-export class RubrkitApiError extends RubrkitError {
-    /**
-     * @param {string} message
-     * @param {{ code?: string, status?: number, requestId?: string | null, details?: unknown }} [options]
-     */
-    constructor(message, { code = 'api_request_failed', status = 0, requestId = null, details = undefined } = {}) {
-        super(message, { code, details });
-        this.name = 'RubrkitApiError';
-        this.status = status;
-        this.requestId = requestId;
-    }
-}
-
-export class RubrkitNetworkError extends RubrkitError {
-    /**
-     * @param {string} message
-     * @param {{ cause?: unknown }} [options]
-     */
-    constructor(message, { cause = undefined } = {}) {
-        super(message, { code: 'network_error', details: cause });
-        this.name = 'RubrkitNetworkError';
-        this.cause = cause;
-    }
-}
-
-export class Rubrkit {
-    /**
-     * @param {RubrkitOptions} [options]
-     */
-    constructor({
-        apiKey = process.env.RUBRKIT_API_KEY ?? null,
-        apiUrl = process.env.RUBRKIT_API_URL ?? DEFAULT_API_URL,
-        fetchImpl = globalThis.fetch,
-        userAgent = 'rubrkit-sdk/0.0.0-local',
-        retryReads = 0,
-    } = {}) {
-        this.apiKey = apiKey;
-        this.apiUrl = normalizeApiUrl(apiUrl);
-        this.fetchImpl = fetchImpl;
-        this.userAgent = userAgent;
-        this.retryReads = Math.max(0, Number(retryReads) || 0);
-
-        this.me = {
-            get: () => this.request('/me'),
-        };
-
-        this.artifactBundles = {
-            list: (params = {}) => this.request('/artifact-bundles', { query: { status: 'active', limit: 100, ...params } }),
-            create: (params = {}) => this.request('/artifact-bundles', { method: 'POST', body: params }),
-            get: (id) => this.request(`/artifact-bundles/${encodePath(id)}`),
-        };
-
-        this.artifacts = {
-            list: (params = {}) => {
-                const artifactBundleId = requireParam(params, 'artifactBundleId');
-                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/files`, {
-                    query: omit(params, ['artifactBundleId']),
-                });
-            },
-            pull: (params = {}) => {
-                const artifactBundleId = requireParam(params, 'artifactBundleId');
-                const artifactId = params.artifactId ?? params.fileId;
-
-                if (artifactId) {
-                    return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/files/${encodePath(artifactId)}`);
-                }
-
-                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/files`, {
-                    query: omit(params, ['artifactBundleId']),
-                });
-            },
-            upload: (params = {}) => {
-                const artifactBundleId = requireParam(params, 'artifactBundleId');
-                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/files`, {
-                    method: 'POST',
-                    body: omit(params, ['artifactBundleId']),
-                });
-            },
-            test: (params = {}) => this.startArtifactTest(params),
-        };
-
-        this.audits = {
-            run: (params = {}) => {
-                const artifactBundleId = requireParam(params, 'artifactBundleId');
-                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/audits`, {
-                    method: 'POST',
-                    body: normalizeAuditBody(omit(params, ['artifactBundleId'])),
-                });
-            },
-        };
-
-        this.evals = {
-            run: (params = {}) => {
-                const artifactBundleId = requireParam(params, 'artifactBundleId');
-                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/evals`, {
-                    method: 'POST',
-                    body: omit(params, ['artifactBundleId']),
-                });
-            },
-        };
-
-        this.rubrFlow = {
-            convert: (params = {}) => {
-                const artifactBundleId = requireParam(params, 'artifactBundleId');
-                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/rubr-flow/conversions`, {
-                    method: 'POST',
-                    body: omit(params, ['artifactBundleId']),
-                });
-            },
-        };
-
-        this.jobs = {
-            get: (id) => this.request(`/jobs/${encodePath(id)}`),
-            wait: (id, options = {}) => this.waitForJob(id, options),
-        };
-
-        this.proofReports = {
-            get: (idOrParams, options = {}) => {
-                const params = typeof idOrParams === 'object' && idOrParams !== null ? idOrParams : { proofReportId: idOrParams, ...options };
-                const artifactBundleId = requireParam(params, 'artifactBundleId');
-                const proofReportId = requireParam(params, 'proofReportId');
-                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/proof-reports/${encodePath(proofReportId)}`);
-            },
-        };
-    }
-
-    /**
-     * @param {string} path
-     * @param {{ method?: string, query?: Record<string, unknown>, body?: unknown, signal?: AbortSignal }} [options]
-     */
-    async request(path, { method = 'GET', query = {}, body = undefined, signal = undefined } = {}) {
-        const url = buildUrl(this.apiUrl, path, query);
-        /** @type {Record<string, string>} */
-        const headers = {
-            accept: 'application/json',
-            'user-agent': this.userAgent,
-        };
-
-        if (this.apiKey) {
-            headers.authorization = `Bearer ${this.apiKey}`;
-        }
-
-        if (body !== undefined) {
-            headers['content-type'] = 'application/json';
-        }
-
-        const attempts = method === 'GET' ? this.retryReads + 1 : 1;
-        let lastError;
-
-        for (let attempt = 1; attempt <= attempts; attempt += 1) {
-            try {
-                const response = await this.fetchImpl(url, {
-                    method,
-                    headers,
-                    body: body === undefined ? undefined : JSON.stringify(body),
-                    signal,
-                });
-                return await parseResponse(response);
-            } catch (error) {
-                lastError = error;
-
-                if (error instanceof RubrkitApiError || attempt >= attempts) {
-                    throw error;
-                }
-            }
-        }
-
-        throw lastError;
-    }
-
-    /**
-     * @param {Record<string, any>} [params]
-     */
-    async startArtifactTest(params = {}) {
-        const files = Array.isArray(params.files) ? params.files : [];
-        let artifactBundleId = typeof params.artifactBundleId === 'string' && params.artifactBundleId.trim() ? params.artifactBundleId.trim() : null;
-        let artifactBundle = null;
-        let upload = null;
-
-        if (files.length > 0) {
-            if (!artifactBundleId) {
-                const created = await this.artifactBundles.create({
-                    name: params.name ?? inferArtifactTestBundleName(files),
-                    description: params.description ?? 'Created by a Rubrkit SDK or CLI remote test run.',
-                    customRubric: params.customRubric,
-                    settings: params.settings,
-                });
-                const createdRecord = asRecord(created);
-                artifactBundle = createdRecord.artifactBundle ?? createdRecord;
-                artifactBundleId = typeof asRecord(artifactBundle).id === 'string' ? asRecord(artifactBundle).id : null;
-            }
-
-            if (!artifactBundleId) {
-                throw new RubrkitError('Rubrkit API response did not include an artifact bundle ID.', { code: 'missing_artifact_bundle_id' });
-            }
-
-            upload = await this.artifacts.upload({
-                artifactBundleId,
-                files,
-            });
-        }
-
-        if (!artifactBundleId) {
-            artifactBundleId = requireParam(params, 'artifactBundleId');
-        }
-
-        const started = await this.audits.run({
-            artifactBundleId,
-            ...pickAuditParams(params),
-        });
-
-        return {
-            ...started,
-            artifactBundleId,
-            artifactBundle,
-            upload,
-            composedFrom: files.length > 0
-                ? ['artifact-bundles.create', 'artifact-bundles.files.upload', 'artifact-bundles.audits.create']
-                : ['artifact-bundles.audits.create'],
-        };
-    }
-
-    /**
-     * @param {string} id
-     * @param {JobWaitOptions} [options]
-     */
-    async waitForJob(id, { intervalMs = 1000, timeoutMs = 10 * 60 * 1000, signal = undefined, onProgress = undefined } = {}) {
-        const startedAt = Date.now();
-        let lastPhase = null;
-
-        while (true) {
-            if (signal?.aborted) {
-                throw new RubrkitError('Job wait was aborted.', { code: 'aborted' });
-            }
-
-            const data = await this.jobs.get(id);
-            const job = data.job ?? data;
-
-            if (job.phase !== lastPhase || TERMINAL_JOB_STATES.has(job.state)) {
-                onProgress?.(job);
-                lastPhase = job.phase;
-            }
-
-            if (TERMINAL_JOB_STATES.has(job.state)) {
-                return job;
-            }
-
-            if (Date.now() - startedAt > timeoutMs) {
-                throw new RubrkitError(`Timed out waiting for Rubrkit job ${id}.`, { code: 'job_wait_timeout', details: { jobId: id } });
-            }
-
-            await sleep(intervalMs);
-        }
-    }
-}
-
-/**
- * @param {Response} response
- */
-async function parseResponse(response) {
-    const text = await response.text();
-    const body = text ? parseJson(text) : {};
-    const requestId = body && typeof body === 'object' && typeof body.requestId === 'string' ? body.requestId : null;
-
-    if (!response.ok) {
-        const error = body && typeof body === 'object' && 'error' in body ? body.error : {};
-        const message =
-            error && typeof error === 'object' && typeof error.message === 'string'
-                ? error.message
-                : `Rubrkit API request failed with HTTP ${response.status}.`;
-        const code = error && typeof error === 'object' && typeof error.code === 'string' ? error.code : 'api_request_failed';
-
-        throw new RubrkitApiError(message, {
-            code,
-            status: response.status,
-            requestId,
-            details: error && typeof error === 'object' ? error.details : undefined,
-        });
-    }
-
-    return body && typeof body === 'object' && 'data' in body ? body.data : body;
-}
-
-/**
- * @param {string} text
- */
-function parseJson(text) {
-    try {
-        return JSON.parse(text);
-    } catch (error) {
-        throw new RubrkitApiError('Rubrkit API returned invalid JSON.', {
-            code: 'invalid_api_response',
-            details: error,
-        });
-    }
-}
-
-/**
- * @param {string} apiUrl
- * @param {string} path
- * @param {Record<string, unknown>} query
- */
-function buildUrl(apiUrl, path, query) {
-    const url = new URL(`${apiUrl.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`);
-
-    for (const [key, value] of Object.entries(query)) {
-        if (value === undefined || value === null || value === false) {
-            continue;
-        }
-
-        url.searchParams.set(key, String(value));
-    }
-
-    return url.toString();
-}
-
-/**
- * @param {unknown} value
- */
-function encodePath(value) {
-    return encodeURIComponent(String(value));
-}
-
-/**
- * @param {Record<string, any>} params
- * @param {string} name
- */
-function requireParam(params, name) {
-    const value = params[name];
-    if (typeof value !== 'string' || !value.trim()) {
-        throw new RubrkitError(`Missing required SDK parameter "${name}".`, { code: 'missing_sdk_parameter', details: { name } });
-    }
-
-    return value.trim();
-}
-
-/**
- * @param {unknown} value
- * @returns {Record<string, any>}
- */
-function asRecord(value) {
-    return value && typeof value === 'object' && !Array.isArray(value) ? /** @type {Record<string, any>} */ (value) : {};
-}
-
-/**
- * @param {Record<string, any>} params
- */
-function pickAuditParams(params) {
-    const picked = {};
-
-    for (const key of ['artifact', 'artifactType', 'targetFileId', 'targetVersionNumber', 'artifactBundleVersionNumber', 'rubric', 'rubricKey', 'noAi']) {
-        if (params[key] !== undefined && params[key] !== null && params[key] !== '') {
-            picked[key] = params[key];
-        }
-    }
-
-    return normalizeAuditBody(picked);
-}
-
-/**
- * @param {Record<string, any>} body
- */
-function normalizeAuditBody(body) {
-    const normalized = { ...body };
-
-    if (normalized.rubric !== undefined && normalized.rubricKey === undefined) {
-        normalized.rubricKey = normalized.rubric;
-    }
-
-    delete normalized.rubric;
-    delete normalized.target;
-    delete normalized.ci;
-    delete normalized.files;
-    delete normalized.name;
-    delete normalized.description;
-    delete normalized.customRubric;
-    delete normalized.settings;
-
-    return normalized;
-}
-
-/**
- * @param {Array<Record<string, any>>} files
- */
-function inferArtifactTestBundleName(files) {
-    const firstPath = typeof files[0]?.path === 'string' && files[0].path.trim() ? files[0].path.trim() : 'artifact';
-    const suffix = files.length > 1 ? ` and ${files.length - 1} more` : '';
-    const name = `CLI test: ${firstPath}${suffix}`;
-
-    return name.length <= 120 ? name : `${name.slice(0, 117)}...`;
-}
-
-/**
- * @param {Record<string, any>} params
- * @param {string[]} keys
- */
-function omit(params, keys) {
-    const blocked = new Set(keys);
-    return Object.fromEntries(Object.entries(params).filter(([key]) => !blocked.has(key)));
-}
-
-/**
- * @param {number} ms
- */
-function sleep(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
-}
+// @ts-check
+
+import { createHash } from 'node:crypto';
+import { DEFAULT_API_URL, normalizeApiUrl } from './config.js';
+
+const TERMINAL_JOB_STATES = new Set(['succeeded', 'failed', 'cancelled', 'paused']);
+
+/**
+ * Content hash matching the server's `computeContentHash` (sha256 of the UTF-8
+ * content bytes, prefixed `sha256:`). Used to detect which files changed.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function contentHashOf(content) {
+    return `sha256:${createHash('sha256').update(Buffer.from(String(content), 'utf8')).digest('hex')}`;
+}
+
+/**
+ * Extracts the file array from a list-files API response, tolerant of the
+ * `{ data: { files } }` / `{ files } / [...]` envelope shapes.
+ *
+ * @param {unknown} listed
+ * @returns {Array<{ id: string, path: string, contentHash?: string }>}
+ */
+function extractBundleFiles(listed) {
+    const root = /** @type {any} */ (listed) || {};
+    const data = root.data ?? root.result ?? root;
+    const files = data?.files ?? data?.artifactFiles ?? (Array.isArray(data) ? data : []);
+    return Array.isArray(files) ? files : [];
+}
+
+/**
+ * @typedef {{
+ *   apiKey?: string | null,
+ *   apiUrl?: string,
+ *   fetchImpl?: typeof fetch,
+ *   userAgent?: string,
+ *   retryReads?: number
+ * }} RubrkitOptions
+ *
+ * @typedef {{
+ *   intervalMs?: number,
+ *   timeoutMs?: number,
+ *   signal?: AbortSignal,
+ *   onProgress?: (job: Record<string, any>) => void
+ * }} JobWaitOptions
+ */
+
+export class RubrkitError extends Error {
+    /**
+     * @param {string} message
+     * @param {{ code?: string, details?: unknown }} [options]
+     */
+    constructor(message, { code = 'rubrkit_error', details = undefined } = {}) {
+        super(message);
+        this.name = 'RubrkitError';
+        this.code = code;
+        this.details = details;
+    }
+}
+
+export class RubrkitApiError extends RubrkitError {
+    /**
+     * @param {string} message
+     * @param {{ code?: string, status?: number, requestId?: string | null, details?: unknown }} [options]
+     */
+    constructor(message, { code = 'api_request_failed', status = 0, requestId = null, details = undefined } = {}) {
+        super(message, { code, details });
+        this.name = 'RubrkitApiError';
+        this.status = status;
+        this.requestId = requestId;
+    }
+}
+
+export class RubrkitNetworkError extends RubrkitError {
+    /**
+     * @param {string} message
+     * @param {{ cause?: unknown }} [options]
+     */
+    constructor(message, { cause = undefined } = {}) {
+        super(message, { code: 'network_error', details: cause });
+        this.name = 'RubrkitNetworkError';
+        this.cause = cause;
+    }
+}
+
+export class Rubrkit {
+    /**
+     * @param {RubrkitOptions} [options]
+     */
+    constructor({
+        apiKey = process.env.RUBRKIT_API_KEY ?? null,
+        apiUrl = process.env.RUBRKIT_API_URL ?? DEFAULT_API_URL,
+        fetchImpl = globalThis.fetch,
+        userAgent = 'rubrkit-sdk/0.0.0-local',
+        retryReads = 0,
+    } = {}) {
+        this.apiKey = apiKey;
+        this.apiUrl = normalizeApiUrl(apiUrl);
+        this.fetchImpl = fetchImpl;
+        this.userAgent = userAgent;
+        this.retryReads = Math.max(0, Number(retryReads) || 0);
+
+        this.me = {
+            get: () => this.request('/me'),
+        };
+
+        this.artifactBundles = {
+            list: (params = {}) => this.request('/artifact-bundles', { query: { status: 'active', limit: 100, ...params } }),
+            create: (params = {}) => this.request('/artifact-bundles', { method: 'POST', body: params }),
+            get: (id) => this.request(`/artifact-bundles/${encodePath(id)}`),
+        };
+
+        this.artifacts = {
+            list: (params = {}) => {
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/files`, {
+                    query: omit(params, ['artifactBundleId']),
+                });
+            },
+            pull: (params = {}) => {
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                const artifactId = params.artifactId ?? params.fileId;
+
+                if (artifactId) {
+                    return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/files/${encodePath(artifactId)}`);
+                }
+
+                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/files`, {
+                    query: omit(params, ['artifactBundleId']),
+                });
+            },
+            upload: (params = {}) => {
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/files`, {
+                    method: 'POST',
+                    body: omit(params, ['artifactBundleId']),
+                });
+            },
+            update: (params = {}) => {
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                const fileId = requireParam(params, 'fileId');
+                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/files/${encodePath(fileId)}`, {
+                    method: 'PUT',
+                    body: omit(params, ['artifactBundleId', 'fileId']),
+                });
+            },
+            remove: (params = {}) => {
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                const fileId = requireParam(params, 'fileId');
+                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/files/${encodePath(fileId)}`, {
+                    method: 'DELETE',
+                });
+            },
+            test: (params = {}) => this.startArtifactTest(params),
+        };
+
+        this.audits = {
+            run: (params = {}) => {
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/audits`, {
+                    method: 'POST',
+                    body: normalizeAuditBody(omit(params, ['artifactBundleId'])),
+                });
+            },
+            apply: (params = {}) => {
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                const auditRunId = requireParam(params, 'auditRunId');
+                return this.request(
+                    `/artifact-bundles/${encodePath(artifactBundleId)}/audits/${encodePath(auditRunId)}/apply`,
+                    { method: 'POST', body: omit(params, ['artifactBundleId', 'auditRunId']) },
+                );
+            },
+        };
+
+        this.evals = {
+            run: (params = {}) => {
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/evals`, {
+                    method: 'POST',
+                    body: omit(params, ['artifactBundleId']),
+                });
+            },
+        };
+
+        this.rubrFlow = {
+            convert: (params = {}) => {
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/rubr-flow/conversions`, {
+                    method: 'POST',
+                    body: omit(params, ['artifactBundleId']),
+                });
+            },
+        };
+
+        this.jobs = {
+            get: (id) => this.request(`/jobs/${encodePath(id)}`),
+            wait: (id, options = {}) => this.waitForJob(id, options),
+        };
+
+        this.proofReports = {
+            get: (idOrParams, options = {}) => {
+                const params = typeof idOrParams === 'object' && idOrParams !== null ? idOrParams : { proofReportId: idOrParams, ...options };
+                const artifactBundleId = requireParam(params, 'artifactBundleId');
+                const proofReportId = requireParam(params, 'proofReportId');
+                return this.request(`/artifact-bundles/${encodePath(artifactBundleId)}/proof-reports/${encodePath(proofReportId)}`);
+            },
+        };
+    }
+
+    /**
+     * @param {string} path
+     * @param {{ method?: string, query?: Record<string, unknown>, body?: unknown, signal?: AbortSignal }} [options]
+     */
+    async request(path, { method = 'GET', query = {}, body = undefined, signal = undefined } = {}) {
+        const url = buildUrl(this.apiUrl, path, query);
+        /** @type {Record<string, string>} */
+        const headers = {
+            accept: 'application/json',
+            'user-agent': this.userAgent,
+        };
+
+        if (this.apiKey) {
+            headers.authorization = `Bearer ${this.apiKey}`;
+        }
+
+        if (body !== undefined) {
+            headers['content-type'] = 'application/json';
+        }
+
+        const attempts = method === 'GET' ? this.retryReads + 1 : 1;
+        let lastError;
+
+        for (let attempt = 1; attempt <= attempts; attempt += 1) {
+            try {
+                const response = await this.fetchImpl(url, {
+                    method,
+                    headers,
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                    signal,
+                });
+                return await parseResponse(response);
+            } catch (error) {
+                lastError = error;
+
+                if (error instanceof RubrkitApiError || attempt >= attempts) {
+                    throw error;
+                }
+            }
+        }
+
+        throw lastError;
+    }
+
+    /**
+     * @param {Record<string, any>} [params]
+     */
+    async startArtifactTest(params = {}) {
+        const files = Array.isArray(params.files) ? params.files : [];
+        let artifactBundleId = typeof params.artifactBundleId === 'string' && params.artifactBundleId.trim() ? params.artifactBundleId.trim() : null;
+        let artifactBundle = null;
+        let upload = null;
+
+        if (files.length > 0) {
+            const reuseExistingBundle = Boolean(artifactBundleId);
+
+            if (!artifactBundleId) {
+                const created = await this.artifactBundles.create({
+                    name: params.name ?? inferArtifactTestBundleName(files),
+                    description: params.description ?? 'Created by a Rubrkit SDK or CLI remote test run.',
+                    customRubric: params.customRubric,
+                    settings: params.settings,
+                });
+                const createdRecord = asRecord(created);
+                artifactBundle = createdRecord.artifactBundle ?? createdRecord;
+                artifactBundleId = typeof asRecord(artifactBundle).id === 'string' ? asRecord(artifactBundle).id : null;
+            }
+
+            if (!artifactBundleId) {
+                throw new RubrkitError('Rubrkit API response did not include an artifact bundle ID.', { code: 'missing_artifact_bundle_id' });
+            }
+
+            // A brand-new bundle is empty, so a plain create-upload is correct. An
+            // existing (pinned) bundle is synced: changed files are updated in place,
+            // new files added, and files no longer present are removed — so repeated
+            // runs don't conflict on already-present paths.
+            upload = reuseExistingBundle
+                ? await this.syncArtifactBundleFiles({ artifactBundleId, files, message: params.message })
+                : await this.artifacts.upload({ artifactBundleId, files });
+        }
+
+        if (!artifactBundleId) {
+            artifactBundleId = requireParam(params, 'artifactBundleId');
+        }
+
+        const started = await this.audits.run({
+            artifactBundleId,
+            ...pickAuditParams(params),
+        });
+
+        return {
+            ...started,
+            artifactBundleId,
+            artifactBundle,
+            upload,
+            composedFrom: files.length > 0
+                ? ['artifact-bundles.create', 'artifact-bundles.files.upload', 'artifact-bundles.audits.create']
+                : ['artifact-bundles.audits.create'],
+        };
+    }
+
+    /**
+     * Mirrors a local file set into an existing artifact bundle: updates files
+     * whose content changed, creates new ones, and deletes files no longer
+     * present. Unchanged files (matching content hash) are left untouched, so
+     * re-running on the same content is a no-op instead of a path conflict.
+     *
+     * @param {{ artifactBundleId: string, files: Array<{ path: string, content: string, artifactType?: string }>, message?: string }} params
+     * @returns {Promise<{ created: string[], updated: string[], deleted: string[], unchanged: string[] }>}
+     */
+    async syncArtifactBundleFiles({ artifactBundleId, files, message }) {
+        // `limit` is capped at 200 by the API; a skills bundle is far smaller.
+        const existing = extractBundleFiles(await this.artifacts.list({ artifactBundleId, limit: 200 }));
+        const existingByPath = new Map(existing.map(file => [file.path, file]));
+
+        const created = [];
+        const updated = [];
+        const unchanged = [];
+        const toCreate = [];
+        const localPaths = new Set();
+
+        for (const file of files) {
+            localPaths.add(file.path);
+            const match = existingByPath.get(file.path);
+
+            if (!match) {
+                toCreate.push(file);
+                continue;
+            }
+
+            if (match.contentHash && match.contentHash === contentHashOf(file.content)) {
+                unchanged.push(file.path);
+                continue;
+            }
+
+            await this.artifacts.update({
+                artifactBundleId,
+                fileId: match.id,
+                content: file.content,
+                ...(message ? { message } : {}),
+            });
+            updated.push(file.path);
+        }
+
+        if (toCreate.length > 0) {
+            await this.artifacts.upload({ artifactBundleId, files: toCreate });
+            created.push(...toCreate.map(file => file.path));
+        }
+
+        const deleted = [];
+        for (const file of existing) {
+            if (!localPaths.has(file.path)) {
+                await this.artifacts.remove({ artifactBundleId, fileId: file.id });
+                deleted.push(file.path);
+            }
+        }
+
+        return { created, updated, deleted, unchanged };
+    }
+
+    /**
+     * @param {string} id
+     * @param {JobWaitOptions} [options]
+     */
+    async waitForJob(id, { intervalMs = 1000, timeoutMs = 10 * 60 * 1000, signal = undefined, onProgress = undefined } = {}) {
+        const startedAt = Date.now();
+        let lastPhase = null;
+
+        while (true) {
+            if (signal?.aborted) {
+                throw new RubrkitError('Job wait was aborted.', { code: 'aborted' });
+            }
+
+            const data = await this.jobs.get(id);
+            const job = data.job ?? data;
+
+            if (job.phase !== lastPhase || TERMINAL_JOB_STATES.has(job.state)) {
+                onProgress?.(job);
+                lastPhase = job.phase;
+            }
+
+            if (TERMINAL_JOB_STATES.has(job.state)) {
+                return job;
+            }
+
+            if (Date.now() - startedAt > timeoutMs) {
+                throw new RubrkitError(`Timed out waiting for Rubrkit job ${id}.`, { code: 'job_wait_timeout', details: { jobId: id } });
+            }
+
+            await sleep(intervalMs);
+        }
+    }
+}
+
+/**
+ * @param {Response} response
+ */
+async function parseResponse(response) {
+    const text = await response.text();
+    const body = text ? parseJson(text) : {};
+    const requestId = body && typeof body === 'object' && typeof body.requestId === 'string' ? body.requestId : null;
+
+    if (!response.ok) {
+        const error = body && typeof body === 'object' && 'error' in body ? body.error : {};
+        const message =
+            error && typeof error === 'object' && typeof error.message === 'string'
+                ? error.message
+                : `Rubrkit API request failed with HTTP ${response.status}.`;
+        const code = error && typeof error === 'object' && typeof error.code === 'string' ? error.code : 'api_request_failed';
+
+        throw new RubrkitApiError(message, {
+            code,
+            status: response.status,
+            requestId,
+            details: error && typeof error === 'object' ? error.details : undefined,
+        });
+    }
+
+    return body && typeof body === 'object' && 'data' in body ? body.data : body;
+}
+
+/**
+ * @param {string} text
+ */
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    } catch (error) {
+        throw new RubrkitApiError('Rubrkit API returned invalid JSON.', {
+            code: 'invalid_api_response',
+            details: error,
+        });
+    }
+}
+
+/**
+ * @param {string} apiUrl
+ * @param {string} path
+ * @param {Record<string, unknown>} query
+ */
+function buildUrl(apiUrl, path, query) {
+    const url = new URL(`${apiUrl.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`);
+
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null || value === false) {
+            continue;
+        }
+
+        url.searchParams.set(key, String(value));
+    }
+
+    return url.toString();
+}
+
+/**
+ * @param {unknown} value
+ */
+function encodePath(value) {
+    return encodeURIComponent(String(value));
+}
+
+/**
+ * @param {Record<string, any>} params
+ * @param {string} name
+ */
+function requireParam(params, name) {
+    const value = params[name];
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new RubrkitError(`Missing required SDK parameter "${name}".`, { code: 'missing_sdk_parameter', details: { name } });
+    }
+
+    return value.trim();
+}
+
+/**
+ * @param {unknown} value
+ * @returns {Record<string, any>}
+ */
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? /** @type {Record<string, any>} */ (value) : {};
+}
+
+/**
+ * @param {Record<string, any>} params
+ */
+function pickAuditParams(params) {
+    const picked = {};
+
+    for (const key of ['artifact', 'artifactType', 'targetFileId', 'targetVersionNumber', 'artifactBundleVersionNumber', 'rubric', 'rubricKey', 'noAi', 'force']) {
+        if (params[key] !== undefined && params[key] !== null && params[key] !== '') {
+            picked[key] = params[key];
+        }
+    }
+
+    return normalizeAuditBody(picked);
+}
+
+/**
+ * @param {Record<string, any>} body
+ */
+function normalizeAuditBody(body) {
+    const normalized = { ...body };
+
+    if (normalized.rubric !== undefined && normalized.rubricKey === undefined) {
+        normalized.rubricKey = normalized.rubric;
+    }
+
+    delete normalized.rubric;
+    delete normalized.target;
+    delete normalized.ci;
+    delete normalized.files;
+    delete normalized.name;
+    delete normalized.description;
+    delete normalized.customRubric;
+    delete normalized.settings;
+
+    return normalized;
+}
+
+/**
+ * @param {Array<Record<string, any>>} files
+ */
+function inferArtifactTestBundleName(files) {
+    const firstPath = typeof files[0]?.path === 'string' && files[0].path.trim() ? files[0].path.trim() : 'artifact';
+    const suffix = files.length > 1 ? ` and ${files.length - 1} more` : '';
+    const name = `CLI test: ${firstPath}${suffix}`;
+
+    return name.length <= 120 ? name : `${name.slice(0, 117)}...`;
+}
+
+/**
+ * @param {Record<string, any>} params
+ * @param {string[]} keys
+ */
+function omit(params, keys) {
+    const blocked = new Set(keys);
+    return Object.fromEntries(Object.entries(params).filter(([key]) => !blocked.has(key)));
+}
+
+/**
+ * @param {number} ms
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}