dataiku-sdk 3.6.1 → 3.8.0

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

@@ -1,13 +1,14 @@
 import { readFileSync, } from "node:fs";
 import { writeFile, } from "node:fs/promises";
 import { join, } from "node:path";
-import { ClientValidationError, } from "../../errors.js";
+import { ClientValidationError, DataikuError, } from "../../errors.js";
+import { recipeCreateWarnings, recipeOutputSchemaIsComputable, schemaUpdateComputableId, schemaUpdateIsPending, } from "../../resources/recipe-create.js";
 import { deepMerge, } from "../../utils/deep-merge.js";
 import { jobLogFilterFromFlag, jsonInput, maxLogLinesFromFlags, normalizeLineEndings, num, recipeInputDatasetsFromFlags, requiredJsonInput, requiredStringFlag, rewritePairsFromFlags, sha256Hex, splitCsvFlag, stableHash, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { moveCreatedItemsToZone, resolveFlowZoneIdFromFlags, } from "../helpers/flow-zone.js";
 import { ensureRecipeBackupDir, readRecipeBackup, recipeBackupDocument, recipeBackupPath, recipeCodeEnv, recipeGraph, recipeInputItemRef, recipeRoleInputItems, recipeRunShouldWait, writeRecipeBackup, } from "../helpers/recipe.js";
-import { encodedProjectEndpoint, readIfExists, skipResult, } from "../output.js";
+import { encodedProjectEndpoint, enqueueCliWarning, readIfExists, skipResult, } from "../output.js";
 import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
 /** Read a local recipe file before any DSS request, mapping read failures to usage validation. */
@@ -30,6 +31,51 @@ function readRecipeBackupFile(backupPath) {
         throw new UsageError(`Could not read --backup ${backupPath}: ${reason}.`, "not_found", "Verify the backup file path and that it is readable.");
     }
 }
+/**
+ * DSS does not recompute visual-recipe output schemas when the recipe is
+ * saved, and a build against a stale or empty output schema "succeeds" with
+ * the wrong columns. Around a payload write: outputs whose schema matched the
+ * DSS-computed one before the write (DSS-derived) or is empty get the newly
+ * computed schema; outputs whose schema had been hand-edited are left alone
+ * and reported in a warning.
+ */
+async function writeKeepingDerivedOutputSchemas(c, recipeName, recipeType, projectKey, write) {
+    if (typeof recipeType !== "string" || !recipeOutputSchemaIsComputable(recipeType)) {
+        await write();
+        return {};
+    }
+    const derivedOutputs = await c.recipes.computeSchemaUpdates(recipeName, projectKey).then((before) => before.computables.filter((computable) => !schemaUpdateIsPending(computable)).map(schemaUpdateComputableId), 
+    // Unknown before-state: only empty schemas are safe to fill.
+    (error) => {
+        if (error instanceof DataikuError)
+            return [];
+        throw error;
+    });
+    await write();
+    try {
+        const result = await c.recipes.updateSchema(recipeName, { projectKey, derivedOutputs, });
+        if (result.pending.length > 0) {
+            enqueueCliWarning({
+                code: "recipe_output_schema_outdated",
+                recipe: recipeName,
+                outputs: result.pending,
+                hint: `These outputs have an edited schema that differs from the DSS-computed one. Run dss recipe update-schema ${recipeName} to replace it, or build with --auto-update-schema.`,
+            });
+        }
+        return result.updated.length > 0 ? { outputSchemaUpdated: result.updated, } : {};
+    }
+    catch (error) {
+        if (!(error instanceof DataikuError))
+            throw error;
+        enqueueCliWarning({
+            code: "recipe_output_schema_not_computed",
+            recipe: recipeName,
+            error: error.message.split("\n")[0],
+            hint: `Fix the recipe settings, then run dss recipe update-schema ${recipeName}.`,
+        });
+        return {};
+    }
+}
 function formatLineDiff(remoteName, localPath, remoteContent, localContent) {
     // Line-ending differences are not content differences: compare and split on
     // CRLF-normalized text, mirroring assert-unchanged's normalized payload hash.
@@ -61,6 +107,19 @@ function formatLineDiff(remoteName, localPath, remoteContent, localContent) {
     }
     return lines.join("\n");
 }
