dataiku-sdk 2.0.0 → 3.1.0

package/dist/src/cli/commands/code.js

@@ -1,17 +1,44 @@
 import { readFileSync, } from "node:fs";
+import { ScenarioScriptRunWithCleanupFailureError, } from "../../resources/scenarios.js";
 import { num, readStdinText, stripUtf8Bom, } from "../coerce.js";
+import { enqueueCliWarning, } from "../output.js";
 import { UsageError, } from "../usage.js";
-const CODE_RUN_USAGE = "dss code run (--file PATH | --stdin) [--env ENV] [--timeout MS] [--keep] [--full-log] [--max-log-bytes N] [--project-key KEY]";
-function resolveCodeInput(args, flags) {
+const CODE_RUN_USAGE = "dss code run (--file PATH | --stdin) [--env ENV] [--timeout MS (default 120000)] [--keep] [--full-log] [--max-log-bytes N (default 1048576)] [--project-key KEY]";
+function previewFlagValue(value) {
+    const text = typeof value === "string" ? value : String(value);
+    return text.length <= 32 ? text : `${text.slice(0, 32)}…`;
+}
+/** Read a local Python source file, mapping read failures to usage validation. */
+function readCodeSourceFile(filePath) {
+    try {
+        return readFileSync(filePath, "utf-8");
+    }
+    catch (error) {
+        throw new UsageError(`Could not read --file ${filePath}: ${error instanceof Error ? error.message : String(error)}.`, "not_found", "Verify the file path and that it is readable.");
+    }
+}
+/**
+ * Canonical validation of `code run` input: rejects positional args and
+ * conflicting sources, reads the chosen source, strips a UTF-8 BOM, and
+ * rejects empty scripts. Returns the script plus source metadata so plan or
+ * replay payloads can hash the script and reference the source without
+ * embedding its contents.
+ */
+export function resolveCodeInputWithSource(args, flags) {
     if (args.length > 0) {
         throw new UsageError(`code run takes no positional arguments; pass the script via --file PATH or --stdin. Usage: ${CODE_RUN_USAGE}`);
     }
     const sources = [];
     if (typeof flags["file"] === "string") {
-        sources.push({ label: "--file", read: () => readFileSync(flags["file"], "utf-8"), });
+        sources.push({
+            kind: "file",
+            label: "--file",
+            path: flags["file"],
+            read: () => readCodeSourceFile(flags["file"]),
+        });
     }
     if (flags["stdin"] === true) {
-        sources.push({ label: "--stdin", read: readStdinText, });
+        sources.push({ kind: "stdin", label: "--stdin", read: readStdinText, });
     }
     if (sources.length === 0) {
         throw new UsageError(`Python source is required: pass --file PATH or --stdin. Usage: ${CODE_RUN_USAGE}`);
@@ -19,23 +46,63 @@ function resolveCodeInput(args, flags) {
     if (sources.length > 1) {
         throw new UsageError(`Choose exactly one Python source: --file or --stdin. Usage: ${CODE_RUN_USAGE}`);
     }
-    const script = stripUtf8Bom(sources[0].read());
+    const source = sources[0];
+    const script = stripUtf8Bom(source.read());
     if (script.trim().length === 0) {
-        throw new UsageError(`Python source from ${sources[0].label} must not be empty. Usage: ${CODE_RUN_USAGE}`);
+        throw new UsageError(`Python source from ${source.label} must not be empty. Usage: ${CODE_RUN_USAGE}`);
+    }
+    return {
+        script,
+        source: source.kind === "file" ? { kind: "file", path: source.path, } : { kind: "stdin", },
+    };
+}
+export function resolveCodeInput(args, flags) {
+    return resolveCodeInputWithSource(args, flags).script;
+}
+/** Parse an integer flag value, rejecting negative and fractional values before any DSS request. */
+export function parseCodeRunIntegerFlag(value, flagName) {
+    const parsed = num(value, flagName);
+    if (parsed === undefined)
+        return undefined;
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        const valuePreview = previewFlagValue(value);
+        throw new UsageError(`Invalid value for ${flagName}: expected a non-negative integer, got ${valuePreview}.`, "invalid_flag_value", undefined, { flag: flagName, value: valuePreview, });
     }
-    return script;
+    return parsed;
+}
+function reportCleanupFailure(cleanupFailure) {
+    enqueueCliWarning({
+        type: "code_run_cleanup_failed",
+        scenarioId: cleanupFailure.scenarioId,
+        error: cleanupFailure.error,
+    });
+}
+function unwrapCodeRunError(error) {
+    if (error instanceof ScenarioScriptRunWithCleanupFailureError) {
+        reportCleanupFailure(error.cleanupFailure);
+        return error.cause;
+    }
+    return error;
 }
 export const codeCommands = {
     run: {
         handler: async (c, a, f) => {
+            const timeoutMs = parseCodeRunIntegerFlag(f["timeout"], "--timeout");
+            const maxLogBytes = parseCodeRunIntegerFlag(f["max-log-bytes"], "--max-log-bytes");
             const script = resolveCodeInput(a, f);
-            const run = await c.scenarios.runScript(script, {
-                envName: f["env"],
-                projectKey: f["project-key"],
-                timeoutMs: num(f["timeout"], "--timeout"),
-                keepScenario: f["keep"] === true,
-                maxLogBytes: num(f["max-log-bytes"], "--max-log-bytes"),
-            });
+            let run;
+            try {
+                run = await c.scenarios.runScript(script, {
+                    envName: f["env"],
+                    projectKey: f["project-key"],
+                    timeoutMs,
+                    keepScenario: f["keep"] === true,
+                    maxLogBytes,
+                });
+            }
+            catch (error) {
+                throw unwrapCodeRunError(error);
+            }
             const result = {
                 outcome: run.outcome,
                 success: run.success,
@@ -45,14 +112,19 @@ export const codeCommands = {
                 output: run.output ?? "",
                 logTruncated: run.logTruncated,
                 maxLogBytes: run.maxLogBytes,
+                cleanup: run.cleanup,
+                ...(run.timedOut === true ? { timedOut: true, timeoutMs: run.timeoutMs, } : {}),
             };
             if (f["full-log"] === true || run.output === undefined) {
                 result.log = run.log;
             }
+            if (run.cleanup.status === "failed") {
+                reportCleanupFailure({ scenarioId: run.scenarioId, error: run.cleanup.error ?? "unknown", });
+            }
             return result;
         },
         usage: CODE_RUN_USAGE,
-        description: "Run one-off Python in a DSS code env via a throwaway custom-python scenario; returns the script's captured output (stdout+stderr) plus outcome/success. Log retrieval is capped by --max-log-bytes (default 1048576); pass --full-log to include the capped raw DSS run log. Exits 4 on a non-SUCCESS outcome.",
+        description: "Run Python through a throwaway custom-python scenario and return captured output plus outcome. --timeout caps waiting; --max-log-bytes caps logs; --full-log returns the capped raw log. Exits 4 unless outcome is SUCCESS.",
         examples: [
             "dss code run --file inspect.py",
             "dss code run --file inspect.py --env py39_pandas",

package/dist/src/cli/commands/dataset.js

@@ -314,6 +314,7 @@ export const datasetCommands = {
                 outputPath: f["output"],
                 projectKey: f["project-key"],
                 limit: num(f["limit"], "--limit"),
+                rawData: f["raw-data"] === true,
             });
             if (result.truncated) {
                 enqueueCliWarning({
@@ -337,9 +338,13 @@ export const datasetCommands = {
             }
             return result;
         },
-        usage: "dss dataset download <name> [--output PATH] [--limit N] [--project-key KEY]",
-        description: "Download up to --limit rows (default 100k) as CSV; returns { path, rows, truncated, limit }. When truncated, a dataset_download_truncated warning is written to stderr; when --output is omitted, a dataset_download_default_location warning names the file's path in the working directory so the write is never silent.",
-        examples: ["dss dataset download orders", "dss dataset download orders --output ./data/",],
+        usage: "dss dataset download <name> [--output PATH] [--limit N] [--raw-data] [--project-key KEY]",
+        description: "Download up to --limit rows (default 100k) as CSV and return { path, rows, truncated, limit }. Formula-like cells are neutralized for spreadsheets; --raw-data preserves exact bytes. Warnings report truncation and the default output path.",
+        examples: [
+            "dss dataset download orders",
+            "dss dataset download orders --output ./data/",
+            "dss dataset download orders --raw-data",
+        ],
     },
     create: {
         handler: async (c, _a, f) => {

package/dist/src/cli/commands/flow-zone.js

@@ -1,5 +1,6 @@
+import { ClientValidationError, } from "../../errors.js";
 import { deepMerge, } from "../../utils/deep-merge.js";
-import { ensureFlowZonePlanTarget, findFlowZoneForPlan, flowZoneColor, flowZoneContains, flowZoneCurrentPosition, flowZoneDetailSummary, flowZoneId, flowZoneMoveItems, flowZoneName, flowZoneOrganizeStep, flowZonePlanItemKeys, flowZonePruneItems, flowZoneSamePosition, flowZoneSummary, readFlowZoneOrganizePlan, resolveFlowZoneIdFromFlags, throwFlowZoneValidationError, validateFlowZoneOrganizeObjects, } from "../helpers/flow-zone.js";
+import { ensureFlowZonePlanTarget, findFlowZoneForPlan, flowZoneColor, flowZoneContains, flowZoneCurrentPosition, flowZoneDetailSummary, flowZoneId, flowZoneMoveDelta, flowZoneMoveItems, flowZoneName, flowZoneOrganizeStep, flowZonePlanFromZones, flowZonePlanItemKeys, flowZonePruneItems, flowZoneSamePosition, flowZoneSummary, readFlowZoneOrganizePlan, resolveFlowZoneIdFromFlags, throwFlowZoneValidationError, validateFlowZoneOrganizeObjects, } from "../helpers/flow-zone.js";
 import { readIfExists, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
 export const flowZoneCommands = {
@@ -166,6 +167,19 @@ export const flowZoneCommands = {
             "dss flow-zone move ZONE_ID --object SAVED_MODEL:model_id",
         ],
     },
+    plan: {
+        handler: async (c, _a, f) => {
+            const pk = f["project-key"];
+            const [zones, topologyFingerprint,] = await Promise.all([
+                c.flowZones.list(pk),
+                c.projects.topologyFingerprint(pk),
+            ]);
+            return flowZonePlanFromZones(zones, topologyFingerprint);
+        },
+        usage: "dss flow-zone plan [--project-key KEY]",
+        description: "Export current visual flow-zone organization as an organize-compatible plan.",
+        examples: ["dss flow-zone plan --project-key MYPROJ",],
+    },
     organize: {
         handler: async (c, _a, f) => {
             const usage = "dss flow-zone organize (--data JSON|--data-file PATH|--file PATH|--stdin) [--sync] [--validate-objects] [--dry-run] [--project-key KEY]";
@@ -173,7 +187,13 @@ export const flowZoneCommands = {
             const plan = readFlowZoneOrganizePlan(f, usage);
             const sync = f["sync"] === true;
             const validateObjects = f["validate-objects"] === true;
-            const zones = await c.flowZones.list(pk);
+            const [zones, topologyFingerprint,] = await Promise.all([
+                c.flowZones.list(pk),
+                c.projects.topologyFingerprint(pk),
+            ]);
+            if (plan.topologyFingerprint && plan.topologyFingerprint !== topologyFingerprint) {
+                throw new ClientValidationError("Flow topology changed after this visual organization plan was generated.", "assertion_failed", "Regenerate the plan with dss flow-zone plan, then review it before applying.", { expected: plan.topologyFingerprint, actual: topologyFingerprint, });
+            }
             const plannedItemKeys = flowZonePlanItemKeys(plan);
             const planned = plan.zones.map((zonePlan) => flowZoneOrganizeStep(zonePlan, findFlowZoneForPlan(zones, zonePlan), sync, plannedItemKeys));
             const validation = validateObjects
@@ -194,6 +214,7 @@ export const flowZoneCommands = {
                     projectKey: pk,
                     sync,
                     validateObjects,
+                    topologyFingerprint,
                     zoneCount: plan.zones.length,
                     itemCount,
                     pruneItemCount,
@@ -209,6 +230,7 @@ export const flowZoneCommands = {
             for (const zonePlan of plan.zones) {
                 let zone = findFlowZoneForPlan(currentZones, zonePlan);
                 ensureFlowZonePlanTarget(zonePlan, zone);
+                const moveItems = flowZoneMoveDelta(zone, zonePlan.items);
                 const pruneItems = sync ? flowZonePruneItems(zone, plannedItemKeys) : [];
                 if (!zone) {
                     zone = await c.flowZones.create({
@@ -238,15 +260,19 @@ export const flowZoneCommands = {
                         updated.push(zone);
                     }
                 }
-                if (zonePlan.items.length > 0) {
-                    await c.flowZones.moveItems(zone.id, zonePlan.items, pk);
-                    moved.push({ zoneId: zone.id, name: zone.name, items: zonePlan.items, });
+                if (moveItems.length > 0) {
+                    await c.flowZones.moveItems(zone.id, moveItems, pk);
+                    moved.push({ zoneId: zone.id, name: zone.name, items: moveItems, });
                 }
                 if (pruneItems.length > 0) {
                     await c.flowZones.moveItems("default", pruneItems, pk);
                     pruned.push({ zoneId: "default", fromZoneId: zone.id, name: zone.name, items: pruneItems, });
                 }
             }
+            const topologyFingerprintAfter = await c.projects.topologyFingerprint(pk);
+            if (topologyFingerprintAfter !== topologyFingerprint) {
+                throw new ClientValidationError("Visual flow-zone changes modified flow topology.", "assertion_failed", "Inspect the flow before applying any further organization changes.", { before: topologyFingerprint, after: topologyFingerprintAfter, });
+            }
             return {
                 organized: true,
                 action: "organize",
@@ -254,6 +280,8 @@ export const flowZoneCommands = {
                 projectKey: pk,
                 sync,
                 validateObjects,
+                topologyFingerprint,
+                topologyUnchanged: true,
                 zoneCount: plan.zones.length,
                 itemCount,
                 pruneItemCount,

package/dist/src/cli/commands/notebook.js

@@ -1,12 +1,17 @@
-import { jsonInput, num, } from "../coerce.js";
-import { encodedProjectEndpoint, isNotFoundError, readIfExists, skipResult, } from "../output.js";
-import { requireArgs, UsageError, } from "../usage.js";
+import { jsonInput, num, parseBooleanOption, } from "../coerce.js";
+import { encodedProjectEndpoint, readIfExists, skipResult, } from "../output.js";
+import { requireArgs, requireNoArgs, UsageError, } from "../usage.js";
 export const notebookCommands = {
     "list-jupyter": {
-        handler: (c, _a, f) => c.notebooks.listJupyter(f["project-key"]),
-        usage: "dss notebook list-jupyter [--project-key KEY]",
-        description: "List Jupyter notebooks.",
-        examples: ["dss notebook list-jupyter",],
+        handler: (c, _a, f) => c.notebooks.listJupyter(f["project-key"], {
+            active: parseBooleanOption(f["active"], "--active"),
+        }),
+        usage: "dss notebook list-jupyter [--active true|false] [--project-key KEY]",
+        description: "List Jupyter notebooks. Pass --active to use the official ?active= filter: true lists currently running notebooks, false lists non-running ones.",
+        examples: [
+            "dss notebook list-jupyter",
+            "dss notebook list-jupyter --active true",
+        ],
     },
     "get-jupyter": {
         handler: (c, a, f) => {
@@ -41,22 +46,19 @@ export const notebookCommands = {
             requireArgs(a, 1, "dss notebook clear-jupyter-outputs <name>");
             const pk = f["project-key"];
             if (f["dry-run"] === true) {
+                // The real mutation is a single server-side DELETE of the
+                // outputs endpoint, so the dry run can only report the current
+                // content (read-only) and the exact request that would run; the
+                // stripped `next` shape would misdescribe the operation.
                 const current = await c.notebooks.getJupyter(a[0], pk);
-                const next = {
-                    ...current,
-                    cells: current.cells.map((cell) => {
-                        if (cell.cell_type !== "code")
-                            return cell;
-                        return { ...cell, outputs: [], execution_count: 0, };
-                    }),
-                };
                 return {
                     dryRun: true,
                     action: "clear-jupyter-outputs",
                     resource: "jupyter-notebook",
                     name: a[0],
                     current,
-                    next,
+                    endpoint: encodedProjectEndpoint(c, pk, `/jupyter-notebooks/${encodeURIComponent(a[0])}/outputs`),
+                    method: "DELETE",
                 };
             }
             await c.notebooks.clearJupyterOutputs(a[0], pk);
@@ -77,8 +79,33 @@ export const notebookCommands = {
     },
     "unload-jupyter": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss notebook unload-jupyter <name> <sessionId>");
             const pk = f["project-key"];
+            if (f["all"] === true) {
+                requireNoArgs(a, "dss notebook unload-jupyter --all [--dry-run] [--project-key KEY]");
+                if (f["dry-run"] === true) {
+                    const planned = [];
+                    for (const notebook of await c.notebooks.listJupyter(pk, { active: true, })) {
+                        for (const session of await c.notebooks.listJupyterSessions(notebook.name, pk)) {
+                            planned.push({
+                                name: notebook.name,
+                                sessionId: session.sessionId,
+                                endpoint: encodedProjectEndpoint(c, pk, `/jupyter-notebooks/${encodeURIComponent(notebook.name)}/sessions/${encodeURIComponent(session.sessionId)}`),
+                                method: "DELETE",
+                            });
+                        }
+                    }
+                    return {
+                        dryRun: true,
+                        action: "unload-jupyter",
+                        resource: "jupyter-notebook",
+                        all: true,
+                        planned,
+                    };
+                }
+                const unloaded = await c.notebooks.unloadJupyterAll(pk);
+                return { unloaded, resource: "jupyter-notebook", all: true, };
+            }
+            requireArgs(a, 2, "dss notebook unload-jupyter <name> <sessionId>");
             if (f["dry-run"] === true) {
                 const sessions = await c.notebooks.listJupyterSessions(a[0], pk);
                 const current = sessions.find((session) => session.sessionId === a[1]);
@@ -96,9 +123,12 @@ export const notebookCommands = {
             await c.notebooks.unloadJupyter(a[0], a[1], pk);
             return { unloaded: a[0], sessionId: a[1], resource: "jupyter-notebook", };
         },
-        usage: "dss notebook unload-jupyter <name> <sessionId> [--dry-run] [--project-key KEY]",
-        description: "Unload a Jupyter notebook kernel session.",
-        examples: ["dss notebook unload-jupyter my_notebook SESSION_ID --dry-run",],
+        usage: "dss notebook unload-jupyter (<name> <sessionId>|--all) [--dry-run] [--project-key KEY]",
+        description: "Unload a Jupyter notebook kernel session, or every session of every running notebook with --all.",
+        examples: [
+            "dss notebook unload-jupyter my_notebook SESSION_ID --dry-run",
+            "dss notebook unload-jupyter --all --dry-run",
+        ],
     },
     "list-sql": {
         handler: (c, _a, f) => c.notebooks.listSql(f["project-key"]),
@@ -162,18 +192,18 @@ export const notebookCommands = {
                     next: data,
                 };
             }
-            try {
-                await c.notebooks.saveJupyter(a[0], data, pk);
-            }
-            catch (error) {
-                if (!isNotFoundError(error))
-                    throw error;
-                await c.notebooks.createJupyter(a[0], data, pk);
-            }
-            return { saved: a[0], resource: "jupyter-notebook", };
+            const result = await c.notebooks.saveOrCreateJupyter(a[0], data, pk, {
+                expectHash: f["expect-hash"],
+            });
+            return {
+                saved: a[0],
+                resource: "jupyter-notebook",
+                created: result.created,
+                hash: result.hash,
+            };
         },
-        usage: "dss notebook save-jupyter <name> (--data '{...}' | --data-file PATH | --stdin) [--dry-run] [--project-key KEY]",
-        description: "Save content to a Jupyter notebook, creating it if missing.",
+        usage: "dss notebook save-jupyter <name> (--data '{...}' | --data-file PATH | --stdin) [--expect-hash SHA256] [--dry-run] [--project-key KEY]",
+        description: "Save content to a Jupyter notebook, creating it if missing. Reports created versus updated and the persisted content hash; --expect-hash aborts with a stale-read error when the stored content hash changed.",
         examples: [
             "dss notebook save-jupyter my_notebook --data-file notebook.json --dry-run",
             "cat notebook.json | dss notebook save-jupyter my_notebook --stdin",
@@ -198,17 +228,18 @@ export const notebookCommands = {
                     next: data,
                 };
             }
-            const current = await readIfExists(() => c.notebooks.getSql(a[0], pk));
-            if (current) {
-                await c.notebooks.saveSql(a[0], data, pk);
-            }
-            else {
-                await c.notebooks.createSql(a[0], data, pk);
-            }
-            return { saved: a[0], resource: "sql-notebook", };
+            const result = await c.notebooks.saveOrCreateSql(a[0], data, pk, {
+                expectHash: f["expect-hash"],
+            });
+            return {
+                saved: a[0],
+                resource: "sql-notebook",
+                created: result.created,
+                hash: result.hash,
+            };
         },
-        usage: "dss notebook save-sql <id> (--data '{...}' | --data-file PATH | --stdin) [--dry-run] [--project-key KEY]",
-        description: "Save content to a SQL notebook, creating it if missing.",
+        usage: "dss notebook save-sql <id> (--data '{...}' | --data-file PATH | --stdin) [--expect-hash SHA256] [--dry-run] [--project-key KEY]",
+        description: "Save content to a SQL notebook, creating it if missing. Reports created versus updated and the persisted content hash; --expect-hash rejects a stale read before writing.",
         examples: ["dss notebook save-sql my_sql_notebook --data-file content.json --dry-run",],
     },
     "clear-sql-history": {

package/dist/src/cli/commands/project-git.js

@@ -1,3 +1,4 @@
+import { validateGitReferencePath, } from "../../resources/project-git.js";
 import { num, parseBooleanOption, requiredStringFlag, } from "../coerce.js";
 import { CommandResultFailure, } from "../output.js";
 import { requireArgs, requireNoArgs, UsageError, } from "../usage.js";
@@ -448,8 +449,9 @@ export const projectGitCommands = {
     "set-library": {
         handler: async (c, a, f) => {
             requireArgs(a, 1, SET_LIBRARY_USAGE);
+            const targetPath = validateGitReferencePath(a[0]);
             const password = libraryPassword(f);
-            return sanitizeProjectGitOutput(await c.projectGit.setLibrary(requiredStringFlag(f, "project-key", SET_LIBRARY_USAGE), a[0], {
+            return sanitizeProjectGitOutput(await c.projectGit.setLibrary(requiredStringFlag(f, "project-key", SET_LIBRARY_USAGE), targetPath, {
                 repository: requiredStringFlag(f, "repository", SET_LIBRARY_USAGE),
                 pathInGitRepository: optionalStringFlag(f, "path-in-repository"),
                 checkout: requiredStringFlag(f, "checkout", SET_LIBRARY_USAGE),
@@ -466,10 +468,11 @@ export const projectGitCommands = {
     "remove-library": {
         handler: async (c, a, f) => {
             requireArgs(a, 1, REMOVE_LIBRARY_USAGE);
+            const targetPath = validateGitReferencePath(a[0]);
             const deleteDirectory = parseBooleanOption(f["delete-directory"], "--delete-directory")
                 ?? false;
-            await c.projectGit.removeLibrary(requiredStringFlag(f, "project-key", REMOVE_LIBRARY_USAGE), a[0], deleteDirectory);
-            return { removed: a[0], resource: "project-git-library", deleteDirectory, };
+            await c.projectGit.removeLibrary(requiredStringFlag(f, "project-key", REMOVE_LIBRARY_USAGE), targetPath, deleteDirectory);
+            return { removed: targetPath, resource: "project-git-library", deleteDirectory, };
         },
         usage: REMOVE_LIBRARY_USAGE,
         description: "Detach an external Git library. --delete-directory also removes its local directory from the project library.",
@@ -478,7 +481,7 @@ export const projectGitCommands = {
     "reset-library": {
         handler: (c, a, f) => {
             requireArgs(a, 1, RESET_LIBRARY_USAGE);
-            return c.projectGit.resetLibrary(requiredStringFlag(f, "project-key", RESET_LIBRARY_USAGE), a[0]);
+            return c.projectGit.resetLibrary(requiredStringFlag(f, "project-key", RESET_LIBRARY_USAGE), validateGitReferencePath(a[0]));
         },
         usage: RESET_LIBRARY_USAGE,
         description: "Reset one attached library to its remote state, discarding local edits. Returns the DSS future that performs the reset.",
@@ -487,7 +490,7 @@ export const projectGitCommands = {
     "push-library": {
         handler: (c, a, f) => {
             requireArgs(a, 1, PUSH_LIBRARY_USAGE);
-            return c.projectGit.pushLibrary(requiredStringFlag(f, "project-key", PUSH_LIBRARY_USAGE), a[0], requiredStringFlag(f, "message", PUSH_LIBRARY_USAGE));
+            return c.projectGit.pushLibrary(requiredStringFlag(f, "project-key", PUSH_LIBRARY_USAGE), validateGitReferencePath(a[0]), requiredStringFlag(f, "message", PUSH_LIBRARY_USAGE));
         },
         usage: PUSH_LIBRARY_USAGE,
         description: "Commit and push one attached library. Returns the DSS future that performs the push.",

package/dist/src/cli/commands/project-library.d.ts

@@ -1,2 +1,23 @@
+import { type ProjectLibraryDiffResult } from "../../resources/project-library.js";
 import type { CommandMeta } from "../types.js";
+export interface ProjectLibraryPutPayload {
+    /** Where the written bytes come from: --content flag, --file, or --stdin. */
+    contentSource: "flag" | "file" | "stdin";
+    /** Local file path when contentSource is "file". */
+    file?: string;
+    /** Byte count of the content when it is available without consuming stdin. */
+    bytes?: number;
+    /** SHA-256 hex digest of the exact bytes to write, when safely available. */
+    sha256?: string;
+    /** SHA-256 hex digest the caller expects the remote file to carry before the write. */
+    expectSha256?: string;
+}
+/**
+ * Put-input metadata for plans and reports. Plans must never include content
+ * bytes: this helper reports only the source, byte count, and SHA-256 digest —
+ * and only when they are available without consuming stdin (dry-run keeps
+ * stdin unread, so the stdin source carries no size/hash).
+ */
+export declare function projectLibraryPutPayload(flags: Record<string, string | boolean>): ProjectLibraryPutPayload;
 export declare const projectLibraryCommands: Record<string, CommandMeta>;
+export type { ProjectLibraryDiffResult, };