naro-mcp 0.19.0 → 0.20.0

package/dist/index.js

@@ -15334,6 +15334,7 @@ var NaroClient = class {
   db;
   backend;
   storage;
+  realtime;
   insights;
   analytics;
   protection;
@@ -15353,6 +15354,7 @@ var NaroClient = class {
     this.db = new DbApi(this);
     this.backend = new BackendApi(this);
     this.storage = new StorageApi(this);
+    this.realtime = new RealtimeApi(this);
     this.insights = new InsightsApi(this);
     this.analytics = new AnalyticsApi(this);
     this.protection = new ProtectionApi(this);
@@ -16378,9 +16380,9 @@ function storageInfo(body) {
     buckets: (body.buckets ?? []).map(storageBucket)
   };
 }
-function storageRunFailure(error51) {
+function provisionFailure(error51, feature) {
   const details = isNaroError(error51) ? error51.details : void 0;
-  if (isNaroError(error51) && error51.code === "BACKEND_PROVISION_FAILED" && isRecord(details?.storage) && isRecord(details.backend))
+  if (isNaroError(error51) && error51.code === "BACKEND_PROVISION_FAILED" && isRecord(details?.[feature]) && isRecord(details.backend))
     return new NaroError(error51.code, error51.message, {
       ...error51.status !== void 0 ? { status: error51.status } : {},
       details: {
@@ -16818,7 +16820,7 @@ var StorageApi = class {
         }
       );
     } catch (error51) {
-      throw storageRunFailure(error51);
+      throw provisionFailure(error51, "storage");
     }
     return storageInfo(body.storage);
   }
@@ -16856,7 +16858,7 @@ var StorageApi = class {
         }
       );
     } catch (error51) {
-      throw storageRunFailure(error51);
+      throw provisionFailure(error51, "storage");
     }
     return storageInfo(body.storage);
   }
@@ -17015,6 +17017,114 @@ var StorageApi = class {
     return body.objects;
   }
 };
