latticesql 1.13.6 → 1.13.8

package/README.md

@@ -65,6 +65,7 @@ Lattice has no opinions about your schema, your agents, or your file format. You
 - [Examples](#examples)
 - [Staying up to date](#staying-up-to-date)
   - [Auto-update](#auto-update-v11)
+- [Telemetry](#telemetry)
 - [Contributing](#contributing)
 - [Changelog](#changelog)
 
@@ -2158,7 +2159,29 @@ await db.init();
 | `~/.lattice/keys/<label>.token` | Per-joined-team bearer tokens (`chmod 0600`)                                                             |
 | `~/.lattice/db-credentials.enc` | AES-GCM-encrypted Postgres URLs keyed by label                                                           |
 
-The GUI's User Config view edits `identity.json` directly; the Project Config "Database" panel writes saved Postgres URLs into `db-credentials.enc` and rewrites `lattice.config.yml`'s `db:` line to `${LATTICE_DB:<label>}`. The config parser resolves that reference at open time so connection passwords never sit in YAML on disk.
+The GUI's User Settings view edits `identity.json` directly; the Database Settings page writes saved Postgres URLs into `db-credentials.enc` and rewrites `lattice.config.yml`'s `db:` line to `${LATTICE_DB:<label>}`. The config parser resolves that reference at open time so connection passwords never sit in YAML on disk.
+
+`~/.lattice/preferences.json` (v1.13.8+) holds machine-local UI preferences keyed by name. Currently a single flag `show_system_tables: boolean` (default `false`) — see _Sidebar system-tables toggle (v1.13.8+)_ below.
+
+**Information architecture, v1.13.8+.** The GUI treats every database as either Local (single-user SQLite) or Cloud (Postgres, one or more invited team members), with the database itself as the first-class concept. "Team" describes the set of members on a cloud database — there is no separate "create a team" step, and the verbiage for member management ("Invite Team", "Join Team", "Team Members") stays where it belongs. Concretely:
+
+- **Editable database name** at the top of Database Settings. For cloud DBs the rename writes `__lattice_team_identity.team_name` (and broadcasts to every member via the realtime channel below); for local DBs it writes a `name:` key into the YAML config, parsed by `parseConfigFile()` and surfaced as `ParsedConfig.name`. New endpoint `POST /api/dbconfig/rename`.
+- **Three-step Create Database wizard.** Opened from the header dropdown's `+ New database` button and from Lattice Settings → Add new database. Step 1: name + Local|Cloud + cloud credentials. Step 2: starter entities, each with a pre-checked "Share with cloud" checkbox when cloud. Step 3: review + create.
+- **Header dropdown** shows the friendly database name + a Local|Cloud kind chip + a connectivity dot per row (green = cloud live, yellow = local SQLite, red = cloud disconnected). The `+ New database` button at the bottom opens the wizard.
+- **Settings sidebar** is reorganized into Lattice Settings (catalog of all databases this lattice can reach + Add-new entry), Database Settings (renamed from Project Config — editable name header on top, the existing Database panel and cloud-databases list below), Data Model, and User Settings. The legacy `/settings/project-config` route still resolves for back-compat.
+- **Migrate-to-Cloud per-table share checkboxes.** The migrate modal lists every user-defined table with "Share with cloud" pre-checked; uncheck individual tables to keep them cloud-stored but unshared. After the migrate, only checked tables call `shareObject`.
+- **New-entity flow** on a cloud-connected database pre-checks a "Share with cloud" box; the share runs best-effort after the entity is created.
+
+**Realtime cloud subscriptions (v1.13.8+).** Cloud Postgres-backed lattices stream changes to every connected GUI in realtime. A Postgres trigger on `__lattice_change_log` emits `pg_notify('lattice_changes', …)` after every insert; the GUI server holds a dedicated `pg.Client` with `LISTEN lattice_changes` and fans payloads out via a new Server-Sent Events endpoint:
+
+| Route                  | Method | Description                                                                      |
+| ---------------------- | ------ | -------------------------------------------------------------------------------- |
+| `/api/realtime/stream` | GET    | SSE stream; `event: state` on connection transitions, `event: change` per NOTIFY |
+| `/api/realtime/status` | GET    | JSON snapshot of `{ mode: 'local'\|'cloud', state, connected }`                  |
+
+The browser's `EventSource` invalidates the entity cache on every `change` event; connection state drives a colored dot in the topbar (green/yellow/red). SQLite databases are unchanged — LISTEN/NOTIFY is Postgres-only and the broker is skipped on those. The trigger installer (`installCloudInternalTriggers`) is exported from `latticesql/teams/internal-tables` for callers that bootstrap cloud schemas outside the GUI.
+
+**Sidebar system-tables toggle (v1.13.8+).** Internal `__lattice_*` and `_lattice_gui_*` tables are hidden from the sidebar by default. Enable the "Show system tables in sidebar" checkbox in User Settings → Preferences to surface them under a "System" section. Persisted to `~/.lattice/preferences.json`; exposed via `GET`/`POST /api/userconfig/preferences`.
 
 ---
 
@@ -2201,6 +2224,8 @@ The cloud rejects redemption if the caller's claimed email doesn't match the inv
 
 **Same flows from the GUI.** The local `lattice gui` Project Config view drives the entire teams lifecycle — create / join, invite by email, share tables, link rows, see sync status. Identity (display name + email) comes from `~/.lattice/identity.json` and is prefilled in every modal.
 
+**Joining via the GUI is one click (v1.13.7+).** When you click "Join via invite" and the redeem succeeds, the team's cloud URL is automatically saved as a switchable database credential and a sibling YAML config is written to your project directory. The new entry shows up in the database dropdown as `<team-name>.config`. Clicking it opens the SPA with the team's shared tables already populated — no YAML editing, no `db.define()` calls.
+
 **Cloud server mode**: `lattice gui --team-cloud` boots the same binary as a cloud server. It exposes the bearer-token-gated `/api/team*` endpoints + the `/objects`/`/changes`/`/rows`/`/links` sync routes, and disables the local dev-tool surface (table viewer, CRUD endpoints, register-and-create modal).
 
 The full architecture, schema, and HTTP surface live in [docs/teams.md](./docs/teams.md).
@@ -2566,6 +2591,45 @@ interface AutoUpdateResult {
 
 ---
 
+## Telemetry
+
+`latticesql` includes [Scarf](https://scarf.sh) install analytics so we can understand how the package is used in the wild — what versions are running, on what platforms, at roughly what scale. This signal is what lets us prioritize fixes, deprecations, and new features against real usage instead of guesswork.
+
+**What is sent — once, at `npm install` time, by the `@scarf/scarf` postinstall hook:**
+
+- Package name + version (e.g. `latticesql@1.13.6`)
+- Node.js version, OS, CPU architecture
+- A coarse, non-identifying hash derived from the install host (Scarf's default — used for deduplication, not identification)
+- The public IP of the install request (visible to any HTTPS endpoint; not stored long-term by Scarf)
+
+**What is NOT sent:**
+
+- No data from your application code, schemas, rows, or query strings
+- No environment variables, file paths, hostnames, or usernames
+- No runtime telemetry — `latticesql` makes zero outbound telemetry calls after install. The only network requests it makes at runtime are the explicit `checkForUpdate()` / `autoUpdate()` calls to `registry.npmjs.org`, which you opt into by calling them.
+
+**How to opt out** — any one of these suppresses the install ping:
+
+```bash
+# Per-install (recommended for CI):
+SCARF_ANALYTICS=false npm install latticesql
+
+# Or, project-wide (add to .npmrc):
+scarf-analytics=false
+
+# Or, the cross-tool standard:
+DO_NOT_TRACK=1 npm install latticesql
+
+# Or, disable all postinstall scripts entirely:
+npm install latticesql --ignore-scripts
+```
+
+Opting out has no effect on functionality — the package works identically. The Scarf postinstall is a fire-and-forget HTTPS ping with a short timeout; even when enabled it cannot fail your install.
+
+See Scarf's own [privacy documentation](https://docs.scarf.sh) for the upstream policy.
+
+---
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for dev setup, test commands, and contribution guidelines.