@substrio/cli 0.0.0-stage → 0.1.1

package/src/cli.mjs

@@ -0,0 +1,405 @@
+/**
+ * Substrio CLI: the one front end every command goes through.
+ *
+ * Global flags are parsed once, wherever they stand on the command line, and
+ * taken off before a command sees its arguments:
+ *   --help, -h         print the command's usage and exit 0; nothing runs
+ *   --json             print results as JSON (stdout) and errors as JSON (stderr)
+ *   --yes, -y          confirm a destructive command without asking
+ *   --profile NAME     use the saved profile NAME (as SUBSTRIO_PROFILE)
+ *   --tenant SLUG      talk to tenant SLUG (as SUBSTRIO_TENANT)
+ *   --dev              use the dev server `substrio dev` runs for the project in this directory (its saved profile)
+ *   --version, -v      print the CLI version
+ *   --                 everything after it is the command's own
+ *
+ * `globals` holds the parsed flags for the commands to read; nothing else
+ * parses them.
+ */
+
+import { writeSync } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+
+const RED = '\x1b[91m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+const BOOLEAN_FLAGS = new Map([
+    ['--help', 'help'], ['-h', 'help'], ['--json', 'json'], ['--yes', 'yes'], ['-y', 'yes'],
+    ['--version', 'version'], ['-v', 'version'], ['--dev', 'dev'],
+]);
+const VALUE_FLAGS = new Map([['--profile', 'profile'], ['--tenant', 'tenant']]);
+
+const emptyFlags = () => ({ help: false, json: false, yes: false, version: false, dev: false, profile: null, tenant: null });
+
+/** The flags of this run, set once by applyGlobals. */
+export const globals = emptyFlags();
+
+/**
+ * The command, its own arguments and the global flags (pure). `substrio help X`
+ * is `substrio X --help`. `--` stops global flag parsing and stays in the command's arguments. Throws when a value flag has no value.
+ */
+export function parseGlobal(argv) {
+    const flags = emptyFlags();
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--') {
+            // Kept for the command's own splitter (ops.mjs splitPositional), which ends option parsing at it.
+            rest.push(...argv.slice(i));
+            break;
+        }
+        if (BOOLEAN_FLAGS.has(arg)) {
+            flags[BOOLEAN_FLAGS.get(arg)] = true;
+            continue;
+        }
+        const eq = arg.indexOf('=');
+        const name = arg.startsWith('--') && eq > 0 ? arg.slice(0, eq) : arg;
+        if (VALUE_FLAGS.has(name)) {
+            const value = name === arg ? argv[++i] : arg.slice(eq + 1);
+            if (value === undefined || value === '' || value.startsWith('-')) throw new Error(`${name} needs a value`);
+            flags[VALUE_FLAGS.get(name)] = value;
+            continue;
+        }
+        rest.push(arg);
+    }
+    if (rest[0] === 'help') {
+        flags.help = true;
+        rest.shift();
+    }
+    return { command: rest[0] ?? null, args: rest.slice(1), flags };
+}
+
+/** Makes `flags` this run's globals; --profile and --tenant reach config as the environment does. */
+export function applyGlobals(flags, env = process.env) {
+    Object.assign(globals, flags);
+    if (flags.profile) env.SUBSTRIO_PROFILE = flags.profile;
+    if (flags.tenant) env.SUBSTRIO_TENANT = flags.tenant;
+    if (flags.json) output.machine();
+}
+
+/**
+ * The codes the CLI raises itself, spelled as the server's error codes (the
+ * `code` enum of the OpenAPI Error schema). A server error keeps its own.
+ */
+export const ErrorCode = Object.freeze({
+    INVALID_ARGUMENT: 'INVALID_ARGUMENT',
+    CREDENTIAL_REQUIRED: 'CREDENTIAL_REQUIRED',
+    FILE_NOT_FOUND: 'FILE_NOT_FOUND',
+    // The server could not be reached (no HTTP answer at all).
+    NETWORK_ERROR: 'NETWORK_ERROR',
+    // A destructive command ran with no --yes and no terminal to ask on.
+    CONFIRMATION_REQUIRED: 'CONFIRMATION_REQUIRED',
+    UNKNOWN: 'UNKNOWN',
+});
+
+/**
+ * One line of a server JSON error body into the message people read: its
+ * `error` (a string, or an {message} object), falling back to `message`,
+ * with `detail` appended; `HTTP status` when the body said nothing (pure).
+ * The one owner cli.mjs's own users import; api.mjs keeps its own copy for
+ * the callers that already load it for the API client.
+ */
+export function errorText(data, status) {
+    const error = data?.error;
+    const label = (typeof error === 'string' ? error : error?.message) || data?.message || '';
+    const detail = typeof data?.detail === 'string' ? data.detail : '';
+    if (detail) return label ? `${label}: ${detail}` : detail;
+    return label || `HTTP ${status}`;
+}
+
+/**
+ * The process exit codes, one per kind of failure, so a script can tell them
+ * apart without parsing text. `exitCodeFor` is their one owner; `substrio help`
+ * lists them (EXIT_CODE_HELP).
+ */
+export const ExitCode = Object.freeze({
+    OK: 0,
+    FAILURE: 1,   // anything not listed below
+    USAGE: 2,     // bad arguments or input (INVALID_ARGUMENT, a 400 or 422)
+    AUTH: 3,      // no credentials or refused (CREDENTIAL_REQUIRED, a 401 or 403)
+    NOT_FOUND: 4, // what was named does not exist (a 404 or 410)
+    CONFLICT: 5,  // it exists already or changed meanwhile (a 409 or 412)
+    SERVER: 6,    // the server failed (a 5xx)
+    NETWORK: 7,   // the server could not be reached
+    PARTIAL: 8,   // a bulk operation stored some documents and refused others (substrio data import)
+    CONFIRM: 9,   // a destructive command needs --yes (no terminal to ask on, or --json)
+});
+
+export const EXIT_CODE_HELP = [
+    [ExitCode.OK, 'success'], [ExitCode.FAILURE, 'failure'], [ExitCode.USAGE, 'usage: bad arguments or input'],
+    [ExitCode.AUTH, 'auth: no credentials, or refused'], [ExitCode.NOT_FOUND, 'not found'],
+    [ExitCode.CONFLICT, 'conflict: exists already or changed meanwhile'], [ExitCode.SERVER, 'server error (5xx)'],
+    [ExitCode.NETWORK, 'network: the server could not be reached'],
+    [ExitCode.PARTIAL, 'partial: some documents were stored, others refused (each reported)'],
+    [ExitCode.CONFIRM, 'confirm: a destructive command needs --yes (no terminal to ask on, or --json)'],
+];
+
+// The exit code of a CLI code that came with no HTTP status.
+const EXIT_BY_CODE = new Map([
+    [ErrorCode.INVALID_ARGUMENT, ExitCode.USAGE], [ErrorCode.CREDENTIAL_REQUIRED, ExitCode.AUTH],
+    [ErrorCode.FILE_NOT_FOUND, ExitCode.NOT_FOUND], [ErrorCode.NETWORK_ERROR, ExitCode.NETWORK],
+    [ErrorCode.CONFIRMATION_REQUIRED, ExitCode.CONFIRM],
+]);
+
+/** The exit code of a CliError: from the server's HTTP status when one came back, else from its code. */
+export function exitCodeFor(error) {
+    const status = error.status;
+    if (status) {
+        if (status === 401 || status === 403) return ExitCode.AUTH;
+        if (status === 404 || status === 410) return ExitCode.NOT_FOUND;
+        if (status === 409 || status === 412) return ExitCode.CONFLICT;
+        if (status >= 500) return ExitCode.SERVER;
+        if (status >= 400) return ExitCode.USAGE;
+    }
+    return EXIT_BY_CODE.get(error.code) ?? ExitCode.FAILURE;
+}
+
+const ANSI = /\x1b\[[0-9;]*m/g;
+const plain = (parts) => parts.map(String).join(' ').replace(ANSI, '').replace(/^\s*✗\s*/, '').trim();
+
+/**
+ * The run's stdout and stderr, and the only writer of both under --json:
+ * then stdout holds one JSON document (what `emit` was given, or
+ * {"ok": true, "messages": [...]} for a command that only prints text) and
+ * stderr holds one error in the server's Error shape ({error, code, status?,
+ * detail?, ...}) on a nonzero exit. Text a command prints under --json is
+ * kept as messages, never mixed into the JSON.
+ */
+class Output {
+    constructor() {
+        this.json = false;
+        this.emitted = false;
+        this.errored = false;
+        this.messages = [];
+        this.problems = [];
+    }
+
+    machine() {
+        if (this.json) return;
+        this.json = true;
+        console.log = console.info = (...parts) => { const line = plain(parts); if (line) this.messages.push(line); };
+        console.error = console.warn = (...parts) => { const line = plain(parts); if (line) this.problems.push(line); };
+        process.on('exit', (code) => this.finish(code));
+    }
+
+    // Small documents at exit: written before the process goes.
+    write(fd, value) {
+        writeSync(fd, `${JSON.stringify(value, null, 2)}\n`);
+    }
+
+    // A result may be large: the stream flushes it before a natural exit.
+    emit(data) {
+        this.emitted = true;
+        process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    }
+
+    error(body) {
+        this.errored = true;
+        this.write(2, body);
+    }
+
+    // One record of a stream (substrio logs --tail): one compact JSON line,
+    // written as it comes, so nothing is held until exit.
+    line(data) {
+        this.emitted = true;
+        process.stdout.write(`${JSON.stringify(data)}\n`);
+    }
+
+    // A failed run that printed its reason as text still ends in one typed
+    // error; one that emitted its result (a status report) already said why.
+    finish(code) {
+        if (code && !this.errored && !this.emitted) {
+            const [first, ...rest] = this.problems.length ? this.problems : this.messages;
+            this.error({ error: first || `exit ${code}`, code: ErrorCode.UNKNOWN, ...(rest.length ? { detail: rest.join('\n') } : {}) });
+        } else if (!code && !this.emitted) {
+            this.write(1, { ok: true, messages: this.messages });
+        }
+    }
+}
+
+const output = new Output();
+
+/**
+ * An error the CLI reports: `code` from ErrorCode (or the server's), `hint`
+ * what to do next, `body` a server's error body when one came back.
+ */
+export class CliError extends Error {
+    constructor(message, { code = ErrorCode.INVALID_ARGUMENT, hint = null, status = null, body = null } = {}) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.status = status;
+        this.body = body;
+    }
+
+    /** A failed server call: `message` for people, the server's body and status as they came. */
+    static fromResponse(message, body, status) {
+        return new CliError(message, { code: body?.code || ErrorCode.UNKNOWN, status, body });
+    }
+
+    /**
+     * The server's Error shape: a server body as it came (with its status), else built here.
+     * `diagnostics` (function.check's shape: severity, message, file, line, column), when a local
+     * build failure set it, rides along: a build failure never has a server body, so it always
+     * takes the shape built here.
+     */
+    toJSON() {
+        if (this.body && typeof this.body === 'object' && this.body.error) {
+            return { ...this.body, ...(this.status ? { status: this.status } : {}) };
+        }
+        return {
+            error: this.message, code: this.code,
+            ...(this.status ? { status: this.status } : {}), ...(this.hint ? { detail: this.hint } : {}),
+            ...(this.diagnostics ? { diagnostics: this.diagnostics } : {}),
+        };
+    }
+}
+
+/** Prints `data` as JSON under --json, else as `human` prints it (pretty JSON when none). */
+export function emit(data, human = null) {
+    if (globals.json) output.emit(data);
+    else if (human) human(data);
+    else console.log(JSON.stringify(data, null, 2));
+}
+
+/**
+ * Prints one record of a stream: a JSON line (NDJSON) under --json, written
+ * at once, else as `human` prints it.
+ */
+export function emitLine(data, human) {
+    if (globals.json) output.line(data);
+    else human(data);
+}
+
+/**
+ * Hands on a key the server just issued (`data` holds `key`): with --print,
+ * the key alone on stdout, or under --json the whole response as the one
+ * JSON document (the key left out without --print, so it is never shown
+ * unasked).
+ */
+export function emitIssuedKey(data, print) {
+    if (globals.json) {
+        const { key, ...rest } = data;
+        output.emit(print ? data : rest);
+    } else if (print) {
+        process.stdout.write(`${data.key}\n`);
+    }
+}
+
+/**
+ * Reports an error and exits with its ExitCode (exitCodeFor): `err` is a
+ * CliError, an Error or a message; `hint` says what to do next. Under
+ * --json, the typed error on stderr.
+ */
+export function fail(err, hint = null, code = ErrorCode.INVALID_ARGUMENT) {
+    // A CliError keeps its own code and status (so its exit code); the hint
+    // fills in when it has none.
+    const error = err instanceof CliError ? err : new CliError(err instanceof Error ? err.message : String(err), { code, hint });
+    if (hint && !error.hint) error.hint = hint;
+    if (globals.json) {
+        output.error(error.toJSON());
+    } else {
+        process.stderr.write(`${RED}✗ ${error.message}${RESET}\n`);
+        if (error.hint) process.stderr.write(`${DIM}  ${error.hint}${RESET}\n`);
+    }
+    process.exit(exitCodeFor(error));
+}
+
+/**
+ * Questions on one readline for the whole run. Asking with no terminal on
+ * stdin throws (the answer has to come from a flag), so piped input is never
+ * read as answers and nothing is half-written.
+ */
+export class Prompter {
+    constructor(input = process.stdin, output = process.stdout) {
+        this.input = input;
+        this.output = output;
+        this.rl = null;
+    }
+
+    get interactive() {
+        return Boolean(this.input.isTTY);
+    }
+
+    async ask(question, fallback = '', flag = null) {
+        if (!this.interactive) {
+            if (fallback) return fallback;
+            throw new Error(`${question}: no terminal to ask on${flag ? `; pass ${flag}` : ''}`);
+        }
+        this.rl ??= createInterface({ input: this.input, output: this.output });
+        const answer = (await this.rl.question(`${question}${fallback ? ` (${fallback})` : ''}: `)).trim();
+        return answer || fallback;
+    }
+
+    /**
+     * Asks `question` with the answer never echoed to the terminal (a
+     * password): raw keystrokes, read and discarded without ever reaching
+     * readline's history or the screen. Throws with no terminal, same as ask.
+     */
+    async askSecret(question, flag = null) {
+        if (!this.interactive) {
+            throw new Error(`${question}: no terminal to ask on${flag ? `; pass ${flag}` : ''}`);
+        }
+        this.output.write(`${question}: `);
+        return new Promise((resolve, reject) => {
+            const stdin = this.input;
+            let value = '';
+            const onData = (chunk) => {
+                for (const ch of chunk.toString('utf8')) {
+                    if (ch === '\n' || ch === '\r') {
+                        cleanup();
+                        this.output.write('\n');
+                        resolve(value);
+                        return;
+                    }
+                    if (ch === '') { // Ctrl+C
+                        cleanup();
+                        this.output.write('\n');
+                        reject(new Error('cancelled'));
+                        return;
+                    }
+                    if (ch === '' || ch === '\b') value = value.slice(0, -1);
+                    else value += ch;
+                }
+            };
+            const cleanup = () => {
+                stdin.setRawMode(false);
+                stdin.pause();
+                stdin.removeListener('data', onData);
+            };
+            stdin.setRawMode(true);
+            stdin.resume();
+            stdin.on('data', onData);
+        });
+    }
+
+    close() {
+        this.rl?.close();
+        this.rl = null;
+    }
+}
+
+/**
+ * The one gate every destructive command runs through (tenants delete,
+ * restore, a registry delete/revoke/remove/drop/purge/reset/clear/restore):
+ * --yes skips it; a terminal asks through Prompter and refuses on anything
+ * but yes; --json or no terminal runs nothing and answers one typed error
+ * (code confirmation_required, naming what would be destroyed, `next` the
+ * same command with --yes), its own exit code (ExitCode.CONFIRM).
+ */
+export async function confirmDestructive(what, nextCommand) {
+    if (globals.yes) return;
+    const prompter = new Prompter();
+    if (globals.json || !prompter.interactive) {
+        fail(new CliError(what, {
+            code: ErrorCode.CONFIRMATION_REQUIRED,
+            body: { error: what, code: 'confirmation_required', next: nextCommand },
+        }));
+    }
+    try {
+        const answer = await prompter.ask(`${what}. Continue?`, 'n');
+        if (!/^y(es)?$/i.test(answer)) fail('Not confirmed.', null, ErrorCode.UNKNOWN);
+    } finally {
+        prompter.close();
+    }
+}