+var RealtimeApi = class {
+  constructor(client) {
+    this.client = client;
+  }
+  path(projectId, suffix = "") {
+    return `/api/projects/${encodeURIComponent(projectId)}/backend/realtime${suffix}`;
+  }
+  /**
+   * Like `StorageApi.bucketPath`: URL parsing folds `.` and `..`, an empty
+   * name is the collection, and `encodeURIComponent` throws on a lone
+   * surrogate — so a name no URL can carry is refused here, before a
+   * request. SQLite does make tables named `.` and `..`, and one with the
+   * empty name (`CREATE TABLE "" (a)`); such a table cannot be published
+   * or unpublished through this API.
+   */
+  tablePath(projectId, table) {
+    if (table === "" || table === "." || table === ".." || LONE_SURROGATE.test(table))
+      throw new NaroError("INVALID_PATH", "The table name is not valid.");
+    return this.path(projectId, `/tables/${encodeURIComponent(table)}`);
+  }
+  /**
+   * Whether Realtime is on, the limits the hub enforces, the published
+   * tables and the hub's own numbers. A project that never turned it on
+   * answers `enabled: false` with no tables.
+   */
+  async info(projectId) {
+    const body = await this.client.request(
+      this.path(projectId),
+      { context: "Read realtime" }
+    );
+    return body.realtime;
+  }
+  /**
+   * Turns Realtime on: the request and the plan's limits are recorded, and
+   * the Naro worker is uploaded again with its hub (a Durable Object). Safe
+   * to repeat, and a repair — also after a plan change. The project must have
+   * a backend, turned on, with its database. A backend in `error` or with a
+   * run that stalled is not refused: its provisioning is resumed on the way.
+   * Two minutes, like `backend.enable`.
+   *
+   * Refusals, in the order they are checked: `BACKEND_DISABLED` (the control
+   * plane's backend switch), `FORBIDDEN` (`database.write`),
+   * `REALTIME_DISABLED` (the control plane's Realtime switch),
+   * `DATABASE_NOT_ENABLED` (the project's database is external),
+   * `BACKEND_NOT_READY` (409, only when the project has no backend at all),
+   * `BACKEND_OFF`, `BACKEND_BUSY`, `REALTIME_ENABLE_FAILED` (502: the request
+   * could not be recorded; nothing changed), and `BACKEND_PROVISION_FAILED`
+   * (502) when Realtime is recorded as on but the worker's upload stopped.
+   * The last one's `details` hold a `RealtimeProvisionFailure` — `{ realtime:
+   * { applied: false, enabled: true }, backend }`, the backend read like
+   * `backend.info` — and `enable` again finishes.
+   */
+  async enable(projectId) {
+    let body;
+    try {
+      body = await this.client.request(
+        this.path(projectId),
+        {
+          method: "POST",
+          context: "Turn on Realtime",
+          timeoutMs: PROVISION_TIMEOUT_MS
+        }
+      );
+    } catch (error51) {
+      throw provisionFailure(error51, "realtime");
+    }
+    return body.realtime;
+  }
+  /**
+   * The tables whose Data API writes are published, in the order they were
+   * published. `exists: false` is a published name whose table was dropped.
+   * `REALTIME_NOT_ENABLED` (409) before `enable`; it answers while the
+   * backend is off, since the list is in the project's database.
+   */
+  async listTables(projectId) {
+    const body = await this.client.request(
+      this.path(projectId, "/tables"),
+      { context: "List realtime tables" }
+    );
+    return body.tables;
+  }
+  /**
+   * Publishes a table's changes to the subscribers of its channel. Safe to
+   * repeat. Only changes made through the Data API are published — writes
+   * the app makes with `env.DB` are not (`warnings` says so).
+   * `TABLE_NOT_FOUND` (404) for a table that does not exist;
+   * `VALIDATION_FAILED` (400) for a Naro system table, a virtual table, a
+   * name over 256 characters, or the 100-table cap; `REALTIME_NOT_ENABLED`
+   * (409) before `enable`.
+   */
+  async publishTable(projectId, table) {
+    return this.client.request(
+      this.tablePath(projectId, table),
+      { method: "PUT", context: "Publish a realtime table" }
+    );
+  }
+  /**
+   * Stops publishing a table's changes; a table dropped since can still be
+   * unpublished. `TABLE_NOT_PUBLISHED` (404) for a table that does not
+   * publish, `REALTIME_NOT_ENABLED` (409) before `enable`.
+   */
+  async unpublishTable(projectId, table) {
+    return this.client.request(
+      this.tablePath(projectId, table),
+      { method: "DELETE", context: "Stop publishing a realtime table" }
+    );
+  }
+};
 
 // ../../packages/sdk/src/database.ts
 var BOOKMARK_RE = /^[0-9a-f]{8}-[0-9a-f]{8}-[0-9a-f]{8}-[0-9a-f]{32}$/;
@@ -17041,6 +17151,39 @@ var MAX_FILE_BYTES2 = 1024 * 1024;
 import { existsSync as existsSync3, readFileSync as readFileSync4 } from "fs";
 import { join as join4 } from "path";
 
