@oxygen-agent/cli 1.1011.405 → 1.1011.440

package/README.md

@@ -34,4 +34,4 @@ oxygen update
 
 For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
 
-Version: 1.1011.405
+Version: 1.1011.440

package/dist/command-manifest.js

@@ -1,3 +1,4 @@
+import { OPERATION_SPECS } from "@oxygen/shared/contracts/operations";
 import { CLI_EXIT_CODE_TABLE, OXYGEN_VERSION, inferUserCapabilityRoute, serializeCapabilityRoute, } from "@oxygen/shared";
 const DEFAULT_COMMAND_SEARCH_LIMIT = 10;
 const MAX_COMMAND_SEARCH_LIMIT = 25;
@@ -341,6 +342,7 @@ function toManifestEntry(command, path) {
     const leafVerb = path[path.length - 1] ?? "";
     const verbPrefix = leafVerb.split("-")[0] ?? leafVerb;
     const commandName = path.join(" ");
+    const operations = OPERATION_SPECS.filter((spec) => spec.cli.path.join(" ") === commandName);
     return {
         name: commandName,
         group: path[0] ?? "",
@@ -355,7 +357,9 @@ function toManifestEntry(command, path) {
             description: option.description,
             required: option.mandatory,
         })),
-        spends_credits: !ZERO_CREDIT_APPROVAL_COMMANDS.has(commandName) &&
+        // Some native commands read without flags and write with an explicit grant.
+        // Their metadata must include every available action's authorization posture.
+        spends_credits: operations.length ? operations.some((spec) => spec.spends) : (!ZERO_CREDIT_APPROVAL_COMMANDS.has(commandName) &&
             (flagStrings.some((flags) => flags.includes("--approved") ||
                 flags.includes("--max-credits") ||
                 // Legacy Copilot compatibility plus any future explicit budget flag.
@@ -368,11 +372,11 @@ function toManifestEntry(command, path) {
                 // cap flag exists for either, so the flag heuristic alone would misreport
                 // them as free.
                 (path[0] === "copilot" &&
-                    (leafVerb === "send" || leafVerb === "approve"))),
-        mutates: !READ_ONLY_COMMANDS.has(commandName)
+                    (leafVerb === "send" || leafVerb === "approve")))),
+        mutates: operations.length ? operations.some((spec) => spec.mutates) : (!READ_ONLY_COMMANDS.has(commandName)
             && (MUTATING_COMMANDS.has(commandName)
                 || MUTATING_VERBS.has(leafVerb)
-                || MUTATING_VERBS.has(verbPrefix)),
+                || MUTATING_VERBS.has(verbPrefix))),
         preview_by_default: flagStrings.some((flags) => flags.includes("--live")) ||
             PREVIEW_BY_DEFAULT_COMMANDS.has(commandName),
         json_supported: flagStrings.some((flags) => flags.includes("--json")),

package/dist/connectors-commands.js

