dataiku-sdk 3.3.0 → 3.5.0

package/dist/src/cli/doctor.js

@@ -29,6 +29,7 @@ export function firstStringField(items, fields) {
     return null;
 }
 export function integrationFlag(name) {
+    // oxlint-disable-next-line dss/no-direct-process-env -- RUN_DATAIKU_* integration opt-in flags
     const value = process.env[name];
     return value === "1" || value?.toLowerCase() === "true";
 }

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

@@ -8,4 +8,6 @@ export type EnvFileProvenance = "project" | "install";
  */
 export declare function envFileProvenance(name: string): EnvFileProvenance | undefined;
 export declare function dataikuEnvironmentEnabled(): boolean;
+/** DATAIKU_PROJECT_KEY from the environment, unless `DATAIKU_DISABLE_ENV=1`. */
+export declare function ambientProjectKey(): string | undefined;
 export declare function loadEnvFile(): void;

package/dist/src/cli/env.js

@@ -20,6 +20,20 @@ export function envFileProvenance(name) {
 export function dataikuEnvironmentEnabled() {
     return process.env.DATAIKU_DISABLE_ENV !== "1";
 }
+/** DATAIKU_PROJECT_KEY from the environment, unless `DATAIKU_DISABLE_ENV=1`. */
+export function ambientProjectKey() {
+    return dataikuEnvironmentEnabled() ? process.env.DATAIKU_PROJECT_KEY : undefined;
+}
+const allowedEnvKeys = new Set(["NODE_EXTRA_CA_CERTS", "NODE_TLS_REJECT_UNAUTHORIZED",]);
+/**
+ * `.env` files are untrusted input: only the CLI's own `DATAIKU_*` variables and
+ * Node's TLS trust knobs are read. Every other key is ignored silently, so a
+ * project working tree cannot redirect the CLI (for example by smuggling in
+ * `DSS_CONFIG_DIR` and sending saved credentials elsewhere).
+ */
+function isAllowedEnvKey(key) {
+    return key.startsWith("DATAIKU_") || allowedEnvKeys.has(key);
+}
 export function loadEnvFile() {
     if (!dataikuEnvironmentEnabled())
         return;
@@ -42,7 +56,7 @@ export function loadEnvFile() {
                     continue;
                 const key = trimmed.slice(0, eq).trim();
                 const val = trimmed.slice(eq + 1).trim().replace(/^['"]|['"]$/g, "");
-                if (!process.env[key]) {
+                if (isAllowedEnvKey(key) && !process.env[key]) {
                     process.env[key] = val;
                     (index === 0 ? projectEnvVars : installEnvVars).add(key);
                 }

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

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { ClientValidationError, } from "../../errors.js";
 import { canonicalDssUrl, } from "../../utils/dss-url.js";
 import { compareStrings, } from "../../utils/stable-hash.js";
 import { parseJsonObject, plainRecord, stableHash, stableJson, } from "../coerce.js";
@@ -61,7 +62,7 @@ function writeAllSync(fd, payload) {
     while (offset < payload.length) {
         const written = fs.writeSync(fd, payload, offset, payload.length - offset, offset);
         if (written <= 0) {
-            throw new Error(`Stalled writing app permissions snapshot at byte ${offset}.`);
+            throw new ClientValidationError(`Stalled writing app permissions snapshot at byte ${offset}.`, "internal_error");
         }
         offset += written;
     }

package/dist/src/cli/helpers/flow-zone.js

@@ -1,6 +1,7 @@
 import { readFileSync, } from "node:fs";
 import { compareStrings, } from "../../utils/stable-hash.js";
 import { finiteNumberField, jsonInput, optionalStringField, parseJsonObject, plainRecord, requiredStringArray, splitCsvFlag, } from "../coerce.js";
+import { commandUsage, } from "../syntax.js";
 import { UsageError, } from "../usage.js";
 export function flowZoneId(value) {
     const trimmed = value.trim();
@@ -10,7 +11,7 @@ export function flowZoneId(value) {
 }
 export function flowZoneName(value) {
     if (typeof value !== "string" || value.trim().length === 0) {
-        throw new UsageError("--name is required. Usage: dss flow-zone create --name NAME [--color #RRGGBB]");
+        throw new UsageError(`--name is required. Usage: ${commandUsage("flow-zone", "create")}`);
     }
     return value.trim();
 }

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

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import { tmpdir, } from "node:os";
 import { join, parse as parsePath, relative as relativePath, resolve as resolvePath, sep, } from "node:path";
+import { ClientValidationError, } from "../../errors.js";
 import { sanitizeFileName, } from "../../utils/sanitize.js";
 import { normalizeLineEndings, sha256Hex, stableHash, } from "../coerce.js";
 import { UsageError, } from "../usage.js";
@@ -126,7 +127,7 @@ function writeAllSync(fd, payload) {
     while (offset < payload.length) {
         const written = fs.writeSync(fd, payload, offset, payload.length - offset, offset);
         if (written <= 0) {
-            throw new Error(`Stalled writing recipe backup at byte ${offset}.`);
+            throw new ClientValidationError(`Stalled writing recipe backup at byte ${offset}.`, "internal_error");
         }
         offset += written;
     }

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

@@ -0,0 +1,24 @@
+/**
+ * Canonical discovery output schemas, keyed by `resource.action`.
+ *
+ * TypeBox definitions from `packages/types` plus the inline literal schemas
+ * that exist only on the CLI side (code-env log envelope, code.run outcome,
+ * project-library payloads, notebook saves, sql.query handoff envelope).
+ * `scripts/generate-action-output-schemas.mjs` serializes this map into
+ * `src/generated/action-output-schemas.json`; discovery (src/cli/contract.ts)
+ * reads that generated JSON as plain data, so the TypeBox schema graph never
+ * loads on the discovery path. SDK validation keeps using the TypeBox schema
+ * objects from `packages/types` directly.
+ *
+ * Imported by the generator and the discovery parity test only.
+ */
+/**
+ * Canonical TypeBox-derived output schemas, keyed by `resource.action`. This is
+ * the single source of truth for `src/generated/action-output-schemas.json`,
+ * which discovery reads as plain data so no TypeBox schema graph loads on the
+ * discovery path. Regenerate with
+ * `bun scripts/generate-action-output-schemas.mjs`; `bun run check` fails when
+ * the generated file is stale. SDK validation keeps using the TypeBox schema
+ * objects from `packages/types` directly and never depends on the generated file.
+ */
+export declare function typeBoxCommandOutputSchemas(): Record<string, Record<string, unknown>>;

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

@@ -0,0 +1,233 @@
+/**
+ * Canonical discovery output schemas, keyed by `resource.action`.
+ *
+ * TypeBox definitions from `packages/types` plus the inline literal schemas
+ * that exist only on the CLI side (code-env log envelope, code.run outcome,
+ * project-library payloads, notebook saves, sql.query handoff envelope).
+ * `scripts/generate-action-output-schemas.mjs` serializes this map into
+ * `src/generated/action-output-schemas.json`; discovery (src/cli/contract.ts)
+ * reads that generated JSON as plain data, so the TypeBox schema graph never
+ * loads on the discovery path. SDK validation keeps using the TypeBox schema
+ * objects from `packages/types` directly.
+ *
+ * Imported by the generator and the discovery parity test only.
+ */
+const PROJECT_LIBRARY_ITEM_OUTPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["name",],
+    properties: {
+        name: { type: "string", },
+        path: { type: "string", },
+        size: { type: "integer", minimum: 0, },
+        mimeType: { type: "string", },
+        hasData: { type: "boolean", },
+        lastModified: { type: "number", },
+        children: { type: "array", items: { type: "object", additionalProperties: true, }, },
+    },
+};
+const NOTEBOOK_SAVE_OUTPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["saved", "resource", "created", "hash",],
+    properties: {
+        saved: { type: "string", },
+        resource: { enum: ["jupyter-notebook", "sql-notebook",], },
+        created: { type: "boolean", },
+        hash: { type: "string", pattern: "^[a-f0-9]{64}$", },
+    },
+};
+/**
+ * `notebook.save-sql` adds `requested`: on create DSS allocates the persisted
+ * id (`saved`), while the requested handle only becomes the display name.
+ */
+const NOTEBOOK_SAVE_SQL_OUTPUT_SCHEMA = {
+    ...NOTEBOOK_SAVE_OUTPUT_SCHEMA,
+    required: ["saved", "requested", "resource", "created", "hash",],
+    properties: {
+        ...NOTEBOOK_SAVE_OUTPUT_SCHEMA["properties"],
+        requested: { type: "string", },
+    },
+};
+let commandOutputSchemas;
+/**
+ * Canonical TypeBox-derived output schemas, keyed by `resource.action`. This is
+ * the single source of truth for `src/generated/action-output-schemas.json`,
+ * which discovery reads as plain data so no TypeBox schema graph loads on the
+ * discovery path. Regenerate with
+ * `bun scripts/generate-action-output-schemas.mjs`; `bun run check` fails when
+ * the generated file is stale. SDK validation keeps using the TypeBox schema
+ * objects from `packages/types` directly and never depends on the generated file.
+ */
+export function typeBoxCommandOutputSchemas() {
+    if (commandOutputSchemas)
+        return commandOutputSchemas;
+    const { CodeEnvDetailsSchema, CodeEnvLogSummaryArraySchema, CodeEnvSummaryArraySchema, CodeEnvUsageArraySchema, CodeEnvVersionForProjectSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, FlowZoneArraySchema, FlowZoneSchema, JobSummaryArraySchema, JobWaitResultSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, NotebookSessionArraySchema, ProjectDetailsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, RecipeSummaryArraySchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioSummaryArraySchema, SqlNotebookContentSchema, SqlNotebookHistorySchema, SqlNotebookSummaryArraySchema, SqlQueryResponseSchema, } = require("../schemas.js");
+    return commandOutputSchemas = {
+        "code-env.list": CodeEnvSummaryArraySchema,
+        "code-env.get": CodeEnvDetailsSchema,
+        "code-env.list-logs": CodeEnvLogSummaryArraySchema,
+        "code-env.get-log": {
+            oneOf: [
+                {
+                    type: "object",
+                    required: ["log", "bytes", "truncated", "tailed", "envLang", "envName", "logName",],
+                    properties: {
+                        log: { type: "string", },
+                        bytes: { type: "integer", minimum: 0, },
+                        truncated: { type: "boolean", },
+                        tailed: { type: "boolean", },
+                        envLang: { enum: ["PYTHON", "R",], },
+                        envName: { type: "string", },
+                        logName: { type: "string", },
+                    },
+                },
+                {
+                    type: "object",
+                    required: ["path", "bytes", "truncated", "tailed", "envLang", "envName", "logName",],
+                    properties: {
+                        path: { type: "string", },
+                        bytes: { type: "integer", minimum: 0, },
+                        truncated: { type: "boolean", },
+                        tailed: { type: "boolean", },
+                        envLang: { enum: ["PYTHON", "R",], },
+                        envName: { type: "string", },
+                        logName: { type: "string", },
+                    },
+                },
+            ],
+        },
+        "code-env.version": CodeEnvVersionForProjectSchema,
+        "code-env.usages": CodeEnvUsageArraySchema,
+        "code.run": {
+            type: "object",
+            additionalProperties: false,
+            required: [
+                "outcome",
+                "success",
+                "runId",
+                "elapsedMs",
+                "pollCount",
+                "output",
+                "logTruncated",
+                "maxLogBytes",
+                "cleanup",
+            ],
+            properties: {
+                outcome: { type: "string", },
+                success: { type: "boolean", },
+                runId: { type: "string", },
+                elapsedMs: { type: "number", minimum: 0, },
+                pollCount: { type: "integer", minimum: 0, },
+                output: { type: "string", },
+                log: { type: "string", },
+                logTruncated: { type: "boolean", },
+                maxLogBytes: { type: "integer", minimum: 0, },
+                timedOut: { const: true, },
+                timeoutMs: { type: "integer", minimum: 0, },
+                cleanup: {
+                    type: "object",
+                    additionalProperties: false,
+                    required: ["status",],
+                    properties: {
+                        status: { enum: ["deleted", "kept", "failed",], },
+                        error: { type: "string", },
+                    },
+                },
+            },
+        },
+        "notebook.list-jupyter": JupyterNotebookSummaryArraySchema,
+        "notebook.get-jupyter": JupyterNotebookContentSchema,
+        "notebook.sessions-jupyter": NotebookSessionArraySchema,
+        "notebook.list-sql": SqlNotebookSummaryArraySchema,
+        "notebook.get-sql": SqlNotebookContentSchema,
+        "notebook.history-sql": SqlNotebookHistorySchema,
+        "notebook.save-jupyter": NOTEBOOK_SAVE_OUTPUT_SCHEMA,
+        "notebook.save-sql": NOTEBOOK_SAVE_SQL_OUTPUT_SCHEMA,
+        "project-library.list": { type: "array", items: PROJECT_LIBRARY_ITEM_OUTPUT_SCHEMA, },
+        "project-library.get-bytes": {
+            type: "object",
+            additionalProperties: false,
+            required: ["path", "bytes", "sha256",],
+            properties: {
+                path: { type: "string", },
+                bytes: { type: "integer", minimum: 0, },
+                sha256: { type: "string", pattern: "^[a-f0-9]{64}$", },
+            },
+        },
+        "project-library.put": {
+            type: "object",
+            additionalProperties: false,
+            required: ["updated", "bytes", "sha256",],
+            properties: {
+                updated: { type: "string", },
+                bytes: { type: "integer", minimum: 0, },
+                sha256: { type: "string", pattern: "^[a-f0-9]{64}$", },
+                beforeSha256: { type: "string", pattern: "^[a-f0-9]{64}$", },
+            },
+        },
+        "project-library.diff": {
+            type: "object",
+            additionalProperties: false,
+            required: [
+                "path",
+                "unchanged",
+                "added",
+                "removed",
+                "diff",
+                "diffTruncated",
+                "localSha256",
+                "localBytes",
+                "maxLines",
+            ],
+            properties: {
+                path: { type: "string", },
+                unchanged: { type: "boolean", },
+                added: { type: "integer", minimum: 0, },
+                removed: { type: "integer", minimum: 0, },
+                diff: { type: "string", },
+                diffTruncated: { type: "boolean", },
+                binary: { type: "boolean", },
+                remoteAbsent: { type: "boolean", },
+                remoteSha256: { type: "string", pattern: "^[a-f0-9]{64}$", },
+                remoteBytes: { type: "integer", minimum: 0, },
+                localSha256: { type: "string", pattern: "^[a-f0-9]{64}$", },
+                localBytes: { type: "integer", minimum: 0, },
+                maxLines: { type: "integer", minimum: 0, },
+            },
+        },
+        "project.list": ProjectSummaryArraySchema,
+        "project.get": ProjectDetailsSchema,
+        "project.metadata": ProjectMetadataSchema,
+        "dataset.list": DatasetSummaryArraySchema,
+        "dataset.get": DatasetDetailsSchema,
+        "dataset.schema": DatasetSchemaSchema,
+        "recipe.list": RecipeSummaryArraySchema,
+        "job.list": JobSummaryArraySchema,
+        "job.wait": JobWaitResultSchema,
+        "job.monitor": JobWaitResultSchema,
+        "scenario.list": ScenarioSummaryArraySchema,
+        "scenario.get": ScenarioDetailsSchema,
+        "scenario.status": ScenarioStatusSchema,
+        "flow-zone.list": FlowZoneArraySchema,
+        "flow-zone.get": FlowZoneSchema,
+        "sql.query": {
+            anyOf: [
+                SqlQueryResponseSchema,
+                {
+                    type: "object",
+                    required: ["queryId", "rowCount", "preview",],
+                    additionalProperties: true,
+                    properties: {
+                        queryId: { type: "string", },
+                        rowCount: { type: "number", },
+                        preview: { type: "array", items: true, },
+                        truncated: { type: "boolean", },
+                        outputPath: { type: "string", },
+                        written: { type: "string", },
+                    },
+                },
+            ],
+        },
+    };
+}

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

@@ -0,0 +1,83 @@
+import type { CommandDefinition, CommandFlagChoice, CommandMeta } from "./types.js";
+/**
+ * One element of a command's usage line. `src/cli/command-syntax.json` holds an
+ * ordered node list per command; it is the source of truth for the usage text
+ * (rendered by {@link commandUsage}) and for every usage-level contract field
+ * (derived by {@link commandSyntax}).
+ */
+export type SyntaxNode = 
+/** Literal word: `dss`, the resource, the action. */
+string
+/** Positional argument, rendered `<name>` (or bare `name` when `bare`). */
+ | {
+    arg: string;
+    bare?: boolean;
+}
+/** Flag, rendered `--flag`, `--flag VALUE`, or `--flag a|b` (enum), plus an optional trailing note. */
+ | {
+    flag: string;
+    value?: string;
+    values?: string[];
+    note?: string;
+}
+/** Optional group `[a|b]`; each alternative is a node sequence. */
+ | {
+    optional: SyntaxNode[][];
+    sep?: string;
+}
+/** Required choice `(a|b)`; each alternative is a node sequence. */
+ | {
+    oneOf: SyntaxNode[][];
+    sep?: string;
+};
+export type FlagNode = Extract<SyntaxNode, {
+    flag: string;
+}>;
+export interface CommandPositionalMetadata {
+    name: string;
+    required: boolean;
+}
+/** Input channels a command accepts for its JSON payload. */
+export interface CommandInputContract {
+    stdin?: boolean;
+    dataFlag?: boolean;
+    dataFileFlag?: boolean;
+}
+/** Usage-level contract fields derived from a command's syntax tree. */
+export interface CommandSyntax {
+    /** Canonical names of the flags the usage line lists, in order. */
+    flags: string[];
+    requiredFlags: string[];
+    requiredOneOf: CommandFlagChoice[];
+    valueHints: Record<string, {
+        valueType: string;
+        enumValues?: string[];
+    }>;
+    inputContract: CommandInputContract;
+    positionalArguments: CommandPositionalMetadata[];
+    /** Alias spellings (canonical name -> raw names) the usage line uses. */
+    aliases: Record<string, string[]>;
+    dryRun: boolean;
+    producesLocalFile: boolean;
+}
+/** The syntax tree for `resource.action`, or undefined when no such command exists. */
+export declare function commandSyntaxTree(resource: string, action: string): SyntaxNode[] | undefined;
+export declare function commandSyntaxKeys(): string[];
+/** Render a node sequence as usage text; `omitOptional` drops every `[...]` group. */
+export declare function renderNodes(nodes: SyntaxNode[], omitOptional?: boolean): string;
+/** The human usage line for `resource.action`, rendered from its syntax tree. */
+export declare function commandUsage(resource: string, action: string): string;
+/**
+ * Attach each action's usage line, rendered from its syntax tree. Every command
+ * module exports its definitions through this, so a command without a syntax
+ * entry fails at load instead of shipping an undocumented contract.
+ */
+export declare function withUsage(resource: string, definitions: Record<string, CommandDefinition>): Record<string, CommandMeta>;
+/** Whether the syntax lists `--name` (the raw spelling, not an alias). */
+export declare function syntaxHasFlag(nodes: SyntaxNode[], name: string): boolean;
+/** Leading literal words after `dss` (resource and, when present, action). */
+export declare function syntaxCommandWords(nodes: SyntaxNode[]): string[];
+/** Usage-level contract fields of a syntax tree (flags, requirements, value hints, positionals, inputs). */
+export declare function deriveSyntax(nodes: SyntaxNode[]): CommandSyntax;
+/** Usage-level contract fields for `resource.action`, derived from its syntax tree. */
+export declare function commandSyntax(resource: string, action: string): CommandSyntax;

package/dist/src/cli/syntax.js

@@ -0,0 +1,217 @@
+import { ClientValidationError, } from "../errors.js";
+import commandSyntaxSource from "./command-syntax.json" with { type: "json" };
+import { FLAG_ALIASES, KNOWN_LONG_FLAGS, } from "./flags.js";
+const SOURCE = commandSyntaxSource.commands;
+/** The syntax tree for `resource.action`, or undefined when no such command exists. */
+export function commandSyntaxTree(resource, action) {
+    return Object.hasOwn(SOURCE, `${resource}.${action}`)
+        ? SOURCE[`${resource}.${action}`]
+        : undefined;
+}
+function requiredSyntaxTree(resource, action) {
+    const nodes = commandSyntaxTree(resource, action);
+    if (!nodes) {
+        throw new ClientValidationError(`No syntax for ${resource} ${action} in src/cli/command-syntax.json.`, "internal_error");
+    }
+    return nodes;
+}
+export function commandSyntaxKeys() {
+    return Object.keys(SOURCE);
+}
+function renderNode(node, omitOptional) {
+    if (typeof node === "string")
+        return node;
+    if ("arg" in node)
+        return node.bare ? node.arg : `<${node.arg}>`;
+    if ("flag" in node) {
+        const value = node.values ? node.values.join("|") : node.value;
+        return `--${node.flag}${value === undefined ? "" : ` ${value}`}${node.note ? ` ${node.note}` : ""}`;
+    }
+    if ("optional" in node) {
+        return omitOptional ? "" : `[${renderAlternatives(node.optional, node.sep, omitOptional)}]`;
+    }
+    return `(${renderAlternatives(node.oneOf, node.sep, omitOptional)})`;
+}
+function renderAlternatives(alternatives, sep, omitOptional) {
+    return alternatives.map((alternative) => renderNodes(alternative, omitOptional)).join(sep ?? "|");
+}
+/** Render a node sequence as usage text; `omitOptional` drops every `[...]` group. */
+export function renderNodes(nodes, omitOptional = false) {
+    return nodes.map((node) => renderNode(node, omitOptional)).filter((part) => part !== "").join(" ");
+}
+const usageCache = new Map();
+/** The human usage line for `resource.action`, rendered from its syntax tree. */
+export function commandUsage(resource, action) {
+    const key = `${resource}.${action}`;
+    let usage = usageCache.get(key);
+    if (usage === undefined) {
+        usage = renderNodes(requiredSyntaxTree(resource, action));
+        usageCache.set(key, usage);
+    }
+    return usage;
+}
+/**
+ * Attach each action's usage line, rendered from its syntax tree. Every command
+ * module exports its definitions through this, so a command without a syntax
+ * entry fails at load instead of shipping an undocumented contract.
+ */
+export function withUsage(resource, definitions) {
+    const commands = {};
+    for (const [action, definition,] of Object.entries(definitions)) {
+        commands[action] = { ...definition, usage: commandUsage(resource, action), };
+    }
+    return commands;
+}
+function walk(nodes, visit, context = {
+    optional: false,
+    oneOf: undefined,
+}) {
+    for (const node of nodes) {
+        if (typeof node === "string")
+            continue;
+        visit(node, context);
+        if ("optional" in node) {
+            for (const alternative of node.optional) {
+                walk(alternative, visit, { ...context, optional: true, });
+            }
+        }
+        else if ("oneOf" in node) {
+            for (const alternative of node.oneOf) {
+                walk(alternative, visit, { ...context, oneOf: node.oneOf, });
+            }
+        }
+    }
+}
+function flagNodes(nodes) {
+    const found = [];
+    walk(nodes, (node) => {
+        if ("flag" in node)
+            found.push(node);
+    });
+    return found;
+}
+/** Whether the syntax lists `--name` (the raw spelling, not an alias). */
+export function syntaxHasFlag(nodes, name) {
+    return flagNodes(nodes).some((node) => node.flag === name);
+}
+/** Leading literal words after `dss` (resource and, when present, action). */
+export function syntaxCommandWords(nodes) {
+    const words = [];
+    for (const node of nodes.slice(1)) {
+        if (typeof node !== "string")
+            break;
+        words.push(node);
+    }
+    return words;
+}
+function canonicalFlag(name) {
+    return FLAG_ALIASES[name] ?? name;
+}
+function knownCanonicalFlags(nodes) {
+    return unique(nodes.map((node) => canonicalFlag(node.flag))).filter((flag) => KNOWN_LONG_FLAGS.has(flag));
+}
+function unique(values) {
+    return [...new Set(values),];
+}
+/** Flags of a sequence outside its optional groups (a required choice's alternative). */
+function requiredFlagsOf(nodes) {
+    const found = [];
+    walk(nodes, (node, context) => {
+        if ("flag" in node && !context.optional)
+            found.push(node);
+    });
+    return knownCanonicalFlags(found);
+}
+function deriveRequired(nodes) {
+    const requiredFlags = knownCanonicalFlags(nodes.filter((node) => typeof node !== "string" && "flag" in node));
+    const requiredOneOf = [];
+    for (const node of nodes) {
+        if (typeof node === "string" || !("oneOf" in node))
+            continue;
+        const alternatives = node.oneOf.map(requiredFlagsOf);
+        if (alternatives.length <= 1) {
+            requiredFlags.push(...(alternatives[0] ?? []));
+            continue;
+        }
+        // A choice with a flagless alternative (a positional, e.g. sql query's
+        // `(SQL | --sql QUERY | ...)`) cannot be expressed as a flag-only choice:
+        // requiring one of the flags would be false. The handler stays the authority.
+        if (alternatives.some((alternative) => alternative.length === 0))
+            continue;
+        requiredOneOf.push({ oneOf: alternatives, });
+    }
+    return { requiredFlags: unique(requiredFlags), requiredOneOf, };
+}
+const PLACEHOLDER_VALUE = /^(<[^>]+>|[A-Z][A-Za-z0-9_]*)/;
+function deriveValueHints(flags) {
+    const hints = {};
+    // Enumerations take precedence over a placeholder elsewhere in the line.
+    for (const node of flags) {
+        const flag = canonicalFlag(node.flag);
+        if (node.values && hints[flag] === undefined) {
+            hints[flag] = { valueType: "enum", enumValues: node.values, };
+        }
+    }
+    for (const node of flags) {
+        const flag = canonicalFlag(node.flag);
+        const placeholder = node.value?.match(PLACEHOLDER_VALUE)?.[1];
+        if (placeholder && hints[flag] === undefined)
+            hints[flag] = { valueType: placeholder, };
+    }
+    return hints;
+}
+function derivePositionals(nodes) {
+    const positionals = [];
+    walk(nodes, (node, context) => {
+        if (!("arg" in node))
+            return;
+        const arg = node;
+        // A positional inside a required choice that offers a flag instead is optional.
+        const flagAlternative = context.oneOf?.some((alternative) => flagNodes(alternative).length > 0)
+            ?? false;
+        const required = !context.optional && !flagAlternative;
+        const existing = positionals.find((positional) => positional.name === arg.arg);
+        if (existing)
+            existing.required ||= required;
+        else
+            positionals.push({ name: arg.arg, required, });
+    });
+    return positionals;
+}
+/** Usage-level contract fields of a syntax tree (flags, requirements, value hints, positionals, inputs). */
+export function deriveSyntax(nodes) {
+    const flags = flagNodes(nodes);
+    const has = (name) => flags.some((node) => node.flag === name);
+    const aliases = {};
+    for (const [raw, canonical,] of Object.entries(FLAG_ALIASES)) {
+        if (has(raw))
+            (aliases[canonical] ??= []).push(raw);
+    }
+    return {
+        flags: knownCanonicalFlags(flags),
+        ...deriveRequired(nodes),
+        valueHints: deriveValueHints(flags),
+        inputContract: {
+            ...(has("stdin") ? { stdin: true, } : {}),
+            ...(flags.some((node) => node.flag === "data" && (node.value !== undefined || node.values !== undefined))
+                ? { dataFlag: true, }
+                : {}),
+            ...(has("data-file") ? { dataFileFlag: true, } : {}),
+        },
+        positionalArguments: derivePositionals(nodes),
+        aliases,
+        dryRun: has("dry-run"),
+        producesLocalFile: flags.some((node) => (node.flag === "output" || node.flag === "output-file") && node.value === "PATH"),
+    };
+}
+const syntaxCache = new Map();
+/** Usage-level contract fields for `resource.action`, derived from its syntax tree. */
+export function commandSyntax(resource, action) {
+    const key = `${resource}.${action}`;
+    let syntax = syntaxCache.get(key);
+    if (!syntax) {
+        syntax = deriveSyntax(requiredSyntaxTree(resource, action));
+        syntaxCache.set(key, syntax);
+    }
+    return syntax;
+}

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

@@ -28,7 +28,10 @@ export interface CommandMeta extends CommandRegistryOverride {
      * credentials are configured, instead of being masked by a missing-URL error.
      */
     validate?: (args: string[], flags: Record<string, string | boolean>) => void;
+    /** Rendered from the command's syntax tree in `src/cli/command-syntax.json`; never hand-written. */
     usage: string;
     description?: string;
     examples?: string[];
 }
+/** A command as authored: its usage line comes from `src/cli/command-syntax.json` (see `withUsage`). */
+export type CommandDefinition = Omit<CommandMeta, "usage">;