@kazurolabs/psql-explorer 0.0.0-stage → 0.3.0

package/dist/commands/explore.js

@@ -0,0 +1,388 @@
+// The commands that work without the TUI: list environments, look at what is in a database, page
+// through a table and run SQL. Each prints its result on stdout (as a table, CSV or JSON) and
+// returns the exit code; what went wrong goes to stderr.
+import { addressOf, findEnvironment, listEnvironments, } from '../environments.js';
+import { describeTable, listSchemas, listTables, parseTableRef, serverInfo, tableLabel, } from '../explorer/catalog.js';
+import { commandSummary, formatBytes, formatDuration, formatEstimate, formatResult, outputFormats, } from '../explorer/format.js';
+import { browseRows, DEFAULT_PAGE_SIZE } from '../explorer/rows.js';
+import { compareSchemas } from '../explorer/schema-diff.js';
+import { DEFAULT_MAX_ROWS, describeQueryError, } from '../explorer/session.js';
+import { connectEntry } from '../explorer/connect-entry.js';
+export const commandNames = [
+    'envs',
+    'schemas',
+    'tables',
+    'describe',
+    'rows',
+    'query',
+    'info',
+    'history',
+    'diff',
+];
+export const isCommand = (name) => commandNames.includes(name);
+/** Thrown for a wrong command line: exit code 2. */
+class UsageError extends Error {
+}
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+// A listing of the explorer's own (not a query's), where nothing is shown for a missing value.
+const result = (columns, rows) => ({
+    command: 'SELECT',
+    columns: columns.map((name) => ({ name, type: 'text' })),
+    rows: rows.map((row) => row.map((value) => value ?? '')),
+    rowCount: rows.length,
+    truncated: false,
+    durationMs: 0,
+});
+const text = (value) => value === null || value === undefined ? null : String(value);
+function formatOf(flags) {
+    if (flags.json)
+        return 'json';
+    const format = flags.format ?? 'table';
+    if (!outputFormats.includes(format)) {
+        throw new UsageError(`--format must be one of: ${outputFormats.join(', ')}`);
+    }
+    return format;
+}
+function environmentFor(options, env = options.flags.env) {
+    if (!env)
+        throw new UsageError(`${options.command} needs --env <name>`);
+    const entry = findEnvironment(options.services, env);
+    if (entry)
+        return entry;
+    const names = listEnvironments(options.services).map((candidate) => candidate.name);
+    throw new Error(`no environment named "${env}"${names.length > 0 ? `; there are: ${names.join(', ')}` : ''}`);
+}
+/** Looks up the environment's settings (Vault, prompts, ...) and connects. */
+function connect(options, entry) {
+    const { timeout } = options.flags;
+    return connectEntry(entry, options.services, {
+        ...(timeout === undefined ? {} : { statementTimeoutMs: timeout === 0 ? null : timeout * 1000 }),
+    });
+}
+async function withSession(options, work) {
+    const entry = environmentFor(options);
+    const session = await connect(options, entry);
+    try {
+        return await work(session, entry);
+    }
+    finally {
+        await session.close();
+    }
+}
+function envs(options) {
+    const format = formatOf(options.flags);
+    const entries = listEnvironments(options.services);
+    if (format === 'json') {
+        options.out(`${JSON.stringify(entries.map((entry) => ({
+            name: entry.name,
+            source: entry.source,
+            tier: entry.tier,
+            protected: entry.protected,
+            readOnly: entry.readOnly,
+            address: addressOf(entry),
+            tls: entry.tlsMode,
+        })), null, 2)}\n`);
+    }
+    else {
+        options.out(formatResult(result(['name', 'source', 'tier', 'access', 'address'], entries.map((entry) => [
+            entry.name,
+            entry.source,
+            entry.tier,
+            entry.readOnly ? 'read only' : 'read write',
+            addressOf(entry),
+        ])), format));
+    }
+    const error = options.services.configError;
+    if (error)
+        options.err(`psql-explorer: ${error.message}\n`);
+    return 0;
+}
+const json = (options, value) => {
+    options.out(`${JSON.stringify(value, null, 2)}\n`);
+};
+async function schemas(options, session) {
+    const format = formatOf(options.flags);
+    const found = await listSchemas(session);
+    if (format === 'json')
+        json(options, found);
+    else {
+        options.out(formatResult(result(['name', 'owner', 'tables'], found.map((schema) => [schema.name, schema.owner, String(schema.tables)])), format));
+    }
+    return 0;
+}
+async function tables(options, session) {
+    const format = formatOf(options.flags);
+    const schema = options.flags.schema ?? session.params.schema;
+    const found = await listTables(session, schema);
+    if (format === 'json')
+        json(options, found);
+    else {
+        options.out(formatResult(result(['name', 'kind', 'rows', 'size', 'comment'], found.map((table) => [
+            table.name,
+            table.kind,
+            format === 'table' ? formatEstimate(table.estimatedRows) : text(table.estimatedRows),
+            format === 'table' ? formatBytes(table.totalBytes) : text(table.totalBytes),
+            table.comment,
+        ])), format));
+    }
+    if (found.length === 0)
+        options.err(`psql-explorer: schema ${schema} has no tables\n`);
+    return 0;
+}
+const tableArgument = (options, session) => {
+    const [name] = options.args;
+    if (!name)
+        throw new UsageError(`${options.command} needs a table, e.g. users or app.users`);
+    return parseTableRef(name, options.flags.schema ?? session.params.schema);
+};
+async function describe(options, session) {
+    const format = formatOf(options.flags);
+    const details = await describeTable(session, tableArgument(options, session));
+    if (format === 'json') {
+        json(options, details);
+        return 0;
+    }
+    const columns = result(['column', 'type', 'nullable', 'default', 'key', 'comment'], details.columns.map((column) => [
+        column.name,
+        column.type,
+        column.nullable ? 'yes' : 'no',
+        column.default,
+        column.primaryKey ? 'PK' : null,
+        column.comment,
+    ]));
+    const indexes = result(['index', 'definition', 'size'], details.indexes.map((index) => [index.name, index.definition, formatBytes(index.bytes)]));
+    const constraints = result(['constraint', 'kind', 'definition'], details.constraints.map((constraint) => [
+        constraint.name,
+        constraint.kind,
+        constraint.definition,
+    ]));
+    if (format === 'csv') {
+        options.out(formatResult(columns, 'csv'));
+        return 0;
+    }
+    options.out(`Table ${tableLabel(details.table)}\n\n${formatResult(columns, 'table')}`);
+    if (details.indexes.length > 0)
+        options.out(`\nIndexes\n${formatResult(indexes, 'table')}`);
+    if (details.constraints.length > 0) {
+        options.out(`\nConstraints\n${formatResult(constraints, 'table')}`);
+    }
+    return 0;
+}
+const orderOf = (flags) => flags.order
+    ? flags.order
+        .split(',')
+        .map((column) => ({ column: column.trim(), descending: flags.desc ?? false }))
+    : [];
+async function rows(options, session) {
+    const format = formatOf(options.flags);
+    const table = tableArgument(options, session);
+    const limit = options.flags.limit ?? DEFAULT_PAGE_SIZE;
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new UsageError('--limit must be at least 1');
+    const offset = options.flags.offset ?? 0;
+    if (!Number.isInteger(offset) || offset < 0)
+        throw new UsageError('--offset must be 0 or more');
+    const page = await browseRows(session, table, { limit, offset, orderBy: orderOf(options.flags) });
+    options.out(formatResult(page, format));
+    return 0;
+}
+async function sqlOf(options) {
+    const [given] = options.args;
+    if (given !== undefined && given !== '-')
+        return given;
+    if (given === undefined && options.stdinIsTTY) {
+        throw new UsageError('query needs SQL: query --env <name> "<sql>", or pipe it in');
+    }
+    return options.readStdin();
+}
+async function query(options, session, entry, sql) {
+    const format = formatOf(options.flags);
+    const maxRows = options.flags.maxRows ?? DEFAULT_MAX_ROWS;
+    const started = performance.now();
+    let ran;
+    try {
+        ran = await session.run(sql, [], { maxRows });
+    }
+    catch (error) {
+        const message = describeQueryError(error);
+        options.services.store.recordQuery({
+            envName: entry.name,
+            sql,
+            durationMs: performance.now() - started,
+            error: message,
+        });
+        options.err(`psql-explorer: ${message}\n`);
+        return 1;
+    }
+    options.services.store.recordQuery({
+        envName: entry.name,
+        sql,
+        durationMs: ran.durationMs,
+        rowCount: ran.rowCount ?? ran.rows.length,
+    });
+    if (ran.columns.length > 0)
+        options.out(formatResult(ran, format));
+    else if (format === 'json')
+        json(options, { command: ran.command, rowCount: ran.rowCount });
+    else if (format === 'table')
+        options.out(`${commandSummary(ran)}\n`);
+    if (ran.truncated) {
+        options.err(`psql-explorer: showing the first ${ran.rows.length} rows; raise --max-rows for more\n`);
+    }
+    return 0;
+}
+async function info(options, session, entry) {
+    const format = formatOf(options.flags);
+    const server = await serverInfo(session);
+    if (format === 'json') {
+        json(options, { environment: entry.name, ...server });
+        return 0;
+    }
+    options.out(formatResult(result(['setting', 'value'], [
+        ['environment', entry.name],
+        ['server', server.version],
+        ['database', server.database],
+        ['user', server.user],
+        ['size', formatBytes(server.databaseBytes)],
+        ['started', server.startedAt],
+        ['read only', server.readOnly ? 'yes' : 'no'],
+        ['time zone', server.timeZone],
+        ['search path', server.searchPath],
+        ['encoding', server.encoding],
+    ]), format));
+    return 0;
+}
+const indent = (text, prefix) => text
+    .split('\n')
+    .map((line) => `${prefix}${line}`)
+    .join('\n');
+/** One object that differs, as text: its parts with each side's value, or a line by line diff. */
+function describeChange(change, a, b) {
+    const name = change.kind === 'schema' || change.kind === 'extension'
+        ? change.name
+        : `${change.schema}.${change.name}`;
+    const status = change.status === 'only-a'
+        ? `only in ${a}`
+        : change.status === 'only-b'
+            ? `only in ${b}`
+            : 'differs';
+    const out = [`${change.kind} ${name}: ${status}`];
+    const width = Math.max(a.length, b.length) + 1;
+    for (const part of change.parts) {
+        const value = part.a ?? part.b ?? '';
+        const label = change.status === 'changed' && (part.a === null || part.b === null)
+            ? `${part.part}, only in ${part.a === null ? b : a}`
+            : part.part;
+        if (change.status !== 'changed' || part.a === null || part.b === null) {
+            out.push(value.includes('\n') ? `  ${label}:\n${indent(value, '      ')}` : `  ${label}: ${value}`);
+        }
+        else if (part.lines) {
+            out.push(`  ${part.part}  (- ${a}, + ${b})`);
+            for (const line of part.lines) {
+                out.push(`    ${line.side === 'a' ? '-' : line.side === 'b' ? '+' : ' '} ${line.text}`);
+            }
+        }
+        else {
+            out.push(`  ${part.part}`, `    ${`${a}:`.padEnd(width)} ${part.a}`, `    ${`${b}:`.padEnd(width)} ${part.b}`);
+        }
+    }
+    return out.join('\n');
+}
+async function diff(options) {
+    const format = formatOf(options.flags);
+    const entry = environmentFor(options);
+    if (!options.flags.with)
+        throw new UsageError('diff needs --with <name>, the environment to compare with');
+    const other = environmentFor(options, options.flags.with);
+    const { schema, withSchema } = options.flags;
+    const session = await connect(options, entry);
+    let found;
+    try {
+        const otherSession = await connect(options, other);
+        try {
+            found = await compareSchemas(session, otherSession, { schema, withSchema });
+        }
+        finally {
+            await otherSession.close();
+        }
+    }
+    finally {
+        await session.close();
+    }
+    if (format === 'json') {
+        json(options, { a: entry.name, b: other.name, ...found });
+        return 0;
+    }
+    if (format === 'csv') {
+        options.out(formatResult(result(['schema', 'kind', 'name', 'status', 'part', entry.name, other.name], found.changes.flatMap((change) => (change.parts.length > 0 ? change.parts : [{ part: null, a: null, b: null }]).map((part) => [
+            change.schema,
+            change.kind,
+            change.name,
+            change.status,
+            part.part,
+            part.a,
+            part.b,
+        ]))), 'csv'));
+        return 0;
+    }
+    for (const change of found.changes)
+        options.out(`${describeChange(change, entry.name, other.name)}\n\n`);
+    const differ = found.changes.length;
+    options.out(differ === 0
+        ? `${entry.name} and ${other.name} are the same (${found.same} objects).\n`
+        : `${differ} ${differ === 1 ? 'object differs' : 'objects differ'}, ${found.same} the same.\n`);
+    return 0;
+}
+function history(options) {
+    const format = formatOf(options.flags);
+    const entry = environmentFor(options);
+    const records = options.services.store.historyFor(entry.name, options.flags.limit ?? 50);
+    if (format === 'json')
+        json(options, records);
+    else {
+        options.out(formatResult(result(['at', 'duration', 'rows', 'sql', 'error'], records.map((record) => [
+            record.at.slice(0, 19).replace('T', ' '),
+            formatDuration(record.durationMs),
+            text(record.rowCount),
+            record.sql,
+            record.error,
+        ])), format));
+    }
+    return 0;
+}
+/** Runs one command; never throws. 0 done, 1 failed, 2 wrong command line. */
+export async function runCommand(options) {
+    try {
+        switch (options.command) {
+            case 'envs':
+                return envs(options);
+            case 'history':
+                return history(options);
+            case 'schemas':
+                return await withSession(options, (session) => schemas(options, session));
+            case 'tables':
+                return await withSession(options, (session) => tables(options, session));
+            case 'describe':
+                return await withSession(options, (session) => describe(options, session));
+            case 'rows':
+                return await withSession(options, (session) => rows(options, session));
+            case 'query': {
+                // Read before connecting, so a wrong command line costs no login.
+                formatOf(options.flags);
+                const sql = (await sqlOf(options)).trim();
+                if (!sql)
+                    throw new UsageError('the SQL is empty');
+                return await withSession(options, (session, entry) => query(options, session, entry, sql));
+            }
+            case 'info':
+                return await withSession(options, (session, entry) => info(options, session, entry));
+            case 'diff':
+                return await diff(options);
+        }
+    }
+    catch (error) {
+        const message = error instanceof UsageError ? error.message : describeQueryError(error);
+        options.err(`psql-explorer: ${message || messageOf(error)}\n`);
+        return error instanceof UsageError ? 2 : 1;
+    }
+}