@@ -49,6 +49,9 @@ export function buildConnectorUpdateBody(options) {
     if (!("default_workspace" in body) && !("credit_ceiling" in body)) {
         throw new OxygenError("invalid_request", "Pass --default-workspace <workspace> (or --clear-default-workspace) to set where the app works, or --credit-ceiling <credits> (or --clear-credit-ceiling) to set what it may spend in 24 hours.", { exitCode: 1 });
     }
+    if ("approve_above_default" in body && !("credit_ceiling" in body)) {
+        throw new OxygenError("invalid_request", "--approve-above-default only goes with --credit-ceiling (or --clear-credit-ceiling).", { exitCode: 1 });
+    }
     return body;
 }
 export function registerConnectorsCommands(program, handle) {

package/dist/contract-flags.js

@@ -24,7 +24,7 @@ function attribute(flag) {
     return flag.replace(/-([a-z0-9])/g, (_match, char) => char.toUpperCase());
 }
 function isObject(property) {
-    return "type" in property && property.type === "object" && property.properties !== undefined;
+    return "type" in property && property.type === "object";
 }
 function contractFlagSpecs(properties, overlay, parentPath = [], parentFlag = "") {
     const specs = [];
@@ -37,11 +37,14 @@ function contractFlagSpecs(properties, overlay, parentPath = [], parentFlag = ""
         const flag = entry.flag ?? `${parentFlag}${kebab(name)}`;
         if (isObject(property)) {
             const fields = Object.values(property.properties ?? {});
-            const splat = entry.flatten || (fields.length <= MAX_SPLAT_FIELDS && !fields.some((field) => isObject(unwrapNullable(field).property)));
+            const splat = entry.flatten || (fields.length > 0 && property.additionalProperties !== true && fields.length <= MAX_SPLAT_FIELDS && !fields.some((field) => isObject(unwrapNullable(field).property)));
             if (splat)
                 specs.push(...contractFlagSpecs(property.properties ?? {}, overlay, path, entry.flatten ? "" : `${flag}-`));
             else
-                specs.push({ kind: "json", path, flag: `${flag}-json`, entry });
+                specs.push({ kind: "json", path, flag: `${flag}-json`, property, entry });
+        }
+        else if (!("type" in property) || (property.type === "array" && !("type" in property.items && ["string", "number", "integer", "boolean"].includes(property.items.type)))) {
+            specs.push({ kind: "json", path, flag: `${flag}-json`, property, entry });
         }
         else if ("type" in property && property.type === "boolean") {
             specs.push(entry.pair ? { kind: "pair", path, on: entry.pair.on, off: entry.pair.off, entry } : { kind: "boolean", path, flag, entry });
@@ -97,7 +100,7 @@ export function addContractFlags(command, contract, overlay = {}) {
     return command;
 }
 function invalid(flag, value, message, code = "invalid_number") {
-    return new OxygenError(code, message, { details: { flag: `--${flag}`, value }, exitCode: 1 });
+    return new OxygenError(code, message, { details: { flag: `--${flag}`, value }, exitCode: 2 });
 }
 function parseScalar(property, raw, flag) {
     if (!("type" in property))
@@ -121,6 +124,13 @@ function parseScalar(property, raw, flag) {
     if (property.type === "string" && property.enum && !property.enum.includes(raw)) {
         throw invalid(flag, raw, `--${flag} must be one of: ${property.enum.join(", ")}.`, "invalid_option");
     }
+    if (property.type === "boolean") {
+        if (raw === "true")
+            return true;
+        if (raw === "false")
+            return false;
+        throw invalid(flag, raw, `--${flag} values must be true or false.`, "invalid_option");
+    }
     return raw;
 }
 function readValue(spec, raw) {
@@ -147,8 +157,8 @@ function setPath(body, path, value) {
 function stringOption(options, flag, aliases = []) {
     for (const name of [flag, ...aliases]) {
         const value = options[attribute(name)];
-        if (typeof value === "string" && value.trim())
-            return value.trim();
+        if (typeof value === "string")
+            return value;
     }
     return undefined;
 }
@@ -177,11 +187,14 @@ export function readContractFlags(options, contract, overlay = {}) {
                 parsed = JSON.parse(raw);
             }
             catch {
-                throw invalid(spec.flag, raw, `--${spec.flag} must be a JSON object.`, "invalid_json");
+                throw invalid(spec.flag, raw, `--${spec.flag} must be valid JSON.`, "invalid_json");
             }
-            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            if ("type" in spec.property && spec.property.type === "object" && (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))) {
                 throw invalid(spec.flag, raw, `--${spec.flag} must be a JSON object.`, "invalid_json");
             }
+            if ("type" in spec.property && spec.property.type === "array" && !Array.isArray(parsed)) {
+                throw invalid(spec.flag, raw, `--${spec.flag} must be a JSON array.`, "invalid_json");
+            }
             setPath(body, spec.path, parsed);
             given.add(spec.flag);
         }
@@ -198,7 +211,7 @@ export function readContractFlags(options, contract, overlay = {}) {
         }
         else if (options[attribute(spec.flag)] === true) {
             if (given.has(spec.target)) {
-                throw new OxygenError("invalid_request", `Pass either --${spec.target} or --${spec.flag}, not both.`, { exitCode: 1 });
+                throw new OxygenError("invalid_request", `Pass either --${spec.target} or --${spec.flag}, not both.`, { exitCode: 2 });
             }
             setPath(body, spec.path, null);
         }

package/dist/customer-operation-commands.d.ts

@@ -0,0 +1,5 @@
+import { Command } from "commander";
+/** Register each domain's selected operation as a native command with exact typed flags. */
+export declare function registerCustomerOperationCommands(program: Command, handle: (command: string, options: {
+    json?: boolean;
+}, action: () => Promise<unknown>) => Promise<void>): void;

package/dist/customer-operation-commands.js

@@ -0,0 +1,101 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { basename, extname, resolve } from "node:path";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { CLI_OPERATIONS, operationFormData, operationInputContract, operationRequest } from "@oxygen/shared/contracts/operations";
+import { unwrapNullable, validateContract } from "@oxygen/shared/contracts/schema";
+import { addContractFlags, readContractFlags } from "./contract-flags.js";
+import { requestOxygen } from "./http-client.js";
+/** Register each domain's selected operation as a native command with exact typed flags. */
+export function registerCustomerOperationCommands(program, handle) {
+    for (const spec of CLI_OPERATIONS) {
+        let parent = program;
+        const words = [...spec.cli.path];
+        const leaf = words.pop();
+        for (const word of words) {
+            let child = parent.commands.find((command) => command.name() === word);
+            if (!child)
+                child = parent.command(word).description(`${word} workspace operations.`);
+            parent = child;
+        }
+        // Never hide an existing owner behind a second Commander command.
+        if (parent.commands.some((command) => command.name() === leaf)) {
+            throw new Error(`Duplicate native operation command ${spec.cli.path.join(" ")}`);
+        }
+        const contract = operationInputContract(spec);
+        const command = addContractFlags(parent.command(leaf).description(spec.cli.summary), contract)
+            .option("--json", "Print a JSON envelope.");
+        if (spec.binary)
+            command.requiredOption("--output <path>", "Write the exact downloaded bytes to this local file.");
+        if (spec.multipart)
+            command.option("--file <path>", "Upload bytes from this local file. Omit the base64 flag; file name and content type default from the path.");
+        for (const name of contract.required ?? []) {
+            const property = contract.properties[name];
+            const flag = `--${name.replace(/_/g, "-")}`;
+            const option = command.options.find((candidate) => candidate.long === flag || candidate.long === `${flag}-json`);
+            const multipartAlternative = spec.multipart && [spec.multipart.contentField, spec.multipart.nameField, spec.multipart.typeField].includes(name);
+            if (multipartAlternative) {
+                if (option)
+                    option.description = `${option.description} Required unless supplied by --file.`.trim();
+            }
+            else if (unwrapNullable(property).nullable) {
+                if (option)
+                    option.description = `${option.description} Required: use this flag or --clear-${name.replace(/_/g, "-")}.`.trim();
+            }
+            else if (option) {
+                // The negative boolean spelling uses the same attribute, so an explicit
+                // false satisfies this requirement just as true does.
+                option.makeOptionMandatory();
+            }
+        }
+        command.action((options, selected) => handle(spec.cli.path.join(" "), { ...options, json: selected.optsWithGlobals().json === true }, async () => {
+            const input = readContractFlags(options, contract);
+            if (spec.multipart && options.file !== undefined) {
+                if (input[spec.multipart.contentField] !== undefined)
+                    throw new OxygenError("invalid_request", "Choose --file or the base64 content flag, not both.", { exitCode: 2 });
+                const filePath = String(options.file);
+                input[spec.multipart.contentField] = (await readFile(filePath)).toString("base64");
+                input[spec.multipart.nameField] ??= basename(filePath);
+                input[spec.multipart.typeField] ??= uploadContentType(filePath);
+            }
+            const validation = validateContract(contract, input, { unknown: "reject", overMax: "reject" });
+            if (!validation.ok)
+                throw new OxygenError("invalid_request", validation.issues.map((issue) => issue.message).join(" "), { exitCode: 2 });
+            const request = operationRequest(spec, input);
+            if (spec.binary) {
+                if (spec.binary.stream)
+                    return requestOxygen(request.path, { method: request.method, binaryOutputPath: resolve(String(options.output)) });
+                const bytes = await requestOxygen(request.path, { method: request.method, binaryMaxBytes: spec.binary.maxBytes });
+                const output = resolve(String(options.output));
+                try {
+                    await writeFile(output, bytes, { flag: "wx" });
+                }
+                catch (error) {
+                    if (error && typeof error === "object" && "code" in error && error.code === "EEXIST") {
+                        throw new OxygenError("output_exists", "The output file already exists. Choose another --output path.", { exitCode: 2 });
+                    }
+                    throw error;
+                }
+                return { path: output, bytes: bytes.byteLength };
+            }
+            if (spec.multipart) {
+                let formData;
+                try {
+                    formData = operationFormData(spec, request.body ?? {});
+                }
+                catch (error) {
+                    throw new OxygenError("invalid_request", error instanceof Error ? error.message : "Invalid upload.", { exitCode: 2 });
+                }
+                return requestOxygen(request.path, { method: request.method, formData });
+            }
+            return requestOxygen(request.path, { method: request.method, ...(request.body ? { body: request.body } : {}) });
+        }));
+    }
+}
+function uploadContentType(filePath) {
+    const types = {
+        ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".svg": "image/svg+xml",
+        ".csv": "text/csv", ".json": "application/json", ".jsonl": "application/x-ndjson",
+        ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    };
+    return types[extname(filePath).toLowerCase()] ?? "application/octet-stream";
+}

package/dist/database-query-flags.d.ts

@@ -0,0 +1,2 @@
+import type { ContractFlagOverlay } from "./contract-flags.js";
+export declare const DATABASE_QUERY_FLAG_OVERLAY: ContractFlagOverlay;

package/dist/database-query-flags.js

@@ -0,0 +1,6 @@
+import { readPositiveInt } from "./cli-values.js";
+export const DATABASE_QUERY_FLAG_OVERLAY = {
+    sql: { omit: true }, // Keep the existing required --sql option.
+    max_rows: { valueName: "<n>", parse: readPositiveInt }, // Preserve legacy coercion/defaults.
+    max_chars: { valueName: "<n>" },
+};

package/dist/help.d.ts

@@ -1,4 +1,4 @@
-import type { Command, CommanderError } from "commander";
+import { CommanderError, type Command } from "commander";
 import { type CliFailure } from "@oxygen/shared/cli-result";
 export declare function applyOxygenHelp(program: Command, binaryName: string): void;
 /**
@@ -12,6 +12,8 @@ export declare function applyOxygenHelp(program: Command, binaryName: string): v
  * `installCommanderExitOverride` recurses.
  */
 export declare function enableCommandSuggestions(command: Command): void;
+/** A declared flag following a value option is a missing value, not literal data. */
+export declare function validateRequiredOptionValues(program: Command, selected: Command): void;
 /**
  * The extra line printed after `error: unknown command '<x>'`.
  *

package/dist/help.js

@@ -1,3 +1,4 @@
+import { CommanderError } from "commander";
 import { CLI_EXIT_CODE_TABLE } from "@oxygen/shared";
 import { exitCodeForErrorCode, failure } from "@oxygen/shared/cli-result";
 // Grouped `--help` for the ~70 top-level command groups: commander's default
@@ -181,6 +182,38 @@ export function enableCommandSuggestions(command) {
     for (const child of command.commands)
         enableCommandSuggestions(child);
 }
+/** A declared flag following a value option is a missing value, not literal data. */
+export function validateRequiredOptionValues(program, selected) {
+    const options = new Map();
+    for (let current = selected; current; current = current.parent) {
+        for (const option of current.options) {
+            if (option.long && !options.has(option.long))
+                options.set(option.long, option);
+            if (option.short && !options.has(option.short))
+                options.set(option.short, option);
+        }
+    }
+    // Installed Commander writes this exact property before command dispatch;
+    // its public typings omit it. Validate only that property at this seam.
+    const rawArgs = Reflect.get(program, "rawArgs");
+    if (!Array.isArray(rawArgs) || !rawArgs.every((value) => typeof value === "string")) {
+        throw new CommanderError(2, "commander.invalidArgument", "Cannot validate the command's original option arguments.");
+    }
+    const argv = rawArgs;
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--")
+            break;
+        const option = options.get(token);
+        if (!option?.required)
+            continue;
+        const next = argv[index + 1];
+        if (next === undefined || next === "--" || options.has(next.split("=")[0])) {
+            throw new CommanderError(2, "commander.optionMissingArgument", `option '${option.flags}' argument missing. To use an option name as literal text, pass ${option.long ?? option.short}=<value>.`);
+        }
+        index += 1;
+    }
+}
 /**
  * Verbs a user reaches for that this CLI spells differently.
  *

package/dist/http-client.d.ts

@@ -3,6 +3,8 @@ import { type CliEndpoint } from "./runtime.js";
 type RequestOptions = {
     /** Internal bounded file download; never follows a caller-supplied URL. */
     binaryMaxBytes?: number;
+    /** Stream a native authenticated download to an exclusively created file. */
+    binaryOutputPath?: string;
     method?: "GET" | "POST" | "PATCH" | "DELETE";
     body?: Record<string, unknown>;
     formData?: FormData;

package/dist/http-client.js

@@ -1,5 +1,6 @@
 import { OXYGEN_VERSION, OxygenError, isCliResult, isVersionGreater, parseSemver, readEnvelopeCompatibility, vercelProtectionBypassHeaders, withRetryAfterDetails, } from "@oxygen/shared";
 import { randomUUID } from "node:crypto";
+import { open, unlink } from "node:fs/promises";
 import { recordMutatingRequestAnswered, recoverFromCliFloorRejection } from "./auto-update.js";
 import { defaultApiUrl, loadCredentialsWithEndpoint } from "./credentials.js";
 import { assertResolvedApiUrl, cliEndpointDetails, describeCliEndpoint, isProdApiUrl, resolveCliUpdateGuidance, } from "./runtime.js";
@@ -86,7 +87,7 @@ path, options = {}) {
     const requestInit = {
         method: options.method ?? "GET",
         headers,
-        ...(options.binaryMaxBytes === undefined ? {} : { redirect: "error" }),
+        ...(options.binaryMaxBytes === undefined && options.binaryOutputPath === undefined ? {} : { redirect: "error" }),
         ...(options.body ? { body: JSON.stringify(options.body) } : {}),
         ...(options.formData ? { body: options.formData } : {}),
     };
@@ -97,6 +98,9 @@ path, options = {}) {
         requestInit.signal = timeout.signal;
     try {
         response = await fetchImpl(`${apiUrl}${path}`, requestInit);
+        if (response.ok && options.binaryOutputPath !== undefined) {
+            return await streamBinaryResponse(response, options.binaryOutputPath);
+        }
         if (response.ok && options.binaryMaxBytes !== undefined) {
             return await readBoundedBinaryResponse(response, options.binaryMaxBytes);
         }
@@ -195,6 +199,42 @@ async function readBoundedBinaryResponse(response, maxBytes) {
     }
     return bytes;
 }
+async function streamBinaryResponse(response, output) {
+    let file;
+    try {
+        file = await open(output, "wx");
+    }
+    catch (error) {
+        await response.body?.cancel();
+        if (error && typeof error === "object" && "code" in error && error.code === "EEXIST") {
+            throw new OxygenError("output_exists", "The output file already exists. Choose another --output path.", { exitCode: 2 });
+        }
+        throw error;
+    }
+    const reader = response.body?.getReader();
+    let bytes = 0;
+    try {
+        if (!reader)
+            throw new OxygenError("invalid_response", "The download had no body.");
+        for (;;) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            await file.writeFile(chunk.value);
+            bytes += chunk.value.byteLength;
+        }
+        await file.close();
+        return { path: output, bytes };
+    }
+    catch (error) {
+        await file.close().catch(() => { });
+        await unlink(output).catch(() => { });
+        throw error;
+    }
+    finally {
+        await reader?.cancel().catch(() => { });
+    }
+}
 export async function ensureFreshCliForApiUrl(apiUrl, options = {}) {
     const checkKey = `${apiUrl}|${OXYGEN_VERSION}`;
     if (cliCompatibilityCheckKeys.has(checkKey))