dataiku-sdk 3.0.0 → 3.1.0

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, };

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

@@ -1,24 +1,12 @@
 import * as fs from "node:fs";
-import { readStdinText, } from "../coerce.js";
-import { encodedProjectEndpoint, planResult, } from "../output.js";
+import { encodeLibraryPath, EXPECT_SHA256_PATTERN, validateLibraryDestinationPath, validateLibraryName, validateLibraryPath, } from "../../resources/project-library.js";
+import { numFlag, readStdinText, sha256Hex, } from "../coerce.js";
+import { encodedProjectEndpoint, planResult, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
 const PROJECT_LIBRARY_EXIT_CODES = { usage: 1, error: 2, transient: 3, };
-function normalizeLibraryPath(path) {
-    const normalized = path.replace(/^\/+/, "");
-    if (!normalized)
-        throw new Error("Project library path is required");
-    return normalized;
-}
-function normalizeLibraryDestinationPath(path) {
-    if (path === "/")
-        return "/";
-    return `/${normalizeLibraryPath(path)}`;
-}
-function encodeLibraryPath(path) {
-    return normalizeLibraryPath(path)
-        .split("/")
-        .map((segment) => encodeURIComponent(segment))
-        .join("/");
+const PUT_FLAG_ERROR_HINT = "Pass a 64-character SHA-256 hex digest (lowercase or uppercase).";
+function sha256BytesHex(bytes) {
+    return new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
 }
 function projectLibraryContentsEndpoint(client, projectKey, path) {
     return encodedProjectEndpoint(client, projectKey, `/libraries/contents/${encodeLibraryPath(path)}`);
@@ -29,22 +17,53 @@ function projectLibraryFolderEndpoint(client, projectKey, path) {
 function projectLibraryActionEndpoint(client, projectKey, action) {
     return encodedProjectEndpoint(client, projectKey, `/libraries/contents-actions/${action}`);
 }
-function projectLibraryPutPayload(flags) {
-    if (typeof flags["content"] === "string")
-        return { contentSource: "flag", };
-    if (typeof flags["file"] === "string")
-        return { contentSource: "file", file: flags["file"], };
-    return { contentSource: "stdin", };
+/**
+ * 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 function projectLibraryPutPayload(flags) {
+    const expectSha256 = expectSha256FromFlags(flags);
+    if (typeof flags["content"] === "string") {
+        const text = flags["content"];
+        return {
+            contentSource: "flag",
+            bytes: Buffer.byteLength(text, "utf8"),
+            sha256: sha256Hex(text),
+            ...(expectSha256 ? { expectSha256, } : {}),
+        };
+    }
+    if (typeof flags["file"] === "string") {
+        const bytes = fs.readFileSync(flags["file"]);
+        return {
+            contentSource: "file",
+            file: flags["file"],
+            bytes: bytes.length,
+            sha256: sha256BytesHex(bytes),
+            ...(expectSha256 ? { expectSha256, } : {}),
+        };
+    }
+    return { contentSource: "stdin", ...(expectSha256 ? { expectSha256, } : {}), };
 }
 function projectLibraryPlan(action, options) {
     return planResult("project-library", action, {
         ...options,
+        idempotency: options.idempotency ?? "none",
         asyncKind: "none",
         exitCodesOnFailure: PROJECT_LIBRARY_EXIT_CODES,
-        idempotency: "none",
         plannedAndDryRun: true,
     });
 }
+function expectSha256FromFlags(flags) {
+    const value = flags["expect-sha256"];
+    if (value === undefined || value === false)
+        return undefined;
+    if (typeof value !== "string" || !EXPECT_SHA256_PATTERN.test(value)) {
+        throw new UsageError("--expect-sha256 must be a 64-character SHA-256 hex digest.", "validation_failed", PUT_FLAG_ERROR_HINT);
+    }
+    return value;
+}
 export const projectLibraryCommands = {
     list: {
         handler: (c, _a, f) => c.projectLibrary.listContents(f["project-key"]),
@@ -55,6 +74,7 @@ export const projectLibraryCommands = {
     get: {
         handler: (c, a, f) => {
             requireArgs(a, 1, "dss project-library get <path> [--project-key KEY]");
+            validateLibraryPath(a[0]);
             return c.projectLibrary.getFile(a[0], f["project-key"]);
         },
         usage: "dss project-library get <path> [--project-key KEY]",
@@ -69,7 +89,7 @@ export const projectLibraryCommands = {
                 throw new UsageError("--output PATH is required.", "missing_required_flag");
             const bytes = await c.projectLibrary.getFileBytes(a[0], f["project-key"]);
             const written = await Bun.write(out, bytes, { createPath: false, });
-            return { path: out, bytes: written, };
+            return { path: out, bytes: written, sha256: sha256BytesHex(bytes), };
         },
         usage: "dss project-library get-bytes <path> --output PATH [--project-key KEY]",
         description: "Download a project library file's raw bytes to a local file.",
@@ -77,44 +97,62 @@ export const projectLibraryCommands = {
     },
     "create-file": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss project-library create-file <path> [--dry-run] [--project-key KEY]");
+            requireArgs(a, 1, "dss project-library create-file <path> [--if-not-exists] [--dry-run] [--project-key KEY]");
             const pk = f["project-key"];
+            validateLibraryPath(a[0]);
             if (f["dry-run"] === true) {
                 return projectLibraryPlan("create-file", {
                     method: "POST",
                     endpoint: projectLibraryContentsEndpoint(c, pk, a[0]),
                     identifiers: { path: a[0], },
+                    idempotency: "if-not-exists",
                 });
             }
+            if (f["if-not-exists"] === true) {
+                const exists = await c.projectLibrary.hasLibraryItem(a[0], pk);
+                if (exists) {
+                    return skipResult("project-library", a[0], "exists", { kind: "file", });
+                }
+            }
             await c.projectLibrary.addFile(a[0], pk);
             return { created: a[0], };
         },
-        usage: "dss project-library create-file <path> [--dry-run] [--project-key KEY]",
-        description: "Create an empty file in the project library.",
-        examples: ["dss project-library create-file python/mylib/new.py",],
+        usage: "dss project-library create-file <path> [--if-not-exists] [--dry-run] [--project-key KEY]",
+        description: "Create an empty file in the project library; refuses to overwrite an existing item.",
+        examples: ["dss project-library create-file python/mylib/new.py --if-not-exists",],
     },
     "create-folder": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss project-library create-folder <path> [--dry-run] [--project-key KEY]");
+            requireArgs(a, 1, "dss project-library create-folder <path> [--if-not-exists] [--dry-run] [--project-key KEY]");
             const pk = f["project-key"];
+            validateLibraryPath(a[0]);
             if (f["dry-run"] === true) {
                 return projectLibraryPlan("create-folder", {
                     method: "POST",
                     endpoint: projectLibraryFolderEndpoint(c, pk, a[0]),
                     identifiers: { path: a[0], },
+                    idempotency: "if-not-exists",
                 });
             }
+            if (f["if-not-exists"] === true) {
+                const exists = await c.projectLibrary.hasLibraryItem(a[0], pk);
+                if (exists) {
+                    return skipResult("project-library", a[0], "exists", { kind: "folder", });
+                }
+            }
             await c.projectLibrary.addFolder(a[0], pk);
             return { created: a[0], };
         },
-        usage: "dss project-library create-folder <path> [--dry-run] [--project-key KEY]",
-        description: "Create a folder in the project library.",
-        examples: ["dss project-library create-folder python/mylib",],
+        usage: "dss project-library create-folder <path> [--if-not-exists] [--dry-run] [--project-key KEY]",
+        description: "Create a folder in the project library; refuses to overwrite an existing item.",
+        examples: ["dss project-library create-folder python/mylib --if-not-exists",],
     },
     put: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss project-library put <path> (--content TEXT|--file PATH|--stdin) [--dry-run] [--project-key KEY]");
+            requireArgs(a, 1, "dss project-library put <path> (--content TEXT|--file PATH|--stdin) [--expect-sha256 SHA256] [--dry-run] [--project-key KEY]");
             const pk = f["project-key"];
+            const expectSha256 = expectSha256FromFlags(f);
+            validateLibraryPath(a[0]);
             if (f["dry-run"] === true) {
                 return projectLibraryPlan("put", {
                     method: "POST",
@@ -126,19 +164,48 @@ export const projectLibraryCommands = {
             const content = typeof f["content"] === "string"
                 ? f["content"]
                 : typeof f["file"] === "string"
-                    ? fs.readFileSync(f["file"], "utf-8")
+                    ? fs.readFileSync(f["file"])
+                    : await readStdinText();
+            const result = await c.projectLibrary.addOrUpdateFile(a[0], content, pk, expectSha256 !== undefined ? { expectSha256, } : undefined);
+            return {
+                updated: result.path,
+                bytes: result.bytes,
+                sha256: result.sha256,
+                ...(result.beforeSha256 !== undefined ? { beforeSha256: result.beforeSha256, } : {}),
+            };
+        },
+        usage: "dss project-library put <path> (--content TEXT|--file PATH|--stdin) [--expect-sha256 SHA256] [--dry-run] [--project-key KEY]",
+        description: "Create or overwrite a project library file with text or binary content; reports the written byte count and sha256.",
+        examples: [
+            "dss project-library put python/mylib/utils.py --file ./utils.py",
+            "dss project-library put python/mylib/utils.py --file ./utils.py --expect-sha256 <previous-sha256>",
+        ],
+    },
+    diff: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss project-library diff <path> (--content TEXT|--file PATH|--stdin) [--max-lines N] [--project-key KEY]");
+            const pk = f["project-key"];
+            validateLibraryPath(a[0]);
+            const maxLines = numFlag(f, ["max-lines",]);
+            const local = typeof f["content"] === "string"
+                ? f["content"]
+                : typeof f["file"] === "string"
+                    ? fs.readFileSync(f["file"])
                     : await readStdinText();
-            await c.projectLibrary.addOrUpdateFile(a[0], content, pk);
-            return { updated: a[0], };
+            return c.projectLibrary.diffFile(a[0], local, pk, maxLines !== undefined ? { maxLines, } : {});
         },
-        usage: "dss project-library put <path> (--content TEXT|--file PATH|--stdin) [--dry-run] [--project-key KEY]",
-        description: "Create or overwrite a project library file with raw text content.",
-        examples: ["dss project-library put python/mylib/utils.py --file ./utils.py",],
+        usage: "dss project-library diff <path> (--content TEXT|--file PATH|--stdin) [--max-lines N] [--project-key KEY]",
+        description: "Diff a project library file against local content; capped unified text diff, binary files detected instead of dumped.",
+        examples: [
+            "dss project-library diff python/mylib/utils.py --file ./utils.py",
+            "dss project-library diff python/mylib/utils.py --content 'print(1)' --max-lines 50",
+        ],
     },
     delete: {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss project-library delete <path> [--dry-run] [--project-key KEY]");
             const pk = f["project-key"];
+            validateLibraryPath(a[0]);
             if (f["dry-run"] === true) {
                 return projectLibraryPlan("delete", {
                     method: "DELETE",
@@ -157,16 +224,18 @@ export const projectLibraryCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 2, "dss project-library rename <path> <new-name> [--dry-run] [--project-key KEY]");
             const pk = f["project-key"];
+            const validPath = validateLibraryPath(a[0]);
+            const validName = validateLibraryName(a[1]);
             if (f["dry-run"] === true) {
                 return projectLibraryPlan("rename", {
                     method: "POST",
                     endpoint: projectLibraryActionEndpoint(c, pk, "rename/"),
-                    identifiers: { path: a[0], newName: a[1], },
-                    payload: { oldPath: `/${normalizeLibraryPath(a[0])}`, newName: a[1], },
+                    identifiers: { path: validPath, newName: validName, },
+                    payload: { oldPath: `/${validPath}`, newName: validName, },
                 });
             }
-            await c.projectLibrary.rename(a[0], a[1], pk);
-            return { renamed: a[0], to: a[1], };
+            await c.projectLibrary.rename(validPath, validName, pk);
+            return { renamed: validPath, to: validName, };
         },
         usage: "dss project-library rename <path> <new-name> [--dry-run] [--project-key KEY]",
         description: "Rename a project library file or folder within its parent.",
@@ -176,19 +245,21 @@ export const projectLibraryCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 2, "dss project-library move <path> <destination-folder> [--dry-run] [--project-key KEY]");
             const pk = f["project-key"];
+            const validPath = validateLibraryPath(a[0]);
+            const destination = validateLibraryDestinationPath(a[1]);
             if (f["dry-run"] === true) {
                 return projectLibraryPlan("move", {
                     method: "POST",
                     endpoint: projectLibraryActionEndpoint(c, pk, "move"),
-                    identifiers: { path: a[0], destinationFolder: a[1], },
+                    identifiers: { path: validPath, destinationFolder: destination, },
                     payload: {
-                        oldPath: `/${normalizeLibraryPath(a[0])}`,
-                        newPath: normalizeLibraryDestinationPath(a[1]),
+                        oldPath: `/${validPath}`,
+                        newPath: destination,
                     },
                 });
             }
-            await c.projectLibrary.move(a[0], a[1], pk);
-            return { moved: a[0], to: a[1], };
+            await c.projectLibrary.move(validPath, destination, pk);
+            return { moved: validPath, to: destination, };
         },
         usage: "dss project-library move <path> <destination-folder> [--dry-run] [--project-key KEY]",
         description: "Move a project library file or folder into another folder.",

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

@@ -6,6 +6,13 @@ import { jsonInput, num, requiredJsonInput, requiredStringFlag, } from "../coerc
 import { CommandResultFailure, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
 const INSPECT_ARCHIVE_USAGE = "dss project inspect-archive <file>";
+function flowRenderFormat(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === "ascii" || value === "mermaid")
+        return value;
+    throw new UsageError("--render must be ascii or mermaid.", "invalid_enum");
+}
 /** Local, DSS-free archive inspection shared by the local handler and the command handler. */
 function inspectArchiveCommand(args) {
     requireArgs(args, 1, INSPECT_ARCHIVE_USAGE);
@@ -42,12 +49,19 @@ export const projectCommands = {
             maxNodes: num(f["max-nodes"], "--max-nodes"),
             maxEdges: num(f["max-edges"], "--max-edges"),
             includeRaw: f["include-raw"] === true,
+            render: flowRenderFormat(f["render"]),
         }),
-        usage: "dss project map [--max-nodes N] [--max-edges N] [--include-raw] [--project-key KEY]",
-        description: "Get a summarized, truncated flow map.",
+        validate: (_a, f) => {
+            flowRenderFormat(f["render"]);
+            num(f["max-nodes"], "--max-nodes");
+            num(f["max-edges"], "--max-edges");
+        },
+        usage: "dss project map [--max-nodes N] [--max-edges N] [--include-raw] [--render ascii|mermaid] [--project-key KEY]",
+        description: "Get an analyzed flow map with zones, layers, components, and diagnostics.",
         examples: [
             "dss project map",
             "dss project map --max-nodes 50 --max-edges 100",
+            "dss project map --render mermaid",
             "dss project map --include-raw",
         ],
     },