planche 0.1.0

package/README.md

@@ -0,0 +1,130 @@
+# planche
+
+Local agent for [Planche](https://planche.dev), a browser-based SQL client for
+MySQL, MariaDB, PostgreSQL and SQLite.
+
+Browsers cannot open TCP connections to a database, so Planche runs this small
+agent on your machine. The app in your browser talks to the agent over
+`127.0.0.1`, and the agent talks to your databases. Credentials and query
+results stay on your computer — nothing is sent to planche.dev.
+
+## Quick start
+
+Requires Node.js 22 or newer.
+
+```bash
+npx planche
+```
+
+The agent starts on port 8888, prints a pairing link and opens it in your
+default browser:
+
+```
+https://planche.dev/#agent=http://127.0.0.1:8888&token=…
+```
+
+Opening that link pairs the app with the agent. From then on you can add
+connections in the app as usual; every connection is opened by the agent on
+your machine.
+
+The token is random on every start. If you restart the agent, the app shows
+"agent restarted" and asks you to open the new link (or set a fixed token, see
+below).
+
+## Usage
+
+```
+npx planche [options]
+
+  -p, --port <n>       Port to listen on (default: 8888)
+      --addr <host>    Address to bind (default: 127.0.0.1)
+      --token <str>    Auth token (default: random on each start)
+      --app <url>      Web app to open (default: https://planche.dev)
+      --origin <url>   Extra browser origin allowed to use the agent (repeatable)
+      --no-open        Print the pairing link without opening a browser
+      --verbose        Log every request
+  -h, --help           Show help
+```
+
+Every option can also be set through an environment variable:
+
+| Variable                  | Option     | Notes                                               |
+| ------------------------- | ---------- | --------------------------------------------------- |
+| `PLANCHE_PORT`            | `--port`   |                                                     |
+| `PLANCHE_ADDR`            | `--addr`   |                                                     |
+| `PLANCHE_AUTH_TOKEN`      | `--token`  | Fixed token; the pairing link stays valid across restarts |
+| `PLANCHE_APP_URL`         | `--app`    | Use a self-hosted build of the app                  |
+| `PLANCHE_ALLOWED_ORIGINS` | `--origin` | Comma-separated list                                |
+| `PLANCHE_BODY_LIMIT`      |            | Max request body, default `50mb` (large SQL scripts) |
+| `PLANCHE_SQLITE_DIR`      |            | Only SQLite files inside this directory may be opened |
+
+### Examples
+
+Keep the same token between restarts so the app never needs re-pairing:
+
+```bash
+PLANCHE_AUTH_TOKEN=my-secret npx planche
+```
+
+Run on another port and print the link only:
+
+```bash
+npx planche --port 9000 --no-open
+```
+
+Use with the app served from your own host:
+
+```bash
+npx planche --app https://planche.example.com
+```
+
+Restrict SQLite access to one folder:
+
+```bash
+PLANCHE_SQLITE_DIR=~/databases npx planche
+```
+
+## How it works
+
+The agent is a small HTTP server with a handful of JSON endpoints
+(`/connect`, `/query`, `/disconnect`, `/test-connection`, `/health`). The app
+calls them with the bearer token from the pairing link; the agent keeps the
+database connections open and forwards queries with the matching driver
+(`mysql2`, `pg`, `better-sqlite3`).
+
+- **MySQL / MariaDB** — switching databases uses `USE`, so open transactions
+  and session variables survive.
+- **PostgreSQL** — one connection is bound to one database; the "database"
+  you pick in the app is a schema of it and is applied with `SET search_path`.
+- **SQLite** — opens a file on your disk by path. Set `PLANCHE_SQLITE_DIR` to
+  limit which files can be opened. (Small SQLite files can also be opened
+  directly in the browser without the agent.)
+
+## Security
+
+- Every request except `GET /health` requires the bearer token.
+- Browser requests are accepted only from the Planche app origin and local
+  dev servers. Any other `Origin` is refused with `403`, even with a valid
+  token. Add your own with `--origin`.
+- The agent binds to `127.0.0.1` by default, so only the browser on the same
+  machine can reach it. Binding to another address (`--addr 0.0.0.0`) exposes
+  your databases to the network — only do that behind a tunnel or firewall you
+  trust.
+- The agent never stores credentials. They are passed per connection by the
+  app and live in memory only while the connection is open.
+
+## Troubleshooting
+
+- **The app says the agent is offline** — make sure `npx planche` is still
+  running and that the port in the pairing link matches. Corporate proxies or
+  browser extensions that block `localhost` requests can also cause this.
+- **"Agent restarted, re-pair"** — the agent generated a new token. Open the
+  new link it printed, or start it with a fixed `--token`.
+- **`403 Forbidden`** — the request came from an origin that is not
+  allow-listed. Pass `--origin https://your-app-host`.
+- **Wrong Node version** — the SQLite driver ships prebuilt binaries for
+  Node 22+. Check with `node -v`, or run with `npx -p node@22 planche`.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,882 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { createRequire } from "module";
+import { spawn } from "child_process";
+import { parseArgs } from "util";
+
+// src/server.ts
+import express from "express";
+import { timingSafeEqual } from "crypto";
+
+// ../shared/contract.ts
+var PROTOCOL_VERSION = 2;
+
+// src/tunneling.ts
+import { randomUUID } from "crypto";
+
+// src/drivers/mysql.ts
+import mysql from "mysql2/promise";
+var MYSQL_TYPES = {
+  0: "decimal",
+  1: "tinyint",
+  2: "smallint",
+  3: "int",
+  4: "float",
+  5: "double",
+  6: "null",
+  7: "timestamp",
+  8: "bigint",
+  9: "mediumint",
+  10: "date",
+  11: "time",
+  12: "datetime",
+  13: "year",
+  14: "newdate",
+  15: "varchar",
+  16: "bit",
+  245: "json",
+  246: "newdecimal",
+  247: "enum",
+  248: "set",
+  249: "tinyblob",
+  250: "mediumblob",
+  251: "longblob",
+  252: "blob",
+  253: "varstring",
+  254: "string",
+  255: "geometry"
+};
+function getTypeName(typeId) {
+  return MYSQL_TYPES[typeId] ?? "unknown";
+}
+function toConnectionOptions(config) {
+  return {
+    host: config.host,
+    port: config.port,
+    user: config.user,
+    password: config.password,
+    database: config.database || void 0,
+    dateStrings: true,
+    charset: config.charset || "utf8mb4"
+  };
+}
+var USE_STATEMENT = /^\s*USE\s/i;
+var MySqlDriver = class {
+  constructor(connection, config) {
+    this.connection = connection;
+    this.label = `${config.user}@${config.host}:${config.port}`;
+    this.currentDatabase = config.database ?? null;
+  }
+  connection;
+  type = "mysql";
+  label;
+  /**
+   * Default schema the session is currently in, or null when unknown (after
+   * the client ran its own `USE`). Tracked so the schema is switched with a
+   * plain `USE` only when it actually changes: `changeUser()` would reset the
+   * whole session on every call, silently rolling back open transactions and
+   * dropping temporary tables and user variables.
+   */
+  currentDatabase;
+  async query(sql, database) {
+    if (database && database !== this.currentDatabase) {
+      await this.connection.query(`USE ${mysql.escapeId(database)}`);
+      this.currentDatabase = database;
+    }
+    const [results, fields] = await this.connection.query(sql);
+    if (USE_STATEMENT.test(sql)) this.currentDatabase = null;
+    if (Array.isArray(results) && fields) {
+      const fieldPackets = fields;
+      const mappedFields = fieldPackets.map((field) => ({
+        name: field.name,
+        orgName: field.orgName ?? field.name,
+        type: getTypeName(field.type ?? 253),
+        table: field.table ?? "",
+        orgTable: field.orgTable ?? "",
+        db: field.db ?? "",
+        maxLength: field.length ?? 0
+      }));
+      const records = results.map(
+        (row) => fieldPackets.map((field) => row[field.name])
+      );
+      return { fields: mappedFields, records, affectedRows: 0, insertId: 0, isResultQuery: true };
+    }
+    const header = results;
+    return {
+      fields: [],
+      records: [],
+      affectedRows: header.affectedRows ?? 0,
+      insertId: header.insertId ?? 0,
+      isResultQuery: false
+    };
+  }
+  async close() {
+    await this.connection.end();
+  }
+};
+var mysqlDriverFactory = {
+  async open(config) {
+    const connection = await mysql.createConnection(toConnectionOptions(config));
+    return new MySqlDriver(connection, config);
+  },
+  async test(config) {
+    const connection = await mysql.createConnection({
+      ...toConnectionOptions(config),
+      database: void 0
+    });
+    await connection.end();
+  },
+  parseConfig(body) {
+    const host = typeof body.host === "string" ? body.host.trim() : "";
+    const user = typeof body.user === "string" ? body.user : "";
+    if (!host || !user) {
+      throw new Error("host and user are required");
+    }
+    return {
+      driver: "mysql",
+      host,
+      port: Number(body.port) || 3306,
+      user,
+      password: typeof body.password === "string" ? body.password : "",
+      database: typeof body.database === "string" && body.database ? body.database : void 0,
+      charset: typeof body.charset === "string" && body.charset ? body.charset : void 0
+    };
+  }
+};
+
+// src/drivers/postgres.ts
+import pg from "pg";
+var TEXT_OIDS = [
+  20,
+  // int8
+  1700,
+  // numeric
+  1082,
+  // date
+  1114,
+  // timestamp
+  1184,
+  // timestamptz
+  1083,
+  // time
+  1266,
+  // timetz
+  1186
+  // interval
+];
+var types = new pg.TypeOverrides();
+for (const oid of TEXT_OIDS) types.setTypeParser(oid, (value) => value);
+var BUILTIN_TYPES = {
+  16: "bool",
+  17: "bytea",
+  18: "char",
+  19: "name",
+  20: "int8",
+  21: "int2",
+  23: "int4",
+  25: "text",
+  26: "oid",
+  114: "json",
+  142: "xml",
+  700: "float4",
+  701: "float8",
+  1042: "bpchar",
+  1043: "varchar",
+  1082: "date",
+  1083: "time",
+  1114: "timestamp",
+  1184: "timestamptz",
+  1186: "interval",
+  1266: "timetz",
+  1700: "numeric",
+  2950: "uuid",
+  3802: "jsonb",
+  1560: "bit",
+  1562: "varbit",
+  600: "point",
+  869: "inet",
+  650: "cidr",
+  829: "macaddr",
+  1007: "_int4",
+  1009: "_text"
+};
+function toClientConfig(config) {
+  return {
+    host: config.host,
+    port: config.port,
+    user: config.user,
+    password: config.password,
+    database: config.database,
+    ssl: config.ssl ? { rejectUnauthorized: false } : void 0,
+    types
+  };
+}
+var SEARCH_PATH_STATEMENT = /^\s*SET\s+(SESSION\s+|LOCAL\s+)?search_path\b/i;
+var quoteIdent = (name) => `"${name.replaceAll('"', '""')}"`;
+var PostgresDriver = class {
+  constructor(client, config) {
+    this.client = client;
+    this.label = `${config.user}@${config.host}:${config.port}/${config.database}`;
+  }
+  client;
+  type = "postgres";
+  label;
+  /**
+   * Schema currently first in `search_path`, or null when unknown (after the
+   * client set it itself). The app's "database" for a Postgres connection is
+   * a schema of the bound database, switched with `SET search_path`.
+   */
+  currentSchema = null;
+  typeNames = { ...BUILTIN_TYPES };
+  /**
+   * Result fields name their source only by OID (`tableID` / `columnID`);
+   * the frontend needs schema/table/column names to decide whether a grid is
+   * editable and to build UPDATEs, so they are resolved here and cached.
+   */
+  relations = /* @__PURE__ */ new Map();
+  async loadTypeNames() {
+    try {
+      const res = await this.client.query(
+        "SELECT oid, typname FROM pg_type WHERE typtype IN ('b', 'e', 'd', 'r')"
+      );
+      for (const row of res.rows) this.typeNames[Number(row.oid)] = row.typname;
+    } catch {
+    }
+  }
+  async resolveRelations(tableIds) {
+    const missing = [...new Set(tableIds)].filter((id) => id > 0 && !this.relations.has(id));
+    if (missing.length === 0) return;
+    try {
+      const res = await this.client.query(
+        `SELECT c.oid, n.nspname, c.relname, a.attnum, a.attname
+         FROM pg_class c
+         JOIN pg_namespace n ON n.oid = c.relnamespace
+         JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped
+         WHERE c.oid = ANY($1::oid[])`,
+        [missing]
+      );
+      for (const row of res.rows) {
+        const oid = Number(row.oid);
+        let rel = this.relations.get(oid);
+        if (!rel) {
+          rel = { schema: row.nspname, table: row.relname, columns: /* @__PURE__ */ new Map() };
+          this.relations.set(oid, rel);
+        }
+        rel.columns.set(Number(row.attnum), row.attname);
+      }
+    } catch {
+    }
+  }
+  async query(sql, database) {
+    if (database && database !== this.currentSchema) {
+      await this.client.query(`SET search_path TO ${quoteIdent(database)}, public`);
+      this.currentSchema = database;
+    }
+    const result = await this.client.query({ text: sql, rowMode: "array" });
+    if (SEARCH_PATH_STATEMENT.test(sql)) this.currentSchema = null;
+    const results = Array.isArray(result) ? result : [result];
+    const last = [...results].reverse().find((r) => r.fields.length > 0) ?? results[results.length - 1];
+    if (last.fields.length > 0) {
+      await this.resolveRelations(last.fields.map((f) => f.tableID));
+      const fields = last.fields.map((field) => {
+        const rel = this.relations.get(field.tableID);
+        return {
+          name: field.name,
+          orgName: rel?.columns.get(field.columnID) ?? field.name,
+          type: this.typeNames[field.dataTypeID] ?? `oid:${field.dataTypeID}`,
+          table: rel?.table ?? "",
+          orgTable: rel?.table ?? "",
+          db: rel?.schema ?? "",
+          maxLength: field.dataTypeSize > 0 ? field.dataTypeSize : 0
+        };
+      });
+      return { fields, records: last.rows, affectedRows: 0, insertId: 0, isResultQuery: true };
+    }
+    return {
+      fields: [],
+      records: [],
+      affectedRows: results.reduce((sum, r) => sum + (r.rowCount ?? 0), 0),
+      insertId: 0,
+      isResultQuery: false
+    };
+  }
+  async close() {
+    await this.client.end();
+  }
+};
+var postgresDriverFactory = {
+  async open(config) {
+    const client = new pg.Client(toClientConfig(config));
+    await client.connect();
+    const driver = new PostgresDriver(client, config);
+    await driver.loadTypeNames();
+    return driver;
+  },
+  async test(config) {
+    const client = new pg.Client(toClientConfig(config));
+    await client.connect();
+    await client.end();
+  },
+  parseConfig(body) {
+    const host = typeof body.host === "string" ? body.host.trim() : "";
+    const user = typeof body.user === "string" ? body.user : "";
+    if (!host || !user) {
+      throw new Error("host and user are required");
+    }
+    return {
+      driver: "postgres",
+      host,
+      port: Number(body.port) || 5432,
+      user,
+      password: typeof body.password === "string" ? body.password : "",
+      database: typeof body.database === "string" && body.database ? body.database : "postgres",
+      ssl: body.ssl === true
+    };
+  }
+};
+
+// src/drivers/sqlite.ts
+import Database from "better-sqlite3";
+import { existsSync } from "fs";
+import { isAbsolute, resolve, sep } from "path";
+function normalizeDeclaredType(declared) {
+  if (!declared) return null;
+  const base = declared.trim().toLowerCase().replace(/\(.*$/, "").trim();
+  return base || null;
+}
+function inferTypeFromValue(value) {
+  if (value === null || value === void 0) return "null";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "real";
+  if (typeof value === "bigint") return "bigint";
+  if (Buffer.isBuffer(value)) return "blob";
+  return "text";
+}
+var SQLITE_DIR = process.env.PLANCHE_SQLITE_DIR ? resolve(process.env.PLANCHE_SQLITE_DIR) : null;
+function resolveFile(file) {
+  if (file === ":memory:") return file;
+  if (file.startsWith("file:")) {
+    if (SQLITE_DIR) throw new Error("URI filenames are disabled while PLANCHE_SQLITE_DIR is set");
+    return file;
+  }
+  const resolved = isAbsolute(file) ? file : resolve(SQLITE_DIR ?? process.cwd(), file);
+  if (SQLITE_DIR && resolved !== SQLITE_DIR && !resolved.startsWith(SQLITE_DIR + sep)) {
+    throw new Error(`SQLite file must be inside ${SQLITE_DIR}`);
+  }
+  return resolved;
+}
+function openDatabase(config) {
+  const file = resolveFile(config.file);
+  const isMemory = file === ":memory:";
+  if (!isMemory && !config.createIfMissing && !existsSync(file)) {
+    throw new Error(`SQLite file not found: ${file}`);
+  }
+  return new Database(file, {
+    readonly: config.readonly ?? false,
+    fileMustExist: !isMemory && !config.createIfMissing
+  });
+}
+var SqliteDriver = class {
+  constructor(db, config) {
+    this.db = db;
+    this.label = resolveFile(config.file);
+  }
+  db;
+  type = "sqlite";
+  label;
+  async query(sql) {
+    let statement;
+    try {
+      statement = this.db.prepare(sql);
+    } catch (err) {
+      if (err instanceof RangeError && /more than one statement/i.test(err.message)) {
+        this.db.exec(sql);
+        return { fields: [], records: [], affectedRows: 0, insertId: 0, isResultQuery: false };
+      }
+      throw err;
+    }
+    if (!statement.reader) {
+      const info = statement.run();
+      return {
+        fields: [],
+        records: [],
+        affectedRows: info.changes,
+        insertId: Number(info.lastInsertRowid),
+        isResultQuery: false
+      };
+    }
+    const columns = statement.columns();
+    const records = statement.raw(true).all();
+    const fields = columns.map((col, index) => {
+      const declared = normalizeDeclaredType(col.type);
+      const type = declared ?? inferTypeFromValue(firstNonNull(records, index));
+      return {
+        name: col.name,
+        orgName: col.column ?? col.name,
+        type,
+        table: col.table ?? "",
+        orgTable: col.table ?? "",
+        db: col.database ?? "",
+        maxLength: 0
+      };
+    });
+    return { fields, records, affectedRows: 0, insertId: 0, isResultQuery: true };
+  }
+  async close() {
+    if (this.db.inTransaction) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {
+      }
+    }
+    this.db.close();
+  }
+};
+function firstNonNull(records, index) {
+  for (const row of records) {
+    const value = row[index];
+    if (value !== null && value !== void 0) return value;
+  }
+  return null;
+}
+var sqliteDriverFactory = {
+  async open(config) {
+    return new SqliteDriver(openDatabase(config), config);
+  },
+  async test(config) {
+    const db = openDatabase(config);
+    try {
+      db.prepare("SELECT 1").get();
+    } finally {
+      db.close();
+    }
+  },
+  parseConfig(body) {
+    const file = typeof body.file === "string" ? body.file.trim() : "";
+    if (!file) {
+      throw new Error("file is required");
+    }
+    return {
+      driver: "sqlite",
+      file,
+      createIfMissing: body.createIfMissing === true,
+      readonly: body.readonly === true
+    };
+  }
+};
+
+// src/drivers/index.ts
+var factories = {
+  mysql: mysqlDriverFactory,
+  postgres: postgresDriverFactory,
+  sqlite: sqliteDriverFactory
+};
+function isDriverType(value) {
+  return typeof value === "string" && value in factories;
+}
+function parseDriverConfig(body) {
+  const driver = body.driver ?? "mysql";
+  if (!isDriverType(driver)) {
+    throw new Error(`Unsupported driver: ${String(driver)}`);
+  }
+  return factories[driver].parseConfig(body);
+}
+function openDriver(config) {
+  switch (config.driver) {
+    case "mysql":
+      return factories.mysql.open(config);
+    case "postgres":
+      return factories.postgres.open(config);
+    case "sqlite":
+      return factories.sqlite.open(config);
+  }
+}
+function testDriver(config) {
+  switch (config.driver) {
+    case "mysql":
+      return factories.mysql.test(config);
+    case "postgres":
+      return factories.postgres.test(config);
+    case "sqlite":
+      return factories.sqlite.test(config);
+  }
+}
+
+// src/tunneling.ts
+var IDLE_TIMEOUT_MS = Number(process.env.PLANCHE_IDLE_TIMEOUT_MS) || 30 * 60 * 1e3;
+var ConnectionManager = class {
+  connections = /* @__PURE__ */ new Map();
+  lastUsed = /* @__PURE__ */ new Map();
+  constructor() {
+    const timer = setInterval(() => void this.closeIdle(), 6e4);
+    timer.unref();
+  }
+  /** Close connections idle for longer than `IDLE_TIMEOUT_MS`. */
+  async closeIdle() {
+    const cutoff = Date.now() - IDLE_TIMEOUT_MS;
+    for (const [id, used] of this.lastUsed) {
+      if (used < cutoff) {
+        console.log(`[ConnectionManager] Closing idle connection: ${id}`);
+        await this.disconnect(id).catch(() => void 0);
+      }
+    }
+  }
+  /**
+   * Open a new connection and return a unique connection ID.
+   */
+  async connect(config) {
+    const driver = await openDriver(config);
+    const connectionId = randomUUID();
+    this.connections.set(connectionId, driver);
+    this.lastUsed.set(connectionId, Date.now());
+    console.log(`[ConnectionManager] New ${driver.type} connection: ${connectionId} -> ${driver.label}`);
+    return connectionId;
+  }
+  has(connectionId) {
+    return this.connections.has(connectionId);
+  }
+  /**
+   * Execute a SQL query on an existing connection.
+   * Optionally switch database before executing (drivers that support it).
+   */
+  async query(connectionId, sql, database) {
+    const driver = this.connections.get(connectionId);
+    if (!driver) {
+      throw new Error(`Connection not found: ${connectionId}`);
+    }
+    this.lastUsed.set(connectionId, Date.now());
+    return driver.query(sql, database);
+  }
+  /**
+   * Close and remove a connection.
+   */
+  async disconnect(connectionId) {
+    const driver = this.connections.get(connectionId);
+    if (!driver) {
+      throw new Error(`Connection not found: ${connectionId}`);
+    }
+    await driver.close();
+    this.connections.delete(connectionId);
+    this.lastUsed.delete(connectionId);
+    console.log(`[ConnectionManager] Disconnected: ${connectionId}`);
+  }
+  /**
+   * Validate a config by opening and immediately closing a connection.
+   */
+  async testConnection(config) {
+    await testDriver(config);
+    return true;
+  }
+  /**
+   * Get the number of active connections.
+   */
+  get activeConnections() {
+    return this.connections.size;
+  }
+  /**
+   * Close all connections (for graceful shutdown).
+   */
+  async disconnectAll() {
+    const promises = Array.from(this.connections.entries()).map(
+      async ([id, driver]) => {
+        try {
+          await driver.close();
+          console.log(`[ConnectionManager] Disconnected: ${id}`);
+        } catch {
+        }
+      }
+    );
+    await Promise.all(promises);
+    this.connections.clear();
+    this.lastUsed.clear();
+  }
+};
+
+// src/server.ts
+function fail(res, status, message) {
+  res.status(status).json({ success: false, message });
+}
+var errorMessage = (err) => err instanceof Error ? err.message : String(err);
+function tokenMatches(header, expected) {
+  if (!header?.startsWith("Bearer ")) return false;
+  const given = Buffer.from(header.slice(7));
+  const want = Buffer.from(expected);
+  return given.length === want.length && timingSafeEqual(given, want);
+}
+function accessControl(allowed) {
+  return (req, res, next) => {
+    const origin = req.headers.origin;
+    if (origin === void 0) {
+      next();
+      return;
+    }
+    if (!allowed.has(origin)) {
+      fail(res, 403, `Origin not allowed: ${origin}`);
+      return;
+    }
+    res.setHeader("Access-Control-Allow-Origin", origin);
+    res.setHeader("Vary", "Origin");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type");
+    res.setHeader("Access-Control-Max-Age", "600");
+    if (req.headers["access-control-request-private-network"] === "true") {
+      res.setHeader("Access-Control-Allow-Private-Network", "true");
+    }
+    if (req.headers["access-control-request-local-network"] === "true") {
+      res.setHeader("Access-Control-Allow-Local-Network", "true");
+    }
+    if (req.method === "OPTIONS") {
+      res.sendStatus(204);
+      return;
+    }
+    next();
+  };
+}
+function createAgent(options) {
+  const app = express();
+  const manager = new ConnectionManager();
+  const allowedOrigins = new Set(options.allowedOrigins.map((o) => o.replace(/\/+$/, "")));
+  if (options.logRequests) {
+    app.use((req, _res, next) => {
+      const hasAuth = !!req.headers.authorization;
+      console.log(`[${(/* @__PURE__ */ new Date()).toISOString()}] ${req.method} ${req.url} (auth: ${hasAuth})`);
+      next();
+    });
+  }
+  app.use(accessControl(allowedOrigins));
+  app.use(express.json({ limit: options.bodyLimit }));
+  app.use((req, res, next) => {
+    if (req.path === "/health") {
+      next();
+      return;
+    }
+    if (!tokenMatches(req.headers.authorization, options.authToken)) {
+      fail(res, 401, "Unauthorized: invalid or missing auth token");
+      return;
+    }
+    next();
+  });
+  app.get("/health", (req, res) => {
+    const body = {
+      success: true,
+      name: "planche",
+      version: options.version,
+      protocolVersion: PROTOCOL_VERSION,
+      activeConnections: manager.activeConnections,
+      uptime: process.uptime()
+    };
+    if (req.headers.authorization !== void 0) {
+      body.authorized = tokenMatches(req.headers.authorization, options.authToken);
+    }
+    res.json(body);
+  });
+  app.post("/connect", async (req, res) => {
+    try {
+      const config = parseDriverConfig(req.body ?? {});
+      const connectionId = await manager.connect(config);
+      res.json({ success: true, connectionId, message: "Connection Successful" });
+    } catch (err) {
+      const message = errorMessage(err);
+      console.error("[connect] Error:", message);
+      fail(res, 400, message);
+    }
+  });
+  app.post("/query", async (req, res) => {
+    try {
+      const { connectionId, sql, database } = req.body;
+      if (typeof connectionId !== "string" || typeof sql !== "string" || !connectionId || !sql) {
+        fail(res, 400, "connectionId and sql are required");
+        return;
+      }
+      if (!manager.has(connectionId)) {
+        fail(res, 404, `Connection not found: ${connectionId}`);
+        return;
+      }
+      const start = Date.now();
+      const result = await manager.query(connectionId, sql, database);
+      const execTime = Date.now() - start;
+      res.json({
+        success: true,
+        fields: result.fields,
+        records: result.records,
+        affectedRows: result.affectedRows,
+        insertId: result.insertId,
+        isResultQuery: result.isResultQuery,
+        execTime
+      });
+    } catch (err) {
+      const message = errorMessage(err);
+      console.error("[query] Error:", message);
+      fail(res, 422, message);
+    }
+  });
+  app.post("/disconnect", async (req, res) => {
+    try {
+      const { connectionId } = req.body;
+      if (typeof connectionId !== "string" || !connectionId) {
+        fail(res, 400, "connectionId is required");
+        return;
+      }
+      if (!manager.has(connectionId)) {
+        fail(res, 404, `Connection not found: ${connectionId}`);
+        return;
+      }
+      await manager.disconnect(connectionId);
+      res.json({ success: true, message: "Disconnected" });
+    } catch (err) {
+      const message = errorMessage(err);
+      console.error("[disconnect] Error:", message);
+      fail(res, 500, message);
+    }
+  });
+  app.post("/test-connection", async (req, res) => {
+    try {
+      await manager.testConnection(parseDriverConfig(req.body ?? {}));
+      res.json({ success: true, message: "Connection test successful" });
+    } catch (err) {
+      const message = errorMessage(err);
+      console.error("[test-connection] Error:", message);
+      fail(res, 400, message);
+    }
+  });
+  return { app, manager };
+}
+
+// src/index.ts
+var { version: VERSION } = createRequire(import.meta.url)("../package.json");
+var DEFAULT_APP_URL = "https://planche.dev";
+var DEV_ORIGINS = [
+  "http://localhost:5173",
+  "http://127.0.0.1:5173",
+  "http://localhost:4173",
+  "http://127.0.0.1:4173"
+];
+function usage() {
+  return `planche ${VERSION} \u2014 local agent for the Planche SQL client
+
+Usage: planche [options]
+
+Options:
+  -p, --port <n>       Port to listen on (default: 8888, env PLANCHE_PORT)
+      --addr <host>    Address to bind (default: 127.0.0.1, env PLANCHE_ADDR)
+      --token <str>    Auth token (default: random, env PLANCHE_AUTH_TOKEN)
+      --app <url>      Web app to open (default: ${DEFAULT_APP_URL}, env PLANCHE_APP_URL)
+      --origin <url>   Extra browser origin allowed to use the agent (repeatable,
+                       env PLANCHE_ALLOWED_ORIGINS as a comma-separated list)
+      --no-open        Do not open the browser
+      --verbose        Log every request
+  -v, --version        Print the version
+  -h, --help           Show this help
+`;
+}
+function splitList(value) {
+  return (value ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+}
+function originOf(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+function openInBrowser(url) {
+  const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url.replace(/&/g, "^&")]] : ["xdg-open", [url]];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).on("error", () => void 0).unref();
+  } catch {
+  }
+}
+function main() {
+  let values;
+  try {
+    values = parseArgs({
+      options: {
+        port: { type: "string", short: "p" },
+        addr: { type: "string" },
+        token: { type: "string" },
+        app: { type: "string" },
+        origin: { type: "string", multiple: true },
+        open: { type: "boolean" },
+        verbose: { type: "boolean" },
+        version: { type: "boolean", short: "v" },
+        help: { type: "boolean", short: "h" }
+      },
+      allowNegative: true,
+      strict: true
+    }).values;
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    console.error(usage());
+    process.exit(2);
+  }
+  const flags = values;
+  if (flags.help) {
+    console.log(usage());
+    return;
+  }
+  if (flags.version) {
+    console.log(VERSION);
+    return;
+  }
+  const port = Number(flags.port ?? process.env.PLANCHE_PORT) || 8888;
+  const addr = flags.addr ?? process.env.PLANCHE_ADDR ?? "127.0.0.1";
+  const tokenFromEnv = !flags.token && !!process.env.PLANCHE_AUTH_TOKEN;
+  const authToken = flags.token ?? process.env.PLANCHE_AUTH_TOKEN ?? randomUUID2();
+  const appUrl = (flags.app ?? process.env.PLANCHE_APP_URL ?? DEFAULT_APP_URL).replace(/\/+$/, "");
+  const shouldOpen = flags.open ?? true;
+  const bodyLimit = process.env.PLANCHE_BODY_LIMIT || "50mb";
+  const appOrigin = originOf(appUrl);
+  if (!appOrigin) {
+    console.error(`Invalid --app URL: ${appUrl}`);
+    process.exit(2);
+  }
+  const allowedOrigins = [
+    appOrigin,
+    ...DEV_ORIGINS,
+    ...flags.origin ?? [],
+    ...splitList(process.env.PLANCHE_ALLOWED_ORIGINS)
+  ];
+  const { app, manager } = createAgent({
+    authToken,
+    allowedOrigins,
+    bodyLimit,
+    version: VERSION,
+    logRequests: flags.verbose ?? false
+  });
+  const agentUrl = `http://${addr}:${port}`;
+  const pairUrl = `${appUrl}/#agent=${encodeURIComponent(agentUrl)}&token=${encodeURIComponent(authToken)}`;
+  const server = app.listen(port, addr, () => {
+    const line = "-".repeat(72);
+    console.log(line);
+    console.log(`Planche agent ${VERSION} listening on ${agentUrl}`);
+    console.log(line);
+    console.log(`Open the app with:
+
+  ${pairUrl}
+`);
+    console.log(tokenFromEnv ? "Auth token: (from PLANCHE_AUTH_TOKEN)" : `Auth token: ${authToken}`);
+    console.log(`Allowed origins: ${allowedOrigins.join(", ")}`);
+    if (!["127.0.0.1", "localhost", "::1"].includes(addr)) {
+      console.log(`WARNING: bound to ${addr} \u2014 anyone who can reach this port and knows the token can use your databases.`);
+    }
+    console.log(line);
+    if (shouldOpen) openInBrowser(pairUrl);
+  });
+  server.on("error", (err) => {
+    if (err.code === "EADDRINUSE") {
+      console.error(`Port ${port} is already in use. Is another agent running? Use --port to pick another.`);
+    } else {
+      console.error(err.message);
+    }
+    process.exit(1);
+  });
+  const shutdown = async () => {
+    console.log("\nShutting down...");
+    await manager.disconnectAll();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+main();

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "planche",
+  "version": "0.1.0",
+  "description": "Local agent for Planche — lets the browser-based Planche SQL client reach MySQL/MariaDB/PostgreSQL/SQLite databases from your machine.",
+  "license": "MIT",
+  "homepage": "https://planche.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/plancheproject/planche-reboot.git",
+    "directory": "server"
+  },
+  "type": "module",
+  "bin": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "planche",
+    "mysql",
+    "mariadb",
+    "postgres",
+    "postgresql",
+    "sqlite",
+    "sql",
+    "client",
+    "gui"
+  ],
+  "scripts": {
+    "dev": "tsx watch --env-file-if-exists=.env src/index.ts --no-open --app http://localhost:5173",
+    "start": "tsx --env-file-if-exists=.env src/index.ts",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit -p .",
+    "prepublishOnly": "yarn typecheck && yarn build"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.11.1",
+    "express": "^5.1.0",
+    "mysql2": "^3.14.1",
+    "pg": "^8.23.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/express": "^5.0.0",
+    "@types/node": "^24.0.0",
+    "@types/pg": "^8.23.1",
+    "tsup": "^8.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.0"
+  }
+}