@oxygen-agent/cli 1.1010.721 → 1.1010.950

package/dist/contract-flags.js

@@ -0,0 +1,220 @@
+// The CLI half of a shared resource contract (@oxygen/shared/contracts/schema).
+// A command's flags and the request body they build are generated from the same
+// contract that generates the MCP input schema and validates the route, so a
+// settable field cannot exist on one surface and not the other.
+//
+// Derivation (the overlay only renames, re-words, aliases or hides):
+//   scalar            --<kebab-name> <value>       numbers parsed and range-checked
+//   enum              --<kebab-name> <value>       membership checked
+//   boolean           --<x> / --no-<x>             tri-state: absent = not sent
+//   array of scalars  --<kebab-name> <a,b,c>
+//   object, <= 6 scalar fields   --<obj>-<field> per field
+//   larger object     --<obj>-json <json>
+//   nullable          also --clear-<x>, which sends null
+// Every value is checked inside the action (never in a Commander parser), so a
+// bad value comes back as the JSON error envelope, not a raw stack trace.
+import { Option } from "commander";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { unwrapNullable } from "@oxygen/shared/contracts/schema";
+const MAX_SPLAT_FIELDS = 6;
+function kebab(name) {
+    return name.replace(/_/g, "-");
+}
+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;
+}
+function contractFlagSpecs(properties, overlay, parentPath = [], parentFlag = "") {
+    const specs = [];
+    for (const [name, raw] of Object.entries(properties)) {
+        const path = [...parentPath, name];
+        const entry = overlay[path.join(".")] ?? {};
+        if (entry.omit)
+            continue;
+        const { property, nullable } = unwrapNullable(raw);
+        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)));
+            if (splat)
+                specs.push(...contractFlagSpecs(property.properties ?? {}, overlay, path, entry.flatten ? "" : `${flag}-`));
+            else
+                specs.push({ kind: "json", path, flag: `${flag}-json`, 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 });
+        }
+        else {
+            specs.push({ kind: "value", path, flag, property, entry });
+        }
+        if (nullable && !entry.noClear)
+            specs.push({ kind: "clear", path, flag: `clear-${flag}`, target: flag });
+    }
+    return specs;
+}
+function helpFor(spec, property) {
+    if (spec.entry.help !== undefined)
+        return spec.entry.help;
+    const description = property && "description" in property ? property.description ?? "" : "";
+    const values = property && "enum" in property && property.enum ? ` One of: ${property.enum.join(", ")}.` : "";
+    return `${description}${values}`.trim();
+}
+function propertyAt(contract, path) {
+    let current = contract;
+    for (const key of path) {
+        const unwrapped = current ? unwrapNullable(current).property : undefined;
+        current = unwrapped && isObject(unwrapped) ? unwrapped.properties?.[key] : undefined;
+    }
+    return current ? unwrapNullable(current).property : undefined;
+}
+/** Registers the contract's flags on `command`, in contract order. */
+export function addContractFlags(command, contract, overlay = {}) {
+    for (const spec of contractFlagSpecs(contract.properties, overlay)) {
+        const property = "path" in spec ? propertyAt(contract, spec.path) : undefined;
+        if (spec.kind === "pair") {
+            command.addOption(new Option(`--${spec.on}`, spec.entry.pair?.onHelp));
+            command.addOption(new Option(`--${spec.off}`, spec.entry.pair?.offHelp));
+            continue;
+        }
+        if (spec.kind === "clear") {
+            command.addOption(new Option(`--${spec.flag}`, `Clear it (sends null). Not with --${spec.target}.`));
+            continue;
+        }
+        if (spec.kind === "boolean") {
+            command.addOption(new Option(`--${spec.flag}`, helpFor(spec, property)));
+            command.addOption(new Option(`--no-${spec.flag}`, spec.entry.negateHelp ?? `Sends ${spec.path.join(".")}: false.`));
+            continue;
+        }
+        const valueName = spec.entry.valueName ?? (spec.kind === "json" ? "<json>" : "<value>");
+        command.addOption(new Option(`--${spec.flag} ${valueName}`, helpFor(spec, property)));
+        for (const alias of spec.entry.aliases ?? [])
+            command.addOption(new Option(`--${alias} ${valueName}`).hideHelp());
+    }
+    return command;
+}
+function invalid(flag, value, message, code = "invalid_number") {
+    return new OxygenError(code, message, { details: { flag: `--${flag}`, value }, exitCode: 1 });
+}
+function parseScalar(property, raw, flag) {
+    if (!("type" in property))
+        return raw;
+    if (property.type === "integer" || property.type === "number") {
+        const parsed = Number(raw);
+        const whole = property.type === "integer";
+        const minimum = property.minimum;
+        const ok = whole ? Number.isSafeInteger(parsed) : Number.isFinite(parsed);
+        if (!ok || (minimum !== undefined && parsed < minimum)) {
+            throw invalid(flag, raw, minimum === 0
+                ? `Expected a non-negative ${whole ? "integer" : "number"}.`
+                : `Expected ${whole ? "an integer" : "a number"}${minimum !== undefined ? ` of at least ${minimum}` : ""}.`);
+        }
+        // A clamped field is lowered (and reported) by the server; anything else over the maximum is refused here.
+        if (property.maximum !== undefined && parsed > property.maximum && !property["x-clamp"]) {
+            throw invalid(flag, raw, `Expected at most ${property.maximum}.`);
+        }
+        return parsed;
+    }
+    if (property.type === "string" && property.enum && !property.enum.includes(raw)) {
+        throw invalid(flag, raw, `--${flag} must be one of: ${property.enum.join(", ")}.`, "invalid_option");
+    }
+    return raw;
+}
+function readValue(spec, raw) {
+    if (spec.entry.parse)
+        return spec.entry.parse(raw);
+    const property = spec.property;
+    if ("type" in property && property.type === "array") {
+        return raw.split(",").map((part) => part.trim()).filter(Boolean)
+            .map((part) => parseScalar(unwrapNullable(property.items).property, part, spec.flag));
+    }
+    return parseScalar(property, raw, spec.flag);
+}
+function setPath(body, path, value) {
+    let cursor = body;
+    for (const key of path.slice(0, -1)) {
+        const next = cursor[key];
+        if (typeof next === "object" && next !== null && !Array.isArray(next))
+            cursor = next;
+        else
+            cursor = (cursor[key] = {});
+    }
+    cursor[path[path.length - 1]] = 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();
+    }
+    return undefined;
+}
+/**
+ * The request body the parsed flags describe: only the fields given, nested as
+ * the contract nests them. An object none of whose flags was given is absent.
+ */
+export function readContractFlags(options, contract, overlay = {}) {
+    const body = {};
+    const specs = contractFlagSpecs(contract.properties, overlay);
+    const given = new Set();
+    for (const spec of specs) {
+        if (spec.kind === "value") {
+            const raw = stringOption(options, spec.flag, spec.entry.aliases);
+            if (raw === undefined)
+                continue;
+            setPath(body, spec.path, readValue(spec, raw));
+            given.add(spec.flag);
+        }
+        else if (spec.kind === "json") {
+            const raw = stringOption(options, spec.flag, spec.entry.aliases);
+            if (raw === undefined)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                throw invalid(spec.flag, raw, `--${spec.flag} must be a JSON object.`, "invalid_json");
+            }
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                throw invalid(spec.flag, raw, `--${spec.flag} must be a JSON object.`, "invalid_json");
+            }
+            setPath(body, spec.path, parsed);
+            given.add(spec.flag);
+        }
+        else if (spec.kind === "boolean") {
+            const value = options[attribute(spec.flag)];
+            if (typeof value === "boolean")
+                setPath(body, spec.path, value);
+        }
+        else if (spec.kind === "pair") {
+            if (options[attribute(spec.off)] === true)
+                setPath(body, spec.path, false);
+            else if (options[attribute(spec.on)] === true)
+                setPath(body, spec.path, true);
+        }
+        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 });
+            }
+            setPath(body, spec.path, null);
+        }
+    }
+    return body;
+}
+/** Every long flag `addContractFlags` registers, in order (for tests and docs). */
+export function contractFlagNames(contract, overlay = {}) {
+    return contractFlagSpecs(contract.properties, overlay).flatMap((spec) => {
+        switch (spec.kind) {
+            case "pair":
+                return [`--${spec.on}`, `--${spec.off}`];
+            case "boolean":
+                return [`--${spec.flag}`, `--no-${spec.flag}`];
+            case "clear":
+                return [`--${spec.flag}`];
+            default:
+                return [`--${spec.flag}`, ...(spec.entry.aliases ?? []).map((alias) => `--${alias}`)];
+        }
+    });
+}

