dataiku-sdk 3.7.0 → 3.9.0

package/dist/src/resources/recipe-create.js

@@ -194,46 +194,158 @@ function processorStep(type, params) {
         alwaysShowComment: false,
     };
 }
+/** Prepare option groups, in the default step order. */
+export const PREPARE_STEP_KINDS = [
+    "rename",
+    "fillEmpty",
+    "formula",
+    "filter",
+    "dropColumns",
+    "keepColumns",
+];
+function isPrepareStepKind(value) {
+    return PREPARE_STEP_KINDS.includes(value);
+}
 /**
- * Prepare (shaker) steps from create options, in a fixed order: rename,
- * fill empty, formula column, row filter, drop columns, keep columns. Later
- * steps see renamed columns. Empty when no prepare option was given.
+ * Order the prepare option groups run in: `stepOrder` (the CLI passes the order
+ * the flags were typed in) first, then any group it leaves out in the default order.
  */
-export function prepareSteps(opts) {
-    const steps = [];
-    const renamings = (opts.rename ?? []).map((raw) => {
-        const [from, to,] = splitPair(raw, "--rename");
-        return { from, to, };
-    });
-    if (renamings.length > 0)
-        steps.push(processorStep("ColumnRenamer", { renamings, }));
-    for (const raw of opts.fillEmpty ?? []) {
-        const [column, value,] = splitPair(raw, "--fill-empty");
-        steps.push(processorStep("FillEmptyWithValue", { appliesTo: "SINGLE_COLUMN", columns: [column,], value, }));
+function prepareStepOrder(opts) {
+    const order = [];
+    for (const kind of opts.stepOrder ?? []) {
+        if (!isPrepareStepKind(kind)) {
+            throw new ClientValidationError(`Unknown stepOrder entry "${kind}"; expected one of ${PREPARE_STEP_KINDS.join(", ")}.`, "invalid_flag_value");
+        }
+        if (!order.includes(kind))
+            order.push(kind);
     }
-    if (opts.formula) {
-        const [column, expression,] = splitPair(opts.formula, "--formula");
-        steps.push(processorStep("CreateColumnWithGREL", { column, expression, }));
+    for (const kind of PREPARE_STEP_KINDS) {
+        if (!order.includes(kind))
+            order.push(kind);
     }
-    if (opts.filter) {
-        steps.push(processorStep("FilterOnCustomFormula", { expression: opts.filter, action: "KEEP_ROW", }));
+    return order;
+}
+/** Prepare steps for one option group (empty when the option was not given). */
+function prepareStepsFor(kind, opts) {
+    switch (kind) {
+        case "rename": {
+            const renamings = (opts.rename ?? []).map((raw) => {
+                const [from, to,] = splitPair(raw, "--rename");
+                return { from, to, };
+            });
+            return renamings.length > 0 ? [processorStep("ColumnRenamer", { renamings, }),] : [];
+        }
+        case "fillEmpty":
+            return (opts.fillEmpty ?? []).map((raw) => {
+                const [column, value,] = splitPair(raw, "--fill-empty");
+                return processorStep("FillEmptyWithValue", {
+                    appliesTo: "SINGLE_COLUMN",
+                    columns: [column,],
+                    value,
+                });
+            });
+        case "formula": {
+            if (!opts.formula)
+                return [];
+            const [column, expression,] = splitPair(opts.formula, "--formula");
+            return [processorStep("CreateColumnWithGREL", { column, expression, }),];
+        }
+        case "filter":
+            return opts.filter
+                ? [processorStep("FilterOnCustomFormula", { expression: opts.filter, action: "KEEP_ROW", }),]
+                : [];
+        case "dropColumns":
+            return opts.dropColumns?.length
+                ? [processorStep("ColumnsSelector", {
+                        appliesTo: "COLUMNS",
+                        columns: opts.dropColumns,
+                        keep: false,
+                    }),]
+                : [];
+        case "keepColumns":
+            return opts.keepColumns?.length
+                ? [processorStep("ColumnsSelector", {
+                        appliesTo: "COLUMNS",
+                        columns: opts.keepColumns,
+                        keep: true,
+                    }),]
+                : [];
     }
-    if (opts.dropColumns?.length) {
-        steps.push(processorStep("ColumnsSelector", {
-            appliesTo: "COLUMNS",
-            columns: opts.dropColumns,
-            keep: false,
-        }));
+}
+/**
+ * Prepare (shaker) steps from create options: rename, fill empty, formula
+ * column, row filter, drop columns, keep columns. They run in `stepOrder`
+ * (flag order on the CLI), defaulting to that sequence, so a step sees the
+ * columns the steps before it produced. Empty when no prepare option was given.
+ */
+export function prepareSteps(opts) {
+    return prepareStepOrder(opts).flatMap((kind) => prepareStepsFor(kind, opts));
+}
+/**
+ * Columns an expression refers to, conservatively: `val('name')` arguments
+ * plus bare identifiers outside string literals (not method names, calls, or
+ * members of another object).
+ */
+function expressionColumnReferences(expression) {
+    const references = new Set();
+    for (const match of expression.matchAll(/\bval\(\s*(['"])((?:\\.|(?!\1).)*)\1\s*\)/g)) {
+        references.add(match[2]);
     }
-    if (opts.keepColumns?.length) {
-        steps.push(processorStep("ColumnsSelector", {
-            appliesTo: "COLUMNS",
-            columns: opts.keepColumns,
-            keep: true,
-        }));
+    const withoutStrings = expression.replace(/(['"])(?:\\.|(?!\1).)*\1/g, " ");
+    for (const match of withoutStrings.matchAll(/(?<![\w.$])([A-Za-z_]\w*)(?!\w)(?!\s*\()/g)) {
+        references.add(match[1]);
     }
-    return steps;
+    return references;
 }
+/**
+ * Warnings about the prepare options that DSS cannot report itself: a
+ * `--formula`/`--filter` that runs after a `--rename` but still names a
+ * column that rename removed (it would fail or read an empty column).
+ */
+export function recipeCreateWarnings(opts) {
+    const warnings = [];
+    const removed = new Map();
+    for (const kind of prepareStepOrder(opts)) {
+        if (kind === "rename") {
+            const renamings = (opts.rename ?? []).map((raw) => splitPair(raw, "--rename"));
+            const targets = new Set(renamings.map(([, to,]) => to));
+            for (const [from, to,] of renamings) {
+                if (!targets.has(from))
+                    removed.set(from, to);
+            }
+        }
+        else if ((kind === "formula" && opts.formula) || (kind === "filter" && opts.filter)) {
+            const expression = kind === "formula"
+                ? splitPair(opts.formula, "--formula")[1]
+                : opts.filter;
+            const stale = [...expressionColumnReferences(expression),].filter((name) => removed.has(name));
+            if (stale.length === 0)
+                continue;
+            const flag = kind === "formula" ? "--formula" : "--filter";
+            warnings.push({
+                code: "recipe_formula_uses_renamed_column",
+                flag,
+                columns: stale.map((name) => ({ renamed: name, to: removed.get(name), })),
+                message: `${flag} runs after --rename and refers to ${stale.map((name) => `"${name}"`).join(", ")}, which the rename removed.`,
+                hint: `Use the new name (${stale.map((name) => removed.get(name)).join(", ")}), or put ${flag} before --rename on the command line: steps run in flag order.`,
+            });
+        }
+    }
+    return warnings;
+}
+/**
+ * Recipe types created from `creationSettings.virtualInputs` (dataikuapi's
+ * VirtualInputsSingleOutputRecipeCreator subclasses: join, fuzzyjoin, geojoin,
+ * vstack, generate_features). Live DSS 15: without it these are created with
+ * no inputs (and `generate_features` fails with a NullPointerException).
+ */
+const VIRTUAL_INPUT_RECIPE_TYPES = {
+    vstack: true,
+    join: true,
+    fuzzyjoin: true,
+    geojoin: true,
+    generate_features: true,
+};
 /**
  * Pure request construction for POST /recipes/ (no DSS calls). Shared with
  * `recipe create --plan` so the plan equals the request the command sends.
@@ -301,6 +413,10 @@ export function buildRecipeCreateRequest(opts, pk) {
     if (!Number.isFinite(fuzzyThreshold)) {
         throw new ClientValidationError("fuzzyThreshold must be a finite number.", "validation_failed");
     }
+    // Virtual-input recipes: DSS builds `inputs` from creationSettings.virtualInputs
+    // (dataikuapi VirtualInputsSingleOutputRecipeCreator) and ignores or drops the
+    // prototype's inputs, creating the recipe with `inputs: {}` and an empty payload.
+    const hasVirtualInputs = VIRTUAL_INPUT_RECIPE_TYPES[type] === true;
     const recipePrototype = {
         type,
         name,
@@ -312,7 +428,7 @@ export function buildRecipeCreateRequest(opts, pk) {
     if (payload !== undefined) {
         creationSettings.script = payload;
     }
-    if (type === "fuzzyjoin") {
+    if (hasVirtualInputs) {
         creationSettings.virtualInputs = recipeInputItems({ inputs, }).map((item) => item.ref);
     }
     return {

package/dist/src/resources/recipes.js

@@ -224,6 +224,18 @@ function shouldRetryRecipeCreateWithOutputProvisioning(error) {
 // ---------------------------------------------------------------------------
 // Resource
 // ---------------------------------------------------------------------------
+// DSS renames some recipe types server-side (e.g. prediction_scoring becomes
+// "score_<inputDataset>") and documents the creation response as the final
+// unique name: Body {"name": "recipe1"} ("Returns the final unique name of the
+// recipe"). The response name is the contract — falling back to the requested
+// name would mask a missing/invalid receipt, so a body without it is an error.
+function requireRecipeName(created) {
+    const name = asString(created?.["name"]);
+    if (!name) {
+        throw unexpectedResponseError('DSS create-recipe response did not include the final recipe name (documented body: {"name": ...}).');
+    }
+    return name;
+}
 export class RecipesResource extends BaseResource {
     /** List all recipes in a project. */
     async list(projectKey) {
@@ -511,34 +523,74 @@ export class RecipesResource extends BaseResource {
             }
         };
         let finalRecipeName;
-        // DSS renames some recipe types server-side (e.g. prediction_scoring
-        // becomes "score_<inputDataset>") and documents the creation response as
-        // the final unique name: Body {"name": "recipe1"} ("Returns the final
-        // unique name of the recipe"). The response name is the contract —
-        // falling back to the requested name would mask a missing/invalid
-        // receipt, so a body without it is an error.
+        // Datasets this call provisioned must not outlive a failed create: the
+        // failure is rethrown unchanged, with the rollback outcome in `details`.
+        // A failure can be ambiguous (timeout, 5xx after DSS committed, a body
+        // without the name), so a dataset some recipe already writes is kept:
+        // deleting it would break that recipe. DSS may rename the recipe, so the
+        // check reads the flow graph rather than the requested recipe name.
+        const rollbackProvisionedDatasets = async (error) => {
+            if (createdDatasets.length === 0)
+                throw error;
+            const deleted = [];
+            const failed = [];
+            const kept = [];
+            let producers;
+            try {
+                const { graph, } = await this.client.projects.flowTopology(pk);
+                producers = new Map(graph.edges.filter((edge) => edge.relation === "writes").map((edge) => [edge.to, edge.from,]));
+            }
+            catch (graphError) {
+                const reason = `could not read the flow graph to check for a recipe writing it (${graphError instanceof Error ? graphError.message : String(graphError)})`;
+                for (const name of createdDatasets)
+                    kept.push({ name, reason, });
+            }
+            for (const name of createdDatasets) {
+                if (!producers)
+                    break;
+                const producer = producers.get(name);
+                if (producer !== undefined) {
+                    kept.push({ name, reason: `written by recipe ${producer}`, });
+                    continue;
+                }
+                try {
+                    await this.client.del(`/public/api/projects/${enc}/datasets/${encodeURIComponent(name)}`);
+                    deleted.push(name);
+                }
+                catch (deleteError) {
+                    failed.push({
+                        name,
+                        error: deleteError instanceof Error ? deleteError.message : String(deleteError),
+                    });
+                }
+            }
+            if (error instanceof DataikuError || error instanceof ClientValidationError) {
+                error.details = {
+                    ...error.details,
+                    createdDatasetsDeleted: deleted,
+                    createdDatasetsNotDeleted: failed,
+                    ...(kept.length > 0 ? { createdDatasetsKept: kept, } : {}),
+                };
+            }
+            throw error;
+        };
         try {
-            if (rawConnection)
+            try {
+                if (rawConnection)
+                    await provisionOutputDatasets();
+                finalRecipeName = requireRecipeName(await createRecipe());
+            }
+            catch (error) {
+                if (!shouldRetryRecipeCreateWithOutputProvisioning(error)) {
+                    throw error;
+                }
+                usedOutputProvisioningFallback = true;
                 await provisionOutputDatasets();
-            const created = await createRecipe();
-            const receivedName = asString(created?.["name"]);
-            if (!receivedName) {
-                throw unexpectedResponseError('DSS create-recipe response did not include the final recipe name (documented body: {"name": ...}).');
+                finalRecipeName = requireRecipeName(await createRecipe());
             }
-            finalRecipeName = receivedName;
         }
         catch (error) {
-            if (!shouldRetryRecipeCreateWithOutputProvisioning(error)) {
-                throw error;
-            }
-            usedOutputProvisioningFallback = true;
-            await provisionOutputDatasets();
-            const retryCreated = await createRecipe();
-            const retryName = asString(retryCreated?.["name"]);
-            if (!retryName) {
-                throw unexpectedResponseError('DSS create-recipe response did not include the final recipe name (documented body: {"name": ...}).');
-            }
-            finalRecipeName = retryName;
+            await rollbackProvisionedDatasets(error);
         }
         // For join recipes: configure join conditions after creation
         let joinConfigured = false;
@@ -684,6 +736,7 @@ export class RecipesResource extends BaseResource {
             }
         }
         return {
+            ...(opts.name && opts.name !== finalRecipeName ? { requestedName: opts.name, } : {}),
             recipeName: finalRecipeName,
             type,
             createdDatasets,

package/dist/src/resources/sql.js

@@ -76,31 +76,70 @@ function sqlErrorDetailFromBody(body) {
     const match = trimmed.match(/\b[A-Z_]+(?:_ERROR|_NOT_FOUND|_MISMATCH|_DENIED|_EXCEEDED)\b[:\s-]+[^\n\r]+/);
     return match?.[0] ?? (isLikelySqlErrorDetail(trimmed) ? trimmed.slice(0, 500) : undefined);
 }
+/**
+ * JDBC/driver failures that mean the connection to the database broke or timed
+ * out mid-statement: a DML statement may already have committed, so these stay
+ * an unknown outcome even though they are SQL/JDBC-flavored.
+ */
+const SQL_CONNECTION_LOSS_TYPE = /transient|recoverable|timeout/i;
+const SQL_CONNECTION_LOSS_TEXT = /i\/o error|communication (?:link|error|failure)|connection (?:reset|closed|refused|lost|abort)|broken pipe|socket|timed out|network/i;
+/**
+ * Whether DSS answered with a definite refusal of the statement, as opposed to
+ * an unknown outcome (transport reset, timeout, bare gateway error). DSS runs the
+ * statement before answering the start POST, so a SQL-flavored error body (JDBC
+ * error, or an error type from a SQL/JDBC class) or a body DSS itself classifies
+ * as permission/not-found means the database rejected the statement — unless
+ * the error reports a lost or timed-out database connection.
+ */
+function isDefiniteSqlRejection(error, sqlDetail) {
+    if (error.status < 400)
+        return false;
+    let errorType;
+    try {
+        errorType = asRecord(JSON.parse(error.body))?.errorType;
+    }
+    catch {
+        errorType = undefined;
+    }
+    if (typeof errorType === "string" && SQL_CONNECTION_LOSS_TYPE.test(errorType))
+        return false;
+    if (SQL_CONNECTION_LOSS_TEXT.test(error.body))
+        return false;
+    if (sqlDetail)
+        return true;
+    if (error.category === "forbidden" || error.category === "not_found")
+        return true;
+    return typeof errorType === "string" && /sql|jdbc/i.test(errorType);
+}
 function withSqlErrorContext(error) {
     if (error instanceof DataikuError) {
         const detail = sqlErrorDetailFromBody(error.body);
-        if (detail) {
+        const definiteFailure = isDefiniteSqlRejection(error, detail);
+        if (detail || definiteFailure) {
             let body = error.body;
-            try {
-                const parsed = JSON.parse(error.body);
-                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                    body = JSON.stringify({
-                        ...parsed,
-                        message: `SQL query failed: ${detail}`,
-                        sqlError: detail,
-                    });
+            if (detail) {
+                try {
+                    const parsed = JSON.parse(error.body);
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        body = JSON.stringify({
+                            ...parsed,
+                            message: `SQL query failed: ${detail}`,
+                            sqlError: detail,
+                        });
+                    }
+                    else {
+                        body = `SQL query failed: ${detail}\n${error.body}`;
+                    }
                 }
-                else {
+                catch {
                     body = `SQL query failed: ${detail}\n${error.body}`;
                 }
             }
-            catch {
-                body = `SQL query failed: ${detail}\n${error.body}`;
-            }
             throw new DataikuError(error.status, error.statusText, body, error.retry, error.requestId, {
                 target: error.trustedTarget,
                 elapsedMs: error.trustedElapsedMs,
                 bodyTruncated: error.bodyTruncated,
+                definiteFailure,
             });
         }
     }

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

@@ -1,4 +1,5 @@
-import type { WikiArticleData, WikiSettings } from "../schemas.js";
+import { ClientValidationError } from "../errors.js";
+import type { WikiArticleAttachment, WikiArticleData, WikiSettings } from "../schemas.js";
 import { BaseResource } from "./base.js";
 export interface WikiArticleCreateOptions {
     name: string;
@@ -12,6 +13,37 @@ export interface WikiArticleUpdateOptions {
     data?: Record<string, unknown>;
     projectKey?: string;
 }
+export interface WikiAttachResult {
+    articleId: string;
+    projectKey: string;
+    fileName: string;
+    bytes: number;
+    /** The attachment DSS created, as re-read from the article. */
+    attachment: WikiArticleAttachment;
+    /** All attachments of the article after the upload. */
+    attachments: WikiArticleAttachment[];
+}
+export interface WikiDetachResult {
+    articleId: string;
+    projectKey: string;
+    /** The attachment that was removed. */
+    detached: WikiArticleAttachment;
+    /** Attachments left on the article. */
+    attachments: WikiArticleAttachment[];
+}
+export interface LocalWikiAttachmentFile {
+    path: string;
+    fileName: string;
+    bytes: number;
+}
+/** Attachments of an article; DSS omits the field when there are none. */
+export declare function wikiAttachments(data: WikiArticleData): WikiArticleAttachment[];
+/** The attachment with exactly this smart id, or undefined. */
+export declare function findWikiAttachment(data: WikiArticleData, smartId: string): WikiArticleAttachment | undefined;
+/** Coded not_found error for a smart id that is not attached to the article. */
+export declare function wikiAttachmentNotFound(data: WikiArticleData, smartId: string): ClientValidationError;
+/** Check that a local path is a readable regular file before any DSS call. */
+export declare function statWikiAttachmentFile(localPath: string): Promise<LocalWikiAttachmentFile>;
 export declare class WikiResource extends BaseResource {
     settings(projectKey?: string): Promise<WikiSettings>;
     /**
@@ -24,4 +56,18 @@ export declare class WikiResource extends BaseResource {
     create(opts: WikiArticleCreateOptions): Promise<WikiArticleData>;
     update(articleIdOrName: string, opts: WikiArticleUpdateOptions): Promise<WikiArticleData>;
     delete(articleIdOrName: string, projectKey?: string): Promise<void>;
+    /**
+     * Upload a local file and attach it to an article (multipart POST to
+     * /wiki/{id}/upload). DSS names the attachment after the file's basename and
+     * types it from the extension. The article is re-read to identify the new
+     * attachment.
+     */
+    attach(articleIdOrName: string, localPath: string, projectKey?: string): Promise<WikiAttachResult>;
+    /**
+     * Remove exactly one attachment (by smart id) from an article: the article is
+     * read, the entry filtered out of `article.attachments`, and the whole
+     * article PUT back. Throws a coded `not_found` error when the smart id is not
+     * attached.
+     */
+    detach(articleIdOrName: string, smartId: string, projectKey?: string): Promise<WikiDetachResult>;
 }

package/dist/src/resources/wiki.js

@@ -1,6 +1,36 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ClientValidationError, } from "../errors.js";
 import { WikiArticleDataArraySchema, WikiArticleDataSchema, WikiSettingsSchema, } from "../schemas.js";
 import { deepMerge, } from "../utils/deep-merge.js";
 import { BaseResource, } from "./base.js";
+/** Attachments of an article; DSS omits the field when there are none. */
+export function wikiAttachments(data) {
+    return data.article.attachments ?? [];
+}
+/** The attachment with exactly this smart id, or undefined. */
+export function findWikiAttachment(data, smartId) {
+    return wikiAttachments(data).find((attachment) => attachment.smartId === smartId);
+}
+/** Coded not_found error for a smart id that is not attached to the article. */
+export function wikiAttachmentNotFound(data, smartId) {
+    const available = wikiAttachments(data).flatMap((attachment) => attachment.smartId === undefined ? [] : [attachment.smartId,]);
+    return new ClientValidationError(`Attachment ${smartId} not found on wiki article ${data.article.id}.`, "not_found", "List attachments with `dss wiki get ARTICLE_ID` (article.attachments[].smartId), or pass --if-exists to treat absence as success.", { articleId: data.article.id, smartId, availableSmartIds: available, });
+}
+/** Check that a local path is a readable regular file before any DSS call. */
+export async function statWikiAttachmentFile(localPath) {
+    let stat;
+    try {
+        stat = await fs.promises.stat(localPath);
+    }
+    catch (error) {
+        throw new ClientValidationError(`Could not read attachment file ${localPath}: ${error instanceof Error ? error.message : String(error)}.`, "not_found", "Verify the file path and that it is readable.");
+    }
+    if (!stat.isFile()) {
+        throw new ClientValidationError(`${localPath} is not a regular file.`);
+    }
+    return { path: localPath, fileName: path.basename(localPath), bytes: stat.size, };
+}
 const WIKI_LIST_CONCURRENCY = 4;
 function taxonomyIds(nodes) {
     const ids = [];
@@ -77,4 +107,63 @@ export class WikiResource extends BaseResource {
         const current = await this.get(articleIdOrName, projectKey);
         await this.client.del(`/public/api/projects/${this.enc(projectKey)}/wiki/${encodeURIComponent(current.article.id)}`);
     }
+    /**
+     * Upload a local file and attach it to an article (multipart POST to
+     * /wiki/{id}/upload). DSS names the attachment after the file's basename and
+     * types it from the extension. The article is re-read to identify the new
+     * attachment.
+     */
+    async attach(articleIdOrName, localPath, projectKey) {
+        const file = await statWikiAttachmentFile(localPath);
+        const pk = this.resolveProjectKey(projectKey);
+        const before = await this.get(articleIdOrName, pk);
+        const articleId = before.article.id;
+        await this.client.uploadJson(`/public/api/projects/${encodeURIComponent(pk)}/wiki/${encodeURIComponent(articleId)}/upload`, localPath, file.fileName);
+        const after = await this.get(articleId, pk);
+        const knownIds = new Set(wikiAttachments(before).map((attachment) => attachment.smartId));
+        let created = wikiAttachments(after).filter((attachment) => !knownIds.has(attachment.smartId));
+        if (created.length > 1) {
+            created = created.filter((attachment) => attachment.details?.["objectDisplayName"] === file.fileName
+                && attachment.details?.["size"] === file.bytes);
+        }
+        const attachment = created[0];
+        if (created.length !== 1 || attachment === undefined || attachment.smartId === undefined) {
+            throw new ClientValidationError(`DSS did not verify upload of ${file.fileName} to wiki article ${articleId}.`, "ambiguous_outcome", "The upload returned successfully, but the article did not show exactly one new attachment. Inspect the article (dss wiki get) before retrying.", { articleId, expectedBytes: file.bytes, newAttachments: created, });
+        }
+        return {
+            articleId,
+            projectKey: pk,
+            fileName: file.fileName,
+            bytes: file.bytes,
+            attachment,
+            attachments: wikiAttachments(after),
+        };
+    }
+    /**
+     * Remove exactly one attachment (by smart id) from an article: the article is
+     * read, the entry filtered out of `article.attachments`, and the whole
+     * article PUT back. Throws a coded `not_found` error when the smart id is not
+     * attached.
+     */
+    async detach(articleIdOrName, smartId, projectKey) {
+        const pk = this.resolveProjectKey(projectKey);
+        const current = await this.get(articleIdOrName, pk);
+        const detached = findWikiAttachment(current, smartId);
+        if (detached === undefined)
+            throw wikiAttachmentNotFound(current, smartId);
+        const remaining = wikiAttachments(current).filter((attachment) => attachment.smartId !== smartId);
+        const raw = await this.client.put(`/public/api/projects/${encodeURIComponent(pk)}/wiki/${encodeURIComponent(current.article.id)}`, { ...current, article: { ...current.article, attachments: remaining, }, });
+        const saved = this.client.safeParse(WikiArticleDataSchema, raw, "wiki.detach");
+        const after = wikiAttachments(saved);
+        if (findWikiAttachment(saved, smartId) !== undefined
+            || after.length !== remaining.length) {
+            throw new ClientValidationError(`DSS did not verify removal of attachment ${smartId} from wiki article ${current.article.id}.`, "ambiguous_outcome", "The save returned successfully, but the article's attachments are not the expected remainder. Inspect the article (dss wiki get) before retrying.", {
+                articleId: current.article.id,
+                smartId,
+                expectedRemaining: remaining.length,
+                actualRemaining: after.length,
+            });
+        }
+        return { articleId: current.article.id, projectKey: pk, detached, attachments: after, };
+    }
 }

package/dist/src/utils/flow-analysis.js

@@ -345,6 +345,10 @@ function renderMermaid(map) {
             lines.push(`    ${idByNode.get(nodeId)}["${mermaidLabel(readableNode(node))}"]`);
         }
         lines.push("  end");
+        // Zone colors come from DSS; only plain #RRGGBB values reach the style line.
+        if (zone.color && /^#[0-9a-fA-F]{6}$/.test(zone.color)) {
+            lines.push(`  style z${zoneIndex} fill:${zone.color}22,stroke:${zone.color}`);
+        }
     }
     for (const edge of map.edges) {
         const from = idByNode.get(edge.from);

package/dist/src/utils/secret-sanitize.d.ts

@@ -7,8 +7,10 @@
  * - optionally redacts userinfo embedded in HTTP(S) URL authorities
  *   (`https://user:pass@host/...` -> `https://[redacted]@host/...`).
  *
- * The SDK resource layer forwards values verbatim to DSS over TLS; sanitization
- * is a CLI presentation concern and must never leak secret material instead.
+ * The SDK resource layer forwards values verbatim to DSS over TLS; sanitizing
+ * structured output is a CLI presentation concern and must never leak secret
+ * material instead. DSS-produced read text that consumers never need secrets
+ * from (job logs) is scrubbed at the SDK download via `redactCredentialPairs`.
  */
 /** Marker replacing every redacted value or secret occurrence. */
 export declare const SECRET_REDACTED = "[redacted]";
@@ -46,6 +48,13 @@ export declare function redactUrlUserinfo(text: string): string;
  * recurse, arrays recurse. Non-string scalars pass through unchanged.
  */
 export declare function sanitizeSecrets<T>(value: T, options: SecretSanitizeOptions): T;
+/**
+ * Redact the string value of every JSON-style `"key":"value"` pair in free
+ * text whose key is credential-like (e.g. the `jobTicketSecret` DSS writes
+ * into job logs). Bare `key` fields are not redacted here: in log text they
+ * name ordinary identifiers far more often than secrets.
+ */
+export declare function redactCredentialPairs(text: string): string;
 /**
  * Every string value under a credential-like key (any depth), plus bare
  * `key` fields such as `authRealm.key`. Collected from a command's own JSON