@kazurolabs/psql-explorer 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kazuro Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,295 @@
-# Temporary Holding Version
+# psql-explorer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Explore your Postgres databases from the terminal: browse schemas and tables, page through rows,
+look at columns, indexes and constraints, and run SQL, in an interactive TUI or from the command
+line. It is in the spirit of pgweb, without a browser.
+
+A team shares one set of environments without a database of its own: the config is a folder of
+small YAML files, kept in a directory or in HashiCorp Vault, and every password is looked up when
+it is needed (from Vault, an environment variable, a file, a prompt, ...). Production environments
+are opened **read only** by default, so nothing typed there can change data.
+
+> **Disclaimer:** psql-explorer is under active development and has not reached a stable release.
+> It connects to real databases, including production ones, and runs the SQL you give it. Check
+> which environment you are in, keep production read only, and expect breaking changes between
+> versions. It is provided as is, without warranty (see [LICENSE](LICENSE)).
+
+## Requirements
+
+- Node.js 22.13 or newer
+- PostgreSQL databases
+- An interactive terminal for the TUI. The commands (`tables`, `query`, ...) need none.
+
+## Install and run
+
+```sh
+npx @kazurolabs/psql-explorer             # once, without installing
+npm i -g @kazurolabs/psql-explorer        # or install the psql-explorer command
+```
+
+### Quick start
+
+```sh
+export PSQL_EXPLORER_ENVIRONMENTS=vault:secret/data/psql-explorer   # or a directory
+export VAULT_ADDR=https://vault.example.com:8200
+vault login                                                          # or VAULT_TOKEN, see below
+psql-explorer
+```
+
+Pick an environment and press `Enter`. Without a shared config psql-explorer still starts, and `n`
+saves your own connections.
+
+## Web UI
+
+```sh
+psql-explorer --web [--port 7878] [--no-open]  # serves the UI and API on http://127.0.0.1:7878 and opens it
+```
+
+The UI lives in `web/` (Vite, React, Tailwind, shadcn/ui) and is powered by the same config,
+Vault lookups and read-only rules as the TUI. A value the config says to `prompt` for (a password, say) is asked for in a dialog in the page, and remembered until the server stops. Picking an environment opens its database: the schemas on the left open to
+their tables, views, functions, sequences and types, and the one you pick is shown on the right
+(columns, indexes, constraints, definition and rows for a table; the source of a function; and so on).
+Every view has an address of its own, e.g. `#/staging/table/app/users`. The server listens on loopback only. From a checkout, `npm run dev:web` starts the API and Vite with hot reload together (run
+`npm run install:web` once first), and `npm run build` compiles the CLI and builds `web/dist`.
+
+## Commands
+
+```sh
+psql-explorer                                   # the interactive TUI
+psql-explorer envs                              # the environments you can use
+psql-explorer schemas  --env staging
+psql-explorer tables   --env staging [--schema app]
+psql-explorer describe --env staging users      # or app.users
+psql-explorer rows     --env staging users --limit 20 --order created_at --desc
+psql-explorer query    --env staging "select count(*) from orders"
+echo "select now()" | psql-explorer query --env staging
+psql-explorer info     --env staging
+psql-explorer history  --env staging
+psql-explorer configgen:file                    # a commented example environment file
+psql-explorer configgen:vault
+psql-explorer secret:set prod-password          # for `source: stored`; asks, or reads stdin
+psql-explorer secret:delete prod-password
+```
+
+Every command prints a table like psql's; `--format csv` or `--format json` (or `--json`) give
+output for other tools. In JSON, numbers that fit a JavaScript number, booleans and `json`/`jsonb`
+values are themselves; `bigint`, `numeric` and everything else are the text Postgres sent, so no
+digit is lost.
+
+| Option            | Used for                                                                    |
+| ----------------- | --------------------------------------------------------------------------- |
+| `--config <base>` | the shared config's base path; default `$PSQL_EXPLORER_ENVIRONMENTS`        |
+| `--env <name>`    | the environment: a shared one, else a local connection of that name         |
+| `--schema <name>` | `tables`, `describe`, `rows`: the schema; default the environment's         |
+| `--format <f>`    | `table` (default), `csv` or `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` for descending     |
+| `--max-rows <n>`  | `query`: read at most this many rows (default 1000), the rest are not read  |
+| `--timeout <s>`   | the server cancels a statement after this many seconds (default 30, 0 none) |
+
+Exit codes: `0` done, `1` failed (the reason is on stderr), `2` wrong command line. A value the
+config says to `prompt` for is asked for on the terminal (a secret without echo); with no terminal
+the command fails and names the value.
+
+`query` runs one statement at a time. Each statement is kept in the history of that environment
+(in your local data, see below), with how long it took and how many rows it returned.
+
+## The TUI
+
+The **Environments** screen lists the shared environments and your local connections, with their
+tier, address, TLS mode and whether they are read only. `Enter` explores one, `t` tests the
+connection, `n` adds a local connection, `e` and `d` edit and delete one.
+
+Exploring an environment has four tabs (`1`–`4`, or `Tab`):
+
+1. **Tables** — the tables, views and materialized views of a schema, with row estimates, sizes
+   and comments. `/` filters, `s` picks another schema (remembered per environment), `Enter` opens
+   a table on its **Rows** (a page at a time, sorted by the primary key), its **Structure**
+   (columns, types, defaults) and its **Indexes & constraints**; `Tab` switches between them.
+   In the rows, `n`/`p` page, `o` sorts by the selected column (again for descending, a third time
+   for the default), `c` counts the rows exactly, and `Enter` shows a row field by field.
+2. **Query** — type a statement and press `Enter`; `↑`/`↓` recall earlier ones. The result is a
+   grid like the rows. `Esc` leaves the editor, `e` returns to it, `r` runs it again.
+3. **History** — what was run against this environment, newest first. `Enter` puts a statement
+   back in the Query tab.
+4. **Info** — the server version, database size and session settings, and the other connections
+   to the database.
+
+In every grid the arrow keys (or `h` `j` `k` `l`) move a cell at a time, `PgUp`/`PgDn` a page,
+`g`/`G` to the first and last row, `0`/`$` to the first and last column. `Esc` goes back, `q`
+quits (when not typing), and so does `Ctrl+C`.
+
+## Read only, and other safety
+
+- An environment with `readOnly: true` opens every session with
+  `default_transaction_read_only = on`, so the server refuses `INSERT`, `UPDATE`, `DELETE`, DDL
+  and the like. `readOnly` defaults to `protected`, which defaults to true for the `production`
+  tier. The header shows **READ ONLY**. This guards against mistakes; it is not a permission
+  system, so give people a database role that can only read where it matters (Vault's database
+  secrets engine is a good way to hand those out, see below).
+- An environment with `confirm: true` makes you type back two random words (for example
+  `maple ticket`) before it is opened, in the TUI, the web UI and on the terminal, so a protected
+  environment is never entered by accident, even when its password is stored in the config.
+  `confirm` defaults to `protected`; set `confirm: false` to turn it off. It is asked once per run
+  of the program, nothing is looked up before it is answered, and it fails (rather than skips)
+  when nobody can be asked, e.g. in a script with no terminal. The web UI also shows a banner
+  above the SQL box on a protected environment.
+- In the web UI, the SQL box of a protected, read only environment has a switch at its top right.
+  Turning it on asks for two random words again (always, whatever `confirm` says), then every
+  connection of that environment is opened read write until you switch it off or stop the server.
+  The banner turns red and pulses while it is on. Turning it off needs no words.
+- Every statement has a time limit (`statement_timeout`, 30 s unless `--timeout` says otherwise),
+  and a query reads at most `--max-rows` rows (1000 in the TUI), so a `SELECT *` on a big table
+  does not fill your memory.
+- Values are shown as the text Postgres sends: no time zone conversion, no rounding.
+- Short-lived credentials and certificates issued by Vault are revoked when you leave the
+  environment or the command ends.
+
+## Configuration
+
+### Environment variables
+
+| Variable                           | Used for                                                                                         |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `PSQL_EXPLORER_ENVIRONMENTS`       | the shared config's base path, a directory or `vault:<path>`; `--config` wins                    |
+| `PSQL_EXPLORER_CONFIG`             | the directory holding `explorer.db` (local connections, stored secrets, settings, query history) |
+| `XDG_CONFIG_HOME`                  | without `PSQL_EXPLORER_CONFIG`, `explorer.db` is in `$XDG_CONFIG_HOME/psql-explorer`             |
+|                                    | (else `~/.config/psql-explorer`)                                                                 |
+| `VAULT_ADDR`                       | Vault's address (required for anything in Vault)                                                 |
+| `VAULT_TOKEN`                      | the Vault token to use                                                                           |
+| `VAULT_ROLE_ID`, `VAULT_SECRET_ID` | log in to Vault through AppRole                                                                  |
+| `VAULT_JWT`, `VAULT_ROLE`          | log in to Vault with a JWT / OIDC token                                                          |
+| `VAULT_NAMESPACE`                  | the Vault Enterprise namespace                                                                   |
+| any name                           | read by an environment's `source: env` values, for example `STAGING_DB_PASSWORD`                 |
+
+Empty values count as unset. `explorer.db` is created readable by its owner only.
+
+### Shared configuration
+
+Environments shared by a team live under a **base path**, given with `--config <base>` or
+`$PSQL_EXPLORER_ENVIRONMENTS`. It holds one folder per environment, each with an `explorer.yaml`:
+
+```
+<base>/staging/explorer.yaml       one environment; the folder name is its name
+<base>/production/explorer.yaml
+```
+
+The base path is a directory (a git checkout, a shared drive, ...) or Vault:
+
+```sh
+psql-explorer --config ~/team/explorer-config
+psql-explorer --config vault:secret/data/psql-explorer   # a KV v2 "<mount>/data/<path>"
+```
+
+Environments are found by listing the base path. A folder without an `explorer.yaml` is ignored.
+An environment file that is wrong is reported (on the Environments screen, or on stderr) and left
+out; the others still load.
+
+#### Config in Vault
+
+In Vault each environment is the `explorer.yaml` key of a secret below the base path:
+`secret/data/psql-explorer/staging` is the `staging` environment. psql-explorer lists
+`secret/metadata/psql-explorer` to find them, so **what a person sees follows their Vault policy**:
+an environment they may not read is simply not in their list.
+
+```sh
+vault kv put secret/psql-explorer/staging explorer.yaml=@staging.yaml
+```
+
+```hcl
+path "secret/metadata/psql-explorer"         { capabilities = ["list"] }
+path "secret/data/psql-explorer/staging"     { capabilities = ["read"] }   # one per environment
+# or: path "secret/data/psql-explorer/*"     { capabilities = ["read"] }
+```
+
+### An environment file
+
+`psql-explorer configgen:file` (or `configgen:vault`) prints a fully commented example. In short:
+
+```yaml
+tier: production # production | reference | demo | development | local
+protected: true # optional; default: tier is production
+readOnly: true # optional; default: protected
+confirm: true # optional; default: protected (type two random words to open it)
+host: db.prod.internal
+port: 5432
+database: app
+schema: app # optional; where browsing starts, and first on the search_path; default public
+username: readonly
+password: # or `auth: none` for a server that takes no password
+  source: vault
+  value: secret/data/db/prod#password
+tls:
+  mode: verify-full # disable | require | verify-ca | verify-full
+  ca: {source: file, value: ./ca.pem}
+```
+
+Any of `host`, `port`, `database`, `schema`, `username`, `password` and the TLS `ca`, `cert`,
+`key` and `keyPassphrase` can be written as plain text or as a `source` and a `value`:
+
+| `source`              | the value is                                                                       |
+| --------------------- | ---------------------------------------------------------------------------------- |
+| `plaintext`, `inline` | the text in `value`                                                                |
+| `env`                 | the environment variable named in `value`                                          |
+| `file`                | the content of the file in `value`, relative to the environment's folder           |
+| `stored`              | a secret of that name in your local store (`psql-explorer secret:set <name>`)      |
+| `prompt`              | asked for when connecting (no `value`), and remembered until the program ends      |
+| `vault`               | a key of a KV v2 secret: `value: <data path>#<key>`, e.g. `secret/data/db/prod#pw` |
+
+Vault can also issue the login and the client certificate:
+
+```yaml
+credentials: # instead of username and password
+  source: vault-database
+  value: database/creds/readonly
+tls:
+  mode: verify-full
+  client: # instead of cert and key (and ca, unless given)
+    source: vault-pki
+    value: pki/issue/psql-explorer
+    commonName: psql-explorer
+```
+
+### Vault
+
+Vault needs `VAULT_ADDR`, and a token from the first of: `VAULT_TOKEN`; an AppRole login with
+`VAULT_ROLE_ID` and `VAULT_SECRET_ID`; a JWT login with `VAULT_JWT` and `VAULT_ROLE`; the
+`~/.vault-token` the `vault` CLI writes on `vault login`. Secrets are read each time they are
+needed and never kept, so a rotated password is picked up at once. An expired token is reported
+as such, with a reminder to `vault login`.
+
+### Local connections
+
+Press `n` on the Environments screen to save a connection of your own (host, port, database,
+username, password, schema and SSL). They live in `explorer.db` with the password unencrypted,
+in a file only you can read, are never read only, and can be used by name with `--env`.
+
+## Development
+
+```sh
+npm install
+npm run build        # compile src/ to dist/ with tsc
+node dist/cli.js     # run the built CLI
+npm test             # run the tests (Vitest; builds dist/ first)
+npm run lint         # typecheck + ESLint + Prettier check
+npm run format       # apply Prettier formatting
+```
+
+`npm run dev` starts psql-explorer against a demo: a `demo_shop` database (customers, products,
+orders, a 200,000-row `page_views` table with no index on `customer_id` for trying Explain, a view,
+a materialized view and an `audit` schema) on the `psql-explorer-pg` container
+(port 55440, started if it is not running; set `DEMO_PG_URL` to use another server), and a shared
+config in `.demo/config` with a read-write, a read-only and a protected environment. Its data
+directory is `.demo/data`, so your real `~/.config/psql-explorer` is untouched.
+`npm run dev:web` starts the web UI against the same demo. `npm run dev:reset` and
+`npm run dev:web:reset` build the demo again. `npm run dev:plain` runs the TUI without it.
+
+The tests that need a real Postgres run when `PSQL_EXPLORER_TEST_PG_URL` is set, and are skipped
+otherwise:
+
+```sh
+PSQL_EXPLORER_TEST_PG_URL=postgres://postgres:postgres@localhost:55440/app npm test
+```
+
+Each run creates a schema of its own (`explorer_test_<random>`) and drops it afterwards.