package/dist/credentials.d.ts

@@ -77,4 +77,6 @@ export declare function pickProfileNameForUserSession(userId: string, candidateS
 export declare function switchCredentialProfile(profile: string, env?: NodeJS.ProcessEnv): Promise<CredentialProfile>;
 export declare function updateActiveOrganizationForProfile(profile: string, organization: StoredOrganization, env?: NodeJS.ProcessEnv): Promise<CredentialProfile>;
 export declare function normalizeApiUrl(value: string): string;
+/** The CLI's per-user config directory; `OXYGEN_CONFIG_DIR` overrides it. */
+export declare function resolveConfigDir(env?: NodeJS.ProcessEnv): string;
 export {};

package/dist/credentials.js

@@ -411,12 +411,15 @@ function credentialStore(env) {
         return "credential-manager";
     return "file";
 }
-function credentialsPath(env) {
-    const configDir = env.OXYGEN_CONFIG_DIR?.trim()
+/** The CLI's per-user config directory; `OXYGEN_CONFIG_DIR` overrides it. */
+export function resolveConfigDir(env = process.env) {
+    return env.OXYGEN_CONFIG_DIR?.trim()
         || (process.platform === "win32"
             ? join(env.APPDATA || join(homedir(), "AppData", "Roaming"), "oxygen")
             : join(homedir(), ".config", "oxygen"));
-    return join(configDir, "credentials.json");
+}
+function credentialsPath(env) {
+    return join(resolveConfigDir(env), "credentials.json");
 }
 function readFileCredentialPayload(env) {
     const path = credentialsPath(env);

package/dist/functions-commands.js

@@ -47,7 +47,7 @@ export function registerFunctionsCommands(program, handle) {
     functions.command("rename <function> <name>").description("Rename a Function while preserving its identity, callers and published execution.")
         .option("--json", "Print a JSON envelope.")
         .action((ref, name, options) => handle("functions rename", options, () => requestOxygen("/api/cli/functions", { method: "POST", body: { operation: "rename", function: ref, display_name: name } })));
-    functions.command("delete <function>").description("Preview removal from the Function library, then remove it with --yes; preserves backing tables, rows and run history. Connected callers or active runs block deletion.")
+    functions.command("delete <function>").description("Preview removal from the Function library, then remove it with --yes; preserves backing tables, rows and run history. The preview names every column that calls it: those stop running, keeping the values they already wrote. Only the Function's own active runs block deletion.")
         .addHelpText("after", "\nDeleting your own Function is final: there is no restore, unlike `tables delete`. To reuse the logic, `tables duplicate` the backing Table and draft a new Function from the copy.\n")
         .option("--yes", "Confirm removal of this Function after reviewing its callers.")
         .option("--json", "Print a JSON envelope.")

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 { recordMutatingRequestAnswered, recoverFromCliFloorRejection } from "./auto-update.js";
 import { defaultApiUrl, loadCredentialsWithEndpoint } from "./credentials.js";
 import { assertResolvedApiUrl, cliEndpointDetails, describeCliEndpoint, isProdApiUrl, resolveCliUpdateGuidance, } from "./runtime.js";
 const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
@@ -31,7 +32,14 @@ path, options = {}) {
         ...init, signal: init?.signal ? AbortSignal.any([options.signal, init.signal]) : options.signal,
     }) : baseFetch;
     if (path !== "/api/health" && shouldCheckCliCompatibility(options)) {
-        await ensureFreshCliForApiUrl(apiUrl, { fetch: fetchImpl, endpoint });
+        try {
+            await ensureFreshCliForApiUrl(apiUrl, { fetch: fetchImpl, endpoint });
+        }
+        catch (error) {
+            // The preflight dialed only /api/health: nothing has run yet, so an
+            // automatic update may re-run this command in the new binary.
+            throw error instanceof OxygenError ? await recoverFromCliFloorRejection(error, endpoint) : error;
+        }
     }
     options.signal?.throwIfAborted();
     const traceId = options.traceId ?? randomUUID();
@@ -117,17 +125,33 @@ path, options = {}) {
     }
     const envelope = await readEnvelope(response);
     const compatibility = readEnvelopeCompatibility(envelope);
-    assertCliMeetsMinimumApiVersion(compatibility, options, endpoint);
+    const failed = !response.ok || !envelope.ok;
+    try {
+        assertCliMeetsMinimumApiVersion(compatibility, options, endpoint);
+    }
+    catch (error) {
+        // Only a refused request is safe to re-run: a successful one already did its work.
+        throw failed && error instanceof OxygenError ? await recoverFromCliFloorRejection(error, endpoint) : error;
+    }
     warnIfCliIsOlderThanApi(compatibility.version, endpoint);
-    if (!response.ok || !envelope.ok) {
+    if (failed) {
         const failure = envelope;
         const responseTraceId = response.headers.get("x-oxygen-trace-id") ?? traceId;
         const details = withRetryAfterDetails(failure.error.details, response);
-        throw new OxygenError(failure.error.code, describeFailureAgainstEndpoint(failure.error.code, failure.error.message, endpoint), {
+        const error = new OxygenError(failure.error.code, describeFailureAgainstEndpoint(failure.error.code, failure.error.message, endpoint), {
             details: withTraceDetails(details, responseTraceId, compatibility, endpoint),
             exitCode: 1,
         });
+        // The floor gate refuses before the route does any work (assertCliClientVersionFloor).
+        if (error.code === "cli_update_required")
+            throw await recoverFromCliFloorRejection(error, endpoint);
+        // Any other answer to a write may have written something; never re-run the command after it.
+        if (method !== "GET")
+            recordMutatingRequestAnswered();
+        throw error;
     }
+    if (method !== "GET")
+        recordMutatingRequestAnswered();
     return envelope.data;
 }
 async function readBoundedBinaryResponse(response, maxBytes) {