dataiku-sdk 3.6.0 → 3.7.0

package/dist/src/cli/doctor.d.ts

@@ -68,11 +68,24 @@ export interface DoctorResult {
         tlsVerify: "strict" | "disabled";
         caCert: "default" | "custom";
     };
+    identity?: DoctorIdentity;
     permissions?: DoctorPermissions;
     permissionDetails?: Partial<Record<DoctorPermissionKey, Record<string, unknown>>>;
     fixtures?: DoctorFixtures;
     environment?: DoctorEnvironment;
 }
+/**
+ * The identity a DSS API key acts as, from `GET /public/api/auth/info`
+ * (no admin privilege required). Explains unexplained 403s: a personal key
+ * acts as its owner, a global key shows up as an `api:<id>` identity.
+ * Carries no secret material.
+ */
+export interface DoctorIdentity {
+    authSource?: string;
+    authIdentifier?: string;
+    groups?: string[];
+    userProfile?: string;
+}
 export declare function errorDetails(error: unknown): Record<string, unknown>;
 export declare function firstStringField(items: unknown[] | undefined, fields: string[]): string | null;
 export declare function integrationFlag(name: string): boolean;

package/dist/src/cli/doctor.js

@@ -49,6 +49,34 @@ export function doctorEnvironment(projectKey, versionInfo) {
         },
     };
 }
+/**
+ * Identity fields this doctor version reports, read from the documented
+ * `GET /public/api/auth/info` payload. Everything is optional: the field set
+ * varies across DSS versions and absent fields stay absent.
+ */
+function doctorIdentityFromAuthInfo(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const record = raw;
+    const groups = Array.isArray(record["groups"])
+        ? record["groups"].filter((g) => typeof g === "string")
+        : undefined;
+    const authSource = typeof record["authSource"] === "string" ? record["authSource"] : undefined;
+    const authIdentifier = typeof record["authIdentifier"] === "string"
+        ? record["authIdentifier"]
+        : undefined;
+    const userProfile = typeof record["userProfile"] === "string" ? record["userProfile"] : undefined;
+    if (authSource === undefined && authIdentifier === undefined && userProfile === undefined
+        && (groups === undefined || groups.length === 0)) {
+        return undefined;
+    }
+    return {
+        ...(authSource !== undefined ? { authSource, } : {}),
+        ...(authIdentifier !== undefined ? { authIdentifier, } : {}),
+        ...(groups !== undefined && groups.length > 0 ? { groups, } : {}),
+        ...(userProfile !== undefined ? { userProfile, } : {}),
+    };
+}
 export function permissionStatusForError(error) {
     if (error instanceof DataikuError) {
         if (error.status === 401 || error.status === 403 || error.status === 404)
@@ -261,6 +289,7 @@ export async function runDoctor(flags) {
     });
     let accessibleProjects;
     let environmentVersion;
+    let identity;
     if (credentialsOk) {
         const requestTimeoutMs = num(flags["request-timeout"], "--request-timeout");
         const retryMaxAttempts = num(flags["retries"], "--retries");
@@ -318,6 +347,12 @@ export async function runDoctor(flags) {
                 details: errorDetails(error),
             });
         }
+        // Which principal the key acts as (personal vs global key, groups) explains
+        // 403s on objects the user's UI profile can use. Diagnostic only: an
+        // unanswered /auth/info (older DSS) never fails doctor.
+        if (accessibleProjects) {
+            identity = await client.get("/public/api/auth/info").then(doctorIdentityFromAuthInfo, () => undefined);
+        }
         if (projectKey) {
             try {
                 const project = await client.projects.get(projectKey);
@@ -341,7 +376,12 @@ export async function runDoctor(flags) {
             }
         }
     }