package/dist/app.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useState, useSyncExternalStore } from 'react';
+import { Box, useApp, useInput, useStdin } from 'ink';
+import { screens as defaultScreens, } from './screens/index.js';
+import PromptModal from './screens/prompt-modal.js';
+import { useTerminalSize } from './screens/terminal.js';
+const noSubscribe = () => () => undefined;
+const noPrompt = () => undefined;
+export default function App({ version, services, initialScreen = 'splash', initialParams, fullScreen = false, screens = defaultScreens, }) {
+    const [route, setRoute] = useState({
+        name: initialScreen,
+        params: initialParams,
+        key: 0,
+    });
+    const { exit } = useApp();
+    const { columns, rows } = useTerminalSize();
+    const { isRawModeSupported } = useStdin();
+    const navigate = useCallback((name, ...[params]) => {
+        setRoute((previous) => ({ name, params, key: previous.key + 1 }));
+    }, []);
+    const entry = screens[route.name];
+    const { prompts } = services;
+    const prompt = useSyncExternalStore(prompts ? prompts.subscribe : noSubscribe, prompts ? prompts.current : noPrompt);
+    const screenInput = isRawModeSupported && !prompt;
+    // Global quit key, off on screens that take text input; Ctrl+C is handled by Ink (exitOnCtrlC).
+    useInput((input) => {
+        if (input === 'q')
+            exit();
+    }, { isActive: screenInput && !entry.capturesInput });
+    // The registry ties each component to its own params type; the route carries the params that
+    // navigate() type-checked for this screen, so widening here is safe.
+    const Screen = entry.component;
+    const screen = (_jsx(Screen, { version: version, navigate: navigate, params: route.params, services: services, isInputActive: screenInput }, route.key));
+    const modal = prompt && (_jsx(PromptModal, { prompt: prompt, isInputActive: isRawModeSupported }, `${prompt.envName}.${prompt.field}`));
+    if (!fullScreen) {
+        return (_jsxs(_Fragment, { children: [screen, modal] }));
+    }
+    return (_jsxs(Box, { width: columns, height: rows, flexDirection: "column", justifyContent: prompt ? 'center' : 'flex-start', children: [_jsx(Box, { display: prompt ? 'none' : 'flex', flexDirection: "column", flexGrow: 1, children: screen }), modal] }));
+}

package/dist/cli.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+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
+	  $ 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 --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.
+	  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)
+	  --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
+
+	Run without a command to start the interactive TUI.
+`, {
+    importMeta: import.meta,
+    flags: {
+        config: { type: 'string' },
+        env: { 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' },
+        open: { type: 'boolean', default: true },
+    },
+});
+// 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,
+        groups: vault.groups,
+        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();
+        void vault.groups.releaseAll().finally(() => {
+            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),
+            groups: vault.groups,
+            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,
+        });
+    }
+    // Credentials and certificates issued for this command end with it.
+    await vault.groups.releaseAll();
+    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),
+    groups: vault.groups,
+    prompts,
+    openSession,
+};
+services.startup = createStartup({ services, base: cli.flags.config, vault });
+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();
+// Short-lived credentials and certificates issued for this session end with it.
+await vault.groups.releaseAll();
+store.close();