@humbdb/humb 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Humb contributors
+
+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

@@ -0,0 +1,11 @@
+# humb
+
+The `humb` CLI launches a local-first database management UI from your terminal.
+
+```bash
+npx humb postgres://user:pass@localhost:5432/mydb
+```
+
+It parses the target, starts the local server, opens your browser, and shuts down cleanly on
+`Ctrl+C`. Supports PostgreSQL first, with more engines planned. See
+[`docs/product-specs/connect-and-inspect-postgres.md`](../../docs/product-specs/connect-and-inspect-postgres.md).

package/dist/bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import {
+  main
+} from "./chunk-2ERJS5IY.js";
+
+// src/bin.ts
+import { InvalidConnectionTargetError } from "@humbdb/core";
+main().catch((error) => {
+  if (error instanceof InvalidConnectionTargetError) {
+    process.stderr.write(`${error.message}
+`);
+  } else {
+    process.stderr.write(`Humb failed to start: ${error.message}
+`);
+  }
+  process.exit(1);
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { InvalidConnectionTargetError } from \"@humbdb/core\";\nimport { main } from \"./index.js\";\n\nmain().catch((error: unknown) => {\n  if (error instanceof InvalidConnectionTargetError) {\n    process.stderr.write(`${error.message}\\n`);\n  } else {\n    process.stderr.write(`Humb failed to start: ${(error as Error).message}\\n`);\n  }\n  process.exit(1);\n});\n"],"mappings":";;;;;;AACA,SAAS,oCAAoC;AAG7C,KAAK,EAAE,MAAM,CAAC,UAAmB;AAC/B,MAAI,iBAAiB,8BAA8B;AACjD,YAAQ,OAAO,MAAM,GAAG,MAAM,OAAO;AAAA,CAAI;AAAA,EAC3C,OAAO;AACL,YAAQ,OAAO,MAAM,yBAA0B,MAAgB,OAAO;AAAA,CAAI;AAAA,EAC5E;AACA,UAAQ,KAAK,CAAC;AAChB,CAAC;","names":[]}

package/dist/chunk-2ERJS5IY.js

