@kazurolabs/psql-explorer 0.0.0-stage → 0.1.0

package/dist/startup.js

@@ -0,0 +1,84 @@
+// What the app does before the first screen is usable: read the shared config (a directory, or
+// Vault). The splash screen shows each step as it happens. A step that cannot finish is reported,
+// never thrown: local connections work without any of it.
+import { environmentsVariable, loadConfig } from './config/load.js';
+import { vaultPrefix } from './config/source.js';
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
+export function createStartup(options) {
+    const { services } = options;
+    const load = options.load ?? loadConfig;
+    let steps = [];
+    let finished = false;
+    let running;
+    const listeners = new Set();
+    const emit = (next) => {
+        steps = next;
+        for (const listener of listeners)
+            listener();
+    };
+    const begin = (id, label) => {
+        emit([...steps, { id, label, state: 'running', startedAt: Date.now() }]);
+    };
+    const change = (id, patch) => {
+        emit(steps.map((step) => (step.id === id ? { ...step, ...patch } : step)));
+    };
+    async function readConfig(base) {
+        const inVault = base.startsWith(vaultPrefix);
+        begin('config', inVault
+            ? `Loading the config from Vault (${base.slice(vaultPrefix.length)})`
+            : `Loading the config from ${base}`);
+        try {
+            const result = await load({
+                base,
+                env: options.env,
+                vault: options.vault,
+                onProgress: (detail) => {
+                    change('config', { detail: `reading ${detail}` });
+                },
+            });
+            services.config = result.config;
+            services.configError = result.error;
+            const problems = result.error?.problems.length ?? 0;
+            if (!result.config) {
+                change('config', {
+                    state: 'failed',
+                    detail: result.error?.problems[0]?.message ?? 'nothing could be read',
+                });
+            }
+            else {
+                const found = plural(result.config.environments.length, 'environment');
+                change('config', {
+                    state: problems > 0 ? 'warn' : 'done',
+                    detail: problems > 0 ? `${found}, ${plural(problems, 'problem')}` : found,
+                });
+            }
+            return result;
+        }
+        catch (error) {
+            change('config', { state: 'failed', detail: messageOf(error) });
+            return {};
+        }
+    }
+    async function run() {
+        const base = options.base || (options.env ?? process.env)[environmentsVariable];
+        if (base)
+            await readConfig(base);
+        finished = true;
+        emit([...steps]);
+    }
+    return {
+        snapshot: () => steps,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        start: () => (running ??= run().catch(() => {
+            finished = true;
+            emit([...steps]);
+        })),
+        finished: () => finished,
+    };
+}

package/dist/web/server.js

