@uptimerobot/cli 0.1.0

package/dist/lib/auth.js

@@ -0,0 +1,60 @@
+import { credentialStore } from './credential-store.js';
+export const PRODUCTION_API_URL = 'https://api.uptimerobot.com/v3';
+const VALIDATION_TIMEOUT_MS = 10_000;
+export class AuthenticationError extends Error {
+    code;
+    exitCode;
+    constructor(code, message, exitCode) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+    }
+}
+export async function saveValidatedApiKey(apiKey, apiUrl, attribution, store = credentialStore, fetchImplementation = fetch) {
+    if (apiUrl !== PRODUCTION_API_URL) {
+        throw new AuthenticationError('AUTH_URL_RESTRICTED', 'Persistent login is only available for api.uptimerobot.com. Use UPTIMEROBOT_API_KEY or --api-key with a custom API URL.', 2);
+    }
+    let response;
+    try {
+        response = await fetchImplementation(new URL(`${apiUrl}/user/me`), {
+            headers: {
+                accept: 'application/json',
+                authorization: `Bearer ${apiKey}`,
+                'user-agent': `uptimerobot-cli/${attribution.version} mode/${attribution.mode} environment/${attribution.environment}`,
+                'x-uptimerobot-client': 'cli',
+                'x-uptimerobot-execution-environment': attribution.environment,
+                'x-uptimerobot-invocation-mode': attribution.mode,
+            },
+            signal: AbortSignal.timeout(VALIDATION_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        throw new AuthenticationError('AUTH_INVALID', `Could not validate the API key: ${error instanceof Error ? error.message : String(error)}`, 1);
+    }
+    if (!response.ok) {
+        throw new AuthenticationError('AUTH_INVALID', `API key validation failed with HTTP ${response.status}.`, 4);
+    }
+    try {
+        return await store.setApiKey(apiKey);
+    }
+    catch {
+        throw new AuthenticationError('AUTH_STORAGE_UNAVAILABLE', 'No credential storage is available. Use UPTIMEROBOT_API_KEY for this environment.', 1);
+    }
+}
+export async function resolveApiKey(explicitApiKey, apiUrl, store = credentialStore) {
+    if (typeof explicitApiKey === 'string' && explicitApiKey.length > 0)
+        return explicitApiKey;
+    if (apiUrl !== PRODUCTION_API_URL) {
+        throw new AuthenticationError('AUTH_URL_RESTRICTED', 'Stored credentials are only used with api.uptimerobot.com. Pass --api-key or set UPTIMEROBOT_API_KEY for a custom API URL.', 2);
+    }
+    let stored;
+    try {
+        stored = await store.getApiKey();
+    }
+    catch {
+        throw new AuthenticationError('AUTH_STORAGE_UNAVAILABLE', 'Credential storage is unavailable. Set UPTIMEROBOT_API_KEY or pass --api-key.', 1);
+    }
+    if (stored)
+        return stored.apiKey;
+    throw new AuthenticationError('AUTH_REQUIRED', 'Run `uptimerobot auth login --api-key <key>`, set UPTIMEROBOT_API_KEY, or pass --api-key.', 2);
+}

package/dist/lib/base-command.js

@@ -0,0 +1,21 @@
+import { Command } from '@oclif/core';
+import { CliFailure, errorEnvelope, exitCodeForError, machineOutputRequested, markErrorHandled, } from './cli-errors.js';
+export class BaseCommand extends Command {
+    async catch(error) {
+        const failure = error instanceof CliFailure;
+        const machineOutput = machineOutputRequested(this.argv);
+        if (!failure && !machineOutput) {
+            await super.catch(error);
+            throw error;
+        }
+        this.logToStderr(failure && !machineOutput
+            ? `${error.cliError.message}${error.cliError.code ? ` (${error.cliError.code})` : ''}`
+            : JSON.stringify(errorEnvelope(error)));
+        process.exitCode = exitCodeForError(error);
+        markErrorHandled(error);
+        throw error;
+    }
+    fail(error, exitCode) {
+        throw new CliFailure(error, exitCode);
+    }
+}

package/dist/lib/cli-errors.js

@@ -0,0 +1,80 @@
+import { outputFormatFromEnvironment, requestedFormatFromArgv } from '../output/resolve-format.js';
+import { agentEnvironmentDetected } from './invocation.js';
+import { isRecord } from './objects.js';
+const handledErrors = new WeakSet();
+export class CliFailure extends Error {
+    cliError;
+    oclif;
+    constructor(error, exitCode) {
+        super(error.message);
+        this.cliError = error;
+        this.oclif = { exit: exitCode };
+    }
+}
+export function errorEnvelope(error) {
+    if (error instanceof CliFailure)
+        return { error: error.cliError };
+    const metadata = isRecord(error) ? error : {};
+    const exitCode = exitCodeForError(error);
+    const code = typeof metadata.code === 'string' && metadata.code !== 'EEXIT'
+        ? metadata.code
+        : exitCode === 2
+            ? 'INVALID_INPUT'
+            : 'CLI_ERROR';
+    const message = typeof metadata.message === 'string'
+        ? metadata.message
+        : typeof error === 'string'
+            ? error
+            : 'The command failed.';
+    return {
+        error: {
+            code,
+            ...(metadata.details !== undefined ? { details: metadata.details } : {}),
+            ...(typeof metadata.expected === 'string' ? { expected: metadata.expected } : {}),
+            message,
+            ...(typeof metadata.path === 'string' ? { path: metadata.path } : {}),
+            ...(typeof metadata.status === 'number' ? { status: metadata.status } : {}),
+            ...(Array.isArray(metadata.suggestions) &&
+                metadata.suggestions.every((suggestion) => typeof suggestion === 'string')
+                ? { suggestions: metadata.suggestions }
+                : {}),
+        },
+    };
+}
+export function exitCodeForError(error) {
+    if (!isRecord(error))
+        return 1;
+    const oclifExit = isRecord(error.oclif) ? error.oclif.exit : undefined;
+    if (typeof oclifExit === 'number')
+        return oclifExit;
+    return typeof error.exitCode === 'number' ? error.exitCode : 1;
+}
+export function machineOutputRequested(argv = process.argv.slice(2), env = process.env, stdoutIsTTY = process.stdout.isTTY === true) {
+    const separator = argv.indexOf('--');
+    const options = separator === -1 ? argv : argv.slice(0, separator);
+    if (options.includes('--json') || options.includes('--raw'))
+        return true;
+    const format = requestedFormatFromArgv(options);
+    if (format === 'json' || format === 'jsonl')
+        return true;
+    if (format === 'plain' || format === 'table')
+        return false;
+    const environmentFormat = outputFormatFromEnvironment(env);
+    if (environmentFormat !== undefined) {
+        if (environmentFormat === 'json' || environmentFormat === 'jsonl')
+            return true;
+        if (environmentFormat === 'plain' || environmentFormat === 'table')
+            return false;
+    }
+    if (options.includes('--agent'))
+        return true;
+    if (agentEnvironmentDetected(env))
+        return true;
+    return !stdoutIsTTY;
+}
+export function markErrorHandled(error) {
+    handledErrors.add(error);
+}
+export function wasErrorHandled(error) {
+    return isRecord(error) && handledErrors.has(error);
+}

package/dist/lib/command-suggestions.js

@@ -0,0 +1,44 @@
+import { operations } from '../generated/operations.js';
+/**
+ * Commands implemented by hand rather than generated from the OpenAPI
+ * contract. A test asserts that each entry maps to a compiled command file,
+ * so renames and removals break CI instead of silently dropping suggestions.
+ */
+export const HANDWRITTEN_COMMANDS = [
+    'auth login',
+    'auth logout',
+    'auth status',
+    'auth whoami',
+    'monitors schema',
+    'user get',
+];
+const commands = [
+    ...Object.keys(operations).map((commandId) => commandId.replaceAll(':', ' ')),
+    ...HANDWRITTEN_COMMANDS,
+];
+export function commandSuggestion(argv) {
+    const firstFlag = argv.findIndex((value) => value.startsWith('-'));
+    const input = (firstFlag === -1 ? argv : argv.slice(0, firstFlag)).join(' ');
+    if (!input)
+        return undefined;
+    const ranked = commands
+        .map((command) => ({ command, distance: editDistance(input, command) }))
+        .sort((left, right) => left.distance - right.distance || left.command.localeCompare(right.command));
+    const best = ranked[0];
+    if (!best || best.distance > Math.max(2, Math.floor(input.length * 0.2)))
+        return undefined;
+    if (ranked[1]?.distance === best.distance)
+        return undefined;
+    return best.command;
+}
+function editDistance(left, right) {
+    let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+        const current = [leftIndex];
+        for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+            current[rightIndex] = Math.min(current[rightIndex - 1] + 1, previous[rightIndex] + 1, previous[rightIndex - 1] + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1));
+        }
+        previous = current;
+    }
+    return previous[right.length];
+}

