dataiku-sdk 3.2.0 → 3.3.0

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

@@ -1,80 +1,153 @@
-import { analysisCommands, } from "./analysis.js";
-import { apiDeployerCommands, } from "./api-deployer.js";
-import { apiServiceCommands, } from "./api-service.js";
-import { appCommands, } from "./app.js";
-import { bundleCommands, } from "./bundle.js";
-import { businessAppCommands, } from "./business-app.js";
-import { codeEnvCommands, } from "./code-env.js";
-import { codeCommands, } from "./code.js";
-import { connectionCommands, } from "./connection.js";
-import { continuousActivityCommands, } from "./continuous-activity.js";
-import { dashboardCommands, } from "./dashboard.js";
-import { dataQualityCommands, } from "./data-quality.js";
-import { datasetCommands, } from "./dataset.js";
-import { discussionCommands, } from "./discussion.js";
-import { doctorCommands, } from "./doctor.js";
-import { flowZoneCommands, } from "./flow-zone.js";
-import { folderCommands, } from "./folder.js";
-import { futureCommands, } from "./future.js";
-import { insightCommands, } from "./insight.js";
-import { jobCommands, } from "./job.js";
-import { meaningCommands, } from "./meaning.js";
-import { metricsCommands, } from "./metrics.js";
-import { mlTaskCommands, } from "./ml-task.js";
-import { modelEvaluationStoreCommands, } from "./model-evaluation-store.js";
-import { notebookCommands, } from "./notebook.js";
-import { projectDeployerCommands, } from "./project-deployer.js";
-import { projectGitCommands, } from "./project-git.js";
-import { projectLibraryCommands, } from "./project-library.js";
-import { projectCommands, } from "./project.js";
-import { recipeCommands, } from "./recipe.js";
-import { savedModelCommands, } from "./saved-model.js";
-import { scenarioCommands, } from "./scenario.js";
-import { sqlCommands, } from "./sql.js";
-import { statisticsCommands, } from "./statistics.js";
-import { streamingEndpointCommands, } from "./streaming-endpoint.js";
-import { variableCommands, } from "./variable.js";
-import { webappCommands, } from "./webapp.js";
-import { wikiCommands, } from "./wiki.js";
-import { workspaceCommands, } from "./workspace.js";
+// Bun caches these synchronous module loads. Enumerating resource names stays
+// cheap; looking up one resource loads only its command definitions.
 export const commands = {
-    project: projectCommands,
-    analysis: analysisCommands,
-    "ml-task": mlTaskCommands,
-    "saved-model": savedModelCommands,
-    "model-evaluation-store": modelEvaluationStoreCommands,
-    app: appCommands,
-    "business-app": businessAppCommands,
-    webapp: webappCommands,
-    "api-service": apiServiceCommands,
-    "api-deployer": apiDeployerCommands,
-    bundle: bundleCommands,
-    "project-deployer": projectDeployerCommands,
-    "project-git": projectGitCommands,
-    "project-library": projectLibraryCommands,
-    "streaming-endpoint": streamingEndpointCommands,
-    "continuous-activity": continuousActivityCommands,
-    statistics: statisticsCommands,
-    discussion: discussionCommands,
-    meaning: meaningCommands,
-    workspace: workspaceCommands,
-    metrics: metricsCommands,
-    doctor: doctorCommands,
-    wiki: wikiCommands,
-    dashboard: dashboardCommands,
-    insight: insightCommands,
-    "data-quality": dataQualityCommands,
-    future: futureCommands,
-    "flow-zone": flowZoneCommands,
-    dataset: datasetCommands,
-    recipe: recipeCommands,
-    job: jobCommands,
-    scenario: scenarioCommands,
-    folder: folderCommands,
-    variable: variableCommands,
-    connection: connectionCommands,
-    "code-env": codeEnvCommands,
-    sql: sqlCommands,
-    code: codeCommands,
-    notebook: notebookCommands,
+    get "project"() {
+        return require("./project.js").projectCommands;
+    },
+    get "analysis"() {
+        return require("./analysis.js").analysisCommands;
+    },
+    get "ml-task"() {
+        return require("./ml-task.js").mlTaskCommands;
+    },
+    get "saved-model"() {
+        return require("./saved-model.js").savedModelCommands;
+    },
+    get "model-evaluation-store"() {
+        return require("./model-evaluation-store.js")
+            .modelEvaluationStoreCommands;
+    },
+    get "app"() {
+        return require("./app.js").appCommands;
+    },
+    get "business-app"() {
+        return require("./business-app.js").businessAppCommands;
+    },
+    get "webapp"() {
+        return require("./webapp.js").webappCommands;
+    },
+    get "api-service"() {
+        return require("./api-service.js").apiServiceCommands;
+    },
+    get "api-deployer"() {
+        return require("./api-deployer.js").apiDeployerCommands;
+    },
+    get "bundle"() {
+        return require("./bundle.js").bundleCommands;
+    },
+    get "project-deployer"() {
+        return require("./project-deployer.js")
+            .projectDeployerCommands;
+    },
+    get "project-git"() {
+        return require("./project-git.js").projectGitCommands;
+    },
+    get "project-folder"() {
+        return require("./project-folder.js")
+            .projectFolderCommands;
+    },
+    get "project-library"() {
+        return require("./project-library.js")
+            .projectLibraryCommands;
+    },
+    get "streaming-endpoint"() {
+        return require("./streaming-endpoint.js")
+            .streamingEndpointCommands;
+    },
+    get "continuous-activity"() {
+        return require("./continuous-activity.js")
+            .continuousActivityCommands;
+    },
+    get "statistics"() {
+        return require("./statistics.js").statisticsCommands;
+    },
+    get "discussion"() {
+        return require("./discussion.js").discussionCommands;
+    },
+    get "meaning"() {
+        return require("./meaning.js").meaningCommands;
+    },
+    get "workspace"() {
+        return require("./workspace.js").workspaceCommands;
+    },
+    get "metrics"() {
+        return require("./metrics.js").metricsCommands;
+    },
+    get "doctor"() {
+        return require("./doctor.js").doctorCommands;
+    },
+    get "wiki"() {
+        return require("./wiki.js").wikiCommands;
+    },
+    get "dashboard"() {
+        return require("./dashboard.js").dashboardCommands;
+    },
+    get "insight"() {
+        return require("./insight.js").insightCommands;
+    },
+    get "data-quality"() {
+        return require("./data-quality.js").dataQualityCommands;
+    },
+    get "future"() {
+        return require("./future.js").futureCommands;
+    },
+    get "flow-zone"() {
+        return require("./flow-zone.js").flowZoneCommands;
+    },
+    get "dataset"() {
+        return require("./dataset.js").datasetCommands;
+    },
+    get "recipe"() {
+        return require("./recipe.js").recipeCommands;
+    },
+    get "job"() {
+        return require("./job.js").jobCommands;
+    },
+    get "scenario"() {
+        return require("./scenario.js").scenarioCommands;
+    },
+    get "folder"() {
+        return require("./folder.js").folderCommands;
+    },
+    get "variable"() {
+        return require("./variable.js").variableCommands;
+    },
+    get "connection"() {
+        return require("./connection.js").connectionCommands;
+    },
+    get "code-env"() {
+        return require("./code-env.js").codeEnvCommands;
+    },
+    get "sql"() {
+        return require("./sql.js").sqlCommands;
+    },
+    get "code"() {
+        return require("./code.js").codeCommands;
+    },
+    get "notebook"() {
+        return require("./notebook.js").notebookCommands;
+    },
+    get "user"() {
+        return require("./user.js").userCommands;
+    },
+    get "group"() {
+        return require("./group.js").groupCommands;
+    },
+    get "plugin"() {
+        return require("./plugin.js").pluginCommands;
+    },
+    get "llm"() {
+        return require("./llm.js").llmCommands;
+    },
+    get "knowledge-bank"() {
+        return require("./knowledge-bank.js")
+            .knowledgeBankCommands;
+    },
+    get "macro"() {
+        return require("./macro.js").macroCommands;
+    },
+    get "data-collection"() {
+        return require("./data-collection.js")
+            .dataCollectionCommands;
+    },
 };

