@oxygen-agent/cli 1.287.12 → 1.310.0

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.287.12
+Version: 1.310.0

package/dist/cli-values.d.ts

@@ -0,0 +1,18 @@
+/** Parse a `--limit`/`--interval`-style flag into a positive integer, or undefined when absent. */
+export declare function readPositiveInt(value: string | undefined): number | undefined;
+/** Read a string field from an unknown record-shaped value, or null when it is missing/non-string. */
+export declare function readRecordString(value: unknown, key: string): string | null;
+/** Parse a JSON string that must decode to a plain object, throwing a typed invalid_json error otherwise. */
+export declare function parseJsonObject(value: string): Record<string, unknown>;
+/** Read a JSON-object CLI option (e.g. `--selection-json`, `--filter-tree-json`), or undefined when absent. */
+export declare function readJsonObjectOption(value: string | undefined): Record<string, unknown> | undefined;
+/** Reject the mutually-exclusive `--live` + `--dry-run` combination with a typed conflicting_flags error. */
+export declare function assertModeFlagsExclusive(options: {
+    live?: boolean;
+    dryRun?: boolean;
+}): void;
+/** Resolve run mode from `--live`/`--dry-run` flags: live only when `--live` is set, otherwise dry_run. */
+export declare function resolveLiveDryRunMode(options: {
+    live?: boolean;
+    dryRun?: boolean;
+}): "live" | "dry_run";

package/dist/cli-values.js

@@ -0,0 +1,66 @@
+// Shared CLI value/option parsers, extracted so the same reader has exactly one
+// definition instead of byte-identical copies drifting apart across index.ts and
+// run-wait.ts (OXY-3733). Every helper here is pure and depends only on the
+// leaf `OxygenError` primitive plus `readOption` from `./util.js`, so this module
+// is a dependency-free leaf that index.ts and run-wait.ts can both import without
+// a cycle. All symbols throw the same typed OxygenError codes the copies did.
+import { OxygenError } from "@oxygen/shared";
+import { readOption } from "./util.js";
+/** Parse a `--limit`/`--interval`-style flag into a positive integer, or undefined when absent. */
+export function readPositiveInt(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new OxygenError("invalid_number", "Expected a positive integer.", {
+            details: { value },
+            exitCode: 1,
+        });
+    }
+    return parsed;
+}
+/** Read a string field from an unknown record-shaped value, or null when it is missing/non-string. */
+export function readRecordString(value, key) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const entry = value[key];
+    return typeof entry === "string" ? entry : null;
+}
+/** Parse a JSON string that must decode to a plain object, throwing a typed invalid_json error otherwise. */
+export function parseJsonObject(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (error) {
+        throw new OxygenError("invalid_json", "Input must be valid JSON.", {
+            details: { reason: error instanceof Error ? error.message : "unknown" },
+            exitCode: 1,
+        });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new OxygenError("invalid_json", "Input JSON must be an object.", {
+            exitCode: 1,
+        });
+    }
+    return parsed;
+}
+/** Read a JSON-object CLI option (e.g. `--selection-json`, `--filter-tree-json`), or undefined when absent. */
+export function readJsonObjectOption(value) {
+    const raw = readOption(value);
+    if (!raw)
+        return undefined;
+    return parseJsonObject(raw);
+}
+/** Reject the mutually-exclusive `--live` + `--dry-run` combination with a typed conflicting_flags error. */
+export function assertModeFlagsExclusive(options) {
+    if (options.live === true && options.dryRun === true) {
+        throw new OxygenError("conflicting_flags", "Pass either --live or --dry-run, not both.", { exitCode: 1 });
+    }
+}
+/** Resolve run mode from `--live`/`--dry-run` flags: live only when `--live` is set, otherwise dry_run. */
+export function resolveLiveDryRunMode(options) {
+    assertModeFlagsExclusive(options);
+    return options.live === true ? "live" : "dry_run";
+}

package/dist/credentials.d.ts

@@ -26,10 +26,30 @@ type CredentialProfilesState = {
     profiles: CredentialProfile[];
 };
 export declare function defaultApiUrl(env?: NodeJS.ProcessEnv): string;