package/dist/lib/credential-store.js

@@ -0,0 +1,152 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const KEYRING_ACCOUNT = 'default:api-key';
+const KEYRING_SERVICE = 'com.uptimerobot.cli';
+const KEYRING_TIMEOUT_MS = 3000;
+const CREDENTIALS_FILENAME = 'credentials.json';
+/** The directory that holds the plaintext fallback credential. */
+export function configDirectory(env = process.env) {
+    const override = env.UPTIMEROBOT_CONFIG_DIR;
+    if (override)
+        return override;
+    const xdgConfigHome = env.XDG_CONFIG_HOME;
+    return xdgConfigHome
+        ? join(xdgConfigHome, 'uptimerobot')
+        : join(homedir(), '.config', 'uptimerobot');
+}
+export function credentialsFilePath(env = process.env) {
+    return join(configDirectory(env), CREDENTIALS_FILENAME);
+}
+/**
+ * OS credential store (macOS Keychain, Windows Credential Manager, Linux
+ * Secret Service or kernel keyring). Keyring operations are time-boxed
+ * because a missing or locked D-Bus session can hang them on Linux.
+ */
+class KeyringCredentialStore {
+    async deleteApiKey() {
+        return withKeyringTimeout((await keyringEntry()).deleteCredential());
+    }
+    async getApiKey() {
+        const apiKey = await withKeyringTimeout((await keyringEntry()).getPassword());
+        return apiKey ? { apiKey, backend: 'keyring' } : undefined;
+    }
+    async setApiKey(apiKey) {
+        const credential = await keyringEntry();
+        await withKeyringTimeout(credential.setPassword(apiKey));
+        if ((await withKeyringTimeout(credential.getPassword())) !== apiKey) {
+            throw new Error('Credential could not be read back after saving.');
+        }
+        return 'keyring';
+    }
+}
+/**
+ * Plaintext fallback for environments without an OS keyring
+ * (minimal/headless Linux, containers): a JSON file beneath the CLI config
+ * directory with directory 0700 and file 0600 permissions.
+ */
+class FileCredentialStore {
+    async deleteApiKey() {
+        try {
+            await rm(credentialsFilePath());
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    }
+    async getApiKey() {
+        let raw;
+        try {
+            raw = await readFile(credentialsFilePath(), 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            const apiKey = typeof parsed === 'object' && parsed !== null
+                ? parsed.apiKey
+                : undefined;
+            return typeof apiKey === 'string' && apiKey.length > 0
+                ? { apiKey, backend: 'file' }
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async setApiKey(apiKey) {
+        const directory = configDirectory();
+        await mkdir(directory, { mode: 0o700, recursive: true });
+        await chmod(directory, 0o700).catch(() => { });
+        const path = credentialsFilePath();
+        const temporary = join(directory, `.${CREDENTIALS_FILENAME}.${process.pid}.tmp`);
+        await writeFile(temporary, JSON.stringify({ apiKey }), { mode: 0o600 });
+        await rename(temporary, path);
+        await chmod(path, 0o600).catch(() => { });
+        const stored = await this.getApiKey();
+        if (stored?.apiKey !== apiKey) {
+            throw new Error('Credential could not be read back after saving.');
+        }
+        return 'file';
+    }
+}
+/**
+ * Prefers the OS keyring and falls back to the plaintext config file when
+ * the keyring is unavailable. Reads prefer the keyring so a credential
+ * migrated there takes precedence over a stale file.
+ */
+class FallbackCredentialStore {
+    keyring;
+    file;
+    constructor(keyring, file) {
+        this.keyring = keyring;
+        this.file = file;
+    }
+    async deleteApiKey() {
+        const [keyring, file] = await Promise.allSettled([
+            this.keyring.deleteApiKey(),
+            this.file.deleteApiKey(),
+        ]);
+        if (keyring.status === 'rejected' && file.status === 'rejected')
+            throw keyring.reason;
+        return ((keyring.status === 'fulfilled' && keyring.value) ||
+            (file.status === 'fulfilled' && file.value));
+    }
+    async getApiKey() {
+        try {
+            const stored = await this.keyring.getApiKey();
+            if (stored)
+                return stored;
+        }
+        catch {
+            // The keyring is unavailable; fall back to the config file.
+        }
+        return this.file.getApiKey();
+    }
+    async setApiKey(apiKey) {
+        try {
+            return await this.keyring.setApiKey(apiKey);
+        }
+        catch {
+            return this.file.setApiKey(apiKey);
+        }
+    }
+}
+export const credentialStore = new FallbackCredentialStore(new KeyringCredentialStore(), new FileCredentialStore());
+async function keyringEntry() {
+    const { AsyncEntry } = await import('@napi-rs/keyring');
+    return new AsyncEntry(KEYRING_SERVICE, KEYRING_ACCOUNT);
+}
+function withKeyringTimeout(operation) {
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error('The OS credential store did not respond in time.')), KEYRING_TIMEOUT_MS);
+    });
+    return Promise.race([operation.finally(() => clearTimeout(timer)), timeout]);
+}