-    const result = { ok: checks.every((check) => check.ok), checks, context, };
+    const result = {
+        ok: checks.every((check) => check.ok),
+        checks,
+        context,
+        ...(identity ? { identity, } : {}),
+    };
     if (flags["capabilities"] === true && credentialsOk) {
         const requestTimeoutMs = num(flags["request-timeout"], "--request-timeout");
         const retryMaxAttempts = num(flags["retries"], "--retries") ?? 1;

package/dist/src/cli/flags.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Positional arguments scanned with the same flag grammar as `parseArgs`, so
+ * error reporting can recover the invoked resource/action without depending
+ * on the command registry being loaded.
+ */
+export declare function rawPositionals(argv: string[]): string[];
 /** Planning wins dispatch; dryRun remains set for combined plan metadata. */
 export declare function executionMode(flags: Record<string, string | boolean>): {
     readonly plan: boolean;
@@ -10,7 +16,7 @@ export declare const FLAG_ALIASES: Record<string, string>;
 export declare const VALUE_FLAGS: Set<string>;
 export declare const REPEATABLE_VALUE_FLAGS: Set<string>;
 export declare const KNOWN_LONG_FLAGS: Set<string>;
-export declare function normalizeLongFlag(rawFlagName: string): string;
+export declare function normalizeLongFlag(rawFlagName: string, argv: string[]): string;
 export declare function isNegativeNumberToken(value: string): boolean;
 export declare function requireFlagValue(flagLabel: string, next: string | undefined): string;
 export declare function setParsedFlagValue(flags: Record<string, string | boolean>, flagName: string, value: string): void;

package/dist/src/cli/flags.js

@@ -1,5 +1,40 @@
 import { parseBooleanOption, } from "./coerce.js";
-import { unsupportedHelpFlag, UsageError, } from "./usage.js";
+import { unknownFlagError, unsupportedHelpFlag, UsageError, } from "./usage.js";
+/**
+ * Positional arguments scanned with the same flag grammar as `parseArgs`, so
+ * error reporting can recover the invoked resource/action without depending
+ * on the command registry being loaded.
+ */
+export function rawPositionals(argv) {
+    const positionals = [];
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg === "--") {
+            positionals.push(...argv.slice(index + 1));
+            break;
+        }
+        if (arg.startsWith("--")) {
+            const name = arg.slice(2).split("=")[0] ?? "";
+            const canonical = FLAG_ALIASES[name] ?? name;
+            if (!arg.includes("=") && VALUE_FLAGS.has(canonical))
+                index++;
+            continue;
+        }
+        if (arg.length === 2 && arg[0] === "-" && arg[1] !== "-") {
+            const long = SHORT_FLAGS[arg[1]];
+            if (long && VALUE_FLAGS.has(long))
+                index++;
+            continue;
+        }
+        positionals.push(arg);
+    }
+    return positionals;
+}
+/** Unknown flags name the invoked command, so the error carries its usage line. */
+function commandUnknownFlagError(flagLabel, argv) {
+    const [resource, action,] = rawPositionals(argv);
+    return unknownFlagError(flagLabel, resource, action);
+}
 /** Planning wins dispatch; dryRun remains set for combined plan metadata. */
 export function executionMode(flags) {
     return {
@@ -31,11 +66,17 @@ export const BOOLEAN_FLAGS = new Set([
     "if-exists",
     "no-wait",
     "force-rebuild",
+    "auto-update-schema",
     "latest",
+    "full",
     "copy-output-settings",
     "copy-permissions",
     "continue-on-error",
     "no-backup",
+    "no-auto-rebuild",
+    "all-users",
+    "with-scenarios",
+    "for-everybody",
     "payload-only",
     "allow-same-path",
     "sync",
@@ -249,6 +290,37 @@ export const VALUE_FLAGS = new Set([
     "full-class-name",
     "include-libs",
     "archive",
+    "stop-at",
+    "mark-ok",
+    "template-file",
+    "group-by",
+    "aggregate",
+    "order-by",
+    "rename",
+    "fill-empty",
+    "formula",
+    "filter",
+    "drop-columns",
+    "keep-columns",
+    "columns",
+    "format-option",
+    "bundle-id",
+    "archive-path",
+    "project-folder",
+    "classes",
+    "version-id",
+    "evaluation-dataset",
+    "experiments",
+    "view-type",
+    "format",
+    "kind",
+    "features",
+    "sample-size",
+    "random-state",
+    "n-jobs",
+    "time-variable",
+    "timeseries-ids",
+    "full-reguess",
 ]);
 export const REPEATABLE_VALUE_FLAGS = new Set([
     "dataset",
@@ -269,12 +341,12 @@ export const KNOWN_LONG_FLAGS = new Set([
     ...Object.keys(FLAG_ALIASES),
     ...Object.values(FLAG_ALIASES),
 ]);
-export function normalizeLongFlag(rawFlagName) {
+export function normalizeLongFlag(rawFlagName, argv) {
     if (rawFlagName === "help")
         throw unsupportedHelpFlag();
     const flagName = FLAG_ALIASES[rawFlagName] ?? rawFlagName;
     if (!KNOWN_LONG_FLAGS.has(rawFlagName) && !KNOWN_LONG_FLAGS.has(flagName)) {
-        throw new UsageError(`Unknown flag: --${rawFlagName}`, "unknown_flag");
+        throw commandUnknownFlagError(`--${rawFlagName}`, argv);
     }
     return flagName;
 }
@@ -309,7 +381,7 @@ export function parseArgs(argv) {
             const eqIdx = arg.indexOf("=");
             if (eqIdx !== -1) {
                 const raw = arg.slice(2, eqIdx);
-                const flagName = normalizeLongFlag(raw);
+                const flagName = normalizeLongFlag(raw, argv);
                 const value = arg.slice(eqIdx + 1);
                 if (BOOLEAN_FLAGS.has(flagName)) {
                     flags[flagName] = parseBooleanOption(value, `--${flagName}`);
@@ -320,7 +392,7 @@ export function parseArgs(argv) {
             }
             else {
                 const rawFlagName = arg.slice(2);
-                const flagName = normalizeLongFlag(rawFlagName);
+                const flagName = normalizeLongFlag(rawFlagName, argv);
                 if (BOOLEAN_FLAGS.has(flagName)) {
                     flags[flagName] = true;
                 }
@@ -346,7 +418,7 @@ export function parseArgs(argv) {
             else {
                 if (arg[1] === "h")
                     throw unsupportedHelpFlag();
-                throw new UsageError(`Unknown flag: -${arg[1]}`, "unknown_flag");
+                throw commandUnknownFlagError(`-${arg[1]}`, argv);
             }
         }
         else {

package/dist/src/cli/helpers/app-successor.js

@@ -1,4 +1,3 @@
-import { randomUUID, } from "node:crypto";
 import { DataikuError, } from "../../errors.js";
 import { projectIncarnationHash, } from "../../utils/project-incarnation.js";
 import { stableHash, stringField, } from "../coerce.js";
@@ -26,7 +25,7 @@ export const VISUAL_UI_GATE = {
  * probed for absence and is never retried under an alternate key.
  */
 export function generatedInstanceKey() {
-    return `APP_${randomUUID().replace(/-/g, "").toUpperCase()}`;
+    return `APP_${crypto.randomUUID().replace(/-/g, "").toUpperCase()}`;
 }
 /**
  * DSS answers the app-manifest probe with 400 ("neither an app template nor an

package/dist/src/cli/helpers/documentation.d.ts

@@ -0,0 +1,21 @@
+import type { DataikuClient } from "../../client.js";
+import type { DocumentationTemplate } from "../../resources/documentation.js";
+import type { DssTask, FutureWaitOptions } from "../../resources/futures.js";
+import type { FutureWaitResult } from "../../schemas.js";
+type Flags = Record<string, string | boolean>;
+/** Documentation template from flags: --template-file, or --folder with --path, or the DSS default. */
+export declare function documentationTemplateFromFlags(flags: Flags): DocumentationTemplate;
+/** `--poll-interval` / `--timeout` for commands that wait on a DSS task. */
+export declare function taskWaitOptions(flags: Flags): FutureWaitOptions;
+/**
+ * Shared `generate-documentation` flow: return the started task; with
+ * --wait, its final state; with --output PATH, wait and download the docx
+ * named by the result's `exportId`. A failed or timed-out generation carries
+ * no exportId, so its state is returned instead.
+ */
+export declare function runDocumentationCommand(client: DataikuClient, flags: Flags, task: DssTask, download: (exportId: string) => Promise<Response>): Promise<DssTask | FutureWaitResult | {
+    path: string;
+    bytes: number;
+    exportId: string;
+}>;
+export {};

package/dist/src/cli/helpers/documentation.js

@@ -0,0 +1,53 @@
+import { writeResponseToFile, } from "../../utils/response-file.js";
+import { num, } from "../coerce.js";
+import { UsageError, } from "../usage.js";
+/** Documentation template from flags: --template-file, or --folder with --path, or the DSS default. */
+export function documentationTemplateFromFlags(flags) {
+    const file = flags["template-file"];
+    const folder = flags["folder"];
+    const path = flags["path"];
+    if (typeof file === "string" && (folder !== undefined || path !== undefined)) {
+        throw new UsageError("Use either --template-file or --folder with --path, not both.", "conflicting_input_sources");
+    }
+    if (typeof file === "string")
+        return { kind: "file", filePath: file, };
+    if (typeof folder === "string" || typeof path === "string") {
+        if (typeof folder !== "string" || typeof path !== "string") {
+            throw new UsageError("A template in a managed folder needs both --folder FOLDER_ID and --path PATH.", "missing_required_flag");
+        }
+        return { kind: "folder", folderId: folder, path, };
+    }
+    return { kind: "default", };
+}
+/** `--poll-interval` / `--timeout` for commands that wait on a DSS task. */
+export function taskWaitOptions(flags) {
+    return {
+        pollIntervalMs: num(flags["poll-interval"], "--poll-interval"),
+        timeoutMs: num(flags["timeout"], "--timeout"),
+    };
+}
+/**
+ * Shared `generate-documentation` flow: return the started task; with
+ * --wait, its final state; with --output PATH, wait and download the docx
+ * named by the result's `exportId`. A failed or timed-out generation carries
+ * no exportId, so its state is returned instead.
+ */
+export async function runDocumentationCommand(client, flags, task, download) {
+    const output = flags["output"];
+    if (flags["wait"] !== true && typeof output !== "string")
+        return task;
+    const waited = await client.futures.waitTask(task, taskWaitOptions(flags));
+    if (typeof output !== "string")
+        return waited;
+    const result = waited.result;
+    const exportId = result && typeof result === "object" && "exportId" in result
+        ? result.exportId
+        : undefined;
+    if (typeof exportId !== "string")
+        return waited;
+    return {
+        path: output,
+        bytes: await writeResponseToFile(output, await download(exportId)),
+        exportId,
+    };
+}

package/dist/src/cli/helpers/trained-model.d.ts

@@ -0,0 +1,26 @@
+import type { DataikuClient } from "../../client.js";
+import { type ComputedModelDiagnostic, type ModelDiagnostic, type ModelDiagnosticsComputation, type TrainedModel } from "../../resources/trained-model.js";
+import type { CommandDefinition } from "../types.js";
+type Flags = Record<string, string | boolean>;
+export declare function diagnosticKindFromFlags(flags: Flags): ModelDiagnostic;
+/** `compute-diagnostics` flags → kind, features, and computation settings (shared with --plan). */
+export declare function diagnosticsComputationFromFlags(flags: Flags): {
+    kind: ComputedModelDiagnostic;
+    features: string[];
+    computation: ModelDiagnosticsComputation;
+};
+export interface TrainedModelCommandSpec {
+    resource: "ml-task" | "saved-model";
+    /** Positional ids in examples, e.g. `ANALYSIS_ID TASK_ID MODEL_ID`. */
+    ids: string;
+    /** What one model is called in descriptions: "lab model" or "saved-model version". */
+    noun: string;
+    model: (client: DataikuClient, args: string[], projectKey: string | undefined) => TrainedModel;
+    downloadDocumentation: (client: DataikuClient, exportId: string, projectKey: string | undefined) => Promise<Response>;
+}
+/**
+ * The actions lab models and saved-model versions share, over one
+ * {@link TrainedModel}: user meta, scoring exports, diagnostics, documentation.
+ */
+export declare function trainedModelCommands(spec: TrainedModelCommandSpec): Record<string, CommandDefinition>;
+export {};

package/dist/src/cli/helpers/trained-model.js

@@ -0,0 +1,144 @@
+import { unexpectedResponseError, } from "../../errors.js";
+import { COMPUTED_MODEL_DIAGNOSTICS, MODEL_DIAGNOSTICS, } from "../../resources/trained-model.js";
+import { writeResponseToFile, } from "../../utils/response-file.js";
+import { num, parseBooleanOption, requiredJsonInput, splitCsvFlag, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
+import { commandUsage, } from "../syntax.js";
+import { requireArgs, UsageError, } from "../usage.js";
+import { documentationTemplateFromFlags, runDocumentationCommand, taskWaitOptions, } from "./documentation.js";
+export function diagnosticKindFromFlags(flags) {
+    const kind = flags["kind"];
+    if (typeof kind !== "string" || MODEL_DIAGNOSTICS[kind] !== true) {
+        throw new UsageError(`--kind must be one of ${Object.keys(MODEL_DIAGNOSTICS).join(", ")}.`, "invalid_enum");
+    }
+    return kind;
+}
+/** `compute-diagnostics` flags → kind, features, and computation settings (shared with --plan). */
+export function diagnosticsComputationFromFlags(flags) {
+    const kind = flags["kind"];
+    if (typeof kind !== "string" || COMPUTED_MODEL_DIAGNOSTICS[kind] !== true) {
+        throw new UsageError(`--kind must be one of ${Object.keys(COMPUTED_MODEL_DIAGNOSTICS).join(", ")}.`, "invalid_enum");
+    }
+    const sampleSize = num(flags["sample-size"], "--sample-size");
+    const randomState = num(flags["random-state"], "--random-state");
+    const nJobs = num(flags["n-jobs"], "--n-jobs");
+    return {
+        kind: kind,
+        features: splitCsvFlag(flags["features"]),
+        computation: {
+            ...(sampleSize !== undefined ? { sampleSize, } : {}),
+            ...(randomState !== undefined ? { randomState, } : {}),
+            ...(nJobs !== undefined ? { nJobs, } : {}),
+        },
+    };
+}
+/** Write a binary export to `--output`; DSS answering without a body is an unexpected response. */
+async function writeExport(res, out, operation) {
+    if (!res.body)
+        throw unexpectedResponseError(`${operation} response did not include a body`);
+    return { path: out, bytes: await writeResponseToFile(out, res), };
+}
+function requiredOutput(flags) {
+    const out = flags["output"];
+    if (typeof out !== "string") {
+        throw new UsageError("--output PATH is required.", "missing_required_flag");
+    }
+    return out;
+}
+/**
+ * The actions lab models and saved-model versions share, over one
+ * {@link TrainedModel}: user meta, scoring exports, diagnostics, documentation.
+ */
+export function trainedModelCommands(spec) {
+    const { resource, ids, noun, } = spec;
+    const argCount = ids.split(" ").length;
+    const model = (c, a, f, action) => {
+        requireArgs(a, argCount, commandUsage(resource, action));
+        return spec.model(c, a, f["project-key"]);
+    };
+    return {
+        "set-user-meta": {
+            handler: async (c, a, f) => {
+                const target = model(c, a, f, "set-user-meta");
+                const userMeta = requiredJsonInput(f, "User-meta JSON is required via --data, --data-file, or --stdin.");
+                if (executionMode(f).dryRun) {
+                    return {
+                        dryRun: true,
+                        action: "set-user-meta",
+                        resource,
+                        ids: a.slice(0, argCount),
+                        payload: userMeta,
+                    };
+                }
+                await target.setUserMeta(userMeta);
+                return { updated: a[argCount - 1], resource, };
+            },
+            description: `Update the user metadata (name, description, labels, ...) of a ${noun}. Send only the "userMeta" field of its details, edited.`,
+            examples: [
+                `dss ${resource} set-user-meta ${ids} --data '{"name":"Churn model","description":"v2"}'`,
+            ],
+        },
+        "download-scoring-jar": {
+            handler: async (c, a, f) => {
+                const target = model(c, a, f, "download-scoring-jar");
+                const out = requiredOutput(f);
+                const fullClassName = f["full-class-name"];
+                const res = await target.downloadScoringJar({
+                    ...(typeof fullClassName === "string" ? { fullClassName, } : {}),
+                    ...(f["include-libs"] !== undefined
+                        ? { includeLibs: parseBooleanOption(f["include-libs"], "--include-libs"), }
+                        : {}),
+                });
+                return writeExport(res, out, "Scoring JAR download");
+            },
+            description: `Download the optimized scoring JAR of a ${noun} (license-gated server side). --full-class-name sets the Java class; --include-libs toggles bundling the scoring libraries.`,
+            examples: [`dss ${resource} download-scoring-jar ${ids} --output ./scoring.jar`,],
+        },
+        "download-scoring-pmml": {
+            handler: async (c, a, f) => {
+                const target = model(c, a, f, "download-scoring-pmml");
+                const out = requiredOutput(f);
+                return writeExport(await target.downloadScoringPmml(), out, "Scoring PMML download");
+            },
+            description: `Download the PMML scoring file of a ${noun} (license-gated server side).`,
+            examples: [`dss ${resource} download-scoring-pmml ${ids} --output ./model.pmml`,],
+        },
+        diagnostics: {
+            handler: (c, a, f) => model(c, a, f, "diagnostics").get(diagnosticKindFromFlags(f)),
+            description: `Read computed diagnostics of a ${noun}: subpopulation-analyses, partial-dependencies, timeseries-residuals, or (forecasting) per-timeseries-metrics / per-timeseries-evaluation-forecasts.`,
+            examples: [`dss ${resource} diagnostics ${ids} --kind partial-dependencies`,],
+        },
+        "compute-diagnostics": {
+            handler: async (c, a, f) => {
+                const target = model(c, a, f, "compute-diagnostics");
+                const { kind, features, computation, } = diagnosticsComputationFromFlags(f);
+                const task = await target.compute(kind, features, computation);
+                return f["wait"] === true ? c.futures.waitTask(task, taskWaitOptions(f)) : task;
+            },
+            description: `Compute subpopulation-analyses or partial-dependencies over --features COLS (--sample-size N, default 10000), or timeseries-residuals, for a ${noun}. Returns the DSS future; --wait waits and returns the result.`,
+            examples: [
+                `dss ${resource} compute-diagnostics ${ids} --kind partial-dependencies --features age,income --wait`,
+            ],
+        },
+        "generate-documentation": {
+            handler: async (c, a, f) => {
+                const target = model(c, a, f, "generate-documentation");
+                const pk = f["project-key"];
+                const task = await target.generateDocumentation(documentationTemplateFromFlags(f));
+                return runDocumentationCommand(c, f, task, (exportId) => spec.downloadDocumentation(c, exportId, pk));
+            },
+            description: `Generate the model documentation (Word docx) of a ${noun} from the DSS default template, an uploaded --template-file, or a template in a managed folder (--folder FOLDER_ID --path PATH). Returns the DSS future; --wait waits; --output PATH waits and downloads.`,
+            examples: [`dss ${resource} generate-documentation ${ids} --output model.docx`,],
+        },
+        "download-documentation": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, commandUsage(resource, "download-documentation"));
+                const out = requiredOutput(f);
+                const res = await spec.downloadDocumentation(c, a[0], f["project-key"]);
+                return writeExport(res, out, "Model documentation download");
+            },
+            description: "Download a generated model documentation by the exportId from a finished generate-documentation future.",
+            examples: [`dss ${resource} download-documentation EXPORT_ID --output model.docx`,],
+        },
+    };
+}

package/dist/src/cli/list-output.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shape a `*.list` result for agents: `--contains` filters on identifier
+ * fields, `--limit` caps the count (a `list_truncated` warning reports the
+ * total), and large DSS objects compact to their decision fields unless
+ * `--full` or `--fields` asks for the DSS objects.
+ */
+export declare function shapeListResult(resource: string, result: unknown, flags: Record<string, string | boolean>): unknown;

package/dist/src/cli/list-output.js

@@ -0,0 +1,77 @@
+import { num, } from "./coerce.js";
+import { COMPACT_LIST_FIELDS, } from "./list-shapes.js";
+import { enqueueCliWarning, } from "./output.js";
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function compactValue(item, spec) {
+    let value = item;
+    for (const key of spec.path.split("."))
+        value = record(value)[key];
+    if (spec.roleRefs !== true)
+        return value;
+    // Dataset refs across every role of recipe inputs/outputs (`{main:{items:[{ref}]}}`).
+    return Object.values(record(value)).flatMap((role) => {
+        const items = record(role).items;
+        return Array.isArray(items)
+            ? items.flatMap((entry) => {
+                const ref = record(entry).ref;
+                return typeof ref === "string" ? [ref,] : [];
+            })
+            : [];
+    });
+}
+/** Identifier fields `--contains` matches; string items match themselves. */
+const IDENTIFIER_FIELDS = [
+    "id",
+    "name",
+    "projectKey",
+    "envName",
+    "login",
+    "displayName",
+    "label",
+    "runnableType",
+];
+/** `job list` filters by --contains/--limit itself (job name, state, outputs). */
+const LISTS_WITH_OWN_FILTERS = { job: true, };
+function itemMatches(item, needle) {
+    if (typeof item === "string")
+        return item.toLowerCase().includes(needle);
+    const fields = record(item);
+    return IDENTIFIER_FIELDS.some((field) => {
+        const value = fields[field];
+        return typeof value === "string" && value.toLowerCase().includes(needle);
+    });
+}
+/**
+ * Shape a `*.list` result for agents: `--contains` filters on identifier
+ * fields, `--limit` caps the count (a `list_truncated` warning reports the
+ * total), and large DSS objects compact to their decision fields unless
+ * `--full` or `--fields` asks for the DSS objects.
+ */
+export function shapeListResult(resource, result, flags) {
+    if (!Array.isArray(result))
+        return result;
+    let items = result;
+    if (LISTS_WITH_OWN_FILTERS[resource] !== true) {
+        const contains = flags["contains"];
+        if (typeof contains === "string" && contains.length > 0) {
+            const needle = contains.toLowerCase();
+            items = items.filter((item) => itemMatches(item, needle));
+        }
+        const limit = num(flags["limit"], "--limit");
+        if (limit !== undefined && items.length > limit) {
+            enqueueCliWarning({
+                code: "list_truncated",
+                shown: limit,
+                total: items.length,
+                hint: "Raise --limit or narrow with --contains.",
+            });
+            items = items.slice(0, Math.max(0, limit));
+        }
+    }
+    const fields = COMPACT_LIST_FIELDS[resource];
+    if (!fields || flags["full"] === true || typeof flags["fields"] === "string")
+        return items;
+    return items.map((item) => Object.fromEntries(Object.entries(fields).map(([name, spec,]) => [name, compactValue(record(item), spec),])));
+}

package/dist/src/cli/list-shapes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Compact `RESOURCE.list` item shapes, as plain data shared by the runtime
+ * mapper (src/cli/list-output.ts) and the discovery output schemas
+ * (src/cli/output-schemas.ts), so the advertised schema is the emitted shape.
+ */
+/** Where a compact field comes from in the DSS object, and its JSON Schema. */
+export interface CompactListField {
+    /** Dotted path into the DSS list item. */
+    path: string;
+    /** Flatten recipe roles (`{main:{items:[{ref}]}}`) to the dataset refs. */
+    roleRefs?: true;
+    schema: Record<string, unknown>;
+}
+/**
+ * Lists whose DSS objects are large: the identifier the follow-up get/build
+ * commands take, the kind, and the one or two attributes that decide what to
+ * call next. Lists not named here keep the DSS objects.
+ */
+export declare const COMPACT_LIST_FIELDS: Record<string, Record<string, CompactListField>>;
+/** Discovery output schemas of the compact `RESOURCE.list` defaults. */
+export declare function compactListOutputSchemas(): Record<string, Record<string, unknown>>;