@@ -0,0 +1,355 @@
+// The HTTP server behind `psql-explorer web`: a small JSON API over the same services the TUI and
+// the commands use, plus the built web UI (web/dist). It only listens on the loopback interface
+// and refuses requests whose Host is not loopback, so a web page cannot reach it by DNS rebinding.
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+import { ResolveError } from '../config/resolvers/index.js';
+import { addressOf, findEnvironment, forgetAnswers, listEnvironments } from '../environments.js';
+import { connectEntry, LoginError } from '../explorer/connect-entry.js';
+import { describeCatalog, describeErd, describeFunction, describeRelation, describeSequence, describeType, listObjects, listSchemas, serverInfo, } from '../explorer/catalog.js';
+import { explainQuery } from '../explorer/explain.js';
+import { browseRows, runPage } from '../explorer/rows.js';
+import { describeQueryError } from '../explorer/session.js';
+export const DEFAULT_WEB_PORT = 7878;
+const MAX_BODY_BYTES = 1_000_000;
+const contentTypes = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.ico': 'image/x-icon',
+    '.woff2': 'font/woff2',
+};
+/** A request that cannot be answered as sent: the status says why. */
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+const sendJson = (res, status, body) => {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+    res.end(JSON.stringify(body));
+};
+const requiredParam = (url, key) => {
+    const value = url.searchParams.get(key);
+    if (!value)
+        throw new HttpError(400, `${url.pathname.split('/').pop()} needs ?${key}=`);
+    return value;
+};
+const isLoopbackHost = (host) => {
+    if (!host)
+        return false;
+    const name = host.startsWith('[') ? host.slice(0, host.indexOf(']') + 1) : host.split(':')[0];
+    return name === 'localhost' || name === '127.0.0.1' || name === '[::1]';
+};
+async function readJson(req) {
+    if (!req.headers['content-type']?.startsWith('application/json')) {
+        throw new HttpError(415, 'send application/json');
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            throw new HttpError(413, 'request body is too large');
+        chunks.push(chunk);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new HttpError(400, 'the body is not valid JSON');
+    }
+}
+export function createWebServer(options) {
+    const { services } = options;
+    const staticDir = options.staticDir ? resolve(options.staticDir) : undefined;
+    const environmentNamed = (name) => {
+        const entry = findEnvironment(services, name);
+        if (!entry)
+            throw new HttpError(404, `no environment named "${name}"`);
+        return entry;
+    };
+    // Protected environments the person has switched to read write, by entry key. In memory only, so
+    // a restart is read only again.
+    const writable = new Set();
+    // One connection per request keeps the scaffold simple; pooling comes with the real UI.
+    async function withSession(name, work, signal) {
+        const entry = environmentNamed(name);
+        let session;
+        try {
+            session = await connectEntry(entry, services, {
+                signal,
+                ...(writable.has(entry.key) ? { readOnly: false } : {}),
+            });
+        }
+        catch (error) {
+            // What was typed was refused, so ask again next time instead of remembering it.
+            if (error instanceof LoginError)
+                forgetAnswers(entry, services);
+            throw error;
+        }
+        try {
+            return await work(session);
+        }
+        finally {
+            await session.close();
+            await services.groups?.release(entry.name);
+        }
+    }
+    async function api(req, url, signal) {
+        const withSessionFor = (name, work) => withSession(name, work, signal);
+        const parts = url.pathname.split('/').slice(2).map(decodeURIComponent);
+        const [resource, name, sub] = parts;
+        if (resource === 'prompt' && !name && req.method === 'GET') {
+            const pending = services.prompts?.current();
+            return {
+                prompt: pending
+                    ? {
+                        envName: pending.envName,
+                        field: pending.field,
+                        masked: pending.masked,
+                        ...(pending.challenge === undefined ? {} : { challenge: pending.challenge }),
+                    }
+                    : null,
+            };
+        }
+        if (resource === 'prompt' && !name && req.method === 'POST') {
+            const body = (await readJson(req));
+            const pending = services.prompts?.current();
+            // The question may have been answered elsewhere since the page last looked.
+            if (!pending || pending.envName !== body?.envName || pending.field !== body?.field) {
+                throw new HttpError(409, 'that question is no longer waiting for an answer');
+            }
+            if (body.value === null)
+                pending.cancel();
+            else if (typeof body.value === 'string' && body.value !== '')
+                pending.submit(body.value);
+            else
+                throw new HttpError(400, 'send {"value": "..."} or {"value": null} to cancel');
+            return {};
+        }
+        if (resource === 'envs' && !name && req.method === 'GET') {
+            return {
+                environments: listEnvironments(services).map((entry) => ({
+                    name: entry.name,
+                    source: entry.source,
+                    tier: entry.tier,
+                    protected: entry.protected,
+                    readOnly: entry.readOnly,
+                    address: addressOf(entry),
+                    tls: entry.tlsMode,
+                })),
+                error: services.configError?.message,
+            };
+        }
+        if (resource === 'envs' && name && sub === 'write' && (req.method === 'GET' || req.method === 'POST')) {
+            const entry = environmentNamed(name);
+            // Only a protected environment that is read only has anything to switch.
+            const available = entry.protected && entry.readOnly;
+            if (req.method === 'POST') {
+                const body = (await readJson(req));
+                if (typeof body?.enabled !== 'boolean')
+                    throw new HttpError(400, 'send {"enabled": true|false}');
+                if (!available)
+                    throw new HttpError(400, `${entry.name} is not a protected read only environment`);
+                if (!body.enabled)
+                    writable.delete(entry.key);
+                else if (!writable.has(entry.key)) {
+                    // Always asked, whatever `confirm` says: this is the step that allows changing data.
+                    const prompt = services.resolvers.get('prompt');
+                    if (!prompt)
+                        throw new HttpError(400, 'there is no way to ask for confirmation');
+                    try {
+                        await prompt.confirm({ envName: entry.name, interactive: true, signal, purpose: 'write' });
+                    }
+                    catch (error) {
+                        if (error instanceof ResolveError)
+                            throw new HttpError(400, error.message);
+                        throw error;
+                    }
+                    writable.add(entry.key);
+                }
+            }
+            return { available, enabled: writable.has(entry.key) };
+        }
+        if (resource === 'envs' && name && sub === 'schemas' && req.method === 'GET') {
+            return withSessionFor(name, (session) => listSchemas(session));
+        }
+        if (resource === 'envs' && name && sub === 'erd' && req.method === 'GET') {
+            const schema = requiredParam(url, 'schema');
+            return withSessionFor(name, (session) => describeErd(session, schema));
+        }
+        if (resource === 'envs' && name && sub === 'catalog' && req.method === 'GET') {
+            return withSessionFor(name, (session) => describeCatalog(session));
+        }
+        if (resource === 'envs' && name && sub === 'info' && req.method === 'GET') {
+            return withSessionFor(name, (session) => serverInfo(session));
+        }
+        if (resource === 'envs' && name && sub === 'objects' && req.method === 'GET') {
+            const schema = requiredParam(url, 'schema');
+            return withSessionFor(name, (session) => listObjects(session, schema));
+        }
+        if (resource === 'envs' && name && sub === 'object' && req.method === 'GET') {
+            const schema = requiredParam(url, 'schema');
+            const object = requiredParam(url, 'name');
+            const kind = requiredParam(url, 'kind');
+            const found = await withSessionFor(name, (session) => {
+                if (kind === 'table')
+                    return describeRelation(session, { schema, name: object });
+                if (kind === 'function') {
+                    return describeFunction(session, { schema, name: object, args: url.searchParams.get('args') ?? '' });
+                }
+                if (kind === 'sequence')
+                    return describeSequence(session, { schema, name: object });
+                if (kind === 'type')
+                    return describeType(session, { schema, name: object });
+                throw new HttpError(400, `unknown kind "${kind}"`);
+            });
+            if (!found)
+                throw new HttpError(404, `no ${kind} ${schema}.${object}`);
+            return found;
+        }
+        if (resource === 'envs' && name && sub === 'rows' && req.method === 'GET') {
+            const schema = requiredParam(url, 'schema');
+            const table = requiredParam(url, 'table');
+            const limit = Math.min(Math.max(Number(url.searchParams.get('limit')) || 100, 1), 1000);
+            const offset = Math.max(Number(url.searchParams.get('offset')) || 0, 0);
+            try {
+                return await withSessionFor(name, (session) => browseRows(session, { schema, name: table }, { limit, offset }));
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'query' && req.method === 'POST') {
+            const body = (await readJson(req));
+            if (typeof body?.sql !== 'string' || body.sql.trim() === '') {
+                throw new HttpError(400, 'send {"sql": "..."}');
+            }
+            const sql = body.sql;
+            const limit = Math.min(Math.max(Number(body.limit) || 100, 1), 1000);
+            const offset = Math.max(Math.floor(Number(body.offset)) || 0, 0);
+            try {
+                return await withSessionFor(name, (session) => runPage(session, sql, { limit, offset }));
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'explain' && req.method === 'POST') {
+            const body = (await readJson(req));
+            if (typeof body?.sql !== 'string' || body.sql.trim() === '') {
+                throw new HttpError(400, 'send {"sql": "..."}');
+            }
+            const sql = body.sql;
+            try {
+                return { plan: await withSessionFor(name, (session) => explainQuery(session, sql)) };
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        throw new HttpError(404, 'not found');
+    }
+    async function serveStatic(res, pathname) {
+        if (!staticDir)
+            throw new HttpError(404, 'the web UI is not built; run npm run build:web');
+        const file = normalize(join(staticDir, pathname === '/' ? 'index.html' : pathname));
+        if (file !== staticDir && !file.startsWith(staticDir + sep))
+            throw new HttpError(403, 'forbidden');
+        let data;
+        let type = contentTypes[extname(file)] ?? 'application/octet-stream';
+        try {
+            data = await readFile(file);
+        }
+        catch {
+            // Not a file: the single page app handles the route itself.
+            if (extname(pathname))
+                throw new HttpError(404, 'not found');
+            data = await readFile(join(staticDir, 'index.html')).catch(() => {
+                throw new HttpError(404, 'the web UI is not built; run npm run build:web');
+            });
+            type = contentTypes['.html'];
+        }
+        res.writeHead(200, { 'content-type': type });
+        res.end(data);
+    }
+    return createServer((req, res) => {
+        void (async () => {
+            try {
+                if (!isLoopbackHost(req.headers.host))
+                    throw new HttpError(403, 'forbidden host');
+                const url = new URL(req.url ?? '/', 'http://localhost');
+                if (url.pathname.startsWith('/api/')) {
+                    // A request the browser gave up on stops waiting for answers to its questions.
+                    const abort = new AbortController();
+                    res.on('close', () => abort.abort());
+                    sendJson(res, 200, await api(req, url, abort.signal));
+                }
+                else if (req.method === 'GET' || req.method === 'HEAD')
+                    await serveStatic(res, url.pathname);
+                else
+                    throw new HttpError(405, 'method not allowed');
+            }
+            catch (error) {
+                if (error instanceof HttpError) {
+                    sendJson(res, error.status, { error: error.message });
+                }
+                else {
+                    sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+                }
+            }
+        })();
+    });
+}
+const PORT_ATTEMPTS = 100;
+/**
+ * Starts listening on the loopback interface; resolves with the address once it is up. When the
+ * port is taken the next free one is used, so the caller compares the result with what it asked for.
+ */
+export async function listen(server, port) {
+    for (let candidate = port; candidate < port + PORT_ATTEMPTS && candidate <= 65535; candidate++) {
+        try {
+            await listenOn(server, candidate);
+            return `http://127.0.0.1:${candidate}`;
+        }
+        catch (error) {
+            if (error.code !== 'EADDRINUSE')
+                throw error;
+        }
+    }
+    throw new Error(`no free port found from ${port} to ${port + PORT_ATTEMPTS - 1}`);
+}
+function listenOn(server, port) {
+    return new Promise((resolveListen, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', () => {
+            server.off('error', reject);
+            resolveListen();
+        });
+    });
+}
+/** Opens the address in the default browser; failing to is not an error, the address is printed. */
+export function openBrowser(address) {
+    const [command, args] = process.platform === 'darwin'
+        ? ['open', [address]]
+        : process.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', address]]
+            : ['xdg-open', [address]];
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => { });
+    child.unref();
+}

package/package.json

@@ -1,6 +1,68 @@
 {
-  "name": "@kazurolabs/psql-explorer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@kazurolabs/psql-explorer",
+	"version": "0.1.0",
+	"description": "Explore your Postgres databases from the terminal, with credentials from Vault",
+	"license": "MIT",
+	"type": "module",
+	"bin": {
+		"psql-explorer": "dist/cli.js"
+	},
+	"files": [
+		"dist",
+		"web/dist",
+		"README.md",
+		"LICENSE"
+	],
+	"engines": {
+		"node": ">=22.13"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsc && npm run build:web",
+		"dev": "tsx scripts/dev.mjs",
+		"test": "vitest run",
+		"typecheck": "tsc -p tsconfig.test.json",
+		"lint": "npm run typecheck && eslint . && prettier --check .",
+		"format": "prettier --write .",
+		"prepublishOnly": "npm run install:web && npm run build",
+		"dev:reset": "tsx scripts/dev.mjs --reset",
+		"dev:plain": "tsx src/cli.tsx",
+		"build:web": "npm --prefix web run build",
+		"dev:web": "tsx scripts/dev-web.mjs",
+		"dev:web:reset": "tsx scripts/dev-web.mjs --reset",
+		"install:web": "npm --prefix web install",
+		"dev:vite": "npm --prefix web run dev"
+	},
+	"dependencies": {
+		"ink": "^8.0.0",
+		"ink-big-text": "^2.0.0",
+		"ink-gradient": "^4.0.1",
+		"ink-spinner": "^5.0.0",
+		"ink-text-input": "^6.0.0",
+		"meow": "^14.1.0",
+		"pg": "^8.23.1",
+		"pg-cursor": "^2.22.1",
+		"react": "^19.3.1",
+		"string-width": "^8.3.0",
+		"yaml": "^2.9.1"
+	},
+	"devDependencies": {
+		"@eslint/js": "^10.0.1",
+		"@types/node": "^22.20.5",
+		"@types/pg": "^8.23.1",
+		"@types/pg-cursor": "^2.7.2",
+		"@types/react": "^19.3.0",
+		"eslint": "^10.13.0",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-react-hooks": "^7.1.1",
+		"globals": "^17.13.0",
+		"ink-testing-library": "^4.0.0",
+		"prettier": "^3.9.10",
+		"tsx": "^4.23.15",
+		"typescript": "~6.0.3",
+		"typescript-eslint": "^8.72.1",
+		"vitest": "^5.0.5"
+	}
+}