+/**
+ * Which host this command will talk to, and what put it there — resolved from the
+ * same read that loads the credentials, so naming it costs nothing.
+ *
+ * A gate rejection that omits this is unreadable: dev's numbers and prod's numbers
+ * look identical, and a drifted profile turns a prod-labelled binary into a report
+ * about dev that reads as a production outage (OXY-4091).
+ */
+export type CliEndpointContext = {
+    apiUrl: string;
+    /** Active profile name, or null when no named profile supplied the credentials. */
+    profile: string | null;
+    apiUrlSource: "env" | "profile" | "default";
+};
+export type LoadedCredentials = {
+    credentials: StoredCredentials | null;
+    endpoint: CliEndpointContext;
+};
+export declare function loadCredentialsWithEndpoint(env?: NodeJS.ProcessEnv): Promise<LoadedCredentials>;
 export declare function loadCredentials(env?: NodeJS.ProcessEnv): Promise<StoredCredentials | null>;
 export declare function saveCredentials(credentials: StoredCredentials, env?: NodeJS.ProcessEnv, options?: {
     profile?: string;
     activate?: boolean;
+    allowHostChange?: boolean;
 }): Promise<string>;
 export declare function clearCredentials(env?: NodeJS.ProcessEnv, options?: {
     profile?: string;
@@ -46,11 +66,11 @@ export type ProfileResolution = {
     exists: boolean;
 };
 export declare function resolveActiveProfile(env?: NodeJS.ProcessEnv): Promise<ProfileResolution>;
-export declare function pickProfileNameForIdentity(organizationId: string, candidateSeed: string, env?: NodeJS.ProcessEnv): Promise<{
+export declare function pickProfileNameForIdentity(organizationId: string, candidateSeed: string, apiUrl: string, env?: NodeJS.ProcessEnv): Promise<{
     name: string;
     renamed: boolean;
 }>;
-export declare function pickProfileNameForUserSession(userId: string, candidateSeed: string, env?: NodeJS.ProcessEnv): Promise<{
+export declare function pickProfileNameForUserSession(userId: string, candidateSeed: string, apiUrl: string, env?: NodeJS.ProcessEnv): Promise<{
     name: string;
     renamed: boolean;
 }>;

package/dist/credentials.js

@@ -4,6 +4,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 import { OxygenError } from "@oxygen/shared";
+import { sameApiOrigin } from "./runtime.js";
 const execFileAsync = promisify(execFile);
 const SERVICE_NAME = "oxygen-cli";
 const ACCOUNT_NAME = "default";
@@ -27,7 +28,11 @@ function withApiUrlOverride(credentials, env) {
         return credentials;
     return { ...credentials, apiUrl: override };
 }
-export async function loadCredentials(env = process.env) {
+export async function loadCredentialsWithEndpoint(env = process.env) {
+    // OXYGEN_API_URL outranks every stored apiUrl (see withApiUrlOverride), so when
+    // it is set it IS the reason we are calling this host — and unsetting it, not
+    // switching profiles, is the remedy.
+    const envApiUrl = readEnvApiUrl(env);
     const envToken = readEnvToken(env);
     if (envToken) {
         const credentials = {
@@ -37,17 +42,41 @@ export async function loadCredentials(env = process.env) {
         const authKind = inferAuthKind(envToken);
         if (authKind)
             credentials.authKind = authKind;
-        return credentials;
+        return {
+            credentials,
+            endpoint: {
+                apiUrl: credentials.apiUrl,
+                profile: null,
+                apiUrlSource: envApiUrl ? "env" : "default",
+            },
+        };
     }
+    const unauthenticated = {
+        credentials: null,
+        endpoint: {
+            apiUrl: defaultApiUrl(env),
+            profile: null,
+            apiUrlSource: envApiUrl ? "env" : "default",
+        },
+    };
     const document = await readSystemCredentialDocument(env);
     if (!document)
-        return null;
+        return unauthenticated;
     const profiles = readProfiles(document);
     const requestedProfile = readEnvProfile(env);
     const activeProfile = requestedProfile ?? readProfileName(document.activeProfile) ?? DEFAULT_PROFILE_NAME;
     const profileCredentials = profiles[activeProfile];
-    if (profileCredentials)
-        return withApiUrlOverride(profileCredentials, env);
+    if (profileCredentials) {
+        const credentials = withApiUrlOverride(profileCredentials, env);
+        return {
+            credentials,
+            endpoint: {
+                apiUrl: credentials.apiUrl,
+                profile: activeProfile,
+                apiUrlSource: envApiUrl ? "env" : "profile",
+            },
+        };
+    }
     if (requestedProfile) {
         throw new OxygenError("profile_not_found", `Oxygen CLI profile "${requestedProfile}" is not stored.`, {
             details: { profile: requestedProfile },
@@ -55,18 +84,47 @@ export async function loadCredentials(env = process.env) {
         });
     }
     const storedCredentials = parseStoredCredentialsObject(document);
-    return storedCredentials ? withApiUrlOverride(storedCredentials, env) : null;
+    if (!storedCredentials)
+        return unauthenticated;
+    const credentials = withApiUrlOverride(storedCredentials, env);
+    return {
+        credentials,
+        endpoint: {
+            apiUrl: credentials.apiUrl,
+            profile: null,
+            apiUrlSource: envApiUrl ? "env" : "profile",
+        },
+    };
+}
+export async function loadCredentials(env = process.env) {
+    return (await loadCredentialsWithEndpoint(env)).credentials;
 }
 export async function saveCredentials(credentials, env = process.env, options = {}) {
     const normalized = normalizeStoredCredentialsRecord(credentials);
     const existing = await readSystemCredentialDocument(env);
     const profile = normalizeProfileName(options.profile ?? readEnvProfile(env) ?? existing?.activeProfile ?? DEFAULT_PROFILE_NAME);
     const profiles = existing ? readProfiles(existing) : {};
-    if (!normalized.identity) {
-        const prior = profiles[profile];
-        if (prior?.identity && prior.token === normalized.token) {
-            normalized.identity = prior.identity;
-        }
+    // A stored profile is bound to the host it was logged into. Without this, a dev
+    // login that names no profile writes its `apiUrl` into whatever profile is
+    // active — which is how the profile literally named `default` came to point at
+    // dev, taking every prod runbook with it (OXY-4109). Repointing is still
+    // possible, but it has to be asked for.
+    const prior = profiles[profile];
+    if (prior && !options.allowHostChange && !sameApiOrigin(prior.apiUrl, normalized.apiUrl)) {
+        throw new OxygenError("profile_host_conflict", `CLI profile "${profile}" is bound to ${prior.apiUrl}, and this login targets ${normalized.apiUrl}. `
+            + `Storing it here would silently repoint every command that uses "${profile}" at the other `
+            + "environment. Re-run with `--profile <name>` to keep them apart, or `--force` to repoint "
+            + `"${profile}" on purpose.`, {
+            details: {
+                profile,
+                stored_api_url: prior.apiUrl,
+                requested_api_url: normalized.apiUrl,
+            },
+            exitCode: 1,
+        });
+    }
+    if (!normalized.identity && prior?.identity && prior.token === normalized.token) {
+        normalized.identity = prior.identity;
     }
     profiles[profile] = normalized;
     const activeProfile = options.activate === false
@@ -159,10 +217,15 @@ export async function resolveActiveProfile(env = process.env) {
             : "default";
     return { name: candidate, source, credentials, exists: Boolean(credentials) };
 }
-async function pickProfileName(matches, candidateSeed, env) {
+async function pickProfileName(matches, candidateSeed, apiUrl, env) {
     const document = await readSystemCredentialDocument(env);
     const profiles = document ? readProfiles(document) : {};
-    const existing = Object.entries(profiles).find(([, credentials]) => matches(credentials));
+    // Identity alone is not enough to reuse a profile: the same person and the same
+    // org slug exist on dev and on prod, so matching on identity across hosts is
+    // what lets a dev login land on top of a production profile (OXY-4109). A
+    // profile is only reusable when it already points at the host we are logging in
+    // to; otherwise we name a new one.
+    const existing = Object.entries(profiles).find(([, credentials]) => sameApiOrigin(credentials.apiUrl, apiUrl) && matches(credentials));
     if (existing)
         return { name: existing[0], renamed: false };
     const base = normalizeProfileName(candidateSeed);
@@ -178,13 +241,13 @@ async function pickProfileName(matches, candidateSeed, env) {
         exitCode: 1,
     });
 }
-export async function pickProfileNameForIdentity(organizationId, candidateSeed, env = process.env) {
+export async function pickProfileNameForIdentity(organizationId, candidateSeed, apiUrl, env = process.env) {
     return pickProfileName((credentials) => credentials.identity?.organization?.id === organizationId ||
-        credentials.activeOrganization?.id === organizationId, candidateSeed, env);
+        credentials.activeOrganization?.id === organizationId, candidateSeed, apiUrl, env);
 }
-export async function pickProfileNameForUserSession(userId, candidateSeed, env = process.env) {
+export async function pickProfileNameForUserSession(userId, candidateSeed, apiUrl, env = process.env) {
     return pickProfileName((credentials) => credentials.authKind === "user_session" &&
-        credentials.identity?.user.id === userId, candidateSeed, env);
+        credentials.identity?.user.id === userId, candidateSeed, apiUrl, env);
 }
 export async function switchCredentialProfile(profile, env = process.env) {
     const document = await readSystemCredentialDocument(env);

package/dist/help.js

@@ -22,7 +22,7 @@ const HELP_GROUPS = [
         heading: "Data (tables, CRM, dashboards):",
         commands: [
             "tables", "rows", "cells", "columns", "action-column", "enrich-column",
-            "enrichment", "table-runs", "table-ingestions", "runs", "crm",
+            "enrichment", "table-runs", "table-ingestions", "runs", "crm", "signals",
             "dashboards", "projects", "signup-leads",
         ],
     },

package/dist/http-client.d.ts

@@ -1,4 +1,5 @@
 import { type StoredCredentials } from "./credentials.js";
+import { type CliEndpoint } from "./runtime.js";
 type RequestOptions = {
     method?: "GET" | "POST" | "PATCH" | "DELETE";
     body?: Record<string, unknown>;
@@ -16,5 +17,6 @@ export declare function requestOxygen<T>(// skipcq: JS-R1005
 path: string, options?: RequestOptions): Promise<T>;
 export declare function ensureFreshCliForApiUrl(apiUrl: string, options?: {
     fetch?: typeof fetch;
+    endpoint?: CliEndpoint;
 }): Promise<void>;
 export {};

package/dist/http-client.js

@@ -1,23 +1,33 @@
 import { OXYGEN_VERSION, OxygenError, isCliResult, isVersionGreater, readEnvelopeCompatibility, vercelProtectionBypassHeaders, withRetryAfterDetails, } from "@oxygen/shared";
 import { randomUUID } from "node:crypto";
-import { defaultApiUrl, loadCredentials } from "./credentials.js";
-import { isProdApiUrl, resolveCliUpdateGuidance } from "./runtime.js";
+import { defaultApiUrl, loadCredentialsWithEndpoint } from "./credentials.js";
+import { assertResolvedApiUrl, cliEndpointDetails, describeCliEndpoint, isProdApiUrl, resolveCliUpdateGuidance, } from "./runtime.js";
 const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
 const CLI_COMPATIBILITY_CHECK_TIMEOUT_MS = 5_000;
 const cliCompatibilityCheckKeys = new Set();
 export async function requestOxygen(// skipcq: JS-R1005
 path, options = {}) {
-    const credentials = options.credentials
-        ?? (options.requireAuth === false ? null : await loadCredentials());
+    const loaded = options.credentials === undefined && options.requireAuth !== false
+        ? await loadCredentialsWithEndpoint()
+        : null;
+    const credentials = options.credentials ?? loaded?.credentials ?? null;
     if (!credentials && options.requireAuth !== false) {
         throw new OxygenError("not_logged_in", "Run `oxygen login` before using CLI commands.", {
             exitCode: 1,
         });
     }
     const apiUrl = credentials?.apiUrl ?? defaultApiUrl();
+    // Which host, on whose behalf. Carried into every rejection below — a gate error
+    // that names only version numbers describes dev and prod identically (OXY-4091).
+    const endpoint = loaded?.endpoint ?? { apiUrl, profile: null };
+    // Before anything is dialed: if the caller pinned a host, this is where a
+    // command aimed at the wrong environment stops. It has to run ahead of the
+    // freshness probe, or the first thing a mispointed prod runbook gets is a
+    // version complaint from dev instead of the host mismatch that explains it.
+    assertResolvedApiUrl(endpoint);
     const fetchImpl = options.fetch ?? fetch;
     if (path !== "/api/health" && shouldCheckCliCompatibility(options)) {
-        await ensureFreshCliForApiUrl(apiUrl, { fetch: fetchImpl });
+        await ensureFreshCliForApiUrl(apiUrl, { fetch: fetchImpl, endpoint });
     }
     const traceId = options.traceId ?? randomUUID();
     const headers = {
@@ -93,14 +103,14 @@ path, options = {}) {
     }
     const envelope = await readEnvelope(response);
     const compatibility = readEnvelopeCompatibility(envelope);
-    assertCliMeetsMinimumApiVersion(compatibility, options, apiUrl);
-    warnIfCliIsOlderThanApi(compatibility.version, apiUrl);
+    assertCliMeetsMinimumApiVersion(compatibility, options, endpoint);
+    warnIfCliIsOlderThanApi(compatibility.version, endpoint);
     if (!response.ok || !envelope.ok) {
         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, failure.error.message, {
-            details: withTraceDetails(details, responseTraceId, compatibility, apiUrl),
+        throw new OxygenError(failure.error.code, describeFailureAgainstEndpoint(failure.error.code, failure.error.message, endpoint), {
+            details: withTraceDetails(details, responseTraceId, compatibility, endpoint),
             exitCode: 1,
         });
     }
@@ -114,10 +124,31 @@ export async function ensureFreshCliForApiUrl(apiUrl, options = {}) {
     if (!compatibility) {
         return;
     }
-    assertCliMeetsMinimumApiVersion(compatibility, {}, apiUrl);
-    warnIfCliIsOlderThanApi(compatibility.version, apiUrl);
+    const endpoint = options.endpoint ?? { apiUrl, profile: null };
+    assertCliMeetsMinimumApiVersion(compatibility, {}, endpoint);
+    warnIfCliIsOlderThanApi(compatibility.version, endpoint);
     cliCompatibilityCheckKeys.add(checkKey);
 }
+// The codes that mean "you may be talking to the wrong place": a floor rejection
+// and an auth rejection both read as catastrophic when the reader assumes prod and
+// the request went to dev. The server cannot know the caller's profile, so the
+// client appends what only it knows. `cli_update_required` is rebuilt outright —
+// the server's stock "run `oxygen update`" is actively wrong advice for a CLI that
+// is merely pointed at the wrong host (OXY-4091).
+const ENDPOINT_CONTEXT_CODES = new Set(["unauthorized", "forbidden"]);
+function describeFailureAgainstEndpoint(code, message, endpoint) {
+    const target = describeCliEndpoint(endpoint);
+    if (!target)
+        return message;
+    if (code === "cli_update_required") {
+        return `This Oxygen API requires a newer CLI. You are calling ${target}. `
+            + `${resolveCliUpdateGuidance(endpoint).failureInstruction}`;
+    }
+    if (ENDPOINT_CONTEXT_CODES.has(code)) {
+        return `${message} You are calling ${target}.`;
+    }
+    return message;
+}
 function resolveSelectedOrganization(credentials, explicit) {
     const fromOption = explicit?.trim();
     if (fromOption)
@@ -161,12 +192,12 @@ async function readHealthCompatibility(apiUrl, fetchImpl) {
     }
 }
 const staleCliWarningVersions = new Set();
-function warnIfCliIsOlderThanApi(serverVersion, apiUrl) {
+function warnIfCliIsOlderThanApi(serverVersion, endpoint) {
     if (!serverVersion)
         return;
     if (!isVersionGreater(serverVersion, OXYGEN_VERSION))
         return;
-    const guidance = resolveCliUpdateGuidance(apiUrl);
+    const guidance = resolveCliUpdateGuidance(endpoint);
     const warningKey = `${serverVersion}|${guidance.channel}|${guidance.binaryName}`;
     if (staleCliWarningVersions.has(warningKey))
         return;
@@ -174,28 +205,35 @@ function warnIfCliIsOlderThanApi(serverVersion, apiUrl) {
     process.stderr.write(`[${guidance.binaryName}] CLI version ${OXYGEN_VERSION} is older than Oxygen API version ${serverVersion}. `
         + `${guidance.warningInstruction}\n`);
 }
-function assertCliMeetsMinimumApiVersion(compatibility, options, apiUrl) {
+function assertCliMeetsMinimumApiVersion(compatibility, options, endpoint) {
     if (options.enforceMinimumCliVersion === false)
         return;
     const minimumCliVersion = compatibility.minimumCliVersion;
     if (!minimumCliVersion || !isVersionGreater(minimumCliVersion, OXYGEN_VERSION))
         return;
-    const guidance = resolveCliUpdateGuidance(apiUrl);
-    throw new OxygenError("cli_update_required", `This Oxygen API requires a newer CLI. ${guidance.failureInstruction}`, {
+    const guidance = resolveCliUpdateGuidance(endpoint);
+    const target = describeCliEndpoint(endpoint);
+    throw new OxygenError("cli_update_required", `This Oxygen API requires a newer CLI.${target ? ` You are calling ${target}.` : ""} `
+        + `${guidance.failureInstruction}`, {
         details: {
             client_version: OXYGEN_VERSION,
             ...(compatibility.version ? { server_version: compatibility.version } : {}),
             minimum_cli_version: minimumCliVersion,
+            ...cliEndpointDetails(endpoint),
             ...guidance.details,
         },
         exitCode: 1,
     });
 }
-function withTraceDetails(details, traceId, compatibility, apiUrl) {
+function withTraceDetails(details, traceId, compatibility, endpoint) {
     const serverVersion = compatibility.version;
+    const guidance = resolveCliUpdateGuidance(endpoint);
     const fields = {
         trace_id: traceId,
         client_version: OXYGEN_VERSION,
+        // Every failure carries the host it was sent to. `unauthorized` on the wrong
+        // host looks exactly like a revoked token on the right one (OXY-4091).
+        ...cliEndpointDetails(endpoint),
     };
     if (serverVersion)
         fields.server_version = serverVersion;
@@ -204,20 +242,20 @@ function withTraceDetails(details, traceId, compatibility, apiUrl) {
     if ((serverVersion && isVersionGreater(serverVersion, OXYGEN_VERSION))
         || (compatibility.minimumCliVersion
             && isVersionGreater(compatibility.minimumCliVersion, OXYGEN_VERSION))) {
-        Object.assign(fields, resolveCliUpdateGuidance(apiUrl).details);
-    }
-    if (details && typeof details === "object" && !Array.isArray(details)) {
-        return {
-            ...details,
-            ...fields,
-        };
+        Object.assign(fields, guidance.details);
     }
-    if (details === undefined)
-        return fields;
-    return {
-        details,
-        ...fields,
-    };
+    const merged = details && typeof details === "object" && !Array.isArray(details)
+        ? { ...details, ...fields }
+        : details === undefined
+            ? { ...fields }
+            : { details, ...fields };
+    // The server tells every rejected CLI to run `oxygen update`, because it cannot
+    // see which binary or profile called it. On a non-production endpoint that is a
+    // closed loop — npm can only reinstall the version this floor is rejecting — so
+    // the client, which does know, removes the fix that cannot work (OXY-4091).
+    if (guidance.channel === "profile")
+        delete merged.cli_update_command;
+    return merged;
 }
 function resolveRequestTimeoutMs(value) {
     if (value === undefined)