package/dist/lib/flag-name.js

@@ -0,0 +1,11 @@
+/**
+ * Converts an OpenAPI parameter or field name into its CLI flag spelling.
+ * The generator (scripts/generate-openapi.ts) and the runtime must always
+ * agree on this mapping, so both import it from here.
+ */
+export function flagName(value) {
+    return value
+        .replace(/_/g, '-')
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .toLowerCase();
+}

package/dist/lib/invocation.js

@@ -0,0 +1,74 @@
+import { emitKeypressEvents } from 'node:readline';
+import { createInterface } from 'node:readline/promises';
+/** Environment variables set by known coding-agent runtimes. */
+export const AGENT_ENVIRONMENT_VARIABLES = ['CLAUDECODE', 'CODEX_SANDBOX', 'CURSOR_AGENT'];
+export function isCI() {
+    return /^(1|true|yes)$/i.test(process.env.CI ?? '');
+}
+/**
+ * The single source of truth for agent-driven execution. UPTIMEROBOT_AGENT is
+ * an explicit override in both directions; otherwise a known agent runtime's
+ * environment marker decides.
+ */
+export function agentEnvironmentDetected(env = process.env) {
+    const override = env.UPTIMEROBOT_AGENT;
+    if (override !== undefined)
+        return /^(1|true|yes)$/i.test(override);
+    return AGENT_ENVIRONMENT_VARIABLES.some((name) => env[name]);
+}
+export function detectInvocationMode(agentFlag, env = process.env) {
+    return agentFlag || agentEnvironmentDetected(env) ? 'agent' : 'human';
+}
+export async function requestConfirmation(operation, mode) {
+    if (mode === 'agent' || !process.stdin.isTTY || !process.stdout.isTTY)
+        return false;
+    const reader = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await reader.question(`${operation.summary}. Continue? [y/N] `);
+        return /^(y|yes)$/i.test(answer.trim());
+    }
+    finally {
+        reader.close();
+    }
+}
+/**
+ * Prompts for a secret on stderr with masked echo. Returns undefined when
+ * there is no interactive terminal, so callers can fail with guidance instead.
+ */
+export async function promptSecret(question) {
+    if (!process.stdin.isTTY || !process.stderr.isTTY)
+        return undefined;
+    process.stderr.write(question);
+    return new Promise((resolve) => {
+        let secret = '';
+        const finish = (value, exitCode) => {
+            process.stdin.setRawMode(false);
+            process.stdin.removeListener('keypress', onKeypress);
+            process.stderr.write('\n');
+            if (exitCode !== undefined)
+                process.exit(exitCode);
+            resolve(value);
+        };
+        const onKeypress = (str, key) => {
+            if (key.ctrl && key.name === 'c')
+                return finish(undefined, 130);
+            if (key.name === 'return')
+                return finish(secret.trim() || undefined);
+            if (key.name === 'backspace') {
+                if (secret.length > 0) {
+                    secret = [...secret].slice(0, -1).join('');
+                    process.stderr.write('\b \b');
+                }
+                return;
+            }
+            if (str === '' || str < ' ')
+                return; // arrows, escape sequences, control keys
+            secret += str;
+            process.stderr.write('*'.repeat([...str].length));
+        };
+        emitKeypressEvents(process.stdin);
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.on('keypress', onKeypress);
+    });
+}

package/dist/lib/objects.js

@@ -0,0 +1,34 @@
+/**
+ * Shared record and dotted-path helpers. Keep these behavior-compatible with
+ * the request compiler: path traversal treats arrays as values, not records.
+ */
+/** Any non-null object, including arrays and class instances such as Error. */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** A plain object: non-null and not an array. */
+export function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function valueAtPath(target, path) {
+    let value = target;
+    for (const segment of path.split('.')) {
+        if (!isPlainRecord(value))
+            return undefined;
+        value = value[segment];
+    }
+    return value;
+}
+export function assignPath(target, path, value) {
+    const segments = path.split('.').filter(Boolean);
+    if (segments.length === 0)
+        throw new Error('A field path is required.');
+    let cursor = target;
+    for (const segment of segments.slice(0, -1)) {
+        const existing = cursor[segment];
+        if (!isPlainRecord(existing))
+            cursor[segment] = {};
+        cursor = cursor[segment];
+    }
+    cursor[segments.at(-1)] = value;
+}