package/dist/commands/terminal-prompt.js

@@ -0,0 +1,68 @@
+import { ResolveError } from '../config/resolvers/index.js';
+/**
+ * Asks on the terminal, for commands run by a person: the question goes to stderr so stdout stays
+ * the command's output, and a secret is read without echo. One question at a time.
+ */
+export function createTerminalPrompter(input = process.stdin, output = process.stderr) {
+    let queue = Promise.resolve();
+    const ask = ({ envName, field, masked, challenge, signal }) => new Promise((resolve, reject) => {
+        let answer = '';
+        const wasRaw = input.isRaw;
+        const finish = (error) => {
+            input.off('data', onData);
+            signal?.removeEventListener('abort', onAbort);
+            input.setRawMode?.(wasRaw);
+            input.pause();
+            output.write('\n');
+            if (error)
+                reject(error);
+            else
+                resolve(answer);
+        };
+        const onAbort = () => {
+            finish(new ResolveError(envName, field, 'cancelled'));
+        };
+        const onData = (chunk) => {
+            for (const char of chunk.toString('utf8')) {
+                if (char === '\r' || char === '\n') {
+                    if (answer)
+                        finish();
+                    return;
+                }
+                if (char === '\u0003' || char === '\u001b') {
+                    finish(new ResolveError(envName, field, 'cancelled'));
+                    return;
+                }
+                if (char === '\u007f' || char === '\b') {
+                    if (answer) {
+                        answer = [...answer].slice(0, -1).join('');
+                        output.write('\b \b');
+                    }
+                    continue;
+                }
+                if (char < ' ')
+                    continue;
+                answer += char;
+                output.write(masked ? '*' : char);
+            }
+        };
+        if (signal?.aborted) {
+            reject(new ResolveError(envName, field, 'cancelled'));
+            return;
+        }
+        output.write(challenge === undefined
+            ? `${envName}.${field} (${masked ? 'secret' : 'value'}): `
+            : `${envName} is protected. Type "${challenge}" to continue: `);
+        input.setRawMode?.(true);
+        input.resume();
+        input.on('data', onData);
+        signal?.addEventListener('abort', onAbort);
+    });
+    return {
+        ask(request) {
+            const next = queue.then(() => ask(request), () => ask(request));
+            queue = next.catch(() => undefined);
+            return next;
+        },
+    };
+}