dataiku-sdk 4.0.0 → 4.2.0

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

@@ -1,8 +1,287 @@
-import { jsonInput, num, parseBooleanOption, } from "../coerce.js";
+import { resolve, } from "node:path";
+import { mailReporter, SCENARIO_TRIGGER_FREQUENCIES, selectScenarioListIndex, temporalTrigger, } from "../../resources/scenario-authoring.js";
+import { messagingChannelSecretsFromBody, sanitizeMessagingChannelError, sanitizeMessagingChannelSecrets, } from "../../utils/messaging-channel-secrets.js";
+import { asRecord, } from "../../utils/records.js";
+import { json, jsonInput, num, parseBooleanOption, parseJsonObject, readInputText, splitCsvFlag, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
-import { encodedProjectEndpoint, readIfExists, skipResult, } from "../output.js";
+import { encodedProjectEndpoint, enqueueCliWarning, readIfExists, skipResult, } from "../output.js";
+import { scenarioRunDiagnosis, shapeCommandResult, } from "../result-shapes.js";
 import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
+/**
+ * The recipe a failed job was running and the datasets it read, from one
+ * `job get` (its FAILED activity). Undefined when the job cannot be read or
+ * names no failed recipe: the diagnosis then stays job-level.
+ */
+async function failedActivity(c, jobId, projectKey) {
+    if (typeof jobId !== "string")
+        return undefined;
+    try {
+        const job = asRecord(await c.jobs.get(jobId, projectKey));
+        const activities = asRecord(asRecord(job?.["baseStatus"])?.["activities"]) ?? {};
+        for (const value of Object.values(activities)) {
+            const activity = asRecord(value);
+            if (activity?.["state"] !== "FAILED" || typeof activity["recipeName"] !== "string")
+                continue;
+            const sources = Array.isArray(activity["sources"]) ? activity["sources"] : [];
+            const inputs = sources.flatMap((source) => {
+                const id = asRecord(source)?.["id"];
+                if (typeof id !== "string")
+                    return [];
+                // Same-project inputs are named bare; foreign ones keep PROJECT.name.
+                const dot = id.indexOf(".");
+                return [dot > 0 && id.slice(0, dot) === projectKey ? id.slice(dot + 1) : id,];
+            });
+            return { recipe: activity["recipeName"], inputs, };
+        }
+    }
+    catch {
+        // A diagnosis aid only: the run report itself is already in hand.
+    }
+    return undefined;
+}
+/** Diagnosis of a raw run report, located at the failed recipe when its job names one. */
+async function locatedDiagnosis(c, details, projectKey) {
+    const plain = scenarioRunDiagnosis(details);
+    const runProject = asRecord(asRecord(asRecord(details)?.["scenarioRun"])?.["trigger"])?.["projectKey"];
+    const pk = projectKey ?? (typeof runProject === "string" ? runProject : undefined);
+    const activity = await failedActivity(c, plain.failure?.["jobId"], pk);
+    return activity ? scenarioRunDiagnosis(details, activity) : plain;
+}
+/**
+ * Run a scenario and wait; a failed (not timed-out) run gains the first
+ * failure, the recipe that failed, and the next commands. Extra reads happen
+ * only on failure; a read error leaves the wait result untouched. A cancelled
+ * trigger fire has no run to diagnose: it says why instead.
+ */
+async function runAndWaitWithFailure(c, scenarioId, options) {
+    const result = await c.scenarios.runAndWait(scenarioId, options);
+    if (result.cancelled === true) {
+        return {
+            ...result,
+            failure: {
+                message: `DSS cancelled this run before it started (trigger run ${result.triggerRunId}): the scenario was already running, or another trigger fire replaced this one. No scenario run exists; wait for or abort the current run (scenario status, scenario abort), then run again.`,
+            },
+            next: [["dss", "scenario", "status", scenarioId, ...projectKeyArgs(options.projectKey),],],
+        };
+    }
+    if (result.success || result.timedOut === true || !result.runId)
+        return result;
+    try {
+        const details = await c.scenarios.getRunDetails(scenarioId, result.runId, {
+            projectKey: options.projectKey,
+        });
+        return { ...result, ...await locatedDiagnosis(c, details, options.projectKey), };
+    }
+    catch {
+        return result;
+    }
+}
+function projectKeyArgs(projectKey) {
+    return projectKey === undefined ? [] : ["--project-key", projectKey,];
+}
+/** `scenario run` result: the trigger fire, with the explicit pointer to the scenario run it will start. */
+function triggerRunResult(fire, scenarioId, projectKey) {
+    if (fire.cancelled) {
+        return {
+            ...fire,
+            hint: "DSS cancelled this trigger fire: the scenario was already running (or another fire replaced it), so no scenario run exists for this triggerRunId.",
+            next: [["dss", "scenario", "status", scenarioId, ...projectKeyArgs(projectKey),],],
+        };
+    }
+    return {
+        ...fire,
+        hint: "triggerRunId identifies this trigger firing, not a scenario run: get-run and log need the scenario run id that get-run-for-trigger returns (or use --wait).",
+        next: [[
+                "dss",
+                "scenario",
+                "get-run-for-trigger",
+                scenarioId,
+                fire.triggerRunId,
+                ...(fire.triggerId === "manual" ? [] : ["--trigger-id", fire.triggerId,]),
+                ...projectKeyArgs(projectKey),
+            ],],
+    };
+}
+/** `scenario get-run-for-trigger` result: the fire's state and the commands that follow from it. */
+function triggerRunStateResult(state, scenarioId, projectKey) {
+    const pk = projectKeyArgs(projectKey);
+    const next = state.runId !== undefined
+        ? [
+            ["dss", "scenario", "get-run", scenarioId, state.runId, ...pk,],
+            ["dss", "scenario", "log", scenarioId, state.runId, ...pk,],
+        ]
+        : state.state === "PENDING"
+            ? [[
+                    "dss",
+                    "scenario",
+                    "get-run-for-trigger",
+                    scenarioId,
+                    state.triggerRunId,
+                    ...(state.triggerId === "manual" ? [] : ["--trigger-id", state.triggerId,]),
+                    ...pk,
+                ],]
+            : [["dss", "scenario", "status", scenarioId, ...pk,],];
+    return {
+        ...state,
+        ...(state.cancelled
+            ? {
+                hint: "DSS cancelled this trigger fire (the scenario was already running, or another fire replaced it); no scenario run will exist.",
+            }
+            : {}),
+        next,
+    };
+}
+/** Run parameters from `--params JSON` or `--params-file PATH` (the POST /run body). */
+export function scenarioRunParams(flags) {
+    const file = flags["params-file"];
+    if (flags["params"] !== undefined && file !== undefined) {
+        throw new UsageError("Pass --params or --params-file, not both.");
+    }
+    return typeof file === "string"
+        ? parseJsonObject(readInputText(file, "--params-file"), "--params-file")
+        : json(flags["params"], "--params");
+}
+/** The trigger `trigger-add` appends: a raw `--data` object, or a schedule built from the --frequency flags. */
+export function scenarioTriggerFromFlags(flags) {
+    const usage = commandUsage("scenario", "trigger-add");
+    const raw = jsonInput(flags);
+    if (raw !== undefined) {
+        if (flags["frequency"] !== undefined) {
+            throw new UsageError(`--frequency builds a schedule; pass it or --data/--data-file/--stdin, not both. Usage: ${usage}`);
+        }
+        return raw;
+    }
+    const frequency = SCENARIO_TRIGGER_FREQUENCIES.find((candidate) => candidate === flags["frequency"]);
+    if (frequency === undefined) {
+        throw new UsageError(`--frequency ${SCENARIO_TRIGGER_FREQUENCIES.join("|")} (or a raw trigger via --data) is required. Usage: ${usage}`);
+    }
+    const text = (name) => typeof flags[name] === "string" ? flags[name] : undefined;
+    return temporalTrigger({
+        frequency,
+        every: num(flags["every"], "--every"),
+        hour: num(flags["hour"], "--hour"),
+        minute: num(flags["minute"], "--minute"),
+        days: flags["days"] === undefined ? undefined : splitCsvFlag(flags["days"]),
+        dayOfMonth: num(flags["day-of-month"], "--day-of-month"),
+        runOn: text("run-on"),
+        startDate: text("start-date"),
+        timezone: text("timezone"),
+        name: text("name"),
+        active: parseBooleanOption(flags["active"], "--active"),
+    });
+}
+/** The reporter `reporter-add` appends: a raw `--data` object, or a mail reporter built from the --channel flags. */
+export function scenarioReporterFromFlags(flags) {
+    const usage = commandUsage("scenario", "reporter-add");
+    const raw = jsonInput(flags);
+    const mailFlags = ["channel", "recipient", "subject", "message", "condition", "phase",];
+    if (raw !== undefined) {
+        const clash = mailFlags.find((name) => flags[name] !== undefined);
+        if (clash !== undefined) {
+            throw new UsageError(`--${clash} builds a mail reporter; pass it or --data/--data-file/--stdin, not both. Usage: ${usage}`);
+        }
+        return raw;
+    }
+    const text = (name) => typeof flags[name] === "string" ? flags[name] : undefined;
+    const [channel, recipient, subject, message,] = ["channel", "recipient", "subject", "message",]
+        .map((name) => {
+        const value = text(name);
+        if (value === undefined) {
+            throw new UsageError(`--${name} is required (or pass a raw reporter via --data). Usage: ${usage}`);
+        }
+        return value;
+    });
+    return mailReporter({
+        channel,
+        recipient,
+        subject,
+        message,
+        condition: text("condition"),
+        phase: text("phase"),
+        name: text("name"),
+        active: parseBooleanOption(flags["active"], "--active"),
+    });
+}
+/** Reporter reduced to what a list needs: identity, phase, condition, channel, recipient, subject. */
+function compactReporter(reporter, index) {
+    const fields = asRecord(reporter);
+    const messaging = asRecord(fields?.["messaging"]);
+    const configuration = asRecord(messaging?.["configuration"]);
+    return {
+        index,
+        id: fields?.["id"],
+        name: fields?.["name"],
+        active: fields?.["active"],
+        phase: fields?.["phase"],
+        runCondition: fields?.["runConditionEnabled"] === true ? fields["runCondition"] : undefined,
+        type: messaging?.["type"],
+        channel: configuration?.["channelId"],
+        recipient: configuration?.["recipient"],
+        subject: configuration?.["subject"],
+    };
+}
+/** Shared `trigger-add`/`reporter-add`: dry-run previews the appended element, otherwise it is written and verified. */
+async function addScenarioItem(c, kind, scenarioId, item, flags) {
+    const projectKey = flags["project-key"];
+    const listAction = `${kind}-list`;
+    if (executionMode(flags).dryRun) {
+        const items = await c.scenarios.listItems(kind, scenarioId, { projectKey, });
+        return {
+            dryRun: true,
+            action: `${kind}-add`,
+            resource: "scenario",
+            id: scenarioId,
+            [kind]: sanitizeMessagingChannelSecrets(item),
+            index: items.length,
+            count: items.length + 1,
+        };
+    }
+    // A raw reporter can carry a webhook URL or token that DSS may echo back in an error.
+    const secrets = messagingChannelSecretsFromBody(item);
+    const result = await c.scenarios.addItem(kind, scenarioId, item, { projectKey, }).catch((error) => {
+        throw sanitizeMessagingChannelError(error, secrets);
+    });
+    return {
+        added: kind,
+        resource: "scenario",
+        id: scenarioId,
+        index: result.index,
+        [kind]: sanitizeMessagingChannelSecrets(result.item),
+        count: result.count,
+        next: [["dss", "scenario", listAction, scenarioId, ...projectKeyArgs(projectKey),],],
+    };
+}
+/** Shared `trigger-remove`/`reporter-remove`: the element is chosen by --index or --name; the others stay. */
+async function removeScenarioItem(c, kind, scenarioId, flags) {
+    const projectKey = flags["project-key"];
+    const selector = {
+        index: num(flags["index"], "--index"),
+        name: flags["name"],
+    };
+    if (executionMode(flags).dryRun) {
+        const items = await c.scenarios.listItems(kind, scenarioId, { projectKey, });
+        const index = selectScenarioListIndex(items, selector, kind);
+        return {
+            dryRun: true,
+            action: `${kind}-remove`,
+            resource: "scenario",
+            id: scenarioId,
+            index,
+            [kind]: sanitizeMessagingChannelSecrets(items[index]),
+            count: items.length - 1,
+        };
+    }
+    const result = await c.scenarios.removeItem(kind, scenarioId, selector, { projectKey, });
+    return {
+        removed: kind,
+        resource: "scenario",
+        id: scenarioId,
+        index: result.index,
+        [kind]: sanitizeMessagingChannelSecrets(result.item),
+        count: result.count,
+    };
+}
 export const scenarioCommands = withUsage("scenario", {
     list: {
         handler: (c, _a, f) => c.scenarios.list(f["project-key"]),
@@ -21,6 +300,7 @@ export const scenarioCommands = withUsage("scenario", {
         handler: async (c, a, f) => {
             requireArgs(a, 1, commandUsage("scenario", "run"));
             const pk = f["project-key"];
+            const params = scenarioRunParams(f);
             const options = {
                 pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
                 timeoutMs: num(f["timeout"], "--timeout"),
@@ -32,22 +312,28 @@ export const scenarioCommands = withUsage("scenario", {
                     resource: "scenario",
                     id: a[0],
                     ...options,
+                    ...(params === undefined ? {} : { params, }),
                     endpoint: encodedProjectEndpoint(c, pk, `/scenarios/${encodeURIComponent(a[0])}/run/`),
                     method: "POST",
                 };
             }
             if (f["wait"] === true) {
-                return c.scenarios.runAndWait(a[0], { ...options, projectKey: pk, });
+                return runAndWaitWithFailure(c, a[0], { ...options, params, projectKey: pk, });
             }
-            return c.scenarios.run(a[0], pk);
+            return triggerRunResult(await c.scenarios.run(a[0], { params, projectKey: pk, }), a[0], pk);
         },
-        description: "Trigger a scenario run, optionally waiting for completion.",
-        examples: ["dss scenario run my_scenario", "dss scenario run my_scenario --wait",],
+        description: "Trigger a scenario run; --wait waits for it. --params JSON/--params-file PATH are the run parameters. Without --wait the result is the trigger fire: triggerRunId is NOT a scenario run id, resolve it with get-run-for-trigger (see `next`). cancelled: true means the scenario was already running; no run starts.",
+        examples: [
+            "dss scenario run my_scenario",
+            "dss scenario run my_scenario --wait",
+            'dss scenario run my_scenario --params \'{"region":"EU"}\' --wait',
+        ],
     },
     "run-and-wait": {
         handler: async (c, a, f) => {
             requireArgs(a, 1, commandUsage("scenario", "run-and-wait"));
             const pk = f["project-key"];
+            const params = scenarioRunParams(f);
             const options = {
                 pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
                 timeoutMs: num(f["timeout"], "--timeout"),
@@ -59,16 +345,18 @@ export const scenarioCommands = withUsage("scenario", {
                     resource: "scenario",
                     id: a[0],
                     ...options,
+                    ...(params === undefined ? {} : { params, }),
                     endpoint: encodedProjectEndpoint(c, pk, `/scenarios/${encodeURIComponent(a[0])}/run/`),
                     method: "POST",
                 };
             }
-            return c.scenarios.runAndWait(a[0], { ...options, projectKey: pk, });
+            return runAndWaitWithFailure(c, a[0], { ...options, params, projectKey: pk, });
         },
-        description: "Run a scenario and wait for completion.",
+        description: "Run a scenario and wait for completion (--params JSON / --params-file PATH as run parameters). Outcome CANCELLED (exit 4) means DSS cancelled the trigger fire because the scenario was already running; TIMEOUT means the wait ran out while the run continues.",
         examples: [
             "dss scenario run-and-wait my_scenario",
             "dss scenario run-and-wait my_scenario --timeout 300000",
+            "dss scenario run-and-wait my_scenario --params-file params.json",
         ],
     },
     status: {
@@ -101,11 +389,13 @@ export const scenarioCommands = withUsage("scenario", {
         handler: async (c, a, f) => {
             requireArgs(a, 2, commandUsage("scenario", "create"));
             const pk = f["project-key"];
+            const data = jsonInput(f);
             const payload = {
                 scenarioId: a[0],
                 name: a[1],
                 scenarioType: f["type"],
                 projectKey: pk,
+                ...(data === undefined ? {} : { data, }),
             };
             if (f["if-not-exists"] === true || executionMode(f).dryRun) {
                 const list = await c.scenarios.list(pk);
@@ -126,14 +416,16 @@ export const scenarioCommands = withUsage("scenario", {
             }
             await c.scenarios.create(a[0], a[1], {
                 scenarioType: payload.scenarioType,
+                data,
                 projectKey: pk,
             });
             return { created: a[0], name: a[1], resource: "scenario", };
         },
-        description: "Create a new scenario.",
+        description: "Create a new scenario. --data/--data-file/--stdin merge extra top-level fields into the create body (e.g. triggers, reporters, params.steps, runAsUser).",
         examples: [
             'dss scenario create my_scenario "My Scenario"',
             'dss scenario create my_scenario "My Scenario" --type custom_python --dry-run',
+            'dss scenario create nightly "Nightly" --data \'{"triggers":[{"active":true,"type":"temporal","params":{"frequency":"Daily","hour":2,"minute":0,"startingFrom":"2026-01-01T00:00:00.000+0000","repeatFrequency":1,"timezone":"SERVER"}}]}\' --dry-run',
         ],
     },
     update: {
@@ -206,20 +498,31 @@ export const scenarioCommands = withUsage("scenario", {
             requireArgs(a, 1, commandUsage("scenario", "last-runs"));
             return c.scenarios.getLastRuns(a[0], {
                 limit: num(f["limit"], "--limit"),
+                onlyFinished: f["only-finished"] === true,
                 projectKey: f["project-key"],
             });
         },
-        description: "List the most recent runs of a scenario (run id, start/end, outcome).",
-        examples: ["dss scenario last-runs my_scenario --limit 10",],
+        description: "List a scenario's most recent runs, newest first (compact: run id, outcome, timing, trigger, failure; --full for DSS objects). --only-finished skips in-progress (and, observed live, aborted) runs: `--only-finished --limit 1` is the last finished run; read its outcome.",
+        examples: [
+            "dss scenario last-runs my_scenario --limit 10",
+            "dss scenario last-runs my_scenario --only-finished --limit 1",
+        ],
     },
     "get-run": {
-        handler: (c, a, f) => {
+        handler: async (c, a, f) => {
             requireArgs(a, 2, commandUsage("scenario", "get-run"));
-            return c.scenarios.getRunDetails(a[0], a[1], {
-                projectKey: f["project-key"],
-            });
+            const projectKey = f["project-key"];
+            const details = await c.scenarios.getRunDetails(a[0], a[1], { projectKey, });
+            if (f["full"] === true || typeof f["fields"] === "string")
+                return details;
+            // Compact view, located at the failed recipe (one extra job read, only on failure).
+            // The shaped object has no `scenarioRun`, so the dispatcher's shaping passes it through.
+            const shaped = asRecord(shapeCommandResult("scenario", "get-run", details, f));
+            if (!shaped?.["failure"])
+                return shaped ?? details;
+            return { ...shaped, ...await locatedDiagnosis(c, details, projectKey), };
         },
-        description: "Get the details of a specific scenario run, including per-step outcomes.",
+        description: "Get a scenario run: outcome, timing, trigger, per-step datasets and jobs, plus `failure` {stepId, jobId, dataset, recipe, inputs, message} and `next` argv (recipe code, input schemas, job errors) for the first failure (compact by default; --full returns the raw DSS run report).",
         examples: ["dss scenario get-run my_scenario 2024-09-01-01-02-03-123",],
     },
     log: {
@@ -233,7 +536,6 @@ export const scenarioCommands = withUsage("scenario", {
             const outputFile = f["output"]
                 ?? f["output-file"];
             if (outputFile) {
-                const { resolve, } = await import("node:path");
                 const outputPath = resolve(outputFile);
                 await Bun.write(outputPath, result.text);
                 return { path: outputPath, truncated: result.truncated, };
@@ -309,4 +611,180 @@ export const scenarioCommands = withUsage("scenario", {
             "dss scenario active-set my_scenario true --dry-run",
         ],
     },
+    "get-run-for-trigger": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 2, commandUsage("scenario", "get-run-for-trigger"));
+            const pk = f["project-key"];
+            const state = await c.scenarios.getRunForTrigger(a[0], a[1], {
+                triggerId: f["trigger-id"],
+                projectKey: pk,
+            });
+            return triggerRunStateResult(state, a[0], pk);
+        },
+        description: "Resolve a trigger run (the triggerRunId `scenario run` returns) to its scenario run: state PENDING (no run yet; repeat), RUNNING, FINISHED (outcome), or CANCELLED (DSS cancelled the fire because the scenario was already running; no run will exist). `runId` is what get-run and log take.",
+        examples: ["dss scenario get-run-for-trigger my_scenario 2024-09-01-01-02-03-123",],
+    },
+    "runs-by-date": {
+        handler: (c, a, f) => {
+            requireArgs(a, 1, commandUsage("scenario", "runs-by-date"));
+            const from = f["from"];
+            if (typeof from !== "string") {
+                throw new UsageError(`--from is required. Usage: ${commandUsage("scenario", "runs-by-date")}`);
+            }
+            return c.scenarios.getRunsByDate(a[0], {
+                from,
+                to: f["to"],
+                projectKey: f["project-key"],
+            });
+        },
+        description: "List the runs of a scenario that started from --from (inclusive) to --to (exclusive: DSS compares the start of that day, so --from D --to D is empty), each YYYY-MM-DD or an ISO date-time (time dropped). --to defaults to tomorrow, i.e. up to now. Compact like last-runs; --full returns the DSS run objects.",
+        examples: ["dss scenario runs-by-date my_scenario --from 2026-10-01 --to 2026-10-31",],
+    },
+    "run-report": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 2, commandUsage("scenario", "run-report"));
+            const result = await c.scenarios.getRunReport(a[0], a[1], {
+                stepId: f["step-id"],
+                maxBytes: num(f["max-bytes"], "--max-bytes"),
+                projectKey: f["project-key"],
+            });
+            const outputFile = f["output"]
+                ?? f["output-file"];
+            if (outputFile) {
+                const outputPath = resolve(outputFile);
+                await Bun.write(outputPath, result.text);
+                return { path: outputPath, truncated: result.truncated, };
+            }
+            return result.text;
+        },
+        description: "Get the JUnit XML report of a test scenario run (or of one step via --step-id). Only scenarios marked as test (markedAsTest) have reports. Byte-bounded at --max-bytes (default 1 MiB); --output PATH writes it to a file (stdout returns the path).",
+        examples: [
+            "dss scenario run-report my_test_scenario RUN_ID --output report.xml",
+            "dss scenario run-report my_test_scenario RUN_ID --step-id run_tests",
+        ],
+    },
+    "trigger-list": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, commandUsage("scenario", "trigger-list"));
+            const triggers = await c.scenarios.listItems("trigger", a[0], {
+                projectKey: f["project-key"],
+            });
+            return triggers.map((trigger, index) => ({ index, ...asRecord(trigger), }));
+        },
+        description: "List the automatic triggers of a scenario with their 0-based index (the --index of trigger-remove). Triggers only fire while the scenario is active (scenario active-set).",
+        examples: ["dss scenario trigger-list my_scenario",],
+    },
+    "trigger-add": {
+        handler: (c, a, f) => {
+            requireArgs(a, 1, commandUsage("scenario", "trigger-add"));
+            return addScenarioItem(c, "trigger", a[0], scenarioTriggerFromFlags(f), f);
+        },
+        description: "Append a trigger, keeping the others. Schedule: --frequency (dataikuapi builders) with --every, --hour, --minute, --days (weekly), --day-of-month/--run-on (monthly), --start-date, --timezone (default SERVER), --name, --active. Other trigger types: JSON via --data.",
+        examples: [
+            "dss scenario trigger-add my_scenario --frequency daily --hour 6 --minute 30",
+            "dss scenario trigger-add my_scenario --frequency weekly --days Monday,Friday --hour 8",
+            "dss scenario trigger-add my_scenario --frequency monthly --day-of-month 5 --run-on ON_THE_DAY --dry-run",
+            'dss scenario trigger-add my_scenario --data \'{"type":"temporal","active":true,"params":{"frequency":"Minutely","repeatFrequency":15}}\'',
+        ],
+    },
+    "trigger-remove": {
+        handler: (c, a, f) => {
+            requireArgs(a, 1, commandUsage("scenario", "trigger-remove"));
+            return removeScenarioItem(c, "trigger", a[0], f);
+        },
+        description: "Remove one trigger, selected by --index (from trigger-list) or --name, keeping the others.",
+        examples: [
+            "dss scenario trigger-remove my_scenario --index 0",
+            "dss scenario trigger-remove my_scenario --name nightly --dry-run",
+        ],
+    },
+    "reporter-list": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, commandUsage("scenario", "reporter-list"));
+            const reporters = await c.scenarios.listItems("reporter", a[0], {
+                projectKey: f["project-key"],
+            });
+            // Channel credentials live on the channel, but reporters of other types may carry their own.
+            return reporters.map((reporter, index) => f["full"] === true
+                ? { index, ...asRecord(sanitizeMessagingChannelSecrets(reporter)), }
+                : compactReporter(reporter, index));
+        },
+        description: "List the reporters (notifications) of a scenario with their 0-based index: id, phase, active, channel, recipient, subject (compact by default; --full returns the DSS objects with credential-looking values redacted).",
+        examples: ["dss scenario reporter-list my_scenario",],
+    },
+    "reporter-add": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, commandUsage("scenario", "reporter-add"));
+            const reporter = scenarioReporterFromFlags(f);
+            // DSS saves a reporter with any channel id; an unknown one never sends. Warn, don't fail:
+            // a channel may be hidden from this key yet usable by the scenario's run-as user.
+            const channel = f["channel"];
+            if (typeof channel === "string") {
+                const known = (await c.messagingChannels.list()).map((entry) => entry.id);
+                if (!known.includes(channel)) {
+                    enqueueCliWarning({
+                        code: "reporter_channel_unknown",
+                        channel,
+                        knownChannels: known,
+                        hint: "No messaging channel with this id is visible: the reporter will not send. Check `dss messaging-channel list`.",
+                    });
+                }
+            }
+            return addScenarioItem(c, "reporter", a[0], reporter, f);
+        },
+        description: "Append a reporter, keeping the others. Mail: --channel ID (messaging-channel list), --recipient, --subject, --message (required), --condition EXPR, --phase START|END (default END). Slack, Teams and other channel types: pass the reporter JSON with --data.",
+        examples: [
+            'dss scenario reporter-add my_scenario --channel smtp --recipient ops@example.com --subject "Scenario done" --message "See DSS"',
+            "dss scenario reporter-add my_scenario --channel smtp --recipient ops@example.com --subject Failed --message Failed --condition \"outcome == 'FAILED'\" --dry-run",
+        ],
+    },
+    "reporter-remove": {
+        handler: (c, a, f) => {
+            requireArgs(a, 1, commandUsage("scenario", "reporter-remove"));
+            return removeScenarioItem(c, "reporter", a[0], f);
+        },
+        description: "Remove one reporter, selected by --index (from reporter-list) or --name, keeping the others.",
+        examples: ["dss scenario reporter-remove my_scenario --index 0",],
+    },
+    "run-as-set": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, commandUsage("scenario", "run-as-set"));
+            const user = f["user"];
+            const clear = f["clear"] === true;
+            if ((typeof user === "string") === clear) {
+                throw new UsageError(`Pass exactly one of --user LOGIN or --clear. Usage: ${commandUsage("scenario", "run-as-set")}`);
+            }
+            const runAsUser = typeof user === "string" ? user : null;
+            const pk = f["project-key"];
+            if (executionMode(f).dryRun) {
+                const current = asRecord(await c.scenarios.get(a[0], { projectKey: pk, }));
+                return {
+                    dryRun: true,
+                    action: "run-as-set",
+                    resource: "scenario",
+                    id: a[0],
+                    runAsUser,
+                    currentRunAsUser: current?.["runAsUser"] ?? null,
+                    endpoint: encodedProjectEndpoint(c, pk, `/scenarios/${encodeURIComponent(a[0])}/`),
+                    method: "PUT",
+                };
+            }
+            const result = await c.scenarios.setRunAs(a[0], runAsUser, { projectKey: pk, });
+            return {
+                updated: a[0],
+                resource: "scenario",
+                part: "runAsUser",
+                runAsUser: result.runAsUser,
+                effectiveRunAs: result.effectiveRunAs,
+                ...(result.previousRunAsUser === undefined
+                    ? {}
+                    : { previousRunAsUser: result.previousRunAsUser, }),
+            };
+        },
+        description: "Set the user a scenario runs as (--user LOGIN, administrators only) or clear it (--clear: it then runs as its last editor). The result reports the effective run-as; scenario status shows runAsUser.",
+        examples: [
+            "dss scenario run-as-set my_scenario --user service_account",
+            "dss scenario run-as-set my_scenario --clear --dry-run",
+        ],
+    },
 });