package/dist/src/cli/commands/knowledge-bank.d.ts

@@ -0,0 +1,2 @@
+import type { CommandMeta } from "../types.js";
+export declare const knowledgeBankCommands: Record<string, CommandMeta>;

package/dist/src/cli/commands/knowledge-bank.js

@@ -0,0 +1,80 @@
+import { requiredJsonInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
+import { planResult, } from "../output.js";
+import { requireArgs, UsageError, } from "../usage.js";
+const KB_PLAN_EXIT_CODES = { usage: 1, error: 2, transient: 3, };
+const KB_SEARCH_USAGE = "dss knowledge-bank search <knowledgeBankId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]";
+const KB_CLEAR_USAGE = "dss knowledge-bank clear <knowledgeBankId> [--dry-run] [--project-key KEY]";
+/**
+ * Validate a search body before any execution mode: the same check runs for
+ * live, --plan, and --dry-run so planning can never succeed for a body the
+ * live call would reject.
+ */
+function requireKnowledgeBankSearchBody(flags) {
+    const body = requiredJsonInput(flags, "--data, --data-file, or --stdin is required (search body with a query string).");
+    const query = body["query"];
+    if (typeof query !== "string" || query.trim().length === 0) {
+        throw new UsageError(`query is required and must be a non-empty string.\nUsage: ${KB_SEARCH_USAGE}`, "invalid_flag_value");
+    }
+    return body;
+}
+function requireNonEmptyPositional(value, usage) {
+    if (value.trim().length === 0) {
+        throw new UsageError(`knowledgeBankId must be a non-empty string.\nUsage: ${usage}`, "invalid_flag_value");
+    }
+    return value;
+}
+export const knowledgeBankCommands = {
+    search: {
+        handler: async (c, a, f) => {
+            const knowledgeBankId = requireNonEmptyPositional(a[0], KB_SEARCH_USAGE);
+            const body = requireKnowledgeBankSearchBody(f);
+            const projectKey = f["project-key"];
+            if (executionMode(f).dryRun) {
+                return planResult("knowledge-bank", "search", {
+                    asyncKind: "none",
+                    method: "POST",
+                    endpoint: `/public/api/projects/${encodeURIComponent(projectKey ?? c.resolveProjectKey(undefined))}/knowledge-banks/${encodeURIComponent(knowledgeBankId)}/search`,
+                    identifiers: { knowledgeBankId, },
+                    payload: body,
+                    idempotency: "none",
+                    exitCodesOnFailure: KB_PLAN_EXIT_CODES,
+                    plannedAndDryRun: true,
+                });
+            }
+            return c.knowledgeBanks.search(knowledgeBankId, body, projectKey);
+        },
+        usage: KB_SEARCH_USAGE,
+        description: "Search a knowledge bank for documents matching a query. Runs retrieval against the backing vector store. Body: { query, params?: { maxDocuments, searchType, similarityThreshold, mmrK, mmrDiversity, useAdvancedReranking, rrfRankConstant, rrfRankWindowSize } }.",
+        examples: [
+            'dss knowledge-bank search my-kb --data \'{"query":"Hello, world!"}\'',
+            'dss knowledge-bank search my-kb --data \'{"query":"refund policy","params":{"maxDocuments":5,"searchType":"SIMILARITY"}}\' --dry-run',
+        ],
+    },
+    clear: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, KB_CLEAR_USAGE);
+            const knowledgeBankId = requireNonEmptyPositional(a[0], KB_CLEAR_USAGE);
+            const projectKey = f["project-key"];
+            if (executionMode(f).dryRun) {
+                return planResult("knowledge-bank", "clear", {
+                    asyncKind: "none",
+                    method: "POST",
+                    endpoint: `/public/api/projects/${encodeURIComponent(projectKey ?? c.resolveProjectKey(undefined))}/knowledge-banks/${encodeURIComponent(knowledgeBankId)}/clear`,
+                    identifiers: { knowledgeBankId, },
+                    idempotency: "convergent",
+                    exitCodesOnFailure: KB_PLAN_EXIT_CODES,
+                    plannedAndDryRun: true,
+                });
+            }
+            await c.knowledgeBanks.clear(knowledgeBankId, projectKey);
+            return { cleared: knowledgeBankId, resource: "knowledge-bank", };
+        },
+        usage: KB_CLEAR_USAGE,
+        description: "DESTRUCTIVE: clear all data from a knowledge bank. The stored content is removed and cannot be recovered from this command.",
+        examples: [
+            "dss knowledge-bank clear my-kb --dry-run",
+            "dss knowledge-bank clear my-kb",
+        ],
+    },
+};

