planche 0.7.1 → 0.7.2

package/README.md

@@ -116,6 +116,10 @@ database connections open and forwards queries with the matching driver
   `~/.ssh/known_hosts` are honoured too). A changed key refuses the
   connection until the stale entry is removed.
 
+When `planche.dev` cannot be reached, the agent serves the copy of the app it
+ships with (at its own address) instead of opening a browser error page, so it
+keeps working offline. `--no-serve-app` turns that off.
+
 ## Gateway mode
 
 Run one agent on a shared host so a team can use Planche with just a
@@ -132,14 +136,63 @@ npx planche --gateway gateway.json --addr 0.0.0.0 --allow-remote \
 {
   "name": "Acme staging",
   "profiles": [
-    { "name": "Shop (read-only)", "driver": "mysql", "host": "db", "port": 3306,
-      "user": "reporting", "password": "…", "database": "shop" },
-    { "name": "Shop (writable)", "readOnly": false, "driver": "postgres",
-      "host": "pg", "port": 5432, "user": "app", "password": "…", "database": "shop" }
+    {
+      "name": "Shop (read-only)",
+      "driver": "mysql",
+      "host": "db.internal",
+      "port": 3306,
+      "user": "reporting",
+      "password": "…",
+      "database": "shop"
+    },
+    {
+      "name": "Shop (writable)",
+      "readOnly": false,
+      "driver": "postgres",
+      "host": "pg.internal",
+      "port": 5432,
+      "user": "app",
+      "password": "…",
+      "database": "shop"
+    }
   ]
 }
 ```
 
+`name` is the gateway's own name and `profiles[].name` is what browsers pick;
+every other field is what the connection form asks for, under the same names
+(`serviceName` for Oracle, `file` for SQLite, `accountId` / `databaseId` /
+`apiToken` for D1, and an `ssh` block where you need one).
+
+A profile behind a jump host carries that `ssh` block; `host`/`port` are then
+resolved on the jump host, so they are usually loopback:
+
+```json
+{
+  "name": "Shop via bastion (read-only)",
+  "driver": "mysql",
+  "host": "127.0.0.1",
+  "port": 3306,
+  "user": "reporting",
+  "password": "…",
+  "database": "shop",
+  "ssh": {
+    "host": "bastion.example.com",
+    "port": 22,
+    "user": "deploy",
+    "auth": "key"
+  }
+}
+```
+
+With `auth: "key"` and no `privateKey`, the agent uses the `IdentityFile` from
+this machine's `~/.ssh/config` (falling back to `~/.ssh/id_*`), so the key
+never lands in the config file; `auth: "agent"` uses `SSH_AUTH_SOCK`. A
+`privateKey` you do set is the key *contents*, not a path. The jump host's key
+must already be in a `known_hosts` file here, or be pinned in the profile with
+`acceptHostKey` — in gateway mode the browser sends only a profile name and
+cannot answer the unknown-host-key prompt.
+
 - Browsers only ever send `{ "profile": "Shop (read-only)" }`; `/connect`
   bodies with credentials are refused in gateway mode.
 - Profiles are **read-only by default**: the agent refuses anything but a

package/dist/index.js

@@ -2172,6 +2172,29 @@ var DEV_ORIGINS = [
   "http://localhost:4173",
   "http://127.0.0.1:4173"
 ];
+function bundledAppDir() {
+  const dir = fileURLToPath(new URL("../app/", import.meta.url));
+  return existsSync3(join5(dir, "index.html")) ? dir : null;
+}
+function isLoopbackUrl(url) {
+  try {
+    return LOOPBACK_ADDRS.has(new URL(url).hostname);
+  } catch {
+    return false;
+  }
+}
+async function appIsReachable(url, timeoutMs = 2500) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { signal: controller.signal, redirect: "follow", headers: { "cache-control": "no-store" } });
+    return response.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
 function resolveAppDir(explicit) {
   const dir = explicit ? resolve3(explicit) : fileURLToPath(new URL("../app/", import.meta.url));
   if (!existsSync3(join5(dir, "index.html"))) {
@@ -2198,8 +2221,8 @@ Options:
                        config instead of accepting credentials (env PLANCHE_GATEWAY)
       --public-url <u> URL users open when the agent serves the app itself
                        (behind your TLS proxy; env PLANCHE_PUBLIC_URL)
-      --no-serve-app   Do not serve the web app at / (served by default in
-                       gateway mode)
+      --no-serve-app   Never serve the web app at / (it is served in gateway
+                       mode, and when planche.dev cannot be reached)
       --app-dir <dir>  Serve this build of the web app instead of the bundled one
       --no-open        Do not open the browser
       --verbose        Log every request
@@ -2230,7 +2253,7 @@ function openInBrowser(url) {
   } catch {
   }
 }
-function main() {
+async function main() {
   const major = Number(process.versions.node.split(".")[0]);
   if (major < 22) {
     console.error(`planche needs Node.js 22 or newer (you are running ${process.version}).`);
@@ -2288,10 +2311,13 @@ function main() {
       process.exit(2);
     }
   }
-  const serveApp2 = flags["serve-app"] ?? Boolean(gateway);
+  const hostedAppUrl = (flags.app ?? process.env.PLANCHE_APP_URL ?? DEFAULT_APP_URL).replace(/\/+$/, "");
+  let serveApp2 = flags["serve-app"] ?? Boolean(gateway);
+  const offlineFallback = !serveApp2 && flags["serve-app"] !== false && bundledAppDir() !== null && !isLoopbackUrl(hostedAppUrl) && !await appIsReachable(hostedAppUrl);
+  if (offlineFallback) serveApp2 = true;
   const appDir = serveApp2 ? resolveAppDir(flags["app-dir"] ?? process.env.PLANCHE_APP_DIR) : void 0;
   const publicUrl = (flags["public-url"] ?? process.env.PLANCHE_PUBLIC_URL ?? "").replace(/\/+$/, "");
-  const appUrl = (serveApp2 ? publicUrl || null : null) ?? (flags.app ?? process.env.PLANCHE_APP_URL ?? DEFAULT_APP_URL).replace(/\/+$/, "");
+  const appUrl = (serveApp2 ? publicUrl || null : null) ?? hostedAppUrl;
   const shouldOpen = flags.open ?? true;
   const bodyLimit = process.env.PLANCHE_BODY_LIMIT || "50mb";
   const appOrigin = originOf(appUrl);
@@ -2341,6 +2367,9 @@ function main() {
     appDir
   });
   const pairUrl = serveApp2 ? `${publicUrl || agentUrl}/#pair=${encodeURIComponent(pairingCode.code)}` : `${appUrl}/#agent=${encodeURIComponent(agentUrl)}&pair=${encodeURIComponent(pairingCode.code)}`;