+const PREPARE_STEP_FLAGS = {
+    "rename": "rename",
+    "fill-empty": "fillEmpty",
+    "formula": "formula",
+    "filter": "filter",
+    "drop-columns": "dropColumns",
+    "keep-columns": "keepColumns",
+};
+/** Queue the stderr warnings for `recipe create` options (also used by `--plan` and `--dry-run`). */
+export function enqueueRecipeCreateWarnings(options) {
+    for (const warning of recipeCreateWarnings(options))
+        enqueueCliWarning(warning);
+}
 /** Maps `recipe create` flags to SDK options; shared by the handler and `--plan`. */
 export function recipeCreateOptionsFromFlags(f) {
     const type = f["type"];
@@ -99,6 +158,11 @@ export function recipeCreateOptionsFromFlags(f) {
         fuzzyDistance = normalized;
     }
     const fuzzyThreshold = num(f["fuzzy-threshold"], "--fuzzy-threshold");
+    // Prepare option groups run in the order their flags were typed (object keys keep first-use order).
+    const stepOrder = Object.keys(f).flatMap((flag) => {
+        const kind = Object.hasOwn(PREPARE_STEP_FLAGS, flag) ? PREPARE_STEP_FLAGS[flag] : undefined;
+        return kind ? [kind,] : [];
+    });
     const payload = {
         type,
         name,
@@ -112,10 +176,24 @@ export function recipeCreateOptionsFromFlags(f) {
         ...(fuzzyDistance ? { fuzzyDistance, } : {}),
         ...(fuzzyThreshold !== undefined ? { fuzzyThreshold, } : {}),
         fuzzyNormalize: f["normalize"] === true,
+        ...csvOption("groupBy", f["group-by"]),
+        ...csvOption("aggregate", f["aggregate"]),
+        ...(typeof f["order-by"] === "string" ? { orderBy: f["order-by"], } : {}),
+        ...csvOption("rename", f["rename"]),
+        ...csvOption("fillEmpty", f["fill-empty"]),
+        ...(typeof f["formula"] === "string" ? { formula: f["formula"], } : {}),
+        ...(typeof f["filter"] === "string" ? { filter: f["filter"], } : {}),
+        ...csvOption("dropColumns", f["drop-columns"]),
+        ...csvOption("keepColumns", f["keep-columns"]),
+        ...(stepOrder.length > 0 ? { stepOrder, } : {}),
         projectKey: pk,
     };
     return payload;
 }
+function csvOption(key, value) {
+    const items = splitCsvFlag(value);
+    return items.length > 0 ? { [key]: items, } : {};
+}
 export const recipeCommands = withUsage("recipe", {
     list: {
         handler: (c, _a, f) => c.recipes.list(f["project-key"]),
@@ -271,6 +349,7 @@ export const recipeCommands = withUsage("recipe", {
     create: {
         handler: async (c, _a, f) => {
             const payload = recipeCreateOptionsFromFlags(f);
+            enqueueRecipeCreateWarnings(payload);
             const name = payload.name;
             const pk = payload.projectKey;
             const zoneId = await resolveFlowZoneIdFromFlags(c, f, pk);
@@ -310,13 +389,38 @@ export const recipeCommands = withUsage("recipe", {
                     objectId: createdName,
                     objectType: "RECIPE",
                 },], pk);
+            if (created.requestedName) {
+                // DSS appends _N when the requested name is taken; any other difference is DSS naming
+                // the recipe itself. The public API has no recipe rename.
+                const suffix = createdName.startsWith(`${created.requestedName}_`)
+                    ? createdName.slice(created.requestedName.length + 1)
+                    : "";
+                const nameTaken = /^\d+$/.test(suffix);
+                enqueueCliWarning({
+                    code: "recipe_renamed",
+                    requestedName: created.requestedName,
+                    recipe: createdName,
+                    reason: nameTaken ? "name_taken" : "dss_chose_name",
+                    hint: nameTaken
+                        ? `A recipe named ${created.requestedName} already exists; use ${createdName} in follow-up commands.`
+                        : `DSS ignored the requested name; use ${createdName} in follow-up commands.`,
+                });
+            }
+            if (created.outputSchemaUpdateError) {
+                enqueueCliWarning({
+                    code: "recipe_output_schema_not_computed",
+                    recipe: createdName,
+                    error: created.outputSchemaUpdateError,
+                    hint: `Fix the recipe settings, then run dss recipe update-schema ${createdName}.`,
+                });
+            }
             return { created: createdName, resource: "recipe", ...created, ...moved, };
         },
-        description: "Create a recipe with optional inputs and a dataset or managed-folder output.",
+        description: "Create a recipe with optional inputs and a dataset or managed-folder output. Missing outputs are created on --output-connection as DSS managed datasets. Join, grouping (--group-by/--aggregate) and prepare (--rename/--formula/--filter/...) payloads come from flags. Visual recipe outputs get the DSS-computed schema (outputSchemaUpdated).",
         examples: [
             "dss recipe create --type python --input raw_orders,lookup --output orders_clean",
-            "dss recipe create --type python --input orders --input customers --output orders_clean --zone Experiments",
-            "dss recipe create --type python --input orders --output-folder LT7TUHJ8 --output-connection filesystem --dry-run",
+            "dss recipe create --type grouping --input orders --output orders_by_cat --group-by category --aggregate amount:sum+avg,name:first --order-by day",
+            "dss recipe create --type prepare --input orders --output orders_prep --rename name=label --formula 'total=amount * 2' --filter 'amount > 0'",
         ],
     },
     clone: {
@@ -586,22 +690,41 @@ export const recipeCommands = withUsage("recipe", {
                 ensureRecipeBackupDir(backupDir);
                 writeRecipeBackup(backupPath, `${JSON.stringify(recipeBackupDocument(a[0], pk, current), null, 2)}\n`);
             }
-            await c.recipes.replace(a[0], { ...current, payload: content, }, pk);
+            const schema = await writeKeepingDerivedOutputSchemas(c, a[0], current.recipe.type, pk, () => c.recipes.replace(a[0], { ...current, payload: content, }, pk));
             return {
                 updated: a[0],
                 resource: "recipe",
                 file: filePath,
                 backupCreated: backupPath !== undefined,
                 ...(backupPath ? { backupPath, } : {}),
+                ...schema,
             };
         },
-        description: "Upload recipe code from a local file, backing up payload, graph, settings, and version metadata by default.",
+        description: "Upload recipe code from a local file, backing up payload, graph, settings, and version metadata by default. For visual and SQL query recipes, outputs whose schema was empty or matched the DSS-computed one before the upload get the newly computed schema (outputSchemaUpdated); hand-edited output schemas are kept and reported in a recipe_output_schema_outdated warning.",
         examples: [
             "dss recipe set-payload compute_orders --file code.py --dry-run",
             "dss recipe set-payload compute_orders --file code.py --backup-dir ./backups",
             "dss recipe set-payload compute_orders --file code.py --no-backup",
         ],
     },
+    "update-schema": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, commandUsage("recipe", "update-schema"));
+            const dryRun = executionMode(f).dryRun;
+            const result = await c.recipes.updateSchema(a[0], {
+                projectKey: f["project-key"],
+                dryRun,
+            });
+            return dryRun
+                ? { dryRun: true, action: "update-schema", resource: "recipe", name: a[0], ...result, }
+                : result;
+        },
+        description: "Propagate schema changes: write the output schemas DSS computes from a visual or SQL query recipe (the UI's Update schema; dataikuapi compute_schema_updates().apply()) to every output whose schema differs. --dry-run lists them under pending. Code recipes are rejected: their code sets the schema when it runs.",
+        examples: [
+            "dss recipe update-schema compute_orders_joined --dry-run",
+            "dss recipe update-schema compute_orders_joined",
+        ],
+    },
     restore: {
         handler: async (c, a, f) => {
             const usage = commandUsage("recipe", "restore");

package/dist/src/cli/commands/saved-model.d.ts

@@ -1,6 +1,6 @@
 import type { CommandMeta } from "../types.js";
 /**
- * Mutating actions accept --plan (buildMutationPlan in contract.ts owns the
+ * Mutating actions accept --plan (buildMutationPlan in plans.ts owns the
  * --plan path centrally); the handlers below keep --dry-run support with a
  * zero-request planned payload, mirroring set-active/delete.
  */

package/dist/src/cli/commands/saved-model.js

@@ -1,12 +1,11 @@
-import { unexpectedResponseError, } from "../../errors.js";
-import { writeResponseToFile, } from "../../utils/response-file.js";
 import { json, jsonInput, parseBooleanOption, requiredJsonInput, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
+import { trainedModelCommands, } from "../helpers/trained-model.js";
 import { readIfExists, skipResult, } from "../output.js";
 import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
 /**
- * Mutating actions accept --plan (buildMutationPlan in contract.ts owns the
+ * Mutating actions accept --plan (buildMutationPlan in plans.ts owns the
  * --plan path centrally); the handlers below keep --dry-run support with a
  * zero-request planned payload, mirroring set-active/delete.
  */
@@ -361,79 +360,13 @@ export const savedModelCommands = withUsage("saved-model", {
             "dss saved-model evaluate-version MODEL_ID VERSION_ID --dataset ds --skip-expensive-reports true --project-key PROJECT",
         ],
     },
-    "download-scoring-jar": {
-        handler: async (c, a, f) => {
-            const usage = commandUsage("saved-model", "download-scoring-jar");
-            requireArgs(a, 2, usage);
-            const out = f["output"];
-            if (!out)
-                throw new UsageError("--output PATH is required.", "missing_required_flag");
-            const fullClassName = f["full-class-name"];
-            const jarOptions = {
-                ...(fullClassName !== undefined ? { fullClassName, } : {}),
-                ...(f["include-libs"] !== undefined
-                    ? { includeLibs: parseBooleanOption(f["include-libs"], "--include-libs"), }
-                    : {}),
-            };
-            const res = await c.savedModels.downloadScoringJar(jarOptions, a[0], a[1], f["project-key"]);
-            if (!res.body) {
-                throw unexpectedResponseError("savedModels.downloadScoringJar response did not include a body");
-            }
-            const bytes = await writeResponseToFile(out, res);
-            return { path: out, bytes, };
-        },
-        description: "Download the optimized scoring JAR of a version (license-gated server side). --full-class-name forwards the documented fullClassName query parameter; --include-libs toggles including scoring libraries.",
-        examples: [
-            "dss saved-model download-scoring-jar MODEL_ID VERSION_ID --output ./scoring.jar --project-key PROJECT",
-            "dss saved-model download-scoring-jar MODEL_ID VERSION_ID --output ./scoring.jar --full-class-name model.Model --include-libs false --project-key PROJECT",
-        ],
-    },
-    "download-scoring-pmml": {
-        handler: async (c, a, f) => {
-            requireArgs(a, 2, commandUsage("saved-model", "download-scoring-pmml"));
-            const out = f["output"];
-            if (!out)
-                throw new UsageError("--output PATH is required.", "missing_required_flag");
-            const res = await c.savedModels.downloadScoringPmml(a[0], a[1], f["project-key"]);
-            if (!res.body) {
-                throw unexpectedResponseError("savedModels.downloadScoringPmml response did not include a body");
-            }
-            const bytes = await writeResponseToFile(out, res);
-            return { path: out, bytes, };
-        },
-        description: "Download the PMML scoring file of a version (license-gated server side).",
-        examples: [
-            "dss saved-model download-scoring-pmml MODEL_ID VERSION_ID --output ./model.pmml --project-key PROJECT",
-        ],
-    },
-    "set-user-meta": {
-        handler: async (c, a, f) => {
-            const usage = commandUsage("saved-model", "set-user-meta");
-            requireArgs(a, 2, usage);
-            const userMeta = requiredJsonInput(f, "User-meta JSON is required via --data, --data-file, or --stdin.");
-            const projectKey = f["project-key"];
-            if (executionMode(f).dryRun) {
-                return {
-                    dryRun: true,
-                    action: "set-user-meta",
-                    resource: "saved-model",
-                    id: a[0],
-                    versionId: a[1],
-                    projectKey,
-                    payload: userMeta,
-                };
-            }
-            return c.savedModels.setUserMeta(a[0], a[1], userMeta, projectKey).then(() => ({
-                updated: a[0],
-                versionId: a[1],
-                resource: "saved-model",
-            }));
-        },
-        description: 'Update the user metadata of a model version. Send only the "userMeta" field of a previously-retrieved version-details object.',
-        examples: [
-            'dss saved-model set-user-meta MODEL_ID VERSION_ID --data \'{"name":"Churn model","description":"v2"}\' --project-key PROJECT',
-        ],
-    },
+    ...trainedModelCommands({
+        resource: "saved-model",
+        ids: "MODEL_ID VERSION_ID",
+        noun: "saved-model version",
+        model: (c, a, pk) => c.savedModels.version(a[0], a[1], pk),
+        downloadDocumentation: (c, exportId, pk) => c.savedModels.downloadDocumentation(exportId, pk),
+    }),
 });
 function mlflowImportOptions(f) {
     const codeEnvName = f["code-env"];

package/dist/src/cli/commands/streaming-endpoint.js

@@ -1,6 +1,6 @@
 import { jsonInput, requiredJsonInput, } from "../coerce.js";
 import { commandUsage, withUsage, } from "../syntax.js";
-import { requireArgs, } from "../usage.js";
+import { requireArgs, UsageError, } from "../usage.js";
 export const streamingEndpointCommands = withUsage("streaming-endpoint", {
     list: {
         handler: (c, _a, f) => c.streamingEndpoints.list(f["project-key"]),
@@ -43,4 +43,33 @@ export const streamingEndpointCommands = withUsage("streaming-endpoint", {
         description: "Delete a streaming endpoint.",
         examples: ["dss streaming-endpoint delete my-stream",],
     },
+    "create-managed": {
+        handler: async (c, a, f) => {
+            const connectionId = f["connection"];
+            if (typeof connectionId !== "string") {
+                throw new UsageError("--connection CONN is required.", "missing_required_flag");
+            }
+            const formatOptionId = f["format-option"];
+            await c.streamingEndpoints.createManaged(a[0], {
+                connectionId,
+                ...(typeof formatOptionId === "string" ? { formatOptionId, } : {}),
+            }, f["project-key"]);
+            return { created: a[0], resource: "streaming-endpoint", };
+        },
+        description: "Create a managed streaming endpoint on a connection; DSS picks type and params from the connection (--format-option for the message format).",
+        examples: ["dss streaming-endpoint create-managed orders_stream --connection kafka_main",],
+    },
+    schema: {
+        handler: (c, a, f) => c.streamingEndpoints.getSchema(a[0], f["project-key"]),
+        description: "Get a streaming endpoint's schema ({columns: [{name, type}]}).",
+        examples: ["dss streaming-endpoint schema orders_stream",],
+    },
+    "set-schema": {
+        handler: async (c, a, f) => {
+            await c.streamingEndpoints.setSchema(a[0], requiredJsonInput(f, '--data, --data-file, or --stdin is required ({"columns": [...]}).'), f["project-key"]);
+            return { updated: a[0], resource: "streaming-endpoint", };
+        },
+        description: "Replace a streaming endpoint's schema with an object from the schema action, edited.",
+        examples: ["dss streaming-endpoint set-schema orders_stream --data-file schema.json",],
+    },
 });

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

@@ -113,4 +113,12 @@ export const webappCommands = withUsage("webapp", {
         description: "Get a webapp backend's runtime state.",
         examples: ["dss webapp backend-state WEBAPP_ID",],
     },
+    trust: {
+        handler: (c, a, f) => c.webapps.trust(a[0], {
+            projectKey: f["project-key"],
+            ...(f["for-everybody"] === true ? { trustForEverybody: true, } : {}),
+        }),
+        description: "Trust a webapp's code so it can run for you, or for every user with --for-everybody (admin). Returns canAccess and trustedCodeStatus.",
+        examples: ["dss webapp trust VCMN2ra", "dss webapp trust VCMN2ra --for-everybody",],
+    },
 });

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

@@ -1,3 +1,4 @@
+import { findWikiAttachment, statWikiAttachmentFile, wikiAttachmentNotFound, wikiAttachments, } from "../../resources/wiki.js";
 import { deepMerge, } from "../../utils/deep-merge.js";
 import { jsonInput, textInput, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
@@ -117,4 +118,81 @@ export const wikiCommands = withUsage("wiki", {
         description: "Delete a wiki article.",
         examples: ["dss wiki delete ARTICLE_ID --dry-run",],
     },
+    attach: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 2, commandUsage("wiki", "attach"));
+            const pk = f["project-key"];
+            const file = await statWikiAttachmentFile(a[1]);
+            if (executionMode(f).dryRun) {
+                const current = await c.wiki.get(a[0], pk);
+                return {
+                    dryRun: true,
+                    action: "attach",
+                    resource: "wiki",
+                    article: a[0],
+                    file,
+                    current: wikiAttachments(current),
+                };
+            }
+            const result = await c.wiki.attach(a[0], a[1], pk);
+            return { attached: result.attachment.smartId, resource: "wiki", ...result, };
+        },
+        description: "Upload a local file and attach it to a wiki article; returns its smartId.",
+        examples: ["dss wiki attach ARTICLE_ID ./diagram.png --dry-run",],
+    },
+    detach: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 2, commandUsage("wiki", "detach"));
+            const pk = f["project-key"];
+            const ifExists = f["if-exists"] === true;
+            const dryRun = executionMode(f).dryRun;
+            if (dryRun || ifExists) {
+                const current = ifExists
+                    ? await readIfExists(() => c.wiki.get(a[0], pk))
+                    : await c.wiki.get(a[0], pk);
+                const attachment = current && findWikiAttachment(current, a[1]);
+                if (!current || !attachment) {
+                    if (!ifExists && current)
+                        throw wikiAttachmentNotFound(current, a[1]);
+                    return skipResult("wiki", a[1], "missing", { article: a[0], });
+                }
+                if (dryRun) {
+                    return {
+                        dryRun: true,
+                        action: "detach",
+                        resource: "wiki",
+                        article: a[0],
+                        smartId: a[1],
+                        current: attachment,
+                    };
+                }
+            }
+            const result = await c.wiki.detach(a[0], a[1], pk);
+            return { resource: "wiki", ...result, };
+        },
+        description: "Remove one attachment from a wiki article by smartId.",
+        examples: ["dss wiki detach ARTICLE_ID SMART_ID --if-exists",],
+    },
+    "update-settings": {
+        handler: async (c, _a, f) => {
+            const pk = f["project-key"];
+            const settings = jsonInput(f);
+            if (!settings) {
+                throw new UsageError("--data, --data-file, or --stdin is required.", "missing_required_flag");
+            }
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "update-settings",
+                    resource: "wiki",
+                    current: await c.wiki.settings(pk),
+                    next: settings,
+                };
+            }
+            await c.wiki.updateSettings(settings, pk);
+            return { updated: "wiki", resource: "wiki", };
+        },
+        description: "Replace the wiki properties (home article id and taxonomy tree) with an object from dss wiki settings, edited.",
+        examples: ["dss wiki update-settings --data-file wiki.json --dry-run",],
+    },
 });

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

