@promptowl/contextnest-community 1.4.0 → 1.6.0

package/CONFIGURATION.md

@@ -45,7 +45,15 @@ The server prints a loud warning at startup when `AUTH_MODE=open` is active.
 |---|---|---|
 | `PORT` | `3838` | HTTP port the server listens on. |
 | `DATA_ROOT` | `./data` (relative to cwd) | Root directory for SQLite DB + nest filesystem vaults. Set to an absolute path in production so it's independent of where you `cd`'d from. |
-| `DATABASE_PATH` | `$DATA_ROOT/community.db` | Override the SQLite file location explicitly. |
+| `DATABASE_PATH` | `$DATA_ROOT/community.db` | Override the SQLite file location explicitly. (SQLite backend only.) |
+| `NEST_STORAGE_ROOT` | `$DATA_ROOT/nests` | Root directory for nest vault files (markdown + version history). Override to store nests separately from the DB — e.g. point it at a Cloud Storage (GCS) volume mount on Cloud Run (`/mnt/nests`) while the SQLite DB stays on `DATA_ROOT` off the mount. **Moving existing nests:** the app does not relocate files — copy `$DATA_ROOT/nests/*` to the new root (e.g. `gsutil rsync`) before switching, or existing nests will appear empty (DB rows present, files missing). On a GCS mount, also set `DRIFT_SCAN_INTERVAL_MS=0` to avoid constant FUSE scans, and run a single instance (GCS FUSE has no file locking — concurrent writers lose data). |
+| `DB_DRIVER` | `sqlite` | Database backend: `sqlite` (default) or `postgres`. When unset, the server infers `postgres` if `DATABASE_URL` or `CLOUD_SQL_CONNECTION_NAME` is set, else `sqlite`. Existing deployments need no change — they stay on SQLite. See [Database backends](#database-backends). |
+| `DATABASE_URL` | `""` | PostgreSQL connection string for a TCP connection, e.g. `postgres://user:pass@host:5432/dbname`. Setting it selects the Postgres backend (unless `DB_DRIVER=sqlite`). |
+| `CLOUD_SQL_CONNECTION_NAME` | `""` | Cloud SQL instance connection name (`project:region:instance`). When set, the server connects over the Cloud SQL Auth Proxy unix socket at `/cloudsql/<name>` — the recommended Cloud Run setup. Combine with `DB_USER`, `DB_PASSWORD`, `DB_NAME`. |
+| `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME` | `localhost` / `5432` / `""` / `""` / `""` | Discrete Postgres connection params, used when neither `CLOUD_SQL_CONNECTION_NAME` nor `DATABASE_URL` is set. |
+| `DB_POOL_MAX` | `10` | Max Postgres pool connections. Keep modest — Cloud SQL tiers cap total connections. |
+| `DB_SSL` | `false` | Set `true` to require TLS on a Postgres TCP connection (not needed over the Cloud SQL unix socket, which is already secure). |
+| `DB_SSL_CA` | `""` | Path to a CA certificate (PEM) for verify-ca/verify-full TLS when `DB_SSL=true`. |
 | `AUTH_MODE` | `key` | `key` or `open`. See above. |
 | `PROMPTOWL_API_URL` | `https://app.promptowl.ai` | PromptOwl's API origin — used for device auth, license validation, telemetry. Override for air-gapped or test setups. |
 | `PROMPTOWL_KEY` | `""` | Your PromptOwl Community License key (`pk_...`). Unlicensed instances still run and serve reads, but every write returns `503` until a valid key is installed. Can also be set via the browser License Setup Page, which persists it to `ENV_FILE_PATH`. |
@@ -61,6 +69,56 @@ The server prints a loud warning at startup when `AUTH_MODE=open` is active.
 
 ---
 
+## Database backends
+
+The governance/auth metadata (users, sessions, nests registry, stewards, reviews,
+versions index, comments, telemetry) is stored in a relational database. Two
+backends are supported:
+
+- **SQLite (default).** A single file at `DATABASE_PATH`. Zero-config, ideal for
+  single-box and local deployments. Nothing changes for existing installs.
+- **PostgreSQL / Cloud SQL.** For deployments where local disk isn't durable
+  (e.g. Google Cloud Run, where the container filesystem is ephemeral). Selected
+  by setting `DB_DRIVER=postgres`, `DATABASE_URL`, or `CLOUD_SQL_CONNECTION_NAME`.
+
+On first connect the server creates its schema automatically (idempotent) — no
+manual migration step. There is no built-in SQLite→Postgres data migration; a new
+Postgres backend starts empty.
+
+> ⚠️ **Cloud Run durability — read this.** Cloud SQL persists only the *metadata
+> database*. The actual **document content and version history** live on the
+> filesystem under `$DATA_ROOT/nests/`, which on Cloud Run is **ephemeral** and is
+> lost when an instance is recycled. Using Cloud SQL alone does **not** make a
+> Cloud Run deployment fully durable. You must also put `$DATA_ROOT` on persistent,
+> shared storage — e.g. mount a GCS bucket via Cloud Storage FUSE, or use a
+> persistent volume — otherwise documents will disappear on redeploy/scale-in.
+
+### Cloud Run + Cloud SQL (PostgreSQL)
+
+Attach the Cloud SQL instance to the service (`--add-cloudsql-instances`) so the
+Auth Proxy unix socket appears at `/cloudsql/<connection-name>`, then:
+
+```bash
+DB_DRIVER=postgres \
+CLOUD_SQL_CONNECTION_NAME=my-project:us-central1:contextnest \
+DB_USER=contextnest \
+DB_PASSWORD=*** \
+DB_NAME=contextnest \
+DATA_ROOT=/mnt/vault \   # mount GCS/persistent storage here — see warning above
+PROMPTOWL_KEY=pk_... \
+node dist/index.js
+```
+
+Or with a plain TCP connection string (e.g. the Cloud SQL Proxy running on
+localhost, or a private IP):
+
+```bash
+DATABASE_URL=postgres://contextnest:***@127.0.0.1:5432/contextnest \
+DB_DRIVER=postgres \
+DATA_ROOT=/mnt/vault \
+npm start
+```
+
 ## Typical deployments
 
 ### Local dev / single user
@@ -86,7 +144,7 @@ Terminate TLS at the proxy, forward `X-Forwarded-For` and `X-Real-IP` headers (t
 ### Hosted / commercial SaaS
 
 Same as team, plus:
-- Run N instances behind a load balancer sharing a network-attached `DATA_ROOT` (note: SQLite + shared filesystem is not a great long-term story — migrate to the MongoDB storage adapter when scaling beyond one box).
+- Run N instances behind a load balancer. SQLite + a shared filesystem is not a great long-term story for the metadata DB when scaling beyond one box — switch to the **PostgreSQL / Cloud SQL** backend (see [Database backends](#database-backends)) so all instances share one consistent database. The on-disk nest vault under `$DATA_ROOT/nests/` still needs durable shared storage.
 - Set `TELEMETRY_ENABLED=true` and a valid `PROMPTOWL_KEY` so usage rolls up to PromptOwl.
 - Rotate keys regularly via `DELETE /auth/keys/:id` + `POST /auth/keys`.
 

package/README.md

@@ -89,6 +89,8 @@ For redistribution, hosted-service, OEM, or regulated-industry licensing, contac
 | Feature | Community Edition | Enterprise |
 |---|:---:|:---:|
 | Self-hosted context server | ✅ | ✅ |
+| SQLite or PostgreSQL / Cloud SQL backend | ✅ | ✅ |
+| Configurable nest storage (external / GCS volume mount) | ✅ | ✅ |
 | Markdown + YAML frontmatter vaults | ✅ | ✅ |
 | Import existing folder / vault | ✅ | ✅ |
 | Markdown rendering + wiki cross-linking | ✅ | ✅ |
@@ -110,6 +112,17 @@ For redistribution, hosted-service, OEM, or regulated-industry licensing, contac
 
 For Enterprise pricing and features, contact **hoot@promptowl.ai** or visit <https://promptowl.ai/contextnest/>.
 
+## What's new in 1.6.0
+
+- **PostgreSQL / Cloud SQL backend** — run the server on PostgreSQL alongside SQLite via an async DB adapter, so metadata survives on Cloud Run and other deployments where local disk isn't durable. Supports the Cloud SQL Auth Proxy (unix socket) and TCP + TLS. New `DB_*` env vars (`DB_DRIVER`, `DATABASE_URL`, `CLOUD_SQL_CONNECTION_NAME`, `DB_HOST`/`DB_PORT`/`DB_USER`/`DB_PASSWORD`/`DB_NAME`, `DB_POOL_MAX`, `DB_SSL`, `DB_SSL_CA`); SQLite stays the default when nothing is configured. See [CONFIGURATION.md](./CONFIGURATION.md).
+- **Configurable `NEST_STORAGE_ROOT`** — store nest vault files (markdown + version history) outside `DATA_ROOT` — e.g. on a Cloud Storage (GCS) volume mount — while the database stays on `DATA_ROOT`. Defaults to `<DATA_ROOT>/nests`, so existing deployments are unchanged. On a GCS FUSE mount, set `DRIFT_SCAN_INTERVAL_MS=0` and run a single instance.
+- **Security fix** — the admin guard on `/admin/settings` (GET/PATCH) is now correctly awaited; without it a non-admin could read or change server-wide settings in key mode.
+- **AdminLoginModal respects `PROMPTOWL_SIGN_IN_GATE`** — the "Sign in with PromptOwl" affordance follows the configured gate (`open` / `admin-only` / `disabled`).
+- **Drift scanner toggle** — `DRIFT_SCAN_INTERVAL_MS=0` now actually disables the drift scanner (previously reset to the 30s default).
+- **Safer folder sync** — unsynced-folder detection no longer treats a configured nest storage root as a sync candidate, preventing accidental duplication/removal of live nests when `NEST_STORAGE_ROOT` is nested under `DATA_ROOT`.
+
+Full history in [CHANGELOG.md](./CHANGELOG.md).
+
 ## What's new in 1.3.0
 
 - **Server super-admins** — emails listed in `access.yaml: super_admins` administer every nest (change visibility, manage collaborators and stewards) without being added per-nest. Owner-only operations (delete, transfer) still require the nest owner. See [STEWARDSHIP.md](./STEWARDSHIP.md).

package/dist/adapter.postgres-YOODX2BI.js

@@ -0,0 +1,71 @@
+// src/db/adapter.postgres.ts
+function translatePlaceholders(sql) {
+  let out = "";
+  let inStr = false;
+  let n = 0;
+  for (let i = 0; i < sql.length; i++) {
+    const ch = sql[i];
+    if (ch === "'") {
+      inStr = !inStr;
+      out += ch;
+    } else if (ch === "?" && !inStr) {
+      out += "$" + ++n;
+    } else {
+      out += ch;
+    }
+  }
+  return out;
+}
+var PgQuerier = class {
+  constructor(q) {
+    this.q = q;
+  }
+  q;
+  async get(sql, params = []) {
+    const res = await this.q.query(translatePlaceholders(sql), params);
+    return res.rows[0];
+  }
+  async all(sql, params = []) {
+    const res = await this.q.query(translatePlaceholders(sql), params);
+    return res.rows;
+  }
+  async run(sql, params = []) {
+    const res = await this.q.query(translatePlaceholders(sql), params);
+    return { changes: res.rowCount ?? 0 };
+  }
+  async exec(sql) {
+    await this.q.query(sql);
+  }
+};
+var PostgresAdapter = class extends PgQuerier {
+  constructor(pool) {
+    super(pool);
+    this.pool = pool;
+  }
+  pool;
+  dialect = "postgres";
+  async transaction(fn) {
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      const result = await fn(new PgQuerier(client));
+      await client.query("COMMIT");
+      return result;
+    } catch (err) {
+      try {
+        await client.query("ROLLBACK");
+      } catch {
+      }
+      throw err;
+    } finally {
+      client.release();
+    }
+  }
+  async close() {
+    await this.pool.end();
+  }
+};
+export {
+  PostgresAdapter,
+  translatePlaceholders
+};