dataiku-sdk 3.0.0 → 3.1.0

package/dist/src/resources/jobs.js

@@ -1,9 +1,16 @@
+import { DataikuError, } from "../errors.js";
 import { JobSummaryArraySchema, } from "../schemas.js";
 import { BaseResource, } from "./base.js";
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const MAX_POLL_INTERVAL_MS = 10_000;
 const DEFAULT_TIMEOUT_MS = 120_000;
 const DEFAULT_MAX_LOG_LINES = 500;
+/**
+ * Default bytes retained from a job log body (default 10 MiB). Logs larger
+ * than this are downloaded bounded: only the most recent `maxLogBytes` bytes
+ * are kept, so a collaborator-influenced log cannot exhaust client memory.
+ */
+const DEFAULT_MAX_LOG_BYTES = 10 * 1024 * 1024;
 const TERMINAL_STATES = new Set([
     "DONE",
     "FAILED",
@@ -69,13 +76,23 @@ function jobBuildDefinition(targets, defaultProjectKey, opts) {
 function jobLogLines(log) {
     return log.split(/\r?\n/).map((line) => line.trimEnd());
 }
+/**
+ * DSS tags recipe subprocess output by reader thread: `[null-out-N]` carries
+ * the child's stdout and `[null-err-N]` its stderr. The legacy fallback is an
+ * explicit `stdout:` / `stderr:` record prefix (hand-written or non-DSS logs);
+ * a bare substring match would also select backend metadata such as the
+ * process wrapper's `pipes {"stdout": ...}` line and crowd out real output.
+ */
+const LEGACY_STDOUT_RECORD = /^\s*stdout:/i;
+const LEGACY_STDERR_RECORD = /^\s*stderr:/i;
 function lineMatchesLogFilter(line, filter) {
     const normalized = line.toLowerCase();
     switch (filter) {
         case "stdout":
-            return normalized.includes("stdout") || line.startsWith(">>> ");
+            return normalized.includes("[null-out-") || LEGACY_STDOUT_RECORD.test(line)
+                || line.startsWith(">>> ");
         case "stderr":
-            return normalized.includes("stderr");
+            return normalized.includes("[null-err-") || LEGACY_STDERR_RECORD.test(line);
         case "errors":
             return /\b(error|failed|failure|exception|traceback)\b/i.test(line);
         case "user":
@@ -173,15 +190,22 @@ export class JobsResource extends BaseResource {
     /**
      * Retrieve job log text.
      * Returns the last `maxLogLines` lines (default 500) from the tail.
-     * Use `0` or `-1` to return the full log without truncation.
+     * Use `0` or `-1` to return the log without line truncation.
+     *
+     * The download is byte-bounded and deadline-covered: at most `maxLogBytes`
+     * (default 10 MiB) of the *most recent* log output is retained, so a
+     * collaborator-influenced oversized log cannot exhaust client memory while
+     * the line limit previously only applied after a full unbounded download.
+     * Logs up to the cap are returned in full.
      */
     async log(jobId, opts) {
         const jobEnc = encodeURIComponent(jobId);
         const query = opts?.activity ? `?activity=${encodeURIComponent(opts.activity)}` : "";
         // DSS cat-activity-log URLs require a browser session; API-key callers must use the public log endpoint.
         const path = `/public/api/projects/${this.enc(opts?.projectKey)}/jobs/${jobEnc}/log/${query}`;
-        const log = await this.client.getText(path);
-        return limitJobLog(filterJobLog(log, opts?.logFilter), opts?.maxLogLines);
+        const maxLogBytes = Math.max(1, opts?.maxLogBytes ?? DEFAULT_MAX_LOG_BYTES);
+        const { text, } = await this.client.getTextTailLimited(path, maxLogBytes);
+        return limitJobLog(filterJobLog(text, opts?.logFilter), opts?.maxLogLines);
     }
     async logFromUrl(logUrl, opts) {
         const parsed = new URL(logUrl, "http://dss.local");
@@ -191,7 +215,12 @@ export class JobsResource extends BaseResource {
         if (!projectKey || !jobId || !activity) {
             throw new Error("Log URL must include projectKey, jobId, and activityId query parameters.");
         }
-        return this.log(jobId, { activity, projectKey, maxLogLines: opts?.maxLogLines, });
+        return this.log(jobId, {
+            activity,
+            projectKey,
+            maxLogLines: opts?.maxLogLines,
+            maxLogBytes: opts?.maxLogBytes,
+        });
     }
     /**
      * Start a build job for one or more dataset or managed-folder outputs.
@@ -250,6 +279,14 @@ export class JobsResource extends BaseResource {
      * Adaptive polling doubles the interval every 3 polls when
      * `pollIntervalMs` is not explicitly set.
      *
+     * A terminal state observed from the status endpoint is authoritative:
+     * when log retrieval fails afterwards (e.g. `not_found` because logs were
+     * purged or the job was removed), `wait` still returns the terminal
+     * outcome instead of throwing, with `logUnavailable` holding the machine-
+     * readable reason and `removed` set once the job itself is probed and
+     * confirmed gone. Explicit `includeLogs`/`summary` requests stay honest:
+     * `log`/`logSummary` are only present when logs were actually retrieved.
+     *
      * On timeout, returns `{ success: false, ... }` rather than throwing.
      */
     async wait(jobId, opts) {
@@ -272,18 +309,38 @@ export class JobsResource extends BaseResource {
                 const success = isSuccessfulTerminalState(state);
                 let log;
                 let logSummary;
+                let logUnavailable;
+                let removed;
                 if (opts?.includeLogs || opts?.summary) {
-                    const rawLog = await this.log(jobId, {
-                        activity: opts.activity,
-                        maxLogLines: opts.summary ? 0 : opts.maxLogLines,
-                        logId: opts.logId,
-                        projectKey: opts.projectKey,
-                    });
-                    const filteredLog = filterJobLog(rawLog, opts.logFilter);
-                    if (opts.includeLogs)
-                        log = limitJobLog(filteredLog, opts.maxLogLines);
-                    if (opts.summary) {
-                        logSummary = summarizeJobLog(state, filteredLog, opts.maxLogLines ?? 20, elapsedMs);
+                    try {
+                        // Fetch unlimited lines (still byte-bounded by log()) so the
+                        // filter runs over the whole retained log; the line limit is
+                        // applied to the filtered result below.
+                        const rawLog = await this.log(jobId, {
+                            activity: opts.activity,
+                            maxLogLines: 0,
+                            logId: opts.logId,
+                            projectKey: opts.projectKey,
+                        });
+                        const filteredLog = filterJobLog(rawLog, opts.logFilter);
+                        if (opts.includeLogs)
+                            log = limitJobLog(filteredLog, opts.maxLogLines);
+                        if (opts.summary) {
+                            logSummary = summarizeJobLog(state, filteredLog, opts.maxLogLines ?? 20, elapsedMs);
+                        }
+                    }
+                    catch (error) {
+                        if (error instanceof DataikuError) {
+                            // A terminal outcome observed from the status endpoint is
+                            // authoritative; failed log retrieval must not fail the wait.
+                            logUnavailable = error.category === "not_found" ? "not_found" : "error";
+                            if (logUnavailable === "not_found") {
+                                removed = await this.probeJobRemoved(projectEnc, jobEnc);
+                            }
+                        }
+                        else {
+                            throw error;
+                        }
                     }
                 }
                 return {
@@ -301,6 +358,8 @@ export class JobsResource extends BaseResource {
                     },
                     ...(log !== undefined ? { log, } : {}),
                     ...(logSummary !== undefined ? { logSummary, } : {}),
+                    ...(logUnavailable !== undefined ? { logUnavailable, } : {}),
+                    ...(removed !== undefined ? { removed, } : {}),
                 };
             }
             // Timeout — return failure result, don't throw
@@ -329,6 +388,22 @@ export class JobsResource extends BaseResource {
             await sleep(Math.min(nextDelayMs, timeout - elapsedMs));
         }
     }
+    /**
+     * Probe whether a job still exists. Returns `true` when the server reports
+     * it as not found, `false` when it is still visible, and `undefined` when
+     * the probe outcome is ambiguous.
+     */
+    async probeJobRemoved(projectEnc, jobEnc) {
+        try {
+            await this.client.get(`/public/api/projects/${projectEnc}/jobs/${jobEnc}/`);
+            return false;
+        }
+        catch (error) {
+            if (error instanceof DataikuError && error.category === "not_found")
+                return true;
+            return undefined;
+        }
+    }
     /** Request a job abort. */
     async abort(jobId, projectKey) {
         const jobEnc = encodeURIComponent(jobId);

package/dist/src/resources/notebooks.d.ts

@@ -1,21 +1,63 @@
-import type { JupyterNotebookContent, JupyterNotebookSummary, NotebookSession, SqlNotebookContent, SqlNotebookSummary } from "../schemas.js";
+import type { JupyterNotebookContent, JupyterNotebookSummary, NotebookSession, SqlNotebookContent, SqlNotebookHistory, SqlNotebookSummary } from "../schemas.js";
 import { BaseResource } from "./base.js";
+/** Result of a save that lands through POST (create) or PUT (update). */
+export interface NotebookSaveResult {
+    /** True when this call created the notebook, false when it overwrote one. */
+    created: boolean;
+    /** SHA-256 (hex) of the persisted content after a confirming re-read. */
+    hash: string;
+}
+export interface SaveNotebookOptions {
+    /** Reject the save when the stored content hash no longer matches. */
+    expectHash?: string;
+}
+export interface JupyterUnloadAllResult {
+    name: string;
+    unloadedSessionIds: string[];
+}
 export declare class NotebooksResource extends BaseResource {
-    /** List all Jupyter notebooks in a project. */
-    listJupyter(projectKey?: string): Promise<JupyterNotebookSummary[]>;
+    /**
+     * List Jupyter notebooks in a project.
+     *
+     * Pass `opts.active` to use the official `?active=` query filter: `true`
+     * returns only currently running notebooks, `false` only non-running ones
+     * (verified against `list_jupyter_notebooks` in the official Python API
+     * client). Omit it to list without the filter.
+     */
+    listJupyter(projectKey?: string, opts?: {
+        active?: boolean;
+    }): Promise<JupyterNotebookSummary[]>;
     /** Get the full content of a Jupyter notebook. */
     getJupyter(name: string, projectKey?: string): Promise<JupyterNotebookContent>;
-    /** Create a Jupyter notebook. */
+    /**
+     * Create a Jupyter notebook.
+     *
+     * The API takes the notebook name in the path; the body is the content.
+     */
     createJupyter(name: string, content: JupyterNotebookContent, projectKey?: string): Promise<void>;
     /** Save (overwrite) a Jupyter notebook's content. */
     saveJupyter(name: string, content: JupyterNotebookContent, projectKey?: string): Promise<void>;
+    /**
+     * Save a Jupyter notebook, creating it when missing.
+     *
+     * `created` reflects what actually happened: a 404 on the fresh read makes
+     * the follow-up POST a creation; an existing notebook is overwritten by
+     * PUT. The returned `hash` is always the hash of the persisted content
+     * from a confirming re-read, so it can be passed straight to
+     * `--expect-hash` on a later save. The PUT/POST themselves stay
+     * unconditional: DSS has no conditional write, so a writer committing
+     * between the read and the write is not detected.
+     */
+    saveOrCreateJupyter(name: string, content: JupyterNotebookContent, projectKey?: string, opts?: SaveNotebookOptions): Promise<NotebookSaveResult>;
     /** Delete a Jupyter notebook. */
     deleteJupyter(name: string, projectKey?: string): Promise<void>;
     /**
      * Clear all cell outputs from a Jupyter notebook.
      *
-     * DSS public APIs do not expose a dedicated clear-outputs endpoint, so this
-     * method fetches the notebook, strips outputs locally, and saves it back.
+     * Uses the official `DELETE .../outputs` endpoint (verified against
+     * `DSSJupyterNotebook.clear_outputs` in the official Python API client),
+     * so the clear is a single atomic server-side operation instead of a
+     * non-atomic GET-strip-PUT round trip.
      */
     clearJupyterOutputs(name: string, projectKey?: string): Promise<void>;
     /** List running kernel sessions for a Jupyter notebook. */
@@ -28,6 +70,16 @@ export declare class NotebooksResource extends BaseResource {
      * requires an externally-started disposable session fixture.
      */
     unloadJupyter(name: string, sessionId: string, projectKey?: string): Promise<void>;
+    /**
+     * Unload every session of every currently running Jupyter notebook.
+     *
+     * DSS exposes no single unload-all endpoint (verified against the official
+     * Python API client, which only ever issues per-session DELETEs), so this
+     * composes the verified endpoints: list active notebooks, list each
+     * notebook's sessions, and DELETE each session. Sessions that vanish
+     * between listing and unloading count as already unloaded.
+     */
+    unloadJupyterAll(projectKey?: string): Promise<JupyterUnloadAllResult[]>;
     /** List all SQL notebooks in a project. */
     listSql(projectKey?: string): Promise<SqlNotebookSummary[]>;
     /** Get the full content of a SQL notebook. */
@@ -36,14 +88,32 @@ export declare class NotebooksResource extends BaseResource {
     createSql(id: string, content: SqlNotebookContent, projectKey?: string): Promise<void>;
     /** Save (overwrite) a SQL notebook's content. */
     saveSql(id: string, content: SqlNotebookContent, projectKey?: string): Promise<void>;
+    /**
+     * Save a SQL notebook, creating it when missing. Same contract as
+     * `saveOrCreateJupyter`: `created` reflects the fresh read, and `hash` is
+     * the hash of the persisted content from a confirming re-read.
+     */
+    saveOrCreateSql(id: string, content: SqlNotebookContent, projectKey?: string, opts?: SaveNotebookOptions): Promise<NotebookSaveResult>;
     /** Delete a SQL notebook. */
     deleteSql(id: string, projectKey?: string): Promise<void>;
     /** Get execution history for a SQL notebook (keyed by cell ID). */
-    getSqlHistory(id: string, projectKey?: string): Promise<Record<string, unknown[]>>;
+    getSqlHistory(id: string, projectKey?: string): Promise<SqlNotebookHistory>;
     /** Clear execution history for a SQL notebook. */
     clearSqlHistory(id: string, opts?: {
         cellId?: string;
         numRunsToRetain?: number;
         projectKey?: string;
     }): Promise<void>;
+    /**
+     * Probe the stored notebook before a save. A missing notebook resolves to
+     * `undefined` (the caller will create it); anything else propagates. When
+     * `expectHash` is armed, the fresh read doubles as the stale-read guard:
+     * the hash of the stored content must match, or the save is rejected
+     * before any write. Like every DSS write, the PUT/POST that follows stays
+     * unconditional — the guard cannot detect a writer that commits between
+     * this read and the write.
+     */
+    private prepareSave;
+    /** Validate the armed `--expect-hash` value into a comparable hex digest. */
+    private validatedExpectHash;
 }

package/dist/src/resources/notebooks.js

@@ -1,10 +1,23 @@
-import { JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, NotebookSessionArraySchema, SqlNotebookContentSchema, SqlNotebookSummaryArraySchema, } from "../schemas.js";
+import { ClientValidationError, DataikuError, } from "../errors.js";
+import { JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, NotebookSessionArraySchema, SqlNotebookContentSchema, SqlNotebookHistorySchema, SqlNotebookSummaryArraySchema, } from "../schemas.js";
+import { stableHash, } from "../utils/stable-hash.js";
 import { BaseResource, } from "./base.js";
+const EXPECT_HASH_PATTERN = /^[0-9a-fA-F]{64}$/;
 export class NotebooksResource extends BaseResource {
     // ── Jupyter Notebooks ──────────────────────────────────────────────
-    /** List all Jupyter notebooks in a project. */
-    async listJupyter(projectKey) {
-        const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/`);
+    /**
+     * List Jupyter notebooks in a project.
+     *
+     * Pass `opts.active` to use the official `?active=` query filter: `true`
+     * returns only currently running notebooks, `false` only non-running ones
+     * (verified against `list_jupyter_notebooks` in the official Python API
+     * client). Omit it to list without the filter.
+     */
+    async listJupyter(projectKey, opts) {
+        const suffix = opts?.active === undefined
+            ? "/"
+            : `/?active=${String(opts.active)}`;
+        const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks${suffix}`);
         return this.client.safeParse(JupyterNotebookSummaryArraySchema, raw, "notebooks.listJupyter");
     }
     /** Get the full content of a Jupyter notebook. */
@@ -13,7 +26,11 @@ export class NotebooksResource extends BaseResource {
         const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/${nameEnc}`);
         return this.client.safeParse(JupyterNotebookContentSchema, raw, "notebooks.getJupyter");
     }
-    /** Create a Jupyter notebook. */
+    /**
+     * Create a Jupyter notebook.
+     *
+     * The API takes the notebook name in the path; the body is the content.
+     */
     async createJupyter(name, content, projectKey) {
         const nameEnc = encodeURIComponent(name);
         await this.client.post(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/${nameEnc}`, content);
@@ -23,6 +40,29 @@ export class NotebooksResource extends BaseResource {
         const nameEnc = encodeURIComponent(name);
         await this.client.putVoid(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/${nameEnc}`, content);
     }
+    /**
+     * Save a Jupyter notebook, creating it when missing.
+     *
+     * `created` reflects what actually happened: a 404 on the fresh read makes
+     * the follow-up POST a creation; an existing notebook is overwritten by
+     * PUT. The returned `hash` is always the hash of the persisted content
+     * from a confirming re-read, so it can be passed straight to
+     * `--expect-hash` on a later save. The PUT/POST themselves stay
+     * unconditional: DSS has no conditional write, so a writer committing
+     * between the read and the write is not detected.
+     */
+    async saveOrCreateJupyter(name, content, projectKey, opts) {
+        const pk = this.resolveProjectKey(projectKey);
+        const before = await this.prepareSave(() => this.getJupyter(name, pk), opts?.expectHash, pk, "Jupyter notebook", name);
+        if (before === undefined) {
+            await this.createJupyter(name, content, pk);
+        }
+        else {
+            await this.saveJupyter(name, content, pk);
+        }
+        const persisted = await this.getJupyter(name, pk);
+        return { created: before === undefined, hash: stableHash(persisted), };
+    }
     /** Delete a Jupyter notebook. */
     async deleteJupyter(name, projectKey) {
         const nameEnc = encodeURIComponent(name);
@@ -31,21 +71,14 @@ export class NotebooksResource extends BaseResource {
     /**
      * Clear all cell outputs from a Jupyter notebook.
      *
-     * DSS public APIs do not expose a dedicated clear-outputs endpoint, so this
-     * method fetches the notebook, strips outputs locally, and saves it back.
+     * Uses the official `DELETE .../outputs` endpoint (verified against
+     * `DSSJupyterNotebook.clear_outputs` in the official Python API client),
+     * so the clear is a single atomic server-side operation instead of a
+     * non-atomic GET-strip-PUT round trip.
      */
     async clearJupyterOutputs(name, projectKey) {
-        const notebook = await this.getJupyter(name, projectKey);
-        const clearedCells = notebook.cells.map((cell) => {
-            if (cell.cell_type !== "code")
-                return cell;
-            return {
-                ...cell,
-                outputs: [],
-                execution_count: 0,
-            };
-        });
-        await this.saveJupyter(name, { ...notebook, cells: clearedCells, }, projectKey);
+        const nameEnc = encodeURIComponent(name);
+        await this.client.del(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/${nameEnc}/outputs`);
     }
     /** List running kernel sessions for a Jupyter notebook. */
     async listJupyterSessions(name, projectKey) {
@@ -65,6 +98,35 @@ export class NotebooksResource extends BaseResource {
         const sidEnc = encodeURIComponent(sessionId);
         await this.client.del(`/public/api/projects/${this.enc(projectKey)}/jupyter-notebooks/${nameEnc}/sessions/${sidEnc}`);
     }
+    /**
+     * Unload every session of every currently running Jupyter notebook.
+     *
+     * DSS exposes no single unload-all endpoint (verified against the official
+     * Python API client, which only ever issues per-session DELETEs), so this
+     * composes the verified endpoints: list active notebooks, list each
+     * notebook's sessions, and DELETE each session. Sessions that vanish
+     * between listing and unloading count as already unloaded.
+     */
+    async unloadJupyterAll(projectKey) {
+        const active = await this.listJupyter(projectKey, { active: true, });
+        const results = [];
+        for (const summary of active) {
+            const sessions = await this.listJupyterSessions(summary.name, projectKey);
+            const unloadedSessionIds = [];
+            for (const session of sessions) {
+                try {
+                    await this.unloadJupyter(summary.name, session.sessionId, projectKey);
+                    unloadedSessionIds.push(session.sessionId);
+                }
+                catch (error) {
+                    if (!(error instanceof DataikuError && error.category === "not_found"))
+                        throw error;
+                }
+            }
+            results.push({ name: summary.name, unloadedSessionIds, });
+        }
+        return results;
+    }
     // ── SQL Notebooks ──────────────────────────────────────────────────
     /** List all SQL notebooks in a project. */
     async listSql(projectKey) {
@@ -86,6 +148,23 @@ export class NotebooksResource extends BaseResource {
         const idEnc = encodeURIComponent(id);
         await this.client.putVoid(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/${idEnc}`, content);
     }
+    /**
+     * Save a SQL notebook, creating it when missing. Same contract as
+     * `saveOrCreateJupyter`: `created` reflects the fresh read, and `hash` is
+     * the hash of the persisted content from a confirming re-read.
+     */
+    async saveOrCreateSql(id, content, projectKey, opts) {
+        const pk = this.resolveProjectKey(projectKey);
+        const before = await this.prepareSave(() => this.getSql(id, pk), opts?.expectHash, pk, "SQL notebook", id);
+        if (before === undefined) {
+            await this.createSql(id, content, pk);
+        }
+        else {
+            await this.saveSql(id, content, pk);
+        }
+        const persisted = await this.getSql(id, pk);
+        return { created: before === undefined, hash: stableHash(persisted), };
+    }
     /** Delete a SQL notebook. */
     async deleteSql(id, projectKey) {
         const idEnc = encodeURIComponent(id);
@@ -94,11 +173,56 @@ export class NotebooksResource extends BaseResource {
     /** Get execution history for a SQL notebook (keyed by cell ID). */
     async getSqlHistory(id, projectKey) {
         const idEnc = encodeURIComponent(id);
-        return this.client.get(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/${idEnc}/history`);
+        const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/sql-notebooks/${idEnc}/history`);
+        return this.client.safeParse(SqlNotebookHistorySchema, raw, "notebooks.getSqlHistory");
     }
     /** Clear execution history for a SQL notebook. */
     async clearSqlHistory(id, opts) {
         const idEnc = encodeURIComponent(id);
         await this.client.post(`/public/api/projects/${this.enc(opts?.projectKey)}/sql-notebooks/${idEnc}/history/clear`, { cellId: opts?.cellId, numRunsToRetain: opts?.numRunsToRetain, });
     }
+    // ── Shared save helpers ────────────────────────────────────────────
+    /**
+     * Probe the stored notebook before a save. A missing notebook resolves to
+     * `undefined` (the caller will create it); anything else propagates. When
+     * `expectHash` is armed, the fresh read doubles as the stale-read guard:
+     * the hash of the stored content must match, or the save is rejected
+     * before any write. Like every DSS write, the PUT/POST that follows stays
+     * unconditional — the guard cannot detect a writer that commits between
+     * this read and the write.
+     */
+    async prepareSave(read, expectHash, pk, resourceLabel, id) {
+        // Shape validation runs before any request so an armed but malformed
+        // guard rejects without touching DSS.
+        const expected = expectHash === undefined
+            ? undefined
+            : this.validatedExpectHash(expectHash, pk, resourceLabel, id);
+        let current;
+        try {
+            current = await read();
+        }
+        catch (error) {
+            if (!(error instanceof DataikuError && error.category === "not_found"))
+                throw error;
+        }
+        if (expected === undefined)
+            return current;
+        const actual = current === undefined ? undefined : stableHash(current);
+        if (actual !== expected) {
+            throw new ClientValidationError(`The ${resourceLabel} ${JSON.stringify(id)} changed since it was read.`, "validation_failed", "Re-read the notebook and retry with the current hash value.", {
+                projectKey: pk,
+                id,
+                expectedHash: expected,
+                ...(actual !== undefined ? { actualHash: actual, } : { absent: true, }),
+            });
+        }
+        return current;
+    }
+    /** Validate the armed `--expect-hash` value into a comparable hex digest. */
+    validatedExpectHash(expectHash, pk, resourceLabel, id) {
+        if (!EXPECT_HASH_PATTERN.test(expectHash)) {
+            throw new ClientValidationError(`Expected ${resourceLabel} hash must be a 64-character SHA-256 hex digest.`, "validation_failed", "Use the hash value returned by a previous save or read.", { projectKey: pk, id, });
+        }
+        return expectHash.toLowerCase();
+    }
 }

package/dist/src/resources/project-git.d.ts

@@ -67,6 +67,18 @@ export interface ProjectGitFutureWaitOptions {
     pollIntervalMs?: number;
     timeoutMs?: number;
 }
+/**
+ * Validate and canonicalize a Git library reference path. This is the single
+ * validator used by both SDK dispatch and CLI mutation planning.
+ *
+ * Strip only the permitted outer '/' separators, then require nonempty
+ * ordinary segments: no empty segments and no '.' or '..' segments. A hostile
+ * path therefore cannot change which API resource a dispatcher's URL
+ * normalization would otherwise select.
+ */
+export declare function validateGitReferencePath(path: string): string;
+/** Validate a Git library reference path and URL-encode it per segment. */
+export declare function encodeGitReferencePath(path: string): string;
 export declare class ProjectGitResource extends BaseResource {
     /** Working-copy status: current branch, remotes, tracking counts, changes. */
     status(projectKey: string): Promise<ProjectGitStatus>;

package/dist/src/resources/project-git.js

@@ -17,11 +17,39 @@ function sleep(ms) {
     setTimeout(resolve, ms);
     return promise;
 }
-function encodePathSegments(path) {
+function gitReferencePathError(path, message) {
+    return new ClientValidationError(message, "validation_failed", "Use a Git library reference path relative to the project library root: '/' -separated segment names, with no '.' or '..' segments.", { path, });
+}
+/**
+ * Validate and canonicalize a Git library reference path. This is the single
+ * validator used by both SDK dispatch and CLI mutation planning.
+ *
+ * Strip only the permitted outer '/' separators, then require nonempty
+ * ordinary segments: no empty segments and no '.' or '..' segments. A hostile
+ * path therefore cannot change which API resource a dispatcher's URL
+ * normalization would otherwise select.
+ */
+export function validateGitReferencePath(path) {
+    if (typeof path !== "string" || path.trim() === "") {
+        throw gitReferencePathError(path, "A Git library reference path is required.");
+    }
     const normalized = path.replace(/^\/+/, "").replace(/\/+$/, "");
-    if (!normalized)
-        throw new ClientValidationError("A Git reference path is required.");
-    return normalized
+    if (normalized === "") {
+        throw gitReferencePathError(path, "A Git library reference path is required.");
+    }
+    for (const segment of normalized.split("/")) {
+        if (segment === "") {
+            throw gitReferencePathError(path, "A Git library reference path must not contain empty segments (consecutive or repeated '/').");
+        }
+        if (segment === "." || segment === "..") {
+            throw gitReferencePathError(path, "A Git library reference path must not contain '.' or '..' segments.");
+        }
+    }
+    return normalized;
+}
+/** Validate a Git library reference path and URL-encode it per segment. */
+export function encodeGitReferencePath(path) {
+    return validateGitReferencePath(path)
         .split("/")
         .map((segment) => encodeURIComponent(segment))
         .join("/");
@@ -280,7 +308,8 @@ export class ProjectGitResource extends BaseResource {
     async setLibrary(projectKey, gitReferencePath, options) {
         const repository = validatedRepository(options.repository, "Git library repository URL");
         const secrets = [options.password,].filter((secret) => secret !== undefined && secret !== "");
-        const raw = await this.request("PUT", `${this.libraryPath(projectKey)}/${encodePathSegments(gitReferencePath)}`, {
+        const encodedPath = encodeGitReferencePath(gitReferencePath);
+        const raw = await this.request("PUT", `${this.libraryPath(projectKey)}/${encodedPath}`, {
             repository,
             login: options.login ?? null,
             password: options.password ?? null,
@@ -291,19 +320,21 @@ export class ProjectGitResource extends BaseResource {
     }
     /** Detach a library, optionally deleting its local directory. */
     async removeLibrary(projectKey, gitReferencePath, deleteDirectory = false) {
-        await this.request("DELETE", `${this.libraryPath(projectKey)}/${encodePathSegments(gitReferencePath)}${this.query({ deleteDirectory, })}`);
+        await this.request("DELETE", `${this.libraryPath(projectKey)}/${encodeGitReferencePath(gitReferencePath)}${this.query({ deleteDirectory, })}`);
     }
     /** Reset one library to its remote state. Runs as a DSS future. */
     async resetLibrary(projectKey, gitReferencePath) {
+        const gitRef = validateGitReferencePath(gitReferencePath);
         const raw = await this.request("POST", `${this.libraryPath(projectKey)}/action/reset`, {
-            gitRef: gitReferencePath,
+            gitRef,
         });
         return this.client.safeParse(ProjectGitFutureResponseSchema, raw ?? {}, "projectGit.resetLibrary");
     }
     /** Commit and push one library. Runs as a DSS future. */
     async pushLibrary(projectKey, gitReferencePath, commitMessage) {
+        const gitRef = validateGitReferencePath(gitReferencePath);
         const raw = await this.request("POST", `${this.libraryPath(projectKey)}/action/push`, {
-            gitRef: gitReferencePath,
+            gitRef,
             commitMessage,
         });
         return this.client.safeParse(ProjectGitFutureResponseSchema, raw ?? {}, "projectGit.pushLibrary");