@kazurolabs/psql-explorer 0.0.0-stage → 0.3.0

package/dist/cli.js

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { render } from 'ink';
+import meow from 'meow';
+import App from './app.js';
+import { createVaultClient, defaultRegistry, PromptRequiredError, } from './config/resolvers/index.js';
+import { loadConfig } from './config/load.js';
+import { dataDir } from './db/paths.js';
+import { openStore } from './db/store.js';
+import { testConnection } from './db/tester.js';
+import { configgen } from './commands/configgen.js';
+import { commandNames, isCommand, runCommand } from './commands/explore.js';
+import { createTerminalPrompter } from './commands/terminal-prompt.js';
+import { openSession } from './explorer/session.js';
+import { createPromptQueue } from './prompts.js';
+import { createStartup } from './startup.js';
+import { createWebServer, DEFAULT_WEB_PORT, listen, openBrowser } from './web/server.js';
+// meow reads package.json via importMeta, so the version and description have
+// a single source of truth. It handles --help and --version (exit 0) itself.
+const cli = meow(`
+	Usage
+	  $ psql-explorer                                   start the interactive TUI (also serves the web UI; --port picks its port)
+	  $ psql-explorer envs
+	  $ psql-explorer schemas  --env <name>
+	  $ psql-explorer tables   --env <name> [--schema <schema>]
+	  $ psql-explorer describe --env <name> <table>
+	  $ psql-explorer rows     --env <name> <table> [--limit 100] [--offset 0] [--order <col>] [--desc]
+	  $ psql-explorer query    --env <name> "<sql>"         (or "-", or pipe the SQL in)
+	  $ psql-explorer info     --env <name>
+	  $ psql-explorer history  --env <name>
+	  $ psql-explorer diff     --env <name> --with <name> [--schema <schema>] [--with-schema <schema>]
+	  $ psql-explorer --web [--port 7878] [--no-open]     serve the web UI and open it
+	  $ psql-explorer web                                same as --web
+	  $ psql-explorer configgen:file
+	  $ psql-explorer configgen:vault
+	  $ psql-explorer secret:set <name>                  (asks for it, or pipe it in)
+	  $ psql-explorer secret:delete <name>
+
+	Commands
+	  envs             List the environments: the shared ones and your local connections.
+	  schemas          List the schemas of the database.
+	  tables           List the tables and views of a schema, with row estimates and sizes.
+	  describe         Show a table's columns, indexes and constraints.
+	  rows             Print a page of a table's rows.
+	  query            Run one SQL statement and print what it returns. On a read-only
+	                   environment anything that would change data is refused by the server.
+	  info             Show the server version, database size and session settings.
+	  history          The statements run with query or the TUI, newest first.
+	  diff             Compare the structure of two environments' databases: tables,
+	                   columns, indexes, constraints, triggers, policies, views, functions,
+	                   sequences, types and extensions. All schemas, or the one --schema names.
+	  web              Serve the web UI and its API on http://127.0.0.1:<port> until stopped.
+	  configgen:file   Print a fully commented example environment kept in a directory.
+	  configgen:vault  Print the same for one kept in Vault.
+	  secret:set       Keep a secret in the local store, for config values written as
+	                   source: stored. secret:delete removes it.
+
+	Options
+	  --config <base>  Where the shared config lives (default: $PSQL_EXPLORER_ENVIRONMENTS): a
+	                   directory, or vault:<KV v2 path> such as vault:secret/data/psql-explorer.
+	                   It holds one <environment>/explorer.yaml per environment.
+	  --env <name>     The environment: a shared one, or a local connection by name
+	  --schema <name>  tables, describe, rows: the schema (default: the environment's);
+	                   diff: compare only this schema
+	  --with <name>    diff: the environment to compare --env with
+	  --with-schema <name>
+	                   diff: the schema on the --with side, when it is named differently
+	  --format <f>     table (default), csv or json
+	  --json           Same as --format json
+	  --limit <n>      rows: rows per page (default 100); history: how many (default 50)
+	  --offset <n>     rows: rows to skip
+	  --order <cols>   rows: sort by these columns, comma separated
+	  --desc           rows: sort descending
+	  --max-rows <n>   query: read at most this many rows (default 1000)
+	  --timeout <s>    Cancel a statement after this many seconds (default 30, 0 for none)
+	  --web            Start the web UI instead of the TUI (same as the web command)
+	  --no-open        web: do not open the browser
+	  --port <n>       web: the port to listen on (default 7878; the next free one is used if taken)
+	  --help           Show this help
+	  --version        Show the version
+	  --relnotes       Show the release notes
+
+	Run without a command to start the interactive TUI.
+`, {
+    importMeta: import.meta,
+    flags: {
+        config: { type: 'string' },
+        env: { type: 'string' },
+        with: { type: 'string' },
+        withSchema: { type: 'string' },
+        schema: { type: 'string' },
+        format: { type: 'string' },
+        json: { type: 'boolean' },
+        limit: { type: 'number' },
+        offset: { type: 'number' },
+        order: { type: 'string' },
+        desc: { type: 'boolean' },
+        maxRows: { type: 'number' },
+        timeout: { type: 'number' },
+        port: { type: 'number' },
+        web: { type: 'boolean' },
+        relnotes: { type: 'boolean' },
+        open: { type: 'boolean', default: true },
+    },
+});
+// RELEASES.md ships next to dist, like web/dist, and needs neither the database nor a config.
+if (cli.flags.relnotes) {
+    try {
+        process.stdout.write(readFileSync(join(import.meta.dirname, '..', 'RELEASES.md'), 'utf8'));
+        process.exit(0);
+    }
+    catch {
+        process.stderr.write('psql-explorer: the release notes are missing from this install\n');
+        process.exit(1);
+    }
+}
+// Prints an example config and needs neither the local database nor a config.
+const [command, ...args] = cli.input;
+if (command === 'configgen:file' || command === 'configgen:vault') {
+    process.stdout.write(configgen(command === 'configgen:file' ? 'file' : 'vault'));
+    process.exit(0);
+}
+const vault = createVaultClient();
+// Opened before the TTY check so a broken data dir is reported the same way everywhere.
+let store;
+try {
+    store = openStore(dataDir());
+}
+catch (error) {
+    process.stderr.write(`psql-explorer: ${error instanceof Error ? error.message : String(error)}\n` +
+        'Check the directory permissions, or set PSQL_EXPLORER_CONFIG to another directory.\n');
+    process.exit(1);
+}
+const readStdin = async () => {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+};
+// Secrets for `source: stored` values: they need the store but no config.
+if (command === 'secret:set' || command === 'secret:delete') {
+    const [name] = args;
+    let code = 0;
+    if (!name) {
+        process.stderr.write(`psql-explorer: ${command} needs the secret's name\n`);
+        code = 2;
+    }
+    else if (command === 'secret:delete') {
+        if (!store.deleteSecret(name)) {
+            process.stderr.write(`psql-explorer: there is no stored secret named "${name}"\n`);
+            code = 1;
+        }
+    }
+    else {
+        try {
+            const value = process.stdin.isTTY
+                ? await createTerminalPrompter().ask({ envName: 'secret', field: name, masked: true })
+                : // A trailing newline from echo or a file is not part of the secret.
+                    (await readStdin()).replace(/\r?\n$/, '');
+            if (value) {
+                store.setSecret(name, value);
+                process.stderr.write(`Stored secret ${name}\n`);
+            }
+            else {
+                process.stderr.write('psql-explorer: the secret is empty; nothing was stored\n');
+                code = 1;
+            }
+        }
+        catch {
+            process.stderr.write('psql-explorer: cancelled; nothing was stored\n');
+            code = 1;
+        }
+    }
+    store.close();
+    process.exit(code);
+}
+if (command === 'web' || (command === undefined && cli.flags.web)) {
+    const { config, error: configError } = await loadConfig({ base: cli.flags.config, vault });
+    const prompts = createPromptQueue();
+    const services = {
+        store,
+        tester: testConnection,
+        config,
+        configError,
+        // Questions are answered in the browser: the page polls /api/prompt and posts the answer.
+        resolvers: defaultRegistry(undefined, prompts, store, vault),
+        prompts,
+        openSession,
+    };
+    const server = createWebServer({
+        services,
+        staticDir: join(import.meta.dirname, '..', 'web', 'dist'),
+    });
+    try {
+        const requested = cli.flags.port ?? DEFAULT_WEB_PORT;
+        const address = await listen(server, requested);
+        const port = Number(new URL(address).port);
+        if (port !== requested) {
+            process.stderr.write(`psql-explorer: port ${requested} is in use, using port ${port} instead\n`);
+        }
+        process.stderr.write(`psql-explorer web UI on ${address} (Ctrl-C to stop)\n`);
+        if (cli.flags.open)
+            openBrowser(address);
+    }
+    catch (error) {
+        store.close();
+        process.stderr.write(`psql-explorer: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(1);
+    }
+    process.once('SIGINT', () => {
+        server.close();
+        store.close();
+        process.exit(0);
+    });
+    await new Promise(() => { });
+}
+if (command !== undefined) {
+    let code = 2;
+    if (!isCommand(command)) {
+        process.stderr.write(`psql-explorer: unknown command "${command}"; use one of: ${commandNames.join(', ')}\n`);
+    }
+    else {
+        const { config, error: configError } = await loadConfig({ base: cli.flags.config, vault });
+        // A person at a terminal can be asked for what the config says to prompt for.
+        const prompter = process.stdin.isTTY
+            ? createTerminalPrompter()
+            : { ask: ({ envName, field }) => Promise.reject(new PromptRequiredError(envName, field)) };
+        const services = {
+            store,
+            tester: testConnection,
+            config,
+            configError,
+            resolvers: defaultRegistry(undefined, prompter, store, vault),
+            openSession,
+        };
+        code = await runCommand({
+            services,
+            command,
+            args,
+            flags: cli.flags,
+            out: (text) => process.stdout.write(text),
+            err: (text) => process.stderr.write(text),
+            readStdin,
+            stdinIsTTY: process.stdin.isTTY === true,
+        });
+    }
+    store.close();
+    // Let piped output drain before exiting.
+    await new Promise((resolve) => process.stdout.write('', resolve));
+    process.exit(code);
+}
+// Ink needs raw-mode keyboard input; without a TTY it would crash, so fail clearly.
+if (!process.stdin.isTTY) {
+    store.close();
+    process.stderr.write('psql-explorer: the TUI needs a terminal (stdin is not a TTY).\n' +
+        'Run it directly in a terminal, or use a command such as query (see --help).\n');
+    process.exit(1);
+}
+const prompts = createPromptQueue();
+// The screen opens at once; reading the config (which may be in Vault) happens behind the splash
+// screen, which shows each step. It fills in `config` and `configError`. What is wrong with the
+// config is shown on the Environments screen (local connections still work, and so do the
+// environments that are fine).
+const services = {
+    store,
+    tester: testConnection,
+    resolvers: defaultRegistry(undefined, prompts, store, vault),
+    prompts,
+    openSession,
+    openUrl: openBrowser,
+};
+services.startup = createStartup({ services, base: cli.flags.config, vault });
+// The web UI is served from the same process, so the Environments screen can say where it is.
+// Questions it triggers are answered in the browser, so it gets a prompt queue of its own; the
+// config is the one the splash screen loads. Failing to start it never stops the TUI.
+const webPrompts = createPromptQueue();
+const webServices = {
+    store,
+    tester: testConnection,
+    resolvers: defaultRegistry(undefined, webPrompts, store, vault),
+    prompts: webPrompts,
+    openSession,
+    get config() {
+        return services.config;
+    },
+    get configError() {
+        return services.configError;
+    },
+};
+const webServer = createWebServer({
+    services: webServices,
+    staticDir: join(import.meta.dirname, '..', 'web', 'dist'),
+});
+try {
+    services.webUrl = await listen(webServer, cli.flags.port ?? DEFAULT_WEB_PORT);
+}
+catch {
+    webServer.close();
+}
+const app = render(_jsx(App, { version: cli.pkg.version ?? '0.0.0', fullScreen: true, services: services }), 
+// The app owns the whole terminal, and the shell's screen comes back when it exits.
+{ alternateScreen: true });
+await app.waitUntilExit();
+webServer.close();
+store.close();

package/dist/commands/configgen.js

@@ -0,0 +1,128 @@
+// `psql-explorer configgen:file` and `psql-explorer configgen:vault` print a fully commented
+// example environment file, ready to copy. Every key the loader accepts appears, optional ones
+// commented out.
+const sources = `A setting is plain text (\`host: db.prod.internal\`) or a source and a value:
+  source: plaintext | inline | env | file | stored | vault | prompt`;
+const access = `# production | reference | demo | development | local. Required.
+tier: production
+
+# Shown with a shield and in red. Optional, default: true for the production tier.
+protected: true
+
+# Open every session read only (default_transaction_read_only), so nothing run here can change
+# data. Optional, default: the value of protected.
+readOnly: true
+
+# Opening the environment first asks for two random words to be typed back, so it is never
+# entered by accident. Optional, default: the value of protected.
+confirm: true
+
+# Offer the web UI's Seed page, which fills tables with generated rows. Optional, default: true
+# for the development and local tiers, false otherwise.
+# seeder: false
+
+# Let the web UI's Design page run statements that create, alter and drop tables; without it the
+# page only previews the SQL. Optional, default: true for the development and local tiers, false
+# otherwise.
+# designer: false
+`;
+const fileEnvironment = `# One environment: <environment>/explorer.yaml below the base path.
+# Use with: psql-explorer --config <base path>   (or export PSQL_EXPLORER_ENVIRONMENTS=<base path>)
+# The environment is named after its folder: lower case letters, digits, - and _.
+# ${sources.replaceAll('\n', '\n# ')}
+# Unknown keys are an error.
+
+${access}
+# Where the database is. Required. Any of these can use a source instead of plain text.
+host: db.prod.internal
+port: 5432
+database: app
+
+# The schema browsing starts in. Optional, default: public
+# schema: app
+
+# Database login. Required.
+username: readonly
+
+# password (default) needs a password; none means the database takes no password.
+auth: password
+
+# Required when auth is password. Must be left out when auth is none.
+password:
+  source: file
+  value: ./password.txt # relative to this file's folder; the whole content, trimmed
+# Other ways to supply it:
+# password: s3cret                       # plain text, in the file itself
+# password: {source: env, value: DB_PASSWORD}   # an environment variable
+# password: {source: stored, value: prod-password}   # a secret kept in the local store
+# password: {source: prompt}   # asked for when connecting
+# password: {source: vault, value: "secret/data/db/prod#password"}   # a key of a Vault KV v2 secret
+
+# TLS. Optional, default: mode disable
+tls:
+  # disable | require | verify-ca | verify-full
+  mode: verify-full
+  # CA certificate (PEM text). Required for verify-ca and verify-full.
+  ca:
+    source: file
+    value: ./certs/ca.pem
+  # Client certificate and its private key, for mutual TLS. Give both or neither.
+  # cert:
+  #   source: file
+  #   value: ./certs/client.pem
+  # key:
+  #   source: file
+  #   value: ./certs/client-key.pem
+  # Only when the key is encrypted.
+  # keyPassphrase:
+  #   source: file
+  #   value: ./certs/client-key.pass
+`;
+const vaultEnvironment = `# One environment, stored as the explorer.yaml key of a secret below the base path:
+#   vault kv put secret/psql-explorer/production explorer.yaml=@production.yaml
+# Use with: psql-explorer --config vault:secret/data/psql-explorer
+# The environment is named after the last part of the secret's path: lower case letters,
+# digits, - and _. Who can read the secret decides who sees the environment.
+# ${sources.replaceAll('\n', '\n# ')}
+# \`file\` values are relative to the working directory here, not to a folder.
+# Unknown keys are an error.
+
+${access}
+# Where the database is. Required. Any of these can use a source instead of plain text.
+host:
+  source: vault
+  value: secret/data/db/prod#host # "<KV v2 data path>#<key>"
+port: 5432
+database: app
+
+# The schema browsing starts in. Optional, default: public
+# schema: app
+
+username: readonly
+auth: password # password (default) | none; none takes no password, so leave password out
+password: # required when auth is password
+  source: vault
+  value: secret/data/db/prod#password
+
+# TLS. Optional, default: mode disable
+tls:
+  # disable | require | verify-ca | verify-full
+  mode: verify-full
+  # CA certificate (PEM text). Required for verify-ca and verify-full.
+  ca:
+    source: vault
+    value: secret/data/db/prod#ca
+  # Client certificate and key, for mutual TLS. Give both or neither.
+  # cert:
+  #   source: vault
+  #   value: secret/data/db/prod#cert
+  # key:
+  #   source: vault
+  #   value: secret/data/db/prod#key
+  # keyPassphrase:        # only when the key is encrypted
+  #   source: vault
+  #   value: secret/data/db/prod#key-passphrase
+`;
+export function configgen(kind) {
+    return kind === 'file' ? fileEnvironment : vaultEnvironment;
+}