+  if (offlineFallback) {
+    console.log(`${DEFAULT_APP_URL === hostedAppUrl ? "planche.dev" : hostedAppUrl} is unreachable \u2014 serving the app bundled with this agent (v${VERSION}) instead.`);
+  }
   const server = app.listen(port, listenAddr, () => {
     const line = "-".repeat(72);
     console.log(line);
@@ -2377,4 +2406,7 @@ function main() {
   process.on("uncaughtException", (err) => console.error("[agent] Uncaught exception:", err instanceof Error ? err.message : String(err)));
   process.on("unhandledRejection", (err) => console.error("[agent] Unhandled rejection:", err instanceof Error ? err.message : String(err)));
 }
-main();
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "planche",
-  "version": "0.7.1",
-  "description": "Local agent for Planche — lets the browser-based Planche SQL client reach MySQL/MariaDB/PostgreSQL/SQLite/SQL Server/Oracle/Neon/Supabase/Cloudflare D1 databases from your machine.",
+  "version": "0.7.2",
+  "description": "Local agent for Planche \u2014 lets the browser-based Planche SQL client reach MySQL/MariaDB/PostgreSQL/SQLite/SQL Server/Oracle/Neon/Supabase/Cloudflare D1 databases from your machine.",
   "license": "UNLICENSED",
   "homepage": "https://planche.dev",
   "repository": {