@@ -59,4 +59,12 @@ export const workspaceCommands = withUsage("workspace", {
         description: "Add an object (link or DSS object) to a workspace.",
         examples: ["dss workspace add-object MY_WS --data-file object.json",],
     },
+    "remove-object": {
+        handler: async (c, a) => {
+            await c.workspaces.removeObject(a[0], a[1]);
+            return { removed: a[1], resource: "workspace", workspace: a[0], };
+        },
+        description: "Remove an object from a workspace by its workspace object id (see list-objects).",
+        examples: ["dss workspace remove-object MY_WORKSPACE abcd1234",],
+    },
 });

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

@@ -1,5 +1,6 @@
 import { type CommandInputContract, type CommandPositionalMetadata } from "./syntax.js";
 import type { CommandFlagChoice, CommandMeta, CommandPayloadSchema } from "./types.js";
+export declare function splitPackageSpec(raw: string): string[];
 export declare const AUTH_ACTIONS: Record<string, {
     handler: (flags: Record<string, string | boolean>) => Promise<unknown>;
     description?: string;
@@ -35,8 +36,7 @@ export interface CommandRequiredInputGroup {
     oneOf: CommandRequiredInputAlternative[];
 }
 export interface CommandStructuredExample {
-    shell: string;
-    argv?: string[];
+    argv: string[];
     payload?: unknown;
 }
 export interface CommandUnsafeOutput {
@@ -58,7 +58,6 @@ export interface CommandRegistryEntry {
     examples?: string[];
     structuredExamples: CommandStructuredExample[];
     flags: CommandFlagMetadata[];
-    positionals: string[];
     positionalArguments: CommandPositionalMetadata[];
     sideEffect: CommandSideEffect;
     requiresAuth: boolean;
@@ -92,22 +91,24 @@ export declare function isAllowedCleanupAction(resource: string, action: string)
 export declare function buildCommandSchemas(resource: string, action: string, flags: CommandFlagMetadata[], requiredFlags: string[], requiredOneOf: CommandFlagChoice[], payloadSchema: CommandPayloadSchema | undefined, outputShape: CommandOutputShape, usage: string): CommandAgentSchemas;
 export declare function supportsCleanupLedger(resource: string, action: string): boolean;
 export declare function inferCleanupHint(resource: string, action: string): string | undefined;
+export declare function buildRegistryEntry(resource: string, action: string, meta: CommandMeta): CommandRegistryEntry;
 export declare function buildCommandRegistry(resourceFilter?: string): Record<string, Record<string, CommandRegistryEntry>>;
+export interface CommandSearchMatch {
+    id: string;
+    usage: string;
+    description: string;
+}
+/**
+ * Find actions by concept: every query word of three or more letters is
+ * matched (case-insensitively, trailing plural `s` ignored) against the action
+ * id, usage, and description. When some actions match every word, only those
+ * are returned; otherwise actions matching more words rank first. Matches in
+ * the id break ties. Reads command definitions only, never builds entries.
+ */
+export declare function searchCommands(query: string): CommandSearchMatch[];
 export declare function agentContractJsonSchema(): Record<string, unknown>;
 export declare function commandActionSummary(): Record<string, string[]>;
 export declare function buildAgentContract(): Record<string, unknown>;
-export declare function commandPlanShape(resource: string, action: string, args: string[], flags: Record<string, string | boolean>, entry: CommandRegistryEntry, projectKey: string | undefined): {
-    endpoint?: string;
-    exact?: boolean;
-    identifiers?: Record<string, unknown>;
-    method?: string;
-    payload?: unknown;
-    localWrites?: unknown;
-    reason?: string;
-    wait?: unknown;
-    requests?: unknown;
-};
-export declare function buildMutationPlan(resource: string, action: string, meta: CommandMeta, args: string[], flags: Record<string, string | boolean>): Record<string, unknown>;
 /**
  * Batch plans may surface exit 4: any dispatched step can be a long-running
  * lifecycle command whose remote work fails, or a synchronous assertion