@@ -0,0 +1,83 @@
+// src/index.ts
+import { existsSync, statSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { parseConnectionTarget } from "@humbdb/core";
+import { resolveAdapter } from "@humbdb/driver-contract";
+import { postgresAdapterFactory } from "@humbdb/postgres";
+import { startServer } from "@humbdb/server";
+import { sqliteAdapterFactory } from "@humbdb/sqlite";
+import { Command } from "commander";
+import open from "open";
+function defaultWebRoot(here) {
+  const bundled = resolve(here, "web");
+  if (existsSync(join(bundled, "index.html"))) {
+    return bundled;
+  }
+  return resolve(here, "../../../apps/web/dist");
+}
+function parseArgs(argv) {
+  const program = new Command();
+  program.name("humb").description("Launch a local-first database management UI from your terminal.").argument(
+    "[target]",
+    "database connection string (postgres://user:pass@host:5432/db) or a path to a SQLite file (./app.db)"
+  ).option("-p, --port <port>", "port for the local server", (value) => parseInt(value, 10)).option(
+    "--files-dir <dir>",
+    "directory the Files tab may read *.sql files from (opt-in; disabled by default)"
+  ).allowExcessArguments(false).exitOverride();
+  program.parse(argv, { from: "user" });
+  const opts = program.opts();
+  return { target: program.args[0], port: opts.port, filesDir: opts.filesDir };
+}
+function resolvePort(flagPort, env) {
+  if (flagPort !== void 0) {
+    return flagPort;
+  }
+  const envPort = env.HUMB_PORT?.trim();
+  if (!envPort) {
+    return void 0;
+  }
+  const parsed = Number.parseInt(envPort, 10);
+  return Number.isNaN(parsed) ? void 0 : parsed;
+}
+function resolveFilesRoot(filesDir, cwd) {
+  return filesDir ? resolve(cwd, filesDir) : void 0;
+}
+async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  const target = parseConnectionTarget(args.target);
+  const adapter = resolveAdapter([postgresAdapterFactory, sqliteAdapterFactory], target);
+  await adapter.connect();
+  const filesRoot = resolveFilesRoot(args.filesDir, process.cwd());
+  if (filesRoot && (!existsSync(filesRoot) || !statSync(filesRoot).isDirectory())) {
+    throw new Error(`--files-dir "${filesRoot}" does not exist or is not a directory.`);
+  }
+  const port = resolvePort(args.port, process.env);
+  const server = await startServer({
+    adapter,
+    target,
+    port,
+    logger: true,
+    webRoot: defaultWebRoot(dirname(fileURLToPath(import.meta.url))),
+    filesRoot
+  });
+  process.stdout.write(`Humb is running at ${server.url}
+`);
+  await open(server.url);
+  const shutdown = async () => {
+    await server.close();
+    await adapter.disconnect();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+export {
+  defaultWebRoot,
+  parseArgs,
+  resolvePort,
+  resolveFilesRoot,
+  main
+};
+//# sourceMappingURL=chunk-2ERJS5IY.js.map

package/dist/chunk-2ERJS5IY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * The `humb` CLI: parse a database target, start the local server, and open the browser.\n */\nimport { existsSync, statSync } from \"node:fs\";\nimport { dirname, join, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { parseConnectionTarget } from \"@humbdb/core\";\nimport { resolveAdapter } from \"@humbdb/driver-contract\";\nimport { postgresAdapterFactory } from \"@humbdb/postgres\";\nimport { startServer } from \"@humbdb/server\";\nimport { sqliteAdapterFactory } from \"@humbdb/sqlite\";\nimport { Command } from \"commander\";\nimport open from \"open\";\n\n/**\n * Where the built `apps/web` static assets live, relative to this file's own directory (`here` -\n * `dist` when built, `src` in dev/test). Two candidates, tried in order:\n *\n * 1. `<here>/web`, bundled alongside this file by `tsup.config.ts`'s `onSuccess` hook and shipped\n *    inside the published `humb` npm package (see `files` in `package.json`) - this is what\n *    resolves once installed standalone outside this monorepo (F010).\n * 2. `<here>/../../../apps/web/dist`, monorepo-relative - what resolves in local dev/test, where\n *    the bundled copy was never created.\n *\n * `startServer` no-ops static serving if neither path contains a build, so this is safe even\n * before `apps/web` is built at all.\n */\nexport function defaultWebRoot(here: string): string {\n  const bundled = resolve(here, \"web\");\n  if (existsSync(join(bundled, \"index.html\"))) {\n    return bundled;\n  }\n  return resolve(here, \"../../../apps/web/dist\");\n}\n\nexport interface CliArgs {\n  target: string | undefined;\n  port: number | undefined;\n  filesDir: string | undefined;\n}\n\n/** Parse CLI arguments. Throws (via commander) on malformed flags. */\nexport function parseArgs(argv: string[]): CliArgs {\n  const program = new Command();\n  program\n    .name(\"humb\")\n    .description(\"Launch a local-first database management UI from your terminal.\")\n    .argument(\n      \"[target]\",\n      \"database connection string (postgres://user:pass@host:5432/db) or a path to a SQLite file (./app.db)\"\n    )\n    .option(\"-p, --port <port>\", \"port for the local server\", (value) => parseInt(value, 10))\n    .option(\n      \"--files-dir <dir>\",\n      \"directory the Files tab may read *.sql files from (opt-in; disabled by default)\"\n    )\n    .allowExcessArguments(false)\n    .exitOverride();\n\n  program.parse(argv, { from: \"user\" });\n  const opts = program.opts<{ port?: number; filesDir?: string }>();\n  return { target: program.args[0], port: opts.port, filesDir: opts.filesDir };\n}\n\n/** Resolve the port to listen on: `--port` flag, then `HUMB_PORT` env var, then the server default. */\nexport function resolvePort(\n  flagPort: number | undefined,\n  env: NodeJS.ProcessEnv\n): number | undefined {\n  if (flagPort !== undefined) {\n    return flagPort;\n  }\n  const envPort = env.HUMB_PORT?.trim();\n  if (!envPort) {\n    return undefined;\n  }\n  const parsed = Number.parseInt(envPort, 10);\n  return Number.isNaN(parsed) ? undefined : parsed;\n}\n\n/** Resolves the `--files-dir` flag to an absolute path. Undefined means file browsing is disabled. */\nexport function resolveFilesRoot(filesDir: string | undefined, cwd: string): string | undefined {\n  return filesDir ? resolve(cwd, filesDir) : undefined;\n}\n\n/** Run the CLI. Returns the running server's URL. */\nexport async function main(argv: string[] = process.argv.slice(2)): Promise<void> {\n  const args = parseArgs(argv);\n\n  const target = parseConnectionTarget(args.target);\n  const adapter = resolveAdapter([postgresAdapterFactory, sqliteAdapterFactory], target);\n  await adapter.connect();\n\n  const filesRoot = resolveFilesRoot(args.filesDir, process.cwd());\n  if (filesRoot && (!existsSync(filesRoot) || !statSync(filesRoot).isDirectory())) {\n    throw new Error(`--files-dir \"${filesRoot}\" does not exist or is not a directory.`);\n  }\n\n  const port = resolvePort(args.port, process.env);\n  const server = await startServer({\n    adapter,\n    target,\n    port,\n    logger: true,\n    webRoot: defaultWebRoot(dirname(fileURLToPath(import.meta.url))),\n    filesRoot\n  });\n  process.stdout.write(`Humb is running at ${server.url}\\n`);\n  await open(server.url);\n\n  const shutdown = async (): Promise<void> => {\n    await server.close();\n    await adapter.disconnect();\n    process.exit(0);\n  };\n  process.on(\"SIGINT\", shutdown);\n  process.on(\"SIGTERM\", shutdown);\n}\n"],"mappings":";AAGA,SAAS,YAAY,gBAAgB;AACrC,SAAS,SAAS,MAAM,eAAe;AACvC,SAAS,qBAAqB;AAC9B,SAAS,6BAA6B;AACtC,SAAS,sBAAsB;AAC/B,SAAS,8BAA8B;AACvC,SAAS,mBAAmB;AAC5B,SAAS,4BAA4B;AACrC,SAAS,eAAe;AACxB,OAAO,UAAU;AAeV,SAAS,eAAe,MAAsB;AACnD,QAAM,UAAU,QAAQ,MAAM,KAAK;AACnC,MAAI,WAAW,KAAK,SAAS,YAAY,CAAC,GAAG;AAC3C,WAAO;AAAA,EACT;AACA,SAAO,QAAQ,MAAM,wBAAwB;AAC/C;AASO,SAAS,UAAU,MAAyB;AACjD,QAAM,UAAU,IAAI,QAAQ;AAC5B,UACG,KAAK,MAAM,EACX,YAAY,iEAAiE,EAC7E;AAAA,IACC;AAAA,IACA;AAAA,EACF,EACC,OAAO,qBAAqB,6BAA6B,CAAC,UAAU,SAAS,OAAO,EAAE,CAAC,EACvF;AAAA,IACC;AAAA,IACA;AAAA,EACF,EACC,qBAAqB,KAAK,EAC1B,aAAa;AAEhB,UAAQ,MAAM,MAAM,EAAE,MAAM,OAAO,CAAC;AACpC,QAAM,OAAO,QAAQ,KAA2C;AAChE,SAAO,EAAE,QAAQ,QAAQ,KAAK,CAAC,GAAG,MAAM,KAAK,MAAM,UAAU,KAAK,SAAS;AAC7E;AAGO,SAAS,YACd,UACA,KACoB;AACpB,MAAI,aAAa,QAAW;AAC1B,WAAO;AAAA,EACT;AACA,QAAM,UAAU,IAAI,WAAW,KAAK;AACpC,MAAI,CAAC,SAAS;AACZ,WAAO;AAAA,EACT;AACA,QAAM,SAAS,OAAO,SAAS,SAAS,EAAE;AAC1C,SAAO,OAAO,MAAM,MAAM,IAAI,SAAY;AAC5C;AAGO,SAAS,iBAAiB,UAA8B,KAAiC;AAC9F,SAAO,WAAW,QAAQ,KAAK,QAAQ,IAAI;AAC7C;AAGA,eAAsB,KAAK,OAAiB,QAAQ,KAAK,MAAM,CAAC,GAAkB;AAChF,QAAM,OAAO,UAAU,IAAI;AAE3B,QAAM,SAAS,sBAAsB,KAAK,MAAM;AAChD,QAAM,UAAU,eAAe,CAAC,wBAAwB,oBAAoB,GAAG,MAAM;AACrF,QAAM,QAAQ,QAAQ;AAEtB,QAAM,YAAY,iBAAiB,KAAK,UAAU,QAAQ,IAAI,CAAC;AAC/D,MAAI,cAAc,CAAC,WAAW,SAAS,KAAK,CAAC,SAAS,SAAS,EAAE,YAAY,IAAI;AAC/E,UAAM,IAAI,MAAM,gBAAgB,SAAS,yCAAyC;AAAA,EACpF;AAEA,QAAM,OAAO,YAAY,KAAK,MAAM,QAAQ,GAAG;AAC/C,QAAM,SAAS,MAAM,YAAY;AAAA,IAC/B;AAAA,IACA;AAAA,IACA;AAAA,IACA,QAAQ;AAAA,IACR,SAAS,eAAe,QAAQ,cAAc,YAAY,GAAG,CAAC,CAAC;AAAA,IAC/D;AAAA,EACF,CAAC;AACD,UAAQ,OAAO,MAAM,sBAAsB,OAAO,GAAG;AAAA,CAAI;AACzD,QAAM,KAAK,OAAO,GAAG;AAErB,QAAM,WAAW,YAA2B;AAC1C,UAAM,OAAO,MAAM;AACnB,UAAM,QAAQ,WAAW;AACzB,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,UAAQ,GAAG,UAAU,QAAQ;AAC7B,UAAQ,GAAG,WAAW,QAAQ;AAChC;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Where the built `apps/web` static assets live, relative to this file's own directory (`here` -
+ * `dist` when built, `src` in dev/test). Two candidates, tried in order:
+ *
+ * 1. `<here>/web`, bundled alongside this file by `tsup.config.ts`'s `onSuccess` hook and shipped
+ *    inside the published `humb` npm package (see `files` in `package.json`) - this is what
+ *    resolves once installed standalone outside this monorepo (F010).
+ * 2. `<here>/../../../apps/web/dist`, monorepo-relative - what resolves in local dev/test, where
+ *    the bundled copy was never created.
+ *
+ * `startServer` no-ops static serving if neither path contains a build, so this is safe even
+ * before `apps/web` is built at all.
+ */
+declare function defaultWebRoot(here: string): string;
+interface CliArgs {
+    target: string | undefined;
+    port: number | undefined;
+    filesDir: string | undefined;
+}
+/** Parse CLI arguments. Throws (via commander) on malformed flags. */
+declare function parseArgs(argv: string[]): CliArgs;
+/** Resolve the port to listen on: `--port` flag, then `HUMB_PORT` env var, then the server default. */
+declare function resolvePort(flagPort: number | undefined, env: NodeJS.ProcessEnv): number | undefined;
+/** Resolves the `--files-dir` flag to an absolute path. Undefined means file browsing is disabled. */
+declare function resolveFilesRoot(filesDir: string | undefined, cwd: string): string | undefined;
+/** Run the CLI. Returns the running server's URL. */
+declare function main(argv?: string[]): Promise<void>;
+
+export { type CliArgs, defaultWebRoot, main, parseArgs, resolveFilesRoot, resolvePort };

package/dist/index.js

@@ -0,0 +1,15 @@
+import {
+  defaultWebRoot,
+  main,
+  parseArgs,
+  resolveFilesRoot,
+  resolvePort
+} from "./chunk-2ERJS5IY.js";
+export {
+  defaultWebRoot,
+  main,
+  parseArgs,
+  resolveFilesRoot,
+  resolvePort
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}