package/dist/src/cli/commands/llm.d.ts

@@ -0,0 +1,2 @@
+import type { CommandMeta } from "../types.js";
+export declare const llmCommands: Record<string, CommandMeta>;

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

@@ -0,0 +1,93 @@
+import { requiredJsonInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
+import { planResult, } from "../output.js";
+import { UsageError, } from "../usage.js";
+const LLM_PLAN_EXIT_CODES = { usage: 1, error: 2, transient: 3, };
+const LLM_LIST_USAGE = "dss llm list [--purpose GENERIC_COMPLETION|TEXT_EMBEDDING_EXTRACTION|IMAGE_GENERATION|NAME] [--project-key KEY]";
+const LLM_COMPLETIONS_USAGE = "dss llm completions (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]";
+const LLM_EMBEDDINGS_USAGE = "dss llm embeddings (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]";
+/**
+ * Validate a completions/embeddings payload before any execution mode: the
+ * same check runs for live, --plan, and --dry-run so planning can never
+ * succeed for a body the live call would reject.
+ */
+function requireLlmInferenceBody(flags, usage) {
+    const body = requiredJsonInput(flags, "--data, --data-file, or --stdin is required (LLM request body with llmId and queries).");
+    const llmId = body["llmId"];
+    if (typeof llmId !== "string" || llmId.trim().length === 0) {
+        throw new UsageError(`llmId is required and must be a non-empty string (e.g. "openai:openai1:gpt-4").\nUsage: ${usage}`, "invalid_flag_value");
+    }
+    const queries = body["queries"];
+    if (!Array.isArray(queries) || queries.length === 0) {
+        throw new UsageError(`queries is required and must be a non-empty array of query objects.\nUsage: ${usage}`, "invalid_flag_value");
+    }
+    return body;
+}
+export const llmCommands = {
+    list: {
+        handler: (c, _a, f) => {
+            const purpose = f["purpose"];
+            return c.llms.list({
+                purpose,
+                projectKey: f["project-key"],
+            });
+        },
+        usage: LLM_LIST_USAGE,
+        description: "List LLMs available in a project (includes Retrieval-Augmented Generation ones). Does not invoke any LLM.",
+        examples: ["dss llm list", "dss llm list --purpose TEXT_EMBEDDING_EXTRACTION",],
+    },
+    completions: {
+        handler: async (c, _a, f) => {
+            const body = requireLlmInferenceBody(f, LLM_COMPLETIONS_USAGE);
+            const projectKey = f["project-key"];
+            if (executionMode(f).dryRun) {
+                return planResult("llm", "completions", {
+                    asyncKind: "none",
+                    method: "POST",
+                    endpoint: `/public/api/projects/${encodeURIComponent(projectKey ?? c.resolveProjectKey(undefined))}/llms/completions`,
+                    identifiers: {
+                        llmId: typeof body["llmId"] === "string" ? body["llmId"] : undefined,
+                    },
+                    payload: body,
+                    idempotency: "none",
+                    exitCodesOnFailure: LLM_PLAN_EXIT_CODES,
+                    plannedAndDryRun: true,
+                });
+            }
+            return c.llms.completions(body, projectKey);
+        },
+        usage: LLM_COMPLETIONS_USAGE,
+        description: "Perform completions on an LLM. COST-BEARING: invokes the LLM provider and may incur charges. Body: { llmId, queries: [{ messages: [...] }], settings?: {...} }.",
+        examples: [
+            'dss llm completions --data \'{"llmId":"openai:openai1:gpt-4","queries":[{"messages":[{"role":"user","content":"Hello"}]}]}\'',
+            'dss llm completions --data \'{"llmId":"openai:openai1:gpt-4","queries":[...],"settings":{"temperature":0.9}}\' --dry-run',
+        ],
+    },
+    embeddings: {
+        handler: async (c, _a, f) => {
+            const body = requireLlmInferenceBody(f, LLM_EMBEDDINGS_USAGE);
+            const projectKey = f["project-key"];
+            if (executionMode(f).dryRun) {
+                return planResult("llm", "embeddings", {
+                    asyncKind: "none",
+                    method: "POST",
+                    endpoint: `/public/api/projects/${encodeURIComponent(projectKey ?? c.resolveProjectKey(undefined))}/llms/embeddings`,
+                    identifiers: {
+                        llmId: typeof body["llmId"] === "string" ? body["llmId"] : undefined,
+                    },
+                    payload: body,
+                    idempotency: "none",
+                    exitCodesOnFailure: LLM_PLAN_EXIT_CODES,
+                    plannedAndDryRun: true,
+                });
+            }
+            return c.llms.embeddings(body, projectKey);
+        },
+        usage: LLM_EMBEDDINGS_USAGE,
+        description: 'Perform embeddings on an LLM. COST-BEARING: invokes the LLM provider and may incur charges. Body: { llmId, queries: [{ text: "..." }] }.',
+        examples: [
+            'dss llm embeddings --data \'{"llmId":"openai:openai1:ada002-text-embedding","queries":[{"text":"Who wrote Beethoven 9th?"}]}\'',
+            'dss llm embeddings --data \'{"llmId":"x","queries":[{"text":"y"}]}\' --dry-run',
+        ],
+    },
+};

package/dist/src/cli/commands/macro.d.ts

@@ -0,0 +1,2 @@
+import type { CommandMeta } from "../types.js";
+export declare const macroCommands: Record<string, CommandMeta>;

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

@@ -0,0 +1,221 @@
+import { macroResultMaxBytes, } from "../../resources/macros.js";
+import { jsonInput, num, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
+import { encodedProjectEndpoint, } from "../output.js";
+import { requireArgs, UsageError, } from "../usage.js";
+const MACRO_RUN_USAGE = "dss macro run <macro_id> [--wait] [--timeout MS (default 120000)] [--poll-interval MS] [--data JSON] [--dry-run] [--project-key KEY]";
+/**
+ * Flags accepted by run/run-and-wait; validated identically for live, dry-run,
+ * and --plan so a plan that would fail cannot be "fixed" by dropping flags.
+ * Returns undefined rather than a partial options object so callers can spread
+ * it only when the macro actually has parameters.
+ */
+function macroWaitOptionsFromFlags(flags) {
+    const timeoutMs = num(flags["timeout"], "--timeout");
+    const pollIntervalMs = num(flags["poll-interval"], "--poll-interval");
+    if (timeoutMs !== undefined && timeoutMs < 0) {
+        throw new UsageError("--timeout must be >= 0.", "invalid_flag_value", undefined, {
+            flag: "--timeout",
+        });
+    }
+    if (pollIntervalMs !== undefined && pollIntervalMs < 1) {
+        throw new UsageError("--poll-interval must be >= 1.", "invalid_flag_value", undefined, { flag: "--poll-interval", });
+    }
+    return { timeoutMs, pollIntervalMs, };
+}
+/**
+ * Macro parameter payload from --data/--data-file/--stdin. The JSON object is
+ * passed through as the POST body: `{ "params": {...}, "adminParams": {...} }`.
+ * Values may carry credentials; the plan redacts nothing beyond DSS's own
+ * response echo, so callers must not log payloads.
+ */
+function macroRunParamsFromFlags(flags) {
+    const input = jsonInput(flags);
+    if (input === undefined)
+        return {};
+    const body = {};
+    if (input["params"] !== undefined) {
+        if (input["params"] === null || typeof input["params"] !== "object") {
+            throw new UsageError("Macro run payload params must be an object keyed by macro parameter names.", "invalid_flag_value", undefined, { flag: "--data", });
+        }
+        body.params = input["params"];
+    }
+    if (input["adminParams"] !== undefined) {
+        if (input["adminParams"] === null || typeof input["adminParams"] !== "object") {
+            throw new UsageError("Macro run payload adminParams must be an object.", "invalid_flag_value", undefined, { flag: "--data", });
+        }
+        body.adminParams = input["adminParams"];
+    }
+    return body;
+}
+/** Exact POST body a run will send; empty object when no parameters. */
+function macroRunDryRunPayload(runParams) {
+    const payload = {};
+    if (runParams.params !== undefined)
+        payload["params"] = runParams.params;
+    if (runParams.adminParams !== undefined)
+        payload["adminParams"] = runParams.adminParams;
+    return payload;
+}
+/**
+ * Reject blank/whitespace positional ids as a usage error BEFORE any request:
+ * an empty macro/run id would hit the list route or an unresolvable path.
+ */
+function requireNotBlankId(value, usage) {
+    if (value.trim().length === 0) {
+        throw new UsageError(`Macro/run id must be non-empty. Usage: ${usage}`);
+    }
+}
+export const macroCommands = {
+    list: {
+        handler: (c, _a, f) => c.macros.list(f["project-key"]),
+        usage: "dss macro list [--project-key KEY]",
+        description: "List the macros (runnables) available in a project.",
+        examples: ["dss macro list",],
+    },
+    get: {
+        handler: (c, a, f) => {
+            requireArgs(a, 1, "dss macro get <macro_id>");
+            requireNotBlankId(a[0], "dss macro get <macro_id>");
+            return c.macros.definition(a[0], {
+                projectKey: f["project-key"],
+            });
+        },
+        usage: "dss macro get <macro_id> [--project-key KEY]",
+        description: "Get a macro's definition: parameters, result type, owning plugin, labels.",
+        examples: ["dss macro get compute_orders",],
+    },
+    run: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss macro run <macro_id>");
+            const pk = f["project-key"];
+            const waitOptions = macroWaitOptionsFromFlags(f);
+            const runParams = macroRunParamsFromFlags(f);
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "run",
+                    resource: "macro",
+                    id: a[0],
+                    ...waitOptions,
+                    ...(runParams.params !== undefined ? { params: runParams.params, } : {}),
+                    ...(runParams.adminParams !== undefined
+                        ? { adminParams: runParams.adminParams, }
+                        : {}),
+                    endpoint: encodedProjectEndpoint(c, pk, `/runnables/${encodeURIComponent(a[0])}?wait=false`),
+                    method: "POST",
+                    payload: macroRunDryRunPayload(runParams),
+                    warning: "Macro runs execute arbitrary plugin code on the DSS backend; review the macro definition before running.",
+                };
+            }
+            if (f["wait"] === true) {
+                return c.macros.runAndWait(a[0], {
+                    ...waitOptions,
+                    ...runParams,
+                    projectKey: pk,
+                });
+            }
+            return c.macros.run(a[0], { ...runParams, projectKey: pk, });
+        },
+        usage: MACRO_RUN_USAGE,
+        description: "Start a macro run. Macros execute arbitrary plugin code and are classified destructive. --wait polls to completion and exits 4 on failure; without it only the runId is returned. --data JSON may carry { params: {...}, adminParams: {...} } for parameterized macros.",
+        examples: [
+            "dss macro run compute_orders",
+            "dss macro run compute_orders --wait",
+            'dss macro run compute_orders --data \'{"params":{"region":"EU"}}\'',
+            "dss macro run compute_orders --wait --timeout 300000",
+        ],
+    },
+    "run-and-wait": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss macro run-and-wait <macro_id>");
+            const pk = f["project-key"];
+            const waitOptions = macroWaitOptionsFromFlags(f);
+            const runParams = macroRunParamsFromFlags(f);
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "run-and-wait",
+                    resource: "macro",
+                    id: a[0],
+                    ...waitOptions,
+                    ...(runParams.params !== undefined ? { params: runParams.params, } : {}),
+                    ...(runParams.adminParams !== undefined
+                        ? { adminParams: runParams.adminParams, }
+                        : {}),
+                    endpoint: encodedProjectEndpoint(c, pk, `/runnables/${encodeURIComponent(a[0])}?wait=false`),
+                    method: "POST",
+                    payload: macroRunDryRunPayload(runParams),
+                    warning: "Macro runs execute arbitrary plugin code on the DSS backend; review the macro definition before running.",
+                };
+            }
+            return c.macros.runAndWait(a[0], {
+                ...waitOptions,
+                ...runParams,
+                projectKey: pk,
+            });
+        },
+        usage: "dss macro run-and-wait <macro_id> [--timeout MS (default 120000)] [--poll-interval MS] [--data JSON] [--dry-run] [--project-key KEY]",
+        description: "Run a macro and poll its state until it finishes. Exits 4 on failure; returns { success: false, timedOut: true } on timeout.",
+        examples: [
+            "dss macro run-and-wait compute_orders",
+            "dss macro run-and-wait compute_orders --timeout 60000 --poll-interval 500",
+        ],
+    },
+    abort: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 2, "dss macro abort <macro_id> <run_id>");
+            requireNotBlankId(a[0], "dss macro abort <macro_id> <run_id>");
+            requireNotBlankId(a[1], "dss macro abort <macro_id> <run_id>");
+            const pk = f["project-key"];
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "abort",
+                    resource: "macro",
+                    id: a[0],
+                    runId: a[1],
+                    endpoint: encodedProjectEndpoint(c, pk, `/runnables/${encodeURIComponent(a[0])}/abort/${encodeURIComponent(a[1])}`),
+                    method: "POST",
+                };
+            }
+            await c.macros.abort(a[0], a[1], pk);
+            return { aborted: a[1], runId: a[1], resource: "macro", };
+        },
+        usage: "dss macro abort <macro_id> <run_id> [--dry-run] [--project-key KEY]",
+        description: "Request abort of a running macro run.",
+        examples: ["dss macro abort compute_orders run_42",],
+    },
+    state: {
+        handler: (c, a, f) => {
+            requireArgs(a, 2, "dss macro state <macro_id> <run_id>");
+            requireNotBlankId(a[0], "dss macro state <macro_id> <run_id>");
+            requireNotBlankId(a[1], "dss macro state <macro_id> <run_id>");
+            return c.macros.state(a[0], a[1], {
+                projectKey: f["project-key"],
+            });
+        },
+        usage: "dss macro state <macro_id> <run_id> [--project-key KEY]",
+        description: "Get the poll state of a macro run: running flag, progress stack, failure details.",
+        examples: ["dss macro state compute_orders run_42",],
+    },
+    result: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 2, "dss macro result <macro_id> <run_id>");
+            requireNotBlankId(a[0], "dss macro result <macro_id> <run_id>");
+            requireNotBlankId(a[1], "dss macro result <macro_id> <run_id>");
+            const pk = f["project-key"];
+            const maxBytes = num(f["max-bytes"], "--max-bytes");
+            if (maxBytes !== undefined && (maxBytes < 1 || !Number.isInteger(maxBytes))) {
+                throw new UsageError("--max-bytes must be a positive integer.", "invalid_flag_value", undefined, { flag: "--max-bytes", });
+            }
+            return c.macros.result(a[0], a[1], {
+                projectKey: pk,
+                maxBytes: macroResultMaxBytes(maxBytes),
+            });
+        },
+        usage: "dss macro result <macro_id> <run_id> [--max-bytes N (default 8388608)] [--project-key KEY]",
+        description: "Download a macro run's result. Text/HTML bodies print as a JSON string (stdout stays one JSON document, embedded newlines escaped); JSON bodies print as the parsed object.",
+        examples: ["dss macro result compute_orders run_42", "dss macro result m r --max-bytes 1024",],
+    },
+};