@oar-sh/oar 0.9.9 → 0.9.11

package/server/migrations/0011-relay-event-subscriptions.mjs

@@ -0,0 +1,125 @@
+'use strict';
+
+/**
+ * Migration: relay event subscriptions.
+ *
+ * 1. `relay_event_subscriptions` — what a conversation (the watcher) asked
+ *    the relay to tell it about: which sessions (listed ids or all), which
+ *    events, one-shot or not. A row stays after it ended (`ended_at`), so
+ *    list_subscriptions can say why one is gone. `heartbeat_minutes` (NULL =
+ *    off) and `last_heartbeat_at` drive the heartbeat while work runs.
+ * 2. `relay_events` — events recorded for a watcher and not yet written into
+ *    its conversation (`delivered_at` NULL), then the ones that were, for a
+ *    couple of hours. The relay rebuilds its flush timers from the
+ *    undelivered rows at boot.
+ *
+ * `relay_id` names the relay a watched session lives on: 'self' today, a
+ * paired relay's registry id once events cross relays.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0011-relay-event-subscriptions.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+export function migrateRelayEventSubscriptions(db) {
+  let tablesAdded = 0;
+  if (!tableExists(db, 'relay_event_subscriptions')) {
+    db.exec(`
+      CREATE TABLE relay_event_subscriptions (
+        id                      TEXT PRIMARY KEY,
+        watcher_conversation_id TEXT NOT NULL,
+        relay_id                TEXT NOT NULL DEFAULT 'self',
+        scope                   TEXT NOT NULL,
+        session_ids_json        TEXT,
+        events_json             TEXT NOT NULL,
+        once                    INTEGER NOT NULL DEFAULT 0,
+        match                   TEXT,
+        stalled_minutes         INTEGER NOT NULL DEFAULT 15,
+        heartbeat_minutes       INTEGER,
+        last_heartbeat_at       TEXT,
+        created_at              TEXT NOT NULL,
+        ended_at                TEXT,
+        end_reason              TEXT,
+        fired_count             INTEGER NOT NULL DEFAULT 0,
+        last_event_at           TEXT
+      )
+    `);
+    tablesAdded += 1;
+  }
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_relay_event_subscriptions_watcher
+    ON relay_event_subscriptions(watcher_conversation_id)
+    WHERE ended_at IS NULL
+  `);
+  if (!tableExists(db, 'relay_events')) {
+    db.exec(`
+      CREATE TABLE relay_events (
+        id                      INTEGER PRIMARY KEY AUTOINCREMENT,
+        subscription_id         TEXT NOT NULL,
+        watcher_conversation_id TEXT NOT NULL,
+        relay_id                TEXT NOT NULL DEFAULT 'self',
+        session_id              TEXT NOT NULL,
+        type                    TEXT NOT NULL,
+        urgent                  INTEGER NOT NULL DEFAULT 0,
+        payload_json            TEXT NOT NULL,
+        created_at              TEXT NOT NULL,
+        delivered_at            TEXT,
+        message_id              TEXT
+      )
+    `);
+    tablesAdded += 1;
+  }
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_relay_events_undelivered
+    ON relay_events(watcher_conversation_id, created_at)
+    WHERE delivered_at IS NULL
+  `);
+  // Delivered events are pruned by age (relay-event-service pruneDelivered).
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_relay_events_delivered
+    ON relay_events(delivered_at)
+    WHERE delivered_at IS NOT NULL
+  `);
+  return { applied: tablesAdded > 0, tablesAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateRelayEventSubscriptions(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0011 on ${dbPath}`);
+    console.log(result.applied
+      ? `  relay event subscriptions: tables added ${result.tablesAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0011 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0012-cross-relay-event-subscriptions.mjs

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * Migration: relay event subscriptions across paired relays.
+ *
+ * The watching relay (it holds the watcher) and the watched relay (it holds
+ * the sessions) both keep a row in `relay_event_subscriptions`:
+ *
+ * - On the watching relay `relay_id` is the paired relay's registry id,
+ *   `remote_subscription_id` that relay's id for the subscription,
+ *   `remote_meta_json` the watched sessions' titles, and `remote_sync` says
+ *   that an end still has to reach the other relay ('unsubscribe').
+ * - On the watched relay `subscriber_relay_id` is the watching relay's own
+ *   id (as it states it), `subscriber_watcher_id` / `_title` name its
+ *   watcher, `last_pull_at` is its last fetch and `dropped_count` the events
+ *   not kept for it since then.
+ *
+ * `relay_event_links` (watching relay): per paired relay the cursor of the
+ * events fetched there and the link's health, so a gap is noticed across
+ * restarts.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0012-cross-relay-event-subscriptions.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+const SUBSCRIPTION_COLUMNS = Object.freeze([
+  ['remote_subscription_id', 'TEXT'],
+  ['remote_meta_json', 'TEXT'],
+  ['remote_sync', 'TEXT'],
+  ['subscriber_relay_id', 'TEXT'],
+  ['subscriber_relay_name', 'TEXT'],
+  ['subscriber_watcher_id', 'TEXT'],
+  ['subscriber_watcher_title', 'TEXT'],
+  ['last_pull_at', 'TEXT'],
+  ['dropped_count', 'INTEGER NOT NULL DEFAULT 0'],
+]);
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+export function migrateCrossRelayEventSubscriptions(db) {
+  if (!tableExists(db, 'relay_event_subscriptions')) {
+    throw new Error('relay_event_subscriptions is missing (migration 0011 has not run)');
+  }
+  const present = new Set(db.prepare(`PRAGMA table_info(relay_event_subscriptions)`).all().map((column) => column.name));
+  let columnsAdded = 0;
+  for (const [name, type] of SUBSCRIPTION_COLUMNS) {
+    if (present.has(name)) continue;
+    db.exec(`ALTER TABLE relay_event_subscriptions ADD COLUMN ${name} ${type}`);
+    columnsAdded += 1;
+  }
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_relay_event_subscriptions_remote
+    ON relay_event_subscriptions(relay_id, remote_subscription_id)
+    WHERE remote_subscription_id IS NOT NULL
+  `);
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_relay_event_subscriptions_subscriber
+    ON relay_event_subscriptions(subscriber_relay_id)
+    WHERE subscriber_relay_id IS NOT NULL
+  `);
+  let tablesAdded = 0;
+  if (!tableExists(db, 'relay_event_links')) {
+    db.exec(`
+      CREATE TABLE relay_event_links (
+        relay_id      TEXT PRIMARY KEY,
+        cursor        INTEGER NOT NULL DEFAULT 0,
+        last_ok_at    TEXT,
+        first_fail_at TEXT,
+        lost_at       TEXT,
+        last_error    TEXT
+      )
+    `);
+    tablesAdded += 1;
+  }
+  return { applied: columnsAdded > 0 || tablesAdded > 0, columnsAdded, tablesAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateCrossRelayEventSubscriptions(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0012 on ${dbPath}`);
+    console.log(result.applied
+      ? `  cross-relay event subscriptions: columns added ${result.columnsAdded}, tables added ${result.tablesAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0012 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0013-previews.mjs

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * Migration: persisted previews.
+ *
+ * `previews` holds every published preview (a public link to a dev-server port
+ * or to a folder the relay serves), so a restarted runtime can restore them and
+ * a link handed out before the restart keeps working. One row per token:
+ *
+ * - `mode` is 'port' or 'static'. A port row has `target_host` and
+ *   `target_port`, a static row `root_dir` (the folder's realpath).
+ * - `conversation_id` is NULL for a preview registered without one.
+ * - `created_at` and `last_hit_at` are epoch milliseconds.
+ * - `host_boot_id` names the host boot the preview was registered in. A port
+ *   preview is restored only in the same boot (a dev server does not survive a
+ *   reboot, and the port may later belong to something else).
+ *
+ * No foreign key on `conversation_id`: deleting a conversation closes its
+ * previews through the registry, and a restore drops rows whose conversation
+ * is gone.
+ *
+ * Additive and idempotent. Safe to run on every boot, and from the command line
+ * against a database a running relay has open (one CREATE TABLE in WAL mode).
+ * An older build never reads the table.
+ *
+ * A `previews` table this migration did not create (other columns) is left
+ * alone and reported as not compatible; the relay then keeps previews in
+ * memory only, it never refuses to start over it.
+ *
+ * Usage: node server/migrations/0013-previews.mjs [path/to/copilot.db]
+ * The file must exist: a wrong path is refused rather than creating an empty
+ * database.
+ */
+
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+export const PREVIEWS_COLUMNS = Object.freeze([
+  'token', 'mode', 'conversation_id', 'label', 'target_host', 'target_port', 'root_dir',
+  'created_at', 'last_hit_at', 'host_boot_id',
+]);
+
+/**
+ * Why the `previews` table cannot be used, or '' when it can: every column
+ * this build reads and writes is there, and any other column takes a NULL or
+ * has a default (an insert would fail otherwise). '' too when the table is
+ * missing; the caller checks that separately.
+ */
+export function previewsTableProblem(db) {
+  const info = db.prepare(`PRAGMA table_info(previews)`).all();
+  if (info.length === 0) return '';
+  const names = new Set(info.map((column) => column.name));
+  const missing = PREVIEWS_COLUMNS.filter((name) => !names.has(name));
+  if (missing.length) return `the previews table lacks column(s) ${missing.join(', ')}`;
+  const blocking = info.filter((column) => !PREVIEWS_COLUMNS.includes(column.name)
+    && column.notnull && column.dflt_value === null && !column.pk);
+  if (blocking.length) {
+    return `the previews table has required column(s) this build does not write: ${blocking.map((column) => column.name).join(', ')}`;
+  }
+  return '';
+}
+
+export function migratePreviews(db) {
+  let tablesAdded = 0;
+  if (!tableExists(db, 'previews')) {
+    db.exec(`
+      CREATE TABLE previews (
+        token           TEXT PRIMARY KEY,
+        mode            TEXT NOT NULL,
+        conversation_id TEXT,
+        label           TEXT NOT NULL,
+        target_host     TEXT,
+        target_port     INTEGER,
+        root_dir        TEXT,
+        created_at      INTEGER NOT NULL,
+        last_hit_at     INTEGER,
+        host_boot_id    TEXT
+      )
+    `);
+    tablesAdded += 1;
+  }
+  const problem = previewsTableProblem(db);
+  if (problem) return { applied: false, tablesAdded, compatible: false, problem };
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_previews_conversation ON previews(conversation_id)`);
+  return { applied: tablesAdded > 0, tablesAdded, compatible: true };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  if (!fs.existsSync(dbPath)) throw new Error(`no database at ${dbPath}`);
+  const db = new Database(dbPath, { fileMustExist: true, ...options });
+  try {
+    return migratePreviews(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0013 on ${dbPath}`);
+    if (!result.compatible) {
+      console.error(`  not compatible: ${result.problem}; the relay will keep previews in memory only`);
+      process.exit(1);
+    }
+    console.log(result.applied
+      ? `  previews: tables added ${result.tablesAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0013 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0014-conversation-groups.mjs

@@ -0,0 +1,89 @@
+'use strict';
+
+/**
+ * Migration: session groups in the sidebar.
+ *
+ * A group is the set of conversations that share a `group_id`. The table
+ * `conversation_groups` holds what the set itself needs: a name given by hand
+ * (NULL means "shown under the head's title") and the head, the session that
+ * created the others with the remote_relay tool (NULL for a group made by
+ * hand, or once the head is deleted). A conversation an agent creates on this
+ * relay joins its creator's group at bootstrap; everything else is done by
+ * hand in the sidebar. Nothing is backfilled.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0014-conversation-groups.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+export function migrateConversationGroups(db) {
+  if (!tableExists(db, 'conversations')) {
+    throw new Error('conversations is missing (the base schema has not run)');
+  }
+  let tablesAdded = 0;
+  if (!tableExists(db, 'conversation_groups')) {
+    db.exec(`
+      CREATE TABLE conversation_groups (
+        id                     TEXT PRIMARY KEY,
+        name                   TEXT,
+        parent_conversation_id TEXT,
+        created_at             TEXT NOT NULL,
+        updated_at             TEXT NOT NULL
+      )
+    `);
+    tablesAdded += 1;
+  }
+  const present = new Set(db.prepare(`PRAGMA table_info(conversations)`).all().map((column) => column.name));
+  let columnsAdded = 0;
+  if (!present.has('group_id')) {
+    db.exec(`ALTER TABLE conversations ADD COLUMN group_id TEXT`);
+    columnsAdded += 1;
+  }
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_conversations_group
+    ON conversations(group_id)
+    WHERE group_id IS NOT NULL
+  `);
+  return { applied: columnsAdded > 0 || tablesAdded > 0, columnsAdded, tablesAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateConversationGroups(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0014 on ${dbPath}`);
+    console.log(result.applied
+      ? `  conversation groups: columns added ${result.columnsAdded}, tables added ${result.tablesAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0014 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0015-conversation-group-position.mjs

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * Migration: a hand order inside a session group.
+ *
+ * `group_position` is a member's place in its group once the owner has
+ * dragged a row there: the members with one come first, by position, the
+ * others after them, newest first. The head keeps NULL (it always leads),
+ * and so does every member of a group nobody reordered. A row that leaves
+ * its group loses its position.
+ *
+ * Additive and idempotent. Safe to run on every boot. Rolling back needs no
+ * data change: older code ignores the column; a row it moves out of a group
+ * keeps a stale place, which the next run here clears.
+ *
+ * Usage: node server/migrations/0015-conversation-group-position.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+export function migrateConversationGroupPosition(db) {
+  if (!tableExists(db, 'conversations')) {
+    throw new Error('conversations is missing (the base schema has not run)');
+  }
+  const present = new Set(db.prepare(`PRAGMA table_info(conversations)`).all().map((column) => column.name));
+  let columnsAdded = 0;
+  if (!present.has('group_position')) {
+    db.exec(`ALTER TABLE conversations ADD COLUMN group_position INTEGER`);
+    columnsAdded += 1;
+  }
+  // A place without a group: an older release (which ignores the column)
+  // moved the row out of its group after a roll back. Cleared on every run.
+  const placesCleared = present.has('group_id')
+    ? db.prepare(`UPDATE conversations SET group_position = NULL WHERE group_id IS NULL AND group_position IS NOT NULL`).run().changes
+    : 0;
+  return { applied: columnsAdded > 0 || placesCleared > 0, columnsAdded, placesCleared };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateConversationGroupPosition(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0015 on ${dbPath}`);
+    console.log(result.applied
+      ? `  group position: columns added ${result.columnsAdded}, stale places cleared ${result.placesCleared}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0015 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0016-share-access-log.mjs

@@ -0,0 +1,110 @@
+'use strict';
+
+/**
+ * Migration: share lineages and the share access log.
+ *
+ * A share link can be renewed: the conversation gets a new token and the old
+ * one stops at once. What the link has been through (its opens) belongs to the
+ * share, not to one token, so every row of `conversation_shares` gets a
+ * `lineage_id`: the token the share started with, carried over to every
+ * renewed token. Existing rows start their own lineage (`lineage_id = token`).
+ *
+ * `conversation_share_opens` holds one row per open of a shared page:
+ *
+ * - `lineage_id` names the share; the log survives a renew.
+ * - `opened_at` is an ISO timestamp.
+ * - `ip` is NULL when the relay does not store viewer addresses (a setting).
+ * - `country` is the edge's two-letter country, NULL when unknown.
+ * - `viewer_key` is a keyed hash of address and browser, so distinct viewers
+ *   can be counted when the address itself is not stored.
+ *
+ * Stopping a share deletes its log; deleting the conversation does too (the
+ * foreign key, and the delete route by hand). Nothing else prunes it.
+ *
+ * Additive and idempotent. Safe to run on every boot. An older build never
+ * reads the new table, and a share it creates has no lineage, which this build
+ * reads as the share's own token.
+ *
+ * Usage: node server/migrations/0016-share-access-log.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+export function migrateShareAccessLog(db) {
+  if (!tableExists(db, 'conversation_shares')) {
+    throw new Error('conversation_shares is missing (the base schema has not run)');
+  }
+  let columnsAdded = 0;
+  let tablesAdded = 0;
+  const present = new Set(db.prepare(`PRAGMA table_info(conversation_shares)`).all().map((column) => column.name));
+  if (!present.has('lineage_id')) {
+    db.exec(`ALTER TABLE conversation_shares ADD COLUMN lineage_id TEXT`);
+    columnsAdded += 1;
+  }
+  // Every run: a share an older build created after this migration has none.
+  const lineagesSet = db.prepare(`UPDATE conversation_shares SET lineage_id = token WHERE lineage_id IS NULL OR lineage_id = ''`).run().changes;
+  if (!tableExists(db, 'conversation_share_opens')) {
+    db.exec(`
+      CREATE TABLE conversation_share_opens (
+        id              INTEGER PRIMARY KEY AUTOINCREMENT,
+        lineage_id      TEXT NOT NULL,
+        conversation_id TEXT NOT NULL,
+        opened_at       TEXT NOT NULL,
+        ip              TEXT,
+        user_agent      TEXT,
+        country         TEXT,
+        viewer_key      TEXT NOT NULL,
+        FOREIGN KEY (conversation_id) REFERENCES conversations(id) ON DELETE CASCADE
+      )
+    `);
+    tablesAdded += 1;
+  }
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_conversation_share_opens_lineage
+    ON conversation_share_opens(lineage_id, opened_at DESC)
+  `);
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_conversation_share_opens_conversation
+    ON conversation_share_opens(conversation_id)
+  `);
+  return { applied: columnsAdded > 0 || tablesAdded > 0 || lineagesSet > 0, columnsAdded, tablesAdded, lineagesSet };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateShareAccessLog(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0016 on ${dbPath}`);
+    console.log(result.applied
+      ? `  share access log: columns added ${result.columnsAdded}, tables added ${result.tablesAdded}, lineages set ${result.lineagesSet}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0016 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}