dataiku-sdk 3.4.0 → 3.6.0

package/dist/src/cli/commands/code-env.js

@@ -1,9 +1,10 @@
 import { readFileSync, writeFileSync, } from "node:fs";
 import { ClientValidationError, } from "../../errors.js";
-import { stableHash, } from "../../utils/stable-hash.js";
+import { SHA256_HEX_PATTERN, stableHash, } from "../../utils/stable-hash.js";
 import { json, jsonInput, num, numFlag, parseBooleanOption, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { enqueueCliWarning, isNotFoundError, readIfExists, skipResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
 const CODE_ENV_LANGS = ["PYTHON", "R",];
 /** Validate a positional `<lang>` argument: required, must be PYTHON or R. */
@@ -24,10 +25,10 @@ function definitionHashMismatch(envLang, envName, expected, current) {
 function validateExpectHash(value) {
     if (value === undefined || value === false)
         return undefined;
-    if (typeof value !== "string" || !/^[0-9a-fA-F]{64}$/.test(value)) {
+    if (typeof value !== "string" || !SHA256_HEX_PATTERN.test(value)) {
         throw new ClientValidationError("Expected code env definition hash must be a 64-character SHA-256 hex digest.", "validation_failed", "Use the definitionHash value returned by dss code-env get.");
     }
-    return value;
+    return value.toLowerCase();
 }
 function codeEnvWait(flags) {
     return flags["no-wait"] !== true;
@@ -64,10 +65,10 @@ function codeEnvPackageList(flags) {
     }
     return packages;
 }
-export const codeEnvCommands = {
+export const codeEnvCommands = withUsage("code-env", {
     list: {
         handler: (c, _a, f) => {
-            const usage = "dss code-env list [--lang PYTHON|R]";
+            const usage = commandUsage("code-env", "list");
             const lang = f["lang"];
             return c.codeEnvs.list({
                 envLang: typeof lang === "string"
@@ -75,46 +76,42 @@ export const codeEnvCommands = {
                     : undefined,
             });
         },
-        usage: "dss code-env list [--lang PYTHON|R]",
         description: "List code environments, optionally filtered to one language.",
         examples: ["dss code-env list", "dss code-env list --lang PYTHON",],
     },
     get: {
         handler: (c, a) => {
-            const usage = "dss code-env get <lang> <name>";
+            const usage = commandUsage("code-env", "get");
             requireArgs(a, 2, usage);
             const envLang = requireEnvLang(a[0], usage);
             return c.codeEnvs.get(envLang, a[1]);
         },
-        usage: "dss code-env get <lang> <name>",
         description: "Get code environment details: requested vs installed packages, Python interpreter, deployment mode, and the stable definition hash (definitionHash) used by set-definition --expect-hash.",
         examples: ["dss code-env get PYTHON my_env",],
     },
     "get-definition": {
         handler: (c, a) => {
-            const usage = "dss code-env get-definition <lang> <name>";
+            const usage = commandUsage("code-env", "get-definition");
             requireArgs(a, 2, usage);
             const envLang = requireEnvLang(a[0], usage);
             return c.codeEnvs.getDefinition(envLang, a[1]);
         },
-        usage: "dss code-env get-definition <lang> <name>",
         description: "Get the raw code environment definition exactly as DSS stores it; capture its hash (definitionHash from code-env get) before replacing it with set-definition --expect-hash.",
         examples: ["dss code-env get-definition PYTHON my_env",],
     },
     "list-logs": {
         handler: (c, a) => {
-            const usage = "dss code-env list-logs <lang> <name>";
+            const usage = commandUsage("code-env", "list-logs");
             requireArgs(a, 2, usage);
             const envLang = requireEnvLang(a[0], usage);
             return c.codeEnvs.listLogs(envLang, a[1]);
         },
-        usage: "dss code-env list-logs <lang> <name>",
         description: "List the build log files DSS keeps for a code environment.",
         examples: ["dss code-env list-logs PYTHON my_env",],
     },
     "get-log": {
         handler: async (c, a, f) => {
-            const usage = "dss code-env get-log <lang> <name> <logName> [--max-lines N|--max-log-lines N] [--max-log-bytes N] [--output PATH]";
+            const usage = commandUsage("code-env", "get-log");
             requireArgs(a, 3, usage);
             const envLang = requireEnvLang(a[0], usage);
             const maxLines = numFlag(f, ["max-lines", "max-log-lines",]);
@@ -153,7 +150,6 @@ export const codeEnvCommands = {
             }
             return { ...result, envLang, envName: a[1], logName: a[2], };
         },
-        usage: "dss code-env get-log <lang> <name> <logName> [--max-lines N|--max-log-lines N] [--max-log-bytes N] [--output PATH]",
         description: "Fetch one code-env build log, bounded for safe output: the last --max-lines lines (default 500, 0 for all) and at most --max-log-bytes bytes (default 10 MiB, 0 for all). --output PATH writes the kept content to a file; stdout then carries the path metadata. A truncation warning names which cap hit.",
         examples: [
             "dss code-env get-log PYTHON my_env install.log --max-lines 200",
@@ -162,23 +158,22 @@ export const codeEnvCommands = {
     },
     version: {
         handler: (c, a) => {
-            const usage = "dss code-env version <lang> <name> <projectKey>";
+            const usage = commandUsage("code-env", "version");
             requireArgs(a, 3, usage);
             const envLang = requireEnvLang(a[0], usage);
             return c.codeEnvs.getVersionForProject(envLang, a[1], a[2]);
         },
-        usage: "dss code-env version <lang> <name> <projectKey>",
         description: "Resolve the code environment version a project uses (versioned automation environments); empty version for unversioned environments.",
         examples: ["dss code-env version PYTHON my_env MY_PROJ",],
     },
     create: {
         handler: async (c, a, f) => {
-            const usage = "dss code-env create <lang> <name> --deployment-mode MODE";
+            const usage = commandUsage("code-env", "create");
             requireArgs(a, 2, usage);
             const envLang = requireEnvLang(a[0], usage);
             const deploymentMode = f["deployment-mode"];
             if (!deploymentMode) {
-                throw new UsageError("--deployment-mode is required. Usage: dss code-env create <lang> <name> --deployment-mode MODE");
+                throw new UsageError(`--deployment-mode is required. Usage: ${commandUsage("code-env", "create")}`);
             }
             const params = codeEnvParams(f);
             const wait = codeEnvWait(f);
@@ -213,7 +208,6 @@ export const codeEnvCommands = {
             });
             return { created: a[1], resource: "code-env", envLang, ...created, };
         },
-        usage: "dss code-env create <lang> <name> --deployment-mode MODE [--params JSON|--data JSON|--data-file PATH|--stdin] [--python-interpreter PYTHON311] [--no-wait] [--if-not-exists] [--dry-run]",
         description: "Create a code environment; --no-wait hands back a DSS future payload you can settle with dss future wait.",
         examples: [
             "dss code-env create PYTHON my_env --deployment-mode DESIGN_MANAGED --python-interpreter PYTHON311",
@@ -222,12 +216,12 @@ export const codeEnvCommands = {
     },
     "set-definition": {
         handler: async (c, a, f) => {
-            const usage = "dss code-env set-definition <lang> <name> (--data JSON|--data-file PATH|--stdin) [--expect-hash SHA256]";
+            const usage = commandUsage("code-env", "set-definition");
             requireArgs(a, 2, usage);
             const envLang = requireEnvLang(a[0], usage);
             const definition = jsonInput(f);
             if (!definition) {
-                throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss code-env set-definition <lang> <name> --data JSON");
+                throw new UsageError(`--data, --data-file, or --stdin is required. Usage: ${commandUsage("code-env", "set-definition")}`);
             }
             const expectHash = validateExpectHash(f["expect-hash"]);
             const definitionHash = stableHash(definition);
@@ -253,7 +247,6 @@ export const codeEnvCommands = {
             }
             return c.codeEnvs.setDefinition(envLang, a[1], definition, { expectHash, });
         },
-        usage: "dss code-env set-definition <lang> <name> (--data JSON|--data-file PATH|--stdin) [--expect-hash SHA256] [--dry-run]",
         description: "Replace a code environment definition previously fetched from DSS (get-definition). --expect-hash SHA256 refuses the PUT unless the current definition still hashes to the hash captured with code-env get, so concurrent edits are never clobbered; --dry-run also fetches the current definition and reports both hashes plus a changed flag.",
         examples: [
             "dss code-env set-definition PYTHON my_env --data-file code-env.json --expect-hash $HASH --dry-run",
@@ -261,7 +254,7 @@ export const codeEnvCommands = {
     },
     "set-packages": {
         handler: async (c, a, f) => {
-            const usage = "dss code-env set-packages <lang> <name> (--packages PKGS|--package PKG|--file PATH)";
+            const usage = commandUsage("code-env", "set-packages");
             requireArgs(a, 2, usage);
             const envLang = requireEnvLang(a[0], usage);
             const packages = codeEnvPackageList(f);
@@ -281,7 +274,6 @@ export const codeEnvCommands = {
             }
             return c.codeEnvs.setPackages(envLang, a[1], packages, { installCorePackages, expectHash, });
         },
-        usage: "dss code-env set-packages <lang> <name> (--packages PKGS|--package PKG|--file PATH) [--install-core-packages true|false] [--expect-hash SHA256] [--dry-run]",
         description: "Fetch the current definition, merge the requested package specs (and --install-core-packages) into it, then PUT the merged definition, so fields outside the package list are never dropped; --expect-hash refuses the merge when DSS changed since the hash was captured. The package list is replaced wholesale, so an explicitly empty --packages value or an empty --file clears the requested packages.",
         examples: [
             "dss code-env set-packages PYTHON my_env --packages 'tabulate\\nnameparser' --dry-run",
@@ -290,7 +282,7 @@ export const codeEnvCommands = {
     },
     "update-packages": {
         handler: async (c, a, f) => {
-            const usage = "dss code-env update-packages <lang> <name>";
+            const usage = commandUsage("code-env", "update-packages");
             requireArgs(a, 2, usage);
             const envLang = requireEnvLang(a[0], usage);
             const wait = codeEnvWait(f);
@@ -316,13 +308,12 @@ export const codeEnvCommands = {
             }
             return c.codeEnvs.updatePackages(envLang, a[1], opts);
         },
-        usage: "dss code-env update-packages <lang> <name> [--force-rebuild] [--env-version VERSION] [--no-wait] [--dry-run]",
         description: "Rebuild or update code environment packages to match the requested specs; --no-wait hands back a DSS future payload you can settle with dss future wait.",
         examples: ["dss code-env update-packages PYTHON my_env --force-rebuild --dry-run",],
     },
     "update-images": {
         handler: async (c, a, f) => {
-            const usage = "dss code-env update-images <lang> <name>";
+            const usage = commandUsage("code-env", "update-images");
             requireArgs(a, 2, usage);
             const envLang = requireEnvLang(a[0], usage);
             const wait = codeEnvWait(f);
@@ -340,7 +331,6 @@ export const codeEnvCommands = {
             }
             return c.codeEnvs.updateImages(envLang, a[1], { envVersion, wait, });
         },
-        usage: "dss code-env update-images <lang> <name> [--env-version VERSION] [--no-wait] [--dry-run]",
         description: "Rebuild the Docker image(s) of a code environment to match its settings; --env-version targets one version of a versioned environment and --no-wait hands back a DSS future payload you can settle with dss future wait.",
         examples: [
             "dss code-env update-images PYTHON my_env --dry-run",
@@ -349,12 +339,12 @@ export const codeEnvCommands = {
     },
     "set-jupyter": {
         handler: async (c, a, f) => {
-            const usage = "dss code-env set-jupyter <lang> <name> --active true|false";
+            const usage = commandUsage("code-env", "set-jupyter");
             requireArgs(a, 2, usage);
             const envLang = requireEnvLang(a[0], usage);
             const active = parseBooleanOption(f["active"], "--active");
             if (active === undefined) {
-                throw new UsageError("--active is required. Usage: dss code-env set-jupyter <lang> <name> --active true|false");
+                throw new UsageError(`--active is required. Usage: ${commandUsage("code-env", "set-jupyter")}`);
             }
             const wait = codeEnvWait(f);
             if (executionMode(f).dryRun) {
@@ -370,13 +360,12 @@ export const codeEnvCommands = {
             }
             return c.codeEnvs.setJupyterSupport(envLang, a[1], active, { wait, });
         },
-        usage: "dss code-env set-jupyter <lang> <name> --active true|false [--no-wait] [--dry-run]",
         description: "Enable or disable Jupyter support for a code environment; --no-wait hands back a DSS future payload you can settle with dss future wait.",
         examples: ["dss code-env set-jupyter PYTHON my_env --active true --dry-run",],
     },
     delete: {
         handler: async (c, a, f) => {
-            const usage = "dss code-env delete <lang> <name>";
+            const usage = commandUsage("code-env", "delete");
             requireArgs(a, 2, usage);
             const envLang = requireEnvLang(a[0], usage);
             const wait = codeEnvWait(f);
@@ -404,7 +393,6 @@ export const codeEnvCommands = {
             }
             return c.codeEnvs.delete(envLang, a[1], { wait, });
         },
-        usage: "dss code-env delete <lang> <name> [--no-wait] [--if-exists] [--dry-run]",
         description: "Delete a code environment; --no-wait hands back a DSS future payload you can settle with dss future wait.",
         examples: ["dss code-env delete PYTHON my_env --dry-run",],
     },
@@ -414,10 +402,9 @@ export const codeEnvCommands = {
                 return c.codeEnvs.listUsages();
             if (a.length === 2)
                 return c.codeEnvs.listUsages(a[0], a[1]);
-            throw new UsageError("Usage: dss code-env usages [<lang> <name>]");
+            throw new UsageError(`Usage: ${commandUsage("code-env", "usages")}`);
         },
-        usage: "dss code-env usages [<lang> <name>]",
         description: "List code environment usages globally or for one environment.",
         examples: ["dss code-env usages", "dss code-env usages PYTHON my_env",],
     },
-};
+});

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

@@ -1,8 +1,9 @@
 import { readFileSync, } from "node:fs";
 import { num, readStdinText, stripUtf8Bom, } from "../coerce.js";
 import { enqueueCliWarning, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { UsageError, } from "../usage.js";
-const CODE_RUN_USAGE = "dss code run (--file PATH | --stdin) [--env ENV] [--timeout MS (default 120000)] [--keep] [--full-log] [--max-log-bytes N (default 1048576)] [--project-key KEY]";
+const CODE_RUN_USAGE = commandUsage("code", "run");
 function previewFlagValue(value) {
     const text = typeof value === "string" ? value : String(value);
     return text.length <= 32 ? text : `${text.slice(0, 32)}…`;
@@ -84,7 +85,7 @@ function unwrapCodeRunError(error) {
     }
     return error;
 }
-export const codeCommands = {
+export const codeCommands = withUsage("code", {
     run: {
         handler: async (c, a, f) => {
             const timeoutMs = parseCodeRunIntegerFlag(f["timeout"], "--timeout");
@@ -123,7 +124,6 @@ export const codeCommands = {
             }
             return result;
         },
-        usage: CODE_RUN_USAGE,
         description: "Run Python through a throwaway custom-python scenario and return captured output plus outcome. --timeout caps waiting; --max-log-bytes caps logs; --full-log returns the capped raw log. Exits 4 unless outcome is SUCCESS.",
         examples: [
             "dss code run --file inspect.py",
@@ -132,4 +132,4 @@ export const codeCommands = {
             "dss code run --file inspect.py --full-log",
         ],
     },
-};
+});

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

@@ -2,6 +2,7 @@ import { sanitizeErrorSecrets, sanitizeSecrets, } from "../../utils/secret-sanit
 import { requiredJsonInput, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { readIfExists, skipResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
 /**
  * Keys of a connection payload that carry credentials. CLI plan/error/output
@@ -76,12 +77,11 @@ function requireConnectionName(value, usage) {
     }
     return trimmed;
 }
-export const connectionCommands = {
+export const connectionCommands = withUsage("connection", {
     list: {
         handler: (c, _a, f) => c.connections.list({
             type: f["type"],
         }),
-        usage: "dss connection list [--type TYPE]",
         description: "List all connection names, optionally filtered by connection type.",
         examples: ["dss connection list", "dss connection list --type Filesystem",],
     },
@@ -90,24 +90,22 @@ export const connectionCommands = {
             mode: f["mode"],
             projectKey: f["project-key"],
         }),
-        usage: "dss connection infer [--mode fast|rich] [--project-key KEY]",
         description: "List connections with inferred types and metadata.",
         examples: ["dss connection infer", "dss connection infer --mode rich",],
     },
     get: {
         handler: async (c, a) => {
-            const usage = "dss connection get <name>";
+            const usage = commandUsage("connection", "get");
             requireArgs(a, 1, usage);
             const details = await c.connections.adminGet(requireConnectionName(a[0], usage));
             return sanitizeConnectionSecrets(details);
         },
-        usage: "dss connection get <name>",
         description: "Get a connection by name (admin). Credential-bearing params (e.g. params.password) are redacted in output.",
         examples: ["dss connection get postgres",],
     },
     create: {
         handler: async (c, _a, f) => {
-            const usage = "dss connection create (--data JSON|--data-file PATH|--stdin)";
+            const usage = commandUsage("connection", "create");
             const body = requiredConnectionJson(f, usage);
             if (executionMode(f).dryRun) {
                 return {
@@ -127,7 +125,6 @@ export const connectionCommands = {
                 throw sanitizeConnectionError(error, connectionSecretsFromBody(body));
             }
         },
-        usage: "dss connection create (--data JSON|--data-file PATH|--stdin) [--dry-run]",
         description: 'Create a connection (admin). Body is the Connection definition, e.g. {"name":"new-connection","type":"PostgreSQL","params":{"host":"...","user":"...","password":"..."}}. Secrets are never echoed in errors or output.',
         examples: [
             `dss connection create --data '{"name":"new-connection","type":"PostgreSQL","params":{"db":"dbname","user":"myuser","password":"s3cret"}}'`,
@@ -135,7 +132,7 @@ export const connectionCommands = {
     },
     update: {
         handler: async (c, a, f) => {
-            const usage = "dss connection update <name> (--data JSON|--data-file PATH|--stdin) [--dry-run]";
+            const usage = commandUsage("connection", "update");
             requireArgs(a, 1, usage);
             const name = requireConnectionName(a[0], usage);
             const body = requiredConnectionJson(f, usage);
@@ -160,7 +157,6 @@ export const connectionCommands = {
                 throw sanitizeConnectionError(error, secrets);
             }
         },
-        usage: "dss connection update <name> (--data JSON|--data-file PATH|--stdin) [--dry-run]",
         description: "Update a connection (admin). The body MUST be the Connection object obtained from `dss connection get` (PUT semantics); type and name cannot be modified. Use --dry-run to preview the merged result without writing.",
         examples: [
             `dss connection update postgres --data '{"type":"PostgreSQL","name":"postgres","allowWrite":true,"params":{"db":"dbname","user":"myuser","password":"s3cret"}}'`,
@@ -168,7 +164,7 @@ export const connectionCommands = {
     },
     delete: {
         handler: async (c, a, f) => {
-            const usage = "dss connection delete <name> [--if-exists] [--dry-run]";
+            const usage = commandUsage("connection", "delete");
             requireArgs(a, 1, usage);
             const name = requireConnectionName(a[0], usage);
             if (executionMode(f).dryRun) {
@@ -191,18 +187,16 @@ export const connectionCommands = {
             }
             return c.connections.adminDelete(name);
         },
-        usage: "dss connection delete <name> [--if-exists] [--dry-run]",
         description: "Delete a connection (admin). Destructive: per the DSS docs no check is performed that the connection is not in use by a dataset.",
         examples: ["dss connection delete old-conn", "dss connection delete old-conn --if-exists",],
     },
     test: {
         handler: async (c, a) => {
-            const usage = "dss connection test <name>";
+            const usage = commandUsage("connection", "test");
             requireArgs(a, 1, usage);
             const result = await c.connections.adminTest(requireConnectionName(a[0], usage));
             return sanitizeConnectionSecrets(result);
         },
-        usage: "dss connection test <name>",
         description: "Test whether a connection is available (uses the same GET /connections/{name}/test route as the official Python client; returns connectionOK, errors when testing is unsupported for the type). Credential-bearing fields are redacted in output.",
         examples: ["dss connection test postgres",],
     },
@@ -210,14 +204,13 @@ export const connectionCommands = {
         handler: (c, _a, f) => {
             const connection = f["connection"];
             if (!connection) {
-                throw new UsageError("--connection is required. Usage: dss connection schemas --connection CONN");
+                throw new UsageError(`--connection is required. Usage: ${commandUsage("connection", "schemas")}`);
             }
             return c.connections.schemas({
                 connection,
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss connection schemas --connection CONN [--project-key KEY]",
         description: "List schemas in a SQL connection.",
         examples: ["dss connection schemas --connection ATHENA_CONN --project-key MYPROJ",],
     },
@@ -225,7 +218,7 @@ export const connectionCommands = {
         handler: (c, _a, f) => {
             const connection = f["connection"];
             if (!connection) {
-                throw new UsageError("--connection is required. Usage: dss connection tables --connection CONN");
+                throw new UsageError(`--connection is required. Usage: ${commandUsage("connection", "tables")}`);
             }
             return c.connections.tables({
                 connection,
@@ -234,7 +227,6 @@ export const connectionCommands = {
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss connection tables --connection CONN [--catalog CATALOG] [--schema SCHEMA] [--project-key KEY]",
         description: "List importable tables in a SQL connection, optionally scoped by catalog and schema.",
         examples: [
             "dss connection tables --connection ATHENA_CONN --schema analytics --project-key MYPROJ",
@@ -242,7 +234,7 @@ export const connectionCommands = {
     },
     "prepare-import": {
         handler: async (c, _a, f) => {
-            const usage = "dss connection prepare-import (--data JSON|--data-file PATH|--stdin) [--project-key KEY]";
+            const usage = commandUsage("connection", "prepare-import");
             const body = requiredJsonInput(f, `--data, --data-file, or --stdin is required (tables-import request). Usage: ${usage}`);
             const keys = body["keys"];
             if (!Array.isArray(keys) || keys.length === 0) {
@@ -273,7 +265,6 @@ export const connectionCommands = {
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss connection prepare-import (--data JSON|--data-file PATH|--stdin) [--project-key KEY] [--dry-run]",
         description: 'Prepare the import of selected SQL or Hive tables (WRITE_CONF). Body is {"keys":[...]} per the DSS tables-import docs. Returns a DSS future; poll with `dss future wait <jobId>`.',
         examples: [
             `dss connection prepare-import --data '{"keys":[{"connectionName":"postgres","name":"my_table"}]}' --project-key MYPROJ`,
@@ -281,7 +272,7 @@ export const connectionCommands = {
     },
     "execute-import": {
         handler: async (c, _a, f) => {
-            const usage = "dss connection execute-import (--data JSON|--data-file PATH|--stdin) [--project-key KEY]";
+            const usage = commandUsage("connection", "execute-import");
             const body = requiredJsonInput(f, `--data, --data-file, or --stdin is required (tables-import request). Usage: ${usage}`);
             const sql = body["sqlImportCandidates"];
             const hive = body["hiveImportCandidates"];
@@ -311,10 +302,9 @@ export const connectionCommands = {
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss connection execute-import (--data JSON|--data-file PATH|--stdin) [--project-key KEY] [--dry-run]",
         description: "Perform an import from SQL/Hive table candidates (WRITE_CONF). Body carries sqlImportCandidates and/or hiveImportCandidates per the DSS tables-import docs. Returns a DSS future.",
         examples: [
             `dss connection execute-import --data '{"sqlImportCandidates":[{"connectionName":"pgsql","table":"my_table","checked":false,"datasetName":"imported_from_db","existingDatasetsNames":[]}]}' --project-key MYPROJ`,
         ],
     },
-};
+});

package/dist/src/cli/commands/continuous-activity.js

@@ -1,38 +1,35 @@
 import { jsonInput, } from "../coerce.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, } from "../usage.js";
-export const continuousActivityCommands = {
+export const continuousActivityCommands = withUsage("continuous-activity", {
     list: {
         handler: (c, _a, f) => c.continuousActivities.list(f["project-key"]),
-        usage: "dss continuous-activity list [--project-key KEY]",
         description: "List continuous activities in a project.",
         examples: ["dss continuous-activity list",],
     },
     status: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss continuous-activity status <recipeId> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("continuous-activity", "status"));
             return c.continuousActivities.getStatus(a[0], f["project-key"]);
         },
-        usage: "dss continuous-activity status <recipeId> [--project-key KEY]",
         description: "Get a continuous recipe's desired and effective state.",
         examples: ["dss continuous-activity status compute_stream",],
     },
     start: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss continuous-activity start <recipeId> [--data JSON|--data-file PATH|--stdin] [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("continuous-activity", "start"));
             return c.continuousActivities.start(a[0], jsonInput(f), f["project-key"]);
         },
-        usage: "dss continuous-activity start <recipeId> [--data JSON|--data-file PATH|--stdin] [--project-key KEY]",
         description: "Start a continuous recipe (optional loop restart params via JSON).",
         examples: ["dss continuous-activity start compute_stream",],
     },
     stop: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss continuous-activity stop <recipeId> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("continuous-activity", "stop"));
             await c.continuousActivities.stop(a[0], f["project-key"]);
             return { stopped: a[0], };
         },
-        usage: "dss continuous-activity stop <recipeId> [--project-key KEY]",
         description: "Stop a continuous recipe.",
         examples: ["dss continuous-activity stop compute_stream",],
     },
-};
+});

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

@@ -4,26 +4,25 @@ import { deepMerge, } from "../../utils/deep-merge.js";
 import { jsonInput, parseBooleanOption, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { readIfExists, skipResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
-export const dashboardCommands = {
+export const dashboardCommands = withUsage("dashboard", {
     list: {
         handler: (c, _a, f) => c.dashboards.list(f["project-key"]),
-        usage: "dss dashboard list [--project-key KEY]",
         description: "List project dashboards.",
         examples: ["dss dashboard list",],
     },
     get: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss dashboard get <id>");
+            requireArgs(a, 1, commandUsage("dashboard", "get"));
             return c.dashboards.get(a[0], f["project-key"]);
         },
-        usage: "dss dashboard get <id> [--project-key KEY]",
         description: "Get dashboard definition.",
         examples: ["dss dashboard get DASHBOARD_ID",],
     },
     export: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss dashboard export <id> --output PATH [--paper-size SIZE] [--orientation PORTRAIT|LANDSCAPE] [--file-type PDF] [--slide-index N] [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("dashboard", "export"));
             const outputPath = f["output"];
             if (typeof outputPath !== "string" || !outputPath.trim()) {
                 throw new UsageError("--output PATH is required.", "missing_required_flag");
@@ -86,7 +85,6 @@ export const dashboardCommands = {
                 slideIndex,
             };
         },
-        usage: "dss dashboard export <id> --output PATH [--paper-size SIZE] [--orientation PORTRAIT|LANDSCAPE] [--file-type PDF] [--slide-index N] [--project-key KEY]",
         description: "Render a dashboard page as PDF. Requires DSS graphics export to be configured.",
         examples: [
             "dss dashboard export DASHBOARD_ID --output dashboard.pdf",
@@ -101,7 +99,7 @@ export const dashboardCommands = {
             const name = flagName ?? (typeof settingsName === "string" ? settingsName : undefined);
             const listed = parseBooleanOption(f["listed"], "--listed");
             if (!name) {
-                throw new UsageError("--name or dashboard settings containing a string name are required. Usage: dss dashboard create --name NAME");
+                throw new UsageError(`--name or dashboard settings containing a string name are required. Usage: ${commandUsage("dashboard", "create")}`);
             }
             const payload = { ...(settings ?? { pages: [], }), name, };
             if (listed !== undefined)
@@ -131,7 +129,6 @@ export const dashboardCommands = {
             });
             return { created: created.id, resource: "dashboard", ...created, };
         },
-        usage: "dss dashboard create (--name NAME|--data JSON|--data-file PATH|--stdin) [--listed true|false] [--if-not-exists] [--dry-run] [--project-key KEY]",
         description: "Create a dashboard from raw settings or minimal name/listed fields. Defaults to an empty pages array.",
         examples: [
             "dss dashboard create --name 'Agent dashboard' --listed true --dry-run",
@@ -140,7 +137,7 @@ export const dashboardCommands = {
     },
     update: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss dashboard update <id> [--name NAME|--listed true|false|--data JSON]");
+            requireArgs(a, 1, commandUsage("dashboard", "update"));
             const name = f["name"];
             const listed = parseBooleanOption(f["listed"], "--listed");
             const data = jsonInput(f);
@@ -163,13 +160,12 @@ export const dashboardCommands = {
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss dashboard update <id> (--name NAME|--listed true|false|--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
         description: "Update dashboard settings via merge.",
         examples: ["dss dashboard update DASHBOARD_ID --listed true --dry-run",],
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss dashboard delete <id>");
+            requireArgs(a, 1, commandUsage("dashboard", "delete"));
             const pk = f["project-key"];
             if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.dashboards.get(a[0], pk));
@@ -182,8 +178,7 @@ export const dashboardCommands = {
             await c.dashboards.delete(a[0], pk);
             return { deleted: a[0], resource: "dashboard", };
         },
-        usage: "dss dashboard delete <id> [--if-exists] [--dry-run] [--project-key KEY]",
         description: "Delete a dashboard.",
         examples: ["dss dashboard delete DASHBOARD_ID --dry-run",],
     },
-};
+});