+// ../../packages/data-core/src/system-tables.ts
+var SYSTEM_TABLE_PREFIXES = [
+  "_naro_",
+  "_cf_",
+  "sqlite_"
+];
+var SYSTEM_TABLE_NAMES = ["d1_migrations"];
+function asciiLower(text) {
+  return text.replace(/[A-Z]+/g, (run) => run.toLowerCase());
+}
+function isSystemTable(name) {
+  const lower = asciiLower(name);
+  return SYSTEM_TABLE_PREFIXES.some((prefix) => lower.startsWith(prefix)) || SYSTEM_TABLE_NAMES.includes(lower);
+}
+function likeLiteral(text) {
+  return text.replace(/[\\%_]/g, (char) => `\\${char}`).replace(/'/g, "''");
+}
+var COLUMN_REFERENCE = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)?$/;
+function systemTablePredicate(column = "name") {
+  if (!COLUMN_REFERENCE.test(column))
+    throw new Error(`Not a column reference: ${column}`);
+  return [
+    ...SYSTEM_TABLE_PREFIXES.map(
+      (prefix) => `${column} NOT LIKE '${likeLiteral(prefix)}%' ESCAPE '\\'`
+    ),
+    ...SYSTEM_TABLE_NAMES.map(
+      (name) => `${column} NOT LIKE '${likeLiteral(name)}' ESCAPE '\\'`
+    ),
+    `${column} NOT IN (SELECT name FROM pragma_table_list WHERE schema = 'main' AND type = 'shadow')`
+  ].join(" AND ");
+}
+var SYSTEM_TABLE_SQL_PREDICATE = systemTablePredicate("name");
+
 // ../../packages/data-core/src/storage-path.ts
 var STORAGE_RESERVED_WORDS = [
   "authenticated",
@@ -17118,39 +17261,6 @@ var STORAGE_BUCKET_DELETING_COLUMN = {
   definition: "TEXT"
 };
 
-// ../../packages/data-core/src/system-tables.ts
-var SYSTEM_TABLE_PREFIXES = [
-  "_naro_",
-  "_cf_",
-  "sqlite_"
-];
-var SYSTEM_TABLE_NAMES = ["d1_migrations"];
-function asciiLower(text) {
-  return text.replace(/[A-Z]+/g, (run) => run.toLowerCase());
-}
-function isSystemTable(name) {
-  const lower = asciiLower(name);
-  return SYSTEM_TABLE_PREFIXES.some((prefix) => lower.startsWith(prefix)) || SYSTEM_TABLE_NAMES.includes(lower);
-}
-function likeLiteral(text) {
-  return text.replace(/[\\%_]/g, (char) => `\\${char}`).replace(/'/g, "''");
-}
-var COLUMN_REFERENCE = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)?$/;
-function systemTablePredicate(column = "name") {
-  if (!COLUMN_REFERENCE.test(column))
-    throw new Error(`Not a column reference: ${column}`);
-  return [
-    ...SYSTEM_TABLE_PREFIXES.map(
-      (prefix) => `${column} NOT LIKE '${likeLiteral(prefix)}%' ESCAPE '\\'`
-    ),
-    ...SYSTEM_TABLE_NAMES.map(
-      (name) => `${column} NOT LIKE '${likeLiteral(name)}' ESCAPE '\\'`
-    ),
-    `${column} NOT IN (SELECT name FROM pragma_table_list WHERE schema = 'main' AND type = 'shadow')`
-  ].join(" AND ");
-}
-var SYSTEM_TABLE_SQL_PREDICATE = systemTablePredicate("name");
-
 // ../../packages/data-core/src/errors.ts
 var STORAGE_MIGRATION_PENDING = new RegExp(
   `^no such column: (?:b\\.|${STORAGE_BUCKET_DELETING_COLUMN.table}\\.)?${STORAGE_BUCKET_DELETING_COLUMN.column}\\b`
@@ -19396,8 +19506,34 @@ var MAX_STATEMENT_BYTES = 1e5;
 // ../../packages/data-core/src/policy-index.ts
 var INDEX_SQL = `SELECT t.name AS table_name, il.name AS index_name, il."partial" AS partial, ix.name AS column_name, ix.coll AS collation FROM pragma_table_list AS t JOIN pragma_index_list(t.name, t.schema) AS il JOIN pragma_index_xinfo(il.name, t.schema) AS ix WHERE t.schema = 'main' AND t.type = 'table' AND ${systemTablePredicate("t.name")} AND ix.seqno = 0`;
 
+// ../../packages/data-core/src/realtime-filter.ts
+var FILTER_REASONS = {
+  bytes: "must be a string of up to 1024 bytes in UTF-8",
+  control: "must have no control character",
+  syntax: "supports eq, neq, lt, lte, gt, gte and in, one condition",
+  list: "needs in.(a,b) with 1 to 100 values"
+};
+
 // ../../packages/data-core/src/realtime-protocol.ts
 var REALTIME_PROTOCOL_VERSION = "1.0.0";
+var MAX_CHANGE_CHANNELS_PER_TABLE = 4;
+var JOIN_CONFIG_REASONS = {
+  object: "must be an object",
+  unsupported: "is not supported",
+  boolean: "must be true or false",
+  presenceKey: "must be 1 to 128 characters",
+  changes: "must be an array of up to 16 subscriptions",
+  changeEvent: "must be *, INSERT, UPDATE or DELETE",
+  schema: "must be public",
+  table: "must be a table name of 1 to 128 characters, or *",
+  filter: FILTER_REASONS.bytes,
+  filterControl: FILTER_REASONS.control,
+  filterSyntax: FILTER_REASONS.syntax,
+  filterList: FILTER_REASONS.list,
+  filterTable: "needs a table: a filter cannot go with *",
+  /** The hub's, after `config.postgres_changes[<i>].table` (3-2c-1): `MAX_CHANGE_CHANNELS_PER_TABLE` against the connection's joins. */
+  changeChannels: `would put more than ${String(MAX_CHANGE_CHANNELS_PER_TABLE)} channels of this connection on one table's changes (* counts for every table): add the subscription to a channel it already has`
+};
 var REALTIME_CLOSE = {
   UNSUPPORTED_PROTOCOL: {
     code: 4e3,
@@ -19486,6 +19622,12 @@ var LIVE_BUCKET = `${STORAGE_BUCKET_DELETING_COLUMN.column} IS NULL`;
 var STORAGE_PROBE_NONCE = "f".repeat(STORAGE_NONCE_MAX_DIGITS);
 var REALTIME_PROBE_NONCE = "f".repeat(64);
 
+// ../../packages/data-core/src/realtime-publication.ts
+var REALTIME_TABLES = "_naro_realtime_tables";
+var REALTIME_TABLES_SQL = `CREATE TABLE IF NOT EXISTS ${REALTIME_TABLES} (table_name TEXT NOT NULL PRIMARY KEY COLLATE NOCASE, created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')))`;
+var MAX_PUBLISHED_TABLES = 100;
+var PUBLISHED_TABLES_SQL = `SELECT table_name FROM ${REALTIME_TABLES} ORDER BY rowid LIMIT ${String(MAX_PUBLISHED_TABLES)}`;
+
 // ../../packages/data-core/src/system-sql.ts
 async function convertLegacyPolicies(db, found) {
   const rows = rowsOf(await db.prepare(POLICY_SQL.list).all());
@@ -19519,6 +19661,7 @@ var MIGRATIONS_TABLE = "CREATE TABLE IF NOT EXISTS _naro_migrations (version INT
 var STORAGE_SUBQUERIES_VERSION = 7;
 var STORAGE_SUBQUERIES_NAME = "storage_subquery_policies";
 var STORAGE_SUBQUERIES_SQL = `SELECT version FROM _naro_migrations WHERE version = ${String(STORAGE_SUBQUERIES_VERSION)} AND name = '${STORAGE_SUBQUERIES_NAME}'`;
+var REALTIME_TABLES_VERSION = 8;
 var SYSTEM_MIGRATIONS = [
   {
     version: 1,
@@ -19607,6 +19750,14 @@ var SYSTEM_MIGRATIONS = [
     version: STORAGE_SUBQUERIES_VERSION,
     name: STORAGE_SUBQUERIES_NAME,
     statements: []
+  },
+  {
+    // Realtime 3-2b (original spec §9.1, design §7.1): the tables whose
+    // Data API writes reach the hub. Empty until the publish API (3-2c)
+    // writes it. A worker from before it never reads it.
+    version: REALTIME_TABLES_VERSION,
+    name: "realtime",
+    statements: [REALTIME_TABLES_SQL]
   }
 ];
 
@@ -19648,6 +19799,10 @@ var ENTERPRISE_REALTIME_LIMITS = Object.freeze({
   restRequestsPerSecond: 100
 });
 
+// ../../packages/data-core/src/realtime-changes.ts
+var CHANGE_TYPES = Object.freeze({ insert: "INSERT", update: "UPDATE", delete: "DELETE" });
+var CHANGE_EVENT_CODES = Object.freeze({ "*": 0, INSERT: 1, UPDATE: 2, DELETE: 3 });
+
 // ../../packages/data-core/src/storage-multipart.ts
 var MiB = 1024 * 1024;
 var MULTIPART_PART_SIZES = [16 * MiB, 32 * MiB, 64 * MiB];
@@ -23010,7 +23165,7 @@ async function openClaims(client, projectId) {
 }
 
 // src/server.ts
-var SERVER_VERSION = "0.19.0";
+var SERVER_VERSION = "0.20.0";
 function visibleTools(options2) {
   const { features, readOnly } = options2;
   return TOOLS.flatMap((tool) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naro-mcp",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "type": "module",
   "bin": {
     "naro-mcp": "./dist/index.js"
@@ -18,7 +18,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@supabase/supabase-js": "2.112.3",
-    "naro-cli": "0.20.0"
+    "naro-cli": "0.21.0"
   },
   "devDependencies": {
     "tsup": "8.5.0",